Vaultspec Curate

ADR architecture reconciliation skill (vaultspec-curate)

This skill terminates within one run. It keeps the architecture decision record (ADR) corpus and the code it governs a single, curated, internally-consistent set of decisions. It reconciles each decision's declared status and supersession against reality, finds where decisions contradict each other or the codebase, and actions the result: propagating status, amending wording, and surfacing gaps, conflicts, and errors that need human judgment.

It also enforces the document boundary - each fact has one home: research grounds, the ADR decides, audits find - across a feature's lifecycle documents: an ADR restating its grounding's evidence, a research or audit body recording a decision, and the same fact forked across documents are curation findings with defined actions.

Mechanical .vault/ hygiene belongs to the vaultspec-core CLI (the vaultspec-cli rule). This skill judges what no check can decide: whether an accepted decision is implemented, whether two ADRs disagree, and whether a superseded decision still governs the code.

Preconditions (cede the mechanical layer first)

Reconciliation reasons over a structurally-correct corpus and a populated semantic index. Before any semantic work:

• Structural hygiene to the CLI. Run vaultspec-core vault check all --fix. This repairs frontmatter, links, names, stamps, and template drift. Never hand-fix these.
• Ensure the semantic index is live. vaultspec-rag powers decision and code recall, but a freshly checked-out worktree is often unindexed. Confirm with vaultspec-rag server doctor; if the vault or code index is empty, populate it with vaultspec-rag index --type vault and vaultspec-rag index --type code before relying on search. Where vaultspec-rag is unavailable, the vaultspec-core discovery verbs and grep carry the same sequence.

Workflow

Dispatch the vaultspec-docs-curator agent persona to run the reconciliation. Instruct it to: "Reconcile the ADR architecture corpus against the codebase. Establish the decision inventory and declared status, reconcile decisions against each other, against the code, and each feature's lifecycle documents against the single-home-fact boundary; action the safe findings, and surface the rest in an audit report."

The persona operates a Ground -> Reconcile -> Act -> Verify loop, the vaultspec-discovery rule applied to decisions:

• Ground. Build the decision inventory: vaultspec-core vault list adr --json for the set, the body H1 (and any legacy status section) for each declared status, and vaultspec-core vault graph --json for the supersession and relatedness edges.
• Reconcile decision-vs-decision. Use vaultspec-rag search "<intent>" --type vault --doc-type adr to surface ADRs covering the same concept, read them whole, and judge agreement, duplication, contradiction, or fragmentation (a refinement chain or sibling accepted records on one scope).
• Reconcile decision-vs-code. For each live decision, vaultspec-rag search "<concept and domain nouns>" --type code, read the epicenter file whole, and confirm the decision is implemented; grep to confirm exact symbols.
• Reconcile document-vs-document. For each feature with an ADR, read its lifecycle documents against the boundary: restated grounding in the ADR, displaced decisions in research or audit bodies, forked facts across documents.
• Act and Verify. Apply the safe actions, surface the rest, re-run vaultspec-core vault check all, and re-scan until clean.

The full query patterns, the conflict taxonomy, and the per-class actions live in references/reconciliation-playbook.md. Read it before reconciling.

Canonical status taxonomy

The curator enforces one canonical ADR status set and one supersession convention. The authoritative definition - the values, their meaning, the canonical encoding, and the divergences the curator must detect - is in references/adr-status-taxonomy.md. Read it before judging any status. This set is the one definition the core library, the ADR template, and the supersede tool all derive from; where the corpus or tooling diverges, the curator reconciles toward it.

Actions and autonomy boundaries

The curator acts on what is mechanically safe and proposes what needs judgment.

• Act directly (mechanically safe). Status-encoding and stamp normalization, including propagation of an already-recorded, unambiguous supersession through an owning body edit, per the reconciliation playbook. A new supersession uses vaultspec-core vault adr supersede OLD --by NEW only after authorization and successor acceptance. Use the CLI mutators (vaultspec-core vault adr supersede, vaultspec-core vault set-body, vaultspec-core vault edit, vaultspec-core vault link add) over raw file edits so the frontmatter contract and the modified stamp stay canonical.
• Act directly (content-preserving boundary conformance). Replacing an ADR's restated evidence with a stem citation, and stripping decision language from a research or audit body where an accepted ADR records the same decision, leaving a one-line pointer. Invariants: no fact is destroyed - text is removed only where its single home is confirmed, or created first by relocating the fact into its grounding document; and no conformance edit ever changes what was decided - decision changes belong to the vaultspec-adr amend-or-supersede path, on human approval. Where the two copies diverge in substance, it is a forked fact, not a restatement: surface it instead.
• Propose for approval (judgment). Rephrasing or amending conflicting ADR wording, and any contradiction whose resolution is not obvious, are written into the audit as recommendations, not applied unprompted.
• Never auto-retrofit ADRs to code. ADRs drive codebase rollout, not the reverse. The curator reports decision-vs-code drift as a finding but does not rewrite an ADR to match the code on its own. Amending an ADR to reflect existing code (the legitimate ADR-from-codebase retrofit for late-adopting projects) is offered and executed only on explicit human request.

Audit persistence

Persist findings as an audit report. Scaffold it with vaultspec-core vault add audit --feature <feature> --topic reconciliation so the CLI owns the filename and frontmatter and the report never collides with the feature's review audit, then author the body: the decision inventory, the conflicts found by class, the actions applied, and the recommendations requiring author judgment. The audit report is the one document the curator authors directly.

Artifact linking

• Link persisted documents through vaultspec-core vault link add, which writes the quoted '[[wiki-links]]' into related:; never hand-edit frontmatter or put links in a body.

Additional resources

• references/adr-status-taxonomy.md - the canonical status set, encodings, supersession convention, and the divergences to detect.
• references/reconciliation-playbook.md - the Ground/Reconcile/Act/Verify loop in detail: query patterns, the conflict taxonomy, and the action for each class.