mandrel 1.82.0 → 1.84.0

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -1,9 +1,11 @@
 /**
- * `qa` contract resolver — Epic #3214, Story #3294.
+ * `qa` contract resolver — Epic #3214, Story #3294; environment-keyed
+ * contract added by Epic #4326, Story #4327.
  *
  * The agent-driven QA harness (`/qa-run`) needs the
  * consumer's `.agentrc.json` `qa` block to know where the `.feature` root
- * lives, how to sign in, and which personas the seam accepts. The block is
+ * lives, which deployment targets (`environments`) exist and how to sign in
+ * to each, and which personas the seam accepts. The block is
  * *optional in the schema* (most repos never bind the harness, so config
  * validation must not break them — see Tech Spec #3285 § "qa contract
  * block"), which means presence is enforced at run time by this resolver
@@ -16,8 +18,14 @@
  *     exists.
  *   - Malformed block → throw an error naming the offending field so the
  *     operator can fix `.agentrc.json` without spelunking the schema.
- *   - Well-formed block → return the normalized contract object with the
- *     two optional fields (`consoleAllowlist`, `designTokens`) defaulted.
+ *   - Well-formed block → return the normalized contract object with
+ *     `environments` + `defaultEnvironment` and the two optional fields
+ *     (`consoleAllowlist`, `designTokens`) defaulted.
+ *
+ * `resolveQaEnvironment(contract, target)` selects one environment per
+ * harness invocation — by exact name or by raw-URL origin match against each
+ * environment's `baseUrl` — and throws loudly (naming the known environments)
+ * on an unknown name or unmatched URL.
  */
 
 import Ajv from 'ajv';
@@ -36,10 +44,19 @@ import { QA_SCHEMA } from '../config-settings-schema.js';
 export const QA_REQUIRED_FIELDS = Object.freeze([
   'featureRoot',
   'fixturesManifest',
-  'signInSeam',
+  'environments',
   'personas',
 ]);
 
+/**
+ * The environment name whose `allowWrites` defaults to `true` when the
+ * consumer omits the flag. Every other environment defaults to read-only
+ * (`allowWrites: false`) so an unguarded remote target cannot accept writes
+ * by accident — only the conventional `local` environment is write-enabled
+ * by default.
+ */
+const WRITE_ENABLED_DEFAULT_ENVIRONMENT = 'local';
+
 /** Defaults applied to the optional fields of a well-formed contract. */
 export const QA_CONTRACT_DEFAULTS = Object.freeze({
   consoleAllowlist: Object.freeze([]),
@@ -48,7 +65,7 @@ export const QA_CONTRACT_DEFAULTS = Object.freeze({
 
 const ABSENT_MESSAGE =
   'qa: this project has not bound the QA harness — add a `qa` block to ' +
-  '.agentrc.json (featureRoot, fixturesManifest, signInSeam, personas) ' +
+  '.agentrc.json (featureRoot, fixturesManifest, environments, personas) ' +
   'before invoking the QA harness. See .agents/docs/agentrc-reference.json for the ' +
   'full contract shape.';
 
@@ -127,7 +144,8 @@ function describeError(err) {
  * @returns {{
  *   featureRoot: string,
  *   fixturesManifest: string,
- *   signInSeam: object,
+ *   environments: Record<string, { baseUrl: string, signInSeam: object, allowWrites?: boolean }>,
+ *   defaultEnvironment: string,
  *   personas: Record<string, object>,
  *   personaNames: string[],
  *   consoleAllowlist: string[],
@@ -173,10 +191,28 @@ export function resolveQaContract(config) {
 
   const { personas, personaNames } = normalizePersonas(qa.personas);
 
+  // Clone each environment so callers cannot mutate the resolver's input.
+  const environments = {};
+  for (const [name, env] of Object.entries(qa.environments)) {
+    environments[name] = { ...env };
+  }
+
+  // The default environment is the conventional `local` target when present,
+  // otherwise the first-declared environment. `resolveQaEnvironment(contract)`
+  // (no target) resolves to this one.
+  const environmentNames = Object.keys(environments);
+  const defaultEnvironment = Object.hasOwn(
+    environments,
+    WRITE_ENABLED_DEFAULT_ENVIRONMENT,
+  )
+    ? WRITE_ENABLED_DEFAULT_ENVIRONMENT
+    : environmentNames[0];
+
   return {
     featureRoot: qa.featureRoot,
     fixturesManifest: qa.fixturesManifest,
-    signInSeam: qa.signInSeam,
+    environments,
+    defaultEnvironment,
     personas,
     personaNames,
     consoleAllowlist: Array.isArray(qa.consoleAllowlist)
@@ -188,3 +224,103 @@ export function resolveQaContract(config) {
         : qa.designTokens,
   };
 }
+
+/**
+ * Normalize a value to its URL origin (`protocol//host:port`), or `null` when
+ * it is not a parseable absolute URL. Used to match a raw-URL `target` against
+ * each environment's `baseUrl` by origin, so a target carrying a path,
+ * query-string, or trailing slash still resolves to the right environment.
+ *
+ * @param {string} value
+ * @returns {string | null}
+ */
+function toOrigin(value) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a single QA environment for one harness invocation.
+ *
+ * `target` selects which of the contract's `environments` to run against:
+ *   - **Omitted / falsy** → the contract's `defaultEnvironment`.
+ *   - **Exact environment name** → that environment.
+ *   - **Raw URL** → the environment whose `baseUrl` shares the same origin
+ *     (`protocol//host:port`), so a target with a path or query still matches.
+ *
+ * Resolution is name-first: a `target` that exactly names an environment wins
+ * even if it also happens to parse as a URL.
+ *
+ * `allowWrites` is resolved to an explicit boolean on the returned object: the
+ * environment's own value when set, otherwise `true` only for the conventional
+ * `local` environment and `false` for every other target — an unguarded remote
+ * environment is read-only unless the consumer opts in.
+ *
+ * Fails **loudly**: an unknown name or an unmatched URL throws an error that
+ * names the known environments so the operator can correct the invocation.
+ *
+ * @param {{ environments: Record<string, { baseUrl: string, signInSeam: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
+ *   A contract returned by `resolveQaContract`.
+ * @param {string} [target] Environment name or raw URL. Omit for the default.
+ * @returns {{ name: string, baseUrl: string, signInSeam: object, allowWrites: boolean }}
+ * @throws {Error} on an unknown name or unmatched URL.
+ */
+export function resolveQaEnvironment(contract, target) {
+  const environments = contract?.environments;
+  if (
+    environments == null ||
+    typeof environments !== 'object' ||
+    Object.keys(environments).length === 0
+  ) {
+    throw new Error(
+      'qa: cannot resolve an environment — the contract carries no ' +
+        '`environments`. Call resolveQaContract first.',
+    );
+  }
+
+  const known = Object.keys(environments);
+  const knownList = known.map((name) => `\`${name}\``).join(', ');
+
+  // No target → the default environment.
+  const name =
+    target == null || target === '' ? contract.defaultEnvironment : target;
+
+  // Exact-name match wins first (a name that also parses as a URL still
+  // resolves by name).
+  let resolvedName = Object.hasOwn(environments, name) ? name : null;
+
+  // Otherwise try to match the target as a raw URL against each baseUrl origin.
+  if (resolvedName === null) {
+    const targetOrigin = toOrigin(name);
+    if (targetOrigin !== null) {
+      resolvedName =
+        known.find(
+          (envName) => toOrigin(environments[envName].baseUrl) === targetOrigin,
+        ) ?? null;
+    }
+  }
+
+  if (resolvedName === null) {
+    throw new Error(
+      `qa: unknown environment \`${name}\` — the contract declares ${knownList}. ` +
+        'Pass an exact environment name or a URL whose origin matches one of ' +
+        'their baseUrl values.',
+    );
+  }
+
+  const env = environments[resolvedName];
+  const allowWrites =
+    typeof env.allowWrites === 'boolean'
+      ? env.allowWrites
+      : resolvedName === WRITE_ENABLED_DEFAULT_ENVIRONMENT;
+
+  return {
+    name: resolvedName,
+    baseUrl: env.baseUrl,
+    signInSeam: env.signInSeam,
+    allowWrites,
+  };
+}

package/.agents/skills/core/epic-plan-consolidate/SKILL.md

@@ -30,11 +30,13 @@ allowed_tools:
 ## Role
 
 Senior Project Manager + Orchestrator, acting as a **holistic critic** with
-fresh context. This Skill is deliberately *separate* from
-`epic-plan-decompose-author` (the generator): a same-pass self-critique is the
-weak mode this is built to escape. The generator maps Epic capabilities to
-Stories ~1:1; this critic steps back and looks at the *whole* decomposition
-against the Tech Spec's intentional grouping before any GitHub write.
+fresh context — deliberately *separate* from `epic-plan-decompose-author` (the
+generator) so the pass is a fresh-context review, not a same-pass self-critique.
+
+> **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
+> why this critic runs with fresh context, why scope conservation is your
+> contract rather than a runtime guarantee, and how the below-ceiling
+> coarsening case is reported.
 
 ## When to use
 

package/.agents/skills/core/epic-plan-consolidate/examples.md

@@ -0,0 +1,51 @@
+# epic-plan-consolidate — examples & extended rationale
+
+Read this file on demand. The SKILL.md carries the operating contract (Policy
+Capsule, Inputs / Outputs, Procedure, Constraints); this file carries the
+extended rationale behind the consolidation pass — why it is a separate,
+fresh-context critic and how the scope-conservation invariant is enforced by
+you rather than by the runtime.
+
+## Why a separate fresh-context critic
+
+This Skill acts as a **holistic critic** with fresh context (a Senior Project
+Manager + Orchestrator lens). It is deliberately *separate* from
+`epic-plan-decompose-author` (the generator): a same-pass self-critique is the
+weak mode this is built to escape. The generator maps Epic capabilities to
+Stories ~1:1; this critic steps back and looks at the *whole* decomposition
+against the Tech Spec's intentional grouping before any GitHub write.
+
+## Scope conservation is your contract, not a machine guarantee
+
+Scope conservation is the load-bearing invariant: you MUST NOT add scope,
+invent tickets, or drop acceptance criteria. Every acceptance item and every
+`verify` entry present in the draft MUST survive into the consolidated array
+(possibly re-homed onto a merged Story).
+
+**This is your contract, not a machine guarantee.** There is **no runtime
+acceptance-union diff** on your output. The only deterministic runtime backstop
+the validator applies after you run is the standard ticket-structure
+validation — it does not re-derive the pre-consolidation acceptance/verify
+union, so a critic that silently dropped an acceptance item would **not** be
+caught downstream. (The repo's unit test exercises a *pure model* of the merge
+over an over-fragmented fixture to document the intended invariant; it does not
+inspect this Skill's actual output.) Conserve scope yourself, deliberately, on
+every merge — and if you cannot preserve an item, you have over-reached, so back
+the operation out.
+
+## Ceiling, not target — the below-ceiling coarsening case
+
+Consume the Tech Spec **"Delivery Slicing"** section as a **ceiling, not a
+target** when present: the Architect's proposed N shippable Stories is an
+*upper bound*, not a floor. Cluster the draft's Stories toward that grouping,
+and go **below** N when slices form dependent single-consumer chains — a slice
+whose "Independent? No" row carries no justification (parallelism, risk
+isolation, or delivery-envelope pressure) folds into its consumer. You **never**
+split above N.
+
+When the consolidated count drops **below** the Delivery-Slicing count, the
+consolidation report MUST surface that fact explicitly — e.g.
+`Below ceiling: N (Delivery Slicing) → M (consolidated)` — and attach a one-line
+rationale to each below-ceiling merge (which dependent single-consumer slice
+folded into which consumer, and why it was unjustified), so the operator sees
+the coarsening at the Phase 8.3 advisory diff.

package/.agents/skills/core/epic-plan-decompose-author/SKILL.md

@@ -302,28 +302,10 @@ When the Acceptance Table contains **one or more `Disposition: new` rows**, you
 
 When the Acceptance Table contains **zero `new`-disposition rows** (every row is `updated` or `unchanged`), do NOT emit a scaffold Story — there is nothing to create.
 
-**Worked example.** Epic #42, Acceptance Table with two `new` rows (`AC-1` -> `tests/features/billing/invoice.feature`, `AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below uses a serialized string `body`, top-level `acceptance`/`verify` arrays, an empty `depends_on`, and tags each scenario with both `@skip` and its namespaced `@epic-42-ac-N` tag:
-
-    {
-      "slug": "scaffold-billing-feature-files",
-      "type": "story",
-      "title": "Scaffold @skip-tagged billing feature files",
-      "depends_on": [],
-      "labels": ["type::story", "persona::qa-engineer"],
-      "acceptance": [
-        "tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch",
-        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)",
-        "the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2"
-      ],
-      "verify": [
-        "test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)",
-        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)",
-        "grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)"
-      ],
-      "body": "## Goal\nbdd-scaffold: create the @skip-tagged, @epic-42-ac-N-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n- [ ] the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n- grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)\n"
-    }
-
-The implementation Stories that later un-skip and flesh out these scenarios each carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later wave than the scaffold. They MUST NOT add the `@epic-42-ac-N` tag themselves — it is already present from the scaffold pass; their job is to remove `@skip` once the scenario passes.
+> **Read [`examples.md`](./examples.md) on demand** for a fully worked wave-0
+> scaffold Story (Epic #42, two `new` rows) showing the serialized string
+> `body`, the top-level `acceptance`/`verify` arrays, the empty `depends_on`,
+> and the paired `@skip` + `@epic-<id>-ac-N` tagging.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work)
 

package/.agents/skills/core/epic-plan-decompose-author/examples.md

@@ -0,0 +1,47 @@
+# epic-plan-decompose-author — examples & extended rationale
+
+Read this file on demand while authoring the ticket array. The SKILL.md carries
+the operating contract (Policy Capsule, Inputs / Outputs, Procedure, the
+authoring guidance that complements the rendered decomposer prompt, and
+Constraints); this file carries the worked WAVE-0 BDD scaffold Story and the
+extended reasoning behind it.
+
+## WAVE-0 BDD scaffold Story — worked example
+
+The contract lives in SKILL.md under **WAVE-0 BDD SCAFFOLD STORY**: when the
+Epic body's `## Acceptance Table` carries one or more `Disposition: new` rows,
+emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create
+those `.feature` files with `@skip`-tagged scenarios (each also carrying its
+namespaced `@epic-<id>-ac-N` tag) BEFORE any implementation Story runs.
+
+**Worked example.** Epic #42, Acceptance Table with two `new` rows
+(`AC-1` -> `tests/features/billing/invoice.feature`,
+`AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below
+uses a serialized string `body`, top-level `acceptance`/`verify` arrays, an
+empty `depends_on`, and tags each scenario with both `@skip` and its namespaced
+`@epic-42-ac-N` tag:
+
+    {
+      "slug": "scaffold-billing-feature-files",
+      "type": "story",
+      "title": "Scaffold @skip-tagged billing feature files",
+      "depends_on": [],
+      "labels": ["type::story", "persona::qa-engineer"],
+      "acceptance": [
+        "tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch",
+        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)",
+        "the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2"
+      ],
+      "verify": [
+        "test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)",
+        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)",
+        "grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)"
+      ],
+      "body": "## Goal\nbdd-scaffold: create the @skip-tagged, @epic-42-ac-N-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n- [ ] the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n- grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)\n"
+    }
+
+The implementation Stories that later un-skip and flesh out these scenarios each
+carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later
+wave than the scaffold. They MUST NOT add the `@epic-42-ac-N` tag themselves —
+it is already present from the scaffold pass; their job is to remove `@skip`
+once the scenario passes.

package/.agents/skills/core/epic-plan-premortem/SKILL.md

@@ -28,14 +28,15 @@ allowed_tools:
 
 ## Role
 
-Senior Engineer + Architect, acting as a **fresh-context pre-mortem critic**.
-This Skill is deliberately *separate* from `epic-plan-decompose-author` (the
-generator) and from `epic-plan-consolidate` (the scope-preserving merge critic):
-a same-pass self-critique is the weak mode this is built to escape. The
-generator maps Epic capabilities to Stories against the spec text; this critic
-opens the **actual cited code** and asks "if I tried to deliver this exact
-backlog, where would it rework?" — before any GitHub write makes the rework
-expensive.
+Senior Engineer + Architect, acting as a **fresh-context pre-mortem critic** —
+deliberately *separate* from `epic-plan-decompose-author` (the generator) and
+`epic-plan-consolidate` (the scope-preserving merge critic) so it is a
+fresh-context, code-reading review, not a same-pass self-critique.
+
+> **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
+> why this critic opens the actual cited code, why it is additive-recommendation
+> (not scope-preserving) unlike consolidation, and the three predicted-rework
+> finding classes in full.
 
 ## When to use
 

package/.agents/skills/core/epic-plan-premortem/examples.md

@@ -0,0 +1,53 @@
+# epic-plan-premortem — examples & extended rationale
+
+Read this file on demand. The SKILL.md carries the operating contract (Policy
+Capsule, Inputs / Outputs, Procedure, Constraints); this file carries the
+extended rationale behind the pre-mortem critic — why it is a separate,
+fresh-context, code-reading pass and how its three predicted-rework finding
+classes differ from the structural gates.
+
+## Why a separate fresh-context code-reading critic
+
+This Skill acts as a Senior Engineer + Architect in the role of a
+**fresh-context pre-mortem critic**. It is deliberately *separate* from
+`epic-plan-decompose-author` (the generator) and from `epic-plan-consolidate`
+(the scope-preserving merge critic): a same-pass self-critique is the weak mode
+this is built to escape. The generator maps Epic capabilities to Stories
+against the spec text; this critic opens the **actual cited code** and asks "if
+I tried to deliver this exact backlog, where would it rework?" — before any
+GitHub write makes the rework expensive.
+
+**You MUST read the actual cited code surfaces.** This is the load-bearing
+difference between this critic and the structural file-assumption gate: that
+gate proves a path **exists** (or does not); this critic reads what the file
+actually **contains**. A pre-mortem that did not open the cited files has not
+run.
+
+## Not scope-preserving (unlike consolidation)
+
+Unlike `epic-plan-consolidate` (merge-and-rewire only), this critic MAY
+recommend splitting an under-specified Story, tightening or rewording an
+acceptance criterion, or flagging an over-specified Story — because it only
+*recommends* in a report; it never applies the change itself. The conservation
+invariant belongs to consolidation; this pass is deliberately a separate,
+additive-recommendation lens. It never writes to GitHub, never persists
+`tickets.json`, and never flips a label — re-authoring on its findings is the
+author skill's job (the workflow re-runs `epic-plan-decompose-author` on the
+report before the persist call).
+
+## The three predicted-rework finding classes
+
+Hunt for the three classes the structural gates cannot catch:
+
+1. **Unverifiable acceptance criteria** — an AC no `verify[]` command or
+   readable code state can prove. Recommend a concrete verify command or a
+   reworded, checkable AC.
+2. **Over- or under-specified Stories** — a Story whose `acceptance[]` is far
+   broader or narrower than its `changes[]` footprint and the cited code
+   support. Recommend a split (under-specified: one Story doing the work of
+   several) or a tightening.
+3. **Semantically-wrong assumptions** — the cited file exists (so the
+   file-assumption gate passes) but does not contain the seam / export /
+   function / data shape the Story assumes — the file-assumption gate passes,
+   the work would still rework. Recommend the corrected target or an explicit
+   "create the seam first" Story.

package/.agents/skills/core/epic-plan-spec-author/SKILL.md

@@ -181,88 +181,28 @@ before reaching for names that appear only in the documentation. Write to
 
 #### Delivery Slicing section (authoritative ceiling for Phase 8 consolidation)
 
-The Tech Spec MUST carry a `## Delivery Slicing` section in which the Architect
-— who holds the full design — proposes how the Epic's enumerated capabilities
-**cluster into N shippable Stories**. This section is the intentional grouping
-the Phase 8 consolidation pass
+The Tech Spec MUST carry a `## Delivery Slicing` section proposing how the
+Epic's enumerated capabilities **cluster into N shippable Stories** — the
+intentional grouping the Phase 8 consolidation pass
 ([`epic-plan-consolidate`](../epic-plan-consolidate/SKILL.md)) reconciles the
-decomposer's draft against before any GitHub write. Without it, the decompose
-phase maps Epic capabilities to Stories ~1:1 and cannot produce a coarser,
-holistic plan; with it, the consolidation critic has a well-defined reference
-instead of a guess.
-
-**The proposed count is a ceiling, not a target.** Consolidation reconciles
-the draft *toward* your grouping, but it treats the count as an upper bound: it
-may **merge below** your proposed count when slices form dependent
-single-consumer chains, and it **never splits above** it. Over-slicing here
-therefore locks in fragmentation only when the extra slices are genuinely
-independent — so keep a slice separate only when it earns its own delivery
-session.
-
-**Write the Delivery Slicing section before any other section — it is the
-primary input to Phase 8 consolidation.** Author it first so the rest of the
-spec (Core Components, API Changes, Data Models) hangs off a deliberate
-slicing decision rather than being reverse-engineered into one at the end.
-Drafting it last is exactly how the model omits it under the weight of the
-other sections.
-
-Author the section as a table — one row per proposed slice — naming the
-capability cluster each slice would deliver, what ships in it, and whether it
-can ship independently. Use **noun phrases** for slice names ("Foundation",
-"Transport seam", "Send helper") so they map cleanly onto Feature titles in the
-resulting decomposition — never verb phrases ("Add transport") or file names
-("`sender.ts`"). Do **not** coarsen the Epic's capability enumeration to produce
-the slicing: the granularity lever is *this* grouping recommendation, not a
-dumbed-down Epic enumeration.
-
-**What "Independent?" means:** can this slice ship to production and provide
-value *without the next slice landing*? A `Yes` slice is releasable on its own;
-a `No` slice only becomes valuable once a later slice lands on top of it.
-
-**"Independent? No" is a smell that must be justified.** A dependent,
-single-consumer slice (one that only feeds the next slice) folds into its
-consumer by default — it is not worth its own delivery session's hydration,
-branch, PR, and CI ceremony. Mark a slice `No` only when you can name a
-one-line reason to keep it separate anyway: **parallelism** (two `No` slices
-that can be delivered concurrently by different sessions), **risk isolation**
-(a blast-radius or reviewability reason to land it as its own reviewable PR),
-or **delivery-envelope pressure** (folding it in would push the consumer past a
-single-session sizing envelope). Absent such a justification, do not author the
-slice as its own row — fold it into its consumer and let the merged slice carry
-the combined capability.
-
-Worked example:
-
-```text
-## Delivery Slicing
-
-Proposed shippable slices (consolidation ceiling for Phase 8):
-
-| Slice          | What ships                                              | Independent? |
-| -------------- | ------------------------------------------------------ | ------------ |
-| Foundation     | Config schema, types, and the no-op default path       | Yes          |
-| Transport seam | The pluggable transport interface + in-memory adapter  | Yes          |
-| Send helper    | The send() helper + retries, built on the transport    | No (justified: risk isolation) |
-
-- **Foundation** folds Epic capabilities "config surface" + "type model" — they
-  share a reason to exist and ship as one reviewable PR.
-- **Transport seam** is the pluggable boundary; it provides value on its own
-  (in-memory adapter is usable for tests) so it is independently shippable.
-- **Send helper** depends on the transport seam landing first, so it is *not*
-  independent. It stays its own slice only because the retry/backoff logic is a
-  large, high-blast-radius surface worth isolating in its own reviewable PR
-  (risk isolation). Absent that justification it would fold into Transport
-  seam — a bare "depends on the previous slice" is not a reason to keep it
-  separate.
-```
-
-The consolidation pass degrades gracefully when this section is absent (it
-falls back to cohesion + single-Story-Feature rules only), so authoring it is
-how the Architect steers the decomposition toward fewer, right-sized Stories.
-Because the count is a **ceiling**, an over-sliced table is coarsened back
-during consolidation — but only where the extra slices are dependent
-single-consumer chains, so an unjustified `No` slice is the one you should fold
-in yourself rather than leaning on the consolidator to catch.
+decomposer draft against before any GitHub write. Author it as a table (one row
+per slice: `Slice | What ships | Independent?`), using **noun-phrase** slice
+names, and **write it before any other section** — it is the primary input to
+consolidation and the section the model most often omits when it drafts it last.
+
+- **The count is a ceiling, not a target.** Consolidation may merge below it
+  (dependent single-consumer chains) but never splits above it.
+- **"Independent?"** answers: can this slice ship to production and provide
+  value without the next slice landing? Mark a slice `No` only with a one-line
+  justification (parallelism, risk isolation, or delivery-envelope pressure);
+  an unjustified dependent single-consumer slice folds into its consumer.
+- Do **not** coarsen the Epic's capability enumeration to produce the slicing;
+  the grouping recommendation is the granularity lever.
+
+> **Read [`examples.md`](./examples.md) on demand** for the worked Delivery
+> Slicing table and the extended rationale behind these rules (what
+> "Independent?" means, why an unjustified `No` slice is a smell, and how the
+> consolidation pass degrades gracefully when the section is absent).
 
 #### Tech Spec system prompt (authoritative)
 

package/.agents/skills/core/epic-plan-spec-author/examples.md

@@ -0,0 +1,91 @@
+# epic-plan-spec-author — examples & extended rationale
+
+Read this file on demand while authoring the Tech Spec. The SKILL.md carries
+the operating contract (Policy Capsule, Inputs / Outputs, Procedure, the two
+authoritative system prompts, and Constraints); this file carries the worked
+Delivery Slicing example and the extended rationale behind the slicing rules.
+
+## Delivery Slicing — extended rationale
+
+The Tech Spec MUST carry a `## Delivery Slicing` section in which the Architect
+— who holds the full design — proposes how the Epic's enumerated capabilities
+**cluster into N shippable Stories**. This section is the intentional grouping
+the Phase 8 consolidation pass
+([`epic-plan-consolidate`](../epic-plan-consolidate/SKILL.md)) reconciles the
+decomposer's draft against before any GitHub write. Without it, the decompose
+phase maps Epic capabilities to Stories ~1:1 and cannot produce a coarser,
+holistic plan; with it, the consolidation critic has a well-defined reference
+instead of a guess.
+
+**The proposed count is a ceiling, not a target.** Consolidation reconciles
+the draft *toward* your grouping, but it treats the count as an upper bound: it
+may **merge below** your proposed count when slices form dependent
+single-consumer chains, and it **never splits above** it. Over-slicing here
+therefore locks in fragmentation only when the extra slices are genuinely
+independent — so keep a slice separate only when it earns its own delivery
+session.
+
+**Write the Delivery Slicing section before any other section — it is the
+primary input to Phase 8 consolidation.** Author it first so the rest of the
+spec (Core Components, API Changes, Data Models) hangs off a deliberate
+slicing decision rather than being reverse-engineered into one at the end.
+Drafting it last is exactly how the model omits it under the weight of the
+other sections.
+
+Author the section as a table — one row per proposed slice — naming the
+capability cluster each slice would deliver, what ships in it, and whether it
+can ship independently. Use **noun phrases** for slice names ("Foundation",
+"Transport seam", "Send helper") so they map cleanly onto Feature titles in the
+resulting decomposition — never verb phrases ("Add transport") or file names
+("`sender.ts`"). Do **not** coarsen the Epic's capability enumeration to produce
+the slicing: the granularity lever is *this* grouping recommendation, not a
+dumbed-down Epic enumeration.
+
+**What "Independent?" means:** can this slice ship to production and provide
+value *without the next slice landing*? A `Yes` slice is releasable on its own;
+a `No` slice only becomes valuable once a later slice lands on top of it.
+
+**"Independent? No" is a smell that must be justified.** A dependent,
+single-consumer slice (one that only feeds the next slice) folds into its
+consumer by default — it is not worth its own delivery session's hydration,
+branch, PR, and CI ceremony. Mark a slice `No` only when you can name a
+one-line reason to keep it separate anyway: **parallelism** (two `No` slices
+that can be delivered concurrently by different sessions), **risk isolation**
+(a blast-radius or reviewability reason to land it as its own reviewable PR),
+or **delivery-envelope pressure** (folding it in would push the consumer past a
+single-session sizing envelope). Absent such a justification, do not author the
+slice as its own row — fold it into its consumer and let the merged slice carry
+the combined capability.
+
+### Worked example
+
+```text
+## Delivery Slicing
+
+Proposed shippable slices (consolidation ceiling for Phase 8):
+
+| Slice          | What ships                                              | Independent? |
+| -------------- | ------------------------------------------------------ | ------------ |
+| Foundation     | Config schema, types, and the no-op default path       | Yes          |
+| Transport seam | The pluggable transport interface + in-memory adapter  | Yes          |
+| Send helper    | The send() helper + retries, built on the transport    | No (justified: risk isolation) |
+
+- **Foundation** folds Epic capabilities "config surface" + "type model" — they
+  share a reason to exist and ship as one reviewable PR.
+- **Transport seam** is the pluggable boundary; it provides value on its own
+  (in-memory adapter is usable for tests) so it is independently shippable.
+- **Send helper** depends on the transport seam landing first, so it is *not*
+  independent. It stays its own slice only because the retry/backoff logic is a
+  large, high-blast-radius surface worth isolating in its own reviewable PR
+  (risk isolation). Absent that justification it would fold into Transport
+  seam — a bare "depends on the previous slice" is not a reason to keep it
+  separate.
+```
+
+The consolidation pass degrades gracefully when this section is absent (it
+falls back to cohesion + single-Story-Feature rules only), so authoring it is
+how the Architect steers the decomposition toward fewer, right-sized Stories.
+Because the count is a **ceiling**, an over-sliced table is coarsened back
+during consolidation — but only where the extra slices are dependent
+single-consumer chains, so an unjustified `No` slice is the one you should fold
+in yourself rather than leaning on the consolidator to catch.