triad-plus 1.6.0 → 1.8.0

package/runtime/lib/quality-baseline.mjs

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+
+const SHA256 = /^[a-f0-9]{64}$/i;
+const QUALITY_SCOPES = new Set(["product_quality", "delivery_closure"]);
+
+function qualityError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Return a JSON-compatible value with object keys sorted recursively. Arrays
+ * intentionally retain their declared order: source and criterion order is
+ * part of the authored contract, while object formatting is not.
+ */
+export function canonicalizeQualityValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeQualityValue);
+  if (!objectLike(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, canonicalizeQualityValue(value[key])])
+  );
+}
+
+export function qualityBaselinePayload(manifest) {
+  if (!objectLike(manifest)) return manifest;
+  const { fingerprint: _fingerprint, ...payload } = manifest;
+  return canonicalizeQualityValue(payload);
+}
+
+export function qualityBaselineFingerprint(manifest) {
+  const canonical = JSON.stringify(qualityBaselinePayload(manifest));
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+function projectRelativePath(root, value, label) {
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value)) {
+    throw qualityError("quality_baseline_invalid", `${label} must be a non-empty project-relative path`);
+  }
+  const normalized = value.replaceAll("\\", "/");
+  const posix = path.posix.normalize(normalized);
+  if (posix === "." || posix === ".." || posix.startsWith("../") || normalized.split("/").includes("..")) {
+    throw qualityError("quality_baseline_invalid", `${label} escapes the project root`);
+  }
+  const resolved = path.resolve(root, normalized);
+  if (!resolved.startsWith(`${root}${path.sep}`)) {
+    throw qualityError("quality_baseline_invalid", `${label} escapes the project root`);
+  }
+  return resolved;
+}
+
+function validateSha(value, label) {
+  if (typeof value !== "string" || !SHA256.test(value)) {
+    throw qualityError("quality_baseline_invalid", `${label} must be a SHA-256 hex digest`);
+  }
+}
+
+function rejectUnknownProperties(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw qualityError("quality_baseline_invalid", `${label} contains unknown property: ${key}`);
+  }
+}
+
+/**
+ * Validate the manifest shape and its self-declared fingerprint without
+ * touching source files. This is useful to callers that only need to inspect
+ * the immutable contract before resolving it against a project.
+ */
+export function validateQualityBaselineManifest(manifest) {
+  if (!objectLike(manifest)) throw qualityError("quality_baseline_invalid", "quality baseline must be a JSON object");
+  rejectUnknownProperties(manifest, new Set(["schema_version", "id", "revision", "sources", "criteria", "fingerprint"]), "quality baseline manifest");
+  if (manifest.schema_version !== 1) throw qualityError("quality_baseline_invalid", "quality baseline schema_version must be 1");
+  if (typeof manifest.id !== "string" || !manifest.id.trim()) throw qualityError("quality_baseline_invalid", "quality baseline id must be non-empty");
+  if (!Number.isInteger(manifest.revision) || manifest.revision < 1) throw qualityError("quality_baseline_invalid", "quality baseline revision must be a positive integer");
+  if (!Array.isArray(manifest.sources) || manifest.sources.length === 0) throw qualityError("quality_baseline_invalid", "quality baseline must declare at least one source");
+  if (!Array.isArray(manifest.criteria)) throw qualityError("quality_baseline_invalid", "quality baseline criteria must be an array");
+
+  const sourceIds = new Set();
+  for (const source of manifest.sources) {
+    if (!objectLike(source)) throw qualityError("quality_baseline_invalid", "quality baseline sources must contain objects");
+    rejectUnknownProperties(source, new Set(["id", "role", "path", "sha256"]), "quality baseline source");
+    if (typeof source.id !== "string" || !source.id.trim()) throw qualityError("quality_baseline_invalid", "quality baseline source id must be non-empty");
+    if (sourceIds.has(source.id)) throw qualityError("quality_baseline_invalid", `duplicate quality baseline source id: ${source.id}`);
+    sourceIds.add(source.id);
+    if (typeof source.role !== "string" || !source.role.trim()) throw qualityError("quality_baseline_invalid", `quality baseline source role is missing: ${source.id}`);
+    if (typeof source.path !== "string" || !source.path.trim() || path.isAbsolute(source.path)) throw qualityError("quality_baseline_invalid", `quality baseline source path must be project-relative: ${source.id}`);
+    const normalizedSourcePath = path.posix.normalize(source.path.replaceAll("\\", "/"));
+    if (normalizedSourcePath === "." || normalizedSourcePath === ".." || normalizedSourcePath.startsWith("../") || source.path.replaceAll("\\", "/").split("/").includes("..")) throw qualityError("quality_baseline_invalid", `quality baseline source path escapes the project root: ${source.id}`);
+    validateSha(source.sha256, `quality baseline source ${source.id}`);
+  }
+
+  const criterionIds = new Set();
+  for (const criterion of manifest.criteria) {
+    if (!objectLike(criterion)) throw qualityError("quality_baseline_invalid", "quality baseline criteria must contain objects");
+    rejectUnknownProperties(criterion, new Set(["id", "scope", "requirement"]), "quality baseline criterion");
+    if (typeof criterion.id !== "string" || !criterion.id.trim()) throw qualityError("quality_baseline_invalid", "quality baseline criterion id must be non-empty");
+    if (criterionIds.has(criterion.id)) throw qualityError("quality_baseline_invalid", `duplicate quality baseline criterion id: ${criterion.id}`);
+    criterionIds.add(criterion.id);
+    if (!QUALITY_SCOPES.has(criterion.scope)) throw qualityError("quality_baseline_invalid", `invalid quality baseline criterion scope: ${criterion.id}`);
+    if (typeof criterion.requirement !== "string" || !criterion.requirement.trim()) throw qualityError("quality_baseline_invalid", `quality baseline criterion requirement must be non-empty: ${criterion.id}`);
+  }
+
+  validateSha(manifest.fingerprint, "quality baseline fingerprint");
+  const calculatedFingerprint = qualityBaselineFingerprint(manifest);
+  if (manifest.fingerprint.toLowerCase() !== calculatedFingerprint) {
+    throw qualityError("quality_baseline_invalid", "quality baseline declared fingerprint does not match its canonical content");
+  }
+  return { manifest, fingerprint: calculatedFingerprint };
+}
+
+async function verifySources(manifest, root) {
+  const verifiedSources = [];
+  for (const source of manifest.sources) {
+    const sourcePath = projectRelativePath(root, source.path, `quality baseline source ${source.id}`);
+    let resolvedSource;
+    try {
+      resolvedSource = await realpath(sourcePath);
+    } catch {
+      throw qualityError("quality_baseline_invalid", `quality baseline source is missing: ${source.path}`);
+    }
+    if (!resolvedSource.startsWith(`${root}${path.sep}`)) {
+      throw qualityError("quality_baseline_invalid", `quality baseline source escapes the project root: ${source.path}`);
+    }
+    let content;
+    try {
+      content = await readFile(resolvedSource);
+    } catch {
+      throw qualityError("quality_baseline_invalid", `quality baseline source cannot be read: ${source.path}`);
+    }
+    const actual = createHash("sha256").update(content).digest("hex");
+    if (actual !== source.sha256.toLowerCase()) {
+      throw qualityError("quality_baseline_drift", `quality baseline source hash mismatch: ${source.path}`);
+    }
+    verifiedSources.push({ id: source.id, path: source.path, sha256: actual });
+  }
+  return verifiedSources;
+}
+
+/**
+ * Load, validate, fingerprint, and resolve the immutable quality contract
+ * against source files under the project root.
+ */
+export async function loadQualityBaseline(manifestPath, { projectRoot = process.cwd(), expectedFingerprint = null } = {}) {
+  const root = await realpath(projectRoot);
+  const resolvedManifestPath = projectRelativePath(root, manifestPath, "quality baseline path");
+  let source;
+  try {
+    source = await readFile(resolvedManifestPath, "utf8");
+  } catch {
+    throw qualityError("quality_baseline_invalid", `quality baseline manifest is missing: ${manifestPath}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(source);
+  } catch (error) {
+    throw qualityError("quality_baseline_invalid", `quality baseline manifest is not valid JSON: ${error.message}`);
+  }
+  const validated = validateQualityBaselineManifest(manifest);
+  if (expectedFingerprint !== null && expectedFingerprint !== undefined) {
+    validateSha(expectedFingerprint, "expected quality baseline fingerprint");
+    if (expectedFingerprint.toLowerCase() !== validated.fingerprint) {
+      throw qualityError("quality_baseline_drift", "quality baseline fingerprint does not match the assignment binding");
+    }
+  }
+  const sources = await verifySources(manifest, root);
+  return {
+    manifest,
+    path: path.relative(root, resolvedManifestPath),
+    fingerprint: validated.fingerprint,
+    sources,
+    criteria: manifest.criteria,
+  };
+}
+
+/** Resolve the optional assignment binding while preserving legacy mode. */
+export async function resolveQualityContract(assignment, projectRoot) {
+  const manifestPath = assignment?.quality_baseline_path;
+  const expectedFingerprint = assignment?.expected_quality_baseline_fingerprint;
+  const pathPresent = typeof manifestPath === "string" && manifestPath.trim();
+  const fingerprintPresent = typeof expectedFingerprint === "string" && expectedFingerprint.trim();
+  if (!pathPresent && !fingerprintPresent) return null;
+  if (!pathPresent || !fingerprintPresent) {
+    throw qualityError("quality_baseline_invalid", "quality contract requires quality_baseline_path and expected_quality_baseline_fingerprint together");
+  }
+  return loadQualityBaseline(manifestPath, { projectRoot, expectedFingerprint });
+}
+
+export function qualityCriteriaByScope(manifestOrContract) {
+  const manifest = manifestOrContract?.manifest ?? manifestOrContract;
+  if (!objectLike(manifest) || !Array.isArray(manifest.criteria)) throw qualityError("quality_baseline_invalid", "quality baseline criteria are unavailable");
+  return {
+    product_quality: manifest.criteria.filter((criterion) => criterion.scope === "product_quality"),
+    delivery_closure: manifest.criteria.filter((criterion) => criterion.scope === "delivery_closure"),
+  };
+}
+
+export { QUALITY_SCOPES };

package/runtime/triad-evaluator-validate.mjs

@@ -0,0 +1,261 @@
+import { loadQualityBaseline, qualityCriteriaByScope, validateQualityBaselineManifest } from "./lib/quality-baseline.mjs";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const VERDICTS = new Set(["PASS", "FAIL", "INDETERMINATE"]);
+const SHA256 = /^[a-f0-9]{64}$/i;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+function evaluatorError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function rejectUnknownProperties(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw evaluatorError("evaluator_result_invalid", `${label} contains unknown property: ${key}`);
+  }
+}
+
+function requireBaseResult(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) throw evaluatorError("evaluator_result_invalid", "Evaluator+ result must be an object");
+  rejectUnknownProperties(result, new Set(["schema_version", "feature_id", "candidate_fingerprint", "quality_baseline_fingerprint", "verdict", "summary", "evidence_refs", "criteria", "created_at"]), "Evaluator+ result");
+  if (result.schema_version !== 1) throw evaluatorError("evaluator_result_invalid", "Evaluator+ schema_version must be 1");
+  if (typeof result.feature_id !== "string" || !result.feature_id.trim()) throw evaluatorError("evaluator_result_invalid", "Evaluator+ feature_id must be non-empty");
+  if (typeof result.candidate_fingerprint !== "string" || !result.candidate_fingerprint.trim()) throw evaluatorError("evaluator_result_invalid", "Evaluator+ candidate_fingerprint must be non-empty");
+  if (result.quality_baseline_fingerprint !== undefined && (typeof result.quality_baseline_fingerprint !== "string" || !SHA256.test(result.quality_baseline_fingerprint))) throw evaluatorError("evaluator_result_invalid", "Evaluator+ quality_baseline_fingerprint must be a SHA-256 hex digest");
+  if (!VERDICTS.has(result.verdict)) throw evaluatorError("evaluator_result_invalid", "Evaluator+ verdict must be PASS, FAIL, or INDETERMINATE");
+  if (typeof result.summary !== "string" || !result.summary.trim()) throw evaluatorError("evaluator_result_invalid", "Evaluator+ summary must be non-empty");
+  if (!Array.isArray(result.evidence_refs) || result.evidence_refs.some((ref) => typeof ref !== "string")) throw evaluatorError("evaluator_result_invalid", "Evaluator+ evidence_refs must be an array of strings");
+  if (typeof result.created_at !== "string" || !DATE_TIME.test(result.created_at) || Number.isNaN(Date.parse(result.created_at))) throw evaluatorError("evaluator_result_invalid", "Evaluator+ created_at must be an RFC 3339 date-time");
+}
+
+export function aggregateEvaluatorVerdict(criteria) {
+  if (!Array.isArray(criteria)) throw evaluatorError("evaluator_result_invalid", "Evaluator+ criteria must be an array");
+  if (criteria.some((criterion) => criterion.verdict === "FAIL")) return "FAIL";
+  if (criteria.some((criterion) => criterion.verdict === "INDETERMINATE")) return "INDETERMINATE";
+  return "PASS";
+}
+
+function validateCriterionShape(criterion) {
+  if (!criterion || typeof criterion !== "object" || Array.isArray(criterion)) throw evaluatorError("evaluator_result_invalid", "Evaluator+ criterion entries must be objects");
+  rejectUnknownProperties(criterion, new Set(["id", "scope", "verdict", "summary", "evidence_refs"]), "Evaluator+ criterion");
+  if (typeof criterion.id !== "string" || !criterion.id.trim()) throw evaluatorError("evaluator_result_invalid", "Evaluator+ criterion id must be non-empty");
+  if (criterion.scope !== "product_quality") throw evaluatorError("evaluator_result_invalid", `Evaluator+ criterion ${criterion.id} is not product_quality`);
+  if (!VERDICTS.has(criterion.verdict)) throw evaluatorError("evaluator_result_invalid", `Evaluator+ criterion ${criterion.id} has an invalid verdict`);
+  if (typeof criterion.summary !== "string" || !criterion.summary.trim()) throw evaluatorError("evaluator_result_invalid", `Evaluator+ criterion ${criterion.id} summary must be non-empty`);
+  if (!Array.isArray(criterion.evidence_refs) || criterion.evidence_refs.some((ref) => typeof ref !== "string")) throw evaluatorError("evaluator_result_invalid", `Evaluator+ criterion ${criterion.id} evidence_refs must be an array of strings`);
+}
+
+/**
+ * Validate an Evaluator+ result. Without a quality baseline the v1.7 legacy
+ * result contract remains valid. With a baseline, every product-quality
+ * criterion must be covered exactly once and the aggregate is deterministic.
+ */
+export function validateEvaluatorResult(result, { qualityBaseline = null, expectedCandidateFingerprint = null } = {}) {
+  requireBaseResult(result);
+  if (!qualityBaseline) {
+    if (result.criteria !== undefined) {
+      if (!Array.isArray(result.criteria)) throw evaluatorError("evaluator_result_invalid", "Evaluator+ criteria must be an array");
+      for (const criterion of result.criteria) validateCriterionShape(criterion);
+    }
+    return { valid: true, legacy: true, verdict: result.verdict, result };
+  }
+
+  const baseline = qualityBaseline.manifest ?? qualityBaseline;
+  const validatedBaseline = validateQualityBaselineManifest(baseline);
+  const expectedBaselineFingerprint = validatedBaseline.fingerprint;
+  if (qualityBaseline.fingerprint !== undefined && qualityBaseline.fingerprint !== expectedBaselineFingerprint) {
+    throw evaluatorError("evaluator_quality_baseline_mismatch", "loaded Quality Baseline fingerprint does not match its canonical content");
+  }
+  if (result.quality_baseline_fingerprint !== expectedBaselineFingerprint) {
+    throw evaluatorError("evaluator_quality_baseline_mismatch", "Evaluator+ result quality baseline fingerprint does not match the approved contract");
+  }
+  if (typeof expectedCandidateFingerprint !== "string" || !expectedCandidateFingerprint.trim()) {
+    throw evaluatorError("evaluator_candidate_binding_missing", "Quality Contract Evaluator+ validation requires an expected candidate fingerprint");
+  }
+  if (result.candidate_fingerprint !== expectedCandidateFingerprint) {
+    throw evaluatorError("evaluator_candidate_fingerprint_mismatch", "Evaluator+ result candidate fingerprint does not match the approved candidate");
+  }
+
+  const { product_quality: expectedCriteria, delivery_closure: deliveryCriteria } = qualityCriteriaByScope(baseline);
+  if (!Array.isArray(result.criteria)) throw evaluatorError("evaluator_result_invalid", "Quality Contract Evaluator+ result must include criteria");
+  const expectedById = new Map(expectedCriteria.map((criterion) => [criterion.id, criterion]));
+  const deliveryIds = new Set(deliveryCriteria.map((criterion) => criterion.id));
+  const seen = new Set();
+  for (const criterion of result.criteria) {
+    validateCriterionShape(criterion);
+    if (seen.has(criterion.id)) throw evaluatorError("evaluator_result_invalid", `duplicate Evaluator+ criterion: ${criterion.id}`);
+    seen.add(criterion.id);
+    if (deliveryIds.has(criterion.id)) throw evaluatorError("evaluator_result_invalid", `delivery_closure criterion was sent to Evaluator+: ${criterion.id}`);
+    if (!expectedById.has(criterion.id)) throw evaluatorError("evaluator_result_invalid", `unexpected product_quality criterion: ${criterion.id}`);
+  }
+  for (const criterion of expectedCriteria) {
+    if (!seen.has(criterion.id)) throw evaluatorError("evaluator_result_invalid", `missing product_quality criterion: ${criterion.id}`);
+  }
+  const aggregate = aggregateEvaluatorVerdict(result.criteria);
+  if (result.verdict !== aggregate) throw evaluatorError("evaluator_result_invalid", `Evaluator+ aggregate verdict must be ${aggregate}`);
+  return {
+    valid: true,
+    legacy: false,
+    verdict: aggregate,
+    quality_baseline_fingerprint: expectedBaselineFingerprint,
+    product_quality_criteria: result.criteria,
+    excluded_delivery_closure_ids: deliveryCriteria.map((criterion) => criterion.id),
+    result,
+  };
+}
+
+function validateClosureCriterion(criterion, expectedScope = "delivery_closure") {
+  if (!criterion || typeof criterion !== "object" || Array.isArray(criterion)) throw evaluatorError("delivery_closure_invalid", "delivery closure criteria must be objects");
+  const allowed = new Set(["id", "scope", "verdict", "summary", "evidence_refs"]);
+  for (const key of Object.keys(criterion)) if (!allowed.has(key)) throw evaluatorError("delivery_closure_invalid", `delivery closure criterion contains unknown property: ${key}`);
+  if (typeof criterion.id !== "string" || !criterion.id.trim()) throw evaluatorError("delivery_closure_invalid", "delivery closure criterion id must be non-empty");
+  if (criterion.scope !== expectedScope) throw evaluatorError("delivery_closure_invalid", `delivery closure criterion ${criterion.id} has the wrong scope`);
+  if (!VERDICTS.has(criterion.verdict)) throw evaluatorError("delivery_closure_invalid", `delivery closure criterion ${criterion.id} has an invalid verdict`);
+  if (typeof criterion.summary !== "string" || !criterion.summary.trim()) throw evaluatorError("delivery_closure_invalid", `delivery closure criterion ${criterion.id} summary must be non-empty`);
+  if (!Array.isArray(criterion.evidence_refs) || criterion.evidence_refs.some((ref) => typeof ref !== "string")) throw evaluatorError("delivery_closure_invalid", `delivery closure criterion ${criterion.id} evidence_refs must be an array of strings`);
+}
+
+/** Validate the separate delivery-closure criterion record. */
+export function validateDeliveryClosureCriteria(qualityBaseline, results) {
+  const baseline = qualityBaseline?.manifest ?? qualityBaseline;
+  const validatedBaseline = validateQualityBaselineManifest(baseline);
+  const expected = qualityCriteriaByScope(baseline).delivery_closure;
+  if (!Array.isArray(results)) throw evaluatorError("delivery_closure_invalid", "delivery closure results must be an array");
+  const expectedIds = new Set(expected.map((criterion) => criterion.id));
+  const seen = new Set();
+  for (const result of results) {
+    validateClosureCriterion(result);
+    if (seen.has(result.id)) throw evaluatorError("delivery_closure_invalid", `duplicate delivery closure criterion: ${result.id}`);
+    seen.add(result.id);
+    if (!expectedIds.has(result.id)) throw evaluatorError("delivery_closure_invalid", `unexpected delivery closure criterion: ${result.id}`);
+  }
+  for (const criterion of expected) {
+    if (!seen.has(criterion.id)) throw evaluatorError("delivery_closure_invalid", `missing delivery closure criterion: ${criterion.id}`);
+  }
+  const verdict = aggregateEvaluatorVerdict(results);
+  if (qualityBaseline?.fingerprint !== undefined && qualityBaseline.fingerprint !== validatedBaseline.fingerprint) {
+    throw evaluatorError("delivery_closure_invalid", "loaded Quality Baseline fingerprint does not match its canonical content");
+  }
+  return {
+    valid: true,
+    verdict,
+    can_deliver: verdict === "PASS",
+    quality_baseline_fingerprint: validatedBaseline.fingerprint,
+    criteria: results,
+  };
+}
+
+export { VERDICTS };
+
+function cliError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function parseArgs(argv) {
+  const args = { mode: null, project: process.cwd(), baseline: null, result: null, expectedCandidateFingerprint: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === "--help" || flag === "-h") {
+      process.stdout.write("Usage: node runtime/triad-evaluator-validate.mjs --mode <baseline|evaluator|delivery> --baseline <path> [--result <path>] [--project <root>] [--expected-candidate-fingerprint <sha256>]\n");
+      return null;
+    }
+    const key = {
+      "--mode": "mode",
+      "--project": "project",
+      "--baseline": "baseline",
+      "--result": "result",
+      "--expected-candidate-fingerprint": "expectedCandidateFingerprint",
+    }[flag];
+    if (!key) throw cliError("quality_contract_cli_invalid", `unknown option: ${flag}`);
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw cliError("quality_contract_cli_invalid", `${flag} requires a value`);
+    args[key] = value;
+    index += 1;
+  }
+  if (!args.mode || !["baseline", "evaluator", "delivery"].includes(args.mode)) throw cliError("quality_contract_cli_invalid", "--mode must be baseline, evaluator, or delivery");
+  if (args.mode !== "baseline" && !args.result) throw cliError("quality_contract_cli_invalid", "--result is required");
+  if ((args.mode === "baseline" || args.mode === "delivery") && !args.baseline) throw cliError("quality_contract_cli_invalid", `--baseline is required for ${args.mode} validation`);
+  return args;
+}
+
+async function readJsonFile(root, value, label) {
+  const target = path.isAbsolute(value) ? value : path.resolve(root, value);
+  let source;
+  try {
+    source = await readFile(target, "utf8");
+  } catch (error) {
+    throw cliError("quality_contract_cli_invalid", `${label} cannot be read: ${error.message}`);
+  }
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    throw cliError("quality_contract_cli_invalid", `${label} is not valid JSON: ${error.message}`);
+  }
+}
+
+/**
+ * Explicit control-plane entry point. It reloads the baseline from disk on
+ * every invocation so Evaluator+ and delivery closure cannot rely on a stale
+ * manifest/source check performed earlier in the run.
+ */
+async function runCli() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args) return;
+  const projectRoot = await realpath(args.project);
+  const qualityBaseline = args.baseline
+    ? await loadQualityBaseline(args.baseline, { projectRoot })
+    : null;
+  if (args.mode === "baseline") {
+    process.stdout.write(`${JSON.stringify({
+      valid: true,
+      mode: "baseline",
+      quality_baseline_fingerprint: qualityBaseline.fingerprint,
+      sources: qualityBaseline.sources,
+    })}\n`);
+    return;
+  }
+  if (args.mode === "evaluator") {
+    const result = await readJsonFile(projectRoot, args.result, "Evaluator+ result");
+    if (qualityBaseline && (!args.expectedCandidateFingerprint || !SHA256.test(args.expectedCandidateFingerprint))) {
+      throw cliError("evaluator_candidate_binding_missing", "Quality Contract Evaluator+ validation requires --expected-candidate-fingerprint");
+    }
+    const validated = validateEvaluatorResult(result, {
+      qualityBaseline,
+      expectedCandidateFingerprint: qualityBaseline ? args.expectedCandidateFingerprint : null,
+    });
+    process.stdout.write(`${JSON.stringify({
+      valid: true,
+      mode: "evaluator",
+      legacy: validated.legacy,
+      verdict: validated.verdict,
+      quality_baseline_fingerprint: validated.quality_baseline_fingerprint ?? null,
+      candidate_fingerprint: result.candidate_fingerprint,
+      product_quality_criteria: validated.product_quality_criteria ?? null,
+    })}\n`);
+    return;
+  }
+
+  const results = await readJsonFile(projectRoot, args.result, "delivery closure results");
+  const validated = validateDeliveryClosureCriteria(qualityBaseline, results);
+  process.stdout.write(`${JSON.stringify({
+    valid: true,
+    mode: "delivery",
+    verdict: validated.verdict,
+    can_deliver: validated.can_deliver,
+    quality_baseline_fingerprint: validated.quality_baseline_fingerprint,
+    criteria: validated.criteria,
+  })}\n`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stdout.write(`${JSON.stringify({ valid: false, error: { code: error.code ?? "quality_contract_cli_invalid", message: error.message } })}\n`);
+    process.exitCode = 2;
+  });
+}

package/runtime/triad-verify.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { writeAtomicJson } from "./lib/evidence.mjs";
 import { calculateCandidateFingerprint, collectCandidateChanges, worktreeBranch } from "./lib/fingerprint.mjs";
 import { executeGates, gateSelectionEvidence, loadTrustedGates, resolveGateSelection } from "./lib/gates.mjs";
+import { resolveQualityContract } from "./lib/quality-baseline.mjs";
 import { evaluateScopeContract, parseScopeContract } from "./lib/scope-contract.mjs";
 
 const argv = process.argv.slice(2);
@@ -24,6 +25,10 @@ function sha256(value) {
   return createHash("sha256").update(value).digest("hex");
 }
 
+function evidenceFingerprint(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/i.test(value) ? value : null;
+}
+
 async function sha256File(value) {
   return sha256(await readFile(value));
 }
@@ -65,7 +70,7 @@ async function resolveAssignment(projectRoot, trigger, explicitAssignment) {
   return { assignmentPath, assignment: JSON.parse(source), assignmentHash: sha256(source) };
 }
 
-async function buildInvalidEvidence({ runId, trigger, assignment, reason, outputPath, failureCode = "verification_context_invalid", gateSelection = null }) {
+async function buildInvalidEvidence({ runId, trigger, assignment, reason, outputPath, failureCode = "verification_context_invalid", gateSelection = null, qualityBaselineFingerprint = null }) {
   const evidence = {
     schema_version: 1,
     run_id: runId,
@@ -77,6 +82,7 @@ async function buildInvalidEvidence({ runId, trigger, assignment, reason, output
     baseline: {
       prd_sha256: assignment?.expected_prd_sha256 ?? null,
       card_sha256: assignment?.expected_card_sha256 ?? null,
+      quality_baseline_fingerprint: evidenceFingerprint(qualityBaselineFingerprint ?? assignment?.expected_quality_baseline_fingerprint),
       git_head: null,
       candidate_fingerprint: null,
     },
@@ -147,6 +153,7 @@ async function main() {
   let assignmentPath;
   let outputPath;
   let gateSelection = null;
+  let qualityBaseline = null;
   try {
     let assignmentHash;
     ({ assignmentPath, assignment, assignmentHash } = await resolveAssignment(projectRoot, trigger, option("--assignment")));
@@ -166,6 +173,10 @@ async function main() {
     const cardPath = path.resolve(projectRoot, assignment.card_path);
     await access(prdPath);
     await access(cardPath);
+    // Resolve the optional immutable Quality Contract before any baseline or
+    // expensive-gate check so a bound source drift keeps its precise failure
+    // classification (including when the source is the PRD itself).
+    qualityBaseline = await resolveQualityContract(assignment, projectRoot);
     if ((await sha256File(prdPath)) !== assignment.expected_prd_sha256) throw new Error("PRD baseline hash mismatch");
     if ((await sha256File(cardPath)) !== assignment.expected_card_sha256) throw new Error("feature card hash mismatch");
     const repositorySkills = await validateRepositorySkills(assignment.required_repository_skills, worktree);
@@ -203,6 +214,7 @@ async function main() {
         baseline: {
           prd_sha256: assignment.expected_prd_sha256,
           card_sha256: assignment.expected_card_sha256,
+          quality_baseline_fingerprint: qualityBaseline?.fingerprint ?? null,
           gates_sha256: null,
           git_head: before.git_head,
           candidate_fingerprint: before.value,
@@ -237,9 +249,10 @@ async function main() {
       trigger,
       assignment_ref: path.relative(projectRoot, assignmentPath),
       baseline: {
-        prd_sha256: assignment.expected_prd_sha256,
-        card_sha256: assignment.expected_card_sha256,
-        gates_sha256: trusted.actualHash,
+          prd_sha256: assignment.expected_prd_sha256,
+          card_sha256: assignment.expected_card_sha256,
+          quality_baseline_fingerprint: qualityBaseline?.fingerprint ?? null,
+          gates_sha256: trusted.actualHash,
         git_head: before.git_head,
         candidate_fingerprint: before.value,
         branch,
@@ -269,7 +282,8 @@ async function main() {
       reason: error.message,
       outputPath,
       failureCode: error.code ?? "verification_context_invalid",
-      gateSelection
+      gateSelection,
+      qualityBaselineFingerprint: qualityBaseline?.fingerprint ?? null
     });
     process.stdout.write(`${JSON.stringify({ run_id: runId, status: evidence.status, evidence: outputPath ?? null })}\n`);
     process.exitCode = 3;

package/schemas/evaluator-plus-result.schema.json

@@ -8,9 +8,25 @@
     "schema_version": { "const": 1 },
     "feature_id": { "type": "string", "minLength": 1 },
     "candidate_fingerprint": { "type": "string", "minLength": 1 },
+    "quality_baseline_fingerprint": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" },
     "verdict": { "enum": ["PASS", "FAIL", "INDETERMINATE"] },
     "summary": { "type": "string", "minLength": 1 },
     "evidence_refs": { "type": "array", "items": { "type": "string" } },
+    "criteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "scope", "verdict", "summary", "evidence_refs"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "scope": { "const": "product_quality" },
+          "verdict": { "enum": ["PASS", "FAIL", "INDETERMINATE"] },
+          "summary": { "type": "string", "minLength": 1 },
+          "evidence_refs": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": false
+      }
+    },
     "created_at": { "type": "string", "format": "date-time" }
   },
   "additionalProperties": false

package/schemas/quality-baseline.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://triad.engineering/schemas/quality-baseline.schema.json",
+  "title": "Triad immutable Quality Baseline",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "revision", "sources", "criteria", "fingerprint"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "revision": { "type": "integer", "minimum": 1 },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "role", "path", "sha256"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "role": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1, "pattern": "^(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+" },
+          "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
+        }
+      }
+    },
+    "criteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "scope", "requirement"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "scope": { "enum": ["product_quality", "delivery_closure"] },
+          "requirement": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "fingerprint": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
+  }
+}

package/schemas/verification-evidence.schema.json

@@ -12,7 +12,7 @@
     "assignment_id": { "type": ["string", "null"] },
     "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"] } } },
+    "baseline": { "type": "object", "required": ["prd_sha256", "card_sha256", "git_head", "candidate_fingerprint"], "properties": { "prd_sha256": { "type": ["string", "null"] }, "card_sha256": { "type": ["string", "null"] }, "quality_baseline_fingerprint": { "type": ["string", "null"], "pattern": "^[a-fA-F0-9]{64}$" }, "git_head": { "type": ["string", "null"] }, "candidate_fingerprint": { "type": ["string", "null"] }, "branch": { "type": ["string", "null"] } } },
     "scope": {
       "type": "object",
       "properties": {

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

@@ -20,6 +20,14 @@ conditions, runnable quality gates, practical-test need, and integration need.
    snapshot, revision when available, and SHA-256.
 4. Copy `assets/loop-template/` to `.loop/`, then create bounded feature cards
    under `features/` and a complete `feature-plan.md`.
+   When an owner-approved Quality Bar or additional intent/architecture source
+   exists, copy `assets/loop-template/quality-baseline.json`, fill only the
+   declared source hashes and criteria, compute its canonical fingerprint, and
+   bind `project.quality_contract.baseline` plus `fingerprint`. Use
+   `criteria: []` when no machine-readable Quality Bar was supplied; never
+   invent criteria. The manifest is immutable for the run and a requirement
+   change creates a new revision/rebaseline event rather than editing it in
+   place.
 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.