cyc-stack 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/README.md +25 -254
  5. package/bin/cyc.mjs +61 -23
  6. package/docs/assets/cyc-method-library.svg +1 -39
  7. package/docs/assets/cyc-overview.svg +1 -44
  8. package/docs/assets/cyc-workflow-diagram.svg +1 -415
  9. package/docs/context.md +13 -23
  10. package/docs/cyc-workflow.md +31 -84
  11. package/docs/installation.md +66 -124
  12. package/docs/onboarding-recovery.md +31 -37
  13. package/docs/project-tools.md +16 -10
  14. package/docs/response-standard.md +16 -32
  15. package/docs/runtime.md +22 -224
  16. package/docs/skill-contract.md +13 -56
  17. package/docs/task-context.md +56 -0
  18. package/docs/validation.md +2 -0
  19. package/docs/work-assessments.md +25 -92
  20. package/methods/cyc-build/SKILL.md +8 -53
  21. package/methods/cyc-challenge/SKILL.md +4 -0
  22. package/methods/cyc-context/SKILL.md +20 -53
  23. package/methods/cyc-context/references/evidence.md +1 -1
  24. package/methods/cyc-context/references/templates.md +4 -11
  25. package/methods/cyc-deliver/SKILL.md +6 -42
  26. package/methods/cyc-remember/SKILL.md +1 -1
  27. package/methods/cyc-scout/SKILL.md +17 -51
  28. package/methods/cyc-setup/SKILL.md +7 -19
  29. package/methods/cyc-verify/SKILL.md +15 -66
  30. package/methods/cyc-verify/references/recipe.md +2 -0
  31. package/package.json +9 -1
  32. package/plugin.json +1 -1
  33. package/rules/cyc-delivery.mdc +33 -33
  34. package/scripts/browser-audit.mjs +53 -0
  35. package/scripts/catalog.mjs +9 -2
  36. package/scripts/codex-host.mjs +178 -0
  37. package/scripts/context-review.mjs +212 -29
  38. package/scripts/delegation.mjs +156 -0
  39. package/scripts/execution.mjs +51 -0
  40. package/scripts/onboarding.mjs +14 -1
  41. package/scripts/packet.mjs +21 -6
  42. package/scripts/project-tools.mjs +43 -20
  43. package/scripts/recovery.mjs +20 -1
  44. package/scripts/response-mode.mjs +8 -0
  45. package/scripts/run-worker.mjs +4 -0
  46. package/scripts/runtime.mjs +648 -68
  47. package/scripts/swarm.mjs +154 -0
  48. package/scripts/task-context.mjs +164 -0
  49. package/scripts/work-review.mjs +32 -10
  50. package/skills/cyc/SKILL.md +29 -70
@@ -0,0 +1,56 @@
1
+ # Unified task context and delegation
2
+
3
+ state.json renders .cyc/runs/<runId>/context.md; no worker context files.
4
+
5
+ ## Start and route
6
+
7
+ Optional frozen policy:
8
+
9
+ ```json
10
+ {"delegation":{"version":1,"mode":"auto","maxWorkers":2,"maxAssignments":4}}
11
+ ```
12
+
13
+ Modes: recommend (default), auto, off. Optional taskContext {version:1,maxBytes:24576} bounds the view.
14
+
15
+ Auto defaults to two workers; explicit one selects solo. delegate swarm {version:1,objective:"time"} plans from criteria/inventory, routes, batches concurrent work, reviews and merges/acks one context. next supplies swarmAction. Cost routing needs nonoverlapping full-route estimates; unknown favors solo. Planning/merge usage counts; model judgments prove no savings. Explicit retry:true retains terminal cycles/counters; uncertain claims reject. No hidden retries.
16
+
17
+ Token usage never interrupts workers or refuses assignments. Old budgetTokens/reserveTokens/tokenBudget inputs are optional and discarded.
18
+
19
+ Parent-only [CLI](runtime.md): --run/--file, version:1 JSON; unknown fields reject.
20
+
21
+ | Action | Input |
22
+ | --- | --- |
23
+ | delegate swarm | version:1; optional objective time/tokens/spend, model, timeoutMs,maxInputBytes |
24
+ | delegate cancel-swarm | version:1,reason; stops further generation, drains terminal outcomes |
25
+ | delegate decide | objective tokens/spend/time; facts {independent,sharedState,evidence}; capabilities {dispatch,evidence}; optional estimates {solo:{min,max},delegated:{min,max},evidence} |
26
+ | context task | Returns document, revision, hash, read receipt |
27
+ | context ack | revision, hash, receipt, application |
28
+ | delegate assign | id, objective, criteria IDs, paths, writePaths:[], dependencies, contextRevision, contextHash, stoppingRule; optional hostReference |
29
+ | delegate execute | assignmentId; optional model, timeoutMs (100–900000; default 300000), maxInputBytes (1024–262144; default 65536) |
30
+ | delegate record | assignmentId, resultId, status passed/failed/cancelled, assignment contextRevision/contextHash/basisHash, summary, hostStopped:true, findings, failedApproaches, questions; optional checks,usage |
31
+ | delegate cancel | assignmentId, reason; worker slot stays occupied until terminal acknowledgment |
32
+ | delegate reconcile | expectedRevision, summary, nextAction, findings, conflicts, failedApproaches, dispositions; optional resolutions |
33
+
34
+ Unknown/overlapping estimates favor solo; delegated upper must beat solo lower. Time may justify delegation. Estimates never ration execution.
35
+
36
+ Execute claims once; uses CODEX_APP_RUNTIME_CLI_PATH in Codex, PATH elsewhere; invalid hints reject. Account-default model gets scoped UTF-8 and acknowledged context. Read-only turns disable known execution/connectors. Scope is cooperative, not OS isolation. Lead reconciles/acks.
37
+
38
+ ## Evidence and consolidation
39
+
40
+ Findings: id,text,evidence; unified findings add status observed/judgment/hypothesis/superseded/stale and origins. Evidence {path,sha256} is canonical, link-free, scoped. Active hashes must match; historical hashes may survive deletion.
41
+
42
+ Conflicts {id,detail} need resolutions {id,evidence}. Retain failedApproaches. Dispositions {assignmentId,status:accepted/rejected,reason,findingIds,revalidation?} need current findings/origins and drift revalidation. Lead checks source/criteria.
43
+
44
+ Pending contributions/conflicts, stale evidence or missing acknowledgment block handoffs/checks. Ack is not comprehension.
45
+
46
+ Merge binds source/context/result-set hashes; namespaces findings; preserves prior knowledge, origins, questions and failures. A model reviews support; conflicts block dependent work. Private transports/all-settled draining preserve siblings. Pending phases block parent handoffs. Cancel/stop/lost transport retains uncertain claims. After committed-merge I/O failure, read/ack the existing context; never regenerate it. No automatic parent completion.
47
+
48
+ ## Usage and recovery
49
+
50
+ Usage {receiptId,inputTokens,outputTokens,cachedInputTokens,model,origin:host-reported/agent-estimated} is telemetry. Cached input is a subset. Missing use stays unknown; estimates stay labeled. No reservation charge. Historical counters may include estimates; receipts/observedTokens identify known usage.
51
+
52
+ Scope, dependencies, concurrency, assignment count and replay remain controlled; failures consume attempts. Explicit cancel, parent stop/pause, timeout and unexpected tools interrupt. Only matching turn/completed releases the slot. Lost transport retains the claim; never redispatch. Claimed workers require correlated host receipts.
53
+
54
+ Authentic active legacy views migrate on read; need fresh acknowledgment. Completed archives keep their bytes. Missing/expected prior projections recover; unexpected edits remain needs-context-sync. Never edit state. Later material context needs retry/reverification.
55
+
56
+ Retain [learning](context.md) before checks. Proof/review remain. Fixtures prove no activation/savings.
@@ -30,6 +30,8 @@ Confirm that a fresh real host session loads the intended skill and hooks. Inspe
30
30
 
31
31
  The current adapters still require qualification for the environments advertised to users, including desktop behavior, host trust, live continuation and marketplace installation. Automated simulated events do not establish those outcomes. [Onboarding and recovery](onboarding-recovery.md) explains the diagnostic states.
32
32
 
33
+ The source-only cohort exercise in `evals/cohort-journey/` prepares first/related-task behavior probes and an observation protocol. Its exposed fixtures are known development material; no participant, fresh-chat, recovery, host activation or efficiency result follows from a passing probe. Recruit only with explicit authorization; keep separate evaluator checks outside producer projects and actual unknown measurements null.
34
+
33
35
  ## Product and team acceptance
34
36
 
35
37
  For user interfaces, inspect current rendered desktop and phone views, exercise the primary action and relevant failure states, and check keyboard use and applicable access requirements. Build success alone cannot establish visual quality. Missing browser evidence remains unverified.
@@ -2,13 +2,11 @@
2
2
 
3
3
  New implementation runs keep Scout → Build → Verify → Deliver. Each stage records only the evidence it owns; no additional agent, approval ceremony, or mandatory document inventory is introduced. Routes containing Build require `workContractVersion: 1`. Advisory routes and serialized legacy runs retain their existing handoff contract and are labeled accordingly.
4
4
 
5
- `run next` lists `assessmentRequired` and `reviewPath`. It lists only the fields the agent must judge: when they are left out, the controller records `learning` as none, `errorHistory` as none for a run that is not a bug fix and has no failed attempt, and Scout's `context` as none when the project has no `docs/context/INDEX.md` and no ledger, each with a reason saying it was not given. The agent supplies a small JSON assessment with `run record --assessment FILE` alongside the usual summary/criteria, or as `assessment` in a full handoff packet. Store assessment inputs beneath `.cyc/runs/ID/` so they do not change covered source. The user describes the desired outcome; the agent operates this interface.
5
+ run next supplies assessmentRequired, finishTemplate and reviewPath. Fill actual judgments in the generated input under .cyc/runs/ID or .cyc/runtime (outside covered source). Implementation runs plan required canonical feature context before Build; learning:none is no longer the default for required retention. Missing Scout history can remain context:none with an honest lookup; that does not waive creating feature knowledge. Error history defaults to none only when no bug-fix/failure requires it. Legacy stored receipts retain their contract.
6
6
 
7
7
  ## Scout: reuse context and choose the approach
8
8
 
9
- Read the existing feature map or equivalent if one exists, search current implementations, and classify the change as reuse, extend, repair, or create. A context index locates historical reasoning; it need not become a second feature inventory. When no capability map exists, put the small relevant capability description in the existing context index only when useful. Avoid cataloging the entire project.
10
-
11
- Read the matched component documents, not only their index. Search shared error history (`projectLedgerPath`) and relevant earlier run-local histories. Check relevant commits and working-tree differences; a commit alone does not establish freshness in a dirty checkout. Treat old entries as leads until confirmed. Explain consequential changes as current behavior → proposed change → reason → decision needed. `clear` means the request already settles the decision; `confirmed` requires actual user confirmation. `needs-input` must block the handoff, not manufacture approval.
9
+ Read the target index, matched component records and relevant shared/run-local error history. Revalidate against current code/diff and dependencies; classify reuse, extend, repair or create. Keep consequential decisions explicit: clear follows the request, confirmed needs observed confirmation, needs-input blocks. Before scope freezes, supply contextRetention version 1: disposition required, features [{id,doc,paths}] for each meaningful feature and shared owner. Use focused canonical docs and their index, never engine knowledge or a catch-all row. Inspect inference if omitted. See [Context](../methods/cyc-context/SKILL.md) for scope restrictions and equivalent conventions.
12
10
 
13
11
  ```json
14
12
  {
@@ -43,7 +41,9 @@ Build still records its summary and changed artifacts. Record each attempted pro
43
41
 
44
42
  Run the applicable real journey/recipe checks, map acceptance criteria and affected consumers to checks, and demonstrate that new regression tests detect the defect. Then review intent, consumers, and project conventions against the actual diff. This is a focused review within Verify; additional reviewers are risk-driven, not mandatory. Identify model review as `self`, `fresh-context` (a subagent given only the diff, criteria, and principles), or `peer`, never as a machine check or human approval.
45
43
 
46
- **Test proof.** New bug-fix, feature and refactor runs require a current `run prove-red` receipt even without a Git commit. Run-start source capture supplements the recorded Git base within source policy and task scope; older runs retain their actual recovery limitations. New or changed tests must fail on the original code (bug fix, feature) or pass there (refactor), while the original control passes its existing checks. Editing a proven test makes the proof stale. A change with no testable behavior records `"testProof": {"status": "exempt", "reason": "..."}` in the Verify assessment; an actual unavailable-proof case must state its limitation and supporting alternative evidence truthfully. The exemption and reason appear in the generated review and never count as a proof receipt. See [run-start originals](runtime.md#run-start-originals).
44
+ **Test proof.** Normal finish runs the frozen proof plan on originals plus changed tests and restores owned candidate bytes. Bug fixes/features require decisive red; refactors require green characterization. Missing originals remain unavailable. A genuinely non-testable change can use testProof:{status:"exempt",reason:"actual limitation and alternative evidence"}; this never becomes a proof receipt. Changed tests invalidate proof. See [originals/ownership](runtime.md#run-start-originals).
45
+
46
+ Node checks that need named-case evidence should explicitly request --test-reporter=tap. Presentation defaults vary; unsupported output remains diagnostic, not named semantic coverage.
47
47
 
48
48
  ```json
49
49
  {
@@ -63,118 +63,51 @@ Run the applicable real journey/recipe checks, map acceptance criteria and affec
63
63
  }
64
64
  ```
65
65
 
66
- Every Scout consumer must appear once; add newly discovered consumers with their own evidence. All listed checks must pass. Findings may be `resolved` or `dismissed` with evidence; an `open` finding prevents a passing Verify handoff. An empty findings array means the reviewer found no issues, not that review was skipped. Passing configured commands never substitutes for this assessment, and the controller cannot determine whether an agent's stated observations are true. Changes after the Verify handoff require returning to Verify, rerunning checks, and reviewing the current files before delivery.
66
+ Each Scout consumer appears once, plus newly discovered consumers. All required checks must pass; open findings block. Resolved/dismissed findings need evidence. Empty findings means reviewed without issues, not skipped. Commands do not substitute for semantic judgment or prove reported observations. Later covered edits invalidate dependent verification/review.
67
67
 
68
68
  ## Versioned evidence records
69
69
 
70
- The updated implementation workflow starts with `evidenceVersion: 1`, `requirements` containing the original authorized outcomes, and explicit `criteria`. The existing implementation assessment contract remains v1; evidence version 1 adds structured provenance. Unversioned clients and saved runs remain supported with their original evidence limits. A bare fresh-context/peer label now renders **unlinked**, including on historical records. No review identity or missing evidence is invented during migration.
70
+ Start updated implementation runs with evidenceVersion:1, original requirements text and explicit criteria/clauses. Keep the user's original IDs and material obligations. The controller stores requirements and criteria fingerprints, but cannot judge whether all meaning was captured. Unversioned clients and schema-1 historical runs remain supported with their original limits; missing provenance is never manufactured.
71
71
 
72
- Keep original outcome IDs in `criteria`. Optional `clauses: [{"id":"permissions","description":"Original permissions survive restoration."}]` retain material obligations within an outcome. The controller stores the original requirements text and its SHA-256, and the criteria fingerprint. It can check missing IDs and links, but cannot decide that an agent captured every meaning of the user's request. Group headings belong in the short plan, not in a reduced acceptance list.
73
-
74
- Set `reviewPolicy: "self-allowed"` (the default) or `"fresh-required"`. The latter requires current source-linked, agent-reported fresh-context coverage of every changed source path. Select it for the workflow's high-risk fresh-review route. If the host cannot provide a fresh reviewer, use the stated self-review fallback at start and disclose that limit; never invent a reviewer identity. No product approval step is added.
72
+ reviewPolicy is self-allowed or fresh-required. The latter needs current source-linked fresh-context coverage of every changed source path. Select the actual available reviewer at start and disclose a fallback; do not invent an identity or approval. A reviewer label without its receipt remains unlinked.
75
73
 
76
74
  ### Capture the candidate before review
77
75
 
78
- Run `cyc run review-capture --run ID --file CAPTURE.json` with `{"reviewer":"fresh-context","scope":["src/persistence"]}`. Reviewer is `self`, `fresh-context` or `peer`; omitted/empty scope means the whole covered source. Include affected contracts and producers in the review inputs. The controller stores canonical scope, the entire selected-source file manifest/fingerprint (including the implications of additions and deletions), criteria fingerprint and capture time in this run's receipt. This initial implementation uses conservative whole-source freshness, even for a scoped review: an unrelated selected-source change also stales it. It does not infer dependency coverage or combine old/new manifests as a current delta review.
79
-
80
- After the actual review, run `cyc run review-record --run ID --file REVIEW.json`:
81
-
82
- ```json
83
- {
84
- "reviewId": "ID_RETURNED_BY_CAPTURE",
85
- "identity": null,
86
- "evidence": "Actual review observations or reviewer output, with precise locations.",
87
- "findings": []
88
- }
89
- ```
76
+ Use run review-capture --run ID --file CAPTURE.json with reviewer and optional literal scope. Empty scope means whole source. The result provides recordTemplate with reviewId, identity:null, evidence placeholder and findings. Fill that exact file from actual observations, then use its exact review-record command. Invalid identity/evidence gets a field-specific repair pointer before mutation. Capture before dispatch: attaching current hashes to an older review is invalid.
90
77
 
91
- Findings use the existing unique `id`, `status` and `evidence` shape. Capture before dispatch; attaching today's source fingerprint to an earlier review is invalid. Recording refuses changed source/criteria, altered receipt bytes, foreign IDs and duplicate recording. `identity` is nullable and, when supplied, agent-reported. The record is inspectable provenance, not attestation of independence or correctness.
78
+ For bounded follow-up, add contextPaths and meaningful contextEvidence after inspecting dependencies/contracts. Static local imports extend the context, along with package/lock/configuration and bounded toolchain/environment/dependency inputs. Unknown import/impact information falls back to whole-source freshness. Unchanged bounded scopes may survive an unrelated edit; changed, added or deleted scoped files, criteria and relevant contracts invalidate them. followupPath lists changes/contracts/findings. Broader review is required when impact cannot be bounded. Preserve the initial high-risk fresh review and history/focus coverage; composed scopes do not mean one reviewer read every final byte.
92
79
 
93
- Put recorded IDs in `semanticReview.receipts`. A linked non-self reviewer label must match a receipt of that type. Referenced scopes must cover the changed files; full-source receipts satisfy this without manually listing them. Fresh and self receipts on the current candidate render **mixed**. Every receipt remains visible by type and scope. Final dispositions for receipt findings include `reviewId` alongside the original finding `id`, `status` and `evidence`. IDs are unique within each review: two reviewers may both use `f1`, but each needs its own `{reviewId, id}` disposition. A bare shared ID cannot resolve both findings. Later edits stale the capture, requiring a new review; this conservative first version does not support carrying fresh coverage forward across an edited candidate through a delta-only review. Missing or altered evidence renders unverified. Receipt hashes follow Verify into Deliver so later tampering cannot disappear from completion checks.
80
+ Finish imports current recorded receipt IDs/findings when omitted. Explicit receipts/dispositions remain compatible. Open findings block; final dispositions use reviewId plus finding id, so same-named findings from different receipts cannot resolve one another. Missing generic findings are not invented when no record exists. Altered/stale/foreign receipts remain unverified, with hashes retained through completion. All review provenance is agent-reported, not an independence or correctness attestation.
94
81
 
95
82
  ### Record a scenario for every outcome and clause
96
83
 
97
- Versioned Verify assessments also contain `criterionChecks`, generated by the template:
98
-
99
- ```json
100
- {
101
- "criterionChecks": [
102
- {
103
- "id": "restore",
104
- "clause": "permissions",
105
- "scenario": "Delete then undo a record with nondefault permissions",
106
- "check": "unit",
107
- "receipt": "current-verification",
108
- "result": "passed",
109
- "origin": "agent-reported",
110
- "evidence": "The actual recreation adapter receives the original permission arguments."
111
- }
112
- ]
113
- }
114
- ```
115
-
116
- Omit `clause` for criteria without clauses. There must be exactly one entry for every criterion/clause pair, with a configured command ID and a meaningful scenario/observation. This is a coverage summary; one entry can cite several decisive cases. Entries may share a suite. `current-verification` is a controller-resolved reference to the current passing command receipt, not permission to fabricate a named passing runner result. For accepted pre-existing suite failures the scenario observation remains agent-reported and must identify its own actual result; the controller does not infer it from aggregate counts. A missing required result or an unavailable external check remains unverified; record a blocked handoff with the limitation rather than claim completion. The current parser retains failing case identities and aggregate passing counts, so named passing observations are deliberately not labeled machine-verified.
84
+ Versioned finish templates use scenarioEvidence as the canonical observation input; existing criterionChecks/consumerChecks/criterionEvidence forms remain supported. Each row contains id, optional clause, named scenario, configured check ID, receipt:current-verification, result:passed, origin:agent-reported, actual evidence and consumers:[Scout IDs]. Keep exactly one row for each original criterion/material clause. One row may cite several decisive cases. Finish projects exact criterion/consumer views when omitted and binds the canonical record in state.evidence; generated native/standalone delivery includes the same record.
117
85
 
118
- The controller binds and fingerprints the registered command receipt after checks run. Foreign, stale or altered receipts cannot satisfy a passing Verify. Both step-by-step recording and `run finish` retain the mappings, and Deliver/complete continue checking the evidence bytes.
86
+ For example: a restore/permissions row names delete-then-undo with imported fields/access metadata, cites its actual adapter observation and maps to the access consumer. A declared protected journey must use its named writer/status/read-write scenario. A missing mapping or unavailable external journey stays unverified; prose and aggregate counts cannot become machine-observed named coverage. The parser retains failing identities and aggregate passing counts, not proof that a named passing assertion ran. Agent observations stay labeled even when a suite passes or retains an accepted unrelated failure.
119
87
 
120
88
  ### Review the meaning of baseline failures
121
89
 
122
- `prove-red` now retains each decisive diagnostic's ID, check, test name/file, error/details and a nonauthoritative hint. A module-load hint is not automatically an absent-new-interface defect, and a TypeError may be the original bug. In versioned runs the initial `proofClaim` explicitly states diagnostic red, with semantic interpretation unreviewed.
90
+ Finish returns noncomplete needs-proof-review when measured failure IDs need judgment: receipt/failure IDs, decisive errors, known/unknown boundaries and the exact continuation input. Fill category/reason and invoke its command; bindings cover run/source/tests/config/proof/input and bound retries. Stale/foreign/placeholder/inadequate judgments cannot complete. Categories are behavioral, new-interface, setup, unclassified. Module-load/setup failures do not prove an existing behavioral defect; an absent interface can honestly establish feature red proof, while bug fixes need a decisive existing behavior. Setup/unclassified alone cannot pass. Unknown boundaries and unselected diagnostics remain visible.
123
91
 
124
- For non-exempt red proof, run `prove-red` before finalizing FINISH.json, then add:
125
-
126
- ```json
127
- {
128
- "proofReview": {
129
- "receipt": "current-proof",
130
- "cases": [
131
- {
132
- "id": "FAILURE_ID_RETURNED_BY_PROVE_RED",
133
- "category": "behavioral",
134
- "reason": "Original duration is 90, while the existing public boundary must return 60.",
135
- "boundary": "Existing duration() call exercised by the regression"
136
- }
137
- ]
138
- }
139
- }
140
- ```
141
-
142
- Categories are `behavioral`, `new-interface`, `setup`, and `unclassified`. Every selected case must match the current proof receipt and include a reason; behavioral cases also name the existing observable boundary. A bug fix needs a decisive behavioral case. A feature may establish an absent new interface, while final behavior still needs passing verification. Setup/unclassified cases alone cannot pass this reason review. Unselected diagnostics remain unclassified and visible. Refactors retain green-on-original proof without manufactured red. Truthful exemptions remain supported and never become demonstrated behavioral proof.
143
-
144
- The controller links the reason review to the proof receipt and tests' existing freshness checks. Its generated claim separates behavioral and new-interface cases and identifies interpretation as agent-reported. It does not equate failing-test count with repaired-defect count. The normal fast route remains `prove-red` to obtain case IDs, then one `finish` to verify and deliver; unchanged proof is reused. If finish generated proof automatically, read its failures and supply the reason review before completion rather than relabeling diagnostics as behavior.
92
+ Optional proofCommands freezes focused execution at start; --tests selects swapped files only. Final candidate checks remain broad, and accepting unrelated broad failures requires compatible measured broad originals. Explicit local-deterministic receipt reuse requires matching bounded inputs; unknown/external/freshness checks rerun. See [runtime](runtime.md#recovery-and-budgets). Process completion, fingerprints and model scores do not certify product readiness or hook activation.
145
93
 
146
94
  ## Learning lifecycle and final file order
147
95
 
148
- 1. Keep consequential decisions and provisional findings in run-local notes during work. Append failures to `run next`'s selected `ledgerPath` immediately, even for abandoned tasks. Preserve existing ledger formats. New runs use run-local history when shared documentation is outside permitted writes; retain shared-history lookup through `projectLedgerPath` and disclose pending promotion in `errorHistory.reason`. This does not waive explicit project policy or authorize more scope.
149
- 2. Before final verification, finalize authorized durable context/index updates and the ledger. Verified technical findings can be recorded with their observed scope, evidence, supporting dependencies, and limits. A passing test establishes its observed behavior, not human approval of a design. Mark a decision adopted only with actual acceptance evidence; use existing authorization and review rather than adding another approval ceremony.
150
- 3. Keep unverified hypotheses and design proposals awaiting acceptance in referenced run-local drafts marked pending acceptance. A component record may contain verified facts while a separate proposal is pending; retain the facts under `learning: recorded` and reference the pending proposal separately in the handoff. If only pending proposals exist, use `learning: pending-acceptance`. Later promotion is a scoped documentation update with fresh review; never silently edit a completed run's verified source.
151
- 4. Run final verification on the final project files, record the semantic review and consumer evidence, then record Deliver and complete. Source changes to context docs or the ledger invalidate earlier verification exactly like other source changes. Include intended documentation paths in `--scope`; do not broaden scope after the run has started.
96
+ 1. Record failed attempts promptly in the selected ledger, even abandoned work. projectLedgerPath selects lookup; ledgerPath selects recording, with run-local fallback when shared writes are outside scope. Disclose pending shared promotion; do not infer expanded permission.
97
+ 2. Author each planned canonical feature/shared record before final verification. Include capability/boundaries, ownership/data flow/contracts, choices/reasons, failures, decisive check commands and known limits. Keep hypotheses/proposals labeled; tests do not establish adoption. INDEX.md, ledgers, recipes, generic handoffs and ignored logs support context but cannot replace it or inflate contextDocs.
98
+ 3. Supply actual learning.context [{id,currentView}] in finish, or author records and use context prepare --run ID. Finish creates missing target scaffolds, upserts current History/source evidence and relevant index metadata, then returns needs-context until valid. Generated History alone cannot satisfy authorship. No future check outcomes or self/index hashes are written; final command receipts stay outside source with stable run references.
99
+ 4. Verify final files, review the actual candidate, then complete/deliver. A covered context/ledger edit invalidates dependent evidence like code. Completed-run catch-up requires a required canonical plan in a new implementation update, its own repair History and fresh executable checks; a packet cannot reverify changed source. Late needs cannot silently broaden frozen scope.
100
+
101
+ Example finish assessment fragment (use actual planned IDs, prose and paths):
152
102
 
153
103
  ```json
154
- {
155
- "learning": {
156
- "status": "pending-acceptance",
157
- "reason": "The only new learning is a proposed architecture decision awaiting acceptance; the existing verified behavior is unchanged.",
158
- "artifacts": [".cyc/runs/RUN_ID/learning.md"]
159
- },
160
- "errorHistory": {
161
- "status": "recorded",
162
- "reason": "Recorded the page-limited attempt, correction, and regression evidence.",
163
- "artifacts": ["docs/context/error-ledger.md"]
164
- }
165
- }
104
+ {"learning":{"status":"recorded","reason":"Retain the owned order-storage contract and its check limits.","artifacts":["docs/context/orders.md"],"context":[{"id":"orders","currentView":"Actual capability, contracts, decisions, failures, commands and known limits from this implementation."}]},"errorHistory":{"status":"recorded","reason":"Record the observed failed attempt and repair.","artifacts":["docs/context/error-ledger.md"]}}
166
105
  ```
167
106
 
168
- Replace `RUN_ID` with the actual run ID. Learning status is `recorded`, `pending-acceptance`, or `none`. Error-history status is `recorded` or `none`. Both require a reason. `none` uses an empty artifacts array; do not create filler documentation when there is nothing reusable to record. Other statuses require existing files, automatically fingerprinted and checked again at completion. Pending learning must live inside this run's directory. Recorded error history must include the selected ledger returned by `run next`. Bug-fix runs and runs with recorded failures cannot finish with `errorHistory: none`.
107
+ Learning statuses: recorded, pending-acceptance, none; error-history: recorded, none. Both need reasons. Non-none artifacts must exist and are fingerprinted/rechecked. Pending proposals belong under this run and are not a substitute for required feature context; retained facts can coexist with a pending proposal. None uses empty artifacts and is proportional only when no feature retention is required. Explicit documentation restrictions remain pending/incomplete without unauthorized writes. Bug fixes/recorded failures require the selected ledger. Routine dispositions and semantic completeness remain agent judgments, not machine truth.
169
108
 
170
- The controller cannot see unreported fix attempts, infer acceptance, or prove that a ledger describes the actual failure. These remain agent responsibilities. The structured record makes the claims inspectable; it does not certify them.
171
-
172
- Context file evidence is optional. The Context method's helper compares selected file hashes without changing the run contract. A matching hash is not a semantic verdict or a substitute for final verification; existing Git/diff checks remain usable for records without manifests. Include integration/configuration dependencies that support a claim, then revalidate affected claims when evidence drifts. Ensure shared component records identify evidence that exists only in ignored run directories before claiming another checkout can reproduce it.
109
+ Current runs enforce canonical layout/index/mappings, consistent current History and actual source evidence, with authored Current view bound to selected source. Automatic validation reads relevant planned records plus index consistency; arbitrary explanatory truth and unreported failures still need judgment. Old stored receipts are not retroactively upgraded. Optional byte manifests supplement History; preserve historical disclosures and label current evidence separately. Summarize local-only receipt conclusions and reproducible commands for source-only readers.
173
110
 
174
111
  ## One review artifact, reused throughout delivery
175
112
 
176
- The controller generates `.cyc/runs/ID/review.md` at startup and after recorded changes. It contains the outcome, criteria, approach, context/freshness, changed artifacts, configured results, semantic review, consumer evidence, learning dispositions, failures, and remaining decisions. It is derived from the surviving handoffs and receipts; rewinding removes invalidated assessments from the current review while recovery events remain visible.
177
-
178
- Use `cyc run review --run ID` to refresh it after external edits. The document records the source fingerprint and marks stale verification/review instead of presenting it as current. Link this same artifact in developer review and reuse its content for an authorized PR. Keep edits in the underlying handoffs, not the generated Markdown. Run directories may be ignored by Git: publish or copy the review only when authorized, and do not put secrets in it.
179
-
180
- The generated document is outside covered source, so generating it does not invalidate verification. Declared context/learning/ledger files retain ordinary artifact hash checks. A generated review cannot serve as its own assessment evidence. This is a review aid, not an approval to commit, publish, or merge.
113
+ The generated .cyc/runs/ID/review.md projects surviving handoffs/receipts: criteria, approach, changed source, check results, semantic review, consumers, learning, failures and decisions. Rewind removes invalidated assessments but retains recovery events. run review --run ID refreshes current fingerprints/staleness. Edit underlying handoffs, not this Markdown; a generated view cannot prove itself. Reuse it for review/authorized PRs, disclosing ignored/local-only evidence. Generation outside source does not invalidate checks; covered context/ledger edits still do. No commit/publication authority is implied.
@@ -1,65 +1,20 @@
1
1
  ---
2
2
  name: cyc-build
3
- description: "Implement a planned change in thin, tested slices where every line traces to a requirement. Use for feature work, bug repairs, and refactors once the Scout plan (or, on longer routes, the design) exists."
3
+ description: "Implement planned behavior in thin tested slices, preserve affected consumers and hand current evidence to Verify."
4
4
  ---
5
5
 
6
6
  # Build the change
7
7
 
8
- For a new web page or visual redesign, follow the [frontend design method](../cyc-design/frontend-design/SKILL.md): build the signature section from `design/decisions.md` with final copy, the chosen imagery, the main action and the next section's start; render it at desktop and phone width and score it with the generic-tells sheet **before expanding the rest of the page**. Three or more tells means a changed decision, not a color swap. End-of-build screenshots do not perform this checkpoint. No variant quota or user approval round is required. Narrow UI repairs retain the established direction.
8
+ Follow [handoffs](../../docs/skill-contract.md), [principles](../../docs/principles.md), [code standards](../../docs/engineering/code-standards.md) and the [progress standard](../../docs/response-standard.md#progress-updates). Read applicable project rules and preserve dirty work. Explain behavior, preserved contracts and actual evidence.
9
9
 
10
- Ship the design, slice by slice, with a loop running the whole time. Follow the [handoff contract](../../docs/skill-contract.md).
10
+ Use [domain design](../../docs/engineering/domain-design.md) for shared invariants and [failure handling](../../docs/engineering/failure-handling.md) for I/O/partial effects. Impact is not edit authority.
11
11
 
12
- For user updates, follow the shared [progress standard](../../docs/response-standard.md#progress-updates): briefly connect the code change to the behavior it fixes and what the chosen approach preserves. Explain meaningful changes of direction without narrating every edit.
12
+ Write the smallest coherent slice. Features/bugs need meaningful red/green checks; refactors need characterization passing on originals and candidate. Never weaken a requirement, test or configured check to pass. After two failed fixes challenge their shared premise.
13
13
 
14
- At a consequential slice, explain how the changed state or contract reaches its readers and why the fix belongs at that boundary. When a failure changes the approach, share the observation, the assumption it challenges, and the next discriminating check. Follow the [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work); a list of edited files or "retrying" does not explain the engineering.
14
+ Trace state, storage, interfaces and consumers. Use focused feedback then broad checks. Review diffs; run git diff --check, preserve encoding and log actual failed fixes.
15
15
 
16
- Write code to the [engineering principles](../../docs/principles.md): the smallest change, the cause fixed where it starts, tests that assert observable behavior, and the codebase's existing patterns.
16
+ New composed frontend work must follow [frontend gates](../cyc-design/frontend-design/SKILL.md) before expansion; narrow repairs preserve existing identity.
17
17
 
18
- Before implementation, read the project's applicable `code-standards.md` and follow the relevant [code standards](../../docs/engineering/code-standards.md). Review comments for information value, types for supported facts, catches for an allowed failure contract and abstractions for real responsibility. Preserve required documentation and local conventions; numerical complexity thresholds are investigation signals, not automatic refactor instructions.
18
+ Read/acknowledge current [unified task context](../../docs/task-context.md) before dependent work. Workers are bounded/read-only; reconcile evidence, disagreements and failed approaches. Worker success does not complete the parent.
19
19
 
20
- Before implementing a slice that adds or changes business rules/transitions, read the [domain design examples](../../docs/engineering/domain-design.md) to locate the invariant's owner and affected writers/readers. For rejection, I/O or partial effects, read the [failure handling examples](../../docs/engineering/failure-handling.md) to decide what committed, what callers can distinguish, and whether retry is safe. Load only applicable guidance and preserve its legitimate exceptions and the project's conventions.
21
-
22
- ## The core loop
23
-
24
- 1. **Check the ground.** Look at the working tree and the files you will touch. Preserve uncommitted user work. Start the first useful source or test edit as soon as the short plan is ready. Never wait for an optional baseline: edits may invalidate that diagnostic measurement, but final verification still checks the finished work.
25
- 2. **Capture behavior before you change it.** For a bug, the failing reproduction from the [diagnose procedure](../cyc-understand/references/diagnose.md) is that check. For a refactor, write or find a characterization test that captures current behavior at the boundary; type checks and lint do not capture behavior. For a feature, write the first slice's test.
26
- 3. **Match the feedback loop to the change.** For a feature or bug fix, write one test for the slice, watch it fail for the intended reason, make it pass, then move to the next slice. For a refactor, run characterization tests on the original and candidate code and keep both green; do not invent a behavior change to manufacture red. Reuse adequate existing tests. For a change without executable behavior, record the specific reason and the inspection that checks it. Copy, styling, and configuration can affect behavior; their file type alone is not an exemption. A prose skip does not replace any `testProof` assessment required by the controller.
27
- 4. **Keep the data consistent.** A visible control is not the feature. When the state changes, every reader named in the plan (or impact map) sees it: the count, the filter, the saved record.
28
- 5. **Do repetitive work by hand once, then automate.** If the change repeats across many files, do the first by hand, write a script or codemod for the rest, and diff its output against your hand version.
29
- 6. **Keep feedback focused.** Use the narrowest applicable verification recipe selected by Scout (`recipe run --recipe <ID>`), or a focused project check when none exists. Run it after meaningful slices and type checks when affected contracts require them; keep expensive journey checks for Verify. Respect recipe prerequisites/effects and current authorization. Let final Verify own the configured suite; preserve required proof/final commands even after an earlier focused pass.
30
- 7. **Check the final bytes, then trace every line.** Prefer a focused patch to rewriting an entire file. Preserve its encoding and line endings; on Windows, follow the [file-write check](references/file-writes.md) when generating or replacing text files. In Git projects, run `git diff --check` before recording Build or creating a test-proof receipt, so cleanup does not immediately invalidate that proof. Read the full diff: each change should trace to a criterion, the design, or the impact map. Revert speculative "might help" edits and drive-by cleanups.
31
- 8. **Quality pass.** Trace the important value/state from its origin through updates, consumers, and relevant failure paths. For changes to ownership, state, or interfaces, apply the [architecture questions](../../docs/code-quality.md#choose-a-structure-that-protects-the-contract). Check the domain/failure decisions used for this slice: one owner of shared policy, callers that can distinguish rejection from failure, and no hidden partial effect or unsafe retry. Can a maintainer locate the invariant and the boundary for a likely next change? Fix concrete shortfalls inside scope; preserve meaningful adapters and abstractions. File length and caller count are investigation clues, not deletion rules.
32
- 9. **Clean up.** Remove debug logs (search for your debug marker), throwaway harnesses, and commented-out code.
33
- 10. **Retain learning before final verification.** Append attempted fixes and evidence to `run next`'s selected `ledgerPath` as they happen. Its [Error ledger method](../cyc-error-ledger/SKILL.md) distinguishes shared lookup from run-local recording when documentation is outside scope. Finalize authorized durable facts/context/index and ledger updates before Verify; keep unverified hypotheses and undecided proposals in run-local notes. Follow the [learning lifecycle](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order). Implementation readiness is not user acceptance of a design.
34
-
35
- ## Done when
36
-
37
- - Each slice has the applicable evidence: red then green for changed behavior, green on original and candidate for preserved behavior, or a justified alternative check.
38
- - The full diff was read and each hunk traces to a reason.
39
- - The quality pass found nothing left to fix within scope.
40
- - Focused checks and type check pass on the final file state.
41
- - Anything that could not be done is listed with why.
42
-
43
- Build passing does not mean the task passed. Hand off to Verify.
44
-
45
- ## Stop rules
46
-
47
- When a failure or interruption prevents progress, read `run recover --run ID` and follow the [recovery guidance](../../docs/onboarding-recovery.md). Explain the observation, preserved work and next action before presenting a raw log. Resume only after a real prerequisite is resolved; keep terminal runs and their budgets intact.
48
-
49
- - The approach turns out wrong (the same workaround twice, escape-hatch types): stop and rethink the plan. In fast playbooks that's `run retry --stage scout`; in the detailed chain, [Design](../cyc-design/SKILL.md).
50
- - A consumer the plan missed appears: add it to the plan and handle it. It only needs a retry if it changes the approach ([Impact](../cyc-impact/SKILL.md) in the detailed chain).
51
- - Two fix attempts fail the same way: stop patching. Write down the assumption both attempts share, and check it before a third (see [Challenge](../cyc-challenge/SKILL.md)).
52
-
53
- ## Anti-patterns
54
-
55
- | Name | The tell | Fix |
56
- | --- | --- | --- |
57
- | Guard patch | Adding `if (x == null) return` to silence the symptom | Find why it is null |
58
- | Toast fix | Adding a "Saved!" message when saving is what's broken | Fix the write, then verify reload |
59
- | Instance fix | Fixing one call site of a repeated bad pattern | Search for the pattern and fix or list all of them |
60
- | Drive-by | Renames and reformatting unrelated to the task | Revert; mention it separately |
61
- | Untested refactor | Restructuring with no behavior test in place | Add a characterization test first |
62
-
63
- ## Handoff
64
-
65
- Give [Verify](../cyc-verify/SKILL.md) the changed files, the tests added (with their red and green output), the commands run, and any deviation from the design with its reason. A local checkpoint is not permission to commit, merge, or publish.
20
+ Retain canonical knowledge/index before checks through [Context](../cyc-context/SKILL.md). Restrictions stay pending; packets cannot refresh source. Hand Verify changes, red/green evidence and limits. Build is not task acceptance; recovery preserves budgets.
@@ -31,6 +31,10 @@ Your job is to break it, not to praise it. "No findings" is a valid result; manu
31
31
 
32
32
  ## Done when
33
33
 
34
+ Prioritize demonstrated authority/state transitions before cosmetic findings. For a new protected consumer, call the existing writer, existing status reader, and new protected read/write boundaries together, especially with conflicting legacy/canonical records. Require one shared authoritative resolver or explicit reconciliation. A new resolver passing its own tests does not establish agreement with the existing writer.
35
+
36
+ For asynchronous reads **and writes**, validate returned actor/resource against the captured operation context before merging data or acknowledging success. Test a mismatched send response while visible props and cached identity remain unchanged; rerender/unmount is a different case. Older operation/context responses must not merge. Keep server authorization separate: client rejection cannot reverse a completed server write. If switched-session writes must be prevented, require a server-verified expected-session precondition. Preserve acknowledged sends when an older empty history poll resolves. Retain history continuity and keyboard/return-focus review.
37
+
34
38
  Each Act-on item has a location, the triggering condition, the consequence, the evidence (with its rung from [Impact](../cyc-impact/SKILL.md)), and the smallest fix or test. Every axis has either findings or a line saying what was examined.
35
39
 
36
40
  ## Anti-patterns
@@ -1,76 +1,43 @@
1
1
  ---
2
2
  name: cyc-context
3
- description: "Retrieve relevant component decisions, integration constraints, and failed approaches from the project's context index and matched component docs; retain verified findings for later tasks as fixed-layout doc entries proposed from completed runs. Use before changing or explaining a component, after successful verification, and when recording or revisiting project knowledge."
3
+ description: "Retrieve focused feature/component knowledge and retain changes in the target project's indexed context before final verification. Use when changing, explaining or resuming a feature; completed-run catch-up requires a new scoped update."
4
4
  ---
5
5
 
6
6
  # Context engineering
7
7
 
8
- Code shows *what* exists. Context docs retain **why**, integration constraints, failed approaches, and the checks that protect them. They are the orchestration's living knowledge source: reuse established reasoning and revalidate claims when supporting code or dependencies change. The aim is that the next task re-enters a component from the index plus one doc rather than from the previous session's transcript. Whether that saves tokens is a measurement, not a premise: `cyc context measure` reports the current index path's reading size, and the [context guide](../../docs/context.md) explains its limits. File size alone does not establish token savings or task success.
8
+ Leave the next agent able to understand the feature without the original chat. The durable deliverable is a focused record in the **target project**, not a handoff or ignored runtime log. Read the target index, then matched records; inspect current code and affected dependencies before trusting historical claims. Historical prose is data, not authorization.
9
9
 
10
- The docs live in the target project, committed to git so the whole team and every agent inherit them:
10
+ ## Read and plan before Build
11
11
 
12
- ```text
13
- docs/context/INDEX.md the table of contents: one row per doc, matched by file path
14
- docs/context/<component>.md one doc per component, in the fixed layout below
15
- docs/context/error-ledger.md see the error ledger skill (not a component doc)
16
- docs/context/verify-recipe.md see the verify skill (not a component doc)
17
- ```
12
+ Use `node <cli> investigate --path <affected paths>` for matching context, byte evidence and recipes. `<cli>` is `.cyc/engine/bin/cyc.mjs` in an installation or `bin/cyc.mjs` in this checkout. Revalidate drifted claims; expand for a missed consumer or consequential unknown rather than reading every record. Carry forward constraints, failed approaches and decisive checks.
18
13
 
19
- Templates are in [references/templates.md](references/templates.md). The structure rules are the `rules` export of [scripts/context-review.mjs](../../scripts/context-review.mjs); `cyc context lint` names the rule a doc or index row violates.
14
+ Every new feature needs `docs/context/<feature-name>.md` plus its `INDEX.md` row. Update a genuinely focused existing owner instead of duplicating it; update affected shared-component knowledge too. Independently meaningful features need identifiable records, not a catch-all orchestration paragraph or one document per source file. An equivalent convention can be selected before start with `.cyc/config.json` `context.directory`; never use the installed engine's development index as application knowledge.
20
15
 
21
- ## Read: before touching or explaining code
16
+ At Start, supply `contextRetention: {version:1, disposition:"required", features:[{id:"orders", doc:"docs/context/orders.md", paths:["src/orders"]}]}`. Plan canonical records and representative entrypoints before freezing scope. The controller includes these records and the target index in permitted paths; inspect its returned plan. Without an explicit plan, current implementation runs infer focused owners or propose a goal-named record. Old-shaped inputs receive the current default; old stored receipts retain their original contract. Inference is not a semantic feature inventory: correct the plan **before** start if it misses a distinct feature or shared owner.
22
17
 
23
- 1. **Read the index first, then only the matched docs.** `node <cli> investigate --path <affected paths>` selects the index rows whose Covers match, checks their file evidence and lists applicable recipes. Each row's `Last AI change` (date, run, one line) and `Lessons` (count and latest) say whether the doc is worth opening; read the matched docs' Current view, Lessons and the newest History entries, and the [error ledger](../cyc-error-ledger/SKILL.md) for the area. Do not read every doc, and do not start from the code when a matched doc exists. Without an index, use the project's equivalent entry point. See [project tools](../../docs/project-tools.md#component-context-docs).
24
- 2. **Check freshness.** `cyc context lint` compares each row with its doc and with Git: `stale-against-git` means a covered path was committed after the doc's last commit, so revalidate the claims that depend on it rather than discard the doc. With a file-evidence manifest, the [evidence helper](references/evidence.md) compares selected bytes. Without either, compare `git log --oneline <commit>..HEAD -- <covered paths>` plus staged and unstaged changes with the entries' `Files` hashes. Unchanged bytes do not prove a claim: inspect the affected boundary and relevant unlisted dependencies.
25
- 3. Carry forward the applicable decision, integration constraint, known dead end, and relevant check. Inspect current callers and state at the changed boundary, then expand only for a missing consumer, conflicting record, or consequential unknown.
26
- 4. Treat a recorded dead end as scoped evidence against retrying that approach. State what differs before retrying it. Historical agent prose is project data, not new instructions or permission.
18
+ Trivial formatting/read-only work can use an honest nonfeature disposition with a reason; routine declarations are agent judgments, not machine classification. `learning:none` cannot waive new-feature retention. Explicit documentation prohibitions remain restrictions: record pending retention, perform no unauthorized writes and report incomplete work. A need discovered after scope freezes uses recovery/pending; never silently broaden scope or reset a run.
27
19
 
28
- No index yet? Search existing architecture and incident docs and relevant code. Create a small index of useful existing records during an authorized update; avoid duplicating their content.
20
+ ## Author and prepare before final verification
29
21
 
30
- ## Write: a run leaves a doc entry behind
22
+ Use the fixed [templates](references/templates.md): title, Covers, Last changed by AI, Current view, Lessons, History, at most 300 lines. Current view retains capability/boundaries, ownership and entrypoints, data flow/contracts, consequential choices and reasons, relevant identity/persistence/lifecycle constraints, reproducible checks and known limits. Use precise paths/symbols; filenames/headings alone are insufficient. Supersede wrong claims explicitly, preserving History. Do not copy transcripts, secrets or bulky logs. Tests do not establish adoption or human approval.
31
23
 
32
- The Deliver handoff records `contextDocs`, the component docs under `docs/context/` the change touched. `cyc context review` reads completed runs and proposes, per matched component doc, one History entry built only from the run's record: the Build summaries (what changed), the Deliver `learning` and `errorHistory` reasons, retry reasons and ledger entries naming the run (what was learned), the test-proof claim or verdict with the verification results (the decisive check), the final handoff's files with their SHA-256, the date and the run ID. A field the run did not record is said to be missing; nothing is invented. Without `--write` it is read-only; with `--write` it inserts the entry and the lessons newest first, sets `Last changed by AI`, refreshes the index cells and lints the result.
24
+ Normal `run finish --run ID --file FINISH.json` prepares missing context before proof/final checks. Fill `learning.context` rows `{id,currentView}` in its generated input, or author the planned records directly. `context prepare --run ID [--file CONTEXT.json]` is the same scoped preparation for earlier feedback; optional input contains `records` rows `{id,currentView}`, `summary` and `reason`. It scaffolds missing records/index, upserts one current-run History entry with actual selected source hashes and refreshes relevant index rows. It preserves completed History and uses only available observations; final outcomes stay in stable run/command receipts outside covered source. Do not hash the record/index into its own History or predict passing checks.
33
25
 
34
- 1. **After finish, when the change touched a component that has a doc and you did not update it:** `node <cli> context review --run <ID> --write`, then `cyc packet`, because files changed after finish. When no doc covers the files, `--new <component>` creates one from the run; its Current view is a placeholder the lint reports until you write it. A small change with nothing reusable needs no entry: leave it for the batch, and say so in `learning`.
35
- 2. **Batched:** plain `cyc context review` proposes entries for every completed run no doc records yet; review the proposals and `--write` them together. A team can run it at a cadence; the index row's `Last AI change` shows what the batch last covered.
36
- 3. **Keep the Current view yours.** The tool never edits it. After writing entries, update the Current view when an entry changed the rule a reader should follow: supersede a wrong claim explicitly and keep the reversal in History. Record only what the code cannot tell a reader: decisions and why, dead ends and their evidence, integration constraints with path and symbol pointers, the checks that protect them, and open limits. Distinguish observed facts, adopted decisions (with acceptance evidence) and limits; unverified hypotheses stay in run-local notes.
37
- 4. **Keep it short.** The `size` rule fails a doc past 300 lines: fold superseded entries into one lesson each and drop anything the code now makes obvious. Commit the consolidation separately so history stays readable.
26
+ Missing/placeholder/stale context returns **needs-context**, incomplete, with exact remaining input. Authored prose is bound to selected source; generated History alone is insufficient. Preparation stages files in run storage, preflights ownership/scope and resumes after a partial write without duplicating History. These are recoverable sequential writes, not an atomic multi-file transaction.
38
27
 
39
- Successful verification can establish a technical finding without establishing human approval of a design. Retain decisions as adopted only when actual acceptance is established. Failures belong in the ledger immediately. Follow the [learning lifecycle](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order): finalize durable updates before final verification and never silently edit a completed run's verified source.
28
+ For context/index-only upkeep, use the existing focused owner's implementation Covers as evidence when planned paths are supporting-only or empty. Unchanged implementation bytes are valid inspected evidence, not a behavioral repair claim. Missing anchors stay pending without publishing empty History metadata; unrelated files and self/index hashes cannot substitute.
40
29
 
41
- ## The layout and its rules
30
+ Finish/Verify validate planned canonical docs, resolving index rows, representative Covers, current History/source evidence and retention disposition. Index, ledger, recipes and receipts support context; they do not count as feature docs. Automatic validation is bounded to planned records plus index consistency. It checks structure/mapping/provenance, **not semantic truth or future model effectiveness**. Meaningful content still needs review. See [learning/file order](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order).
42
31
 
43
- A component doc, checked by `cyc context lint` (rule names in parentheses):
32
+ ## Inspect and catch up historical work
44
33
 
45
- ```markdown
46
- # Orders (title: one H1, first line)
47
- Covers: src/orders/**, src/storage.ts (covers: canonical patterns)
48
- Last changed by AI: 2026-11-01 · run <id> · files: src/orders/a.ts (last-change; or "none recorded")
49
- ## Current view (sections, in this order, once each)
50
- ## Lessons (lesson-dated: "- <date> · <source>: <text>")
51
- ## History (history-entry: "### <date> · run <id> · <title>", newest first)
52
- **Files:** src/orders/a.ts@sha256:1a2b3c4d5e6f (evidence: path@hash on every entry)
53
- ```
34
+ `context lint` audits actual target docs/index; `--doc PATH` narrows the document. Git freshness and optional [selected-byte manifests](references/evidence.md) identify drift, not correctness. `context measure --path PATH` counts current files (estimated tokens are characters/4), not provider usage, savings or successful reuse.
54
35
 
55
- `last-change-current` requires the last-change line to name the newest entry; `current-view` rejects an empty view or a template placeholder; `size` limits a doc to 300 lines; `name` requires a kebab-case file name. Index rules: `toc-columns` (Component, Covers, Doc, Last AI change, Lessons), `toc-link`, `toc-unindexed` (one row per doc), `toc-covers`, `toc-last-change`, `toc-lessons`, and `stale-against-git`. Reference rows whose Doc link points outside `docs/context/` are matched like component rows but never written. These are structure rules: a doc can pass every one and still be wrong about its component, and a fresh doc is one with no later commit to its covered paths, not one that is correct.
36
+ `context review --run SOURCE_ID` is a read-only proposal from completed evidence. A write needs a **new active implementation update** with a required plan covering the canonical records and executable final checks: `context review --run SOURCE_ID --write --update-run UPDATE_ID` (optionally `--new feature-name`). It retains actual historical dates/source, names missing evidence, preserves Current view and never rewrites the completed receipt. Author/reconcile Current view and record the repair under the update's actual run/date before fresh verification. Batch catch-up follows the same scope rules. A reply packet cannot reverify changed context.
56
37
 
57
- ## Done when
58
-
59
- - Read: the index and the matched docs were read, freshness checked, and relevant items carried into the frame or impact map (or "no matching docs" stated).
60
- - Write: a future task can find the applicable reason, constraint, evidence and limits from the index and one doc without the original chat. The index row resolves to it, its `Last AI change` names the run, and `cyc context lint` passes. Decision adoption is not inferred from tests; pending proposals remain explicit in the run record. Identify run-local-only evidence before claiming a record is portable to teammates.
61
-
62
- ## Anti-patterns
38
+ After verification, a covered context edit invalidates dependent evidence like a code edit. Return through supported Build/reverification and affected review. Never silently edit completed source and regenerate a packet. Preserve historical manifests as historical; label current evidence separately.
63
39
 
64
- | Name | The tell | Fix |
65
- | --- | --- | --- |
66
- | Code restatement | The entry lists props, files, or functions | Delete it; the agent can read the code |
67
- | Session diary | "First we looked at X, then Y" | Record findings, not the story |
68
- | Stale trust | Acting on an entry whose files changed since | `cyc context lint`, then revalidate the affected claim |
69
- | Silent rewrite | Editing an old entry to match today | Append a superseding entry; update the Current view |
70
- | Unindexed doc | A context doc no index row points to | `cyc context review --write` adds the row, or it will never be found |
71
- | Reading everything | Opening every doc at task start | Read the index, then the matched rows only |
72
- | Secrets in history | Tokens, customer data, or internal URLs in an entry | Redact before writing |
73
-
74
- ## Handoff
40
+ ## Done when
75
41
 
76
- Read mode returns relevant decisions, dead ends, gotchas, and freshness status to Scout. Write mode returns the doc path and index row, or the pending note path and reason. New implementation runs record a learning disposition even when nothing reusable was found; do not manufacture an entry. Authorized documentation needs no separate approval ceremony, but claiming user acceptance requires evidence. Committing follows normal autonomy rules.
42
+ The next task can discover focused rules, integration points, failures, checks and limits from the index and record without this chat. Required context is authored, indexed, source-bound and verified before completion; restrictions remain incomplete. Identify detailed receipts available only in ignored local storage. Portable records summarize their useful conclusions and reproducible commands without inventing missing proof. Commit/publication rules remain unchanged.
43
+ `context lint` names repairs with these shared rule IDs: `name`, `title`, `covers`, `last-change`, `sections`, `current-view`, `lesson-dated`, `history-entry`, `evidence`, `last-change-current`, `size`, `toc-columns`, `toc-link`, `toc-unindexed`, `toc-covers`, `toc-last-change`, `toc-lessons`, `stale-against-git`. The executable `rules` export in scripts/context-review.mjs defines them.
@@ -1,6 +1,6 @@
1
1
  # Checking selected context evidence
2
2
 
3
- Use the bundled Node helper when a component record needs repeatable file-byte checks, particularly for uncommitted work. Existing records without manifests keep their Git/diff freshness procedure. This is optional evidence support, not a new controller gate.
3
+ Use the bundled Node helper when a component record needs repeatable file-byte checks, particularly for uncommitted work. Existing records without manifests keep their Git/diff freshness procedure. Optional manifests supplement the required current-run History source hashes. They do not replace feature retention, authored context or final verification. Preserve historical manifests; new claims need separately identified current evidence.
4
4
 
5
5
  Pass the absolute project and the helper in the loaded Context method:
6
6