@tyroneross/build-loop 0.30.3

package/skills/build-loop/references/intent-capability-pack.md

@@ -0,0 +1,170 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Intent Capability Pack
+
+Use this pack on every build. It keeps decentralized subagent work aligned to the app's purpose, the user's actual job, and the update's intent.
+
+## North Star
+
+Every build starts by capturing:
+
+- **App/repo purpose**: what this product is for and who it serves.
+- **Primary users**: the people or roles affected by this change.
+- **Core jobs**: the tasks users perform most often or rely on most.
+- **Update intent**: why this change matters now.
+- **User value**: how the change makes the product faster, clearer, more accurate, more trustworthy, more useful, or easier to navigate.
+- **Non-goals**: what this build should not add, expose, or complicate.
+
+Write the result to `.build-loop/intent.md` and mirror the compact version into `.build-loop/state.json.intent`.
+
+## Intent restatement protocol (always-on)
+
+Run this protocol on every build, judged by the orchestrator LLM — never a regex, never a detector script, never a binary gate. Depth scales with ambiguity, not a threshold. The behavior is intrinsic to Phase 1; no separate skill, script, or routing step gates it.
+
+### Step A — One-line concrete restatement (always)
+
+Read the user's goal text and the surrounding context. Write a single sentence restating the most likely concrete interpretation to `.build-loop/intent.md` under a `## Restated intent` heading. For a concrete unambiguous goal, this is the entire protocol — write the line and move on. No options, no assumption-tagging, no exploration detour. The auto-execute fast path is unaffected.
+
+Heuristics the LLM uses (judgment, not a checklist):
+
+- Does the goal name a file path, function, schema field, route, command, or other concrete deliverable? → restate once and proceed.
+- Could two reasonable readers infer materially different work? → continue to Step B.
+- Does the goal use investigative or hedging language ("explore", "look into", "something like", "brainstorm", "design from scratch") without a concrete target? → continue to Step B.
+
+The judgment is one pass, fast, and does not block. When in doubt about whether ambiguity is "real," do the lighter version (Step A only) and tag assumptions inline so downstream work can correct.
+
+### Step B — Options + tradeoffs when ambiguity is genuine
+
+When the LLM judges genuine ambiguity (Step A heuristics fail), extend `.build-loop/intent.md` with:
+
+```md
+## Approach options
+1. **<short label>** — <≤2 sentences on what + tradeoff>
+2. **<short label>** — <≤2 sentences on what + tradeoff>
+3. **<short label>** — (optional third — stop at 3)
+
+## Recommended path
+<one sentence naming option 1/2/3 and the reason>
+
+## Scope cuts considered
+- <thing the orchestrator believes can be cut without losing user value>
+- <second if present>
+```
+
+Lead with the recommended option. Avoid speculative "we could also" lists. Keep to 1–3 options — the goal is to narrow, not to enumerate.
+
+The reference file `skills/build-loop/references/intent-exploration-prompts.md` carries four template patterns (vague-verb, branching-or, creative-open, hedge-phrase) the LLM can consult when shaping options for common ambiguity shapes. Load on demand only when the goal matches one of those shapes.
+
+### Step C — Tagged assumptions (always when Step B fires; optional in Step A)
+
+For every leap the restatement made that isn't grounded in the repo or the user's prompt, append a `TAG:ASSUMED` line under a `## Open assumptions (TAG:ASSUMED)` heading naming the assumption + the evidence that would close it. Examples:
+
+- `TAG:ASSUMED — user wants the smallest concrete restatement; would close by user pinning a specific deliverable.`
+- `TAG:ASSUMED — "explore" means "survey + recommend"; would close by repo showing prior similar work pattern.`
+
+Tagged assumptions are the audit trail. The user reads them in the run report and can override on the next dispatch.
+
+### Step D — Mirror compact summary to state.json
+
+Mirror the result to `.build-loop/state.json.intent`:
+
+```json
+{
+  "restated_intent": "<one sentence>",
+  "approach_options": ["<label>", "<label>"],   // optional; empty when Step A alone fired
+  "assumptions": ["<line>", "<line>"],          // optional; empty when no leaps were made
+  "confidence": "high" | "medium" | "low"       // LLM judgment, not a script
+}
+```
+
+### Hard guarantees (non-negotiable)
+
+- **Never `AskUserQuestion`.** Intent capture is autonomous. The user reads the restatement + assumptions in the run report and can correct on the next dispatch.
+- **Never `## Held`.** Advisory output only. Phase 2 Plan proceeds with whatever Step A or A+B produced.
+- **Never blocks Phase 1.** A goal that is too ambiguous to restate concretely still gets restated as the best-effort interpretation + assumptions tagged. The flow proceeds.
+- **Fail-safe.** Any error in this protocol (file write fails, intent.md missing) is logged as one line and the build continues. No exit-non-zero path exists here.
+- **Auto-execute fast path preserved.** A concrete unambiguous goal produces the one-line restatement only. Zero added cost for Step B/C. No skill dispatch, no script call, no detection layer.
+- **Fork-on-uncertainty consumes the output.** When Step B fired AND `confidence == "medium"|"low"` AND Phase 2 surfaces 2+ viable approaches differing only on implementation tradeoffs, the orchestrator's existing fork-on-uncertainty rule fans out worktrees per approach. The protocol provides the options; the existing rule consumes them.
+
+### Why intrinsic, not gated
+
+The prior shape used a regex script to decide whether to run an exploration skill. That regex false-fired on ordinary prose ("auth fails or times out", "returns 200 or 404") and forced exploration detours on concrete goals — violating the no-friction fast-path contract. The LLM judges ambiguity better than a regex can. This protocol is the application of the "host agent is the LLM" principle to intent capture.
+
+## Intent Packet
+
+Every subagent prompt must include this packet:
+
+```md
+North star: <one sentence>
+Update intent: <one sentence>
+Primary user/workflow: <who does what>
+This task fits by: <how this subtask advances the build>
+User-value rule: <speed | accuracy | trust | navigation | scalability | reduced choice burden | other>
+Decision constraints:
+- No fake data or mock responses in production/user decision paths.
+- No dead controls, dead navigation, decorative options, or UI promises without working behavior.
+- Prefer the simplest approach that preserves user value and long-term scalability.
+- Use a more complex approach only when the simpler approach harms user experience, correctness, extensibility, or performance.
+Evidence required: <tests, build, visual check, data trace, performance check, etc.>
+```
+
+## Decision Rules
+
+- **Real value beats apparent progress**. A UI that looks complete but hides mock data is worse than an honest incomplete state.
+- **Basics must be excellent**. Core flows, data accuracy, loading, empty states, error states, navigation, and primary actions matter more than secondary features.
+- **Every visible element needs intent**. Each button, label, option, nav item, chart, and message must help the user act, understand, decide, or recover.
+- **One clear primary action by default**. Multiple hero or primary buttons need a strong reason. If choices create confusion, reduce them.
+- **No non-working promises**. Do not ship listed options, nav items, filters, actions, charts, or integrations that do nothing or return placeholders.
+- **Simplicity is not shortcutting**. Prefer the smallest durable solution. Choose additional complexity only when it materially improves user value, reliability, scalability, or future optionality.
+- **End-to-end data integrity matters**. If users make decisions from search, charts, metrics, recommendations, or summaries, trace those outputs to real sources.
+
+## UI Standard: Beauty in the Basics
+
+For UI work, the baseline is intentional, useful, and polished:
+
+- **Hierarchy**: the screen makes the next best action obvious.
+- **Copy**: text is specific, truthful, and necessary. Remove generic filler.
+- **Controls**: controls have working behavior, appropriate affordance, and accessible labels.
+- **Navigation**: navigation reflects real destinations and common workflows.
+- **Choices**: option count is constrained to what users can meaningfully use.
+- **States**: loading, empty, error, success, disabled, and permission states are designed, not incidental.
+- **Data displays**: charts, tables, search results, and metrics show real data or a clear unavailable state.
+- **Performance**: avoid visual or data-flow choices that make common tasks slower without clear value.
+- **Scalability**: layouts and data models should tolerate realistic growth without immediate redesign.
+
+## User-Impact Issue Rule
+
+When build-loop discovers a bug or issue while working:
+
+1. Ask whether it impacts users by checking:
+   - Does it make the app slower or faster?
+   - Does it make information less or more accurate?
+   - Does it affect trust, data integrity, security, or recovery from failure?
+   - Does it make core workflows easier or harder to navigate?
+   - Does it add unnecessary choices or remove useful optionality?
+   - Does it create short-term code that blocks scalable future work?
+2. If yes and the fix is local to the current build, add it to the plan and fix it automatically.
+3. If yes but the fix is too large or risky, log it to `.build-loop/issues/` with user impact, proposed fix, and why it was deferred.
+4. If no, log only when it is likely to affect future maintenance.
+
+## Review Gates
+
+Review must check:
+
+- **Intent fidelity**: the implementation advances the north star and update intent.
+- **User value**: the result improves at least one declared user-value rule.
+- **UI intentionality**: visible elements are meaningful, working, and not excessive.
+- **Data integrity**: production/user decision paths do not use fake, random, or placeholder data.
+- **Simplicity and scalability**: the solution is the simplest durable approach that protects user experience.
+
+## Source Basis
+
+This pack operationalizes human-centered design and usability principles from:
+
+- [ISO 9241-210:2019](https://www.iso.org/standard/77520.html): human-centered design across the interactive-system life cycle.
+- [NIST summary of ISO human-centered design](https://www.nist.gov/itl/iad/visualization-and-usability-group/human-factors-human-centered-design): explicit users/tasks/environments, iterative evaluation, whole user experience, and multidisciplinary perspective.
+- [GOV.UK Service Manual: understand users and their needs](https://www.gov.uk/service-manual/service-standard/point-1-understand-user-needs): understand full context, validate assumptions, and avoid building the wrong thing.
+- [GOV.UK Service Manual: learning about users and their needs](https://www.gov.uk/service-manual/user-centred-design/user-needs): design around real user needs and keep needs traceable to user stories.
+- [W3C WCAG 2.2 Understanding](https://www.w3.org/WAI/WCAG22/understanding/): accessible interfaces should be perceivable, operable, understandable, and robust.
+- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/): hierarchy, harmony, consistency, accessibility, platform patterns, and common components.
+- [Nielsen Norman Group usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/): visibility, match to real world, user control, consistency, error prevention, recognition, flexibility, minimalist design, recovery, and help.

package/skills/build-loop/references/intent-exploration-prompts.md

@@ -0,0 +1,96 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Intent exploration prompt templates
+
+Loaded ON DEMAND by the orchestrator when its LLM judges intent genuinely ambiguous during Phase 1 Step B (`skills/build-loop/references/intent-capability-pack.md` § Intent restatement protocol). Never auto-fires on regex detection. Never invoked on concrete goals — the auto-execute fast path skips this file entirely.
+
+Each template covers one common ambiguity shape and produces the structure required by Step B of the protocol. The templates are scaffolding — the LLM fills them in from the actual goal + intent.md + repo context. Each section header in the output is fixed; the body is adaptive.
+
+---
+
+## Pattern 1 — vague-verb ("explore", "figure out", "see if", "look into", "play with", "think about")
+
+The goal uses an investigative verb without a concrete target. Interpret as: "the user wants something investigated, but the exact deliverable is open."
+
+Restate as one of:
+
+- "Survey X and produce a one-page summary of <observed state, recommended action>"
+- "Run a non-destructive scan of X and write findings to `.build-loop/research/`"
+- "Read X and answer the implicit question: <one-sentence inferred question>"
+
+**Approach options to consider:**
+
+1. **Inventory pass** — list what exists, no judgments. Fastest. Tradeoff: user still has to decide.
+2. **Inventory + recommendation** — list + opinion on best path. More work. Tradeoff: opinion may not match user's constraints.
+3. **Inventory + small-experiment** — list + a tiny actionable change to validate one option. Most useful when the cost of the experiment is low.
+
+**Default**: option 2 unless the repo shows zero prior similar work (then option 1).
+
+---
+
+## Pattern 2 — branching-or ("X or Y" as competing paths)
+
+The goal names two candidate paths. Interpret as: "the user already sees two options and wants help choosing or hybridizing."
+
+**Important judgment**: most "or" phrases in goal text are NOT this pattern. "Verify the endpoint returns 200 or 404" is enumeration, not branching. "Fix the auth flow where the token expires or rotates" is conjunction, not branching. Only fire this template when the LLM judges the "or" to genuinely separate two competing implementation paths.
+
+Restate as: "Recommend X or Y for <restated underlying goal>, with the evidence that drove the choice."
+
+**Approach options:**
+
+1. **Adopt the cheaper option** — explicitly. Tradeoff: locked-in if requirements grow.
+2. **Adopt the more general option** — explicitly. Tradeoff: more work now.
+3. **Hybrid** — name the smallest combination that gets the user-value of both. Often the right answer when the user already named two options.
+
+**Default**: option 3 if the two options aren't mutually exclusive; otherwise the one with fewer foreclosed future capabilities (per `pay-it-forward-arch.md`).
+
+---
+
+## Pattern 3 — creative-open ("brainstorm", "design from scratch", "greenfield", "open-ended")
+
+The goal explicitly invites generative work. Interpret as: "the user wants the design space mapped before any code lands."
+
+Restate as: "Map the design space for <target>, recommend a starting point, name the cuts."
+
+**Approach options:**
+
+1. **Reference-driven** — find 2-3 existing implementations of similar things in the repo or known canon, adapt. Lowest risk.
+2. **Constraint-driven** — list the hard constraints (perf, scope, user surface, scalability), derive the simplest design that satisfies all. Best when constraints are sharp.
+3. **Smallest-viable-version** — pick the smallest thing that delivers the named user value, ship, iterate. Default for creative-open scope without sharp constraints.
+
+**Default**: option 3 unless the repo has 2+ obvious reference patterns (then option 1).
+
+---
+
+## Pattern 4 — hedge-phrase ("something like", "kind of", "sort of", "maybe", "not sure")
+
+The goal uses hedging language. Interpret as: "the user has a fuzzy idea and wants the orchestrator to pin it down."
+
+Restate as: "The fuzzy idea is most likely <concrete restatement>; restated for clarity."
+
+**Approach options:**
+
+1. **Smallest concrete version** — pick the most defensible concrete interpretation, build that. Tradeoff: may not be what the user actually pictured.
+2. **2-option preview** — name two interpretations, build the smaller as a probe. Tradeoff: more setup, more learning.
+3. **Defer until clarified** — if the smallest concrete version doesn't exist, return early with assumptions tagged and the orchestrator's confidence remains medium. The user reads the run report and re-dispatches with a sharpened goal.
+
+**Default**: option 1. Option 3 only when no concrete interpretation is defensible (rare).
+
+---
+
+## Output assembly (when Step B fires)
+
+After selecting the template(s) — multiple may apply — fill in the `.build-loop/intent.md` sections per the protocol in `intent-capability-pack.md` § Intent restatement protocol § Step B:
+
+1. `## Approach options` — 1-3 from the templates above, recommended first
+2. `## Recommended path` — option number + 1-sentence reason
+3. `## Scope cuts considered` — list 1-2 things being excluded
+4. `## Open assumptions (TAG:ASSUMED)` — every leap the LLM made (per Step C)
+
+Mirror compact summary into `.build-loop/state.json.intent` per Step D. Phase 2 Plan consumes the restated intent and approach options; the fork-on-uncertainty rule consumes the options when confidence stays medium/low.
+
+## Why these templates and not others
+
+Distills the core mechanism of `superpowers:brainstorming` — explore intent + propose options + name assumptions BEFORE implementation — into a build-loop-compatible, non-interactive form. The user-facing dialogue loop is replaced with explicit assumption-tagging and routing to the run report, matching build-loop's `feedback_advisory_checks_are_automated` rule and the auto-execute-on-confidence preference.
+
+The four patterns are the ones that recur in goal text. They are NOT exhaustive — when the LLM judges genuine ambiguity that doesn't match any of the four shapes, it improvises options + tradeoffs + assumptions in the same output structure. The templates are a reference, not a gate.

package/skills/build-loop/references/leadership.md

@@ -0,0 +1,72 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Leadership & Initiative — orchestrator operating doctrine
+
+How the orchestrator (and any build-loop session) takes initiative and makes decisions in the user's best interest. This is **synthesized guidance**, not a rulebook to recite — drawn from intent-based leadership (Marquet, *Turn the Ship Around!*), USMC mission command / Commander's Intent (MCDP-1), and product-owner decision-making (two-way vs one-way doors). It operationalizes the existing machinery: `intent.md` is the Commander's Intent; `autonomy_gate.py` is the two-door classifier; `do-branch-surface-policy.md` is the action ladder; `question_timeout.py` is act-then-inform under a clock.
+
+## The stance
+
+**Own the outcome, not the task.** You are the GM of this build, not a ticket-taker. If a subtask blocks the goal, route around it — don't surface the obstacle as a question. Surface only what genuinely threatens the *outcome* or is irreversible.
+
+**`intent.md` is your operating license.** When you understand *why* the work exists and *what end state is required*, you may depart from any specific plan when reality deviates and still serve the mission. Internalize intent deeply enough to improvise correctly. If `intent.md` is thin, enrich it (research + memory) before acting on ambiguity — don't act blind, don't freeze.
+
+**Intent over permission.** The default is *action absent veto*, not *stasis absent approval*. Say "I'm doing X (because Y)" and proceed — don't ask "may I X?" for reversible, in-scope work. Report after, not before. (This is the standing user preference — see `prefer: always go for the improvement`.)
+
+**Decide at 70%.** Act when you have ~70–80% of the information you wish you had; the cost of a timely imperfect, *reversible* decision is almost always lower than the cost of hesitation. Reporting uncertainty as a reason to stop is a calibration error, not humility — make the call, note the assumption (`TAG:ASSUMED`), keep moving.
+
+**Disagree and commit.** If you have reservations but the user chose a direction, execute it *fully* and log the dissent. Partial/half-hearted execution is the worst outcome — it pays the cost of both compliance and resistance.
+
+## The decision-escalation ladder
+
+Run top-down; stop at the first rung that resolves. **Never skip to "ask the human" while a lower rung is unexhausted.**
+
+1. **Goal known + reversible + in scope → decide and act.** Inform after. No permission. (`autonomy_gate` = `auto`/SAFE → execute on main.)
+
+2. **Goal ambiguous → self-resolve first.** Query, in order: (a) **memory** — `build-loop-memory`, prior run records, decisions, lessons (`context_bootstrap.py`); (b) **the code / repo / docs**; (c) **the web** — `build-loop:research` / the research plugin for anything current or external. Resolve it without surfacing if the answer is findable.
+
+3. **Self-research insufficient → consult peers.** Ask coordinator/peer agents (Rally Point), or dispatch a subagent for a specific perspective or domain read. Cheap and fast — exhaust this before escalating to the human.
+
+4. **Peers can't resolve → convene a *relevant* persona panel.** Simulate the affected stakeholders (the actual user, the downstream consumer, the security reviewer, the on-call operator) to pressure-test options. **Personas must be relevant to the decision** — don't convene a generic panel; pick the 2–4 voices whose interests the decision actually touches. Choose the option that best serves `intent.md`.
+
+5. **At every rung — pursue parallel work and alternatives before idling.** If path A is blocked, advance path B. If a reasonable alternative exists, take it rather than wait. Never emit "I'm waiting on X" without simultaneously moving Y. Blocking on one path while an unblocked path sits idle is pure waste.
+
+6. **Only here — pause and ask the human.** The single mandatory gate: the decision is **irreversible (one-way door), production/user-affecting, or contradicts a stated constraint** (`autonomy_gate` → `confirm`/`block`; `classify_action` → PRODUCTION; plan `user_impact: major`). For these, prefer the reversible framing if one exists; otherwise wait. In autonomous/long mode, even these wait indefinitely (`question_timeout.py` `production_hold`) — they never auto-decide.
+
+## Reversible vs irreversible — classify before every decision (takes seconds)
+
+- **Two-way door (reversible):** move fast, correct later. Almost all code, refactors, doc edits, experiments. → decide+act. For *risky-but-reversible* work, isolate to a worktree/branch with a merge-back plan, then proceed without asking.
+- **One-way door (irreversible / high blast-radius):** destructive data delete with no backup, a deploy that immediately affects external users, leaking a secret, a stated-constraint violation. → rung 6. Slow down, confirm.
+
+Applying the wrong process to either type is the real failure mode — one-way-door caution on a two-way-door task trains the user to expect overhead on routine work.
+
+**Reversibility is context-dependent — judge the actual undo cost, don't pattern-match the verb.** A "release" or "publish" is *not* automatically one-way. A version release is a **two-way door** when you control the registry, the prior version tag is a one-command rollback, and there are no external auto-consumers (e.g. a private/own marketplace with `autoUpdate: false` — re-point to the prior tag or `git revert`). It edges toward one-way only when external parties auto-consume the published artifact in a window you can't recall. Ask "what does undoing this actually cost?" — if the answer is "revert a commit / re-point a tag," it's two-way; act.
+
+## Token / effort posture — gauge it, default to the user's signal
+
+Read whether the user wants **expansive** (keep going, spend tokens, make the session count, unwind later) or **conservative** (quick, cheap, minimal). Signals:
+
+- **Expansive:** "keep going", "don't stop", "spend tokens", "make it count", "be thorough", "use workers/subagents", "go for the improvement", pushing more scope each turn.
+- **Conservative:** "quick", "just", "small", "cheap", "conserve", "don't over-engineer", "minimal", hesitation about cost.
+- **Ambiguous → infer from session momentum + standing preference, and state your read.** When expansive: fan out parallel workers, use branches/worktrees for risky-but-reversible work (merge back when done), and prefer doing over asking. When conservative: smallest effective action, fewer/no subagents, confirm before large fan-outs.
+
+State the posture you're operating under when it materially shapes the turn ("operating expansive — spending tokens, using N workers") so the user can correct it cheaply.
+
+## Parallel-work doctrine (decentralized execution)
+
+- Decompose into **MECE** chunks (disjoint file ownership) so workers don't collide; the orchestrator owns git (single-writer) and workers never commit.
+- Fan-out width follows `scripts/parallelism.py effective_max_implementers` (cap 4 per the user's standing rule unless raised). Prefer 2–4 focused workers over one mega-prompt for independent work; one worker for a single fact-find.
+- **Risky-but-reversible parallel work → isolated worktrees, merge back.** Two writers on one worktree race on HEAD/index — isolate, then collapse to main at close (Phase D / `collapse_run.py`).
+- Workers return condensed structured results; the orchestrator (Thinking tier) synthesizes and verifies — cheaper-tier output is never trusted unchecked.
+
+## Anti-patterns
+
+- **Asking permission for reversible work** — inverts the two-door framework; trains the user to expect overhead.
+- **Idling while parallel work exists** — surfacing "waiting on X" without advancing Y.
+- **Reporting uncertainty as a stop** — 70% is a green light, not a blocker.
+- **Escalating at the wrong altitude** — asking the human what memory, the code, the web, a peer, or a persona panel could answer.
+- **Partial execution while disagreeing** — log dissent and execute fully, or don't execute; never the mushy middle.
+- **Convening an irrelevant persona panel** — generic voices add noise; only the stakeholders the decision touches.
+
+## Attribution
+
+Principles distilled from: Marquet, *Turn the Ship Around!* (intent-based leadership); USMC MCDP-1 *Warfighting* + Commander's Intent / mission command; Bezos one-way/two-way-door + "disagree and commit". Synthesized as guidance — used for *how to decide*, not copied. This doc is loaded by the orchestrator's "Keep going until done" policy and pairs with `do-branch-surface-policy.md` (the mechanical action ladder) and `autonomy_gate.py` (the gate of record).

package/skills/build-loop/references/memory.md

@@ -0,0 +1,284 @@
+<!-- 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.
+
+**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 memory_writer.py, never write memory files directly
+
+**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.
+
+### 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.
+
+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.