SciDEX Schema-Hygiene Resolver

Use this skill when the substrate schema_registry_auditor worker emits a schema_hygiene gap_mission — a JSON schema in src/scidex_substrate/schema_registry/default_schemas/ doesn’t have a matching row in the schema_registry DB table, or vice versa, or the validators per SPEC-031 are missing.

You are the remediation half of the loop. The detector does the cheap part (walking the dir + querying the DB); you do the judgment (which fix is right for each finding) and file a reviewable proposal.

The detector worker is the iter-167 #2195 unblocked iter-168 #N target; sibling to the iter-11 #2096 spec_drift_auditor + iter-12 spec-drift-resolver pair.

Loop

1. Claim a mission. scidex.gap_mission.list_open filtered to kind=schema_hygiene, then scidex.gap_mission.claim one. The claim is race-safe; on lock_conflict, pick another.

2. Read the mission payload — it carries schema_name (e.g. agent_work_packet), category (one of missing_db_row, missing_file, missing_validator, field_mismatch), and evidence_paths (paths to the schema JSON + the DB row if any).

3. Inspect the file + DB row state. Use scidex.schema.get (if reading registry rows is exposed) or scidex.schema.list to verify the current state.

4. Categorise the fix:

   • missing_db_row: schema JSON exists but no DB row. Propose a migration to insert it (with version bumping).

   • missing_file: DB row exists but file deleted/renamed. Propose restoring the file from git history OR deprecating the DB row.

   • missing_validator: file + row exist but no validator per SPEC-031. Propose authoring the validator.

   • field_mismatch: file fields don’t match the DB row’s declared fields. Propose a reconciling migration.

5. File the proposal as a comment on the mission’s target_ref (or as an audit_finding for governance review if the fix is destructive). Use scidex.comments.create with kind=proposal.

6. Complete the mission with scidex.gap_mission.complete once the proposal is filed.

Quality bar

• One mission per claim; don’t batch — keep each fix reviewable.

• Always cite SPEC-031 §N when proposing validator authoring.

• Prefer ADDITIVE fixes (insert row, restore file) over DESTRUCTIVE (delete row). When proposing destruction, route via @senate-review.

• If unsure which fix applies, file a comment requesting clarification rather than guessing.

Anti-patterns

• Don’t apply fixes directly via scidex.schema.create / scidex.schema.update — file proposals; reviewers apply.

• Don’t claim multiple missions concurrently.

• Don’t propose validator code in the resolver — that’s SPEC-031 authoring work; propose a follow-up task instead.

Cross-references

Sister governance-loop skills: [[scidex-spec-drift-resolver]] (iter-12 sibling pair pattern) — same claim → read → categorise → propose → complete loop, different drift class. Foundation: [[artifact-editing]] (safe-mutate base via scidex-substrate skills), [[scidex-citation-auditor]] (for SPEC-031 cite hygiene). Detector (forthcoming): substrate scheduled_workers/schema_registry_auditor/ — unblocked by iter-167 #2195 SPEC-073 path correction.