@azure-id/orc 0.55.0

package/templates/skills/orc-challenge/references/plain-english.md

@@ -0,0 +1,98 @@
+# Plain English — what the lint actually checks
+
+`orc challenge lint <path> [--template <p>]` is the deterministic half of this
+lane. **Everything a computer can decide must never cost a model token**, and
+"is this English simple enough for a non-native reader" is *substantially*
+computable.
+
+## Two honesty rules — stated here and printed by the command
+
+1. **It is a SIGNAL, not a verdict** — the `/orc-aftermath` rule. A long sentence
+   is not automatically a defect. The lint never blocks; it feeds the judge, who
+   decides whether it costs the STATED AUDIENCE anything.
+2. **It is English-specific and heuristic.** The grade formula is an estimate and
+   passive-voice detection is a pattern match. Say so, once, on the output.
+
+Its real payoff: `lint.json` rides in the judge's slice, so the judge never
+spends tokens counting sentences — it spends them on D2, the only dimension no
+computer can reach. It is also useful standalone: `orc challenge lint README.md`
+needs no cycle, no model, and no ORC run at all.
+
+## Structure (needs `--template`)
+
+- heading tree extracted from both, at **depth 2–3 only** (the H1 is the
+  document's title; a title that differs from the template's is the document
+  being about something, not a missing section)
+- required sections **missing**, **out of order**, or **invented**
+- **empty ceremony** — a heading with under 15 words of body. A CONTAINER (its
+  next heading is deeper) is skipped: its children carry the body
+- table column-count consistency
+- code fences with no language tag
+- relative links and `file:line` anchors that do not resolve on disk
+
+## Prose (no template needed)
+
+| Check | Emits | Dimension |
+|---|---|---|
+| Acronym used before it is defined | `L-###` at first use | D5 |
+| Sentence over 25 words | `L-###`, plus a p50/p90 distribution | D5 |
+| Passive voice (be-verb + participle heuristic) | a **percentage**; findings only past 25% | D5 |
+| Idioms / phrasal verbs (the list below) | `L-###` | D5 |
+| Sentences opening with a bare `This`/`It`/`They` | `L-###` | D3 |
+| Placeholder markers | `L-###` | D6 |
+| Ambiguous quantifiers | `L-###` | D6 |
+| Flesch–Kincaid grade estimate | one number | — |
+
+**Sentences are measured over PARAGRAPHS, not over lines.** A hard-wrapped
+39-word sentence is still a 39-word sentence; splitting at the newline is how a
+length check silently passes every wrapped document.
+
+Code fences, tables, indented blocks, HTML comments, inline code and URL targets
+are stripped before any prose metric runs. Counting a URL as a long sentence is
+how a lint loses a reader's trust in one line of output.
+
+## The curated lists
+
+Mirrored in `bin/cli.js` (`LINT_IDIOMS`, `LINT_MARKERS`, `LINT_VAGUE`,
+`LINT_COMMON_ACRONYMS`) — documented drift the token lint cannot see, because a
+word list is not a single token. Change both together.
+
+### Idioms and phrasal verbs
+
+spin up · spun up · roll out · rolled out · kick off · kicked off · go-live ·
+reach out · circle back · touch base · move the needle · low-hanging fruit ·
+boil the ocean · ramp up · wind down · drill down · hash out · iron out ·
+flesh out · in the weeds · on the same page · at the end of the day · bake in ·
+baked in · double down · take a stab · ballpark · off the shelf
+
+### Placeholder markers
+
+`TBD` · `TODO` · `???` · `tbc` · `as needed` · `and so on` · `etc.` · `FIXME`
+
+### Ambiguous quantifiers
+
+some · several · appropriate · reasonable · quickly · efficient · efficiently ·
+properly · adequate · sufficient · various · a number of · as required ·
+if necessary · where applicable · robust · scalable · seamless
+
+### Acronyms every technical reader already has
+
+API · HTTP · HTTPS · JSON · YAML · XML · URL · URI · ID · UI · UX · CPU · RAM ·
+SQL · CSV · PDF · HTML · CSS · CI · CD · PR · MR · AWS · GCP · SDK · CLI · IDE ·
+OS · TLS · SSL · DNS · TCP · UDP · REST · CRUD · UUID · README · SLA · SLO · QA ·
+AI · ML · LLM · ADR · PRD · TSD · FAQ
+
+Everything else must be expanded on first use. That is a D5 finding, not a style
+opinion — a reader who does not know what `SoR` means cannot check whether the
+sentence is true.
+
+## Thresholds
+
+| | Default | Why |
+|---|---|---|
+| sentence length | 25 words | past this, a non-native reader re-reads |
+| passive voice | 25% of sentences | a percentage, never a per-sentence finding |
+| empty section | 15 words of body | below this it is ceremony, not content |
+
+These are constants in the CLI, not config keys. A knob per threshold would turn
+a signal into a negotiation.

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

@@ -0,0 +1,109 @@
+# How the judge scores — and why it cannot pass anything
+
+## Severity
+
+Reuses ORC's existing reviewer ladder, so nobody has to learn a second one.
+
+| | Meaning in this lane |
+|---|---|
+| **P0** | The artifact actively **misleads**. A reader who follows it will build the wrong thing. |
+| **P1** | The artifact is **incomplete or undecidable** at a load-bearing point. |
+| **P2** | Advisory — real, worth fixing, not a blocker. |
+| **P3** | Nit. |
+
+Severity is about the CONSEQUENCE to the stated audience, never about how much
+text is wrong. One missing number in an interface is a P0. Four paragraphs of
+clumsy phrasing in a document nobody reads cold is a P3.
+
+## PASS
+
+> **PASS is computed, never declared.**
+
+`PASS` = zero open findings at or above `challenge_pass_severity` (default `p1`),
+**after** accepted exceptions are subtracted, **and** every selected dimension
+reported a result.
+
+`orc challenge record` computes it. The judge cannot: it reports findings, and
+that is all. This is not ceremony — it removes leniency as a possibility. A judge
+that can pass something can be talked into passing something.
+A judge that **can only find, or fail to find** cannot.
+
+The second half is structural too: `record` REJECTS an iteration in which a
+selected dimension reported nothing, so "every dimension reported" is guaranteed
+before the severity question is even asked.
+
+## What a finding must carry
+
+```
+id · dimension · severity · anchor(file:line) · quote · what_is_wrong ·
+consequence · acceptance_line · serves
+```
+
+- **`consequence`** — what a reader BUILDS wrong because of this. A finding with
+  no consequence is a preference.
+- **`acceptance_line`** — what "fixed" looks like, concretely. It is what stops
+  the fixer guessing, and it is what gives the next judge an objective re-check
+  instead of a fresh opinion.
+- **`serves`** — which goal element the finding advances (`goal`, `audience`,
+  `done_means`, or a named `out_of_scope` entry). **A finding with no `serves` is
+  out of scope and is DROPPED by the CLI.**
+
+## Zero findings is a legitimate outcome
+
+Do not invent findings to look thorough. Do not soften one to be kind — you are
+not the one who decides whether the artifact passes, so there is nothing to be
+kind about.
+
+## The two escape valves
+
+A loop with no exit is a trap.
+
+- **`orc challenge accept <slug> <id> "reason"`** — the user accepts a blocking
+  finding as a known gap. It stops blocking immediately, it stays visible forever
+  in the report under **Accepted exceptions** with the reason. *Never automatic*
+  — the `/orc-pact` retirement rule.
+- **`orc challenge rebut <slug> <id> "reason"`** — the user thinks the judge is
+  wrong. The next judge must address it explicitly and return `withdrawn` (with
+  an admission) or `upheld` (with NEW evidence, not a restatement). **A rebutted
+  finding the next verdict ignores makes the iteration malformed and it is
+  rejected.** Without this, one bad finding loops forever and the user's only
+  move is to give up.
+
+## Convergence, not a cap
+
+There is no loop cap and there is no config key for one. Every other loop in ORC
+(TDD 3, drift recovery 2, quick repair 3) runs inside one session and costs
+tokens per turn. Here each turn is a separate human sitting down to work, and a
+cap that refuses on iteration 6 would be refusing to review a hard document.
+
+So: measure instead.
+
+```
+convergence: 9 → 4 → 4 → 4 blocking findings over 4 iterations
+             ⚠ stalled — no net reduction in 3 iterations.
+
+Three honest options:
+  1  Narrow the rubric          orc challenge init … --dimensions D1,D2,D6
+  2  Accept them as known gaps  orc challenge accept tsd-payments F-003 "…"
+  3  Keep going                 /orc-challenge tsd-payments
+```
+
+It prints once when `stalled` flips true, and again only if the count RISES.
+Never a block, never a nag repeated every iteration.
+
+## Severity is about the consequence, never about who raised it
+
+A council lens does not get a severity discount for being clever or a bump for
+being enthusiastic. The ladder is unchanged and it asks one question: **what
+happens to the STATED audience if this ships as written?**
+
+`corroborated_by` — two lenses independently landing on the same defect — is the
+strongest comprehension evidence this lane can produce, and it is **a signal,
+never an automatic severity bump.** (The `/orc-aftermath` rule: churn is a
+signal, not a verdict.) The judge may raise a severity because the corroboration
+told it something about the consequence; it may never raise one because two
+agents agreed.
+
+And the contrarian's rule against manufacturing findings is the same rule
+everybody else here lives under: **never invent a finding to look thorough, and
+never soften one to look balanced.** Balance is the judge's job.

package/templates/skills/orc-challenge/references/sealed-slice.md

@@ -0,0 +1,97 @@
+# The sealed slice
+
+The single most important sentence in this lane:
+
+> **the judge slice is SEALED** — its dispatch payload contains PATHS and IDs. It
+> never contains prose written in this session.
+
+**A fix is a claim; a verdict is evidence.** The moment the judge is handed a
+summary of what changed, it is grading the summary. And the moment the session
+that wrote the fix also writes the slice, the summary is written by the party
+with an interest in passing.
+
+## The permitted field list — complete
+
+```
+goals:         orc/orc-challenge/tsd-payments/goals.md          (frozen, v1)
+artifact:      docs/tsd-payments.md
+template:      orc/orc-challenge/tsd-payments/template.md       (frozen, v1)
+dimensions:    <skill>/references/dimensions.md   (selected: D1 D2 D3 D4 D5 D6)
+lint:          orc/orc-challenge/tsd-payments/iteration-02/lint.json
+reader:        orc/orc-challenge/tsd-payments/iteration-02/council/reader.md
+contrarian:    orc/orc-challenge/tsd-payments/iteration-02/council/contrarian.md
+outsider:      orc/orc-challenge/tsd-payments/iteration-02/council/outsider.md
+executor:      orc/orc-challenge/tsd-payments/iteration-02/council/executor.md
+carry_ids:     F-003 F-007 C-002
+rebuttal_ids:  F-007
+```
+
+Every value is either a PATH or an ID. Nothing else may appear.
+
+One row per **finding** lens on the roster, and no more. A council report is a
+path to a file an *agent* wrote, so it does not breach the rule: the line this
+rule actually draws is *"a summary written by the party with an interest in
+passing"*, and no council member has one.
+
+`goals.md` is a path, not prose — which is exactly why the goal is frozen to disk
+at intake instead of being retyped into each dispatch. Every iteration's judge
+reads the identical goal from the identical file, forever.
+
+## The two reports that may NEVER appear
+
+**`council/principles.md` and `council/expansionist.md` are forbidden in the
+judge's slice.** Handing a judge a document arguing that the frozen goal is wrong
+biases every finding it produces afterwards, and an opportunity is not a defect
+at all. **The three finding lenses feed the judge; the two non-finding lenses
+feed the user** — see `council.md`.
+
+## What may NOT appear
+
+- what changed since last time
+- the diff, or `orc challenge diff`'s output
+- the fix brief
+- the previous `advice.md`
+- the finding BODIES
+- any sentence beginning "the user says", "they fixed", "this should now be"
+- a severity suggestion, a hint about what to look at, or an expected outcome
+
+**The judge opens `iteration-01/verdict.md` itself if it wants the carried
+bodies.** Reading them from disk is fine; being handed a summary of them is not,
+because a summary is where the bias enters.
+
+## The reader's slice is even tighter
+
+`orc-challenge-reader-opus-5-low` gets the artifact path(s), the questionnaire
+protocol, and **the `audience` line only**, lifted from `goals.md`.
+
+*Why the audience but not the goal:* "a reader without context" is meaningless
+until you say WHICH reader — a staff engineer and a non-native junior are
+different instruments. But telling the reader what the document is *trying to
+achieve* hands it the answers it is supposed to have to find, and D4 measures
+exactly the gap between the two.
+
+Its tools are `Read` and nothing else. Not `Glob`, not `Grep`, not `Bash`. **The
+instrument is defined by what it cannot reach.**
+
+## The outsider's slice is the tightest in the lane
+
+`orc-challenge-outsider-opus-5-low` gets **the artifact path(s) and its protocol.
+Nothing else.** Not the goal, not the audience, not the kind, not the template,
+not the repository. Its tools are `Read` and nothing else.
+
+Tighter than the reader, which at least knows who it is reading as. The outsider
+is not told, because the moment it can look anything up it stops being able to
+measure what a stranger cannot find out.
+
+## The advisor's slice is the loose one, on purpose
+
+`orc-challenge-advisor-opus-5-med` gets `goals.md`, the verdict's findings, the
+council reports, the artifact and the repository. It needs the goal because ORDERING a fix is a goal
+question: which repair unblocks the most of what the user actually wants. It is
+dispatched only on a FAIL, and it never writes prose for the artifact.
+
+## Testable
+
+`test/payload.test.js` greps this file and `../SKILL.md` for the sealed-slice
+token and asserts the C4 dispatch block lists only path-shaped and ID-shaped
+fields.

package/templates/skills/orc-challenge/references/verdict-doc.md

@@ -0,0 +1,154 @@
+# `verdict.md` and the findings array
+
+Two halves of one return. The **prose** is for a human reading the review; the
+**array** is what `orc challenge record` gates and stores. They must agree —
+`record` re-checks the file's sha forever after, so an edit to one without the
+other shows up as `TAMPERED`.
+
+## The file
+
+`orc/orc-challenge/<slug>/iteration-NN/verdict.md`. `NN` is zero-padded so
+iteration 10 sorts after iteration 9.
+
+This is the file the reader thinks of as "the review". It lives inside its
+iteration folder because an iteration has four artifacts, not one:
+`lint.json` · `reader-report.md` · `verdict.md` · `advice.md` (absent on PASS).
+
+```markdown
+# Verdict — iteration 2 · 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
+
+Graded against template v1 · goal v1 · dimensions D1 D2 D3 D4 D5 D6
+
+## Summary
+
+Two sentences. What state the artifact is in, and what is standing between it
+and the stated goal. Not a list — the list is below.
+
+## Dimensions
+
+| ID | Status | Findings | Note |
+|---|---|---|---|
+| D1 | CHECKED | 0 | every required section is present and carries content |
+| D5 | NOT-CHECKED | — | challenge_reader is off |
+
+## Carried findings
+
+| id | outcome | why |
+|---|---|---|
+| F-001 | resolved | §3.2 now names the window as 24h |
+| F-003 | still-open | Scope is still `TBD` |
+| F-004 | withdrawn | the rebuttal is right — it is a quotation from JIRA-4412 |
+
+## New findings
+
+### F-014 · P1 · D2 — docs/tsd-payments.md:118
+
+> the idempotency window is applied appropriately
+
+**What is wrong:** the window is never given a value anywhere in the document.
+**Consequence:** two teams implementing from this will pick different windows,
+and the mismatch only shows up in production.
+**Fixed when:** §4.2 names the window in seconds and the dead-letter destination.
+**Serves:** done_means
+```
+
+**Every verdict restates the goal at the top.** Nobody should ever fix in the
+dark.
+
+## The array
+
+One object per finding — new AND carried, in the same array:
+
+```yaml
+- id: F-014                 # permanent. Never renumber, never reuse
+  dimension: D2             # one of D1…D7
+  severity: P1              # P0 | P1 | P2 | P3
+  anchor: "docs/tsd-payments.md:118"   # real, resolvable
+  quote: "the idempotency window is applied appropriately"
+  what_is_wrong: "…"
+  consequence: "…"          # what a reader BUILDS wrong
+  acceptance_line: "…"      # what "fixed" looks like, concretely
+  serves: done_means        # goal | audience | done_means | out_of_scope:<name>
+  # carried findings ALSO carry:
+  outcome: still-open       # resolved | still-open | superseded | withdrawn
+  reason: "…"               # required for withdrawn
+  superseded_by: F-021      # required for superseded
+```
+
+Plus, at the top level of the return:
+
+```yaml
+verdict_file: "iteration-02/verdict.md"
+lint:    { findings: 13, grade: 8.1 }
+reader:  { asked: 12, answered: 11, score: "11/12" }
+dimensions:
+  - { id: D1, status: CHECKED, findings: 0 }
+  - { id: D5, status: NOT-CHECKED, reason: "challenge_reader is off" }
+rebuttals_addressed:
+  - { id: F-004, result: withdrawn, reason: "agreed — it is a quotation" }
+```
+
+## What `record` rejects, by name
+
+| Rejection | Rule |
+|---|---|
+| a selected dimension reported nothing | 6 — silence is indistinguishable from a forgotten check |
+| `NOT-CHECKED` with no reason | 6 |
+| coverage below 100% | 4 — with the missing ids named |
+| an outcome on a finding that was not open | 4 |
+| `withdrawn` with no reason, `superseded` with no id | 4 |
+| an open rebuttal not addressed | the rebuttal contract |
+| the verdict file is missing from disk | 10 |
+| a bad severity or an unknown dimension | the enums |
+
+And one thing it does NOT reject: a finding with no `serves`. That one is
+**dropped**, counted, and reported — it is out of scope of the stated goal, which
+is a judge working outside its brief, not a broken return.
+
+## Writing the return to disk
+
+The skill writes the array to a temp JSON (inside the cycle folder), then:
+
+```bash
+orc challenge record <slug> --iteration N --from orc/orc-challenge/<slug>/iteration-NN/verdict.json
+```
+
+The CLI prints the `trace_line` for the iteration. Use it verbatim — do not
+compose a second wording for it.
+
+## The council section (v0.49.1)
+
+The verdict body gains one section, above the findings.
+
+**One row per roster lens, and a NOT-RUN row keeps its slot with its reason** —
+filtering it out makes *"the contrarian found nothing"* and *"the contrarian
+never ran"* look identical. Rule 15.
+
+```
+council v1 — 4 of 5 ran
+
+  RAN      reader        raised 3 · adopted 2 · merged 1 · rejected 0 · out-of-goal 0
+  RAN      contrarian    raised 6 · adopted 4 · merged 1 · rejected 1 · out-of-goal 0
+  RAN      outsider      raised 3 · adopted 1 · merged 2 · rejected 0 · out-of-goal 0
+  RAN      executor      raised 2 · adopted 2 · merged 0 · rejected 0 · out-of-goal 0
+  NOT-RUN  principles    usage limit reached mid-batch
+```
+
+Then the **disposition table** — every id the council raised, with the ONE
+disposition it got and its reason. `council_coverage_pct` must be 100 or
+`orc challenge record` rejects the verdict and names the missing ids.
+
+Every finding line carries its **lens**, and where two lenses landed on the same
+defect, `also found by: outsider`. **Corroboration is a signal, never an
+automatic severity bump.**
+
+An **adopted council finding keeps the raiser's id.** `C-004` is `C-004` here and
+in iteration 9.
+
+The council executor's `monday_morning` list is printed verbatim — including
+`monday_morning_stops_at`, which is the most legible sentence this lane produces
+for a non-engineer.

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

@@ -0,0 +1,199 @@
+---
+name: orc-claude
+description: >
+  CLAUDE.md builder/updater for the LOCAL project. Use for "/orc-claude",
+  "build a CLAUDE.md", "update the CLAUDE.md", or "refresh the CLAUDE.md".
+  Runs INDEPENDENTLY — no orchestrator, no run folder. Scans the repo for
+  ground-truth facts (verified commands, layout, conventions, boundaries) and
+  writes a section-fenced, version-stamped CLAUDE.md at the repo root — even
+  when ORC itself is installed globally. Never asks questions: P0 rules are a
+  template the user fills in themself. Refresh regenerates ONLY stale sections
+  and bumps the file version by 0.0.1. Never trims user-authored content;
+  never touches the orc-wiki pointer block. The skill dispatches the pinned
+  orc-claude-writer-opus-4-8-high agent — it never writes the file itself.
+---
+
+# ORC-CLAUDE (standalone)
+
+Build or maintain the **local project's** `CLAUDE.md` from verified repo facts.
+The target is ALWAYS `<repo root>/CLAUDE.md` of the current working directory —
+never `~/.claude/CLAUDE.md`, even if ORC is installed globally.
+
+**Dispatch, don't do.** Whatever model this chat runs on, the skill itself only
+selects the mode and spawns `orc-claude-writer-opus-4-8-high` (the pinned
+engine) — so the scan + writing always run at Opus 4.8 high regardless of the
+caller's tier. When `opus5_only: true` the engine is
+`orc-claude-writer-opus-5-med` instead (that mode FORCES it — see
+`../_shared/opus5-only.md`), and it then needs an Opus 5 main session.
+The one exception: the skill also writes the
+trace pointer + a few markers around that spawn (behavior-trace logging is
+permanent; see "Behavior trace"); that
+tracing is its ONLY self-write — the `CLAUDE.md` write is always the writer's.
+**Fully non-interactive: ask the user NOTHING.** No AskUserQuestion, no
+confirmation prompts. Dispatch, relay the report, stop.
+
+**Worked example** (orient only — never execute from it):
+`examples/claude-run-mock.md`.
+
+## The three modes (auto-selected, in this order)
+
+1. **REFRESH** — `CLAUDE.md` exists AND contains an `orc-claude:meta` header.
+   Recompute section fingerprints; regenerate ONLY stale fenced sections;
+   bump `version` by exactly 0.0.1; update `updated:` (DD-MM-YYYY). Nothing
+   stale → report "up to date (vX.Y.Z)" and write NOTHING (no bump, no bak).
+   Protocol: `references/refresh.md`.
+2. **UPDATE** — `CLAUDE.md` exists but has NO `orc-claude:meta` header (a
+   foreign / hand-written file). Copy it to `CLAUDE.md.bak` first (one bak,
+   overwritten each run; offer a `.gitignore` line for it in the report). Then
+   inject the meta header at the top and append/merge fenced generated
+   sections at version `0.0.1`.
+   **NEVER trim, delete, reorder, or rewrite existing user content — not one
+   line.** If a generated section would duplicate what the user already wrote,
+   generate the slimmer remainder or skip that section. The merged file MAY
+   exceed the budget (e.g. 600 existing lines + generated → 800): that is OK
+   by design — end the report with a hard note that the user should trim
+   unused content themself for better instruction-following.
+3. **CREATE** — no `CLAUDE.md` at the repo root. Generate a fresh one from
+   `references/template.md` at version `0.0.1`.
+
+Not inside a git repo / no project root findable → say so and stop.
+
+## Dispatch (the skill's only real job)
+
+Behavior-trace logging is permanent (always on). Weave the **Trace:** steps below
+into the procedure — this skill owns a minimal one-dispatch trace (full marker
+set in "Behavior trace").
+
+1. Detect the repo root and pick the mode (REFRESH / UPDATE / CREATE above —
+   header sniff only; the writer re-verifies). **Trace:** open the run now —
+   write `log_dir/.current` = `run-claude-<slug>-<DDMMYY>-<HHMMSS>.txt` and
+   `touch the trace file` of that name in the SAME step, BEFORE the spawn (a
+   pointer to a file that does not exist reads as dangling — the hook rotates
+   away from it and the run splits across two files).
+2. Spawn `orc-claude-writer-opus-4-8-high` — or `orc-claude-writer-opus-5-med`
+   when `opus5_only` — with: `mode`, `repo_root`,
+   `budget` (from a `budget=N` argument, else null), and the paths to
+   `references/template.md` + `references/refresh.md`. **Trace:** emit
+   `DISPATCH orc-claude-writer :: <mode> expect=opus-4-8/high` just before the
+   spawn (`expect=opus-5/medium` under `opus5_only` — the expectation is
+   derived from the agent NAME you actually dispatched, never from this line's
+   default; the hook then adds `SPAWN`/`RETURN` on its own).
+3. On return, check `actual_model`/`actual_effort` against the pinned tier —
+   mismatch → prepend a tier-downgrade warning to the report. **Trace:** emit
+   `VERIFY writer actual=<model>/<effort> ✅ MATCH` (or
+   `⛔ DOWNGRADE expected=opus-4-8/high`).
+4. Relay the Phase-3 report verbatim. **Trace:** emit
+   `FINISH :: <mode_ran> CLAUDE.md v<X.Y.Z>` (mode_ran may be `noop`), then
+   delete `log_dir/.current`. Then stop. The skill NEVER writes CLAUDE.md
+   itself — not even in a "trivial" refresh.
+
+The writer performs Phases 1–3 below.
+
+## Phase 1 — ground-truth scan (facts, never guesses)
+
+Read-only. Detect from real files, never from memory:
+
+- **Stack & manifests:** `package.json`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`, `pom.xml`/`build.gradle`, `*.csproj`, `composer.json`,
+  `Gemfile`, `mix.exs` … Monorepo? (workspaces, `pnpm-workspace.yaml`,
+  `turbo.json`, `nx.json`, multiple manifests).
+- **Commands:** only invocations that PROVABLY exist — a script in a manifest,
+  a Makefile/Taskfile target, a CI step. Prefer the single-test form when the
+  runner supports one. **Never invent a command.** Unverifiable → omit.
+- **Conventions:** lint/format/type configs (eslint, prettier, biome, ruff,
+  black, clippy, tsconfig strictness…) + a small sample of real source files.
+  Record only DEVIATIONS from language defaults.
+- **Boundaries:** generated/vendored/build dirs (from `.gitignore` + tree),
+  lockfiles, migration dirs, obvious legacy zones.
+- **Environment:** env-var NAMES referenced in code/config/`.env.example`
+  (never values), external services.
+
+## Phase 2 — generate / merge
+
+Follow `references/template.md` exactly: the meta header, the section order
+(Zone A rules → Zone B reference), and the fence grammar. Every generated
+section sits inside `<!-- orc-claude:section <name> -->` …
+`<!-- /orc-claude:section -->` fences so refresh can replace it surgically.
+Sections whose scan came back empty are OMITTED, not stubbed.
+
+**P0 is user-authored, always.** Emit the P0 placeholder template from
+`references/template.md` with its hard fill-it-yourself note. Never invent P0
+rules, never ask for them. Same for the other `@user` sections (Boundaries'
+user half, Gotchas, Glossary): placeholder + note, then leave.
+
+**Line budget — generated content only.** Default 400 lines, persisted as
+`line-budget:` in the meta header. The budget counts ONLY orc-claude's own
+output (header + fenced sections) — existing user content NEVER counts against
+it and is NEVER trimmed to meet it. If generation would exceed the budget,
+trim Zone B first: move overflow to a `docs/` file and leave an `@docs/...`
+pointer. Zone A is never cut. The user may pass a different budget as an
+argument (`/orc-claude budget=600`) — honor it and persist it in the header.
+
+**Wiki block is untouchable.** If the file contains an `ORC-WIKI:START` /
+`ORC-WIKI:END` block (managed by orc-wiki), byte-preserve it and generate no
+wiki-overlapping content. orc-claude never writes inside another skill's
+markers.
+
+## Phase 3 — report
+
+Show a short summary and STOP:
+
+```
+ORC-CLAUDE — <create|update|refresh> → CLAUDE.md v<X.Y.Z> (<DD-MM-YYYY>)
+Sections written: <list>   ·   skipped (empty scan): <list>
+Sections stale→refreshed: <list>            (refresh mode only)
+Preserved untouched: user content (<n> lines), wiki block
+Conflicts flagged (scan contradicts existing text — NOT auto-edited):
+  - <file says X, repo shows Y>
+Backup: CLAUDE.md.bak <written|not needed>   (add it to .gitignore)
+NOTE: file is <n> lines total (budget covers generated content only) — trim
+unused user content yourself for better instruction-following.
+Fill in the P0 / Gotchas / Glossary placeholders yourself — orc-claude never
+writes them for you.
+```
+
+## Behavior trace (PERMANENT — a minimal one-dispatch orchestrator; always on)
+
+orc-claude owns the trace protocol for its run exactly
+like the full orchestrator — but it is a SINGLE-DISPATCH lane, so it emits ONLY
+the markers it can truthfully witness. It does **not** emit `PHASE`/`SCORE`/
+`FINDING`/`VERDICT`: the scan/generate/report phases run INSIDE the writer
+sub-agent (which self-traces nothing — it only returns `actual_model`/
+`actual_effort`), and there is no scoring or review in this lane. Resolve
+`log_dir` (`../orc/config.md` default + `.claude/orc.config.yaml`)
+at start and follow `../orc/references/trace-protocol.md`. The marker set, in
+order (all under actor `orc`, plus the hook's `SPAWN`/`RETURN`):
+
+1. `log_dir/.current` = `run-claude-<slug>-<DDMMYY>-<HHMMSS>.txt` — written FIRST
+   (the hook also bootstraps it on the writer dispatch, so the skeleton is never
+   lost, and the end-of-run packet renames a bootstrapped file).
+2. `DISPATCH orc-claude-writer :: <mode> expect=opus-4-8/high` — before the
+   spawn. The hook then appends `SPAWN`/`RETURN` around the dispatch. The mode
+   rides in this line's tail (and in `FINISH`), so no separate mode marker.
+3. `VERIFY writer actual=<model>/<effort> ✅ MATCH` or
+   `⛔ DOWNGRADE expected=opus-4-8/high` — from the writer's returned
+   `actual_model`/`actual_effort` (the one honesty signal this lane feeds
+   `/orc-retro`).
+4. `FINISH :: <mode_ran> CLAUDE.md v<X.Y.Z>` (mode_ran may be `noop`), then
+   delete `.current`.
+
+Narration is **dispatched, never remembered**: record each marker with its REAL
+timestamp as its event happens, then — as a single-dispatch lane — dispatch the
+trace writer ONCE with the whole event list plus `decisions` (the WHY: mode
+choice, what the user asked) after the writer return validates and BEFORE you
+delete `.current`. Stamps are the run's timeline, never the write time, and a run
+that ends with zero new trace lines is a protocol violation. A noop refresh still
+traces the full cycle (ending `FINISH :: noop`) and still deletes `.current`.
+
+## Boundaries
+
+- **Writes ONLY** `CLAUDE.md`, `CLAUDE.md.bak`, and (on budget overflow) a
+  `docs/` overflow file. Never edits source code, never commits, never pushes.
+- **Never asks the user anything.** Placeholders + report notes replace every
+  question.
+- **Never deletes or rewrites user-authored lines** — contradictions are
+  flagged in the report, not fixed.
+- **Never touches** the orc-wiki managed block or any other skill's markers.
+- Version bumps are always exactly +0.0.1; dates are always DD-MM-YYYY.
+- Reminder: to see usage limits, tell the user to run `/usage` (never invoke
+  it programmatically).