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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/README.md +1 -1
- package/bin/cyc.mjs +35 -20
- package/docs/context.md +10 -26
- package/docs/project-tools.md +14 -10
- package/docs/response-standard.md +8 -32
- package/docs/runtime.md +58 -174
- package/docs/work-assessments.md +25 -92
- package/methods/cyc-build/SKILL.md +1 -1
- package/methods/cyc-challenge/SKILL.md +4 -0
- package/methods/cyc-context/SKILL.md +18 -53
- package/methods/cyc-context/references/evidence.md +1 -1
- package/methods/cyc-context/references/templates.md +4 -11
- package/methods/cyc-deliver/SKILL.md +2 -2
- package/methods/cyc-remember/SKILL.md +1 -1
- package/methods/cyc-scout/SKILL.md +17 -51
- package/methods/cyc-verify/SKILL.md +15 -66
- package/methods/cyc-verify/references/recipe.md +2 -0
- package/package.json +4 -1
- package/plugin.json +1 -1
- package/rules/cyc-delivery.mdc +33 -33
- package/scripts/browser-audit.mjs +53 -0
- package/scripts/context-review.mjs +202 -29
- package/scripts/execution.mjs +51 -0
- package/scripts/packet.mjs +21 -6
- package/scripts/project-tools.mjs +18 -16
- package/scripts/run-worker.mjs +4 -0
- package/scripts/runtime.mjs +482 -65
- package/scripts/work-review.mjs +32 -10
- package/skills/cyc/SKILL.md +24 -71
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
|
|
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’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 (
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
7
|
+
## Normal workflow
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
20
|
+
## Evidence limits
|
|
37
21
|
|
|
38
|
-
|
|
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
|
-
|
|
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.
|
package/docs/project-tools.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
37
|
-
node .cyc/engine/bin/cyc.mjs context review --run
|
|
38
|
-
node .cyc/engine/bin/cyc.mjs context review --
|
|
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
|
|
40
|
+
node .cyc/engine/bin/cyc.mjs context measure --path src/orders [--run ID]
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|