@open-agent-toolkit/cli 0.3.9 → 0.3.11

package/dist/commands/instructions/instructions.utils.js

@@ -122,23 +122,11 @@ export async function inspectManagedShim(claudePath, agentsPath, dependencies) {
             detail: `unable to read AGENTS.md (${getErrorCode(error) ?? 'unknown error'})`,
         };
     }
-    let agentsResolvesToClaude = agentsStats.dev === claudeStats.dev && agentsStats.ino === claudeStats.ino;
-    if (agentsStats.isSymbolicLink()) {
-        try {
-            const [realAgents, realClaude] = await Promise.all([
-                dependencies.realpath(agentsPath),
-                dependencies.realpath(claudePath),
-            ]);
-            agentsResolvesToClaude = realAgents === realClaude;
-        }
-        catch (error) {
-            return {
-                kind: 'unreadable',
-                detail: `unable to resolve AGENTS.md (${getErrorCode(error) ?? 'unknown error'})`,
-            };
-        }
+    const resolution = await agentsResolvesToClaude(agentsPath, agentsStats, claudeStats, dependencies);
+    if (typeof resolution === 'string') {
+        return { kind: 'unreadable', detail: resolution };
     }
-    if (agentsResolvesToClaude) {
+    if (resolution) {
         return {
             kind: 'unmanaged',
             detail: 'AGENTS.md resolves to this CLAUDE.md, so CLAUDE.md holds the instructions ' +
@@ -184,6 +172,90 @@ export async function inspectManagedShim(claudePath, agentsPath, dependencies) {
         detail: 'hand-written or modified CLAUDE.md; kept',
     };
 }
+/**
+ * Whether `agentsPath` resolves to the regular file `claudePath`: a hard link
+ * of it, or a symlink chain whose endpoint is that file or a hard link of it.
+ * Such a CLAUDE.md holds the only copy of the instructions behind that
+ * AGENTS.md. Both stats come from `lstat`, and a symlinked AGENTS.md is judged
+ * by the device and inode of its resolved endpoint, not by its realpath
+ * spelling: `pkg/AGENTS.md -> ../alias.md`, with `alias.md` hard-linked to
+ * CLAUDE.md, has a different realpath but reaches the same file.
+ *
+ * Callers pass a regular CLAUDE.md, so the ordinary `CLAUDE.md -> AGENTS.md`
+ * shim, where CLAUDE.md is the symlink, never reaches this check.
+ *
+ * Returns the answer, or the reason it could not be decided.
+ */
+async function agentsResolvesToClaude(agentsPath, agentsStats, claudeStats, dependencies) {
+    if (!agentsStats.isSymbolicLink()) {
+        return (agentsStats.dev === claudeStats.dev && agentsStats.ino === claudeStats.ino);
+    }
+    try {
+        const endpoint = await dependencies.lstat(await dependencies.realpath(agentsPath));
+        return endpoint.dev === claudeStats.dev && endpoint.ino === claudeStats.ino;
+    }
+    catch (error) {
+        return `unable to resolve AGENTS.md (${getErrorCode(error) ?? 'unknown error'})`;
+    }
+}
+/**
+ * The AGENTS.md files among `agentsPaths` that resolve to `claudePath`, the
+ * check that keeps `instructions sync --force` from overwriting the only copy
+ * of the instructions under a shim strategy. A regular CLAUDE.md is judged as
+ * the `none` classification judges it (hard link, or a symlink chain that
+ * ends at it); a CLAUDE.md that is itself a symlink counts only when an
+ * AGENTS.md chain passes through it, so the ordinary `CLAUDE.md -> AGENTS.md`
+ * shim is never mistaken for a link the other way.
+ *
+ * A missing CLAUDE.md or AGENTS.md links nothing. Any other read failure is
+ * returned as the reason the answer is unknown, and the caller keeps the file.
+ */
+export async function findAgentsResolvingTo(claudePath, agentsPaths, dependencies) {
+    let claudeStats;
+    try {
+        claudeStats = await dependencies.lstat(claudePath);
+    }
+    catch (error) {
+        const errorCode = getErrorCode(error);
+        return errorCode === 'ENOENT'
+            ? { linkers: [] }
+            : {
+                unreadable: `unable to read CLAUDE.md (${errorCode ?? 'unknown error'})`,
+            };
+    }
+    if (claudeStats.isSymbolicLink()) {
+        return {
+            linkers: await findLinksThrough(claudePath, agentsPaths, dependencies),
+        };
+    }
+    if (!claudeStats.isFile()) {
+        return { linkers: [] };
+    }
+    const linkers = [];
+    for (const agentsPath of new Set(agentsPaths)) {
+        let agentsStats;
+        try {
+            agentsStats = await dependencies.lstat(agentsPath);
+        }
+        catch (error) {
+            const errorCode = getErrorCode(error);
+            if (errorCode === 'ENOENT') {
+                continue;
+            }
+            return {
+                unreadable: `unable to read AGENTS.md (${errorCode ?? 'unknown error'})`,
+            };
+        }
+        const resolution = await agentsResolvesToClaude(agentsPath, agentsStats, claudeStats, dependencies);
+        if (typeof resolution === 'string') {
+            return { unreadable: resolution };
+        }
+        if (resolution) {
+            linkers.push(agentsPath);
+        }
+    }
+    return { linkers: linkers.sort((left, right) => left.localeCompare(right)) };
+}
 /**
  * The path of a directory entry itself, with its parent directories resolved
  * but the entry not followed, so a link and the file it names compare by the
@@ -246,7 +318,7 @@ export async function findLinksThrough(targetPath, candidates, dependencies) {
     return linkers.sort((left, right) => left.localeCompare(right));
 }
 /** `a` / `a and b` / `a, b, and c`, repository-relative. */
-function describeLinkers(repoRoot, linkers) {
+export function describeLinkers(repoRoot, linkers) {
     const paths = linkers.map((path) => toPosixPath(relative(repoRoot, path)));
     if (paths.length <= 2) {
         return paths.join(' and ');

package/dist/commands/instructions/sync/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/sync/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,EAAE,EAGH,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAKL,KAAK,mCAAmC,EAEzC,MAAM,2CAA2C,CAAC;AAuBnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AAiiBD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CAyLT"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/sync/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,EAAE,EAGH,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAKL,KAAK,mCAAmC,EAEzC,MAAM,2CAA2C,CAAC;AAyBnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AA2lBD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CAkMT"}

package/dist/commands/instructions/sync/sync.js

@@ -2,7 +2,7 @@ import { lstat, readFile, readlink, realpath, rm, symlink, writeFile, } from 'no
 import { dirname, join, relative } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
 import { INSTRUCTION_SYNC_STRATEGIES, } from '../../instructions/instructions.types.js';
-import { buildInstructionsPayload, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, readConfiguredInstructionSyncStrategy, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, findLeftoverClaudeFiles, findLinksThrough, inspectManagedShim, buildLeftoverClaudeWarnings, buildShimRemovalBlockWarning, describeShimRemovalBlock, findShimRemovalBlockers, omitHeldBackLeftovers, markBlockedShimEntries, scanInstructionFiles, verifyManagedShimUnchanged, } from '../../instructions/instructions.utils.js';
+import { buildInstructionsPayload, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, readConfiguredInstructionSyncStrategy, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, describeLinkers, findAgentsResolvingTo, findLeftoverClaudeFiles, findLinksThrough, inspectManagedShim, buildLeftoverClaudeWarnings, buildShimRemovalBlockWarning, describeShimRemovalBlock, findShimRemovalBlockers, omitHeldBackLeftovers, markBlockedShimEntries, scanInstructionFiles, verifyManagedShimUnchanged, } from '../../instructions/instructions.utils.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -213,6 +213,50 @@ function planSyncActions({ entries, force, strategy, }) {
     }
     return actions;
 }
+/**
+ * Under a shim strategy, keep every CLAUDE.md that an AGENTS.md resolves to
+ * (a symlink, a symlink chain, or a hard link) instead of overwriting it:
+ * that CLAUDE.md holds the only copy of the instructions behind the link.
+ * Planning-time only; a planned overwrite of any other file is unchanged.
+ */
+async function keepClaudeFilesAgentsResolveTo(actions, entries, dependencies, repoRoot) {
+    const claudePaths = new Set(entries.map((entry) => entry.claudePath));
+    const agentsPaths = entries.flatMap((entry) => entry.agentsPath === null || hasUnreadableCanonicalAgents(entry)
+        ? []
+        : [entry.agentsPath]);
+    if (agentsPaths.length === 0) {
+        return actions;
+    }
+    const kept = [];
+    for (const action of actions) {
+        if (action.type !== 'update' || !claudePaths.has(action.target)) {
+            kept.push(action);
+            continue;
+        }
+        const resolution = await findAgentsResolvingTo(action.target, agentsPaths, dependencies);
+        if ('unreadable' in resolution) {
+            kept.push({
+                type: 'skip',
+                target: action.target,
+                reason: `cannot tell whether an AGENTS.md resolves to this CLAUDE.md (${resolution.unreadable}); kept`,
+                result: 'skipped',
+            });
+            continue;
+        }
+        if (resolution.linkers.length === 0) {
+            kept.push(action);
+            continue;
+        }
+        const verb = resolution.linkers.length === 1 ? 'resolves' : 'resolve';
+        kept.push({
+            type: 'skip',
+            target: action.target,
+            reason: `${describeLinkers(repoRoot, resolution.linkers)} ${verb} to this CLAUDE.md, so it holds the instructions; kept`,
+            result: 'skipped',
+        });
+    }
+    return kept;
+}
 async function applySyncActions(actions, entries, dependencies, strategy, repoRoot) {
     const appliedActions = [];
     const entriesByTarget = new Map();
@@ -454,11 +498,14 @@ export function createInstructionsSyncCommand(overrides = {}) {
                 ? await dependencies.findLeftoverClaudeFiles(repoRoot)
                 : [];
             const blockers = findShimRemovalBlockers(entries, leftoversBeforeSync);
-            const unblockedActions = planSyncActions({
+            const plannedOverwrites = planSyncActions({
                 entries,
                 force: options.force ?? false,
                 strategy,
             });
+            const unblockedActions = strategy === 'none'
+                ? plannedOverwrites
+                : await keepClaudeFilesAgentsResolveTo(plannedOverwrites, entries, dependencies, repoRoot);
             const heldBack = unblockedActions
                 .filter((action) => action.type === 'remove')
                 .map((action) => action.target);

package/dist/commands/pjm/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AAMpC,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE;QACR,iBAAiB,EAAE,mBAAmB,CAAC;QACvC,SAAS,EAAE,mBAAmB,CAAC;KAChC,CAAC;CACH;AAsBD,eAAO,MAAM,sBAAsB,QAIoB,CAAC;AAOxD,eAAO,MAAM,gCAAgC,0FAC4C,CAAC;AAC1F,eAAO,MAAM,8BAA8B,QAG4C,CAAC;AACxF,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAMR;AAeD,eAAO,MAAM,8BAA8B,kVAIjC,CAAC;AAEX,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAiC7C,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAsHlC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AAKpC,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE;QACR,iBAAiB,EAAE,mBAAmB,CAAC;QACvC,SAAS,EAAE,mBAAmB,CAAC;KAChC,CAAC;CACH;AAsBD,eAAO,MAAM,sBAAsB,QAIoB,CAAC;AAOxD,eAAO,MAAM,gCAAgC,0FAC4C,CAAC;AAC1F,eAAO,MAAM,8BAA8B,QAG4C,CAAC;AACxF,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAMR;AAeD,eAAO,MAAM,8BAA8B,kVAIjC,CAAC;AAEX,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAiC7C,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAsHlC"}

package/dist/commands/pjm/init.js

@@ -6,8 +6,8 @@ import { initializeDecisionRecords } from '../decision/init.js';
 import { buildProjectManagementAgentsSectionBody, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, } from '../init/tools/project-management/agents-guidance.js';
 import { upsertAgentsMdSections, } from '../shared/agents-md.js';
 import { stripTemplateFrontmatter } from '../shared/strip-template-frontmatter.js';
+import { resolveTemplate } from '../shared/template-source.js';
 import { readOatConfig, writeOatConfig } from '../../config/oat-config.js';
-import { resolvePjmTemplate } from './template-source.js';
 const TEMPLATE_TARGETS = [
     { template: 'repo-agents.md', target: 'AGENTS.md' },
     { template: 'pjm-agents.md', target: 'pjm/AGENTS.md' },
@@ -89,7 +89,7 @@ export async function initializeRepoReference(options) {
             skipped.push(target.target);
             continue;
         }
-        const template = await resolvePjmTemplate({
+        const template = await resolveTemplate({
             name: target.template,
             assetsRoot: options.assetsRoot,
             templatesRoot: options.templatesRoot,

package/dist/commands/project/closeout-check/closeout-invariant.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The closeout invariant shared by `oat project closeout-check` and
+ * `oat project complete-state` (BL-260806-fail-closed-when-configured).
+ *
+ * A closeout that the implement skill must snapshot (configured
+ * `workflow.postImplementSequence`, autonomous, or lite) cannot reach terminal
+ * completion until its durable `oat_post_implement_sequence` snapshot exists,
+ * every stored step is recorded complete, approval is recorded, and the
+ * snapshot reached `status: complete`. The snapshot schema is the one
+ * `oat-project-implement/references/completion-and-closeout.md` Step 15
+ * persists. Once a snapshot exists it is authoritative: current configuration
+ * is never consulted, so a later config change cannot invalidate a persisted
+ * run.
+ */
+export declare const SEQUENCE_FIELD = "oat_post_implement_sequence";
+export declare const RECOVERY_SKILL = "oat-project-implement";
+declare const POST_APPROVAL_STEPS: readonly ['summary', 'document', 'pr', 'retro'];
+declare const SEQUENCE_STATUSES: readonly ['pre_approval', 'awaiting_approval', 'post_approval', 'failed', 'complete'];
+declare const APPROVALS: readonly ['pending', 'approved', 'not_required'];
+declare const SOURCES: readonly ['configured', 'autonomous-default'];
+export type SequenceStep = (typeof POST_APPROVAL_STEPS)[number];
+export type SequencePhase = 'pre_approval' | 'post_approval';
+export declare const STEP_SKILLS: Record<SequenceStep, string>;
+export interface CloseoutSnapshot {
+    status: (typeof SEQUENCE_STATUSES)[number];
+    source: (typeof SOURCES)[number] | null;
+    preApproval: SequenceStep[];
+    preApprovalCompleted: SequenceStep[];
+    approval: (typeof APPROVALS)[number];
+    postApproval: SequenceStep[];
+    postApprovalCompleted: SequenceStep[];
+    failure: unknown;
+}
+export type CloseoutInvariant = 'snapshot_missing' | 'snapshot_malformed' | 'sequence_failed' | 'pre_approval_step_pending' | 'approval_pending' | 'post_approval_step_pending' | 'sequence_not_complete';
+export type CloseoutNextOwner = {
+    kind: 'snapshot';
+    skill: string;
+} | {
+    kind: 'step';
+    phase: SequencePhase;
+    step: SequenceStep;
+    skill: string;
+} | {
+    kind: 'approval';
+    skill: string;
+    /**
+     * The two valid approval writes: `approved` after final HiLL sign-off,
+     * `not_required` when no final checkpoint exists (Step 15 item 5).
+     */
+    writes: readonly ['approval: approved', 'approval: not_required'];
+} | {
+    kind: 'sequence-status';
+    skill: string;
+};
+export type SnapshotRequirementReason = 'lite' | 'autonomous' | 'configured';
+export interface CloseoutInputs {
+    workflowMode: string;
+    lite: boolean;
+    autonomous: boolean;
+    autonomousSource: 'flag' | 'env' | null;
+    /** Null when configuration was not consulted (snapshot present, or lite/autonomous already decided). */
+    configured: boolean | null;
+    snapshot: 'absent' | 'present';
+    snapshotSource: string | null;
+}
+export type CloseoutResult = {
+    status: 'complete';
+    inputs: CloseoutInputs;
+} | {
+    status: 'not_required';
+    inputs: CloseoutInputs;
+} | {
+    status: 'incomplete';
+    invariant: CloseoutInvariant;
+    detail: string;
+    route: typeof RECOVERY_SKILL;
+    nextOwner: CloseoutNextOwner;
+    inputs: CloseoutInputs;
+};
+export interface EvaluateCloseoutOptions {
+    stateContent: string;
+    autonomousFlag: boolean;
+    env: NodeJS.ProcessEnv;
+    /** Resolves the effective layered `workflow.postImplementSequence`; called only when needed. */
+    resolveConfigured: () => Promise<boolean>;
+}
+export declare function parseCloseoutSnapshot(value: unknown): CloseoutSnapshot;
+export declare function evaluateCloseout(options: EvaluateCloseoutOptions): Promise<CloseoutResult>;
+/**
+ * The one refusal message both commands print, so a skill or operator sees the
+ * same invariant and recovery route from either.
+ */
+export declare function formatCloseoutRefusal(projectPath: string, result: Extract<CloseoutResult, {
+    status: 'incomplete';
+}>): string;
+export {};
+//# sourceMappingURL=closeout-invariant.d.ts.map

package/dist/commands/project/closeout-check/closeout-invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout-invariant.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/closeout-check/closeout-invariant.ts"],"names":[],"mappings":"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"}

package/dist/commands/project/closeout-check/closeout-invariant.js

@@ -0,0 +1,301 @@
+import YAML, { isMap } from 'yaml';
+/**
+ * The closeout invariant shared by `oat project closeout-check` and
+ * `oat project complete-state` (BL-260806-fail-closed-when-configured).
+ *
+ * A closeout that the implement skill must snapshot (configured
+ * `workflow.postImplementSequence`, autonomous, or lite) cannot reach terminal
+ * completion until its durable `oat_post_implement_sequence` snapshot exists,
+ * every stored step is recorded complete, approval is recorded, and the
+ * snapshot reached `status: complete`. The snapshot schema is the one
+ * `oat-project-implement/references/completion-and-closeout.md` Step 15
+ * persists. Once a snapshot exists it is authoritative: current configuration
+ * is never consulted, so a later config change cannot invalidate a persisted
+ * run.
+ */
+export const SEQUENCE_FIELD = 'oat_post_implement_sequence';
+export const RECOVERY_SKILL = 'oat-project-implement';
+const APPROVAL_WRITES = [
+    'approval: approved',
+    'approval: not_required',
+];
+const PRE_APPROVAL_STEPS = ['summary', 'document', 'pr'];
+const POST_APPROVAL_STEPS = ['summary', 'document', 'pr', 'retro'];
+const SEQUENCE_STATUSES = [
+    'pre_approval',
+    'awaiting_approval',
+    'post_approval',
+    'failed',
+    'complete',
+];
+const APPROVALS = ['pending', 'approved', 'not_required'];
+const SOURCES = ['configured', 'autonomous-default'];
+const APPROVAL_SOURCES = ['user', 'oat-autonomous'];
+export const STEP_SKILLS = {
+    summary: 'oat-project-summary',
+    document: 'oat-project-document',
+    pr: 'oat-project-pr-final',
+    retro: 'oat-project-retro',
+};
+class MalformedSnapshotError extends Error {
+}
+function malformed(detail) {
+    throw new MalformedSnapshotError(detail);
+}
+function readFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) {
+        throw new Error('state.md is missing frontmatter');
+    }
+    const document = YAML.parseDocument(match[1], { uniqueKeys: true });
+    if (document.errors.length > 0) {
+        throw new Error(`state.md frontmatter is malformed (${document.errors[0]?.message ?? 'YAML parse error'})`);
+    }
+    if (!isMap(document.contents)) {
+        throw new Error('state.md frontmatter root is not a YAML map');
+    }
+    const value = document.toJS();
+    return value;
+}
+function readEnum(record, key, allowed, options = {}) {
+    if (!(key in record)) {
+        if (options.optional)
+            return null;
+        malformed(`\`${key}\` is missing`);
+    }
+    const value = record[key];
+    if (value === null && options.nullable)
+        return null;
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        malformed(`\`${key}\` must be one of ${allowed.join(', ')}${options.nullable ? ', or null' : ''}`);
+    }
+    return value;
+}
+function readSteps(record, key, allowed) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        malformed(`\`${key}\` must be an array`);
+    }
+    const steps = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string' || !allowed.includes(entry)) {
+            malformed(`\`${key}\` contains \`${String(entry)}\`; allowed steps are ${allowed.join(', ')}`);
+        }
+        if (steps.includes(entry)) {
+            malformed(`\`${key}\` lists \`${entry}\` more than once`);
+        }
+        steps.push(entry);
+    }
+    return steps;
+}
+/**
+ * Completed steps must be exactly the first N stored steps: the implement
+ * skill dispatches in stored order, so a gap or a foreign step is a
+ * contradiction, not progress.
+ */
+function assertCompletedPrefix(stored, completed, storedKey, completedKey) {
+    for (const step of completed) {
+        if (!stored.includes(step)) {
+            malformed(`\`${completedKey}\` lists \`${step}\`, which \`${storedKey}\` does not`);
+        }
+    }
+    const prefix = stored.slice(0, completed.length);
+    if (!prefix.every((step) => completed.includes(step))) {
+        malformed(`\`${completedKey}\` is not a prefix of the stored \`${storedKey}\` order`);
+    }
+}
+export function parseCloseoutSnapshot(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        malformed('the snapshot must be a map');
+    }
+    const record = value;
+    const status = readEnum(record, 'status', SEQUENCE_STATUSES);
+    // `source` and `approval_source` are additive provenance; an older snapshot
+    // without them stays valid.
+    const source = readEnum(record, 'source', SOURCES, {
+        optional: true,
+        nullable: true,
+    });
+    readEnum(record, 'approval_source', APPROVAL_SOURCES, {
+        optional: true,
+        nullable: true,
+    });
+    if ('final_phase' in record &&
+        record.final_phase !== null &&
+        typeof record.final_phase !== 'string') {
+        malformed('`final_phase` must be a phase ID string');
+    }
+    const preApproval = readSteps(record, 'pre_approval', PRE_APPROVAL_STEPS);
+    const postApproval = readSteps(record, 'post_approval', POST_APPROVAL_STEPS);
+    for (const step of postApproval) {
+        if (preApproval.includes(step)) {
+            malformed(`\`${step}\` appears in both pre_approval and post_approval`);
+        }
+    }
+    const preApprovalCompleted = readSteps(record, 'pre_approval_completed', PRE_APPROVAL_STEPS);
+    const postApprovalCompleted = readSteps(record, 'post_approval_completed', POST_APPROVAL_STEPS);
+    assertCompletedPrefix(preApproval, preApprovalCompleted, 'pre_approval', 'pre_approval_completed');
+    assertCompletedPrefix(postApproval, postApprovalCompleted, 'post_approval', 'post_approval_completed');
+    const approval = readEnum(record, 'approval', APPROVALS);
+    if (postApprovalCompleted.length > 0 && approval === 'pending') {
+        malformed('`post_approval_completed` records work while `approval` is still pending');
+    }
+    const snapshot = {
+        status,
+        source,
+        preApproval,
+        preApprovalCompleted,
+        approval,
+        postApproval,
+        postApprovalCompleted,
+        failure: record.failure ?? null,
+    };
+    if (status === 'complete') {
+        const pending = firstPending(preApproval, preApprovalCompleted) ??
+            firstPending(postApproval, postApprovalCompleted);
+        if (pending || approval === 'pending') {
+            malformed('`status: complete` contradicts pending steps or a pending approval');
+        }
+    }
+    return snapshot;
+}
+function firstPending(stored, completed) {
+    return stored.find((step) => !completed.includes(step));
+}
+function stepOwner(phase, step) {
+    return { kind: 'step', phase, step, skill: STEP_SKILLS[step] };
+}
+function approvalOwner() {
+    return { kind: 'approval', skill: RECOVERY_SKILL, writes: APPROVAL_WRITES };
+}
+function evaluateSnapshot(snapshot, inputs) {
+    const prePending = firstPending(snapshot.preApproval, snapshot.preApprovalCompleted);
+    const postPending = firstPending(snapshot.postApproval, snapshot.postApprovalCompleted);
+    const incomplete = (invariant, detail, nextOwner) => ({
+        status: 'incomplete',
+        invariant,
+        detail,
+        route: RECOVERY_SKILL,
+        nextOwner,
+        inputs,
+    });
+    if (snapshot.status === 'failed') {
+        // Approval-aware order: pending pre-approval work, then the pending
+        // approval boundary, then post-approval work, then status repair. A
+        // post-approval step is never named while approval is pending.
+        const approvalPending = snapshot.approval === 'pending';
+        const owner = prePending
+            ? stepOwner('pre_approval', prePending)
+            : approvalPending
+                ? approvalOwner()
+                : postPending
+                    ? stepOwner('post_approval', postPending)
+                    : { kind: 'sequence-status', skill: RECOVERY_SKILL };
+        const at = owner.kind === 'step'
+            ? ` at \`${owner.step}\``
+            : owner.kind === 'approval'
+                ? ' at the approval boundary'
+                : '';
+        return incomplete('sequence_failed', `the post-implementation sequence recorded a failure${at}`, owner);
+    }
+    if (prePending) {
+        return incomplete('pre_approval_step_pending', `pre-approval step \`${prePending}\` is not recorded complete (stored order: ${snapshot.preApproval.join(', ')})`, stepOwner('pre_approval', prePending));
+    }
+    if (snapshot.approval === 'pending') {
+        return incomplete('approval_pending', 'final approval is not recorded', approvalOwner());
+    }
+    if (postPending) {
+        return incomplete('post_approval_step_pending', `post-approval step \`${postPending}\` is not recorded complete (stored order: ${snapshot.postApproval.join(', ')})`, stepOwner('post_approval', postPending));
+    }
+    if (snapshot.status !== 'complete') {
+        return incomplete('sequence_not_complete', `every step and approval is recorded but the snapshot status is \`${snapshot.status}\`, not \`complete\``, { kind: 'sequence-status', skill: RECOVERY_SKILL });
+    }
+    return { status: 'complete', inputs };
+}
+export async function evaluateCloseout(options) {
+    const frontmatter = readFrontmatter(options.stateContent);
+    const workflowMode = typeof frontmatter.oat_workflow_mode === 'string'
+        ? frontmatter.oat_workflow_mode
+        : 'spec-driven';
+    const autonomousSource = options.autonomousFlag
+        ? 'flag'
+        : options.env.OAT_AUTONOMOUS === '1'
+            ? 'env'
+            : null;
+    const rawSnapshot = frontmatter[SEQUENCE_FIELD];
+    // An explicit null carries no snapshot, exactly like an absent key.
+    const snapshotPresent = SEQUENCE_FIELD in frontmatter && rawSnapshot !== null;
+    const inputs = {
+        workflowMode,
+        lite: workflowMode === 'lite',
+        autonomous: autonomousSource !== null,
+        autonomousSource,
+        configured: null,
+        snapshot: snapshotPresent ? 'present' : 'absent',
+        snapshotSource: null,
+    };
+    if (snapshotPresent) {
+        let snapshot;
+        try {
+            snapshot = parseCloseoutSnapshot(rawSnapshot);
+        }
+        catch (error) {
+            if (!(error instanceof MalformedSnapshotError))
+                throw error;
+            return {
+                status: 'incomplete',
+                invariant: 'snapshot_malformed',
+                detail: `\`${SEQUENCE_FIELD}\` is malformed: ${error.message}`,
+                route: RECOVERY_SKILL,
+                nextOwner: { kind: 'snapshot', skill: RECOVERY_SKILL },
+                inputs,
+            };
+        }
+        inputs.snapshotSource = snapshot.source;
+        return evaluateSnapshot(snapshot, inputs);
+    }
+    let reason = null;
+    if (inputs.lite) {
+        reason = 'lite';
+    }
+    else if (inputs.autonomous) {
+        reason = 'autonomous';
+    }
+    else {
+        inputs.configured = await options.resolveConfigured();
+        if (inputs.configured)
+            reason = 'configured';
+    }
+    if (!reason) {
+        return { status: 'not_required', inputs };
+    }
+    const why = {
+        lite: '`oat_workflow_mode: lite` always snapshots its closeout',
+        autonomous: 'an autonomous closeout (`--autonomous` or `OAT_AUTONOMOUS=1`) always snapshots its closeout',
+        configured: 'the effective `workflow.postImplementSequence` is configured',
+    }[reason];
+    return {
+        status: 'incomplete',
+        invariant: 'snapshot_missing',
+        detail: `\`${SEQUENCE_FIELD}\` is absent, but ${why}`,
+        route: RECOVERY_SKILL,
+        nextOwner: { kind: 'snapshot', skill: RECOVERY_SKILL },
+        inputs,
+    };
+}
+/**
+ * The one refusal message both commands print, so a skill or operator sees the
+ * same invariant and recovery route from either.
+ */
+export function formatCloseoutRefusal(projectPath, result) {
+    const owner = result.nextOwner;
+    const next = owner.kind === 'step'
+        ? ` Next stored step: \`${owner.step}\` (${owner.skill}).`
+        : owner.kind === 'approval'
+            ? ' Next: record the final approval decision: `approval: approved` after final HiLL sign-off, or `approval: not_required` when no final checkpoint exists.'
+            : '';
+    return [
+        `Closeout invariant not satisfied for ${projectPath} (${result.invariant}): ${result.detail}.${next}`,
+        `Resume with ${RECOVERY_SKILL}; it persists the ${SEQUENCE_FIELD} snapshot (completion-and-closeout.md Step 15) and completes every stored step before completion.`,
+    ].join(' ');
+}