@gobing-ai/spur 0.3.41 → 0.3.42

package/plugins/sp/skills/doubt-driven-development/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: doubt-driven-development
+description: "In-flight adversarial review of a non-trivial decision before you commit it: extract the artifact + contract, hand them (not your reasoning) to a fresh-context skeptic, reconcile findings, stop at 3 cycles. Triggers: \"doubt this\", \"stress-test this decision\", \"adversarial check before I commit\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - doubt
+  openclaw:
+    emoji: "🕵️"
+see_also:
+  - sp:parallel-execution
+  - sp:code-verification
+  - sp:source-driven-development
+---
+
+# doubt-driven-development — the in-flight adversarial-review competency
+
+Catch a wrong decision **while you can still change it cheaply** — before the code is written, the
+migration is run, or the design is locked. You state a claim, strip it to its artifact and its
+contract, and hand *only those* to a fresh-context skeptic whose job is to find where the artifact
+violates the contract. The skeptic never sees your reasoning, so it cannot be talked into agreeing.
+
+This is a **technique** skill: it stress-tests a decision mid-flight. It is **not** the post-hoc
+gate — `sp:code-verification` verifies finished work against requirements, and `sp:code-review`
+reviews a completed diff. Doubt runs *earlier and cheaper*: on a plan, an interface, a schema, a
+tricky algorithm, before you invest in building it.
+
+## When to use
+
+- A non-trivial decision is about to be committed: an API/interface shape, a schema, a state
+  machine, a concurrency approach, a migration plan, a security boundary.
+- You feel the pull of "this is probably right" on something whose cost-of-wrong is high.
+- Review flagged a design concern and you want an independent adversary before reworking.
+
+Do **not** use this skill for:
+
+- **Trivial or reversible choices** — a variable name, a local refactor. Doubt has a cost; spend it
+  where being wrong is expensive.
+- **Finished-work verification** — that is `sp:code-verification` (requirements) / `sp:code-review`
+  (diff). Doubt is pre-commit, not the completion gate.
+- **Fact-checking an external claim** — that is `sp:source-driven-development` (verify against
+  primary sources). Doubt tests *your* artifact against *its* contract, not the world.
+
+## The five-step loop
+
+### 1. CLAIM — state what you are about to commit
+
+One sentence: the decision and why you believe it is right. This is *your* view — it does **not**
+travel to the skeptic. Writing it down makes the next step honest.
+
+### 2. EXTRACT — artifact + contract, strip the reasoning
+
+Reduce the claim to two things the skeptic can check independently:
+
+- **Artifact** — the concrete thing under judgment: the interface signature, the schema DDL, the
+  pseudocode, the plan steps. No commentary.
+- **Contract** — the invariants it must satisfy: the requirements, the edge cases, the performance
+  or safety bounds, the AC it will be verified against later.
+
+**Strip your reasoning.** The skeptic must not receive *why* you think it works — only *what* it is
+and *what it must do*. Reasoning is what smuggles your blind spot into the reviewer.
+
+### 3. DOUBT — hand artifact + contract (NOT the claim) to a fresh-context skeptic
+
+Dispatch an adversarial reviewer whose sole instruction is: *find where this artifact violates this
+contract; assume it is wrong until proven otherwise.* Pass **only** the artifact and the contract.
+Use `sp:parallel-execution` (the adversarial-verification-panel pattern) or a single
+`spur agent run` with a fresh context — the point is a reviewer that shares none of your framing.
+
+**Never pre-judge the reviewer.** No "don't worry about X", no "this part is fine", no pre-rated
+severity. A steered skeptic is theater. (See `sp:parallel-execution` — never pre-judge the reviewer.)
+
+Optional: offer a **cross-model** skeptic (a different model than the author) when the decision is
+high-stakes — a different model has different blind spots.
+
+### 4. RECONCILE — classify every finding
+
+For each thing the skeptic raised, classify it — do not argue with it reflexively:
+
+| Class | Meaning | Action |
+|---|---|---|
+| **Contract-misread** | The skeptic misunderstood an invariant | Tighten the contract wording; the artifact stands |
+| **Actionable** | A real violation of the contract | Fix the artifact before committing |
+| **Trade-off** | A cost you knowingly accept | Record the decision + why; do not silently drop it |
+| **Noise** | Out of scope / not tied to the contract | Discard, with a one-line reason |
+
+A finding you cannot classify is **actionable** until proven otherwise — the benefit of the doubt
+goes to the doubt.
+
+### 5. STOP — bounded at 3 cycles
+
+If RECONCILE produced fixes, you may re-run DOUBT on the changed artifact — but **at most 3 cycles
+total**. Beyond three, the loop is no longer finding defects; it is manufacturing them. Stop, record
+the residual trade-offs, and commit. Endless doubting is its own failure mode (see Red Flags).
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I already reviewed it myself — a second pass is redundant." | Self-review shares your blind spot. A fresh-context skeptic exists precisely to see what you cannot. |
+| "I'll give the reviewer my reasoning so it understands." | Your reasoning is the vector for your blind spot. Pass artifact + contract only; reasoning steers the skeptic to agree. |
+| "The skeptic is being pedantic — I'll just overrule it." | Reflexive overrule defeats the loop. Classify the finding (misread / actionable / trade-off / noise); overrule only with a recorded reason. |
+| "This decision is basically right, doubt is overkill." | "Basically right" on a high-cost-of-wrong decision is exactly what doubt is for. Cheap now beats a rewrite later. |
+| "One more cycle and it'll be perfect." | Past 3 cycles you are inventing problems, not finding them. Record residual trade-offs and commit. |
+
+## Red Flags
+
+- Passing your **reasoning** (not just artifact + contract) to the skeptic — the review is now contaminated.
+- Pre-judging the reviewer ("this part is fine", pre-rated severity, "don't flag X").
+- Overruling every finding without classifying it — the loop became a rubber stamp for your original claim.
+- **Doubt theater**: running the loop but having already decided to ship unchanged regardless of findings.
+- Exceeding 3 cycles — endless doubting that manufactures defects instead of finding them.
+- Using doubt as a substitute for the post-hoc gates (`sp:code-verification` / `sp:code-review`) rather than as the earlier, cheaper pass.
+
+## Verification
+
+Before you commit the decision, confirm — with evidence, not assertion:
+
+- [ ] The skeptic received the **artifact + contract only**; your reasoning was withheld (state it).
+- [ ] Every finding is classified (contract-misread / actionable / trade-off / noise) with a one-line disposition.
+- [ ] Every **actionable** finding is fixed in the artifact, or explicitly deferred with a recorded reason.
+- [ ] Every **trade-off** is recorded (not silently dropped) — it survives into the task's design/decision notes.
+- [ ] The loop stopped at ≤ 3 cycles; residual trade-offs are named.
+- [ ] This was a *pre-commit* pass — the post-hoc gate (`sp:code-verification` / `sp:code-review`) still runs on the finished work.
+
+## See also
+
+- **`sp:parallel-execution`** — the adversarial-verification-panel / fresh-context subagent mechanics doubt dispatches through.
+- **`sp:code-verification`** — the post-hoc requirements/AC gate; doubt is the earlier, cheaper, pre-commit counterpart.
+- **`sp:source-driven-development`** — when the doubt is about an external fact (an API contract), verify it against primary sources there.

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

@@ -0,0 +1,364 @@
+---
+name: functional-review
+description: "Requirements traceability assessment: verify implementation satisfies ALL task requirements. Phase 8b gate for the sp pipeline. Produces per-requirement verdicts with file:line evidence. Triggers: \"functional review\", \"traceability check\", \"verify requirements\", \"did we build what was asked\", \"requirements completeness\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - reviewer
+    - pipeline
+  modes:
+    - verify
+  verdicts:
+    - PASS
+    - PARTIAL
+    - FAIL
+  openclaw:
+    emoji: "📋"
+see_also:
+  - sp:code-verification
+  - sp:code-improvement
+  - sp:spur-dev
+---
+
+# Spur Functional Review
+
+The **requirements traceability** counterweight to `sp:code-verification`'s SECUA review. Where
+code-verification asks "is the code correct and secure?", functional-review asks "did we build what
+the task actually asked for?" — mapping every `R{n}` requirement to concrete implementation evidence
+and refusing to certify gaps.
+
+## When to Use
+
+**Trigger phrases:** "functional review", "traceability check", "verify requirements",
+"requirements completeness", "did we build what was asked", "check the requirements".
+
+Load this skill when:
+
+- Verifying implementation against the task's `## Requirements` section (per-requirement traceability).
+- Producing an audit trail that ties each requirement to `file:line` evidence.
+- Running the requirements-completeness dimension of a multi-dimensional review (`/sp:dev-review`).
+- Determining whether functional completeness is sufficient for `done`.
+
+Do **not** use this skill for:
+
+- SECUA code-quality review (use `sp:code-verification` review mode).
+- Architecture / deepening review (use `sp:code-improvement`).
+- Running tests or measuring coverage (use `sp:code-testing`).
+- Driving the pipeline (use `sp:spur-dev`).
+
+## Key Distinctions
+
+| Skill | Question it answers |
+| ------- | --------------------- |
+| **`sp:functional-review`** | Are all task requirements implemented? (requirements completeness) |
+| **`sp:code-verification`** | Is the code correct, secure, efficient, usable? (SECUA quality) |
+| **`sp:code-improvement`** | Is the architecture deep / testable? (structural depth) |
+
+A complete `/sp:dev-review` runs all three: functional (this skill) + SECUA + architecture.
+
+## Cross-cutting rules (inherited from sp:spur-dev)
+
+The CLI-gated section-write contract (every mutation via `spur task update --section --from-file`,
+never a legacy `tasks` CLI) is the SSOT in
+[spur-dev/cross-cutting.md](../spur-dev/references/cross-cutting.md). The universal honesty gate —
+**no "done / passing / fixed / works" claim without fresh, pasted verification evidence run this
+turn** — lives in that same file:
+[Verification Before Completion](../spur-dev/references/cross-cutting.md#verification-before-completion).
+A PASS verdict is a completion claim; it obeys the gate.
+
+---
+
+## Two-Track Assessment
+
+### Track A — BDD-Assisted (if `--bdd-report` provided)
+
+When a BDD execution report exists (from `sp:code-testing --bdd` or equivalent), map each
+requirement to one or more Gherkin scenarios by requirement text, identifier, or explicit
+traceability markers:
+
+| Scenario status | Requirement status |
+| ----------------- | -------------------- |
+| All covering scenarios `passed` | `MET` |
+| Any covering scenario `failed` or `skipped` | `PARTIAL` |
+| No covering scenarios found | fall through to Track B |
+
+Only requirements that remain uncovered after BDD mapping fall through to Track B — the BDD report
+is the stronger (deterministic) evidence and takes precedence.
+
+**Expected BDD report schema** (JSON):
+
+```typescript
+interface BddExecutionReport {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    duration_ms: number;
+    scenarios: Array<{
+        name: string;          // maps to requirement text or AC scenario title
+        feature: string;
+        status: 'passed' | 'failed' | 'skipped';
+        steps: Array<{ step: string; checker: string; status: string }>;
+    }>;
+}
+```
+
+### Track B — LLM Assessment (direct source evidence)
+
+For each requirement not covered by BDD, gather concrete source evidence and assess:
+
+1. Read the changed files (the task's diff scope — see Step 3 of `sp:code-verification`).
+2. Search for implementation evidence: function definitions, type declarations, test cases,
+   config keys, CLI surface.
+3. Assign a per-requirement status using the Evidence Quality Standard below.
+
+```typescript
+// For each uncovered requirement
+const evidence = gatherEvidence(req, changedFiles);
+const assessment = llmAssess(req, evidence);
+verdict[req.id] = { status: assessment.status, evidence: assessment.evidence };
+```
+
+---
+
+## Per-Requirement Status
+
+| Status | Condition |
+| -------- | ----------- |
+| **MET** | Concrete evidence (code + test, or code + static ref) for the requirement exists in scope |
+| **PARTIAL** | Evidence for part of the requirement only — a material sub-condition is missing or only inferred |
+| **UNMET** | No implementation evidence found in scope |
+
+**Zero-requirements case:** if the task has 0 numbered requirements, return `verdict = PASS` with the
+note "No requirements to verify" — this is a documentation-only or config-only task, not a failure.
+
+---
+
+## Evidence Quality Standard
+
+All evidence MUST be specific. Vague evidence is rejected and the requirement is downgraded to
+`UNMET` or `PARTIAL`.
+
+### SPECIFIC Evidence (required)
+
+| Type | Example |
+| ------ | --------- |
+| File path + line | `src/api/users.ts:42` |
+| Function / method name | `createUser()` |
+| Class / type name | `UserController` |
+| Test case | `tests/users.test.ts::createUser validates email` |
+| Command + exit status | `bun test apps/cli --reporter=dots` → exit 0, 2499 pass |
+| Config / schema key | `package.json#bin.spur` |
+
+### VAGUE Evidence (rejected)
+
+| Type | Why rejected |
+| ------ | -------------- |
+| "implemented correctly" | No specific location |
+| "meets requirements" | No evidence cited |
+| "the code does X" | No file:line reference |
+| "as specified" | No implementation pointer |
+
+### Evidence Templates
+
+**MET:**
+
+```
+- `src/api/users.ts:42` — `createUser()` implements user creation
+- `src/api/users.ts:45-48` — input validation for email field
+- `tests/users.test.ts:15-20` — unit test verifies email uniqueness
+```
+
+**PARTIAL:**
+
+```
+- `src/api/users.ts:42` — `createUser()` implements basic creation
+- MISSING: `src/api/users.ts` — no error handling for duplicate emails (R3 sub-condition "duplicate email rejected")
+```
+
+**UNMET:**
+
+```
+- NO IMPLEMENTATION FOUND for requirement R5: "Send email notification on user creation"
+- Searched: src/api/, src/services/, src/notifications/
+```
+
+---
+
+## Workflow
+
+### Step 1 — Load the task
+
+```bash
+spur task show <wbs> --json
+```
+
+Parse from `content`:
+
+- `## Requirements` — the `R{n}` items (the traceability targets).
+- `## Acceptance Criteria` — if present, AC evaluation is complementary; `sp:code-verification`
+  verify mode owns the AC gate, but functional-review cross-checks that AC map back to requirements.
+
+Flags: `--bdd-report <path>` (BDD execution report JSON), `--source-paths <a,b>` (explicit source
+scope; defaults to the task's diff scope), `--auto` (no confirmations), `--next` (on PASS,
+auto-transition `testing → done`; on PARTIAL/FAIL, stop).
+
+### Step 2 — Parse requirements
+
+Extract every `R{n}` from `## Requirements` into a numbered list. If the section is empty or absent,
+return `verdict = PASS` with "No requirements to verify" (zero-requirements case).
+
+### Step 3 — Establish the change scope
+
+If `--source-paths` is given, use it. Otherwise derive the diff scope exactly as
+`sp:code-verification` Step 3 does (the task file's last commit → `git diff --name-only` for
+`*.ts`/`*.tsx`/`*.js`/`*.jsx`, fallback to working-tree diff).
+
+### Step 4 — Track A: BDD mapping (if `--bdd-report`)
+
+Load the BDD report, map each requirement to scenarios, assign `MET`/`PARTIAL` per the Track A
+table. Uncovered requirements fall through to Track B.
+
+### Step 5 — Track B: LLM evidence assessment
+
+For each uncovered requirement, gather source evidence and assign `MET`/`PARTIAL`/`UNMET` per the
+Evidence Quality Standard. Record the evidence string (`file:line`, command, or test name).
+
+### Step 6 — Aggregate the verdict
+
+Apply the aggregation rule (contract in
+[references/verdict-schema.md](references/verdict-schema.md#aggregation-rule)):
+
+```
+any core requirement UNMET                         → FAIL
+any core requirement PARTIAL (no UNMET)            → PARTIAL
+all core requirements MET                          → PASS
+```
+
+`PARTIAL` blocks the gate exactly like `FAIL` — the distinction only tells the operator *how far
+off* delivery is.
+
+### Step 7 — Write findings to the task
+
+Write the review body to the task's `## Review` section via CLI verbs. The body MUST lead with a
+`| Priority | Dimension | Location | Finding |` table (the L3 `hasPopulatedPriorityTable` gate at
+`task-check.ts:96-106` requires at least one `P[1-4]` row with non-placeholder siblings — any other
+shape, e.g. `| Req | Status | Evidence |` alone, is structurally rejected and denies the
+`wip→testing` transition). Use the same canonical shape as `sp:code-verification`:
+
+```bash
+cat > /tmp/<wbs>-functional.md <<'BODY'
+| Priority | Dimension | Location | Finding |
+| --- | --- | --- | --- |
+| P4 | — | — | No P1–P3 findings; functional verdict PASS |
+
+| Req | Status | Evidence |
+| --- | --- | --- |
+| R1  | MET     | `src/api/users.ts:42` — `createUser()` |
+| R2  | PARTIAL | `src/api/users.ts:42` — basic only; MISSING duplicate-email handling |
+| R3  | UNMET   | no implementation found; searched src/api/, src/services/ |
+BODY
+spur task update <wbs> --section Review --from-file /tmp/<wbs>-functional.md
+rm /tmp/<wbs>-functional.md
+```
+
+For a PARTIAL/FAIL verdict, replace the P4 row with the actual P1–P3 findings ranked by severity.
+The priority table leads; the traceability table follows for per-requirement detail.
+
+Section bodies passed to `spur task update --section` must be **body-only** — no same-level (`##`)
+headings inside the body. Tables and bold labels are fine.
+
+### Step 8 — Report
+
+End the output with an explicit, parseable verdict line:
+
+```
+Functional Verdict: PASS    (or PARTIAL / FAIL)
+```
+
+Include the per-requirement traceability table in the report:
+
+```markdown
+| Req | Status | Evidence |
+|-----|--------|----------|
+| R1  | MET    | `src/api/users.ts:42` — `createUser()` |
+| R2  | PARTIAL | `src/api/users.ts:42` — basic only; MISSING duplicate-email handling |
+| R3  | UNMET  | no implementation found; searched src/api/, src/services/ |
+```
+
+**Under the pipeline**, `sp:functional-review` is the review step dispatched by `/sp:dev-review`,
+so it owns `## Review` — its `--section Review` write is the authoritative source. The pipeline's
+`record` step transcribes only `## Testing` from the verify verdict (`code-verification/SKILL.md`,
+`task-record.ts:226-247`); it does not overwrite a non-bare `## Review` thanks to the
+`sectionIsBare` guard (`task-service.ts:485`). Keep the priority-table lead stable so the L3 gate
+stays satisfied through `record` → `done`.
+
+---
+
+## Quality Gates
+
+1. **Evidence gate:** all evidence must be specific (`file:line` or named test/command).
+2. **Coverage gate:** every numbered requirement must have a verdict row.
+3. **Verdict gate:** overall verdict must be PASS/PARTIAL/FAIL with per-requirement reasoning.
+
+---
+
+## Verdict Schema
+
+The artifact shape, per-requirement status enum, and aggregation rule are the contract in
+[references/verdict-schema.md](references/verdict-schema.md). When emitting a machine-readable
+verdict (standalone or pipeline), shape it as `FunctionalVerdict` — not `VerifyVerdict` (which is
+`sp:code-verification`'s SECUA + AC contract). The two artifacts are complementary; a full
+`/sp:dev-review` may emit both.
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "The requirement is obviously met — I can see it in the diff." | Seeing code is not evidence. A requirement is MET only when `file:line` evidence is cited. |
+| "All tests pass, so all requirements are covered." | Green tests prove the suite's assertions, not that every requirement has coverage. Map each requirement to its evidence. |
+| "The implementer reported it works — I'll trust the summary." | A subagent success report is a claim, not a verdict. Functional review **re-checks** the evidence; trusting the report skips the gate. |
+| "R5 is a minor requirement — I'll skip it." | Every numbered requirement gets a row. No silent skipping. |
+| "PARTIAL is close enough to ship." | PARTIAL/FAIL both block the gate. Rounding PARTIAL up to PASS is the exact dishonesty this gate exists to catch. |
+
+---
+
+## Red Flags
+
+- A PASS verdict with no per-requirement evidence column.
+- A requirement marked MET with evidence that is a description, not a `file:line` anchor.
+- A verdict authored from the implementer's summary without independently re-reading the source.
+- Softening FAIL to PARTIAL, or PARTIAL to PASS, to avoid surfacing to the operator.
+- Skipping a requirement because "it's advisory" — if it carries an `R{n}` number, it gets a row.
+
+---
+
+## Gotchas
+
+1. **Requirements ≠ AC.** `sp:code-verification` owns the AC gate; this skill owns the
+   requirements gate. They are complementary, not redundant.
+2. **Zero requirements is a PASS.** A doc-only or config-only task with no `R{n}` items is not a
+   failure — return PASS with the "No requirements to verify" note.
+3. **BDD takes precedence.** When a BDD report covers a requirement, the deterministic scenario
+   result wins; do not re-assess with LLM judgment.
+4. **Never direct-write the task file.** All findings go through `spur task update --section`.
+
+---
+
+## Platform Notes
+
+### Claude Code
+
+Invoke via `Skill(skill="sp:functional-review", args="<wbs>")`. The `spur` CLI runs via the Bash
+tool for `spur task show` / `spur task update`.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run `spur` CLI via Bash; parse `--json`. Invoke this skill directly for the functional-review logic
+— the skill is the SSOT; the commands are thin wrappers. `Skill()` and `$ARGUMENTS` are
+Claude-specific; on other platforms, execute the workflow steps inline.

package/plugins/sp/skills/functional-review/references/verdict-schema.md

@@ -0,0 +1,133 @@
+# Functional Review Verdict Schema
+
+The machine-readable artifact shape for `sp:functional-review`. This is the **requirements
+traceability** contract; for the SECUA quality contract, see
+[`sp:code-verification`'s `verdict-schema.md`](../../code-verification/references/verdict-schema.md)
+(`VerifyVerdict`). The two are complementary — a full `/sp:dev-review` may emit both.
+
+## TypeScript Interface
+
+```typescript
+/**
+ * Requirements-traceability artifact produced by sp:functional-review.
+ * Maps every R{n} requirement to implementation evidence and a per-requirement status.
+ */
+interface FunctionalVerdict {
+    /** Task WBS number, e.g. "0227". */
+    wbs: string;
+    /** Overall aggregation of per-requirement statuses. */
+    verdict: 'PASS' | 'PARTIAL' | 'FAIL';
+    /** One row per numbered requirement in the task's ## Requirements section. */
+    requirements: RequirementVerdict[];
+    /** Free-form summary: counts, notes, zero-requirements case. */
+    summary: string;
+    /**
+     * BDD execution report path, if Track A was used. null for LLM-only (Track B).
+     */
+    bddReportPath: string | null;
+    /**
+     * Explicit source scope (if --source-paths given) or derived diff scope
+     * (the changed *.ts/*.tsx/*.js/*.jsx files for the task's last commit).
+     */
+    sourcePaths: string[];
+}
+
+interface RequirementVerdict {
+    /** Requirement id from the task, e.g. "R1". */
+    id: string;
+    /** Requirement text (verbatim from ## Requirements). */
+    text: string;
+    /** Per-requirement status. */
+    status: 'MET' | 'PARTIAL' | 'UNMET';
+    /**
+     * Specific evidence: file:line, named test, or command+exit status.
+     * MUST be specific — vague evidence ("implemented correctly") downgrades to UNMET/PARTIAL.
+     */
+    evidence: string[];
+    /** For PARTIAL/UNMET: what's missing. Empty array for MET. */
+    gaps: string[];
+    /**
+     * Assessment track used.
+     * - 'bdd' if a BDD report covered this requirement (deterministic)
+     * - 'llm' if Track B LLM assessment was used
+     */
+    track: 'bdd' | 'llm';
+}
+```
+
+## Aggregation Rule
+
+```
+any core requirement UNMET                                  → FAIL
+any core requirement PARTIAL (no UNMET)                      → PARTIAL
+all core requirements MET                                    → PASS
+```
+
+- **Zero-requirements case:** if the task has 0 numbered requirements, return `verdict = PASS`
+  with `summary: "No requirements to verify"`.
+- **PARTIAL blocks the gate** exactly like FAIL — the distinction only tells the operator *how
+  far off* delivery is. Never round PARTIAL up to PASS.
+- The verdict is computed from `requirements[].status`; the `summary` field is descriptive, not
+  load-bearing.
+
+## JSON Example
+
+```json
+{
+    "wbs": "0227",
+    "verdict": "PARTIAL",
+    "requirements": [
+        {
+            "id": "R1",
+            "text": "Add functional-review skill to plugins/sp/skills/",
+            "status": "MET",
+            "evidence": [
+                "plugins/sp/skills/functional-review/SKILL.md:1 — skill file created",
+                "plugins/sp/skills/functional-review/references/verdict-schema.md:1 — verdict schema ref"
+            ],
+            "gaps": [],
+            "track": "llm"
+        },
+        {
+            "id": "R2",
+            "text": "Add code-improvement skill",
+            "status": "PARTIAL",
+            "evidence": [
+                "plugins/sp/skills/code-improvement/SKILL.md:1 — skill body created"
+            ],
+            "gaps": [
+                "plugins/sp/skills/code-improvement/references/deepening-signals.md — referenced but not yet written"
+            ],
+            "track": "llm"
+        },
+        {
+            "id": "R5",
+            "text": "Add receiving-code-review + verification-before-completion guardrails",
+            "status": "UNMET",
+            "evidence": [],
+            "gaps": [
+                "No guardrail reference files found in plugins/sp/skills/code-review/references/"
+            ],
+            "track": "llm"
+        }
+    ],
+    "summary": "4 MET, 1 PARTIAL, 1 UNMET — R5 guardrails missing, R2 deepening-signals ref pending",
+    "bddReportPath": null,
+    "sourcePaths": [
+        "plugins/sp/skills/functional-review/SKILL.md",
+        "plugins/sp/skills/code-improvement/SKILL.md",
+        "plugins/sp/commands/dev-review.md",
+        "plugins/sp/agents/super-reviewer.md"
+    ]
+}
+```
+
+## Relationship to `VerifyVerdict`
+
+| Artifact | Owning skill | Question | Aggregation |
+|----------|-------------|----------|-------------|
+| `FunctionalVerdict` | `sp:functional-review` | Did we build what was asked? (requirements completeness) | any UNMET → FAIL; any PARTIAL → PARTIAL; else PASS |
+| `VerifyVerdict` | `sp:code-verification` | Is the code SECUA-correct and AC-complete? | any core req/AC UNMET → FAIL; any blocker correctness/security → FAIL; any PARTIAL → PARTIAL; else PASS |
+
+A complete `/sp:dev-review --focus all` pipeline may produce both artifacts; they are consumed by
+the pipeline's `record` step and written to the task's `## Testing` section.