sequant 2.2.0 → 2.3.0

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 };
+}

package/dist/src/lib/assess-comment-parser.d.ts

@@ -75,7 +75,12 @@ export interface AssessMarkers {
  */
 export type SolveMarkers = AssessMarkers;
 /**
- * Check if a comment is an assess command output (new format)
+ * Check if a comment is an assess command output (new format).
+ *
+ * Matches either prose markers (e.g., "## Assess Analysis") or the durable
+ * HTML action marker `<!-- assess:action=... -->` written by every /assess
+ * comment regardless of prose format. The HTML marker is the contract;
+ * prose can change.
  */
 export declare function isAssessComment(body: string): boolean;
 /**
@@ -87,6 +92,14 @@ export declare function isSolveComment(body: string): boolean;
  * Find the most recent assess/solve comment from a list of comments
  */
 export declare function findAssessComment(comments: IssueComment[]): IssueComment | null;
+/**
+ * Find every assess/solve comment in chronological order (oldest first).
+ *
+ * Preserves the input order of `comments`, which is the order GitHub returns
+ * them (chronological). Callers that need the most recent comment should
+ * read the last element.
+ */
+export declare function findAllAssessComments(comments: IssueComment[]): IssueComment[];
 /**
  * Find the most recent solve comment from a list of comments
  * @deprecated Use findAssessComment instead
@@ -135,3 +148,48 @@ export declare function assessCoversIssue(workflow: AssessWorkflowResult, issueN
  * @deprecated Use assessCoversIssue instead
  */
 export declare function solveCoversIssue(workflow: AssessWorkflowResult, issueNumber: number): boolean;
+/**
+ * Build a one-line supersession header for a new assess comment.
+ *
+ * Format:
+ * - 0 priors → null (caller omits the header entirely)
+ * - 1 prior  → `Supersedes prior assess from <date> (<action>)`
+ * - ≥2 priors → `Supersedes N prior assessments (most recent: <date>)`
+ *
+ * Priors must be passed in chronological order (oldest first), matching
+ * the output of findAllAssessComments.
+ */
+export declare function buildSupersessionHeader(priors: IssueComment[]): string | null;
+/**
+ * Result of churn detection: whether to fire the warning, the count
+ * of prior assessments, and the date of the first one.
+ */
+export interface ChurnResult {
+    isChurn: boolean;
+    count: number;
+    firstDate?: string;
+}
+/**
+ * Detect re-assessment churn — repeated /assess invocations without
+ * an intervening exec phase. Fires only when ≥3 priors exist and no
+ * exec phase marker appears in any comment dated after the first prior.
+ *
+ * `allComments` should be the full comment list from the issue
+ * (including the prior assess comments themselves) so we can search
+ * for SEQUANT_PHASE exec markers in non-assess comments.
+ */
+export declare function detectChurn(priors: IssueComment[], allComments: IssueComment[]): ChurnResult;
+/**
+ * Decide whether to prompt the user before posting a new assess comment
+ * that conflicts with the most recent prior recommendation.
+ *
+ * Prompts only when:
+ *   - A prior action exists, AND
+ *   - The prior action is PROCEED or REWRITE (the "do work" actions
+ *     where flipping to PARK/CLOSE/etc. needs explicit confirmation), AND
+ *   - The new action differs from the prior.
+ *
+ * Skips the prompt for prior CLOSE/PARK/CLARIFY/MERGE — flipping
+ * away from those is rarely "wrong" and the prompt would just be noise.
+ */
+export declare function shouldPromptOnConflict(priorAction: AssessAction | undefined, newAction: AssessAction | undefined): boolean;

package/dist/src/lib/assess-comment-parser.js

@@ -70,6 +70,11 @@ const HTML_MARKER_PATTERN = /<!--\s*(?:assess|solve):(\w[\w-]*)=([\w,.-]*)\s*-->
  * Pattern to extract assess-specific HTML markers (takes precedence)
  */
 const ASSESS_HTML_MARKER_PATTERN = /<!--\s*assess:(\w[\w-]*)=([\w,.-]*)\s*-->/g;
+/**
+ * Non-global pattern for `.test()` checks. Matches any assess/solve action
+ * marker — the durable contract written by /assess regardless of prose format.
+ */
+const ASSESS_ACTION_MARKER_PATTERN = /<!--\s*(?:assess|solve):action=[\w-]+\s*-->/;
 /**
  * Pattern to extract issue numbers from header
  * Matches: "## Solve Workflow for Issues: 123, 456" or "#123"
@@ -88,10 +93,17 @@ const VALID_ACTIONS = [
 ];
 // ─── Detection Functions ────────────────────────────────────────────────────
 /**
- * Check if a comment is an assess command output (new format)
+ * Check if a comment is an assess command output (new format).
+ *
+ * Matches either prose markers (e.g., "## Assess Analysis") or the durable
+ * HTML action marker `<!-- assess:action=... -->` written by every /assess
+ * comment regardless of prose format. The HTML marker is the contract;
+ * prose can change.
  */
 export function isAssessComment(body) {
-    return ALL_MARKERS.some((marker) => body.includes(marker));
+    if (ALL_MARKERS.some((marker) => body.includes(marker)))
+        return true;
+    return ASSESS_ACTION_MARKER_PATTERN.test(body);
 }
 /**
  * Check if a comment is a solve command output (legacy format)
@@ -111,6 +123,16 @@ export function findAssessComment(comments) {
     }
     return null;
 }
+/**
+ * Find every assess/solve comment in chronological order (oldest first).
+ *
+ * Preserves the input order of `comments`, which is the order GitHub returns
+ * them (chronological). Callers that need the most recent comment should
+ * read the last element.
+ */
+export function findAllAssessComments(comments) {
+    return comments.filter((c) => isAssessComment(c.body));
+}
 /**
  * Find the most recent solve comment from a list of comments
  * @deprecated Use findAssessComment instead
@@ -342,3 +364,103 @@ export function assessCoversIssue(workflow, issueNumber) {
 export function solveCoversIssue(workflow, issueNumber) {
     return assessCoversIssue(workflow, issueNumber);
 }
+// ─── Prior-Assessment Detection ─────────────────────────────────────────────
+/**
+ * Pattern matching exec phase markers in any comment.
+ * Used by detectChurn to differentiate "no execution" churn from
+ * legitimate re-assessment after exec.
+ */
+const EXEC_PHASE_MARKER_PATTERN = /<!--\s*SEQUANT_PHASE:\s*\{[^}]*"phase"\s*:\s*"exec"[^}]*\}\s*-->/;
+/**
+ * Format a comment's createdAt timestamp as YYYY-MM-DD.
+ * Falls back to the raw value when missing or unparseable so output
+ * still says something useful.
+ */
+function formatAssessDate(createdAt) {
+    if (!createdAt)
+        return "unknown date";
+    const parsed = new Date(createdAt);
+    if (isNaN(parsed.getTime()))
+        return createdAt;
+    return parsed.toISOString().slice(0, 10);
+}
+/**
+ * Build a one-line supersession header for a new assess comment.
+ *
+ * Format:
+ * - 0 priors → null (caller omits the header entirely)
+ * - 1 prior  → `Supersedes prior assess from <date> (<action>)`
+ * - ≥2 priors → `Supersedes N prior assessments (most recent: <date>)`
+ *
+ * Priors must be passed in chronological order (oldest first), matching
+ * the output of findAllAssessComments.
+ */
+export function buildSupersessionHeader(priors) {
+    if (priors.length === 0)
+        return null;
+    const mostRecent = priors[priors.length - 1];
+    const date = formatAssessDate(mostRecent.createdAt);
+    if (priors.length === 1) {
+        const workflow = parseAssessWorkflow(mostRecent.body);
+        const action = workflow.action ?? "unknown";
+        return `Supersedes prior assess from ${date} (${action})`;
+    }
+    return `Supersedes ${priors.length} prior assessments (most recent: ${date})`;
+}
+/**
+ * Detect re-assessment churn — repeated /assess invocations without
+ * an intervening exec phase. Fires only when ≥3 priors exist and no
+ * exec phase marker appears in any comment dated after the first prior.
+ *
+ * `allComments` should be the full comment list from the issue
+ * (including the prior assess comments themselves) so we can search
+ * for SEQUANT_PHASE exec markers in non-assess comments.
+ */
+export function detectChurn(priors, allComments) {
+    const count = priors.length;
+    if (count < 3) {
+        return { isChurn: false, count };
+    }
+    const firstPrior = priors[0];
+    const firstDate = formatAssessDate(firstPrior.createdAt);
+    const firstTimestamp = firstPrior.createdAt
+        ? new Date(firstPrior.createdAt).getTime()
+        : NaN;
+    const hasExecAfterFirst = allComments.some((c) => {
+        if (!EXEC_PHASE_MARKER_PATTERN.test(c.body))
+            return false;
+        if (!Number.isFinite(firstTimestamp))
+            return true;
+        if (!c.createdAt)
+            return true;
+        const ts = new Date(c.createdAt).getTime();
+        if (isNaN(ts))
+            return true;
+        return ts >= firstTimestamp;
+    });
+    return {
+        isChurn: !hasExecAfterFirst,
+        count,
+        firstDate,
+    };
+}
+/**
+ * Decide whether to prompt the user before posting a new assess comment
+ * that conflicts with the most recent prior recommendation.
+ *
+ * Prompts only when:
+ *   - A prior action exists, AND
+ *   - The prior action is PROCEED or REWRITE (the "do work" actions
+ *     where flipping to PARK/CLOSE/etc. needs explicit confirmation), AND
+ *   - The new action differs from the prior.
+ *
+ * Skips the prompt for prior CLOSE/PARK/CLARIFY/MERGE — flipping
+ * away from those is rarely "wrong" and the prompt would just be noise.
+ */
+export function shouldPromptOnConflict(priorAction, newAction) {
+    if (!priorAction || !newAction)
+        return false;
+    if (priorAction === newAction)
+        return false;
+    return priorAction === "PROCEED" || priorAction === "REWRITE";
+}

package/dist/src/lib/cli-ui/format.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared formatting helpers used by run-renderer and friends.
+ *
+ * Lives in cli-ui/ so renderer and heartbeat can share without depending on
+ * the legacy phase-spinner module.
+ */
+/**
+ * Format elapsed time in human-readable form.
+ *
+ * @example
+ *   formatElapsedTime(5)       // "5s"
+ *   formatElapsedTime(75)      // "1m 15s"
+ *   formatElapsedTime(3725)    // "1h 2m"
+ */
+export declare function formatElapsedTime(seconds: number): string;
+/**
+ * Format a wall-clock timestamp as `HH:MM:SS`. Used by the non-TTY renderer.
+ */
+export declare function formatTimestamp(date: Date): string;

package/dist/src/lib/cli-ui/format.js

@@ -0,0 +1,34 @@
+/**
+ * Shared formatting helpers used by run-renderer and friends.
+ *
+ * Lives in cli-ui/ so renderer and heartbeat can share without depending on
+ * the legacy phase-spinner module.
+ */
+/**
+ * Format elapsed time in human-readable form.
+ *
+ * @example
+ *   formatElapsedTime(5)       // "5s"
+ *   formatElapsedTime(75)      // "1m 15s"
+ *   formatElapsedTime(3725)    // "1h 2m"
+ */
+export function formatElapsedTime(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600) {
+        const m = Math.floor(s / 60);
+        const r = s % 60;
+        return r > 0 ? `${m}m ${r}s` : `${m}m`;
+    }
+    const h = Math.floor(s / 3600);
+    const r = Math.floor((s % 3600) / 60);
+    return r > 0 ? `${h}h ${r}m` : `${h}h`;
+}
+/**
+ * Format a wall-clock timestamp as `HH:MM:SS`. Used by the non-TTY renderer.
+ */
+export function formatTimestamp(date) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}