mandrel 1.71.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/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -26,6 +26,15 @@
  * "clean sprint" retro trailer), emit `epic.merge.ready`. Otherwise emit
  * `epic.merge.blocked` with a non-empty reason.
  *
+ * Code-review parse-miss policy (Story #4222): a code-review comment that is
+ * present but whose severity bullets cannot be parsed is treated as a DISTINCT
+ * condition — surfaced via the `codeReviewUnparseable` signal — and FAILS OPEN
+ * rather than blocking. Failing closed on a format miss is indistinguishable,
+ * to the operator and to downstream telemetry, from a real disqualifying
+ * finding; a parser miss must never masquerade as "the signal said no" inside
+ * a generic `epic.merge.blocked`. Genuine critical/high findings still block,
+ * because those require the counts to have parsed.
+ *
  * Critical contract:
  *   - The verdict for any given input set is byte-identical to the
  *     pre-inlining legacy module's output — this file is its
@@ -229,11 +238,30 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
     : { critical: null, high: null, medium: null, suggestion: null };
   if (!codeReviewFound) {
     reasons.push('code-review structured comment not found on Epic');
-    return { codeReviewFound, severity };
+    return { codeReviewFound, codeReviewUnparseable: false, severity };
   }
-  if (severity.critical === null || severity.high === null) {
-    reasons.push('code-review severity bullets could not be parsed');
-    return { codeReviewFound, severity };
+  // "Present but unparseable" is a DISTINCT condition from "present and says
+  // no" (Story #4222). The canonical renderer
+  // (`review-providers/findings-renderer.js`) always emits all four severity
+  // bullets, so a body whose critical/high counts we cannot extract is a
+  // FORMAT MISS, not a disqualifying signal. Failing closed here — pushing a
+  // generic block reason — is indistinguishable, to the operator and to
+  // downstream telemetry (the mandrel-bench Autonomy dimension), from a real
+  // critical finding: it stalls an otherwise-clean unattended run for a
+  // non-reason.
+  //
+  // Chosen policy: FAIL OPEN on an unparseable code-review body. We surface
+  // the condition explicitly via the `codeReviewUnparseable` signal so
+  // telemetry can tell a parser miss from a true HITL hand-off, but we do NOT
+  // add a disqualifying `reasons[]` entry — the absence of a parseable
+  // critical/high count cannot, on its own, block a run whose other signals
+  // are clean. Genuine disqualifying review findings (critical > 0 /
+  // high > 0) still block below, because those require the counts to have
+  // parsed successfully.
+  const codeReviewUnparseable =
+    severity.critical === null || severity.high === null;
+  if (codeReviewUnparseable) {
+    return { codeReviewFound, codeReviewUnparseable, severity };
   }
   if (severity.critical > 0) {
     reasons.push(`code-review has ${severity.critical} 🔴 Critical Blocker(s)`);
@@ -241,7 +269,7 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
   if (severity.high > 0) {
     reasons.push(`code-review has ${severity.high} 🟠 High Risk finding(s)`);
   }
-  return { codeReviewFound, severity };
+  return { codeReviewFound, codeReviewUnparseable, severity };
 }
 
 function evaluateRetroSignals(retro, reasons) {
@@ -287,6 +315,7 @@ function evaluateRetroSignals(retro, reasons) {
  *     storyStatuses: string[],
  *     storyBlockers: number,
  *     severity: { critical: number|null, high: number|null, medium: number|null, suggestion: number|null },
+ *     codeReviewUnparseable: boolean,
  *     retroCompact: boolean,
  *     codeReviewFound: boolean,
  *     retroFound: boolean,
@@ -308,6 +337,7 @@ export function deriveAutoMergeVerdict({ state, codeReview, retro }) {
       storyStatuses: stateSig.storyStatuses,
       storyBlockers: stateSig.storyBlockers,
       severity: reviewSig.severity,
+      codeReviewUnparseable: reviewSig.codeReviewUnparseable,
       retroCompact: retroSig.retroCompact,
       codeReviewFound: reviewSig.codeReviewFound,
       retroFound: retroSig.retroFound,

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)) {