@tyroneross/build-loop 0.36.0 → 0.43.0

package/plugin-artifacts/codex/references/memory-systems.md

@@ -1,261 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Memory Systems — orchestrator reference
-
-Build-loop reads/writes four memory stores. Loaded on demand at Phase 1 Assess and Phase 4 Review sub-step F.
-
-## Substrate vs memory policy
-
-The database is not memory. Databases, files, object stores, vector indexes,
-keyword indexes, caches, and event logs are storage/retrieval substrates. Memory
-is the policy layer that decides what should be remembered, forgotten,
-superseded, trusted, refreshed, retrieved, and injected into the model context.
-
-When changing build-loop memory, keep these layers explicit:
-
-| Layer | Build-loop examples | Rule |
-|---|---|---|
-| Canonical truth | `<memory-root>/projects/<project>/decisions/*.md`, project lessons, `.build-loop/state.json.runs[]` | Durable facts must be evidenced, scoped, and supersedable. |
-| Raw artifacts | archived plans, source docs, run artifacts, attachments | Preserve evidence separately from promoted memory. |
-| Derived indexes | `INDEX.md`, `INDEX.jsonl`, semantic/Postgres rows, SQLite/FTS projections | Rebuildable; never the sole source of truth. |
-| Explicit memory records | decisions, lessons, preferences, gotchas, run summaries | Small, structured, and future-recallable. |
-| Cache/working state | context bootstrap packet, backend health, run-local snapshots | Useful for current work; not durable memory by default. |
-| Audit/event log | milestones, telemetry, JSONL ledgers, Rally facts | Explains what happened and supports replay/debugging. |
-
-Design implication: do not promote raw transcripts, vector hits, cache entries,
-or retrieved chunks directly into memory. Promote only the distilled rule,
-decision, preference, or lesson, with source evidence and freshness/supersession
-metadata.
-
-## The four stores
-
-| Store | Path | Purpose | Scope |
-|---|---|---|---|
-| Run history | `.build-loop/state.json.runs[]` | Per-build outcome + diagnostic trail. Phase 6 Learn scans this for recurring patterns. | Project-local |
-| Episodic decisions | `<memory-root>/projects/<project>/decisions/*.md` (canonical); legacy paths only when `BUILD_LOOP_MEMORY_MIGRATION_MODE=1` | MADR-style decisions. Topic-identity supersession by `primary_tag + entity`. | Project-tagged, repo-deletion-survivable |
-| Semantic facts | Postgres `agent_memory.<schema>.semantic_facts` | Embeddings + structured facts for hybrid retrieval. | Project-tagged, opt-in |
-| Debugger incidents | `.build-loop/issues/*.md` plus optional standalone Coding Debugger MCP | Bug history with local recall; optional verdict-classifier feedback loop when Coding Debugger is installed. | Project-local by default; optional cross-project |
-
-The **memory facade** at `scripts/memory_facade.py` exposes one `recall(query, kind, project, limit)` over all four with graceful degradation. Use it instead of writing four ad-hoc reads.
-
-## Read protocol — Phase 1 Assess
-
-Mirrors the write-protocol's executable shape (fenced commands + return-shape table + graceful-degradation matrix). The first operation is the automatic context bootstrap; empty results are valid; never raise on a missing backend. The orchestrator's Phase 1 imperative in `agents/build-orchestrator.md` MUST stay in lock-step with this section — when call wiring changes, update both.
-
-### 1. Automatic context bootstrap
-
-```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/context_bootstrap.py \
-  --workdir "$PWD" \
-  --query "<goal-keywords>" \
-  --output "$PWD/.build-loop/context-bootstrap.json" \
-  --json
-```
-
-**Return shape**: JSON packet with `{ generated_at, workdir, project, query, terms, sources, agent_brief }`.
-
-`sources` includes:
-- `canonical_memory`: root and project `MEMORY.md` / `constitution.md` from `<memory-root>`, plus `scripts/memory_facade.py recall()` results over canonical project files and local runs. If the root `constitution.md` is missing, `scripts/context_bootstrap.py` seeds it once from `templates/memory/constitution.md.template` before reading; existing files and project-specific constitutions are never overwritten. Semantic/Postgres reads are opt-in via `--include-postgres` so the default Phase 1 pass stays file-backed and fast.
-- Ephemeral project plans must be archived before cleanup removes them. Use `scripts/archive_project_plan.py <plan> --workdir "$PWD"` to copy them into `build-loop-memory/projects/<slug>/archive/plans/<YYYY-MM-DD>/`; pass `--remove-source` only when the local file should be deleted after the archive write succeeds.
-- `repo_local`: `.build-loop/feedback.md`, `.build-loop/state.json` summary including `runs[-3:]` and backend health when present, plus current `.build-loop/intent.md`, `.build-loop/goal.md`, and `.build-loop/plan.md`.
-- `codex_memory`: `~/.codex/memories/MEMORY.md` registry hits and bounded excerpts from linked `rollout_summaries/*` files.
-- `rally`: best-effort `coordination_status.py` result when coordination context exists.
-
-**Degradation**: every source carries `reasons[]`. Missing Codex memory, absent repo-local files, skipped or down Postgres, unavailable optional Coding Debugger, or Rally errors are context-quality signals, not blockers. Surface high-impact gaps in the Assess brief.
-
-### 1b. Re-read cadence — long/autonomous mode only (WP-G1)
-
-Short runs read once at Phase 1 (above). In **LONG / AUTONOMOUS mode ONLY**, re-read
-memory at each iterate-loop entry and each phase boundary, **gated by
-`scripts/memory_staleness_check.py`** so it is a no-op when nothing changed:
-
-```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_staleness_check.py --workdir "$PWD" --json
-# stale=true → re-run the §1 bootstrap; stale=false → skip (cheap milestone-vs-HEAD read)
-```
-
-The staleness check is a single cheap file read (latest milestone `commit` sha vs
-commits-since count); it costs almost nothing when clean. The re-read catches two
-things: parallel-session writes landing in canonical memory mid-run, and the run's
-OWN accumulating decisions (see incremental writes, G2). Classic short runs skip
-this entirely — the once-at-Phase-1 read is sufficient when the run is brief.
-
-### 1a. Live context snapshots (handoff/resume, not durable memory)
-
-After bootstrap, Build Loop keeps the current handoff state fresh through:
-
-```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/context_snapshot.py \
-  --workdir "$PWD" \
-  --trigger "<manual | interval | phase_transition | agent_dispatch | agent_return | pre_commit | post_commit>" \
-  --phase "<phase>" \
-  --run-id "$RUN_ID" \
-  --message "<one-line current state>" \
-  --if-changed \
-  --json
-```
-
-**Return shape**: `{ ok, action: "written" | "skipped", snapshot_id, snapshot_path?, current_path }`.
-
-**Writes**: `.build-loop/context/current.md`, `.build-loop/context/snapshots/*.json`, and trigger-specific JSONL sidecars for agent and commit boundaries. This is session/runtime context like Bookmark's useful handoff layer, but non-blocking and repo-local. Do NOT promote every snapshot into durable memory. Only Review-G or explicit decisions write reusable facts to `build-loop-memory`.
-
-### 2. Unified recall facade (diagnostic/reference)
-
-The bootstrap calls the facade directly. Use the standalone command when debugging the canonical memory layer itself:
-
-```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_facade.py recall \
-  --query "<goal-keywords>" \
-  --limit 10
-```
-
-**Return shape**: JSON envelope `{ results_by_kind: {...}, merged: [...], reasons: [...], telemetry_correlation_id: "..." }`. Inspect `reasons[]` for `db_unavailable` / `mcp_unavailable` / `path_missing` signals — those are data, not failures. **Degradation**: any backend down -> that backend reports a `reason`; remaining backends still return rows.
-
-### 3. Debugger incidents priming (recent-list)
-
-The bootstrap includes build-loop incident results through the facade. If the build is debugging-heavy, also call:
-
-```text
-Skill("build-loop:debugging-memory") with { intent: "list-recent" }
-```
-
-**Return shape**: one-line summary `"N recent incidents in this project, top categories: [...]"`. Counts feed Phase 1's awareness of what's been failing lately. **Degradation**: optional Coding Debugger unavailable -> fall through to `${CLAUDE_PLUGIN_ROOT}/skills/build-loop/fallbacks.md#bug-memory` (token-extract + grep over `.build-loop/issues/` and `.build-loop/feedback.md`). Flag debugger fallback in Review-F only when cross-project recall was requested and unavailable.
-
-### 4. Optional Coding Debugger MCP shape (diagnostic reference; use only when installed)
-
-```text
-mcp__plugin_coding_debugger__list({ filter: { project: "<current>" }, limit: 10 })
-```
-
-**Return shape**: `{ incidents: [{ id, symptom, root_cause, fix, tags, created_at }, ...] }`. Surfaced here so a diagnostic check of the standalone debugger doesn't have to traverse the skill abstraction.
-
-### 5. Backend health check (Priority 17)
-
-```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/backend_health.py --workdir "$PWD"
-```
-
-**Why this exists**: `recall()` (step 2) gracefully degrades on Postgres-down or MCP-down — the orchestrator never visibly logs which backends responded. The health-check surface makes that explicit so the Phase 1 Assess brief can tell the user whether memory is at full or partial capacity.
-
-**Return shape**: stdout one-liner `runs: OK N entries | decisions: OK N entries | semantic: DOWN postgres_unavailable | debugger: DOWN mcp_unreachable`. Full JSON envelope is written to `state.json.architecture.backendHealth` (`{ runs: {ok, count}, decisions: {ok, count}, semantic: {ok, reason?}, debugger: {ok, reason?}, summary, generated_at, total_duration_ms }`).
-
-**Budget**: 5s per backend, 30s total. Exit 0 even when all backends are down — graceful degradation is the contract.
-
-**Surface in the Phase 1 Assess brief**: the orchestrator must echo the one-liner so the user can see backend availability before any work begins.
-
-### Return-shape & exit-code summary
-
-| Step | Surface | Return shape | Empty-OK | On backend down |
-|---|---|---|---|---|
-| 1 | `context_bootstrap.py` | JSON packet w/ `sources.*.reasons[]` + `agent_brief` | yes | per-source `reason`; other sources still respond |
-| 2 | `memory_facade.py recall` | JSON envelope w/ `reasons[]` | yes | per-backend `reason`; other backends still respond |
-| 3 | `Skill("build-loop:debugging-memory")` | one-line text summary | yes | grep-fallback per `fallbacks.md#bug-memory` |
-| 4 | optional `mcp__plugin_coding_debugger__list` | `{ incidents: [...] }` | yes | step 3 already covered the fallback |
-| 5 | `scripts/backend_health.py` | one-liner + JSON envelope written to `state.json.architecture.backendHealth` | n/a | per-backend `ok: false` + `reason`; other backends still probable |
-
-### Graceful-degradation matrix
-
-| Failure mode | Step 1 | Step 2 | Step 3 | Step 4 | Step 5 |
-|---|---|---|---|---|---|
-| Postgres unavailable | `canonical_memory.reasons[]` records skip/down | `reason: db_unavailable` for semantic backend, others continue | n/a | n/a | `semantic.ok: false` |
-| Optional Coding Debugger unavailable | `canonical_memory.reasons[]` records debugger unavailable when requested | `reason: debugger_unavailable` | grep fallback | unusable; rely on step 3 fallback | `debugger.ok: false` |
-| `state.json` missing | `repo_local.reasons[]` records missing file | recall still runs other backends | n/a | n/a | runs may still report down |
-| Codex MEMORY.md absent | `codex_memory.reasons[]` records missing registry | n/a | n/a | n/a | n/a |
-| All backends down | packet still emits with populated `reasons[]` | envelope w/ all `reasons` populated, `results: []` | grep fallback | n/a | all relevant backends `ok: false` |
-
-## Write protocol — Phase 4 Review sub-step F
-
-Apply the canonical recall-optimized write rule in
-`build-loop-memory/references/2026-06-11-memory-discipline-prompt.md`
-(`version: 2026-06-11.1`) before every durable memory write: recall first,
-write only future-recallable facts, avoid duplicates, classify by indexed
-lane, stamp provenance through the writer in use, and verify reachability from
-the relevant recall surface.
-
-The **run entry + milestone** (the structured summary of the whole run) is written
-once on the final Review pass — that aggregate is correctly batch-at-Review-G.
-
-### Incremental durable writes — at discovery time (WP-G2, crash-resilience)
-
-Durable **lessons / decisions / falsifiers** are written INCREMENTALLY at discovery
-time, NOT batched to Review-G. The same total volume, written earlier:
-
-- When a lesson is learned, a decision is made, or a falsifier is named mid-run,
-  append it to canonical memory on the spot via `scripts/write_decision/__main__.py`
-  (decisions) or `scripts/memory_writer.py` (lessons/reusable memories) — the
-  append-immediately contract.
-- Review-G then does a final **dedup sweep** over what accumulated (it no longer
-  originates the writes, it reconciles them).
-
-Why: the batch-at-Review-G model loses every lesson when a run crashes before close
-(the resume / 529 / OOM scenario; documented closeout-never-fires-on-crashed-work
-class). Incremental append means a crash at iterate-3 still leaves iterate-1/2's
-lessons durable. Pairs with the G1 re-read: the run's own incremental writes are
-exactly what the staleness-gated re-read picks back up.
-
-### Run entry — delegate to the deterministic writer
-
-Do NOT hand-write JSON. Schema source-of-truth lives in `scripts/write_run_entry.py`.
-
-```bash
-RUN_ID=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/write_run_entry.py" \
-  --workdir "$PWD" \
-  --goal "$GOAL_SUMMARY" \
-  --outcome pass \
-  --phases-json '{"assess":{"status":"pass","duration_s":12},"plan":{...}}' \
-  --files-touched-from-git \
-  --diagnostic-commands "$(printf 'cmd1\ncmd2\n')" \
-  --manual-interventions-json '[]' \
-  --active-experimental-artifacts "skill-a,skill-b" \
-  --security-findings-json .build-loop/issues/security-findings.json)
-```
-
-Capture `RUN_ID` from stdout and cite it in the scorecard. Always pass `--security-findings-json` even when `triggers.riskSurfaceChange` was false — the script silently treats a missing file as no findings. Exit codes: `0` ok, `1` validation error, `2` filesystem error.
-
-### Resolved debugger incidents
-
-Use the native `Skill("build-loop:debugging-memory")` with `{op:"store", ...}`. Procedure also in `Skill("build-loop:debugging-memory")` §"Review-F outcome feedback":
-
-- For each newly resolved Review-B/Iterate failure: invoke `build-loop:debugging-memory` `{op:"store", symptom, root_cause, fix, tags: ["build-loop", project, layer], files}`.
-- For each Review-B memory gate where a prior `KNOWN_FIX` or `LIKELY_MATCH` was applied: invoke `outcome` MCP tool with `{incident_id, result: "worked"|"failed"|"modified", notes}`. This trains the verdict classifier.
-
-Both steps are required to close the memory-first gate's feedback loop. Skipping `outcome` means the verdict classifier never improves from this build's signal.
-
-### Memory tier
-
-Write new memory entries to the correct tier:
-
-- **Cross-project learnings** (new tool, deployment pattern, user preference) → `<memory-root>/lessons/<type>_<slug>.md` via `scripts/memory_writer.py --scope top-level write ...`.
-- **Project-specific learnings** (design decisions, internal conventions, gotchas) → `<memory-root>/projects/<project>/lessons/<type>_<slug>.md` via `scripts/memory_writer.py --scope project --project <project> write ...`.
-
-Do not hand-write project decision markdown. Use the paired decision writer. It
-writes `projects/<slug>/decisions/`, regenerates that lane's `INDEX.md`, and
-records `indexes/updates.jsonl`. Generated master-index reachability is still
-incomplete for project decisions: `rebuild_memory_indexes.py` does not
-content-scan `decisions/`, so verify through the `memory_facade` read API or the
-decision lane/index until the scanner/map split is reconciled.
-
-Reference capture has a lane mismatch today: `memory_writer.py` has `research`
-as a project sublane but not `references`; `reference_capture` writes to
-`projects/<slug>/research/`, while
-`build-loop-memory/scripts/rebuild_memory_indexes.py` scans `references/` and
-not `research/`. For generated-index recall, write `type: reference` content
-under `projects/<slug>/lessons/references/`, or update both writer and indexer
-to agree on `references` or `research`.
-
-Evaluate any skill authored during the build (Skill-on-Demand §SKILL.md): keep, promote, or drop. Record the decision in memory.
-
-## Decision-store paths over time
-
-Decisions live under TWO paths today (canonical + legacy). The orchestrator and any verification check MUST go through the `scripts.memory_facade` read API, not raw filesystem assumptions.
-
-| Path | Status | Notes |
-|---|---|---|
-| `<memory-root>/projects/<project>/decisions/NNNN-YYYY-MM-DD-slug.md` | **Canonical (current)** | New writes land here. `<project>/` is resolved via `scripts/project_resolver.py` from `cwd → project tag`. |
-| `<repo>/.episodic/decisions/NNNN-YYYY-MM-DD-slug.md` | Legacy migration/archive input | Pre-cutover decisions. Active reads include it only when `BUILD_LOOP_MEMORY_MIGRATION_MODE=1`. |
-
-**Read path**: `scripts.memory_facade.recall(..., kind="decision", ...)` reads canonical indexes/files and, only in migration mode, legacy paths. **Direct filesystem reads are fragile** — a verification rule that `ls`'d only the legacy path returned a phantom miss because the new canonical was authoritative. Locked by lesson `lesson-bl-decision-store-path-cutover`; consume it through the facade instead of hard-coding the lesson-file path.
-
-**Write path**: `scripts/write_decision/__main__.py` writes to the canonical (new) path by default. The legacy path is only written when explicitly requested by tests fixturing pre-cutover state.
-
-**INDEX.md**: each decision-store directory has its own `INDEX.md`. The facade reads both indexes and merges by ID. Do NOT edit `INDEX.md` by hand — `write_decision.py` regenerates it atomically as part of the memory-triad write.

package/plugin-artifacts/codex/references/memory.md

@@ -1,313 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Memory — Global and Project-Scoped (full protocol)
-
-> Loaded from `skills/build-loop/SKILL.md` summary. Contains the full memory system: global vs project stores, routing rules, and read/write policies.
-
-## Memory — Global and Project-Scoped
-
-Build-loop maintains one canonical long-term memory store at `~/dev/git-folder/build-loop-memory/`. Every build reads canonical indexes/folders; writes go to exactly one lane based on scope.
-
-### Recall-optimized memory discipline
-
-Canonical reference: `build-loop-memory/references/2026-06-11-memory-discipline-prompt.md` (`version: 2026-06-11.1`). Apply it to every non-trivial memory-relevant read or write.
-
-Operational contract:
-
-- Recall first for significant repo work, debugging, planning, and any memory write. Read the store-root `INDEX.md` first, then project context such as `projects/<slug>/context/CONTEXT.md` and generated `CURRENT.*`, plus `constitution.md` / `MEMORY.md` where present. Search `indexes/INDEX.jsonl`, scan `chronology.jsonl`, read the matching lane, and verify any remembered file/flag/API/script still exists before relying on it.
-- Write only durable facts that aid future recall: decisions + rationale, lessons, reusable references, gotchas, experiment results, product opportunities, and durable operational patterns. Do not write restated code, git-derivable facts, transient status, or handoff-only state.
-- Before writing, search `indexes/INDEX.jsonl` for an existing slug/title, update instead of duplicating, then check `indexes/duplicates.jsonl` after indexing. Use title and `description` as the recall hooks.
-- Do not hand-write project decisions. Use `scripts/write_decision/__main__.py`; it writes the decision lane and updates that lane's `INDEX.md` / update ledger. Generated master-index reachability is still incomplete for new `projects/<slug>/decisions/` files, so verify decisions through `memory_facade` or the decision lane until the scanner/map split is reconciled.
-- Current reference gap: `memory_writer.py` has `research` as a project sublane but not `references`; `reference_capture` writes to `projects/<slug>/research/`, while `build-loop-memory/scripts/rebuild_memory_indexes.py` scans `references/` and not `research/`. For generated-index recall today, write `type: reference` content under `projects/<slug>/lessons/references/`, or update both writer and indexer to agree on `references` or `research`.
-- After any memory write, run the relevant host index/check step when mutation is in scope and verify the entry is reachable from the proper recall surface: `INDEX.jsonl` for generated-index lanes, decision lane/index or `memory_facade` for decisions, or the host system's equivalent.
-
-**Cross-project memory**: `build-loop-memory/lessons/` plus the sibling top-level lanes `design/`, `debugging/`, and `product/`
-
-- Applies across every project this user builds.
-- Examples: "Deployment to Vercel uses `vercel deploy --prebuilt` when `ENABLE_AUTH=true`"; "Neon is the default Postgres for Next.js 16 projects"; "TestFlight upload uses ASC API key from `~/.appstoreconnect/private_keys/`"; "User prefers zero-dep scripts over package additions".
-- Structure: one file per fact/lesson/tool-discovery. Generated recall indexes live in `build-loop-memory/indexes/`.
-- Types: `tool`, `deployment`, `library-choice`, `user-preference`, `pattern`.
-
-**Project memory**: `build-loop-memory/projects/<slug>/` (slug derived via `scripts/_paths.derive_slug_from_cwd`)
-
-- Applies only to the current project.
-- Examples: "This app's design system lives in `src/styles/tokens.css`, not Tailwind"; "Routes under `/admin/` require `requireAdmin()` guard"; "The `custom_themes` table has a user_id VarChar bug from 2026-04-13 — see migration note".
-- Same lane structure as top level: `decisions/`, `lessons/`, `debugging/`, `design/`, `product/`, and related domain folders.
-- Types: `design`, `convention`, `gotcha`, `decision`, `contract`.
-
-### Routing rule (always ask this question)
-
-**"Would this apply to a different project?"**
-
-- **Yes** → top-level canonical lane (`build-loop-memory/lessons/`, `design/`, `debugging/`, or `product/`). Deployment tools, library choices, general user preferences, reusable patterns.
-- **No** → project canonical lane (`build-loop-memory/projects/<slug>/...`). Design tokens, internal APIs, project-specific gotchas, per-repo conventions.
-- **Ambiguous** → ask the user once, then save. Don't guess.
-
-### Artifact lanes & segmentation (issues / backlog / lessons)
-
-Three work/knowledge artifact types, each with a clear WRITE → READ → TRACK lane. **Every lane is repo-segmented; the segmentation is mechanical, not discretionary** — so work on repo X never reads or writes repo Y's items.
-
-| Artifact | Write (where) | Read / Track | Lifetime |
-|---|---|---|---|
-| **issues** | `<repo>/.build-loop/issues/<id>.md` — current-run bugs | Phase 5 Iterate drains them; repo-local so inherently scoped | short-lived (resolve → delete) |
-| **backlog** | durable: `build-loop-memory/projects/<slug>/backlog.md` (slug folder = repo scope); active: `<repo>/.build-loop/backlog/<id>.md` | read before planning self-work; Phase 5 drains active items | long-lived |
-| **backlog-archive** | `build-loop-memory/projects/<slug>/backlog-archive.md` | closed/moved/superseded items land here **with rationale + ref** — never deleted silently | durable |
-| **lessons** | `projects/<slug>/lessons/` (project) OR top-level `lessons/` (cross-project, stored `_unscoped`) — via `memory_writer.py` | `context_bootstrap` recall scopes to `(slug OR _unscoped)` — never other projects | durable |
-
-**Segmentation contract (binding):**
-- The **slug folder** (`projects/<slug>/`) is the repo key; the **`repo` + `branch` frontmatter** on each issue/backlog item is the explicit scope tag (template: `templates/backlog-item.md`). Both must agree.
-- When working repo X on branch B, **read and write only** items where `repo == X` (and `branch == B` or unscoped). A cross-repo item discovered mid-work is recorded in **its** repo's scope, **never** the current repo's tracker.
-- **No shared/freeform cross-repo trackers.** (The retired `OPEN-ITEMS.md` was exactly this anti-pattern — one file that accreted rows from unrelated app repos into build-loop's scope. Replaced by the slug-segmented `projects/<slug>/backlog.md`.)
-- Reads are already enforced: `context_bootstrap` queue reads are repo-local `.build-loop/`, and lessons recall passes the resolved `project` so the query scopes to `(project OR _unscoped)` — `project=None` (all-projects) is never used for current-work context.
-
-### When to write memory
-
-- User states a preference or convention: save immediately.
-- A build surfaces a new tool/library/deployment pattern worth reusing: save after Review-F.
-- A project-specific gotcha or decision emerges: save during Review-F Report.
-- Do NOT save: ephemeral task details, things already derivable from code or git log, state that changes per build.
-
-### When to read memory
-
-- Always during Phase 1 ASSESS.
-- Before deploying: check global deployment memory.
-- Before UI work: check project design memory.
-- Before adopting a new library: check global library-choice memory.
-
-## Cross-session memory propagation + provenance schema (multi-process / multi-host)
-
-Multiple build-loop sessions can run concurrently. Two scripts own the cross-session model end-to-end:
-
-- `scripts/memory_writer.py` — canonical WRITER. Adds provenance frontmatter and appends to the index in one atomic operation.
-- `scripts/memory_index.py` — append-only discovery log in the selected canonical lane.
-- `scripts/memory_update_ledger.py` — global append-only audit/freshness log for the whole configured memory root.
-
-### Provenance frontmatter (every memory file)
-
-```yaml
----
-name: <slug>
-description: <one-line summary>
-type: tool | deployment | library-choice | user-preference | pattern | feedback | reference | design | convention | gotcha | decision | contract
-source_repo: "<git remote url or null>"
-source_workdir: "<abs path>"
-source_run_id: "run_<UTC>_<hash>"
-source_host: "claude_code | codex | gemini | other"
-cross_repo_validated: false          # flips to true once a DIFFERENT repo applies it
-applied_in_repos: []                  # appended entries: {repo, workdir, run_id, applied_at}
-created_at: "ISO8601 UTC"
-last_updated_at: "ISO8601 UTC"
----
-```
-
-### Writer side — use the canonical writer for normal memory writes
-
-**Top-level (cross-project) write** — `--scope top-level` routes to `build-loop-memory/lessons/` (or a sibling lane when `--file <lane>/x.md` is used):
-
-```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py \
-  --scope top-level \
-  write \
-  --file "<rel-path>" \
-  --name "<slug>" \
-  --description "<one-line>" \
-  --type feedback \
-  --run-id "$RUN_ID" \
-  --workdir "$PWD" \
-  --host claude_code \
-  --body-file /tmp/memory-body.md
-```
-
-**Project-scoped write** — `--scope project --project <slug>` routes to `build-loop-memory/projects/<slug>/lessons/` (or a sublane when `--file <sublane>/x.md` is used):
-
-```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py \
-  --scope project --project "$PROJECT_SLUG" \
-  write \
-  --file "<rel-path>" \
-  --name "<slug>" \
-  --description "<one-line>" \
-  --type gotcha \
-  --run-id "$RUN_ID" \
-  --workdir "$PWD" \
-  --host claude_code \
-  --body-file /tmp/memory-body.md
-```
-
-The writer auto-detects `source_repo` from the workdir's git remote, appends a row to the lane-local `INDEX.jsonl`, appends a row to the global update ledger at `indexes/updates.jsonl`, and (on update) preserves `created_at` + `applied_in_repos` so cross-repo validation history survives edits. Direct writes are repair/fallback work only: use them only when no canonical writer exists or the current task is explicitly a memory-system repair, then run the host index/check step and verify reachability.
-
-### Codex cross-repo write guard
-
-When using Codex `apply_patch`, path resolution is relative to the active
-workspace, not to a shell command `workdir`. If a memory artifact belongs in a
-different repo such as `build-loop-memory`, use one of these safe paths:
-
-- Prefer `scripts/memory_writer.py` for normal memory writes.
-- If direct repair is unavoidable, pass absolute target paths to `apply_patch`.
-- Before moving a generated file that already appeared in a Codex file card,
-  leave an openable pointer, mirror, or stub at the old path and update any
-  dependent indexes/links. Do not strand UI/Finder file cards at missing paths.
-- After a move, verify both the canonical destination and every old path that a
-  user-facing file card, index, or markdown link still references.
-
-### Reader side — surface peer writes via INDEX.jsonl
-
-Between phases (or at every M2 heartbeat), tail since your last check:
-
-```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_index.py tail \
-  --since "$LAST_INDEX_CHECK_TS" \
-  --exclude-run-id "$RUN_ID" \
-  --json
-```
-
-For each row:
-1. Read the underlying memory file.
-2. If `source_workdir` ≠ this `$PWD` AND `source_repo` ≠ this repo's git remote — tag `[CROSS-REPO — requires scrutiny]` in the phase brief.
-3. Surface to the user with the memory's `description` field as the hook.
-
-### Store side — global update ledger
-
-Every canonical memory mutation should also append one JSONL row to:
-
-```
-<memory-root>/indexes/updates.jsonl
-```
-
-This is the store-wide ledger. It is not a replacement for lane-local `INDEX.jsonl`; the two logs have different jobs:
-
-| Log | Scope | Primary job |
-|---|---|---|
-| `<lane>/INDEX.jsonl` | One memory lane | Peer discovery inside that lane |
-| `indexes/updates.jsonl` | Whole memory root | Audit trail, freshness baseline, repair inventory |
-
-Row schema:
-
-```json
-{
-  "ts": "2026-06-01T12:00:00Z",
-  "schema_version": 1,
-  "event_id": "<sha256-prefix>",
-  "project": "build-loop",
-  "lane": "decisions",
-  "action": "write",
-  "path": "projects/build-loop/decisions/0001-example.md",
-  "writer": "write_decision.py",
-  "run_id": "run_...",
-  "source_repo": "<git remote or omitted>",
-  "source_workdir": "<absolute workdir or omitted>",
-  "source_commit": "<repo HEAD represented by this memory update>",
-  "source_host": "codex",
-  "memory_id": "0001",
-  "summary": "Short human hook",
-  "sha256": "<content hash when available>",
-  "metadata": {}
-}
-```
-
-`memory_writer.py`, `write_decision.py`, and `append_milestone.py` emit this ledger row automatically. Direct writes to memory files should be treated as legacy or repair work because they bypass provenance, discovery, and freshness.
-
-CLI:
-
-```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_update_ledger.py tail \
-  --project "$PROJECT_SLUG" \
-  --limit 20 \
-  --json
-```
-
-### Trust gradient — mark-applied flow
-
-When a memory written elsewhere is successfully applied in the current repo, record it:
-
-```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py mark-applied \
-  --file "<rel-path>" \
-  --applying-repo "$THIS_REPO_REMOTE" \
-  --applying-workdir "$PWD" \
-  --applying-run-id "$RUN_ID"
-```
-
-Appends to `applied_in_repos[]` (deduped by `(repo, workdir)`) and flips `cross_repo_validated` to `true` once at least one applying repo differs from the source. Memories with `cross_repo_validated: true` AND `len(applied_in_repos) >= 2` have earned higher trust — independently verified to hold across distinct repos. Surface that distinction in Phase 1 Assess briefs as `[VALIDATED — applied in N repos]`.
-
-### Migration — existing memory files
-
-`memory_writer.py migrate` is an idempotent backfill that adds provenance frontmatter to existing memory files. Safe to re-run; skips any file that already has all required provenance keys.
-
-```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py migrate \
-  --run-id "$RUN_ID" \
-  --workdir "$PWD" \
-  --host claude_code \
-  --dry-run    # inspect first; remove the flag to apply
-```
-
-Run once after this version of build-loop is installed; the migration completes immediately for memory dirs of ordinary size (the user's global memory at ~80 files migrates in well under a second).
-
-### Concurrency
-
-- `memory_writer.py write` — atomic tmpfile + os.replace; the memory file IS the lock.
-- `memory_index.py append` — `fcntl.flock(LOCK_EX)` on `INDEX.jsonl.lock`; multi-writer safe across hosts.
-- `memory_update_ledger.py append` — `fcntl.flock(LOCK_EX)` on `updates.jsonl.lock`; append-only and multi-writer safe.
-
-## Append-only milestones (anti-rewrite-drift)
-
-### The problem this solves
-
-"Current state" files that are rewritten in place rot: the writer overwrites without fully reading, summaries drift from reality, and no one can tell which run produced a given snapshot. The fix is append-only by construction — a log that can only grow forward.
-
-### What gets appended and when
-
-Every build-loop run appends a single milestone record at **Review-G** via `scripts/append_milestone.py`. Each record captures what shipped and the repo HEAD sha at write time.
-
-The milestone (durable `milestones.jsonl` in build-loop-memory) is **distinct from** `state.json.runs[]`, which Phase 6 Learn scans for pain signals. The orchestrator's Review-G writes both; an **inline run or the closeout** writes neither unless it calls them explicitly. So at run-close, in addition to the milestone, record the run for Learn with `python3 scripts/append_run.py --workdir "$PWD" --run-id <id> --goal "..." --outcome <done|partial|blocked>` (append-only, idempotent on `run_id`; capture `--manual-intervention "<phase>:<note>"` for any step the user had to re-prompt). Without it, inline work never reaches the `runs[] >= 3` Learn threshold. See `references/phase-6-learn.md` §Detect.
-
-JSONL contract (frozen — sibling staleness-check reads this):
-
-```
-<memory-root>/projects/<slug>/milestones.jsonl
-```
-
-Each line:
-
-```json
-{"ts": "2026-05-30T12:00:00Z", "commit": "<sha>", "repo": "<dir-name>", "summary": "<what shipped>", "run_id": "<id|null>"}
-```
-
-### How to append
-
-```
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/append_milestone.py \
-  --workdir "$PWD" \
-  --summary "feat: shipped auth + dashboard" \
-  --run-id "$RUN_ID" \
-  --json
-```
-
-`--commit` and `--project` override the defaults (git HEAD and slug derived from `--workdir`). `--memory-root` overrides the default `~/dev/git-folder/build-loop-memory`.
-
-Output: `{"appended": true, "path": "...", "line": "..."}` on success; `{"appended": false, "reason": "..."}` on fail-soft (non-git workdir, unwritable root). Exit 0 in both cases.
-
-Idempotency: if the last line already has the same `commit` AND `summary`, the call is a no-op. Safe to re-run on retry.
-
-### The core principle: pointer not duplicate
-
-The milestone log is the **durable, never-rewritten** record of project progress. Other memory files (`lessons/`, `decisions/`, etc.) remain the authoritative content store. The milestone is a pointer — "at this commit, this run shipped this" — not a duplicated copy of their content.
-
-> The rewrite-in-place pattern is what rots. Append-only logs + pointers resist drift by construction: you can always `tail` to see the latest state, `grep` to find when something shipped, and the sibling staleness-check can compare the latest milestone commit against the current HEAD to detect stale memory instantly.
-
-Decisions use the existing `decisions/` lane (also append-only files, one file per decision). The milestone log adds the run-level "what shipped" layer that `decisions/` doesn't track.
-
-### Staleness detection
-
-`memory_staleness_check.py` now prefers the latest `source_commit` in `indexes/updates.jsonl` for the current project, then falls back to the latest milestone's `commit` field. It compares that baseline against `git rev-parse HEAD` in the project workdir. If HEAD has moved past the last memory update by the configured commit threshold, the project's memory is potentially stale and Phase 1 Assess should flag it.
-
-Impact:
-
-- A decision, lesson, migration, mark-applied, or milestone can refresh the memory baseline when it records `source_commit`.
-- Older memory stores without `indexes/updates.jsonl` keep working because milestone fallback is unchanged.
-- A stale warning means "no durable memory update has been recorded for this project at or near HEAD"; it does not prove every individual memory file is stale.
-
-### Concurrency
-
-`fcntl.flock(LOCK_EX)` on `milestones.jsonl.lock` — same pattern as `memory_index.py`. Multi-writer safe.