cyc-stack 0.7.0 → 0.8.3
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/INSTALL.md +2 -0
- package/README.md +1 -1
- package/bin/cyc.mjs +81 -22
- package/docs/context.md +10 -26
- package/docs/installation.md +4 -0
- package/docs/project-tools.md +14 -10
- package/docs/response-standard.md +8 -32
- package/docs/runtime.md +58 -174
- package/docs/work-assessments.md +25 -92
- package/methods/cyc-build/SKILL.md +1 -1
- package/methods/cyc-challenge/SKILL.md +4 -0
- package/methods/cyc-context/SKILL.md +18 -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 +2 -2
- package/methods/cyc-remember/SKILL.md +1 -1
- package/methods/cyc-scout/SKILL.md +17 -51
- package/methods/cyc-verify/SKILL.md +15 -66
- package/methods/cyc-verify/references/recipe.md +2 -0
- package/package.json +4 -1
- package/plugin.json +1 -1
- package/rules/cyc-delivery.mdc +33 -33
- package/scripts/browser-audit.mjs +53 -0
- package/scripts/context-review.mjs +202 -29
- package/scripts/execution.mjs +51 -0
- package/scripts/packet.mjs +21 -6
- package/scripts/project-tools.mjs +18 -16
- package/scripts/run-worker.mjs +4 -0
- package/scripts/runtime.mjs +482 -65
- package/scripts/work-review.mjs +32 -10
- package/skills/cyc/SKILL.md +24 -71
package/docs/runtime.md
CHANGED
|
@@ -1,205 +1,101 @@
|
|
|
1
1
|
# CYC execution controller
|
|
2
2
|
|
|
3
|
-
The
|
|
3
|
+
The controller validates skill handoffs and configured checks; the host performs the methods. It neither launches model fleets nor authorizes publication. Build routes require Scout context/approach/alignment/consumers, Verify semantic review/consumer checks and Deliver retained learning/error history in existing handoffs.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
New implementation runs (routes containing Build) record work assessment contract v1. Scout must account for context freshness, existing functionality, alignment, and affected consumers. Verify must record semantic review and consumer checks. Deliver must account for retained learning and the selected error ledger. These are fields in existing handoffs, not new stages. See [assessment examples and the knowledge lifecycle](work-assessments.md). Advisory routes and legacy runs retain their prior handoffs and are explicitly labeled.
|
|
5
|
+
Select `evidenceVersion:1` to retain original requirements, criteria/clauses, named scenarios, source-bound review and case-specific proof judgments. `reviewPolicy` is `self-allowed` or `fresh-required`. [Assessment examples](work-assessments.md#versioned-evidence-records) define these fields. Legacy/advisory callers remain supported and labeled; historical reviewer prose is never upgraded into linked provenance.
|
|
8
6
|
|
|
9
7
|
## Start with a project and criteria
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
Create explicit acceptance criteria before starting a substantial run:
|
|
9
|
+
Installed CLI: node .cyc/engine/bin/cyc.mjs; source checkout: node bin/cyc.mjs. --project PATH selects a target; otherwise the CLI finds the nearest parent .cyc/config.json. Save inputs under excluded .cyc/runtime before start. Prefer run start --file START.json for multiline/quoted metadata:
|
|
14
10
|
|
|
15
11
|
```json
|
|
16
|
-
[
|
|
17
|
-
{ "id": "complete", "description": "Marking one assignment finished moves only that assignment." },
|
|
18
|
-
{ "id": "persist", "description": "Refreshing preserves its finished status." },
|
|
19
|
-
{ "id": "count", "description": "The remaining-assignment count stays consistent." }
|
|
20
|
-
]
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
These are illustrative requirements; discover the actual project behavior before adopting them. Save this file before starting the run or beneath an excluded runtime location. Ordinary project files created later count as source changes.
|
|
24
|
-
|
|
25
|
-
```text
|
|
26
|
-
node .cyc/engine/bin/cyc.mjs run start --goal "Add assignment completion" --playbook feature --criterion "Finished work leaves the active list" --criterion "Survives reload" --session <ID> --scope src --scope test
|
|
12
|
+
{"goal":"Repair saved status","playbook":"bug-fix","criteria":[{"id":"reload","description":"Saved status survives reload."}],"allowedPaths":["src","test"],"executionMode":"standalone","session":"workflow-label","contextRetention":{"version":1,"disposition":"required","features":[{"id":"status","doc":"docs/context/status.md","paths":["src/status"]}]}}
|
|
27
13
|
```
|
|
28
14
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
### Structured input without shell quoting
|
|
32
|
-
|
|
33
|
-
Prefer JSON-file input for generated metadata, multiline text, quotes, or literal shell characters. `run start --file START.json` accepts this object; `--project PATH` selects the project independently:
|
|
34
|
-
|
|
35
|
-
```json
|
|
36
|
-
{
|
|
37
|
-
"goal": "Repair saved customer status\nPreserve compatibility.",
|
|
38
|
-
"playbook": "bug-fix",
|
|
39
|
-
"criteria": [{"id": "reload", "description": "Saved status survives reload."}],
|
|
40
|
-
"allowedPaths": ["src", "test"],
|
|
41
|
-
"session": "CURRENT_SESSION_ID"
|
|
42
|
-
}
|
|
43
|
-
```
|
|
15
|
+
Use actual authorized mode/context. Optional scout/plan records Scout once at start; invalid input creates no run. Legacy argument commands remain supported: repeated --criterion yields c1,c2,…; --criteria FILE accepts IDs; omitted criteria are explicitly inferred. Fast routes use scout → build → verify → deliver; detailed plan/explore/teach/evaluate retain their chain. Follow returned exact runId/templates; implicit selection requires an unambiguous owned run, never another conversation's sole run.
|
|
44
16
|
|
|
45
|
-
|
|
17
|
+
JSON accepts BOM/repairs invalid Windows escapes only: use forward slashes because C:\new contains a valid newline escape. Canonical paths stay inside the target. Assessment aliases normalize spelling, not observations. Unknown fields/types and mixed file/field flags reject; matching --run is permitted with finish input. Inputs cannot override config, budgets or protected paths; proofCommands freezes at start.
|
|
46
18
|
|
|
47
|
-
|
|
48
|
-
{
|
|
49
|
-
"runId": "ACTUAL_RUN_ID",
|
|
50
|
-
"summary": "Reload preserves status; live host activation unverified.",
|
|
51
|
-
"criterionEvidence": {"reload": "Named reload regression passes."},
|
|
52
|
-
"assessment": {},
|
|
53
|
-
"artifacts": ["src/store.py", "test/test_store.py"]
|
|
54
|
-
}
|
|
55
|
-
```
|
|
19
|
+
allowedPaths/--scope restrict net changes to literal files/directory prefixes, not OS writes. Translate brief globs into authorized literal paths without broadening. Omit only for project-wide authorization. protectedPaths, context.ledgerPath and source include/exclude use the same literal rule: missing * or ? components reject before locks/snapshots/capture, never expand. Existing POSIX wildcard filenames remain literal; ordinary future paths, spaces, Unicode and [id] routes are valid. Historical scopes stay frozen; no failed run is widened/reset.
|
|
56
20
|
|
|
57
|
-
|
|
21
|
+
## Execution capabilities and progress
|
|
58
22
|
|
|
59
|
-
|
|
23
|
+
New start inputs may set executionMode to native-codex, native-claude, cursor or explicitly authorized standalone. conversationId identifies the real host conversation, session is a separate workflow label, and runId identifies controller work. A label's length does not choose Cursor. Native modes require actual context; standalone cannot downgrade a live native request or create activation evidence. Explicit ownership rejects foreign mutations. Legacy runs retain their original schema/evidence limits. Standalone finish generates run-local delivery.json; native packet tokens, windows, exact-response and blocked-run gates remain active.
|
|
60
24
|
|
|
61
|
-
|
|
25
|
+
Use --wait-ms 30000 on finish/verify/prove-red. operationComplete differs from workflow finished. Phase/check, elapsed time, actual output, logs and a handle support run wait --run ID --operation OPERATION_ID --wait-ms 30000 (maximum 60000). Silence is not success. Owned run stop requests cancellation outside the check lock; wait for acknowledgement and proof restoration. Conflicts retain halted recovery instead. Locks protect ownership/recovery, not status discovery.
|
|
62
26
|
|
|
63
|
-
|
|
27
|
+
Optional proofCommands freezes a focused command array at start; --tests selects swapped files, not execution scope. Final verification still runs all broad commands. Focused proof cannot substitute for a compatible measured original broad failure. Finish requests bounded proof judgment and measures broad originals when needed, retaining compatible focused treatment.
|
|
64
28
|
|
|
29
|
+
Reuse is opt-in per check: reuse:{kind:"local-deterministic",inputs:["explicit/dependency/path"]}. Include relevant non-source inputs. Keys also cover source/tests/configuration, installed dependencies, environment and executable/toolchain bytes. Unknown/unbounded inputs, links, external/freshness checks or changed inputs disable reuse. The existing baseline cache is reused; no competing evidence cache is introduced. Old records are never upgraded without measurement. CODEX_TOOL_CALL_ID is removed from checks and fingerprints; other environment inputs remain bound.
|
|
65
30
|
|
|
66
31
|
## Move through the recorded stages
|
|
67
32
|
|
|
68
33
|
`run next` includes read-only tool hints at Scout/Understand/Impact and recipe-list hints at Build/Verify. Use [project tools](project-tools.md) to select context and applicable project checks from the run's changed paths or declared scope. Recipe execution retains diagnostic evidence outside covered source; it cannot advance stages, reset budgets, or replace the required command/test-proof gates.
|
|
69
34
|
|
|
70
|
-
| Command |
|
|
35
|
+
| Command (always bind --run ID) | Purpose |
|
|
71
36
|
| --- | --- |
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
| `run status --run ID` | Read the complete current state and history (other commands print a compact summary; add `--verbose` for full output) |
|
|
83
|
-
| `readiness --session ID [--since ISO_TIMESTAMP]` | Read current-request controller statuses before delivery. Uses this session's hook `updatedAt` when available; otherwise requires an explicit non-future timestamp. An explicit window is diagnostic and can omit work if chosen incorrectly. Reports no host activation or source-quality guarantee |
|
|
84
|
-
| `run recover --run ID` | Read-only explanation of current constraints, historical check results, preserved work and the next justified action; does not resume or reset a run |
|
|
85
|
-
| `run pause --run ID` | Preserve a running task as paused |
|
|
86
|
-
| `run resume --run ID` | Resume a paused or blocked task without resetting its budget |
|
|
87
|
-
| `run stop --run ID` | End the run without claiming success |
|
|
88
|
-
| `run complete --run ID` | Check that every stage and required completion condition passed |
|
|
89
|
-
|
|
90
|
-
The active host agent reads the current skill, performs its bounded work, and writes the [handoff contract](skill-contract.md). Save packet files beneath `.cyc/runs/ID/`, not beside application source. Do not modify controller state or verification receipts. The response hook has a separate packet format; neither packet substitutes for the other.
|
|
91
|
-
|
|
92
|
-
`run next` exposes `assessmentRequired`, an `assessmentTemplate` to fill in (at Verify it covers Verify and Deliver, with consumer checks prefilled from Scout, and `finishWith` shows the call), `workContractVersion`, and `reviewPath`. Both list only the fields the agent must judge. The controller records the rest when they are left out, and says so in each one's reason: `learning` as none, `errorHistory` as none for a run that is not a bug fix and has no failed attempt, and Scout's `context` as none when the project has no `docs/context/INDEX.md` and no ledger. A bug fix's error history, consumer checks and the semantic review always come from the agent. Once the run reaches finishing, the whole finish input is also written once to `.cyc/runs/ID/finish-template.json`. The agent's edits to it are never overwritten; while it is untouched, a run-start baseline that finds a failing check adds that check to its `acceptFailures` with a placeholder reason. The compact CLI output then shows `finishTemplate` first and prints the inline template only with `--verbose`. Any leftover `<placeholder>` value or `a | b` choice is rejected, so a template submitted unedited never passes. The generated review updates at recorded mutations and preserves recovery history while dropping invalidated later assessments. Refresh it after external edits to mark stale results. It lives outside covered source; durable context/ledger files do not. Finish intended project documentation edits before final verification. Pending acceptance uses a referenced run-local draft, never invented approval. The Deliver handoff also records `contextDocs`: the component docs under `docs/context/` among the artifacts and `learning.artifacts`, printed in `review.md` and read by `cyc context review`, which proposes a component doc entry from a completed run's record ([project tools](project-tools.md#component-context-docs)). A passing Verify handoff's semantic review is tied to its source snapshot; later source changes require retrying Verify even if commands have since passed again.
|
|
93
|
-
|
|
94
|
-
Pass every configured criterion ID exactly once in each handoff. Early stages can honestly mark task criteria unverified. Passing verification or delivery requires all criteria passed. A successful early stage means its local output is usable, not that the whole feature already works.
|
|
95
|
-
|
|
96
|
-
## Configure meaningful executable checks
|
|
97
|
-
|
|
98
|
-
Use `onboard` to inspect setup and locate project evidence sources. After reviewing and authorizing configured commands, `onboard --verify` executes them once and saves a source/configuration-bound diagnostic receipt. This does not replace `run verify`, establish a baseline for `run accept-failure`, or confirm live host activation. See [guided onboarding and recovery](onboarding-recovery.md).
|
|
99
|
-
|
|
100
|
-
Before starting a code run, configure actual project checks in `.cyc/config.json`:
|
|
101
|
-
|
|
102
|
-
```json
|
|
103
|
-
{
|
|
104
|
-
"schemaVersion": 1,
|
|
105
|
-
"limits": {
|
|
106
|
-
"maxAttempts": 3,
|
|
107
|
-
"maxNoProgress": 2
|
|
108
|
-
},
|
|
109
|
-
"verification": {
|
|
110
|
-
"commands": [
|
|
111
|
-
{
|
|
112
|
-
"id": "tests",
|
|
113
|
-
"command": "node",
|
|
114
|
-
"args": ["--test"],
|
|
115
|
-
"timeoutMs": 900000
|
|
116
|
-
}
|
|
117
|
-
]
|
|
118
|
-
},
|
|
119
|
-
"protectedPaths": []
|
|
120
|
-
}
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
Use the project's own executable and arguments; this Node example does not imply another language's project must use Node tests. Commands run without shell interpolation, with the project as working directory. On Windows, use an actual executable or explicitly invoke the project's intended runner rather than assuming shell aliases resolve. Inspect commands for intended side effects before authorizing their execution.
|
|
124
|
-
|
|
125
|
-
Configuration is captured at run start, and `.cyc/config.json` is protected against changes during that run. Additional `protectedPaths` are separately fingerprinted even when ordinary source snapshots exclude their directory. Do not weaken checks mid-run to obtain a green result. A legitimate configuration correction requires an explicitly explained new run, preserving the earlier outcome rather than hiding it.
|
|
37
|
+
| run next/status | Next stage/attempt/criteria/templates/skills or full state |
|
|
38
|
+
| run record --summary TEXT --assessment FILE | Quick handoff; generated stage/attempt/artifact hashes. Use --file for full packet. |
|
|
39
|
+
| run finish --file FINISH.json --wait-ms 30000 | Normal resumable context → proof/judgment → broad Verify → Deliver/completion |
|
|
40
|
+
| run prove-red [--tests PATH...] / run verify | Execute proof or broad final checks without skipping prerequisites |
|
|
41
|
+
| run review / review-capture / review-record | Generated review/current source provenance; see assessments |
|
|
42
|
+
| run retry --stage STAGE --reason TEXT | Rewind within shared budget (early detailed stages map to Scout on fast routes) |
|
|
43
|
+
| run accept-failure --check ID --reason TEXT | Judge a compatible measured original broad failure |
|
|
44
|
+
| run recover | Read-only constraints, preserved evidence and justified next action |
|
|
45
|
+
| run pause/resume/stop | Pause; resume without budget reset; stop without success |
|
|
46
|
+
| run complete | Require every completion condition; cannot substitute for finish work |
|
|
126
47
|
|
|
127
|
-
|
|
48
|
+
Quick record needs --criteria-passed TEXT for one criterion or --criterion-evidence JSON per ID for multiple criteria; early criteria can be unverified, Verify/Deliver require passed evidence. Failed/blocked handoffs report that status honestly. Full packets follow the [handoff contract](skill-contract.md). Keep input/receipts in excluded run storage; never edit state to pass. Returned commands/templates preserve exact IDs and agent edits. Current review records feed finish; generated projections are not their own evidence. See [assessments](work-assessments.md).
|
|
128
49
|
|
|
129
|
-
|
|
50
|
+
readiness --session ID [--since ISO_TIMESTAMP] diagnoses request-scoped states. Use the actual hook window; explicit non-future windows may omit work and do not certify activation/quality. Response packets remain separate from handoffs.
|
|
130
51
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
## Recovery and budgets
|
|
52
|
+
## Feature context before completion
|
|
134
53
|
|
|
135
|
-
|
|
54
|
+
Current implementation starts receive contextRetention version 1 independently of evidenceVersion or input envelope. Supply a focused features array [{id,doc,paths}] before Build; omission infers existing focused owners or a goal-named record. Each canonical record and the target index join scope before freezing. New source entrypoints must resolve to planned owners; catch-all records and reference-only rows cannot satisfy retention. Meaningful shared-component changes require their focused records too; inference cannot establish semantic completeness.
|
|
136
55
|
|
|
137
|
-
|
|
56
|
+
Use learning.context [{id,currentView}] in finish, or author planned records then context prepare --run ID. Finish prepares missing records/index and returns noncomplete needs-context with exact remaining input until authored knowledge, index/mappings, current History/source evidence and freshness pass. It does this before proof/final verification; direct verify/complete cannot skip the gate. Current-view authorship binds to selected source; generated History alone is insufficient. Preparation uses actual available observations and stable run/command references, not future passing claims or self hashes. Sequential writes resume without duplicate current History; they are not atomic across files.
|
|
138
57
|
|
|
139
|
-
|
|
140
|
-
- the treatment passes every check, so the new tests would not catch the change; or
|
|
141
|
-
- the change only adds new test files (no existing test file is edited, moved or deleted), and every failure in the treatment is in those files, matched by exact project path, with TAP, mocha or jest output complete enough to name the failing tests and nothing else printed. The treatment is then exactly the run-start suite plus the new files, so the run-start suite alone can only pass.
|
|
58
|
+
Default target convention is docs/context/<feature>.md plus INDEX.md. Configure context.directory before start to reuse a project-owned equivalent directory. Engine/runtime storage is invalid; index/ledger/recipe/receipt files are supporting records, excluded from contextDocs. Validation reads planned docs plus index consistency, not every historical Current view. Semantic correctness and adoption remain agent/reviewer judgments.
|
|
142
59
|
|
|
143
|
-
|
|
60
|
+
An honest nonfeature routine/read-only disposition remains proportional. A feature cannot waive retention through learning:none or an older start shape. Explicit scope/protected-document restrictions remain pending/incomplete without writes. A late need cannot broaden frozen scope. Older stored records preserve their contract and are labeled legacy. Completed-run catch-up requires a new implementation update with a required canonical plan and final executable checks (--update-run ID); fresh verification follows context edits, and a new reply packet cannot restore stale evidence. See [Context](../methods/cyc-context/SKILL.md).
|
|
144
61
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
An accepted check that still fails does not block completion if it fails exactly as it did on the run-start code, and at least one check passes. "Exactly" means:
|
|
148
|
-
- the same exit code and error;
|
|
149
|
-
- the same set of output lines, with only timestamps, clock times, durations, and the process ID in node warnings such as `(node:12316)` ignored;
|
|
150
|
-
- neither output cut off: each stream keeps its last 32,000 characters, so longer output can be compared only test by test (below), and only when a test failed at the run start;
|
|
151
|
-
- no file the run changed named in the output.
|
|
152
|
-
|
|
153
|
-
The receipt marks verification `passed-with-accepted-failures`, `review.md` lists each accepted failure with its reason, and `run finish` returns them for the reply to name. A suite can contain both old and new failures, so any of the following leaves the check **unverified** and blocks:
|
|
154
|
-
- a new or lost line, such as a new failing test, a new lint error, or a version number that moved;
|
|
155
|
-
- a different exit code or a hang;
|
|
156
|
-
- truncated output;
|
|
157
|
-
- a mention of a changed file;
|
|
158
|
-
- a check that printed nothing at the run start.
|
|
62
|
+
## Configure meaningful executable checks
|
|
159
63
|
|
|
160
|
-
|
|
64
|
+
Use onboard for read-only setup; authorized onboard --verify saves diagnostic evidence, not final verification, failure-acceptance baseline or host activation. Configure genuine project checks **before** starting:
|
|
161
65
|
|
|
162
|
-
|
|
66
|
+
```json
|
|
67
|
+
{"schemaVersion":1,"limits":{"maxAttempts":3,"maxNoProgress":2},"verification":{"commands":[{"id":"tests","command":"node","args":["--test"],"timeoutMs":900000}]},"protectedPaths":[]}
|
|
68
|
+
```
|
|
163
69
|
|
|
164
|
-
|
|
70
|
+
Commands use executable/argv without shell interpolation in the target working directory; inspect side effects. A successful no-op is not a meaningful check. Configuration is frozen/protected during a run, including protectedPaths even outside ordinary source selection. A legitimate config correction needs an explained new run preserving the old result, never weakened checks.
|
|
165
71
|
|
|
166
|
-
|
|
167
|
-
- no test fails that did not fail at the run start, and none fails more often;
|
|
168
|
-
- every old failure still has the same error;
|
|
169
|
-
- no failure's stack or error names a changed source file;
|
|
170
|
-
- every line that is not a test result, plan, summary, or failure diagnostic also appeared then;
|
|
171
|
-
- at least one of its tests passes.
|
|
72
|
+
Default timeout is 30 minutes, distinct from optional run deadline. The runner stops process trees on timeout/controller loss/owned cancellation (full-path taskkill on Windows). The helper excludes NODE_OPTIONS; checks retain it. Logs keep up to 64 MiB per stream plus tails outside source; escaped output holders drain for two seconds after exit. Receipts bind commands, actual exit/errors/output and covered source stability. All-green commands that change covered source do not verify a stable candidate; finalize generated files first.
|
|
172
73
|
|
|
173
|
-
|
|
174
|
-
- it sits in a changed test file;
|
|
175
|
-
- it is not an old failure renamed or wrapped in place;
|
|
176
|
-
- neither output was cut off without a complete summary.
|
|
74
|
+
## Recovery and budgets
|
|
177
75
|
|
|
178
|
-
|
|
76
|
+
No wall-clock deadline applies unless limits.maxDurationMs is configured. Failed attempts share maxAttempts (default 3) and maxNoProgress (default 2) across stages; retries cannot reset them. No-progress signatures are heuristics. Pause/resume preserves deadlines and invalidates executable verification. Attempt IDs advance on recovery; read run next rather than replaying an earlier packet.
|
|
179
77
|
|
|
180
|
-
|
|
78
|
+
Baseline measurement is off by default. verification.baseline:true measures originals with workspace ownership; edits invalidate it. Compatible explicitly deterministic inputs use the existing cache. Otherwise accepting an old broad failure needs a measured broad original control. Focused proof cannot excuse omitted broad checks. Refactor/exempt runs needing acceptance must arrange broad originals before edits.
|
|
181
79
|
|
|
182
|
-
|
|
80
|
+
Proof roles remain original-only control, originals-plus-new-tests treatment and candidate. Control may be skipped when treatment passes (no decisive red), or only newly added exact-path tests fail with complete named output and no extra diagnostics. Edited/moved/deleted tests, unknown names, cutoff or other errors require control. Do not infer identities from test source. npm pretest/posttest lifecycle checks remain required.
|
|
183
81
|
|
|
184
|
-
|
|
82
|
+
Finish templates list measured old failures with placeholder reasons; fill genuine reasons or fix them. Passing originals do not need acceptance. A failing candidate check may be accepted only with compatible broad original evidence, at least one passing check, and identical exit/error plus stable failures/non-test diagnostics. Timings, dates, durations and Node warning PIDs may differ. Changed-source stack paths, new/lost failures or lines, hangs, empty/cutoff evidence and changed errors block. Parser-aware TAP/mocha/jest comparison retains identity/file/parent path/count/error; unknown formats use conservative line comparison. Large complete output can compare parsed tests within the 64-MiB limit; 32,000-character tails alone cannot prove equality. See scripts/test-output.mjs and its adversarial tests.
|
|
185
83
|
|
|
186
|
-
|
|
84
|
+
Once per run, only unchanged measured old failures can stop as awaiting-acceptance without consuming the failure budget; later stops count. Accepted failures remain passed-with-accepted-failures and require disclosure. failedAtRunStart and acceptedFailuresThatChanged distinguish missing judgments from incompatibility.
|
|
187
85
|
|
|
188
|
-
States distinguish running, paused, blocked, complete, exhausted, halted
|
|
86
|
+
Recovery invalidates dependent later handoffs/evidence. States distinguish running, paused, blocked, complete, exhausted, halted and stopped. A blocker is an unmet prerequisite, not success. Halt preserves unexpected source for review, not rollback. The controller checks budgets when advancing; it does not terminate the host agent. New runs require an explicit task decision, never automatic escape from a failed budget.
|
|
189
87
|
|
|
190
88
|
### Shared working-folder ownership
|
|
191
89
|
|
|
192
|
-
Controller
|
|
193
|
-
|
|
194
|
-
Proof writes its candidate backup and manifest outside test discovery, then publishes the backup path, candidate source hash and prepared phase in the operation record before replacing source. At phase boundaries and restoration, it compares temporary files with the bytes CYC last placed. A detected edit, deletion, path-type change, restoration error or final source mismatch halts the run, clears current proof/verification and retains the candidate backup. Unexpected regular bytes are also copied into that backup when possible; copy/manifest errors remain disclosed. Other owned paths are restored independently. No successful proof receipt is issued for a conflict. `run recover` and the generated review name the retained evidence and require deliberate comparison/merge; a halted run cannot resume.
|
|
90
|
+
Controller mutations/baselines hold exclusive project-local .cyc/runs/workspace.lock plus per-run locks. A second controller is refused before writes/checks/budget use. Startup releases ownership before optional baseline launch; busy baselines become unavailable. Read-only recovery reports owners and defers source interpretation.
|
|
195
91
|
|
|
196
|
-
|
|
92
|
+
Proof publishes its extensionless candidate backup/manifest pointer and phase **before** temporary source replacement. At each boundary/restoration it compares files with its own last bytes. Unexpected edits, deletion, type changes, restore/publication failures or final mismatch halt the run and retain backup evidence; other owned paths restore independently. Unexpected regular bytes are preserved when possible; capture failures are disclosed. No successful proof receipt is issued for conflicts. A killed proof requires deliberate operator comparison, never automatic rollback or lock clearing.
|
|
197
93
|
|
|
198
|
-
|
|
94
|
+
Locks bind PID, host, OS and Linux PID namespace. Reclaim requires same identity, ended owner and idle phase; commit/publication failures, swapped/halted backups and unknown phases remain protected. Recorded deadlines protect checks outliving the controller; scanner-blocked deadline updates disclose that missing extra protection. Reclaim compares exact owner under its own exclusive guard, preserves newer owners and logs lock-reclaims.jsonl; abandoned baselines become failed. Foreign/unknown owners need operator recovery.
|
|
199
95
|
|
|
200
|
-
|
|
96
|
+
State/review publication failures retain both locks and backup pointer; commit-in-progress remains protected even if writing the failure record also fails. Recovery marks old passing fields/review unverified; it neither publishes the staged result nor resumes work. A restored phase can retain a pointer whose backup was already removed after restoration.
|
|
201
97
|
|
|
202
|
-
This
|
|
98
|
+
This coordinates controller work, not arbitrary editors or independent recipes. Locks are local workflow records, not access control/attestation. Byte checks are not filesystem compare-and-swap; an external write/open handle can race observation/replacement. Use an isolated quiescent folder when proof could overlap other writers.
|
|
203
99
|
|
|
204
100
|
## What the controller establishes—and what it does not
|
|
205
101
|
|
|
@@ -211,23 +107,17 @@ The source guard compares project state at checkpoints. It is not a filesystem s
|
|
|
211
107
|
|
|
212
108
|
### Run-start originals
|
|
213
109
|
|
|
214
|
-
New bug-fix
|
|
215
|
-
|
|
216
|
-
Proof accepts recovered filtered or raw Git bytes only when they match the recorded original SHA exactly. For manually held CRLF bytes that disagree with current Git line-ending attributes, it may try a byte-preserving CRLF reconstruction under that same hash check. Equivalent normalized text is insufficient: unreconstructable mixed endings or other filters still refuse proof. This does not rewrite original hashes, captured-file lists or older run state.
|
|
217
|
-
|
|
218
|
-
Without a Git commit or Git repository, capture supplies the permitted selected originals, so new runs still require a current proof. Narrow `allowedPaths` to the actual task: unrestricted plain projects can capture all covered regular source. Capture holds originals in memory until the run is recorded, so it has its own limit of 20,000 files and 128 MiB, below the selected-source limits; a larger plain project must narrow `allowedPaths` or commit so Git keeps the originals. Equal bytes within a run share one blob. This is working evidence stored separately from the installed engine, not a complete checkout backup or an automatic retention/pruning policy.
|
|
110
|
+
New bug-fix/feature/refactor runs capture permitted selected originals for exact proof. A recorded Git working tree supplies ordinary tracked bytes; assume-unchanged/skip-worktree files and permitted uncaptured originals use extensionless hash blobs in .cyc/runs/ID/original-source with sourceCapture metadata. Without Git, or if Git cannot record working bytes, capture supplies them. Git selection failure refuses startup instead of reading ignored data. Protected/out-of-scope/link/excluded-secret inputs are not captured.
|
|
219
111
|
|
|
220
|
-
Captured
|
|
112
|
+
Captured hashes must match before recording and using originals. Filtered or raw Git bytes are accepted only with exact initial SHA; CRLF reconstruction is attempted only under that same check. Equivalent text is insufficient for mixed endings/noninvertible filters. Missing objects/captures remain unavailable, never reconstructed from repaired code. Historical runs do not gain new captures. Honest exemptions remain labeled limitations, not proof receipts.
|
|
221
113
|
|
|
222
|
-
|
|
114
|
+
Capture holds originals until startup records them: max 20,000 files/128 MiB, deduplicated within a run. Larger plain projects must narrow scope or use Git. Storage is separate from the installed engine, not a full backup or retention/pruning policy. Protected storage/junction/casing aliases are refused before recording. Proof backups remain outside test discovery and bind original source, control/treatment and candidate tests; this establishes check-level evidence, not that every assertion detects a defect.
|
|
223
115
|
|
|
224
|
-
|
|
116
|
+
source.include/exclude use literal relative paths, never globs. Include real generated inputs; exclude only untracked artifacts (tracked files remain covered). Missing wildcard components reject before startup writes; ordinary future paths, spaces, Unicode and bracketed routes remain literal. Existing literal wildcard names on POSIX do not enable expansion or symlink following. Includes cannot expose untracked .env secrets. Non-Git traversal uses dependency/build defaults, not .gitignore. Selected-source defaults are 200,000 files/2 GiB; positive source.maxFiles/maxBytes can change them. Example: {"source":{"include":["generated/api-types.d.ts"],"exclude":["output"],"maxFiles":300000}}.
|
|
225
117
|
|
|
226
|
-
|
|
118
|
+
Evidence snapshots fully hash selected files at start, proof swap/restore, final checks, baseline/recipes/onboarding and completion. Intermediate guarded views can reuse .cyc/runs/source-cache.json SHA when size/mtime/ctime/file ID match a file hashed after two seconds stillness. Windows mapped writes/reset timestamps and FAT can defeat that intermediate heuristic; the next full evidence read repairs it. Stale preverification views make checks unstable, never certify stability. Only operation owners update cache; successful/recorded-failure returns publish accumulated updates, thrown refusals publish none and remove only demonstrated wrong entries. Read-only recover/investigate/recipe list write nothing. Git listing bounds are 512 MiB/two minutes. Scope restricts edits, not fingerprint selection. sourceStable/changedPaths explain mutations during passing checks.
|
|
227
119
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
A full-content snapshot of 1,000 or more files reads them on up to eight worker threads (`scripts/source-hash-worker.mjs`); smaller ones stay on one thread, since workers take about 25 ms to start. Opening each file is most of the cost, about 0.4 ms on Windows with its file system filters, so on this Windows machine a 60,000-file snapshot that took 25.8–26.0 s on one thread takes 6.8 s (three runs each, alternating; four or six threads were slower, more than eight no faster), and a feature run on that project starts in 15 s instead of 35–37 s and finishes in 57 s instead of 133 s. Workers only read and SHA-256 regular files no larger than `source.maxBytes`, in 1 MiB chunks, so a large file never sits whole in memory; like the earlier `readFileSync`, a read stops at the size the file had when opened, and a file over 2 GiB is now hashed instead of failing with `ERR_FS_FILE_TOO_LARGE`. The main thread applies their results in path order, so file selection, limits, the order of entries and so the snapshot hash, and cache updates are those of a single-threaded read. Links, directories, vanished files, a file the byte limit stops, and read errors go back to the main thread, which inspects them in order, so an error is raised where a single-threaded read raises it and a file over the limit is never read. Workers get no `NODE_OPTIONS` or command-line preloads, and their output never reaches a command's result. If no worker has started after two seconds, or no read has progressed for five (workers report each chunk, so a long read counts as progress), the main thread reads the files it is waiting for itself. Before a snapshot returns or throws, it waits for reads in progress, so no worker still holds a file open, giving up only after five seconds without progress. A copy of `source-snapshot.mjs` without its worker file reads on one thread. Cached views and the delivery gate's size-and-time snapshot stay on one thread.
|
|
120
|
+
Full snapshots of at least 1,000 files use up to eight source-hash-worker threads, reading SHA-256 in 1-MiB chunks and applying results/errors in original path order. Links/type changes/read errors/size limits defer to main-thread policy. Workers exclude preloads/NODE_OPTIONS, expose no output and fall back after two seconds without startup or five without progress; snapshot exit waits for active reads, bounded by five seconds of silence. A missing worker module falls back to one thread. Cached/gate views remain single-threaded. Local performance observations are not generalized savings claims; behavior/order/source limits remain those of the serial reader.
|
|
231
121
|
|
|
232
122
|
Linked paths in the covered project tree are fingerprinted by their identity, but their targets are not recursively verified. Executable verification refuses unsupported symlink/junction coverage rather than issuing a passing receipt. Adding or changing such a link is also a source change. Linked dependencies inside excluded dependency directories remain outside this guard's coverage; use the project's dependency controls for those.
|
|
233
123
|
|
|
@@ -236,14 +126,8 @@ Use the host's actual sandbox, access controls, and authorization boundaries whe
|
|
|
236
126
|
|
|
237
127
|
## Project conventions
|
|
238
128
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
Run-local storage retains required failure evidence without authorizing shared-document edits. Deliver still requires the exact selected file and checks its hash; protected-source and scope guards remain. The generated review identifies both paths and deferred shared-log promotion. Search relevant earlier run-local histories too, but disclose that they may exist only in this checkout. Explicit project policies still apply; a separate requirement for a committed shared record cannot be waived by this selection. Later promotion needs authorized scope and fresh verification.
|
|
242
|
-
|
|
243
|
-
Set `delivery.presentation: "project"` when an existing hook owns reply formatting. CYC then delegates length, visuals and presentation review to project instructions, while its controller-completion gate remains active. Cursor still needs the small identity packet described in its installed rule. Defaults retain CYC presentation checks.
|
|
244
|
-
|
|
245
|
-
The delivery gate checks this session's runs in the current checkout and Git-registered worktrees of the same repository. Other sessions and unowned legacy runs in other worktrees are excluded. Arbitrary independent folders are not discovered: use their own activated host session. Worktree discovery is a local protocol check, not proof of live host loading.
|
|
129
|
+
context.ledgerPath selects the existing ledger (otherwise INCIDENT-LEDGER.md, then docs/context/error-ledger.md). Start freezes projectLedgerPath for lookup and ledgerPath for recording. Out-of-scope/protected shared writes use .cyc/runs/ID/error-history.md; a protected fallback rejects before creating the run. Record failures in the selected file, disclose deferred shared promotion and search relevant local histories. Old states retain their selection; explicit shared-record requirements are not waived. See [learning/file order](work-assessments.md#learning-lifecycle-and-final-file-order).
|
|
246
130
|
|
|
247
|
-
|
|
131
|
+
delivery.presentation:"project" delegates reply formatting to project instructions while keeping controller completion gates; Cursor still needs its identity/exact-response packet. Default presentation checks remain. Gate discovery includes this session's runs in this checkout and registered Git worktrees, excludes foreign sessions/unowned legacy runs elsewhere and never searches independent folders. This protocol does not prove live host loading.
|
|
248
132
|
|
|
249
|
-
|
|
133
|
+
An active run cannot advance across an engine-version change: stop, reload and explicitly start new work preserving the prior outcome. Old metadata stays unknown. run next returns internal skill and absolute skillFile paths under the engine; methods are supporting resources, and /cyc remains the public entry.
|