dds

---
name: dds-sync
description: The daily loop — mechanically catch the repository's documentation up to its code. Witnesses the repo IN-SESSION per the carried procedures (delta-driven; the committed register state is the baseline), regenerates derived state, writes evidence-cited DRAFTS for instrument-witnessed claims (register claim files) and STUBS for judgment-only surface (ADRs, goals, premises), repairs structure under the firmness contract, then reports the residue only judgment can move — and OFFERS to propose treatments for it (never without asking; headless runs never improve). It never alters ratified content bytes and never commits.
---

# /dds-sync

Catch this repository's documentation up to its code — the **mechanical
half** of the discipline, on demand and on every meaningful change.
This skill is one of four modes, separated by what each compares and
what each may write:

| mode | compares | may write |
|---|---|---|
| `/dds-check` | claims ↔ witness · structure ↔ canon | nothing (verdicts) |
| **`/dds-sync`** | machine-owned state ↔ witness | the REGISTER world only |
| `/dds-suggest-adrs` | register evidence ↔ the ADR corpus | suggested `Proposed` ADRs |
| `/dds-suggest-risks` | witnessed stakes ↔ the risk spine | suggested risk stubs · merge reports |
| `/dds-upgrade` | installed framework ↔ shipped version | canon merge · migrations |
| `/dds-prep-merge` | branch history ↔ the decisions made | the ratifying commits |

The world is split in two. The **register world** — `docs/registers/`
(the claim files, incl. their `Held by` ledgers) and `docs/risks/` — is largely machine
generated: sync drafts and regenerates freely there, merge ratifies.
The **ADR world** — `docs/adr/` — is human design decisions: sync
NEVER writes there; machine output enters only through the explicitly
invoked `/dds-suggest-adrs`.

Sync's one-line contract: **everything machine-owned catches up;
everything ratified is untouchable.** A ratified claim that disagrees
with the code is *not* a sync target from either side — it is a
`/dds-check` finding whose resolution (fix the code? amend the claim?)
is a human decision. Sync can therefore never make check pass by
itself; that is a feature.

## The witnessing and proposing procedures

The survey is performed BY THIS SKILL, in-session — no external tool.
Two carried procedures govern it, and they are normative (every rule
in them was learned live; do not improvise past them):

- `assets/witnessing.md` — the mechanical reads (schema, processing,
  policies, surface, capabilities, secrets, flows, erasure), the fold
  rules, the mapping ledger, and the honesty rules;
- `assets/proposing.md` — the judgment passes (cells → columns →
  activities → bindings) with the full guard catalogue.

**Work the delta.** The committed register state (the claim files and
their ledgers) is the baseline; `git diff` against the tree it last
described names the files to witness. Full-repo passes are for first
adoption only. Where the repo's stack has no documented read rule,
derive one from the same principles, apply it, and record it in the
residue as a candidate upstream contribution.

## Drafts vs stubs (the load-bearing line, v0.6)

Two kinds of gap, two kinds of fill — the rule of
`assets/deriving-from-code.md` ("only what is derived may be filled")
now has an instrument on its derived side:

- **Witnessed surface → evidence-cited DRAFTS.** Where the
  witnessing procedure establishes the fact (a datum's holdings, an activity's
  operating evidence, a boundary crossing), sync writes a *draft* claim
  into the claim files — facets and all — marked unratified. A draft
  differs from a guess in three ways: it cites its witness verbatim, it
  is structurally marked as awaiting ratification, and merging the PR —
  never the generator — is what turns it into a claim.
- **Judgment-only surface → STUBS, exactly as before.** Premises,
  goals' sources, classifications with no witness, activity boundaries
  that could go two ways — everything in `principles.md` §5's
  reservation stays a marked hole (`TODO`, `needs-ratification`, `⚠`).
  **Lawful basis and necessity are never drafted**, whatever the
  instrument saw: `basis.TODO` is the honest state until a human with
  authority fills it.

## Procedure

### 1. Preconditions

- Refuse on the default branch.
- Refuse on a dirty working tree — **except** the framework's own
  uncommitted footprint (`apm.yml`, `apm.lock.yaml`, the `.gitignore`
  line, `apm_modules/`, and structure `/dds-upgrade` just installed:
  `docs/`, `.github/CODEOWNERS`, `.dds-version`,
  `AGENTS.md`, `CLAUDE.md`). Uncommitted *application* changes mean
  work in progress — refuse.
- If the canon is absent (`docs/principles.md` missing), stop and
  direct the user to `/dds-upgrade` (install = upgrade from nothing).
- Runs on a fresh scaffold (draft/stub everything) and repeatedly
  thereafter (delta: only what is newly uncovered or newly drifted).

### 2. Witness and propose (the procedures)

Witness the delta per `assets/witnessing.md`; run the proposing passes
per `assets/proposing.md`; reconcile against the claim files and the
pin. The output to work from is the reconciliation — drafts, claims
the witness no longer supports, surface no claim covers. Where the
mechanical reads do not reach (protection mechanisms, deeper
realization surfaces), survey per `assets/deriving-from-code.md`.

### 3. Write — the mechanical catch-up

- **Derived state** — regenerate anything marked generated; never
  hand-maintained values (`registers.md`'s split rule).
- **Claim files** (`docs/registers/` — formats in
  `assets/claim-files.md`): append the instrument's drafts (datums into
  their subject's file, activities into `processing-activities.md`),
  each section carrying its witness evidence. Never rewrite a ratified
  section's bytes — a drifted ratified claim is residue, not a target.
- **Risk-spine files** — cluster witnessed stakes into `docs/risks/`
  drafts (stake and currency evidence-cited; validation question,
  exclusions and clustering `needs-ratification`) — the risk spine is
  register-world: machine-drafted, merge-ratified.
- **Governance holes** — the `basis.*` / `retention.*` / processor
  entries the register implies, per the carried stub format.
- **Never ADR stubs.** Decision-shaped findings (an ungated store, a
  dormant mechanism, an unauthenticated surface) are named in the
  residue and routed to `/dds-suggest-adrs` — the ADR world is the
  human's; sync does not scaffold in it.
- **Structural repair** — apply the mechanical reshaping the canon
  requires (missing sections, dangling edges, provenance tags, trailer
  vocabulary — the list `/dds-check` verdicts against), under the
  firmness contract: **reshape structure freely; never alter a human's
  content bytes**; surface any fix that would require choosing or
  changing content.
- **Agent-context hygiene** — relocate vendored rules out of
  `AGENTS.md`/`CLAUDE.md` per `conventions.md` §9 (mechanical); stage
  `⚠`/`Proposed`-ADR judgments, never resolve them.

### 4. Report the residue

Summarize what sync **may not touch** — the judgment worklist, freshly
computed over the whole claim set (not just this delta):

- ratified claims the instrument could not witness (*implemented?*)
- open `basis.TODO` / `needs-ratification` / `⚠` holes
- drafts awaiting ratification (this run's and prior runs')
- ratified claims the witness has drifted under (stale mappings)
- coverage gaps with no strategy — flagged for `/dds-suggest-adrs`

### 5. Offer the improve continuation (ask — never assume)

Ask the user, with two scopes:

1. **Work the flagged residue** *(default)* — for each item, propose a
   treatment: a `Status: Proposed` ADR, a challenge note, a candidate
   basis with its reasoning, a draft amendment to a stale claim. All
   output is proposal-shaped; nothing is decided.
2. **Also adversarially review the ratified register content the
   instrument can't fault** — purposes that don't match the code's
   behavior in spirit, risk clusterings the evidence outgrew. Slower;
   offer it, don't default to it.

Decision-shaped residue is NOT worked here: name it and point at
`/dds-suggest-adrs` — proposing design decisions is its own explicitly
invoked act, never a residue treatment.

**Headless or unattended runs never improve** — the run ends at the
residue report. Saying yes does not widen what may be written:
improving produces *proposals only*, in artifacts separate from the
mechanical changes, so `/dds-prep-merge` can keep one mode per commit.

### 6. Hand off

Do **not** commit. Show `git status` / `git diff`, grouped into: the
mechanical catch-up (one future commit), each improvement proposal
(one future commit each), and the residue that needs a human.

## Fidelity (the load-bearing rule)

Structure is carried, never invented. Drafts cite the instrument's
witness, never plausibility. Judgments reserved to humans stay holes.
A draft with honest evidence and an honest hole is the goal; a filled
hole with no witness is the failure this discipline exists to prevent.

## Residual scaffolding (mechanical)

When `/dds-check`'s latest run carries findings with no disposition,
scaffold — never ratify — the ledger entries: for each undisposed
structural/cube/judged finding, DRAFT a `## Residuals` line in the
owning risk file (`res.<slug>` · open · one sentence · the witness
quote taken from the finding's artifact), marked for the human to keep,
re-state, or delete in the PR. The human's act is the disposition (open
vs accepted vs fix-instead); the machine's act is only the clerical
shape. Never scaffold an `accepted` state, and never touch existing
residual lines — re-witnessing a stale one is a human edit.

## Refusals (hard)

- Never alter a ratified claim's bytes, or any human content — drafts
  append, stubs scaffold, structure reshapes; substance never moves.
- Never draft a lawful basis, a necessity judgment, a goal's source, or
  a premise — holes, always.
- Never write a draft whose evidence you did not obtain from the
  instrument (or a code path you did not verify this session).
- Never run the improve continuation without the user's explicit yes
  this session; never in a headless run.
- Never mix modes in staged output — mechanical catch-up and proposals
  stay separable for `/dds-prep-merge`.
- Never write in `docs/adr/` — the ADR world is the human's; route
  decision-shaped findings to `/dds-suggest-adrs`.
- Never install or update the canon — that is `/dds-upgrade`.
- Never commit on the user's behalf.