@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/code-improvement/references/deepening-signals.md

@@ -0,0 +1,205 @@
+# Deepening Signals
+
+Reference for the five improvement signals used by `sp:code-improvement`. Each entry defines the
+symptom, the diagnostic, the deepening direction, and a concrete example.
+
+These signals are adapted from the deep-module principle (a module's interface should be narrower
+than its implementation) and the seam/locality/test-surface heuristics for structural health.
+
+---
+
+## 1. Shallow Module
+
+**Symptom:** A module whose interface is as complex as its implementation. The caller must
+understand the module's internals to use it correctly — the abstraction leaks because there is no
+abstraction, only a pass-through.
+
+**Diagnostic:**
+
+- Count the exported symbols. Count the non-exported implementation lines.
+- If `exported_symbols / implementation_lines ≈ 1` (every line is exported, or the body is a
+  single delegation), the module is shallow.
+- A wrapper that only forwards to another module is the classic case.
+
+**Deepening direction:** Either collapse it into its caller (inline the delegation) or give it a
+real body (move logic from the caller into the module so the interface narrows).
+
+**Example:**
+
+```typescript
+// shallow: the service just forwards to the DAO
+export class UserService {
+    constructor(private dao: UserDao) {}
+    getUser(id: string) { return this.dao.findById(id); }      // pass-through
+    createUser(data: UserInput) { return this.dao.insert(data); } // pass-through
+    updateUser(id: string, data: UserInput) { return this.dao.update(id, data); } // pass-through
+}
+```
+
+Deepening: move the validation and event emission (currently in the route handler) into the
+service, so the service's interface (`createUser`) is narrower than its body (validate → insert →
+emit event).
+
+---
+
+## 2. Tight Coupling
+
+**Symptom:** Two modules that must change together. A change to module A forces a coordinated
+change to module B. Often caused by shared mutable state, deep relative imports, or a shared
+concrete class instead of an interface.
+
+**Diagnostic:**
+
+- Grep for imports of module B inside module A's directory and vice versa (bidirectional).
+- Check `git log --oneline` for files in A and B that change in the same commits.
+- Look for a concrete class shared across a package boundary (no interface seam).
+
+**Deepening direction:** Introduce a seam — an interface, an event, or a DTO — so A depends on an
+abstraction, not B's concrete implementation.
+
+**Example:**
+
+```typescript
+// tight: the route handler imports the concrete DAO
+import { UserDao } from '@gobing-ai/spur-domain';              // deep relative import across package
+router.post('/users', async (c) => {
+    const dao = new UserDao(c.env.db);                         // direct construction
+    const user = await dao.insert(c.body);                     // no seam
+});
+```
+
+Deepening: inject a `UserRepository` interface (owned by app, implemented by domain) so the route
+handler depends on the abstraction, not the concrete DAO.
+
+---
+
+## 3. Wrong Seam
+
+**Symptom:** The abstraction boundary is in the wrong place. Domain types leak across a transport
+seam; a service imports a DAO directly instead of through a repository; config validation lives in
+the HTTP layer instead of the config package.
+
+**Diagnostic:**
+
+- Draw the intended layer boundaries (e.g., `apps/server` → `packages/app` → `packages/domain`).
+- Grep for imports that cross a boundary in the wrong direction (e.g., `packages/domain` importing
+  from `apps/server`, or transport DTOs in `packages/contracts` containing domain types).
+- Check for a service that returns a domain entity instead of a DTO.
+
+**Deepening direction:** Move responsibility across the seam so the boundary matches the
+dependency direction. Domain types stay in domain; transport DTOs stay in contracts; services
+map between them.
+
+**Example:**
+
+```typescript
+// wrong seam: a transport DTO contains a domain entity
+// packages/contracts/src/users.ts
+import { User } from '@gobing-ai/ts-db';                       // domain type in transport contract
+export interface UserDto {
+    user: User;                                                // domain leak
+}
+```
+
+Deepening: define `UserDto` with primitive fields in `packages/contracts`; map `User → UserDto`
+in the server handler. The contract no longer depends on domain.
+
+---
+
+## 4. Weak Locality
+
+**Symptom:** Related logic is scattered across modules. A single responsibility (e.g., "user
+creation") is spread across a route handler, a service, a DAO, a validator, an event emitter, and a
+test factory — each with one line of the logic. Reading the feature requires opening six files.
+
+**Diagnostic:**
+
+- Pick a feature (a verb, e.g., "create user"). Grep for the feature name across the scope.
+- If the implementation is spread across N files with no single module that owns the full
+  flow, locality is weak.
+- Check for "co-located by layer" (all routes together, all services together) instead of
+  "co-located by feature."
+
+**Deepening direction:** Co-locate by responsibility. Group the route, service, validator, and
+event emitter for a feature into one module/directory so the full flow reads top-to-bottom.
+
+**Example:**
+
+```
+src/
+  routes/users.ts        // 1 line of createUser
+  routes/orders.ts       // 1 line of createOrder
+  services/users.ts      // 1 line of createUser
+  services/orders.ts     // 1 line of createOrder
+  dao/users.ts           // 1 line of insert
+  dao/orders.ts          // 1 line of insert
+```
+
+Deepening: co-locate by feature —
+
+```
+src/
+  users/
+    route.ts             // full createUser flow
+    service.ts
+    dao.ts
+  orders/
+    route.ts
+    service.ts
+    dao.ts
+```
+
+---
+
+## 5. Poor Test Surface
+
+**Symptom:** Core logic can only be tested by standing up a large stack — a real database, a server,
+a full request cycle. The logic isn't pure; it's entangled with I/O.
+
+**Diagnostic:**
+
+- Try to write a unit test for the core logic (the business rule, not the I/O).
+- If the test requires a database, a server, or a mock of a large dependency graph, the test
+  surface is poor.
+- Look for a function that mixes pure logic with I/O (e.g., `async createUser` that both validates
+  AND inserts AND emits an event).
+
+**Deepening direction:** Extract the pure logic into a function with no I/O, and test that. Inject
+the I/O (database, event bus) at the boundary.
+
+**Example:**
+
+```typescript
+// poor surface: validate + insert + emit are entangled
+export async function createUser(input: UserInput, db: Database, events: EventBus) {
+    if (!input.email.includes('@')) throw new Error('invalid email');  // pure logic
+    const user = await db.insert(input);                              // I/O
+    await events.emit('user.created', user);                           // I/O
+}
+```
+
+Deepening: extract the pure validator —
+
+```typescript
+export function validateUser(input: UserInput): void {
+    if (!input.email.includes('@')) throw new Error('invalid email');  // pure, trivially testable
+}
+export async function createUser(input: UserInput, db: Database, events: EventBus) {
+    validateUser(input);
+    const user = await db.insert(input);
+    await events.emit('user.created', user);
+}
+```
+
+Now `validateUser` has a test surface independent of the stack.
+
+---
+
+## Applying the Signals
+
+- **One module can hit multiple signals.** Record each as a separate candidate.
+- **Signals compound.** A shallow module with tight coupling is worse than either alone; bump the
+  severity one level.
+- **Severity is contextual.** A shallow module in a hot path is `major`; the same module in a
+  seldom-touched corner is `advisory`.
+- **No signal hit is a good outcome.** Emit "No deepening candidates found in scope" — do not pad.

package/plugins/sp/skills/code-review/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: code-review
+description: "Pre-commit self-review checklist, structured review requests, and processing review findings into tasks. Triggers: \"review this\", \"self-review\", \"pre-commit check\", \"code review\", \"review my changes\", \"check before commit\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - self-review
+    - request-review
+    - process-findings
+see_also:
+  - sp:code-verification
+  - sp:code-implementation
+---
+
+# sp:code-review — Code Review Workflow
+
+Two workflows: **pre-commit self-review** (catch issues before they leave your machine) and **requesting/receiving agent review** (structured context for deeper review). This skill owns the review *workflow*; `sp:code-verification` owns post-implementation SECUA review within the pipeline.
+
+## Workflow A — Pre-commit self-review
+
+Run before `git commit`. Catches 60-80% of issues that a reviewer would flag.
+
+1. **Diff it:** `git diff --cached` (or `git diff` if unstaged). Read every changed line.
+2. **Checklist:** Walk the [self-review-checklist.md](references/self-review-checklist.md) — type-safety, null-handling, error-propagation, test-coverage, security-surface. Each category has diagnostic questions.
+3. **Fix:** Anything the checklist flags → fix before committing.
+4. **Commit:** Only when the checklist is clean.
+
+## Workflow B — Requesting agent review
+
+When you want a deeper review (SECUA, architectural, or second-opinion):
+
+1. **Prepare a structured brief** and prefer a fresh reviewer context/subagent when available:
+
+   ```markdown
+   WHAT_WAS_IMPLEMENTED:
+   <one paragraph>
+
+   PLAN_OR_REQUIREMENTS:
+   <task WBS, requirements, AC, or design refs>
+
+   DIFF_RANGE:
+   <base sha>..<head sha> or "working tree"
+
+   FOCUS_HINTS:
+   <security | correctness | architecture | specific concern>
+   ```
+
+2. **Attach evidence:** include the relevant `git diff`, self-review results (Workflow A output), and
+   any verification commands already run.
+3. **Request:** Invoke `sp:code-review` directly or trigger via "review my changes", "review this diff".
+4. **Receive:** The reviewer produces a P1–P4 findings table.
+
+## Workflow C — Processing review findings
+
+When you receive review findings:
+
+1. **Verify each finding against the codebase first.** A finding can be stale or based on a misread;
+   cite the file/line that proves it before changing code. Reasoned pushback is allowed.
+2. **Fix in priority order:** blockers first (P1), then simple P2 fixes, then complex P2 fixes. Keep
+   unrelated refactors out of the review-response diff.
+3. **Test each fix individually** with the narrowest command that proves it, then run the task gate.
+4. **Re-review:** After all P1/P2 fixes, request a follow-up review to confirm resolution.
+5. **File follow-up tasks** for deferred P3/P4 items via `spur task create --template review`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It looks good to me — approve." | "LGTM" with no specific findings is not a review; it's a rubber stamp. State what you checked and what you found, with anchors. |
+| "It's a small diff, skim it." | Small diffs ship real bugs. Size does not lower the bar; run the same lenses regardless. |
+| "The author knows this area better — trust them." | Deference is not review. Your job is the independent second pair of eyes; verify, don't assume. |
+| "I'll soften this finding so it doesn't sound harsh." | Softening a real finding is dishonest and lets the defect through. State severity plainly; the diff, not the author, is under review. |
+| "There's dead code — I'll just delete it." | Deleting code you don't fully understand is risky. Identify it, list it, and ask before removing (Chesterton's Fence). |
+| "A new dependency is fine for this one helper." | Prefer stdlib / existing utilities. Flag every new dependency; a one-function import is rarely worth the supply-chain cost. |
+
+## Red Flags
+
+- An approval with no specific, anchored findings.
+- Findings phrased to spare feelings instead of stating severity and impact.
+- Rubber-stamping because the author is senior or the diff is small.
+- Proposing a rewrite far larger than the change under review (scope creep in the review itself).
+- Deleting flagged dead code without confirming it is truly unreachable.
+- Waving through a new third-party dependency without justification.
+
+## When to use
+
+- Before committing changes.
+- Before creating a PR or merge request.
+- After receiving review feedback.
+- The operator says "review this" or "check my changes before commit."
+
+Do **not** use this skill for:
+- Pipeline verification — that is `sp:code-verification` (`/sp:dev-verify`).
+- SECUA review of a completed task — that is `sp:code-verification` (`/sp:dev-review`).
+- Architectural review alone — that is `sp:sys-architecture`.
+
+## References
+
+| Reference | Covers |
+|-----------|--------|
+| [self-review-checklist.md](references/self-review-checklist.md) | Pre-commit checklist: 6 categories with diagnostic questions |
+| [review-lenses.md](references/review-lenses.md) | SECUA review lenses: correctness, security, efficiency, usability, architecture |
+
+## See also
+
+- **`sp:code-implementation`** — the implement step that produces the changes being reviewed.

package/plugins/sp/skills/code-review/references/receiving-code-review.md

@@ -0,0 +1,70 @@
+# Receiving Code Review
+
+A behavioral guardrail for the **reviewee** — the agent whose code is under review. The review
+specialist (`sp:super-reviewer`) and the review skills (`sp:code-verification`,
+`sp:functional-review`, `sp:code-improvement`) produce findings; this reference governs how the
+reviewee *receives* and acts on them.
+
+## The Contract
+
+When review findings arrive:
+
+1. **Verify before implementing.** Each finding is a claim, not an order. Re-read the cited
+   `file:line` and confirm the finding is real before acting. A finding that misreads the code is
+   rejected with evidence, not silently ignored.
+2. **Technical rigor over performative agreement.** Do not agree with a finding just because a
+   reviewer said it. Do not disagree just because it's your code. Judge on the evidence.
+3. **Blind implementation is a failure mode.** Implementing every suggestion verbatim, without
+   assessing correctness, is as bad as ignoring the review. You are responsible for the merged
+   code, not the reviewer.
+4. **Challenge unclear findings.** If a finding lacks `file:line` evidence or the reasoning is
+   vague, ask for clarification — do not guess what the reviewer meant.
+5. **Push back once, then comply.** If a finding looks wrong (security theater, misread code,
+   conflicts with a stated goal), say so with evidence — once. If the reviewer confirms, comply;
+   their context may exceed yours.
+
+## Decision Table
+
+| Finding quality | Reviewee action |
+|-----------------|-----------------|
+| Specific (`file:line`, clear reasoning) | Verify the code → implement the fix |
+| Specific but wrong (misreads code) | Reject with evidence citing the actual code |
+| Vague (no `file:line`, no reasoning) | Ask for clarification; do not guess |
+| Correct but low-value (advisory) | Acknowledge; implement only if cheap or if it blocks |
+| Conflicts with a stated goal | Push back once with the goal conflict; comply if confirmed |
+
+## Anti-Patterns
+
+- **Agreeing reflexively:** "Good catch — I'll fix that" without re-reading the code. The finding
+  might misread the control flow.
+- **Implementing verbatim:** Copy-pasting the reviewer's suggested code without understanding it.
+  The reviewer doesn't have the full context; their suggestion might break an invariant.
+- **Silent rejection:** Disagreeing with a finding but not saying so, letting the review "pass"
+  without resolution. Either implement or reject with evidence — no silent drops.
+- **Escalation theater:** "I'll let the operator decide" for a finding that's clearly wrong. Reject
+  it with evidence; save the operator's attention for genuine judgment calls.
+
+## When you are the reviewee under the pipeline
+
+Under `task-pipeline.yaml`, the `review` step's findings are written to the task's `## Review`
+section. As the reviewee (the implementer agent):
+
+1. Read the `## Review` section via `spur task show <wbs> --json`.
+2. For each finding, apply the Decision Table.
+3. Implement the accepted fixes; reject the wrong ones with evidence in the commit message or the
+   task's `## Solution` section.
+4. Do **not** edit the `## Review` section directly — it is the reviewer's record. Your response
+   goes in the implementation and the `## Solution` section.
+
+## Relationship to `sp:code-verification`'s Common Rationalizations
+
+`sp:code-verification`'s Common Rationalizations table governs the *reviewer's* honesty —
+rationalizations a reviewer uses to soften a finding. This reference governs the *reviewee's*
+honesty — rationalizations a reviewee uses to dismiss a finding. Both must be resisted.
+
+| Reviewer rationalization (code-verification) | Reviewee rationalization (this reference) |
+|----------------------------------------------|------------------------------------------|
+| "The code looks fine to me." | "The reviewer doesn't know my codebase." |
+| "I'll skip that dimension." | "That's advisory — I'll skip it." |
+| "PARTIAL is close enough." | "The finding is nitpicky — I'll ignore it." |
+| "The implementer said it works." | "The reviewer is wrong — I'll silently ignore it." |

package/plugins/sp/skills/code-review/references/review-lenses.md

@@ -0,0 +1,117 @@
+---
+name: review-lenses
+description: "SECUA review lenses — correctness, security, efficiency, usability, architecture — with per-lens diagnostic questions and finding-severity guidance."
+see_also:
+  - code-review
+  - code-verification
+---
+
+# Review Lenses (SECUA)
+
+Five dimensions for structured code review. Each lens has diagnostic questions; answer them against the diff. Findings are severity-graded P1 (blocker) through P4 (advisory).
+
+## Correctness
+
+**Question:** Does this code do what it claims to do?
+
+- Does every code path produce the expected output for the given input?
+- Are edge cases handled (empty, null, boundary, error)?
+- Are invariants preserved across the changed functions?
+- Is there a test that fails if the behavior is wrong?
+
+**Severity guide:** Logic errors that produce wrong output → P1. Missing edge case that could cause wrong output → P2. Unclear control flow that might hide bugs → P3.
+
+## Security
+
+**Question:** Can this code be exploited?
+
+- Is user input validated, sanitized, and bounded?
+- Are secrets, tokens, or credentials exposed (in logs, error messages, client code)?
+- Are SQL queries parameterized? Is there any string-interpolated SQL?
+- Does the change expand the auth/permission surface?
+- Is there a path that bypasses authentication or authorization?
+
+**Severity guide:** Exploitable vulnerability (injection, auth bypass, secret leak) → P1. Missing validation that could be exploited → P2. Hardcoded configuration that weakens security → P3.
+
+## Efficiency
+
+**Question:** Will this code perform at scale?
+
+- Are there N+1 queries or unnecessary loops?
+- Is data transformed through unnecessary intermediate representations?
+- Are large allocations bounded? Is there unbounded memory growth?
+- Is there blocking I/O on a hot path?
+
+**Severity guide:** O(n²) or worse on a hot path → P2. Unnecessary allocation on a cold path → P3. Minor optimization opportunity → P4.
+
+## Usability
+
+**Question:** Can a developer understand and use this code?
+
+- Are function and variable names self-documenting?
+- Are error messages actionable (what failed, expected, path involved)?
+- Is the API surface consistent with surrounding code?
+- Are complex algorithms explained with a brief comment?
+
+**Severity guide:** Misleading name that could cause bugs → P2. Missing error context → P3. Inconsistent naming → P4.
+
+## Architecture
+
+**Question:** Does this code fit the system's design?
+
+- Does it respect module boundaries? No cross-cutting imports that bypass the public API?
+- Does it follow existing patterns, or introduce a new one with justification?
+- Is the right separation of concerns maintained?
+- Would this change make future changes harder (coupling, rigidity)?
+- **Deep-module check:** does the new/changed module pass the deletion test (would inlining its one
+  caller make anything harder)? Is there a **seam** with only one **adapter** — i.e. speculative,
+  not yet justified by a second caller? Full vocabulary (module/interface/depth/seam/adapter/
+  leverage/locality) and the deletion test: `sp:sys-architecture`'s
+  [decision-method.md](../../sys-architecture/references/decision-method.md).
+
+**Severity guide:** Violates module boundary or dependency rule → P1. Introduces a new pattern without justification → P2 (a seam with only one adapter and no stated second-caller plan is this severity). Minor boundary fuzziness → P3.
+
+## Structural Remedies
+
+A finding is worth more when it carries the fix. Do not stop at "this is tangled" — propose the
+restructuring: name the deeper module, the extracted seam, the guard-clause flattening, the
+collapsed pass-through. State the before/after shape in prose so the author can act without a second
+round-trip. A problem without a proposed remedy is half a review.
+
+## Change Sizing
+
+Diff size is a reviewability signal. Flag oversized changes and propose a split:
+
+| Size | Verdict | Action |
+|---|---|---|
+| ~100 lines | Good | Review normally. |
+| ~300 lines | Acceptable | Review, but note if it bundles independent concerns. |
+| ~1000 lines | Too large | Ask to split before deep review — a diff this size hides defects and cannot be reviewed honestly. |
+
+**Split strategies:** separate refactor from feature (two commits); slice vertically by behavior, not
+by layer; land a mechanical rename/move on its own; extract a shared helper in a preceding change so
+the feature diff shrinks to the new logic.
+
+## Honesty in Review (anti-sycophancy)
+
+The diff is under review, not the author. Do not rubber-stamp, do not soften a real finding to spare
+feelings, do not pad with praise to cushion a criticism. Quantify impact ("this N+1 query runs once
+per row"), state severity plainly, and push back when the change is wrong — once, with reasoning. A
+review that makes everyone feel good and lets a defect through has failed. "LGTM" with no specific,
+anchored findings is not a review.
+
+## Dead-Code Hygiene
+
+When you spot unreachable branches, unused exports, commented-out blocks, or orphaned helpers:
+**identify and list them** — do not silently delete them in the review. Deleting code you do not
+fully understand is its own risk (Chesterton's Fence). Confirm it is truly unreachable, list each
+item with its location, and ask before removal. Dead code called out and removed deliberately is
+hygiene; dead code swept away mid-review is a landmine.
+
+## Dependency Discipline
+
+Prefer the standard library and existing in-repo utilities over a new third-party dependency. Flag
+every new dependency a diff introduces: a one-function import rarely justifies the supply-chain,
+version-drift, and bundle cost it adds. Ask whether an existing helper covers the need, whether the
+dependency is maintained, and whether its footprint matches the value. New top-level dependencies are
+an operator decision, not a reviewer's silent pass-through.

package/plugins/sp/skills/code-review/references/self-review-checklist.md

@@ -0,0 +1,53 @@
+---
+name: self-review-checklist
+description: "Pre-commit self-review checklist — 6 categories with diagnostic questions. Catches 60-80% of issues before a reviewer sees them."
+see_also:
+  - code-review
+---
+
+# Self-Review Checklist
+
+Run before `git commit`. For each category, answer the diagnostic questions. If any answer is "no" or "I don't know", fix before committing.
+
+## 1. Type Safety
+
+- [ ] Are all function return types explicit (no inferred `any`)?
+- [ ] Are `null`/`undefined` handled at every boundary (API responses, user input, DB queries)?
+- [ ] Are type assertions (`as`, `!`) justified with a comment or guard, not used to silence the compiler?
+
+## 2. Null Handling
+
+- [ ] Does every `?.` chain have a fallback or explicit null check at the consumer?
+- [ ] Are optional parameters handled when `undefined` is passed?
+- [ ] Do array accesses (`arr[i]`) guard against out-of-bounds?
+
+## 3. Error Propagation
+
+- [ ] Are errors caught at system boundaries (API calls, file I/O, DB queries)?
+- [ ] Do caught errors include context (what failed, what was expected, what path/identifier)?
+- [ ] Are there any empty `catch {}` blocks? Each must have a comment justifying why the error is intentionally swallowed.
+
+## 4. Test Coverage
+
+- [ ] Does the changed code have corresponding tests?
+- [ ] Do the tests verify behavior, not implementation?
+- [ ] Are edge cases covered (empty input, boundary values, error paths)?
+
+## 5. Security Surface
+
+- [ ] Is user input validated and sanitized?
+- [ ] Are secrets, tokens, or credentials hardcoded? (They must never be.)
+- [ ] Are SQL queries parameterized? (Never string-interpolated.)
+- [ ] Does the change touch auth, sessions, or permissions? If yes, re-audit the entire auth flow.
+
+## 6. Performance Regression
+
+- [ ] Does the change add N+1 queries? (Check for queries inside loops.)
+- [ ] Is there unnecessary data transformation (serialize → deserialize → serialize)?
+- [ ] Are large allocations (buffers, arrays) bounded?
+
+## When to skip
+
+- Docs-only changes → skip categories 1, 4, 5, 6.
+- Test-only changes → skip categories 2, 3, 5, 6.
+- Config-only changes → skip all except category 5.

package/plugins/sp/skills/code-review/references/verification-before-completion.md

@@ -0,0 +1,68 @@
+# Verification Before Completion
+
+A behavioral guardrail for **any agent claiming work is done**. This is the universal honesty gate:
+no "done", "passing", "fixed", or "works" claim without fresh, pasted verification evidence run
+this turn.
+
+## The Contract
+
+Before reporting a task as complete, a test as passing, a bug as fixed, or a feature as working:
+
+1. **Run the verification command.** Not last session's output. Not the implementer's summary. Run
+   it now, this turn, and capture the output.
+2. **Paste the evidence.** The raw tail output (last 20+ lines for high-stakes changes), not a
+   one-line "green" summary. For doc-only changes, a one-liner is acceptable.
+3. **No claim without evidence.** If you cannot run the verification (tool unavailable, environment
+   missing), say so explicitly — do not claim success.
+4. **No skipped checks.** A test suite with `.skip`/`xfail`/`#[ignore]` is not green. Past the
+   raw output so the operator can see skips.
+
+## Evidence Standard
+
+| Claim | Required evidence |
+|-------|-------------------|
+| "Tests pass" | Raw `bun test` / `pytest` / `cargo test` tail showing 0 failures, 0 skips |
+| "Lint clean" | Raw `biome check . --error-on-warnings` / `eslint` / `clippy` exit 0 output |
+| "Build succeeds" | Raw `bun run build` / `cargo build` / `go build` exit 0 output |
+| "Bug fixed" | The failing test now passing (raw output) + the root-cause explanation |
+| "Feature works" | The specific test or manual scenario that exercises the feature, run this turn |
+| "Doc-only change" | One-liner acceptable; no gate evidence needed |
+
+## Anti-Patterns
+
+- **Trust the summary:** "The implementer reported all tests pass — I'll trust it." The summary is a
+  claim, not evidence. Re-run the gate.
+- **Stale evidence:** Paste last session's output. Gates must be run this turn, after the last
+  code change.
+- **One-line green:** "All gates green ✓" without the raw output. Paste the tail; let the operator
+  see the actual numbers.
+- **Silent skips:** "Test suite passes" with 3 `.skip`'d tests. Skips are not passes. Surface them.
+- **Premature done:** "Done" with a known failing check, planning to fix it later. Done means done —
+  if a check fails, you are not done.
+
+## Under the pipeline
+
+`task-pipeline.yaml`'s `verify` step (Phase 8) and `record` step enforce this gate. The `verify`
+step runs `sp:code-verification` verify mode, which produces a `VerifyVerdict` artifact; the
+`record` step transcribes it to the task's `## Testing` section. A `done` transition requires a
+PASS verdict.
+
+Under manual execution (no pipeline), the agent must still run the gates and paste the evidence.
+"Manual" is not an exemption — it just means the agent, not the pipeline, runs the commands.
+
+## Relationship to `sp:code-verification` and `sp:functional-review`
+
+Both review skills produce verdicts (PASS/PARTIAL/FAIL). A verdict is a completion claim — it
+obeys this gate. The reviewer must have run the verification (read the code, run the tests, checked
+the evidence) before emitting the verdict, not guess from the implementer's summary.
+
+| Skill | Verdict artifact | This gate says |
+|-------|-----------------|----------------|
+| `sp:code-verification` | `VerifyVerdict` (SECUA + AC) | Run the SECUA review + AC check; paste evidence |
+| `sp:functional-review` | `FunctionalVerdict` (requirements) | Map each R{n} to file:line evidence; no MET without a citation |
+| `sp:code-improvement` | Candidate list (advisory) | Every candidate needs file:line evidence; no "looks shallow" without a location |
+
+## The one sentence
+
+If you cannot paste the raw output of the verification command you just ran, you cannot claim
+"done".