@azure-id/orc 0.55.0

package/templates/skills/orc/subskills/orc-checkpoint/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: orc-checkpoint
+description: >
+  Stateless persistence service for ORC — the checkpoint read/write engine. On a
+  trigger passed in by the orchestrator (batch_pause | token_limit |
+  phase_transition | crash_guard), it atomically writes
+  run/{slug}/checkpoint.json, regenerates the 10-line state-of-play.md, then reads
+  both back and validates; the read op locates the newest valid checkpoint for a
+  fresh-session resume. It makes NO judgment — it never decides WHEN to stop or
+  resume (the orchestrator owns that and passes the trigger in). Coordination
+  skill: always runs inline (loaded by the orchestrator), never spawned. Not for
+  direct user invocation.
+---
+
+# orc-checkpoint
+
+## Boundary (locked in design)
+
+- Orchestrator DECIDES: when to checkpoint, when to stop, when/whether to
+  resume. These judgments need full run context and never leave the orchestrator.
+- This skill EXECUTES: serialize/write atomically, read/validate back. It makes
+  no judgment; the `trigger` is an input, already decided.
+
+## Write operation
+
+Input: run_state (the checkpoint fields per `../../schemas/checkpoint.md`),
+       trigger (batch_pause | token_limit | phase_transition | crash_guard)
+
+Minimal `run_state` shape (see `../../schemas/checkpoint.md` for the full field set):
+```json
+{ "run_slug": "merchant-notifications", "phase": 3, "updated_at": "2026-07-10T09:00:00Z",
+  "tasks": [ { "id": "T1", "status": "done", "actual_files": ["services/notify.ts"] } ],
+  "resume_pointer": "wave 2 of 3", "logging_enabled": true }
+```
+Steps:
+1. Serialize run_state to JSON.
+2. Atomic write: temp file → rename to run/{run-slug}/checkpoint.json.
+3. Regenerate run/{run-slug}/state-of-play.md from the same state (10-line format per
+   `../../schemas/checkpoint.md`).
+4. Read back and validate both writes.
+Return: { checkpoint_path, state_of_play_path, written_at, resume_pointer }
+
+A failed or unvalidated write returns failure — the caller must NOT stop the
+session on a failed write; it surfaces the failure instead.
+
+## Read operation
+
+Input: run_id (or "newest")
+Steps: locate the run subfolder, then newest valid checkpoint by updated_at → parse → validate schema.
+Return: { run_state, resume_pointer } or failure if none valid.
+
+## What this skill never does
+
+- Decide to stop. Announce a pause. Talk to the user. Modify task logic.
+- Write anything other than the two files above.

package/templates/skills/orc/subskills/orc-execution/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: orc-execution
+description: >
+  Executor worker for ORC — the single-task implementer. Given one task slice
+  (task_id, declared_files, constraints, spec_ref, log_digest), it implements
+  EXACTLY that task within its declared files, honors every hard-rule constraint,
+  creates/updates tests, emits milestone progress pings, and returns a strict
+  contract (status done|failed|partial|needs_context, actual_files, log_entries,
+  and claimed-vs-actual model/effort so the caller can catch a silent tier
+  downgrade). Dispatched once per task in an execution wave, on the scored model
+  pinned by its executor agent. Distinct from the review/verify/test-author
+  workers — this one writes the implementation. ALWAYS a spawned subagent; the
+  orchestrator never implements. Not for direct user invocation.
+---
+
+# orc-execution
+
+One entry point: the orchestrator spawns a subagent via the Task tool,
+prepending `subagent.md` framing + the input slice, which points to `core.md`.
+`core.md` is the AUTHORITATIVE spec (full input slice, procedure, and return
+contract); the summary below orients — on any conflict, `core.md` wins.
+
+## What the worker does (summary)
+
+1. Absorb `log_digest` (prior DECISIONs/INTERFACEs/ANSWERs bind you); read `spec_ref`.
+2. Implement EXACTLY the task in the slice, touching only `declared_files[]`,
+   honoring every `constraints[]` hard rule AND the standing `house_rules` card
+   (surgical changes, simplicity-first, no unrequested scope, never claim
+   unobserved results, honest partial over false done); create/update
+   tests for what you build.
+3. Run the proof: build/test for your changes, capturing `evidence`
+   {command, exit_code, tail} VERBATIM (no runner → `no_runner_detected: true`);
+   self-check the diff against the slice's `acceptance[]` + `constraints[]` —
+   anything unsatisfied goes in `unmet[]` (non-empty = partial/failed, never done).
+4. Emit milestone pings ({percent, files_written[], notes}) as you go.
+5. Stay in your slice — need outside context? emit `needs_context`, don't fetch it.
+
+## Return shape (summary — full contract in `core.md`)
+
+`{ task_id, actual_model, actual_effort, status: done|failed|partial|needs_context,
+actual_files[], evidence, no_runner_detected, unmet[], log_entries[],
+failure_reason, progress, context_request,
+pattern_version, invariants_checked, tdd_state }`
+
+When the slice carries a `pattern`, MATCH its conventions, satisfy every BLOCKING
+invariant AND every enforceable `validation_gate[]` line (advisory gate lines are
+informational); echo the `pattern_version` and set `invariants_checked: true` only after
+re-checking your diff. A pattern task that returns false/absent here is malformed.
+
+When the slice carries a `tdd_spec` (v0.33.0), run its materialized tests and
+implement to green — implement→test→repair, capped at the slice's
+`tdd_loop_max`; never edit a TDD test to make it pass (a wrong-looking test is
+a spec bug — return it). Return `tdd_state: green|red` (green needs the passing
+run in `evidence`; `done` with red is malformed).
+
+**Crosslink injection (orchestrator-side, advisory).** At slice assembly, if a
+task's declared files include a call site that matches an entry in
+`.claude/orc/crosslink/needs.json`, prepend the cached tag contract (from
+`.claude/orc/crosslink/cache/`) to the slice as `crosslink`, labeled with its
+effective cross-repo tier + "hints, not verified". The executor MATCHES the
+stated field names/types but never lets it override local code — it is advisory,
+so there is NO return field and nothing to attest (unlike `pattern`). A task with
+no boundary carries no `crosslink`.
+On a UI task, if the environment ships a `frontend-design` skill, read and apply
+it (skip silently when absent).
+
+**Validation checkpoint before returning:** `status=failed` REQUIRES a
+`failure_reason`; `needs_context` REQUIRES a `context_request` (capped at 2/task);
+`actual_model` is quoted VERBATIM from your system prompt, never inferred;
+`status=done` REQUIRES `evidence` when a runner exists (else
+`no_runner_detected: true`) and an EMPTY `unmet[]`. A
+malformed return is treated as failure by the caller.

package/templates/skills/orc/subskills/orc-execution/core.md

@@ -0,0 +1,151 @@
+# orc-execution — Core (mode-neutral)
+
+A procedure specification: inputs, steps, outputs. Executed by a spawned
+subagent; the orchestrator never runs this itself.
+
+## Input slice (you receive exactly this; you cannot pull more)
+
+- task_id, description, spec_ref
+- declared_files[]        — the files you are expected to touch (incl. tests)
+- acceptance[]            — this task's sliced definition-of-done lines (from the
+                            plan); self-check your diff against them before returning
+- constraints[]           — HARD RULES from the intent-spec, plus the task's
+                            `spec_invariants` (analyst do-not-build invariants)
+                            appended verbatim at slice assembly; never violate
+- pattern                 — the resolved code-pattern for this task's language, or
+                            null. When present: {conventions[] you MUST MATCH,
+                            invariants[] that are BLOCKING, validation_gate[]
+                            (enforceable acceptance checks you must SATISFY —
+                            advisory lines are marked and informational),
+                            pattern_version}. Agnostic
+                            tasks carry invariants only (no conventions, no gate).
+- wiki                    — project-wiki grounding for this task, or absent:
+                            page CONTENT (full/mini) or page PATHS to read first
+                            (fast), plus the freshness tier in force. Precedence
+                            is always `code > fresh wiki > stale wiki (hints) >
+                            model priors` — on any wiki-vs-code conflict the code
+                            wins. You MUST return `wiki_used` naming the pages
+                            you actually read, or `none`; see the return
+                            contract. Absent on a task the orchestrator grounded
+                            without the wiki.
+- crosslink               — the cross-repo boundary contract for a call site in
+                            this task, or null. Present ONLY when a declared file
+                            touches a boundary the orchestrator resolved from
+                            `.claude/orc/crosslink/needs.json` + cache. It is
+                            ADVISORY hints ("cross-repo fresh/aging/stale wiki")
+                            labeled with an effective tier — MATCH the field
+                            names/types/errors it states, but it never overrides
+                            local code and there is nothing to attest (no return
+                            field). Absent on any task with no boundary.
+- gotchas                 — 0–3 repair-memory entries whose `scope` glob matches
+                            this task's declared_files, or absent. Each is one
+                            failure THIS PROJECT already hit and fixed
+                            {trigger, symptom, cause, fix}. Read them as a
+                            "don't re-pay for this" list, not as requirements:
+                            they never override `acceptance[]`, `constraints[]`
+                            or the pattern's invariants. Absent = no match, which
+                            is the normal case — never treat absence as a signal.
+                            Canonical: `.claude/skills/_shared/gotchas.md`.
+- tdd_spec                — this task's plan-time acceptance tests, or null
+                            (TDD off, or every entry scoped out as
+                            covered-by-existing / no-behavior / no-runner —
+                            null is NOT "untested"). Present = the failing tests
+                            a PAIRED TDD task already materialized, which your
+                            work must
+                            turn GREEN, plus `tdd_loop_max` (the repair cap).
+                            Never edit a TDD test to make it pass — a test
+                            that looks wrong is a spec bug: return it, don't
+                            fix it.
+- house_rules             — the standing behavioral card (injected literally,
+                            never a pointer): surgical changes, simplicity-first,
+                            no unrequested scope, boring-solution preference
+- log_digest              — compacted decisions from prior waves; absorb before working
+- worktree_path           — null unless worktrees mode
+- model, effort           — informational (already applied by the caller)
+
+## Procedure
+
+1. Absorb log_digest — prior DECISIONs/INTERFACEs/ANSWERs bind you.
+2. Read spec_ref if provided.
+2a. **Read on the ladder** (`../../../_shared/read-ladder.md`): locate
+   (Grep/Glob) → outline → the ±40 lines around the anchor → full. Stop at the
+   step that answers the question; two full reads with no answer is
+   `needs_context`, not a third. TWO EXCEPTIONS — every `declared_files` path is
+   a FULL read before you edit it (an `old_string` rebuilt from an outline is a
+   corruption bug), and build/test output is always read whole.
+3. Perform the task within `worktree_path` (or the current tree if null).
+   Obey every `house_rules` line. Follow every constraint. If `pattern` is present, MATCH its conventions,
+   satisfy every BLOCKING invariant, and satisfy every enforceable
+   `validation_gate[]` line (re-read your diff to confirm before returning;
+   advisory gate lines are informational — never add tooling to meet one);
+   if `pattern` is null but carries invariants (agnostic), still satisfy them and
+   imitate the neighboring files you read. Create/update tests for what you build.
+   **UI task + a `frontend-design` skill present in the environment** (check
+   `.claude/skills/frontend-design/` or the plugin dir): read its SKILL.md and
+   apply its guidance to the UI work — skip silently when absent.
+4. **Run the proof, capture the evidence:** if the project has a runnable build
+   or test setup, run it for your changes and capture {command, exit_code, the
+   last ~5 output lines} — QUOTED VERBATIM, never paraphrased, never predicted.
+   No runner → set `no_runner_detected: true` instead. Never claim green you
+   did not observe. With a `tdd_spec`: run ITS tests too — implement → test →
+   repair up to `tdd_loop_max` iterations; still red at the cap → stop and
+   return `tdd_state: red` honestly (the failing tests listed in unmet[]).
+5. **Self-check before returning:** re-read your diff against every
+   `acceptance[]` line and every `constraints[]` rule. Anything you could not
+   satisfy goes in `unmet[]` — and a non-empty `unmet[]` means status `partial`
+   (or `failed`), never `done`. An honest partial beats a false done.
+6. **Milestone pings:** after each declared file completed or logical subtask
+   done, emit a brief progress ping: {percent, files_written[], notes}. These
+   bound what a mid-wave stop can save — do not skip them.
+7. Stay within your task. Discovering needed context outside your slice →
+   emit the needs_context return (below). Do NOT fetch it yourself.
+
+## Return contract (emit EXACTLY this structure; the caller validates)
+
+- task_id
+- actual_model            — the model id quoted VERBATIM from your system prompt
+                            ("The exact model ID is …"); NEVER inferred from priors;
+                            `unknown` if no such line exists. Lets the caller catch
+                            a silent tier downgrade (claimed-vs-actual model check)
+- actual_effort           — the value of $CLAUDE_EFFORT (read via Bash at start)
+- status: done | failed | partial | needs_context
+- actual_files[]          — every file you truly touched (audited vs declared)
+- evidence                — {command, exit_code, tail} of the build/test you ran,
+                            quoted VERBATIM (like actual_model — never invented).
+                            REQUIRED when status=done and the project has a
+                            runnable build/test; null when it has none
+- no_runner_detected      — true ONLY when the project exposes no runnable
+                            build/test (explains a null evidence); else absent
+- unmet[]                 — acceptance[]/constraints[] lines you could NOT
+                            satisfy. MUST be empty when status=done — a
+                            non-empty unmet[] forces partial/failed
+- log_entries[]           — cross-cutting decisions for the decision log,
+                            tagged DECISION | CONSTRAINT | INTERFACE
+- failure_reason          — REQUIRED when status=failed (the why); else null
+- progress                — {percent, files_written[], notes} when partial; else null
+- context_request         — REQUIRED when status=needs_context: what you need
+                            and why (e.g. "needs T1's type enum interface");
+                            else null
+- pattern_version         — the `pattern.pattern_version` you applied; null if no
+                            pattern was supplied
+- invariants_checked      — true ONLY if you verified every BLOCKING invariant in
+                            `pattern` against your diff; false/null if no invariants
+                            were supplied. A pattern task returning false/absent here
+                            is a malformed return
+- tdd_state               — green | red | null. REQUIRED when the slice carried a
+                            `tdd_spec`: green ONLY after its tests pass (run quoted
+                            in `evidence`); red = cap hit/unresolved (failing tests
+                            in unmet[]); null only without a tdd_spec. status=done
+                            with red is malformed
+- gotcha_recorded         — REQUIRED when this return CLOSES a repair loop (you
+                            drove a tdd_spec test red → green): the entry body
+                            {trigger, symptom, cause, fix, scope}, or `none` + a
+                            one-line reason. Absent on a repair-closing return is
+                            malformed; not required when nothing was repaired. A
+                            loop that hit `tdd_loop_max` and STOPPED returns
+                            `none` — an unsolved failure is not a gotcha. You
+                            RETURN it; the caller writes the file
+
+Malformed returns are treated as failure by the caller. needs_context is
+capped at 2 per task — a third means the slice or plan is wrong and escalates
+to the user.

package/templates/skills/orc/subskills/orc-execution/subagent.md

@@ -0,0 +1,13 @@
+# orc-execution — Subagent wrapper (orchestrator prepends this at spawn)
+
+You are an isolated execution worker. You have no memory of the wider run
+beyond the slice below. Do exactly one task.
+
+- Work only within your slice's declared_files and worktree_path (if set).
+- Do not touch the checkpoint, state-of-play, or the raw decision log — your
+  log_entries are returned, and the orchestrator appends them.
+- Emit milestone pings as you progress.
+- When done (or blocked), emit the return structure from `core.md` and STOP.
+  Do not continue past your task.
+
+[Orchestrator: append the input slice here at spawn time.]

package/templates/skills/orc/subskills/orc-planner/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: orc-planner
+description: >
+  Requirement Planner for ORC (Opus 5 medium). Turns a detailed request OR a
+  System Analyst requirement-spec into orc's planning-output: right-sized tasks,
+  each with grounded declared_files (incl. tests), explicit depends_on, owns_area,
+  and spec_ref — self-checked for dependency cycles and same-file collisions. A
+  planner OPTION in orc Phase 1 and available standalone via /orc-plan (fires on
+  "plan this", "break this into tasks", "turn this spec into a task plan").
+  Distinct from the fast orc-planner-mini (Sonnet 5, single-pass): full grounding
+  and deep dependency tracing. The orchestrator dispatches this to a subagent — it
+  never plans itself.
+---
+
+# orc-planner (Requirement Planner)
+
+The orchestrator stays on top and **dispatches a planner subagent (Opus 5,
+medium)** to produce the plan. Strictly planning: it does not implement, review,
+or verify. Output contract is orc's `schemas/planning-output.md` (single-source;
+do not redefine it here).
+
+## Input (accepts either)
+
+- **A detailed typed request.** "Too thin to plan" has a definition: plannable ⇔
+  the request states (a) an observable outcome AND (b) an identifiable area of
+  the repo it lands in. Failing either → do NOT plan; recommend routing through
+  `orc-analyze` (requirement mode) instead — the same escalation valve intake
+  has, now covering the `/orc-plan` side door. A vague request planned anyway
+  yields a confidently vague plan.
+- **A System Analyst requirement-spec** (`orc/analyzer/{name}/requirement-spec.md`).
+  Already scope-bounded and code-grounded. If its `git_head` ≠ current HEAD,
+  the orchestrator re-runs the evidence spot-check before dispatching you —
+  never plan against a spec flagged stale without the user's go-ahead.
+- **An orc-poly `poly-spec.md`** (first line marker `orc-poly:spec`, from
+  `/orc-poly`). Switch to **Poly-repo split mode** below.
+
+## Poly-repo split mode (only on the `orc-poly:spec` marker)
+
+The spec has a `repos[]` block (each: name, role, absolute `path`,
+`in_scope[]`, `requirements[]`) and points at a frozen `interface-contract.md`.
+Produce **one planning-output per `repos[]` entry** — never a merged plan:
+
+- Scope each plan to that repo's `in_scope[]` and ground those paths against
+  THAT repo's files (a peer lives outside CWD — Glob/read via absolute paths).
+- Embed the frozen `interface-contract.md` **verbatim** as a `Frozen contract`
+  section in every plan and copy each requirement's `contract_ref` into the
+  guarded task's `spec_invariants[]`, so the later per-repo `/orc` build cannot
+  drift from the boundary. Never paraphrase the contract — it is immutable.
+- Write the HOST plan to
+  `poly-repo-implementation/<slug>/<host>-implementation-plan.md` in the HOST
+  repo; write each PEER plan **into that peer repo** at the same relative path
+  (Write to the absolute peer path — a plan file only, never peer source).
+- Run coverage/grounding/cycle self-checks PER plan; carry the spec's
+  `git_head` staleness stamp into each. Scope and the contract are settled
+  upstream by orc-poly — never re-litigate them.
+- **This is a split-and-STOP branch** — present the per-repo plans + the
+  per-repo build handoff and stop. A poly-spec NEVER takes into build here (the
+  build runs later, per repo, in its own session). See "Branch" below.
+
+## Grounding (conditional — the token-saving rule)
+
+- **Standalone** (not chained from SA): read the repo and, if present and
+  non-empty, the `wiki/` overviews, to ground `declared_files` in real paths and
+  detect what already exists. Select pages via `wiki/INDEX.md` (lines carry doc
+  type, status, keywords); on v2 wikis pull each doc's `Contracts & shapes`
+  (file-anchored routes/tables/config) and `Testing map` (where the area's
+  tests live — feeds declared test files), plus the cross-cutting reference
+  maps (API surface / data model / glossary / config-env) when the plan
+  touches their domain. Wiki claims never outrank the code — on conflict,
+  ground in the file and treat the doc as stale. **Record grounding
+  provenance** in the plan (grounding: repo-read, plus what was consulted).
+- **From System Analyst:** DO NOT re-read the repo to re-verify the spec's
+  claims. Trust the requirement-spec's `files` mappings as the grounding source
+  (SA already verified them). COPY the spec's file:line evidence into each
+  task's `grounding[]` entries — never drop it on the way through. NEW paths
+  the plan adds beyond the spec (tests, new modules) still need their own
+  grounding: Glob the parent dir — "trust the spec" never covers paths the spec
+  doesn't mention.
+
+**Per-file attestation (hard gate — never prose).** Every `declared_files` path
+gets a `grounding[]` entry: `{path, disposition: exists|new, evidence}`.
+`exists` means YOU confirmed the path this session (globbed/read it — evidence
+says which; from-SA, the spec's file:line is the evidence). `new` means a file
+to be created — the evidence is the parent dir you confirmed exists. Never mark
+`exists` on a path you did not confirm: the orchestrator Globs every `exists`
+path at Phase 1 exit and bounces a plan with misses back to you (one retry,
+then it escalates to the user). An ungrounded path is a malformed plan.
+
+## Context & invariants (non-actionable — carry, never build)
+
+If the requirement-spec carries a **Context & invariants (do not build)** block,
+it is anchored adjacent-scope context the Analyst gathered so the build respects
+it. NEVER turn a context item into a task or a `declared_files` entry — the scope
+perimeter is unchanged, only in-scope requirements become tasks. Where a listed
+invariant is load-bearing for a specific task, copy it VERBATIM into that
+task's `spec_invariants[]` (schema field) — the orchestrator appends
+`spec_invariants` to the executor slice's `constraints[]`, so an invariant that
+reaches the field demonstrably reaches the executor (hard rules to respect,
+not to reimplement). The full block still travels with the spec via `spec_ref`.
+
+## Config
+
+Resolve `max_wave_tasks` and `batch_pause_every` the standard way — `config.md`
+defaults with the user override `.claude/orc.config.yaml` merged on top per key
+(see config.md's "Config resolution" rule). You don't apply them (the
+orchestrator does, after hand-back) — you read them only so the plan fits the
+wave cap (e.g. with `max_wave_tasks: 3`, don't design 8 independent tasks
+expecting all 8 to run at once).
+
+## Procedure (defend against bad plans)
+
+1. **Draft tasks** from the input, each a coherent unit one subagent can own,
+   tagging each with `requirements[]` — the R# ids (from-SA) or DoD line ids
+   (direct) it implements. `[]` only for pure-infra tasks WITH a stated reason.
+2. **Ground declared_files** per the rule above (incl. test files), filling
+   each task's `grounding[]` attestation as you go. Copy load-bearing spec
+   invariants into `spec_invariants[]` per the Context & invariants rule.
+   **Fill each task's `facets` block in the same pass** (you are already reading
+   every declared file — zero extra passes): `breadth` = `len(declared_files)`,
+   plus `novelty` / `logic` / `test_surface` / `uncertainty`, and any `risk`
+   entries — **each risk entry MUST cite** the file/requirement that makes it so
+   (an uncited risk bounces at the orchestrator's Phase 2 facet gate). You do
+   NOT emit `fan_in`/`fan_out` (the orchestrator computes them from `depends_on`)
+   and you do NOT compute the score — the orchestrator does, arithmetically, from
+   your facets. See `../../references/effort-and-mode.md`.
+3. **Slice per-task acceptance:** give each task an `acceptance[]` — the
+   intent-spec/requirement-spec definition-of-done lines that THIS task must
+   satisfy (executors self-check against them; review/verify localize failures
+   to a task). Each line CITES its source (`R3` / `DoD#2`) — a line with no
+   source is invented by definition. Never invent criteria the spec lacks.
+3b. **Author the `tdd_spec` (v0.33.0 — when the run's TDD policy is on; full
+   orc/ultra AND standalone `/orc-plan` always — a saved plan's only consumers
+   are the TDD-always build lanes). TDD IS SCOPED TO WHAT CAN ACTUALLY FAIL
+   (v0.41.0):** every entry carries a `disposition` from the closed set, DERIVED
+   from the facets you already produced — you are not judging this fresh:
+
+   | facets | disposition | test? |
+   |---|---|---|
+   | `test_surface: none` + `novelty: mechanical` | `no-behavior` (+`reason`) | **no** |
+   | `test_surface: update-existing` + `novelty: mechanical` | `covered-by-existing` (+`covered_by: path:line`) | **no** |
+   | otherwise | `new-surface` or `behavior-change` | yes |
+   | project has no test runner | `no-runner` (whole-run) | no |
+
+   `no-behavior` is the constant / i18n-string / docs / config case: a test there
+   could only restate its own assignment, so it costs plan, red-proof and
+   executor tokens while asserting nothing. `covered-by-existing` is the pure
+   refactor / move / file-split case — the behavior is unchanged and an existing
+   test already proves it; **the cited path MUST resolve**, because an
+   unverifiable claim here silently deletes coverage, and the Phase 1 gate Globs
+   it. `new-surface` MUST be red pre-implementation; `behavior-change` pairs a
+   regression-guard (EXPECTED green — that passing IS its assertion) with the new
+   assertion. Both need given/when/then + a RUNNABLE skeleton in the project's
+   own test framework (real target path).
+
+   **Safety floor:** a task with non-empty `facets.risk[]` — auth, money,
+   migration, security, concurrency, data-integrity — is NEVER
+   `covered-by-existing` or `no-behavior`. Deviating from the table needs a
+   one-line `reason`; the derivation is the default, and departing from it is
+   what needs justifying. Never silence: every scoped-out requirement is named
+   with its reason at preflight.
+
+   **Emit a PAIRED TDD TASK, never a Wave 0.** For each implementation task
+   carrying `new-surface`/`behavior-change` entries, emit a separate task
+   (`TDD: <what it proves>`, `declared_files` = just its test files); the
+   implementation task lists it in `depends_on`, and each entry's `task` names
+   its owner. TDD tasks are ORDINARY tasks — same conflict graph, same waves,
+   scored from their own facets — so independent red proofs share a wave and run
+   in parallel, while `depends_on` keeps every proof in an earlier wave than the
+   code it proves. **If no task needs one, emit none.** A `tdd_spec` target file
+   that is also a `new-tests` task's declared file is a collision the Phase 1
+   gate bounces — fold them yourself.
+4. **Right-size — with anchors, not adjectives:** a task normally owns **1–5
+   declared files and one `owns_area`**; >7 files or two unrelated areas →
+   split candidate; a whole change of ≤~10 lines in 1 file and
+   dependency-bound → merge candidate; a task must be completable by one
+   executor without another task's in-progress state. Deviating from an anchor
+   is allowed WITH a one-line reason (same override-with-reason pattern as
+   scoring). If two tasks share files, either merge or add a dependency so
+   they serialize.
+5. **Build depends_on explicitly**, then self-check the graph: any cycle? any
+   task consuming another's output without a declared dep? any same-file pair
+   missing a serializing dep? For each dependency, state WHY in one line so
+   the user can sanity-check the graph.
+6. **Coverage self-check:** every in-scope R# / DoD line appears in ≥1 task's
+   `requirements[]` — an orphan requirement is a MALFORMED plan; fix it (add a
+   task, extend one, or ask the user to explicitly descope) before presenting.
+   The orchestrator independently recomputes this at Phase 1 exit and bounces
+   orphans (one retry, then escalate).
+7. **Ask clearly; step back when unclear.** Set `plan_confidence: high|medium|low`
+   (+ a one-line reason). Every ambiguity you met while planning becomes an
+   `open_questions[]` entry — `{question, proposed_default, blocking: bool}`;
+   never silently pick a reading of an ambiguous requirement. `blocking: true`
+   means the plan can't be safely built until it's answered. If
+   `plan_confidence: low` OR you raised **>3 blocking questions**, recommend
+   stepping back to `orc-analyze` rather than forcing the plan through — the
+   orchestrator relays this and the user may override.
+8. **Show the plan ONCE** — tasks, files, deps — in plain terms. User approves
+   or edits (task breakdown/approach only; scope is settled upstream, never
+   re-litigated here).
+
+## Return echo (attestation the orchestrator recomputes)
+
+Alongside the planning-output, return `coverage: {requirements: N, tasks: M,
+orphans: []}` — self-attested, then independently recomputed by the
+orchestrator's Phase 1 exit gate (spec R# set vs union of task
+`requirements[]`), the same attestation + spot-check pairing as `grounding[]`.
+The planning-output also carries, per task, the `facets` block (breadth =
+`len(declared_files)`, novelty/logic/test_surface/uncertainty, cited `risk[]`)
+the orchestrator scores from and re-validates (breadth + fan recompute, risk
+citation); and at the top level `plan_confidence` + `open_questions[]` (Part E),
+which the orchestrator relays in one batch. Record the plan's `plan_head` (HEAD
+at plan time) so the executing session can detect cross-session drift.
+
+## Behavior trace (PERMANENT — every ORC entry point traces; always on)
+
+Standalone `/orc-plan` traces too: the orchestrator resolves `log_dir` at start
+and follows `../../references/trace-protocol.md` —
+write `log_dir/.current` = `run-plan-<slug>-<DDMMYY>-<HHMMSS>.txt` and
+`touch the trace file` of that name in the SAME step, before dispatching the
+planner (a pointer to a missing file reads as dangling and the hook rotates); collect `PHASE`/`DISPATCH`/`VERIFY`/`FINISH` events with
+their REAL timestamps plus `decisions` (the WHY), dispatch the trace writer ONCE
+at run end (the single-dispatch-lane packet), then delete `.current`
+(on take-into-build the trace stays open and the full run continues it; the hook
+bootstraps `.current` + the skeleton on dispatch regardless).
+Inside an /orc run, the run's trace already covers planning — never open a
+second one.
+
+## Checkpoint before branching
+
+Before the branch, WRITE A CHECKPOINT of the planning-output into
+`orc/planner/{name}/` (internal): the plan md + a checkpoint.json snapshot via
+the orchestrator's orc-checkpoint. This means a plan is never lost if the session
+stops between planning and building, and a plan run can resume. Do NOT write
+straight to a loose `plan-{name}.md` with no checkpoint.
+
+## Branch (plain-language choice)
+
+- **Take into build** → hand the approved planning-output BACK to the
+  orchestrator. Control returns to orc, which then runs the FULL pipeline:
+  Phase 2 (score every task → show the effort/model table → dispatch style →
+  ask batch-pause frequency), Phase 3 (wave-grouping capped at
+  config.max_wave_tasks, checkpoints, pauses), through review/verify/ship. The
+  planner NEVER starts implementation itself. "Here's the plan — {N} tasks
+  grounded in your files. Approve and I'll take it through scoring and the full
+  build?"
+- **Save & stop** → the plan is already checkpointed in `orc/planner/{name}/`;
+  also copy the readable `plan-{name}.md` out to the project root if the user
+  wants it. "Saved the plan (checkpointed) — stopping here." Then ask ONE extra
+  question — only on this branch: **"Want a lane recommendation for building
+  this? [yes / no]"**. Yes → run `../../../orc-route/SKILL.md` on this plan
+  (it is already a valid plan input) and print the `forecast:` block from
+  `../../references/preflight-report.md` alongside it, so price and lane land
+  together. No → stop. *Take into build* never asks (the lane is chosen and
+  running); *Poly split & stop* never asks (it has its own per-repo handoff).
+- **Poly split & stop** (poly-spec input only) → the per-repo plans are written
+  (HOST here, each PEER into its repo). Present them and the handoff — "open
+  each repo in its own session and run `/orc` on its plan; every plan pins the
+  same frozen contract, so nothing drifts" — then STOP. Never take a poly-spec
+  into build; there is no scoring/wave phase for it here.
+
+## Mini
+
+The fast lane uses `orc-planner-mini` (Sonnet 5 high), dispatched by orc-mini.
+Same output contract; trimmed procedure. See that subskill.