triad-plus 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.7.0 — 2026-09-10
+
+- Add an optional deterministic importer for one BMAD `ready-for-dev` Story at
+  a time, preserving the normal Triad Card contract and source provenance.
+
+## 1.6.0 — 2026-09-05
+
+- Add card-declared repository `required_gates` with additive per-card gate
+  selection; globally required gates are always preserved.
+- Promote selected optional repository gates to mandatory for the card, with
+  trusted assignment binding, fail-closed unavailable-gate handling, and
+  generic gate-selection evidence.
+- Preserve the existing legacy behavior when a card has no selected gates.
+
 ## 1.5.0 — 2026-09-05
 
 - Add cause-coded retry/recovery accounting with independent finite runtime and

package/README.md

@@ -107,6 +107,23 @@ The Orchestrator first shows the feature cards, then delegates the bounded work.
 If a tutorial step is unclear, see the [OpenCode guide](docs/runtimes.md#opencode)
 and [troubleshooting](docs/troubleshooting.md).
 
+## Optional BMAD Story import
+
+When BMAD planning has already produced a Story with `status: ready-for-dev`,
+you can convert one Story at a time into the normal Triad Card contract:
+
+```bash
+npx triad-plus import-bmad-story \
+  --source /absolute/path/to/story.md \
+  --output /absolute/path/to/control/features/STORY-001.md
+```
+
+The importer is read-only and fail-closed. It preserves the Story's executable
+intent, acceptance criteria, technical context, and references, while any
+required gates or dependencies remain explicit caller options. It does not run
+BMAD workflows or add BMAD semantics to the Core. See the [BMAD integration
+guide](docs/bmad-integration.md).
+
 ## Quick start for every runtime
 
 Requirements: Node.js 20+ and one supported coding-agent host.

package/bin/triad-plus.js

@@ -8,6 +8,7 @@ import { dirname, join, resolve } from 'node:path';
 import process from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { getAdapter, listAdapters, roleDefinitions, sharedSkillNames } from '../adapters/registry.mjs';
+import { writeImportedCard } from '../integrations/bmad/story-importer.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -20,6 +21,7 @@ Usage:
   npx triad-plus init --host <adapter-id> --control <path> [--global] [--team-config <path>] [--allow-product-repo]
   npx triad-plus doctor --host <adapter-id> --control <path> [--hook-config <path>]
   npx triad-plus upgrade --host <adapter-id> --control <path> [--global] [--apply]
+  npx triad-plus import-bmad-story --source <story.md> --output <card.md> [--target-repository <id>] [--provenance <record.json>] [--required-gate <id>] [--depends-on <card-id>]
 
 Adapters: ${listAdapters().map((adapter) => adapter.id).join(', ')}
 
@@ -31,13 +33,20 @@ Installation refuses every asset overwrite. Upgrade is a dry run unless --apply
 
 function parseArgs(args) {
   const [command, ...rest] = args;
-  const options = { command, global: false, allowProductRepo: false, apply: false };
+  const options = { command, global: false, allowProductRepo: false, apply: false, requiredGates: [], dependsOn: [] };
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
     if (argument === '--global') options.global = true;
     else if (argument === '--allow-product-repo') options.allowProductRepo = true;
     else if (argument === '--apply') options.apply = true;
-    else if (['--host', '--control', '--team-config', '--hook-config'].includes(argument)) {
+    else if (argument === '--required-gate' || argument === '--depends-on') {
+      const value = rest[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value.`);
+      const target = argument === '--required-gate' ? options.requiredGates : options.dependsOn;
+      target.push(value);
+      index += 1;
+    }
+    else if (['--host', '--control', '--team-config', '--hook-config', '--source', '--output', '--target-repository', '--provenance'].includes(argument)) {
       const value = rest[index + 1];
       if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value.`);
       options[argument.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())] = value;
@@ -395,6 +404,21 @@ async function upgrade(options) {
   if (!options.apply) process.stdout.write('Dry run only. Re-run with --apply to update managed assets.\n');
 }
 
+async function importBmadStory(options) {
+  if (!options.source) throw new Error('Provide --source <bmad-story.md>.');
+  if (!options.output) throw new Error('Provide --output <triad-card.md>.');
+  const result = await writeImportedCard({
+    sourcePath: options.source,
+    outputPath: options.output,
+    targetRepository: options.targetRepository,
+    provenancePath: options.provenance,
+    requiredGates: options.requiredGates,
+    dependsOn: options.dependsOn
+  });
+  process.stdout.write(`Imported BMAD Story ${result.story.id} as Triad Card ${result.outputPath}\n`);
+  process.stdout.write(`Provenance ${result.provenancePath}\n`);
+}
+
 async function doctor(options) {
   if (!options.control) throw new Error('Provide --control <project-control-path>.');
   const controlRoot = resolve(options.control);
@@ -468,10 +492,11 @@ try {
   if (options.command === 'init') await init(options);
   else if (options.command === 'doctor') await doctor(options);
   else if (options.command === 'upgrade') await upgrade(options);
+  else if (options.command === 'import-bmad-story') await importBmadStory(options);
   else if (!options.command) await interactiveInit();
   else if (options.command === '--help' || options.command === '-h') usage(0);
   else throw new Error(`Unknown command: ${options.command}`);
 } catch (error) {
-  process.stderr.write(`${error.message}\n`);
+  process.stderr.write(`${error.code ? `${error.code}: ` : ''}${error.message}\n`);
   usage(2);
 }

package/docs/bmad-integration.md

@@ -0,0 +1,110 @@
+# Optional BMAD Story integration
+
+Triad+ can consume one already-produced BMAD Story and turn it into a normal
+Triad feature Card. This is an integration boundary, not a BMAD execution
+adapter: BMAD remains the planning authority and Triad remains responsible for
+implementation, verification, review, and delivery.
+
+## Contract
+
+The source is a read-only Markdown Story. It must contain:
+
+- a unique Story `id` and `title` (frontmatter, metadata labels, or a Story
+  heading);
+- `status: ready-for-dev` (frontmatter or a `Status` field);
+- a target repository (or an explicit `--target-repository` importer option);
+- an intent/outcome; and
+- acceptance criteria.
+
+The importer also carries through the Story's `Tasks & Acceptance`, Code Map,
+Design Notes/constraints, verification expectations, and source references
+when they are present. It does not interpret prose with an LLM, re-decompose a
+Story, or invoke BMAD Build, Build Auto, or `bmad-loop`.
+
+## CLI
+
+```bash
+npx triad-plus import-bmad-story \
+  --source /absolute/path/to/story.md \
+  --output /absolute/path/to/control/features/JFR-001.md \
+  --target-repository webup \
+  --required-gate cypress-jfr \
+  --depends-on JFR-000
+```
+
+`--required-gate` and `--depends-on` may be repeated. They are explicit caller
+options: gate IDs are additive to the repository's globally required gates,
+and dependencies are never inferred from `stories.yaml` order. Omit both when
+the Card should use the repository's normal/baseline behavior.
+
+The command writes the Card and a sidecar provenance record (by default
+`<card>.bmad-provenance.json`). The provenance records `source_kind:
+bmad-story`, the resolved source path, source SHA-256, BMAD Story ID, target
+repository, Card SHA-256, and the explicit options used for the import.
+
+The same operation is available to Node consumers:
+
+```js
+import { importBmadStory, writeImportedCard } from
+  'triad-plus/integrations/bmad/story-importer.mjs';
+
+const result = await importBmadStory({
+  sourcePath: '/absolute/path/to/story.md',
+  targetRepository: 'webup',
+  requiredGates: ['cypress-jfr']
+});
+
+await writeImportedCard({
+  sourcePath: '/absolute/path/to/story.md',
+  outputPath: '/absolute/path/to/control/features/JFR-001.md',
+  targetRepository: 'webup',
+  requiredGates: ['cypress-jfr']
+});
+```
+
+## Example mapping
+
+Input (abridged):
+
+```md
+---
+id: JFR-001
+title: Route the provider document
+status: ready-for-dev
+target_repository: webup
+---
+
+# Story JFR-001: Route the provider document
+
+## Intent
+
+Webup renders the provider-owned document at the existing boundary.
+
+## Acceptance Criteria
+
+- Given a valid document, when the route is requested, then it renders.
+
+## Code Map
+
+- `src/components/jfr/`
+```
+
+The generated Card keeps that intent, acceptance criterion, Code Map, and the
+target repository, then adds the normal Triad sections and the integration
+boundary note. The caller-supplied `cypress-jfr` (if any) is recorded as an
+additive required gate; it is not inferred from the word "render" or from a
+file extension.
+
+## Fail-closed behavior
+
+No executable Card is produced for a missing source, missing/non-`ready-for-dev`
+status, malformed or ambiguous ID/title, missing indispensable Card fields,
+conflicting target repository, invalid caller options, or a source that changes
+while it is being read. The API exposes integration-level error codes such as
+`bmad_story_not_ready`, `bmad_story_ambiguous`, `bmad_story_unmappable`, and
+`bmad_story_source_mutated` so a planning gap can return upstream rather than
+become a Developer decision.
+
+After import, the generated Card goes through the existing assignment and
+`triad-verify` path. No Core schema, lifecycle, Reviewer, retry, or gate
+execution semantics are changed by this integration.

package/docs/configuration.md

@@ -40,3 +40,10 @@ bind a versioned JSON scope contract at its first assignment; without one, the
 deterministic scope preflight is not configured and independent review remains
 the semantic scope check. See [verification.md](verification.md) for the
 contract and matching rules.
+
+Cards may also declare `required_gates` as an additive list of trusted
+repository gate IDs. Globally required gates are never suppressed; a selected
+optional gate becomes required for that card, and an absent or empty list keeps
+the legacy gate behavior. Selected IDs are validated before Developer dispatch
+and are bound to the assignment; Triad does not attach visual or other
+domain-specific meaning to a gate ID.

package/docs/operating-guide.it.md

@@ -44,6 +44,13 @@ registra push finale, eventuale valutazione, handoff, stato finale della run e
 prova pratica prima di dichiarare il progetto consegnato. Avvio e stop della demo
 restano del proprietario.
 
+Una card può aggiungere una lista `required_gates` di gate ID del repository.
+La lista è additiva: i gate globalmente obbligatori continuano a essere eseguiti,
+quelli opzionali selezionati diventano obbligatori per la card e gli opzionali non
+selezionati possono essere saltati. Lista assente o vuota mantiene il
+comportamento legacy. Triad collega e registra gli ID senza attribuire loro un
+significato visuale o di altro dominio.
+
 ## Retry e scope del candidato
 
 Gli attempt sono record storici di esecuzione. I nuovi workspace separano e

package/docs/operating-guide.md

@@ -45,6 +45,12 @@ closure gate: it records the final push, optional evaluation, handoff, final run
 record, and practical test before the project is called delivered. Demo start and
 stop remain owner-controlled.
 
+Cards may add a `required_gates` list containing trusted repository gate IDs.
+The list is additive: globally required gates still run, selected optional gates
+become required for that card, and unselected optional gates may be skipped. An
+absent or empty list preserves the legacy behavior. Triad binds and records the
+IDs but does not attach visual or other domain-specific meaning to them.
+
 ## Retry accounting and candidate scope
 
 Attempts are historical execution records. New workspaces separately bound

package/docs/verification.md

@@ -29,6 +29,30 @@ it does not itself approve, rework, or transition a run.
 Evidence files and logs are diagnostics. Users normally need only the
 Orchestrator's summary and the Reviewer verdict.
 
+## Card-declared required gates
+
+The work queue may carry a machine-readable `required_gates` list for an
+individual card. The values are repository-owned gate IDs; Triad does not infer
+their purpose or know whether a gate checks UI, an API, a migration, or another
+concern.
+
+An absent or empty list preserves the v1.5 legacy execution behavior. When the
+list is non-empty, the Orchestrator resolves one effective set by taking the
+union of every trusted repository gate whose definition has `required: true`
+and the card-selected IDs. The set is deduplicated. A selected optional gate is
+promoted to required for that card, while unselected optional gates may be
+skipped. The trusted catalog remains authoritative for command, timeout, and
+executor details.
+
+Every selected ID is validated before Developer dispatch. A missing ID,
+placeholder command, or unsupported executor is an
+`unavailable_required_gate` capability gap: the Developer is not dispatched and
+no retry budget is consumed. The verifier repeats the binding check so a stale
+assignment fails closed. Verification evidence records the mode, card-selected
+IDs, baseline required IDs, effective IDs, and effective required IDs. A verifier
+pass still always leads to an independent Reviewer; gate pass is not semantic
+approval.
+
 ## Optional deterministic candidate scope
 
 Cards may add a versioned JSON scope contract, bound by path and SHA-256 in the

package/integrations/bmad/README.md

@@ -0,0 +1,12 @@
+# BMAD Story importer
+
+This optional integration converts one BMAD Markdown Story with
+`status: ready-for-dev` into a normal Triad feature Card. It is intentionally
+small and deterministic: the source is read-only, caller options are explicit,
+and BMAD workflows are never invoked.
+
+See [the public BMAD integration guide](../../docs/bmad-integration.md) for the
+mapping contract, CLI/API examples, provenance sidecar, and fail-closed rules.
+
+The implementation is in `story-importer.mjs`. It does not add BMAD-specific
+branches to the Triad Core or infer gates/dependencies from planning order.

package/integrations/bmad/story-importer.mjs

@@ -0,0 +1,475 @@
+import { createHash } from 'node:crypto';
+import { access, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+const READY_STATUS = 'ready-for-dev';
+const SOURCE_KIND = 'bmad-story';
+
+export class BmadStoryImportError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'BmadStoryImportError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function clean(value) {
+  return String(value ?? '').trim();
+}
+
+function unquote(value) {
+  const text = clean(value);
+  if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
+    return text.slice(1, -1).replaceAll('\\"', '"').replaceAll("\\'", "'");
+  }
+  return text;
+}
+
+function scalar(value) {
+  const text = unquote(value);
+  if (text === 'null' || text === '~') return null;
+  if (text === 'true') return true;
+  if (text === 'false') return false;
+  if (text.startsWith('[') && text.endsWith(']')) {
+    try {
+      const parsed = JSON.parse(text);
+      return parsed;
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+function parseFrontmatter(source) {
+  if (!source.startsWith('---\n') && !source.startsWith('---\r\n')) return { metadata: {}, body: source };
+  const openingEnd = source.indexOf('\n');
+  const closing = source.indexOf('\n---', openingEnd + 1);
+  if (closing < 0) throw new BmadStoryImportError('bmad_story_invalid', 'BMAD Story frontmatter is not closed.');
+  const closingEnd = source.indexOf('\n', closing + 1);
+  const frontmatter = source.slice(openingEnd + 1, closing);
+  const metadata = {};
+  const duplicateKeys = [];
+  for (const line of frontmatter.split(/\r?\n/)) {
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const match = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!match) {
+      // BMAD frontmatter may contain nested lists/maps. They are not part of
+      // this importer contract, but are preserved in the source and ignored.
+      if (/^\s+/.test(line) || /^\s*-\s+/.test(line)) continue;
+      throw new BmadStoryImportError('bmad_story_invalid', `Malformed BMAD Story frontmatter line: ${line}`);
+    }
+    const [, key, rawValue] = match;
+    if (Object.hasOwn(metadata, key)) duplicateKeys.push(key);
+    metadata[key] = scalar(rawValue);
+  }
+  if (duplicateKeys.length) {
+    throw new BmadStoryImportError('bmad_story_ambiguous', `BMAD Story frontmatter repeats: ${duplicateKeys.join(', ')}`);
+  }
+  return { metadata, body: closingEnd < 0 ? '' : source.slice(closingEnd + 1) };
+}
+
+function normalizeHeading(value) {
+  return clean(value)
+    .replaceAll('`', '')
+    .replace(/^\*+|\*+$/g, '')
+    .replace(/[：:]+$/g, '')
+    .toLowerCase()
+    .replace(/&/g, 'and')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+function parseSections(body) {
+  const sections = [];
+  let current = null;
+  const flush = () => {
+    if (!current) return;
+    const content = current.lines.join('\n').trim();
+    sections.push({ heading: current.heading, level: current.level, content });
+  };
+  for (const line of body.split(/\r?\n/)) {
+    const heading = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (heading) {
+      flush();
+      current = { heading: heading[2], level: heading[1].length, lines: [] };
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+function parseLabelBlocks(body) {
+  const blocks = [];
+  let current = null;
+  const flush = () => {
+    if (!current) return;
+    const content = current.lines.join('\n').trim();
+    if (content) blocks.push({ heading: current.heading, content });
+  };
+  for (const line of body.split(/\r?\n/)) {
+    const label = line.match(/^\s*(?:[-*]\s*)?\*\*([^*]+)\*\*\s*:?\s*$/);
+    if (label) {
+      flush();
+      current = { heading: label[1], lines: [] };
+    } else if (/^#{1,6}\s+/.test(line)) {
+      flush();
+      current = null;
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  flush();
+  return blocks;
+}
+
+function valuesForMetadata(metadata, names) {
+  const values = [];
+  for (const name of names) if (metadata[name] !== undefined && metadata[name] !== null) values.push(metadata[name]);
+  return values;
+}
+
+function metadataLines(body, names) {
+  const wanted = new Set(names.map((name) => normalizeHeading(name)));
+  const values = [];
+  for (const line of body.split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:[-*]\s*)?(?:\*\*)?([^:*]+?)(?:\*\*)?\s*:\s*(.+?)\s*$/);
+    if (match && wanted.has(normalizeHeading(match[1]))) values.push(unquote(match[2]));
+  }
+  return values;
+}
+
+function contentsFor(sections, labels, labelBlocks = []) {
+  const wanted = new Set(labels.map((label) => normalizeHeading(label)));
+  const values = [
+    ...sections.filter((section) => wanted.has(normalizeHeading(section.heading))).map((section) => section.content),
+    ...labelBlocks.filter((block) => wanted.has(normalizeHeading(block.heading))).map((block) => block.content)
+  ];
+  return [...new Set(values.map(clean).filter(Boolean))];
+}
+
+function firstContent(sections, labelBlocks, labels) {
+  const values = contentsFor(sections, labels, labelBlocks);
+  return values[0] ?? '';
+}
+
+function firstLabelOrSectionContent(sections, labelBlocks, labels) {
+  const labeled = contentsFor([], labels, labelBlocks);
+  return labeled[0] ?? firstContent(sections, labelBlocks, labels);
+}
+
+function distinctStrings(values, field) {
+  const normalized = values.map((value) => clean(value)).filter(Boolean);
+  const distinct = [...new Set(normalized)];
+  if (distinct.length > 1) {
+    throw new BmadStoryImportError('bmad_story_ambiguous', `BMAD Story has conflicting ${field} values.`, { field, values: distinct });
+  }
+  return distinct[0] ?? '';
+}
+
+function parseStoryHeading(sections) {
+  const headings = sections
+    .filter((section) => section.level === 1)
+    .map((section) => section.heading)
+    .map((heading) => {
+      const match = clean(heading).match(/^Story\s+([A-Za-z0-9][A-Za-z0-9._-]*)(?:\s*[:—-]\s*(.+))?$/i);
+      if (match) return { id: match[1], title: clean(match[2]) };
+      const plain = clean(heading).match(/^([A-Za-z0-9][A-Za-z0-9._-]*)\s*[:—-]\s*(.+)$/);
+      return plain ? { id: plain[1], title: clean(plain[2]) } : null;
+    })
+    .filter(Boolean);
+  if (headings.length > 1) {
+    throw new BmadStoryImportError('bmad_story_ambiguous', 'BMAD Story source contains multiple story headings.', { headings });
+  }
+  return headings[0] ?? { id: '', title: '' };
+}
+
+function normalizeList(value, field) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new BmadStoryImportError('bmad_story_unmappable', `${field} must be an array when supplied.`);
+  const result = [];
+  for (const item of value) {
+    if (typeof item !== 'string' || !item.trim()) throw new BmadStoryImportError('bmad_story_unmappable', `${field} must contain non-empty strings.`);
+    const normalized = item.trim();
+    if (!result.includes(normalized)) result.push(normalized);
+  }
+  return result;
+}
+
+function sourcePathLabel(sourcePath) {
+  return sourcePath ? resolve(sourcePath) : '<BMAD Story source>';
+}
+
+export function parseBmadStory(source, { sourcePath = null, targetRepository = null } = {}) {
+  if (typeof source !== 'string' || !source.trim()) {
+    throw new BmadStoryImportError('bmad_story_invalid', 'BMAD Story source is empty.');
+  }
+  const { metadata, body } = parseFrontmatter(source);
+  const sections = parseSections(body);
+  const labelBlocks = parseLabelBlocks(body);
+  const heading = parseStoryHeading(sections);
+
+  const id = distinctStrings([
+    ...valuesForMetadata(metadata, ['id', 'story_id', 'storyId']),
+    ...metadataLines(body, ['Story ID', 'ID']),
+    heading.id
+  ], 'story id');
+  if (!id) throw new BmadStoryImportError('bmad_story_not_found', `No BMAD Story id found in ${sourcePathLabel(sourcePath)}.`);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+    throw new BmadStoryImportError('bmad_story_invalid', `BMAD Story id is not filename-safe: ${id}`);
+  }
+
+  const title = distinctStrings([
+    ...valuesForMetadata(metadata, ['title']),
+    ...metadataLines(body, ['Title']),
+    heading.title
+  ], 'title');
+  if (!title) throw new BmadStoryImportError('bmad_story_unmappable', 'BMAD Story title is required.');
+
+  const status = distinctStrings([
+    ...valuesForMetadata(metadata, ['status']),
+    ...metadataLines(body, ['Status']),
+    firstContent(sections, labelBlocks, ['Status'])
+  ], 'status').toLowerCase();
+  if (!status) throw new BmadStoryImportError('bmad_story_not_ready', 'BMAD Story status is required and must be ready-for-dev.');
+  if (status !== READY_STATUS) {
+    throw new BmadStoryImportError('bmad_story_not_ready', `BMAD Story ${id} has status ${status}; only ready-for-dev can be imported.`, { status });
+  }
+
+  const declaredTargetRepository = distinctStrings([
+    ...valuesForMetadata(metadata, ['target_repository', 'targetRepository', 'repository', 'repo']),
+    ...metadataLines(body, ['Target repository', 'Target repo', 'Repository'])
+  ], 'target repository');
+  const explicitTargetRepository = targetRepository === undefined || targetRepository === null ? '' : clean(targetRepository);
+  if (targetRepository !== undefined && targetRepository !== null && !explicitTargetRepository) {
+    throw new BmadStoryImportError('bmad_story_unmappable', 'targetRepository must be a non-empty string when supplied.');
+  }
+  if (declaredTargetRepository && explicitTargetRepository && declaredTargetRepository !== explicitTargetRepository) {
+    throw new BmadStoryImportError('bmad_story_ambiguous', 'BMAD Story target repository conflicts with the explicit importer option.', {
+      declared: declaredTargetRepository,
+      explicit: explicitTargetRepository
+    });
+  }
+  const resolvedTargetRepository = declaredTargetRepository || explicitTargetRepository;
+  if (!resolvedTargetRepository) throw new BmadStoryImportError('bmad_story_unmappable', 'BMAD Story target repository is required.');
+
+  const outcome = firstContent(sections, labelBlocks, ['Intent', 'Outcome', 'User outcome', 'Objective', 'Story', 'Description']) || distinctStrings([
+    ...valuesForMetadata(metadata, ['intent', 'outcome', 'objective', 'description']),
+    ...metadataLines(body, ['Intent', 'Outcome', 'Objective', 'Description'])
+  ], 'intent/outcome');
+  if (!outcome) throw new BmadStoryImportError('bmad_story_unmappable', 'BMAD Story intent/outcome is required.');
+
+  const acceptanceCriteria = firstContent(sections, labelBlocks, ['Acceptance Criteria', 'Acceptance']) || '';
+  if (!acceptanceCriteria) throw new BmadStoryImportError('bmad_story_unmappable', 'BMAD Story acceptance criteria are required.');
+
+  return {
+    id,
+    title,
+    status,
+    targetRepository: resolvedTargetRepository,
+    branchWorktree: distinctStrings([
+      ...valuesForMetadata(metadata, ['branch', 'worktree', 'branch_worktree', 'branchWorktree']),
+      ...metadataLines(body, ['Branch', 'Worktree', 'Branch/worktree'])
+    ], 'branch/worktree'),
+    outcome,
+    acceptanceCriteria,
+    tasksAcceptance: firstLabelOrSectionContent(sections, labelBlocks, ['Execution', 'Tasks / Subtasks', 'Tasks', 'Tasks & Acceptance']),
+    codeMap: firstContent(sections, labelBlocks, ['Code Map', 'Technical Context', 'Technical context / code map', 'Implementation Context']),
+    designNotes: firstContent(sections, labelBlocks, ['Design Notes', 'Boundaries & Constraints', 'Constraints', 'Technical Constraints']),
+    verification: firstContent(sections, labelBlocks, ['Verification', 'Verification Expectations', 'Metrics and Gates', 'Verification expectations']),
+    references: firstContent(sections, labelBlocks, ['Source References', 'References', 'References / Provenance']),
+    inScope: firstContent(sections, labelBlocks, ['In Scope', 'Scope']),
+    outOfScope: firstContent(sections, labelBlocks, ['Out of Scope', 'Non-goals', 'Non Goals']),
+    sourcePath: sourcePath ? resolve(sourcePath) : null
+  };
+}
+
+function listText(values) {
+  return values.length ? values.map((value) => `\`${value}\``).join(', ') : 'none';
+}
+
+function sectionOrFallback(value, fallback) {
+  return value?.trim() || fallback;
+}
+
+export function buildTriadCard(story, { requiredGates = [], dependsOn = [] } = {}) {
+  if (!story || typeof story !== 'object') {
+    throw new BmadStoryImportError('bmad_story_unmappable', 'A parsed BMAD Story object is required.');
+  }
+  for (const field of ['id', 'title', 'targetRepository', 'outcome', 'acceptanceCriteria']) {
+    if (typeof story[field] !== 'string' || !story[field].trim()) {
+      throw new BmadStoryImportError('bmad_story_unmappable', `BMAD Story ${field} is required before Card generation.`);
+    }
+  }
+  if (story.status !== READY_STATUS) {
+    throw new BmadStoryImportError('bmad_story_not_ready', 'Only a ready-for-dev BMAD Story can become an executable Triad Card.', { status: story.status ?? null });
+  }
+  const gates = normalizeList(requiredGates, 'requiredGates');
+  const dependencies = normalizeList(dependsOn, 'dependsOn');
+  const branch = story.branchWorktree || 'not declared by BMAD Story';
+  const inScope = sectionOrFallback(story.inScope, 'Acceptance criteria, tasks, and technical context below define the bounded implementation; no additional scope is inferred.');
+  const outOfScope = sectionOrFallback(story.outOfScope, 'No additional out-of-scope constraints were declared by the BMAD Story.');
+  const tasks = sectionOrFallback(story.tasksAcceptance, 'No Tasks & Acceptance section was supplied by the BMAD Story.');
+  const codeMap = sectionOrFallback(story.codeMap, 'No Code Map or technical context section was supplied by the BMAD Story.');
+  const designNotes = sectionOrFallback(story.designNotes, 'No Design Notes or additional constraints were supplied by the BMAD Story.');
+  const verification = sectionOrFallback(story.verification, 'Use the repository-owned deterministic gates declared by the caller and the normal Triad verifier.');
+  const references = sectionOrFallback(story.references, 'No source references were declared by the BMAD Story.');
+
+  return [
+    `# ${story.id} — ${story.title}`,
+    '',
+    '## Outcome and scope',
+    '',
+    `- Target repository: \`${story.targetRepository}\``,
+    `- Branch/worktree: \`${branch}\``,
+    `- Outcome: ${story.outcome}`,
+    `- In scope: ${inScope}`,
+    `- Out of scope: ${outOfScope}`,
+    `- Dependencies: ${listText(dependencies)}`,
+    '',
+    '## Acceptance criteria',
+    '',
+    story.acceptanceCriteria,
+    '',
+    '## Tasks & Acceptance',
+    '',
+    tasks,
+    '',
+    '## Technical context / Code Map',
+    '',
+    codeMap,
+    '',
+    '## Design Notes / Constraints',
+    '',
+    designNotes,
+    '',
+    '## Verification expectations',
+    '',
+    verification,
+    '',
+    '## Source references',
+    '',
+    references,
+    '',
+    '## Metrics and gates',
+    '',
+    '| ID | Target | Evidence command or observation |',
+    '| --- | --- | --- |',
+    '| bmad-story-status | ready-for-dev source imported | source status and hash recorded in integration provenance |',
+    `- Required gates (\`required_gates\`): [${gates.join(', ')}]`,
+    '- Allowed dependencies: repository-owned dependencies only; no dependency was inferred from BMAD ordering.',
+    '',
+    '## Integration boundary',
+    '',
+    '- This card was generated from one BMAD Story; BMAD remains planning authority and Triad remains execution authority.',
+    '- The BMAD source is read-only. Provenance is recorded in the integration-side companion record.',
+    ''
+  ].join('\n');
+}
+
+export function validateTriadCard(card) {
+  const required = [
+    /^#\s+[^\n]+/m,
+    /^## Outcome and scope$/m,
+    /^## Acceptance criteria$/m,
+    /^## Metrics and gates$/m,
+    /Required gates \(`required_gates`\):/,
+    /^## Integration boundary$/m
+  ];
+  const missing = required.filter((pattern) => !pattern.test(card)).map((pattern) => pattern.toString());
+  return { valid: missing.length === 0, missing };
+}
+
+async function readStableSource(sourcePath) {
+  const resolved = resolve(sourcePath);
+  let first;
+  try {
+    const sourceStat = await stat(resolved);
+    if (!sourceStat.isFile()) throw new Error('not a file');
+    first = await readFile(resolved);
+  } catch (error) {
+    throw new BmadStoryImportError('bmad_story_not_found', `Cannot read BMAD Story source: ${resolved}`, { cause: error.code ?? 'not_a_file' });
+  }
+  const sourceText = first.toString('utf8');
+  let second;
+  try { second = await readFile(resolved); }
+  catch (error) { throw new BmadStoryImportError('bmad_story_source_mutated', `BMAD Story source changed during import: ${resolved}`, { cause: error.code ?? 'read_failed' }); }
+  if (!first.equals(second)) {
+    throw new BmadStoryImportError('bmad_story_source_mutated', `BMAD Story source changed during import: ${resolved}`);
+  }
+  return { resolved, source: sourceText, sourceSha256: sha256(first) };
+}
+
+export async function importBmadStory({ sourcePath, targetRepository = null, requiredGates = [], dependsOn = [], capturedAt = null } = {}) {
+  if (!sourcePath || typeof sourcePath !== 'string') throw new BmadStoryImportError('bmad_story_not_found', 'Provide a BMAD Story source path.');
+  const loaded = await readStableSource(sourcePath);
+  const story = parseBmadStory(loaded.source, { sourcePath: loaded.resolved, targetRepository });
+  const card = buildTriadCard(story, { requiredGates, dependsOn });
+  const cardValidation = validateTriadCard(card);
+  if (!cardValidation.valid) throw new BmadStoryImportError('bmad_story_unmappable', 'Generated Triad Card failed integration validation.', { missing: cardValidation.missing });
+  const provenance = {
+    schema_version: 1,
+    source_kind: SOURCE_KIND,
+    source_path: loaded.resolved,
+    source_sha256: loaded.sourceSha256,
+    bmad_story_id: story.id,
+    target_repository: story.targetRepository,
+    card_sha256: sha256(card),
+    required_gate_ids: normalizeList(requiredGates, 'requiredGates'),
+    depends_on: normalizeList(dependsOn, 'dependsOn'),
+    imported_at: capturedAt ?? new Date().toISOString()
+  };
+  return { story, card, provenance };
+}
+
+async function pathExists(target) {
+  try { await access(target); return true; } catch { return false; }
+}
+
+export async function writeImportedCard({ sourcePath, outputPath, provenancePath = null, targetRepository = null, requiredGates = [], dependsOn = [], capturedAt = null } = {}) {
+  if (!outputPath || typeof outputPath !== 'string') throw new BmadStoryImportError('bmad_story_unmappable', 'Provide an output path for the generated Triad Card.');
+  const output = resolve(outputPath);
+  const provenance = resolve(provenancePath || `${output}.bmad-provenance.json`);
+  if (output === provenance) throw new BmadStoryImportError('bmad_story_unmappable', 'Card output and provenance output must be different paths.');
+  if (await pathExists(output) || await pathExists(provenance)) {
+    throw new BmadStoryImportError('bmad_story_unmappable', 'Refusing to overwrite an existing Card or provenance record.', { output, provenance });
+  }
+  const result = await importBmadStory({ sourcePath, targetRepository, requiredGates, dependsOn, capturedAt });
+  await mkdir(dirname(output), { recursive: true });
+  await mkdir(dirname(provenance), { recursive: true });
+  const outputTemp = `${output}.tmp-${process.pid}`;
+  const provenanceTemp = `${provenance}.tmp-${process.pid}`;
+  let outputWritten = false;
+  let provenanceWritten = false;
+  try {
+    await writeFile(outputTemp, result.card, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(provenanceTemp, `${JSON.stringify({ ...result.provenance, card_path: output }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    await rename(outputTemp, output);
+    outputWritten = true;
+    await rename(provenanceTemp, provenance);
+    provenanceWritten = true;
+  } catch (error) {
+    await rm(outputTemp, { force: true });
+    await rm(provenanceTemp, { force: true });
+    if (outputWritten) await rm(output, { force: true });
+    if (provenanceWritten) await rm(provenance, { force: true });
+    throw new BmadStoryImportError('bmad_story_unmappable', `Could not write imported Card: ${error.message}`, { cause: error.code ?? 'write_failed' });
+  }
+  return { ...result, outputPath: output, provenancePath: provenance };
+}
+
+export const bmadStoryImporter = {
+  sourceKind: SOURCE_KIND,
+  readyStatus: READY_STATUS,
+  parse: parseBmadStory,
+  buildCard: buildTriadCard,
+  import: importBmadStory,
+  write: writeImportedCard
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triad-plus",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "A lightweight, evidence-backed engineering loop for coding agents.",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,7 +28,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node tests/runtime-forward-test.mjs && node tests/retry-scope-contracts-test.mjs && node tests/cli-install-test.mjs && node tests/codex-liveness-test.mjs",
+    "test": "node tests/runtime-forward-test.mjs && node tests/retry-scope-contracts-test.mjs && node tests/cli-install-test.mjs && node tests/codex-liveness-test.mjs && node tests/bmad-story-importer-test.mjs",
     "pack:check": "npm pack --dry-run"
   },
   "repository": {

package/runtime/lib/gates.mjs

@@ -54,6 +54,120 @@ export async function loadTrustedGates(gatesPath, expectedHash) {
   return { valid: true, actualHash, gates: parseQualityGates(source) };
 }
 
+function normalizeRequiredGateIds(requiredGateIds) {
+  if (requiredGateIds === undefined) return [];
+  if (!Array.isArray(requiredGateIds)) throw new Error("required_gate_ids must be an array");
+  const seen = new Set();
+  const normalized = [];
+  for (const value of requiredGateIds) {
+    if (typeof value !== "string" || !value.trim()) throw new Error("required_gate_ids must contain non-empty strings");
+    const id = value.trim();
+    if (!seen.has(id)) {
+      seen.add(id);
+      normalized.push(id);
+    }
+  }
+  return normalized;
+}
+
+function selectedGateIssues(gate) {
+  if (!gate || typeof gate !== "object" || typeof gate.id !== "string" || !gate.id.trim()) return "invalid_definition";
+  if (typeof gate.command !== "string" || !gate.command.trim() || /^REPLACE_ME/.test(gate.command.trim())) return "missing_trusted_command";
+  if ((gate.executor ?? "control-plane") !== "control-plane") return "unsupported_executor";
+  return null;
+}
+
+/**
+ * Resolve the repository gate catalog and an optional card-level additive
+ * selection. The returned gate objects are copies so a selected optional gate
+ * can be promoted to required without mutating the trusted catalog.
+ */
+export function resolveGateSelection(gates, requiredGateIds = undefined) {
+  if (!Array.isArray(gates)) throw new Error("trusted gates must be an array");
+  const cardRequiredGateIds = normalizeRequiredGateIds(requiredGateIds);
+  const selected = new Set(cardRequiredGateIds);
+  const definitions = new Map();
+  const duplicateGateIds = new Set();
+  for (const gate of gates) {
+    if (typeof gate?.id !== "string" || !gate.id.trim()) continue;
+    const id = gate.id.trim();
+    if (definitions.has(id)) duplicateGateIds.add(id);
+    else definitions.set(id, gate);
+  }
+
+  const missingGateIds = cardRequiredGateIds.filter((id) => !definitions.has(id));
+  const invalidGateIds = cardRequiredGateIds
+    .filter((id) => definitions.has(id) && (duplicateGateIds.has(id) || selectedGateIssues(definitions.get(id))))
+    .map((id) => ({ id, reason: duplicateGateIds.has(id) ? "duplicate_definition" : selectedGateIssues(definitions.get(id)) }));
+  const baselineRequiredGateIds = [];
+  const baselineRequired = new Set();
+  for (const gate of gates) {
+    const id = typeof gate?.id === "string" ? gate.id.trim() : "";
+    if (id && gate.required !== false && !baselineRequired.has(id)) {
+      baselineRequired.add(id);
+      baselineRequiredGateIds.push(id);
+    }
+  }
+
+  const mode = cardRequiredGateIds.length > 0 ? "selected" : "legacy";
+  if (mode === "legacy") {
+    return {
+      mode,
+      card_required_gate_ids: [],
+      baseline_required_gate_ids: baselineRequiredGateIds,
+      effective_gate_ids: gates.map((gate) => typeof gate?.id === "string" && gate.id.trim() ? gate.id.trim() : "unknown"),
+      effective_required_gate_ids: baselineRequiredGateIds,
+      missing_gate_ids: [],
+      invalid_gate_ids: [],
+      effective_gates: gates.map((gate) => ({ ...gate }))
+    };
+  }
+
+  const effectiveGateIds = [];
+  const effectiveRequiredGateIds = [];
+  const effectiveGates = [];
+  const emitted = new Set();
+  for (const gate of gates) {
+    const id = typeof gate?.id === "string" ? gate.id.trim() : "";
+    if (!id || emitted.has(id)) continue;
+    const isSelected = selected.has(id);
+    const isGlobalRequired = gate.required !== false;
+    if (mode === "selected" && !isGlobalRequired && !isSelected) continue;
+    emitted.add(id);
+    effectiveGateIds.push(id);
+    if (isGlobalRequired || isSelected) effectiveRequiredGateIds.push(id);
+    effectiveGates.push(isSelected ? { ...gate, required: true } : { ...gate });
+  }
+  for (const id of cardRequiredGateIds) {
+    if (!effectiveGateIds.includes(id)) effectiveGateIds.push(id);
+    if (!effectiveRequiredGateIds.includes(id)) effectiveRequiredGateIds.push(id);
+  }
+
+  return {
+    mode,
+    card_required_gate_ids: cardRequiredGateIds,
+    baseline_required_gate_ids: baselineRequiredGateIds,
+    effective_gate_ids: effectiveGateIds,
+    effective_required_gate_ids: effectiveRequiredGateIds,
+    missing_gate_ids: missingGateIds,
+    invalid_gate_ids: invalidGateIds,
+    effective_gates: effectiveGates
+  };
+}
+
+export function gateSelectionEvidence(selection) {
+  if (!selection) return null;
+  return {
+    mode: selection.mode,
+    card_required_gate_ids: selection.card_required_gate_ids,
+    baseline_required_gate_ids: selection.baseline_required_gate_ids,
+    effective_gate_ids: selection.effective_gate_ids,
+    effective_required_gate_ids: selection.effective_required_gate_ids,
+    missing_gate_ids: selection.missing_gate_ids,
+    invalid_gate_ids: selection.invalid_gate_ids
+  };
+}
+
 export async function executeGates(gates, worktree, logDirectory) {
   const results = [];
   for (const gate of gates) {

package/runtime/triad-verify.mjs

@@ -5,7 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAtomicJson } from "./lib/evidence.mjs";
 import { calculateCandidateFingerprint, collectCandidateChanges, worktreeBranch } from "./lib/fingerprint.mjs";
-import { executeGates, loadTrustedGates } from "./lib/gates.mjs";
+import { executeGates, gateSelectionEvidence, loadTrustedGates, resolveGateSelection } from "./lib/gates.mjs";
 import { evaluateScopeContract, parseScopeContract } from "./lib/scope-contract.mjs";
 
 const argv = process.argv.slice(2);
@@ -65,7 +65,7 @@ async function resolveAssignment(projectRoot, trigger, explicitAssignment) {
   return { assignmentPath, assignment: JSON.parse(source), assignmentHash: sha256(source) };
 }
 
-async function buildInvalidEvidence({ runId, trigger, assignment, reason, outputPath }) {
+async function buildInvalidEvidence({ runId, trigger, assignment, reason, outputPath, failureCode = "verification_context_invalid", gateSelection = null }) {
   const evidence = {
     schema_version: 1,
     run_id: runId,
@@ -83,9 +83,10 @@ async function buildInvalidEvidence({ runId, trigger, assignment, reason, output
     gates: [],
     required_gates_passed: false,
     status: "invalid_context",
-    failure: { code: "verification_context_invalid", reason },
+    failure: { code: failureCode, reason },
     created_at: new Date().toISOString(),
   };
+  if (gateSelection) evidence.gate_selection = gateSelectionEvidence(gateSelection);
   if (outputPath) await writeAtomicJson(outputPath, evidence);
   return evidence;
 }
@@ -145,6 +146,7 @@ async function main() {
   let assignment;
   let assignmentPath;
   let outputPath;
+  let gateSelection = null;
   try {
     let assignmentHash;
     ({ assignmentPath, assignment, assignmentHash } = await resolveAssignment(projectRoot, trigger, option("--assignment")));
@@ -170,6 +172,23 @@ async function main() {
     const before = await calculateCandidateFingerprint(worktree);
     const branch = await worktreeBranch(worktree);
     if (assignment.expected_branch && assignment.expected_branch !== branch) throw new Error("worktree branch does not match assignment");
+    const gatesPath = path.resolve(projectRoot, assignment.gates_path ?? ".loop/quality-gates.yaml");
+    const trusted = await loadTrustedGates(gatesPath, assignment.expected_gates_sha256);
+    if (!trusted.valid) throw new Error("quality gates are missing or changed from their declared hash");
+    try {
+      gateSelection = resolveGateSelection(trusted.gates, assignment.required_gate_ids);
+    } catch (error) {
+      error.code = "unavailable_required_gate";
+      throw error;
+    }
+    if (gateSelection.missing_gate_ids.length > 0 || gateSelection.invalid_gate_ids.length > 0) {
+      const missing = gateSelection.missing_gate_ids.join(", ");
+      const invalid = gateSelection.invalid_gate_ids.map(({ id, reason }) => `${id} (${reason})`).join(", ");
+      const details = [missing && `missing: ${missing}`, invalid && `invalid: ${invalid}`].filter(Boolean).join("; ");
+      const error = new Error(`unavailable_required_gate: ${details}`);
+      error.code = "unavailable_required_gate";
+      throw error;
+    }
     const scope = await scopePreflight(projectRoot, worktree, assignment);
     if (scope.status === "fail") {
       const evidence = {
@@ -192,6 +211,7 @@ async function main() {
         repository_skills: repositorySkills,
         scope,
         gates: [],
+        gate_selection: gateSelectionEvidence(gateSelection),
         required_gates_passed: false,
         status: "fail",
         failure: { code: "candidate_scope_violation", reason: "candidate changed paths exceed the declared scope contract" },
@@ -202,11 +222,8 @@ async function main() {
       process.exitCode = 2;
       return;
     }
-    const gatesPath = path.resolve(projectRoot, assignment.gates_path ?? ".loop/quality-gates.yaml");
-    const trusted = await loadTrustedGates(gatesPath, assignment.expected_gates_sha256);
-    if (!trusted.valid) throw new Error("quality gates are missing or changed from their declared hash");
     const logDirectory = path.join(evidenceDirectory, "logs");
-    const gates = await executeGates(trusted.gates, worktree, logDirectory);
+    const gates = await executeGates(gateSelection.effective_gates, worktree, logDirectory);
     const after = await calculateCandidateFingerprint(worktree);
     const candidateChanged = before.value !== after.value;
     const requiredGatesPassed = !candidateChanged && gates.filter((gate) => gate.required).every((gate) => gate.status === "pass");
@@ -229,6 +246,7 @@ async function main() {
       },
       repository_skills: repositorySkills,
       scope,
+      gate_selection: gateSelectionEvidence(gateSelection),
       gates,
       required_gates_passed: requiredGatesPassed,
       status: candidateChanged ? "invalidated" : requiredGatesPassed ? "pass" : "fail",
@@ -244,7 +262,15 @@ async function main() {
       const directory = path.join(projectRoot, ".loop", "evidence", fallbackAssignment.feature_id, `attempt-${String(fallbackAssignment.attempt).padStart(3, "0")}`);
       outputPath = path.join(directory, "verification.json");
     }
-    const evidence = await buildInvalidEvidence({ runId, trigger, assignment: fallbackAssignment, reason: error.message, outputPath });
+    const evidence = await buildInvalidEvidence({
+      runId,
+      trigger,
+      assignment: fallbackAssignment,
+      reason: error.message,
+      outputPath,
+      failureCode: error.code ?? "verification_context_invalid",
+      gateSelection
+    });
     process.stdout.write(`${JSON.stringify({ run_id: runId, status: evidence.status, evidence: outputPath ?? null })}\n`);
     process.exitCode = 3;
   }

package/schemas/verification-evidence.schema.json

@@ -23,6 +23,26 @@
         "offending_paths": { "type": "array" }
       }
     },
+    "gate_selection": {
+      "type": "object",
+      "required": ["mode", "card_required_gate_ids", "baseline_required_gate_ids", "effective_gate_ids", "effective_required_gate_ids", "missing_gate_ids", "invalid_gate_ids"],
+      "properties": {
+        "mode": { "enum": ["legacy", "selected"] },
+        "card_required_gate_ids": { "type": "array", "items": { "type": "string" } },
+        "baseline_required_gate_ids": { "type": "array", "items": { "type": "string" } },
+        "effective_gate_ids": { "type": "array", "items": { "type": "string" } },
+        "effective_required_gate_ids": { "type": "array", "items": { "type": "string" } },
+        "missing_gate_ids": { "type": "array", "items": { "type": "string" } },
+        "invalid_gate_ids": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "reason"],
+            "properties": { "id": { "type": "string" }, "reason": { "type": "string" } }
+          }
+        }
+      }
+    },
     "gates": { "type": "array" },
     "required_gates_passed": { "type": "boolean" },
     "status": { "enum": ["pass", "fail", "invalid_context", "infrastructure_error", "invalidated"] },

package/skills/triad-loop-bootstrap/SKILL.md

@@ -23,6 +23,10 @@ conditions, runnable quality gates, practical-test need, and integration need.
 5. Replace every gate placeholder. Gate executors in v1 are only
    `control-plane`; remove a non-applicable gate with a recorded reason instead
    of declaring manual or MCP execution.
+   Preserve each card's structured `required_gates` list in the work queue. An
+   absent or empty list keeps the legacy project-gate behavior; selected IDs are
+   additive and must be validated against the trusted gate catalog before a
+   Developer assignment is created.
 6. Create `.loop/runtime/assignments/` and record the active adapter metadata in
    `.loop/runtime/capabilities.json` by running
    `.triad-runtime/triad-runtime-capabilities.mjs --adapter

package/skills/triad-loop-bootstrap/assets/loop-template/feature-card.template.md

@@ -20,7 +20,7 @@
 | --- | --- | --- |
 | `<metric>` | `<exact target>` | `<command/measurement>` |
 
-- Required gates: `<gate IDs>`
+- Required gates (`required_gates`): `<gate IDs; additive to globally required gates; empty/absent preserves existing project behavior>`
 - Allowed dependencies: `<names or none>`
 - Test fixtures/examples: `<paths>`
 

package/skills/triad-loop-bootstrap/assets/loop-template/runtime/assignments/assignment.template.json

@@ -16,6 +16,7 @@
   "expected_prd_sha256": "REPLACE_ME_SHA256",
   "expected_card_sha256": "REPLACE_ME_SHA256",
   "expected_gates_sha256": "REPLACE_ME_SHA256",
+  "required_gate_ids": [],
   "scope_contract": null,
   "required_repository_skills": [
     {

package/skills/triad-loop-orchestrator/SKILL.md

@@ -31,6 +31,17 @@ presentation for this invocation, do not repeat it.
 1. Verify the PRD hash, declared worktree/branch, repository instructions,
    runnable gates, and capability snapshot. The snapshot must reflect
    `project.control_plane.dispatch_mode` as `requested_mode` (default `auto`).
+   Read each card's structured `required_gates` list from the queue; do not
+   infer gate requirements from prose, filenames, or repository type. An absent
+   or empty list is legacy mode. For a non-empty list, load the trusted gate
+   catalog and normalize/dedupe the IDs, then validate that every selected gate
+   exists, has a configured non-placeholder command, and uses a supported
+   executor. An unavailable or invalid selected gate is an owner-visible
+   capability gap (`unavailable_required_gate`): do not dispatch the Developer
+   and consume no retry budget. Bind the normalized IDs as
+   `required_gate_ids` in the assignment together with the existing gate path
+   and hash; the trusted catalog remains authoritative for command, timeout, and
+   executor details.
    When repository instructions define
    a skill router, read it, select the router, routed skills, and completion
    skill required by the card, and bind their worktree-relative paths plus
@@ -45,8 +56,11 @@ presentation for this invocation, do not repeat it.
    attempt, and create an active assignment before delegating. Before each
    delegation, publish an owner-facing activation notice that attributes the
    configured display name, technical role, and card/attempt to that role.
-3. Give the Developer the card, relevant PRD excerpt, allowed surface, gates,
-   risks, and prior findings. Treat its command results and report as
+3. Give the Developer the card, relevant PRD excerpt, allowed surface, the
+   effective gate IDs (all trusted `required: true` gates plus the card's
+   selected IDs), risks, and prior findings. Globally required gates are never
+   suppressed. In selected mode, a selected optional gate is required for that card and unselected optional gates may be
+   skipped; dedupe the effective set. Treat its command results and report as
    **agent-reported claims**, never as control-plane gate truth.
 4. After completion, move to `verifying`. Follow the recorded dispatch route:
    wait for a valid hook-produced file when one is configured, otherwise invoke
@@ -61,7 +75,11 @@ presentation for this invocation, do not repeat it.
    A Developer report is never a human-input wait condition: immediately wait
    for the configured hook evidence or invoke the verifier, then immediately
    dispatch the Reviewer on a verifier pass. Do not ask the owner to continue
-   between Developer completion, verification, and review.
+   between Developer completion, verification, and review. The verifier
+   resolves the assignment's `required_gate_ids` against the same trusted
+   catalog and fails closed if a stale assignment names a missing or invalid
+   gate. It records the selection mode, card IDs, effective IDs, and required
+   IDs in the verification evidence.
 5. A passing verifier result is **environment-derived evidence**. Move only then
    to `in_review`. Missing, stale, failed, timed-out, invalid-context, or
    invalidated evidence never advances the card.