sequant 2.11.0 → 2.12.0

package/templates/skills/loop/SKILL.md

@@ -59,7 +59,7 @@ When running as part of an orchestrated workflow (e.g., `sequant run` or `/fulls
 1. **Use provided worktree** - Work in `SEQUANT_WORKTREE` path directly
 2. **Use `SEQUANT_ISSUE`** - Skip issue number parsing from invocation
 3. **Reduce GitHub comment frequency** - Defer updates to orchestrator
-4. **Trust issue context** - Orchestrator has already validated issue
+4. **Trust embedded context** - when the orchestrator injected a `<!-- SEQUANT_PROMPT_CONTEXT -->` block into this invocation, it is the authoritative QA-findings source; do not re-fetch from GitHub (see Step 1A below)
 
 **Behavior when standalone (SEQUANT_ORCHESTRATOR is NOT set):**
 
@@ -81,10 +81,20 @@ When running as part of an orchestrated workflow (e.g., `sequant run` or `/fulls
 
 #### Step 1A: Orchestrated Mode (SEQUANT_ORCHESTRATOR is set)
 
-When `SEQUANT_ORCHESTRATOR` is set, read QA findings from the GitHub issue comments instead of a log file:
+<!-- BEGIN: step-1a-context-source (#960) -->
+
+**Check your own invocation first — before fetching anything.** The orchestrator (`ready-gate.ts` or `batch-executor.ts`, via `buildLoopContext`) may already have embedded the QA findings directly into the prompt that invoked this `/loop` run, wrapped in a `<!-- SEQUANT_PROMPT_CONTEXT -->` / `<!-- /SEQUANT_PROMPT_CONTEXT -->` sentinel pair (`getPhasePrompt`, `src/lib/workflow/phase-executor.ts`). When that sentinel is present in your own invocation text:
+
+- Treat the text between the markers as the authoritative QA findings (`qa_comment` below).
+- **Do not** fetch `gh issue view` for QA comments — skip straight to "Parsing QA comment" below, using the embedded text in place of the fetched comment.
+- **The embedded block's gap list IS your `recommendations`.** The block is not QA-comment-shaped — the parsing snippets below (verdict grep aside) won't extract anything from it. Read the list under `Gaps to address:` (ready-gate) or `QA Gaps:` (batch-executor) directly as the findings to fix; the `QA Verdict:` line is the verdict.
+- That gap list is already `fixableGaps`-filtered by the orchestrator (`selectFixableGaps` in `batch-executor.ts`, or ready-gate's own filter), so the `document`/`pause_for_human` exclusion in "Excluded Finding Classes" below is redundant for it — it exists for the fetched-comment fallback. But this applies **only to the gap list**: any `Suggestions:` or `Last output:` sections in the block (batch-executor only) are raw, unfiltered context — use them for understanding, never as additional findings to fix.
+
+**Only when the sentinel is absent** from your invocation — a standalone-style dispatch, or an orchestrator that doesn't inject `promptContext` — fall back to reading QA findings from the GitHub issue comments instead of a log file:
 
 ```bash
-# Check if we're in orchestrated mode
+# Fallback: no embedded SEQUANT_PROMPT_CONTEXT sentinel in the invocation.
+# Fetch QA findings from GitHub comments instead.
 if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
   echo "Orchestrated mode detected (orchestrator: $SEQUANT_ORCHESTRATOR)"
 
@@ -96,6 +106,8 @@ if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
 fi
 ```
 
+<!-- END: step-1a-context-source (#960) -->
+
 **How to identify QA comments:**
 
 | Pattern | Meaning |
@@ -103,7 +115,7 @@ fi
 | `## QA Review for Issue #N` | QA phase comment header |
 | `### Verdict:` | Contains AC_NOT_MET, AC_MET_BUT_NOT_A_PLUS, etc. |
 | `### AC Coverage` | Table with MET/NOT_MET/PARTIALLY_MET statuses |
-| `### Required Fixes` or `### Recommendations` | Actionable items to fix |
+| `<!-- SEQUANT_QA_GAPS: {...} -->` | Structured findings — the primary source for `recommendations` (#937; see below) |
 
 **Parsing QA comment:**
 
@@ -116,14 +128,58 @@ verdict=$(echo "$qa_comment" | grep -oE "Verdict:\s*\w+" | head -1 | awk '{print
 # Extract NOT_MET AC items
 not_met_acs=$(echo "$qa_comment" | grep -E "NOT_MET|PARTIALLY_MET" || true)
 
-# Extract recommendations section
-recommendations=$(echo "$qa_comment" | sed -n '/### Required Fixes/,/###/p' | head -n -1)
+# #937: prefer the structured SEQUANT_QA_GAPS marker over prose scraping.
+# `### Required Fixes` was removed — no QA output template ever emitted that
+# heading, so the old `sed -n '/### Required Fixes/,/###/p'` extraction was
+# dead code that always produced an empty `recommendations`. The marker's
+# payload is an array of objects, so a single node -e does the stripping,
+# matching, AND JSON.parse/filter in one script — instead of hand-rolled
+# jq/awk — mirroring the "do real parsing in TS/JS, keep shell to presence
+# checks" split from the #871 drift-guard lesson (the same taxonomy filter
+# also lives in `selectFixableGaps`, `src/lib/workflow/phase-executor.ts` —
+# this is the shell-side mirror for standalone/orchestrated-comment-scrape
+# mode, not a duplicate contract).
+#
+# Stripping fenced/inline code before matching mirrors `stripMarkdownCode`
+# (src/lib/workflow/phase-detection.ts) — a bare grep/sed would mistake a
+# marker quoted inside a code fence (e.g. this skill's own "QA Log Example"
+# below) for a real one. Latest-wins if more than one marker is present,
+# matching `parseQaGapsMarker`'s semantics.
+recommendations=$(printf '%s' "$qa_comment" | node -e '
+  let input = "";
+  process.stdin.on("data", (d) => (input += d));
+  process.stdin.on("end", () => {
+    const stripped = input
+      .replace(/`{3,}[\s\S]*?`{3,}|~{3,}[\s\S]*?~{3,}/g, "")
+      .replace(/`[^`\n]+`/g, "");
+    const matches = [...stripped.matchAll(/<!-- SEQUANT_QA_GAPS: (\{[\s\S]*?\}) -->/g)];
+    if (matches.length === 0) return;
+    try {
+      const payload = JSON.parse(matches[matches.length - 1][1]);
+      const findings = Array.isArray(payload.findings) ? payload.findings : [];
+      for (const f of findings) {
+        if (f.recommendedAction === "document" || f.recommendedAction === "pause_for_human") continue;
+        console.log(`- ${f.description}`);
+      }
+    } catch {
+      // Malformed marker JSON — leave recommendations empty, not a crash.
+    }
+  });
+' || true)
+
+# No marker (QA output predates #937, or emitted an empty findings array
+# with everything filtered) — fall back to the AC-table NOT_MET/PARTIALLY_MET
+# rows already captured above; there is no prose "Required Fixes" section to
+# scrape.
+if [[ -z "$recommendations" ]]; then
+  recommendations="$not_met_acs"
+fi
 ```
 
-**If no QA comment found in orchestrated mode:**
-1. Log a clear error: `"Warning: No QA comment found in issue #N"`
+**If neither an embedded `SEQUANT_PROMPT_CONTEXT` block nor a matching GitHub QA comment is found in orchestrated mode:**
+1. Log a clear error: `"Warning: No embedded context or QA comment found for issue #N"`
 2. Fall back to Step 1B (log file) as a recovery mechanism
-3. If log file also doesn't exist, exit with error
+3. If log file also doesn't exist, exit with error — do not silently report "no actionable issues"; a silent miss here is the exact failure mode this section exists to prevent (#960)
 
 #### Step 1B: Standalone Mode (no SEQUANT_ORCHESTRATOR)
 
@@ -178,13 +234,14 @@ Some QA findings are real but **not fixable by a code change**. Feeding them to
 | Class | Marker in the QA comment | Why it is not actionable |
 |-------|--------------------------|--------------------------|
 | Infra-blocked CI | `<!-- qa:ci-infra-blocked -->` | Every check failed without a runner ever starting (e.g. an Actions spending-limit lockout). The cause is account/infrastructure state; no diff can turn the checks green. See `qa/SKILL.md` § "Infra-Blocked CI Detection". |
+| `document`/`pause_for_human` findings | `<!-- SEQUANT_QA_GAPS: {...} -->`, per-finding `recommendedAction` | Quality/polish gaps deliberately deferred (`document`), or findings needing a human decision the loop can't make on its own (`pause_for_human`) — see #937. Filtered directly out of the `recommendations` extraction above (Step 1A), not by rebinding `qa_comment` — the marker's structure makes a per-finding filter more precise than a text-range delete. |
 
 ```bash
 # Drop the marked findings when QA flagged CI as infra-blocked, so its
 # NEEDS_VERIFICATION AC items are never mistaken for actionable findings.
 # Range is EXCLUSIVE of the next `### ` header — a `sed '/marker/,/^### /d'`
 # range would delete that header too and orphan the following section's
-# content (verified: it silently swallows `### Required Fixes`).
+# content (verified against this file's own `### AC Coverage` header).
 qa_comment_raw="$qa_comment"   # keep the original so the cause can be reported verbatim
 
 if echo "$qa_comment" | grep -q '<!-- qa:ci-infra-blocked -->'; then
@@ -513,13 +570,15 @@ For each iteration, output:
 
 ### Verdict: AC_NOT_MET
 
-### Required Fixes
+### Next Steps
 
 1. Complete URL validation in ExternalUrlTab
 2. Add focal point persistence in updateArticleImage action
+
+<!-- SEQUANT_QA_GAPS: {"findings":[{"category":"requirement_gap","evidence":"AC-3 row: PARTIALLY_MET — External URL validation incomplete","description":"Complete URL validation in ExternalUrlTab","recommendedAction":"fix_now","affectedAcs":["AC-3"]},{"category":"requirement_gap","evidence":"AC-4 row: NOT_MET — Focal point not persisted to database","description":"Add focal point persistence in updateArticleImage action","recommendedAction":"fix_now","affectedAcs":["AC-4"]}]} -->
 ```
 
-**Parsed Output:**
+**Parsed Output** (marker-derived — this is the real emission shape, see §"How to build the marker" in `qa/SKILL.md`):
 - Last phase: `/qa`
 - Verdict: `AC_NOT_MET`
 - Issues to fix:

package/templates/skills/merger/SKILL.md

@@ -540,6 +540,32 @@ On a *failure* exit instead, the release is done at the halt site — the
 regression gate (Step 7) or "Error Handling" — never both, so exactly one release
 runs per invocation.
 
+<!-- BEGIN: named-set-boundary (#961) -->
+## Named-Set Boundary (REQUIRED)
+
+`/merger <issue-numbers>` is the user's consent to merge **exactly those
+issues** — invoking it is the explicit authorization, the same way `sequant
+merge`/`sequant merge --watch` are explicit and human-triggered (#958's
+Non-Goals). That consent does not extend past the named set: never let
+Dependency Detection or Stacked PR Detection below pull an**other** issue's PR
+into `gh pr merge` just because it happens to unblock or precede a named one.
+
+**Rule:** if merge ordering requires a PR whose issue number is **not** in the
+invocation's arg list, halt before merging anything and report it — do not
+widen the merge silently, and do not treat the stacked-PR "Continue anyway?
+(y/N)" confirmation as license to include an unnamed predecessor. Offer the
+widened command for the user to re-run:
+
+```text
+❌ Out-of-named-set dependency
+   #101 depends on #100, but #100 was not in your /merger invocation.
+   Halting before any merge.
+   To include it: /merger 100 101
+```
+
+This rule governs both sections below.
+<!-- END: named-set-boundary (#961) -->
+
 ## Dependency Detection
 
 Parse dependencies from issue body or comments:
@@ -557,7 +583,9 @@ Labels: depends-on/10
 gh issue view <issue> --json body,labels | jq '.body, .labels[].name'
 ```
 
-If dependencies found, enforce merge order.
+If dependencies found, enforce merge order **among the named set**. If a
+dependency's issue number falls outside the named set, apply the Named-Set
+Boundary rule above: halt and report instead of merging it.
 
 ### Stacked PR Detection (#605)
 
@@ -578,8 +606,9 @@ gh pr view <PR_NUMBER> --json baseRefName,body | \
 
 1. Extract the stack manifest from each PR's body (`Part of stack: #100 → #101 (this) → #102`).
 2. Treat the order in the manifest as the merge order — earlier entries land first.
-3. If the user requests an out-of-order merge (e.g. `/merger 102 100 101` for the stack above), **warn before proceeding** and recommend the manifest order.
-4. GitHub auto-updates the dependent PR's base when its predecessor merges, so once the order is correct no manual rebasing is needed.
+3. If **every** predecessor is in the named set but requested out of order (e.g. `/merger 102 100 101` for the stack above), **warn before proceeding** and recommend the manifest order.
+4. If a predecessor is **not** in the named set at all (e.g. `/merger 102` alone for that stack), the Named-Set Boundary rule applies: halt and report — do not fall through to the "Continue anyway? (y/N)" prompt, since that prompt is for reordering named issues, not for merging an unnamed one.
+5. GitHub auto-updates the dependent PR's base when its predecessor merges, so once the order is correct no manual rebasing is needed.
 
 **Warning template:**
 

package/templates/skills/qa/SKILL.md

@@ -2402,6 +2402,181 @@ Two classes are explicitly **not** findings. Legitimate imperative *requirements
 
 ---
 
+### 6h. Declared-Evidence Execution (REQUIRED for evidence-bearing ACs)
+
+**Purpose:** For any AC with a declared `Evidence:` clause naming a runnable command, verify that exact command was executed against this diff (or a captured run of it verified) before marking the AC `MET`. Closes the #853 "marked MET by construction" path (#938) — a declared, checkable claim that goes unexecuted is a bug, not a checkbox.
+
+**When to apply:** Any AC whose stored state includes a non-empty `evidence` field naming a backtick-quoted command (i.e., `verificationMethod` resolved to `unit_test` or `integration_test` via declaration, not inference — see `resolveVerificationMethod` in `ac-parser.ts`). Skip entirely when no AC declares a runnable command (cheap short-circuit).
+
+**How to perform:**
+
+```bash
+# Retrieve declared evidence per AC from state.
+npx tsx -e '
+(async () => {
+  const sm = await import("./src/lib/workflow/state-manager.ts");
+  const mgr = new sm.StateManager(process.cwd());
+  const ac = await mgr.getAcceptanceCriteria(<issue-number>);
+  const declared = (ac?.items ?? []).filter(
+    (i) => i.evidence && /`[^`]+`/.test(i.evidence),
+  );
+  console.log(JSON.stringify(declared.map((i) => ({ id: i.id, evidence: i.evidence })), null, 2));
+})();
+'
+```
+
+For each AC returned, **execute the exact backtick-quoted command** — or verify a captured run of it from earlier in this session's tool output — and record its exit code / pass-fail result before marking that AC `MET`. Do not mark a declared-evidence AC `MET` on reasoning alone; that is precisely the #853 gap this section closes.
+
+**Status outcomes:**
+
+| Status | Criteria |
+|--------|----------|
+| **Complete** | Every declared-evidence AC's command was executed (or a captured prior run verified) this QA pass |
+| **Incomplete** | One or more declared-evidence ACs have no executed/verified command |
+| **N/A** | No AC declares evidence with a runnable command |
+
+**AC marking and verdict gating:**
+
+- A declared-evidence AC whose command was NOT executed or verified this pass → AC status = `PENDING` (increments `pending_count`, same mechanism as the Manual Test AC Enforcement in step 3a) — it cannot be marked `MET` on reasoning alone.
+- `declared_evidence_status == "Incomplete"` also floors the verdict directly — see step 4's `Section 6h` branch.
+
+**Output Format:**
+
+```markdown
+### Declared-Evidence Execution
+
+| AC | Evidence | Executed? | Result |
+|----|----------|-----------|--------|
+| AC-N | `npm test -- reset-expiry` | Yes | ✅ 4 passed |
+| AC-M | `npx sequant doctor --help` | No | ⚠️ Not run — AC marked PENDING |
+
+**Status:** Complete / Incomplete / N/A
+```
+
+---
+
+### 6i. Mutation Verification (REQUIRED for gate-test ACs)
+
+**Purpose:** CLAUDE.md's testing rule — "Gate tests ship with a recorded mutation result: delete the thing it asserts, confirm exactly that test fails, restore, and record the result" — was honor-system prose until now: nothing parsed or checked the recorded result, so compliance was invisible (#830, and the same "prose only, and therefore unenforceable" defect class #834 fixed for `/qa`'s own §7 gates). This section promotes that record to a parseable `SEQUANT_MUTATION` PR-body marker and gates on it.
+
+**When to apply:** Any AC whose declared `evidence` text matches the CLAUDE.md gate-test definition — a fixture-exists / section-present / flag-wired assertion (see `isGateTestEvidence` in `ac-parser.ts`). Skip entirely when no AC in the diff is a gate-test AC (cheap short-circuit — mark N/A).
+
+> **Scope note (v1):** gate-test ACs only, not every AC with a declared runnable-command `Evidence:` clause. The population widens after a backtest measures the real authoring burden (#939 AC-5) — see that issue for the human-decision record if this scope is revisited.
+
+**How to perform:**
+
+```bash
+# 1. Identify in-scope (gate-test) ACs for this issue.
+npx tsx -e '
+(async () => {
+  const sm = await import("./src/lib/workflow/state-manager.ts");
+  const acp = await import("./src/lib/ac-parser.ts");
+  const mgr = new sm.StateManager(process.cwd());
+  const ac = await mgr.getAcceptanceCriteria(<issue-number>);
+  const gateTests = (ac?.items ?? []).filter(
+    (i) => i.evidence && acp.isGateTestEvidence(i.evidence),
+  );
+  console.log(JSON.stringify(gateTests.map((i) => ({ id: i.id, evidence: i.evidence })), null, 2));
+})();
+'
+
+# 2. Parse SEQUANT_MUTATION markers from the PR body — this single call
+#    both parses AND rejects: given the diff's test-file paths, each
+#    returned marker carries a "classification" ("valid" or
+#    "test_not_in_diff"), so a marker naming a test absent from the diff
+#    is surfaced, not silently dropped.
+npx tsx -e '
+(async () => {
+  const mm = await import("./src/lib/workflow/mutation-marker.ts");
+  const prBody = process.argv[1];
+  const diffTestFiles = process.argv.slice(2);
+  const markers = mm.parseMutationMarkers(prBody, diffTestFiles);
+  const byAc = new Map(markers.map((m) => [m.ac, m]));
+  for (const [ac, marker] of byAc) {
+    console.log(ac, marker.classification, marker.failedTest);
+  }
+})();
+' -- "$PR_BODY" $(git diff origin/main...HEAD --diff-filter=AM --name-only | grep -E '\.(test|spec)\.')
+```
+
+**Safety rules (carry into any manual mutation performed during this check, per #883 and the commit-before-mutating discipline):**
+- **Commit before mutating.** `git checkout <file>` to revert a mutation wipes any uncommitted edits in that file, not just the mutation.
+- **Never mutate a variable a `finally` block passes to `rmSync`.** A mutation that touches cleanup-path state can delete a worktree (#883's motivating incident).
+
+**Per-AC status outcomes:**
+
+| Status | Criteria |
+|--------|----------|
+| **Verified** | The in-scope AC has a `SEQUANT_MUTATION` marker whose `failedTest` names a test file present in the diff |
+| **Missing** | The in-scope AC has no `SEQUANT_MUTATION` marker |
+| **Failed** | The in-scope AC has a marker naming a test file NOT present in the diff — a fabricated marker is worse than a missing one |
+
+**Aggregate `mutation_verification_status`** (the single §7 step-2 token — worst case across in-scope ACs wins, mirroring §6e's per-AC-table-to-single-status rollup): `Failed` if any in-scope AC is `Failed`; else `Missing` if any in-scope AC is `Missing`; else `Verified` if every in-scope AC is `Verified`; `Not-Applicable` when no AC in the diff is a gate-test AC.
+
+**AC marking and verdict gating:**
+
+- Aggregate `Missing` → the mutation-verification gate caps the verdict at `AC_MET_BUT_NOT_A_PLUS` regardless of individual ACs' own MET status — see step 4's `mutation_verification_status == "Missing"` branch.
+- Aggregate `Failed` → floor the verdict at `AC_NOT_MET` — see step 4's `mutation_verification_status == "Failed"` branch. This is a hard floor, not a soft cap: a marker naming a test absent from the diff is affirmatively false evidence, not merely absent evidence.
+
+**Output Format:**
+
+```markdown
+### Mutation Verification
+
+| AC | Gate Test? | Marker | Status |
+|----|-----------|--------|--------|
+| AC-N | Yes | `injection.test.ts > rejects payload` | Verified |
+| AC-M | Yes | — | Missing |
+| AC-P | Yes | `nonexistent.test.ts > some test` | Failed — test not in diff |
+| AC-Q | No | — | N/A |
+
+**Status:** Verified / Missing / Failed / Not-Applicable
+```
+
+---
+
+### 6j. Structured Gap Findings (REQUIRED)
+
+**Purpose:** `parseQaSummary`'s gap channel (`src/lib/workflow/phase-executor.ts`) used to scrape only the `**Issues:**` bullet list under Code Review — one specific spot in this template. It missed AC-table `NOT_MET`/`PARTIALLY_MET` rows, §6d Adversarial Re-Read findings, and §5/Risk Assessment gaps entirely, so a QA pass that failed on a §6d "Severe Gap" could hand `/loop` an empty findings list (#937). This section closes that gap: every finding this review surfaces — anywhere in the output, not just Code Review — gets classified into the taxonomy below and emitted as one machine-readable marker.
+
+**Taxonomy** (finite — six categories, pick the closest fit):
+
+| Category | Use for |
+|----------|---------|
+| `requirement_gap` | An AC (or a table row) is `NOT_MET`/`PARTIALLY_MET` |
+| `dependency_gap` | Missing/incompatible dependency, unregistered CLI flag, wiring gap (§2h, §3g-class) |
+| `test_gap` | Missing/tautological/insufficient test coverage (§2b, §2d, §6i Missing/Failed) |
+| `repository_gap` | Code quality, duplication, anti-pattern, dead code (§2, §2e) |
+| `risk_gap` | §5 Risk Assessment item, §6d Adversarial Re-Read finding, §6f Trust-Boundary finding |
+| `execution_gap` | Build/lint/CI failure, script/CLI execution failure (§2a, §Phase 1 CI Status) |
+
+**Per-finding fields:**
+
+| Field | Required? | Content |
+|-------|-----------|---------|
+| `category` | Yes | One of the six above |
+| `evidence` | Yes | A concrete observation — file:line, failing check name, or table row — never speculation |
+| `description` | Yes | One-sentence statement of the gap (same text you'd put in a prose bullet) |
+| `recommendedAction` | Yes | `fix_now` (blocks `READY_FOR_MERGE`, actionable by a code change), `document` (real but non-blocking — quality/polish, or explicitly deferred), or `pause_for_human` (needs a decision `/loop` cannot make, e.g. `SCOPE_SPLIT_RECOMMENDED`-class ambiguity) |
+| `affectedAcs` | If applicable | e.g. `["AC-3"]` |
+| `nonGoal` | If applicable | `true` when the finding overlaps one of the issue's Non-Goals — report-only under `ac` policy, same semantics as `ReadyGapItem.nonGoal` |
+
+**Fallback rule (no dropped findings):** if a real finding does not fit any of the six categories, **do not force it into the marker** — leave it as prose only (in Code Review's `**Issues:**`, Risk Assessment, or wherever it naturally belongs). The marker narrows the *structured* channel; every consumer that reads it also unions it with the prose scrape, so an unclassifiable finding is never silently lost — it just doesn't get machine-readable category/action metadata.
+
+**How to build the marker:** after finishing every other section, walk back through this review's own output — the AC Coverage table's non-MET rows, §5 Risk Assessment, §6d Adversarial Re-Read (Standard only), §6f Trust-Boundary, and Code Review's `**Issues:**` — and classify each real finding. Append exactly one marker as the LAST line of the comment (after `### Next Steps`), single-line flat-ish JSON (no line breaks inside the `{...}`, and no literal `-->` inside any string value — both would break the parser's `[\s\S]*?-->` match):
+
+```markdown
+<!-- SEQUANT_QA_GAPS: {"findings":[{"category":"requirement_gap","evidence":"AC-3 table row: NOT_MET — no rate limit found in src/retry.ts","description":"AC-3 (rate limiting) is not implemented","recommendedAction":"fix_now","affectedAcs":["AC-3"]}]} -->
+```
+
+When there are no findings to report (clean pass), still emit the marker with an empty array — this positively confirms the structured channel ran, rather than leaving `/loop` to distinguish "clean" from "QA output predates this marker":
+
+```markdown
+<!-- SEQUANT_QA_GAPS: {"findings":[]} -->
+```
+
+---
+
 
 ### 7. A+ Status Verdict
 
@@ -2433,6 +2608,8 @@ Provide an overall verdict:
    - adversarial_reread_status = status from Section 6d (Clean/Gaps Found/Severe Gap) — REQUIRED for Standard QA, omitted for Simple Fix
    - behavior_rule_survival_status = status from Section 6e (Clean/Survivors Found/N/A) — REQUIRED when any AC triggers the behavior-rule heuristic, omitted otherwise
    - trust_boundary_status = status from Section 6f (Clean/Injection Acted On) — REQUIRED in **both** Standard QA and Simple Fix mode (unlike 6d, it is never omitted: an injected command is a small diff by definition)
+   - declared_evidence_status = status from Section 6h (Complete/Incomplete/N/A) — REQUIRED when any AC declares evidence naming a runnable command, `N/A` otherwise
+   - mutation_verification_status = status from Section 6i (Verified/Missing/Failed/Not-Applicable) — REQUIRED when any AC is a gate-test AC per `isGateTestEvidence`, `Not-Applicable` otherwise
    - cli_registration_status = status from Section 2h (Passed/Failed/N/A) — REQUIRED when option interfaces are modified, `N/A` otherwise; omitted in Simple Fix mode along with the rest of §2h
    - script_verification_status = status from Section 11 (Verified/Overridden/Not Verified/Not Required) — REQUIRED when `scripts/` or `templates/scripts/` files are modified, `Not Required` otherwise
    - changelog_required = true IFF Section 10a's `CHANGELOG.md` exists AND Section 10a's `user_facing` count is >0 (single source of truth — see §10a for the conventional-commit detection regex, which accepts unscoped, scoped, and breaking variants of `feat`/`fix`/`perf`/`refactor`/`docs`); false otherwise
@@ -2467,12 +2644,18 @@ Provide an overall verdict:
        → AC_NOT_MET (the diff acted on an agent-directed instruction embedded in untrusted external text — see Section 6f and _shared/references/trust-model.md; name the instruction verbatim with its path:line)
    - ELSE IF cli_registration_status == "Failed":
        → AC_NOT_MET (an option-interface field has runtime `mergedOptions.X` usage but no `.option()` registration in `bin/cli.ts`, so users cannot reach the feature from the command line — invisible to TypeScript, build, and unit tests; see Section 2h and #305. Name each unregistered field.)
+   - ELSE IF mutation_verification_status == "Failed":
+       → AC_NOT_MET (a `SEQUANT_MUTATION` marker names a test file absent from this diff — a fabricated mutation-verification record; see Section 6i and #939. A fabricated marker is worse than a missing one.)
    - ELSE IF adversarial_reread_status == "Severe Gap":
        → AC_NOT_MET (verbatim motivating-example fixture not run / evidence claim is bug reproduction not validation / AC marked MET without runtime or corpus check the AC text required)
    - ELSE IF skill_verification == "Failed":
        → AC_MET_BUT_NOT_A_PLUS (skill commands have issues - cannot be READY_FOR_MERGE)
    - ELSE IF execution_evidence == "Incomplete":
        → AC_MET_BUT_NOT_A_PLUS (scripts not verified - cannot be READY_FOR_MERGE)
+   - ELSE IF declared_evidence_status == "Incomplete":
+       → AC_MET_BUT_NOT_A_PLUS (a declared `Evidence:` command was not executed/verified for one or more ACs - see Section 6h; the #853 "marked MET by construction" path)
+   - ELSE IF mutation_verification_status == "Missing":
+       → AC_MET_BUT_NOT_A_PLUS (a gate-test AC has no recorded `SEQUANT_MUTATION` marker - see Section 6i; the honor-system-prose gap #939 closes)
    - ELSE IF script_verification_status == "Not Verified":
        → AC_MET_BUT_NOT_A_PLUS (`scripts/` changed with no `/verify` evidence and no approved §11a override — code review and unit tests miss integration failures; see Section 11)
    - ELSE IF changelog_required AND changelog_missing:
@@ -2713,7 +2896,10 @@ Produce a Markdown snippet for the PR/issue:
 ### 9. Update GitHub Issue
 
 **If orchestrated (SEQUANT_ORCHESTRATOR is set):**
-- Skip posting GitHub comment (orchestrator handles aggregated summary)
+- Skip posting this skill's own GitHub comment — under `sequant run`,
+  `batch-executor.ts` posts a compact verdict comment (AC coverage + a
+  `SEQUANT_QA_VERDICT` marker) itself right after this phase completes with a
+  parseable verdict (#964); don't post a second, redundant one here
 - Include verdict and AC coverage in output for orchestrator to capture
 - Let orchestrator update labels based on final workflow status
 
@@ -2932,7 +3118,7 @@ When the size gate determined `SMALL_DIFF=true`, use the **simplified output tem
 - Skill Change Review
 - Adversarial Re-Read
 
-**Not omitted:** the Trust-Boundary Check (§6f), the Behavior-Rule Survival Check (§6e), and the CHANGELOG Quality Gate (§10a) are all required in simple fix mode too — each is cheap, and each guards a defect class that a small diff is a *likely* carrier of rather than an unlikely one. Every `(REQUIRED` section must appear in either the required list below or the omitted list above; `scripts/lint-skill-gates.ts` (I3) fails the build on silence, because silence is how #819 F2 shipped a security check that Simple Fix mode switched off.
+**Not omitted:** the Trust-Boundary Check (§6f), the Behavior-Rule Survival Check (§6e), the Declared-Evidence Execution check (§6h), the Mutation Verification check (§6i), and the CHANGELOG Quality Gate (§10a) are all required in simple fix mode too — each is cheap (a short-circuit to N/A when no AC qualifies), and each guards a defect class that a small diff is a *likely* carrier of rather than an unlikely one — a gate test (fixture/section/flag assertion) is very often itself a small, localized diff. Every `(REQUIRED` section must appear in either the required list below or the omitted list above; `scripts/lint-skill-gates.ts` (I3) fails the build on silence, because silence is how #819 F2 shipped a security check that Simple Fix mode switched off.
 
 **Required sections for simple fix mode:**
 
@@ -2944,12 +3130,15 @@ When the size gate determined `SMALL_DIFF=true`, use the **simplified output tem
 - [ ] **Anti-Pattern Detection** - Code patterns check (lightweight)
 - [ ] **Trust-Boundary Check** - Required in simple fix mode too (see Section 6f); "Finding:" and "Status:" lines populated
 - [ ] **Behavior-Rule Survival Check** - Required in simple fix mode too (see Section 6e): a #533-class stale-rule survival is very plausibly a sub-threshold diff. Cheap short-circuit — mark "N/A" when no AC triggers the behavior-rule heuristic
+- [ ] **Declared-Evidence Execution** - Required in simple fix mode too (see Section 6h): a declared-evidence AC marked MET without running its command is exactly the #853 gap, regardless of diff size. Cheap short-circuit — mark "N/A" when no AC declares evidence naming a runnable command
+- [ ] **Mutation Verification** - Required in simple fix mode too (see Section 6i): a gate-test AC merged without a recorded mutation result is exactly the #830 gap, regardless of diff size. Cheap short-circuit — mark "N/A" when no AC is a gate-test AC
 - [ ] **CHANGELOG Verification** - Required in simple fix mode too (see Section 10a): a one-line user-facing fix still needs an `[Unreleased]` entry (or marked N/A)
 - [ ] **Risk Assessment** - Likely failure mode and coverage gaps stated
 - [ ] **Verdict** - One of: READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, NEEDS_VERIFICATION, AC_NOT_MET
 - [ ] **Documentation Check** - README/docs updated if feature adds new functionality
 - [ ] **Next Steps** - Clear, actionable recommendations
 - [ ] Adversarial re-read of core logic — list anything the structured pipeline didn't surface
+- [ ] **Structured Gap Findings** - `SEQUANT_QA_GAPS` marker present as the last line, findings classified per Section 6j (or `{"findings":[]}` on a clean pass)
 
 ### Standard QA (Implementation Exists, `SMALL_DIFF=false`)
 
@@ -2973,6 +3162,8 @@ When the size gate determined `SMALL_DIFF=true`, use the **simplified output tem
 - [ ] **Detection Pattern Verification** - Included if skill markdown adds new `grep`/`awk`/`jq`/`sed`/regex (or marked N/A)
 - [ ] **CLI Registration Verification** - Included if option interfaces modified (or marked N/A — see Section 2h); `Failed` floors the verdict at `AC_NOT_MET` via §7
 - [ ] **Behavior-Rule Survival Check** - Included if any AC triggers the behavior-rule heuristic (or marked N/A — see Section 6e); `Survivors Found` floors the verdict at `AC_NOT_MET` via §7
+- [ ] **Declared-Evidence Execution** - Included if any AC declares evidence naming a runnable command (or marked N/A — see Section 6h); `Incomplete` floors the verdict at `AC_MET_BUT_NOT_A_PLUS` via §7, and an unexecuted AC is marked PENDING rather than MET
+- [ ] **Mutation Verification** - Included if any AC is a gate-test AC per `isGateTestEvidence` (or marked Not-Applicable — see Section 6i); `Missing` floors the verdict at `AC_MET_BUT_NOT_A_PLUS` via §7, `Failed` floors it at `AC_NOT_MET`
 - [ ] **Skill Change Review** - Skill-specific verification prompts included if skills changed
 - [ ] **Smoke Test** - Included if workflow-affecting changes (skills, scripts, CLI), or marked "Not Required"
 - [ ] **Manual Test AC Enforcement** - Included if spec plan has Manual Test ACs (or marked N/A if no manual-test ACs detected)
@@ -2981,6 +3172,7 @@ When the size gate determined `SMALL_DIFF=true`, use the **simplified output tem
 - [ ] **Adversarial Re-Read** - Required structured section: all 5 sub-prompts answered with concrete content; "Findings:" and "Status:" lines populated; bare "No gaps" without specific reasoning fails verification (see Section 6d)
 - [ ] **Documentation Check** - README/docs updated if feature adds new functionality
 - [ ] **Next Steps** - Clear, actionable recommendations
+- [ ] **Structured Gap Findings** - `SEQUANT_QA_GAPS` marker present as the last line, findings classified per Section 6j (or `{"findings":[]}` on a clean pass)
 
 ### Early Exit (No Implementation)
 
@@ -3083,6 +3275,26 @@ When the size gate triggers simple fix mode, use this shorter template:
 
 ---
 
+### Declared-Evidence Execution
+
+| AC | Evidence | Executed? | Result |
+|----|----------|-----------|--------|
+| AC-N | `<command>` or — | Yes/No/— | [pass-fail result, or "Not run — AC marked PENDING"] |
+
+**Status:** Complete / Incomplete / N/A
+
+---
+
+### Mutation Verification
+
+| AC | Gate Test? | Marker | Status |
+|----|-----------|--------|--------|
+| AC-N | Yes/No | `<file.test.ts > test name>` or — | Verified / Missing / Failed / N/A |
+
+**Status:** Verified / Missing / Failed / Not-Applicable
+
+---
+
 ### CHANGELOG Verification
 
 **Result:** [CHANGELOG requirements met / Missing entry for user-facing changes / N/A (non-user-facing changes only)]
@@ -3110,6 +3322,10 @@ When the size gate triggers simple fix mode, use this shorter template:
 ### Next Steps
 
 1. [Action item]
+
+### Structured Gap Findings
+
+<!-- SEQUANT_QA_GAPS: {"findings":[...]} -->
 ```
 
 ---
@@ -3453,6 +3669,31 @@ You MUST include these sections:
 
 ---
 
+### Declared-Evidence Execution
+
+| AC | Evidence | Executed? | Result |
+|----|----------|-----------|--------|
+| AC-N | `npm test -- reset-expiry` | Yes | ✅ 4 passed |
+| AC-M | `npx sequant doctor --help` | No | ⚠️ Not run — AC marked PENDING |
+| AC-P | — | — | N/A (no declared evidence) |
+
+**Status:** Complete / Incomplete / N/A
+
+---
+
+### Mutation Verification
+
+| AC | Gate Test? | Marker | Status |
+|----|-----------|--------|--------|
+| AC-N | Yes | `injection.test.ts > rejects payload` | Verified |
+| AC-M | Yes | — | Missing |
+| AC-P | Yes | `nonexistent.test.ts > some test` | Failed — test not in diff |
+| AC-Q | No | — | N/A |
+
+**Status:** Verified / Missing / Failed / Not-Applicable
+
+---
+
 ### CHANGELOG Verification
 
 | Check | Status |
@@ -3489,4 +3730,8 @@ You MUST include these sections:
 
 1. [Action item 1]
 2. [Action item 2]
+
+### Structured Gap Findings
+
+<!-- SEQUANT_QA_GAPS: {"findings":[...]} -->
 ```

package/templates/skills/spec/SKILL.md

@@ -374,15 +374,19 @@ actually posted via `gh issue comment`, not just shown in this response.
 | Docs-only (`docs` label) | No | Skip testgen — no unit tests needed |
 | All ACs have "Manual Test" or "Browser Test" | No | Skip testgen — no code stubs to generate |
 
-**Detection logic:**
-1. Count ACs with "Unit Test" → If >0, recommend testgen
-2. Count ACs with "Integration Test" → If >0, recommend testgen
-3. Check labels: `bug`/`fix` only → Skip testgen. `docs` → Skip testgen.
+**Detection logic — declared evidence counts before inferred (#938):**
+
+`extractAcceptanceCriteria` resolves each AC's `verificationMethod` from a declared `Evidence:` clause when the AC line has one (`AC.evidence` is set), falling back to keyword inference only when it doesn't. Ground the recommendation in the stronger signal first:
+
+1. Count ACs with **declared** evidence (`AC.evidence` set) resolving to "Unit Test" or "Integration Test" → these are the reasoning's primary citation; if >0, recommend testgen and name them.
+2. Count remaining ACs — no declared evidence, method came from **inference** — that are "Unit Test" → if >0, recommend testgen.
+3. Count remaining inferred "Integration Test" ACs → if >0, recommend testgen.
+4. Check labels: `bug`/`fix` only → Skip testgen. `docs` → Skip testgen.
 
 **Example when testgen recommended:**
 ```markdown
 **Phases:** spec → testgen → exec → qa
-**Reasoning:** ACs include Unit Test verification methods; testgen will create stubs before implementation
+**Reasoning:** AC-1 declares evidence (`npm test -- reset-expiry`, unit_test); testgen will create stubs before implementation
 ```
 
 ### Browser Testing Label Suggestion

package/templates/skills/test/SKILL.md

@@ -582,7 +582,7 @@ Create structured test results:
 ### 3.2 GitHub Comment
 
 **If orchestrated (SEQUANT_ORCHESTRATOR is set):**
-- Skip posting GitHub comment (orchestrator handles summary)
+- Skip posting this skill's own GitHub comment — no per-phase comment is posted under `sequant run`; test results surface through the run summary and the PR body (#964)
 - Include test summary in output for orchestrator to capture
 - Let orchestrator aggregate results across phases