mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/story-body/story-body.js

@@ -11,6 +11,8 @@
  * ```js
  * {
  *   goal:                string,           // one-sentence purpose
+ *   slicing:             string,           // v2 intra-Story delivery slice plan (optional; '' when absent)
+ *   spec:                string,           // folded Tech Spec text block (optional; '' when absent)
  *   changes:             PathEntry[],      // files/globs this Story touches
  *   acceptance:          string[],         // observable criteria
  *   verify:              string[],         // exact commands / tier annotation
@@ -23,10 +25,9 @@
  * }
  * ```
  *
- * Where `PathEntry` is one of:
+ * Where `PathEntry` is:
  *   - `{ path: string, assumption: "creates"|"refactors-existing"|"exists"|"deletes" }`
- *     (canonical form)
- *   - `string` (legacy form — emits a `legacy-path-entry` warning)
+ *     (canonical form — string bullets are rejected at parse time)
  *
  * ## Round-trip contract
  *
@@ -61,16 +62,15 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
  */
 
 /**
- * @typedef {PathEntry | string} ChangeEntry
- *   Canonical: PathEntry object.
- *   Legacy: bare string bullet (emits a `legacy-path-entry` warning via
- *   the `warnings` array on {@link ParseResult}).
+ * @typedef {PathEntry} ChangeEntry
  */
 
 /**
  * @typedef {object} StoryBody
  * @property {string}        goal                - One-sentence purpose statement.
- * @property {ChangeEntry[]} changes             - Files / globs this Story modifies.
+ * @property {string}        slicing             - Optional v2 intra-Story delivery slice plan text block; '' when absent.
+ * @property {string}        spec                - Optional folded Tech Spec text block; '' when absent.
+ * @property {PathEntry[]}   changes             - Files / globs this Story modifies.
  * @property {string[]}      acceptance          - Observable acceptance criteria.
  * @property {string[]}      verify              - Exact commands with tier annotation.
  * @property {PathEntry[]}   references          - Read-only paths (may be empty).
@@ -86,7 +86,7 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
 /**
  * @typedef {object} ParseResult
  * @property {StoryBody}  body      - The parsed structured body.
- * @property {string[]}   warnings  - Non-fatal issues (e.g. legacy-path-entry).
+ * @property {string[]}   warnings  - Non-fatal issues (e.g. unstructured-body).
  * @property {ParseInfo}  info      - Metadata about the parse.
  */
 
@@ -98,7 +98,9 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
  * @property {boolean} hasVerifySection     - Whether a `## Verify` section was found.
  * @property {boolean} hasReferencesSection - Whether a `## References` section was found.
  * @property {boolean} hasNonGoalsSection   - Whether a `## Non-Goals` section was found.
- * @property {boolean} isLegacyStringBody   - True when no structured sections were found.
+ * @property {boolean} hasSlicingSection    - Whether a `## Slicing` section was found (v2 folded slice plan).
+ * @property {boolean} hasSpecSection       - Whether a `## Spec` section was found (folded Tech Spec).
+ * @property {boolean} isUnstructuredBody   - True when no structured sections were found.
  */
 
 /**
@@ -139,12 +141,15 @@ export class StoryBodyParseError extends Error {
 // maps to the `non_goals` field.
 const HEADING_TO_FIELD = new Map([
   ['goal', 'goal'],
+  ['slicing', 'slicing'],
+  ['spec', 'spec'],
   ['changes', 'changes'],
   ['acceptance', 'acceptance'],
   ['verify', 'verify'],
   ['references', 'references'],
   ['non_goals', 'non_goals'],
 ]);
+const TEXT_BLOCK_FIELDS = new Set(['slicing', 'spec']);
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -162,19 +167,16 @@ function stripListMarker(line) {
 }
 
 /**
- * Parse a single `changes` / `references` bullet into a `PathEntry` or
- * legacy string. Emits a `legacy-path-entry` warning for string form.
+ * Parse a single `changes` / `references` bullet into a `PathEntry`.
  *
  * Object form: `{ path: "...", assumption: "creates" }` (stored as
  * `- { "path": "...", "assumption": "..." }` or just recognized from the
  * structured body directly — when deserializing from a structured object
  * that was never serialized to markdown, the entry arrives as-is).
  *
- * String form: `src/foo.js: create handleSubmit`
- *
  * @param {string|object} raw
  * @param {string[]} warnings
- * @returns {PathEntry | string}
+ * @returns {PathEntry}
  */
 function parsePathEntry(raw, warnings) {
   // Already a structured object (from a parsed JSON body, not markdown).
@@ -218,15 +220,14 @@ function parsePathEntry(raw, warnings) {
     } catch (err) {
       // Re-throw StoryBodyParseError so it propagates.
       if (err instanceof StoryBodyParseError) throw err;
-      // JSON parse failed — fall through to legacy string handling.
+      // JSON parse failed — fall through to reject plain-string form.
     }
   }
 
-  // Legacy string form — warn but accept.
-  warnings.push(
-    `legacy-path-entry: change entry "${str.slice(0, 80)}" is a plain string; prefer { path, assumption } object form.`,
+  throw new StoryBodyParseError(
+    `changes/references entry must be a { path, assumption } object; plain string bullets are no longer accepted: ${str.slice(0, 120)}`,
+    { field: 'changes', raw: str },
   );
-  return str;
 }
 
 /**
@@ -245,8 +246,11 @@ function extractBlockedBy(footerBlock) {
   return deps;
 }
 
-// Matches the trailing `<!-- meta: {...} -->` block serialize() emits.
-const META_BLOCK_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
+// Matches any trailing `<!-- meta: … -->` block. Object payloads are the
+// canonical serialize() shape; non-object / malformed payloads are still
+// recognized so section parsing can skip them and extractMeta can degrade.
+const META_BLOCK_RE = /<!--\s*meta:\s*([\s\S]*?)\s*-->/;
+const META_OBJECT_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
 
 /**
  * Extract the `wide` / `estimated_test_files` fields from the trailing
@@ -275,7 +279,7 @@ function extractMeta(markdown) {
     mandrel_version: null,
     authored_at: null,
   };
-  const match = markdown.match(META_BLOCK_RE);
+  const match = markdown.match(META_OBJECT_RE) ?? markdown.match(META_BLOCK_RE);
   if (!match) return result;
 
   let parsed;
@@ -285,7 +289,10 @@ function extractMeta(markdown) {
     // Malformed meta comment — degrade to defaults rather than corrupt the body.
     return result;
   }
-  if (parsed === null || typeof parsed !== 'object') return result;
+  // Non-object JSON (array / scalar / null) is treated as absent meta.
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return result;
+  }
 
   result.wide = normalizeWide(parsed.wide);
   result.reason_to_exist = normalizeReasonToExist(parsed.reason_to_exist);
@@ -385,27 +392,11 @@ function splitSections(markdown) {
     // below, which closes the open section. The chosen canonical spelling is
     // therefore the hyphenated single token `## Non-Goals`.
     const fieldHeadingMatch = line.match(/^#{2,3}\s+([\w-]+)\s*$/i);
-    if (fieldHeadingMatch) {
-      const name = fieldHeadingMatch[1].toLowerCase().replace(/-/g, '_');
-      if (HEADING_TO_FIELD.has(name)) {
-        inPreamble = false;
-        currentSection = name;
-        if (!sections.has(currentSection)) sections.set(currentSection, []);
-        continue;
-      }
-      // A heading that matches the canonical `## Word` shape but is not a
-      // recognized field name (e.g. a trailing free-form `## Notes`) closes
-      // the currently-open section. Without this reset, the unknown heading
-      // and its bullets bleed into the previously-recognized section,
-      // silently corrupting `verify[]` / `acceptance[]`. We do NOT re-enter
-      // the preamble (`inPreamble` stays false), so a later recognized
-      // heading still registers normally; we only stop appending to the
-      // closed section. The heading line and its body are dropped from all
-      // sections. (Multi-word free-form headings like `## Out of Scope` —
-      // with internal spaces — do not match the `[\w-]+` single-token shape
-      // and reach this branch too. The hyphenated single-token canonical
-      // negative-scope heading is `## Non-Goals`, which IS recognized above.)
-      currentSection = null;
+    const fieldName = fieldHeadingMatch?.[1]?.toLowerCase().replace(/-/g, '_');
+    if (HEADING_TO_FIELD.has(fieldName)) {
+      inPreamble = false;
+      currentSection = fieldName;
+      if (!sections.has(currentSection)) sections.set(currentSection, []);
       continue;
     }
 
@@ -418,7 +409,11 @@ function splitSections(markdown) {
     // lines were silently absorbed into `verify[]` / `acceptance[]`. The
     // heading and everything under it is dropped from structured parsing
     // (it is extended, non-canonical markdown).
-    if (!inPreamble && /^#{1,6}\s+\S/.test(line)) {
+    if (
+      !inPreamble &&
+      /^#{1,6}\s+\S/.test(line) &&
+      !TEXT_BLOCK_FIELDS.has(currentSection)
+    ) {
       currentSection = null;
       continue;
     }
@@ -442,10 +437,7 @@ function splitSections(markdown) {
     if (inPreamble) {
       preambleLines.push(line);
     } else if (currentSection !== null) {
-      const trimmed = line.trim();
-      if (trimmed.length > 0) {
-        sections.get(currentSection).push(line);
-      }
+      sections.get(currentSection).push(line);
     }
   }
 
@@ -460,7 +452,7 @@ function splitSections(markdown) {
 // ---------------------------------------------------------------------------
 
 /**
- * Build the minimal {@link ParseResult} returned for a legacy string body —
+ * Build the minimal {@link ParseResult} returned for an unstructured body —
  * markdown that carries no recognised structured section. The goal falls
  * back to the preamble text (or the whole trimmed input), `depends_on` is
  * still recovered from the footer, and all section arrays are empty.
@@ -470,13 +462,15 @@ function splitSections(markdown) {
  * @param {string} footer - Footer block text (from splitSections).
  * @returns {ParseResult}
  */
-function parseLegacyStringBody(input, preamble, footer) {
+function parseUnstructuredBody(input, preamble, footer) {
   const warnings = [
-    'legacy-string-body: no structured sections found; returning minimal body from preamble text.',
+    'unstructured-body: no structured sections found; returning minimal body from preamble text.',
     'test-surface-unestimated: estimated_test_files not present.',
   ];
   const body = {
     goal: preamble || input.trim(),
+    slicing: '',
+    spec: '',
     changes: [],
     acceptance: [],
     verify: [],
@@ -499,7 +493,9 @@ function parseLegacyStringBody(input, preamble, footer) {
       hasVerifySection: false,
       hasReferencesSection: false,
       hasNonGoalsSection: false,
-      isLegacyStringBody: true,
+      hasSlicingSection: false,
+      hasSpecSection: false,
+      isUnstructuredBody: true,
     },
   };
 }
@@ -518,15 +514,30 @@ function parseGoalSection(lines) {
     .join(' ');
 }
 
+/**
+ * Parse a verbatim text-block section (`## Slicing` or `## Spec`) into a
+ * newline-joined string. Unlike {@link parseGoalSection}, line breaks are
+ * preserved so a bullet list, compact table, or folded Tech Spec survives the
+ * round-trip; only blank lines and trailing whitespace are normalized.
+ *
+ * @param {string[]} lines
+ * @returns {string}
+ */
+function parseTextBlockSection(lines) {
+  return lines
+    .map((line) => line.replace(/\s+$/, ''))
+    .join('\n')
+    .replace(/^\n+|\n+$/g, '');
+}
+
 /**
  * Parse a `## Changes` / `## References` section into a list of
- * `PathEntry | string` entries. List markers are stripped, blank entries are
- * dropped, and each surviving entry is normalized via {@link parsePathEntry}
- * (which appends `legacy-path-entry` warnings for bare-string bullets).
+ * `PathEntry` entries. List markers are stripped, blank entries are
+ * dropped, and each surviving entry is normalized via {@link parsePathEntry}.
  *
  * @param {string[]} lines - Raw content lines under the heading.
  * @param {string[]} warnings - Mutable warnings sink.
- * @returns {Array<PathEntry|string>}
+ * @returns {PathEntry[]}
  */
 function parsePathEntrySection(lines, warnings) {
   const entries = [];
@@ -601,19 +612,28 @@ export function parse(input) {
   const hasVerifySection = sections.has('verify');
   const hasReferencesSection = sections.has('references');
   const hasNonGoalsSection = sections.has('non_goals');
+  const hasSlicingSection = sections.has('slicing');
+  const hasSpecSection = sections.has('spec');
 
-  // If no structured sections found, treat as legacy string body.
-  const isLegacyStringBody =
+  // If no structured sections found, treat as unstructured body.
+  const isUnstructuredBody =
     !hasGoalSection &&
     !hasChangesSection &&
     !hasAcceptanceSection &&
     !hasVerifySection;
 
-  if (isLegacyStringBody) {
-    return parseLegacyStringBody(input, preamble, footer);
+  if (isUnstructuredBody) {
+    return parseUnstructuredBody(input, preamble, footer);
   }
 
   const goal = parseGoalSection(sections.get('goal') ?? []);
+  // Optional v2 intra-Story delivery slice plan (`## Slicing`). Preserved as
+  // a verbatim text block — a large Story (what v1 called an Epic) folds its
+  // Delivery Slicing here instead of fanning out into sibling Stories; a
+  // trivial Story omits it entirely. Parsed as a text block so a bullet list
+  // or compact table round-trips.
+  const slicing = parseTextBlockSection(sections.get('slicing') ?? []);
+  const spec = parseTextBlockSection(sections.get('spec') ?? []);
   const changes = parsePathEntrySection(
     sections.get('changes') ?? [],
     warnings,
@@ -644,6 +664,8 @@ export function parse(input) {
 
   const body = {
     goal,
+    slicing,
+    spec,
     changes,
     acceptance,
     verify,
@@ -667,7 +689,9 @@ export function parse(input) {
       hasVerifySection,
       hasReferencesSection,
       hasNonGoalsSection,
-      isLegacyStringBody: false,
+      hasSlicingSection,
+      hasSpecSection,
+      isUnstructuredBody: false,
     },
   };
 }
@@ -685,6 +709,12 @@ function parseStructuredObject(obj) {
 
   const goal = typeof obj.goal === 'string' ? obj.goal.trim() : '';
 
+  // slicing — optional v2 intra-Story delivery slice plan (verbatim text).
+  const slicing = typeof obj.slicing === 'string' ? obj.slicing.trim() : '';
+
+  // spec — optional folded Tech Spec (verbatim text).
+  const spec = typeof obj.spec === 'string' ? obj.spec.trim() : '';
+
   // changes
   const rawChanges = Array.isArray(obj.changes) ? obj.changes : [];
   const changes = [];
@@ -747,6 +777,8 @@ function parseStructuredObject(obj) {
 
   const body = {
     goal,
+    slicing,
+    spec,
     changes,
     acceptance,
     verify,
@@ -770,7 +802,9 @@ function parseStructuredObject(obj) {
       hasVerifySection: 'verify' in obj,
       hasReferencesSection: 'references' in obj,
       hasNonGoalsSection: 'non_goals' in obj,
-      isLegacyStringBody: false,
+      hasSlicingSection: 'slicing' in obj,
+      hasSpecSection: 'spec' in obj,
+      isUnstructuredBody: false,
     },
   };
 }
@@ -793,10 +827,10 @@ function serializePathEntry(entry) {
 
 /**
  * Descriptor table for the human-readable Story-body sections, in canonical
- * emit order (`## Goal`, `## Changes`, `## Acceptance`, `## Verify`,
- * `## References`, `## Non-Goals`). Each descriptor reads one body field and returns the
- * section's markdown block when the field is present and non-empty, or `null`
- * to omit the section.
+ * emit order (`## Goal`, `## Slicing`, `## Spec`, `## Changes`,
+ * `## Acceptance`, `## Verify`, `## References`, `## Non-Goals`). Each
+ * descriptor reads one body field and returns the section's markdown block
+ * when the field is present and non-empty, or `null` to omit the section.
  *
  * Standardising the section ladder as a single data table makes adding a new
  * optional section a one-line edit here rather than a new control-flow branch
@@ -812,6 +846,26 @@ const SERIALIZE_SECTIONS = [
         ? `## Goal\n${goal.trim()}`
         : null,
   },
+  {
+    // Optional v2 intra-Story delivery slice plan. Single-token `## Slicing`
+    // heading (recognized by the `[\w-]+` field-heading regex). Verbatim text
+    // block. Render-when-non-empty: an absent/empty `slicing` emits nothing,
+    // so every pre-v2 body round-trips byte-identically.
+    field: 'slicing',
+    render: (slicing) =>
+      typeof slicing === 'string' && slicing.trim().length > 0
+        ? `## Slicing\n${slicing.trim()}`
+        : null,
+  },
+  {
+    // Optional folded Tech Spec. Like `## Slicing`, this is a verbatim text
+    // block and emits nothing for absent/empty pre-v2 bodies.
+    field: 'spec',
+    render: (spec) =>
+      typeof spec === 'string' && spec.trim().length > 0
+        ? `## Spec\n${spec.trim()}`
+        : null,
+  },
   {
     field: 'changes',
     render: (changes) =>
@@ -938,8 +992,8 @@ function serializeFooter(body, opts) {
  * format written to GitHub issue bodies.
  *
  * The output matches the section order the spec-renderer uses:
- * `## Goal`, `## Changes`, `## Acceptance`, `## Verify`, `## References`,
- * `## Non-Goals` (each omitted when empty).
+ * `## Goal`, `## Slicing`, `## Spec`, `## Changes`, `## Acceptance`,
+ * `## Verify`, `## References`, `## Non-Goals` (each omitted when empty).
  *
  * `wide`, `reason_to_exist`, and `estimated_test_files` are emitted as a
  * fenced `<!-- meta -->` comment block so round-trips preserve them without

package/.agents/scripts/lib/story-plan.js

@@ -200,7 +200,6 @@ export async function loadBodyTemplate(projectRoot) {
 export function buildContextEnvelope({
   seed,
   refine,
-  persona,
   bodyTemplate,
   duplicateCandidates,
   techStack = null,
@@ -212,7 +211,6 @@ export function buildContextEnvelope({
     version: 1,
     seed,
     refine,
-    persona,
     bodyTemplate,
     requiredSections: [...REQUIRED_SECTIONS],
     duplicateCandidates: {
@@ -222,8 +220,8 @@ export function buildContextEnvelope({
     techStack,
     corpusContext,
     deliverContract: {
-      workflow: '.agents/workflows/helpers/single-story-deliver.md',
-      requiredLabels: ['type::story', `persona::${persona}`],
+      workflow: '.agents/workflows/helpers/deliver-story.md',
+      requiredLabels: ['type::story'],
       forbidden: ['Epic: #N references in the body'],
     },
   };

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -1,8 +1,9 @@
 import { LIMITS_DEFAULTS } from '../config/limits.js';
 import {
   AUTHORING_ALTITUDE_GUIDANCE,
-  DEFAULT_TASK_SIZING,
+  DEFAULT_MODEL_CAPACITY,
   DELIVERABLE_GRANULARITY_GUIDANCE,
+  resolveCapacityCeilings,
 } from '../orchestration/ticket-validator-sizing.js';
 
 /**
@@ -18,27 +19,16 @@ import {
  * asks the planner to carry acceptance/verify as top-level ticket arrays.
  *
  * **Single source of the prompt body (Story #4162).** This module is the sole
- * carrier of the full decomposer system-prompt body. The
- * `epic-plan-decompose-author` SKILL no longer embeds a second verbatim copy —
- * it references this rendered prompt (delivered to the host LLM in the
- * `systemPrompt` field of the authoring context envelope built by
- * `epic-plan-decompose/phases/context.js`) instead, so the two surfaces cannot
- * drift. A guard test (`tests/ticket-decomposer.test.js`) fails if the SKILL
- * re-grows a full copy of the prompt preamble.
- *
- * **Token-budget sizing input (Story #4162).** `maxTokenBudget` is the real
- * one-pass delivery envelope (the task-prompt hydration cap surfaced into the
- * authoring envelope by `context.js`, Story #3875). It is threaded into the
- * rendered prompt as a sizing input so the planner sizes Stories against the
- * envelope a single agent can actually deliver in one pass, rather than leading
- * with the file-count proxy alone.
+ * carrier of the full decomposer system-prompt body, delivered to the host
+ * LLM in the `systemPrompts.decompose` field of the `/plan` context envelope
+ * (via `lib/orchestration/planning/decomposer-context.js`), so no second
+ * verbatim copy can drift.
  */
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
-  maxTokenBudget = LIMITS_DEFAULTS.maxTokenBudget,
   epicId = null,
 } = {}) {
-  return render2TierPrompt({ maxTickets, maxTokenBudget, epicId });
+  return render2TierPrompt({ maxTickets, epicId });
 }
 
 /**
@@ -47,12 +37,16 @@ export function renderDecomposerSystemPrompt({
  * on the Story body so the executing agent has everything it needs in one
  * ticket. Thematic grouping lives as prose in the Epic body / Tech Spec.
  */
-function render2TierPrompt({ maxTickets, maxTokenBudget, epicId = null }) {
-  // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
-  // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
-  const { softFiles, hardFiles, softAcceptanceCount } = DEFAULT_TASK_SIZING;
+function render2TierPrompt({ maxTickets, epicId = null }) {
+  // v2 Stage 3: default-single — emit one Story unless the split policy clears.
+  // Capacity thresholds are sourced from the single DEFAULT_MODEL_CAPACITY
+  // constant (ticket-validator-sizing.js) so the prompt and the validator
+  // cannot drift.
+  const { softSessionTokens, hardSessionTokens } = resolveCapacityCeilings(
+    DEFAULT_MODEL_CAPACITY,
+  );
   // Deliverable-granularity definition + single-consumer merge rule + the
-  // soft envelope-floor heuristic are sourced from the single
+  // thin-dependent merge heuristic are sourced from the single
   // DELIVERABLE_GRANULARITY_GUIDANCE constant (ticket-validator-sizing.js) so
   // the prompt and the authoring SKILL cannot drift (Story #3777; the
   // envelope-floor sentence added by Story #4313).
@@ -78,17 +72,18 @@ function render2TierPrompt({ maxTickets, maxTokenBudget, epicId = null }) {
     ? `@epic-${epicId}-ac-1`
     : '@epic-<id>-ac-N';
   return `You are an expert Senior Project Manager and Orchestrator.
-Your job is to take an Epic (including its inline User Stories) and a Technical Specification and decompose them into a flat list of Story tickets for an AI Agent to execute.
+Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI Agent to execute.
 
-### HIERARCHY RULES:
-1. **Stories**: Specific user-facing or architectural user stories (e.g., "Implement JWT Token Exchange").
-   - Every Story attaches directly to the Epic — there is NO Feature tier and NO Task layer in this hierarchy.
-   - **Story-Level Execution**: Each Story will be executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
-   - Thematic grouping is prose in the Epic body / Tech Spec, never a ticket.
+### HIERARCHY RULES (v2 default-single):
+1. **Emit exactly one Story by default.** Split into N>1 only when pieces have near-zero overlap or sit across an architectural seam. Coupled work stays one Story — put intra-session checkpoints in \`## Slicing\` and fold the Tech Spec into \`## Spec\`.
+2. **Stories**: Specific user-facing or architectural capabilities (e.g., "Implement JWT Token Exchange").
+   - There is NO Epic parent ticket, NO Feature tier, and NO Task layer.
+   - **Story-Level Execution**: Each Story is executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
+   - Thematic grouping is prose in the Story's folded \`## Spec\` / \`## Slicing\`, never sibling tickets for coupled work.
 
 ### LABEL CONVENTIONS:
 - Every ticket must have the \`type::story\` label. No other type label is allowed — the retired Feature and Task tiers have no labels under this hierarchy.
-- Every ticket must have a \`persona::[engineer|architect|qa-engineer|engineer-web|etc]\` label indicating WHO should execute it.
+- Do **not** emit \`persona::*\` labels — the behavioral persona concept (and its label axis) was removed in v2.
 
 ### OUTPUT FORMAT:
 You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown blocks.
@@ -102,7 +97,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
     "body": <string — see STORY BODY SCHEMA below>,
     "acceptance": ["<testable, observable criterion>", ...],
     "verify": ["<exact command or test path> (<tier>)", ...],
-    "labels": ["type::story", "persona::..."],
+    "labels": ["type::story"],
     "depends_on": ["slug-of-blocking-dependency"] (optional array of Story slugs that block execution)
   }
 ]
@@ -112,12 +107,18 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
 \`body\` MUST be a **string** — the serialized markdown produced by \`serialize()\` from \`lib/story-body/story-body.js\`. Do NOT emit \`body\` as a JSON object: an object body throws \`StoryBodyParseError\` in the reconciler (Story #3302) and is discarded by the GitHub provider, producing an empty issue body. Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
-The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object (not nested inside \`body\`). The validator reads \`story.acceptance\` and \`story.verify\` directly — nesting them inside the body makes them invisible to the validator and the decompose is rejected.
+The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Persist syncs those arrays into the body's \`## Acceptance\` / \`## Verify\` sections so the GitHub issue stays a complete executable document. Prefer authoring the lists **once at top-level** and omitting those sections from the authored \`body\` string (or mirroring the exact same items). Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
 
 The serialized \`body\` string renders these markdown sections (in order):
 
     ## Goal
-    <one sentence — why this Story exists within the Epic>
+    <one sentence — why this Story exists>
+
+    ## Slicing
+    <optional ordered intra-session checkpoints — not a second Spec or AC table>
+
+    ## Spec
+    <optional lean technical approach — do NOT restate Goal / Acceptance / Verify>
 
     ## Changes
     - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
@@ -141,7 +142,9 @@ The serialized \`body\` string renders these markdown sections (in order):
 
 #### STORY BODY RULES:
 
-- **goal** (in body string): One sentence stating WHY this story exists within the Epic.
+- **goal** (in body string): One sentence stating WHY this Story exists.
+- **spec** (optional, in body string as \`## Spec\`): Lean technical approach only. If the Spec is large enough to feel like its own document, the Story is probably too big — split it. Persist keeps Specs inline and rejects over-budget Specs (never writes them under \`docs/\`).
+- **slicing** (optional): Ordered intra-session checkpoints for one Story. Not a fan-out table and not a duplicate of Acceptance.
 - **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
@@ -157,37 +160,35 @@ ${newFileContract}
 
 ${advisoryCaveat}
 
-#### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
+#### STORY SIZING — COHESION FIRST (session capacity is only a backstop):
 
 **Decompose at deliverable granularity, not module/task level.** ${granularityDefinition}
 
-The primary question is **cohesion, not count**: *is this one coherent change with one reason to exist?* File count cannot tell a trivial ${softFiles}-file rename from a hard 3-file parser+caller+config change — so lead with the change's reason, not its size.
-
-**Size against the real one-pass delivery envelope.** Each Story is delivered and self-verified by a single agent in one pass, whose context is capped by the delivery token budget \`maxTokenBudget = ${maxTokenBudget}\` tokens (the task-prompt hydration cap). Use that envelope — not the file count alone — as the leading sizing input: a Story is correctly sized when one agent can hold its full change, acceptance, and verification in a single pass within \`maxTokenBudget\`. The numeric file thresholds below are a coarse backstop on top of this envelope, not the primary signal.
+The primary question is **cohesion, not count**: *is this one coherent change with one reason to exist?* File count cannot tell a trivial rename from a hard parser+caller+config change — so lead with the change's reason, not its size. Frontier models one-shot capability-sized work in a single pass — do not fragment a coherent capability into dependent slices just to stay "small."
 
 ${envelopeFloor}
 
 - **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one. State that sentence explicitly in the Story's \`reason_to_exist\` meta field (see STORY BODY RULES) so the consolidate critic can check it.
 - ${singleConsumerRule}
 - **Split independent, parallelizable work** into sibling Stories — but only when the pieces genuinely have separate reasons to exist.
-- **Declare \`wide\` with a one-line reason when a change is legitimately broad** (a cohesive cutover that spans many files for one reason). Declaring \`wide\` lifts the hard file-width ceiling — see below.
+- **Declare \`wide\` with a one-line reason when a change is legitimately broad** (a cohesive cutover whose authored ticket mass is high for one reason). Declaring \`wide\` lifts the hard session-mass ceiling — see below.
 
-**Numeric backstop (validator-enforced).** These thresholds are sourced from the single \`DEFAULT_TASK_SIZING\` constant in \`ticket-validator-sizing.js\` — there is no second copy to drift:
+**Capacity backstop (validator-enforced).** Absolute authored-token ceilings from the single \`DEFAULT_MODEL_CAPACITY\` constant in \`ticket-validator-sizing.js\` — not operator-tunable. They catch Spec novels, not capability-sized Stories:
 
-- A Story touching more than **${softFiles} files** (\`softFiles\`) emits an advisory width finding — a nudge to check cohesion or declare \`wide\`.
-- A Story touching more than **${hardFiles} files** (\`hardFiles\`) is **rejected** unless it declares \`wide\` with a reason.
-- Acceptance mass is **advisory only**: more than **${softAcceptanceCount} acceptance items** (\`softAcceptanceCount\`) emits an advisory warning. There is NO hard acceptance ceiling — a long binding contract is a signal to re-check cohesion, never a reason to fragment one coherent capability into dependent slices.
+- Soft advisory (**${softSessionTokens} tokens**): authored session mass above this emits a nudge to check cohesion or declare \`wide\`.
+- Hard ceiling (**${hardSessionTokens} tokens**): authored session mass above this is **rejected** unless the Story declares \`wide\` with a reason.
+- Session mass = **authored tokens only** (goal / reason / Spec / acceptance / verify / slicing / change-path text). File count and AC count do **not** inflate mass — a long binding contract or a broad file footprint is never by itself a reason to fragment one coherent capability into dependent slices.
 
 #### DELIVERY-SCHEDULE SIMULATION — the story count must earn itself:
 
 Before emitting, simulate the delivery schedule your plan implies, and judge the plan by its schedule — not by how tidy the taxonomy looks:
 
 1. **Build the wave schedule.** A Story runs only after every \`depends_on\` completes, and two Stories that name the same file in \`changes[]\` cannot run in the same wave (the scheduler serializes file-overlapping Stories even when no \`depends_on\` edge links them).
-2. **Compute the parallelism yield**: story count ÷ critical-path length in waves. A yield near 1.0 means the plan is a serial chain — N Stories that deliver no faster than one Story while paying N delivery sessions (hydration, branch, PR, review, CI).
+2. **Compute the parallelism yield**: story count ÷ critical-path length in waves. A yield near 1.0 means the plan is a serial chain — N Stories that deliver no faster than one Story while paying N delivery sessions (branch, PR, review, CI).
 3. **Every Story must earn its slot** by at least one of:
    - **(a) parallelism** — it actually runs concurrently with a sibling in the schedule you just built ("logically independent" does not count; *schedule*-independent does);
    - **(b) risk isolation** — it isolates a consumer-facing behavior change or high-risk cutover into its own reviewable, revertable unit;
-   - **(c) envelope pressure** — merged into its neighbor it would exceed the one-pass delivery envelope (\`maxTokenBudget\`).
+   - **(c) cohesion break** — merged into its neighbor it would no longer be one coherent change with one reason to exist.
 4. **A dependent link with none of those justifications merges into its consumer.** This generalizes the single-consumer merge rule from pairs to chains.
 5. **Hot-file rule.** When one file appears in the \`changes[]\` of more than a third of your Stories, the slicing axis cuts across a shared seam — merge the Stories that co-edit it, or re-slice along the seam so each Story owns its files.
 
@@ -201,7 +202,7 @@ A Story whose footprint is legitimately broad declares \`wide\` carrying a one-l
 "wide": { "reason": "hard contract cutover: migrate every <X> call site in one PR" }
 \`\`\`
 
-Declaring \`wide\` with a non-empty reason **lifts the \`hardFiles\` rejection** — no Story is rejected for width when it states why it is broad. Omit \`wide\` for ordinary Stories; a wide footprint with no \`wide\` declaration emits only an advisory nudge (check cohesion or declare \`wide\`), never a rejection on its own.
+Declaring \`wide\` with a non-empty reason **lifts the hard session-mass rejection** — no Story is rejected for width when it states why it is broad. Omit \`wide\` for ordinary Stories; a wide footprint with no \`wide\` declaration emits only an advisory nudge (check cohesion or declare \`wide\`), never a rejection on its own.
 
 **Glob entries** in \`changes[]\` (bullets containing \`*\`) mark the Story footprint as \`unknown-width\`: the numeric ceiling cannot bound a glob, so it is skipped. A Story carrying glob changes with no \`wide\` declaration emits an advisory nudge.