wade-cli 0.52.0__tar.gz → 0.53.1__tar.gz

{wade_cli-0.52.0 → wade_cli-0.53.1}/.gitignore

@@ -37,6 +37,7 @@ htmlcov/
 .wade/
 CLAUDE.md
 PLAN.md
+!templates/workflows/plan.md
 PR-SUMMARY.md
 
 # OS

{wade_cli-0.52.0 → wade_cli-0.53.1}/AGENTS.md

@@ -15,13 +15,15 @@ Two distinct worlds interact in this codebase. Always be clear which one you are
 |------|---------|
 | **the WADE repo** / **this project** | This source repository — `src/wade/`, `templates/`, `tests/`, `scripts/` |
 | **inited project** / **target project** | Any third-party repo that has run `wade init` to adopt the workflow |
-| **skill templates** | Markdown files in `templates/skills/` — the source of truth, part of the WADE repo |
-| **installed skills** | Copies (or symlinks) of skill templates placed in a project's `.claude/skills/` **per session by worktree bootstrap** (`bootstrap_worktree`), not by `wade init` |
+| **workflow templates** | Fixed WADE lifecycle files in `templates/workflows/`; rendered to `.wade/session/WORKFLOW.md` and never replaceable by skill configuration |
+| **methodology skill templates** | WADE-agnostic replaceable methods in `templates/skills/` (planning, implementation, review, and dependency analysis) |
+| **session skill snapshots** | Immutable copies of active and available skills under `.wade/session/skills/`, including project skills discovered from the worktree and main checkout |
+| **support skills** | Fixed WADE command-support skills projected into `.claude/skills/` per worktree bootstrap; they are not replaceable methodology |
 | **AGENTS.md pointer** | A short `## Git Workflow` block that **worktree bootstrap** injects into an inited project's `AGENTS.md` per session, not by `wade init` |
 
 **This `AGENTS.md` governs development of WADE itself.** Skills, the pointer, and the progressive disclosure architecture are all *outputs* of WADE — artifacts installed into inited projects, not rules for developing WADE.
 
-**WADE uses its own workflow.** This repo is itself an inited project. Follow the `## Git Workflow` pointer at the bottom and the phase-specific skill referenced in your clipboard prompt.
+**WADE uses its own workflow.** This repo is itself an inited project. Follow the `## Git Workflow` pointer at the bottom, then the fixed `.wade/session/WORKFLOW.md` and its selected WORK methodology.
 
 ## Commands
 
@@ -113,13 +115,15 @@ Everything in this repo exists in one of two worlds:
 | WADE repo (source) | Inited project (output) |
 |---------------------|------------------------|
 | `src/wade/` | installed `wade` binary |
-| `templates/skills/<name>/SKILL.md` | `.claude/skills/<name>/SKILL.md` |
+| `templates/workflows/<session>.md` | `.wade/session/WORKFLOW.md` |
+| `templates/skills/<method>/SKILL.md` | `.wade/session/skills/{builtin,project}/.../SKILL.md` |
+| support skills in `templates/skills/` | `.claude/skills/<name>/SKILL.md` |
 | `templates/agents-pointer.md` | `## Git Workflow` block in target `AGENTS.md` |
 | `AGENTS.md` (this file) | target project's own `AGENTS.md` |
 
-When developing WADE, **only touch the left column**. Always edit `templates/skills/<name>/SKILL.md` directly — never edit files inside `.claude/skills/` (those are symlinks in this repo, copies in inited projects).
+When developing WADE, **only touch the left column**. Put lifecycle steps and WADE commands in `templates/workflows/`; put replaceable methodology in WADE-agnostic `templates/skills/<method>/SKILL.md`. Never edit `.claude/skills/` or `.wade/session/` outputs directly.
 
-The right-column artifacts (installed skills, the `## Git Workflow` pointer, and the Claude/Cursor allowlists) are produced **per session by worktree bootstrap** (`bootstrap_worktree` in `implementation_service/bootstrap.py`, invoked by `wade implement`/`wade plan`/`wade review` and by a standalone `wade task deps`), *not* by `wade init`. `wade init` writes only `.wade.yml`, optional provider/knowledge files, and the `.wade/` manifest.
+The right-column artifacts (workflow, frozen skill bundle, support skills, the `## Git Workflow` pointer, and tool configuration) are produced **per session by worktree bootstrap** (`bootstrap_worktree` in `implementation_service/bootstrap.py`, invoked by `wade implement`/`wade plan`/`wade review`; standalone delegations use operation bundles), *not* by `wade init`. `wade init` writes only `.wade.yml`, optional provider/knowledge files, and the `.wade/` manifest.
 
 > Skills system deep dive (symlinks, pointer markers, installation lifecycle): see `docs/dev/skills-system.md`
 
@@ -151,12 +155,10 @@ Before considering any work complete:
 - [ ] **`templates/skills/`** — updated if agent-facing rules changed (plan-session for planning, implementation-session for implementation, review-pr-comments-session for reviews)
 - [ ] **Commit** — uses conventional-commit prefix
 
-Note: for inited projects, the doc update pass is now an explicit, mandatory
-closing step in the installed `implementation-session` and
-`review-pr-comments-session` skills (`{doc_update_step}` /
-`templates/skills/_partials/doc-update-step.md`) — not something an agent has
-to remember on its own. This repo's own checklist above is unaffected; it
-still governs what WADE-repo changes require here.
+Note: for inited projects, the doc update pass is an explicit mandatory step in
+the fixed implementation and PR-comment workflows. WADE records an `--updated`
+or reasoned `--not-needed` receipt for the current commit; methodology skills do
+not own or satisfy that step. This repo's own checklist above is unaffected.
 
 > Full 10-item checklist, documentation rules, feedback loop, and correction-driven docs: see `docs/dev/documentation-policies.md`
 
@@ -169,5 +171,6 @@ Read these on-demand when working in a specific area:
 | Modifying architecture, config, or commands | `docs/dev/architecture.md` |
 | Adding an AI tool, provider, or subcommand | `docs/dev/extending.md` |
 | Writing or running tests | `docs/dev/testing.md` |
-| Working on skills, pointer system, or `wade init` | `docs/dev/skills-system.md` |
+| Working on discovery, snapshots, support skills, pointer system, or `wade init` | `docs/dev/skills-system.md` |
+| Working on fixed workflows, dynamic bindings, manifests, or delegation skill contracts | `docs/dev/workflows-and-skills.md` |
 | Updating documentation policies | `docs/dev/documentation-policies.md` |

{wade_cli-0.52.0 → wade_cli-0.53.1}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [v0.53.1] — 2026-08-31
+
+### Bug Fixes
+
+- relaunch Codex with implementation network policy after plan handoff (#473) (202018b)
+
+## [v0.53.0] — 2026-08-31
+
+### Features
+
+- decouple session workflows from dynamic skills (#470) (3f588a4)
+
 ## [v0.52.0] — 2026-08-23
 
 ### Features

{wade_cli-0.52.0 → wade_cli-0.53.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 0.52.0
+Version: 0.53.1
 Summary: WADE — Workflow for AI-Driven Engineering
 Project-URL: Homepage, https://github.com/ivanviragine/wade
 Project-URL: Repository, https://github.com/ivanviragine/wade
@@ -61,7 +61,8 @@ while WADE handles the git and GitHub plumbing around every AI session.
   project conventions are loaded into the AI automatically.
 - **Agent guardrails** — on hook-capable AI tools, per-session hooks keep the AI
   inside its worktree and route it through a completion gate before any push;
-  hookless tools fall back to skill rules (see the tool support table).
+  hookless tools retain the same fixed workflow and deterministic service gates
+  (see the tool support table).
 - **Quality gates** — opt-in pre-commit lint/test and conventional-commit checks,
   plus an AI code-review pass before the PR is marked ready.
 - **Pluggable task providers** — GitHub Issues, ClickUp, or a committed Markdown
@@ -90,8 +91,8 @@ wade 42
 
 With no open PR for task #42 yet, WADE starts an implementation session: it
 creates an isolated git worktree, launches your AI tool with the full task
-loaded — title, description, labels, and all your project conventions — and
-Skills guide the AI from first commit to open PR without you touching git again.
+loaded — title, description, labels, and all your project conventions — and a
+fixed workflow plus selected methodology guide it from first commit to open PR.
 Want the AI to break the work down first? Run `wade plan` — planning is a
 deliberate step, not something `wade 42` guesses at from a missing plan.
 
@@ -131,7 +132,7 @@ wade implement-batch 42 43 44   # three worktrees, three AI sessions, zero stash
 | `git fetch && checkout && pull && checkout -b ...` before every task | `wade 42` — one command, done |
 | Copy-paste task title + description into AI chat every time | Full task context + project conventions loaded automatically |
 | One task at a time, or stash-juggle between branches | Parallel tasks in isolated worktrees, zero conflicts |
-| Re-explain your branching rules, test commands, linters every session | Skills teach the AI your conventions once |
+| Re-explain lifecycle and review rules every session | A fixed workflow carries them; dynamic skills add your methodology |
 | PRs opened on stale branches — reviewer sees conflict noise, asks for a rebase, CI fails | AI merges the latest main and resolves conflicts before the PR — reviewer sees only your changes |
 | Write the PR description, link the task, clean up the branch — manually | The AI ships the PR. You just review |
 | Manually pick the right model for each task | Automatic model routing based on task complexity |
@@ -239,6 +240,12 @@ wade plan ─▶ tasks + draft PRs ─▶ wade <N> ─▶ AI implements in an is
 | `wade update` | Upgrade WADE and refresh project files |
 | `wade deinit` | Remove WADE from the current project |
 | `wade check-config` | Validate `.wade.yml` configuration |
+| `wade skills list` | List built-in methods and discovered project skills |
+| `wade skills resolve --session <kind>` | Explain effective session bindings and precedence |
+| `wade skills resolve --delegation <kind>` | Explain an effective standalone delegation binding |
+| `wade skills check` | Deep-check discovered trees and configured skill refs |
+| `wade session describe` | Show the active session's frozen workflow/bindings |
+| `wade session refresh-skills` | Explicitly rediscover and replace active skill snapshots |
 | `wade knowledge add` | Append a project learning from stdin (unavailable in a plan/deps session) |
 | `wade knowledge get` | Print the current project knowledge file |
 | `wade knowledge rate` | Record an up / down / stale vote for a knowledge entry |
@@ -259,16 +266,17 @@ These are invoked by the AI during a session — you normally don't run them by
 | Command | Description |
 |---------|-------------|
 | `wade implementation-session check` | Verify the implementation session's Git, GitHub, and required local capabilities before edits |
+| `wade implementation-session docs --updated \| --not-needed "reason"` | Record the required documentation-impact decision for current HEAD |
 | `wade implementation-session sync` | Sync the branch onto the base branch |
 | `wade implementation-session done` | Completion gate — runs the gates, pushes, and opens/updates the PR |
-| `wade review-pr-comments-session check \| sync \| done` | Same lifecycle for a review session |
+| `wade review-pr-comments-session check \| docs \| sync \| done` | Same lifecycle and documentation receipt for a review session |
 | `wade review-pr-comments-session fetch <N>` | Fetch unresolved PR review comments as markdown |
 | `wade review-pr-comments-session resolve <thread>` | Mark a PR review thread as resolved on GitHub |
 | `wade plan-session check` | Verify detached planning capabilities before writing plan artefacts or knowledge votes |
 | `wade plan-session done <plan_dir>` | Finalize a planning session |
 | `wade deps-session check` | Verify the detached dependency-analysis runtime before writing output or staging a knowledge vote |
 
-Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `implement`, `review pr-comments`, and the `wade <N>` shorthand also accept `--network` / `--no-network` (see [Codex sandbox](#codex-sandbox--network-policy)); the shorthand forwards the flag to whichever session it routes to. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
+Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `implement`, `review pr-comments`, and the `wade <N>` shorthand also accept `--network` / `--no-network` (see [Codex sandbox](#codex-sandbox--network-policy)); the shorthand forwards the flag to whichever session it routes to. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
 
 ## Planning & base branches
 
@@ -322,6 +330,13 @@ WADE splits review into an **AI review pass** you or the agent can invoke, and
 | `wade review pr-comments <N>` | Starts a session to address human/bot PR comments |
 | `wade review trigger <N>` | Posts configured bot-review trigger comments on the task's PR |
 
+Prompt-mode implementation review prints the bounded review prompt and exits 2;
+printing it does not certify that a review happened. After performing that
+self-review and addressing its findings, run
+`wade review implementation --ack-self-review` to write the current commit and
+frozen-review-binding receipt. Successful headless or interactive reviews write
+the same receipt directly.
+
 To fetch the unresolved comments themselves during a review session, the agent
 runs `wade review-pr-comments-session fetch <N>`; it resolves individual threads with
 `wade review-pr-comments-session resolve`.
@@ -513,21 +528,24 @@ deliberate obfuscation (variable indirection, command substitution, subshells).
 | Antigravity CLI | ✅ | ✅ |
 
 The remaining supported tools (OpenCode, VS Code, Antigravity IDE) expose no hook
-mechanism WADE can install into, so they receive neither guard — session rules
-there rest on the skill files alone.
+mechanism WADE can install into, so they receive neither hook guard. Their
+session still loads the fixed workflow, and deterministic lifecycle commands and
+completion gates remain authoritative.
 
 ### Completion gates
 
 `wade implementation-session done` (and `review-pr-comments-session done`) is the
 authoritative completion gate: it refuses to finalize until the work is actually
-ready, then writes the `.wade/done@<HEAD>` marker and pushes. Each gate has an
-escape hatch under a `done:` block in `.wade.yml` (all default on):
+ready, then writes the `.wade/done@<HEAD>` marker and pushes. Policy gates normally
+have an escape hatch under a `done:` block in `.wade.yml` (all default on).
+Decision and integrity gates deliberately require an explicit valid outcome:
 
 | Gate | Refuses when… | Hatch |
 |------|---------------|-------|
-| PR-SUMMARY | `PR-SUMMARY.md` is missing, empty, or still a template placeholder (implementation only) | `done.require_pr_summary: false` |
-| Sync | the branch is behind main — auto-syncs first, refuses only on conflict (implementation only) | `done.require_sync: false` |
-| Review ran | `wade review implementation` did not run for the current commit. **Implementation sessions bound this loop:** after `done.max_review_passes` (default 2) review→fix→re-review cycles, `done` completes anyway with a notice instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
+| PR-SUMMARY | `PR-SUMMARY.md` is missing, empty, or still a template placeholder (both change-producing session types) | `done.require_pr_summary: false` |
+| Documentation decision | neither an `--updated` nor reasoned `--not-needed` receipt exists for current HEAD | *no disable toggle; `docs --not-needed "<reason>"` records the explicit no-change outcome* |
+| Sync | the branch is behind main — auto-syncs first, refuses only on conflict (both change-producing session types) | `done.require_sync: false` |
+| Review ran | `wade review implementation` has no successful external-review or explicitly acknowledged self-review record for the current commit **and frozen REVIEW binding**, or the frozen workflow/skill bundle no longer matches its manifest. Bundle validation happens before receipts or pass counts are trusted. Prompt emission alone never satisfies this gate. **Implementation sessions bound this loop:** after `done.max_review_passes` (default 2) review→fix→re-review cycles for the active reviewer, `done` completes anyway with a notice instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
 | Resolved threads | unresolved PR review threads remain (review-comments only) | `done.require_resolved_threads: false` |
 | Conventional title | the task title is not a conventional-commit title (the PR title is derived from it, so it would fail `PR Title Lint`) — blocks; when valid but the open PR's title differs, syncs the PR title to match (both session types) — if that sync fails while the PR's current title is itself non-conventional (lint would fail), `done` fails so it can be retried | `done.require_conventional_title: false` |
 | Knowledge valid | the knowledge file is structurally corrupt — duplicate entry IDs or unresolved conflict markers (e.g. from a `merge=union` merge) | *none — gated by `knowledge.enabled`; no `done.*` hatch* |
@@ -541,11 +559,11 @@ bypasses the backstop in one flag — this is a quality/backstop layer that make
 the gate hard to skip, not an airtight boundary.
 
 `done` also writes a **`## Review Status`** line into the PR body recording the
-review outcome — reviewed at `<sha>`, skipped via `--skip-review`, gate disabled
-(`done.require_review: false` / `ai.review_implementation.enabled: false`), or
-completed at the review-pass cap — with the review-pass count. A skipped or
-never-run review is therefore visible to reviewers in the PR itself, not just in
-the worktree-local `.wade/` markers that are discarded when the session ends.
+review outcome — reviewed at `<sha>`, reviewer changed, skipped via
+`--skip-review`, gate disabled (`done.require_review: false` /
+`ai.review_implementation.enabled: false`), or completed at the active review
+binding's pass cap. A skipped, stale-reviewer, or never-run review is therefore
+visible to reviewers rather than hidden in worktree state.
 
 ## Task Providers
 
@@ -712,6 +730,15 @@ flag enables it there. Precedence for the commands that honor it is
 enable network for a WADE-managed sandbox. Enabling network never disables the
 sandbox and never changes approval-policy semantics.
 
+An accepted single-issue plan handoff starts implementation from a planning
+session that is always network-off. When both the planning tool and resolved
+implementation tool are Codex and the implementation policy resolves to enabled,
+WADE starts a fresh detached Codex context with network explicitly enabled;
+reusing the planner process would retain its immutable network-off sandbox. If
+WADE cannot open that detached context, the handoff fails rather than reporting
+an implementation session ready. Open a new host terminal and run the displayed
+`wade implement <issue> --network` command to continue with the required policy.
+
 ### Session readiness and least-privilege remediation
 
 Every `wade` command an agent runs is a child of the AI tool. It inherits that
@@ -818,15 +845,106 @@ Adapters, model/effort resolution, and per-tool config (allowlists, hooks) are p
 
 ## Agent Skills
 
-wade installs Skills that teach your AI agent the workflow — task format, planning rules, implementation session rules, and dependency analysis. Skills, the `AGENTS.md` workflow pointer, and any tool-specific configuration are set up automatically for every session (when you run `wade plan`/`wade implement`/`wade review`, or a standalone `wade task deps`), for every supported tool. Nothing to configure manually.
+WADE keeps the workflow fixed while letting you replace the methodology. Every
+interactive session gets an authoritative `.wade/session/WORKFLOW.md`; it still
+contains planning/implementation/review steps, documentation, synchronization,
+and `done` regardless of which skills are selected. Agent Skills control only
+*how* the WORK or REVIEW step reasons.
+
+Default replaceable methods:
+
+| Operation | WORK method | REVIEW method |
+|---|---|---|
+| planning session | `builtin:planning` | `builtin:plan-review` |
+| implementation session | `builtin:implementation` | `builtin:code-review` |
+| PR-comment session | `builtin:review-comments` | `builtin:code-review` |
+| batch review | `builtin:batch-review` | — |
+| dependency analysis | `builtin:dependency-analysis` | — |
+
+Custom skills stay generic: they do not need to mention WADE, worktrees,
+session commands, markers, review budgets, or `done`. WADE wraps their
+methodology in its fixed lifecycle or bounded operation contract.
+
+Project skills are discovered from every skill root supported by the selected
+tool integration, including real or symlinked `.claude/skills`,
+`.agents/skills`, `.cursor/skills`, and `.github/skills` layouts. WADE merges
+the new worktree inventory with the main checkout so local-only/ignored skills
+are available too, while worktree content wins for matching tracked paths.
+Generated `task` and `knowledge` command-support projections are excluded from
+methodology discovery, so they cannot shadow a project skill with the same name.
+WADE copies the complete skill directory—`SKILL.md`, references, scripts, and
+assets—into the session snapshot; source directories are never overwritten or
+pruned.
+
+Use explicit refs:
+
+- `builtin:<name>` for a bundled default;
+- `project:<name>` for a unique discovered project skill;
+- `path:<repo-relative-directory>` to select one exact source when names collide.
+
+Bindings are ordered and frozen in `.wade/session/manifest.json`. Resuming uses
+the same physical copies even if config or the main checkout changes. To change
+an active session, use `--refresh-skills` with the session command or run
+`wade session refresh-skills`; an override without explicit refresh fails.
+In a worktree-less planning fallback, session diagnostics and refresh target the
+temporary bundle advertised to the agent while continuing to load config and
+project skills from the checkout that launched it.
+
+Example configuration (all sections are optional; omitted values keep the
+defaults):
+
+```yaml
+skills:
+  project:
+    discover: true
+    include: ["*"]
+    exclude: []
+
+sessions:
+  implementation:
+    skills:
+      work: [project:django-implementation]
+      review: [project:security-review]
+  plan:
+    skills:
+      work: [builtin:planning]
+  review_pr_comments:
+    skills:
+      work: [builtin:review-comments]
+
+delegations:
+  code_review:
+    skills:
+      work: [project:security-review]
+  plan_review:
+    skills:
+      work: [builtin:plan-review]
+  batch_review:
+    skills:
+      work: [builtin:batch-review]
+  dependency_analysis:
+    skills:
+      work: [builtin:dependency-analysis]
+```
 
-| Skill | Purpose |
-|-------|---------|
-| `task` | Task creation and plan format |
-| `plan-session` | Planning session rules and workflow |
-| `implementation-session` | Implementation session rules and workflow |
-| `review-pr-comments-session` | Review session rules and workflow |
-| `deps` | Dependency analysis between tasks |
+For a new session the order is CLI override, session binding, mapped delegation
+binding for REVIEW, then built-in default. A session REVIEW binding wins over a
+different `delegations.code_review`/`plan_review` value for that session.
+Standalone review, batch, and dependency operations use their delegation
+binding. `wade skills resolve` prints every candidate and the winner.
+
+Tool-native roots receive only fixed command-support skills. Session lifecycle
+comes from the rendered workflow, while default or custom methodology is frozen
+inside the session bundle. Deprecated phase skills are not installed.
+Resume revalidates workflow identity and the complete physical bundle against
+its manifest digest; completion does the same before trusting a review receipt.
+Stale metadata and edited, missing, extra, or unsafe snapshot content require an
+explicit `--refresh-skills` or `wade session refresh-skills` replacement.
+
+This redesign is a clean cutover. It does not import pre-redesign phase-skill or
+review-marker state. Resuming an older in-flight worktree creates the current
+session bundle, and its current commit must complete the new review and
+documentation-decision gates before `done` can accept it.
 
 ### Session communication
 

{wade_cli-0.52.0 → wade_cli-0.53.1}/README.md

@@ -25,7 +25,8 @@ while WADE handles the git and GitHub plumbing around every AI session.
   project conventions are loaded into the AI automatically.
 - **Agent guardrails** — on hook-capable AI tools, per-session hooks keep the AI
   inside its worktree and route it through a completion gate before any push;
-  hookless tools fall back to skill rules (see the tool support table).
+  hookless tools retain the same fixed workflow and deterministic service gates
+  (see the tool support table).
 - **Quality gates** — opt-in pre-commit lint/test and conventional-commit checks,
   plus an AI code-review pass before the PR is marked ready.
 - **Pluggable task providers** — GitHub Issues, ClickUp, or a committed Markdown
@@ -54,8 +55,8 @@ wade 42
 
 With no open PR for task #42 yet, WADE starts an implementation session: it
 creates an isolated git worktree, launches your AI tool with the full task
-loaded — title, description, labels, and all your project conventions — and
-Skills guide the AI from first commit to open PR without you touching git again.
+loaded — title, description, labels, and all your project conventions — and a
+fixed workflow plus selected methodology guide it from first commit to open PR.
 Want the AI to break the work down first? Run `wade plan` — planning is a
 deliberate step, not something `wade 42` guesses at from a missing plan.
 
@@ -95,7 +96,7 @@ wade implement-batch 42 43 44   # three worktrees, three AI sessions, zero stash
 | `git fetch && checkout && pull && checkout -b ...` before every task | `wade 42` — one command, done |
 | Copy-paste task title + description into AI chat every time | Full task context + project conventions loaded automatically |
 | One task at a time, or stash-juggle between branches | Parallel tasks in isolated worktrees, zero conflicts |
-| Re-explain your branching rules, test commands, linters every session | Skills teach the AI your conventions once |
+| Re-explain lifecycle and review rules every session | A fixed workflow carries them; dynamic skills add your methodology |
 | PRs opened on stale branches — reviewer sees conflict noise, asks for a rebase, CI fails | AI merges the latest main and resolves conflicts before the PR — reviewer sees only your changes |
 | Write the PR description, link the task, clean up the branch — manually | The AI ships the PR. You just review |
 | Manually pick the right model for each task | Automatic model routing based on task complexity |
@@ -203,6 +204,12 @@ wade plan ─▶ tasks + draft PRs ─▶ wade <N> ─▶ AI implements in an is
 | `wade update` | Upgrade WADE and refresh project files |
 | `wade deinit` | Remove WADE from the current project |
 | `wade check-config` | Validate `.wade.yml` configuration |
+| `wade skills list` | List built-in methods and discovered project skills |
+| `wade skills resolve --session <kind>` | Explain effective session bindings and precedence |
+| `wade skills resolve --delegation <kind>` | Explain an effective standalone delegation binding |
+| `wade skills check` | Deep-check discovered trees and configured skill refs |
+| `wade session describe` | Show the active session's frozen workflow/bindings |
+| `wade session refresh-skills` | Explicitly rediscover and replace active skill snapshots |
 | `wade knowledge add` | Append a project learning from stdin (unavailable in a plan/deps session) |
 | `wade knowledge get` | Print the current project knowledge file |
 | `wade knowledge rate` | Record an up / down / stale vote for a knowledge entry |
@@ -223,16 +230,17 @@ These are invoked by the AI during a session — you normally don't run them by
 | Command | Description |
 |---------|-------------|
 | `wade implementation-session check` | Verify the implementation session's Git, GitHub, and required local capabilities before edits |
+| `wade implementation-session docs --updated \| --not-needed "reason"` | Record the required documentation-impact decision for current HEAD |
 | `wade implementation-session sync` | Sync the branch onto the base branch |
 | `wade implementation-session done` | Completion gate — runs the gates, pushes, and opens/updates the PR |
-| `wade review-pr-comments-session check \| sync \| done` | Same lifecycle for a review session |
+| `wade review-pr-comments-session check \| docs \| sync \| done` | Same lifecycle and documentation receipt for a review session |
 | `wade review-pr-comments-session fetch <N>` | Fetch unresolved PR review comments as markdown |
 | `wade review-pr-comments-session resolve <thread>` | Mark a PR review thread as resolved on GitHub |
 | `wade plan-session check` | Verify detached planning capabilities before writing plan artefacts or knowledge votes |
 | `wade plan-session done <plan_dir>` | Finalize a planning session |
 | `wade deps-session check` | Verify the detached dependency-analysis runtime before writing output or staging a knowledge vote |
 
-Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `implement`, `review pr-comments`, and the `wade <N>` shorthand also accept `--network` / `--no-network` (see [Codex sandbox](#codex-sandbox--network-policy)); the shorthand forwards the flag to whichever session it routes to. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
+Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `implement`, `review pr-comments`, and the `wade <N>` shorthand also accept `--network` / `--no-network` (see [Codex sandbox](#codex-sandbox--network-policy)); the shorthand forwards the flag to whichever session it routes to. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
 
 ## Planning & base branches
 
@@ -286,6 +294,13 @@ WADE splits review into an **AI review pass** you or the agent can invoke, and
 | `wade review pr-comments <N>` | Starts a session to address human/bot PR comments |
 | `wade review trigger <N>` | Posts configured bot-review trigger comments on the task's PR |
 
+Prompt-mode implementation review prints the bounded review prompt and exits 2;
+printing it does not certify that a review happened. After performing that
+self-review and addressing its findings, run
+`wade review implementation --ack-self-review` to write the current commit and
+frozen-review-binding receipt. Successful headless or interactive reviews write
+the same receipt directly.
+
 To fetch the unresolved comments themselves during a review session, the agent
 runs `wade review-pr-comments-session fetch <N>`; it resolves individual threads with
 `wade review-pr-comments-session resolve`.
@@ -477,21 +492,24 @@ deliberate obfuscation (variable indirection, command substitution, subshells).
 | Antigravity CLI | ✅ | ✅ |
 
 The remaining supported tools (OpenCode, VS Code, Antigravity IDE) expose no hook
-mechanism WADE can install into, so they receive neither guard — session rules
-there rest on the skill files alone.
+mechanism WADE can install into, so they receive neither hook guard. Their
+session still loads the fixed workflow, and deterministic lifecycle commands and
+completion gates remain authoritative.
 
 ### Completion gates
 
 `wade implementation-session done` (and `review-pr-comments-session done`) is the
 authoritative completion gate: it refuses to finalize until the work is actually
-ready, then writes the `.wade/done@<HEAD>` marker and pushes. Each gate has an
-escape hatch under a `done:` block in `.wade.yml` (all default on):
+ready, then writes the `.wade/done@<HEAD>` marker and pushes. Policy gates normally
+have an escape hatch under a `done:` block in `.wade.yml` (all default on).
+Decision and integrity gates deliberately require an explicit valid outcome:
 
 | Gate | Refuses when… | Hatch |
 |------|---------------|-------|
-| PR-SUMMARY | `PR-SUMMARY.md` is missing, empty, or still a template placeholder (implementation only) | `done.require_pr_summary: false` |
-| Sync | the branch is behind main — auto-syncs first, refuses only on conflict (implementation only) | `done.require_sync: false` |
-| Review ran | `wade review implementation` did not run for the current commit. **Implementation sessions bound this loop:** after `done.max_review_passes` (default 2) review→fix→re-review cycles, `done` completes anyway with a notice instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
+| PR-SUMMARY | `PR-SUMMARY.md` is missing, empty, or still a template placeholder (both change-producing session types) | `done.require_pr_summary: false` |
+| Documentation decision | neither an `--updated` nor reasoned `--not-needed` receipt exists for current HEAD | *no disable toggle; `docs --not-needed "<reason>"` records the explicit no-change outcome* |
+| Sync | the branch is behind main — auto-syncs first, refuses only on conflict (both change-producing session types) | `done.require_sync: false` |
+| Review ran | `wade review implementation` has no successful external-review or explicitly acknowledged self-review record for the current commit **and frozen REVIEW binding**, or the frozen workflow/skill bundle no longer matches its manifest. Bundle validation happens before receipts or pass counts are trusted. Prompt emission alone never satisfies this gate. **Implementation sessions bound this loop:** after `done.max_review_passes` (default 2) review→fix→re-review cycles for the active reviewer, `done` completes anyway with a notice instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
 | Resolved threads | unresolved PR review threads remain (review-comments only) | `done.require_resolved_threads: false` |
 | Conventional title | the task title is not a conventional-commit title (the PR title is derived from it, so it would fail `PR Title Lint`) — blocks; when valid but the open PR's title differs, syncs the PR title to match (both session types) — if that sync fails while the PR's current title is itself non-conventional (lint would fail), `done` fails so it can be retried | `done.require_conventional_title: false` |
 | Knowledge valid | the knowledge file is structurally corrupt — duplicate entry IDs or unresolved conflict markers (e.g. from a `merge=union` merge) | *none — gated by `knowledge.enabled`; no `done.*` hatch* |
@@ -505,11 +523,11 @@ bypasses the backstop in one flag — this is a quality/backstop layer that make
 the gate hard to skip, not an airtight boundary.
 
 `done` also writes a **`## Review Status`** line into the PR body recording the
-review outcome — reviewed at `<sha>`, skipped via `--skip-review`, gate disabled
-(`done.require_review: false` / `ai.review_implementation.enabled: false`), or
-completed at the review-pass cap — with the review-pass count. A skipped or
-never-run review is therefore visible to reviewers in the PR itself, not just in
-the worktree-local `.wade/` markers that are discarded when the session ends.
+review outcome — reviewed at `<sha>`, reviewer changed, skipped via
+`--skip-review`, gate disabled (`done.require_review: false` /
+`ai.review_implementation.enabled: false`), or completed at the active review
+binding's pass cap. A skipped, stale-reviewer, or never-run review is therefore
+visible to reviewers rather than hidden in worktree state.
 
 ## Task Providers
 
@@ -676,6 +694,15 @@ flag enables it there. Precedence for the commands that honor it is
 enable network for a WADE-managed sandbox. Enabling network never disables the
 sandbox and never changes approval-policy semantics.
 
+An accepted single-issue plan handoff starts implementation from a planning
+session that is always network-off. When both the planning tool and resolved
+implementation tool are Codex and the implementation policy resolves to enabled,
+WADE starts a fresh detached Codex context with network explicitly enabled;
+reusing the planner process would retain its immutable network-off sandbox. If
+WADE cannot open that detached context, the handoff fails rather than reporting
+an implementation session ready. Open a new host terminal and run the displayed
+`wade implement <issue> --network` command to continue with the required policy.
+
 ### Session readiness and least-privilege remediation
 
 Every `wade` command an agent runs is a child of the AI tool. It inherits that
@@ -782,15 +809,106 @@ Adapters, model/effort resolution, and per-tool config (allowlists, hooks) are p
 
 ## Agent Skills
 
-wade installs Skills that teach your AI agent the workflow — task format, planning rules, implementation session rules, and dependency analysis. Skills, the `AGENTS.md` workflow pointer, and any tool-specific configuration are set up automatically for every session (when you run `wade plan`/`wade implement`/`wade review`, or a standalone `wade task deps`), for every supported tool. Nothing to configure manually.
+WADE keeps the workflow fixed while letting you replace the methodology. Every
+interactive session gets an authoritative `.wade/session/WORKFLOW.md`; it still
+contains planning/implementation/review steps, documentation, synchronization,
+and `done` regardless of which skills are selected. Agent Skills control only
+*how* the WORK or REVIEW step reasons.
+
+Default replaceable methods:
+
+| Operation | WORK method | REVIEW method |
+|---|---|---|
+| planning session | `builtin:planning` | `builtin:plan-review` |
+| implementation session | `builtin:implementation` | `builtin:code-review` |
+| PR-comment session | `builtin:review-comments` | `builtin:code-review` |
+| batch review | `builtin:batch-review` | — |
+| dependency analysis | `builtin:dependency-analysis` | — |
+
+Custom skills stay generic: they do not need to mention WADE, worktrees,
+session commands, markers, review budgets, or `done`. WADE wraps their
+methodology in its fixed lifecycle or bounded operation contract.
+
+Project skills are discovered from every skill root supported by the selected
+tool integration, including real or symlinked `.claude/skills`,
+`.agents/skills`, `.cursor/skills`, and `.github/skills` layouts. WADE merges
+the new worktree inventory with the main checkout so local-only/ignored skills
+are available too, while worktree content wins for matching tracked paths.
+Generated `task` and `knowledge` command-support projections are excluded from
+methodology discovery, so they cannot shadow a project skill with the same name.
+WADE copies the complete skill directory—`SKILL.md`, references, scripts, and
+assets—into the session snapshot; source directories are never overwritten or
+pruned.
+
+Use explicit refs:
+
+- `builtin:<name>` for a bundled default;
+- `project:<name>` for a unique discovered project skill;
+- `path:<repo-relative-directory>` to select one exact source when names collide.
+
+Bindings are ordered and frozen in `.wade/session/manifest.json`. Resuming uses
+the same physical copies even if config or the main checkout changes. To change
+an active session, use `--refresh-skills` with the session command or run
+`wade session refresh-skills`; an override without explicit refresh fails.
+In a worktree-less planning fallback, session diagnostics and refresh target the
+temporary bundle advertised to the agent while continuing to load config and
+project skills from the checkout that launched it.
+
+Example configuration (all sections are optional; omitted values keep the
+defaults):
+
+```yaml
+skills:
+  project:
+    discover: true
+    include: ["*"]
+    exclude: []
+
+sessions:
+  implementation:
+    skills:
+      work: [project:django-implementation]
+      review: [project:security-review]
+  plan:
+    skills:
+      work: [builtin:planning]
+  review_pr_comments:
+    skills:
+      work: [builtin:review-comments]
+
+delegations:
+  code_review:
+    skills:
+      work: [project:security-review]
+  plan_review:
+    skills:
+      work: [builtin:plan-review]
+  batch_review:
+    skills:
+      work: [builtin:batch-review]
+  dependency_analysis:
+    skills:
+      work: [builtin:dependency-analysis]
+```
 
-| Skill | Purpose |
-|-------|---------|
-| `task` | Task creation and plan format |
-| `plan-session` | Planning session rules and workflow |
-| `implementation-session` | Implementation session rules and workflow |
-| `review-pr-comments-session` | Review session rules and workflow |
-| `deps` | Dependency analysis between tasks |
+For a new session the order is CLI override, session binding, mapped delegation
+binding for REVIEW, then built-in default. A session REVIEW binding wins over a
+different `delegations.code_review`/`plan_review` value for that session.
+Standalone review, batch, and dependency operations use their delegation
+binding. `wade skills resolve` prints every candidate and the winner.
+
+Tool-native roots receive only fixed command-support skills. Session lifecycle
+comes from the rendered workflow, while default or custom methodology is frozen
+inside the session bundle. Deprecated phase skills are not installed.
+Resume revalidates workflow identity and the complete physical bundle against
+its manifest digest; completion does the same before trusting a review receipt.
+Stale metadata and edited, missing, extra, or unsafe snapshot content require an
+explicit `--refresh-skills` or `wade session refresh-skills` replacement.
+
+This redesign is a clean cutover. It does not import pre-redesign phase-skill or
+review-marker state. Resuming an older in-flight worktree creates the current
+session bundle, and its current commit must complete the new review and
+documentation-decision gates before `done` can accept it.
 
 ### Session communication