@yolo-labs/yolo-cli 0.43.0 → 0.44.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,208 +0,0 @@
1
- /**
2
- * Plan-file canonicalizer (Phase 8b).
3
- *
4
- * Pure function: a parsed plan-frontmatter object → canonical YAML
5
- * string. The canonical form is what `import` writes to the file
6
- * after parsing/normalizing user input AND what `export` emits when
7
- * snapshotting the live DB plan back to disk. Both paths share this
8
- * one engine so a round-trip through import → export produces a
9
- * byte-identical file.
10
- *
11
- * Round 5 stance #7 + Round 2 stance answers locked these rules:
12
- * - Stable key order at the schema-defined level (planId, name,
13
- * state, …, steps[]). Top-level field order is fixed.
14
- * - Step-level + gate-level + input-level + declared-output-level +
15
- * template-level orders are also schema-defined.
16
- * - Nested arbitrary-keyed objects (gate.config,
17
- * integrationPolicy, template.metadata) sort recursively
18
- * lexicographically. The schema says nothing about their key
19
- * order, so alphabetical is the only stable rule.
20
- * - Unknown top-level keys (forward-compat) trail the known schema
21
- * fields in lexicographic order.
22
- * - Output uses `\n` line endings, single trailing newline, 2-space
23
- * indent, plain scalars where unambiguous (double-quoted when a
24
- * string would otherwise parse as a non-string YAML value), and
25
- * no boolean/numeric coercion at parse time (caller's
26
- * responsibility — js-yaml's default load is happy to coerce, so
27
- * callers should run their own validator that doesn't).
28
- *
29
- * NOT enforced here (caller's job):
30
- * - Schema validation (frontmatter shape).
31
- * - Stripping DB-only fields (`_id`, `workspaceId`, `version`,
32
- * `latestRunId`, `nextRunNumber`, `createdAt`, `updatedAt`).
33
- * - Verifying `planId` matches the file stem.
34
- * - Asserting stepId uniqueness, gate `requires` resolves to
35
- * siblings, etc.
36
- */
37
- import yaml from 'js-yaml';
38
- // ─── Schema-defined field orders ──────────────────────────────────────────
39
- // NB: no `description` at the plan level. Per the Phase 8 design
40
- // (`docs/_ORCHESTRATION_PHASE8_PLAN_FILES_DESIGN.md` §"body is
41
- // Plan.description"), the markdown body IS `Plan.description` —
42
- // frontmatter has no description field, by design, to avoid dual
43
- // sources. Step- and input-level `description` fields are unrelated
44
- // and remain in their respective `*_FIELD_ORDER`s below.
45
- const PLAN_FIELD_ORDER = [
46
- 'planId',
47
- 'name',
48
- 'state',
49
- 'failurePolicy',
50
- 'autoRetryCap',
51
- 'autoRetryFallback',
52
- 'inputs',
53
- 'integrationPolicy',
54
- 'steps',
55
- ];
56
- const STEP_FIELD_ORDER = [
57
- 'stepId',
58
- 'name',
59
- 'description',
60
- 'mode',
61
- 'runner',
62
- 'gates',
63
- 'declaredOutputs',
64
- 'failurePolicy',
65
- 'autoRetryCap',
66
- 'autoRetryFallback',
67
- 'template',
68
- ];
69
- const GATE_FIELD_ORDER = ['gateId', 'type', 'config'];
70
- const INPUT_FIELD_ORDER = ['name', 'required', 'default', 'description'];
71
- const DECLARED_OUTPUT_FIELD_ORDER = ['name', 'artifactType', 'required'];
72
- const TEMPLATE_FIELD_ORDER = ['todoContent', 'todoFile', 'branch', 'surfacesArtifacts', 'metadata'];
73
- // ─── Helpers ──────────────────────────────────────────────────────────────
74
- /**
75
- * Reorder an object's keys: known schema keys first (in the given
76
- * order), then any unknown keys lexicographically. Missing schema
77
- * keys are skipped (we never emit `null` for unset optional fields).
78
- */
79
- function reorderObject(obj, order) {
80
- const out = {};
81
- for (const key of order) {
82
- if (key in obj && obj[key] !== undefined) {
83
- out[key] = obj[key];
84
- }
85
- }
86
- const known = new Set(order);
87
- const extras = Object.keys(obj)
88
- .filter((k) => !known.has(k) && obj[k] !== undefined)
89
- .sort();
90
- for (const k of extras) {
91
- out[k] = obj[k];
92
- }
93
- return out;
94
- }
95
- /**
96
- * Recursively sort the keys of arbitrary-keyed nested objects
97
- * lexicographically. Arrays preserve their declared order; primitives
98
- * pass through unchanged.
99
- *
100
- * Used for `gate.config`, `integrationPolicy`, `template.metadata`,
101
- * and any future free-form nested map. The schema doesn't dictate
102
- * key order for these, so alphabetical is the only deterministic
103
- * choice.
104
- */
105
- function sortNestedKeys(value) {
106
- if (Array.isArray(value)) {
107
- return value.map(sortNestedKeys);
108
- }
109
- if (value !== null && typeof value === 'object') {
110
- const obj = value;
111
- const out = {};
112
- for (const key of Object.keys(obj).sort()) {
113
- out[key] = sortNestedKeys(obj[key]);
114
- }
115
- return out;
116
- }
117
- return value;
118
- }
119
- /**
120
- * Reorder a parsed plan frontmatter to canonical shape. Pure — does
121
- * not mutate the input.
122
- */
123
- export function canonicalizeFrontmatterObject(plan) {
124
- const ordered = reorderObject(plan, PLAN_FIELD_ORDER);
125
- if (Array.isArray(ordered.inputs)) {
126
- ordered.inputs = ordered.inputs.map((input) => reorderObject(input, INPUT_FIELD_ORDER));
127
- }
128
- if (ordered.integrationPolicy && typeof ordered.integrationPolicy === 'object') {
129
- ordered.integrationPolicy = sortNestedKeys(ordered.integrationPolicy);
130
- }
131
- if (Array.isArray(ordered.steps)) {
132
- ordered.steps = ordered.steps.map((step) => {
133
- const orderedStep = reorderObject(step, STEP_FIELD_ORDER);
134
- if (Array.isArray(orderedStep.gates)) {
135
- orderedStep.gates = orderedStep.gates.map((gate) => {
136
- const og = reorderObject(gate, GATE_FIELD_ORDER);
137
- if (og.config && typeof og.config === 'object') {
138
- og.config = sortNestedKeys(og.config);
139
- }
140
- return og;
141
- });
142
- }
143
- if (Array.isArray(orderedStep.declaredOutputs)) {
144
- orderedStep.declaredOutputs = orderedStep.declaredOutputs.map((d) => reorderObject(d, DECLARED_OUTPUT_FIELD_ORDER));
145
- }
146
- if (orderedStep.template && typeof orderedStep.template === 'object') {
147
- const ot = reorderObject(orderedStep.template, TEMPLATE_FIELD_ORDER);
148
- if (ot.metadata && typeof ot.metadata === 'object') {
149
- ot.metadata = sortNestedKeys(ot.metadata);
150
- }
151
- orderedStep.template = ot;
152
- }
153
- return orderedStep;
154
- });
155
- }
156
- return ordered;
157
- }
158
- // ─── YAML emission ────────────────────────────────────────────────────────
159
- /**
160
- * Emit a canonical YAML string for the given (already-reordered)
161
- * frontmatter object. Always ends with a single `\n`.
162
- */
163
- export function emitCanonicalYaml(ordered) {
164
- return yaml.dump(ordered, {
165
- noRefs: true, // no anchors/aliases
166
- sortKeys: false, // we control order ourselves; js-yaml leaves it alone
167
- lineWidth: -1, // never wrap long scalars
168
- quotingType: '"', // double-quotes when quoting is needed
169
- forceQuotes: false, // only quote when ambiguous
170
- indent: 2,
171
- flowLevel: -1, // always block style for objects/arrays (except where the YAML grammar requires flow)
172
- });
173
- }
174
- // ─── Public entry points ──────────────────────────────────────────────────
175
- /**
176
- * Canonicalize a parsed plan frontmatter object to its YAML string.
177
- * Pure: same input → same byte-identical output.
178
- */
179
- export function canonicalizeFrontmatter(plan) {
180
- const ordered = canonicalizeFrontmatterObject(plan);
181
- return emitCanonicalYaml(ordered);
182
- }
183
- /**
184
- * Canonicalize a full plan file (frontmatter + body). Output shape:
185
- *
186
- * ---
187
- * <frontmatter>
188
- * ---
189
- *
190
- * <body>
191
- *
192
- * Body is normalized to LF-only, exactly one trailing newline, no
193
- * trailing whitespace beyond that. Frontmatter and body are
194
- * separated by `---` plus one blank line (markdown-friendly).
195
- */
196
- export function canonicalizePlanFile(plan, body) {
197
- const fm = canonicalizeFrontmatter(plan);
198
- // js-yaml's dump always ends with a single \n; collapse any
199
- // accidental trailing blanks just in case.
200
- const fmTrimmed = fm.replace(/\n+$/, '\n');
201
- // Body: LF-only, strip CR; strip any leading newlines (the
202
- // frontmatter-body separator is owned by this function, not the
203
- // caller's body string — a parsed file's body capture often starts
204
- // with the blank line after the closing `---`); trim trailing
205
- // whitespace; ensure exactly one trailing newline.
206
- const bodyTrimmed = body.replace(/\r\n/g, '\n').replace(/^\n+/, '').replace(/\s+$/, '');
207
- return `---\n${fmTrimmed}---\n\n${bodyTrimmed}\n`;
208
- }
package/dist/lockfile.js DELETED
@@ -1,203 +0,0 @@
1
- /**
2
- * Plan-import lockfile (Phase 8c.2).
3
- *
4
- * Tracks `(workspaceId, planId) → { lastImportedRevision,
5
- * lastImportedVersion, lastImportedAt }` so `yolo plan import` (8c.3)
6
- * can detect drift between the file and the DB. The lockfile is NOT
7
- * an identity remap — `planId` IS the workspace-scoped DB identifier
8
- * (substrate enforces `(workspaceId, planId)` uniqueness directly).
9
- *
10
- * Two locations, per design F8.2:
11
- * - **Default** (`.yolo/plans/.imports.json`) — gitignored. Per-developer
12
- * state. Each engineer's local Plan Run / staging workspace lands here.
13
- * - **Env-named** (`.yolo/plans/.imports.<env>.json`) — opt-in checked-in.
14
- * Use for shared stable workspaces (e.g., the team's prod workspace)
15
- * so reproducible imports work across machines. Selected via
16
- * `--env <name>` on the CLI.
17
- *
18
- * Canonical write shape:
19
- * - JSON, 2-space indent, single trailing `\n`.
20
- * - Workspace IDs sorted lexicographically; planIds within each
21
- * workspace also sorted; entry keys in fixed order
22
- * (lastImportedAt, lastImportedRevision, lastImportedVersion —
23
- * alphabetical, mirroring how the plan-file canonicalizer treats
24
- * free-form maps).
25
- * - Same input → byte-identical output (idempotent re-write).
26
- *
27
- * Out of scope here (lands in 8c.3 import):
28
- * - The actual import flow (mint token → call work.create_plan /
29
- * work.update_plan → update lockfile).
30
- * - Divergence-policy decisions (`--force` to override DB version
31
- * drift, etc.) — `lockfile.ts` is just storage.
32
- *
33
- * Out of scope (8c.5 / future):
34
- * - Lockfile schema evolution. v1 has no version field; if the shape
35
- * ever changes, add a `$version` top-level field then.
36
- */
37
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
38
- import path from 'node:path';
39
- import { isWellFormedRevision } from './revision.js';
40
- const LOCKFILE_DEFAULT_BASENAME = '.imports.json';
41
- export class LockfileError extends Error {
42
- code;
43
- constructor(message, code) {
44
- super(message);
45
- this.name = 'LockfileError';
46
- this.code = code;
47
- }
48
- }
49
- /**
50
- * Resolve the lockfile path for a given plans directory and optional
51
- * env name.
52
- *
53
- * @param plansDir - the absolute or relative path to `.yolo/plans/`.
54
- * @param env - if set, picks `.imports.<env>.json` (the opt-in
55
- * checked-in variant). If unset, picks the gitignored default.
56
- */
57
- export function resolveLockfilePath(plansDir, env) {
58
- if (env !== undefined) {
59
- if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(env)) {
60
- throw new LockfileError(`--env name must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/, got '${env}'`, 'malformed');
61
- }
62
- return path.join(plansDir, `.imports.${env}.json`);
63
- }
64
- return path.join(plansDir, LOCKFILE_DEFAULT_BASENAME);
65
- }
66
- /**
67
- * Read a lockfile from disk. Returns an empty object if the file
68
- * doesn't exist (first-import case). Throws `LockfileError` if the
69
- * file is unreadable or malformed.
70
- */
71
- export function readLockfile(filePath) {
72
- if (!existsSync(filePath))
73
- return {};
74
- let text;
75
- try {
76
- text = readFileSync(filePath, 'utf8');
77
- }
78
- catch (err) {
79
- const msg = err instanceof Error ? err.message : String(err);
80
- throw new LockfileError(`could not read lockfile at ${filePath}: ${msg}`, 'unreadable');
81
- }
82
- if (text.trim() === '')
83
- return {};
84
- let parsed;
85
- try {
86
- parsed = JSON.parse(text);
87
- }
88
- catch (err) {
89
- const msg = err instanceof Error ? err.message : String(err);
90
- throw new LockfileError(`malformed JSON in lockfile at ${filePath}: ${msg}`, 'malformed');
91
- }
92
- if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
93
- throw new LockfileError(`malformed lockfile at ${filePath}: top-level must be a JSON object, got ${describe(parsed)}`, 'malformed');
94
- }
95
- return validateShape(parsed, filePath);
96
- }
97
- /**
98
- * Write a lockfile to disk in canonical form. Creates the parent
99
- * directory if missing. Idempotent: same lockfile contents always
100
- * produce byte-identical output.
101
- */
102
- export function writeLockfile(filePath, lockfile) {
103
- const dir = path.dirname(filePath);
104
- try {
105
- mkdirSync(dir, { recursive: true });
106
- }
107
- catch (err) {
108
- const msg = err instanceof Error ? err.message : String(err);
109
- throw new LockfileError(`could not create lockfile dir ${dir}: ${msg}`, 'unwritable');
110
- }
111
- const sorted = canonicalize(lockfile);
112
- const text = JSON.stringify(sorted, null, 2) + '\n';
113
- try {
114
- writeFileSync(filePath, text, 'utf8');
115
- }
116
- catch (err) {
117
- const msg = err instanceof Error ? err.message : String(err);
118
- throw new LockfileError(`could not write lockfile at ${filePath}: ${msg}`, 'unwritable');
119
- }
120
- }
121
- /**
122
- * Lookup helper. Returns the entry for a `(workspaceId, planId)` pair,
123
- * or `null` if either key is missing. Pure read — does not mutate the
124
- * lockfile.
125
- */
126
- export function getEntry(lockfile, workspaceId, planId) {
127
- return lockfile[workspaceId]?.[planId] ?? null;
128
- }
129
- /**
130
- * Mutator. Inserts or replaces the entry for a `(workspaceId, planId)`
131
- * pair. Mutates `lockfile` in place AND returns it (for chaining /
132
- * test ergonomics).
133
- */
134
- export function setEntry(lockfile, workspaceId, planId, entry) {
135
- if (!lockfile[workspaceId])
136
- lockfile[workspaceId] = {};
137
- lockfile[workspaceId][planId] = entry;
138
- return lockfile;
139
- }
140
- // ─── Internals ────────────────────────────────────────────────────────────
141
- /**
142
- * Reorder the lockfile to canonical shape: workspace IDs sorted,
143
- * planIds within each sorted, entry fields in fixed alphabetical
144
- * order. Same canonicalization rule as the plan-file canonicalizer's
145
- * `sortNestedKeys`: lex sort because the schema doesn't dictate
146
- * order. Pure — does not mutate input.
147
- */
148
- function canonicalize(lockfile) {
149
- const out = {};
150
- for (const ws of Object.keys(lockfile).sort()) {
151
- out[ws] = {};
152
- for (const planId of Object.keys(lockfile[ws]).sort()) {
153
- const e = lockfile[ws][planId];
154
- // Fixed alphabetical entry-field order (matches a future
155
- // round-trip test: read → write → read produces same object).
156
- out[ws][planId] = {
157
- lastImportedAt: e.lastImportedAt,
158
- lastImportedRevision: e.lastImportedRevision,
159
- lastImportedVersion: e.lastImportedVersion,
160
- };
161
- }
162
- }
163
- return out;
164
- }
165
- /**
166
- * Validate the shape of a parsed lockfile. Throws `LockfileError`
167
- * with `code: 'malformed_entry'` if any entry is missing required
168
- * fields or has wrong types. Returns the validated object cast to
169
- * `Lockfile`.
170
- */
171
- function validateShape(parsed, filePath) {
172
- for (const [ws, plans] of Object.entries(parsed)) {
173
- if (plans === null || typeof plans !== 'object' || Array.isArray(plans)) {
174
- throw new LockfileError(`malformed lockfile at ${filePath}: entry for workspace '${ws}' must be an object, got ${describe(plans)}`, 'malformed_entry');
175
- }
176
- for (const [planId, entry] of Object.entries(plans)) {
177
- if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
178
- throw new LockfileError(`malformed lockfile at ${filePath}: entry for ${ws}/${planId} must be an object, got ${describe(entry)}`, 'malformed_entry');
179
- }
180
- const e = entry;
181
- if (typeof e.lastImportedRevision !== 'string') {
182
- throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedRevision must be a string, got ${describe(e.lastImportedRevision)}`, 'malformed_entry');
183
- }
184
- if (!isWellFormedRevision(e.lastImportedRevision)) {
185
- throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedRevision must match 'sha256:<64-hex>', got '${e.lastImportedRevision}'`, 'malformed_entry');
186
- }
187
- if (typeof e.lastImportedVersion !== 'number' || !Number.isInteger(e.lastImportedVersion) || e.lastImportedVersion < 1) {
188
- throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedVersion must be a positive integer, got ${describe(e.lastImportedVersion)}`, 'malformed_entry');
189
- }
190
- if (typeof e.lastImportedAt !== 'string' || Number.isNaN(Date.parse(e.lastImportedAt))) {
191
- throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedAt must be an ISO-8601 timestamp, got ${describe(e.lastImportedAt)}`, 'malformed_entry');
192
- }
193
- }
194
- }
195
- return parsed;
196
- }
197
- function describe(value) {
198
- if (value === null)
199
- return 'null';
200
- if (Array.isArray(value))
201
- return 'array';
202
- return typeof value;
203
- }
@@ -1,191 +0,0 @@
1
- {
2
- "$schema": "http://json-schema.org/draft-07/schema#",
3
- "$id": "https://yolo.studio/schemas/plan-frontmatter.json",
4
- "title": "YOLO Studio Plan Frontmatter",
5
- "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.",
6
- "type": "object",
7
- "required": [
8
- "planId",
9
- "name",
10
- "state",
11
- "failurePolicy",
12
- "steps"
13
- ],
14
- "additionalProperties": false,
15
- "properties": {
16
- "planId": {
17
- "type": "string",
18
- "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$",
19
- "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."
20
- },
21
- "name": {
22
- "type": "string",
23
- "minLength": 1,
24
- "maxLength": 80,
25
- "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)."
26
- },
27
- "state": {
28
- "type": "string",
29
- "enum": ["draft", "active", "archived"]
30
- },
31
- "failurePolicy": {
32
- "type": "string",
33
- "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked", "auto-retry"]
34
- },
35
- "autoRetryCap": {
36
- "type": "integer",
37
- "minimum": 0,
38
- "description": "Required when failurePolicy is auto-retry; ignored otherwise."
39
- },
40
- "autoRetryFallback": {
41
- "type": "string",
42
- "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked"],
43
- "description": "Fallback when auto-retry exhausts the cap."
44
- },
45
- "inputs": {
46
- "type": "array",
47
- "items": { "$ref": "#/definitions/PlanInputDecl" }
48
- },
49
- "integrationPolicy": {
50
- "type": "object",
51
- "additionalProperties": true,
52
- "description": "Free-form per-Plan integration knobs (base branch, merge strategy, etc.). Canonicalizer sorts keys lexicographically."
53
- },
54
- "steps": {
55
- "type": "array",
56
- "items": { "$ref": "#/definitions/StepDefinition" }
57
- }
58
- },
59
- "definitions": {
60
- "PlanInputDecl": {
61
- "type": "object",
62
- "required": ["name", "required"],
63
- "additionalProperties": false,
64
- "properties": {
65
- "name": { "type": "string", "minLength": 1 },
66
- "required": { "type": "boolean" },
67
- "default": { "type": "string", "description": "Default value (string-typed; substrate inputs are always string per R5)." },
68
- "description": { "type": "string" }
69
- }
70
- },
71
- "StepDefinition": {
72
- "type": "object",
73
- "required": ["stepId", "name", "mode", "gates"],
74
- "additionalProperties": false,
75
- "properties": {
76
- "stepId": { "type": "string", "minLength": 1 },
77
- "name": { "type": "string", "minLength": 1 },
78
- "description": { "type": "string" },
79
- "mode": {
80
- "type": "string",
81
- "enum": ["workstream", "test", "critic", "manual", "preview", "automation", "decision"]
82
- },
83
- "runner": { "type": "string" },
84
- "gates": {
85
- "type": "array",
86
- "items": { "$ref": "#/definitions/GateDefinition" }
87
- },
88
- "declaredOutputs": {
89
- "type": "array",
90
- "items": { "$ref": "#/definitions/StepDeclaredOutput" }
91
- },
92
- "failurePolicy": {
93
- "type": "string",
94
- "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked", "auto-retry"]
95
- },
96
- "autoRetryCap": { "type": "integer", "minimum": 0 },
97
- "autoRetryFallback": {
98
- "type": "string",
99
- "enum": ["pause-and-wait", "abort-run", "proceed-on-non-blocked"]
100
- },
101
- "template": { "$ref": "#/definitions/StepTemplate" }
102
- }
103
- },
104
- "GateDefinition": {
105
- "type": "object",
106
- "required": ["gateId", "type", "config"],
107
- "additionalProperties": false,
108
- "properties": {
109
- "gateId": { "type": "string", "minLength": 1 },
110
- "type": {
111
- "type": "string",
112
- "enum": ["dependency", "dependency-failed", "dependency-any-of", "dependency-quorum", "acceptance", "artifact-presence", "test-result", "approval", "critique", "merge"]
113
- },
114
- "config": {
115
- "type": "object",
116
- "additionalProperties": true,
117
- "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}."
118
- }
119
- }
120
- },
121
- "StepDeclaredOutput": {
122
- "type": "object",
123
- "required": ["name", "artifactType"],
124
- "additionalProperties": false,
125
- "properties": {
126
- "name": { "type": "string", "minLength": 1 },
127
- "artifactType": { "type": "string", "minLength": 1 },
128
- "required": { "type": "boolean" }
129
- }
130
- },
131
- "StepTemplate": {
132
- "type": "object",
133
- "additionalProperties": false,
134
- "properties": {
135
- "todoContent": { "type": "string" },
136
- "todoFile": { "type": "string" },
137
- "branch": { "type": "string" },
138
- "surfacesArtifacts": {
139
- "type": "array",
140
- "maxItems": 8,
141
- "uniqueItems": true,
142
- "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "\\S" },
143
- "description": "work.report_artifact artifactTypes to relay to the requester as they land (e.g. a preview URL), instead of only at run terminal. Default: none. Max 8 unique non-blank types, each \u2264 64 chars. NOTE: currently honored ONLY for assistant quick-job (ephemeral) runs; inert on a standard Plan Run (no channel to relay to)."
144
- },
145
- "metadata": {
146
- "type": "object",
147
- "additionalProperties": { "type": "string" },
148
- "description": "Free-form key-value metadata (string-valued). Canonicalizer sorts keys lexicographically."
149
- },
150
- "agentType": {
151
- "type": "string",
152
- "enum": ["claude", "codex", "opencode-yolo", "yolo", "yolo-code"],
153
- "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."
154
- },
155
- "decision": {
156
- "type": "object",
157
- "additionalProperties": false,
158
- "required": ["prompt"],
159
- "properties": {
160
- "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 },
161
- "options": {
162
- "type": "array",
163
- "items": {
164
- "type": "object",
165
- "additionalProperties": false,
166
- "required": ["id", "label"],
167
- "properties": {
168
- "id": { "type": "string", "minLength": 1 },
169
- "label": { "type": "string", "minLength": 1 },
170
- "description": { "type": "string" }
171
- }
172
- }
173
- }
174
- },
175
- "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."
176
- },
177
- "uiBehavior": {
178
- "type": "object",
179
- "additionalProperties": false,
180
- "properties": {
181
- "keepFullSizeOnTerminal": {
182
- "type": "boolean",
183
- "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."
184
- }
185
- },
186
- "description": "Plan-author UI hints. Currently the only field is `keepFullSizeOnTerminal`; future hints land here as additional properties (each closed-schema)."
187
- }
188
- }
189
- }
190
- }
191
- }