@williambeto/ai-workflow 2.8.0 → 2.8.2

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.2",
   "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-DDKN6ORS.js}

@@ -3,8 +3,8 @@ import {
   QualityGuard,
   ValidationPlanner,
   VisualVerifier
-} from "./chunk-Y4RLP6ZM.js";
-import "./chunk-XW747GIG.js";
+} from "./chunk-GLYX3HEY.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-DDKN6ORS.js.map