vaultspec-curate git:20260924.2797685A

Immutable. This exact content never changes and is served at /api/v1/blob/7309ead1d4940b89.

---
name: vaultspec-curate
description: 'Reconcile the ADR architecture corpus against the codebase and the feature lifecycle documents against the single-home-fact boundary. Use to audit ADR status and supersession, find ADR-vs-ADR, ADR-vs-code, and document-vs-document conflicts (restated grounding, displaced decisions, forked facts), and action them. Mechanical .vault/ hygiene is the CLI''s job; this skill does the semantic reconciliation the CLI cannot.'
---

# 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. 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.
- **Check the code index.** Decision recall goes through the `vaultspec-discovery`
  rule's search and ADR listing. Code recall needs the `vaultspec-rag` index, and a
  fresh worktree is often unindexed. Confirm with `vaultspec-rag server doctor`; if the
  code index is empty, run `vaultspec-rag index --type code`. When `vaultspec-rag` is
  unavailable, use the rule's fallback.

## 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.** Start from one bounded cross-reference sweep:
  `vaultspec-core vault adr crossref --all` (MCP: `crossref`), `--feature`, or
  `--isolated`; a resumed sweep repeats its selector and adds the reported
  `--after <next_after>`. One sweep judges at most 50 ADRs within fixed request and time
  ceilings, at up to 46 paid requests each. Run one sweep per curation run; report its
  `next_after`, `remaining`, and `stopped`, and start another only on the orchestrator's
  go-ahead. On `not_configured`, run the next step the reply names. On `stopped`, report
  the reason; a sweep stopped on time or a transient failure is resumed later, and one
  stopped on a refusal (`content_rejected` or `request_too_large`) means no read settled
  it: cross-reference one other ADR on its own, and if that is judged, cross-reference
  the first refused ADR on its own. If it is refused again, its refusal is its own:
  record it and resume with `--after` set to it. Otherwise resume as usual. Every
  refused source at or before `next_after` was refused on its own text, whether or not
  the sweep stopped: record it. Read the ADRs behind each `link` verdict and each `weak`
  declared link, and judge them. Then surface the ADRs covering the same concept with
  the `vaultspec-discovery` rule's decision search and ADR listing, 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, locate the implementation per
  the `vaultspec-discovery` rule, 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.
- **Act directly (confirmed cross-reference).** Adding a `crossref` `link` verdict the
  source does not declare, once reading both ADRs confirms it, with
  `vaultspec-core vault link add`. A `weak` declared link is never removed on the
  verdict alone; it is recorded with a recommendation.
- **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.