@specship/specship-win32-arm64 0.25.0 → 0.29.0

package/lib/dist/bin/specship.js

@@ -268,9 +268,10 @@ if (nodeMajor >= 25) {
 // Enforce the supported Node floor. `engines` in package.json only *warns* on
 // install (unless engine-strict), so hard-block here to actually keep users off
 // unsupported versions. Mirrors the 25+ block above. See package.json `engines`.
-if (nodeMajor < node_version_check_1.MIN_NODE_MAJOR) {
+const nodeFloor = (0, node_version_check_1.nodeFloorDecision)(nodeVersion);
+if (nodeFloor !== 'ok') {
     process.stderr.write((0, node_version_check_1.buildNodeTooOldBanner)(nodeVersion) + '\n');
-    if (!process.env.SPECSHIP_ALLOW_UNSAFE_NODE) {
+    if (nodeFloor === 'block') {
         process.exit(1);
     }
     // Override active — banner shown for visibility, continuing.
@@ -862,6 +863,45 @@ function main() {
             catch {
                 /* surfacing is best-effort */
             }
+            // Stale external facts (REQ-KNOW-002): one line when any dependency
+            // moved past the version a fact was verified against. Local
+            // node_modules only on this path — no `npm root -g` spawn at session start.
+            try {
+                const { findStaleExternalFacts } = require('../knowledge/stale');
+                const stale = findStaleExternalFacts(projectPath, { globalRoot: () => null }).stale;
+                if (stale.length > 0) {
+                    console.log(`⚠ ${stale.length} external fact(s) stale (dependency changed since verified) — review with: specship knowledge stale`);
+                }
+            }
+            catch {
+                /* surfacing is best-effort */
+            }
+            // Pipeline pulse (REQ-PIPETRUST-007): one line per failing item from
+            // the CACHED pulse only — no network on this path; silent when healthy.
+            try {
+                const { readCachedPulse, formatPulseLines } = require('../pulse/pulse');
+                const cached = readCachedPulse(projectPath);
+                if (cached) {
+                    for (const line of formatPulseLines(cached.items))
+                        console.log(line);
+                }
+                // Keep the cache warm without blocking the session: when it is missing
+                // or older than six hours, refresh it in a detached child (bounded by
+                // pulse's own time budget). This session prints what was cached; the
+                // next one sees the refreshed result.
+                const SIX_HOURS = 6 * 60 * 60 * 1000;
+                if ((!cached || Date.now() - cached.checkedAt > SIX_HOURS) && !process.env.SPECSHIP_NO_PULSE) {
+                    const { spawn } = require('child_process');
+                    const child = spawn(process.execPath, [process.argv[1], 'pulse', projectPath, '--refresh', '--json'], {
+                        detached: true,
+                        stdio: 'ignore',
+                    });
+                    child.unref();
+                }
+            }
+            catch {
+                /* surfacing is best-effort */
+            }
         };
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
@@ -893,12 +933,32 @@ function main() {
                     /* summary is best-effort */
                 }
             };
+            // Guarded auto-learn sweep (REQ-ALEARN-004): cooldown-bounded, opt-out
+            // via reflect.autoSweep=false, and NEVER allowed to fail the sync (A3).
+            const runAutoSweep = async (instance) => {
+                try {
+                    const { loadReflectConfig, shouldAutoSweep, recordAutoSweep } = await Promise.resolve().then(() => __importStar(require('../reflect/auto-sweep')));
+                    const cfg = loadReflectConfig(projectPath);
+                    if (!shouldAutoSweep(projectPath, Date.now(), cfg))
+                        return;
+                    recordAutoSweep(projectPath, Date.now());
+                    const { notify } = instance.reflectSweep();
+                    const { learnedNotice } = await Promise.resolve().then(() => __importStar(require('../reflect/cli')));
+                    for (const p of notify) {
+                        console.log(learnedNotice(p.title));
+                    }
+                }
+                catch {
+                    /* a sweep failure never blocks a sync (REQ-ALEARN-004.A3) */
+                }
+            };
             if (options.quiet) {
                 const result = await cg.sync();
                 pushDriftNotices(result);
                 await pushJiraDriftComments(cg, result);
                 await pushJiraAutoPublish(result);
                 pushDriftSummary(cg);
+                await runAutoSweep(cg);
                 cg.destroy();
                 return;
             }
@@ -941,6 +1001,7 @@ function main() {
             await pushJiraDriftComments(cg, result);
             await pushJiraAutoPublish(result);
             pushDriftSummary(cg);
+            await runAutoSweep(cg);
             clack.outro('Done');
             cg.destroy();
         }
@@ -1358,15 +1419,30 @@ function main() {
      * Run a reflection pass over the ingested Claude Code transcripts and print the
      * self-improvement proposals it surfaces (REQ-REFLECT-006.A1). Headless — no
      * dashboard required. With no usable transcript history, prints an empty state.
+     *
+     * Review verbs (REQ-AUDFIX-002): `specship reflect apply <hash> [--yes]`,
+     * `specship reflect undo <hash>`, `specship reflect dismiss <hash>`. The first
+     * positional is a verb when it is exactly apply/undo/dismiss, otherwise the
+     * project path (so `specship reflect` and `specship reflect <path>` are
+     * unchanged); verb mode takes its project from --path (default: cwd).
      */
     program
-        .command('reflect [path]')
-        .description('Mine ingested transcripts for self-improvement proposals (memory rules, skills, hooks)')
+        .command('reflect [path-or-verb] [hash]')
+        .description('Mine ingested transcripts for self-improvement proposals; review them with apply <hash> [--yes] / undo <hash> / dismiss <hash>')
         .option('-j, --json', 'Output as JSON')
+        .option('-p, --path <path>', 'Project path (for apply/undo/dismiss; default: cwd)')
+        .option('-y, --yes', 'With apply: write the change (without it, apply only previews)')
         .option('--capture', 'Capture a routine as a skill proposal: --title required, content on stdin (LEARN-DOC)')
         .option('--title <title>', 'Title for --capture')
-        .action(async (pathArg, options) => {
-        const projectPath = resolveProjectPath(pathArg);
+        .option('--lane <lane>', 'Capture lane: skill (default), style (project convention → .specship/conventions.md), or domain (draft fact → specs/domain/) (ALEARN-DOC)')
+        .action(async (firstArg, hashArg, options) => {
+        const { isReflectVerb, runReflectVerb, REFLECT_VERBS, REFLECT_REVIEW_HINT, DISPLAY_HASH_LEN } = await Promise.resolve().then(() => __importStar(require('../reflect/cli')));
+        const verb = isReflectVerb(firstArg) ? firstArg : undefined;
+        if (!verb && hashArg !== undefined) {
+            error(`Unknown reflect action: ${firstArg}. Valid: ${REFLECT_VERBS.join(', ')} (or a project path with no further arguments)`);
+            process.exit(1);
+        }
+        const projectPath = resolveProjectPath(verb ? options.path : (firstArg ?? options.path));
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
                 error(`SpecShip not initialized in ${projectPath}`);
@@ -1374,6 +1450,17 @@ function main() {
             }
             const { default: SpecShip } = await loadSpecShip();
             const cg = await SpecShip.open(projectPath);
+            // Review verbs (REQ-AUDFIX-002): apply / undo / dismiss by hash prefix.
+            if (verb) {
+                const code = runReflectVerb(cg, verb, hashArg, { yes: options.yes, json: options.json }, {
+                    log: (m) => console.log(m),
+                    error: (m) => error(m),
+                });
+                cg.destroy();
+                if (code !== 0)
+                    process.exit(code);
+                return;
+            }
             // Explicit capture door (LEARN-DOC, REQ-LEARN-002): crystallize a
             // distilled routine into a human-gated skill proposal. Content on
             // stdin so multi-line routines survive shell quoting.
@@ -1390,13 +1477,18 @@ function main() {
                     error('--capture expects the routine content on stdin (pipe or heredoc)');
                     process.exit(1);
                 }
-                const p = cg.reflectCapture({ title: options.title, content });
+                const lane = options.lane;
+                if (lane && !['skill', 'style', 'domain'].includes(lane)) {
+                    error(`Unknown --lane: ${lane}. Valid: skill, style, domain`);
+                    process.exit(1);
+                }
+                const p = cg.reflectCapture({ title: options.title, content, lane });
                 if (options.json) {
                     console.log(JSON.stringify(p, null, 2));
                 }
                 else {
                     info(`Captured as proposal ${p.contentHash.slice(0, 12)} (${p.state}): ${p.title}`);
-                    info('Review the open proposals with `specship reflect` — nothing lands until you apply it.');
+                    info(`Review the open proposals with \`specship reflect\`; apply this one with \`specship reflect apply ${p.contentHash.slice(0, DISPLAY_HASH_LEN)}\` — nothing lands until you apply it.`);
                 }
                 cg.destroy();
                 return;
@@ -1407,7 +1499,9 @@ function main() {
                 cg.destroy();
                 return;
             }
-            if (result.empty || result.open.length === 0) {
+            // Stored open proposals (incl. explicit captures) list even when this
+            // pass mined nothing new — they are what apply/dismiss act on.
+            if (result.open.length === 0) {
                 info('No proposals yet — not enough signal in the ingested transcripts.');
                 info('Tip: run the dashboard with `specship desktop --ingest` to build transcript history.');
                 cg.destroy();
@@ -1426,13 +1520,14 @@ function main() {
             console.log(chalk.bold(`\nReflection proposals (${result.open.length}):\n`));
             for (const p of result.open) {
                 const sev = (sevColor[p.severity] ?? chalk.white)(p.severity.toUpperCase().padEnd(5));
-                console.log(`${sev} ${chalk.bold(p.title)}`);
+                console.log(`${sev} ${chalk.bold(p.title)}  ${chalk.cyan(p.contentHash.slice(0, DISPLAY_HASH_LEN))}`);
                 console.log(chalk.dim(`      ${typeLabel[p.type] ?? p.type} → ${p.targetPath}`));
                 console.log(chalk.dim(`      ${p.evidence.detail}`));
                 console.log(chalk.dim(`      ${p.body}`));
                 console.log();
             }
             info('These are proposals only — nothing is written until you apply one.');
+            info(REFLECT_REVIEW_HINT);
             cg.destroy();
         }
         catch (err) {
@@ -1746,6 +1841,7 @@ function main() {
         .option('-p, --path <path>', 'Project path')
         .option('-j, --json', 'Output as JSON')
         .option('--line', 'Print only the one-line "N of M acceptance criteria …" summary')
+        .option('--require-kinds', 'Exit non-zero when any criterion in scope lacks its required evidence kind')
         .action(async (specArg, options) => {
         const projectPath = resolveProjectPath(options.path);
         try {
@@ -1753,17 +1849,24 @@ function main() {
                 error(`SpecShip not initialized in ${projectPath}`);
                 process.exit(1);
             }
-            const { default: SpecShip, formatCoverageLine } = await loadSpecShip();
+            const { default: SpecShip, formatCoverageLine, requireKindsExitCode, criteriaMissingKind } = await loadSpecShip();
             const cg = await SpecShip.open(projectPath);
             const report = cg.getSpecCoverage(specArg);
+            // REQ-PIPETRUST-003.A2: --require-kinds gates on evidence kind; the
+            // verdicts themselves are unchanged.
+            const kindsExit = requireKindsExitCode(report, !!options.requireKinds);
             if (options.json) {
                 console.log(JSON.stringify(report, null, 2));
                 cg.destroy();
+                if (kindsExit !== 0)
+                    process.exit(kindsExit);
                 return;
             }
             if (options.line) {
                 console.log(formatCoverageLine(report));
                 cg.destroy();
+                if (kindsExit !== 0)
+                    process.exit(kindsExit);
                 return;
             }
             if (report.requirements.length === 0) {
@@ -1779,15 +1882,29 @@ function main() {
                 untested: chalk.dim('·'),
                 broken: chalk.red('✗'),
             };
+            // Evidence kind per criterion (REQ-PIPETRUST-003.A1): required vs present,
+            // flagged `needs <kind>` when the tests don't include the required kind.
+            const kindNote = (c) => {
+                const present = c.presentKinds.length > 0 ? c.presentKinds.join(',') : 'none';
+                const base = `kind: requires ${c.requiredKind}, has ${present}`;
+                return c.kindSatisfied ? chalk.dim(base) : `${chalk.dim(base)} ${chalk.yellow(`needs ${c.requiredKind}`)}`;
+            };
             for (const req of report.requirements) {
-                console.log(`${mark[req.verdict]} ${chalk.bold(req.specId)} ${chalk.dim(req.verdict)} — ${req.title}`);
+                console.log(`${mark[req.verdict]} ${chalk.bold(req.specId)} ${chalk.dim(req.verdict)} — ${req.title}` +
+                    (req.criteria.length === 0 ? ` ${kindNote(req)}` : ''));
                 for (const c of req.criteria) {
-                    console.log(`    ${mark[c.verdict]} ${c.specId} ${chalk.dim(`${c.verdict} · implements:${c.implementsLinks.count} tests:${c.testsLinks.count}`)}`);
+                    console.log(`    ${mark[c.verdict]} ${c.specId} ${chalk.dim(`${c.verdict} · implements:${c.implementsLinks.count} tests:${c.testsLinks.count}`)} · ${kindNote(c)}`);
                 }
             }
             console.log();
             console.log(formatCoverageLine(report));
+            const missing = criteriaMissingKind(report);
+            if (missing.length > 0) {
+                console.log(`${missing.length} criteria lack their required evidence kind.`);
+            }
             cg.destroy();
+            if (kindsExit !== 0)
+                process.exit(kindsExit);
         }
         catch (err) {
             error(`coverage failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1822,6 +1939,184 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * design.md (DESIGNMD-DOC). `extract` turns a Claude Design snapshot or a
+     * Figma export into a pixel-exact reference; `check` fails one that is
+     * incomplete, stale or vague. File-based, needs no index.
+     */
+    program
+        .command('design <action> [paths...]')
+        .description('design.md reference: extract <source...> [--out|--update <design.md>] | check <design.md> | verify <build.html> --against <design.md>')
+        .option('-p, --path <path>', 'Project path (paths are resolved against it; defaults to cwd)')
+        .option('-o, --out <file>', 'extract: write a new design.md')
+        .option('-u, --update <file>', 'extract: refresh the generated block of an existing design.md')
+        .option('-t, --title <title>', 'extract --out: the design title')
+        .option('--origin <link>', 'extract --out: where the design came from (claude.ai/design or figma.com link)')
+        .option('-j, --json', 'check: output as JSON')
+        .option('-a, --against <file>', 'verify: the design.md to compare the build with')
+        .action(async (action, paths, options) => {
+        const projectRoot = resolveProjectPath(options.path);
+        const { runDesignExtractCli, runDesignCheckCli, runDesignVerifyCli } = await Promise.resolve().then(() => __importStar(require('../design-md/check')));
+        const flags = (pairs) => pairs.flatMap(([k, v]) => (v ? [k, v] : []));
+        let result;
+        if (action === 'extract') {
+            result = runDesignExtractCli([...(paths ?? []), ...flags([['--out', options.out], ['--update', options.update], ['--title', options.title], ['--origin', options.origin]])], { projectRoot });
+        }
+        else if (action === 'check') {
+            result = runDesignCheckCli([...(paths ?? []), ...(options.json ? ['--json'] : [])], { projectRoot });
+        }
+        else if (action === 'verify') {
+            result = runDesignVerifyCli([...(paths ?? []), ...flags([['--against', options.against]])], { projectRoot });
+        }
+        else {
+            error(`unknown design action "${action}" — use extract, check or verify`);
+            process.exit(1);
+        }
+        console.log(result.output);
+        if (result.exitCode !== 0)
+            process.exit(result.exitCode);
+    });
+    /**
+     * specship knowledge <action> — the knowledge layer (KNOWLEDGE-DOC).
+     *   stale            external facts whose dependency version changed (REQ-KNOW-002/006)
+     *   check            enforced rules → violations (REQ-KNOW-003)
+     *   proposals        pending proposals drafted by the implement workflow (REQ-KNOW-004)
+     *   apply <id>       move a confirmed proposal into specs/domain/ (human-only)
+     *   reject <id>      delete a proposal
+     * File-based: needs no index, so it runs in CI and inside run worktrees.
+     */
+    program
+        .command('knowledge <action> [id]')
+        .description('Knowledge layer: stale | check | proposals | apply <id> | reject <id>')
+        .option('-p, --path <path>', 'Project path (defaults to cwd)')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (action, id, options) => {
+        const projectRoot = options.path ? path.resolve(options.path) : process.cwd();
+        const out = (value, textOut) => console.log(options.json ? JSON.stringify(value, null, 2) : textOut);
+        try {
+            if (action === 'stale') {
+                const { findStaleExternalFacts, formatStaleReport, exitCodeForStale } = await Promise.resolve().then(() => __importStar(require('../knowledge/stale')));
+                const result = findStaleExternalFacts(projectRoot);
+                out(result, formatStaleReport(result));
+                process.exit(exitCodeForStale(result));
+            }
+            else if (action === 'check') {
+                const { checkEnforcedRules, formatEnforceReport, exitCodeForEnforce } = await Promise.resolve().then(() => __importStar(require('../knowledge/enforce')));
+                const result = checkEnforcedRules(projectRoot);
+                out(result, formatEnforceReport(result));
+                process.exit(exitCodeForEnforce(result));
+            }
+            else if (action === 'proposals') {
+                const { listProposals, formatProposalList } = await Promise.resolve().then(() => __importStar(require('../knowledge/proposals')));
+                const list = listProposals(projectRoot);
+                out(list, formatProposalList(list));
+            }
+            else if (action === 'apply' || action === 'reject') {
+                if (!id) {
+                    error(`knowledge ${action} needs a proposal id — see \`specship knowledge proposals\``);
+                    process.exit(1);
+                }
+                const { applyProposal, rejectProposal, ProposalRefusedError } = await Promise.resolve().then(() => __importStar(require('../knowledge/proposals')));
+                if (action === 'reject') {
+                    rejectProposal(projectRoot, id);
+                    out({ rejected: id }, `Rejected proposal ${id} — nothing was written to specs/domain/.`);
+                }
+                else {
+                    try {
+                        const applied = applyProposal(projectRoot, id);
+                        out(applied, `Applied ${id} as ${applied.id} → ${applied.path}. Run \`specship sync\` to index it.`);
+                    }
+                    catch (err) {
+                        if (err instanceof ProposalRefusedError) {
+                            error(`Refused to apply ${id} — fix the proposal first:`);
+                            for (const f of err.findings)
+                                console.log(`  ${f.severity} ${f.code}: ${f.message}`);
+                            process.exit(1);
+                        }
+                        throw err;
+                    }
+                }
+            }
+            else {
+                error(`unknown knowledge action "${action}" — expected stale | check | proposals | apply | reject`);
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            error(`knowledge ${action} failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * specship plan-scope <SPEC_ID> --plan-file <f> — small-plan auto-approval
+     * check (THROUGHPUT-DOC, REQ-THRU-003). Always exits 0; the AUTO_APPROVE
+     * marker is what the plan gate reads.
+     */
+    program
+        .command('plan-scope <specId>')
+        .description('Decide whether a plan may skip the plan gate (opt-in; prints AUTO_APPROVE=yes|no)')
+        .requiredOption('--plan-file <file>', 'File holding the plan text')
+        .option('-p, --path <path>', 'Project path (defaults to cwd)')
+        .action(async (specId, options) => {
+        const projectRoot = options.path ? path.resolve(options.path) : process.cwd();
+        try {
+            const { assessPlanScopeFromFile, formatPlanScope } = await Promise.resolve().then(() => __importStar(require('../spec-quality/plan-scope')));
+            const planText = fs.readFileSync(path.resolve(options.planFile), 'utf8');
+            console.log(formatPlanScope(assessPlanScopeFromFile(projectRoot, specId, planText)));
+        }
+        catch (err) {
+            console.log(`AUTO_APPROVE=no\n- plan-scope failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    /**
+     * specship ready <SPEC_ID> — readiness gate (PIPETRUST-DOC, REQ-PIPETRUST-004).
+     * File-based (no index needed), so it runs inside a workflow worktree. Exits
+     * non-zero when the requirement is not ready; prints the evidence plan.
+     */
+    program
+        .command('ready <specId>')
+        .description('Check a requirement is ready to implement and print its evidence plan (exits non-zero when not ready)')
+        .option('-p, --path <path>', 'Project path (defaults to cwd)')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (specId, options) => {
+        const projectRoot = options.path ? path.resolve(options.path) : process.cwd();
+        try {
+            const { assessReadinessFromFile, formatEvidencePlan } = await Promise.resolve().then(() => __importStar(require('../spec-quality/readiness')));
+            const result = assessReadinessFromFile(projectRoot, specId);
+            console.log(options.json ? JSON.stringify(result, null, 2) : formatEvidencePlan(result));
+            if (!result.ready)
+                process.exit(1);
+        }
+        catch (err) {
+            error(`ready failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * specship postcheck <SPEC_ID> [--fix] — mechanical post-implement checks
+     * (PIPETRUST-DOC, REQ-PIPETRUST-005). File-based, worktree-safe.
+     */
+    program
+        .command('postcheck <specId>')
+        .description('Mechanically check an implemented requirement: verifies coverage, CHANGELOG, configured checks (exits non-zero on failure)')
+        .option('-p, --path <path>', 'Project path (defaults to cwd)')
+        .option('--fix', 'Run each configured check\'s fix command first')
+        .option('--base <ref>', 'Base ref for the CHANGELOG check (defaults to the recorded run base, then the merge-base with the default branch)')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (specId, options) => {
+        const projectRoot = options.path ? path.resolve(options.path) : process.cwd();
+        try {
+            const { runPostcheck, formatPostcheck } = await Promise.resolve().then(() => __importStar(require('../spec-quality/postcheck')));
+            const result = runPostcheck({ projectRoot, requirementId: specId, fix: options.fix, base: options.base });
+            console.log(options.json ? JSON.stringify(result, null, 2) : formatPostcheck(result));
+            if (!result.ok)
+                process.exit(1);
+        }
+        catch (err) {
+            error(`postcheck failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * specship verify --report <file>
      *
@@ -2021,9 +2316,12 @@ function main() {
             }
             for (const c of r.checks) {
                 const tag = c.gating ? chalk.dim('[gating]') : chalk.dim('[advisory]');
-                const mark = c.passed ? chalk.green('✓') : (c.gating ? chalk.red('✗') : chalk.yellow('•'));
+                // A skipped check's input was unavailable — presented as skipped,
+                // never as pass or fail (REQ-QGATE-002.A3).
+                const mark = c.skipped ? chalk.yellow('○') : c.passed ? chalk.green('✓') : (c.gating ? chalk.red('✗') : chalk.yellow('•'));
                 const reach = scope ? chalk.dim(c.scoped ? ' [since]' : ' [repo-wide]') : '';
-                console.log(`  ${mark} ${c.check.padEnd(16)} ${tag}${reach} ${c.passed ? 'pass' : `${c.findings.length} finding(s)`}`);
+                const status = c.skipped ? 'skipped' : c.passed ? 'pass' : `${c.findings.length} finding(s)`;
+                console.log(`  ${mark} ${c.check.padEnd(16)} ${tag}${reach} ${status}`);
                 if (!c.passed)
                     for (const f of c.findings.slice(0, 8))
                         console.log(chalk.dim(`        ${f}`));
@@ -2037,7 +2335,7 @@ function main() {
                     : 'Pass (no gating checks failed).');
                 // The advisory sell (REQ-ENFORCE-004.A1): findings that would fail
                 // a gated run end the report with the exact opt-in command.
-                const wouldGate = r.checks.filter((c) => !c.gating && !c.passed).map((c) => c.check);
+                const wouldGate = r.checks.filter((c) => !c.gating && !c.passed && !c.skipped).map((c) => c.check);
                 if (wouldGate.length) {
                     const total = r.checks
                         .filter((c) => wouldGate.includes(c.check))
@@ -2162,6 +2460,39 @@ function main() {
             process.exit(1);
         }
     }
+    program
+        .command('suppressions [path]')
+        .description('Scan the change under review for newly introduced lint/type suppression comments (noqa, eslint-disable, @ts-ignore, …); exits non-zero when any were added')
+        .option('--since <ref>', 'Diff base (default HEAD): scan lines added since this ref')
+        .option('-j, --json', 'Output findings as JSON')
+        .action(async (pathArg, options) => {
+        const projectPath = resolveProjectPath(pathArg);
+        // The SUPPRESSION_GATE marker is the machine-readable contract the
+        // spec-implement workflows route on (REQ-QGATE-004.A3) — same doctrine as
+        // VERIFY_RESULT: a scan that could not run is `skipped`, never `clean`.
+        try {
+            const { workingTreeDiffText } = await Promise.resolve().then(() => __importStar(require('../enforce/changed-files')));
+            const { scanDisableComments, formatSuppressionFinding } = await Promise.resolve().then(() => __importStar(require('../enforce/suppressions')));
+            const findings = scanDisableComments(workingTreeDiffText(projectPath, options.since ?? 'HEAD'));
+            if (options.json) {
+                console.log(JSON.stringify({ gate: findings.length === 0 ? 'clean' : 'failed', findings }, null, 2));
+                process.exit(findings.length === 0 ? 0 : 1);
+            }
+            if (findings.length === 0) {
+                console.log('SUPPRESSION_GATE=clean');
+                return;
+            }
+            console.log('SUPPRESSION_GATE=failed');
+            for (const f of findings)
+                console.log(`  ${formatSuppressionFinding(f)}`);
+            console.log('Fix the code instead of silencing the rule (REQ-QGATE-004).');
+            process.exit(1);
+        }
+        catch (err) {
+            console.log('SUPPRESSION_GATE=skipped');
+            console.log(`SUPPRESSION_REASON=${err instanceof Error ? err.message.split('\n')[0] : String(err)}`);
+        }
+    });
     program
         .command('serve')
         .description('Start SpecShip as an MCP server for AI assistants (stdio transport)')
@@ -2663,6 +2994,7 @@ function main() {
         // existing invocations — including our own offline-install scripts — behave
         // exactly as before.
         .option('-t, --target <ids>', 'Agents to wire, comma-separated: "claude" (default) | "gemini" | "claude,gemini". Also selects the snippet `--print-config` prints. Legacy: "auto"/"all" = claude, "none" = skip')
+        .option('--trust', 'Gemini only (REQ-GEMINI-009): write ~/.gemini/policies/specship.toml auto-allowing SpecShip\'s read-only tools. Opt-in — an admin policy still wins and run_shell_command is unaffected')
         .action(async (opts) => {
         if (opts.printConfig) {
             const loc = (opts.location === 'local' ? 'local' : 'global');
@@ -2723,6 +3055,10 @@ function main() {
                 withJira: opts.withJira === true ? true : undefined,
                 withDesigner: opts.withDesigner === true ? true : undefined,
                 statusLine,
+                // REQ-AUDFIX-001: a local install must honor --skip-index too.
+                skipIndex: opts.skipIndex === true,
+                // REQ-GEMINI-009: strictly opt-in, no prompt. Claude target ignores it.
+                trust: opts.trust === true ? true : undefined,
                 yes: opts.yes,
             });
             // Index the current project (REQ-HANDSHAKE-004) before the smoke check,
@@ -2899,7 +3235,32 @@ function main() {
             }
         }
         const { buildCheatsheetPayload } = await Promise.resolve().then(() => __importStar(require('../activation/cheatsheet')));
-        const payload = buildCheatsheetPayload();
+        // Learned-state extras (REQ-ALEARN-002 / REQ-ALEARN-004.A2) — both
+        // best-effort: an unreadable file or DB silently yields the base
+        // cheatsheet, never an error in the SessionStart hook.
+        const projectPath = resolveProjectPath(undefined);
+        let conventions = null;
+        try {
+            conventions = (await Promise.resolve().then(() => __importStar(require('fs')))).readFileSync((await Promise.resolve().then(() => __importStar(require('path')))).join(projectPath, '.specship', 'conventions.md'), 'utf-8');
+        }
+        catch { /* no conventions file */ }
+        let openProposals = 0;
+        try {
+            const { DatabaseConnection, DATABASE_FILENAME } = await Promise.resolve().then(() => __importStar(require('../db')));
+            const { ReflectStore } = await Promise.resolve().then(() => __importStar(require('../reflect')));
+            const dbPath = (await Promise.resolve().then(() => __importStar(require('path')))).join(projectPath, '.specship', DATABASE_FILENAME);
+            if ((await Promise.resolve().then(() => __importStar(require('fs')))).existsSync(dbPath)) {
+                const conn = DatabaseConnection.initialize(dbPath);
+                try {
+                    openProposals = new ReflectStore(conn.getDb()).list('open').length;
+                }
+                finally {
+                    conn.close();
+                }
+            }
+        }
+        catch { /* store unavailable → omit the line */ }
+        const payload = buildCheatsheetPayload(process.env, { conventions, openProposals });
         if (payload)
             process.stdout.write(JSON.stringify(payload) + '\n');
         process.exit(0);
@@ -2937,21 +3298,14 @@ function main() {
         }
         catch { /* no stdin — nothing to nudge */ }
         const raw = Buffer.concat(chunks).toString('utf-8').trim();
-        let prompt = '';
-        if (raw) {
-            try {
-                const parsed = JSON.parse(raw);
-                prompt = typeof parsed?.prompt === 'string' ? parsed.prompt : raw;
-            }
-            catch {
-                prompt = raw; // not JSON — treat as the raw prompt text
-            }
-        }
-        if (shouldNudge(prompt)) {
+        const { parseHookPayload, buildHookAdditionalContext, deriveHostTraits } = await Promise.resolve().then(() => __importStar(require('../activation/hook-output')));
+        const payload = parseHookPayload(raw);
+        const traits = deriveHostTraits(payload);
+        if (shouldNudge(payload.prompt || raw)) {
             const additionalContext = 'This repo uses spec-driven development (SpecShip). Before any brainstorming or ' +
                 'planning skill, FIRST invoke spec-author to author the spec under specs/ for this ' +
                 'work — the spec is the contract; implement from it with /specship:spec implement.';
-            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext } }) + '\n');
+            process.stdout.write(buildHookAdditionalContext(additionalContext, payload.hookEventName, traits.fallbackPromptEvent));
         }
         process.exit(0);
     });
@@ -2967,11 +3321,9 @@ function main() {
         .command('steer-nudge')
         .description('Internal hook: steer flow/structure questions to specship_explore (UserPromptSubmit)')
         .action(async () => {
-        // Prefer the hook payload's cwd (Claude Code sends it on stdin) so the
-        // check targets the project the prompt belongs to, not wherever the hook
-        // process happened to spawn.
-        let cwd = process.cwd();
-        let transcriptPath = null;
+        // Prefer the hook payload's cwd (Claude Code / Gemini CLI both send it
+        // on stdin) so the check targets the project the prompt belongs to, not
+        // wherever the hook process happened to spawn.
         const chunks = [];
         try {
             for await (const c of process.stdin)
@@ -2979,81 +3331,100 @@ function main() {
         }
         catch { /* no stdin — fall back to process.cwd() */ }
         const raw = Buffer.concat(chunks).toString('utf-8').trim();
-        if (raw) {
-            try {
-                const parsed = JSON.parse(raw);
-                if (typeof parsed?.cwd === 'string' && parsed.cwd.length > 0)
-                    cwd = parsed.cwd;
-                if (typeof parsed?.transcript_path === 'string' && parsed.transcript_path.length > 0) {
-                    transcriptPath = parsed.transcript_path;
-                }
-            }
-            catch { /* not JSON — keep process.cwd() */ }
-        }
+        const { parseHookPayload, buildHookAdditionalContext, deriveHostTraits } = await Promise.resolve().then(() => __importStar(require('../activation/hook-output')));
+        const payload = parseHookPayload(raw);
+        const traits = deriveHostTraits(payload);
+        const cwd = payload.cwd ?? process.cwd();
         // Record the session's model from the transcript tail (MODCTX-DOC,
         // REQ-MODCTX-001.A4) — the primary detection channel, present on every
         // default install. Fires per prompt so mid-session /model switches
         // track; runs even when the steering text is suppressed, but only in
         // initialized projects. Best-effort: never fails the hook.
-        if (transcriptPath && fs.existsSync(path.join(cwd, '.specship'))) {
+        if (payload.transcriptPath && fs.existsSync(path.join(cwd, '.specship'))) {
             try {
                 const { readModelFromTranscript, recordSessionModel } = await Promise.resolve().then(() => __importStar(require('../mcp/model-context')));
-                const model = readModelFromTranscript(transcriptPath);
+                const model = readModelFromTranscript(payload.transcriptPath);
                 if (model)
                     recordSessionModel(cwd, model);
             }
             catch { /* telemetry must never break the hook */ }
         }
         const { buildSteeringNudge } = await Promise.resolve().then(() => __importStar(require('../activation/steering')));
-        const additionalContext = buildSteeringNudge(cwd);
+        const additionalContext = buildSteeringNudge(cwd, process.env, undefined, traits.toolPrefix);
         if (additionalContext) {
-            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext } }) + '\n');
+            process.stdout.write(buildHookAdditionalContext(additionalContext, payload.hookEventName, traits.fallbackPromptEvent));
         }
         process.exit(0);
     });
     /**
-     * specship search-intercept (STEER-HOOK-DOC, REQ-STEER-004/005)
+     * specship search-intercept (STEER-HOOK-DOC, REQ-STEER-004/005, REQ-GEMINI-011)
      *
-     * Internal PreToolUse hook command on search-shaped tools (Grep/Glob): emit
-     * the point-of-use redirect to specship_explore, at most once per session and
-     * only when the session hasn't used specship yet. STRICTLY ADVISORY — the
-     * output is additionalContext, never a permission decision, and the command
-     * exits 0 on every path (including internal errors) so the matched call
-     * always proceeds (REQ-STEER-004.A2).
+     * Internal hook on search-shaped tools. For Claude's PreToolUse (Grep/Glob)
+     * and Gemini's BeforeTool (grep_search / glob / run_shell_command), emit the
+     * point-of-use redirect to specship_explore. Host-aware traits are derived
+     * from the payload in `activation/hook-output.ts`; shared code never sniffs
+     * event names. Advisory for Claude; Gemini also supports strict mode
+     * (`SPECSHIP_GEMINI_STRICT=1`) which denies grep_search / glob — never
+     * run_shell_command (REQ-GEMINI-011.A3). Exits 0 on every path.
      */
     program
         .command('search-intercept')
-        .description('Internal hook: point-of-use redirect from search tools to specship_explore (PreToolUse)')
+        .description('Internal hook: point-of-use redirect from search tools to specship_explore (PreToolUse / BeforeTool)')
         .action(async () => {
         try {
-            let cwd = process.cwd();
-            let sessionId = null;
-            let transcriptPath = null;
             const chunks = [];
             try {
                 for await (const c of process.stdin)
                     chunks.push(c);
             }
-            catch { /* no stdin — fall back to process.cwd(), untracked session */ }
-            const raw = Buffer.concat(chunks).toString('utf-8').trim();
-            if (raw) {
-                try {
-                    const parsed = JSON.parse(raw);
-                    if (typeof parsed?.cwd === 'string' && parsed.cwd.length > 0)
-                        cwd = parsed.cwd;
-                    if (typeof parsed?.session_id === 'string' && parsed.session_id.length > 0) {
-                        sessionId = parsed.session_id;
-                    }
-                    if (typeof parsed?.transcript_path === 'string' && parsed.transcript_path.length > 0) {
-                        transcriptPath = parsed.transcript_path;
-                    }
+            catch { /* no stdin — fall through with empty payload */ }
+            const raw = Buffer.concat(chunks).toString('utf-8');
+            const { parseHookPayload, deriveHostTraits, buildHookAdditionalContext, buildHookDenyDecision } = await Promise.resolve().then(() => __importStar(require('../activation/hook-output')));
+            const payload = parseHookPayload(raw);
+            const traits = deriveHostTraits(payload);
+            const cwd = payload.cwd ?? process.cwd();
+            let toolName = '';
+            let toolInput = {};
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed?.tool_name === 'string')
+                    toolName = parsed.tool_name;
+                if (parsed?.tool_input && typeof parsed.tool_input === 'object' && !Array.isArray(parsed.tool_input)) {
+                    toolInput = parsed.tool_input;
                 }
-                catch { /* not JSON — keep defaults */ }
             }
+            catch { /* not JSON — strict path stays off, advisory still works via payload */ }
+            const DENY_TOOLS = new Set(traits.denyEligibleTools);
+            const shellCommand = traits.shellTool !== null && toolName === traits.shellTool && typeof toolInput.command === 'string'
+                ? toolInput.command
+                : null;
+            const { resolveSetting } = await Promise.resolve().then(() => __importStar(require('../config/runtime-settings')));
+            const strict = traits.supportsBeforeToolDeny &&
+                resolveSetting('SPECSHIP_GEMINI_STRICT', cwd, process.env, os.homedir()) === '1';
+            const searchPattern = (typeof toolInput.pattern === 'string' && toolInput.pattern) ||
+                (typeof toolInput.query === 'string' && toolInput.query) ||
+                null;
             const { buildSearchIntercept } = await Promise.resolve().then(() => __importStar(require('../activation/search-intercept')));
-            const additionalContext = buildSearchIntercept({ cwd, sessionId, transcriptPath });
-            if (additionalContext) {
-                process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext } }) + '\n');
+            const result = buildSearchIntercept({
+                cwd,
+                sessionId: payload.sessionId,
+                transcriptPath: payload.transcriptPath,
+                specshipToolMarkers: traits.specshipToolMarkers,
+                transcriptFormat: traits.transcriptFormat,
+                strict,
+                denyEligible: DENY_TOOLS.has(toolName),
+                shellCommand,
+                searchPattern,
+            });
+            if (result) {
+                if ('decision' in result) {
+                    // Gemini BeforeToolHookOutput reads `decision` at the top level
+                    // (isBlockingDecision), not inside hookSpecificOutput.
+                    process.stdout.write(buildHookDenyDecision(result.reason));
+                }
+                else {
+                    process.stdout.write(buildHookAdditionalContext(result.additionalContext, payload.hookEventName, traits.fallbackToolEvent));
+                }
             }
         }
         catch { /* advisory only — never block the matched call (REQ-STEER-004.A2) */ }
@@ -3155,6 +3526,75 @@ function main() {
             cg.close();
         }
     });
+    // @implements REQ-PIPETRUST-007
+    // Pipeline health: release run, npm lag, last JIRA auto-publish, merged run
+    // worktrees. Network checks are time-bounded and skip offline; results are
+    // cached to .specship/pulse.json for the session-start summary.
+    program
+        .command('pulse [path]')
+        .description('Report pipeline health (release run, npm lag, JIRA auto-publish, merged run worktrees); exits non-zero on any failure.')
+        .option('--refresh', 'ignore the cache and re-run every check')
+        .option('--max-age <minutes>', 'serve the cached result when younger than this (default: always re-run)')
+        .option('--json', 'emit JSON')
+        .action(async (pathArg, options) => {
+        const projectRoot = path.resolve(pathArg ?? process.cwd());
+        const { computePulse } = await Promise.resolve().then(() => __importStar(require('../pulse/pulse')));
+        // Resolve a run worktree back to its full run id for the purge hint
+        // (best-effort; falls back to the short id from the branch name).
+        let runIdForWorktree;
+        let close;
+        if ((0, directory_1.isInitialized)(projectRoot)) {
+            try {
+                const { SpecShip } = await loadSpecShip();
+                const cg = await SpecShip.open(projectRoot);
+                close = () => cg.close();
+                const byPath = new Map();
+                const sq = cg.getSpecQueries();
+                for (const run of sq.getAllWorkflowRuns(500)) {
+                    if (!run.isolationEnvId)
+                        continue;
+                    const env = sq.getIsolationEnvById(run.isolationEnvId);
+                    if (env?.workingPath)
+                        byPath.set(path.resolve(env.workingPath), run.id);
+                }
+                runIdForWorktree = (p) => byPath.get(path.resolve(p));
+            }
+            catch {
+                /* hint falls back to the short id */
+            }
+        }
+        const maxAgeMin = options.maxAge !== undefined ? Number(options.maxAge) : NaN;
+        let result;
+        try {
+            result = await computePulse({
+                projectRoot,
+                refresh: options.refresh,
+                maxAgeMs: Number.isFinite(maxAgeMin) ? maxAgeMin * 60_000 : undefined,
+                writeCache: fs.existsSync(path.join(projectRoot, '.specship')),
+                runIdForWorktree,
+            });
+        }
+        finally {
+            close?.();
+        }
+        if (options.json) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            const tag = { ok: 'ok  ', fail: 'FAIL', skipped: 'skip' };
+            for (const item of result.items) {
+                // eslint-disable-next-line no-console
+                console.log(`[${tag[item.status]}] ${item.message}${item.hint ? ` — ${item.hint}` : ''}`);
+            }
+            if (result.fromCache) {
+                // eslint-disable-next-line no-console
+                console.log(`(cached ${new Date(result.checkedAt).toISOString()}; --refresh to re-run)`);
+            }
+        }
+        if (result.items.some((i) => i.status === 'fail'))
+            process.exit(1);
+    });
     program
         .command('drifted [path]')
         .description('List spec links in concerning states (drifted, broken, orphaned).')
@@ -3436,14 +3876,19 @@ function main() {
         }
     });
     program
-        .command('workflow <action> [arg]')
-        .description('Workflow engine: list | run <name> | resume <runId> | cancel <runId> | approve <runId> | reject <runId> | purge <runId> | runs')
+        .command('workflow <action> [args...]')
+        .description('Workflow engine: list | run <name> | run-batch <name> --specs <ids> | merge-queue <runId...> | gc | resume <runId> | cancel <runId> | approve <runId> | reject <runId> | purge <runId> | runs')
         .option('-i, --input <kv...>', 'workflow inputs as KEY=VALUE (repeatable)')
         .option('--path <projectRoot>', 'project root (default: cwd)')
         .option('--comment <text>', 'comment for approve/reject')
         .option('--reason <text>', 'reason for cancel/reject')
+        .option('--specs <ids>', 'run-batch: comma-separated requirement ids')
+        .option('--concurrency <n>', 'run-batch: max concurrent runs per wave (default 3)')
+        .option('--dry-run', 'gc: list merged-run worktrees without removing them')
+        .option('--agent <name>', 'run/run-batch: the coding agent prompt steps run on (claude | gemini; default: SPECSHIP_WORKFLOW_AGENT, workflow.agent, the launching agent, then claude)')
         .option('--json', 'emit JSON where applicable')
-        .action(async (action, arg, options) => {
+        .action(async (action, args, options) => {
+        const arg = args?.[0];
         const projectRoot = path.resolve(options.path ?? process.cwd());
         if (!(0, directory_1.isInitialized)(projectRoot)) {
             error(`SpecShip not initialized in ${projectRoot}. Run \`specship init -i\` first.`);
@@ -3451,6 +3896,7 @@ function main() {
         }
         const { SpecShip } = await loadSpecShip();
         const { discoverWorkflows, loadWorkflowByName } = await Promise.resolve().then(() => __importStar(require('../workflows/discovery')));
+        const { resolveWorkflowAgent } = await Promise.resolve().then(() => __importStar(require('../workflows/agents')));
         const { WorkflowExecutor } = await Promise.resolve().then(() => __importStar(require('../workflows/executor')));
         const { WorktreeProvider } = await Promise.resolve().then(() => __importStar(require('../isolation/worktree')));
         const { handleJiraRunCompletion } = await Promise.resolve().then(() => __importStar(require('../mcp/jira-tools')));
@@ -3541,9 +3987,18 @@ function main() {
                             inputs[inp.name] = inp.default ?? '';
                         }
                     }
+                    // Unknown agent names fail here, before a run exists (REQ-AGENTADAPT-006.A4).
+                    try {
+                        resolveWorkflowAgent({ flag: options.agent, projectRoot });
+                    }
+                    catch (err) {
+                        error(err instanceof Error ? err.message : String(err));
+                        process.exit(1);
+                    }
                     const result = await executor.start(loaded.workflow, {
                         projectRoot,
                         inputs,
+                        agent: options.agent,
                         variables: {
                             ARTIFACTS_DIR: path.join((0, directory_1.getSpecShipDir)(projectRoot), 'artifacts'),
                             CONTEXT: projectRoot,
@@ -3664,6 +4119,208 @@ function main() {
                         : `Run ${arg} had no worktree — nothing to remove. Artifacts and the run record are kept.`);
                     break;
                 }
+                case 'run-batch': {
+                    // REQ-THRU-001 — one run per requirement, overlapping files serialized.
+                    if (!arg) {
+                        error('workflow run-batch requires a workflow name');
+                        process.exit(1);
+                    }
+                    const loaded = loadWorkflowByName(projectRoot, arg);
+                    if (!loaded) {
+                        error(`Workflow "${arg}" not found. Use \`specship workflow list\` to see available workflows.`);
+                        process.exit(1);
+                    }
+                    const specIds = (options.specs ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+                    if (specIds.length === 0) {
+                        error('workflow run-batch requires --specs <ID,ID,...>');
+                        process.exit(1);
+                    }
+                    const concurrency = options.concurrency !== undefined ? Number(options.concurrency) : undefined;
+                    if (concurrency !== undefined && (!Number.isInteger(concurrency) || concurrency < 1)) {
+                        error('--concurrency must be a positive integer');
+                        process.exit(1);
+                    }
+                    const baseInputs = {};
+                    for (const kv of options.input ?? []) {
+                        const eqIdx = kv.indexOf('=');
+                        if (eqIdx <= 0) {
+                            error(`--input must be KEY=VALUE (got "${kv}")`);
+                            process.exit(1);
+                        }
+                        baseInputs[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
+                    }
+                    for (const inp of loaded.workflow.inputs ?? []) {
+                        if (inp.name !== 'SPEC_ID' && !(inp.name in baseInputs)) {
+                            if (inp.required) {
+                                error(`Required input missing: --input ${inp.name}=...`);
+                                process.exit(1);
+                            }
+                            baseInputs[inp.name] = inp.default ?? '';
+                        }
+                    }
+                    try {
+                        resolveWorkflowAgent({ flag: options.agent, projectRoot });
+                    }
+                    catch (err) {
+                        error(err instanceof Error ? err.message : String(err));
+                        process.exit(1);
+                    }
+                    const { runBatch, TERMINAL_RUN_STATUSES, DEFAULT_BATCH_CONCURRENCY } = await Promise.resolve().then(() => __importStar(require('../workflows/batch')));
+                    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+                    let batch;
+                    try {
+                        batch = await runBatch({
+                            projectRoot,
+                            specIds,
+                            concurrency,
+                            startRun: async (specId) => {
+                                const result = await executor.start(loaded.workflow, {
+                                    projectRoot,
+                                    agent: options.agent,
+                                    inputs: { ...baseInputs, SPEC_ID: specId },
+                                    variables: {
+                                        ARTIFACTS_DIR: path.join((0, directory_1.getSpecShipDir)(projectRoot), 'artifacts'),
+                                        CONTEXT: projectRoot,
+                                    },
+                                });
+                                return { runId: result.run.id, status: result.run.status };
+                            },
+                            // A run paused at an approval still holds its files: wait for a
+                            // terminal status (approve + resume it from another terminal).
+                            waitForRun: async (runId, status) => {
+                                let current = status;
+                                let announced = false;
+                                while (!TERMINAL_RUN_STATUSES.has(current)) {
+                                    if (current === 'paused' && !announced) {
+                                        // eslint-disable-next-line no-console
+                                        console.log(`  ${runId} is paused — approve it with \`specship workflow approve ${runId}\`, then \`specship workflow resume ${runId}\``);
+                                        announced = true;
+                                    }
+                                    await sleep(5000);
+                                    current = specQueries.getWorkflowRunById(runId)?.status ?? 'failed';
+                                }
+                                return current;
+                            },
+                            onPlan: (waves) => {
+                                if (options.json)
+                                    return;
+                                // eslint-disable-next-line no-console
+                                console.log(`Serialization: ${waves.length} wave(s), concurrency ${concurrency ?? DEFAULT_BATCH_CONCURRENCY}`);
+                                waves.forEach((w, i) => {
+                                    // eslint-disable-next-line no-console
+                                    console.log(`  wave ${i + 1}: ${w.join(', ')}`);
+                                });
+                            },
+                            onRunStarted: (r) => {
+                                if (options.json)
+                                    return;
+                                // eslint-disable-next-line no-console
+                                console.log(`  ${r.specId} → run ${r.runId} [${r.status}] (wave ${r.wave + 1})`);
+                            },
+                        });
+                    }
+                    catch (err) {
+                        error(err instanceof Error ? err.message : String(err));
+                        process.exit(1);
+                    }
+                    if (options.json) {
+                        // eslint-disable-next-line no-console
+                        console.log(JSON.stringify(batch, null, 2));
+                    }
+                    else {
+                        // eslint-disable-next-line no-console
+                        console.log('Runs:');
+                        for (const r of batch.runs) {
+                            // eslint-disable-next-line no-console
+                            console.log(`  ${r.runId} ${r.specId} [${r.status}]`);
+                        }
+                    }
+                    if (batch.runs.some((r) => r.status === 'failed'))
+                        process.exit(1);
+                    break;
+                }
+                case 'merge-queue': {
+                    // REQ-THRU-002 — merge completed runs in order, re-checking each merge.
+                    const runIds = args ?? [];
+                    if (runIds.length === 0) {
+                        error('workflow merge-queue requires one or more runIds');
+                        process.exit(1);
+                    }
+                    const { runMergeQueue } = await Promise.resolve().then(() => __importStar(require('../workflows/merge-queue')));
+                    const result = runMergeQueue({
+                        projectRoot,
+                        runIds,
+                        getRun: (id) => {
+                            const run = specQueries.getWorkflowRunById(id);
+                            if (!run)
+                                return null;
+                            const env = run.isolationEnvId ? specQueries.getIsolationEnvById(run.isolationEnvId) : null;
+                            return { id: run.id, status: run.status, branch: env?.branchName };
+                        },
+                    });
+                    if (options.json) {
+                        // eslint-disable-next-line no-console
+                        console.log(JSON.stringify(result, null, 2));
+                    }
+                    else {
+                        for (const id of result.merged) {
+                            // eslint-disable-next-line no-console
+                            console.log(`  merged ${id}`);
+                        }
+                        // eslint-disable-next-line no-console
+                        console.log(result.stoppedAt
+                            ? `Stopped at run ${result.stoppedAt} (${result.reason}): ${result.detail ?? ''}`
+                            : `Merge queue done — ${result.merged.length} run(s) merged.`);
+                    }
+                    if (result.stoppedAt)
+                        process.exit(1);
+                    break;
+                }
+                case 'gc': {
+                    // REQ-THRU-007 — purge worktrees of merged runs; records + artifacts kept.
+                    const { collectMergedRuns } = await Promise.resolve().then(() => __importStar(require('../workflows/gc')));
+                    const result = collectMergedRuns({
+                        projectRoot,
+                        dryRun: options.dryRun === true,
+                        listRuns: () => specQueries.getAllWorkflowRuns(1000).flatMap((run) => {
+                            if (!run.isolationEnvId)
+                                return [];
+                            const env = specQueries.getIsolationEnvById(run.isolationEnvId);
+                            if (!env)
+                                return [];
+                            return [{ id: run.id, status: run.status, branch: env.branchName, workingPath: env.workingPath }];
+                        }),
+                        purge: (runId) => {
+                            executor.purge(runId);
+                        },
+                    });
+                    if (options.json) {
+                        // eslint-disable-next-line no-console
+                        console.log(JSON.stringify(result, null, 2));
+                    }
+                    else if (!result.defaultBranch) {
+                        // eslint-disable-next-line no-console
+                        console.log('Default branch unknown (no origin HEAD, main or master) — nothing collected.');
+                    }
+                    else {
+                        const verb = result.dryRun ? 'would remove' : 'removed';
+                        for (const c of result.candidates) {
+                            // eslint-disable-next-line no-console
+                            console.log(`  ${verb} ${c.runId} ${c.branch} (${c.workingPath})`);
+                        }
+                        for (const s of result.skipped) {
+                            // eslint-disable-next-line no-console
+                            console.log(`  kept ${s.runId} — ${s.reason}`);
+                        }
+                        // eslint-disable-next-line no-console
+                        console.log(result.candidates.length === 0
+                            ? `No merged-run worktrees to collect (default branch: ${result.defaultBranch}).`
+                            : result.dryRun
+                                ? `${result.candidates.length} worktree(s) would be removed. Run without --dry-run to collect.`
+                                : `${result.purged.length} worktree(s) removed. Run records and artifacts are kept.`);
+                    }
+                    break;
+                }
                 case 'runs': {
                     const runs = specQueries.getAllWorkflowRuns(50);
                     if (options.json) {
@@ -3686,7 +4343,7 @@ function main() {
                     break;
                 }
                 default:
-                    error(`Unknown workflow action "${action}". Use: list | run | resume | cancel | approve | reject | purge | runs`);
+                    error(`Unknown workflow action "${action}". Use: list | run | run-batch | merge-queue | gc | resume | cancel | approve | reject | purge | runs`);
                     process.exit(1);
             }
         }
@@ -4087,6 +4744,67 @@ function main() {
             cg.close();
         }
     });
+    /**
+     * specship jira publish --pending — the explicit, one-batch publish of every
+     * requirement sync held back (REQ-THRU-006). Sync only publishes when
+     * `jira.autoPublish: true` is set in specship.config.json; otherwise it
+     * reports the pending count and points here.
+     */
+    jira
+        .command('publish')
+        .description('Publish specs to the bound JIRA project in one explicit batch (--pending: every requirement sync held back).')
+        .option('--pending', 'publish every requirement with no JIRA issue yet or whose content changed')
+        .option('--dry-run', 'list what would be published without writing to JIRA')
+        .option('--path <projectRoot>', 'project root (default: cwd)')
+        .action(async (options) => {
+        const projectRoot = path.resolve(options.path ?? process.cwd());
+        if (!options.pending) {
+            error('Nothing to publish: pass --pending to publish every requirement sync held back.');
+            process.exit(1);
+        }
+        if (!(0, directory_1.isInitialized)(projectRoot)) {
+            error(`SpecShip not initialized in ${projectRoot}. Run \`specship init -i\` first.`);
+            process.exit(1);
+        }
+        const { SpecShip } = await loadSpecShip();
+        const { publishPendingSpecs, runAutoPublish, summarizeAutoPublishReport, countAutoPublishReport } = await Promise.resolve().then(() => __importStar(require('../jira/auto-publish')));
+        const cg = await SpecShip.open(projectRoot);
+        try {
+            const deps = { specQueries: cg.getSpecQueries(), projectRoot };
+            const report = options.dryRun
+                ? await runAutoPublish(deps, { explicit: true, dryRun: true })
+                : await publishPendingSpecs(deps);
+            if (report.skipped === 'unbound') {
+                error('No JIRA binding in specship.config.json — run `specship jira bind` first.');
+                process.exit(1);
+            }
+            if (options.dryRun) {
+                const pending = report.results.filter((r) => r.status === 'pending');
+                // eslint-disable-next-line no-console
+                console.log(`${pending.length} spec(s) would be published:`);
+                // eslint-disable-next-line no-console
+                for (const r of pending)
+                    console.log(`  ${r.specId}${r.jiraKey ? ` (${r.jiraKey})` : ''}`);
+                return;
+            }
+            const line = summarizeAutoPublishReport(report);
+            // eslint-disable-next-line no-console
+            if (line)
+                console.log(line.replace(/^JIRA auto-publish/, 'JIRA publish'));
+            for (const r of report.results) {
+                if (r.status === 'failed') {
+                    // eslint-disable-next-line no-console
+                    console.log(`JIRA: ${r.specId} failed — ${r.note ?? 'unknown error'}`);
+                }
+            }
+            if (report.skipped === 'no-credentials' || countAutoPublishReport(report).failed > 0) {
+                process.exitCode = 1;
+            }
+        }
+        finally {
+            cg.close();
+        }
+    });
     /**
      * specship jira reconcile — detect JIRA-side edits and (with --apply) fold
      * them back into the spec (REQ-JIRATEAM-005). Preview is read-only and the