Archie Sync

Archie Sync — keep the snapshot current

The blueprint and per-folder CLAUDE.md are living snapshots of the codebase. Capture the work just done and reconcile it back so those snapshots stay accurate. No git writes — record + edit files only; the user decides what to commit.

Prerequisites: Archie must already be installed (.archie/sync.py exists). If it doesn't, tell the user to run npx @bitraptors/archie "$PWD" and try again.

Phase 1 — record the change ledger

Step 1 — Get context: PROVIDE or BUILD

Produce statements about what the code now is (not a changelog of your edits):

• PROVIDE — you hold the reasoning: emit statements from what you know. Real confidence, reconstructed: false.
• BUILD — context cleared/compacted or fresh session: read git diff and derive statements from the change itself. Structural facts are fine; mark inferred intent confidence: "low", reconstructed: true. Don't invent beyond the diff.

Step 1b — Pull durable signals (plans + churn)

Two background signals were captured for you since the last sync; use them to make the record richer and to scope what to review:

python3 .archie/sync.py plan-list .      # captured ExitPlanMode plans (durable intent)
python3 .archie/sync.py churn-status .   # files/lines changed since last sync

• Read each plan in the returned plans[] paths (.archie/tmp/plans/plan_*.md). A plan states intent and decisions the diff can't show. Use it to:
  • seed advisory claims — a stated decision/pitfall/rule becomes a decision/pitfall/ rule claim (these always stage as proposed amendments — the "rule worth jotting down").
  • ground descriptive claims even if context was compacted — but treat plan intent as a candidate to verify against the actual code, not ground truth (a plan is intent-before, the code is fact-after). If the code diverged from the plan, record what shipped.
• Use the churn file list to scope which areas to review.

Step 2 — Record

Pipe a JSON array of statements. Descriptive kinds are the default — what the code now is. Advisory kinds (decision/pitfall/rule) only when a change genuinely establishes one; they are NOT the point.

{ "statement": "MainViewModel now filters background subscription-refresh errors so they no longer surface the purchase dialog",
  "kind": "behavior",
  "evidence_files": ["path/touched/by/this/change.ext"],
  "confidence": "low | medium | high", "reconstructed": false }

Descriptive kinds: behavior (what a component/flow now does) · structure (component/ layer/file role added·changed·removed) · dataflow (a changed interaction/event/dependency) · data (data-model/persistence) · tech (stack/dependency) · reference (a quick-ref fact). Advisory (optional): decision · pitfall · rule.

echo '<your JSON array>' | python3 .archie/sync.py record .

(Add --agent claude under Claude Code, or --agent codex under Codex, to tag the record's provenance.)

A statement is eligible to fold only if it is a DESCRIPTIVE kind (the mirror) AND confidence: medium|high, reconstructed: false, and grounded in a file inside the diff. ADVISORY kinds (decision/pitfall/rule/guideline) are ALWAYS staged — the contract (the law) changes only deliberately, never via a code-fold. Everything else is staged.

Step 2b — Fold override acknowledgments

Read .archie/overrides.json. For each entry with status: "acked" whose branch is the CURRENT branch and which has no staged claim yet, record the break through the normal Step 2 flow as a staged contract amendment: a rule claim titled override: <rule_id>, rationale = the entry's reason, evidence_files = the files the violating change touched.

The rule itself is already gone from rules.json and the blueprint invariant is already stamped overridden — override-ack did that when the user authorized it. There is no ratify step: merging the PR is the ratification. Never delete or edit an override entry by hand.

Phase 2 — reconcile eligible statements into the snapshot

If record reported eligible > 0, fold them. The fold is your job — you reconcile; the script resolves scope and re-renders.

Step 3 — Get the scoped targets

python3 .archie/sync.py fold-context .

Returns, per eligible statement, the descriptive blueprint_sections to reconcile, the edit_file, and the touched per-folder CLAUDE.md (intent_files). Read only those sections — not the whole blueprint.

Step 4 — Reconcile (do NOT just append)

For each statement, read the target section of the CURRENT snapshot and pick ONE op:

• NO-OP — already described accurately → change nothing. (Common — "it's already there." Don't manufacture an edit.)
• UPDATE — described but now wrong → correct it in place.
• ADD — not represented → add it to the right section.
• REMOVE — the section describes behavior the code no longer has → remove/correct it.

Where edits land — the descriptive MIRROR only (what the code is now):

• behavior/structure → .archie/blueprint.json components[] (responsibilities) / communication
• dataflow → communication, architecture_diagram
• data → data_models / persistence_stores / data_overview
• tech → technology · reference → quick_reference

Don't AUTO-change the CONTRACT (the law). Advisory claims (decision/pitfall/rule/ guideline) are recorded staged and surface under staged_amendments in fold-context — proposed changes for a separate, deliberate decision, NOT something the code-fold applies. The fold reconciles the descriptive mirror only. If the law genuinely changes during the work, change it deliberately (edit rules.json / domain_invariants on purpose) — fold-apply allows it but reports contract_changed so the law never moves silently. (Why: the PR Intent Review catches code-vs-law drift; the law must move deliberately and visibly, never as a silent side effect of reconciling code.)

Then reconcile the intent layer: for each touched folder in intent_files, update the descriptive (AI-authored) section of that folder's CLAUDE.md to match the code now — same NO-OP/UPDATE/ADD/REMOVE discipline, touched folders only. These are the folder snapshots; edit them directly. Preserve every untouched section; never drop a whole top-level blueprint key.

Step 5 — Apply

python3 .archie/sync.py fold-apply .

Re-renders root CLAUDE.md / AGENTS.md / rule docs from your edited blueprint, validates that no top-level section was dropped (aborts the render otherwise), and marks the record folded. It does not mass-rewrite per-folder CLAUDE.md — those you reconciled directly in Step 4.

After applying (or after recording when nothing was eligible), retire the signals you used so they don't double-count next time:

python3 .archie/sync.py plan-consume .   # moves captured plans to consumed/
python3 .archie/sync.py churn-reset .    # zero the churn counter
python3 .archie/sync.py sync-stamp .     # record the synced code state (commit .archie/sync_state.json)

sync-stamp writes .archie/sync_state.json — a content fingerprint of the source you just reconciled. Commit it alongside the blueprint/intent edits. The PR intent review reads it to tell whether a branch's code later moved on without a re-sync, and surfaces a (non-blocking) "run {{COMMAND_PREFIX}}archie-sync" advisory if so.

Step 5b — Regenerate and review the task story (MANDATORY — do not skip)

Archie captured the user's intent from their planning turns (via hooks) and distills it into a task story (versioned under .archie/stories/<branch-slug>/<timestamp>.md). The Stop hook already attempted a background imprint at turn end, but you MUST now regenerate it explicitly to ensure it reflects the full session, then review the result. Skipping it leaves the story stale and the PR delivery review has no accurate yardstick.

Always run these in order:

python3 .archie/sync.py imprint .    # REQUIRED: regenerate the story → .archie/stories/<branch-slug>/<timestamp>.md
python3 .archie/sync.py story .      # review the story + facts for correctness

Then, in your Step 6 report, show the user the story and tell them: "story wrong? edit the story file shown by python3 .archie/sync.py story . or re-run python3 .archie/sync.py imprint . to regenerate."

If imprint reports no events captured (e.g. a pure-exploration branch with no planning turns), say so plainly — the PR falls back to PR-body intent — and move on.

Stage .archie/stories/ (the whole directory) and .archie/intent-events.jsonl so the versioned story commits with the branch.

Step 6 — Report what changed ARCHITECTURALLY (not a file list)

Lead with the architectural meaning, plain language:

• What the snapshot now says that it didn't before — the changed behavior/structure/ flow, named at the component or boundary it concerns. e.g. "the subscription layer now distinguishes background refresh errors from user-initiated ones" — not "added pf_0010".
• What was corrected — if you UPDATEd/REMOVEd a now-false section, say what it used to claim and what it says now.
• Where it lives — which component/folder snapshot now reflects it.

Rules of the report: don't lead with entry IDs, row counts, or a list of files. Keep mechanics (version, branch, that blueprint/intent were updated, nothing committed) to ONE closing line. If the fold was mostly NO-OPs (already current), say that plainly.

Review the ledger any time: python3 .archie/sync.py list .