Build Memory

The owner of the build-memory layer that decompose-spec, orchestrate-build, implement-spec, synthesize-spec and reconcile-build all read and write. It owns one contract file, one set of templates, one validator and one migration tool, so build memory is defined in exactly one place.

Precedent. agent-docs owns the shared Doc Authoring Guidelines other skills cite; build-memory owns the layout the same way. The contract is layout.md — the tree, the modes, the machine-state ledger, the manifest / ticket / marker / tail shapes, the deferrals / ADR / index / gate rules, who writes what, the validator, and the compatibility policy. Read it before any mode below; every other skill cites it and does not restate the tree.

Build memory is committed (the record of a multi-session build is audit-valuable and git is the artifact store); only regenerable bulk (logs/) is gitignored. A repo opts in with the marker <!-- build-memory: v2 --> in docs/build/README.md. A repo without it runs in legacy scratch mode — byte-for-byte the pre-0.2.0 behaviour (see layout.md § Compatibility and README.md).

Resolve the root first (every mode)

// turbo

bash scripts/memory-root.sh            # prints: mode=<committed|scratch>  root=<abs path>

Committed mode → the root is <worktree>/docs/build, resolved from the current worktree (a sibling build worktree reads its own chain tip). Scratch mode → the legacy gitignored dir. $BUILD_MEMORY_ROOT overrides both.

Mode: check (default)

Validate the layout. Read-only; exit-code gated; runnable in CI.

// turbo

bash scripts/check-build-memory.sh .                      # tree mode: 0 clean · 1 violations · 2 not a build-memory repo · 3 vacuous
bash scripts/check-build-memory.sh . --range BASE..HEAD   # history mode (also --staged, --first-parent SHA); 5 = unknown
bash scripts/check-build-memory.sh . --planning docs/research-ledger.md   # planning-ledger freshness (V14)

It checks everything the skills derive (layout allowlist + logs/.gitignore; ticket filename grammar + unique sequence; manifest ↔ files both ways; backward Depends on; skeletons carry no run line; markers referenced; DEFERRALS ids unique + valid statuses; no OPEN row past a PASSED gate; ADR files ↔ generated index; every ADR has ## Revisit trigger; spec ADR appendix == file set when present; LEDGER.md key set + order and nextTicket; PHASE-LOG "done" ↔ BUILD_INDEX row + runs/<ID>.md; REQ→ticket coverage when the spec and req_id_pattern resolve; size + secret scans; the ledger budget and shape, BM-LEDGER-08; the kind of 7-column GATE DECISIONS rows and scoped pre-authorizations, BM-GATE-05/-09; the CURRENT STATE vocabularies; stale orient text; record dates later than the clock; BUILD_INDEX row shape; readout guard sentences; run-ledger Harness: lines; living-pin? tests). The PHASE LOG parser reports what it evaluated, and exits 3 rather than pass vacuously. The human summary lists each violation and warning; the JSON report (build-memory-check/2: input identity, counts, diagnostics) goes to --json PATH or a unique temp file named on the last line. A failure is a real block — the caller does not proceed past it. Guarded rules warn unless docs/build/README.md also carries <!-- build-memory-guards: 1 --> (BM-COMPAT-06), so legacy content never fails on them.

History mode (--range, --staged, --first-parent; scripts/check-history.sh, BM-HIST-01) judges only the lines a change adds or removes — append-only regions and their append position, row-annotated DEFERRALS, frozen contracts and ADRs, *.jsonl prefixes, the living-archived ledger head, and the record dates on added lines (R1–R6) — so legacy content never fails it. A repo guard docs/build/tools/memory_guard.* takes over when present; repo policy lives in docs/build/tools/record_policy/history.policy.

decompose-spec runs check after seeding, implement-spec before its close commit (tree, then --staged), orchestrate-build at every boundary (tree, then --range).

Mode: init

Write the layout into a repo. Idempotent — never overwrites an existing file. For each target, if the file is absent, create it from the matching template in templates/ (filling any placeholders); if present, leave it untouched.

1. Resolve the root (above). init implies committed mode: the target root is <repo>/docs/build.
2. Create, if absent:
   • docs/build/README.md (from templates/build-README.md; must contain the marker).
   • docs/build/LEDGER.md (from templates/LEDGER.md; the state-only shape — seed projectStatus: NOT_STARTED, round: 1).
   • docs/build/BUILD_INDEX.md (from templates/BUILD_INDEX.md; header row only).
   • docs/build/logs/.gitignore containing * then !.gitignore (the one ignored subtree).
   • docs/tickets/{00_MANIFEST.md,_TEMPLATE.md,DEFERRALS.md} (from templates/MANIFEST.md, templates/ticket.md, templates/DEFERRALS.md).
   • docs/build/readouts/_TEMPLATE.md (from templates/READOUT.md).
   • docs/adr/{_TEMPLATE.md} (from templates/adr-TEMPLATE.md); then generate docs/adr/README.md with adr-index (below).
   • AGENTS.md "Build memory" section (from templates/AGENTS-build-memory.md) — appended if AGENTS.md exists, else the section is offered to agent-docs.
   • docs/README.md — if it exists, add the build-memory rows (build/, tickets/, adr/) with their modes; else create it from templates/docs-README.md.
3. Do not overwrite tickets, ledgers, ADRs, or a spec that already exist.
4. Run check — a fresh init must be clean.

decompose-spec calls init during seeding; the operator may call it directly to adopt the layout in an existing repo.

Mode: adr-index

Regenerate docs/adr/README.md from the ADR files (numeric order; columns ADR · Title · Ticket · Status; carries the generated marker). Never hand-edit the index.

bash scripts/adr-index.sh docs/adr          # writes docs/adr/README.md
bash scripts/adr-index.sh --check docs/adr  # print to stdout only (what the validator diffs)

Mode: migrate

Move a legacy gitignored scratch dir into the committed docs/build/ tree. Mutating with apply=true; a dry-run plan otherwise. Move/rename only — the contents of every moved run ledger / PR body / tool / fixture stay byte-identical; the machine ledger is the one file edited, and only by appending manifest: / memoryRoot: / round: to CURRENT STATE.

bash scripts/migrate-legacy-scratch.sh --from .agents/scratch          # dry-run plan
bash scripts/migrate-legacy-scratch.sh --from .agents/scratch --apply  # perform it

Mapping (see the script header for the full list): implement-spec_*.md → runs/<ID>.md (id from the filename, else the file's H1; unresolvable names keep their basename); pr/*, tools/*, fixtures/*, planning/* → the same-named dirs; *build-ledger.md → LEDGER.md (converted); *.log → dropped; the rename mapping is appended to docs/build/README.md. After migrating, run check and review the diff before committing; then remove the now-empty legacy dir and add docs/build/logs/ to .gitignore (leave the old .agents/ line — it is harmless).

Templates and tests

• templates/ holds one self-describing template per artifact (each with a header comment naming who fills it and when):
  • memory root & docs map: build-README.md, docs-README.md, AGENTS-build-memory.md.
  • machine state & index: LEDGER.md, BUILD_INDEX.md.
  • contracts & markers: MANIFEST.md, ticket.md, ticket-skeleton.md, HUMAN.md, GATE.md, READOUT.md, DEFERRALS.md, adr-TEMPLATE.md.
  • upstream (synthesize-spec): research-ledger.md, research-CONVENTIONS.md, spec-front-matter.md.
  • closeout CSVs: COVERAGE_MATRIX.csv, BACKLOG.csv.
  • templates/tail/ — the tail tickets decompose-spec instantiates: CAP.1, CAP.2, CAP.3, GATE-ACCEPT, REC.1, REC.2, REC.3, DOC.1, DOC.2 (tail=full), and DOC (the default tail=minimal's single docs row).
• tests/ holds five fixture repos (v2-clean, v2-violations, legacy-scratch, v2-legacy-ledger, v2-guards-violations), history/build.sh (throw-away git repos committed with GIT_COMMITTER_DATE in the shapes of real violations) and run-tests.sh, which exercises all five scripts, asserts exit codes and expected files, and golden-checks the templates. Run it from anywhere:

// turbo

bash tests/run-tests.sh     # one PASS line per fixture; exit 0 iff all pass

Scripts (all bash 3.2+, read-only unless noted)

What this skill does NOT do

• No sequencing, no implementation — it owns the layer; orchestrate-build sequences and implement-spec implements.
• No harness-specific config — the layout is portable prose + POSIX-ish bash.
• No deletion of history — migration moves and renames; it never edits moved contents and never drops anything but regenerable logs.