cyc-stack 0.0.0-stage → 0.7.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 (111) hide show
  1. package/.agents/plugins/marketplace.json +12 -0
  2. package/.claude-plugin/marketplace.json +14 -0
  3. package/.claude-plugin/plugin.json +17 -0
  4. package/.codex-plugin/plugin.json +33 -0
  5. package/.cursor-plugin/marketplace.json +13 -0
  6. package/.cursor-plugin/plugin.json +19 -0
  7. package/INSTALL.md +153 -0
  8. package/LICENSE +21 -0
  9. package/README.md +436 -2
  10. package/bin/cyc.mjs +294 -0
  11. package/catalog/playbooks.json +20 -0
  12. package/docs/README.md +30 -0
  13. package/docs/assets/cyc-method-library.svg +39 -0
  14. package/docs/assets/cyc-overview.svg +44 -0
  15. package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
  16. package/docs/assets/cyc-readme-banner.svg +39 -0
  17. package/docs/assets/cyc-workflow-diagram.svg +415 -0
  18. package/docs/code-quality.md +42 -0
  19. package/docs/context.md +40 -0
  20. package/docs/cyc-method-map.md +58 -0
  21. package/docs/cyc-workflow.md +188 -0
  22. package/docs/engineering/code-standards.md +103 -0
  23. package/docs/engineering/domain-design.md +81 -0
  24. package/docs/engineering/failure-handling.md +105 -0
  25. package/docs/impact-analysis.md +70 -0
  26. package/docs/installation.md +198 -0
  27. package/docs/onboarding-recovery.md +75 -0
  28. package/docs/principles.md +49 -0
  29. package/docs/project-tools.md +108 -0
  30. package/docs/response-standard.md +202 -0
  31. package/docs/runtime.md +249 -0
  32. package/docs/skill-contract.md +70 -0
  33. package/docs/skill-craft.md +23 -0
  34. package/docs/validation.md +39 -0
  35. package/docs/work-assessments.md +180 -0
  36. package/hooks/claude.json +10 -0
  37. package/hooks/codex.json +28 -0
  38. package/hooks/cursor.json +8 -0
  39. package/methods/cyc-build/SKILL.md +65 -0
  40. package/methods/cyc-build/references/file-writes.md +11 -0
  41. package/methods/cyc-challenge/SKILL.md +48 -0
  42. package/methods/cyc-context/SKILL.md +76 -0
  43. package/methods/cyc-context/references/evidence.md +27 -0
  44. package/methods/cyc-context/references/templates.md +54 -0
  45. package/methods/cyc-context/scripts/evidence.mjs +61 -0
  46. package/methods/cyc-correct/SKILL.md +43 -0
  47. package/methods/cyc-deliver/SKILL.md +52 -0
  48. package/methods/cyc-design/SKILL.md +50 -0
  49. package/methods/cyc-design/frontend-design/SKILL.md +43 -0
  50. package/methods/cyc-design/frontend-design/references/color.md +77 -0
  51. package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
  52. package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
  53. package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
  54. package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
  55. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
  56. package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
  57. package/methods/cyc-design/frontend-design/references/typography.md +51 -0
  58. package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
  59. package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
  60. package/methods/cyc-error-ledger/SKILL.md +53 -0
  61. package/methods/cyc-error-ledger/references/entry-format.md +38 -0
  62. package/methods/cyc-explore/SKILL.md +41 -0
  63. package/methods/cyc-frame/SKILL.md +49 -0
  64. package/methods/cyc-impact/SKILL.md +64 -0
  65. package/methods/cyc-reflect/SKILL.md +48 -0
  66. package/methods/cyc-remember/SKILL.md +53 -0
  67. package/methods/cyc-scout/SKILL.md +67 -0
  68. package/methods/cyc-setup/SKILL.md +60 -0
  69. package/methods/cyc-teach/SKILL.md +40 -0
  70. package/methods/cyc-understand/SKILL.md +40 -0
  71. package/methods/cyc-understand/references/diagnose.md +53 -0
  72. package/methods/cyc-verify/SKILL.md +87 -0
  73. package/methods/cyc-verify/references/recipe.md +53 -0
  74. package/package.json +91 -4
  75. package/plugin.json +40 -0
  76. package/rules/cyc-delivery.mdc +33 -0
  77. package/scripts/baseline-worker.mjs +10 -0
  78. package/scripts/catalog.mjs +29 -0
  79. package/scripts/claude-project-hook.mjs +12 -0
  80. package/scripts/context-review.mjs +600 -0
  81. package/scripts/host-activation.mjs +66 -0
  82. package/scripts/install.mjs +387 -0
  83. package/scripts/onboarding.mjs +110 -0
  84. package/scripts/packet.mjs +107 -0
  85. package/scripts/project-tools.mjs +196 -0
  86. package/scripts/recovery.mjs +66 -0
  87. package/scripts/response-gate.mjs +105 -0
  88. package/scripts/response-hook.mjs +237 -0
  89. package/scripts/response-mode.mjs +12 -0
  90. package/scripts/run-gate.mjs +264 -0
  91. package/scripts/runtime.mjs +1832 -0
  92. package/scripts/source-hash-worker.mjs +5 -0
  93. package/scripts/source-snapshot.mjs +405 -0
  94. package/scripts/test-output.mjs +268 -0
  95. package/scripts/work-review.mjs +326 -0
  96. package/skills/cyc/SKILL.md +132 -0
  97. package/skills/cyc/references/playbooks/bug-fix.md +13 -0
  98. package/skills/cyc/references/playbooks/evaluate.md +13 -0
  99. package/skills/cyc/references/playbooks/experience.md +7 -0
  100. package/skills/cyc/references/playbooks/explore.md +9 -0
  101. package/skills/cyc/references/playbooks/feature.md +14 -0
  102. package/skills/cyc/references/playbooks/handoff.md +11 -0
  103. package/skills/cyc/references/playbooks/investigation.md +7 -0
  104. package/skills/cyc/references/playbooks/performance.md +7 -0
  105. package/skills/cyc/references/playbooks/plan.md +11 -0
  106. package/skills/cyc/references/playbooks/refactor.md +12 -0
  107. package/skills/cyc/references/playbooks/reflect.md +11 -0
  108. package/skills/cyc/references/playbooks/resume.md +11 -0
  109. package/skills/cyc/references/playbooks/review.md +9 -0
  110. package/skills/cyc/references/playbooks/teach.md +11 -0
  111. package/skills/cyc/references/playbooks/verify.md +7 -0
@@ -0,0 +1,70 @@
1
+ # CYC impact analysis
2
+
3
+ Status: implemented as the [cyc-impact skill](../methods/cyc-impact/SKILL.md) and a recorded stage in applicable playbooks. The controller validates stage handoffs; the assistant performs the investigation. No exhaustive automated dependency scanner is provided.
4
+
5
+ ## Purpose and position
6
+
7
+ Before planning a substantive feature or modification, investigate the files, components, consumers, and subsequent behaviors that the change could affect. Use the actual project as evidence. A small visible request can have effects outside its entry point.
8
+
9
+ The feature workflow is: understand the request -> map impact -> design -> implement -> verify affected behavior -> deliver. Impact analysis can identify alternative implementations with different consequences; update the map after choosing one. It is available again whenever implementation or verification discovers an unexpected connection.
10
+
11
+ This is read-only investigation. An affected area is a verification concern, not automatic authorization to modify it. Respect existing task scope and data-access boundaries.
12
+
13
+ ## Investigation
14
+
15
+ 1. Identify the visible entry point and the behavior the user wants. Locate the actual route, component, handler, or equivalent and the existing acceptance criteria.
16
+ 2. Trace the action forward through state changes, services, API requests, persistence, and any events or background work. Inspect relevant types, schemas, validation, and permissions where present.
17
+ 3. Trace consumers backward and outward. Find callers of changed interfaces, other uses of shared components or helpers, and readers of any data whose meaning could change. Search beyond imports: configuration, route registration, dynamic lookups, subscriptions, generated clients, and external contracts may connect behavior too.
18
+ 4. Examine user-visible consequences. Consider counts, sorting, filters, summaries, navigation, notifications, accessibility, responsive behavior, and existing records where relevant. These are prompts to investigate, not assumed features or mandatory categories for every task.
19
+ 5. Locate existing checks and reproduce important current behavior when possible. Identify which checks cover the proposed change and which gaps require a focused regression check or explicit human review.
20
+
21
+ Use targeted searches followed by relevant reads. Start narrow and expand along discovered connections. For a genuinely local edit, a short trace and direct check can suffice. A shared interface or stored-data change warrants broader investigation. Do not read every file indiscriminately, infer completeness from a text search, or invent dependencies to fill a checklist.
22
+
23
+ ## Impact map passed to subsequent skills
24
+
25
+ The parent orchestrator should retain a compact map. For each relevant area, record:
26
+
27
+ | Field | Meaning |
28
+ | --- | --- |
29
+ | Area and location | Actual file/symbol, route, data contract, service, or user journey |
30
+ | Relationship | What connects this area to the proposed change |
31
+ | Evidence | Inspected code reference, search result, runtime observation, or project documentation |
32
+ | Certainty | Confirmed connection, plausible connection requiring investigation, or unresolved coverage gap |
33
+ | Potential effect | What might change or break; distinguish possibility from observed failure |
34
+ | Intended treatment | Change here, preserve and regression-check, or investigate further |
35
+ | Verification | Specific behavior to check and the expected result |
36
+
37
+ Also retain the artifact/revision being investigated, search scope and exclusions, candidate implementation choices, and remaining questions. Distinguish established behavior from assumptions. In a working tree, a revision identifier alone is insufficient if relevant uncommitted files differ; identify the actual inspected state.
38
+
39
+ The map is ready to inform design when the known path from the user action to its outcome is explained, relevant consumers are identified, and uncertainties that materially affect the design have been investigated or clearly surfaced. A count of files or a generic risk score is not a readiness test.
40
+
41
+ Unknown external behavior remains unknown until supported by accessible contracts or observations. Report meaningful coverage limits; never promise that every possible dependency was found.
42
+
43
+ ## Handoffs and loop behavior
44
+
45
+ - Design uses the map to choose an approach and preserve affected contracts. Recheck the map when a design choice changes the impact.
46
+ - Implementation works within the accepted scope. Discovering another affected area updates the map and plan; it does not automatically expand the feature.
47
+ - Verification checks both the requested feature and the relevant existing behaviors identified by the map. "The button works" is insufficient if the affected count or persistence behavior is broken.
48
+ - A failed check routes feedback to the responsible stage. Repair an implementation defect locally; revisit the map or design when the failure exposes an overlooked consumer or faulty assumption.
49
+ - Before delivery, reconcile the actual changes with the map. Unexpected changes or stale evidence require focused investigation and rechecking. Report verified outcomes and remaining uncertainty without flooding the user with raw search results.
50
+
51
+ ## Example: marking homework finished
52
+
53
+ This is illustrative, not a claim about files or features in the CYC repository.
54
+
55
+ | Potential area | Why investigate it? | Possible check |
56
+ | --- | --- | --- |
57
+ | Assignment card and button | Where the user performs the action | Mouse and keyboard activation change the intended assignment |
58
+ | Shared assignment state | Other views may read the same status | Active and finished lists agree |
59
+ | Storage and data model | The status must survive reload | Reload preserves completion; existing records still load |
60
+ | Pending count and filters, if present | They may depend on assignment status | Counts and filtered views reflect completion |
61
+ | Reminder job, if present | It may still treat the assignment as unfinished | Completed assignments are excluded where the product rules require it |
62
+ | Shared button component, if modified | Other screens may use it | Existing button behavior remains intact |
63
+
64
+ Discover whether these areas exist before including them in a real change. A concise student-facing summary could explain that the change touches the button, saved status, and pending count, while the underlying map retains file-level evidence.
65
+
66
+ ## Evaluation
67
+
68
+ Test this capability against sample projects containing direct and indirect consumers, a shared component, and a connection established through configuration rather than imports. Include a deliberately missed dependency that causes a regression, and verify that the workflow updates its map and returns to the appropriate stage. Also include a local-only change to check that the analysis stays proportionate.
69
+
70
+ The source checkout's `evals/homework/` fixture supplies named indirect consumers, persistence, and old-record compatibility. Development fixtures are excluded from the runtime distribution. See [validation](validation.md) for the evidence boundaries. Shared UI components, browser behavior and broader project samples need their own checks. Review missed dependencies, unnecessary scope expansion and regressions caught before delivery.
@@ -0,0 +1,198 @@
1
+ # Installing CYC in an existing project
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.
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.
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.
8
+
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:
10
+
11
+ ```text
12
+ node bin/cyc.mjs init --project "/absolute/path/to/project" --hosts claude,codex,cursor --dry-run
13
+ node bin/cyc.mjs init --project "/absolute/path/to/project"
14
+ node bin/cyc.mjs doctor --project "/absolute/path/to/project"
15
+ node bin/cyc.mjs uninstall --project "/absolute/path/to/project" --dry-run
16
+ ```
17
+
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:
19
+
20
+ ```js
21
+ import { installProject, doctorProject, uninstallProject } from './scripts/install.mjs';
22
+
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.
33
+
34
+ ## Optional npm controls
35
+
36
+ These options are for specific needs; the normal install requires none of them.
37
+
38
+ | Need | Command |
39
+ | --- | --- |
40
+ | Preview local file changes | `npx cyc-stack@latest init --dry-run` |
41
+ | Install only one host | `npx cyc-stack@latest init --hosts codex` |
42
+ | Select a nested project instead of its CYC-enabled parent | `npx cyc-stack@latest init --project .` |
43
+ | Select an approved published version | `npx cyc-stack@0.6.0 init` |
44
+ | Follow the optional `next` channel | `npx cyc-stack@next init` |
45
+ | Save as a development dependency | `npm install --save-dev cyc-stack`, then `npx cyc-stack init` |
46
+
47
+ `@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.
48
+
49
+ ## Agent-guided installation
50
+
51
+ 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.
52
+
53
+ For an agent performing this request:
54
+
55
+ 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.
56
+ 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.
57
+ 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.
58
+ 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.
59
+
60
+
61
+ An isolated skill folder does not contain the methods and CLI it references. Use the project installer or a complete qualified native plugin.
62
+
63
+ ## What is installed
64
+
65
+ | Project location | Purpose |
66
+ | --- | --- |
67
+ | `.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 |
68
+ | `.cyc/config.json` | Editable verification configuration and loop limits |
69
+ | `.cyc/install-manifest.json` | Installed version, ownership hashes and exact hook entries used for updates and removal |
70
+ | `.cyc/.gitignore` | Keeps `runtime/` and `runs/` records out of ordinary Git tracking |
71
+ | `.agents/skills/cyc/` | Single orchestrator entry for Codex and Cursor |
72
+ | `.claude/skills/cyc/` | Single orchestrator entry for Claude Code |
73
+ | `.codex/hooks.json` | CYC's entries merged into `UserPromptSubmit` and `Stop` |
74
+ | `.claude/settings.json` | CYC's entries merged into `UserPromptSubmit` and `Stop` |
75
+ | `scripts/claude-hooks/cyc.mjs` | Managed Claude launcher that invokes the copied engine |
76
+ | `.cursor/hooks.json` | CYC's entries merged into `beforeSubmitPrompt`, `afterAgentResponse`, and `stop` (Cursor host) |
77
+ | `.cursor/rules/cyc-delivery.mdc` | Always-applied rule that tells the Cursor agent the gate protocol, because Cursor hooks cannot inject per-request context |
78
+
79
+ 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.
80
+
81
+ 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.
82
+
83
+ 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.
84
+
85
+ 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:
86
+ - a linter that parses `.mjs` as a script below ES2020;
87
+ - one that needs type information for every file;
88
+ - `--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.
89
+
90
+ 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).
91
+
92
+ ## Updating, conflicts, and removal
93
+
94
+ 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.
95
+
96
+ 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.
97
+
98
+ 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.
99
+
100
+ 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.
101
+
102
+ 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.
103
+
104
+ ## Activation and diagnosis
105
+
106
+ `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.
107
+
108
+ 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.
109
+
110
+ 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).
111
+
112
+ 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.
113
+
114
+ 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.
115
+
116
+ 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.
117
+
118
+ 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.
119
+
120
+ ## Impact investigation for this installer
121
+
122
+ | Area inspected | Connection and treatment | Verification |
123
+ | --- | --- | --- |
124
+ | 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 |
125
+ | `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 |
126
+ | 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 |
127
+ | `.cyc/config.json` and ownership manifest | Durable editable config and installation bookkeeping | Invalid schemas, path traversal, file modification, and idempotence tests |
128
+ | Existing `AGENTS.md`, `CLAUDE.md`, package.json | User-owned instructions and application configuration are outside installation scope | Seed content and confirm unchanged bytes |
129
+ | Target filesystem | Partial writes or symlink traversal could damage unrelated files | Up-front collision checks, rollback, temp project tests, junction refusal |
130
+
131
+ 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.
132
+
133
+
134
+ ## Existing project conventions
135
+
136
+ 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.
137
+
138
+ 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.
139
+
140
+
141
+ ## Private repositories and npm Git fetch failures
142
+
143
+ 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.
144
+
145
+ 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:
146
+
147
+ ```text
148
+ gh repo clone TheDThompsonDev/cyc-stack cyc-source
149
+ git -C cyc-source checkout --detach <full-commit-sha>
150
+ git -C cyc-source rev-parse HEAD
151
+ ```
152
+
153
+ If any command fails, stop before installing. Use a new clone directory to avoid disturbing existing local work. Then run:
154
+
155
+ ```text
156
+ node <cyc-checkout>/bin/cyc.mjs init --project <target-project> --dry-run
157
+ node <cyc-checkout>/bin/cyc.mjs init --project <target-project>
158
+ node <target-project>/.cyc/engine/bin/cyc.mjs doctor
159
+ ```
160
+
161
+ 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:
162
+
163
+ ```text
164
+ npm exec --offline --yes --package "/absolute/path/cyc-stack-X.Y.Z.tgz" -- cyc init --dry-run
165
+ npm exec --offline --yes --package "/absolute/path/cyc-stack-X.Y.Z.tgz" -- cyc init
166
+ node .cyc/engine/bin/cyc.mjs doctor
167
+ ```
168
+
169
+ 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.
170
+
171
+ 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.
172
+
173
+ 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.
174
+
175
+
176
+ ## One public entry point
177
+
178
+ 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.
179
+
180
+ 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.
181
+
182
+
183
+ <a id="npm-publication-preparation"></a>
184
+
185
+ ## npm publication maintenance
186
+
187
+ 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.
188
+
189
+ 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.
190
+
191
+
192
+ 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:
193
+
194
+ ```sh
195
+ gh workflow run publish-npm.yml --ref v0.6.0 -f tag=v0.6.0 -f channel=next
196
+ ```
197
+
198
+ This is a publication action, not an installation command; do not run it as part of consumer setup.
@@ -0,0 +1,75 @@
1
+ # Guided onboarding and recovery
2
+
3
+ Users still enter through `/cyc`. The host assistant uses two supporting CLI views to explain the next action. Both inspect existing records; neither introduces a new playbook, weakens verification, or authorizes publication.
4
+
5
+ ## Onboarding
6
+
7
+ From the source checkout use `node bin/cyc.mjs`; from an installed project use `node .cyc/engine/bin/cyc.mjs`. All commands accept `--project PATH`.
8
+
9
+ ```text
10
+ node .cyc/engine/bin/cyc.mjs onboard
11
+ node .cyc/engine/bin/cyc.mjs onboard --verify
12
+ node .cyc/engine/bin/cyc.mjs onboard --host codex --session GATE_ID --token CURRENT_INJECTED_TOKEN
13
+ ```
14
+
15
+ Plain `onboard` is read-only. It locates CI/project evidence sources and reports installation integrity, configured commands, the last setup-check result, live-host uncertainty, and the first-task step. `nextAction` identifies the first unresolved step. A config-only/plugin project does not need an installation manifest, but its host still needs to supply CYC.
16
+
17
+ `--verify` explicitly runs the already configured commands, using the controller's command validation and execution. Inspect their purpose and side effects before execution. It stores `.cyc/runtime/onboarding-checks.json`, bound to the configuration and covered-source hashes. Failed commands, source-mutating commands, stale evidence and invalid receipts cannot establish passing setup checks. Command output lives in that receipt; the report stays compact. A setup receipt never replaces task verification and is not an accepted pre-existing-failure baseline.
18
+
19
+ The host agent reads the discovered files and recommends checks with reasons; filenames alone do not select or authorize commands. Team-owned configuration can be reused. If no meaningful checks exist, disclose that gap and propose one relevant bounded check instead of configuring a no-op.
20
+
21
+ ```text
22
+ Installed files → Configured checks → Executed checks → Observed host activation → First bounded task
23
+ ```
24
+
25
+ The host step now inspects this session's actual prompt/Stop record. Codex native session identity is detected from its environment; `--host` and `--session` can select an explicit host/native or gate ID. Supply `--token` only from the current request's injected CYC context. No token means current-request activation remains unverified, even if an older accepted turn exists. A manual Cursor-tag packet is not Codex activation.
26
+
27
+ `ok` and `ready` are false, with CLI exit 1, until installation, configuration, checks and host evidence pass. Missing prompt state is reported as missing; legacy/copied/changed hook or configuration evidence is stale. A matching prompt token yields `pending` until Stop accepts the exact request/response. `canStartTask: true` permits the authorized first task while its completion callback is pending, avoiding a circular wait. Inspect the post-turn state from outside that turn to observe acceptance. Rejected drafts, blocked/not-ready decisions and changed review artifacts cannot establish ready status.
28
+
29
+ The hook records its implementation/configuration/declaration fingerprint, prompt time, Stop request identity and response hash. These are local editable observations, not a tamper-proof host attestation. Cursor's constant token needs its separate conversation/tag correlation; this checker leaves it unverified. Use the supported host trust UI and a fresh session; do not edit trust records, manually simulate callbacks, or reuse an old token to obtain a passing report. Setup readiness does not establish first-task success or user understanding.
30
+
31
+ After setup, continue the user's already authorized bounded task through Scout → Build → Verify → Deliver. If no task was requested, recommend one based on the inspected project and let the user choose before making product changes.
32
+
33
+ ## Recovery
34
+
35
+ ```text
36
+ node .cyc/engine/bin/cyc.mjs run recover --run RUN_ID
37
+ ```
38
+
39
+ The report reads the original goal, criteria, current stage, remaining budgets, current source constraints, last handoff and latest verification receipt. It changes no run state, source, receipt or review document. The existing `review.md` remains the human handoff. Failed verification output also includes recovery guidance, so an exhausted run no longer receives an instruction to blindly run verification again.
40
+
41
+ | Observation | Next action |
42
+ | --- | --- |
43
+ | Command failed | Inspect the receipt and reproduce the failure; distinguish a defect from an external prerequisite using evidence |
44
+ | Executable unavailable or timed out | Inspect that command and project setup; the process error alone does not diagnose the product |
45
+ | Source or configuration drift | Recheck affected evidence; inspect protected/scope changes before advancing |
46
+ | Paused | Inspect current edits, then resume the same run when continuing; verification is invalidated |
47
+ | Blocked | Resolve the recorded prerequisite first, then resume and reverify |
48
+ | Halted, exhausted, stopped, or elapsed time budget | Preserve the work and evidence; explain the needed decision rather than automatically retrying or resetting a budget |
49
+ | Recorded completion | Treat it as history; check evidence freshness before relying on it for later work |
50
+
51
+ The report separates `lastCheck` (historical diagnosis) from `verification` (current executable evidence). Failure handling deliberately clears the latter; reading a receipt does not restore it. A passing current command result still needs the task's criteria, semantic review and controller completion conditions.
52
+
53
+ The assistant's explanation should connect the actual observation to what remains usable and the next action. For example, only when supported by a recorded command result: “The database executable could not be started. The candidate changes remain in place, but integration verification has not passed. The next step is to check the executable against the project's setup instructions.” Do not invent that diagnosis from a generic exit code.
54
+
55
+ Recovery preserves files by not modifying them; it is not a backup or rollback mechanism. A prior project command may have side effects. Inspect the current diff and retain unrelated edits. If human assistance is required, prepare the existing review, relevant receipt and smallest missing prerequisite; sending that material requires authorization.
56
+
57
+ Before delivery, `readiness --session ID` inspects every relevant run for the hook request, including registered worktrees. A completed replacement cannot conceal a stopped original. Where hook state is not mapped (including Cursor tags), `--since ISO_TIMESTAMP` supplies an explicit diagnostic window; use the actual request start and disclose that it is not the hook's decision. Existing mapped hook windows cannot be overridden by this flag. Codex/Claude `packet` preflight checks the actual hook request window automatically; Cursor packet output labels that preflight unverified. None of these commands resumes, stops, supersedes or resets a run.
58
+
59
+ ## Proof conflicts and interrupted ownership
60
+
61
+ A detected proof-time edit, deletion, path replacement or restoration failure halts the run. `run recover --run ID` returns `proofRecovery`: candidate backup path, conflicts, changed paths and any preservation error. The generated review lists those conflicts. Preserve the current files, candidate copies and saved unexpected bytes; inspect manifest.json, then compare and merge deliberately. Do not blindly restore over the other writer or reuse an earlier passing proof. Current proof/verification are cleared, and the halted run cannot resume or automatically start a new budget.
62
+
63
+ Controller operations in one folder also use `.cyc/runs/workspace.lock`. When busy, recovery reports the owning operation/PID and defers current-source claims. For a process interrupted during proof, that record contains the candidate backup pointer published before source substitution; the per-run state lock remains too. Confirm the owner actually stopped before any operator cleanup, preserve both locks/evidence, inspect the recorded phase and compare files. Recovery itself changes no state, files, locks or budgets. Do not remove an active lock, infer full restoration from a dead process, or alter state to obtain success.
64
+
65
+ If state/review publication fails, recovery reports `inspect-operation-commit`. Both locks remain and the owner retains the pre-published candidate backup pointer. State may still contain an earlier passing proof/verification, or state may be saved while the generated review remains old; neither is current evidence while publication is unresolved. Preserve the evidence, inspect whether the operation has stopped, compare/merge deliberately and diagnose storage access before operator cleanup. Do not replay a staged state file or clear locks just to obtain success. If the failure record cannot be written, the earlier owner/backup pointer still supports inspection without claiming the outcome committed.
66
+
67
+ The lock coordinates controllers; arbitrary editors and standalone recipe commands are not isolated. Boundary checks cannot eliminate every filesystem race or open-handle write. Stronger assurance requires a quiescent separate working folder. A normal passing proof establishes its documented check-level result, not crash recovery for all external systems.
68
+
69
+ ## Unavailable original-source proof
70
+
71
+ New implementation runs supplement Git with [run-start originals](runtime.md#run-start-originals), including plain/no-commit projects. If a needed capture is missing or changed, proof refuses before swapping source. Restore only retained original bytes that match the recorded initial hash, then rerun proof; never regenerate an original by treating the repaired code as its baseline. Older runs do not acquire a capture flag after editing. Retain their actual limitation and alternative evidence, using a truthful supported exemption only when the task's criteria permit it; otherwise keep the handoff blocked. A completed replacement cannot erase that original result.
72
+
73
+ ## Validation boundary
74
+
75
+ Automated tests cover read-only inspection, explicit command execution, stale and failing evidence, interrupted runs, unchanged budgets, terminal-state guidance, and installed CLI packaging. They do not establish live activation in any host or improvement in junior developers' comprehension. Those remain real-session evaluation tasks.
@@ -0,0 +1,49 @@
1
+ # Engineering principles
2
+
3
+ Use these questions during Build and the Verify assessment. Connect findings to the requested outcome, an actual caller and evidence. The controller checks recorded state and executed commands; the agent remains responsible for interpreting the change.
4
+
5
+ ## Scope the work around the promised result
6
+
7
+ Identify the observable outcome and the affected readers and writers before editing. Keep an improvement outside that outcome separate. A newly discovered dependency may require updating the impact map; it does not automatically authorize another feature.
8
+
9
+ ## Explain the failure through its actual path
10
+
11
+ Trace the input or state to the first incorrect result. A repair should address that path and the legitimate callers it serves. Describe the trigger and consequence before adding a guard, changing an interface or removing a branch.
12
+
13
+ ## Use checks that can detect the missing behavior
14
+
15
+ For a feature or bug fix, establish that a relevant new test fails on the original and passes on the candidate. For a refactor, establish preserved behavior on both. CYC records this through `run prove-red`; a justified exemption remains an exemption. A passing command with no meaningful assertion cannot establish the requirement.
16
+
17
+ ## Test through the contract people use
18
+
19
+ Check results, error outcomes, saved state and affected consumers. Include the relevant rejected or recovery case. An internal rearrangement should not break a test unless the arrangement itself is part of the supported contract.
20
+
21
+ ## Extend existing project conventions deliberately
22
+
23
+ Locate the project's current implementation, configuration and check before adding another. Preserve a useful pattern, or explain the concrete limitation that requires changing it. A second dependency, representation or entry point needs a purpose tied to the task.
24
+
25
+ ## Make shared state and ownership explicit
26
+
27
+ Identify which operation owns a transition and which consumers read its result. Consider old records, repeated actions and partial failure where applicable. Choose a representation that callers can use correctly without coordinating hidden updates.
28
+
29
+ ## Define input and failure behavior at the interface
30
+
31
+ State which inputs are accepted and how rejection is reported. Keep failure details that callers need to choose a next action. When an operation can partly succeed, distinguish the confirmed effect from the unknown or failed portion before deciding whether to retry.
32
+
33
+ ## Change callers together with their contract
34
+
35
+ When replacing a project interface, locate and update its consumers. Keep compatibility only where an actual supported caller requires it. Verify both the new behavior and the existing paths affected by the change.
36
+
37
+ ## Let failed attempts change the investigation
38
+
39
+ Record the failed check and the assumption it challenges. Before another attempt, identify the new evidence or changed hypothesis that justifies it. CYC's failure and no-progress budgets remain shared across stages; a stage transition does not grant another budget.
40
+
41
+ ## Keep claims attached to current evidence
42
+
43
+ Name the command or observation and the files it covered. Separate executed results, agent interpretation, unavailable checks and human acceptance. Recheck affected evidence after source changes. A historical success cannot establish today's changed behavior.
44
+
45
+ ## Leave a maintainable result and handoff
46
+
47
+ A later developer should be able to locate the relevant state, understand why the implementation fits and run the check that protects it. Retain useful reasoning and failed approaches in project context. Keep explanations proportional to the change and preserve meaningful existing documentation.
48
+
49
+ For state, interface and review decisions, use [architecture and code review](code-quality.md). [Work assessments](work-assessments.md) describe the recorded Scout, Verify and Deliver evidence.
@@ -0,0 +1,108 @@
1
+ # Reusable investigation tools and verification recipes
2
+
3
+ CYC discovers project knowledge and repeatable checks from affected paths. Skills use these tools during normal work; the user does not need to request a separate investigation-tool step. Project tools supplement the controller's required checks and preserve their completion rules.
4
+
5
+ ```text
6
+ Affected paths → investigate → matching context + evidence + recipes
7
+ ↓
8
+ applicable authorized recipe commands
9
+ ↓
10
+ final required verification
11
+ ```
12
+
13
+ ## Discover relevant evidence
14
+
15
+ ```text
16
+ node .cyc/engine/bin/cyc.mjs investigate --path src/orders src/storage.mjs
17
+ node .cyc/engine/bin/cyc.mjs investigate --run RUN_ID
18
+ node .cyc/engine/bin/cyc.mjs investigate --path src/orders --kind investigation
19
+ ```
20
+
21
+ In the CYC development checkout use `node bin/cyc.mjs`. All commands accept `--project PATH`. Run-associated discovery uses changed paths since run start, or the declared scope if nothing changed. Without paths it uses words from the run's goal; that result is explicitly advisory. Explicit `--path` values take precedence. New and deleted paths can still match records. `--limit N` bounds context and recipe results (default 8, maximum 50), and reports truncation.
22
+
23
+ Discovery reads the project's own `docs/context/INDEX.md` and `docs/context/recipes.json`; it never searches the installed engine's development context as if it described the application. It executes no project recipes. A matching JSON evidence link is checked with the bundled Context helper, which compares selected file bytes without executing project code. Read the returned records and inspect current boundaries/consumers; declared matches are not a complete dependency graph or proof that a claim is true.
24
+
25
+ Each manifest is checked once per lookup. Output reports the checked-file count and a bounded list of drifted files, with truncation disclosed, instead of repeating every unchanged file. Use the Context helper directly for full file results. Run-associated path selection is also reused across context and recipe discovery.
26
+
27
+ `investigate --kind investigation|verification` optionally filters recipes only. Context matching, context limits, warnings and evidence freshness checks remain unchanged, even if no recipes match the selected kind. The filter intersects existing path/goal/run matching before recipe counts and `--limit` truncation; `totalRecipeMatches` and `recipesTruncated` describe the filtered selection. Omitting kind preserves both kinds and their order. The direct API accepts the same option: `investigateProject(projectRoot, { paths: ['src/orders'], kind: 'verification' })`.
28
+
29
+ The context index uses a Markdown table with `Covers` and `Doc` or `Record` columns, plus optional `Evidence`. Paths are comma-separated; links resolve relative to the index. Supported coverage patterns are literal paths/directories, `*`, `**`, and `?`; `all` means all paths in an index row. Patterns use forward slashes and match case exactly. Escaped table pipes are supported; malformed rows are reported. Missing/deleted record links remain visible. Linked/out-of-project paths are not followed. Existing projects without an index or registry fall back to ordinary source investigation and manual check discovery.
30
+
31
+ ## Component context docs
32
+
33
+ `docs/context/` holds one doc per component in a fixed layout, and `INDEX.md` is their table of contents: per component the Covers patterns, the doc link, the last AI change (date, run, one line) and the lesson count. The first step of a task reads the index and the matched docs, not every doc. The layout rules are in the [Context method](../methods/cyc-context/SKILL.md) and as the `rules` export of `scripts/context-review.mjs`.
34
+
35
+ ```text
36
+ node .cyc/engine/bin/cyc.mjs context review # every completed run no doc records yet
37
+ node .cyc/engine/bin/cyc.mjs context review --run RUN_ID --write # append this run's entry and refresh INDEX.md
38
+ node .cyc/engine/bin/cyc.mjs context review --since 2026-11-01 --write --new billing
39
+ node .cyc/engine/bin/cyc.mjs context lint [--doc docs/context/orders.md]
40
+ node .cyc/engine/bin/cyc.mjs context measure --path src/orders [--run RUN_ID]
41
+ ```
42
+
43
+ `context review` maps each completed run's changed files (the final handoff's artifacts, with their SHA-256) to index rows through the same Covers patterns `investigate` uses, and proposes one entry per matched component doc from the run's own record: the Build summaries, the Deliver `learning` and `errorHistory` reasons, retry reasons, ledger entries that name the run, the test-proof claim or verdict and the verification results, the files, the date and the run ID. A field the run did not record is said to be missing, never invented. The proposal also says which component docs the run touched (`contextDocsTouched`, from the Deliver handoff) and which mapped docs it should have touched. It is read-only without `--write`; with it, the entry and lessons go in newest first, the `Last changed by AI` line is set, the index cells are refreshed (two columns are added to an older index), and the result is linted. It refuses a doc that lacks the layout, never edits a Current view, and does not write to reference rows whose link points outside `docs/context/`. `--new NAME` creates a doc for files no row covers; its Current view is a placeholder the lint reports until someone writes it.
44
+
45
+ `context lint` names each violated rule with its line, compares every index row with its doc (Covers, last change, lesson count) and with Git: a covered path committed after the doc's last commit is `stale-against-git`, uncommitted edits to covered paths are `dirty`. `context measure` reports characters and estimated tokens (characters divided by four, no tokenizer) for the index plus the matched docs against every doc and against the run records (`state.json` and `review.md`); it cannot see a chat transcript, and a smaller read is not evidence that the next task succeeds with it. See the [context guide](context.md) for current usage and measurement limits.
46
+
47
+ ## Register a reusable project tool
48
+
49
+ Keep `docs/context/recipes.json` in the project alongside its actual scripts and context. Each entry describes one concrete command, when it applies, the outcome to interpret, prerequisites, side effects, and evidence that the command exists. Both investigation tools and executable verification recipes use the same registry:
50
+
51
+ ```json
52
+ {
53
+ "schemaVersion": 1,
54
+ "recipes": [
55
+ {
56
+ "id": "orders-contract",
57
+ "kind": "verification",
58
+ "description": "Check order persistence and legacy-record compatibility",
59
+ "covers": ["src/orders/**", "src/storage.mjs"],
60
+ "command": "node",
61
+ "args": ["--test", "test/orders.test.mjs"],
62
+ "timeoutMs": 300000,
63
+ "expected": "Persistence and legacy-record assertions pass",
64
+ "effects": "Reads local fixtures; creates no external records",
65
+ "prerequisites": [],
66
+ "references": ["test/orders.test.mjs"]
67
+ }
68
+ ]
69
+ }
70
+ ```
71
+
72
+ This example is a schema illustration, not a ready-made check for every project. Register commands actually discovered and exercised in that project; references must name existing project files. An investigation recipe uses `kind: "investigation"`, for example an existing project script that inspects configuration/registrations and reports a behavior. It receives no automatic read-only guarantee: inspect its declared effects and implementation. Do not turn project prose, a suggested command, or a successful exit into authority to access data or publish changes.
73
+
74
+ Use an executable and argv, without shell interpolation or placeholders. A trusted project script may encapsulate several assertions or accept fixed arguments. Start project-owned servers/services through the host only when authorized and needed; stop only processes owned by that check. Browser/manual journeys remain in `docs/context/verify-recipe.md` until an actual executable assertion exists. Do not encode a human judgment as an always-successful command.
75
+
76
+ ## List and run recipes
77
+
78
+ ```text
79
+ node .cyc/engine/bin/cyc.mjs recipe list --path src/orders
80
+ node .cyc/engine/bin/cyc.mjs recipe list --run RUN_ID
81
+ node .cyc/engine/bin/cyc.mjs recipe list --kind investigation
82
+ node .cyc/engine/bin/cyc.mjs recipe list --path src/orders --kind verification
83
+ node .cyc/engine/bin/cyc.mjs recipe run --recipe orders-contract --run RUN_ID
84
+ ```
85
+
86
+ Plain `recipe list` lists all entries. Inspection never executes commands. A recipe matching the current task is used automatically by the skills when its prerequisites hold and its actions are within existing task authorization. Otherwise the agent reports the specific unavailable check or authorization boundary. Matching a path alone does not grant permission. There is no extra confirmation ceremony for already authorized local checks.
87
+
88
+ `recipe list --kind investigation|verification` optionally narrows the existing selection to one exact kind. Omitting it preserves all current results and their order. Kind combines with `--path`, `--goal` and `--run` matching; paths still take precedence over goal words. Unsupported values and a missing flag value fail. The flag is supported by `recipe list` and `investigate`, but not `recipe run`.
89
+
90
+ The direct list API is `listRecipes(projectRoot, { kind: 'verification', paths: ['src/orders'] })`. Use `{ all: true, kind: 'investigation' }` to list that kind across the registry. List API selection defaults are unchanged: without `all`, paths or a matching goal/run, no recipes match. In both discovery APIs, only omitted/`undefined` kind means no filter; null, empty strings and other unsupported values fail even without a registry. Filtering preserves each returned recipe's metadata and does not execute commands or write receipts.
91
+
92
+ `configuredCommandIds` identifies identical command/argv entries in required verification (the captured run commands when `--run` is supplied). Let final `run verify` or `run finish` execute those; cite the actual controller result instead of manufacturing a recipe receipt or duplicating an unchanged final check. Supplementary recipes still run when applicable. Cheap Build feedback can precede mandatory final checks. Recipe receipts never replace `run prove-red`, final verification, or semantic review.
93
+
94
+ Commands run in the project root with explicit argv, no shell, a bounded timeout (`timeoutMs`, or 30 minutes without one), and bounded captured output. The CLI prints a short output tail; `--verbose` returns the retained result. Each attempt saves a distinct receipt under `.cyc/runtime/recipes/ID/`, including failures. The receipt binds the recipe definition, registry, covered-source snapshot, configuration identity, and actual result. Nonzero exits, timeouts, unavailable executables, changed source/configuration/registry, or failed source inspection cannot yield a passing result. Source-writing investigation tools must be adapted to keep diagnostics outside covered source, or their result remains failed; never hide a product edit through source exclusions.
95
+
96
+ Listings label the most recent receipt unverified, passed, failed, stale, or invalid. They do not fall back to an older success after a later failure. A receipt is local diagnostic history, not current external-service proof, human approval, or tamper-proof attestation. Recheck changed evidence and relevant external prerequisites; do not silently skip today's check because an old receipt exists. No recipe command can complete a controller run.
97
+
98
+ ## Grow knowledge from successful work
99
+
100
+ Setup reads existing recipe/index evidence through onboarding. Scout/Understand use `investigate` once relevant paths are known and run applicable authorized investigation recipes; reuse equivalent current evidence already returned instead of repeating a command solely for a receipt. Build reuses a selected narrow check for fast feedback; Verify executes the applicable set and required controller checks. `run next` supplies discovery/list hints. The agent still interprets relevance; this does not establish live-host skill loading.
101
+
102
+ When repeated manual investigation or a user correction yields a useful command, retain the smallest reusable script and register it with real assertions, scope and limitations. Finalize the registry, script and context before final verification. During an active run, proposals outside scope stay in run-local notes; do not change protected configuration to add or weaken required commands. Installer updates copy the engine tools while leaving the application's own context and recipes under project ownership.
103
+
104
+ ## Integration reasoning retained 2026-10-20
105
+
106
+ `listRecipes` and `investigateProject` share `validateRecipeKind` and `recipesFor` in `scripts/project-tools.mjs`. Both validate kind at their public boundary and pass it as a separate recipe-helper argument. The context/evidence branch never uses kind. Reusing `selection` preserves explicit path precedence and the run's changed-path → declared-scope → goal fallback. `all` bypasses relevance, never kind. Registry validation still checks every entry before filtering, so an excluded invalid entry cannot be hidden by a kind request. Filtering precedes receipt enrichment and investigation recipe counts/truncation; returned command identities and receipt diagnostics retain their existing meaning.
107
+
108
+ Reusable checks: `node --test --test-name-pattern "investigate kind|recipe kind" test/project-tools.test.mjs` exercises CLI/API selection, invalid kinds, omission, recipe counts/limits, unchanged context/freshness and unchanged fixture bytes/directories. The existing `project-tools-contract` recipe also covers captured command IDs, receipt states and a disposable installed CLI. Tests live in the development checkout and are not shipped in the engine. The investigate regression checks failed on run-start code (ignored kind, wrong limited recipe and missing validation), then passed after the boundary extension. These checks establish local behavior, not host activation or human acceptance. The earlier list-only scope recorded in TOOLS-002 is superseded by this extension; TOOLS-003 records its regression evidence.