cyc-stack 0.7.1 → 0.8.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/README.md +1 -1
- package/bin/cyc.mjs +35 -20
- package/docs/context.md +10 -26
- package/docs/project-tools.md +14 -10
- package/docs/response-standard.md +8 -32
- package/docs/runtime.md +58 -174
- package/docs/work-assessments.md +25 -92
- package/methods/cyc-build/SKILL.md +1 -1
- package/methods/cyc-challenge/SKILL.md +4 -0
- package/methods/cyc-context/SKILL.md +18 -53
- package/methods/cyc-context/references/evidence.md +1 -1
- package/methods/cyc-context/references/templates.md +4 -11
- package/methods/cyc-deliver/SKILL.md +2 -2
- package/methods/cyc-remember/SKILL.md +1 -1
- package/methods/cyc-scout/SKILL.md +17 -51
- package/methods/cyc-verify/SKILL.md +15 -66
- package/methods/cyc-verify/references/recipe.md +2 -0
- package/package.json +4 -1
- package/plugin.json +1 -1
- package/rules/cyc-delivery.mdc +33 -33
- package/scripts/browser-audit.mjs +53 -0
- package/scripts/context-review.mjs +202 -29
- package/scripts/execution.mjs +51 -0
- package/scripts/packet.mjs +21 -6
- package/scripts/project-tools.mjs +18 -16
- package/scripts/run-worker.mjs +4 -0
- package/scripts/runtime.mjs +482 -65
- package/scripts/work-review.mjs +32 -10
- package/skills/cyc/SKILL.md +24 -71
package/docs/work-assessments.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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.**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
149
|
-
2.
|
|
150
|
-
3.
|
|
151
|
-
4.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
10
|
+
## Read and plan before Build
|
|
11
11
|
|
|
12
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
20
|
+
## Author and prepare before final verification
|
|
29
21
|
|
|
30
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
30
|
+
## Inspect and catch up historical work
|
|
42
31
|
|
|
43
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
60
|
-
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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. **
|
|
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
|
|
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
|
|