cyc-stack 0.7.1 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.
@@ -30,7 +30,7 @@ Before implementing a slice that adds or changes business rules/transitions, rea
30
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
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
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.
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. Author/update every planned canonical feature/shared record and index before Verify. Use finish’s learning.context input or context prepare --run ID; placeholders and generated History alone cannot satisfy retention. Preserve historical entries, write only available observations and keep future final outcomes in run receipts. Finalize ledger updates too; 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
34
 
35
35
  ## Done when
36
36
 
@@ -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,41 @@
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
+ 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).
40
29
 
41
- ## The layout and its rules
30
+ ## Inspect and catch up historical work
42
31
 
43
- A component doc, checked by `cyc context lint` (rule names in parentheses):
32
+ `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.
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 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.
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
+ 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.
56
37
 
57
38
  ## Done when
58
39
 
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
63
-
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
75
-
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.
40
+ 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.
41
+ `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
 
@@ -1,6 +1,6 @@
1
1
  # Context doc templates
2
2
 
3
- These are the shapes `cyc context lint` checks and `cyc context review --write` produces. Names and events below are illustrative; substitute observed findings, actual checks and acceptance evidence.
3
+ These are the shapes context lint checks and active-run context prepare/finish produces. Plan canonical paths before scope freezes; historical catch-up with context review --write requires --update-run ID. Names and events below are illustrative; substitute observed findings, actual checks and acceptance evidence.
4
4
 
5
5
  ## docs/context/INDEX.md
6
6
 
@@ -11,12 +11,10 @@ Read this index first, then only the docs whose Covers match the paths you are a
11
11
 
12
12
  | Component | Covers | Doc | Last AI change | Lessons | Reason to read |
13
13
  | --- | --- | --- | --- | --- | --- |
14
- | Context evidence helper | methods/cyc-context/scripts/**, methods/cyc-context/references/evidence.md | [Evidence helper](evidence.md) | 2026-10-02 · run 7f3a9c1e · Capture selected bytes | 3 · latest: Capturing the whole repository invalidates useful context | Byte evidence for selected claims |
15
- | Context doc layout | methods/cyc-context/** | [Templates](templates.md) | none recorded | none | The fixed layout and its rules |
16
- | Error ledger | all | [Ledger format](../../cyc-error-ledger/references/entry-format.md) | reference row | reference row | Past errors, causes, and fixes tried |
14
+ | Context layout | methods/cyc-context/** | [Layout](templates.md) | none recorded | none | Layout illustration |
17
15
  ```
18
16
 
19
- Links are relative to `INDEX.md`; in a project index the Doc cell is the doc's file name, `homework.md`, in a Markdown link. `Component`, `Covers`, `Doc`, `Last AI change` and `Lessons` are required (`Area` and `Record` are accepted aliases); other columns are kept as written. `--write` fills the two AI columns from the doc and adds them to an older index. A row whose Doc link points outside `docs/context/` is a reference row: matched like the others, never written.
17
+ Links resolve relative to INDEX.md. Component/Covers/Doc/Last AI change/Lessons are required (Area/Record aliases supported); extra columns survive refresh. Focused canonical rows own feature retention; outside-directory references are useful matched context, never substitute feature records.
20
18
 
21
19
  ## docs/context/<component>.md
22
20
 
@@ -44,11 +42,6 @@ Completion is a persisted boolean; lists and counts derive from the same selecto
44
42
  **Decisive check:** These new tests fail on the original code: week view count (check unit). Checks: unit passed (exit 0).
45
43
  **Files:** src/homework/select.ts@sha256:9b1c2d3e4f50, src/homework/week.tsx@sha256:0a1b2c3d4e5f, test/homework.test.js@sha256:5e6f708192a3
46
44
 
47
- ### 2026-09-25 · run 3c9d2e1f-7a8b-4c9d-8e0f-1a2b3c4d5e6f · Mark homework finished
48
- **Changed:** finished is a persisted boolean; loadAll defaults it for legacy records.
49
- **Learned:** Hiding finished items with CSS only left the count wrong (count test failed at step 2). Ledger ERR-012: resolved · Homework finished flag missing after reload
50
- **Decisive check:** These new tests fail on the original code: legacy-record load, double-mark (check unit). Checks: unit passed (exit 0).
51
- **Files:** src/homework/finish.ts@sha256:1a2b3c4d5e6f, src/storage.ts@sha256:a1b2c3d4e5f6, test/homework.test.js@sha256:f6e5d4c3b2a1
52
45
  ```
53
46
 
54
- Entries are newest first. The `**Files:**` items are `path@sha256:<prefix>` as `--write` records them, or `path@<commit>` when written by hand. The Current view is yours: the tool never edits it, so update it when an entry changes the rule a reader should follow, and name who accepted an adopted decision. A hash identifies the bytes an entry describes; it does not establish that the claim is correct or that anyone approved it.
47
+ Entries are newest first. The `**Files:**` items are `path@sha256:<prefix>` as `--write` records them, or `path@<commit>` when written by hand. The Current view is authored knowledge: preparation preserves it unless you supply learning.context/records with actual currentView text. Update it when an entry changes the rule a reader should follow, and name who accepted an adopted decision. A hash identifies the bytes an entry describes; it does not establish that the claim is correct or that anyone approved it.
@@ -16,7 +16,7 @@ Leave the engineer able to follow and maintain the change: summarize the before/
16
16
  3. **Frame impact for the user, then the maintainer.** What they will see, then what changed in the code.
17
17
  4. **Include and display one visual that carries information, even under the 1,000-character limit.** Choose it with the answer: a diagram or labeled flow for processes and relationships, a data chart for quantities, a before/after for changes, or a table for comparisons and status. Use available rendering tools when helpful; otherwise use a readable text flow. A bare link, decoration, or a table that restates the paragraph above it doesn't count. Check that the visual makes the main idea easier to grasp, not merely that its markup passes the gate. Every number or output in it must be one you observed this run: take "before" values from running the original code, never from reading it. If you did not run the old code, describe the change without a before-value.
18
18
  5. **Use the shared review artifact.** Link `.cyc/runs/ID/review.md`, generated from handoffs and receipts, alongside relevant files/diffs. Refresh it with `run review` after external changes and reuse it for an authorized PR. Update underlying records rather than maintaining competing reports.
19
- 6. **Retain what the next task needs.** Follow the [Deliver assessment](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order): record verified reusable facts, actual adopted decisions, and error history with evidence and limits; keep unverified hypotheses or undecided proposals explicit in run-local notes. Name the canonical component/index path so a teammate can find the learning; identify local-only evidence. Bug fixes and recorded failures require the selected `ledgerPath`; when run-local, explain in `errorHistory.reason` that shared-log promotion remains pending authorized scope. Do not claim the shared log was updated. Finalize durable updates before final verification; source changes afterwards require fresh Verify. No reusable finding is a valid `learning: none` with a reason. The Deliver handoff records `contextDocs`, the component docs under `docs/context/` among the artifacts and `learning.artifacts`; a mapped component whose doc the run did not touch is what `cyc context review --run ID` proposes an entry for, from the run's record, and `--write` appends it and refreshes the index (see [Context](../cyc-context/SKILL.md)).
19
+ 6. **Deliver retained feature knowledge.** Required feature/shared records and index must already be authored and source-bound before final verification; finish enforces the [Context contract](../cyc-context/SKILL.md). Report their canonical paths and local-only receipt limits. Index, ledger, recipes and runtime logs are supporting records, excluded from contextDocs. Learning:none is proportional only for genuinely nonfeature work. Preserve explicit restrictions as incomplete/pending. Bug fixes and recorded failures require the selected ledgerPath; run-local error history must disclose pending shared promotion. Do not infer adoption from passing tests. Completed-run catch-up needs a new scoped update and fresh checks; editing context then generating a packet cannot restore verification.
20
20
  7. **Check session readiness and say what is left.** The latest run's completion is not the whole session's readiness. Codex/Claude `packet` preflight includes current-request run status; `cyc readiness --session ID` provides a read-only diagnosis. Without mapped hook state, supply the actual request start with `--since ISO_TIMESTAMP`; that explicit window does not replace the Stop hook. Cursor packet preflight leaves controller readiness unverified, so inspect its actual request window separately. Preserve stopped originals and failed attempts; do not start replacements or change a cutoff to evade a block. Disclose accepted pre-existing failures (each with its reason), unverified rows, known limits, and a decision only if one remains. No forced "next task."
21
21
 
22
22
  ## Shape for code work
@@ -36,7 +36,7 @@ Your call: a decision, only if one exists.
36
36
 
37
37
  The first sentence states the result or the blocker. Every claim has a label. The visual is included in the response, its form fits the subject, and it adds understanding. Limits are stated. The length honors the conversation's `limit on` or `limit off` setting; shortening prose must not silently remove the visual.
38
38
 
39
- If the host gate provides a review token and packet path: in Claude Code and Codex, a completed `run finish` writes the packet from the run's record, and the Stop gate checks the reply itself. Otherwise (no completed run, files changed after finish, or Cursor) write it with `cyc packet`; Cursor's packet carries the exact final response. Before sending, draft the reply in `.cyc/runtime/reply.md` and run `cyc check-reply .cyc/runtime/reply.md --session <ID>`: it reports the character count, how much to cut, and whether the visual is recognized, writes nothing, and is the same check the gate applies. If hooks aren't active, say that automatic enforcement is unverified.
39
+ If the host gate provides a review token and packet path: in Claude Code and Codex, a completed `run finish` writes the packet from the run's record, and the Stop gate checks the reply itself. Otherwise (no completed run or Cursor) write it with `cyc packet`; changed covered files require fresh verification first; Cursor's packet carries the exact final response. Before sending, draft the reply in `.cyc/runtime/reply.md` and run `cyc check-reply .cyc/runtime/reply.md --session <ID>`: it reports the character count, how much to cut, and whether the visual is recognized, writes nothing, and is the same check the gate applies. If hooks aren't active, say that automatic enforcement is unverified.
40
40
 
41
41
  ## Anti-patterns
42
42
 
@@ -25,7 +25,7 @@ time stage decision why evidence who
25
25
 
26
26
  Write a capsule of five bullets or fewer: destination, current stage, what's proven (with evidence pointers), what's open, and the next single action. Tag each open thread with one status: `[done]`, `[in progress]`, `[blocked: reason]`, or `[dropped: reason]`. Untagged threads count as not done.
27
27
 
28
- Point to canonical component context and its relevant constraints/checks instead of copying them into the capsule. Retain verified reusable findings through [Context](../cyc-context/SKILL.md) before final verification; a local decision log alone is not shared project memory. Keep adoption status and technical evidence distinct.
28
+ Point to canonical component context and its relevant constraints/checks instead of copying them into the capsule. Retain verified reusable findings through [Context](../cyc-context/SKILL.md) before final verification; a local decision log alone is not shared project memory. Each new feature and meaningful contract change leaves its planned canonical target-project record/index before completion; use finish/context prepare and preserve restrictions as pending. Completed-run catch-up is a new scoped update with fresh verification, not an edit to old evidence. Keep adoption status and technical evidence distinct.
29
29
 
30
30
  ## When resuming
31
31