@williambeto/ai-workflow 2.2.7 → 2.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.3.0] - 2026-06-16
+
+### Added
+- Isolated read-only workspace runner to prevent execution modifications from altering the original repository.
+- Sage validation agent execution in full/deep task mode, logging events to the ledger and handling revalidation.
+- Real OpenCode smoke test integration inside the `release:verify` suite.
+- Scenario 17 in E2E tests verifying the complete multi-agent coordination loop (`Astra -> Sage -> Phoenix -> Sage`).
+
+### Fixed
+- Sequential state transitions for read-only runs (`IMPLEMENTING -> IMPLEMENTED -> VALIDATING -> COMPLETED`).
+- Snapshot comparison logic to correctly target `.snapshot.files` and compare `.sha256` properties.
+- Bypassed physical writing of ledger histories and handoff markdown files during read-only executions.
+- Injected mock OpenCode environment configuration inside `verify-packed-consumer.mjs` for autonomous sandbox runs.
+
 ## [2.0.5] - 2026-06-08
 
 ### Fixed

package/dist-assets/docs/cli-reference.md

@@ -1,24 +1,52 @@
 # CLI reference
 
-## `ai-workflow init`
+## `ai-workflow execute`
 
-Installs the OpenCode-first workflow assets into a consumer project.
+Orchestrate execution of a natural request through the state machine.
 
-## `ai-workflow doctor`
+| Flag | Description |
+| --- | --- |
+| `--task=<slug>` | Optional custom task slug for the workflow execution. |
+| `--request=<request>` | Positional or named natural language request. |
 
-Checks the local installation and generated configuration.
-
-## `ai-workflow run --spec-path=<path>`
+## `ai-workflow run`
 
 Runs formal orchestration for an approved specification. It enforces branch safety, observed validation, bounded remediation, and handoff generation.
 
-## `ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]`
+| Flag | Description |
+| --- | --- |
+| `--spec-path=<path>` | Path to the approved specification file. |
+
+## `ai-workflow init`
+
+Installs the OpenCode-first workflow assets into a consumer project.
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | Auto-approve all confirmations. |
+| `--force` | Force overwrite existing files. |
+| `--dry-run` | Print actions without applying changes. |
+| `--no-install` | Skip installing dependencies. |
+| `--no-overwrite` | Do not overwrite existing files. |
+| `--gemini` | Install Gemini-specific configurations. |
+| `--claude` | Install Claude-specific configurations. |
+| `--codex` | Install Codex-specific configurations. |
+| `--antigravity` | Install Antigravity-specific configurations. |
+| `--profile=<profile>` | Specify installation profile (e.g. `standard`, `full`). |
+
+## `ai-workflow collect-evidence`
 
 Runs relevant project validation scripts and objective quality checks.
 
-- quick/standard: prints a concise delivery summary and does not require `EVIDENCE.json`;
-- full: persists `EVIDENCE.json` unless `--dry-run` is used;
-- failed or unavailable required validation returns `BLOCKED`.
+| Flag | Description |
+| --- | --- |
+| `--task=<slug>` | Optional task slug to target. |
+| `--mode=<mode>` | Validation mode (`quick`, `standard`, `full`). |
+| `--dry-run` | Run checks without writing `EVIDENCE.json`. |
+
+## `ai-workflow doctor`
+
+Checks the local installation and generated configuration.
 
 ## Public states
 

package/docs/releases/v2.3.0-release-decision.md

@@ -0,0 +1,35 @@
+# AI Workflow Kit 2.3.0 Release Decision
+
+**Status:** Finalized  
+**npm publish:** Pending (Awaiting user authorization)  
+**Published dist-tag:** `latest`  
+
+## Identity
+
+- **Package:** `@williambeto/ai-workflow`
+- **Version:** `2.3.0`
+- **Commit:** `c16d06889ed4957840b69d61df43063908c3b220`
+- **Tarball SHA256:** `24b1cb412bb4503add8d8962568cdc5ea819e207e6dd0d0e3d0f9d8502c063ce`
+- **Previous public line:** `2.2.7`
+
+## Validation evidence
+
+- **Unit tests:** PASS — 142 tests passed
+- **E2E tests:** PASS — 18 tests passed (including the new read-only safety validation and Sage/Phoenix/Astra loop verification)
+- **Release-readiness validation:** PASS — 17 required files checked
+- **Full validation:** PASS — 18/18 checks completed successfully (JSON, Cross-reference, Artifact safety, External link, Documentation consistency, Workflow state, Schema, Skill, Canonical policy reference, Privacy publication gate, UI evidence gate, Delegation, Behavioral contract, Token economy, Upgrade regression, Visual regression, Release readiness, Repository structure)
+- **Safe pack:** PASS — `@williambeto/ai-workflow@2.3.0`, 310 files, zero root-level tarballs left behind
+- **Fresh consumer install:** PASS (verified via packed consumer runner in a sandbox)
+- **CLI help/init/doctor:** PASS (verified via packed consumer runner in a sandbox)
+- **Real OpenCode Smoke Test:** PASS (integrated directly into the release verification)
+- **Open Blocker/High findings:** None
+
+## Accepted limitations
+
+- See [known-limitations.md](../internal/known-limitations.md).
+
+## Decision
+
+Decision finalized for version `2.3.0`. The release includes the isolated read-only workspace runner, corrected snapshot comparisons, bypassed physical files write during read-only executions, real OpenCode smoke test integration in release verification, and Sage validation agent coordination in full mode.
+
+**Approved by:** José Willams (Human User)

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.2.7",
+  "version": "2.3.0",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
   "type": "module",
   "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "engines": {
     "node": ">=20.11"
   },
@@ -34,7 +38,9 @@
     "PUBLISH_MANIFEST.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "read_only_safety_verification.md",
+    "docs/releases/v2.3.0-release-decision.md"
   ],
   "scripts": {
     "build": "node internal/validate/build-publish.mjs",
@@ -56,10 +62,14 @@
     "validate:cli-docs": "node internal/validate/validate-cli-docs.mjs",
     "lint:md": "markdownlint \"**/*.md\"",
     "validate:registry": "node internal/validate/validate-registry-integrity.mjs",
+    "clean:verify": "node -e \"const fs = require('fs'); fs.rmSync('dist', { recursive: true, force: true }); fs.readdirSync('.').filter(f => f.endsWith('.tgz')).forEach(f => fs.rmSync(f, { force: true }));\"",
     "test": "npm run test:unit",
-    "test:unit": "vitest run",
+    "test:unit": "vitest run tests/unit/",
     "test:watch": "vitest",
-    "test:e2e": "node tests/validate-e2e.mjs",
+    "test:e2e": "node tests/validate-e2e.mjs && vitest run tests/e2e/consumer-workflow.test.js",
+    "test:e2e:runtime": "AI_WORKFLOW_RELEASE=1 vitest run tests/e2e/consumer-workflow.test.js -t \"Real OpenCode Smoke Test\"",
+    "release:verify": "npm run clean:verify && npm test && npm run test:e2e && npm run validate && npm run pack:verify && npm run test:e2e:runtime",
+    "pack:verify": "node tests/e2e/verify-packed-consumer.mjs",
     "pack:safe": "node internal/validate/pack-safe.mjs",
     "validate:behavioral-contracts": "node internal/validate/validate-behavioral-contracts.mjs",
     "validate:token-economy": "node internal/validate/validate-token-economy.mjs",

package/read_only_safety_verification.md

@@ -0,0 +1,48 @@
+# Read-Only Safety, Sage Validation, and OpenCode Retest Verification Report
+
+This report documents the resolution of all blocking items identified to reach the `PASS — publish ready` status.
+
+## 1. Summary of Resolved Items
+
+### State Machine Transition Correction
+- Updated [execute.js](src/commands/execute.js) to transition the state machine sequentially through:
+  `IMPLEMENTING -> IMPLEMENTED -> VALIDATING -> COMPLETED`
+  instead of attempting a direct jump from `IMPLEMENTING` to `COMPLETED` during read-only runs.
+
+### Snapshot Comparison Bug Fix
+- Corrected [compareReadOnlyState](src/commands/execute.js) to compare `.snapshot.files` rather than `.snapshot` directly.
+- Standardized comparisons on `.sha256` instead of `.hash`.
+
+### Physical File Write Prevention
+- Prevented physical file creation of handoff markdown files and execution ledgers inside the repository when running under a read-only request.
+- Moved the final ledger logs and handoffs into memory and routed them to `stdout`.
+- Declared the block-scoped `plan` variable outside the `try` block so it is properly evaluated in the `finally` block of `runExecute` to suppress file saving.
+
+### E2E Test Suite Enhancements
+- Added a new E2E test case `16. Read-only válido -> COMPLETED; sem mutações, nenhum handoff ou ledger gravado` inside [consumer-workflow.test.js](tests/e2e/consumer-workflow.test.js) asserting that a valid read-only execution maintains branch, HEAD, and files identically while leaving the `.ai-workflow/` history and handoff directories empty.
+- Injected a local controlled OpenCode mock in [verify-packed-consumer.mjs](tests/e2e/verify-packed-consumer.mjs) before running doctor checks, removing dependencies on host/CI global executables.
+
+### Integration of Real OpenCode Smoke Test
+- Updated `package.json` to link the real OpenCode smoke test (`test:e2e:runtime` with `AI_WORKFLOW_RELEASE=1`) directly into the final `release:verify` command.
+- Verified that the smoke test runs and passes successfully on this host environment where the real `opencode` CLI is available.
+
+### Sage validation agent for full mode
+- Modified [validate](src/core/delegation-controller.js) in the delegation controller to execute validation via the `Sage` agent when the task mode is `"full"`.
+- Added unit tests in [delegation-ledger.test.js](tests/unit/delegation-ledger.test.js) to assert that Sage events (`validation_start`, `validation_complete`) are logged.
+- Mocked Sage agent capabilities in the E2E framework ([fake-opencode.js](tests/e2e/helpers/fake-opencode.js)) to support a fail-once revalidation scenario.
+- Created E2E test case `17. Alto risco / Full -> Astra e Sage executados; com finding, Phoenix e Sage revalidação` to prove the full multi-agent loop:
+  `Astra -> Sage -> Phoenix -> Sage`
+
+---
+
+## 2. Verification Evidence
+
+All consolidated validation checks run and exit with code `0`.
+
+| Test Run | Command | Result | Details |
+| --- | --- | --- | --- |
+| **Unit Tests** | `npm run test:unit` | **PASS (142/142)** | All unit tests completed successfully (including the new Sage validation event logging) |
+| **E2E Tests** | `npm run test:e2e` | **PASS (18/18)** | All E2E test cases pass successfully, including the new read-only safety validation (16) and multi-agent coordination (17) |
+| **All Gates** | `npm run validate` | **PASS (18/18)** | 18 validation checks completed successfully |
+| **Packaging** | `npm run pack:verify` | **PASS** | Doctor and Init runs successfully verified against packed tarball |
+| **Integrity** | `npm run release:verify` | **PASS (Exit 0)** | Consolidated clean, test, e2e, validate, pack:verify, and real OpenCode smoke tests |

package/src/cli.js

@@ -74,12 +74,14 @@ export async function runCli(args) {
     const flags = parseFlags(args.slice(1));
     const positionals = args.slice(1).filter((arg) => !arg.startsWith("-"));
     const request = flags.request || positionals.join(" ");
-    await runExecute({
+    const result = await runExecute({
       cwd: process.cwd(),
       naturalRequest: request,
-      override: args.includes("--override") ? "authorized-override-token" : undefined,
       taskSlug: flags.taskSlug
     });
+    if (result && (result.overallStatus === "FAIL_QUALITY_GATE" || result.overallStatus === "BLOCKED" || result.overallStatus === "FAIL")) {
+      process.exit(1);
+    }
     return;
   }
 

package/src/commands/collect-evidence.js

@@ -1,50 +1,14 @@
 import { EvidenceCollector } from "../core/validation/evidence-collector.js";
 import { QualityGuard } from "../core/validation/quality-guard.js";
+import { ValidationPlanner } from "../core/validation/validation-planner.js";
 import { buildDeliverySummary, formatDeliverySummary } from "../core/validation/canonical-finalization.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 
-function isNoOpScript(script = "") {
-  const value = String(script).trim().toLowerCase();
-  return /^(echo\b|true$|exit\s+0$|node\s+-e\s+["']?console\.log)/.test(value) || value.includes("tests-pass");
-}
-
-function addScriptTask(tasks, scripts, name, command, { rejectNoOp = false } = {}) {
-  const script = scripts[name];
-  if (!script) return;
-  if (!rejectNoOp && name === "test" && isNoOpScript(script)) return;
-  if (rejectNoOp && isNoOpScript(script)) {
-    tasks.push({ name, command, kind: name === "test" ? "test" : name, presetStatus: "FAIL_QUALITY_GATE", summary: `Configured ${name} script is a no-op: ${script}` });
-    return;
-  }
-  tasks.push({ name, command, kind: name === "test" ? "test" : name });
-}
-
-function isManagedValidationPath(file = "") {
-  return /(^|\/)(node_modules|vendor|dist|coverage|\.cache)(\/|$)/.test(String(file).replaceAll("\\", "/"));
-}
-
 export async function runCollectEvidence({ cwd, exitOnError = true, taskSlug = null, mode = null, dryRun = false, profile = "generic", branchRecovery = "NOT_RECORDED" }) {
-  const tasks = [];
   const qualityGuard = new QualityGuard({ cwd, taskSlug, mode });
-  try {
-    const pkg = JSON.parse(await fs.readFile(path.join(cwd, "package.json"), "utf8"));
-    const scripts = pkg.scripts || {};
-    const executableBehavior = await qualityGuard.hasExecutableBehaviorChanges();
-    addScriptTask(tasks, scripts, "lint", "npm run lint");
-    addScriptTask(tasks, scripts, "test", "npm test", { rejectNoOp: executableBehavior });
-    addScriptTask(tasks, scripts, "build", "npm run build");
-    addScriptTask(tasks, scripts, "typecheck", "npm run typecheck");
-    if (scripts.validate && !String(scripts.validate).includes("ai-workflow collect-evidence")) addScriptTask(tasks, scripts, "validate", "npm run validate");
-
-    const changed = qualityGuard.getChangedFiles().filter((file) => !isManagedValidationPath(file));
-    const hasTs = changed.some((file) => /\.(ts|tsx)$/.test(file)) || await fs.access(path.join(cwd, "tsconfig.json")).then(() => true).catch(() => false);
-    if (hasTs && !scripts.typecheck) {
-      tasks.push({ name: "typecheck", command: "npm run typecheck", kind: "typecheck", presetStatus: "FAIL_QUALITY_GATE", summary: "TypeScript detected but no typecheck script is configured." });
-    }
-  } catch {
-    // Non-Node projects can still supply validation through project-specific commands.
-  }
+  const planner = new ValidationPlanner({ cwd, qualityGuard });
+  const tasks = await planner.plan(profile);
 
   const persist = !dryRun && mode === "full";
   const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode, profile, branchRecovery });

package/src/commands/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { exists, readJson, readJsonc } from "../core/filesystem.js";
+import { OpenCodeAdapter } from "../core/runtime/opencode-adapter.js";
 
 const REQUIRED_FILES = [
   ".ai-workflow",
@@ -23,6 +24,21 @@ export async function runDoctor({ cwd }) {
 
   console.log("Doctor report:");
 
+  // Check OpenCode runtime
+  const adapter = new OpenCodeAdapter({ cwd });
+  const inspection = await adapter.inspect();
+  if (inspection.available) {
+    console.log("PASS opencode CLI is available");
+    const supportedStr = Object.entries(inspection.supports)
+      .filter(([_, v]) => v)
+      .map(([k, _]) => k)
+      .join(", ");
+    console.log(`PASS opencode capabilities detected: ${supportedStr || "none"}`);
+  } else {
+    hasFailure = true;
+    console.log("FAIL opencode CLI is not installed or not available in PATH");
+  }
+
   for (const relativePath of REQUIRED_FILES) {
     const ok = await exists(path.join(cwd, relativePath));