@williambeto/ai-workflow 2.9.2 → 2.9.4

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 ## [unreleased]
 
+## [2.9.4] - 2026-07-16
+
+### 🛡️ Hardening
+
+- Add an opt-in repository-local pre-push hook that rejects direct updates to
+  `main` and `master` without changing the published consumer payload
+- Refresh development-only lockfile dependencies to remove known production,
+  moderate, high, and critical audit findings
+
+### 🧪 Testing
+
+- Add stable contract coverage for documentation integrity, protected-branch
+  pushes, finalizer change detection, and validation-result precedence
+- Verify that the public tarball excludes contributor hooks, internal
+  validators, tests, and generated evidence
+
+### 📚 Documentation
+
+- Align the README with the canonical AI Workflow Kit product promise,
+  installed paths, agent roles, and the actual CLI enforcement boundary
+
+## [2.9.3] - 2026-07-16
+
+### 🐛 Bug Fixes
+
+- Restore scoped specialist delegation for every core AIWK agent without
+  reintroducing `bash` or `edit` approval prompts
+- Allow Atlas to reach both workflow agents and all registered specialists
+  while preventing specialists from delegating recursively
+- Set OpenCode's bounded subagent depth to two so workflow agents delegated by
+  Atlas can still consult one specialist
+- Detect stale or incomplete specialist routing through `ai-workflow doctor`
+
+### 🧪 Testing
+
+- Cover the complete six-caller by twenty-specialist routing matrix
+- Verify upgrades from permission-free `2.9.2` configurations and reject
+  recursive specialist delegation
+- Exercise Atlas to workflow-agent to specialist routing in a real OpenCode
+  runtime smoke test
+
 ## [2.9.2] - 2026-07-16
 
 ### 🐛 Bug Fixes

package/README.md

@@ -15,20 +15,22 @@
 
 ## What is AI Workflow Kit?
 
-AI Workflow Kit (AIWK) is an **npm CLI** you install in your project that makes AI-assisted software delivery **safe, structured, and verifiable**.
+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.
 
-It works with [OpenCode](https://opencode.ai) to turn a natural language request into a full delivery — with branch protection, specialist agent delegation, automated validation, and a persisted evidence log.
+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.
+
+It works with [OpenCode](https://opencode.ai) to turn a natural language request into a proportionate delivery — with branch isolation, optional specialist analysis, observed validation, and evidence appropriate to the task risk.
 
 **Without AIWK**, a coding agent receives a request, writes code, and reports success. There is no proof, no branch isolation, and no guarantee that tests passed.
 
 **With AIWK**, the same request travels through a mandatory workflow:
 
 ```
-Your request  →  Classification  →  Branch Gate  →  Specialist Agent
-     →  Automated Validation  →  Evidence  →  Handoff
+Your request  →  Classification  →  Branch Gate  →  Workflow Owner
+     →  Observed Validation  →  Evidence  →  Handoff
 ```
 
-No step can be skipped. No claim of success is made without proof.
+Within the `ai-workflow execute` control plane, every stage is evaluated and a successful final state requires observed validation. Direct model chat remains subject to runtime capabilities; see the [runtime compatibility matrix](dist-assets/docs/compatibility/runtime-matrix.md).
 
 ---
 
@@ -47,7 +49,7 @@ AI Workflow Kit enforces a contract: **the agent must earn the right to deliver.
 
 ## How it works
 
-AIWK installs a structured team of 6 specialist agents into your repository. Each agent has a defined role, a permission boundary, and cannot claim work that belongs to another.
+AIWK installs a structured team of 6 core workflow agents into your repository. Each agent has a defined role and ownership boundary. Any core agent may request bounded analysis from a registered specialist when that improves the result, while retaining ownership of its workflow stage.
 
 When you run `npx aw execute "your task"`, Atlas (the coordinator) takes over:
 
@@ -59,7 +61,7 @@ When you run `npx aw execute "your task"`, Atlas (the coordinator) takes over:
 | **4. Implement** | Astra | Implements the change on the feature branch |
 | **5. Validate** | Sage | Runs tests, accessibility checks, visual regression — writes evidence |
 | **6. Remediate** | Phoenix | If validation fails, Phoenix heals within a bounded attempt limit |
-| **7. Evidence** | Atlas | Saves `EVIDENCE.json` + `HANDOFF-<task>.md` to `.ai-workflow/` |
+| **7. Evidence** | Atlas | Saves the handoff and ledger; persists `EVIDENCE.json` when the evidence policy requires it |
 
 > **Proportional by design.** A typo fix in a README gets 1 remediation attempt and no spec. A payment integration gets 3 attempts, a required SDD, and mandatory persisted evidence. The kit calibrates automatically.
 
@@ -100,7 +102,7 @@ This creates the `.ai-workflow/` directory and installs 6 agents, 25 skills, and
 npx aw execute "Add a health check endpoint returning HTTP 200"
 ```
 
-Atlas classifies the request, creates a branch, delegates to Astra, validates with Sage, and writes evidence — all automatically.
+Atlas classifies the request, the branch gate establishes a safe branch, Astra owns requested changes, and validation and evidence run proportionally.
 
 ### 4. Check the evidence
 
@@ -134,7 +136,7 @@ Each agent has a fixed role and cannot exceed its operational boundary.
 | 🧪 **Sage** | Validator | Audits changes, runs quality gates, writes verifiable evidence |
 | 🔧 **Phoenix** | Recovery | Heals broken states within a bounded remediation limit |
 
-Agents are installed as prompts in your `.ai-workflow/agents/` directory. You can read, audit, or customise them.
+Agents are installed as prompts in your `.ai-workflow/opencode/agents/` directory. You can read, audit, or customise them.
 
 ---
 
@@ -170,15 +172,22 @@ You don't configure this. The kit reads your request and calibrates automaticall
 
 Running `npx aw init` writes the following into your repository:
 
+The canonical OpenCode runtime paths are `.ai-workflow/opencode/agents/`, `.ai-workflow/opencode/commands/`, `.ai-workflow/opencode/skills/`, and `.ai-workflow/opencode/docs/`.
+
 ```
 .ai-workflow/
-├── agents/          # Atlas, Nexus, Orion, Astra, Sage, Phoenix prompts
-├── commands/        # Slash commands for your AI IDE
-├── skills/          # 25 domain skills (architecture, security, database, ...)
+├── opencode/
+│   ├── agents/      # Atlas, Nexus, Orion, Astra, Sage, Phoenix prompts
+│   ├── commands/    # Slash commands for OpenCode
+│   ├── skills/      # Domain skills (architecture, security, database, ...)
+│   └── docs/        # Runtime policies, profiles, references, and guides
+├── harness/         # Workflow and handoff harness
+├── schemas/         # Evidence and workflow schemas
 ├── templates/       # Specification and handoff templates
-├── policies/        # Branch gate, quality gate, merge gate policies
-├── history/         # Ledger of every workflow execution
-└── handoffs/        # HANDOFF-<task>.md for every completed delivery
+├── history/         # Runtime-generated workflow ledgers
+└── handoffs/        # Runtime-generated delivery handoffs
+AGENTS.md             # Project-local contributor contract
+QUICKSTART.md         # Installed quickstart
 opencode.jsonc        # OpenCode runtime configuration
 ```
 
@@ -188,8 +197,8 @@ Everything is plain text — readable, auditable, and version-controlled.
 
 ## Safety Guarantees
 
-- **Branch protection**: execution is always blocked on `main`/`master`. A feature branch is created automatically.
-- **Read-only confinement**: tasks classified as read-only are cryptographically verified — any file mutation blocks the execution.
+- **Branch gate**: write-mode execution is blocked on `main`/`master`. A feature branch is created automatically when the worktree is clean.
+- **Read-only confinement**: tasks classified as read-only compare SHA-256 workspace snapshots before and after execution; any observed mutation blocks completion.
 - **Bounded remediation**: Phoenix is limited to N attempts. The kit never loops indefinitely.
 - **Mandatory handoff**: every write-mode execution produces a `HANDOFF-<task>.md` with evidence, diff, and status — regardless of risk level.
 - **Schema-validated evidence**: `EVIDENCE.json` is validated against a strict Ajv schema. Path traversal and shell injection are blocked.
@@ -231,12 +240,12 @@ Beyond the 6 core agents, AIWK ships 25 domain skills that agents activate as co
 
 ## Contributing
 
-AIWK uses itself to manage its own development. To contribute:
+This development repository follows the AIWK contributor contract directly without installing consumer runtime assets into itself. To contribute:
 
 ```
 src/           TypeScript source (CLI + Core)
 dist-assets/   Templates, agents, skills, schemas installed into consumer repos
-tests/         Unit (296 tests) and E2E (19 tests) suites
+tests/         Unit, contract, linting, and E2E suites
 internal/      Validation pipelines and release scripts
 docs/          Guides, ADRs, specs, and release notes
 ```
@@ -249,6 +258,14 @@ npm run validate
 
 All 23 quality gates must pass.
 
+Contributors without server-side branch protection can enable the repository's local push safeguard explicitly:
+
+```bash
+npm run setup:hooks
+```
+
+The hook blocks pushes targeting `main` or `master` and allows maintenance or feature branches. It prevents accidents but is not a server-side security boundary and can be bypassed with Git's `--no-verify` option.
+
 ---
 
 ## License

package/bin/ai-workflow.js

@@ -761,6 +761,58 @@ var SUBAGENTS = {
   "Technical-Leader": { description: "Capability only: analyze technical decisions, architecture, and trade-offs", skill: "technical-leadership" },
   "UI-UX-Engineer": { description: "Capability only: review usability and interface clarity", skill: "ui-ux-design" }
 };
+var CORE_AGENT_NAMES = Object.freeze(Object.keys(AGENTS));
+var SPECIALIST_AGENT_NAMES = Object.freeze(Object.keys(SUBAGENTS));
+var MIN_SUBAGENT_DEPTH = 2;
+function inspectSpecialistRoutingConfig(opencodeConfig) {
+  const errors = [];
+  const warnings = [];
+  const agents = opencodeConfig?.agent ?? {};
+  if (typeof opencodeConfig?.subagent_depth !== "number" || opencodeConfig.subagent_depth < MIN_SUBAGENT_DEPTH) {
+    errors.push(`OpenCode subagent_depth must be at least ${MIN_SUBAGENT_DEPTH} for workflow-agent to specialist routing`);
+  }
+  for (const specialist of SPECIALIST_AGENT_NAMES) {
+    if (agents[specialist]?.mode !== "subagent") {
+      errors.push(`specialist missing or not configured as subagent: ${specialist}`);
+    }
+    if (agents[specialist]?.permission?.task !== void 0) {
+      errors.push(`specialist must not delegate recursively: ${specialist}`);
+    }
+  }
+  for (const caller of CORE_AGENT_NAMES) {
+    const taskPermissions = agents[caller]?.permission?.task;
+    if (!taskPermissions || typeof taskPermissions !== "object" || Array.isArray(taskPermissions)) {
+      errors.push(`core agent lacks explicit specialist task routing: ${caller}`);
+      continue;
+    }
+    if (taskPermissions["*"] !== "deny") {
+      errors.push(`core agent task routing must deny unspecified targets: ${caller}`);
+    }
+    if (Object.values(taskPermissions).includes("ask")) {
+      errors.push(`core agent task routing must not request approval: ${caller}`);
+    }
+    const blockedSpecialists = SPECIALIST_AGENT_NAMES.filter((specialist) => taskPermissions[specialist] !== "allow");
+    if (blockedSpecialists.length > 0) {
+      errors.push(`core agent cannot reach all specialists: ${caller} (${blockedSpecialists.join(", ")})`);
+    }
+    const otherCoreAgents = CORE_AGENT_NAMES.filter((name) => name !== caller);
+    if (caller === "Atlas") {
+      const blockedCoreAgents = otherCoreAgents.filter((name) => taskPermissions[name] !== "allow");
+      if (blockedCoreAgents.length > 0) {
+        errors.push(`Atlas cannot reach all workflow agents: ${blockedCoreAgents.join(", ")}`);
+      }
+    } else {
+      const recursiveCoreAgents = otherCoreAgents.filter((name) => taskPermissions[name] === "allow");
+      if (recursiveCoreAgents.length > 0) {
+        errors.push(`non-Atlas core agent can recursively delegate workflow ownership: ${caller} (${recursiveCoreAgents.join(", ")})`);
+      }
+    }
+  }
+  if (opencodeConfig?.permission?.task !== void 0) {
+    warnings.push("consumer-level permission.task may override AIWK specialist routing or enable recursive delegation");
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
 var COMMANDS = {
   atlas: { description: "Decide safest next step and delegate to the appropriate workflow or agent", agent: "Atlas" },
   run: { description: "Execute the master orchestration pipeline (Gates, SDD, Implementation, Validation, Healing)", agent: "Atlas" },
@@ -779,11 +831,23 @@ var COMMANDS = {
 };
 function buildManagedConfig() {
   const agent = {};
+  const specialistTaskPermissions = Object.fromEntries([
+    ["*", "deny"],
+    ...SPECIALIST_AGENT_NAMES.map((name) => [name, "allow"])
+  ]);
+  const atlasTaskPermissions = Object.fromEntries([
+    ["*", "deny"],
+    ...CORE_AGENT_NAMES.filter((name) => name !== "Atlas").map((name) => [name, "allow"]),
+    ...SPECIALIST_AGENT_NAMES.map((name) => [name, "allow"])
+  ]);
   for (const [name, def] of Object.entries(AGENTS)) {
     agent[name] = {
       mode: def.mode,
       description: def.description,
-      prompt: `{file:./.ai-workflow/opencode/agents/${name.toLowerCase()}.md}`
+      prompt: `{file:./.ai-workflow/opencode/agents/${name.toLowerCase()}.md}`,
+      permission: {
+        task: name === "Atlas" ? atlasTaskPermissions : specialistTaskPermissions
+      }
     };
   }
   for (const [name, def] of Object.entries(SUBAGENTS)) {
@@ -804,6 +868,7 @@ function buildManagedConfig() {
   return {
     $schema: "https://opencode.ai/config.json",
     default_agent: "Atlas",
+    subagent_depth: MIN_SUBAGENT_DEPTH,
     agent,
     skills: {
       paths: ["./.ai-workflow/opencode/skills"]
@@ -839,6 +904,7 @@ async function mergeOpencodeConfig(cwd, { force = false, backupRoot = ".ai-workf
   const next = {
     ...currentWithoutLegacy,
     $schema: current.$schema ?? managed.$schema,
+    subagent_depth: typeof current.subagent_depth === "number" ? Math.max(current.subagent_depth, managed.subagent_depth) : managed.subagent_depth,
     ...managed.mcp ? {
       mcp: {
         ...current.mcp ?? {},
@@ -1988,6 +2054,18 @@ async function checkOpencodeJson(cwd, state) {
         console.log(`FAIL opencode agent entries missing: ${missingAgents.join(", ")}`);
       }
     }
+    const specialistRouting = inspectSpecialistRoutingConfig(opencodeConfig);
+    if (specialistRouting.valid) {
+      console.log(`PASS OpenCode specialist routing available (${CORE_AGENT_NAMES.length} callers, ${SPECIALIST_AGENT_NAMES.length} specialists)`);
+    } else {
+      state.hasWarning = true;
+      for (const error of specialistRouting.errors) console.log(`WARN ${error}`);
+      console.log("WARN specialist routing is stale or incomplete; rerun `ai-workflow init --yes --no-install`");
+    }
+    for (const warning of specialistRouting.warnings) {
+      state.hasWarning = true;
+      console.log(`WARN ${warning}`);
+    }
   } catch {
     state.hasFailure = true;
     console.log("FAIL opencode.jsonc is not valid JSONC");