truecourse 0.6.0-next.1 → 0.6.0-next.10

package/README.md

@@ -193,6 +193,8 @@ truecourse verify                       # Check code against the contracts → d
 
 Resolve conflicts and review drifts visually in the [dashboard](#dashboard-web-ui)'s BL Drift section, or drive every step from the CLI.
 
+> Like `analyze`, the spec → contracts → verify track requires a **git repository** — TrueCourse's baselines are commit-anchored (committable `LATEST.json`, diff vs HEAD, stashing the committed state). On a non-git folder these commands stop with a clear message and the dashboard hides their actions.
+
 ## How it works
 
 Three stages run in order, each producing artifacts the next consumes:
@@ -254,17 +256,22 @@ truecourse spec docs uninclude <path>
 
 # Contract extraction (canonical spec → .tc artifacts)
 truecourse contracts generate                     # Extract / re-extract TC contract files
-truecourse contracts list                         # List generated contracts
+truecourse contracts list                         # List artifacts (kind · identity · location)
+truecourse contracts list --inferred / --authored # Only reverse-engineered (_inferred/) / only authored
 truecourse contracts validate                     # Parse + resolve TC files; report unresolved refs
 
 # Verification (code against contracts)
 truecourse verify                                 # Full run: stashes dirty tree (prompts), writes verifier/runs + LATEST + history
 truecourse verify --diff                          # Git diff: working-tree drifts vs committed baseline (added/resolved/unchanged)
 truecourse verify --stash / --no-stash            # Pre-approve / skip stashing on a full run
+truecourse drifts list                            # List drifts from the latest verify (paginated; reads LATEST, no re-run)
+truecourse drifts list --all                      # Show every drift (no pagination)
+truecourse drifts list --offset 20 / --severity critical,high  # Page through / filter by severity
 
 # Inference (code → inferred contracts) — reverse-engineer undocumented decisions
 truecourse infer                                  # Write inferred .tc files to contracts/_inferred/
 truecourse infer --dry-run                        # Report what would be written, touch nothing
+truecourse contracts list --inferred              # Review what infer produced (kind · confidence · code location)
 ```
 
 ---
@@ -316,7 +323,31 @@ The first `truecourse analyze` (or `truecourse add`) in a fresh repo asks whethe
 ## Prerequisites
 
 - Node.js >= 20
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI on your PATH. Deterministic rules run without it; LLM-powered rules and the Spec → Verify pipeline need it.
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI on your PATH — optional. The default `cli` transport spawns it for LLM-powered work; deterministic rules and the `agent` transport (below) don't need it.
+
+## LLM transport (`--llm-transport`)
+
+Every LLM-powered step — `analyze`'s LLM rules, and the whole Spec → Verify pipeline (`spec scan`, `spec resolve`, `contracts generate`) — reaches the model through a pluggable **transport**, chosen with `--llm-transport`:
+
+| Mode | How it reaches the model | Needs |
+|---|---|---|
+| **`cli`** *(default)* | spawns `claude -p …` per call | the `claude` binary on PATH, signed in. No API key. |
+| **`agent`** | a **filesystem mailbox** under `--io <dir>` | nothing — no `claude` binary, no API key |
+
+In **`agent`** mode the tool doesn't call the model itself: for each prompt it writes `requests/<id>.json` (`{ stage, system, user, schema, … }`) into the `--io` directory and waits for a matching `responses/<id>.json` (`{ text }`). An **orchestrating agent that is itself an LLM** — e.g. a [Claude Code routine](https://code.claude.com/docs/en/routines) — watches that directory and answers each prompt. This lets contract generation and `analyze`'s LLM rules run **inside a headless cloud session with no `claude` binary and no API key**.
+
+```bash
+# default: spawn the claude CLI
+truecourse analyze --llm
+truecourse contracts generate
+
+# agent transport: the tool parks prompts in ./io and an external agent answers them
+truecourse analyze --llm --llm-transport agent --io ./io
+truecourse spec scan          --llm-transport agent --io ./io
+truecourse contracts generate --llm-transport agent --io ./io
+```
+
+Accepted by: `analyze`, `spec scan`, `spec resolve`, `contracts generate`. (On `analyze`, `--llm` / `--no-llm` is a *separate* flag — it decides **whether** LLM rules run; `--llm-transport` decides **how** to reach the model.) Both modes send identical prompts and parse identical schema-validated JSON — only the delivery differs.
 
 ## Configuration
 
@@ -359,7 +390,7 @@ Patterns are anchored to the file's location, so `src/generated/` matches the to
 
 ## Telemetry
 
-TrueCourse collects anonymous usage data (event type, language, file count range, OS) to improve the product. No source code, file paths, or violation details are collected. It is automatically disabled in CI environments.
+TrueCourse collects anonymous usage data to improve the product — one event per command (`analyze`, `spec_scan`, `contracts_generate`, `verify`, `infer`), each carrying only coarse, bucketed counts (file/artifact/drift/decision *ranges*, duration range), the surface (CLI vs dashboard), OS, and tool version. No source code, file paths, identities, or violation/drift details are collected. It is automatically disabled in CI environments.
 
 ```bash
 truecourse telemetry status           # Check telemetry status