@azure-id/orc 1.7.1 → 1.8.2

package/templates/skills/orc-diy/references/flow-schema.md

@@ -1,100 +1,101 @@
-# ORC-DIY — Flow config schema
-
-The single source of intent is `.claude/orc-diy.config.yaml`, written ONLY by
-the `orc diy` CLI (never by hand, never in a Claude session). Every write
-regenerates `.claude/orc/diy/flow.md` (the human-readable spec) and updates
-`.claude/orc/diy/flow.lock.json`, invalidating any previous compile.
-
-**Project-scoped only.** The config, lock, and compiled flow live in the
-project's `.claude/` — there is no global variant; `orc diy` rejects
-`--global`. One flow per project; `flow_name` is a display label, never a
-selector.
-
-## Keys (all set via `orc diy set <key> <value>`)
-
-| Key | Values (default first) | Meaning |
-|---|---|---|
-| `analyze` | `auto` / `off` / `mini` / `full` | Doc-intake analyst routing |
-| `planning` | `auto` / `own-planner` / `superpowers` / `openspec` | Planning route |
-| `pattern` | `ask` / `off` / `on` | Code-pattern gate on a cache miss |
-| `scoring` | `on` / `off` | Rubric scoring; `off` needs `fixed_executor` |
-| `fixed_executor` | (none) — an executor agent name | Used for every task when `scoring: off` |
-| `extra` | `off` / `on` | May this flow dispatch an executor to a non-Claude worker (`_shared/extra-dispatch.md`)? It decides WHETHER; `orc extra resolve` still decides WHERE, per task, at run time — route rows are NOT baked into the compiled flow, because the lock's staleness triggers cannot see the ledger change. `off` makes a globally-enabled Extra **INERT here**, announced once, so turning it on globally never silently changes a compiled flow |
-| `review` | `on` / `off` / `blocking-only` | Review phase strictness |
-| `security` | `off` / `ask` / `on` / `always` | Security pass; `always` drops the risk-floor trigger |
-| `verify` | `full` / `off` / `smoke` | Verify depth |
-| `testgen` | `off` / `ask` / `on` | Test-authoring phase |
-| `mock_example` | `ask` / `on` / `off` | Post-verify mocked example + drift recovery (`mock-examples/<slug>/`, never committed) |
-| `tdd` | `on` / `off` | TDD-anchored planning: plan-time `tdd_spec` (scoped by `disposition`), paired TDD tasks for the red proof, TDD gate in the verify slot |
-| `gotchas` | `on` / `off` | Repair memory: inject scope-matching gotchas into slices, record one when a repair loop goes red → green (`_shared/gotchas.md`) |
-| `wiki_gate` | `notice` / `off` / `hard` | Wiki freshness handling at preflight |
-| `post_ship_wiki_ask` | `on` / `off` | Post-ship wiki refresh offer on big runs |
-| `summary` | `full` / `off` / `short` | Summary depth |
-| `autonomy` | `interactive` / `semi` / `hands-off` | Who answers routine asks |
-| `ship_mode` | `ask` / `commit` / `pr` / `report-only` | Terminal ship behavior |
-| `session_tier` | `sonnet-4-6-{med,high}` / `opus-4-7-{med,high}` / `opus-4-8-{med,high,xhigh,max}` / `opus-5-{med,high,xhigh,max}` / `fable-5-{med,high,xhigh,max}` | Required main-session model+effort (default `opus-5-high`) |
-| `max_wave_tasks` | `3` (integer ≥ 1) | Wave hard cap |
-| `batch_pause_every` | `2` (integer ≥ 1) | Waves between pauses |
-| `rubric_bands` | `5` (2–8) | Scoring granularity (`scoring: on` only) |
-| `flow_name` | `my-flow` (slug) | Display label for traces/statusline |
-
-## Cross-key validation (CLI `orc diy validate`; also runs on every write)
-
-Hard errors (config not written):
-- `scoring: off` without a `fixed_executor`.
-- `fixed_executor` or any agent choice above `session_tier` (tier order:
-  haiku-4-5 < sonnet-4-6 < sonnet-5 < opus-4-7 < opus-4-8 < opus-5 < fable-5 —
-  subagents cannot exceed the main session; effort medium < high < xhigh < max).
-  A tier below `opus-5-high` clips the `[90,100]` band to the highest agent it
-  allows, at compile time.
-- `review: off` with `security` not `off` (the security pass reuses the
-  reviewer).
-- Anything that would disable a locked rule (see `locked-blocks.md`).
-
-Warnings (written, reported):
-- `scoring: off` with `rubric_bands` overridden (ignored).
-- `testgen` on/ask with `verify: off` (testgen normally follows verify).
-- `tdd: on` with `verify: off` (the TDD gate runs in the verify slot; plan-time
-  tests are authored but never gate the ship).
-- `autonomy: hands-off` with `ship_mode: commit` or `pr` (fully unattended
-  git actions).
-- `session_tier` below `opus-5-med` with `review`/`verify` on: the pinned
-  Opus 5 reviewer/verifier agents will silently run at the session's model —
-  the flow still works, honesty-checked by the tier-honesty locked rule.
-
-## `flow.lock.json` (machine state — written by the CLI only)
-
-```json
-{
-  "flow_name": "my-flow",
-  "session_tier": "opus-5-high",
-  "config_hash": "sha256 of orc-diy.config.yaml",
-  "flow_hash": "sha256 of flow.md",
-  "compiled_hash": "sha256 of FLOW-COMPILED.md (null until compiled)",
-  "compiled_at": "ISO timestamp or null",
-  "orc_version": "installed orc payload version at compile time, or null"
-}
-```
-
-Gate status (computed by `orc diy status`, consumed by the stub skill and
-`orc doctor`; the effort guard does NOT read it — it keys on `flow.lock.json` +
-`session_tier` directly, and the statusline reads the lock, not this verb):
-
-**The exit code IS the contract** (v0.34.7), same convention as the sibling
-`orc pattern status <lang>` in `_shared/detecting-artifacts.md`:
-
-| Exit | State | Meaning |
-|---|---|---|
-| 0 | READY | everything matches; `/orc-diy` may run the compiled flow |
-| 1 | STALE | see the triggers below — the flow must be recompiled first |
-| 1 | UNCONFIGURED | no config file (or empty) |
-
-It used to exit 0 in all three states, so anything branching on it treated a
-hard-blocked flow as runnable — the direct inverse of its own sibling.
-
-STALE triggers (**all live ones are reported, joined by `;`** — not just the
-first): no lock / never compiled / `config_hash` mismatch (config changed since
-compile) / `orc_version` mismatch (orc was updated) / compiled file missing or
-`compiled_hash` mismatch (artifact modified). Reporting only the first meant a
-flow stale ONLY because `orc update` bumped the payload said "config changed",
-which contradicts a user who knows they never touched their config.
+# ORC-DIY — Flow config schema
+
+The single source of intent is `.claude/orc-diy.config.yaml`, written ONLY by
+the `orc diy` CLI (never by hand, never in a Claude session). Every write
+regenerates `.claude/orc/diy/flow.md` (the human-readable spec) and updates
+`.claude/orc/diy/flow.lock.json`, invalidating any previous compile.
+
+**Project-scoped only.** The config, lock, and compiled flow live in the
+project's `.claude/` — there is no global variant; `orc diy` rejects
+`--global`. One flow per project; `flow_name` is a display label, never a
+selector.
+
+## Keys (all set via `orc diy set <key> <value>`)
+
+| Key | Values (default first) | Meaning |
+|---|---|---|
+| `analyze` | `auto` / `off` / `mini` / `full` | Doc-intake analyst routing |
+| `planning` | `auto` / `own-planner` / `superpowers` / `openspec` | Planning route |
+| `pattern` | `ask` / `off` / `on` | Code-pattern gate on a cache miss |
+| `scoring` | `on` / `off` | Rubric scoring; `off` needs `fixed_executor` |
+| `fixed_executor` | (none) — an executor agent name | Used for every task when `scoring: off` |
+| `extra` | `off` / `on` | May this flow dispatch an executor to a non-Claude worker (`_shared/extra-dispatch.md`)? It decides WHETHER; `orc extra resolve` still decides WHERE, per task, at run time — route rows are NOT baked into the compiled flow, because the lock's staleness triggers cannot see the ledger change. `off` makes a globally-enabled Extra **INERT here**, announced once, so turning it on globally never silently changes a compiled flow |
+| `review` | `on` / `off` / `blocking-only` | Review phase strictness |
+| `security` | `off` / `ask` / `on` / `always` | Security pass; `always` drops the risk-floor trigger |
+| `verify` | `full` / `off` / `smoke` | Verify depth |
+| `testgen` | `off` / `ask` / `on` | Test-authoring phase |
+| `mock_example` | `ask` / `on` / `off` | Post-verify mocked example + drift recovery (`mock-examples/<slug>/`, never committed) |
+| `tdd` | `on` / `off` | TDD-anchored planning: plan-time `tdd_spec` (scoped by `disposition`), paired TDD tasks for the red proof, TDD gate in the verify slot |
+| `gotchas` | `on` / `off` | Repair memory: inject scope-matching gotchas into slices, record one when a repair loop goes red → green (`_shared/gotchas.md`) |
+| `code_graph` | `on` (default) / `off` | Code-graph cache steps: `orc graph status --heal` at preflight, `orc graph ctx` cards in slices, `orc graph map` then `orc graph impact` + `orc graph cochange` at planning, `orc graph changes` at review, `orc graph coverage` on demand, `orc graph update` after every wave and at ship, one `orc graph notes` batch per wave when notes are on. `on` compiles them in and the global `code_graph` key decides at run time (every call carries `--if-enabled`); `off` removes them (`_shared/code-graph.md`) |
+| `wiki_gate` | `notice` / `off` / `hard` | Wiki freshness handling at preflight |
+| `post_ship_wiki_ask` | `on` / `off` | Post-ship wiki refresh offer on big runs |
+| `summary` | `full` / `off` / `short` | Summary depth |
+| `autonomy` | `interactive` / `semi` / `hands-off` | Who answers routine asks |
+| `ship_mode` | `ask` / `commit` / `pr` / `report-only` | Terminal ship behavior |
+| `session_tier` | `sonnet-4-6-{med,high}` / `opus-4-7-{med,high}` / `opus-4-8-{med,high,xhigh,max}` / `opus-5-{med,high,xhigh,max}` / `fable-5-{med,high,xhigh,max}` | Required main-session model+effort (default `opus-5-high`) |
+| `max_wave_tasks` | `3` (integer ≥ 1) | Wave hard cap |
+| `batch_pause_every` | `2` (integer ≥ 1) | Waves between pauses |
+| `rubric_bands` | `5` (2–8) | Scoring granularity (`scoring: on` only) |
+| `flow_name` | `my-flow` (slug) | Display label for traces/statusline |
+
+## Cross-key validation (CLI `orc diy validate`; also runs on every write)
+
+Hard errors (config not written):
+- `scoring: off` without a `fixed_executor`.
+- `fixed_executor` or any agent choice above `session_tier` (tier order:
+  haiku-4-5 < sonnet-4-6 < sonnet-5 < opus-4-7 < opus-4-8 < opus-5 < fable-5 —
+  subagents cannot exceed the main session; effort medium < high < xhigh < max).
+  A tier below `opus-5-high` clips the `[90,100]` band to the highest agent it
+  allows, at compile time.
+- `review: off` with `security` not `off` (the security pass reuses the
+  reviewer).
+- Anything that would disable a locked rule (see `locked-blocks.md`).
+
+Warnings (written, reported):
+- `scoring: off` with `rubric_bands` overridden (ignored).
+- `testgen` on/ask with `verify: off` (testgen normally follows verify).
+- `tdd: on` with `verify: off` (the TDD gate runs in the verify slot; plan-time
+  tests are authored but never gate the ship).
+- `autonomy: hands-off` with `ship_mode: commit` or `pr` (fully unattended
+  git actions).
+- `session_tier` below `opus-5-med` with `review`/`verify` on: the pinned
+  Opus 5 reviewer/verifier agents will silently run at the session's model —
+  the flow still works, honesty-checked by the tier-honesty locked rule.
+
+## `flow.lock.json` (machine state — written by the CLI only)
+
+```json
+{
+  "flow_name": "my-flow",
+  "session_tier": "opus-5-high",
+  "config_hash": "sha256 of orc-diy.config.yaml",
+  "flow_hash": "sha256 of flow.md",
+  "compiled_hash": "sha256 of FLOW-COMPILED.md (null until compiled)",
+  "compiled_at": "ISO timestamp or null",
+  "orc_version": "installed orc payload version at compile time, or null"
+}
+```
+
+Gate status (computed by `orc diy status`, consumed by the stub skill and
+`orc doctor`; the effort guard does NOT read it — it keys on `flow.lock.json` +
+`session_tier` directly, and the statusline reads the lock, not this verb):
+
+**The exit code IS the contract** (v0.34.7), same convention as the sibling
+`orc pattern status <lang>` in `_shared/detecting-artifacts.md`:
+
+| Exit | State | Meaning |
+|---|---|---|
+| 0 | READY | everything matches; `/orc-diy` may run the compiled flow |
+| 1 | STALE | see the triggers below — the flow must be recompiled first |
+| 1 | UNCONFIGURED | no config file (or empty) |
+
+It used to exit 0 in all three states, so anything branching on it treated a
+hard-blocked flow as runnable — the direct inverse of its own sibling.
+
+STALE triggers (**all live ones are reported, joined by `;`** — not just the
+first): no lock / never compiled / `config_hash` mismatch (config changed since
+compile) / `orc_version` mismatch (orc was updated) / compiled file missing or
+`compiled_hash` mismatch (artifact modified). Reporting only the first meant a
+flow stale ONLY because `orc update` bumped the payload said "config changed",
+which contradicts a user who knows they never touched their config.