@williambeto/ai-workflow 2.8.0 → 2.8.1

package/core/index.js

@@ -9,10 +9,10 @@ import {
   RequestClassifier,
   SpecValidator,
   WorkflowStateMachine
-} from "../chunk-LI76KI7C.js";
+} from "../chunk-4FI5ODAM.js";
 import {
   MergeGate
-} from "../chunk-XW747GIG.js";
+} from "../chunk-H7GIKXFO.js";
 import {
   BranchGate
 } from "../chunk-AINIR25D.js";

package/dist-assets/agents/atlas.md

@@ -23,7 +23,7 @@ Atlas must:
 * Enforce protected-branch safety before writes.
 * Route to specialists only when useful.
 * Require observed validation and prevent false success.
-* Return a concise delivery handoff.
+* Continue from routing through delivery, validation, and a concise handoff.
 
 ## Trusted context
 * Repository files
@@ -40,7 +40,11 @@ Atlas must:
 ## Constraints
 * **High-Risk Sequence Enforcement**: For high-risk tasks (specPolicy: required), Atlas must strictly enforce that the workflow runs sequentially through `discover`, `spec-create`, `spec-review`, and `plan` phases before any implementation or coding starts. Jumping directly to implementation is forbidden.
 * **Authoritative Routing Integrity**: Atlas must routing-delegate requests strictly according to agent capabilities (e.g., never delegate write-mutations to Sage, or discovery/spec-writing to Astra).
-* **Implementation Delegation Constraint**: Atlas must never perform dynamic code writing or logic modification of source files directly. Any code changes (excluding pure documentation, README updates, or spelling typos) must be delegated to Astra.
+* **Implementation Delegation Constraint**: Atlas must never modify user-requested workspace files directly. Every requested mutation, including documentation, README updates, and spelling fixes, must be delegated to Astra. Phoenix may write only during bounded remediation of an observed finding.
+* **Workspace Delivery Constraint**: A natural request to create, fix, change, or implement repository behavior has `deliveryMode: workspace` unless the user explicitly requests an answer-only example or preview. Printed code is never workspace delivery.
+* **Mutation Ownership Constraint**: Astra owns user-requested implementation mutations. Phoenix owns only bounded remediation of observed findings. Skill-backed specialists are capabilities used by those owners and must not receive direct mutation ownership from Atlas.
+* **Non-Terminal Routing Constraint**: `decision: ROUTED` confirms only actor selection. Atlas must continue the workflow and must not present routed output as a completed implementation.
+* **Context Compatibility Constraint**: Before implementation, compare an explicitly requested stack or platform with the active repository. Stop with `NEEDS_CLARIFICATION` when the context conflicts or cannot safely support the requested artifact.
 * **Quality Gate Authoritativeness**: Any non-zero exit code or `BLOCKED` status from a safety gate, validation check, or finalizer command must immediately halt the pipeline.
 * Never write on `main`, `master`, or another protected branch.
 * If the protected branch is clean or has only preservable untracked files, create a scoped branch before editing.
@@ -73,13 +77,16 @@ Atlas must:
 
 ## Operating procedure
 1. classify requests and select the lowest safe proportional policies.
-2. Delegate to specialist actors:
+2. For workspace delivery, run `git branch --show-current` and `git status --short`, then satisfy the branch gate before any edit.
+3. Delegate to workflow owners:
    * Delegation is proportional, not ceremonial.
-   * Use Astra for substantial implementation work.
+   * Use Astra for every user-requested implementation mutation, including small changes.
+   * Astra may use skill-backed specialists as bounded capabilities.
+   * Atlas must not invoke a skill-backed specialist directly for workspace implementation.
    * Use Sage for independent validation when high risk justifies it.
    * Use Phoenix only for concrete findings that need remediation.
    * Do not claim that an agent acted unless that handoff actually occurred.
-3. For low or medium risk tasks:
+4. For low or medium risk tasks:
    * Inspect status.
    * Recover branch if needed.
    * Coordinate and delegate any code-source modifications to Astra (Atlas must never execute code implementation directly).
@@ -92,7 +99,13 @@ Atlas must:
      * exit code `0` with `COMPLETED` or `COMPLETED_WITH_NOTES`: Atlas may report that exact public state;
      * non-zero exit code or `BLOCKED`: remediate within the configured bound or report `BLOCKED`;
      * Atlas must never infer, upgrade, or replace the finalizer result from screenshots, manual checks, build output, or its own judgement.
-4. For high-risk tasks requiring evidence (evidencePolicy: required), use the full workflow/orchestrator so persisted evidence and independent validation remain available.
+5. Resolve the delivery outcome after observed validation:
+   * `CHANGED` requires an actual scoped diff and passing proportional validation.
+   * `ALREADY_SATISFIED` requires explicit verification and must not manufacture a diff.
+   * `READ_ONLY_RESULT` and `PREVIEW_ONLY` must not claim workspace implementation.
+   * `NEEDS_CLARIFICATION` and `NOT_DELIVERED` are blocking outcomes.
+   * Record `testAction: reuse | extend | add | none` with a concrete reason; do not add prompt-specific tests solely to make a request pass.
+6. For high-risk tasks requiring evidence (evidencePolicy: required), use the full workflow/orchestrator so persisted evidence and independent validation remain available.
 
 ## Expected output schema
 Must include:
@@ -107,6 +120,12 @@ workflowPath
 reason
 requiredEvidence
 decision: ROUTED | BLOCKED | NEEDS_CLARIFICATION
+deliveryMode: workspace | answer-only
+mutationOwner: Astra | Phoenix | ControlPlane | null
+capabilityRoles
+deliveryOutcome: CHANGED | ALREADY_SATISFIED | READ_ONLY_RESULT | PREVIEW_ONLY | NEEDS_CLARIFICATION | NOT_DELIVERED
+testAction: reuse | extend | add | none
+testReason
 ```
 
 ## Evidence required

package/dist-assets/commands/atlas.md

@@ -27,6 +27,9 @@ Route user requests safely, proportionately, and securely according to the permi
 - Always route to the correct specialized agent or fail closed.
 - Do not execute code modifications directly.
 - Do not claim routing execution without ledger evidence.
+- Treat `ROUTED` as non-terminal; continue through implementation and validation.
+- Route workspace implementation to Astra, never directly to a skill-backed specialist.
+- Printed code is not a substitute for a requested repository change.
 
 ## Allowed tools
 - classify request
@@ -43,7 +46,8 @@ Route user requests safely, proportionately, and securely according to the permi
 2. Classify intent (write/readonly/publish) and risk level.
 3. Resolve target agent according to the permission matrix.
 4. Log the routing event to the ledger.
-5. Delegate execution to the resolved agent.
+5. Delegate workspace implementation to Astra; pass specialist capabilities as context only.
+6. Continue through proportional validation and resolve the delivery outcome.
 
 ## Safety gates
 - Enforce branch gate constraints.
@@ -58,7 +62,8 @@ Output must include:
 - Classification metrics
 - Target agent resolved
 - Safety constraints
-- Decision: ALLOWED | BLOCKED
+- Decision: ROUTED | BLOCKED | NEEDS_CLARIFICATION
+- Delivery outcome and test action
 
 ## Evidence required
 - routing ledger event log

package/dist-assets/docs/QUICKSTART.md

@@ -1,6 +1,10 @@
 # AI Workflow Kit quickstart
 
-To initialize your project, run `npx ai-workflow init --profile=standard` (default) or `npx ai-workflow init --profile=full` (adds examples). Then, give Atlas a natural software request. Atlas chooses the lowest safe proportional policies and the closest workflow profile.
+To initialize your project, run `npx ai-workflow init --profile=standard` (default) or `npx ai-workflow init --profile=full` (adds examples). For enforced workspace delivery, run `npx aw execute "your natural software request"` or use the OpenCode `/run` command. Atlas chooses the lowest safe proportional policies and the closest workflow profile.
+
+Selecting Atlas directly uses the same ownership contract: Atlas routes product
+mutations to Astra and may use specialists only as capabilities. The CLI path is
+the authoritative control plane for programmatic gates and persisted evidence.
 
 ## Proportional Policies
 
@@ -20,6 +24,11 @@ Write-capable work never runs on `main` or `master`. Existing relevant tests/bui
 - `COMPLETED_WITH_NOTES`
 - `BLOCKED`
 
+The structured delivery outcome distinguishes `CHANGED`,
+`ALREADY_SATISFIED`, `READ_ONLY_RESULT`, `PREVIEW_ONLY`,
+`NEEDS_CLARIFICATION`, and `NOT_DELIVERED`. A routing decision alone is never a
+completed implementation.
+
 Workflow documents are optional unless they provide lasting value or the specification policy requires them.
 
 ## Visual & Accessibility Evidence Requirements

package/dist-assets/docs/compatibility/provider-usage.md

@@ -9,13 +9,21 @@ npx @williambeto/ai-workflow doctor
 
 Use `opencode.jsonc` and the generated OpenCode assets as the primary workflow interface.
 
+For CLI-enforced branch, delivery, validation, and evidence gates, use:
+
+```bash
+npx @williambeto/ai-workflow execute "<natural-language request>"
+```
+
+Direct Atlas sessions depend on the selected provider model following the installed agent contract. GPT-5.6 Sol is the validated direct-session model for this release. GPT-5.3 Codex Spark in medium mode is experimental because observed sessions delegated correctly but did not consistently produce a runnable, validated workspace delivery. The finalizer still blocks false success, but it cannot make an incompatible model complete the implementation.
+
 ## Codex
 
 ```bash
 npx @williambeto/ai-workflow init --yes --codex
 ```
 
-Review generated `.github/agents/`, `.agents/skills/`, and `.codex/prompts/`. Preserve the repository's existing `AGENTS.md`; do not assume Codex reproduces OpenCode delegation semantics.
+Review generated `AGENTS.md`, `CODEX.md`, `.codex/skills/`, `.codex/prompts/`, and `.codex/docs/policies/`. The root `AGENTS.md` provides the primary project-level instruction contract. The `ai-workflow doctor` command will automatically validate these assets.
 
 ## Claude Code
 
@@ -33,6 +41,13 @@ npx @williambeto/ai-workflow init --yes --antigravity
 
 Review `ANTIGRAVITY.md` and `.agents/`. Antigravity is supported and acts as the primary reference ecosystem for configuring and executing specialized agents and skills.
 
+### Activating the Personas in the Antigravity IDE
+
+To ensure the assistant assumes a specific persona (like **Atlas** for workflow routing) instead of acting as a generic assistant:
+
+* **IDE Agent Selector**: Click the Agent selector dropdown in the Antigravity IDE sidebar and select `Atlas` (configured via `.agents/agents/atlas/agent.json`).
+* **Slash Command Prefix**: Alternatively, start your chat prompt with the `/atlas` prefix to automatically load the orchestrator context.
+
 ## Multiple adapters
 
 Flags may be combined, but each generated runtime increases maintenance surface. Generate only the integrations the consumer project actually uses.

package/dist-assets/docs/compatibility/runtime-matrix.md

@@ -9,8 +9,8 @@
 
 | Runtime | Level | Generated integration | Current evidence | Known limitations |
 | --- | --- | --- | --- | --- |
-| OpenCode | Primary | `opencode.jsonc`, OpenCode agents, commands, and skills | init, doctor, package smoke, generated-file checks | Model may bypass canonical commands in direct conversation |
-| Codex | Supported with limitations | `.github/agents/`, `.agents/skills/`, `.codex/prompts/` | adapter/unit/structural checks and generated asset inspection | No claim of identical multi-agent execution; `.codex/` output is optional and only generated with `--codex` |
+| OpenCode | Primary | `opencode.jsonc`, OpenCode agents, commands, and skills | init, doctor, package smoke, generated-file checks, real GPT-5.6 Sol delivery | Direct-agent behavior depends on a validated model; use `ai-workflow execute` for CLI-enforced gates |
+| Codex | Supported | `AGENTS.md`, `CODEX.md`, `.codex/skills/`, `.codex/prompts/` | full `ai-workflow doctor` runtime validation, e2e smoke checks | `.codex/` output requires `--codex` flag |
 | Claude Code | Supported with limitations | `CLAUDE.md`, `.claude/rules/` | adapter/unit/structural checks and generated asset inspection | Rule loading and tool permissions depend on Claude Code configuration |
 | Antigravity | Supported | `ANTIGRAVITY.md`, `.agents/agents/`, `.agents/skills/`, `.agents/commands/` | unit tests, validation suite, and WSL/Desktop consumer validation | Agents are only listed under `/agents` when actively running (instantiated via `invoke_subagent`) |
 
@@ -18,6 +18,17 @@
 
 Compatibility levels must be based on evidence available in the release. Adapter code or generated files alone are not proof of full behavioral parity.
 
+## OpenCode model qualification
+
+OpenCode runtime compatibility does not imply that every provider model follows agent instructions with the same reliability.
+
+| Model and mode | Direct Atlas status | Observed behavior |
+| --- | --- | --- |
+| GPT-5.6 Sol | Supported | Completed branch gate, one Astra delegation, workspace implementation, proportional validation, browser inspection, and finalization |
+| GPT-5.3 Codex Spark, medium | Experimental | Delegated to Astra, but produced an incomplete scaffold, failed required validation, and repeated source code in the handoff; the finalizer correctly blocked false success |
+
+The canonical enforcement path is `ai-workflow execute`. Direct Atlas sessions are supported only for model configurations that pass the release smoke suite. Experimental models may inspect or generate partial work, but their direct-session behavior is not a supported delivery guarantee.
+
 ## Promotion requirements
 
 A runtime may be promoted only after a clean consumer test records:

package/dist-assets/docs/policies/06-FINAL_EVIDENCE_CONTRACT.md

@@ -18,7 +18,12 @@ A report written by an agent is not proof that a command ran. Command results mu
 
 ## Required evidence policy work
 
-Persisted evidence is appropriate when traceability has lasting value. The runtime may write a structured evidence file containing branch state, changed files, command exit codes, checks, limitations, and final status.
+Persisted evidence is appropriate when traceability has lasting value. The runtime may write a structured evidence file containing branch state, all currently changed files, the files changed by the current delivery, mutation owner, capability roles, delivery mode, delivery outcome, test action and reason, command exit codes, checks, limitations, and final status.
+
+`changedFiles` preserves the complete dirty-workspace view used by safety checks.
+`deliveryChangedFiles` is the delta observed from the current execution baseline
+and is the only file set used to attribute the delivery outcome and test action.
+Pre-existing dirty work must never be claimed as the current delivery.
 
 The model must not manually author successful command results.
 
@@ -29,3 +34,8 @@ The model must not manually author successful command results.
 - `BLOCKED`
 
 A failed required command, protected-branch violation, missing meaningful validation, or unresolved material finding cannot be promoted to success.
+
+`COMPLETED` does not imply a diff by itself. `CHANGED` requires an observed
+workspace change and proportional validation. `ALREADY_SATISFIED` requires
+explicit verification without an artificial change. Read-only and preview
+outcomes must not claim implementation.

package/dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md

@@ -4,6 +4,22 @@ This document defines the shared execution contracts, quality gates, and finaliz
 
 ---
 
+## Ownership boundary
+
+Skills and skill-backed specialist roles are capabilities, not autonomous
+mutation owners. Atlas routes workspace implementation to Astra. Phoenix owns
+only bounded remediation of observed findings. A specialist may provide analysis,
+candidate content, or validation guidance to the active owner, but it must not:
+
+- accept direct workspace-delivery ownership from Atlas;
+- edit repository files unless Astra or Phoenix explicitly delegated that
+  bounded capability inside an authorized branch;
+- replace a requested repository change with printed code;
+- claim terminal workflow completion.
+
+If the delegation does not identify the active mutation owner and delivery mode,
+return the missing context instead of assuming ownership.
+
 ## Behavioral contract core
 
 All executing agents and specialist roles must respect these rules:

package/dist-assets/schemas/README.md

@@ -39,6 +39,10 @@ For normal Markdown documents, use the schemas as a checklist. A document does n
 | `pr-breakdown.schema.json` | Pull request breakdown shape |
 | `handoff.schema.json` | Agent handoff shape |
 | `validation-report.schema.json` | Validation report shape |
+| `evidence.schema.json` | Observed delivery, validation, outcome, and test-action evidence |
+
+In evidence artifacts, `changedFiles` is the full dirty-workspace view and
+`deliveryChangedFiles` is the delta attributable to the current execution.
 
 ## Validation
 

package/dist-assets/schemas/evidence.schema.json

@@ -35,6 +35,34 @@
         "type": "string"
       }
     },
+    "deliveryChangedFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "mutationOwner": {
+      "type": ["string", "null"],
+      "enum": ["Astra", "Phoenix", "ControlPlane", null]
+    },
+    "capabilitiesUsed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "deliveryMode": {
+      "enum": ["workspace", "answer-only"]
+    },
+    "deliveryOutcome": {
+      "enum": ["CHANGED", "ALREADY_SATISFIED", "READ_ONLY_RESULT", "PREVIEW_ONLY", "NEEDS_CLARIFICATION", "NOT_DELIVERED"]
+    },
+    "testAction": {
+      "enum": ["reuse", "extend", "add", "none"]
+    },
+    "testReason": {
+      "type": "string"
+    },
     "status": {
       "enum": ["COMPLETED", "COMPLETED_WITH_NOTES", "BLOCKED"]
     },
@@ -138,5 +166,36 @@
         }
       }
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "deliveryMode": { "const": "workspace" },
+          "deliveryOutcome": { "const": "CHANGED" }
+        },
+        "required": ["deliveryMode", "deliveryOutcome"]
+      },
+      "then": {
+        "required": ["mutationOwner", "commands"],
+        "properties": {
+          "mutationOwner": {
+            "enum": ["Astra", "Phoenix"]
+          },
+          "commands": {
+            "type": "array",
+            "minItems": 1,
+            "contains": {
+              "type": "object",
+              "required": ["kind", "status"],
+              "properties": {
+                "kind": { "not": { "const": "other" } },
+                "status": { "enum": ["PASS", "PASS_WITH_NOTES"] }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

package/package.json

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

package/{validate-IEHLAVZ6.js → validate-F3ZH63LI.js}

@@ -3,8 +3,8 @@ import {
   QualityGuard,
   ValidationPlanner,
   VisualVerifier
-} from "./chunk-Y4RLP6ZM.js";
-import "./chunk-XW747GIG.js";
+} from "./chunk-LD7EHAU2.js";
+import "./chunk-H7GIKXFO.js";
 import "./chunk-5WRI5ZAA.js";
 
 // src/cli/commands/validate.ts
@@ -86,4 +86,4 @@ async function runValidate({
 export {
   runValidate
 };
-//# sourceMappingURL=validate-IEHLAVZ6.js.map
+//# sourceMappingURL=validate-F3ZH63LI.js.map