@azure-id/orc 2.0.2 → 2.1.1

package/templates/skills/orc/references/ultra-mode.md

@@ -17,7 +17,7 @@ Apply at Phase 0, on top of the normal config resolution:
 - `pattern_findings` = on · `generate_tests` = on · `security_review` = on.
 - Executor **tier floor**: remap the resolved score→model table so no task
   dispatches below `orc-executor-sonnet-5-high`; bands at/above the opus
-  boundary (65) rise to at least `orc-executor-opus-5-low`. The floor only ever
+  boundary (41) rise to at least `orc-executor-opus-5-low`. The floor only ever
   raises a band, so the top `[90,100]` band keeps `orc-executor-opus-5-med`.
   **Under `opus5_only` the floor raises EFFORT, not model** (every band is
   already Opus 5.5, so there is no model left to raise): the `[0,90)` band rises

package/templates/skills/orc/schemas/checkpoint.md

@@ -1,122 +1,122 @@
-# Schema — Durable Checkpoint + State-of-Play
-
-Two files, two jobs:
-- `run/{run-slug}/checkpoint.json` — machine truth. Orchestrator-only writes.
-  Survives pause, compaction, crash, fresh sessions. KEPT after success (audit).
-- `run/{run-slug}/state-of-play.md` — 10-line human-readable re-anchor. Read FIRST on any
-  resume, then the checkpoint for detail.
-
-## run/{run-slug}/checkpoint.json
-
-```jsonc
-{
-  "run_id": "run-020726-1422",
-  "schema_version": "0.2",
-  "phase": "execution",        // intake|planning|scoring|execution|integration|review|verify|summary|ship|done
-  "planner": "openspec",
-  "effort": "medium",
-  "execution_model": "parallel",   // sequential | parallel | parallel_worktrees
-  "source_branch": "feat/notifications",
-  "intent_spec": "run/merchant-notifications/intent-spec.md",
-  "batch_pause_every": 2,
-  "pause_schedule": [2],           // wave indices where a MANDATORY batch stop fires
-                                   // (computed from the Phase 2 answer; last wave never included) —
-                                   // a resumed session enforces the same hard boundaries
-  "logging_enabled": true,         // logging is PERMANENT (always on) — re-anchor the behavior trace on resume
-  "trace_path": null,              // "<log_dir>/run-<lane>-<slug>-<DDMMYY>-<HHMMSS>.txt" — the run's trace file
-  "ultra_mode": false,             // true only on /orc-ultra runs; gates the "ultra" block below
-  "ultra": null,                   /* when ultra_mode — a resumed run continues mid-gate/mid-loop:
-    { "brief_path": "run/…/ultra/advisory-brief.md",
-      "ledger_path": "run/…/ultra/assumption-ledger.md",
-      "matrix_path": null,                    // set before gate 3
-      "gates": {                              // per-gate judgment state
-        "analysis":       { "verdict": "approve", "round": 1, "loops_used": 0 },
-        "plan":           { "verdict": "revise",  "round": 2, "loops_used": 1 },
-        "implementation": { "verdict": null,      "round": 0, "loops_used": 0 } } } */
-  "current_wave": 2,
-  "paused": true,
-  "pause_trigger": "batch_pause",  // batch_pause | token_limit | phase_transition | crash_guard
-
-  "plan": { /* full planning-output object */ },
-
-  // fast-resume mirror; kept in sync on every task state change
-  "task_state": {
-    "T1": { "status": "done", "retry_count": 0, "context_requests": 0,
-            "failure_reason": null, "progress": null,
-            "actual_files": ["db/migrations/0001.sql", "models/notification.x", "models/notification.test.x"] },
-    "T3": { "status": "partial", "retry_count": 0, "context_requests": 1,
-            "failure_reason": null,
-            "progress": { "percent": 60, "files_written": ["services/email_digest/scheduler.x"],
-                          "notes": "daily path done; weekly cron pending" } }
-  },
-
-  // every spawn, for the usage report + rubric audit
-  "dispatch_log": [
-    { "task_id": "T1", "computed_score": 72, "override_score": null,
-      "override_reason": null, "model": "sonnet-5", "effort": "medium",
-      "spawned_at": "020726 14:24:01.100",
-      // claimed-vs-actual (only when logging_enabled): what the worker reported
-      "actual_model": "claude-sonnet-5", "actual_effort": "medium",
-      "verify": "match" },      // match | downgrade
-
-    { "task_id": "T6", "computed_score": 88, "override_score": 62,
-      "override_reason": "rubric over-weighted file count; isolated leaf UI",
-      "model": "sonnet-5", "effort": "high", "spawned_at": "020726 15:01:22.040" }
-  ],
-
-  "worktrees": { /* subagent_worktrees mode: agent → {path, branch, merged} */ },
-  "merge_state": null,           // null | pending_verify | merged | conflict_resolving
-
-  "escalations": [
-    { "id": "E1", "agent": "Agent-C", "task": "T3",
-      "question": "Digest send time?", "answer": "07:00 fixed",
-      "at": "020726 14:28:41.507",
-      "affected_tasks": [], "downstream_flagged": [] }
-  ],
-
-  "review":  { "ran": false },   // when ran: p0[], p1[], p2[], p3[], model, effort
-                                 // (v1 checkpoints used blocking[]/nits[] — on resume
-                                 //  map blocking→p1, nits→p3; never rewrite the old file.
-                                 //  v0.7.0+: each recorded P0–P2 finding keeps its
-                                 //  file:line + verbatim quote so a resumed run can
-                                 //  re-run the quote spot-check before acting)
-  "verify":  { "ran": false },   // result, autofix_used, autofix_remaining (starts 1)
-  "ship":    { "commit": null, "push": null, "create_pr": null,
-               "ticket": null, "pr_title": null, "target_branch": null, "pr_file": null },
-
-  "decision_log": "run/merchant-notifications/decision-log.md",
-  "created_at": "020726 14:22:01.000",
-  "updated_at": "020726 15:02:00.331"
-}
-```
-
-## run/{run-slug}/state-of-play.md (regenerated at every checkpoint write)
-
-```markdown
-# State of Play — run-020726-1422
-Phase: execution · Wave 2 of 3 · PAUSED (batch)
-Done: T1 T2 T4 · Partial: T3 (60%, weekly cron pending) · Pending: T5 T6
-Mode: subagent · Planner: openspec · Branch: feat/notifications
-Last decision: digest send 07:00 fixed (user, via Agent-C)
-Next action on resume: finish T3 from milestone, then dispatch wave 3
-Intent: merchant notifications (in-app + email digest + prefs) — no push, no admin
-```
-
-## Write discipline
-
-- Orchestrator-only. Atomic write (temp file + rename). `updated_at` bumped to
-  ms on every write.
-- Write EAGERLY: after every wave, escalation answer, phase transition, and
-  before any risky operation — so surprise compaction never catches
-  conversation-only state.
-- A failed/malformed checkpoint write is a FAILURE: do not stop the session on
-  it; surface it.
-
-## Resume contract
-
-1. Read state-of-play (orientation) → newest checkpoint (`updated_at` wins).
-2. Fresh session: one-line intent reconfirm from the Intent line.
-3. task_state: done stays done · partial resumes from progress.files_written ·
-   pending awaits wave · requeued/failed re-dispatch reading failure_reason ·
-   stale_review gets a review pass.
-4. Re-attach decision log, regenerate digest, continue from `phase`.
+# Schema — Durable Checkpoint + State-of-Play
+
+Two files, two jobs:
+- `run/{run-slug}/checkpoint.json` — machine truth. Orchestrator-only writes.
+  Survives pause, compaction, crash, fresh sessions. KEPT after success (audit).
+- `run/{run-slug}/state-of-play.md` — 10-line human-readable re-anchor. Read FIRST on any
+  resume, then the checkpoint for detail.
+
+## run/{run-slug}/checkpoint.json
+
+```jsonc
+{
+  "run_id": "run-020726-1422",
+  "schema_version": "0.2",
+  "phase": "execution",        // intake|planning|scoring|execution|integration|review|verify|summary|ship|done
+  "planner": "openspec",
+  "effort": "medium",
+  "execution_model": "parallel",   // sequential | parallel | parallel_worktrees
+  "source_branch": "feat/notifications",
+  "intent_spec": "run/merchant-notifications/intent-spec.md",
+  "batch_pause_every": 2,
+  "pause_schedule": [2],           // wave indices where a MANDATORY batch stop fires
+                                   // (computed from the Phase 2 answer; last wave never included) —
+                                   // a resumed session enforces the same hard boundaries
+  "logging_enabled": true,         // logging is PERMANENT (always on) — re-anchor the behavior trace on resume
+  "trace_path": null,              // "<log_dir>/run-<lane>-<slug>-<DDMMYY>-<HHMMSS>.txt" — the run's trace file
+  "ultra_mode": false,             // true only on /orc-ultra runs; gates the "ultra" block below
+  "ultra": null,                   /* when ultra_mode — a resumed run continues mid-gate/mid-loop:
+    { "brief_path": "run/…/ultra/advisory-brief.md",
+      "ledger_path": "run/…/ultra/assumption-ledger.md",
+      "matrix_path": null,                    // set before gate 3
+      "gates": {                              // per-gate judgment state
+        "analysis":       { "verdict": "approve", "round": 1, "loops_used": 0 },
+        "plan":           { "verdict": "revise",  "round": 2, "loops_used": 1 },
+        "implementation": { "verdict": null,      "round": 0, "loops_used": 0 } } } */
+  "current_wave": 2,
+  "paused": true,
+  "pause_trigger": "batch_pause",  // batch_pause | token_limit | phase_transition | crash_guard
+
+  "plan": { /* full planning-output object */ },
+
+  // fast-resume mirror; kept in sync on every task state change
+  "task_state": {
+    "T1": { "status": "done", "retry_count": 0, "context_requests": 0,
+            "failure_reason": null, "progress": null,
+            "actual_files": ["db/migrations/0001.sql", "models/notification.x", "models/notification.test.x"] },
+    "T3": { "status": "partial", "retry_count": 0, "context_requests": 1,
+            "failure_reason": null,
+            "progress": { "percent": 60, "files_written": ["services/email_digest/scheduler.x"],
+                          "notes": "daily path done; weekly cron pending" } }
+  },
+
+  // every spawn, for the usage report + rubric audit
+  "dispatch_log": [
+    { "task_id": "T1", "computed_score": 72, "override_score": null,
+      "override_reason": null, "model": "sonnet-5", "effort": "medium",
+      "spawned_at": "020726 14:24:01.100",
+      // claimed-vs-actual (only when logging_enabled): what the worker reported
+      "actual_model": "claude-sonnet-5-5", "actual_effort": "medium",
+      "verify": "match" },      // match | downgrade
+
+    { "task_id": "T6", "computed_score": 88, "override_score": 62,
+      "override_reason": "rubric over-weighted file count; isolated leaf UI",
+      "model": "sonnet-5", "effort": "high", "spawned_at": "020726 15:01:22.040" }
+  ],
+
+  "worktrees": { /* subagent_worktrees mode: agent → {path, branch, merged} */ },
+  "merge_state": null,           // null | pending_verify | merged | conflict_resolving
+
+  "escalations": [
+    { "id": "E1", "agent": "Agent-C", "task": "T3",
+      "question": "Digest send time?", "answer": "07:00 fixed",
+      "at": "020726 14:28:41.507",
+      "affected_tasks": [], "downstream_flagged": [] }
+  ],
+
+  "review":  { "ran": false },   // when ran: p0[], p1[], p2[], p3[], model, effort
+                                 // (v1 checkpoints used blocking[]/nits[] — on resume
+                                 //  map blocking→p1, nits→p3; never rewrite the old file.
+                                 //  v0.7.0+: each recorded P0–P2 finding keeps its
+                                 //  file:line + verbatim quote so a resumed run can
+                                 //  re-run the quote spot-check before acting)
+  "verify":  { "ran": false },   // result, autofix_used, autofix_remaining (starts 1)
+  "ship":    { "commit": null, "push": null, "create_pr": null,
+               "ticket": null, "pr_title": null, "target_branch": null, "pr_file": null },
+
+  "decision_log": "run/merchant-notifications/decision-log.md",
+  "created_at": "020726 14:22:01.000",
+  "updated_at": "020726 15:02:00.331"
+}
+```
+
+## run/{run-slug}/state-of-play.md (regenerated at every checkpoint write)
+
+```markdown
+# State of Play — run-020726-1422
+Phase: execution · Wave 2 of 3 · PAUSED (batch)
+Done: T1 T2 T4 · Partial: T3 (60%, weekly cron pending) · Pending: T5 T6
+Mode: subagent · Planner: openspec · Branch: feat/notifications
+Last decision: digest send 07:00 fixed (user, via Agent-C)
+Next action on resume: finish T3 from milestone, then dispatch wave 3
+Intent: merchant notifications (in-app + email digest + prefs) — no push, no admin
+```
+
+## Write discipline
+
+- Orchestrator-only. Atomic write (temp file + rename). `updated_at` bumped to
+  ms on every write.
+- Write EAGERLY: after every wave, escalation answer, phase transition, and
+  before any risky operation — so surprise compaction never catches
+  conversation-only state.
+- A failed/malformed checkpoint write is a FAILURE: do not stop the session on
+  it; surface it.
+
+## Resume contract
+
+1. Read state-of-play (orientation) → newest checkpoint (`updated_at` wins).
+2. Fresh session: one-line intent reconfirm from the Intent line.
+3. task_state: done stays done · partial resumes from progress.files_written ·
+   pending awaits wave · requeued/failed re-dispatch reading failure_reason ·
+   stale_review gets a review pass.
+4. Re-attach decision log, regenerate digest, continue from `phase`.

package/templates/skills/orc/subskills/orc-review-verify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: orc-review-verify
 description: >
-  Review/verify worker for ORC Phases 5–6 (Opus 5.5 medium). Two modes: a REVIEW
+  Review/verify worker for ORC Phases 5–6 (review Opus 5.5 low, verify medium). Two modes: a REVIEW
   pass — examine the changed files against the code pattern + constraints,
   create/update tests, and classify EVERY finding on the P0–P3 severity
   ladder (P0/P1 gate ship, P2/P3 advisory); a VERIFY
@@ -23,13 +23,13 @@ owns the auto-fix-once loop.
 
 - **Input slice** (the orchestrator builds it): `core.md`.
 - **Procedure + return contract** (the ONE source): the agent file —
-  `phase=review` and `phase=security` → `.claude/agents/orc-reviewer-opus-5-med.md`;
+  `phase=review` and `phase=security` → `.claude/agents/orc-reviewer-opus-5-low.md`;
   `phase=verify` → `.claude/agents/orc-verifier-opus-5-med.md`.
 - **Validator** (the caller checks every return against it):
   `../../../_shared/return-validation.md`. A malformed return is treated as
   failure by the caller.
 
 Fixed models (from `../../references/effort-and-mode.md`): review on the OpenSpec/self
-path = Opus 5.5 medium; review on the Superpowers path is delegated to the
+path = Opus 5.5 low; review on the Superpowers path is delegated to the
 Superpowers review skill instead (Sonnet 4.6 medium). Verify = Opus 5.5 medium,
 always this subskill.

package/templates/skills/orc/subskills/orc-review-verify/core.md

@@ -2,7 +2,7 @@
 
 The INPUT SLICE the orchestrator builds for ONE review, verify or security
 dispatch. The procedure and the return contract live in ONE place, the agent
-file: `phase=review` and `phase=security` → `.claude/agents/orc-reviewer-opus-5-med.md`;
+file: `phase=review` and `phase=security` → `.claude/agents/orc-reviewer-opus-5-low.md`;
 `phase=verify` → `.claude/agents/orc-verifier-opus-5-med.md`. The caller owns
 the auto-fix-once loop and the `tdd_loop_max` repair loop, and validates the
 return against `../../../_shared/return-validation.md`.

package/templates/skills/orc-analyze/SKILL.md

@@ -91,7 +91,9 @@ without the manifest (`../_shared/lane-contract.md` §Phases).
 
 ## Phase A — Ingest & detect source mode
 
-Read the source. **Auto-detect** which of three modes applies:
+First `orc lane config orc-analyze --json`. **`habits{}` in it → print
+`habits.line`, read `../_shared/habits.md` NOW**; none → ignore every `(H …)`.
+Then read the source. **Auto-detect** which of three modes applies:
 - **prose/spec** — a document of narrative requirements, or
 - **audit/structured** — a document with columns like expectation / notes / result, or
 - **requirement** — NO document; the user's plain-language request is the source
@@ -213,7 +215,7 @@ exist). Menu rules, relatedness gate, combiner handling:
 - **Config:** `orc lane config orc-analyze --json`. Obey `effective`, print every line
   in `announce[]` VERBATIM at preflight, and honour `stops[]` before wave 1.
   Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
-- **Habits:** `habits{}` in that answer → `../_shared/habits.md`; else ignore `(H …)`.
+- **Habits:** Phase A, first step.
 - **Rules:** `orc rules slice --lane orc-analyze --json` is the ONLY assembler
   (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
 

package/templates/skills/orc-claude/SKILL.md

@@ -10,7 +10,7 @@ description: >
   template the user fills in themself. Refresh regenerates ONLY stale sections
   and bumps the file version by 0.0.1. Never trims user-authored content;
   never touches the orc-wiki pointer block. The skill dispatches the pinned
-  orc-claude-writer-opus-4-8-high agent — it never writes the file itself.
+  orc-claude-writer-opus-5-low agent — it never writes the file itself.
 ---
 
 # ORC-CLAUDE (standalone)
@@ -20,11 +20,11 @@ The target is ALWAYS `<repo root>/CLAUDE.md` of the current working directory
 never `~/.claude/CLAUDE.md`, even if ORC is installed globally.
 
 **Dispatch, don't do.** Whatever model this chat runs on, the skill itself only
-selects the mode and spawns `orc-claude-writer-opus-4-8-high` (the pinned
-engine) — so the scan + writing always run at Opus 4.8 high regardless of the
-caller's tier. When `opus5_only: true` the engine is
-`orc-claude-writer-opus-5-med` instead (that mode FORCES it — see
-`../_shared/opus5-only.md`), and it then needs an Opus 5.5 main session.
+selects the mode and spawns `orc-claude-writer-opus-5-low` (the pinned
+engine) — so the scan + writing always run at Opus 5.5 low regardless of the
+caller's tier. `opus5_only` does not change this role. The writer is already
+Opus 5.5 low, so that mode has nothing to flip (see `../_shared/opus5-only.md`).
+The writer needs an Opus 5.5 main session in both modes.
 The one exception: the skill also writes the
 trace pointer + a few markers around that spawn (behavior-trace logging is
 permanent; see "Behavior trace"); that
@@ -70,18 +70,18 @@ set in "Behavior trace").
    `touch the trace file` of that name in the SAME step, BEFORE the spawn (a
    pointer to a file that does not exist reads as dangling — the hook rotates
    away from it and the run splits across two files).
-2. Spawn `orc-claude-writer-opus-4-8-high` — or `orc-claude-writer-opus-5-med`
-   when `opus5_only` — with: `mode`, `repo_root`,
+2. Spawn `orc-claude-writer-opus-5-low` (also under `opus5_only` — that mode
+   does not change this role) with: `mode`, `repo_root`,
    `budget` (from a `budget=N` argument, else null), and the paths to
    `references/template.md` + `references/refresh.md`. **Trace:** emit
-   `DISPATCH orc-claude-writer :: <mode> expect=opus-4-8/high` just before the
-   spawn (`expect=opus-5/medium` under `opus5_only` — the expectation is
-   derived from the agent NAME you actually dispatched, never from this line's
-   default; the hook then adds `SPAWN`/`RETURN` on its own).
+   `DISPATCH orc-claude-writer :: <mode> expect=opus-5/low` just before the
+   spawn (the expectation is derived from the agent NAME you actually
+   dispatched, never from this line's default; the hook then adds
+   `SPAWN`/`RETURN` on its own).
 3. On return, check `actual_model`/`actual_effort` against the pinned tier —
    mismatch → prepend a tier-downgrade warning to the report. **Trace:** emit
    `VERIFY writer actual=<model>/<effort> ✅ MATCH` (or
-   `⛔ DOWNGRADE expected=opus-4-8/high`).
+   `⛔ DOWNGRADE expected=opus-5/low`).
 4. Relay the Phase-3 report verbatim. **Trace:** emit
    `FINISH :: <mode_ran> CLAUDE.md v<X.Y.Z>` (mode_ran may be `noop`), then
    delete `log_dir/.current`. Then stop. The skill NEVER writes CLAUDE.md
@@ -175,7 +175,7 @@ Dispatch-only lane: emit ONLY the markers it can truthfully witness — **not**
 `PHASE`/`SCORE`/`FINDING`/`VERDICT`, because scan/generate/report run INSIDE
 the writer sub-agent and there is no scoring or review here. The marker set, in
 order (actor `orc`, plus the hook's `SPAWN`/`RETURN`): `DISPATCH
-orc-claude-writer :: <mode> expect=opus-4-8/high` before the spawn (the mode
+orc-claude-writer :: <mode> expect=opus-5/low` before the spawn (the mode
 rides in this tail and in `FINISH`, so no separate mode marker) · `VERIFY writer
 actual=<model>/<effort>` · `FINISH :: <mode_ran> CLAUDE.md v<X.Y.Z>`, where
 `mode_ran` may be `noop`. A noop refresh still traces the full cycle.

package/templates/skills/orc-claude/examples/claude-run-mock.md

@@ -1,65 +1,65 @@
-# Worked example — orc-claude runs (mock; orient only, never execute from this)
-
-## Run 1 — UPDATE (existing hand-written CLAUDE.md, 610 lines)
-
-U: /orc-claude
-C: CLAUDE.md exists, no orc-claude:meta header → UPDATE mode. Spawns
-   orc-claude-writer-opus-4-8-high (the skill never writes the file itself).
-W: Scans: pnpm monorepo (3 workspaces), turbo, eslint+prettier, vitest,
-   Postgres migrations under `packages/db/migrations`.
-W: Copies CLAUDE.md → CLAUDE.md.bak. Injects meta header (v0.0.1, 12-07-2026,
-   line-budget: 400) + P0 placeholder at top, appends fenced sections:
-   commands, layout (ownership map), conventions, boundaries, workflow,
-   decisions, patterns, gotchas placeholder, testing, environment, glossary
-   placeholder. Skips `adr` (nothing scannable). Existing 610 lines: untouched.
-
-```
-ORC-CLAUDE — update → CLAUDE.md v0.0.1 (12-07-2026)
-Sections written: p0*, commands, layout, conventions, boundaries, workflow,
-decisions, patterns, gotchas*, testing, environment, glossary*   (*=fill yourself)
-Skipped (empty scan): adr, pointers
-Preserved untouched: user content (610 lines), no wiki block found
-Conflicts flagged (NOT auto-edited):
-  - existing line 42 says "run yarn test" — repo uses pnpm (pnpm test)
-Backup: CLAUDE.md.bak written (add it to .gitignore)
-NOTE: file is 802 lines total (budget covers generated content only) — trim
-unused user content yourself for better instruction-following.
-```
-
-## Run 2 — REFRESH, one stale section
-
-U: /orc-claude   (weeks later; `test` script renamed to `test:unit` + `test:e2e`)
-C: Header found → REFRESH → spawns the writer.
-W: Recomputes fingerprints: only `commands` differs (e3f1a2 → 8c04b1). Writes
-   .bak, replaces the commands fence interior, bumps 0.0.1 → 0.0.2,
-   updated: 03-08-2026. User's edits outside fences + the wiki block:
-   byte-identical. Returns actual_model=claude-opus-4-8, actual_effort=high.
-
-## Run 3 — REFRESH, noop
-
-U: /orc-claude
-W: All fingerprints match →
-   `CLAUDE.md up to date (v0.0.2, 03-08-2026)` — no write, no bump, no bak.
-
-## Run 4 — behavior trace (permanent, always on)
-
-Same dispatch as any run, plus the minimal one-dispatch trace. The skill writes
-the run pointer (`run-claude-<slug>-<DDMMYY>-<HHMMSS>.txt` into `log_dir`)
-FIRST, records these events as they happen, and — as a single-dispatch lane —
-dispatches the trace writer ONCE at run end to append them (`SPAWN`/`RETURN`
-come from the `orc-trace.js` hook as they occur):
-
-```
-[120726 09:14:02.110] writer   DISPATCH orc-claude-writer :: refresh expect=opus-4-8/high
-[120726 09:14:02.230] hook     SPAWN orc-claude-writer-opus-4-8-high
-[120726 09:15:47.900] hook     RETURN
-[120726 09:15:48.010] writer   VERIFY writer actual=claude-opus-4-8/high ✅ MATCH
-[120726 09:15:48.120] writer   FINISH :: refresh CLAUDE.md v0.0.3
-```
-
-Then the writer packet returns and the run pointer is deleted (in that order).
-A noop refresh traces the same shape, ending
-`FINISH :: noop`. No phase/score/gate/finding/verdict markers — orc-claude
-runs none of those phases (they live inside the writer). The `orc-trace.js` hook
-bootstraps the pointer on the writer dispatch, so the SPAWN/RETURN skeleton is
-captured even if the skill's run-start step is skipped.
+# Worked example — orc-claude runs (mock; orient only, never execute from this)
+
+## Run 1 — UPDATE (existing hand-written CLAUDE.md, 610 lines)
+
+U: /orc-claude
+C: CLAUDE.md exists, no orc-claude:meta header → UPDATE mode. Spawns
+   orc-claude-writer-opus-5-low (the skill never writes the file itself).
+W: Scans: pnpm monorepo (3 workspaces), turbo, eslint+prettier, vitest,
+   Postgres migrations under `packages/db/migrations`.
+W: Copies CLAUDE.md → CLAUDE.md.bak. Injects meta header (v0.0.1, 12-07-2026,
+   line-budget: 400) + P0 placeholder at top, appends fenced sections:
+   commands, layout (ownership map), conventions, boundaries, workflow,
+   decisions, patterns, gotchas placeholder, testing, environment, glossary
+   placeholder. Skips `adr` (nothing scannable). Existing 610 lines: untouched.
+
+```
+ORC-CLAUDE — update → CLAUDE.md v0.0.1 (12-07-2026)
+Sections written: p0*, commands, layout, conventions, boundaries, workflow,
+decisions, patterns, gotchas*, testing, environment, glossary*   (*=fill yourself)
+Skipped (empty scan): adr, pointers
+Preserved untouched: user content (610 lines), no wiki block found
+Conflicts flagged (NOT auto-edited):
+  - existing line 42 says "run yarn test" — repo uses pnpm (pnpm test)
+Backup: CLAUDE.md.bak written (add it to .gitignore)
+NOTE: file is 802 lines total (budget covers generated content only) — trim
+unused user content yourself for better instruction-following.
+```
+
+## Run 2 — REFRESH, one stale section
+
+U: /orc-claude   (weeks later; `test` script renamed to `test:unit` + `test:e2e`)
+C: Header found → REFRESH → spawns the writer.
+W: Recomputes fingerprints: only `commands` differs (e3f1a2 → 8c04b1). Writes
+   .bak, replaces the commands fence interior, bumps 0.0.1 → 0.0.2,
+   updated: 03-08-2026. User's edits outside fences + the wiki block:
+   byte-identical. Returns actual_model=claude-opus-4-8, actual_effort=high.
+
+## Run 3 — REFRESH, noop
+
+U: /orc-claude
+W: All fingerprints match →
+   `CLAUDE.md up to date (v0.0.2, 03-08-2026)` — no write, no bump, no bak.
+
+## Run 4 — behavior trace (permanent, always on)
+
+Same dispatch as any run, plus the minimal one-dispatch trace. The skill writes
+the run pointer (`run-claude-<slug>-<DDMMYY>-<HHMMSS>.txt` into `log_dir`)
+FIRST, records these events as they happen, and — as a single-dispatch lane —
+dispatches the trace writer ONCE at run end to append them (`SPAWN`/`RETURN`
+come from the `orc-trace.js` hook as they occur):
+
+```
+[120726 09:14:02.110] writer   DISPATCH orc-claude-writer :: refresh expect=opus-5/low
+[120726 09:14:02.230] hook     SPAWN orc-claude-writer-opus-5-low
+[120726 09:15:47.900] hook     RETURN
+[120726 09:15:48.010] writer   VERIFY writer actual=claude-opus-5-5/low ✅ MATCH
+[120726 09:15:48.120] writer   FINISH :: refresh CLAUDE.md v0.0.3
+```
+
+Then the writer packet returns and the run pointer is deleted (in that order).
+A noop refresh traces the same shape, ending
+`FINISH :: noop`. No phase/score/gate/finding/verdict markers — orc-claude
+runs none of those phases (they live inside the writer). The `orc-trace.js` hook
+bootstraps the pointer on the writer dispatch, so the SPAWN/RETURN skeleton is
+captured even if the skill's run-start step is skipped.

package/templates/skills/orc-diy/SKILL.md

@@ -49,13 +49,14 @@ unavailable, apply the same checks manually from
 
 ## Step 2 — dispatch the compiled flow
 
+First `orc lane config orc-diy --json`. **`habits{}` in it → print `habits.line`,
+read `../_shared/habits.md` NOW**; none → ignore every `(H …)`. Then:
 Read `.claude/orc/diy/FLOW-COMPILED.md` and follow it as your orchestrator
 spine for this run — it is self-contained: tier self-check, locked rules,
 phase sequence, and the references it cherry-picks from the installed orc
 skill. Honor its generated header: if its own self-gate fails, stop exactly
-as it says. Do not consult this stub again for the rest of the run, and do
-not load orc's SKILL.md as a spine (the compiled flow already references the
-exact orc subskills and schemas it needs).
+as it says. Never consult this stub again this run, and never load orc's
+SKILL.md as a spine — the flow names every subskill and schema it needs.
 
 ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
 
@@ -64,8 +65,7 @@ exact orc subskills and schemas it needs).
 - **Config:** `orc lane config orc-diy --json`. Obey `effective`, print every line
   in `announce[]` VERBATIM at preflight, and honour `stops[]` before wave 1.
   Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
-- **Habits:** `habits{}` in the config answer → read `../_shared/habits.md`. No
-  `habits{}` → ignore every `(H …)` mark.
+- **Habits:** Step 2, first.
 - **Rules:** `orc rules slice --lane orc-diy --json` is the ONLY assembler
   (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.