@trailstep/create-flows 0.3.1 → 0.3.3

package/dist/index.js

@@ -1,527 +1,365 @@
-// src/grill-it-away/workflow.ts
-import { defineWorkflow, shape as shape2 } from "@trailstep/authoring";
+import {
+  MAX_IMPLEMENTATION_DOC_REVIEW_ATTEMPTS,
+  STORY_BOUNDARY,
+  STORY_CONTEXT_END,
+  STORY_CONTEXT_START,
+  STORY_STATE_KEYS,
+  normalizeTakeItAwayWorkflowOptions,
+  resetStoryLocalState,
+  reviewOutput,
+  reviewPasses,
+  storyRouterStep,
+  takeItAwayInput,
+  takeItAwayOutput
+} from "./chunk-RF3PMHPX.js";
 
-// src/feature-implementation/shared/output-schema.ts
-import { jsonSchema } from "@trailstep/authoring";
-var takeItAwayOutput = jsonSchema({
-  type: "object",
-  properties: {
-    status: { type: "string", const: "implemented" },
-    featureDocPath: { type: "string" },
-    implementationDocPath: { type: "string" },
-    storyCount: { type: "number" },
-    completedStories: { type: "array", items: { type: "string" } },
-    summary: { type: "string" }
+// src/grill-it-away/workflow.ts
+import { defineWorkflow, shape } from "@trailstep/authoring";
+
+// src/feature-implementation/shared/agent-roles.ts
+var featureImplementationAgents = {
+  featureWriter: {
+    size: "medium",
+    thinking: "medium",
+    description: "Turns a conversation/feature request into a standalone feature doc."
   },
-  required: [
-    "status",
-    "featureDocPath",
-    "implementationDocPath",
-    "storyCount",
-    "completedStories",
-    "summary"
-  ],
-  additionalProperties: false
-});
-function extractStoryTitle(storyContent, fallbackIndex) {
-  const heading = /^#{1,6}\s+(.+)$/m.exec(storyContent);
-  return heading?.[1]?.trim() || `Story ${fallbackIndex}`;
-}
+  planner: {
+    size: "large",
+    thinking: "high",
+    description: "Creates or improves the implementation strategy: architecture-aware, TDD/vertical-slice/tracer-bullet story design."
+  },
+  reviewer: {
+    size: "large",
+    thinking: "high",
+    description: "Reviews implementation strategies before story slicing."
+  },
+  slicer: {
+    size: "large",
+    thinking: "high",
+    description: "Slices an approved implementation strategy into coherent implementation stories."
+  },
+  storyExplorer: {
+    size: "small",
+    thinking: "low",
+    description: "Finds story-specific files, seams, and validation hints without editing."
+  },
+  testWriter: {
+    size: "medium",
+    thinking: "medium",
+    description: "Writes focused behavioral red tests for the active story."
+  },
+  storyImplementer: {
+    size: "medium",
+    thinking: "medium",
+    description: "Implements the smallest green slice for the active story."
+  },
+  storyDoctor: {
+    size: "large",
+    thinking: "high",
+    description: "Diagnoses and repairs repeated active-story validation failures before the workflow exhausts retries."
+  },
+  validator: {
+    size: "small",
+    thinking: "low",
+    description: "Runs focused validation commands and reports concise results."
+  },
+  storyReviewer: {
+    size: "large",
+    thinking: "high",
+    description: "Reviews isolated story diffs and phase evidence before commit."
+  }
+};
 
 // src/grill-it-away/grill/step.ts
 import { step as step8 } from "@trailstep/authoring";
 
+// src/feature-implementation/initialize-take-it-away/step.ts
+import { state as state6, step as step7 } from "@trailstep/authoring";
+
 // src/feature-implementation/create-feature-doc/step.ts
-import { Document as Document2, state as state5, step as step7 } from "@trailstep/authoring";
-
-// src/feature-implementation/create-or-improve-implementation-doc/step.ts
-import { Document, state as state4, step as step6 } from "@trailstep/authoring";
-
-// src/feature-implementation/review-implementation-doc/step.ts
-import { fail as fail5, step as step5 } from "@trailstep/authoring";
-
-// src/feature-implementation/shared/constants.ts
-var STORY_BOUNDARY = "<!-- trailstep-story-boundary -->";
-var STORY_CONTEXT_START = "<context>";
-var STORY_CONTEXT_END = "</context>";
-var REVIEW_PASS_THRESHOLD = 4;
-var MAX_IMPLEMENTATION_DOC_REVIEW_ATTEMPTS = 5;
-var MAX_STORY_REVIEW_ATTEMPTS = 3;
-
-// src/feature-implementation/shared/review-schema.ts
-import { jsonSchema as jsonSchema2 } from "@trailstep/authoring";
-var RATING_SCHEMA = { type: "integer", minimum: 1, maximum: 5 };
-var reviewOutput = jsonSchema2({
+import { Document as Document3, state as state5, step as step6 } from "@trailstep/authoring";
+
+// src/feature-implementation/create-or-improve-implementation-strategy/step.ts
+import { Document as Document2, state as state4, step as step5 } from "@trailstep/authoring";
+
+// src/feature-implementation/review-implementation-strategy/step.ts
+import { fail as fail3, step as step4 } from "@trailstep/authoring";
+
+// src/feature-implementation/slice-implementation-stories/step.ts
+import { Document, state as state3, step as step3 } from "@trailstep/authoring";
+
+// src/feature-implementation/split-implementation-stories/step.ts
+import { document, fail as fail2, state as state2, step as step2 } from "@trailstep/authoring";
+
+// src/feature-implementation/planning-checkpoint/step.ts
+import {
+  fail,
+  jsonSchema,
+  state,
+  step
+} from "@trailstep/authoring";
+var planningCheckpointAnswer = jsonSchema({
   type: "object",
   properties: {
-    score: RATING_SCHEMA,
-    summary: { type: "string" },
-    methodologyRatings: {
-      type: "object",
-      properties: {
-        tdd: RATING_SCHEMA,
-        verticalSlicing: RATING_SCHEMA,
-        tracerBullet: RATING_SCHEMA,
-        dependencies: RATING_SCHEMA,
-        architecture: RATING_SCHEMA
-      },
-      required: ["tdd", "verticalSlicing", "tracerBullet", "dependencies", "architecture"],
-      additionalProperties: false
-    },
-    requiredImprovements: { type: "array", items: { type: "string" } }
+    action: { type: "string", enum: ["approve", "revise", "abort"] },
+    notes: { type: "string" }
   },
-  required: ["score", "summary", "methodologyRatings", "requiredImprovements"],
+  required: ["action"],
   additionalProperties: false
 });
-function reviewPasses(review) {
-  return review.score >= REVIEW_PASS_THRESHOLD;
-}
-
-// src/feature-implementation/split-implementation-stories/step.ts
-import { document, fail as fail4, state as state3, step as step4 } from "@trailstep/authoring";
-
-// src/feature-implementation/implement-story/step.ts
-import { fail as fail3, step as step3 } from "@trailstep/authoring";
-
-// src/feature-implementation/review-story-implementation/step.ts
-import { fail as fail2, step as step2 } from "@trailstep/authoring";
-
-// src/feature-implementation/commit-reviewed-story/step.ts
-import { done, fail, state as state2, step } from "@trailstep/authoring";
-
-// src/feature-implementation/shared/story-state.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-import { state } from "@trailstep/authoring";
-var execFileAsync = promisify(execFile);
-var STORY_STATE_KEYS = {
-  activeStory: "activeStory",
-  activeStoryStartCommit: "activeStoryStartCommit",
-  completedStories: "completedStories",
-  storyQueue: "storyQueue"
-};
-async function runGit(args, cwd) {
-  try {
-    const { stdout } = await execFileAsync("git", [...args], {
-      cwd,
-      maxBuffer: 1024 * 1024 * 10
+var planningCheckpointStep = step({ id: "planning-checkpoint" }).wait(async (context) => {
+  const input = context.input;
+  const waitId = await nextPlanningCheckpointWaitId();
+  return {
+    id: waitId,
+    kind: "input",
+    message: [
+      "Review the accepted implementation plan and story slices before execution.",
+      `Implementation doc: ${input.implementationDoc.path}`,
+      'Answer with {"action":"approve"} to continue, {"action":"revise","notes":"..."} to return to planning, or {"action":"abort","notes":"..."} to stop.'
+    ].join("\n"),
+    output: planningCheckpointAnswer
+  };
+}).do(async (context, input) => {
+  const answer = readPlanningCheckpointAnswer(context.waits);
+  if (!answer) {
+    return fail({
+      code: "planning_checkpoint_missing_answer",
+      message: "Planning checkpoint resumed without a recorded human answer."
     });
-    return { ok: true, stdout: stdout.trimEnd() };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { ok: false, error: message };
   }
-}
-async function recordActiveStoryStartCommit() {
-  const existing = await state.get(
-    STORY_STATE_KEYS.activeStoryStartCommit
-  );
-  if (existing?.commit || existing?.warning) {
-    return existing;
-  }
-  const cwd = state.cwd;
-  if (!cwd) {
-    const missingCwd = {
-      warning: "Workflow cwd is unavailable; the story reviewer cannot verify committed story changes from a durable git baseline."
-    };
-    await state.set(STORY_STATE_KEYS.activeStoryStartCommit, missingCwd);
-    return missingCwd;
-  }
-  const result = await runGit(["rev-parse", "HEAD"], cwd);
-  if (!result.ok || result.stdout.length === 0) {
-    const missingGitBaseline = {
-      warning: `Unable to record story start commit with \`git rev-parse HEAD\`: ${result.ok ? "no commit was returned" : result.error}`
-    };
-    await state.set(STORY_STATE_KEYS.activeStoryStartCommit, missingGitBaseline);
-    return missingGitBaseline;
+  if (answer.action === "abort") {
+    return fail({
+      code: "planning_checkpoint_aborted",
+      message: answer.notes?.trim() || "Human aborted at the planning checkpoint.",
+      details: { implementationDocPath: input.implementationDoc.path }
+    });
   }
-  const baseline = { commit: result.stdout };
-  await state.set(STORY_STATE_KEYS.activeStoryStartCommit, baseline);
-  return baseline;
-}
-async function resetActiveStoryStartCommit() {
-  await state.set(STORY_STATE_KEYS.activeStoryStartCommit, null);
-}
-async function loadStoryReviewGitContext() {
-  const baseline = await state.get(
-    STORY_STATE_KEYS.activeStoryStartCommit
-  );
-  const warnings = [];
-  if (baseline?.warning) {
-    warnings.push(baseline.warning);
+  if (answer.action === "revise") {
+    await state.set(STORY_STATE_KEYS.skipNextPlanningCheckpoint, true);
+    return createOrImproveImplementationStrategyStep({
+      featureDoc: input.featureDoc,
+      previousReview: humanRevisionReview(answer.notes),
+      attempt: 1
+    });
   }
-  const cwd = state.cwd;
-  if (!cwd) {
-    warnings.push(
-      "Workflow cwd is unavailable; reviewer must treat committed story-change context as missing."
-    );
-    return { storyStartCommit: baseline?.commit, warnings };
+  const activeStory = await state.get(STORY_STATE_KEYS.activeStory);
+  if (!activeStory) {
+    return fail({
+      code: "planning_checkpoint_missing_active_story",
+      message: "Planning checkpoint approved, but no active story was prepared for execution.",
+      details: { implementationDocPath: input.implementationDoc.path }
+    });
   }
-  const status = await runGit(["status", "--short"], cwd);
-  if (!status.ok) {
-    warnings.push(`Unable to inspect \`git status --short\`: ${status.error}`);
+  return storyRouterStep({ reason: "start-story", currentStory: activeStory });
+});
+async function shouldPauseForPlanningCheckpoint() {
+  const options = await state.get(STORY_STATE_KEYS.workflowOptions);
+  if (!(options?.planningCheckpoint.enabled ?? false)) {
+    return false;
   }
-  const uncommittedDiff = await runGit(["diff"], cwd);
-  if (!uncommittedDiff.ok) {
-    warnings.push(
-      `Unable to inspect uncommitted changes with \`git diff\`: ${uncommittedDiff.error}`
-    );
+  const skipNextCheckpoint = await state.get(
+    STORY_STATE_KEYS.skipNextPlanningCheckpoint
+  );
+  if (skipNextCheckpoint) {
+    await state.set(STORY_STATE_KEYS.skipNextPlanningCheckpoint, false);
+    return false;
   }
-  const storyStartCommit = baseline?.commit;
-  let committedDiff;
-  if (!storyStartCommit) {
-    warnings.push(
-      "No durable story start commit is recorded; reviewer must not silently review only the current working tree diff."
-    );
-  } else {
-    const baselineReachable = await runGit(["cat-file", "-e", `${storyStartCommit}^{commit}`], cwd);
-    if (!baselineReachable.ok) {
-      warnings.push(
-        `Recorded story start commit \`${storyStartCommit}\` is invalid or unreachable: ${baselineReachable.error}`
-      );
-    } else {
-      const committed = await runGit(["diff", `${storyStartCommit}..HEAD`], cwd);
-      if (!committed.ok) {
-        warnings.push(
-          `Unable to inspect committed story changes with \`git diff ${storyStartCommit}..HEAD\`: ${committed.error}`
-        );
-      } else {
-        committedDiff = committed.stdout;
-      }
+  return true;
+}
+async function nextPlanningCheckpointWaitId() {
+  const previousCount = await state.get(STORY_STATE_KEYS.planningCheckpointCount) ?? 0;
+  const nextCount = previousCount + 1;
+  await state.set(STORY_STATE_KEYS.planningCheckpointCount, nextCount);
+  return nextCount === 1 ? "planning-checkpoint" : `planning-checkpoint-${nextCount}`;
+}
+function readPlanningCheckpointAnswer(waits) {
+  for (const [waitId, value] of Object.entries(waits)) {
+    if (!waitId.startsWith("planning-checkpoint") || !isPlanningCheckpointAnswer(value)) {
+      continue;
     }
+    return value;
   }
+  return void 0;
+}
+function isPlanningCheckpointAnswer(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const action = value.action;
+  return action === "approve" || action === "revise" || action === "abort";
+}
+function humanRevisionReview(notes) {
+  const trimmedNotes = notes?.trim();
   return {
-    storyStartCommit,
-    statusShort: status.ok ? status.stdout : void 0,
-    committedDiff,
-    uncommittedDiff: uncommittedDiff.ok ? uncommittedDiff.stdout : void 0,
-    warnings
+    score: 1,
+    summary: trimmedNotes ? `Human requested planning revision: ${trimmedNotes}` : "Human requested planning revision at the checkpoint.",
+    methodologyRatings: {
+      tdd: 1,
+      verticalSlicing: 1,
+      tracerBullet: 1,
+      dependencies: 1,
+      architecture: 1
+    },
+    requiredImprovements: [
+      trimmedNotes || "Revise the implementation plan per human checkpoint feedback."
+    ]
   };
 }
 
-// src/feature-implementation/commit-reviewed-story/run-git.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execFileAsync2 = promisify2(execFile2);
-async function runGit2(args, cwd) {
-  try {
-    const { stdout } = await execFileAsync2("git", [...args], {
-      cwd,
-      maxBuffer: 1024 * 1024 * 10
-    });
-    return { ok: true, stdout: stdout.trimEnd() };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { ok: false, error: message };
+// src/feature-implementation/split-implementation-stories/story-context.ts
+function parseStoryContextBlocks(rawBlocks) {
+  return rawBlocks.flatMap((rawBlock) => {
+    const parsed = parseStoryContextBlock(rawBlock);
+    return parsed ? [parsed] : [];
+  });
+}
+function selectStoryContext({
+  blocks,
+  storyContent,
+  audience,
+  phase
+}) {
+  return blocks.filter(
+    (block) => blockMatchesAudience(block, audience) && blockMatchesStory(block, storyContent) && blockMatchesPhase(block, phase)
+  ).map((block) => block.body).join("\n\n---\n\n");
+}
+function parseStoryContextBlock(rawBlock) {
+  const lines = rawBlock.replace(/\r\n?/g, "\n").split("\n");
+  const firstBlankLine = lines.findIndex((line) => line.trim().length === 0);
+  const metadataLines = firstBlankLine === -1 ? lines : lines.slice(0, firstBlankLine);
+  const bodyLines = firstBlankLine === -1 ? [] : lines.slice(firstBlankLine + 1);
+  const metadata = parseMetadataLines(metadataLines);
+  const body = bodyLines.join("\n").trim();
+  if (body.length === 0 || !hasRecognizedScopeMetadata(metadata)) {
+    return void 0;
   }
+  return { ...metadata, body };
 }
-
-// src/feature-implementation/commit-reviewed-story/step.ts
-var commitReviewedStoryStep = step({ id: "commit-reviewed-story" }).do(
-  async (input) => {
-    const activeStory = await state2.get(STORY_STATE_KEYS.activeStory) ?? input.currentStory;
-    if (storyAutoCommitEnabled()) {
-      const commitResult = await commitReviewedStoryChanges(
-        activeStory,
-        input.implementationSummary
-      );
-      if (!commitResult.ok) {
-        return fail({
-          code: commitResult.code,
-          message: commitResult.message,
-          details: commitResult.details
-        });
+function parseMetadataLines(lines) {
+  const metadata = {};
+  for (const line of lines) {
+    const match = /^([A-Za-z-]+):\s*(.*?)\s*$/.exec(line.trim());
+    if (!match) {
+      continue;
+    }
+    const key = match[1]?.toLowerCase();
+    const value = match[2] ?? "";
+    if (key === "audience") {
+      const audience = parseAudience(value);
+      if (audience) {
+        metadata.audience = audience;
       }
+      continue;
     }
-    return completeReviewedStory(activeStory);
-  }
-);
-function storyAutoCommitEnabled() {
-  const mode = process.env.TRAILSTEP_STORY_COMMIT_MODE;
-  return ["1", "true", "enabled", "worktree"].includes(mode?.toLowerCase() ?? "");
-}
-async function commitReviewedStoryChanges(activeStory, implementationSummary) {
-  const cwd = state2.cwd;
-  if (!cwd) {
-    return {
-      ok: false,
-      code: "story_commit_missing_cwd",
-      message: "Cannot commit reviewed story because the TrailStep workflow cwd is unavailable.",
-      details: { storyPath: activeStory.path }
-    };
-  }
-  const insideWorkTree = await runGit2(["rev-parse", "--is-inside-work-tree"], cwd);
-  if (!insideWorkTree.ok || insideWorkTree.stdout !== "true") {
-    return {
-      ok: false,
-      code: "story_commit_not_git_worktree",
-      message: "Cannot commit reviewed story because the workflow is not running inside a git worktree.",
-      details: {
-        storyPath: activeStory.path,
-        gitError: insideWorkTree.ok ? void 0 : insideWorkTree.error
+    if (key === "stories") {
+      const stories = parseStoryList(value);
+      if (stories) {
+        metadata.stories = stories;
       }
-    };
-  }
-  const add = await runGit2(["add", "-A"], cwd);
-  if (!add.ok) {
-    return {
-      ok: false,
-      code: "story_commit_stage_failed",
-      message: "Cannot commit reviewed story because `git add -A` failed.",
-      details: { storyPath: activeStory.path, gitError: add.error }
-    };
-  }
-  const staged = await runGit2(["diff", "--cached", "--name-only"], cwd);
-  if (!staged.ok) {
-    return {
-      ok: false,
-      code: "story_commit_status_failed",
-      message: "Cannot commit reviewed story because staged changes could not be inspected.",
-      details: { storyPath: activeStory.path, gitError: staged.error }
-    };
-  }
-  if (staged.stdout.trim().length === 0) {
-    const baseline = await state2.get(
-      STORY_STATE_KEYS.activeStoryStartCommit
-    );
-    const head = await runGit2(["rev-parse", "HEAD"], cwd);
-    if (baseline?.commit && head.ok && head.stdout !== baseline.commit) {
-      return { ok: true };
+      continue;
     }
-    return {
-      ok: false,
-      code: "story_commit_empty",
-      message: "The story passed review, but there are no staged or already-committed changes since the story baseline to commit.",
-      details: {
-        storyPath: activeStory.path,
-        storyStartCommit: baseline?.commit,
-        head: head.ok ? head.stdout : void 0,
-        gitError: head.ok ? void 0 : head.error
+    if (key === "phases") {
+      const phases = parsePhaseList(value);
+      if (phases) {
+        metadata.phases = phases;
       }
-    };
+    }
   }
-  const storyTitle = extractStoryTitle(activeStory.content, 1);
-  const commit = await runGit2(
-    [
-      "commit",
-      "-m",
-      truncateCommitSubject(`trailstep: ${storyTitle}`),
-      "-m",
-      commitBody(activeStory, implementationSummary, staged.stdout)
-    ],
-    cwd
-  );
-  if (!commit.ok) {
-    return {
-      ok: false,
-      code: "story_commit_failed",
-      message: "The story passed review, but TrailStep could not create the story commit.",
-      details: { storyPath: activeStory.path, gitError: commit.error }
-    };
+  return metadata;
+}
+function parseAudience(value) {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "implementer" || normalized === "reviewer" || normalized === "all") {
+    return normalized;
   }
-  return { ok: true };
+  return void 0;
 }
-async function completeReviewedStory(activeStory) {
-  const completed = await state2.get(STORY_STATE_KEYS.completedStories) ?? [];
-  const updatedCompleted = [
-    ...completed,
-    extractStoryTitle(activeStory.content, completed.length + 1)
-  ];
-  await state2.set(STORY_STATE_KEYS.completedStories, updatedCompleted);
-  const storyQueue = await state2.get(STORY_STATE_KEYS.storyQueue) ?? [];
-  const [nextStory, ...remaining] = storyQueue;
-  if (!nextStory) {
-    await state2.set(STORY_STATE_KEYS.activeStory, null);
-    await resetActiveStoryStartCommit();
-    const featureDoc = await state2.get("featureDoc");
-    const implementationDoc = await state2.get("implementationDoc");
-    const output = {
-      status: "implemented",
-      featureDocPath: featureDoc?.path ?? "",
-      implementationDocPath: implementationDoc?.path ?? "",
-      storyCount: updatedCompleted.length,
-      completedStories: updatedCompleted,
-      summary: `Implemented and reviewed ${updatedCompleted.length} ${updatedCompleted.length === 1 ? "story" : "stories"}.`
-    };
-    return done(output);
+function parseStoryList(value) {
+  const items = splitMetadataList(value);
+  if (items.length === 0) {
+    return void 0;
   }
-  await state2.set(STORY_STATE_KEYS.storyQueue, remaining);
-  await state2.set(STORY_STATE_KEYS.activeStory, nextStory);
-  await resetActiveStoryStartCommit();
-  await recordActiveStoryStartCommit();
-  return implementStoryStep({ currentStory: nextStory, attempt: 1 });
+  if (items.length === 1 && items[0]?.toLowerCase() === "all") {
+    return "all";
+  }
+  return items.filter((item) => item.toLowerCase() !== "all");
+}
+function parsePhaseList(value) {
+  const items = splitMetadataList(value);
+  if (items.length === 0) {
+    return void 0;
+  }
+  if (items.length === 1 && items[0]?.toLowerCase() === "all") {
+    return "all";
+  }
+  const phases = items.filter(isStoryContextPhase);
+  return phases.length > 0 ? phases : void 0;
 }
-function truncateCommitSubject(subject) {
-  return subject.length <= 72 ? subject : `${subject.slice(0, 69)}...`;
+function splitMetadataList(value) {
+  return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
 }
-function commitBody(activeStory, implementationSummary, stagedFiles) {
+function isStoryContextPhase(value) {
   return [
-    "Committed automatically by TrailStep after a passing story review.",
-    "",
-    `Story artifact: ${activeStory.path}`,
-    "",
-    "Implementer summary:",
-    implementationSummary?.trim() || "Not provided.",
-    "",
-    "Staged files:",
-    stagedFiles.split("\n").filter((file) => file.length > 0).map((file) => `- ${file}`).join("\n")
-  ].join("\n");
+    "deterministic-context-preflight",
+    "explore-story",
+    "write-red-tests",
+    "implement-green",
+    "validate-story",
+    "review-story-implementation"
+  ].includes(value);
 }
-
-// src/feature-implementation/review-story-implementation/prompt.ts
-import { promptSections, section } from "@trailstep/authoring";
-
-// src/feature-implementation/shared/feature-methodology.md?raw
-var feature_methodology_default = "# Feature workflow methodology\n\n## Planning principles\n\n- Start from observable behavior and user value.\n- Preserve uncertainty explicitly; do not invent missing product decisions.\n- Prefer the smallest vertical slice that proves a complete path through the system.\n- Use tracer bullets to de-risk integration seams early with thin end-to-end behavior.\n- Every implementation story must begin with a behavioral red test that fails for the right reason.\n- The green phase should add only enough production code to pass the focused red test.\n- Refactor only after focused tests pass, and keep refactors scoped to the feature.\n- Dependencies are hard dependencies only: story B depends on story A when B cannot pass its own tests until A is complete.\n\n## Review scoring\n\nScore on a 1-5 integer scale:\n\n- 5: excellent; strongly aligned with TDD, vertical slicing, tracer-bullet risk reduction, dependency clarity, and local architecture.\n- 4: good; acceptable with only minor non-blocking improvements.\n- 3: incomplete; useful but needs material changes before continuing.\n- 2: poor; misses core methodology or important requirements.\n- 1: unusable; unsafe, incoherent, or not traceable to the feature.\n\nScores of 4 or 5 pass. Scores below 4 must list specific `requiredImprovements` so the next attempt can address them directly.\n";
-
-// src/feature-implementation/shared/story-implementation-contract.md?raw
-var story_implementation_contract_default = "# Story implementation contract\n\nThe story loop works one story at a time. Each story is self-contained. You will not see non-context overview text or other stories; you will see only the active story plus any shared `<context>` content prepended by the split-stories step.\n\n## Protect pre-existing uncommitted work\n\nRun `git status --short` before making any change.\n\n- The preferred execution mode is a TrailStep-created isolated worktree/branch. In that mode, a successful review is followed by an automatic story commit, so the next story starts from a clean diff boundary.\n- Treat every pre-existing uncommitted file as protected \u2014 it may be unfinished human work, another run's in-progress work, or a sign that isolation failed.\n- Do not run destructive cleanup: no `git reset`, `git checkout --`, broad `git clean`, or equivalent revert/format-away operations.\n- Do not delete or rewrite unrelated chunks in a file that already has changes.\n- If this story requires editing a file that is already dirty, preserve the existing changes and make only the minimal additional change the story requires.\n- If dirty work makes the story ambiguous or blocked, stop and report a blocked state instead of removing it.\n- Do not create git commits yourself unless the story explicitly requires it. TrailStep creates the reviewed story commit after the reviewer passes the story when auto-commit mode is enabled.\n\n## Implementer responsibilities\n\n- Implement only the current story and required dependency-compatible adjustments. Do not start later stories.\n- Use strict behavioral-red TDD: write or update a focused failing behavioral test first, confirm it fails for the intended reason when feasible, implement the smallest change to pass it, then refactor only after it's green.\n- Run the story's validation commands before reporting completion when feasible.\n- Do not report success until implementation and focused validation are done, or until a true blocked state is reached \u2014 report the blocker clearly instead of pretending the story is complete.\n\n## Reviewer responsibilities\n\n- Review only the active story diff from the recorded story baseline through HEAD plus the current uncommitted diff. Do not try to review every dirty change in the checkout as global context.\n- Inspect with read-only commands only (`git status --short`, the exact `git diff <storyStartCommit>..HEAD` command supplied in your prompt, and `git diff`). Do not run tests or other commands \u2014 the implementer is responsible for passing focused validation; this is an AI-only review.\n- Never edit code, delete files, revert files, run cleanup, stage files, commit files, or otherwise modify the working tree to isolate your review.\n- If unrelated dirty files, missing baseline information, or overlapping changes make the active story diff unreviewable, return a failing structured review that explains the isolation problem instead of changing the repository.\n- Review against: the story's acceptance criteria, TDD evidence and test quality, vertical-slice completeness, tracer-bullet alignment where applicable, minimal scope with no gold-plating, and integration with existing architecture/project conventions.\n\n## Completion\n\nA story is complete when code is changed as needed, behavioral tests exist, focused validation passes according to the implementer, and the implementation is well integrated with the existing architecture.\n";
-
-// src/feature-implementation/review-story-implementation/prompt.ts
-var fragments = {
-  methodology: feature_methodology_default.trimEnd(),
-  storyContract: story_implementation_contract_default.trimEnd()
-};
-function reviewStoryImplementationPrompt({
-  input
-}) {
-  const committedDiffCommand = input.gitContext.storyStartCommit ? `git diff ${input.gitContext.storyStartCommit}..HEAD` : "git diff <missing-story-start-commit>..HEAD";
-  return promptSections(
-    fragments.methodology,
-    fragments.storyContract,
-    section("Story", input.currentStory.content),
-    section("Implementer summary", input.implementationSummary ?? "Not provided."),
-    section(
-      "Story review git baseline",
-      [
-        `Recorded story start commit: ${input.gitContext.storyStartCommit ?? "MISSING"}`,
-        `Inspect committed story changes with: \`${committedDiffCommand}\``,
-        "Inspect uncommitted working tree changes with: `git diff`",
-        "Inspect status with: `git status --short`",
-        input.gitContext.warnings.length > 0 ? [
-          "",
-          "Warnings / blocked context:",
-          ...input.gitContext.warnings.map((warning) => `- ${warning}`)
-        ].join("\n") : ""
-      ].filter((line) => line.length > 0).join("\n")
-    ),
-    section(
-      "Committed story changes (`git diff <storyStartCommit>..HEAD`)",
-      input.gitContext.committedDiff ?? "Not available."
-    ),
-    section(
-      "Uncommitted working tree changes (`git diff`)",
-      input.gitContext.uncommittedDiff ?? "Not available."
-    ),
-    section(
-      "Working tree status (`git status --short`)",
-      input.gitContext.statusShort ?? "Not available."
-    ),
-    section(
-      "Task",
-      "Review only the active story slice represented by the recorded story start commit through HEAD, plus the current uncommitted working tree changes, against the story above and the implementer summary. Prefer the supplied diff/status sections; if you need to inspect locally, use read-only commands only (`git status --short`, the listed `git diff <storyStartCommit>..HEAD`, and `git diff`) \u2014 do not run tests, edit code, revert files, clean files, or try to isolate the diff by changing the repository. If unrelated dirty files, a missing/invalid baseline, or ambiguous context prevents a trustworthy review, say so in the structured review and require the implementer/workflow to fix the isolation; never remove changes yourself. Respond only with the structured review."
-    )
-  );
+function hasRecognizedScopeMetadata(metadata) {
+  return Boolean(metadata.audience || metadata.stories || metadata.phases);
 }
-
-// src/feature-implementation/review-story-implementation/step.ts
-var reviewStoryImplementationStep = step2({ id: "review-story-implementation" }).prompt(reviewStoryImplementationPrompt, {
-  agent: "reviewer",
-  output: reviewOutput
-}).do(async (review, input) => {
-  if (!reviewPasses(review)) {
-    if (input.attempt >= MAX_STORY_REVIEW_ATTEMPTS) {
-      return fail2({
-        code: "story_review_exhausted",
-        message: `Story failed review ${MAX_STORY_REVIEW_ATTEMPTS} times in a row (last score ${review.score}/5).`,
-        details: { review, storyPath: input.currentStory.path }
-      });
-    }
-    return implementStoryStep({
-      currentStory: input.currentStory,
-      previousStoryReview: review,
-      attempt: input.attempt + 1
-    });
+function blockMatchesAudience(block, audience) {
+  return block.audience === audience || block.audience === "all";
+}
+function blockMatchesStory(block, storyContent) {
+  if (block.stories === "all") {
+    return true;
   }
-  return commitReviewedStoryStep({
-    currentStory: input.currentStory,
-    implementationSummary: input.implementationSummary
-  });
-});
-
-// src/feature-implementation/implement-story/prompt.ts
-import { jsonSchema as jsonSchema3, list, promptSections as promptSections2, section as section2 } from "@trailstep/authoring";
-
-// src/feature-implementation/shared/project-architecture-guidance.md?raw
-var project_architecture_guidance_default = "# Architecture awareness\n\nBefore naming files, choosing package/module boundaries, picking integration seams, or ordering stories/dependencies, ground the decision in the target project's own conventions rather than inventing structure:\n\n- Look for and read the project's own architecture/convention docs at its root and nearby \u2014 `CLAUDE.md`, `AGENTS.md`, `.pi/rules/`, ADRs, architecture docs, or an equivalent README section.\n- Prefer existing module/package boundaries, naming conventions, and file layout patterns already established in the project over introducing new ones.\n- When the project's own guidance is silent or ambiguous on a non-trivial integration choice, say so explicitly as an assumption rather than silently picking one convention over another.\n";
-
-// src/feature-implementation/implement-story/prompt.ts
-var fragments2 = {
-  methodology: feature_methodology_default.trimEnd(),
-  architectureGuidance: project_architecture_guidance_default.trimEnd(),
-  storyContract: story_implementation_contract_default.trimEnd()
-};
-var implementStoryOutput = jsonSchema3({
-  type: "object",
-  properties: {
-    blocked: { type: "boolean" },
-    blockedReason: { type: "string" },
-    summary: {
-      type: "string",
-      description: "Files changed, commands run, and their results."
-    }
-  },
-  required: ["blocked", "summary"],
-  additionalProperties: false
-});
-function implementStoryPrompt({ input }) {
-  const taskBody = input.previousStoryReview === void 0 ? "Implement this story." : promptSections2(
-    `This is retry attempt ${input.attempt} for this story. A previous review scored the implementation ${input.previousStoryReview.score}/5: ${input.previousStoryReview.summary}`,
-    `Required improvements to address, without discarding what already works:
-
-${list(input.previousStoryReview.requiredImprovements)}`
-  );
-  return promptSections2(
-    fragments2.methodology,
-    fragments2.architectureGuidance,
-    fragments2.storyContract,
-    section2("Story", input.currentStory.content),
-    section2(
-      "Task",
-      `${taskBody}
-
-Set \`blocked: true\` with a clear \`blockedReason\` instead of guessing or pretending the story is complete. Otherwise set \`blocked: false\` and use \`summary\` to report files changed, commands run, and their results.`
-    )
-  );
+  if (!block.stories) {
+    return false;
+  }
+  const storyLabels = extractStoryLabels(storyContent).map(normalizeStoryLabel);
+  return block.stories.some((story) => storyLabels.includes(normalizeStoryLabel(story)));
 }
-
-// src/feature-implementation/implement-story/step.ts
-var implementStoryStep = step3({ id: "implement-story" }).prompt(implementStoryPrompt, {
-  agent: "implementer",
-  output: implementStoryOutput
-}).do(async (promptOutput, input) => {
-  if (promptOutput.blocked) {
-    return fail3({
-      code: "story_blocked",
-      message: promptOutput.blockedReason ?? "Story implementation reported a blocked state.",
-      details: { storyPath: input.currentStory.path }
-    });
+function blockMatchesPhase(block, phase) {
+  if (!block.phases || block.phases === "all" || block.phases.includes(phase)) {
+    return true;
   }
-  return reviewStoryImplementationStep({
-    currentStory: input.currentStory,
-    attempt: input.attempt,
-    implementationSummary: promptOutput.summary,
-    gitContext: await loadStoryReviewGitContext()
-  });
-});
+  return phase === "deterministic-context-preflight" && block.phases.includes("explore-story");
+}
+function extractStoryLabels(storyContent) {
+  const match = /^#{1,6}\s+(Story\s+\d+)(?::\s*(.+))?\s*$/im.exec(storyContent);
+  const ordinal = match?.[1]?.trim();
+  if (!ordinal) {
+    return [];
+  }
+  const title = match?.[2]?.trim();
+  return title ? [ordinal, `${ordinal}: ${title}`] : [ordinal];
+}
+function normalizeStoryLabel(value) {
+  return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
 
 // src/feature-implementation/split-implementation-stories/step.ts
-var splitImplementationStoriesStep = step4({ id: "split-implementation-stories" }).do(
-  async ({ implementationDoc }) => {
-    const contextStartCount = countOccurrences(implementationDoc.content, STORY_CONTEXT_START);
-    const contextEndCount = countOccurrences(implementationDoc.content, STORY_CONTEXT_END);
+var splitImplementationStoriesStep = step2({ id: "split-implementation-stories" }).do(
+  async ({
+    featureDoc,
+    implementationDoc
+  }) => {
+    const contextStartCount = countStandaloneMarkerLines(
+      implementationDoc.content,
+      STORY_CONTEXT_START
+    );
+    const contextEndCount = countStandaloneMarkerLines(
+      implementationDoc.content,
+      STORY_CONTEXT_END
+    );
     if (contextStartCount !== contextEndCount) {
-      return fail4({
+      return fail2({
         code: "unbalanced_story_context",
         message: `Found ${contextStartCount} \`${STORY_CONTEXT_START}\` marker(s) and ${contextEndCount} \`${STORY_CONTEXT_END}\` marker(s) in implementation-doc.md. Context blocks must be balanced.`,
         details: { implementationDocPath: implementationDoc.path }
@@ -529,21 +367,25 @@ var splitImplementationStoriesStep = step4({ id: "split-implementation-stories"
     }
     const contextMatches = Array.from(implementationDoc.content.matchAll(storyContextPattern()));
     if (contextMatches.length !== contextStartCount) {
-      return fail4({
+      return fail2({
         code: "invalid_story_context_order",
         message: `Every \`${STORY_CONTEXT_START}\` marker in implementation-doc.md must be followed by a matching \`${STORY_CONTEXT_END}\` marker.`,
         details: { implementationDocPath: implementationDoc.path }
       });
     }
-    const contextBlocks = contextMatches.map(([, context]) => context?.trim() ?? "").filter((context) => context.length > 0);
-    const sharedContext = contextBlocks.join("\n\n---\n\n");
+    const parsedContextBlocks = parseStoryContextBlocks(
+      contextMatches.map(([, context]) => context ?? "")
+    );
     const contentWithoutContextBlocks = implementationDoc.content.replace(
       storyContextPattern(),
       ""
     );
-    const chunks = contentWithoutContextBlocks.split(STORY_BOUNDARY).slice(1).map((chunk) => chunk.trim()).filter((chunk) => chunk.length > 0).map((chunk) => prependSharedContext(chunk, sharedContext));
+    const chunks = contentWithoutContextBlocks.split(STORY_BOUNDARY).slice(1).map((chunk) => chunk.trim()).filter((chunk) => chunk.length > 0);
+    const storyContexts = chunks.map(
+      (chunk) => buildStoryPhaseContexts(parsedContextBlocks, chunk)
+    );
     if (chunks.length === 0) {
-      return fail4({
+      return fail2({
         code: "no_stories_found",
         message: `No \`${STORY_BOUNDARY}\`-delimited stories found in implementation-doc.md.`,
         details: { implementationDocPath: implementationDoc.path }
@@ -554,201 +396,280 @@ var splitImplementationStoriesStep = step4({ id: "split-implementation-stories"
       storyDocs.push(await document(chunk));
     }
     const [firstStory, ...remaining] = storyDocs;
-    await state3.set(STORY_STATE_KEYS.storyQueue, remaining);
-    await state3.set(STORY_STATE_KEYS.completedStories, []);
-    await state3.set(STORY_STATE_KEYS.activeStory, firstStory);
-    await recordActiveStoryStartCommit();
-    return implementStoryStep({ currentStory: firstStory, attempt: 1 });
-  }
-);
-function countOccurrences(value, needle) {
-  if (needle.length === 0) {
-    return 0;
-  }
-  let count = 0;
-  let offset = 0;
-  while (true) {
-    const index = value.indexOf(needle, offset);
-    if (index === -1) {
-      return count;
+    const [firstStoryContext = {}, ...remainingStoryContexts] = storyContexts;
+    await state2.set(STORY_STATE_KEYS.storyQueue, remaining);
+    await state2.set(STORY_STATE_KEYS.storyContextQueue, remainingStoryContexts);
+    await state2.set(STORY_STATE_KEYS.completedStories, []);
+    await state2.set(STORY_STATE_KEYS.activeStory, firstStory);
+    await state2.set(STORY_STATE_KEYS.activeStoryContext, firstStoryContext);
+    await state2.set(STORY_STATE_KEYS.activePhase, "story-router");
+    await resetStoryLocalState({
+      preserveActiveStoryStartCommit: true,
+      preserveLatestStoryRouterState: true,
+      preserveStoryBaseline: true
+    });
+    if (featureDoc && await shouldPauseForPlanningCheckpoint()) {
+      return planningCheckpointStep({ featureDoc, implementationDoc });
     }
-    count += 1;
-    offset = index + needle.length;
+    return storyRouterStep({ reason: "start-story", currentStory: firstStory });
   }
+);
+function buildStoryPhaseContexts(blocks, storyContent) {
+  const phases = [
+    "deterministic-context-preflight",
+    "explore-story",
+    "write-red-tests",
+    "implement-green",
+    "validate-story",
+    "review-story-implementation"
+  ];
+  return Object.fromEntries(
+    phases.map((phase) => [
+      phase,
+      selectStoryContext({
+        blocks,
+        storyContent,
+        audience: phase === "review-story-implementation" ? "reviewer" : "implementer",
+        phase
+      })
+    ])
+  );
+}
+function countStandaloneMarkerLines(value, marker) {
+  return Array.from(value.matchAll(standaloneMarkerLinePattern(marker))).length;
+}
+function standaloneMarkerLinePattern(marker) {
+  return new RegExp(`^[ \\t]*${escapeRegExp(marker)}[ \\t]*$`, "gm");
 }
 function storyContextPattern() {
   return new RegExp(
-    `${escapeRegExp(STORY_CONTEXT_START)}([\\s\\S]*?)${escapeRegExp(STORY_CONTEXT_END)}`,
-    "g"
+    `^[ \\t]*${escapeRegExp(STORY_CONTEXT_START)}[ \\t]*\\r?\\n([\\s\\S]*?)^[ \\t]*${escapeRegExp(STORY_CONTEXT_END)}[ \\t]*$`,
+    "gm"
   );
 }
-function prependSharedContext(story, sharedContext) {
-  if (sharedContext.length === 0) {
-    return story;
-  }
-  return ["## Shared implementation context", sharedContext, "## Active story", story].join("\n\n");
-}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-// src/feature-implementation/review-implementation-doc/prompt.ts
-import { list as list2, promptSections as promptSections3, section as section3 } from "@trailstep/authoring";
+// src/feature-implementation/slice-implementation-stories/prompt.ts
+import { promptSections, section } from "@trailstep/authoring";
+
+// src/feature-implementation/shared/feature-methodology.md?raw
+var feature_methodology_default = "# Feature workflow methodology\n\n## Planning principles\n\n- Start from observable behavior and user value.\n- Preserve uncertainty explicitly; do not invent missing product decisions.\n- Prefer the smallest vertical slice that proves a complete path through the system.\n- Slice by integration-visible value and risk, not by numeric story budgets.\n- Split a story when it contains separable user-visible/integration-visible outcomes, independent risk seams, or hard dependency boundaries that can each be proven by distinct behavioral tests.\n- Bundle work into the same story when splitting would create micro-stories, docs/package-metadata-only tasks, duplicate validation-only paths, or horizontal setup/refactor/test-only tasks that are not independently observable.\n- Use tracer bullets to de-risk integration seams early with thin end-to-end behavior.\n- Every implementation story must begin with a behavioral red test that fails for the right reason.\n- The green phase should add only enough production code to pass the focused red test.\n- Refactor only after focused tests pass, and keep refactors scoped to the feature.\n- Dependencies are hard dependencies only: story B depends on story A when B cannot pass its own tests until A is complete.\n\n## Review scoring\n\nScore on a 1-5 integer scale:\n\n- 5: excellent; strongly aligned with TDD, cost-aware vertical slicing, tracer-bullet risk reduction, dependency clarity, and local architecture.\n- 4: good; acceptable with only minor non-blocking improvements.\n- 3: incomplete; useful but needs material changes before continuing.\n- 2: poor; misses core methodology or important requirements.\n- 1: unusable; unsafe, incoherent, or not traceable to the feature.\n\nScores of 4 or 5 pass. Scores below 4 must list specific `requiredImprovements` so the next attempt can address them directly.\n";
 
 // src/feature-implementation/shared/implementation-doc-format.md?raw
-var implementation_doc_format_default = "# Implementation doc format\n\n`implementation-doc.md` converts `feature-doc.md` into implementation-ready stories.\n\nUse this structure:\n\n```markdown\n# Implementation Plan: <Feature Name>\n\n## Overview for planner/reviewer\n\nOptional high-level planning notes that do not need to be seen by story implementers.\n\n<context>\n\n## Shared Implementation Context\n\nPut every cross-story detail that an implementer may need here: outcome and constraints, architecture/integration notes, tracer-bullet strategy, repository conventions, shared validation commands, edge cases, assumptions, and hard dependency graph notes.\n\nAnything inside this balanced `<context>` block is prepended programmatically to every story by the split-stories step.\n\n</context>\n\n<!-- trailstep-story-boundary -->\n\n### Story 001: <title>\n\nDependencies: none\n\n#### Goal\n\n#### User-Visible / Integration-Visible Slice\n\n#### Acceptance Criteria\n\n#### Red Phase\n\n- Test file:\n- Test case:\n- Expected failing assertion:\n\n#### Green Phase\n\n#### Refactor Phase\n\n#### Validation Commands\n\n#### Notes for Implementer\n\n<!-- trailstep-story-boundary -->\n\n### Story 002: <title>\n\nDependencies: Story 001\n\n...\n```\n\nRules:\n\n- Text above the first `<!-- trailstep-story-boundary -->` is never read by an implementer unless it is inside a balanced `<context>` ... `</context>` block. The split-stories step prepends all context blocks to every story.\n- If a detail applies to most/all stories, put it in `<context>`; if it applies only to selected stories, repeat it inside those stories. No story-critical detail may live only in non-context overview text.\n- Every `<context>` marker must have a matching `</context>` marker, and context blocks should be outside story bodies unless there is a deliberate reason to prepend that block to every story.\n- Every story must start right after a `<!-- trailstep-story-boundary -->` line, on its own line, with nothing else on that line. Splitting is mechanical and depends on this exact marker \u2014 do not use markdown headings alone to separate stories, and do not add or omit a boundary marker except between/before stories.\n- Stories must be topologically ordered.\n- Every story must be implementation-ready and self-contained, written as instructions to an implementer who will not see this file, only their own story's content.\n- Avoid horizontal stories unless they are embedded in an observable vertical slice.\n- Name concrete files/tests/commands when they can be inferred from the repository.\n- Preserve uncertainty as assumptions or blocked states instead of guessing.\n";
+var implementation_doc_format_default = "# Implementation doc format\n\n`implementation-doc.md` converts `feature-doc.md` into implementation-ready stories.\n\nUse this structure:\n\n```markdown\n# Implementation Plan: <Feature Name>\n\n## Overview for planner/reviewer\n\nOptional high-level planning notes that do not need to be seen by story implementers.\n\n<context>\naudience: implementer\nstories: all\nphases: deterministic-context-preflight\n\n## Shared Implementer Exploration Context\n\nPut only cross-story details that an implementer needs during story exploration: outcome constraints, architecture/integration notes, repository conventions, shared validation command hints, assumptions, and hard dependency graph notes. Do not put reviewer-only instructions, full implementation-doc process guidance, or unrelated story details here.\n\nScoped context blocks are stored separately from story bodies. They are not prepended to every split story. The router passes matching implementer context only to the narrow phase that needs it.\n\n</context>\n\n<!-- trailstep-story-boundary -->\n\n### Story 001: <title>\n\nDependencies: none\n\n#### Goal\n\n#### User-Visible / Integration-Visible Slice\n\n#### Acceptance Criteria\n\n#### Red Phase\n\n- Test file:\n- Test case:\n- Expected failing assertion:\n\n#### Green Phase\n\n#### Refactor Phase\n\n#### Validation Commands\n\n#### Notes for Implementer\n\n<!-- trailstep-story-boundary -->\n\n### Story 002: <title>\n\nDependencies: Story 001\n\n...\n```\n\nRules:\n\n- Text above the first `<!-- trailstep-story-boundary -->` is never part of an active story body. Only scoped `<context>` ... `</context>` blocks with recognized metadata can be selected as separate phase context.\n- Context blocks must begin with metadata lines before the first blank line. Recognized keys are `audience: implementer|reviewer|all`, `stories: all|Story 001|Story 001: Title`, and `phases: all|deterministic-context-preflight|explore-story|write-red-tests|implement-green|validate-story|review-story-implementation`.\n- Unscoped context blocks are ignored instead of being blindly prepended to every story. If a detail applies to only one story, prefer putting it directly in that story. No story-critical detail may live only in non-context overview text.\n- Every `<context>` marker must have a matching `</context>` marker. Context markers are recognized only when the marker is the sole non-whitespace content on its line; inline mentions of `<context>` in prose are ignored by the splitter.\n- Every story must start right after a `<!-- trailstep-story-boundary -->` line, on its own line, with nothing else on that line. Splitting is mechanical and depends on this exact marker \u2014 do not use markdown headings alone to separate stories, and do not add or omit a boundary marker except between/before stories.\n- Stories must be topologically ordered.\n- Every story must be implementation-ready and self-contained, written as instructions to an implementer who will not see this file, only their own story's content.\n- Avoid horizontal stories unless they are embedded in an observable vertical slice.\n- Split versus bundle by delivery value, risk, and validation distinctness, not by numeric story budgets.\n- Split a candidate story when it contains separable integration-visible outcomes, independent high-risk seams, or true hard dependency boundaries that can each be proven by a distinct behavioral red test.\n- Bundle small changes when splitting would produce micro-stories, duplicate validation paths, docs/package-metadata-only stories, package metadata wiring without behavior, or horizontal setup/refactor/test-only work that is not independently observable.\n- Keep slicing rationale in the overview or reviewer context only; do not put split/bundle justification inside story bodies shown to implementers.\n- Name concrete files/tests/commands when they can be inferred from the repository.\n- Preserve uncertainty as assumptions or blocked states instead of guessing.\n";
 
-// src/feature-implementation/review-implementation-doc/prompt.ts
-var fragments3 = {
+// src/feature-implementation/slice-implementation-stories/prompt.ts
+var fragments = {
   methodology: feature_methodology_default.trimEnd(),
   implementationDocFormat: implementation_doc_format_default.trimEnd()
 };
-function reviewImplementationDocPrompt({
+function sliceImplementationStoriesPrompt({
+  input
+}) {
+  return promptSections(
+    fragments.methodology,
+    fragments.implementationDocFormat,
+    section("Feature doc", input.featureDoc.content),
+    section("Reviewed implementation strategy", input.implementationStrategy.content),
+    section(
+      "Task",
+      "Generate only the implementation-ready story document to be mechanically split for execution. Consume the feature doc and reviewed strategy, but do not copy broad architecture/risk planning into overview prose that implementers will not see. Use `<!-- trailstep-story-boundary -->` only to delimit story bodies. Keep each story self-contained for its implementer; put genuinely shared implementer-only phase context in balanced `<context>` blocks with metadata. Do not add a separate strategy section, reviewer notes, or non-story planning artifact content."
+    )
+  );
+}
+
+// src/feature-implementation/slice-implementation-stories/step.ts
+var sliceImplementationStoriesStep = step3({ id: "slice-implementation-stories" }).prompt(sliceImplementationStoriesPrompt, {
+  agent: "slicer",
+  output: Document
+}).do(async (implementationDoc, input) => {
+  await state3.set("implementationDoc", implementationDoc);
+  return splitImplementationStoriesStep({ featureDoc: input.featureDoc, implementationDoc });
+});
+
+// src/feature-implementation/review-implementation-strategy/prompt.ts
+import { list, promptSections as promptSections2, section as section2 } from "@trailstep/authoring";
+
+// src/feature-implementation/shared/implementation-strategy-format.md?raw
+var implementation_strategy_format_default = "# Implementation strategy format\n\n`implementation-strategy.md` captures architecture and risk planning before executable story slicing.\n\nUse this structure:\n\n```markdown\n# Implementation Strategy: <Feature Name>\n\n## Objective and Scope\n\n## Architecture Approach\n\n## Key Files and Integration Points\n\n## Risk Plan\n\n## Testing Strategy\n\n## Slicing Guidance\n```\n\nRules:\n\n- Do not include `<!-- trailstep-story-boundary -->` or any other TrailStep story boundary markup.\n- Do not write executable story bodies in this artifact.\n- Focus on architecture, risk, sequencing rationale, tracer-bullet path, hard dependencies, and validation strategy.\n- Preserve uncertainty as assumptions or explicit risks instead of guessing.\n";
+
+// src/feature-implementation/review-implementation-strategy/prompt.ts
+var fragments2 = {
+  methodology: feature_methodology_default.trimEnd(),
+  implementationStrategyFormat: implementation_strategy_format_default.trimEnd()
+};
+function reviewImplementationStrategyPrompt({
   input
 }) {
-  const reviewCriteria = list2([
+  const reviewCriteria = list([
     "traceability to the feature doc",
-    "strict behavioral-red TDD story design",
-    "vertical slices rather than horizontal tasks",
+    "sound architecture and integration planning",
+    "explicit risk and uncertainty handling",
     "a clear tracer-bullet strategy",
-    "hard dependency labels and topological ordering",
-    "acceptance criteria and validation commands",
-    "story instructions self-contained enough for an implementer who will only see one story plus the prepended shared context at a time",
-    "correct use of balanced `<context>` ... `</context>` blocks for shared implementer context",
-    "correct use of the `<!-- trailstep-story-boundary -->` marker between stories, and that no story-critical detail lives only in non-context overview text above the first marker"
+    "hard dependency reasoning without over-constraining",
+    "testing and validation strategy",
+    "useful slicing guidance for a later story slicer",
+    "absence of `<!-- trailstep-story-boundary -->` markers or executable story bodies"
   ]);
-  return promptSections3(
-    fragments3.methodology,
-    fragments3.implementationDocFormat,
-    section3("Feature doc", input.featureDoc.content),
-    section3("Implementation doc under review", input.implementationDoc.content),
-    section3(
+  return promptSections2(
+    fragments2.methodology,
+    fragments2.implementationStrategyFormat,
+    section2("Feature doc", input.featureDoc.content),
+    section2("Implementation strategy under review", input.implementationStrategy.content),
+    section2(
       "Task",
-      `Critically review the implementation doc above against the feature doc and the methodology. Review for:
+      `Critically review the implementation strategy above against the feature doc and the methodology. Review for:
 
 ${reviewCriteria}
 
-Do not edit the implementation doc. Respond only with the structured review.`
+Do not edit the strategy. Respond only with the structured review.`
     )
   );
 }
 
-// src/feature-implementation/review-implementation-doc/step.ts
-var reviewImplementationDocStep = step5({ id: "review-implementation-doc" }).prompt(reviewImplementationDocPrompt, {
+// src/feature-implementation/review-implementation-strategy/step.ts
+var reviewImplementationStrategyStep = step4({ id: "review-implementation-strategy" }).prompt(reviewImplementationStrategyPrompt, {
   agent: "reviewer",
   output: reviewOutput
 }).do((review, input) => {
   if (reviewPasses(review)) {
-    return splitImplementationStoriesStep({ implementationDoc: input.implementationDoc });
+    return sliceImplementationStoriesStep({
+      featureDoc: input.featureDoc,
+      implementationStrategy: input.implementationStrategy
+    });
   }
   if (input.attempt >= MAX_IMPLEMENTATION_DOC_REVIEW_ATTEMPTS) {
-    return fail5({
-      code: "implementation_doc_review_exhausted",
-      message: `implementation-doc.md failed review ${MAX_IMPLEMENTATION_DOC_REVIEW_ATTEMPTS} times in a row (last score ${review.score}/5).`,
-      details: { review, implementationDocPath: input.implementationDoc.path }
+    return fail3({
+      code: "implementation_strategy_review_exhausted",
+      message: `implementation-strategy.md failed review ${MAX_IMPLEMENTATION_DOC_REVIEW_ATTEMPTS} times in a row (last score ${review.score}/5).`,
+      details: { review, implementationStrategyPath: input.implementationStrategy.path }
     });
   }
-  return createOrImproveImplementationDocStep({
+  return createOrImproveImplementationStrategyStep({
     featureDoc: input.featureDoc,
     previousReview: review,
     attempt: input.attempt + 1
   });
 });
 
-// src/feature-implementation/create-or-improve-implementation-doc/prompt.ts
-import { list as list3, promptSections as promptSections4, section as section4 } from "@trailstep/authoring";
-var fragments4 = {
+// src/feature-implementation/create-or-improve-implementation-strategy/prompt.ts
+import { list as list2, promptSections as promptSections3, section as section3 } from "@trailstep/authoring";
+
+// src/feature-implementation/shared/project-architecture-guidance.md?raw
+var project_architecture_guidance_default = "# Architecture awareness\n\nBefore naming files, choosing package/module boundaries, picking integration seams, or ordering stories/dependencies, ground the decision in the target project's own conventions rather than inventing structure:\n\n- Look for and read the project's own architecture/convention docs at its root and nearby \u2014 `CLAUDE.md`, `AGENTS.md`, `.pi/rules/`, ADRs, architecture docs, or an equivalent README section.\n- Prefer existing module/package boundaries, naming conventions, and file layout patterns already established in the project over introducing new ones.\n- When the project's own guidance is silent or ambiguous on a non-trivial integration choice, say so explicitly as an assumption rather than silently picking one convention over another.\n";
+
+// src/feature-implementation/create-or-improve-implementation-strategy/prompt.ts
+var fragments3 = {
   methodology: feature_methodology_default.trimEnd(),
   architectureGuidance: project_architecture_guidance_default.trimEnd(),
-  implementationDocFormat: implementation_doc_format_default.trimEnd()
+  implementationStrategyFormat: implementation_strategy_format_default.trimEnd()
 };
-function createOrImproveImplementationDocPrompt({
+function createOrImproveImplementationStrategyPrompt({
   input
 }) {
-  const taskBody = input.previousReview === void 0 ? "Create `implementation-doc.md` from the feature doc above, following the format exactly enough that stories can later be split mechanically on the `<!-- trailstep-story-boundary -->` marker and shared context can be prepended from balanced `<context>` blocks." : promptSections4(
-    `This is improvement attempt ${input.attempt}. A previous review scored this plan ${input.previousReview.score}/5: ${input.previousReview.summary}`,
+  const taskBody = input.previousReview === void 0 ? "Create `implementation-strategy.md` from the feature doc above. This is architecture/risk planning only, not executable story generation." : promptSections3(
+    `This is improvement attempt ${input.attempt}. A previous review scored this strategy ${input.previousReview.score}/5: ${input.previousReview.summary}`,
     `Required improvements to address, without discarding what already works:
 
-${list3(input.previousReview.requiredImprovements)}`
+${list2(input.previousReview.requiredImprovements)}`
   );
-  return promptSections4(
-    fragments4.methodology,
-    fragments4.architectureGuidance,
-    fragments4.implementationDocFormat,
-    section4("Feature doc", input.featureDoc.content),
-    section4(
+  return promptSections3(
+    fragments3.methodology,
+    fragments3.architectureGuidance,
+    fragments3.implementationStrategyFormat,
+    section3("Feature doc", input.featureDoc.content),
+    section3(
       "Task",
       `${taskBody}
 
-Design stories around strict behavioral-red TDD, vertical slicing, tracer-bullet methodology, and hard dependency labels only. Topologically order stories by dependency. Put shared implementation details in balanced \`<context>\` ... \`</context>\` blocks so split-stories prepends them to every story; repeat details inside individual stories when only selected stories need them. Write every story as implementation-ready instructions for an implementer who will only see that story plus the prepended context.`
+Plan the implementation architecture, risks, tracer-bullet path, hard dependencies, test strategy, and slicing guidance. Do not include story boundary markers and do not write full story bodies; a separate slicer will turn this strategy into implementation-ready stories.`
     )
   );
 }
 
-// src/feature-implementation/create-or-improve-implementation-doc/step.ts
-var createOrImproveImplementationDocStep = step6({
-  id: "create-or-improve-implementation-doc"
-}).prompt(createOrImproveImplementationDocPrompt, {
+// src/feature-implementation/create-or-improve-implementation-strategy/step.ts
+var createOrImproveImplementationStrategyStep = step5({
+  id: "create-or-improve-implementation-strategy"
+}).prompt(createOrImproveImplementationStrategyPrompt, {
   agent: "planner",
-  output: Document
-}).do(async (implementationDoc, input) => {
-  await state4.set("implementationDoc", implementationDoc);
-  return reviewImplementationDocStep({
+  output: Document2
+}).do(async (implementationStrategy, input) => {
+  await state4.set("implementationStrategy", implementationStrategy);
+  return reviewImplementationStrategyStep({
     featureDoc: input.featureDoc,
-    implementationDoc,
+    implementationStrategy,
     attempt: input.attempt
   });
 });
 
 // src/feature-implementation/create-feature-doc/prompt.ts
-import { promptSections as promptSections5, section as section5 } from "@trailstep/authoring";
+import { promptSections as promptSections4, section as section4 } from "@trailstep/authoring";
 
 // src/feature-implementation/shared/feature-doc-format.md?raw
-var feature_doc_format_default = "# Feature doc format\n\n`feature-doc.md` is an intermediate product-quality feature description used as input to implementation planning.\n\nUse this structure:\n\n```markdown\n# <Feature Name>\n\n## Outcome\n\n## Users / Jobs / Pain\n\n## Proposed Behavior\n\n## Non-Goals\n\n## Examples and Acceptance Criteria\n\n## Edge Cases and Failure Modes\n\n## Affected Areas and Integration Points\n\n## Testing Expectations\n\n## Documentation / Migration / Rollout Notes\n\n## Open Questions and Assumptions\n```\n\nThe document should be detailed enough that another agent can plan implementation without reading the original conversation, while still preserving important uncertainty.\n";
+var feature_doc_format_default = "# Feature doc format\n\n`feature-doc.md` is an intermediate, scope-preserving feature description used as input to implementation planning. It should distill the real request without turning it into an idealized product specification.\n\nUse this structure:\n\n```markdown\n# <Feature Name>\n\n## Must-Have Outcome\n\nSummarize the smallest confirmed outcome the user actually requested. Prefer the user's concrete wording and avoid expanding into adjacent product vision.\n\n## Users / Jobs / Pain\n\n## In-Scope Proposed Behavior\n\nDescribe only behavior needed for the must-have outcome. If something seems useful but was not requested or is uncertain, keep it out of this section.\n\n## Explicit Non-Goals\n\nList non-goals, exclusions, and scope limits explicitly stated by the conversation. Include strongly implied exclusions only when tied to clear evidence. If none were stated, say so instead of inventing exclusions.\n\n## Examples and Acceptance Criteria\n\n## Edge Cases and Failure Modes\n\n## Affected Areas and Integration Points\n\n## Testing Expectations\n\n## Documentation / Migration / Rollout Notes\n\n## Assumptions and Open Questions\n\nCapture missing product decisions, uncertain details, and assumptions required for planning. Do not resolve uncertainty by inventing answers.\n\n## Conversation Context Worth Preserving\n\nRecord constraints, rationale, terminology, user preferences, tradeoffs, and notable uncertainty that a planner or implementer should know without rereading the full conversation.\n\n## Optional / Future Ideas\n\nList explicitly mentioned nice-to-haves, possible follow-ups, or adjacent ideas separately from the current implementation scope. These ideas are not acceptance criteria unless the conversation explicitly makes them must-haves.\n\n## Structured Scope Facts\n\nProvide a compact, planning-friendly fact list without introducing new scope. Use `- Key: value` bullets for confirmed actors, in-scope surfaces, data/entities, integrations, constraints, explicit exclusions, and open decisions that later planning should preserve mechanically.\n```\n\nThe document should be detailed enough that another agent can plan implementation without reading the original conversation, while still preserving important uncertainty and scope boundaries.\n";
 
 // src/feature-implementation/create-feature-doc/prompt.ts
-var fragments5 = {
+var fragments4 = {
   methodology: feature_methodology_default.trimEnd(),
   featureDocFormat: feature_doc_format_default.trimEnd()
 };
 function createFeatureDocPrompt({ input }) {
-  return promptSections5(
-    fragments5.methodology,
-    fragments5.featureDocFormat,
-    section5("Conversation / feature request", input.conversation),
-    section5(
+  return promptSections4(
+    fragments4.methodology,
+    fragments4.featureDocFormat,
+    section4("Conversation / feature request", input.conversation),
+    section4(
+      "Distillation guardrails",
+      [
+        "Treat the conversation/request as evidence, not as permission to finish a product vision.",
+        "Preserve the user's actual must-have outcome, explicit constraints, uncertainty, and explicit non-goals; include implied scope limits only when tied to clear evidence.",
+        "Do not invent scope, acceptance criteria, integrations, personas, product decisions, or polish that the user did not ask for.",
+        "When a broad request includes brainstorming, ambitions, or adjacent possibilities, keep the confirmed current scope in the must-have/in-scope sections and move nonessential ideas to Optional / Future Ideas.",
+        "Use Structured Scope Facts for compact planning metadata copied or derived directly from the conversation; do not let that fact list add new requirements.",
+        "If a detail is unknown, record it as an assumption or open question instead of choosing an answer.",
+        "A later planning agent may implement the must-have and in-scope sections; optional/future ideas are context only and must not become story scope unless explicitly promoted by the user."
+      ].join("\n")
+    ),
+    section4(
       "Task",
-      'Write `feature-doc.md` following the format above, based on the conversation/request. Make it detailed enough that another agent can plan implementation without reading the original conversation. Preserve uncertainty explicitly in "Open Questions and Assumptions" \u2014 do not invent missing product decisions.'
+      "Write `feature-doc.md` following the format above, based on the conversation/request. Make it detailed enough that another agent can plan implementation without reading the original conversation, while preserving scope boundaries and uncertainty. Do not inflate the request into an idealized product spec."
     )
   );
 }
 
 // src/feature-implementation/create-feature-doc/step.ts
-var createFeatureDocStep = step7({ id: "create-feature-doc" }).prompt(createFeatureDocPrompt, {
+var createFeatureDocStep = step6({ id: "create-feature-doc" }).prompt(createFeatureDocPrompt, {
   agent: "featureWriter",
-  output: Document2
+  output: Document3
 }).do(async (featureDoc) => {
   await state5.set("featureDoc", featureDoc);
-  return createOrImproveImplementationDocStep({ featureDoc, attempt: 1 });
+  return createOrImproveImplementationStrategyStep({ featureDoc, attempt: 1 });
 });
 
-// src/feature-implementation/shared/input-schema.ts
-import { shape } from "@trailstep/authoring";
-var takeItAwayInput = shape({ conversation: "string" });
+// src/feature-implementation/initialize-take-it-away/step.ts
+var initializeTakeItAwayStep = step7({ id: "initialize-take-it-away" }).do(
+  async (input) => {
+    await state6.set(STORY_STATE_KEYS.workflowOptions, normalizeTakeItAwayWorkflowOptions(input));
+    await state6.set(STORY_STATE_KEYS.workflowWarnings, []);
+    return createFeatureDocStep(input);
+  }
+);
 
 // src/grill-it-away/grill/prompt.ts
-import { promptSections as promptSections6, section as section6 } from "@trailstep/authoring";
+import { promptSections as promptSections5, section as section5 } from "@trailstep/authoring";
 function grillPrompt() {
-  return promptSections6(
-    section6(
+  return promptSections5(
+    section5(
       "Role",
       "You are the interactive front door for starting a new feature in the current project. Open by asking the user what they want to build."
     ),
-    section6(
+    section5(
       "Task",
       "Keep asking follow-up questions until you are confident you understand the feature request well enough to hand off to a planning agent. There is no fixed checklist of required topics \u2014 use your judgment, and do not end the conversation prematurely just to finish quickly."
     ),
-    section6(
+    section5(
       "Output",
       "Your structured output's `conversation` field must contain the full raw transcript of the conversation so far, not a summary. Preserve as much of the actual back-and-forth as possible."
     )
@@ -760,13 +681,13 @@ var grillStep = step8({ id: "grill" }).prompt(grillPrompt, {
   agent: "grillingAgent",
   mode: "interactive",
   output: takeItAwayInput
-}).do((output) => createFeatureDocStep(output));
+}).do((output) => initializeTakeItAwayStep(output));
 
 // src/grill-it-away/workflow.ts
 var grillItAway = defineWorkflow({
   id: "grill-it-away",
   description: "Interactively grills the user until it understands the requested feature.",
-  inputShape: shape2({}),
+  inputShape: shape({}),
   outputShape: takeItAwayOutput,
   agents: {
     grillingAgent: {
@@ -774,26 +695,7 @@ var grillItAway = defineWorkflow({
       thinking: "medium",
       description: "Grills the user until it understands the requested feature."
     },
-    featureWriter: {
-      size: "medium",
-      thinking: "medium",
-      description: "Turns a conversation/feature request into a standalone feature doc."
-    },
-    planner: {
-      size: "large",
-      thinking: "high",
-      description: "Creates or improves the implementation doc: architecture-aware, TDD/vertical-slice/tracer-bullet story design."
-    },
-    reviewer: {
-      size: "large",
-      thinking: "high",
-      description: "Reviews isolated implementation docs and story diffs against methodology."
-    },
-    implementer: {
-      size: "medium",
-      thinking: "medium",
-      description: "Implements one story at a time using strict behavioral-red TDD."
-    }
+    ...featureImplementationAgents
   },
   start() {
     return grillStep();
@@ -807,30 +709,9 @@ var takeItAway = defineWorkflow2({
   description: "Turns an already-organic conversation/feature request into a reviewed implementation plan, then implements it story by story.",
   inputShape: takeItAwayInput,
   outputShape: takeItAwayOutput,
-  agents: {
-    featureWriter: {
-      size: "medium",
-      thinking: "medium",
-      description: "Turns a conversation/feature request into a standalone feature doc."
-    },
-    planner: {
-      size: "large",
-      thinking: "high",
-      description: "Creates or improves the implementation doc: architecture-aware, TDD/vertical-slice/tracer-bullet story design."
-    },
-    reviewer: {
-      size: "large",
-      thinking: "high",
-      description: "Reviews isolated implementation docs and story diffs against methodology."
-    },
-    implementer: {
-      size: "medium",
-      thinking: "medium",
-      description: "Implements one story at a time using strict behavioral-red TDD."
-    }
-  },
+  agents: featureImplementationAgents,
   start(input) {
-    return createFeatureDocStep(input);
+    return initializeTakeItAwayStep(input);
   }
 });
 export {