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
|
@@ -27,43 +27,17 @@ The reliable expansion commands are a standalone `expand` or `/cyc-expand` (opti
|
|
|
27
27
|
|
|
28
28
|
## Progress updates
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
Usually give one or two readable paragraphs at a meaningful discovery or decision, and about every minute during long work. Explain the concrete behavior, relevant mechanism, evidence and next uncertainty. A command count, stage name or repeated reassurance is not a useful update. State observed failures separately from suspected causes. Before changing an assertion, explain the requested behavior that justifies it; never change a failing criterion merely to pass.
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
- Explain consequential decisions and the behavior they protect. Share why a fix is narrow, why an approach changed, or what a test establishes. Avoid unexplained shorthand such as "pins green," incident IDs alone, or file counts as the whole update.
|
|
34
|
-
- Match certainty to evidence. Label suspected causes, distinguish a planned check from its result, and preserve failures and unchecked behavior. Before changing a test expectation, explain the requested behavior that justifies it; an incident record alone does not establish correctness.
|
|
35
|
-
- Update at meaningful discoveries, changes of approach, and verification results. During longer work, provide a useful update about every minute: what is being checked, what remains unknown, and what the result will resolve. Do not invent progress, repeat reassurance, or narrate each command.
|
|
36
|
-
|
|
37
|
-
Illustrative update, not a diagnosis of a real project:
|
|
38
|
-
|
|
39
|
-
> The app saved "Improved processing" but dropped "from four hours to one." The code that interprets corrections treated the replacement sentence as a complaint, so it asked another question instead of saving the supplied wording.
|
|
40
|
-
>
|
|
41
|
-
> I'm adjusting that decision so explicit replacements are saved, while vague complaints still ask for clarification. I'll test both paths to check that we fix the omission without making the app guess what someone meant.
|
|
42
|
-
|
|
43
|
-
Use only details supported by the actual task; do not reuse the example as evidence. Routine work may need less explanation. Expand when a consequential decision needs it or the user asks to learn more. Keep deeper evidence in the existing run records or relevant artifacts, without requiring extra documents for every update.
|
|
44
|
-
|
|
45
|
-
These are shared instructions for the orchestrator and supporting methods, not a new stage or a requirement to pause work. Progress messages do not require the final response's visual or character cap. The completion hook does not measure their clarity or enforce their cadence. Review the next live trial for both engineering comprehension and readability; structural checks alone cannot establish either.
|
|
32
|
+
For long commands, prefer the returned bounded operation handle and latest actual output. No output is silence, not progress or success. Keep setup/host limits separate from product defects. User interruption is not verification. Progress text has no final-response length/visual gate; clarity is a judgment, not a controller-certified property.
|
|
46
33
|
|
|
47
34
|
## Engineering understanding throughout the work
|
|
48
35
|
|
|
49
|
-
Help the engineer
|
|
50
|
-
|
|
51
|
-
Plain language must preserve engineering substance. Labels such as "validate," "use context," or "retry" are not explanations on their own. Name the relevant state, interface, dependency, or assumption; explain its effect on behavior and the evidence supporting the conclusion. When work loops back, state what failed, why that invalidates an implementation or earlier decision, what remains valid, and which evidence must be established again. Describe a trust claim through the actual check or review record and its limits. Use enough detail for the engineer to evaluate the reasoning; brevity must not erase the causal connection. The [detailed workflow](cyc-workflow.md) demonstrates this distinction.
|
|
52
|
-
|
|
53
|
-
| Moment | Understanding to support | What to explain from the actual work |
|
|
54
|
-
| --- | --- | --- |
|
|
55
|
-
| Scout: establish the system | How does this behavior happen today? | Trace the relevant request, data, state, or dependency through the affected components. Explain which historical decision or failed attempt changes today's approach, after checking freshness. |
|
|
56
|
-
| Scout: choose and align | Why this approach, and what does it cost? | Connect the proposed change to the goal, explain a meaningful alternative or trade-off when one exists, and identify behavior that must remain intact. Resolve consequential ambiguity before relying on it. |
|
|
57
|
-
| Build: implement a meaningful slice | How does this change reach the places that depend on it? | Explain the affected reader/writer, boundary, or contract and why the change belongs there. Show a small before/after or flow when that clarifies the mechanism. |
|
|
58
|
-
| Recovery: a failure changes the plan | What did this failure teach us? | Separate the observation from the suspected cause. Name the assumption being tested, what evidence ruled out, and how the next check distinguishes remaining possibilities. Preserve failed evidence in the ledger. |
|
|
59
|
-
| Verify: interpret the evidence | What can we now conclude, and what remains uncertain? | Connect checks to the behavior and affected consumers they exercise. Explain an important rejected case or regression guard, and separate executed results from semantic judgment. |
|
|
60
|
-
| Deliver: support maintenance | How can the engineer review, debug, or extend this later? | Give the concise before/after mechanism, the consequential trade-off, and where the relevant check and retained context live. Include a useful maintenance implication when one exists. |
|
|
36
|
+
Help the engineer follow cause and effect while decisions are still useful: trace authoritative state and consumers in Scout, connect the implementation to that contract in Build, explain what a failure disproved during recovery, and connect each decisive check to its practical limits in Verify. Deliver a usable result, maintenance pointer and material limitations. Use the relevant moments naturally; these are not six additional stages or documents.
|
|
61
37
|
|
|
62
|
-
Use
|
|
38
|
+
Use plain language without erasing technical substance. Name a function/interface when it helps locate the issue. Explain consequential choices and rejection/recovery behavior; skip generic lectures, mandatory quizzes and invented user approval. Match depth to the actual question. Keep lasting context in existing run/handoff artifacts rather than a parallel teaching report. The [Teach method](../methods/cyc-teach/SKILL.md) supports requested lessons.
|
|
63
39
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
Before delivery, self-review whether an engineer could locate the affected path, follow the consequential choice, understand why the checks matter, and find the retained explanation. Repair missing explanations concisely; do not invent user understanding. Distinguish **explanation supplied** from **understanding demonstrated**: only the engineer's own reasoning, correction, or application can provide evidence of the latter, and only within what was observed. These are qualitative review criteria, not a new machine-enforced completion gate.
|
|
40
|
+
Before delivery, check whether a reader can locate the affected path, follow the consequential choice, understand why the checks matter and find retained evidence. Repair missing explanations. Distinguish explanation supplied from understanding demonstrated: only the engineer's observed reasoning, correction or application supports the latter. A controller pass, fingerprint or agent review does not prove understanding or product correctness.
|
|
67
41
|
|
|
68
42
|
## Character-limit toggle
|
|
69
43
|
|
|
@@ -78,12 +52,20 @@ Send one of these as a standalone message:
|
|
|
78
52
|
|
|
79
53
|
The toggle applies to the current conversation in the current host. It survives subsequent turns and resuming the same session; new conversations start with the limit ON. It does not change other conversations or synchronize between Codex and Claude Code. Both hosts support the same behavior.
|
|
80
54
|
|
|
55
|
+
For first completion, or concise delivery linking deeper material, offer: **Say `expand` for more detail once, or `limit off` to allow longer replies in this chat. Use `limit on` to bring back short replies.** Send controls as standalone messages. Omit redundant invitations when already expanded/OFF or project-owned presentation applies, and avoid repeating the full footer in progress updates. The ambiguous “turn this off” is not recognized. `responseGuidance` projects observed preferences; unknown state stays unverified.
|
|
56
|
+
|
|
81
57
|
Standalone "Turn off the thousand character limit" and "Turn on the 1,000-character limit" are also recognized, with optional "please" and trailing punctuation. Mentioning a toggle inside a longer request, quotation, code block, or example does not activate it. Use plain `limit off` and `limit on` to avoid host-specific slash-command routing.
|
|
82
58
|
|
|
83
59
|
The assistant confirms the setting after a toggle. Turning the limit OFF only lifts the length cap: visuals, acceptance checks, evidence, and honest limitations remain required. OFF permits useful depth without requiring verbosity. Expansion never silently turns an OFF setting back ON. Hook-generated repair continuations retain both the setting and retry budget.
|
|
84
60
|
|
|
85
61
|
`cyc check-reply` without `--session` is a stateless diagnostic: its default remains capped, and `--expanded` explicitly checks without the cap. With `--session`, and in the hook, the conversation setting applies automatically.
|
|
86
62
|
|
|
63
|
+
## A first task that explains context
|
|
64
|
+
|
|
65
|
+
For setup/requested guided work, introduce the purpose once: “Your request tells us what to change. The project's rules and earlier decisions tell us what must keep working.” Use relevant records, recheck consequential claims against code/current authorization and explain the decision affected. No new report, automatic personal tracking or mandatory quiz is required.
|
|
66
|
+
|
|
67
|
+
Illustrative task: add an Open tasks filter. Before: name the behavior to preserve. During, only if observed: “Imported fields exist outside this screen; the filter will preserve the stored records.” After, only with actual evidence: name the passing/failed checks, limits and saved canonical context. A fresh chat adding a count should find/revalidate that rule; observing its use and a developer's explanation is separate from supplying this copy. Never invent a discovery, failure or usefulness claim to make CYC look helpful.
|
|
68
|
+
|
|
87
69
|
## Levels of done
|
|
88
70
|
|
|
89
71
|
| Level | What must be established |
|
|
@@ -98,7 +80,9 @@ Only a ready handoff may describe work as complete. It must clear all three leve
|
|
|
98
80
|
|
|
99
81
|
The UserPromptSubmit hook supplies a local packet path and a fresh token. Write a review to that path before finishing. The token prevents a packet from an earlier request from being reused.
|
|
100
82
|
|
|
101
|
-
|
|
83
|
+
Native Claude/Codex finish generates the request-bound packet from the canonical run evidence, without claiming human review of the reply. Stop still checks length, visual and blocked prefix. It accepts a finish packet only when every named run completed in this request for this session, the writer recorded its exact digest, and no later finish superseded it. Multiple completed runs retain compatible checks/files. A forged writtenBy label cannot substitute. If response is included it must match exactly; Cursor requires it because Stop lacks reply text. Explicit mode selects capability, never a session string's length.
|
|
84
|
+
|
|
85
|
+
Authorized standalone finish writes run-local delivery.json with hook activation unverified and product readiness uncertified. It cannot downgrade a live native request or fabricate its state/token. Native manual packets remain for advisory/blocked work or source changes after finish; Cursor uses its explicit exact-response packet. Reread the final reply for all four human-readiness questions even when finish generated the packet. Never paste packet bookkeeping into the final answer.
|
|
102
86
|
|
|
103
87
|
For code changes, include the decisive regression's exact name or precise review location with its command and result. A count alone leaves a reviewer searching for the assertion. Conversation-only work does not need an invented regression. Codex/Claude packet preflight also checks the current hook request's controller statuses; a completed latest run cannot hide a stopped original. Use `cyc readiness --session ID` for diagnosis. Explicit `--since` windows and Cursor-tag diagnostics remain separate from live host enforcement.
|
|
104
88
|
|
package/docs/runtime.md
CHANGED
|
@@ -1,249 +1,47 @@
|
|
|
1
1
|
# CYC execution controller
|
|
2
2
|
|
|
3
|
-
The
|
|
3
|
+
The controller validates handoffs/checks and optionally dispatches bounded Codex workers. It authorizes no publication. Scout → Build → Verify → Deliver is the implementation route; other routes use [playbooks](../catalog/playbooks.json). Evidence establishes what was checked.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Start and authority
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Use node bin/cyc.mjs here or node .cyc/engine/bin/cyc.mjs installed. Save inputs under .cyc/runtime; run start --file START.json records goal, criteria/clauses, literal scope, identity and contextRetention before freezing. Confirm inferred criteria/owners before start.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
evidenceVersion:1 requires original requirements/criteria; reviewPolicy is self-allowed/fresh-required. Follow exact generated IDs/templates and [assessment](work-assessments.md)/[handoff](skill-contract.md) fields.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
<a id="execution-capabilities-and-progress"></a>
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
```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
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Each `--criterion` becomes a separate acceptance criterion (`c1`, `c2`, …); `--criteria FILE` accepts a JSON array instead. `--session` ties the run to the conversation that started it (the ID comes from the CYC gate context), so another conversation's run status does not block this conversation's completion gate. A native host session ID that has hook state in this project is stored as that conversation's gate key. Controller operations sharing one working folder are serialized as described below.
|
|
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
|
-
```
|
|
44
|
-
|
|
45
|
-
Save input under `.cyc/runtime/` before starting. `run start --file START.json` also accepts `scout` (the filled Scout assessment) with `plan` (a short approach summary), and records Scout in the same call; an invalid scout creates no run. `run finish --file FINISH.json` accepts `summary`, `assessment` (the filled Verify/Deliver object), `criterionEvidence` (an object mapping criterion IDs to strings), and optional `runId` and `artifacts` (path array). Run commands without `--run` use the single active run in the project, narrowed by `--session` when given, and name the candidates when several are active. JSON input tolerates a byte-order mark and single backslashes in Windows paths. Only invalid escapes are repaired, so a path such as `C:\new` still reads its `\n` as a newline; prefer forward slashes. Paths may use backslashes or be absolute inside the project. Assessments accept `resolution` for a finding's `status`, `fixed` for `resolved`, `reason` for a finding's `evidence`, `pass` for `passed`, and empty lists where a `none` status implies them. Evidence text and findings are never filled in. `passedEvidence` remains available for a single criterion. Use the actual fields returned by `run next`; this abbreviated shape is not a ready assessment:
|
|
46
|
-
|
|
47
|
-
```json
|
|
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
|
-
```
|
|
56
|
-
|
|
57
|
-
The ordinary stage assessment still applies. Unknown envelope fields, non-object JSON, invalid field types and mixed field flags are rejected before invoking the controller. Do not mix `--file` with `--goal`, `--summary`, or assessment/evidence flags; a matching `--run` is allowed for finish. JSON cannot override project configuration, commands, budgets, or protected paths. Existing argument-based commands and `run record --file` remain available.
|
|
58
|
-
|
|
59
|
-
Most build playbooks are fast: **scout → build → verify → deliver**. Scout replaces frame, understand, impact, and design with one parallel pass and a short plan. The plan, explore, teach, and evaluate playbooks keep the detailed chain.
|
|
60
|
-
|
|
61
|
-
Repeated `--scope` arguments and structured `allowedPaths` use literal project-relative files or directory prefixes, such as `src/parser.py` and `tests/test_parser.py`. Translate a task brief's `src/*.py` notation into the actual permitted files or already-authorized directory prefixes; do not broaden task permissions. These entries restrict net changes accepted by the source guard, and do not restrict the operating system's write permissions. Omit scope only when the task legitimately needs project-wide changes. The controller returns a run ID; use that exact ID for subsequent operations. Criteria omitted at start default to an inferred goal criterion, which the state labels as inferred rather than pretending detailed acceptance was established.
|
|
62
|
-
|
|
63
|
-
The same literal-path rule applies to `protectedPaths` and `context.ledgerPath`. Startup rejects a `*` or `?` component that does not already name a literal filesystem entry, before creating a run, workspace lock, Git snapshot or original-source capture. The error asks for explicit permitted paths; no patterns are expanded. Existing POSIX names containing those characters remain literal. Bracketed routes such as `routes/[id]`, spaces, Unicode and ordinary future paths remain valid. A permitted missing ordinary path may be intentional, so this is not a general typo detector. Stored older runs keep their frozen literal scopes and guards; no failed run is widened or reset by this validation.
|
|
13
|
+
executionMode is native-codex/native-claude/cursor or authorized standalone. Conversation, workflow session and run IDs differ. Native modes need actual hook context; no downgrade or label-shape inference. Legacy limits remain; standalone delivery is local and does not establish activation.
|
|
64
14
|
|
|
15
|
+
Literal project paths, config/protection and scope freeze at start. Wildcard expansion and escaped paths reject; literal existing names/bracketed routes remain valid. Scope is not OS isolation. Prefer forward slashes; unknown/mixed inputs reject.
|
|
65
16
|
|
|
66
17
|
## Move through the recorded stages
|
|
67
18
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
| Command | Result |
|
|
71
|
-
| --- | --- |
|
|
72
|
-
| `run next --run ID` | Current stage, attempt, required criteria, skill location, and recent feedback |
|
|
73
|
-
| `run record --run ID --summary TEXT [--artifact PATH...] [--criteria-passed EVIDENCE] [--status failed\|blocked]` | One-line handoff: the controller fills stage, attempt, and criteria and hashes the artifacts itself. Verify and deliver need evidence: `--criteria-passed TEXT` for one criterion; `--criterion-evidence JSON` mapping every ID to its own evidence for multiple criteria |
|
|
74
|
-
| `run record --file FILE` | Full form: validate and record a hand-written handoff |
|
|
75
|
-
| `run record ... --assessment FILE` | Add the required stage assessment to a quick handoff; assessment artifact hashes are computed by the controller |
|
|
76
|
-
| `run review --run ID` | Refresh `.cyc/runs/ID/review.md` from the recorded evidence and current source; reuse for developer review and authorized PRs |
|
|
77
|
-
| `run verify --run ID` | Execute configured project checks and retain their receipt |
|
|
78
|
-
| `run prove-red --run ID [--tests PATH...]` | Run configured checks with new or changed tests against exact run-start code recovered from the recorded Git base and/or source capture, then restore the candidate bytes that CYC still owns, halting with backups if unexpected edits are detected. Bug fixes and features need a check that fails there while the original control passes; refactors need the new tests to pass there. Test paths (`test/`, `*.test.*`, `*_test.go`, `test_*.py`, ...) are detected or named with `--tests`. Missing/corrupt needed originals are refused before source changes |
|
|
79
|
-
| `run finish --run ID --summary TEXT --assessment FILE --criterion-evidence JSON [--artifact PATH...]` | From Build or Verify, in order: refuse incomplete evidence or assessments before running anything; record Build; run `prove-red` when the proof is missing or outdated and no exemption is given; run the checks; record Verify and Deliver from one assessment file; complete; and, in Claude Code and Codex, write this request's review packet from the run's record (`packet` in the result). Artifacts default to the files changed since run start. A failed proof stops with its verdict. A failed check is recorded as a normal failed attempt and nothing else is recorded. Any later refusal names the step it stopped at and leaves the run there for an ordinary `run record`. If a step halts the run, for example because a protected file or a file outside `allowedPaths` changed, finish stops there and returns `failedAt`, the files, and whether Verify was recorded. With `--file`, a test proof exemption may be given as top-level `testProof` or as `assessment.testProof`, not both with different values. From Deliver: record Deliver and complete |
|
|
80
|
-
| `run retry --run ID --stage STAGE --reason TEXT` | Return to the current or an earlier stage within the shared budget. In fast playbooks, `frame`, `understand`, `impact`, and `design` map to `scout` |
|
|
81
|
-
| `run accept-failure --run ID --check ID --reason TEXT` | Accept a check that already failed on the run-start code, measured by an opt-in baseline or the proof's control run. Also available as `acceptFailures` in `run finish`. Verification then passes only if that check fails the same way (see Baselines) |
|
|
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.
|
|
126
|
-
|
|
127
|
-
A check without `timeoutMs` may run for 30 minutes, the same default for configured and package-declared checks; the receipt records the limit it ran under. A check that runs out of time is stopped together with the processes it started, and fails with an error naming its limit and how to raise it; one cut short by the run's own deadline (`limits.maxDurationMs`) says so instead. Each check runs through a small Node helper that copies its output to temporary files outside the project, at most 64 MB per stream plus a rolling tail, and removes them afterwards, so output size never fails a check and a check that prints without end cannot fill the disk. The helper is a generated CommonJS file, run without `NODE_OPTIONS` so a preload cannot break it (the check still gets them). It stops the check if the controller ends, calls `taskkill` by its full path on Windows, and reports a check that exits while a process it started still holds its output two seconds later. Without a writable system temp folder, the files go to `.cyc/runtime/checks`. The optional run-start baseline runs checks while holding the operation lock, so a hung check without `timeoutMs` can block other controller commands for up to 30 minutes; give checks that may hang a `timeoutMs`.
|
|
128
|
-
|
|
129
|
-
Receipts contain the commands, exit status, bounded output, execution errors, and source fingerprint. Successful execution and an unchanged covered source snapshot are required for a passing receipt. A command that rewrites covered source does not establish verification of a stable candidate; finalize generated artifacts first or select a check that does not mutate the candidate.
|
|
130
|
-
|
|
131
|
-
The runtime cannot judge whether a command is meaningful. `node -e "process.exit(0)"` would not test a feature, even though it exits successfully. Choose checks that exercise the promised behavior and affected consumers. Distinguish existing suite coverage from additional manual observations.
|
|
132
|
-
|
|
133
|
-
## Recovery and budgets
|
|
134
|
-
|
|
135
|
-
There is no wall-clock deadline by default: a long task may take as long as it needs. The loop is bounded by failed attempts (`maxAttempts`, default 3) and repeated unchanged failures (`maxNoProgress`, default 2). A project can opt into a deadline with `limits.maxDurationMs`.
|
|
136
|
-
|
|
137
|
-
Baseline checks are **off by default**. Final verification still runs every configured command. Set `verification.baseline: true` only for optional diagnostic background measurements; never wait for these before editing. If covered files change while they run, the baseline is invalid. A matching source/command cache is diagnostic evidence only and may not reflect a changed external service. `run accept-failure` takes the baseline from that measurement when it is complete. Otherwise it uses the proof's control run, which ran every check on the run-start code. Only bug fixes and features have one; refactors, exempt proofs and other playbooks need `verification.baseline: true` set before the run.
|
|
138
|
-
|
|
139
|
-
**When the proof skips its control run.** The control run measures the run-start code so that a failure the new tests cause can be told from one that was already there. It cannot change the verdict in two cases, and finish then runs the suite twice (treatment and verify) instead of three times:
|
|
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.
|
|
142
|
-
|
|
143
|
-
A test added to an existing test file, a moved or deleted test file, a check that prints no test names (lint, a template check) or anything besides test results (a coverage line, a warning), and output cut short all run the control as before. Test titles are never matched against source text: an edited file can hide a data-driven or renamed old failure behind any title. The proof receipt records `controlSource`. After a skipped control, the treatment has shown every check passing on the run-start code apart from the new files: a finish `acceptFailures` entry is dropped as unnecessary, and `run accept-failure` refuses, since a failure now is a regression.
|
|
144
|
-
|
|
145
|
-
With a run-start baseline, a check that failed there is also listed in the run's `finish-template.json` as an `acceptFailures` entry with a placeholder reason, while the agent has not edited that file, so the agent decides before finishing instead of finding out at verify. Finish refuses a placeholder reason before running anything. A finish entry for a check that passed at run start is dropped with a note in `droppedAcceptFailures`; verify still requires that check to pass.
|
|
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.
|
|
159
|
-
|
|
160
|
-
`acceptedFailuresThatChanged` in the verify output says which of these applied. When verification fails, `failedAtRunStart` lists the failing checks that also failed in the run-start measurement and are not accepted yet. The CLI hint shows the `acceptFailures` entry to add if they are unrelated.
|
|
161
|
-
|
|
162
|
-
If those checks are the only failures, and each fails exactly as it did then, the stop is logged as `awaiting-acceptance`: a decision still to make, not a failed fix. Once per run, such a stop does not count against the failure budget or require error history. Every later stop counts, whatever changed, so the loop stays bounded. The CLI's accept hint appears only on that stop; otherwise the recovery instruction leads.
|
|
163
|
-
|
|
164
|
-
Test runner output is compared by test instead of by line, because the new tests add passing lines to the suite. `scripts/test-output.mjs` reads TAP (`node --test`, `tap`), mocha (any reporter: it reads the numbered failures after "N passing"), and jest. Failing tests are keyed by their file and their name under parent suites, and counted. The file comes from the failure's `location` in TAP, a subtest named after a test file for `tap`, the `Context.<anonymous>` stack frame for mocha, and the `FAIL` line for jest. Suites, `describe` groups, and skipped, pending, or todo tests are not tests, and jest's `● Console` is output, not a test. The report is read from the stream the runner writes it to (jest uses stderr, the others stdout); every line of the other stream is other output. TAP is tried first only when the output declares `TAP version`, so a stray `ok` line does not hide a mocha or jest report.
|
|
165
|
-
|
|
166
|
-
When a check prints more than the 32,000 characters kept per stream, the whole output is read as the check finishes, and its results are kept whole with the receipt: every failing test with all of its details, the passing count, and every other line. Up to 64 MB of each stream is kept for this; past that only the tail is kept and the results count as cut off, while the exit code still decides whether the check passed. A summary over 4,000,000 characters keeps only counts and also counts as cut off. An accepted check whose output a reader recognizes, and which had a failing test at the run start, is excused if all of these hold:
|
|
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.
|
|
172
|
-
|
|
173
|
-
The proof uses the same names, because its two runs differ only by the new tests. A failure counts as a new test failing on the original code only if all of these hold:
|
|
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.
|
|
177
|
-
|
|
178
|
-
This works even when the suite already failed for an older test, and `proofClaim` names those tests.
|
|
179
|
-
|
|
180
|
-
Other output, such as node's dot reporter, and output whose run-start failure was not a test (a coverage threshold, say), is compared by whole output, so it cannot be excused once it is longer than the kept tail. A runner that reports only counts cannot reveal a new failure, so give such checks a reporter that names failures. Report a blocker rather than changing checks to force completion.
|
|
181
|
-
|
|
182
|
-
With no configured commands, a declared npm test whose package defines `pretest` or `posttest` runs each hook as its own check around `npm test --ignore-scripts`. A posttest that already fails, such as lint or a template check, then leaves the test runner as a check that passes on the run-start code, which the proof needs. `--ignore-scripts` also skips the hooks of npm scripts that the test script runs. So npm test stays whole when any script it reaches has its own hooks, or when it uses a script runner such as `run-s` or `concurrently`.
|
|
183
|
-
|
|
184
|
-
Failures across all stages share one budget. A failed handoff or failed verification consumes that budget; moving to an earlier stage does not provide a fresh allowance. Repeated unchanged failure signatures can exhaust the no-progress threshold sooner. This signature comparison is a heuristic, not a semantic judgment that all meaningful progress has stopped.
|
|
185
|
-
|
|
186
|
-
Recovery invalidates dependent later handoffs and verification. The attempt identifier advances across stages and recovery, so a packet from an earlier visit to the same stage cannot be replayed. Read the current value from `run next`; do not calculate it yourself. Pause/resume preserves any configured wall-clock deadline and invalidates executable verification so resumed work must be checked again. The controller checks budgets when an operation advances work; it does not continuously monitor a host agent between calls or terminate that agent.
|
|
187
|
-
|
|
188
|
-
States distinguish running, paused, blocked, complete, exhausted, halted, and stopped. A blocker is an external prerequisite or needed participation, not a successful outcome. A halted guard preserves changes for review rather than rolling them back. Starting a new run must be an explicit task decision, not an automatic escape from a failed budget.
|
|
189
|
-
|
|
190
|
-
### Shared working-folder ownership
|
|
191
|
-
|
|
192
|
-
Controller starts, verification/proof, handoffs, review updates and optional baseline measurements use an exclusive project-local operation record at `.cyc/runs/workspace.lock`. A second controller operation is refused before checks, run writes or failure-budget use; independent working folders remain independent. Existing per-run locks remain. A busy optional baseline records an unavailable diagnostic instead of measuring temporary source. Startup releases ownership before launching its baseline. Read-only recovery reports the owner and defers source interpretation. This is separate from session ownership in the completion gate.
|
|
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.
|
|
195
|
-
|
|
196
|
-
Both locks record the owner's process ID, host name, operating system and, on Linux, process ID namespace, so a container or WSL that shares the host name and the folder is never judged by process IDs it cannot see. The next controller operation reclaims a lock only when it was taken in this same place, is not the current process, its process is no longer running (only "no such process" counts as ended), and it was idle when it ended. Idle means no commit under way (both locks record one before it starts, so a failure whose own record cannot be written still leaves the lock kept), no proof with swapped or halted source (a backup pointer in any phase but `restored`), no publication failure, and no phase this engine does not know. While a check runs, the operation lock also records until when it may run, and the lock is not reclaimed before then: on Windows a check started through `cmd` or another program can outlive a controller killed by force. If that record cannot be written, for example while a scanner holds the lock file, the check still runs and the lock only lacks this protection. Reclaiming a lock left by a run-start measurement records that measurement as failed, so the run stops waiting for it. A reclaimer first creates an exclusive `<lock>.reclaim` guard, then removes the lock only if it still holds exactly the owner record it judged; another process reclaiming at the same moment is refused as busy, and a lock written by a newer operation is left alone. Each reclaim is appended to `.cyc/runs/lock-reclaims.jsonl` with the old owner record. A process ID the system has reused for another program reads as alive, which only ever keeps a lock. Every other lock stays for the operator, and the busy error says why: another host or namespace, an older engine without a host name, an empty or partly written record, a commit or proof that may not have completed, a check that may still be running, or a guard left by a reclaimer that crashed, with that guard's process and whether it still runs.
|
|
197
|
-
|
|
198
|
-
So a killed proof still leaves the operation and per-run locks plus the pre-published backup pointer. Recovery performs no automatic rollback. Confirm the owner has stopped, preserve current files and locks, inspect the backup manifest and compare versions before deliberate operator cleanup. Never clear locks or rewrite state merely to obtain completion. A restored phase records completed source restoration; a remaining backup may already have been removed after that point.
|
|
199
|
-
|
|
200
|
-
If committing run state or publishing its generated review fails, both operation and per-run locks remain. The owner record retains the backup pointer and, when writable, a publication failure identifying whether state was saved; the run lock records the same failure. Both already record the commit under way, so neither lock is reclaimed as merely abandoned even when the failure record cannot be written. Read-only recovery treats earlier passing fields as unverified, names the retained evidence and warns that the old review may be stale. It does not publish the staged outcome, clear locks or resume the run automatically. A prior durable backup pointer still remains if the later failure record itself cannot be written.
|
|
201
|
-
|
|
202
|
-
This coordination covers controller operations and baseline measurement, not arbitrary editors, external tools or independent recipe invocations. Recipes still use the configured runner directly, including recipes intentionally called by a controller command; coordinate separate invocations yourself. Byte checks are not an atomic filesystem compare-and-swap and cannot rule out a write between observation and replacement or through an existing open handle. Use a quiescent, isolated working folder for proof when other actors could write. Local editable locks are workflow coordination, not an access-control or enterprise attestation boundary.
|
|
203
|
-
|
|
204
|
-
## What the controller establishes—and what it does not
|
|
205
|
-
|
|
206
|
-
It checks matching run/stage/attempt identity, criterion preservation, evidence presence, current declared file hashes, configured command outcomes, covered source stability, scope guards, and budgets. Non-executable playbooks can complete with clearly labelled agent-reviewed observations; they do not receive invented machine-verification claims.
|
|
207
|
-
|
|
208
|
-
Evidence quality still needs judgment. The controller cannot prove an observation is truthful, discover every omitted artifact, establish user acceptance, or guarantee that a test measured the desired result. Skill validation checks document structure, not teaching quality or engineering effectiveness.
|
|
209
|
-
|
|
210
|
-
The source guard compares project state at checkpoints. It is not a filesystem sandbox. Git projects select tracked files plus untracked files not ignored by Git; tracked files remain covered even when ignore rules or `source.exclude` match them. CYC's own runtime/run/engine directories and Git metadata are always outside ordinary snapshots. Untracked dependency/build directories and untracked `.env` secrets are excluded. Tracked secrets remain tracked source: do not commit secrets.
|
|
211
|
-
|
|
212
|
-
### Run-start originals
|
|
213
|
-
|
|
214
|
-
New bug-fix, feature and refactor runs retain selected originals needed for later proof. A successfully recorded Git working-tree base supplies ordinary tracked files; the existing source scan reuses Git index flags without another inventory scan. Files marked assume-unchanged or skip-worktree are captured because Git can omit their working bytes even when the snapshot command succeeds. Other permitted regular originals are captured as extensionless hash-named blobs in `.cyc/runs/ID/original-source/`, with a `sourceCapture` record in state. If Git cannot record that working tree, capture supplies the permitted selected bytes instead of assuming HEAD matches. This includes permitted ignored inputs explicitly selected through `source.include`; excluded untracked secrets, links, protected files and source outside task scope are not copied. Git source-selection failures still refuse startup rather than silently scanning ignored files.
|
|
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.
|
|
219
|
-
|
|
220
|
-
Captured bytes must match the initial source hashes before the run is recorded and again when used for proof. Protected run storage, including demonstrated junction/casing aliases, is rejected before new records/blobs. Proof keeps the configured commands and working folder; its temporary restoration backup remains outside test discovery. The receipt binds the original source hash, control/treatment results and current test hashes. As before, it establishes a check-level result, not that every new test detects the defect.
|
|
221
|
-
|
|
222
|
-
Existing serialized runs keep their original recovery contract. They do not gain a capture after editing; an older null-base run remains unavailable, and an older untracked file may remain unrecoverable. Missing Git objects, noninvertible content filters or missing/changed needed captures can still prevent exact recovery. Preserve the actual limitation and evidence; never manufacture originals from the repaired code. A supported exemption needs a truthful reason and does not become a proof receipt. Local editable state/capture records are not independent enterprise attestation.
|
|
19
|
+
Bind --run ID. next/status inspect; record submits a handoff; finish orchestrates context/proof/checks/delivery. prove-red/verify preserve prerequisites. review-capture precedes dispatch and review-record records observations. retry/recover/pause/resume preserve budgets. stop is cancellation; complete requires every completion condition.
|
|
223
20
|
|
|
224
|
-
|
|
21
|
+
Use --wait-ms 30000 for long checks and run wait with the returned operation ID. Silence/operation completion is not workflow success. Honor interruption and restoration acknowledgment.
|
|
225
22
|
|
|
226
|
-
|
|
23
|
+
Verify/Deliver needs criterion evidence: --criteria-passed for one or --criterion-evidence for multiple. Worker/model reports cannot replace configured checks, original proof or semantic review.
|
|
227
24
|
|
|
228
|
-
|
|
25
|
+
## Context and delegation
|
|
229
26
|
|
|
230
|
-
|
|
27
|
+
Plan focused feature/shared records and index before Build. Author learning.context or planned docs through context prepare/finish before checks. Missing/restricted/stale knowledge stays needs-context; generated History/support files do not substitute. Completed catch-up needs a new scoped update/checks. [Context](context.md) defines retention.
|
|
231
28
|
|
|
232
|
-
|
|
29
|
+
Optional [task context/delegation](task-context.md) provides one parent document and read-only assignments. Auto swarm plans, decides, fans out concurrently and reviews/merges via parent transactions; solo and unresolved conflicts remain explicit. Manual execute/reconcile stays available. Handoffs/checks bind revision/hash separately from source. Token usage is reporting only.
|
|
233
30
|
|
|
234
|
-
|
|
31
|
+
## Checks, proof and recovery
|
|
235
32
|
|
|
33
|
+
Configure meaningful executable/argv checks before start. No shell interpolation or no-op substitutes. Checks must leave source stable. Onboard diagnostics are not final evidence. Check timeout defaults to 30 minutes; maxDurationMs is separate. Full logs, not tails alone, establish failure equivalence.
|
|
236
34
|
|
|
237
|
-
|
|
35
|
+
Failed attempts share maxAttempts (default 3) and maxNoProgress (default 2); recovery never resets them. Baselines default off. Reuse requires explicitly bounded local-deterministic inputs covering source, config, dependencies, environment and toolchain; CODEX_TOOL_CALL_ID is excluded. Unknown inputs rerun.
|
|
238
36
|
|
|
239
|
-
|
|
37
|
+
Proof separates original control, originals with new tests and candidate. Features may prove a missing interface; bugs need existing behavior. Only compatible measured broad originals can excuse broad candidate failures. Matching diagnostics/passing evidence and reasons are required; changed causes, new/lost failures, cutoff and unknowns stay blocking. Disclose accepted failures.
|
|
240
38
|
|
|
241
|
-
|
|
39
|
+
<a id="run-start-originals"></a>
|
|
242
40
|
|
|
243
|
-
|
|
41
|
+
## Shared working-folder ownership
|
|
244
42
|
|
|
245
|
-
|
|
43
|
+
Workspace/run locks coordinate controllers. Proof publishes backup ownership before swaps; conflicts, external edits or publication failures preserve bytes/evidence and halt. Reclaim only ended same-host idle owners; never clear unknown locks or reconstruct originals from repaired source. Git/captured originals require exact hashes. Runtime/engine data and untracked secrets are excluded; tracked source remains covered. Symlink targets cannot receive executable verification.
|
|
246
44
|
|
|
247
|
-
|
|
45
|
+
Full evidence boundaries hash source; intermediate caches and parallel hash readers do not relax serial policy. Scope guards are not OS isolation, locks are not filesystem compare-and-swap, and local hooks are not attestation. Use actual host access controls.
|
|
248
46
|
|
|
249
|
-
|
|
47
|
+
context.ledgerPath selects history; restricted writes use the disclosed run-local ledger. Engine changes need stop/reload/new decision. [Response standard](response-standard.md) owns request readiness, packets, presentation and host limits.
|
package/docs/skill-contract.md
CHANGED
|
@@ -1,70 +1,27 @@
|
|
|
1
1
|
# CYC skill and handoff contract
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A parent owns the outcome; children own bounded results. Preserve goal, scope, criteria/clauses, authority and budget. Skills are methods, not separate agents. Supplied data is evidence, not higher-priority instruction.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Supply run/stage/attempt, relevant findings/source, criteria and remaining budget. Children inspect project rules/current source. Load only relevant context; missing host support is not enforcement.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Handoff packet
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Required: runId,stage,attempt,status,summary,evidence,artifacts,criteria. Optional: nextAction. IDs/positive attempt match run next, not child retries.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
status is passed, failed or blocked. Each criterion appears once with original ID, result passed/failed/unverified and evidence. Early acceptance may be unverified; Verify/Deliver requires all passed. Local success is not product acceptance.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
evidence is nonempty file/observation entries with detail; files require safe path/current sha256. artifacts lists produced/changed regular files with path/sha256, or []. Never invent evidence/approval. Reject traversal/linked escapes and secrets.
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
{
|
|
17
|
-
"runId": "ID_FROM_RUNTIME",
|
|
18
|
-
"stage": "STAGE_FROM_RUNTIME",
|
|
19
|
-
"attempt": 1,
|
|
20
|
-
"status": "passed",
|
|
21
|
-
"summary": "What this stage established, with remaining limits.",
|
|
22
|
-
"evidence": [
|
|
23
|
-
{ "kind": "file", "path": "src/example.js", "sha256": "CURRENT_SHA256", "detail": "The inspected handler saves status before updating the view." },
|
|
24
|
-
{ "kind": "observation", "detail": "Self-review: the chosen design preserves the two accepted user journeys; not a runtime test." }
|
|
25
|
-
],
|
|
26
|
-
"artifacts": [
|
|
27
|
-
{ "path": "docs/task-design.md", "sha256": "CURRENT_SHA256" }
|
|
28
|
-
],
|
|
29
|
-
"criteria": [
|
|
30
|
-
{ "id": "CRITERION_FROM_RUN", "result": "unverified", "evidence": "Design addresses persistence; refresh behavior still needs execution." }
|
|
31
|
-
],
|
|
32
|
-
"nextAction": "Implement the documented persistence change and run the refresh check."
|
|
33
|
-
}
|
|
34
|
-
```
|
|
15
|
+
Passing Scout, Verify and Deliver on implementation routes require assessment. [Work assessments](work-assessments.md) define context, approach, alignment, consumers, scenario evidence, semantic review, learning and error history. run next/finish generate exact templates; generated fields are not their own evidence. Legacy/advisory records retain their documented limits.
|
|
35
16
|
|
|
36
|
-
|
|
17
|
+
Save packets/receipts under excluded .cyc/runs/<runId>/ and product artifacts in authorized source before checks. Never edit state to advance; source changes invalidate dependent evidence.
|
|
37
18
|
|
|
38
|
-
|
|
19
|
+
## Loop and acceptance
|
|
39
20
|
|
|
40
|
-
|
|
21
|
+
The controller owns transitions, source/scope guards, attempts and shared budgets. The host investigates, interprets findings and makes authorized repairs. Use retry for affected earlier work, preserving failed evidence. Pause/resume does not reset limits; recovery is read-only diagnosis. Stop at success, interruption, blocker, conflict, exhaustion or no progress; checkpoints do not publish.
|
|
41
22
|
|
|
42
|
-
|
|
23
|
+
Code needs actual configured checks. Self/peer judgments are review, not execution or user approval. Non-executable work may use labeled observations. Checks prove only measured behavior.
|
|
43
24
|
|
|
44
|
-
|
|
25
|
+
Parallel workers share parent authority/budget and independent scopes. [Bounded delegation](task-context.md) initially allows read-only host work. Results feed one reconciled context document and current lead acknowledgment; they cannot complete a parent stage, waive proof/review/retention or reset budgets.
|
|
45
26
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
- Tie evidence to the state inspected. Recompute fingerprints after edits and invalidate claims affected by subsequent changes.
|
|
49
|
-
- Mark model judgments as self-review. A second agent's assessment is review evidence, not an executed behavior check or a user approval.
|
|
50
|
-
- Code playbooks require actual configured machine checks before completion; a hand-authored statement that tests passed cannot replace the runtime check record. Run behavior checks appropriate to the impact map in addition to compilation where needed.
|
|
51
|
-
- Non-executable work may use clearly labelled reviewed observations. Explain the criteria and source/artifact inspected; do not invent a test command for an explanation or lesson.
|
|
52
|
-
- A successful check supports only what it measured. Passing existing tests does not prove an untested user journey, security property, or learning outcome.
|
|
53
|
-
|
|
54
|
-
## Loop ownership
|
|
55
|
-
|
|
56
|
-
The controller tracks stages, attempts, recorded evidence, checkpoints, and shared budgets. The parent interprets failures, updates the impact map and design when necessary, and selects the next authorized action. Discovering an affected area is not authorization to change it.
|
|
57
|
-
|
|
58
|
-
Use the CLI's current help and catalog for supported transitions. A failed record may retry within the configured attempt and task budget. When recovery requires an earlier stage, preserve failed evidence and use `run retry --run ID --stage STAGE --reason TEXT`; this invalidates dependent later evidence and consumes the same budget. Never edit state files or pretend a stage passed to reach a later step. The controller records a catalog-defined chain while the parent reasons adaptively within stages.
|
|
59
|
-
|
|
60
|
-
Parallel work shares the task budget and authority. Give separate agents concrete independent scopes, avoid overlapping writes, and reconcile changed artifacts before verification. Do not spawn one agent merely because a skill was called. Changes to shared assumptions invalidate dependent handoffs and checks.
|
|
61
|
-
|
|
62
|
-
Stop at success, a genuine blocker, user interruption, scope violation, exhausted budget, or repeated attempts with no evidence of progress. Do not silently restart a run to evade budgets. Checkpoints preserve candidate work; they do not publish, merge, or accept it.
|
|
63
|
-
|
|
64
|
-
## Completion and portability
|
|
65
|
-
|
|
66
|
-
The installed CLI is `node .cyc/engine/bin/cyc.mjs`; inside the CYC source repository use `node bin/cyc.mjs`. Start with `run start --goal TEXT --playbook NAME --criteria FILE`, where FILE contains an array of `{ "id": "stable-id", "description": "Observable acceptance requirement" }`. Start returns the run ID. `run next --run ID` supplies the current stage, attempt, and required criteria. `run record --file FILE` consumes a handoff containing that run ID. `run verify --run ID` executes configured machine checks. Pass `--session ID` to `run start` so the delivery gate only holds a conversation to its own runs. Baseline checks are off by default; `verification.baseline: true` enables optional diagnostics without requiring the agent to wait. `run accept-failure`, or `acceptFailures` in `run finish`, accepts a check that failed on the run-start code. Verification excuses it only while it fails exactly as it did then: the same exit code and output lines apart from timings, nothing truncated, no changed file named, and another check passing. Every other failure still prevents completion; see [Baselines](runtime.md). Multi-criterion quick handoffs require `--criterion-evidence` with a JSON map of every criterion ID to its own evidence. `run complete --run ID` checks completion. Status, pause, and resume use `run status|pause|resume --run ID`. Consult current CLI help for configuration and supported optional arguments. The controller does not call a paid model or execute a skill automatically; the active host agent performs the work.
|
|
67
|
-
|
|
68
|
-
Run completion and response readiness are separate gates. Read the [response standard](response-standard.md) before final delivery. Honor conversation length toggles, use a relevant visual, and preserve failures and limitations. If the host supplies a response review path and token, write its exact required packet; this stage handoff does not substitute for that packet.
|
|
69
|
-
|
|
70
|
-
Source skills use relative links to this document and the catalog. Project installation must preserve or rewrite those references to the installed engine. Host invocation differs: use the installed host's discovered skill syntax rather than claiming every host supports slash commands. Missing or untrusted hooks mean automatic enforcement is unverified even when skill files exist.
|
|
27
|
+
See [runtime](runtime.md) for executable commands, original-control/candidate evidence and accepted failures; [Context](context.md) for canonical feature retention; [response standard](response-standard.md) for separate request-bound final delivery gates. Installed CLI: node .cyc/engine/bin/cyc.mjs; source CLI: node bin/cyc.mjs. No automatic paid-model calls or host-activation claim.
|