trackops 2.0.6 → 2.2.0

package/lib/quality.js

@@ -0,0 +1,1759 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const config = require("./config");
+const controlLib = require("./control");
+const env = require("./env");
+const { t, setLocale } = require("./i18n");
+const { PHASE_DOD } = require("./opera-phase-dod");
+
+const STALE_TASK_MS = 24 * 60 * 60 * 1000;
+const BLOCKING_SEVERITIES = new Set(["critical", "high"]);
+const QUALITY_STATUS_VALUES = new Set([
+  "pass",
+  "fail",
+  "warn",
+  "skip",
+  "passed",
+  "failed",
+  "skipped",
+  "not_configured",
+  "ready",
+  "blocked",
+  "attention",
+  "unknown",
+]);
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch (_error) {
+    return false;
+  }
+}
+
+function readText(filePath, fallback = "") {
+  if (!fileExists(filePath)) return fallback;
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function readJson(filePath, fallback = null) {
+  if (!fileExists(filePath)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_error) {
+    return fallback;
+  }
+}
+
+function writeJson(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+function normalizePath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function hasText(value) {
+  return Boolean(String(value || "").trim());
+}
+
+function hasOwn(object, key) {
+  return Boolean(object) && Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function normalizeString(value) {
+  return hasText(value) ? String(value).trim() : null;
+}
+
+function normalizeStringList(values) {
+  return Array.isArray(values)
+    ? values.map((value) => String(value || "").trim()).filter(Boolean)
+    : [];
+}
+
+function ensureQualityStorage(context) {
+  fs.mkdirSync(context.paths.qualityDir, { recursive: true });
+  fs.mkdirSync(context.paths.qualityRunsDir, { recursive: true });
+}
+
+function formatQualityStatus(value) {
+  const normalized = String(value || "unknown").trim().toLowerCase();
+  return QUALITY_STATUS_VALUES.has(normalized) ? t(`quality.status.${normalized}`) : normalized || t("quality.status.unknown");
+}
+
+function formatScopeLabel(scope) {
+  const normalized = String(scope || "").trim().toLowerCase();
+  return t(`quality.scope.${normalized}`) || normalized || t("quality.value.unknown");
+}
+
+function normalizeIntakeSection(intake) {
+  if (!intake || typeof intake !== "object") return {};
+  return {
+    ...intake,
+    externalServices: normalizeStringList(intake.externalServices),
+    behaviorRules: normalizeStringList(intake.behaviorRules),
+    architecturalInvariants: normalizeStringList(intake.architecturalInvariants),
+    pipeline: normalizeStringList(intake.pipeline),
+    templates: normalizeStringList(intake.templates),
+    versionControl: intake.versionControl && typeof intake.versionControl === "object"
+      ? {
+          remote: hasOwn(intake.versionControl, "remote") ? intake.versionControl.remote === true : false,
+          provider: normalizeString(intake.versionControl.provider),
+          developmentBranch: normalizeString(intake.versionControl.developmentBranch),
+          releaseBranch: normalizeString(intake.versionControl.releaseBranch),
+        }
+      : null,
+    deployment: intake.deployment && typeof intake.deployment === "object"
+      ? {
+          mode: normalizeString(intake.deployment.mode),
+          target: normalizeString(intake.deployment.target),
+          smokeCommand: normalizeString(intake.deployment.smokeCommand),
+        }
+      : null,
+  };
+}
+
+function loadContract(context) {
+  const raw = readText(context.paths.contractFile, "");
+  if (!raw.trim()) return { exists: false, valid: false, data: null };
+  try {
+    return { exists: true, valid: true, data: JSON.parse(raw) };
+  } catch (error) {
+    return { exists: true, valid: false, data: null, error: error.message };
+  }
+}
+
+function loadPolicy(context) {
+  const raw = readText(context.paths.autonomyPolicyFile, "");
+  if (!raw.trim()) return { exists: false, valid: false, data: null };
+  try {
+    return { exists: true, valid: true, data: JSON.parse(raw) };
+  } catch (error) {
+    return { exists: true, valid: false, data: null, error: error.message };
+  }
+}
+
+function parsePackageScripts(context) {
+  const pkg = readJson(context.packageFile, null);
+  const scripts = pkg && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  return {
+    packageJson: pkg,
+    packageDir: context.layout === "split" ? context.appRoot : context.workspaceRoot,
+    scripts,
+  };
+}
+
+function buildCommandSignature(commands) {
+  return (commands || [])
+    .map((item) => `${normalizePath(item.cwd || "")}::${String(item.command || "").trim()}`)
+    .join("|");
+}
+
+function latestVerificationSummary(context) {
+  const raw = readJson(context.paths.qualityLatestFile, {});
+  const normalizedRuns = {};
+  const sourceRuns = raw?.verification?.runs && typeof raw.verification.runs === "object"
+    ? raw.verification.runs
+    : {};
+
+  for (const [scope, run] of Object.entries(sourceRuns)) {
+    if (!run || typeof run !== "object") continue;
+    const commands = Array.isArray(run.commands)
+      ? run.commands
+          .map((entry) => ({
+            command: normalizeString(entry?.command),
+            cwd: normalizeString(entry?.cwd),
+          }))
+          .filter((entry) => entry.command)
+      : normalizeString(run.command)
+        ? [{ command: normalizeString(run.command), cwd: normalizeString(run.cwd) }]
+        : [];
+    normalizedRuns[scope] = {
+      status: String(run.status || "unknown").trim() || "unknown",
+      commands,
+      commandSignature: normalizeString(run.commandSignature) || buildCommandSignature(commands),
+      startedAt: normalizeString(run.startedAt),
+      finishedAt: normalizeString(run.finishedAt),
+      exitCode: Number.isFinite(Number(run.exitCode)) ? Number(run.exitCode) : null,
+      note: normalizeString(run.note) || "",
+      commit: normalizeString(run.commit),
+      scope,
+    };
+  }
+
+  return {
+    generatedAt: normalizeString(raw.generatedAt),
+    lastVerificationAt: normalizeString(raw.lastVerificationAt),
+    verification: { runs: normalizedRuns },
+  };
+}
+
+function getGitCommit(context) {
+  const result = spawnSync("git", ["rev-parse", "HEAD"], {
+    cwd: context.workspaceRoot,
+    encoding: "utf8",
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function gitText(args, cwd) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  return result.status === 0 ? result.stdout.trim() : "";
+}
+
+function getGitRemoteUrl(context) {
+  return gitText(["remote", "get-url", "origin"], context.workspaceRoot) || null;
+}
+
+function getGitBranches(context) {
+  const output = gitText(["branch", "--format=%(refname:short)"], context.workspaceRoot);
+  return output.split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean);
+}
+
+function inferProvider(remoteUrl) {
+  const value = String(remoteUrl || "").trim().toLowerCase();
+  if (!value) return null;
+  if (value.includes("github.com")) return "github";
+  if (value.includes("gitlab.com")) return "gitlab";
+  if (value.includes("bitbucket.org")) return "bitbucket";
+  return null;
+}
+
+function inferDevelopmentBranch(repo, branches) {
+  if (branches.includes("develop")) return "develop";
+  if (repo.branch && repo.branch !== "master" && repo.branch !== "main") return repo.branch;
+  if (branches.includes("main")) return "main";
+  if (branches.includes("master")) return "master";
+  return repo.branch || null;
+}
+
+function inferReleaseBranch(branches) {
+  if (branches.includes("master")) return "master";
+  if (branches.includes("main")) return "main";
+  return null;
+}
+
+function inferVersionControlMetadata(context, repo) {
+  if (!repo.available) return null;
+  const remoteUrl = getGitRemoteUrl(context);
+  const branches = getGitBranches(context);
+  const hasRemoteSignal = Boolean(remoteUrl || repo.hasUpstream);
+  if (!hasRemoteSignal && !branches.length) return null;
+  return {
+    remote: hasRemoteSignal,
+    provider: inferProvider(remoteUrl),
+    developmentBranch: inferDevelopmentBranch(repo, branches),
+    releaseBranch: inferReleaseBranch(branches),
+  };
+}
+
+function inferDeploymentMetadata(controlState, pkgInfo) {
+  const metaQuality = config.normalizeQualityMeta(controlState.meta?.quality);
+  const scripts = pkgInfo.scripts || {};
+  const smokeCommand = normalizeString(metaQuality.verification.smokeCommands[0])
+    || normalizeString(scripts.smoke ? "npm run smoke" : null)
+    || normalizeString(scripts["release:check"] ? "npm run release:check" : null);
+  if (!smokeCommand) return null;
+  return {
+    mode: "manual",
+    target: null,
+    smokeCommand,
+  };
+}
+
+function resolveVersionControlSection(explicitSection, fallbackSection, inferredSection) {
+  const source = explicitSection ? "intake" : fallbackSection ? "bootstrap" : inferredSection ? "inferred" : null;
+  if (!source) return { value: null, source: null, inferred: false };
+  const value = {
+    remote: hasOwn(explicitSection, "remote")
+      ? explicitSection.remote === true
+      : hasOwn(fallbackSection, "remote")
+        ? fallbackSection.remote === true
+        : inferredSection?.remote === true,
+    provider: normalizeString(explicitSection?.provider)
+      || normalizeString(fallbackSection?.provider)
+      || normalizeString(inferredSection?.provider),
+    developmentBranch: normalizeString(explicitSection?.developmentBranch)
+      || normalizeString(fallbackSection?.developmentBranch)
+      || normalizeString(inferredSection?.developmentBranch),
+    releaseBranch: normalizeString(explicitSection?.releaseBranch)
+      || normalizeString(fallbackSection?.releaseBranch)
+      || normalizeString(inferredSection?.releaseBranch),
+  };
+  return { value, source, inferred: source === "inferred" };
+}
+
+function resolveDeploymentSection(explicitSection, fallbackSection, inferredSection) {
+  const source = explicitSection ? "intake" : fallbackSection ? "bootstrap" : inferredSection ? "inferred" : null;
+  if (!source) return { value: null, source: null, inferred: false };
+  const value = {
+    mode: normalizeString(explicitSection?.mode)
+      || normalizeString(fallbackSection?.mode)
+      || normalizeString(inferredSection?.mode),
+    target: normalizeString(explicitSection?.target)
+      || normalizeString(fallbackSection?.target)
+      || normalizeString(inferredSection?.target),
+    smokeCommand: normalizeString(explicitSection?.smokeCommand)
+      || normalizeString(fallbackSection?.smokeCommand)
+      || normalizeString(inferredSection?.smokeCommand),
+  };
+  if (!value.mode && !value.target && !value.smokeCommand) {
+    return { value: null, source: null, inferred: false };
+  }
+  return { value, source, inferred: source === "inferred" };
+}
+
+function buildBootstrapMetadataBackfill(contextOrRoot, controlState, options = {}) {
+  const context = config.ensureContext(contextOrRoot);
+  const control = controlState || config.loadControl(context);
+  const repo = options.repo || controlLib.getRepoSnapshot(context);
+  const pkgInfo = options.pkgInfo || parsePackageScripts(context);
+  const bootstrapState = control.meta?.opera?.bootstrap || {};
+  const discovery = normalizeIntakeSection(bootstrapState.discovery || {});
+  const rawIntake = normalizeIntakeSection(readJson(path.join(context.paths.bootstrapDir, "intake.json"), null));
+  const explicitVersionControl = rawIntake.versionControl || null;
+  const explicitDeployment = rawIntake.deployment || null;
+  const fallbackVersionControl = discovery.versionControl || null;
+  const fallbackDeployment = discovery.deployment || null;
+  const inferredVersionControl = inferVersionControlMetadata(context, repo);
+  const inferredDeployment = inferDeploymentMetadata(control, pkgInfo);
+  const versionControl = resolveVersionControlSection(explicitVersionControl, fallbackVersionControl, inferredVersionControl);
+  const deployment = resolveDeploymentSection(explicitDeployment, fallbackDeployment, inferredDeployment);
+  const intake = normalizeIntakeSection({
+    ...discovery,
+    ...(rawIntake || {}),
+    versionControl: versionControl.value,
+    deployment: deployment.value,
+  });
+
+  return {
+    rawIntake: rawIntake || {},
+    discovery,
+    intake,
+    inferred: {
+      versionControl: inferredVersionControl,
+      deployment: inferredDeployment,
+    },
+    sources: {
+      versionControl: versionControl.source,
+      deployment: deployment.source,
+    },
+    changed: versionControl.inferred || deployment.inferred,
+  };
+}
+
+function backfillBootstrapMetadata(contextOrRoot, controlState, options = {}) {
+  const context = config.ensureContext(contextOrRoot);
+  const control = controlState || config.loadControl(context);
+  const hasBootstrapState = Boolean(control.meta?.opera?.bootstrap);
+  if (!hasBootstrapState) {
+    return { changed: false, intake: null, sources: { versionControl: null, deployment: null } };
+  }
+
+  const backfill = buildBootstrapMetadataBackfill(context, control, options);
+  const nextDiscovery = normalizeIntakeSection({
+    ...(control.meta.opera.bootstrap.discovery || {}),
+    versionControl: backfill.intake.versionControl,
+    deployment: backfill.intake.deployment,
+  });
+
+  const discoveryChanged = JSON.stringify(nextDiscovery.versionControl || null) !== JSON.stringify(control.meta.opera.bootstrap.discovery?.versionControl || null)
+    || JSON.stringify(nextDiscovery.deployment || null) !== JSON.stringify(control.meta.opera.bootstrap.discovery?.deployment || null);
+
+  if (discoveryChanged) {
+    control.meta.opera.bootstrap = {
+      ...control.meta.opera.bootstrap,
+      discovery: {
+        ...(control.meta.opera.bootstrap.discovery || {}),
+        versionControl: nextDiscovery.versionControl,
+        deployment: nextDiscovery.deployment,
+      },
+    };
+  }
+
+  const intakePath = path.join(context.paths.bootstrapDir, "intake.json");
+  const shouldWriteIntake = options.persist === true && (fileExists(intakePath) || Object.keys(backfill.rawIntake).length > 0 || Object.keys(backfill.discovery).length > 0);
+  let intakeChanged = false;
+  if (shouldWriteIntake) {
+    const nextIntake = normalizeIntakeSection({
+      ...backfill.rawIntake,
+      versionControl: backfill.intake.versionControl,
+      deployment: backfill.intake.deployment,
+    });
+    const currentSerialized = JSON.stringify(normalizeIntakeSection(readJson(intakePath, {})));
+    const nextSerialized = JSON.stringify(nextIntake);
+    if (currentSerialized !== nextSerialized) {
+      writeJson(intakePath, nextIntake);
+      intakeChanged = true;
+    }
+  }
+
+  return {
+    changed: discoveryChanged || intakeChanged,
+    intake: backfill.intake,
+    sources: backfill.sources,
+  };
+}
+
+function loadBootstrapArtifacts(context, controlState, options = {}) {
+  const backfill = buildBootstrapMetadataBackfill(context, controlState, options);
+  const specPath = path.join(context.paths.bootstrapDir, "spec-dossier.md");
+  const openQuestionsPath = path.join(context.paths.bootstrapDir, "open-questions.md");
+  const qualityReportPath = path.join(context.paths.bootstrapDir, "quality-report.json");
+  const intakePath = path.join(context.paths.bootstrapDir, "intake.json");
+  return {
+    intake: backfill.intake,
+    rawIntake: backfill.rawIntake,
+    discovery: backfill.discovery,
+    inferred: backfill.inferred,
+    sources: backfill.sources,
+    intakeExists: fileExists(intakePath),
+    specExists: fileExists(specPath),
+    specText: readText(specPath, "").trim(),
+    qualityReport: readJson(qualityReportPath, null),
+    openQuestions: readText(openQuestionsPath, "").trim(),
+    genesisExists: fileExists(context.paths.genesisFile),
+    paths: {
+      intake: normalizePath(intakePath),
+      specDossier: normalizePath(specPath),
+      openQuestions: normalizePath(openQuestionsPath),
+      qualityReport: normalizePath(qualityReportPath),
+    },
+  };
+}
+
+function detectProfiles(context, contract, intake, envState, pkgInfo, verificationConfig) {
+  const profiles = new Set(["baseline"]);
+  if (pkgInfo.packageJson) profiles.add("node-runtime");
+  if ((contract?.data?.system?.externalServices || []).length || (envState.requiredKeys || []).length) {
+    profiles.add("external-services");
+  }
+  if (context.layout === "split" || pkgInfo.packageJson?.version) {
+    profiles.add("publishable-release");
+  }
+  if (
+    intake?.deployment?.mode ||
+    intake?.deployment?.target ||
+    intake?.deployment?.smokeCommand ||
+    verificationConfig.smokeCommands.length
+  ) {
+    profiles.add("deployable-app");
+  }
+  return [...profiles];
+}
+
+function inferVerificationConfig(context, controlState, intake, pkgInfo) {
+  const metaQuality = config.normalizeQualityMeta(controlState.meta?.quality);
+  const fromMeta = metaQuality.verification || {};
+  const scripts = pkgInfo.scripts || {};
+  const packageDir = pkgInfo.packageDir || context.workspaceRoot;
+  const deploymentSmokeCommand = normalizeString(intake?.deployment?.smokeCommand);
+  const deploymentSmokeCwd = deploymentSmokeCommand && pkgInfo.packageJson
+    && /^npm(?:\.cmd)?\s+run\s+/i.test(deploymentSmokeCommand)
+    ? packageDir
+    : context.workspaceRoot;
+
+  const testCommands = fromMeta.testCommands.length
+    ? fromMeta.testCommands.map((command) => ({ command, cwd: packageDir }))
+    : scripts.test
+      ? [{ command: "npm test", cwd: packageDir }]
+      : [];
+  const buildCommands = fromMeta.buildCommands.length
+    ? fromMeta.buildCommands.map((command) => ({ command, cwd: packageDir }))
+    : scripts.build
+      ? [{ command: "npm run build", cwd: packageDir }]
+      : [];
+  const smokeCommands = fromMeta.smokeCommands.length
+    ? fromMeta.smokeCommands.map((command) => ({ command, cwd: packageDir }))
+    : deploymentSmokeCommand
+      ? [{ command: deploymentSmokeCommand, cwd: deploymentSmokeCwd }]
+      : scripts.smoke
+        ? [{ command: "npm run smoke", cwd: packageDir }]
+        : scripts["release:check"]
+          ? [{ command: "npm run release:check", cwd: packageDir }]
+          : [];
+
+  return {
+    reviewRequired: fromMeta.reviewRequired === true,
+    testCommands,
+    buildCommands,
+    smokeCommands,
+  };
+}
+
+function getBridgeSyncStatus(context) {
+  if (context.layout !== "split" || context.env.bridgeMode === "none") {
+    return { applicable: false, ok: true, missing: false, mismatchedKeys: [] };
+  }
+  if (!fileExists(context.env.appBridgeFile)) {
+    return { applicable: true, ok: false, missing: true, mismatchedKeys: [] };
+  }
+  const rootEntries = env.parseEnv(readText(context.env.rootFile, ""));
+  const bridgeEntries = env.parseEnv(readText(context.env.appBridgeFile, ""));
+  const keys = new Set([...Object.keys(rootEntries), ...Object.keys(bridgeEntries)]);
+  const mismatchedKeys = [...keys].filter((key) => String(rootEntries[key] || "") !== String(bridgeEntries[key] || ""));
+  return {
+    applicable: true,
+    ok: mismatchedKeys.length === 0,
+    missing: false,
+    mismatchedKeys,
+  };
+}
+
+function getTaskActivityMs(task, controlState) {
+  const timestamps = [];
+  if (task.execution?.updatedAt) timestamps.push(Date.parse(task.execution.updatedAt));
+  for (const entry of Array.isArray(task.history) ? task.history : []) {
+    if (entry?.at) timestamps.push(Date.parse(entry.at));
+  }
+  for (const entry of Array.isArray(controlState.timeEntries) ? controlState.timeEntries : []) {
+    if (entry?.taskId !== task.id) continue;
+    if (entry.startedAt) timestamps.push(Date.parse(entry.startedAt));
+    if (entry.stoppedAt) timestamps.push(Date.parse(entry.stoppedAt));
+  }
+  const valid = timestamps.filter((value) => Number.isFinite(value));
+  return valid.length ? Math.max(...valid) : null;
+}
+
+function normalizeFindingSeverity(finding) {
+  const value = String(finding?.severity || finding?.priority || "").trim().toLowerCase();
+  if (["critical", "high", "medium", "low"].includes(value)) return value;
+  if (value === "p0") return "critical";
+  if (value === "p1") return "high";
+  if (value === "p2") return "medium";
+  if (value === "p3") return "low";
+  return "medium";
+}
+
+function makeProbe(overrides) {
+  return {
+    id: overrides.id,
+    domain: overrides.domain,
+    severity: overrides.severity || "medium",
+    gates: Array.isArray(overrides.gates) ? overrides.gates : [],
+    phaseRelevance: Array.isArray(overrides.phaseRelevance) ? overrides.phaseRelevance : [],
+    status: overrides.status || "pass",
+    title: overrides.title || overrides.id,
+    message: overrides.message || "",
+    recommendation: overrides.recommendation || "",
+    evidence: overrides.evidence || {},
+  };
+}
+
+function summarizeProbes(probes) {
+  const counts = { pass: 0, fail: 0, skip: 0 };
+  const byDomain = {};
+  const failures = [];
+  for (const probe of probes) {
+    counts[probe.status] = (counts[probe.status] || 0) + 1;
+    byDomain[probe.domain] = byDomain[probe.domain] || { pass: 0, fail: 0, skip: 0 };
+    byDomain[probe.domain][probe.status] += 1;
+    if (probe.status === "fail") failures.push(probe);
+  }
+  const overallStatus = failures.some((probe) => BLOCKING_SEVERITIES.has(probe.severity))
+    ? "fail"
+    : failures.length
+      ? "warn"
+      : "pass";
+  return {
+    overallStatus,
+    counts,
+    byDomain,
+    failingIds: failures.map((probe) => probe.id),
+    failingHighSeverity: failures.filter((probe) => BLOCKING_SEVERITIES.has(probe.severity)).map((probe) => probe.id),
+  };
+}
+
+function probeTitle(id) {
+  return t(`quality.probe.${id}.title`);
+}
+
+function probeRecommendation(id) {
+  return t(`quality.probe.${id}.recommendation`);
+}
+
+function buildProbes(state) {
+  const probes = [];
+  const intake = state.bootstrapArtifacts.intake || {};
+  const bridgeSync = getBridgeSyncStatus(state.context);
+  const criticalFindings = (state.derived.openFindings || []).filter((finding) => normalizeFindingSeverity(finding) === "critical");
+  const highFindings = (state.derived.openFindings || []).filter((finding) => normalizeFindingSeverity(finding) === "high");
+  const blockedWithoutNote = (state.derived.blockers || []).filter((task) => !hasText(task.blocker));
+  const requiredWithoutAcceptance = (state.derived.actionableTasks || []).filter(
+    (task) => task.required !== false && (!Array.isArray(task.acceptance) || task.acceptance.length === 0),
+  );
+  const staleInProgress = (state.derived.activeTasks || []).filter((task) => {
+    const lastActivity = getTaskActivityMs(task, state.control);
+    return Number.isFinite(lastActivity) && (Date.now() - lastActivity) > STALE_TASK_MS;
+  });
+  const contractIntentMissing = state.contract.valid
+    ? ["problemStatement", "targetUser", "singularDesiredOutcome", "deliveryTarget"]
+        .filter((key) => !hasText(state.contract.data?.intent?.[key]))
+    : [];
+  const verificationConfigured = state.verificationConfig.testCommands.length
+    || state.verificationConfig.buildCommands.length
+    || state.verificationConfig.smokeCommands.length
+    || state.verificationConfig.reviewRequired;
+
+  probes.push(makeProbe({
+    id: "bootstrap.complete",
+    domain: "bootstrap",
+    severity: "high",
+    gates: ["phase", "release", "promotion"],
+    phaseRelevance: ["O", "P", "A"],
+    status: !state.hasOpera ? "skip" : String(state.control.meta?.opera?.bootstrap?.status || "").trim() === "completed" ? "pass" : "fail",
+    title: probeTitle("bootstrap.complete"),
+    message: !state.hasOpera
+      ? t("quality.message.notApplicable", { subject: probeTitle("bootstrap.complete") })
+      : String(state.control.meta?.opera?.bootstrap?.status || "").trim() === "completed"
+        ? t("quality.message.ok", { subject: probeTitle("bootstrap.complete") })
+        : t("quality.message.failDetail", {
+            subject: probeTitle("bootstrap.complete"),
+            detail: String(state.control.meta?.opera?.bootstrap?.status || t("quality.value.unknown")),
+          }),
+    recommendation: probeRecommendation("bootstrap.complete"),
+    evidence: { status: state.control.meta?.opera?.bootstrap?.status || null },
+  }));
+
+  probes.push(makeProbe({
+    id: "contract.exists",
+    domain: "contract",
+    severity: "high",
+    gates: ["phase", "release", "promotion"],
+    phaseRelevance: ["O", "R", "A"],
+    status: !state.hasOpera ? "skip" : state.contract.exists ? "pass" : "fail",
+    title: probeTitle("contract.exists"),
+    message: !state.hasOpera
+      ? t("quality.message.notApplicable", { subject: probeTitle("contract.exists") })
+      : state.contract.exists
+        ? t("quality.message.ok", { subject: probeTitle("contract.exists") })
+        : t("quality.message.fileMissing", { subject: probeTitle("contract.exists"), path: normalizePath(state.context.paths.contractFile) }),
+    recommendation: probeRecommendation("contract.exists"),
+    evidence: { path: normalizePath(state.context.paths.contractFile) },
+  }));
+
+  probes.push(makeProbe({
+    id: "contract.valid-json",
+    domain: "contract",
+    severity: "critical",
+    gates: ["phase", "release", "promotion"],
+    phaseRelevance: ["O", "R", "A"],
+    status: !state.contract.exists ? "skip" : state.contract.valid ? "pass" : "fail",
+    title: probeTitle("contract.valid-json"),
+    message: !state.contract.exists
+      ? t("quality.message.notApplicable", { subject: probeTitle("contract.valid-json") })
+      : state.contract.valid
+        ? t("quality.message.ok", { subject: probeTitle("contract.valid-json") })
+        : t("quality.message.failDetail", { subject: probeTitle("contract.valid-json"), detail: state.contract.error || t("quality.value.unknown") }),
+    recommendation: probeRecommendation("contract.valid-json"),
+    evidence: { error: state.contract.error || null },
+  }));
+
+  probes.push(makeProbe({
+    id: "contract.intent-complete",
+    domain: "contract",
+    severity: "high",
+    gates: ["phase", "release"],
+    phaseRelevance: ["O", "R"],
+    status: !state.contract.valid ? "skip" : contractIntentMissing.length ? "fail" : "pass",
+    title: probeTitle("contract.intent-complete"),
+    message: !state.contract.valid
+      ? t("quality.message.notApplicable", { subject: probeTitle("contract.intent-complete") })
+      : contractIntentMissing.length
+        ? t("quality.message.missingItems", { subject: probeTitle("contract.intent-complete"), items: contractIntentMissing.join(", ") })
+        : t("quality.message.ok", { subject: probeTitle("contract.intent-complete") }),
+    recommendation: probeRecommendation("contract.intent-complete"),
+    evidence: { missingFields: contractIntentMissing },
+  }));
+
+  probes.push(makeProbe({
+    id: "policy.exists",
+    domain: "policy",
+    severity: "high",
+    gates: ["phase", "release", "promotion"],
+    phaseRelevance: ["P", "A"],
+    status: !state.hasOpera ? "skip" : state.policy.exists ? "pass" : "fail",
+    title: probeTitle("policy.exists"),
+    message: !state.hasOpera
+      ? t("quality.message.notApplicable", { subject: probeTitle("policy.exists") })
+      : state.policy.exists
+        ? t("quality.message.ok", { subject: probeTitle("policy.exists") })
+        : t("quality.message.fileMissing", { subject: probeTitle("policy.exists"), path: normalizePath(state.context.paths.autonomyPolicyFile) }),
+    recommendation: probeRecommendation("policy.exists"),
+    evidence: { path: normalizePath(state.context.paths.autonomyPolicyFile) },
+  }));
+
+  probes.push(makeProbe({
+    id: "policy.valid-json",
+    domain: "policy",
+    severity: "critical",
+    gates: ["phase", "release", "promotion"],
+    phaseRelevance: ["P", "A"],
+    status: !state.policy.exists ? "skip" : state.policy.valid ? "pass" : "fail",
+    title: probeTitle("policy.valid-json"),
+    message: !state.policy.exists
+      ? t("quality.message.notApplicable", { subject: probeTitle("policy.valid-json") })
+      : state.policy.valid
+        ? t("quality.message.ok", { subject: probeTitle("policy.valid-json") })
+        : t("quality.message.failDetail", { subject: probeTitle("policy.valid-json"), detail: state.policy.error || t("quality.value.unknown") }),
+    recommendation: probeRecommendation("policy.valid-json"),
+    evidence: { error: state.policy.error || null },
+  }));
+
+  probes.push(makeProbe({
+    id: "docs.drift",
+    domain: "docs",
+    severity: "medium",
+    gates: ["phase", "release"],
+    phaseRelevance: ["R", "A"],
+    status: state.drift.length ? "fail" : "pass",
+    title: probeTitle("docs.drift"),
+    message: state.drift.length
+      ? t("quality.message.outOfSync", { subject: probeTitle("docs.drift"), detail: state.drift.join(", ") })
+      : t("quality.message.ok", { subject: probeTitle("docs.drift") }),
+    recommendation: probeRecommendation("docs.drift"),
+    evidence: { drift: state.drift },
+  }));
+
+  probes.push(makeProbe({
+    id: "docs.genesis-exists",
+    domain: "docs",
+    severity: "low",
+    gates: ["phase"],
+    phaseRelevance: ["O", "R"],
+    status: !state.hasOpera ? "skip" : state.bootstrapArtifacts.genesisExists ? "pass" : "fail",
+    title: probeTitle("docs.genesis-exists"),
+    message: !state.hasOpera
+      ? t("quality.message.notApplicable", { subject: probeTitle("docs.genesis-exists") })
+      : state.bootstrapArtifacts.genesisExists
+        ? t("quality.message.ok", { subject: probeTitle("docs.genesis-exists") })
+        : t("quality.message.fileMissing", { subject: probeTitle("docs.genesis-exists"), path: normalizePath(state.context.paths.genesisFile) }),
+    recommendation: probeRecommendation("docs.genesis-exists"),
+    evidence: { path: normalizePath(state.context.paths.genesisFile) },
+  }));
+
+  probes.push(makeProbe({
+    id: "env.missing-keys",
+    domain: "env",
+    severity: "high",
+    gates: ["phase", "release", "promotion"],
+    phaseRelevance: ["P", "A"],
+    status: state.envState.missingKeys.length ? "fail" : "pass",
+    title: probeTitle("env.missing-keys"),
+    message: state.envState.missingKeys.length
+      ? t("quality.message.missingItems", { subject: probeTitle("env.missing-keys"), items: state.envState.missingKeys.join(", ") })
+      : t("quality.message.ok", { subject: probeTitle("env.missing-keys") }),
+    recommendation: probeRecommendation("env.missing-keys"),
+    evidence: { missingKeys: state.envState.missingKeys },
+  }));
+
+  probes.push(makeProbe({
+    id: "env.bridge-sync",
+    domain: "env",
+    severity: "medium",
+    gates: ["phase", "release"],
+    phaseRelevance: ["P", "A"],
+    status: !bridgeSync.applicable ? "skip" : bridgeSync.ok ? "pass" : "fail",
+    title: probeTitle("env.bridge-sync"),
+    message: !bridgeSync.applicable
+      ? t("quality.message.notApplicable", { subject: probeTitle("env.bridge-sync") })
+      : bridgeSync.ok
+        ? t("quality.message.ok", { subject: probeTitle("env.bridge-sync") })
+        : bridgeSync.missing
+          ? t("quality.message.bridgeMissing", { subject: probeTitle("env.bridge-sync") })
+          : t("quality.message.bridgeMismatch", { subject: probeTitle("env.bridge-sync"), items: bridgeSync.mismatchedKeys.join(", ") }),
+    recommendation: probeRecommendation("env.bridge-sync"),
+    evidence: bridgeSync,
+  }));
+
+  probes.push(makeProbe({
+    id: "repo.clean",
+    domain: "repo",
+    severity: "high",
+    gates: ["release", "promotion"],
+    phaseRelevance: ["A"],
+    status: !state.repo.available ? "skip" : state.repo.clean ? "pass" : "fail",
+    title: probeTitle("repo.clean"),
+    message: !state.repo.available
+      ? t("quality.message.notApplicable", { subject: probeTitle("repo.clean") })
+      : state.repo.clean
+        ? t("quality.message.ok", { subject: probeTitle("repo.clean") })
+        : t("quality.message.dirtyTree", { subject: probeTitle("repo.clean") }),
+    recommendation: probeRecommendation("repo.clean"),
+    evidence: { clean: state.repo.clean, staged: state.repo.staged, unstaged: state.repo.unstaged, untracked: state.repo.untracked },
+  }));
+
+  probes.push(makeProbe({
+    id: "repo.behind-remote",
+    domain: "repo",
+    severity: "high",
+    gates: ["release", "promotion"],
+    phaseRelevance: ["A"],
+    status: !state.repo.available || !state.repo.hasUpstream ? "skip" : state.repo.behind > 0 ? "fail" : "pass",
+    title: probeTitle("repo.behind-remote"),
+    message: !state.repo.available || !state.repo.hasUpstream
+      ? t("quality.message.notApplicable", { subject: probeTitle("repo.behind-remote") })
+      : state.repo.behind > 0
+        ? t("quality.message.behindRemote", { subject: probeTitle("repo.behind-remote"), count: String(state.repo.behind) })
+        : t("quality.message.ok", { subject: probeTitle("repo.behind-remote") }),
+    recommendation: probeRecommendation("repo.behind-remote"),
+    evidence: { ahead: state.repo.ahead, behind: state.repo.behind, hasUpstream: state.repo.hasUpstream },
+  }));
+
+  probes.push(makeProbe({
+    id: "tasks.circular-deps",
+    domain: "tasks",
+    severity: "critical",
+    gates: ["phase", "release"],
+    phaseRelevance: ["E", "R", "A"],
+    status: state.derived.circularDeps.length ? "fail" : "pass",
+    title: probeTitle("tasks.circular-deps"),
+    message: state.derived.circularDeps.length
+      ? t("quality.message.missingItems", { subject: probeTitle("tasks.circular-deps"), items: state.derived.circularDeps.join(", ") })
+      : t("quality.message.ok", { subject: probeTitle("tasks.circular-deps") }),
+    recommendation: probeRecommendation("tasks.circular-deps"),
+    evidence: { taskIds: state.derived.circularDeps },
+  }));
+
+  probes.push(makeProbe({
+    id: "tasks.phantom-deps",
+    domain: "tasks",
+    severity: "high",
+    gates: ["phase", "release"],
+    phaseRelevance: ["E", "R"],
+    status: state.derived.phantomDeps.length ? "fail" : "pass",
+    title: probeTitle("tasks.phantom-deps"),
+    message: state.derived.phantomDeps.length
+      ? t("quality.message.countFail", { subject: probeTitle("tasks.phantom-deps"), count: String(state.derived.phantomDeps.length) })
+      : t("quality.message.ok", { subject: probeTitle("tasks.phantom-deps") }),
+    recommendation: probeRecommendation("tasks.phantom-deps"),
+    evidence: { phantomDeps: state.derived.phantomDeps },
+  }));
+
+  probes.push(makeProbe({
+    id: "tasks.phantom-parents",
+    domain: "tasks",
+    severity: "high",
+    gates: ["phase", "release"],
+    phaseRelevance: ["E", "R"],
+    status: state.derived.phantomParents.length ? "fail" : "pass",
+    title: probeTitle("tasks.phantom-parents"),
+    message: state.derived.phantomParents.length
+      ? t("quality.message.countFail", { subject: probeTitle("tasks.phantom-parents"), count: String(state.derived.phantomParents.length) })
+      : t("quality.message.ok", { subject: probeTitle("tasks.phantom-parents") }),
+    recommendation: probeRecommendation("tasks.phantom-parents"),
+    evidence: { phantomParents: state.derived.phantomParents },
+  }));
+
+  probes.push(makeProbe({
+    id: "tasks.hierarchy-cycles",
+    domain: "tasks",
+    severity: "critical",
+    gates: ["phase", "release"],
+    phaseRelevance: ["E", "R"],
+    status: state.derived.hierarchyCycles.length ? "fail" : "pass",
+    title: probeTitle("tasks.hierarchy-cycles"),
+    message: state.derived.hierarchyCycles.length
+      ? t("quality.message.missingItems", { subject: probeTitle("tasks.hierarchy-cycles"), items: state.derived.hierarchyCycles.join(", ") })
+      : t("quality.message.ok", { subject: probeTitle("tasks.hierarchy-cycles") }),
+    recommendation: probeRecommendation("tasks.hierarchy-cycles"),
+    evidence: { taskIds: state.derived.hierarchyCycles },
+  }));
+
+  probes.push(makeProbe({
+    id: "tasks.stale-in-progress",
+    domain: "tasks",
+    severity: "medium",
+    gates: ["phase"],
+    phaseRelevance: ["E", "R"],
+    status: staleInProgress.length ? "fail" : "pass",
+    title: probeTitle("tasks.stale-in-progress"),
+    message: staleInProgress.length
+      ? t("quality.message.staleTasks", { subject: probeTitle("tasks.stale-in-progress"), count: String(staleInProgress.length) })
+      : t("quality.message.ok", { subject: probeTitle("tasks.stale-in-progress") }),
+    recommendation: probeRecommendation("tasks.stale-in-progress"),
+    evidence: { taskIds: staleInProgress.map((task) => task.id) },
+  }));
+
+  probes.push(makeProbe({
+    id: "tasks.blocked-without-note",
+    domain: "tasks",
+    severity: "medium",
+    gates: ["phase"],
+    phaseRelevance: ["P", "E", "R"],
+    status: blockedWithoutNote.length ? "fail" : "pass",
+    title: probeTitle("tasks.blocked-without-note"),
+    message: blockedWithoutNote.length
+      ? t("quality.message.countFail", { subject: probeTitle("tasks.blocked-without-note"), count: String(blockedWithoutNote.length) })
+      : t("quality.message.ok", { subject: probeTitle("tasks.blocked-without-note") }),
+    recommendation: probeRecommendation("tasks.blocked-without-note"),
+    evidence: { taskIds: blockedWithoutNote.map((task) => task.id) },
+  }));
+
+  probes.push(makeProbe({
+    id: "tasks.required-without-acceptance",
+    domain: "tasks",
+    severity: "medium",
+    gates: ["phase"],
+    phaseRelevance: ["E", "R"],
+    status: requiredWithoutAcceptance.length ? "fail" : "pass",
+    title: probeTitle("tasks.required-without-acceptance"),
+    message: requiredWithoutAcceptance.length
+      ? t("quality.message.countFail", { subject: probeTitle("tasks.required-without-acceptance"), count: String(requiredWithoutAcceptance.length) })
+      : t("quality.message.ok", { subject: probeTitle("tasks.required-without-acceptance") }),
+    recommendation: probeRecommendation("tasks.required-without-acceptance"),
+    evidence: { taskIds: requiredWithoutAcceptance.map((task) => task.id) },
+  }));
+
+  probes.push(makeProbe({
+    id: "findings.open-critical",
+    domain: "findings",
+    severity: "critical",
+    gates: ["release", "promotion"],
+    phaseRelevance: ["R", "A"],
+    status: criticalFindings.length ? "fail" : "pass",
+    title: probeTitle("findings.open-critical"),
+    message: criticalFindings.length
+      ? t("quality.message.countFail", { subject: probeTitle("findings.open-critical"), count: String(criticalFindings.length) })
+      : t("quality.message.ok", { subject: probeTitle("findings.open-critical") }),
+    recommendation: probeRecommendation("findings.open-critical"),
+    evidence: { findingIds: criticalFindings.map((finding) => finding.id) },
+  }));
+
+  probes.push(makeProbe({
+    id: "findings.open-high",
+    domain: "findings",
+    severity: "high",
+    gates: ["phase"],
+    phaseRelevance: ["R", "A"],
+    status: highFindings.length ? "fail" : "pass",
+    title: probeTitle("findings.open-high"),
+    message: highFindings.length
+      ? t("quality.message.countFail", { subject: probeTitle("findings.open-high"), count: String(highFindings.length) })
+      : t("quality.message.ok", { subject: probeTitle("findings.open-high") }),
+    recommendation: probeRecommendation("findings.open-high"),
+    evidence: { findingIds: highFindings.map((finding) => finding.id) },
+  }));
+
+  probes.push(makeProbe({
+    id: "bootstrap.version-control",
+    domain: "bootstrap",
+    severity: "medium",
+    gates: ["phase", "promotion"],
+    phaseRelevance: ["O", "A"],
+    status: !state.hasOpera ? "skip" : intake.versionControl ? "pass" : "fail",
+    title: probeTitle("bootstrap.version-control"),
+    message: !state.hasOpera
+      ? t("quality.message.notApplicable", { subject: probeTitle("bootstrap.version-control") })
+      : intake.versionControl
+        ? t("quality.message.recordedFrom", {
+            subject: probeTitle("bootstrap.version-control"),
+            source: t(`quality.source.${state.bootstrapArtifacts.sources.versionControl || "unknown"}`),
+          })
+        : t("quality.message.failDetail", { subject: probeTitle("bootstrap.version-control"), detail: t("quality.value.missing") }),
+    recommendation: probeRecommendation("bootstrap.version-control"),
+    evidence: { versionControl: intake.versionControl || null, source: state.bootstrapArtifacts.sources.versionControl || null },
+  }));
+
+  probes.push(makeProbe({
+    id: "bootstrap.deployment",
+    domain: "bootstrap",
+    severity: "medium",
+    gates: ["phase", "promotion"],
+    phaseRelevance: ["O", "A"],
+    status: !state.hasOpera ? "skip" : intake.deployment ? "pass" : "fail",
+    title: probeTitle("bootstrap.deployment"),
+    message: !state.hasOpera
+      ? t("quality.message.notApplicable", { subject: probeTitle("bootstrap.deployment") })
+      : intake.deployment
+        ? t("quality.message.recordedFrom", {
+            subject: probeTitle("bootstrap.deployment"),
+            source: t(`quality.source.${state.bootstrapArtifacts.sources.deployment || "unknown"}`),
+          })
+        : t("quality.message.failDetail", { subject: probeTitle("bootstrap.deployment"), detail: t("quality.value.missing") }),
+    recommendation: probeRecommendation("bootstrap.deployment"),
+    evidence: { deployment: intake.deployment || null, source: state.bootstrapArtifacts.sources.deployment || null },
+  }));
+
+  probes.push(makeProbe({
+    id: "verification.configured",
+    domain: "verification",
+    severity: "low",
+    gates: ["phase"],
+    phaseRelevance: ["P", "R", "A"],
+    status: verificationConfigured ? "pass" : "skip",
+    title: probeTitle("verification.configured"),
+    message: verificationConfigured
+      ? t("quality.message.ok", { subject: probeTitle("verification.configured") })
+      : t("quality.message.notApplicable", { subject: probeTitle("verification.configured") }),
+    recommendation: probeRecommendation("verification.configured"),
+    evidence: {
+      testCommands: state.verificationConfig.testCommands.map((item) => item.command),
+      buildCommands: state.verificationConfig.buildCommands.map((item) => item.command),
+      smokeCommands: state.verificationConfig.smokeCommands.map((item) => item.command),
+      reviewRequired: state.verificationConfig.reviewRequired,
+    },
+  }));
+
+  return probes;
+}
+
+function buildQualityState(contextOrRoot, controlState) {
+  const context = config.ensureContext(contextOrRoot);
+  const control = controlState || config.loadControl(context);
+  setLocale(config.getLocale(control));
+  const derived = controlLib.derive(control);
+  const repo = controlLib.getRepoSnapshot(context);
+  const drift = controlLib.getDocDrift(context, control);
+  const envState = env.auditEnvironment(context, control);
+  const contract = loadContract(context);
+  const policy = loadPolicy(context);
+  const pkgInfo = parsePackageScripts(context);
+  const latest = latestVerificationSummary(context);
+  const bootstrapArtifacts = loadBootstrapArtifacts(context, control, { repo, pkgInfo });
+  const verificationConfig = inferVerificationConfig(context, control, bootstrapArtifacts.intake, pkgInfo);
+  const activeProfiles = detectProfiles(context, contract, bootstrapArtifacts.intake, envState, pkgInfo, verificationConfig);
+  return {
+    __qualityState: true,
+    context,
+    control,
+    derived,
+    repo,
+    drift,
+    envState,
+    contract,
+    policy,
+    pkgInfo,
+    latestVerification: latest,
+    bootstrapArtifacts,
+    verificationConfig,
+    activeProfiles,
+    hasOpera: config.isOperaInstalled(control),
+  };
+}
+
+function ensureQualityState(contextOrRoot, controlState) {
+  if (contextOrRoot && typeof contextOrRoot === "object" && contextOrRoot.__qualityState === true) {
+    return contextOrRoot;
+  }
+  return buildQualityState(contextOrRoot, controlState);
+}
+
+function buildQualityReportFromState(state) {
+  const probes = buildProbes(state);
+  const summary = summarizeProbes(probes);
+  return {
+    generatedAt: nowIso(),
+    projectName: state.control.meta?.projectName || path.basename(state.context.workspaceRoot),
+    currentPhase: state.derived.activePhase?.id || state.control.meta?.focusPhase || "O",
+    activeProfiles: state.activeProfiles,
+    summary,
+    probes,
+    verification: {
+      config: {
+        reviewRequired: state.verificationConfig.reviewRequired,
+        testCommands: state.verificationConfig.testCommands.map((item) => item.command),
+        buildCommands: state.verificationConfig.buildCommands.map((item) => item.command),
+        smokeCommands: state.verificationConfig.smokeCommands.map((item) => item.command),
+      },
+      latest: state.latestVerification.verification?.runs || {},
+      lastVerificationAt: state.latestVerification.lastVerificationAt || state.control.meta?.quality?.lastVerificationAt || null,
+    },
+  };
+}
+
+function buildQualityReport(contextOrRoot, controlState) {
+  return buildQualityReportFromState(ensureQualityState(contextOrRoot, controlState));
+}
+
+function recomputeSummaryWithFilters(report, filters = {}) {
+  const domain = filters.domain ? String(filters.domain).trim() : null;
+  const phase = filters.phase && filters.phase !== "current"
+    ? String(filters.phase).trim()
+    : filters.phase === "current"
+      ? report.currentPhase
+      : null;
+  const probes = report.probes.filter((probe) => {
+    if (domain && probe.domain !== domain) return false;
+    if (phase && probe.phaseRelevance.length && !probe.phaseRelevance.includes(phase)) return false;
+    return true;
+  });
+  return {
+    ...report,
+    probes,
+    summary: summarizeProbes(probes),
+  };
+}
+
+function normalizeWaiver(raw) {
+  return {
+    id: String(raw?.id || "").trim(),
+    probeId: String(raw?.probeId || "").trim(),
+    scope: String(raw?.scope || "").trim(),
+    reason: String(raw?.reason || "").trim(),
+    approvedBy: String(raw?.approvedBy || "").trim(),
+    expiresAt: raw?.expiresAt ? String(raw.expiresAt).trim() : null,
+    createdAt: raw?.createdAt ? String(raw.createdAt).trim() : null,
+  };
+}
+
+function listWaivers(contextOrRoot) {
+  const context = config.ensureContext(contextOrRoot);
+  const waivers = readJson(context.paths.qualityWaiversFile, []);
+  return Array.isArray(waivers) ? waivers.map((item) => normalizeWaiver(item)).filter((item) => item.id) : [];
+}
+
+function addWaiver(contextOrRoot, payload) {
+  const context = config.ensureContext(contextOrRoot);
+  const probeId = String(payload?.probeId || "").trim();
+  const scope = String(payload?.scope || "").trim();
+  const reason = String(payload?.reason || "").trim();
+  const approvedBy = String(payload?.approvedBy || "").trim();
+  const expiresAt = payload?.expiresAt ? String(payload.expiresAt).trim() : null;
+
+  if (!probeId) throw new Error(t("quality.error.waiverProbeRequired"));
+  if (!["release", "promotion"].includes(scope)) throw new Error(t("quality.error.waiverScope"));
+  if (!reason) throw new Error(t("quality.error.waiverReason"));
+  if (!approvedBy) throw new Error(t("quality.error.waiverApprovedBy"));
+  if (scope === "promotion" && !expiresAt) throw new Error(t("quality.error.waiverExpiry"));
+
+  ensureQualityStorage(context);
+  const waivers = listWaivers(context);
+  const waiver = {
+    id: `waiver-${Date.now().toString(36)}`,
+    probeId,
+    scope,
+    reason,
+    approvedBy,
+    expiresAt,
+    createdAt: nowIso(),
+  };
+  waivers.push(waiver);
+  writeJson(context.paths.qualityWaiversFile, waivers);
+  return waiver;
+}
+
+function activeWaiverFor(waivers, probeId, scope) {
+  const now = Date.now();
+  return waivers.find((waiver) => {
+    if (waiver.probeId !== probeId || waiver.scope !== scope) return false;
+    if (!waiver.expiresAt) return true;
+    const expiry = Date.parse(waiver.expiresAt);
+    return !Number.isFinite(expiry) || expiry > now;
+  }) || null;
+}
+
+function verificationRequirements(state) {
+  return {
+    test: state.verificationConfig.testCommands.length > 0,
+    build: state.verificationConfig.buildCommands.length > 0,
+    smoke: state.verificationConfig.smokeCommands.length > 0,
+    review: state.verificationConfig.reviewRequired === true,
+  };
+}
+
+function verificationBlockers(state, scope) {
+  const latestRuns = state.latestVerification.verification?.runs || {};
+  const requirements = verificationRequirements(state);
+  const blockers = [];
+  const evaluateScope = (name, commands, required) => {
+    if (!required) return;
+    const latestRun = latestRuns[name];
+    const expectedCommands = name === "review"
+      ? [{ command: "manual-review", cwd: state.context.workspaceRoot }]
+      : commands;
+    const expectedSignature = buildCommandSignature(expectedCommands);
+    const signatureMatches = latestRun?.commandSignature === expectedSignature;
+    if (latestRun && latestRun.status === "passed" && signatureMatches) return;
+    blockers.push({
+      id: `verification.${name}`,
+      source: "verification",
+      severity: name === "review" ? "medium" : "high",
+      message: !latestRun
+        ? t("quality.verification.blocker.missing", { scope: formatScopeLabel(name) })
+        : latestRun.status !== "passed"
+          ? t("quality.verification.blocker.failed", { scope: formatScopeLabel(name) })
+          : t("quality.verification.blocker.stale", { scope: formatScopeLabel(name) }),
+      recommendation: t("quality.verification.blocker.recommendation", { scope: name }),
+      evidence: latestRun || {
+        commands: expectedCommands.map((item) => item.command),
+        commandSignature: expectedSignature,
+      },
+    });
+  };
+
+  if (scope === "release" || scope === "promotion") {
+    evaluateScope("test", state.verificationConfig.testCommands, requirements.test);
+    evaluateScope("build", state.verificationConfig.buildCommands, requirements.build);
+    evaluateScope("smoke", state.verificationConfig.smokeCommands, requirements.smoke);
+    evaluateScope("review", [], requirements.review);
+  }
+  return blockers;
+}
+
+function evaluatePhaseReadinessFromState(state, options = {}) {
+  const phaseId = options.phase && options.phase !== "current"
+    ? String(options.phase).trim()
+    : state.derived.activePhase?.id || state.control.meta?.focusPhase || "O";
+  const definition = PHASE_DOD[phaseId] || PHASE_DOD.O;
+  const checks = definition.checks.map((check) => {
+    const result = check.evaluate({
+      ...state,
+      fs,
+      fileExists,
+      normalizeFindingSeverity,
+    }) || { status: "skip" };
+    const status = ["pass", "fail", "warn", "skip"].includes(result.status) ? result.status : "skip";
+    const title = t(check.titleKey);
+    const detail = hasText(result.detail) ? String(result.detail).trim() : "";
+    const messageKey = status === "pass"
+      ? "quality.phase.message.pass"
+      : status === "fail"
+        ? (detail ? "quality.phase.message.failDetail" : "quality.phase.message.fail")
+        : status === "warn"
+          ? (detail ? "quality.phase.message.warnDetail" : "quality.phase.message.warn")
+          : "quality.phase.message.skip";
+    return {
+      id: check.id,
+      severity: check.severity || "medium",
+      status,
+      title,
+      message: detail ? t(messageKey, { title, detail }) : t(messageKey, { title }),
+      recommendation: status === "pass" || status === "skip" ? "" : t(check.recommendationKey),
+      evidence: result.evidence || {},
+    };
+  });
+
+  const blockers = checks.filter((check) => check.status === "fail");
+  const warnings = checks.filter((check) => check.status === "warn");
+  return {
+    kind: "phase",
+    phase: phaseId,
+    generatedAt: nowIso(),
+    ready: blockers.length === 0 && warnings.length === 0,
+    status: blockers.length || warnings.length ? "attention" : "ready",
+    blockers,
+    warnings,
+    checks,
+    definition: {
+      id: definition.id,
+      title: t(definition.titleKey),
+    },
+  };
+}
+
+function applyWaiversToItems(waivers, scope, items) {
+  return items.map((item) => {
+    const waiver = activeWaiverFor(waivers, item.id, scope);
+    return { ...item, waived: Boolean(waiver), waiver };
+  });
+}
+
+function resolveReadinessFromState(kind, state, options = {}) {
+  if (kind === "phase") {
+    return evaluatePhaseReadinessFromState(state, options);
+  }
+
+  const report = buildQualityReportFromState(state);
+  const waivers = listWaivers(state.context);
+  const scope = kind === "promotion" ? "promotion" : "release";
+  const probeCandidates = report.probes
+    .filter((probe) => probe.status === "fail" && probe.gates.includes(scope))
+    .map((probe) => ({
+      id: probe.id,
+      source: "probe",
+      severity: probe.severity,
+      message: probe.message,
+      recommendation: probe.recommendation,
+      evidence: probe.evidence,
+    }));
+
+  const extraBlockers = verificationBlockers(state, scope);
+  if (kind === "promotion" && String(options.target || "").trim() === "production") {
+    if (!state.bootstrapArtifacts.intake?.versionControl) {
+      extraBlockers.push({
+        id: "promotion.version-control-metadata",
+        source: "policy",
+        severity: "high",
+        message: t("quality.promotion.versionControlRequired"),
+        recommendation: t("quality.promotion.versionControlRecommendation"),
+        evidence: { versionControl: null },
+      });
+    }
+    const deployment = state.bootstrapArtifacts.intake?.deployment || null;
+    if (!deployment?.target || !deployment?.mode || !deployment?.smokeCommand) {
+      extraBlockers.push({
+        id: "promotion.deployment-metadata",
+        source: "policy",
+        severity: "high",
+        message: t("quality.promotion.deploymentRequired"),
+        recommendation: t("quality.promotion.deploymentRecommendation"),
+        evidence: { deployment },
+      });
+    }
+    if (!state.policy.valid || state.policy.data?.approvalRules?.production_deploy_requires_approval !== true) {
+      extraBlockers.push({
+        id: "promotion.policy-approval",
+        source: "policy",
+        severity: "critical",
+        message: t("quality.promotion.policyApprovalRequired"),
+        recommendation: t("quality.promotion.policyApprovalRecommendation"),
+        evidence: { approvalRules: state.policy.data?.approvalRules || null, valid: state.policy.valid },
+      });
+    }
+  }
+
+  const candidates = applyWaiversToItems(waivers, scope, [...probeCandidates, ...extraBlockers]);
+  const unwaived = candidates.filter((item) => !item.waived);
+  const blockers = unwaived.filter((item) => BLOCKING_SEVERITIES.has(item.severity));
+  const warnings = unwaived.filter((item) => !BLOCKING_SEVERITIES.has(item.severity));
+
+  return {
+    kind,
+    target: kind === "promotion" ? String(options.target || "").trim() || "staging" : null,
+    phase: null,
+    generatedAt: nowIso(),
+    ready: blockers.length === 0,
+    status: blockers.length ? "blocked" : warnings.length ? "attention" : "ready",
+    blockers,
+    warnings,
+    waived: candidates.filter((item) => item.waived),
+    verification: state.latestVerification.verification?.runs || {},
+  };
+}
+
+function buildPhaseReadiness(contextOrRoot, controlState, options = {}) {
+  return resolveReadinessFromState("phase", ensureQualityState(contextOrRoot, controlState), options);
+}
+
+function buildReleaseReadiness(contextOrRoot, controlState, options = {}) {
+  return resolveReadinessFromState("release", ensureQualityState(contextOrRoot, controlState), options);
+}
+
+function buildPromotionReadiness(contextOrRoot, controlState, options = {}) {
+  return resolveReadinessFromState("promotion", ensureQualityState(contextOrRoot, controlState), options);
+}
+
+function updateQualityMeta(context, controlState, patch) {
+  controlState.meta = controlState.meta || {};
+  controlState.meta.quality = config.normalizeQualityMeta({
+    ...(controlState.meta.quality || {}),
+    ...(patch || {}),
+  });
+}
+
+function persistVerificationLatest(context, runSummary) {
+  ensureQualityStorage(context);
+  const latest = latestVerificationSummary(context);
+  latest.generatedAt = nowIso();
+  if (runSummary.results.some((result) => result.executed)) {
+    latest.lastVerificationAt = runSummary.finishedAt;
+  }
+  latest.verification = latest.verification || { runs: {} };
+  latest.verification.runs = latest.verification.runs || {};
+
+  for (const result of runSummary.results) {
+    if (!result.executed) continue;
+    latest.verification.runs[result.scope] = {
+      status: result.status,
+      commands: result.commands.map((item) => ({
+        command: item.command,
+        cwd: normalizePath(item.cwd),
+      })),
+      commandSignature: buildCommandSignature(result.commands),
+      startedAt: result.startedAt,
+      finishedAt: result.finishedAt,
+      exitCode: result.exitCode,
+      note: result.note || "",
+      commit: result.commit || null,
+    };
+  }
+
+  writeJson(context.paths.qualityLatestFile, latest);
+}
+
+function truncateText(text, limit = 1200) {
+  const value = String(text || "");
+  if (value.length <= limit) return value;
+  return `${value.slice(0, limit)}\n...[truncated]`;
+}
+
+function runVerificationCommand(spec) {
+  const startedAt = nowIso();
+  const result = spawnSync(spec.command, {
+    cwd: spec.cwd,
+    shell: true,
+    encoding: "utf8",
+  });
+  const finishedAt = nowIso();
+  return {
+    command: spec.command,
+    cwd: spec.cwd,
+    startedAt,
+    finishedAt,
+    exitCode: Number.isInteger(result.status) ? result.status : 1,
+    stdout: truncateText(result.stdout || ""),
+    stderr: truncateText(result.stderr || ""),
+    status: result.status === 0 ? "passed" : "failed",
+  };
+}
+
+function scopeCommandSpecs(state, scope) {
+  const map = {
+    test: state.verificationConfig.testCommands,
+    build: state.verificationConfig.buildCommands,
+    smoke: state.verificationConfig.smokeCommands,
+  };
+  return (map[scope] || []).map((item) => ({ command: item.command, cwd: item.cwd }));
+}
+
+function aggregateVerificationScope(state, scope, options = {}) {
+  const note = String(options.note || "").trim();
+  const commit = options.commit || null;
+  const specific = options.specific === true;
+  const at = nowIso();
+
+  if (scope === "review") {
+    if (!state.verificationConfig.reviewRequired) {
+      return {
+        scope,
+        status: "skipped",
+        reason: "not_required",
+        required: false,
+        executed: false,
+        commands: [],
+        startedAt: at,
+        finishedAt: at,
+        exitCode: 0,
+        note,
+        commit,
+      };
+    }
+    if (!note) {
+      return {
+        scope,
+        status: "failed",
+        reason: "missing_note",
+        required: true,
+        executed: true,
+        commands: [{ command: "manual-review", cwd: state.context.workspaceRoot, status: "failed", exitCode: 1, startedAt: at, finishedAt: at, stdout: "", stderr: t("quality.verify.reviewNoteRequired") }],
+        startedAt: at,
+        finishedAt: at,
+        exitCode: 1,
+        note,
+        commit,
+      };
+    }
+    return {
+      scope,
+      status: "passed",
+      reason: null,
+      required: true,
+      executed: true,
+      commands: [{ command: "manual-review", cwd: state.context.workspaceRoot, status: "passed", exitCode: 0, startedAt: at, finishedAt: at, stdout: "", stderr: "" }],
+      startedAt: at,
+      finishedAt: at,
+      exitCode: 0,
+      note,
+      commit,
+    };
+  }
+
+  const specs = scopeCommandSpecs(state, scope);
+  if (!specs.length) {
+    return {
+      scope,
+      status: specific ? "not_configured" : "skipped",
+      reason: specific ? "missing_config" : "not_required",
+      required: specific,
+      executed: false,
+      commands: [],
+      startedAt: at,
+      finishedAt: at,
+      exitCode: specific ? 1 : 0,
+      note,
+      commit,
+    };
+  }
+
+  const commands = specs.map((spec) => runVerificationCommand(spec));
+  return {
+    scope,
+    status: commands.every((item) => item.status === "passed") ? "passed" : "failed",
+    reason: null,
+    required: true,
+    executed: true,
+    commands,
+    startedAt: commands[0]?.startedAt || at,
+    finishedAt: commands[commands.length - 1]?.finishedAt || at,
+    exitCode: commands.every((item) => item.exitCode === 0) ? 0 : 1,
+    note,
+    commit,
+  };
+}
+
+function requestedScopes(scope) {
+  const normalized = String(scope || "all").trim().toLowerCase();
+  if (normalized === "all") return ["test", "build", "smoke", "review"];
+  return [normalized];
+}
+
+function summarizeVerificationResults(results) {
+  if (results.some((result) => result.status === "failed" || result.status === "not_configured")) {
+    return { status: "failed", ok: false };
+  }
+  if (results.every((result) => result.status === "skipped")) {
+    return { status: "skipped", ok: true };
+  }
+  if (results.every((result) => result.status === "passed" || result.status === "skipped")) {
+    return { status: "passed", ok: true };
+  }
+  return { status: "failed", ok: false };
+}
+
+function verify(contextOrRoot, options = {}) {
+  const state = ensureQualityState(contextOrRoot);
+  const context = state.context;
+  const controlState = state.control;
+  const scope = String(options.scope || "all").trim().toLowerCase();
+  const note = String(options.note || "").trim();
+  const commit = getGitCommit(context);
+  const results = requestedScopes(scope).map((requestedScope) => aggregateVerificationScope(state, requestedScope, {
+    note,
+    commit,
+    specific: scope !== "all",
+  }));
+  const finishedAt = nowIso();
+  const summary = summarizeVerificationResults(results);
+  const runId = finishedAt.replace(/[:.]/g, "-");
+  const runSummary = {
+    id: `quality-${runId}`,
+    generatedAt: nowIso(),
+    startedAt: results[0]?.startedAt || finishedAt,
+    finishedAt,
+    scope,
+    note,
+    commit,
+    status: summary.status,
+    results,
+  };
+
+  ensureQualityStorage(context);
+  writeJson(path.join(context.paths.qualityRunsDir, `${runId}.json`), runSummary);
+  persistVerificationLatest(context, runSummary);
+
+  const latestByScope = Object.fromEntries(results.map((item) => [item.scope, item]));
+  controlState.checks = controlState.checks || {};
+  if (latestByScope.test?.executed) {
+    controlState.checks.lastTest = {
+      status: latestByScope.test.status === "passed" ? "pass" : "fail",
+      date: latestByScope.test.finishedAt,
+      note: latestByScope.test.note || latestByScope.test.commands.map((item) => item.command).join(" && "),
+    };
+  }
+  if (latestByScope.build?.executed) {
+    controlState.checks.lastBuild = {
+      status: latestByScope.build.status === "passed" ? "pass" : "fail",
+      date: latestByScope.build.finishedAt,
+      note: latestByScope.build.note || latestByScope.build.commands.map((item) => item.command).join(" && "),
+    };
+  }
+  if (latestByScope.review?.executed) {
+    controlState.checks.lastReview = {
+      status: latestByScope.review.status === "passed" ? "pass" : "fail",
+      date: latestByScope.review.finishedAt,
+      note: latestByScope.review.note || "manual-review",
+    };
+  }
+  const activeProfiles = buildQualityReportFromState(buildQualityState(context, controlState)).activeProfiles;
+  updateQualityMeta(context, controlState, {
+    activeProfiles,
+    lastVerificationAt: results.some((result) => result.executed) ? finishedAt : controlState.meta?.quality?.lastVerificationAt || null,
+  });
+  config.saveControl(context, controlState);
+  controlLib.syncDocs(context, controlState);
+  controlLib.refreshRepoRuntime(context, { quiet: true });
+  return runSummary;
+}
+
+function buildQualitySnapshot(contextOrRoot, controlState) {
+  const state = ensureQualityState(contextOrRoot, controlState);
+  return {
+    report: buildQualityReportFromState(state),
+    phaseReadiness: buildPhaseReadiness(state, null, { phase: "current" }),
+    releaseReadiness: buildReleaseReadiness(state),
+    promotionReadiness: buildPromotionReadiness(state, null, { target: "production" }),
+    waivers: listWaivers(state.context),
+  };
+}
+
+function parseFlagValue(args, flagName) {
+  const index = args.indexOf(flagName);
+  if (index === -1) return null;
+  return args[index + 1] || null;
+}
+
+function printReadiness(readiness) {
+  const label = readiness.kind === "phase"
+    ? t("quality.readiness.phase", { phase: readiness.phase })
+    : readiness.kind === "promotion"
+      ? t("quality.readiness.promotion", { target: readiness.target })
+      : t("quality.readiness.release");
+  console.log(`${label}: ${formatQualityStatus(readiness.status)}`);
+  if (readiness.blockers.length) {
+    console.log("");
+    console.log(t("quality.section.blockers"));
+    readiness.blockers.forEach((item) => console.log(`- [${item.severity}] ${item.id}: ${item.message}`));
+  }
+  if (readiness.warnings.length) {
+    console.log("");
+    console.log(t("quality.section.warnings"));
+    readiness.warnings.forEach((item) => console.log(`- [${item.severity}] ${item.id}: ${item.message}`));
+  }
+  if (readiness.waived?.length) {
+    console.log("");
+    console.log(t("quality.section.waived"));
+    readiness.waived.forEach((item) => console.log(`- ${item.id} (${item.waiver.id})`));
+  }
+}
+
+function printStatusReport(report) {
+  console.log(`${t("quality.section.status")}: ${formatQualityStatus(report.summary.overallStatus)}`);
+  console.log(`${t("quality.section.currentPhase")}: ${report.currentPhase}`);
+  console.log(`${t("quality.section.profiles")}: ${report.activeProfiles.join(", ") || t("locale.none")}`);
+  console.log(`${t("quality.section.probes")}: pass=${report.summary.counts.pass} fail=${report.summary.counts.fail} skip=${report.summary.counts.skip}`);
+  const failures = report.probes.filter((probe) => probe.status === "fail");
+  if (failures.length) {
+    console.log("");
+    console.log(t("quality.section.findings"));
+    failures.forEach((probe) => console.log(`- [${probe.severity}] ${probe.id}: ${probe.message}`));
+  }
+}
+
+function printVerification(runSummary) {
+  console.log(`${t("quality.section.verification")}: ${formatQualityStatus(runSummary.status)}`);
+  runSummary.results.forEach((result) => {
+    console.log(`- ${formatScopeLabel(result.scope)}: ${formatQualityStatus(result.status)}`);
+  });
+}
+
+function printWaivers(waivers) {
+  if (!waivers.length) {
+    console.log(t("quality.waivers.none"));
+    return;
+  }
+  waivers.forEach((waiver) => {
+    console.log(`- ${waiver.id}: ${waiver.probeId} (${waiver.scope}) ${t("quality.waivers.approvedBy", { approvedBy: waiver.approvedBy })}`);
+  });
+}
+
+function printUsage() {
+  console.log(t("quality.usage.title"));
+  console.log(`  ${t("quality.usage.status")}`);
+  console.log(`  ${t("quality.usage.verify")}`);
+  console.log(`  ${t("quality.usage.phaseReadiness")}`);
+  console.log(`  ${t("quality.usage.releaseReadiness")}`);
+  console.log(`  ${t("quality.usage.promoteReadiness")}`);
+  console.log(`  ${t("quality.usage.waiverList")}`);
+  console.log(`  ${t("quality.usage.waiverAdd")}`);
+}
+
+function cmdQuality(root, args = []) {
+  const context = config.ensureContext(root);
+  const control = config.loadControl(context);
+  setLocale(config.getLocale(control));
+  const sub = String(args[0] || "status").trim();
+  const json = args.includes("--json");
+
+  if (sub === "status") {
+    const report = recomputeSummaryWithFilters(buildQualityReport(context, control), {
+      domain: parseFlagValue(args, "--domain"),
+      phase: parseFlagValue(args, "--phase"),
+    });
+    if (json) console.log(JSON.stringify(report, null, 2));
+    else printStatusReport(report);
+    return;
+  }
+
+  if (sub === "verify") {
+    const runSummary = verify(context, {
+      scope: parseFlagValue(args, "--scope") || "all",
+      note: parseFlagValue(args, "--note") || "",
+    });
+    if (json) console.log(JSON.stringify(runSummary, null, 2));
+    else printVerification(runSummary);
+    if (runSummary.status === "failed") process.exitCode = 1;
+    return;
+  }
+
+  if (sub === "phase-readiness") {
+    const readiness = buildPhaseReadiness(context, control, { phase: parseFlagValue(args, "--phase") || "current" });
+    if (json) console.log(JSON.stringify(readiness, null, 2));
+    else printReadiness(readiness);
+    return;
+  }
+
+  if (sub === "release-readiness") {
+    const readiness = buildReleaseReadiness(context, control);
+    if (json) console.log(JSON.stringify(readiness, null, 2));
+    else printReadiness(readiness);
+    if (!readiness.ready) process.exitCode = 1;
+    return;
+  }
+
+  if (sub === "promote-readiness") {
+    const readiness = buildPromotionReadiness(context, control, { target: parseFlagValue(args, "--target") || "staging" });
+    if (json) console.log(JSON.stringify(readiness, null, 2));
+    else printReadiness(readiness);
+    if (!readiness.ready) process.exitCode = 1;
+    return;
+  }
+
+  if (sub === "waiver") {
+    const action = String(args[1] || "list").trim();
+    if (action === "list") {
+      const waivers = listWaivers(context);
+      if (json) console.log(JSON.stringify(waivers, null, 2));
+      else printWaivers(waivers);
+      return;
+    }
+    if (action === "add") {
+      const waiver = addWaiver(context, {
+        probeId: args[2],
+        scope: parseFlagValue(args, "--scope"),
+        reason: parseFlagValue(args, "--reason"),
+        approvedBy: parseFlagValue(args, "--approved-by"),
+        expiresAt: parseFlagValue(args, "--expires-at"),
+      });
+      if (json) console.log(JSON.stringify(waiver, null, 2));
+      else console.log(t("quality.waivers.created", { id: waiver.id }));
+      return;
+    }
+  }
+
+  printUsage();
+}
+
+module.exports = {
+  buildQualityReport,
+  buildQualitySnapshot,
+  buildPhaseReadiness,
+  buildReleaseReadiness,
+  buildPromotionReadiness,
+  verify,
+  listWaivers,
+  addWaiver,
+  backfillBootstrapMetadata,
+  normalizeFindingSeverity,
+  formatQualityStatus,
+  cmdQuality,
+};