layer-sync

A research project's knowledge lives in ordered layers — typically {{doc_layers}} = decision log → spec/docs → code → notebooks/reports. Any change that lands in one layer and not the others is drift, and drift silently corrupts the paper the project is building toward. This skill audits a scoped slice of the layers, reports drift with file:line evidence, and proposes exactly one next action. It never fixes anything in the same turn.

When to use

• After a decision-log entry lands (did it reach spec, code, notebooks?).
• After a commit range that touched a documented behavior.
• As a phase-gate step (the phase-gate skill calls this before closing).
• When any two layers are suspected to disagree.

When NOT to use

• "Where are we / what's next" — that is a status question for the session-historian agent.
• Verifying a single computed result — that is the verifier agent's job.
• General code review, style review, or test-coverage review.
• Fixing the drift — fixes happen in a separate, user-approved turn.

Scoping the audit

Parse the user's scope; default to recent.

Runbook

1. Read the layers in authority order: {{decision_log}} (newest entries first), then git log --oneline -20 (+ --name-only for the scope window), then the spec docs and {{build_log_dir}} (last ~3 entries), then the implementation, then notebooks/reports. Read only what the scope needs — for notebooks prefer targeted greps over full parses.
2. For each in-scope decision or change, build a layer-by-layer row: reflected / missing / contradicting, with a file:line citation for every non-✅ cell.

3. Emit the report:

   ## Drift audit — <date>
   **Scope**: <…>   **Layers**: <{{doc_layers}}>
   **Verdict**: ✅ in sync | ⚠ drift detected | ❌ contradictions
   
   | Decision / change | <layer 1> | <layer 2> | <layer 3> | <layer 4> | Status |
   | ... | ✅ | ✅ | ⚠ old term at src/x.py:42 | ✅ | ⚠ |
   
   ### Drift details (⚠/❌ only)
   - What the authority layer says (cite), what the drifted layer says (cite),
     one concrete suggested fix.

4. Append exactly one next action:
   • ✅ → "no drift — proceed with <next planned item>".
   • ⚠ → the single highest-value fix, phrased as a proposal awaiting approval.
   • ❌ → stop; ask the user which layer is canonical before proposing anything.

Anchor links (point-precise mode)

For pairs that must never drift (a doc section describing a specific function, a constant table mirroring a config file), register an explicit link in a small manifest, docs/drift_links.yml:

links:
  - id: 1
    doc: docs/<doc>.md        # optionally with a doc_anchor section
    src: src/<file>           # optionally with a #symbol
    note: "what this pair pins"
    created: YYYY-MM-DD

Adding a link: verify the doc path exists, the source path exists, and the symbol (if given) is actually declared in the source (grep for its definition; no match → refuse, show the grep). Reject duplicates of the same (doc, src, symbol) triple. Removing: by id. The manifest is the only file this mode ever writes. Audits with scope links compare each pair's content substance directly — the manifest says where to look, never what is correct.

Rules

1. The decision log is the source of truth. If code and the decision log disagree, the code is the drift — unless the entry is itself marked superseded.
2. Cite file:line for every drift claim. "The notebook still has the old form" is not a finding; the cell/line reference is.
3. Read-only audit. No test runs, no builds, no notebook execution, no edits.
4. Skip layers that are out of scope for a given decision. A code-only decision with no notebook impact must not be flagged for "missing notebook reference".
5. Group related drifts into one row with the missing piece — not N rows for N sub-edits.
6. Recency bias. Decisions older than ~30 days (or several numbers back) are assumed propagated unless the caller explicitly widens the scope.
7. Historical narrative is not drift. A prose cell explaining the old form next to code using the new form is documentation; flag only executable code that uses a retired form.
8. Beware short-token renames. Grep with word boundaries (\bold_name\b) — short identifiers collide.
9. One action, not a menu. Three drifts found → propose the first fix; the rest surface on the next audit.
10. Never soften the verdict letter. ⚠ and ❌ are load-bearing for the next-action branching; do not downgrade them to "minor inconsistency" prose.

Dispatching to the auditor agent

The pack ships a read-only drift-auditor agent implementing exactly this protocol. When subagents are available, this skill is a thin coordinator: parse the scope, dispatch the agent, present its report verbatim (do not re-summarize its table), append the single action line. Do not pre-read layer files before dispatching — that duplicates the agent's work. Do not run the audit inside another agent; it is a top-level, user-facing flow.

Configuration

• {{doc_layers}} — ordered layer list (default: decisions, spec, code, notebooks).
• {{decision_log}} — the authority layer file.
• {{build_log_dir}} — build-log directory (part of the docs layer).

Provenance & maintenance

Generalized from a working four-layer sync discipline (coordinator skill + read-only audit agent + anchor-link manifest) in a mature computational-research repository; see the pack's examples/ directory for the worked exemplar mapping. The scope table, verdict semantics, and rules 1–10 are verified practice; the YAML manifest schema is copied verbatim from the exemplar (field names are the convention, not a requirement).

Re-verify in your project:

• test -f {{decision_log}} && head -40 {{decision_log}} — the authority layer exists and is newest-first.
• git log --oneline -10 -- <spec doc> — the spec layer actually changes over time (a never-touched spec is itself a drift signal).
• test -f docs/drift_links.yml && cat docs/drift_links.yml — anchor manifest present (only if you use the links mode).