cyc-stack 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/README.md +25 -254
  5. package/bin/cyc.mjs +61 -23
  6. package/docs/assets/cyc-method-library.svg +1 -39
  7. package/docs/assets/cyc-overview.svg +1 -44
  8. package/docs/assets/cyc-workflow-diagram.svg +1 -415
  9. package/docs/context.md +13 -23
  10. package/docs/cyc-workflow.md +31 -84
  11. package/docs/installation.md +66 -124
  12. package/docs/onboarding-recovery.md +31 -37
  13. package/docs/project-tools.md +16 -10
  14. package/docs/response-standard.md +16 -32
  15. package/docs/runtime.md +22 -224
  16. package/docs/skill-contract.md +13 -56
  17. package/docs/task-context.md +56 -0
  18. package/docs/validation.md +2 -0
  19. package/docs/work-assessments.md +25 -92
  20. package/methods/cyc-build/SKILL.md +8 -53
  21. package/methods/cyc-challenge/SKILL.md +4 -0
  22. package/methods/cyc-context/SKILL.md +20 -53
  23. package/methods/cyc-context/references/evidence.md +1 -1
  24. package/methods/cyc-context/references/templates.md +4 -11
  25. package/methods/cyc-deliver/SKILL.md +6 -42
  26. package/methods/cyc-remember/SKILL.md +1 -1
  27. package/methods/cyc-scout/SKILL.md +17 -51
  28. package/methods/cyc-setup/SKILL.md +7 -19
  29. package/methods/cyc-verify/SKILL.md +15 -66
  30. package/methods/cyc-verify/references/recipe.md +2 -0
  31. package/package.json +9 -1
  32. package/plugin.json +1 -1
  33. package/rules/cyc-delivery.mdc +33 -33
  34. package/scripts/browser-audit.mjs +53 -0
  35. package/scripts/catalog.mjs +9 -2
  36. package/scripts/codex-host.mjs +178 -0
  37. package/scripts/context-review.mjs +212 -29
  38. package/scripts/delegation.mjs +156 -0
  39. package/scripts/execution.mjs +51 -0
  40. package/scripts/onboarding.mjs +14 -1
  41. package/scripts/packet.mjs +21 -6
  42. package/scripts/project-tools.mjs +43 -20
  43. package/scripts/recovery.mjs +20 -1
  44. package/scripts/response-mode.mjs +8 -0
  45. package/scripts/run-worker.mjs +4 -0
  46. package/scripts/runtime.mjs +648 -68
  47. package/scripts/swarm.mjs +154 -0
  48. package/scripts/task-context.mjs +164 -0
  49. package/scripts/work-review.mjs +32 -10
  50. package/skills/cyc/SKILL.md +29 -70
package/docs/context.md CHANGED
@@ -1,40 +1,30 @@
1
1
  # Project context
2
2
 
3
- CYC keeps useful project knowledge in the repository so a fresh chat or teammate can find the relevant reasoning without replaying the original conversation. The agent selects and interprets that knowledge; structural validation does not establish that every recorded claim is correct.
3
+ Every new feature leaves a focused canonical record and index row in the target project. Meaningful changes update that feature and affected shared-component knowledge. The next agent should find capability boundaries, contracts, choices, failures, checks and limits without the original chat. A handoff, recipe, setup guide or ignored receipt alone is insufficient.
4
4
 
5
- ## What belongs in context
5
+ Read docs/context/INDEX.md, then matched records and relevant error history. Revalidate consequential claims against current source/dependencies. A configured context.directory can reuse a genuine equivalent project convention; never substitute the installed engine's development index.
6
6
 
7
- Keep decisions and their reasons, integration constraints, failed approaches worth avoiding, and checks that protect the behavior. Reference the supporting source or observed result. Separate verified facts from proposals and assumptions. Update a current view when the implementation changes; retain historical entries as history.
7
+ ## Normal workflow
8
8
 
9
- Use one index at `docs/context/INDEX.md`, with path coverage and links to the relevant component notes. Read the matching notes and error-ledger entries for the task. Do not load every component or the entire run history by default.
9
+ Scout/Start plans canonical records and representative entrypoints before scope freezes. Finish prepares/validates authored knowledge, History/source evidence and index before final checks. Missing/stale context returns needs-context with remaining input; fill learning.context or use context prepare --run ID for earlier feedback. Explicit restrictions remain pending without unauthorized writes. See the [Context method](../methods/cyc-context/SKILL.md) for schemas, fixed layout and recovery.
10
10
 
11
- The [Context method](../methods/cyc-context/SKILL.md) defines the component layout and retention procedure. [Work assessments](work-assessments.md) describe learning dispositions and the distinction between technical evidence and adopted decisions.
11
+ Context-only upkeep can bind unchanged implementation files from its focused owner's Covers. Missing anchors remain pending; self/index hashes and unrelated source cannot substitute. Completion guidance retains the exact remaining input and owned command.
12
12
 
13
- ## Inspect and maintain context
14
-
15
- From the CYC source checkout:
16
-
17
- ```sh
13
+ ```text
18
14
  node bin/cyc.mjs investigate --path src/orders
19
15
  node bin/cyc.mjs context lint
20
- node bin/cyc.mjs context review
16
+ node bin/cyc.mjs context review --run SOURCE_ID
21
17
  node bin/cyc.mjs context measure --path src/orders
22
18
  ```
23
19
 
24
- Replace `src/orders` with the paths relevant to the task. In an installed application, use `node .cyc/engine/bin/cyc.mjs` instead. These inspection commands do not run the project's verification recipes.
25
-
26
- `context lint` checks document/index structure and evidence freshness where supported. A valid index can still contain an incorrect or unhelpful explanation. Recheck consequential statements against current code and dependencies.
27
-
28
- `context review` proposes entries from recorded completed work. Review the proposed retention before using `--write`; keep changes within the authorized scope. Existing records and reference rows are handled according to the [project-tools contract](project-tools.md).
29
-
30
- ## Interpret reading-size measurements
20
+ Installed projects use .cyc/engine/bin/cyc.mjs. Read-only inspection executes no recipe. Historical catch-up writes need a new implementation update with a required canonical plan and executable final checks (--write --update-run ID). Preserve old receipts, record the repair under its actual run/date and verify final files. A reply packet cannot restore evidence after context changes.
31
21
 
32
- `context measure` reports the current index and matching linked documents, the wider context folder, and available local run records. It counts matching local documents once, including multiple links in a row, and avoids counting the index twice. Repeated links do not increase the selected size.
22
+ ## Evidence limits
33
23
 
34
- Character counts are Unicode code points. Estimated tokens use approximately four characters per token; no model tokenizer is run. Controller run records are not chat transcripts. A source-only machine may have history that a teammate's checkout does not contain.
24
+ Lint validates structure, mapping and supported freshness, not semantic truth or adoption. Optional manifests bind selected bytes, not complete dependencies. Context measure counts unique selected local files, estimates tokens as Unicode characters/4 and cannot see chat usage, billing or savings. Run records are not transcripts and may exist only in ignored local storage.
35
25
 
36
- These are file-size measurements. They do not establish provider billing, tokens saved, faster work or successful context reuse. Rerun the measurement for the current files rather than relying on historical figures.
26
+ To evaluate actual reuse, give a fresh chat/teammate a related bounded task without the original conversation; observe discovery, reading, revalidation and successful use with real checks. Record missed/stale guidance. Parser/fixture passes alone do not establish future model quality or measured workflow savings.
37
27
 
38
- ## Check that knowledge transfers
28
+ ## Consolidate delegated findings
39
29
 
40
- Complete one bounded task and retain the useful constraint with its evidence. Then use a fresh chat or teammate, without the original conversation, for a related change. Observe whether the relevant record is found, read, revalidated and used. Run the new task's real checks and inspect the result. Record missed or stale guidance honestly.
30
+ [Task context](task-context.md) reconciles read-only worker evidence into one parent document and feeds existing canonical feature owners before checks. It creates no permanent worker context documents and waives no retention, proof or freshness requirement.
@@ -1,21 +1,11 @@
1
1
  # CYC engineering workflow: decisions, evidence, and recovery
2
2
 
3
- Open the [connected workflow diagram](assets/cyc-workflow-diagram.svg) for the responsibilities, recovery arrows, project knowledge, and separate delivery outcomes. The sections below explain the steps. A [quick overview](assets/cyc-overview.svg) is also available. The runtime distribution uses compact vector diagrams; bitmap and interactive HTML exports stay in the source checkout.
3
+ [Workflow](assets/cyc-workflow-diagram.svg), [overview](assets/cyc-overview.svg), [17-method map](assets/cyc-method-library.svg) and [method roles](cyc-method-map.md) cover **Scout → Build → Verify → Deliver**. Twelve responsibilities sit inside these stages. Other routes use the [catalog](../catalog/playbooks.json); Teach adds requested lessons.
4
4
 
5
- Skill labels inside the numbered steps and recovery cards show where existing CYC methods help. Open a numbered step for its selection trigger, a worked CSV-export example, direct method links and the evidence it passes forward. These placements describe agent-selected methods, not automatic dispatch or additional controller stages. Ordinary engineering explanation belongs throughout the work; Teach adds a lesson only when requested.
6
-
7
- The common implementation route does not show the entire library. See the [full map of all 17 methods](assets/cyc-method-library.svg) and [method roles, examples and routing limitations](cyc-method-map.md), including Setup, Remember, Explore, Correct and Reflect. CYC has 15 playbooks; planning, exploration, teaching, resumption and evaluation use other recorded sequences.
8
-
9
- CYC moves work forward when the next stage has usable evidence. A failure sends work back to the earliest affected decision, so the agent can repair the cause and regenerate the conclusions that depended on it. The engineer should be able to inspect both the change and the reasoning for taking that route.
10
-
11
- This document describes the current local implementation and its method instructions for the common feature, bug-fix, and refactor routes. The controller records **Scout → Build → Verify → Deliver**. The twelve responsibilities below occur inside those stages; they are not twelve machine-enforced states. Other routes use the [playbook catalog](../catalog/playbooks.json).
12
-
13
- **Read the boundaries literally:** the agent investigates, explains, chooses checks, and judges meaning. The controller validates recorded fields, stage identity, covered file state, configured command results, and budgets. A required evidence field does not prove the evidence is true.
5
+ Explain consequential behavior. Agents investigate/judge; the controller checks records, stages, files, commands and failure limits. Fields, hashes and green commands certify no truth/comprehension. SVGs ship; bitmap/HTML exports and docs/maintainers/cyc-workflow-reference.md stay source-only.
14
6
 
15
7
  ## 1. The engineering path
16
8
 
17
- Each box describes work and the evidence it produces. The separate recovery map below explains backward movement; those returns are deliberately not repeated across this entire diagram.
18
-
19
9
  ```mermaid
20
10
  flowchart TB
21
11
  subgraph SC["SCOUT — establish what must change and what must remain true"]
@@ -63,59 +53,43 @@ flowchart TB
63
53
  DC --> OUT["Ready handoff when completion and delivery checks pass<br/>Team review and publication follow project authorization"]
64
54
  ```
65
55
 
66
- Steps 8 and 9 can interleave: record attempts when they happen, not after reconstructing the whole run. Step 9 can finish during Verify preparation, but covered documentation edits must precede the final executable checks. Missing evidence is repaired; an unavailable prerequisite is disclosed as a blocker.
56
+ Record attempts when they happen. Steps 8/9 can interleave, but finish authorized source, context/index and ledger edits before final executable checks. Missing prerequisites remain blockers.
67
57
 
68
58
  ### Scout: why these seven responsibilities precede implementation
69
59
 
70
- **1. Define observable success.** Translate the request into outcomes that a reviewer could distinguish from a plausible-looking implementation. For an export, “a CSV downloads” is weaker than “all matching records are exported and existing access restrictions still apply.” Preserve constraints and exclusions. Explicit criteria give verification a stable target; the controller requires each configured criterion ID to survive handoffs. The agent still owns whether those criteria describe the right product behavior. Explain the difference between a working control and the promised outcome.
71
-
72
- **2. Select the route and risk treatment.** Choose a playbook before starting the tracked run. Investigation, teaching, verification, and implementation have different work requirements. Identify consequential permissions, stored-data changes, public interfaces, or other risk in this task. Configure meaningful project checks before the run; configuration is captured and protected during it. Explain why the selected checks and review depth match the changed behavior. A high-risk plan gets a focused Challenge pass; ordinary work proceeds without that extra pass.
73
-
74
- **3. Retrieve matched history.** Read relevant component context, the capability index if present, and the selected error ledger. Look for the reason an interface behaves as it does, the existing implementation to reuse, and approaches already shown to fail. Produce references to the matched material or an honest account of no relevant history. This changes the starting hypothesis and can avoid repeating investigation; it does not establish a measured token or dollar saving. Explain which prior decision affects today's change.
75
-
76
- **4. Revalidate history against the working project.** Compare recorded claims with the actual covered components, relevant revisions, and uncommitted changes. A note may describe an old design even when the note itself is readable. Confirm useful claims and label contradictions or uncertainty. The assessment records freshness reasoning and fingerprints referenced files; the agent must actually perform the comparison. Explain any outdated assumption before using a new one.
77
-
78
- **5. Trace impact and choose the design.** Follow the affected input through state, services, interfaces, persistence, and readers that exist in the project. Name the consumers whose behavior must remain consistent, then select reuse, extension, repair, or new construction with a reason. Pair each consumer with a behavior check. An affected area is a verification concern, not permission to broaden the feature. Explain where the change belongs and why an alternative would create a consequential cost or risk.
79
-
80
- **6. Explain the causal path and resolve decisions.** Connect observed behavior to the mechanism producing it, then explain what will change and what must remain true. Ask only when an unresolved answer changes the solution. A settled request can be recorded as clear; confirmed alignment requires actual confirmation. The controller rejects a passing Scout assessment marked needs-input. Supplying an explanation does not establish comprehension, and silence does not establish approval.
81
-
82
- **7. Plan slices that can be evaluated.** Sequence implementation around observable behavior, not a list of arbitrary files. Identify how the first slice can fail, how later slices depend on it, and what broader checks will cover the result. For high-risk work, challenge consequential assumptions and revise the plan if evidence defeats them. This is method guidance inside Scout; the runtime does not independently judge the plan or enforce a separate Challenge state for the fast routes. Explain the dependency that determines the sequence.
60
+ 1. **Define success.** Preserve observable outcomes, constraints, exclusions and criterion IDs; explain what checks distinguish. Criteria quality needs judgment.
61
+ 2. **Choose route/risk treatment.** Select playbook and meaningful checks before start; captured config is protected. Match review depth to changed behavior; challenge high-risk assumptions.
62
+ 3. **Retrieve history.** Read index, matched records, capabilities and ledger. Cite applicable decisions/failures or their absence.
63
+ 4. **Revalidate.** Compare claims with current code/revisions/dirty files. Retain file evidence, freshness reasoning, contradictions and unknowns.
64
+ 5. **Trace/design.** Follow writers, state, services, persistence and readers. Name consumers/checks and justify reuse/extension/repair/creation. Impact grants no broader authority.
65
+ 6. **Settle decisions.** Explain behavior, mechanism, change and invariants. Ask consequential questions only. Clear requests need no invented approval; confirmation needs actual confirmation. needs-input cannot pass Scout. Silence is not approval.
66
+ 7. **Plan slices.** Sequence observable outcomes, failures, dependencies and checks. Challenge defeated high-risk premises; fast routes add no Challenge state.
83
67
 
84
68
  ### Build: keep changes and explanations connected
85
69
 
86
- **8. Implement a tested slice.** For a bug, reproduce the defect before claiming a repair; for a refactor, preserve a behavior check; for a feature, exercise the intended new outcome. Confirm that a new regression check can detect the original defect, then implement the change and inspect its effect on named consumers. Existing checks or a justified skip can cover work with no new testable behavior. Focused failures trigger diagnosis, not blind repetition. Record failed attempts in the selected ledger and explain the affected state or interface, why the repair belongs there, and what the focused result establishes. These actions are method responsibilities; CYC cannot see an unreported attempt.
70
+ 8. **Tested slices.** Reproduce bugs, characterize refactors and exercise feature outcomes; prove relevant original behavior. Use existing checks/reasoned exemption when no new testable behavior exists. Inspect diffs/consumers, diagnose failures and ledger actual attempts/results. Explain affected state/interface and repair location.
71
+ 9. **Knowledge.** Plan required component owners/index before Build. Retain capability, contracts, adopted decisions, evidenced failures, dependencies, checks and issues. Preserve/supersede history explicitly and bind paths/current files, including dirty evidence.
87
72
 
88
- **9. Retain useful project knowledge.** For affected components or areas with reusable knowledge, create or update `docs/context/<area>.md` and its path-matched row in `docs/context/INDEX.md`. Name the document for the component or area, not the task or conversation. Append a dated entry preserving verified facts, actual adopted decisions, rejected alternatives, dead ends with evidence, non-obvious dependencies or gotchas, verification references, and open issues. Record covered paths and the reviewed revision; for a dirty checkout, include the base commit plus covered-file evidence. Explicitly supersede outdated entries while retaining their history.
73
+ docs/context/<area>.md holds component reasoning; docs/context/INDEX.md maps paths/freshness; the ledger holds failures/causes. Name by component, not task/chat. Keep hypotheses pending; adoption needs acceptance. No filler/generic waiver of feature retention. Explain retrieval/revalidation. Deliver records disposition, not source edits.
89
74
 
90
- This step produces inspectable component knowledge, not just a delivery summary:
91
-
92
- | Output | What it preserves | How subsequent work uses it |
93
- | --- | --- | --- |
94
- | `docs/context/<area>.md` | Why the component behaves this way, what failed, dependencies, checks and known limits | Step 3 retrieves the matching document; step 4 checks its freshness against the current code |
95
- | `docs/context/INDEX.md` | Component/area, covered paths, document location, reviewed revision and a short summary | Locates relevant history from the files being changed |
96
- | Selected error ledger | Failed attempts, observed results and confirmed causes | Supplies failure evidence that component entries can reference without duplicating the entire log |
97
-
98
- For example, an export-component entry could preserve why exports query all authorized matching records rather than the current UI page, the failed page-state approach and its evidence, and the regression check covering pagination. This is an illustrative entry, not a claim about this project's components.
99
-
100
- Finish authorized durable context/index and ledger edits before final verification because those files belong to the candidate being checked. Retain useful verified technical facts with their evidence and limits. Keep unverified hypotheses and undecided proposals explicitly pending; mark a decision adopted only with actual acceptance. Do not create filler documents when there is no reusable finding. Explain the retained reasoning and how a future engineer would locate and revalidate it. Deliver records this disposition; it is not a second opportunity to mutate verified source. The existing component-context method and templates define this responsibility; the diagram does not add a new runtime state or claim the controller proves documentation quality.
75
+ [Task delegation](task-context.md) preserves parent authority and one document; worker results cannot replace parent proof/review/checks/retention.
101
76
 
102
77
  ### Verify: require both executed behavior and explained judgment
103
78
 
104
- **10. Prove tests and exercise the promised behavior.** The controller runs required original-code proof when it is missing or outdated: changed tests for feature and bug-fix runs must fail on the original code; refactor tests must pass there. An explicit exemption records its actual reason and limits. Run relevant journey or recipe checks and every configured command. Map results to acceptance criteria and identified consumers; include rejected cases where they protect the requirement. The controller retains command arguments, exit status, output, and a covered source fingerprint. It rejects a passing receipt when commands fail or covered source changes during execution. It does not know whether a zero-exit command meaningfully tested the product. Explain which path each consequential check exercises and what remains outside its coverage.
105
-
106
- **11. Review whether the implementation means the right thing.** Review the current diff for intent, affected consumers, and project conventions. Tests can pass while encoding an incomplete assumption, missing a consumer, or accepting the wrong behavior. Record findings as resolved or dismissed with evidence; open findings prevent a passing assessment. Every consumer named in Scout needs passing evidence; newly discovered consumers also belong in the review. Label self-review and peer review accurately. Explain the consequence of a finding and why its resolution addresses that consequence. Required fields make the judgment inspectable, not independently true.
79
+ 10. **Prove/verify.** Changed feature/bug tests must fail on originals; refactor characterization must pass. Classify interface/setup/behavior honestly; exemptions retain reasons/limits. Run relevant journeys/recipes, negatives and all configured commands. Map criteria/consumers. Receipts bind arguments/status/output/source; failure/drift rejects passing verification. Explain omissions.
80
+ 11. **Review meaning.** Inspect intent/consumers/conventions in the current diff. Resolve/dismiss findings with evidence; open findings block. Evidence every Scout consumer and add discoveries. Label self/fresh/peer provenance.
107
81
 
108
82
  ### Deliver: expose the basis for acceptance
109
83
 
110
- **12. Account for the result and make it maintainable.** Record every criterion's outcome, material limits, retained-learning disposition, and error-history evidence. Bug-fix runs and runs with recorded failures require the selected ledger. Reuse the generated review, which refreshes throughout recorded mutations. A passing Deliver handoff needs current executable evidence where required and a current semantic assessment; run complete rechecks final conditions and artifact hashes. The developer receives the before/after mechanism, important trade-offs, checks, and locations needed for maintenance. Project review and publication require the applicable authorization.
84
+ 12. **Account for outcomes.** Record criteria, limits, learning/history; bugs/failures require the ledger. Reuse the review; Deliver needs current executable/semantic evidence. Completion rechecks conditions/artifacts. Supply mechanism, trade-offs, checks and maintenance pointers. Publication needs authorization.
111
85
 
112
- The host delivery hook, when active, separately checks response readiness and relevant session runs. A ready handoff requires completed runs; a recorded blocked or exhausted outcome permits an honest blocked handoff. An actively running unfinished run cannot be concealed by a polished final answer. Codex and Claude provide the response through their native Stop event; Cursor requires the exact response in its packet. Finish-generated records can therefore omit a copied response in Codex and Claude. Formatting rules follow the project's settings. The hook does not establish that the engineer understands the work.
86
+ run start can record Scout; run finish can combine Build, proof/judgment, verification, Verify/Deliver and completion. Sharing local evidence needs authorization.
113
87
 
114
- These are responsibilities, not separate required tool calls. On the ordinary successful path, `run start` can record Scout and `run finish` can combine Build recording, original-code proof, configured verification, Verify and Deliver records, and completion. The assistant performs the engineering and interprets findings; the controller validates records and runs project commands. Generated run evidence is local by default. Teams share useful context and review evidence through their own authorized project workflow.
88
+ An active host hook separately checks readiness/session runs. Ready delivery needs completion; blocked/exhausted work allows honest blocked handoffs, never concealed running work. Native Codex/Claude Stop supplies reply text; finish may write request-bound evidence. Cursor needs the exact-response packet. Follow [response rules](response-standard.md#engineering-understanding-throughout-the-work), actual capability/current hook context. Files/simulations prove no activation.
115
89
 
116
90
  ## 2. Why the process loops, and why the return destination matters
117
91
 
118
- A verification failure is new evidence about the implementation, the design, the requirements, or the check itself. Those are different problems. Repeating implementation without distinguishing them can preserve the original error and accumulate patches.
92
+ Preserve results; confirm intended build, data and requirement.
119
93
 
120
94
  ```mermaid
121
95
  flowchart TB
@@ -132,57 +106,30 @@ flowchart TB
132
106
  T --> RE
133
107
  ```
134
108
 
135
- The diagram shows the **engineering destination**, not a mandatory restart for every failure. A defect discovered before a passing Verify handoff can be repaired within the active stage. When returning to a recorded earlier stage is necessary, run retry rewinds there and invalidates dependent later handoffs and executable verification. Changes after a passing Verify handoff require returning to Verify, fresh checks, and a current semantic review. Fast routes map detailed impact/design destinations back to Scout.
136
-
137
- | Evidence that changes the route | Why the return is necessary | What must be established again |
138
- | --- | --- | --- |
139
- | A correctly specified export omits the last page because its loop stops early | The design still works; a local implementation violates it | The failing pagination case, affected consumers, current configured checks and review |
140
- | Export reuses a UI-only filter while server access rules differ | The design relied on the wrong source of truth; another patch to pagination cannot repair that premise | Relevant context and impact, design rationale, access consumers, implementation and verification |
141
- | A passing review is followed by another covered source edit | The old result describes different bytes | Executed checks and semantic review for the new candidate |
142
- | A check hits an old build or asserts the wrong requirement | The observation cannot support the intended conclusion | Correct target or justified assertion and a fresh result; do not simply lower the threshold |
143
- | A required service or decision is unavailable | More code cannot supply the missing prerequisite | An honest blocker and the smallest needed input; verification after work resumes |
144
-
145
- When a legitimate correction requires changing protected verification configuration or run criteria, explain it and start a new authorized run while retaining the old outcome. Do not weaken the current run to pass.
109
+ These are destinations, not mandatory restarts. Before passed Verify, repair may stay active. Recorded returns use run retry, invalidating dependent handoffs/verification. Post-Verify edits require Verify plus fresh checks/review. Fast routes map impact/design returns to Scout. Re-establish affected source/consumer/check/review evidence.
146
110
 
147
- Controller guard checks at record, verification, retry, resume, and completion detect protected or out-of-scope file changes. A detected violation sets the run to **halted** and preserves the files for review; it does not automatically roll them back. Halted and exhausted runs are terminal. A blocked run may resume after its prerequisite is resolved, subject to guard checks and the remaining budget. A halted run requires resolving scope or authorization before starting a new run. This is a guard at controller operations, not continuous filesystem monitoring.
111
+ Protected criteria/config changes need explained, authorized new runs retaining old outcomes; never weaken the active run. Record/verify/retry/resume/complete guards halt on protected/out-of-scope changes, preserving files without rollback or continuous monitoring. Halted/exhausted runs are terminal. Blocked work may resume after resolution within guards/remaining allowance; halted work needs resolved scope/authority before a new run.
148
112
 
149
- Recovery uses a shared configurable failure budget across stages: defaults are three recorded failures and two repeated unchanged failure signatures. A stage return does not reset the allowance. The no-progress signature is a heuristic. Focused agent activity between controller calls is not continuously monitored, and the controller cannot count concealed attempts. Instructions require recording those attempts; the bounded runtime checks occur at controller operations.
113
+ Defaults share three failures/two unchanged repeated signatures across stages; returns never reset them. No-progress detection is heuristic.
150
114
 
151
115
  ### A worked example: why going back to Scout is sometimes essential
152
116
 
153
- This is illustrative, not a report of a CYC repository defect.
154
-
155
- The request is to export every order matching the dashboard filters while preserving access restrictions. The initial plan assumes the browser holds the complete filtered result. A multiple-page test shows that only the visible page reaches the export.
156
-
157
- If the server already provides the correct complete query and the export loop stops early, the repair belongs in implementation. If the browser only ever receives one page and applies different filtering from the server, the assumption behind the design is false. Return to Scout, inspect the authoritative query and access boundary, revise the impact map, and choose the correct data path before rebuilding.
158
-
159
- The explanation to the engineer should identify that distinction: “The browser only has one page, so formatting its rows cannot produce the requested export. We need the server's filtered query, with the same access restriction, and checks for both multiple pages and denied access.” The ledger retains the failed browser-only attempt and its evidence so the next task does not repeat it.
117
+ Illustrative export: an early loop exit needs Build repair; a browser holding one page/different filters defeats the design. Revisit Scout/query/access, rebuild and check pagination/denied access. Explain absent-record limits and retain the failure.
160
118
 
161
119
  ## 3. What an engineering team can inspect before trusting a result
162
120
 
163
- Trust should be attached to a particular claim and supporting evidence. CYC makes that relationship inspectable and rejects several unsupported completion paths.
164
-
165
- | Claim presented to the team | Current mechanism and inspectable record | Boundary of that assurance |
166
- | --- | --- | --- |
167
- | The delivered change addresses the agreed criteria | Every handoff preserves criterion IDs; passing Verify and Deliver require all criterion results passed with evidence | The agent and engineer must choose meaningful criteria and judge the supplied evidence |
168
- | The result still covers the candidate being handed over | Covered source fingerprints, referenced artifact hashes, verification receipts, and a semantic-review source snapshot are rechecked | Coverage has documented exclusions; external services and omitted dependencies are not frozen by a file hash |
169
- | Green commands cannot replace reviewing the change | Required intent/consumer/convention assessment; open findings and missing Scout consumer checks reject a passing handoff | Review and consumer evidence are agent-reported; this is not automatic dependency discovery or independent approval |
170
- | A failed attempt cannot be silently turned into completed work through ordinary controller operations | Shared failure budget, retry history, invalidated dependent handoffs, stage/attempt identity, terminal outcomes | Local records are editable; unreported agent actions are invisible to the controller |
171
- | The reasoning remains available after the conversation | Matched context references, selected error ledger, pending/recorded learning disposition, generated review | The agent must write accurate history, and acceptance must be real |
172
- | The engineer can follow and maintain the change | Stage-specific explanation responsibilities and qualitative delivery review | This is instruction-level behavior; there is no automated comprehension measurement |
173
-
174
- The useful question for a reviewer is: **“What evidence supports this claim, does it still describe these files, and what has not been established?”** A diagram, an agent's confidence, or a successful exit code alone cannot answer that.
121
+ Ask **what supports this claim, does it describe these files, and what remains unestablished?** Inspect criteria/results, hashes/receipts/external and excluded inputs, intent/consumer/convention findings, limits/retries/outcomes, context/ledger/learning and explanation. Editable reports cannot reveal concealed actions or certify independent approval/comprehension. Adoption needs evidence.
175
122
 
176
- For the implementation behind these claims, inspect [assessment validation](../scripts/work-review.mjs), [runtime transitions and source checks](../scripts/runtime.mjs), [source coverage](../scripts/source-snapshot.mjs), and [session run delivery rules](../scripts/run-gate.mjs). In a CYC source checkout, relevant regression checks are `test/work-review.test.mjs` and `test/runtime-adversarial.test.mjs`; repository tests are not included in the installed `.cyc/engine`. Test existence alone is not a test result.
123
+ Inspect [assessment validation](../scripts/work-review.mjs), [runtime](../scripts/runtime.mjs), [source coverage](../scripts/source-snapshot.mjs) and [session rules](../scripts/run-gate.mjs). Source regressions: test/work-review.test.mjs and test/runtime-adversarial.test.mjs; names are not results.
177
124
 
178
125
  ## Regenerating the diagram
179
126
 
180
- In the source checkout, run `npm install` (or `npm ci` with the lockfile), then `npm run build:workflow`. The generator uses the development-only `sharp` package to render the compact overview, detailed workflow and method-library PNGs before refreshing the exports. It writes the SVGs, PNG previews and embedded HTML diagram together, and synchronizes all twelve explanation titles. A missing renderer or missing HTML marker/title fails before updating the exports. There is no separate manual PNG step. Font availability may affect rendering across machines; repeated builds on the same machine should produce identical files. CYC's installed runtime ships the compact SVGs and does not need this authoring dependency.
127
+ In source, npm install (or npm ci), then npm run build:workflow uses dev-only sharp for PNG/SVG/HTML previews and twelve titles. Missing renderer/HTML marker/title fails before updates. Fonts vary by machine; same-machine repeats should agree. Installed CYC needs no authoring dependency.
181
128
 
182
129
  ## Supporting references and earlier overview
183
130
 
184
- - [Runtime contract and configurable limits](runtime.md)
185
- - [Assessment fields and learning lifecycle](work-assessments.md)
186
- - [Impact investigation](impact-analysis.md)
187
- - [Engineering explanation standard](response-standard.md#engineering-understanding-throughout-the-work)
131
+ - [Runtime](runtime.md)
132
+ - [Assessments](work-assessments.md)
133
+ - [Impact](impact-analysis.md)
134
+ - [Explanation](response-standard.md#engineering-understanding-throughout-the-work)
188
135
  - [Orchestrator](../skills/cyc/SKILL.md), [Build](../methods/cyc-build/SKILL.md), and [Verify](../methods/cyc-verify/SKILL.md)