cyc-stack 0.7.1 → 0.8.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/README.md +1 -1
- package/bin/cyc.mjs +35 -20
- package/docs/context.md +10 -26
- package/docs/project-tools.md +14 -10
- package/docs/response-standard.md +8 -32
- package/docs/runtime.md +58 -174
- package/docs/work-assessments.md +25 -92
- package/methods/cyc-build/SKILL.md +1 -1
- package/methods/cyc-challenge/SKILL.md +4 -0
- package/methods/cyc-context/SKILL.md +18 -53
- package/methods/cyc-context/references/evidence.md +1 -1
- package/methods/cyc-context/references/templates.md +4 -11
- package/methods/cyc-deliver/SKILL.md +2 -2
- package/methods/cyc-remember/SKILL.md +1 -1
- package/methods/cyc-scout/SKILL.md +17 -51
- package/methods/cyc-verify/SKILL.md +15 -66
- package/methods/cyc-verify/references/recipe.md +2 -0
- package/package.json +4 -1
- package/plugin.json +1 -1
- package/rules/cyc-delivery.mdc +33 -33
- package/scripts/browser-audit.mjs +53 -0
- package/scripts/context-review.mjs +202 -29
- package/scripts/execution.mjs +51 -0
- package/scripts/packet.mjs +21 -6
- package/scripts/project-tools.mjs +18 -16
- package/scripts/run-worker.mjs +4 -0
- package/scripts/runtime.mjs +482 -65
- package/scripts/work-review.mjs +32 -10
- package/skills/cyc/SKILL.md +24 -71
|
@@ -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. 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,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.8.3",
|
|
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,7 @@
|
|
|
38
40
|
"scripts/response-mode.mjs",
|
|
39
41
|
"scripts/run-gate.mjs",
|
|
40
42
|
"scripts/runtime.mjs",
|
|
43
|
+
"scripts/run-worker.mjs",
|
|
41
44
|
"scripts/source-hash-worker.mjs",
|
|
42
45
|
"scripts/source-snapshot.mjs",
|
|
43
46
|
"scripts/test-output.mjs",
|
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.8.3",
|
|
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.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
3
|
+
import { artifactFiles } from './execution.mjs';
|
|
4
|
+
|
|
5
|
+
export function validateBrowserPlan(plan) {
|
|
6
|
+
if (!plan || !Array.isArray(plan.prerequisiteFiles) || !Array.isArray(plan.viewports) || !plan.viewports.length || !Array.isArray(plan.journeys) || !plan.journeys.length) throw new Error('Browser recipe needs prerequisiteFiles, viewports and named state/action/outcome journeys.');
|
|
7
|
+
for (const v of plan.viewports) if (!v.name || !Number.isInteger(v.width) || !Number.isInteger(v.height) || v.width <= 0 || v.height <= 0) throw new Error('Browser viewport needs name and positive width/height.');
|
|
8
|
+
if (new Set(plan.journeys.map(j => j.id)).size !== plan.journeys.length) throw new Error('Browser journeys need unique ids.');
|
|
9
|
+
for (const j of plan.journeys) if (!j.id || !j.state || !Array.isArray(j.actions) || !Array.isArray(j.outcomes) || !j.outcomes.length) throw new Error('Browser journey needs id, initial state, actions and named outcomes.');
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
// Host integration supplies adapters bound to its actual supported API/handles. The runner
|
|
13
|
+
// never guesses a browser API, changes app layouts, installs dependencies or rewrites CSS.
|
|
14
|
+
export async function runBrowserAudit(root, plan, { driver, scanner, signal } = {}) {
|
|
15
|
+
validateBrowserPlan(plan);
|
|
16
|
+
const missing = plan.prerequisiteFiles.filter(path => !existsSync(resolve(root, path)));
|
|
17
|
+
if (missing.length) return { ok: false, status: 'limited', missing, instruction: 'Inspect the existing preview/CSS/build prerequisites before starting a browser. No application edits were made.' };
|
|
18
|
+
const before = artifactFiles(root, plan.prerequisiteFiles);
|
|
19
|
+
if (!driver || !['open', 'act', 'observe', 'close'].every(name => typeof driver[name] === 'function') || typeof scanner !== 'function') return { ok: false, status: 'limited', missing: ['supported host browser driver/handles and separate scanner harness'], instruction: 'Bind the actual supported browser API and use an external scanner context. Do not instrument the application layout.' };
|
|
20
|
+
const observations = [], scans = [], handles = []; let failure = null;
|
|
21
|
+
const interrupted = () => signal?.aborted;
|
|
22
|
+
try {
|
|
23
|
+
for (const viewport of plan.viewports) {
|
|
24
|
+
if (interrupted()) break;
|
|
25
|
+
for (const journey of plan.journeys) {
|
|
26
|
+
if (interrupted()) break;
|
|
27
|
+
const handle = await driver.open({ viewport, state: journey.state, purpose: 'journey' }); handles.push(handle);
|
|
28
|
+
for (const action of journey.actions) { if (interrupted()) break; await driver.act(handle, action); }
|
|
29
|
+
if (interrupted()) break;
|
|
30
|
+
const observe = async outcome => {
|
|
31
|
+
const observation = await driver.observe(handle, outcome);
|
|
32
|
+
if (typeof observation?.passed !== 'boolean' || typeof observation.evidence !== 'string') throw new Error('Browser observation needs an actual passed/failed result and evidence.');
|
|
33
|
+
return { journey: journey.id, viewport: viewport.name, outcome, ...observation, origin: 'adapter-observed' };
|
|
34
|
+
};
|
|
35
|
+
// Independent observations only, after the actions established the current state.
|
|
36
|
+
if (driver.allowIndependentObservations === true) observations.push(...await Promise.all(journey.outcomes.map(observe)));
|
|
37
|
+
else for (const outcome of journey.outcomes) observations.push(await observe(outcome));
|
|
38
|
+
}
|
|
39
|
+
if (interrupted()) break;
|
|
40
|
+
const handle = await driver.open({ viewport, state: plan.scanState ?? plan.journeys[0].state, purpose: 'external-accessibility-scan' }); handles.push(handle);
|
|
41
|
+
const scan = await scanner(handle);
|
|
42
|
+
if (!Array.isArray(scan?.violations)) throw new Error('External scanner did not supply violations.');
|
|
43
|
+
scans.push({ viewport: viewport.name, violations: scan.violations, origin: 'scanner-observed' });
|
|
44
|
+
}
|
|
45
|
+
} catch (error) {
|
|
46
|
+
failure = error.message;
|
|
47
|
+
} finally { for (const handle of handles.reverse()) { try { await driver.close(handle); } catch (error) { failure ??= error.message; } } }
|
|
48
|
+
let unchanged = false;
|
|
49
|
+
try { unchanged = before.every(file => artifactFiles(root, [file.path])[0].sha256 === file.sha256); } catch { /* removed/replaced prerequisite is a failed preservation check */ }
|
|
50
|
+
const complete = observations.length === plan.viewports.length * plan.journeys.reduce((n, j) => n + j.outcomes.length, 0) && scans.length === plan.viewports.length;
|
|
51
|
+
const ok = !failure && !interrupted() && unchanged && complete && observations.every(o => o.passed) && scans.every(s => s.violations.length === 0);
|
|
52
|
+
return { ok, status: interrupted() ? 'interrupted' : ok ? 'passed' : 'failed', ...(failure ? { error: failure } : {}), applicationPrerequisitesUnchanged: unchanged, observations, scans, limits: 'Only declared journeys and scanner rules were exercised; this does not certify complete accessibility or host activation.' };
|
|
53
|
+
}
|