@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/silent-assumptions/references/elicitation-detectors.md

@@ -0,0 +1,342 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# The eleven detectors, with the real row each was derived from
+
+Every example below is a genuine row from the reference register
+(`.build-loop/decisions/2026-09-01-rosslabs-mockup-audit/` in `ross-labs-astro`),
+which the user ruled on. Where he overrode the default, that is recorded — it is
+the strongest available evidence that the detector found something real rather
+than something tidy.
+
+The detectors work on your trajectory, not on your memory of it. Before running
+them, assemble the concrete record: files read, commands run, tools called,
+figures reported, subagents briefed, fixes landed. Then take each detector to
+that list. A detector you cannot point at a specific trajectory entry for did not
+fire; do not write a row for it.
+
+---
+
+## 1. `ambiguous-term` — a word with more than one defensible referent
+
+**Scan for:** every noun and adjective in the request that could resolve two
+ways. `latest`, `the main page`, `production`, `the tests`, `recent`, `broken`,
+`the config`. Resolve each one out loud and check whether a different resolution
+was equally defensible.
+
+**Stopping rule — materiality.** Applied literally to a 400-word brief this
+yields dozens of terms and drowns the register. Keep a term only when a
+different reading would have changed **what you actually did**. If both readings
+lead to the same action, the ambiguity was never load-bearing. This threshold
+was missing from the first version and an auditor had to invent it; it is now
+the rule, not a judgement call.
+
+**Worked row — `latest`, leverage `high`, still unruled.**
+"I read 'latest mockups' as most recently edited, not most recently chosen."
+File modification time picked an 11-file batch from Aug 31. The gallery's own
+selection record (`.mockup-gallery/selected.json`) pointed at April 2026 picks.
+Two records disagreed and the agent silently trusted one.
+
+**Why it is high leverage:** the whole audit ran on those files. If the referent
+was wrong, every finding describes the wrong artifact.
+
+**The tell:** two sources of truth existed and you consulted one. When a repo
+carries an explicit selection, pin, or lockfile, timestamp recency is a *second*
+answer, not the answer.
+
+---
+
+## 2. `scope-narrowed` — you did N of M and did not say so
+
+**Scan for:** every count you executed against the count available. Files read
+vs files present. Viewports tested vs profiles shipped. Routes, samples, date
+ranges, log lines, test cases. Write both numbers down; the gap is the row.
+
+**Worked row — `viewports`, leverage `med`, user overrode to "add tablet".**
+"I tested two viewports and called that the risk envelope." Scanned at iPhone 14
+and desktop 1440 on the assumption that narrowest-phone and standard-desktop
+bracket the failure modes between them. Evidence names what was skipped:
+`ipad-air`, `ipad-pro-11`, `iphone-14-pro-max`, `pixel-7`. Tablet widths are
+exactly where column counts and sticky headers break.
+
+**The tell:** you described a subset with a word that implies the whole —
+"the mockups", "the viewports", "the tests". Say N of M, or write the row.
+
+---
+
+## 3. `rule-applied-or-waived` — a standard invoked, or passed over
+
+**Scan for:** every project rule, standing instruction, or memory you acted on,
+and every one that applied and you did not. Both directions are silent calls.
+
+**Worked row — `deadbtn`, leverage `high`, user overrode to "expected in a
+mockup", note: "just fix design do not wire buttons if a mockup".**
+"I called the dead buttons real defects, though your own rule exempts mockups."
+The no-fake-buttons rule was applied as if these were shipping pages; the user's
+own instructions explicitly exempt declared mockups and prototypes. Evidence
+names the exact selectors and sizes.
+
+**Why the note matters more than the pick:** the user's note is a standing
+policy for all future mockup work, not a comment on these three buttons.
+
+**The tell:** you enforced a rule without checking its exemptions, or skipped
+one because it felt inapplicable. Cite the rule's own carve-outs.
+
+---
+
+## 4. `tool-output-as-truth` — a tool's model of importance became yours
+
+**Scan for:** every tool whose severity, ranking, score, or verdict you passed
+through unchanged. Then, separately, every scan that returned nothing.
+
+**Worked row — `severity`, leverage `med`, user overrode to "re-rank by user
+impact".** "I accepted the tool's severity ranking instead of ranking by user
+harm." IBR labelled no-handler as error and hick-choice-count as warning; the
+agent reported those labels. But they rank by rule type, not by how badly a user
+is blocked. On mobile the dead menu button removes the only navigation
+affordance on the page, and the tool graded it like any other unwired control.
+
+**The second half, easily missed:** a scan that found nothing is not a clean
+result. Reading silence as a pass is itself a silent call, and it is the one
+that hides broken instruments. In this same session a contrast rule returned
+`null` when it could not measure, and null read as "no failures".
+
+**The tell:** your output inherits a vocabulary you did not choose.
+
+---
+
+## 5. `number-wrong-basis` — a figure whose inputs are assumed
+
+**Scan for:** every number you reported. Name its inputs one at a time and mark
+each measured or assumed. One assumed input contaminates the figure.
+
+**Worked row — `whitebg`, leverage `high`, user overrode to "re-measure now by
+hand".** "I reported zero contrast failures using a number I know is partly
+wrong." Ratios were computed for 29–34 elements per page; where an element had a
+transparent background the agent assumed the page was white. Page 09 contains a
+near-black container, so text inside it was measured against the wrong
+background. Evidence quotes the tool's own semantic warning: page luminance
+1.000, container luminance 0.003.
+
+**The tell:** you know the caveat and reported the number anyway, with the caveat
+in a different paragraph. If the basis is wrong, the row belongs here even when
+you disclosed the gap in general terms — this agent had flagged coverage, but
+not *this specific inaccuracy*.
+
+---
+
+## 6. `invented-context` — you filled a field no source supplied
+
+**Scan for:** every audience, persona, goal, threshold, deadline, priority, or
+success criterion in your output. Trace each to a source. Anything with no
+source, you invented.
+
+**Worked row — `audience`, leverage `high`, user overrode to "panel infers it
+from the page".** "I invented the audience the panel is reviewing for." The
+agent told a five-persona panel the audience was technical practitioners,
+AI-curious professionals, and people evaluating the user's credibility. The user
+never defined an audience. Evidence quotes the dispatch verbatim.
+
+**The user's note is the real payload:** "let them discover and don't lead them"
+— a standing instruction about how to brief every future panel.
+
+**The tell:** you briefed a subagent. Everything in a brief that did not come
+from the user is invented context, and it propagates before anyone can check it.
+This is why invented context is almost always `high`.
+
+---
+
+## 7. `assumed-workflow` — you optimised for a workflow that may not exist
+
+**Scan for:** every optimisation target you chose. Precision vs recall. Speed vs
+thoroughness. Strict vs lenient. Fail-closed vs fail-open. Each implies a
+workflow. Name it and ask whether the user has it.
+
+**Also scan every ordering call:** what you ran in parallel, and what you ran
+before what. Ordering decides what information a later step has. Observed case:
+an agent was told to run a synthesis pass *after* reviewing a second opinion,
+ran both concurrently to save a round trip, and the synthesis therefore never
+saw the input it was supposed to consume. It announced "two things in parallel",
+which surfaced the action while leaving the overridden sequencing invisible.
+
+**Worked row — `recall`, leverage `high`, user overrode to "recall first".**
+"I first optimised for precision, and you corrected me to recall." The agent
+briefed a build to avoid false positives, assuming a CI gate where noise is
+expensive. The user's note: there is no gate; he uses the tool to improve UI by
+hand and would rather catch issues than miss them. Under human triage, silence
+costs far more than noise.
+
+**This row is the reason the skill exists.** The assumption had already shaped a
+code fix's acceptance criteria before it was ever stated out loud.
+
+**The tell:** you can name the cost you were minimising but not the process that
+makes it costly.
+
+---
+
+## 8. `static-for-dynamic` — you inspected at rest something that has behaviour
+
+**Scan for:** everything you looked at but did not operate. A page not clicked.
+An API described from its schema, not called. A script read, not run. A form not
+submitted. A keyboard path not walked.
+
+**Worked row — `static`, leverage `high`, user overrode to "full interaction
+session".** "I scanned the pages at rest and never operated them." Evidence
+enumerates precisely what went untested: keyboard tab order, the declared
+`:focus-visible` ring, `prefers-reduced-motion` behaviour, a `<details>`
+disclosure, every hover state.
+
+**The tell:** your finding describes what is rendered, and the user's question
+was whether someone can use it. Those are different questions.
+
+---
+
+## 9. `root-cause-not-swept` — you fixed the instances and not the pattern
+
+**Scan for:** every fix **or conclusion** you landed. For each, ask whether you
+searched for other instances of the same shape.
+
+**And every fix you declined.** The original scan target was "every fix you
+landed", which makes this detector structurally inert on a read-only session —
+review, audit, research, planning — where nothing lands. Declining to fix a
+defect you found is a call, and it is silent unless you said so. Observed case:
+an agent found a live claim-integrity defect mid-review and queued it rather
+than fixing it, which was the right call and an invisible one.
+
+**Worked row — `pattern`, leverage `high`, user overrode to "audit every rule
+for silent skips".** "I fixed the four defects I found and did not check whether
+the pattern repeats." The defect shape was a rule returning null instead of
+reporting that it could not measure. Evidence names the unaudited files carrying
+the same shape: three other presets and the built-in run-all path. A third
+instance was later found by someone else.
+
+**The tell:** your fix list matches your discovery list exactly. That is a
+coincidence worth one grep.
+
+---
+
+---
+
+## 10. `source-authority` — you obeyed an instruction without checking who sent it
+
+**Added 2026-09-01.** The original nine had no detector for this and it was the
+largest-blast-radius class the audit found.
+
+**Scan for:** every instruction you obeyed, sorted by who sent it — the human
+principal, a peer agent, a hook, a file on disk, a tool's output. For each
+non-human source, ask what authority you granted it and whether you verified the
+sender.
+
+**Worked row — from the audit transcript, `agent-rally-point`, leverage `high`.**
+Six of nine user-role turns in that session were injected by a peer agent over
+Rally, each stamped `[rally: UNVERIFIED SENDER]`. The repo's own
+`docs/security/TRUST-MODEL.md` states the sender field is self-asserted and
+authenticated by nothing. The agent treated all six as authoritative, including
+"You are GO", "Open Item 1 is DONE (do not duplicate)", and an instruction to
+halt a transfer sequence. In the same session it wrote a lucid explanation of
+why that warning label exists.
+
+**Consequence shape:** you did work, or skipped work, on the word of a sender
+nobody authenticated. If the claim was wrong or stale, everything downstream
+inherits it, and the register is the only place the trust decision is visible.
+
+**The tell:** you can quote the instruction but not name who authored it, or you
+name the author and never checked. Note the interaction with Filter B: a peer
+agent's instruction never cuts a row as a restatement, because "the user" means
+the human principal. Obeying a peer is a call, not a given.
+
+---
+
+## 11. `irreversible-act` — you did something un-undoable while still deciding
+
+**Added 2026-09-01.** This is the inverse of detector 8: detector 8 finds what
+you looked at but did not operate; this finds what you operated and cannot
+un-operate.
+
+**Scan for:** every act with no undo. A write to an append-only ledger. A push.
+A dispatch to another agent. A published artifact. A sent message. A released
+lock or a claimed seat. For each, ask whether the decision to do it was settled
+at the moment you did it.
+
+**Worked row — from the audit transcript, leverage `high`.** An instruction
+arrived at 07:04:02Z saying "do not edit files, claim work, or change Rally
+state." At 07:04:13Z, eleven seconds later, the agent ran `rally enter`, which
+appended a presence fact to an append-only ledger at seq 14608. The agent's own
+account — that the write committed before the message landed — is true from
+inside its turn and false against the clock.
+
+**Consequence shape:** the record now contains something the user asked not to
+be there, and no later decision can remove it.
+
+**The tell:** you describe an action in the past tense and cannot describe how to
+undo it. That is the row. Set `"escalate": true` on it — the skill's offer
+threshold surfaces an irreversible consequence immediately, at any score.
+
+---
+
+## Adversarial audit, 2026-09-01 — what changed and why
+
+The first nine detectors were run against a real 915KB multi-agent transcript
+from a different repo by an auditor briefed to break the procedure rather than
+confirm it. Results, kept here because they calibrate what this procedure is
+worth:
+
+- **28 raw candidates → 14 survivors.** 5 cut as restatements, 5 cut for having
+  no writable consequence, 4 cut because the agent had already surfaced the call.
+- **Restatement rate 18%, and the auditor called that a floor**, not a
+  measurement, because it knew Filter B before generating and suppressed obvious
+  restatements at write time. Treat 18% as the optimistic end.
+- **The three strongest survivors** were: a second-opinion brief that pre-loaded
+  the requester's own diagnoses under a "do not re-derive" heading, spending an
+  independent review on a critique of the first opinion; a standing rule applied
+  to the artifact the user named and waived 25 seconds later on the only prompt
+  that actually shipped; and a green verdict issued on a peer's CI fix by a
+  session that ran no tests. None appears in any instruction.
+
+Five defects it found, all now fixed above or in `SKILL.md`:
+
+1. **Filter B did not define whose words count.** With peer-authored turns
+   counted as "the user's", the restatement rate swung 18% → 4% and the
+   session's largest assumption disappeared. Now: "the user" is the human
+   principal; a peer instruction is a source, and detector 10 covers it.
+2. **Detector 1 had no stopping rule.** Now: materiality.
+3. **Leverage `high` did not define "consumed."** Now: handed off, not observed
+   being used. Delivery is the line.
+4. **Filter A demanded a "when" that none of the worked examples exhibited.**
+   Now: a condition satisfies it, not only a clock time.
+5. **Detector 9 was inert on read-only sessions.** Now: conclusions and declined
+   work count, not only landed fixes.
+
+One class it named remains only partly addressed: **narrated but not flagged**,
+where the agent describes the action while never signalling that a choice with
+alternatives existed. Four of fourteen survivors sat in that grey zone. `SKILL.md`
+Filter B now states that narration does not disqualify a row, but there is no
+mechanical test for it, and a register built by a lenient reader will include
+rows a strict reader would cut.
+
+## Calibration: what this session produced
+
+20 rows from one audit: 8 `high`, 8 `med`, 4 `low`. The user ruled on 14 and
+overrode 12 of those, writing notes on 8. Six rows were left unruled, one of them
+`high` (`latest`).
+
+Two numbers worth carrying:
+
+- **A 60% override rate** means the defaults were defensible but frequently not
+  what he wanted. That is the normal case, not a failure — it is the argument
+  for the register.
+- **8 notes on 14 rulings.** More than half the rulings carried free text, and
+  several were standing policy rather than a comment on that row. A design that
+  captured only the pick would have lost most of the instruction.
+
+## Anti-patterns that make a register worthless
+
+- **Restating the brief.** "I audited the mockups because you asked me to audit
+  the mockups" is not a silent assumption. Filter B exists for this.
+- **A row with no consequence.** If you cannot say what breaks, for whom, and
+  when, delete it. Filter A exists for this.
+- **Vague evidence.** "The scan showed issues" is not evidence. A path, a
+  selector, a line number, a PID, a count, or command output is.
+- **Binary options on a non-binary call.** Three of the rows the user overrode
+  had a third option, and he picked the third twice.
+- **Leverage rated by difficulty.** The hardest call in a session is often
+  `low`. Rate by what consumed it.

package/skills/spec-writing/SKILL.md

@@ -31,6 +31,8 @@ A skill that walks a completeness checklist before producing a build-loop-compat
 
 Walk every item before writing a single line of the plan body. For each item, record the answer (or "N/A with reason") inline in a `<!-- checklist -->` HTML comment block at the top of the plan file so the critic can verify it.
 
+> **Architectural-class pre-plan alignment (gated).** When the build is **architectural-class** — it introduces new module boundaries, a schema change, or a cross-surface contract — reach a *shared design concept* with the requester (intent-restatement / brainstorming) **before** the plan asset is created, and carry a **required architecture note** in the plan (goal-level design intent, the boundary/contract being established, and why this shape over the alternatives; link the relevant ADRs from Item 12). Peer-reviewed evidence (ICSE 2026) shows architecture documentation *in the loop* substantially improves functional correctness, architectural conformance, and modularity, and that gated + architecture-anchored spec-driven development reverses the codebase-entropy decay that "never read the code" pipelines cause. For non-architectural changes (isolated fix, single-surface feature), skip this note — it is not a universal gate. Source: `build-loop-memory/research/2026-07-06-ai-coding-fundamentals-and-harness-claims.md` (Claim 3).
+
 ### Item 1 — Auth guard utility
 
 **Prompt:** Name the auth guard utility used by similar endpoints (e.g., `requireAuth` from `lib/api-auth-guard.ts`). Reject "match existing pattern" without naming it.
@@ -161,10 +163,10 @@ For each new POST/PUT/PATCH route: name the validation library and schema file.
 ```bash
 # Verify ID prefixes appear in the plan body
 grep -E "\bU-[0-9]+\b|\bF-[0-9]+\b|\bD-[0-9]+\b|\bS-[0-9]+\b|\bT-[0-9]+\b|\bA-[0-9]+\b" \
-  docs/plans/<feature-slug>.md | head -20
+  .build-loop/plans/<feature-slug>.md | head -20
 
 # Every [P0] line must have at least one T- reference on the same or adjacent line
-grep -n "\[P0\]" docs/plans/<feature-slug>.md
+grep -n "\[P0\]" .build-loop/plans/<feature-slug>.md
 ```
 
 The checklist answer must name at least one full trace chain (e.g., `U-01 → F-03 → D-02 → T-07`). If the spec has no P0 items, write "N/A: no P0 scope."
@@ -178,8 +180,8 @@ The checklist answer must name at least one full trace chain (e.g., `U-01 → F-
 **How to check:**
 
 ```bash
-grep -n "## Spec Object" docs/plans/<feature-slug>.md
-grep -n '```json' docs/plans/<feature-slug>.md | head -5
+grep -n "## Spec Object" .build-loop/plans/<feature-slug>.md
+grep -n '```json' .build-loop/plans/<feature-slug>.md | head -5
 ```
 
 The plan must contain a `## Spec Object (JSON)` section with a fenced JSON block whose top-level keys include `needs`, `features`, and `tests`. If the plan is a one-line doc update with no structured outputs, write "N/A: doc-only change, no spec object required."
@@ -193,9 +195,9 @@ The plan must contain a `## Spec Object (JSON)` section with a fenced JSON block
 **How to check:**
 
 ```bash
-grep -n "blocking-test:" docs/plans/<feature-slug>.md
-grep -n "\[ASSUMED:\]" docs/plans/<feature-slug>.md
-grep -n "## Open Questions" docs/plans/<feature-slug>.md
+grep -n "blocking-test:" .build-loop/plans/<feature-slug>.md
+grep -n "\[ASSUMED:\]" .build-loop/plans/<feature-slug>.md
+grep -n "## Open Questions" .build-loop/plans/<feature-slug>.md
 ```
 
 Each entry in the "Open Questions" section must carry a `blocking-test: T-NN` annotation. Questions without that annotation are invalid — resolve them as `[ASSUMED: ...]` in the spec body instead.
@@ -209,9 +211,9 @@ Each entry in the "Open Questions" section must carry a `blocking-test: T-NN` an
 **How to check:**
 
 ```bash
-grep -n "## ADR-" docs/plans/<feature-slug>.md
+grep -n "## ADR-" .build-loop/plans/<feature-slug>.md
 grep -in "low-reversib\|db choice\|auth provider\|api contract\|public schema" \
-  docs/plans/<feature-slug>.md
+  .build-loop/plans/<feature-slug>.md
 ```
 
 Every "Locked Decision" row tagged as low-reversibility must reference an `ADR-NN` entry. If no low-reversibility decisions exist in this spec, write "N/A: all decisions are reversible."
@@ -225,7 +227,7 @@ Every "Locked Decision" row tagged as low-reversibility must reference an `ADR-N
 **How to check:**
 
 ```bash
-grep -in "Analytical lens:" docs/plans/<feature-slug>.md
+grep -in "Analytical lens:" .build-loop/plans/<feature-slug>.md
 ```
 
 The Locked Decisions section must contain a line matching `Analytical lens: <name>` (e.g., `Analytical lens: QFD — need-to-feature mapping`). If multiple lenses apply, list all. Choosing "none / not applicable" is only valid for trivial patches with no user-facing scope.
@@ -234,13 +236,13 @@ The Locked Decisions section must contain a line matching `Analytical lens: <nam
 
 ### Item 14 — Coding-agent handoff document
 
-**Prompt:** Generate a coding-agent handoff document (`docs/plans/<slug>.handoff.md`) alongside the plan. Aggregates ADRs + Tests + relevant context with explicit pointers ("When implementing F-08, read ADR-002 and satisfy T-19"). The implementer subagent reads the handoff, not the plan.
+**Prompt:** Generate a coding-agent handoff document (`.build-loop/plans/<slug>.handoff.md`) alongside the plan. Aggregates ADRs + Tests + relevant context with explicit pointers ("When implementing F-08, read ADR-002 and satisfy T-19"). The implementer subagent reads the handoff, not the plan.
 
 **How to check:**
 
 ```bash
-ls docs/plans/<feature-slug>.handoff.md
-grep -n "When implementing\|read ADR-\|satisfy T-" docs/plans/<feature-slug>.handoff.md | head -10
+ls .build-loop/plans/<feature-slug>.handoff.md
+grep -n "When implementing\|read ADR-\|satisfy T-" .build-loop/plans/<feature-slug>.handoff.md | head -10
 ```
 
 The sibling `<slug>.handoff.md` file must exist and contain at least one implementation pointer linking a feature ID to an ADR or test ID. If the plan has no P0 features (doc-only), write "N/A: no implementation tasks."
@@ -287,7 +289,7 @@ If the plan adds no UI surface (API/backend only), write "N/A: no UI surface."
 **How to check:**
 
 ```bash
-grep -n "risk_reason:" docs/plans/<feature-slug>.md
+grep -n "risk_reason:" .build-loop/plans/<feature-slug>.md
 ```
 
 If `risk_reason:` is present, its value must be exactly one of the five canonical strings above. Any other value causes a BLOCKER in `plan_verify.py` (rule `risk-reason-invalid-value`). If none of the five applies, omit `risk_reason:` entirely — absent is fine; only invalid values are rejected.
@@ -327,7 +329,7 @@ If no UI surface is in scope, write "N/A: no UI surface."
 **How to check:**
 
 ```bash
-grep -n "dispatch_tier:" docs/plans/<feature-slug>.md
+grep -n "dispatch_tier:" .build-loop/plans/<feature-slug>.md
 ```
 
 Each value must be exactly one of `script | haiku | sonnet | opus | frontier`. Omit the field for an item whose tier is obvious from context; the checks fire only on a declared tier that fights its task description. (`frontier` never trips a sanity WARN — it is the top judgment tier, never a "waste" smell.)
@@ -372,6 +374,80 @@ If the change adds no new external service, write "N/A: no new external service.
 
 ---
 
+### Item 20 — Capability gap map (implementation plans)
+
+**Gate:** this item fires for non-trivial implementation plans: code changes, workflow changes, migrations, API/schema changes, UI surfaces, hooks/watchers, or anything with a multi-step execution table. If the plan is doc-only, config-only, or a trivial local edit, write "N/A: no implementation capability gap."
+
+**Why:** this prevents the planner from describing the desired future while skipping the current source of truth. It makes the build plan answer, explicitly, "what already exists, what target behavior is required, what is missing, and how will we close that gap?"
+
+**Prompt:** add a `## Capability Gap Map` section with one row per capability, workflow, or contract the build changes:
+
+- **Capability/Workflow** — the user or system capability being changed.
+- **Current source of truth** — file, schema, route, test, doc, or explicit "none found" evidence.
+- **Target behavior** — the desired behavior after the build.
+- **Gap** — what is missing, stale, broken, duplicated, or misaligned.
+- **Build action** — the concrete change that closes the gap.
+- **Owned files/contracts** — exact files, contracts, or APIs the work will touch.
+- **Validation** — the test, command, or manual check that proves closure.
+
+**How to check:**
+
+```bash
+grep -n "## Capability Gap Map" .build-loop/plans/<feature-slug>.md
+grep -in "current source of truth\|target behavior\|gap\|validation" .build-loop/plans/<feature-slug>.md
+```
+
+The section should be small enough to guide execution. Do not create a separate gap-closure plan unless the user explicitly asks for a standalone artifact or the gap map is too large for the main plan.
+
+---
+
+### Item 21 — Single-shot build guardrails (implementation plans)
+
+**Gate:** this item fires for non-trivial implementation plans. If there is no implementation task, write "N/A: no implementation tasks."
+
+**Why:** this captures the failure modes that would cause rework before code is written. A good plan should name the constraints that keep the first implementation attempt from drifting, overbuilding, omitting validation, or regressing adjacent behavior.
+
+**Prompt:** add a `## Single-Shot Build Guardrails` section. Each guardrail must be concrete and cite evidence:
+
+- **Guardrail** — the rule the implementer must preserve.
+- **Prevents** — the failure mode it blocks.
+- **Evidence/test** — the command, test, existing file, ADR, or acceptance criterion that proves compliance.
+
+**How to check:**
+
+```bash
+grep -n "## Single-Shot Build Guardrails" .build-loop/plans/<feature-slug>.md
+grep -in "guardrail\|prevents\|evidence" .build-loop/plans/<feature-slug>.md
+```
+
+Reject generic rules like "keep it simple" unless they cite the exact file, scope boundary, or validation that makes the rule enforceable.
+
+---
+
+### Item 22 — Read-before-edit map (implementation plans)
+
+**Gate:** this item fires for non-trivial implementation plans. If there is no implementation task, write "N/A: no implementation tasks."
+
+**Why:** this reduces build-from-memory errors. It tells the implementer which files, tests, contracts, or docs must be read before editing each chunk, and why those reads matter.
+
+**Prompt:** add a `## Read-Before-Edit Map` section with one row per work item:
+
+- **Chunk/Work item** — the commit, feature, or task.
+- **Read first** — exact files, tests, contracts, docs, or search commands.
+- **Why it matters** — the invariant or coupling the read protects.
+- **Edit after** — exact files/directories to modify only after the reads are complete.
+
+**How to check:**
+
+```bash
+grep -n "## Read-Before-Edit Map" .build-loop/plans/<feature-slug>.md
+grep -in "read first\|why\|edit after" .build-loop/plans/<feature-slug>.md
+```
+
+The map must be repo-grounded. "Review existing code" is insufficient; name the files or the command that finds them.
+
+---
+
 ## Frontmatter fields used by routing
 
 These fields appear in plan or chunk frontmatter and affect orchestrator routing decisions. They are validated by `scripts/plan_verify.py`.
@@ -386,7 +462,7 @@ These fields appear in plan or chunk frontmatter and affect orchestrator routing
 
 ## Plan Output Template
 
-After the checklist is complete, write the plan to `docs/plans/<feature-slug>.md` using this structure:
+After the checklist is complete, write the plan to `.build-loop/plans/<feature-slug>.md` using this structure:
 
 ```markdown
 # Plan: <Feature Name>
@@ -409,7 +485,11 @@ Item 14 — Handoff document: <answer>
 Item 15 — Synthesis dimensions: <answer>
 Item 16 — Risk reason: <answer>
 Item 17 — UI input/output contract: <answer>
+Item 18 — Dispatch tier per work item: <answer>
 Item 19 — Env-var manifest: <answer or "N/A: no new external service">
+Item 20 — Capability gap map: <answer or "N/A: no implementation capability gap">
+Item 21 — Single-shot build guardrails: <answer or "N/A: no implementation tasks">
+Item 22 — Read-before-edit map: <answer or "N/A: no implementation tasks">
 -->
 
 ## Goal
@@ -436,6 +516,24 @@ Item 19 — Env-var manifest: <answer or "N/A: no new external service">
 | 2 | feat(...): ... | ... | C1 |
 ...
 
+## Capability Gap Map
+
+| Capability/Workflow | Current source of truth | Target behavior | Gap | Build action | Owned files/contracts | Validation |
+|---|---|---|---|---|---|---|
+| ... | ... | ... | ... | ... | ... | ... |
+
+## Single-Shot Build Guardrails
+
+| Guardrail | Prevents | Evidence/test |
+|---|---|---|
+| ... | ... | ... |
+
+## Read-Before-Edit Map
+
+| Chunk/Work item | Read first | Why it matters | Edit after |
+|---|---|---|---|
+| ... | ... | ... | ... |
+
 ## F-Criteria (functional)
 
 | Criterion | Pass condition | Grader |
@@ -479,9 +577,9 @@ When the checklist surfaces an unknown that cannot be answered from the plan con
 
 Search each of these locations for keywords related to the unknown. Use `grep -ri <keyword>` against each path.
 
-1. `~/.claude/projects/-Users-tyroneross/memory/` — user-global feedback, reference, pattern files
-2. `~/dev/git-folder/build-loop-memory/` — build-loop global memory (if it exists)
-3. `~/dev/git-folder/build-loop-memory/projects/<slug>/` — project-local memory (slug from `derive_slug_from_cwd`)
+1. `~/.claude/projects/<slug-for-$HOME>/memory/` — user-global feedback, reference, pattern files, if present. Claude Code derives the slug from an absolute path by replacing every `/` with `-` (e.g. `$HOME` of `/Users/yourname` → `-Users-yourname`); if unsure, glob `~/.claude/projects/*/memory/` and grep across matches
+2. `<memory-store-root>/` — build-loop global memory (if it exists)
+3. `<memory-store-root>/projects/<slug>/` — project-local memory (slug from `derive_slug_from_cwd`)
 
 **If a feedback, reference, or pattern entry covers the unknown → use it. Mark it `[ASSUMED: from memory/<filename>]`. Done.**
 
@@ -564,7 +662,7 @@ After writing the plan, run both verifiers before returning. Attempt up to 3 fix
 
 ```bash
 python3 ${CLAUDE_PLUGIN_ROOT}/skills/spec-writing/scripts/check_checklist.py \
-  --plan docs/plans/<feature-slug>.md --json
+  --plan .build-loop/plans/<feature-slug>.md --json
 ```
 
 Exit 0 = checklist complete. Exit 1 = items missing — revise the plan's checklist block and re-run.
@@ -573,7 +671,7 @@ Also run the existing plan-verify script:
 
 ```bash
 python3 ${CLAUDE_PLUGIN_ROOT}/scripts/plan_verify.py \
-  docs/plans/<feature-slug>.md --repo "$PWD" --json
+  .build-loop/plans/<feature-slug>.md --repo "$PWD" --json
 ```
 
 Both must exit 0 before proceeding to Step B.
@@ -601,8 +699,14 @@ The critic's output has `strong_checkpoint_count` (its name for WARN findings th
 
 ## Output Convention
 
-1. Write the plan to `docs/plans/<feature-slug>.md` (create `docs/plans/` if it doesn't exist).
-2. Commit on a docs-only commit with subject `docs(plans): draft <feature-slug> spec` BEFORE any implementation branches are cut.
-3. Copy the plan path into `.build-loop/plan.md` (symlink or copy — copy is fine) so Phase 3 Execute picks it up.
+1. Write the plan to `.build-loop/plans/<feature-slug>.md` (create `.build-loop/plans/` if it doesn't exist).
+2. Copy the plan path into `.build-loop/plan.md` (symlink or copy — copy is fine) so Phase 3 Execute picks it up.
+
+A plan is a run artifact, not a published document. `.build-loop/` is gitignored, so
+the plan stays out of the public tree and needs no docs-only commit. When a plan is
+worth keeping past the run, Review-G promotes it to build-loop-memory through
+`scripts/archive_project_plan.py` — never to `docs/`. Writing plans, retrospectives,
+RCAs, or session handoffs into `docs/` puts private working material in a published
+surface; see `references/public-repository-documentation-boundary.md`.
 
 Return the plan path, the checklist answers, and the final verifier JSON to the caller.