@williambeto/ai-workflow 2.4.9 → 2.6.3

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

@@ -18,7 +18,7 @@ Installs AI Workflow Kit assets into a consumer project.
 
 **Synopsis:**
 ```bash
-ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--profile=<profile>] [--gemini] [--claude] [--codex] [--antigravity]
+ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--profile=<profile>] [--claude] [--codex] [--antigravity]
 ```
 
 **Description:**
@@ -32,14 +32,13 @@ Creates the `.ai-workflow/` directory with agents, skills, commands, policies, a
 | `--no-install` | Skip installing npm dependencies |
 | `--no-overwrite` | Do not overwrite any existing files |
 | `--profile=<profile>` | Installation profile: `standard` (default) or `full` (includes examples) |
-| `--gemini` | Install Gemini platform adapter configuration |
 | `--claude` | Install Claude platform adapter configuration |
 | `--codex` | Install Codex platform adapter configuration |
 | `--antigravity` | Install Antigravity platform adapter configuration |
 
 **Example:**
 ```bash
-ai-workflow init --yes --profile=full --gemini --claude
+ai-workflow init --yes --profile=full --antigravity --claude
 ```
 
 ---
@@ -54,7 +53,7 @@ ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
 ```
 
 **Description:**
-Accepts a natural language request, classifies intent, selects the appropriate workflow mode, creates a safe branch, delegates to the right agent, runs observed validation, and returns a structured delivery summary.
+Accepts a natural language request, classifies intent, selects the appropriate proportional policies, creates a safe branch, delegates to the right agent, runs observed validation, and returns a structured delivery summary.
 
 | Flag | Description |
 | --- | --- |
@@ -129,19 +128,20 @@ ai-workflow collect-evidence [--task=<slug>] [--mode=<mode>] [--dry-run] [--visu
 ```
 
 **Description:**
-Executes validation scripts, collects results, and produces a delivery summary. In `full` mode, persists an `EVIDENCE.json` artifact. Returns one of three statuses: `COMPLETED`, `COMPLETED_WITH_NOTES`, or `BLOCKED`.
+Executes validation scripts, collects results, and produces a delivery summary. Under the required evidence policy, persists an `EVIDENCE.json` artifact. Returns one of three statuses: `COMPLETED`, `COMPLETED_WITH_NOTES`, or `BLOCKED`.
 
 | Flag | Description |
 | --- | --- |
 | `--task=<slug>` | Optional task slug to associate with the evidence |
-| `--mode=<mode>` | Validation mode: `quick`, `standard` (default), or `full` |
+| `--evidence-policy=<policy>` | Controls whether EVIDENCE.json is persisted: `optional` or `required` |
+| `--mode=<mode>` | (Deprecated) Legacy validation mode compatibility mapping: `quick`, `standard`, or `full` |
 | `--dry-run` | Run checks without writing `EVIDENCE.json` |
 | `--visual-dist=<path>` | Path to built frontend assets for visual validation |
 | `--port=<port>` | Port for serving frontend assets |
 
 **Example:**
 ```bash
-ai-workflow collect-evidence --mode=full --task=auth-feature
+ai-workflow collect-evidence --evidence-policy=required --task=auth-feature
 ai-workflow collect-evidence --dry-run
 ```
 

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

@@ -25,21 +25,13 @@ npx @williambeto/ai-workflow init --yes --claude
 
 Review `CLAUDE.md` and `.claude/rules/`. Existing user-authored instructions must not be overwritten without backup and explicit intent.
 
-## Gemini CLI
-
-```bash
-npx @williambeto/ai-workflow init --yes --gemini
-```
-
-Review `GEMINI.md` and `.gemini/`. Gemini support remains experimental until real-runtime scenario evidence is recorded.
-
 ## Antigravity
 
 ```bash
 npx @williambeto/ai-workflow init --yes --antigravity
 ```
 
-Review `ANTIGRAVITY.md` and `.agents/`. Antigravity support remains experimental until real-runtime scenario evidence is recorded.
+Review `ANTIGRAVITY.md` and `.agents/`. Antigravity is supported and acts as the primary reference ecosystem for configuring and executing specialized agents and skills.
 
 ## Multiple adapters
 

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

@@ -12,7 +12,6 @@
 | 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` |
 | 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 |
-| Gemini CLI | Experimental | `GEMINI.md`, `.gemini/agents/`, `.gemini/skills/`, `.gemini/commands/` | adapter/unit/structural checks and generated asset inspection | Native discovery and command behavior require real Gemini CLI validation before `Supported` |
 | 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`) |
 
 ## Claim policy
@@ -24,8 +23,8 @@ Compatibility levels must be based on evidence available in the release. Adapter
 A runtime may be promoted only after a clean consumer test records:
 
 1. package installation;
-2. `init` with the runtime flag;
-3. expected generated assets;
-4. runtime startup or configuration validation;
-5. at least one quick workflow scenario;
-6. known limitations and failures.
+1. `init` with the runtime flag;
+1. expected generated assets;
+1. runtime startup or configuration validation;
+1. at least one low-risk workflow scenario;
+1. known limitations and failures.

package/dist-assets/docs/consumer-onboarding.md

@@ -6,12 +6,12 @@ Atlas will:
 
 1. inspect project context;
 2. verify branch safety before writes;
-3. select quick, standard, or full mode;
+3. select proportional risk and evidence policies;
 4. apply the closest domain profile;
 5. delegate only when it improves quality;
 6. run relevant validation;
 7. return a concise delivery summary.
 
-Quick and standard work do not require owner JSON, fixed workflow filenames, checklists, or `EVIDENCE.json`. Full, release, audit, security, and migration workflows may persist structured evidence.
+Workflows under the optional evidence policy do not require owner JSON, fixed workflow filenames, checklists, or EVIDENCE.json. Workflows under the required evidence policy (high-risk, release, audit, security, or migration tasks) must persist structured evidence.
 
 A failed required command or unsafe protected-branch state always finishes `BLOCKED`.

package/dist-assets/docs/design-patterns-policy.md

@@ -112,7 +112,7 @@ Do not introduce these unless explicitly justified by current complexity and arc
 For workflow kits, CLIs, validators, presets, templates, and npm-package-style code:
 
 - prefer Command for CLI actions/validation tasks;
-- prefer Strategy for interchangeable execution modes;
+- prefer Strategy for interchangeable execution algorithms;
 - prefer Adapter for OpenCode/GitHub/filesystem/package-manager integrations;
 - prefer Simple Factory for config-based creation;
 - prefer Builder for generated documents/reports;

package/dist-assets/docs/npm-consumer-quickstart.md

@@ -1,141 +1,102 @@
-# npm Consumer Quickstart
+# NPM Consumer Quickstart & Onboarding
 
-## Purpose
+An operational onboarding guide for integrating the AI Workflow Kit (AIWK) into your codebase.
 
-This guide explains what to do after installing `@williambeto/ai-workflow` in your project.
+---
 
-## Install the package
+## 🔒 Enterprise Security & Reliability Gates
 
-Add the package to your project:
+AIWK is designed under a **Zero Regression Guarantee**. It acts as an orchestrator and validator that sandboxes AI agent execution:
+- **No Production Disruptions**: It operates strictly on ephemeral feature branches. Merges to `main` or `master` are blocked until gates pass.
+- **Observed Quality Gates**: Every code modification must satisfy visual regression, formatting, unit tests, and accessibility checks before generating delivery evidence.
+- **Clean Execution**: Backup mechanisms preserve any local changes if cleanups are triggered during failure remediation loops.
 
-```bash
-npm install @williambeto/ai-workflow
-```
+---
 
-Or install globally for CLI access:
+## 📦 1. Installation
+
+Integrate AIWK into your development workspace:
 
 ```bash
+# Add as a development dependency
+npm install -D @williambeto/ai-workflow
+
+# Or install globally for general CLI access
 npm install -g @williambeto/ai-workflow
 ```
 
-## Inspect the installed package
-
-Verify the package installed correctly:
+Verify that the executable resolves correctly:
 
 ```bash
-npm pack @williambeto/ai-workflow --dry-run
-npx @williambeto/ai-workflow --help
+npx ai-workflow doctor
 ```
 
-The package provides:
-
-- a CLI binary (`ai-workflow`);
-- core scripts for `init`, `doctor`, and workflow validation;
-- template and skill references that the CLI installs into your project.
+---
 
-## Initialize workflow assets
+## 🚀 2. Initializing Your Codebase
 
-Run the CLI to create project-local workflow files:
+Bootstrap the managed workflow assets inside your repository. This process generates instructions, commands, templates, and safety configurations for AI agents:
 
 ```bash
-npx @williambeto/ai-workflow init --yes
-npx @williambeto/ai-workflow doctor
+npx ai-workflow init --yes
 ```
 
-The `init` command creates:
+> [!TIP]
+> Use the `--profile=full` flag if you want to include reference template files and detailed implementation examples.
+> Use `--dry-run` to preview the files that will be generated before writing to disk.
 
-- `README.workflow.md` — project-local workflow instructions;
-- `.ai-workflow.json` — install metadata;
-- managed `opencode.jsonc` sections;
-- `opencode/README.md` — OpenCode command reference;
-- starter agent and skill files.
+### What is generated?
+1. **`.ai-workflow/`**: The core directory containing your project's customized agent configurations, prompts, and templates.
+2. **`opencode.jsonc`**: Configuration mappings linking your AI runtime (OpenCode, Claude, Codex, etc.) to the AIWK agent team.
+3. **`README.workflow.md`**: Symlinked to the root as the first file that any AI agent reads to align with your project rules.
 
-Use `--dry-run` to preview changes before writing:
+---
 
-```bash
-npx @williambeto/ai-workflow init --dry-run
-```
+## 🤖 3. The OpenCode Workflow CLI
 
-## How workflow assets work
+Once initialized, you can launch your agent team using the `opencode` runtime, which uses the commands defined by the AIWK:
 
-The `init` command installs workflow assets into `.ai-workflow/` and creates symlinks in expected project paths (`.agents/`, `opencode/`, `prompts/`, and others). These linked assets become the source of truth for workflow behavior:
+| Command | Purpose | Lifecycle Phase |
+| --- | --- | --- |
+| **`Atlas`** | Routing entrypoint & Classification | Intake |
+| **`discover`** | Gather project files and context | Intake |
+| **`spec-create`** | Create a functional specification | Specification |
+| **`spec-review`** | Verify and review specification scope | Specification |
+| **`plan`** | Formulate a technical implementation plan | Planning |
+| **`implement`** | Execute code changes for a single PR | Implementation |
+| **`validate`** | Run tests, visual gates, and collect evidence | Validation |
+| **`deploy`** | Evaluate deployment and release readiness | Release |
 
-- `README.workflow.md` is symlinked from `.ai-workflow/README.workflow.md` and is the first file an agent should read.
-- Workflow-managed assets should be edited in `.ai-workflow/` when customization is intentional.
-- The package remains available for future updates (`npm update @williambeto/ai-workflow`).
-- Run `npx @williambeto/ai-workflow init --force` to regenerate managed files when the package is updated.
-- Backup copies of replaced files are stored in `.ai-workflow-backups/`.
+---
 
-There is no `.workflow/` directory in this onboarding path. Legacy `.workflow` submodule guidance is deprecated for npm consumers. Workflow assets are managed under `.ai-workflow/` with symlinks in project-root paths for tool compatibility.
+## 📊 4. Onboarding Checklist
 
-## OpenCode quickstart
+After running `init`, check off these items to verify integration success:
 
-After `init`, OpenCode users can start the workflow:
+- [ ] `npx ai-workflow doctor` reports a fully green/PASS status.
+- [ ] `README.workflow.md` is visible at your project root.
+- [ ] `opencode.jsonc` has been successfully created/updated.
+- [ ] Standard test scripts (`npm test`) run and pass locally.
+- [ ] The `.ai-workflow/` folder is committed to your repository so all developers share the same AI safety gates.
 
-```bash
-opencode
-```
+---
+
+## 🔍 5. Troubleshooting & FAQ
+
+| Problem | Cause | Solution |
+| --- | --- | --- |
+| **Windows Symlink Errors** | Lacks permission to link files from `.ai-workflow/`. | Enable **Developer Mode** in Windows Settings or run your terminal as Administrator. |
+| **`doctor` reports missing files** | Accidental file deletions in the configuration paths. | Re-run `npx ai-workflow init --force` to restore missing templates. |
+| **Tests fail on `collect-evidence`** | A quality gate is failing or the `test` script is missing. | Verify your `package.json` has a valid `test` script. AIWK blocks delivery if tests exit with non-zero codes. |
+| **`ERR_MODULE_NOT_FOUND`** | Deprecated Node.js runtime or execution paths. | Ensure you are running Node.js **>= 20.11** and executing the CLI from your project root. |
+
+---
+
+## 📖 6. Recommended Next Steps
 
-Then use these commands from the OpenCode TUI:
-
-| Command | Purpose |
-| --- | --- |
-| `Atlas` | Default routing entrypoint |
-| `discover` | Project context gathering |
-| `spec-create` | Specification creation |
-| `spec-review` | Specification review |
-| `plan` | Create a plan from a requirement |
-| `implement` | Implement one selected PR |
-| `validate` | Validate work with evidence |
-| `deploy` | Prepare deployment readiness |
-
-For agent routing and subagent delegation, see `opencode/agents/`.
-
-## Validation checklist
-
-After `init` and `doctor`, confirm:
-
-- [ ] `npx @williambeto/ai-workflow doctor` reports no errors
-- [ ] `npm run validate` passes (or project-specific validation commands)
-- [ ] `README.workflow.md` exists at the project root
-- [ ] `opencode.jsonc` contains managed sections
-- [ ] OpenCode config is present (`opencode.jsonc`)
-- [ ] No unintended file changes outside workflow-managed paths
-- [ ] Review backup files in `.ai-workflow-backups/` if any exist
-
-## Troubleshooting
-
-| Problem | Likely cause and fix |
-| --- | --- |
-| `npx` command not found | Install Node.js 20+ and npm. |
-| Init fails with permission error | Run in a project directory where you have write access. |
-| `doctor` reports missing files | Run `npx @williambeto/ai-workflow init --force` to regenerate. |
-| Init fails creating symlink | Windows: enable Developer Mode or run terminal as Administrator. Linux/macOS: verify write permissions and rerun `npx @williambeto/ai-workflow init --force`. |
-| OpenCode does not recognize commands | Confirm `opencode.jsonc` was created and contains the expected managed sections. |
-| Commands not available | Run `npx @williambeto/ai-workflow init --force` to regenerate command files. |
-| Conflicts with existing files | Preview with `--dry-run`, then use `--no-overwrite` to skip conflicting files. |
-| Backup files accumulate | Clean `rm -rf .ai-workflow-backups/` when backups are no longer needed. |
-| Package version needs update | Run `npm update @williambeto/ai-workflow`. |
-
-## Next recommended workflow
-
-After install, `init`, `doctor`, and validation pass:
-
-1. Pick one small feature or documentation change in your project.
-2. Start with `README.workflow.md` and your local project rules.
-3. Create a requirement before writing code.
-4. Write a functional specification for shared understanding.
-5. Create a technical plan before implementation.
-6. Split the work into small reviewable PRs.
-7. Implement only the first PR.
-8. Review and validate before continuing.
-
-For a guided walkthrough, see:
-
-- [`QUICKSTART.md`](QUICKSTART.md) (consolidated walkthrough)
-- [`runbooks/apply-starter-to-real-project.md`](../runbooks/apply-starter-to-real-project.md)
-
-## Reference
-
-- Package source: <https://github.com/williambeto/ai-workflow>
-- OpenCode docs: <https://opencode.ai/docs>
+1. **Configure Rules**: Open [AGENTS.md](../../AGENTS.md) and adapt the project-specific policies.
+2. **Setup E2E Tools**: For visual and accessibility gates, ensure `playwright` is installed in `devDependencies` and run `npx playwright install chromium`.
+3. **Execute a Test Task**: Run a test command to watch the agents work:
+   ```bash
+   npx ai-workflow execute "Update the repository contributing guide"
+   ```

package/dist-assets/docs/policies/01-BRANCH_GATE.md

@@ -13,7 +13,7 @@ Branch Gate is a safety mechanism, not a dead end.
 
 `main` and `master` are protected for direct writes.
 
-For write-capable `quick`, `standard`, or `full` workflow work invoked on `main`/`master`:
+For write-capable tasks invoked on `main`/`master`:
 
 1. create a safe scoped branch when the repository state allows it;
 2. verify the branch changed;

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

@@ -2,7 +2,7 @@
 
 Evidence exists to help the user trust the delivery. It must not become the delivery itself.
 
-## Quick and standard work
+## Optional evidence policy work
 
 No fixed workflow filename, owner JSON, checklist, or `EVIDENCE.json` is required.
 
@@ -16,7 +16,7 @@ The final handoff must state:
 
 A report written by an agent is not proof that a command ran. Command results must come from observed execution.
 
-## Full, release, audit, and security work
+## 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.
 

package/dist-assets/docs/policies/08-PRODUCT_TRUTHFULNESS_AND_PROJECT_DOCS.md

@@ -15,4 +15,4 @@ Truthfulness is primarily a semantic review responsibility. Keyword matching is
 
 Update documentation when setup, usage, public behavior, architecture, or operational expectations changed. Do not create documentation solely to satisfy a gate.
 
-For small work, a concise final summary may be sufficient. Full, release, migration, and audit work may justify persisted documentation.
+For low-risk work, a concise final summary may be sufficient. High-risk, release, migration, and audit work may justify persisted documentation.

package/dist-assets/docs/policies/10-BEHAVIORAL_CONTRACT_HARDENING.md

@@ -6,4 +6,4 @@ The runtime hardens three outcomes, not report formatting:
 2. existing relevant validation is executed and observed;
 3. failed or unavailable required validation cannot become success.
 
-Prompt text, workflow filenames, owner labels, and checklists are not independent proof. Quick and standard workflows remain proportionate. Full workflows may persist structured runtime evidence.
+Prompt text, workflow filenames, owner labels, and checklists are not independent proof. Workflows under the optional evidence policy remain proportionate. Workflows under the required evidence policy must persist structured runtime evidence.

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

@@ -1,15 +1,14 @@
 # Orchestration protocol
 
-## Quick
+The AI Workflow Kit operates under a single, mandatory orchestration protocol:
+Request → Planning → Branch Gate → Delegation → Implementation → Validation → Evidence
 
-Inspect → safe branch → edit → targeted validation → concise handoff.
+Proportional constraints adapt gate checks and depth according to the active policies (`riskLevel`, `evidencePolicy`, `remediationLimit`, `specPolicy`).
 
-## Standard
+## Policies
 
-Understand → brief plan → safe branch → implement → relevant validation → bounded remediation when needed → concise handoff.
+- **Low Risk:** Streamlined targeted validation and checklist-based quality gates.
+- **Medium Risk:** Comprehensive planning, PR breakdown, relevant test suite validation, and automated healing.
+- **High Risk:** Thorough discovery/specification, technical planning, independent validation, and persisted machine-generated evidence.
 
-## Full
-
-Discovery/specification → safe branch → specialist implementation → independent validation → bounded remediation → revalidation → persisted evidence → final decision.
-
-Protected-branch safety, required validation, and false-success prevention apply to every write-capable mode.
+Protected-branch safety, required validation, and false-success prevention apply to every write-capable task.

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

@@ -2,19 +2,13 @@
 
 Artefacts are proportional to risk and future value.
 
-## Quick
+## Optional Evidence Policy
 
-No mandatory persisted artefact. Provide a concise final summary with validation evidence.
+No mandatory persisted artefact. Update project documentation only when behavior, setup, usage, or architecture changed. Provide a concise final summary with validation evidence.
 
-## Standard
+## Required Evidence Policy
 
-No mandatory filename or document set. Update project documentation only when behavior, setup, usage, or architecture changed.
-
-A delivery report is optional when it helps review or handoff.
-
-## Full
-
-Persist a concise evidence package appropriate to the task. It should record requirements or scope, implementation, validation, unresolved limitations, and final decision without duplicating the same information across several files.
+Persist a concise evidence package (EVIDENCE.json) appropriate to the task. It should record requirements or scope, implementation, validation, unresolved limitations, and final decision without duplicating the same information across several files.
 
 ## Rule
 

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

@@ -11,7 +11,7 @@ All executing agents and specialist roles must respect these rules:
 - **Ownership**: Use the owning primary agent; a skill supplies domain judgment and must not pretend that delegation occurred.
 - **Reference Lookups**: Load the project conventions and the domain references named by this skill before making decisions.
 - **Truthfulness**: Do not invent capabilities, integrations, metrics, users, evidence, validation, security properties, or completed work.
-- **Proportionality**: Use the smallest safe execution mode and keep artifacts proportional.
+- **Proportionality**: Use the smallest safe proportional policies and keep artifacts proportional.
 - **Delivery Support**: Implementation support must include relevant documentation, tests, validation, and current-task evidence.
 - **No Compromise**: A blocking finding remains `FAIL_QUALITY_GATE` or `BLOCKED`; never soften it to obtain completion.
 

package/dist-assets/docs/profiles/README.md

@@ -1,6 +1,6 @@
 # Workflow Profiles
 
-Workflow profiles guide domain quality without turning subjective preferences into universal runtime gates. Execution mode controls artifact depth; workflow profile controls domain guidance.
+Workflow profiles guide domain quality without turning subjective preferences into universal runtime gates. Proportional policies control artifact depth; workflow profile controls domain guidance.
 
 The core remains deterministic: branch safety, scope, ownership, tests/build/typecheck, artifacts, evidence, truthfulness contradictions, bounded remediation, and final status.
 
@@ -16,4 +16,4 @@ Available profiles:
 - `security-review`
 - `generic`
 
-A profile is independent from execution mode. Example: `standard + frontend-utility`.
+A profile is independent from active policies. Example: `riskLevel: medium + frontend-utility`.

package/dist-assets/docs/specs/runtime-operational-contract.md

@@ -12,25 +12,25 @@ Turn a natural software request into a safe, useful, validated delivery with pro
 - bounded remediation with `BLOCKED` on no progress;
 - no fabricated command, test, file, or agent claims.
 
-## Modes
+## Proportional Policies
 
-### Quick
+The AI Workflow Kit runtime operates on a single, mandatory path:
+Request → Planning → Branch Gate → Delegation → Implementation → Validation → Evidence
 
-Inspect → safe branch → edit → targeted validation → concise handoff.
+Operational constraints adapt proportionally using explicit policies:
+- `riskLevel`: `low | medium | high` (controls gate checks and validation depth)
+- `evidencePolicy`: `optional | required` (determines whether a persisted EVIDENCE.json is mandatory)
+- `remediationLimit`: `number` (enforces attempt limits for automatic remediation)
+- `specPolicy`: `none | required` (determines whether a specification document is required)
 
-### Standard
-
-Understand → brief plan → safe branch → implement → relevant validation → bounded remediation when needed → concise handoff.
-
-### Full
-
-Discovery/specification → safe branch → specialist implementation → independent validation → bounded remediation → revalidation → persisted evidence → final decision.
+> [!NOTE]
+> Legacy modes (`quick`, `standard`, and `full`) are deprecated. They exist only as CLI-level parsing fallbacks and historical metadata tags, never as active runtime controllers.
 
 ## Evidence
 
-Quick and standard modes report branch, changed areas, observed commands/results, and limitations. No fixed workflow filenames or owner JSON are required.
+Workflows under the `optional` evidence policy report the branch, changed areas, observed commands/results, and limitations. No fixed workflow filenames or owner JSON are required to be saved.
 
-Full, release, audit, security, migration, and explicitly requested workflows may persist machine-generated evidence.
+Workflows under the `required` evidence policy (high-risk, release, audit, or explicitly requested tasks) must persist machine-generated evidence as an `EVIDENCE.json` file.
 
 ## Public completion states
 

package/dist-assets/docs/troubleshooting-guide.md

@@ -8,9 +8,9 @@ Move to a scoped branch. If tracked dirty work makes recovery unsafe, preserve i
 
 Inspect the command results. Fix failed tests/build/typecheck/lint, or add a meaningful validation path when none exists. Do not add no-op scripts or workflow documents as substitutes.
 
-## Standard work did not create EVIDENCE.json
+## Optional evidence policy did not create EVIDENCE.json
 
-Expected. Quick and standard work use concise observed evidence. Persisted evidence is reserved for full, release, audit, security, migration, or explicitly requested work.
+Expected. Workflows under the optional evidence policy use concise observed evidence. Persisted evidence is reserved for required evidence, release, audit, security, migration, or explicitly requested work.
 
 ## UI or product quality is weak
 

package/dist-assets/docs/visual-validation-guide.md

@@ -69,9 +69,9 @@ Subjective quality (color harmony, readable contrast, visual hierarchy) cannot b
 You can configure a specialized `ux-auditor` agent or load a skill containing these rules:
 
 1. **Hierarchy & Composition**: The first fold must look like a cohesive layout. Check that headings, buttons, and graphics do not overlap or look cluttered.
-2. **Color Contrast & Accessibility**: Ensure contrast between text and background is high. Avoid using unstyled bright primary colors (e.g., plain red/blue/green) without proper styling.
-3. **Typography**: Typography must use a modern system (e.g., Google Fonts) instead of browser defaults. Line heights should be balanced.
-4. **Responsiveness**: Verify that the mobile render does not cut off text or overflow horizontally.
+1. **Color Contrast & Accessibility**: Ensure contrast between text and background is high. Avoid using unstyled bright primary colors (e.g., plain red/blue/green) without proper styling.
+1. **Typography**: Typography must use a modern system (e.g., Google Fonts) instead of browser defaults. Line heights should be balanced.
+1. **Responsiveness**: Verify that the mobile render does not cut off text or overflow horizontally.
 
 If the Vision LLM finds aesthetic defects, it outputs a `FAIL_QUALITY_GATE` status along with coordinates or descriptions of the design bugs, which are then passed to the `HealerEngine` for remediation.
 

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

@@ -0,0 +1,109 @@
+{
+  "$id": "https://github.com/williambeto/ai-workflow/schemas/evidence.schema.json",
+  "title": "Evidence Artifact",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "timestamp",
+    "changedFiles",
+    "status",
+    "internalStatus",
+    "commands"
+  ],
+  "properties": {
+    "timestamp": {
+      "type": "string"
+    },
+    "taskSlug": {
+      "type": ["string", "null"]
+    },
+    "executionMode": {
+      "type": "string"
+    },
+    "workflowProfile": {
+      "type": "string"
+    },
+    "branchRecovery": {
+      "type": "string"
+    },
+    "branch": {
+      "type": "string"
+    },
+    "changedFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "status": {
+      "enum": ["COMPLETED", "COMPLETED_WITH_NOTES", "BLOCKED"]
+    },
+    "internalStatus": {
+      "enum": ["PASS", "PASS_WITH_NOTES", "BLOCKED"]
+    },
+    "commands": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": [
+          "name",
+          "command",
+          "kind",
+          "status"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "command": {
+            "type": ["string", "object", "array"]
+          },
+          "kind": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          },
+          "exitCode": {
+            "type": ["number", "null"]
+          },
+          "signal": {
+            "type": ["string", "null"]
+          },
+          "summary": {
+            "type": "string"
+          },
+          "output": {
+            "type": "string"
+          },
+          "commitHash": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "checks": {
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "limitations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "deliveryDecision": {
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "artifactFidelityCheck": {
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "visualEvidence": {
+      "type": ["object", "null"],
+      "additionalProperties": true
+    }
+  }
+}