@printpractical/cruze 0.0.1

package/skills/formats/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: cruze-formats
+description: The formats and templates of every Cruze project document. Use when reading, writing or reviewing any file under docs/ or .cruze/ in a Cruze project.
+---
+
+# Cruze document formats
+
+Every Cruze document is Markdown that people read and the `cruze` CLI parses. Write them exactly in these formats: `cruze validate` rejects documents that drift, and approvals, staleness and merges all depend on the structure.
+
+## Where documents live
+
+| Path | Document | Written by |
+| --- | --- | --- |
+| `docs/vision.md` | Problem, users, goals, non-goals, constraints, feature map | envision (project scope) |
+| `docs/glossary.md` | Domain terms and terms to avoid | any step, as terms settle |
+| `docs/architecture.md` | Contexts, domain model, use cases, ports, adapters, flows, modules, rules | architect (project scope), rethink, land |
+| `docs/adr/<date>-<slug>.md` | One decision that is hard to reverse, surprising and a real trade-off | architect, rethink |
+| `docs/specs/<capability>.md` | Living behaviour: requirements and scenarios | land, from spec deltas |
+| `docs/roadmap.md` | The current release: phases, items, coverage | architect (project scope), roadmap |
+| `.cruze/features/<id>/feature.md` | One feature: intent, deltas, its ordered changes | envision and architect (feature scope) |
+| `.cruze/features/<id>/changes/<NN-slug>/change.md` | One change of a feature: scope, test plan, tasks | plan |
+| `.cruze/changes/<id>/change.md` | A standalone change, carrying its own deltas | architect (tweak scope) |
+| `.cruze/config.yaml` | Project configuration | `cruze init`, architect |
+| `.cruze/notes/<date>-<slug>.md` | A captured explore note, or research evidence behind an adopt-or-build decision, free-form | explore, research |
+
+Only the CLI writes `approvals.json`, `journal.jsonl` and anything under `.cruze/archive/`.
+
+## IDs
+
+An ID names one element for its whole life. Other documents cite it, tests carry it, and approvals hash it.
+
+- Grammar: `<KIND>-<name>` or `<KIND>-<scope>.<name>`. `scope` and `name` are lowercase words joined by single hyphens, such as `REQ-access.open-console`.
+- Elements that belong to a bounded context or a capability carry it as their scope. Elements outside every context, such as the CLI shell and the composition root, use the scope `system`.
+- IDs are named, never numbered, so parallel branches never race for the next number.
+- An ID is never reused, even after its element is removed. Rename the title freely; the ID stays.
+
+| Kind | Element | Lives in | Scope |
+| --- | --- | --- | --- |
+| `GOAL` | A goal of the product | vision | none |
+| `CTX` | Bounded context | architecture | none |
+| `ENT` | Domain concept: aggregate, entity, value object, domain service, policy or domain event | architecture | context |
+| `UC` | Use case (the application's driving API) | architecture | context |
+| `PORT` | Port, driven or driving | architecture | context |
+| `ADP` | Adapter | architecture | context |
+| `FLOW` | Interaction flow, as a sequence diagram | architecture | context |
+| `MOD` | Module: a directory or file with one role | architecture | context, or none for shared modules |
+| `RULE` | Dependency rule | architecture | none |
+| `VIEW` | Overview diagram | architecture | none |
+| `XC` | Cross-cutting concern | architecture | none |
+| `REQ` | Requirement | specs | capability |
+| `SCN` | Scenario of a requirement | specs | capability |
+| `ADR` | Decision record, named by its file stem | `docs/adr/` | none |
+
+## Elements
+
+- A **heading element** is a heading whose text is exactly `<ID>: <Title>`. It extends to the next heading of the same or a higher level.
+- A **row element** is a table row whose first cell is exactly an ID. Only goals use rows.
+- Element facts are list items of the form `- Key: value`, directly in the element's body. Sub-items hold lists of values.
+- An element cites another by writing its ID anywhere in its body. Every ID a document mentions counts as cited.
+- A cited ID must exist, either in the living docs or in a delta of the same feature or change. Design at project scope cites only what it defines; the feature that adds scenarios links them to flows and use cases through `MODIFIED` operations.
+
+## Managed content
+
+The CLI owns some content so that routine bookkeeping never changes a design:
+
+- A block between `<!-- cruze:managed -->` and `<!-- /cruze:managed -->` is written only by the CLI.
+- A `- Status: planned` or `- Status: built` item in an element body is written only by the CLI. Elements that have code (`ENT`, `UC`, `PORT`, `ADP`, `FLOW`, `MOD`) and scenarios (`SCN`) carry one.
+- Both are excluded from every hash. Read them freely; change them only through `cruze` commands:
+  - `cruze approve` adds missing statuses to the architecture, sets built elements back to planned with `--replan`, and binds a change to its branch.
+  - `cruze task` records progress, and `cruze features` edits the feature map.
+  - `cruze land` merges work, marks it built and fills the Commands and Layout sections of `AGENTS.md`.
+  - `cruze roadmap prune` and `cruze abandon` update the roadmap's status.
+
+## Reference files
+
+Read the one that matches the document in front of you:
+
+- [reference/architecture.md](reference/architecture.md) for `docs/architecture.md` and architecture deltas.
+- [reference/specs.md](reference/specs.md) for `docs/specs/`, requirements, scenarios and spec deltas.
+- [reference/work-items.md](reference/work-items.md) for `feature.md`, `change.md`, test plans and task lines.
+- [reference/durable-docs.md](reference/durable-docs.md) for vision, glossary, ADRs and the roadmap.
+- [reference/config.md](reference/config.md) for `.cruze/config.yaml`.
+
+Create documents with `cruze new`: `cruze new vision`, `glossary`, `architecture` or `roadmap` for the project documents, and `cruze new feature`, `change`, `adr` or `note <slug> --title <title>` for the rest. It starts each one from the matching file in `templates/` and fills the `{{placeholders}}`. Replace every `<angle-bracket>` guide.

package/skills/formats/reference/architecture.md

@@ -0,0 +1,80 @@
+# Architecture format
+
+`docs/architecture.md` is the living model of how the system is built. Every step reads it, including build and review. It describes the designed system for the current and upcoming releases. Each element's managed `Status` says whether it is still `planned` or already `built`.
+
+Template: [../templates/architecture.md](../templates/architecture.md).
+
+## Sections
+
+The document has these `##` sections, in this order. Each holds elements of one kind as `###` heading elements, plus any `VIEW` diagrams that summarize them. A section with no elements yet keeps its heading and a one-line note.
+
+| Section | Kind | Holds |
+| --- | --- | --- |
+| Overview | `VIEW` | One paragraph on the system, then a context diagram |
+| Bounded contexts | `CTX` | Each context's purpose and what it depends on |
+| Domain model | `ENT` | Entities, aggregates, value objects, domain services, policies and domain events, with invariants and relationships |
+| Use cases | `UC` | The application API: what callers can ask the system to do |
+| Ports | `PORT` | Capabilities the application needs (driven) or offers (driving) |
+| Adapters | `ADP` | Technology behind ports, and inbound adapters that drive use cases |
+| Flows | `FLOW` | How elements interact for key scenarios, as sequence diagrams |
+| Modules | `MOD` | Where each element lives in the source tree |
+| Dependency rules | `RULE` | What may import what |
+| Cross-cutting concerns | `XC` | Errors, configuration, logging, concurrency, security |
+| Decisions | none | Links to ADRs, one line each, then project-level settled decisions as `D<n>: <decision> (<reason>)`, including overrides of Cruze's advice |
+
+## Element facts
+
+Facts are `- Key: value` items. Keys marked required must be present; the others appear when they apply. Multi-valued facts use sub-items.
+
+| Kind | Required facts | Optional facts |
+| --- | --- | --- |
+| `VIEW` | a Mermaid block | |
+| `CTX` | `Purpose` | `Depends on` (context IDs, with what is used) |
+| `ENT` | `Kind` (`aggregate`, `entity`, `value`, `service`, `policy` or `event`), `Module`, `File` | `Invariants`, `Relationships`, `States` (for state machines) |
+| `UC` | `Input`, `Output`, `Errors`, `Uses`, `Module`, `File` | `Serves` (REQ IDs) |
+| `PORT` | `Direction` (`driven` or `driving`), `Operations`, `Module`, `File` | `Implemented by`, `Future` |
+| `ADP` | `Implements` (a driven port) or `Drives` (use cases), `Technology`, `Module`, `File` | `Adopts` (library and adopt-or-build reason), `Format` (the stored or wire format it owns, or where its schema lives) |
+| `FLOW` | `Elements`, a Mermaid `sequenceDiagram` | `Serves` (SCN IDs, once they exist), `Failure paths` |
+| `MOD` | `Path`, `Layer` (`domain`, `application`, `adapter` or `composition`) | |
+| `RULE` | one or two sentences of rule | `Enforced by` (config layer names) |
+| `XC` | prose | |
+
+Rules for facts:
+
+- Membership is never listed twice. An element's scope names its context, and its `Module` fact names its module; contexts and modules don't list their members, so adding an element never changes them.
+- `File` names the real source path, one per element, with sub-items when an element spans files. Every element with code has one: an element without a file cannot be built, checked or reviewed.
+- `Operations` lists each operation as a sub-item with its signature in the project's language, then its contract: what it guarantees, its failure cases and who owns cleanup.
+- `Relationships` sub-items read `<verb> <ID> (<cardinality>)`, for example `- has one ENT-inventory.console-path (1)`.
+- `Future` records a seam kept open for a later release and the element it will need, so later features extend the design rather than rework it.
+- Add another fact when it helps a reader, such as `Failure attribution` on an adapter. The CLI checks the listed facts and ignores the others.
+- An element that grows over several features, such as the CLI adapter gaining a command per feature, gets a `MODIFIED` operation in each feature that extends it. Its status goes back to `planned` when that feature's first change lands, and to `built` when the change that builds the new text lands.
+- The CLI adds `- Status: planned` to a new element and flips it to `built` when a landed change builds it. Leave it out of what you write.
+
+## Diagrams
+
+- Every `FLOW` has one `sequenceDiagram`. Participants are element titles, and every participant's ID appears in the flow's `Elements`.
+- The Overview `VIEW` shows contexts, the inbound adapters that drive them and the external systems adapters reach.
+- A `VIEW-domain-model` class diagram in the Domain model section shows every `ENT` and its relationships.
+- Keep a diagram to at most 15 nodes. Split a bigger picture into two views.
+
+## Architecture delta
+
+A feature, or a standalone change, proposes architecture edits in its `## Architecture delta` section. Each operation is a `###` heading:
+
+```markdown
+### ADDED PORT-access.hop-connector: HopConnector
+- Direction: driven
+- ...the full element body, as it will read in architecture.md
+
+### MODIFIED UC-access.open-console: Open a console
+- ...the full new body, replacing the old one
+
+### REMOVED ADP-access.telnet-connector: Telnet connector
+- Reason: telnet support was dropped from the release scope
+```
+
+- `ADDED` introduces an ID that doesn't exist yet. `MODIFIED` replaces an existing element's whole body. `REMOVED` retires an ID and needs a `Reason`.
+- The element kind decides its section. `land` appends an added element to the end of its section.
+- A delta never touches `Status`. A change's `Builds` scope decides what becomes built.
+- A delta with no operations says `None.` under its heading.
+- Direct edits to `docs/architecture.md` happen only at project scope and through `rethink`. Every other design change arrives as a delta.

package/skills/formats/reference/config.md

@@ -0,0 +1,57 @@
+# Configuration format
+
+`.cruze/config.yaml` configures the CLI for one project. `cruze init` creates it. Project-scope architect fills in `source`, `tests` and `layers` from the module map.
+
+```yaml
+version: 1
+project: "Console Access"
+tracker: markdown
+
+source: ["src/**/*.rs"]
+tests: ["src/**/*.rs", "tests/**/*.rs"]
+
+check:
+  max_lines: 250
+  max_types: 5
+  exceptions:
+    - path: src/cli/args.rs
+      reason: the clap derive struct lists every flag in one place
+
+commands:
+  format: cargo fmt --check
+  lint: cargo clippy -- -D warnings
+  test: cargo test
+  run: cargo run -- list
+
+review:
+  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*) Bash(cargo:*)"]
+
+layers:
+  - name: inventory-domain
+    paths: ["src/inventory/domain/**"]
+    may_import: []
+  - name: inventory-app
+    paths: ["src/inventory/app/**"]
+    may_import: [inventory-domain]
+```
+
+| Key | Meaning |
+| --- | --- |
+| `version` | Format version. Always `1` for now. |
+| `project` | The project name, quoted. |
+| `tracker` | Where work items live. `markdown` is the only value in V1. |
+| `source` | Globs of the source files `cruze check` inspects. |
+| `tests` | Globs of the files `cruze trace` searches for scenario IDs. |
+| `check.max_lines` | Line budget per source file. |
+| `check.max_types` | Budget of top-level types per source file. |
+| `check.exceptions` | Files allowed past a budget, each with a `path` and a `reason`. |
+| `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
+| `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. |
+| `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. The default runs Claude Code in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. |
+
+Rules for layers:
+
+- A source file belongs to the first layer whose paths match it. A file in no layer may import anything, so every source file should be in a layer.
+- Imports of code outside the project, such as the standard library and dependencies, are always allowed. Adapter layers are where they belong, and review checks that.
+- A layer may import itself. Every other dependency is listed in `may_import`, and together they follow the `RULE` elements in the architecture.
+- Each `MOD` element's `Path` falls in exactly one layer, and the layer's `may_import` fits the module's `Layer`. A domain layer imports only domain layers, and nothing outside composition imports adapter layers.

package/skills/formats/reference/durable-docs.md

@@ -0,0 +1,71 @@
+# Vision, glossary, ADR and roadmap formats
+
+Templates: [../templates/vision.md](../templates/vision.md), [../templates/glossary.md](../templates/glossary.md), [../templates/adr.md](../templates/adr.md) and [../templates/roadmap.md](../templates/roadmap.md).
+
+## docs/vision.md
+
+What the product is for. At most one page, excluding the feature map.
+
+| Section | Holds |
+| --- | --- |
+| `## Problem` | The problem, in the user's words, in one short paragraph |
+| `## Users` | Who uses it and in what situation, one bullet each |
+| `## Goals` | Table of ID, Goal and Measure. Each goal is a row element with a `GOAL-<name>` ID, and its measure says how you would know it's met |
+| `## Non-goals` | What the product deliberately doesn't do, one bullet each with the reason |
+| `## Constraints` | Platforms, languages, dependencies, performance, security and legal limits, one bullet each |
+| `## Feature map` | Managed. `### Implemented` is a table of Feature, Release and Summary. `### Future` is a table of Feature, Summary and Goals |
+
+- Feature-map entries are named by slug, such as `jump-hosts`. A future entry gets a folder ID only when its feature starts.
+- Only the CLI writes the feature map. `cruze features add` puts an entry on the future list, `cruze features drop` removes one, and `land` moves a finished feature to implemented, tagged with the release in progress.
+
+## docs/glossary.md
+
+The shared language, with no implementation detail. Anyone may add a term the moment it settles. The glossary is not approval-gated.
+
+```markdown
+## Console access
+
+**Hop**: One link in the chain from the user to a device console: an SSH connection or a serial line.
+_Avoid_: jump, leg
+
+**Console path**: The ordered hops that reach one device's console.
+_Avoid_: route, connection string
+```
+
+- Group terms under a `##` heading per bounded context, alphabetically within each group.
+- A definition is one or two sentences, in terms a domain expert would accept.
+- `_Avoid_:` lists synonyms to stop using, so code, docs and conversation converge on one word.
+- A term used in docs or code but missing here is a signal. Either the term is new and belongs here, or someone is inventing language.
+
+## docs/adr/<date>-<slug>.md
+
+Write one only when a decision is hard to reverse, would surprise a newcomer, and was a real trade-off. Everything else is a settled decision: in a feature or change, or at project scope in the architecture's `## Decisions`.
+
+```markdown
+# Console paths are ordered hop chains
+
+- Status: accepted
+- Date: 2026-09-24
+- Elements: ENT-inventory.console-path, PORT-access.hop-connector
+
+<One paragraph: the context, the decision, why it won, and the alternatives rejected.>
+```
+
+- The ID is `ADR-<file stem>`, such as `ADR-2026-09-24-hop-chains`.
+- `Status` is `accepted` or `superseded by ADR-<stem>`. A superseded ADR stays; the new ADR says what changed.
+- Review never re-raises a decision covered by an accepted ADR without new evidence. Proposing to contradict one must name it: "Contradicts ADR-<stem>, worth reopening because…".
+
+## docs/roadmap.md
+
+The current release, as an index. It changes only when a feature or standalone change starts, finishes or is reordered.
+
+| Section | Holds |
+| --- | --- |
+| `## Release` | The release name and one sentence on what it delivers |
+| `## Phases` | One `### Phase <n>: <name>` per phase, each a table of Item (slug), Kind (`feature` or `change`), Goals and Blocked by |
+| `## Coverage` | Table of Goal and the items that serve it. Every goal in scope has at least one item |
+| `## Status` | Managed: each started item's folder ID and state (`designing`, `building` or `landed`). `cruze new` adds the row and `cruze land` updates it |
+
+- Items are named by slug. The first item of a new project is the `walking-skeleton` standalone change.
+- `Blocked by` lists slugs that must land first. The blocking graph has no cycles.
+- A new release replaces `## Release` and `## Phases`. Landed items leave the roadmap once the release closes; the feature map in the vision keeps the record.

package/skills/formats/reference/specs.md

@@ -0,0 +1,65 @@
+# Specs format
+
+`docs/specs/<capability>.md` holds the living behaviour of one capability, meaning what the system does as seen from outside. Requirements say what must hold. Scenarios are worked examples that become behaviour tests. Nothing in a spec names classes, files or libraries; those belong in the architecture.
+
+Template: [../templates/spec.md](../templates/spec.md).
+
+## Spec file
+
+```markdown
+# Console access
+
+Opening consoles on configured devices and running commands on them.
+
+## REQ-access.open-console: Open a device console
+The CLI SHALL connect the user's terminal to the console of a configured device, through every hop of its console path, and restore the terminal when the session ends.
+
+### SCN-access.direct-serial: Console on a local serial port
+- GIVEN device `lab-router` has console path `serial /dev/ttyUSB0 115200`
+- WHEN the user runs `consolectl open lab-router`
+- THEN the terminal shows the device's console output within 2 seconds
+- AND pressing `Ctrl-]` then `q` closes the session and restores the terminal
+```
+
+- The file name is the capability, and the capability is the scope of every ID in it.
+- One `#` title, then a purpose paragraph of one to three sentences.
+- Each requirement is a `##` heading element, `REQ-<capability>.<name>: <Title>`. Its body states the requirement in one to three sentences containing `SHALL` or `MUST`. Use `SHALL NOT` or `MUST NOT` for behaviour that must never happen.
+- Each scenario is a `###` heading element under its requirement, `SCN-<capability>.<name>: <Title>`. A requirement has at least one.
+
+## Scenario grammar
+
+- Bullets in order: zero or more `GIVEN`, one `WHEN`, one or more `THEN`. `AND` continues the clause above it.
+- Use concrete values: names, inputs, outputs, limits and times. The expected values are the test's oracle, worked out by hand. They are never copied from running the code.
+- One behaviour per scenario. Failure behaviour gets its own scenario, including what state is left behind.
+- The CLI adds a managed `- Status:` item. A scenario is `built` once a landed change delivered it with a passing test that names its ID.
+
+## Spec delta
+
+A feature, or a standalone change, proposes behaviour changes in its `## Spec delta` section. Operation headings sit at `###` and scenarios at `####`:
+
+```markdown
+### ADDED CAPABILITY inventory: Device inventory
+Reading and validating the configured devices and their console paths.
+
+### ADDED REQ-access.jump-host-chain: Connect through jump hosts
+The CLI SHALL reach a device's console through every SSH hop in its console path, in order.
+
+#### SCN-access.serial-behind-jump-host: Serial console on a jump host
+- GIVEN ...
+
+### MODIFIED REQ-access.open-console: Open a device console
+The full new requirement text.
+
+#### SCN-access.direct-serial: Console on a local serial port
+- ...every scenario the requirement keeps, in full
+
+### REMOVED REQ-access.telnet: Telnet consoles
+- Reason: telnet support was dropped
+- Migration: configure an SSH hop to a terminal server instead
+```
+
+- `ADDED CAPABILITY` creates a new spec file, with its title and purpose paragraph. It is only needed for a capability that has no file yet.
+- `ADDED` introduces a new requirement with all its scenarios.
+- `MODIFIED` replaces a requirement's whole block, including every scenario it keeps. A scenario left out is removed.
+- `REMOVED` retires a requirement and its scenarios, and needs a `Reason` and a `Migration`.
+- `land` shifts heading levels to fit the spec file and keeps the managed status of scenarios that were already built.

package/skills/formats/reference/work-items.md

@@ -0,0 +1,100 @@
+# Feature and change format
+
+Work in progress lives in `.cruze/`. A **feature** carries the design: its intent, its deltas and the ordered list of its changes. A **change** is one buildable slice: its scope, its test plan and its tasks. A small tweak is a **standalone change** that carries its own deltas. When work lands it is archived, and its deltas become part of the living docs.
+
+Templates: [../templates/feature.md](../templates/feature.md), [../templates/change.md](../templates/change.md) and [../templates/standalone-change.md](../templates/standalone-change.md).
+
+## IDs and folders
+
+- Features and standalone changes get an ID from `cruze new`: the creation date plus a slug, such as `2026-09-25-jump-hosts`. The CLI adds `-2` on a same-day clash.
+- A feature's changes are numbered inside the feature, as in `01-ssh-hop` and `02-serial-behind-hop`. The full reference is `<feature id>/<change>`.
+- Frontmatter holds `id`, `title` and, for features, `roadmap` (the roadmap item slug). A retry of an abandoned or superseded item adds `supersedes: <old id>`.
+
+## feature.md
+
+| Section | Holds |
+| --- | --- |
+| `## Intent` | The problem and outcome in the user's words, who it is for, constraints, and what is out of scope |
+| `## Settled decisions` | Decisions the user confirmed, one bullet each as `D<n>: <decision> (<reason>)`, including overrides of Cruze's advice |
+| `## Adopt or build` | Table of components that aren't domain logic, as Component, Decision (`adopt` or `build`), Choice and Reason |
+| `## Spec delta` | See [specs.md](specs.md) |
+| `## Architecture delta` | See [architecture.md](architecture.md) |
+| `## Changes` | Table of the ordered changes, as Change, Delivers, Builds, Removes (optional) and Depends on |
+| `## Progress` | Managed: state of each change, landed commits and the deviation log |
+
+## change.md
+
+| Section | Holds |
+| --- | --- |
+| `## Scope` | `- Delivers:` scenario and requirement IDs, `- Builds:` architecture IDs, `- Removes:` IDs retired by this change |
+| `## Test plan` | Table of Subject, Seam, Test file and Kind, one row per delivered scenario and per contract-tested port |
+| `## Tasks` | One task line per task, in build order |
+| `## Settled decisions` | Decisions made while planning this change, same format as the feature |
+| `## Risks` | What could break and the riskiest task, when there are any |
+| `## Progress` | Managed: ticked tasks with their commits, deviations and the bound branch |
+
+A standalone change adds `## Intent`, `## Adopt or build`, `## Spec delta` and `## Architecture delta` before its `## Scope`, in the same format as a feature's. Its scope covers every ID in its own deltas, plus any `planned` elements from the living docs that it builds.
+
+A feature is designed in two steps. Feature-scope `envision` writes the intent, settled decisions and spec delta, and leaves `## Architecture delta` as `None.` and the Changes table empty. `architect` writes the architecture delta and the changes. Until the Changes table has a row, `cruze validate` reports the feature as `not-designed` (a warning), skips the coverage rules, and `cruze approve` refuses it.
+
+`architect` writes a standalone change's design sections and its scope, and leaves the test plan table empty and the tasks section blank. Until `plan` fills them, `cruze validate` reports the change as `not-planned` (a warning), skips the task and test plan rules, and `cruze approve` refuses it.
+
+## Scope rules
+
+These rules close the gap between a design and what gets built. `cruze validate` checks them.
+
+- Every ID in a feature's deltas appears in the scope of exactly one of its changes. For a standalone change, that is its own scope. A `MODIFIED` or `REMOVED` requirement is covered by its ID or by one of its scenarios.
+- A scope may also name elements already in the living docs with status `planned`, such as a walking-skeleton change that builds elements the project architecture defined. An element with no status yet counts as planned: it appears only while the architecture has never been approved, so project-scope architect can write the walking skeleton before that first approval.
+- The first change of a feature to land merges the feature's whole delta, so the living docs never cite something a later change hasn't merged yet. What this change delivers or builds becomes `built`. Everything else arrives as `planned`, including a `MODIFIED` element whose new text isn't built yet. Each later change flips what it builds to `built`.
+- A `REMOVED` operation applies when the change whose scope lists it under `Removes` lands.
+- Under a `MODIFIED` requirement, a scenario must be in some change's scope when it is new or its text changed. An unchanged scenario the requirement keeps needs no change.
+- If someone else edits an element after this feature merged it, the next land refuses with a conflict instead of overwriting their edit. Resolve it with `rethink`.
+- The `Changes` table and each change's `Scope` agree. `plan` copies the row into the change and refines it; a disagreement is a validation error.
+
+## Test plan
+
+| Kind | Subject | Seam |
+| --- | --- | --- |
+| `behaviour` | a `SCN` ID | the use case it runs through, with a fake named for each driven port; or the inbound adapter, when the outcome is what that adapter shows, such as CLI output and exit codes |
+| `contract` | a `PORT` ID | the port, run against its fake and each real adapter |
+| `domain` | an `ENT` ID | the entity's own API, only for rules with real logic |
+| `smoke` | a `FLOW` ID | the real inbound adapter, end to end |
+
+Every delivered scenario has at least one `behaviour` row, and every port that a built adapter `Implements` has a `contract` row. The test file path is where the test will live. The subject ID appears in the test's name, or in a comment on the line directly above it when the language's names can't hold an ID. That is how `cruze trace` finds it.
+
+## Task lines
+
+```markdown
+- T1: `HopConnector` port in `src/access/app/ports/hop_connector.rs`, proves PORT-access.hop-connector
+- T2: `SshConnector` in `src/access/adapters/ssh_connector.rs`, proves PORT-access.hop-connector, SCN-access.ssh-through-jump-host
+```
+
+- Grammar: `- T<n>: <owner> in <path>[, <path>], proves <ID>[, <ID>]`. Owner and paths are in backticks.
+- One owner per task, and every path names a file the architecture assigns to that owner. Test support that no element owns, such as a shared fake, names its test file instead.
+- Every scenario the change delivers is proved by at least one task, and so is every `Builds` element. The exception is a `MOD`, which is proved by any task with a path inside the module's `Path`.
+- Tasks are design, not progress. Their checkboxes live in `## Progress`.
+
+## Progress
+
+The managed block the CLI maintains. `cruze approve` binds a change to the current branch, `cruze task done` ticks a task with its commit, `cruze task reopen` unticks one a rethink changed, `cruze task deviation` records a deviation, and `cruze land` records the date and the last commit of the change's work:
+
+```markdown
+<!-- cruze:managed -->
+## Progress
+- Branch: jump-hosts-ssh
+- [x] T1 (a1b2c3d)
+- [ ] T2
+- Deviation T1: moved `HopError` into `hop_connector.rs`; same owner, same module
+<!-- /cruze:managed -->
+```
+
+A deviation line records a task-level choice the agent made on its own. Anything larger goes through `rethink`.
+
+## Other files in a change folder
+
+- `manual-test.md`, written by `verify`: numbered steps a person runs against the real system, one section per delivered scenario, each with its expected result.
+- `approvals.json` and `journal.jsonl`, written only by the CLI.
+
+## Verification
+
+A change lands only after the user accepts it at `verify`, which records `cruze journal add verification --set result=accepted --set summary=<text> --item <ref>`. A later approval of the change keeps that acceptance only when the change's own design is unchanged. `cruze land --override <reason>` lands without it, and journals the reason.

package/skills/formats/templates/adr.md

@@ -0,0 +1,7 @@
+# <Decision, stated as a fact>
+
+- Status: accepted
+- Date: {{date}}
+- Elements: <IDs of the architecture elements this decision shapes>
+
+<One paragraph: the context that forced a decision, the decision, why it won, and the alternatives rejected.>

package/skills/formats/templates/architecture.md

@@ -0,0 +1,100 @@
+# Architecture: {{project_name}}
+
+## Overview
+
+<One paragraph: what the system is, how it is used, and the architectural style.>
+
+### VIEW-context: System context
+
+```mermaid
+flowchart LR
+  user([<User>]) --> cli[<Inbound adapter>]
+  cli --> ctx[<Bounded context>]
+  ctx --> ext[(<External system>)]
+```
+
+## Bounded contexts
+
+### CTX-<name>: <Context title>
+- Purpose: <what this context is responsible for>
+- Depends on: <CTX ID and what it uses, or "nothing">
+
+## Domain model
+
+### VIEW-domain-model: Domain model
+
+```mermaid
+classDiagram
+  class <Entity>
+```
+
+### ENT-<context>.<name>: <Entity title>
+- Kind: <aggregate | entity | value | service | policy | event>
+- Invariants:
+  - <a rule that always holds>
+- Relationships:
+  - <verb> <ENT ID> (<cardinality>)
+- Module: <MOD ID>
+- File: `<path>`
+
+## Use cases
+
+### UC-<context>.<name>: <Use case title>
+- Input: <what the caller provides>
+- Output: <what the caller gets>
+- Errors: <each failure the caller can see>
+- Uses: <PORT IDs>
+- Module: <MOD ID>
+- File: `<path>`
+
+## Ports
+
+### PORT-<context>.<name>: <Port title>
+- Direction: <driven | driving>
+- Operations:
+  - `<signature>`: <guarantee; failure cases; who owns cleanup>
+- Implemented by: <ADP IDs>
+- Module: <MOD ID>
+- File: `<path>`
+
+## Adapters
+
+### ADP-<context>.<name>: <Adapter title>
+- Implements: <PORT ID>
+- Technology: <library, protocol or system>
+- Adopts: <library, and why adopt rather than build>
+- Module: <MOD ID>
+- File: `<path>`
+
+## Flows
+
+### FLOW-<context>.<name>: <Flow title>
+- Serves: <SCN IDs>
+- Elements: <IDs of every participant>
+
+```mermaid
+sequenceDiagram
+  participant A as <Element title>
+```
+
+## Modules
+
+### MOD-<context>.<name>: <Module title>
+- Path: `<directory or file>`
+- Layer: <domain | application | adapter | composition>
+
+## Dependency rules
+
+### RULE-<name>: <Rule title>
+<One or two sentences stating what may depend on what.>
+- Enforced by: <config layer names>
+
+## Cross-cutting concerns
+
+### XC-<name>: <Concern title>
+<How the system handles it, and where.>
+
+## Decisions
+
+- ADR-<stem>: <one-line summary>
+- D1: <a project-level decision below the ADR bar> (<reason>)

package/skills/formats/templates/change.md

@@ -0,0 +1,29 @@
+---
+id: {{id}}
+title: {{title}}
+---
+
+# Change: {{title}}
+
+## Scope
+
+- Delivers: <SCN and REQ IDs>
+- Builds: <architecture element IDs>
+
+## Test plan
+
+| Subject | Seam | Test file | Kind |
+| --- | --- | --- | --- |
+| <SCN ID> | <UC ID> with fake <PORT IDs> | `<path>` | behaviour |
+
+## Tasks
+
+- T1: `<owner>` in `<path>`, proves <IDs>
+
+## Settled decisions
+
+- D1: <decision> (<reason>)
+
+<!-- cruze:managed -->
+## Progress
+<!-- /cruze:managed -->

package/skills/formats/templates/feature.md

@@ -0,0 +1,49 @@
+---
+id: {{id}}
+title: {{title}}
+roadmap: <roadmap item slug>
+---
+
+# Feature: {{title}}
+
+## Intent
+
+<The problem and outcome in the user's words. Who it is for. Constraints.>
+
+Out of scope:
+
+- <what this feature deliberately leaves out>
+
+## Settled decisions
+
+- D1: <decision> (<reason>)
+
+## Adopt or build
+
+| Component | Decision | Choice | Reason |
+| --- | --- | --- | --- |
+
+## Spec delta
+
+### ADDED REQ-<capability>.<name>: <Requirement title>
+<The requirement using SHALL or MUST.>
+
+#### SCN-<capability>.<name>: <Scenario title>
+- GIVEN <starting state>
+- WHEN <the one action>
+- THEN <observable outcome>
+
+## Architecture delta
+
+### ADDED <ID>: <Element title>
+- <the element's full body, as it will read in architecture.md>
+
+## Changes
+
+| Change | Delivers | Builds | Depends on |
+| --- | --- | --- | --- |
+| 01-<slug> | <SCN and REQ IDs> | <architecture IDs> | |
+
+<!-- cruze:managed -->
+## Progress
+<!-- /cruze:managed -->

package/skills/formats/templates/glossary.md

@@ -0,0 +1,8 @@
+# Glossary
+
+The shared language of {{project_name}}. Terms are grouped by bounded context, alphabetically within each group. Add a term the moment it settles.
+
+## <Context name>
+
+**<Term>**: <One or two sentences a domain expert would accept.>
+_Avoid_: <synonyms to stop using>