cadet-agent 0.21.0 → 0.25.0

package/README.md

@@ -2,43 +2,50 @@
 
 Cadet-Agent is an **opinionated** cross-IDE agent framework for game-development workflows. It is built on foundational software engineering practices and real-world game-development experience, with the goal of **guiding you through the entire development process** — from requirements and technical design through TDD, implementation, and review.
 
-Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished game from a single prompt. Instead, it walks you through each phase methodically: calibrating the learner model, scoping work into epics and stories, planning architecture, writing tests first, and iterating on feedback. The shared framework core integrates with GitHub Copilot, Cursor, Continue, and Claude Code.
+Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished game from a single prompt. Instead, it walks you through each phase methodically: calibrating the learner model, scoping work into epics and stories, planning architecture, writing tests first, and iterating on feedback. The shared framework core integrates with GitHub Copilot, Cursor, Continue, Claude Code, and Deep Code.
 
 ## Repository Layout
 - `.cadet/agent/core/` contains the shared Cadet-Agent framework documents.
   - `cadet-agent.md` is the thin global directive: identity, non-negotiable rules, workflow routing, hard-gate protocol, and skill dispatch.
-  - `skills/` contains scoped workflow-phase skills (Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview).
+  - `Harness.md` is the canonical harness contract: budgets, evidence-backed gates, retries, context tiers, tool routing, privacy, and escalation.
+  - `harness.schema.json` and `state.schema.json` are the machine-readable schemas for harness records and session state.
+  - `skills/` contains scoped workflow-phase skills (Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer).
   - `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).
 - `.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.).
 - `.cursor/` contains Cursor-specific authored files.
 - `.continue/` contains Continue-specific authored files.
 - `.claude/` contains Claude Code-specific authored files.
+- `.agents/skills/` contains Deep Code (and cross-client) skill adapters.
 - These IDE folders hold thin integration shims; the core framework logic still lives in `.cadet/agent/core/`.
 - `package-agent.ps1` builds the distributable `cadet-agent.zip` package.
 - `publish-npm.ps1` publishes the CLI to npm using a token from `~/.npm_token`.
 
 ## Cross-IDE Support
 
-Cadet-Agent provides full workflow parity across four IDEs. The same 7 skills + resume + reviewer are available in each:
-
-| Feature | GitHub Copilot | Cursor | Continue | Claude Code |
-|---|---|---|---|---|
-| Auto-load rules | Agent definition | `alwaysApply` rule | Project rule | Project skill |
-| Skill dispatch | `/cadet-<skill>` prompts | Natural language | `/cadet-<skill>` commands | `/cadet-<skill>` skills |
-| Requirements | ✅ | ✅ | ✅ | ✅ |
-| Architecture | ✅ | ✅ | ✅ | ✅ |
-| Spike | ✅ | ✅ | ✅ | ✅ |
-| Story Breakdown | ✅ | ✅ | ✅ | ✅ |
-| TDD | ✅ | ✅ | ✅ | ✅ |
-| Debugging | ✅ | ✅ | ✅ | ✅ |
-| Code Review | ✅ | ✅ | ✅ | ✅ |
-| Resume | ✅ | ✅ | ✅ | ✅ |
-| Reviewer mode | Agent picker | Rule toggle | `/cadet-agent-reviewer` | `/cadet-agent-reviewer` |
-| Git guard | PreToolUse hook | Manual | Manual | Manual |
-
-All adapters delegate to the canonical files under `.cadet/agent/core/` — no duplicated rules or skills. See `ADAPTERS.md` for the full inventory.
+Cadet-Agent provides full workflow parity across five IDEs. The same 9 skills + reviewer are available in each:
+
+| Feature | GitHub Copilot | Cursor | Continue | Claude Code | Deep Code |
+|---|---|---|---|---|---|
+| Auto-load rules | Agent definition | `alwaysApply` rule | Project rule | Project skill | Project skill (`.agents/skills/`) |
+| Skill dispatch | `/cadet-<skill>` prompts | Natural language | `/cadet-<skill>` commands | `/cadet-<skill>` skills | `/skills` menu (`/`) |
+| Requirements | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Architecture | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Spike | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Story Breakdown | ✅ | ✅ | ✅ | ✅ | ✅ |
+| TDD | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Debugging | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Code Review | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Resume | ✅ | ✅ | ✅ | ✅ | ✅ |
+| MCP Setup | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reviewer mode | Agent picker | Rule toggle | `/cadet-agent-reviewer` | `/cadet-agent-reviewer` | `cadet-agent-reviewer` skill |
+| Git guard | PreToolUse hook | Manual | Manual | Manual | `permissions.ask` (`mutate-git-log`) |
+
+All adapters delegate to the canonical files under `.cadet/agent/core/` — no duplicated rules or skills. See `ADAPTERS.md` for the full inventory and `docs/guidance/DeepCode.md` for Deep Code setup.
 
 ## Quick Install
 
@@ -58,7 +65,7 @@ npx cadet-agent@latest init --target ./my-unity-project
 npx cadet-agent@latest sync
 ```
 
-When a new release is available, `sync` downloads the updated framework and replaces managed files (`.cadet/agent/core/`, IDE integration shims, agent definitions). Your local policies (`.cadet/agent/policies/`) and project plans (`.cadet/agent/project-plans/`) are automatically preserved. After syncing, start a fresh chat for the changes to take effect.
+When a new release is available, `sync` downloads the updated framework and replaces managed files (`.cadet/agent/core/`, IDE integration shims, agent definitions). Your local policies (`.cadet/agent/policies/`), project plans (`.cadet/agent/project-plans/`), harness overrides (`.cadet/harness.json`), and run ledgers (`.cadet/runs/`) are automatically preserved. After syncing, start a fresh chat for the changes to take effect.
 
 To sync a specific directory:
 
@@ -66,6 +73,20 @@ To sync a specific directory:
 npx cadet-agent@latest sync --target ./my-unity-project
 ```
 
+#### AGENTS.md is create-only
+
+Cadet ships a repository-root `AGENTS.md` (a thin pointer to `.cadet/agent/core/cadet-agent.md`). If your repo already has one, Cadet **never overwrites it**:
+
+- In a terminal, `init`/`sync` ask whether to keep, overwrite, or merge (default: keep).
+- Non-interactive installs (CI, `--yes`, piped output) always **keep** and print a tag-pinned link to Cadet's copy.
+- Control it explicitly with `--agents-md keep|overwrite|merge`.
+- `merge` inserts Cadet's text between `<!-- cadet-agent:begin -->` / `<!-- cadet-agent:end -->` markers and leaves the rest of your file untouched.
+
+```bash
+npx cadet-agent@latest sync --agents-md keep       # never touch an existing AGENTS.md
+npx cadet-agent@latest sync --yes                  # non-interactive; keeps existing files
+```
+
 ## Manual Install (fallback)
 
 If you prefer to install from a packaged release artifact, download `cadet-agent.zip` from [GitHub Releases](https://github.com/naishtech/cadet-agent/releases) and extract it into your Unity project root:
@@ -128,7 +149,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. 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 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`.
 
 ### Phase Gating
 
@@ -140,6 +161,36 @@ Hard gates are enforced at every phase transition. The agent reads `.cadet/state
 | review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated` |
 | validation → closed | `designArtifactSyncConfirmed` |
 
+### Harness
+
+Gates are backed by **evidence**, not assertion. Each claimed gate must have a fresh, non-superseded evidence record bound to the current work item, input tree hash, and acceptance criteria. The harness also bounds context, tokens, tool calls, retries, wall-clock time, cost, and archive sizes — and those bounds are enforced, not advisory.
+
+- Rules: `.cadet/agent/core/Harness.md`. Data contract: `docs/core/HarnessContract.md`.
+- Overrides: `.cadet/harness.json` (preserved by sync; conservative defaults in `src/harness/policy.mjs`).
+- Ledgers: `.cadet/runs/<runId>.json` (sanitized; artifacts are redacted before they are written; no secrets or raw prompts by default).
+- Transitions recompute the input tree hash from the evidence's relevant files, so editing a relevant file invalidates the evidence.
+- `harness verify` binds evidence to `--files` (or the working tree's changed files), and a `testsPassed` green result requires a prior red record.
+- When Git is unavailable and no `--files` are given, verification blocks (`freshness-unavailable`) rather than recording unscoped evidence.
+- `state validate` rejects a `true` gate whose evidence is missing, stale, expired, superseded, or bound to another work item; evidence records are schema-validated in full (`command`, `result`, `criteriaHash`, and a freshness bound).
+- 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`.
+- 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.
+
+```bash
+cadet-agent state validate                       # validate state against the schema
+cadet-agent state migrate                        # atomically upgrade v1 → v2
+cadet-agent state transition --to review         # enforce the matrix + evidence
+cadet-agent harness verify --gate testsPassed --files src/a.cs   # bounded, classified loop
+cadet-agent harness report                       # budget consumption and failures (no secrets)
+cadet-agent harness cleanup                      # apply the retention policy
+cadet-agent harness capabilities                 # available CLI/Unity/MCP/hook/token/cost telemetry
+```
+
+Every command supports `--format human|json` and exits nonzero for invalid state, failed verification, budget exhaustion, stale evidence, or safety rejection.
+
+See `docs/guidance/HarnessTroubleshooting.md` for stale evidence, budget exhaustion, unavailable Unity CLI, and live MCP connection failures.
+
 ## Examples
 
 ### GitHub Copilot
@@ -191,6 +242,26 @@ Create a requirements outline for a single-player time-trial mode with ghost rep
 
 The Continue rule in `.continue/rules/cadet-agent.md` should steer the response back through the shared Cadet framework.
 
+### Deep Code request
+With [Deep Code](https://deepcode.vegamo.cn/) installed (`npm install -g @vegamo/deepcode-cli`), run `deepcode` in the repository and use `/skills` to confirm the `cadet-*` skills are discovered from `.agents/skills/`. Then pick a phase skill from the `/` menu (there is no `/cadet-<skill>` command — select it by name, or ask for the phase in plain language):
+
+```text
+Run the TDD skill for the ghost-replay story.
+```
+
+Because Deep Code has no PreToolUse hook, enforce the commit/push approval gate in `.deepcode/settings.json`:
+
+```json
+{
+  "permissions": {
+    "ask": ["mutate-git-log", "network"],
+    "defaultMode": "askAll"
+  }
+}
+```
+
+See `docs/guidance/DeepCode.md` for the full setup, MCP wiring, and configuration reference.
+
 ### Repository policy example
 If a specific game repository needs local conventions, add a policy file under `.cadet/agent/policies` using `.cadet/agent/core/Templates/PolicyTemplate.md`. For example, a repository policy could define:
 - where project plans should live
@@ -199,7 +270,7 @@ If a specific game repository needs local conventions, add a policy file under `
 
 ## Package Output
 Running `./package-agent.ps1` produces `cadet-agent.zip` with this layout:
-- `.cadet/agent/core/`
+- `.cadet/agent/core/` (including `Harness.md`, `harness.schema.json`, and `state.schema.json`)
 - `.cadet/agent/core/skills/`
 - `.cadet/agent/core/templates/`
 - `.github/agents/cadet.agent.md`
@@ -207,8 +278,12 @@ Running `./package-agent.ps1` produces `cadet-agent.zip` with this layout:
 - `.github/prompts/cadet-*.prompt.md`
 - `.github/hooks/`
 - `.cursor/rules/cadet-agent.md`
+- `.cursor/rules/cadet-agent-reviewer.md`
 - `.continue/rules/cadet-agent.md`
-- `.claude/skills/cadet-agent.md`
+- `.continue/rules/cadet-agent-reviewer.md`
+- `.continue/config.yaml`
+- `.claude/skills/cadet-agent/SKILL.md`
+- `.claude/skills/cadet-*/SKILL.md`
 
 ## Notes
 - `.cadet/agent/core/FrameworkManifest.json` defines the managed and preserved paths for packaged installs.

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "cadet-agent",
-  "version": "0.21.0",
-  "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
-  "type": "module",
-  "bin": {
-    "cadet-agent": "bin/cli.mjs"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/"
-  ],
-  "keywords": [
-    "cadet",
-    "cadet-agent",
-    "unity",
-    "game-development",
-    "ai-agent",
-    "copilot",
-    "cursor",
-    "claude-code"
-  ],
-  "license": "CC-BY-4.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/naishtech/cadet-agent.git"
-  },
-  "homepage": "https://github.com/naishtech/cadet-agent#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "cadet-agent",
+  "version": "0.25.0",
+  "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
+  "type": "module",
+  "bin": {
+    "cadet-agent": "bin/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "cadet",
+    "cadet-agent",
+    "unity",
+    "game-development",
+    "ai-agent",
+    "copilot",
+    "cursor",
+    "claude-code"
+  ],
+  "license": "CC-BY-4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naishtech/cadet-agent.git"
+  },
+  "homepage": "https://github.com/naishtech/cadet-agent#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}