session-orchestrator 3.22.0 → 3.23.0

package/rules/always-on/parallel-sessions.md

@@ -3,21 +3,95 @@
 
 Multiple Claude Code sessions may be active in the same working directory simultaneously. Another agent may be editing files, creating commits, or running builds right now. Treat the repo as a shared workspace, not a private sandbox.
 
-## Recognizing Parallel Work (PSA-001: Detect Before Acting)
-- **Unexpected git status changes:** Files modified or staged that are not part of your current task likely belong to another session.
-- **Unfamiliar commits:** New entries in `git log` that you did not create mean another agent (or the user manually) committed work.
-- **Spontaneous errors:** Build failures, type errors, or test failures in code you did not touch may be in-progress work from another session — not pre-existing bugs.
-- **Files changed between reads:** If a file's content differs from what you read moments ago, another session likely edited it.
-- **New untracked files:** Files appearing in `git status` that you did not create belong to someone else's work.
-
-## Behavioral Guidance (PSA-002: Ask, Don't Assume)
-- **When you detect signs of parallel work, stop and ask the user:** "I notice changes I didn't make (e.g., modified files in git status, new commits). Is another session active?"
+## PSA Scope Axes — Operator-Session vs In-Run
+
+PSA rules span two distinct axes. Naming them keeps clear which rule protects what:
+
+- **Operator-session axis:** independent parallel operator / Claude sessions in the **same working copy**. PSA-001..004, plus the per-repo session lock, guard this domain. Native in-run multi-agent primitives cannot enter it — they are per-process / per-session, never per-repo.
+- **In-run axis:** multiple agents coordinated inside a single session/run. Native agent-coordination features provide **no automatic isolation**: file-scope deconfliction (no two agents in the same wave may modify the same file) plus serialized STATE.md writes still do work the platform does not.
+
+PSA-005 spans **both** axes; only its session-lock half is purely operator-scoped. PSA-006 is **orthogonal** to both (Discovery grep-discipline). PSA-007 is in-run only.
+
+## Decision Tree — What To Do When You Detect Parallel Signals
+
+```
+Did I detect any parallel-session signal?
+│
+├─ No  →  Continue normally.
+│
+└─ Yes →  Does the signal originate from a SIBLING wave-agent dispatched in
+          THIS SAME wave (in-run axis — same dispatch round, the file sits
+          inside that sibling's declared file-scope per the wave plan) —
+          AND the file is NOT ALSO inside my own declared file-scope?
+          │
+          ├─ Yes →  NOT a PSA-002 case. Confirm the sibling's file-scope
+          │          ownership against the wave plan, then continue working —
+          │          note it PSA-001-style, do not pause. (PSA-007 governs the
+          │          in-run git-write rule.)
+          │
+          └─ No  →  Does the signal touch files/scope I own in this task?
+                    │
+                    ├─ No  →  PSA-001 (Aware): note the signal, continue
+                    │          working. Do NOT pause. Do NOT "fix" the foreign
+                    │          change.
+                    │
+                    └─ Yes →  PSA-002 (Pause): stop the current action, ask the
+                              user before proceeding. This branch also catches a
+                              file assigned to BOTH my scope AND a sibling's
+                              scope per the wave plan (a wave-plan deconfliction
+                              bug) — that overlap is a genuine in-run collision,
+                              never a benign sibling signal, so the sibling
+                              branch above may not mask it.
+```
+
+**Scope overlap examples (triggers PSA-002):**
+- A file you are about to edit is already modified by someone else.
+- Staged changes in `git diff --cached` include files you did not touch.
+- A build error appears in a file you just edited — but the error is in a line you didn't change.
+
+**No-overlap examples (stay at PSA-001):**
+- Unfamiliar commits in `git log` for modules you are not working on.
+- New untracked files in directories outside your file scope.
+- A test failure in a file not in your task's file-scope list.
+
+## PSA-001 — Aware (Passive Detection, No Pause)
+
+Detect and note parallel-session signals without interrupting your work. Continue normally when the signal does not overlap your owned files.
+
+**Signals to recognise:**
+- **Unexpected git status changes:** files modified or staged that are not part of your current task likely belong to another session.
+- **Unfamiliar commits:** new entries in `git log` that you did not create mean another agent (or the user manually) committed work.
+- **Spontaneous errors:** build failures, type errors, or test failures in code you did not touch may be in-progress work from another session — not pre-existing bugs.
+- **Files changed between reads:** if a file's content differs from what you read moments ago, another session likely edited it.
+- **New untracked files:** files appearing in `git status` that you did not create belong to someone else's work.
+
+**In-run caveat:** in a wave dispatched without per-agent isolation, unfamiliar modifications outside your own scope may simply belong to a sibling wave-agent's declared file-scope in the SAME dispatch round — disambiguate against the wave plan before logging it as a generic parallel-session signal (see PSA-007).
+
+**PSA-001 behaviour:**
+- Log the observation in your response narrative.
+- Do NOT pause, do NOT ask the user, do NOT "fix" foreign changes.
+- Continue with your assigned task in your own file scope.
+
+## PSA-002 — Pause (Active Conflict, Stop and Ask)
+
+When a parallel-session signal **directly overlaps your owned scope**, stop the current action and ask the user before proceeding.
+
+**Triggers (overlap = PSA-002):**
+- A file in your task's file-scope list has unexpected modifications you did not make.
+- `git diff --cached` includes staged changes you did not stage.
+- A file you need to write or edit is locked in an in-progress state by another session.
+- External changes block your task (e.g. a merge conflict in one of your files).
+
+**PSA-002 behaviour:**
+- Stop immediately — do not overwrite, merge, or work around the conflict.
+- Ask the user: *"I notice changes I didn't make in [file(s)] that are in my task scope. Is another session active?"*
+- Wait for user guidance before touching the affected file(s).
 - **Never "fix" code outside your task scope.** Errors in files you are not working on may be intentional intermediate states from another session.
-- **Stay in your lane.** Only read, create, modify, and delete files directly relevant to your assigned task.
 - **If blocked by external changes, ask the user** rather than reverting, resetting, or working around them.
 - **Track your own footprint.** Be aware of which files you have created or modified. Your commits should contain only your changes.
 
-## Destructive Action Safeguards (PSA-003: Never Destroy What You Didn't Create)
+## PSA-003 — Destructive Action Safeguards (Never Destroy What You Didn't Create)
+
 These commands require explicit user confirmation even in normal operation. When parallel work is suspected, they are **forbidden** without user approval:
 - **`git reset` (any form)** — destroys staged or committed work that may belong to another session.
 - **`git checkout -- <file>`** — discards uncommitted changes another session is actively building.
@@ -29,15 +103,71 @@ These commands require explicit user confirmation even in normal operation. When
 
 Before running any of the above, ask: "Did I create this file/commit/change? If not, it is not mine to touch."
 
-## Commit Discipline (PSA-004: Isolate Your Changes)
+## PSA-004 — Commit Discipline (Isolate Your Changes)
+
 - **Stage files individually** (`git add <file>`) rather than `git add .` or `git add -A`, which may sweep in another session's work.
 - **Review `git diff --cached` before committing** to verify every staged change is yours.
 - **If you see unfamiliar changes in the diff, unstage them** and ask the user.
 - **Never amend a commit you did not create.**
 
+## PSA-005 — Mechanical STATE.md Write Protection
+
+The behavioural rules above are complemented by mechanical enforcement. When `state-md-lock.enabled: true` is set in Session Config, every STATE.md write is wrapped by the plugin's session-lock helper (`withStateMdLock(repoRoot, fn)`), which guards an `.orchestrator/state.lock` lockfile using atomic tmp-file + rename acquisition with liveness-based stale detection.
+
+**What this mechanically enforces:**
+- **PSA-003:** a concurrent writer cannot overwrite STATE.md while another writer holds the lock. The race is structurally impossible — not merely discouraged.
+- **PSA-004:** STATE.md updates are serialised; no frontmatter update can be silently lost between two concurrent callers.
+
+**Bypass mechanics:** lock timeout defaults to 10s (`state-md-lock.timeout-ms`). On a stale lock (holder no longer alive) → atomic override + WARN on stderr. On genuine contention timeout → the caller receives a failure result and must decide whether to retry or abort.
+
+**When to use:** all STATE.md writers (session-start, inter-wave checkpoints, session-end), and any hook that mutates STATE.md.
+
+**When NOT to use:** STATE.md *readers* — locking readers serialises them with no safety benefit. The session lock is a separate, orthogonal domain: the session lock means "this working copy is occupied by an active session"; the state lock means "STATE.md is being written right now".
+
+## PSA-006 — Discovery Grep-Verification
+
+Discovery agents and exploration agents MUST verify any distributional claim — "100% of callers opt-in", "N of M sites use pattern X", "no remaining references to Y", "all instances replaced" — **and any bare number describing repo state** ("14 commits since the ref", "5 dirty files", "412 lines") with an EXECUTED measurement command: `grep`/`rg`/`find` for code locations, `git`/`wc`/`jq`/`ls`/`node` for repo state. The output MUST quote:
+
+1. The exact command executed.
+2. The file scope passed to the tool.
+3. The resulting count or zero-match assertion.
+4. WHEN it was measured — an ISO date, or the SHA / `HEAD` it was measured at. A fact re-used by a downstream wave hours later is a claim about the PAST unless it carries its measurement time.
+
+Untestable adoption claims based on inference, partial sampling, or model recall are **forbidden**. Coordinators reviewing Discovery output MUST REJECT claims that lack a quoted measurement transcript and ask for re-verification — even when the claim is plausible. Verification cost is cheap; mid-session correction cost is expensive.
+
+**When PSA-006 does NOT apply:**
+- Inline single-file reads — the file read IS the verification.
+- Claims about the behaviour of a SINGLE function — a focused test verifies, not a grep.
+- Hypotheticals stated as such ("if all callers opted in, ..." is a question, not a claim).
+
+**Mechanical enforcement:** when `discovery-validator.enabled: true` in Session Config, a `SubagentStop` hook scans the subagent's transcript tail for these claim patterns and records a violation event (plus a stderr WARN) whenever such a claim lacks an adjacent measurement transcript. The hook is log + warn only and never blocks the agent — it complements the rule rather than replacing the coordinator's REJECT obligation.
+
+## PSA-007 — Subagent Git-Write Prohibition
+
+*In-run axis. Distinct from PSA-003/PSA-004, which govern the COORDINATOR's own destructive-op and commit discipline; PSA-007 governs what a DISPATCHED SUBAGENT may touch of the shared VCS state.*
+
+The git index and stash are **shared resources of the working copy**, not a private workspace scoped to each dispatched agent. When a wave dispatches multiple subagents in parallel, a subagent that runs a git-write command competes with its siblings for the SAME `.git/index` and stash stack — observed failure modes include `index.lock` collisions and stash operations that silently discard sibling work-in-progress.
+
+**Dispatched subagents MUST NEVER run:**
+- `git add` / `git commit` — index writes race with a sibling agent's concurrent index write, even when each agent only stages its own files.
+- `git stash` (any form) — captures (and can drop) a sibling agent's uncommitted work; the sibling has no way to find or recover it.
+- `git mv` / `git rm` — index-mutating, same race class as `git add`.
+- `git push` — no subagent has the authority to publish; also destructive at the remote-history layer.
+- `git reset` / `git checkout -- <file>` — destructive to sibling work AND an index-write race; banned from subagents unconditionally, not only "when parallel work is suspected".
+
+**The only write channel a subagent has is editing files inside its own declared file scope.** All VCS operations — staging, committing, pushing — belong to the coordinator. This makes the PSA-004 guarantee structural rather than behavioural at the subagent layer: an agent that never touches the index cannot violate PSA-004 by construction.
+
+**Anti-patterns:**
+- A subagent running `git add <its own files>` "to be helpful" before reporting done — even scoped to its own files, it races the coordinator's staging pass and any sibling's concurrent index write.
+- A subagent running `git stash` to "save progress" before switching tasks — report `blocked` and let the coordinator decide, never stash.
+- A subagent running `git commit --no-verify` "just this once to unblock the wave".
+
 ## Anti-Patterns
+
 - Seeing unfamiliar changes and assuming they are "leftover mess" to clean up — they are likely active work.
 - Running `git reset --hard` to "start fresh" — this destroys all uncommitted work across all sessions.
 - Fixing type errors or lint issues in files outside your scope — the other session will handle their own files.
 - Using `git add .` in a shared workspace — you will commit another session's partial work.
 - Reverting "broken" commits without asking — another session may have intentionally pushed incremental progress.
+- Pausing at PSA-001 signals when your scope is unaffected — unnecessary interruptions slow the session.
+- A subagent staging or committing its own work (PSA-007).

package/rules/always-on/receiving-review.md

@@ -0,0 +1,108 @@
+<!-- source: session-orchestrator plugin (canonical: rules/always-on/receiving-review.md) -->
+# Receiving Code Review (Always-on)
+
+How the coordinator — and any agent receiving review output — handles feedback, and what a reviewer owes in return. The default failure mode is performative agreement: accepting before verifying, then half-implementing a wrong suggestion.
+
+## RCR-001: The 6-Step Pattern
+
+When you receive review output containing feedback items, process them in this order. Do NOT skip steps.
+
+1. **READ** — every item, in full, never just the summary. Reviewers nest the actionable detail below the headline.
+2. **UNDERSTAND** — restate each item in your own words. Cannot restate it precisely? Re-read the code the reviewer cited.
+3. **VERIFY** — check the claim against the codebase: is the cited file still shaped that way, the function still on that line? Reviewers can be wrong, especially after recent edits.
+4. **EVALUATE** — improvement, stylistic preference, or misunderstanding? Project conventions (the rules directory, the project instruction file) are the tiebreaker.
+5. **RESPOND** — per item: accept, modify, or push back, each with its rationale. Never accept silently — the rationale is the audit trail.
+6. **IMPLEMENT** — one item at a time, running the verification command after each (`verification-before-completion.md`).
+
+## RCR-002: Forbidden Phrases
+
+Signals that you skipped steps 2-4. Forbidden in any response to review feedback:
+
+- "You're absolutely right!"
+- "Great point!"
+- "Excellent feedback!"
+- "Let me implement that now" (before VERIFY + EVALUATE)
+- "Thanks for catching that!" / "Thanks for [anything]" — gratitude standing in for analysis, before verifying it is a catch
+
+Replace these with: a restatement (UNDERSTAND), a verification reference (VERIFY), and a decision (EVALUATE).
+
+## RCR-003: Source-Specific Handling
+
+| Source | Default posture | Why |
+|---|---|---|
+| **Human user (the operator)** | Trust-after-understanding — restate, verify, then implement | Operator usually has context you do not |
+| **Automated reviewer agents** (architect, QA, analyst personas) | Skeptical — verify against codebase before accepting | Agent output can lag behind the most recent edits |
+| **Security reviewer** | Take seriously, verify scope | Security findings have asymmetric cost — false positives are cheaper than false negatives |
+| **Automated quality gates** | Mechanical — typecheck/lint failures are facts, fix them | Automated tool output is rarely wrong, often surprising |
+| **External code review (PR comments)** | Skeptical, push back if wrong | External reviewers lack project context |
+
+The default posture is **skeptical** unless explicitly overridden — falsely accepting a wrong suggestion costs as much as implementing a bad feature.
+
+## RCR-004: YAGNI Check (Especially for "Implement Properly")
+
+When a reviewer suggests "implement X properly" / "add validation for this case" / "make this configurable":
+
+1. **Grep for usage**: is the code path the reviewer cites actually called in production? `git grep <function-name>` + `git log -p -- <file>`
+2. **Check the call site**: does the caller actually pass the inputs the reviewer's hypothetical case would trigger?
+3. **If unused**: suggest REMOVAL (the dead code is the real problem) instead of "implementing properly"
+4. **If used but the case is impossible at the call site**: push back with the call-site analysis
+
+## RCR-005: Implementation Order
+
+Multi-item review responses follow this order:
+
+1. **Clarify first** — items that reference each other ("fix X AND consider Y"): ASK before partial-implementing. Partial implementations of related items create incoherent intermediate states.
+2. **Blocking items** — anything stopping the work (a type error your edit introduced) goes first.
+3. **Simple items** — no dependencies; batch them.
+4. **Complex items** — needs its own design discussion; surface as a question first.
+
+Verify after each step before moving on (RCR-001.6).
+
+## RCR-006: Push-Back Posture
+
+You are allowed — and expected — to push back on review feedback that is wrong.
+
+Cite one of three: the codebase ("the function at file:line already handles this — the check would duplicate"), the convention ("per the project rule the pattern is Y, not Z"), or the trade-off ("surface area without a prevented failure mode").
+
+Push-back is a feature, not a bug: an implementer who never pushes back implements every wrong suggestion.
+
+## RCR-007: Four-Class Finding Triage
+
+Classify every finding into **exactly one** class before patching:
+
+| Class | Meaning | Action |
+|---|---|---|
+| **`in-scope-blocker`** | Introduced by this diff, same owner boundary, fixable without changing the task's contract | Fix this cycle |
+| **`same-pattern-sweep`** | The identical defect recurs at further sites, all inside your own file scope, none needing a contract change | Fix every site this cycle |
+| **`follow-up`** | Real, but an adjacent bug class or sibling surface | Route to a follow-up issue |
+| **`stop-and-escalate`** | The correct fix would break the frozen scope | Never patch, however small — escalate |
+
+`same-pattern-sweep` needs all four, else the finding is `follow-up`: identical pattern (one edit shape fixes every site, not merely a related bug class); every site inside your file scope; none whose fix changes a contract (that site is `stop-and-escalate` and ends the sweep); population ENUMERATED by a quoted census of CALL SITES — not files, and not a payload-keyed grep, which misses consumers pinning only the channel (`parallel-sessions.md` § PSA-006). Cannot enumerate it → a suspicion, not a sweep; out-of-scope sites go to `follow-up` with the census.
+
+`stop-and-escalate` triggers — exactly these five, nothing else: (1) a new protocol, (2) a new config surface, (3) a storage change, (4) a public-API contract, (5) a different owner boundary or a release-process change.
+
+Frozen-scope exceptions — exactly these five, nothing else: (1) active data loss, (2) crash, (3) broken install/upgrade, (4) release blocker, (5) concrete security exposure.
+
+Before invoking `stop-and-escalate`: name which of the five applies, show that no in-scope-blocker subset resolves the finding without crossing it, and hand the operator both — escalating IS the action, never a workaround commit.
+
+## RCR-008: Two-Cycle Reclassify
+
+After two fix cycles without a **strict decrease** in blocking findings: pause, reclassify every remaining finding. A third cycle starts only if every finding is still `in-scope-blocker`; otherwise move the smallest safely-landable subset forward and the rest to `follow-up`.
+
+**Landing-lane hygiene**: no stacked, no pushed fix commits while a classification or a focused proof is open. Edits stay local until the cycle is proven in-scope.
+
+A retry cap **stops** on budget; RCR-008 forces **reclassification**. They are different instruments — do not substitute one for the other.
+
+## RCR-009: Depth, and the Reviewer's Authority
+
+A review that only confirms has not reviewed: report the surfaces examined and found SOUND and the suspicions MEASURED AWAY, not findings alone — otherwise the next pass re-opens the same file to learn what you already know. And a reviewer MAY REFUSE an instruction it can REFUTE, provided the refusal carries the measurement and never a preference (the reverse of RCR-006; complying against a measurement you already hold is the costlier error). Self-review is a precondition of handoff, never a substitute — nor is a green gate.
+
+## Anti-Patterns
+
+- Accepting before VERIFY — gratitude, "great point", or a reviewer claim taken as fact without grep-verification (RCR-001/002)
+- A review that returns findings only, or an agent that complies with an instruction it can measurably refute (RCR-009)
+- One site fixed with its enumerated siblings left standing (RCR-007)
+
+## See Also
+
+verification-before-completion.md · ask-via-tool.md · parallel-sessions.md · test-value.md · build-value.md

package/rules/always-on/test-value.md

@@ -0,0 +1,40 @@
+<!-- source: session-orchestrator plugin (canonical: rules/always-on/test-value.md) -->
+# Test Value Over Test Volume (Always-on)
+
+A test earns its place by catching a bug the existing suite would miss. Volume is a cost, not an achievement. This rule is always-on because the "write this test / don't" decision is made in implementation work, where path-scoped testing rules are not loaded.
+
+## TV-001: The Core Question (before writing any test)
+
+Name the concrete bug this test would catch that the existing suite does not. If you cannot name it, do NOT write the test — report `no-tests-needed: <reason>` instead. That report is a SUCCESS outcome, not a gap.
+
+## TV-002: Deletion Is a Feature
+
+A test MAY be deleted or consolidated without approval ceremony when it (a) fails TV-001's falsification check, (b) duplicates behaviour another test already covers, or (c) pins the prose or structure of documentation (`.md` content assertions). Count removals in your reported test delta — a negative test delta is a valid, reportable result.
+
+## TV-003: Budget Corridor (advisory)
+
+Target a tests:src LOC ratio of ≤ 1.60. Above that ceiling, the next quality pass is a CONSOLIDATION pass: no new test lands without removing a redundant one. The corridor bounds test VOLUME only — the project's coverage floor is unchanged and still binds.
+
+**Measure the ratio with a script, never by hand.** While the recipe lived only in prose, six numbers for the one metric were in simultaneous circulation, differing only in which files each measurer chose to count. A threshold steered by six numbers is steered blind. Pin the recipe in code and cite its output: **numerator = tracked code under the test directory; denominator = every other tracked code file** (src by negation, so a new top-level directory is counted the moment it is committed), counting physical lines including blanks and comments. The number is reproducible at a SHA only when the working tree is clean.
+
+The ceiling is derived from measurement, not aspiration. An unreachable ceiling only manufactures standing deletion pressure with no nameable target per file — the precise thing TV-001 and TV-002 forbid. The consolidation rule above is the operative instrument; the ratio is merely the trigger that switches it on.
+
+**Corridor, not ratchet — deliberately.** A bidirectional ratchet (baseline the current value; fail the build on any worsening AND on any un-banked improvement) fails three ways: (a) the un-banked-improvement half turns deleting worthless tests — which TV-002 calls a *feature* — into a build break; (b) the worsening half forces a compensating deletion with no nameable target per file the moment a legitimate new test lands; and (c) a ratchet on a *ratio* is satisfiable by adding production LOC, an incentive that catches no bug. What this rule needs is a trustworthy number, not a tripwire — so the ratio check reports the consolidation trigger and is not wired into a blocking gate.
+
+## TV-004: Duplication Check Before Writing
+
+Grep for an existing test of the same behaviour first. Extend or parametrize that test instead of adding a sibling case or a near-duplicate file.
+
+## TV-005: Where Bugs Are Actually Caught
+
+Measured across a multi-repo fleet: of 27 escaped bugs, 0 were caught by the unit-test corpus and 9 by a review panel. Prefer, in this order: wiring/contract tests exercising the real production call shape; golden fixtures derived from real production records; lint/AST gates for structural invariants, which hold repo-wide where a test holds for one case. Unit-test volume is the last resort, not the first.
+
+## Anti-Patterns
+
+- Writing a test because the task said "add tests", with no nameable bug (TV-001).
+- Asserting that a sentence is present in a `.md` file — that pins prose, not behaviour (TV-002c).
+- Treating a coverage drop caused by DELETING worthless tests as a regression (TV-003).
+
+## See Also
+
+build-value.md · verification-before-completion.md · receiving-review.md · npm-quality-gates.md

package/rules/always-on/verification-before-completion.md

@@ -0,0 +1,77 @@
+<!-- source: session-orchestrator plugin (canonical: rules/always-on/verification-before-completion.md) -->
+# Verification Before Completion (Always-on)
+
+Evidence before assertions. If you have not run the verification command in this message, you cannot claim it passes. This rule exists because the most expensive failure class in a long-lived repo is the silent regression that ships behind a "should work" claim.
+
+## The Iron Law
+
+> **NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**
+
+"Fresh" means: in the current message thread, within the last few tool calls, against the current working tree. A test result from 5 minutes ago no longer counts if you have written code since. A type check from before the last edit no longer counts.
+
+## VBC-001: The Gate Function
+
+Before any claim of completion ("done", "passes", "green", "complete", "fixed"), run this gate:
+
+1. **IDENTIFY** — name the specific command that verifies the claim (the project's test / typecheck / lint command, `gh pr checks`, `glab ci status`, `curl <url>`, …)
+2. **RUN** — execute the command completely. Do not extrapolate from partial output. Do not skip flags ("the long version is slow" is not an exception).
+3. **READ** — read the FULL output (not just the last 5 lines) and check the exit code. Many test runners report "PASS" lines for individual cases while exiting non-zero overall.
+4. **VERIFY** — confirm the output actually demonstrates the claim. "312 passed" verifies "tests pass". "312 passed / 7 failed" does NOT verify "tests pass" even though the first number is impressive.
+5. **STATE** — make the claim, quoting the evidence: "Tests pass: 312 passed / 0 failed / 12 skipped (exit 0)" — never "Tests pass" alone.
+
+## VBC-002: Banned Phrases
+
+The following phrases are forbidden when used to characterize completion without fresh evidence. They are signals that the Gate Function was skipped.
+
+- "should work now" / "should pass" / "should be fine"
+- "I'm confident" / "I believe" / "I'm pretty sure"
+- "looks correct" / "looks right" / "looks good"
+- "Great!" / "Perfect!" / "Done!" / "Excellent!"
+- "Just this once" / "I'll verify later"
+- "Agent said success" — the agent's word is not evidence; the verification command is
+
+If you catch yourself typing one of these without the verification evidence in the SAME message, stop. Run the command first, then state the claim with the evidence inline.
+
+## VBC-003: Common Failures Table
+
+| Claim type | Required verification | Common shortcut to avoid |
+|---|---|---|
+| "Tests pass" | The project's test command exits 0 + per-file count | "I ran one file" |
+| "TypeScript clean" | `tsgo --noEmit` / `tsc --noEmit` exit 0 | "The file I edited compiled" |
+| "Lint clean" | The project's lint command exits 0 | "The editor extension shows no errors" |
+| "CI green" | `glab ci status` / `gh pr checks` on the current SHA | "Last pipeline was green" (last week) |
+| "Migration applies" | A reset against a clean database succeeds | "It worked on my dev DB" |
+| "Endpoint works" | `curl <url>` returns expected status + body | "The browser showed it" |
+| "Hook fires" | Trigger the hook event + read the resulting log line | "The hook config looks right" |
+| "Issue closed" | `gh issue view <N>` / `glab issue view <N>` shows state=closed | "I commented `closes #N`" |
+| "Subagent edit persisted" | `git diff --stat` / `--name-only` shows the declared file(s) changed after the agent reported done | "The agent reported done" |
+
+## VBC-004: Exceptions (Narrow)
+
+These are the only acceptable contexts in which a verification command may be deferred:
+
+1. **Read-only exploration**: claims about CODE STATE (not behavior) can cite a file read instead of a command run. "The function is at file:line" verifies via a read, not via test execution.
+2. **Coordinator orchestration**: claims about SUBAGENT outputs (not your own work) cite the agent's reported status — but the coordinator accepts that status only paired with its OWN `git diff --name-only` evidence that the agent's declared files actually changed. An agent's word is a claim, not proof of a filesystem effect. The agent itself must have followed VBC-001 — the coordinator's claim is "agent reported done with evidence X, confirmed changed in `git diff --name-only`", not "the work is done" on the status alone.
+3. **Documentation-only changes**: changes to `*.md` files that affect no code paths can skip test runs. They still require typecheck/lint if those tools touch markdown.
+
+If you think you have a fourth exception, you do not. Run the command.
+
+## VBC-005: Why This Is Strict
+
+- The most expensive failures are the ones a claim covers up.
+- "Should pass" claims are not falsifiable — they invite no challenge and produce no learning. Evidence-anchored claims either pass or surface a real problem; both outcomes have value.
+- Verification commands are cheap. Investigating a regression days after the fact is expensive. The cost ratio is at least 10:1, often 100:1.
+- Treat this rule with the same enforcement weight as the ask-via-tool and destructive-action safeguards: the default is the command, and skipping it requires an explicit named exception above.
+
+## Anti-Patterns
+
+- Claiming "tests pass" without running the test command in the current message
+- Citing a test run from before the last edit
+- Quoting only the success count when failures exist ("312 passed" suppressing "/ 7 failed")
+- Saying "should work now" instead of running the verification
+- Treating an agent's reported "done" as evidence (it's a claim that needs its own verification)
+- Skipping verification because "the change is trivial"
+
+## See Also
+
+npm-quality-gates.md · ask-via-tool.md · parallel-sessions.md · receiving-review.md · test-value.md · build-value.md