@azure-id/orc 2.1.1 → 2.2.0

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

@@ -1,74 +1,74 @@
-# Example — Annotated Full Run (v2.2, dry run)
-
-O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
-orchestrator NEVER implements — it always spawns scored subagents.
-
-U: Orchestrate: merchant notification system — in-app, email digest, prefs page.
-
-## Phase 0 — Intake
-O: Creates run folder run/merchant-notifications/ FIRST.
-   [reads repo: TS/yarn/jest — asks nothing about stack] Rough size: medium+ → 4-question tier (one batched round):
-   1) What should exist when done? 2) Out of scope? 3) How do we know it's done? 4) Patterns/files to avoid?
-U: [answers] no push, no admin; bell count + both digest schedules + prefs persist; follow services/ pattern, don't touch auth_service.
-O: [drafts run/merchant-notifications/intent-spec.md] Sign-off: gate or soft? (default gate)
-U: gate → approved
-
-## Phase 1 — Planning
-O: Planner? U: OpenSpec
-O: [6 tasks with declared_files incl. tests + per-file grounding attestations + sliced acceptance[], depends_on, spec_ref] ⚠ T1/T2 share models/notification.ts → scheduling separates them.
-   Grounding spot-check (Phase 1 exit): globs all `exists` paths — 13/14 present, models/notifcation.ts MISSING (typo) → plan bounced to planner with the miss list → corrected to models/notification.ts ✓.
-
-## Phase 2 — Effort, dispatch style, scoring
-O: Refined: medium, partially dependent. Recommend PARALLEL waves. Confirm? U: yes. Batch pause? U: every 2 waves.
-O: Facet scoring (planner facets → formula → band; facet gate: breadth + fan recomputed, risk cites checked):
-   T1 3·new-surface·stateful·new-tests·fan0/3·low = 6+18+16+8+9 = 57 → sonnet-5-high (keystone — every later task imports its enum)
-   T2 3·imitate·branching·new-tests·fan1/0·low = 6+8+8+8+5 = 35 → sonnet-5-high
-   T3 3·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-5-high
-   T4 2·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-5-high
-   T5 1·mechanical·none·update-existing·fan0/0·low = 2+0+0+4 = 6 → haiku-4-5
-   T6 1·mechanical·none·none·fan0/0·low = 2+0+0+0 = 2 → haiku-4-5
-   Plan: 6 tasks, 3 waves W1{T1} W2{T2,T3,T4} W3{T5,T6}, all spawned. Anticipated escalations? U: none, go.
-
-## Phase 3 — Execution (ALL spawned; orchestrator coordinates only)
-O: [checkpoint + state-of-play written into run/merchant-notifications/ BEFORE dispatch]
-▶ W1: spawn Agent-A(T1, sonnet-5-high) — milestones 40%→100% — return validated ✓ (evidence: `yarn jest models/` exit 0, tail quoted; unmet[] empty) — log: DECISION type enum.
-▶ W2: spawn 3 agents (sonnet-5-high each).
-   Agent-C needs_context (1/2): "needs T1's enum interface" → O adjudicates in-scope → re-slices → resumes. (User never bothered.)
-   Agent-C user escalation: "digest send time?" → U: 07:00 fixed → ANSWER broadcast to log.
-   Returns validated ✓ · collision audit clean.
-⏸ BATCH PAUSE (stop sequence):
-   checkpoint ✓ → state-of-play ✓ → dispatch report shown (models/scores) → "Run /usage to see your remaining limits."
-   → resume block:
-   | Continue ORC run `merchant-notifications`.
-   | Read run/merchant-notifications/state-of-play.md, then run/merchant-notifications/checkpoint.json.
-   | Resume from checkpoint phase/wave. Intent-spec approved — do not re-plan. Do not redo done tasks.
-   "Reply continue here, or paste in a fresh session (recommended if long)."
-
-U: [next day, FRESH session, pastes block]
-O: [state-of-play → checkpoint → re-anchored] "Resuming: merchant notifications (in-app+digest+prefs). Still correct?" U: yes.
-▶ W3: spawn T5+T6 (haiku-4-5) → done. All 6 complete.
-
-## Phase 5 — Review (spawned worker, Opus 5.5 medium)
-O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:line + verbatim quote):
-   P1 T2 no pagination — services/notification_list.ts:88 — O spot-checks: Reads line 88, quote matches ✓ → asks user, U: fix it
-   · P3 email_digest naming ×2 · 12 tests added. (An unanchored finding would be auto-P3 — never fixed unasked.)
-
-## Phase 6 — Verify (spawned worker, Opus 5.5 medium; criteria = definition-of-done)
-   criteria[] with per-line evidence: bell ✓ (test name) · both schedules ✗ (weekly cron missing = P0, unmet criterion, evidence: no cron entry in scheduler.ts) · prefs ✓ → FAILED → quote spot-check ✓ → P0 auto-fix (single attempt, no ask) → re-verify → PASSED. 14/14.
-
-## Phase 7 — Summary
-O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
-O: review close → `orc gotcha observe` ×3 (P1 addressed · 2× P3 wontfix, each with `run`) → `FINDING-OUTCOME addressed=1 disputed=0 wontfix=2 open=0 pre=0 suppressed=0 :: functional.check:1/1,evolvability.documentation:0/2`
-
-## Phase 8 — Ship (orc-pr, reads pr.md)
-O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
-O: Ticket/title/target? U: DRP-482 / Add merchant notification system / develop
-O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-notification-system.md from pr.md (base develop).
-   Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
-
-## What this exercises
-always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 5-band ladder ·
-per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
-planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
-build/test proof) · reviewer quote spot-check before any P0/P1 action ·
-definition-of-done catching the weekly-cron gap · needs_context resolved internally · fresh-session resume.
+# Example — Annotated Full Run (v2.2, dry run)
+
+O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
+orchestrator NEVER implements — it always spawns scored subagents.
+
+U: Orchestrate: merchant notification system — in-app, email digest, prefs page.
+
+## Phase 0 — Intake
+O: Creates run folder run/merchant-notifications/ FIRST.
+   [reads repo: TS/yarn/jest — asks nothing about stack] Rough size: medium+ → 4-question tier (one batched round):
+   1) What should exist when done? 2) Out of scope? 3) How do we know it's done? 4) Patterns/files to avoid?
+U: [answers] no push, no admin; bell count + both digest schedules + prefs persist; follow services/ pattern, don't touch auth_service.
+O: [drafts run/merchant-notifications/intent-spec.md] Sign-off: gate or soft? (default gate)
+U: gate → approved
+
+## Phase 1 — Planning
+O: Planner? U: OpenSpec
+O: [6 tasks with declared_files incl. tests + per-file grounding attestations + sliced acceptance[], depends_on, spec_ref] ⚠ T1/T2 share models/notification.ts → scheduling separates them.
+   Grounding spot-check (Phase 1 exit): globs all `exists` paths — 13/14 present, models/notifcation.ts MISSING (typo) → plan bounced to planner with the miss list → corrected to models/notification.ts ✓.
+
+## Phase 2 — Effort, dispatch style, scoring
+O: Refined: medium, partially dependent. Recommend PARALLEL waves. Confirm? U: yes. Batch pause? U: every 2 waves.
+O: Facet scoring (planner facets → formula → band; facet gate: breadth + fan recomputed, risk cites checked):
+   T1 3·new-surface·stateful·new-tests·fan0/3·low = 6+18+16+8+9 = 57 → sonnet-5-high (keystone — every later task imports its enum)
+   T2 3·imitate·branching·new-tests·fan1/0·low = 6+8+8+8+5 = 35 → sonnet-5-high
+   T3 3·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-5-high
+   T4 2·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-5-high
+   T5 1·mechanical·none·update-existing·fan0/0·low = 2+0+0+4 = 6 → haiku-5-high
+   T6 1·mechanical·none·none·fan0/0·low = 2+0+0+0 = 2 → haiku-5-high
+   Plan: 6 tasks, 3 waves W1{T1} W2{T2,T3,T4} W3{T5,T6}, all spawned. Anticipated escalations? U: none, go.
+
+## Phase 3 — Execution (ALL spawned; orchestrator coordinates only)
+O: [checkpoint + state-of-play written into run/merchant-notifications/ BEFORE dispatch]
+▶ W1: spawn Agent-A(T1, sonnet-5-high) — milestones 40%→100% — return validated ✓ (evidence: `yarn jest models/` exit 0, tail quoted; unmet[] empty) — log: DECISION type enum.
+▶ W2: spawn 3 agents (sonnet-5-high each).
+   Agent-C needs_context (1/2): "needs T1's enum interface" → O adjudicates in-scope → re-slices → resumes. (User never bothered.)
+   Agent-C user escalation: "digest send time?" → U: 07:00 fixed → ANSWER broadcast to log.
+   Returns validated ✓ · collision audit clean.
+⏸ BATCH PAUSE (stop sequence):
+   checkpoint ✓ → state-of-play ✓ → dispatch report shown (models/scores) → "Run /usage to see your remaining limits."
+   → resume block:
+   | Continue ORC run `merchant-notifications`.
+   | Read run/merchant-notifications/state-of-play.md, then run/merchant-notifications/checkpoint.json.
+   | Resume from checkpoint phase/wave. Intent-spec approved — do not re-plan. Do not redo done tasks.
+   "Reply continue here, or paste in a fresh session (recommended if long)."
+
+U: [next day, FRESH session, pastes block]
+O: [state-of-play → checkpoint → re-anchored] "Resuming: merchant notifications (in-app+digest+prefs). Still correct?" U: yes.
+▶ W3: spawn T5+T6 (haiku-5-high) → done. All 6 complete.
+
+## Phase 5 — Review (spawned worker, Opus 5.5 medium)
+O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:line + verbatim quote):
+   P1 T2 no pagination — services/notification_list.ts:88 — O spot-checks: Reads line 88, quote matches ✓ → asks user, U: fix it
+   · P3 email_digest naming ×2 · 12 tests added. (An unanchored finding would be auto-P3 — never fixed unasked.)
+
+## Phase 6 — Verify (spawned worker, Opus 5.5 medium; criteria = definition-of-done)
+   criteria[] with per-line evidence: bell ✓ (test name) · both schedules ✗ (weekly cron missing = P0, unmet criterion, evidence: no cron entry in scheduler.ts) · prefs ✓ → FAILED → quote spot-check ✓ → P0 auto-fix (single attempt, no ask) → re-verify → PASSED. 14/14.
+
+## Phase 7 — Summary
+O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
+O: review close → `orc gotcha observe` ×3 (P1 addressed · 2× P3 wontfix, each with `run`) → `FINDING-OUTCOME addressed=1 disputed=0 wontfix=2 open=0 pre=0 suppressed=0 :: functional.check:1/1,evolvability.documentation:0/2`
+
+## Phase 8 — Ship (orc-pr, reads pr.md)
+O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
+O: Ticket/title/target? U: DRP-482 / Add merchant notification system / develop
+O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-notification-system.md from pr.md (base develop).
+   Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
+
+## What this exercises
+always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 5-band ladder ·
+per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
+planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
+build/test proof) · reviewer quote spot-check before any P0/P1 action ·
+definition-of-done catching the weekly-cron gap · needs_context resolved internally · fresh-session resume.

package/templates/skills/orc/schemas/planning-output.md

@@ -50,6 +50,9 @@ open_questions: [object]   # [] or [{question, proposed_default, blocking: bool}
   declared_files: [string] # HARD GATE: actual files it will touch, incl. tests.
                            # File-level globs. No declaration → no wave assignment.
   depends_on: [string]     # forward = ordering; reverse = stale_review flagging
+  precedent: [string]      # OPTIONAL. Read-only files this task copies behaviour
+                           # or style from (max 5); the lane passes them to the
+                           # pack as `--refs=`. Absent = the map picks them.
 
   # grounding attestation (filled by the PLANNER — one entry per declared path)
   grounding: [object]      # {path, disposition: exists|new, evidence}

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

@@ -144,22 +144,22 @@ preflight line and has no gate to honour.
 ## Calls
 
 **ONE catalogue, and it is not you:** `orc lane calls orc-aftermath --json` names every
-CLI call this lane makes, each with its exit-code contract, its cost, when to run
+SHARED 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.
+a failure**. A call that neither it nor this skill names 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.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-aftermath --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[]`.
-## 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 **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+command you are about to run, out loud, before running it.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-aftermath --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[]`.
+## 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 **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

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

@@ -210,8 +210,8 @@ exist). Menu rules, relatedness gate, combiner handling:
 
 ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
 
-- **Calls:** `orc lane calls orc-analyze --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.
+- **Calls:** `orc lane calls orc-analyze --json` names shared calls and exit codes.
+  **An exit code is an ANSWER where it says so, not a failure.** Own calls are here; make no other.
 - **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`).

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

@@ -92,8 +92,8 @@ Never build or spawn.
 
 ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
 
-- **Calls:** `orc lane calls orc-analyze-mini --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.
+- **Calls:** `orc lane calls orc-analyze-mini --json` names shared calls and exit codes.
+  **An exit code is an ANSWER where it says so, not a failure.** Own calls are here; make no other.
 - **Config:** `orc lane config orc-analyze-mini --json`. Obey `effective`. Never merge
   `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`). Nothing
   here is contested, gated or a stop: no preflight line, no gate to honour.

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

@@ -235,22 +235,22 @@ documented defaults, out loud. Priorities and families:
 ## Calls
 
 **ONE catalogue, and it is not you:** `orc lane calls orc-boundary --json` names every
-CLI call this lane makes, each with its exit-code contract, its cost, when to run
+SHARED 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.
+a failure**. A call that neither it nor this skill names 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.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-boundary --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[]`.
-## 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 **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+command you are about to run, out loud, before running it.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-boundary --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[]`.
+## 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 **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-boundary/references/card.md

@@ -1,78 +1,81 @@
-# Reference — the boundary card
-
-Loaded at B4. One file per area: `.claude/orc/boundary/<area-slug>.md`. The slug
-is the area path with `/` → `-` (`src/payments` → `src-payments.md`), the same
-sanitisation `wiki/crosslink/<kind>/` uses — a nested path a single-level readdir
-never sees is a card that is invisible with the status check still green.
-
-## Shape
-
-```markdown
----
-area: src/payments                  # verbatim — this is the identity
-verdict: EXECUTE | ESCALATE | REFUSE
-anchored_files:                     # what staleness is computed against
-  - src/payments/ledger.ts
-  - src/payments/idempotency.ts
-verified_commit: 8a62b4f            # HEAD when the four questions were answered
-scanned_at: 100826 14:11:30
-reasons:                            # the four answers, compressed. Required.
-  - "self-verify: no — no test runner in this package"
-  - "reversible: no — writes to a live ledger"
-checklist:                          # REQUIRED when verdict is REFUSE
-  - add a test runner to this package
-  - cover the idempotency path
-escalate_to: "the payments owner"   # REQUIRED when verdict is ESCALATE
----
-
-# src/payments — REFUSE
-
-## Why
-<the derivation, in prose. Two or three sentences.>
-
-## What would make this a yes
-<the checklist again, with the lane that clears each item named.>
-
-## What an agent MAY do here today
-<the part that is fine. A card that reads as "hands off entirely" when only one
- file is dangerous costs more than it saves.>
-```
-
-## Field rules
-
-**`area`** — verbatim, never sanitised. The filename is sanitised; the identity is
-not. Same split as a crosslink kind.
-
-**`anchored_files`** — the files whose change should make this verdict
-re-examined. Over-broad (`src/**`) makes every card permanently stale; empty makes
-every card permanently fresh. Both defeat the point.
-
-**`verified_commit`** — HEAD at the moment the four questions were answered. Moved
-only by a real re-examination, never bumped to quiet a stale flag.
-
-**`reasons`** — at least the answers that DROVE the verdict. This is what makes a
-verdict arguable, and a verdict nobody can argue with is one people route around.
-
-**`checklist`** — required on REFUSE, and each item must be a thing somebody could
-actually finish. "Be more careful" is not a checklist item. Where another lane
-clears it, name the lane (`→ /orc-pact`, `→ /orc-pattern`).
-
-**`escalate_to`** — required on ESCALATE. A role is fine ("the payments owner"); a
-shrug is not.
-
-## The last section is not optional
-
-**"What an agent MAY do here today"** is what stops a card from reading as a wall.
-Most REFUSE areas contain plenty of safe work — tests, docs, a rename, a log line.
-A card that does not say so gets ignored, and an ignored card is worse than none,
-because it looks like coverage.
-
-## Staleness
-
-Computed on read by `orc boundary status`, never stored:
-`git rev-list --count <verified_commit>..HEAD -- <anchored_files>`. Non-zero =
-stale. **The skill never computes this** — same rule as the wiki tier
-(`../../_shared/detecting-artifacts.md`).
-
-A stale card is not a wrong card; it is one whose evidence has moved. Refresh is
-cheap: re-run the four questions for that area only.
+# Reference — the boundary card
+
+Loaded at B4. One file per area: `.claude/orc/boundary/<area-slug>.md`. The slug
+is the area path with `/` → `-` (`src/payments` → `src-payments.md`), the same
+sanitisation `wiki/crosslink/<kind>/` uses — a nested path a single-level readdir
+never sees is a card that is invisible with the status check still green.
+
+## Shape
+
+```markdown
+---
+area: src/payments                  # verbatim — this is the identity
+verdict: EXECUTE | ESCALATE | REFUSE
+anchored_files:                     # what staleness is computed against
+  - src/payments/ledger.ts
+  - src/payments/idempotency.ts
+verified_commit: 8a62b4f            # HEAD when the four questions were answered
+scanned_at: 100826 14:11:30
+reasons:                            # the four answers, compressed. Required.
+  - "self-verify: no — no test runner in this package"
+  - "reversible: no — writes to a live ledger"
+checklist:                          # REQUIRED when verdict is REFUSE
+  - add a test runner to this package
+  - cover the idempotency path
+escalate_to: "the payments owner"   # REQUIRED when verdict is ESCALATE
+---
+
+# src/payments — REFUSE
+
+## Why
+<the derivation, in prose. Two or three sentences.>
+
+## What would make this a yes
+<the checklist again, with the lane that clears each item named.>
+
+## What an agent MAY do here today
+<the part that is fine. A card that reads as "hands off entirely" when only one
+ file is dangerous costs more than it saves.>
+```
+
+Lists may be block (`- item`) or inline (`[a, b]`). `orc boundary status` reads
+both (v2.1.2). An item that holds a comma or a `#` goes in quotes.
+
+## Field rules
+
+**`area`** — verbatim, never sanitised. The filename is sanitised; the identity is
+not. Same split as a crosslink kind.
+
+**`anchored_files`** — the files whose change should make this verdict
+re-examined. Over-broad (`src/**`) makes every card permanently stale; empty makes
+every card permanently fresh. Both defeat the point.
+
+**`verified_commit`** — HEAD at the moment the four questions were answered. Moved
+only by a real re-examination, never bumped to quiet a stale flag.
+
+**`reasons`** — at least the answers that DROVE the verdict. This is what makes a
+verdict arguable, and a verdict nobody can argue with is one people route around.
+
+**`checklist`** — required on REFUSE, and each item must be a thing somebody could
+actually finish. "Be more careful" is not a checklist item. Where another lane
+clears it, name the lane (`→ /orc-pact`, `→ /orc-pattern`).
+
+**`escalate_to`** — required on ESCALATE. A role is fine ("the payments owner"); a
+shrug is not.
+
+## The last section is not optional
+
+**"What an agent MAY do here today"** is what stops a card from reading as a wall.
+Most REFUSE areas contain plenty of safe work — tests, docs, a rename, a log line.
+A card that does not say so gets ignored, and an ignored card is worse than none,
+because it looks like coverage.
+
+## Staleness
+
+Computed on read by `orc boundary status`, never stored:
+`git rev-list --count <verified_commit>..HEAD -- <anchored_files>`. Non-zero =
+stale. **The skill never computes this** — same rule as the wiki tier
+(`../../_shared/detecting-artifacts.md`).
+
+A stale card is not a wrong card; it is one whose evidence has moved. Refresh is
+cheap: re-run the four questions for that area only.