cyc-stack 0.7.0 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,67 +1,33 @@
1
1
  ---
2
2
  name: cyc-scout
3
- description: "Get from request to a concrete plan in one or two minutes: one parallel batch of searches and reads, then a short plan naming the files to change, the consumers to keep consistent, and the checks to run. Use at the start of any feature, bug fix, refactor, or verification task before editing code."
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
- For a new website, composed interface or visual redesign, use the [frontend design method](../cyc-design/frontend-design/SKILL.md) before choosing structure or acceptance criteria: write `design/decisions.md` (archetype, typeface pair, palette values, signature element, rejection condition) and, for several sites, the set-divergence table. A palette, image presence and readability cannot be the entire visual criterion. Keep this within the user's criterion count; a narrow repair preserves the existing direction.
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
- Scouting establishes the affected behavior and the next justified action. For an implementation route, aim for a short plan and a useful first edit; for Investigation, Review, or Verify, establish the explanation or checks without assuming permission to change the product. Expand investigation for consequential uncertainty; verification cannot justify skipping relevant project history or a misunderstood goal.
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
- For user updates, follow the shared [progress standard](../../docs/response-standard.md#progress-updates): explain the observed behavior and the likely or confirmed mechanism in short, readable prose, then the next useful change or unresolved question. File counts alone do not explain a discovery.
12
+ ## One focused pass
13
13
 
14
- Build the engineer's picture of the affected system: connect the relevant input, state, and readers; explain how checked project history informs the approach and which trade-off matters. Follow the [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work). Agreement on scope is not evidence of comprehension; ask only for a consequential missing decision.
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
- ## The pass
21
+ ## Risk and decisive journeys
17
22
 
18
- After locating the affected paths, run `node <cli> investigate --path <paths>` (or `--run <ID>` with a known scope). Read the returned records and recipe definitions. Run applicable investigation recipes when their prerequisites hold and effects are already authorized; explain unavailable checks. Reuse equivalent current evidence already returned by discovery rather than rerunning solely to create a receipt. Do this without a separate user request, and reuse the result until paths or evidence change. Missing recipes mean ordinary focused discovery, not a new documentation requirement. See [project tools](../../docs/project-tools.md).
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
- 1. **One parallel batch, not a file-by-file tour.** In a single round of tool calls, run together:
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
- 3. **Write the plan in about ten lines:**
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
- Pass the findings to the stage returned by `run next`: Build for implementation, Challenge for review, Verify for verification, Explore for experience work, or Deliver for investigation. Advisory Scout establishes an evidence-backed explanation or review scope, not permission to edit. If later work finds a consumer the plan missed, update the plan and relevant retained context before verification.
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
- For a new web interface or visual redesign, score the finished page with the [generic-tells sheet](../cyc-design/frontend-design/references/generic-tells.md#score-sheet) at desktop and phone width, then run the [experience review](../cyc-design/frontend-design/references/experience-review.md) against the decision sheet's rejection condition. A theme description, image presence and no clipping cannot establish design quality. If the criterion admits any default page, restore the original ambition before judging; never weaken it to fit the output. Keep a material visual miss unmet despite passing behavior checks. Inspect the main action and access/recovery states separately. Narrow repairs need only applicable checks.
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
- 0. **Use applicable recipes automatically.** Run `node <cli> recipe list --run <ID>` or `--path <affected paths>`. Read selected expected outcomes, prerequisites/effects and any relevant manual steps in `docs/context/verify-recipe.md`. Execute applicable authorized supplementary checks with `recipe run --recipe <ID>`; explain unavailable prerequisites or scope boundaries. Entries with `configuredCommandIds` are already owned by final configured verification: defer those to step 5 and cite that actual result, avoiding duplicate final execution. Old recipe receipts are diagnostic history. When nothing matches, discover the needed check through [references/recipe.md](references/recipe.md). Retain authorized reusable steps before final verification; document/CLI work does not require a browser recipe.
21
- 1. **Build the check matrix first.** One row per acceptance criterion and one row per consumer named in the plan (or the [impact map](../cyc-impact/SKILL.md) in the detailed chain). Each row names the check that would show it *red* if it were broken. A row with no red-capable check is a gap; record it now, not at the end.
22
- 2. **Establish the appropriate test proof.** For features and bugs, check that the regression test fails on the original code for the intended reason and passes on the candidate. For refactors, characterization tests must pass on both. In a managed run, `run finish` runs `prove-red` when the proof is missing or outdated; run `run prove-red` yourself for an earlier check, and inspect its receipt. Do not manually revert shared working files. New runs retain permitted originals through Git and/or bounded run-start capture, including plain/no-commit projects; older runs cannot gain a capture after edits. Missing or changed needed originals refuse proof. Use a quiescent working folder: the project operation lock coordinates controllers, while external edits are checked only at boundaries. On a conflict or interruption, use `run recover`, preserve current files/locks and the recorded candidate backup, and compare deliberately; never clear locks, overwrite another writer or reset a halted run to force proof. See [ownership and recovery](../../docs/onboarding-recovery.md#proof-conflicts-and-interrupted-ownership). The aggregate proof establishes that at least one new test detects changed behavior, not that every test does. Existing-behavior guards may stay green. For advisory claims, inspect primary evidence and reproduce findings where feasible; no manufactured red test is required. If proof is unavailable, record the actual limitation and alternative evidence through the supported assessment exemption; never describe it as proven or disguise testable behavior as untestable. See [run-start originals](../../docs/runtime.md#run-start-originals).
23
- 3. **Run the journey, not only the unit.** Run the recipe's checks that apply to this change first. For anything the recipe doesn't cover, pick the tightest loop that exercises the real path, in this order of preference:
24
- 1. the project's existing test for that behavior
25
- 2. a new focused test at the boundary the user touches
26
- 3. a script or CLI call with a snapshot or diff of output
27
- 4. an HTTP request (`curl`) against the running app
28
- 5. a headless browser such as Playwright for UI journeys (click, reload, check again)
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
- Applicable checks have captured evidence, every criterion and affected consumer has a result, and every passing claim cites evidence for the current file state. Changed behavior has the required red/green proof; refactors have preservation evidence; exemptions and advisory observations remain labeled. If a required criterion is failed or unverified, do not record a passing stage: route it using the table below. A review can report defects successfully when its criteria ask for supported findings rather than a working product.
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
- **Pre-existing failures.** Normal runs do not run a baseline before editing. A project may explicitly enable `verification.baseline: true` for diagnostic background measurements; do not wait for them. For bug fixes and features without one, the proof's control run measures every check on the run-start code. An unrelated check that already failed there can be accepted with a reason, in `run finish` (`acceptFailures`) or with `run accept-failure`. It no longer blocks completion while it fails exactly as it did then, and another check passes. "Exactly" means the same exit code, the same output lines apart from timings, and no file you changed named in its output.
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
- | Name | The tell | Fix |
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
- Read `run recover --run ID` after a verification failure or interruption. Failed receipts remain diagnostic even when current verification has been invalidated. Describe the specific failed behavior, the cause only as far as the evidence supports it, and the next justified action. Executable-not-found and timeout observations do not by themselves diagnose the application. Use the existing review and receipt when teammate help is needed; never automatically message someone or start a new budget after exhaustion. See [recovery guidance](../../docs/onboarding-recovery.md).
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
- Homework "mark finished": the matrix has rows for the click, the active list, the remaining count, reload persistence, old saved records without a `finished` field, and double-marking. The new persistence test is first run against the unmodified save code and fails, proving it can catch the bug. After the fix it passes, and a reload check in the browser confirms it. The row for cross-device sync stays out of the matrix because it was never requested.
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.7.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.7.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"
@@ -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
+ }