cyc-stack 0.7.1 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.7.1",
3
+ "version": "0.8.3",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.7.1",
3
+ "version": "0.8.3",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.7.1",
3
+ "version": "0.8.3",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  <div align="center">
4
4
  <p><strong>CYC Stack</strong></p>
5
5
  <h1>Make your AI worth the tokens it uses.</h1>
6
- <p>CYC is a portable library of engineering skills and playbooks for Claude Code, Codex and Cursor&mdash;built around <strong>context engineering, token optimization and clear, actionable results.</strong></p>
6
+ <p>CYC is a portable library of engineering skills and playbooks for Claude Code, Codex and Cursor, built around <strong>context engineering, token optimization and clear, actionable results.</strong></p>
7
7
  <p>You spent the tokens getting it right. <strong>The decisions and lessons that got you there shouldn&rsquo;t disappear when the chat ends.</strong></p>
8
8
  <p>Give your agent the context that matters. Carry what you learn into the next task. Get answers that show what changed, what was checked and what still needs attention.</p>
9
9
  <p><strong>Put it to work on your next task. Make it a shared standard for your team.</strong></p>
package/bin/cyc.mjs CHANGED
@@ -1,9 +1,10 @@
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 { acceptFailure, activeRun, callerSession, inputPath, completeRun, controlRun, finishRun, nextRun, projectFile, proveRun, quickHandoff, readRun, recordHandoff, recoverRun, retryRun, reviewRun, startRun, verifyRun, captureReview, recordReview, startOperation, waitOperation, prepareRunContext } from '../scripts/runtime.mjs';
7
8
 
8
9
  const args = process.argv.slice(2);
9
10
  const positionals = [];
@@ -14,7 +15,8 @@ try {
14
15
  if (!args[i].startsWith('--')) { positionals.push(args[i]); continue; }
15
16
  const name = args[i].slice(2);
16
17
  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}`);
18
+ 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; }
19
+ 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
20
  const value = args[++i];
19
21
  if (!value || value.startsWith('--')) throw new Error(`--${name} needs a value.`);
20
22
  if (['scope', 'artifact', 'criterion', 'passed', 'unmet', 'tests', 'path'].includes(name)) {
@@ -27,6 +29,7 @@ try {
27
29
  if ((options.host !== undefined || options.token !== undefined) && command !== 'onboard') throw new Error('--host and --token are only supported by onboard.');
28
30
  if (options.kind !== undefined && command !== 'investigate' && (command !== 'recipe' || action !== 'list')) throw new Error('--kind is only supported by recipe list and investigate.');
29
31
  if (options.since !== undefined && command !== 'readiness' && command !== 'context') throw new Error('--since is only supported by readiness and context review.');
32
+ if (options['update-run'] !== undefined && (command !== 'context' || action !== 'review' || !options.write)) throw new Error('--update-run is only supported by context review --write.');
30
33
  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
34
  if (options.verify && command !== 'onboard') throw new Error('--verify is only supported by onboard. Use run verify for task verification.');
32
35
  if (options.verify && options['dry-run']) throw new Error('Do not combine --verify with --dry-run. Plain onboard performs read-only inspection.');
@@ -51,7 +54,8 @@ Discover:
51
54
  (execute an applicable authorized recipe; retain diagnostic evidence)
52
55
 
53
56
  Component context docs (docs/context/):
54
- cyc context review [--run ID | --since YYYY-MM-DD | --all] [--write] [--new NAME]
57
+ cyc context prepare --run ID [--file CONTEXT.json]
58
+ cyc context review [--run ID | --since YYYY-MM-DD | --all] [--write --update-run UPDATE_ID] [--new NAME]
55
59
  (map completed runs' changed files to component docs and propose the doc entry from each run's
56
60
  record: what changed, what was learned, the decisive check, files with hashes, date and run ID.
57
61
  Read-only without --write; --write appends the entries and refreshes INDEX.md)
@@ -75,6 +79,9 @@ Execute through your existing AI host:
75
79
  (from build or verify: record build, prove new tests, verify, record verify and deliver, and complete;
76
80
  artifacts default to the files this run changed; run next gives the assessment template)
77
81
  cyc run finish --file FINISH.json (summary, assessment, criterionEvidence; optional runId and artifacts)
82
+ (versioned input uses canonical scenarioEvidence; needs-proof-review returns its bound continuation file)
83
+ cyc run wait --run ID --operation ID --wait-ms 30000 (bounded progress; finish/verify/prove-red also accept --wait-ms)
84
+ Start JSON: executionMode native-codex|native-claude|cursor|standalone, real conversationId, separate session label; optional frozen proofCommands.
78
85
  cyc run retry --run ID --stage build --reason "What changed in the approach"
79
86
  cyc run accept-failure --run ID --check CHECK_ID --reason "Why this pre-existing failure is unrelated"
80
87
  cyc run complete --run ID
@@ -128,15 +135,19 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
128
135
  else if (action === 'run') {
129
136
  if (options['dry-run']) throw new Error('Use recipe list to inspect without execution; recipe run does not accept --dry-run.');
130
137
  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') }));
138
+ result = await tools.runRecipe(root, options.recipe, { run: options.run });
139
+ 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
140
  } else throw new Error('Use recipe list or recipe run.');
134
141
  } else if (command === 'context') {
135
142
  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 });
143
+ 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'] });
144
+ else if (action === 'prepare') {
145
+ if (!options.run) throw new Error('context prepare needs the exact --run ID.');
146
+ result = prepareRunContext(root, options.run, options.file ? inputObject(options.file, ['records', 'summary', 'reason']) : {});
147
+ }
137
148
  else if (action === 'lint') result = context.lintContext(root, { doc: options.doc });
138
149
  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.');
150
+ else throw new Error('Use context prepare, context review, context lint, or context measure.');
140
151
  } else if (command === 'onboard') {
141
152
  result = (await import('../scripts/onboarding.mjs')).onboardProject(root, { verify: !!options.verify, host: options.host, session: options.session, token: options.token });
142
153
  } else if (['init', 'install', 'uninstall', 'doctor', 'activate'].includes(command)) {
@@ -150,9 +161,10 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
150
161
  const { checkReply } = await import('../scripts/response-gate.mjs');
151
162
  const { allowsLongResponse } = await import('../scripts/response-mode.mjs');
152
163
  let expanded = !!options.expanded;
153
- if (options.session) {
164
+ const execution = options.mode ? resolveExecution(root, { executionMode: options.mode, conversationId: options.conversation, session: options.session }) : null;
165
+ if (options.session && execution?.mode !== 'standalone') {
154
166
  // The conversation's own setting decides the cap, as it does at Stop.
155
- const statePath = resolve(root, '.cyc/runtime', `${options.session}.state.json`);
167
+ const statePath = resolve(root, '.cyc/runtime', `${execution?.gateSession ?? options.session}.state.json`);
156
168
  if (!existsSync(statePath)) throw new Error(`No hook state for session ${options.session} at ${statePath}.`);
157
169
  expanded = allowsLongResponse(JSON.parse(readFileSync(statePath, 'utf8').replace(/^/, '')));
158
170
  }
@@ -161,7 +173,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
161
173
  } else if (command === 'readiness') {
162
174
  result = (await import('../scripts/run-gate.mjs')).sessionReadiness({ root, session: options.session, since: options.since });
163
175
  } 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 });
176
+ 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
177
  } else if (command === 'playbooks') result = catalog;
166
178
  else if (command === 'route') {
167
179
  if (!options.goal) throw new Error('--goal is required.');
@@ -172,13 +184,14 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
172
184
  let input;
173
185
  if (options.file) {
174
186
  fileOnly(options, ['file', 'project', 'verbose']);
175
- input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy']);
187
+ input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy', 'executionMode', 'conversationId', 'proofCommands', 'contextRetention']);
176
188
  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
189
  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
190
  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
191
  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
192
  } 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
193
  // Without an explicit session, the run belongs to the calling conversation when the host names it.
194
+ if (!options.file) { input.executionMode = options.mode; input.conversationId = options.conversation; }
182
195
  input.session ??= callerSession();
183
196
  result = startRun(root, input); break;
184
197
  }
@@ -195,13 +208,14 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
195
208
  if (options.run && packet.runId !== options.run) throw new Error('--run and handoff runId differ.');
196
209
  result = recordHandoff(root, packet); break;
197
210
  }
198
- case 'verify': result = verifyRun(root, options.run); break;
199
- case 'prove-red': result = proveRun(root, options.run, { tests: options.tests }); break;
211
+ case 'verify': result = options['wait-ms'] === undefined ? verifyRun(root, options.run) : startOperation(root, options.run, { action: 'verify', waitMs: Number(options['wait-ms']) }); break;
212
+ 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;
213
+ 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
214
  case 'finish': {
201
215
  let input;
202
216
  if (options.file) {
203
- fileOnly(options, ['file', 'project', 'verbose', 'run', 'session']);
204
- input = inputObject(options.file, ['runId', 'summary', 'artifacts', 'passedEvidence', 'criterionEvidence', 'assessment', 'acceptFailures', 'testProof']);
217
+ fileOnly(options, ['file', 'project', 'verbose', 'run', 'session', 'wait-ms']);
218
+ input = inputObject(options.file, ['runId', 'summary', 'artifacts', 'passedEvidence', 'criterionEvidence', 'assessment', 'acceptFailures', 'testProof', 'scenarioEvidence', 'continuation']);
205
219
  // A test proof exemption belongs to the verify assessment; agents also put it at the top
206
220
  // level, so it is moved there unless the assessment already has a different one.
207
221
  if ('testProof' in input) {
@@ -216,11 +230,11 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
216
230
  if (!object(input.assessment)) throw new Error('assessment must be an object.');
217
231
  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
232
  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)));
233
+ artifactFiles(root, (input.artifacts ?? []).map(path => inputPath(root, path)));
220
234
  // finishRun checks evidence and assessments against the run before any test runs.
221
235
  options.run = options.run ?? input.runId ?? activeRun(root, options.session);
222
236
  } 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;
237
+ result = options['wait-ms'] === undefined ? finishRun(root, options.run, input) : startOperation(root, options.run, { action: 'finish', input, waitMs: Number(options['wait-ms']) }); break;
224
238
  }
225
239
  case 'retry': result = retryRun(root, options.run, { stage: options.stage, reason: options.reason }); break;
226
240
  case 'accept-failure': result = acceptFailure(root, options.run, { check: options.check, reason: options.reason }); break;
@@ -228,7 +242,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
228
242
  case 'review': result = reviewRun(root, options.run); break;
229
243
  case 'review-capture':
230
244
  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;
245
+ result = captureReview(root, options.run, inputObject(options.file, ['reviewer', 'scope', 'contextPaths', 'contextEvidence'])); break;
232
246
  case 'review-record':
233
247
  if (!options.file) throw new Error('review-record needs --file JSON with reviewId, evidence, identity and findings.');
234
248
  result = recordReview(root, options.run, inputObject(options.file, ['reviewId', 'evidence', 'identity', 'findings'])); break;
@@ -238,9 +252,9 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
238
252
  } else throw new Error(`Unknown command ${command}. Use cyc help.`);
239
253
  if (command === 'run' && !options.verbose) result = compact(action, result, root, options);
240
254
  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;
255
+ if (result?.ok === false || ['halted', 'exhausted', 'blocked'].includes(result?.status) || result?.passed === false || result?.result?.passed === false || ['halted', 'exhausted', 'blocked'].includes(result?.result?.status)) process.exitCode = 1;
242
256
  } catch (error) {
243
- const result = { ok: false, error: error.message };
257
+ const result = { ok: false, error: error.message, ...(error.setup ? { setup: error.setup } : {}), ...(error.field ? { field: error.field, repairTemplate: error.repairTemplate } : {}) };
244
258
  console.error(humanInstallOutput(positionals[0]) ? formatInstall(result) : JSON.stringify(result));
245
259
  process.exitCode = 1;
246
260
  }
@@ -315,6 +329,7 @@ function preexistingHint(ids) {
315
329
 
316
330
  function compact(action, result, root, options) {
317
331
  if (!result || typeof result !== 'object' || ['status', 'recover'].includes(action)) return result;
332
+ if (result.operationId) return result;
318
333
  const id = result.runId ?? result.id ?? options.run;
319
334
  if (['review-capture', 'review-record'].includes(action)) { const { files, ...receipt } = result; return receipt; }
320
335
  if (action === 'prove-red') return result;
package/docs/context.md CHANGED
@@ -1,40 +1,24 @@
1
1
  # Project context
2
2
 
3
- CYC keeps useful project knowledge in the repository so a fresh chat or teammate can find the relevant reasoning without replaying the original conversation. The agent selects and interprets that knowledge; structural validation does not establish that every recorded claim is correct.
3
+ Every new feature leaves a focused canonical record and index row in the target project. Meaningful changes update that feature and affected shared-component knowledge. The next agent should find capability boundaries, contracts, choices, failures, checks and limits without the original chat. A handoff, recipe, setup guide or ignored receipt alone is insufficient.
4
4
 
5
- ## What belongs in context
5
+ Read docs/context/INDEX.md, then matched records and relevant error history. Revalidate consequential claims against current source/dependencies. A configured context.directory can reuse a genuine equivalent project convention; never substitute the installed engine's development index.
6
6
 
7
- Keep decisions and their reasons, integration constraints, failed approaches worth avoiding, and checks that protect the behavior. Reference the supporting source or observed result. Separate verified facts from proposals and assumptions. Update a current view when the implementation changes; retain historical entries as history.
7
+ ## Normal workflow
8
8
 
9
- Use one index at `docs/context/INDEX.md`, with path coverage and links to the relevant component notes. Read the matching notes and error-ledger entries for the task. Do not load every component or the entire run history by default.
9
+ Scout/Start plans canonical records and representative entrypoints before scope freezes. Finish prepares/validates authored knowledge, History/source evidence and index before final checks. Missing/stale context returns needs-context with remaining input; fill learning.context or use context prepare --run ID for earlier feedback. Explicit restrictions remain pending without unauthorized writes. See the [Context method](../methods/cyc-context/SKILL.md) for schemas, fixed layout and recovery.
10
10
 
11
- The [Context method](../methods/cyc-context/SKILL.md) defines the component layout and retention procedure. [Work assessments](work-assessments.md) describe learning dispositions and the distinction between technical evidence and adopted decisions.
12
-
13
- ## Inspect and maintain context
14
-
15
- From the CYC source checkout:
16
-
17
- ```sh
11
+ ```text
18
12
  node bin/cyc.mjs investigate --path src/orders
19
13
  node bin/cyc.mjs context lint
20
- node bin/cyc.mjs context review
14
+ node bin/cyc.mjs context review --run SOURCE_ID
21
15
  node bin/cyc.mjs context measure --path src/orders
22
16
  ```
23
17
 
24
- Replace `src/orders` with the paths relevant to the task. In an installed application, use `node .cyc/engine/bin/cyc.mjs` instead. These inspection commands do not run the project's verification recipes.
25
-
26
- `context lint` checks document/index structure and evidence freshness where supported. A valid index can still contain an incorrect or unhelpful explanation. Recheck consequential statements against current code and dependencies.
27
-
28
- `context review` proposes entries from recorded completed work. Review the proposed retention before using `--write`; keep changes within the authorized scope. Existing records and reference rows are handled according to the [project-tools contract](project-tools.md).
29
-
30
- ## Interpret reading-size measurements
31
-
32
- `context measure` reports the current index and matching linked documents, the wider context folder, and available local run records. It counts matching local documents once, including multiple links in a row, and avoids counting the index twice. Repeated links do not increase the selected size.
33
-
34
- Character counts are Unicode code points. Estimated tokens use approximately four characters per token; no model tokenizer is run. Controller run records are not chat transcripts. A source-only machine may have history that a teammate's checkout does not contain.
18
+ Installed projects use .cyc/engine/bin/cyc.mjs. Read-only inspection executes no recipe. Historical catch-up writes need a new implementation update with a required canonical plan and executable final checks (--write --update-run ID). Preserve old receipts, record the repair under its actual run/date and verify final files. A reply packet cannot restore evidence after context changes.
35
19
 
36
- These are file-size measurements. They do not establish provider billing, tokens saved, faster work or successful context reuse. Rerun the measurement for the current files rather than relying on historical figures.
20
+ ## Evidence limits
37
21
 
38
- ## Check that knowledge transfers
22
+ Lint validates structure, mapping and supported freshness, not semantic truth or adoption. Optional manifests bind selected bytes, not complete dependencies. Context measure counts unique selected local files, estimates tokens as Unicode characters/4 and cannot see chat usage, billing or savings. Run records are not transcripts and may exist only in ignored local storage.
39
23
 
40
- Complete one bounded task and retain the useful constraint with its evidence. Then use a fresh chat or teammate, without the original conversation, for a related change. Observe whether the relevant record is found, read, revalidated and used. Run the new task's real checks and inspect the result. Record missed or stale guidance honestly.
24
+ To evaluate actual reuse, give a fresh chat/teammate a related bounded task without the original conversation; observe discovery, reading, revalidation and successful use with real checks. Record missed/stale guidance. Parser/fixture passes alone do not establish future model quality or measured workflow savings.
@@ -26,23 +26,23 @@ Each manifest is checked once per lookup. Output reports the checked-file count
26
26
 
27
27
  `investigate --kind investigation|verification` optionally filters recipes only. Context matching, context limits, warnings and evidence freshness checks remain unchanged, even if no recipes match the selected kind. The filter intersects existing path/goal/run matching before recipe counts and `--limit` truncation; `totalRecipeMatches` and `recipesTruncated` describe the filtered selection. Omitting kind preserves both kinds and their order. The direct API accepts the same option: `investigateProject(projectRoot, { paths: ['src/orders'], kind: 'verification' })`.
28
28
 
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. 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.
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
31
  ## Component context docs
32
32
 
33
- `docs/context/` holds one doc per component in a fixed layout, and `INDEX.md` is their table of contents: per component the Covers patterns, the doc link, the last AI change (date, run, one line) and the lesson count. The first step of a task reads the index and the matched docs, not every doc. The layout rules are in the [Context method](../methods/cyc-context/SKILL.md) and as the `rules` export of `scripts/context-review.mjs`.
33
+ The target index maps focused canonical feature/component records, with Covers, resolving Doc link, Last AI change and Lessons. Read matched records, not all historical prose. Configure context.directory before start only to reuse a project-owned equivalent. Default is docs/context/; engine/runtime knowledge is never target context.
34
34
 
35
35
  ```text
36
- node .cyc/engine/bin/cyc.mjs context review # every completed run no doc records yet
37
- node .cyc/engine/bin/cyc.mjs context review --run RUN_ID --write # append this run's entry and refresh INDEX.md
38
- node .cyc/engine/bin/cyc.mjs context review --since 2026-11-01 --write --new billing
36
+ node .cyc/engine/bin/cyc.mjs context prepare --run ID [--file CONTEXT.json]
37
+ node .cyc/engine/bin/cyc.mjs context review --run SOURCE_ID
38
+ node .cyc/engine/bin/cyc.mjs context review --run SOURCE_ID --write --update-run UPDATE_ID
39
39
  node .cyc/engine/bin/cyc.mjs context lint [--doc docs/context/orders.md]
40
- node .cyc/engine/bin/cyc.mjs context measure --path src/orders [--run RUN_ID]
40
+ node .cyc/engine/bin/cyc.mjs context measure --path src/orders [--run ID]
41
41
  ```
42
42
 
43
- `context review` maps each completed run's changed files (the final handoff's artifacts, with their SHA-256) to index rows through the same Covers patterns `investigate` uses, and proposes one entry per matched component doc from the run's own record: the Build summaries, the Deliver `learning` and `errorHistory` reasons, retry reasons, ledger entries that name the run, the test-proof claim or verdict and the verification results, the files, the date and the run ID. A field the run did not record is said to be missing, never invented. The proposal also says which component docs the run touched (`contextDocsTouched`, from the Deliver handoff) and which mapped docs it should have touched. It is read-only without `--write`; with it, the entry and lessons go in newest first, the `Last changed by AI` line is set, the index cells are refreshed (two columns are added to an older index), and the result is linted. It refuses a doc that lacks the layout, never edits a Current view, and does not write to reference rows whose link points outside `docs/context/`. `--new NAME` creates a doc for files no row covers; its Current view is a placeholder the lint reports until someone writes it.
43
+ 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.
44
44
 
45
- `context lint` names each violated rule with its line, compares every index row with its doc (Covers, last change, lesson count) and with Git: a covered path committed after the doc's last commit is `stale-against-git`, uncommitted edits to covered paths are `dirty`. `context measure` reports characters and estimated tokens (characters divided by four, no tokenizer) for the index plus the matched docs against every doc and against the run records (`state.json` and `review.md`); it cannot see a chat transcript, and a smaller read is not evidence that the next task succeeds with it. See the [context guide](context.md) for current usage and measurement limits.
45
+ 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).
46
46
 
47
47
  ## Register a reusable project tool
48
48
 
@@ -103,6 +103,10 @@ When repeated manual investigation or a user correction yields a useful command,
103
103
 
104
104
  ## Integration reasoning retained 2026-10-20
105
105
 
106
- `listRecipes` and `investigateProject` share `validateRecipeKind` and `recipesFor` in `scripts/project-tools.mjs`. Both validate kind at their public boundary and pass it as a separate recipe-helper argument. The context/evidence branch never uses kind. Reusing `selection` preserves explicit path precedence and the run's changed-path → declared-scope → goal fallback. `all` bypasses relevance, never kind. Registry validation still checks every entry before filtering, so an excluded invalid entry cannot be hidden by a kind request. Filtering precedes receipt enrichment and investigation recipe counts/truncation; returned command identities and receipt diagnostics retain their existing meaning.
106
+ listRecipes/investigateProject share validateRecipeKind/recipesFor; kind never alters context/freshness. Filtering precedes enrichment/counts/limits, preserves explicit-path precedence and validates the entire registry first. all bypasses relevance, not kind. Run node --test --test-name-pattern "investigate kind|recipe kind" test/project-tools.test.mjs or project-tools-contract for API/CLI/disposable-install coverage and unchanged fixture checks. Its investigate regressions failed on originals and passed after repair. This supersedes TOOLS-002's list-only scope; TOOLS-003 retains observed local evidence, not host activation or acceptance.
107
107
 
108
- Reusable checks: `node --test --test-name-pattern "investigate kind|recipe kind" test/project-tools.test.mjs` exercises CLI/API selection, invalid kinds, omission, recipe counts/limits, unchanged context/freshness and unchanged fixture bytes/directories. The existing `project-tools-contract` recipe also covers captured command IDs, receipt states and a disposable installed CLI. Tests live in the development checkout and are not shipped in the engine. The investigate regression checks failed on run-start code (ignored kind, wrong limited recipe and missing validation), then passed after the boundary extension. These checks establish local behavior, not host activation or human acceptance. The earlier list-only scope recorded in TOOLS-002 is superseded by this extension; TOOLS-003 records its regression evidence.
108
+ ## External browser recipes
109
+
110
+ A verification recipe may add browser:{prerequisiteFiles,viewports,journeys}. Each viewport names width/height; each journey has unique id, named state, actions and outcomes. scanState optionally chooses scanner state. Inspect existing preview/CSS/build prerequisites first. runRecipe accepts a driver bound to the host's actual supported open/act/observe/close handles and a separate scanner function. It never installs dependencies or instruments application layouts/configuration. CLI execution without capability returns one precise limited result and retained receipt; interruption is nonpassing.
111
+
112
+ Scanning uses a separate context. Batch independent observations only after known actions and explicit adapter permission. Declare proportional desktop/phone and applicable send/reload, empty/error, membership-loss, overflow, keyboard/history/focus checks. Observations and source/configuration stability remain distinct from command receipts and host activation. The development test/browser-recipe.test.mjs uses a separate Playwright/axe harness and seeded desktop/phone name/focus defects. Missing harness prerequisites are explicitly skipped, never repaired through app rewrites.
@@ -27,43 +27,17 @@ The reliable expansion commands are a standalone `expand` or `/cyc-expand` (opti
27
27
 
28
28
  ## Progress updates
29
29
 
30
- Help the engineer follow the work while it happens. Usually write one or two short paragraphs about one useful development: a concrete behavior, enough engineering detail to understand its cause, and the change or check that follows. Use the relevant parts naturally, not mandatory headings or a checklist in each message.
30
+ Usually give one or two readable paragraphs at a meaningful discovery or decision, and about every minute during long work. Explain the concrete behavior, relevant mechanism, evidence and next uncertainty. A command count, stage name or repeated reassurance is not a useful update. State observed failures separately from suspected causes. Before changing an assertion, explain the requested behavior that justifies it; never change a failing criterion merely to pass.
31
31
 
32
- - Make the symptom specific. If information was omitted, identify what was kept and what was lost using an observed example. Explain the mechanism in one plain-language sentence; name functions or files when they help the reader locate or assess it.
33
- - Explain consequential decisions and the behavior they protect. Share why a fix is narrow, why an approach changed, or what a test establishes. Avoid unexplained shorthand such as "pins green," incident IDs alone, or file counts as the whole update.
34
- - Match certainty to evidence. Label suspected causes, distinguish a planned check from its result, and preserve failures and unchecked behavior. Before changing a test expectation, explain the requested behavior that justifies it; an incident record alone does not establish correctness.
35
- - Update at meaningful discoveries, changes of approach, and verification results. During longer work, provide a useful update about every minute: what is being checked, what remains unknown, and what the result will resolve. Do not invent progress, repeat reassurance, or narrate each command.
36
-
37
- Illustrative update, not a diagnosis of a real project:
38
-
39
- > The app saved "Improved processing" but dropped "from four hours to one." The code that interprets corrections treated the replacement sentence as a complaint, so it asked another question instead of saving the supplied wording.
40
- >
41
- > I'm adjusting that decision so explicit replacements are saved, while vague complaints still ask for clarification. I'll test both paths to check that we fix the omission without making the app guess what someone meant.
42
-
43
- Use only details supported by the actual task; do not reuse the example as evidence. Routine work may need less explanation. Expand when a consequential decision needs it or the user asks to learn more. Keep deeper evidence in the existing run records or relevant artifacts, without requiring extra documents for every update.
44
-
45
- These are shared instructions for the orchestrator and supporting methods, not a new stage or a requirement to pause work. Progress messages do not require the final response's visual or character cap. The completion hook does not measure their clarity or enforce their cadence. Review the next live trial for both engineering comprehension and readability; structural checks alone cannot establish either.
32
+ For long commands, prefer the returned bounded operation handle and latest actual output. No output is silence, not progress or success. Keep setup/host limits separate from product defects. User interruption is not verification. Progress text has no final-response length/visual gate; clarity is a judgment, not a controller-certified property.
46
33
 
47
34
  ## Engineering understanding throughout the work
48
35
 
49
- Help the engineer build a usable picture of the system as the work proceeds. A status update says what the agent is doing; an engineering explanation connects behavior to its cause, the chosen change, and the evidence. Share that explanation at the relevant moment, not only in the initial plan or final handoff. Communication is part of every stage, even when the engineer did not request a separate lesson.
36
+ Help the engineer follow cause and effect while decisions are still useful: trace authoritative state and consumers in Scout, connect the implementation to that contract in Build, explain what a failure disproved during recovery, and connect each decisive check to its practical limits in Verify. Deliver a usable result, maintenance pointer and material limitations. Use the relevant moments naturally; these are not six additional stages or documents.
50
37
 
51
- Plain language must preserve engineering substance. Labels such as "validate," "use context," or "retry" are not explanations on their own. Name the relevant state, interface, dependency, or assumption; explain its effect on behavior and the evidence supporting the conclusion. When work loops back, state what failed, why that invalidates an implementation or earlier decision, what remains valid, and which evidence must be established again. Describe a trust claim through the actual check or review record and its limits. Use enough detail for the engineer to evaluate the reasoning; brevity must not erase the causal connection. The [detailed workflow](cyc-workflow.md) demonstrates this distinction.
38
+ Use plain language without erasing technical substance. Name a function/interface when it helps locate the issue. Explain consequential choices and rejection/recovery behavior; skip generic lectures, mandatory quizzes and invented user approval. Match depth to the actual question. Keep lasting context in existing run/handoff artifacts rather than a parallel teaching report. The [Teach method](../methods/cyc-teach/SKILL.md) supports requested lessons.
52
39
 
53
- | Moment | Understanding to support | What to explain from the actual work |
54
- | --- | --- | --- |
55
- | Scout: establish the system | How does this behavior happen today? | Trace the relevant request, data, state, or dependency through the affected components. Explain which historical decision or failed attempt changes today's approach, after checking freshness. |
56
- | Scout: choose and align | Why this approach, and what does it cost? | Connect the proposed change to the goal, explain a meaningful alternative or trade-off when one exists, and identify behavior that must remain intact. Resolve consequential ambiguity before relying on it. |
57
- | Build: implement a meaningful slice | How does this change reach the places that depend on it? | Explain the affected reader/writer, boundary, or contract and why the change belongs there. Show a small before/after or flow when that clarifies the mechanism. |
58
- | Recovery: a failure changes the plan | What did this failure teach us? | Separate the observation from the suspected cause. Name the assumption being tested, what evidence ruled out, and how the next check distinguishes remaining possibilities. Preserve failed evidence in the ledger. |
59
- | Verify: interpret the evidence | What can we now conclude, and what remains uncertain? | Connect checks to the behavior and affected consumers they exercise. Explain an important rejected case or regression guard, and separate executed results from semantic judgment. |
60
- | Deliver: support maintenance | How can the engineer review, debug, or extend this later? | Give the concise before/after mechanism, the consequential trade-off, and where the relevant check and retained context live. Include a useful maintenance implication when one exists. |
61
-
62
- Use the rows that matter to this task; they are not six required messages or a script to repeat. Combine explanations for a small change. For substantial work, deliver them when the engineer can still question a decision. A report saved at the end does not substitute for explaining a changed approach while it happens. Reuse the existing handoff summary and assessment evidence for lasting reasoning; do not create a parallel teaching report or claim the controller checks explanation quality.
63
-
64
- Match the depth to the engineer's demonstrated familiarity and requested detail. Define an unfamiliar term through its effect in their project; name exact components when it helps them inspect the reasoning. Avoid lectures about concepts they already use. If they signal confusion, explain the missing connection with a concrete example and update the plan if their correction reveals a misunderstanding. Do not infer comprehension or approval from silence. Keep ordinary work moving unless an actual decision or prerequisite is missing. Use the [Teach method](../methods/cyc-teach/SKILL.md) for requested lessons or practice; routine implementation does not require quizzes or learner participation.
65
-
66
- Before delivery, self-review whether an engineer could locate the affected path, follow the consequential choice, understand why the checks matter, and find the retained explanation. Repair missing explanations concisely; do not invent user understanding. Distinguish **explanation supplied** from **understanding demonstrated**: only the engineer's own reasoning, correction, or application can provide evidence of the latter, and only within what was observed. These are qualitative review criteria, not a new machine-enforced completion gate.
40
+ Before delivery, check whether a reader can locate the affected path, follow the consequential choice, understand why the checks matter and find retained evidence. Repair missing explanations. Distinguish explanation supplied from understanding demonstrated: only the engineer's observed reasoning, correction or application supports the latter. A controller pass, fingerprint or agent review does not prove understanding or product correctness.
67
41
 
68
42
  ## Character-limit toggle
69
43
 
@@ -98,7 +72,9 @@ Only a ready handoff may describe work as complete. It must clear all three leve
98
72
 
99
73
  The UserPromptSubmit hook supplies a local packet path and a fresh token. Write a review to that path before finishing. The token prevents a packet from an earlier request from being reused.
100
74
 
101
- In Claude Code and Codex, a completed `run finish` writes the packet itself, from the run's record: one check per criterion with the evidence the agent gave, the hashes of the files the run changed, and `writtenBy: "run finish"` with the run's ID. It claims nothing about the reply, so it has no `humanReview`, and a revised reply after a rejected Stop needs no new packet. The Stop gate still checks the reply's length, visual and blocked prefix, and accepts the packet only if every run it names completed in this request for this session the writer named by `runId` recorded that exact packet, and no later finish in the request wrote another, so a hand-written packet that only claims `writtenBy: "run finish"` is refused. A second run finished in the same request adds its checks and files. The agent writes the packet with `cyc packet` when no run completed (a blocked run, an advisory change), when files changed after finish (the listed hashes then no longer match), and always in Cursor. The four human-readiness questions remain the agent's to answer before sending; only the separate affirmation step is gone for finish-written packets. In Claude Code and Codex, the Stop event carries the final reply, so the gate checks that reply's length, visual, and blocked-handoff prefix itself, and the packet need not copy it. A packet that does include `response` must match the reply exactly. Cursor's stop event has no reply text, so its packets always include the exact response. Do not paste this packet into the user-facing answer.
75
+ Native Claude/Codex finish generates the request-bound packet from the canonical run evidence, without claiming human review of the reply. Stop still checks length, visual and blocked prefix. It accepts a finish packet only when every named run completed in this request for this session, the writer recorded its exact digest, and no later finish superseded it. Multiple completed runs retain compatible checks/files. A forged writtenBy label cannot substitute. If response is included it must match exactly; Cursor requires it because Stop lacks reply text. Explicit mode selects capability, never a session string's length.
76
+
77
+ Authorized standalone finish writes run-local delivery.json with hook activation unverified and product readiness uncertified. It cannot downgrade a live native request or fabricate its state/token. Native manual packets remain for advisory/blocked work or source changes after finish; Cursor uses its explicit exact-response packet. Reread the final reply for all four human-readiness questions even when finish generated the packet. Never paste packet bookkeeping into the final answer.
102
78
 
103
79
  For code changes, include the decisive regression's exact name or precise review location with its command and result. A count alone leaves a reviewer searching for the assertion. Conversation-only work does not need an invented regression. Codex/Claude packet preflight also checks the current hook request's controller statuses; a completed latest run cannot hide a stopped original. Use `cyc readiness --session ID` for diagnosis. Explicit `--since` windows and Cursor-tag diagnostics remain separate from live host enforcement.
104
80