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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Context doc templates
|
|
2
2
|
|
|
3
|
-
These are the shapes
|
|
3
|
+
These are the shapes context lint checks and active-run context prepare/finish produces. Plan canonical paths before scope freezes; historical catch-up with context review --write requires --update-run ID. Names and events below are illustrative; substitute observed findings, actual checks and acceptance evidence.
|
|
4
4
|
|
|
5
5
|
## docs/context/INDEX.md
|
|
6
6
|
|
|
@@ -11,12 +11,10 @@ Read this index first, then only the docs whose Covers match the paths you are a
|
|
|
11
11
|
|
|
12
12
|
| Component | Covers | Doc | Last AI change | Lessons | Reason to read |
|
|
13
13
|
| --- | --- | --- | --- | --- | --- |
|
|
14
|
-
| Context
|
|
15
|
-
| Context doc layout | methods/cyc-context/** | [Templates](templates.md) | none recorded | none | The fixed layout and its rules |
|
|
16
|
-
| Error ledger | all | [Ledger format](../../cyc-error-ledger/references/entry-format.md) | reference row | reference row | Past errors, causes, and fixes tried |
|
|
14
|
+
| Context layout | methods/cyc-context/** | [Layout](templates.md) | none recorded | none | Layout illustration |
|
|
17
15
|
```
|
|
18
16
|
|
|
19
|
-
Links
|
|
17
|
+
Links resolve relative to INDEX.md. Component/Covers/Doc/Last AI change/Lessons are required (Area/Record aliases supported); extra columns survive refresh. Focused canonical rows own feature retention; outside-directory references are useful matched context, never substitute feature records.
|
|
20
18
|
|
|
21
19
|
## docs/context/<component>.md
|
|
22
20
|
|
|
@@ -44,11 +42,6 @@ Completion is a persisted boolean; lists and counts derive from the same selecto
|
|
|
44
42
|
**Decisive check:** These new tests fail on the original code: week view count (check unit). Checks: unit passed (exit 0).
|
|
45
43
|
**Files:** src/homework/select.ts@sha256:9b1c2d3e4f50, src/homework/week.tsx@sha256:0a1b2c3d4e5f, test/homework.test.js@sha256:5e6f708192a3
|
|
46
44
|
|
|
47
|
-
### 2026-09-25 · run 3c9d2e1f-7a8b-4c9d-8e0f-1a2b3c4d5e6f · Mark homework finished
|
|
48
|
-
**Changed:** finished is a persisted boolean; loadAll defaults it for legacy records.
|
|
49
|
-
**Learned:** Hiding finished items with CSS only left the count wrong (count test failed at step 2). Ledger ERR-012: resolved · Homework finished flag missing after reload
|
|
50
|
-
**Decisive check:** These new tests fail on the original code: legacy-record load, double-mark (check unit). Checks: unit passed (exit 0).
|
|
51
|
-
**Files:** src/homework/finish.ts@sha256:1a2b3c4d5e6f, src/storage.ts@sha256:a1b2c3d4e5f6, test/homework.test.js@sha256:f6e5d4c3b2a1
|
|
52
45
|
```
|
|
53
46
|
|
|
54
|
-
Entries are newest first. The `**Files:**` items are `path@sha256:<prefix>` as `--write` records them, or `path@<commit>` when written by hand. The Current view is
|
|
47
|
+
Entries are newest first. The `**Files:**` items are `path@sha256:<prefix>` as `--write` records them, or `path@<commit>` when written by hand. The Current view is authored knowledge: preparation preserves it unless you supply learning.context/records with actual currentView text. Update it when an entry changes the rule a reader should follow, and name who accepted an adopted decision. A hash identifies the bytes an entry describes; it does not establish that the claim is correct or that anyone approved it.
|
|
@@ -1,52 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: cyc-deliver
|
|
3
|
-
description: "
|
|
3
|
+
description: "Deliver the result first with a useful visual, traceable evidence and honest limits."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Deliver the result
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Follow the [response standard](../../docs/response-standard.md) and [handoff contract](../../docs/skill-contract.md). Lead with what works or the actual blocker. Explain the consequential behavior/mechanism and link the relevant source, decisive regression/check and retained context. Distinguish run/read/unchecked evidence; explanation is not comprehension.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Display one relevant visual, even under the default 1,000-character cap. Use observed values only; do not reconstruct a before-value from code. Honor session limit/expand settings and the standard's footer.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Reuse the generated run review and current receipts. Finalize required canonical feature/shared records and index before checks, not afterward. [Task context](../../docs/task-context.md) feeds authored learning.context into existing feature owners; no permanent document per worker. Preserve selected error history and disclose run-local/source-only limits.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
2. **Label each claim in the same sentence.** *Ran*: "the persistence test fails on the old code and passes now." *Read*: "the reminder job skips unknown fields (read, not run)." *Didn't check*: "cross-device sync is untested." For code changes, name the decisive regression test or its precise review location alongside the command/result so a maintainer can find the assertion; this does not apply to conversation-only work. Never hand the reader a check you could have run yourself.
|
|
16
|
-
3. **Frame impact for the user, then the maintainer.** What they will see, then what changed in the code.
|
|
17
|
-
4. **Include and display one visual that carries information, even under the 1,000-character limit.** Choose it with the answer: a diagram or labeled flow for processes and relationships, a data chart for quantities, a before/after for changes, or a table for comparisons and status. Use available rendering tools when helpful; otherwise use a readable text flow. A bare link, decoration, or a table that restates the paragraph above it doesn't count. Check that the visual makes the main idea easier to grasp, not merely that its markup passes the gate. Every number or output in it must be one you observed this run: take "before" values from running the original code, never from reading it. If you did not run the old code, describe the change without a before-value.
|
|
18
|
-
5. **Use the shared review artifact.** Link `.cyc/runs/ID/review.md`, generated from handoffs and receipts, alongside relevant files/diffs. Refresh it with `run review` after external changes and reuse it for an authorized PR. Update underlying records rather than maintaining competing reports.
|
|
19
|
-
6. **Retain what the next task needs.** Follow the [Deliver assessment](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order): record verified reusable facts, actual adopted decisions, and error history with evidence and limits; keep unverified hypotheses or undecided proposals explicit in run-local notes. Name the canonical component/index path so a teammate can find the learning; identify local-only evidence. Bug fixes and recorded failures require the selected `ledgerPath`; when run-local, explain in `errorHistory.reason` that shared-log promotion remains pending authorized scope. Do not claim the shared log was updated. Finalize durable updates before final verification; source changes afterwards require fresh Verify. No reusable finding is a valid `learning: none` with a reason. The Deliver handoff records `contextDocs`, the component docs under `docs/context/` among the artifacts and `learning.artifacts`; a mapped component whose doc the run did not touch is what `cyc context review --run ID` proposes an entry for, from the run's record, and `--write` appends it and refreshes the index (see [Context](../cyc-context/SKILL.md)).
|
|
20
|
-
7. **Check session readiness and say what is left.** The latest run's completion is not the whole session's readiness. Codex/Claude `packet` preflight includes current-request run status; `cyc readiness --session ID` provides a read-only diagnosis. Without mapped hook state, supply the actual request start with `--since ISO_TIMESTAMP`; that explicit window does not replace the Stop hook. Cursor packet preflight leaves controller readiness unverified, so inspect its actual request window separately. Preserve stopped originals and failed attempts; do not start replacements or change a cutoff to evade a block. Disclose accepted pre-existing failures (each with its reason), unverified rows, known limits, and a decision only if one remains. No forced "next task."
|
|
14
|
+
Check all relevant request runs, not only the latest. Do not hide stopped originals, reset budgets or change readiness windows to pass. State accepted old failures with reasons and preserve uncertainty, unverified host activation and missing services. Blocked: names the prerequisite/smallest action; never call it done.
|
|
21
15
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
```text
|
|
25
|
-
Result: one or two sentences.
|
|
26
|
-
|
|
27
|
-
[One displayed visual: changed flow, before/after, or criteria table,
|
|
28
|
-
chosen for what the reader needs to understand.]
|
|
29
|
-
|
|
30
|
-
Changed: files and why (short).
|
|
31
|
-
Not covered: what wasn't checked and why.
|
|
32
|
-
Your call: a decision, only if one exists.
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Done when
|
|
36
|
-
|
|
37
|
-
The first sentence states the result or the blocker. Every claim has a label. The visual is included in the response, its form fits the subject, and it adds understanding. Limits are stated. The length honors the conversation's `limit on` or `limit off` setting; shortening prose must not silently remove the visual.
|
|
38
|
-
|
|
39
|
-
If the host gate provides a review token and packet path: in Claude Code and Codex, a completed `run finish` writes the packet from the run's record, and the Stop gate checks the reply itself. Otherwise (no completed run, files changed after finish, or Cursor) write it with `cyc packet`; Cursor's packet carries the exact final response. Before sending, draft the reply in `.cyc/runtime/reply.md` and run `cyc check-reply .cyc/runtime/reply.md --session <ID>`: it reports the character count, how much to cut, and whether the visual is recognized, writes nothing, and is the same check the gate applies. If hooks aren't active, say that automatic enforcement is unverified.
|
|
40
|
-
|
|
41
|
-
## Anti-patterns
|
|
42
|
-
|
|
43
|
-
| Name | The tell | Fix |
|
|
44
|
-
| --- | --- | --- |
|
|
45
|
-
| Buried lead | Three sentences of process before the result | Result first |
|
|
46
|
-
| Unlabeled claim | "Everything works" | Say what was run, read, or unchecked |
|
|
47
|
-
| Log replay | Narrating each step taken | Report outcomes, link logs |
|
|
48
|
-
| Decoration | An emoji or a table that repeats the prose | Use a visual that adds facts |
|
|
49
|
-
| Reconstructed before-value | A before/after row whose "before" was worked out by reading old code | Run the old code, or drop the before-value |
|
|
50
|
-
| Hedge fog | "Should probably mostly work" | State what's proven and what isn't, plainly |
|
|
51
|
-
|
|
52
|
-
A blocked handoff starts with "Blocked:", names the missing prerequisite, and names the smallest action the user can take. It is never presented as done. If verification failed, send the work back to its stage instead of polishing the summary.
|
|
16
|
+
Native finish generates request-bound delivery evidence where available. Cursor needs its exact-response packet. Draft and check the exact reply with check-reply; missing hooks leave automatic enforcement unverified. Passing a structural gate does not certify correctness or adoption.
|
|
@@ -25,7 +25,7 @@ time stage decision why evidence who
|
|
|
25
25
|
|
|
26
26
|
Write a capsule of five bullets or fewer: destination, current stage, what's proven (with evidence pointers), what's open, and the next single action. Tag each open thread with one status: `[done]`, `[in progress]`, `[blocked: reason]`, or `[dropped: reason]`. Untagged threads count as not done.
|
|
27
27
|
|
|
28
|
-
Point to canonical component context and its relevant constraints/checks instead of copying them into the capsule. Retain verified reusable findings through [Context](../cyc-context/SKILL.md) before final verification; a local decision log alone is not shared project memory. Keep adoption status and technical evidence distinct.
|
|
28
|
+
Point to canonical component context and its relevant constraints/checks instead of copying them into the capsule. Retain verified reusable findings through [Context](../cyc-context/SKILL.md) before final verification; a local decision log alone is not shared project memory. Each new feature and meaningful contract change leaves its planned canonical target-project record/index before completion; use finish/context prepare and preserve restrictions as pending. Completed-run catch-up is a new scoped update with fresh verification, not an edit to old evidence. Keep adoption status and technical evidence distinct.
|
|
29
29
|
|
|
30
30
|
## When resuming
|
|
31
31
|
|
|
@@ -1,67 +1,33 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: cyc-scout
|
|
3
|
-
description: "
|
|
3
|
+
description: "Establish affected behavior, consumers, checks and a short implementation plan before editing; for advisory work, establish the explanation/review scope without assuming edit permission."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Scout, then build
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Read the target context index and matched records before code, then inspect the actual boundary and dirty diff. Reuse relevant constraints, failed approaches and check recipes; revalidate stale claims. Explain why selected context matters: identify the matched path/rule, check its consequential claim against code and the current request, and connect it to a decision/check in the existing Scout fields. investigate reports bounded byte evidence, not semantic truth. Route/workflowAdvice is advisory: confirm actual impact and preserve required checks/review, especially for unknown indirect consumers. Stop when affected behavior, intended files, consumers and decisive checks are understood. Expand for consequential unknowns, not completeness.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
For new websites/composed visual work, use the [frontend design method](../cyc-design/frontend-design/SKILL.md) before markup/criteria: design/decisions.md names archetype, typeface pair, palette, signature and rejection condition; multiple sites include set divergence. Keep actual visual quality within the original criterion mapping. Narrow repairs preserve identity.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
## One focused pass
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
1. Batch independent searches/reads: entrypoint, every reader/writer of affected state, target index/matched history/error ledger, and git status/diff. Use `node <cli> investigate --path <paths>` (or --run ID); inspect returned context/recipes and run only applicable already-authorized investigation checks. Reuse equivalent current evidence, reporting unavailable prerequisites. Missing recipes mean ordinary focused discovery. See [project tools](../../docs/project-tools.md).
|
|
15
|
+
2. Trace authoritative state, permitted writers, ownership, caller invariant and consumers. Choose reuse/extend/repair/create with evidence. Use [architecture questions](../../docs/code-quality.md#choose-a-structure-that-protects-the-contract) when state/interfaces change; compare alternatives only for consequential uncertainty.
|
|
16
|
+
3. Keep the plan short: goal/original criteria and material clauses → approach/reason → context/freshness → files/changes → consumers/contracts → decisive checks → consequential open decisions. Group prose without dropping the original requirement-to-check mapping.
|
|
17
|
+
4. Explain consequential changes as current behavior → proposed change → reason → needed decision. Ask only when missing information changes the solution; otherwise state a supported assumption and continue. Alignment clear follows the request; confirmed needs actual confirmation; unresolved needs-input blocks.
|
|
18
|
+
5. Before Start freezes scope, map each new/meaningfully changed feature and affected shared owner to a canonical target-project context doc, representative paths and index. Supply contextRetention version 1, disposition required, features [{id,doc,paths}]. Reuse focused owners or create distinct identifiable records; inspect automatic inference if omitted. No index means authorized feature work creates a minimal one; context.directory can reuse a real equivalent convention. Restrictions remain pending; never broaden frozen scope later. See [Context](../cyc-context/SKILL.md).
|
|
19
|
+
6. Record Scout once. Scout supplied to run start is already recorded; a second record would land at Build. Otherwise use `run record --run ID --summary TEXT --assessment FILE` with context lookup/freshness, approach, alignment and stable consumer IDs/checks from the [assessment contract](../../docs/work-assessments.md). Keep input JSON in run storage. Advisory routes retain ordinary handoffs and grant no product-edit permission.
|
|
15
20
|
|
|
16
|
-
##
|
|
21
|
+
## Risk and decisive journeys
|
|
17
22
|
|
|
18
|
-
|
|
23
|
+
For a new protected consumer, execute the existing authoritative state-changing entrypoint followed by existing status and the new protected reads **and writes**. Name it in scout.consumers using journey:{name,writer,operations}, then map the same scenario in criterionChecks/consumerChecks without losing original criteria/clauses. Reuse the authoritative resolver or explicitly reconcile canonical/legacy conflicts; never invent an independent membership policy.
|
|
19
24
|
|
|
20
|
-
|
|
21
|
-
- a search for the entry point (the visible string, route, function, or error message)
|
|
22
|
-
- a search for every reader and writer of the data you'll change (field name, storage key, event name, exported function)
|
|
23
|
-
- the existing feature map (if any), `docs/context/INDEX.md`, and the selected error ledger for these paths
|
|
24
|
-
- `git status` / `git diff --stat` when work is already in progress
|
|
25
|
-
2. **Reuse what is established.** Read matching current component context, then inspect the affected functions and integration boundaries. Follow [Context](../cyc-context/SKILL.md) for revision/file-evidence checks; revalidate affected claims when dependencies drift. Reuse still-applicable impact knowledge, failed approaches, and check recipes rather than reconstructing them. Expand for missing consumers or consequential unknowns. State when no history applies. Choose **reuse, extend, repair, or create**, with evidence; use the project's existing capability map. Stop when affected behavior, intended files, consumers, and checks are understood.
|
|
26
|
-
When the change introduces or reshapes state, ownership, or an interface, use the [architecture questions](../../docs/code-quality.md#choose-a-structure-that-protects-the-contract) while choosing the approach. Name the authoritative state, permitted writers, and invariant at the real caller. Compare another shape only if consequential uncertainty remains; a familiar local change does not need a design exercise.
|
|
25
|
+
Known development case: older canonical cancelled RSVP plus newer legacy Going → existing cancellation → existing status → history/send both denied. Include canonical-only, legacy-only, ordinary Going-to-cancelled and eligible/unauthenticated/other-resource controls as applicable. Query-aware isolated adapters execute actual entrypoints, not an invented status flip. Missing journey execution stays unverified; a test/example does not prove unseen model effectiveness.
|
|
27
26
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
```text
|
|
31
|
-
Goal: one sentence. Done when: original user criteria, grouped for the short plan with a retained criterion-to-check mapping.
|
|
32
|
-
Approach: reuse/extend/repair/create → existing capability and reason.
|
|
33
|
-
Context: relevant history, freshness, known failed approaches (or no match).
|
|
34
|
-
Change: file → what changes (one line each)
|
|
35
|
-
Keep consistent: consumer → why it depends on this (from the search)
|
|
36
|
-
Test: the checks that would show it broken
|
|
37
|
-
Open: only decisions that change the solution (with your recommendation)
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
4. **Explain consequential changes.** Current behavior → proposed change → reason → decision needed. Ask only when an unresolved answer changes the solution; bundle questions with a recommendation. Otherwise state supported assumptions and continue. Record alignment as clear or actually confirmed; unresolved consequential alignment is blocked, not assumed approved.
|
|
41
|
-
5. **Record and move on.** If `run start` was given `scout`, Scout is already recorded: do not record it again, because a second record lands at Build. Otherwise `cyc run record --run ID --summary "<plan>" --assessment <scout.json>` for new implementation runs. The [assessment](../../docs/work-assessments.md) records context lookup/freshness, approach, alignment, and stable consumer IDs/checks, including directly affected behavior. Keep JSON in the run directory. Advisory routes retain ordinary handoffs.
|
|
42
|
-
|
|
43
|
-
## Scale by risk, not by habit
|
|
44
|
-
|
|
45
|
-
- **Normal work:** the pass above. Do not add paperwork or invent alternatives without a real decision to resolve. For visual frontend work, a useful first implementation can resolve the actual composition with meaningful content and assets; source-edit speed is not a reason to settle for a generic scaffold.
|
|
46
|
-
- **High risk** (auth, payments, data migrations, deletes, public interfaces): also run [Challenge](../cyc-challenge/SKILL.md) on the plan before building. It's one focused pass, not a new research phase.
|
|
47
|
-
- **Bugs:** include getting the failure to reproduce in the same batch (run the failing test or request). See the [diagnose branch](../cyc-understand/references/diagnose.md) only if it doesn't reproduce quickly.
|
|
48
|
-
|
|
49
|
-
The detailed skills ([Understand](../cyc-understand/SKILL.md), [Impact](../cyc-impact/SKILL.md), [Design](../cyc-design/SKILL.md)) are reference material for when something is genuinely unclear. Don't read them by default.
|
|
50
|
-
|
|
51
|
-
## Done when
|
|
52
|
-
|
|
53
|
-
The findings name the affected files, consumers supported by inspection, checks to run, and the next stage for the selected route. For implementation, begin a safe, useful test or reversible slice once the plan is ready. For advisory work, pass the supported findings onward without editing the product. If investigation takes longer than expected, identify the unresolved question; surface a real blocker promptly. Never defer a critical permission, data-loss, or interface-contract question on the assumption that verification will catch it.
|
|
54
|
-
|
|
55
|
-
## Anti-patterns
|
|
56
|
-
|
|
57
|
-
| Name | The tell | Fix |
|
|
58
|
-
| --- | --- | --- |
|
|
59
|
-
| Serial tour | One file read per step, narrating each | Batch searches and reads in parallel |
|
|
60
|
-
| Reading for completeness | Understanding code paths the change doesn't touch | Stop when every changed file and consumer is named |
|
|
61
|
-
| Paperwork | Tables, evidence rungs, category checklists | Ten-line plan |
|
|
62
|
-
| Pre-verifying | Measuring or testing hypotheticals before any edit | Build, then let the verify loop measure |
|
|
63
|
-
| Re-reading instructions | Opening unrelated methods at every step | Load needed instructions once; preserve required outcomes |
|
|
27
|
+
High risk (auth, payments, migrations, deletes, public interfaces) adds one focused [Challenge](../cyc-challenge/SKILL.md) before Build. Bugs include reproduction in the same pass; use [diagnosis](../cyc-understand/references/diagnose.md) if it does not reproduce quickly. Do not defer a critical permission/data-loss/interface question to verification.
|
|
64
28
|
|
|
65
29
|
## Handoff
|
|
66
30
|
|
|
67
|
-
|
|
31
|
+
Follow run next: Build for implementation, Challenge for review, Verify for verification, Explore for experience work, Deliver for investigation. Start a useful reversible slice once the bounded plan is ready. A newly discovered consumer changes the plan/context before final checks; a late scope gap uses honest recovery/pending. The detailed [Understand](../cyc-understand/SKILL.md), [Impact](../cyc-impact/SKILL.md) and [Design](../cyc-design/SKILL.md) methods are conditional references, not default reading.
|
|
32
|
+
|
|
33
|
+
Updates follow the [progress/engineering-understanding standard](../../docs/response-standard.md#progress-updates): connect observed behavior, mechanism, consequential choice and evidence in readable prose. File counts, repeated reassurance and agreement alone do not demonstrate understanding. Surface a real blocker and its discriminating next check promptly.
|
|
@@ -5,7 +5,7 @@ description: "Set up CYC in the current project: activate it, find the project's
|
|
|
5
5
|
|
|
6
6
|
# Set up CYC in this project
|
|
7
7
|
|
|
8
|
-
Guide the developer from installation to one useful task. Keep installed files, configured checks, executed checks, and live host activation distinct. Use the existing project conventions and ask only about consequential missing decisions.
|
|
8
|
+
Explain once: CYC finds relevant project knowledge, checks a change and retains consequential decisions for the next chat. Use onboard.experience for first-task guidance and responseChoices for an observed preference; unknown state cannot be called concise or unlimited. Guide the developer from installation to one useful task. Keep installed files, configured checks, executed checks, and live host activation distinct. Use the existing project conventions and ask only about consequential missing decisions.
|
|
9
9
|
|
|
10
10
|
The CYC CLI is [bin/cyc.mjs](../../bin/cyc.mjs), two folders up from this skill. Resolve it to an absolute path and run it with `node`.
|
|
11
11
|
|
|
@@ -16,29 +16,17 @@ The CYC CLI is [bin/cyc.mjs](../../bin/cyc.mjs), two folders up from this skill.
|
|
|
16
16
|
- Only a config exists: the project is configured, but confirm that the host supplies the plugin. Do not reinstall or overwrite a team's existing checks just to repeat onboarding.
|
|
17
17
|
- No config exists: continue with activation or the project installer, according to how the user obtained CYC.
|
|
18
18
|
2. **Activate.** Run `node <cli> activate --dry-run`, show the planned files, then run it without `--dry-run`. This creates `.cyc/config.json` and `.cyc/.gitignore` only. It changes nothing else.
|
|
19
|
-
3. **Find the real checks.**
|
|
20
|
-
|
|
21
|
-
4. **Propose the commands in one round**, each
|
|
22
|
-
|
|
23
|
-
```text
|
|
24
|
-
Proposed verification commands for .cyc/config.json:
|
|
25
|
-
1. test npm test (runs in CI: .github/workflows/ci.yml:31) Recommended: yes
|
|
26
|
-
2. typecheck npx tsc --noEmit (in CI) Recommended: yes
|
|
27
|
-
3. lint npm run lint (in CI, ~40s) Recommended: yes
|
|
28
|
-
4. e2e npm run test:e2e (needs a running server) Recommended: no, keep it in the verify recipe
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Never add a command you haven't seen defined in the project. Never guess. Prefer checks that finish in a few minutes: CYC runs them to verify every change (optional diagnostic baseline checks are off by default). Leave hour-long suites to CI or the verify recipe, and split one giant command into separate ones (unit, integration) so each can be run and judged on its own.
|
|
19
|
+
3. **Find the real checks.** Read `onboard.evidenceSources`, actual CI/project scripts and contributing instructions. Discovery does not endorse commands. Explain each recommended check's detectable behavior/error. Missing checks need a bounded proposal within authorized scope; an always-successful command cannot substitute.
|
|
20
|
+
Use `node <cli> recipe list`; reuse project tools and register successful reusable checks in `docs/context/recipes.json` under the [project-tools contract](../../docs/project-tools.md). Retain concrete coverage, references, prerequisites, effects and outcomes. Mandatory checks stay in `verification.commands`; recipes cannot replace them. Setup grants no publication permission or authority to copy CYC's development recipes into an application.
|
|
21
|
+
4. **Propose the commands in one round**, with each executable/arguments, observed CI or script reference, prerequisite, reason and recommendation. Keep required project checks; separate supplementary service-dependent recipes. Prefer bounded commands and separate independently judged unit/integration checks. Diagnostic baselines are off by default. Never guess a command or its duration.
|
|
32
22
|
When no one can answer (an unattended run, or `/cyc` was invoked with instructions not to wait), do not stop: write only commands the project itself defines and runs (CI or a package script), prove them in step 7, and name them in the final handoff as configured checks. That disclosure is information, not a blocker.
|
|
33
23
|
|
|
34
24
|
Do all of this before `run start`. The controller captures the checks when a run starts and protects `.cyc/config.json` while it runs; an edit then halts the run, and `run start` refuses code playbooks while no checks exist.
|
|
35
25
|
5. **Write the approved commands** into `verification.commands` as `{ "id", "command", "args": [], "timeoutMs" }`. Reuse already authorized team configuration; do not ask for approval again when the session already provides it. Do not change configuration beneath an active run. Split the executable from its arguments (`"command": "npm", "args": ["test"]`). On Windows, Node cannot launch `npm`, `npx`, or other `.cmd` shims directly, so wrap them: `"command": "cmd", "args": ["/c", "npm", "test"]`.
|
|
36
26
|
6. **Respect existing conventions.** Reuse the project ledger through `context.ledgerPath`. If another hook already enforces response formatting, configure `delivery.presentation: "project"`; preserve that hook. CYC still enforces controller completion. Show these choices with the proposed commands.
|
|
37
|
-
7. **Prove the configured commands run.** After
|
|
38
|
-
8. **Check the hooks in the actual host.** `
|
|
39
|
-
|
|
40
|
-
Do not manually invoke a hook script and call it live activation. A missing table alone is not a reliable probe: project-owned presentation and alternative valid visuals change the requirements. Report the observed host/version and remaining limits; local editable trace evidence is not independent certification.
|
|
41
|
-
9. **Connect setup to a first success.** If the user already requested a bounded task, continue that task through the existing orchestrator once prerequisites permit. Otherwise recommend a small task from inspected project evidence and let the user choose it before editing product behavior. Explain the outcome and the checks that would establish it. On delivery, connect one consequential change to its test and point to the existing review. Do not require practice or claim that an explanation proves understanding.
|
|
27
|
+
7. **Prove the configured commands run.** After reviewing side effects/authorization, run `node <cli> onboard --verify`. Explain its [bound diagnostic receipt and limitations](../../docs/onboarding-recovery.md#onboarding). Source-mutating/stale results cannot pass or replace task verification. Disclose existing failures; preserve unrelated code and checks.
|
|
28
|
+
8. **Check the hooks in the actual host.** Explain `guidance` and the first unresolved `host` step using the [setup states and trust procedure](../../docs/onboarding-recovery.md#onboarding). `onboard` exits nonzero until ready; `canStartTask: true` permits authorized work while its own Stop is pending. Report actual host/version, current prompt and separate post-turn completion observations. Missing state needs supported trust/reload controls; never simulate activation, edit trust/state, read an old token or invent a Cursor tag. Project-owned presentation changes rejection probes: a missing table alone is inconclusive. Preserve stale/rejected/blocked observations and disclose unavailable qualification.
|
|
29
|
+
9. **Connect setup to a first success.** Continue the authorized bounded task once prerequisites permit. Otherwise recommend one from project evidence for the user to choose before product edits. Explain its outcome/checks and connect delivery to the existing review. Explanation does not prove user understanding.
|
|
42
30
|
|
|
43
31
|
## Done when
|
|
44
32
|
|
|
@@ -5,83 +5,32 @@ description: "Prove the requested change works and nothing it touches broke, usi
|
|
|
5
5
|
|
|
6
6
|
# Verify the promised outcome
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
For user updates, follow the shared [progress standard](../../docs/response-standard.md#progress-updates): explain which behavior the checks establish and what remains unverified, rather than reporting only pass counts. When a check fails, explain what it revealed and how that affects the next decision.
|
|
11
|
-
|
|
12
|
-
Help the engineer interpret the evidence: connect an important check to the path or consumer it exercises, the defect or rejected case it could detect, and the limit of that conclusion. Explain separately why the implementation fits the intended behavior; semantic review is a judgment, not an executed check. Follow the [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work).
|
|
13
|
-
|
|
14
|
-
For implementation, verify the changed behavior with executable checks. For advisory Review or Handoff, verify the claims and cited evidence without manufacturing a code change or failing test. An accurate report of a defect can satisfy a review criterion; it cannot satisfy a criterion that the product works. Follow the [handoff contract](../../docs/skill-contract.md) for evidence labels.
|
|
15
|
-
|
|
16
|
-
Apply the project's applicable `code-standards.md` and the relevant [code standards](../../docs/engineering/code-standards.md) to the actual diff and callers. Check information-bearing comments, justified assertions/suppressions, failure outcomes and useful structure; preserve legitimate exceptions. Record tool results separately from this semantic judgment. Reading the standards, a comment search or an unchecked checklist does not prove compliance.
|
|
8
|
+
Establish behavior with checks actually run against current files. Follow the [handoff contract](../../docs/skill-contract.md), [code standards](../../docs/engineering/code-standards.md) and [progress standard](../../docs/response-standard.md#progress-updates). An advisory review may accurately report a defect; that does not satisfy a criterion that the product works. Label semantic judgment separately from executed results.
|
|
17
9
|
|
|
18
10
|
## The core loop
|
|
19
11
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
6. a human-in-the-loop step, as a last resort, with exact instructions and the expected observation
|
|
30
|
-
4. **Hit the edges the change created.** Old saved data, repeat actions (clicking twice), unknown IDs, empty state, and the error path. For a guard, show a rejected case, not only an allowed one. For operations that recreate records, apply the [preservation contract](../../docs/engineering/failure-handling.md#preserve-records-when-an-operation-recreates-them): inspect stored fields and relevant access metadata beyond the UI projection, through success and failure recovery. Check that the fixture would detect losing them.
|
|
31
|
-
|
|
32
|
-
Tie each original user criterion to a decisive check/scenario and the observed result, even when several share a suite command. In red proof, distinguish an assertion of the original defect from a missing newly introduced API or module-load failure. The latter may show a new dependency is absent; it does not establish the intended old-behavior failure. Keep useful genuine red assertions and state their limits.
|
|
33
|
-
5. **Run configured checks on the final candidate.** For step-by-step execution use `run verify --run <ID>`; the fast implementation route's `run finish` executes these checks itself. Do not run both on an unchanged candidate merely to duplicate a receipt. Advisory routes without configured checks use clearly labeled inspected evidence. Focused checks give fast feedback; final checks cover the affected behavior.
|
|
34
|
-
With `evidenceVersion: 1`, fill `criterionChecks` for every original criterion/clause. Use a named scenario and actual observation, configured command ID, `receipt: "current-verification"`, `result: "passed"`, and `origin: "agent-reported"`. Missing or unavailable required checks stay unverified and cannot pass. For non-exempt red proof, run `prove-red` and fill `proofReview` against its failure IDs: `behavioral`, `new-interface`, `setup`, or `unclassified`, with a reason and an existing observable boundary for behavioral cases. A bug-fix proof needs a decisive behavioral case; a feature may demonstrate an absent new interface. Error type alone cannot decide the category. Review receipts must come from capture before the review and record afterward; later edits stale the whole-source capture. See the [evidence record examples](../../docs/work-assessments.md#versioned-evidence-records).
|
|
35
|
-
6. **Fill the matrix with results.** Each row: passed (with the command and what you saw), failed (with output), or unverified (with why, such as no browser access). Model review of code goes in its own labeled row and never turns a row green.
|
|
36
|
-
7. **Record semantic review separately.** Trace the important state, shared invariant, consumers and relevant failure paths in the actual diff; identify where a likely next change belongs. Review intent, conventions and the [engineering principles](../../docs/principles.md), using the [finding adjudication guidance](../../docs/code-quality.md#review-findings-before-turning-them-into-edits) for consequential diffs. For changed business rules/transitions, inspect the owner and callers using the [domain examples](../../docs/engineering/domain-design.md); for rejection, I/O or partial effects, inspect failure identity, committed/unknown state and retry safety using the [failure examples](../../docs/engineering/failure-handling.md). Apply their stated contracts and exceptions rather than requiring their exact code shape. Show the legitimate trigger or concrete maintenance consequence before requiring a repair; check whether a proposed simplification removes policy duplication or merely moves it. Resolve or dismiss findings with evidence, and keep unresolved required findings open and blocking. New implementation runs require the [Verify assessment](../../docs/work-assessments.md#verify-executable-evidence-plus-semantic-judgment), with a passing check for every Scout consumer and newly discovered consumer. Label self-review; extra reviewers depend on risk. If final context/ledger edits change source, rerun checks before recording the assessment.
|
|
12
|
+
1. **Select relevant checks.** Inspect recipe list --run ID and each applicable prerequisite/effect/expected outcome. Execute authorized supplementary recipes; configuredCommandIds are already owned by final verification. Existing receipts are diagnostic history, not fresh external evidence. Use the project's preview/CSS/build setup before adding dependencies. Keep named state/action/outcome checks in the [existing recipe mechanism](references/recipe.md), not another mandatory report. Missing prerequisites or browser capability produce one precise limited result.
|
|
13
|
+
2. **Map decisive scenarios.** Retain every original criterion/material clause and affected consumer. Use one canonical scenarioEvidence observation per criterion/clause, mapping consumers to Scout IDs; finish derives exact legacy views. Record actual scenario, configured check, current-verification receipt, passed result, agent-reported origin and evidence. Missing/unavailable execution stays unverified; prose and suite counts cannot become machine-observed semantic coverage.
|
|
14
|
+
3. **Exercise authority together.** A new protected consumer requires the existing authoritative state-changing entrypoint → existing status → new protected read/write operations in one named journey. Use query-aware isolated storage/session adapters and actual handler behavior, including conflicting canonical/legacy representations. Cover canonical-only, legacy-only, ordinary transition and applicable eligible/unauthenticated/other-resource controls. Reuse a shared authoritative resolver or explicit reconciliation. Declared Scout journey names must match the scenario record; do not merely flip an invented status flag.
|
|
15
|
+
4. **Exercise asynchronous identity.** Validate actor/resource/operation context before acknowledging sends or merging reads. Test mismatched send identity while props/caches stay unchanged, mismatched reads/resources, older operations/contexts and delayed empty polling after a confirmed send. Invalidate stale context without falsely acknowledging the draft. Keep loaded-empty distinct from not loaded. Authorization remains server-owned: client rejection cannot reverse a completed write; preventing switched-session writes requires a separately tested server-verified expected-session precondition.
|
|
16
|
+
5. **Run the actual journey.** Prefer an existing behavioral test, then a focused boundary test, CLI/API trial, or supported browser journey. Check reload/persistence, error/retry and relevant negative cases. For record recreation inspect stored fields/references/access metadata beyond the UI projection using the [preservation contract](../../docs/engineering/failure-handling.md#preserve-records-when-an-operation-recreates-them). Known CYC development fixtures demonstrate these contracts; they do not prove a model finds unseen defects.
|
|
17
|
+
6. **Keep browser auditing external.** Reuse the host's actual documented API and current handles; do not guess methods/variables. Declare proportional desktop/phone and applicable send/reload, empty/error, membership-loss, overflow, keyboard/history/focus checks. Run supplementary accessibility scanning from a separate harness/context with dependencies/artifacts in its designated scope. Never string-replace application layouts or rewrite CSS/build configuration for instrumentation. Batch independent observations only after known state and when host policy permits. Respect interruption and report incomplete coverage. For new visual design also apply the [generic-tells](../cyc-design/frontend-design/references/generic-tells.md#score-sheet) and [experience](../cyc-design/frontend-design/references/experience-review.md) checks; narrow repairs preserve identity.
|
|
18
|
+
7. **Finish context, proof and verification.** Finish first validates planned canonical records/index against actual target source, or returns needs-context with the remaining authoring input. Required feature learning cannot be none or only a general handoff. Finalize context before final checks; later edits require fresh verification. Structural validation cannot certify the explanation’s semantic truth. Use run finish --run ID --file FINISH.json --wait-ms 30000 as the normal entrypoint. Frozen proofCommands can target decisive tests on originals; --tests only chooses swapped files. Bug-fix/feature tests go red on originals; refactor characterization stays green. Keep original-only, original-plus-new-tests and candidate roles distinct. A broad original result is required to excuse a pre-existing broad failure; finish measures it when needed and can retain compatible focused treatment. Missing/corrupt originals or source conflicts halt safely; never manually reset source or locks. See [run-start originals](../../docs/runtime.md#run-start-originals).
|
|
19
|
+
Finish returns needs-proof-review when judgment is required, with receipt/failure IDs, errors, unknown boundaries and the exact bound continuation file. Supply categories/reasons there and call its command. Missing new interfaces/module-load/setup failures are not existing behavioral defects. Bug fixes need a decisive behavioral boundary; feature proof may establish a new interface. Inadequate/stale/foreign/placeholder judgments cannot complete. Non-testable exemptions and genuine unavailable-proof limits must be honest. Successful steps resume only while compatible. Final checks stay broad; deterministic receipt reuse needs explicit suitability and matching source/tests/config/dependency/toolchain/environment inputs. External/freshness-dependent checks remain nonreusable.
|
|
20
|
+
8. **Review the source and interpret results.** Check intent, consumers, conventions and the [principles](../../docs/principles.md); trace domain ownership and partial-effect/recovery boundaries. Prioritize demonstrated critical state/identity transitions before cosmetics, retaining history continuity and keyboard/return focus. Resolve or justify dismissing findings with evidence; open findings block. Capture before review and use the generated record template with actual evidence/identity or null. Bounded scoped review can survive an unrelated edit only with unchanged reviewed files, criteria and dependency/contract context. Unknown impact requires broader review; never relabel stale coverage as fresh. Final context/ledger/source edits invalidate affected evidence.
|
|
37
21
|
|
|
38
22
|
## Done when
|
|
39
23
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
**Suspect the observation before the system.** When a result surprises you, first check that the check itself measures the right thing (right port, right build, right data).
|
|
24
|
+
Each original criterion and consumer has current evidence and honest limits. A proof shows the named failures actually observed; it never establishes every new test failed or assigns a repaired-defect count. Passing a stage, model review, source fingerprint or self-authored score does not certify product correctness.
|
|
43
25
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
For a TAP (`node --test`, `tap`), mocha, or jest suite, "exactly" means all of these, also for output longer than the 32,000 characters kept, provided a test in it already failed at the run start:
|
|
47
|
-
- no test fails that did not fail then;
|
|
48
|
-
- every old failure has the same error, and its stack does not run through source you changed;
|
|
49
|
-
- no new non-test line appears. A failed verification lists `failedAtRunStart`: decide for each check whether it is unrelated (accept it) or caused by your change (fix it). Do not retry unchanged. Name it in the reply as a pre-existing failure. New regressions can hide inside the same command. Any of these still leaves verification unverified, with the cause in `acceptedFailuresThatChanged`:
|
|
50
|
-
- a new or lost line;
|
|
51
|
-
- a different exit code or a hang;
|
|
52
|
-
- truncated output;
|
|
53
|
-
- a check that prints nothing. Report a blocked handoff when the failure cannot be repaired within scope. Do not change configuration or drop tests mid-run to obtain success.
|
|
26
|
+
Unrelated baseline failures need compatible measured original evidence and an explicit reason. Verification rejects new/changed failures, changed-source stacks, unmatched non-test output, changed exits or truncated/incomparable evidence. Report accepted failures; do not weaken criteria or config to fit a budget. New regressions inside an already failing suite remain blocking. A silent process, timeout, cancellation and crash are distinct outcomes; wait on the returned handle for 30–60 seconds rather than discovering status through ephemeral locks.
|
|
54
27
|
|
|
55
28
|
## Anti-patterns
|
|
56
29
|
|
|
57
|
-
|
|
58
|
-
| --- | --- | --- |
|
|
59
|
-
| Green-by-reading | "The logic looks correct" with no command run | Run something that could fail |
|
|
60
|
-
| Tautological test | The expected value is computed the same way the code computes it | Assert a literal known-good value |
|
|
61
|
-
| Hollow test | It would still pass if every imported function returned `undefined` | Assert on real output, not on mocks or fixtures |
|
|
62
|
-
| Wrong surface | Checked the API when the user asked about the page | Verify where the user sees the behavior |
|
|
63
|
-
| Unit-only for a journey | Component test passes; nobody reloaded the page | Add the journey check from step 3 |
|
|
64
|
-
| Retry until green | Rerunning a flaky test until it passes | Diagnose the flake or mark unverified |
|
|
65
|
-
| Stale evidence | Result is from before the last edit | Rerun after the final change |
|
|
30
|
+
Reading alone is not verification; tautological/mirrored assertions and mocks that pass with broken entrypoints prove little. Exercise the user's surface and reload path. Do not retry flakes until green, reuse stale evidence, infer unavailable browser success, weaken criteria, skip failures or change protected configuration. An agent review is a judgment, not a command result.
|
|
66
31
|
|
|
67
32
|
## Routing failures
|
|
68
33
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
In fast playbooks (scout → build → verify → deliver), Frame, Impact, and Design map to Scout. Before an authorized implementation repair, use `run retry --run <ID> --stage build --reason "<finding>"`, record the repaired artifacts, and verify again. Return to Scout when a missed consumer or invalid approach changes the plan. Advisory routes report the finding unless repairs are authorized. Changes after a passing Verify handoff require returning to Verify with fresh checks and semantic review before delivery; implementation repairs return through Build first.
|
|
72
|
-
|
|
73
|
-
| What you saw | Send it to |
|
|
74
|
-
| --- | --- |
|
|
75
|
-
| Right design, wrong code | [Build](../cyc-build/SKILL.md) with the failing command |
|
|
76
|
-
| A consumer nobody mapped broke | [Impact](../cyc-impact/SKILL.md), then affected work |
|
|
77
|
-
| The approach cannot meet a criterion | [Design](../cyc-design/SKILL.md) with the disproved assumption |
|
|
78
|
-
| The criterion measures the wrong thing | [Frame](../cyc-frame/SKILL.md), keeping the failed result on record |
|
|
79
|
-
| Missing access or service | Blocked, naming the smallest thing the user can provide |
|
|
80
|
-
|
|
81
|
-
Never edit thresholds, skip tests, or loosen criteria to pass. When a recipe check fails, fix the cause and rerun the whole applicable set: this is the loop, and it runs without the user pointing anything out.
|
|
82
|
-
|
|
83
|
-
**Retain missing checks without changing the contract.** Save proposed checks in `.cyc/runs/<runId>/proposed-checks.json` when durable recipe edits are outside scope. Never edit `.cyc/config.json` during an active run. Promote authorized proposals in a subsequent scoped change and verify that change; edits after completion are not covered by the completed run's evidence. Do not ask for permission again when the user already authorized that follow-up.
|
|
84
|
-
|
|
85
|
-
## Example
|
|
34
|
+
Use run recover --run ID after failure/interruption; keep failed receipts diagnostic and describe the specific observation, supported cause and next justified action. Missing executables and timeouts do not themselves diagnose an application defect. Preserve locks/backups and budgets; do not automatically message others or start a replacement budget.
|
|
86
35
|
|
|
87
|
-
|
|
36
|
+
An authorized implementation repair returns through Build with run retry --run ID --stage build --reason, then re-verifies relevant consumers. A missed consumer or disproved approach returns through Scout/Impact/Design as appropriate. Advisory work reports findings unless repairs are authorized. External prerequisites get an honest blocked handoff with the smallest needed user action. Changes after Verify require renewed relevant checks/review. Save proposed checks in existing run-local notes when durable recipe/config edits are outside scope; never change the active run's verification contract to pass. Existing user authorization persists.
|
|
@@ -47,6 +47,8 @@ When applicable checks need discovering, record these steps in run-local notes f
|
|
|
47
47
|
|
|
48
48
|
## Growing it
|
|
49
49
|
|
|
50
|
+
For protected state, one named scenario invokes the existing writer/status and new protected history/send with conflicting canonical/legacy data, followed by eligible and denied controls. For async UI, check matching read/send responses, mismatched actor/resource with unchanged visible identity, prior operation/context, and an empty poll resolving after a confirmed send. Client context rejection and server authorization/expected-session prevention are separate observations. Store these in existing scenario/consumer fields; unavailable journeys remain unverified. `test/quality-journeys.test.mjs` in the CYC development checkout demonstrates these known contracts, not the frozen application or a new model benchmark.
|
|
51
|
+
|
|
50
52
|
- **Whenever the user checks something by hand and tells the agent what to fix, add that check to the recipe.** That correction was a missing verification step.
|
|
51
53
|
- **Propose useful scriptable checks as controller commands** in `.cyc/config.json` (`verification.commands`). During an active run, retain the proposal in `.cyc/runs/<runId>/proposed-checks.json`; the controller protects configuration mid-run. Apply authorized proposals as a subsequent scoped change with its own verification. Checks that need judgment or a browser tool stay as recipe steps.
|
|
52
54
|
- Keep each check tied to when it applies (the paths or change type), so a backend fix doesn't trigger a layout trace.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cyc-stack",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"private": false,
|
|
6
6
|
"type": "module",
|
|
@@ -31,6 +31,8 @@
|
|
|
31
31
|
"scripts/install.mjs",
|
|
32
32
|
"scripts/onboarding.mjs",
|
|
33
33
|
"scripts/packet.mjs",
|
|
34
|
+
"scripts/execution.mjs",
|
|
35
|
+
"scripts/browser-audit.mjs",
|
|
34
36
|
"scripts/project-tools.mjs",
|
|
35
37
|
"scripts/recovery.mjs",
|
|
36
38
|
"scripts/response-gate.mjs",
|
|
@@ -38,6 +40,11 @@
|
|
|
38
40
|
"scripts/response-mode.mjs",
|
|
39
41
|
"scripts/run-gate.mjs",
|
|
40
42
|
"scripts/runtime.mjs",
|
|
43
|
+
"scripts/task-context.mjs",
|
|
44
|
+
"scripts/delegation.mjs",
|
|
45
|
+
"scripts/codex-host.mjs",
|
|
46
|
+
"scripts/swarm.mjs",
|
|
47
|
+
"scripts/run-worker.mjs",
|
|
41
48
|
"scripts/source-hash-worker.mjs",
|
|
42
49
|
"scripts/source-snapshot.mjs",
|
|
43
50
|
"scripts/test-output.mjs",
|
|
@@ -48,6 +55,7 @@
|
|
|
48
55
|
"docs/code-quality.md",
|
|
49
56
|
"docs/README.md",
|
|
50
57
|
"docs/context.md",
|
|
58
|
+
"docs/task-context.md",
|
|
51
59
|
"docs/cyc-method-map.md",
|
|
52
60
|
"docs/cyc-workflow.md",
|
|
53
61
|
"docs/engineering",
|
package/plugin.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
3
3
|
"name": "cycstack",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.9.0",
|
|
5
5
|
"description": "Portable AI engineering workflows with shared project context and verifiable changes.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "CYC Stack contributors"
|
package/rules/cyc-delivery.mdc
CHANGED
|
@@ -1,33 +1,33 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: CYC delivery gate protocol for Cursor
|
|
3
|
-
alwaysApply: true
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# CYC delivery gate (Cursor)
|
|
7
|
-
|
|
8
|
-
This project uses CYC. A stop hook checks your final response before the turn ends. Cursor hooks cannot pass you per-request instructions, so follow this protocol on every turn.
|
|
9
|
-
|
|
10
|
-
**Existing project formatting:** Read `.cyc/config.json` first. With `delivery.presentation: "project"`, follow the existing project formatting rules instead of the length, visual and review rules below. Still choose a session tag and write `.cyc/runtime/cursor-<tag>.review.json` with `{ "token": "cursor", "response": "<exact final text>", "status": "ready" }` (or `"blocked"` with a reply starting `Blocked:`). This identity packet associates your controller runs with this conversation; it is not a CYC presentation review.
|
|
11
|
-
|
|
12
|
-
**Session tag:** at the start of this conversation, pick a random tag of 6 to 12 lowercase letters and digits (for example `k3v9qd`) and reuse it for the whole conversation. It keeps parallel chats in this folder independent. Pass it as `--session <tag>` whenever you run `cyc run start`.
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
1. Draft your final response first. It must include one visual that adds information (a table, a labeled arrow flow like `A → B → C`, a Mermaid diagram, or an image with alt text).
|
|
16
|
-
2. Length: at most 1,000 characters by default, counting Markdown. If `.cyc/config.json` sets `delivery.defaultCharacterLimitEnabled: false`, new conversations start without the cap; explicit user toggles override that default. If the user sent `limit off` as a standalone message in this conversation, there is no cap until they send `limit on`. A standalone `expand` lifts the cap for one reply.
|
|
17
|
-
3. Before sending, write `.cyc/runtime/cursor-<tag>.review.json`:
|
|
18
|
-
|
|
19
|
-
```json
|
|
20
|
-
{
|
|
21
|
-
"token": "cursor",
|
|
22
|
-
"response": "<your exact final response>",
|
|
23
|
-
"status": "ready",
|
|
24
|
-
"checks": [{ "criterion": "<what the user asked>", "result": "passed", "evidence": "<command run, file read, or observation>" }],
|
|
25
|
-
"humanReview": { "answersRequest": true, "understandable": true, "visualAddsInformation": true, "limitationsDisclosed": true },
|
|
26
|
-
"artifacts": [{ "path": "<changed file>", "sha256": "<current sha256>" }]
|
|
27
|
-
}
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
4. Send exactly the text you recorded. Any edit after writing the file fails the check.
|
|
31
|
-
5. If you can't finish, use `"status": "blocked"`, a `"blocker"` string that appears verbatim in the response, and start the response with `Blocked:` or `Not ready:`.
|
|
32
|
-
|
|
33
|
-
If the hook replies with `CYC_GATE_CONTINUE`, fix the listed issues in the work (not only the wording), rewrite the review file, and respond again. Never edit files under `.cyc/runtime/` other than the review file, and never edit the hook to pass. Full standard: `docs/response-standard.md` in the CYC engine.
|
|
1
|
+
---
|
|
2
|
+
description: CYC delivery gate protocol for Cursor
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CYC delivery gate (Cursor)
|
|
7
|
+
|
|
8
|
+
This project uses CYC. A stop hook checks your final response before the turn ends. Cursor hooks cannot pass you per-request instructions, so follow this protocol on every turn.
|
|
9
|
+
|
|
10
|
+
**Existing project formatting:** Read `.cyc/config.json` first. With `delivery.presentation: "project"`, follow the existing project formatting rules instead of the length, visual and review rules below. Still choose a session tag and write `.cyc/runtime/cursor-<tag>.review.json` with `{ "token": "cursor", "response": "<exact final text>", "status": "ready" }` (or `"blocked"` with a reply starting `Blocked:`). This identity packet associates your controller runs with this conversation; it is not a CYC presentation review.
|
|
11
|
+
|
|
12
|
+
**Session tag:** at the start of this conversation, pick a random tag of 6 to 12 lowercase letters and digits (for example `k3v9qd`) and reuse it for the whole conversation. It keeps parallel chats in this folder independent. Pass it as `--session <tag>` whenever you run `cyc run start`.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
1. Draft your final response first. It must include one visual that adds information (a table, a labeled arrow flow like `A → B → C`, a Mermaid diagram, or an image with alt text).
|
|
16
|
+
2. Length: at most 1,000 characters by default, counting Markdown. If `.cyc/config.json` sets `delivery.defaultCharacterLimitEnabled: false`, new conversations start without the cap; explicit user toggles override that default. If the user sent `limit off` as a standalone message in this conversation, there is no cap until they send `limit on`. A standalone `expand` lifts the cap for one reply.
|
|
17
|
+
3. Before sending, write `.cyc/runtime/cursor-<tag>.review.json`:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"token": "cursor",
|
|
22
|
+
"response": "<your exact final response>",
|
|
23
|
+
"status": "ready",
|
|
24
|
+
"checks": [{ "criterion": "<what the user asked>", "result": "passed", "evidence": "<command run, file read, or observation>" }],
|
|
25
|
+
"humanReview": { "answersRequest": true, "understandable": true, "visualAddsInformation": true, "limitationsDisclosed": true },
|
|
26
|
+
"artifacts": [{ "path": "<changed file>", "sha256": "<current sha256>" }]
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
4. Send exactly the text you recorded. Any edit after writing the file fails the check.
|
|
31
|
+
5. If you can't finish, use `"status": "blocked"`, a `"blocker"` string that appears verbatim in the response, and start the response with `Blocked:` or `Not ready:`.
|
|
32
|
+
|
|
33
|
+
If the hook replies with `CYC_GATE_CONTINUE`, fix the listed issues in the work (not only the wording), rewrite the review file, and respond again. Never edit files under `.cyc/runtime/` other than the review file, and never edit the hook to pass. Full standard: `docs/response-standard.md` in the CYC engine.
|