@tyroneross/build-loop 0.36.0 → 0.43.0

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

@@ -1,96 +0,0 @@
-<!-- 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/plugin-artifacts/codex/skills/build-loop/references/leadership.md

@@ -1,72 +0,0 @@
-<!-- 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/plugin-artifacts/codex/skills/build-loop/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.

package/plugin-artifacts/codex/skills/build-loop/references/modular-systems-pack.md

@@ -1,96 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Modular Systems Pack
-
-Use this pack on every non-trivial build. It makes modular, scalable structure the default while allowing a simpler or more integrated approach when that better serves the use case.
-
-## Default
-
-Build-loop should prefer systems that are:
-
-- **Modular**: each module hides one important design decision behind a stable interface.
-- **Scalable**: the design can grow in data volume, user volume, feature count, or team ownership without immediate redesign.
-- **MECE**: task groups, file ownership, and agent scopes are mutually exclusive and collectively exhaustive.
-- **Pyramid-structured**: plans, handoffs, reports, and repo organization lead with the governing thought, then supporting groups, then details.
-
-This is a default, not dogma. The goal is durable user value, not extra architecture.
-
-## Exception Rule
-
-Do not add modularity for its own sake. Choose a simpler or more integrated approach when:
-
-- The change is a one-off script, short-lived migration, or isolated fix.
-- A new boundary would add indirection without reducing real complexity.
-- A performance hot path needs a tightly integrated implementation.
-- The repo is small and the added module structure would obscure the core workflow.
-- The product need is intentionally limited and extra optionality would confuse users.
-
-When taking an exception, record:
-
-```text
-MODULARITY EXCEPTION: <why simpler/integrated is better for this use case>
-```
-
-## MECE File And Agent Partition
-
-Phase 2 Plan must partition work so every changed file has exactly one owner and every required responsibility has an owner.
-
-For each task group, use this packet:
-
-```md
-Group: <name>
-Dimension: <domain | layer | workflow | bounded context | adapter | test surface>
-Owns files: <paths>
-Does not own: <paths handled elsewhere>
-Interface contract: <exports/events/API/schema it may change>
-Integration checkpoint: <command or review step>
-Intent link: <north-star or user-value rule this group supports>
-```
-
-MECE checks:
-
-- No overlap: a file or interface is not owned by two agents unless the plan defines a handoff point.
-- No gaps: every required behavior, state, migration, test, and user-facing surface has an owner.
-- One dimension per level: avoid mixing domains, layers, and workflows in the same grouping level.
-- Stable interfaces: agents can change internals, but cross-group contracts are explicit.
-- Integration checkpoint: every boundary has a test, build, visual check, schema check, or reviewer step.
-
-## Modular Design Heuristics
-
-- Hide volatile decisions behind small interfaces: data shape, provider choice, algorithm, storage, rendering strategy, or external API.
-- Prefer high cohesion: code that changes for the same reason lives together.
-- Prefer loose coupling: callers depend on published interfaces, not internal data structures or side effects.
-- Design around business/domain capabilities when the system is large enough for domains to matter.
-- Keep boundaries small enough to understand and large enough to own a useful capability.
-- Separate deploy/runtime config from code when values vary by environment.
-- Preserve directness when extra layers make the core workflow harder to read, test, or operate.
-
-## Pyramid Structure
-
-Use pyramid structure for plans, reports, repo notes, and agent handoffs:
-
-1. Governing thought: the one decision, result, or recommendation.
-2. MECE key lines: 3-5 non-overlapping supporting claims or work groups.
-3. Evidence/details: commands, files, risks, interfaces, and validation.
-
-For repo structure, this means names should communicate purpose, folders should group by one clear dimension, and cross-cutting utilities should stay genuinely shared rather than becoming a junk drawer.
-
-## Review Gates
-
-Critic and final review should flag:
-
-- Avoidable tight coupling or weak cohesion.
-- Hidden cross-file ownership overlap between agents.
-- Missing owner for a required behavior, state, migration, test, or user-facing surface.
-- Abstraction added without user, scalability, testability, security, or maintainability benefit.
-- Simplification that collapses a boundary needed for accuracy, security, scale, testability, or future optionality.
-- Missing `MODULARITY EXCEPTION` when the plan intentionally chooses an integrated shortcut.
-
-## Source Basis
-
-- Parnas, "On the Criteria to Be Used in Decomposing Systems into Modules" (CACM, 1972): https://cacm.acm.org/research/on-the-criteria-to-be-used-in-decomposing-systems-into-modules/
-- AWS Well-Architected REL04-BP02, "Implement loosely coupled dependencies": https://docs.aws.amazon.com/wellarchitected/2024-06-27/framework/rel_prevent_interaction_failure_loosely_coupled_system.html
-- Microsoft Azure Architecture Center, domain analysis for microservices: https://learn.microsoft.com/en-us/azure/architecture/microservices/model/domain-analysis
-- Microsoft Azure Architecture Center, design principles for Azure applications: https://learn.microsoft.com/en-gb/azure/architecture/guide/design-principles/
-- Twelve-Factor App config guidance: https://12factor.net/config
-- MECE framework overview: https://www.casestar.io/guides/mece