@azure-id/orc 0.55.0

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

@@ -0,0 +1,184 @@
+---
+name: orc-pr-setup
+description: >
+  Stacked-PR PLANNER. Use for "/orc-pr-setup", "plan the stacked PRs", "split
+  this change into stacked pull requests", "where do the PR cut lines go".
+  Decides the LAYERING of a big change — ordered layers, each with a purpose, a
+  value class, an explicit file list, a measured LoC/file budget and a
+  dependency reason — and writes stacked-pr/<slug>/stack-plan.md. Runs
+  INDEPENDENTLY (no orchestrator needed) and is also the lane ORC's ship phase
+  hands off to when a change is too big for one PR. It NEVER touches git
+  history: no branches, no commits, no pushes — that is orc-pr-driver's job.
+  P0 HARD GATE: when a boundary is uncertain it STOPS and asks, one decision at
+  a time, and records the answer.
+---
+
+# ORC-PR-SETUP (stacked-PR planner)
+
+Big PRs are not reviewed, they are rubber-stamped. A 3k-LoC / 40-file diff is
+unreviewable, so review is weak, merges are big-bang, and reverts are painful.
+GitHub's **stacked pull requests** fix the mechanics — an ordered chain of PRs in
+one repo, each targeting the branch below it, each reviewable on its own.
+
+The mechanics are the easy half. **The hard part is deciding where the cut lines
+go**, and that is this skill's entire job: decide the layering correctly, prove
+each layer stands alone, and **refuse to guess**.
+
+This lane **plans only**. It writes one markdown file and stops. Every branch,
+commit, push and merge belongs to `/orc-pr-driver`.
+
+**Tier.** Not effort-gated (the effort guard matches the exact skill name `orc`),
+so it runs at whatever tier the chat is on. Layering judgment is better at Opus
+high; it is correct at any tier.
+
+**Human guide:** this skill's own `README.md` (what a stack is, the whole
+workflow, the plan file field by field, FAQ) — point the USER there when they ask
+how any of this works; never load it to drive the run.
+
+**Load at their phase, never preloaded:**
+`../_shared/gh-stack-commands.md` (preflight + command surface) ·
+`../_shared/stack-plan.md` (plan location, schema, budget math, `STACK-FROM`) ·
+`../_shared/pr-templates.md` (template resolution) ·
+`references/layer-taxonomy.md` (where the cut lines go) ·
+`references/certainty-gate.md` (the P0 gate + red flags).
+
+## Hard rules
+
+1. **Never touches git history.** No branch, no commit, no push, no PR. Reads
+   git (`diff --numstat`, `status`, `log`) only.
+2. **P0 HARD GATE — uncertainty ASKS.** Every candidate boundary is classified
+   CERTAIN or UNCERTAIN (`references/certainty-gate.md`). Every UNCERTAIN stops
+   the lane and asks the user, **one decision at a time**, with the cost of each
+   option and a recommendation. Never a silent default, never "I assumed and
+   noted it".
+3. **Every layer needs a purpose and a value class.** No purpose → it is not a
+   layer, it is part of another one.
+4. **Budgets are measured, not estimated** (`../_shared/stack-plan.md`): real
+   `git diff --numstat` numbers, exclusions applied, ceilings from config.
+5. **Every answer is recorded** under `## Decisions` in the plan — that is the
+   audit trail and what makes the plan re-runnable after compaction.
+6. **A ticket is required.** Branch names and layer titles derive from it. No
+   ticket after asking once → stop and recommend one regular PR.
+
+## Phase S0 — Preflight (probe, never assume)
+
+Per `../_shared/gh-stack-commands.md`: `gh` present and ≥ 2.0 · authed ·
+`github/gh-stack` installed (offer the install if not) · **same repo, not a
+fork** (a fork is a hard STOP — cross-fork stacks are unsupported) · trunk name ·
+branch protections / required checks (this is where "N layers = N CI runs"
+becomes a real number) · merge queue present? Report the block in a few lines.
+
+Any hard fail → say which check failed and recommend ONE regular PR. Do not
+plan a stack that cannot be submitted.
+
+## Phase S1 — Intake (ticket, entry mode, template)
+
+1. **Ticket** — ask for it if it was not given. Required (hard rule 6).
+2. **Entry mode** (`../_shared/stack-plan.md`) — exactly two:
+   - **`greenfield`** — nothing written yet; the input is a spec / TSD / ticket.
+   - **`orc-run`** — the change already exists in the worktree (ORC built it, or
+     the user did). The split is **file-granular only**; hunk surgery is
+     forbidden.
+   Detect it: a dirty worktree with real changes → `orc-run`; a clean tree →
+   `greenfield`. Say which mode you picked. An already-open fat PR is out of
+   scope — say so and recommend one regular PR.
+3. **`STACK-FROM` handoff?** If the invocation points at a
+   `stacked-pr/<slug>/STACK-FROM.md`, read it and skip everything it carries
+   (ticket, slug, entry mode, template, surface, run dir). `BUILD-GREEN: false`
+   is a **hard stop** — never plan a stack over a red build.
+4. **PR template** — resolve per `../_shared/pr-templates.md` (ORC template →
+   project → CLAUDE.md → recommend three options). The user declining every
+   option means the **stack is skipped** — say so and stop; the change ships as
+   one regular PR.
+5. Derive `<slug>` (kebab-case, from the ticket or the change).
+
+## Phase S2 — Inventory (the real numbers)
+
+- `orc-run`: `git diff --numstat` (staged + unstaged) → every changed file with
+  its additions/deletions. Apply the exclusion list from
+  `../_shared/stack-plan.md`, keeping excluded files in a separate LISTED bucket.
+- `greenfield`: enumerate the files the change WILL touch from the spec, and
+  estimate each one's size — marked as estimates, refined by the driver.
+- Build the **dependency graph** between those files (imports/callers, schema →
+  reader, type → consumer). A `RUN-DIR` from a `STACK-FROM` handoff gives you
+  ORC's per-task `declared_files` and `depends_on` — use it; it is better
+  evidence than a fresh guess.
+- Report: total LoC, total files, excluded count, and how many layers the
+  ceilings imply.
+
+## Phase S3 — Tier-assign
+
+Map every file to a taxonomy tier per `references/layer-taxonomy.md` (framework
+tiers first — data/schema → store → domain → adapter → wiring → transport →
+async → tests-at-scale → docs/flag; generic fallback for unlisted stacks). A
+file that fits no tier is an UNCERTAIN, not a guess.
+
+## Phase S4 — Cut (the P0 gate lives here)
+
+Group tiers into layers under the config ceilings (`stacked_pr_loc`,
+`stacked_pr_files`, `stacked_pr_max_layers`). **Ordering principle: dependency
+direction = stack direction.** Layer N may depend only on layers < N; the bottom
+is the widest blast radius and the least reversible (schema), the top is the
+thinnest (docs, flag flip).
+
+At **every seam**, run the certainty classifier (`references/certainty-gate.md`).
+CERTAIN → proceed silently. UNCERTAIN → **STOP and ask**, one decision at a
+time, showing both candidate boundaries, the LoC/file/CI cost of each, the
+review-experience consequence, and a recommended option. Record the answer.
+
+Component and handler are **different layers by default** — even when both are
+small and were written in the same sitting. Same for handler vs async consumer,
+and migration vs the code that reads the new column.
+
+## Phase S5 — Validate the plan (all seven, explicitly)
+
+| # | Check | Fail → |
+|---|-------|--------|
+| 1 | every layer ≤ `stacked_pr_loc` | split, or log an accepted exception |
+| 2 | every layer ≤ `stacked_pr_files` (soft target = half) | same |
+| 3 | every layer has a purpose + value class (FOUNDATION names its consumer) | merge it into its consumer |
+| 4 | component/handler and migration/reader are separated | re-cut |
+| 5 | dependency order is acyclic and bottom-up | ask which seam breaks the cycle |
+| 6 | every layer can plausibly **build + test on its own base** | re-cut, or ask |
+| 7 | layer count ≤ `stacked_pr_max_layers` (+2 with an override, beyond → STOP) | multiple stacks or a phased release |
+
+Check 6 is REASONED here and **verified for real by the driver** — say so, never
+claim it as proven.
+
+## Phase S6 — Emit the plan, then stop
+
+Write `stacked-pr/<slug>/stack-plan.md` exactly per the schema in
+`../_shared/stack-plan.md`, including per-layer draft PR titles/bodies built from
+the resolved template, `## Decisions` (every P0 answer) and `## Accepted
+exceptions`. Then:
+
+1. Show the layer table in chat (# · branch · purpose · value · files · LoC).
+2. State plainly that **nothing has been created yet** — no branches, no PRs.
+3. Offer the handoff: write `stacked-pr/<slug>/STACK-FROM.md`
+   (`STACK-FROM: orc-pr-setup`, per `../_shared/stack-plan.md`) and tell the user
+   to run **`/orc-pr-driver`** — human approval sits exactly here, before any git
+   surgery.
+
+## Behavior trace (PERMANENT — every ORC entry point traces; always on)
+
+Resolve `log_dir` (`../orc/config.md` default ← `.claude/orc.config.yaml`) at
+start and follow `../orc/references/trace-protocol.md`: write
+`log_dir/.current` = `run-prsetup-<slug>-<DDMMYY>-<HHMMSS>.txt` and
+`touch the trace file` of that name in the SAME step, first. Narration is
+dispatched, not remembered — collect the events with their REAL timestamps
+(`PHASE S0..S6`, `GATE stack-certainty pass|bounce` per seam decision,
+`QUESTION count=<n>`, `FINISH`) plus `decisions` (the WHY: every boundary the
+user chose, verbatim), dispatch the trace writer ONCE at run end (the
+single-dispatch-lane packet), then delete `.current`. A phase ending with
+`zero new trace lines is a protocol violation`.
+
+## Boundaries
+
+- **Plans only.** Never a branch, commit, push, PR, or `gh stack` write command.
+- **Never guesses a seam.** Uncertainty is a question, not an assumption.
+- **Never fake-splits** an unsplittable atom, and never games the budget.
+- Out of scope: splitting an already-open PR (`gh stack link` retrofit), and
+  cross-repo stacks (unsupported by GitHub — use `/orc-poly` for cross-repo
+  planning).
+- Reminder: to see usage limits, tell the user to run `/usage` (never invoke it
+  programmatically).

package/templates/skills/orc-pr-setup/references/certainty-gate.md

@@ -0,0 +1,66 @@
+# Reference — the P0 certainty gate (never quietly pick a boundary)
+
+Loaded at Phase S4, at **every** seam. The rule the whole lane exists to enforce:
+**when the layering is uncertain, ASK — blocking.** A wrong seam costs re-cutting
+N branches and force-pushing N PRs; the question costs seconds.
+
+## Step 1 — classify every candidate boundary
+
+**CERTAIN (proceed, no question):**
+
+- the files sit in different taxonomy tiers **by path** (`migrations/` vs
+  `handler/` vs `repository/`);
+- file X is imported only by files in later layers (a one-way dependency you can
+  PROVE by grep, not assume);
+- migration/DDL files (always their own bottom layer);
+- a config/factory-registration-only change (always the wiring layer);
+- the layer is already within both ceilings and single-concern.
+
+**UNCERTAIN (STOP and ask):**
+
+- two files in the **same tier** that could be one layer or two (two handlers,
+  two providers, two components);
+- a shared util/helper consumed by two different layers — bottom layer, or
+  duplicate-then-dedupe?
+- a refactor/rename mixed with a behavior change in the same file;
+- a circular dependency between candidate layers (a human picks the seam);
+- splitting would leave a layer that cannot build/test alone with no obvious fix;
+- the smallest coherent unit exceeds a ceiling (an oversize atom);
+- **ordering ambiguity** — two layers with no dependency between them, where the
+  order changes what reviewers see first;
+- **feature-flag placement** — flag in the foundation layer or in the flip layer?
+- (`orc-run` mode) a single FILE whose content belongs in two layers — the
+  default option offered is "the whole file lands in the LOWEST layer that needs
+  it", because hunk surgery is forbidden.
+
+## Step 2 — ask, blocking, ONE decision at a time
+
+Use the question tool. Each question states:
+
+- the two candidate boundaries, concretely (which files land where);
+- the **cost of each**: LoC and file count per resulting layer, plus the extra CI
+  run a split adds;
+- the **review-experience consequence** ("reviewer of layer 3 sees a call to a
+  function that does not exist yet");
+- a **recommended option** — first in the list, marked as recommended.
+
+Never batch six vague questions. Never assume and note it later.
+
+## Step 3 — record every answer
+
+Append to `## Decisions` in the plan: the boundary, the options offered, the
+choice, and the rationale in the user's own words. This is the audit trail, and
+it is what lets the plan be re-run after compaction or handed to someone else.
+
+## Red flags — these thoughts mean STOP, you are rationalizing
+
+| Excuse | Reality |
+|---|---|
+| "It's obvious these two handlers go together" | Same tier ≠ same layer. That is the DEFINITION of UNCERTAIN. Ask. |
+| "I'll pick one and note the assumption in the plan" | The gate is blocking, not a footnote. Ask before cutting. |
+| "Asking is slow, the user wants speed" | A wrong seam means re-cutting N branches and force-pushing N PRs. The question costs seconds. |
+| "It's under the LoC ceiling, so the layer is fine" | The budget is a ceiling, not a definition. Mixed concerns fail at any size. |
+| "I'll put everything in layer 1 and split later" | Post-hoc splitting is hunk surgery plus N force-pushes. Cut before submitting. |
+| "Layer 2 doesn't compile alone but the stack does" | Merging layer 1 alone then breaks the trunk. Re-cut the seam. |
+| "12 layers = maximum reviewability" | 12 layers = 12 CI runs + 12 review contexts. Reviewability peaks, then collapses. |
+| "The user said 'just split it', so no questions" | "Split it" is the goal, not permission to guess the seams. |

package/templates/skills/orc-pr-setup/references/layer-taxonomy.md

@@ -0,0 +1,67 @@
+# Reference — layer taxonomy (where the cut lines go)
+
+Loaded at Phase S3/S4. **Ordering principle: dependency direction = stack
+direction.** Layer N may depend only on layers < N. The bottom layer has the
+widest blast radius and is the least reversible (schema); the top is the
+thinnest (docs, a flag flip).
+
+## Generic tiers (the fallback — any stack)
+
+`data/schema → store → domain logic → external adapter → wiring → transport →
+async consumers → tests-at-scale → docs & flag flip`
+
+Use the framework tiers below when they match; fall back to the generic four
+(**data → logic → transport → wiring**) for anything unlisted.
+
+## Backend service (Go / Java / Node / Python — layered service shape)
+
+| # | Tier | What it contains | Typical value class |
+|---|------|------------------|---------------------|
+| 1 | **Migrations / schema** | DDL only. Deployable ahead of code, reversible | CONTRACT or FOUNDATION |
+| 2 | **Models + repository / store** | structs/entities, queries, repo tests. Consumes 1 | FOUNDATION |
+| 3 | **Domain / service logic** | business rules, unit-tested in isolation | FOUNDATION or CONTRACT |
+| 4 | **Adapter / external client** | provider HTTP/gRPC client, signing, DTO mapping | FOUNDATION |
+| 5 | **Wiring** | factory registration, config, DI, feature flag default-OFF | FOUNDATION |
+| 6 | **Handler / route / API contract** | transport layer, request validation, response shape | CONTRACT |
+| 7 | **Callbacks / async consumers** | webhook + queue handlers — separate from 6: different reviewer, different risk | CONTRACT or OPERATOR |
+| 8 | **Tests-at-scale / e2e** | only when they would blow the budget of the layer they belong to | FOUNDATION |
+| 9 | **Docs / dashboards / flag flip** | the flip that turns the feature on for users | USER or OPERATOR |
+
+## Frontend
+
+`types + API client → presentational component (+ stories/tests) → state/store →
+page/route + wiring → flag flip`
+
+## Separation rule (the one people break)
+
+A **component** and its **handler** are different concerns → **different layers
+by default**, even when both are small and were written in the same sitting.
+Likewise:
+
+- handler vs async consumer (webhook/queue),
+- migration vs the code that reads the new column,
+- provider adapter vs the domain logic that calls it,
+- refactor/rename vs behavior change in the same file (this one is an UNCERTAIN —
+  see `certainty-gate.md`).
+
+## Value classes (every layer carries exactly one)
+
+- **`USER`** — an end user or merchant sees a behavior change.
+- **`OPERATOR`** — ops/on-call gains a capability (dashboard, script, better
+  log/alert).
+- **`CONTRACT`** — a consumer-visible API / schema / event contract lands,
+  unblocking another team or repo.
+- **`FOUNDATION`** — no external value; it enables named upper layer(s). Allowed
+  (layer 1 of any stack is foundation by construction) but **capped**: it MUST
+  name its consumer layer, at most **2 consecutive** FOUNDATION layers, and a
+  FOUNDATION layer with no named consumer merges into its consumer.
+
+No purpose → not a layer. No value class → not a layer.
+
+## Layer ordering when there is no dependency
+
+Two layers with no dependency between them can go in either order — which means
+**the order is a review decision, not a technical one**, and that makes it an
+UNCERTAIN (ask). Default recommendation when you ask: the layer that gives a
+reviewer the most context first (usually schema/contract before the code that
+consumes it).