@azure-id/orc 1.8.2 → 1.9.1

package/templates/skills/_shared/read-ladder.md

@@ -26,7 +26,7 @@ Escalate one step at a time. Stop at the step that answers the question.
 
 ## Step 0 — ask the graph (always first; the CLI decides if it is on)
 
-Before step 1, run `orc graph ctx <symbol|file[:line]> --if-enabled --json`
+Before step 1, run `orc graph ctx <symbol|file[:line]> --if-enabled --json --brief`
 yourself. You do not need to know whether the graph is on. Exit 0 → the card
 answers step 1 and step 2 together: where the symbol is, its line range, who
 calls or uses it, what it calls, and which effects it has. Then continue at
@@ -40,6 +40,19 @@ footer says how many lines it cut. Use it for the CALLER'S range, the callee's,
 the neighbour you will not touch. **It never replaces exception 1**: a file you
 will EDIT is read IN FULL with `Read` first, because an `old_string` rebuilt
 from a printed range is the same corruption bug as one rebuilt from an outline.
+**`--callers-source` adds six lines around each confident call site (≤ 5)**
+(v1.9.1), charged against the same `--budget` after everything else. A file you
+will EDIT is still read in full with `Read` first — this is for the callers you
+will not touch.
+
+**Ask a language server when the card cannot be exact** (v1.9.1). If the card
+answers `AMBIGUOUS (n)` for a callee, or `← maybe <n>` for callers, and an `LSP`
+tool is available in this session, run `LSP findReferences` (callers) or
+`goToDefinition` (a callee) at the card's `lsp_at` — file, line, character —
+before any Grep. A language server's answer is EXACT; the card's `AMBIGUOUS` is a
+list of candidates. Without an LSP tool, or with `lsp_at: null`, the ladder
+continues as before.
+
 Exit 3 (off) → skip step 0 for the rest of the task. Exit 1 (no index) or 4 (not
 in the graph) → step 1 as before. Name the card targets you used in
 `graph_used`. Both exceptions below apply unchanged.

package/templates/skills/_shared/return-validation.md

@@ -231,6 +231,28 @@ A rule the slice could not honour because this lane structurally cannot do it
 comes back as `unsupported_request`, relayed as a gap. **Never a guessed
 compromise.**
 
+## 5d. Reproduce-first attestation (when a `repro` was requested — v1.9.0)
+
+A slice that carried `repro: {required: true, kind, hint}` must come back with a
+`repro` field. Either both runs, quoted verbatim, or an honest `none`:
+
+```
+repro: { command, before: {exit_code, tail}, after: {exit_code, tail} }
+repro: none  — <one line of reason>
+```
+
+Two malformed shapes, and they are the whole point of the field. **`status=done`
+with `before.exit_code` 0** means the "reproduction" never failed, so it proved
+nothing; **`status=done` with a non-zero `after.exit_code`** means the bug is
+still there. Either one is a failure of the return, not a finding about the
+code. A `repro: none` is a valid answer — a defect with no reachable entry point
+and no runner cannot be shown red — and the lane says **not reproduced** out
+loud rather than letting a green suite imply a fixed bug.
+
+`repro` is required ONLY when the slice carried `repro.required: true`. A slice
+that asked for none gets none back, exactly like `tdd_spec`, `wiki_used` and
+`graph_used`.
+
 ## 6. Worktree delta (post-wave, every lane that dispatches executors)
 
 Compare `git status --short` before and after each dispatch. A path that

package/templates/skills/context-combiner/SKILL.md

@@ -11,10 +11,10 @@ description: >
   collapsed, conflicts, ordering) one issue at a time; proves NOTHING WAS LOST
   via a source coverage matrix and a 100% coverage gate before handoff;
   spot-checks inherited evidence and marks stale anchors; writes
-  combined-report.md + combined-requirement-spec.md (the merged spec reuses the
-  requirement-spec schema, so the planner/build pipeline is unchanged). Full
-  lane only (Opus 5 high). The orchestrator DISPATCHES this to a subagent —
-  it never combines itself, and the combiner never builds or spawns subagents.
+  combined-report.md + combined-requirement-spec.md, which reuse the
+  requirement-spec schema, so the planner/build pipeline is unchanged. Full
+  lane only. The orchestrator DISPATCHES this to a subagent — it never
+  combines itself, and the combiner never spawns subagents.
 ---
 
 # CONTEXT-COMBINER
@@ -211,12 +211,12 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 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.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane context-combiner --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[]`.
+command you are about to run, out loud, before running it.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane context-combiner --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[]`.

package/templates/skills/orc/SKILL.md

@@ -205,7 +205,7 @@ them; they are never dispatched as subagents).
 - Phase 5.5 → `../_shared/phases/security-checklist.md`; 6.5 → `subskills/orc-testgen/`
 - Phase 8 → `subskills/orc-pr/SKILL.md` (template `subskills/orc-pr/pr.md`);
   stack gate → `subskills/orc-pr/stack-gate.md` + `_shared/pr-templates.md`
-- Code graph cache, NEVER skipped (§0 of the contract) — `orc graph status --if-enabled --heal --json` at preflight BEFORE the first dispatch (builds or updates it) · ONE `orc graph ctx <declared files>` call per slice · `orc graph map` FIRST at planning (orientation — before any Glob, before `impact`) then `orc graph impact` + `orc graph cochange`, `orc graph changes` at review · `orc graph coverage` before you trust a card's silence · `orc graph update` + `orc graph notes` at every wave close and ship · print each JSON `line`, copy each `trace` VERBATIM (CLI-resolved) → `../_shared/code-graph.md`
+- Code graph cache, NEVER skipped (§0 of the contract) — `orc graph status --if-enabled --heal --json` at preflight BEFORE the first dispatch (builds or updates it) · ONE `orc graph ctx <declared files>` call per slice · `orc graph map` FIRST at planning (orientation — before any Glob, before `impact`) then `orc graph impact` + `orc graph cochange`, `orc graph changes` at review · `orc graph coverage` before you trust a card's silence · `orc graph update` + `orc graph notes` at every wave close and ship · every `--json` read carries `--brief` · print each JSON `line`, copy each `trace` VERBATIM (CLI-resolved) → `../_shared/code-graph.md`
 - Schemas (you own; pass slices only): `schemas/intent-spec.md`,
   `schemas/planning-output.md`, `schemas/checkpoint.md`
 - Worked example (orient only — never execute from it) → `examples/full-run-mock.md`

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

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

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

@@ -74,9 +74,9 @@ hand off to orc-mini via the fallback contract below. Never stop the chat.
 
 **e. Code graph cache — NOT a gate, and never skipped** (`../_shared/code-graph.md` §0). Every call carries
 `--if-enabled`: exit 3 = off → print `graph: off` once, make no other graph call. Print each JSON `line`; put
-each `trace` in the next packet VERBATIM. (1) **Here:** `orc graph status --if-enabled --heal --json` builds or
-updates the cache itself. (2) **F2 slice:** ONE `orc graph ctx <declared files> --if-enabled --json` → its `card`
-is the `graph` block; the return carries `graph_used`. (3) **F3 GREEN:** `orc graph update --if-enabled --json`,
+each `trace` in the next packet VERBATIM. (1) **Here:** `orc graph status --if-enabled --heal --json --brief` builds or
+updates the cache itself. (2) **F2 slice:** ONE `orc graph ctx <declared files> --if-enabled --json --brief` → its `card`
+is the `graph` block; the return carries `graph_used`. (3) **F3 GREEN:** `orc graph update --if-enabled --json --brief`,
 then one `orc graph notes pending` batch — the next run starts from this cache. A missing graph never falls back.
 
 **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.