cyc-stack 0.9.1 → 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 (48) 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/README.md +3 -2
  5. package/bin/cyc.mjs +72 -20
  6. package/docs/README.md +2 -0
  7. package/docs/context.md +18 -10
  8. package/docs/project-tools.md +2 -12
  9. package/docs/runtime.md +5 -1
  10. package/docs/work-assessments.md +4 -4
  11. package/docs/work-queue.md +187 -0
  12. package/methods/cyc-build/SKILL.md +1 -1
  13. package/methods/cyc-context/SKILL.md +28 -20
  14. package/methods/cyc-context/references/evidence.md +1 -1
  15. package/methods/cyc-context/references/templates.md +30 -18
  16. package/methods/cyc-design/frontend-design/SKILL.md +132 -21
  17. package/methods/cyc-design/frontend-design/references/color.md +43 -56
  18. package/methods/cyc-design/frontend-design/references/craft-rules.md +17 -14
  19. package/methods/cyc-design/frontend-design/references/decision-sheet.md +95 -93
  20. package/methods/cyc-design/frontend-design/references/experience-review.md +15 -6
  21. package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
  22. package/methods/cyc-design/frontend-design/references/generic-tells.md +83 -32
  23. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
  24. package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
  25. package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
  26. package/methods/cyc-design/frontend-design/references/typography.md +59 -44
  27. package/methods/cyc-design/frontend-design/references/ux-foundations.md +2 -1
  28. package/methods/cyc-design/frontend-design/references/visual-material.md +43 -8
  29. package/methods/cyc-design/frontend-design/scripts/contrast.mjs +39 -0
  30. package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
  31. package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
  32. package/methods/cyc-verify/SKILL.md +1 -1
  33. package/package.json +6 -1
  34. package/plugin.json +1 -1
  35. package/scripts/catalog.mjs +5 -3
  36. package/scripts/context-review.mjs +364 -261
  37. package/scripts/hub-page.mjs +275 -0
  38. package/scripts/hub.mjs +139 -0
  39. package/scripts/project-tools.mjs +14 -6
  40. package/scripts/queue-board.mjs +287 -0
  41. package/scripts/queue.mjs +283 -0
  42. package/scripts/run-gate.mjs +8 -5
  43. package/scripts/runtime.mjs +270 -19
  44. package/scripts/source-snapshot.mjs +20 -2
  45. package/scripts/work-review.mjs +4 -3
  46. package/skills/cyc/SKILL.md +12 -4
  47. package/skills/cyc/references/playbooks/experience.md +2 -0
  48. package/skills/cyc/references/playbooks/plan.md +2 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.9.1",
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.9.1",
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.9.1",
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/README.md CHANGED
@@ -168,10 +168,11 @@ Explain the evidence behind the findings. No edits.
168
168
  ```
169
169
 
170
170
  ```text
171
- /cyc Improve this site's complete signup journey. Establish a visual direction,
172
- build a usable mobile layout, and check keyboard, validation and recovery states.
171
+ /cyc Make my homepage look better.
173
172
  ```
174
173
 
174
+ Run that in the project you want to improve. CYC uses the page, content and brand assets to choose type, colors, imagery and layout. Before it extends a design, it checks that the main action is readable, reachable by keyboard and usable on a narrow screen. You see the recommended desktop and phone design, what was tested and any remaining limits. Add preferences in your own words, such as “Keep our logo” or “Show the work we make.”
175
+
175
176
  ## Updating
176
177
 
177
178
  From the target project, preview with `npx cyc-stack@latest init --dry-run`, then update with `npx cyc-stack@latest init`. Reload the host and repeat setup validation. Project configuration and run records are preserved. Modified managed files cause a conflict with no writes; merge deliberately before retrying. [Updates, version pinning and conflicts](docs/installation.md#updating-conflicts-and-removal).
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'].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)) {
@@ -30,8 +30,12 @@ try {
30
30
  if ((options.host !== undefined || options.token !== undefined) && command !== 'onboard') throw new Error('--host and --token are only supported by onboard.');
31
31
  if (options.kind !== undefined && command !== 'investigate' && (command !== 'recipe' || action !== 'list')) throw new Error('--kind is only supported by recipe list and investigate.');
32
32
  if (options.since !== undefined && command !== 'readiness' && command !== 'context') throw new Error('--since is only supported by readiness and context review.');
33
- if (options['update-run'] !== undefined && (command !== 'context' || action !== 'review' || !options.write)) throw new Error('--update-run is only supported by context review --write.');
34
- if ((options.write || options.all || options.new !== undefined || options.doc !== undefined) && command !== 'context') throw new Error('--write, --all, --new and --doc are only supported by context.');
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
+ 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) {
@@ -54,19 +58,19 @@ Discover:
54
58
  cyc recipe run --recipe ID [--run ID]
55
59
  (execute an applicable authorized recipe; retain diagnostic evidence)
56
60
 
57
- Component context docs (docs/context/):
61
+ Project context (docs/context/): docs say what is true now, change records what each run did.
58
62
  cyc context task --run ID
59
63
  cyc context ack --run ID --file ACK.json
60
64
  cyc delegate swarm|decide|assign|execute|record|cancel|cancel-swarm|reconcile --run ID --file INPUT.json
61
65
  cyc context prepare --run ID [--file CONTEXT.json]
62
- cyc context review [--run ID | --since YYYY-MM-DD | --all] [--write --update-run UPDATE_ID] [--new NAME]
63
- (map completed runs' changed files to component docs and propose the doc entry from each run's
64
- record: what changed, what was learned, the decisive check, files with hashes, date and run ID.
65
- Read-only without --write; --write appends the entries and refreshes INDEX.md)
66
- cyc context lint [--doc PATH]
67
- (check the doc layout rules and the index rows, including freshness against Git)
68
- cyc context measure --path PATH... [--run ID]
69
- (characters and estimated tokens of INDEX.md plus the matched docs, against every doc and the run records)
66
+ cyc context lint [--doc PATH] (docs, index, change records, freshness against Git)
67
+ cyc context index [--write] (rebuild INDEX.md from the docs; repairs conflict markers)
68
+ cyc context history [DOC] (a component's change records, newest first)
69
+ cyc context review [--run ID | --since YYYY-MM-DD | --all] [--write]
70
+ (completed runs without a change record; --write publishes them)
71
+ cyc context rollup [--before YYYY-MM] [--write] (one digest per earlier month)
72
+ cyc context migrate [--write] (move History out of earlier-layout docs)
73
+ cyc context measure --path PATH... [--run ID] (reading cost of INDEX.md plus matched docs)
70
74
 
71
75
  Execute through your existing AI host:
72
76
  cyc run start --goal TEXT --playbook feature [--criterion "done when..."]... [--scope PATH] [--session ID] [--scout FILE --plan TEXT]
@@ -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.
@@ -155,14 +173,18 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
155
173
  result = taskContext(root, options.run, action, action === 'ack' ? readJSON(options.file) : {});
156
174
  } else if (command === 'context') {
157
175
  const context = await import('../scripts/context-review.mjs');
158
- if (action === 'review') result = context.reviewContext(root, { run: options.run, since: options.since, all: !!options.all, write: !!options.write, newDoc: options.new, updateRun: options['update-run'] });
176
+ if (action === 'review') result = context.reviewContext(root, { run: options.run, since: options.since, all: !!options.all, write: !!options.write });
159
177
  else if (action === 'prepare') {
160
178
  if (!options.run) throw new Error('context prepare needs the exact --run ID.');
161
179
  result = prepareRunContext(root, options.run, options.file ? inputObject(options.file, ['records', 'summary', 'reason']) : {});
162
180
  }
163
181
  else if (action === 'lint') result = context.lintContext(root, { doc: options.doc });
164
182
  else if (action === 'measure') result = context.measureContext(root, { paths: options.path ?? [], run: options.run });
165
- else throw new Error('Use context prepare, context review, context lint, or context measure.');
183
+ else if (action === 'index') result = context.indexContext(root, { write: !!options.write });
184
+ else if (action === 'history') result = context.historyContext(root, { doc: options.doc ?? positionals[2] });
185
+ else if (action === 'rollup') result = context.rollupContext(root, { before: options.before, write: !!options.write });
186
+ else if (action === 'migrate') result = context.migrateContext(root, { write: !!options.write });
187
+ else throw new Error('Use context prepare, lint, index, history, review, rollup, migrate or measure.');
166
188
  } else if (command === 'onboard') {
167
189
  result = (await import('../scripts/onboarding.mjs')).onboardProject(root, { verify: !!options.verify, host: options.host, session: options.session, token: options.token });
168
190
  } else if (['init', 'install', 'uninstall', 'doctor', 'activate'].includes(command)) {
@@ -189,6 +211,25 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
189
211
  result = (await import('../scripts/run-gate.mjs')).sessionReadiness({ root, session: options.session, since: options.since });
190
212
  } else if (command === 'packet') {
191
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 } : {}) });
192
233
  } else if (command === 'playbooks') result = catalog;
193
234
  else if (command === 'route') {
194
235
  if (!options.goal) throw new Error('--goal is required.');
@@ -199,7 +240,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
199
240
  let input;
200
241
  if (options.file) {
201
242
  fileOnly(options, ['file', 'project', 'verbose']);
202
- 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']);
203
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.`);
204
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).');
205
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.');
@@ -259,6 +300,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
259
300
  if (!options.file) throw new Error('review-capture needs --file JSON with reviewer and optional scope.');
260
301
  result = captureReview(root, options.run, inputObject(options.file, ['reviewer', 'scope', 'contextPaths', 'contextEvidence'])); break;
261
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; }
262
304
  if (!options.file) throw new Error('review-record needs --file JSON with reviewId, evidence, identity and findings.');
263
305
  result = recordReview(root, options.run, inputObject(options.file, ['reviewId', 'evidence', 'identity', 'findings'])); break;
264
306
  case 'pause': case 'resume': case 'stop': result = controlRun(root, options.run, action); break;
@@ -266,6 +308,14 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
266
308
  }
267
309
  } else throw new Error(`Unknown command ${command}. Use cyc help.`);
268
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
+ }
269
319
  console.log(humanInstallOutput(command) ? formatInstall(result) : JSON.stringify(result, null, 2));
270
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;
271
321
  } catch (error) {
@@ -346,12 +396,14 @@ function compact(action, result, root, options) {
346
396
  if (!result || typeof result !== 'object' || ['status', 'recover'].includes(action)) return result;
347
397
  const id = result.runId ?? result.id ?? options.run;
348
398
  const guidance = value => completionGuidance(value, { executionMode: (value.result ?? value).packet?.written === false ? readRun(root, id).execution?.mode : undefined });
349
- 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) });
350
402
  if (['review-capture', 'review-record'].includes(action)) { const { files, ...receipt } = result; return receipt; }
351
403
  if (action === 'prove-red') return result;
352
404
  if (action === 'finish') {
353
405
  const display = result.failedAt === 'verify' && 'verificationStatus' in result ? { ...compact('verify', result, root, options), finished: false, failedAt: 'verify' } : result;
354
- return { ...display, guidance: guidance(display) };
406
+ return lined({ ...display, guidance: guidance(display) });
355
407
  }
356
408
  if (action === 'verify') {
357
409
  const recovery = result.passed ? null : recoverRun(root, id);
@@ -372,5 +424,5 @@ function compact(action, result, root, options) {
372
424
  // Agents often read only the first lines (| head -40), so what they act on comes first and the
373
425
  // long fill-in template last.
374
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]]));
375
- 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 }) });
376
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/context.md CHANGED
@@ -1,30 +1,38 @@
1
1
  # Project context
2
2
 
3
- Every new feature leaves a focused canonical record and index row in the target project. Meaningful changes update that feature and affected shared-component knowledge. The next agent should find capability boundaries, contracts, choices, failures, checks and limits without the original chat. A handoff, recipe, setup guide or ignored receipt alone is insufficient.
3
+ Project context is what the next agent or teammate needs without the original chat. It lives in the target project under docs/context/, in three parts:
4
4
 
5
- Read docs/context/INDEX.md, then matched records and relevant error history. Revalidate consequential claims against current source/dependencies. A configured context.directory can reuse a genuine equivalent project convention; never substitute the installed engine's development index.
5
+ | Part | Answers | Written by |
6
+ | --- | --- | --- |
7
+ | Index, INDEX.md | Which doc covers the files I am about to change? | Rebuilt from the docs |
8
+ | Component doc | What is true now: boundaries, contracts, choices, checks, limits, lessons | The run that changes the component, before its checks |
9
+ | Change record, changes/ | What did a run change, and how did its checks end? | The controller, after the checks pass |
6
10
 
7
- ## Normal workflow
11
+ A doc changes only when the rule a reader should follow changes. History is one small record per completed run that planned context, so docs stay short and two people in one component conflict only where they changed the same line. A routine run publishes none; `context review --write` can publish one for a completed run that lacks it.
8
12
 
9
- Scout/Start plans canonical records and representative entrypoints before scope freezes. Finish prepares/validates authored knowledge, History/source evidence and index before final checks. Missing/stale context returns needs-context with remaining input; fill learning.context or use context prepare --run ID for earlier feedback. Explicit restrictions remain pending without unauthorized writes. See the [Context method](../methods/cyc-context/SKILL.md) for schemas, fixed layout and recovery.
13
+ ## Normal workflow
10
14
 
11
- Context-only upkeep can bind unchanged implementation files from its focused owner's Covers. Missing anchors remain pending; self/index hashes and unrelated source cannot substitute. Completion guidance retains the exact remaining input and owned command.
15
+ Read docs/context/INDEX.md, then matched docs and relevant error history; revalidate consequential claims against current source. Start plans each feature's doc and entrypoints before scope freezes. Finish validates the authored Current view and the index before final checks; missing or stale context returns needs-context with the remaining input (fill learning.context, or use context prepare --run ID earlier). On completion the controller publishes the change record with the results it observed. Restrictions remain pending without unauthorized writes. See the [Context method](../methods/cyc-context/SKILL.md) for schemas, layout and recovery.
12
16
 
13
17
  ```text
14
18
  node bin/cyc.mjs investigate --path src/orders
19
+ node bin/cyc.mjs context history orders
15
20
  node bin/cyc.mjs context lint
16
- node bin/cyc.mjs context review --run SOURCE_ID
21
+ node bin/cyc.mjs context index --write
22
+ node bin/cyc.mjs context rollup --write
23
+ node bin/cyc.mjs context migrate --write
24
+ node bin/cyc.mjs context review [--run ID] [--write]
17
25
  node bin/cyc.mjs context measure --path src/orders
18
26
  ```
19
27
 
20
- Installed projects use .cyc/engine/bin/cyc.mjs. Read-only inspection executes no recipe. Historical catch-up writes need a new implementation update with a required canonical plan and executable final checks (--write --update-run ID). Preserve old receipts, record the repair under its actual run/date and verify final files. A reply packet cannot restore evidence after context changes.
28
+ Installed projects use .cyc/engine/bin/cyc.mjs. Commit a change record with the change it describes. rollup folds earlier months into one digest each, so the folder stays bounded; run it on the default branch. migrate converts docs that still hold a History section. review publishes the record of a completed run that lacks one and never edits a doc. A configured context.directory can reuse an equivalent convention; never substitute the engine's development index.
21
29
 
22
30
  ## Evidence limits
23
31
 
24
- Lint validates structure, mapping and supported freshness, not semantic truth or adoption. Optional manifests bind selected bytes, not complete dependencies. Context measure counts unique selected local files, estimates tokens as Unicode characters/4 and cannot see chat usage, billing or savings. Run records are not transcripts and may exist only in ignored local storage.
32
+ Lint validates structure, mapping and supported freshness, not semantic truth or adoption. A change record states what one run observed when it completed; it is not verified source and does not show the code is correct now. measure counts selected local files and estimates tokens as characters/4; it cannot see chat usage, billing or savings.
25
33
 
26
- To evaluate actual reuse, give a fresh chat/teammate a related bounded task without the original conversation; observe discovery, reading, revalidation and successful use with real checks. Record missed/stale guidance. Parser/fixture passes alone do not establish future model quality or measured workflow savings.
34
+ To evaluate actual reuse, give a fresh chat or teammate a related bounded task without the original conversation; observe discovery, reading, revalidation and successful use with real checks. Parser or fixture passes alone do not establish future model quality or measured savings.
27
35
 
28
36
  ## Consolidate delegated findings
29
37
 
30
- [Task context](task-context.md) reconciles read-only worker evidence into one parent document and feeds existing canonical feature owners before checks. It creates no permanent worker context documents and waives no retention, proof or freshness requirement.
38
+ [Task context](task-context.md) reconciles read-only worker evidence into one parent document and feeds existing feature owners before checks. It creates no permanent worker context documents and waives no retention, proof or freshness requirement.
@@ -28,21 +28,11 @@ Each manifest is checked once per lookup. Output reports the checked-file count
28
28
 
29
29
  The context index uses a Markdown table with `Covers` and `Doc` or `Record` columns, plus optional `Evidence`. Paths are comma-separated; links resolve relative to the index. Supported coverage patterns are literal paths/directories, `*`, `**`, and `?`; `all` means all paths in an index row. Patterns use forward slashes and match case exactly. Brackets in actual framework paths such as src/app/events/[eventId]/route.ts are literal, not character classes; traversal/backslashes/unsupported braces remain rejected. Catch-all reference matching cannot satisfy required focused feature retention. Escaped table pipes are supported; malformed rows are reported. Missing/deleted record links remain visible. Linked/out-of-project paths are not followed. Existing projects without an index or registry fall back to ordinary source investigation and manual check discovery.
30
30
 
31
- Each context match now explains its selection: match.kind is path or advisory goal; match.paths lists requested paths and matching Covers patterns, while match.words identifies goal terms. The additive recordEvidence array leaves the existing records shape intact and checks only the newest canonical History's selected SHA-256 bindings, once per lookup and at most the lookup limit. It reports matches, drifted, missing, invalid or unverified, checked/total counts and truncation. Reference prose, commit-only bindings and absent evidence stay unverified. Matching selected bytes never establishes complete dependency coverage or semantic truth. Inspect current code and user requirements; conflicting notes cannot override them. Discovery still runs no project commands.
31
+ Each context match explains its selection: match.kind is path or advisory goal; match.paths lists requested paths and matching Covers patterns; match.words lists goal terms. recordEvidence compares each covered file with the SHA-256 that the newest change record naming the doc gave it (earlier layout: its newest History entry), queried paths first, at most the lookup limit. It reports matches, drifted, missing, invalid or unverified, counts and truncation; reference prose and commit-only bindings stay unverified. Matching bytes never establish dependency coverage or semantic truth; conflicting notes cannot override current code and requirements. Discovery runs no project commands.
32
32
 
33
33
  ## Component context docs
34
34
 
35
- The target index maps focused canonical feature/component records, with Covers, resolving Doc link, Last AI change and Lessons. Read matched records, not all historical prose. Configure context.directory before start only to reuse a project-owned equivalent. Default is docs/context/; engine/runtime knowledge is never target context.
36
-
37
- ```text
38
- node .cyc/engine/bin/cyc.mjs context prepare --run ID [--file CONTEXT.json]
39
- node .cyc/engine/bin/cyc.mjs context review --run SOURCE_ID
40
- node .cyc/engine/bin/cyc.mjs context review --run SOURCE_ID --write --update-run UPDATE_ID
41
- node .cyc/engine/bin/cyc.mjs context lint [--doc docs/context/orders.md]
42
- node .cyc/engine/bin/cyc.mjs context measure --path src/orders [--run ID]
43
- ```
44
-
45
- Normal finish performs preparation/retention validation before proof/final checks. Plan canonical docs/index before Build; fill learning.context or author the records. Missing knowledge returns needs-context. Read-only review proposes catch-up from actual completed evidence, naming absent fields rather than inventing observations. Writing requires a new implementation update with a required canonical plan and final executable checks; optional --new NAME scaffolds unmapped records with failing placeholders. It preserves Current view/completed receipts and inserts chronological actual History, lessons and index metadata. Then author the update's own context and verify final files. A packet cannot bypass freshness. See [Context](../methods/cyc-context/SKILL.md) for the fixed layout, provenance and restrictions.
35
+ [Project context](context.md) describes the index, component docs and change records with their commands; the [Context method](../methods/cyc-context/SKILL.md) has the layout and restrictions. Read matched docs, not all history. The default folder is docs/context/; configure context.directory before start only to reuse a project-owned equivalent, and never use engine/runtime knowledge as target context.
46
36
 
47
37
  Manual context lint audits all docs/index and supported Git freshness; automatic retention limits content reads to planned docs plus index consistency. Dirty means uncommitted covered changes, stale-against-git means later covered commits. Context measure counts selected linked local files once, estimates tokens as characters/4 and cannot see chat usage or establish savings/reuse success. See [context guide](context.md).
48
38
 
package/docs/runtime.md CHANGED
@@ -20,11 +20,13 @@ 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
26
28
 
27
- Plan focused feature/shared records and index before Build. Author learning.context or planned docs through context prepare/finish before checks. Missing/restricted/stale knowledge stays needs-context; generated History/support files do not substitute. Completed catch-up needs a new scoped update/checks. [Context](context.md) defines retention.
29
+ Plan focused feature/shared records and index before Build. Author learning.context or planned docs through context prepare/finish before checks. Missing/restricted/stale knowledge stays needs-context; support files do not substitute. Completion publishes the run's change record, which is history and not verified source. [Context](context.md) defines retention.
28
30
 
29
31
  Optional [task context/delegation](task-context.md) provides one parent document and read-only assignments. Auto swarm plans, decides, fans out concurrently and reviews/merges via parent transactions; solo and unresolved conflicts remain explicit. Manual execute/reconcile stays available. Handoffs/checks bind revision/hash separately from source. Token usage is reporting only.
30
32
 
@@ -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
@@ -94,9 +94,9 @@ Optional proofCommands freezes focused execution at start; --tests selects swapp
94
94
  ## Learning lifecycle and final file order
95
95
 
96
96
  1. Record failed attempts promptly in the selected ledger, even abandoned work. projectLedgerPath selects lookup; ledgerPath selects recording, with run-local fallback when shared writes are outside scope. Disclose pending shared promotion; do not infer expanded permission.
97
- 2. Author each planned canonical feature/shared record before final verification. Include capability/boundaries, ownership/data flow/contracts, choices/reasons, failures, decisive check commands and known limits. Keep hypotheses/proposals labeled; tests do not establish adoption. INDEX.md, ledgers, recipes, generic handoffs and ignored logs support context but cannot replace it or inflate contextDocs.
98
- 3. Supply actual learning.context [{id,currentView}] in finish, or author records and use context prepare --run ID. Finish creates missing target scaffolds, upserts current History/source evidence and relevant index metadata, then returns needs-context until valid. Generated History alone cannot satisfy authorship. No future check outcomes or self/index hashes are written; final command receipts stay outside source with stable run references.
99
- 4. Verify final files, review the actual candidate, then complete/deliver. A covered context/ledger edit invalidates dependent evidence like code. Completed-run catch-up requires a required canonical plan in a new implementation update, its own repair History and fresh executable checks; a packet cannot reverify changed source. Late needs cannot silently broaden frozen scope.
97
+ 2. Author each planned feature/shared doc before final verification: capability and boundaries, contracts, choices with reasons, failures, decisive checks and limits. Keep proposals labeled; tests do not establish adoption. The index, ledgers, recipes, handoffs and ignored logs support context but cannot replace it.
98
+ 3. Supply learning.context [{id,currentView,changed?,lesson?}] in finish, or author docs and use context prepare --run ID. Finish scaffolds missing docs and index rows, binds each authored view to selected source and returns needs-context until valid; a scaffold is not authorship.
99
+ 4. Verify final files, review the candidate, then complete. A covered context/ledger edit invalidates dependent evidence like code; a packet cannot reverify it. Completion publishes the change record (history, not verified source) with the check outcome. Late needs cannot broaden frozen scope.
100
100
 
101
101
  Example finish assessment fragment (use actual planned IDs, prose and paths):
102
102
 
@@ -106,7 +106,7 @@ Example finish assessment fragment (use actual planned IDs, prose and paths):
106
106
 
107
107
  Learning statuses: recorded, pending-acceptance, none; error-history: recorded, none. Both need reasons. Non-none artifacts must exist and are fingerprinted/rechecked. Pending proposals belong under this run and are not a substitute for required feature context; retained facts can coexist with a pending proposal. None uses empty artifacts and is proportional only when no feature retention is required. Explicit documentation restrictions remain pending/incomplete without unauthorized writes. Bug fixes/recorded failures require the selected ledger. Routine dispositions and semantic completeness remain agent judgments, not machine truth.
108
108
 
109
- Current runs enforce canonical layout/index/mappings, consistent current History and actual source evidence, with authored Current view bound to selected source. Automatic validation reads relevant planned records plus index consistency; arbitrary explanatory truth and unreported failures still need judgment. Old stored receipts are not retroactively upgraded. Optional byte manifests supplement History; preserve historical disclosures and label current evidence separately. Summarize local-only receipt conclusions and reproducible commands for source-only readers.
109
+ Current runs enforce doc layout, index mappings and source evidence, with the authored Current view bound to selected source. Validation reads planned docs plus index consistency; explanatory truth and unreported failures still need judgment. Old receipts are not upgraded. Optional byte manifests supplement change records. Summarize local-only receipt conclusions and reproducible commands for source-only readers.
110
110
 
111
111
  ## One review artifact, reused throughout delivery
112
112
 
@@ -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.