cadet-agent 0.60.0 → 0.63.1

package/README.md

@@ -13,7 +13,7 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
   - `templates/` contains runtime templates for planning artifacts.
 - `.cadet/harness.json` holds repository-local budget/policy overrides (preserved by sync).
 - `.cadet/runs/` holds sanitized run ledgers (preserved by sync; no secrets or raw prompts by default).
-- `src/harness/` contains the dependency-free harness implementation (policy, budget, state, verification, context, routing, redaction, ledger, archive, hook).
+- `src/harness/` contains the harness implementation (policy, budget, state, verification, context, routing, redaction, ledger, archive, hook, C# scan and diagram generation). Its one runtime dependency is `nomnoml`, the UML renderer used by `harness diagram` — see [Component diagrams](#component-diagrams).
 - `.cadet/agent/docs/` contains setup guides for each supported IDE.
 - `.github/agents/` contains the Copilot custom agent definitions (Cadet Agent + Cadet Agent Reviewer).
 - `.github/prompts/` contains Copilot slash-command skill prompts (`/cadet-review`, `/cadet-tdd`, etc.).
@@ -163,7 +163,7 @@ flowchart TD
 
 ### Resuming a Session
 
-Use the `/cadet-resume` slash command to pick up where you left off. It reads `.cadet/state.json` and reports the current phase, epic/story progress, and outstanding gates — then dispatches the right skill for the next step. It also checks the current branch and working tree, so leftover changes from a previous task are resolved (commit, stash, push, or move to a new branch) before a new task begins. If no state file exists, it initializes a fresh session from `context-resolution`.
+Use the `/cadet-resume` slash command to pick up where you left off. It runs `cadet-agent state brief`, the tier-0 summary of `.cadet/state.json`, and it checks the document with `cadet-agent state validate`. The brief prints the phase, the active work item, every gate with its newest evidence record, and the legal edge out of the current phase. A session therefore opens a bounded summary, not a record that grows with the project — the document also holds every work item ever closed and every change checkpoint ever recorded. It also checks the current branch and working tree, so leftover changes from a previous task are resolved (commit, stash, push, or move to a new branch) before a new task begins. If no state file exists, it initializes a fresh session from `context-resolution`.
 
 ### Phase Gating
 
@@ -173,8 +173,8 @@ Hard gates are enforced at every phase transition. The agent reads `.cadet/state
 |---|---|
 | architectureComplete → story-breakdown | `designReviewCompleted` when `designReview.enabled` is set — the formal design review, recorded by `harness verify-design-review` |
 | implementation → review | `testsPassed`, `compileCheckConfirmed`, `unityAnalyzerClean`, `storyTrackingUpdated`, and `architectureFitnessPassed` when the project declares architecture checks and enables them |
-| review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated`, `reachabilityAddressed` when `reachability.enabled` is set, and `userPlaythroughConfirmed` when `userPlay.enabled` is set — a story declares `Play: required — <what the user does and what they see>` or `Play: deferred to <work item> — <why>`. A person's own record satisfies `required` (`harness play-form` writes the form, `harness confirm --artifact` records it); `harness verify-play` records `deferred`, and the deferral expires when the named work item closes |
-| validation → closed | `designArtifactSyncConfirmed`, and `humanAcceptanceConfirmed` when `humanAcceptance.enabled` is set — a person's own record (`harness acceptance-form` writes the form, `harness confirm --artifact` records it); no command can produce it |
+| review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated`, `reachabilityAddressed` when `reachability.enabled` is set, and `userPlaythroughConfirmed` when `userPlay.enabled` is set — a story declares `Play: required — <what the user does and what they see>` or `Play: deferred to <work item> — <why>`. A person's own answer satisfies `required` (ask them, then `harness confirm --gate userPlaythroughConfirmed --reason "<their answer>"`); `harness verify-play` records `deferred`, and the deferral expires when the named work item closes |
+| validation → closed | `designArtifactSyncConfirmed`, and `humanAcceptanceConfirmed` when `humanAcceptance.enabled` is set — a person's own answer, recorded with `harness confirm --gate humanAcceptanceConfirmed --reason "<their answer>"`; no command can produce it |
 
 ### Runtime context protocol (opt-in, and the framework's own claim discipline)
 
@@ -191,7 +191,9 @@ The full set of legal transitions is the three gated rows above **plus** the ung
 
 ### The response contract
 
-The framework's only per-reply output is one line: `cadet-agent: ok`, or the problem in its place. `cadet-agent harness status` derives that line — read-only — from the state document and the run ledger, so it cannot claim a health nothing verified. `ok` means the record is readable, valid and fresh, and no recorded run stopped on a budget or failed to run. A gate that is unmet because the story is unfinished is normal, and is not reported. The rest of a reply carries the work: the decisions taken, what changed, what the checks show, and what is unverified or deferred.
+The framework's only per-reply output is one line: `cadet-agent: ok`, or the problem in its place. `cadet-agent harness status` derives that line — read-only — from the state document and the run ledger, so it cannot claim a health nothing verified. `ok` means the record is readable, valid and fresh, and no recorded run stopped on a budget or failed to run. A gate that is unmet because the story is unfinished is normal, and is not reported.
+
+The rest of a reply carries the work, in Simplified Technical English (ASD-STE100). What it must carry is set by **what it reports**, not by the phase: a change to the software — lead with what the software now does that it did not before, in the product's own terms; a change to a plan artifact — what the plan now says, the decisions taken, the alternatives rejected and why; a measurement or an investigation — the question, the number, and what it does not settle; a review verdict — met, not met, or met in part; or nothing new — the answer, then the reasoning, then what it depends on. A reply that changed the repository also carries three **invariants**, whichever subject it leads with: **files** — one line per changed file, path first, taken from `cadet-agent harness changes` rather than from memory; **checks** — red before green, compile, analyzer, verdict; and **owed** — what is unverified, deferred, or waiting on the reader. The file list is the reply's only list, and it is required: it is how the reader finds the change in his IDE. A record id never appears alone — `AC-65 (the match-end banner — the world stops and the player is told)`.
 
 ### Harness
 
@@ -209,11 +211,13 @@ Gates are backed by **evidence**, not assertion. Each claimed gate must have a f
 - A `changeHistory` entry is a pointer, not a retelling: it is limited to 400 characters, and `state compact` archives a longer entry in place rather than truncating it.
 - Evidence must include a UUID, work item, phase, gate, status, command/result, input-tree hash, criteria hash, relevant files, timestamp, and either `expiresAt` or `freshnessPolicy`.
 - **Evidence history does not live in `state.json`.** A v4 document keeps only the active work item's records inline; a closed work item's evidence is written into the commit that closes it, as `Cadet-*` trailers, and archived to `.cadet/archive/`. `evidenceCoverage` indexes what left, so the "a done story owns evidence" check still works offline. Cadet still never commits: `state seal` prepares a message file and you commit with `git commit -F`.
+- **Tier 0 loads the state brief, not the state document.** `cadet-agent state brief` prints the phase, the active work item with its story and epic status, every gate with its newest evidence record, and what compaction would archive; `harness context plan` writes it to `.cadet/context/state-brief.md` and names it at tier 0, hashed like any other required reference. The document is not the current story — it also holds every work item ever closed and every change checkpoint ever recorded, so it grows with the project and never shrinks. On a real consumer it reached 94,547 B, about 31,500 tokens, of which the current story was 31%; the brief for that same document was 1,745 B.
 - **Two gates are human-owned: `humanAcceptanceConfirmed` and `userPlaythroughConfirmed`.** No
-  command can produce them, and `--command` is refused for them. `harness acceptance-form --epic <id>`
-  and `harness play-form --story <path>` write the form; `harness confirm --gate <gate> --artifact <form>`
-  records what the person wrote. A form still holding a placeholder is refused, and a form someone has
-  started is never overwritten.
+  command can produce them, and `--command` is refused for them. ASK the person — for a playthrough,
+  whether they played it and what was unexpected; for an acceptance, whether they accept the work and
+  what they saw — and record their own answer with `harness confirm --gate <gate> --reason "<what they
+  said>"`. There is no form: the record is the person's sentence, and a record with no answer in it is
+  refused when it is written and again when the state is validated.
 - Command output counts against the output budget; a configured cost budget cannot be satisfied by unmeasurable cost (the run is blocked, `budget-blocked`).
 - State and run ledgers are written atomically, so an interrupted write cannot truncate a record; persisted artifacts are redacted before hashing or writing.
 - Empty freshness coverage is an explicit policy decision: set `allowEmptyFreshness: true` in `.cadet/harness.json` only when unscoped evidence is acceptable.
@@ -235,9 +239,7 @@ cadet-agent harness verify-reachability --story <path>           # check the dec
 cadet-agent harness verify-design-review --artifact <path> --files <design,requirements,ADRs>
 cadet-agent harness verify-architecture          # run the project's declared fitness checks
 cadet-agent harness verify-play --story <path>   # check a story's `Play:` declaration; record a deferral
-cadet-agent harness play-form --story <path>     # write a user-playthrough form for a person to fill
-cadet-agent harness acceptance-form --epic <id>  # write the epic's human-acceptance form
-cadet-agent harness confirm --gate <gate> --artifact <form>      # record a person's own account
+cadet-agent harness confirm --gate <gate> --reason "<answer>"    # record a person's own answer
 cadet-agent harness changes                      # the files a story changed, with links (read-only)
 cadet-agent harness report                       # budget consumption and failures (no secrets)
 cadet-agent harness reconcile                    # reconcile the planning chain against state.json (read-only)
@@ -246,6 +248,8 @@ cadet-agent harness context plan|record|validate # plan what a phase loads, reco
 cadet-agent harness cleanup --older-than-ms <n>  # apply the retention policy (bound required)
 cadet-agent harness capabilities                 # available CLI/Unity/MCP/hook/token/cost telemetry
 cadet-agent harness capabilities --verify-host   # probe the configured interception, per action
+cadet-agent harness diagram                      # render UML component diagrams per package, coloured by progress
+cadet-agent harness verify-diagrams              # check the committed diagram tree is current (read-only)
 ```
 
 Every command supports `--format human|json` and exits nonzero for invalid state, failed verification, budget exhaustion, stale evidence, or safety rejection.
@@ -266,6 +270,30 @@ cadet-agent harness record --dry-run             # reports what it would write,
 
 See `docs/guidance/HarnessTroubleshooting.md` for stale evidence, budget exhaustion, unavailable Unity CLI, and live MCP connection failures.
 
+## Component diagrams
+
+`cadet-agent harness diagram` renders the C# structure as UML component diagrams — one per (package × epic) — and colours every component by how far its work has progressed: **red** not started, **amber** in progress, **green** done.
+
+The picture is the record, not a separate map to maintain. Progress is read from `.cadet/state.json` and the evidence archive, joined to the files each story's evidence bound (`relevantFiles`).
+
+- **Packages** come from Unity `.asmdef` assembly definitions and their `references`, falling back to top-level folders when a tree has none. Unity test assemblies are left out by default; pass `--include-tests` to keep them.
+- **Components** are the namespaces inside a package.
+- **Scope** is the components the epic touched, plus their one-hop dependencies; anything else is reported as an elided count, so a package stays readable however large it grows.
+- **Colour is cumulative.** A component shows its progress across *all* epics, so a component finished by one epic is green in every diagram, not only the one that finished it.
+- **Drill down.** Click any component box to open that component's page: the files it owns (linked to source), the types it declares, what it depends on and is used by, and the stories that touched it.
+
+The generator writes a self-contained tree under `.cadet/diagrams/`: an `index.html` at the root, an `index.html` per package, a page per component, and a `.noml` (the UML source — the portable, testable artifact) plus a `.svg` per (package × epic). Open `.cadet/diagrams/index.html` to navigate. Rendering is done by [nomnoml](https://github.com/skanaar/nomnoml) (MIT), the CLI's only runtime dependency; no browser, Java, or CDN is involved.
+
+```bash
+cadet-agent harness diagram                       # default output: .cadet/diagrams
+cadet-agent harness diagram --package Cadet.Core  # one package only
+cadet-agent harness diagram --include-tests       # keep Unity test assemblies
+cadet-agent harness diagram --out ./docs/diagrams # somewhere else
+cadet-agent harness verify-diagrams               # is the committed tree still current?
+```
+
+The tree is **committed** and is part of closure: the CodeReview skill regenerates it once the story and epic records are updated, and `harness reconcile` reports a blocking `diagram-drift` finding when it no longer matches — which is what `designArtifactSyncConfirmed` refuses closure on. `harness verify-diagrams` is the read-only check for CI.
+
 ## Examples
 
 ### GitHub Copilot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadet-agent",
-  "version": "0.60.0",
+  "version": "0.63.1",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {
@@ -33,5 +33,8 @@
   "homepage": "https://github.com/naishtech/cadet-agent#readme",
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "nomnoml": "^1.7.0"
   }
 }