cyc-stack 0.8.3 → 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.
package/docs/context.md CHANGED
@@ -8,6 +8,8 @@ Read docs/context/INDEX.md, then matched records and relevant error history. Rev
8
8
 
9
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
+ 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
+
11
13
  ```text
12
14
  node bin/cyc.mjs investigate --path src/orders
13
15
  node bin/cyc.mjs context lint
@@ -22,3 +24,7 @@ Installed projects use .cyc/engine/bin/cyc.mjs. Read-only inspection executes no
22
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.
23
25
 
24
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.
27
+
28
+ ## Consolidate delegated findings
29
+
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)
@@ -1,202 +1,144 @@
1
1
  # Installing CYC in an existing project
2
2
 
3
- CYC's project installer adds skill copies and response-hook configuration to an existing project. It does not change global settings, install a marketplace, rewrite project instructions, edit the application's package.json, or execute the application's scripts. Node.js 20 or later is required on the machine running the AI tool; the target project can use any language.
3
+ CYC installs project-local skills/engine/hooks, preserving application instructions/package.json/dependencies and unrelated hooks. No global changes or application-script execution. The AI host needs Node.js 20+; applications may use any language.
4
4
 
5
- CYC is [published on npm](https://www.npmjs.com/package/cyc-stack). The package and source checkout carry a top-level [INSTALL.md](../INSTALL.md) guide covering installation, AI-chat setup and a first task. A reviewed checkout or archive also works. Downloading the npm package does not activate a project: `init` performs that explicit step, while a complete native plugin uses project activation through its Setup method.
5
+ Follow [INSTALL.md](../INSTALL.md) for the [published npm package](https://www.npmjs.com/package/cyc-stack), route selection and setup request. From the target root:
6
6
 
7
- Run `npx cyc-stack@latest init` from the target project root to install the latest published release. No flags are required. npm may ask before downloading the package. To save a development dependency in `package.json`, run `npm install --save-dev cyc-stack`, then `npx cyc-stack init`. Downloading the package alone does not set up project integration. After installation, reload your AI host and ask `/cyc` to set up the project's checks.
7
+ ~~~text
8
+ npx cyc-stack@latest init
9
+ ~~~
8
10
 
9
- For a source checkout, use `node bin/cyc.mjs init --project PATH` from the reviewed CYC checkout. Hosts are auto-detected from `CLAUDE.md`/`.claude/`, `AGENTS.md`/`.agents/`/`.codex/`, and `.cursor/`/`.cursorrules`; with no signal, all three are set up. Use `--hosts` to choose explicitly and `--dry-run` to inspect the plan:
11
+ Reload and ask /cyc to configure checks; download alone does not activate CYC. From a reviewed checkout:
10
12
 
11
- ```text
13
+ ~~~text
12
14
  node bin/cyc.mjs init --project "/absolute/path/to/project" --hosts claude,codex,cursor --dry-run
13
15
  node bin/cyc.mjs init --project "/absolute/path/to/project"
14
16
  node bin/cyc.mjs doctor --project "/absolute/path/to/project"
15
17
  node bin/cyc.mjs uninstall --project "/absolute/path/to/project" --dry-run
16
- ```
18
+ ~~~
17
19
 
18
- The plugin route is an alternative: install the `cycstack` plugin from the host marketplace (see the README), then run `cyc activate` in a project (`/cyc set up this project` handles this). Activation writes only `.cyc/config.json` and `.cyc/.gitignore`; the plugin supplies skills, hooks, and the engine. Plugin hooks do nothing in projects without `.cyc/config.json` and defer to a project install when one exists. Once installed, the project-local CLI is `.cyc/engine/bin/cyc.mjs`. The underlying supported API is:
20
+ CLI detection uses CLAUDE.md/.claude, AGENTS.md/.agents/.codex and .cursor/.cursorrules; no signals selects all three. --hosts overrides selection. Installed CLI: .cyc/engine/bin/cyc.mjs.
19
21
 
20
- ```js
21
- import { installProject, doctorProject, uninstallProject } from './scripts/install.mjs';
22
+ A complete cycstack plugin supplies engine/skills/hooks. cyc activate or /cyc set up this project writes only .cyc/config.json/.cyc/.gitignore. Hooks ignore unactivated projects and defer to project installs.
22
23
 
23
- installProject('/absolute/path/to/project', {
24
- hosts: ['codex', 'claude'],
25
- dryRun: true,
26
- });
27
- installProject('/absolute/path/to/project', { hosts: ['codex', 'claude'] });
28
- doctorProject('/absolute/path/to/project');
29
- uninstallProject('/absolute/path/to/project', { dryRun: true });
30
- ```
31
-
32
- These functions return JSON-friendly objects. Inspect `ok` before proceeding. Installation results include planned `changes`, `conflicts`, `warnings`, and an `error` when applicable. A dry run performs validation and reports changes without writing them. Hosts default to both supported integrations. Adding a host preserves previously installed hosts.
24
+ scripts/install.mjs exports installProject(target,{hosts,dryRun}), doctorProject(target), uninstallProject(target,{dryRun}). API hosts default to codex/claude and retain existing hosts. Inspect JSON ok/changes/conflicts/warnings/error. dryRun validates without writes. Source reference: docs/maintainers/installation-reference.md.
33
25
 
34
26
  ## Optional npm controls
35
27
 
36
- Interactive `init`/`install` output summarizes the outcome, project, hosts and file counts, keeps setup warnings and conflicts visible, and points to the next step in your AI host. A preview says no files changed; an unchanged install says it is up to date. Notes produced while planning are explicitly qualified in previews and failed installs, since a planned migration may not have been applied. Neither installation nor that summary establishes host trust or real-session activation.
37
-
38
- Use `--json` for the complete structured installer result. Redirected/piped output remains JSON automatically, preserving existing automation, and `--verbose` retains its existing detailed JSON behavior. Other command output and the installer API are unchanged. For example: `npx cyc-stack@latest init --json`.
39
-
40
- These options are for specific needs; the normal install requires none of them.
28
+ Interactive init/install shows outcome, project, hosts, changes, warnings/conflicts and next action. Previews/failed plans qualify unapplied migrations; unchanged installs report up to date. --json/--verbose exposes details; piped output stays JSON. Other commands/API stay unchanged.
41
29
 
42
30
  | Need | Command |
43
31
  | --- | --- |
44
- | Preview local file changes | `npx cyc-stack@latest init --dry-run` |
45
- | Install only one host | `npx cyc-stack@latest init --hosts codex` |
46
- | Select a nested project instead of its CYC-enabled parent | `npx cyc-stack@latest init --project .` |
47
- | Select an approved published version | `npx cyc-stack@0.6.0 init` |
48
- | Follow the optional `next` channel | `npx cyc-stack@next init` |
49
- | Save as a development dependency | `npm install --save-dev cyc-stack`, then `npx cyc-stack init` |
32
+ | Preview | npx cyc-stack@latest init --dry-run |
33
+ | One host | npx cyc-stack@latest init --hosts codex |
34
+ | Exact nested root | npx cyc-stack@latest init --project . |
35
+ | Approved version/channel | npx cyc-stack@0.6.0 init or npx cyc-stack@next init |
36
+ | Dependency | npm install --save-dev cyc-stack; npx cyc-stack init |
50
37
 
51
- `@latest` explicitly selects npm's `latest` tag; it is not a guarantee of production qualification. An unversioned command can use a package already installed in the project. For exact dependency pinning, add `--save-exact` to `npm install`. In automation, npm's `--yes` option goes before the package name to suppress its download prompt. These controls do not replace host reload, trust or project check configuration.
38
+ @latest selects a tag, not qualification. Unversioned commands may use project packages; --save-exact pins. npm --yes precedes the package name. Reload/trust/check setup still apply.
52
39
 
53
40
  ## Agent-guided installation
54
41
 
55
- Ask your agent to install CYC in the target project from a reviewed checkout, archive or published npm version, preserving existing instructions and hooks. The source/package INSTALL.md gives a pasteable request and route selection; this procedure is also available in a project-installed engine.
56
-
57
- For an agent performing this request:
58
-
59
- 1. Read the target project's instructions. Use the requested project and release, whether a published npm version or a supplied reviewed checkout/archive. Do not treat a registry error as permission to alter credentials, visibility or global settings.
60
- 2. Preview with the selected CLI's `init --dry-run`, using `--project` for a different existing target directory. Explain the proposed changes and continue within the user's installation authorization. Resolve reported conflicts without deleting or taking ownership of existing files.
61
- 3. Complete `init`, then follow [project setup](../methods/cyc-setup/SKILL.md). Find checks in the project's CI and configuration, explain which behavior they exercise, and use the project's authorization rules before running them. Do not invent always-passing checks.
62
- 4. Keep installed files, configured checks, executed checks and real host activation distinct. Missing trust or prompt/Stop observations remain unverified. Use supported host controls; never simulate callbacks or edit trust/state to claim activation.
63
-
42
+ 1. Read target instructions; use the requested project/reviewed release. Registry errors authorize no credential, visibility or global changes.
43
+ 2. Preview init --dry-run with --project when needed. Explain/proceed within installation authorization; resolve conflicts without deleting or claiming existing files.
44
+ 3. Install; follow [project setup](../methods/cyc-setup/SKILL.md). Find meaningful CI/config checks, explain coverage and honor execution authorization. No always-passing substitutes.
45
+ 4. Distinguish installed files, configured/executed checks and activation. Use supported trust controls; missing prompt/Stop observations stay unverified. Never simulate callbacks or edit trust/state to claim activation.
64
46
 
65
- An isolated skill folder does not contain the methods and CLI it references. Use the project installer or a complete qualified native plugin.
47
+ An isolated skill lacks its methods/CLI; use the installer or complete qualified plugin.
66
48
 
67
49
  ## What is installed
68
50
 
69
- | Project location | Purpose |
51
+ | Location | Purpose |
70
52
  | --- | --- |
71
- | `.cyc/engine/` | A project-local copy of CYC's scripts, CLI, catalog, documentation, original skills, and small homework evaluation fixture, with an ESLint config that ignores it |
72
- | `.cyc/config.json` | Editable verification configuration and loop limits |
73
- | `.cyc/install-manifest.json` | Installed version, ownership hashes and exact hook entries used for updates and removal |
74
- | `.cyc/.gitignore` | Keeps `runtime/` and `runs/` records out of ordinary Git tracking |
75
- | `.agents/skills/cyc/` | Single orchestrator entry for Codex and Cursor |
76
- | `.claude/skills/cyc/` | Single orchestrator entry for Claude Code |
77
- | `.codex/hooks.json` | CYC's entries merged into `UserPromptSubmit` and `Stop` |
78
- | `.claude/settings.json` | CYC's entries merged into `UserPromptSubmit` and `Stop` |
79
- | `scripts/claude-hooks/cyc.mjs` | Managed Claude launcher that invokes the copied engine |
80
- | `.cursor/hooks.json` | CYC's entries merged into `beforeSubmitPrompt`, `afterAgentResponse`, and `stop` (Cursor host) |
81
- | `.cursor/rules/cyc-delivery.mdc` | Always-applied rule that tells the Cursor agent the gate protocol, because Cursor hooks cannot inject per-request context |
53
+ | .cyc/engine/ | Runtime/CLI, methods/catalog/docs/skills, compact SVGs and ESLint config |
54
+ | .cyc/config.json | Checks/limits |
55
+ | .cyc/install-manifest.json | Version, ownership hashes/exact hooks |
56
+ | .cyc/.gitignore | Excludes runtime/ and runs/ |
57
+ | .agents/skills/cyc/ | Codex/Cursor entry |
58
+ | .claude/skills/cyc/ | Claude entry |
59
+ | .codex/hooks.json | UserPromptSubmit/Stop |
60
+ | .claude/settings.json | UserPromptSubmit/Stop |
61
+ | scripts/claude-hooks/cyc.mjs | Claude launcher |
62
+ | .cursor/hooks.json | beforeSubmitPrompt/afterAgentResponse/stop |
63
+ | .cursor/rules/cyc-delivery.mdc | Cursor protocol |
82
64
 
83
- Only CYC-owned files are updated. Existing instructions, application dependencies, and unrelated hooks remain intact. Installed Markdown skills have relative links to CYC's docs, catalog, scripts, and CLI rewritten to the copied engine. The npm archive and project installer share the explicit release selection in `package.json`: the standard engine, skills/playbooks, operational documentation, engineering examples and compact SVG diagrams. Development tests, evaluation fixtures/results, historical reports, bitmap/HTML exports and release/diagram generators stay in the source checkout. No application code needs to use JavaScript; Node runs CYC's local checks and hooks, while verification invokes your project's own commands.
65
+ package.json selects npm/copied payload; skill links target the engine. Tests/evaluations/reports and bitmap/HTML generators/exports stay source-only. Verification uses project commands.
84
66
 
85
- Updating an older full installation removes obsolete CYC-owned payload only when its bytes still match the recorded ownership hash. Modified obsolete files, project configuration and run records are preserved. Dry-run reports removals and preservation warnings before any change. Preserved customized leftovers can make an existing installation larger than a fresh one; review those files individually.
67
+ Defaults: schema 1, no checks, three failures/two consecutive no-progress attempts, no wall-clock deadline. limits.maxDurationMs opts into time bounds. Configure meaningful checks; installation neither guesses/runs unfamiliar scripts nor guarantees success.
86
68
 
87
- The default project configuration has schema version 1, no verification commands, and limits of three failed attempts and two consecutive attempts without progress. There is no wall-clock deadline by default: long tasks may take as long as they need, and the loop is bounded by failures, not time. Set `limits.maxDurationMs` to opt into one. These are execution bounds, not a guarantee of success. Configure suitable project checks deliberately; the installer never guesses and runs scripts from an unfamiliar repository.
69
+ Scripts carry eslint-disable after shebangs; ESLint 10's nearest engine config ignores the engine. The Claude launcher avoids static imports/import.meta/top-level await; dynamic import needs ES2020. Comments cannot fix parsing. Project ignores may remain necessary for below-ES2020 script parsers, type-aware linting or unused-disable launcher warnings under --max-warnings 0.
88
70
 
89
- CYC's installed files stay out of the project's own lint. ESLint flat config lints dot-folders, so it reaches `.cyc/engine`, and the Claude launcher sits in the project's `scripts/`. Each installed script therefore starts with `/* eslint-disable */` (after any shebang). `.cyc/engine/eslint.config.mjs` ignores the whole engine for ESLint 10, which reads the config nearest each file; that also avoids "unused eslint-disable directive" warnings under `--max-warnings 0`. The launcher uses no import declarations, `import.meta`, or top-level `await`. A linter that parses `.mjs` as a classic script can therefore still parse it at `ecmaVersion` 2020 or later; its dynamic `import()` is ES2020 syntax. No comment can suppress a parse error. ESLint's parser (espree 9.6) was checked at 5, 2015, 2019, 2020 and latest. Some projects may still need `.cyc/` and `scripts/claude-hooks/` in their own ignores:
90
- - a linter that parses `.mjs` as a script below ES2020;
91
- - one that needs type information for every file;
92
- - `--max-warnings 0` where a file's header suppresses nothing. ESLint reports that as an unused directive; ESLint 10's engine config avoids it for `.cyc/engine` but not for the launcher.
93
-
94
- Hook commands use `node` on PATH. Claude invokes `node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/cyc.mjs"` through Bash (Git Bash required on Windows). The launcher resolves the engine relative to its own location, preserving nested-directory and relocated-clone behavior. Codex and Cursor retain an inline bootstrap that locates the copied engine from the host event. No installer-specific Node or project paths are embedded. Host trust/reload is still required. `doctor` reports the installed version and checks installed command definitions and file hashes. Tests exercise simulated events, not live host activation. Claude's shell setting follows the [official hook command contract](https://code.claude.com/docs/en/hooks).
71
+ Hooks need node on PATH. Claude uses node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/cyc.mjs" through Bash (Git Bash on Windows), then relative engine resolution. Codex/Cursor bootstrap from host events. No machine-specific paths; trust/reload remains required. [Claude hook contract](https://code.claude.com/docs/en/hooks).
95
72
 
96
73
  ## Updating, conflicts, and removal
97
74
 
98
- Run installation again to update from the current distribution. An unchanged distribution produces no file changes. A skill or engine file edited since installation is a conflict: the installer reports it and writes nothing. Move or merge that customization deliberately before retrying; it will not be silently overwritten. Valid changes to `.cyc/config.json` are preserved.
99
-
100
- Installation builds and validates the complete operation plan before writing. Ordinary write failures trigger rollback to the previous file contents. This is an in-process rollback, not a filesystem transaction: abrupt termination or power loss can leave a partial operation. Inspect the manifest and run doctor before retrying; do not erase custom files to force an update.
75
+ Reinstall the selected distribution; unchanged files stay untouched. Modified owned skills/engine files cause a no-write conflict: reconcile deliberately. Valid config stays. Obsolete payload is removed only on matching ownership hashes; modified leftovers/records remain and may exceed fresh-install size.
101
76
 
102
- Uninstall removes only files whose contents still match their ownership hashes, and only hook entries that still exactly match CYC's entries. Before writing, it checks whether any remaining hook command references `.cyc/engine` or the managed Claude launcher, including customized or duplicated entries. Such a dependency is an atomic conflict: uninstall leaves the entire installation unchanged and reports the affected configuration. Remove or adapt the retained reference deliberately, then retry. Independent customized hooks remain intact.
77
+ Preflight validates the full plan. Ordinary write failures restore prior bytes; abrupt termination/power loss may leave partial work. Inspect manifest/doctor before retrying; rollback is not a filesystem transaction.
103
78
 
104
- Modified files, unrelated hook entries, and runtime/run records are preserved and reported. When retained record directories exist, `.cyc/.gitignore` is also kept so those records remain excluded from ordinary Git tracking. Existing tracked files and explicit force-adds are outside that protection. Empty directories may remain. After uninstall, retained files are no longer managed; a later install reports collisions rather than claiming ownership.
79
+ Uninstall removes matching owned files/exact hooks only. Retained/custom/duplicate hooks referencing engine/launcher cause an atomic conflict leaving everything unchanged; adapt deliberately. Other customizations/records remain, including .cyc/.gitignore with records. Tracked files/force-adds are outside that protection. Empty directories may remain; later installs treat unmanaged leftovers as collisions.
105
80
 
106
- Destination symlinks and junctions are refused. The installer also rejects corrupt configuration and unsafe manifest paths before mutating files. Do not run install/update concurrently with another installer or editor changing the same integration files.
81
+ Corrupt config, unsafe manifests and destination symlinks/junctions reject before writes. Avoid concurrent integration-file installers/editors.
107
82
 
108
83
  ## Activation and diagnosis
109
84
 
110
- `doctorProject` checks the Node runtime, project config, installation manifest, distribution hashes, and the structural presence of both response-hook events for installed hosts. A failing `<host> hooks` check says which repair applies: the entry is missing from an event (rerun init), it was modified by hand (rerun init, or keep the edit and expect the notice), or it is out of date because the engine's entry changed since the install (rerun init). It does not execute project verification commands or prove that the host has loaded or trusted those hooks.
111
-
112
- Reload the host and use its hook trust/activation flow where required. Validate a real session with a deliberately invalid response, then a valid review-backed response. Hook tests using simulated events do not establish real-session activation. Skill discovery, plugin command prefixes, and host UI behavior must also be checked in the actual supported host version.
85
+ doctorProject checks Node/config/manifest/hashes/hook structure, not verification or loaded/trusted hooks. Notices distinguish missing, edited and outdated entries; rerun init or retain a deliberate edit with its notice.
113
86
 
114
- Confirm fresh prompt state and the post-turn Stop decision in the invocation you actually use. Installation or a manually checked packet is insufficient. A successful acceptance does not establish that rejection/correction, interactive trust or another host works. See [validation](validation.md).
87
+ Reload/trust exact definitions. Observe fresh prompt state, invalid-response rejection/correction and valid review-backed Stop in the actual host/version/invocation. Installation, simulated callbacks, manual packets or one acceptance prove no other outcome/host. See [validation](validation.md).
115
88
 
116
- Setup now makes missing hook observations actionable: `onboard --host codex --session ID --token TOKEN` uses the current injected gate token to distinguish a prompt awaiting completion from an accepted Stop. Missing, old or mismatched evidence is not successful setup even when project checks pass. The [setup diagnostic contract](onboarding-recovery.md) explains readiness and the first-task transition. Review/trust the exact definitions through the host UI; the [official OpenAI hooks documentation](https://learn.chatgpt.com/docs/hooks) describes Codex's project and per-definition trust requirements. Installing files does not grant that trust.
89
+ onboard --host codex --session ID --token TOKEN uses the current injected token to distinguish pending prompt from accepted Stop. Missing/stale/mismatched observations stay unready despite passing checks. See [setup diagnostics](onboarding-recovery.md) and [OpenAI hooks guidance](https://learn.chatgpt.com/docs/hooks).
117
90
 
118
- Plugin manifests and marketplaces are included for all three hosts: `.claude-plugin/` (Claude Code), root `plugin.json` with `.codex-plugin/` compatibility plus `.agents/plugins/marketplace.json` (Codex), and `.cursor-plugin/` (Cursor). Each points at its own hook file in `hooks/`, because the hosts use different event names and plugin-root variables. File presence is not proof of native-host installation or activation. Repository/manual distribution and official public directory listings have separate requirements; public repository visibility alone does not establish either. OpenAI currently excludes lifecycle-hook plugins from its public directory and directs them to manual installation in Codex desktop. See [OpenAI's hook distribution limits](https://developers.openai.com/plugins/build/plugins#bundled-mcp-servers-and-lifecycle-hooks). CYC's current full plugin includes hooks, and fresh real-host qualification remains pending.
91
+ Resources include .claude-plugin, root plugin.json/.codex-plugin compatibility/.agents/plugins/marketplace.json, and .cursor-plugin with host-specific hook events/variables. Files/public visibility/manual distribution prove no activation or directory listing. Full CYC includes hooks; fresh native qualification remains pending. [OpenAI distribution limits](https://developers.openai.com/plugins/build/plugins#bundled-mcp-servers-and-lifecycle-hooks) direct directory-excluded hook plugins to manual desktop installation.
119
92
 
120
- Cursor differences: its prompt hook cannot inject context and its stop hook does not receive the final text. The Cursor adapter captures the text from `afterAgentResponse`, the rule file supplies the protocol, and each conversation picks its own session tag and writes `.cyc/runtime/cursor-<tag>.review.json` with token `cursor`. The hook finds its packet by freshness (written after the current request began) and an exact match with the captured response, so parallel Cursor chats in one folder never share or overwrite a packet. Claude and Codex hooks detect when Cursor runs them as third-party hooks and stay silent so the Cursor adapter owns the session.
93
+ Cursor prompt cannot inject context; stop lacks reply text. afterAgentResponse captures it, and the rule supplies protocol. Each conversation chooses a tag and writes .cyc/runtime/cursor-<tag>.review.json, token cursor. Freshness after request start/exact reply match isolates parallel chats. Claude/Codex third-party hooks stay silent under Cursor.
121
94
 
122
- Project-install hooks are portable across clone locations when Node is on PATH. Legacy installations must be updated once to replace absolute commands. A new machine must still trust and load the hooks.
95
+ Relative commands survive relocation with Node on PATH. Update legacy absolute-command installs once; new machines still need trust/loading.
123
96
 
124
97
  ## Impact investigation for this installer
125
98
 
126
- | Area inspected | Connection and treatment | Verification |
127
- | --- | --- | --- |
128
- | Existing `.codex/hooks.json` and `.claude/settings.json` | Both call `scripts/response-hook.mjs` with a host argument; add an explicit target root and merge exact owned entries | Seed unrelated hook entries and confirm install/update/uninstall preservation |
129
- | `scripts/response-hook.mjs` | Runtime previously derived from its source location; portable copies require root resolution independent of engine location | Root coordinator adapts `--project`; integration tests check copied hooks in a temporary target |
130
- | Skill discovery folders | Copy the same skills for each host; relative documentation links require adjustment | Check installed copies and link targets; do not claim host discovery from file presence |
131
- | `.cyc/config.json` and ownership manifest | Durable editable config and installation bookkeeping | Invalid schemas, path traversal, file modification, and idempotence tests |
132
- | Existing `AGENTS.md`, `CLAUDE.md`, package.json | User-owned instructions and application configuration are outside installation scope | Seed content and confirm unchanged bytes |
133
- | Target filesystem | Partial writes or symlink traversal could damage unrelated files | Up-front collision checks, rollback, temp project tests, junction refusal |
134
-
135
- The investigated source is the working tree used for this implementation. Host activation and compatibility beyond simulated/file-level checks remain external verification gaps. This installer is a distribution mechanism, not an automatic whole-project dependency analyzer.
136
-
99
+ The source reference holds the full investigation. Temporary-project/simulated tests cover preservation, links, schema/ownership, collision, rollback and linked-path rejection; no live activation/dependency-discovery claim.
137
100
 
138
101
  ## Existing project conventions
139
102
 
140
- Existing Stop hooks are preserved, with an installation warning to review presentation ownership. Set `delivery.presentation` to `"project"` to delegate reply-format checks to existing project rules while retaining CYC run-completion checks. Set `context.ledgerPath` to reuse an existing ledger. Updates preserve these configuration choices. Do not remove an unrelated hook automatically.
141
-
142
- After updating, reload the host so the conversation does not mix previously loaded skills with the new engine. For repeatable trials, pin the selected full Git commit in the GitHub install command and record the installed manifest version. Qualify the exact revision used; an older release tag installs the behavior at that tag.
103
+ Keep unrelated Stop hooks. delivery.presentation:"project" delegates formatting but retains completion checks; context.ledgerPath reuses a ledger. Updates preserve valid config, including delivery.defaultCharacterLimitEnabled:false for unlimited new-session replies. Avoid managed-hook edits.
143
104
 
105
+ Reload to avoid mixed old/new code. Pin/record full commit and manifest version; old tags retain old behavior.
144
106
 
145
107
  ## Private repositories and npm Git fetch failures
146
108
 
147
- GitHub archive fetching through npm may not share the credentials used by Git or the GitHub CLI. A private repository can return HTTP 404, followed by a Git packing error. Do not change repository visibility or clear global caches to work around this.
148
-
149
- Use an authenticated checkout of the desired commit and invoke its installer directly. This avoids npm's GitFetcher entirely. In a separate tools directory, clone once, check out the exact published commit, and record it:
109
+ npm archive auth can differ from Git/gh and return 404/packing errors. Do not change visibility or clear global caches. In a new authenticated clone, stop on failed commands:
150
110
 
151
- ```text
111
+ ~~~text
152
112
  gh repo clone TheDThompsonDev/cyc-stack cyc-source
153
113
  git -C cyc-source checkout --detach <full-commit-sha>
154
114
  git -C cyc-source rev-parse HEAD
155
- ```
156
-
157
- If any command fails, stop before installing. Use a new clone directory to avoid disturbing existing local work. Then run:
115
+ ~~~
158
116
 
159
- ```text
160
- node <cyc-checkout>/bin/cyc.mjs init --project <target-project> --dry-run
161
- node <cyc-checkout>/bin/cyc.mjs init --project <target-project>
162
- node <target-project>/.cyc/engine/bin/cyc.mjs doctor
163
- ```
117
+ Use that checkout's CLI init --project <target-project> --dry-run, then init and target doctor. Alternatively npm pack --ignore-scripts once, using the same archive from the target root:
164
118
 
165
- For an npm-based distribution, pack that authenticated checkout once with `npm pack --ignore-scripts`. Copy the resulting archive to the target machine, then invoke its explicit binary:
166
-
167
- ```text
119
+ ~~~text
168
120
  npm exec --offline --yes --package "/absolute/path/cyc-stack-X.Y.Z.tgz" -- cyc init --dry-run
169
121
  npm exec --offline --yes --package "/absolute/path/cyc-stack-X.Y.Z.tgz" -- cyc init
170
- node .cyc/engine/bin/cyc.mjs doctor
171
- ```
172
-
173
- Run these from the target project root. Both preview and installation use the same archive. There are no runtime npm dependencies. Our packaging regression test uses an empty npm cache and offline installation, checking dry-run, install, bundled methods, and doctor.
174
-
175
- Future tagged releases built with the updated release workflow attach this `.tgz` and `SHA256SUMS`. They can be downloaded through authenticated `gh release download <tag> --repo TheDThompsonDev/cyc-stack --pattern "*.tgz" --pattern SHA256SUMS`. Compare the archive's SHA-256 with the downloaded checksum before installation. This is an integrity check, not an independent signature. These assets do not exist until that release workflow runs; no release was published by this repair.
176
-
177
- Keep custom preferences in `.cyc/config.json`. For example, `"delivery": { "defaultCharacterLimitEnabled": false }` preserves an unlimited new-session default without editing managed hook files. Back up and reconcile existing managed-file modifications before updating; the installer intentionally refuses to overwrite them.
122
+ ~~~
178
123
 
124
+ No runtime npm dependencies. Tagged workflows attach .tgz/SHA256SUMS only after running; fetch with gh release download <tag> --repo TheDThompsonDev/cyc-stack --pattern "*.tgz" --pattern SHA256SUMS. Compare SHA-256: integrity, not independent signature. Reconcile managed customizations before updates.
179
125
 
180
126
  ## One public entry point
181
127
 
182
- Use `/cyc` with an ordinary task, including setup. Plugin hosts may namespace it as `/cycstack:cyc`. Only the parent lives under `skills/`; supporting instructions live under `methods/`, outside host skill discovery. Project installs copy those methods under `.cyc/engine/methods/` and rewrite parent links to them. The orchestrator loads methods by path when needed; users do not choose a skill.
183
-
184
- An update removes unchanged CYC-owned legacy supporting entries from `.claude/skills` and `.agents/skills`. Customized legacy entries cause an atomic conflict so their changes can be preserved and deliberately migrated; unrelated user skills are untouched. Reload the host after updating to remove previously loaded menu entries. Live menu rendering still requires host verification.
128
+ Use /cyc (possibly /cycstack:cyc) for tasks/setup. Only the parent skill is discoverable; .cyc/engine/methods loads by path.
185
129
 
130
+ Updates remove unchanged legacy skills. Customized .claude/skills/.agents/skills entries require atomic conflict resolution and deliberate migration; unrelated skills stay. Reload clears old entries; actual menus need host verification.
186
131
 
187
132
  <a id="npm-publication-preparation"></a>
188
133
 
189
134
  ## npm publication maintenance
190
135
 
191
- CYC is published on npm. For future releases, the source includes public package metadata, an INSTALL.md entry guide, and an offline release preflight. In the CYC source checkout, run `npm run check:distribution`; add the desired tag to `node scripts/check-distribution.mjs` to check version agreement. This tooling is development-only and does not ship inside the local engine.
192
-
193
- The source workflow `.github/workflows/publish-npm.yml` is manually invoked for an existing release tag and defaults to the `next` channel. It uses Node 24, validates publishing-tool versions, runs tests, packs the candidate and uses npm OIDC. Package ownership, the exact npm trusted-publisher repository/workflow/environment binding and any required `npm-publish` environment reviewers must be configured by the maintainer. The repository is public; registry publication still requires an authorized npm account. This preparation does not publish anything. Registry install examples require an actual published release.
194
-
136
+ Source-only publishing is not consumer setup. npm run check:distribution validates metadata/optional tag versions. Manual publish-npm.yml uses Node 24, validates tools, tests/packs and npm OIDC. Maintainers authorize ownership, exact trusted-publisher repository/workflow/environment binding and npm-publish reviewers.
195
137
 
196
- For npm provenance to identify the packaged commit, dispatch the workflow from the same tag supplied in its input. The workflow checks out the immutable event SHA and rejects a different dispatch ref or checkout HEAD. After account configuration and release approval, a maintainer can use:
138
+ Dispatch with matching existing input tag, event SHA/ref and checkout HEAD:
197
139
 
198
- ```sh
140
+ ~~~text
199
141
  gh workflow run publish-npm.yml --ref v0.6.0 -f tag=v0.6.0 -f channel=next
200
- ```
142
+ ~~~
201
143
 
202
- This is a publication action, not an installation command; do not run it as part of consumer setup.
144
+ Default next; authorized npm account/published release required. Preparation publishes nothing.