@azure-id/orc 0.55.0

package/templates/skills/orc-challenge/references/cycle-state.md

@@ -0,0 +1,185 @@
+# Cycle state — computed, never stored
+
+Nothing below is written to disk. `orc challenge status` derives all of it from
+`challenge.json` plus the artifact shas on disk plus `git`. **The skill never
+computes a state itself** — the same rule `../../_shared/detecting-artifacts.md`
+sets for the wiki tier, and the same rule `/orc-pact` keeps for a promise.
+
+| State | Computed when |
+|---|---|
+| `AWAITING-JUDGE` | the cycle exists and no iteration has been recorded |
+| `AWAITING-FIX` | the last verdict FAILED and no artifact sha has changed since |
+| `AWAITING-RECHECK` | the last verdict FAILED and at least one artifact sha HAS changed — the user did work, a new iteration is warranted |
+| `PASSED` | no open finding is at or above the blocking severity, and nothing has changed since |
+| `STALE-PASS` | passed, but an artifact changed afterwards. **Honest, not a failure** — the `UNCHECKABLE` precedent from `/orc-pact` |
+| `MISSING-REVISION` | the last verdict FAILED and the **declared** revision path does not exist. Candidates are listed, never adopted |
+| `TAMPERED` | a stored `verdict_file_sha` no longer matches disk. Reported, never silently re-graded |
+
+`TAMPERED` is checked FIRST and raises the exit code to 2. A cycle whose evidence
+moved under it is not "passed" and is not "awaiting" anything — it needs a human
+to say what happened.
+
+## Two flags, not two states
+
+A state that means two things is a state that lies. These ride alongside:
+
+- **`stalled: true`** — findings at or above the blocking severity have not net
+  decreased across `challenge_stall_after` iterations (default 3).
+- **`no_template: true`** — D1 is `NOT-CHECKED`.
+
+## Why PASS is recomputed on read
+
+The stored `passed` on an iteration is that VERDICT'S OWN HISTORY — it is what
+the convergence chart draws, and it never changes. The STATE is recomputed live,
+because `orc challenge accept` is a decision that takes effect the moment it is
+recorded. If it did not, the escape valve would not escape until one more paid
+iteration had run.
+
+## Exit codes
+
+| Command | Codes |
+|---|---|
+| `challenge list` | 0 all passed · 1 ≥1 in-flight · 3 no cycles |
+| `challenge status <slug>` | 0 PASSED · 1 open blocking findings · 2 a P0 is open, or TAMPERED · 3 unknown slug |
+| `challenge show <slug>` | 0 · 3 unknown |
+| `challenge diff <slug>` | 0 unchanged · 1 changed · 2 `MISSING-REVISION` · 3 unknown |
+| `challenge expect <slug>` | 0 · 2 refused (outside the repo, or inside the review trail) · 3 unknown |
+| `challenge lint <path>` | 0 clean · 1 findings · 2 unreadable |
+| `challenge outline <path>` | 0 · 2 unreadable |
+| `challenge record` | 0 recorded · 2 malformed · 3 unknown slug |
+| `challenge roles` | 0 (static — works with no cycle, no project, no git) |
+| `challenge council <slug>` | 0 roster set · 1 roster UNSET · 3 unknown slug |
+| `challenge council --set` | 0 · 2 no reason, or an unknown lens · 3 unknown slug |
+| `challenge note` | 0 · 2 malformed (incl. a `findings[]` key) · 3 unknown slug |
+| `challenge premise <slug> <id> --dismiss` | 0 · 2 no reason · 3 unknown id |
+| `challenge opportunity <slug> <id> --take\|--drop` | 0 · 2 no reason, or neither/both flags · 3 unknown id |
+| `challenge accept` / `rebut` | 0 · 2 no reason · 3 unknown id |
+| `challenge template` / `goals` | 0 · 2 refused (no reason, or no such file) · 3 unknown |
+| `challenge report` | 0 · 3 unknown |
+| `challenge init` | 0 · 2 exists, or a required flag is missing (`--goal`, `--audience`, `--done-means`, **`--council`**), or no template decision |
+
+## Per-finding freshness is COVERAGE-RELATIVE
+
+The `computeWikiFreshness` lesson, applied to findings. On resume, for each
+carried finding, the CLI asks: **did the lines this finding anchors actually
+change?**
+
+```
+$ orc challenge diff tsd-payments
+
+expected revision:  docs/tsd-payments-v2.md   FOUND   (3f9a… → b71c…, +48 −12)
+carried findings:   12   ·  9 touched  ·  3 untouched   ← F-003 F-009 F-011
+```
+
+**It is a hint for the human, not an input to the judge.** Untouched does not
+mean unfixed (the fix may be elsewhere), and touched does not mean fixed. Hard
+rule 11: the judge re-reads.
+
+## `MISSING-REVISION` lists, it does not adopt
+
+```
+expected revision:  docs/tsd-payments-v2.md   MISSING
+
+Candidates changed since iteration 1 (git):
+  1  docs/tsd-payments-v2.draft.md      +51 −12
+  2  docs/tsd-payments.md               +4  −0
+
+Which of these is the revision — or is the work not done yet?
+Record it:  orc challenge expect tsd-payments --set <path>
+```
+
+Picking the closest-looking file would be ORC guessing what the user did, and **a
+judge pointed at the wrong file produces a page of confident, useless findings.**
+The choice is recorded, so the next iteration knows too.
+
+## `challenge.json`
+
+THE LEDGER. Written ONLY by `orc challenge` — never by a model, the same rule
+`wiki-meta.json` lives under. What is NOT stored: `state`, `passed` (as a cycle
+fact), `stalled`. All computed.
+
+```jsonc
+{
+  "version": 1,
+  "slug": "tsd-payments",
+  "kind": "tsd",
+  "created_at": "12-08-2026 14:02:11",
+  "artifacts": [
+    { "path": "docs/tsd-payments.md", "sha": "b71c…", "seen_at_commit": "9fa41c2" }
+  ],
+  "template": { "source": "docs/templates/tsd.md", "frozen": "template.md",
+                "sha": "0c8e…", "version": 1 },
+  "goals": {
+    "frozen": "goals.md", "sha": "5d20…", "version": 1,
+    "goal": "a backend team implements this without asking me anything",
+    "audience": "backend engineers, 2 of 5 non-native English readers",
+    "done_means": "no open interface question and no TBD in §3–§7",
+    "out_of_scope": ["the mobile client"],
+    "context_refs": ["JIRA-4412"]
+  },
+  "revision": { "mode": "new-file", "pattern": "docs/tsd-payments-v{n}.md" },
+  "dimensions": ["D1","D2","D3","D4","D5","D6"],
+  "accepted": {}, "rebuttals": {}, "events": [],
+  "iterations": [
+    { "n": 1, "graded_against": 1, "graded_against_goal": 1,
+      "artifact_shas": { "docs/tsd-payments.md": "3f9a…" },
+      "lint": { "findings": 14 }, "reader": { "score": "8/12" },
+      "verdict_file": "iteration-01/verdict.md", "verdict_file_sha": "aa19…",
+      "dimensions": [ { "id": "D1", "status": "CHECKED", "findings": 2 } ],
+      "findings": [
+        { "id": "F-003", "dimension": "D2", "severity": "P0",
+          "anchor": "docs/tsd-payments.md:118", "serves": "done_means",
+          "carried": false, "outcome": null }
+      ],
+      "coverage_pct": 100, "blocking": 4, "passed": false, "advised": true }
+  ]
+}
+```
+
+## The state word list
+
+`AWAITING-JUDGE · AWAITING-FIX · AWAITING-RECHECK · PASSED · STALE-PASS ·
+MISSING-REVISION · TAMPERED`
+
+Mirrored in `bin/cli.js`'s `CHALLENGE_STATES` and `challengeStateOf()` —
+documented drift the token lint cannot see (a word list is not a single token),
+covered by a golden test instead. Change both together.
+
+## Ledger v2 (v0.49.1) — additive, and `council: null` is a real state
+
+Every v1 key keeps its name, its meaning and its position. Added:
+
+```jsonc
+{
+  "version": 2,
+  "council": ["reader","contrarian","executor"],   // FROZEN; null on a migrated v1 cycle
+  "council_version": 1,
+  "opportunities": { "X-002": { "raised_at": 2, "status": "open", "route": "brainstorm", "…": "…" } },
+  "premises":      { "Q-001": { "raised_at": 2, "disputes": "goal", "status": "open", "…": "…" } },
+  "iterations": [
+    { "n": 2,
+      "graded_against_council": 1,
+      "council": [
+        { "lens": "contrarian", "ran": true,  "raised": 6, "adopted": 4, "rejected": 1, "merged": 1, "out_of_goal": 0 },
+        { "lens": "outsider",   "ran": false, "reason": "usage limit reached mid-batch" }
+      ],
+      "council_coverage_pct": 100,
+      "findings": [
+        { "id": "C-004", "lens": "contrarian", "disposition": "adopted",
+          "corroborated_by": ["outsider"], "dimension": "D2", "severity": "P0", "…": "…" }
+      ]
+    }
+  ]
+}
+```
+
+- **`lens` is required on every finding.** A v1 iteration read back gets `judge`,
+  so the per-lens legend never gains a blank column.
+- **`council: null` is not "no council".** It means the roster was never
+  answered, and `orc challenge record` **refuses the next iteration by name**
+  (`council-unset`) until it is. A silent default would be ORC picking the
+  council — rule 12.
+- **`council_version`** increments on a recorded `recouncil` event, exactly like
+  `goals.version` and `template.version`, and the iteration rail draws a THIRD
+  version break for it: comparing an iteration judged by three lenses to one
+  judged by six is not a comparison.

package/templates/skills/orc-challenge/references/dimensions.md

@@ -0,0 +1,121 @@
+# The seven dimensions
+
+Selected per cycle (`--dimensions D1,D2,D4,D5`). A README does not need D2.
+
+**A deselected dimension is `NOT-SELECTED`; a selected dimension that could not
+run is `NOT-CHECKED` WITH ITS REASON.** Two different words on purpose, and hard
+rule 6 forbids either being silent: a silently skipped check is indistinguishable
+from a forgotten one.
+
+| ID | Dimension | Produced by | Blocking by default |
+|---|---|---|---|
+| `D1` | Template conformance | lint (structure) + judge (substance) | yes |
+| `D2` | Technical completeness | judge (grounded) + contrarian + council executor | yes |
+| `D3` | Internal consistency | lint (links/anchors) + judge | yes |
+| `D4` | Cold comprehension | **reader (the score)** + outsider (load-bearing assumptions) | yes |
+| `D5` | Plain English for non-native readers | lint (metrics) + reader (judgment) + outsider | yes |
+| `D6` | Actionability | lint (markers) + judge + council executor | yes |
+| `D7` | Scope discipline | judge | advisory |
+
+**D4 stays the reader's score.** The outsider feeds D4 only where an assumption
+is load-bearing, and it returns **no score of its own** — a second comprehension
+number would leave a user asking which one is real. The seam between the two is
+in `council.md`, and it is structural, not stylistic.
+
+The two non-finding lenses feed **no dimension at all.** An `opportunity` and a
+`premise` never enter `findings[]` and never touch the pass gate, so they can
+never move a dimension's status.
+
+---
+
+## D1 — Template conformance
+
+Every required section present, in the template's order, none invented, none
+empty ceremony.
+
+**Evidence a finding must carry:** the section name, and either its absence, its
+position, or the word count under it. `orc challenge lint --template` already
+computes all four — the judge grades the SUBSTANCE (is the section actually doing
+its job) and never re-counts.
+
+With `--no-template`, D1 is `NOT-CHECKED — no template supplied`, in the verdict,
+in every report, and as a chip in the panel.
+
+## D2 — Technical completeness
+
+**For the document's own declared scope**, does the low-level design actually
+exist? Every claim anchored to a real file, or explicitly marked `ASSUMPTION`.
+
+**Evidence:** a `file:line` anchor that resolves, or the absence of one where the
+document asserts something about the code. This is the ONLY dimension no computer
+can reach, and it is where the judge should spend its effort.
+
+**`/orc-boundary` seam:** an area whose boundary card says `REFUSE` should not be
+judged for automation-friendly detail — the point of a REFUSE is that a human
+decides there. Note it and move on; do not raise a D2 finding demanding a
+step-by-step an agent could follow.
+
+## D3 — Internal consistency
+
+No self-contradiction. Names, ids, versions and units used the same way
+throughout. Every referenced artifact exists.
+
+**Evidence:** the two places that disagree, both quoted. A single quote is an
+opinion; two quotes are a contradiction.
+
+## D4 — Cold comprehension
+
+A reader with NO prior context can answer the artifact's own questions from the
+artifact alone.
+
+**This is why the reader agent exists, and why it is `low` effort.** To judge
+"can a reader without context follow this?" the reader must BE without context.
+The grounded judge has read the repository — it can no longer simulate ignorance
+and it will unconsciously fill every gap the document leaves.
+
+**A stronger, harder-thinking reader is a WORSE instrument.** Low effort does not
+reason around a gap: it reports what the document actually says rather than what
+a determined reader could reconstruct. That is precisely the measurement.
+
+**Evidence:** the scored questionnaire, and per finding, the LINE THAT OWED THE
+ANSWER — not the place the reader noticed it was missing.
+
+## D5 — Plain English for non-native readers
+
+Measured, not felt. `orc challenge lint` computes: acronyms used before they are
+defined, sentences over 25 words (with a p50/p90 distribution), a passive-voice
+percentage, idioms and phrasal verbs from `plain-english.md`, ambiguous
+quantifiers, and a Flesch–Kincaid grade estimate.
+
+**Evidence:** the metric AND the cost to the stated audience. A long sentence is
+not automatically a defect — the lint is a signal, the judge decides. A D5
+finding on an audience of "staff engineers, all native speakers" needs to justify
+itself.
+
+## D6 — Actionability
+
+An implementer can build from it without asking a question. Every `TBD`, `etc.`,
+`as needed`, `and so on` is a finding, and so is every ambiguous quantifier
+(`some`, `several`, `appropriate`, `reasonable`, `quickly`, `robust`).
+
+**Evidence:** the marker, quoted, plus the DECISION it is standing in for.
+"§4.2 says the retry budget is `TBD`" is a finding; "§4.2 could be clearer" is
+not.
+
+## D7 — Scope discipline (advisory by default)
+
+The artifact stays inside its own declared scope and does not quietly annex an
+adjacent one.
+
+**Evidence:** the `out_of_scope` entry from `goals.md` that the artifact crossed,
+plus the line that crossed it. **Without a declared `out_of_scope`, every D7
+finding is a guess** — which is why intake asks for it once and accepts
+"nothing".
+
+---
+
+## The enum
+
+`D1 D2 D3 D4 D5 D6 D7`. Mirrored in `bin/cli.js`'s `CHALLENGE_DIMS` and its
+`--dimensions` validator — documented drift the token lint cannot see, covered by
+a golden test instead. Change both together.

package/templates/skills/orc-challenge/references/fix-brief.md

@@ -0,0 +1,130 @@
+# The stop, and `fix-brief-NN.md`
+
+## The stop sequence (C8)
+
+**Written by ORC itself, never by a dispatched agent** — the v0.42.0 rule: a
+dispatch inside the stop sequence lets a stop fail because a subagent did.
+
+1. `orc challenge record` — append the iteration, compute the verdict.
+2. Write `fix-brief-NN.md`.
+3. Write `{run_dir}/{slug}/RESUME.md` with the one parseable line:
+   ```
+   Where it stands:  /orc-challenge · iteration 2 · awaiting fix · 4 blocking findings
+   ```
+   Keep that shape — it is the line `orc resume` and `orc run list` parse, which
+   is how a listing never has to open the ledger. **`RESUME.md` existing IS the
+   "run unfinished" flag**, so this is free integration.
+4. `orc challenge report <slug>` — re-derive `CHALLENGE.md`.
+5. Dispatch the trace packet for the iteration.
+6. Print the stop block and **END THE TURN.** No follow-up question, no "want me
+   to fix it?" — offering would be hard rule 1 with better manners.
+
+On PASS instead: no advisor, `orc challenge report` writes the final report,
+DELETE `RESUME.md`, dispatch the `FINISH` packet, delete `.current`.
+
+## The file
+
+`orc/orc-challenge/<slug>/fix-brief-NN.md` — named for the iteration it CLOSES.
+(`iteration-1-continue-to-2` reads as a file about a transition; this is a file
+about work to do.)
+
+It opens with a fenced block that is literally the prompt to paste:
+
+````markdown
+# Fix brief — iteration 1 · tsd-payments
+
+**Goal (frozen v1):** a backend team implements this without asking me anything
+**Audience:** backend engineers, 2 of 5 non-native English readers
+**Done means:** no open interface question and no TBD in §3–§7
+
+## Paste this into a NEW Claude Code session
+
+```
+Fix the findings in orc/orc-challenge/tsd-payments/fix-brief-01.md.
+
+Artifact:  docs/tsd-payments.md
+Goal:      orc/orc-challenge/tsd-payments/goals.md  (read this first)
+
+Write the revised version to:  docs/tsd-payments-v2.md
+(see "Where to put the revised version" in the brief)
+
+Rules:
+- Change the artifact only. Do not edit anything under orc/orc-challenge/.
+- Do not mark findings resolved. The next judgement decides that.
+- If you think a finding is wrong, do not argue with it here —
+  run: orc challenge rebut tsd-payments F-007 "why"
+
+When you are done, start ANOTHER new session and run:
+  /orc-challenge tsd-payments
+```
+
+## Where to put the revised version
+
+  Write to:      docs/tsd-payments-v2.md        ← this exact path
+  Copied from:   docs/tsd-payments.md           (iteration 1's version)
+  Do NOT write:  anything under orc/orc-challenge/tsd-payments/
+
+  When you are done, this is what the next session will look for.
+  If you must use a different path, run:
+    orc challenge expect tsd-payments --set <path>
+
+## 4 blocking · 6 advisory · grouped by root cause
+…
+````
+
+**A plan the user cannot deviate from is a plan they will deviate from
+silently.** The escape is a recorded command, not a guess — and that is why
+`orc challenge diff` resolves the expectation FIRST, so the resumed session opens
+knowing whether the work exists.
+
+When it does not, the state is `MISSING-REVISION` and the CLI **lists candidates
+without adopting one** (`cycle-state.md`). Open the resumed session with that
+list and let the user say which file is theirs — a judge pointed at the wrong
+file writes a page of confident, useless findings.
+
+## Below the paste block
+
+Per the advisor's grouping, in the advisor's suggested order:
+
+- the **group**, its **root cause** in one sentence, and the dependency reason
+  the order rests on (*"fix the glossary first — six D5 findings dissolve"*)
+- per finding: `id`, the anchor, the quote, what is wrong, the **consequence**,
+  and the **acceptance line** — *"fixed when §4.2 names the retry budget and the
+  dead-letter destination"*
+- the **decisions that are not defects**, routed: a P0/P1 that is really an
+  unmade decision ("the doc never says whether refunds are idempotent") belongs
+  in `/orc-pact` as a constraint, or in `/orc-grill` as a question — not in a
+  fifth iteration of a document review
+- **accepted exceptions**, if any, so the fixer does not fix something the user
+  already signed off
+
+## What the brief must NEVER contain
+
+- rewritten prose, a suggested paragraph, or a diff. That is the fixer's job, and
+  handing over wording is fixing by another name.
+- a claim that a finding is easy, or an estimate in hours. Effort is in the
+  artifact's own units — sections, endpoints, rows.
+- a promise about what the next judgement will say.
+
+## The council changes the ORDER of the brief (v0.49.1)
+
+Three blocks, in this order, and the order is the argument:
+
+1. **Open premise challenges — FIRST.** A premise disputes the frozen goal, and
+   the goal is the yardstick every finding below it was measured against. If the
+   user adopts one, some of the findings underneath stop mattering. Print each
+   with its `reframe` and its `cheapest_test`, and the two commands that resolve
+   it — `orc challenge goals <slug> --set <path> --reason "…"` (adopt) or
+   `orc challenge premise <slug> <id> --dismiss --reason "…"`. **Neither is
+   automatic, and ORC never picks.**
+2. **The findings**, grouped by the advisor's root causes, exactly as before.
+   A council-origin finding shows its raiser (`raised by the contrarian · adopted
+   by the judge`) — an id is permanent, and so is its credit.
+3. **Opportunities — LAST, and clearly marked NOT WORK.** They never block and
+   nothing here is required. Each carries its `first_step` and its route, and the
+   route is where it belongs *next*: `/orc-brainstorm`, `/orc-pact`,
+   `/orc-grill`, or nowhere yet. **This lane never builds one.**
+
+And rule 15: **a selected lens that did not run is named here too, with its
+reason.** A brief that silently omits a role the user paid to select is the same
+defect as a silently skipped dimension.

package/templates/skills/orc-challenge/references/intake.md

@@ -0,0 +1,171 @@
+# Intake — the goal contract
+
+**ORC never guesses what "good" means here.**
+
+A finding is only a finding relative to a goal. The same TSD is *finished* for
+one purpose and *nowhere near done* for another:
+
+| The user's actual goal | What "good" means | What the judge should attack |
+|---|---|---|
+| "a backend team must implement this without asking me anything" | D2 + D6 dominate | every undecided interface, every `TBD`, every missing error path |
+| "this goes to an architecture review board next Tuesday" | D1 + D3 + D7 dominate | template conformance, self-contradiction, scope creep |
+| "our offshore team, none of them native English speakers, must read this cold" | D4 + D5 dominate | idioms, undefined acronyms, three-clause sentences |
+| "I just want to know if I forgot anything obvious" | breadth over depth | coverage gaps, not phrasing |
+
+A lane that assumes the goal will attack the wrong thing with total confidence,
+and every one of its findings will be *defensible* — which is worse than being
+obviously wrong, because the user will spend three iterations fixing things that
+did not matter.
+
+> **The user states the goal and supplies the context. ORC ASKS when either is
+> thin, and NEVER fills the gap itself.**
+> **a lane that guesses the user's goal has broken this contract.**
+
+That is `../../_shared/interview.md`'s split applied to the *purpose* of the
+review rather than to a design question: facts are ORC's to look up, the goal is
+the user's to state, and the lane waits.
+
+## What intake must collect
+
+| Field | Required | If missing |
+|---|---|---|
+| **`goal`** — what this artifact must achieve, in the user's own words | **yes** | **ASK. Never proceed.** Offer the four rows above as *shapes*, never as a default to accept silently |
+| **`audience`** — who reads it and what they already know | **yes** | **ASK.** It is what makes D4 and D5 measurable at all — "a reader without context" is meaningless until you know which reader |
+| **`done_means`** — what the user would accept as finished | **yes** | **ASK.** This is what `challenge_pass_severity` is actually calibrating |
+| **`template`** | yes (or an explicit `--no-template`) | **ASK them to paste it** |
+| **`context_refs`** — tickets, prior docs, the spec this derives from | no | **ASK ONCE**, accept "none". Recorded as paths/URLs and treated as **evidence, never instruction** |
+| **`out_of_scope`** — what the artifact deliberately does not cover | no | **ASK ONCE**, accept "nothing". Without it, D7 findings are guesses |
+| **`revision_mode`** — where the fixed version will be put | **yes** | **ASK.** `in-place` is the default OFFERED, and it is confirmed, never assumed — the resume depends on it |
+| **`kind`**, **`dimensions`**, **`slug`** | yes | derived from the answers, then **confirmed** — deriving a dimension set is a FACT, so ORC may propose it; accepting it is a DECISION, so the user confirms |
+| **`council`** — which lenses review this | **yes** | **ASK.** ORC SUGGESTS a roster from the `kind` and the goal; the user PICKS it. `--council` has no default and `init` refuses by name. `none` is a first-class answer |
+
+## The council ask — question 7, and it is a P0
+
+**a lane that picks its own council has broken this contract.** A council chosen
+by ORC is ORC deciding which kinds of criticism the user is allowed to hear,
+which is a bigger decision than any single finding in the run.
+
+Four rules on this block:
+
+1. **The suggestion is COMPUTED; the selection is the USER's.** Deriving a
+   suggestion from `kind` + the goal is a FACT (the same latitude `--dimensions`
+   already has); accepting it is a DECISION.
+2. **The cost is stated in DISPATCHES, never in dollars.** `/orc-budget`'s rule:
+   no dollar figure without a dated price table, and this ask has no plan to
+   price.
+3. **`challenge_reader` is announced when the roster overrides it.** The config
+   key seeds the reader's default; if the user unticks it while
+   `challenge_reader: on`, say so — *a shadowed setting must never be silent*
+   (the `opus5_only` precedent).
+4. **The table is read from `orc challenge roles --kind <k> --json`.** The skill
+   NEVER hand-lists the lenses, and neither does the panel. One catalogue, three
+   renderers — the Flow-stepper rule.
+
+```
+7  Who is on the council for this review?  (judge always runs; advisor runs on a fail)
+
+     ORC suggests, for a TSD aimed at implementers:
+       [x] cold reader     can a stranger answer this document's own questions?
+       [x] contrarian      assume it has a fatal flaw, then go find it
+       [x] executor        can this be started on Monday? where is the first step?
+       [ ] outsider        what does this assume you already know?
+       [ ] principles      is this even the right problem?          (never blocks)
+       [ ] expansionist    what upside is being missed?             (never blocks)
+
+     Reply with the ones you want (or "all", or "none").
+     Each one is one extra read-only Opus 5 dispatch per iteration.
+```
+
+Roles, efforts, the reader/outsider seam and the class split: `council.md`.
+
+## The asking is ONE round, not an interrogation
+
+Every question that is ready goes in the same round — the
+`../../_shared/interview.md` round format. If the user answers three of six, ask
+the remaining three in a second round rather than filling them in.
+
+```
+Before I can judge this, I need to know what "good" means for it. Seven
+questions, one round:
+
+1  What must this document achieve?  (e.g. "a backend team implements it without
+   asking me anything" · "it survives Tuesday's review board" · "our offshore
+   team reads it cold")
+2  Who reads it, and what do they already know?
+3  What would you accept as finished?
+4  Do you have a template it should follow? Paste it, or give me a path.
+   (If you genuinely have none, say so — D1 will report NOT-CHECKED and say why.)
+5  Anything deliberately OUT of scope?
+6  When you fix it, where will the fixed version go?
+      a  over the same file        b  docs/<name>-v{n}.md        c  a folder
+7  Who is on the council?  (the block above — I suggest, you pick)
+```
+
+## "I don't know yet" is a legitimate answer to `goal`
+
+And it is the signal to offer `/orc-grill` through
+`../../_shared/lane-suspend.md` (`RETURN-TO`). A user who cannot say what the
+document is for does not need a document review; they need the decision lane, and
+then to come back. The gate is lane-suspend's tight one — a DECISION, a
+PREREQUISITE, and a SUBTREE — and the resume rule applies: re-write `.current`
+AND `touch the trace file` in the SAME step.
+
+## Where the goal lives
+
+The goal is prose the user wrote in this session, and rule 3 forbids handing the
+judge prose from this session. The resolution is the same one the template uses:
+**freeze it to disk.**
+
+```
+orc/orc-challenge/<slug>/goals.md      ← frozen at intake, v1
+```
+
+The judge slice then carries `goals.md` as a PATH, like everything else in
+`sealed-slice.md`. Every iteration's judge reads the identical goal from the
+identical file.
+
+It is frozen exactly like the template: changing it is a `regoal` event
+(`orc challenge goals <slug> --set <path> --reason "…"`), prior iterations are
+stamped `graded_against_goal`, and the panel draws the version break — because a
+review history against a moving goal is not a history.
+
+**Every downstream artifact restates the goal** so nobody ever fixes in the dark:
+the top of `verdict.md`, the top of `advice.md`, the paste block in
+`fix-brief-NN.md`, `CHALLENGE.md`, and the final report.
+
+**And every finding must name which goal element it serves.** A finding that
+cannot be traced to the stated goal, audience or `done_means` is out of scope and
+is dropped by `orc challenge record`. That is the mechanism that stops a judge
+with a large context window from reviewing the entire universe.
+
+## Where the revised version goes
+
+`revision_mode` is collected here, frozen into `goals.md`, and restated in every
+fix brief — see `fix-brief.md` for the `Where to put the revised version` block.
+**The resumed session must never ask "where did you put the fixed version?"** It
+is a fact the cycle already owns, and asking for it is rule 0's failure mode in
+miniature.
+
+| Mode | The fixer writes to | Resume checks |
+|---|---|---|
+| `in-place` *(default offered, confirmed not assumed)* | the artifact's existing path | that path's sha vs the last iteration's |
+| `new-file` | a declared pattern — `docs/tsd-payments-v{n}.md` | the pattern resolved at `n = iteration + 1` |
+| `directory` | a declared folder — for `mixed` and `code` kinds | every tracked file under it, sha'd per file |
+
+## Closing intake
+
+```bash
+orc challenge init <slug> \
+  --artifact docs/tsd-payments.md --kind tsd \
+  --goal "…" --audience "…" --done-means "…" \
+  --out-of-scope "…" --context-ref "…" \
+  --template docs/templates/tsd.md \
+  --dimensions D1,D2,D3,D4,D5,D6 \
+  --council reader,contrarian,executor \
+  --revision new-file --revision-pattern "docs/tsd-payments-v{n}.md"
+```
+
+`--goal`, `--audience`, `--done-means` and `--council` have **no default value**:
+a run that tried to skip this round fails at the CLI, by name, rather than
+silently inventing a purpose or a roster. That is rules 0 and 12 made structural
+instead of merely written down.

package/templates/skills/orc-challenge/references/kinds.md

@@ -0,0 +1,44 @@
+# Artifact kinds
+
+The kind picks a **default dimension set** and a **default template hint**. It
+never invents a template.
+
+| Kind | Typical artifact | Default dimensions | Default template hint |
+|---|---|---|---|
+| `tsd` | Technical Solution/Spec Document | D1 D2 D3 D4 D5 D6 | user-supplied — asked for, never guessed |
+| `prd` | Product requirement doc | D1 D3 D4 D5 D6 D7 | user-supplied |
+| `adr` | Architecture Decision Record | D1 D2 D3 D7 | user-supplied, or the repo's existing ADRs |
+| `api-contract` | OpenAPI / proto / GraphQL SDL | D1 D2 D3 D6 | the repo's existing contract files |
+| `readme` | README / onboarding doc | D1 D3 D4 D5 | user-supplied |
+| `runbook` | Ops runbook | D1 D3 D4 D6 | user-supplied |
+| `plan` | An ORC plan or a written implementation plan | D1 D2 D3 D6 D7 | `_shared/stack-plan.md`-style structure |
+| `code` | A module, a package, a PR-sized change | D2 D3 D4 D6 | **`.claude/orc/patterns/<lang>-pattern.md`** |
+| `mixed` | A folder of several of the above | per artifact | per artifact |
+
+**A default is a PROPOSAL.** Deriving a dimension set from a kind is a fact, so
+ORC may propose it; accepting it is a decision, so the user confirms it at
+intake. Never apply one silently.
+
+## `code` — the template problem is already solved
+
+For `kind: code` the cached code-pattern IS the template. It is a file ORC
+already generates (`/orc-pattern`), it already reconciles the project's real
+conventions against a per-language playbook, and it already distinguishes
+CONVENTIONS (which defer to the project) from INVARIANTS (which are always
+enforced). Probe for it the deterministic way — `orc pattern status <lang>`,
+exit 0 cached / 1 absent / 2 unknown language key
+(`../../_shared/detecting-artifacts.md`) — and if it is absent, say so and offer
+`/orc-pattern`. Never substitute a generic style guide.
+
+**The cold reader's question changes shape but not nature:** *"can a new engineer
+understand this module without asking anyone?"* Same instrument, different
+artifact.
+
+## `mixed` — a folder
+
+Several artifacts, one cycle, one PASS. The cycle is ATOMIC: a TSD split over
+three files passes as one document, because a reader reads it as one document.
+Each artifact gets its own sha in the ledger, so `orc challenge diff` still tells
+you which one moved.
+
+Use `--revision directory` so the fixer has one declared place to write.