@williambeto/ai-workflow 1.19.0 → 2.1.0

package/dist-assets/docs/adr/ADR-0006.md

@@ -0,0 +1,82 @@
+# ADR-0006: Evidence-First Validation
+
+- **Status**: Accepted
+- **Date**: YYYY-MM-DD
+- **Author**: José Willams
+
+## Context
+
+In autonomous AI workflows, agents frequently claim success ("the task is complete", "everything works") without verifiable proof. Without physical evidence of execution, these claims cannot be audited or validated. This creates risk when merging code or deploying changes.
+
+The project needed a mechanism to:
+- Require executable evidence for all validation claims
+- Collect and persist evidence in a structured, machine-readable format
+- Enforce that no success claim is valid without corresponding evidence
+
+## Decision
+
+Adopt **Evidence-First Validation**: every validation claim must be backed by executable evidence recorded in `EVIDENCE.json`.
+
+### Components
+
+1. **EvidenceCollector** (`src/core/validation/evidence-collector.js`):
+   - Auto-detects validation scripts from `package.json` (lint, test, validate)
+   - Runs each task and captures output, exit codes, and duration
+   - Generates structured `EVIDENCE.json` at project root
+   - Injects documentation-specific validation tasks when a docs-only task is detected
+
+2. **QualityGuard** (`src/core/validation/quality-guard.js`):
+   - Verifies policy compliance after evidence collection
+   - Checks UI evidence (screenshots) for UI tasks
+   - Checks self-review dimensions (security, performance, accessibility, etc.)
+   - Checks documentation consistency for docs tasks
+
+3. **Evidence Format**:
+   ```json
+   {
+     "overallStatus": "PASS" | "FAIL",
+     "tasks": [
+       {
+         "name": "lint",
+         "status": "PASS" | "FAIL",
+         "output": "...",
+         "exitCode": 0
+       }
+     ],
+     "policyValidation": {
+       "overallStatus": "PASS" | "FAIL",
+       "checks": { ... }
+     }
+   }
+   ```
+
+### Enforcement
+
+- `runMasterOrchestrator` runs evidence collection as Phase 2 (Validation & Self-Healing).
+- `runCollectEvidence()` persists results to `EVIDENCE.json`.
+- QualityGuard enforces policies after evidence is collected.
+- `AGENTS.md` hard constraint: "**Evidence-First**: No success claim is valid without executable evidence."
+
+## Consequences
+
+**Positive**:
+- All validation claims are backed by physical evidence.
+- Evidence is machine-readable and can be audited programmatically.
+- Quality policy violations are caught and reported with specific missing items.
+- Evidence persists across sessions for later review.
+
+**Negative**:
+- Evidence collection adds time to the pipeline.
+- Some evidence (e.g., UI screenshots) requires manual creation.
+- Large evidence files may bloat the repository if not managed.
+
+## Compliance
+
+- `src/commands/collect-evidence.js` orchestrates evidence collection.
+- `src/core/validation/evidence-collector.js` runs tasks and captures output.
+- `src/core/validation/quality-guard.js` enforces policy checks.
+- `EVIDENCE.json` is generated at project root and excluded from git via `.gitignore`.
+
+## Notes
+
+The evidence collector auto-detects standard npm scripts but can also run custom tasks. Documentation-specific validation tasks are injected when `isDocsTask()` returns true, ensuring that documentation changes are validated with appropriate checks (link validation, consistency).

package/dist-assets/docs/adr/ADR-0007.md

@@ -0,0 +1,78 @@
+# ADR-0007: Unified Private Monorepo Structure
+
+- **Status**: Accepted
+- **Date**: YYYY-MM-DD
+- **Author**: José Willams
+
+## Context
+
+The `@williambeto/ai-workflow` package started as a standalone tool but grew to include multiple concerns: core engine logic, CLI commands, platform adapters, documentation, specifications, validation scripts, and template files. Files were scattered across the repository without clear boundaries between:
+
+- Public API (`src/`) vs. internal tooling (`internal/`)
+- Specifications (`specs/`) vs. documentation (`assets/docs/`)
+- Package source (`packages/ai-workflow/`) vs. root configuration
+
+A unified structure was needed to clarify ownership, simplify imports, and provide clear separation between the distributed package and internal utilities.
+
+## Decision
+
+Adopt a **Unified Private Monorepo Structure** with the following top-level layout:
+
+```
+core/                          # Package root (published as @williambeto/ai-workflow)
+├── src/                       # Public API source code
+│   ├── adapters/              # Platform adapters (Gemini, Claude, Codex)
+│   ├── commands/              # CLI command implementations
+│   ├── cli.js                 # CLI entry point
+│   └── core/                  # Core engine modules
+│       ├── gates/             # BranchGate
+│       ├── healing/           # HealerEngine
+│       ├── sdd/               # SpecValidator
+│       ├── handoff/           # HandoffEngine
+│       └── validation/        # EvidenceCollector, QualityGuard
+├── assets/docs/               # Published documentation
+├── bin/                       # CLI binary
+├── internal/                  # Internal tooling (not published)
+│   ├── validate/              # Validation pipeline scripts
+│   └── docs/                  # Documentation generators
+├── specs/                     # Project specifications
+├── packages/                  # Workspace packages
+│   └── ai-workflow/           # (symlink or workspace)
+├── checklists/                # Readiness checklists
+├── tests/                     # E2E tests
+├── .opencode/                 # OpenCode agent/skill definitions
+├── openspec/                  # OpenSpec change definitions
+└── .ai-workflow/              # Managed workflow state (gitignored)
+```
+
+### Key Principles
+
+1. **Separation of public and internal**: `src/` is the public API; `internal/` is unpublished tooling.
+2. **Specifications are specifications**: `specs/` contains requirement and architecture documents. `assets/docs/` contains user-facing documentation.
+3. **Publisher control**: `package.json` `files` field explicitly lists what gets published.
+4. **Managed workspace**: `.ai-workflow/` is gitignored and regenerated via `ai-workflow init`.
+5. **Unified identity**: The package lives in `core/` and is published as `@williambeto/ai-workflow`.
+
+## Consequences
+
+**Positive**:
+- Clear separation between public API and internal utilities.
+- Published package is minimal (`bin`, `src`, `assets`, `opencode.jsonc`).
+- Specs are co-located with source, enabling Spec-Driven Development.
+- Monorepo structure supports future workspace expansion.
+
+**Negative**:
+- Some path references must account for `core/` prefix.
+- Migration from flat structure required renaming and refactoring.
+- Contributors must understand the public/internal boundary.
+
+## Compliance
+
+- `package.json` `files` field defines the published scope.
+- `internal/` scripts are not listed in `files` and are not published.
+- `internal/validate/` scripts are invoked by `npm run validate:*` but not distributed to consumers.
+- `specs/` is included in the repository but excluded from npm publish.
+
+## Notes
+
+The monorepo structure supports the unified package identity (`@williambeto/ai-workflow`). Future expansions (e.g., separate CLI package, web dashboard) would be added as additional workspace packages under `packages/`. The `internal/validate/validate-all.mjs` script references all 14 validation checks, ensuring the structure remains consistent.

package/dist-assets/docs/api-engine-reference.md

@@ -0,0 +1,7 @@
+# API Engine Reference
+
+This package distributes runtime contracts for agents, commands, skills, policies, schemas, and templates.
+
+## Runtime taxonomy
+
+Primary Agents own workflow accountability. Skill-backed Specialist Roles provide domain support through skills. Commands are entrypoints. Skills standardize domain practice.

package/{docs → dist-assets/docs}/architecture-policy.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Define the default architecture selection rule for Codex/OpenCode agents.
+Define the default architecture selection rule for AI-assisted workflow agents.
 
 Core decision:
 

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

@@ -0,0 +1,27 @@
+# CLI reference
+
+## `ai-workflow init`
+
+Installs the OpenCode-first workflow assets into a consumer project.
+
+## `ai-workflow doctor`
+
+Checks the local installation and generated configuration.
+
+## `ai-workflow run --spec-path=<path>`
+
+Runs formal orchestration for an approved specification. It enforces branch safety, observed validation, bounded remediation, and handoff generation.
+
+## `ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]`
+
+Runs relevant project validation scripts and objective quality checks.
+
+- quick/standard: prints a concise delivery summary and does not require `EVIDENCE.json`;
+- full: persists `EVIDENCE.json` unless `--dry-run` is used;
+- failed or unavailable required validation returns `BLOCKED`.
+
+## Public states
+
+- `COMPLETED`
+- `COMPLETED_WITH_NOTES`
+- `BLOCKED`

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

@@ -0,0 +1,38 @@
+# Provider Usage
+
+## OpenCode
+
+```bash
+npx @williambeto/ai-workflow init --yes
+npx @williambeto/ai-workflow doctor
+```
+
+Use `opencode.jsonc` and the generated OpenCode assets as the primary workflow interface.
+
+## 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.
+
+## Claude Code
+
+```bash
+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.
+
+## 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

@@ -0,0 +1,30 @@
+# Runtime Compatibility Matrix
+
+## Compatibility levels
+
+- **Primary:** native project target and most thoroughly exercised path.
+- **Supported:** generated integration and package-level smoke coverage exist; runtime limitations are documented.
+- **Supported with limitations:** assets are generated, but behavior is not equivalent to the primary runtime.
+- **Experimental:** adapter exists, but real-runtime evidence is insufficient for a stronger claim.
+
+| 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` |
+| 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` |
+
+## Claim policy
+
+Compatibility levels must be based on evidence available in the release. Adapter code or generated files alone are not proof of full behavioral parity.
+
+## Promotion requirements
+
+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.

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

@@ -0,0 +1,17 @@
+# Consumer onboarding
+
+Install and initialize the kit, then make a natural request to Atlas.
+
+Atlas will:
+
+1. inspect project context;
+2. verify branch safety before writes;
+3. select quick, standard, or full mode;
+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.
+
+A failed required command or unsafe protected-branch state always finishes `BLOCKED`.

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

@@ -0,0 +1,11 @@
+# Contributing Guide
+
+Contributions should preserve the AI Workflow Kit operating model: specify, plan, implement, document, test, validate, and provide evidence.
+
+## Required evidence
+
+- Scope and rationale.
+- Files changed.
+- Tests and validation commands.
+- Documentation impact.
+- Known risks.

package/{docs → dist-assets/docs}/design-patterns-policy.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Define when Codex/OpenCode agents may use formal design patterns.
+Define when AI-assisted workflow agents may use formal design patterns.
 
 Core decision:
 
@@ -113,7 +113,7 @@ For workflow kits, CLIs, validators, presets, templates, and npm-package-style c
 
 - prefer Command for CLI actions/validation tasks;
 - prefer Strategy for interchangeable execution modes;
-- prefer Adapter for Codex/OpenCode/GitHub/filesystem/package-manager integrations;
+- prefer Adapter for OpenCode/GitHub/filesystem/package-manager integrations;
 - prefer Simple Factory for config-based creation;
 - prefer Builder for generated documents/reports;
 - prefer Facade for install/bootstrap/validate/audit/release workflows;

package/dist-assets/docs/full-documentation.md

@@ -0,0 +1,113 @@
+# AI Workflow Kit Full Documentation
+
+AI Workflow Kit is an OpenCode-first workflow system for AI-assisted software delivery.
+
+This document summarizes the current v2 runtime model. Historical roadmaps, backlog files, migration notes, and obsolete planning artifacts are intentionally not part of the active runtime context. Git history is the archive.
+
+## Current runtime model
+
+- Commands start operational workflows.
+- Autopilot coordinates the safest next step.
+- Agents execute domain-specific work.
+- Skills standardize quality, patterns, and validation expectations.
+- Project Memory preserves durable decisions.
+- Validation proves the result.
+
+## Standard delivery flow
+
+1. Request
+2. Discover
+3. Spec draft
+4. Spec review
+5. Technical plan
+6. PR breakdown
+7. Implementation
+8. Documentation
+9. Automated tests when viable
+10. Validation
+11. Evidence report
+12. Commit / push, only when explicitly requested
+13. Merge, only when explicitly approved
+14. Approved release, only when explicitly approved
+
+## Non-negotiable runtime rules
+
+- Routing is not completion.
+- Branch Gate uses auto-recovery for safe write-capable work.
+- Documentation is required by default for implementations.
+- Automated tests are required when viable.
+- Build validation does not replace automated tests.
+- Missing viable tests must produce `FAIL_QUALITY_GATE`.
+- Evidence reports must include branch recovery, docs, tests, validation, risks, and final status.
+- Publish, deploy, tag, release, merge, and force-push require explicit approval.
+
+## Active runtime references
+
+In an initialized consumer, use:
+
+- `.ai-workflow/AGENTS.md`
+- `.ai-workflow/opencode/agents/*.md`
+- `.ai-workflow/opencode/commands/*.md`
+- `.ai-workflow/opencode/skills/*/SKILL.md`
+- `.ai-workflow/docs/policies/*.md`
+- `.ai-workflow/QUICKSTART.md`
+
+Repository maintainers edit the packaged sources under `dist-assets/**`.
+
+## Validation
+
+Run:
+
+```bash
+npm run validate
+npm pack
+```
+
+For consumer smoke:
+
+```bash
+npx ai-workflow --help
+npx ai-workflow init --yes
+npx @williambeto/ai-workflow doctor
+```
+
+## Active commands
+
+- atlas
+- run
+- discover
+- spec-create
+- spec-review
+- spec-implement
+- plan
+- implement
+- validate
+- audit
+- optimize-tokens
+- update-memory
+- release
+- deploy
+
+
+## Examples and runbooks
+
+Examples maturity: Complete (15 examples in catalog).
+
+Current v2 runbooks:
+
+- `runbooks/agent-delegation-workflow.md`
+- `runbooks/apply-starter-to-real-project.md`
+- `runbooks/branch-cleanup.md`
+- `runbooks/commands-cheatsheet.md`
+- `runbooks/deploy-checklist.md`
+- `runbooks/how-to-use-skills.md`
+- `runbooks/private-spec-publication-safety.md`
+- `runbooks/publication-readiness-checklist.md`
+- `runbooks/publish-package-checklist.md`
+- `runbooks/spec-driven-development.md`
+- `runbooks/team-governance-pr-readiness.md`
+- `runbooks/tutorial-walkthroughs.md`
+- `runbooks/use-linear-for-operational-planning.md`
+- `runbooks/use-napkin-project-memory.md`
+- `runbooks/validate-starter-in-real-project.md`
+- `runbooks/validation-checklist.md`

package/{docs → dist-assets/docs}/npm-consumer-quickstart.md

@@ -45,11 +45,10 @@ npx @williambeto/ai-workflow doctor
 The `init` command creates:
 
 - `README.workflow.md` — project-local workflow instructions;
-- `.ai-workflow.json` — install profile metadata;
-- managed `opencode.jsonc` sections (for `operational` and `full` profiles);
-- `.codex/prompts/README.md` — Codex prompt entrypoint reference;
+- `.ai-workflow.json` — install metadata;
+- managed `opencode.jsonc` sections;
 - `opencode/README.md` — OpenCode command reference;
-- starter agent and skill files (for the `full` profile).
+- starter agent and skill files.
 
 Use `--dry-run` to preview changes before writing:
 
@@ -59,7 +58,7 @@ npx @williambeto/ai-workflow init --dry-run
 
 ## How workflow assets work
 
-The `init` command installs workflow assets into `.ai-workflow/` and creates symlinks in expected project paths (`.codex/`, `.agents/`, `opencode/`, `prompts/`, and others). These linked assets become the source of truth for workflow behavior:
+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:
 
 - `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.
@@ -81,42 +80,16 @@ Then use these commands from the OpenCode TUI:
 
 | Command | Purpose |
 | --- | --- |
-| `/start` | Start workflow discovery |
-| `/plan` | Create a plan from a requirement |
-| `/execute` | Implement one selected PR |
-| `/review` | Review implementation |
-| `/validate` | Validate work with evidence |
-| `/orchestrate` | Run gate-based handoff routing |
-| `/ship` | Run end-to-end shipping workflow |
-| `/deploy` | Prepare deployment readiness |
+| `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/` and `opencode/agents/orchestrator.md`.
-
-## Codex quickstart
-
-After `init`, Codex users reference the local `.codex/prompts/README.md` for available entrypoints.
-
-Primary prompts:
-
-| Prompt file | Use |
-| --- | --- |
-| `.codex/prompts/start-project.md` | Start a project workflow |
-| `.codex/prompts/plan-from-requirement.md` | Turn a requirement into a plan |
-| `.codex/prompts/execute-selected-pr.md` | Implement one PR |
-| `.codex/prompts/review-implementation.md` | Review implementation |
-| `.codex/prompts/validate-work.md` | Validate with evidence |
-
-Copy the content of a prompt file into your Codex session, or use the CLI wrapper commands:
-
-```bash
-npx @williambeto/ai-workflow codex:start
-npx @williambeto/ai-workflow codex:plan
-npx @williambeto/ai-workflow codex:execute
-npx @williambeto/ai-workflow codex:review
-npx @williambeto/ai-workflow codex:validate
-```
-
-Codex users should treat [`AGENTS.md`](AGENTS.md) as the main operational contract.
+For agent routing and subagent delegation, see `opencode/agents/`.
 
 ## Validation checklist
 
@@ -125,8 +98,8 @@ 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 (for `operational`/`full` profiles)
-- [ ] Codex prompt placeholders exist (`.codex/prompts/`)
+- [ ] `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
 
@@ -139,7 +112,7 @@ After `init` and `doctor`, confirm:
 | `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. |
-| Codex prompts not shown | Use `--profile=full` to generate prompt starter files. |
+| 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`. |
@@ -159,11 +132,10 @@ After install, `init`, `doctor`, and validation pass:
 
 For a guided walkthrough, see:
 
-- [`runbooks/quick-start-guide.md`](runbooks/quick-start-guide.md) (consolidated walkthrough)
-- [`runbooks/apply-starter-to-real-project.md`](runbooks/apply-starter-to-real-project.md)
+- [`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>
-- Codex repo: <https://github.com/openai/codex>

package/dist-assets/docs/opencode-readme.md

@@ -0,0 +1,8 @@
+# OpenCode Runtime Assets
+
+- `agents/`: primary agent prompt contracts.
+- `commands/`: runtime command contracts.
+- `skills/`: reusable capability documents.
+- `docs/policies/`: canonical workflow policies.
+
+Use professional taxonomy: Primary Agents, Skill-backed Specialist Roles, Skills, and Commands.

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

@@ -0,0 +1,63 @@
+# Branch Gate Auto-Recovery
+
+Before any write-capable action, require branch awareness:
+
+```bash
+git branch --show-current
+git status --short
+```
+
+Branch Gate is a safety mechanism, not a dead end.
+
+### Protected branches
+
+`main` and `master` are protected for direct writes.
+
+For write-capable `quick`, `standard`, or `full` workflow work invoked on `main`/`master`:
+
+1. create a safe scoped branch when the repository state allows it;
+2. verify the branch changed;
+3. continue the original task from the correct owner/command;
+4. include branch recovery evidence in the final report.
+
+Do not stop after creating the branch. Branch recovery is not the deliverable.
+
+### Branch naming
+
+Use deterministic lowercase kebab-case names:
+
+- `feat/<short-task>` for new user-facing functionality;
+- `fix/<short-task>` for bug fixes and typos;
+- `docs/<short-task>` for documentation-only work;
+- `chore/<short-task>` for configuration, workflow, package, or runtime maintenance;
+- `refactor/<short-task>` for structure changes without behavior changes;
+- `test/<short-task>` for test-only work;
+- `release/<short-task>` for release preparation.
+
+Keep names short, avoid secrets/URLs, and add a numeric suffix if the branch exists.
+
+### Dirty state handling
+
+Classify dirty state before blocking:
+
+- expected generated workflow files, package lock changes, or `node_modules/` noise: preserve and continue when safe;
+- user-edited project files: create the branch preserving the state and report it;
+- merge conflicts, unresolved rebase, partial tool output, or unsafe unknown changes: stop with reason;
+- secrets or `.env` files: do not inspect or modify; warn and continue only if unrelated.
+
+### Restricted actions
+
+Do not auto-execute publish, deploy, tag, release, merge, push, force-push, broad deletion, or package-version changes without explicit approval. For restricted requests, create the preparation branch/plan if needed, but stop before the restricted action.
+
+### Branch recovery report
+
+Any agent/command that performs branch recovery must report:
+
+```md
+Branch recovery:
+- Branch before:
+- Dirty state:
+- Action:
+- Branch after:
+- Continue original task: yes/no
+```