triad-plus 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triad-plus",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A lightweight, evidence-backed engineering loop for coding agents.",
   "license": "Apache-2.0",
   "type": "module",

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.