sequant 2.8.0 → 2.10.0

package/dist/src/lib/assess/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Schema for `/assess` rendered output (#823).
+ *
+ * The `/assess` skill produces judgment (triage verdicts); this schema is the
+ * contract it hands to the renderer, which produces geometry. Splitting the two
+ * is the point of #823: the model stopped emitting the output block at all, and
+ * when it did emit one the columns drifted, because deterministic formatting was
+ * being done by hand in a prompt.
+ *
+ * Modeled on `src/lib/scope/types.ts` (the in-repo precedent for a zod schema
+ * module). Deliberately carries no rendering logic — see `./renderer.ts`.
+ */
+import { z } from "zod";
+/**
+ * The fixed action vocabulary from `skills/assess/SKILL.md`. Every assessed
+ * issue gets exactly one.
+ */
+export declare const AssessActionSchema: z.ZodEnum<{
+    PROCEED: "PROCEED";
+    CLOSE: "CLOSE";
+    MERGE: "MERGE";
+    REWRITE: "REWRITE";
+    CLARIFY: "CLARIFY";
+    PARK: "PARK";
+}>;
+export type AssessAction = z.infer<typeof AssessActionSchema>;
+/**
+ * A `sequant` invocation. `args` excludes the command prefix — the renderer
+ * prepends the single resolved `commandPrefix` so one assessment can never mix
+ * `sequant` and `npx sequant` (Commands Block Rule #9).
+ */
+export declare const AssessCommandSchema: z.ZodObject<{
+    args: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AssessCommand = z.infer<typeof AssessCommandSchema>;
+/**
+ * A `Cleanup:` entry. These are `git`/`gh` commands, not `sequant` ones, so
+ * they carry no prefix and are emitted verbatim.
+ */
+export declare const AssessCleanupSchema: z.ZodObject<{
+    command: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AssessCleanup = z.infer<typeof AssessCleanupSchema>;
+/** A `Flags:` entry — one distinct flag plus its one-line justification. */
+export declare const AssessFlagSchema: z.ZodObject<{
+    flag: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type AssessFlag = z.infer<typeof AssessFlagSchema>;
+/**
+ * A `Considered:` entry — a flag or topology (`--chain`, `--testgen`,
+ * `--security-review`, …) whose trigger was evaluated and **not** met, plus the
+ * one-line reason it was not applied. Restores the why-not reasoning the
+ * original `/solve` format carried ("Also consider:") that the v3.0 redesign
+ * dropped and #522 only partially restored.
+ */
+export declare const AssessConsideredSchema: z.ZodObject<{
+    flag: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type AssessConsidered = z.infer<typeof AssessConsideredSchema>;
+/**
+ * A `⚠` warning. In batch mode `issue` scopes it to a row (`⚠ #458 ...`); in a
+ * posted single-mode comment the number is dropped because the comment is
+ * already scoped to that issue.
+ */
+export declare const AssessWarningSchema: z.ZodObject<{
+    issue: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type AssessWarning = z.infer<typeof AssessWarningSchema>;
+/**
+ * One assessed issue. Batch mode consumes the table fields; single mode
+ * consumes the detail fields. Cross-field requirements are enforced per-mode in
+ * {@link AssessResultSchema}'s refinement rather than by making fields
+ * unconditionally required, so a batch payload is not forced to carry titles it
+ * never renders.
+ */
+export declare const AssessIssueSchema: z.ZodObject<{
+    number: z.ZodNumber;
+    action: z.ZodEnum<{
+        PROCEED: "PROCEED";
+        CLOSE: "CLOSE";
+        MERGE: "MERGE";
+        REWRITE: "REWRITE";
+        CLARIFY: "CLARIFY";
+        PARK: "PARK";
+    }>;
+    reason: z.ZodString;
+    run: z.ZodOptional<z.ZodString>;
+    acCount: z.ZodOptional<z.ZodNumber>;
+    phases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    qualityLoop: z.ZodOptional<z.ZodBoolean>;
+    title: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    command: z.ZodOptional<z.ZodObject<{
+        args: z.ZodString;
+        comment: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    supersession: z.ZodOptional<z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    considered: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    cleanup: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    mergeTarget: z.ZodOptional<z.ZodNumber>;
+    scopeSelf: z.ZodOptional<z.ZodString>;
+    scopeTarget: z.ZodOptional<z.ZodString>;
+    need: z.ZodOptional<z.ZodString>;
+    needDetail: z.ZodOptional<z.ZodString>;
+    resumeAfter: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AssessIssue = z.infer<typeof AssessIssueSchema>;
+/** `Chain:` suggestion — an alternative execution topology, never auto-applied. */
+export declare const AssessChainSchema: z.ZodObject<{
+    args: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type AssessChain = z.infer<typeof AssessChainSchema>;
+/**
+ * The complete payload the `/assess` skill hands to the renderer.
+ *
+ * `.strict()` throughout is deliberate: a typo'd key is a silent data-loss bug
+ * in a hand-built JSON payload, and naming the unknown key is exactly the
+ * actionable error AC-2 asks for.
+ */
+export declare const AssessResultSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        single: "single";
+        batch: "batch";
+    }>;
+    commandPrefix: z.ZodString;
+    issues: z.ZodArray<z.ZodObject<{
+        number: z.ZodNumber;
+        action: z.ZodEnum<{
+            PROCEED: "PROCEED";
+            CLOSE: "CLOSE";
+            MERGE: "MERGE";
+            REWRITE: "REWRITE";
+            CLARIFY: "CLARIFY";
+            PARK: "PARK";
+        }>;
+        reason: z.ZodString;
+        run: z.ZodOptional<z.ZodString>;
+        acCount: z.ZodOptional<z.ZodNumber>;
+        phases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        qualityLoop: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        command: z.ZodOptional<z.ZodObject<{
+            args: z.ZodString;
+            comment: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        supersession: z.ZodOptional<z.ZodString>;
+        warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            flag: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strict>>>;
+        considered: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            flag: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strict>>>;
+        cleanup: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            command: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        mergeTarget: z.ZodOptional<z.ZodNumber>;
+        scopeSelf: z.ZodOptional<z.ZodString>;
+        scopeTarget: z.ZodOptional<z.ZodString>;
+        need: z.ZodOptional<z.ZodString>;
+        needDetail: z.ZodOptional<z.ZodString>;
+        resumeAfter: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        args: z.ZodString;
+        comment: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    orders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        issue: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodString;
+    }, z.core.$strict>>>;
+    chain: z.ZodOptional<z.ZodObject<{
+        args: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    considered: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    cleanup: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type AssessResult = z.infer<typeof AssessResultSchema>;
+/** Raised by {@link parseAssessResult} when validation fails. */
+export declare class AssessResultValidationError extends Error {
+    readonly problems: string[];
+    constructor(message: string, problems: string[]);
+}
+/**
+ * Validate an untrusted payload against {@link AssessResultSchema}.
+ *
+ * @throws {AssessResultValidationError} naming every offending field.
+ */
+export declare function parseAssessResult(input: unknown): AssessResult;

package/dist/src/lib/assess/types.js

@@ -0,0 +1,241 @@
+/**
+ * Schema for `/assess` rendered output (#823).
+ *
+ * The `/assess` skill produces judgment (triage verdicts); this schema is the
+ * contract it hands to the renderer, which produces geometry. Splitting the two
+ * is the point of #823: the model stopped emitting the output block at all, and
+ * when it did emit one the columns drifted, because deterministic formatting was
+ * being done by hand in a prompt.
+ *
+ * Modeled on `src/lib/scope/types.ts` (the in-repo precedent for a zod schema
+ * module). Deliberately carries no rendering logic — see `./renderer.ts`.
+ */
+import { z } from "zod";
+/**
+ * The fixed action vocabulary from `skills/assess/SKILL.md`. Every assessed
+ * issue gets exactly one.
+ */
+export const AssessActionSchema = z.enum([
+    "PROCEED",
+    "CLOSE",
+    "MERGE",
+    "REWRITE",
+    "CLARIFY",
+    "PARK",
+]);
+/**
+ * A `sequant` invocation. `args` excludes the command prefix — the renderer
+ * prepends the single resolved `commandPrefix` so one assessment can never mix
+ * `sequant` and `npx sequant` (Commands Block Rule #9).
+ */
+export const AssessCommandSchema = z
+    .object({
+    /** Everything after the prefix, e.g. `run 820 819 -Q`. */
+    args: z.string().min(1),
+    /** Trailing `# ...` annotation, e.g. `resume`, `restart`, `fresh start`. */
+    comment: z.string().optional(),
+})
+    .strict();
+/**
+ * A `Cleanup:` entry. These are `git`/`gh` commands, not `sequant` ones, so
+ * they carry no prefix and are emitted verbatim.
+ */
+export const AssessCleanupSchema = z
+    .object({
+    command: z.string().min(1),
+    reason: z.string().optional(),
+})
+    .strict();
+/** A `Flags:` entry — one distinct flag plus its one-line justification. */
+export const AssessFlagSchema = z
+    .object({
+    flag: z.string().min(1),
+    reason: z.string().min(1),
+})
+    .strict();
+/**
+ * A `Considered:` entry — a flag or topology (`--chain`, `--testgen`,
+ * `--security-review`, …) whose trigger was evaluated and **not** met, plus the
+ * one-line reason it was not applied. Restores the why-not reasoning the
+ * original `/solve` format carried ("Also consider:") that the v3.0 redesign
+ * dropped and #522 only partially restored.
+ */
+export const AssessConsideredSchema = AssessFlagSchema;
+/**
+ * A `⚠` warning. In batch mode `issue` scopes it to a row (`⚠ #458 ...`); in a
+ * posted single-mode comment the number is dropped because the comment is
+ * already scoped to that issue.
+ */
+export const AssessWarningSchema = z
+    .object({
+    issue: z.number().int().positive().optional(),
+    text: z.string().min(1),
+})
+    .strict();
+/**
+ * One assessed issue. Batch mode consumes the table fields; single mode
+ * consumes the detail fields. Cross-field requirements are enforced per-mode in
+ * {@link AssessResultSchema}'s refinement rather than by making fields
+ * unconditionally required, so a batch payload is not forced to carry titles it
+ * never renders.
+ */
+export const AssessIssueSchema = z
+    .object({
+    number: z.number().int().positive(),
+    action: AssessActionSchema,
+    /** Short `Reason` column text. The only column the renderer truncates. */
+    reason: z.string().min(1),
+    /** `Run` column value — a workflow (`spec → exec → qa`) or a symbol (`‖`). */
+    run: z.string().min(1).optional(),
+    /** Drives the conditional `ACs` column; omit when the issue has no checkbox ACs. */
+    acCount: z.number().int().nonnegative().optional(),
+    /** Resolved workflow, recorded in the HTML marker regardless of shorthand flags. */
+    phases: z.array(z.string().min(1)).optional(),
+    qualityLoop: z.boolean().optional(),
+    // --- single mode / posted comment ---
+    title: z.string().min(1).optional(),
+    state: z.string().min(1).optional(),
+    labels: z.array(z.string().min(1)).optional(),
+    /** This issue's own single-issue invocation (PROCEED / REWRITE). */
+    command: AssessCommandSchema.optional(),
+    /** `buildSupersessionHeader(priors)` output, emitted above the verdict line. */
+    supersession: z.string().min(1).optional(),
+    /** Per-issue warnings with the leading `#N` already dropped. */
+    warnings: z.array(z.string().min(1)).optional(),
+    flags: z.array(AssessFlagSchema).optional(),
+    /** Flags evaluated but not applied, each with its why-not reason. */
+    considered: z.array(AssessConsideredSchema).optional(),
+    cleanup: z.array(AssessCleanupSchema).optional(),
+    // --- verdict-specific ---
+    /** MERGE: the issue absorbing this one. */
+    mergeTarget: z.number().int().positive().optional(),
+    /** MERGE: this issue's scope summary. */
+    scopeSelf: z.string().min(1).optional(),
+    /** MERGE: the target's scope summary. */
+    scopeTarget: z.string().min(1).optional(),
+    /** CLARIFY: the specific information required. */
+    need: z.string().min(1).optional(),
+    /** CLARIFY: why the gap blocks work. */
+    needDetail: z.string().min(1).optional(),
+    /** PARK: the condition that unblocks this issue. */
+    resumeAfter: z.string().min(1).optional(),
+})
+    .strict();
+/** `Chain:` suggestion — an alternative execution topology, never auto-applied. */
+export const AssessChainSchema = z
+    .object({
+    args: z.string().min(1),
+    reason: z.string().min(1),
+})
+    .strict();
+/**
+ * The complete payload the `/assess` skill hands to the renderer.
+ *
+ * `.strict()` throughout is deliberate: a typo'd key is a silent data-loss bug
+ * in a hand-built JSON payload, and naming the unknown key is exactly the
+ * actionable error AC-2 asks for.
+ */
+export const AssessResultSchema = z
+    .object({
+    mode: z.enum(["batch", "single"]),
+    /** Resolved in the skill's Step-1 probe: `sequant` or `npx sequant`. */
+    commandPrefix: z.string().min(1),
+    issues: z.array(AssessIssueSchema).min(1),
+    // --- batch-only sections ---
+    commands: z.array(AssessCommandSchema).optional(),
+    /** `Order:` annotations, each carrying dependency reasoning. */
+    orders: z.array(z.string().min(1)).optional(),
+    warnings: z.array(AssessWarningSchema).optional(),
+    chain: AssessChainSchema.optional(),
+    flags: z.array(AssessFlagSchema).optional(),
+    /** Flags evaluated but not applied, each with its why-not reason. */
+    considered: z.array(AssessConsideredSchema).optional(),
+    cleanup: z.array(AssessCleanupSchema).optional(),
+})
+    .strict()
+    .superRefine((result, ctx) => {
+    if (result.mode === "batch") {
+        result.issues.forEach((issue, i) => {
+            if (!issue.run) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["issues", i, "run"],
+                    message: `batch mode requires a Run column value for issue #${issue.number}`,
+                });
+            }
+        });
+        return;
+    }
+    if (result.issues.length !== 1) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["issues"],
+            message: `single mode renders exactly one issue, received ${result.issues.length}`,
+        });
+    }
+    result.issues.forEach((issue, i) => {
+        for (const field of ["title", "state"]) {
+            if (!issue[field]) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["issues", i, field],
+                    message: `single mode requires ${field} for the #${issue.number} header line`,
+                });
+            }
+        }
+        if (issue.action === "MERGE" && issue.mergeTarget === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["issues", i, "mergeTarget"],
+                message: "MERGE requires the target issue number",
+            });
+        }
+        if (issue.action === "PARK" && !issue.resumeAfter) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["issues", i, "resumeAfter"],
+                message: "PARK requires a resume condition",
+            });
+        }
+        if (issue.action === "CLARIFY" && !issue.need) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["issues", i, "need"],
+                message: "CLARIFY requires the specific information needed",
+            });
+        }
+    });
+});
+/** Raised by {@link parseAssessResult} when validation fails. */
+export class AssessResultValidationError extends Error {
+    problems;
+    constructor(message, problems) {
+        super(message);
+        this.problems = problems;
+        this.name = "AssessResultValidationError";
+    }
+}
+/**
+ * Render a zod path as a readable field reference: `issues[2].action`.
+ */
+function formatPath(path) {
+    if (path.length === 0)
+        return "(root)";
+    return path.reduce((acc, segment) => {
+        if (typeof segment === "number")
+            return `${acc}[${segment}]`;
+        return acc === "" ? String(segment) : `${acc}.${String(segment)}`;
+    }, "");
+}
+/**
+ * Validate an untrusted payload against {@link AssessResultSchema}.
+ *
+ * @throws {AssessResultValidationError} naming every offending field.
+ */
+export function parseAssessResult(input) {
+    const result = AssessResultSchema.safeParse(input);
+    if (result.success)
+        return result.data;
+    const problems = result.error.issues.map((issue) => `${formatPath(issue.path)}: ${issue.message}`);
+    throw new AssessResultValidationError(`Invalid AssessResult:\n  ${problems.join("\n  ")}`, problems);
+}

package/dist/src/lib/assess-collision-detect.d.ts

@@ -22,12 +22,28 @@
  * users to ignore the warning.
  */
 export declare const EXCLUDED_PATHS: ReadonlySet<string>;
+/**
+ * Markdown H1/H2 section headings whose bodies are background/citation prose,
+ * not statements of intent-to-modify. A path named *only* under one of these
+ * is a reference to existing code, not a file the issue will touch — so the
+ * whole section is stripped before path extraction.
+ *
+ * Match is case-insensitive and prefix-based, so `## Motivation — concrete
+ * recent miss` and `## Additional context (see #533)` both match. This is the
+ * cheap version of the #556 proximity-weighting mitigation (#769): exclude
+ * background sections wholesale rather than scoring per-path distance to AC
+ * bullets. "A path appears only in background" ⟺ "the path is absent from the
+ * foreground", so stripping these sections up front subsumes per-path tagging.
+ */
+export declare const BACKGROUND_SECTIONS: ReadonlySet<string>;
 /**
  * Extract the set of file paths an issue body identifies as
  * targets-of-modification.
  *
  * Strategy:
- *   1. Strip fenced code blocks and HTML comments (AC-5 guard).
+ *   1. Strip fenced code blocks and HTML comments (AC-5 guard), then strip
+ *      background/citation sections (#769) so a path named only under
+ *      `## References`, `## Context`, etc. isn't counted as a target.
  *   2. Pull every backtick-quoted path matching the source-tree regex,
  *      normalizing skill-mirror paths to their canonical bare form.
  *   3. If the body mentions "3-dir sync", also pull bare
@@ -71,7 +87,8 @@ export declare function detectFileCollisions(issuePaths: Map<number, Set<string>
  * - `chainSuggestion` — emitted only when ≥3 issues collide on the same
  *   file (AC-4); suggest-only, never auto-applied. Annotated with the
  *   historical chain-mode success rate at length≥3 (1/6 = 17%, per #604
- *   forensics) so users can weigh chain mode against the parallel default.
+ *   forensics — the entire sample predates the #748/#749 fixes) so users
+ *   can weigh chain mode against the parallel default.
  */
 export interface CollisionAnnotations {
     orderLines: string[];

package/dist/src/lib/assess-collision-detect.js

@@ -27,6 +27,26 @@ export const EXCLUDED_PATHS = new Set([
     "yarn.lock",
     "pnpm-lock.yaml",
 ]);
+/**
+ * Markdown H1/H2 section headings whose bodies are background/citation prose,
+ * not statements of intent-to-modify. A path named *only* under one of these
+ * is a reference to existing code, not a file the issue will touch — so the
+ * whole section is stripped before path extraction.
+ *
+ * Match is case-insensitive and prefix-based, so `## Motivation — concrete
+ * recent miss` and `## Additional context (see #533)` both match. This is the
+ * cheap version of the #556 proximity-weighting mitigation (#769): exclude
+ * background sections wholesale rather than scoring per-path distance to AC
+ * bullets. "A path appears only in background" ⟺ "the path is absent from the
+ * foreground", so stripping these sections up front subsumes per-path tagging.
+ */
+export const BACKGROUND_SECTIONS = new Set([
+    "references",
+    "context",
+    "motivation",
+    "additional context",
+    "see also",
+]);
 /**
  * Slash-command names recognized as references to a skill's SKILL.md.
  * Used by the slash-command-skill derivation rule when an issue body
@@ -83,10 +103,52 @@ const THREE_DIR_SYNC_PATTERN = /3[- ]dir(?:ectory)?\s+sync|across\s+all\s+three\
  * single-backtick wrapper, so this gives us the "paths quoted as code in
  * prose count, paths inside a code block don't" behavior the AC-5 guard
  * specifies.
+ *
+ * Do NOT unify this with `dependency-markers.ts:stripCodeAndComments`, which
+ * looks nearly identical but additionally strips inline spans. The two have
+ * opposite requirements for the same syntax: there a backticked marker is a
+ * documentation example to discard, here a backticked path is the entire
+ * signal. Adding its inline-span strip to this function would delete every
+ * path PATH_REGEX is looking for and silently return an empty set.
  */
 function stripCodeBlocksAndComments(body) {
     return body.replace(/```[\s\S]*?```/g, "").replace(/<!--[\s\S]*?-->/g, "");
 }
+/**
+ * Remove background/citation sections (see `BACKGROUND_SECTIONS`) so a path
+ * named only as a reference — under `## References`, `## Context`, etc. — is
+ * not counted as a modification target (#769).
+ *
+ * A section runs from its H1/H2 heading to the next H1/H2 heading (or EOF);
+ * `###`+ subsections belong to their parent section and are dropped with it.
+ * Only H1/H2 headings toggle sections — a `### Detail` inside a stripped
+ * `## Additional context` must not resurrect the rest of the section.
+ *
+ * Run this *after* `stripCodeBlocksAndComments` so a fenced block containing a
+ * `## `-prefixed line can't be misread as a real heading.
+ */
+function stripBackgroundSections(body) {
+    const kept = [];
+    let stripping = false;
+    for (const line of body.split("\n")) {
+        const heading = line.match(/^(#{1,6})\s+(.*)$/);
+        if (heading && heading[1].length <= 2) {
+            const text = heading[2].trim().toLowerCase();
+            stripping = false;
+            for (const section of BACKGROUND_SECTIONS) {
+                if (text.startsWith(section)) {
+                    stripping = true;
+                    break;
+                }
+            }
+            if (stripping)
+                continue; // drop the heading line itself
+        }
+        if (!stripping)
+            kept.push(line);
+    }
+    return kept.join("\n");
+}
 /**
  * Collapse a fully-qualified skill-mirror path to its canonical bare form.
  *
@@ -109,7 +171,9 @@ function normalizeSkillMirrorPath(path) {
  * targets-of-modification.
  *
  * Strategy:
- *   1. Strip fenced code blocks and HTML comments (AC-5 guard).
+ *   1. Strip fenced code blocks and HTML comments (AC-5 guard), then strip
+ *      background/citation sections (#769) so a path named only under
+ *      `## References`, `## Context`, etc. isn't counted as a target.
  *   2. Pull every backtick-quoted path matching the source-tree regex,
  *      normalizing skill-mirror paths to their canonical bare form.
  *   3. If the body mentions "3-dir sync", also pull bare
@@ -125,7 +189,7 @@ function normalizeSkillMirrorPath(path) {
  */
 export function extractPathsFromIssueBody(body) {
     const paths = new Set();
-    const cleaned = stripCodeBlocksAndComments(body);
+    const cleaned = stripBackgroundSections(stripCodeBlocksAndComments(body));
     for (const m of cleaned.matchAll(PATH_REGEX)) {
         paths.add(normalizeSkillMirrorPath(m[1]));
     }
@@ -208,9 +272,9 @@ export function formatCollisionAnnotations(results) {
         if (r.issues.length >= 3 && !chainSuggestion) {
             const ids = r.issues.join(" ");
             chainSuggestion =
-                `Chain: npx sequant run ${ids} --chain --qa-gate -Q   ` +
+                `Chain: npx sequant run ${ids} --chain -Q   ` +
                     `# alternative — ${r.issues.length} issues modify ${r.file} ` +
-                    `(chain length≥3 historically 1/6 = 17%; see docs/reference/chain-mode-analysis-2026-05.md)`;
+                    `(chain length≥3 historically 1/6 = 17%, predates the #748/#749 fixes; see docs/reference/chain-mode-analysis-2026-05.md)`;
         }
     }
     return { orderLines, warnings, chainSuggestion };

package/dist/src/lib/ci/outputs.d.ts

@@ -12,8 +12,15 @@ import type { ActionOutputs } from "./types.js";
 export declare function formatOutputs(result: IssueResult): ActionOutputs;
 /**
  * Format multiple issue results into combined outputs.
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration, computed by
+ * whoever brackets the run (the orchestrator surfaces it as
+ * `RunResult.wallClockDurationSeconds`). It is a required argument rather than
+ * something derived here because the per-issue durations this function receives
+ * cannot express it: under `--parallel` they overlap, so summing them
+ * double-counts and over-reports by roughly the concurrency factor (#867).
  */
-export declare function formatMultiOutputs(results: IssueResult[]): ActionOutputs;
+export declare function formatMultiOutputs(results: IssueResult[], wallClockDurationSeconds: number): ActionOutputs;
 /**
  * Generate shell commands to set GitHub Actions outputs.
  * Each output is written to $GITHUB_OUTPUT file.
@@ -21,5 +28,11 @@ export declare function formatMultiOutputs(results: IssueResult[]): ActionOutput
 export declare function outputCommands(outputs: ActionOutputs): string[];
 /**
  * Generate a GitHub Actions step summary (Markdown).
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration. Required for
+ * the same reason as in {@link formatMultiOutputs}: the per-issue durations
+ * below overlap under `--parallel`, so the "Total duration" line cannot be
+ * derived by summing them (#867). Per-*phase* durations in the tables are
+ * unaffected — phases within an issue run sequentially.
  */
-export declare function formatSummary(results: IssueResult[]): string;
+export declare function formatSummary(results: IssueResult[], wallClockDurationSeconds: number): string;