@event4u/agent-config 16.4.0 → 17.0.0

package/src/agent-src/templates/scripts/work_engine/procedure/run.ts

@@ -0,0 +1,432 @@
+/**
+ * The procedure cursor: `agent-config work --procedure <skill>`
+ * (road-to-steps-the-skill-cannot-skip Phase 5, default-off).
+ *
+ * One call loads the skill's sidecar, revalidates every step already recorded
+ * as done, and runs the `/work` dispatcher once over the sidecar's own step
+ * order (`dispatch(..., order)`, 5.1). A step's handler hands the step out the
+ * first time it is reached and checks its exit on every later call, so step
+ * n+1 is never handed out before step n's exit is met, recorded as a confirmed
+ * judgement, or recorded as `skipped: <reason>`.
+ *
+ * Bounds (5.6): linear and finite — one dispatch per call, no repeat mode, no
+ * background work, no subagent, no process, no hook. Nothing read from a
+ * sidecar or a state file is executed.
+ *
+ * Judgement steps (5.7): a `judgement` exit cannot be verified by code, so the
+ * step is sequenced, not verified. The operator who runs the cursor answers it
+ * with `--procedure-confirm <step-id>`; that explicit confirmation of the
+ * current step is the only answer that clears it, and it is recorded with the
+ * step file's hash and a timestamp. When nobody answers, the step stays the
+ * current step on every call — it never times out and never advances itself.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { Outcome, StepResult } from '../delivery_state.js';
+import type { Step } from '../delivery_state.js';
+import { dispatch } from '../dispatcher.js';
+import { Input, WorkState, from_dict, to_dict } from '../state.js';
+import { _sync_back, _to_delivery } from '../state_io.js';
+import { PROCEDURE_CHECKS, PROCEDURE_CHECK_INPUTS } from './checks.js';
+import { SidecarError, containedPath, loadSidecar, sha256, type Sidecar, type SidecarStep } from './sidecar.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** Set to `1` to refuse every procedure activation, whatever the flags say (5.8). */
+export const PROCEDURE_KILL_SWITCH = 'AGENT_CONFIG_PROCEDURE_OFF';
+export const PROCEDURE_ENGINE_VERSION = 1;
+export const PROCEDURE_DATA_SCHEMA = 'procedure/v1';
+const DEFAULT_STATE_FILE = '.work-state.json';
+const MAX_STATE_BYTES = 1024 * 1024;
+const MAX_FAILED = 10;
+
+export type StepStatus = 'emitted' | 'partial' | 'ok' | 'skipped' | 'stale';
+const STATUSES: ReadonlySet<string> = new Set(['emitted', 'partial', 'ok', 'skipped', 'stale']);
+
+export interface Adjudication {
+    answer: 'confirmed';
+    by: 'operator';
+    at: string;
+    step_sha: string;
+}
+
+export interface StepRecord {
+    status: StepStatus;
+    failed_approaches: string[];
+    reason?: string;
+    head?: string;
+    step_sha?: string;
+    inputs_sha?: string;
+    adjudication?: Adjudication;
+}
+
+export interface ProcedureData {
+    schema: string;
+    skill: string;
+    sidecar_sha: string;
+    engine_version: number;
+    started_head: string;
+    current: string | null;
+    /** The sidecar's step ids in order, so a reader of the state file can say "step k of n". */
+    order: string[];
+    steps: Record<string, StepRecord>;
+}
+
+export interface ProcedureRunOptions {
+    skill: string;
+    projectRoot: string;
+    skillsRoot?: string;
+    stateFile?: string;
+    confirm?: string | null;
+    restart?: boolean;
+    env?: Record<string, string | undefined>;
+}
+
+export interface ProcedureRunResult {
+    code: 0 | 1 | 2;
+    output: string;
+}
+
+class Refusal extends Error {}
+
+const RECORD_KEYS = new Set(['status', 'failed_approaches', 'reason', 'head', 'step_sha', 'inputs_sha', 'adjudication']);
+const DATA_KEYS = new Set(['schema', 'skill', 'sidecar_sha', 'engine_version', 'started_head', 'current', 'order', 'steps']);
+
+function isDict(v: unknown): v is Record<string, unknown> {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** The persisted procedure record is untrusted: a closed, versioned shape or a refusal. */
+function validateData(raw: unknown, sidecar: Sidecar): ProcedureData {
+    if (!isDict(raw)) throw new Refusal('the procedure record in the state file is not an object');
+    for (const k of Object.keys(raw)) if (!DATA_KEYS.has(k)) throw new Refusal(`unknown key '${k}' in the procedure record`);
+    if (raw['schema'] !== PROCEDURE_DATA_SCHEMA) throw new Refusal(`the procedure record is not ${PROCEDURE_DATA_SCHEMA}`);
+    const steps = raw['steps'];
+    if (!isDict(steps)) throw new Refusal('the procedure record carries no step map');
+    const ids = new Set(sidecar.steps.map((s) => s.id));
+    for (const [id, rec] of Object.entries(steps)) {
+        if (!ids.has(id)) throw new Refusal(`the procedure record names step '${id}', which the sidecar does not`);
+        if (!isDict(rec) || !STATUSES.has(String(rec['status'])) || !Array.isArray(rec['failed_approaches'])) {
+            throw new Refusal(`the record of step '${id}' is malformed`);
+        }
+        for (const k of Object.keys(rec)) if (!RECORD_KEYS.has(k)) throw new Refusal(`unknown key '${k}' in step '${id}'`);
+    }
+    const order = raw['order'];
+    if (!Array.isArray(order) || order.join('\n') !== sidecar.steps.map((s) => s.id).join('\n')) {
+        throw new Refusal('the step order in the state file is not the sidecar\'s');
+    }
+    const current = raw['current'];
+    if (current !== null && (typeof current !== 'string' || !ids.has(current))) throw new Refusal('the current step is unknown');
+    return raw as unknown as ProcedureData;
+}
+
+function freshData(sidecar: Sidecar, head: string): ProcedureData {
+    return {
+        schema: PROCEDURE_DATA_SCHEMA,
+        skill: sidecar.skill,
+        sidecar_sha: sidecar.sha,
+        engine_version: PROCEDURE_ENGINE_VERSION,
+        started_head: head,
+        current: null,
+        order: sidecar.steps.map((s) => s.id),
+        steps: {},
+    };
+}
+
+/** HEAD read from the repository files, so no process is started for it. */
+export function readHead(projectRoot: string): string {
+    let dir = path.resolve(projectRoot);
+    for (;;) {
+        const dotGit = path.join(dir, '.git');
+        if (fs.existsSync(dotGit)) {
+            let gitDir = dotGit;
+            if (fs.statSync(dotGit).isFile()) {
+                const m = /^gitdir: (.+)$/m.exec(fs.readFileSync(dotGit, 'utf-8'));
+                if (m === null) return 'none';
+                gitDir = path.resolve(dir, (m[1] as string).trim());
+            }
+            const head = readOr(path.join(gitDir, 'HEAD')).trim();
+            const ref = /^ref: (.+)$/.exec(head);
+            if (ref === null) return head === '' ? 'none' : head;
+            const common = readOr(path.join(gitDir, 'commondir')).trim();
+            const roots = [gitDir, ...(common === '' ? [] : [path.resolve(gitDir, common)])];
+            for (const r of roots) {
+                const loose = readOr(path.join(r, ref[1] as string)).trim();
+                if (loose !== '') return loose;
+                const packed = readOr(path.join(r, 'packed-refs'))
+                    .split('\n')
+                    .find((l) => l.endsWith(` ${ref[1] as string}`));
+                if (packed !== undefined) return packed.split(' ')[0] as string;
+            }
+            return 'none';
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) return 'none';
+        dir = parent;
+    }
+}
+
+function readOr(file: string): string {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    } catch {
+        return '';
+    }
+}
+
+function inTree(projectRoot: string, rel: string): boolean {
+    if (!containedPath(rel)) return false;
+    return fs.existsSync(path.join(projectRoot, rel));
+}
+
+function existsFingerprint(projectRoot: string, rel: string): string {
+    const abs = path.join(projectRoot, rel);
+    try {
+        const st = fs.statSync(abs);
+        return st.isDirectory() ? fs.readdirSync(abs).sort().join('\n') : sha256(fs.readFileSync(abs));
+    } catch {
+        return 'absent';
+    }
+}
+
+function stepSha(sidecar: Sidecar, step: SidecarStep): string {
+    return sha256(fs.readFileSync(path.join(sidecar.skillDir, step.file)));
+}
+
+function inputsSha(sidecar: Sidecar, step: SidecarStep, projectRoot: string): string {
+    const exit = step.exit;
+    if (exit.kind === 'exists') return sha256(existsFingerprint(projectRoot, exit.path));
+    if (exit.kind === 'check') {
+        const inputs = PROCEDURE_CHECK_INPUTS[exit.id];
+        return sha256(inputs === undefined ? '' : inputs({ projectRoot, skillDir: sidecar.skillDir }));
+    }
+    return sha256('');
+}
+
+interface ExitResult {
+    ok: boolean;
+    reason: string;
+}
+
+function evaluate(sidecar: Sidecar, step: SidecarStep, rec: StepRecord | undefined, projectRoot: string): ExitResult {
+    const exit = step.exit;
+    if (exit.kind === 'exists') {
+        return inTree(projectRoot, exit.path) ? { ok: true, reason: '' } : { ok: false, reason: `${exit.path} does not exist` };
+    }
+    if (exit.kind === 'check') {
+        const check = PROCEDURE_CHECKS[exit.id];
+        if (check === undefined) return { ok: false, reason: `check '${exit.id}' is not registered` };
+        const r = check({ projectRoot, skillDir: sidecar.skillDir });
+        return { ok: r.ok, reason: r.reason ?? '' };
+    }
+    if (exit.kind === 'schema') {
+        return { ok: false, reason: 'schema exits are not executable by this engine version' };
+    }
+    const adj = rec?.adjudication;
+    if (adj === undefined) return { ok: false, reason: 'awaiting confirmation' };
+    if (adj.step_sha !== stepSha(sidecar, step)) {
+        return { ok: false, reason: 'the step file changed after it was confirmed' };
+    }
+    return { ok: true, reason: '' };
+}
+
+function whenHolds(step: SidecarStep, projectRoot: string): boolean {
+    if (step.when === undefined) return true;
+    const present = inTree(projectRoot, step.when.path);
+    return step.when.predicate === 'file-exists' ? present : !present;
+}
+
+function exitClass(step: SidecarStep): string {
+    if (step.exit.kind === 'check') return 'verified';
+    if (step.exit.kind === 'judgement') return 'sequenced, not verified';
+    return 'shape';
+}
+
+function pushFailed(rec: StepRecord, reason: string): void {
+    if (reason === '' || rec.failed_approaches.includes(reason)) return;
+    rec.failed_approaches = [...rec.failed_approaches, reason].slice(-MAX_FAILED);
+}
+
+function atomicWrite(file: string, text: string): void {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text, 'utf-8');
+    fs.renameSync(tmp, file);
+}
+
+function defaultSkillsRoot(skill: string): string {
+    const candidates = [path.resolve(HERE, '..', '..', '..', '..', 'skills'), path.resolve(HERE, '..', '..', '..', '..', '..', 'skills')];
+    return candidates.find((c) => fs.existsSync(path.join(c, skill, 'procedure.yaml'))) ?? (candidates[0] as string);
+}
+
+function loadWork(statePath: string, sidecar: Sidecar, restart: boolean, head: string): WorkState {
+    const fresh = (): WorkState =>
+        new WorkState({ input: new Input('procedure', freshData(sidecar, head) as unknown as Record<string, never>) });
+    if (!fs.existsSync(statePath)) return fresh();
+    const st = fs.lstatSync(statePath);
+    if (st.isSymbolicLink() || !st.isFile()) throw new Refusal(`${statePath} is not a regular file`);
+    if (st.size > MAX_STATE_BYTES) throw new Refusal(`${statePath} is over the ${MAX_STATE_BYTES}-byte limit`);
+    let payload: unknown;
+    try {
+        payload = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as unknown;
+    } catch {
+        throw new Refusal(`${statePath} is not valid JSON`);
+    }
+    const kind = isDict(payload) && isDict(payload['input']) ? payload['input']['kind'] : undefined;
+    if (kind !== 'procedure') {
+        throw new Refusal(`${statePath} holds a '${String(kind)}' run; pass --state-file to start a procedure elsewhere`);
+    }
+    if (restart) return fresh();
+    let work: WorkState;
+    try {
+        work = from_dict(payload as never);
+    } catch (exc) {
+        throw new Refusal(`${statePath} does not validate: ${(exc as Error).message}`);
+    }
+    const data = validateData(work.input.data, sidecar);
+    const restartHint = 'run again with --procedure-restart to start over';
+    if (data.skill !== sidecar.skill) throw new Refusal(`the state file is bound to procedure '${data.skill}'; ${restartHint}`);
+    if (data.engine_version !== PROCEDURE_ENGINE_VERSION) {
+        throw new Refusal(`the state file was written by procedure engine v${String(data.engine_version)}; ${restartHint}`);
+    }
+    if (data.sidecar_sha !== sidecar.sha) throw new Refusal(`the ${sidecar.skill} sidecar changed since this run started; ${restartHint}`);
+    return work;
+}
+
+function brief(sidecar: Sidecar, data: ProcedureData, step: SidecarStep, headline: string): string[] {
+    const n = sidecar.steps.length;
+    const k = sidecar.steps.findIndex((s) => s.id === step.id) + 1;
+    const rec = data.steps[step.id];
+    const remaining = sidecar.steps.slice(k).map((s) => s.id);
+    const lines = [
+        `procedure ${sidecar.skill}@${data.started_head.slice(0, 12)} · step ${String(k)} of ${String(n)} (${step.id})`,
+        headline,
+        `goal: ${sidecar.brief.goal}`,
+        `done_when: ${sidecar.brief.done_when}`,
+        `step file: ${path.join(sidecar.skillDir, step.file)}`,
+        `exit: ${step.exitText} (${exitClass(step)})`,
+        `remaining: ${remaining.length === 0 ? 'none' : remaining.join(', ')}`,
+        `failed_approaches: ${rec === undefined || rec.failed_approaches.length === 0 ? 'none' : rec.failed_approaches.join('; ')}`,
+    ];
+    if (step.exit.kind === 'judgement') {
+        lines.push(
+            'This step is sequenced, not verified: no code can check it. Do it, state the decision you took, ' +
+                `then run: agent-config work --procedure ${sidecar.skill} --procedure-confirm ${step.id}`,
+        );
+    }
+    return lines;
+}
+
+export function run_procedure(opts: ProcedureRunOptions): ProcedureRunResult {
+    const env = opts.env ?? process.env;
+    if (env[PROCEDURE_KILL_SWITCH] === '1') {
+        return { code: 2, output: `procedure cursor disabled by ${PROCEDURE_KILL_SWITCH}=1; nothing was read or written` };
+    }
+    const projectRoot = path.resolve(opts.projectRoot);
+    try {
+        const sidecar = loadSidecar(opts.skillsRoot ?? defaultSkillsRoot(opts.skill), opts.skill);
+        const statePath = path.resolve(projectRoot, opts.stateFile ?? DEFAULT_STATE_FILE);
+        const head = readHead(projectRoot);
+        const work = loadWork(statePath, sidecar, opts.restart === true, head);
+        const data = work.input.data as unknown as ProcedureData;
+        const byId = new Map(sidecar.steps.map((s) => [s.id, s]));
+        const notes: string[] = [];
+
+        if (opts.confirm !== undefined && opts.confirm !== null) {
+            const target = byId.get(opts.confirm);
+            const rec = data.steps[opts.confirm];
+            if (target === undefined || target.exit.kind !== 'judgement' || data.current !== opts.confirm || rec === undefined || rec.status === 'ok') {
+                throw new Refusal(`--procedure-confirm ${opts.confirm}: only the current judgement step can be confirmed (current: ${String(data.current)})`);
+            }
+            rec.adjudication = { answer: 'confirmed', by: 'operator', at: new Date().toISOString(), step_sha: stepSha(sidecar, target) };
+        }
+
+        for (const step of sidecar.steps) {
+            const rec = data.steps[step.id];
+            if (rec === undefined || rec.status !== 'ok' || work.outcomes[step.id] !== Outcome.SUCCESS) continue;
+            const now = { head, step_sha: stepSha(sidecar, step), inputs_sha: inputsSha(sidecar, step, projectRoot) };
+            if (now.head === rec.head && now.step_sha === rec.step_sha && now.inputs_sha === rec.inputs_sha) continue;
+            const again = evaluate(sidecar, step, rec, projectRoot);
+            if (again.ok) {
+                Object.assign(rec, now);
+                notes.push(`revalidated: ${step.id} (stale, exit re-checked and still met)`);
+            } else {
+                rec.status = 'stale';
+                rec.reason = again.reason;
+                Reflect.deleteProperty(work.outcomes, step.id);
+            }
+        }
+
+        let handedOut: string | null = null;
+        const handler = (step: SidecarStep): Step => () => {
+            const rec = data.steps[step.id];
+            if (!whenHolds(step, projectRoot)) {
+                data.steps[step.id] = { status: 'skipped', reason: `skipped: ${String(step.whenText)} is false`, failed_approaches: [] };
+                return new StepResult({ outcome: Outcome.SUCCESS });
+            }
+            if (rec === undefined || rec.status === 'skipped') {
+                data.steps[step.id] = { status: 'emitted', failed_approaches: rec?.failed_approaches ?? [] };
+                data.current = step.id;
+                handedOut = step.id;
+                return new StepResult({ outcome: Outcome.PARTIAL, questions: [`do step ${step.id}`], message: 'handed out' });
+            }
+            const result = evaluate(sidecar, step, rec, projectRoot);
+            if (result.ok) {
+                const done: StepRecord = {
+                    status: 'ok',
+                    failed_approaches: rec.failed_approaches,
+                    head,
+                    step_sha: stepSha(sidecar, step),
+                    inputs_sha: inputsSha(sidecar, step, projectRoot),
+                };
+                if (rec.adjudication !== undefined) done.adjudication = rec.adjudication;
+                data.steps[step.id] = done;
+                return new StepResult({ outcome: Outcome.SUCCESS });
+            }
+            if (rec.status !== 'stale') rec.status = 'partial';
+            rec.reason = result.reason;
+            if (step.exit.kind !== 'judgement' || rec.status === 'stale') pushFailed(rec, result.reason);
+            data.current = step.id;
+            return new StepResult({ outcome: Outcome.PARTIAL, questions: [result.reason], message: result.reason });
+        };
+
+        const steps = new Map<string, Step>(sidecar.steps.map((s) => [s.id, handler(s)]));
+        const delivery = _to_delivery(work);
+        const [final, halting] = dispatch(delivery, steps, null, sidecar.steps.map((s) => s.id));
+        _sync_back(work, delivery);
+        if (final === Outcome.SUCCESS) data.current = null;
+        atomicWrite(statePath, `${JSON.stringify(to_dict(work), null, 2)}\n`);
+
+        if (final === Outcome.SUCCESS) {
+            const recs = sidecar.steps.map((s) => ({ s, r: data.steps[s.id] }));
+            const skipped = recs.filter((x) => x.r?.status === 'skipped').length;
+            const taken = recs.filter((x) => x.r?.status !== 'skipped');
+            const count = (cls: string): number => taken.filter((x) => exitClass(x.s) === cls).length;
+            return {
+                code: 0,
+                output: [
+                    ...notes,
+                    `procedure ${sidecar.skill} complete — ${String(sidecar.steps.length)} steps: ${String(count('verified'))} verified, ` +
+                        `${String(count('shape'))} shape, ${String(count('sequenced, not verified'))} sequenced, ${String(skipped)} skipped`,
+                ].join('\n'),
+            };
+        }
+        const step = byId.get(String(halting)) as SidecarStep;
+        const rec = data.steps[step.id] as StepRecord;
+        const headline =
+            handedOut === step.id
+                ? 'handed out — do this step, then run the cursor again'
+                : rec.status === 'stale'
+                  ? `stale: ${String(rec.reason)} — the exit is re-checked, the step is not handed out again`
+                  : step.exit.kind === 'judgement'
+                    ? 'awaiting confirmation'
+                    : `exit not met: ${String(rec.reason)}`;
+        return { code: 1, output: [...notes, ...brief(sidecar, data, step, headline)].join('\n') };
+    } catch (exc) {
+        if (exc instanceof Refusal || exc instanceof SidecarError) return { code: 2, output: `procedure: ${exc.message}` };
+        throw exc;
+    }
+}

package/src/agent-src/templates/scripts/work_engine/procedure/sidecar.ts

@@ -0,0 +1,185 @@
+/**
+ * A skill's `procedure.yaml`, read as untrusted input
+ * (road-to-steps-the-skill-cannot-skip 5.8).
+ *
+ * The lint (`lint_skill_procedures`) holds the authored shape in this
+ * repository; this reader is what the cursor trusts at run time, on a consumer
+ * machine where the sidecar may have been edited by anyone. So it repeats the
+ * closed schema rather than assuming the lint ran, refuses a file over
+ * {@link MAX_SIDECAR_BYTES}, and refuses any step file that is a symlink or
+ * resolves outside the skill directory. Nothing it reads is ever executed: an
+ * exit is a typed value, and a `check:` exit names a registered function.
+ */
+
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import YAML from 'yaml';
+
+import { registeredCheckIds } from './checks.js';
+
+export const SIDECAR_FILE = 'procedure.yaml';
+export const MAX_SIDECAR_BYTES = 64 * 1024;
+export const MAX_STEP_FILE_BYTES = 256 * 1024;
+const STEPS_DIR = 'references/steps/';
+const SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
+const STEP_ID = /^[a-z0-9][a-z0-9-]*$/;
+const TOP_KEYS = new Set(['schema_version', 'brief', 'steps']);
+const BRIEF_KEYS = new Set(['goal', 'inputs', 'done_when']);
+const STEP_KEYS = new Set(['id', 'file', 'exit', 'when']);
+const WHEN_PREDICATES = new Set(['file-exists', 'file-absent']);
+
+export type Exit =
+    | { kind: 'exists'; path: string }
+    | { kind: 'schema'; path: string; id: string }
+    | { kind: 'check'; id: string }
+    | { kind: 'judgement' };
+
+export interface When {
+    predicate: 'file-exists' | 'file-absent';
+    path: string;
+}
+
+export interface SidecarStep {
+    id: string;
+    file: string;
+    exit: Exit;
+    exitText: string;
+    when?: When;
+    whenText?: string;
+}
+
+export interface Sidecar {
+    skill: string;
+    skillDir: string;
+    sha: string;
+    brief: { goal: string; inputs: string[]; done_when: string };
+    steps: SidecarStep[];
+}
+
+export class SidecarError extends Error {}
+
+/** A relative path with no `..`, no scheme, no shell metacharacter. */
+export function containedPath(p: string): boolean {
+    if (p === '' || path.isAbsolute(p) || /^[a-z][a-z0-9+.-]*:/i.test(p) || /[\s;&|`$<>\\]/.test(p)) return false;
+    return !p.split('/').includes('..');
+}
+
+function isDict(v: unknown): v is Record<string, unknown> {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function closedKeys(obj: Record<string, unknown>, allowed: ReadonlySet<string>, where: string): void {
+    for (const k of Object.keys(obj)) {
+        if (!allowed.has(k)) throw new SidecarError(`${where}: unknown key '${k}'`);
+    }
+}
+
+function parseExit(raw: unknown, where: string): Exit {
+    if (raw === 'judgement') return { kind: 'judgement' };
+    const m = typeof raw === 'string' ? /^(exists|schema|check): (\S+)$/.exec(raw) : null;
+    if (m === null) throw new SidecarError(`${where}: exit is not one of exists: · schema: · check: · judgement`);
+    const arg = m[2] as string;
+    if (m[1] === 'check') {
+        if (!STEP_ID.test(arg) || !registeredCheckIds().has(arg)) {
+            throw new SidecarError(`${where}: exit 'check: ${arg}' names no registered check`);
+        }
+        return { kind: 'check', id: arg };
+    }
+    if (m[1] === 'exists') {
+        if (!containedPath(arg)) throw new SidecarError(`${where}: exit path '${arg}' escapes the project`);
+        return { kind: 'exists', path: arg };
+    }
+    const hash = arg.lastIndexOf('#');
+    const file = hash === -1 ? '' : arg.slice(0, hash);
+    if (file === '' || !containedPath(file)) throw new SidecarError(`${where}: schema exit must be <path>#<id>`);
+    return { kind: 'schema', path: file, id: arg.slice(hash + 1) };
+}
+
+function parseWhen(raw: unknown, where: string): When {
+    const m = typeof raw === 'string' ? /^([a-z-]+): (\S+)$/.exec(raw) : null;
+    if (m === null || !WHEN_PREDICATES.has(m[1] as string) || !containedPath(m[2] as string)) {
+        throw new SidecarError(`${where}: when is not file-exists: <path> or file-absent: <path>`);
+    }
+    return { predicate: m[1] as When['predicate'], path: m[2] as string };
+}
+
+/** The real path of a file inside `dir`, refusing a symlink and any escape. */
+export function containedFile(dir: string, rel: string, maxBytes: number): string {
+    const abs = path.join(dir, rel);
+    let st: fs.Stats;
+    try {
+        st = fs.lstatSync(abs);
+    } catch {
+        throw new SidecarError(`${rel} does not exist`);
+    }
+    if (st.isSymbolicLink()) throw new SidecarError(`${rel} is a symlink; a procedure file must be a regular file`);
+    if (!st.isFile()) throw new SidecarError(`${rel} is not a regular file`);
+    if (st.size > maxBytes) throw new SidecarError(`${rel} is ${st.size} bytes, over the ${maxBytes}-byte limit`);
+    const real = fs.realpathSync(abs);
+    const root = fs.realpathSync(dir);
+    if (!real.startsWith(root + path.sep)) throw new SidecarError(`${rel} resolves outside the skill`);
+    return real;
+}
+
+export function sha256(text: string | Buffer): string {
+    return createHash('sha256').update(text).digest('hex');
+}
+
+export function loadSidecar(skillsRoot: string, skill: string): Sidecar {
+    if (!SKILL_NAME.test(skill)) throw new SidecarError(`'${skill}' is not a skill name`);
+    const skillDir = path.join(skillsRoot, skill);
+    if (!fs.existsSync(path.join(skillDir, SIDECAR_FILE))) {
+        throw new SidecarError(`skill '${skill}' carries no ${SIDECAR_FILE}`);
+    }
+    const file = containedFile(skillDir, SIDECAR_FILE, MAX_SIDECAR_BYTES);
+    const text = fs.readFileSync(file, 'utf-8');
+    let doc: unknown;
+    try {
+        doc = YAML.parse(text);
+    } catch {
+        throw new SidecarError(`${SIDECAR_FILE} is not valid YAML`);
+    }
+    if (!isDict(doc)) throw new SidecarError(`${SIDECAR_FILE} must be a mapping`);
+    closedKeys(doc, TOP_KEYS, 'top level');
+    if (doc['schema_version'] !== 1) throw new SidecarError('schema_version must be 1');
+    const brief = doc['brief'];
+    if (!isDict(brief)) throw new SidecarError('brief must be a mapping');
+    closedKeys(brief, BRIEF_KEYS, 'brief');
+    const inputs = brief['inputs'];
+    if (typeof brief['goal'] !== 'string' || typeof brief['done_when'] !== 'string' || !Array.isArray(inputs)) {
+        throw new SidecarError('brief needs a string goal, a string done_when and an inputs list');
+    }
+    const rawSteps = doc['steps'];
+    if (!Array.isArray(rawSteps) || rawSteps.length === 0) throw new SidecarError('steps must be a non-empty list');
+    const seen = new Set<string>();
+    const steps = rawSteps.map((raw, i): SidecarStep => {
+        const where = `steps[${i}]`;
+        if (!isDict(raw)) throw new SidecarError(`${where} must be a mapping`);
+        closedKeys(raw, STEP_KEYS, where);
+        const id = raw['id'];
+        if (typeof id !== 'string' || !STEP_ID.test(id) || seen.has(id)) {
+            throw new SidecarError(`${where}: id must be a unique lower-case slug`);
+        }
+        seen.add(id);
+        const stepFile = raw['file'];
+        if (typeof stepFile !== 'string' || !stepFile.startsWith(STEPS_DIR) || !containedPath(stepFile)) {
+            throw new SidecarError(`${where}: file must be under ${STEPS_DIR}`);
+        }
+        containedFile(skillDir, stepFile, MAX_STEP_FILE_BYTES);
+        const step: SidecarStep = { id, file: stepFile, exit: parseExit(raw['exit'], where), exitText: String(raw['exit']) };
+        if ('when' in raw) {
+            step.when = parseWhen(raw['when'], where);
+            step.whenText = String(raw['when']);
+        }
+        return step;
+    });
+    return {
+        skill,
+        skillDir,
+        sha: sha256(text),
+        brief: { goal: brief['goal'], inputs: inputs.map(String), done_when: brief['done_when'] },
+        steps,
+    };
+}

package/src/agent-src/templates/scripts/work_engine/state.ts

@@ -154,6 +154,8 @@ export const DEFAULT_DIRECTIVE_SET = 'backend';
  * route it. R2 widens the envelope; R2 Phase 3 widens backend's capability
  * tuple in lockstep with the `refine-prompt` skill landing. R3 Phase 1 widens
  * the envelope further; `ui` capability is wired in Phase 3 of the UI track.
+ * `procedure` is run only by the procedure cursor (`work --procedure`); no
+ * directive set lists it, so the ordinary dispatch path refuses it.
  *
  * Other kinds are rejected so unknown values surface as errors instead of
  * silently falling through to a default branch.
@@ -163,6 +165,7 @@ export const KNOWN_INPUT_KINDS: ReadonlySet<string> = new Set([
     'prompt',
     'diff',
     'file',
+    'procedure',
 ]);
 
 /**