@yolo-labs/yolo-cli 0.23.0

package/dist/plan-diff.js

@@ -0,0 +1,162 @@
+/**
+ * Plan diff → mutations (Phase 8c.3 helper).
+ *
+ * Given the DB's current Plan and the parsed-from-file Plan,
+ * compute the mutation list that `work.update_plan` needs to bring
+ * the DB into the file's state. Pure — no I/O, no Mongo, no fetch.
+ *
+ * Mutation shapes match `common-api/src/services/work/plan-mutations.ts`:
+ *
+ *   { op: 'set-plan-fields', fields: { name?, description?, inputs?,
+ *     failurePolicy?, autoRetryCap?, autoRetryFallback?, integrationPolicy? } }
+ *   { op: 'add-step', step: StepDefinition }
+ *   { op: 'update-step', stepId: string, fields: <full new step shape, used as patch> }
+ *   { op: 'remove-step', stepId: string }
+ *   { op: 'set-state', state: 'draft' | 'active' | 'archived' }
+ *
+ * Re-import strategy notes:
+ *   - Top-level fields: emit `set-plan-fields` with only the fields
+ *     that differ. Compared via canonical JSON for inputs /
+ *     integrationPolicy (free-form objects); primitive equality for
+ *     scalars. The substrate validator at the Worker tier ignores any
+ *     field absent from the patch, so this is safe to send selectively.
+ *   - Steps: emit add/remove/update by stepId. `update-step.fields` is
+ *     the FULL new step shape used as a patch — the substrate's
+ *     `applyAndValidateStepPatch` re-validates after applying, so
+ *     sending the whole shape is equivalent to a per-step replace.
+ *   - Step ORDER inside the file is NOT enforced as a diff target in
+ *     v1: the substrate's executor reads `gate.config.requires`, not
+ *     array order, so reordering is semantically a no-op. New steps
+ *     from `add-step` land at the end of the array. (A later phase
+ *     can add `reorder-steps` if a UI reason emerges.)
+ *   - Description: the design says body IS Plan.description (no
+ *     frontmatter description field). The caller passes the body as
+ *     `filePlan.description`; the diff treats it as a regular
+ *     top-level string field.
+ *   - state: emit `set-state` only if the file's state differs from
+ *     the DB. Substrate-side validates the transition; this layer
+ *     just produces the request. (Renamed from `authoringState` /
+ *     `set-authoring-state` 2026-05-09 — item 17.)
+ *
+ * Input shape:
+ *   - `dbPlan` = the response from `work.get_plan` (already validated
+ *     by common-api).
+ *   - `filePlan` = the validated frontmatter object plus the body
+ *     string used as `description`.
+ */
+/**
+ * Top-level fields that round-trip through `set-plan-fields`. Order
+ * matters for nothing here — we compare by name and emit only deltas.
+ */
+const TOP_LEVEL_DIFF_FIELDS = [
+    'name',
+    'description',
+    'failurePolicy',
+    'autoRetryCap',
+    'autoRetryFallback',
+    'inputs',
+    'integrationPolicy',
+];
+/**
+ * Compute the mutation list required to bring `dbPlan` to match
+ * `filePlan`. Empty array means "nothing to do". The caller is
+ * responsible for guarding on `filePlan.planId === dbPlan.planId`
+ * before calling this — diff doesn't cross identity.
+ */
+export function computeMutations(dbPlan, filePlan) {
+    const mutations = [];
+    // 1) Top-level fields (set-plan-fields)
+    const fieldDelta = {};
+    for (const field of TOP_LEVEL_DIFF_FIELDS) {
+        const fileValue = filePlan[field];
+        const dbValue = dbPlan[field];
+        if (!equalDeep(fileValue, dbValue)) {
+            // Server validator coerces null → undefined for description; we
+            // mirror that here so the produced mutation is what the route
+            // already accepts.
+            fieldDelta[field] = fileValue ?? undefined;
+        }
+    }
+    if (Object.keys(fieldDelta).length > 0) {
+        mutations.push({ op: 'set-plan-fields', fields: fieldDelta });
+    }
+    // 2) Steps diff (add / update / remove)
+    const dbStepIndex = new Map();
+    for (const step of dbPlan.steps) {
+        const id = step.stepId;
+        if (typeof id === 'string')
+            dbStepIndex.set(id, step);
+    }
+    const fileStepIds = new Set();
+    for (const step of filePlan.steps) {
+        const id = step.stepId;
+        if (typeof id !== 'string')
+            continue;
+        fileStepIds.add(id);
+        const dbStep = dbStepIndex.get(id);
+        if (!dbStep) {
+            mutations.push({ op: 'add-step', step });
+        }
+        else if (!equalDeep(step, dbStep)) {
+            mutations.push({ op: 'update-step', stepId: id, fields: step });
+        }
+    }
+    for (const id of dbStepIndex.keys()) {
+        if (!fileStepIds.has(id)) {
+            mutations.push({ op: 'remove-step', stepId: id });
+        }
+    }
+    // 3) Plan state (set-state)
+    if (filePlan.state !== dbPlan.state) {
+        mutations.push({ op: 'set-state', state: filePlan.state });
+    }
+    return mutations;
+}
+// ─── Internals ────────────────────────────────────────────────────────────
+/**
+ * Structural equality for the value shapes that show up in plan
+ * frontmatter: strings / numbers / booleans / null / undefined / arrays
+ * of same / plain objects of same. NOT a general-purpose deep equality;
+ * doesn't handle Date, RegExp, Map, Set, class instances. None of those
+ * appear in the file → DB diff path because we're comparing JSON-shaped
+ * data on both sides.
+ *
+ * Treats `undefined` and missing keys identically, so a file that omits
+ * `autoRetryCap` matches a DB where `autoRetryCap: undefined`. Treats
+ * `null` and `undefined` as equal too — the substrate validator
+ * normalizes both ways.
+ */
+function equalDeep(a, b) {
+    if (a === b)
+        return true;
+    if (a == null && b == null)
+        return true; // null/undefined normalize
+    if (a == null || b == null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (!equalDeep(a[i], b[i]))
+                return false;
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    // Ignore keys whose values are undefined — they're equivalent to absent.
+    const aKeys = Object.keys(ao).filter((k) => ao[k] !== undefined);
+    const bKeys = Object.keys(bo).filter((k) => bo[k] !== undefined);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys) {
+        if (!equalDeep(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}

package/dist/plan-export.js

@@ -0,0 +1,261 @@
+/**
+ * `yolo plan export <planId>` orchestration (Phase 8c.4).
+ *
+ * Inverse of `yolo plan import`: DB → file. Composes everything from
+ * earlier slices:
+ *   - `work-client`     (8c.2) — mint + authenticatedRequest for
+ *                                `work.get_plan`.
+ *   - `canonicalizer`   (8b)   — pure object → canonical YAML+body.
+ *   - `revision`        (8c.2) — sha256 of the bytes we just wrote.
+ *   - `lockfile`        (8c.2) — refresh `(workspaceId, planId)`
+ *                                entry so a follow-up `import` is
+ *                                NO_CHANGE.
+ *
+ * High-level flow:
+ *
+ *   1. Resolve substrate context (env trio); error if missing.
+ *   2. Mint a session-bound delegated token; the response is the
+ *      authoritative `workspaceId`.
+ *   3. If `--workspace` was passed, assert it matches the minted
+ *      workspaceId (same ergonomics as import).
+ *   4. Call `work.get_plan(workspaceId, planId)`; serialize to the
+ *      canonical file form.
+ *   5. Write the canonical bytes to `-o <file>` (default
+ *      `<plansDir>/<planId>.md`). Errors out if the destination
+ *      directory doesn't exist UNLESS `--force` is set, in which
+ *      case it `mkdir -p`s.
+ *   6. Refresh the lockfile entry so `import` of the freshly
+ *      written file is detected as NO_CHANGE on the next run.
+ *
+ * Out of scope (deferred):
+ *   - `--diff` / dry-run output. Add when there's real demand.
+ *   - File-watch / auto-export daemon. Manual export only per the
+ *     Phase 8 design ("Bidirectional file ↔ DB sync... out of scope").
+ *   - Outside-container login. v1 errors out without `SESSION_ID`
+ *     (substrate CLI is container-only — design Round 5).
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success
+ *   - 1  = HTTP / file-write / lockfile failure
+ *   - 64 = usage error (missing planId, workspace mismatch, missing env trio)
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { canonicalizePlanFile } from './canonicalizer.js';
+import { computeRevisionHash } from './revision.js';
+import { LockfileError, readLockfile, resolveLockfilePath, setEntry, writeLockfile, } from './lockfile.js';
+import { SUBSTRATE_CLI_PLAN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+const PLAN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+export async function runPlanExport(options) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? (() => new Date().toISOString());
+    // 1) planId shape (matches substrate's PLAN_ID_REGEX)
+    if (!PLAN_ID_REGEX.test(options.planId)) {
+        return fail('usage', `invalid planId '${options.planId}': must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/`);
+    }
+    // 1b) -o basename stem must equal planId so the exported file
+    //     round-trips through `yolo plan import`, which enforces
+    //     `frontmatter.planId === file-stem` (plan-import.ts:172).
+    //     Otherwise `yolo plan export foo -o custom-name.md` produces
+    //     a file the import command refuses (Codex 8c.4 R1 Medium).
+    //     -o is for changing the DIRECTORY, not the filename.
+    if (options.outputFlag !== undefined) {
+        const outStem = path.basename(options.outputFlag, path.extname(options.outputFlag));
+        if (outStem !== options.planId) {
+            return fail('usage', `-o basename stem '${outStem}' must equal planId '${options.planId}' so the exported file round-trips through \`yolo plan import\`. ` +
+                `Either rename the output to '${options.planId}.md' (with any directory you like) or drop -o to use the default <plansDir>/${options.planId}.md.`);
+        }
+    }
+    // 2) Substrate context
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    // 3) Mint token
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_PLAN_SCOPES,
+            fetchImpl: options.fetchImpl,
+        });
+    }
+    catch (err) {
+        if (err instanceof WorkClientError) {
+            return fail('auth', `failed to mint substrate token: ${err.message}`, { status: err.status, code: err.code });
+        }
+        return fail('auth', `failed to mint substrate token: ${describeError(err)}`);
+    }
+    // 4) --workspace assertion
+    if (options.workspaceFlag && options.workspaceFlag !== mint.workspaceId) {
+        return fail('workspace_mismatch', `--workspace ${options.workspaceFlag} does not match the workspace bound to this session (${mint.workspaceId}).`);
+    }
+    // 5) work.get_plan
+    const plansDir = options.plansDir ?? path.resolve('.yolo', 'plans');
+    const requestCtx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    const fetched = await tryGet(requestCtx, mint.workspaceId, options.planId);
+    if (!fetched.ok)
+        return fetched.error;
+    // 6) Convert to canonical file bytes
+    const dbPlan = fetched.plan;
+    const { frontmatter, body } = dbPlanToFile(dbPlan);
+    const canonicalBytes = canonicalizePlanFile(frontmatter, body);
+    // 7) Resolve output path + ensure dir
+    const outputPath = options.outputFlag
+        ? path.resolve(options.outputFlag)
+        : path.join(plansDir, `${dbPlan.planId}.md`);
+    try {
+        mkdirSync(path.dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, canonicalBytes, 'utf8');
+    }
+    catch (err) {
+        return fail('write', `could not write '${outputPath}': ${describeError(err)}`);
+    }
+    // 8) Refresh lockfile so a subsequent `yolo plan import` of this
+    //    file is a NO_CHANGE (file revision == lockfile entry).
+    const revision = computeRevisionHash(canonicalBytes);
+    const exportedAt = now();
+    let lockfilePath;
+    let lockfile;
+    try {
+        lockfilePath = resolveLockfilePath(plansDir, options.lockfileFlag);
+        lockfile = readLockfile(lockfilePath);
+    }
+    catch (err) {
+        if (err instanceof LockfileError) {
+            return fail('lockfile', err.message, { code: err.code });
+        }
+        return fail('lockfile', describeError(err));
+    }
+    const newEntry = {
+        lastImportedRevision: revision,
+        lastImportedVersion: dbPlan.version,
+        lastImportedAt: exportedAt,
+    };
+    setEntry(lockfile, mint.workspaceId, dbPlan.planId, newEntry);
+    try {
+        writeLockfile(lockfilePath, lockfile);
+    }
+    catch (err) {
+        if (err instanceof LockfileError) {
+            return fail('lockfile', err.message, { code: err.code });
+        }
+        return fail('lockfile', describeError(err));
+    }
+    return {
+        ok: true,
+        planId: dbPlan.planId,
+        workspaceId: mint.workspaceId,
+        version: dbPlan.version,
+        revision,
+        outputPath,
+        exportedAt,
+        lockfilePath,
+    };
+}
+/**
+ * Convert a `work.get_plan` response (the `serializePlan` shape from
+ * `common-api/src/routes/work.ts`) to the canonical file form
+ * (frontmatter object + body string). Pure, no I/O.
+ *
+ * Strips DB-only fields (`version`, `latestRunId`, `createdAt`,
+ * `updatedAt`) per the Phase 8 design — those don't round-trip.
+ * Converts nulls back to `undefined` so the canonicalizer drops them
+ * via `reorderObject`'s "skip undefined" rule.
+ *
+ * Empty `inputs: []` is preserved in the frontmatter so a follow-up
+ * `import` produces a stable diff (round-trip equivalence). Empty
+ * `integrationPolicy: {}` is dropped since the substrate validator
+ * normalizes it to `undefined` anyway.
+ */
+export function dbPlanToFile(dbPlan) {
+    const frontmatter = {
+        planId: dbPlan.planId,
+        name: dbPlan.name,
+        state: dbPlan.state,
+        failurePolicy: dbPlan.failurePolicy ?? 'pause-and-wait',
+        steps: dbPlan.steps,
+    };
+    if (dbPlan.autoRetryCap !== undefined && dbPlan.autoRetryCap !== null) {
+        frontmatter.autoRetryCap = dbPlan.autoRetryCap;
+    }
+    if (dbPlan.autoRetryFallback !== undefined && dbPlan.autoRetryFallback !== null) {
+        frontmatter.autoRetryFallback = dbPlan.autoRetryFallback;
+    }
+    if (Array.isArray(dbPlan.inputs)) {
+        frontmatter.inputs = dbPlan.inputs;
+    }
+    if (dbPlan.integrationPolicy !== undefined &&
+        dbPlan.integrationPolicy !== null &&
+        Object.keys(dbPlan.integrationPolicy).length > 0) {
+        frontmatter.integrationPolicy = dbPlan.integrationPolicy;
+    }
+    // Body = description. canonicalizePlanFile's body-side normalization
+    // (CRLF→LF, strip leading `\n+`, exactly one trailing newline)
+    // handles whatever comes out of the DB. Treat `null`/`undefined` as
+    // empty string — canonical form will be `---\n…\n---\n\n\n`, which
+    // is an empty body plus the mandatory trailing newline.
+    const body = typeof dbPlan.description === 'string' ? dbPlan.description : '';
+    return { frontmatter, body };
+}
+async function tryGet(ctx, workspaceId, planId) {
+    const response = await authenticatedRequest(ctx, `/workspaces/${workspaceId}/plans/${planId}`, { method: 'GET' });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return {
+            ok: false,
+            error: fail('http', `work.get_plan failed: HTTP ${response.status} — ${text}`, { status: response.status }),
+        };
+    }
+    const json = (await response.json());
+    if (!json.plan) {
+        return { ok: false, error: fail('http', 'work.get_plan response missing `plan` field') };
+    }
+    return { ok: true, plan: json.plan };
+}
+// ─── Helpers + CLI surface ────────────────────────────────────────────────
+function fail(kind, message, detail) {
+    return { ok: false, kind, message, detail };
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '<no body>';
+    }
+}
+/**
+ * Map an `ExportFailure.kind` to a CLI exit code. Used by cli.ts and
+ * exported for tests.
+ */
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+        case 'auth':
+        case 'workspace_mismatch':
+            return 64; // EX_USAGE
+        case 'http':
+        case 'write':
+        case 'lockfile':
+            return 1;
+    }
+}
+/**
+ * Render an `ExportSuccess` as a single-line CLI summary. Caller
+ * appends `\n` if needed.
+ */
+export function formatSuccess(result) {
+    return `OK: exported plan '${result.planId}' (workspace ${result.workspaceId}, version ${result.version}) to ${result.outputPath} (revision ${result.revision.slice(0, 14)}…)`;
+}

package/dist/plan-frontmatter.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://yolo.studio/schemas/plan-frontmatter.json",
+  "title": "YOLO Studio Plan Frontmatter",
+  "description": "Schema for the YAML frontmatter of a `.yolo/plans/<slug>.md` file. Mirrors the WorkPlan TypeScript type in common-api/src/types/work.ts. Lossless round-trip with the canonicalizer at packages/yolo-cli/src/canonicalizer.ts.",
+  "type": "object",
+  "required": [
+    "planId",
+    "name",
+    "state",
+    "failurePolicy",
+    "steps"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "planId": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$",
+      "description": "Workspace-scoped slug. Must equal the file stem (e.g., `final-launch.md` → `planId: final-launch`). Substrate-side regex enforced at /internal/work create_plan."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "Human-readable Plan name. Tighter character-class rules (Unicode-aware) live in semantic validation, not in this schema (Draft-07 `pattern` runs through validators that don't all support `\\p{L}`/`\\p{N}` consistently)."
+    },
+    "state": {
+      "type": "string",
+      "enum": ["draft", "active", "archived"]
+    },
+    "failurePolicy": {
+      "type": "string",
+      "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked", "auto-retry"]
+    },
+    "autoRetryCap": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Required when failurePolicy is auto-retry; ignored otherwise."
+    },
+    "autoRetryFallback": {
+      "type": "string",
+      "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked"],
+      "description": "Fallback when auto-retry exhausts the cap."
+    },
+    "inputs": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/PlanInputDecl" }
+    },
+    "integrationPolicy": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Free-form per-Plan integration knobs (base branch, merge strategy, etc.). Canonicalizer sorts keys lexicographically."
+    },
+    "steps": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/StepDefinition" }
+    }
+  },
+  "definitions": {
+    "PlanInputDecl": {
+      "type": "object",
+      "required": ["name", "required"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "required": { "type": "boolean" },
+        "default": { "type": "string", "description": "Default value (string-typed; substrate inputs are always string per R5)." },
+        "description": { "type": "string" }
+      }
+    },
+    "StepDefinition": {
+      "type": "object",
+      "required": ["stepId", "name", "mode", "gates"],
+      "additionalProperties": false,
+      "properties": {
+        "stepId": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "mode": {
+          "type": "string",
+          "enum": ["workstream", "test", "critic", "manual", "preview", "automation", "decision"]
+        },
+        "runner": { "type": "string" },
+        "gates": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/GateDefinition" }
+        },
+        "declaredOutputs": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/StepDeclaredOutput" }
+        },
+        "failurePolicy": {
+          "type": "string",
+          "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked", "auto-retry"]
+        },
+        "autoRetryCap": { "type": "integer", "minimum": 0 },
+        "autoRetryFallback": {
+          "type": "string",
+          "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked"]
+        },
+        "template": { "$ref": "#/definitions/StepTemplate" }
+      }
+    },
+    "GateDefinition": {
+      "type": "object",
+      "required": ["gateId", "type", "config"],
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string", "minLength": 1 },
+        "type": {
+          "type": "string",
+          "enum": ["dependency", "dependency-failed", "dependency-any-of", "dependency-quorum", "acceptance", "artifact-presence", "test-result", "approval", "critique", "merge"]
+        },
+        "config": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Free-form per-gate-type config. Canonicalizer sorts keys lexicographically. Conventional shapes: dependency.requires (string[]); artifact-presence.{name,producerStepId}; test-result.{minPassRate,requiredSuites,retryFlakes}; critique.{rubric,minScore,reviewers}; merge.{baseBranch,allowedStrategies,requireGreenCi,blockOnConflict}."
+        }
+      }
+    },
+    "StepDeclaredOutput": {
+      "type": "object",
+      "required": ["name", "artifactType"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "artifactType": { "type": "string", "minLength": 1 },
+        "required": { "type": "boolean" }
+      }
+    },
+    "StepTemplate": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "todoContent": { "type": "string" },
+        "todoFile": { "type": "string" },
+        "branch": { "type": "string" },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Free-form key-value metadata (string-valued). Canonicalizer sorts keys lexicographically."
+        },
+        "agentType": {
+          "type": "string",
+          "enum": ["claude", "codex", "opencode-yolo", "yolo", "yolo-code"],
+          "description": "Item 16 follow-up — per-Step agent label (workstream-mode only). Forwarded to container-api's /lanes/:name/spawn-agent so the lane runner picks the matching adapter, AND used by the dispatcher to append the agent to the Plan Run's operators[] on Step Run spawn (addedReason 'step-spawn') so the agent fan grows to match actual execution. Must be in the substrate's container-spawnable set; the alias 'yolo-code' canonicalizes to 'yolo' (the canonical id token-minting expects) before persisted on the binding. test / critic / preview / automation modes don't use this field. Enum mirrors the server-side check in common-api/src/services/work/plan-validators.ts; keep them in sync."
+        },
+        "decision": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["prompt"],
+          "properties": {
+            "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 },
+            "options": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id", "label"],
+                "properties": {
+                  "id": { "type": "string", "minLength": 1 },
+                  "label": { "type": "string", "minLength": 1 },
+                  "description": { "type": "string" }
+                }
+              }
+            }
+          },
+          "description": "Decision-mode config (mode: 'decision'). A human-in-the-loop choice gate: the Run PAUSES (pauseReasonStructured.kind 'awaiting-decision') and the operator resolves via work.resolve_decision, which records the choice, completes the Step, and resumes the Run. Requires `prompt`; `options` are author-supplied or, when omitted, derived from the Step's dependency / dependency-any-of candidate gates (the bake-off 'operator picks the winner' shape). Only valid on mode='decision' Steps. Mirrors the server-side check in common-api/src/services/work/plan-validators.ts."
+        },
+        "uiBehavior": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "keepFullSizeOnTerminal": {
+              "type": "boolean",
+              "description": "SUBSTRATE_IMPROVEMENTS #31 addendum (2026-05-11) — keep this Step's tile at full chrome on the Run desktop after the Step Run reaches terminal success / skip / cancelled. Use sparingly: workstream / critic / test / automation Steps whose generated artifact (rendered dashboard, demo page, etc.) the operator wants to keep looking at after the agent finishes. Default false / undefined. Preview-mode and manual-mode Steps are exempt from compact-on-terminal regardless of this field — those modes' tiles always stay full."
+            }
+          },
+          "description": "Plan-author UI hints. Currently the only field is `keepFullSizeOnTerminal`; future hints land here as additional properties (each closed-schema)."
+        }
+      }
+    }
+  }
+}