release(v8.4.1): activate the doc-verifier spawn in /audit + /refactor

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "simple-workflow",
   "description": "The Claude Code plugin for an end-to-end AI development workflow — ticket management, multi-agent code review, security audit, and automated PR creation — built on a Harness for long-running AI agents with strict context management and cross-session learning.",
-  "version": "8.4.0",
+  "version": "8.4.1",
   "author": {
     "name": "aimsise",
     "url": "https://github.com/aimsise"

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.4.1] — 2026-06-10
+
+**TL;DR.** Activates the `doc-verifier` agent that v8.4.0 shipped but never spawned: `/audit` (Step 2) and `/refactor` (Phase 3 Step 6) now spawn `simple-workflow:doc-verifier` in parallel with their other read-only reviewers, so the EC-SELFDOC doc/interface-truthfulness check runs as an independent agent at review time — not only as the inline `ac-evaluator` duty. The cross-agent EC-SELFDOC handoff is now demonstrated at runtime.
+
+### Added
+
+- **`doc-verifier` spawn-wiring in `/audit` + `/refactor`** — both review orchestrators now invoke `simple-workflow:doc-verifier` (sonnet, read-only, scratch-only exec) in parallel with `code-reviewer` (and `security-scanner` for `/audit`) when `constraints.selfdoc_verification` is active AND the change touches a documentation / advertised-interface surface (a `README` / `*.md` / `--help` / man-page, or a Gate 9 R3 `DESCRIPTION-MATCHES-BEHAVIOR` / R4 `DOC/INTERFACE TRUTHFULNESS` AC). doc-verifier RUNs the unit's advertised examples / boundary claims against the real build under the `.simple-workflow/scratch/` carve-out and reports EC-SELFDOC drift (class A) or advertised-vs-enforced boundary mismatch (class E); a non-reproducing example or advertised≠enforced boundary is a Critical that feeds the `/audit` Step 3 aggregation and the `/refactor` Step 7 loop-exit tally, while an unrunnable build is a fail-open `PASS-WITH-CAVEATS`. `agents/doc-verifier.md` gains a `## When spawned (input contract)` section (the spawner inlines the changed files, the build location, the report path, and the ticket's Gate 9 R3 / R4 rows). Both the `/audit` reviewer table + Binding-rules and the `/refactor` agent table + Binding-rules name doc-verifier. Guarded by **CT-EV-SELFDOC-6**.
+
+### Changed
+
+- **`constraints.selfdoc_verification: off` now also skips the spawn** — `autopilot-policy-reference.md` documents that `off` skips the `/audit` + `/refactor` doc-verifier spawn in addition to standing down the inline `ac-evaluator` EC-SELFDOC duty. No new kill switch; the existing one gates the spawn. doc-verifier is intentionally wired into the two review skills only (`/audit`, `/refactor`) — the other Skill-bearing spawners (`/impl` Step 15 grades EC-SELFDOC inline via the `ac-evaluator` duty; `/create-ticket` is authoring-side) do not spawn it.
+
+### Verification
+
+- `bash tests/test-skill-contracts.sh` (prior + **CT-EV-SELFDOC-6**), `bash tests/test-path-consistency.sh` unchanged (`doc-verifier` was already registered); full `run-all.sh` ALL SUITES PASSED. `plugin.json` `8.4.1` == newest CHANGELOG `[8.4.1]` (CT-MODE-14), real ISO date (CT-MODE-13). Additive + kill-switched: with `constraints.selfdoc_verification: off`, or no documentation / advertised-interface surface touched, neither review skill spawns doc-verifier — byte-for-byte the pre-v8.4.1 review flow.
+
 ## [8.4.0] — 2026-06-09
 
 **TL;DR.** Phase A + B + C of the *failure-class-coverage by default* line. **Phase A** splits the verification machinery's **evidence-independence floor** off the Size×risk depth axis (**M3**) so the independence that beat a max-effort human build in the 2026-06-02 / 06-09 A/B is no longer gated behind blast-radius, and adds per-AC `[ORACLE-AUDIT]` observability (**M8**, partial). Concretely: `evidence_floor = max(tier floor, AC-shape floor)` — ANY behavioral AC now floors at `+1-independent` regardless of Size, so a routine `standard`-tier ticket with a behavioral AC has its single evaluator establish one independent channel beyond the natural one; Gate 7's adversarial-input requirement broadens from computational-only to **every external-input boundary (computational or behavioral)**; and a tier-independent **strongest-derivation oracle** preference (first-principles over sibling library, recorded as `oracle-kind`) applies at every tier. Depth is untouched — Size still gates rounds / `/audit` third-pass / the 3-spawn fan-out — so routine S/M spawn count and wall-clock are unchanged; only the evidence bar rises, by one channel, in-agent. **Phase B** turns two more defaults on. The *failure-class eval panel*: the evaluator now grades through a fixed five-lens set (`L-CORRECTNESS` / `L-ROBUSTNESS` / `L-CONTRACT-CONFORMANCE` / `L-UNIFORMITY` / `L-SIMPLICITY`) instead of a single all-purpose pass — at `standard` one evaluator runs `>=2` lenses sequentially with NO added spawn, at `exhaustive` the existing 3-spawn fan-out carries them — emitting a per-ticket `[EVAL-PANEL]` line; and **Gate 9: Failure-Class Coverage**, an authoring-side gate making AC derivation coverage-driven by forcing, per Scope-touched external boundary, a four-row failure-class matrix (full-domain invariant / hostile + bounded termination / description-matches-behavior / doc-interface truthfulness) each resolved to `>=1` AC or a justified `n/a`. Both carry kill switches (`constraints.eval_panel`, `constraints.failure_class_coverage`) and do not fire on trivial single-unit / internal-helper-only tickets. **Phase C** completes the failure-class surface: a new `EC-SELFDOC` evidence channel + a read-only `doc-verifier` agent (classes A/E — the unit's own docstring / `--help` / advertised boundary RUN against the real build and diffed), a canonical **Gate 10: Peer-Set Uniformity** forcing one error-convention / envelope / vocabulary / wrapper AC across a `>=2`-peer set (class D), a **refute-then-synthesize merge** replacing the majority-merge so a lone non-critical FAIL survives unless a sibling refutes it (no more silent demotion), and a **Gate 9 R1 round-trip-losslessness cue** that closes the persistence-format strength axis a 2-subject dogfood A/B found a max-effort build still led on. Every Phase-C mechanism is kill-switched (`constraints.peer_uniformity` / `constraints.selfdoc_verification` / `constraints.refute_merge`).

agents/doc-verifier.md

@@ -67,6 +67,19 @@ quality and security are reviewed by `code-reviewer` / `security-scanner`. Do NO
 re-grade those — report only EC-SELFDOC (and any EC-RUNTIME observation you make while
 running the example).
 
+## When spawned (input contract)
+
+A review orchestrator (`/audit` Step 2, `/refactor` Phase 3 Step 6) spawns you via the
+Agent tool when `constraints.selfdoc_verification` is active AND the change touches a
+documentation / advertised-interface surface. Your spawn prompt carries: the changed
+files list, the build / project location to exercise, your report output path, and —
+when a ticket is in scope — the `#### Failure-Class Coverage (Gate 9)` matrix's R3
+(DESCRIPTION-MATCHES-BEHAVIOR) and R4 (DOC/INTERFACE TRUTHFULNESS) rows, which name the
+advertised examples / boundaries you MUST exercise. Verify ONLY those EC-SELFDOC
+surfaces and return the structured `## Result` envelope below (under 500 tokens — never
+raw command output). You never read `constraints.selfdoc_verification` yourself: when it
+is off the orchestrator does not spawn you at all.
+
 ## What you check (failure classes A + E)
 
 1. **Description-vs-behavior drift (class A)** — for each unit in scope that carries a

skills/audit/SKILL.md

@@ -35,10 +35,12 @@ The following agent invocations are **contractual** — `/audit` MUST delegate t
 |---|---|---|
 | `security-scanner` agent (Agent tool) | Step 2 — **always**, regardless of `only_security_scan` flag | No security review; hardcoded secrets / injection vulnerabilities may reach `done/` undetected. Detected by absence of `security-scan-{n}.md` in ticket dir and absence of security-scanner trace in skill invocation audit |
 | `code-reviewer` agent (Agent tool) | Step 2 — in parallel with security-scanner when `only_security_scan=false` (default) | No code quality review; `/impl`'s retry loop has no feedback on style/maintainability/correctness concerns. Detected by absence of `quality-round-{n}.md` in ticket dir |
+| `doc-verifier` agent (Agent tool) | Step 2 — in parallel when `constraints.selfdoc_verification` is active AND a documentation / advertised-interface surface is touched | No EC-SELFDOC verification; a docstring / README / `--help` example that no longer reproduces, or an advertised boundary ≠ the enforced one, reaches `done/` undetected. Detected by absence of `doc-verify-{n}.md` in ticket dir when the trigger fired |
 
 **Binding rules**:
 - `MUST invoke simple-workflow:security-scanner via the Agent tool` every time `/audit` runs — never skip security review even when changes look "obviously safe".
 - `MUST invoke simple-workflow:code-reviewer via the Agent tool` unless `only_security_scan=true` was explicitly passed. Never substitute by having `/audit` itself read files and render a verdict.
+- `MUST invoke simple-workflow:doc-verifier via the Agent tool` when `constraints.selfdoc_verification` is active AND the change touches a documentation / advertised-interface surface (a `README` / `*.md` / `--help` / man-page, or a Gate 9 R3 / R4 AC). Never substitute by having `/audit` itself reproduce the examples and judge; skip only via the documented `constraints.selfdoc_verification: off` / no-doc-surface paths.
 - `NEVER bypass these agents via direct file operations` — `/audit` must NOT read the changed files itself (Step 2 explicitly states: "Do NOT read files directly — delegate ALL review work to the agents").
 - `Fail this audit immediately if any required agent cannot be invoked via the Agent tool` — the Error Handling section treats agent failure as Critical = 1; **never silently treat a failed agent as PASS or PASS_WITH_CONCERNS**.
 
@@ -199,21 +201,26 @@ When `ticket-dir` is NOT set, do NOT write a dispatch log.
 
 If `only_security_scan` is `true`, the code-reviewer is **skipped** (security-only mode).
 
+**If** `constraints.selfdoc_verification` is active (read it from `{ticket-dir}/autopilot-policy.yaml`; absent file / field / unknown value → `auto` = active) **AND** the change touches a documentation / advertised-interface surface (a changed `README` / `*.md` / `--help` / man-page / quickstart, OR the ticket carries a Gate 9 R3 `DESCRIPTION-MATCHES-BEHAVIOR` / R4 `DOC/INTERFACE TRUTHFULNESS` AC), you **MUST also invoke the `simple-workflow:doc-verifier` agent via the Agent tool** (sonnet) **in parallel** with the other reviewers. doc-verifier RUNs the unit's OWN advertised examples and boundary claims against the real build under the `.simple-workflow/scratch/` exec carve-out and reports **EC-SELFDOC** drift (description-vs-behavior, class A) or advertised-vs-enforced boundary mismatch (class E) — independent of code-reviewer (quality) and security-scanner (security). **NEVER substitute by having `/audit` itself read the docs and judge.**
+- Pass the changed files list and the doc-verify output path (`{ticket-dir}/doc-verify-{n}.md`, or the default `.simple-workflow/docs/reviews/doc-verify-{topic}.md`). When `ticket-dir` is set and `{ticket-dir}/ticket.md` carries a `#### Failure-Class Coverage (Gate 9)` matrix, inline its R3 / R4 rows so doc-verifier knows which advertised examples / boundaries to exercise.
+- Receive Critical / Warnings / Suggestions counts and a summary. A doc example that does not reproduce, or an advertised boundary that differs from the enforced one, is a Critical finding; where the build genuinely cannot be exercised, doc-verifier returns `PASS-WITH-CAVEATS` (fail-open), never a spurious Critical.
+- doc-verifier is **skipped** (record a one-line note in the aggregated report) when `constraints.selfdoc_verification: off` OR no documentation / advertised-interface surface is touched. This is the per-brief kill switch for the EC-SELFDOC verification line.
+
 Do NOT read files directly — delegate ALL review work to the agents.
 
 ### 3. Aggregate Results
 
 Combine the results from the spawned agents into a single aggregated report:
 
-- `Critical` = sum of Critical counts from all spawned agents (security-scanner always; code-reviewer when not skipped).
+- `Critical` = sum of Critical counts from all spawned agents (security-scanner always; code-reviewer when not skipped; doc-verifier when the EC-SELFDOC trigger fired).
 - `Warnings` = sum of Warnings counts from all spawned agents.
 - `Suggestions` = sum of Suggestions counts from all spawned agents.
 - Determine `Status`:
   - If `Critical > 0` → `FAIL`
   - Else if `Warnings > 0` or `Suggestions > 0` → `PASS_WITH_CONCERNS`
   - Else → `PASS`
 
-The aggregated counts MUST be calculated across both agents (or just security-scanner when code-reviewer is skipped).
+The aggregated counts MUST be calculated across all spawned agents (security-scanner always; code-reviewer when not skipped; doc-verifier when the EC-SELFDOC trigger fired).
 
 - When Step 3.5 (Skeptical Third-Pass) fires and returns `DO_NOT_SHIP`, treat this as `Critical += 1` in the aggregated tally. This causes `Status` to be `FAIL` via the existing `Critical > 0` rule. When Step 3.5 does not fire, the tally is unaffected.
 

skills/create-ticket/references/autopilot-policy-reference.md

@@ -274,7 +274,9 @@ switch for the refute-then-synthesize merge; it is independent of
 
 **Consumed by**: the EC-SELFDOC evidence channel in
 [`../../impl/references/evidence-channels.md`](../../impl/references/evidence-channels.md)
-— the `doc-verifier` agent, the `ac-evaluator` / `ac-evaluator-hi`
+— the `doc-verifier` agent (spawned by `/audit` Step 2 and `/refactor` Phase 3 Step 6,
+in parallel with the other reviewers, when this switch is active and a documentation /
+advertised-interface surface is touched), the `ac-evaluator` / `ac-evaluator-hi`
 `## Independent Evidence (behavioral ACs)` EC-SELFDOC duty, and the Gate 9 R3
 (DESCRIPTION-MATCHES-BEHAVIOR) / R4 (DOC/INTERFACE TRUTHFULNESS) authoring rows in
 [`ac-quality-criteria.md`](ac-quality-criteria.md).
@@ -297,7 +299,8 @@ be exercised or the unit advertises no example / boundary, the verifier records
 Caveat (PASS-WITH-CAVEATS), never a force-FAIL. When `off`, the EC-SELFDOC channel and the
 `doc-verifier` agent stand down: the `ac-evaluator` drops the EC-SELFDOC duty (the other
 behavioral-AC channels — EC-ORACLE / EC-DIFFERENTIAL / EC-PROPERTY / EC-RUNTIME / EC-STATIC
-— are unaffected) and Gate 9 rows R3 / R4 are satisfied by their pre-v8.4.0 prose form
+— are unaffected), `/audit` Step 2 and `/refactor` Phase 3 Step 6 skip the `doc-verifier`
+spawn, and Gate 9 rows R3 / R4 are satisfied by their pre-v8.4.0 prose form
 without the RUN-the-example / FORBIDDEN+ALLOWED concretization — the byte-for-byte revert.
 This is the per-brief kill switch for the EC-SELFDOC / doc-verifier feature line; it is
 independent of `constraints.oracle_verification` (Gate 7 / EC-ORACLE),

skills/refactor/SKILL.md

@@ -82,10 +82,12 @@ Invocation policy: Do not auto-invoke. `disable-model-invocation: true` is inten
 |---|---|---|
 | `planner` agent (Agent tool) | Phase 1 Step 1 — always, before user approval is sought | No refactoring plan exists; Phase 2 has nothing to seek approval for; Phase 3 has no scope to implement against. Detected by the absence of a planner agent return value in the conversation transcript. |
 | `code-reviewer` agent (Agent tool) | Phase 3 Step 6 — each iteration of the implement → verify → review loop, up to 3 iterations | Quality review SKIPPED; Critical and Warning findings cannot be detected; loop exit condition `Critical = 0 AND Warning = 0` cannot be evaluated, so Critical bugs may slip through unverified. Detected by absence of the configured output file (`{ticket-dir}/quality-refactor-{n}.md` or the default `.simple-workflow/docs/reviews/{topic}.md`). |
+| `doc-verifier` agent (Agent tool) | Phase 3 Step 6 — in parallel with code-reviewer when `constraints.selfdoc_verification` is active AND the refactor touches a documentation / advertised-interface surface | No EC-SELFDOC verification; a refactor that silently breaks a docstring / README / `--help` worked-example, or shifts an advertised boundary, ships unverified. Detected by absence of `doc-verify-{n}.md` when the trigger fired. |
 
 **Binding rules**:
 - `MUST invoke the simple-workflow:planner agent` in Phase 1 Step 1 before presenting any plan summary to the user. The orchestrator MUST NOT fabricate a plan in lieu of the planner return value.
 - `MUST invoke the simple-workflow:code-reviewer agent` in every iteration of Phase 3 Step 6 (up to the 3-iteration ceiling). The orchestrator MUST NOT skip review by self-judging "no issues".
+- `MUST invoke the simple-workflow:doc-verifier agent` in each Phase 3 Step 6 iteration when `constraints.selfdoc_verification` is active AND the refactor touches a documentation / advertised-interface surface. The orchestrator MUST NOT self-judge doc truthfulness; skip only via `constraints.selfdoc_verification: off` or the no-doc-surface path.
 - `NEVER bypass the code-reviewer` by treating an Agent-tool infrastructure failure as a clean review — Phase 3 Step 7 defines the explicit `AskUserQuestion` fallback (`stop` / `continue without review`) and the non-interactive default-to-stop; bypass is allowed only via that documented path.
 - `Fail the task immediately` when the planner agent cannot be invoked at all (no fallback exists — Phase 2 backup branch creation cannot proceed without a plan). Print the failure reason and stop.
 
@@ -118,6 +120,7 @@ Invocation policy: Do not auto-invoke. `disable-model-invocation: true` is inten
    - **Capability binding pre-load** (v8.0.0): when `ticket-dir` is set (resolved in Step 1 / Step 1b) and `{ticket-dir}/ticket.md` exists with a `### Capabilities` section, inline the full table verbatim into the code-reviewer spawn prompt under `## Bound capabilities (per AC)`. The code-reviewer is a Skill-bearing Group C agent that consumes the deterministic per-AC binding (never speculative — see `## Subagent Skill-Access Handoff` below). When the ticket lacks `### Capabilities`, inline `## Bound capabilities (per AC): (none recorded — ticket pre-dates Gate 6)`.
    - If `ticket-dir` is set: specify output path as `{ticket-dir}/quality-refactor-{n}.md` where {n} is the iteration number
    - If `ticket-dir` is not set: let the code-reviewer use its default (`.simple-workflow/docs/reviews/{topic}.md`)
+   - **doc-verifier (EC-SELFDOC, v8.4.1+)**: in the SAME iteration, when `constraints.selfdoc_verification` is active (read from `{ticket-dir}/autopilot-policy.yaml`; absent file / field / unknown → `auto` = active) AND the refactor touches a documentation / advertised-interface surface (a `README` / `*.md` / `--help` / man-page, or a Gate 9 R3 / R4 AC in the ticket), **also spawn the `simple-workflow:doc-verifier` agent in parallel** with code-reviewer to RUN the unit's advertised examples / boundary claims against the post-refactor build under the `.simple-workflow/scratch/` carve-out. Output path `{ticket-dir}/doc-verify-{n}.md` (or the default `.simple-workflow/docs/reviews/doc-verify-{topic}.md`); inline the ticket's `#### Failure-Class Coverage (Gate 9)` R3 / R4 rows when present. Fold a doc-verifier `FAIL` / `FAIL-CRITICAL` (a non-reproducing example or advertised≠enforced boundary) into the Step 7 loop-exit tally exactly as a code-reviewer Critical; a `PASS-WITH-CAVEATS` (build unrunnable, fail-open) is not a Critical. Skip when `constraints.selfdoc_verification: off` or no doc surface is touched.
 7. Evaluate review results:
    - **code-reviewer Status: failed or partial** (review infrastructure failure):
      Use `AskUserQuestion` to ask "code-reviewer failed. How do you want to proceed?" with options: