sequant 2.9.0 → 2.11.0

package/dist/src/commands/status.js

@@ -2,6 +2,8 @@
  * sequant status - Show version, configuration, and workflow state
  */
 import chalk from "chalk";
+import { formatResetTime } from "../lib/errors.js";
+import { MAX_RESUME_REENTRIES } from "../lib/workflow/state-schema.js";
 import { ui, colors } from "../lib/cli-ui.js";
 import { getManifest, getPackageVersion } from "../lib/manifest.js";
 import { fileExists } from "../lib/fs.js";
@@ -102,8 +104,12 @@ function getPhaseSymbol(phaseState) {
 }
 /**
  * Format a single issue state for display
+ *
+ * @internal Exported for testing only (#892: the windowHalt/autoWait pause
+ * lines are display contract — a halted issue must read as resumable, not as
+ * a bare failure).
  */
-function formatIssueState(issue) {
+export function formatIssueState(issue) {
     const lines = [];
     // Issue header
     lines.push(chalk.bold(`  #${issue.number}: ${issue.title.substring(0, 50)}${issue.title.length > 50 ? "..." : ""}`));
@@ -128,6 +134,16 @@ function formatIssueState(issue) {
         .join(" ");
     lines.push(`    Phases: ${phaseProgress}`);
     lines.push(`            ${phases.map((p) => p.charAt(0).toUpperCase()).join(" ")}`);
+    // #860: an auto-waiting issue is paused on purpose, not stalled — name the
+    // wake time so a multi-hour rate-limit pause is distinguishable from a hang.
+    if (issue.autoWait) {
+        lines.push(chalk.yellow(`    ⏸ Auto-wait: ${issue.autoWait.phase} paused — resuming at ${formatResetTime(new Date(issue.autoWait.wakeAt).getTime())}`));
+    }
+    // #892: a window-halted issue exited cleanly (lock released) and is waiting
+    // for `sequant resume` — show the resume time instead of a bare failure.
+    if (issue.windowHalt) {
+        lines.push(chalk.yellow(`    ⏸ Halted: ${issue.windowHalt.phase} hit a rate-limit window — resumable at ${formatResetTime(new Date(issue.windowHalt.resumeAt).getTime())} via \`sequant resume\` (re-entries ${issue.windowHalt.reentries}/${MAX_RESUME_REENTRIES})`));
+    }
     // PR info
     if (issue.pr) {
         lines.push(chalk.gray(`    PR: #${issue.pr.number} ${issue.pr.url}`));
@@ -419,6 +435,7 @@ async function displayIssueState(options) {
         else {
             console.log(chalk.red(`\nError reading state: ${error}`));
         }
+        process.exitCode = 1;
     }
 }
 /**
@@ -431,6 +448,8 @@ async function handleRebuild(options) {
     const result = await rebuildStateFromLogs({ verbose: !options.json });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (result.success) {
@@ -443,6 +462,7 @@ async function handleRebuild(options) {
     }
     else {
         console.log(chalk.red(`✗ Rebuild failed: ${result.error}`));
+        process.exitCode = 1;
     }
 }
 /**
@@ -470,6 +490,8 @@ async function handleCleanup(options) {
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (result.success) {
@@ -511,5 +533,6 @@ async function handleCleanup(options) {
     }
     else {
         console.log(chalk.red(`✗ Cleanup failed: ${result.error}`));
+        process.exitCode = 1;
     }
 }

package/dist/src/commands/sync.js

@@ -8,8 +8,10 @@ import chalk from "chalk";
 import { join } from "path";
 import { createHash } from "crypto";
 import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest.js";
-import { copyTemplates, computeTemplateChanges, listTemplateFiles, getTemplatesDir, } from "../lib/templates.js";
+import { copyTemplates, computeTemplateChanges, listTemplateFiles, getTemplatesDir, assertTemplatesDirExists, isCustomizableFile, } from "../lib/templates.js";
 import { getConfig } from "../lib/config.js";
+import { resolveCliInvocation } from "../lib/version-check.js";
+import { syncSequantMcpPin } from "../lib/mcp-config.js";
 import { writeFile, readFile, fileExists, getFileStats } from "../lib/fs.js";
 import { generateAgentsMd, writeAgentsMd, AGENTS_MD_PATH, } from "../lib/agents-md.js";
 import { getProjectName } from "../lib/project-name.js";
@@ -195,6 +197,18 @@ export async function syncCommand(options = {}) {
         process.exitCode = 1;
         return;
     }
+    // Fail loudly on a missing templates root before anything reads or writes.
+    // This must precede the version fast path below: that path diffs against the
+    // same (missing) directory, sees no drift, and reports "already up to date"
+    // over an empty tree — the second-run trap in #822.
+    try {
+        await assertTemplatesDirExists();
+    }
+    catch (error) {
+        console.log(chalk.red(`❌ ${error.message}`));
+        process.exitCode = 1;
+        return;
+    }
     const packageVersion = getPackageVersion();
     const skillsVersion = await getSkillsVersion();
     if (!quiet) {
@@ -205,6 +219,18 @@ export async function syncCommand(options = {}) {
     // Get config tokens for template processing
     const config = await getConfig();
     const tokens = config?.tokens || {};
+    // Re-pin the project .mcp.json MCP server to the installed version (#793).
+    // `syncSequantMcpPin`'s contract has always named this the `update`/`sync`
+    // path, but only `update` ever called it, so a `sync` left the pin stale.
+    // Placed here for the same reason update.ts states: it must precede the
+    // "already up to date" fast path below, because a version-only upgrade
+    // leaves every template byte-identical and returns early — and that is
+    // exactly the case where the pin most needs refreshing.
+    const mcpPin = syncSequantMcpPin(process.cwd(), { dryRun });
+    if (mcpPin.updated && !quiet) {
+        const verb = dryRun ? "Would update" : "Updated";
+        console.log(chalk.blue(`${verb} .mcp.json MCP pin: ${mcpPin.from} → ${mcpPin.to}`));
+    }
     // The version marker is only a fast-path hint — verify actual content before
     // claiming "up to date". On a version match we still diff bundled templates
     // against installed content (rendered with the same variables) so we never
@@ -233,25 +259,36 @@ export async function syncCommand(options = {}) {
     }
     // Preview path: report exactly what the apply would write, then stop without
     // mutating (#722). This branch is only reached when `force` is set or the
-    // version marker mismatches — i.e. the path that runs `copyTemplates(force:
-    // true)` and rewrites the whole tree. (A matching-version, non-force dry-run
-    // already returned at the report-only short-circuit above, which never
-    // mutates.) `copyTemplates` does NOT protect in-place customizations the way
-    // `update` does — the force copy overwrites them — so the preview counts
-    // `local-override` files alongside `new`/`modified`. Reporting only
-    // new+modified would under-report the write-set, the exact divergence #722
-    // is about.
+    // version marker mismatches — i.e. the path that runs `copyTemplates` and
+    // rewrites the whole tree. (A matching-version, non-force dry-run already
+    // returned at the report-only short-circuit above, which never mutates.)
+    //
+    // Since #814 the apply path PRESERVES in-place customizations (files in
+    // CUSTOMIZABLE_FILES) under a plain sync and only overwrites them under an
+    // explicit `--force`. The preview must mirror that split exactly, or it would
+    // re-introduce the dry-run/apply divergence #722 is about: partition the
+    // `local-override` set into preserved (plain sync) vs overwritten (--force,
+    // or a non-customizable `.local`-twin the tree copy still rewrites).
     if (dryRun) {
         const changes = await computeTemplateChanges(manifest.stack, tokens);
         const newFiles = changes.filter((c) => c.status === "new");
         const modifiedFiles = changes.filter((c) => c.status === "modified");
         const localOverrides = changes.filter((c) => c.status === "local-override");
-        const toWrite = [...newFiles, ...modifiedFiles, ...localOverrides];
+        const preservedOverrides = force
+            ? []
+            : localOverrides.filter((c) => isCustomizableFile(c.path));
+        const overwrittenOverrides = localOverrides.filter((c) => force || !isCustomizableFile(c.path));
+        const toWrite = [...newFiles, ...modifiedFiles, ...overwrittenOverrides];
         if (!quiet) {
             console.log(chalk.bold("Summary (dry-run):"));
             console.log(chalk.green(`  New files: ${newFiles.length}`));
             console.log(chalk.yellow(`  Modified: ${modifiedFiles.length}`));
-            console.log(chalk.blue(`  Local overrides (overwritten by sync): ${localOverrides.length}`));
+            if (preservedOverrides.length > 0) {
+                console.log(chalk.blue(`  Customizable (preserved): ${preservedOverrides.length}`));
+            }
+            if (overwrittenOverrides.length > 0) {
+                console.log(chalk.blue(`  Local overrides (overwritten): ${overwrittenOverrides.length}`));
+            }
             if (modifiedFiles.length > 0) {
                 console.log(chalk.bold("\nModified files:"));
                 for (const file of modifiedFiles) {
@@ -264,9 +301,15 @@ export async function syncCommand(options = {}) {
                     console.log(chalk.green(`  ${file.path}`));
                 }
             }
-            if (localOverrides.length > 0) {
-                console.log(chalk.bold("\nLocal overrides (will be overwritten by sync):"));
-                for (const file of localOverrides) {
+            if (preservedOverrides.length > 0) {
+                console.log(chalk.bold("\nCustomizable files (preserved — run `sync --force` to replace):"));
+                for (const file of preservedOverrides) {
+                    console.log(chalk.blue(`  ${file.path}`));
+                }
+            }
+            if (overwrittenOverrides.length > 0) {
+                console.log(chalk.bold("\nLocal overrides (will be overwritten):"));
+                for (const file of overwrittenOverrides) {
                     console.log(chalk.blue(`  ${file.path}`));
                 }
             }
@@ -286,14 +329,39 @@ export async function syncCommand(options = {}) {
         }
         return;
     }
-    // Copy templates with force to overwrite existing files
+    // Copy templates: always refresh the managed trees, but only overwrite
+    // user-owned CUSTOMIZABLE_FILES (e.g. the constitution) when the user
+    // explicitly passed --force. These are two distinct notions of "force" and
+    // conflating them is what silently ate the constitution (#814).
     const copyOptions = {
-        force: true, // Always overwrite when syncing
+        force: true, // Always overwrite the managed skills/agents/hooks trees
+        overwriteCustomizable: force, // Clobber user-owned files only on explicit --force
     };
+    // AC-3: under --force, announce which customizable files are about to be
+    // overwritten *before* writing them, so the destructive action is never
+    // silent. Reuse the diff path's `local-override` classification (the same
+    // set --dry-run reports), narrowed to CUSTOMIZABLE_FILES.
+    if (force && !quiet) {
+        const changes = await computeTemplateChanges(manifest.stack, tokens);
+        const overwrites = changes.filter((c) => c.status === "local-override" && isCustomizableFile(c.path));
+        if (overwrites.length > 0) {
+            console.log(chalk.yellow(`Overwriting ${overwrites.length} customizable file(s) (--force):`));
+            for (const file of overwrites) {
+                console.log(chalk.yellow(`  ${file.path}`));
+            }
+        }
+    }
     if (!quiet) {
         console.log(chalk.blue("Copying templates..."));
     }
-    await copyTemplates(manifest.stack, tokens, copyOptions);
+    const { preservedCustomizable } = await copyTemplates(manifest.stack, tokens, copyOptions);
+    // AC-4: on a plain sync, report each customizable file that was preserved so
+    // the apply path's output matches what --dry-run already promises (#722).
+    if (!quiet && preservedCustomizable.length > 0) {
+        for (const file of preservedCustomizable) {
+            console.log(chalk.blue(`  preserved: ${file} — run \`sync --force\` to replace`));
+        }
+    }
     // Update version markers
     await updateSkillsVersion();
     await updateManifest();
@@ -340,9 +408,12 @@ export async function syncCommand(options = {}) {
  */
 export async function checkAndWarnSkillsOutdated(status) {
     const { outdated, currentVersion, packageVersion, contentDrift } = status ?? (await areSkillsOutdated());
+    // Name the invocation that reaches *this* build rather than assuming the
+    // documented `npm install sequant` shape — see resolveCliInvocation.
+    const cli = resolveCliInvocation();
     if (outdated) {
         console.log(chalk.yellow(`\n!  Skills are outdated (${currentVersion || "unknown"} → ${packageVersion})`));
-        console.log(chalk.yellow("   Run: npx sequant sync\n"));
+        console.log(chalk.yellow(`   Run: ${cli} sync\n`));
         return true;
     }
     if (contentDrift > 0) {
@@ -350,7 +421,7 @@ export async function checkAndWarnSkillsOutdated(status) {
         // version is report-only (it won't copy), so point at the commands that
         // actually resolve in-place drift — `sync --force` or `update`.
         console.log(chalk.yellow(`\n!  Version current, but ${contentDrift} file(s) differ from bundled content`));
-        console.log(chalk.yellow("   Run: npx sequant sync --force (or npx sequant update)\n"));
+        console.log(chalk.yellow(`   Run: ${cli} sync --force (or ${cli} update)\n`));
         return true;
     }
     return false;

package/dist/src/commands/update.js

@@ -7,9 +7,11 @@ import { spawnSync } from "child_process";
 import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest.js";
 import { computeTemplateChanges } from "../lib/templates.js";
 import { getConfig, saveConfig } from "../lib/config.js";
-import { getStackConfig, PM_CONFIG, getPackageManagerCommands, } from "../lib/stacks.js";
+import { getStackConfig, PM_CONFIG, getPackageManagerCommands, resolvePackageManager, } from "../lib/stacks.js";
 import { writeFile } from "../lib/fs.js";
+import { chmod } from "fs/promises";
 import { isStdinTTY, isCI, getNonInteractiveReason } from "../lib/tty.js";
+import { syncSequantMcpPin } from "../lib/mcp-config.js";
 /**
  * True when `update` must not prompt: stdin is not a terminal (piped input) or
  * we are running in a recognized CI environment. CI is checked explicitly
@@ -41,8 +43,18 @@ export async function updateCommand(options) {
     const manifest = await getManifest();
     if (!manifest) {
         console.log(chalk.red("❌ Sequant is not initialized. Run `sequant init` first."));
+        process.exitCode = 1;
         return;
     }
+    // Resolved once for the whole command. The manifest's packageManager is a
+    // snapshot taken at `sequant init`, so it is absent on pre-1.3.0 installs —
+    // exactly the population the PM_RUN backfill below exists to serve. The
+    // three sites that used to spell this `(manifest.packageManager as keyof
+    // typeof PM_CONFIG) || "npm"` therefore assumed npm for those installs, and
+    // wrote an npm PM_RUN token into a pnpm/yarn/bun project's config (#870).
+    // The root is the cwd because `update` operates on the project in place,
+    // the same directory `getManifest` and `syncSequantMcpPin` read.
+    const pm = resolvePackageManager(manifest.packageManager, process.cwd());
     const packageVersion = getPackageVersion();
     console.log(chalk.gray(`Current version: ${manifest.version}`));
     console.log(chalk.gray(`Stack: ${manifest.stack}`));
@@ -64,7 +76,6 @@ export async function updateCommand(options) {
         console.log(chalk.gray(`Dev URL: ${tokens.DEV_URL || "(not set)"}\n`));
         // Add PM_RUN if missing (for existing installs before v1.3.0)
         if (!tokens.PM_RUN) {
-            const pm = manifest.packageManager || "npm";
             const pmConfig = getPackageManagerCommands(pm);
             tokens.PM_RUN = pmConfig.run;
             config.tokens = tokens;
@@ -78,7 +89,6 @@ export async function updateCommand(options) {
         const stackConfig = getStackConfig(manifest.stack);
         const defaultDevUrl = stackConfig.devUrl;
         // Get package manager run command
-        const pm = manifest.packageManager || "npm";
         const pmConfig = getPackageManagerCommands(pm);
         if (options.force || options.yes) {
             tokens = { DEV_URL: defaultDevUrl, PM_RUN: pmConfig.run };
@@ -116,6 +126,16 @@ export async function updateCommand(options) {
             console.log(chalk.green("✔ Configuration saved\n"));
         }
     }
+    // Re-pin the project .mcp.json MCP server to the installed version (#793).
+    // Independent of template changes: a version-only upgrade leaves every
+    // template unchanged (so the flow would short-circuit at "Everything is up to
+    // date" below) but should still refresh the pin so the MCP server tracks the
+    // release the user just updated to. Runs here, before that short-circuit.
+    const mcpPin = syncSequantMcpPin(process.cwd(), { dryRun: options.dryRun });
+    if (mcpPin.updated) {
+        const verb = options.dryRun ? "Would update" : "Updated";
+        console.log(chalk.blue(`${verb} .mcp.json MCP pin: ${mcpPin.from} → ${mcpPin.to}`));
+    }
     // Compute changes using the shared, variable-aware comparison.
     // Templates are rendered (PROJECT_NAME, STACK_NOTES, etc.) before diffing,
     // and in-place-customizable files (constitution) are protected as overrides.
@@ -202,6 +222,11 @@ export async function updateCommand(options) {
     let updated = 0;
     for (const file of applySet) {
         await writeFile(file.path, file.rendered);
+        // Shell scripts (hooks, scripts/dev) need the exec bit, matching the
+        // copyTemplates write path.
+        if (file.path.endsWith(".sh")) {
+            await chmod(file.path, 0o755);
+        }
         updated++;
     }
     // Update manifest
@@ -210,8 +235,6 @@ export async function updateCommand(options) {
     // Check if package.json was updated and run install
     const packageJsonUpdated = applySet.some((f) => f.path === "package.json" || f.path.endsWith("/package.json"));
     if (packageJsonUpdated) {
-        // Use detected package manager or default to npm
-        const pm = manifest.packageManager || "npm";
         const pmConfig = PM_CONFIG[pm];
         console.log(chalk.blue(`\npackage.json updated, running ${pmConfig.install}...`));
         const [cmd, ...args] = pmConfig.install.split(" ");

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

@@ -0,0 +1,31 @@
+/**
+ * `sequant worktree` — repo-scoped worktree resolution for skill bodies (#899).
+ *
+ * `/fullsolve` uses `resolve` to turn an issue number into a real absolute
+ * path before exporting `SEQUANT_WORKTREE`; `/exec` uses `verify` to refuse a
+ * path that does not exist or belongs to another repository. Both fail closed:
+ * a non-zero exit means the caller must halt, not continue where it stands.
+ */
+export interface WorktreeResolveOptions {
+    json?: boolean;
+}
+export interface WorktreeVerifyOptions {
+    issue?: string;
+    json?: boolean;
+}
+/**
+ * `sequant worktree resolve <issue>` — print the absolute path of this
+ * repository's worktree for an issue.
+ *
+ * On success the path is the *only* thing written to stdout, so callers can
+ * capture it with `WT="$(sequant worktree resolve 123)"`. Everything else goes
+ * to stderr.
+ */
+export declare function worktreeResolveCommand(issueArg: string, options?: WorktreeResolveOptions): Promise<void>;
+/**
+ * `sequant worktree verify <path>` — confirm a path is a worktree of this
+ * repository (and, with `--issue`, that it belongs to that issue).
+ *
+ * Exit 1 with a named error is the signal for `/exec` to halt.
+ */
+export declare function worktreeVerifyCommand(pathArg: string, options?: WorktreeVerifyOptions): Promise<void>;

package/dist/src/commands/worktree.js

@@ -0,0 +1,95 @@
+/**
+ * `sequant worktree` — repo-scoped worktree resolution for skill bodies (#899).
+ *
+ * `/fullsolve` uses `resolve` to turn an issue number into a real absolute
+ * path before exporting `SEQUANT_WORKTREE`; `/exec` uses `verify` to refuse a
+ * path that does not exist or belongs to another repository. Both fail closed:
+ * a non-zero exit means the caller must halt, not continue where it stands.
+ */
+import chalk from "chalk";
+import { resolveIssueWorktree, verifyWorktreePath, } from "../lib/workflow/worktree-resolver.js";
+function parseIssue(arg) {
+    const issue = Number.parseInt(arg, 10);
+    if (!Number.isInteger(issue) || issue <= 0) {
+        console.error(chalk.red(`Invalid issue number: ${arg}`));
+        process.exitCode = 2;
+        return null;
+    }
+    return issue;
+}
+/**
+ * `sequant worktree resolve <issue>` — print the absolute path of this
+ * repository's worktree for an issue.
+ *
+ * On success the path is the *only* thing written to stdout, so callers can
+ * capture it with `WT="$(sequant worktree resolve 123)"`. Everything else goes
+ * to stderr.
+ */
+export async function worktreeResolveCommand(issueArg, options = {}) {
+    const issue = parseIssue(issueArg);
+    if (issue === null)
+        return;
+    const result = resolveIssueWorktree(issue);
+    if (!result.ok) {
+        process.exitCode = 1;
+        if (options.json) {
+            console.error(JSON.stringify({
+                issue,
+                ok: false,
+                error: result.error,
+                message: result.message,
+                candidates: result.candidates,
+            }));
+        }
+        else {
+            console.error(chalk.red(result.message));
+        }
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            issue,
+            ok: true,
+            path: result.path,
+            branch: result.branch,
+        }));
+        return;
+    }
+    // Bare path only — this is consumed by `$(...)` in skill bodies.
+    console.log(result.path);
+}
+/**
+ * `sequant worktree verify <path>` — confirm a path is a worktree of this
+ * repository (and, with `--issue`, that it belongs to that issue).
+ *
+ * Exit 1 with a named error is the signal for `/exec` to halt.
+ */
+export async function worktreeVerifyCommand(pathArg, options = {}) {
+    let issue;
+    if (options.issue !== undefined) {
+        const parsed = parseIssue(options.issue);
+        if (parsed === null)
+            return;
+        issue = parsed;
+    }
+    const result = verifyWorktreePath(pathArg, { issue });
+    if (!result.ok) {
+        process.exitCode = 1;
+        if (options.json) {
+            console.error(JSON.stringify({
+                ok: false,
+                error: result.error,
+                message: result.message,
+            }));
+        }
+        else {
+            console.error(chalk.red(result.message));
+        }
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, path: result.path, branch: result.branch }));
+        return;
+    }
+    console.log(chalk.green(`✓ ${result.path} (${result.branch})`));
+}

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

@@ -6,6 +6,12 @@
  * Also supports alternate formats: `- [ ] **B2:** Description`
  * And bold-wrapped format: `- [ ] **AC-1: Description**`
  *
+ * Bare checkbox items (`- [ ] Some requirement`, no ID prefix) are also
+ * honored, but ONLY under an explicit `## Acceptance Criteria` heading, where
+ * they receive synthesized stable IDs. Human-authored issues rarely prefix
+ * their ACs with IDs, so without this every hand-written issue parsed to zero
+ * ACs — blinding every downstream AC consumer (#850).
+ *
  * @example
  * ```typescript
  * import { parseAcceptanceCriteria } from './ac-parser';
@@ -39,8 +45,16 @@ export declare function inferVerificationMethod(description: string): ACVerifica
  * - `- [ ] **AC-1:** Description`
  * - `- [ ] **B2:** Description`
  * - `- [ ] **AC-1: Description**` (bold wraps ID + description)
+ * - `- [ ] **AC-1** Description` (bold ID, no colon)
+ * - `- [ ] **AC-1**: Description` (colon outside the bold)
  * - `- [ ] AC-1: Description`
  *
+ * Bare checkbox items without an ID prefix (`- [ ] Some requirement`) are also
+ * parsed, but ONLY under an explicit `## Acceptance Criteria` heading, where
+ * they receive synthesized stable IDs (`AC-1`, `AC-2`, ...). This keeps
+ * unrelated checklists elsewhere in the body (Open Questions, Test Plan) from
+ * being misread as ACs, while letting ordinary human-written issues parse.
+ *
  * @param issueBody - The full GitHub issue body markdown
  * @returns Array of parsed acceptance criteria
  */

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

@@ -6,6 +6,12 @@
  * Also supports alternate formats: `- [ ] **B2:** Description`
  * And bold-wrapped format: `- [ ] **AC-1: Description**`
  *
+ * Bare checkbox items (`- [ ] Some requirement`, no ID prefix) are also
+ * honored, but ONLY under an explicit `## Acceptance Criteria` heading, where
+ * they receive synthesized stable IDs. Human-authored issues rarely prefix
+ * their ACs with IDs, so without this every hand-written issue parsed to zero
+ * ACs — blinding every downstream AC consumer (#850).
+ *
  * @example
  * ```typescript
  * import { parseAcceptanceCriteria } from './ac-parser';
@@ -33,6 +39,9 @@ import { createAcceptanceCriterion, createAcceptanceCriteria, } from "./workflow
  * - `- [ ] **B2:** Description`
  * - `- [ ] **AC1:** Description`
  * - `- [ ] **AC-1: Description**` (bold wraps ID + description)
+ * - `- [ ] **AC-1** Description` (bold ID, no colon)
+ * - `- [ ] **AC-1**: Description` (colon outside the bold)
+ * - `- [ ] AC-1: Description`
  */
 const AC_PATTERNS = [
     // Pattern 1: `- [ ] **AC-1:** Description` or `- [x] **AC-1:** Description`
@@ -43,7 +52,41 @@ const AC_PATTERNS = [
     /^-\s*\[[x\s]\]\s*\*\*([A-Za-z]+-?\d+):\s*(.+?)\*\*\s*(.*)$/gim,
     // Pattern 4: `- [ ] AC-1: Description` (no bold)
     /^-\s*\[[x\s]\]\s*([A-Za-z]+-?\d+):\s*(.+)$/gim,
+    // Pattern 5: `- [ ] **AC-1** Description` / `- [ ] **AC-1**: Description` (#808)
+    //
+    // The colon-less form is a very common authoring style, and before this
+    // pattern existed it matched nothing at all — an issue written this way
+    // parsed as ZERO acceptance criteria, silently, with no warning anywhere
+    // downstream (#803's five ACs were written exactly like this).
+    //
+    // The trailing `:?` also absorbs a colon placed *outside* the bold, which
+    // would otherwise land in the description as a leading ": ".
+    //
+    // Deliberately requires the bold markers. A bare `- [ ] AC1 something` is
+    // ambiguous against ordinary checklist prose, so widening that far would
+    // trade a silent miss for silent false positives. The `\d+` at the end of
+    // the ID keeps non-identifier bold labels (`**Note**`, `**Verify**`) out.
+    /^-\s*\[[x\s]\]\s*\*\*([A-Za-z]+-?\d+)\*\*:?\s*(.+)$/gim,
 ];
+/**
+ * Matches an `## Acceptance Criteria` heading (any level, case-insensitive).
+ *
+ * Real issues vary the casing — #703 uses `## Acceptance criteria` (lowercase
+ * "criteria") — so the match must be case-insensitive. The trailing `\b` lets
+ * a suffix follow ("Acceptance Criteria (v2)") without demanding an exact end.
+ */
+const AC_HEADING_RE = /^#{1,6}\s+acceptance\s+criteria\b/i;
+/**
+ * Matches any markdown ATX heading. Used to detect when the AC section ends —
+ * the next heading of any level closes it, mirroring `parseNonGoals` in
+ * `ready-gate.ts`.
+ */
+const HEADING_RE = /^#{1,6}\s+/;
+/**
+ * Matches a bare checkbox item with no ID prefix: `- [ ] Some requirement`.
+ * Honored only inside the AC section (see {@link parseAcceptanceCriteria}).
+ */
+const BARE_CHECKBOX_RE = /^-\s*\[[x\s]\]\s*(.+)$/i;
 /**
  * Keywords that suggest verification method
  */
@@ -122,22 +165,73 @@ function parseACLine(line) {
  * - `- [ ] **AC-1:** Description`
  * - `- [ ] **B2:** Description`
  * - `- [ ] **AC-1: Description**` (bold wraps ID + description)
+ * - `- [ ] **AC-1** Description` (bold ID, no colon)
+ * - `- [ ] **AC-1**: Description` (colon outside the bold)
  * - `- [ ] AC-1: Description`
  *
+ * Bare checkbox items without an ID prefix (`- [ ] Some requirement`) are also
+ * parsed, but ONLY under an explicit `## Acceptance Criteria` heading, where
+ * they receive synthesized stable IDs (`AC-1`, `AC-2`, ...). This keeps
+ * unrelated checklists elsewhere in the body (Open Questions, Test Plan) from
+ * being misread as ACs, while letting ordinary human-written issues parse.
+ *
  * @param issueBody - The full GitHub issue body markdown
  * @returns Array of parsed acceptance criteria
  */
 export function parseAcceptanceCriteria(issueBody) {
     const criteria = [];
     const seenIds = new Set();
-    // Split into lines and process each
+    const push = (id, description) => {
+        if (seenIds.has(id))
+            return;
+        seenIds.add(id);
+        criteria.push(createAcceptanceCriterion(id, description, inferVerificationMethod(description)));
+    };
+    // Split into lines and process each. `inAcSection` tracks whether the
+    // current line falls under an `## Acceptance Criteria` heading; it toggles on
+    // every heading and closes at the next heading of any level (same boundary
+    // rule as `parseNonGoals` in ready-gate.ts). `bareCount` numbers synthesized
+    // IDs for bare checkboxes in appearance order.
     const lines = issueBody.split("\n");
+    let inAcSection = false;
+    let bareCount = 0;
+    // Pre-scan for explicit IDs anywhere in the body. Synthesis must skip IDs
+    // owned by explicit markers even when the marker appears on a LATER line —
+    // otherwise a bare checkbox listed before `**AC-1:**` under the same heading
+    // 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);
-        if (parsed && !seenIds.has(parsed.id)) {
-            seenIds.add(parsed.id);
-            const verificationMethod = inferVerificationMethod(parsed.description);
-            criteria.push(createAcceptanceCriterion(parsed.id, parsed.description, verificationMethod));
+        if (parsed)
+            explicitIds.add(parsed.id);
+    }
+    for (const line of lines) {
+        if (HEADING_RE.test(line)) {
+            inAcSection = AC_HEADING_RE.test(line);
+            continue;
+        }
+        // Existing ID-prefixed patterns run on every line, regardless of section,
+        // so previously-parsable issues are unaffected (AC-4).
+        const parsed = parseACLine(line);
+        if (parsed) {
+            push(parsed.id, parsed.description);
+            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) {
+                // 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.
+                let id;
+                do {
+                    id = `AC-${++bareCount}`;
+                } while (seenIds.has(id) || explicitIds.has(id));
+                push(id, description);
+            }
         }
     }
     return criteria;

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

@@ -0,0 +1,10 @@
+/**
+ * Deterministic rendering for `/assess` output (#823).
+ *
+ * `types.ts` owns the contract, `renderer.ts` owns the geometry. Neither touches
+ * TTY state, ANSI, or I/O — see the header comment in `renderer.ts` for why that
+ * rules out the `cli-ui.ts` helpers.
+ */
+export { AssessActionSchema, AssessChainSchema, AssessCleanupSchema, AssessCommandSchema, AssessFlagSchema, AssessIssueSchema, AssessResultSchema, AssessResultValidationError, AssessWarningSchema, parseAssessResult, } from "./types.js";
+export type { AssessAction, AssessChain, AssessCleanup, AssessCommand, AssessFlag, AssessIssue, AssessResult, AssessWarning, } from "./types.js";
+export { GEOMETRY, render, renderBatch, renderSingle } from "./renderer.js";