mandrel 1.72.0 → 1.73.0

package/.agents/docs/configuration.md

@@ -358,6 +358,19 @@ Read with `getCommands(config)` — see
 | ------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------- |
 | `docsContextFiles` | No       | `[]`    | Files the context-hydration engine includes when assembling agent prompts. Resolved against `paths.docsRoot`. |
 
+> **Entries are plain filenames, not globs.** Each entry is resolved as a
+> single file under `paths.docsRoot`; the loader does **not** expand glob
+> patterns. This matters for the decisions log: when a project adopts the
+> index + `decisions/` ADR-directory layout (see
+> [`documentation-and-adrs`](../skills/core/documentation-and-adrs/SKILL.md)),
+> the **index** `decisions.md` stays the mandatory-read and the per-ADR bodies
+> under `decisions/` are link-followed on demand — **index-only by default**.
+> Auto-loading every ADR body into each task's context would reintroduce the
+> bloat the directory split exists to remove. A project that genuinely wants
+> the full ADR set in mandatory context must opt in by listing the individual
+> ADR files explicitly (one filename per entry); there is no built-in
+> `decisions/*.md` glob.
+
 ---
 
 ## `github`

package/.agents/instructions.md

@@ -86,11 +86,13 @@ apply by checking the `.agents/rules/` directory (e.g.,
 ### G. Structured Configuration
 
 Refer to `.agentrc.json` to understand your operational limits (e.g., allowed
-auto-run permissions, default personas). Refer to the **Tech Stack** section
-of `docs/architecture.md` for the project's specific technology choices
-(database, ORM, API framework, auth provider, validation library, workspace
-paths). Project-specific technology context is intentionally kept out of
-`.agentrc.json`.
+auto-run permissions, default personas). For the project's specific
+technology choices (database, ORM, API framework, auth provider, validation
+library, workspace paths), refer to the project's Tech Stack inventory: a
+dedicated `docs/tech-stack.md` when present (the single-ownership convention),
+otherwise the **Tech Stack** section of `docs/architecture.md` (a numbered or
+decorated heading such as `## 1. Tech Stack` is fine). Project-specific
+technology context is intentionally kept out of `.agentrc.json`.
 
 ### H. Observability & Friction Telemetry
 
@@ -240,7 +242,13 @@ stops.
      data dictionary, decisions log, patterns, etc.) and replaces any
      hardcoded filename list. Resolve each entry against
      `project.paths.docsRoot` (default `docs/`) and skip silently
-     when an entry's file is absent.
+     when an entry's file is absent. The decisions log (`decisions.md`) may
+     be either a single-file dated-entry log or an **index** into a
+     `decisions/` ADR directory — both are first-class layouts (see
+     [`skills/core/documentation-and-adrs`](skills/core/documentation-and-adrs/SKILL.md)).
+     When it is an index, only the index is the mandatory-read; the
+     per-ADR bodies under `decisions/` are link-followed on demand
+     (index-only by default), not auto-loaded into every task's context.
    - **Conditional Reads**: When the task touches UI copy, layout, or
      routing and the corresponding file is present in the project, also
      read `docs/style-guide.md` and `docs/web-routes.md`. Skip both when

package/.agents/personas/devops-engineer.md

@@ -14,8 +14,10 @@ express it through code or documented configuration files.
 
 1. **Read Context:** Before making any infrastructure changes, analyze the
    existing CI/CD, deployment, and security configurations.
-2. **Follow Protocols:** Adhere strictly to the **Tech Stack** section of
-   `docs/architecture.md` and the `orchestration` block of `.agentrc.json`.
+2. **Follow Protocols:** Adhere strictly to the project's Tech Stack
+   inventory — a dedicated `docs/tech-stack.md` when present, otherwise the
+   **Tech Stack** section of `docs/architecture.md` — and the `orchestration`
+   block of `.agentrc.json`.
 3. **Validate Always:** For every task, determine how the change will be
    monitored and validated (logs, health checks, or test gates).
 

package/.agents/scripts/lib/bootstrap/issue-forms-template.js

@@ -0,0 +1,430 @@
+/**
+ * bootstrap/issue-forms-template — Story #4227 (framework-gap)
+ *
+ * Generates GitHub **Issue Forms** (`.github/ISSUE_TEMPLATE/story.yml` and
+ * `epic.yml`) derived from the canonical Story-body SSOT
+ * (`lib/story-body/story-body.js`). The forms exist so a human filing a
+ * Story/Epic in the GitHub web UI produces a body that round-trips through
+ * the same `story-body.parse()` agents rely on — closing the
+ * human↔agent ticket-shape gap.
+ *
+ * ## Why generated, not hand-authored
+ *
+ * Hand-authoring the forms would let the field headings drift from what
+ * `parse()` expects. Instead the form field set is derived from a single
+ * `HUMAN_INTENT_FIELDS` table here, and each field's heading is the exact
+ * section name the parser maps (`goal` → `## Goal`, etc.). The CI
+ * conformance lint (`lint-issue-body.js`) runs the real `parse()` against
+ * human-opened issues so the form and the parser cannot silently drift —
+ * the same model `ci-workflow-template.js` follows for `ci.yml`.
+ *
+ * ## Form fields ⊆ body schema
+ *
+ * The forms expose only the human **intent subset** — `goal`, `changes`,
+ * `acceptance`, `verify`, `references`. Machine-managed sections (the
+ * `<!-- meta: … -->` block, the frozen dispatch manifest, `agent::*`
+ * transitions) are deliberately absent; the runtime fills those. The
+ * relationship is "form fields ⊆ body schema," not "form == body."
+ *
+ * ## GitHub serialization contract (the lossy seam)
+ *
+ * GitHub Issue Forms render every `textarea`/`input` field as:
+ *
+ * ```text
+ * ### {label}
+ *
+ * {value}
+ * ```
+ *
+ * i.e. the field label becomes a level-3 heading (`###`), not the level-2
+ * (`##`) the canonical serializer emits. `story-body.parse()` accepts both
+ * heading levels (Story #4227 widened its heading regex), so a body
+ * assembled from form output round-trips. This is the single point where
+ * the form shape and the canonical serializer differ, and it is covered by
+ * the round-trip test that feeds simulated GitHub output back through
+ * `parse()`.
+ *
+ * @module bootstrap/issue-forms-template
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Directory (relative to a project root) GitHub reads issue forms from.
+ * Internal — the per-form path constants below are the exported surface.
+ */
+const ISSUE_TEMPLATE_RELATIVE_DIR = '.github/ISSUE_TEMPLATE';
+
+/**
+ * Relative paths of the two generated forms, surfaced as constants so tests
+ * and the bootstrap caller assert the canonical write targets without
+ * re-deriving them.
+ */
+export const STORY_FORM_RELATIVE_PATH = `${ISSUE_TEMPLATE_RELATIVE_DIR}/story.yml`;
+export const EPIC_FORM_RELATIVE_PATH = `${ISSUE_TEMPLATE_RELATIVE_DIR}/epic.yml`;
+
+/**
+ * The human **intent subset** of the Story-body schema, in canonical
+ * `parse()` section order. Each entry drives one form field. `heading` is
+ * the exact section name `story-body.parse()` maps (case-insensitive); the
+ * generated YAML uses it verbatim as the field `label` so GitHub's
+ * `### {label}` render produces a heading the parser recognises.
+ *
+ * Machine-managed body fields (`wide`, `reason_to_exist`,
+ * `estimated_test_files`, `depends_on` meta) are intentionally absent —
+ * the runtime fills those. `depends_on` is exposed as a free-text input
+ * that serializes to the `blocked by #N` footer `parse()` already reads.
+ *
+ * @type {Array<{
+ *   id: string,
+ *   heading: string,
+ *   label: string,
+ *   description: string,
+ *   placeholder: string,
+ *   required: boolean,
+ *   kind: 'textarea'|'input',
+ * }>}
+ */
+export const HUMAN_INTENT_FIELDS = [
+  {
+    id: 'goal',
+    heading: 'Goal',
+    label: 'Goal',
+    description: 'One sentence: the purpose of this work.',
+    placeholder:
+      'Add a conformance lint that parses human-opened issue bodies.',
+    required: true,
+    kind: 'textarea',
+  },
+  {
+    id: 'changes',
+    heading: 'Changes',
+    label: 'Changes',
+    description:
+      'Files or globs this work touches, one per line (e.g. `- src/foo.js: add handler`). Advisory — the binding contract is Acceptance/Verify.',
+    placeholder: '- src/foo.js: add the handler\n- tests/foo.test.js: cover it',
+    required: false,
+    kind: 'textarea',
+  },
+  {
+    id: 'acceptance',
+    heading: 'Acceptance',
+    label: 'Acceptance',
+    description:
+      'Observable, checkable criteria — one per line. This is the binding definition of done.',
+    placeholder:
+      '- The lint comments on a non-conformant body\n- A conformant body produces no comment',
+    required: true,
+    kind: 'textarea',
+  },
+  {
+    id: 'verify',
+    heading: 'Verify',
+    label: 'Verify',
+    description:
+      'Exact commands that prove the work, one per line (annotate the tier, e.g. `(unit)`).',
+    placeholder: '- npm test -- tests/foo.test.js (unit)',
+    required: true,
+    kind: 'textarea',
+  },
+  {
+    id: 'references',
+    heading: 'References',
+    label: 'References',
+    description: 'Read-only paths worth consulting, one per line. Optional.',
+    placeholder: '- docs/architecture.md',
+    required: false,
+    kind: 'textarea',
+  },
+];
+
+/**
+ * Escape a string for safe embedding inside a double-quoted YAML scalar.
+ * The generated YAML only ever quotes single-line scalars (labels,
+ * descriptions, placeholders), so we escape backslashes, double quotes,
+ * and collapse embedded newlines into the literal `\n` placeholder GitHub
+ * renders verbatim in the form preview.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function yamlQuote(value) {
+  const escaped = String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n');
+  return `"${escaped}"`;
+}
+
+/**
+ * Render a single Issue-Form field block (a `textarea` or `input`) from a
+ * {@link HUMAN_INTENT_FIELDS} descriptor. Indented to sit under the
+ * top-level `body:` sequence.
+ *
+ * @param {(typeof HUMAN_INTENT_FIELDS)[number]} field
+ * @returns {string}
+ */
+function renderFieldBlock(field) {
+  return [
+    `  - type: ${field.kind}`,
+    `    id: ${field.id}`,
+    '    attributes:',
+    `      label: ${yamlQuote(field.label)}`,
+    `      description: ${yamlQuote(field.description)}`,
+    `      placeholder: ${yamlQuote(field.placeholder)}`,
+    '    validations:',
+    `      required: ${field.required}`,
+  ].join('\n');
+}
+
+/**
+ * Render the shared `depends_on` input. Its value serializes (by the
+ * conformance lint / body assembler) into the `blocked by #N` footer lines
+ * `parse()` already extracts, so it stays out of the heading-mapped field
+ * set above.
+ *
+ * @returns {string}
+ */
+function renderDependsOnBlock() {
+  return [
+    '  - type: input',
+    '    id: depends_on',
+    '    attributes:',
+    '      label: "Blocked by"',
+    '      description: "Comma-separated issue refs this work depends on (e.g. #123, #456). Optional."',
+    '      placeholder: "#123, #456"',
+    '    validations:',
+    '      required: false',
+  ].join('\n');
+}
+
+/**
+ * @typedef {object} IssueFormOptions
+ * @property {string} [entryStateLabel='agent::review-spec'] - Lifecycle
+ *   entry-state label auto-applied alongside the `type::*` label so
+ *   human-filed tickets land in the same lane as agent-created ones.
+ * @property {string} [projectName] - Optional repo/project name woven into
+ *   the form description. Purely cosmetic.
+ */
+
+/**
+ * Shared header banner stamped on every generated form so the provenance
+ * (and the "regenerate, don't hand-edit" rule) travels with the file.
+ */
+const GENERATED_BANNER =
+  '# Generated by agents-bootstrap-github (Story #4227) from the Story-body SSOT\n' +
+  '# (.agents/scripts/lib/story-body/story-body.js). Do NOT hand-edit the\n' +
+  '# field set — field headings must stay in lockstep with story-body.parse().\n' +
+  '# Re-run /agents-bootstrap-github to refresh. The CI conformance lint\n' +
+  '# (lint-issue-body.js) is the drift guard between this form and the parser.';
+
+/**
+ * Render the GitHub Issue Form YAML for a given ticket type (`story` or
+ * `epic`). Both forms share the identical human-intent field set — the
+ * difference is the `type::` label and the form name/description — because
+ * `parse()` is type-agnostic over the body shape.
+ *
+ * The output is deterministic so the round-trip + idempotency tests assert
+ * on its exact shape.
+ *
+ * @param {'story'|'epic'} ticketType
+ * @param {IssueFormOptions} [opts]
+ * @returns {string}
+ */
+export function renderIssueForm(ticketType, opts = {}) {
+  if (ticketType !== 'story' && ticketType !== 'epic') {
+    throw new Error(
+      `renderIssueForm: ticketType must be 'story' or 'epic', got ${ticketType}`,
+    );
+  }
+  const entryStateLabel = opts.entryStateLabel ?? 'agent::review-spec';
+  const typeLabel = `type::${ticketType}`;
+  const titleCase = ticketType === 'story' ? 'Story' : 'Epic';
+  const projectSuffix = opts.projectName ? ` for ${opts.projectName}` : '';
+
+  const fieldBlocks = HUMAN_INTENT_FIELDS.map(renderFieldBlock).join('\n');
+
+  return `${GENERATED_BANNER}
+name: ${titleCase}
+description: File a ${titleCase} that round-trips through the Mandrel body parser${projectSuffix}.
+title: "[${titleCase}]: "
+labels:
+  - ${typeLabel}
+  - ${entryStateLabel}
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Fill the fields below. They serialize to the canonical Story body
+        the framework parses — keep each section's content under its own
+        heading. Machine-managed sections (dispatch manifest, lifecycle
+        transitions) are added by the runtime; you do not author them here.
+${fieldBlocks}
+${renderDependsOnBlock()}
+`;
+}
+
+/**
+ * Assemble a canonical Story-body markdown string from the per-field values
+ * a GitHub Issue Form yields (keyed by field `id`). This is the inverse of
+ * the form: it reconstructs what GitHub *would* serialize, using the
+ * canonical `## {Heading}` form so the result feeds straight into
+ * `story-body.parse()`. The conformance lint and the round-trip test use it
+ * to prove the form → parser contract without a live GitHub call.
+ *
+ * @param {Record<string, string>} values - Field id → raw textarea/input value.
+ * @returns {string} Canonical markdown body.
+ */
+export function assembleBodyFromFormValues(values = {}) {
+  const sections = [];
+  for (const field of HUMAN_INTENT_FIELDS) {
+    const raw = values[field.id];
+    if (typeof raw !== 'string' || raw.trim().length === 0) continue;
+    sections.push(`## ${field.heading}\n${raw.trim()}`);
+  }
+  let body = sections.join('\n\n');
+
+  const dependsRaw = values.depends_on;
+  if (typeof dependsRaw === 'string' && dependsRaw.trim().length > 0) {
+    const refs = dependsRaw
+      .split(',')
+      .map((r) => r.trim())
+      .filter(Boolean)
+      .map((r) => (r.startsWith('#') ? r : `#${r.replace(/^#/, '')}`));
+    if (refs.length > 0) {
+      const footer = ['---', ...refs.map((r) => `blocked by ${r}`)].join('\n');
+      body = `${body}\n\n${footer}`;
+    }
+  }
+  return body;
+}
+
+/**
+ * Relative path of the issue-body conformance workflow — the drift guard
+ * that runs `story-body.parse()` against human-opened tickets.
+ */
+export const CONFORMANCE_WORKFLOW_RELATIVE_PATH =
+  '.github/workflows/issue-body-conformance.yml';
+
+/**
+ * Render the CI workflow that runs the issue-body conformance lint
+ * (`lint-issue-body.js`) on opened/edited `type::story` / `type::epic`
+ * issues. This is the mechanism that prevents the generated forms and
+ * `story-body.parse()` from silently drifting (Story #4227 acceptance).
+ * Deterministic so the bootstrap test asserts its exact shape. Internal —
+ * exposed to consumers only through {@link ensureIssueForms}.
+ *
+ * @returns {string}
+ */
+function renderConformanceWorkflow() {
+  return `# Issue-body conformance lint (Story #4227).
+#
+# Generated by agents-bootstrap-github. Runs the canonical story-body parser
+# against human-opened type::story / type::epic issues and comments when the
+# body does not round-trip, instead of letting the supported human entry
+# points (e.g. /plan from an existing Epic ID) fail silently later. The lint
+# informs; it never fails the issue. Re-run /agents-bootstrap-github to refresh.
+name: Issue Body Conformance
+
+on:
+  issues:
+    types: [opened, edited]
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: issue-body-conformance-\${{ github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  conformance:
+    name: Parse issue body
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Lint issue body
+        env:
+          GH_TOKEN: \${{ github.token }}
+          ISSUE_NUMBER: \${{ github.event.issue.number }}
+          GITHUB_REPOSITORY: \${{ github.repository }}
+        run: node .agents/scripts/lint-issue-body.js
+`;
+}
+
+/**
+ * Write (or refresh) both issue forms into a project checkout. Idempotent at
+ * the byte level — mirrors {@link ensureCiWorkflow}'s contract:
+ *
+ * - file absent → `created`
+ * - byte-identical → `unchanged`
+ * - operator-edited (differs from the rendered template) → `custom-skip`
+ *   (the existing file is preserved; `rendered` is returned so the caller
+ *   can offer a diff)
+ *
+ * Network-free; safe under tests with a tmp `projectRoot`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {IssueFormOptions} [args.options]
+ * @param {boolean} [args.write=true] - When `false`, compute the would-be
+ *   actions without touching disk (dry-run).
+ * @returns {{ forms: Array<{ type: 'story'|'epic'|'conformance-workflow',
+ *             action: 'created'|'unchanged'|'custom-skip',
+ *             path: string, rendered: string }> }}
+ */
+export function ensureIssueForms(args) {
+  const projectRoot = args.projectRoot;
+  const options = args.options ?? {};
+  const write = args.write !== false;
+
+  // Each target pairs a ticket-type key with the rendered body. The
+  // conformance workflow is materialized alongside the forms because it is
+  // the forms' drift guard — they ship as one unit.
+  const targets = [
+    {
+      type: 'story',
+      rel: STORY_FORM_RELATIVE_PATH,
+      rendered: renderIssueForm('story', options),
+    },
+    {
+      type: 'epic',
+      rel: EPIC_FORM_RELATIVE_PATH,
+      rendered: renderIssueForm('epic', options),
+    },
+    {
+      type: 'conformance-workflow',
+      rel: CONFORMANCE_WORKFLOW_RELATIVE_PATH,
+      rendered: renderConformanceWorkflow(),
+    },
+  ];
+
+  const forms = targets.map(({ type, rel, rendered }) => {
+    const target = path.join(projectRoot, rel);
+
+    if (!fs.existsSync(target)) {
+      if (write) {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, rendered, 'utf8');
+      }
+      return { type, action: 'created', path: target, rendered };
+    }
+
+    const existing = fs.readFileSync(target, 'utf8');
+    if (existing === rendered) {
+      return { type, action: 'unchanged', path: target, rendered };
+    }
+    return { type, action: 'custom-skip', path: target, rendered };
+  });
+
+  return { forms };
+}

package/.agents/scripts/lib/bootstrap/manifest.js

@@ -177,6 +177,14 @@ export function buildMutationManifest(ctx = {}) {
         'Seed .agentrc.json from the bundled starter with the operator-supplied owner/repo/handle/base-branch.',
       reversible: true,
     },
+    {
+      phaseGroup: PHASE_GROUPS.REPO_CONFIG,
+      target: rel('.github', 'ISSUE_TEMPLATE'),
+      action: 'create',
+      detail:
+        'Generate the Story/Epic GitHub Issue Forms from the body SSOT so human-filed tickets round-trip through story-body.parse(). Operator-edited forms are preserved.',
+      reversible: true,
+    },
   );
 
   // --- quality-gates ----------------------------------------------------

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

@@ -18,6 +18,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 import { LEDGER_RELATIVE_PATH } from './install-ledger.js';
+import { ensureIssueForms } from './issue-forms-template.js';
 import { PHASE_GROUPS, previewMutationManifest } from './manifest.js';
 import { applyQualityBootstrap } from './quality-bootstrap.js';
 
@@ -439,6 +440,36 @@ export function ensureGitignore(ctx) {
   return { ...outcomes, path: target };
 }
 
+/**
+ * Materialize the generated GitHub Issue Forms
+ * (`.github/ISSUE_TEMPLATE/story.yml` + `epic.yml`) into the consumer
+ * project (Story #4227). Derived from the Story-body SSOT so a human-filed
+ * ticket round-trips through `story-body.parse()`. Idempotent and additive,
+ * mirroring `ensureGitignore`: byte-identical forms are `unchanged`,
+ * operator-edited forms are preserved (`custom-skip`). Honours `ctx.preview`
+ * (no writes) like the other phases.
+ *
+ * Returns the per-form action envelope keyed by ticket type.
+ *
+ * Internal — consumed only by the `issueForms` entry in
+ * {@link BOOTSTRAP_PHASES} below.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.projectRoot
+ * @param {boolean} [ctx.preview]
+ */
+function ensureIssueFormsPhase(ctx) {
+  const { forms } = ensureIssueForms({
+    projectRoot: ctx.projectRoot,
+    write: !ctx.preview,
+  });
+  const outcomes = {};
+  for (const form of forms) {
+    outcomes[form.type] = { action: form.action, path: form.path };
+  }
+  return outcomes;
+}
+
 /**
  * Step 5 — Run the sync script. Step 6 (parity) is enforced by the
  * sync script itself (it removes stale entries and writes from the
@@ -690,6 +721,11 @@ export const BOOTSTRAP_PHASES = Object.freeze([
     phaseGroup: PHASE_GROUPS.IDE_WIRING,
     run: (ctx) => ensureGitignore(ctx),
   },
+  {
+    name: 'issueForms',
+    phaseGroup: PHASE_GROUPS.REPO_CONFIG,
+    run: (ctx) => ensureIssueFormsPhase(ctx),
+  },
   {
     name: 'sync',
     phaseGroup: PHASE_GROUPS.IDE_WIRING,

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

@@ -342,8 +342,11 @@ function splitSections(markdown) {
       }
     }
 
-    // Detect `## Heading` lines
-    const headingMatch = line.match(/^##\s+(\w+)\s*$/i);
+    // Detect `## Heading` (canonical) or `### Heading` lines. GitHub Issue
+    // Forms (Story #4227) render every field label as a level-3 heading
+    // (`### Goal`), not the level-2 the canonical serializer emits, so the
+    // parser accepts both levels. Any other heading depth is ignored.
+    const headingMatch = line.match(/^#{2,3}\s+(\w+)\s*$/i);
     if (headingMatch) {
       const name = headingMatch[1].toLowerCase();
       if (HEADING_TO_FIELD.has(name)) {

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-story.md

@@ -97,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

package/docs/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.73.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.72.0...mandrel-v1.73.0) (2026-06-17)
+
+
+### Added
+
+* generate GitHub issue forms from the Story/Epic body SSOT (human↔agent ticket consistency) ([#4227](https://github.com/dsj1984/mandrel/issues/4227)) ([#4233](https://github.com/dsj1984/mandrel/issues/4233)) ([d42b0cb](https://github.com/dsj1984/mandrel/commit/d42b0cb6122f46d8528d4bbb3793f27be2854bc1))
+* **plan:** robust tech-stack hydrator resolution (refs [#4228](https://github.com/dsj1984/mandrel/issues/4228)) ([#4230](https://github.com/dsj1984/mandrel/issues/4230)) ([4f1ad3c](https://github.com/dsj1984/mandrel/commit/4f1ad3c13b9a50f4e436d63282c7f6c2f461ab0e))
+
 ## [1.72.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.71.0...mandrel-v1.72.0) (2026-06-17)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.72.0",
+  "version": "1.73.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",