mandrel 1.72.0 → 1.74.0

package/.agents/scripts/lib/onboard/init-tail.js

@@ -62,23 +62,22 @@ function formatMissingList(missing) {
 }
 
 /** Prompt text shown only on a TTY when asking to scaffold. */
-const SCAFFOLD_PROMPT = '\nCreate placeholders? [Y/n]: ';
+const SCAFFOLD_PROMPT = '\nCreate placeholders? [y/N]: ';
 
 /**
  * Async y/N read from stdin via `node:readline` (mirrors the prompt mechanism
  * in `bootstrap.js`). Returns on Enter and never blocks waiting for EOF the way
  * `fs.readFileSync(0)` did — that EOF-blocking read hung `mandrel init` on an
- * interactive TTY. Yes is the default (`[Y/n]`): a bare Enter — or anything but
- * an explicit `n`/`no` — resolves to `true` (create the placeholders), since the
- * missing docs are known-needed and the stubs carry a `MANDREL:STUB` marker the
- * `/plan` preflight still flags until they are fleshed out. A read error
- * resolves to `false` so a genuine I/O failure never writes unattended. The
- * prompt text is written by the caller via `stdout`, so the question string
- * passed here is empty.
+ * interactive TTY. No is the default (`[y/N]`): only an explicit `y`/`yes`
+ * resolves to `true` (create the placeholders). A bare Enter or any other input
+ * declines, matching the same default-off policy as `--with-issue-forms`. A
+ * read error resolves to `false` so a genuine I/O failure never writes
+ * unattended. The prompt text is written by the caller via `stdout`, so the
+ * question string passed here is empty.
  *
  * `terminal: false` is **load-bearing**: with terminal mode on (the default
  * when stdout is a TTY) readline emits cursor-control escapes
- * (`\x1b[1G\x1b[0J`) that erase the `Create placeholders? [Y/n]:` prompt already
+ * (`\x1b[1G\x1b[0J`) that erase the `Create placeholders? [y/N]:` prompt already
  * written via the caller's `stdout`, leaving the operator staring at a blank,
  * dead-looking line. Disabling terminal mode preserves the pre-written prompt
  * and reads the line via the TTY's cooked-mode echo. `createInterface` is
@@ -97,7 +96,7 @@ export async function readConfirm({
   });
   try {
     const answer = (await rl.question('')).trim().toLowerCase();
-    return answer !== 'n' && answer !== 'no';
+    return answer === 'y' || answer === 'yes';
   } catch {
     return false;
   } finally {

package/.agents/scripts/lib/orchestration/column-sync.js

@@ -35,6 +35,7 @@
  */
 
 import { AGENT_LABELS } from '../label-constants.js';
+import { resolveProjectMeta } from './project-meta-resolver.js';
 
 export const LABEL_TO_COLUMN = Object.freeze({
   [AGENT_LABELS.REVIEW_SPEC]: 'Todo',
@@ -141,49 +142,29 @@ export class ColumnSync {
   async #loadMeta() {
     if (this._meta !== null) return this._meta || null;
     try {
-      let project;
-      if (this.projectOwner) {
-        // When the project is owned by a different account than the
-        // authenticated viewer, `viewer.projectV2` returns null. Use
-        // `user(login: $owner).projectV2` instead. (Story #3560)
-        const data = await this.provider.graphql(
-          `
-          query($owner: String!, $number: Int!) {
-            user(login: $owner) {
-              projectV2(number: $number) {
-                id
-                field(name: "Status") {
-                  ... on ProjectV2SingleSelectField {
-                    id
-                    options { id name }
-                  }
-                }
-              }
+      // Resolve the board by walking the owner-type ladder
+      // (organization → user → viewer) via the shared resolver so the
+      // org-owned path can't drift from `workflow-audit.js`. The Status
+      // single-select field is projected alongside the board id in one
+      // round-trip. (Story #4237; org-owner support extends the
+      // user/viewer ladder added in #3560.)
+      const project = await resolveProjectMeta({
+        provider: this.provider,
+        // Prefer the explicit `github.projectOwner`; fall back to the repo
+        // owner so an org-owned board still gets a login to scope
+        // `organization(login:)` / `user(login:)` by even when no separate
+        // projectOwner is configured. `viewer` is always the final rung.
+        owner: this.projectOwner ?? this.provider.owner ?? null,
+        projectNumber: this.projectNumber,
+        projectFields: `
+          id
+          field(name: "Status") {
+            ... on ProjectV2SingleSelectField {
+              id
+              options { id name }
             }
           }`,
-          { owner: this.projectOwner, number: this.projectNumber },
-        );
-        project = data?.user?.projectV2;
-      } else {
-        const data = await this.provider.graphql(
-          `
-          query($number: Int!) {
-            viewer {
-              projectV2(number: $number) {
-                id
-                field(name: "Status") {
-                  ... on ProjectV2SingleSelectField {
-                    id
-                    options { id name }
-                  }
-                }
-              }
-            }
-          }`,
-          { number: this.projectNumber },
-        );
-        project = data?.viewer?.projectV2;
-      }
+      });
       const field = project?.field;
       if (!project || !field) {
         this._meta = false;

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-discriminator.js

@@ -45,7 +45,7 @@
  * @property {string}  [reason]   Structured reason code when allowed=false.
  */
 
-import { AGENT_LABELS } from '../label-constants.js';
+import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
 
 /**
  * Execution-signal labels that block Close. Stored as a frozen Set for
@@ -245,6 +245,57 @@ export class LabelAllowListViolation extends Error {
   }
 }
 
+/**
+ * Error class thrown synchronously by `assertStoryTypeLabel` when a Story
+ * create operation carries no `type::story` label. Named distinctly from
+ * `LabelAllowListViolation` so callers can route it separately.
+ *
+ * The class carries structured metadata (`slug`, `title`) so the error
+ * message can name the offending Story clearly.
+ */
+export class MissingTypeLabelError extends Error {
+  /**
+   * @param {string} message
+   * @param {{slug?: string, title?: string}} [meta]
+   */
+  constructor(message, meta = {}) {
+    super(message);
+    this.name = 'MissingTypeLabelError';
+    if (meta.slug !== undefined) this.slug = meta.slug;
+    if (meta.title !== undefined) this.title = meta.title;
+  }
+}
+
+/**
+ * Diff-time assertion. Throws `MissingTypeLabelError` synchronously when a
+ * Story create operation is missing the mandatory `type::story` label.
+ *
+ * Symmetric with `assertNoAgentLabels`: both fire at diff time so the plan
+ * fails loudly before the apply pipeline touches GitHub.
+ *
+ * Only validates Story create ops — Epic creates carry a different mandatory
+ * label (`type::epic`) that the caller already hard-codes at issue-creation
+ * time; the assertion is not needed there.
+ *
+ * @param {{slug?: string, title?: string, entity?: string, labels?: string[]}} op
+ * @returns {void}
+ */
+export function assertStoryTypeLabel(op) {
+  if (!op || typeof op !== 'object') return;
+  if (op.entity !== 'story') return;
+  // A create op for a Story MUST carry type::story. An absent or empty labels
+  // array means the mandatory label is missing — fail loud so the operator
+  // sees a named Story rather than a silent unlabeled issue on GitHub.
+  if (!Array.isArray(op.labels) || !op.labels.includes(TYPE_LABELS.STORY)) {
+    throw new MissingTypeLabelError(
+      `create plan for story slug=${op.slug ?? '?'} ("${op.title ?? ''}") is ` +
+        `missing the mandatory "${TYPE_LABELS.STORY}" label. Add it to the ` +
+        `spec's labels array for this Story and re-run.`,
+      { slug: op.slug, title: op.title },
+    );
+  }
+}
+
 /**
  * Diff-time assertion. Throws `LabelAllowListViolation` synchronously
  * when an operation targets an `agent::*` label. The assertion is the
@@ -329,7 +380,10 @@ export function assertNoAgentLabels(op) {
  */
 export function assertPlanLabelAllowList(plan) {
   if (!plan || typeof plan !== 'object') return;
-  for (const op of plan.creates ?? []) assertNoAgentLabels(op);
+  for (const op of plan.creates ?? []) {
+    assertNoAgentLabels(op);
+    assertStoryTypeLabel(op);
+  }
   for (const op of plan.updates ?? []) assertNoAgentLabels(op);
   // closes/relinks do not carry label payloads — nothing to assert.
 }

package/.agents/scripts/lib/orchestration/project-meta-resolver.js

@@ -0,0 +1,129 @@
+/**
+ * project-meta-resolver — shared GitHub Projects v2 owner-resolution
+ * primitive (Story #4237).
+ *
+ * Background:
+ *   Both `ColumnSync._loadMeta` (`lib/orchestration/column-sync.js`) and
+ *   `resolveProjectIdByNumber` (`lib/bootstrap/workflow-audit.js`)
+ *   needed to turn a `(owner, projectNumber)` pair into a Projects v2
+ *   board node id. Each historically resolved only **user-owned** /
+ *   `viewer`-owned boards: `viewer.projectV2(number:)` first, then
+ *   `user(login:$owner).projectV2(number:)` (Story #3560). Neither had an
+ *   `organization(login:$owner)` branch, so for an **org-owned** board
+ *   every lookup failed with `NOT_FOUND` and the `agent::*` → board
+ *   Status mirror silently no-oped (reproduced on `Beestera/swarm-os`).
+ *
+ * Fix:
+ *   A single shared resolver that walks the owner-type ladder in order —
+ *   `organization(login:$owner)` → `user(login:$owner)` → `viewer` —
+ *   returning the first board it can resolve. Centralising the ladder in
+ *   one place means the org path can never again drift between the two
+ *   call sites.
+ *
+ * The resolver issues a sub-query for the project itself (`field(name:
+ * "Status") { … }` for the column-sync caller, or a bare `id` for the
+ * workflow-audit caller). Pass the desired projection in via
+ * `projectFields`; the resolver wraps it in the right owner scope and
+ * extracts the resolved `projectV2` node.
+ */
+
+/**
+ * The owner-resolution ladder, in priority order. Each entry names the
+ * GraphQL root field and whether it requires the `$owner` variable.
+ *
+ * `organization` and `user` are keyed by `login: $owner`; `viewer` is the
+ * authenticated identity and takes no owner argument. The viewer rung is
+ * the historical default and stays last so a configured owner is always
+ * preferred over the ambient identity.
+ */
+const OWNER_SCOPES = Object.freeze([
+  { root: 'organization', needsOwner: true },
+  { root: 'user', needsOwner: true },
+  { root: 'viewer', needsOwner: false },
+]);
+
+/**
+ * Build the GraphQL document for a single owner scope.
+ *
+ * @param {{ root: string, needsOwner: boolean }} scope
+ * @param {string} projectFields — the inner `projectV2(number: $number) { … }`
+ *   selection body (everything between the braces).
+ * @returns {string}
+ */
+function buildScopedQuery(scope, projectFields) {
+  if (scope.needsOwner) {
+    return `
+      query($owner: String!, $number: Int!) {
+        ${scope.root}(login: $owner) {
+          projectV2(number: $number) {
+            ${projectFields}
+          }
+        }
+      }`;
+  }
+  return `
+    query($number: Int!) {
+      ${scope.root} {
+        projectV2(number: $number) {
+          ${projectFields}
+        }
+      }
+    }`;
+}
+
+/**
+ * Resolve a Projects v2 board node by walking the owner-type ladder.
+ *
+ * Tries `organization(login:$owner)` → `user(login:$owner)` → `viewer` in
+ * order, returning the first non-null `projectV2` node. A scope that
+ * throws (e.g. GitHub returns `NOT_FOUND` for the wrong owner type) or
+ * resolves to `null` is treated as a miss and the ladder advances to the
+ * next rung. Returns `null` when every rung misses.
+ *
+ * When `owner` is falsy, only the `viewer` rung is attempted (there is no
+ * login to scope `organization`/`user` by) — this preserves the original
+ * viewer-only behaviour for callers that never configured a project owner.
+ *
+ * @param {{
+ *   provider: { graphql: Function },
+ *   owner?: string | null,
+ *   projectNumber: number,
+ *   projectFields: string,
+ * }} args
+ * @returns {Promise<object|null>} the resolved `projectV2` node, or null.
+ */
+export async function resolveProjectMeta(args) {
+  const { provider, owner, projectNumber, projectFields } = args ?? {};
+  if (!provider || typeof provider.graphql !== 'function') {
+    throw new TypeError('resolveProjectMeta requires a provider with graphql');
+  }
+  if (typeof projectFields !== 'string' || projectFields.length === 0) {
+    throw new TypeError(
+      'resolveProjectMeta requires a projectFields selection',
+    );
+  }
+
+  for (const scope of OWNER_SCOPES) {
+    // Skip the owner-scoped rungs when no owner login is available.
+    if (scope.needsOwner && !owner) continue;
+
+    const query = buildScopedQuery(scope, projectFields);
+    const vars = scope.needsOwner
+      ? { owner, number: projectNumber }
+      : { number: projectNumber };
+
+    let data;
+    try {
+      data = await provider.graphql(query, vars);
+    } catch {
+      // Wrong owner type (NOT_FOUND), missing scope, etc. — advance the
+      // ladder rather than aborting the whole resolution.
+      continue;
+    }
+
+    const node = data?.[scope.root]?.projectV2;
+    if (node) return node;
+  }
+
+  return null;
+}

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' });