cyc-stack 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/README.md +25 -254
  5. package/bin/cyc.mjs +61 -23
  6. package/docs/assets/cyc-method-library.svg +1 -39
  7. package/docs/assets/cyc-overview.svg +1 -44
  8. package/docs/assets/cyc-workflow-diagram.svg +1 -415
  9. package/docs/context.md +13 -23
  10. package/docs/cyc-workflow.md +31 -84
  11. package/docs/installation.md +66 -124
  12. package/docs/onboarding-recovery.md +31 -37
  13. package/docs/project-tools.md +16 -10
  14. package/docs/response-standard.md +16 -32
  15. package/docs/runtime.md +22 -224
  16. package/docs/skill-contract.md +13 -56
  17. package/docs/task-context.md +56 -0
  18. package/docs/validation.md +2 -0
  19. package/docs/work-assessments.md +25 -92
  20. package/methods/cyc-build/SKILL.md +8 -53
  21. package/methods/cyc-challenge/SKILL.md +4 -0
  22. package/methods/cyc-context/SKILL.md +20 -53
  23. package/methods/cyc-context/references/evidence.md +1 -1
  24. package/methods/cyc-context/references/templates.md +4 -11
  25. package/methods/cyc-deliver/SKILL.md +6 -42
  26. package/methods/cyc-remember/SKILL.md +1 -1
  27. package/methods/cyc-scout/SKILL.md +17 -51
  28. package/methods/cyc-setup/SKILL.md +7 -19
  29. package/methods/cyc-verify/SKILL.md +15 -66
  30. package/methods/cyc-verify/references/recipe.md +2 -0
  31. package/package.json +9 -1
  32. package/plugin.json +1 -1
  33. package/rules/cyc-delivery.mdc +33 -33
  34. package/scripts/browser-audit.mjs +53 -0
  35. package/scripts/catalog.mjs +9 -2
  36. package/scripts/codex-host.mjs +178 -0
  37. package/scripts/context-review.mjs +212 -29
  38. package/scripts/delegation.mjs +156 -0
  39. package/scripts/execution.mjs +51 -0
  40. package/scripts/onboarding.mjs +14 -1
  41. package/scripts/packet.mjs +21 -6
  42. package/scripts/project-tools.mjs +43 -20
  43. package/scripts/recovery.mjs +20 -1
  44. package/scripts/response-mode.mjs +8 -0
  45. package/scripts/run-worker.mjs +4 -0
  46. package/scripts/runtime.mjs +648 -68
  47. package/scripts/swarm.mjs +154 -0
  48. package/scripts/task-context.mjs +164 -0
  49. package/scripts/work-review.mjs +32 -10
  50. package/skills/cyc/SKILL.md +29 -70
@@ -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.
@@ -1,10 +1,10 @@
1
1
  # Guided onboarding and recovery
2
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.
3
+ Users enter through /cyc. The agent uses the existing setup, finish and recovery views to explain the confirmed state and one next action. These projections do not authorize publication or change completion decisions.
4
4
 
5
5
  ## Onboarding
6
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`.
7
+ Use node bin/cyc.mjs in the source checkout, or node .cyc/engine/bin/cyc.mjs in an installed project. Add --project PATH when needed.
8
8
 
9
9
  ```text
10
10
  node .cyc/engine/bin/cyc.mjs onboard
@@ -12,64 +12,58 @@ node .cyc/engine/bin/cyc.mjs onboard --verify
12
12
  node .cyc/engine/bin/cyc.mjs onboard --host codex --session GATE_ID --token CURRENT_INJECTED_TOKEN
13
13
  ```
14
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.
15
+ Plain onboard is read-only. It reports installation integrity, configured commands, retained setup checks and current host observations. environment identifies this CLI's Node/OS/architecture, not the host application's version. Config-only/plugin projects need no installation manifest, but host availability still needs confirmation.
16
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.
17
+ The agent reads discovered CI/project files, explains relevant checks and reuses authorized team configuration. Filenames do not authorize commands. Missing meaningful checks remain a gap. After reviewing side effects, --verify runs configured commands and saves .cyc/runtime/onboarding-checks.json, bound to configuration and covered source. Failed, source-mutating, malformed or stale results cannot pass. Setup receipts replace neither task verification nor a measured original baseline.
18
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
19
  Installed files → Configured checks → Executed checks → Observed host activation → First bounded task
23
- ```
24
20
 
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.
21
+ | guidance.outcome | Meaning and next action |
22
+ | --- | --- |
23
+ | setup-needed | Address the first unresolved step in nextAction; keep other gaps visible |
24
+ | task-can-start | Current prompt observed; continue the authorized task while Stop is pending |
25
+ | setup-checked | Setup has matching local checks and host observations; task success still needs verification |
26
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.
27
+ ok/ready remain false (exit 1) until installation, configuration, checks and host evidence pass. canStartTask permits authorized work before its own Stop callback, avoiding a circular wait. With no authorized task, recommend a bounded one and let the user choose before product edits.
28
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.
29
+ For native activation, supply only this request's injected token and actual host/session. Missing prompt state requires inspecting exact hooks and supported host trust controls, then a fresh session/reload. Never repair this by simulating callbacks, editing trust/state, copying old tokens or inventing Cursor tags. Matching prompt evidence stays pending until post-turn Stop accepts the exact request/response and current implementation/configuration/declarations. Rejection needs correction; blocked/not-ready completion, changed artifacts and stale identities cannot establish readiness. Cursor requires its separate conversation/tag correlation and remains unverified by this checker. Local editable traces are observations, not independent certification. See [installation](installation.md#activation-and-diagnosis).
30
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.
31
+ onboard also reports executing-engine identity and an experience view: outcome/preserved behavior before work, consequential rule/decision/check during work, evidence/limits/retained context after work. It certifies neither understanding nor task success. hostVersion remains null unless separately observed; another CLI on PATH is not the running host. responseChoices uses current bound prompt preferences only; missing state remains unverified. Share report fields deliberately, redacting paths/session metadata as needed; never share live tokens or fabricate an activation export.
32
32
 
33
- ## Recovery
33
+ ## Completion guidance
34
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.
35
+ Normal run finish and bounded run wait return additive guidance without replacing existing result/receipt fields:
40
36
 
41
- | Observation | Next action |
37
+ | outcome | Meaning |
42
38
  | --- | --- |
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 |
39
+ | in-progress | Operation active, or one check passed; the workflow is unfinished |
40
+ | needs-input | Fill the exact nextAction.inputTemplate for context or proof judgment, then use its run-bound command |
41
+ | needs-repair | Inspect the failed step/receipt or delivery-publication error before retrying |
42
+ | blocked | Resolve the recorded restriction; preserve work, evidence and budgets |
43
+ | complete | Completion recorded; consult the review and delivery evidence for scope and limits |
50
44
 
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.
45
+ Silence is not success. A finished worker is distinct from a finished workflow. Recorded completion with failed delivery publication needs repair. Use returned operation handles for progress; locks serve ownership/recovery. See [runtime](runtime.md#execution-capabilities-and-progress).
52
46
 
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.
47
+ ## Recovery
54
48
 
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.
49
+ Run recover --run RUN_ID reads the original goal, criteria, stages, budgets, source constraints, handoff and latest receipt. It changes no source, state, review, receipt or budget. Files remain in place; inspection is not backup/rollback and earlier commands may have side effects.
56
50
 
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.
51
+ guidance explains the state. nextAction.command supplies an exact owned resume command only for a resumable paused run, or read-only run next guidance for continuing work. Inspect the diff first. Other recovery actions have no automatic mutation command: resolve blockers before resuming; inspect failed checks and stale reviews; terminal/halted/exhausted/stopped runs cannot resume or reset their budgets. Preserve unrelated edits.
58
52
 
59
- ## Proof conflicts and interrupted ownership
53
+ lastCheck is historical diagnosis; verification describes current executable evidence. Reading an old passing receipt cannot restore it. Missing executables and timeouts identify setup observations, not product causes; ordinary failing exits need investigation. Passing commands still require current semantic review and criterion evidence. The existing review.md remains the handoff.
60
54
 
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.
55
+ Before delivery use request-scoped [readiness and packet checks](runtime.md#move-through-the-recorded-stages). A completed replacement cannot conceal a stopped original. Diagnostic --since windows use the actual request start and do not override mapped native windows or certify activation.
62
56
 
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.
57
+ ## Proof conflicts and interrupted ownership
64
58
 
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.
59
+ Proof conflicts/restoration failures halt the run and retain proofRecovery backups/manifest and unexpected bytes. Preserve current files, locks and candidate evidence; compare and merge deliberately. A dead process does not establish restoration. Never blindly overwrite files, replay staged state, clear active locks or reset a budget to obtain success.
66
60
 
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.
61
+ Busy workspaces defer current-source claims. Failed state/review publication returns inspect-operation-commit: old passing fields/reviews remain untrusted until reconciled. Follow the [shared ownership/recovery contract](runtime.md#shared-working-folder-ownership), including process identity and retained backup pointers. Locks coordinate controllers, not arbitrary editors or external systems; stronger isolation needs a separate quiescent working folder.
68
62
 
69
63
  ## Unavailable original-source proof
70
64
 
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.
65
+ [Run-start originals](runtime.md#run-start-originals) support plain/no-commit projects. Missing/changed captures refuse before swapping. Restore only retained bytes matching initial hashes; never relabel repaired code as original. Historical runs retain their limits. Supported exemptions need actual reasons/alternative evidence; unresolved requirements stay blocked.
72
66
 
73
67
  ## Validation boundary
74
68
 
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.
69
+ Run node --test for regression coverage; --test-concurrency=2 bounds local scheduling without excluding tests. Simulated hook events test adapters, not live activation. Record actual host/version, prompt and post-turn completion observations separately; missing capabilities stay unverified. See [qualification](validation.md#native-host-qualification). Process checks do not establish product readiness, user comprehension or workflow savings.
@@ -26,23 +26,25 @@ Each manifest is checked once per lookup. Output reports the checked-file count
26
26
 
27
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
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.
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. Brackets in actual framework paths such as src/app/events/[eventId]/route.ts are literal, not character classes; traversal/backslashes/unsupported braces remain rejected. Catch-all reference matching cannot satisfy required focused feature retention. 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
+ Each context match now explains its selection: match.kind is path or advisory goal; match.paths lists requested paths and matching Covers patterns, while match.words identifies goal terms. The additive recordEvidence array leaves the existing records shape intact and checks only the newest canonical History's selected SHA-256 bindings, once per lookup and at most the lookup limit. It reports matches, drifted, missing, invalid or unverified, checked/total counts and truncation. Reference prose, commit-only bindings and absent evidence stay unverified. Matching selected bytes never establishes complete dependency coverage or semantic truth. Inspect current code and user requirements; conflicting notes cannot override them. Discovery still runs no project commands.
30
32
 
31
33
  ## Component context docs
32
34
 
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`.
35
+ The target index maps focused canonical feature/component records, with Covers, resolving Doc link, Last AI change and Lessons. Read matched records, not all historical prose. Configure context.directory before start only to reuse a project-owned equivalent. Default is docs/context/; engine/runtime knowledge is never target context.
34
36
 
35
37
  ```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
38
+ node .cyc/engine/bin/cyc.mjs context prepare --run ID [--file CONTEXT.json]
39
+ node .cyc/engine/bin/cyc.mjs context review --run SOURCE_ID
40
+ node .cyc/engine/bin/cyc.mjs context review --run SOURCE_ID --write --update-run UPDATE_ID
39
41
  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]
42
+ node .cyc/engine/bin/cyc.mjs context measure --path src/orders [--run ID]
41
43
  ```
42
44
 
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.
45
+ Normal finish performs preparation/retention validation before proof/final checks. Plan canonical docs/index before Build; fill learning.context or author the records. Missing knowledge returns needs-context. Read-only review proposes catch-up from actual completed evidence, naming absent fields rather than inventing observations. Writing requires a new implementation update with a required canonical plan and final executable checks; optional --new NAME scaffolds unmapped records with failing placeholders. It preserves Current view/completed receipts and inserts chronological actual History, lessons and index metadata. Then author the update's own context and verify final files. A packet cannot bypass freshness. See [Context](../methods/cyc-context/SKILL.md) for the fixed layout, provenance and restrictions.
44
46
 
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.
47
+ Manual context lint audits all docs/index and supported Git freshness; automatic retention limits content reads to planned docs plus index consistency. Dirty means uncommitted covered changes, stale-against-git means later covered commits. Context measure counts selected linked local files once, estimates tokens as characters/4 and cannot see chat usage or establish savings/reuse success. See [context guide](context.md).
46
48
 
47
49
  ## Register a reusable project tool
48
50
 
@@ -103,6 +105,10 @@ When repeated manual investigation or a user correction yields a useful command,
103
105
 
104
106
  ## Integration reasoning retained 2026-10-20
105
107
 
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.
108
+ listRecipes/investigateProject share validateRecipeKind/recipesFor; kind never alters context/freshness. Filtering precedes enrichment/counts/limits, preserves explicit-path precedence and validates the entire registry first. all bypasses relevance, not kind. Run node --test --test-name-pattern "investigate kind|recipe kind" test/project-tools.test.mjs or project-tools-contract for API/CLI/disposable-install coverage and unchanged fixture checks. Its investigate regressions failed on originals and passed after repair. This supersedes TOOLS-002's list-only scope; TOOLS-003 retains observed local evidence, not host activation or acceptance.
109
+
110
+ ## External browser recipes
111
+
112
+ A verification recipe may add browser:{prerequisiteFiles,viewports,journeys}. Each viewport names width/height; each journey has unique id, named state, actions and outcomes. scanState optionally chooses scanner state. Inspect existing preview/CSS/build prerequisites first. runRecipe accepts a driver bound to the host's actual supported open/act/observe/close handles and a separate scanner function. It never installs dependencies or instruments application layouts/configuration. CLI execution without capability returns one precise limited result and retained receipt; interruption is nonpassing.
107
113
 
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.
114
+ Scanning uses a separate context. Batch independent observations only after known actions and explicit adapter permission. Declare proportional desktop/phone and applicable send/reload, empty/error, membership-loss, overflow, keyboard/history/focus checks. Observations and source/configuration stability remain distinct from command receipts and host activation. The development test/browser-recipe.test.mjs uses a separate Playwright/axe harness and seeded desktop/phone name/focus defects. Missing harness prerequisites are explicitly skipped, never repaired through app rewrites.