cyc-stack 0.6.0 → 0.7.1

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.
@@ -256,3 +256,13 @@ export function testsOf(result) {
256
256
 
257
257
  // Output whose earlier lines were dropped, with no complete summary to stand in for them.
258
258
  export const cutOff = result => result?.tests ? !result.tests.complete : [result?.stdout, result?.stderr].some(stream => (stream ?? '').length >= outputLimit);
259
+
260
+ // Diagnostic hints only. A TypeError or load failure can itself be the real old bug;
261
+ // only a case-specific reason review can establish the meaning of a failure.
262
+ export function failureHint(entry) {
263
+ const error = `${entry.error ?? ''}\n${(entry.details ?? []).join('\n')}`;
264
+ if (/ERR_MODULE_NOT_FOUND|Cannot find (?:module|package)|does not provide an export|ModuleNotFoundError/.test(error)) return 'module-load';
265
+ if (/AssertionError|ERR_ASSERTION|assertion failed|Expected:|expected .* to /i.test(error)) return 'assertion';
266
+ if (/timeout|timed out|ENOENT|ECONNREFUSED/.test(error)) return 'execution-or-setup';
267
+ return 'unclassified';
268
+ }
@@ -1,3 +1,5 @@
1
+ import { digest } from './response-gate.mjs';
2
+
1
3
  // These checks establish recorded process evidence, not the truth of an agent's judgment.
2
4
  const text = value => typeof value === 'string' && value.trim().length > 0;
3
5
  const object = value => value && typeof value === 'object' && !Array.isArray(value);
@@ -7,7 +9,35 @@ export const reviewPath = state => `.cyc/runs/${state.id}/review.md`;
7
9
 
8
10
  export function assessmentRequirements(state, stage) {
9
11
  if (state.workContractVersion !== 1) return [];
10
- return ({ scout: ['context', 'approach', 'alignment', 'consumers'], verify: ['semanticReview', 'consumerChecks'], deliver: ['learning', 'errorHistory'] })[stage] ?? [];
12
+ const keys = ({ scout: ['context', 'approach', 'alignment', 'consumers'], verify: ['semanticReview', 'consumerChecks'], deliver: ['learning', 'errorHistory'] })[stage] ?? [];
13
+ return stage === 'verify' && state.evidenceVersion === 1 ? [...keys, 'criterionChecks'] : keys;
14
+ }
15
+
16
+ export const criterionClauses = state => state.criteria.flatMap(c => (c.clauses ?? [{ id: undefined }]).map(clause => ({ id: c.id, clause: clause.id })));
17
+
18
+ // Coverage records describe source provenance. They do not attest reviewer independence.
19
+ export function reviewCoverage(state, review, sourceHash) {
20
+ const refs = review?.receipts ?? [];
21
+ const entries = refs.map(id => (state.reviewReceipts ?? []).find(r => r.id === id));
22
+ if (!entries.length) return { status: review?.reviewer === 'self' ? 'self-assessment' : 'unlinked', entries: [] };
23
+ const stale = entries.some(r => !r || r.status !== 'recorded' || r.sourceHash !== sourceHash || r.criteriaHash !== (state.criteriaHash ?? digest(JSON.stringify(state.criteria))));
24
+ const kinds = new Set(entries.filter(Boolean).map(r => r.reviewer));
25
+ return { status: stale ? 'stale' : kinds.size > 1 ? 'mixed' : 'source-linked', entries };
26
+ }
27
+
28
+ export function validateProofReview(state, review) {
29
+ if (state.evidenceVersion !== 1 || !state.testProof?.passed || state.testProof.mode === 'green') return;
30
+ if (!object(review) || !Array.isArray(review.cases) || !review.cases.length) throw new Error('Diagnostic red needs proofReview.cases with a reason review of decisive failures; run prove-red first.');
31
+ if (!['current-proof', state.testProof.receiptPath].includes(review.receipt)) throw new Error('proofReview must reference the current proof receipt.');
32
+ if (new Set(review.cases.map(c => c?.id)).size !== review.cases.length) throw new Error('proofReview case ids must be unique.');
33
+ for (const item of review.cases) {
34
+ if (!state.testProof.failures?.some(f => f.id === item?.id)) throw new Error(`Unknown proof failure ${item?.id}.`);
35
+ requireChoice(item.category, ['behavioral', 'new-interface', 'setup', 'unclassified'], 'Proof category');
36
+ requireText(item.reason, 'Proof reason');
37
+ if (item.category === 'behavioral') requireText(item.boundary, 'Existing observable boundary');
38
+ }
39
+ const decisive = state.playbook === 'bug-fix' ? ['behavioral'] : ['behavioral', 'new-interface'];
40
+ if (!review.cases.some(c => decisive.includes(c.category))) throw new Error('No decisive behavioral proof for this bug fix (features may prove a new interface); setup and unclassified failures remain diagnostic.');
11
41
  }
12
42
 
13
43
  // Fields the controller records when the agent leaves them out, limited to what its own record
@@ -40,6 +70,7 @@ export function assessmentTemplate(state, stage) {
40
70
  consumers: [{ id: 'direct', description: '<the behavior you are changing>', check: '<how you will verify it>' }],
41
71
  semanticReview: { reviewer: 'self | fresh-context | peer', intent: '<does the diff do what was asked, nothing more>', consumers: '<are dependents still correct>', conventions: '<does it match project style>', findings: [] },
42
72
  consumerChecks: (scoutConsumers.length ? scoutConsumers : [{ id: 'direct' }]).map(item => ({ id: item.id, result: 'passed', evidence: '<the command or observation that showed it works>' })),
73
+ criterionChecks: criterionClauses(state).map(item => ({ ...item, scenario: '<named scenario for this original outcome/clause>', check: '<configured command id>', receipt: 'current-verification', result: 'passed', origin: 'agent-reported', evidence: '<what this scenario established; not a suite count>' })),
43
74
  learning: { status: 'none | recorded | pending-acceptance', reason: '<why nothing is reusable, or what was recorded>', artifacts: [] },
44
75
  errorHistory: { status: state.playbook === 'bug-fix' || state.failures > 0 ? 'recorded' : 'none | recorded', reason: '<what failed and how it was resolved, or why there was no error>', artifacts: state.playbook === 'bug-fix' || state.failures > 0 ? [state.ledgerPath ?? 'docs/context/error-ledger.md'] : [] }
45
76
  };
@@ -137,7 +168,8 @@ export function validateAssessment(state, packet, fingerprint) {
137
168
  requireChoice(semanticReview?.reviewer, ['self', 'fresh-context', 'peer'], 'semanticReview.reviewer');
138
169
  for (const axis of ['intent', 'consumers', 'conventions']) requireText(semanticReview[axis], `Semantic review ${axis}`);
139
170
  if (!Array.isArray(semanticReview.findings)) throw new Error('Semantic review needs findings (an empty array means no findings).');
140
- if (new Set(semanticReview.findings.map(item => item?.id)).size !== semanticReview.findings.length) throw new Error(`Review finding ids must be unique. ${findingShape}`);
171
+ const findingKey = item => state.evidenceVersion === 1 ? JSON.stringify([item?.reviewId ?? null, item?.id]) : item?.id;
172
+ if (new Set(semanticReview.findings.map(findingKey)).size !== semanticReview.findings.length) throw new Error(`Review finding ids must be unique within their receipt scope. ${findingShape}`);
141
173
  for (const finding of semanticReview.findings) {
142
174
  try {
143
175
  requireText(finding?.id, 'Finding id');
@@ -156,6 +188,26 @@ export function validateAssessment(state, packet, fingerprint) {
156
188
  requireText(check.evidence, 'Consumer check result');
157
189
  if (check.result !== 'passed') throw new Error(`Consumer ${check.id} is not verified; repair or record a blocked handoff.`);
158
190
  }
191
+ if (state.evidenceVersion === 1) {
192
+ const checks = assessment.criterionChecks;
193
+ if (!Array.isArray(checks)) throw new Error('criterionChecks needs original outcome/clause scenarios.');
194
+ const key = c => JSON.stringify([c?.id, c?.clause ?? null]);
195
+ const expected = criterionClauses(state);
196
+ if (new Set(checks.map(key)).size !== checks.length) throw new Error('Duplicate criterion/clause check.');
197
+ for (const c of expected) if (!checks.some(item => key(item) === key(c))) throw new Error(`Missing scenario for ${c.id}${c.clause ? `/${c.clause}` : ''}.`);
198
+ for (const check of checks) {
199
+ if (!expected.some(c => key(c) === key(check))) throw new Error(`Unknown criterion/clause ${check?.id}/${check?.clause}.`);
200
+ requireText(check.scenario, 'Criterion scenario'); requireText(check.evidence, 'Scenario observation');
201
+ if (!state.commands?.some(c => c.id === check.check)) throw new Error(`Unknown configured check ${check.check}.`);
202
+ if (check.result !== 'passed') throw new Error(`Criterion ${check.id} is unverified; repair or record a blocked handoff.`);
203
+ if (check.origin !== 'agent-reported') throw new Error('Scenario results are agent-reported; command success alone does not establish a named assertion.');
204
+ requireText(check.receipt, 'Scenario receipt');
205
+ }
206
+ if (semanticReview.reviewer !== 'self' && !semanticReview.receipts?.length) throw new Error('Fresh/peer review needs source-linked review receipts, not a reviewer label alone.');
207
+ if (semanticReview.receipts !== undefined && (!Array.isArray(semanticReview.receipts) || new Set(semanticReview.receipts).size !== semanticReview.receipts.length)) throw new Error('Review receipts need unique ids.');
208
+ // The runtime performs source and receipt-byte checks with the actual snapshot.
209
+ if (!assessment.testProof?.status || assessment.testProof.status !== 'exempt') validateProofReview(state, assessment.proofReview);
210
+ }
159
211
  }
160
212
  if (packet.stage === 'deliver') {
161
213
  for (const name of ['learning', 'errorHistory']) {
@@ -202,6 +254,10 @@ export function renderReview(state, currentSourceHash, artifactIssues = []) {
202
254
  for (const criterion of state.criteria) {
203
255
  const result = (delivery ?? verification)?.criteria.find(item => item.id === criterion.id);
204
256
  lines.push(`| ${safe(criterion.description)} | ${safe(result ? (!evidenceCurrent ? 'stale / unverified' : result.result) : 'unverified')} | ${safe(result?.evidence ?? 'Not yet established')} |`);
257
+ for (const clause of criterion.clauses ?? []) {
258
+ const check = verification?.assessment?.criterionChecks?.find(c => c.id === criterion.id && c.clause === clause.id);
259
+ lines.push(`| ${safe(criterion.id)}/${safe(clause.id)}: ${safe(clause.description)} | ${check && evidenceCurrent ? safe(check.result) : 'unverified'} | ${check ? `${safe(check.scenario)} — ${safe(check.evidence)} (agent-reported)` : 'No scenario evidence recorded'} |`);
260
+ }
205
261
  }
206
262
  lines.push('', '## Context, approach, and alignment', '');
207
263
  if (scout) {
@@ -225,11 +281,24 @@ export function renderReview(state, currentSourceHash, artifactIssues = []) {
225
281
  else if (['bug-fix', 'feature', 'refactor'].includes(state.playbook) && state.base === null) lines.push('Test proof: unavailable (this older run has no Git base or run-start source capture).');
226
282
  const assessment = state.workContractVersion === 1 ? verification?.assessment : null;
227
283
  if (assessment) {
228
- lines.push(`Semantic review: ${semanticCurrent ? 'current' : 'stale'}; reviewer: ${safe(assessment.semanticReview.reviewer)}.`);
284
+ const coverage = reviewCoverage(state, assessment.semanticReview, currentSourceHash);
285
+ if (coverage.entries.length && artifactIssues.length) coverage.status = 'unverified (receipt/evidence unavailable)';
286
+ const reviewers = coverage.entries.length ? [...new Set(coverage.entries.filter(Boolean).map(r => r.reviewer))].join(' + ') : assessment.semanticReview.reviewer;
287
+ lines.push(`Semantic review: ${coverage.status === 'self-assessment' ? (semanticCurrent ? 'current' : 'stale') : coverage.status}; reviewer: ${safe(reviewers)}; provenance: agent-reported. Final assessment: ${semanticCurrent ? 'current' : 'stale'}.`);
288
+ for (const receipt of coverage.entries) lines.push(receipt ? `- Review ${safe(receipt.id)}: ${safe(receipt.reviewer)}, ${receipt.sourceHash === currentSourceHash ? 'matching source' : 'stale source'}; scope: ${safe(receipt.scope.length ? receipt.scope.join(', ') : 'whole covered source')}; identity: ${safe(receipt.identity ?? 'unknown')}; evidence: ${safe(receipt.path)}.` : '- Review receipt missing.');
289
+ if (state.evidenceVersion === 1) {
290
+ lines.push(`Original requirements: ${safe(state.requirements.sha256)}. Scenario observations below are agent-reported, not automatically verified named runner results.`);
291
+ for (const criterion of state.criteria) for (const clause of criterion.clauses ?? []) lines.push(`- Original clause ${safe(criterion.id)}/${safe(clause.id)}: ${safe(clause.description)}`);
292
+ for (const check of assessment.criterionChecks ?? []) lines.push(`- Outcome ${safe(check.id)}${check.clause ? `/${safe(check.clause)}` : ''}: ${evidenceCurrent ? safe(check.result) : 'stale / unverified'} — ${safe(check.scenario)}; check ${safe(check.check)}, receipt ${safe(check.receipt)}; ${safe(check.evidence)}`);
293
+ }
294
+ for (const failure of proof?.failures ?? []) {
295
+ const reason = assessment.proofReview?.cases?.find(c => c.id === failure.id);
296
+ lines.push(`- Baseline failure ${safe(failure.id)}: ${safe(failure.name)} — ${safe(reason?.category ?? 'unclassified')}; hint: ${safe(failure.hint)}. ${safe(reason?.reason ?? 'No semantic reason review recorded.')} ${reason?.boundary ? `Boundary: ${safe(reason.boundary)}.` : ''}`);
297
+ }
229
298
  for (const axis of ['intent', 'consumers', 'conventions']) lines.push(`- ${axis}: ${safe(assessment.semanticReview[axis])}`);
230
299
  for (const check of assessment.consumerChecks) lines.push(`- Consumer ${safe(check.id)}: ${safe(check.result)} — ${safe(check.evidence)}`);
231
300
  if (!assessment.semanticReview.findings.length) lines.push('- No semantic findings recorded.');
232
- for (const finding of assessment.semanticReview.findings) lines.push(`- ${safe(finding.id)} (${safe(finding.status)}): ${safe(finding.evidence)}`);
301
+ for (const finding of assessment.semanticReview.findings) lines.push(`- ${finding.reviewId ? `${safe(finding.reviewId)}/` : ''}${safe(finding.id)} (${safe(finding.status)}): ${safe(finding.evidence)}`);
233
302
  } else lines.push('No passing semantic-review assessment recorded.');
234
303
  lines.push('', '## Learning and error history', '');
235
304
  lines.push(`Project ledger lookup: ${safe(state.projectLedgerPath ?? state.ledgerPath ?? 'not captured')}. Error history target: ${safe(state.ledgerPath ?? 'not captured')}.`);
@@ -23,7 +23,8 @@ scout → build → verify ⟲ repair within budget → deliver → reply
23
23
 
24
24
  1. **Scout.** Pick the playbook from the table below (usually `feature` or `bug-fix`) and open its page. Read the project's context index first, `docs/context/INDEX.md`, and then only the component docs whose Covers match the paths you will touch (`node <cli> investigate --path <paths>` does the match and checks their evidence), plus the error ledger for that area; each row's `Last AI change` and `Lessons` cells say whether the doc is worth opening. Do not read every doc, and do not start from the code when a matched doc exists. Then follow [Scout](../../methods/cyc-scout/SKILL.md): focused searches, matched component history and ledger lookup, freshness checks, and a short plan. Identify existing functionality and choose reuse, extend, repair, or create. Explain consequential behavior changes and trade-offs; ask only for unresolved decisions that affect the solution. Fill every field with what you found; unedited placeholders are rejected. Aim for a first useful edit within a couple of minutes without skipping critical unknowns.
25
25
  2. **Start the run with its plan.** Save a JSON object under `.cyc/runtime/` with these fields:
26
- - `goal`, `playbook`, `criteria` (`[{"id":"c1","description":"..."}]`), `allowedPaths`, and `session`;
26
+ - `goal`, `playbook`, `criteria` (`[{"id":"c1","description":"..."}]`, with optional unique `clauses: [{"id":"...","description":"..."}]`), `allowedPaths`, and `session`;
27
+ - `evidenceVersion: 1` and `requirements`: the original authorized outcome text, kept separately from the short plan. Preserve every original outcome ID and material clause. Use `reviewPolicy: "fresh-required"` for high-risk work when a fresh reviewer is available; otherwise select `"self-allowed"` and disclose the actual fallback. Unversioned inputs remain the compatibility interface for older clients, not the updated workflow;
27
28
  - `plan`: one or two sentences;
28
29
  - `scout`: `{"context":{"status":"used|none","evidence":"...","freshness":"...","sources":[]},"approach":{"kind":"reuse|extend|repair|create","evidence":"..."},"alignment":{"status":"clear|confirmed","evidence":"..."},"consumers":[{"id":"direct","description":"...","check":"..."}]}`. `context.sources` are matched history (context docs, decisions, ledger entries); with `status: "none"`, list the code you read as `context.read` instead. Omit `context` only when the project has no `docs/context/INDEX.md` and no ledger: the controller then records that there was no history to consult.
29
30
 
@@ -35,6 +36,7 @@ scout → build → verify ⟲ repair within budget → deliver → reply
35
36
  3. **Build.** Follow [Build](../../methods/cyc-build/SKILL.md). Work in small slices: features and bug fixes use red then green; refactors keep characterization tests green on original and candidate code. Keep named consumers consistent. Record failed fixes in the selected ledger immediately, with evidence and the next hypothesis; if `run next`'s `ledgerPath` does not exist yet, create it in the [entry format](../../methods/cyc-error-ledger/references/entry-format.md). Reread the diff and fix shortfalls. `run finish` records Build and lists the files you changed; `run record` remains for step-by-step work. Finalize authorized context/index and ledger edits before final verification. Verified facts keep their evidence and limits; unverified hypotheses and undecided proposals stay labeled in run-local notes.
36
37
  4. **Prove, verify, and deliver in one call.** Use [Verify](../../methods/cyc-verify/SKILL.md)'s applicable checks: task criteria, affected consumers, rejected cases, and the real journey/recipe.
37
38
  - **Test proof.** New regression tests must detect the original defect. `run finish` runs `prove-red` itself when the proof is missing or outdated: tests for bug fixes and features must fail on the run-start code, and refactor tests must pass on it. A change with no testable behavior records `testProof: {"status":"exempt","reason":"..."}`, in FINISH.json or its assessment. With TAP (`node --test`, `tap`), mocha, or jest output, the proof names the new tests that fail on the original code, including output longer than the 32,000 characters kept. It does so even when an older test in the same suite already failed there, because it compares failing test names. Other output gives a per-check result: at least one new test fails on the original. In `criterionEvidence` and the reply, say a specific case failed before the fix only if the proof named it or you ran it on the original code yourself. Otherwise quote `proofClaim` from the finish result.
39
+ - **Versioned evidence.** For `evidenceVersion: 1`, fill `criterionChecks` from the template: one named scenario/observation per original criterion or clause, its configured `check`, `receipt: "current-verification"`, `result: "passed"`, `origin: "agent-reported"`, and actual evidence. The controller binds the command receipt after verification; it does not claim to have observed a named passing assertion. Run `prove-red` before finalizing a non-exempt proof and add `proofReview` using the returned failure IDs, categories, reasons and existing boundary for behavioral claims. See [versioned evidence](../../docs/work-assessments.md#versioned-evidence-records).
38
40
  - **Review.** Review the current diff against the senior bar below for intent, consumers, and conventions, and resolve or justify dismissing every finding. Tests alone cannot replace review. Each finding is `{"id":"f1","status":"resolved|dismissed|open","evidence":"<how it was resolved, or why it is dismissed>"}`; an open finding blocks verification.
39
41
  - **Finish.** Copy `finishTemplate` to `FINISH.json` and replace every `<...>` with what you found: `summary`, `assessment`, `criterionEvidence` (each criterion ID mapped to its evidence), and `acceptFailures` (see below). The template asks only for what you must judge: `errorHistory` appears for bug fixes, and `learning` is yours to add when you recorded something reusable. Left out, the controller records none and says so. If the template lists an `acceptFailures` entry, that check already failed in the project's run-start baseline: replace its reason with why it is unrelated, or delete the entry and fix the check. Placeholders left in are refused. Add `artifacts` only to override the changed-file list. Run `run finish --file FINISH.json`; the [input examples](../../docs/runtime.md#structured-input-without-shell-quoting) show the envelope. It records Build if needed, proves the new tests, runs the configured checks, records both stages, and completes the run. It refuses an incomplete assessment before running anything.
40
42
  - **If the proof or a check fails**, finish stops and says which. Read the receipt, then run `run retry --stage build --reason "<what the failure showed>"` before editing, so the repair is recorded as a build artifact. Do not rerun checks on unchanged files to reproduce a failure, because repeated identical failures exhaust the run.
@@ -85,7 +87,7 @@ Every change is judged as a senior reviewer would. The [engineering principles](
85
87
  The quality bar is always the highest. Only the process scales:
86
88
 
87
89
  - **Normal:** the flow above.
88
- - **High risk** (auth, permissions, payments, data migrations, deletes, public APIs): run one focused [Challenge](../../methods/cyc-challenge/SKILL.md) pass on the plan before building. Before finishing, get a fresh-context review when the host can start a subagent: give it only the diff, the criteria, and the [principles](../../docs/principles.md), never your reasoning, and ask for findings it can demonstrate. Resolve or dismiss each with evidence and record `reviewer: "fresh-context"`. If no subagent is available, record `self` and say so in the reply. Use additional agents only for specific independent questions that warrant them.
90
+ - **High risk** (auth, permissions, payments, data migrations, deletes, public APIs): run one focused [Challenge](../../methods/cyc-challenge/SKILL.md) pass on the plan before building. Before finishing, get a fresh-context review when the host can start a subagent: give it the diff, the original criteria, the [principles](../../docs/principles.md), and paths to the affected data contracts and existing producers/consumers; omit your implementation rationale, and ask for findings it can demonstrate. Resolve or dismiss each with evidence and record `reviewer: "fresh-context"`. If no subagent is available, record `self` and say so in the reply. Use additional agents only for specific independent questions that warrant them. Capture a review before dispatch with `run review-capture --run ID --file CAPTURE.json` (`{"reviewer":"fresh-context","scope":["affected/path"]}`; omit scope for whole covered source). After the actual review, call `run review-record --run ID --file REVIEW.json` with `reviewId`, review `evidence`, `findings` and observable `identity` or null. Put the returned ID in `semanticReview.receipts`. Record self/peer scopes the same way when combining coverage. These are agent-reported provenance records, not identity attestation. Record the source and scope actually reviewed. After later changes, review the affected delta or identify that coverage as self-reviewed or unverified; do not describe mixed coverage as a fresh review of the entire final candidate. A matching source fingerprint establishes which bytes were reviewed, not that the code is correct.
89
91
 
90
92
  ## When things go wrong
91
93
 
@@ -1,13 +0,0 @@
1
- import { readFileSync } from 'node:fs';
2
- import { resolve } from 'node:path';
3
- import { checkResponse } from './response-gate.mjs';
4
-
5
- try {
6
- const packet = JSON.parse(readFileSync(process.argv[2], 'utf8'));
7
- const issues = checkResponse({ response: packet.response, packet, token: packet.token, root: resolve('.'), expanded: process.argv.includes('--expanded') });
8
- console.log(JSON.stringify({ accepted: issues.length === 0, issues }, null, 2));
9
- process.exitCode = issues.length ? 1 : 0;
10
- } catch (error) {
11
- console.error(`Cannot check response: ${error.message}`);
12
- process.exitCode = 1;
13
- }