--- name: work description: "This skill should be used when executing work plans efficiently while maintaining quality and finishing features." --- ## Anti-bypass protocol (load-bearing — especially Grok Build) You are the **implementation orchestrator** for standalone `/work` and one-shot Step 3: - **FORBIDDEN:** Pushing a branch and reporting "done" without `/review` → `/compound` → `/ship`. - **FORBIDDEN:** Treating `## Work Phase Complete` as a turn boundary when you own the pipeline (see Invocation Mode below). - **REQUIRED (Grok Build):** Invoke `/review`, `/compound`, `/ship` via slash commands — never hand-roll ship steps. - **Deliverable:** merged PR (standalone) or return to parent one-shot (pipeline mode). See `plugins/soleur/lib/workflow-fidelity.ts` (`IMPLEMENTATION_TAIL`) and Phase 4 Invocation Mode below. **"PROPAGATED" IS A MEASUREMENT ACROSS EVERY SITE ASSERTING THE CLAIM — NOT AN OBSERVATION ABOUT THE ONE YOU EDITED.** Grep for the OLD claim after correcting it, never for the new one: a residual count over the new text is structurally blind to the sites still carrying the old. A superseded position survives precisely where prose review does not look — machine-readable frontmatter, an operative conclusion far from the edited paragraph, and a DIFFERENT document citing the old position as its own contrast case — so a corrected document containing an uncorrected field clears both the gates and the review. **A literal grep is the WEAKEST of the three sweeps, and PARAPHRASE is the mode with no coverage** — wrap-insensitivity handles a blockquote splitting a phrase, and neither handles a site that restates the claim in different words. Write the claim as a SENTENCE and grep its paraphrases; the highest-risk position is a `**Prevention:**` line, because that is the part a future session executes. **Why:** #7957 — a sweep that was wrap-insensitive across all 9,684 tracked `*.md` returned 0 for a file it had just corrected, while that file's `## Session Errors` still prescribed "wait for the completion notification" as the remedy for an error it names "Inferred a commit VERDICT". **Why:** #7349 — a legal record's controllership was corrected in prose while its YAML `controller:` field FIFTEEN LINES ABOVE still asserted the superseded position, along with the operative balancing conclusion and a sibling document; the signed-off audit had already recorded that propagation as DISCHARGED. Same shape as the measurement rule below, one level up: that rule protects a number's freshness, this one protects a correction's reach. See `knowledge-base/project/learnings/2026-08-12-every-blocking-finding-was-the-defect-class-the-pr-existed-to-close.md`. **VERIFY A MEASUREMENT ONCE, BEFORE IT PROPAGATES.** When a plan's sweep will write the same measured fact into more than one file, verify it at the granularity you are about to CLAIM it — before the first write, not after the last. A false measurement does not stay where you put it: downstream files, issue comments, and review agents all consume it as fact and build on it, so the cost of correcting it scales with how far it spread, and the correction itself has to be swept. **Why:** #7325 — "cx33 is available in hel1-dc2" was read off a FLEET-WIDE probe and written into 4 files and 2 issue comments. It is false per-datacenter. Six review agents read it and one built its top finding on it (recommending an amendment to a hard-rule exception), so the error had already propagated one level past the diff before a 15-second re-probe falsified it. Project every measurement onto the exact scope you will assert — per datacenter, per host, per environment — and re-probe rather than adjudicating between two readings of the record. **SINGLE-SOURCE THE RATIONALE BEFORE WRITING IT, NOT AFTER REVIEW SAYS SO.** Prose is review surface: every restated paragraph is re-read by every agent and can drift independently. Write the reasoning ONCE at the artifact that owns the decision (the ADR for the element, the resource for the resource) and make every other site a one-line pointer anchored on content, not a line number. **Why:** #7325 — ~300 lines of justification prose across 8 files became the bulk of the review surface for a one-literal change, and two copies of the same probe table DIVERGED INSIDE THE SAME PR (one said "flipped twice", the other "three times") before any reviewer saw them. The review's own conclusion was to delete one copy. A short rationale plus a pointer is both cheaper to review and structurally unable to drift. **A ROLE TEST BUILT FROM AN ABSENCE DOES NOT DISCRIMINATE, AND ITS FIXTURE WILL AGREE WITH IT.** When one artifact is rendered for two roles (a shared bootstrap, a shared workflow, a shared config), scope role-specific behaviour on a POSITIVE identity the role owns — and emit that identity as a field so the consumer can require it rather than infer it. Never scope on "the other role does not have X": you must then prove the negative, and the CI sandbox lacking X will pass the arm you labelled "the other role" while proving nothing about it. Fixture the role that HAS X, with every input present and only the identity differing. **Why:** #7695 gated a destructive-recut input on "is `/mnt/data` a mountpoint", commenting that the co-located web host has no `/mnt/data`; `cloud-init.yml` mounts the workspaces volume there, so the probe would have walked every user's repo tree hourly and shipped a store measurement from the wrong host into a gate whose clearance condition is `0`. See `knowledge-base/project/learnings/2026-09-02-i-built-a-host-discriminator-out-of-an-absence-and-fixtured-the-absence.md`. **ASSERT THE VALUE THAT MUST NEVER APPEAR, AND PUT THE INSTRUMENT UPSTREAM OF EVERY ASSERTION.** When a change exists to guarantee a value never occurs, assert that negative directly over every arm and every field — a positive "is it the token I expect" is satisfied by the correct answer AND by any arm that never reaches the field. Give each suite an instrument self-test that drives its pass/fail helpers once each and refuses to continue unless both counters moved, and report assertion-count floors with `printf` + `exit 1`, never through the helper they backstop (ADR-193). **Why:** #7695 — 16 of 24 mutants survived a 250-assertion battery; three flipped `__UNREADABLE__` to the literal `0` that authorizes a destroy and stayed green, `if eval "$condition"` -> `if true` produced a byte-identical summary line, deleting the entire new block reported `232/232 passed, 0 failed` exit 0, and the sibling suite's floor called the very `fail()` one edit disarms. Same learning file. **THE WRAPPER THAT REPORTS A GATE IS ITSELF A GUARD, AND IT IS THE ONE NOBODY REVIEWS.** The suite under test gets mutation rows, assertion floors and an instrument self-test; the five-line bash that RUNS it and reports the verdict gets none, so the could-not-measure/measured-bad collapse survives there. Three rules: never take a verdict from a PARTIAL artifact, and never from the completion NOTIFICATION either — the notification is authoritative for LIVENESS (has it exited?), never for VERDICT (did it succeed?), and TWO INDEPENDENT mechanisms defeat the verdict reading. (i) Its exit code is that of the LAST command the shell EXECUTED, so a trailing `git log` for convenience becomes the verdict — measured in #7912 (filed as #7957): three commits notified `exit code 0` while `git commit` had returned 1. (ii) A run killed mid-`tsc` by the memory reaper ALSO notified `completed`, with no trailing command involved at all — so ending the string with the command that matters does NOT make the notification trustworthy; a missing verdict line is UNRESOLVED, never a pass. Write the real code yourself — `echo "RC=$?" >> log` IMMEDIATELY after the command whose status matters, before any convenience line, because `$?` binds to the immediately preceding command — and read that; a per-step line is not the runner's verdict either. Never pipe a command whose exit code IS the result (`cmd | tail` takes the pipe's status and destroys the evidence in the same stroke — redirect and read `$?`); and make "the loop ran" observable, because `grep -c` exits 1 on zero matches, so `0 failures` and `0 executions` render identically. Put long-lived logs in the worktree — `/tmp` is swept between turns and leaves the writer holding a deleted inode. **Why:** #7828 — a partial lefthook tail read as "rejected" started a SECOND concurrent `git commit` in one worktree (two writers, one index); `git commit | tail -25` reported success on a failed commit and destroyed the only copy of a 52-minute battery failure, which then had to be re-run; and a fleet loop reported `0 reds` without proving it executed. Seven process errors, one shape — the same shape the PR's own 38 findings existed to remove. #7912 hit the two-writers case AGAIN by a different route: the harness reaped the parent `git commit` and its lefthook kept running, so a retry made two writers on one index. Before any git-write retry, check this worktree for a surviving hook process — a reaped task does not imply a reaped process tree. See `knowledge-base/project/learnings/2026-09-07-every-instrument-i-built-to-check-my-own-work-could-not-tell-clean-from-never-ran.md`. **A DATED record is APPEND-ONLY.** When a plan's sweep touches a probe table, ledger row, dated addendum or post-mortem, correct it by APPENDING a new reading/section that cites the old one — never by editing the old one's body or substituting a cell. Editing in place is what turns a correction into destroyed evidence, and the destroyed datum is disproportionately the one that supported your own claim. Use `## Addendum — YYYY-MM-DD (#N)` or `> **Superseded YYYY-MM-DD (#N):**`, and put the record in the ADR that OWNS the element rather than the one you happened to be reading. **Why:** #7309 — a repin overwrote ADR-143's dated `cx23 = YES — in stock` cell, then asserted "Both read NO here" four lines above it; that deleted `YES` was the only in-repo evidence for the PR's own headline claim, and restoring it made the argument stronger than the one that replaced it. See `knowledge-base/project/learnings/2026-08-06-i-deleted-the-measurement-that-was-my-own-evidence.md`. **BEFORE FIXING A DEFECT CLASS, GREP THE LEARNINGS FOR IT — AND IF IT RECURRED, THE FINDING IS THE PROPAGATION FAILURE, NOT THE DEFECT.** When the fix is a helper, the durable unit is the IMPORT, not the helper and not the write-up: a helper that must be re-derived per file will eventually be re-derived wrongly, and the wrong copy is disproportionately the one that does damage. Strip by PREFIX, never by a hand-listed set of names — a name list is a claim about which values the tool honours, and it is wrong the moment the tool adds one. **Why:** #7822 — a fixture spreading a raw `process.env` into `git commit` under lefthook committed onto the caller's live branch and CONSUMED an in-flight commit (`GIT_DIR` beats `cwd`, and beats `git -C` too). The identical mechanism was already documented five months earlier in the same directory (#1454), WITH two correct working copies in the tree; neither was importable, so neither propagated. The first fix hardcoded six `GIT_*` names — exactly what the prior learning's Prevention section said not to do, unread until after it was committed. Second harm: a case asserting "this directory is NOT a repository" inverts under the inherited variable and proves nothing while staying green. See `knowledge-base/project/learnings/2026-09-04-a-learning-two-working-copies-and-it-still-got-re-derived-wrong.md`. **A YAML `run: |` BLOCK APPLIES NO ESCAPE PROCESSING — VERIFY THE LINE AS THE RUNTIME WILL RECEIVE IT, NOT AS YOU WROTE IT.** A literal block scalar hands the command its bytes verbatim, so a doubled backslash reaches `sed` as a LITERAL backslash: `\\(` is not a capture group in BRE, and the expression silently matches nothing. Nothing rejects it — the step exits 0, the variable is empty, and every condition downstream of it goes false. The same block has two more traps: no line inside it may begin at column 0 (a heredoc terminator or a wrapped quote there ends the block), and a `templatefile()`-rendered one needs `$${…}` for braced shell expansions. So never grade one of these edits by reading it: parse the YAML, extract the command, and run it against a fixture whose correct answer you already know. **Why:** #7500 — a fix hardening `NIC_ALARM_VERDICT` against injection doubled the backslashes in its own anchored `sed`, so BOTH verdicts extracted empty on every run and all four filing conditions went false: the alarm would have filed nothing on any verdict. That is the #7242 "dark on exactly the verdicts it exists to raise" defect, reintroduced by the commit fixing a different defect in the same file, and it was caught by a reviewer re-reading the uncommitted tree rather than by any suite. See `knowledge-base/project/learnings/2026-09-08-every-field-my-alarm-trusted-came-from-the-region-it-did-not-trust.md`. # Work Plan Execution Command Execute a work plan efficiently while maintaining quality and finishing features. ## Introduction This command takes a work document (plan, specification, or todo file) and executes it systematically. The focus is on **shipping complete features** by understanding requirements quickly, following existing patterns, and maintaining quality throughout. ## Headless Mode Detection If `$ARGUMENTS` contains `--headless`, set `HEADLESS_MODE=true`. Strip `--headless` from `$ARGUMENTS` before processing the remainder as a plan path. Pipeline mode (file path detection) already covers all prompt bypasses for work's own prompts — `--headless` is only needed for forwarding to child skills in Phase 4. ## Input Document #$ARGUMENTS **API budget.** This skill executes a work plan iteratively across many phases. Tier A (Agent Teams) carries ~7x per-task token cost; Tier B (Subagent Fan-Out) is moderate; Tier C is single-agent. Total cost scales with plan length, chosen tier, and per-task RED/GREEN/REFACTOR cycles. Soleur does not bill or proxy these calls — Anthropic does, against the key in your session. The Soleur LICENSE (BSL 1.1) disclaims warranty for runtime cost; you operate this loop against your own budget. The tier offer fires inline at the right phase. Decline if running an unfamiliar plan against a tight budget. ## Execution Workflow ### Phase 0: Load Knowledge Base Context (if exists) **Load project conventions:** ```bash # Load project conventions if [[ -f "CLAUDE.md" ]]; then cat CLAUDE.md fi ``` **Clean up merged worktrees (silent, runs in background):** Navigate to the repository root, then run `bash ${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}/skills/git-worktree/scripts/worktree-manager.sh cleanup-merged`. Report cleanup results: how many worktrees were cleaned up, which branches remain active. **Check for knowledge-base directory and load context:** Check if `knowledge-base/` directory exists. If it does: 1. Run `git branch --show-current` to get the current branch name 2. If the branch starts with `feat-`, read `knowledge-base/project/specs//tasks.md` if it exists **If knowledge-base/ exists:** 1. Read `CLAUDE.md` if it exists - apply project conventions during implementation 2. If `# Project Constitution` heading is NOT already in context, read `knowledge-base/project/constitution.md` - apply principles during implementation. Skip if already loaded (e.g., from a preceding `/soleur:plan`). 3. Detect feature from current branch (`feat-` pattern) 4. Read `knowledge-base/project/specs/feat-/tasks.md` if it exists - use as work checklist alongside TodoWrite 4.5. Read `lane:` from spec.md if present. Guard file existence first: ```bash spec_path="knowledge-base/project/specs/feat-${branch_name}/spec.md" if [[ -f "$spec_path" ]]; then LANE=$(awk '/^lane:/ { gsub(/^lane:[[:space:]]*"?|"?$/, ""); print; exit }' "$spec_path") case "$LANE" in single-domain|cross-domain|procedural) ;; "") LANE="" ;; # legacy spec; silent skip in announce *) echo "work: invalid lane value '$LANE' in spec; ignoring."; LANE="" ;; esac fi ``` Lane is **non-binding in skill logic** — `work` code does not branch on `LANE`. Operators MAY use the announced lane as a heuristic when picking work Tier 0/A/B/C in Phase 2; binding behavior is deferred per Non-Goal #2. 5. Announce: ``"Loaded constitution and tasks for `feat-`"`` — append `" (lane=)"` when `LANE` is non-empty. **If knowledge-base/ does NOT exist:** - Continue with standard work flow (use input document only) ### Phase 0.5: Pre-Flight Checks Run these checks before proceeding to Phase 1. A FAIL blocks execution with a remediation message. A WARN displays and continues. If all checks pass, proceed silently. **Environment checks:** 1. Run `git branch --show-current`. If the result is empty (detached HEAD), FAIL: "Detached HEAD state -- checkout a feature branch or create a worktree." If the result is the default branch (main or master), FAIL: "On default branch -- create a worktree before starting work. Run: `bash ${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}/skills/git-worktree/scripts/worktree-manager.sh feature `" 2. Run `pwd`. If the path does NOT contain `.worktrees/`, WARN: "Not in a worktree directory. You can create one via `git-worktree` skill in Phase 1." 3. Run `git status --short`. If output is non-empty, WARN: "Uncommitted changes detected. Consider committing or stashing before starting new work." 4. Probe for stashed changes WITHOUT invoking `git stash` (the `hr-never-git-stash-in-worktrees` hook denies even the read-only `git stash list`). Use `git rev-parse --verify --quiet refs/stash` — a zero exit means a stash exists; WARN: "Stashed changes found. Review stash list to avoid forgotten work." A non-zero exit means no stash; continue silently. **Scope checks:** 5. If a plan file path was provided as input (ends in `.md` or starts with a path-like pattern), verify it exists and is readable. If not, FAIL: "Plan file not found at the specified path." If the input appears to be a text description rather than a file path, WARN: "Input appears to be a description, not a file path. Scope validation limited." 6. Run `git diff --name-only HEAD...origin/main` to identify files that diverged between this branch and main. If output is non-empty, WARN: "Branch has diverged from main in [N] files: [file list]. Consider merging main before starting." If the git command fails (e.g., offline, no remote), skip this check silently. **For plans that edit AGENTS.\* (high-collision file class), `plugins/soleur/skills/ship/SKILL.md` (Phase 5.5 gates), OR any path under `docs/legal/**` / `knowledge-base/legal/**` (legal-doc cross-document gate; weekly compliance PRs collide on the same 4-file set), FAIL HARD instead of WARN — fetch + rebase BEFORE Phase 1 (`git fetch origin main && git rebase origin/main`); sibling PRs landing mid-session reliably obsolete plan-quoted budget baselines and trim-target line numbers. Applying-then-rebasing duplicates sibling work and requires full reassessment.** See `knowledge-base/project/learnings/best-practices/2026-05-20-rebase-before-applying-agents-md-plan-edits.md` and `knowledge-base/project/learnings/2026-05-25-closed-field-list-must-classify-at-value-shape-not-column-name.md` §Session Errors #5 (PR #4351 — 10 commits behind including #4353 legal-doc lockstep; caught at review time, not Phase 0.5). 7. If a plan file was provided (check 5 passed), scan for a `## Domain Review` or `## UX Review` heading (both are accepted for backward compatibility). If NEITHER heading found: scan the plan content for UI file patterns (page.tsx, layout.tsx, template.tsx, .jsx, .vue, .svelte, .astro, +page.svelte, app/, pages/, components/, layouts/, routes/). If UI patterns found, WARN: "Plan references UI files but has no Domain Review section. Consider running /soleur:plan to add domain review before implementing." If either heading IS present: pass silently. **Design artifact checks:** 8. Check if prior phases produced design artifacts. Search the repo for design files matching the feature name: `git ls-files '*.pen' '*.fig' '*.sketch' | grep -i ""` and check `knowledge-base/product/design/` for related files. If design artifacts exist AND the current tasks include UI/page implementation (patterns: `.njk`, `.html`, `.tsx`, `.jsx`, `.vue`, `.svelte`, `pages/`, `components/`, `layouts/`): store the artifact paths as `DESIGN_ARTIFACTS` for use in Phase 2. **Specialist review checks:** 9. If a plan file was provided (check 5 passed) and a `## Domain Review` section exists with a `### Product/UX Gate` subsection: check whether domain leader assessments recommended specialists (copywriter, ux-design-lead, conversion-optimizer) that are NEITHER listed in `**Agents invoked:**` NOR in `**Skipped specialists:**`. If the `**Decision:**` field says `reviewed (partial)`, WARN: "Domain review was partial — some specialist agents failed. Review the Domain Review section before proceeding." If any recommended specialist is missing from both fields: **Interactive mode:** FAIL with message listing the missing specialists and options: (a) "Run \ now" — invoke the specialist agent directly, update the plan file's `**Agents invoked:**` field, then continue; (b) "Skip with justification" — prompt for reason, add to the plan file's `**Skipped specialists:**` field, then continue. **Pipeline mode (headless/one-shot):** auto-invoke each missing specialist agent. If the agent succeeds, add to `**Agents invoked:**`. If it fails, add to `**Skipped specialists:**` with note `(auto-skipped — agent unavailable in pipeline)` and WARN. Do not FAIL in pipeline mode. If all recommended specialists are accounted for (in `**Agents invoked:**` or `**Skipped specialists:**`): pass silently. **UX-skip-on-UI-plan hard gate (within check 9):** Determine "UI plan" by matching the plan's `## Files to Create` AND `## Files to Edit` against the shared UI-surface term list + glob superset (`plugins/soleur/skills/brainstorm/references/ui-surface-terms.md`) — NOT just `*.tsx/*.jsx`. The superset includes `*.njk`, `*.html`, `*.vue`, `*.svelte`, `*.astro`, and email templates, so an Eleventy/Svelte/email UI surface does not slip the gate (`wg-ui-feature-requires-pen-wireframe`). On a UI plan, FAIL when EITHER: (a) `ux-design-lead` appears in `**Skipped specialists:**`, OR (b) the plan has **no `### Product/UX Gate` subsection at all** (the gate was never run). Message: "Plan touches a UI surface but has no committed `.pen` (ux-design-lead skipped or gate never ran). Invoke the specialist or provide an explicit override naming the specific UI surfaces being shipped without review." This overrides the "all accounted for → pass silently" branch. A documented skip — or absent gate — on a UI plan is a process gap, not process compliance. See `knowledge-base/project/learnings/workflow-patterns/2026-05-26-ux-design-review-skip-must-fail-hard-on-ui-plans.md`. **UX artifact commit checkpoint (after each specialist in check 9):** After each specialist agent completes successfully (interactive "Run specialist now" or pipeline auto-invoke), commit the output: 1. Run `git status --short` to discover new/modified files from the specialist 2. Stage specialist output files: `git add ` 3. Commit: `git commit -m "wip: artifacts for "` Each specialist gets its own commit so partial progress is preserved if a later specialist fails. Do not commit on specialist failure. **On FAIL:** Display the failure message with remediation steps and stop. Do not proceed to Phase 1. **On WARN only:** Display all warnings together and proceed to Phase 1. **On all pass:** Proceed silently to Phase 1. ### Phase 1: Quick Start **Pipeline detection:** If `$ARGUMENTS` contains a file path (ends in `.md` or matches a path-like pattern), this skill is running in **pipeline mode** (invoked by one-shot or another orchestrator). In pipeline mode, skip all interactive approval gates and proceed directly. If `$ARGUMENTS` is empty or a plain text description, this is **interactive mode** — keep the approval gates below. 1. **Read Plan and Clarify** - Read the work document completely - Review any references or links provided in the plan - Before proceeding, verify the plan does not contradict conventions in AGENTS.md and constitution.md: file format (markdown tables not YAML), kebab-case naming, directory structure (agents recurse, skills flat), required frontmatter fields, shell script conventions - **A budget you write as a LITERAL is stale the moment a sibling PR moves its base — write it as a delta, and measure the shell rather than assuming it.** Two shapes from one session. (a) An assertion floor, byte cap or count copied into the diff as `47` encodes *today's* base; when a sibling raises the base mid-flight the number is silently wrong and the rebase conflicts exactly where both PRs land. Derive it (`main's floor + 1`), state the increment in the comment, and re-read the base from `git show origin/main:` at ship rather than at plan time — measured, one suite's floor moved 44 -> 46 -> 48 -> 49 over four days across three PRs, and the branch's own in-flight 47 was never a value that shipped, so a literal carried from it would have been wrong in a direction no local test could see. (b) `set -e` does **not** fire on a failing NON-FINAL member of an AND-OR list (`bash -c 'set -e; sh -c "exit 100" && true; echo reached'` prints `reached`), so `setup_a && setup_b` lets a failing `setup_a` fall through into the code under test with its preconditions unmet — which then surfaces as whichever *later* guard trips, asserting a cause that never occurred. Split such pairs into separate statements so each failure aborts with its own rc. **Why:** #7291 — a floor literal and an `apt-get update && apt-get install` both shipped, the second producing a hard FAIL naming a deterministic fixture defect that had not happened. See `knowledge-base/project/learnings/2026-08-16-every-number-i-inherited-was-stale-and-the-panel-found-the-defect-class-inside-my-fix.md`. - **A format captured from the LOCAL toolchain is a claim about a version that may not be the one that ships — diff the pin before depending on it.** When a change makes parsing, matching, or a guard newly dependent on another tool's OUTPUT FORMAT (a runner's summary line, a CLI's table, a compiler's diagnostic), the captures are taken with whatever is installed here, and CI installs whatever the repo PINS. Check them against each other (`.bun-version`/`.nvmrc`/`.tool-versions` vs ` --version`) and, if they differ, re-capture under the pinned version in a scratch install before merging — a format difference turns every CI run into the fail-closed branch, on a version you never observed. State in the artifact which versions the format was verified on, so the next reader knows the claim's scope. **Why:** #7466 — every byte capture, fixture and terminator claim was measured on bun 1.3.11 while CI installs 1.3.14 from `.bun-version`; verified identical only because the shard runner's preamble happened to print the mismatch. Do not let the discovery depend on that. - **Plan-quoted numbers are preconditions to verify, not facts.** When the plan quotes a current measurement (`bun test … reports X`, `wc -c < AGENTS.md = N`, "cumulative ~Y words; ~Z headroom", `git ls-files | wc -l`), re-run the measurement at /work start before depending on it. Plans authored hours-or-days earlier observe a moving target; parallel branches landing in `main` invalidate the measurement. PR #3501 plan claimed `~186 word headroom` against an actual `15` and required inline trim of the gate description. See `knowledge-base/project/learnings/2026-05-10-handshake-schema-drift-and-stale-precondition-budgets.md`. - **A remedy PROPOSED BY AN ISSUE is a claim to MEASURE, not a fix to apply — and a correct diagnosis is what makes the proposed fix go unchecked.** The rule above re-derives plan-quoted *numbers*; this is the same discipline applied to a *remedy*. An issue's diagnosis and its suggested repair are independent claims, and when the diagnosis is obviously right (a reproduced P1, a named file:line), the repair inherits its credibility and nobody runs it. Before implementing an issue's prescribed fix, expand/execute it in the failing condition and confirm it changes the outcome — for a path/anchor/env remedy that means printing what it actually expands to on the target surface, not on yours. **Why:** #7442 — the issue correctly diagnosed CWD-relative producers executing a customer's same-named file, then proposed `${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}`; the variable is unset in bash, so the `:-` default expands to `./plugins/soleur` — the defect itself. Measuring the remedy (~30s) is what caught it, and the same PR then shipped an unmeasured safety claim about its *replacement* that review falsified. See `knowledge-base/project/learnings/2026-08-11-i-measured-the-issues-remedy-then-asserted-my-own-without-measuring.md`. - **A plan premise you REFUTED is only refuted against the SHA you checked — re-check refutations after the ship-time rebase, not just re-derive counts.** The stale-number rule above runs one direction (the plan claimed X, X has since changed); this is the inverse, and it is the one that reads as diligence: you verify a plan-asserted defect does not exist, correctly decline to file it, and a sibling PR merging mid-session then CREATES it. The rebase that brings siblings in is exactly the event that can manufacture the condition you ruled out, so a refutation recorded at Phase 0 is stale by Phase 5 on a fast-moving `main`. Cheapest gate: re-run the refuting command after the final rebase for any premise you declined to act on. **Why:** #7160 — a deferral claiming [scripts/test-all.sh](../../../../scripts/test-all.sh) carried a stale "21 suites" header was correctly refuted (no numeric suite claim existed anywhere in the file), and #7146 merged that exact line an hour later. See `knowledge-base/project/learnings/2026-08-03-my-guards-error-channel-was-published-before-its-writers-ran.md`. - **Before concluding from a measured delta, state the harness's NOISE FLOOR and check the SIGN — a delta smaller than the noise is UNRESOLVED, never zero.** Re-deriving a plan-quoted number (rule above) fixes staleness, not statistical power — and fixing the *known* flaw in a harness is exactly when the unexamined one ships: interleaving A/B arms removes drift **bias** but adds no **resolution**, so a "corrected" harness feels trustworthy while still noise-dominated. Two gates before any measurement-driven decision: (a) compute the run-to-run spread and compare it to the effect — if `|delta| < spread`, report "this harness cannot resolve it" and measure the PRIMITIVE that changed instead (25 reps of the one `cp`/`diff`/parse has negligible variance where a whole-suite run does not); (b) ask whether the SIGN is physically possible — a result showing strictly-less-work as *slower* is a broken instrument, not a finding. When the decision is right for a non-timing reason (coverage, correctness, blast radius), justify it that way and drop the number entirely. **Why:** #7001 — a plan-mandated fast path was removed on a 5-pair whole-suite A/B reading 6.86s WITH vs 6.60s WITHOUT; the real effect is ~89ms against a ~±590ms (1σ) floor needing ~160 pairs, and the sign was impossible. The removal was correct on coverage grounds alone. See `knowledge-base/project/learnings/2026-07-27-my-ab-could-not-resolve-the-effect-i-concluded-from-it.md`. - **Name both A/B arms literally and check one against `main` — every other rigor check protects the SUBJECT of a measurement, and nothing protects its REFERENT.** Interleaving, noise floors, sign checks and rep counts all interrogate how well you measured *the two things you chose*; none asks whether either is the status quo. When a change is built in stages the natural comparison is stage-N vs stage-N+1 ("do these excludes earn their place?"), which is a legitimate question whose number has the identical shape to the one a PR body actually claims ("is this better than today?"). Before reading any delta, write out `arm A = `, `arm B = `, and answer *which one runs on `main` right now*; if the answer is "neither", the result can support a claim about a choice INSIDE the change and none about the change. The status-quo arm usually has to invoke the real thing (`exec -a ugrep "$CLAUDE_BIN" …`), not a reconstruction of its flags. **Why:** #7165 — a carefully-run interleaved benchmark (noise floor stated, cold rep excluded, sign checked, and it even corrected the plan's figure downward) compared new-without-excludes to new-with-excludes and shipped a **2.25x regression as a win**; the three-arm re-run showed today 243 ms vs new 548 ms, with the dominant term the single-threaded-engine swap rather than the `.gitignore` loss the spec blamed. See `knowledge-base/project/learnings/2026-08-03-my-ab-had-the-wrong-baseline-arm-so-i-shipped-a-regression-as-a-win.md`. - **A plan-quoted tool-flag VALUE/UNIT is a claim to verify against the PINNED tool's source/`--help` — the unit is the highest-risk part.** When the plan names a CLI/config flag value (`--postgres-conn-max-idle-time 30`, a timeout, a size, a percent), resolve the pinned version and read that version's flag registration for type + **unit** + default + validation before writing it — a wrong unit (minutes/seconds/ms, bytes/KB, count/%) passes typecheck AND the binary's own validation, so only the source catches it. The plan is authoritative for *intent* (e.g. "drain idle conns fast"), never the literal value. **Why:** #6258 — the plan's `SECS=30` for `--postgres-conn-max-idle-time` was seconds-intent, but the inngest v1.19.4 flag is an IntFlag in MINUTES (default 5) → `30` = 30 min, defeating the drain; corrected to `1`. See `knowledge-base/project/learnings/best-practices/2026-07-09-plan-quoted-tool-flag-value-and-unit-are-claims-verify-against-pinned-source.md`. - **A vendor error that CLEARS ON RE-RUN is two hypotheses, and one follow-up probe cannot separate them — read the response HEADERS before writing down "transient".** Vendors retire APIs behind scheduled BROWNOUTS: the endpoint serves the error for a window on a recurring schedule and 200 the rest of the time, so a re-probe minutes later returns clean whether it was restored or merely outside the next window. Both readings fit and the reassuring one gets recorded. Capture headers on the failing call (`curl -D `, never body-only) and treat a deprecation/sunset header on a **successful** response as the durable signal — it is served on 200s too, which is the half that is always observable. Never retry a `410`: a retry long enough to swallow a brownout necessarily also masks the permanent post-sunset case the check exists to catch. **Why:** #7590 — a 2026-07-17 session re-probed a `410`, got a clean plan, and wrote "the 410 was transient" into `versions.tf`; the endpoint had been deprecated since 2026-05-14 and the 410 carried `x-sentry-deprecation-date` + `x-sentry-replacement-endpoint` all along. Measured in BOTH states inside one session on 2026-08-19 — 410 at ~20:5x, 200/200/200 at 21:23, same token, same host, no change on our side. See `knowledge-base/project/learnings/integration-issues/2026-08-19-a-vendor-brownout-is-not-a-flake-and-the-header-said-so-all-along.md`. - **Plan hypotheses about a symptom's mechanism (and its route/file classifications) are starting points, not the work-list — trace the ACTUAL producer before coding.** For a symptom-named bug (a 404, an empty state), grep the literal producer (`notFound()`, the `404` response, the empty-state component) and walk the redirect/call chain to the exact determining condition, confirming or falsifying each plan hypothesis against code. Code-tracing is a valid substitute for a plan-prescribed live repro when the repro needs hard-to-synthesize state. Verify route classifications by reading the route's exported HTTP methods (a "read route" with no GET is a write route). **Why:** #4543 follow-up — the plan's two 404 hypotheses + its "redirect lands on /dashboard" reconciliation were all wrong; a 4-file trace (`invite-actions` → `settings/team/page.notFound()` → null-org resolver → `accept-invite` never set active workspace) found the real cause. See `knowledge-base/project/learnings/bug-fixes/2026-06-01-symptom-root-cause-trace-the-actual-redirect-not-the-plan-hypothesis.md`. - **A short-circuit guard that returns early to skip a code path must sit AFTER any recovery mechanism that lives inside that path.** Before adding a "detect bad state → skip the expensive path → show a fallback" branch where the plan prescribes a placement, grep for where the *recovery* for that bad state actually runs; if recovery is entangled inside the path you're skipping, the early-return amputates it and dead-ends the user. An honest "X is gone" fallback is a *post-recovery-failure* concept — placing it pre-recovery makes the message a lie in exactly the recoverable case. The placement-time companion to "trace the ACTUAL producer". **Why:** #5240 — the plan's pre-dispatch `.git` probe (FR2/FR3) would have skipped the in-dispatch `ensureWorkspaceRepoCloned` self-heal, dead-ending connected-repo resume; reverted + descoped. See `knowledge-base/project/learnings/best-practices/2026-06-14-short-circuit-guard-must-sit-after-the-recovery-it-gates.md`. - **A fail-loud/short-circuit guard for state-class X must not nest under a precondition that only holds for a DIFFERENT state class — and a self-noticed plan-vs-goal gap gets fixed at write-time, not deferred to review.** When the plan nests "flag bad-state X and refuse to proceed" inside an enclosing gate you inherited from an adjacent branch (a staleness/age check, an auth check, a size check) that belongs to a *different* state class, the guard silently narrows to "refuse only when X *also* satisfies the unrelated gate" — undercutting the plan's own stated goal. Ask: does the enclosing condition belong to the SAME class the guard protects? If you notice the gap while coding, fix it inline (a ≤10-line correctness fix is not an architecture fork — reserve CTO routing for genuine forks); implementing the plan's literal placement and waiting for review to catch it is the wasteful path. **Why:** #5907 — the non-regular-lock `UNREMOVABLE` emit was nested under the regular-lock staleness gate, so a *fresh* non-regular `config.lock` slipped straight into the doomed `git config` EEXIST write; 3 review agents converged on a gap noticed at write-time. See `knowledge-base/project/learnings/best-practices/2026-07-02-fail-loud-guard-must-not-nest-under-a-different-state-class-gate.md`. - **A RIDER recorded against a pending event is only as live as its VEHICLE — and a probe that measures delivery cannot tell "not yet" from "the vehicle already departed."** When a change ships inert and its delivery is booked onto a future event (a host replace, a migration window, a cutover), the rider has TWO operands and every gate reliably watches only the change. Before reading a follow-through's `not_delivered` as "still waiting", re-check the vehicle: `gh issue view --json state` plus its closing comment, because a CLOSED ordered path is the signal the rider is spent, not the probe. Better, state the falsification condition when recording it (*"if #N closes without this delivering, the rider is spent"*) so it is checkable rather than implicit. Corollary for the correction sweep afterwards: **index by CLAIM, not by literal** — three engineering-corpus literals returned 0 across `knowledge-base/legal/` and that zero was read as "not relevant", while the claim as the legal corpus phrases it returned 4; the same bound missed the ORIGIN text on punctuation alone (backticks around the command; `INERT UNTIL PROVISIONED` ≠ `… A PROVISIONING`), and correcting every paraphrase while leaving the origin standing makes the repo self-contradictory where it was merely stale. **Why:** #7455 — the rider rode a step-6 replace that had fired ~45h BEFORE the shipper merged, so the change sat inert on a host born before it existed and the probe would have reported `not_delivered` accurately for the full 90-day horizon. See `knowledge-base/project/learnings/2026-08-13-a-rider-is-only-valid-while-its-vehicle-is-still-pending.md`. - **On resume, a `session-state.md` `### Decisions` entry is INTENT, not an accomplishment — verify each against the live artifact before treating it as done.** The section is written in the past tense by a session that was still mid-flight, so a decision reading "met the intent via a correcting comment on #N" / "filed the follow-up" / "re-titled the issue" records what the author RESOLVED to do, and the step is exactly what a mid-task death (API timeout, compaction, crash) leaves undone — the resume then inherits the *claim* without the *act*. Cheapest gate: for every Decisions line naming an outward-facing artifact, probe it (`gh issue view N --json comments --jq '[.comments[]|select(.body|test(""))]|length'`, `gh issue view N --json title`, `ls `) and re-open it in the task list on a zero. This is the outward-facing sibling of the artifact rule below (which covers FILES the contaminated session wrote); a GitHub comment leaves no working-tree trace at all, so nothing else surfaces its absence. **Why:** #6497 — `session-state.md` recorded a #6416 correcting comment as met; `gh issue view 6416` showed ZERO comments citing #6497, and the resumed session nearly shipped the claim in its PR body. See `knowledge-base/project/learnings/2026-07-16-a-mutation-battery-only-covers-what-you-mutate.md`. - **On resume, prior-session artifacts are UNVERIFIED — not work-in-progress to extend.** When `session-state.md` documents that the originating session's tool layer was contaminated/degraded (batched output, warnings prepended to `Read` results), the contamination taints every FILE that session wrote, not just the status claims it retracted ("applied"/"GREEN"). Re-derive each artifact from its authoritative source: read the real migration/file it claims to mirror and rewrite it as a verbatim delta (diff to prove byte-identity), then re-establish status from scratch (apply + verify the live DB; re-run RED→GREEN). For SQL, a misread `RETURNS` type is a free tripwire — `CREATE OR REPLACE` cannot change a function's return type, so any "applied GREEN" against a return-type-changed body is self-evidently false. **Why:** #4709 — 089 was authored against a misread of 088 (`RETURNS void` vs `integer`, dropped NULL-auth + 22023 gates); caught only by reading the real 088 body. See `knowledge-base/project/learnings/2026-06-01-resumed-session-artifacts-from-contaminated-tool-layer-are-unverified.md`. - **Counts written into the artifact (workflow header, script comment, AC expected-N) must be derived from the as-written file, not from plan-prose estimates.** Plan §Phase X says "~40 resources after expansion" → /work runs the grep → the actual count goes into the workflow header comment AND into AC4's expected N. Cheapest gate: after writing the artifact, re-run the canonical count command against the as-written file (`grep -cE '^[[:space:]]+-target=' `, `wc -l `, etc.) and copy the integer into every comment/AC reference. Plan-prose mental tallies drift by ±1-2 during expansion; multi-agent review reliably catches it (P3 polish) but the inline grep at write-time is free. **Why:** PR #4122 — workflow header carried "68 explicit targets" from plan §Phase 0.3 mental tally while `grep` returned 67; caught by `code-quality-analyst` + `pattern-recognition-specialist` at review. See `knowledge-base/project/learnings/best-practices/2026-05-20-plan-time-pr-vs-issue-disambiguation-and-self-derived-counts.md`. - **Re-running the count is necessary but NOT sufficient — publish the COMMAND next to the number, because a prose predicate does not pin a count.** Stating the filter ("N sites, where site = ``") reads like rigour and is not: the prose leaves per-line-vs-per-match, unique-vs-all, marker position, and language-correct-markers free, each worth 10–30%. A number pinned to prose rots exactly like a citation pinned to a line number — both name a referent without fixing it — so the fix is the same: anchor on content (the command), not on a description. If the figure is load-bearing, also show the conclusion survives the plausible range. **Why:** #6517/PR #6527 — a reviewer *measured* and adopted "**403**, where site = a line in a code file bearing a comment marker AND citing `.:`" as canonical; at /work, **18 faithful readings of that exact prose returned 319–583 and never 403** (two independent resolvers also disagreed on the sibling counts). Shipped as `~360` + a `git grep … | wc -l`; the conclusion was invariant across the whole range (0.17–0.31%), which is *why* the false precision survived a 5-agent panel — nothing depended on it. See `knowledge-base/project/learnings/2026-07-16-advisory-first-precedent-is-a-claim-to-measure-and-a-coordinate-citation-carries-no-claim.md` Session Errors #3. - **Verify an AC by running its LITERAL command — a normalized variant verifies a different, weaker claim.** When self-checking acceptance criteria, it is natural to "helpfully" widen the plan's grep (add `-i`, alternate a second spelling, swap a space for `.`), and the widened form is a DIFFERENT predicate: it can pass while the AC's own bytes fail. The AC is the contract and the plan-quoted command is part of it, so paste it verbatim; if it fails, fix the artifact or amend the AC explicitly — never quietly satisfy a looser one. Same family as `cq-assert-anchor-not-bare-token` (anchor on what is actually asserted) and the plan-quoted-number rule above (re-derive, don't restate). **Why:** #6178/PR #6933 — AC9's `grep -c 'function discovery'` was self-reported satisfied after running `grep -c 'function.discovery\|FUNCTION-DISCOVERY'`; the literal command returned **0**, and a checked `tasks.md` line already claimed every AC baseline had been re-confirmed. See `knowledge-base/project/learnings/2026-07-25-i-added-the-field-that-closes-the-gap-and-nothing-read-it.md`. - **Discrete-enumeration re-lockstep (when applicable).** When the plan asserts paraphrased lockstep across discretely-enumerated documents — e.g., "files in lockstep at sections (a)-(N)", "all 7 entries match in both files", "list is (i) through (v) on both sides" — run a fresh `grep -cE '^- \*\*\([a-z]\)\*\* '` (or equivalent, using `[a-z]` NOT `[a-N]`) across each file BEFORE the first letter-inserting Edit. Counts AND letter-sets must match; anything else means the plan's lockstep claim is paraphrase-from-stale-read. PR #3755 (#3708): plan asserted DPD §(a)-(k) lockstep; canonical actually had §(l) DSAR; AC1 caught the §(l) collision but the cheaper gate is re-lockstep at /work-start. See `knowledge-base/project/learnings/2026-05-14-discrete-enumeration-relockstep-and-pr-introduced-asymmetry.md`. - **Sequential-section insertion anchor.** When inserting a new `### N.M`-numbered section, the Edit anchor MUST target the LAST `### N.M` block before the desired slot (not the lexically-adjacent one). Confirm with `grep -nE '^### [0-9]+\.[0-9]+ ' | tail -3`; the new `M` must be greater than the picked anchor's `M`. PR #3755 (#3708): §5.10 was anchored on §5.9-Resend's block start and landed BEFORE §5.9. One-grep prevention. Same learning file. - **Write-boundary sentinel sweep (when applicable).** If the plan introduces a sentinel/guard that asserts a property at write sites (e.g., `assertWriteScope` for cross-tenant integrity, GDPR write-boundary checks), enumerate ALL write sites where the property applies — not just diff sites. Run `git grep -nE '\.from\(""\)\.insert\(' ` (or the equivalent for the boundary type) at Phase 0 and verify every match is sentinel-gated, then file follow-up tasks for any uncovered sites BEFORE entering Phase 1. See `knowledge-base/project/learnings/2026-05-12-type-widening-cascades-and-write-boundary-sentinels.md`; hard rule `hr-write-boundary-sentinel-sweep-all-write-sites`. **Why:** PR-A2 #3603 — sentinel placed at assistant-row write but not user-row write at `cc-dispatcher.ts:1008`; same service-role-bypass surface. - **Type-widening cross-consumer grep (when applicable).** When the PR widens a producer-side shared type whose payload crosses an `unknown`/`any`/jsonb boundary (compiler cannot enforce optionality at the consumer), `git grep -nE '' apps/` across every consumer and verify each respects the new optionality. For `Message`-class fields the canonical grep is `git grep -nE '\bmessage\.usage\.(input_tokens|output_tokens|completed_actions)\b' apps/` (adapt per field family). See learning `2026-05-12-type-widening-cascades-and-write-boundary-sentinels.md`; hard rule `hr-type-widening-cross-consumer-grep`. **Why:** PR-A2 #3603. - **Id-shape/format-guard fixture blast-radius (when applicable).** When the PR adds a shape/format guard (UUID allowlist, regex, length check) to an id that is DB-sourced AND flows through a shared resolver (`workspacePathForWorkspaceId`, an active-workspace resolver, any `join(root, id)` path builder), the guard THROWS on every test fixture that fabricated that id with a short non-UUID literal. Before sizing the change as "1 file", grep the fixture surface — `git grep -nE '"(user-1|ws-[A-Za-z0-9]|owner-[A-Z]|[a-z]+-workspace)"' apps/web-platform/test/` — and trace which hits reach the guarded function; size the fixture sweep at plan time, not at GREEN. The fix is realistic UUID fixtures (`cq-test-fixtures-synthesized-only`), never a looser guard. **Why:** #5344 — a "1 source + 1 test file" estimate broke ~34 fixture files. See `knowledge-base/project/learnings/2026-06-15-id-shape-guard-test-fixture-blast-radius-and-syntactic-sast.md`. - **A PATH-shimmed fake that dispatches on `$1` only puts the fixture seam ABOVE the code under test — assert the argv the SUT must send.** When a suite stubs an external CLI (`docker`, `gh`, `psql`, `curl`), a stub that returns a fixture regardless of `--filter`/`--format`/subcommand cannot detect the SUT querying the WRONG thing, so the query shape ships unpinned: measured, switching a gate from `.NetworkSettings.Ports` to `.HostConfig.PortBindings` and corrupting its label selector (so it matched zero rows and passed forever) BOTH left a 12/12 suite green. Make the fake `exit 64` on a missing required flag, and key multi-entity output per id (`FIXTURE_`) so an early-`break` is detectable — a fake that answers identically for every entity makes "one clean, one dirty" fixtures impossible. `.claude/hooks/stub-argv-fidelity.test.sh` codifies this class but scopes to `.claude/hooks/` with `STUB_CMDS="gh|jq|git"`, so a stub elsewhere is unguarded. **Why:** #7081 — 11 of 17 mutations survived. See `knowledge-base/project/learnings/2026-07-30-every-green-signal-i-had-certified-a-gate-with-six-fail-open-paths.md`. **The same seam also sits above every property the VENDOR validates, so an external-API client needs one verification on the REAL request path.** The rule above pins the argv the SUT sends; this is the half nothing local can reach. A fake that answers regardless of the request cannot observe request ENCODING, parameter FORMAT, header shape or auth form — and a mutation battery cannot either, because it perturbs the SUT and then scores it THROUGH that same fake, so every row is judged by an oracle blind to the class. Exercise the real path once, end to end, with the CLIENT's own argument construction; probing the endpoint with hand-written arguments probes the endpoint. Then teach the stub to reject what the vendor rejects, one exit code per contract violation. **Why:** #7706 — `to_iso` emitted a timestamp with no timezone designator, which the vendor answers with HTTP 400 on EVERY ref, window and source, so the tool could not complete one live query; green through 3 suites, 2 batteries reporting no survivors, 12 review agents, shellcheck and actionlint, and the plan's own live probes missed it because a hand-written curl carries the `Z` by reflex. See `knowledge-base/project/learnings/test-failures/2026-09-02-my-fake-curl-put-the-seam-above-everything-the-vendor-validates.md`. - **A finding names an INSTANCE; the fix is scoped to the CLASS — enumerate all sites {A,B,C} BEFORE writing it.** When a review finding says "X can be added at site A", the work is not "fix A". It is: name the property X violates, enumerate every site that can reach the same sink, THEN fix. Record the enumeration AND the command that produced it (`git grep -nE ''`, a directory walk, the array's own definition) — a remembered list is a snapshot, and the next one-line edit invalidates it. **A mutation protocol validates a FIX; it never tells you the fix's POPULATION is right** — this is the trap, because the protocol feels like the rigorous part and it is orthogonal to scope. Two tells that the population is wrong: (a) the fix lives INSIDE an array/window/branch while the sink is reachable from outside it; (b) you can describe the fix as "at site A" rather than "at every site that reaches S". **Why:** the preflight Check 10 work (merged 2026-08-10) — the `/home` re-bind was fixed inside `BWRAP_ARGS` and validated FOUR ways; three more mount-injection entry points existed outside that array (`GIT_BIND`, `BWRAP_PROC`, the exec line), and three separate one-line edits each re-opened the operator's credential surface with the whole suite green, verified against live bwrap reaching the Doppler token, `~/.ssh` and the gh token store. Five review rounds each found a different instance of that one unperformed enumeration. See `knowledge-base/project/learnings/2026-08-10-a-guard-that-cannot-be-driven-red-is-vacuous-four-rounds-four-instances.md`. When the deliverable is itself a guard, the plan's `## Guard Contract` (plan Phase 2.12) already names the assembly — implement against THAT, not against the finding's example site. - **Sweep-class fixes use grep-enumerated work-lists, not intuited ones.** When a plan declares a multi-file sweep with a verification grep (e.g., AC5-style `git grep -nE '' | grep -vE '' | wc -l = 0`), run the grep ONCE at Phase 0 to enumerate the authoritative work-list (capture it via `targets=$(mktemp)` and write the hits there — never a fixed `/tmp` name a sibling session would clobber), fix each line, then re-run the grep after each batch. The plan's narrative enumeration of "files X, Y, Z" is a starting hypothesis; the grep result is the work-list. Same applies to regex widenings: enumerate the configs/verbs/paths invoked by the IN-SCOPE runbooks, not the configs the incident occurred against — the incident is one data point; the trap-class config-set is the full union of every config the runbooks touch. **Why:** PR #4031 — initial sweep handled 9 named runbook hits but missed 2 buried in deeper sections of the same files; widened regex covered `(prd|prd_terraform|dev|ci)` per the plan's leak-footprint enumeration but missed `prd_orchestration` which 2 in-scope runbooks operate against. Pattern-recognition + security-sentinel caught both at multi-agent review. See `knowledge-base/project/learnings/best-practices/2026-05-18-sweep-class-fixes-grep-enumerated-not-intuited.md`. - **A plan-prescribed cross-file drift guard ("all N files reference all M tokens") must be verified against each file's ACTUAL token usage before writing the assertion.** A family of parsers is rarely homogeneous — a secondary member often shares only a subset (e.g. a wipe-gate that checks only `--postgres-uri` and never parses redis). Run `grep -cF -- "$tok" "$file"` for every (file, token) pair at Phase 0 and let the matrix define the per-file token set; asserting the full set on a file that uses a subset false-fails a correct codebase. The plan is authoritative for the guard's intent, never its exact token/file set (same class as `hr-when-a-plan-specifies-relative-paths-e-g`). Corollary: plan-quoted AC verify commands are preconditions to re-derive, not facts — a `git diff origin/main | grep -c 'ssh '` proxy false-positives on self-referential prose + branch-divergence in cited-but-unedited files; scope it to the changed code files. **Why:** #5553 — the drift-guard spec required 4 tokens on all 3 ExecStart parsers, but `inngest-wiped-volume-verify.sh` references only 2; scoped per-file at /work. See `knowledge-base/project/learnings/best-practices/2026-06-18-cross-file-drift-guard-verify-per-file-token-usage.md`. - **When you write a conditional gate in PROSE, every rung must end in an action and the safe branch must be reachable by READING, not by remembering.** Three checks, because the failure is silent: (a) a rung ending in a classification ("that is the uncertain case") prescribes nothing, so the reader falls through to the document's default — end every rung in an executable verb and say so in the ladder's preamble; (b) the fail-safe sentence's predicate must be the UNION of what each rung can leave undetermined, or it reads as not firing for the case that actually reached it; (c) state the condition FIRST at each prescription site — a relaxed imperative with a parenthetical pointer to the conditional several hundred lines away makes the safe outcome depend on the reader following a link they have no reason to follow. **Why:** #7352 — a two-rung check for whether a project has a CI-enforced gate answered YES at rung 1, undeterminable at rung 2, took no branch, and handed self-hosted users the relaxed path the design forbade reaching by assumption. See `knowledge-base/project/learnings/2026-08-12-my-ladder-rung-ended-in-a-label-so-it-fell-through-to-the-unsafe-branch.md`. - **A plan's own `## BLOCKING` section is a WORK-LIST, not context — check each finding off against the diff before review, and do not trust a subagent's summary for what that list contains.** Two failures compose here and both are cheap to prevent. (a) The findings a plan marks blocking are written before implementation and read during it, so they are exactly the items an implementer treats as already-absorbed background; grep the plan for its blocking identifiers at Phase 0 and record a disposition per identifier, because "I read that section" is not a disposition. (b) A planning subagent's Session Summary is a CLAIM ABOUT A FILE — verify every identifier it cites exists in the artifact, since a summary that invents or renames findings sends you to check things that do not exist while the real ones go unchecked. **Why:** #7569 — the plan named F14/F15/F16/F18 as blocking, the summary reported `F2`/`F4`/`F7` (none of which exist), and F15 — an unanchored `--grep` letting one row that merely QUOTED a marker suppress the alarm indefinitely — shipped unimplemented into review, which rediscovered it independently. See `knowledge-base/project/learnings/2026-08-17-an-empty-read-is-three-states-and-my-guard-shipped-two-fail-opens.md`. - **When a gate cannot use the obvious discriminator, the replacement is probably a PROXY — name the property before you write the predicate.** The shape recurs whenever a plan says "X cannot tell these apart" (an ack that sees identical counts, a status code shared by several outcomes, a timestamp that moves for two reasons): the fix reaches for a field that *correlates* with the hazard, and a proxy fails in both directions. It misses the hazard when the proxy reads clean for a legitimate reason, and it fires when the proxy is absent for a legitimate reason — the second landing on post-partial-failure states, which are exactly the states with no fixture. Write the property as one sentence first ("no two addresses at this name"), then check the predicate expresses THAT; and enumerate the system's states including after a half-completed operation, saying what the guard reports in each. A guard that blocks a state you would need to recover from is a defect even if nobody has reached it. **Why:** #7640 PR4b — see `knowledge-base/project/learnings/2026-09-03-my-guard-blocked-the-recovery-and-missed-the-hazard.md`. - **Architectural-fork decisions route to the CTO agent, NOT the operator (HARD GATE — both modes).** When mid-work you discover the plan's prescribed mechanism is structurally blocked or contradicted by the code (a plan-vs-codebase contradiction surfaced by tracing the ACTUAL producer) AND the resolution is an *engineering/architecture* decision with material trade-offs — schema/audit substrate, data model, technology choice, security model, or which load-bearing module to disturb — route the BINDING decision to the `soleur:engineering:cto` agent (`Agent` tool, `subagent_type: soleur:engineering:cto`). Do NOT surface it to the operator via `AskUserQuestion`: the operator is non-technical, and architecture is the CTO's call. Reserve operator escalation for *product / scope / preference* decisions (what to build, never how). Hand the CTO the discovered evidence (`file:line`), the candidate options with trade-offs, and the plan's `brand_survival_threshold`; then implement exactly what it returns and record the decision + rejected alternatives in an ADR (`/soleur:architecture`). This is a routing rule, not an approval gate — it fires in pipeline mode too. **Why:** #5325 — /work found the plan's `action_sends`-reuse mechanism (deepen P0-1) was structurally blocked (NOT NULL `message_id` FK with no agent-path message id; UI-only `scope_grants` creation); the substrate choice (dedicated WORM table vs gate-only vs full reuse) is an architecture decision that was first (wrongly) offered to the operator before being routed to the `cto` agent, which ruled. See `knowledge-base/project/learnings/workflow-patterns/2026-06-15-architectural-fork-decisions-route-to-cto-not-operator.md`. - **Legal/compliance-substantive decisions route to the CLO agent, NOT the operator (HARD GATE — both modes).** The exact sibling of the CTO rule above, for the legal domain. When mid-work or at review you hit a decision about *legal posture* — whether a published claim is adequately scoped, whether a lawful basis needs a balancing test or an Art. 30 entry, whether Art. 13/14 notice is adequate for third-party data subjects, whether a correction is a scoping clarification or a retraction, whether a notice and a bilateral instrument may say different things, or whether a determination condition can be discharged at all — route the BINDING decision to the `soleur:legal:clo` agent (`Agent` tool, `subagent_type: soleur:legal:clo`). Do NOT surface it via `AskUserQuestion`: the operator is non-technical, and legal posture is the CLO's call exactly as architecture is the CTO's. Hand the CLO the findings, the governing records (determination, Art. 30 / 30(2) registers, LIA, any instrument), and the binding constraints, and require **drafted replacement wording** back — not just a verdict; then implement exactly what it returns. Two boundaries: (a) **weight is not a routing signal** — a decision feeling consequential is the reason to route it to the CLO, never past it; (b) the genuine external escalation is a **qualified-counsel review**, which is a different act with a different cost, and it routes through the threshold catalog in `knowledge-base/legal/recommended-tools.md` plus a tracked issue — never as an inline operator question. Prompt the CLO with "do NOT use AskUserQuestion" (it defaults to orchestrator mode and would hang a headless run). **Why:** #7347 — a legal-corpus PR blocked on ten P1s surfaced three decisions (a 6(1)(f) limb with no balancing test, an Art. 14 route for third-party subjects, an annex/notice asymmetry on a transfer mechanism); all three were offered to the operator, who asked why the CLO was not taking ownership. See `knowledge-base/project/learnings/workflow-patterns/2026-08-09-legal-decisions-route-to-clo-not-operator.md`. - **Verify that every BINDING item LANDED — a prohibition sweep cannot detect an omission (HARD GATE).** When a plan, review, or amendment list marks items binding, the post-implementation check must assert each one **positively** (grep the artifact for the thing that had to appear), not merely assert that forbidden things are absent. The two sweeps feel interchangeable and are not: "don't touch X / don't assert Y / don't publish Z" can pass 6-for-6 while a required edit was silently dropped, because nothing in a negative predicate quantifies over the obligations. Build the check from the binding list itself — one `grep` per item, output the item id next to a hit/miss — and treat any miss as blocking. Applies with equal force when the implementation was delegated: the delegate's report names what it did, never what it forgot. **Why:** #7347 — a 6/6-green prohibition sweep (T&C untouched, §3.1(b)/(d) unasserted, "eleven processing activities" unchanged, no PR refs, pre-existing drift untouched, no forbidden term-classes) shipped a diff that had silently dropped two amendments recorded as binding by the PR's own plan review, plus a third closed-list fix applied in one document and not its sibling. Same learning file. - **A delegation brief that hands over CONTENT without PLACEMENT delegates the placement decision — and bound the delegate's read scope or it stalls.** Two halves of one lesson about brief shape, both measured on the same corpus in one session. (a) **Per-site, not per-string.** A brief supplying N fixed strings plus a list of target files leaves "which sentence goes in which section" to the delegate, and template-pasting is the predictable result — a section-scoped sentence lands in sections that are not in that scope, which on a published document is a false statement rather than a style nit. Label every block with target file + section + whether the mirror/sibling takes the same change; generate the site list FROM the binding-items list rather than restating it, or the two disagree and nothing compares them. (b) **Bound the read scope.** "Read all N target files, then edit" is the shape that hits the stream watchdog; scope the delegate to one document at a time, its own blocks only, with a commit after each, so a stall costs one unit rather than the run. Prefer **resume over respawn** when one does stall — a resume keeps the transcript. **Why:** #7347 — round 1 (ten strings, no placement) produced 10 P1s, 6-7 of them greps, and cost a four-agent panel plus a full re-implementation; round 2 (14 blocks, each labelled file + section + mirror) applied cleanly, and its only deviations were contract bugs rather than placement errors. Two subagents stalled on the wide-read shape. See `knowledge-base/project/learnings/2026-08-09-three-green-gates-and-the-published-page-was-still-wrong.md`. - **Emergent PRODUCT/SCOPE/PREFERENCE decisions classify via the taxonomy, and headless never pauses on them.** For a mid-work decision that is NOT an architecture fork (those route to the CTO agent, above) — dropping/deferring operator-requested scope, a user-visible behavior choice, a money/compliance call — classify it Mechanical / Taste(user-legible) / User-Challenge per [decision-principles.md](../brainstorm-techniques/references/decision-principles.md) (ADR-084). Mechanical + technical-taste: auto-decide silently. A user-legible Taste or a User-Challenge (both against the operator's stated direction) in a headless/one-shot run: keep the operator's stated direction as the default and **persist** it to `knowledge-base/project/specs//decision-challenges.md` (append; alongside `session-state.md`) — never a mid-pipeline pause. `ship` Phase 6 renders that artifact into the PR body and files the `action-required` issue the operator actually sees. The one exception to no-pause: a security/feasibility regression halts terminally before merge (see the reference doc). - **A composite read fails as its WEAKEST arm, and a verdict must never rest on an instrument that was not shown to work.** When a query `UNION`s two sources (or a check ANDs two probes), verify each answers INDEPENDENTLY before relying on the pair: a `UNION ALL` over a healthy arm and an absent one fails entirely, so the read errors on every attempt regardless of the data — and if the loop only inspects results when `rc == 0`, "the read failed" becomes indistinguishable from "the read found nothing". The damage is downstream: the code then consults a CONTROL source, which is a DIFFERENT table whose health licenses nothing about yours, and emits a substantive verdict off a query that never ran. Track whether the read ever succeeded, report UNKNOWN when it did not, and carry the transport error so the next reader does not re-derive it. **Why:** #7855 — a round-trip probe's readback UNIONed an archive arm whose named collection does not exist for that source (669, measured), so it failed on every poll and the probe posted a public vendor data-loss accusation off it; the same PR's own header claimed the opposite behaviour. See `knowledge-base/project/learnings/security-issues/2026-09-06-the-file-i-added-to-fix-a-p1-shipped-a-p1.md`. - **Interactive mode only:** If anything is unclear or ambiguous, ask clarifying questions now. Get user approval to proceed. **Do not skip this** - better to ask questions now than build the wrong thing. - **Pipeline mode:** Skip clarifying questions and approval. Proceed directly to step 2. 2. **Setup Environment** First, check the current branch by running `git branch --show-current`. Then determine the default branch by running `git symbolic-ref refs/remotes/origin/HEAD` and extracting the branch name. If that fails, check whether `origin/main` exists (fallback to `master`). **If already on a feature branch** (not the default branch): - **Interactive mode only:** Ask: "Continue working on `[current_branch]`, or create a new branch?" - **Pipeline mode:** Continue on current branch without asking. - If continuing, proceed to step 3 - If creating new, follow the worktree creation instructions below **If on the default branch**, you MUST create a worktree before proceeding. Never edit files on the default branch -- parallel agents cause silent merge conflicts, and this repo uses `core.bare=true` where `git pull` and `git checkout` are unavailable. Create a worktree for the new feature: ```bash SOLEUR_SKILL_NAME=work SOLEUR_EXPECTED_DURATION_MIN=240 \ bash ${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}/skills/git-worktree/scripts/worktree-manager.sh --yes create feature-branch-name ``` Then `cd` into the worktree path printed by the script. The worktree manager handles bare-repo detection, branch creation from latest origin/main, .env copying, and dependency installation. The env vars wire a session lease so sibling cleanup-merged invocations refuse to reap this worktree. **Phase Exit (release lease).** At the end of the workflow — after `/soleur:ship` returns OR if you exit without shipping — release the lease so a sibling `cleanup-merged` can reap the worktree once it's actually merged: ```bash # Degrade open (#7409): releasing is advisory — an unreleased lease expires # on its own window — so a missing library must not fail the pipeline here. SS_LIB="${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}/scripts/lib/session-state.sh" if [[ -r "$SS_LIB" ]]; then bash "$SS_LIB" release_lease "$(basename "$PWD")" || true else echo "SOLEUR_SESSION_STATE_UNAVAILABLE path=$SS_LIB reason=lease-not-released" fi ``` The release is a no-op if the lease was already removed by the multi-signal trap (EXIT/INT/TERM/HUP fires on abnormal exit). Stale leases get swept after 24 hours regardless. Use a meaningful name based on the work (e.g., `feat-user-authentication`, `fix-email-validation`). 3. **Create Todo List (TDD-First Structure)** Structure tasks as RED/GREEN/REFACTOR units, not as "implement everything, then test": - For each feature requirement with Acceptance Criteria or testable behavior: - Create a **RED task**: "Write failing test for [feature]" — the test file with at least one failing test - Create a **GREEN task**: "Implement [feature] to pass tests" — blocked by its RED task - Group these as a TDD unit with `blockedBy` dependency (GREEN blocked by RED) - Infrastructure-only tasks (config files, CI, scaffolding, legal docs) are exempt from RED/GREEN pairing — create them as standalone tasks - Place a final test-and-lint task at the end, blocked by all other tasks. **If the project has no CI-enforced full-suite gate on the merge branch, make it "Run the full test suite and lint" — see **Full-suite fallback** in Phase 2 §9, and when in doubt this is the branch you take.** Otherwise "Run the touched-file suites and lint". - Keep tasks specific and completable **Anti-pattern to avoid:** Creating a task list like `[implement A, implement B, implement C, ..., write tests, lint]`. This structure guarantees TDD violation because the agent executes tasks in order. The correct structure is `[RED: test A, GREEN: implement A, RED: test B, GREEN: implement B, ..., lint]`. **Post-creation validation (HARD GATE):** After creating all tasks, scan the task list for any non-exempt implementation task (GREEN) that does NOT have a corresponding RED test task in its `blockedBy` list. If found, restructure the task list before proceeding. Do not start Phase 2 with an invalid task structure. **Why:** In PR #2428, the agent created flat tasks ("Fix X", "Write tests") and started implementation before tests — the user had to intervene and force a restructure. The anti-pattern instruction was not enough without a validation gate. ### Phase 2: Execute **Output discipline (all tiers).** Long execution phases blow the response-token ceiling and truncate mid-pipeline, losing the thread. Keep inline output bounded: when a command's output is large (full diffs, build logs, test dumps), write it to a file and reference the path rather than pasting it — never echo a diff over ~200 lines inline (`d=$(mktemp -t .XXXXXXXX.diff); git diff > "$d"; echo "DIFF=$d"` then summarize, citing the path). After each task or logical unit, emit a one-line `## Work Phase complete` checkpoint marker so an interrupted run has a clear resume point. This complements hard rule `hr-never-run-commands-with-unbounded-output` (which forbids unbounded *commands*); this is about bounding your own *narration* of them. 1. **Execution Mode Selection** (HARD GATE — must complete before executing ANY task) **Do NOT execute any task before completing this analysis.** Analyze independence first, select the execution tier, then begin. Starting sequential execution "because the first tasks feel simple" is a workflow violation — it forfeits parallelization savings on the remaining tasks. Before starting the sequential task loop, check for parallelization opportunities: **Step 0: Tier 0 pre-check (Lifecycle Parallelism)** Read the plan. Apply a single judgment: "Does this plan have distinct code and test workstreams that can be assigned to separate agents with non-overlapping file scopes?" - If yes (interactive mode): offer Tier 0 to the user - If yes (pipeline mode): auto-select Tier 0 without prompting - If declined or ineligible: fall through to Step 1 below **Read `plugins/soleur/skills/work/references/work-lifecycle-parallel.md` now** for the full Tier 0 protocol (offer/auto-select, generate contract, spawn 2 agents, collect/commit, test-fix-loop, docs). If Tier 0 executes, proceed directly to Phase 3 after completing Step 06 of the protocol. If declined, fall through to Step 1. --- **Standing constraint for EVERY tier — a spawned agent never runs the gate.** Spawned agents run only the suites targeting the files they were given. **`SOLEUR_SUBAGENT=1` is a convention a lead MAY export before spawning — the harness does not set it** (measured 2026-08-19 from inside two independent spawned agents: UNSET in both, and no repo-controlled spawn path exists to set it). They must not run [scripts/test-all.sh](../../../../scripts/test-all.sh), `apps/web-platform/infra/run-registered-suites.sh`, or any other full-gate runner: concurrent full-gate runs inflate each other's timings and corrupt the measurement. Measured 2026-08-11 — three agents running lints and suites at once turned an 860 s battery into 1675 s, and that 1.9x figure was then nearly used as the suite's cost budget. The lead runs the gate ONCE, after collecting fan-out work. Two mechanical backstops exist, and neither depends on an agent volunteering anything: [scripts/test-all.sh](../../../../scripts/test-all.sh) exits 4 when it MEASURES a sibling full-gate run already in flight (#7553), and `tc_acquire`'s advisory lock (ADR-133) serialises whatever gets past that. The `SOLEUR_SUBAGENT=1` exit-4 path is real and reachable by anyone who exports it deliberately, but it is a convention rather than an enforced one — so the paragraph above IS agent discretion for the non-concurrent case, and is written as an instruction, not a claim about the harness. **Step 1: Analyze independence** Read the TaskList. Identify tasks that have no `blockedBy` dependencies and reference different files or modules (no obvious file overlap). Count the independent tasks. If fewer than 3 independent tasks exist, skip to **Tier C: Sequential** below. If 3+ independent tasks exist, proceed through the tiers in order (A, then B, then C). Each tier either executes or falls through to the next. --- **Pipeline mode override:** If running in pipeline mode (plan file argument detected in Phase 1), auto-select Tier 0 if eligible (Step 0 above). If Tier 0 is ineligible, skip Tier A entirely and auto-accept Tier B without prompting. Do not present "Run as Agent Team?" or "Run in parallel?" questions -- proceed directly to Step B2 of the Subagent Fan-Out protocol if 3+ independent tasks exist, otherwise fall through to Tier C. --- **Tier A: Agent Teams** (highest capability, ~7x token cost) **Read `plugins/soleur/skills/work/references/work-agent-teams.md` now** for the full Agent Teams protocol (offer, activate, spawn teammates, monitor/commit/shutdown). If declined or failed, fall through to Tier B. --- **Tier B: Subagent Fan-Out** (fire-and-gather, moderate cost) **Read `plugins/soleur/skills/work/references/work-subagent-fanout.md` now** for the full Subagent Fan-Out protocol (offer, group/spawn, collect/integrate). If declined **or failed**, fall through to Tier C. The `or failed` is load-bearing and was missing: Tier 0 and Tier A both read "If declined **or failed**, fall through", so a spawn FAILURE at those tiers has a defined next step. Tier B said only "If declined" — leaving a spawn failure (agent tool withheld, `529 Overloaded`, headless run with no agent surface) with no prescribed behavior at the LAST tier that can degrade. Tier C is always available because it is sequential execution in the main context, so the fall-through costs nothing and closes the gap. When it fires, say so: "Tier B fan-out unavailable () — executing sequentially" rather than silently running Tier C as though it were the chosen tier. --- **Tier C: Sequential** (default) Proceed to the task execution loop below. 2. **Task Execution Loop** **Design Artifact Gate (before first UI task):** If `DESIGN_ARTIFACTS` was set in Phase 0.5, spawn the `ux-design-lead` agent with the artifact paths and ask it to produce an **implementation brief** (see ux-design-lead "Wireframe-to-Implementation Handoff" workflow). The brief is a structured description of every section, its content, and its layout — this becomes the binding input for all UI tasks. Do not write any markup until the brief is received. **UX artifact commit checkpoint (after Design Artifact Gate):** After the implementation brief is received, commit before proceeding to UI tasks: 1. Run `git status --short` to discover the implementation brief and any generated design files 2. Stage output files: `git add ` 3. Commit: `git commit -m "wip: UX implementation brief for "` This checkpoint ensures the implementation brief survives session crashes. For each task in priority order: ```text while (tasks remain): - Mark task as in_progress in TodoWrite - Read any referenced files from the plan - If task creates UI/pages: verify implementation brief exists (HARD GATE) - TDD GATE: (see below) - Look for similar patterns in codebase - RED: Write failing test(s) for this task's acceptance criteria - GREEN: Write minimum code to make the test(s) pass - REFACTOR: Improve code while keeping tests green - Run the touched-file suites after changes — **full suite instead if the project has no CI-enforced merge gate; see **Full-suite fallback** in Phase 2 §9** - Mark task as completed in TodoWrite - Mark off the corresponding checkbox in the plan file ([ ] → [x]) - Evaluate for incremental commit (see below) ``` **No mid-plan pause gates (HARD GATE).** A multi-phase plan (`tasks.md` Phase 0 through Phase N) is a SINGLE execution unit. Do NOT insert "Pause for review or continue?" prompts between phases. Do NOT end a turn after one phase commits with "Continue into Phase N+1 next turn?". The skill's Phase 4 handoff is the only sanctioned stopping point — until then, chain straight through every phase the plan defines, including phases the plan labels "Pre-merge verification" or "Post-merge (operator)" if they're automatable per the next gate. **Why:** the founder is a solo operator; every "continue or pause?" is a context switch that defeats the entire point of a multi-phase plan. Pipeline mode (file-path arg in Phase 1) means pipeline mode for the WHOLE plan, not per-phase. **Operator-step automation gate (HARD GATE).** Before treating any task in `tasks.md` as "operator-driven" (apply migration, verify pg_cron, verify Storage bucket, run end-to-end smoke, `gh pr ready`, `gh pr merge --auto`), check whether it is automatable via a loaded MCP server or CLI: - Supabase migrations + `cron.job` queries + Storage bucket existence + RLS spot-checks → `mcp__plugin_supabase_supabase__*` **with Doppler `DATABASE_URL_POOLER` fallback when MCP is unavailable** — see "Supabase fallback chain" below. When a migration needs a SECURITY DEFINER RPC (e.g. to bypass an RLS / column-grant restriction), start from [`sql-security-definer-rpc-scaffold.sql`](./references/sql-security-definer-rpc-scaffold.sql) — it encodes the `search_path` pin + 4-role REVOKE + `auth.uid()` authorization pin that `test/migration-rpc-grants.test.ts` enforces. - `gh pr ready` / `gh pr merge --squash --auto` / `gh issue close` → Bash via `gh` CLI - End-to-end UI flow → Playwright MCP (`mcp__playwright__*`) - Cloudflare DNS / WAF / Workers → `mcp__plugin_soleur_cloudflare__*` - Live Stripe state → `mcp__plugin_soleur_stripe__*` If automatable, EXECUTE it inline as part of the work pipeline — never list it back to the operator. The /ship skill already handles `gh pr ready` + auto-merge + migration verification (see `plugins/soleur/skills/ship/SKILL.md`); chain to `/soleur:ship` at Phase 4 and let it run. For migration **apply** to dev (vs verify), invoke `mcp__plugin_supabase_supabase__apply_migration` inline at the phase where the migration lands, not as a post-merge todo. **Why:** see ship/SKILL.md:1027 ("Every 'please run this manually' is a context switch") and ship/SKILL.md:1177 (PR #1375 — migration verification was left as a manual "post-merge todo" instead of being executed; deployed code expected the new schema and broke). Same class as the Playwright-first audit in Phase 4: if a tool exists, use it. **Supabase fallback chain (when MCP OAuth fails).** The Supabase MCP OAuth flow at `https://api.supabase.com/v1/oauth/authorize` intermittently rejects valid URLs at the dashboard `auth_id` handoff (cause: external — Supabase-side). When that happens, do NOT fall back to "paste this SQL into the dashboard SQL editor" handoff — that's a manual-step rationalisation that violates `hr-never-label-any-step-as-manual-without`. Instead walk down the `hr-exhaust-all-automated-options-before` priority chain: (1) Doppler `DATABASE_URL_POOLER` — already provisioned for every env; the migration apply path. (2) Verify the project ref in the URL matches the plan's stated dev/prd refs — Doppler is the source of truth (plan-quoted project refs are preconditions to verify, never facts; the plan can drift). (3) Rewrite the URL's port `:6543` → `:5432` so the pooler runs in session mode (multi- statement DDL works; transaction mode rejects with SQLSTATE 42601 "cannot insert multiple commands into a prepared statement"). (4) Apply via `pg` (node-pg, bun-installed in `/tmp` if missing) wrapped in `BEGIN; ; COMMIT;`. The direct DB host `db..supabase.co:5432` is IPv6-only and typically unreachable from operator/CI networks; the pooler is IPv4. (5) Post-apply, verify schema via the same connection — RLS enabled, policy_count, trigger names, RPC signatures + SECURITY DEFINER flag, UNIQUE constraints. Write the verification artifact to `knowledge-base/project/specs/feat-/migration-checklist.md`. **Why:** PR #3853 / #3205 — Supabase MCP OAuth was rejecting URLs at the auth_id handoff; the agent first proposed "paste SQL into dashboard" (manual-step violation), then pivoted to Playwright- first audit on dashboard navigation (correct), then discovered Doppler had the working `DATABASE_URL_POOLER` and applied via pg directly — the path it should have taken at step 1. **Session stickiness:** once the MCP OAuth handoff has failed even once in the current session, treat Doppler `DATABASE_URL_POOLER` as the default for ALL subsequent Supabase operations this session — do not re-attempt the OAuth flow per-operation. Re-probing a known-flaky external auth each time is the wasted-cycle trap; the fallback is not slower once you are already authenticated to Doppler. **Pre-apply collision check (always, even on first attempt).** Before invoking pg apply (or `supabase migration up`) against any shared env, run `git fetch origin main && git ls-tree origin/main -- apps/web-platform/supabase/migrations/ | awk '{print $4}' | grep -oE '^[0-9]{3}_[^.]+' | sort -u`. For each LOCAL migration file the branch introduces, assert no DIFFERENT filename with the same 3-digit prefix exists in that list. A collision means a sibling PR is landing the same number window; renumber FIRST, then apply under the final filename. **Why:** PR #4225 — applied 053–057 in the morning; PR #4251 landed `054_schema_migrations_ content_sha.sql` 10 hours later and main's CI drift probe flagged the entire branch; the recovery (renumber 054→058, 055→059, 056→060, 057→061 + reconcile `public._schema_migrations` on both dev + prd via `git hash-object` content_sha) took ~30 min and could have been zero-cost if the operator had grepped origin/main first. **The collision window extends through `/ship`, not just work-time.** This check at work-start is necessary but NOT sufficient: a sibling migration can land on main DURING the (often 30–90 min) ship phase — especially under a fast-moving-main burst where `/ship` Phase 7 performs repeated `git merge origin/main` auto-syncs on `OPEN BEHIND`. Each sync that pulls in a sibling `supabase/migrations/NNN_*.sql` sharing your prefix is a silent collision the BEHIND loop pushes straight to CI (where the migration drift/shape gate fails, ~16 min later). After ANY ship-time sync whose merge output lists `supabase/migrations/`, re-run the prefix check above and renumber-during-ship (`git mv` both up/down + update every in-repo reference: migration headers, code comments, plan/tasks/learning) BEFORE the next push. **Why:** PR #5760 — `114_disk_io_top_wal_statements` (a #5739-sibling) landed mid-ship; my `114_prune_cron_job_run_details` collided and surfaced only at CI after ~6 auto-syncs; recovery was a renumber to 115. See `knowledge-base/project/learnings/workflow-patterns/2026-06-30-migration-number-collision-mid-pipeline.md`. **The collision set includes the shared DEV DATABASE, not just `origin/main`.** The check above greps `origin/main`, and a sibling branch's migration is invisible there until it merges — but it is fully visible in dev's `_schema_migrations`, because the sibling session APPLIED it. Query all three sources and take the union: `origin/main`, every worktree's `supabase/migrations/`, and `SELECT filename FROM public._schema_migrations ORDER BY filename DESC LIMIT 5` over Doppler `DATABASE_URL_POOLER`. **Why:** #7829 — `136` was free on `origin/main` and already applied to dev by a sibling; the collision surfaced only when a live probe for an unrelated question happened to list the applied set, after the number had been written into a function body (which Postgres stores in `prosrc`), an Article 30 register cell, and 38 prose sites. **Tracking row in the SAME transaction as the migration body.** The project's canonical `apps/web-platform/scripts/run-migrations.sh` writes `INSERT INTO public._schema_migrations (filename, content_sha) VALUES ('', '')` in the same transaction as the migration SQL. The Doppler+pg fallback MUST mirror this — bare `BEGIN; ; COMMIT;` produces a phantom-applied state where the schema reflects the migration but `_schema_migrations` does not, and the next deploy attempts re-apply (failing on non-idempotent statements like `CREATE TRIGGER`). The reconciliation pattern (UPSERT with `ON CONFLICT (filename) DO UPDATE SET content_sha = EXCLUDED.content_sha`) is the recovery shape — but doing it inline is cheaper. **PostgREST schema cache reload via session-mode pooler does NOT work.** `NOTIFY pgrst, 'reload schema'` over a `:5432` pooler connection does not reach PostgREST's `LISTEN` (PgBouncer multiplexes; LISTEN/NOTIFY channel scope is bound to backend process identity, not session). 90 attempts over 5 minutes returned `PGRST205`. After a direct-pg apply: either wait for the natural ~10-min schema poll cycle, OR use the Supabase Management API to restart PostgREST. The direct DB host (`db..supabase.co:5432`) is IPv6-only and typically unreachable from operator networks, so the canonical "NOTIFY via direct connection" workaround documented upstream isn't available. **Storage-bucket migrations: `down.sql` cannot DELETE storage tables; column-takeover proof is permissive-vs-restrictive, not name-count.** Supabase installs a platform `BEFORE DELETE` trigger (`protect_objects_delete` → `storage.protect_delete()`) that blocks direct `DELETE FROM storage.objects` AND `storage.buckets` ("Direct deletion from storage tables is not allowed"). So a bucket migration's `down.sql` reverts only SQL-droppable objects (policies → function → column) — NOT the bucket/objects (Storage-API/operator teardown; 019/042 precedent ship none; 071's `DELETE FROM storage.buckets` is a dormant bug). Runtime cleanup uses `service.storage.from(b).remove([...])` (allowed). And when verifying "no client can write column X" (read-proxy trust), assert no **PERMISSIVE** INSERT/UPDATE/DELETE/ALL policy (a RESTRICTIVE `FOR ALL` like `workspaces_jti_not_denied` only denies, never grants) + a behavioral authenticated `UPDATE` affecting **0 rows**. The pooler also presents a self-signed CA chain → transient node-pg verify scripts use `ssl:{rejectUnauthorized:false}` (dev-only, mirrors run-migrations.sh `sslmode=require`; no committed code disables TLS verify). See `knowledge-base/project/learnings/2026-06-04-supabase-bucket-migration-down-and-rls-takeover-proof.md` (#4916). **TDD Gate (HARD GATE):** Before writing ANY implementation code for a task, determine if the task has testable behavior: Emit rule-application telemetry (records that the TDD gate was reached — see AGENTS.md `cq-write-failing-tests-before`): ```bash echo 'SOLEUR_RULE_APPLIED rule=cq-write-failing-tests-before note=Write failing tests BEFORE implementation code whe' ``` 1. **Check:** Does the plan have a "Test Scenarios" or "Acceptance Criteria" section that covers this task? If yes, this task requires test-first. 2. **Exempt:** Infrastructure-only tasks (config files, CI workflows, scaffolding directories, dependency installs) are exempt. If the task only creates/modifies config, it skips to Infrastructure Validation below. 3. **Enforce:** For non-exempt tasks, write the failing test file FIRST. The test must: - Import the component/function/module that will be created (the import will fail — that is correct) - Assert the specific behavior from the acceptance criteria - Be runnable via the project's test command (even if it fails due to missing implementation) 4. **Verify RED:** Run the test. It must fail (missing module, assertion failure, etc.). If it passes, the test is not testing new behavior — rewrite it. **For gating/sequencing primitives (semaphores, locks, queues, ordering guarantees), the test must distinguish gate-absent from gate-present: add an intermediate-state assertion that would fail without the primitive (e.g., `count === 2` while two slots are held) in addition to the final-state assertion. A test that passes identically with and without the primitive isn't testing the primitive.** See `knowledge-base/project/learnings/test-failures/2026-04-18-red-verification-must-distinguish-gated-from-ungated.md`. **Test-environment fidelity:** if the SUT's buggy code lives behind a guard (`if [[ -d "$X" ]]`, `if (cache.has(key))`, etc.), the harness MUST seed the precondition the guard requires — otherwise both buggy and fixed paths short-circuit identically and any negative-space assertion passes vacuously. See `knowledge-base/project/learnings/test-failures/2026-04-22-red-test-must-simulate-suts-preconditions.md`. **Early-exit shadowing:** if the SUT has a guarded fast path (substring strip like `replaceAll(arg, "")`, cache-hit, env-flag short-circuit) that handles a superset of inputs the slow path under test handles, RED inputs MUST choose identities ONLY the slow path can produce. Sharing a fixture across the fast/slow boundary lets the fast path scrub first and the regex/branch under test never fires — the assertion passes without testing the fix. Add an invariant guard test asserting the fast/slow fixtures do not collide. See `knowledge-base/project/learnings/2026-05-04-vacuous-red-via-shared-fixture-and-toolchain-pinning.md`. **In-component state machines (RTL):** when the gate-under-test is component-local state (`useState`/`useRef`/`useReducer`), drive the SUT through state transitions with `result.rerender()` — never `unmount()` + fresh `render()`. Remount resets the in-component bookkeeping that IS the gate, producing vacuous green. See `knowledge-base/project/learnings/test-failures/2026-05-11-rerender-not-remount-for-in-component-state-machine-tests.md`. **Laundered-target resolvability (normalizer/strip/prefix-mangle security fixes):** a regression guard for an anchored-strip / path-canonicalization / allowlist-key fix is vacuous unless the fixture makes the LAUNDERED (mis-normalized) target resolvable to an observable effect — if the downstream gate rejects it for an *unrelated* reason (nonexistent skill/row/file), the test passes identically with and without the fix. Litmus: under the buggy impl, does this input produce a DIFFERENT output than under the correct one? See `knowledge-base/project/learnings/test-failures/2026-07-05-security-fix-regression-guard-must-make-the-laundered-target-resolvable.md`. **Fixture-space cardinality (ask this per contract sentence, and note that your own passing mutation battery cannot answer it):** for each property the test claims, name the SET it quantifies over and count how many distinct members the FIXTURE instantiates — one member is a sample, not a proof, and code-mutation coverage does not detect a fixture-space gap. Three shapes recur: (a) a **temporal** contract (a wait/retry/debounce/convergence) sampled only by STATIC fixtures probes t=0 and t=∞ but never the transition — the case the guard exists for — so deleting the loop's `break` stays green; drive it with a stateful stub that changes on the Nth invocation and assert the success arm was reached VIA the loop; (b) a **bidirectional** guard (`-w`, an ordering, a comparison) must be fixtured in the direction where the weaker implementation gives a FALSE POSITIVE, not the direction that fails either way; (c) a stub that ignores `argv`, or a `sleep`/clock stubbed to a no-op, silently voids the call-shape and budget contracts — validate `"$*"` in the stub and COUNT the stubbed calls against the design's bound. **Why:** #6441 — a 7-mutation battery reported 7/7 RED while nine unimagined mutations (loop-`break` deleted, `grep -qwF`→`-qF`, `addr show`→`link show`, bound 30→1, `sleep 2`→`600`) all survived. See `knowledge-base/project/learnings/2026-07-19-my-own-mutation-battery-was-the-false-confidence.md`. **A SURVIVING mutant is a result, and it has exactly two readings — label which:** either the fixtures do not exercise the property (fix the FIXTURES, not the guard) or the mutant is EQUIVALENT (prove no verdict changes, and record that it survives). Leaving it unlabelled is how a guard that is merely adjacent to a working one ships. Measured: two anchoring fixes survived their own mutations because an earlier `action=` split already caught every fixtured row, and both were reachable in production once the fixture used a field whose sanitiser PERMITS the colliding literal; a third survived and was correctly left alone as equivalent. **Why:** #7220 — see `knowledge-base/project/learnings/2026-08-05-my-anchoring-fix-survived-its-own-mutation-and-three-gates-were-green-elsewhere.md`. **A DISJUNCTION needs one fixture per disjunct, ALONE — and when the operands come from `@tsv`, check the parse before the logic.** A fixture that satisfies every arm of an `||` at once proves the set is non-empty and nothing else: dropping either arm keeps the suite green, so a load-bearing signal and a dead one are indistinguishable. The sharpest instance is not a missing fixture but a PARSE bug the all-arms fixture hides: tab is IFS-**whitespace**, so `while IFS=$'\t' read -r a b c` COLLAPSES runs of tabs and drops empty middle fields, and `@tsv` emits an empty field for an absent key — so `digestunknown` parses as `b="unknown", c=""`, shifting every later field one position left. The arm reading `c` is then unreachable in exactly the case where it is the only signal. Sentinel every optional `@tsv` field (`(.x // "-")`) so no field is ever empty, and fixture each disjunct in isolation. **Why:** #7378/PR #7379 — the guard written to stop `crane validate` gunzipping an in-toto attestation layer sent that layer to `crane validate` whenever the annotation was absent, while emitting a message asserting that was impossible; five further guards in the same PR (a `> 0` count that could not see partial enumeration, an untested `ref_repo`, two `verify_die` arms with no failing fixture, and the whole new block behind no assertion floor) were vacuous the same way. See `knowledge-base/project/learnings/2026-08-10-the-guard-i-wrote-to-close-7378-reopened-it-one-field-to-the-left.md`. **A numeric predicate that is a LOWER BOUND ONLY cannot distinguish a measurement from a CONSTANT — bound it on both sides, against a value the artifact itself reports.** `value >= N` over any measured quantity (an elapsed, a count, a byte size, a row total) passes identically against a hardcoded literal, so a suite of them tests that something happened and never that the something is a function of its inputs. Litmus per assertion: **name a constant that satisfies it** — if you can, it is a shape check wearing a measurement's clothes. Prefer a ceiling derived from the output itself (the banner prints its own budget; the report prints its own input size) over a second magic number, and place the two bounds so no single value can satisfy both arms at once. **Why:** #7484 — a PR whose entire thesis was "report the measured wait instead of asserting one" had all three elapsed predicates as one-sided floors and the discriminating premise ("a free lock reads single-digit ms") sitting in a PROSE COMMENT; `printf '%sms' 1500` passed 95/0, and dropping the `/1000` printed a claimed 33-minute wait against a 2-second budget, also green. Its 7-row mutation battery could not see either: every row perturbed the SUT toward *small or absent*, so a plausible constant was outside the axis it edited. See `knowledge-base/project/learnings/2026-08-13-a-lower-bound-cannot-tell-a-measurement-from-a-constant.md`. 5. **Only then:** Write the minimum implementation to make the test pass (GREEN). 6. **Refactor:** Improve code while keeping tests green. Skipping this gate — writing implementation before tests — is a workflow violation equivalent to committing directly to main. The rationalization "this is simple enough to not need test-first" is exactly the reasoning TDD is designed to prevent. - **Three shell-authoring traps that fail SILENTLY and cost a full debug cycle each.** (a) **Tab is IFS whitespace**, so `while IFS=$'\t' read -r a b c` collapses a LEADING or empty field — a sentinel emitted as `\t__MARK__\t12` arrives as `a=__MARK__ b=12 c=`, and the count lands in the wrong variable. Put a sentinel in a non-empty FIRST field. (b) **An apostrophe anywhere inside `awk '…'` closes the block** — including in a prose comment written to explain the code ("split on the shell's own separators"), which surfaces as a bash syntax error pointing at an unrelated line; grep the block for `'` after editing. (c) **A `case` glob's `*` matches `/` but the pattern is still ANCHORED**: a root-anchored `/*.sh` pattern covers arbitrary depth BELOW that directory and matches no same-named directory elsewhere in the tree, so a two-pattern list read as "covers everything" while missing ~185 tracked scripts. When claiming a pattern's reach, name the axis and test a member on the OTHER one. **Why:** #7084/PR #7566 — (a) reported "parsed 0 jobs" and would have been "fixed" by lowering the floor; (c) shipped in a commit message asserting the opposite. See `knowledge-base/project/learnings/security-issues/2026-08-16-a-guard-asserting-absence-was-backwards-and-my-floors-counted-the-wrong-thing.md`. - **A gate placed AFTER a cheap pre-filter is only reachable for inputs the filter admits — give every gate a counter, or its removal has no observable.** When a walk is structured as cheap-filter-then-expensive-check, ask per gate *which inputs actually reach this line*. Measured: an own-uid gate inside the classifier counted ZERO against a real `/proc`, because a foreign process's `/proc//fd` is mode 500 so the `fd/255` pre-filter rejected it first — the gate could not fire and deleting it changed nothing, which is a guard that no test can falsify. Moving it ahead of the pre-filter as a fork-free `[[ -O ]]` took it from 0 to 390 of 627. Same session, same shape one level out: `(( x < $SEAM ))` on a NON-numeric seam does not abort — it errors and evaluates the `if` as FALSE, silently skipping the branch, so an unvalidated `MIN_AGE_S=10m` signalled a two-second-old process while every counter reported a clean walk. Validate numeric seams as `^[0-9]+$` at the boundary. **Why:** #7537 — see `knowledge-base/project/learnings/2026-08-20-my-test-suite-reaped-the-live-box-and-every-gate-was-green.md`. - When adding MCP tools to an existing registration block in agent-runner.ts, verify each tool's prerequisites are independent of the block's guard condition. Write a test that validates the new tool works WITHOUT the existing block's prerequisites (e.g., Plausible tools work without GitHub installation). - When adding route handler tests that require `vi.mock()`, create a separate test file from existing unit tests that import the real module. Vitest hoists all `vi.mock()` calls to the top of the file, clobbering real imports for the entire file regardless of describe block scope. - When creating test files with `vi.mock()` factories that reference shared variables, use `vi.hoisted()` from the start -- vitest hoists `vi.mock` to the top of the file before `const`/`let` declarations execute. - When a NEW shared module will be imported (directly or transitively) by files that already have test suites mocking a node builtin (`vi.mock("node:child_process")` with spawn-only factories is the common case), do NOT destructure that builtin's exports at module top level (`promisify(execFile)` crashes EVERY sibling suite at import). Lazy-import inside the function that uses it. **Why:** #5091 — `_cron-safe-commit.ts`'s top-level `promisify(execFile)` broke 28 cron-bug-fixer tests at module load. See `knowledge-base/project/learnings/2026-06-10-bot-cron-safe-commit-substrate-symlink-removal.md`. - Before adding a `vi.mock("")` to an EXISTING test file, grep the file for a pre-existing mock of the same module (`grep -n 'vi.mock' | grep `) and wire your spy into that block instead. Vitest registers one mock per resolved module per file; a duplicate does not error — it silently picks one, and your hoisted spy captures zero calls. **Why:** PR #5090 — a new egress-posture-log spy was added as a second `@/server/logger` mock while the factory test already mocked it ~150 lines down; cost 4 debug cycles. See `knowledge-base/project/learnings/bug-fixes/2026-06-10-sandbox-network-plane-not-token-plane-error-shape-triage.md`. - A WHOLESALE `vi.mock("", () => ({...}))` replaces the ENTIRE module, dropping every export the factory omits — so a module with multiple named exports (`@/server/logger` exposes `default` AND `createChildLogger`; observability, db-helper, supabase wrappers similarly) breaks any REAL sibling in the SUT's import graph that consumes a different export. Default to `vi.mock(spec, async (importOriginal) => ({ ...await importOriginal(), }))`; reserve wholesale factories for modules you fully replace — or skip the mock entirely if the thing under test already mocks the export's consumer. Detection is free: run the FULL test file (never `-t ""` alone) — the RED run surfaces unexpected sibling failures naming the missing export. **Why:** #5689 — a wholesale `@/server/logger` mock dropped `createChildLogger` (used by `probe-octokit.ts` via `_cron-shared`), breaking 10 unrelated arm-2 tests. See `knowledge-base/project/learnings/test-failures/2026-06-29-wholesale-module-mock-drops-named-exports-needed-by-transitive-siblings.md`. - A partial `vi.mock(spec, async (importOriginal) => ({ ...actual, B: spy }))` override only changes what **importERS** see — it does NOT intercept a call made by a REAL sibling function `A` (kept via `...actual`) to `B` **within the same module**; `A` references `B` through the module's internal lexical binding, not the export object. Symptom: the spy reports 0 calls even though the path clearly runs `B`. To observe `B` while keeping `A` real, mock the deeper boundary `B` itself crosses (`fetch`, the DB client, `child_process`) and assert there. Decision rule: **mock the seam the unit under test does not own.** **Why:** #5728 — overriding `postSentryHeartbeat` didn't intercept the real `finalizeOutputAwareHeartbeat`'s internal call; fixed by keeping it real + stubbing `fetch` + asserting the POST URL. See `knowledge-base/project/learnings/test-failures/2026-06-30-partial-module-mock-does-not-intercept-intra-module-calls.md`. - When mocking `child_process.spawn`, `fetch`, or any constructor returning an event-emitter-like object, use `mockImplementation(() => factory(...))` rather than `mockReturnValue(factory(...))`. `mockReturnValue` evaluates the factory eagerly at test-setup time; any `queueMicrotask` / `setTimeout` / `setImmediate` scheduled inside the factory fires BEFORE the SUT attaches its listeners, producing empty event data or an "uncaught error" test timeout. See `knowledge-base/project/learnings/test-failures/2026-04-17-vitest-mockReturnValue-eager-factory-async-event-race.md`. - A `vi.fn(() => value)` mock declared with a ZERO-parameter implementation cannot be invoked via a `(...args) => mock(...args)` forwarder (the standard `vi.mock` factory shape) — `tsc` rejects the spread with TS2556 "A spread argument must either have a tuple type or be passed to a rest parameter", even though the vitest run is GREEN (vitest type-checks test files lazily). Give the impl a rest param: `vi.fn((..._args: unknown[]) => value)`, matching sibling `vi.fn()` mocks. Only a standalone `./node_modules/.bin/tsc --noEmit` catches it. **Why:** #5817 — `execFileSyncMock = vi.fn(() => Buffer.from(""))` passed 36/36 tests but failed tsc. See `knowledge-base/project/learnings/test-failures/2026-07-01-vitest-zero-arg-mock-cannot-take-spread-suite-green-tsc-red.md`. - When the SUT `await`s something (`mkdtemp`, a config read, a lock) BEFORE it calls the mocked `spawn`/`fetch` and attaches listeners, emit the child's `close`/`error`/`data` events from INSIDE the spawn mock (`spawnMock.mockImplementation(() => { queueMicrotask(emit); return child; })`), NOT from a sibling top-level `queueMicrotask` in the test body. A test-level microtask scheduled right after calling the SUT fires during the pre-spawn `await` gap — before listeners exist — so the settle-once promise never resolves and the test times out (16s). The emit must be scheduled relative to when `spawn` is actually invoked. **Why:** PR #4970 — adding `await mkdtemp` before `spawn` in `c4-render.ts` timed out 6 tests until the emit moved inside the mock; see `knowledge-base/project/learnings/best-practices/2026-06-05-external-cli-exit-0-is-not-proof-validate-the-artifact.md`. - When using `vi.doMock("specifier", () => { throw new Error("X") })` to simulate a module-init failure, do NOT assert on the inner error message via the SUT's caller. Vitest wraps factory throws with its own synthetic Error (`"[vitest] There was an error when mocking a module..."`) and the inner string is unobservable. Assert on the SUT's observable contract (return shape, observability mirror call) instead — the throw is a *trigger*, not a *contract*. See `knowledge-base/project/learnings/2026-05-07-vitest-domock-factory-throw-wrapped-message.md`. - To prove a cache-hit skips work (not just that the response status is correct), wrap the real implementation in a spy via `vi.importActual` rather than stubbing the return value: `vi.mock("@/module", async () => { const actual = await vi.importActual(...); return { ...actual, expensiveFn: (...args) => { spy(...args); return actual.expensiveFn(...args); } })`. Stubbed returns break any downstream behavior that depends on the real output (hash-match, SQL row shape, etc.); wrapping preserves the contract while exposing call counts for assertions like `expect(spy).toHaveBeenCalledTimes(1)` across a HEAD+GET sequence. **Why:** In PR #2515, verifying that HEAD populates `shareHashVerdictCache` so a follow-up GET skips the SHA-256 drain required counting `hashStream` calls, not stubbing its return — a stubbed return would have broken the post-drain hash-equality check and masked the very regression the test was meant to catch. - When testing decorative images (alt="") with happy-dom, use container.querySelector instead of screen.getAllByRole("img", { hidden: true }) -- happy-dom excludes presentational elements from role queries even with hidden: true. - When asserting against a conditional render branch in a component test, grep the test file's `vi.mock(...)` factories for the inputs the branch reads and confirm the mock returns values that activate the target branch. Mocks that simplify (e.g., `getDisplayName: (id) => id.toUpperCase()`) often skip production branches like `leader.title.includes(displayName)` — assertions on the skipped branch fail for non-bug reasons. **Why:** PR #3427 — see `knowledge-base/project/learnings/2026-05-07-test-assertion-must-verify-mock-activates-branch.md`. - A wait-on-ABSENCE (`await vi.waitFor(() => expect(queryByTestId(x)).toBeNull())`) is vacuous — it passes on the FIRST tick, before the async work resolves, so it never proves "absent AFTER the state commit." Anchor the wait on a positive settle signal (e.g., a `.finally(() => { settled = true; })` flag on the mocked response body), then assert absence. Also: vitest's `vi.waitFor` and RTL's `waitFor`/`findBy*` have independent 1 s defaults and independent config surfaces — a global RTL `asyncUtilTimeout` bump does not touch `vi.waitFor` call sites. **Why:** #5113 — see `knowledge-base/project/learnings/test-failures/2026-06-10-parallel-load-flake-two-mechanisms-and-vacuous-absence-waits.md`. - An intermittent absence-wait that times out at the **FULL (explicit) timeout** is a component/state RACE, not a timeout-floor problem — raising the timeout cannot fix it. Discriminator: if the failing `vi.waitFor` site already carries an explicit `{ timeout }`, the floor is irrelevant; trace the component's effect ordering. A passive effect that resets state on EVERY render where a condition holds (`if (cond) setX(false)`) rather than on a `prev→curr` transition races any user action that should win (React runs passive effects AFTER commit, so it can land after the click and undo it) — gate such effects on the transition via a `prevValue` ref. **Why:** #5796 — see `knowledge-base/project/learnings/test-failures/2026-06-30-vi-waitfor-floor-vs-component-rearm-race.md`. - When testing a fallback ladder or mode option (primary-then-degrade, retry-then-cache, mergeMode direct→arm-auto-merge), assert the FIRST rung was *attempted* (the primary call fired), not just the fallback's effect — an effect-only assertion passes identically against an option-ignoring implementation whose default path yields the same end state. **Why:** PR #5133 — two mergeMode-direct fallback tests passed against the pre-#5111 helper; see `knowledge-base/project/learnings/2026-06-11-pipeline-consolidation-behavior-preserving-migration-traps.md`. - When adding `sessionStorage` usage to React components, ensure the component's test file includes `sessionStorage.clear()` in its `beforeEach` block. Shared jsdom environments leak sessionStorage between tests, causing ordering-dependent failures. - When adding a React-context-dependent hook (`useTheme`, `useRouter`, any provider-gated hook) OR a new provider import to a SHARED component, grep `test/` for every file that renders that component DIRECTLY (not via a `vi.mock` of its module) and add the provider stub in the SAME commit. `tsc` and the component's own test pass; sibling direct-render tests fail at RUNTIME with ` must be used inside `. **Why:** PR #5217 — `C4Canvas` gained `useTheme()`; `c4-fullscreen.test.tsx` (the only direct `` renderer) broke 8 tests until stubs for `theme-provider` + `@mantine/core` were added. See `knowledge-base/project/learnings/2026-06-12-likec4-mantine-color-scheme-seam-and-vendored-theme-preservation.md`. - To reproduce a provider's SSR-hydration "no-bootstrap" state in jsdom (lazy `useState` initializer landed on a server fallback like `"system"` WHILE durable storage holds the real value AND the DOM attribute is absent), do NOT use a `Storage.prototype.getItem` call-count spy — it bleeds across tests in the shared jsdom worker (passes in isolation, fails in-suite) and a leftover DOM attribute pollutes later inits. Instead use REAL localStorage (empty at init) and write the stored value from inside the `matchMedia.matches` getter (fires during the resolved-state initializer — after both init storage reads, before the first-mount effect); scrub the attribute + clear storage inside the mount helper and `cleanup()` in `afterEach`. Pair it with a precondition self-check (`if (!released) throw`) so a future init refactor that stops touching `matchMedia` fails as a clear FIXTURE error, not a phantom SUT regression. A naive client-only mount masks the bug (initializer reaches the durable value directly → vacuous green). **Why:** PR #5312 — see `knowledge-base/project/learnings/test-failures/2026-06-15-ssr-hydration-no-bootstrap-theme-test-gate.md`. - When asserting on `vi.getTimerCount()`, remember that `vi.useFakeTimers()` mocks every timer-like API by default — including `requestAnimationFrame`, `setImmediate`, `queueMicrotask`, `requestIdleCallback`. The count is a SUM across all fake timer types, not just `setTimeout`. Prefer stability assertions (`count before N extra calls === count after`) over magnitude assertions (`count === 1`) so refactors that add a well-behaved rAF or microtask don't falsely read as leaks. See `knowledge-base/project/learnings/test-failures/2026-04-17-vitest-getTimerCount-counts-requestAnimationFrame.md`. - When a component exports an interface that a test harness consumes (e.g., `ChatInputQuoteHandle`), have the test import it via `type X = ExportedInterface` — never shadow with a local duplicate. Duplicate interfaces silently drift when the exported type gains a method; the `tsc --noEmit` failure surfaces only at build time. - When adding a new npm dependency, check the installed major version (`node -e "console.log(require('/package.json').version)"`) and read the type definitions before using API from docs or training data. Library APIs change across major versions (e.g., `react-resizable-panels` v4 uses `Group`/`Separator`/`orientation`/`useDefaultLayout`, not v2's `PanelGroup`/`PanelResizeHandle`/`direction`/`autoSaveId`). - For sizing APIs from third-party libraries, always pass **explicit units as strings** (e.g., `"18%"`, `"100px"`, `"1rem"`) rather than bare numbers. Docstrings may claim a default unit but runtime parsers often treat numbers as pixels. **Why:** `react-resizable-panels` v4 doc said "Percentage of the parent Group (0..100)" for numeric sizes, but the runtime treated `18` as 18px, producing a ~18px-wide sidebar in production. Explicit units make intent visible at the call site and survive library version upgrades. **Test environment setup:** If the project's test runner cannot run the type of test needed (e.g., React component tests require jsdom but vitest is configured for node), set up the test environment BEFORE starting the task. This is part of RED — the test infrastructure must exist for the test to fail properly. - When configuring bun preload scripts that register DOM globals (e.g., happy-dom), use dynamic `await import()` for all subsequent dependencies — static ES imports are hoisted before any imperative code, causing libraries like @testing-library/react to initialize without DOM globals. See `knowledge-base/project/learnings/test-failures/2026-04-03-bun-test-dom-preload-execution-order.md`. - **Bash performs QUOTE REMOVAL on `word` in `${VAR:?word}`, so quotes there are consumed, not printed — and an UNBALANCED one is a whole-file parse error reported far from its cause.** `: "${d:?git -C '' would retarget}"` prints `git -C would retarget` (note the double space): the `''` never reaches the operator, so it buys nothing and costs the parse hazard. One extra apostrophe — a possessive like `caller's` alongside a `''` pair — makes three, and bash then reports `syntax error near unexpected token` at a line 150 below the real one. Write these messages quote-free (`git -C `), which removes the hazard class rather than balancing it, and run `bash -n` over the WHOLE file after any edit rather than eyeballing the edited region. **Why:** #7709 — hit twice on one branch, the second time after the trap was written into a commit message. See `knowledge-base/project/learnings/2026-09-03-every-p1-was-in-the-verification-not-the-fix.md`. - Never write a literal `*/` inside a `/* … */` / `/** … */` block comment — it closes the comment early. The trap is documenting a regex that ends in `*/` (`/--[^\n]*/g`, `foo/**/*`): esbuild/tsc then parses the trailing prose as code and reports `Expected ";" but found ` at a line deep inside the docstring (a red herring — the real cause is the stray `*/` upstream). Describe the regex in prose or use a `//` line comment; `grep -nF '*/' ` after authoring confirms every hit is real code. **Why:** #5920 — a `*/g` in a JSDoc comment broke collection of `byok-rpc-body-markers.test.ts`. See `knowledge-base/project/learnings/build-errors/2026-07-03-jsdoc-block-comment-closed-early-by-regex-star-slash.md`. - When a test file calls a SUT that lazy-imports a heavy module (`pdfjs-dist`, `sharp`, `puppeteer`, `playwright`, `@xenova/transformers`, `onnxruntime`), pre-warm the module in `beforeAll(async () => { await import(""); }, 30_000)`. The cold-start cost (~5-10s on CI runners) otherwise lands on the first `it()` and blows the default 5s vitest timeout — the second test in the same file runs at warm ~9ms because subsequent calls hit the module cache. Cheapest detection: `git grep -lE '(pdfjs-dist|sharp|puppeteer|playwright|@xenova/transformers|onnxruntime)' -- '*.test.ts'` and check for sibling `beforeAll`. **Why:** PR #3681 `pdf-text-extract.test.ts` cold-start flake (7s vs 9ms, #3687). - When uploading files via Playwright MCP, save files to repo-accessible paths (not `/tmp/`). Playwright MCP restricts file access to the repo root. When Google Search Console offers Cloudflare auto-verification, prefer "Any DNS provider" manual flow — the popup OAuth flow opens an external tab that crashes the Playwright browser context. - **Vendor-token extraction via Playwright MUST use `browser_evaluate(filename: ...)` from the FIRST attempt** — the return value otherwise enters the conversation transcript and the token is leaked even after revocation. AND the `filename` parameter JSON-encodes the result (surrounding quotes), so the canonical pipe is `python3 -c "import sys,json; sys.stdout.write(json.loads(open('').read()))" | doppler secrets set --no-interactive`. Validate via the vendor's API (HTTP 200 + length check) before shredding the file — some vendors silently tolerate quoted tokens via `Authorization: Bearer "abc"`, but Terraform's HCL parser does not. For `●●●`-masked UI tokens (Doppler personal tokens), click the in-page copy button via `browser_evaluate`, then `xclip -selection clipboard -o > `; clear with `xclip -i = N`, `floor == inventory count`, a derived-list equality, a run-time re-assertion) all held while one config was swapped for another, so reach shrank and the scan reported a clean `13/13`. Tightening the counts never closes it — they measure the wrong thing, which is exactly why the gap survives review. Assert the SET (e.g. a superset check against the merge base, with an explicit ack array for deliberate removals), and prefer the MERGE BASE over `origin/main`'s tip so an un-rebased branch does not red for a shrink it did not make. (b) An anti-vacuity `PASS + FAIL >= N` floor counts assertion CALLS, not BODIES: deleting the new guard's whole comparison loop still reported 61/61 and exit 0, because a gutted control still calls `pass()`. Give a loop-based assertion its own accounting (count what it examined, reconcile against the expected input size) and mutation-prove it — reading the guard is not sufficient, this one was written by someone who knew the vacuity class. **Why:** #7234 — see `knowledge-base/project/learnings/2026-08-04-a-count-framed-ratchet-cannot-see-a-rename.md`. - **NARROWING THE SCOPE IS NOT THE FIX — ANCHOR ON SYNTAX.** The bash body-grep rule below generalizes to EVERY source-reading assertion (`readFileSync` + `toContain`/`toMatch` over `.tf`/`.yml`/`.ts`), and the obvious correction — slice a narrower region — FAILS when a file puts explanatory comments INSIDE the construct: there is then no scope that holds the config but no prose. Anchor on something a comment cannot produce (`^\s*key\s*=` — a comment line starts with `#`; a call shape `Fn\(\s*arg`), never a bare word. Treat every `toContain` of a token that also appears in a nearby comment as guilty until mutation-tested, and give every slice helper an explicit lower bound plus an `indexOf === -1` guard (`slice(-1)` yields the last character, so `.not.toMatch()` against it always passes). **Why:** #6456 shipped FOUR — `/value\s*=\s*2/` matched its own "WHY value = 2 AND NOT 3" comment; `toContain("IssueOwners")` matched an in-body comment while the entire `actions_v2` block was deleted (the rule then paged nobody — the outcome the test was named for) and stayed 10/10 green; a boundless `scopeResource` swallowed the next resource's comment so a GROUPING-anchor check was satisfied by the pointer to the paragraph it was meant to find. All four were read-and-believed; only mutation caught them. Count failures from the runner's summary line after stripping ANSI — `grep -cE '^\s+×'` always returns 0. See `knowledge-base/project/learnings/2026-07-15-narrowing-is-not-anchoring-and-a-documented-class-recurred-four-times-in-one-pr.md`. - When adding a static-grep assertion over a SCRIPT BODY (a `.sh`/`.test.sh` body-grep gate, an AC `grep -n … | head -1` order check), anchor it on the syntactic write/call construct (`rest/v1/
`, a function-call shape) — NEVER a bare token (`
`, ``) that the same file also names in a COMMENT or header-inventory. A body-grep sees comments too, so the moment a task requires both a "must / must-not contain X" assertion AND documenting X in a comment, they collide: a negative `! grep -qE 'X'` false-FAILs on the explanatory comment, and a `grep -n X | head -1` order check returns the comment line, not the code. Reword forbidden-literal comments to drop the literal. Same class as the source-reading-regex rule above, for bash. **Why:** PR for #5501 — `seed-live-verify-user.sh`'s `user_session_state` upsert: the test's `! grep '/rpc/set_current_workspace_id'` tripped on a comment naming the RPC, and the AC3 bare `grep user_session_state` matched the new header-inventory line. See `knowledge-base/project/learnings/test-failures/2026-06-17-grep-assertion-over-script-body-false-matches-own-comments.md`. - When a drift-guard test EXTRACTS a substring (regex over SKILL.md/source) to compare against an **exact-equality production Set** (an allowlist, a carve-out, a canonical-literal set), the extraction must (a) span the SAME command/token boundaries the production checker uses — capture the FULL command, not a salient prefix; a verb-terminated `(?:list|ls)\b` lets `… list --json` extract the bare `… list` (a member) and pass GREEN while the real command is a non-member — and (b) match EVERY shape the producer can legitimately emit (optional `bash ` prefix, env-prefixed direct-exec) — an unmatched shape silently escapes the guard, it is not caught drift. Litmus: mentally mutate the producer (add a flag, drop the prefix, change the anchor) and confirm the test goes RED for each; `.trim()` the extract to mirror the checker's own normalization. Do NOT assert a failure *consequence* in the docstring you haven't traced in the gate code (e.g. "DENIED on server" when the path only degrades to the review-gate). **Why:** PR #6152 (#6121) — the plugin-root list/ls coupling test's regex false-GREENed on trailing-arg + no-`bash` drift; caught by test-design + user-impact review. See `knowledge-base/project/learnings/best-practices/2026-07-07-drift-guard-extraction-must-mirror-production-checker-boundaries-and-all-emission-shapes.md`. - When a bun-test file mutates `process.env.*` or `globalThis.*`, capture originals at module top-level (before any `describe`) and restore in `afterEach` using `delete` when the original was `undefined` — `bun test` runs every file in a single OS process, so mutations leak to sibling files and to any `spawnSync` subprocess launched after the mutation. Vitest isolates files in workers by default; bun does not, and has no built-in `stubEnv`/`unstubAllEnvs` equivalent. **Why:** PR #2579 — `bot-fixture-helpers.test.ts` stubbed `SUPABASE_URL` in `beforeEach` with no restore, causing 4 integration tests in `bot-fixture.test.ts` (same run) to ConnectionRefused against the stub host. See `knowledge-base/project/learnings/test-failures/2026-04-18-bun-test-env-var-leak-across-files-single-process.md`. - When a vitest test asserts a `process.env.X === "true"`-gated default-off path, add `vi.stubEnv("X", "")` to `beforeEach` regardless of whether the current Doppler/CI config injects the var. `vi.unstubAllEnvs()` reverts `vi.stubEnv` writes only — it CANNOT delete a process-inherited env var (Doppler dev / CI secrets / `direnv` / devcontainer envs). The test passes locally with plain `npx vitest run` and fails deterministically under `doppler run -p soleur -c dev -- npx vitest run` when the dev config flips the flag on. Tests that need the flag on continue to call `vi.stubEnv("X", "true")` in their own `it()` bodies — the local stub overrides the beforeEach default (overwrite-semantics). **Why:** PR #4141 (#4128) — `cc-dispatcher.test.ts > T-W4-basic-off` failed 1/1 under Doppler dev because `CC_PERSIST_USAGE=true` injection survived `unstubAllEnvs()`. See `knowledge-base/project/learnings/test-failures/2026-05-20-vitest-unstub-does-not-clear-process-inherited-env-vars.md`. - When a test uses retry-on-flake logic (network, LLM non-determinism, timing), collect every attempt into an array and assert the invariant across ALL attempts — not just the last. Early-return after retry silently drops first-attempt failures. If the retry exists to force a precondition (tool invocation, tool output presence), assert the precondition WAS met on the final attempt; a refusal on retry is a hard failure, not a silent pass. **Why:** PR #2610 FR2-smoke/FR8/FR9 originally used `if (!condition) { retry; return; }` which let attempt-1 leaks slip through. See `knowledge-base/project/learnings/test-failures/2026-04-19-retry-once-early-return-masks-first-attempt-failures.md`. - When adding Eleventy `_data/*.js` files: (a) name the file in camelCase matching a valid JS identifier — kebab-case filenames produce hyphenated template variables that Nunjucks dotted access cannot resolve; (b) keep the module **default-export-only** — sibling `export` statements silently disable Eleventy's data-module registration (no error, no warning, the benchmark log omits the file); attach test helpers as properties on the default export. Verify each new `_data/*.js` appears in the build's `Benchmark ... (Data) ...` log. **Why:** PR #2596 — see `knowledge-base/project/learnings/build-errors/2026-04-18-eleventy-data-module-loading-and-nunjucks-null-test.md`. - Nunjucks has **no** `is null` / `is not null` test — the parser accepts `{% if x is not null %}` but evaluates it unpredictably for numeric values. To distinguish `undefined` / `null` / `0`, precompute a boolean in the `_data/*.js` module (e.g., `{ stars, showStars: stars != null }`) or accept a truthy guard. **Why:** PR #2596 — see same learning file. - When a work task ports a TS regex normalizer to SQL (or vice versa) for a backfill migration, run every fixture from the TS unit test file through the SQL expression BEFORE committing the migration. Cheapest shape: a `WITH fixtures AS (VALUES (, ), ...) SELECT input, expected, AS actual, expected = AS ok FROM fixtures` query. The WHERE-clause idempotence guard (`col <> `) is necessary but not sufficient — it only catches drift on re-runs, not on first apply. Idempotence fixtures must include at least one repeated-suffix case per strip-class (`.git.git`, trailing `//`) so a `\.git$` that should be `(\.git)+$` is forced to fail. **Why:** PR #2817 — migration 031 had a P1 operator-precedence bug (`.git` stripped before trailing `/`) and a P2 non-idempotency bug (`bar.git.git`), both caught only at multi-agent review. See `knowledge-base/project/learnings/best-practices/2026-04-22-ts-sql-normalizer-parity-when-shipping-backfill-migration.md`. **IMPORTANT**: Always update the original plan document by checking off completed items. Use the Edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked. 3. **Incremental Commits** After completing each task, evaluate whether to create an incremental commit: | Commit when... | Don't commit when... | |----------------|---------------------| | Logical unit complete (model, service, component) | Small part of a larger unit | | Tests pass + meaningful progress | Tests failing | | About to switch contexts (backend → frontend) | Purely scaffolding with no behavior | | About to attempt risky/uncertain changes | Would need a "WIP" commit message (exception: UX artifacts use `wip:` prefix) | | UX specialist produces artifacts (wireframes, copy, brief) | Specialist is still generating (mid-output) | | Domain leader review cycle completes (feedback applied) | Review feedback not yet incorporated | | Brand guide alignment pass completes | Alignment still in progress | - When lefthook hangs during commit in a worktree (common with `core.bare=true` repos), verify typecheck and tests pass manually, then use `LEFTHOOK=0 git commit`. Always check for stalled lefthook processes (`pgrep -fa lefthook`) before retrying. - **`LEFTHOOK=0` also bypasses the `c4-model-regenerate` pre-commit hook.** If the diff edits a `.c4` file, run `bash scripts/regenerate-c4-model.sh` and stage the updated `model.likec4.json` BEFORE the `LEFTHOOK=0` commit — otherwise `c4-model-freshness.test.sh` reds — it is in the `scripts` shard, so include that shard in the Phase 2 touched-shard gate whenever the diff touches a `*.c4` file. `c4-render.test.ts`/`c4-code-syntax.test.ts` do NOT check the committed artifact. **Why:** #6549 — a `model.c4` edit committed under `LEFTHOOK=0` shipped a stale `model.likec4.json`. - After a `git mv old new`, never `git add old` (the pre-rename path) — the stale pathspec exits fatal `pathspec 'old' did not match` and ABORTS the entire `git add`, silently dropping every other path, so the commit captures only the rename (`0 insertions`). Stage the NEW path (or `git add -A `) and verify `git show --stat HEAD` shows the full expected file set before trusting the commit; a rename-only stat on a content change is the tell. **Why:** #6448 — a `git add …/docker-daemon.json` after renaming it to `.tmpl` produced a rename-only first commit; fixed by `--amend`. - **Never pass a commit message containing backticks via `git commit -m "…"` — bash command-substitutes them and the text is silently EATEN.** **The same trap has two more homes, and one of them is silent.** (a) A backtick inside a double-quoted BASH ARRAY ELEMENT is substituted the same way — `"path | reason x.md ..."` made a guard exit **127** with `x.md: No such file or directory`, which at least fails loudly. (b) A backtick inside an **unquoted** heredoc (`<` (Write the body first) or a quoted heredoc (`git commit -F - <<'EOF'` — note the quoted `'EOF'`, which is what disables substitution); verify with ``git log -1 --format=%B | grep '`'``. Same class as the `sed` replacement `&` trap: `&` expands to the whole match, so an unescaped `&` in a `sed` replacement silently duplicates the matched text. **Why:** #7035. - **When a commit needs a machine-readable trailer (`Allowlist-Widened-By:`, `Signed-off-by:`, `Reviewed-by:`, etc. — anything downstream parses via `git log --format='%(trailers:key=NAME,valueonly)'`), keep the FINAL paragraph as a pure contiguous block of `Token: value` lines.** Two silent-drop shapes: (a) blank line between the new trailer and `Co-Authored-By:` makes the former part of the body, not a trailer; (b) ANY non-key:value line in the final paragraph (e.g., `Closes #3877.`, `Refs #3874 (precedent).`) invalidates the WHOLE block — both legitimate trailer lines below it drop silently. Put `Closes`/`Refs`/`Fixes` in mid-body prose; GitHub auto-close still works anywhere in the body. Verify locally with `git interpret-trailers --parse < <(git log -1 --format=%B)` — empty output for a trailer that should exist is a hard fail. See `knowledge-base/project/learnings/2026-05-16-git-trailer-parser-requires-contiguous-key-value-block.md`. **Heuristic:** "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait." - **A mutation battery restores from a PRISTINE COPY, never from `git checkout` — and the fix it tests must be COMMITTED first.** `git checkout -- ` restores to HEAD, which is a different thing from "what I had a moment ago" in exactly the situation a battery runs in: a fix in flight. Measured: a P0 battery restored that way against an UNCOMMITTED fix, so row 1 reverted the fix and every later row scored the DEFECT against itself — two rows reported SURVIVED while measuring a file that no longer contained the thing under test. The only thing that caught it was the battery's own `diff pristine vs SUT` restore check at the end, which most batteries omit. Add that check, `cp` a pristine copy before row 1, and commit the unit before mutating it. **Why:** #7104 PR-B. See `knowledge-base/project/learnings/2026-08-19-my-battery-reverted-the-fix-it-was-testing.md`. - **A SURVIVING mutant is fixture-inadequate OR equivalent — decide which before touching the guard.** The reflex is "the guard has a gap", and the expensive version of this is a row that does not reproduce the attack it names: a composite bypass reconstructed as only its *balanced-phantom* half survived, correctly, because balanced phantoms around a genuinely-terminal assert perturb nothing. It read as a guard gap and was a FIXTURE gap. Reconstruct the attack exactly — every half, in order — before concluding anything about the guard, and record the finding in the row's own comment so the next reader does not re-litigate it. - **Commit each verified unit IMMEDIATELY — a worktree sync can revert uncommitted work with no warning.** `worktree-manager.sh` carries a "Syncing on-disk files from git HEAD" pass that restores tracked files to HEAD, and `.claude/hooks/guardrails.sh` can invoke it mid-session; anything verified-but-uncommitted is silently lost. Never hold verified work in the working tree across a long-running background job (a full test-all, a review agent). Where an edit must be followed by a commit, do BOTH IN ONE Bash call (`cat > file <<'EOF' … EOF; git add …; git commit`) so no window exists. Corollary: a reconciliation script that silently no-ops on a missing anchor (`python str.replace`, `sed s///`) will print success against a reverted file — assert the anchor (`assert old in s`) or the edit is unverified. **Why:** #6578 — two full re-applications of verified work; the revert was caught only because a re-run printed numbers that contradicted a result verified minutes earlier. **UX artifact heuristic:** "Did a specialist just produce or revise artifacts? If yes, commit with `wip: UX for feat-X`. UX artifacts are high-effort and low-recoverability -- err on the side of committing too often rather than too rarely." The `wip:` prefix is intentional -- UX artifacts are valuable at every revision stage, and WIP commits are squashed on merge with no impact on final git history. Do not run compound before UX WIP commits -- compound runs once in Phase 4. **Compound-before-commit scope:** AGENTS.md Workflow Gates says "Before every commit, run compound." Within this skill, that rule applies to the **final Phase 4 commit** (the one that closes the feature), not to Phase 2 incremental commits. Running compound per incremental commit is recursive (compound creates commits) and defeats the point of incremental checkpoints. A single compound at Phase 4 covers the whole feature's session-error inventory and learnings. **Commit workflow:** ```bash # 1. Verify tests pass (use project's test command) # Examples: bin/rails test, npm test, pytest, go test, etc. # 2. Stage only files related to this logical unit (not `git add .`) git add # 3. Commit with conventional message git commit -m "feat(scope): description of this unit" ``` **Handling merge conflicts:** If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused. **Note:** Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution. 4. **Follow Existing Patterns** - The plan should reference similar code - read those files first - Match naming conventions exactly - Reuse existing components where possible - Follow project coding standards (see CLAUDE.md) - When in doubt, grep for similar implementations - **An acceptance checkbox is a CLAIM — never bulk-toggle `- [ ]` → `- [x]`, and never append to a markdown table row past its closing pipe.** Two write-time foot-guns that both convert unverified work into work that reads as verified. (a) A bulk checkbox replace marks every AC "verified" at once with zero verification performed; run each AC's command and let the output decide (in #6781 a bulk toggle marked 15 ACs done and AC13 was then measured FALSE). This is the `session-state.md` decisions-are-intent rule applied to your own artifact in the same session. (b) Appending prose after a table row's trailing `|` creates a cell beyond the header count, and GFM **discards** it — so the text survives in raw markdown, passes any grep-based AC, and renders as though the edit never happened. That shipped an Article 30 statutory-register amendment that displayed as unamended. Cheapest gate after any table-row edit: `awk '{n=gsub(/\|/,"|"); print NR, n}' ` and compare the row's pipe count against a sibling row. See `knowledge-base/project/learnings/2026-07-21-the-guard-i-shipped-could-never-have-fired-and-my-fake-certified-it.md`. - **Before writing a new format, date, or util helper in any app, `ls` + grep the app's canonical `lib/` directory (e.g., `apps/web-platform/lib/`) for equivalents.** Canonical helpers are often single-purpose small files named by verb (`relative-time.ts`, `format-currency.ts`); typecheck and tests will not catch duplicated logic. See `knowledge-base/project/learnings/2026-04-17-grep-lib-before-writing-format-helpers.md`. - **When the plan says "mirror precedent X 1:1" but the new table/RPC reuses a precedent column for a NEW role X never had (a fencing token, a WORM-audit row, a portability-export field), enumerate the new role's invariants and check each against the precedent's lifecycle — a passing 1:1 mirror is NOT proof of correctness.** A precedent's guarantees hold only for the role it was built for: `acquire_conversation_slot` (029) is a concurrency slot, so its DELETE-on-release is correct there but silently breaks a *fencing-token* contract (the next acquire resets `lease_generation` to the column default → the git-data `reject gen < max` fence inverts into a write outage). The fix lives at the lock service, never the resource server; route the data-model fork to the `cto` agent. tsc + the precedent-cloned ACs pass green — only `architecture-strategist`, prompted with the downstream contract (the ADR), catches it. **Why:** #5274 PR A — DELETE-on-release vs ADR-068 §3 monotonic-max; CTO ruled tombstone-on-release. See `knowledge-base/project/learnings/best-practices/2026-06-30-precedent-mirror-for-new-role-breaks-fencing-token-monotonicity.md`. - **When the plan's specified path is wrong and you correct it during implementation, immediately `git grep` the corrected path's basename across the diff scope and fix EVERY secondary citation in the same edit cycle.** The plan often appears as an authoritative path source in multiple secondary artifacts (Article 30 register entries, runbooks, ADRs, README references); fixing only the primary landing site leaves a silent drift the reviewer must catch. The plan is authoritative for intent, never for paths (`hr-when-a-plan-specifies-relative-paths-e-g`). **Why:** PR #4287 — plan §6.2 named `knowledge-base/engineering/runbooks/cron-retention-monitor.md`; runbook landed at the correct `engineering/operations/runbooks/...` but the PA-20 Article 30 entry cited the plan's wrong path; caught at multi-agent review by `git-history-analyzer`. See `knowledge-base/project/learnings/2026-05-22-or-semantics-allowlist-inverse-lint-and-keyset-cursor-tiebreak.md`. - **When you DELETE an entity from an enumeration in prose, grep the SAME sentence/cell/bullet for clauses whose SUBJECT was that entity — a claim family is removed whole or not at all.** Deleting the head silently re-points its dependent clauses at whatever remains, which can make a FALSE claim strictly worse: bound to a named phantom (`…web-2 plus a dedicated git-data host. Stored workspace git data sits on a LUKS-encrypted volume…`) the tail reads as a claim about *that host*; unbound it reads as a claim about the **live** substrate. Litmus: after removing X from "…A, B, and X. X does P, Q, R." — ask *what does "does P" now attach to?* If the answer changed, you rewrote a claim you never meant to touch. Verify mechanically (per-file clause counts byte-identical to `main`), never by eye. Prose sibling of `cq-ref-removal-sweep-cleanup-closures`. **Why:** #6538/PR #6568 — removing a never-provisioned git-data host left its LUKS encryption-at-rest clause dangling onto `hcloud_volume.workspaces` (plain `ext4`), converting a scoped falsehood into a live false Art. 32 claim on the published privacy policy; 4 review agents converged, the edit cycle never saw it. See `knowledge-base/project/learnings/2026-07-16-removing-a-false-claim-can-strengthen-the-false-claim-that-leaned-on-it.md`. - **Sweep the SEMANTIC quantity, not its formatted representation.** A stale-figure sweep anchored on exact literals (`grep -E '176\.11|595\.82|92\.81'`) misses the same quantities written as rounded prose (`~$176/mo`, `4 paying users`, `~93%`) — and rounded prose is where *outward-facing summary sections* live, so the miss lands on the highest-consequence text. Enumerate the derived figures first (subtotal → each break-even → each margin → each rounded restatement), then grep per figure. Same root as `cq-assert-anchor-not-bare-token`. **Why:** #6538 — a "clean" sweep left §6 Pricing Gate asserting the exact `~93%` framing §5 retired one screen above. - **Before offering the operator options on a governed surface, read the governing rubric — an option the rubric forbids is not a choice, it is a trap.** Consent/versioning/retention surfaces carry signed policies (`knowledge-base/legal/tc-version-bump-policy.md`) that pre-decide the option space; presenting a forbidden option gets it chosen, then retracted. **Why:** #6538 — offered "repin SHA, no `TC_VERSION` bump" for a T&C edit; the CLO-signed rubric makes Tier 3 (no bump) *typos/whitespace/markdown only* and Tier 2 clarifying **BUMP REQUIRED**, tie-break *"if unsure, treat as clarifying"*. The operator's real intent (no forced re-acceptance) was served by not editing the T&C at all. - **When you INSERT or DELETE lines in a doc, every `path.md:N`/`:N-M` line-number citation pointing INTO that doc (from the plan, tasks.md, PIR, ADRs, sibling runbooks — including files this PR isn't "about") goes stale below the edit point.** After the insertion, `grep -rn ':[0-9]' knowledge-base/` and fix every hit in the SAME edit cycle; for churn-prone targets, prefer an insertion-stable section/anchor reference over a bare line range. tsc/tests are blind to prose offsets — review catches it as a P2 round-trip. **Why:** #5548 — a 10-line runbook §A callout shifted `:71-74`→`:81-84` and `:126`→`:132` across plan/tasks/PIR; caught by pattern-recognition + code-quality. See `knowledge-base/project/learnings/best-practices/2026-06-18-doc-insertion-stales-cross-artifact-line-citations.md`. - **Plan-prescribed redaction filters for captured-real fixtures are intent, never authority. Audit the filter against every secret-class the artifact can contain before executing it.** When a plan instructs "capture real provider output → run jq redaction → commit as fixture" (terraform-show-json, supabase log dumps, sentry event payloads, vendor API captures), the prescribed jq filter is a starting point — not a sufficient scrub. Same shape as `hr-when-a-plan-specifies-relative-paths-e-g`: plan is authoritative for intent (which fields to scrub), never for completeness (which fields exist). Concretely: for `terraform show -json` captures, **always** prepend `del(.variables)` regardless of the plan's prescribed filter — terraform-show-json embeds plan-input variables verbatim including `sensitive=true` declarations (`sensitive` masks render-time text output, NOT JSON serialization). After redaction, run a mandatory canonical scan: `! grep -qE 'BEGIN [A-Z ]*PRIVATE KEY|ghp_[A-Za-z0-9_]{20,}|ghs_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-ant-api03-[A-Za-z0-9_-]{20,}|sk_(test|live)_[A-Za-z0-9]{20,}|sbp_[A-Za-z0-9]{20,}|xoxb-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16}|dp\.(pt\|st\|sa\|ct)\.[A-Za-z0-9_-]{40,}' ` — must return rc=1 (no matches). A token-prefix-only scan (the plan's typical `no token values, no actor IDs` framing) misses PEM headers. **Why:** PR #4420 — the captured-real fixture initially shipped with the full GitHub App RSA private key embedded under `.variables.github_app_private_key.value`; caught at post-implementation multi-agent review by `security-sentinel` AFTER 9 other agents had read the file. Full incident post-mortem at `knowledge-base/project/learnings/security-issues/2026-05-25-terraform-show-json-leaks-sensitive-variables-into-fixtures.md`. Backstop: PreToolUse hook `git-commit-secret-scan.sh` runs gitleaks on the staged index at every `git commit` regardless of `.git/hooks/pre-commit` installation state. - **Before writing data-layer tests that use new PostgREST operators, read the shared mock helper (e.g., `apps/web-platform/test/helpers/mock-supabase.ts`) to confirm it covers every operator the code under test uses.** If not, extend it at the START of Phase 2, not after the first cryptic test failure. - **When a change adds or edits a Supabase embedded ``.select(`…`)`` against an UNTYPED client, neither `tsc` nor a select-arg-discarding mock catches a non-existent column — it ships green and errors with Postgres 42703 at runtime (silently returns `[]`). Add an arg-capturing select-string test (capture `chain.select.mock.calls[i][0]`, assert no `auth.users`-only column like `raw_user_meta_data`) AND/OR an opt-in `*.integration.test.ts` vs dev. The embed FK target `users` resolves to `public.users`, NOT `auth.users`.** See `knowledge-base/project/learnings/2026-06-01-untyped-supabase-select-nonexistent-column-ships-green.md` (#4715/#4713). - **A supabase-js `.update()/.delete().eq(...)` returns NO error when the WHERE matches 0 rows — a write whose success path returns 200 WITHOUT reading back what it wrote silently no-ops (the active id has no row / a stale resolved-id).** Append `.select("id")` and assert `data.length === 1` (`!== 1`, not `< 1`) → fail loud + distinct Sentry breadcrumb instead of a false success. A sound robustness guard — but do NOT assume a 0-rows no-op is the cause of a "didn't persist"-shaped bug without a live read proving the row is actually absent (see the cautionary case below). Mirrors `.update().select()` precedents in `account-delete.ts`/`ws-handler.ts`. See `knowledge-base/project/learnings/bug-fixes/2026-06-08-supabase-update-eq-zero-rows-silent-noop-and-code-trace-repro.md`. - **A route that 302-redirects a browser asset (``/`