@williambeto/ai-workflow 2.9.3 → 2.9.5

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [unreleased]
 
+## [2.9.5] - 2026-07-17
+
+### 🛡️ Hardening
+
+- Declare the 17 required command-to-policy relationships through a
+  runtime-neutral canonical policy section
+- Fail validation when required command policy references are missing,
+  duplicated, unknown, or unexpected
+
+### 🧪 Testing
+
+- Add data-driven contract coverage for the complete policy reference map
+- Verify referenced policies remain available in OpenCode installations and
+  Codex command skills
+
+## [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

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/dist-assets/commands/atlas.md

@@ -31,6 +31,13 @@ Route user requests safely, proportionately, and securely according to the permi
 - Route workspace implementation to Astra, never directly to a skill-backed specialist.
 - Printed code is not a substitute for a requested repository change.
 
+## Canonical policies
+Resolve these policy files from the policies directory declared in `.ai-workflow/config.json`:
+- `01-BRANCH_GATE.md`
+- `03-QUALITY_GATE.md`
+- `05-AGENT_CONTRACT.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`
+
 ## Allowed tools
 - classify request
 - evaluate routing permissions

package/dist-assets/commands/deploy.md

@@ -32,6 +32,12 @@ Execute package publication or deployment securely after passing validation chec
 - Do not deploy if any validation check fails.
 - Do not claim deploy execution without verified deploy logs.
 
+## Canonical policies
+Resolve these policy files from the policies directory declared in `.ai-workflow/config.json`:
+- `01-BRANCH_GATE.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`
+- `07-RELEASE_GATE.md`
+
 ## Allowed tools
 - execute deployment scripts
 - run environment smoke tests

package/dist-assets/commands/implement.md

@@ -31,6 +31,13 @@ Implement a small task with defined scope, verifying changes incrementally.
 - Do not claim implementation without validation evidence.
 - Treat the finalizer exit code and public status as authoritative.
 
+## Canonical policies
+Resolve these policy files from the policies directory declared in `.ai-workflow/config.json`:
+- `01-BRANCH_GATE.md`
+- `03-QUALITY_GATE.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`
+- `PROCEDURE_UI_CHECKLIST.md`
+
 ## Allowed tools
 - read files
 - edit source files

package/dist-assets/commands/release.md

@@ -32,6 +32,12 @@ Coordinate the release process, verifying package status and generating release
 - Do not push to remote, publish to npm, or create git tags without user approval.
 - Do not claim release readiness without release evidence document.
 
+## Canonical policies
+Resolve these policy files from the policies directory declared in `.ai-workflow/config.json`:
+- `01-BRANCH_GATE.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`
+- `07-RELEASE_GATE.md`
+
 ## Allowed tools
 - read version configuration
 - update changelog

package/dist-assets/commands/validate.md

@@ -29,6 +29,12 @@ Execute validation checks and compile an evidence report showing quality status.
 - All validation commands must exit 0.
 - Do not claim validation success without evidence log.
 
+## Canonical policies
+Resolve these policy files from the policies directory declared in `.ai-workflow/config.json`:
+- `03-QUALITY_GATE.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`
+- `PROCEDURE_UI_CHECKLIST.md`
+
 ## Allowed tools
 - execute test commands
 - run code linters

package/package.json

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