feat: add substitution contract to digital twin

README.md

@@ -1,6 +1,6 @@
 # digital-twin
 
-> A Claude Code plugin that mines your own session logs to build a digital twin: a profile of how you actually work, a sub-agent that imitates you, and a CLAUDE.md patch you can drop into any new project.
+> A Claude Code plugin that mines your own session logs to build a digital twin: a profile of how you actually work, a user-substituting orchestration sub-agent, and a CLAUDE.md patch you can drop into any new project.
 
 Local extraction/statistics/rendering stay on your machine. The LLM-bound phases use your existing Claude Code auth and can send corpus-derived evidence to Claude: deep-read agents, profile-insight extraction, and compact behavioral `twin-spec.json` extraction. No plugin telemetry.
 
@@ -14,8 +14,8 @@ The plugin walks `~/.claude/projects/*/*.jsonl` (every Claude Code session you'v
 |---|---|
 | `PROFILE.md` | An insights-style report: how you orchestrate, where you push back, what plans you write, what rules you've encoded. Includes ASCII charts. |
 | `PROFILE.html` | The same report with inline SVG charts. Self-contained — open in any browser. |
-| `~/.claude/agents/twin.md` | A compact operational subagent rendered from `analysis/twin-spec.json`. Invocable as `@twin` (or via the `Agent` tool). |
-| `rules/*.md` | Generated CLAUDE rule files for preferences, workflows, verification, and recovery. |
+| `~/.claude/agents/twin.md` | A compact operational delegate rendered from `analysis/twin-spec.json`. Invocable as `@twin` (or via the `Agent` tool) to guide work the way you would. |
+| `rules/*.md` | Generated CLAUDE rule files for substitution authority, preferences, workflows, verification, and recovery. |
 | `CLAUDE-md-patch.md` | A short install guide that imports or symlinks the generated rules. |
 | `gotchas.md` | Seed list of pushback patterns from your own corpus. Editable. |
 | `numbers.md` | Canonical metrics — source of truth for everything else. |
@@ -137,7 +137,7 @@ The qualitative deep-read phase (6 parallel agents producing 1500-2500 word repo
 
 ## Self-updating loop
 
-The plugin includes a **pushback detector** that watches `(assistant-turn, user-reply)` pairs incrementally. When it sees a pushback that isn't already covered by an existing memory rule, it drafts a candidate rule and queues it at `~/.claude/digital-twin/proposed-rules/`.
+The plugin includes a **pushback detector** that watches `(assistant-turn, user-reply)` pairs incrementally. When it sees a pushback that isn't already covered by an existing memory rule or principle, it drafts a candidate judgment correction and queues it at `~/.claude/digital-twin/proposed-rules/`.
 
 ```bash
 # Run the detector manually (incremental — only new sessions since last run)
@@ -181,7 +181,7 @@ Your `private/` directory in this repo (if present) is gitignored — personal c
 
 ## Customizing the twin
 
-The synthesized `twin.md` sub-agent is rendered from `analysis/twin-spec.json`, not from a raw memory dump. The 6 deep-read agents write free-form narrative to `analysis/reports/`; Phase 5.5 (`extract-insights.py`) distills profile cards into `analysis/insights/`; Phase 5.6 (`extract-twin-spec.py`) distills operational behavior into `analysis/twin-spec.json`. `synthesize.py` also emits `rules/preferences.md`, `rules/workflows.md`, `rules/verification.md`, and `rules/recovery.md` for CLAUDE.md installation.
+The synthesized `twin.md` sub-agent is rendered from `analysis/twin-spec.json`, not from a raw memory dump. The 6 deep-read agents write free-form narrative to `analysis/reports/`; Phase 5.5 (`extract-insights.py`) distills profile cards into `analysis/insights/`; Phase 5.6 (`extract-twin-spec.py`) distills substitution authority, principles, trust behavior, agent supervision, and operational behavior into `analysis/twin-spec.json`. `synthesize.py` also emits `rules/substitution.md`, `rules/preferences.md`, `rules/workflows.md`, `rules/verification.md`, and `rules/recovery.md` for CLAUDE.md installation.
 
 The CLAUDE.md patch is intended to be edited before you commit it — it's a starting point, not a finished doc.
 

commands/init.md

@@ -15,7 +15,7 @@ First-time run of the digital-twin pipeline.
 4. **Phase 4 (deep sources, ~5 sec total)** — `memory-inventory.py`, `plan-inventory.py`, `assistant-turn-mining.py`, optional `pr-comment-mining.sh` in parallel. These files feed both the deep-read prompts and the twin spec.
 5. **Phase 5 (qualitative agents, LLM-bound)** — Dispatch 6 `general-purpose` agents in parallel. Each reads the corpus from a specific angle and writes a 1500-2500 word free-form deep read. Wall-clock depends on model latency and parallel-dispatch overhead; budget the bulk of the run here.
 6. **Phase 5.5 (insights extraction, 3-10+ min, ~$0.50-1)** — Single Sonnet call distills the 6 deep reads + corpus stats (~180 KB prompt) into 7 structured JSON files (`project_areas`, `interaction_style`, `big_wins`, `friction`, `suggestions`, `horizon`, `fun_ending`). Default timeout is 15 min; pass `--timeout` for larger corpora. On overrun, falls through to Tier 2.
-7. **Phase 5.6 (behavioral twin spec, 3-10+ min)** — `scripts/extract-twin-spec.py` distills the reports, insights, stats, and deep-source inventories into `analysis/twin-spec.json`, the compact operational contract used by `twin.md` and generated CLAUDE rules.
+7. **Phase 5.6 (behavioral twin spec, 3-10+ min)** — `scripts/extract-twin-spec.py` distills the reports, insights, stats, and deep-source inventories into `analysis/twin-spec.json`, the compact substitution contract used by `twin.md` and generated CLAUDE rules. This includes authority boundaries, principles, trust behavior, and agent-supervision policy.
 8. **Phase 6 (synthesize, <1 sec)** — `scripts/synthesize.py` fills the templates and writes PROFILE.md, PROFILE.html, twin.md, CLAUDE-md-patch.md, generated rules, gotchas.md, numbers.md.
 
 **Local pipeline (Phases 2, 3, 4, 6): ~20 sec on a 10k-session corpus.** Phases 5, 5.5, and 5.6 are LLM-bound and dominate wall-clock — there is no useful fixed estimate for those because agent latency and prompt size vary too much. Cost: ~$5-9 total (Sonnet for 6 deep-read agents + two extraction calls).
@@ -118,7 +118,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/skills/digital-twin/scripts/extract-twin-spec.py \
   --user-name "$USER_NAME"
 ```
 
-This writes `~/.claude/digital-twin/analysis/twin-spec.json`. It is the source of truth for `~/.claude/agents/twin.md` and `~/.claude/digital-twin/rules/*.md`. It must run after Phase 4 so the spec has memory, plan, and convergence evidence. If it is missing or invalid, `synthesize.py` still writes profile artifacts but emits an explicitly degraded twin with an incomplete-spec warning.
+This writes `~/.claude/digital-twin/analysis/twin-spec.json`. It is the source of truth for `~/.claude/agents/twin.md` and `~/.claude/digital-twin/rules/*.md`. It must run after Phase 4 so the spec has memory, plan, convergence, and trust evidence. If it is missing or invalid, `synthesize.py` still writes profile artifacts but emits an explicitly degraded twin with an incomplete-spec warning and without claiming user-substitution authority.
 
 ### Phase 6 — synthesize
 
@@ -134,8 +134,8 @@ After successful completion:
 
 - `~/.claude/digital-twin/PROFILE.html` — card-styled report (open in browser)
 - `~/.claude/digital-twin/PROFILE.md` — markdown mirror of PROFILE.html
-- `~/.claude/agents/twin.md` — installable sub-agent that imitates the operator
-- `~/.claude/digital-twin/rules/*.md` — generated user-level rule files for preferences, workflows, verification, and recovery
+- `~/.claude/agents/twin.md` — installable sub-agent that acts as the operator's delegate within authority boundaries
+- `~/.claude/digital-twin/rules/*.md` — generated user-level rule files for substitution, preferences, workflows, verification, and recovery
 - `~/.claude/digital-twin/CLAUDE-md-patch.md` — short install guide that imports the generated rules
 - `~/.claude/digital-twin/gotchas.md` — per-user gotchas catalog
 - `~/.claude/digital-twin/numbers.md` — canonical numbers source-of-truth

commands/propose-rules.md

@@ -1,21 +1,21 @@
 ---
 name: digital-twin:propose-rules
-description: Review pending memory rule proposals from the digital-twin pushback detector. Approves or rejects each proposed rule before it lands in the user's memory.
+description: Review pending memory rule and principle proposals from the digital-twin pushback detector. Approves or rejects each proposed correction before it lands in the user's memory.
 ---
 
 # /digital-twin propose-rules
 
-Review and approve auto-detected rule proposals.
+Review and approve auto-detected rule/principle corrections.
 
 ## How it works
 
-The `pushback-detector.py` watches `(assistant-turn, user-reply)` pairs and drafts candidate memory files when it sees a pushback that isn't already encoded in an existing rule. Proposals live at:
+The `pushback-detector.py` watches `(assistant-turn, user-reply)` pairs and drafts candidate memory files when it sees a pushback that isn't already encoded in an existing rule or principle. Proposals live at:
 
 ```
 ~/.claude/digital-twin/proposed-rules/
 ```
 
-Each proposal is a canonical-format memory file (YAML frontmatter + body + evidence section). Filenames are prefixed with a 3-digit confidence score (e.g., `090_<hash>_<slug>.md` for confidence 0.90).
+Each proposal is a canonical-format memory file (YAML frontmatter + correction body + evidence section). Filenames are prefixed with a 3-digit confidence score (e.g., `090_<hash>_<slug>.md` for confidence 0.90).
 
 ## Procedure (when this command is invoked)
 
@@ -51,12 +51,18 @@ Evidence
   Assistant:  > <truncated assistant turn, 200 chars>
   User reply: > <truncated user reply, 300 chars>
 
-Proposed rule
+Proposed correction
   Name:        <name>
   Description: <description>
   Type:        feedback
   Body:
-    <first 5 lines of body, indented>
+    Judgment correction:
+    Underlying principle:
+    Rationale:
+    Applies when:
+    Does not apply when:
+    Failure mode:
+    Trust/delegation implication:
 
 [a]pprove · [r]eject · [d]efer · [e]dit · [s]kip-all
 ```
@@ -65,16 +71,16 @@ Proposed rule
 
 4. **Act on the response:**
 
-   - **approve (`a`)**: Ask which project's memory to write to (list projects from `~/.claude/projects/`). Then:
+   - **approve (`a`)**: First check the proposal body for unresolved scaffold text. If it still contains `_Fill in`, `TODO`, or an empty required section for Underlying principle, Rationale, Applies when, Does not apply when, Failure mode, or Trust/delegation implication, require `edit` first and do not approve. Then ask which project's memory to write to (list projects from `~/.claude/projects/`). Then:
      a. Strip the `<!-- AUTO-PROPOSED ... -->` comments and the `## Evidence` section from the body.
-     b. Write the cleaned rule to `~/.claude/projects/<chosen-project>/memory/<name>.md`.
+     b. Write the cleaned principle-rich correction to `~/.claude/projects/<chosen-project>/memory/<name>.md`.
      c. Append a one-line entry to that project's `MEMORY.md` index (create the file if it doesn't exist).
      d. Move the original proposal to `~/.claude/digital-twin/proposed-rules/archive/approved_<filename>`.
      e. Confirm: "Approved → ~/.claude/projects/<project>/memory/<name>.md".
 
    - **reject (`r`)**: Ask "Why? (one line, optional)". Move the proposal to `~/.claude/digital-twin/proposed-rules/archive/rejected_<filename>`. Append the rejection reason as an HTML comment at the top of the archived file. Never delete — rejections are reviewable.
 
-   - **edit (`e`)**: Open an inline edit dialogue. Read the proposal, ask the user to provide replacement text for the rule body (everything between the frontmatter and the `## Evidence` section). Update the file in place. Then re-present the updated proposal for a/r/d.
+   - **edit (`e`)**: Open an inline edit dialogue. Read the proposal, ask the user to provide replacement text for the correction body (everything between the frontmatter and the `## Evidence` section). Update the file in place. Then re-present the updated proposal for a/r/d.
 
    - **defer (`d`)**: Leave the file in place. Continue to the next proposal.
 

commands/update.md

@@ -11,6 +11,8 @@ Refresh the digital-twin artifacts against the user's most recent logs.
 
 By default, re-runs Phases 2-6 with full recompute, including the behavioral `twin-spec.json`. With `--delta`, only re-mines logs newer than `~/.claude/digital-twin/_synthesis.json` `generated_at` timestamp.
 
+The current `twin-spec.json` includes substitution authority, principles, trust behavior, and agent-supervision policy. Older specs can still be rendered with conservative compatibility defaults, but refresh the spec before treating the twin as a user-substituting delegate.
+
 ## How to run
 
 ```bash
@@ -54,4 +56,4 @@ Same as init: fully local, no telemetry.
 
 ## Estimated cost
 
-~30% of an initial run if no qualitative agents are re-dispatched (the deep reads are the expensive part). Even when reports are reused, refresh `analysis/twin-spec.json` before synthesis whenever stats, insights, or memory inventories changed; never silently reuse a stale behavioral spec. With `--rerun-agents`, full cost.
+~30% of an initial run if no qualitative agents are re-dispatched (the deep reads are the expensive part). Even when reports are reused, refresh `analysis/twin-spec.json` before synthesis whenever stats, insights, memory inventories, or trust/delegation signals changed; never silently reuse a stale behavioral spec for user-substitution. With `--rerun-agents`, full cost.

examples/sample-CLAUDE-md-patch.md

@@ -6,67 +6,53 @@
 ---
 
 ```markdown
-# Twin defaults — auto-distilled from 300 of my own prompts
+# Digital Twin Rules
 
-## Operating model
+My operational delegate rules are maintained by the digital-twin pipeline.
+Load the substitution contract first, then the lower-level workflow rules:
 
-- Default delegation: parallel agents when work spans >2 areas
-- Approval gates at: plan, post-impl, pre-merge
-- Verification before 'ship': type check + tests + (UI cases: browser)
-
-## Workflow defaults
-
-- Default planner archetype: surgical for single-PR work, multi-phase only for >1 week scope
-- Always include in plans: Context, Goal, Approach, Out-of-scope, Verification
-- Verification gate before "ship it": type check + tests + (UI: browser dogfood)
-- Merge convention: _TBD_ (review your repo conventions)
-
-## Quality bar
-
-- No unhandled edge cases at PR time
-- No backfill gaps for data migrations
-- No stale references in docs
-
-## Voice
+@~/.claude/digital-twin/rules/substitution.md
+@~/.claude/digital-twin/rules/preferences.md
+@~/.claude/digital-twin/rules/workflows.md
+@~/.claude/digital-twin/rules/verification.md
+@~/.claude/digital-twin/rules/recovery.md
+```
 
-- Default register: terse imperative, ship-it framing
-- Approval phrases: `ship`, `ok`, `merge`, `yes`, `proceed`, `go`, `great`, `perfect`
-- Pushback phrases I use: `no`, `wait`, `but`, `actually`, `hold`, `stop`
-- Avoid: filler, emojis (unless explicit), recapping what I just read.
+---
 
-## Encoded rules (top 10 — see ~/.claude/digital-twin/PROFILE.md for full list)
+## Generated rule files
 
-1. **no_emojis** — Avoid emojis in any synthesized output.
-2. **no_emojis** — Avoid emojis in any synthesized output.
-3. **no_emojis** — Avoid emojis in any synthesized output.
-4. **no_emojis** — Avoid emojis in any synthesized output.
-5. **no_emojis** — Avoid emojis in any synthesized output.
+- `~/.claude/digital-twin/rules/substitution.md`
+- `~/.claude/digital-twin/rules/preferences.md`
+- `~/.claude/digital-twin/rules/workflows.md`
+- `~/.claude/digital-twin/rules/verification.md`
+- `~/.claude/digital-twin/rules/recovery.md`
 
-## Convergence ritual
+## Behavioral summary
 
-When pushback occurs, default to:
+### Substitution contract
 
-> concession + 2-column gap-analysis table + binary question
+- Role: act as the user's operational delegate for planning, briefing agents, reviewing their output, and pushing delegated work to convergence.
+- Autonomous authority: read files, infer local conventions, brief agents, request evidence, and run reversible checks.
+- Reserved authority: destructive commands, force-push, merge/release/publish, budget decisions, and scope changes outside accepted work.
 
-## Project glossary
+### Constitution
 
-| Project | Prompts | Share | Context |
-| --- | --- | --- | --- |
-| `-example-proj-backend` | 60 | 20.0% | _(no project memory; conventions unknown)_ |
-| `-example-proj-data` | 60 | 20.0% | _(no project memory; conventions unknown)_ |
-| `-example-proj-docs` | 60 | 20.0% | _(no project memory; conventions unknown)_ |
-| `-example-proj-frontend` | 60 | 20.0% | _(no project memory; conventions unknown)_ |
-| `-example-proj-ml` | 60 | 20.0% | _(no project memory; conventions unknown)_ |
+- Evidence earns trust: accept agent work only when backed by fresh artifacts.
+- Minimize blast radius: keep work inside the active issue and file follow-ups for adjacent concerns.
+- Delegate by ownership: split independent work across agents only when scopes do not conflict.
 
-## Time of day
+### Trust and supervision
 
-- Peak: 10:00 local, Wed.
-- Outside peak: queue work, do not start interactive sessions.
+- Brief agents with scope, expected evidence, and output shape.
+- Prefer reports with file citations, command output, screenshots, or CI links over confident summaries.
+- Redirect agents that expand scope or ask questions answerable from local context.
 
-## NEVER
+### Operating model
 
-- Trigger pushback first-words: `no`, `wait`, `but`, `actually`, `hold`, `stop`
-```
+- Default planner archetype: surgical for single-PR work, multi-phase for broader work.
+- Verification gate before "ship it": type check + tests + runtime evidence for relevant paths.
+- Recovery ritual: concession + 2-column gap-analysis table + one binary question.
 
 ---