@williambeto/ai-workflow 1.19.1 → 2.1.0

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
+      }
+    };
+  }
+}

package/src/core/workflow-profiles.js

@@ -0,0 +1,107 @@
+const PROFILE_DEFINITIONS = Object.freeze({
+  "frontend-product": Object.freeze({
+    owner: "Astra",
+    skills: ["frontend-development", "ui-ux-design"],
+    objective: "Deliver a user-facing product or marketing surface with truthful copy and deliberate visual composition.",
+    requiredChecks: ["tests", "typecheck", "build", "responsive-render", "primary-interaction", "truthfulness"],
+    forbiddenAssumptions: ["fixed SaaS section sequence", "mandatory pricing", "mandatory testimonials", "subjective premium score"]
+  }),
+  "frontend-utility": Object.freeze({
+    owner: "Astra",
+    skills: ["frontend-development", "ui-ux-design"],
+    objective: "Deliver a focused user tool with a complete primary flow and clear operational states.",
+    requiredChecks: ["tests", "typecheck", "build", "responsive-render", "primary-interaction"],
+    forbiddenAssumptions: ["marketing sections", "pricing", "testimonials", "commercial narrative"]
+  }),
+  "backend-api": Object.freeze({
+    owner: "Astra",
+    skills: ["backend-development"],
+    objective: "Deliver a bounded backend/API change with validated contracts, errors, authorization, and tests.",
+    requiredChecks: ["tests", "build-or-typecheck", "input-validation", "failure-paths"],
+    forbiddenAssumptions: ["frontend deliverables", "visual evidence"]
+  }),
+  refactor: Object.freeze({
+    owner: "Astra",
+    skills: ["refactoring"],
+    objective: "Improve structure without changing observable behavior outside the approved scope.",
+    requiredChecks: ["behavior-preservation", "tests", "focused-diff"],
+    forbiddenAssumptions: ["new product behavior", "unrelated cleanup"]
+  }),
+  documentation: Object.freeze({
+    owner: "Astra",
+    skills: ["documentation"],
+    objective: "Create or update accurate documentation grounded in the current repository behavior.",
+    requiredChecks: ["references", "paths", "commands", "consistency"],
+    forbiddenAssumptions: ["implementation claims without evidence"]
+  }),
+  "security-review": Object.freeze({
+    owner: "Sage",
+    skills: ["qa-workflow", "technical-leadership"],
+    objective: "Inspect security-relevant behavior and report evidence-ranked findings without implementing unrelated changes.",
+    requiredChecks: ["evidence", "severity", "runtime-vs-dev", "remediation-owner"],
+    forbiddenAssumptions: ["automatic force fixes", "unverified exploitability"]
+  }),
+  generic: Object.freeze({
+    owner: "Atlas",
+    skills: [],
+    objective: "Route work without inventing domain requirements.",
+    requiredChecks: ["scope", "owner", "mode"],
+    forbiddenAssumptions: ["domain-specific structure"]
+  })
+});
+
+/**
+ * NOTE: requiredChecks are advisory, not programmatically enforced.
+ *
+ * Each profile's `requiredChecks` array is informational — it guides agent behaviour,
+ * informs the handoff document, and communicates domain expectations to the AI.
+ * QualityGuard and EvidenceCollector do NOT iterate requiredChecks to block delivery.
+ *
+ * The rationale: profile-specific checks (e.g. "responsive-render", "primary-interaction")
+ * are context-dependent and require human or agent judgement. Automated enforcement
+ * would require domain-specific validators that don't currently exist.
+ *
+ * If you add automated enforcement for a profile check, update this comment.
+ */
+
+const PROFILE_PATTERNS = Object.freeze([
+  ["security-review", /\b(?:security review|security audit|vulnerability audit|threat model)\b/i],
+  ["refactor", /\b(?:refactor|restructure|cleanup without behavior change|preserve behavior)\b/i],
+  ["documentation", /\b(?:documentation only|write docs|update readme|document the|documentation task)\b/i],
+  ["backend-api", /\b(?:api endpoint|backend api|rest api|graphql|controller|service endpoint|authenticated api)\b/i],
+  ["frontend-product", /\b(?:landing page|marketing page|product page|pricing page|homepage|redesign|brand page)\b/i],
+  ["frontend-utility", /\b(?:validator|search page|lookup|dashboard|form|calculator|tool|admin page|repository search)\b/i]
+]);
+
+export function getWorkflowProfile(name = "generic") {
+  return PROFILE_DEFINITIONS[name] || PROFILE_DEFINITIONS.generic;
+}
+
+export function listWorkflowProfiles() {
+  return Object.keys(PROFILE_DEFINITIONS);
+}
+
+export function resolveWorkflowProfile({ request = "", explicitProfile = null } = {}) {
+  if (explicitProfile && PROFILE_DEFINITIONS[explicitProfile]) return explicitProfile;
+  const text = String(request).trim();
+  for (const [profile, pattern] of PROFILE_PATTERNS) {
+    if (pattern.test(text)) return profile;
+  }
+  return "generic";
+}
+
+export function buildCompactProfileHandoff({ profile, objective, requirements = [], constraints = [] }) {
+  const selected = getWorkflowProfile(profile);
+  const unique = (values) => [...new Set(values.filter(Boolean))];
+  return {
+    profile,
+    owner: selected.owner,
+    skills: [...selected.skills],
+    objective: objective || selected.objective,
+    requirements: unique(requirements),
+    constraints: unique(constraints),
+    requiredChecks: [...selected.requiredChecks]
+  };
+}
+
+export { PROFILE_DEFINITIONS };

package/.agents/napkin.md

@@ -1,89 +0,0 @@
-# Project Napkin Memory
-
-## Purpose
-
-This file stores durable, reusable project memory for `ai-workflow`.
-
-It captures recurring corrections and stable operational rules that should survive across sessions.
-
-## Usage rules
-
-- Read at relevant task start when work depends on repository structure, workflow rules, validation behavior, or recurring conventions.
-- Apply progressive disclosure: use only entries relevant to the current task.
-- Add entries only when guidance is durable and reusable.
-- Do not store secrets, credentials, tokens, private keys, or personal/environment-sensitive data.
-- Do not use this file as a temporary notes dump or task timeline log.
-
-## Current durable project memory
-
-### [2026-05-11] Workflow: Keep pull requests small and reviewable
-
-- Instead of: Combining multiple workflow phases or unrelated refactors in one change.
-- Do: Implement one scoped PR-sized unit at a time and preserve no-regression behavior.
-- Evidence/source: `AGENTS.md` hard constraints and primary workflow.
-
-### [2026-05-11] Validation: Run full repository validation before closing work
-
-- Instead of: Assuming docs or script edits are safe without full validation.
-- Do: Run `npm run validate` and report command evidence in the final output.
-- Evidence/source: `AGENTS.md` evidence requirements and validation rules.
-
-### [2026-05-11] Skill design: Keep skills portable and lightweight
-
-- Instead of: Embedding heavy repo-specific logic directly into each skill.
-- Do: Keep skills operational, concise, and reusable across real project contexts.
-- Evidence/source: `AGENTS.md` repository context and specialist skill guidance.
-
-### [2026-05-11] Skill structure: Every skill directory needs `SKILL.md`
-
-- Instead of: Treating a skill directory as valid without its required definition file.
-- Do: Ensure each `.agents/skills/*` directory contains `SKILL.md`.
-- Evidence/source: `scripts/validate-skills.mjs` dynamic directory check.
-
-### [2026-05-11] Validation quality: Do not allow incomplete skills to pass
-
-- Instead of: Passing validation when required skill files are missing.
-- Do: Fail validation for missing skill files and treat it as a blocking issue.
-- Evidence/source: `scripts/validate-skills.mjs` failure behavior and repo quality gates.
-
-### [2026-05-11] Review quality: Prefer evidence-based findings
-
-- Instead of: Reporting vague findings without concrete references.
-- Do: Include file paths and command output in findings and validation summaries.
-- Evidence/source: `AGENTS.md` evidence requirements and finding model.
-
-### [2026-05-12] Token economy: Caveman mode does not auto-pass to delegated agents
-
-- Instead of: Activating `/caveman` and assuming all delegated agents stay compact.
-- Do: Each new agent context loads fresh without caveman compression unless the delegation packet explicitly requests it.
-- Do: When delegating, include in the handoff packet: "Use compact output — caveman mode active."
-- Do: For multi-agent chains (planner → implementer → reviewer), activate token-economy + minimal-context in each agent's Required context or delegation contract.
-- Evidence/source: `AGENTS.md` anti-overdelegation rules, `minimal-context` skill, `token-economy` skill.
-
-### [2026-05-13] Phase 8: Codex parity complete — all PRs merged
-
-- Instead of: Leaving Codex users without guided orchestration or debugging entrypoints.
-- Do: After any audit that identifies gaps, create a Phase in ROADMAP.md and deliver PRs sequentially with validation at each step.
-- Do: Mark each Phase as `[x]` in ROADMAP when complete, update status line, and update "next recommended PR".
-- Evidence/source: ROADMAP.md Phase 8 — 6 PRs delivered (orchestrate-next.md, fix-issue.md, deploy.md, autopilot→orchestrator fixes, README tree, AGENTS.md note). PR #89 merged. 9/9 validate checks.
-
-### [2026-05-13] Audit: Napkin works for both Codex and OpenCode
-
-- Instead of: Worrying that Napkin might be tool-specific or only work for OpenCode.
-- Do: Trust that Napkin is fully shared — same file, same skill, same format for both Codex and OpenCode.
-- Do: After any audit or significant workflow change, update Napkin if a durable lesson was confirmed.
-- Evidence/source: `.agents/napkin.md` audit 2026-05-13 — SKILL.md passes validate:skills for both tools; progressive disclosure documented; 0 secrets; 8 valid entries.
-
-### [2026-05-14] Release hygiene: update `package.json` before release
-
-- Instead of: Creating a release tag without aligning repository version metadata.
-- Do: Update `package.json` version before creating a release.
-- Do: Keep version, tag, and release notes aligned so release automation and changelog extraction stay consistent.
-- Evidence/source: `release.yml` extracts notes by tag version; release flow consistency depends on matching semver across tags and project metadata.
-
-### [2026-05-23] Documentation language: English only for repository docs
-
-- Instead of: Adding or keeping Portuguese (or mixed-language) content in official documentation files.
-- Do: Write and maintain all repository documentation in English by default.
-- Do: Apply this rule to docs, runbooks, prompts, specs, and policy files unless a file explicitly declares a localization scope.
-- Evidence/source: User directive in session (2026-05-23) and consistency requirement for public developer experience.