@williambeto/ai-workflow 1.19.0 → 2.1.0

package/src/core/sdd/validator.js

@@ -0,0 +1,67 @@
+import fs from "node:fs/promises";
+
+/**
+ * SpecValidator - Enforces "No Spec, No Code" rule.
+ * Validates existence, structure, and approval status of specifications.
+ */
+export class SpecValidator {
+  /**
+   * Validates a specification file.
+   * @param {string} filePath - Path to the .md specification file.
+   * @returns {Promise<{valid: boolean, reason?: string, tier?: string}>}
+   */
+  async validate(filePath) {
+    try {
+      const content = await fs.readFile(filePath, "utf8");
+
+      // Check for tiered tier identification
+      let tier = "unknown";
+      if (content.includes("[DEEP]")) tier = "deep";
+      else if (content.includes("[STANDARD]")) tier = "standard";
+      else if (content.includes("[TINY]")) tier = "tiny";
+
+      if (tier === "unknown") {
+        return { valid: false, reason: "Specification tier [DEEP|STANDARD|TINY] not identified in title." };
+      }
+
+      // Check for Metadata section
+      if (!content.includes("## Metadata")) {
+        return { valid: false, reason: "Missing '## Metadata' section.", tier };
+      }
+
+      // Check for Acceptance Criteria section
+      if (!content.includes("## Acceptance Criteria")) {
+        return { valid: false, reason: "Missing '## Acceptance Criteria' section.", tier };
+      }
+
+      // Check for Approved status
+      const lines = content.split("\n");
+      const statusLine = lines.find(l => l.includes("Status:"));
+      
+      if (!statusLine) {
+        return { valid: false, reason: "Missing Status field in Metadata section.", tier };
+      }
+
+      const statusPart = statusLine.split(":")[1]
+        .replace(/[\*_]/g, "") // Remove bold/italic markers
+        .trim()
+        .toUpperCase();
+      
+      // If it contains multiple options separated by |, it's not approved yet
+      if (statusPart.includes("|")) {
+        return { valid: false, reason: "Specification status is a template list. Must be explicitly set to 'APPROVED'.", tier };
+      }
+
+      if (statusPart !== "APPROVED") {
+        return { valid: false, reason: `Specification status is '${statusPart}', but must be 'APPROVED' to proceed.`, tier };
+      }
+
+      return { valid: true, tier };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return { valid: false, reason: `Specification file not found: ${filePath}` };
+      }
+      return { valid: false, reason: `Error reading specification: ${error.message}` };
+    }
+  }
+}

package/src/core/statuses.js

@@ -0,0 +1,29 @@
+export const COMPLETION_STATUSES = Object.freeze([
+  "PASS",
+  "PASS_WITH_NOTES",
+  "FAIL_DELEGATION_GATE",
+  "FAIL_QUALITY_GATE",
+  "FAIL",
+  "BLOCKED",
+  "NOT_RUN"
+]);
+
+export const RECOVERABLE_GATE_STATUSES = Object.freeze([
+  "FAIL_DELEGATION_GATE",
+  "FAIL_QUALITY_GATE"
+]);
+
+export const TERMINAL_FAILURE_STATUSES = Object.freeze([
+  "FAIL",
+  "BLOCKED"
+]);
+
+export function isRecoverableGateFailure(status) {
+  return RECOVERABLE_GATE_STATUSES.includes(status);
+}
+
+export function isTerminalFailure(status) {
+  return TERMINAL_FAILURE_STATUSES.includes(status);
+}
+
+export const COMPLETION_STATUS_TEXT = COMPLETION_STATUSES.join(" | ");

package/src/core/symlink-layout.js

@@ -0,0 +1,93 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function normalize(p) {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * For v3.0.0 "Elite Governance", we want an ULTRA-CLEAN root.
+ * Only "opencode" is symlinked to the root (required for OpenCode discovery).
+ * All other assets stay inside .ai-workflow/.
+ */
+const LINKABLE_ROOTS = new Set([
+  "opencode",
+  ".agents"
+]);
+
+const LINKABLE_FILES = new Set([]);
+
+export function buildSymlinkEntries({ templateFiles, installRoot = ".ai-workflow" }) {
+  const entries = new Map();
+
+  for (const relativePath of Object.keys(templateFiles)) {
+    if (relativePath === "opencode.jsonc") continue;
+
+    const normalized = normalize(relativePath);
+
+    if (LINKABLE_FILES.has(normalized)) {
+      entries.set(normalized, `${installRoot}/${normalized}`);
+      continue;
+    }
+
+    // Match composite paths in LINKABLE_ROOTS (e.g., "docs/policies")
+    for (const rootPath of LINKABLE_ROOTS) {
+      if (normalized === rootPath || normalized.startsWith(`${rootPath}/`)) {
+        entries.set(rootPath, `${installRoot}/${rootPath}`);
+        break;
+      }
+    }
+  }
+
+  return Array.from(entries.entries()).map(([linkPath, targetPath]) => ({ linkPath, targetPath }));
+}
+
+export async function isSymlinkTo(absoluteLinkPath, absoluteTargetPath) {
+  try {
+    const stat = await fs.lstat(absoluteLinkPath);
+    if (!stat.isSymbolicLink()) return false;
+    const currentTarget = await fs.readlink(absoluteLinkPath);
+    const resolved = path.resolve(path.dirname(absoluteLinkPath), currentTarget);
+    return resolved === absoluteTargetPath;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Internal symlink to satisfy opencode.jsonc paths without polluting the root.
+ * Creates .ai-workflow/opencode/skills -> ../.agents/skills
+ */
+export async function setupInternalSymlinks(cwd, installRoot = ".ai-workflow") {
+  const skillsLink = path.join(cwd, installRoot, "opencode/skills");
+  const skillsTarget = path.join(cwd, installRoot, ".agents/skills");
+
+  if (!(await exists(skillsTarget))) return;
+
+  try {
+    const stat = await fs.lstat(skillsLink).catch(() => null);
+    if (stat) {
+      if (stat.isSymbolicLink()) {
+        const current = await fs.readlink(skillsLink);
+        if (current === "../.agents/skills") return;
+        await fs.unlink(skillsLink);
+      } else {
+        return; // File exists, skip
+      }
+    }
+
+    const type = process.platform === "win32" ? "junction" : "dir";
+    await fs.symlink("../.agents/skills", skillsLink, type);
+  } catch {
+    // Silent fail for internal symlink
+  }
+}
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/templates.js

@@ -0,0 +1,218 @@
+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 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 };