mandrel 1.71.0 → 1.73.0

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

@@ -227,13 +227,51 @@ export function buildContextEnvelope({
 }
 
 /**
- * Strip the leading "Tech Stack" section of `docs/architecture.md` for
- * the host LLM. Returns `null` when the file or section is missing.
+ * Extract the "Tech Stack" `##` section from a markdown document.
+ *
+ * Tolerates a numbered / decorated heading (`## 1. Tech Stack`,
+ * `## Tech Stack`, etc.) and a section that is the final `##` in the
+ * file (the terminator matches the next `##` heading **or** end-of-file).
+ * Returns the matched section text (re-headed to a clean `## Tech Stack`)
+ * or `null` when no Tech Stack heading is present.
+ *
+ * @param {string} content
+ * @returns {string|null}
+ */
+function extractTechStackSection(content) {
+  const match = content.match(
+    /^##\s+(?:\d+[.)]\s+)?Tech Stack\s*$([\s\S]*?)(?=^##\s+|(?![\s\S]))/m,
+  );
+  return match ? `## Tech Stack${match[1]}`.trim() : null;
+}
+
+/**
+ * Resolve the project's Tech Stack inventory for the host LLM, in order:
+ *
+ *   1. A dedicated `docs/tech-stack.md` when present (the emerging
+ *      single-ownership convention — WHAT in tech-stack.md, HOW in
+ *      architecture.md, WHY in the ADRs). Its full body is returned.
+ *   2. Otherwise, the `## Tech Stack` section of `docs/architecture.md`,
+ *      tolerating a numbered/decorated heading and a final-section
+ *      heading (no following `##` required).
+ *
+ * Returns `null` when neither source yields an inventory.
  *
  * @param {string} projectRoot
  * @returns {Promise<string|null>}
  */
 export async function readTechStackSummary(projectRoot) {
+  const dedicatedPath = path.join(projectRoot, 'docs', 'tech-stack.md');
+  try {
+    const dedicated = await readFile(dedicatedPath, 'utf8');
+    const trimmed = dedicated.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  } catch {
+    // No dedicated tech-stack.md — fall through to architecture.md.
+  }
+
   const archPath = path.join(projectRoot, 'docs', 'architecture.md');
   let content;
   try {
@@ -241,6 +279,5 @@ export async function readTechStackSummary(projectRoot) {
   } catch {
     return null;
   }
-  const match = content.match(/^##\s+Tech Stack\s*$([\s\S]*?)(?=^##\s+\S)/m);
-  return match ? `## Tech Stack${match[1]}`.trim() : null;
+  return extractTechStackSection(content);
 }

package/.agents/scripts/lint-issue-body.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// .agents/scripts/lint-issue-body.js
+/**
+ * Issue-body conformance lint (Story #4227).
+ *
+ * Runs the canonical `story-body.parse()` against a human-opened
+ * `type::story` / `type::epic` issue body and reports whether the body
+ * round-trips. This is the drift guard between the generated GitHub Issue
+ * Forms (`lib/bootstrap/issue-forms-template.js`) and the parser: if a
+ * human files a ticket whose body `parse()` rejects (or which lacks the
+ * binding `goal` / `acceptance` / `verify` sections), the lint surfaces a
+ * **comment** on the issue rather than failing silently — the supported
+ * human entry points (`/plan` from an existing Epic ID, the qa-assist →
+ * `/plan` handoff) depend on a parseable body.
+ *
+ * ## Design
+ *
+ * - `evaluateIssueBody(body)` is **pure** (no I/O): it parses the body and
+ *   returns a structured conformance verdict. This is the unit-tested core.
+ * - The CLI wrapper reads the issue body + labels (via `gh` or env), runs
+ *   the evaluator, and posts/updates a single marker comment when the body
+ *   is non-conformant. Network-touching, exercised in CI.
+ *
+ * GitHub Issue Forms render a skipped optional field as the literal
+ * `_No response_`; the evaluator strips that sentinel so an empty optional
+ * section does not masquerade as content.
+ *
+ * @module lint-issue-body
+ */
+
+import { spawnSync } from 'node:child_process';
+import { runAsCli } from './lib/cli-utils.js';
+import { parse, StoryBodyParseError } from './lib/story-body/story-body.js';
+
+/**
+ * Marker that identifies the lint's own comment so re-runs update rather
+ * than duplicate it.
+ */
+export const LINT_COMMENT_MARKER = '<!-- mandrel:issue-body-conformance -->';
+
+/**
+ * The binding sections every conformant ticket body MUST carry. `changes`
+ * and `references` are advisory (per the Engineer persona's implementation
+ * latitude), so they are not required here.
+ */
+const REQUIRED_SECTIONS = [
+  { field: 'goal', label: 'Goal' },
+  { field: 'acceptance', label: 'Acceptance' },
+  { field: 'verify', label: 'Verify' },
+];
+
+/**
+ * Strip the GitHub Issue Form empty-field sentinel so a skipped optional
+ * field is treated as absent rather than literal content.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+function stripNoResponseSentinel(body) {
+  return body
+    .split('\n')
+    .filter((line) => line.trim() !== '_No response_')
+    .join('\n');
+}
+
+/**
+ * @typedef {object} ConformanceVerdict
+ * @property {boolean}  conformant   - True when the body parses AND carries
+ *   every required section with non-empty content.
+ * @property {string[]} problems     - Human-readable problem statements
+ *   (empty when conformant).
+ * @property {string[]} warnings     - Non-fatal parser warnings surfaced for
+ *   transparency (e.g. legacy-path-entry).
+ * @property {boolean}  parseFailed  - True when `parse()` threw (fail-closed).
+ */
+
+/**
+ * Evaluate an issue body for conformance with the canonical Story-body
+ * schema. Pure — no I/O. Fail-closed parse errors are caught and reported
+ * as a non-conformant verdict (never thrown), because the caller's job is
+ * to *comment*, not to crash CI.
+ *
+ * @param {string} body - Raw issue-body markdown.
+ * @returns {ConformanceVerdict}
+ */
+export function evaluateIssueBody(body) {
+  if (typeof body !== 'string' || body.trim().length === 0) {
+    return {
+      conformant: false,
+      problems: ['The issue body is empty.'],
+      warnings: [],
+      parseFailed: true,
+    };
+  }
+
+  const cleaned = stripNoResponseSentinel(body);
+
+  let result;
+  try {
+    result = parse(cleaned);
+  } catch (err) {
+    if (err instanceof StoryBodyParseError) {
+      return {
+        conformant: false,
+        problems: [
+          `The body could not be parsed into the canonical schema: ${err.message}`,
+        ],
+        warnings: [],
+        parseFailed: true,
+      };
+    }
+    throw err;
+  }
+
+  const problems = [];
+
+  // A legacy string body parses but carries no structured sections — that
+  // is exactly the human-filed shape this lint exists to catch.
+  if (result.info.isLegacyStringBody) {
+    problems.push(
+      'The body has no recognised `## Goal` / `## Acceptance` / `## Verify` sections. ' +
+        'File via the Story/Epic issue form so it round-trips through the parser.',
+    );
+  }
+
+  for (const { field, label } of REQUIRED_SECTIONS) {
+    const value = result.body[field];
+    const empty =
+      value == null ||
+      (typeof value === 'string' && value.trim().length === 0) ||
+      (Array.isArray(value) && value.length === 0);
+    if (empty) {
+      problems.push(
+        `The required \`## ${label}\` section is missing or empty.`,
+      );
+    }
+  }
+
+  return {
+    conformant: problems.length === 0,
+    problems,
+    warnings: result.warnings,
+    parseFailed: false,
+  };
+}
+
+/**
+ * Render the markdown comment body the lint posts on a non-conformant
+ * issue. Carries {@link LINT_COMMENT_MARKER} so re-runs update in place.
+ *
+ * @param {ConformanceVerdict} verdict
+ * @returns {string}
+ */
+export function renderConformanceComment(verdict) {
+  const lines = [
+    LINT_COMMENT_MARKER,
+    '### ⚠️ Ticket body does not round-trip through the Mandrel parser',
+    '',
+    'Agents build ticket bodies from a canonical schema that this body does ' +
+      'not match, so the supported human entry points (e.g. `/plan` from an ' +
+      'existing Epic ID) will reject it. Please fix the following:',
+    '',
+    ...verdict.problems.map((p) => `- ${p}`),
+    '',
+    'The quickest fix is to refile using the **Story** or **Epic** issue form ' +
+      '(New issue → pick the template), which lays out the required sections.',
+  ];
+  if (verdict.warnings.length > 0) {
+    lines.push(
+      '',
+      '<details><summary>Parser warnings (non-blocking)</summary>',
+      '',
+      ...verdict.warnings.map((w) => `- ${w}`),
+      '',
+      '</details>',
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Thin `gh` wrapper. Returns the trimmed stdout, throwing on a non-zero
+ * exit so the CLI surfaces the failure (orchestration-error-handling rule).
+ *
+ * @param {string[]} args
+ * @returns {string}
+ */
+function gh(args) {
+  const res = spawnSync('gh', args, { encoding: 'utf8' });
+  if (res.status !== 0) {
+    throw new Error(
+      `gh ${args.join(' ')} failed (exit ${res.status}): ${res.stderr?.trim() ?? ''}`,
+    );
+  }
+  return (res.stdout ?? '').trim();
+}
+
+/**
+ * CLI entry. Reads the target issue (number from `--issue` or the
+ * `ISSUE_NUMBER` env), fetches its body + labels, and — when the body is
+ * non-conformant — upserts a single marker comment. Always exits 0 (the
+ * lint *informs*, it does not block), unless an unexpected I/O error occurs.
+ *
+ * Flags:
+ *   --issue <n>   Issue number (defaults to env ISSUE_NUMBER).
+ *   --repo <o/r>  owner/repo (defaults to env GITHUB_REPOSITORY).
+ *   --dry-run     Evaluate + print the verdict, never touch GitHub.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const get = (flag) => {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const dryRun = args.includes('--dry-run');
+  const issue = get('--issue') ?? process.env.ISSUE_NUMBER;
+  const repo = get('--repo') ?? process.env.GITHUB_REPOSITORY;
+
+  if (!issue) {
+    throw new Error('lint-issue-body: --issue <n> or ISSUE_NUMBER is required');
+  }
+
+  const repoArgs = repo ? ['--repo', repo] : [];
+  const raw = gh([
+    'issue',
+    'view',
+    String(issue),
+    ...repoArgs,
+    '--json',
+    'body,labels',
+  ]);
+  const { body, labels } = JSON.parse(raw);
+  const labelNames = (labels ?? []).map((l) => l.name);
+  const isTicket =
+    labelNames.includes('type::story') || labelNames.includes('type::epic');
+
+  if (!isTicket) {
+    // Machine-parsable JSON envelope → process.stdout.write (not console.log),
+    // per the .agents/scripts logging contract (tests/enforcement/no-console).
+    process.stdout.write(
+      `${JSON.stringify({ issue: Number(issue), skipped: 'not-a-ticket' })}\n`,
+    );
+    return;
+  }
+
+  const verdict = evaluateIssueBody(body ?? '');
+  process.stdout.write(
+    `${JSON.stringify({
+      issue: Number(issue),
+      conformant: verdict.conformant,
+      problems: verdict.problems,
+    })}\n`,
+  );
+
+  if (verdict.conformant || dryRun) return;
+
+  const comment = renderConformanceComment(verdict);
+  gh(['issue', 'comment', String(issue), ...repoArgs, '--body', comment]);
+}
+
+runAsCli(import.meta.url, main, { source: 'lint-issue-body' });

package/.agents/skills/core/documentation-and-adrs/SKILL.md

@@ -12,7 +12,7 @@ description:
 
 - Document the **why**, not the what. Capture context, constraints, alternatives considered, and trade-offs — code already shows what was built.
 - Write an ADR for any decision that would be expensive to reverse (framework choice, data model, auth strategy, API architecture, hosting platform).
-- Store ADRs at `docs/decisions/` with sequential numbering (`ADR-001`, `ADR-002`, …) and the canonical sections: **Status, Date, Context, Decision, Alternatives Considered, Consequences**.
+- Mandrel ships **two first-class decisions-log layouts** — pick one at onboarding (see [Decisions-log layouts](#decisions-log-layouts)): the **single-file dated-entry** `docs/decisions.md` (default; best for small projects) or the **index + `docs/decisions/` directory** (MADR-style, one file per ADR; best once the log outgrows a single file). Either way, the canonical ADR sections are **Status, Date, Deciders, Context, Decision, (Alternatives Considered), Consequences**.
 - Mark an ADR's status as `Accepted`, `Superseded by ADR-XXX`, or `Deprecated`. Never silently delete an ADR — supersede it.
 - Do **not** document obvious code; do **not** restate what the code already says. Stale or redundant docs are worse than no docs.
 - Comments explain **non-obvious intent** (the why). If a comment describes what the code does, refactor the code instead.
@@ -54,9 +54,41 @@ highest-value documentation you can write.
 - Choosing between build tools, hosting platforms, or infrastructure
 - Any decision that would be expensive to reverse
 
+### Decisions-log layouts
+
+Mandrel ships **two supported layouts** for the decisions log. Both keep the
+mandatory-read file named `docs/decisions.md` (the `project.docsContextFiles`
+default), so `config-resolver.js` and every `.agents/` reference resolve the
+same regardless of which you pick — only the **shape** differs. Choose one at
+onboarding:
+
+| Layout                              | Shape                                                                 | Template(s)                                                                                                | When to use                                                                       |
+| ----------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Single-file dated entries** (default) | One `decisions.md` of append-only `## YYYY-MM-DD — title` entries     | [`templates/docs/decisions.md`](../../../templates/docs/decisions.md)                                      | Small projects; a handful of decisions; you want everything in one scannable file. |
+| **Index + `decisions/` directory**  | `decisions.md` is a one-row-per-ADR **index**; each ADR is `decisions/NNNN-*.md` | [`templates/docs/decisions.index.md`](../../../templates/docs/decisions.index.md) + [`templates/docs/decisions/_template.md`](../../../templates/docs/decisions/_template.md) | The log has outgrown a single file (dozens of ADRs); you want per-decision history and `git blame` per ADR. |
+
+To adopt the directory layout, replace `decisions.md` with the index variant,
+create a `decisions/` directory beside it, and scaffold each ADR from
+`decisions/_template.md` using zero-padded sequential numbering
+(`0001-*.md`, `0002-*.md`, …).
+
+> **Loading model (resolved design question).** The decisions **index** is the
+> only artifact loaded into mandatory task context — individual ADR bodies
+> under `decisions/` are **lazy / link-followed**, not auto-loaded. This is
+> **index-only by default**: auto-loading every ADR body into each task's
+> context would reintroduce exactly the bloat the split exists to remove.
+> `project.docsContextFiles` entries are plain filenames resolved against the
+> docs root (no glob expansion in the loader), so the index ships as a normal
+> mandatory-read with no loader change. A project that genuinely wants the full
+> ADR set in mandatory context can add explicit per-file entries (or a
+> `decisions/*.md`-style entry if it maintains its own globbing) as a
+> deliberate opt-in, but that is the exception, not the default.
+
 ### ADR Template
 
-Store ADRs in `docs/decisions/` with sequential numbering:
+In the **single-file** layout, append a short dated entry per the
+`templates/docs/decisions.md` format. In the **directory** layout, store ADRs
+in `docs/decisions/` with sequential numbering:
 
 ```markdown
 # ADR-001: Use PostgreSQL for primary database
@@ -69,6 +101,10 @@ Accepted | Superseded by ADR-XXX | Deprecated
 
 2025-01-15
 
+## Deciders
+
+The platform team (architect + two senior engineers).
+
 ## Context
 
 We need a primary database for the task management application. Key

package/.agents/templates/docs/architecture.md

@@ -27,4 +27,7 @@ Describe the top-level directories and their responsibilities.
 
 ## Key Decisions
 
-Link to `decisions.md` for the architectural decision log.
+Link to `decisions.md` for the architectural decision log. Mandrel supports two
+first-class layouts for it: a single-file dated-entry `decisions.md` (default)
+or an index + `decisions/` ADR directory — see
+[`.agents/skills/core/documentation-and-adrs/SKILL.md`](../../skills/core/documentation-and-adrs/SKILL.md).

package/.agents/templates/docs/decisions/_template.md

@@ -0,0 +1,35 @@
+# ADR-NNNN: <short decision title>
+
+> Copy this file to `decisions/NNNN-<kebab-title>.md` (zero-padded, sequential
+> — `0001`, `0002`, …) and add a matching row to the `decisions.md` index.
+> ADRs are **append-only**: never rewrite or delete an accepted ADR — supersede
+> it with a new one and flip this one's **Status** to `Superseded by ADR-NNNN`.
+
+## Status
+
+Accepted
+
+<!-- One of: Proposed | Accepted | Superseded by ADR-NNNN | Deprecated -->
+
+## Date
+
+YYYY-MM-DD
+
+## Deciders
+
+<!-- Who made the call (names / roles / "the team"). -->
+
+## Context
+
+<!-- What forced the decision: the constraint, problem, or trade-off. What
+were the requirements and the forces in tension? -->
+
+## Decision
+
+<!-- What was chosen, stated plainly. -->
+
+## Consequences
+
+<!-- What this enables and what it costs going forward — positive and negative.
+Include follow-on work, new constraints, and anything a future reader must
+know before reversing this. -->

package/.agents/templates/docs/decisions.index.md

@@ -0,0 +1,49 @@
+# Architectural Decisions Log (Index)
+
+> **Directory-layout variant.** This is the MADR-style **index + `decisions/`
+> directory** alternative to the default single-file dated-entry
+> [`decisions.md`](decisions.md). To adopt it, replace your `decisions.md` with
+> this index, create a `decisions/` directory next to it, and scaffold ADRs
+> from [`decisions/_template.md`](decisions/_template.md). This file stays named
+> `decisions.md` so it remains the `project.docsContextFiles` mandatory-read
+> every `.agents/` reference and `config-resolver.js` already point at — only
+> its **shape** changes from dated entries to an index.
+>
+> Prefer this layout once the single-file log grows past a few dozen entries
+> (athportal hit ~1060 lines / 32 ADRs before splitting). For small projects,
+> keep the default single-file template instead.
+
+## How this layout works
+
+- **This file is the index** — one row per ADR, newest at the top. It is the
+  mandatory-read; agents scan the index and follow the link into a specific
+  ADR only when the detail is relevant (index-only by default — see
+  [Loading model](#loading-model)).
+- **Each ADR is its own file** under `decisions/`, named
+  `NNNN-<kebab-title>.md` with a zero-padded sequential number.
+- **ADRs are append-only.** Never rewrite or delete an accepted ADR — write a
+  new one and flip the old one's status to `Superseded by ADR-NNNN`.
+- **Scaffold new ADRs** from [`decisions/_template.md`](decisions/_template.md)
+  (Status / Date / Deciders / Context / Decision / Consequences).
+
+## Loading model
+
+This index is the only decisions artifact loaded into mandatory task context
+(`project.docsContextFiles`). Individual ADR bodies under `decisions/` are
+**lazy / link-followed**, not auto-loaded — that is the whole point of the
+split: keep the per-task context lean while preserving the full decision
+history on disk. If a project genuinely wants the entire ADR set in mandatory
+context, it can add an explicit `decisions/*.md`-style entry to
+`project.docsContextFiles` as an opt-in (see the configuration reference), but
+index-only is the intended default.
+
+## Index
+
+| ADR      | Title                                    | Status   | Date       |
+| -------- | ---------------------------------------- | -------- | ---------- |
+| ADR-0001 | _Example — replace with your first ADR_  | Proposed | YYYY-MM-DD |
+
+_Add new rows above this line, newest first. Once you scaffold a real ADR from
+[`decisions/_template.md`](decisions/_template.md) into
+`decisions/0001-<title>.md`, link the ADR id to that file (e.g.
+`[ADR-0001](decisions/0001-<title>.md)`) and delete this example row._

package/.agents/templates/docs/decisions.md

@@ -4,6 +4,17 @@
 > decisions here as dated entries. This file is one of the
 > `project.docsContextFiles` mandatory-reads — agents consult it before every
 > task to avoid re-litigating settled choices.
+>
+> **Two supported layouts — pick one at onboarding.** This single-file
+> dated-entry layout is the **default**, ideal for small projects. Once the
+> log grows past a few dozen entries it becomes a context-bloat liability;
+> at that point switch to the first-class **index + `decisions/` directory**
+> variant ([`decisions.index.md`](decisions.index.md) + the ADR scaffold at
+> [`decisions/_template.md`](decisions/_template.md)). Both layouts keep the
+> file named `decisions.md` so the `project.docsContextFiles` mandatory-read
+> resolves the same; only the shape differs. See
+> [`.agents/skills/core/documentation-and-adrs/SKILL.md`](../../skills/core/documentation-and-adrs/SKILL.md)
+> for when to choose which.
 
 ## Format
 

package/.agents/workflows/helpers/plan-epic.md

@@ -74,14 +74,22 @@ Phase 5 (Re-Plan Detection).
    one-pager feeds the scope-triage gate below, whose verdict folds into
    the **same** Phase 1 HITL confirmation. Do not stop twice.
 
-3. **HITL stop — confirm the sharpened one-pager**: Display the one-pager
-   to the operator and **STOP**. Do not proceed to Phase 2 until the
-   user explicitly confirms the direction. This is the same gate the
-   skill's own Phase 3 enforces; surfacing it here makes the wait
+3. **HITL stop — confirm the sharpened one-pager** (**gate #1**): Display
+   the one-pager to the operator and **STOP**. Do not proceed to Phase 2
+   until the user explicitly confirms the direction. This is the same gate
+   the skill's own Phase 3 enforces; surfacing it here makes the wait
    contract visible to `/plan` callers. When the Phase 1.5 verdict is
    `story` or `borderline`, this stop carries the three-way choice the
    triage gate defines (below) instead of a plain confirm.
 
+   > **`--yes` (headless) auto-proceed.** When `/plan` was invoked with
+   > `--yes`, this gate does **not** STOP: the one-pager confirm resolves as
+   > **approved** and the run continues to Phase 2. A `story` / `borderline`
+   > triage verdict resolves to its **Recommended** branch (below) rather
+   > than prompting the three-way choice. Display the one-pager and the
+   > verdict line for the record, then proceed without waiting. See
+   > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
+
 ## Phase 1.5: Scope Triage (ideation path only)
 
 This phase runs **only** on the ideation path, immediately after Phase 1
@@ -124,6 +132,15 @@ skill states once).
    avoid the ceremony tax of pushing a story-sized scope through the full Epic
    pipeline.
 
+   > **`--yes` (headless) exception.** "Never auto-route" is the interactive
+   > contract. Under `--yes` the operator has *pre-authorized* the
+   > recommendation: the three-way choice resolves to its **Recommended**
+   > branch deterministically — `single Story` hands off to
+   > `/plan --from-notes <path>` (carrying `--yes` so the receiving story
+   > path also auto-proceeds), and an `epic` verdict simply continues to
+   > Phase 2. No operator wait. This is the only sanctioned auto-route, and it
+   > exists solely to make `/plan` driveable headlessly.
+
 ## Phase 2: Cross-Epic Duplicate Search
 
 Runs immediately after Phase 1 (and only on the s-plan-ideation path).
@@ -396,6 +413,19 @@ for the scoring logic.
    permission") is honored — no `gh issue edit` call until the
    operator confirms.
 
+   > **`--yes` (headless) auto-proceed.** This refinement-diff confirm is the
+   > clarity-gate face of `/plan`'s **gate #1** on the existing-Epic
+   > (`/plan <epicId>`) path — it is an operator *wait*, not a deterministic
+   > validator (the deterministic half is the section-presence *scoring* in
+   > step 1, which always runs). When `/plan` was invoked with `--yes`, this
+   > confirm does **not** STOP: the sharpened body is auto-**approved** and the
+   > run proceeds to step 6 (persist). The blast-radius note is still displayed
+   > for the record; only the operator wait is suppressed. This keeps
+   > `/plan <epicId> --yes` driveable headlessly even when the Epic body needs
+   > refinement (`gh issue edit` still runs only via the step 6 persist call,
+   > which the auto-approval authorizes). See
+   > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
+
 6. **Persist**: On approval, run the persist mode:
 
    ```bash
@@ -556,18 +586,31 @@ for the scoring logic.
      `planningRisk.requiresReview` unless the operator passed
      `--force-review`:
      - **High risk** (`requiresReview === true`) or **operator override**
-       (`--force-review`): **STOP**. Ask the USER to review the generated
-       PRD, Tech Spec, and Acceptance Spec on GitHub. Approval is the
-       user's verbal OK in this session — the three context tickets stay
+       (`--force-review`) — **gate #2**: **STOP**. Ask the USER to review the
+       generated PRD, Tech Spec, and Acceptance Spec on GitHub. Approval is
+       the user's verbal OK in this session — the three context tickets stay
        **open** through delivery and are closed automatically by
        `/deliver` when the Epic PR opens. Do NOT proceed
        to decomposition until the user confirms the plan is accurate.
+
+       > **`--yes` (headless) auto-proceed.** When `/plan` was invoked with
+       > `--yes`, this review gate does **not** STOP, even when
+       > `requiresReview === true` or `--force-review` was also passed: the
+       > review resolves as **approved** and the run **continues directly to
+       > Phase 8**, exactly as the low-risk auto-proceed branch below. The
+       > three context tickets stay **open** through delivery as usual; only
+       > the operator *wait* is suppressed. This is `/plan`'s **gate #2** —
+       > the second and last HITL STOP `--yes` suppresses. `--yes` does
+       > **not** alter risk routing or the review criteria themselves; it
+       > only forces a proceed where this gate would otherwise STOP. See
+       > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
      - **Low risk** (`requiresReview === false` and no `--force-review`):
        Emit the auto-proceed message from the persist stdout
        (`reviewRouting.operatorMessage`) and **continue directly to Phase 8**
        without an extra review stop. The Epic still carries
        `agent::review-spec` until decomposition completes; the routing
-       decision is recorded in the `epic-plan-state` checkpoint.
+       decision is recorded in the `epic-plan-state` checkpoint. (`--yes` is
+       a no-op on this branch — there is no STOP to suppress.)
 
 5. **Tech Spec freshness check (advisory)**: After the Tech Spec issue
    is created, `epic-plan-spec.js` runs

package/.agents/workflows/helpers/plan-story.md

@@ -68,6 +68,9 @@ to authoring the standalone Story body from the handed-off one-pager.
 
 # Inspect the draft body without creating an Issue:
 /plan --dry-run --body temp/single-story-draft.md
+
+# Headless / non-interactive (auto-proceeds the draft-confirm gate):
+/plan --idea "rip out the unused TaskBodyMigrator export" --yes
 ```
 
 ## Phase 1 — Emit Context
@@ -94,7 +97,7 @@ Envelope fields (`kind: "story-plan-context"`, `version: 1`):
 | `bodyTemplate`         | Contents of `.agents/templates/single-story-body.md`.     |
 | `requiredSections`     | `["Context", "Acceptance Criteria", "Out of Scope", "Notes"]`. |
 | `duplicateCandidates`  | Ranked open Stories whose titles fuzzy-match the seed.    |
-| `techStack`            | The `## Tech Stack` section of `docs/architecture.md`.    |
+| `techStack`            | The project's Tech Stack inventory, resolved in order: `docs/tech-stack.md` (full body) when present, else the `## Tech Stack` section of `docs/architecture.md` (numbered/decorated and final-section headings tolerated). |
 | `deliverContract`      | Workflow path + required/forbidden labels and references. |
 
 ### Refine heuristic
@@ -153,8 +156,18 @@ add a second stop.
 
 Display the draft to the operator and **STOP**. Do not call the persist phase
 until the operator explicitly confirms the draft. This mirrors the HITL gate
-`/plan` Phase 3 enforces before opening the Epic Issue. The scope-triage
-verdict folds into this same stop:
+`/plan` Phase 3 enforces before opening the Epic Issue. This is the
+story-path face of `/plan`'s **gate #1** (the ideation one-pager /
+scope-triage confirm). The scope-triage verdict folds into this same stop:
+
+> **`--yes` (headless) auto-proceed.** When `/plan` was invoked with `--yes`,
+> this gate does **not** STOP: the draft confirm resolves as **approved** and
+> the run proceeds to Phase 3 (persist). An `epic` verdict resolves to its
+> **Recommended** branch — escalate to `/plan --idea` (carrying `--yes`),
+> abandoning the draft — rather than prompting the three-way choice. Display
+> the draft and the verdict line for the record, then proceed without
+> waiting. See
+> [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
 
 - **`story` verdict (or gate skipped via handoff)** → no extra prompt. The
   operator confirms the draft as usual and the run proceeds to Phase 3
@@ -177,6 +190,9 @@ verdict folds into this same stop:
 
   **Never auto-route.** The verdict is advisory; the operator always decides,
   and no `agent::*` / label transition happens on either side of the choice.
+  (**`--yes` exception:** headless mode pre-authorizes the **Recommended**
+  branch deterministically — see the `--yes` note above — the only sanctioned
+  auto-route, present solely to make `/plan` driveable without an operator.)
 
 ## Phase 3 — Persist (`gh issue create`)