@rpamis/comet 0.4.0-beta.1 → 0.4.0-beta.11

package/dist/domains/comet-classic/classic-guard.js

@@ -1,14 +1,22 @@
 import { spawnSync } from 'child_process';
 import { createHash } from 'crypto';
-import { existsSync, promises as fs, readFileSync } from 'fs';
+import { promises as fs } from 'fs';
 import path from 'path';
 import { parseDocument } from 'yaml';
+import { latestCommandCheck, } from './classic-command-checks.js';
 import { inspectClassicChange } from './classic-diagnostics.js';
+import { assertClassicLayoutWritable, classicProjectRelative } from './classic-layout.js';
 import { openSpecChangeNameError, resolveClassicChangeDirectory } from './classic-paths.js';
 import { ensureClassicRuntimeRun, transitionClassicRuntimeRun } from './classic-runtime-run.js';
 import { appendClassicStateEvent } from './classic-state-events.js';
 import { CLASSIC_GUARD_TRANSITION_EVENT, applyClassicTransition } from './classic-transitions.js';
 import { classicValidateCommand } from './classic-validate-command.js';
+import { readClassicState } from './classic-store.js';
+import { readClassicConfigValue } from './classic-project-config.js';
+import { readWorkflowProjectConfigDocument } from '../workflow-contract/project-config-reader.js';
+import { classicProjectFileNonempty, classicProjectTargetExists, inspectClassicProjectTarget, readClassicProjectBytes, readClassicProjectFile, } from './classic-protected-path.js';
+import { driftBlockedMessage, resolveBranchBinding, unboundDetachedMessage, } from './classic-branch-binding.js';
+import { classicCommandInvocationCwd, classicCommandProjectRoot, withClassicCommandContext, } from './classic-command-context.js';
 const GREEN = '\u001b[32m';
 const RED = '\u001b[31m';
 const YELLOW = '\u001b[33m';
@@ -76,68 +84,30 @@ class GuardOutput {
     }
 }
 async function exists(file) {
-    try {
-        await fs.access(file);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    }
+    const projectRoot = classicCommandProjectRoot();
+    return classicProjectTargetExists(projectRoot, file, {
+        label: `Classic guard path ${path.relative(projectRoot, path.resolve(projectRoot, file)).replaceAll('\\', '/')}`,
+    });
 }
 async function nonempty(file) {
-    try {
-        return (await fs.stat(file)).size > 0;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    }
+    const projectRoot = classicCommandProjectRoot();
+    return classicProjectFileNonempty(projectRoot, file, `Classic guard file ${path.relative(projectRoot, path.resolve(projectRoot, file)).replaceAll('\\', '/')}`);
 }
 function validateChangeName(name) {
     const error = openSpecChangeNameError(name);
     if (error)
         throw new GuardFailure(red(`ERROR: ${error}`));
 }
-// Resolve the change directory the way the frozen guard does: prefer the active
-// `openspec/changes/<name>` path, fall back to the archive copy. Returns the
-// RELATIVE path (cwd is the project root) so handoff-hash inputs and check
-// output match the frozen `openspec/changes/...` form byte-for-byte.
+// Resolve an absolute change directory for filesystem and runtime consumers.
+// Frozen relative provenance strings are derived separately from projectRoot.
 async function resolveChangeDir(name) {
-    return (await resolveClassicChangeDirectory(name)).label;
-}
-function stripInlineComment(value) {
-    let out = '';
-    let quote = '';
-    for (let i = 0; i < value.length; i += 1) {
-        const c = value[i];
-        if (quote === '') {
-            if (c === '"' || c === "'") {
-                quote = c;
-            }
-            else if (c === '#' && (i === 0 || /\s/u.test(value[i - 1]))) {
-                return out.replace(/\s+$/u, '');
-            }
-        }
-        else if (c === quote) {
-            quote = '';
-        }
-        out += c;
-    }
-    return out;
-}
-function stripWrappingQuotes(value) {
-    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"'))
-        return value.slice(1, -1);
-    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'"))
-        return value.slice(1, -1);
-    return value;
+    return (await resolveClassicChangeDirectory(name, classicCommandProjectRoot())).directory;
 }
 async function readField(changeDir, field) {
     const file = path.join(changeDir, '.comet.yaml');
-    const document = parseDocument(await fs.readFile(file, 'utf8'), { uniqueKeys: false });
+    const document = parseDocument(await readClassicProjectFile(classicCommandProjectRoot(), file, {
+        label: `Classic state ${changeDir}/.comet.yaml`,
+    }), { uniqueKeys: false });
     if (document.errors.length > 0) {
         throw new GuardFailure(`ERROR: Invalid .comet.yaml: ${document.errors[0].message}`);
     }
@@ -153,24 +123,7 @@ async function projectConfigValue(field, changeDir) {
     const changeValue = await readField(changeDir, field);
     if (changeValue && changeValue !== 'null')
         return changeValue;
-    for (const config of [
-        '.comet/config.yaml',
-        '.comet.yaml',
-        'comet.yaml',
-        '.comet.yml',
-        'comet.yml',
-    ]) {
-        if (!(await exists(config)))
-            continue;
-        for (const line of (await fs.readFile(config, 'utf8')).split(/\r?\n/u)) {
-            if (new RegExp(`^${field}:`, 'u').test(line)) {
-                const value = stripWrappingQuotes(stripInlineComment(line.replace(new RegExp(`^${field}:\\s*`, 'u'), '')));
-                if (value && value !== 'null')
-                    return value;
-            }
-        }
-    }
-    return '';
+    return (await readClassicConfigValue(field, { cwd: classicCommandProjectRoot() }))?.value ?? '';
 }
 async function configuredLanguage(changeDir) {
     const language = await projectConfigValue('language', changeDir);
@@ -201,7 +154,9 @@ function countEnglishWords(source) {
 }
 async function documentLanguageMatchesConfigured(changeDir, file) {
     const language = await configuredLanguage(changeDir);
-    const source = stripFencedCodeBlocks(await fs.readFile(file, 'utf8'));
+    const source = stripFencedCodeBlocks(await readClassicProjectFile(classicCommandProjectRoot(), file, {
+        label: `Classic language-check artifact ${file}`,
+    }));
     const cjk = countCjkChars(source);
     const englishWords = countEnglishWords(source);
     if (language === 'zh-CN' && cjk < 20 && englishWords >= 20) {
@@ -212,82 +167,26 @@ async function documentLanguageMatchesConfigured(changeDir, file) {
     }
     return pass();
 }
-// Build/verify commands run through the platform's default shell (cmd.exe on
-// Windows, /bin/sh elsewhere) via `shell: true`, so Comet no longer requires a
-// usable bash. Configured commands are pre-validated to reject shell
-// metacharacters before they ever reach the shell.
-function runCommandString(command) {
-    if (!command)
-        return { status: 1, output: red('ERROR: build/verify command is empty') };
-    const split = splitCommandChain(command);
-    if (typeof split === 'string') {
-        return {
-            status: 1,
-            output: `${red(`ERROR: build/verify command contains shell metacharacters: ${command}`)}\n${red(split)}`,
-        };
-    }
-    const output = [];
-    for (const part of split) {
-        const segment = part.trim();
-        if (!segment) {
-            return { status: 1, output: red('ERROR: build/verify command contains an empty && step') };
-        }
-        const result = spawnSync(segment, { shell: true, encoding: 'utf8', timeout: 300_000 });
-        const combined = `${result.stdout ?? ''}${result.stderr ?? ''}`.replace(/\n+$/u, '');
-        output.push(`${red(`+ ${segment}`)}${combined ? `\n${combined}` : ''}`);
-        if (result.status !== 0) {
-            return { status: result.status ?? 1, output: output.join('\n') };
-        }
-    }
-    return { status: 0, output: output.join('\n') };
-}
-function splitCommandChain(command) {
-    const parts = [];
-    let current = '';
-    let quote = '';
-    for (let i = 0; i < command.length; i += 1) {
-        const c = command[i];
-        if (c === '$' || c === '`') {
-            return 'Allowed: command words, quotes, paths, and && between sequential commands';
-        }
-        if (quote) {
-            current += c;
-            if (c === quote)
-                quote = '';
-            continue;
-        }
-        if (c === '"' || c === "'") {
-            quote = c;
-            current += c;
-            continue;
-        }
-        if (c === '&' && command[i + 1] === '&') {
-            parts.push(current);
-            current = '';
-            i += 1;
-            continue;
-        }
-        if (c === ';' || c === '|' || c === '&') {
-            return 'Allowed: command words, quotes, paths, and && between sequential commands';
-        }
-        current += c;
-    }
-    if (quote)
-        return 'Command has an unmatched quote';
-    parts.push(current);
-    return parts;
-}
-function hashFile(file) {
-    return createHash('sha256').update(readFileSync(file)).digest('hex');
+async function hashFile(file) {
+    return createHash('sha256')
+        .update(await readClassicProjectBytes(classicCommandProjectRoot(), file, {
+        label: `Classic handoff source ${file}`,
+    }))
+        .digest('hex');
 }
 async function handoffSourceFiles(changeDir) {
     // Use forward-slash concatenation (not path.join, which uses the OS separator)
     // so the handoff-hash input and markdown `Source:` references match the frozen
     // shell + comet-handoff provenance byte-for-byte. changeDir is a relative forward-slash
     // path (openspec/changes/<name>); forward slashes are readable on Windows too.
-    const files = [`${changeDir}/proposal.md`, `${changeDir}/design.md`, `${changeDir}/tasks.md`];
-    const specs = `${changeDir}/specs`;
+    const changeRef = classicProjectRelative(classicCommandProjectRoot(), changeDir);
+    const files = [`${changeRef}/proposal.md`, `${changeRef}/design.md`, `${changeRef}/tasks.md`];
+    const specs = `${changeRef}/specs`;
     if (await exists(specs)) {
+        await inspectClassicProjectTarget(classicCommandProjectRoot(), specs, {
+            label: `Classic delta-spec directory ${specs}`,
+            expected: 'directory',
+        });
         for (const entry of (await fs.readdir(specs)).sort()) {
             const spec = `${specs}/${entry}/spec.md`;
             if (await exists(spec))
@@ -300,7 +199,7 @@ async function computeHandoffHash(changeDir) {
     const lines = [];
     for (const file of await handoffSourceFiles(changeDir)) {
         if (await exists(file)) {
-            lines.push(`path:${file}`, `sha256:${hashFile(file)}`);
+            lines.push(`path:${file}`, `sha256:${await hashFile(file)}`);
         }
     }
     // Match the frozen shell: command substitution $(...) strips the trailing
@@ -314,16 +213,29 @@ async function preflight(changeDir, name) {
     if (!(await exists(path.join(changeDir, '.comet.yaml')))) {
         throw new GuardFailure(red(`FATAL: .comet.yaml not found in ${changeDir}`));
     }
+    await inspectClassicProjectTarget(classicCommandProjectRoot(), path.join(changeDir, '.comet'), {
+        label: `Classic runtime directory for ${name}`,
+        expected: 'directory',
+    });
     const result = await classicValidateCommand([name], { json: false });
     if (result.exitCode !== 0) {
         if (result.stderr)
             process.stderr.write(result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`);
         throw new GuardFailure(red('FATAL: .comet.yaml schema validation failed'));
     }
+    const projection = await readClassicState(changeDir);
+    const unknownKeys = Array.from(new Set(projection.unknownKeys)).sort();
+    if (unknownKeys.length > 0) {
+        throw new GuardFailure(red(`FATAL: .comet.yaml has unknown field(s): ${unknownKeys.join(', ')}`));
+    }
 }
 function pushCheck(output, outcome) {
     if (outcome.passed) {
         output.stderr.push(green(`  [PASS] ${outcome.description}`));
+        if (outcome.detail) {
+            for (const line of outcome.detail.split('\n'))
+                output.stderr.push(green(`    ${line}`));
+        }
     }
     else {
         output.stderr.push(red(`  [FAIL] ${outcome.description}`));
@@ -352,8 +264,8 @@ function check(description, run) {
         }
     };
 }
-function pass() {
-    return { passed: true };
+function pass(detail) {
+    return { passed: true, ...(detail ? { detail } : {}) };
 }
 function fail(detail) {
     return { passed: false, detail };
@@ -368,54 +280,115 @@ async function runChecks(output, builders) {
     }
     return blocked;
 }
+const INFERRED_COMMAND_SOURCES = [
+    'package.json with a build script',
+    'pom.xml',
+    'Cargo.toml',
+];
+async function removedProjectCommandField(field) {
+    try {
+        const document = await readWorkflowProjectConfigDocument(classicCommandProjectRoot(), {
+            allowPartialProject: true,
+        });
+        if (!document)
+            return false;
+        return Object.prototype.hasOwnProperty.call(document.value, field);
+    }
+    catch (error) {
+        throw new Error(`.comet/config.yaml is invalid YAML (${error instanceof Error ? error.message : String(error)}); cannot check for removed "${field}" field. Fix the config and retry.`, { cause: error });
+    }
+}
+function removedProjectCommandRun(field) {
+    return {
+        status: 1,
+        output: `${field} has been removed from .comet/config.yaml. Delete this field and run any required ${field === 'build_command' ? 'build' : 'verification'} command manually before retrying.`,
+    };
+}
 function runInferred(command) {
     // Inferred build/verify commands (npm run build, mvn, cargo, …) run through
     // the platform's default shell so .cmd shims resolve on Windows without
     // requiring bash. Output is returned raw (no `+ ` prefix).
-    const result = spawnSync(command, { shell: true, encoding: 'utf8', timeout: 300_000 });
+    const result = spawnSync(command, {
+        shell: true,
+        cwd: classicCommandInvocationCwd(),
+        encoding: 'utf8',
+        timeout: 300_000,
+    });
     return {
         status: result.status ?? 1,
         output: `${result.stdout ?? ''}${result.stderr ?? ''}`.replace(/\n+$/u, ''),
     };
 }
-async function buildPasses(changeDir) {
-    if (process.env.COMET_SKIP_BUILD === '1')
-        return { status: 0, output: '' };
-    const configured = await projectConfigValue('build_command', changeDir);
-    if (configured)
-        return runCommandString(configured);
-    if ((await exists('package.json')) &&
-        /"build"/u.test(await fs.readFile('package.json', 'utf8'))) {
-        return runInferred('npm run build');
-    }
-    if (await exists('pom.xml')) {
+function invocationTarget(relative) {
+    return path.resolve(classicCommandInvocationCwd(), relative);
+}
+async function inferredBuildCommand() {
+    const packageJson = invocationTarget('package.json');
+    if (await exists(packageJson)) {
+        const parsed = JSON.parse(await readClassicProjectFile(classicCommandProjectRoot(), packageJson, {
+            label: 'package.json',
+        }));
+        if (typeof parsed.scripts?.build === 'string')
+            return 'npm run build';
+    }
+    if (await exists(invocationTarget('pom.xml'))) {
         if (process.platform === 'win32') {
-            if (existsSync('mvnw.cmd'))
-                return runInferred('mvnw.cmd compile -q');
-            return runInferred('mvn.cmd compile -q');
+            if (await exists(invocationTarget('mvnw.cmd')))
+                return 'mvnw.cmd compile -q';
+            return 'mvn.cmd compile -q';
         }
-        if (existsSync('mvnw'))
-            return runInferred('./mvnw compile -q');
-        return runInferred('mvn compile -q');
-    }
-    if (await exists('Cargo.toml'))
-        return runInferred('cargo build');
-    return { status: 1, output: '' };
-}
-async function verificationCommandPasses(changeDir) {
-    if (process.env.COMET_SKIP_BUILD === '1')
-        return { status: 0, output: '' };
-    const configured = await projectConfigValue('verify_command', changeDir);
-    if (configured)
-        return runCommandString(configured);
-    return buildPasses(changeDir);
+        if (await exists(invocationTarget('mvnw')))
+            return './mvnw compile -q';
+        return 'mvn compile -q';
+    }
+    if (await exists(invocationTarget('Cargo.toml')))
+        return 'cargo build';
+    return null;
+}
+function evidenceDetail(record) {
+    return `Evidence: recorded command-check at ${record.timestamp}; command: ${record.command}; cwd: ${record.cwd}`;
+}
+function recoveryCommand(change, scope, command) {
+    return `comet state record-check ${change} ${scope} --command "${command}" --exit-code 0`;
+}
+async function commandCheckPasses(changeDir, change, run, scope) {
+    if (process.env.COMET_SKIP_BUILD === '1') {
+        return { status: 0, output: 'SKIPPED via COMET_SKIP_BUILD=1' };
+    }
+    const removedFields = scope === 'build' ? ['build_command'] : ['verify_command', 'build_command'];
+    for (const removedField of removedFields) {
+        if (await removedProjectCommandField(removedField)) {
+            return removedProjectCommandRun(removedField);
+        }
+    }
+    const inferred = scope === 'build' ? await inferredBuildCommand() : null;
+    if (inferred)
+        return runInferred(inferred);
+    const recorded = await latestCommandCheck(classicCommandProjectRoot(), changeDir, run, scope);
+    if (!recorded) {
+        return {
+            status: 1,
+            output: scope === 'build'
+                ? `No inferred build command or recorded build check. Detection searched: ${INFERRED_COMMAND_SOURCES.join(', ')}.\nNext: run the required command, then record it with:\n${recoveryCommand(change, scope, '<command>')}`
+                : `No recorded verify check.\nNext: run the required verification command, then record it with:\n${recoveryCommand(change, scope, '<command>')}`,
+        };
+    }
+    if (recorded.exitCode !== 0) {
+        return {
+            status: recorded.exitCode,
+            output: `Latest recorded ${scope} check failed with exit code ${recorded.exitCode}.\n${evidenceDetail(recorded)}\nNext: rerun the command successfully, then record it with:\n${recoveryCommand(change, scope, recorded.command)}`,
+        };
+    }
+    return { status: 0, output: evidenceDetail(recorded) };
 }
 async function tasksAllDone(changeDir) {
     const tasks = path.join(changeDir, 'tasks.md');
     if (!(await exists(tasks))) {
         return fail(`tasks.md is missing at ${tasks}\nNext: restore or create tasks.md for this change before leaving build.`);
     }
-    const source = await fs.readFile(tasks, 'utf8');
+    const source = await readClassicProjectFile(classicCommandProjectRoot(), tasks, {
+        label: `Classic tasks ${tasks}`,
+    });
     if (!/- \[x\]/u.test(source)) {
         return fail("tasks.md has no completed tasks.\nNext: complete implementation tasks and mark them with '- [x]'.");
     }
@@ -432,7 +405,9 @@ async function tasksHasAny(changeDir) {
     const tasks = path.join(changeDir, 'tasks.md');
     if (!(await exists(tasks)))
         return false;
-    return /- \[/u.test(await fs.readFile(tasks, 'utf8'));
+    return /- \[/u.test(await readClassicProjectFile(classicCommandProjectRoot(), tasks, {
+        label: `Classic tasks ${tasks}`,
+    }));
 }
 async function planTasksAllDone(changeDir) {
     const plan = await readField(changeDir, 'plan');
@@ -441,7 +416,9 @@ async function planTasksAllDone(changeDir) {
     if (!(await exists(plan))) {
         return fail(`plan file is missing at ${plan}\nNext: restore the Superpowers plan file or update .comet.yaml plan before leaving build.`);
     }
-    const source = await fs.readFile(plan, 'utf8');
+    const source = await readClassicProjectFile(classicCommandProjectRoot(), plan, {
+        label: `Classic plan ${plan}`,
+    });
     const unfinished = source
         .split(/\r?\n/u)
         .map((line, index) => ({ line, number: index + 1 }))
@@ -451,17 +428,46 @@ async function planTasksAllDone(changeDir) {
     }
     return pass();
 }
+async function boundBranchMatches(changeDir, change) {
+    let outcome;
+    try {
+        outcome = await resolveBranchBinding(changeDir, {
+            heal: true,
+            cwd: classicCommandInvocationCwd(),
+        });
+    }
+    catch (error) {
+        throw new GuardFailure(`ERROR: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    switch (outcome.status) {
+        case 'drift':
+            return fail(driftBlockedMessage(change, outcome.boundBranch, outcome.currentBranch));
+        case 'unbound-detached':
+            return fail(unboundDetachedMessage(change));
+        case 'healed':
+            return pass(`bound_branch lazily set to ${outcome.branch}`);
+        case 'needs-heal':
+        case 'ok':
+        case 'not-applicable':
+            return pass();
+        default: {
+            const exhaustive = outcome;
+            throw new Error(`unhandled branch binding status: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
 async function isolationSelected(changeDir, change) {
     const isolation = await readField(changeDir, 'isolation');
-    if (isolation === 'branch' || isolation === 'worktree')
+    if (isolation === 'current' || isolation === 'branch' || isolation === 'worktree')
         return pass();
-    return fail(`isolation must be branch or worktree, got '${isolation || 'null'}'\nNext: ask the user to choose branch or worktree, create the chosen isolation, then run:\n  node "$COMET_STATE" set ${change} isolation <branch|worktree>`);
+    const allowedValues = '<current|branch|worktree>';
+    return fail(`isolation must be current, branch, or worktree, got '${isolation || 'null'}'\nNext: choose a valid workspace mode, prepare it when needed, then run:\n  comet state set ${change} isolation ${allowedValues}`);
 }
 async function buildModeSelected(changeDir, change) {
     const buildMode = await readField(changeDir, 'build_mode');
     if (['subagent-driven-development', 'executing-plans', 'direct'].includes(buildMode))
         return pass();
-    return fail(`build_mode must be selected before leaving build, got '${buildMode || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  node "$COMET_STATE" set ${change} build_mode <subagent-driven-development|executing-plans>`);
+    return fail(`build_mode must be selected before leaving build, got '${buildMode || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  comet state set ${change} build_mode <subagent-driven-development|executing-plans>`);
 }
 async function buildModeAllowedForWorkflow(changeDir) {
     const workflow = await readField(changeDir, 'workflow');
@@ -482,7 +488,7 @@ async function subagentDispatchConfirmed(changeDir, change) {
         return pass();
     if (subagentDispatch === 'confirmed')
         return pass();
-    return fail(`subagent_dispatch must be confirmed before using build_mode=subagent-driven-development\nNext: confirm the current platform has a real background subagent/Task/multi-agent dispatcher, then run:\n  node "$COMET_STATE" set ${change} subagent_dispatch confirmed\nOr ask the user to switch to executing-plans and run:\n  node "$COMET_STATE" set ${change} build_mode executing-plans`);
+    return fail(`subagent_dispatch must be confirmed before using build_mode=subagent-driven-development\nNext: confirm the current platform has a real background subagent/Task/multi-agent dispatcher, then run:\n  comet state set ${change} subagent_dispatch confirmed\nIf dispatch is unavailable, return to /comet-build Step 2 with subagent-driven-development removed. When executing-plans is the only valid mode, run:\n  comet state set ${change} build_mode executing-plans`);
 }
 async function tddModeSelected(changeDir, change) {
     const workflow = await readField(changeDir, 'workflow');
@@ -491,7 +497,7 @@ async function tddModeSelected(changeDir, change) {
     const tddMode = await readField(changeDir, 'tdd_mode');
     if (tddMode === 'tdd' || tddMode === 'direct')
         return pass();
-    return fail(`tdd_mode must be tdd or direct for full workflow, got '${tddMode || 'null'}'\nNext: ask the user to choose TDD enforcement level, then run:\n  node "$COMET_STATE" set ${change} tdd_mode <tdd|direct>`);
+    return fail(`tdd_mode must be tdd or direct for full workflow, got '${tddMode || 'null'}'\nNext: ask the user to choose TDD enforcement level, then run:\n  comet state set ${change} tdd_mode <tdd|direct>`);
 }
 async function reviewModeSelected(changeDir, change) {
     const workflow = await readField(changeDir, 'workflow');
@@ -501,11 +507,11 @@ async function reviewModeSelected(changeDir, change) {
     if (reviewMode === 'off' || reviewMode === 'standard' || reviewMode === 'thorough') {
         return pass();
     }
-    return fail(`review_mode must be off, standard, or thorough before leaving build, got '${reviewMode || 'null'}'\nNext: ask the user to choose review strength, then run:\n  node "$COMET_STATE" set ${change} review_mode <off|standard|thorough>`);
+    return fail(`review_mode must be off, standard, or thorough before leaving build, got '${reviewMode || 'null'}'\nNext: ask the user to choose review strength, then run:\n  comet state set ${change} review_mode <off|standard|thorough>`);
 }
 async function verificationReportExists(changeDir) {
     const report = await readField(changeDir, 'verification_report');
-    return Boolean(report) && report !== 'null' && existsSync(report);
+    return Boolean(report) && report !== 'null' && (await exists(report));
 }
 async function branchStatusHandled(changeDir) {
     return (await readField(changeDir, 'branch_status')) === 'handled';
@@ -514,7 +520,9 @@ async function archivedIsTrue(changeDir) {
     return (await readField(changeDir, 'archived')) === 'true';
 }
 async function designDocFrontmatterHas(designDoc, field, expected) {
-    const source = (await fs.readFile(designDoc, 'utf8')).replace(/^\uFEFF/u, '');
+    const source = (await readClassicProjectFile(classicCommandProjectRoot(), designDoc, {
+        label: `Classic Design Doc ${designDoc}`,
+    })).replace(/^\uFEFF/u, '');
     let inFrontmatter = false;
     for (const line of source.split(/\r?\n/u)) {
         if (!inFrontmatter) {
@@ -531,9 +539,9 @@ async function designDocFrontmatterHas(designDoc, field, expected) {
 }
 async function designDocRecorded(changeDir, change) {
     const designDoc = await readField(changeDir, 'design_doc');
-    if (designDoc && designDoc !== 'null' && existsSync(designDoc))
+    if (designDoc && designDoc !== 'null' && (await exists(designDoc)))
         return pass();
-    return fail(`design_doc must point to an existing Superpowers Design Doc for full workflow before leaving design.\nNext: create the Design Doc and run: node "$COMET_STATE" set ${change} design_doc <path>`);
+    return fail(`design_doc must point to an existing Superpowers Design Doc for full workflow before leaving design.\nNext: create the Design Doc and run: comet state set ${change} design_doc <path>`);
 }
 async function designHandoffContextValid(changeDir, change) {
     const context = await readField(changeDir, 'handoff_context');
@@ -542,18 +550,18 @@ async function designHandoffContextValid(changeDir, change) {
         return fail(`handoff_context is missing from .comet.yaml\nNext: run node "$COMET_HANDOFF" ${change} design --write before invoking Superpowers.`);
     }
     if (!(await nonempty(context))) {
-        return fail(`handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet-handoff.mjs.`);
+        return fail(`handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet handoff ${change} design --write.`);
     }
     if (!/^[a-f0-9]{64}$/u.test(recordedHash)) {
-        return fail(`handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet-handoff.mjs.`);
+        return fail(`handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet handoff ${change} design --write.`);
     }
     const actualHash = await computeHandoffHash(changeDir);
     if (actualHash !== recordedHash) {
-        return fail(`OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: rerun comet-handoff.mjs so Superpowers receives the current OpenSpec context.`);
+        return fail(`OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: run comet handoff ${change} design --write so Superpowers receives the current OpenSpec context.`);
     }
     const markdown = `${context.replace(/\.json$/u, '')}.md`;
     if (!(await nonempty(markdown))) {
-        return fail(`design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet-handoff.mjs.`);
+        return fail(`design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet handoff ${change} design --write.`);
     }
     return pass();
 }
@@ -564,7 +572,10 @@ async function designHandoffMarkdownTraceable(changeDir) {
     const markdown = `${context.replace(/\.json$/u, '')}.md`;
     if (!(await nonempty(markdown)))
         return fail(`design handoff markdown is missing or empty: ${markdown}`);
-    const source = await fs.readFile(markdown, 'utf8');
+    const source = await readClassicProjectFile(classicCommandProjectRoot(), markdown, {
+        label: `Classic handoff markdown ${markdown}`,
+    });
+    const lines = new Set(source.split(/\r?\n/u));
     const problems = [];
     if (!/^Generated-by: comet-handoff\.sh$/mu.test(source)) {
         problems.push('handoff markdown is missing Generated-by marker');
@@ -575,10 +586,10 @@ async function designHandoffMarkdownTraceable(changeDir) {
     for (const file of await handoffSourceFiles(changeDir)) {
         if (!(await exists(file)))
             continue;
-        if (!new RegExp(`^- Source: ${file}$`, 'mu').test(source)) {
+        if (!lines.has(`- Source: ${file}`)) {
             problems.push(`handoff markdown is missing source reference: ${file}`);
         }
-        if (!new RegExp(`^- SHA256: ${hashFile(file)}$`, 'mu').test(source)) {
+        if (!lines.has(`- SHA256: ${await hashFile(file)}`)) {
             problems.push(`handoff markdown is missing current sha256 for: ${file}`);
         }
     }
@@ -595,7 +606,9 @@ async function betaSpecJsonStructurallyValid(changeDir) {
         return fail('handoff_context is missing from .comet.yaml');
     if (!(await nonempty(context)))
         return fail(`spec-context.json is missing or empty: ${context}`);
-    const source = await fs.readFile(context, 'utf8');
+    const source = await readClassicProjectFile(classicCommandProjectRoot(), context, {
+        label: `Classic handoff context ${context}`,
+    });
     const problems = [];
     let parsed;
     try {
@@ -698,8 +711,9 @@ async function guardDesignChecks(output, changeDir, change) {
     }
     return blocked;
 }
-async function guardBuildChecks(output, changeDir, change) {
+async function guardBuildChecks(output, changeDir, change, run) {
     return runChecks(output, [
+        check('bound branch matches workspace mode', () => boundBranchMatches(changeDir, change)),
         check('isolation selected', () => isolationSelected(changeDir, change)),
         check('build_mode selected', () => buildModeSelected(changeDir, change)),
         check('build_mode allowed for workflow', () => buildModeAllowedForWorkflow(changeDir)),
@@ -719,19 +733,20 @@ async function guardBuildChecks(output, changeDir, change) {
         // Build check runs last — only after all config checks pass — to avoid
         // wasting time on a build that would be rejected by a config failure.
         check('Build passes', async () => {
-            const buildResult = await buildPasses(changeDir);
-            return buildResult.status === 0 ? pass() : fail(buildResult.output);
+            const buildResult = await commandCheckPasses(changeDir, change, run, 'build');
+            return buildResult.status === 0 ? pass(buildResult.output) : fail(buildResult.output);
         }),
     ]);
 }
-async function guardVerifyChecks(output, changeDir) {
+async function guardVerifyChecks(output, changeDir, change, run) {
     return runChecks(output, [
+        check('bound branch matches workspace mode', () => boundBranchMatches(changeDir, change)),
         check('tasks.md all tasks checked', () => tasksAllDone(changeDir)),
         // Verification command runs after tasks check — no point running tests
         // if tasks.md is incomplete.
         check('Verification passes', async () => {
-            const verifyResult = await verificationCommandPasses(changeDir);
-            return verifyResult.status === 0 ? pass() : fail(verifyResult.output);
+            const verifyResult = await commandCheckPasses(changeDir, change, run, 'verify');
+            return verifyResult.status === 0 ? pass(verifyResult.output) : fail(verifyResult.output);
         }),
         check('verification_report exists', async () => (await verificationReportExists(changeDir)) ? pass() : fail('')),
         check('verification_report matches configured language', async () => {
@@ -740,21 +755,26 @@ async function guardVerifyChecks(output, changeDir) {
                 return pass();
             return documentLanguageMatchesConfigured(changeDir, report);
         }),
-        check('branch_status=handled', async () => (await branchStatusHandled(changeDir)) ? pass() : fail('')),
     ]);
 }
-async function guardArchiveChecks(output, changeDir) {
+async function guardArchiveChecks(output, changeDir, change) {
     return runChecks(output, [
+        check('bound branch matches workspace mode', () => boundBranchMatches(changeDir, change)),
         check('archived is true', async () => ((await archivedIsTrue(changeDir)) ? pass() : fail(''))),
         check('proposal.md exists', async () => (await nonempty(path.join(changeDir, 'proposal.md'))) ? pass() : fail('')),
         check('design.md exists', async () => (await nonempty(path.join(changeDir, 'design.md'))) ? pass() : fail('')),
         check('tasks.md all tasks checked', () => tasksAllDone(changeDir)),
+        check('branch_status=handled', async () => (await branchStatusHandled(changeDir)) ? pass() : fail('')),
     ]);
 }
-async function applyStateUpdate(output, change, changeDir, phase, context) {
+async function applyStateUpdate(output, change, changeDir, phase) {
     const event = CLASSIC_GUARD_TRANSITION_EVENT[phase];
     if (!event)
         return;
+    // Re-read instead of reusing the run context captured before the checks:
+    // boundBranchMatches may have lazily healed bound_branch on disk, and a
+    // stale projection would write the pre-heal null back over it.
+    const context = await ensureClassicRuntimeRun(changeDir);
     const result = applyClassicTransition(context.classic, event);
     await transitionClassicRuntimeRun(changeDir, result.classic, context.run, {
         event,
@@ -777,7 +797,7 @@ async function applyStateUpdate(output, change, changeDir, phase, context) {
     const message = phase === 'open' ? template.replace('PLACEHOLDER', result.classic.phase) : template;
     output.stderr.push(green(message));
 }
-export const classicGuardCommand = async (args, options) => {
+export const classicGuardCommand = async (args, options) => withClassicCommandContext(options, async () => {
     const output = new GuardOutput();
     const [change, phase, flag] = args;
     try {
@@ -785,6 +805,7 @@ export const classicGuardCommand = async (args, options) => {
         if (!phase || !PHASES.includes(phase)) {
             throw new GuardFailure(`${red(`Unknown phase: ${phase ?? ''}`)}\nValid phases: open, design, build, verify, archive`);
         }
+        await assertClassicLayoutWritable(classicCommandProjectRoot());
         const changeDir = await resolveChangeDir(change);
         await preflight(changeDir, change);
         const runContext = await ensureClassicRuntimeRun(changeDir);
@@ -804,11 +825,11 @@ export const classicGuardCommand = async (args, options) => {
         else if (phase === 'design')
             blocked = await guardDesignChecks(output, changeDir, change);
         else if (phase === 'build')
-            blocked = await guardBuildChecks(output, changeDir, change);
+            blocked = await guardBuildChecks(output, changeDir, change, runContext.run);
         else if (phase === 'verify')
-            blocked = await guardVerifyChecks(output, changeDir);
+            blocked = await guardVerifyChecks(output, changeDir, change, runContext.run);
         else
-            blocked = await guardArchiveChecks(output, changeDir);
+            blocked = await guardArchiveChecks(output, changeDir, change);
         if (blocked) {
             output.stderr.push('');
             output.stderr.push(red('BLOCKED — fix failing checks before proceeding to next phase'));
@@ -817,7 +838,7 @@ export const classicGuardCommand = async (args, options) => {
         output.stderr.push('');
         output.stderr.push(green('ALL CHECKS PASSED — ready for next phase'));
         if (flag === '--apply') {
-            await applyStateUpdate(output, change, changeDir, phase, runContext);
+            await applyStateUpdate(output, change, changeDir, phase);
         }
         return output.toResult(0);
     }
@@ -829,5 +850,5 @@ export const classicGuardCommand = async (args, options) => {
         }
         throw error;
     }
-};
+});
 //# sourceMappingURL=classic-guard.js.map