@williambeto/ai-workflow 2.4.3 → 2.4.6

package/AGENTS.md

@@ -11,6 +11,8 @@ Deliver useful software through proportionate workflow, minimum diff, observed v
 - Run existing relevant validation commands.
 - Never report success after failed or unavailable required validation.
 - Bound remediation and stop when no progress is made.
+- Always await explicit conversational authorization from the human user in the chat before executing any codebase modification, Git commit, tagging, or remote push. Automated system approval hooks (e.g., artifact reviews) do not bypass this human-in-the-loop requirement.
+- Remote push is only permitted on non-protected feature/maintenance branches (e.g. feat/*, fix/*, chore/*, docs/*) with explicit conversational authorization, and is strictly prohibited on protected branches like main or master.
 
 ## Routing & Delegation
 

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [2.4.5] - 2026-06-24
+
+### Changed
+- Refined Design System token validation to support both CSS custom property declarations and usages via `var()`, reducing false-positive quality gate blocks on minor style adjustments.
+- Flexibilized `git push` policy to allow remote pushes to non-protected feature/maintenance branches upon explicit human authorization in the chat, keeping `main` and `master` branches strictly protected.
+
+## [2.4.4] - 2026-06-24
+
+### Added
+- Added `clean` CLI command (`aw clean`) to cleanly de-initialize and remove AI Workflow files and symlinks from a project.
+- Translated all E2E test titles and comments in the codebase to English for consistent localization.
+
 ## [2.4.3] - 2026-06-24
 
 ### Added

package/dist-assets/AGENTS.md

@@ -11,10 +11,12 @@ Deliver useful software through proportionate workflow, minimum diff, observed v
 - Run existing relevant validation commands.
 - Never report success after failed or unavailable required validation.
 - Bound remediation and stop when no progress is made.
+- Always await explicit conversational authorization from the human user in the chat before executing any codebase modification, Git commit, tagging, or remote push. Automated system approval hooks (e.g., artifact reviews) do not bypass this human-in-the-loop requirement.
+- Remote push is only permitted on non-protected feature/maintenance branches (e.g. feat/*, fix/*, chore/*, docs/*) with explicit conversational authorization, and is strictly prohibited on protected branches like main or master.
 
 ## Routing & Delegation
 
-Atlas routes. Astra implements substantial scoped work. Sage independently validates when risk or full mode justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
+Atlas routes. Nexus owns discovery, requirements, and spec authoring. Orion owns planning, PR sequencing, and release strategy. Astra implements substantial scoped work. Sage independently validates when risk or full mode justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
 
 ## Modes
 
@@ -25,3 +27,8 @@ Atlas routes. Astra implements substantial scoped work. Sage independently valid
 ## Evidence
 
 Quick and standard work require only branch, changed areas, commands/results, and limitations in the handoff. Full/release/audit/security work may persist machine-generated evidence.
+
+## Core Concept
+
+AI Workflow is an npm CLI that installs agents, commands, skills, policies and templates into your repository.
+It guides coding agents from request to implementation, validation and evidence. AI Workflow Kit preserves workflow integrity so coding agents cannot skip from request to code to success without an explicit implementation path, proportional validation, and final evidence.

package/dist-assets/agents/astra.md

@@ -56,7 +56,7 @@ Astra implements only after branch gate is satisfied. It keeps changes bounded t
 * Silent scope expansion.
 * Skipping validation.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Running production deployment tools.
 

package/dist-assets/agents/atlas.md

@@ -59,7 +59,7 @@ Atlas must:
 * Implement feature code directly when Astra should execute.
 * Validate its own implementation as final evidence.
 * `npm publish`
-* `git push`
+* `git push` to protected branches (main, master), or to remote without explicit user approval in the chat.
 * `git tag`
 * `gh release create`
 * `gh repo create`

package/dist-assets/agents/nexus.md

@@ -47,7 +47,7 @@ Nexus must inspect project structure, identify stack, entry points, scripts, con
 * Modifying files during discovery.
 * Writing codebase changes or creating code files.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Bypassing safety gates or routing rules.
 * Inventing project details without evidence.

package/dist-assets/agents/phoenix.md

@@ -50,7 +50,7 @@ Phoenix acts only on concrete findings, identifies root cause, applies the small
 * Fixing issues without a concrete finding.
 * Rewriting unrelated code blocks.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Bypassing safety gates, branch gates, or validation gates.
 

package/dist-assets/agents/sage.md

@@ -48,7 +48,7 @@ Sage validates implementation evidence independently, classifies risk, runs or i
 * Writing new features.
 * Accepting claims without command output or logs.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Bypassing quality gates, branch gates, or validation gates.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.4.3",
+  "version": "2.4.6",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",

package/src/cli.js

@@ -4,6 +4,7 @@ import { runDoctor } from "./commands/doctor.js";
 import { runCollectEvidence } from "./commands/collect-evidence.js";
 import { runMasterOrchestrator } from "./commands/run.js";
 import { runExecute } from "./commands/execute.js";
+import { runClean } from "./commands/clean.js";
 
 function printHelp() {
   console.log(`ai-workflow
@@ -15,6 +16,7 @@ Usage:
   ai-workflow validate [--a11y] [--visual-dist=<path>] [--port=<port>]
   ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run] [--visual-dist=<path>] [--port=<port>]
   ai-workflow doctor
+  ai-workflow clean [--yes] [--dry-run] [--purge-agents]
 
 Commands:
   execute           Orchestrate execution of a natural request through the state machine
@@ -22,6 +24,7 @@ Commands:
   init              Install AI workflow defaults (OpenCode). --profile=standard (default) or --profile=full (adds examples)
   collect-evidence  Run observed project validation; persists EVIDENCE.json only for full mode
   doctor            Verify local ai-workflow installation
+  clean             De-initialize and remove AI Workflow files and symlinks from the project
 `);
 }
 
@@ -58,7 +61,8 @@ function parseFlags(args) {
     request: requestArg ? requestArg.replace("--request=", "") : undefined,
     visualDist: visualDistArg ? visualDistArg.replace("--visual-dist=", "") : undefined,
     port: portArg ? portArg.replace("--port=", "") : undefined,
-    a11y: args.includes("--a11y")
+    a11y: args.includes("--a11y"),
+    purgeAgents: args.includes("--purge-agents") || args.includes("--purge")
   };
 }
 
@@ -139,5 +143,13 @@ export async function runCli(args) {
     return;
   }
 
+  if (command === "clean") {
+    await runClean({
+      cwd: process.cwd(),
+      ...parseFlags(args.slice(1))
+    });
+    return;
+  }
+
   throw new Error(`unknown command: ${command}`);
 }

package/src/commands/clean.js

@@ -0,0 +1,106 @@
+import { existsSync, rmSync, lstatSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import readline from "node:readline";
+
+function askConfirmation(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function isSymlink(filePath) {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch (_) {
+    return false;
+  }
+}
+
+export async function runClean({ cwd, yes = false, dryRun = false, purgeAgents = false }) {
+  const targets = [
+    ".ai-workflow",
+    "opencode.jsonc",
+    ".workflow-state.json",
+    "opencode"
+  ];
+
+  const hasAgents = existsSync(join(cwd, ".agents"));
+
+  // Check what actually exists
+  const existingTargets = targets
+    .map(name => join(cwd, name))
+    .filter(path => existsSync(path) || isSymlink(path));
+
+  if (existingTargets.length === 0 && (!hasAgents || !purgeAgents)) {
+    console.log("No AI Workflow configuration or files found in the current project.");
+    return;
+  }
+
+  console.log("\n[AI WORKFLOW] De-initialization");
+  console.log("===============================");
+
+  if (dryRun) {
+    console.log("[DRY RUN] The following items would be deleted:");
+    existingTargets.forEach(path => console.log(`  - ${path}`));
+    if (hasAgents && purgeAgents) {
+      console.log(`  - ${join(cwd, ".agents")} (customizations folder)`);
+    } else if (hasAgents) {
+      console.log(`  - NOTE: ${join(cwd, ".agents")} exists but will NOT be deleted (run with --purge-agents to delete)`);
+    }
+    return;
+  }
+
+  // Interactive prompts if --yes / -y is not passed
+  if (!yes) {
+    if (!process.stdin.isTTY) {
+      console.log("Error: Non-interactive terminal detected. Run with --yes to bypass confirmation.");
+      if (process.env.NODE_ENV === "test") {
+        // Allow tests to bypass TTY block if they mock/stub process.stdin
+      } else {
+        process.exit(1);
+      }
+    }
+
+    const confirmDeinit = await askConfirmation("Are you sure you want to de-initialize AI Workflow from the project? [y/N] ");
+    if (confirmDeinit !== "y" && confirmDeinit !== "yes") {
+      console.log("Aborted.");
+      return;
+    }
+
+    if (hasAgents && !purgeAgents) {
+      const confirmPurge = await askConfirmation("A custom '.agents' folder was detected. Do you want to purge it (this deletes custom prompts/rules/skills)? [y/N] ");
+      if (confirmPurge === "y" || confirmPurge === "yes") {
+        purgeAgents = true;
+      }
+    }
+  }
+
+  // Add .agents if requested and exists
+  if (purgeAgents && hasAgents) {
+    existingTargets.push(join(cwd, ".agents"));
+  }
+
+  console.log("\nRemoving files...");
+  for (const target of existingTargets) {
+    try {
+      if (isSymlink(target)) {
+        unlinkSync(target);
+        console.log(`Deleted symlink: ${target}`);
+      } else {
+        rmSync(target, { recursive: true, force: true });
+        console.log(`Deleted directory/file: ${target}`);
+      }
+    } catch (error) {
+      console.error(`Failed to delete ${target}: ${error.message}`);
+    }
+  }
+
+  console.log("\nAI Workflow has been successfully removed from this project.");
+}

package/src/core/validation/artifact-fidelity-gate.js

@@ -392,19 +392,26 @@ export class ArtifactFidelityGate {
       }
     }
 
-    // 1. Tokens CSS mínimos Check
+    // 1. Minimum CSS tokens check
+    // Option D: only enforce when CSS volume is substantial (>200 chars of effective rules)
+    // and bypass is available via explicit approval token 'no-css-vars' or 'css-vars-bypass'.
     const hasRules = cssContentCombined.includes("{");
-    const hasCssVars = /--[a-zA-Z0-9_-]+\s*:/g.test(cssContentCombined);
-    if (hasRules && !hasCssVars) {
-      violations.push("Fidelity Violation: Design System token mismatch. No CSS custom properties (variables) detected in changed UI stylesheets.");
+    const cssVarsApproved = (this.explicitApprovals || []).some(app =>
+      /no-css-vars|css-vars-bypass/i.test(app)
+    );
+    const cssRulesContent = cssContentCombined.replace(/\/\*[\s\S]*?\*\//g, "").trim();
+    const isSubstantialCss = cssRulesContent.length > 200;
+    const hasCssVars = /(--[a-zA-Z0-9_-]+\s*:|var\(--[a-zA-Z0-9_-]+\))/g.test(cssContentCombined);
+    if (hasRules && isSubstantialCss && !hasCssVars && !cssVarsApproved) {
+      violations.push("Fidelity Violation: Design System token mismatch. No CSS custom properties (variables) detected or used in changed UI stylesheets. Add explicit approval 'no-css-vars' to bypass this check for simple or legacy stylesheets.");
     }
 
-    // 2. Excesso de style="..."
+    // 2. Excessive style="..." inline styles check
     if (styleAttrsCount > 5) {
       violations.push(`Fidelity Violation: excessive inline styles detected (${styleAttrsCount} style="..." declarations). Use CSS classes or utility classes instead.`);
     }
 
-    // 3. HTML principal tags semânticas básicas Check
+    // 3. Main HTML semantic tags check
     if (htmlContentCombined.length > 0) {
       const hasSemanticTags = /<(header|main|footer|nav|section)\b/i.test(htmlContentCombined);
       const hasH1 = /<h1\b/i.test(htmlContentCombined);