@tyroneross/build-loop 0.30.3 → 0.34.0

package/plugin-artifacts/codex/skills/build-loop/references/memory.md

@@ -0,0 +1,297 @@
+<!-- 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.
+
+### 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.

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

@@ -0,0 +1,96 @@
+<!-- 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

package/plugin-artifacts/codex/skills/build-loop/references/output-style.md

@@ -0,0 +1,129 @@
+# Output Style Contract — User-Facing Terminal Output
+
+Final user-facing output (Phase 4 Review-G report, phase status lines printed to the operator's terminal) must be **clear, direct, concise, and free of internal jargon**. This contract is enforced — `scripts/report_lint.py` runs on the draft before the user sees it, and Review-G auto-revises on findings (warn-and-self-heal, never a hard halt).
+
+It extends — does not duplicate — the existing guidance:
+
+- `CLAUDE.md` § "Concise output" — say only what the user needs to decide or act
+- `~/.claude/CLAUDE.md` § "Intentional word choice" — every line must transmit information the reader does not already have
+- `~/.claude/CLAUDE.md` § "Reporting Work" — pyramid-principle headline + verification line + impact-by-size
+
+Scope: **user-facing output only.** Internal agent-to-agent envelopes (subagent return JSON, judge-decisions, run records, MECE briefs) are structured data and stay as-is — they exist for machines, not the human.
+
+## The five rules
+
+1. **Headline = one plain full sentence** stating what changed. First non-blank line. Not a noun phrase, not a telegraph fragment, not a heading.
+2. **Bulleted concrete artifacts.** Below the headline: commit hashes, file paths, issue paths. Concrete things the user can grep, open, or `git show`.
+3. **Substance bullets.** What the change captures or does, in plain language. Optional when the artifacts alone are self-explanatory.
+4. **Validation line, explicit.** Name the exact command, method, or observer that verified the work, with a status marker:
+   - `✅ Verified by <method>` — ran the script, passing test, curl response, IBR scan, demo
+   - `⚠️ Untested — <what couldn't be verified and why>`
+   - `❓ Uncertain — <what's assumed and what would close it>`
+5. **Plain language.** No jargon (see blocklist below). No contrastive pivot (`not X — it's Y`, `isn't X, it's Y`, `not just X but Y`) — state the point directly.
+
+## Jargon blocklist (user-facing only)
+
+These tokens are fine in internal envelopes; they must be translated to plain language in user-facing output:
+
+| Internal token | Plain-language translation |
+|---|---|
+| `GAP-1`, `GAP-N` | Name the actual gap (e.g. "missing auditor dispatch") |
+| `auditor_status: not-run:parent-must-dispatch` | "Auditor not run — parent owes it" |
+| `auditor_status: ran:dispatched-agent` | "Auditor ran" or omit if obvious |
+| `sub-step G`, `sub-step F` | "Final report step", "Auto-resolve step", or omit |
+| `MECE` | "ownership split", "one owner per file" |
+| `envelope` | "return data", "result" |
+| `scope=build` | "full build review" or omit |
+| `suggest_correction` / `yay` / `nay` / `look_again` | "approve", "reject", "needs change", "needs another look" |
+| `Phase 4G` / `Phase 5` | "final review", "iterate step" |
+| `state.json.runs[]` | "run record" |
+| Internal phase codenames (C-HEAL, C-RCA, C-FLOW…) | Describe the behavior, not the code |
+
+## Good — the exemplar (Codex output, captured 2026-06-04)
+
+```
+- ad1ac79a memory(build-loop): capture native ax ui follow-up
+- Issue: dev/git-folder/build-loop-memory/projects/build-loop/issues/bl-native-ax-light-ui-gap-check.md
+- Backlog row added to .../backlog.md
+
+It captures:
+- skills/native-ax-driver/ as the home.
+- IBR as the primary/full verifier, native AX as the lighter gap/fill layer.
+- Blockers: clean main/fresh worktree and recovered AX/screencapture.
+
+Validation passed: python3 scripts/validate_memory_store.py --strict.
+```
+
+Why this is good: plain-sentence headline implied by the commit subject, bulleted concrete artifacts with paths and a commit hash, an "It captures:" substance block, and an explicit validation line naming the exact command. Scannable, direct, no jargon.
+
+## Good — exemplar B (scoped-edit narration, captured 2026-06-06)
+
+```
+Claim is recorded. I'm keeping the edit scoped: selector scoring plus one regression
+test that reproduces "old handoff masks newer targeted inbox/review request."
+[visible actions: git switch -c …, Explored: read/search …]
+The edit is small: add a typed helper for requires_ack evidence, score direct targeted
+artifacts as inbox-doorbell work, and cover it with a regression where a stale handoff
+used to hide the newer message.
+```
+
+Why it's good: declarative state → scope stated plainly with the bug in plain words → the change in one informed sentence.
+
+## Good — exemplar C (closeout note, captured 2026-06-06)
+
+```
+Commit 4392166 is created on fix/actionable-inbox-next. I'm posting the closeout to
+Rally and releasing the two file claims now.
+[visible actions: rally say release …, rally say artifact …]
+```
+
+Why it's good: states the landed artifact (commit + branch) → then the action-in-progress in one plain line.
+
+## Bad — verbose + jargon (rewritten Good)
+
+**Bad (jargon + filler):**
+
+```
+Phase 4G Sub-step G completed for the auditor dispatch ladder. The auditor_status
+field was changed to ran:dispatched-agent based on the GAP-1 contract; the build
+scope=build review-completeness gate passed. We've now wired the MECE envelope
+through the build-orchestrator so it propagates to the runs[] entry. Suggested
+correction verdict from independent-auditor: yay. Want me to push?
+```
+
+**Good (rewrite):**
+
+```
+Auditor now runs on every build commit; the gap where nested orchestrators
+skipped it is closed.
+
+- Commit: 7e54621 fix(audit): close nested-orchestrator audit gap
+- Files: agents/build-orchestrator.md, scripts/audit_before_commit.py
+- Run record: .build-loop/state.json runs[] entry build-2026-06-07-...
+
+It captures:
+- Nested orchestrators now hand the audit back to the dispatching parent.
+- Auditor's approve verdict recorded in .build-loop/judge-decisions.json.
+
+✅ Verified by python3 scripts/test_audit_before_commit.py — 14 passed.
+```
+
+## What stays internal (do not lint)
+
+These are structured data for machines, not user-facing prose:
+
+- Subagent return envelopes (JSON return values, `status: blocked | partial`, etc.)
+- `state.json` writes
+- `.build-loop/judge-decisions.json` entries
+- MECE brief packets between orchestrator and implementers
+- Rally Point post bodies on internal channels (peer-to-peer coordination)
+- `auditor_status` and other machine fields embedded in run records
+
+The lint targets ONLY the final user-facing report markdown + phase status lines printed to the operator's terminal. Inline backtick spans are NOT exempted — if an internal token appears in prose (even quoted), translate it; use a full fenced block only for verbatim code/trace the user should see literally.
+
+## Enforcement summary
+
+- `scripts/report_lint.py <draft.md> --json` runs on every Phase 4G draft
+- Findings are WARN (advisory): the orchestrator self-heals by revising the draft once, then emits it
+- Never hard-blocks a run — worst case is one revision pass
+- The structural lint (`scripts/build_report_lint.py`) keeps running in parallel; it is orthogonal (parallel_batch / merge_plan / evidence triplet shape)

package/plugin-artifacts/codex/skills/build-loop/references/pay-it-forward-arch.md

@@ -0,0 +1,98 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Pay-it-Forward Architectural Posture (full protocol)
+
+> Loaded from `skills/build-loop/SKILL.md` summary. Encodes the user's preference that scalability and product-roadmap unlocks matter more than short-term build velocity when costs aren't prohibitive.
+
+## The rule (verbatim, user-stated 2026-05-11)
+
+> *"I'd rather do a slightly harder thing now to avoid a more painful change in the future if not prohibited by costs or other concerns."*
+
+When a chunk has two viable implementations:
+
+- **Path A** — minimum-viable, working v1, easy to ship now.
+- **Path B** — same user-visible behavior, but extends the typed / structural contract so future surfaces can reuse it.
+
+**Default to Path B** unless one of the explicit gates below blocks.
+
+## Gates (Path B blocked when ANY is true)
+
+| Gate | Condition | Recommendation |
+|---|---|---|
+| **Time-budget gate** | Path B blows the immediate time budget by more than 2× (e.g. requires a schema migration when none was needed for Path A). | Fall back to Path A. |
+| **Missing dep / infra** | Path B requires a dependency or infrastructure not yet in the project. | Fall back to Path A. Note the dep as a roadmap item. |
+| **Missing design decision** | Path B requires a product/architecture decision the user has not yet made (multi-tenant boundary, auth model, etc.). | Fall back to Path A. Surface the decision in the plan's Open Questions section. |
+| **Empty foreclosed-future-capability list** | Path B's "what does this unlock?" list is empty — no named future capability needs the typed contract. | Fall back to Path A. The "flexibility" is speculative. |
+
+## Anti-pattern explicitly excluded
+
+Path B that's flexibility-for-its-own-sake is **NOT** what this rule means. Excluded shapes:
+
+- Plugin/extension systems with no named future plugin.
+- Abstract factories / hook architectures for a single current consumer.
+- Generic event buses for a single producer / single consumer pair.
+- Parameterized configs whose only caller hardcodes one value.
+
+Path B must be tied to a **NAMED** future capability that's in the roadmap, PRD, intent.md, or stated user goal. "Future flexibility" is not a named capability.
+
+## When this fires
+
+Phase 2 Plan must trigger a Path A / Path B comparison for any chunk that touches:
+
+1. **A typed protocol or interface boundary** — engine types, API contracts, DB schemas, message schemas, envelope shapes, MCP tool input/output schemas, agent return contracts.
+2. **User-facing behavior servable by multiple surfaces** — a feature that could theoretically be exposed via chat + voice + native + email + CLI. Even if today only one surface uses it.
+3. **A consumer where the path of least resistance inlines the contract** — prompt templates that embed business logic, route handlers that JSON-shape ad-hoc, single components that own a state machine.
+4. **A schema change** — any addition/modification to a typed boundary (Prisma schema, Pydantic model, TypeScript interface, JSON Schema, Protobuf message).
+
+If the chunk fits NONE of these signals, skip the comparison and proceed.
+
+## How to apply (Phase 2 Plan output)
+
+For each chunk that fires the signal above, the plan must include:
+
+```markdown
+### Path A vs Path B — <chunk name>
+
+**Path A (minimum-viable):**
+- <one paragraph: what gets shipped, where the contract lives>
+- Time estimate: <derived from t-shirt size>
+- Limitation: <what future capability is foreclosed if we go this way>
+
+**Path B (typed-contract extension):**
+- <one paragraph: what gets shipped, where the contract lives>
+- Time delta vs A: <e.g. "+30 min — adds 1 type definition + 1 module boundary">
+- Unlocks (named future capabilities, NOT generic flexibility):
+  - <capability 1, with citation to roadmap/PRD/intent.md>
+  - <capability 2, with citation>
+
+**Gates check:**
+- Time-budget (>2× A)? <yes/no>
+- Missing dep / infra? <yes — name it / no>
+- Missing design decision? <yes — name it / no>
+- Foreclosed-future list empty? <yes — explain / no — list above>
+
+**Recommendation:** **Path B** (default) / **Path A** (because <named gate>).
+```
+
+The orchestrator's default recommendation is **Path B**. User may override to A on plan acceptance.
+
+## Examples (from user's prior decisions)
+
+- **Clarifier flow**: prompt-layer (A) vs engine-typed (B) — Decision Doctor C6b. Path B chosen because typed engine output unlocked voice + native surfaces named in the PRD.
+- **Auth checks**: per-route gate (A) vs middleware abstraction (B). Path B chosen when 3+ routes need the check; Path A when only one route.
+- **Theme**: hardcoded primary color (A) vs CSS-var token scaffold (B). Path B chosen when alt-theme is on the roadmap; A otherwise.
+- **Search results**: route-shape JSON (A) vs typed result schema in `lib/` (B). Path B chosen when a second consumer (chat tool, RSS export) is already planned.
+
+## Phase 4 Review-A Critic check
+
+When reviewing a commit that landed on Path A, the critic asks: did the plan's Path A/B section name a gate that justified A? If the plan lacked the section entirely AND the chunk fits the signals above, flag as a strong checkpoint: **"missing Path-A-vs-B analysis on a typed-boundary commit."**
+
+This is a process check, not a re-implementation request — the commit can still ship on A, but the synthesis decision should be on the record.
+
+## Relationship to existing packs
+
+- **Intent Capability Pack** (`references/intent-capability-pack.md`) — captures user value + non-goals. Provides the named-future-capability list this pack draws on.
+- **UI Input/Output Contract** (`references/ui-io-contract.md`) — names every user input/output. Surfaces the "could be served by multiple surfaces" signal.
+- **Modular Systems Pack** (`references/modular-systems-pack.md`) — MECE/cohesion/coupling defaults. Path B usually advances modularity; Path A often inlines responsibilities.
+
+The three packs together establish *what* the build is for and *how* it should be structured. The pay-it-forward pack establishes *which version* to ship when there's a choice.