@azure-id/orc 1.9.2 → 2.1.0

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

@@ -1,14 +1,12 @@
 ---
 name: orc-fast
 description: >
-  Fastest ORC lane — knowledge-gated single-executor implementation. Use for
-  "use orc-fast to implement X" or "/orc-fast". Requires TWO prerequisites:
-  a fresh project wiki (orc-wiki) AND a cached code-pattern for the request's
-  language — the precomputed knowledge replaces the analyst/planner entirely.
-  Either missing → falls back to orc-mini (never stops the chat). One
-  Sonnet 4.6 high executor, a build+test smoke gate, one repair round, ship.
-  Orchestrator runs fine at Sonnet medium. The orchestrator never implements —
-  it spawns.
+  Fastest ORC lane — knowledge-gated single-executor implementation, with no
+  analyst and no planner. Use for "use orc-fast to implement X" or "/orc-fast".
+  Requires TWO prerequisites: a fresh project wiki (orc-wiki) AND a cached
+  code-pattern for the request's language. If either is missing, it falls back
+  to orc-mini. One Sonnet 4.6 high executor, a build+test smoke gate, one repair
+  round, ship.
 ---
 
 # ORC-FAST
@@ -32,24 +30,26 @@ fit gate hands it to orc-mini.
 
 ## Phases
 
-`orc lane phases orc-fast --json` is this lane's pipeline: the ordered list, where
-each phase lives, and how much of it to read. **The CLI owns the order** — never
-derive it from the headings below, and never renumber or rename one without the
-manifest, because a `read: section` pointer names a HEADING and a renamed heading
-is a pointer into nothing.
+`orc lane phases orc-fast --json` is this lane's pipeline. **The CLI owns the order**:
+never derive it from the headings below, and never rename or renumber one
+without the manifest (`../_shared/lane-contract.md` §Phases).
 
 ## Phase F0 — Preflight (the two prerequisite gates; no spawn)
 
-Emit a `GATE` trace line per check when logging.
+Emit a `GATE` trace line per check.
+
+**0. Config, FIRST.** `orc lane config orc-fast --json`: obey `effective`, print
+`announce[]` VERBATIM, honour `stops[]`; never merge `.claude/orc.config.yaml`
+(`../_shared/config-precedence.md`). **`habits{}` in it → print `habits.line`,
+read `../_shared/habits.md` NOW.**
 
 **a. Wiki gate.** Decide existence with `orc wiki status` — the deterministic
 probe in `../_shared/detecting-artifacts.md`, never an ad-hoc `find` (`.claude`
-is hidden). `none` = gate FAILED → fallback; else wiki present → compute the
-tier from `.claude/orc/wiki-meta.json` per `../orc-wiki/references/staleness.md`:
-`git rev-list --count <scan_commit>..HEAD` → FRESH / AGING / STALE (manifest
-absent but docs present = STALE; wiki absent/empty = gate FAILED → fallback).
+is hidden). `none` = gate FAILED → fallback; else read the tier from
+`orc wiki status --json` → `.tier` (FRESH / AGING / STALE; the CLI computes
+it — never recompute it by hand).
 - **FRESH** → proceed silently. **AGING** → one-line notice, proceed.
-- **STALE** → the user judges. Ask with exactly these options:
+- **STALE** → the user judges. Ask (H `fast.f0.stale-wiki`) with exactly these options:
   1. **Refresh wiki, then continue fast** *(recommended)* — run orc-wiki's
      incremental refresh (diff since `scan_commit`, re-scan only affected
      docs), then re-enter this preflight.
@@ -81,9 +81,8 @@ then one `orc graph notes pending` batch — the next run starts from this cache
 
 **d. Extra — a PROBE, not a gate (P0).** Run `orc extra resolve --slot fast-executor --json` (0 = extra, 1 = Claude) — **a gate that is never probed is a gate that is always off**, and without this step the lane silently runs on Claude however `extra_enabled` and `orc extra role` were set. `extra` → print the `extra:` line HERE and carry the answer into F2; `claude` → print nothing, never fall back, never stop.
 
-The SHAPE of these steps — the order, and the four rules that make it worth
-having — is `../_shared/phases/preflight.md` (`core`). The probes
-themselves are this lane's own and stay here.
+Their shape and four rules: `../_shared/phases/preflight.md` (`core`). The
+probes are this lane's own.
 
 ## Phase F1 — Fit gate + micro-intake (one pass, ONE user round-trip)
 
@@ -134,35 +133,35 @@ pinned in the agent file). **Under `opus5_only` it is `orc-executor-opus-5-low`*
 - **terse-return rule:** standard contract fields, NO narrative prose — files
   changed, one-line diff summary, smoke-relevant notes only.
 
-Validate the return per `../_shared/return-validation.md` — `unmet[]`
+Validate the return per `../_shared/return-validation.md` §1–§3 + the § of
+each field you injected — `unmet[]`
 honesty, `pattern_version` + `invariants_checked` attestation, `actual_model`
 / `actual_effort` downgrade check (emit the `VERIFY` trace line), and §6's worktree delta (`git status --short` before/after; a path changed outside `declared_files` is a violation whatever the return said). Malformed
 return = failure (one re-dispatch, then fallback offer).
 
-**Before any re-dispatch, run `orc run inflight`** (0 clear · 1 in-flight · 2 unknown). A Task error does not kill the agent behind it, and exit 2 REFUSES by default — `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `../_shared/return-validation.md`.
+**Before any re-dispatch, run `orc run inflight`**. A Task error does not kill the agent behind it, and exit 2 REFUSES by default — `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `../_shared/return-validation.md`.
 
 ## Phase F3 — Smoke gate (build + test; blocks ship on red)
 
 Run the gate per `../_shared/smoke-gate.md`, sourcing commands **from
 `wiki-meta.json`'s `commands` block** (recorded at wiki scan — don't
 rediscover tooling; manifest lacks them → detect once and say so). **GREEN**
-→ code-graph step e.(3) (never a gate) → ship. **RED** → one repair round; second red → STOP and offer: escalate to
+→ code-graph step e.(3) (never a gate) → ship. **RED** → the flaky check, then one repair round; second red → STOP and offer: escalate to
 orc-mini (reason `smoke-red-escalation`) / switch to full `/orc` / stop.
 Docs-only → gate N/A, say so.
 
 ## Phase F3.5 — Mock example (config `mock_example`, default ask)
 
-Canonical: `../_shared/drift-recovery.md` — load on fire. Only after a GREEN
-F3, before ship: `ask` → MANDATORY offer · `on` → build · `off` → skip.
-Deliverable `mock-examples/<change-slug>/` at project root — **never
-committed/staged**. Drift answer → `DRIFT-FROM` recovery (cap 2 loops, honest
-report on cap). Trace: `PHASE mock-example`, `DRIFT loop=<n>`.
+After a GREEN F3, before ship (H `fast.f3-5.mock`): follow `../_shared/drift-recovery.md` (load on
+fire) — the `mock-examples/<change-slug>/` deliverable, the `DRIFT-FROM` loop and
+its cap. Trace: `PHASE mock-example`, `DRIFT loop=<n>`.
 
 ## Phase F4 — Ship
 
-Offer commit (push if asked; never stage `mock-examples/`). Append the final markers to the checkpoint, emit
+Offer commit (H `fast.f4.ship` · `any.ship.review-before-push`; push if asked; never stage `mock-examples/`). Append the final markers to the checkpoint, emit
 `OUTCOME task=… band=fast model=… retries=… unmet=…` + `FINISH`, show the
-dispatch line (model/effort actually used) + the `/usage` reminder. Fast never
+dispatch line (model/effort actually used) + the `/usage` reminder. Every end — ship
+or a red STOP — prints the card (`../_shared/phases/summary.md` §End-of-run card). Fast never
 triggers the post-ship wiki refresh ask (preflight polices freshness on the
 way in) — the passive stale-flag note still applies to touched covered files.
 
@@ -176,46 +175,23 @@ already in the shared format — no migration.
 
 ## Behavior trace (always on)
 
-`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
-the file and the layers). Lane token `fast`, tier **Build lanes** —
-per phase, batched to **2 packets** (preflight+dispatch · gate+ship), each
-paired with the next phase's first dispatch.
-At run start write `log_dir/.current` = `run-fast-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
-`touch the trace file` of that name in the SAME step.
-Nothing else about the protocol is restated here; a phase that ends with
-`zero new trace lines is a protocol violation`.
-
-## Config
-
-**ONE resolver, and it is not you:** `orc lane config orc-fast --json`. Obey
-`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
-`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
-from `.claude/orc.config.yaml` — a key this lane does not read is not in the
-answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
-the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
-documented defaults, out loud. Priorities and families:
-`../_shared/config-precedence.md`.
-
-Fast has no config key of its own — command-entry only; wave/scoring/review
-keys never apply, and the tier edges the F0 gate reads arrive resolved.
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases orc-fast --json` →
+`trace_grammar` gives the verbs). Lane token `fast`, tier
+**Build lanes** — batched to **2 packets** (preflight+dispatch ·
+gate+ship) → `orc trace write --packet -`. At run start write `log_dir/.current` =
+`run-fast-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step. A phase that ends with `zero new trace lines is a protocol violation`.
 
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
 
-`orc rules slice --lane orc-fast --json` is the ONLY assembler; never build
-the card here. It rides under the house rules and above the task —
-**house rules > your project's rules > ORC's own packs** — and its `line` prints
-VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
-never a silent choice) and `rules_overridden[]`.
-## Calls
+- **Calls:** `orc lane calls orc-fast --json` names every call and its exit codes.
+  **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
+- **Config:** F0 step 0.
+- **Rules:** `orc rules slice --lane orc-fast --json` is the ONLY assembler
+  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
 
-**ONE catalogue, and it is not you:** `orc lane calls orc-fast --json` names every
-CLI call this lane makes, each with its exit-code contract, its cost, when to run
-it, and what an EMPTY answer means. Never invent a spelling, never re-word an
-exit code, and never re-derive a state word — the CLI's state words are the only
-state words, and **an exit code is an ANSWER wherever that contract says so, not
-a failure**. A call the answer does not name is a call this lane does not make.
-Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
+Fast has no config key of its own — command-entry only; wave/scoring/review
+keys never apply, and the tier edges the F0 gate reads arrive resolved.
 
 ## Checkpoint (minimal, append-only)
 
@@ -223,14 +199,12 @@ One `fast-checkpoint.md` in the run folder: GATE results (+ any
 `wiki_stale_override`), the dispatch, smoke verdicts, OUTCOME — enough for
 /orc-retro mining and fresh-session resume, nothing more.
 
-## What fast still enforces (from the main hard rules)
+## What fast still enforces
 
-Never implement yourself (smoke gate = read-only build+test) · all artifacts
-in the run subfolder, never project root · validate the subagent return
-(malformed = failure) · never offer commit on a red build · report the
-dispatch + remind the user to run `/usage` (never invoke it programmatically).
+All artifacts in the run subfolder, never project root · never offer commit on
+a red build · never invoke `/usage` programmatically.
 
 ## Waiting mid-run (`/orc-wait`)
 
 Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
-Checkpoint **full** · safe point **after the executor returns**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+Checkpoint **full** · safe point **after the executor returns**.

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

@@ -0,0 +1,110 @@
+---
+name: orc-fix
+description: >
+  Say "this is a fix, and here is what it fixes". Use for "/orc-fix", "this
+  fixes Sonar typescript:S3776", "ORC caused this defect", "this bug came from
+  AI-generated code", "record this fix". It classifies the fix from evidence,
+  asks once, and records it so the next review sees it. A rider: it opens no
+  run and returns to exactly where the run was. With no run open it can also
+  make the fix, like /orc-quick.
+---
+
+# ORC — the fix record
+
+A RIDER lane, like `/orc-wait` and `/orc-explain`. It opens no run of its own,
+writes no `run-<lane>-<slug>` pointer and never writes `.current`. The user can
+call it at any time — also while another lane waits at a question.
+
+## What this lane never does
+
+- It never begins between a dispatch and its validated return.
+- It never changes the host run: no re-plan, no re-score, no new task. A
+  suspend does not widen anyone's authority.
+- With a run open, it never writes code. The host lane makes the fix — two
+  writers on one tree is the conflict `/orc-wait` forbids (DE-12).
+- It never sets `miss` itself, and never records `author: orc`. The CLI does
+  the first, and refuses the second.
+
+## F0 — look (silent)
+
+Run `orc fix classify --text "<the user's words>" --json`. The CLI reads the
+git state, `git blame` on the named lines, the traces and the host run, and
+proposes ONE class on two axes:
+
+- `source` (what found it): `sonar` · `ci` · `defect` · `pr` · `review` · `other`
+- `introduced_by` (who wrote the bad lines): `orc` · `ai` · `human` · `unknown`
+
+| exit | meaning | what you do |
+|---|---|---|
+| 0 | classified | go to F1 |
+| 1 | a dispatch is in flight | say so, wait for its return, then run F0 again |
+| 2 | no text | ask what the fix fixes |
+
+Never classify in your head. The user's three cases: "a SonarQube fix" →
+`source: sonar`; "a defect caused by ORC" → `source: defect, introduced_by:
+orc`; "a bug caused by AI-generated code" → `introduced_by: ai`.
+
+## F1 — ask once (H `fix.f1.class`)
+
+Show the proposed class, every `evidence` line and the file, then:
+
+```text
+This fix:  source sonar · introduced by ORC (run-mini-total-290926)
+  - a Sonar rule key (typescript:S3776)
+  - git blame → 4c1e2a9: the commit falls inside the run's trace window ...
+  1. confirm   2. change the class   3. cancel
+```
+
+The user's word wins over the evidence. A changed class goes into the record
+as `class_by: "user"`; a confirmed one as `class_by: "evidence"`. Cancel →
+nothing is written; return to the run.
+
+## F2 — record
+
+Pipe the classify answer's `record` object (with the user's class and
+`class_by`) to `orc fix record - --json`. The CLI:
+
+1. writes ONE observation through the gotcha store — with a Sonar issue key it
+   uses the importer's own id, so a later `gotcha sync` completes the same row;
+2. computes `miss` from the stored review scopes;
+3. writes ONE `FIX` line into the HOST run's trace, when one is open;
+4. prints ONE line. Show it VERBATIM, then stop.
+
+Exit 1 → a dispatch started meanwhile; nothing was written. Wait, then F2 again.
+
+## No run open — offer the fix (DE-12)
+
+`mode: may-fix` from F0 → offer to make the fix before F2, like `/orc-quick`:
+
+1. The user picks the executor at the `/orc-quick` dispatch gate (that lane's
+   `dispatch-gate.md` reference, "Writing code") — nothing spawns without a yes.
+2. The slice carries `orc rules slice --lane orc-fix --json` (below).
+3. The smoke gate (`../_shared/smoke-gate.md`): red blocks the record.
+4. F2 with `outcome: "addressed"` and `via: "orc-fix"`.
+
+The user can also say "record only" — then F2 at once.
+
+## Config
+
+`orc lane config orc-fix --json`, obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-fix --json` is the ONLY assembler. It rides only in
+an executor slice of the no-run fix.
+
+## Habits and trace
+
+**Habits:** the host run had `habits{}` in its config answer → read
+`../_shared/habits.md`; its next packet takes the `ASK` for `fix.f1.class`
+(class `never`: a fact is never a habit). No `habits{}` → ignore `(H …)`.
+
+**Trace:** the CLI writes the `FIX` line itself. You do not narrate it and you
+do not repeat it. With no run open, nothing is traced — the record is the
+observation.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **none** · safe point **after the record is written**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking.

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

@@ -1,82 +1,77 @@
----
-name: orc-judge
-description: >
-  Judgment gates for the ORC ultra lane. One judge skill, one agent
-  (orc-judge-opus-5-xhigh), three dispatch contexts: gate=analysis (after the
-  analyst), gate=plan (after the planner), gate=implementation (after verify —
-  the anti-miss-implementation fidelity + strict-quality gate). Returns a
-  structured verdict (APPROVE | REVISE | ESCALATE) with anchored,
-  consequence-cited findings; REVISE loops the author with a hard 2-loop cap
-  and a convergence rule. Dispatched only from /orc-ultra — no slash command
-  of its own, never in orc or orc-mini. The orchestrator dispatches the judge
-  subagent — it never judges itself.
----
-
-# ORC-JUDGE (ultra-lane judgment gates)
-
-A model-based quality gate on top of ORC's deterministic gates. The judge
-handles what determinism cannot: scope-interpretation correctness, plan
-soundness, implementation fidelity, and — at the final gate — ultra-strict
-code quality. Deterministic gates ALWAYS run first; the judge never re-checks
-what a string-compare catches.
-
-Ultra lane ONLY. No `/orc-judge` command; the orchestrator dispatches
-`orc-judge-opus-5-xhigh` at the three ultra gates.
-
-## Hard rules
-
-1. **The orchestrator never judges — it spawns.** One agent, three contexts
-   (`gate=analysis|plan|implementation`).
-2. **Deterministic first.** A judge dispatch is only legal AFTER the gate's
-   deterministic checks passed (evidence spot-check + derivation lint /
-   coverage + graph checks / verify + traceability matrix + static analysis).
-3. **The judge is read-only** and blind to the author's internal reasoning or
-   self-assessment (anti-anchoring): it sees the artifact, its evidence, the
-   advisor brief + rubric, and the original request.
-4. **Judge gates ADD to user sign-offs, never replace them.** Gate approvals
-   never skip the analyst challenge round or the plan sign-off.
-5. **Gate scope is one-directional.** gate=plan takes the approved spec as
-   fixed ground truth; gate=implementation takes the approved plan as fixed —
-   no gate re-litigates an earlier approved gate.
-6. **The judge never fixes.** Authors fix: analyst (gate=analysis), planner
-   (gate=plan), a scored executor fix wave (gate=implementation).
-
-## Verdict handling (orchestrator side)
-
-Validate the return against the agent's verdict contract, then:
-
-- **Downgrade enforcement:** any blocking finding missing its verbatim
-  anchor or its class-appropriate justification (failure_consequence for
-  correctness/security; named category + concrete alternative for
-  smell/simplification/placement) → downgrade to advisory and tell the user.
-  EXCEPTION: a security finding with a concrete consequence is always
-  blocking — never downgraded.
-- **APPROVE** → record the verdict artifact, continue the pipeline.
-- **REVISE** → re-dispatch the author with the original slice + the blocking
-  findings verbatim. The author's return must echo `finding_id → resolution`
-  per finding; a missing echo is a malformed return (requeue). Then RE-JUDGE
-  under the convergence rule: block only on unresolved prior findings by id
-  or on lines the revision changed; new findings on untouched material are
-  advisory-only. **Hard cap: 2 revision loops per gate**, counted in the
-  checkpoint.
-- **ESCALATE** (or a third failure) → present the ESCALATE menu:
-  accept-and-proceed (unresolved findings recorded in the Phase 7 summary) /
-  user fixes manually then re-judge (does not consume a loop) / grant one
-  extra loop / stop-and-checkpoint.
-- Advisory findings NEVER loop — they ride forward attached to the next
-  phase's slices as notes.
-- Persist every verdict as `run/{run-slug}/ultra/verdict-<gate>-<round>.md`
-  (mined by /orc-retro; survives resume). When logging, emit
-  `JUDGE <gate> <verdict>` and the judgment GATE line (pass|bounce|escalate).
-
-## The three gates
-
-| Gate | After | Judges | REVISE target |
-|------|-------|--------|---------------|
-| analysis | analyst-return deterministic gates | scope interpretation, requirement coherence, rubric misses, stale-doc risk | analyst |
-| plan | Phase 1 exit gate + blast-radius map | decomposition, declared-file plausibility, deps, right-sizing, blast-radius coverage | planner |
-| implementation | Phase 6/6.5 + traceability matrix + static analysis | fidelity to the user's ask + ultra-strict quality (security, smells, simplification, placement, pattern invariants) | scored executor fix wave → re-verify → re-judge |
-
-Return fields include `actual_model` + `actual_effort` (standard
-claimed-vs-actual check) and `rubric_items_checked[]` +
-`unconfirmed_assumptions_touched[]` — validate them like any worker return.
+---
+name: orc-judge
+description: >
+  Internal to /orc-ultra: the three judgment gates — analysis, plan,
+  implementation. Returns APPROVE | REVISE | ESCALATE with anchored findings;
+  REVISE has a hard 2-loop cap. No slash command of its own.
+disable-model-invocation: true
+---
+
+# ORC-JUDGE (ultra-lane judgment gates)
+
+A model-based quality gate on top of ORC's deterministic gates. The judge
+handles what determinism cannot: scope-interpretation correctness, plan
+soundness, implementation fidelity, and — at the final gate — ultra-strict
+code quality. Deterministic gates ALWAYS run first; the judge never re-checks
+what a string-compare catches.
+
+Ultra lane ONLY. No `/orc-judge` command; the orchestrator dispatches
+`orc-judge-opus-5-xhigh` at the three ultra gates.
+
+## Hard rules
+
+1. **The orchestrator never judges — it spawns.** One agent, three contexts
+   (`gate=analysis|plan|implementation`).
+2. **Deterministic first.** A judge dispatch is only legal AFTER the gate's
+   deterministic checks passed (evidence spot-check + derivation lint /
+   coverage + graph checks / verify + traceability matrix + static analysis).
+3. **The judge is read-only** and blind to the author's internal reasoning or
+   self-assessment (anti-anchoring): it sees the artifact, its evidence, the
+   advisor brief + rubric, and the original request.
+4. **Judge gates ADD to user sign-offs, never replace them.** Gate approvals
+   never skip the analyst challenge round or the plan sign-off.
+5. **Gate scope is one-directional.** gate=plan takes the approved spec as
+   fixed ground truth; gate=implementation takes the approved plan as fixed —
+   no gate re-litigates an earlier approved gate.
+6. **The judge never fixes.** Authors fix: analyst (gate=analysis), planner
+   (gate=plan), a scored executor fix wave (gate=implementation).
+
+## Verdict handling (orchestrator side)
+
+Validate the return against the agent's verdict contract, then:
+
+- **Downgrade enforcement:** any blocking finding missing its verbatim
+  anchor or its class-appropriate justification (failure_consequence for
+  correctness/security; named category + concrete alternative for
+  smell/simplification/placement) → downgrade to advisory and tell the user.
+  EXCEPTION: a security finding with a concrete consequence is always
+  blocking — never downgraded.
+- **APPROVE** → record the verdict artifact, continue the pipeline.
+- **REVISE** → re-dispatch the author with the original slice + the blocking
+  findings verbatim. The author's return must echo `finding_id → resolution`
+  per finding; a missing echo is a malformed return (requeue). Then RE-JUDGE
+  under the convergence rule: block only on unresolved prior findings by id
+  or on lines the revision changed; new findings on untouched material are
+  advisory-only. **Hard cap: 2 revision loops per gate**, counted in the
+  checkpoint.
+- **ESCALATE** (or a third failure) → present the ESCALATE menu:
+  accept-and-proceed (unresolved findings recorded in the Phase 7 summary) /
+  user fixes manually then re-judge (does not consume a loop) / grant one
+  extra loop / stop-and-checkpoint.
+- Advisory findings NEVER loop — they ride forward attached to the next
+  phase's slices as notes.
+- Persist every verdict as `run/{run-slug}/ultra/verdict-<gate>-<round>.md`
+  (mined by /orc-retro; survives resume). When logging, emit
+  `JUDGE <gate> <verdict>` and the judgment GATE line (pass|bounce|escalate).
+
+## The three gates
+
+| Gate | After | Judges | REVISE target |
+|------|-------|--------|---------------|
+| analysis | analyst-return deterministic gates | scope interpretation, requirement coherence, rubric misses, stale-doc risk | analyst |
+| plan | Phase 1 exit gate + blast-radius map | decomposition, declared-file plausibility, deps, right-sizing, blast-radius coverage | planner |
+| implementation | Phase 6/6.5 + traceability matrix + static analysis | fidelity to the user's ask + ultra-strict quality (security, smells, simplification, placement, pattern invariants) | scored executor fix wave → re-verify → re-judge |
+
+Return fields include `actual_model` + `actual_effort` (standard
+claimed-vs-actual check) and `rubric_items_checked[]` +
+`unconfirmed_assumptions_touched[]` — validate them like any worker return.