usesteady 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -1,724 +1,133 @@
-# usesteady-core-v2
+# UseSteady — Review AI actions before they run
 
-UseSteady V1 — controlled refactor engine with step-by-step approval and full audit trail.
-
-**Core system:** deterministic intake + understanding engine, Cursor and Claude execution runtimes, multi-step workflow coordinator, CLI shell, React web UI, and history/audit layer. No LLM in the control path. No cloud dependency.
-
----
-
-## What this does in one sentence
-
-Given a natural-language input and a session context, the system returns one of five verbs: **refuse, ignore, clarify, guide, or execute** ? plus structured data explaining why.
-
-Natural language never executes directly. Ever.
-
----
-
-## Build phases
-
-| Phase | Name | Status |
-|-------|------|--------|
-| 1 | Intake — PRV, Safety, Context Alignment, Disambiguation, Completion | ✅ Locked |
-| 2–3 | Understand — Intent Interpretation Bridge, interpreter system | ✅ Locked |
-| 4 | UCP Core — canonical envelope format, hashing, persistence, provenance chain | ✅ Locked |
-| 4C | Silent Guidance — selector expansion (operation + investigation), evidence loop | ✅ Locked |
-| 5 | Present Layer — reminder presentation, formatIntakeResult, presentFromInput | ✅ Frozen |
-| 5B | Control Visibility (CVG) — authority-signal classifier, assertion layer | ✅ Baseline locked |
-| 5C | Boundary Explanation — why-routing surfaced to H | ✅ Baseline locked |
-| 5D | Cross-layer Contradiction Visibility | ✅ Baseline locked |
-| 6 | Execution Layer — Cursor seam (artifact → gate → adapter) | ✅ Locked |
-| 6B | Cursor Product Session — phase state machine, terminal guards, session invariants | ✅ Baseline locked |
-| 6C | Session Resilience — interruption handling, partial-session recovery | ✅ Baseline locked |
-| 7 | UCP Alignment — cursor envelope types, timeline, provenance chain extension | ✅ Locked |
-| 8A | Claude Managed Agents — seam design, authority model, tool policy | ✅ Phase A frozen |
-| 8B | Claude Delivery Gate — ClaudeAgentPlugin, handoff persistence, stub adapter | ✅ Baseline locked |
-| 8C | Claude API Adapter — real Anthropic client behind ClaudeAgentPlugin interface | ✅ Baseline locked |
-| 8D | Claude Product Session — session wiring, parity with Cursor path | ✅ Baseline locked |
-| 9A–9F | Product Shell — CLI, workflow coordinator, workflow shell, UCP persistence | ✅ Frozen |
-| 10A–10C | History / Audit — two-tier read model, history shell | ✅ Frozen |
-| 11B–11C | Product Slice Validation — Safe Refactor Workflow, CLI surface validation | ✅ Frozen |
-| 11D | UI Design — reviewing phase, raw input anchor, targetFiles scope | ✅ Frozen |
-| 11A-Web | Web UI — React shell on frozen contracts, Express API bridge | ✅ Frozen |
-| 11E | Workflow Builder — natural-language entry model | ✅ Frozen |
-| 12 | Simulation — persona-based validation across all interaction states | ✅ Passed |
-
-**Correctly deferred (not yet built):**
-reminder scheduler / persistence, timezone resolution,
-`cursor_artifact.v1`, `ucp.claude_session.v1`, `ucp.claude_result.v1`,
-Session 7 vocabulary validation, `networkAccess: "allow_limited"` semantics,
-Claude session resumability, mobile layout.
-
----
-
-## Core pipeline
-
-Every input passes through the same sequence. No step is skipped. No step can be reordered.
+UseSteady shows you exactly what AI will do — before it executes anything.
 
 ```
-input + context
-    ?
-    ?
-  PRV                         ? Is this input obviously missing required prior state?
-    ? clarify if yes
-    ?
-  Safety Gate                 ? Is this input unsafe to process at all?
-    ? refuse if yes
-    ?
-  Context Alignment           ? Is this a social message or a context reference with no context?
-    ? ignore / clarify if yes
-    ?
-  Disambiguation              ? Does this input contain a term with multiple valid meanings?
-    ? clarify if yes
-    ?
-  Completion                  ? Is this input specific enough to be actionable?
-    ?                           (receives full context ? resolves "run again" etc.)
-    ? guide if incomplete or vague
-    ?
-  Intent Interpretation       ? What does the user appear to be trying to do? (guided_recovery only)
-  Bridge ?                    advisory ? improves guidance labels, never invents missing facts
-    ?
-    ?
-  Response Planner            ? Maps intent state to a final response mode
-    ?
-    ?
-  (if execute)
-  Change Interpretation       ? What will the human experience from this change? (advisory)
-    ?
-    ?
-  Guidance Ordering           ? applyGuidanceOrdering (B2 ? session-aware, advisory only)
-  [if guidance exists]          reorders read_first before use_exact_format
-                                shortens read_first label when category is familiar (?3 obs)
-    ?
-    ?
-  IntakeResult                ? { mode, reason, signal, intentState, guidance?, interpretation? }
-    ?
-    ?
-  Presentation Layer          ? formatIntakeResult ? PresentationOutput
-                                badge, headline, category, confidence, steps, missing
+npx usesteady
 ```
 
 ---
 
-## Layers
-
-### UCP ? UseSteady Control Protocol
-**What it is:** The canonical message envelope format. Every payload in the system has a version, kind, id, timestamp, and a SHA-256 hash derived from all fields.
-
-**Why it matters:** Envelopes are tamper-evident. The hash makes the payload verifiable without trusting memory or state.
-
-**One-liner:** All messages have a stable identity and a content hash.
-
----
-
-### PRV ? Pre-Response Validation
-**What it is:** A fast lexical check that runs before anything else. Looks for high-signal markers (`again`, `continue`, `previous`, `same as`) that mean the input requires prior state.
-
-**Why it matters:** If you say "run again" and there is no prior run, the system must clarify ? not guess. PRV enforces this at the front door.
-
-**One-liner:** Stops obvious context-dependent requests before they go anywhere.
-
-**Boundary with Context Alignment:** PRV is lexical (word-level). Context Alignment is semantic (phrase-level). "same file", "that result", "my project" are handled by Context Alignment, not PRV.
-
----
-
-### Safety Gate
-**What it is:** A deterministic, registry-driven chain of detectors. Runs after PRV, before anything else. Each detector has an `id`, a `priority`, and labeled patterns that produce a `matchedPattern` and `detectorId` on block.
-
-**Why it matters:** Unsafe inputs ? destructive actions, credential access, rule bypass, arbitrary script execution ? are refused here. No unsafe input reaches interpretation or execution.
-
-**One-liner:** Blocks dangerous inputs early and tells you exactly why.
-
-**Inspectable fields on a block result:**
-- `detectorId` ? which detector fired
-- `matchedPattern` ? which specific phrase triggered it
-- `reason` ? the risk category enum
-- `note` ? plain-English explanation
-
----
-
-### Context Alignment
-**What it is:** Classifies the input into one of three states: `aligned` (normal task), `non_literal` (social/greeting), or `hard_mismatch` (references prior context that isn't available).
-
-**Why it matters:** "Good morning" and "use same file" should never reach the planner. Context Alignment handles both correctly.
-
-**One-liner:** Identifies social messages and unresolvable context references.
-
----
-
-### Disambiguation
-**What it is:** A registry of detectors that flag inputs with multiple valid interpretations. When a term is ambiguous, it returns bounded options ? never a silent rewrite.
-
-**Why it matters:** "change button" could mean text, color, behavior, or handler. The system must ask, not guess.
-
-**One-liner:** Detects terms with multiple meanings and surfaces the options.
-
-**Note:** `unknown` from disambiguation is an internal state ? it means "no ambiguity detected, proceed to completion." It is not returned as a public signal.
-
----
-
-### Completion
-**What it is:** The authority on executability. Determines whether the input is actionable (`complete`), missing a specific required field (`incomplete`), or too vague to act on without format guidance (`guided_recovery`).
-
-**Why it matters:** Completion receives full session context, so "run again" resolves to `complete` when a prior run exists. Disambiguation returning `unknown` does not block completion from returning `complete`.
-
-**One-liner:** Decides whether the input is ready to execute ? and if not, explains exactly what's needed.
-
-**Semantic contract (must not be collapsed):**
-- `incomplete` = intent is clear, a required field is missing (e.g. "commit my changes" ? needs a message)
-- `guided_recovery` = intent is vague, a safe format path exists (e.g. "make button blue" ? needs file + values)
-
-**Written contract:** Completion is the sole authority on executability. Disambiguation `unknown` does not block it. Context-dependent executable inputs are resolved here.
-
----
-
-### Change Interpretation (v1)
-**What it is:** An advisory layer that runs only when mode is `execute`. Describes what the human will experience from the change ? in plain English, with impact notes and confidence.
-
-**Why it matters:** The system can now say "this changes the background color from blue-500 to red-500 in Button.tsx ? visual change only, no logic impact" rather than just "execute." That is meaningful information for the user and for any downstream reviewer.
-
-**One-liner:** Tells you what the change means, not just that it's allowed.
-
-**v1 scope (deterministic, no inference):**
-- Tailwind color class changes (`bg-`, `text-`, `border-`, etc.) ? confidence: high
-- CSS color value changes (hex, rgb, hsl, named colors, CSS property declarations) ? confidence: high/medium
-- Config value changes (numbers, URLs, booleans in .json/.yaml/.env files) ? confidence: high/medium
-- Text literal changes (human-readable UI copy) ? confidence: medium
-
-**Returns `null`** for any input outside these three categories. Does not guess.
-
----
-
-### Intent Interpretation Bridge
-**What it is:** An advisory layer that runs only when `CompletionResult.kind === "guided_recovery"`. It classifies the user's broad intent (visual color change, text/copy change, configuration change) and uses that classification to rewrite guidance labels into human-readable, context-aware form.
-
-**Why it matters:** Before this layer, guided recovery returned generic format instructions. After it, the same instructions are prefaced with "Read the component file first to find the current color value" ? which tells the user *why* they're being asked to read before patching. The meaning is still safe; nothing is invented.
-
-**One-liner:** Tells you what the user appears to be trying to do, so guided recovery reads like help rather than syntax documentation.
-
-**Hard invariant (locked):** Interpretation can improve guidance, but it can never manufacture executability.
-
-**What it classifies:**
-- `visual_color` ? named colors, comparative terms (darker/lighter), color/style targets (button, background, header)
-- `text_change` ? text-change verb AND text-content target (heading, label, copy, title, placeholder)
-- `config_change` ? strong config verbs (toggle/enable/disable) or config nouns (port, timeout, flag, env)
-
-**What it never does:**
-- Guess the file path
-- Guess the current or new value
-- Guess any token, class name, or key
-- Change the mode from `guide` to `execute`
-
-**Returns `null`** (no enrichment) if the input does not match any safe category. Original guidance is returned unchanged.
-
-**Priority ordering in the registry:**
-1. Config (priority 10) ? must beat color for "toggle dark mode"
-2. Color (priority 20) ? named colors + UI target terms
-3. Text (priority 30) ? requires both verb AND target (tighter match)
-
----
-
-### Presentation Layer
-**What it is:** A pure translation layer that converts an `IntakeResult` into a `PresentationOutput` ? the last-mile data structure a consumer can render directly, without re-running or re-interpreting anything.
-
-**Why it matters:** Without this layer, every consumer needs to know how to branch on `mode`, which interpretation family to use, where to find confidence, and how to format step labels. The presentation layer handles that once, correctly, and deterministically.
+## Why
 
-**One-liner:** Takes a decided `IntakeResult` and formats it for display.
+AI tools can generate code, run commands, and modify files — often before you fully understand what will change.
 
-**`PresentationOutput` fields:**
-- `badge` ? mode indicator: `REFUSE` | `IGNORE` | `CLARIFY` | `GUIDE` | `EXECUTE`
-- `headline` ? the first sentence to show; sourced from interpretation summary (when available) or system reason
-- `category` ? human-readable display name for the interpretation category (when available)
-- `confidence` ? `"High confidence"` / `"Medium confidence"` / `"Low confidence"` (when available)
-- `steps` ? formatted step labels from `guidance.nextSteps` (guide mode only)
-- `missing` ? list of missing fields from `guidance.missing` (guide mode only)
+UseSteady adds a review layer:
 
-**What it never does:**
-- Re-runs intake, completion, or interpretation
-- Adds new decisions or modifies existing ones
-- Invents values, categories, or steps not already in `IntakeResult`
+- **SYSTEM WILL** — the exact change, not a summary
+- **Risk level** — LOW / MEDIUM / HIGH, derived from what is actually changing
+- **WHY explanation** — what this does and why it was triggered
+- **Approve / Reject** — per step, before anything runs
 
 ---
 
-### Silent Guidance
-**What it is:** A presentation-only selector layer that maps inputs to operation or investigation mode when interpretation does not apply. It runs inside the Present Layer ? never inside intake.
-
-**Why it matters:** 86% "unknown" at the presentation level is honest, not a failure. But when a pattern recurs across sessions (C1/C3 evidence), it can be given a structured guidance voice without involving the interpreter. Silent Guidance covers ops/BI vocabulary (scale, export, deploy, inspect, trace) that belongs to presentation, not execution.
-
-**Hard invariants:** no patch leakage, deterministic output, investigation > operation precedence when both match, no template may contain `replace ? with ?`.
-
----
+## Example
 
-### Control Visibility & Boundary Integrity (CVG ? Phase 5B)
-**What it is:** A presentation-layer safety contract. Not a UI concern. A programmatic classifier that maps any presentation state to a `ControlVisibilityResult` ? a structured record of the signal's authority tier (`blocking` / `attention` / `normal`) and three derived boolean flags.
-
-**Why it matters:** This is the formal guard against the Helix-style failure mode where critical authority signals blend into normal presentation. With CVG in place, a `conflict_detected` state cannot be visually or programmatically equivalent to a `ready_to_confirm` state.
-
-**One-liner:** Makes higher-authority signals structurally distinct from lower-authority signals ? and throws immediately if that contract is violated.
-
-**Locked rules (C1?C4):**
-- **C1** ? CVG derives from existing presentation state only. No re-evaluation. No inference.
-- **C2** ? CVG may assert, but never route. It never changes the caller's output.
-- **C3** ? CVG may detect violations, but never repair them silently. Bad results throw.
-- **C4** ? Any new presentation family must extend `ControlVisibilityInput`, add an exhaustive mapping, and pass uniqueness + invariant tests before shipping.
-
-**Level ? flag assignment:**
-
-| Level | `must_block_confirm` | `must_surface` | `must_differentiate` |
-|-------|---------------------|----------------|----------------------|
-| `blocking` | `true` | `true` | `true` |
-| `attention` | `false` | `true` | `true` |
-| `normal` | `false` | `false` | `true` |
-
-**Hooks:** `presentFromInput()` and `renderReminder()` run CVG eval + assert on every call. Output shapes are unchanged.
-
----
-
-### Cursor Execution Seam (Phase 6)
-**What it is:** The governed handoff path from a prepared edit artifact to real filesystem mutation. Consists of four components that form a strict one-way delivery pipe:
-
-```
-CursorHandoffArtifact
-    ? CursorDeliveryGate     (eligibility check + UCP persistence)
-    ? CursorEditorPlugin     (transport interface)
-    ? CursorInProcessAdapter (exact-match filesystem edit)
 ```
+$ npx usesteady
 
-**Why it matters:** Natural language never directly edits files. Every edit goes through: intake (mode authority), OCD policy (constraint authority), H approval (sole approval authority), delivery gate (eligibility enforcement), and then ? only then ? the adapter. No layer can bypass another.
+  UseSteady
 
-**Key invariants (I1?I10):**
-- `prepareCursorExecution()` is side-effect-free ? nothing touches disk before H approval
-- `ucp.cursor_handoff.v1` persists before send, or delivery is blocked
-- Raw input never crosses the seam ? Cursor cannot reinterpret what it never receives
-- Exactly one string match required ? `ambiguous_match` is a first-class refusal
-- Scope refusal is recoverable only through H narrowing ? never automatic file choice
-- OCD constrains only; it never proposes `allowedFiles`
+  AI can propose changes.
+  You approve before they run.
 
----
+  Type your request:
+  > Update button color
 
-### Cursor Product Session (Phase 6B)
-**What it is:** A flat immutable state machine that connects the execution engine to human interaction flows. One session = one edit attempt. Consumers receive a `CursorSessionState` after each transition and route based on `phase`.
+  Generating execution plan...
 
-**Phases:** `idle` ? `prepared` | `conflict` ? `approved` ? `accepted` | `scope_question` | `exec_error` | `blocked` | `rejected` | `not_execute` | `intake_failed`
+  SYSTEM WILL
 
-**Why it matters:** The session makes the governed edit workflow operable from any shell (CLI, UI, plugin) without each shell needing to re-implement the authority logic. The session holds state; authority stays upstream.
+  1. Modify src/components/Button.tsx
+     Replace bg-blue-500 → bg-indigo-600
 
-**Baseline truths (P1?P6):**
-- **P1** ? Terminal states are immutable. All transitions return the same state object unchanged after termination.
-- **P2** ? Scope clarification is candidate-bounded. `answerScope()` rejects any file not in `scopeQuestion.candidates`.
-- **P3** ? Approval is never execution. `approve()` ? `"approved"`. `deliver()` is a separate explicit act.
-- **P4** ? Delivery requires approved. `deliver()` from any other phase ? `"blocked"`.
-- **P5** ? Session carries state but has no independent authority.
-- **P6** ? All authority lives in intake, OCD/policy, H, and the delivery gate. The session calls them; it does not replace them.
+  RISK: LOW
 
----
-
-### Interaction Contract
-**What it is:** An immutable record of how this user prefers to receive responses ? ambiguity tolerance, explanation style, guidance format. Updated by pure functions from observed events.
-
-**Why it matters:** The system can adapt to a user who consistently corrects misinterpretations, without requiring a profile UI or persistent identity.
+  WHY
+  Updates shared button styling.
 
-**One-liner:** Tracks how the user communicates, without storing personal data.
+  [a] Approve   [r] Reject
 
-**`observedIntentPatterns` (Phase B1 ? advisory session signal):**
-A counter field on the contract that records how many times each intent category was seen in guided recovery flows where the Intent Interpretation Bridge actually fired.
+  > a
 
-```ts
-type ObservedIntentPatterns = {
-  visual_color:  number; // guide + visual_color classification + bridgeFired
-  text_change:   number; // guide + text_change classification + bridgeFired
-  config_change: number; // guide + config_change classification + bridgeFired
-};
-```
-
-**How to observe:** Call `observeIntentPattern(result, trace)` after a pipeline run. It returns an `InteractionEvent | null`. If non-null, pass it to `applyInteractionEvent(contract, event)` to get an updated contract.
+  ✓ Step approved — Button.tsx updated.
 
-```ts
-const { result, trace } = runIntakeWithTrace(input, ctx);
-const event = observeIntentPattern(result, trace);
-if (event !== null) {
-  contract = applyInteractionEvent(contract, event);
-}
+  All steps reviewed.
+  Return to your workflow to continue.
 ```
 
-**Hard invariants (must not be violated):**
-1. `observeIntentPattern` returns null unless **all four** conditions are met:
-   - `result.mode === "guide"`
-   - `result.guidance?.interpretation` is defined
-   - `trace.bridgeFired === true`
-   - interpretation category is one of `visual_color`, `text_change`, `config_change`
-2. `observedIntentPatterns` is **advisory only**. It influences guidance ordering and label emphasis in B2. It may **never** affect: PRV, Safety Gate, Context Alignment, Disambiguation, Completion, response mode, intentState, or interpretation category/confidence.
-3. No observation event fires on `execute`, `refuse`, `clarify`, or `ignore` flows.
-4. No observation event fires when `bridgeFired: false` or when no trace is provided.
-
-**Why `bridgeFired` is required (not just interpretation presence):** The trace is explicit confirmation that the bridge ran and completed. Requiring it prevents the observation from being triggered by any future path that might attach interpretation from a different source.
-
----
-
-### Session-Aware Guidance Ordering (Phase B2)
-**What it is:** A purely presentational step that runs after `enrichGuidance` and applies two adjustments to the `GuidancePayload` based on `observedIntentPatterns`:
-
-1. **Step type ordering** ? `read_first` is guaranteed before `use_exact_format` (defensive sort; already true for enriched paths, but now an explicit invariant).
-
-2. **Label emphasis** ? when `patterns[category] >= FAMILIARITY_THRESHOLD` (3 observations), the `read_first` step label shortens from its explanatory form to an action-first form:
+### High risk example
 
-| Category | Default label (0 observations) | Familiar label (?3 observations) |
-|---|---|---|
-| `visual_color` | `Read the component file first to find the current color value: read "<file>"` | `Find the current color in the component file: read "<file>"` |
-| `text_change` | `Read the file first to find the current text: read "<file>"` | `Find the current text in the file: read "<file>"` |
-| `config_change` | `Read the config file first to find the current setting: read "<file>"` | `Find the current setting in the config file: read "<file>"` |
-
-**The "first" word is the learner cue.** New users need it. Experienced users don't.
-
-**Hard invariants (must not be violated):**
-1. Step count never changes ? no step is added or removed.
-2. `missing[]` never changes.
-3. `interpretation` (category, confidence, summary, basis) never changes.
-4. `mode`, `reason`, `signal`, `intentState` are decided before this function runs ? it cannot affect them.
-5. A high count for one category never touches another category's labels.
-6. `read_first` is never suppressed, only relabeled.
-7. If no `read_first` step exists in the guidance, the function has no effect.
-8. Tie-breaking: stable sort ? same-type steps preserve their original relative order.
-
-**`FAMILIARITY_THRESHOLD = 3`** ? enough observations to distinguish deliberate repeated use from accidental. Below threshold, nothing changes.
-
----
-
-### Response Planner
-**What it is:** A deterministic mapping from intent state to response mode. No logic ? just a lookup table with documented reasoning.
-
-**Why it matters:** The decision of what to do is explicit, auditable, and separate from the understanding that produced it.
-
-**Mapping:**
-| Intent state | Response mode |
-|---|---|
-| unsafe | refuse |
-| non_literal | ignore |
-| ambiguous | clarify |
-| incomplete | guide |
-| guided_recovery | guide |
-| clear | execute |
-
----
-
-## Locked behavior invariants
-
-These were confirmed by a persona friction pass against the live system. They are product invariants, not guidelines. Future contributors must not violate them.
-
-Any code change that violates an invariant below is a breaking change ? same as the written contracts above.
-
-1. **Intent Interpretation is narrower than user language.** The bridge only classifies what it can safely claim. If no color word, text-change verb+target, or config signal is present, it returns null and stays silent. Helpfulness without evidence is overclaiming.
-
-2. **Null is a valid success state.** A bridge result of null means "no safe interpretation exists." It is not an error. It is not a fallback. It is the correct answer when the signal is absent. Do not replace null with a guess.
-
-3. **Vague intent never yields high confidence.** High confidence is reserved for inputs where the evidence is unambiguous and specific. No vague natural-language request (without exact values) may produce `confidence: "high"`. Medium or low are the correct ceiling.
-
-4. **Incomplete intent does not use the bridge.** When `CompletionResult.kind === "incomplete"`, the intent is already unambiguous ? a required field is simply missing. Running intent interpretation on these inputs would add noise, not meaning. The bridge skips them.
-
-5. **Bridge output may improve labels, not truth.** The bridge may rewrite step labels to be context-aware. It may never invent file paths, token names, current values, or new values. The `missing[]` array must remain identical before and after enrichment.
-
-6. **Executable interpretation and guided interpretation are separate families.** `InterpretationResult` (change interpretation, at `IntakeResult.interpretation`) describes what a structured patch command means. `IntentInterpretation` (intent bridge, at `IntakeResult.guidance.interpretation`) describes what a vague request appears to be attempting. These must never be merged or confused. One is for execute mode. One is for guide mode.
-
-7. **Observation events fire only when the bridge actually ran.** `observeIntentPattern` requires `trace.bridgeFired === true` as an explicit precondition. Without a trace, no observation fires. This ensures the session observation only tracks meaningful guided interpretations ? not generic noise, incomplete paths, or short-circuited flows.
-
-8. **Observed patterns are advisory only ? they never affect mode or truth.** `observedIntentPatterns` counts accumulate silently. They influence guidance ordering and label emphasis (B2). They must never influence `mode`, `intentState`, `safetyVerdict`, `completionKind`, or `interpretation category/confidence`. Same input + same context ? same mode, always, regardless of prior observation counts.
-
-9. **Guidance ordering may only reorder and relabel ? never add, remove, or suppress.** `applyGuidanceOrdering` may change the position and label text of existing steps. It may never add a new step, remove an existing step, remove a `read_first` step, or suppress any step that was present in the input guidance. Step count in equals step count out, always.
-
-10. **Cross-category isolation is absolute.** A high count in `text_change` never affects `visual_color` labels, and vice versa. Category-specific familiar labels are applied only when the current guidance's `interpretation.category` matches the pattern that exceeded the threshold.
-
----
-
-## Integration boundaries
-
-### Intake + Present seam (HTTP API / CLI)
-
-```
-User input
-  →
-runIntakeWithTrace(input, ctx)               → this package
-observeIntentPattern + applyInteractionEvent → this package
-presentFromInput(input, intakeResult)        → this package
-  → PresentResult (kind: "reminder" | "intake")
-  → consumed by CLI shell (src/shell/cli/main.ts)
-    or API server   (server.ts → HTTP JSON → React UI at ui/)
 ```
+  SYSTEM WILL
 
-CVG assertions run inside `presentFromInput()` and `renderReminder()` — zero-cost for consumers, throws on invalid states.
+  1. Permanently delete src/utils/deprecated.ts
 
-### Cursor execution seam (governed edit path)
+     Removes deprecated.ts and all its exports
+     Any import of this file will fail immediately after deletion
+     No automatic recovery — requires git revert if this was a mistake
 
-```
-User input
-  ? runIntakeWithUCP()
-  ?
-CursorProductSession.submit()     ? prepareCursorExecution() inside
-  ? phase: "prepared" | "conflict"
-  ? H reviews display, accepts conflict (if any)
-  ?
-CursorProductSession.approve()    ? approveArtifact() inside
-  ? phase: "approved"
-  ?
-CursorProductSession.deliver()    ? deliverCursorExecution() ? CursorDeliveryGate inside
-  ? phase: "accepted" | "scope_question" | "exec_error" | "blocked"
-  ?
-Filesystem (real file mutation ? only on "accepted")
-```
-
-Every stage is independently testable. The gate is the enforcement point between H and filesystem. Nothing below the gate is reachable without a persisted `ucp.cursor_handoff.v1`.
+  RISK: HIGH
 
-Authority distribution:
-```
-intake          ? sole mode authority
-OCD policy      ? sole constraint authority
-H               ? sole approval authority
-delivery gate   ? sole eligibility authority
-session         ? state carrier only (no authority of its own)
-```
+  WHY
+  Removes deprecated utilities no longer used.
 
-### Claude Managed Agents seam (Phase 8B ? scaffold locked)
+  ⚠ HIGH RISK — cannot be undone without version control
 
+  [a] Approve (high risk)
+  [r] Reject
 ```
-User input
-  ? runIntakeWithUCP()                          ? intake: sole mode authority
-  ?
-buildClaudeHandoffArtifact()
-  ? executionDomain derived here (A1) ? never reclassified downstream
-  ? toolPolicy.networkAccess = "deny" (V1 lock, A2)
-  ? H reviews, approves ? approveClaudeArtifact()
-  ?
-ClaudeDeliveryGate.deliver()
-  ? checks: eligibility, networkAccess === "deny" (A2), filesystemMode, allowedTools
-  ? persists ucp.claude_handoff.v1 BEFORE Claude is called
-  ?
-ClaudeAgentPlugin.receive()                     ? only call gate makes into Claude (A4)
-  ? returns: accepted | refused_due_to_scope | refused_due_to_execution_error
-  ? unknown kinds ? refused_due_to_execution_error (fail-closed)
-  ?
-gate persists ucp.claude_receipt.v1 or ucp.claude_refused.v1
-```
-
-Four Phase A locked truths enforced in the gate:
-- **A1** ? `executionDomain` is mapper-derived; gate validates presence only
-- **A2** ? `networkAccess: "allow_limited"` ? `blocked_tool_policy` (V1 hard block)
-- **A3** ? Session interruption ? `refused_due_to_execution_error` (non-resumable in V1)
-- **A4** ? No Claude?Intake callback path; `ClaudeAgentPlugin` is one-way only
-
----
-
-## Governance documents
-
-| Document | What it governs |
-|---|---|
-| [`docs/cursor-v1-baseline.md`](docs/cursor-v1-baseline.md) | Cursor seam + product session invariants |
-| [`docs/cvg-baseline.md`](docs/cvg-baseline.md) | Control Visibility & Boundary Integrity invariants |
-| [`docs/claude-agent-phase-a-architecture.md`](docs/claude-agent-phase-a-architecture.md) | Claude Managed Agents Phase A freeze |
-| [`docs/architecture/MODEL_INSERTION_POLICY.md`](docs/architecture/MODEL_INSERTION_POLICY.md) | Where AI models may and may not be used ? authority/advisory split, forbidden patterns, CI enforcement |
-
-The Model Insertion Policy is a first-class invariant document alongside CVG and the Cursor baseline. Any change that introduces an AI model at any layer must comply with it before implementation.
-
----
-
-## Non-goals
-
-This project does not:
-- Generate responses (that is the consumer's job)
-- Execute anything
-- Connect to any external service
-- Use an LLM at any stage to make control decisions
-- Correct user input silently
-- Guess missing values
-- Produce fuzzy matches
 
 ---
 
-## Example flows
+## What makes it different
 
-### "make button blue" (Maya ? vague style change, with bridge)
+- No silent execution
+- No vague summaries
+- No hidden changes
 
-| Stage | Result |
-|---|---|
-| PRV | pass |
-| Safety | allow |
-| Context Alignment | aligned |
-| Disambiguation | unknown (no ambiguity) |
-| Completion | guided_recovery ? missing: [file path, current value, new value] |
-| Intent Interpretation | visual_color ? "This appears to be a color/style change request." |
-| Response Planner | **guide** |
-| Guidance | missing: [file path, current value, new value] *(unchanged)* |
-| | `Read the component file first to find the current color value: read "<file>"` |
-| | `Then patch it: replace "<current color>" with "<new color>" in "<file>"` |
-| | interpretation: { category: visual_color, confidence: medium } |
-
-**What the user sees (before bridge):** "Start by reading the file, then use: replace \"\" with \"\" in \"\""
-
-**What the user sees (after bridge):** "This appears to be a color/style change request. Read the component file first to find the current color value, then patch it: replace \"<current color>\" with \"<new color>\" in \"<file>\""
-
-The user now knows *why* they're reading first and what kind of change they're making. No file or value was invented.
-
----
-
-### "run rm -rf /" (Alex ? destructive command)
-
-| Stage | Result |
-|---|---|
-| PRV | pass |
-| Safety | **block** ? detectorId: destructive_mass_action, matchedPattern: "rm -rf" |
-| Response Planner | **refuse** |
-
-**What the user sees:** "This input cannot be processed. It matches a pattern associated with irreversible bulk data destruction."
-
----
-
-### "run again" with no prior session (Priya ? missing context)
-
-| Stage | Result |
-|---|---|
-| PRV | **clarify** ? 'again' requires prior context, none available |
-| Response Planner | **clarify** |
-
-**What the user sees:** "This request depends on prior context, but none is available. What would you like to run?"
+You see what changes, why it changes, and how risky it is — before anything runs.
 
 ---
 
-### "run again" WITH a prior session (Priya ? context-aware rerun)
-
-| Stage | Result |
-|---|---|
-| PRV | pass (prior session exists) |
-| Safety | allow |
-| Context Alignment | aligned |
-| Disambiguation | unknown |
-| Completion | **complete** (rerun_previous rule resolves it) |
-| Response Planner | **execute** |
-
-**What the user sees:** The system re-runs the last command without asking again.
-
----
+## Install
 
-### "find loops in the approval rules" (disambiguation)
+```bash
+# No install needed — run directly
+npx usesteady
 
-| Stage | Result |
-|---|---|
-| PRV | pass |
-| Safety | allow |
-| Context Alignment | aligned |
-| Disambiguation | **ambiguous** ? options: ["loops = circular logic", "loops = iteration patterns"] |
-| Response Planner | **clarify** |
+# Or install globally
+npm install -g usesteady
+```
 
-**What the user sees:** "Did you mean (a) circular references in the approval flow, or (b) iteration patterns in the approval code?"
+Requires Node.js 18+. Runs fully local. No cloud, no API key.
 
 ---
 
-### "commit my changes" (incomplete ? missing message)
+## Core idea
 
-| Stage | Result |
-|---|---|
-| PRV | pass |
-| Safety | allow |
-| Context Alignment | aligned |
-| Disambiguation | unknown |
-| Completion | **incomplete** ? missing: [commit message] |
-| Response Planner | **guide** |
-| Guidance | next step: commit "" |
+**AI proposes. You approve. Then it runs.**
 
-**What the user sees:** "A commit message is required. Use: commit \"\""
+Like `git diff` — but for AI actions before they execute.
 
 ---
 
-### replace "bg-blue-500" with "bg-red-500" in src/Button.tsx (Maya ? exact change with interpretation)
+## Language
 
-| Stage | Result |
+| Term | Meaning |
 |---|---|
-| PRV | pass |
-| Safety | allow |
-| Context Alignment | aligned |
-| Disambiguation | unknown |
-| Completion | **complete** |
-| Response Planner | **execute** |
-| Interpretation | category: tailwind_color_change, confidence: high |
-| | summary: "Changes background color from 'bg-blue-500' to 'bg-red-500' in Button.tsx." |
-| | impact: ["Visual change only ? no logic, data, or behavior impact."] |
-
-**What the user sees:** The change is applied. The result includes a plain-English description: "Changes background color from blue-500 to red-500 in Button.tsx ? visual change only."
+| `SYSTEM WILL` | The exact operation that will run — not a summary |
+| `SYSTEM SUGGESTS` | Options shown when AI is unsure — not a guess |
+| `Approve` / `Reject` | Your decision, per step |
+| `Revert last approval` | Undo a decision (not a filesystem change — nothing has run yet) |
+| `Risk: LOW / MEDIUM / HIGH` | Derived from what is actually changing |
 
 ---
 
-## Written contracts
-
-These are non-negotiable invariants of the system. Any code change that violates one is a breaking change.
-
-1. **Completion is the sole authority on executability.** Disambiguation `unknown` does not block completion from returning `complete`.
-
-2. **Guide mode must carry structured guidance.** No consumer should need to re-run completion to render next steps.
-
-3. **Completion receives context.** Any context-dependent executable intent must be resolvable in completion.
-
-4. **PRV is lexical. Context Alignment is semantic.** No semantic reasoning in PRV.
-
-5. **Public output exposes final outcome, not internal intermediates.** Disambiguation `unknown` is not a public signal.
-
-6. **Interpretation is advisory.** It does not change the mode decision. It describes what the human will experience.
-
-7. **`incomplete` ? `guided_recovery`.** These are distinct states with distinct semantics. Do not collapse them.
-
-8. **Interpretation can improve guidance, but it can never manufacture executability.** The Intent Interpretation Bridge runs only for `guided_recovery`. It may improve labels. It may never guess values, file paths, or tokens. It may never change the mode decision.
-
----
-
-## Test summary
-
-```
-2321 tests passing across 53 test files.
-0 failures.
-```
-
-| Area | Files | What is covered |
-|------|-------|-----------------|
-| `tests/ucp/` | 4 | Envelope hash determinism, structure, persistence, timeline, phase 7 alignment |
-| `tests/prv/` | 1 | Lexical markers, narrowed patterns, context boundary |
-| `tests/safety/` | 1 | Blocking, allowing, detectorId + matchedPattern inspectability |
-| `tests/understand/` | 12 | Context alignment, disambiguation, completion, change interpretation, intent bridge (unit + friction + pressure), silent guidance, session-aware guidance ordering |
-| `tests/interaction/` | 2 | Default contract, updater, selectors, observation events |
-| `tests/intake/` | 10 | All five modes, guidance contract, interpretation, branch validation, session validation |
-| `tests/present/` | 4 | Badge/headline/category/confidence, reminder presenter + renderer, coordinator routing, CVG signal mapping + flag assignment + uniqueness + assertion invariants + integration |
-| `tests/cursor/` | 3 | Delivery gate (eligibility, persistence, OCD, glob-matcher), in-process adapter (real FS, round-trip scope proof), execution coordinator (two-phase, consumer helpers) |
-| `tests/product/` | 2 | Session invariants S1?S8, phase gates, terminal state preservation, approve ? deliver; session resilience (snapshot, staleness, summary) |
-| `tests/execution/` | 8 | Reminder execution parse-once, validator, artifact-first design, UCP reminder chain |
-| `tests/claude/` | 1 | Claude delivery gate: A1?A4 invariants, three delivery paths, UCP chain integrity, fail-closed unknowns, session interruption (A3) |
-
----
-
-## How to safely extend the system
-
-Three rules. All three apply to every change.
-
-**1. Extend only one layer at a time.**  
-Each layer has a defined scope and a defined boundary. An intake change is an intake change. A presentation change is a presentation change. A change that touches two layers simultaneously is a seam violation ? it means the boundary was unclear, not that the rule is wrong. Clarify the boundary first, then make the change in the correct layer.
-
-**2. Update baseline ? annotation ? tests. In that order.**  
-Before writing code: update the relevant baseline document (`docs/cursor-v1-baseline.md`, `docs/cvg-baseline.md`, or the written contracts in this file) to state what the new invariant is. Then add the comment-level annotation to the source file at the point where the rule could be violated. Then write the test that proves it. If you cannot write the invariant before the code, the design is not clear enough yet.
-
-**3. Never introduce authority into the Present or Session layers.**  
-The Present layer formats state. The Session layer carries state. Neither layer may make a decision that belongs to intake, OCD policy, H, or the delivery gate. The test is simple: if the new code changes what *happens* based on what *was presented*, it belongs to a different layer. If it only changes what *is shown* based on what *already happened*, it belongs here.
+## You see SYSTEM WILL before anything runs.
 
-**4. If the change involves an AI model, consult the Model Insertion Policy first.**  
-Models may only be inserted as language adapters in advisory layers. They may never participate in routing, classification, approval, scope selection, gate decisions, or UCP persistence. See [`docs/architecture/MODEL_INSERTION_POLICY.md`](docs/architecture/MODEL_INSERTION_POLICY.md) for the complete authority/advisory split, forbidden patterns, implementation constraints, and CI enforcement requirements.
+That is the guarantee. Every step. No exceptions.
 
 ---
 
-## What is intentionally deferred
-
-| Item | Status |
-|------|--------|
-| Change Interpretation ? structural code changes | Not in v1 scope |
-| Change Interpretation ? multi-file changes | Not in v1 scope |
-| Intent Interpretation Bridge ? file search / token lookup | Intentionally excluded; bridge never searches |
-| Intent Interpretation Bridge ? `incomplete` enrichment | Intentionally excluded; incomplete already has specific guidance |
-| Interaction Contract ? persistence | In-memory only; no storage layer yet |
-| Reminder scheduler / persistence | Reminder execution is complete; scheduling is deferred |
-| Timezone resolution | Deferred; time is extracted as text, not resolved |
-| `ucp.cursor_artifact.v1` | Reserved slot between `cursor_receipt` and `execution_trace`; deferred until Cursor produces a real diff object |
-| IPC / remote Cursor transport | In-process adapter proves the contract; remote transport follows same `CursorEditorPlugin` interface |
-| Persistent run store | ✅ Shipped PI-4 Iter 1 — file-backed store (`server-store.ts`) |
-| Real-time frame streaming | ✅ Shipped PI-4 Iter 3 — SSE endpoint (`GET /api/workflow/:runId/events`) |
-| Claude real API adapter | `ClaudeStubAdapter` used in web server; real Anthropic wiring requires `@anthropic-ai/sdk` install |
+[usesteady.dev](https://usesteady.dev) · Apache 2.0