triad-plus 1.4.2 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.5.0 — 2026-09-05
+
+- Add cause-coded retry/recovery accounting with independent finite runtime and
+  candidate-remediation budgets, plus fail-closed retry-policy validation while
+  retaining backward-compatible legacy retry behavior.
+- Add opt-in deterministic candidate scope contracts with card-level baselines,
+  changed-path evidence, and scope verification before expensive gates.
+- Keep independent Reviewer approval mandatory after deterministic verification.
+
 ## 1.4.2 — 2026-09-01
 
 - Align package repository, homepage, and issue links with the renamed GitHub

package/docs/configuration.md

@@ -30,3 +30,13 @@ different hosts. The team file records role-level models and effort, but an
 adapter writes those into host-native profiles only where the selected host
 supports that facility. A blank model means the host default. Never put tokens,
 API keys, or private deployment data in this file.
+
+## Retry and scope policy
+
+New control workspaces use separate finite budgets for environment recovery and
+candidate remediation. Existing workspaces that only declare
+`max_rework_attempts_per_item` retain that legacy policy. A card may optionally
+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.

package/docs/operating-guide.it.md

@@ -44,6 +44,15 @@ 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.
 
+## Retry e scope del candidato
+
+Gli attempt sono record storici di esecuzione. I nuovi workspace separano e
+limitano le transizioni di recovery runtime e di remediation del candidato: un
+rework o uno scope cleanup non consuma il budget di recovery. Una card può
+attivare un contratto deterministico sui path; il verifier confronta il delta
+completo con il baseline originario della card prima dei gate costosi. Uno scope
+PASS non sostituisce mai la review indipendente.
+
 ## Evaluator+
 
 Evaluator+ è opzionale e fuori dal loop produttivo. Se abilitato in `team.json`,

package/docs/operating-guide.md

@@ -45,6 +45,16 @@ 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.
 
+## Retry accounting and candidate scope
+
+Attempts are historical execution records. New workspaces separately bound
+runtime recovery and candidate remediation transitions; a rework or scope
+cleanup does not consume recovery capacity. A card can opt in to a deterministic
+path scope contract. The verifier checks the complete card delta against the
+card's original baseline before expensive gates; a scope failure returns only a
+bounded cleanup to Developer. A scope pass never replaces independent Reviewer
+review.
+
 ## Evaluator+
 
 Evaluator+ is optional and outside the production loop. When enabled in

package/docs/verification.md

@@ -29,6 +29,27 @@ 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.
 
+## Optional deterministic candidate scope
+
+Cards may add a versioned JSON scope contract, bound by path and SHA-256 in the
+Developer assignment. The contract names repository-relative `allowed_paths`,
+optional `allowed_incidental_paths`, and `forbidden_paths` for each target
+repository. It uses a small glob syntax: `*` does not cross a directory,
+`**` may cross directories, and `?` matches one non-separator character.
+
+For a scope-bound card, the Orchestrator captures a clean card baseline commit
+before the first assignment and reuses it for every rework attempt. The verifier
+compares the full cumulative candidate delta against that baseline before running
+expensive gates. It records changed paths and offending paths in evidence. A
+scope failure skips expensive gates and Reviewer dispatch; it is bounded
+`scope_cleanup`, not approval. A card without a scope contract records
+`scope_not_configured` and retains legacy behavior.
+
+Package manifests and lockfiles require an explicit `allowed_incidental_paths`
+entry. Snapshot patterns must be narrow; broad `snapshots/**` contracts are
+rejected. A scope pass is only a deterministic path check: Reviewer remains
+mandatory for semantic scope, correctness, design, and risk.
+
 ## Codex dispatch modes
 
 Codex uses `explicit_dispatch` by default, including when a compatible async

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triad-plus",
-  "version": "1.4.2",
+  "version": "1.5.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/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",
     "pack:check": "npm pack --dry-run"
   },
   "repository": {

package/runtime/lib/fingerprint.mjs

@@ -20,6 +20,70 @@ async function gitLines(worktree, args) {
   return parseLines(result.stdout);
 }
 
+async function gitOutput(worktree, args) {
+  const result = await runProcess("git", args, { cwd: worktree, timeoutMs: 15_000 });
+  if (result.exitCode !== 0) throw new Error(`git ${args.join(" ")} failed`);
+  return result.stdout;
+}
+
+function ignored(relativePath) {
+  return SENSITIVE_PATH.test(relativePath) || IGNORED_PATH.test(relativePath);
+}
+
+function statusFrom(code) {
+  if (code.startsWith("R")) return "renamed";
+  if (code.startsWith("A")) return "added";
+  if (code.startsWith("D")) return "deleted";
+  return "modified";
+}
+
+function parseNameStatus(source) {
+  const entries = [];
+  for (const line of source.split("\n")) {
+    if (!line) continue;
+    const [code, firstPath, secondPath] = line.split("\t");
+    if (!code || !firstPath) continue;
+    if (code.startsWith("R")) {
+      if (!secondPath) throw new Error("git rename entry is missing destination path");
+      entries.push({ status: "renamed", source: firstPath, destination: secondPath });
+    } else {
+      entries.push({ status: statusFrom(code), path: firstPath });
+    }
+  }
+  return entries;
+}
+
+function pathsFor(entry) {
+  return entry.status === "renamed" ? [entry.source, entry.destination] : [entry.path];
+}
+
+export async function collectCandidateChanges(worktree, { baseCommit = null } = {}) {
+  const root = await realpath(worktree);
+  const head = (await gitLines(root, ["rev-parse", "HEAD"]))[0] ?? "NO_HEAD";
+  const base = baseCommit ?? head;
+  await gitLines(root, ["rev-parse", "--verify", `${base}^{commit}`]);
+  const tracked = parseNameStatus(await gitOutput(root, ["diff", "--name-status", "--find-renames", base]));
+  const known = new Set(tracked.flatMap(pathsFor));
+  for (const relativePath of await gitLines(root, ["ls-files", "--others", "--exclude-standard"])) {
+    if (!known.has(relativePath)) tracked.push({ status: "untracked", path: relativePath });
+  }
+  const changes = [];
+  const ignored_paths = [];
+  for (const entry of tracked) {
+    const entryPaths = pathsFor(entry);
+    if (entryPaths.some(ignored)) {
+      ignored_paths.push(...entryPaths.filter(ignored));
+      continue;
+    }
+    for (const relativePath of entryPaths) {
+      const absolutePath = path.resolve(root, relativePath);
+      if (!absolutePath.startsWith(`${root}${path.sep}`)) throw new Error(`unsafe changed path: ${relativePath}`);
+    }
+    changes.push(entry);
+  }
+  return { git_head: head, base_commit: base, changes, ignored_paths: [...new Set(ignored_paths)].sort() };
+}
+
 export async function worktreeBranch(worktree) {
   const root = await realpath(worktree);
   return (await gitLines(root, ["branch", "--show-current"]))[0] ?? "DETACHED";
@@ -27,26 +91,32 @@ export async function worktreeBranch(worktree) {
 
 export async function calculateCandidateFingerprint(worktree) {
   const root = await realpath(worktree);
-  const head = (await gitLines(root, ["rev-parse", "HEAD"]))[0] ?? "NO_HEAD";
-  const changed = new Set([
-    ...(await gitLines(root, ["diff", "--name-only"])),
-    ...(await gitLines(root, ["diff", "--cached", "--name-only"])),
-    ...(await gitLines(root, ["ls-files", "--others", "--exclude-standard"])),
-  ]);
+  const candidate = await collectCandidateChanges(root);
   const files = [];
-  for (const relativePath of [...changed].sort()) {
-    if (SENSITIVE_PATH.test(relativePath) || IGNORED_PATH.test(relativePath)) continue;
+  const changed = new Map();
+  for (const entry of candidate.changes) {
+    if (entry.status === "renamed") {
+      changed.set(entry.source, "DELETED");
+      changed.set(entry.destination, null);
+    } else {
+      changed.set(entry.path, entry.status === "deleted" ? "DELETED" : null);
+    }
+  }
+  for (const [relativePath, knownHash] of [...changed.entries()].sort(([left], [right]) => left.localeCompare(right))) {
     const absolutePath = path.resolve(root, relativePath);
     if (!absolutePath.startsWith(`${root}${path.sep}`)) throw new Error(`unsafe changed path: ${relativePath}`);
-    let contentHash = "DELETED";
-    try {
-      const metadata = await stat(absolutePath);
-      if (metadata.isFile()) contentHash = digest(await readFile(absolutePath));
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
+    let contentHash = knownHash;
+    if (contentHash === null) {
+      contentHash = "DELETED";
+      try {
+        const metadata = await stat(absolutePath);
+        if (metadata.isFile()) contentHash = digest(await readFile(absolutePath));
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
     }
     files.push({ path: relativePath, sha256: contentHash });
   }
-  const canonical = JSON.stringify({ git_head: head, files });
-  return { algorithm: "sha256", value: digest(canonical), git_head: head, files };
+  const canonical = JSON.stringify({ git_head: candidate.git_head, files });
+  return { algorithm: "sha256", value: digest(canonical), git_head: candidate.git_head, files };
 }

package/runtime/lib/retry-accounting.mjs

@@ -0,0 +1,112 @@
+export const resolutionKinds = new Set([
+  "runtime_recovery",
+  "verifier_infrastructure_failure",
+  "verifier_candidate_failure",
+  "reviewer_rework",
+  "scope_cleanup",
+  "blocked"
+]);
+
+const runtimeKinds = new Set(["runtime_recovery", "verifier_infrastructure_failure"]);
+const candidateKinds = new Set(["verifier_candidate_failure", "reviewer_rework", "scope_cleanup"]);
+
+export function budgetFamily(kind) {
+  if (runtimeKinds.has(kind)) return "runtime";
+  if (candidateKinds.has(kind)) return "candidate_remediation";
+  if (kind === "blocked") return null;
+  throw new Error(`Unknown retry resolution kind: ${kind}`);
+}
+
+export function retryPolicyMode(policy = {}) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new Error("retry policy must define either a valid legacy max_rework_attempts_per_item or both max_runtime_recoveries_per_item and max_candidate_remediations_per_item");
+  }
+
+  const hasRuntime = Object.hasOwn(policy, "max_runtime_recoveries_per_item");
+  const hasCandidate = Object.hasOwn(policy, "max_candidate_remediations_per_item");
+  const runtime = policy.max_runtime_recoveries_per_item;
+  const candidate = policy.max_candidate_remediations_per_item;
+
+  if (hasRuntime || hasCandidate) {
+    if (hasRuntime && hasCandidate && Number.isInteger(runtime) && runtime >= 0 && Number.isInteger(candidate) && candidate >= 0) {
+      return "cause_coded";
+    }
+    throw new Error("retry policy must define either a valid legacy max_rework_attempts_per_item or both max_runtime_recoveries_per_item and max_candidate_remediations_per_item");
+  }
+
+  const legacy = policy.max_rework_attempts_per_item;
+  if (Number.isInteger(legacy) && legacy >= 0) return "legacy";
+
+  throw new Error("retry policy must define either a valid legacy max_rework_attempts_per_item or both max_runtime_recoveries_per_item and max_candidate_remediations_per_item");
+}
+
+export function classifyVerifierResolution(evidence = {}) {
+  if (evidence.status === "infrastructure_error" || evidence?.failure?.code === "verified_infrastructure_failure") {
+    return "verifier_infrastructure_failure";
+  }
+  return "verifier_candidate_failure";
+}
+
+function automaticResolution(attempt) {
+  return attempt?.resolution?.automatic === true ? attempt.resolution : null;
+}
+
+function legacyReworkCount(attempts) {
+  return attempts.filter((attempt) => attempt?.state === "rework").length;
+}
+
+function causeCount(attempts, family) {
+  return attempts
+    .map(automaticResolution)
+    .filter(Boolean)
+    .filter((resolution) => budgetFamily(resolution.kind) === family)
+    .length;
+}
+
+export function evaluateAutomaticRetry({ policy = {}, attempts = [], kind }) {
+  if (!resolutionKinds.has(kind)) throw new Error(`Unsupported retry resolution kind: ${kind}`);
+  const mode = retryPolicyMode(policy);
+  if (kind === "blocked") {
+    return {
+      mode,
+      allowed: false,
+      reason: "blocked_never_retries_automatically",
+      family: null,
+      previous_automatic_transitions: 0,
+      maximum: 0
+    };
+  }
+
+  if (mode === "legacy") {
+    const maximum = policy.max_rework_attempts_per_item;
+    if (!Number.isInteger(maximum) || maximum < 0) throw new Error("Legacy retry policy requires max_rework_attempts_per_item");
+    const previous = legacyReworkCount(attempts);
+    return {
+      mode,
+      allowed: previous < maximum,
+      reason: previous < maximum ? "legacy_rework_budget_available" : "legacy_rework_budget_exhausted",
+      family: "legacy_rework",
+      previous_automatic_transitions: previous,
+      maximum
+    };
+  }
+
+  const family = budgetFamily(kind);
+  const policyKey = family === "runtime" ? "max_runtime_recoveries_per_item" : "max_candidate_remediations_per_item";
+  const maximum = policy[policyKey];
+  const previous = causeCount(attempts, family);
+  return {
+    mode,
+    allowed: previous < maximum,
+    reason: previous < maximum ? `${family}_budget_available` : `${family}_budget_exhausted`,
+    family,
+    previous_automatic_transitions: previous,
+    maximum
+  };
+}
+
+export function resolutionRecord(kind, evidenceRefs = [], automatic = true) {
+  if (!resolutionKinds.has(kind)) throw new Error(`Unsupported retry resolution kind: ${kind}`);
+  if (!Array.isArray(evidenceRefs)) throw new Error("resolution evidence_refs must be an array");
+  return { kind, evidence_refs: evidenceRefs, automatic };
+}

package/runtime/lib/scope-contract.mjs

@@ -0,0 +1,109 @@
+const packagePaths = /(?:^|\/)(?:package\.json|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock)$/;
+
+function normalized(value) {
+  if (typeof value !== "string" || !value || value.startsWith("/") || value.split("/").includes("..")) {
+    throw new Error("scope paths and patterns must be non-empty repository-relative paths");
+  }
+  return value.replaceAll("\\", "/");
+}
+
+function patternExpression(pattern) {
+  let expression = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    const next = pattern[index + 1];
+    if (character === "*" && next === "*") {
+      if (pattern[index + 2] === "/") {
+        expression += "(?:.*/)?";
+        index += 2;
+      } else {
+        expression += ".*";
+        index += 1;
+      }
+    } else if (character === "*") {
+      expression += "[^/]*";
+    } else if (character === "?") {
+      expression += "[^/]";
+    } else {
+      expression += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${expression}$`);
+}
+
+function validatePatterns(patterns, label) {
+  if (patterns === undefined) return [];
+  if (!Array.isArray(patterns)) throw new Error(`${label} must be an array`);
+  return patterns.map((pattern) => {
+    const value = normalized(pattern);
+    if ((value.includes("/snapshots/") || value.startsWith("snapshots/")) && (value.startsWith("**/") || value.includes("/snapshots/**") || value.startsWith("snapshots/**") || value.endsWith("/**"))) {
+      throw new Error(`snapshot pattern is too broad: ${value}`);
+    }
+    patternExpression(value);
+    return value;
+  });
+}
+
+export function validateScopeContract(contract) {
+  if (!contract || contract.schema_version !== 1 || contract.mode !== "enforce" || !contract.repositories || typeof contract.repositories !== "object" || Array.isArray(contract.repositories)) {
+    throw new Error("scope contract requires schema_version 1, mode enforce, and repositories");
+  }
+  const repositories = {};
+  for (const [repository, value] of Object.entries(contract.repositories)) {
+    if (!repository || !value || typeof value !== "object" || Array.isArray(value)) throw new Error("scope contract repository entries must be objects");
+    const allowed = validatePatterns(value.allowed_paths, `allowed_paths for ${repository}`);
+    if (allowed.length === 0) throw new Error(`allowed_paths for ${repository} must not be empty`);
+    repositories[repository] = {
+      allowed_paths: allowed,
+      allowed_incidental_paths: validatePatterns(value.allowed_incidental_paths, `allowed_incidental_paths for ${repository}`),
+      forbidden_paths: validatePatterns(value.forbidden_paths, `forbidden_paths for ${repository}`)
+    };
+  }
+  return { schema_version: 1, mode: "enforce", repositories };
+}
+
+function matches(pathname, patterns) {
+  return patterns.some((pattern) => patternExpression(pattern).test(pathname));
+}
+
+function pathChecks(change) {
+  if (change.status === "renamed") {
+    return [
+      { path: change.source, side: "source" },
+      { path: change.destination, side: "destination" }
+    ];
+  }
+  return [{ path: change.path, side: null }];
+}
+
+export function evaluateScopeContract({ contract, repository, changes }) {
+  const validated = validateScopeContract(contract);
+  const surface = validated.repositories[repository];
+  if (!surface) throw new Error(`scope contract has no surface for repository: ${repository}`);
+  const offending_paths = [];
+  for (const change of changes) {
+    for (const check of pathChecks(change)) {
+      const pathname = normalized(check.path);
+      let reason = null;
+      if (matches(pathname, surface.forbidden_paths)) reason = "forbidden_path";
+      else if (packagePaths.test(pathname) && !matches(pathname, surface.allowed_incidental_paths)) reason = "package_or_lock_requires_explicit_incidental_allowance";
+      else if (!matches(pathname, surface.allowed_paths) && !matches(pathname, surface.allowed_incidental_paths)) reason = "outside_allowed_surface";
+      if (reason) offending_paths.push({ path: pathname, status: change.status, ...(check.side ? { side: check.side } : {}), reason });
+    }
+  }
+  return {
+    configured: true,
+    status: offending_paths.length === 0 ? "pass" : "fail",
+    repository,
+    changed_paths: changes,
+    offending_paths
+  };
+}
+
+export function parseScopeContract(source) {
+  try {
+    return validateScopeContract(JSON.parse(source));
+  } catch (error) {
+    throw new Error(`invalid scope contract: ${error.message}`);
+  }
+}

package/runtime/triad-verify.mjs

@@ -4,8 +4,9 @@ import { access, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAtomicJson } from "./lib/evidence.mjs";
-import { calculateCandidateFingerprint, worktreeBranch } from "./lib/fingerprint.mjs";
+import { calculateCandidateFingerprint, collectCandidateChanges, worktreeBranch } from "./lib/fingerprint.mjs";
 import { executeGates, loadTrustedGates } from "./lib/gates.mjs";
+import { evaluateScopeContract, parseScopeContract } from "./lib/scope-contract.mjs";
 
 const argv = process.argv.slice(2);
 const option = (name) => {
@@ -89,6 +90,51 @@ async function buildInvalidEvidence({ runId, trigger, assignment, reason, output
   return evidence;
 }
 
+function withinRoot(root, candidate, label) {
+  const resolved = path.resolve(root, candidate);
+  if (!resolved.startsWith(`${root}${path.sep}`)) throw new Error(`${label} escapes project root`);
+  return resolved;
+}
+
+async function scopePreflight(projectRoot, worktree, assignment) {
+  const specification = assignment.scope_contract;
+  if (specification === undefined) {
+    const candidate = await collectCandidateChanges(worktree);
+    return {
+      configured: false,
+      status: "not_configured",
+      baseline: null,
+      changed_paths: candidate.changes,
+      ignored_paths: candidate.ignored_paths,
+      offending_paths: []
+    };
+  }
+  if (!specification || typeof specification !== "object") throw new Error("scope_contract must be an object when declared");
+  if (typeof specification.path !== "string" || typeof specification.sha256 !== "string" || typeof specification.repository_id !== "string") {
+    throw new Error("scope_contract requires path, sha256, and repository_id");
+  }
+  const baseline = specification.card_baseline;
+  if (!baseline || baseline.initial_state !== "clean" || typeof baseline.git_head !== "string" || typeof baseline.repository_id !== "string") {
+    throw new Error("scope_contract requires a clean card_baseline with repository_id and git_head");
+  }
+  if (baseline.repository_id !== specification.repository_id) throw new Error("scope contract repository does not match card baseline repository");
+  const contractPath = withinRoot(projectRoot, specification.path, "scope contract");
+  const source = await readFile(contractPath, "utf8");
+  const actualHash = sha256(source);
+  if (actualHash !== specification.sha256) throw new Error("scope contract hash mismatch");
+  const contract = parseScopeContract(source);
+  const candidate = await collectCandidateChanges(worktree, { baseCommit: baseline.git_head });
+  const changes = candidate.changes.map((change) => ({ ...change, repository: specification.repository_id }));
+  const result = evaluateScopeContract({ contract, repository: specification.repository_id, changes });
+  return {
+    ...result,
+    contract_ref: path.relative(projectRoot, contractPath),
+    contract_sha256: actualHash,
+    baseline: { repository_id: baseline.repository_id, git_head: baseline.git_head },
+    ignored_paths: candidate.ignored_paths
+  };
+}
+
 async function main() {
   const payload = await readStdin();
   const trigger = triggerFrom(payload);
@@ -124,6 +170,38 @@ 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 scope = await scopePreflight(projectRoot, worktree, assignment);
+    if (scope.status === "fail") {
+      const evidence = {
+        schema_version: 1,
+        run_id: runId,
+        feature_id: assignment.feature_id,
+        attempt: assignment.attempt,
+        assignment_id: assignment.assignment_id,
+        assignment_sha256: assignmentHash,
+        trigger,
+        assignment_ref: path.relative(projectRoot, assignmentPath),
+        baseline: {
+          prd_sha256: assignment.expected_prd_sha256,
+          card_sha256: assignment.expected_card_sha256,
+          gates_sha256: null,
+          git_head: before.git_head,
+          candidate_fingerprint: before.value,
+          branch,
+        },
+        repository_skills: repositorySkills,
+        scope,
+        gates: [],
+        required_gates_passed: false,
+        status: "fail",
+        failure: { code: "candidate_scope_violation", reason: "candidate changed paths exceed the declared scope contract" },
+        created_at: new Date().toISOString(),
+      };
+      await writeAtomicJson(outputPath, evidence);
+      process.stdout.write(`${JSON.stringify({ run_id: runId, status: evidence.status, evidence: outputPath })}\n`);
+      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");
@@ -150,6 +228,7 @@ async function main() {
         branch,
       },
       repository_skills: repositorySkills,
+      scope,
       gates,
       required_gates_passed: requiredGatesPassed,
       status: candidateChanged ? "invalidated" : requiredGatesPassed ? "pass" : "fail",

package/schemas/verification-evidence.schema.json

@@ -13,6 +13,16 @@
     "assignment_sha256": { "type": ["string", "null"] },
     "trigger": { "type": "object", "required": ["event", "agent_id", "agent_type"], "properties": { "event": { "type": "string" }, "agent_id": { "type": ["string", "null"] }, "agent_type": { "type": ["string", "null"] } } },
     "baseline": { "type": "object", "required": ["prd_sha256", "card_sha256", "git_head", "candidate_fingerprint"], "properties": { "prd_sha256": { "type": ["string", "null"] }, "card_sha256": { "type": ["string", "null"] }, "git_head": { "type": ["string", "null"] }, "candidate_fingerprint": { "type": ["string", "null"] }, "branch": { "type": ["string", "null"] } } },
+    "scope": {
+      "type": "object",
+      "properties": {
+        "configured": { "type": "boolean" },
+        "status": { "enum": ["not_configured", "pass", "fail"] },
+        "baseline": { "type": ["object", "null"] },
+        "changed_paths": { "type": "array" },
+        "offending_paths": { "type": "array" }
+      }
+    },
     "gates": { "type": "array" },
     "required_gates_passed": { "type": "boolean" },
     "status": { "enum": ["pass", "fail", "invalid_context", "infrastructure_error", "invalidated"] },

package/skills/triad-loop-bootstrap/assets/loop-template/decision-policy.md

@@ -15,8 +15,25 @@
 Only the Orchestrator records transitions. The verifier writes evidence only.
 Developer and Reviewer reports are agent-reported claims; a `control-plane` gate
 is authoritative only through matching verifier evidence. Every new patch needs
-a new verifier run. Stop automatic retry at the declared limit and record the
-owner decision needed. Normal delivery requires all non-deferred cards approved,
-project gates passed, one local commit per approved card, and declared branches
-pushed. Pull requests, releases, publication, force pushes, and demo start/stop
-remain owner decisions.
+a new verifier run.
+
+For a cause-coded policy, `max_runtime_recoveries_per_item` and
+`max_candidate_remediations_per_item` each mean the number of automatic
+transitions permitted for that family. Before starting a retry, count only prior
+automatic resolutions in that family: if the count is lower than the declared
+maximum, record the resolution and start the next attempt; otherwise record an
+escalation and do not start it. Runtime family: `runtime_recovery`,
+`verifier_infrastructure_failure`. Candidate-remediation family:
+`verifier_candidate_failure`, `reviewer_rework`, `scope_cleanup`. `blocked`
+never starts an automatic retry. An ambiguous verifier failure is candidate
+remediation or an escalation; a Developer claim cannot classify it as
+infrastructure. Existing policies that declare only
+`max_rework_attempts_per_item` retain legacy single-budget accounting.
+When both valid cause-coded limits are present, they take precedence even if the
+legacy limit is also present. The cause-coded limits are an atomic pair: they
+must both be non-negative integers, or both be absent. A partial or malformed
+pair is invalid and must not fall back to legacy accounting.
+
+Normal delivery requires all non-deferred cards approved, project gates passed,
+one local commit per approved card, and declared branches pushed. Pull requests,
+releases, publication, force pushes, and demo start/stop remain owner decisions.

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

@@ -30,6 +30,14 @@
 - Required skills: `<router, routed skills, and completion skill>`
 - Assignment evidence: `<relative SKILL.md paths and SHA-256 values>`
 
+## Optional deterministic scope contract
+
+- Scope contract: `<scope-contracts/<feature ID>.json or not configured>`
+- Repository IDs: `<one or more declared repository IDs>`
+- Card baseline: `<clean commit captured before the first Developer assignment>`
+- The human-readable scope above remains authoritative for semantic review. A
+  configured scope contract only permits deterministic changed-path checks.
+
 ## Integration, practical test, and risk
 
 - Local-worktree setup: `<not applicable or command>`

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",
+  "scope_contract": null,
   "required_repository_skills": [
     {
       "path": ".agents/skills/router/SKILL.md",

package/skills/triad-loop-bootstrap/assets/loop-template/scope-contract.template.json

@@ -0,0 +1,17 @@
+{
+  "schema_version": 1,
+  "mode": "enforce",
+  "repositories": {
+    "product-repository": {
+      "allowed_paths": [
+        "src/example/**",
+        "test/example-*.test.js"
+      ],
+      "allowed_incidental_paths": [],
+      "forbidden_paths": [
+        "package.json",
+        "package-lock.json"
+      ]
+    }
+  }
+}

package/skills/triad-loop-bootstrap/assets/loop-template/work-queue.yaml

@@ -1,6 +1,7 @@
 version: 2
 policy:
-  max_rework_attempts_per_item: 2
+  max_runtime_recoveries_per_item: 2
+  max_candidate_remediations_per_item: 2
   require_reviewer_approval: true
   require_feature_plan_declaration: true
   require_clean_diff_check: true

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

@@ -7,8 +7,12 @@ description: Implement one bounded Triad feature card, add focused tests, and re
 
 Change the artifact to satisfy the assigned goal. Read the card, PRD excerpt,
 project manifest, repository instructions, allowed surface, prior findings, and
-gates. Verify the declared worktree and branch before editing. Do not change
-scope, policy, assignments, queue, state, or evidence records.
+gates. When the assignment contains a scope contract, read it as a deterministic
+path boundary in addition to the human card scope: keep every cumulative change
+from the card baseline within its allowed paths, and use the recorded offending
+paths for `scope_cleanup`. Verify the declared worktree and branch before
+editing. Do not change scope, policy, assignments, queue, state, or evidence
+records.
 
 At the beginning of every activation, read `.triad-plus/team.json` when it
 exists. Your first report to the Orchestrator must identify you as its configured

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

@@ -35,7 +35,12 @@ presentation for this invocation, do not repeat it.
    a skill router, read it, select the router, routed skills, and completion
    skill required by the card, and bind their worktree-relative paths plus
    SHA-256 values in `required_repository_skills` on the Developer assignment.
-   Do not assign the card if this binding cannot be made.
+   Do not assign the card if this binding cannot be made. If the card declares
+   an opt-in scope contract, capture its repository ID, file path, SHA-256, and
+   a clean card baseline commit before its first Developer assignment. Reuse
+   that exact card baseline for every rework attempt: preserved candidate changes
+   are normal during rework. Do not create the first scope-bound assignment from
+   unattributable dirty product changes; record `invalid_context` instead.
 2. Choose one dependency-approved `ready` card, mark it `in_progress`, append an
    attempt, and create an active assignment before delegating. Before each
    delegation, publish an owner-facing activation notice that attributes the
@@ -47,7 +52,12 @@ presentation for this invocation, do not repeat it.
    wait for a valid hook-produced file when one is configured, otherwise invoke
    the verifier explicitly. Accept only current evidence whose assignment ID,
    feature, attempt, PRD/card/gate hashes, expected branch, and candidate
-   fingerprint match the active candidate.
+   fingerprint match the active candidate. When an opt-in scope contract is
+   configured, `triad-verify` first compares the complete candidate delta from
+   the card baseline with that contract. A scope fail records offending paths,
+   runs no expensive gates, and returns only bounded `scope_cleanup` work to the
+   Developer; it never dispatches the Reviewer. `scope_not_configured` preserves
+   legacy behavior.
    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
@@ -60,10 +70,22 @@ presentation for this invocation, do not repeat it.
    - `approved`: verify scope/evidence, commit the card locally, promote every
      dependency-satisfied draft card to `ready`, then immediately select and
      assign the next ready card;
-   - `rework`: preserve findings and return the card to `in_progress` for a new
-     attempt and new verification;
+   - `rework`: preserve findings as `reviewer_rework` and return the card to
+     `in_progress` for a new attempt and new verification;
    - `blocked`: record the exact external condition or owner decision required.
-7. Stop automatic retry at the declared limit and escalate the decision needed.
+7. Attempts are historical execution numbers, not a retry budget. Before an
+   automatic restart, record `resolution.kind`, `evidence_refs`, and whether
+   the transition is automatic. For a cause-coded policy, count only previous
+   automatic transitions in the relevant family: runtime
+   (`runtime_recovery`, `verifier_infrastructure_failure`) or candidate
+   remediation (`verifier_candidate_failure`, `reviewer_rework`,
+   `scope_cleanup`). A maximum of two permits transition #1 and #2, then
+   escalates transition #3. `blocked` never retries. Only verifier/log evidence
+   may classify infrastructure; an ambiguous verifier failure is candidate
+   remediation or an escalation. A legacy policy declaring only
+   `max_rework_attempts_per_item` retains its single-budget behavior; do not
+   silently reset its history. Stop automatic retry at the relevant declared
+   limit and escalate the decision needed.
    Do not ask the owner to continue, pause between cards, or finish the run
    while a dependency-satisfied card remains `ready`; stop only for a declared
    escalation, a blocked card, or when every required card is terminal.