@azure-id/orc 0.55.0

package/templates/skills/orc/subskills/orc-planner-mini/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: orc-planner-mini
+description: >
+  Fast-lane Requirement Planner for ORC-MINI (Sonnet 5, high effort). Turns a
+  detailed request OR a System Analyst requirement-spec into orc's
+  planning-output: right-sized tasks, each with grounded declared_files (incl.
+  tests), explicit depends_on, owns_area, and spec_ref — self-checked for
+  dependency cycles, same-file collisions, and requirement coverage. Use when
+  orc-mini needs a fast plan for a well-scoped request — fires on "plan this
+  quickly", "fast task breakdown", "break this into tasks", or after mini doc
+  analysis. Distinct from the full orc-planner (Opus 5 medium — pick that one
+  when the dependency graph is genuinely complex: >8 tasks, deep chains, or
+  many same-file serializations): single-pass, lighter grounding, deep
+  dependency tracing trimmed. The orchestrator dispatches this to a subagent —
+  it never plans itself.
+---
+
+# orc-planner-mini
+
+Fast variant of the Requirement Planner, dispatched by orc-mini as a Sonnet 5
+high subagent. Produces the SAME artifact (orc's `schemas/planning-output.md`)
+and follows the SAME input + grounding + branch rules as `../orc-planner/`, which
+is AUTHORITATIVE for the full procedure; the summary below orients.
+
+## Procedure (summary)
+
+1. **Accept** a detailed request OR an analyst requirement-spec. "Too thin to
+   plan" is defined, not felt: plannable ⇔ the request states (a) an observable
+   outcome AND (b) an identifiable repo area it lands in — failing either, do
+   NOT plan; recommend `orc-analyze-mini` (requirement mode) instead.
+2. **Ground** `declared_files[]` in real paths: standalone → read the repo (+ a
+   non-empty `wiki/` — select via `wiki/INDEX.md` keywords; pull `Contracts &
+   shapes` + `Testing map` from the matching docs; code outranks any wiki
+   claim); from-SA → trust the spec's file map, no repo re-read —
+   but NEW paths beyond the spec (tests, new modules) still get their own
+   parent-dir Glob. Fill each task's `grounding[]` attestation (`{path,
+   disposition: exists|new, evidence}`) — never mark `exists` on a path you
+   didn't confirm; the orchestrator Globs every `exists` path and bounces
+   misses back (one retry).
+3. **Draft** right-sized tasks — anchors, not adjectives: normally **1–5
+   declared files, one `owns_area`** per task; >7 files or two unrelated areas
+   → split; ≤~10-line dependency-bound change → merge; deviation needs a
+   one-line reason. Each task carries `depends_on`, `owns_area`, `spec_ref`,
+   `requirements[]` (the R#/DoD ids it implements — `[]` only for pure-infra
+   with a stated reason), `spec_invariants[]` (load-bearing Context & invariants
+   lines copied verbatim — the orchestrator appends them to the executor
+   slice's constraints[]), a `facets` block (breadth = `len(declared_files)`,
+   novelty/logic/test_surface/uncertainty, cited `risk[]` — the orchestrator
+   scores from these; you never compute the score), and a sliced `acceptance[]`
+   where each line cites its source (`R3` / `DoD#2` — a line with no source is
+   invented). **When the caller's slice says `tdd: on`** (orc-mini asked its
+   one intake question and the user said yes), also author each requirement's
+   `tdd_spec` entry — given/when/then + a runnable skeleton in the project's
+   test framework, or `tdd: exempt — <reason>` (schema: planning-output.md).
+4. **Self-check (always — cheap, prevents broken waves):**
+   - **cycle detection** — no `depends_on` chain loops back on itself;
+   - **same-file collision** — two tasks sharing a `declared_files` entry must be
+     merged, or serialized with a dependency;
+   - **coverage** — every in-scope R# / DoD line appears in ≥1 task's
+     `requirements[]`; an orphan requirement is a MALFORMED plan.
+   On a failed check, FIX the plan (merge/split/add-dep/add-task) before
+   presenting — never emit a plan with a cycle, an unserialized collision, or
+   an orphan. The orchestrator recomputes all three at Phase 1 exit and
+   bounces failures (one retry). Deep dependency tracing is trimmed here.
+5. **Ask clearly; step back when unclear:** set `plan_confidence: high|medium|low`
+   (+ reason) and turn every ambiguity into an `open_questions[]` entry
+   (`{question, proposed_default, blocking}`) — never silently pick a reading.
+   `plan_confidence: low` OR >3 blocking questions → recommend stepping back to
+   `orc-analyze-mini` (the user may override).
+6. **Present** the plan once → approve/edit (breakdown/approach only).
+7. **Branch** → take into build (hand back to orc-mini) or save & stop — checkpoint
+   FIRST either way (never a loose plan file with no checkpoint).
+
+## What's trimmed vs the full planner
+
+- **Lighter grounding:** confirms the main file paths rather than exhaustively
+  tracing every reference (standalone case). From-SA case is identical — trust
+  the spec, no repo re-read (new paths still grounded).
+- **Lighter self-check:** cycle + same-file-collision + coverage checks always
+  run (they're cheap and prevent broken waves); deep dependency tracing is
+  trimmed.
+- **Concrete escalation thresholds** (suggest the full `../orc-planner/`, Opus
+  4.8 medium, and let the user choose — not self-assessed vibes): >8 tasks, OR
+  any dependency chain 3+ deep, OR >2 same-file serializations needed.
+- **Model:** Sonnet 5, high effort.
+
+## Checkpoint + hand-back (same as full)
+
+Checkpoint the plan into `orc/planner/{name}/` before branching (never a loose
+file with no checkpoint). On "take into build", hand back to the orchestrator,
+which runs the full Phase 2–8 (scoring, effort table, wave cap, pauses). The
+mini planner never builds directly.
+
+## Identical
+
+- Accepts detailed request OR analyst requirement-spec; refuses requests below
+  the plannable floor.
+- Grounding provenance recorded only when standalone.
+- Show plan once → approve/edit (breakdown/approach only) → branch
+  (take into build / save plan-{name}.md and stop).
+- Plain-language handoffs, dispatched not self-run.
+
+## Return contract (inlined — do not reconstruct from the full planner)
+
+Produce `../orc-planner/`'s artifact — orc's `schemas/planning-output.md`: every
+task with `declared_files` (incl. tests), `grounding[]` (per-file
+exists|new attestation with evidence), `acceptance[]` (sliced, source-cited
+definition-of-done lines), `requirements[]`, `spec_invariants[]`, `facets`
+(breadth/novelty/logic/test_surface/uncertainty + cited `risk[]`), `depends_on`,
+`owns_area`, `spec_ref`; and at the top level `plan_head`, `plan_confidence`, and
+`open_questions[]`. Checkpoint it into `orc/planner/{name}/` before branching.
+Return exactly:
+
+- the `planning-output` (the plan itself) + a plain-language `summary`.
+- `coverage: {requirements: N, tasks: M, orphans: []}` — self-attested; the
+  orchestrator recomputes it and bounces orphans.
+- `actual_model` — quoted verbatim from your system prompt's "The exact model ID
+  is …" line (`unknown` if absent, never guessed).
+- `actual_effort` — `$CLAUDE_EFFORT`.
+
+Never build or spawn.

package/templates/skills/orc/subskills/orc-pr/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: orc-pr
+description: >
+  Ship-phase subskill for ORC Phase 8. Handles commit, push, and PR
+  file generation from the team's template (pr.md in this folder). Coordination
+  skill: always runs inline. Not for direct user invocation.
+---
+
+# orc-pr
+
+## Input slice
+
+- ticket, pr_title, target_branch  — asked together by the orchestrator
+- changed_files[] / commit_range
+- template_ref = subskills/orc-pr/pr.md  — the team's PR template (user-provided)
+- build_green: bool — MUST be true; refuse commit otherwise (hard rule 8)
+- stacked_pr, stacked_pr_loc, stacked_pr_files, stacked_pr_max_layers — the
+  stack-gate config (`../../config.md`)
+
+## Procedure
+
+1. Gate: build_green must be true. If not, return failure — never commit red.
+2. **Stacked-PR gate (load `stack-gate.md` — full `/orc` + `/orc-ultra` only).**
+   Measure the change, compare against `stacked_pr_loc` / `stacked_pr_files`, and
+   on a tripped threshold ask the ONE P0 question. "Yes" (with a ticket AND a
+   resolved PR template) → write `stacked-pr/<slug>/STACK-FROM.md` and hand off to
+   `/orc-pr-setup` → `/orc-pr-driver`; anything else (under threshold, `off`,
+   declined, no ticket, no template) → continue this procedure as one regular PR.
+3. Show the current branch to the user via the orchestrator before committing.
+4. Commit (message referencing the ticket) → push → generate the PR file:
+   - Read pr.md as the template. Fill its sections from the run: intent-spec
+     scope, task summary, test results, verify outcome.
+   - Filename: run/{ticket}-{sanitized-title}.md
+     (lowercase, spaces→hyphens, strip anything unsafe for filenames)
+5. PR targets `target_branch` as base.
+
+## Return contract
+
+- { pr_file_path, commit_result, push_result, pr_result }
+- `stack_gate`: { tripped: bool, loc, files, decision: `under-threshold` | `off` |
+  `declined` | `no-ticket` | `no-template` | `handoff`, slug } — always present in
+  full `/orc` / `/orc-ultra`; `handoff` means no PR was created here.
+- failure_reason on any failed step (the why). Malformed = failure to caller.
+
+## Template
+
+The file `pr.md` in this folder is the team's default PR template. Replace the
+placeholder with your real template — the skill reads whatever is there. Template
+resolution when it is still the placeholder (project `.github/`, `docs/`,
+`CLAUDE.md`, or three recommended options) is
+`../../../_shared/pr-templates.md` — shared with the stacked-PR lanes.

package/templates/skills/orc/subskills/orc-pr/pr.md

@@ -0,0 +1,22 @@
+<!--
+PLACEHOLDER — replace this entire file with your team's real PR template (md).
+orc-pr reads this file as the template for every generated PR description.
+The structure below is only a fallback so the skill works before you paste yours.
+-->
+
+# {pr_title}
+
+**Ticket:** {ticket}
+**Target:** {target_branch}
+
+## What changed
+{summary of tasks completed, from the run}
+
+## Why
+{scope-in from the intent-spec}
+
+## Testing
+{tests added/updated, verify result}
+
+## Notes
+{P2/P3 findings left unfixed, stale_review flags, anything reviewers should know}

package/templates/skills/orc/subskills/orc-pr/stack-gate.md

@@ -0,0 +1,108 @@
+# Ship-phase STACKED-PR gate (Phase 8, deterministic)
+
+Loaded by `orc-pr` at Phase 8, before the commit/push/PR question. Turns "this
+change is too big for one PR" from a judgment call into a measured gate with ONE
+P0 question.
+
+Scope: full `/orc` and `/orc-ultra` only — **never in orc-mini**, orc-fast (the
+fast lane never stops the chat) or orc-diy (flow shape is compile-owned).
+
+## Step 1 — measure the change (never estimate)
+
+```bash
+git diff --numstat            # unstaged
+git diff --numstat --cached   # staged
+git status --short            # untracked adds
+```
+
+`LoC = additions + deletions` and `files = count`, both **after** removing the
+exclusion list in `../../../_shared/stack-plan.md` (generated code, lockfiles,
+`vendor/`, `node_modules/`, `testdata/`, pure renames). Excluded paths are kept as
+a LISTED bucket, never silently dropped. `test-generator/` deliverables count;
+`mock-examples/` is never staged, so it never counts.
+
+## Step 2 — the threshold (config, not vibes)
+
+Read from `../../config.md` (← `.claude/orc.config.yaml`):
+
+| Key | Default | Meaning here |
+|---|---|---|
+| `stacked_pr` | `ask` | `ask` = P0 question when the threshold trips · `on` = go straight into the stack flow · `off` = never offer, regular PR |
+| `stacked_pr_loc` | 1000 | change LoC **≥ this** → stack candidate (also the per-layer LoC ceiling) |
+| `stacked_pr_files` | 20 | changed files **≥ this** → stack candidate (also the per-layer file ceiling) |
+| `stacked_pr_max_layers` | 6 | soft layer cap the planner honors |
+
+**Trigger = `LoC >= stacked_pr_loc` OR `files >= stacked_pr_files`.** One number
+does both jobs on purpose: a change that cannot fit inside ONE layer's budget is
+exactly the change worth stacking.
+
+Below the threshold, or `stacked_pr: off` → **no question, no mention**: continue
+the normal ship flow. Emit `GATE stack-gate pass :: under-threshold loc=<n>
+files=<n>` and move on. Above it, print the one-line report either way:
+
+```
+STACK GATE — <n> LoC · <n> files (excluded: <n> files) → threshold <loc>/<files> TRIPPED
+```
+
+## Step 3 — prerequisites (both required, asked in the SAME round as the P0)
+
+1. **Ticket number.** Required — layer branch names and titles derive from it.
+   Ask once. No ticket → skip stacking, ship one regular PR.
+2. **PR template.** Resolve per `../../../_shared/pr-templates.md`: the ORC
+   template (`pr.md`, only if the team replaced the placeholder) → a project
+   template (`.github/`, `docs/`) → a PR-template section in `CLAUDE.md` → else
+   RECOMMEND three options (`minimal`, `context-first`, `risk-and-rollback`) and
+   let the user pick or paste their own. **Declining every option → skip
+   stacking, ship one regular PR** and say so in one line.
+
+Neither prerequisite is silently defaulted, and neither is a build failure — both
+degrade to a regular PR.
+
+## Step 4 — the P0 question (one question, both answers legitimate)
+
+With the threshold tripped and both prerequisites satisfied, ask ONE question
+(`stacked_pr: on` skips the asking and takes "yes"):
+
+```
+This change is <n> LoC across <n> files — above the one-PR budget
+(<stacked_pr_loc> LoC / <stacked_pr_files> files).
+
+Stack it into reviewable layers?
+  [yes] plan the layers (/orc-pr-setup) → build + submit them (/orc-pr-driver).
+        <n> layers means <n> full CI runs; each layer is reviewable on its own.
+  [no]  push one regular PR as usual.        ← no penalty, no re-ask
+```
+
+"No" → continue the normal ship flow, and never re-ask this run. Emit
+`GATE stack-gate pass :: declined`.
+
+## Step 5 — handoff (never inline)
+
+The ship phase does NOT plan or cut layers itself. It hands off:
+
+1. Verify the build is green (`build_green` — hard rule 10: never stack a red
+   build; a red build ends the gate).
+2. Commit the run's work as usual **on the current feature branch** — the
+   snapshot the driver splits from (`orc-pr-driver/references/orc-run-split.md`).
+   Do not push it as a PR yet.
+3. Write `stacked-pr/<slug>/STACK-FROM.md` per `../../../_shared/stack-plan.md`
+   with `STACK-FROM: orc-ship`, the ticket, `ENTRY-MODE: orc-run`, the resolved
+   `PR-TEMPLATE`, the measured `SURFACE`, this run's `RUN-DIR` (the driver reads
+   the task graph, `declared_files` and verify evidence from it) and
+   `BUILD-GREEN: true`.
+4. Tell the user, in this order: run **`/orc-pr-setup`** (plans the layers, asks
+   on every uncertain seam, writes `stacked-pr/<slug>/stack-plan.md`), then
+   **`/orc-pr-driver`** (branches, per-layer green gate, `gh stack submit`).
+   A user who already has a filled plan can go straight to `/orc-pr-driver`.
+5. Emit `GATE stack-gate pass :: handoff ticket=<T> slug=<slug>` and finish the
+   ship phase normally (usage report, wiki stale-flag, `FINISH`) — the stack
+   itself completes in the two standalone lanes.
+
+## Boundaries
+
+- The gate **measures and asks**; it never plans layers, never creates a branch
+  per layer, never runs `gh stack`.
+- Missing `gh`/`gh-stack`, or a fork, is not this gate's problem to solve — the
+  lanes preflight it (`../../../_shared/gh-stack-commands.md`) and fall back to a
+  regular PR.
+- One question per run. A declined stack is never re-offered.

package/templates/skills/orc/subskills/orc-review-verify/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: orc-review-verify
+description: >
+  Review/verify worker for ORC Phases 5–6 (Opus 5 medium). Two modes: a REVIEW
+  pass — examine the changed files against the code pattern + constraints,
+  create/update tests, and classify EVERY finding on the P0–P3 severity
+  ladder (P0/P1 gate ship, P2/P3 advisory); a VERIFY
+  pass — run the build + full test suite and check each intent-spec
+  definition-of-done criterion PLUS the pattern's enforceable validation-gate
+  lines, reporting pass/fail; or an opt-in SECURITY pass — sweep the changed
+  files against a supplied OWASP/STRIDE checklist. Returns findings[] with
+  severity, a tests tally, and a verify result — it reports; the orchestrator
+  owns the auto-fix-once loop. Dispatched in-pipeline after execution; distinct
+  from the standalone /orc-verify (which checks only git-modified changes with no
+  orchestrator). ALWAYS a spawned subagent — not for direct user invocation.
+---
+
+# orc-review-verify
+
+One entry point: spawned via the Task tool with `subagent.md` framing + the
+slice, which points to `core.md`. `core.md` is the AUTHORITATIVE spec (full input
+slice, both procedures, return contract); the summary below orients — on any
+conflict, `core.md` wins.
+
+## What the worker does (summary)
+
+- **phase=review:** examine `changed_files[]` against `code_pattern` + `constraints[]`;
+  create/update tests for the changed surface; independently re-check each
+  `invariants[]` rule AND each enforceable `validation_gate[]` line against the
+  diff (a violation is P0), plus any `fe_rules[]` pack rules on FE diffs
+  (file:line findings, P1–P3 by impact, never auto-P0); classify EVERY
+  finding on the ladder — **P0** (failing tests/build, unmet acceptance
+  criteria, runtime errors, invariant violations — caller auto-fixes, no ask),
+  **P1** (correctness/security risk, constraint violations — caller asks the
+  user before fixing), **P2** (maintainability — advisory fix-batch offer),
+  **P3** (cosmetic — advisory, counted). Never fix P2/P3; P0/P1 fixes are the
+  caller's call. **Evidence-or-advisory:** every P0–P2 finding carries
+  `file:line` + the offending line(s) quoted VERBATIM; an unanchored finding is
+  AUTO-P3 (never gates, never triggers a fix) — the caller spot-checks quotes
+  before acting on P0/P1.
+- **phase=verify (two halves, v0.33.0):** FIRST the **TDD gate** — run the
+  plan's TDD suite (`tdd_suite[]` in the slice) plus the build + full test
+  suite; green is the definition-of-done for non-exempt requirements, and each
+  red TDD test is a P0 tied to its requirement (the caller owns the
+  `tdd_loop_max` repair loop). THEN the **adversarial review** — attack the
+  green implementation: edge cases the spec missed, error paths, contract
+  violations, race/ordering, workflow breaks (dead wiring, broken commands) —
+  findings on the same P0–P3 ladder. Also fold the enforceable
+  `validation_gate[]` lines into the criteria set, then check EACH criterion
+  individually (pass/fail, nothing invented; an unmet gate line = unmet
+  criterion = P0), each with per-criterion `evidence` (the test/output line or
+  file:line that proves it); report failures precisely. You don't fix — the
+  caller owns the auto-fix-once loop.
+- **phase=security (opt-in):** sweep only `changed_files[]` against the supplied
+  `security_checklist[]` (wrap Semgrep if installed, never install it); findings
+  on the same ladder (exploitable-in-diff = P0, hardening gap = P1,
+  defense-in-depth = P2/P3). Report-only, no `result` verdict.
+
+## Return shape (summary — full contract in `core.md`)
+
+`{ phase, findings[]{severity: P0|P1|P2|P3, location "file:line", quote (verbatim,
+required P0–P2; unanchored ⇒ AUTO-P3), description, criterion},
+criteria[] (verify only){criterion, result, evidence}, tests{added,updated,passing},
+result (verify only): passed|failed, actual_model, actual_effort, failure_reason }`
+
+**Validation checkpoint before returning:** every finding carries a `severity`
+from the P0–P3 ladder; every P0–P2 finding carries `file:line` + a VERBATIM
+`quote` (else downgrade it to P3 yourself);
+verify sets `result` + per-criterion `evidence`; `actual_model` is quoted
+VERBATIM (never inferred). A
+malformed return is treated as failure by the caller.
+
+Fixed models (from `../../references/effort-and-mode.md`): review on the OpenSpec/self
+path = Opus 5 medium; review on the Superpowers path is delegated to the
+Superpowers review skill instead (Sonnet 4.6 medium). Verify = Opus 5 medium,
+always this subskill.

package/templates/skills/orc/subskills/orc-review-verify/core.md

@@ -0,0 +1,135 @@
+# orc-review-verify — Core (mode-neutral)
+
+## Input slice
+
+- phase: review | verify | security
+- acceptance_criteria[]   — the intent-spec's definition-of-done, verbatim
+                            (verify checks EXACTLY these; nothing invented)
+- code_pattern            — resolved/user-provided style guide, or null (review bare)
+- invariants[]            — BLOCKING code-pattern rules to re-check, or empty
+                            (a violation is a P0 finding)
+- validation_gate[]       — the pattern's enforceable acceptance checks (already
+                            measurability-filtered at reconciliation), or empty.
+                            Verify treats each line as an acceptance criterion;
+                            review re-checks them against the diff.
+- fe_rules[]              — impact-ordered FE rule-pack rules (a11y/perf) when the
+                            diff touches FE files, else empty. Findings from these
+                            are P1–P3 by impact (never automatic P0), always with
+                            file:line.
+- security_checklist[]    — OWASP/STRIDE checklist items (phase=security only),
+                            else empty
+- tdd_suite[]             — (phase=verify, v0.33.0) the plan's materialized TDD
+                            acceptance tests: {requirement, test_path} per
+                            non-exempt requirement, plus the run's exemptions
+                            (`tdd: exempt — <reason>` lines). Empty on a
+                            whole-run exemption or a pre-v0.33.0 plan.
+- gotchas[]               — 0–3 repair-memory entries whose `scope` glob matches
+                            `changed_files`, or empty. A CHECKLIST, not a rule
+                            set: "has this change reintroduced a failure this
+                            project already paid for?" A confirmed hit is a
+                            normal finding, anchored and severity-classified like
+                            any other — never an automatic P0 because a gotcha
+                            named it. Empty is the normal case. Canonical:
+                            `.claude/skills/_shared/gotchas.md`.
+- changed_files[]         — the surface to examine
+- constraints[]           — intent-spec hard rules (a violation is a P1 finding)
+- model, effort           — informational
+
+## Review procedure (phase=review)
+
+1. Examine changed_files against code_pattern (if given) and constraints.
+2. Create/update test files and test cases for the changed surface.
+3. Re-check each `invariants[]` rule against the diff independently (don't trust the
+   executor's self-attestation) — any violation is a P0 finding. Re-check each
+   `validation_gate[]` line the same way — an unmet enforceable line is P0.
+4. Re-check each `fe_rules[]` rule against the FE parts of the diff; emit
+   findings with file:line, classified P1–P3 by real impact (a rule-pack hit is
+   never automatically P0 — invariants and the gate own that severity).
+5. **Evidence-or-advisory (anti-phantom rule):** every P0–P2 finding MUST carry
+   `location` as `file:line` plus `quote` — the offending line(s) copied
+   VERBATIM from the file (like `actual_model`: quoted, never reconstructed).
+   A finding you cannot anchor to a real line you read this session is
+   AUTO-P3 (advisory — it never gates ship and never triggers a fix dispatch).
+   The caller spot-checks quotes before acting on P0/P1.
+6. Classify EVERY finding on the P0–P3 ladder:
+   - P0 — objective breakage: failing tests, broken build, unmet acceptance
+     criteria, runtime errors, invariant violations. Gates ship; the caller
+     auto-fixes immediately (no ask).
+   - P1 — correctness or security risk, constraint violations (judgment-level
+     blockers that don't break the build). Gates ship; the caller asks the user
+     before fixing.
+   - P2 — maintainability: duplication, missing tests for a changed path,
+     unclear structure. Advisory; itemized in the summary as an optional fix-batch.
+   - P3 — cosmetic: naming, formatting, length, style. Advisory; counted only.
+7. Never fix P2/P3. P0/P1 fixes are the caller's decision, not yours.
+
+## Verify procedure (phase=verify — two halves, v0.33.0)
+
+**Half 1 — TDD gate (deterministic):**
+1. Run the build and full test suite — INCLUDING every `tdd_suite[]` test.
+2. Per non-exempt requirement: its TDD test green = that requirement's
+   definition-of-done met; red = a P0 finding tied to that requirement
+   (`criterion` = the requirement id). Report `tdd: {green: n, red: n,
+   exempt: n}` — the caller owns the `tdd_loop_max` repair loop; you never fix.
+   An empty `tdd_suite[]` (whole-run exemption / older plan) → skip this half
+   and SAY so in the return; never invent tests here.
+
+**Half 2 — adversarial review (attack the green implementation):**
+3. Hunt what the spec missed: edge cases (empty/zero/max inputs, unicode,
+   pagination edges), error paths (failure of each external call, partial
+   writes), contract violations (response shapes, status codes, event
+   payloads vs consumers), race/ordering hazards on shared state, and
+   workflow breaks — dead wiring (a route/handler/command nothing reaches),
+   broken commands, config keys read by nothing. Findings on the P0–P3
+   ladder with the same evidence-or-advisory rule (verbatim quote or AUTO-P3).
+
+**Criteria sweep (unchanged):**
+4. Fold every `validation_gate[]` line into the criteria set (each enforceable
+   line IS an acceptance criterion; the slice only carries enforceable ones —
+   measurability was decided at reconciliation, don't re-litigate it).
+5. Check each criterion individually — pass/fail per criterion, each with
+   `evidence`: the test name/output line that proves it, or the `file:line`
+   that satisfies it (quoted, never asserted from memory). An unmet gate
+   line is an unmet criterion (P0).
+6. Report failures precisely (which criterion, what observed). You do not fix;
+   the caller owns the auto-fix-once loop.
+
+## Security procedure (phase=security — opt-in, config `security_review`)
+
+1. Sweep ONLY `changed_files[]` against each `security_checklist[]` item
+   (OWASP/STRIDE-derived; supplied in the slice, never invented).
+2. If Semgrep is installed in the environment (`semgrep --version` succeeds),
+   run it scoped to the changed files and fold its results in; skip silently
+   otherwise — never install tooling.
+3. Findings on the same P0–P3 ladder: a directly exploitable flaw introduced by
+   the diff (injection, authz bypass, secret in code) is P0; a hardening gap or
+   risky-but-guarded path is P1; defense-in-depth suggestions are P2/P3.
+4. Report only; you never fix. Same return contract (no `result` field —
+   security is a findings pass, not a verdict).
+
+## Return contract (emit EXACTLY this)
+
+- phase
+- findings[]: { severity: P0|P1|P2|P3, location ("file:line" — REQUIRED for
+               P0–P2), quote (offending line(s) VERBATIM — REQUIRED for P0–P2;
+               missing/unanchored ⇒ the finding is AUTO-P3), description,
+               criterion|null }
+- criteria[] (verify only): { criterion, result: pass|fail, evidence — the test
+               name/output line or file:line that proves it }
+- tdd (verify only): { green: int, red: int, exempt: int } — the TDD-gate tally
+               (omit only when the slice carried no tdd_suite[])
+- tests: { added: int, updated: int, passing: "x/y" }
+- result (verify only): passed | failed
+- actual_model — the model id quoted VERBATIM from your system prompt ("The exact
+                 model ID is …"); NEVER inferred; `unknown` if absent
+- actual_effort — the value of $CLAUDE_EFFORT (read via Bash)
+- failure_reason — required if the pass itself could not run; else null
+- gotcha_recorded — REQUIRED only when a repair loop CLOSED inside this same run
+                 and you re-checked it (a P0/P1 you raised and that was fixed; a
+                 verify criterion that was unmet and is now met): the entry body
+                 {trigger, symptom, cause, fix, scope}, or `none` + a one-line
+                 reason. Not required otherwise. A finding left OPEN returns
+                 `none` — an unsolved failure is not a gotcha. You RETURN it;
+                 the caller writes the file (`_shared/return-validation.md` §7)
+
+Malformed returns are treated as failure by the caller.

package/templates/skills/orc/subskills/orc-review-verify/subagent.md

@@ -0,0 +1,7 @@
+# orc-review-verify — Subagent wrapper (orchestrator prepends at spawn)
+
+You are an isolated review/verify worker. Examine only what the slice gives
+you. You do not fix anything — you classify, test, and report. Emit the return
+structure from core.md and STOP.
+
+[Orchestrator: append the input slice here at spawn time.]

package/templates/skills/orc/subskills/orc-testgen/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: orc-testgen
+description: >
+  Worker subskill for ORC's opt-in Phase 6.5 (Test Authoring). Fires when the user
+  opts into writing tests ("write test cases", "generate tests", "author test
+  cases for these changes"). Writes test cases as a deliverable — automated test
+  files, a manual TEST-PLAN.md, and (for HTTP/API backends) a Postman-importable
+  curl bundle. It NEVER runs tests and NEVER gates the ship; the user tests
+  manually. ALWAYS invoked as a spawned subagent by the orchestrator. Not for
+  direct user invocation.
+---
+
+# orc-testgen
+
+One entry point: spawned via the Task tool with `subagent.md` framing + the
+slice, which points to `core.md` — the AUTHORITATIVE procedure + return contract;
+the summary below orients.
+
+## What the worker does (summary)
+
+1. Take the slice: changed surface (`actual_files`), the intent-spec's
+   definition-of-done (acceptance criteria), touched flows, constraints, detected stack.
+2. Write **automated test files** in the project's framework, covering the changed surface.
+3. Write a manual **TEST-PLAN.md** with two separated sections — "run the automated
+   suite" (exact CLI command) and "exercise the real running service" (manual/curl steps).
+4. For an HTTP/API backend, write a Postman-importable **test-cases.http** curl bundle
+   (env-var placeholders — never real secrets).
+5. Run NOTHING. Advisory `notes[]` may flag a case the code likely won't satisfy.
+
+The manual deliverables (TEST-PLAN.md + test-cases.http) are pinned to
+**`test-generator/<change-slug>/` at the project root** — a visible user
+deliverable, never inside `.claude/` or the run folder (see `core.md`).
+
+**Validation checkpoint before returning:** confirm each promised deliverable
+actually exists on disk **at the pinned path** (test files in the project's
+conventions; TEST-PLAN.md and — when the stack exposes HTTP — test-cases.http
+under `test-generator/<change-slug>/`) before emitting the return contract in `core.md`.
+
+Fixed model: `orc-test-author-opus-5-med` (Opus 5 medium — authoring good
+integration tests is a judgment task). Opt-in: the orchestrator dispatches this
+only when the user accepts the offer, defaulted from `config.generate_tests`. The
+full lane runs it as Phase 6.5 (after Verify, confirmed at intake); **orc-mini
+also offers it** as an end-of-run ask (only on a GREEN smoke gate). Either lane,
+it never runs tests and never gates the ship. orc-mini still skips full
+review/verify.

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

@@ -0,0 +1,59 @@
+# orc-testgen — Core (mode-neutral)
+
+A procedure specification: inputs, steps, outputs. Executed by a spawned
+`orc-test-author-opus-5-med` subagent; the orchestrator never runs this
+itself. **Authoring only — RUN NOTHING, GATE NOTHING.** The user tests manually.
+
+## Input slice (you receive exactly this)
+
+- changed_files[]        — the surface the change touched (from the run's actual_files)
+- acceptance_criteria[]  — the intent-spec's definition-of-done (the "new behaviour")
+- touched_flows[]        — user journeys through the changed code (may be empty)
+- constraints[]          — intent-spec hard rules
+- stack                  — {language, test_framework, is_http_api}; detect if absent
+- test_types[]           — subset of {new_behaviour, flow, change, regression}; default all
+- output_conventions     — where tests live in this repo
+
+## Procedure
+
+1. Detect stack: test framework + conventions, and whether the project exposes
+   HTTP endpoints (→ `is_http_api`).
+2. Derive a **test matrix** from changed_files + acceptance_criteria + flows —
+   one row per case {id, type, target, asserts, external_deps}. Bound regression
+   to the diff's blast radius; never test the whole app.
+3. Author **automated test files** in the project's framework/conventions where
+   feasible. Match existing test style. These stay in the project's own test
+   conventions (`output_conventions`) — do NOT move them.
+4. **Pin the manual-QA output folder.** The two manual deliverables below are
+   USER deliverables, not run state — write BOTH to
+   **`test-generator/<change-slug>/` at the PROJECT ROOT** (create the folder if
+   absent). `<change-slug>` = the run's existing kebab-case run-folder slug (e.g.
+   `post-users`). NEVER write them inside `.claude/`, and NEVER inside the run
+   folder — a hidden path is invisible for self-QA.
+5. Write **`test-generator/<change-slug>/TEST-PLAN.md`** (manual cases: scenario,
+   setup, steps, expected) with two CLEARLY SEPARATED sections:
+   - "Run the automated test suite" — the exact CLI command(s), pasted.
+   - "Exercise the real running service" — manual steps / curl.
+6. If `is_http_api`: write **`test-generator/<change-slug>/test-cases.http`** —
+   one Postman-importable `curl` per endpoint/flow (env-var placeholders for base
+   URL + auth; NEVER real secrets). Reference it from TEST-PLAN.md.
+7. Advisory only: note (do not gate) any case the code likely won't satisfy.
+
+## Return contract (emit EXACTLY this; the caller validates)
+
+- test_matrix[]         — the rows above (or counts by type)
+- files_authored[]      — automated test files created/updated
+- test_plan_path        — path to TEST-PLAN.md; MUST be inside
+                          `test-generator/<change-slug>/` (any other location is
+                          a malformed return)
+- curl_bundle_path      — path to test-cases.http (also inside
+                          `test-generator/<change-slug>/`), or null (non-API projects)
+- run_command           — exact CLI command(s) to run the authored tests
+- notes[]               — advisory gaps noticed while authoring (non-blocking); else []
+- actual_model          — model id quoted VERBATIM from your system prompt ("The
+                          exact model ID is …"); NEVER inferred; `unknown` if absent
+- actual_effort         — the value of $CLAUDE_EFFORT (read via Bash)
+- failure_reason        — required if you could not author; else null
+
+Malformed returns are treated as failure by the caller. Never run tests; never
+spawn subagents.

package/templates/skills/orc/subskills/orc-testgen/subagent.md

@@ -0,0 +1,7 @@
+# orc-testgen — Subagent wrapper (orchestrator prepends at spawn)
+
+You are an isolated test-authoring worker. You WRITE test cases from the slice
+below; you never run them, never fix code, never gate the ship. Make manual
+testing easy for the user. Emit the return structure from core.md and STOP.
+
+[Orchestrator: append the input slice here at spawn time.]