opensquid 0.5.395

package/dist/runtime/capability_gate.js

@@ -0,0 +1,295 @@
+/**
+ * Capability gate (AUTO.3) — POSIX-style declared-capability check.
+ * Spec: `docs/tasks/automation.md` AUTO.3.
+ *
+ * Precedence: builtin-deny → pack-deny → pack-allow → prompt → deny+audit.
+ * Engine-vocabulary: gate speaks in `(pack, capability, target)` only.
+ *
+ * Risk postures (locked at AUTO.3):
+ *   - Shell metacharacters (`; && || $() backticks | > >> <(`) blanket-
+ *     reject unless the exact raw command is in the allowlist; SEC.4 ships
+ *     full `shell-quote` argv parser.
+ *   - HTTP allowlist match is on `new URL(target).hostname` (never glob on
+ *     raw URL — foot-gun: `api.github.com.attacker.com`).
+ *   - Parse failures + prompt-throw + audit-throw all DENY (constraint C10).
+ *
+ * Audit: every verdict flows through `auditLog`. CLI.5 lands the libsql
+ * `audit_log` table; AUTO.3 ships the interface (no-op default).
+ */
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { minimatch } from 'minimatch';
+import { BUILTIN_BINARY_DENY, BUILTIN_CHANNEL_DENY, BUILTIN_PATH_DENY, BUILTIN_SHELL_DENY, BUILTIN_SUBAGENT_DENY, SHELL_METACHARACTERS, trustBuiltinDeny, } from './builtin_denylist.js';
+function noopAudit() {
+    /* default audit sink (named to satisfy eslint no-empty-function) */
+}
+function safeParseUrl(target) {
+    try {
+        return new URL(target);
+    }
+    catch {
+        return null;
+    }
+}
+// Hostname allowlist: exact OR `*.<suffix>` subdomain. The foot-gun
+// `api.github.com.attacker.com` is rejected (its hostname is .attacker.com).
+function matchHostname(hostname, pattern) {
+    if (pattern === hostname)
+        return true;
+    if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(2);
+        return hostname.endsWith(`.${suffix}`);
+    }
+    return false;
+}
+function expandHome(path, home) {
+    if (path === '~')
+        return home;
+    if (path.startsWith('~/'))
+        return resolve(home, path.slice(2));
+    return path;
+}
+// Matchers are pure; `check()` is async only for the prompt callback.
+export class CapabilityGate {
+    packs;
+    prompt;
+    auditLogFn;
+    trustBuiltinDeny;
+    homeDir;
+    overrides;
+    constructor(opts) {
+        this.packs = opts.packs;
+        this.prompt = opts.prompt;
+        this.auditLogFn = opts.auditLog ?? noopAudit;
+        this.trustBuiltinDeny = opts.trustBuiltinDeny ?? trustBuiltinDeny();
+        this.homeDir = opts.homeDir ?? homedir();
+        this.overrides = opts.overrides ?? [];
+    }
+    async check(req) {
+        const block = this.packs.get(req.pack)?.permissions?.[req.capability];
+        if (this.trustBuiltinDeny) {
+            const builtinDeny = this.matchBuiltinDeny(req);
+            if (builtinDeny) {
+                return this.audit({ allowed: false, source: 'denylist', message: builtinDeny }, req);
+            }
+        }
+        // Pack-local deny wins over user overrides (a pack author explicitly
+        // forbidding a pattern shouldn't be silently undermined by an old
+        // override file). User override wins over pack allowlist gaps.
+        if (block) {
+            const packDeny = this.matchPackDeny(req, block);
+            if (packDeny) {
+                return this.audit({ allowed: false, source: 'denylist', message: packDeny }, req);
+            }
+        }
+        const override = this.matchOverride(req);
+        if (override) {
+            return this.audit({ allowed: true, source: 'user_override', message: override }, req);
+        }
+        if (!block)
+            return this.handleUndeclared(req);
+        const declared = this.matchAllowlist(req, block);
+        if (declared)
+            return this.audit({ allowed: true, source: 'declared', message: declared }, req);
+        return this.handleUndeclared(req);
+    }
+    matchOverride(req) {
+        for (const o of this.overrides) {
+            if (o.pack !== req.pack)
+                continue;
+            if (o.capability !== req.capability)
+                continue;
+            // http_request override: hostname-exact OR `*.<suffix>` (parity with
+            // pack allowlist; never raw-URL glob — foot-gun guard).
+            if (req.capability === 'http_request') {
+                const url = safeParseUrl(req.target);
+                if (url === null)
+                    continue;
+                if (matchHostname(url.hostname, o.target)) {
+                    return `user override: ${url.hostname} matches "${o.target}"`;
+                }
+                continue;
+            }
+            // file_write override: ~-expand + minimatch with dot:true (parity
+            // with declared allowlist + pack-local deny matchPathList).
+            if (req.capability === 'file_write') {
+                const expanded = resolve(expandHome(req.target, this.homeDir));
+                const expandedPattern = resolve(expandHome(o.target, this.homeDir));
+                if (minimatch(expanded, expandedPattern, { dot: true })) {
+                    return `user override: matches "${o.target}"`;
+                }
+                continue;
+            }
+            // shell_exec override: exact OR glob, but the SHELL_METACHARACTERS
+            // gate still applies (an override cannot un-block metachars unless
+            // it's an exact-match like the declared allowlist semantic).
+            if (req.capability === 'shell_exec') {
+                if (o.target === req.target)
+                    return `user override exact: "${o.target}"`;
+                let hasMeta = false;
+                for (const meta of SHELL_METACHARACTERS) {
+                    if (req.target.includes(meta)) {
+                        hasMeta = true;
+                        break;
+                    }
+                }
+                if (hasMeta)
+                    continue;
+                if (minimatch(req.target, o.target))
+                    return `user override glob: "${o.target}"`;
+                continue;
+            }
+            // send_message / subprocess_call / subagent_call → minimatch glob
+            // on the raw target (parity with `matchGlobList`).
+            if (minimatch(req.target, o.target))
+                return `user override: matches "${o.target}"`;
+        }
+        return null;
+    }
+    matchBuiltinDeny(req) {
+        switch (req.capability) {
+            case 'shell_exec':
+                for (const re of BUILTIN_SHELL_DENY) {
+                    if (re.test(req.target))
+                        return `built-in shell deny: matches ${re.source}`;
+                }
+                return null;
+            case 'file_write':
+                return this.matchPathList(req.target, BUILTIN_PATH_DENY, 'built-in path deny');
+            case 'send_message':
+                return matchGlobList(req.target, BUILTIN_CHANNEL_DENY, 'built-in channel deny');
+            case 'subprocess_call':
+                return matchGlobList(req.target, BUILTIN_BINARY_DENY, 'built-in binary deny');
+            case 'subagent_call':
+                return matchGlobList(req.target, BUILTIN_SUBAGENT_DENY, 'built-in subagent deny');
+            case 'http_request':
+                // Parse-failure → deny (C10: no silent fail-open).
+                if (safeParseUrl(req.target) === null)
+                    return `invalid URL "${req.target}"`;
+                return null;
+            default: {
+                const _exhaustive = req.capability;
+                return `unknown capability ${String(_exhaustive)}`;
+            }
+        }
+    }
+    matchPackDeny(req, block) {
+        const denies = block.deny ?? [];
+        if (denies.length === 0)
+            return null;
+        if (req.capability === 'shell_exec') {
+            for (const pattern of denies) {
+                if (minimatch(req.target, pattern))
+                    return `pack-local shell deny: matches "${pattern}"`;
+            }
+            return null;
+        }
+        if (req.capability === 'file_write') {
+            return this.matchPathList(req.target, denies, 'pack-local path deny');
+        }
+        return matchGlobList(req.target, denies, 'pack-local deny');
+    }
+    // Shared file-path matcher: expand `~`, resolve, minimatch both sides.
+    matchPathList(target, patterns, label) {
+        const expanded = resolve(expandHome(target, this.homeDir));
+        for (const pattern of patterns) {
+            const expandedPattern = resolve(expandHome(pattern, this.homeDir));
+            if (minimatch(expanded, expandedPattern, { dot: true })) {
+                return `${label}: matches "${pattern}"`;
+            }
+        }
+        return null;
+    }
+    matchAllowlist(req, block) {
+        if (req.capability === 'shell_exec') {
+            const cmds = block.commands ?? [];
+            const exact = cmds.find((c) => c === req.target);
+            if (exact !== undefined)
+                return `shell allowlist exact: "${exact}"`;
+            // Metachar gate (replaced by shell-quote argv parser in SEC.4).
+            for (const meta of SHELL_METACHARACTERS) {
+                if (req.target.includes(meta))
+                    return null;
+            }
+            for (const pattern of cmds) {
+                if (minimatch(req.target, pattern))
+                    return `shell allowlist glob: "${pattern}"`;
+            }
+            return null;
+        }
+        if (req.capability === 'http_request') {
+            const perm = block;
+            const url = safeParseUrl(req.target);
+            if (url === null)
+                return null;
+            const method = (req.method ?? 'GET').toUpperCase();
+            const methods = perm.methods ?? ['GET'];
+            if (!methods.includes(method))
+                return null;
+            for (const pattern of perm.domains ?? []) {
+                if (matchHostname(url.hostname, pattern)) {
+                    return `http allowlist: ${url.hostname} matches "${pattern}" (${method})`;
+                }
+            }
+            return null;
+        }
+        if (req.capability === 'file_write') {
+            const paths = block.paths ?? [];
+            return this.matchPathList(req.target, paths, 'file allowlist');
+        }
+        if (req.capability === 'send_message') {
+            const channels = block.channels ?? [];
+            return matchGlobList(req.target, channels, 'channel allowlist');
+        }
+        if (req.capability === 'subprocess_call') {
+            const bins = block.binaries ?? [];
+            return matchGlobList(req.target, bins, 'binary allowlist');
+        }
+        if (req.capability === 'subagent_call') {
+            const targets = block.targets ?? [];
+            return matchGlobList(req.target, targets, 'subagent allowlist');
+        }
+        const _exhaustive = req.capability;
+        return `unknown capability ${String(_exhaustive)}`;
+    }
+    // Undeclared: prompt callback OR deny+audit. C10: prompt-throw +
+    // audit-throw both DENY (never fail-open).
+    async handleUndeclared(req) {
+        if (!this.prompt) {
+            return this.audit(denied(`undeclared "${req.capability}" for pack "${req.pack}" (non-interactive)`), req);
+        }
+        try {
+            const approved = await this.prompt(req);
+            return this.audit(approved
+                ? {
+                    allowed: true,
+                    source: 'user_approved',
+                    message: `user approved "${req.capability}" → "${req.target}"`,
+                }
+                : denied(`user denied "${req.capability}" → "${req.target}"`), req);
+        }
+        catch (e) {
+            return this.audit(denied(`prompt threw — deny (C10): ${String(e)}`), req);
+        }
+    }
+    audit(verdict, req) {
+        try {
+            this.auditLogFn(verdict, req);
+        }
+        catch {
+            // Audit-sink errors NEVER influence the verdict (constraint C10).
+        }
+        return verdict;
+    }
+}
+function matchGlobList(target, patterns, label) {
+    for (const pattern of patterns) {
+        if (minimatch(target, pattern))
+            return `${label}: matches "${pattern}"`;
+    }
+    return null;
+}
+function denied(message) {
+    return { allowed: false, source: 'denied', message };
+}
+//# sourceMappingURL=capability_gate.js.map

package/dist/runtime/capability_gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability_gate.js","sourceRoot":"","sources":["../../src/runtime/capability_gate.ts"],"names":[],"mappings":"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"}

package/dist/runtime/chain_state.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Per-session auto-start chain state machine (T-ASC, ASC.1).
+ *
+ * Tracks the user-locked pipeline scope-decomposer → task-spec-author →
+ * workflow / 7-layer across a single Claude Code session. The state is the
+ * substrate ASC.2's `Skill.requires: chain_stage` precondition reads, and the
+ * data source ASC.5's reframed scope-decomposer handoff rules consume to
+ * shape their structured `directive` verdicts (ASC.3).
+ *
+ * 7 stages (declaration order = pipeline order):
+ *   idle              — no scope work in flight (initial)
+ *   scoping           — scope-authoring intent detected on the most recent
+ *                       prompt (the SCOPE_INTENT_REGEX matched while idle)
+ *   researched        — a pre-research artifact landed on disk
+ *                       (docs/research/*-pre-research-*.md)
+ *   spec_authored     — a track spec landed on disk
+ *                       (docs/tasks/T-*.md)
+ *   tasks_loaded      — harness TaskCreate fired with metadata.taskId
+ *                       provenance (the spec became loaded tasks)
+ *   phases_in_flight  — at least one phase logged for the active task
+ *   phases_complete   — all 7 REQUIRED phases logged for the active task
+ *
+ * Writers (5 distributed transition points across the runtime):
+ *   UserPromptSubmit  → 'scoping'         (prompt matches SCOPE_INTENT_REGEX
+ *                                          AND current stage is 'idle')
+ *   PreToolUse        → 'researched'      (Write to docs/research/*-pre-research-*.md)
+ *   PreToolUse        → 'spec_authored'   (Write to docs/tasks/T-*.md)
+ *   PreToolUse        → 'tasks_loaded'    (TaskCreate/TaskUpdate with metadata.taskId)
+ *   log_phase MCP     → 'phases_in_flight' / 'phases_complete'
+ *
+ * Lifecycle: session-scoped per T-ASC L3. SessionEnd hook calls
+ * `clearChainState`. Cross-session resume is OUT OF SCOPE for this track
+ * (separate product question).
+ *
+ * Invariants:
+ *   - Same-stage write is idempotent (no double-history-entry, no file rewrite).
+ *     The `history` is append-only and entries are NEVER removed mid-session
+ *     (per L4); history captures stage ENTRIES, not write attempts.
+ *   - No-throw read posture: absent / malformed → null; the caller defaults
+ *     to 'idle' via `readChainStage`'s nullish coalesce. Same eventual-
+ *     consistency model as session_state.ts:108-135 (recordSessionCwd).
+ *   - Enrichment fields (pre_research_path, spec_path, task_ids) ACCUMULATE
+ *     across transitions: a transition without enrich preserves prior values.
+ *     A same-stage idempotent call does NOT update enrichment (L4 contract —
+ *     same stage = no write at all). If a future need surfaces ("update
+ *     enrichment on current stage"), add a sibling enrichChainState helper;
+ *     do NOT loosen transitionChainStage's idempotency.
+ *   - Write failures throw (caller-owned recovery). Call sites in hooks /
+ *     log_phase wrap in try/catch with stderr-warn or silent (their existing
+ *     best-effort discipline).
+ *
+ * Imports from: node:fs/promises, node:path, ./paths.js.
+ * Imported by:
+ *   - src/runtime/hooks/{pre-tool-use,user-prompt-submit,session-end}.ts (writers)
+ *   - src/mcp/tools/log_phase.ts (writer)
+ *   - src/runtime/skill_requires.ts (ASC.2 — `chain_stage` precondition reader)
+ *   - src/functions/chain_state.ts (ASC.5 — `read_chain_state` primitive)
+ */
+/** The 7 stages, in pipeline order. `as const` so ChainStage narrows to the literal union. */
+export declare const CHAIN_STAGES: readonly ["idle", "scoping", "researched", "spec_authored", "tasks_loaded", "phases_in_flight", "phases_complete"];
+export type ChainStage = (typeof CHAIN_STAGES)[number];
+export interface ChainHistoryEntry {
+    stage: ChainStage;
+    /** ISO-8601 timestamp the chain ENTERED this stage. */
+    at: string;
+}
+export interface ChainState {
+    stage: ChainStage;
+    /** ISO timestamp the chain entered the CURRENT stage. */
+    started_at: string;
+    /** ISO timestamp of the most-recent transition write (same as started_at after a fresh transition). */
+    last_transition_at: string;
+    /** Absolute path to the pre-research artifact; set when transitioning to 'researched'. */
+    pre_research_path?: string;
+    /** Absolute path to the track spec; set when transitioning to 'spec_authored'. */
+    spec_path?: string;
+    /** Harness task ids that loaded from the spec; set when transitioning to 'tasks_loaded'. */
+    task_ids?: string[];
+    /** Append-only audit trail of every stage entered. */
+    history: ChainHistoryEntry[];
+}
+/** Optional enrichment supplied on transition; merges into ChainState (only when the stage actually transitions). */
+export interface ChainEnrich {
+    pre_research_path?: string;
+    spec_path?: string;
+    task_ids?: string[];
+}
+/**
+ * Write a stage transition. Idempotent on same-stage re-write: when the
+ * persisted stage already equals `next`, this is a no-op (history unchanged,
+ * enrichment NOT applied — L4 contract: same stage = no write).
+ *
+ * Enrichment fields ACCUMULATE on actual transitions: a transition without
+ * an explicit enrich value preserves whatever was in the prior state for that
+ * field. Supplying enrich for a stage we're already in is silently dropped
+ * (the function returns early). If a caller needs to update enrichment on
+ * the current stage, that's a separate concern (out of scope for ASC.1).
+ *
+ * Fail-open is caller-side: write failures throw, hook bins wrap with
+ * try/catch + stderr-warn, the log_phase MCP tool wraps silently (the tool's
+ * return shape is the gate's contract and a chain-state-write failure must
+ * NOT propagate into the tool response).
+ */
+export declare function transitionChainStage(sessionId: string, next: ChainStage, enrich?: ChainEnrich): Promise<void>;
+/**
+ * Read the persisted ChainState, or `null` if absent/unreadable/malformed.
+ * Same no-throw posture as readSessionCwd / readActiveTask: a missing or
+ * shape-invalid file reads as null inside a hook bin, never an exception.
+ */
+export declare function readChainState(sessionId: string): Promise<ChainState | null>;
+/**
+ * Read just the current stage; defaults to 'idle' when the chain has not yet
+ * been initialized (absent file) or when the persisted state is malformed.
+ * The convenience reader for callers that only care about the stage gate
+ * (ASC.2's `Skill.requires: chain_stage` precondition, ASC.5's rule guards).
+ */
+export declare function readChainStage(sessionId: string): Promise<ChainStage>;
+/**
+ * Remove the chain-state file (SessionEnd cleanup). ENOENT is swallowed —
+ * a session that never advanced past 'idle' has no file to clear. Any other
+ * error throws (caller wraps with best-effort discipline).
+ */
+export declare function clearChainState(sessionId: string): Promise<void>;
+//# sourceMappingURL=chain_state.d.ts.map

package/dist/runtime/chain_state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain_state.d.ts","sourceRoot":"","sources":["../../src/runtime/chain_state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAMH,8FAA8F;AAC9F,eAAO,MAAM,YAAY,oHAQf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAKvD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,uGAAuG;IACvG,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,qHAAqH;AACrH,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAQlF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAE3E;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtE"}

package/dist/runtime/chain_state.js

@@ -0,0 +1,189 @@
+/**
+ * Per-session auto-start chain state machine (T-ASC, ASC.1).
+ *
+ * Tracks the user-locked pipeline scope-decomposer → task-spec-author →
+ * workflow / 7-layer across a single Claude Code session. The state is the
+ * substrate ASC.2's `Skill.requires: chain_stage` precondition reads, and the
+ * data source ASC.5's reframed scope-decomposer handoff rules consume to
+ * shape their structured `directive` verdicts (ASC.3).
+ *
+ * 7 stages (declaration order = pipeline order):
+ *   idle              — no scope work in flight (initial)
+ *   scoping           — scope-authoring intent detected on the most recent
+ *                       prompt (the SCOPE_INTENT_REGEX matched while idle)
+ *   researched        — a pre-research artifact landed on disk
+ *                       (docs/research/*-pre-research-*.md)
+ *   spec_authored     — a track spec landed on disk
+ *                       (docs/tasks/T-*.md)
+ *   tasks_loaded      — harness TaskCreate fired with metadata.taskId
+ *                       provenance (the spec became loaded tasks)
+ *   phases_in_flight  — at least one phase logged for the active task
+ *   phases_complete   — all 7 REQUIRED phases logged for the active task
+ *
+ * Writers (5 distributed transition points across the runtime):
+ *   UserPromptSubmit  → 'scoping'         (prompt matches SCOPE_INTENT_REGEX
+ *                                          AND current stage is 'idle')
+ *   PreToolUse        → 'researched'      (Write to docs/research/*-pre-research-*.md)
+ *   PreToolUse        → 'spec_authored'   (Write to docs/tasks/T-*.md)
+ *   PreToolUse        → 'tasks_loaded'    (TaskCreate/TaskUpdate with metadata.taskId)
+ *   log_phase MCP     → 'phases_in_flight' / 'phases_complete'
+ *
+ * Lifecycle: session-scoped per T-ASC L3. SessionEnd hook calls
+ * `clearChainState`. Cross-session resume is OUT OF SCOPE for this track
+ * (separate product question).
+ *
+ * Invariants:
+ *   - Same-stage write is idempotent (no double-history-entry, no file rewrite).
+ *     The `history` is append-only and entries are NEVER removed mid-session
+ *     (per L4); history captures stage ENTRIES, not write attempts.
+ *   - No-throw read posture: absent / malformed → null; the caller defaults
+ *     to 'idle' via `readChainStage`'s nullish coalesce. Same eventual-
+ *     consistency model as session_state.ts:108-135 (recordSessionCwd).
+ *   - Enrichment fields (pre_research_path, spec_path, task_ids) ACCUMULATE
+ *     across transitions: a transition without enrich preserves prior values.
+ *     A same-stage idempotent call does NOT update enrichment (L4 contract —
+ *     same stage = no write at all). If a future need surfaces ("update
+ *     enrichment on current stage"), add a sibling enrichChainState helper;
+ *     do NOT loosen transitionChainStage's idempotency.
+ *   - Write failures throw (caller-owned recovery). Call sites in hooks /
+ *     log_phase wrap in try/catch with stderr-warn or silent (their existing
+ *     best-effort discipline).
+ *
+ * Imports from: node:fs/promises, node:path, ./paths.js.
+ * Imported by:
+ *   - src/runtime/hooks/{pre-tool-use,user-prompt-submit,session-end}.ts (writers)
+ *   - src/mcp/tools/log_phase.ts (writer)
+ *   - src/runtime/skill_requires.ts (ASC.2 — `chain_stage` precondition reader)
+ *   - src/functions/chain_state.ts (ASC.5 — `read_chain_state` primitive)
+ */
+import { readFile, unlink } from 'node:fs/promises';
+import { atomicWriteFile } from './atomic_write.js';
+import { sessionStateFile } from './paths.js';
+/** The 7 stages, in pipeline order. `as const` so ChainStage narrows to the literal union. */
+export const CHAIN_STAGES = [
+    'idle',
+    'scoping',
+    'researched',
+    'spec_authored',
+    'tasks_loaded',
+    'phases_in_flight',
+    'phases_complete',
+];
+/** Well-known session-state key for the chain-state file. */
+const CHAIN_STATE_KEY = 'chain-state';
+/**
+ * Runtime type guard for the persisted shape. Validates every required field
+ * + stage-membership; the unknown-shape branches return false so the read
+ * helpers default to null (no-throw posture).
+ */
+function isChainState(o) {
+    if (o === null || typeof o !== 'object')
+        return false;
+    const obj = o;
+    if (typeof obj.stage !== 'string')
+        return false;
+    if (!CHAIN_STAGES.includes(obj.stage))
+        return false;
+    if (typeof obj.started_at !== 'string')
+        return false;
+    if (typeof obj.last_transition_at !== 'string')
+        return false;
+    if (!Array.isArray(obj.history))
+        return false;
+    return true;
+}
+/**
+ * Write a stage transition. Idempotent on same-stage re-write: when the
+ * persisted stage already equals `next`, this is a no-op (history unchanged,
+ * enrichment NOT applied — L4 contract: same stage = no write).
+ *
+ * Enrichment fields ACCUMULATE on actual transitions: a transition without
+ * an explicit enrich value preserves whatever was in the prior state for that
+ * field. Supplying enrich for a stage we're already in is silently dropped
+ * (the function returns early). If a caller needs to update enrichment on
+ * the current stage, that's a separate concern (out of scope for ASC.1).
+ *
+ * Fail-open is caller-side: write failures throw, hook bins wrap with
+ * try/catch + stderr-warn, the log_phase MCP tool wraps silently (the tool's
+ * return shape is the gate's contract and a chain-state-write failure must
+ * NOT propagate into the tool response).
+ */
+export async function transitionChainStage(sessionId, next, enrich) {
+    const path = sessionStateFile(sessionId, CHAIN_STATE_KEY);
+    const now = new Date().toISOString();
+    const current = await readChainState(sessionId);
+    if (current?.stage === next)
+        return; // L4 idempotency: same stage = no-op
+    // T-PACK-FSM-STANDARDIZATION slice A4 — legality. The workflow pipeline is
+    // FORWARD-ONLY (CHAIN_STAGES order); forward JUMPS are allowed by design
+    // (e.g. a spec write lands `spec_authored` without an intervening prompt),
+    // but a BACKWARD transition was silently accepted before — the exact "accepts
+    // any target, no legality matrix" gap the generic FSM engine closes. Reject
+    // it: no-op + warn, so an illegal regress can't quietly rewind a gate. (The
+    // legitimate research loop-back lives in the `scope-fsm` pack's FSM, not this
+    // global one-shot chain.)
+    const curIdx = current ? CHAIN_STAGES.indexOf(current.stage) : -1;
+    const nextIdx = CHAIN_STAGES.indexOf(next);
+    if (nextIdx < curIdx) {
+        process.stderr.write(`opensquid: illegal backward chain transition ${current?.stage ?? 'idle'} -> ${next} ignored (forward-only)\n`);
+        return;
+    }
+    const merged = {
+        stage: next,
+        started_at: now,
+        last_transition_at: now,
+        ...(current?.pre_research_path !== undefined
+            ? { pre_research_path: current.pre_research_path }
+            : {}),
+        ...(current?.spec_path !== undefined ? { spec_path: current.spec_path } : {}),
+        ...(current?.task_ids !== undefined ? { task_ids: current.task_ids } : {}),
+        ...(enrich?.pre_research_path !== undefined
+            ? { pre_research_path: enrich.pre_research_path }
+            : {}),
+        ...(enrich?.spec_path !== undefined ? { spec_path: enrich.spec_path } : {}),
+        ...(enrich?.task_ids !== undefined ? { task_ids: enrich.task_ids } : {}),
+        history: [...(current?.history ?? []), { stage: next, at: now }],
+    };
+    // FC.1: atomic publish so concurrent transitions can't tear/lose the stage —
+    // the stage the gates read is always the last fully-committed one.
+    await atomicWriteFile(path, JSON.stringify(merged, null, 2));
+}
+/**
+ * Read the persisted ChainState, or `null` if absent/unreadable/malformed.
+ * Same no-throw posture as readSessionCwd / readActiveTask: a missing or
+ * shape-invalid file reads as null inside a hook bin, never an exception.
+ */
+export async function readChainState(sessionId) {
+    try {
+        const raw = await readFile(sessionStateFile(sessionId, CHAIN_STATE_KEY), 'utf8');
+        const parsed = JSON.parse(raw);
+        return isChainState(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read just the current stage; defaults to 'idle' when the chain has not yet
+ * been initialized (absent file) or when the persisted state is malformed.
+ * The convenience reader for callers that only care about the stage gate
+ * (ASC.2's `Skill.requires: chain_stage` precondition, ASC.5's rule guards).
+ */
+export async function readChainStage(sessionId) {
+    return (await readChainState(sessionId))?.stage ?? 'idle';
+}
+/**
+ * Remove the chain-state file (SessionEnd cleanup). ENOENT is swallowed —
+ * a session that never advanced past 'idle' has no file to clear. Any other
+ * error throws (caller wraps with best-effort discipline).
+ */
+export async function clearChainState(sessionId) {
+    try {
+        await unlink(sessionStateFile(sessionId, CHAIN_STATE_KEY));
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+}
+//# sourceMappingURL=chain_state.js.map

package/dist/runtime/chain_state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain_state.js","sourceRoot":"","sources":["../../src/runtime/chain_state.ts"],"names":[],"mappings":"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"}