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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/README.md +25 -254
- package/bin/cyc.mjs +61 -23
- package/docs/assets/cyc-method-library.svg +1 -39
- package/docs/assets/cyc-overview.svg +1 -44
- package/docs/assets/cyc-workflow-diagram.svg +1 -415
- package/docs/context.md +13 -23
- package/docs/cyc-workflow.md +31 -84
- package/docs/installation.md +66 -124
- package/docs/onboarding-recovery.md +31 -37
- package/docs/project-tools.md +16 -10
- package/docs/response-standard.md +16 -32
- package/docs/runtime.md +22 -224
- package/docs/skill-contract.md +13 -56
- package/docs/task-context.md +56 -0
- package/docs/validation.md +2 -0
- package/docs/work-assessments.md +25 -92
- package/methods/cyc-build/SKILL.md +8 -53
- package/methods/cyc-challenge/SKILL.md +4 -0
- package/methods/cyc-context/SKILL.md +20 -53
- package/methods/cyc-context/references/evidence.md +1 -1
- package/methods/cyc-context/references/templates.md +4 -11
- package/methods/cyc-deliver/SKILL.md +6 -42
- package/methods/cyc-remember/SKILL.md +1 -1
- package/methods/cyc-scout/SKILL.md +17 -51
- package/methods/cyc-setup/SKILL.md +7 -19
- package/methods/cyc-verify/SKILL.md +15 -66
- package/methods/cyc-verify/references/recipe.md +2 -0
- package/package.json +9 -1
- package/plugin.json +1 -1
- package/rules/cyc-delivery.mdc +33 -33
- package/scripts/browser-audit.mjs +53 -0
- package/scripts/catalog.mjs +9 -2
- package/scripts/codex-host.mjs +178 -0
- package/scripts/context-review.mjs +212 -29
- package/scripts/delegation.mjs +156 -0
- package/scripts/execution.mjs +51 -0
- package/scripts/onboarding.mjs +14 -1
- package/scripts/packet.mjs +21 -6
- package/scripts/project-tools.mjs +43 -20
- package/scripts/recovery.mjs +20 -1
- package/scripts/response-mode.mjs +8 -0
- package/scripts/run-worker.mjs +4 -0
- package/scripts/runtime.mjs +648 -68
- package/scripts/swarm.mjs +154 -0
- package/scripts/task-context.mjs +164 -0
- package/scripts/work-review.mjs +32 -10
- package/skills/cyc/SKILL.md +29 -70
package/docs/installation.md
CHANGED
|
@@ -1,202 +1,144 @@
|
|
|
1
1
|
# Installing CYC in an existing project
|
|
2
2
|
|
|
3
|
-
CYC
|
|
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
|
-
|
|
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
|
-
|
|
7
|
+
~~~text
|
|
8
|
+
npx cyc-stack@latest init
|
|
9
|
+
~~~
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
Reload and ask /cyc to configure checks; download alone does not activate CYC. From a reviewed checkout:
|
|
10
12
|
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
|
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
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
|
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
|
-
|
|
|
51
|
+
| Location | Purpose |
|
|
70
52
|
| --- | --- |
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
138
|
+
Dispatch with matching existing input tag, event SHA/ref and checkout HEAD:
|
|
197
139
|
|
|
198
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
33
|
+
## Completion guidance
|
|
34
34
|
|
|
35
|
-
|
|
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
|
-
|
|
|
37
|
+
| outcome | Meaning |
|
|
42
38
|
| --- | --- |
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
47
|
+
## Recovery
|
|
54
48
|
|
|
55
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
57
|
+
## Proof conflicts and interrupted ownership
|
|
64
58
|
|
|
65
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
package/docs/project-tools.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
37
|
-
node .cyc/engine/bin/cyc.mjs context review --run
|
|
38
|
-
node .cyc/engine/bin/cyc.mjs context review --
|
|
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
|
|
42
|
+
node .cyc/engine/bin/cyc.mjs context measure --path src/orders [--run ID]
|
|
41
43
|
```
|
|
42
44
|
|
|
43
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|