sequant 2.1.2 → 2.3.0

package/dist/src/commands/status.js

@@ -10,6 +10,8 @@ import { StateManager } from "../lib/workflow/state-manager.js";
 import { rebuildStateFromLogs, cleanupStaleEntries, } from "../lib/workflow/state-utils.js";
 import { reconcileState, getNextActionHint, formatRelativeTime, } from "../lib/workflow/reconcile.js";
 import { getSettingsWithWarnings } from "../lib/settings.js";
+import { getSkillVersions } from "../lib/skill-version.js";
+import { LockManager, formatLockedMessage } from "../lib/locks/index.js";
 /**
  * Run reconciliation and display warnings.
  * Returns the reconcile result for use in display.
@@ -181,11 +183,16 @@ function displayIssueSummary(issues) {
             const hintDisplay = hint
                 ? chalk.gray(`→ ${hint.length > 30 ? hint.substring(0, 27) + "..." : hint}`)
                 : "";
+            // Relay column (#383). Shows ✓ when active, "-" otherwise.
+            const relayDisplay = issue.relay?.enabled
+                ? chalk.green("on")
+                : chalk.gray("-");
             rows.push([
                 `#${issue.number}`,
                 title,
                 colorStatus(issue.status, issue.resolvedAt),
                 issue.currentPhase || "-",
+                relayDisplay,
                 hintDisplay,
             ]);
         }
@@ -198,6 +205,7 @@ function displayIssueSummary(issues) {
                 { header: "Title", width: 32 },
                 { header: "Status", width: 20 },
                 { header: "Phase", width: 10 },
+                { header: "Relay", width: 5 },
                 { header: "Next", width: 34 },
             ],
         }));
@@ -263,13 +271,26 @@ export async function statusCommand(options = {}) {
             console.log(chalk.yellow(`    ${w.message}`));
         }
     }
-    // Count skills
+    // Count skills and check versions
     const skillsDir = ".claude/skills";
     if (await fileExists(skillsDir)) {
         try {
             const skills = await readdir(skillsDir);
             const skillCount = skills.filter((s) => !s.startsWith(".")).length;
             console.log(chalk.gray(`Skills: ${skillCount}`));
+            // Show skill version info
+            const { getTemplatesDir } = await import("../lib/templates.js");
+            const { join } = await import("path");
+            const templateSkillsDir = join(getTemplatesDir(), "skills");
+            const skillVersions = await getSkillVersions(templateSkillsDir);
+            const outdated = skillVersions.filter((s) => s.updateAvailable);
+            if (outdated.length > 0) {
+                console.log(chalk.yellow(`\n  Skill updates available (${outdated.length}):`));
+                for (const s of outdated) {
+                    console.log(chalk.yellow(`    ${s.name}: v${s.installedVersion} → v${s.templateVersion}`));
+                }
+                console.log(chalk.gray("    Run `sequant init --upgrade-skills` to update."));
+            }
         }
         catch {
             // Ignore errors
@@ -342,6 +363,11 @@ async function displayIssueState(options) {
             else if (issueState) {
                 console.log(chalk.bold(`\nIssue #${options.issue} State\n`));
                 console.log(formatIssueState(issueState));
+                const lockManager = new LockManager();
+                const holder = lockManager.check(options.issue);
+                if (holder) {
+                    console.log(chalk.yellow(`    !  ${formatLockedMessage(options.issue, holder)}`));
+                }
                 const hint = getNextActionHint(issueState);
                 if (hint) {
                     console.log(chalk.cyan(`\n    Next: ${hint}`));

package/dist/src/commands/watch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `sequant watch <issue>` — tail the relay outbox for replies from a running
+ * headless session (#383). Uses `fs.watch()` when available, falls back to
+ * polling on platforms where `fs.watch` is unreliable (NFS, some WSL setups).
+ */
+export interface WatchCommandOptions {
+    json?: boolean;
+    /** Poll interval (ms); used when fs.watch is unavailable. Default: 200. */
+    pollIntervalMs?: number;
+    /** Abort signal for clean shutdown (tests). */
+    signal?: AbortSignal;
+}
+export declare function watchCommand(argsAndOptions: {
+    args: string[];
+    options: WatchCommandOptions;
+}): Promise<void>;

package/dist/src/commands/watch.js

@@ -0,0 +1,147 @@
+/**
+ * `sequant watch <issue>` — tail the relay outbox for replies from a running
+ * headless session (#383). Uses `fs.watch()` when available, falls back to
+ * polling on platforms where `fs.watch` is unreliable (NFS, some WSL setups).
+ */
+import { existsSync, statSync, createReadStream, watch } from "fs";
+import chalk from "chalk";
+import { outboxPathFor } from "../lib/relay/paths.js";
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { RelayResponseSchema } from "../lib/relay/types.js";
+function formatTimestamp(iso) {
+    try {
+        const date = new Date(iso);
+        const hh = String(date.getHours()).padStart(2, "0");
+        const mm = String(date.getMinutes()).padStart(2, "0");
+        const ss = String(date.getSeconds()).padStart(2, "0");
+        return `${hh}:${mm}:${ss}`;
+    }
+    catch {
+        return iso;
+    }
+}
+function formatLine(reply, json) {
+    if (json)
+        return JSON.stringify(reply);
+    return chalk.gray(`[${formatTimestamp(reply.timestamp)}] `) + reply.message;
+}
+function readNewLines(path, state) {
+    return new Promise((resolve, reject) => {
+        if (!existsSync(path)) {
+            resolve([]);
+            return;
+        }
+        const stat = statSync(path);
+        if (stat.size <= state.offset) {
+            // File was truncated/rotated — reset offset.
+            if (stat.size < state.offset)
+                state.offset = 0;
+            resolve([]);
+            return;
+        }
+        const stream = createReadStream(path, {
+            start: state.offset,
+            end: stat.size - 1,
+            encoding: "utf-8",
+        });
+        let buf = state.partial;
+        stream.on("data", (chunk) => {
+            buf += chunk;
+        });
+        stream.on("error", (err) => reject(err));
+        stream.on("end", () => {
+            state.offset = stat.size;
+            const lines = buf.split("\n");
+            state.partial = lines.pop() ?? "";
+            const replies = [];
+            for (const line of lines) {
+                if (line.trim() === "")
+                    continue;
+                try {
+                    const parsed = RelayResponseSchema.safeParse(JSON.parse(line));
+                    if (parsed.success)
+                        replies.push(parsed.data);
+                }
+                catch {
+                    /* skip malformed */
+                }
+            }
+            resolve(replies);
+        });
+    });
+}
+export async function watchCommand(argsAndOptions) {
+    const { args, options } = argsAndOptions;
+    const issueArg = args[0];
+    if (!issueArg) {
+        throw new Error("Usage: sequant watch <issue>");
+    }
+    const issueNumber = Number.parseInt(issueArg, 10);
+    if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+        throw new Error(`Invalid issue number: '${issueArg}'`);
+    }
+    const stateManager = new StateManager();
+    const issueState = await stateManager.getIssueState(issueNumber);
+    const outboxPath = outboxPathFor(issueNumber, {
+        worktreePath: issueState?.worktree,
+    });
+    const pollIntervalMs = options.pollIntervalMs ?? 200;
+    const tail = { offset: 0, partial: "" };
+    // Seed tail offset at current EOF so we only show NEW replies.
+    if (existsSync(outboxPath)) {
+        tail.offset = statSync(outboxPath).size;
+    }
+    if (!options.json) {
+        console.log(chalk.gray(`Watching #${issueNumber} outbox — Ctrl+C to stop`));
+    }
+    let stopped = false;
+    const stop = () => {
+        stopped = true;
+    };
+    options.signal?.addEventListener("abort", stop);
+    process.on("SIGINT", () => {
+        stop();
+        if (!options.json)
+            console.log(chalk.gray("\nStopped watching."));
+        process.exit(0);
+    });
+    let useWatcher = false;
+    let watcher = null;
+    try {
+        if (existsSync(outboxPath)) {
+            watcher = watch(outboxPath, { persistent: true }, () => {
+                // fs.watch fires on any modification; we still poll readNewLines.
+            });
+            useWatcher = true;
+        }
+    }
+    catch {
+        useWatcher = false;
+    }
+    const emit = (replies) => {
+        for (const r of replies) {
+            console.log(formatLine(r, options.json === true));
+        }
+    };
+    // Polling loop — also used as a heartbeat when fs.watch is active so we
+    // don't miss events on filesystems where watch is unreliable.
+    while (!stopped) {
+        try {
+            const replies = await readNewLines(outboxPath, tail);
+            emit(replies);
+        }
+        catch {
+            /* transient — try again next tick */
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    if (watcher) {
+        try {
+            watcher.close();
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    void useWatcher; // currently unused beyond best-effort init
+}

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

@@ -19,7 +19,7 @@ import type { AcceptanceCriterion } from "./workflow/state-schema.js";
 /**
  * Types of issues that can be flagged in AC
  */
-export type ACLintIssueType = "vague" | "unmeasurable" | "incomplete" | "open_ended";
+export type ACLintIssueType = "vague" | "unmeasurable" | "incomplete" | "open_ended" | "title-body-tension";
 /**
  * A lint issue found in an acceptance criterion
  */

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

@@ -194,6 +194,84 @@ const DEFAULT_LINT_PATTERNS = [
         suggestion: "List all items explicitly or define boundaries",
     },
 ];
+/**
+ * Documentation-noun head words that suggest a doc-only verification bar
+ * when they appear in the AC title.
+ */
+const DOC_NOUNS = [
+    "note",
+    "comment",
+    "documentation",
+    "description",
+    "snippet",
+    "entry",
+    "mention",
+];
+/**
+ * Runtime-imperative phrases that suggest an execution/evidence bar
+ * when they appear in the AC body.
+ */
+const RUNTIME_IMPERATIVES = [
+    "execute",
+    "trigger",
+    "capture",
+    "verify by running",
+    "reproduce",
+    "confirm at runtime",
+];
+/**
+ * Slash-command runtime pattern: "run /<command>" anywhere in the body.
+ */
+const RUN_SLASH_RE = /\brun\s+\/[a-z][a-z0-9_-]*/i;
+/**
+ * Detect title/body verification-method tension.
+ *
+ * Splits the AC description on the first separator (`.`, `\n`, `:`, or `—`).
+ * Treats the head as the "title" and the rest as the "body". Warns when the
+ * title contains a documentation-noun (suggesting a doc bar) AND the body
+ * contains a runtime-imperative (incl. inflections like `triggered`,
+ * `captured`) or `run /<command>` (suggesting a runtime bar).
+ *
+ * Warning-only — same convention as the regex-based DEFAULT_LINT_PATTERNS.
+ *
+ * @param ac - The acceptance criterion to check
+ * @returns A lint issue if tension is detected, otherwise null
+ */
+function detectTitleBodyTension(ac) {
+    const description = ac.description;
+    const splitIdx = description.search(/[.\n:—]/);
+    if (splitIdx <= 0)
+        return null;
+    const title = description.slice(0, splitIdx);
+    const body = description.slice(splitIdx + 1);
+    if (title.length === 0 || body.length === 0)
+        return null;
+    const titleLower = title.toLowerCase();
+    const bodyLower = body.toLowerCase();
+    const docNoun = DOC_NOUNS.find((noun) => new RegExp(`\\b${noun}\\b`, "i").test(titleLower));
+    if (!docNoun)
+        return null;
+    const runtimeImperative = RUNTIME_IMPERATIVES.find((imp) => {
+        if (imp.includes(" ")) {
+            return new RegExp(`\\b${imp}\\b`, "i").test(bodyLower);
+        }
+        if (imp.endsWith("e")) {
+            const stem = imp.slice(0, -1);
+            return new RegExp(`\\b${stem}(?:e|es|ed|ing)\\b`, "i").test(bodyLower);
+        }
+        return new RegExp(`\\b${imp}(?:s|ed|ing)?\\b`, "i").test(bodyLower);
+    });
+    const slashRun = RUN_SLASH_RE.test(body);
+    if (!runtimeImperative && !slashRun)
+        return null;
+    const matched = runtimeImperative ?? "run /<command>";
+    return {
+        type: "title-body-tension",
+        matchedPattern: `title="${docNoun}" + body="${matched}"`,
+        problem: "Title/body tension: title implies a documentation bar, body specifies a runtime/execution bar",
+        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.",
+    };
+}
 /**
  * Lint a single acceptance criterion against all patterns
  *
@@ -215,6 +293,9 @@ export function lintAcceptanceCriterion(ac, patterns = DEFAULT_LINT_PATTERNS) {
             });
         }
     }
+    const tension = detectTitleBodyTension(ac);
+    if (tension)
+        issues.push(tension);
     return {
         ac,
         issues,

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

@@ -0,0 +1,91 @@
+/**
+ * Predicted file-collision detection between PROCEED issues.
+ *
+ * Step 5 of `/assess` already inspects active worktrees for in-flight overlap.
+ * This module adds a complementary heuristic: read the bodies of unstarted
+ * PROCEED issues and predict which pairs will modify the same file once
+ * they're both run in parallel worktrees.
+ *
+ * The detector scans markdown bodies for file-path mentions outside fenced
+ * code blocks and HTML comments, then computes pairwise intersections. A
+ * small exclusion list filters paths that nearly every PROCEED issue tends
+ * to touch (CHANGELOG.md, lockfiles).
+ *
+ * Tunables — including the exclusion list, path regex, and the
+ * slash-command-skill derivation rule — are documented in
+ * `references/predicted-collision-detection.md` so they can change without
+ * skill-prose edits.
+ */
+/**
+ * Files that virtually every PROCEED issue mentions. Including them in
+ * pairwise intersection would flag every batch as colliding, training
+ * users to ignore the warning.
+ */
+export declare const EXCLUDED_PATHS: 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).
+ *   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
+ *      `<name>/SKILL.md` references and `/<skill>` slash-command
+ *      mentions (where `<skill>` is in KNOWN_SKILL_NAMES). Both already
+ *      live in the canonical bare form.
+ *   4. Remove globally excluded paths.
+ *
+ * The canonical bare form (`qa/SKILL.md`, not `.claude/skills/qa/SKILL.md`)
+ * is what the dashboard's `Order:` annotations render, and it makes
+ * mirrored collisions deduplicate without a separate post-processing
+ * pass.
+ */
+export declare function extractPathsFromIssueBody(body: string): Set<string>;
+/**
+ * A predicted file collision: 2+ issues whose bodies both name the same
+ * file as a target-of-modification.
+ */
+export interface CollisionResult {
+    /** Issue numbers involved, in ascending order. */
+    issues: number[];
+    /** Path of the shared file (POSIX-style). */
+    file: string;
+}
+/**
+ * Compute file-path overlaps across issue bodies.
+ *
+ * Each shared file emits one CollisionResult. When N issues all share a
+ * file, that's a single result with `issues.length === N` — the caller
+ * decides whether to chain-suggest based on count.
+ *
+ * Sort order: ascending file name, then ascending first-issue number.
+ */
+export declare function detectFileCollisions(issuePaths: Map<number, Set<string>>): CollisionResult[];
+/**
+ * Rendered collision annotations ready for the dashboard output.
+ *
+ * - `orderLines` — one `Order:` line per pair (or per group).
+ * - `warnings` — `⚠ #N  Modifies ... (overlaps #M); land sequentially`,
+ *   one per affected issue per collision.
+ * - `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.
+ */
+export interface CollisionAnnotations {
+    orderLines: string[];
+    warnings: string[];
+    chainSuggestion?: string;
+}
+/**
+ * Format collision results as dashboard annotations.
+ *
+ * - 2-issue collision: `Order: A → B (path)` plus a warning per issue.
+ * - 3+-issue collision on the same file: `Order: A → B → C (path)`,
+ *   warnings per issue, plus a single `Chain:` suggestion.
+ *
+ * Multiple shared files between the same pair render as multiple
+ * Order: lines (one per file). Callers decide whether to truncate.
+ */
+export declare function formatCollisionAnnotations(results: CollisionResult[]): CollisionAnnotations;

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

@@ -0,0 +1,217 @@
+/**
+ * Predicted file-collision detection between PROCEED issues.
+ *
+ * Step 5 of `/assess` already inspects active worktrees for in-flight overlap.
+ * This module adds a complementary heuristic: read the bodies of unstarted
+ * PROCEED issues and predict which pairs will modify the same file once
+ * they're both run in parallel worktrees.
+ *
+ * The detector scans markdown bodies for file-path mentions outside fenced
+ * code blocks and HTML comments, then computes pairwise intersections. A
+ * small exclusion list filters paths that nearly every PROCEED issue tends
+ * to touch (CHANGELOG.md, lockfiles).
+ *
+ * Tunables — including the exclusion list, path regex, and the
+ * slash-command-skill derivation rule — are documented in
+ * `references/predicted-collision-detection.md` so they can change without
+ * skill-prose edits.
+ */
+/**
+ * Files that virtually every PROCEED issue mentions. Including them in
+ * pairwise intersection would flag every batch as colliding, training
+ * users to ignore the warning.
+ */
+export const EXCLUDED_PATHS = new Set([
+    "CHANGELOG.md",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+]);
+/**
+ * Slash-command names recognized as references to a skill's SKILL.md.
+ * Used by the slash-command-skill derivation rule when an issue body
+ * also signals 3-dir sync — the skill name maps deterministically to the
+ * three mirrored SKILL.md files.
+ */
+const KNOWN_SKILL_NAMES = [
+    "assess",
+    "spec",
+    "exec",
+    "qa",
+    "test",
+    "testgen",
+    "verify",
+    "loop",
+    "merger",
+    "security-review",
+    "fullsolve",
+    "docs",
+    "release",
+    "clean",
+    "improve",
+    "reflect",
+    "setup",
+];
+/**
+ * Regex matching backtick-quoted file paths under the project's tracked
+ * directories. The path component must start with a tracked directory
+ * root and end with a known source extension.
+ */
+const PATH_REGEX = /`((?:\.claude|templates|skills|src|bin|docs)\/[A-Za-z0-9_./@-]+\.(?:md|tsx?|json|sh))`/g;
+/**
+ * Bare-filename match for skill files referenced alongside "3-dir sync"
+ * language. Captures e.g. `qa/SKILL.md` so we can expand it to the three
+ * skill roots.
+ */
+const SKILL_FILE_REGEX = /`((?:[a-z][a-z0-9_-]*\/)+SKILL\.md)`/g;
+/**
+ * Slash-command mention regex (e.g. `/qa`, `/spec`). Captures the name
+ * for cross-reference against KNOWN_SKILL_NAMES. The non-word lookahead
+ * keeps `/qa-section` from matching as `/qa`.
+ */
+const SLASH_COMMAND_REGEX = /(?<![\w-])\/([a-z][a-z-]*)(?![\w-])/g;
+/**
+ * Phrase that signals the cited skill file is mirrored to all three
+ * skill-root directories.
+ */
+const THREE_DIR_SYNC_PATTERN = /3[- ]dir(?:ectory)?\s+sync|across\s+all\s+three\s+skill\s+directories|across\s+(?:the\s+)?three\s+skill\s+directories/i;
+/**
+ * Strip fenced code blocks and HTML comments from a markdown body so the
+ * path regex doesn't fire on quoted shell snippets or commented-out drafts.
+ *
+ * Inline backticks (single ` `) are preserved — the path regex requires a
+ * 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.
+ */
+function stripCodeBlocksAndComments(body) {
+    return body.replace(/```[\s\S]*?```/g, "").replace(/<!--[\s\S]*?-->/g, "");
+}
+/**
+ * Collapse a fully-qualified skill-mirror path to its canonical bare form.
+ *
+ * The repo maintains three byte-identical mirrors of every skill file
+ * under `.claude/skills/`, `templates/skills/`, and `skills/`. Treating
+ * those mirrors as separate paths in collision detection produces 3× the
+ * Order: lines and 6× the warnings for one logical conflict, since both
+ * sides of the 3-dir-sync expansion match each mirror.
+ *
+ * Normalizing to the bare subpath (e.g. `qa/SKILL.md`) makes mirrored
+ * collisions deduplicate naturally and matches the issue-body shorthand
+ * the dashboard's `Order:` annotation already uses.
+ */
+function normalizeSkillMirrorPath(path) {
+    const m = path.match(/^(?:\.claude\/skills\/|templates\/skills\/|skills\/)(.+)$/);
+    return m ? m[1] : path;
+}
+/**
+ * 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).
+ *   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
+ *      `<name>/SKILL.md` references and `/<skill>` slash-command
+ *      mentions (where `<skill>` is in KNOWN_SKILL_NAMES). Both already
+ *      live in the canonical bare form.
+ *   4. Remove globally excluded paths.
+ *
+ * The canonical bare form (`qa/SKILL.md`, not `.claude/skills/qa/SKILL.md`)
+ * is what the dashboard's `Order:` annotations render, and it makes
+ * mirrored collisions deduplicate without a separate post-processing
+ * pass.
+ */
+export function extractPathsFromIssueBody(body) {
+    const paths = new Set();
+    const cleaned = stripCodeBlocksAndComments(body);
+    for (const m of cleaned.matchAll(PATH_REGEX)) {
+        paths.add(normalizeSkillMirrorPath(m[1]));
+    }
+    const threeDir = THREE_DIR_SYNC_PATTERN.test(cleaned);
+    if (threeDir) {
+        for (const m of cleaned.matchAll(SKILL_FILE_REGEX)) {
+            paths.add(m[1]);
+        }
+        for (const m of cleaned.matchAll(SLASH_COMMAND_REGEX)) {
+            const name = m[1];
+            if (KNOWN_SKILL_NAMES.includes(name)) {
+                paths.add(`${name}/SKILL.md`);
+            }
+        }
+    }
+    for (const excluded of EXCLUDED_PATHS) {
+        paths.delete(excluded);
+    }
+    return paths;
+}
+/**
+ * Compute file-path overlaps across issue bodies.
+ *
+ * Each shared file emits one CollisionResult. When N issues all share a
+ * file, that's a single result with `issues.length === N` — the caller
+ * decides whether to chain-suggest based on count.
+ *
+ * Sort order: ascending file name, then ascending first-issue number.
+ */
+export function detectFileCollisions(issuePaths) {
+    const fileToIssues = new Map();
+    for (const [issueNumber, paths] of issuePaths) {
+        for (const file of paths) {
+            let bucket = fileToIssues.get(file);
+            if (!bucket) {
+                bucket = new Set();
+                fileToIssues.set(file, bucket);
+            }
+            bucket.add(issueNumber);
+        }
+    }
+    const results = [];
+    for (const [file, issues] of fileToIssues) {
+        if (issues.size < 2)
+            continue;
+        results.push({
+            file,
+            issues: [...issues].sort((a, b) => a - b),
+        });
+    }
+    results.sort((a, b) => {
+        if (a.file !== b.file)
+            return a.file < b.file ? -1 : 1;
+        return a.issues[0] - b.issues[0];
+    });
+    return results;
+}
+/**
+ * Format collision results as dashboard annotations.
+ *
+ * - 2-issue collision: `Order: A → B (path)` plus a warning per issue.
+ * - 3+-issue collision on the same file: `Order: A → B → C (path)`,
+ *   warnings per issue, plus a single `Chain:` suggestion.
+ *
+ * Multiple shared files between the same pair render as multiple
+ * Order: lines (one per file). Callers decide whether to truncate.
+ */
+export function formatCollisionAnnotations(results) {
+    const orderLines = [];
+    const warnings = [];
+    let chainSuggestion;
+    for (const r of results) {
+        const arrow = r.issues.join(" → ");
+        orderLines.push(`Order: ${arrow} (${r.file})`);
+        for (const n of r.issues) {
+            const others = r.issues.filter((m) => m !== n);
+            const overlapStr = others.map((m) => `#${m}`).join(", ");
+            warnings.push(`⚠ #${n}  Modifies ${r.file} (overlaps ${overlapStr}); land sequentially`);
+        }
+        if (r.issues.length >= 3 && !chainSuggestion) {
+            const ids = r.issues.join(" ");
+            chainSuggestion =
+                `Chain: npx sequant run ${ids} --chain --qa-gate -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)`;
+        }
+    }
+    return { orderLines, warnings, chainSuggestion };
+}