sequant 2.1.2 → 2.3.0

package/templates/skills/qa/SKILL.md

@@ -107,9 +107,11 @@ COMMIT_SHA=$(git rev-parse HEAD)
 ```
 
 ```markdown
-<!-- SEQUANT_PHASE: {"phase":"qa","status":"completed","timestamp":"<ISO-8601>","commitSHA":"<HEAD-SHA>"} -->
+<!-- SEQUANT_PHASE: {"phase":"qa","status":"completed","timestamp":"<ISO-8601>","commitSHA":"<HEAD-SHA>","verdict":"<READY_FOR_MERGE|AC_MET_BUT_NOT_A_PLUS|NEEDS_VERIFICATION>"} -->
 ```
 
+**Note:** The `verdict` field is required on `status:"completed"` markers so the Phase 0a short-circuit can surface the prior verdict without re-reading the comment body. Older markers without this field are still accepted — Phase 0a falls back to `(see prior QA comment)`.
+
 If QA determines AC_NOT_MET, emit:
 ```markdown
 <!-- SEQUANT_PHASE: {"phase":"qa","status":"failed","timestamp":"<ISO-8601>","error":"AC_NOT_MET","commitSHA":"<HEAD-SHA>"} -->
@@ -122,9 +124,23 @@ Include this marker in every `gh issue comment` that represents QA completion.
 Invocation:
 
 - `/qa 123`: Treat `123` as the GitHub issue/PR identifier in context.
+- `/qa 123 172`: Treat both as issue numbers — process each sequentially.
 - `/qa <freeform description>`: Treat the text as context about the change to review.
 - `/qa 123 --parallel`: Force parallel agent execution (faster, higher token usage).
 - `/qa 123 --sequential`: Force sequential agent execution (slower, lower token usage).
+- `/qa 123 --force`: Bypass prior-QA short-circuit and force a full re-run even if the last QA covers the current commit.
+
+### Multi-Issue Invocation
+
+When multiple issue numbers are provided (e.g., `/qa 167 172`):
+
+1. **Parse all issue numbers** from args
+2. **Process each issue sequentially** with inline code review — do NOT spawn ad-hoc background agents for the diff reading or AC verification portions
+3. The built-in `sequant-qa-checker` sub-agents (type safety, scope, security) continue to run per the size gate rules for each issue
+4. Each issue gets its own full QA cycle: context fetch → diff review → quality checks → verdict → comment
+5. Post a **separate QA comment** to each issue's GitHub thread
+
+**Why sequential with inline review:** Ad-hoc background agents for code review are unreliable — they hallucinate about file existence, misattribute API patterns, and hit permission issues on worktree reads. The narrowly-scoped `sequant-qa-checker` agents work well because they have specific, bounded tasks. The code review portion must stay inline for accuracy.
 
 ### Agent Execution Mode
 
@@ -487,6 +503,87 @@ fi
 
 ---
 
+### Phase 0a: Prior QA Short-Circuit Check
+
+**After confirming implementation exists** (Phase 0 passed), check whether a prior QA run already covers the current commit. This avoids re-running the full QA pipeline when nothing has changed.
+
+**Skip this check if any of these are true:**
+- `--force` flag is present in the invocation args
+- `--no-cache` flag is present in the invocation args
+- `SEQUANT_ORCHESTRATOR` is set and the orchestrator explicitly requests a fresh run
+
+**Detection Logic:**
+
+```bash
+# 1. Get current HEAD SHA
+current_sha=$(git rev-parse HEAD)
+
+# 2. Fetch the latest qa:completed or qa:failed phase marker from issue comments
+# NOTE: Use `.comments[].body` (NOT `[.comments[].body]`). The array form JSON-encodes
+# each body, escaping internal quotes (`"phase":"qa"` → `\"phase\":\"qa\"`) and `<` →
+# `\u003c`, which defeats the grep pattern below. The streaming form outputs raw bodies.
+latest_qa_marker=$(gh issue view <issue-number> --json comments --jq '.comments[].body' | \
+  grep -o '<!-- SEQUANT_PHASE: {[^}]*"phase":"qa"[^}]*} -->' | \
+  tail -1 || true)
+
+# 3. Extract status, commitSHA, verdict, and timestamp from the marker
+if [[ -n "$latest_qa_marker" ]]; then
+  marker_json=$(echo "$latest_qa_marker" | grep -o '{[^}]*}')
+  marker_status=$(echo "$marker_json" | jq -r '.status // empty' 2>/dev/null || true)
+  marker_sha=$(echo "$marker_json" | jq -r '.commitSHA // empty' 2>/dev/null || true)
+  marker_timestamp=$(echo "$marker_json" | jq -r '.timestamp // empty' 2>/dev/null || true)
+  marker_verdict=$(echo "$marker_json" | jq -r '.verdict // empty' 2>/dev/null || true)
+fi
+```
+
+**Short-Circuit Decision Matrix:**
+
+| marker_status | marker_sha == HEAD | Action |
+|---------------|-------------------|--------|
+| `completed` | Yes | **Short-circuit** — skip full QA |
+| `completed` | No | Proceed with full QA (new commits since last run) |
+| `failed` | Yes or No | Proceed with full QA (user likely wants re-run after fix) |
+| (not found) | N/A | Proceed with full QA (no prior run) |
+
+**When short-circuiting (status=completed, SHA matches):**
+
+1. **Skip** sub-agent spawning
+2. **Skip** code review and quality checks
+3. **Output** the short-circuit summary (template below)
+4. **Do NOT** post a new GitHub comment (the prior comment is still valid)
+
+**Short-Circuit Output Template:**
+
+Populate `**Prior Verdict:**` from `$marker_verdict` when non-empty. When empty (legacy marker without the field), substitute the literal string `(see prior QA comment)`.
+
+```markdown
+## QA Review for Issue #<N>
+
+### Prior QA Still Valid
+
+QA already completed at commit `<SHA>` on <timestamp> — no changes since last run.
+Current HEAD (`<current_sha>`) matches the previously reviewed commit.
+
+**Prior Verdict:** <$marker_verdict OR "(see prior QA comment)" if empty>
+
+To force a full re-run, use: `/qa <N> --force` or `/qa <N> --no-cache`
+
+---
+
+*QA short-circuited: prior run at same SHA is still valid*
+```
+
+**Verdict field handling:**
+
+| `$marker_verdict` | Action |
+|-------------------|--------|
+| Non-empty (new markers) | Emit literally: `**Prior Verdict:** READY_FOR_MERGE` (etc.) |
+| Empty (legacy markers) | Emit: `**Prior Verdict:** (see prior QA comment)` — the prior comment body contains the full verdict |
+
+The short-circuit itself still triggers in both cases — only the displayed verdict text differs.
+
+---
+
 ### Phase 0b: Quality Plan Verification (CONDITIONAL)
 
 **When to apply:** If issue has a Feature Quality Planning section in comments (from `/spec`).
@@ -599,6 +696,82 @@ quality_plan_exists=$(gh issue view <issue> --comments --json comments -q '.comm
 
 ---
 
+### Phase 0c: Precheck Findings (CONDITIONAL)
+
+**Purpose:** Consume deterministic gap-check output from `scripts/qa/precheck.ts`. The script handles three checks the agent doesn't need to evaluate but pays token cost for if inlined: verbatim motivating-example fixture extraction, cross-file sibling-grep on changed identifiers, and AC literal-id diff between issue body and PR body. Downstream sections (§1 AC Literal Verification, §5 Sibling-site Scan, §6c Step 4 Fixture Verification, §6d Q1 Verbatim Fixtures) consult the precheck output when available and fall back to inline logic on miss/error.
+
+**Origin:** #609 — extract deterministic gap-checks into a pre-QA gate. Backed by #608's signal-to-noise study (e.g. §6c at 0/11 actioned findings, ~1,800 tokens/invoke).
+
+**Run (best-effort, exit code is always 0 even on partial failure):**
+
+```bash
+issue=<issue-number>
+npx tsx scripts/qa/precheck.ts --issue "$issue" 2>/dev/null || true
+```
+
+The script also auto-detects the PR via `gh pr view --json number` and runs `git diff origin/main...HEAD` for the changed-identifier scan.
+
+**Output:** `.sequant/gap-precheck.json` (schemaVersion 1):
+
+```json
+{
+  "schemaVersion": 1,
+  "issue": 609,
+  "pr": 999,
+  "generatedAt": "...",
+  "checks": {
+    "fixtures":      { "status": "pass | not_applicable | fail", "count": N, "fixtures": [...] },
+    "siblingGrep":   { "status": "...", "identifiers": [{ "name": "...", "definedIn": "...", "siblingSites": [...] }] },
+    "acLiteralDiff": { "status": "...", "issueACs": [...], "prACs": [...], "missingInPR": [...] }
+  }
+}
+```
+
+**Consumption rules per downstream section:**
+
+| Precheck status | Downstream section behavior |
+|-----------------|-----------------------------|
+| `pass` | Use precheck output as primary input; agent judgment evaluates surfaced candidates (e.g. is each sibling-grep hit a real sibling site?) |
+| `not_applicable` | Treat as section N/A; do NOT inline-re-extract |
+| `fail` | Fall back to inline extraction (the section's pre-existing logic) |
+| Precheck JSON missing / malformed | Fall back to inline extraction; note "precheck unavailable" |
+
+**Fallback (precheck JSON missing / malformed):**
+
+```bash
+precheck_path=".sequant/gap-precheck.json"
+precheck_ok="no"
+if [[ -f "$precheck_path" ]]; then
+  schema=$(jq -r .schemaVersion "$precheck_path" 2>/dev/null || echo "")
+  if [[ "$schema" == "1" ]]; then
+    precheck_ok="yes"
+  fi
+fi
+# When precheck_ok=no, every downstream consumer falls back to its inline path.
+```
+
+Do NOT block the QA run on a missing precheck — the script is best-effort. The fallback path is the pre-#609 behavior, which still produces a correct verdict (just at higher token cost).
+
+**Output Format:**
+
+```markdown
+### Precheck Findings
+
+| Section | Status | Surfaced |
+|---------|--------|----------|
+| Fixtures | pass | 3 motivating-example fixtures (consumed by §6c Step 4 / §6d Q1) |
+| Sibling-grep | pass | 5 changed identifiers (candidate sites surfaced to §5) |
+| AC literal-diff | fail | Issue lists AC-3 / AC-4; PR body omits them |
+
+**Source:** `.sequant/gap-precheck.json` (schemaVersion 1)
+```
+
+If precheck unavailable, omit the table and emit a single line: `**Precheck Findings:** unavailable — inline fallback used.`
+
+**Verdict impact:** None directly. Phase 0c is plumbing — the downstream sections own the verdict effect when they consume the surfaced candidates.
+
+---
+
 ### Phase 1: CI Status Check — REQUIRED
 
 **Purpose:** Check GitHub CI status before finalizing verdict. CI-dependent AC items (e.g., "Tests pass in CI") should reflect actual CI status, not just local test results.
@@ -624,11 +797,13 @@ fi
 | `FAILURE` | `fail` | `NOT_MET` | Blocks merge |
 | `CANCELLED` | `fail` | `NOT_MET` | Blocks merge |
 | `SKIPPED` | `pass` | `N/A` | No impact |
-| `PENDING` | `pending` | `PENDING` | → `NEEDS_VERIFICATION` |
-| `QUEUED` | `pending` | `PENDING` | → `NEEDS_VERIFICATION` |
-| `IN_PROGRESS` | `pending` | `PENDING` | → `NEEDS_VERIFICATION` |
+| `PENDING` | `pending` | `PENDING` * | → `NEEDS_VERIFICATION` * |
+| `QUEUED` | `pending` | `PENDING` * | → `NEEDS_VERIFICATION` * |
+| `IN_PROGRESS` | `pending` | `PENDING` * | → `NEEDS_VERIFICATION` * |
 | (empty response) | - | `N/A` | No CI configured |
 
+\* Pending checks may be reclassified as `MET` (informational) when the diff is markdown-only and the check name matches `qa.markdownOnlySafeCiPatterns` — see "Markdown-Only Diff Relaxation" below for the gating-vs-relaxed partitioning rules. Failed checks are never relaxed.
+
 **CI-Related AC Detection:**
 
 Identify AC items that depend on CI by matching these patterns:
@@ -696,12 +871,72 @@ No CI checks configured for this repository.
 **Verdict Integration:**
 
 CI status affects the final verdict through the standard verdict algorithm:
-- CI `PENDING` → AC item marked `PENDING` → Verdict: `NEEDS_VERIFICATION`
+- CI `PENDING` (gating) → AC item marked `PENDING` → Verdict: `NEEDS_VERIFICATION`
+- CI `PENDING` (relaxed via the markdown-only block below) → AC item marked `MET` → no impact on verdict
 - CI `failure` → AC item marked `NOT_MET` → Verdict: `AC_NOT_MET`
 - CI `success` → AC item marked `MET` → No additional impact
 - No CI → AC item marked `N/A` → No impact on verdict
 
-**Important:** Do NOT give `READY_FOR_MERGE` if any CI check is still pending. The correct verdict is `NEEDS_VERIFICATION` with a note to re-run QA after CI completes.
+**Important:** Do NOT give `READY_FOR_MERGE` if any *gating* CI check is still pending. Pending checks are gating by default; the markdown-only relaxation below reclassifies a narrow allowlist as informational. When any gating-pending check remains, the correct verdict is `NEEDS_VERIFICATION` with a note to re-run QA after CI completes.
+
+#### Markdown-Only Diff Relaxation
+
+**Purpose:** A diff that touches only `.md` files cannot break the build matrix. Forcing `NEEDS_VERIFICATION` until the build matrix reports back wastes wakeup cycles when `typecheck` (already green) has proven the change is structurally inert. This relaxation reclassifies a small, configurable allowlist of pending checks (default: build matrix + Plugin Structure Validation) as informational for markdown-only diffs.
+
+**Scope and limits:**
+
+- **Only pending checks are relaxed.** Failed checks always gate, regardless of diff type.
+- **Only the configured allowlist is relaxed.** Other pending checks (`validate-skills`, `Hooks Validation`, `validate-plugin`, etc.) still gate.
+- **Build-affecting files disqualify the diff** even if every other change is `.md`. The detector treats `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `tsconfig*.json`, `*.config.{js,ts,mjs,cjs}`, and `.github/workflows/**` as non-markdown.
+
+**Settings (`.sequant/settings.json`, `qa` section):**
+
+| Key | Default | Effect |
+|-----|---------|--------|
+| `markdownOnlyCiRelaxed` | `true` | Master switch. Set to `false` to restore strict gating for paranoid projects. |
+| `markdownOnlySafeCiPatterns` | `["build (*)", "Plugin Structure Validation"]` | Glob patterns (single `*` wildcard) for CI check names that are safe to ignore when pending on a markdown-only diff. Override per project to match local CI step names. |
+
+**Procedure:**
+
+```bash
+# 1. Read settings — silently fall back to defaults on parse failure.
+relaxed_enabled=$(cat .sequant/settings.json 2>/dev/null \
+  | grep -o '"markdownOnlyCiRelaxed"[[:space:]]*:[[:space:]]*\(true\|false\)' \
+  | grep -o 'true\|false' || echo "true")
+
+# 2. Compute changed-file list against origin/main.
+changed_files=$(git diff origin/main...HEAD --name-only || true)
+
+# 3. Run the helpers (single npx call returns the gating-pending bucket).
+result=$(SEQUANT_QA_RELAX_FILES="$changed_files" SEQUANT_QA_RELAX_PENDING="$pending_check_names" \
+  npx tsx -e '
+    (async () => {
+      const m = await import("./src/lib/qa/markdown-only-ci.ts");
+      const { getSettings } = await import("./src/lib/settings.ts");
+      const files = (process.env.SEQUANT_QA_RELAX_FILES || "").split("\n").filter(Boolean);
+      const pending = (process.env.SEQUANT_QA_RELAX_PENDING || "").split("\n").filter(Boolean);
+      const settings = await getSettings();
+      const isMdOnly = m.detectMarkdownOnlyDiff(files);
+      const enabled = settings.qa.markdownOnlyCiRelaxed && isMdOnly;
+      const buckets = enabled
+        ? m.filterRelaxablePending(pending, settings.qa.markdownOnlySafeCiPatterns)
+        : { relaxed: [], gating: pending };
+      console.log(JSON.stringify({ isMdOnly, enabled, ...buckets }));
+    })();
+  ' 2>/dev/null || echo '{"isMdOnly":false,"enabled":false,"relaxed":[],"gating":[]}')
+```
+
+When `enabled === true` (markdown-only diff AND `markdownOnlyCiRelaxed` is `true`), use `gating` for the verdict's `pending_count`; the `relaxed` list is informational and rendered in the output.
+
+**Output transparency (REQUIRED when relaxation triggers):**
+
+When `enabled === true` AND `relaxed.length > 0`, the `### CI Status` section MUST include this labeled note immediately after the CI summary line, listing the relaxed check names verbatim:
+
+```markdown
+**Markdown-only diff detected — pending build-matrix checks treated as informational. Relaxed: build (20.x), build (22.x), Plugin Structure Validation.**
+```
+
+If `enabled === false` (flag off, or diff includes non-markdown files), do not emit the note — render the CI Status section unchanged.
 
 ---
 
@@ -838,6 +1073,12 @@ issue_type="${SEQUANT_ISSUE_TYPE:-}"
 admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head -1 || true)
 ```
 
+**Add skill sync check if skill files modified:**
+```bash
+skill_modified=$(git diff main...HEAD --name-only | grep -E "^\.(claude/skills|skills|templates/skills)/" | head -1 || true)
+```
+If skill files are modified, the quality-checks.sh script automatically runs the three-directory sync check (section 12). If divergence is detected, this blocks `READY_FOR_MERGE` — verdict becomes `AC_MET_BUT_NOT_A_PLUS` with a note to run `npx tsx scripts/check-skill-sync.ts --fix`.
+
 See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
 
 ### Using MCP Tools (Optional)
@@ -1356,10 +1597,11 @@ Before any READY_FOR_MERGE verdict, complete the adversarial thinking checklist:
 2. **"What assumptions am I making?"** - List and validate key assumptions
 3. **"What's the unhappy path?"** - Test invalid inputs, failed dependencies
 4. **"Did I test the feature's PRIMARY PURPOSE?"** - If it handles errors, trigger an error
+5. **"Does the same root-cause pattern exist at sibling sites in this file?"** - The literal repro from the issue body is necessary but not sufficient. After the cited bug is fixed, audit other call sites in the same file (and same function/loop) that share the root-cause pattern. Example: if a destructive operation invalidates a resource that subsequent code depends on, scan for other destructive operations on that resource type in the same function/loop; if a wrong null-check is the bug, scan for the same access pattern elsewhere. **Complementary to Section 5's cross-file sibling-site scan: §4's question is intra-file (other lines/functions in the same file with the same root cause); §5 is cross-file (other files in the codebase with the same vulnerability).**
 
 See [testing-requirements.md](references/testing-requirements.md) for edge case checklists.
 
-### 5. Risk Assessment (REQUIRED unless SMALL_DIFF)
+### 5. Risk Assessment (REQUIRED)
 
 **Before issuing your verdict**, state the implementation risks in 2-3 sentences.
 
@@ -1370,10 +1612,22 @@ See [testing-requirements.md](references/testing-requirements.md) for edge case
 
 - **Likely failure mode:** [How would this break in production? Be specific.]
 - **Not tested:** [What gaps exist in test coverage for these changes?]
+- **Sibling sites considered:** [List sibling code in other files in the codebase with the same root cause, or "none — no cross-file siblings" / "N/A — cross-file sibling-site scan does not apply"]
+- **Sibling-line audit:** [Adjacent call sites in the same file/function audited with the same root-cause pattern, OR "none — single-call-site fix"]
 ```
 
 **If either field reveals significant concerns**, factor them into your verdict. A serious failure mode with no test coverage should downgrade to `AC_MET_BUT_NOT_A_PLUS` or `AC_NOT_MET`.
 
+#### Sibling-site Scan (Conditional)
+
+**When to apply:** Focused AC + a localized fix where the same root-cause pattern likely exists in other files in the codebase (≥3 occurrences of the affected pattern across files — e.g. regex blocks repeated across multiple hook scripts). Intra-file sibling sites are covered by §4 Q5; this scan is the cross-file complement.
+
+**Before declaring AC met**, scan other files in the codebase for sibling code with the same pattern as the bug being fixed. If sibling sites would exhibit the same root cause but weren't part of the literal AC, surface them in the verdict's `Sibling sites considered:` slot — as expanded scope (only when trivial) or follow-up issue suggestion. **Don't widen scope mid-PR; file a follow-up issue instead.** Sibling sites alone do not produce `NEEDS_VERIFICATION`; that verdict is reserved for external/temporal gates (CI pending, manual-test ACs unexecuted).
+
+**Scope:** orchestrator/inline-review only — `sequant-qa-checker` sub-agents are not asked to do this scan; the orchestrator owns it during verdict synthesis.
+
+This operationalizes the principle in `feedback_qa_second_look.md` (structured QA biases positive on clean code; an adversarial re-read of core logic surfaces real gaps). Don't automate via grep — false-positive risk; this is a "look at adjacent files" prompt.
+
 #### Skill Change Review (Conditional)
 
 **When to apply:** `.claude/skills/**/*.md` files were modified.
@@ -1623,6 +1877,293 @@ fi
 
 ---
 
+### 6c. Detection Pattern Verification (REQUIRED for skill regex/grep/awk/jq/sed changes)
+
+**HARD PRECONDITION (REQUIRED — emit nothing when false):**
+
+```bash
+# Skill markdown files whose DIFF HUNKS (added lines) contain
+# regex/grep/awk/jq/sed literals. Grepping diff hunks rather than current
+# file content is load-bearing: all 19 sequant SKILL.md files mention these
+# tokens in unrelated example code, so a content-grep gate fires for ~100%
+# of skill-md PRs and the cost-saving intent of #608 / #609 evaporates.
+pattern_files=$(git diff origin/main...HEAD --name-only | \
+  grep -E '^(\.claude/skills|templates/skills|skills)/.*\.md$' | \
+  while read -r f; do
+    if git diff origin/main...HEAD -- "$f" | grep -E '^\+[^+]' | \
+       grep -qE '\b(grep|awk|jq|sed)\b|/[^/]+/[gim]?'; then
+      echo "$f"
+    fi
+  done || true)
+```
+
+If `pattern_files` is empty, **omit the entire §6c block — including its output template row — from the QA comment.** Do NOT emit "Not Required." Per the #608 signal-to-noise study, every one of §6c's 11 prior emissions said exactly "N/A — no skill regex/grep/awk changes" and produced zero substantive findings. The header recitation itself is the cost (~1,800 tokens / invoke). When the precondition is false, treat §6c as not loaded for this run.
+
+**When precondition is TRUE:** continue with Steps 1–5 below.
+
+**When to apply:** Diff modifies skill markdown files (`.claude/skills/**/*.md`, `templates/skills/**/*.md`, `skills/**/*.md`) AND adds or modifies regex literals or `grep`/`awk`/`jq`/`sed` commands inside those files.
+
+**Purpose:** Prompt-only skill changes (regex/grep/awk/jq inside `SKILL.md`) have **no automated test coverage**. Section 6a (Skill Command Verification) checks command syntax — whether `gh pr checks --json conclusion` is a valid field — but does NOT check whether `awk '/^### AC-[0-9]+/'` actually matches real spec headers. A pattern that is syntactically valid but matches the wrong corpus produces a **silent detection failure** — the worst kind of bug, because the pipeline reports success.
+
+**Origin (PR #547 / issue #529):** Three such bugs shipped in a single PR before adversarial review surfaced them:
+
+1. `jq 'select(contains("SEQUANT_PHASE") and contains("spec"))'` matched 5 unrelated comments and returned a QA comment as "the spec plan"
+2. `awk '/^### AC-[0-9]+/'` only matched 3-hash headers, missing `#### AC-N` and `**AC-N:**` (~45% of sampled past specs)
+3. The grep regex omitted `**Verify:**` as a prefix — even though the issue body's verbatim motivating example used that exact prefix
+
+Each was a 30-second diagnostic once piped through real corpus. None showed up in static review of the diff against AC text because every pattern was syntactically valid and matched the AC description in the abstract.
+
+#### Step 1: Detect Pattern Changes
+
+```bash
+# Skill markdown files modified in this PR
+skill_md_changed=$(git diff origin/main...HEAD --name-only | \
+  grep -E '^(\.claude/skills|templates/skills|skills)/.*\.md$' || true)
+
+# Among those, ADDED lines that introduce a grep/awk/jq/sed command or a regex literal
+pattern_changes=""
+for f in $skill_md_changed; do
+  added=$(git diff origin/main...HEAD -- "$f" | \
+    awk '/^\+[^+]/ { print substr($0, 2) }' | \
+    grep -E '(\b(grep|awk|jq|sed) [-\x27"]|/\^[^/]+/|\(\?[:=!]|\\b[A-Za-z]+\\b)' || true)
+  if [[ -n "$added" ]]; then
+    pattern_changes="${pattern_changes}\n=== $f ===\n${added}"
+  fi
+done
+
+if [[ -z "$pattern_changes" ]]; then
+  echo "No pattern changes detected — verification not required"
+  # Set detection_pattern_status = "Not Required"
+fi
+```
+
+**Manual review fallback:** Heuristic regex misses some pattern shapes — bare `grep "pattern"` with no flag, multi-line `awk` blocks, complex `sed` programs, regex literals embedded in JSON examples, non-anchored character classes (`[A-Z]+`, `(\d+)`). Even when the script reports zero matches, scan the diff for pattern-shaped additions if any of `grep`/`awk`/`jq`/`sed`/`regex`/`pattern` appear in the diff text.
+
+#### Step 2: Identify Intended Corpus per Pattern
+
+For each modified pattern, determine WHERE it is supposed to match. Use the surrounding skill prose (section title, preceding paragraph, the bash variable name) to infer the corpus:
+
+| Pattern Context | Corpus Source | How to Sample |
+|-----------------|---------------|---------------|
+| Spec plan parsing | Past `/spec` comments on GitHub issues | `gh api 'repos/{owner}/{repo}/issues/comments?per_page=100' --paginate -q '.[] \| select(.body \| contains("SEQUANT_PHASE: spec")) \| .body'` |
+| Assess action parsing | Past `/assess` comments | `gh api 'repos/{owner}/{repo}/issues/comments?per_page=100' --paginate -q '.[] \| select(.body \| contains("assess:action=")) \| .body'` |
+| QA verdict parsing | Past `/qa` review comments | `gh api 'repos/{owner}/{repo}/issues/comments?per_page=100' --paginate -q '.[] \| select(.body \| startswith("## /qa Review")) \| .body'` |
+| Issue body extraction | Real issue bodies | `gh issue view <N> --json body` for ≥5 representative issues |
+| AC checkbox detection | Issue/PR bodies with `- [ ] AC-N` | Sample ≥5 issues from current milestone |
+| Skill markdown | This repo's own `.claude/skills/**/*.md` | Local files (no API call needed) |
+| Generic markdown | Repo `*.md` fixtures, `docs/`, examples | Local files |
+
+**Why `gh api` over `gh search issues`:** `gh search` relies on GitHub's full-text search index, which does not reliably cover HTML-comment markers (`<!-- SEQUANT_PHASE: spec -->`) buried in comment bodies. Query strings containing `:` (e.g. `assess:action`) are also parsed as search qualifiers and return empty. `gh api` returns raw JSON that local `jq` filters can match deterministically against the actual marker text.
+
+If a pattern's corpus cannot be identified from surrounding prose, that itself is a finding — the skill author needs to document where the pattern is meant to match before it ships.
+
+#### Step 3: Execute Pattern Against ≥5 Real Samples
+
+For each detected pattern, sample at least 5 real instances from the identified corpus and run the pattern. Record actual matches vs. AC-claimed expected matches.
+
+```bash
+# Example: verifying a new awk header regex against past /spec comments.
+# Fetch comment bodies via gh api (full-text search of HTML markers is unreliable).
+spec_bodies=$(gh api 'repos/{owner}/{repo}/issues/comments?per_page=100' --paginate \
+  -q '.[] | select(.body | contains("SEQUANT_PHASE: spec")) | .body' || true)
+sample_count=0
+while IFS= read -r body; do
+  [[ -z "$body" ]] && continue
+  matches=$(echo "$body" | awk '/^### AC-[0-9]+/' | wc -l | xargs)
+  expected_at_least=1   # AC says pattern should match ≥1 AC header per spec
+  status="Passed"
+  [[ "$matches" -lt "$expected_at_least" ]] && status="Failed"
+  sample_count=$((sample_count + 1))
+  echo "sample $sample_count: matched=$matches expected≥$expected_at_least → $status"
+done <<< "$spec_bodies"
+if [[ "$sample_count" -lt 5 ]]; then
+  echo "⚠ Only $sample_count samples available — set detection_pattern_status='Insufficient Samples'"
+fi
+```
+
+**Output table (REQUIRED):**
+
+| Pattern | Corpus | Samples | Expected | Actual | Status |
+|---------|--------|---------|----------|--------|--------|
+| `awk '/^### AC-[0-9]+/'` | past `/spec` comments | 5 | ≥1 match per | 3/5 had 0 matches | ❌ Failed |
+| `jq 'select(contains("SEQUANT_PHASE"))'` | issue comments | 5 | exactly 1 spec comment | returned 5 | ❌ Failed |
+
+#### Step 4: Motivating-Example Fixture Verification (REQUIRED)
+
+Snippets quoted in the **issue body** as motivating examples or AC verification targets are **mandatory test fixtures**. The new pattern MUST produce the AC-claimed result on each. This is belt-and-suspenders to Step 3 — Step 3 catches general corpus drift; Step 4 catches the specific case the AC was written to address.
+
+**What counts as a motivating-example fixture:**
+
+- Blockquoted text (lines starting with `>`)
+- Fenced code blocks (` ``` `) under non-Setup/non-Install headings
+- Lines prefixed with `**Verify:**`, `**Verbatim:**`, `**Example:**`, `**AC verification:**`
+- Verbatim spec excerpts referenced in the AC text (e.g. "the issue body's verbatim motivating example used that exact prefix")
+
+**What is excluded:**
+
+- Code blocks under headings named `## Setup`, `## Install`, `## Prerequisites`, `## How to install` (these are environment commands, not fixtures)
+- Generic shell session transcripts unrelated to the pattern under test
+
+**Extraction:**
+
+Prefer the Phase 0c precheck output when available — fixture extraction is
+deterministic and #609 moved it out of the QA prompt:
+
+```bash
+precheck=".sequant/gap-precheck.json"
+if [[ -f "$precheck" ]] && [[ "$(jq -r .schemaVersion "$precheck" 2>/dev/null)" == "1" ]]; then
+  jq -r '.checks.fixtures.fixtures[] | "[\(.kind)\(if .label then ":" + .label else "" end) line \(.line)] \(.content)"' "$precheck"
+else
+  # Inline fallback (pre-#609 behavior)
+  issue_body=$(gh issue view <issue-number> --json body -q '.body')
+  echo "$issue_body" | grep -E '^>' || true
+  echo "$issue_body" | awk '
+    /^## (Setup|Install|Prerequisites|How to install)/ { skip=1; next }
+    /^## / && skip { skip=0 }
+    /^```/ { in_block=!in_block; next }
+    in_block && !skip { print }
+  '
+  echo "$issue_body" | grep -E '\*\*(Verify|Verbatim|Example|AC verification|Repro):\*\*' || true
+fi
+```
+
+**Run the new pattern against each extracted fixture.** For every fixture the AC says should match, the pattern MUST produce a match. **A 0-match result on a verbatim AC fixture is automatically `Failed`.**
+
+#### Step 5: Detection Pattern Verification Status
+
+| Status | Meaning |
+|--------|---------|
+| **Passed** | All patterns matched their corpora at the AC-claimed rate (≥5 samples each); all motivating-example fixtures matched |
+| **Failed** | At least one pattern produced 0 matches against input the AC says should match (corpus or fixture) |
+| **Insufficient Samples** | Corpus exists but fewer than 5 representative instances were available; reviewer must record the actual count |
+| **Skipped** | Patterns identified but corpus fully unavailable (e.g. `gh` offline / unauth / rate-limited); document the specific reason |
+| **Not Required** | No pattern changes in skill markdown |
+
+**CORPUS-UNAVAILABLE RULE:** If `gh` is unauthenticated, offline, or rate-limited, mark `Skipped` with the specific reason. Do **NOT** silently mark `Passed`.
+
+**SPARSE-CORPUS RULE:** If corpus is reachable but fewer than 5 samples are found (and all matched), mark `Insufficient Samples` with the actual count. Do **NOT** silently mark `Passed` — AC-2 requires ≥5 samples.
+
+#### Verdict Gating (STRICTER than Section 6a)
+
+| Verification Status | Maximum Verdict |
+|---------------------|-----------------|
+| Passed | READY_FOR_MERGE |
+| Insufficient Samples | AC_MET_BUT_NOT_A_PLUS (sparse corpus — record actual count) |
+| Skipped | AC_MET_BUT_NOT_A_PLUS (note unverified corpus) |
+| **Failed** | **`AC_NOT_MET`** (silent detection failures are worse than wrong CLI flags — block merge) |
+| Not Required | READY_FOR_MERGE |
+
+**Rationale for stricter gate vs Section 6a:** Section 6a catches CLI commands that error out at runtime (loud failures). Detection patterns silently match the wrong thing (quiet failures the pipeline reports as success). The 3 bugs in PR #547 all passed Section 6a-style review and only surfaced when patterns were piped through real input.
+
+**Output Format:**
+
+```markdown
+### Detection Pattern Verification
+
+**Skill markdown files with pattern changes:** N
+
+| Pattern | Corpus | Samples | Expected | Actual | Status |
+|---------|--------|---------|----------|--------|--------|
+| `awk '/^### AC-[0-9]+/'` | past `/spec` comments | 5 | ≥1 per | 3/5 = 0 | ❌ Failed |
+| `grep -E '\*\*Verify:\*\*'` | issue #551 body | 1 (verbatim fixture) | matched | matched | ✅ Passed |
+
+**Motivating-example fixtures from issue body:** M (all run against the new pattern)
+
+**Verification Status:** Failed (1 pattern misses ~45% of corpus)
+```
+
+---
+
+### 6d. Adversarial Re-Read (REQUIRED for Standard QA before READY_FOR_MERGE)
+
+**Purpose:** Catch what the structured pipeline doesn't gate on. Operationalizes `feedback_qa_second_look.md` — structured QA biases positive on clean code; an adversarial re-read of core logic surfaces real gaps.
+
+**When to apply:** Required for non-Simple-Fix verdicts before issuing `READY_FOR_MERGE`. Omitted entirely for Simple Fix mode (`SMALL_DIFF=true`).
+
+**How to perform:** Before declaring READY_FOR_MERGE, walk through the diff once more adversarially and surface anything the structured pipeline didn't gate on. In particular: (1) run the implementation against every verbatim motivating-example fixture from the issue body — Phase 0c precheck surfaces these in `.checks.fixtures.fixtures`; if precheck unavailable, extract inline per `feedback_motivating_example_regression.md`; (2) flag any "evidence" claim that is actually a pre-fix bug repro rather than a post-fix validation; (3) inspect process state the pipeline normalizes away (uncommitted work, divergent branches, stashed changes, orchestrator state); (4) cite sibling sites explicitly — §5 (cross-file) and §4 Q5 (intra-file); do not hand-wave with "N/A"; (5) surface any Non-Goals from the issue body that have silently expanded into scope. A bare "No gaps" without specific reasoning fails output verification — name what you scanned, ran, or traced.
+
+**Status outcomes:** **Clean** = walked the 5 checks above, surfaced no gaps. **Gaps Found** = surfaced gaps that map to recommendations or follow-up issues but no missing AC fixture. **Severe Gap** = surfaced (a) a verbatim motivating-example fixture not run, OR (b) an evidence claim that's actually a bug repro not a validation, OR (c) an AC marked MET on code review alone without the runtime / corpus check the AC's text required.
+
+**Verdict gating:**
+
+| Status | Maximum Verdict |
+|--------|-----------------|
+| Clean | READY_FOR_MERGE |
+| Gaps Found | AC_MET_BUT_NOT_A_PLUS |
+| Severe Gap | AC_NOT_MET |
+
+**Output Format:**
+
+```markdown
+### Adversarial Re-Read
+
+**Findings:** [Concrete enumeration of gaps surfaced, OR "No gaps found because: <specific reason citing what was scanned/run/traced — fixtures consulted, evidence claims audited, process state inspected, sibling sites cited, Non-Goals checked>"]
+
+**Status:** Clean / Gaps Found / Severe Gap
+```
+
+**Origin:** This section was promoted to a structured 5-sub-prompt table in #582. #608's signal-to-noise study found 9/14 emits surfaced findings but 0 were actioned — the structure produced visibility without action. #609 trims back to a single-paragraph prompt while preserving the safety net and verdict gating.
+
+### 6e. Behavior-Rule Survival Check (REQUIRED for behavior-rule ACs)
+
+**Purpose:** When an AC asserts a behavior rule (e.g. "default becomes X", "always include Y", "never skip Z"), verify the OLD-rule's implementation has been removed from every touchpoint inside the diff blast radius. Catches the #533-class miss where the SKILL.md was updated but the runtime CLI's short-circuit (`BUG_LABELS`/`DOCS_LABELS`) survived. See [behavior-rule-detection.md](../_shared/references/behavior-rule-detection.md).
+
+**When to apply:** Run on every AC for which the behavior-rule heuristic triggers (>= 2 distinct keywords from `default | always | never | rule | behavior | skip` OR explicit pattern like `always X unless Y`). Skip entirely when no AC triggers across the issue (cheap short-circuit per the reference doc's Performance budget).
+
+**How to perform:**
+
+```bash
+# Per-AC survival check. Run once per behavior-rule AC.
+QA_AC_ID="AC-1" \
+QA_AC_TEXT="<verbatim AC description>" \
+QA_DIFF_PATHS="$(git diff main...HEAD --name-only | tr '\n' '|')" \
+npx tsx -e '
+(async () => {
+  const m = await import("./src/lib/heuristics/behavior-rule-detector.ts");
+  const ac = {
+    id: process.env.QA_AC_ID,
+    description: process.env.QA_AC_TEXT,
+    verificationMethod: "manual",
+    status: "pending",
+  };
+  const detection = m.detectBehaviorRule(ac);
+  if (!detection.triggered) { console.log(JSON.stringify({ triggered: false })); return; }
+  const diffPaths = (process.env.QA_DIFF_PATHS || "").split("|").filter(Boolean);
+  const survivors = m.findSurvivingInverseSymbols(ac, process.cwd(), diffPaths);
+  console.log(JSON.stringify({ triggered: true, survivors }));
+})();
+'
+```
+
+**Status outcomes:**
+
+| Status | Criteria |
+|--------|----------|
+| **Clean** | Detector triggered, `survivors` is empty across diff blast radius |
+| **Survivors Found** | One or more inverse symbols / inverse-keyword lines survive in the diff blast radius |
+| **N/A** | No AC triggers the behavior-rule detector (skip section entirely) |
+
+**AC marking and verdict gating:**
+
+- Survival inside the diff blast radius -> the corresponding AC is marked `NOT_MET` with the `path:line` list in the AC explanation (per AC-2 of #552).
+- Survivors -> verdict floors at `AC_NOT_MET` via the §7 algorithm's `behavior_rule_survival_status` gate.
+
+**Output Format:**
+
+```markdown
+### Behavior-Rule Survival Check
+
+| AC | Triggered? | Survivors | Status |
+|----|-----------|-----------|--------|
+| AC-N | Yes | path/to/file.ts:LINE — `<snippet>` | Survivors Found |
+| AC-M | No | — | N/A |
+
+**Status:** Clean / Survivors Found / N/A
+```
+
+---
+
+
 ### 7. A+ Status Verdict
 
 Provide an overall verdict:
@@ -1649,6 +2190,11 @@ Provide an overall verdict:
    - execution_evidence = status from Section 6 (Complete/Incomplete/Waived/Not Required)
    - quality_plan_status = status from Phase 0b (Complete/Partial/Not Addressed/N/A)
    - smoke_test_status = status from Section 6b (Complete/Partial/Not Required)
+   - detection_pattern_status = status from Section 6c (Passed/Failed/Insufficient Samples/Skipped/Not Required)
+   - 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
+   - 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
+   - changelog_missing = true IFF `changelog_required` AND Section 10a's `[Unreleased]` entry check finds no entry for the issue/PR; false otherwise
 
 3. Browser testing enforcement check:
    - Check if any .tsx files were changed: git diff main...HEAD --name-only | grep '\.tsx$' || true
@@ -1657,13 +2203,30 @@ Provide an overall verdict:
    - IF .tsx files changed AND /test did NOT run AND no 'no-browser-test' label:
        → Set browser_test_missing = true
 
+3a. Manual test AC enforcement check:
+   - Scan spec plan comment for ACs with **Verification:** Manual Test (or freeform: try X confirm Y, verify by, test that)
+   - For each detected manual-test AC:
+     - IF runtime test was executed → AC status from test result (MET/NOT_MET)
+     - IF approved override documented → AC status = MET
+     - ELSE → AC status = PENDING (this increments pending_count)
+   - NOTE: No new verdict branch needed — PENDING manual-test ACs flow through
+     the existing pending_count > 0 → NEEDS_VERIFICATION path in step 4
+
 4. Determine verdict (in order):
    - IF not_met_count > 0 OR partial_count > 0:
        → AC_NOT_MET (block merge)
+   - ELSE IF detection_pattern_status == "Failed":
+       → AC_NOT_MET (silent detection failures - block merge; STRICTER than skill_verification because pattern bugs report success but match the wrong corpus)
+   - ELSE IF behavior_rule_survival_status == "Survivors Found":
+       → AC_NOT_MET (OLD-rule symbol survived inside the diff blast radius — see #533 motivating miss in Section 6e and references/behavior-rule-detection.md)
+   - 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 changelog_required AND changelog_missing:
+       → AC_MET_BUT_NOT_A_PLUS (CHANGELOG entry required for user-facing changes - see Section 10a for remediation)
    - ELSE IF quality_plan_status == "Not Addressed" AND quality_plan_exists:
        → AC_MET_BUT_NOT_A_PLUS (quality dimensions not addressed - flag for review)
    - ELSE IF browser_test_missing (from step 3):
@@ -1676,6 +2239,12 @@ Provide an overall verdict:
        → AC_MET_BUT_NOT_A_PLUS (some quality dimensions incomplete - can merge with notes)
    - ELSE IF smoke_test_status == "Partial":
        → AC_MET_BUT_NOT_A_PLUS (smoke tests incomplete - document gaps before merge)
+   - ELSE IF detection_pattern_status == "Insufficient Samples":
+       → AC_MET_BUT_NOT_A_PLUS (sparse corpus - record actual sample count)
+   - ELSE IF detection_pattern_status == "Skipped":
+       → AC_MET_BUT_NOT_A_PLUS (corpus unavailable for pattern verification - document reason)
+   - ELSE IF adversarial_reread_status == "Gaps Found":
+       → AC_MET_BUT_NOT_A_PLUS (adversarial re-read surfaced non-blocking gaps; address as follow-up or improvement suggestions)
    - ELSE IF improvement_suggestions.length > 0:
        → AC_MET_BUT_NOT_A_PLUS (can merge with notes)
    - ELSE:
@@ -1711,10 +2280,111 @@ fi
 | `.tsx` changed + no `/test` + no opt-out | Force `AC_MET_BUT_NOT_A_PLUS` |
 | No `.tsx` changed | Normal verdict |
 
+**Manual Test AC Enforcement:**
+
+Before finalizing the verdict, check if any ACs require manual (runtime) verification that was specified in the `/spec` plan:
+
+```bash
+# 1. Extract spec plan comment from issue
+spec_comment=$(gh issue view <issue-number> --json comments --jq \
+  '[.comments[].body | select(contains("\"phase\":\"spec\""))] | last' || true)
+
+# 2. Detect ACs with manual-test verification methods
+# Matches: "**Verification:** Manual Test", "**Verify:** ...", "try X, confirm Y", "verify by", "test that"
+manual_test_acs=$(echo "$spec_comment" | \
+  grep -iE '(\*\*Verification:\*\*\s*Manual Test|\*\*Verify:\*\*\s*|try .*, confirm|verify by|test that|verify:?\s*manual)' || true)
+
+# 3. Extract AC IDs associated with manual-test lines
+# Scan backwards from each match to find the nearest ### AC-N header
+manual_ac_ids=$(echo "$spec_comment" | \
+  awk 'BEGIN{IGNORECASE=1} /^(#+ AC-[0-9]+|\*\*AC-[0-9]+)/{ac=$0} /Manual Test|\*\*Verify:\*\*|try .*, confirm|verify by|test that/{print ac}' | \
+  grep -oE 'AC-[0-9]+' | sort -u || true)
+```
+
+**If manual-test ACs are detected**, include this section in QA output:
+
+```markdown
+### Manual Test ACs Detected
+
+| AC | Verification Method | Runtime Test Status |
+|----|--------------------|--------------------|
+| AC-N | Manual Test | ✅ Executed / ⚠️ PENDING / 🔄 Overridden |
+```
+
+**Enforcement Rules:**
+
+For each detected manual-test AC, QA must do ONE of:
+
+1. **Execute the test** using available tools (chrome-devtools MCP, dev server, CLI invocation) and record pass/fail evidence → mark AC `MET` or `NOT_MET` based on result
+2. **Mark AC `PENDING`** with note: `⚠️ Manual verification required — runtime test not executed` → flows through `pending_count > 0 → NEEDS_VERIFICATION` verdict path
+3. **Override** with approved justification (see Manual Test Override below) → mark AC `MET`
+
+**Key Rule:** A manual-test AC CANNOT be marked `MET` from static code review alone. QA must either execute the runtime test, provide an approved override, or mark `PENDING`.
+
+| Scenario | AC Status | Verdict Impact |
+|----------|-----------|----------------|
+| Runtime test executed and passed | `MET` | Normal verdict |
+| Runtime test executed and failed | `NOT_MET` | → `AC_NOT_MET` |
+| Runtime test not executed, no override | `PENDING` | → `NEEDS_VERIFICATION` |
+| Override with approved justification | `MET` | Normal verdict |
+| Override with unapproved justification | `PENDING` | → `NEEDS_VERIFICATION` |
+
+### Manual Test Override
+
+In some cases, runtime verification can be safely skipped for manual-test ACs when the verification target has no runtime surface or is covered by equivalent automated tests. **Overrides require explicit justification and risk assessment.**
+
+**Override Format (REQUIRED when skipping manual-test execution):**
+
+```markdown
+### Manual Test Override
+
+**AC:** AC-N
+**Requirement:** Runtime verification for manual-test AC
+**Override:** Yes
+**Justification:** [One of the approved categories below]
+**Risk Assessment:** [None/Low]
+```
+
+**Approved Override Categories:**
+
+| Category | Example | Risk |
+|----------|---------|------|
+| No runtime surface | Pure type definitions, config schema validation | None |
+| Equivalent unit test coverage | Automated test covers the exact same code path the manual test would exercise | Low |
+| Tested in sibling issue | Cross-reference to another issue where the same runtime behavior was verified | Low |
+
+**NOT Approved for Override (always require runtime test):**
+
+| Category | Example | Why |
+|----------|---------|-----|
+| Logic changes with UI surface | Modified form validation, new user flows | Runtime behavior may diverge from code review expectations |
+| New user-facing features | Added pages, new interactions | Must verify actual user experience |
+| Integration points | API calls, database writes, auth flows | Runtime dependencies may behave differently |
+| Error handling with user feedback | Toast messages, error pages, redirects | Presentation layer needs runtime check |
+
+**Risk Assessment Definitions:**
+
+| Level | Meaning | Criteria |
+|-------|---------|----------|
+| **None** | Zero runtime impact | Change has no executable runtime surface (types, config) |
+| **Low** | Negligible runtime impact | Automated tests cover the same path; manual test would be redundant |
+| **Medium** | Possible runtime impact | **Should NOT be overridden** — run the manual test |
+
+**Override Decision Flow:**
+
+1. Check if change matches an approved category → If no, runtime test is required
+2. Assess risk level → If Medium or higher, runtime test is required
+3. Document override using the format above in the QA output
+4. Include override in the GitHub issue comment for audit trail
+
+**CRITICAL:** When in doubt, execute the manual test. Overrides are for clear-cut cases only. The motivation for this gate (issue #529) was a real bug that passed QA because `minRows: 1` appeared correct in code review but did not work at runtime.
+
 **CRITICAL:** `PARTIALLY_MET` is NOT sufficient for merge. It MUST be treated as `NOT_MET` for verdict purposes.
 
 **CRITICAL:** If skill command verification = "Failed", verdict CANNOT be `READY_FOR_MERGE`. This prevents shipping skills with broken commands (like issue #178's `conclusion` field).
 
+**CRITICAL:** If detection pattern verification = "Failed" (Section 6c), verdict MUST be `AC_NOT_MET` — stricter than the skill_verification gate. Silent detection failures (regex/grep/awk/jq matching the wrong corpus while reporting success) are worse than wrong CLI flags because the pipeline reports success.
+
 See [quality-gates.md](references/quality-gates.md) for detailed verdict criteria.
 
 ---
@@ -1779,6 +2449,10 @@ If verdict is `READY_FOR_MERGE` or `AC_MET_BUT_NOT_A_PLUS`:
 
 **Purpose:** Verify user-facing changes have corresponding CHANGELOG entries before `READY_FOR_MERGE`.
 
+**Wired into §7 verdict algorithm:** This gate is enforced via the `changelog_required AND changelog_missing` branch in §7 — when both conditions are true, the verdict is demoted from `READY_FOR_MERGE` to `AC_MET_BUT_NOT_A_PLUS`. The branch is no-op when `CHANGELOG.md` is absent or no user-facing commit prefix is detected.
+
+**Caveat — conventional-commit dependency:** Detection requires conventional-commit prefixes — `feat`, `fix`, `perf`, `refactor`, `docs`, with optional scope (`(...)`) and breaking marker (`!`) — in `git log main..HEAD`. Projects whose commits don't follow this pattern silently skip this gate (failsafe-off). Acceptable for sequant's typical user base; document in your project's contributing guide if you rely on this gate.
+
 **Detection:**
 
 ```bash
@@ -1793,7 +2467,7 @@ unreleased_entries=$(sed -n '/^## \[Unreleased\]/,/^## \[/p' CHANGELOG.md | grep
 
 # Determine if change is user-facing (new features, bug fixes, etc.)
 # Look at commit messages or file changes
-user_facing=$(git log main..HEAD --oneline | grep -iE '^[a-f0-9]+ (feat|fix|perf|refactor|docs):' | wc -l | xargs || true)
+user_facing=$(git log main..HEAD --oneline | grep -iE '^[a-f0-9]+ (feat|fix|perf|refactor|docs)(\([^)]*\))?!?:' | wc -l | xargs || true)
 ```
 
 **Verification Logic:**
@@ -1955,8 +2629,10 @@ When the size gate determined `SMALL_DIFF=true`, use the **simplified output tem
 - Smoke Test
 - CLI Registration Verification
 - Skill Command Verification
+- Detection Pattern Verification
 - Script Verification Override
 - Skill Change Review
+- Adversarial Re-Read
 
 **Required sections for simple fix mode:**
 
@@ -1970,6 +2646,7 @@ When the size gate determined `SMALL_DIFF=true`, use the **simplified output tem
 - [ ] **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
 
 ### Standard QA (Implementation Exists, `SMALL_DIFF=false`)
 
@@ -1989,9 +2666,12 @@ When the size gate determined `SMALL_DIFF=true`, use the **simplified output tem
 - [ ] **Execution Evidence** - Included if scripts/CLI modified (or marked N/A)
 - [ ] **Script Verification Override** - Included if scripts/CLI modified AND /verify was skipped (with justification and risk assessment)
 - [ ] **Skill Command Verification** - Included if `.claude/skills/**/*.md` modified (or marked N/A)
+- [ ] **Detection Pattern Verification** - Included if skill markdown adds new `grep`/`awk`/`jq`/`sed`/regex (or marked N/A)
 - [ ] **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)
 - [ ] **CHANGELOG Verification** - User-facing changes have `[Unreleased]` entry (or marked N/A)
+- [ ] **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
 
@@ -2082,6 +2762,8 @@ When the size gate triggers simple fix mode, use this shorter template:
 
 - **Likely failure mode:** [How would this break in production?]
 - **Not tested:** [What gaps exist in test coverage?]
+- **Sibling sites considered:** [List sibling code in other files in the codebase with the same root cause, or "none — no cross-file siblings" / "N/A — cross-file sibling-site scan does not apply"]
+- **Sibling-line audit:** [Adjacent call sites in the same file/function audited with the same root-cause pattern, OR "none — single-call-site fix"]
 
 ---
 
@@ -2142,6 +2824,20 @@ You MUST include these sections:
 
 ---
 
+### Precheck Findings
+
+[Include if `.sequant/gap-precheck.json` (schemaVersion 1) is present. Otherwise emit one line: "Precheck Findings: unavailable — inline fallback used." and omit the table.]
+
+| Section | Status | Surfaced |
+|---------|--------|----------|
+| Fixtures | pass / not_applicable / fail | [N fixtures, consumed by §6c Step 4 / §6d Q1] |
+| Sibling-grep | pass / not_applicable / fail | [N identifiers, candidate sites surfaced to §5] |
+| AC literal-diff | pass / not_applicable / fail | [IDs missing from PR body, if any] |
+
+**Source:** `.sequant/gap-precheck.json` (schemaVersion 1)
+
+---
+
 ### CI Status
 
 [Include if PR exists, otherwise: "No PR exists yet" or "No CI configured"]
@@ -2324,6 +3020,24 @@ You MUST include these sections:
 
 ---
 
+### Detection Pattern Verification
+
+[Include if skill markdown adds/modifies `grep`/`awk`/`jq`/`sed` commands or regex literals, otherwise: "N/A - No pattern changes in skill markdown"]
+
+**Skill markdown files with pattern changes:** X
+
+| Pattern | Corpus | Samples | Expected | Actual | Status |
+|---------|--------|---------|----------|--------|--------|
+| `[pattern]` | [corpus source] | [N samples] | [AC-claimed result] | [observed] | ✅ Passed / ❌ Failed |
+
+**Motivating-example fixtures from issue body:** Y (run against the new pattern)
+
+**Verification Status:** Passed / Failed / Insufficient Samples / Skipped / Not Required
+
+**Verdict impact (stricter than 6a):** Failed → `AC_NOT_MET` (silent detection failures block merge)
+
+---
+
 ### CLI Registration Verification
 
 [Include if option interfaces or CLI file modified, otherwise: "N/A - No option interface changes"]
@@ -2366,10 +3080,34 @@ You MUST include these sections:
 
 ---
 
+### Manual Test ACs
+
+[Include if spec plan has ACs with **Verification:** Manual Test, otherwise: "N/A - No manual-test ACs detected"]
+
+| AC | Verification Method | Runtime Test Status | Evidence |
+|----|--------------------|--------------------|----------|
+| AC-N | Manual Test | ✅ Executed / ⚠️ PENDING / 🔄 Overridden | [result or override justification] |
+
+**Manual Test Enforcement:** X/Y manual-test ACs verified at runtime
+
+[If any overrides applied, include Manual Test Override block per Section 7]
+
+---
+
 ### Risk Assessment
 
 - **Likely failure mode:** [How would this break in production? Be specific.]
 - **Not tested:** [What gaps exist in test coverage for these changes?]
+- **Sibling sites considered:** [List sibling code in other files in the codebase with the same root cause, or "none — no cross-file siblings" / "N/A — cross-file sibling-site scan does not apply"]
+- **Sibling-line audit:** [Adjacent call sites in the same file/function audited with the same root-cause pattern, OR "none — single-call-site fix"]
+
+---
+
+### Adversarial Re-Read
+
+**Findings:** [Concrete enumeration of gaps surfaced, OR "No gaps found because: <specific reason citing what was scanned/run/traced — fixtures consulted, evidence claims audited, process state inspected, sibling sites cited, Non-Goals checked>"]
+
+**Status:** Clean / Gaps Found / Severe Gap
 
 ---