mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/presentation/manifest-builder.js

@@ -9,19 +9,19 @@
  * Extracted from `manifest-formatter.js` (Story #1849 Task #1869). The
  * shape projection used to be inlined in the formatter; pulling it out
  * isolates the spec → manifest projection from the Markdown renderer and
- * lets the per-feature / per-story guard cascade live behind a single
+ * lets the per-story guard cascade live behind a single
  * private predicate (`validateSpecShape`) so the orchestrator function's
  * CRAP score drops below 12.
  *
- * Story #3413 (3-tier cutover, final): the residual per-Task projection
+ * Story #3413 (2-tier cutover, final): the residual per-Task projection
  * (the Task projector, the per-Story Task array, and the Task-count
- * rollup) has been deleted. The walker (`projectFeatures`) now counts
+ * rollup) has been deleted. The walker (`projectStories`) counts
  * Stories directly, and `summary` carries Story-tier counts only
  * (`totalStories` / `doneStories` / `progressPercent`), matching the
  * canonical producer in `lib/orchestration/manifest-builder.js`.
  *
  * Story-level status surfaces on each `storyEntry.status` so downstream
- * renderers read the Story's own `agent::*` label directly — the 3-tier
+ * renderers read the Story's own `agent::*` label directly — the
  * "Stories are first-class lifecycle units" invariant.
  *
  * No fs / network access; pure transform. Caller supplies `state` from
@@ -38,8 +38,7 @@ import { AGENT_LABELS } from '../label-constants.js';
  * "is this thing iterable / object-shaped?" decisions.
  *
  * `level` describes which spec node we are validating:
- *   - `'features'` → the spec-level `features` array
- *   - `'stories'`  → a feature's `stories` array
+ *   - `'stories'`  → the spec-level `stories` array
  *   - `'story'`    → a single Story object (must be a non-null object)
  *
  * Returns `true` when the node satisfies the shape contract for that
@@ -52,7 +51,6 @@ import { AGENT_LABELS } from '../label-constants.js';
  */
 function validateSpecShape(level, value) {
   switch (level) {
-    case 'features':
     case 'stories':
       return Array.isArray(value);
     case 'story':
@@ -102,8 +100,8 @@ function buildResolvers(state) {
  * Private: project a single spec Story into a manifest Story entry. The
  * Story's status is resolved directly from the Story-level label
  * (`state.mapping[slug].lastObservedAgentState`) and surfaces on
- * `storyEntry.status` — under the 3-tier hierarchy Stories carry their
- * own lifecycle state and are leaves with no child Task tickets. Caller
+ * `storyEntry.status` — Stories carry their own lifecycle state and are
+ * leaves with no child tickets. Caller
  * filters non-object stories with `validateSpecShape('story', ...)`
  * before invoking.
  *
@@ -129,16 +127,17 @@ function projectStory(story, resolvers) {
 }
 
 /**
- * Private: walk every feature → story pair in a spec and collect the
- * per-story projections + Story-tier roll-up counters. Keeps the loop
- * machinery out of `buildManifestFromSpec` so the entry point reads as a
- * straight assembly of the result envelope.
+ * Private: walk every Story in a spec and collect the per-story
+ * projections + Story-tier roll-up counters. Keeps the loop machinery
+ * out of `buildManifestFromSpec` so the entry point reads as a straight
+ * assembly of the result envelope.
  *
- * Under the 3-tier hierarchy (Epic #3163) Stories are leaves, so the
- * rollup counts Stories directly: `totalStories` is every projected
- * Story and `doneStories` is the subset carrying `agent::done`.
+ * Under the 2-tier hierarchy (Story #4041) Stories are direct Epic
+ * children and leaves, so the rollup counts Stories directly:
+ * `totalStories` is every projected Story and `doneStories` is the
+ * subset carrying `agent::done`.
  *
- * @param {object[]} features
+ * @param {object[]} stories
  * @param {{ resolveId: Function, resolveStatus: Function }} resolvers
  * @returns {{
  *   storyManifest: object[],
@@ -147,23 +146,18 @@ function projectStory(story, resolvers) {
  *   waveSet: Set<number>,
  * }}
  */
-function projectFeatures(features, resolvers) {
+function projectStories(stories, resolvers) {
   const storyManifest = [];
   let totalStories = 0;
   let doneStories = 0;
   const waveSet = new Set();
-  for (const feature of features) {
-    const stories = validateSpecShape('stories', feature?.stories)
-      ? feature.stories
-      : [];
-    for (const story of stories) {
-      if (!validateSpecShape('story', story)) continue;
-      const { storyEntry, wave } = projectStory(story, resolvers);
-      storyManifest.push(storyEntry);
-      totalStories++;
-      if (storyEntry.status === AGENT_LABELS.DONE) doneStories++;
-      if (wave >= 0) waveSet.add(wave);
-    }
+  for (const story of stories) {
+    if (!validateSpecShape('story', story)) continue;
+    const { storyEntry, wave } = projectStory(story, resolvers);
+    storyManifest.push(storyEntry);
+    totalStories++;
+    if (storyEntry.status === AGENT_LABELS.DONE) doneStories++;
+    if (wave >= 0) waveSet.add(wave);
   }
   return { storyManifest, totalStories, doneStories, waveSet };
 }
@@ -199,12 +193,12 @@ export function buildManifestFromSpec(spec, opts = {}) {
     spec?.epic && typeof spec.epic.id === 'number' ? spec.epic.id : null;
   const epicTitle =
     spec?.epic && typeof spec.epic.title === 'string' ? spec.epic.title : '';
-  const features = validateSpecShape('features', spec?.features)
-    ? spec.features
+  const stories = validateSpecShape('stories', spec?.stories)
+    ? spec.stories
     : [];
 
-  const { storyManifest, totalStories, doneStories, waveSet } = projectFeatures(
-    features,
+  const { storyManifest, totalStories, doneStories, waveSet } = projectStories(
+    stories,
     resolvers,
   );
 

package/.agents/scripts/lib/presentation/manifest-formatter.js

@@ -144,7 +144,6 @@ function renderManifestHeader(manifest) {
 
 /**
  * Private: emit the Wave Summary table plus the per-wave H2 sections.
- * Filters Feature containers out of the wave-eligible set.
  *
  * @param {object} manifest
  * @returns {string[]}
@@ -155,7 +154,7 @@ function renderManifestBody(manifest) {
     manifest.stories ||
     manifest.summary?.stories ||
     [];
-  const waveEligible = allItems.filter((s) => s.type !== 'feature');
+  const waveEligible = allItems;
   const lines = [];
   const waveBlock = renderWaveSections(waveEligible);
   if (waveBlock) lines.push(waveBlock);
@@ -165,7 +164,7 @@ function renderManifestBody(manifest) {
     if (nestedBlock) lines.push(nestedBlock);
   }
   // Cross-Story concurrency hazards block — only emitted when the caller
-  // attaches `concurrencyFindings` to the manifest (i.e. `/epic-plan`
+  // attaches `concurrencyFindings` to the manifest (i.e. `/plan`
   // Phase 9 dispatcher dry-run forwards the validator's findings array).
   // Absent for live progress-reporter manifests where the block would
   // duplicate Story-level state already shown above.
@@ -178,7 +177,7 @@ function renderManifestBody(manifest) {
 
 /**
  * Private: emit the agent-telemetry trailer (friction count + recent
- * friction list) when the manifest carries one. Under the 3-tier
+ * friction list) when the manifest carries one. Under the 2-tier
  * hierarchy (Epic #3163) friction records are Story-scoped, so each
  * recent-friction item is keyed by its `storyId`.
  *

package/.agents/scripts/lib/presentation/manifest-helpers.js

@@ -8,7 +8,7 @@
  * re-exports every name here so existing call-sites' import paths stay
  * unchanged.
  *
- * Post-3-tier (Story #3194 / #3413, Epic #3163): the helpers consume the
+ * Post-2-tier (Story #3194 / #3413, Epic #3163): the helpers consume the
  * Story-only manifest shape. Stories carry their lifecycle state on a
  * top-level `status` field (the parent Story's `agent::*` label) — the
  * old per-Story Task array, the per-Task id indirection, and the

package/.agents/scripts/lib/presentation/manifest-procedures.js

@@ -16,7 +16,7 @@
  * the only HTML the manifest emits by AC — every other section is plain
  * Markdown.
  *
- * @param {number|string} epicId  the Epic id used to substitute `/epic-deliver` examples.
+ * @param {number|string} epicId  the Epic id used to substitute `/deliver` examples.
  * @returns {string}
  */
 export function renderProceduresAndLegendDetails(epicId) {
@@ -28,13 +28,13 @@ export function renderProceduresAndLegendDetails(epicId) {
   lines.push('### Operating Procedures');
   lines.push('');
   lines.push(
-    `1. **Deliver**: Run \`/epic-deliver ${epicId}\`. The runner iterates waves in order, fans Stories out in parallel via \`/story-deliver\`, and only pauses when the Epic flips to \`agent::blocked\`.`,
+    `1. **Deliver**: Run \`/deliver ${epicId}\`. The runner iterates waves in order, fans Stories out in parallel via \`/deliver\`, and only pauses when the Epic flips to \`agent::blocked\`.`,
   );
   lines.push(
-    '2. **Resume (granular, optional)**: Re-running `/epic-deliver` resumes from the checkpointed wave. To re-drive a single Story, run `/story-deliver <storyId>`. Re-runs are checkpoint-idempotent.',
+    '2. **Resume (granular, optional)**: Re-running `/deliver` resumes from the checkpointed wave. To re-drive a single Story, run `/deliver <storyId>`. Re-runs are checkpoint-idempotent.',
   );
   lines.push(
-    `3. **Close**: \`/epic-deliver ${epicId}\` runs close-validation, code-review, retro, and PR-create in its tail. Operators merge the PR via the GitHub UI.`,
+    `3. **Close**: \`/deliver ${epicId}\` runs close-validation, code-review, retro, and PR-create in its tail. Operators merge the PR via the GitHub UI.`,
   );
   lines.push('');
   lines.push('### Symbol legend');

package/.agents/scripts/lib/presentation/manifest-render-waves.js

@@ -3,7 +3,7 @@
  *
  * Presentation-only: emits the per-wave `## <emoji> Wave N` H2 sections
  * (with nested per-Story H3 headings) that sit beneath the Wave Summary
- * table in the dispatch manifest. Under the 3-tier hierarchy (Epic
+ * table in the dispatch manifest. Under the 2-tier hierarchy (Epic
  * #3163) Stories are leaves with no child Task tickets, so each wave
  * counts Stories (done/total) and renders one H3 per Story. The TOC
  * links emitted by `renderWaveSections` jump directly into the H2
@@ -85,7 +85,7 @@ function pickWaveTail(status, waveIdx, sortedWaves, storyCount) {
 /**
  * Group Stories into per-wave buckets and accumulate per-wave Story
  * totals. Pure helper — keeps the bookkeeping outside the main render
- * loop. Under the 3-tier hierarchy (Epic #3163) Stories are leaves with
+ * loop. Under the 2-tier hierarchy (Epic #3163) Stories are leaves with
  * no child Task tickets, so each wave's `total` / `done` counts Stories
  * (a Story is "done" when it carries `agent::done`) — the unit
  * `deriveWaveStatus` consumes.
@@ -122,11 +122,8 @@ export function renderNestedWaveSections(storyManifest) {
   if (!validateWaveSection('storyManifest', storyManifest)) return '';
   if (storyManifest.length === 0) return '';
 
-  const waveStories = storyManifest.filter(
-    (s) => validateWaveSection('story', s) && s.type !== 'feature',
-  );
-  const featureItems = storyManifest.filter(
-    (s) => validateWaveSection('story', s) && s.type === 'feature',
+  const waveStories = storyManifest.filter((s) =>
+    validateWaveSection('story', s),
   );
 
   const { waveGroups, waveStats } = groupStoriesByWave(waveStories);
@@ -158,22 +155,6 @@ export function renderNestedWaveSections(storyManifest) {
     }
   }
 
-  if (featureItems.length > 0) {
-    lines.push('## Feature Containers');
-    lines.push('');
-    lines.push(
-      '> Features are organizational groupings and are **not directly executable**.',
-    );
-    lines.push('> Execute the Stories within each Feature instead.');
-    lines.push('');
-    lines.push('| Feature | Title |');
-    lines.push('| :--- | :--- |');
-    for (const f of featureItems) {
-      lines.push(`| #${f.storyId} | ${f.storySlug} |`);
-    }
-    lines.push('');
-  }
-
   return lines.join('\n');
 }
 

package/.agents/scripts/lib/presentation/manifest-renderer.js

@@ -139,7 +139,7 @@ export async function postParkedFollowOnsComment(manifest, provider) {
 
   const storyManifest = manifest.storyManifest ?? [];
   const manifestStoryIds = storyManifest
-    .filter((s) => s.type !== 'feature' && s.storyId !== '__ungrouped__')
+    .filter((s) => s.storyId !== '__ungrouped__')
     .map((s) => Number(s.storyId))
     .filter((n) => Number.isFinite(n));
 

package/.agents/scripts/lib/presentation/manifest-story-views.js

@@ -83,9 +83,7 @@ export function printStoryDispatchTable(storyManifest, opts = {}) {
   const log = opts.logger?.log ?? ((line) => Logger.info(line));
   if (!storyManifest || storyManifest.length === 0) return;
 
-  // Split into wave-eligible Stories and Feature containers
-  const stories = storyManifest.filter((s) => s.type !== 'feature');
-  const features = storyManifest.filter((s) => s.type === 'feature');
+  const stories = storyManifest;
 
   log('\n┌─────────┬──────────────────────────────────────┬──────┐');
   log('│                  📋 STORY DISPATCH TABLE                 │');
@@ -106,14 +104,7 @@ export function printStoryDispatchTable(storyManifest, opts = {}) {
   log('└─────────┴──────────────────────────────────────┴──────┘');
   log('');
   log('  💡 Stories in the same [Wave] can be executed in parallel.');
-  log('  💡 Use /epic-deliver #[Story ID] to execute a Story.');
+  log('  💡 Use /deliver #[Story ID] to execute a Story.');
 
-  if (features.length > 0) {
-    log('');
-    log('  📦 Feature Containers (not directly executable):');
-    for (const f of features) {
-      log(`     #${f.storyId} — ${f.storySlug}`);
-    }
-  }
   log('');
 }

package/.agents/scripts/lib/project-root.js

@@ -0,0 +1,17 @@
+/**
+ * lib/project-root.js — side-effect-free leaf module for the repository
+ * root path.
+ *
+ * Extracted from `config-resolver.js` (Story #3993) so the ~10 importers
+ * that need only the path constant no longer transitively load the
+ * stateful config subsystem (module-global caches + `.env` load side
+ * effect). `config-resolver.js` re-exports this constant, so its barrel
+ * surface is unchanged.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// scripts/lib/ → scripts/ → .agents/ → project root
+export const PROJECT_ROOT = path.resolve(__dirname, '../../..');

package/.agents/scripts/lib/signals/schema.js

@@ -98,7 +98,7 @@ export const EVENT_KINDS = Object.freeze({
   // Story #3819 — per-criterion acceptance self-eval signal emitted by
   // acceptance-eval.js. One record per Story per eval-loop terminus,
   // carrying which acceptance items needed rework and the round count, so
-  // the retro and /epic-plan Phase 0 feedback fetch can see acceptance
+  // the retro and /plan Phase 0 feedback fetch can see acceptance
   // churn alongside friction/hotspot data.
   ACCEPTANCE_EVAL: 'acceptance-eval',
 });

package/.agents/scripts/lib/spec/index.js

@@ -2,7 +2,7 @@
  * lib/spec/index.js — public surface for the spec I/O module.
  *
  * Re-exports the loader (and, in Wave 1, future spec utilities) so
- * downstream consumers — the reconciler, the rewritten /epic-plan, the
+ * downstream consumers — the reconciler, the rewritten /plan, the
  * wave-runner — can `import * from '../lib/spec/index.js'` without
  * reaching into individual submodules.
  *

package/.agents/scripts/lib/spec/loader.js

@@ -8,7 +8,7 @@
  *   - `temp/epic-<epic-id>/<epic-id>.state.json`  — slug→issue mapping (observed)
  *
  * Both files live under the per-Epic ephemeral tree `temp/epic-<id>/`
- * (already gitignored) so /epic-plan reruns don't churn a tracked path
+ * (already gitignored) so /plan reruns don't churn a tracked path
  * and so concurrent Epics never collide on a single shared directory.
  * Tests inject `opts.epicsDir` to point at a sandbox; the default for
  * production callers is derived from `lib/config/temp-paths.js#epicTempDir`.
@@ -382,7 +382,7 @@ export function writeState(epicId, state, opts = {}) {
  * the schema from the file itself.
  *
  * Story #1498 / Task #1525 introduced this writer so the rewritten
- * `/epic-plan` halves can persist the spec from the decomposer's
+ * `/plan` halves can persist the spec from the decomposer's
  * ticket-array projection (`renderSpec`) without reaching into raw
  * `js-yaml` calls scattered across the planning scripts.
  *

package/.agents/scripts/lib/spec/state.js

@@ -108,7 +108,7 @@ export function sha256Hex(input) {
 }
 
 /**
- * Hash a spec entry (a Feature, Story, or Task object) deterministically.
+ * Hash a spec entry (a Story object) deterministically.
  * The entry is canonicalised (recursive key-sort), serialised, and
  * sha256'd. Equivalent entries (any key order, equivalent nested order
  * for the object-valued fields) hash to the same digest.
@@ -126,10 +126,9 @@ export function hashSpecEntry(entry) {
 
 /**
  * Iterate every slug-bearing entity in the spec. Yields tuples of
- * `[slug, entry]` where `entry` is the raw object as authored in the
- * spec (feature/story/task). Order is feature-major, story-minor,
- * task-tertiary — the natural read order, useful for deterministic
- * mapping iteration.
+ * `[slug, entry]` where `entry` is the raw Story object as authored in
+ * the spec. Order follows `spec.stories[]` — the natural read order,
+ * useful for deterministic mapping iteration.
  *
  * Exported for tests; the reconciler diff path uses `projectMapping`
  * (below) rather than this generator directly.
@@ -138,17 +137,9 @@ export function hashSpecEntry(entry) {
  * @returns {Generator<[string, object]>}
  */
 export function* iterSpecEntries(spec) {
-  if (!spec || !Array.isArray(spec.features)) return;
-  for (const feature of spec.features) {
-    if (feature?.slug) yield [feature.slug, feature];
-    if (!Array.isArray(feature?.stories)) continue;
-    for (const story of feature.stories) {
-      if (story?.slug) yield [story.slug, story];
-      if (!Array.isArray(story?.tasks)) continue;
-      for (const task of story.tasks) {
-        if (task?.slug) yield [task.slug, task];
-      }
-    }
+  if (!spec || !Array.isArray(spec.stories)) return;
+  for (const story of spec.stories) {
+    if (story?.slug) yield [story.slug, story];
   }
 }
 

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

@@ -0,0 +1,76 @@
+/**
+ * lib/story-adjacency.js — the single story-level adjacency builder.
+ *
+ * All three wave-computation wrappers bottom out in the shared
+ * `lib/Graph.js` kernel (`detectCycle` / `assignLayers` /
+ * `computeWaves`), but each historically re-implemented the step that
+ * turns a list of Story records into the `Map<storyId, number[]>`
+ * adjacency the kernel consumes. This module is now the one home for
+ * that step; the consumers are:
+ *
+ *   - `lib/orchestration/epic-runner/phases/build-wave-dag.js`
+ *     (`buildStoryDag` → `computeWaves`)
+ *   - `lib/orchestration/dispatch-pipeline.js`
+ *     (`buildStoryDispatchGraph` → `computeStoryWaves`)
+ *   - `stories-wave-tick.js` (`buildAdjacency` → `assignLayers`)
+ *
+ * Dependency source order (must stay aligned with manifest-builder.js so
+ * the dispatch manifest and runtime wave scheduling never disagree):
+ *   1. Canonical: `blocked by #NNN` / `depends on #NNN` parsed from the
+ *      Story body via `parseBlockedBy` (the same parser the dispatcher
+ *      uses).
+ *   2. Fallback: an explicit `dependencies` (ticket shape) or
+ *      `dependsOn` (operator-DAG shape) array on the Story record.
+ *
+ * @module lib/story-adjacency
+ */
+
+import { parseBlockedBy } from './dependency-parser.js';
+
+/**
+ * Build a story-level adjacency map (`Map<storyId, dependencyIds[]>`)
+ * from an ordered list of Story records.
+ *
+ * Each record contributes one adjacency entry keyed by
+ * `Number(record.id ?? record.number)`. Dependencies are the deduped
+ * union of body-parsed `blocked by` references and the record's
+ * explicit `dependencies` / `dependsOn` array, with self-edges and
+ * non-integer ids always dropped.
+ *
+ * @param {Array<{id?: number|string, number?: number, body?: string,
+ *   dependencies?: Array<number|string>, dependsOn?: Array<number|string>}>} stories
+ *   Story records (live ticket payloads, fixture tickets, or operator
+ *   DAG nodes).
+ * @param {object} [opts]
+ * @param {boolean} [opts.dropForeign=true] When true (the default,
+ *   matching the Epic-scoped wrappers), edges pointing at ids outside
+ *   the supplied story set are dropped so the DAG stays closed over the
+ *   scheduled set. `stories-wave-tick.js` passes `false` to preserve its
+ *   historical operator-DAG contract, where a dependency on an id absent
+ *   from the input still deepens the dependent's layer.
+ * @returns {Map<number, number[]>}
+ */
+export function buildStoryAdjacency(stories, { dropForeign = true } = {}) {
+  const records = Array.isArray(stories) ? stories : [];
+  const storyIds = new Set(records.map((s) => Number(s?.id ?? s?.number)));
+  const adjacency = new Map();
+  for (const s of records) {
+    const id = Number(s?.id ?? s?.number);
+    const fromBody = parseBlockedBy(s?.body ?? '');
+    const fromField = Array.isArray(s?.dependencies)
+      ? s.dependencies.map(Number)
+      : Array.isArray(s?.dependsOn)
+        ? s.dependsOn.map(Number)
+        : [];
+    const merged = [...new Set([...fromBody, ...fromField])]
+      .map(Number)
+      .filter(
+        (dep) =>
+          Number.isInteger(dep) &&
+          dep !== id &&
+          (!dropForeign || storyIds.has(dep)),
+      );
+    adjacency.set(id, merged);
+  }
+  return adjacency;
+}

package/.agents/scripts/lib/story-init/context-resolver.js

@@ -21,7 +21,7 @@ import { resolveStoryHierarchy } from '../story-lifecycle.js';
  * @param {number} deps.input.storyId
  * @param {number|null} [deps.input.recutOf]
  * @param {boolean} [deps.input.dryRun]
- * @returns {Promise<{ story: object, body: string, epicId: number, featureId: number|null }>}
+ * @returns {Promise<{ story: object, body: string, epicId: number, parentId: number|null }>}
  */
 export async function resolveContext({ provider, logger, input }) {
   const { storyId, recutOf = null, dryRun = false } = input;
@@ -43,7 +43,7 @@ export async function resolveContext({ provider, logger, input }) {
   }
 
   let body = story.body ?? '';
-  const { epicId, featureId } = resolveStoryHierarchy(body);
+  const { epicId, parentId } = resolveStoryHierarchy(body);
 
   if (!epicId) {
     throw new Error(
@@ -88,5 +88,5 @@ export async function resolveContext({ provider, logger, input }) {
     }
   }
 
-  return { story, body, epicId, featureId };
+  return { story, body, epicId, parentId };
 }

package/.agents/scripts/lib/story-init/state-transitioner.js

@@ -2,8 +2,8 @@
  * state-transitioner.js — Stage 6 of the story-init pipeline.
  *
  * Flips the Story ticket to `agent::executing` at init time. Under the
- * 3-tier hierarchy the Story has inline acceptance and no child Task
- * lifecycle — `/story-deliver` runs a single Story-implementation phase.
+ * 2-tier hierarchy the Story has inline acceptance and no child Task
+ * lifecycle — `/deliver` runs a single Story-implementation phase.
  */
 
 import {

package/.agents/scripts/lib/story-init/task-graph-builder.js

@@ -14,7 +14,7 @@ import { fetchChildTickets } from '../story-lifecycle.js';
 
 /**
  * Detect whether a Story body carries inline acceptance criteria, the
- * structural signal that the Story is authored in the 3-tier
+ * structural signal that the Story is authored in the 2-tier
  * (Story-with-inline-acceptance) shape and therefore should not be expected
  * to enumerate child Task tickets. Recognises both `## Acceptance` and
  * `## Acceptance Criteria` headings, with at least one list bullet under
@@ -67,15 +67,15 @@ function sortTasksByDependencies(tasks) {
  * @param {object} deps.input
  * @param {number} deps.input.storyId
  * @param {string} [deps.input.storyBody]   Story body — used to detect
- *   whether the Story carries inline acceptance (3-tier shape) so the
+ *   whether the Story carries inline acceptance (2-tier shape) so the
  *   empty-Task-list path is treated as expected rather than as a warning.
  *
  * Task #3154 (Epic #3078) deleted the `planning.hierarchy` flag; the
- * 3-tier vs 4-tier mode is now derived entirely from the ticket shape —
- * inline acceptance + zero Tasks resolves to `'3-tier'`, otherwise
+ * 2-tier vs 4-tier mode is now derived entirely from the ticket shape —
+ * inline acceptance + zero Tasks resolves to `'2-tier'`, otherwise
  * `'4-tier'`.
  *
- * @returns {Promise<{ sortedTasks: Array<object>, mode: '3-tier'|'4-tier' }>}
+ * @returns {Promise<{ sortedTasks: Array<object>, mode: '2-tier'|'4-tier' }>}
  */
 export async function buildTaskGraph({ provider, logger, input }) {
   const { storyId, storyBody = '' } = input;
@@ -85,13 +85,13 @@ export async function buildTaskGraph({ provider, logger, input }) {
   const tasks = await fetchChildTickets(provider, storyId);
 
   const inlineAcceptance = hasInlineAcceptance(storyBody);
-  const mode = tasks.length === 0 && inlineAcceptance ? '3-tier' : '4-tier';
+  const mode = tasks.length === 0 && inlineAcceptance ? '2-tier' : '4-tier';
 
   if (tasks.length === 0) {
     if (inlineAcceptance) {
       progress(
         'TASKS',
-        `Story #${storyId} has inline acceptance — no child Tasks expected (3-tier shape).`,
+        `Story #${storyId} has inline acceptance — no child Tasks expected (2-tier shape).`,
       );
     } else {
       warn(

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

@@ -10,7 +10,7 @@
  * (branch bootstrap, merge, cascade, notifications). Expanding this module to
  * cover those would over-abstract — they are genuinely different concerns.
  *
- * Under the 3-tier hierarchy (Epic #3078) Stories have no child tickets, so
+ * Under the 2-tier hierarchy (Epic #3078) Stories have no child tickets, so
  * `fetchChildTickets` typically returns `[]` — but the helper remains in
  * place so legacy callers still resolve the Story's direct children cleanly.
  */
@@ -24,7 +24,7 @@ import {
  * Parse the `Epic: #N` and `parent: #N` references from a Story body.
  *
  * @param {string} body  Raw Story body Markdown.
- * @returns {{ epicId: number|null, featureId: number|null }}
+ * @returns {{ epicId: number|null, parentId: number|null }}
  */
 export function resolveStoryHierarchy(body) {
   const source = body ?? '';
@@ -32,25 +32,25 @@ export function resolveStoryHierarchy(body) {
   const parentMatch = source.match(/(?:^\s*parent:\s*#(\d+))/im);
   return {
     epicId: epicMatch ? Number.parseInt(epicMatch[1], 10) : null,
-    featureId: parentMatch ? Number.parseInt(parentMatch[1], 10) : null,
+    parentId: parentMatch ? Number.parseInt(parentMatch[1], 10) : null,
   };
 }
 
 /**
  * Fetch the Story's direct child tickets via the provider.
  *
- * Under the 3-tier hierarchy (Epic #3078) Stories no longer enumerate
+ * Under the 2-tier hierarchy (Epic #3078) Stories no longer enumerate
  * child Task tickets — acceptance criteria and verification steps live
- * inline on the Story body, and decomposers emit only Epic / Feature /
- * Story issues. For those Stories this helper resolves to an empty
+ * inline on the Story body, and decomposers emit only Epic / Story
+ * issues. For those Stories this helper resolves to an empty
  * array because `provider.getSubTickets(storyId)` itself returns no
  * rows. The helper is retained as a thin pass-through so the three
- * orchestration callers (`story-deliver-prepare`, `task-graph-builder`,
+ * orchestration callers (`story-init` prepare, `task-graph-builder`,
  * and `locked-pipeline`) keep a single, named seam for sub-ticket
  * hydration that is easy to mock in tests and to instrument in the
  * provider layer.
  *
- * Legacy ticket trees that were planned before the 3-tier cutover may
+ * Legacy ticket trees that were planned before the 2-tier cutover may
  * still carry sub-tickets (PRD/Tech-Spec links recorded as direct
  * children, for example). The helper deliberately does **not** filter
  * those out — the caller is responsible for classifying anything that
@@ -59,7 +59,7 @@ export function resolveStoryHierarchy(body) {
  *
  * @param {object} provider  ITicketingProvider instance.
  * @param {number} storyId   Story ticket number to hydrate children for.
- * @returns {Promise<object[]>} Array of child tickets (empty under 3-tier).
+ * @returns {Promise<object[]>} Array of child tickets (empty under 2-tier).
  */
 export async function fetchChildTickets(provider, storyId) {
   return provider.getSubTickets(storyId);

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

@@ -1,5 +1,5 @@
 /**
- * story-plan.js — helpers for `/story-plan`.
+ * story-plan.js — helpers for `/plan`.
  *
  * Pure functions used by `.agents/scripts/story-plan.js` (the CLI).
  * Kept side-effect-free so the CLI stays a thin orchestrator and these