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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/README.md +3 -2
- package/bin/cyc.mjs +72 -20
- package/docs/README.md +2 -0
- package/docs/context.md +18 -10
- package/docs/project-tools.md +2 -12
- package/docs/runtime.md +5 -1
- package/docs/work-assessments.md +4 -4
- package/docs/work-queue.md +187 -0
- package/methods/cyc-build/SKILL.md +1 -1
- package/methods/cyc-context/SKILL.md +28 -20
- package/methods/cyc-context/references/evidence.md +1 -1
- package/methods/cyc-context/references/templates.md +30 -18
- package/methods/cyc-design/frontend-design/SKILL.md +132 -21
- package/methods/cyc-design/frontend-design/references/color.md +43 -56
- package/methods/cyc-design/frontend-design/references/craft-rules.md +17 -14
- package/methods/cyc-design/frontend-design/references/decision-sheet.md +95 -93
- package/methods/cyc-design/frontend-design/references/experience-review.md +15 -6
- package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
- package/methods/cyc-design/frontend-design/references/generic-tells.md +83 -32
- package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
- package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
- package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
- package/methods/cyc-design/frontend-design/references/typography.md +59 -44
- package/methods/cyc-design/frontend-design/references/ux-foundations.md +2 -1
- package/methods/cyc-design/frontend-design/references/visual-material.md +43 -8
- package/methods/cyc-design/frontend-design/scripts/contrast.mjs +39 -0
- package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
- package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
- package/methods/cyc-verify/SKILL.md +1 -1
- package/package.json +6 -1
- package/plugin.json +1 -1
- package/scripts/catalog.mjs +5 -3
- package/scripts/context-review.mjs +364 -261
- package/scripts/hub-page.mjs +275 -0
- package/scripts/hub.mjs +139 -0
- package/scripts/project-tools.mjs +14 -6
- package/scripts/queue-board.mjs +287 -0
- package/scripts/queue.mjs +283 -0
- package/scripts/run-gate.mjs +8 -5
- package/scripts/runtime.mjs +270 -19
- package/scripts/source-snapshot.mjs +20 -2
- package/scripts/work-review.mjs +4 -3
- package/skills/cyc/SKILL.md +12 -4
- package/skills/cyc/references/playbooks/experience.md +2 -0
- package/skills/cyc/references/playbooks/plan.md +2 -0
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
|
|
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
|
|
34
|
-
if ((options.write || options.all || options.
|
|
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
|
-
|
|
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
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
cyc context
|
|
69
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
13
|
+
## Normal workflow
|
|
10
14
|
|
|
11
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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.
|
package/docs/project-tools.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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;
|
|
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
|
package/docs/work-assessments.md
CHANGED
|
@@ -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
|
|
98
|
-
3. Supply
|
|
99
|
-
4. Verify final files, review the
|
|
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
|
|
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.
|