@williambeto/ai-workflow 1.19.1 → 2.2.0

package/src/core/templates.js

@@ -0,0 +1,221 @@
+import { getFullAgentContent, getFullSkillFiles, discoverPackageFiles, readPackageFile, getPackageVersion } from "./package-assets.js";
+import { getCanonicalAgentName } from "./identity.js";
+
+const COMMON_FILES = {
+  "opencode/README.md": `# OpenCode Setup\n\nThis directory is managed by \`ai-workflow\` init.\nAdd agent and command files required by your project workflow.\n`
+};
+
+const FULL_PRIMARY_AGENTS = [
+  "atlas",
+  "nexus",
+  "orion",
+  "astra",
+  "sage",
+  "phoenix"
+];
+
+const FULL_SKILLS = [
+  "project-memory",
+  "optimize-tokens",
+  "documentation",
+  "architecture",
+  "technical-leadership",
+  "product-discovery",
+  "product-planning",
+  "spec-driven-development",
+  "pr-workflow",
+  "qa-workflow",
+  "release-workflow",
+  "deployment",
+  "ui-ux-design",
+  "design-principles",
+  "frontend-development",
+  "backend-development",
+  "full-stack-development",
+  "refactoring",
+  "prompt-engineer"
+];
+
+const KIT_VERSION = getPackageVersion() ?? "unknown";
+
+function buildRuntimeFiles({ includeFormalEvidence = false } = {}) {
+  const files = {};
+
+  for (const agent of FULL_PRIMARY_AGENTS) {
+    const content = getFullAgentContent(agent);
+    if (content === null) {
+      throw new Error(`CRITICAL FAILURE: Missing required agent asset: dist-assets/agents/${agent}.md`);
+    }
+    files[`opencode/agents/${agent}.md`] = content;
+  }
+
+  for (const skill of FULL_SKILLS) {
+    const skillFiles = getFullSkillFiles(skill);
+    if (Object.keys(skillFiles).length === 0) {
+      continue;
+    }
+    for (const [relPath, content] of Object.entries(skillFiles)) {
+      const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+      if (!files[targetPath]) {
+        files[targetPath] = content;
+      }
+    }
+  }
+
+  const commandFiles = discoverPackageFiles("dist-assets/commands");
+  for (const [relPath, content] of Object.entries(commandFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    if (!files[targetPath]) {
+      files[targetPath] = content;
+    }
+  }
+
+  const opencodeSkillFiles = discoverPackageFiles("dist-assets/skills");
+  for (const [relPath, content] of Object.entries(opencodeSkillFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    if (!files[targetPath]) {
+      files[targetPath] = content;
+    }
+  }
+
+  const harnessWorkflowFiles = discoverPackageFiles("dist-assets/harness/workflows");
+  for (const [relPath, content] of Object.entries(harnessWorkflowFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  const harnessHandoffFiles = discoverPackageFiles("dist-assets/harness/handoffs");
+  for (const [relPath, content] of Object.entries(harnessHandoffFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  const agentsContent = readPackageFile("dist-assets/AGENTS.md");
+  if (agentsContent !== null) files["AGENTS.md"] = agentsContent;
+
+  const consumerQuickstart = readPackageFile("dist-assets/docs/QUICKSTART.md");
+  if (consumerQuickstart !== null) files["QUICKSTART.md"] = consumerQuickstart;
+
+  const policyContent = readPackageFile("dist-assets/docs/architecture-policy.md");
+  if (policyContent !== null) files["docs/architecture-policy.md"] = policyContent;
+
+  const dpContent = readPackageFile("dist-assets/docs/design-patterns-policy.md");
+  if (dpContent !== null) files["docs/design-patterns-policy.md"] = dpContent;
+
+  const visualValidationGuide = readPackageFile("dist-assets/docs/visual-validation-guide.md");
+  if (visualValidationGuide !== null) files["docs/visual-validation-guide.md"] = visualValidationGuide;
+
+  const governancePolicies = discoverPackageFiles("dist-assets/docs/policies");
+  for (const [relPath, content] of Object.entries(governancePolicies)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  const compatibilityDocs = discoverPackageFiles("dist-assets/docs/compatibility");
+  for (const [relPath, content] of Object.entries(compatibilityDocs)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  const qualityReferenceFiles = discoverPackageFiles("dist-assets/docs/references");
+  for (const [relPath, content] of Object.entries(qualityReferenceFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  const workflowProfileFiles = discoverPackageFiles("dist-assets/docs/profiles");
+  for (const [relPath, content] of Object.entries(workflowProfileFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  const templateFiles = discoverPackageFiles("dist-assets/templates");
+  for (const [relPath, content] of Object.entries(templateFiles)) {
+    if (!includeFormalEvidence && relPath.includes("/owner-evidence/")) continue;
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  const schemaFiles = discoverPackageFiles("dist-assets/schemas");
+  for (const [relPath, content] of Object.entries(schemaFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+
+  return files;
+}
+
+function buildExtraFiles() {
+  const files = {};
+  const exampleFiles = discoverPackageFiles("dist-assets/examples");
+  for (const [relPath, content] of Object.entries(exampleFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+  return files;
+}
+
+const STANDARD_FILES = buildRuntimeFiles();
+const FULL_FILES = { ...buildRuntimeFiles({ includeFormalEvidence: true }), ...buildExtraFiles() };
+
+export const PROFILE_FILES = {
+  standard: {
+    ...COMMON_FILES,
+    ...STANDARD_FILES
+  },
+  full: {
+    ...COMMON_FILES,
+    ...FULL_FILES
+  }
+};
+
+export function isValidProfile(profile) {
+  return profile === "standard" || profile === "full";
+}
+
+export function getTemplateFiles(profile = "standard") {
+  return PROFILE_FILES[profile] ?? PROFILE_FILES.standard;
+}
+
+export function getManagedBlocks() {
+  return [
+    ...FULL_PRIMARY_AGENTS.map((agent) => `opencode.jsonc:agent.${getCanonicalAgentName(agent)}`),
+    ...FULL_SKILLS.map((skill) => `opencode.jsonc:agent.${getCanonicalAgentName(skill)}`),
+    "opencode.jsonc:command.atlas",
+    "opencode.jsonc:command.run",
+    "opencode.jsonc:command.discover",
+    "opencode.jsonc:command.spec-create",
+    "opencode.jsonc:command.spec-review",
+    "opencode.jsonc:command.spec-implement",
+    "opencode.jsonc:command.plan",
+    "opencode.jsonc:command.implement",
+    "opencode.jsonc:command.validate",
+    "opencode.jsonc:command.audit",
+    "opencode.jsonc:command.optimize-tokens",
+    "opencode.jsonc:command.update-memory",
+    "opencode.jsonc:command.release",
+    "opencode.jsonc:command.deploy"
+  ];
+}
+
+export function buildAiWorkflowConfig({ profile, managedFiles, managedLinks = [] }) {
+  const version = getPackageVersion();
+  const now = new Date().toISOString();
+
+  return {
+    package: "@williambeto/ai-workflow",
+    version,
+    runtime: "opencode",
+    profile,
+    installMode: "project-local",
+    generatedAt: now,
+    paths: {
+      agents: ".ai-workflow/opencode/agents",
+      commands: ".ai-workflow/opencode/commands",
+      skills: ".ai-workflow/opencode/skills",
+      policies: ".ai-workflow/docs/policies",
+      harness: ".ai-workflow/harness",
+      schemas: ".ai-workflow/schemas"
+    }
+  };
+}

package/src/core/validation/canonical-finalization.js

@@ -0,0 +1,43 @@
+export const DELIVERY_SUMMARY_FIELDS = Object.freeze([
+  "Status",
+  "Branch",
+  "Changes",
+  "Validation",
+  "Known limitations"
+]);
+
+export function buildDeliverySummary({ evidence }) {
+  const commands = (evidence?.commands || []).map((item) => `${item.command || item.name}: ${item.status}`).join("; ") || "No validation commands recorded";
+  return {
+    Status: evidence?.status || "BLOCKED",
+    Branch: evidence?.branch || "unknown",
+    Changes: (evidence?.changedFiles || []).join(", ") || "No changed files recorded",
+    Validation: commands,
+    "Known limitations": (evidence?.limitations || []).join("; ") || "None recorded"
+  };
+}
+
+export function validateDeliverySummary(summary) {
+  const missing = DELIVERY_SUMMARY_FIELDS.filter((field) => !String(summary?.[field] || "").trim());
+  const status = String(summary?.Status || "").trim();
+  const invalid = [];
+  if (!["COMPLETED", "COMPLETED_WITH_NOTES", "BLOCKED"].includes(status)) invalid.push("Status");
+  if (status !== "BLOCKED" && /FAIL|BLOCKED/.test(String(summary?.Validation || ""))) invalid.push("successful status with failed validation");
+  return { status: missing.length || invalid.length ? "FAIL" : "PASS", missing, invalid };
+}
+
+export function formatDeliverySummary(summary) {
+  return DELIVERY_SUMMARY_FIELDS.map((field) => `${field}: ${summary?.[field] || "NOT_RECORDED"}`).join("\n");
+}
+
+// Backward-compatible aliases for integrations that imported the previous API.
+export const CANONICAL_FINALIZATION_FIELDS = DELIVERY_SUMMARY_FIELDS;
+export const buildCanonicalFinalization = ({ collectorStatus = "BLOCKED", branchRecovery = "unknown" } = {}) => ({
+  Status: collectorStatus === "PASS" ? "COMPLETED" : collectorStatus === "PASS_WITH_NOTES" ? "COMPLETED_WITH_NOTES" : "BLOCKED",
+  Branch: branchRecovery,
+  Changes: "See observed diff",
+  Validation: collectorStatus,
+  "Known limitations": "See evidence"
+});
+export const validateCanonicalFinalization = validateDeliverySummary;
+export const formatCanonicalFinalization = formatDeliverySummary;

package/src/core/validation/evidence-collector.js

@@ -0,0 +1,109 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { QualityGuard } from "./quality-guard.js";
+
+const VALIDATION_KINDS = new Set(["test", "build", "typecheck", "lint", "security", "smoke", "validate", "other"]);
+
+function publicStatus(status) {
+  if (status === "PASS") return "COMPLETED";
+  if (status === "PASS_WITH_NOTES") return "COMPLETED_WITH_NOTES";
+  return "BLOCKED";
+}
+
+function inferTaskKind(task = {}) {
+  const explicit = String(task.kind || "").trim().toLowerCase();
+  if (VALIDATION_KINDS.has(explicit)) return explicit;
+
+  const value = `${task.name || ""} ${task.command || ""}`.toLowerCase();
+  if (/\b(test|tests|vitest|jest|mocha|ava|tap|pytest|phpunit|rspec|cypress|playwright)\b/.test(value)) return "test";
+  if (/\b(typecheck|tsc\b|mypy|pyright)\b/.test(value)) return "typecheck";
+  if (/\b(lint|eslint|stylelint|ruff|flake8|pylint)\b/.test(value)) return "lint";
+  if (/\b(build|bundle|compile)\b/.test(value)) return "build";
+  if (/\b(audit|security|sast|scan)\b/.test(value)) return "security";
+  if (/\b(smoke|curl|preview|serve)\b/.test(value)) return "smoke";
+  if (/\bvalidate\b/.test(value)) return "validate";
+  return "other";
+}
+
+export class EvidenceCollector {
+  constructor({ cwd, maxLogLength = 2000, timeout = 60000, taskSlug = null, mode = null, profile = "generic", branchRecovery = "NOT_RECORDED" } = {}) {
+    this.cwd = cwd;
+    this.maxLogLength = maxLogLength;
+    this.timeout = timeout;
+    this.taskSlug = taskSlug;
+    this.mode = mode;
+    this.profile = profile;
+    this.branchRecovery = branchRecovery;
+  }
+
+  runTask(task) {
+    const kind = inferTaskKind(task);
+    if (task.presetStatus) {
+      return { name: task.name, command: task.command, kind, status: task.presetStatus, exitCode: null, summary: task.summary, output: "" };
+    }
+    const result = spawnSync(task.command, {
+      cwd: this.cwd,
+      shell: true,
+      encoding: "utf8",
+      timeout: this.timeout
+    });
+    let status = result.status === 0 ? "PASS" : "FAIL";
+    let summary = status === "PASS" ? "Command completed successfully." : "Command failed.";
+    if (result.error?.code === "ETIMEDOUT") {
+      status = "BLOCKED";
+      summary = `Command timed out after ${this.timeout / 1000}s.`;
+    }
+    const rawOutput = `${result.stdout || ""}${result.stderr || ""}`.trim();
+    const output = rawOutput.length > this.maxLogLength ? `${rawOutput.slice(0, this.maxLogLength)}\n... [TRUNCATED]` : rawOutput;
+    return { name: task.name, command: task.command, kind, status, exitCode: result.status, signal: result.signal, summary, output };
+  }
+
+  async collect(tasks, { writeArtifact = false } = {}) {
+    const qualityGuard = new QualityGuard({ cwd: this.cwd, taskSlug: this.taskSlug, mode: this.mode, evidenceWillBePersisted: writeArtifact });
+    const implementation = qualityGuard.isImplementationTask();
+    const executableBehavior = await qualityGuard.hasExecutableBehaviorChanges();
+    const results = tasks.map((task) => this.runTask(task));
+    const policyValidation = await qualityGuard.verify();
+    const behaviorTests = results.filter((result) => result.kind === "test");
+    const passingBehaviorTest = behaviorTests.some((result) => result.status === "PASS");
+
+    let overallStatus = "PASS";
+    if (implementation && executableBehavior && tasks.length === 0) overallStatus = "BLOCKED";
+    else if (results.some((result) => ["FAIL", "BLOCKED", "FAIL_QUALITY_GATE"].includes(result.status))) overallStatus = "FAIL_QUALITY_GATE";
+    else if (executableBehavior && !passingBehaviorTest) overallStatus = "BLOCKED";
+    else if (["FAIL", "BLOCKED", "FAIL_QUALITY_GATE"].includes(policyValidation.overallStatus)) overallStatus = "FAIL_QUALITY_GATE";
+    else if (results.some((result) => result.status === "PASS_WITH_NOTES") || policyValidation.overallStatus === "PASS_WITH_NOTES") overallStatus = "PASS_WITH_NOTES";
+
+    const limitations = [];
+    if (implementation && executableBehavior && tasks.length === 0) limitations.push("No meaningful validation command was available for executable implementation work.");
+    if (executableBehavior && behaviorTests.length === 0) {
+      limitations.push("Executable behavior changed without a proportional automated behavior test. Build, lint, typecheck, smoke, screenshots, and manual review do not replace behavior tests.");
+    }
+    for (const [name, check] of Object.entries(policyValidation.checks || {})) {
+      if (check.status === "PASS_WITH_NOTES" && check.reason) limitations.push(`${name}: ${check.reason}`);
+    }
+
+    const evidence = {
+      timestamp: new Date().toISOString(),
+      taskSlug: this.taskSlug,
+      executionMode: this.mode,
+      workflowProfile: this.profile,
+      branchRecovery: this.branchRecovery,
+      branch: policyValidation.git?.branch || "unknown",
+      changedFiles: policyValidation.git?.changedFiles || [],
+      status: publicStatus(overallStatus),
+      internalStatus: overallStatus,
+      commands: results,
+      checks: policyValidation.checks,
+      limitations
+    };
+
+    if (writeArtifact) {
+      await fs.writeFile(path.join(this.cwd, "EVIDENCE.json"), JSON.stringify(evidence, null, 2));
+    }
+    return evidence;
+  }
+}
+
+export { inferTaskKind };

package/src/core/validation/quality-guard.js

@@ -0,0 +1,243 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const PROTECTED_BRANCHES = new Set(["main", "master"]);
+
+function normalizePath(file) {
+  return String(file || "").trim().replaceAll("\\", "/");
+}
+
+function parseStatusLine(line) {
+  const value = String(line || "");
+  const match = value.match(/^(?:[ MADRCU?!]{2}\s+|[MADRCU?!]\s+)(.+)$/);
+  if (!match) return "";
+  const candidate = match[1].trim();
+  const renamed = candidate.includes(" -> ") ? candidate.split(" -> ").at(-1) : candidate;
+  return normalizePath(renamed);
+}
+
+function isManagedChangePath(file = "") {
+  return /(^|\/)(node_modules|vendor|dist|coverage|\.cache)(\/|$)/.test(normalizePath(file));
+}
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export { parseStatusLine };
+
+/**
+ * QualityGuard verifies objective delivery safety. It does not grade prose or
+ * require ceremonial workflow files.
+ */
+export class QualityGuard {
+  constructor({ cwd, taskSlug = null, mode = null, evidenceWillBePersisted = false } = {}) {
+    this.cwd = cwd;
+    this.taskSlug = taskSlug;
+    this.mode = mode;
+    this._changedFiles = null;
+    this._hasHead = null;
+    this.evidenceWillBePersisted = evidenceWillBePersisted;
+  }
+
+  runGit(command) {
+    return execSync(command, {
+      cwd: this.cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+  }
+
+  hasGitHead() {
+    if (this._hasHead !== null) return this._hasHead;
+    try {
+      this.runGit("git rev-parse --verify HEAD");
+      this._hasHead = true;
+    } catch {
+      this._hasHead = false;
+    }
+    return this._hasHead;
+  }
+
+  getCurrentBranch() {
+    try {
+      return this.runGit("git branch --show-current") || "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+
+  getChangedFiles() {
+    if (this._changedFiles) return this._changedFiles;
+    const files = new Set();
+    try {
+      if (this.hasGitHead()) {
+        this.runGit("git diff --name-only HEAD")
+          .split("\n")
+          .map(normalizePath)
+          .filter(Boolean)
+          .forEach((file) => files.add(file));
+      }
+      this.runGit("git status --short --untracked-files=all")
+        .split("\n")
+        .map(parseStatusLine)
+        .filter(Boolean)
+        .filter((file) => !isManagedChangePath(file))
+        .forEach((file) => files.add(file));
+    } catch {
+      // A non-git consumer may still run validation commands. Branch safety is
+      // reported as unavailable rather than fabricated.
+    }
+    this._changedFiles = [...files].sort();
+    return this._changedFiles;
+  }
+
+  isDocsTask() {
+    const files = this.getChangedFiles();
+    return files.length > 0 && files.every((file) => file.endsWith(".md") || file.endsWith(".txt") || file.startsWith("docs/"));
+  }
+
+  isUiTask() {
+    return this.getChangedFiles().some((file) =>
+      /\.(tsx|jsx|vue|html|css|scss|less|blade\.php)$/.test(file) ||
+      /(^|\/)(components|pages|views)\//.test(file)
+    );
+  }
+
+  isImplementationTask() {
+    const files = this.getChangedFiles();
+    if (files.length === 0 || this.isDocsTask()) return false;
+    return files.some((file) =>
+      file === "package.json" ||
+      /^(src|app|pages|components|server|api)\//.test(file) ||
+      /\.(js|jsx|ts|tsx|vue|php|py|rb|go|java|css|scss|html)$/.test(file)
+    );
+  }
+
+
+  async hasExecutableBehaviorChanges() {
+    const files = this.getChangedFiles().filter((file) => !isManagedChangePath(file));
+    const executableExtensions = /\.(js|jsx|mjs|cjs|ts|tsx|vue|php|py|rb|go|java|cs|rs|swift|kt|kts|sh|bash)$/i;
+    if (files.some((file) => executableExtensions.test(file))) return true;
+
+    for (const file of files.filter((item) => /\.(html?|xhtml)$/i.test(item))) {
+      try {
+        const content = await fs.readFile(path.join(this.cwd, file), "utf8");
+        if (/<script\b|\son(?:click|change|input|submit|keydown|keyup|load|error)\s*=|javascript:/i.test(content)) return true;
+      } catch {
+        // Missing or unreadable changed files are handled by the normal validation path.
+      }
+    }
+    return false;
+  }
+
+  verifyBranchSafety() {
+    const branch = this.getCurrentBranch();
+    const implementation = this.isImplementationTask();
+    if (!this.hasGitHead()) {
+      return { status: "PASS_WITH_NOTES", branch, reason: "Git HEAD unavailable; branch safety could not be verified." };
+    }
+    if (implementation && PROTECTED_BRANCHES.has(branch)) {
+      return { status: "FAIL_QUALITY_GATE", branch, reason: `Implementation changes are present on protected branch '${branch}'.` };
+    }
+    return { status: "PASS", branch };
+  }
+
+  async verifyDocumentationNeed() {
+    if (!this.isImplementationTask()) return { status: "NOT_RUN", reason: "No implementation changes detected." };
+    const files = this.getChangedFiles();
+    const docsChanged = files.some((file) => file === "README.md" || file.startsWith("docs/") || file.endsWith(".md"));
+    const publicSurfaceChanged = files.some((file) =>
+      file === "package.json" ||
+      /(^|\/)(routes?|api|cli|commands?|config|public)\//.test(file) ||
+      /README|CHANGELOG/.test(file)
+    );
+    if (publicSurfaceChanged && !docsChanged) {
+      return { status: "PASS_WITH_NOTES", reason: "Public behavior may have changed without a documentation update." };
+    }
+    return { status: "PASS" };
+  }
+
+  async verifyUiEvidence() {
+    if (!this.isUiTask()) return { status: "NOT_RUN", reason: "Non-UI task." };
+    const candidates = ["docs", "screenshots", "evidence"];
+    const found = [];
+    for (const dir of candidates) {
+      const root = path.join(this.cwd, dir);
+      if (!(await exists(root))) continue;
+      const entries = await fs.readdir(root, { recursive: true }).catch(() => []);
+      for (const entry of entries) {
+        if (/\.(png|jpe?g|webp)$/i.test(String(entry))) found.push(normalizePath(path.join(dir, String(entry))));
+      }
+    }
+    return found.length
+      ? { status: "PASS", screenshots: found.slice(0, 20) }
+      : { status: "PASS_WITH_NOTES", reason: "UI changed without persisted screenshots; rely on the stated browser/manual review only if it actually occurred." };
+  }
+
+  async verifyFullModeEvidence() {
+    if (this.mode !== "full") return { status: "NOT_RUN", reason: "Persisted evidence is optional outside full mode." };
+    if (this.evidenceWillBePersisted) return { status: "PASS", reason: "Collector will persist observed full-mode evidence." };
+    const candidates = [
+      path.join(this.cwd, "EVIDENCE.json"),
+      this.taskSlug ? path.join(this.cwd, "docs/workflows", this.taskSlug, "evidence.json") : null
+    ].filter(Boolean);
+    for (const file of candidates) {
+      if (await exists(file)) return { status: "PASS", file: path.relative(this.cwd, file) };
+    }
+    return { status: "FAIL_QUALITY_GATE", reason: "Full mode requires persisted evidence generated from observed execution." };
+  }
+
+  verifyTruthfulnessBoundary() {
+    if (!this.isUiTask()) return { status: "NOT_RUN", reason: "Non-UI task." };
+    return {
+      status: "NOT_RUN",
+      reason: "Product truthfulness requires semantic review; keyword matching is intentionally not used as proof."
+    };
+  }
+
+  async verify() {
+    const branchSafety = this.verifyBranchSafety();
+    const documentation = await this.verifyDocumentationNeed();
+    const uiEvidence = await this.verifyUiEvidence();
+    const fullModeEvidence = await this.verifyFullModeEvidence();
+    const productTruthfulness = this.verifyTruthfulnessBoundary();
+
+    // productTruthfulness is intentionally excluded from the blocking checks array.
+    // Semantic truthfulness cannot be verified by keyword matching; it always returns
+    // NOT_RUN by design. It appears in the output as an observational signal for
+    // human reviewers, but never affects overallStatus.
+    const checks = [branchSafety, documentation, uiEvidence, fullModeEvidence];
+    let overallStatus = "PASS";
+    if (checks.some((check) => ["FAIL", "FAIL_QUALITY_GATE", "BLOCKED"].includes(check.status))) {
+      overallStatus = "FAIL_QUALITY_GATE";
+    } else if (checks.some((check) => check.status === "PASS_WITH_NOTES")) {
+      overallStatus = "PASS_WITH_NOTES";
+    }
+
+    return {
+      overallStatus,
+      isUiTask: this.isUiTask(),
+      isDocsTask: this.isDocsTask(),
+      isImplementationTask: this.isImplementationTask(),
+      git: {
+        hasHead: this.hasGitHead(),
+        branch: this.getCurrentBranch(),
+        changedFiles: this.getChangedFiles()
+      },
+      checks: {
+        branchSafety,
+        documentation,
+        uiEvidence,
+        fullModeEvidence,
+        productTruthfulness
+      }
+    };
+  }
+}