cyc-stack 0.10.0 → 0.11.0

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.
Files changed (36) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/bin/cyc.mjs +55 -7
  5. package/docs/README.md +2 -0
  6. package/docs/runtime.md +4 -0
  7. package/docs/work-queue.md +187 -0
  8. package/methods/cyc-build/SKILL.md +1 -1
  9. package/methods/cyc-design/frontend-design/SKILL.md +125 -28
  10. package/methods/cyc-design/frontend-design/references/color.md +42 -50
  11. package/methods/cyc-design/frontend-design/references/craft-rules.md +13 -10
  12. package/methods/cyc-design/frontend-design/references/decision-sheet.md +94 -98
  13. package/methods/cyc-design/frontend-design/references/experience-review.md +10 -2
  14. package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
  15. package/methods/cyc-design/frontend-design/references/generic-tells.md +82 -33
  16. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
  17. package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
  18. package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
  19. package/methods/cyc-design/frontend-design/references/typography.md +59 -44
  20. package/methods/cyc-design/frontend-design/references/visual-material.md +40 -7
  21. package/methods/cyc-design/frontend-design/scripts/contrast.mjs +1 -1
  22. package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
  23. package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
  24. package/methods/cyc-verify/SKILL.md +1 -1
  25. package/package.json +6 -1
  26. package/plugin.json +1 -1
  27. package/scripts/hub-page.mjs +275 -0
  28. package/scripts/hub.mjs +139 -0
  29. package/scripts/queue-board.mjs +287 -0
  30. package/scripts/queue.mjs +283 -0
  31. package/scripts/run-gate.mjs +1 -1
  32. package/scripts/runtime.mjs +248 -13
  33. package/scripts/source-snapshot.mjs +1 -1
  34. package/scripts/work-review.mjs +1 -1
  35. package/skills/cyc/SKILL.md +8 -0
  36. package/skills/cyc/references/playbooks/plan.md +2 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
package/bin/cyc.mjs CHANGED
@@ -5,19 +5,19 @@ import { resolveExecution, artifactFiles } from '../scripts/execution.mjs';
5
5
  import { isDeepStrictEqual } from 'node:util';
6
6
  import { catalog, routeTask } from '../scripts/catalog.mjs';
7
7
  import { completionGuidance } from '../scripts/recovery.mjs';
8
- import { acceptFailure, activeRun, callerSession, inputPath, completeRun, controlRun, finishRun, nextRun, projectFile, proveRun, quickHandoff, readRun, recordHandoff, recoverRun, retryRun, reviewRun, startRun, verifyRun, captureReview, recordReview, startOperation, waitOperation, prepareRunContext, taskContext, delegateRun } from '../scripts/runtime.mjs';
8
+ import { acceptFailure, activeRun, callerSession, inputPath, completeRun, controlRun, finishRun, nextRun, projectFile, proveRun, quickHandoff, readRun, recordHandoff, recoverRun, retryRun, reviewRun, startRun, verifyRun, captureReview, recordReview, startOperation, waitOperation, prepareRunContext, taskContext, delegateRun, queueCommand, queueOf, boardOf, recordBoardReview } from '../scripts/runtime.mjs';
9
9
 
10
10
  const args = process.argv.slice(2);
11
11
  const positionals = [];
12
12
  const options = {};
13
- const flags = new Set(['dry-run', 'help', 'verbose', 'verify', 'reviewed', 'write', 'all', 'expanded', 'json']);
13
+ const flags = new Set(['dry-run', 'help', 'verbose', 'verify', 'reviewed', 'write', 'all', 'expanded', 'json', 'open', 'from-board']);
14
14
  try {
15
15
  for (let i = 0; i < args.length; i++) {
16
16
  if (!args[i].startsWith('--')) { positionals.push(args[i]); continue; }
17
17
  const name = args[i].slice(2);
18
18
  if (flags.has(name)) { options[name] = true; continue; }
19
19
  if (['mode', 'conversation', 'wait-ms', 'operation'].includes(name)) { const value = args[++i]; if (!value || value.startsWith('--')) throw new Error(`--${name} needs a value.`); options[name] = value; continue; }
20
- if (!['project', 'hosts', 'host', 'token', 'goal', 'playbook', 'criteria', 'run', 'file', 'scope', 'stage', 'reason', 'session', 'since', 'check', 'status', 'summary', 'artifact', 'criteria-passed', 'criterion-evidence', 'next', 'criterion', 'verbose', 'assessment', 'response', 'blocker', 'advisory', 'passed', 'unmet', 'tests', 'path', 'limit', 'recipe', 'kind', 'plan', 'scout', 'new', 'doc', 'update-run', 'before'].includes(name)) throw new Error(`Unknown option --${name}`);
20
+ if (!['project', 'hosts', 'host', 'token', 'goal', 'playbook', 'criteria', 'run', 'file', 'scope', 'stage', 'reason', 'session', 'since', 'check', 'status', 'summary', 'artifact', 'criteria-passed', 'criterion-evidence', 'next', 'criterion', 'verbose', 'assessment', 'response', 'blocker', 'advisory', 'passed', 'unmet', 'tests', 'path', 'limit', 'recipe', 'kind', 'plan', 'scout', 'new', 'doc', 'update-run', 'before', 'queue', 'seat', 'unit', 'port'].includes(name)) throw new Error(`Unknown option --${name}`);
21
21
  const value = args[++i];
22
22
  if (!value || value.startsWith('--')) throw new Error(`--${name} needs a value.`);
23
23
  if (['scope', 'artifact', 'criterion', 'passed', 'unmet', 'tests', 'path'].includes(name)) {
@@ -32,6 +32,10 @@ try {
32
32
  if (options.since !== undefined && command !== 'readiness' && command !== 'context') throw new Error('--since is only supported by readiness and context review.');
33
33
  if (options['update-run'] !== undefined || options.new !== undefined) throw new Error('--new and --update-run were removed: context review --write publishes change records and never edits a doc');
34
34
  if ((options.write || options.all || options.doc !== undefined || options.before !== undefined) && command !== 'context') throw new Error('--write, --all, --doc and --before are only supported by context.');
35
+ if (options.queue !== undefined && command !== 'queue') throw new Error('--queue is only supported by the queue command. A run joins a queue through the queue field of its start file.');
36
+ if ((options.seat !== undefined || options.unit !== undefined || options.open) && command !== 'queue') throw new Error('--seat, --unit and --open are only supported by the queue command.');
37
+ if (options.port !== undefined && command !== 'hub') throw new Error('--port is only supported by hub.');
38
+ if (options['from-board'] && (command !== 'run' || action !== 'review-record')) throw new Error('--from-board is only supported by run review-record.');
35
39
  if (options.verify && command !== 'onboard') throw new Error('--verify is only supported by onboard. Use run verify for task verification.');
36
40
  if (options.verify && options['dry-run']) throw new Error('Do not combine --verify with --dry-run. Plain onboard performs read-only inspection.');
37
41
  if (!command || command === 'help' || options.help) {
@@ -96,6 +100,20 @@ Execute through your existing AI host:
96
100
  cyc run review-record --run ID --file REVIEW.json (reviewId, evidence, identity or null, findings)
97
101
  cyc run pause|resume|stop --run ID
98
102
 
103
+ Work queue (ordered units, each an ordinary run; docs/work-queue.md):
104
+ cyc queue create --file QUEUE.json (version, goal, requirements, units: id, outcome, playbook, criteria, paths, dependsOn)
105
+ cyc queue status [--queue ID] (each unit's status, read from its runs)
106
+ cyc queue next [--queue ID] (the ready unit and its start file, or the halted unit and why)
107
+ (start it with run start --file; the start file's queue field binds the run to the unit)
108
+ cyc queue decide [--queue ID] --file DECISION.json (version, action retry|skip|cancel, reason; unit for retry and skip)
109
+ cyc queue post [--queue ID] [--run ID | --seat ID] --file MESSAGE.json (kind question|finding|answer|notice; neither option: the person)
110
+ cyc queue board [--queue ID] [--unit ID] [--open] [--seat ID] (--open: unanswered items)
111
+ cyc queue wait [--queue ID] (--run ID | --seat ID) [--wait-ms N] (until a message arrives; at most 60000)
112
+ cyc queue next [--queue ID] --seat review --session ID [--wait-ms N] (review the unit in progress)
113
+ cyc queue release [--queue ID] --seat ID
114
+ cyc run review-record --run ID --from-board (a peer receipt from that review)
115
+ cyc hub [--project PATH] [--port N] (a page on this machine to watch the queue: the line, what the agents say, what waits on you)
116
+
99
117
  Deliver the reply:
100
118
  cyc check-reply FILE [--session ID | --expanded]
101
119
  (the Stop gate's reply checks on a draft: character count, how much to cut, visual; reads nothing else and writes nothing.
@@ -193,6 +211,25 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
193
211
  result = (await import('../scripts/run-gate.mjs')).sessionReadiness({ root, session: options.session, since: options.since });
194
212
  } else if (command === 'packet') {
195
213
  result = (await import('../scripts/packet.mjs')).writePacket(root, { session: options.session, executionMode: options.mode, conversationId: options.conversation, responseFile: options.response, status: options.status, blocker: options.blocker, advisory: options.advisory, passed: options.passed ?? [], unmet: options.unmet ?? [], artifacts: options.artifact ?? [], reviewed: !!options.reviewed });
214
+ } else if (command === 'hub') {
215
+ // Stays running: the server keeps the process alive after its address is printed.
216
+ const stray = [...positionals.slice(1), ...Object.keys(options).filter(name => !['project', 'port'].includes(name)).map(name => `--${name}`)];
217
+ if (stray.length) throw new Error(`cyc hub takes only --project and --port, not ${stray.join(', ')}. It shows every queue; pick one on the page.`);
218
+ if (options.port !== undefined && !/^\d+$/.test(options.port)) throw new Error('--port is a whole number from 0 to 65535.');
219
+ const hub = await (await import('../scripts/hub.mjs')).startHub(root, { port: options.port === undefined ? undefined : Number(options.port) });
220
+ result = { ok: true, url: hub.url, project: hub.project, note: 'The hub is running on this machine only and changes nothing. Open the address in a browser. Press Ctrl+C to stop it.' };
221
+ } else if (command === 'queue') {
222
+ if (!['create', 'status', 'next', 'decide', 'post', 'board', 'wait', 'release'].includes(action)) throw new Error('Use queue create, status, next or decide; the board takes queue post, board, wait and release.');
223
+ const takes = { create: ['file', 'session'], status: ['queue', 'session'], next: ['queue', 'seat', 'session', 'wait-ms'], decide: ['file', 'queue', 'session'], post: ['file', 'queue', 'run', 'seat', 'session'], board: ['queue', 'unit', 'open', 'seat', 'session'], wait: ['queue', 'run', 'seat', 'wait-ms', 'session'], release: ['queue', 'seat', 'session'] }[action];
224
+ fileOnly(options, ['file', 'queue', 'project', 'verbose', 'run', 'seat', 'unit', 'open', 'session', 'wait-ms']);
225
+ const fromFile = ['create', 'decide', 'post'].includes(action);
226
+ if (fromFile !== !!options.file) throw new Error(fromFile ? `queue ${action} needs --file JSON.` : `queue ${action} takes no --file.`);
227
+ if (action === 'create' && options.queue) throw new Error('queue create assigns the queue ID; do not pass --queue.');
228
+ const extra = Object.keys(options).filter(key => !['project', 'verbose', ...takes].includes(key));
229
+ if (extra.length) throw new Error(`queue ${action} does not take ${extra.map(key => `--${key}`).join(', ')}.`);
230
+ result = queueCommand(root, action, action === 'create' ? readJSON(options.file)
231
+ : action === 'decide' ? { ...inputObject(options.file, ['version', 'unit', 'action', 'reason']), queue: options.queue }
232
+ : { queue: options.queue, ...(action === 'post' ? { message: readJSON(options.file) } : {}), ...Object.fromEntries([['run', options.run], ['seat', options.seat], ['unit', options.unit], ['session', options.session], ['waitMs', options['wait-ms']]].filter(([, value]) => value !== undefined)), ...(options.open ? { open: true } : {}) });
196
233
  } else if (command === 'playbooks') result = catalog;
197
234
  else if (command === 'route') {
198
235
  if (!options.goal) throw new Error('--goal is required.');
@@ -203,7 +240,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
203
240
  let input;
204
241
  if (options.file) {
205
242
  fileOnly(options, ['file', 'project', 'verbose']);
206
- input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy', 'executionMode', 'conversationId', 'proofCommands', 'contextRetention', 'taskContext', 'delegation']);
243
+ input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy', 'executionMode', 'conversationId', 'proofCommands', 'contextRetention', 'taskContext', 'delegation', 'queue']);
207
244
  for (const key of ['goal', 'playbook', 'session', 'plan']) if (input[key] !== undefined && typeof input[key] !== 'string') throw new Error(`${key} must be a string.`);
208
245
  if (input.scout !== undefined && !object(input.scout)) throw new Error('scout must be the Scout assessment object (run start without it returns the template).');
209
246
  if (input.criteria !== undefined && (!Array.isArray(input.criteria) || !input.criteria.length || input.criteria.some(item => !object(item) || typeof item.id !== 'string' || typeof item.description !== 'string'))) throw new Error('criteria must be a nonempty array of {id, description} string records.');
@@ -263,6 +300,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
263
300
  if (!options.file) throw new Error('review-capture needs --file JSON with reviewer and optional scope.');
264
301
  result = captureReview(root, options.run, inputObject(options.file, ['reviewer', 'scope', 'contextPaths', 'contextEvidence'])); break;
265
302
  case 'review-record':
303
+ if (options['from-board']) { if (options.file) throw new Error('review-record --from-board takes no --file: the receipt is built from the queue board.'); result = recordBoardReview(root, options.run, options.session); break; }
266
304
  if (!options.file) throw new Error('review-record needs --file JSON with reviewId, evidence, identity and findings.');
267
305
  result = recordReview(root, options.run, inputObject(options.file, ['reviewId', 'evidence', 'identity', 'findings'])); break;
268
306
  case 'pause': case 'resume': case 'stop': result = controlRun(root, options.run, action); break;
@@ -270,6 +308,14 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
270
308
  }
271
309
  } else throw new Error(`Unknown command ${command}. Use cyc help.`);
272
310
  if (command === 'run' && !options.verbose) result = compact(action, result, root, options);
311
+ // A bound run's board entry comes first: agents act on the head of a result.
312
+ if (command === 'run' && result && typeof result === 'object' && !Array.isArray(result)) {
313
+ const id = options.run ?? result.runId;
314
+ // Reading commands leave the board's mark where it was.
315
+ const board = typeof id === 'string' ? boardOf(root, id, !['status', 'recover', 'list', 'review'].includes(action), options.session) : null;
316
+ if (board) result = { board: result.board?.hold && !board.hold ? { ...board, hold: result.board.hold } : board, ...Object.fromEntries(Object.entries(result).filter(([key]) => key !== 'board')) };
317
+ if ((result.result ?? result).status === 'needs-answer') delete result.guidance;
318
+ }
273
319
  console.log(humanInstallOutput(command) ? formatInstall(result) : JSON.stringify(result, null, 2));
274
320
  if (result?.ok === false || result?.status === 'needs-context-sync' || ['halted', 'exhausted', 'blocked'].includes(result?.status) || result?.passed === false || result?.result?.passed === false || ['halted', 'exhausted', 'blocked'].includes(result?.result?.status)) process.exitCode = 1;
275
321
  } catch (error) {
@@ -350,12 +396,14 @@ function compact(action, result, root, options) {
350
396
  if (!result || typeof result !== 'object' || ['status', 'recover'].includes(action)) return result;
351
397
  const id = result.runId ?? result.id ?? options.run;
352
398
  const guidance = value => completionGuidance(value, { executionMode: (value.result ?? value).packet?.written === false ? readRun(root, id).execution?.mode : undefined });
353
- if (result.operationId) return { ...result, guidance: guidance(result) };
399
+ // A run bound to a queue unit also says where the line stands. Advice only: it changes no result.
400
+ const lined = value => { let line = null; try { line = queueOf(root, readRun(root, id)); } catch { /* advice only */ } return line ? { ...value, queue: line } : value; };
401
+ if (result.operationId) return lined({ ...result, guidance: guidance(result) });
354
402
  if (['review-capture', 'review-record'].includes(action)) { const { files, ...receipt } = result; return receipt; }
355
403
  if (action === 'prove-red') return result;
356
404
  if (action === 'finish') {
357
405
  const display = result.failedAt === 'verify' && 'verificationStatus' in result ? { ...compact('verify', result, root, options), finished: false, failedAt: 'verify' } : result;
358
- return { ...display, guidance: guidance(display) };
406
+ return lined({ ...display, guidance: guidance(display) });
359
407
  }
360
408
  if (action === 'verify') {
361
409
  const recovery = result.passed ? null : recoverRun(root, id);
@@ -376,5 +424,5 @@ function compact(action, result, root, options) {
376
424
  // Agents often read only the first lines (| head -40), so what they act on comes first and the
377
425
  // long fill-in template last.
378
426
  const lead = Object.fromEntries(['runId', 'status', 'stage', 'attempt', 'finishTemplate', 'verificationSource', 'verificationCommands', 'baseline', 'baselineFailures', 'testProof', 'finishWith', 'ledgerPath', 'feedback'].filter(key => key in rest).map(key => [key, rest[key]]));
379
- return { ...lead, criteria: criteria.map(item => item.id), previous: previousHandoff ? { stage: previousHandoff.stage, status: previousHandoff.status, summary: previousHandoff.summary } : null, ...rest, ...(result.acceptedFailures ? { acceptedFailures: result.acceptedFailures } : {}), ...(['paused', 'blocked', 'halted', 'exhausted', 'stopped'].includes(next.status) ? { recovery: recoverRun(root, id) } : {}), assessmentRequired, ...(rest.finishTemplate ? {} : { assessmentTemplate }) };
427
+ return lined({ ...lead, criteria: criteria.map(item => item.id), previous: previousHandoff ? { stage: previousHandoff.stage, status: previousHandoff.status, summary: previousHandoff.summary } : null, ...rest, ...(result.acceptedFailures ? { acceptedFailures: result.acceptedFailures } : {}), ...(['paused', 'blocked', 'halted', 'exhausted', 'stopped'].includes(next.status) ? { recovery: recoverRun(root, id) } : {}), assessmentRequired, ...(rest.finishTemplate ? {} : { assessmentTemplate }) });
380
428
  }
package/docs/README.md CHANGED
@@ -19,6 +19,8 @@ Start with the guide for the task at hand. Current operating guidance lives here
19
19
  | Need | Guide |
20
20
  | --- | --- |
21
21
  | Controller state, commands and source-bound evidence | [Runtime](runtime.md) |
22
+ | Run a plan's units in order, one verified run at a time | [Work queue](work-queue.md) |
23
+ | Watch a queue being worked: the line, what the agents say, what waits on you | [The hub](work-queue.md#the-hub) |
22
24
  | Stage handoffs and evidence labels | [Skill contract](skill-contract.md) |
23
25
  | Required work assessments | [Work assessments](work-assessments.md) |
24
26
  | Impact investigation | [Impact analysis](impact-analysis.md) |
package/docs/runtime.md CHANGED
@@ -20,6 +20,8 @@ Bind --run ID. next/status inspect; record submits a handoff; finish orchestrate
20
20
 
21
21
  Use --wait-ms 30000 for long checks and run wait with the returned operation ID. Silence/operation completion is not workflow success. Honor interruption and restoration acknowledgment.
22
22
 
23
+ A [work queue](work-queue.md) orders several runs: queue create/status/next/decide, with the start file's queue field binding a run to its unit. Start rules reject a unit out of order, changed criteria or paths outside the unit; a run that ends short of complete halts the line until a recorded decision. Unit status is read from the runs, never stored. Its board (`queue post`, `board`, `wait`) carries messages between the agents on a queue and the person; a bound run cannot complete while the board holds it, and a second conversation can review a unit from `queue next --seat review`.
24
+
23
25
  Verify/Deliver needs criterion evidence: --criteria-passed for one or --criterion-evidence for multiple. Worker/model reports cannot replace configured checks, original proof or semantic review.
24
26
 
25
27
  ## Context and delegation
@@ -36,6 +38,8 @@ Failed attempts share maxAttempts (default 3) and maxNoProgress (default 2); rec
36
38
 
37
39
  Proof separates original control, originals with new tests and candidate. Features may prove a missing interface; bugs need existing behavior. Only compatible measured broad originals can excuse broad candidate failures. Matching diagnostics/passing evidence and reasons are required; changed causes, new/lost failures, cutoff and unknowns stay blocking. Disclose accepted failures.
38
40
 
41
+ A proof command may name only test files the change adds. On the run-start code it finds no file and exits before any test runs. The control still runs; when it prints no test results and every failing test with the new tests added is in a test file the change added, that exit is read as nothing to run, and the receipt records `controlWithoutTests`. A mistyped or never-created file, output without test names, or a deleted or moved test file stays inconclusive.
42
+
39
43
  <a id="run-start-originals"></a>
40
44
 
41
45
  ## Shared working-folder ownership
@@ -0,0 +1,187 @@
1
+ # Work queue
2
+
3
+ A work queue is an ordered set of units. Each unit is an ordinary CYC run with its own criteria, checks and evidence. The [controller](runtime.md) decides which unit may start, so a larger piece of work moves one verified step at a time.
4
+
5
+ ```text
6
+ Plan → queue create → queue next → run start → run finish → queue next → …
7
+ a run that ends short of complete halts the line
8
+ ```
9
+
10
+ Use a queue when a [plan](../skills/cyc/references/playbooks/plan.md) has several units and the order matters. One change does not need one.
11
+
12
+ ## The queue file
13
+
14
+ Save the units under `.cyc/runtime` and pass the file to `queue create`:
15
+
16
+ ```json
17
+ {
18
+ "version": 1,
19
+ "goal": "Customers can export their orders",
20
+ "requirements": "The original request, word for word",
21
+ "units": [
22
+ {
23
+ "id": "export-endpoint",
24
+ "outcome": "An endpoint returns every order matching the current filters as CSV",
25
+ "playbook": "feature",
26
+ "criteria": [{ "id": "all-rows", "description": "Exports all matching orders, not the visible page" }],
27
+ "paths": ["src/orders", "test/orders"],
28
+ "dependsOn": []
29
+ }
30
+ ]
31
+ }
32
+ ```
33
+
34
+ A unit names what is true when it is done, not how to build it: earlier units change the code that later units meet. `paths` is the limit of what the unit's run may change. `dependsOn` lists units that must be done first.
35
+
36
+ Unknown fields, duplicate or missing unit ids, an unknown playbook, a unit without paths and a dependency cycle are refused. The units are frozen when the queue is created. A queue whose units were edited afterwards is refused; cancel it and create a new one.
37
+
38
+ ## Commands
39
+
40
+ | Command | What it does |
41
+ | --- | --- |
42
+ | `cyc queue create --file QUEUE.json` | Checks and stores the queue. |
43
+ | `cyc queue status [--queue ID]` | Every unit with its status and runs. |
44
+ | `cyc queue next [--queue ID]` | The ready unit with a start file, or the halted unit and why. |
45
+ | `cyc queue decide [--queue ID] --file DECISION.json` | Records a person's decision about a halted unit. |
46
+
47
+ `--queue` may be left out while one queue is open; when none is, the error names the queue that finished last. Every queue command accepts `--session`.
48
+
49
+ `queue next` writes a start file with the unit's goal, playbook, criteria, paths and a `queue` field. For a playbook that starts with Scout, scout the unit, add `scout` and `plan` (and `contextRetention` when it builds) to that file, then `run start --file` it. Other playbooks start the file as written. From there the run is worked and finished like any other.
50
+
51
+ `queue next` also lists the change records of the units this one depends on, and `drift`: the files changed since the last unit completed, or since the line's first run started. They come from an attempt that ended short of complete or an edit outside the line, and a retry starts from them. `drift.outsideUnit` lists the ones the unit's run may not touch: tell the user before building on them. A bound run records the same drift at start. Drift never refuses a start, and says so (`lostRuns`) when a lost run record leaves the starting point unknown.
52
+
53
+ ## Rules at start
54
+
55
+ A run with a `queue` field starts only when all of these hold. They are checked before any run record is written.
56
+
57
+ 1. The unit is ready: every unit it depends on is done.
58
+ 2. No other unit of the queue is in progress or halted. One unit runs at a time.
59
+ 3. The playbook and criteria equal the unit's.
60
+ 4. Every entry in `allowedPaths` is inside the unit's `paths`. Narrower is fine. The context docs the controller adds for retention are allowed as usual.
61
+
62
+ A start without a `queue` field is an ordinary run, unchanged.
63
+
64
+ ## Unit status
65
+
66
+ Status is read from the unit's runs each time. The queue stores no copy of it.
67
+
68
+ | The unit's latest run | Status |
69
+ | --- | --- |
70
+ | None yet, and a dependency is not done | `waiting` |
71
+ | None yet, and every dependency is done | `ready` |
72
+ | Running or paused | `in-progress` |
73
+ | Complete | `done` |
74
+ | Blocked, halted, exhausted or stopped | `halted` |
75
+ | Its record can no longer be read (`missing`) | `halted` |
76
+ | Ended, with a recorded skip | `skipped` |
77
+ | Any, not done, in a cancelled queue | `cancelled` |
78
+
79
+ A unit's attempts are ordered by attempt number, and a run that has not ended decides the unit whichever attempt it is.
80
+
81
+ The line as a whole is `halted` when any unit is halted, `in-progress` when one is running, `complete` when all are done, `ready` when a unit can start, `ended` when what remains was skipped or waits on a skipped unit, and `cancelled` after a cancel. An ended line needs a cancel before a new queue replaces it.
82
+
83
+ ## When the line halts
84
+
85
+ A halted unit stops the whole line. `queue next` returns that unit, the reason its run recorded and the same `drift`, so the files a retry would start from are seen before anyone decides.
86
+
87
+ A blocked run has not ended: resume and finish it, or stop it. A stopped run keeps the reason it was blocked for. A run that ended halted, exhausted or stopped, or whose record is missing, needs a decision from a person:
88
+
89
+ ```json
90
+ { "version": 1, "unit": "export-endpoint", "action": "retry", "reason": "The failing check was a network outage" }
91
+ ```
92
+
93
+ | Action | Effect |
94
+ | --- | --- |
95
+ | `retry` | The unit may start again. The earlier run stays listed under it. |
96
+ | `skip` | The unit is passed over. Units that depend on it keep waiting. |
97
+ | `cancel` | Closes the queue. It takes no `unit`. |
98
+
99
+ Every decision needs a reason. A decision is about one run as it stood: it does not pass a later attempt, or the same run if its record reads differently later. An agent does not record a decision the user has not made.
100
+
101
+ A queue whose units were edited after creation is refused everywhere except `queue decide --queue ID` with `cancel`, which is how it is closed.
102
+
103
+ ## The board
104
+
105
+ Agents working a queue, and the person, talk through the queue's board. A message is stored once, with its author filled in by the controller.
106
+
107
+ ```json
108
+ { "version": 1, "kind": "question", "to": "person", "text": "May the export include cancelled orders?" }
109
+ ```
110
+
111
+ | Kind | From | To | Closed by |
112
+ | --- | --- | --- | --- |
113
+ | `question` | Anyone | One unit, or `person` | An `answer` with its `replyTo` |
114
+ | `finding` | A reviewer or the person | One unit | An `answer` with `disposition` `fixed` or `declined` |
115
+ | `answer` | Whoever the item is for, the person, or its author | Whoever asked | It closes the item |
116
+ | `notice` | Anyone | A unit, `person` or `all` | It needs no answer |
117
+
118
+ Whoever asked may close their own item: a question with `disposition` `assumed` and what they assumed, or either kind with `withdrawn`. A question closed with `assumed` still takes one answer, from whoever it was for or from the person: people often answer after an agent has gone on. That answer reaches the asker at its next command or, once the asker is done, the units that build on it. It holds nothing, and is shown beside the assumption in `queue board` and in `queue next`. The asker cannot give it for someone else.
119
+
120
+ | Command | What it does |
121
+ | --- | --- |
122
+ | `cyc queue post [--queue ID] [--run RUN \| --seat SEAT] --file MESSAGE.json` | Posts for a run's unit, for a reviewer, or with neither for the person. |
123
+ | `cyc queue board [--queue ID] [--unit ID] [--open]` | Reads the messages; `--open` lists unanswered items. |
124
+ | `cyc queue wait [--queue ID] (--run RUN \| --seat SEAT) [--wait-ms N]` | Returns when a message arrives, or after N ms (at most 60000). |
125
+
126
+ A message reaches an agent at its next controller command. The result of a `run` command for a bound run starts with a `board` entry when something is new for its unit: messages for it or for `all`, and answers to what it posted (the newest 20, with a count of earlier ones). They count as shown once the run's own conversation has run such a command; `run status` and `run recover` do not count. A unit that starts later is shown what was left for it.
127
+
128
+ `queue status` and `queue next` show how many items are open, the ones that wait for the person, and the latest said to the person. `queue next` also lists `assumed`: what the units this one depends on went on with.
129
+
130
+ 1. A unit cannot complete while a question or finding addressed to it is open. `run finish` returns `needs-answer` and names each one before it runs any check.
131
+ 2. A unit cannot complete while a question of its own is open. It waits, or closes the question with `assumed`.
132
+ 3. An item for a unit that is done, skipped or cancelled is the person's, and the post says so.
133
+ 4. An agent does not post as the person. A post with no `--run` and no `--seat` is the person's. From a conversation that builds or reviews on the queue it is accepted only to relay the person's answer to a question that waits for them, and is recorded as relayed.
134
+
135
+ ### The review seat
136
+
137
+ A second conversation can review a unit while it is built. It starts no run and changes no file.
138
+
139
+ ```text
140
+ reviewer: queue next --seat review --session ID → the unit, its criteria, the changed files, the sourceHash
141
+ reviewer: queue post --seat SEAT (kind finding) → the builder sees it at its next command
142
+ builder: queue post --run RUN (kind answer, disposition fixed or declined)
143
+ builder: queue post --run RUN (kind notice, topic ready-for-review)
144
+ reviewer: queue post --seat SEAT (kind notice, topic review-done, sourceHash)
145
+ builder: run review-record --run RUN --from-board → one peer receipt, built from the board
146
+ ```
147
+
148
+ A seat belongs to the conversation that took it, and the conversation that builds the unit cannot take it. A conversation is the session its host reports; `--session` names it only when the host reports none. `--wait-ms N` lets a reviewer that arrives early wait for a unit to start.
149
+
150
+ While the seat is held, the unit cannot complete until the reviewer posts `review-done`. The seat also clears on `cyc queue release --seat SEAT`, after 30 minutes with no post, read or wait from the reviewer and no new `ready-for-review`, or when the run ends.
151
+
152
+ `review-done` carries the `sourceHash` the reviewer read, which every reviewer command returns, and is refused when the source is no longer that. `review-record --from-board` is refused when a finding has no answer, when the source changed after the sign-off, and when the builder has since asked for another look. Settle the context records first, then ask for review.
153
+
154
+ ## The hub
155
+
156
+ The hub is a page where a person watches a queue being worked. Agents talk through commands and files; the hub is where that becomes visible.
157
+
158
+ ```text
159
+ cyc hub → http://127.0.0.1:4780/ → open it in a browser and leave it open
160
+ ```
161
+
162
+ | On the page | What it shows |
163
+ | --- | --- |
164
+ | The line | Each unit in order: done, in progress and what its run is doing, next up, waiting, or halted and why |
165
+ | Conversation | Every board message as it is posted: who said it, to whom, and how it was answered |
166
+ | Waiting on you | What an agent asked you, or found for you to settle, and has no answer yet. A question you asked yourself stays in the conversation, marked open |
167
+ | Activity | What each run did, in plain words: started, finished building, ran the checks, completed |
168
+
169
+ The hub is read-only and local. It is served from this machine to this machine, answers only `GET`, and refuses a request that reaches it under any other name. It writes no file and moves no read mark, so watching never changes what an agent is shown. It reads the same records the controller writes, about every second and a half, so what it shows is at most a moment behind them. A page that is already current is told so and redraws nothing.
170
+
171
+ `cyc hub` prints its address and keeps running until it is stopped. Without `--port` it takes the first free port from 4780 to 4799; a port that is asked for and already answers on this machine is an error. It shows the open queue. With several open it shows the one being worked, then a halted one; with none open, the last one created. The queue list on the page, or `?queue=ID` in the address, picks another.
172
+
173
+ To answer what waits on you, tell your agent what you decided; it posts your answer. Answering from the page is not built yet.
174
+
175
+ ## Limits
176
+
177
+ - The queue orders runs; it does not start them. Unattended running, parallel units, commits, merges and deploys are not part of it.
178
+ - A done unit means its run completed, not that the product is certified.
179
+ - Only runs that carry the `queue` field are bound by the rules.
180
+ - One unit at a time holds within a queue. Two open queues in one checkout can halt each other's runs.
181
+ - A retry starts from the files the halted attempt left, including any outside the unit's paths; they are listed, not reverted.
182
+ - Queues are local: `.cyc/queues` ignores itself in Git and is never project source.
183
+ - A message cannot interrupt an agent: it is handed over at the next controller command or wait.
184
+ - The hub shows what is recorded. Work an agent is doing between two controller commands appears when the next command records it.
185
+ - The board is a local file that records what the controller was told. A run is spoken for by the session it recorded; one that recorded none can be posted for by anyone who has its ID. The relay rule knows a builder or reviewer only while its run is open or its seat held, and only by that session.
186
+ - A reviewer works in the builder's folder and is trusted to change nothing.
187
+ - A queue belongs to one checkout, and its files are editable local records, not attestation. A lost run record halts its unit instead of freeing it; a queue file and its runs edited together are not detected.
@@ -13,7 +13,7 @@ Write the smallest coherent slice. Features/bugs need meaningful red/green check
13
13
 
14
14
  Trace state, storage, interfaces and consumers. Use focused feedback then broad checks. Review diffs; run git diff --check, preserve encoding and log actual failed fixes.
15
15
 
16
- New composed frontend work must follow [frontend gates](../cyc-design/frontend-design/SKILL.md) before expansion; narrow repairs preserve existing identity.
16
+ New composed frontend work must follow [frontend gates](../cyc-design/frontend-design/SKILL.md) before expansion. On a new build or handoff read the study decision in the project’s `design/decisions.md` (or its recorded run-local path). Build the named material and its next state as one slice; check that slice before repeating it. Narrow repairs preserve existing identity.
17
17
 
18
18
  Read/acknowledge current [unified task context](../../docs/task-context.md) before dependent work. Workers are bounded/read-only; reconcile evidence, disagreements and failed approaches. Worker success does not complete the parent.
19
19