cyc-stack 0.7.1 → 0.9.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 (50) 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 +25 -254
  5. package/bin/cyc.mjs +61 -23
  6. package/docs/assets/cyc-method-library.svg +1 -39
  7. package/docs/assets/cyc-overview.svg +1 -44
  8. package/docs/assets/cyc-workflow-diagram.svg +1 -415
  9. package/docs/context.md +13 -23
  10. package/docs/cyc-workflow.md +31 -84
  11. package/docs/installation.md +66 -124
  12. package/docs/onboarding-recovery.md +31 -37
  13. package/docs/project-tools.md +16 -10
  14. package/docs/response-standard.md +16 -32
  15. package/docs/runtime.md +22 -224
  16. package/docs/skill-contract.md +13 -56
  17. package/docs/task-context.md +56 -0
  18. package/docs/validation.md +2 -0
  19. package/docs/work-assessments.md +25 -92
  20. package/methods/cyc-build/SKILL.md +8 -53
  21. package/methods/cyc-challenge/SKILL.md +4 -0
  22. package/methods/cyc-context/SKILL.md +20 -53
  23. package/methods/cyc-context/references/evidence.md +1 -1
  24. package/methods/cyc-context/references/templates.md +4 -11
  25. package/methods/cyc-deliver/SKILL.md +6 -42
  26. package/methods/cyc-remember/SKILL.md +1 -1
  27. package/methods/cyc-scout/SKILL.md +17 -51
  28. package/methods/cyc-setup/SKILL.md +7 -19
  29. package/methods/cyc-verify/SKILL.md +15 -66
  30. package/methods/cyc-verify/references/recipe.md +2 -0
  31. package/package.json +9 -1
  32. package/plugin.json +1 -1
  33. package/rules/cyc-delivery.mdc +33 -33
  34. package/scripts/browser-audit.mjs +53 -0
  35. package/scripts/catalog.mjs +9 -2
  36. package/scripts/codex-host.mjs +178 -0
  37. package/scripts/context-review.mjs +212 -29
  38. package/scripts/delegation.mjs +156 -0
  39. package/scripts/execution.mjs +51 -0
  40. package/scripts/onboarding.mjs +14 -1
  41. package/scripts/packet.mjs +21 -6
  42. package/scripts/project-tools.mjs +43 -20
  43. package/scripts/recovery.mjs +20 -1
  44. package/scripts/response-mode.mjs +8 -0
  45. package/scripts/run-worker.mjs +4 -0
  46. package/scripts/runtime.mjs +648 -68
  47. package/scripts/swarm.mjs +154 -0
  48. package/scripts/task-context.mjs +164 -0
  49. package/scripts/work-review.mjs +32 -10
  50. package/skills/cyc/SKILL.md +29 -70
package/bin/cyc.mjs CHANGED
@@ -1,9 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
  import { existsSync, readFileSync } from 'node:fs';
3
3
  import { dirname, resolve } from 'node:path';
4
+ import { resolveExecution, artifactFiles } from '../scripts/execution.mjs';
4
5
  import { isDeepStrictEqual } from 'node:util';
5
6
  import { catalog, routeTask } from '../scripts/catalog.mjs';
6
- import { acceptFailure, activeRun, callerSession, inputPath, completeRun, controlRun, finishRun, nextRun, projectFile, proveRun, quickHandoff, readRun, recordHandoff, recoverRun, retryRun, reviewRun, startRun, verifyRun, captureReview, recordReview } from '../scripts/runtime.mjs';
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';
7
9
 
8
10
  const args = process.argv.slice(2);
9
11
  const positionals = [];
@@ -14,7 +16,8 @@ try {
14
16
  if (!args[i].startsWith('--')) { positionals.push(args[i]); continue; }
15
17
  const name = args[i].slice(2);
16
18
  if (flags.has(name)) { options[name] = true; continue; }
17
- 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'].includes(name)) throw new Error(`Unknown option --${name}`);
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}`);
18
21
  const value = args[++i];
19
22
  if (!value || value.startsWith('--')) throw new Error(`--${name} needs a value.`);
20
23
  if (['scope', 'artifact', 'criterion', 'passed', 'unmet', 'tests', 'path'].includes(name)) {
@@ -27,6 +30,7 @@ try {
27
30
  if ((options.host !== undefined || options.token !== undefined) && command !== 'onboard') throw new Error('--host and --token are only supported by onboard.');
28
31
  if (options.kind !== undefined && command !== 'investigate' && (command !== 'recipe' || action !== 'list')) throw new Error('--kind is only supported by recipe list and investigate.');
29
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.');
30
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.');
31
35
  if (options.verify && command !== 'onboard') throw new Error('--verify is only supported by onboard. Use run verify for task verification.');
32
36
  if (options.verify && options['dry-run']) throw new Error('Do not combine --verify with --dry-run. Plain onboard performs read-only inspection.');
@@ -51,7 +55,11 @@ Discover:
51
55
  (execute an applicable authorized recipe; retain diagnostic evidence)
52
56
 
53
57
  Component context docs (docs/context/):
54
- cyc context review [--run ID | --since YYYY-MM-DD | --all] [--write] [--new NAME]
58
+ cyc context task --run ID
59
+ cyc context ack --run ID --file ACK.json
60
+ cyc delegate swarm|decide|assign|execute|record|cancel|cancel-swarm|reconcile --run ID --file INPUT.json
61
+ 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]
55
63
  (map completed runs' changed files to component docs and propose the doc entry from each run's
56
64
  record: what changed, what was learned, the decisive check, files with hashes, date and run ID.
57
65
  Read-only without --write; --write appends the entries and refreshes INDEX.md)
@@ -75,6 +83,9 @@ Execute through your existing AI host:
75
83
  (from build or verify: record build, prove new tests, verify, record verify and deliver, and complete;
76
84
  artifacts default to the files this run changed; run next gives the assessment template)
77
85
  cyc run finish --file FINISH.json (summary, assessment, criterionEvidence; optional runId and artifacts)
86
+ (versioned input uses canonical scenarioEvidence; needs-proof-review returns its bound continuation file)
87
+ cyc run wait --run ID --operation ID --wait-ms 30000 (bounded progress; finish/verify/prove-red also accept --wait-ms)
88
+ Start JSON: executionMode native-codex|native-claude|cursor|standalone, real conversationId, separate session label; optional frozen proofCommands.
78
89
  cyc run retry --run ID --stage build --reason "What changed in the approach"
79
90
  cyc run accept-failure --run ID --check CHECK_ID --reason "Why this pre-existing failure is unrelated"
80
91
  cyc run complete --run ID
@@ -102,7 +113,7 @@ All commands accept --project PATH. Criteria file: [{"id":"saved","description":
102
113
  Store handoff files under .cyc/runs/ID/ to avoid changing the source being verified.
103
114
  New implementation runs require Scout, Verify, and Deliver assessments; run next lists required fields.
104
115
  See docs/work-assessments.md for the compact JSON contract and knowledge lifecycle.
105
- The host agent reads and executes the returned skill; CYC does not launch paid model calls.
116
+ The host executes skills; opt-in delegate execute launches Codex model calls.
106
117
  Configure verification.commands in .cyc/config.json; without them, executable runs use the project's declared test command or are refused.
107
118
  Hook activation/trust must be checked in your host; doctor does not certify it.`);
108
119
  process.exit(0);
@@ -128,15 +139,30 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
128
139
  else if (action === 'run') {
129
140
  if (options['dry-run']) throw new Error('Use recipe list to inspect without execution; recipe run does not accept --dry-run.');
130
141
  if (!options.recipe) throw new Error('--recipe is required.');
131
- result = tools.runRecipe(root, options.recipe, { run: options.run });
132
- if (!options.verbose) result.results = result.results.map(({ id, command, args, passed, exitCode, error, errorCode, stdout, stderr }) => ({ id, command, args, passed, exitCode, error, errorCode, outputTail: `${stdout ?? ''}${stderr ?? ''}`.trim().split('\n').slice(-15).join('\n') }));
142
+ result = await tools.runRecipe(root, options.recipe, { run: options.run });
143
+ if (!options.verbose && result.results) result.results = result.results.map(({ id, command, args, passed, exitCode, error, errorCode, stdout, stderr }) => ({ id, command, args, passed, exitCode, error, errorCode, outputTail: `${stdout ?? ''}${stderr ?? ''}`.trim().split('\n').slice(-15).join('\n') }));
133
144
  } else throw new Error('Use recipe list or recipe run.');
145
+ } else if (command === 'delegate') {
146
+ if (!options.run || !options.file) throw new Error('delegate needs the exact --run ID and --file JSON.');
147
+ fileOnly(options, ['run','file','project','verbose']);
148
+ result = action === 'swarm' ? await (await import('../scripts/swarm.mjs')).executeSwarm(root,options.run,readJSON(options.file)) : action === 'execute'
149
+ ? await (await import('../scripts/codex-host.mjs')).executeCodex(root, options.run, readJSON(options.file))
150
+ : delegateRun(root, options.run, action, readJSON(options.file));
151
+ } else if (command === 'context' && ['task','ack'].includes(action)) {
152
+ if (!options.run) throw new Error('Task context needs the exact --run ID.');
153
+ fileOnly(options, action === 'ack' ? ['run','file','project','verbose'] : ['run','project','verbose']);
154
+ if (action === 'ack' && !options.file) throw new Error('context ack needs --file JSON.');
155
+ result = taskContext(root, options.run, action, action === 'ack' ? readJSON(options.file) : {});
134
156
  } else if (command === 'context') {
135
157
  const context = await import('../scripts/context-review.mjs');
136
- if (action === 'review') result = context.reviewContext(root, { run: options.run, since: options.since, all: !!options.all, write: !!options.write, newDoc: options.new });
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'] });
159
+ else if (action === 'prepare') {
160
+ if (!options.run) throw new Error('context prepare needs the exact --run ID.');
161
+ result = prepareRunContext(root, options.run, options.file ? inputObject(options.file, ['records', 'summary', 'reason']) : {});
162
+ }
137
163
  else if (action === 'lint') result = context.lintContext(root, { doc: options.doc });
138
164
  else if (action === 'measure') result = context.measureContext(root, { paths: options.path ?? [], run: options.run });
139
- else throw new Error('Use context review, context lint, or context measure.');
165
+ else throw new Error('Use context prepare, context review, context lint, or context measure.');
140
166
  } else if (command === 'onboard') {
141
167
  result = (await import('../scripts/onboarding.mjs')).onboardProject(root, { verify: !!options.verify, host: options.host, session: options.session, token: options.token });
142
168
  } else if (['init', 'install', 'uninstall', 'doctor', 'activate'].includes(command)) {
@@ -150,9 +176,10 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
150
176
  const { checkReply } = await import('../scripts/response-gate.mjs');
151
177
  const { allowsLongResponse } = await import('../scripts/response-mode.mjs');
152
178
  let expanded = !!options.expanded;
153
- if (options.session) {
179
+ const execution = options.mode ? resolveExecution(root, { executionMode: options.mode, conversationId: options.conversation, session: options.session }) : null;
180
+ if (options.session && execution?.mode !== 'standalone') {
154
181
  // The conversation's own setting decides the cap, as it does at Stop.
155
- const statePath = resolve(root, '.cyc/runtime', `${options.session}.state.json`);
182
+ const statePath = resolve(root, '.cyc/runtime', `${execution?.gateSession ?? options.session}.state.json`);
156
183
  if (!existsSync(statePath)) throw new Error(`No hook state for session ${options.session} at ${statePath}.`);
157
184
  expanded = allowsLongResponse(JSON.parse(readFileSync(statePath, 'utf8').replace(/^/, '')));
158
185
  }
@@ -161,24 +188,25 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
161
188
  } else if (command === 'readiness') {
162
189
  result = (await import('../scripts/run-gate.mjs')).sessionReadiness({ root, session: options.session, since: options.since });
163
190
  } else if (command === 'packet') {
164
- result = (await import('../scripts/packet.mjs')).writePacket(root, { session: options.session, responseFile: options.response, status: options.status, blocker: options.blocker, advisory: options.advisory, passed: options.passed ?? [], unmet: options.unmet ?? [], artifacts: options.artifact ?? [], reviewed: !!options.reviewed });
191
+ 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 });
165
192
  } else if (command === 'playbooks') result = catalog;
166
193
  else if (command === 'route') {
167
194
  if (!options.goal) throw new Error('--goal is required.');
168
- result = routeTask(options.goal);
195
+ result = routeTask(options.goal,{paths:options.path??[]});
169
196
  } else if (command === 'run') {
170
197
  switch (action) {
171
198
  case 'start': {
172
199
  let input;
173
200
  if (options.file) {
174
201
  fileOnly(options, ['file', 'project', 'verbose']);
175
- input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy']);
202
+ input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy', 'executionMode', 'conversationId', 'proofCommands', 'contextRetention', 'taskContext', 'delegation']);
176
203
  for (const key of ['goal', 'playbook', 'session', 'plan']) if (input[key] !== undefined && typeof input[key] !== 'string') throw new Error(`${key} must be a string.`);
177
204
  if (input.scout !== undefined && !object(input.scout)) throw new Error('scout must be the Scout assessment object (run start without it returns the template).');
178
205
  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.');
179
206
  if (input.allowedPaths !== undefined && (!Array.isArray(input.allowedPaths) || input.allowedPaths.some(p => typeof p !== 'string'))) throw new Error('allowedPaths must be an array of paths.');
180
207
  } else input = { goal: options.goal, playbook: options.playbook, criteria: options.criteria ? readJSON(options.criteria) : options.criterion ? options.criterion.map((description, index) => ({ id: `c${index + 1}`, description })) : undefined, allowedPaths: options.scope ?? [], session: options.session, scout: options.scout ? readJSON(options.scout) : undefined, plan: options.plan };
181
208
  // Without an explicit session, the run belongs to the calling conversation when the host names it.
209
+ if (!options.file) { input.executionMode = options.mode; input.conversationId = options.conversation; }
182
210
  input.session ??= callerSession();
183
211
  result = startRun(root, input); break;
184
212
  }
@@ -195,13 +223,14 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
195
223
  if (options.run && packet.runId !== options.run) throw new Error('--run and handoff runId differ.');
196
224
  result = recordHandoff(root, packet); break;
197
225
  }
198
- case 'verify': result = verifyRun(root, options.run); break;
199
- case 'prove-red': result = proveRun(root, options.run, { tests: options.tests }); break;
226
+ case 'verify': result = options['wait-ms'] === undefined ? verifyRun(root, options.run) : startOperation(root, options.run, { action: 'verify', waitMs: Number(options['wait-ms']) }); break;
227
+ case 'prove-red': result = options['wait-ms'] === undefined ? proveRun(root, options.run, { tests: options.tests }) : startOperation(root, options.run, { action: 'prove-red', input: { tests: options.tests }, waitMs: Number(options['wait-ms']) }); break;
228
+ case 'wait': if (!options.operation) throw new Error('run wait needs --operation ID from the returned handle.'); result = waitOperation(root, options.run, options.operation, Number(options['wait-ms'] ?? 30000)); break;
200
229
  case 'finish': {
201
230
  let input;
202
231
  if (options.file) {
203
- fileOnly(options, ['file', 'project', 'verbose', 'run', 'session']);
204
- input = inputObject(options.file, ['runId', 'summary', 'artifacts', 'passedEvidence', 'criterionEvidence', 'assessment', 'acceptFailures', 'testProof']);
232
+ fileOnly(options, ['file', 'project', 'verbose', 'run', 'session', 'wait-ms']);
233
+ input = inputObject(options.file, ['runId', 'summary', 'artifacts', 'passedEvidence', 'criterionEvidence', 'assessment', 'acceptFailures', 'testProof', 'scenarioEvidence', 'continuation']);
205
234
  // A test proof exemption belongs to the verify assessment; agents also put it at the top
206
235
  // level, so it is moved there unless the assessment already has a different one.
207
236
  if ('testProof' in input) {
@@ -216,11 +245,11 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
216
245
  if (!object(input.assessment)) throw new Error('assessment must be an object.');
217
246
  if (input.criterionEvidence !== undefined && (!object(input.criterionEvidence) || Object.values(input.criterionEvidence).some(v => typeof v !== 'string' || !v.trim()))) throw new Error('criterionEvidence must map criterion IDs to evidence strings.');
218
247
  if (input.passedEvidence !== undefined && (typeof input.passedEvidence !== 'string' || !input.passedEvidence.trim())) throw new Error('passedEvidence must be a nonempty string.');
219
- for (const path of input.artifacts ?? []) readFileSync(projectFile(root, inputPath(root, path)));
248
+ artifactFiles(root, (input.artifacts ?? []).map(path => inputPath(root, path)));
220
249
  // finishRun checks evidence and assessments against the run before any test runs.
221
250
  options.run = options.run ?? input.runId ?? activeRun(root, options.session);
222
251
  } else input = { summary: options.summary, artifacts: options.artifact, passedEvidence: options['criteria-passed'], criterionEvidence: options['criterion-evidence'] ? parseJSON(options['criterion-evidence'], '--criterion-evidence') : undefined, assessment: options.assessment ? readJSON(options.assessment) : {} };
223
- result = finishRun(root, options.run, input); break;
252
+ result = options['wait-ms'] === undefined ? finishRun(root, options.run, input) : startOperation(root, options.run, { action: 'finish', input, waitMs: Number(options['wait-ms']) }); break;
224
253
  }
225
254
  case 'retry': result = retryRun(root, options.run, { stage: options.stage, reason: options.reason }); break;
226
255
  case 'accept-failure': result = acceptFailure(root, options.run, { check: options.check, reason: options.reason }); break;
@@ -228,7 +257,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
228
257
  case 'review': result = reviewRun(root, options.run); break;
229
258
  case 'review-capture':
230
259
  if (!options.file) throw new Error('review-capture needs --file JSON with reviewer and optional scope.');
231
- result = captureReview(root, options.run, inputObject(options.file, ['reviewer', 'scope'])); break;
260
+ result = captureReview(root, options.run, inputObject(options.file, ['reviewer', 'scope', 'contextPaths', 'contextEvidence'])); break;
232
261
  case 'review-record':
233
262
  if (!options.file) throw new Error('review-record needs --file JSON with reviewId, evidence, identity and findings.');
234
263
  result = recordReview(root, options.run, inputObject(options.file, ['reviewId', 'evidence', 'identity', 'findings'])); break;
@@ -238,9 +267,9 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
238
267
  } else throw new Error(`Unknown command ${command}. Use cyc help.`);
239
268
  if (command === 'run' && !options.verbose) result = compact(action, result, root, options);
240
269
  console.log(humanInstallOutput(command) ? formatInstall(result) : JSON.stringify(result, null, 2));
241
- if (result?.ok === false || ['halted', 'exhausted', 'blocked'].includes(result?.status) || result?.passed === false) process.exitCode = 1;
270
+ 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;
242
271
  } catch (error) {
243
- const result = { ok: false, error: error.message };
272
+ const result = { ok: false, error: error.message, ...(error.setup ? { setup: error.setup } : {}), ...(error.field ? { field: error.field, repairTemplate: error.repairTemplate } : {}) };
244
273
  console.error(humanInstallOutput(positionals[0]) ? formatInstall(result) : JSON.stringify(result));
245
274
  process.exitCode = 1;
246
275
  }
@@ -316,9 +345,14 @@ function preexistingHint(ids) {
316
345
  function compact(action, result, root, options) {
317
346
  if (!result || typeof result !== 'object' || ['status', 'recover'].includes(action)) return result;
318
347
  const id = result.runId ?? result.id ?? options.run;
348
+ 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) };
319
350
  if (['review-capture', 'review-record'].includes(action)) { const { files, ...receipt } = result; return receipt; }
320
351
  if (action === 'prove-red') return result;
321
- if (action === 'finish') return result.failedAt === 'verify' && 'verificationStatus' in result ? { ...compact('verify', result, root, options), finished: false, failedAt: 'verify' } : result;
352
+ if (action === 'finish') {
353
+ const display = result.failedAt === 'verify' && 'verificationStatus' in result ? { ...compact('verify', result, root, options), finished: false, failedAt: 'verify' } : result;
354
+ return { ...display, guidance: guidance(display) };
355
+ }
322
356
  if (action === 'verify') {
323
357
  const recovery = result.passed ? null : recoverRun(root, id);
324
358
  return { runId: id, status: result.status, passed: result.passed, sourceStable: result.sourceStable, changedPaths: result.changedPaths, verificationStatus: result.verificationStatus, acceptedPreexistingFailures: result.acceptedPreexistingFailures, ...(result.acceptedFailuresThatChanged ? { acceptedFailuresThatChanged: result.acceptedFailuresThatChanged } : {}), ...(result.failedAtRunStart ? { failedAtRunStart: result.failedAtRunStart } : {}), ...(result.awaitingAcceptance ? { awaitingAcceptance: true } : {}),
@@ -330,6 +364,10 @@ function compact(action, result, root, options) {
330
364
  }
331
365
  if (!id) return result;
332
366
  const next = nextRun(root, id);
367
+ if(action==='next') {
368
+ const state=readRun(root,id);
369
+ next.workflowAdvice=routeTask(state.goal,{paths:state.allowedPaths}).guidance;
370
+ }
333
371
  const { previousHandoff, criteria, limits, assessmentRequired, assessmentTemplate, ...rest } = next;
334
372
  // Agents often read only the first lines (| head -40), so what they act on comes first and the
335
373
  // long fill-in template last.
@@ -1,39 +1 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="2020" height="1300" viewBox="0 0 2020 1300" role="img" aria-labelledby="methods-title methods-desc" font-family="Segoe UI, Arial, sans-serif"><title id="methods-title">CYC complete method-selection map</title><desc id="methods-desc">The cyc orchestrator chooses methods by task need. All seventeen supporting methods have a selection condition and output. These are capabilities, not seventeen mandatory steps. Examples are available in each method's accessible description; links open its source instructions.</desc><defs><marker id="select-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#2b69b0"/></marker></defs><rect width="2020" height="1300" fill="white"/><text x="40" y="54" font-size="40" font-weight="800" fill="#16225a">CYC · the full method library</text>
2
- <text x="40" y="96" font-size="22" font-weight="400" fill="#334362">1 orchestrator selects from 17 methods and 15 playbooks. Four stages describe only the common implementation route.</text>
3
- <text x="40" y="134" font-size="19" font-weight="400" fill="#334362">Arrows show selection by need. Rows group responsibilities; they are not an execution sequence. Click a method to read its instructions.</text>
4
- <g data-method="cyc"><a href="../../skills/cyc/SKILL.md"><rect x="40" y="540" width="250" height="180" rx="12" fill="#eaf3ff" stroke="#2b69b0" stroke-width="2"/><text x="60" y="578" font-size="30" font-weight="800" fill="#16225a">/cyc</text><text x="60" y="616" font-size="21" font-weight="700" fill="#334362">Own the outcome</text><text x="60" y="650" font-size="18" font-weight="400" fill="#334362">Choose the playbook</text><text x="60" y="681" font-size="18" font-weight="400" fill="#334362">Load relevant methods</text></a></g>
5
- <path d="M290 630 H320 V217 H350" fill="none" stroke="#2b69b0" stroke-width="2" marker-end="url(#select-arrow)"/>
6
- <rect x="350" y="190" width="1630" height="230" rx="12" fill="#f7f9fc" stroke="#ced9e5"/>
7
- <text x="370" y="219" font-size="21" font-weight="700" fill="#16225a">ENTER, RECOVER OR EXPLAIN</text>
8
- <text x="370" y="247" font-size="18" font-weight="400" fill="#334362">Project setup, task entry, interruption or requested learning</text>
9
- <g data-method="setup"><a href="../../methods/cyc-setup/SKILL.md" aria-label="Setup: Project needs configuration. Example: discover CI commands, run them and disclose hook status."><title>Example: discover CI commands, run them and disclose hook status.</title><rect x="370" y="268" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="384" y="296" font-size="23" font-weight="700" fill="#16225a">Setup</text><text x="384" y="326" font-size="16" font-weight="400" fill="#334362">Project needs configuration</text><text x="384" y="347" font-size="16" font-weight="400" fill="#334362">→ real checks + activation status</text></a></g>
10
- <g data-method="scout"><a href="../../methods/cyc-scout/SKILL.md" aria-label="Scout: Start a bounded engineering task. Example: locate the export path and the permission checks it must preserve."><title>Example: locate the export path and the permission checks it must preserve.</title><rect x="771.5" y="268" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="785.5" y="296" font-size="23" font-weight="700" fill="#16225a">Scout</text><text x="785.5" y="326" font-size="16" font-weight="400" fill="#334362">Start a bounded engineering task</text><text x="785.5" y="347" font-size="16" font-weight="400" fill="#334362">→ plan, consumers + checks</text></a></g>
11
- <g data-method="remember"><a href="../../methods/cyc-remember/SKILL.md" aria-label="Remember: Decision, checkpoint or resumption. Example: recover why a query was chosen; recheck files changed since the checkpoint."><title>Example: recover why a query was chosen; recheck files changed since the checkpoint.</title><rect x="1173" y="268" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1187" y="296" font-size="23" font-weight="700" fill="#16225a">Remember</text><text x="1187" y="326" font-size="16" font-weight="400" fill="#334362">Decision, checkpoint or resumption</text><text x="1187" y="347" font-size="16" font-weight="400" fill="#334362">→ decision log + revalidated next step</text></a></g>
12
- <g data-method="teach"><a href="../../methods/cyc-teach/SKILL.md" aria-label="Teach: Engineer requests a lesson. Example: explain why visible page rows differ from all matching export records."><title>Example: explain why visible page rows differ from all matching export records.</title><rect x="1574.5" y="268" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1588.5" y="296" font-size="23" font-weight="700" fill="#16225a">Teach</text><text x="1588.5" y="326" font-size="16" font-weight="400" fill="#334362">Engineer requests a lesson</text><text x="1588.5" y="347" font-size="16" font-weight="400" fill="#334362">→ project-grounded explanation / practice</text></a></g>
13
- <path d="M290 630 H320 V472 H350" fill="none" stroke="#2b69b0" stroke-width="2" marker-end="url(#select-arrow)"/>
14
- <rect x="350" y="445" width="1630" height="230" rx="12" fill="#f7f9fc" stroke="#ced9e5"/>
15
- <text x="370" y="474" font-size="21" font-weight="700" fill="#16225a">RESOLVE THE ENGINEERING QUESTION</text>
16
- <text x="370" y="502" font-size="18" font-weight="400" fill="#334362">Unclear goal, behavior, alternatives, impact, design or claim</text>
17
- <g data-method="frame"><a href="../../methods/cyc-frame/SKILL.md" aria-label="Frame: What counts as success?. Example: all matching rows, not merely a downloaded CSV."><title>Example: all matching rows, not merely a downloaded CSV.</title><rect x="370" y="523" width="251.66666666666666" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="384" y="551" font-size="23" font-weight="700" fill="#16225a">Frame</text><text x="384" y="581" font-size="16" font-weight="400" fill="#334362">What counts as success?</text><text x="384" y="602" font-size="16" font-weight="400" fill="#334362">→ criteria + scope</text></a></g>
18
- <g data-method="understand"><a href="../../methods/cyc-understand/SKILL.md" aria-label="Understand: Why does it behave this way?. Example: trace pagination from request to query."><title>Example: trace pagination from request to query.</title><rect x="637.6666666666666" y="523" width="251.66666666666666" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="651.6666666666666" y="551" font-size="23" font-weight="700" fill="#16225a">Understand</text><text x="651.6666666666666" y="581" font-size="16" font-weight="400" fill="#334362">Why does it behave this</text><text x="651.6666666666666" y="602" font-size="16" font-weight="400" fill="#334362">way?</text><text x="651.6666666666666" y="623" font-size="16" font-weight="400" fill="#334362">→ traced cause + evidence</text></a></g>
19
- <g data-method="explore"><a href="../../methods/cyc-explore/SKILL.md" aria-label="Explore: Which approach fits?. Example: compare paged fetch, streaming and queued export."><title>Example: compare paged fetch, streaming and queued export.</title><rect x="905.3333333333333" y="523" width="251.66666666666666" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="919.3333333333333" y="551" font-size="23" font-weight="700" fill="#16225a">Explore</text><text x="919.3333333333333" y="581" font-size="16" font-weight="400" fill="#334362">Which approach fits?</text><text x="919.3333333333333" y="602" font-size="16" font-weight="400" fill="#334362">→ compared options +</text><text x="919.3333333333333" y="623" font-size="16" font-weight="400" fill="#334362">recommendation</text></a></g>
20
- <g data-method="impact"><a href="../../methods/cyc-impact/SKILL.md" aria-label="Impact: What else could this affect?. Example: find permission and count consumers of the query."><title>Example: find permission and count consumers of the query.</title><rect x="1173" y="523" width="251.66666666666666" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1187" y="551" font-size="23" font-weight="700" fill="#16225a">Impact</text><text x="1187" y="581" font-size="16" font-weight="400" fill="#334362">What else could this</text><text x="1187" y="602" font-size="16" font-weight="400" fill="#334362">affect?</text><text x="1187" y="623" font-size="16" font-weight="400" fill="#334362">→ dependencies + checks</text></a></g>
21
- <g data-method="design"><a href="../../methods/cyc-design/SKILL.md" aria-label="Design: How should the change work?. Example: define the export/query boundary and errors."><title>Example: define the export/query boundary and errors.</title><rect x="1440.6666666666665" y="523" width="251.66666666666666" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1454.6666666666665" y="551" font-size="23" font-weight="700" fill="#16225a">Design</text><text x="1454.6666666666665" y="581" font-size="16" font-weight="400" fill="#334362">How should the change</text><text x="1454.6666666666665" y="602" font-size="16" font-weight="400" fill="#334362">work?</text><text x="1454.6666666666665" y="623" font-size="16" font-weight="400" fill="#334362">→ shape, contracts +</text><text x="1454.6666666666665" y="644" font-size="16" font-weight="400" fill="#334362">trade-offs</text></a></g>
22
- <g data-method="challenge"><a href="../../methods/cyc-challenge/SKILL.md" aria-label="Challenge: Does the plan or claim hold?. Example: question whether the export bypasses access filtering."><title>Example: question whether the export bypasses access filtering.</title><rect x="1708.333333333333" y="523" width="251.66666666666666" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1722.333333333333" y="551" font-size="23" font-weight="700" fill="#16225a">Challenge</text><text x="1722.333333333333" y="581" font-size="16" font-weight="400" fill="#334362">Does the plan or claim</text><text x="1722.333333333333" y="602" font-size="16" font-weight="400" fill="#334362">hold?</text><text x="1722.333333333333" y="623" font-size="16" font-weight="400" fill="#334362">→ supported objections +</text><text x="1722.333333333333" y="644" font-size="16" font-weight="400" fill="#334362">resolution</text></a></g>
23
- <path d="M290 630 H320 V727 H350" fill="none" stroke="#2b69b0" stroke-width="2" marker-end="url(#select-arrow)"/>
24
- <rect x="350" y="700" width="1630" height="230" rx="12" fill="#f7f9fc" stroke="#ced9e5"/>
25
- <text x="370" y="729" font-size="21" font-weight="700" fill="#16225a">PRODUCE AND ESTABLISH THE RESULT</text>
26
- <text x="370" y="757" font-size="18" font-weight="400" fill="#334362">Implement, verify or hand off the selected task</text>
27
- <g data-method="build"><a href="../../methods/cyc-build/SKILL.md" aria-label="Build: An agreed approach needs implementation. Example: repair retrieval in small slices; check duplicates before continuing."><title>Example: repair retrieval in small slices; check duplicates before continuing.</title><rect x="370" y="778" width="519.3333333333334" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="384" y="806" font-size="23" font-weight="700" fill="#16225a">Build</text><text x="384" y="836" font-size="16" font-weight="400" fill="#334362">An agreed approach needs implementation</text><text x="384" y="857" font-size="16" font-weight="400" fill="#334362">→ tested slices + inspected changes</text></a></g>
28
- <g data-method="verify"><a href="../../methods/cyc-verify/SKILL.md" aria-label="Verify: A behavior claim needs current evidence. Example: inspect the full exported membership, permissions and CSV consumer."><title>Example: inspect the full exported membership, permissions and CSV consumer.</title><rect x="905.3333333333334" y="778" width="519.3333333333334" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="919.3333333333334" y="806" font-size="23" font-weight="700" fill="#16225a">Verify</text><text x="919.3333333333334" y="836" font-size="16" font-weight="400" fill="#334362">A behavior claim needs current evidence</text><text x="919.3333333333334" y="857" font-size="16" font-weight="400" fill="#334362">→ checks, consumer results + limits</text></a></g>
29
- <g data-method="deliver"><a href="../../methods/cyc-deliver/SKILL.md" aria-label="Deliver: The result needs a reviewable handoff. Example: explain the query change, show checks and identify unmeasured scale."><title>Example: explain the query change, show checks and identify unmeasured scale.</title><rect x="1440.6666666666667" y="778" width="519.3333333333334" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1454.6666666666667" y="806" font-size="23" font-weight="700" fill="#16225a">Deliver</text><text x="1454.6666666666667" y="836" font-size="16" font-weight="400" fill="#334362">The result needs a reviewable handoff</text><text x="1454.6666666666667" y="857" font-size="16" font-weight="400" fill="#334362">→ outcome, evidence + remaining limits</text></a></g>
30
- <path d="M290 630 H320 V982 H350" fill="none" stroke="#2b69b0" stroke-width="2" marker-end="url(#select-arrow)"/>
31
- <rect x="350" y="955" width="1630" height="230" rx="12" fill="#f7f9fc" stroke="#ced9e5"/>
32
- <text x="370" y="984" font-size="21" font-weight="700" fill="#16225a">PRESERVE KNOWLEDGE AND RESPOND TO FINDINGS</text>
33
- <text x="370" y="1012" font-size="18" font-weight="400" fill="#334362">Relevant history, failed attempts, user correction or reusable lessons</text>
34
- <g data-method="context"><a href="../../methods/cyc-context/SKILL.md" aria-label="Context: Before component work; useful findings. Example: retain observed query constraints with evidence; identify adopted decisions only with actual acceptance."><title>Example: retain observed query constraints with evidence; identify adopted decisions only with actual acceptance.</title><rect x="370" y="1033" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="384" y="1061" font-size="23" font-weight="700" fill="#16225a">Context</text><text x="384" y="1091" font-size="16" font-weight="400" fill="#334362">Before component work; useful findings</text><text x="384" y="1112" font-size="16" font-weight="400" fill="#334362">→ verified facts / pending proposals</text></a></g>
35
- <g data-method="error-ledger"><a href="../../methods/cyc-error-ledger/SKILL.md" aria-label="Error Ledger: Before debugging; after failed attempts. Example: record that a paging fix duplicated rows and the check that exposed it."><title>Example: record that a paging fix duplicated rows and the check that exposed it.</title><rect x="771.5" y="1033" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="785.5" y="1061" font-size="23" font-weight="700" fill="#16225a">Error Ledger</text><text x="785.5" y="1091" font-size="16" font-weight="400" fill="#334362">Before debugging; after failed attempts</text><text x="785.5" y="1112" font-size="16" font-weight="400" fill="#334362">→ signatures, attempts + confirmed causes</text></a></g>
36
- <g data-method="correct"><a href="../../methods/cyc-correct/SKILL.md" aria-label="Correct: Feedback reveals a missing criterion. Example: “Not just the visible page” changes the target and its verification."><title>Example: “Not just the visible page” changes the target and its verification.</title><rect x="1173" y="1033" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1187" y="1061" font-size="23" font-weight="700" fill="#16225a">Correct</text><text x="1187" y="1091" font-size="16" font-weight="400" fill="#334362">Feedback reveals a missing criterion</text><text x="1187" y="1112" font-size="16" font-weight="400" fill="#334362">→ targeted repair + rechecked criteria</text></a></g>
37
- <g data-method="reflect"><a href="../../methods/cyc-reflect/SKILL.md" aria-label="Reflect: An outcome reveals a reusable improvement. Example: propose a multi-page check after a repeated omission; do not silently adopt rules."><title>Example: propose a multi-page check after a repeated omission; do not silently adopt rules.</title><rect x="1574.5" y="1033" width="385.5" height="136" rx="8" fill="white" stroke="#2b69b0"/><text x="1588.5" y="1061" font-size="23" font-weight="700" fill="#16225a">Reflect</text><text x="1588.5" y="1091" font-size="16" font-weight="400" fill="#334362">An outcome reveals a reusable improvement</text><text x="1588.5" y="1112" font-size="16" font-weight="400" fill="#334362">→ evidence-backed proposals to</text><text x="1588.5" y="1133" font-size="16" font-weight="400" fill="#334362">skills/checks</text></a></g>
38
- <text x="40" y="1230" font-size="19" font-weight="400" fill="#334362">The playbook sets the recorded sequence; the agent selects methods and interprets their findings. The controller does not invoke skills.</text>
39
- <a href="cyc-workflow.html#overview"><text x="40" y="1264" font-size="21" font-weight="700" fill="#2b69b0">Continue to the connected implementation flow →</text></a></svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="2020" height="1300" viewBox="0 0 2020 1300" role="img" aria-labelledby="methods-title methods-desc" font-family="Segoe UI, Arial, sans-serif"><style>.s0{fill:#eaf3ff;stroke:#2b69b0;stroke-width:2}.s1{fill:none;stroke:#2b69b0;stroke-width:2}.s2{fill:#f7f9fc;stroke:#ced9e5}.s3{fill:white;stroke:#2b69b0}</style><style>.t0{font-size:40px;font-weight:800;fill:#16225a}.t1{font-size:22px;fill:#334362}.t2{font-size:19px;fill:#334362}.t3{font-size:30px;font-weight:800;fill:#16225a}.t4{font-size:21px;font-weight:700;fill:#334362}.t5{font-size:18px;fill:#334362}.t6{font-size:21px;font-weight:700;fill:#16225a}.t7{font-size:23px;font-weight:700;fill:#16225a}.t8{font-size:16px;fill:#334362}.t9{font-size:21px;font-weight:700;fill:#2b69b0}</style><title id="methods-title">CYC complete method-selection map</title><desc id="methods-desc">The cyc orchestrator chooses methods by task need. All seventeen supporting methods have a selection condition and output. These are capabilities, not seventeen mandatory steps. Examples are available in each method's accessible description; links open its source instructions.</desc><defs><marker id="select-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#2b69b0"/></marker></defs><rect width="2020" height="1300" fill="white"/><text x="40" y="54" class="t0">CYC · the full method library</text><text x="40" y="96" class="t1">1 orchestrator selects from 17 methods and 15 playbooks. Four stages describe only the common implementation route.</text><text x="40" y="134" class="t2">Arrows show selection by need. Rows group responsibilities; they are not an execution sequence. Click a method to read its instructions.</text><g data-method="cyc"><a href="../../skills/cyc/SKILL.md"><rect x="40" y="540" width="250" height="180" rx="12" class="s0"/><text x="60" y="578" class="t3">/cyc</text><text x="60" y="616" class="t4">Own the outcome</text><text x="60" y="650" class="t5">Choose the playbook</text><text x="60" y="681" class="t5">Load relevant methods</text></a></g><path d="M290 630 H320 V217 H350" marker-end="url(#select-arrow)" class="s1"/><rect x="350" y="190" width="1630" height="230" rx="12" class="s2"/><text x="370" y="219" class="t6">ENTER, RECOVER OR EXPLAIN</text><text x="370" y="247" class="t5">Project setup, task entry, interruption or requested learning</text><g data-method="setup"><a href="../../methods/cyc-setup/SKILL.md" aria-label="Setup: Project needs configuration. Example: discover CI commands, run them and disclose hook status."><title>Example: discover CI commands, run them and disclose hook status.</title><rect x="370" y="268" width="385.5" height="136" rx="8" class="s3"/><text x="384" y="296" class="t7">Setup</text><text x="384" y="326" class="t8">Project needs configuration</text><text x="384" y="347" class="t8">→ real checks + activation status</text></a></g><g data-method="scout"><a href="../../methods/cyc-scout/SKILL.md" aria-label="Scout: Start a bounded engineering task. Example: locate the export path and the permission checks it must preserve."><title>Example: locate the export path and the permission checks it must preserve.</title><rect x="771.5" y="268" width="385.5" height="136" rx="8" class="s3"/><text x="785.5" y="296" class="t7">Scout</text><text x="785.5" y="326" class="t8">Start a bounded engineering task</text><text x="785.5" y="347" class="t8">→ plan, consumers + checks</text></a></g><g data-method="remember"><a href="../../methods/cyc-remember/SKILL.md" aria-label="Remember: Decision, checkpoint or resumption. Example: recover why a query was chosen; recheck files changed since the checkpoint."><title>Example: recover why a query was chosen; recheck files changed since the checkpoint.</title><rect x="1173" y="268" width="385.5" height="136" rx="8" class="s3"/><text x="1187" y="296" class="t7">Remember</text><text x="1187" y="326" class="t8">Decision, checkpoint or resumption</text><text x="1187" y="347" class="t8">→ decision log + revalidated next step</text></a></g><g data-method="teach"><a href="../../methods/cyc-teach/SKILL.md" aria-label="Teach: Engineer requests a lesson. Example: explain why visible page rows differ from all matching export records."><title>Example: explain why visible page rows differ from all matching export records.</title><rect x="1574.5" y="268" width="385.5" height="136" rx="8" class="s3"/><text x="1588.5" y="296" class="t7">Teach</text><text x="1588.5" y="326" class="t8">Engineer requests a lesson</text><text x="1588.5" y="347" class="t8">→ project-grounded explanation / practice</text></a></g><path d="M290 630 H320 V472 H350" marker-end="url(#select-arrow)" class="s1"/><rect x="350" y="445" width="1630" height="230" rx="12" class="s2"/><text x="370" y="474" class="t6">RESOLVE THE ENGINEERING QUESTION</text><text x="370" y="502" class="t5">Unclear goal, behavior, alternatives, impact, design or claim</text><g data-method="frame"><a href="../../methods/cyc-frame/SKILL.md" aria-label="Frame: What counts as success?. Example: all matching rows, not merely a downloaded CSV."><title>Example: all matching rows, not merely a downloaded CSV.</title><rect x="370" y="523" width="251.66666666666666" height="136" rx="8" class="s3"/><text x="384" y="551" class="t7">Frame</text><text x="384" y="581" class="t8">What counts as success?</text><text x="384" y="602" class="t8">→ criteria + scope</text></a></g><g data-method="understand"><a href="../../methods/cyc-understand/SKILL.md" aria-label="Understand: Why does it behave this way?. Example: trace pagination from request to query."><title>Example: trace pagination from request to query.</title><rect x="637.6666666666666" y="523" width="251.66666666666666" height="136" rx="8" class="s3"/><text x="651.6666666666666" y="551" class="t7">Understand</text><text x="651.6666666666666" y="581" class="t8">Why does it behave this</text><text x="651.6666666666666" y="602" class="t8">way?</text><text x="651.6666666666666" y="623" class="t8">→ traced cause + evidence</text></a></g><g data-method="explore"><a href="../../methods/cyc-explore/SKILL.md" aria-label="Explore: Which approach fits?. Example: compare paged fetch, streaming and queued export."><title>Example: compare paged fetch, streaming and queued export.</title><rect x="905.3333333333333" y="523" width="251.66666666666666" height="136" rx="8" class="s3"/><text x="919.3333333333333" y="551" class="t7">Explore</text><text x="919.3333333333333" y="581" class="t8">Which approach fits?</text><text x="919.3333333333333" y="602" class="t8">→ compared options +</text><text x="919.3333333333333" y="623" class="t8">recommendation</text></a></g><g data-method="impact"><a href="../../methods/cyc-impact/SKILL.md" aria-label="Impact: What else could this affect?. Example: find permission and count consumers of the query."><title>Example: find permission and count consumers of the query.</title><rect x="1173" y="523" width="251.66666666666666" height="136" rx="8" class="s3"/><text x="1187" y="551" class="t7">Impact</text><text x="1187" y="581" class="t8">What else could this</text><text x="1187" y="602" class="t8">affect?</text><text x="1187" y="623" class="t8">→ dependencies + checks</text></a></g><g data-method="design"><a href="../../methods/cyc-design/SKILL.md" aria-label="Design: How should the change work?. Example: define the export/query boundary and errors."><title>Example: define the export/query boundary and errors.</title><rect x="1440.6666666666665" y="523" width="251.66666666666666" height="136" rx="8" class="s3"/><text x="1454.6666666666665" y="551" class="t7">Design</text><text x="1454.6666666666665" y="581" class="t8">How should the change</text><text x="1454.6666666666665" y="602" class="t8">work?</text><text x="1454.6666666666665" y="623" class="t8">→ shape, contracts +</text><text x="1454.6666666666665" y="644" class="t8">trade-offs</text></a></g><g data-method="challenge"><a href="../../methods/cyc-challenge/SKILL.md" aria-label="Challenge: Does the plan or claim hold?. Example: question whether the export bypasses access filtering."><title>Example: question whether the export bypasses access filtering.</title><rect x="1708.333333333333" y="523" width="251.66666666666666" height="136" rx="8" class="s3"/><text x="1722.333333333333" y="551" class="t7">Challenge</text><text x="1722.333333333333" y="581" class="t8">Does the plan or claim</text><text x="1722.333333333333" y="602" class="t8">hold?</text><text x="1722.333333333333" y="623" class="t8">→ supported objections +</text><text x="1722.333333333333" y="644" class="t8">resolution</text></a></g><path d="M290 630 H320 V727 H350" marker-end="url(#select-arrow)" class="s1"/><rect x="350" y="700" width="1630" height="230" rx="12" class="s2"/><text x="370" y="729" class="t6">PRODUCE AND ESTABLISH THE RESULT</text><text x="370" y="757" class="t5">Implement, verify or hand off the selected task</text><g data-method="build"><a href="../../methods/cyc-build/SKILL.md" aria-label="Build: An agreed approach needs implementation. Example: repair retrieval in small slices; check duplicates before continuing."><title>Example: repair retrieval in small slices; check duplicates before continuing.</title><rect x="370" y="778" width="519.3333333333334" height="136" rx="8" class="s3"/><text x="384" y="806" class="t7">Build</text><text x="384" y="836" class="t8">An agreed approach needs implementation</text><text x="384" y="857" class="t8">→ tested slices + inspected changes</text></a></g><g data-method="verify"><a href="../../methods/cyc-verify/SKILL.md" aria-label="Verify: A behavior claim needs current evidence. Example: inspect the full exported membership, permissions and CSV consumer."><title>Example: inspect the full exported membership, permissions and CSV consumer.</title><rect x="905.3333333333334" y="778" width="519.3333333333334" height="136" rx="8" class="s3"/><text x="919.3333333333334" y="806" class="t7">Verify</text><text x="919.3333333333334" y="836" class="t8">A behavior claim needs current evidence</text><text x="919.3333333333334" y="857" class="t8">→ checks, consumer results + limits</text></a></g><g data-method="deliver"><a href="../../methods/cyc-deliver/SKILL.md" aria-label="Deliver: The result needs a reviewable handoff. Example: explain the query change, show checks and identify unmeasured scale."><title>Example: explain the query change, show checks and identify unmeasured scale.</title><rect x="1440.6666666666667" y="778" width="519.3333333333334" height="136" rx="8" class="s3"/><text x="1454.6666666666667" y="806" class="t7">Deliver</text><text x="1454.6666666666667" y="836" class="t8">The result needs a reviewable handoff</text><text x="1454.6666666666667" y="857" class="t8">→ outcome, evidence + remaining limits</text></a></g><path d="M290 630 H320 V982 H350" marker-end="url(#select-arrow)" class="s1"/><rect x="350" y="955" width="1630" height="230" rx="12" class="s2"/><text x="370" y="984" class="t6">PRESERVE KNOWLEDGE AND RESPOND TO FINDINGS</text><text x="370" y="1012" class="t5">Relevant history, failed attempts, user correction or reusable lessons</text><g data-method="context"><a href="../../methods/cyc-context/SKILL.md" aria-label="Context: Before component work; useful findings. Example: retain observed query constraints with evidence; identify adopted decisions only with actual acceptance."><title>Example: retain observed query constraints with evidence; identify adopted decisions only with actual acceptance.</title><rect x="370" y="1033" width="385.5" height="136" rx="8" class="s3"/><text x="384" y="1061" class="t7">Context</text><text x="384" y="1091" class="t8">Before component work; useful findings</text><text x="384" y="1112" class="t8">→ verified facts / pending proposals</text></a></g><g data-method="error-ledger"><a href="../../methods/cyc-error-ledger/SKILL.md" aria-label="Error Ledger: Before debugging; after failed attempts. Example: record that a paging fix duplicated rows and the check that exposed it."><title>Example: record that a paging fix duplicated rows and the check that exposed it.</title><rect x="771.5" y="1033" width="385.5" height="136" rx="8" class="s3"/><text x="785.5" y="1061" class="t7">Error Ledger</text><text x="785.5" y="1091" class="t8">Before debugging; after failed attempts</text><text x="785.5" y="1112" class="t8">→ signatures, attempts + confirmed causes</text></a></g><g data-method="correct"><a href="../../methods/cyc-correct/SKILL.md" aria-label="Correct: Feedback reveals a missing criterion. Example: “Not just the visible page” changes the target and its verification."><title>Example: “Not just the visible page” changes the target and its verification.</title><rect x="1173" y="1033" width="385.5" height="136" rx="8" class="s3"/><text x="1187" y="1061" class="t7">Correct</text><text x="1187" y="1091" class="t8">Feedback reveals a missing criterion</text><text x="1187" y="1112" class="t8">→ targeted repair + rechecked criteria</text></a></g><g data-method="reflect"><a href="../../methods/cyc-reflect/SKILL.md" aria-label="Reflect: An outcome reveals a reusable improvement. Example: propose a multi-page check after a repeated omission; do not silently adopt rules."><title>Example: propose a multi-page check after a repeated omission; do not silently adopt rules.</title><rect x="1574.5" y="1033" width="385.5" height="136" rx="8" class="s3"/><text x="1588.5" y="1061" class="t7">Reflect</text><text x="1588.5" y="1091" class="t8">An outcome reveals a reusable improvement</text><text x="1588.5" y="1112" class="t8">→ evidence-backed proposals to</text><text x="1588.5" y="1133" class="t8">skills/checks</text></a></g><text x="40" y="1230" class="t2">The playbook sets the recorded sequence; the agent selects methods and interprets their findings. The controller does not invoke skills.</text><a href="cyc-workflow.html#overview"><text x="40" y="1264" class="t9">Continue to the connected implementation flow →</text></a></svg>
@@ -1,44 +1 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="1200" height="1030" viewBox="0 0 1200 1030" role="img" aria-labelledby="overview-title overview-desc" font-family="Segoe UI, Arial, sans-serif"><title id="overview-title">CYC Stack team workflow</title><desc id="overview-desc">Your AI assistant reuses and revalidates project knowledge, builds a focused change and retains useful findings before final checks, proves applicable tests against original code, runs configured checks and reviews consumers, then delivers evidence and context pointers. The local controller checks records and executes project commands; an active host hook enforces delivery. Failed checks return to repair within the retry budget. Teams share through their existing project review process; run logs are local by default.</desc><defs><marker id="overview-forward" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#197f70"/></marker><marker id="overview-knowledge" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#7044b4"/></marker><marker id="overview-retry" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#b86b0a"/></marker></defs><rect x="0" y="0" width="1200" height="1030" rx="14" fill="white" stroke="none" stroke-width="2"/>
2
- <text x="48" y="43" fill="#197f70" font-size="16" font-weight="700" text-anchor="start"><tspan x="48" dy="0">CYC STACK / TEAM WORKFLOW</tspan></text>
3
- <text x="48" y="88" fill="#16225a" font-size="35" font-weight="800" text-anchor="start"><tspan x="48" dy="0">Shared project knowledge. Reviewable AI changes.</tspan></text>
4
- <rect x="48" y="116" width="1104" height="60" rx="14" fill="#eaf3ff" stroke="#2b69b0" stroke-width="2"/>
5
- <text x="72" y="154" fill="#16225a" font-size="23" font-weight="600" text-anchor="start"><tspan x="72" dy="0">Describe the outcome. Your AI assistant selects the relevant methods through /cyc.</tspan></text>
6
- <rect x="48" y="202" width="1104" height="132" rx="14" fill="#f5effc" stroke="#7044b4" stroke-width="2"/>
7
- <text x="72" y="235" fill="#7044b4" font-size="16" font-weight="700" text-anchor="start"><tspan x="72" dy="0">PROJECT KNOWLEDGE IN YOUR REPO</tspan></text>
8
- <text x="72" y="268" fill="#16225a" font-size="23" font-weight="600" text-anchor="start"><tspan x="72" dy="0">Reuse matched decisions, constraints, failed approaches and check recipes.</tspan></text>
9
- <text x="72" y="300" fill="#334362" font-size="20" font-weight="400" text-anchor="start"><tspan x="72" dy="0">Revalidate current code. Keep useful verified facts; label proposals and record acceptance for adopted decisions.</tspan></text>
10
- <polyline points="174,334 174,400" fill="none" stroke="#7044b4" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-knowledge)"/>
11
- <text x="196" y="373" fill="#7044b4" font-size="17" font-weight="600" text-anchor="start"><tspan x="196" dy="0">Read + revalidate</tspan></text>
12
- <polyline points="458,400 458,334" fill="none" stroke="#7044b4" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-knowledge)"/>
13
- <text x="478" y="373" fill="#7044b4" font-size="17" font-weight="600" text-anchor="start"><tspan x="478" dy="0">Retain before final checks</tspan></text>
14
- <rect x="48" y="400" width="252" height="200" rx="14" fill="#e6f5ef" stroke="#197f70" stroke-width="2"/>
15
- <text x="68" y="439" fill="#16225a" font-size="27" font-weight="800" text-anchor="start"><tspan x="68" dy="0">1. SCOUT</tspan></text>
16
- <text x="68" y="471" fill="#197f70" font-size="18" font-weight="600" text-anchor="start"><tspan x="68" dy="0">Understand the change</tspan></text>
17
- <text x="68" y="514" fill="#334362" font-size="20" font-weight="400" text-anchor="start"><tspan x="68" dy="0">Read relevant history.</tspan><tspan x="68" dy="29">Trace affected paths.</tspan><tspan x="68" dy="29">Set criteria and checks.</tspan></text>
18
- <polyline points="300,500 332,500" fill="none" stroke="#197f70" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-forward)"/>
19
- <rect x="332" y="400" width="252" height="200" rx="14" fill="#e6f5ef" stroke="#197f70" stroke-width="2"/>
20
- <text x="352" y="439" fill="#16225a" font-size="27" font-weight="800" text-anchor="start"><tspan x="352" dy="0">2. BUILD</tspan></text>
21
- <text x="352" y="471" fill="#197f70" font-size="18" font-weight="600" text-anchor="start"><tspan x="352" dy="0">Make a focused change</tspan></text>
22
- <text x="352" y="514" fill="#334362" font-size="20" font-weight="400" text-anchor="start"><tspan x="352" dy="0">Change one useful slice.</tspan><tspan x="352" dy="29">Check affected behavior.</tspan><tspan x="352" dy="29">Retain useful findings.</tspan></text>
23
- <polyline points="584,500 616,500" fill="none" stroke="#197f70" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-forward)"/>
24
- <rect x="616" y="400" width="252" height="200" rx="14" fill="#e6f5ef" stroke="#197f70" stroke-width="2"/>
25
- <text x="636" y="439" fill="#16225a" font-size="27" font-weight="800" text-anchor="start"><tspan x="636" dy="0">3. VERIFY</tspan></text>
26
- <text x="636" y="471" fill="#197f70" font-size="18" font-weight="600" text-anchor="start"><tspan x="636" dy="0">Establish current evidence</tspan></text>
27
- <text x="636" y="514" fill="#334362" font-size="20" font-weight="400" text-anchor="start"><tspan x="636" dy="0">Original-code proof.*</tspan><tspan x="636" dy="29">Your configured checks.</tspan><tspan x="636" dy="29">Intent + consumer review.</tspan></text>
28
- <polyline points="868,500 900,500" fill="none" stroke="#197f70" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-forward)"/>
29
- <rect x="900" y="400" width="252" height="200" rx="14" fill="#e6f5ef" stroke="#197f70" stroke-width="2"/>
30
- <text x="920" y="439" fill="#16225a" font-size="27" font-weight="800" text-anchor="start"><tspan x="920" dy="0">4. DELIVER</tspan></text>
31
- <text x="920" y="471" fill="#197f70" font-size="18" font-weight="600" text-anchor="start"><tspan x="920" dy="0">Leave a useful handoff</tspan></text>
32
- <text x="920" y="514" fill="#334362" font-size="20" font-weight="400" text-anchor="start"><tspan x="920" dy="0">Outcome and limits.</tspan><tspan x="920" dy="29">A generated review.</tspan><tspan x="920" dy="29">Useful context pointers.</tspan></text>
33
- <polyline points="742,600 742,665 458,665 458,600" fill="none" stroke="#b86b0a" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-retry)"/>
34
- <text x="600" y="696" fill="#b86b0a" font-size="19" font-weight="600" text-anchor="middle"><tspan x="600" dy="0">Failed checks return to repair within the same retry budget.</tspan></text>
35
- <text x="48" y="740" fill="#16225a" font-size="22" font-weight="700" text-anchor="start"><tspan x="48" dy="0">The assistant does the engineering. Code checks the recorded evidence.</tspan></text>
36
- <rect x="48" y="765" width="536" height="128" rx="14" fill="#f3f6fa" stroke="#ced9e5" stroke-width="2"/>
37
- <text x="72" y="800" fill="#16225a" font-size="23" font-weight="700" text-anchor="start"><tspan x="72" dy="0">LOCAL CONTROLLER</tspan></text>
38
- <text x="72" y="833" fill="#334362" font-size="19" font-weight="400" text-anchor="start"><tspan x="72" dy="0">Scope, current file evidence and retry budgets.</tspan><tspan x="72" dy="29">Runs the project’s configured commands.</tspan></text>
39
- <rect x="616" y="765" width="536" height="128" rx="14" fill="#eaf3ff" stroke="#2b69b0" stroke-width="2"/>
40
- <text x="640" y="800" fill="#16225a" font-size="23" font-weight="700" text-anchor="start"><tspan x="640" dy="0">ACTIVE HOST HOOK</tspan></text>
41
- <text x="640" y="833" fill="#334362" font-size="19" font-weight="400" text-anchor="start"><tspan x="640" dy="0">Enforces delivery when the hook is active.</tspan><tspan x="640" dy="29">A ready result or an honest blocked handoff.</tspan></text>
42
- <text x="48" y="927" fill="#334362" font-size="17" font-weight="400" text-anchor="start"><tspan x="48" dy="0">* Original-code proof for applicable feature, bug-fix and refactor runs; exemptions are recorded.</tspan></text>
43
- <text x="48" y="964" fill="#16225a" font-size="22" font-weight="700" text-anchor="start"><tspan x="48" dy="0">Your team reviews and shares. Publication requires authorization.</tspan></text>
44
- <text x="48" y="995" fill="#334362" font-size="18" font-weight="400" text-anchor="start"><tspan x="48" dy="0">Run logs stay local by default. Share useful project docs and review evidence through your normal process.</tspan></text></svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1200" height="1030" viewBox="0 0 1200 1030" role="img" aria-labelledby="overview-title overview-desc" font-family="Segoe UI, Arial, sans-serif"><style>.s0{fill:white;stroke:none;stroke-width:2}.s1{fill:#eaf3ff;stroke:#2b69b0;stroke-width:2}.s2{fill:#f5effc;stroke:#7044b4;stroke-width:2}.s3{fill:#e6f5ef;stroke:#197f70;stroke-width:2}.s4{fill:#f3f6fa;stroke:#ced9e5;stroke-width:2}</style><style>.t0{fill:#197f70;font-size:16px;font-weight:700}.t1{fill:#16225a;font-size:35px;font-weight:800}.t2{fill:#16225a;font-size:23px;font-weight:600}.t3{fill:#7044b4;font-size:16px;font-weight:700}.t4{fill:#334362;font-size:20px}.t5{fill:#7044b4;font-size:17px;font-weight:600}.t6{fill:#16225a;font-size:27px;font-weight:800}.t7{fill:#197f70;font-size:18px;font-weight:600}.t8{fill:#b86b0a;font-size:19px;font-weight:600;text-anchor:middle}.t9{fill:#16225a;font-size:22px;font-weight:700}.t10{fill:#16225a;font-size:23px;font-weight:700}.t11{fill:#334362;font-size:19px}.t12{fill:#334362;font-size:17px}.t13{fill:#334362;font-size:18px}</style><title id="overview-title">CYC Stack team workflow</title><desc id="overview-desc">Your AI assistant reuses and revalidates project knowledge, builds a focused change and retains useful findings before final checks, proves applicable tests against original code, runs configured checks and reviews consumers, then delivers evidence and context pointers. The local controller checks records and executes project commands; an active host hook enforces delivery. Failed checks return to repair within the retry budget. Teams share through their existing project review process; run logs are local by default.</desc><defs><marker id="overview-forward" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#197f70"/></marker><marker id="overview-knowledge" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#7044b4"/></marker><marker id="overview-retry" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0 L10 5 L0 10 Z" fill="#b86b0a"/></marker></defs><rect x="0" y="0" width="1200" height="1030" rx="14" class="s0"/><text x="48" y="43" class="t0">CYC STACK / TEAM WORKFLOW</text><text x="48" y="88" class="t1">Shared project knowledge. Reviewable AI changes.</text><rect x="48" y="116" width="1104" height="60" rx="14" class="s1"/><text x="72" y="154" class="t2">Describe the outcome. Your AI assistant selects the relevant methods through /cyc.</text><rect x="48" y="202" width="1104" height="132" rx="14" class="s2"/><text x="72" y="235" class="t3">PROJECT KNOWLEDGE IN YOUR REPO</text><text x="72" y="268" class="t2">Reuse matched decisions, constraints, failed approaches and check recipes.</text><text x="72" y="300" class="t4">Revalidate current code. Keep useful verified facts; label proposals and record acceptance for adopted decisions.</text><polyline points="174,334 174,400" fill="none" stroke="#7044b4" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-knowledge)"/><text x="196" y="373" class="t5">Read + revalidate</text><polyline points="458,400 458,334" fill="none" stroke="#7044b4" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-knowledge)"/><text x="478" y="373" class="t5">Retain before final checks</text><rect x="48" y="400" width="252" height="200" rx="14" class="s3"/><text x="68" y="439" class="t6">1. SCOUT</text><text x="68" y="471" class="t7">Understand the change</text><text x="68" y="514" class="t4">Read relevant history.<tspan x="68" dy="29">Trace affected paths.</tspan><tspan x="68" dy="29">Set criteria and checks.</tspan></text><polyline points="300,500 332,500" fill="none" stroke="#197f70" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-forward)"/><rect x="332" y="400" width="252" height="200" rx="14" class="s3"/><text x="352" y="439" class="t6">2. BUILD</text><text x="352" y="471" class="t7">Make a focused change</text><text x="352" y="514" class="t4">Change one useful slice.<tspan x="352" dy="29">Check affected behavior.</tspan><tspan x="352" dy="29">Retain useful findings.</tspan></text><polyline points="584,500 616,500" fill="none" stroke="#197f70" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-forward)"/><rect x="616" y="400" width="252" height="200" rx="14" class="s3"/><text x="636" y="439" class="t6">3. VERIFY</text><text x="636" y="471" class="t7">Establish current evidence</text><text x="636" y="514" class="t4">Original-code proof.*<tspan x="636" dy="29">Your configured checks.</tspan><tspan x="636" dy="29">Intent + consumer review.</tspan></text><polyline points="868,500 900,500" fill="none" stroke="#197f70" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-forward)"/><rect x="900" y="400" width="252" height="200" rx="14" class="s3"/><text x="920" y="439" class="t6">4. DELIVER</text><text x="920" y="471" class="t7">Leave a useful handoff</text><text x="920" y="514" class="t4">Outcome and limits.<tspan x="920" dy="29">A generated review.</tspan><tspan x="920" dy="29">Useful context pointers.</tspan></text><polyline points="742,600 742,665 458,665 458,600" fill="none" stroke="#b86b0a" stroke-width="3" stroke-linejoin="round" marker-end="url(#overview-retry)"/><text x="600" y="696" class="t8">Failed checks return to repair within the same retry budget.</text><text x="48" y="740" class="t9">The assistant does the engineering. Code checks the recorded evidence.</text><rect x="48" y="765" width="536" height="128" rx="14" class="s4"/><text x="72" y="800" class="t10">LOCAL CONTROLLER</text><text x="72" y="833" class="t11">Scope, current file evidence and retry budgets.<tspan x="72" dy="29">Runs the project’s configured commands.</tspan></text><rect x="616" y="765" width="536" height="128" rx="14" class="s1"/><text x="640" y="800" class="t10">ACTIVE HOST HOOK</text><text x="640" y="833" class="t11">Enforces delivery when the hook is active.<tspan x="640" dy="29">A ready result or an honest blocked handoff.</tspan></text><text x="48" y="927" class="t12">* Original-code proof for applicable feature, bug-fix and refactor runs; exemptions are recorded.</text><text x="48" y="964" class="t9">Your team reviews and shares. Publication requires authorization.</text><text x="48" y="995" class="t13">Run logs stay local by default. Share useful project docs and review evidence through your normal process.</text></svg>