sequant 2.11.0 → 2.13.0

package/dist/marketplace/external_plugins/sequant/skills/spec/references/recommended-workflow.md

@@ -1,6 +1,17 @@
 # Recommended Workflow Format
 
-This document shows the expected output format for the `## Recommended Workflow` section in `/spec` output. The `parseRecommendedWorkflow()` function parses this format to determine which phases to execute.
+This document shows the expected output format for the `## Recommended Workflow` section in `/spec` output.
+
+## Resolution chain (#921)
+
+`sequant run` resolves phases through an ordered chain, not `parseRecommendedWorkflow()` alone:
+
+1. **`SEQUANT_SPEC` marker** — a structured HTML comment in the posted plan comment, e.g. `<!-- SEQUANT_SPEC: {"phases":["testgen","exec","qa"],"qualityLoop":true} -->`. This is the primary, durable channel — always emit it alongside the prose section below.
+2. **Comment prose** — `parseRecommendedWorkflow()` applied to the plan comment body (same format as this doc).
+3. **Chat text** — the same parser applied to the spec agent's chat output. Nondeterministic: only present if the agent happens to restate the section in chat rather than posting via a body file (#814).
+4. **Label fallback** — `detectPhasesFromLabels()`. Can never produce `testgen` or `security-review`.
+
+The marker's `phases` array excludes `spec` (it already ran) and must name only registered phases — an unknown phase name invalidates the whole marker and falls through to step 2.
 
 ## Format
 
@@ -10,6 +21,8 @@ This document shows the expected output format for the `## Recommended Workflow`
 **Phases:** spec → exec → qa
 **Quality Loop:** disabled
 **Reasoning:** Brief explanation of why this workflow was chosen.
+
+<!-- SEQUANT_SPEC: {"phases":["exec","qa"],"qualityLoop":false} -->
 ```
 
 ## Examples

package/dist/marketplace/external_plugins/sequant/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
 

package/dist/marketplace/external_plugins/sequant/skills/testgen/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   author: sequant
   version: "1.0"
 allowed-tools:
+  - Bash(npx sequant worktree:*)
   - Read
   - Write
   - Edit
@@ -530,17 +531,33 @@ If an AC has verification method "N/A - Trivial", skip test generation and note
 
 ### Step 4: Locate Feature Worktree
 
-If generating file-based tests (Unit Test, Integration Test), find the worktree:
+If generating file-based tests (Unit Test, Integration Test), find the worktree.
 
-```bash
-git worktree list | grep -E "feature.*<issue-number>" || true
-```
+<!-- BEGIN: worktree-standalone-lookup (#899) -->
+
+Resolve it through git, not the filesystem:
 
-Or check:
 ```bash
-ls ../worktrees/feature/<issue-number>-*/
+WORKTREE="$(npx sequant worktree resolve <issue-number>)" || {
+  echo "❌ HALT: no worktree for #<issue-number> in this repository."
+  exit 1
+}
+cd "$WORKTREE"
 ```
 
+`sequant worktree resolve` reads `git worktree list` in the current repository
+— which reports only *this* repo's worktrees — and selects on the **branch**
+git reports, not the directory name.
+
+**Do not glob `../worktrees/feature/<issue-number>-*`, and do not grep
+`git worktree list` for the issue number.** The first matches across sibling
+repositories, which share that directory; the second matches the printed path,
+so it keys on the directory slug — and a slug can drift from its own branch
+after a rename. Because this skill **writes test files**, landing in the wrong
+tree scatters stubs into an unrelated project.
+
+<!-- END: worktree-standalone-lookup (#899) -->
+
 Create test directories if needed:
 ```bash
 mkdir -p __tests__/integration

package/dist/src/commands/doctor.js

@@ -8,7 +8,8 @@ import { GitHubProvider } from "../lib/workflow/platforms/github.js";
 import { fileExists, isExecutable } from "../lib/fs.js";
 import { checkSkillsInstalled } from "../lib/skills-check.js";
 import { getManifest } from "../lib/manifest.js";
-import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, getMcpServersConfig, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
+import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
+import { getPhaseMcpServersConfig } from "../lib/mcp-config.js";
 import { getSettings, DEFAULT_AGENT_SETTINGS } from "../lib/settings.js";
 import { checkVersionThorough, getVersionWarning, resolveCliInvocation, } from "../lib/version-check.js";
 import { areSkillsOutdated } from "./sync.js";
@@ -435,23 +436,24 @@ export async function doctorCommand(options = {}) {
             message: "No optional MCPs configured (Sequant works without them, but they enhance functionality)",
         });
     }
-    // Check: MCP availability for headless mode (sequant run)
-    const mcpServersConfig = getMcpServersConfig();
-    if (mcpServersConfig) {
-        const serverCount = Object.keys(mcpServersConfig).length;
-        checks.push({
-            name: "MCP Servers (headless)",
-            status: "pass",
-            message: `Available for sequant run (${serverCount} server${serverCount !== 1 ? "s" : ""} configured)`,
-        });
-    }
-    else {
-        checks.push({
-            name: "MCP Servers (headless)",
-            status: "warn",
-            message: "Not available for sequant run (no Claude Desktop config found or empty mcpServers)",
-        });
-    }
+    // Check: MCP availability for headless mode (sequant run) (#936)
+    //
+    // Phase agents read the project's .mcp.json + settings.run.mcpAllowlist,
+    // never Claude Desktop config wholesale — see getPhaseMcpServersConfig.
+    // The sequant server is always guaranteed, so this check reports what a
+    // phase will actually receive rather than pass/warn on presence.
+    const phaseServersConfig = getPhaseMcpServersConfig(process.cwd(), {
+        desktopAllowlist: settings.run.mcpAllowlist,
+    });
+    const phaseServerCount = Object.keys(phaseServersConfig).length;
+    const extraServerCount = phaseServerCount - 1; // minus the guaranteed sequant entry
+    checks.push({
+        name: "MCP Servers (headless)",
+        status: "pass",
+        message: extraServerCount > 0
+            ? `Available for sequant run (${phaseServerCount} servers: sequant + ${extraServerCount} from .mcp.json${settings.run.mcpAllowlist?.length ? "/mcpAllowlist" : ""})`
+            : "Available for sequant run (sequant only — add servers to .mcp.json, or settings.run.mcpAllowlist for desktop servers, for more)",
+    });
     // Check: Sequant MCP server health
     try {
         // Verify MCP server can be created (validates SDK availability)

package/dist/src/commands/ready.js

@@ -107,7 +107,9 @@ export async function readyCommand(issueArg, options) {
     const policy = resolvePolicy(options.policy, settings.ready.policy);
     const { maxIterations, tokenBudget, phaseTimeout } = resolveReadyLimits(options, settings);
     const mcp = options.mcp !== false;
-    const phasePolicies = resolvePhasePolicies(options.models, options.efforts, settings.run.phases, getPhaseNames());
+    // #975: pass modelRoles + active driver so `role:` prefixes resolve,
+    // matching the same call in buildExecutionConfig (AC-5 drift guard).
+    const phasePolicies = resolvePhasePolicies(options.models, options.efforts, settings.run.phases, getPhaseNames(), settings.run.modelRoles, settings.run.agent ?? "claude-code");
     // #915: CLI > settings > default `false`, same precedence as the `run`
     // path's `buildExecutionConfig` (config-resolver.ts).
     const effortEscalation = options.escalateEffort ?? settings.run.effortEscalation ?? false;
@@ -200,11 +202,15 @@ export async function readyCommand(issueArg, options) {
             nonGoals,
             phaseTimeout,
             mcp,
+            mcpAllowlist: settings.run.mcpAllowlist,
             verbose: options.verbose,
             runPhase,
             onProgress,
             phasePolicies,
             effortEscalation,
+            // #937 AC-4: persist the final gap report so it survives the terminal
+            // closing (previously terminal-scrollback only under `ac` policy).
+            postReport: (body) => gh.postComment(String(issueNumber), body),
         });
     }
     catch (error) {

package/dist/src/commands/status.js

@@ -69,6 +69,8 @@ function colorStatus(status, resolvedAt) {
             return chalk.yellow(status);
         case "waiting_for_human_merge":
             return chalk.green(status);
+        case "awaiting_verification":
+            return chalk.magenta(status);
         case "ready_for_merge":
             return chalk.green(status);
         case "merged":
@@ -171,6 +173,7 @@ function displayIssueSummary(issues) {
         in_progress: [],
         waiting_for_qa_gate: [],
         waiting_for_human_merge: [],
+        awaiting_verification: [],
         ready_for_merge: [],
         blocked: [],
         not_started: [],
@@ -184,6 +187,7 @@ function displayIssueSummary(issues) {
     const statusOrder = [
         "in_progress",
         "waiting_for_qa_gate",
+        "awaiting_verification",
         "waiting_for_human_merge",
         "ready_for_merge",
         "blocked",

package/dist/src/lib/ac-linter.js

@@ -272,6 +272,29 @@ function detectTitleBodyTension(ac) {
         suggestion: "Two verification bars detected. Either (a) tighten the title to match the runtime body (e.g., 'Smoke test execution — capture evidence'), or (b) split the runtime requirement into a separate AC.",
     };
 }
+/**
+ * Detect a test-type AC (unit/integration/browser) whose verification
+ * method came from keyword inference rather than a declared `Evidence:`
+ * clause (#938). `manual` ACs are exempt — docs/decision ACs legitimately
+ * have no runnable evidence.
+ *
+ * Warning-only, same convention as the regex-based DEFAULT_LINT_PATTERNS.
+ *
+ * @param ac - The acceptance criterion to check
+ * @returns A lint issue if evidence is missing, otherwise null
+ */
+function detectMissingEvidence(ac) {
+    if (ac.evidence)
+        return null;
+    if (ac.verificationMethod === "manual")
+        return null;
+    return {
+        type: "incomplete",
+        matchedPattern: ac.verificationMethod,
+        problem: `Incomplete: verification not named — method "${ac.verificationMethod}" was inferred from keywords, not declared`,
+        suggestion: "Add a trailing `Evidence:` clause naming the command or check that verifies this AC (e.g., `Evidence: \\`npm test -- foo\\``).",
+    };
+}
 /**
  * Lint a single acceptance criterion against all patterns
  *
@@ -296,6 +319,9 @@ export function lintAcceptanceCriterion(ac, patterns = DEFAULT_LINT_PATTERNS) {
     const tension = detectTitleBodyTension(ac);
     if (tension)
         issues.push(tension);
+    const missingEvidence = detectMissingEvidence(ac);
+    if (missingEvidence)
+        issues.push(missingEvidence);
     return {
         ac,
         issues,

package/dist/src/lib/ac-parser.d.ts

@@ -30,6 +30,20 @@
  * ```
  */
 import { type AcceptanceCriterion, type AcceptanceCriteria, type ACVerificationMethod } from "./workflow/state-schema.js";
+/**
+ * Build a word-boundary-anchored, case-insensitive matcher for a keyword.
+ * `\b` sits correctly around spaces and hyphens too, so this is safe for
+ * both single words ("ui") and phrases ("end-to-end", "unit test") — a
+ * phrase already reads as self-anchoring under plain substring matching,
+ * and anchoring it doesn't change that (#946).
+ *
+ * @param allowPlural - Also match a trailing "s" (e.g. `flag` -> `flags`).
+ *   Only meaningful for single nouns/verbs that commonly appear inflected
+ *   in prose; multi-word phrases never need it.
+ *
+ * @internal Exported for testing only — not part of the module's public API.
+ */
+export declare function keywordMatcher(keyword: string, allowPlural?: boolean): RegExp;
 /**
  * Infer verification method from description text
  *
@@ -37,6 +51,32 @@ import { type AcceptanceCriterion, type AcceptanceCriteria, type ACVerificationM
  * @returns The inferred verification method (defaults to 'manual')
  */
 export declare function inferVerificationMethod(description: string): ACVerificationMethod;
+/**
+ * Resolve the verification method for an AC, preferring a declared
+ * `Evidence:` clause over keyword inference (#938).
+ *
+ * - Evidence names a backtick-quoted command containing a unit-test
+ *   token (`test`, `vitest`, `jest`) → `unit_test`.
+ * - Evidence names any other backtick-quoted command → `integration_test`.
+ * - Evidence is prose with no backtick command (e.g. "human review") →
+ *   `manual`.
+ * - No evidence declared → falls back to {@link inferVerificationMethod}.
+ *
+ * @param description - The AC description text (evidence clause stripped)
+ * @param evidence - The declared evidence clause, if any
+ * @returns The resolved verification method
+ */
+export declare function resolveVerificationMethod(description: string, evidence?: string): ACVerificationMethod;
+/**
+ * Whether a declared `Evidence:` clause describes a CLAUDE.md-style gate
+ * test — a fixture-exists / section-present / flag-wired assertion — rather
+ * than an ordinary behavioral unit/integration test or a human sign-off.
+ *
+ * @param evidence - The declared evidence clause text (from {@link splitEvidenceClause})
+ * @returns True when the evidence text matches the gate-test keyword set and
+ *   does not read as a manual-review attestation
+ */
+export declare function isGateTestEvidence(evidence: string): boolean;
 /**
  * Parse acceptance criteria from GitHub issue markdown
  *

package/dist/src/lib/ac-parser.js

@@ -30,6 +30,7 @@
  * ```
  */
 import { createAcceptanceCriterion, createAcceptanceCriteria, } from "./workflow/state-schema.js";
+import { computeFenceMask } from "./markdown-fence.js";
 /**
  * Regex patterns for AC extraction
  *
@@ -115,6 +116,39 @@ const VERIFICATION_KEYWORDS = {
     "manual test": "manual",
     verify: "manual",
 };
+/**
+ * Escape regex metacharacters in a literal keyword before embedding it in a
+ * constructed RegExp.
+ */
+function escapeRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Build a word-boundary-anchored, case-insensitive matcher for a keyword.
+ * `\b` sits correctly around spaces and hyphens too, so this is safe for
+ * both single words ("ui") and phrases ("end-to-end", "unit test") — a
+ * phrase already reads as self-anchoring under plain substring matching,
+ * and anchoring it doesn't change that (#946).
+ *
+ * @param allowPlural - Also match a trailing "s" (e.g. `flag` -> `flags`).
+ *   Only meaningful for single nouns/verbs that commonly appear inflected
+ *   in prose; multi-word phrases never need it.
+ *
+ * @internal Exported for testing only — not part of the module's public API.
+ */
+export function keywordMatcher(keyword, allowPlural = false) {
+    const escaped = escapeRegExp(keyword);
+    const pattern = allowPlural ? `\\b${escaped}s?\\b` : `\\b${escaped}\\b`;
+    return new RegExp(pattern, "i");
+}
+/**
+ * Precompiled, longest-keyword-first matchers for {@link VERIFICATION_KEYWORDS}.
+ * Longest-first preserves the original precedence (e.g. "unit test" wins
+ * over a lone "unit").
+ */
+const VERIFICATION_KEYWORD_MATCHERS = Object.entries(VERIFICATION_KEYWORDS)
+    .sort((a, b) => b[0].length - a[0].length)
+    .map(([keyword, method]) => ({ regex: keywordMatcher(keyword), method }));
 /**
  * Infer verification method from description text
  *
@@ -122,16 +156,156 @@ const VERIFICATION_KEYWORDS = {
  * @returns The inferred verification method (defaults to 'manual')
  */
 export function inferVerificationMethod(description) {
-    const lowerDesc = description.toLowerCase();
-    // Check for explicit keywords (longer phrases first)
-    const sortedKeywords = Object.keys(VERIFICATION_KEYWORDS).sort((a, b) => b.length - a.length);
-    for (const keyword of sortedKeywords) {
-        if (lowerDesc.includes(keyword)) {
-            return VERIFICATION_KEYWORDS[keyword];
+    for (const { regex, method } of VERIFICATION_KEYWORD_MATCHERS) {
+        if (regex.test(description)) {
+            return method;
         }
     }
     return "manual";
 }
+/**
+ * Matches a trailing `Evidence:` clause on an AC line (#938). Only the
+ * LAST occurrence is honored — the clause is defined as trailing, and AC
+ * prose can legitimately contain the word "Evidence:" earlier in the
+ * sentence (e.g. "the report cites strong Evidence: peer review ..."
+ * before the real declaration). Splitting on the first match would corrupt
+ * extraction by swallowing the real trailing clause into the description.
+ */
+const EVIDENCE_CLAUSE_RE = /\bEvidence:\s*/gi;
+/**
+ * Split a trailing `Evidence:` clause out of an AC description (#938).
+ *
+ * @param description - The AC description text (post ID-stripping)
+ * @returns The description with the clause removed, plus the declared
+ *   evidence text if present
+ */
+function splitEvidenceClause(description) {
+    const matches = [...description.matchAll(EVIDENCE_CLAUSE_RE)];
+    if (matches.length === 0)
+        return { description };
+    const last = matches[matches.length - 1];
+    const before = description.slice(0, last.index).trim();
+    const evidence = description.slice(last.index + last[0].length).trim();
+    if (!before || !evidence)
+        return { description };
+    return { description: before, evidence };
+}
+/**
+ * Matches a backtick-quoted command inside a declared evidence clause.
+ * A command (vs. prose like "human review") is what makes evidence
+ * runnable/checkable rather than a manual attestation.
+ */
+const EVIDENCE_COMMAND_RE = /`([^`]+)`/;
+/**
+ * Command tokens that indicate a unit-test invocation. Anything else
+ * backtick-quoted (CLI commands, curl, scripts) is treated as an
+ * integration-level check.
+ */
+const UNIT_TEST_COMMAND_RE = /\b(test|vitest|jest)\b/i;
+/**
+ * Resolve the verification method for an AC, preferring a declared
+ * `Evidence:` clause over keyword inference (#938).
+ *
+ * - Evidence names a backtick-quoted command containing a unit-test
+ *   token (`test`, `vitest`, `jest`) → `unit_test`.
+ * - Evidence names any other backtick-quoted command → `integration_test`.
+ * - Evidence is prose with no backtick command (e.g. "human review") →
+ *   `manual`.
+ * - No evidence declared → falls back to {@link inferVerificationMethod}.
+ *
+ * @param description - The AC description text (evidence clause stripped)
+ * @param evidence - The declared evidence clause, if any
+ * @returns The resolved verification method
+ */
+export function resolveVerificationMethod(description, evidence) {
+    if (evidence) {
+        const commandMatch = EVIDENCE_COMMAND_RE.exec(evidence);
+        if (commandMatch) {
+            return UNIT_TEST_COMMAND_RE.test(commandMatch[1])
+                ? "unit_test"
+                : "integration_test";
+        }
+        return "manual";
+    }
+    return inferVerificationMethod(description);
+}
+/**
+ * Keywords matching the CLAUDE.md "gate test" definition — a test whose job
+ * is to gate a claim that "a fixture exists, a skill section is present, a
+ * flag is wired" (#830, #939). Distinct from {@link VERIFICATION_KEYWORDS}:
+ * those classify *how* an AC is checked (unit/integration/browser/manual),
+ * this classifies *what kind of claim* the test makes, independent of
+ * verification method.
+ *
+ * A heuristic, not a hard classifier — same caveat {@link inferVerificationMethod}
+ * already carries. Over-firing sweeps ordinary tests into the gate-test
+ * population (inflating the mutation-verification gate's authoring burden);
+ * under-firing lets a real gate test slip through ungated, the exact defect
+ * class #830 exists to prevent.
+ */
+/**
+ * Single-word gate-test keywords that commonly appear inflected/pluralized
+ * in evidence prose ("flags are wired", "fixtures exist", "the section
+ * presents..."). Matched with an optional trailing "s" (#946 AC-4) so
+ * anchoring to word boundaries doesn't lose those forms.
+ */
+const GATE_TEST_PLURAL_KEYWORDS = ["fixture", "section", "flag", "present"];
+/**
+ * Single-word gate-test keywords with no natural plural/inflection needed
+ * for this AC's evidence phrasing — matched as exact words only.
+ */
+const GATE_TEST_SINGULAR_KEYWORDS = ["wired", "exists", "registered"];
+/**
+ * Multi-word gate-test phrases, matched as substrings (already
+ * self-anchoring, same rationale as {@link VERIFICATION_KEYWORDS} phrases).
+ *
+ * The mutation-verification rule (CLAUDE.md, #830) IS the gate-test
+ * definition — an AC that already names its own mutation-verified record
+ * is self-identifying, even when it doesn't separately name a
+ * fixture/section/flag (e.g. "lint test fails when the §7 entry is
+ * deleted (mutation-verified)").
+ */
+const GATE_TEST_PHRASE_KEYWORDS = [
+    "skill gate",
+    "mutation-verified",
+    "mutation test",
+];
+const GATE_TEST_KEYWORD_MATCHERS = [
+    ...GATE_TEST_PLURAL_KEYWORDS.map((k) => keywordMatcher(k, true)),
+    ...GATE_TEST_SINGULAR_KEYWORDS.map((k) => keywordMatcher(k)),
+    ...GATE_TEST_PHRASE_KEYWORDS.map((k) => keywordMatcher(k)),
+];
+/**
+ * Phrases that mark evidence as a human-review attestation rather than an
+ * automated gate test, even when a {@link GATE_TEST_KEYWORD_MATCHERS} term also
+ * appears (#939 QA finding: "reviewed manually, fixture exists in the demo
+ * env" false-positived on `fixture` alone). Checked first and short-circuits
+ * to `false` — a human sign-off is not the mutation-verifiable claim §6i
+ * gates on, regardless of which nouns it happens to mention.
+ */
+const MANUAL_REVIEW_NEGATIVE_SIGNALS = [
+    "reviewed manually",
+    "manual review",
+    "human review",
+    "manually verified",
+    "manually confirmed",
+];
+/**
+ * Whether a declared `Evidence:` clause describes a CLAUDE.md-style gate
+ * test — a fixture-exists / section-present / flag-wired assertion — rather
+ * than an ordinary behavioral unit/integration test or a human sign-off.
+ *
+ * @param evidence - The declared evidence clause text (from {@link splitEvidenceClause})
+ * @returns True when the evidence text matches the gate-test keyword set and
+ *   does not read as a manual-review attestation
+ */
+export function isGateTestEvidence(evidence) {
+    const lower = evidence.toLowerCase();
+    if (MANUAL_REVIEW_NEGATIVE_SIGNALS.some((signal) => lower.includes(signal))) {
+        return false;
+    }
+    return GATE_TEST_KEYWORD_MATCHERS.some((regex) => regex.test(evidence));
+}
 /**
  * Parse a single line and extract AC if present
  *
@@ -146,12 +320,14 @@ function parseACLine(line) {
         if (match) {
             // Combine groups 2 and 3 for bold-wrapped format (Pattern 3)
             // where group 3 captures optional text after closing **
-            const description = match[3]
+            const rawDescription = match[3]
                 ? `${match[2].trim()} ${match[3].trim()}`.trim()
                 : match[2].trim();
+            const { description, evidence } = splitEvidenceClause(rawDescription);
             return {
                 id: match[1].toUpperCase(),
                 description,
+                ...(evidence !== undefined ? { evidence } : {}),
             };
         }
     }
@@ -181,11 +357,11 @@ function parseACLine(line) {
 export function parseAcceptanceCriteria(issueBody) {
     const criteria = [];
     const seenIds = new Set();
-    const push = (id, description) => {
+    const push = (id, description, evidence) => {
         if (seenIds.has(id))
             return;
         seenIds.add(id);
-        criteria.push(createAcceptanceCriterion(id, description, inferVerificationMethod(description)));
+        criteria.push(createAcceptanceCriterion(id, description, resolveVerificationMethod(description, evidence), evidence));
     };
     // Split into lines and process each. `inAcSection` tracks whether the
     // current line falls under an `## Acceptance Criteria` heading; it toggles on
@@ -193,6 +369,10 @@ export function parseAcceptanceCriteria(issueBody) {
     // rule as `parseNonGoals` in ready-gate.ts). `bareCount` numbers synthesized
     // IDs for bare checkboxes in appearance order.
     const lines = issueBody.split("\n");
+    // Lines inside a fenced code block (#947) — an AC-authoring example shown
+    // in a fence must not be scanned as a real AC, or toggle the AC-section
+    // heading state, in either pass below.
+    const fenceMask = computeFenceMask(lines);
     let inAcSection = false;
     let bareCount = 0;
     // Pre-scan for explicit IDs anywhere in the body. Synthesis must skip IDs
@@ -201,12 +381,17 @@ export function parseAcceptanceCriteria(issueBody) {
     // synthesizes AC-1 first and the author's explicit AC-1 is silently dropped
     // by the first-occurrence dedupe.
     const explicitIds = new Set();
-    for (const line of lines) {
-        const parsed = parseACLine(line);
+    for (let i = 0; i < lines.length; i++) {
+        if (fenceMask[i])
+            continue;
+        const parsed = parseACLine(lines[i]);
         if (parsed)
             explicitIds.add(parsed.id);
     }
-    for (const line of lines) {
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (fenceMask[i])
+            continue;
         if (HEADING_RE.test(line)) {
             inAcSection = AC_HEADING_RE.test(line);
             continue;
@@ -215,14 +400,15 @@ export function parseAcceptanceCriteria(issueBody) {
         // so previously-parsable issues are unaffected (AC-4).
         const parsed = parseACLine(line);
         if (parsed) {
-            push(parsed.id, parsed.description);
+            push(parsed.id, parsed.description, parsed.evidence);
             continue;
         }
         // Bare-checkbox fallback: only inside the AC section (AC-1/AC-2).
         if (inAcSection) {
             const bare = line.match(BARE_CHECKBOX_RE);
-            const description = bare?.[1].trim();
-            if (description) {
+            const bareText = bare?.[1].trim();
+            if (bareText) {
+                const { description, evidence } = splitEvidenceClause(bareText);
                 // Synthesize `AC-<n>`, skipping any ID already taken by an explicit
                 // marker — before OR after this line — so a synthesized ID can never
                 // collide with (and be silently dropped against) a hand-written one.
@@ -230,7 +416,7 @@ export function parseAcceptanceCriteria(issueBody) {
                 do {
                     id = `AC-${++bareCount}`;
                 } while (seenIds.has(id) || explicitIds.has(id));
-                push(id, description);
+                push(id, description, evidence);
             }
         }
     }

package/dist/src/lib/markdown-fence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Fenced-code-block tracking for line-oriented markdown scanners.
+ *
+ * Multiple parsers in this codebase scan an issue/PR body line-by-line
+ * looking for patterns (checkbox items, `## Non-Goals` bullets). Without
+ * fence awareness, a markdown-authoring example quoted inside a fence
+ * — showing what the pattern syntax looks like — gets scanned as if it
+ * were real content. See #947 (ac-parser.ts) and its sibling in
+ * scope/analyzer.ts's `parseNonGoals`.
+ */
+/**
+ * Compute, for every line of a split markdown body, whether that line falls
+ * inside a fenced code block (CommonMark rules: matching delimiter
+ * character, closing fence length >= opening fence length; an unclosed
+ * fence runs to EOF). The delimiter lines themselves are marked `true` —
+ * they're fence syntax, not real content, so patterns should skip them too.
+ */
+export declare function computeFenceMask(lines: string[]): boolean[];
+/**
+ * Blank out every line that falls inside a fenced code block, preserving
+ * line count (and therefore `\n`-relative offsets) so callers that locate
+ * sections via newline-anchored regexes on the full body are unaffected.
+ */
+export declare function stripFencedLines(body: string): string;

package/dist/src/lib/markdown-fence.js

@@ -0,0 +1,51 @@
+/**
+ * Fenced-code-block tracking for line-oriented markdown scanners.
+ *
+ * Multiple parsers in this codebase scan an issue/PR body line-by-line
+ * looking for patterns (checkbox items, `## Non-Goals` bullets). Without
+ * fence awareness, a markdown-authoring example quoted inside a fence
+ * — showing what the pattern syntax looks like — gets scanned as if it
+ * were real content. See #947 (ac-parser.ts) and its sibling in
+ * scope/analyzer.ts's `parseNonGoals`.
+ */
+/** Matches a fenced-code-block delimiter line (` ``` ` or `~~~`, 3+ repeats). */
+const FENCE_DELIMITER_RE = /^\s*(`{3,}|~{3,})/;
+/**
+ * Compute, for every line of a split markdown body, whether that line falls
+ * inside a fenced code block (CommonMark rules: matching delimiter
+ * character, closing fence length >= opening fence length; an unclosed
+ * fence runs to EOF). The delimiter lines themselves are marked `true` —
+ * they're fence syntax, not real content, so patterns should skip them too.
+ */
+export function computeFenceMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let fenceChar = null;
+    let fenceLen = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(FENCE_DELIMITER_RE);
+        if (fenceChar === null) {
+            if (match) {
+                fenceChar = match[1][0];
+                fenceLen = match[1].length;
+                mask[i] = true;
+            }
+            continue;
+        }
+        mask[i] = true;
+        if (match && match[1][0] === fenceChar && match[1].length >= fenceLen) {
+            fenceChar = null;
+            fenceLen = 0;
+        }
+    }
+    return mask;
+}
+/**
+ * Blank out every line that falls inside a fenced code block, preserving
+ * line count (and therefore `\n`-relative offsets) so callers that locate
+ * sections via newline-anchored regexes on the full body are unaffected.
+ */
+export function stripFencedLines(body) {
+    const lines = body.split("\n");
+    const mask = computeFenceMask(lines);
+    return lines.map((line, i) => (mask[i] ? "" : line)).join("\n");
+}