mandrel 1.93.0 → 2.0.0

package/.agents/skills/core/code-review-and-quality/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: code-review-and-quality
 description:
-  Conducts multi-axis code review. Use before merging any change. Use when
-  reviewing code written by yourself, another agent, or a human. Use when you
-  need to assess code quality across multiple dimensions before it enters the
-  main branch.
+  Conducts multi-axis code review and runs the disciplined post-green refactor
+  pass. Use before merging any change, when reviewing code written by yourself,
+  another agent, or a human, or when the opt-in `delivery.refactorStage`
+  checkpoint asks for a behaviour-preserving CRAP/duplication pass after the
+  suite is green.
 ---
 
 # Code Review and Quality
@@ -18,9 +19,11 @@ description:
 - Reject "clever" code in favour of the boring, obvious solution. Abstractions MUST earn their complexity (no generalizing before the third use case).
 - Flag dead code artifacts (`_unused` vars, backwards-compat shims, `// removed` comments) and require their removal before merge.
 - Defer to `.agents/rules/security-baseline.md` and the `security-and-hardening` skill for security review; explicit checks include input validation, no hardcoded secrets, parameterized queries, encoded output, authn+authz, and treating external data as untrusted.
-- Defer to `performance-optimization` for perf review; explicit checks include no N+1 queries, no unbounded fetches, no blocking sync work, no obviously oversized bundles.
+- Review performance on the hot path only, and measure before optimizing; explicit checks include no N+1 queries, no unbounded fetches, no blocking sync work, no obviously oversized bundles.
 - Disallow scope creep in a PR: drive-by cleanups, adjacent refactors, and "while I'm here" edits should be split into a separate change.
 - Bug-fix reviews cover **both** the fix and the regression test; a fix without a failing-then-passing test is not approvable.
+- **Refactoring is post-green and behaviour-preserving.** Run the refactor pass only when the suite is already green and gates pass; inputs, outputs, side effects, error semantics, and ordering MUST be identical before and after, and existing tests MUST keep passing **without modification** (if a test had to change, behaviour changed — revert).
+- **Lower CRAP by lowering complexity, and remove duplication at the root.** Target the highest-CRAP well-covered functions and the largest verbatim duplications by measurement (`check-baselines.js`), not by smell; extract one well-named helper rather than leaving near-copies. CRAP must not rise and maintainability must not fall on any touched file, and no gate, floor, or threshold may be retuned to make the pass "succeed".
 
 ## Overview
 
@@ -105,8 +108,8 @@ introduce vulnerabilities?
 
 ### 5. Performance
 
-For detailed profiling and optimization, see `performance-optimization`. Does
-the change introduce performance problems?
+Measure before optimizing, and only on the hot path. Does the change introduce
+performance problems?
 
 - Any N+1 query patterns?
 - Any unbounded loops or unconstrained data fetching?
@@ -409,6 +412,50 @@ Every dependency is a liability.
   optional
 - Accepting "I'll fix it later" — it never happens
 
+## Post-Green Refactor Pass
+
+Review's sibling discipline is the **behaviour-preserving refactor** that drives
+CRAP (Change Risk Anti-Patterns) and duplication down _after_ the code is green
+— the pass wired in as the opt-in `delivery.refactorStage` checkpoint. It
+optimises for the measured CRAP and duplication axes the baselines ratchet, not
+for subjective readability, and it never runs from red.
+
+**When to run:** a baseline report flags a high-CRAP function that is already
+well-covered (so the lever is complexity, not coverage); the same logic is
+duplicated across two or more files and the copies are drifting; or the
+`delivery.refactorStage` checkpoint fires after gates pass and before a Story
+closes. **When NOT to:** before tests are green (write/fix tests first), or when
+a function's CRAP is high because it is _uncovered_ — that is a missing-test
+problem, so drive it with the TDD cycle in
+[`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md).
+
+```text
+Confirm green + baseline  →  pick highest-CRAP / largest dup
+        ▲                                  │
+        │                                  ▼
+  re-run gates, confirm   ◄──  refactor   ◄──  comprehend the target
+  CRAP↓ / maint↑, tests pass   (one change)    (call sites + tests)
+```
+
+1. **Baseline.** Confirm green and capture current CRAP and maintainability
+   (`node .agents/scripts/check-baselines.js`) — your do-no-harm reference.
+2. **Target by measurement.** Pick the highest-CRAP well-covered function, or
+   the largest verbatim duplication. Work worst-first.
+3. **Comprehend before you touch (Chesterton's Fence).** Read the call sites and
+   the tests that pin the behaviour first; an "unnecessary" abstraction may
+   exist for testability or extensibility.
+4. **Refactor one step.** Extract a focused function, flatten nesting into guard
+   clauses, replace a nested ternary / boolean-flag param, or extract a single
+   shared helper for the duplication (dedup the _behaviour_, not just the text —
+   look-alike blocks that encode different responsibilities stay separate).
+5. **Verify.** Re-run the affected tests (unmodified) and the baselines. CRAP
+   must not rise, maintainability must not fall, tests must pass. If a test
+   needed editing, revert — behaviour changed.
+
+Keep each refactor an isolated, reviewable commit separate from feature or fix
+work, refactor only the targeted functions/duplications (no drive-by rewrites),
+and leave no dead code behind (unused imports, orphaned helpers).
+
 ## Verification
 
 After review is complete:
@@ -419,3 +466,12 @@ After review is complete:
 - [ ] Tests pass
 - [ ] Build succeeds
 - [ ] The verification story is documented (what changed, how it was verified)
+
+After a post-green refactor pass:
+
+- [ ] The suite was green before and after, with **no test modifications**
+- [ ] CRAP did not rise and maintainability did not fall on any touched file
+      (baselines re-run and compared)
+- [ ] No gate, floor, or coverage threshold was loosened
+- [ ] Duplication was removed at the root (one helper), not just locally patched
+- [ ] Each refactor is an isolated commit, separate from feature or fix work

package/.agents/skills/core/debugging-and-error-recovery/SKILL.md

@@ -15,7 +15,7 @@ description:
 - Follow the triage checklist in order — **Reproduce → Localize → Diagnose → Fix → Verify → Guard** — and never skip steps.
 - A bug you cannot reproduce reliably is a bug you cannot fix with confidence. Invest in reproduction before patching.
 - Fix the **root cause**, not the symptom. Suppressing an error, swallowing an exception, or stubbing an assertion is not a fix.
-- Every bug fix ships with a **failing-then-passing regression test** (the Prove-It Pattern from `test-driven-development`). A fix without a guard test is incomplete.
+- Every bug fix ships with a **failing-then-passing regression test** (the Prove-It Pattern in `.agents/rules/testing-standards.md`). A fix without a guard test is incomplete.
 - Apply the **Anti-Thrashing** rule: if you have applied the same kind of fix more than once and the failure mode hasn't changed, the diagnosis is wrong — re-plan.
 - For non-reproducible bugs, classify them (timing / environment / state / random), add targeted instrumentation, and document conditions instead of chasing in the dark.
 - Bisect history with `git bisect` (or equivalent) when "something used to work" and you cannot localize from the diff.

package/.agents/skills/core/gates-and-baselines/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: gates-and-baselines
+description:
+  Governs quality gates and the unified-baseline snapshots. Use when authoring
+  a baseline refresh commit (CRAP, maintainability, dead-exports, lighthouse),
+  when setting up or modifying CI quality gates, or when introducing a new gate
+  that asserts on pre-existing state without turning the integration branch red.
+allowed_tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# Gates and Baselines
+
+## Policy Capsule
+
+- **No gate may be skipped.** Failing lint means fix lint, not disable the rule; a failing test means fix the code, not `.skip` or delete the test. Gates are ordered shift-left so cheap checks fail first, and CI failure output is fed back verbatim with the directive to reproduce and fix locally before re-pushing.
+- **Introducing a gate that asserts on pre-existing state** (doc-drift, lint-vocabulary, dependency-cycle, missing-coverage) MUST land green at merge: either advisory-first (report-only until the backlog is burned down) or with the populated baseline committed in the same change that turns the gate on. Never wire a gate into `requiredChecks` that lands red on latent findings nobody authored.
+- **Refresh a baseline only when the change is deliberate** — a rename/move, an operator-approved complexity bump, a signed-off perf delta, an intentional API-surface change. Never refresh to paper over an unintentional regression; fix the regression instead.
+- Run the kind-specific update command (`npm run crap:update` / `maintainability:update` / `dead-exports:update` / `lighthouse:update`) on the **Story branch**, not on `main`.
+- Verify the refresh diff is scoped to the relevant `baselines/<kind>.json` (plus cosmetic `package-lock.json` churn only). If unrelated files appear, STOP — the refresh is contaminated. Stage baseline files **explicitly** (`git add baselines/<kind>.json`); never `git add -A` in a refresh commit.
+- Commit-subject contract: a **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story/Epic that triggered it.
+- Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Epic: #<epic-id>` to the body whenever observability classification matters. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
+- After the refresh lands, re-run `node .agents/scripts/check-baselines.js` to confirm the gate passes against the new snapshot; if it still fails, a sibling kind drifted — refresh that kind too.
+- Keep credentials in GitHub Secrets (or platform equivalent) even for CI-only test databases; treat the security audit (`npm audit` or equivalent) as gating for critical/high vulnerabilities reachable in production code.
+
+## The Quality Gate Pipeline
+
+Automate quality gates so no change reaches production without passing tests,
+lint, type checking, and build. **Shift left** — a bug caught in linting costs
+minutes; the same bug caught in production costs hours — and prefer many small,
+frequent releases over big-bang merges (a deploy of 3 changes is debuggable, one
+of 30 is not).
+
+```text
+lint → typecheck → unit tests → build → integration → E2E (optional)
+     → security audit → bundle-size
+```
+
+**No gate can be skipped.** If lint fails, fix lint. If a test fails, fix the
+code. When CI fails, feed the specific error back into the agent loop with the
+directive to verify locally before re-pushing.
+
+### Introducing a gate on pre-existing state
+
+A new gate that asserts on latent state (doc-drift, lint-vocabulary,
+dependency-cycle, missing-test-coverage) lands red because of findings nobody
+authored, and every downstream PR is blocked until someone hotfixes the
+integration branch. Before wiring such a gate into `requiredChecks`, land it in
+a shape that is green at merge — **advisory-first** (report-only until the
+backlog is burned down) or by **committing the populated baseline in the same
+change** that turns the gate on.
+
+## Baseline Refresh
+
+The close-validation chain enforces unified baseline snapshots
+(`baselines/crap.json`, `baselines/maintainability.json`,
+`baselines/dead-exports.json`, `baselines/lighthouse.json`). A refresh is **not**
+a regression entry — it tells the ratchet that the new baseline key is
+intentional, so the gate compares future runs against the refreshed snapshot
+rather than the prior one.
+
+**When to refresh:** a file rename/move detached an MI/CRAP key; a method rename
+inside a file produced a phantom new + phantom deleted key (escomplex keys CRAP
+rows on `<file>::<methodName>`); an operator-approved complexity bump or perf
+delta needs to be enshrined as the new floor; a dead-export gate flagged a
+signed-off API-surface change. If the underlying change is an **unintentional**
+regression, do not refresh — remediate first.
+
+### Commit-subject contract (authoritative)
+
+```text
+chore(baselines): refresh <kind> snapshot for <reason>
+
+<non-empty body explaining the refresh — what changed, why the new
+baseline is the correct floor, and any operator sign-off reference>
+
+baseline-refresh: true
+Epic: #<epic-id>
+```
+
+The `commit-msg` hook (`commitlint`) rejects any subject whose leading token is
+not one of `feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert`, and
+`--no-verify` is forbidden by
+[`.agents/rules/git-conventions.md`](../../../rules/git-conventions.md), so the
+subject MUST conform. `release-please` consumes the subject on `main`;
+`chore(baselines):` keeps the refresh out of the user-facing changelog (correct —
+it is internal hygiene) while staying machine-parseable. The
+`baseline-refresh: true` **body trailer** is the canonical machine-readable
+marker (what
+[`.agents/scripts/lib/observability/baseline-refresh-rate.js`](../../../scripts/lib/observability/baseline-refresh-rate.js)
+classifies against) — subject-level leading tokens are not, and must not be, used
+for this purpose.
+
+### Procedure
+
+| Kind            | Update command                   |
+| --------------- | -------------------------------- |
+| CRAP            | `npm run crap:update`            |
+| Maintainability | `npm run maintainability:update` |
+| Dead-exports    | `npm run dead-exports:update`    |
+| Lighthouse      | `npm run lighthouse:update`      |
+
+1. **Run the matching update command** on the Story branch (HEAD must already be
+   the Story branch, not `main`).
+2. **Verify the diff is scoped** to the relevant `baselines/<kind>.json` (and
+   possibly cosmetic `package-lock.json` churn). Unrelated files → STOP, the
+   refresh is contaminated.
+3. **Author the commit.** Stage the baseline file(s) explicitly, then commit with
+   the Conventional-Commits subject + body trailer above:
+
+   ```bash
+   git add baselines/<kind>.json
+   git commit -m "$(cat <<'EOF'
+   chore(baselines): refresh <kind> snapshot for <reason>
+
+   <body: what changed, why the new floor is correct, linking the Story/Epic.>
+
+   baseline-refresh: true
+   Epic: #<epic-id>
+   EOF
+   )"
+   ```
+
+   Do NOT pass `--no-verify`.
+4. **Re-run the gate** — `node .agents/scripts/check-baselines.js`. If it still
+   fails, a sibling kind drifted; repeat from step 1 for that kind.
+
+## Red Flags
+
+- CI failures ignored or silenced; tests disabled in CI to make the pipeline pass.
+- A new required gate merged red on pre-existing findings, blocking every
+  downstream PR.
+- A legacy ad-hoc leading token (`baseline-refresh:`) as the commit subject type.
+- An empty-body refresh — unreviewable, hides the operator decision.
+- A refresh commit whose diff touches unrelated files (contaminated refresh).
+- Refreshing to paper over an unintentional regression.
+- Secrets stored in code or CI config instead of a secrets manager.
+
+## Verification
+
+- [ ] Every quality gate is present (lint, types, tests, build, audit) and
+      failures block merge (branch protection configured).
+- [ ] Any newly introduced gate is green at merge (advisory-first or
+      baseline-in-same-change).
+- [ ] A baseline refresh uses the Conventional-Commits subject + non-empty body
+      + `baseline-refresh: true` trailer, staged explicitly, no `--no-verify`.
+- [ ] `check-baselines.js` passes against the refreshed snapshot.

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -35,12 +35,12 @@ structured divergent and convergent thinking.
 
 ## Activation
 
-Called from `/plan` Phase 1 (ideation entry, when no `<epic#>` is
-supplied or `--idea "<seed>"` is passed) and Phase 6 (Epic Clarity Gate,
-when an existing Epic body fails the section-presence rubric). In Phase 6
-the skill is seeded from the **current Epic body** — not a blank seed —
-with the rubric gap list (`missingOrPlaceholder`) as the convergence
-target.
+Called from [`/plan`](../../../workflows/plan.md) during ideation when the
+operator supplies `--seed "<text>"` (or runs ideation with no seed and
+the host collects one interactively). The skill sharpens freeform intent
+into canonical planning sections that `/plan` then folds into a Story.
+There is no separate Epic Clarity Gate path in v2 — N=1 Story authoring
+with a folded `## Spec` is the lean default.
 
 ## Usage
 
@@ -124,17 +124,14 @@ conversation, not a template.
      wouldn't?"
 
    Push beyond what the user initially asked for. Create products people don't
-   know they need yet.
+   know they need yet. Pick the lens that fits the idea — don't run every one
+   mechanically.
 
 **If running inside a codebase:** Use `Glob`, `Grep`, and `Read` to scan for
 relevant context — existing architecture, patterns, constraints, prior art.
 Ground your variations in what actually exists. Reference specific files and
 patterns when relevant.
 
-Read `frameworks.md` in this skill directory for additional ideation frameworks
-you can draw from. Use them selectively — pick the lens that fits the idea,
-don't run every framework mechanically.
-
 #### Phase 2: Evaluate & Converge (Grill)
 
 After the user reacts to Phase 1 (indicates which ideas resonate, pushes back,
@@ -283,9 +280,6 @@ Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a
 facilitator reading from a script. Channel the energy of "that's interesting,
 but what if..." -- always pushing one step further without being exhausting.
 
-Read `examples.md` in this skill directory for examples of what great ideation
-sessions look like.
-
 ## Red Flags
 
 - Generating 20+ shallow variations instead of 5-8 considered ones

package/.agents/skills/core/qa-coverage-mapping/SKILL.md

@@ -22,7 +22,7 @@ allowed_tools:
 - Read the verdict as a `{unit, contract, acceptance}` object: each tier is `{status: 'present'|'absent', note}`. A surface with only a colocated unit test reports `unit: present` and `contract`/`acceptance`: `absent` with explanatory notes.
 - Route remediation by the absent tiers, honoring the assertion-placement rule: wire-shape and status-code gaps become **contract** tests, user-visible journey gaps become **acceptance** scenarios — never push those into unit tests or `.feature` files incorrectly.
 - Treat `absent` as a coverage gap to surface, not an automatic failure: some surfaces legitimately need only one tier (a pure formatter needs no acceptance scenario). Use the notes to justify, not to mandate, the missing tier.
-- This skill is read + classify only: it does not author tests, mutate tickets, or run the suite. Hand the verdict to `core/test-driven-development` to actually write the missing tier.
+- This skill is read + classify only: it does not author tests, mutate tickets, or run the suite. Hand the verdict to the TDD cycle in `.agents/rules/testing-standards.md` to actually write the missing tier.
 
 ## Role
 
@@ -45,9 +45,9 @@ missing so remediation is aimed correctly.
 - During a test-pyramid audit, to roll up many surfaces into a tier-by-tier
   gap report.
 
-**When NOT to use:** for authoring tests (use
-[`core/test-driven-development`](../test-driven-development/SKILL.md)), for
-measuring line/branch coverage percentages (that is the unit-tier coverage
+**When NOT to use:** for authoring tests (use the TDD cycle in
+[`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md#applying-the-standards)),
+for measuring line/branch coverage percentages (that is the unit-tier coverage
 config, not this skill), or for anything that requires running the suite.
 
 ## The verdict shape
@@ -79,9 +79,9 @@ config, not this skill), or for anything that requires running the suite.
    explicit `tier` field when you already know it.
 3. **Read the gaps.** Every `absent` tier is a candidate gap. Apply judgment
    from the Policy Capsule: not every surface needs all three tiers.
-4. **Route remediation.** For real gaps, hand off to
-   `core/test-driven-development` with the missing tier named, honoring the
-   assertion-placement rule so each assertion lands in its correct tier.
+4. **Route remediation.** For real gaps, hand off to the TDD cycle in
+   `.agents/rules/testing-standards.md` with the missing tier named, honoring
+   the assertion-placement rule so each assertion lands in its correct tier.
 
 ## Example
 

package/.agents/skills/core/scope-triage/SKILL.md

@@ -1,189 +1,45 @@
 ---
 name: scope-triage
 description:
-  Judge whether a piece of planned work is epic-sized or story-sized before the
-  planning ceremony is paid for. Emits one of three verdicts —
-  `epic` | `story` | `borderline` — over any planning artifact (a one-pager, an
-  Epic body, or a Story draft). Use from `/plan` Phase 1.5 and any other
-  planning gate that needs the canonical story-vs-epic rubric.
+  Optional split-advisory for `/plan`. Under v2 there is no epic|story routing
+  verdict — `/plan` always authors Stories. Use this skill only when judging
+  whether a draft should stay one Story or legitimately split (near-zero
+  overlap or an architectural seam).
 ---
 
-# scope-triage
+# scope-triage (split advisory)
 
 ## Policy Capsule
 
-- Produce exactly one verdict — `epic` | `story` | `borderline` — for the
-  artifact under judgment. Never auto-route on the verdict; the verdict is
-  **advisory**, and the operator always decides what to do with it.
-- Anchor every sizing judgment to the existing sizing SSOT **by reference**:
-  `DELIVERABLE_GRANULARITY_GUIDANCE` and `DEFAULT_TASK_SIZING` in
+- There is **no** `epic | story | borderline` routing verdict in v2. `/plan`
+  is a single path that emits **one Story by default**.
+- This skill is an optional **split advisory**: should the author keep one
+  Story, or does the seed clear the default-single split policy?
+- Anchor sizing judgment to `DEFAULT_MODEL_CAPACITY` and
+  `DELIVERABLE_GRANULARITY_GUIDANCE` in
   [`ticket-validator-sizing.js`](../../../scripts/lib/orchestration/ticket-validator-sizing.js).
-  **Do not restate the numeric thresholds** — read them from that module so the
-  rubric cannot drift from the validator that enforces them.
-- The verdict is **host-LLM judgment**, not a deterministic score. There is no
-  `--flag`, no scorer, no schema, and no label transition behind this skill —
-  it is read-on-demand library content, evaluated with judgment per
-  [`.agents/instructions.md` § 1.B](../../../instructions.md).
-- Lead with **cohesion**, the same primary heuristic the sizing SSOT leads
-  with: one Story is *one coherent change with one reason to exist*. The file /
-  acceptance ceilings are the backstop, not the first cut.
-- Bias toward `epic` only when the work genuinely spans multiple independent
-  capabilities, crosses subsystems, or carries a real dependency graph. Being
-  wrong in the `epic` direction is cheap — the Phase 8.3 consolidation pass and
-  the sizing validator catch an over-planned Story later. Being wrong in the
-  `story` direction is expensive — a story-sized scope pushed through the full
-  Epic ceremony pays a sectioned-Epic-body (Tech Spec + Acceptance Table) +
-  Story backlog +
-  `epic/<id>` integration-branch tax for a degenerate one-Story output.
-- Keep the rubric prose **artifact-agnostic**. The thing under judgment may be a
-  sharpened one-pager, an existing Epic body, or a draft Story — the rubric
-  reads the same against all three so every consumer reuses it verbatim.
+  Do not restate numeric thresholds.
+- Lead with **cohesion**: one Story is one coherent change with one reason
+  to exist. Coupled work stays one Story and uses `## Slicing` for
+  intra-session checkpoints.
 
-## Verdicts
+## Split policy (when N>1 is allowed)
 
-The skill emits exactly one of three verdicts.
+Split into sibling Stories **only** when:
 
-### `story`
+1. **Near-zero overlap** — genuinely independent capabilities that happen to
+   share a seed idea, or
+2. **Architectural seam** — different deployables, or a migration vs the
+   feature that consumes it.
 
-The work is a single shippable capability. Signals:
+Otherwise keep one Story. Persist refuses coupled splits via
+`assertAcceptancePartition` (identical AC text across Stories).
 
-- **One capability, one reason to exist.** The artifact describes one coherent
-  change a reviewer would accept as a single PR — the
-  `DELIVERABLE_GRANULARITY_GUIDANCE.definition` notion of a Story.
-- **Acceptance fits one Story.** The acceptance-criteria list reads as the
-  binding contract of one coherent capability rather than spanning many
-  independent outcomes. Acceptance mass is advisory-only (the
-  `softAcceptanceCount` nudge in `DEFAULT_TASK_SIZING` — there is no hard
-  ceiling), so the question is cohesion, not count.
-- **Footprint fits Story sizing.** The plausible file footprint fits the Story
-  width described by `DEFAULT_TASK_SIZING` (the `softFiles` / `hardFiles`
-  knobs); a legitimately broad-but-cohesive change would declare `wide` rather
-  than being two Stories.
-- **No novel architecture, no high-risk trigger.** The work introduces no novel
-  architectural decision and matches none of the `planning.riskHeuristics` in
-  `.agentrc.json` (destructive/irreversible changes, shared auth/security,
-  CI/CD gate changes, monorepo-wide rewrites, destructive migrations).
-- **Decomposition would degenerate.** Running it through `/plan` would
-  plausibly yield exactly **one Feature with one Story** — the shape the Phase
-  8.3 consolidation skill flags only after all the spec authoring is already
-  sunk cost.
+## Advisory output
 
-### `epic`
+Emit one of:
 
-The work is genuinely Epic-sized. Signals (any one is sufficient):
+- `keep-single` — default; fold complexity into `## Spec` / `## Slicing`
+- `split` — list the proposed Stories and the seam/overlap rationale
 
-- **Multiple independent capabilities.** The artifact bundles two or more
-  capabilities that each stand alone as a unit of work.
-- **Cross-subsystem blast radius.** The change reaches across subsystems that
-  do not share one cohesive reason to exist.
-- **A real dependency graph.** The work has internal ordering — slices that
-  must land before others — rather than one atomic change.
-
-### `borderline`
-
-The work is genuinely on the line — it could reasonably be one ambitious Story
-or a small Epic, and neither call is clearly right. **Present the choice rather
-than deciding for the operator.** Do not force a verdict to avoid the third
-option; a borderline scope surfaced as borderline is the correct output.
-
-## Change-Request Triage Rubric
-
-A **change request** — "fix this", "tweak that", "extend the existing X" —
-is the common case this rubric routes cheaply: a delta against a surface the
-project already shipped, not a from-scratch capability. Route it to `story`
-by default when all three delta signals hold; treat any one signal's absence
-as a prompt to re-check, not an automatic `epic` bump.
-
-### Delta signals
-
-- **Delta to an already-delivered surface.** The request references a
-  concrete existing capability (a module, workflow, script, or shipped
-  feature) rather than proposing a new one. "Fix the flaky retry in
-  `evidence-gate.js`" is a delta; "add a retry framework" is not.
-- **Existing corpus covers the touched area.** The project's docs digest
-  and/or an already-closed or in-flight Epic's Tech Spec section already
-  describe the surface being changed — the standalone-Story path can draft
-  against that inherited context (`corpusContext` in the `/plan --idea`
-  envelope) instead of re-deriving architecture from a blank slate. When no
-  corpus hit exists for the touched area, that is a signal the request may
-  be reaching into genuinely new territory — re-check the `epic` signals
-  below before defaulting to `story`.
-- **Footprint fits Story sizing.** The plausible file footprint and
-  acceptance-criteria count still fit the Story width in
-  `DEFAULT_TASK_SIZING` (per the `story` verdict signals above) — a change
-  request that fans out across independent subsystems is sized like an Epic
-  regardless of how small the originating request sounded.
-
-### Story-verdict rationale template
-
-Use this template to record the verdict — it names which delta signal
-carried the call, so a reviewer can sanity-check the routing decision without
-re-deriving it:
-
-```text
-Verdict: story
-Delta: <the existing surface this change targets>
-Corpus hit: <docs digest section / Epic # and Tech Spec excerpt that covers
-  this area, or "none — re-checked epic signals, still story-sized">
-Footprint: <rough file/AC count vs DEFAULT_TASK_SIZING>
-```
-
-### Worked example
-
-> Request: "The `/plan` standalone-Story path always drafts from a blank
-> slate even when a change request is a small delta against something we
-> already shipped — thread the existing docs digest and matching Epic
-> Tech Spec sections into the draft context."
->
-> ```text
-> Verdict: story
-> Delta: story-plan.js's --emit-context envelope and the plan-story.md
->   Phase 2 drafting instructions — both already exist and ship today.
-> Corpus hit: Epic #4429's own Tech Spec section (this rubric's parent
->   Epic) already describes the docs-digest reuse pattern from
->   orchestration/docs-digest.js.
-> Footprint: one new lib module (planning-corpus.js), one envelope field,
->   one helper-doc instruction — comfortably inside DEFAULT_TASK_SIZING's
->   softFiles/softAcceptanceCount band.
-> ```
-
-## Handoff & no-re-triage rule
-
-A workflow entered via a scope-triage **handoff** MUST NOT re-triage. A handoff
-*is* a triage decision already made — re-running this gate on the receiving side
-would re-litigate a settled call and risk a ping-pong between two planning
-workflows. Handoff invocations identify themselves as such (e.g. `/plan`
-entered via a `/plan` scope-triage escalation, or `/plan` entered
-via an `/plan` Phase 1.5 handoff), and the receiving workflow skips its own
-scope-triage gate when it detects the handoff marker.
-
-## When to use
-
-- **`/plan` Phase 1.5** (ideation path only) — judge the sharpened
-  one-pager Phase 1 produced before the Epic ceremony is paid for. The verdict
-  folds into the existing Phase 1 HITL stop; on a `story` / `borderline`
-  verdict the operator may hand off to
-  [`/plan --from-notes`](../../../workflows/helpers/plan-story.md).
-- Any other planning gate that needs the canonical story-vs-epic rubric. Keep
-  the rubric here as the SSOT; consumers reference this file rather than
-  forking the prose.
-
-## Output
-
-A single verdict (`epic` | `story` | `borderline`) plus a one-paragraph
-rationale grounded in the signals above. The rationale names the deciding
-signal (cohesion, capability count, blast radius, dependency graph, or sizing
-fit) so the operator can sanity-check the call before acting on it.
-
-## Anti-patterns to avoid
-
-- **Restating the sizing numbers.** Reference `DEFAULT_TASK_SIZING` /
-  `DELIVERABLE_GRANULARITY_GUIDANCE`; never copy the thresholds into this file
-  (they would drift from the validator).
-- **Auto-routing on the verdict.** The verdict is advisory; the operator
-  decides. Never silently fork a workflow on a `story` verdict.
-- **Forcing a binary call.** When the work is genuinely on the line, emit
-  `borderline` and present the choice. Do not collapse it to `epic` or `story`
-  to look decisive.
-- **Re-triaging after a handoff.** A handoff is a settled decision. Skip the
-  gate when the invocation identifies itself as a scope-triage handoff.
+Never auto-route. The operator (or `--yes` default = `keep-single`) decides.