@printpractical/cruze 0.0.13 → 0.0.14

package/skills/realign/notes/0.0.8.md

@@ -1,97 +0,0 @@
-# Realign notes: 0.0.8
-
-## Existing code
-
-### module-path-glob: A module's Path is a directory or a file, never a glob
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-formats/reference/architecture.md`, "Element facts"
-- Detect: validate:module-path-glob
-- Migrate: replace each glob in a `MOD` element's `Path` with the directories it meant, each ending in `/`, or the files, through `rethink` at architecture level.
-
-### budget-not-a-shape: No code is bent to fit a file budget
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-hexagonal-design/SKILL.md`, "Many small modules"
-- Ask: is any code shaped to stay under `check.max_lines` or `check.max_types`, such as a type alias, a string where an error type belongs, merged types, a function placed away from its owner, or Rust domain tests moved out of their file only for its length?
-- Migrate: write the code as it would be with no budget. Split a file that then passes its budget along a second responsibility, or list it under `check.exceptions` with the reason it has one. Rust domain tests may move back inline, since their `#[cfg(test)]` modules no longer count.
-
-### no-dependency-workarounds: No code works around a dependency or feature nobody asked for
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-dependency-approval/SKILL.md`, "Weighing"
-- Ask: does any code hand-write, shell out for, or use a less idiomatic construct for something a dependency or a feature of an approved dependency does cleanly, where the design or a deviation gives avoiding the dependency as the reason?
-- Migrate: ask the user for the dependency as the dependency-approval skill says, then replace the workaround through `rethink`: at architecture level when the workaround is in an `XC` rule or an import allowlist, at feature level otherwise.
-
-### size-exceptions: An accepted size warning is recorded under changes.exceptions
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-formats/reference/config.md`, "changes.exceptions"
-- Ask: does `cruze validate` report a `change-too-small`, `change-too-large`, `plan-too-large` or `feature-size` warning that a `D<n>` line records the user accepting? `cruze approve` now refuses the item until it is listed.
-- Migrate: list each such feature or change under `changes.exceptions` in `.cruze/config.yaml`, as its ref and the decision's reason.
-
-## New work only
-
-### fresh-session: Every step runs in a new session
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-next/SKILL.md`, "Steps", step 3
-
-### show-scope: Plan, build and the roles read the scope through cruze show
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 6
-
-### scoped-ledger: The settled ledger is the item's, and journal list leaves landed work out
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/SKILL.md`, "The settled ledger"
-
-### round-2-by-agent: Round 2 is checked by the agent
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Round 2"
-
-### verifier-front-doors: The verifier drives the scenarios that have a front door and never idles
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/verifier.md`, "Work", step 3
-
-### design-gives-every-value: The design gives every error, limit, timeout, transition and message owner
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 6
-
-### one-owner-per-rule: Plan gives each rule one owner, and each item to its first handler's task
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-plan/tasks.md`, steps 2 and 4
-
-### deviations-reviewed: The code reviewer reports a deviation that needed a rethink
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/code-reviewer.md`, "Rubric", item 11
-
-### depends-on-gate: Building waits for every change a change depends on to land
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-build/SKILL.md`, "Steps", step 1
-
-### build-checks-ci: Build runs the same check as verify and CI
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-build/SKILL.md`, "The task loop", step 4
-
-### check-in-flight-modules: cruze check knows the modules that work in progress adds
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-build/SKILL.md`, "The task loop", step 4
-
-### cites-dropped: Work doesn't cite a scenario its delta drops
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-formats/reference/specs.md`, "Spec delta"
-
-### planned-breaks: Plans name a break as the wrong behaviour, and put each test in the task that builds what it checks
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-plan/tasks.md`, step 2
-
-### declaring-files: A task lists the file that declares what it adds
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-plan/tasks.md`, step 3
-
-### named-dependencies: Every outside name the design uses comes from a dependency the using target declares
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-research/SKILL.md`, "Adopt or build", step 7
-
-### nits-are-counts: Review nits get no disposition
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a review"
-
-### illustrated-questions: Questions, review exceptions and the walkthrough show what each option looks like
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-grilling/illustrating.md`

package/skills/realign/notes/0.0.9.md

@@ -1,59 +0,0 @@
-# Realign notes: 0.0.9
-
-## Existing code
-
-### budget-backstop: File budgets are a backstop, and files split by responsibility, never by length
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-hexagonal-design/SKILL.md`, "Many small modules"
-- Ask: does `.cruze/config.yaml` still set the old defaults, `check.max_lines: 250` and `check.max_types: 5`? Is any `check.exceptions` entry, or any split of one owner across files, there only to meet them?
-- Migrate: raise the budgets to `max_lines: 600` and `max_types: 12`, unless the user chose the old ones, and remove each exception whose file is now within budget. A split made only for length, whose files share one responsibility, merges back in a prefactor; waive it when the files read well apart.
-
-### flow-control-review: A design says how its work flows, waits and recovers
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 11
-- Ask: for each feature in flight, does its design leave out any check in rubric item 11 that a scenario or an `XC` rule depends on, such as what a sender does when a queue is full, or what happens when a reconnect fails?
-- Migrate: settle each gap through `rethink` at feature level before the feature's next change is planned. Code a landed change built goes to a prefactor.
-
-### references: External specifications the design must follow are listed under references
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-formats/reference/config.md`, "references"
-- Ask: does the project rely on an external document it must comply with, such as a protocol specification in the repository, that `references:` in `.cruze/config.yaml` doesn't list?
-- Migrate: list each under `references:` with its path and what it governs, as the user confirms.
-
-## New work only
-
-### plan-splits-by-responsibility: Plan splits a file for a second responsibility, never for its length
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-plan/tasks.md`, step 6
-
-### name-clash-review: The design reviewer checks new names against the ones a caller already reaches
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 8
-
-### architecture-rethink-review: An architecture rethink that changes a contract gets a design review of the diff
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-rethink/levels.md`, "Architecture", step 2
-
-### missed-by-design-review: A gap the design review's rubric covers is missed by design-review
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-rethink/SKILL.md`, "Steps", step 7
-
-### sent-back-to: A sent-back verification says whether the change goes back to build or to rethink
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-verify/SKILL.md`, "Steps", step 10
-
-### standalone-plan-approval: The user approves the plan of a standalone change
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 13
-
-### deviation-read-back: Build reads a deviation back, and one that names a value the design didn't give is a rethink
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-build/SKILL.md`, "Deviations"
-
-### prefactor-verify: The verifier runs no suite again for a change that delivers no scenarios
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/verifier.md`, "Work", step 3
-
-### design-on-main: The approved design reaches main before plan branches from it
-- Applies to: new work only
-- Rule: `.agents/skills/cruze-architect/SKILL.md`, "Next step"

package/skills/realign/notes.md

@@ -1,40 +0,0 @@
-# Realign notes
-
-Each release that changes what Cruze expects of a project ships a notes file, `notes/<version>.md`. `cruze realign status` reads the notes between the project's `standards:` and the installed version.
-
-## Releases
-
-- [0.0.2](notes/0.0.2.md)
-- [0.0.3](notes/0.0.3.md)
-- [0.0.4](notes/0.0.4.md)
-- [0.0.5](notes/0.0.5.md)
-- [0.0.6](notes/0.0.6.md)
-- [0.0.7](notes/0.0.7.md)
-- [0.0.8](notes/0.0.8.md)
-- [0.0.9](notes/0.0.9.md)
-- [0.0.10](notes/0.0.10.md)
-- [0.0.11](notes/0.0.11.md)
-- [0.0.12](notes/0.0.12.md)
-- [0.0.13](notes/0.0.13.md)
-
-## Format
-
-A note is a `###` heading with an ID and a title, then facts:
-
-```markdown
-### test-placement: Rust tests live in tests/
-- Applies to: existing code
-- Rule: `.agents/skills/cruze-hexagonal-design/languages/rust.md`, "Dependencies and tooling"
-- Detect: check:test-placement
-- Migrate: move `src/<module>/tests.rs` to `tests/<module>.rs`
-```
-
-| Fact | Holds |
-| --- | --- |
-| `Applies to` | `existing code`, when work that met the last release must change; `new work only`, when only future work follows it |
-| `Rule` | The skill file and heading that state the rule |
-| `Detect` | The CLI rule that finds it, as `check:<rule>` or `validate:<rule>` |
-| `Ask` | The question the auditor answers when no CLI rule can |
-| `Migrate` | How existing work changes to meet it |
-
-A note for existing code has `Migrate`, and `Detect` or `Ask`.

package/skills/rethink/SKILL.md

@@ -1,62 +0,0 @@
----
-name: cruze-rethink
-description: Steps back from any point, before or after landing, when something decided upstream turns out wrong or new information arrives. It amends only the level the discovery touches, keeps completed work, re-approves what went stale, and records the rethink for improving Cruze.
----
-
-# Rethink
-
-Finding a design flaw mid-build is information, not failure. Rethink amends the highest document the discovery touches and lets computed status show what went stale downstream. Then it re-approves exactly that, keeping every completed task the amendment doesn't touch. There is no state to reset: approvals follow content, so editing a document is how you step back.
-
-## Steps
-
-1. **State the discovery.** Say what is wrong or new, and quote the evidence: the failing test, the output, the document line, or what the user said. When `cruze next` sent you here for findings decided `rethink`, those findings are the discovery: `cruze show <ref>` lists them in its ledger.
-2. **Classify it.** Pick the level from the table below, using the highest level the discovery touches. Pick its kind:
-   - **Defect:** a Cruze step should have caught it.
-   - **Discovery:** it is new information no step could have had.
-
-   Tell the user the level and the kind in one line, and let them correct it.
-3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md`. At feature or architecture level, also read `.agents/skills/cruze-hexagonal-design/SKILL.md`, `.agents/skills/cruze-research/SKILL.md` and `.agents/skills/cruze-dependency-approval/SKILL.md`. Also read the format reference for the document you will amend: `.agents/skills/cruze-formats/reference/architecture.md`, `specs.md`, `work-items.md` or `durable-docs.md`.
-4. **Amend that level,** following the level's section in [levels.md](levels.md). Settle any decision the amendment needs with the user, and record it as that level records decisions. At feature level and above, design the amendment as architect designs a feature, following the Rules in `.agents/skills/cruze-architect/SKILL.md`: read the vision's principles and capabilities that must stay possible, the feature map and the roadmap, and design for the features ahead while building only what the work in hand needs. Each option you offer says how the features ahead would use it, which capabilities it keeps open, and what it does to a running device or service, such as across a restart, an upgrade or a downgrade. In one architecture rethink, the user had to ask whether an option would still work for the apps the product plans to host, and point out that refusing to start after a downgrade could brick a router.
-5. **Keep completed work.** A ticked task stays ticked unless the amendment changes its owner, its files, or what it proves. Reopen each task that changed with `cruze task reopen T<n> "<what changed>"`. Its commits stay in history, and build redoes the task.
-6. **Re-approve what went stale.** Run `cruze status` and work from the top down. The amended document comes first, and the user approves it as its level says. Then take each feature or change it lists as `upstream changed`, whose own text you didn't edit:
-   - Run `cruze diff <ref>`. It shows each changed element's approved and current text, and whether the work's delta needs a rebase. Check the work still holds against it. When it doesn't, amend it too, and the user approves it as an amended document.
-   - When it holds, re-stamp it with `cruze approve <ref> --restamp-unchanged`. The CLI refuses work whose own text changed, a project document, and a change with a task reopened since its approval; the user re-approves those.
-
-   Tell the user, in one line each, what you re-stamped and why it still holds. They can object, and that document goes to them. A change's verification carries over when its own design didn't change.
-7. **Record the rethink.** Draft the entry and show it to the user in one line. When they confirm, run:
-
-   ```sh
-   cruze journal add rethink --set level=<task|detail|change|feature|architecture|vision> --set kind=<defect|discovery> \
-     --set summary="<what changed>" --set wrong="<document and element, and what was wrong>" \
-     --set found_by=<step> [--set missed_by=<step>] \
-     --set agent="<the agent you run in>" [--item <ref>]
-   ```
-
-   Name the feature or change with `--item` whenever the rethink amends one: a rethink recorded for it closes the findings decided `rethink` on it.
-
-   `found_by` is the step that found it. A defect also needs `missed_by`, the earliest step whose job was to catch it. Both take one of `envision`, `architect`, `research`, `design-review`, `walkthrough`, `plan`, `plan-review`, `build`, `code-review`, `verify`, `land`, `realign`, `improve`, `validate`, `check` or `user`. When a design review ran over the element and an item of its rubric, `.agents/skills/cruze-roles/design-rubric.md` or `.agents/skills/cruze-roles/plan-rubric.md`, covers the gap, `missed_by` is `design-review`, not `architect`: a retro reads it to know which rubric to fix.
-
-Done when `cruze status` shows every document approved and current, or names only work the user chose to leave for later.
-
-## Levels
-
-| Level | Example | Amend | Then |
-| --- | --- | --- | --- |
-| Task | A helper belongs in a different file of the same module | Nothing. Record it with `cruze task deviation` | Carry on building. This is not a rethink, so record no rethink entry |
-| Detail | Build or verify needs a limit, timeout, message or error case | The element's text, with the code | The user approves it, with no review. Run from build or verify, as [levels.md](levels.md) says |
-| Change | A test plan row or a task's file is wrong, with no design change | `change.md`: its test plan or tasks | Plan review of the diff, then re-approve the change |
-| Feature | A use case needs a second port operation; a scenario is wrong | `feature.md`: its deltas and Changes table, or a standalone `change.md`'s deltas | Design review of the diff, walkthrough of the changed parts, then re-approve the feature and its changes |
-| Architecture | An entity boundary is wrong, or a new port is needed | `docs/architecture.md` directly, plus an ADR when it passes the ADR test | Design review of the diff when it changes an operation, port, error or `XC` rule, walkthrough of the diff, then `cruze approve architecture`, with `--replan` for built elements whose code must change |
-| Vision | The release's scope was wrong, or a new goal appears | `docs/vision.md`, and `docs/roadmap.md` | Re-approve the vision and the roadmap. Decide what happens to features that served a dropped goal |
-
-## After landing
-
-Landed work is history, so rethink never edits an archived folder.
-
-- A discovery about behaviour that already shipped becomes a tweak or a feature through `architect`.
-- A discovery about the design becomes an architecture-level rethink, whose `--replan` hands the rebuild to a change.
-- A `merge-conflict` from `cruze land`, or a `rebase-required` from `cruze approve`, is a feature-level rethink, reconciled as described in [levels.md](levels.md).
-
-## Next step
-
-Run `cruze next`, and name what it says. Start it in a new session, so its context starts empty.

package/skills/rethink/levels.md

@@ -1,54 +0,0 @@
-# Amending each level
-
-## Detail
-
-A detail settles a limit, timeout, buffer size, message or error case that an element of the work in progress doesn't give, with no new element, port operation or dependency, and no change to an approved scenario. Build and verify run it without leaving their step: one message length settled as a full rethink took 75 minutes.
-
-1. Ask the user, recommending a value and showing what the code then does, as `.agents/skills/cruze-grilling/illustrating.md` says.
-2. Amend the element where it lives, in the delta or `docs/architecture.md`, adding at most one failure scenario and its test plan row for a new error case. Run `cruze validate`; done when it reports no errors.
-3. Commit the text with the code and its test, naming the task. Tasks stay ticked.
-4. The user approves the amended document. Re-stamp what went stale, and record the rethink with `level=detail`, as the skill's steps 6 and 7 say.
-
-## Change
-
-1. Edit the change's `## Test plan` or `## Tasks` so they are right. The scope doesn't change at this level; a scope change is a feature-level rethink.
-2. Run `cruze validate`. Done when it reports no errors for the change.
-3. Run the plan review from `.agents/skills/cruze-roles/SKILL.md` on the diff alone, with the design reviewer's plan rubric, `.agents/skills/cruze-roles/plan-rubric.md`, and `review=plan`.
-4. Re-approve with `cruze approve <change> --by-agent` once the review has closed, as plan does.
-
-## Feature
-
-1. Edit the feature's `## Spec delta`, `## Architecture delta` or `## Changes`. Read the elements the discovery touches with `cruze show <ID>`, which prints the living body and this feature's version side by side, and the rest of `feature.md` when the amendment reaches beyond them. For a standalone change, edit its own deltas and scope. Write complete bodies, as `architect` does, and keep the scope rules.
-2. Run `cruze validate`. Done when it reports no errors for the feature or its changes.
-3. Run the design review from the roles skill on the diff alone, with `review=design`. Run the walkthrough of the changed parts, following `.agents/skills/cruze-architect/walkthrough.md`.
-4. Re-approve the feature. For each of its changes that shows as stale, check it against the diff. When the amendment touches the change's scope, test plan or tasks, update them to match, reopen touched tasks, run the plan review on the diff, and re-approve it with `cruze approve <change> --by-agent`. When it doesn't, re-stamp the change as the skill's step 6 describes.
-5. When a change hasn't been created yet, only the feature's Changes row changes; `plan` picks it up.
-
-## Architecture
-
-1. Edit `docs/architecture.md` directly. Keep every element's ID, and write complete bodies. Write an ADR with `cruze new adr` when the decision passes the ADR test, and link it under `## Decisions`.
-2. Run `cruze validate`. When the amendment adds, renames or changes an operation, a port, a use case's `Errors` or an `XC` rule, run the review in `.agents/skills/cruze-roles/SKILL.md` on the diff with the design reviewer, `review=design`: a realign amendment once named a method that clashed with one the type already had, found only at plan. Then run the walkthrough of the diff only, following `.agents/skills/cruze-architect/walkthrough.md`.
-3. List the elements you changed that are already `built`, whose code must now change. When the user approves, run `cruze approve architecture`, adding `--replan <ID>` for each of them. They go back to `planned` until a change rebuilds them, and only a land sets them back to `built`. A `- Status:` line belongs to the CLI: when an element was replanned by mistake, tell the user, and let the change rebuild or re-check it.
-4. Commit the amendment, and get it onto main on its own, as a pull request or a merge. Every branch and every later change must build on it. Then merge main into the branch you were working on.
-5. Hand each replanned element to a change that rebuilds it:
-   - **The current change**, when the rebuild belongs to its work. Add the element to the feature's Changes row for that change and to the change's `Builds`, then re-plan and re-approve the change.
-   - **A prefactor**, otherwise. From an up-to-date main, run `architect "<prefactor>"`, which designs it as a standalone change, then `plan`, `build`, `verify` and `land` it before the current change continues.
-6. Run `cruze status`. Every document citing a changed element shows `upstream changed`:
-   - When the document's own delta still changes that element, rewrite the delta so it keeps your amendment. `cruze approve` refuses it with `rebase-required` until you do, and `cruze diff <ref>` names each such element. Then approve it with `--rebase <ID>`.
-   - Otherwise, check the document against `cruze diff <ref>`, and re-stamp it or amend it as the skill's step 6 describes. An element the feature already merged, with its delta entry unchanged since, needs no rebase: the living text now holds it, and later lands keep your amendment.
-
-## Vision
-
-1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add`, `cruze features update` and `cruze features drop`. When the problem, users or goals changed, update the overview under the title of `README.md` to match.
-2. Update `docs/roadmap.md` to match, following `.agents/skills/cruze-roadmap/SKILL.md`.
-3. For each feature in progress that served a dropped goal, the user decides: keep it, or stop it with `cruze abandon <ref> --reason "<why>"`. Abandoning archives the folder and puts the feature back on the future list; changes that already landed stay.
-4. Re-approve with `cruze approve vision`, then `cruze approve roadmap`.
-
-## A conflict with living text
-
-`cruze approve` refuses a feature or standalone change with `rebase-required` when an element its delta changes was edited in the living docs since its last approval, by a rethink, a realign or another branch's land, and the delta would still write that element: the work hasn't merged it yet, or has changed its delta entry since merging it. `cruze land` refuses with `merge-conflict` for the same reason when the approval came first. Either way, the delta would overwrite that edit. Record the rethink at feature level.
-
-1. Show the user `cruze diff <feature>`, which has the element's approved and current text, and the feature's delta for it.
-2. Rewrite the delta's body so that it holds both: their edit, and what this feature needs.
-3. Re-approve the feature with `cruze approve <feature> --rebase <ID>`. This records that the feature now builds on the current text.
-4. Re-approve the change that is landing, when it shows stale; its verification carries over. Then run `land` again.

package/skills/roadmap/SKILL.md

@@ -1,54 +0,0 @@
----
-name: cruze-roadmap
-description: Orders the release's features and standalone changes into phases with blocking edges and goal coverage, adds or reorders items as work starts or plans change, and closes a finished release to plan the next.
----
-
-# Roadmap
-
-`docs/roadmap.md` is the index of the current release. It changes only when an item is added, reordered or dropped, or a release closes. The CLI keeps its managed `## Status` table current as work starts and lands. Format: `.agents/skills/cruze-formats/reference/durable-docs.md`.
-
-## Steps
-
-1. **Read the state.** Read `docs/vision.md` (goals and feature map), `docs/roadmap.md`, and `docs/architecture.md` as "Reading it" in `.agents/skills/cruze-formats/reference/architecture.md` says, and run `cruze status`. The vision must be approved. When no roadmap exists, stop: project-scope `architect` creates the first one with the foundation.
-2. **Pick the job.**
-   - **Add an item:** a feature or standalone change the user wants in this release. Its slug comes from the feature map when it is there.
-   - **Reorder or drop:** the order or scope of the release changed.
-   - **Close the release:** every item in `## Status` is `landed`, or the user decides to ship what has landed.
-3. **Load the standard.** Read `.agents/skills/cruze-grilling/SKILL.md`. The order of work is the user's decision, so put each ordering question to them with your recommendation.
-4. **Do the job,** as described in the matching section below.
-5. **Check the rules.**
-   - Every item names the goals it serves.
-   - `Blocked by` names only items in this or an earlier phase, and the blocking graph has no cycle.
-   - Every goal the release covers has at least one item in `## Coverage`.
-   - A phase holds items that can proceed in parallel once their blockers land.
-   - Done when `cruze validate` reports no errors in `docs/roadmap.md`.
-6. **Approve.** Show the user the phases, the blocking edges and the coverage table. When they approve the ordering, run `cruze approve roadmap` and quote its result.
-
-## Adding an item
-
-- Place it in the earliest phase whose items don't block it. Name its blockers: an item blocks it when it builds an element this item extends, or delivers behaviour this item changes.
-- A prefactor restructures code that later items build on, so it goes first: each item it overlaps names it under `Blocked by`. The exception is an item already building, with a change planned or in progress, which the prefactor would rebuild under: the prefactor waits for it and names it under `Blocked by` instead. Put the order to the user either way. One project's realign put a prefactor behind a feature that hadn't started, and the user wanted it first.
-- Add its slug to the coverage row of each goal it serves.
-- A feature that isn't on the feature map gets there first: `cruze features add <slug> --summary <text> --goals <ids>`.
-
-## Reordering or dropping
-
-- Never move or drop an item whose `## Status` row shows it started (`designing` or `building`) without the user deciding what happens to its folder. The options are to finish it, or to stop it and supersede it later.
-- Move a dropped feature back to the future list with `cruze features add` when it may return. When it won't, record why with `cruze features drop <slug> --reason <text>`.
-
-## Closing the release
-
-1. Confirm that every feature that landed shows in the vision's implemented list. `cruze land` moves each one there when its last change lands.
-2. Agree the next release with the user: its name, one sentence on what it delivers, and which future features it takes from the feature map. Grill on the goals the choice serves.
-3. Replace `## Release` and `## Phases` with the next release, and rebuild `## Coverage`. Run `cruze roadmap prune` to clear the landed items from `## Status`. The feature map keeps the record.
-
-## Next step
-
-Name the first item whose blockers have all landed:
-
-- A feature whose requirements aren't settled: `envision "<feature>"`.
-- A feature whose requirements are settled: `architect "<feature>"`.
-- A standalone change whose design exists: `plan`.
-- A tweak without a design yet: `architect "<tweak>"`.
-
-Start it in a new session, so its context starts empty.

package/skills/roles/auditor.md

@@ -1,35 +0,0 @@
-# Auditor
-
-You compare a project's existing code and documents with what the installed Cruze now expects, and report every place they differ. You report findings, and you edit nothing.
-
-## Inputs
-
-- The notes to audit, from `cruze realign status`: each note's ID, `Rule`, `Ask` and `Migrate`.
-- In a full audit, the standards instead of notes: `.agents/skills/cruze-hexagonal-design/SKILL.md` and its language file, `.agents/skills/cruze-behavioural-testing/SKILL.md`, and `.agents/skills/cruze-formats/reference/architecture.md`. You audit one module, named with its `Path`.
-- `docs/architecture.md`, for the module map and the elements the code implements: `cruze show --index <context>` lists them, and `cruze show <ID>` prints each.
-- The files in scope: every source and test file under the project's `source` and `tests` globs in `.cruze/config.yaml`, or under the module's `Path`.
-- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, and the earlier realign dispositions from `cruze journal list --event disposition`. Never raise a finding they waived.
-
-## Work
-
-1. For each note, answer its `Ask` for every file in scope, not a sample. Work module by module.
-2. For each difference, find the smallest fix the note's `Migrate` allows, and whether it changes the text of an element in `docs/architecture.md`.
-3. Done when every note has findings, or evidence that the code already meets it.
-
-## Findings
-
-Group findings by note, in this shape:
-
-```markdown
-### <n>. <note ID>: <one-line summary>
-- Evidence: <path:line, quoting the code>
-- Standard: <the rule text it departs from>
-- Fix: <the specific change>
-- Design change: <the element in docs/architecture.md whose text must change, or `no`>
-```
-
-List every finding. When one pattern repeats more than 5 times, list 5 and give the count and the paths of the rest in one line.
-
-## Report
-
-End with one line: `Findings: <n> across <m> notes.` For each note with no findings, give the evidence that the code meets it.

package/skills/roles/design-reviewer.md

@@ -1,43 +0,0 @@
-# Design reviewer
-
-You review a design, or a change's plan, before any code exists. You find the places where it is wrong, incomplete or ambiguous enough that a competent implementer who never saw the conversation would build the wrong thing. You report findings, and you edit nothing.
-
-## Inputs
-
-- The artifact under review:
-  - Feature scope: the feature's `feature.md`, and the output of `cruze show <ref>` for the elements its delta cites, each with where it sits, and the settled ledger.
-  - Project scope: `docs/architecture.md`, `.cruze/config.yaml` and `docs/roadmap.md`, plus the foundation change once it exists.
-  - A plan: the change's `change.md`, the output of `cruze show <ref>`, and the output of `cruze status --overlap --change <ref>`.
-- The living docs it builds on: `docs/vision.md`, `docs/glossary.md`, the ADRs in `docs/adr/`, the specs in `docs/specs/` that the artifact cites, and, from `docs/architecture.md`, its Overview, Dependency rules, Cross-cutting concerns and Decisions sections plus each element `cruze show` lists as cited. Read any other element with `cruze show <ID>`, and find what exists with `cruze show --index`. Read the whole architecture only at project scope.
-- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, with the output of `cruze journal list --event disposition --item <ref>`.
-- The output of `cruze validate`.
-- The references `cruze show` lists, from `references:` in `.cruze/config.yaml`: read the sections the design cites or relies on.
-- The standards: `.agents/skills/cruze-hexagonal-design/SKILL.md` and `.agents/skills/cruze-formats/SKILL.md`.
-
-## Rubric
-
-Review against one rubric and nothing else, and read only that one. Each finding names one of its items.
-
-- A design, at project scope or of a feature or a standalone change: `.agents/skills/cruze-roles/design-rubric.md`.
-- A change's plan: `.agents/skills/cruze-roles/plan-rubric.md`.
-
-## Findings
-
-Each finding has this shape:
-
-```markdown
-### <n>. <rubric item>: <one-line summary>
-- Severity: blocker | concern
-- Evidence: <path:line, quoting the text>
-- Failure scenario: <what goes wrong, concretely, if this ships as written>
-- Proposed fix: <the specific edit>
-```
-
-- A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Two elements that contradict each other are always a blocker, because an implementer has to pick one. Everything else is a **concern**.
-- List every blocker. List at most 5 concerns, or one per 5 scenarios in a feature's spec delta, or for a plan one per 5 tasks, when that is more, the most important first. Count the rest as nits: give only their number, never their text. Report only what would go wrong: no concerns is a valid report, and a small artifact usually has few.
-- Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
-- When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.
-
-## Report
-
-End with one line: `Blockers: <n>. Concerns: <n>. Nits: <n>.` When there are no findings, say which rubric items you checked and give the evidence for the most important one.

package/skills/roles/design-rubric.md

@@ -1,41 +0,0 @@
-# Design rubric
-
-The design reviewer's rubric for a design: the architecture at project scope, or the design of a feature or a standalone change. Review against these items and nothing else. Each finding names one. At project scope, items 6 and 11 hold in full for what the foundation builds; a later part may leave a specific open when a `Future` fact names it, but not an operation or data that crosses into the foundation.
-
-1. **Behaviour.** Every requirement has at least one scenario. Every scenario has concrete values, one WHEN, and a THEN a person could check. Failure behaviour the user will meet has its own scenario.
-2. **Seams.** Every scenario can be driven through a use case, or through an inbound adapter when the outcome is what that adapter shows. Every driven port the use case needs can be faked.
-3. **Placement.** Every new or changed element with code has a `Module` whose `Layer` fits its role and a `File` with a real path. No generic modules, and no file is likely to hold two responsibilities. The layout is the one normal for the kind of system and the language, and every layer, module, package or target split beyond a context's `core` and its adapters has a recorded reason. Every element, fact and value serves a requirement in scope, or a `Future` fact the feature map or a `LATER` capability calls for. Anything reserved for a need nobody stated is a finding, and so is anything built, rather than left room for, for a `LATER` capability. A field or value serves a need only when a person, a tool or another element reads it in a scenario or a `LATER` row; a scenario that only checks it is written doesn't count. A design carried over from an earlier build or a seed is checked the same way: one project built a clock port and timestamp parsing for a status field nothing read.
-4. **Direction.** Every dependency points inward and is allowed by the `RULE` elements and the `layers:` in `.cruze/config.yaml`.
-5. **Adopt or build.** Every component that isn't domain logic has an adopt-or-build decision with a reason, and every new dependency is named with the features the design uses. Every type, trait, macro, framework or tool the design names from outside the project comes from a dependency and feature the design approves, declared by each crate, package or target that uses it, test support included, and allowed by the import rules in `XC` and the `layers:` in `.cruze/config.yaml`. A choice whose reason is avoiding a dependency, a crate or a feature, where the idiomatic design needs one, is a concern: name the idiomatic design. Every command the design spells out, such as a CI step, is spelled as that version's `--help` or source shows it. A claim the design relies on that the research left unverified is a blocker.
-6. **Contracts.** Every new or changed port's `Operations` state what each operation guarantees, how it fails, and who owns cleanup. Check each use case and each port operation for the values build would otherwise have to pick: a named error for every failure a caller can meet, where a panic, an `expect` or "caller error" counts as missing; a number for every timeout, limit, buffer and poll interval; what a caller observes after each state transition, and what happens to queued or in-flight work at it; and one owner for every message a scenario quotes. Each one missing is a blocker: two projects settled 35 of them during build, as deviations.
-7. **Flows.** The key scenarios have a `FLOW` whose participants are all in its `Elements`, including the failure paths the scenarios need.
-8. **Consistency.** The design agrees with `docs/architecture.md`, the accepted ADRs, the references and what earlier changes landed, or changes them explicitly through a `MODIFIED` operation or a new ADR. Its own elements agree with each other. Check every pair, not a sample:
-   - each use case's `Output` and `Errors` against the `FLOW`s that serve it and the `XC` rules that apply to it;
-   - each use case against every port operation it calls: it says what it does with each refusal that operation can answer, from its `Operations` and the use case behind it, and lists the port under `Uses`. A new use of an existing operation, such as the clock stamping a new kind of time, is a `MODIFIED` port whose `Operations` name the use;
-   - each adapter's duties against the port it implements and the `XC` rules it follows;
-   - each guarantee, such as "always fits" or "never returns", against the limits and failures that bound it;
-   - each `XC` rule against the other `XC` rules, the `RULE` elements and the `layers:` in `.cruze/config.yaml`, such as a logging rule that every module logs against a build rule that forbids the logging import;
-   - each pair of use cases that change the same state, for an interleaving that leaves it wrong, against the concurrency rule in `XC`;
-   - at feature scope, the prose in `docs/architecture.md`, the ADRs and the feature itself that the delta makes untrue, such as an Overview sentence, a `D<n>` line describing an element the delta splits or replaces, or any sentence stating a rule the delta retires;
-   - each message or value a scenario quotes from code already built, such as an error's printed form or a revision every write advances, against the code that produces it;
-   - each new or renamed operation, method or builder step against the others the same type, trait or caller reaches, for two names a caller can't tell apart, such as an `events` method beside an `events` trait method the type also implements.
-9. **Slicing.** Each change delivers scenarios end to end, through a real interface, and can land on its own. The order respects `Depends on`. At project scope, the first change builds the kind of foundation the user chose, recorded in `## Decisions`, and nothing beyond it. Each change carries enough work to be worth its own plan review, code review and verify: changes that build one or two elements each on the same adapters or screens, in a chain, are one change split too fine. A change that one verifier run can't hold is split too coarse. A `change-too-small`, `change-too-large` or `feature-size` warning from `cruze validate` is a finding, unless a decision records the user accepting it. A change `Builds` an element only when its delivered scenarios prove the whole body; an element whose duties arrive in several changes is split into elements that each arrive whole. `Depends on` names every earlier change that builds something this change's scenarios need. At project scope, the roadmap starts with the foundation, and every goal in the release is covered.
-10. **Ambiguity.** Name each point where a fresh implementer could reasonably build something different from what the user expects.
-11. **Flow control and recovery.** Follow each message, request and event from its source to its consumer through every task, channel and queue the design names, against `.agents/skills/cruze-hexagonal-design/runtime.md`. Check:
-   - each bounded queue or buffer: what a sender does when it is full, and which other work waits meanwhile. One slow peer, link, subscriber or consumer holds up only its own work unless a decision says otherwise, so one queue or one task serving several peers needs a reason. A limit meant to tell a stalled consumer from a burst says how it tells them apart;
-   - each place several sources feed one consumer: the order it takes them in, so that none starves;
-   - each asynchronous result: how it reaches the request that waits for it, including across a reconnect or a retry;
-   - each recovery, such as a reconnect, resubscribe, relist or retry: its schedule, its limit and when that count resets, what happens when the recovery itself fails, what is lost between the failure and the recovery and how the consumer learns of it, and the order of steps that loses nothing, such as subscribing before relisting;
-   - each loop, task and retry: what stops it, and what shutdown does with the work it holds;
-   - each value the design compares with observed state: an adapter can observe it, or the difference is reported for good;
-   - each exclusive resource, such as a socket, a device or kernel state: what happens when a second instance or caller claims it.
-
-   Each one missing that a scenario or an `XC` rule depends on is a blocker: in two projects, 7 of 14 defect rethinks after a design review were one of these, found as late as verify.
-12. **Long-term intent.** Check the design against `## Principles` and `## Must stay possible` in `docs/vision.md`:
-   - each principle: the design follows it, or the vision's row was amended for this design and approved;
-   - each `LATER` capability, whatever its area: nothing in the design, such as a fixed set, a single owner or a one-way protocol, rules it out; and where the design touches its area, it leaves the room the row names, in a `Future` fact that cites the ID;
-   - each part of the user's input handed to this work, as the Notes section of `cruze show` lists it, or `cruze show --notes architect` at project scope: settled with the user, or the design doesn't rest on it;
-   - each settled decision of the design that states long-term intent, such as "eventually" or "later": it is a `LATER` row in the vision, since the decision is archived when the work lands.
-
-   A departure from a principle with no amendment, a `likely` capability closed off, or a design resting on an open hand-off row, is a blocker; a `possible` one closed off is a concern.
-13. **Typed inside.** Each value one of the system's own components passes another in the same process has its own type, as the standards' domain rules say. A serialization format between them, such as a JSON value, a raw frame or an untyped map, is a concern even when an ADR gives the reason, so the walkthrough brings it to the user.

package/skills/roles/plan-rubric.md

@@ -1,11 +0,0 @@
-# Plan rubric
-
-The design reviewer's rubric for a change's plan. Review against these items and nothing else. Each finding names one.
-
-1. **Test plan.** Every delivered scenario has a `behaviour` row at a real seam, with its test file. Every port that a built adapter implements has a `contract` row. Seams need fakes of driven ports only, never mocks of internal code.
-2. **Tasks.** Every task names one owner and file paths the architecture assigns to that owner. Every scope ID is proved by a task. Each task is small enough to build red to green and commit on its own. A task that changes a signature, default or setting lists every file whose callers it breaks, including tests that start the real binary. A task that adds a module, file or dependency lists the file that declares it, such as a crate root, a `mod.rs`, a package manifest or an Xcode project, and the lockfile for a dependency. A task that adds a field lists every file with a literal of its type that names all the fields. A rule, text, format or conversion that several elements apply has one owning file, and each later task that applies it names that file as a callee rather than restating it. An accessor, variant or type arrives in the task whose code first handles, matches or constructs it, never in the task that only tests it.
-3. **Order.** Tasks run from the inside out, domain before ports, use cases and adapters, so each task's test can fail first and then pass. A test sits in the task that builds the behaviour it checks: a test that an earlier task's code already passes is in the wrong task. A break the plan names is a behaviour the task's code could get wrong, not an edit that may not compile. The last tasks wire the composition root.
-4. **No design.** Nothing in the plan changes the architecture or the specs. A plan that needs a new element, operation or scenario goes back to `architect` or `rethink`.
-5. **Risks and overlap.** The riskiest task is named, with how it is checked, and that check reaches the failure rather than a value a clamp or default hides. Overlap with work on other branches is resolved or accepted.
-6. **Ambiguity.** Name each task a fresh implementer could reasonably build differently from what the plan means.
-7. **Prefactor.** For a change that delivers no scenarios and rebuilds built elements, as "A prefactor" in `.agents/skills/cruze-plan/SKILL.md` describes: `## Risks` names the existing tests that reach each rebuilt element, and the command that runs them; no task adds, edits or deletes a test, except one that pins current behaviour before the restructuring; and no item's visibility or public surface grows beyond what its new callers need.

package/skills/roles/surveyor.md

@@ -1,41 +0,0 @@
-# Surveyor
-
-You survey existing code for structure that departs from Cruze's current standards, or that keeps causing friction, and say what it should become. You report candidates, and you edit nothing.
-
-## Inputs
-
-- What to survey: the system's layout, or one module, named with its `Path`.
-- The standards: `.agents/skills/cruze-hexagonal-design/SKILL.md`, `.agents/skills/cruze-hexagonal-design/shapes.md`, the language file for the project's language when one exists, and `.agents/skills/cruze-behavioural-testing/SKILL.md`.
-- `docs/architecture.md`, for the module map and the elements the code implements, which `cruze show --index` lists and `cruze show <ID>` prints, and `.cruze/config.yaml`.
-- `## Principles` and `## Must stay possible` in `docs/vision.md`: why parts of the design exist that no current feature uses yet.
-- The files in scope: for the layout, the build manifests, such as `Cargo.toml` or `Package.swift`, and each module's `Path`; for a module, every source and test file under its `Path`.
-- The journal, landed work included: the output of `cruze journal list --event deviation --all`, `cruze journal list --event rethink --all` and `cruze journal list --event disposition --all`.
-- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, and the earlier `improve` and `realign` dispositions. Never raise a candidate they waived.
-
-## Work
-
-1. **The layout.** Name the kind of system, and compare the module map and the packages, crates or targets with the layout `shapes.md` and the language file describe. For each boundary between packages or targets, count what it costs: the declarations made public to cross it, and the bridges, re-exports and duplicated types that exist only because of it.
-2. **The module's code.** Read every file in scope, not a sample. Check it against the standards: who owns each rule, dependency direction, ports and adapters, errors, and the warning signs in the hexagonal-design skill.
-3. **The journal.** Find the deviations, rethinks and review findings that name a file in scope, and group them by cause. A cause that recurs is friction.
-4. **The history.** Run `git log --format=%h --name-only -n 300 -- <Path>`. Name the files outside the module that change in the same commits as its files in more than half of those commits; a boundary there is often in the wrong place. Name the files that change most.
-5. **One operation.** Pick one representative operation the module serves, and list the files a reader opens to follow it from the inbound adapter to the outbound one. Note modules that only forward calls, and pairs of modules that own one responsibility between them.
-6. **Shape each candidate.** Give the smallest target that meets the standard or removes the friction, and say whether it changes the text of an element in `docs/architecture.md`. A target keeps behaviour, keeps small files, and keeps every technology behind a port. It follows every principle and keeps the room each `LATER` capability needs; when removing something would close one off, name the capability, and leave the choice to the user.
-
-Done when every file in scope was read, and every candidate has evidence.
-
-## Report
-
-One block per candidate:
-
-```markdown
-### <n>. <one-line summary>
-- Kind: standard | friction
-- Evidence: <path:line quoting the code, journal entries with their timestamps, or commit counts>
-- Cost: <the rule text it departs from, or what the friction cost, such as five deviations>
-- Target: <the specific shape it should take>
-- Size: <prefactor changes, and tasks in each>
-- Risk: <what could break, and which tests cover it>
-- Design change: <the elements in docs/architecture.md whose text must change, or `no`>
-```
-
-Report every candidate that has evidence, and none that doesn't. End with one line: `Candidates: <n>. Standard: <n>. Friction: <n>.`

package/skills/roles/verifier.md

@@ -1,42 +0,0 @@
-# Verifier
-
-You check that a change actually works when someone uses it. The tests passing is not enough: you build the real system, and run each scenario the change delivers through its real front door. You report what happened, and you change nothing in the project.
-
-## Inputs
-
-- The change's `change.md`, for its test plan, and the output of `cruze show <ref>`: the scenarios it delivers, written out, and the flows and elements it builds.
-- The project's commands, from `commands:` in `.cruze/config.yaml`, and from `README.md` when they aren't there.
-- The mechanical checks' results, with the commit they ran at.
-
-## Work
-
-1. **Build.** Build the system with the project's build command, and record whether it passed. The test suite already ran at the commit in your inputs, and CI runs it again before the merge, so don't run it. Run a single test only when it is how a scenario reaches its real front door, such as a UI test that drives the app.
-2. **Trace.** Run `cruze trace --change <ref>` and record its result.
-3. **Run each scenario that has a front door.** A scenario whose test plan row names an inbound adapter, a screen or a real adapter as its seam is one a user meets, so run it:
-   - Set up its GIVEN with real things where you can: configuration files, directories, a local test server, a pseudo-terminal. Put them in a temporary directory outside the project.
-   - Perform its WHEN through the real inbound adapter, such as the CLI binary or an HTTP request, the way a user or client would.
-   - Compare what you observe with its THEN, word for word where the scenario quotes output.
-
-   A scenario whose row runs through a use case with fakes is proved by its behaviour test, which passed at the checks commit: give the test's file and name as `Ran:` and the commit as `Observed:`, and don't drive it. Driving every scenario cost one app project 31 minutes a change, for one defect in 28 runs.
-
-   A change that delivers no scenarios, such as a prefactor that keeps behaviour, is proved by the suite that passed at the checks commit. Run the system once through a front door that reaches each element it rebuilds, as a smoke check, and run no test or test suite again: one prefactor's verifier re-ran a 4-minute UI suite that had passed an hour before.
-4. **Probe one step further.** For each scenario you ran, try the nearest thing a user would plausibly do next or get wrong, such as the same command twice, a typo in the input, or an interrupt. Report surprises; they are not failures of the scenario.
-5. **Clean up** everything you created outside the project.
-
-When a scenario needs something you don't have, such as real hardware or a remote host, don't fake it. Mark it `could not run`, and say exactly what it needs, so a person can run it by hand. The same holds for time: don't idle through a timer, a scheduled notification or a device settling. Drive time through the project's seam for it when there is one; otherwise a wait over 30 seconds is `could not run`, with the wait a person needs.
-
-## Report
-
-One block per scenario:
-
-```markdown
-### SCN-<id>: <title>
-- Result: pass | fail | could not run
-- Setup: <what you created>
-- Ran: <the exact command or request>
-- Observed: <the exact output, exit code or response>
-- Expected: <the THEN, quoted>
-- Notes: <surprises from probing, or what a person needs to run it>
-```
-
-Before the blocks, list the build and trace commands with their results, and the commit the mechanical checks ran at. End with one line: `Pass: <n>. Fail: <n>. Could not run: <n>.`