joshuaboys · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -5,12 +5,17 @@ for planning and task authorisation in AI-assisted development.
 
 ## What this repo is
 
-APS is a **specification format**, not executable code. It contains:
+APS is a **specification format with optional executable tooling**. It contains:
 
 - Templates for plans, modules, work items, action plans, and **design documents**
 - Prompts for AI agents
 - Examples and documentation
-- A CLI for validation (linting)
+- A native Rust CLI/TUI plus maintained bash and PowerShell implementations
+- Optional MCP transport, installers, hooks, and generated agent assets
+
+Start with [CONTEXT.md](CONTEXT.md) for the source map and
+[docs/architecture.md](docs/architecture.md) for boundaries and decisions.
+Do not treat historical designs or example work items as new authority.
 
 ## Execution authority
 
@@ -64,6 +69,10 @@ Module status in the metadata table is always hand-edited.
 
 ### What validation to run
 
+Use [native Windows PowerShell checks](CONTRIBUTING.md#windows-native-powershell)
+on Windows; do not require WSL or label a skipped shell suite as full coverage.
+The following block is the macOS/Linux route.
+
 ```bash
 ./bin/aps lint plans                # plan structure (errors fail CI-style)
 ./test/run.sh                       # full CLI test suite
@@ -78,7 +87,7 @@ keep it warning-free where practical — warnings are drift signals.
 
 - **Work items** define outcomes (what to achieve)
 - **Actions** define what to do (not how)
-- Action plans live in `execution/[WORKITEM-ID].actions.md`
+- Action plans live in `plans/execution/[WORKITEM-ID].actions.md`
 - Each action has a checkpoint (observable completion state)
 
 See: [docs/ai/prompting/actions.prompt.md](docs/ai/prompting/actions.prompt.md)

diff --git a/CONTEXT.md b/CONTEXT.md
@@ -0,0 +1,56 @@
+# Repository context
+
+APS combines a portable Markdown planning format with optional tooling.
+This describes this repository, not a consumer project or new work authority.
+
+## Start here
+
+- [README](README.md): value, installation, and format
+- [Getting started](docs/getting-started.md): disposable CLI walkthrough
+- [Architecture](docs/architecture.md): source map, data flow, and limitations
+- [AGENTS.md](AGENTS.md): collaboration and plan-update rules
+- [CONTRIBUTING](CONTRIBUTING.md): public work candidates and local checks
+- [Current plans](plans/index.aps.md): statuses, dependencies, and decisions
+
+## Sources of truth
+
+The format is expressed through templates/, plans/aps-rules.md, examples,
+and documented lint behaviour. The native CLI is in cli/src/; bash and
+PowerShell peers are in bin/ and lib/. Shared parity fixtures live in
+test/fixtures/. Behaviour changes account for all three implementations
+under D-039; release-command parity debt is tracked by REL-005.
+
+scaffold/ is the installation payload, including skills and neutral agent
+cores. Generated agent variants are reviewable install-time envelopes.
+See [agent documentation](docs/agents.md) before editing them. The top-level
+aps-planning/ tree is not a substitute for checking which scaffold assets
+the installer and native binary actually consume.
+
+## Context ownership
+
+Consumer plans/project-context.md is user-owned project knowledge. Its
+[scaffold template](scaffold/plans/project-context.md) is not this repo's context.
+Generated .aps/context/ briefs can be regenerated; they are not durable
+decisions or claim leases. Keep credentials and private consumer material
+out of public plans, examples, and context packages.
+
+## Native platforms
+
+Windows is a first-class native CLI platform, not a WSL workflow. Start with
+[PowerShell setup](docs/installation.md#windows-details) and
+[Windows contributor checks](CONTRIBUTING.md#windows-native-powershell).
+The shipped Windows GNU zip is exercised by CI under PowerShell 7 and Windows
+PowerShell 5.1. This does not imply every fallback script or terminal has the
+same coverage; interactive Warp verification remains CIB-010.
+
+## Scope and authority
+
+Current work lives in plans/modules/; release history lives in plans/releases/
+and plans/completed.aps.md. Historical proposals under docs/plans/ are not
+automatically accepted architecture. Examples illustrate other projects and
+do not authorise implementing those applications here.
+
+No hosted APS service or mandatory agent harness is needed. Tooling does write
+files, and optional audit/hooks can execute commands: review untrusted plans
+before running them. Disclosure and community routes are in
+[SECURITY](SECURITY.md) and [the code of conduct](CODE_OF_CONDUCT.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -45,7 +45,8 @@ the plans describe, update them **in the same PR**.
 (`Draft → Ready → In Progress → Complete`). Add a `Results:` line when
 completing non-trivial items, and log discoveries in `plans/issues.md`.
 
-**Validation to run before requesting review:**
+**Validation before requesting review:** use the
+[Windows native checks](#windows-native-powershell) or the Unix summary below.
 
 ```bash
 ./bin/aps lint plans              # plan structure
@@ -56,6 +57,120 @@ npx markdownlint-cli "**/*.md"    # markdown style (CI-enforced)
 See [AGENTS.md](AGENTS.md) → "Keeping the plans honest" for the full
 conventions, and [docs/workflow.md](docs/workflow.md) for the lifecycle.
 
+## Finding bounded public work
+
+Start with [the roadmap](plans/index.aps.md) and
+the linked module's status, dependencies, and validation. Run
+`./bin/aps next`; an empty queue means no work item is currently Ready, not
+that the repository has no useful work. Draft design work is not implementation
+authority. Check open PRs and agree a bounded slice with a maintainer before
+starting an already In Progress item.
+
+Current public-only contribution candidates:
+
+- **REL-005 fixture extraction:** move the synthetic pre-sweep corpus from
+  `cli/src/release.rs` into shared `test/fixtures/release-close/` files and
+  make the Rust tests consume those exact bytes. Preserve dry-run non-mutation,
+  apply idempotence, lifecycle guards, and existing output. Keep this separate
+  from the bash/PowerShell ports; do not use live plan files as mutation fixtures.
+- **CIB-010 Windows verification:** on native Windows PowerShell in Warp, build
+  the current CLI, run interactive `aps setup` in a disposable directory, and
+  record whether one arrow press moves one option and holding/releasing keys
+  causes no duplicate navigation. Include commit, Windows, Warp, and PowerShell
+  versions. Unit tests alone do not close this manual gate.
+- **CIB-009 toolchain decision evidence:** reproduce local-versus-CI toolchain
+  drift and propose either an explicit stable-update preflight or a shared
+  exact pin. A `stable` toolchain file alone does not update an already-installed
+  stale stable toolchain. Implementation waits for the maintainer decision.
+
+These slices need only this public checkout and public dependencies; no private
+consumer repository, publishing token, or production service is required.
+REL-005 remains In Progress until all three CLI implementations agree.
+TEAM/PROG implementation and CLI-002 remain design/dependency-gated.
+
+### Local development checks
+
+Use Rust/Cargo, Node.js 24 or newer, and the pnpm version in `package.json`.
+Run from the repository root. Windows uses the native route below; Unix shell
+suites are additional CI coverage, not a Windows onboarding prerequisite.
+
+#### Windows native PowerShell
+
+Use Windows PowerShell 5.1 or PowerShell 7, Git for Windows, Node.js 24+ and
+pnpm from package.json. A native source build also needs Rust via rustup and
+its target's linker: the default MSVC toolchain needs Visual Studio C++ Build
+Tools and a Windows SDK. Alternatively an explicitly selected GNU toolchain
+needs a compatible MinGW linker. Installing build tools may need your device
+administrator; running APS from the released zip does not.
+
+For native Node tooling use pnpm.cmd, avoiding PowerShell's pnpm.ps1 shim if
+local script policy blocks it. Do not weaken the machine's execution policy.
+
+```powershell
+$ErrorActionPreference = 'Stop'
+function Invoke-Checked {
+    param([scriptblock]$Command)
+    $global:LASTEXITCODE = 0
+    & $Command
+    if ($LASTEXITCODE -ne 0) { throw "Command failed: exit $LASTEXITCODE" }
+}
+Invoke-Checked { pnpm.cmd install --frozen-lockfile }
+Invoke-Checked { pnpm.cmd --dir mcp install --frozen-lockfile }
+Invoke-Checked { pnpm.cmd lint }
+Invoke-Checked { cargo fmt --manifest-path cli/Cargo.toml --check }
+Invoke-Checked { cargo clippy --manifest-path cli/Cargo.toml --locked --all-targets -- -D warnings }
+Invoke-Checked { cargo test --manifest-path cli/Cargo.toml --locked }
+Invoke-Checked { cargo build --manifest-path cli/Cargo.toml --locked }
+$Aps = (Resolve-Path -LiteralPath '.\cli\target\debug\aps.exe').Path
+Invoke-Checked { & $Aps lint plans }
+$PreviousApsBin = $env:APS_BIN
+try {
+    $env:APS_BIN = $Aps
+    Invoke-Checked { pnpm.cmd --dir mcp test }
+    Invoke-Checked { pnpm.cmd --dir mcp exec tsc -p . }
+} finally { $env:APS_BIN = $PreviousApsBin }
+```
+
+With PowerShell 7 installed, run the fallback parity harness in its own process
+so its exit cannot terminate your interactive session:
+
+```powershell
+pwsh -NoProfile -File .\test\ps-parity.ps1
+if ($LASTEXITCODE -ne 0) { throw 'PowerShell parity failed' }
+```
+
+The native Windows release journey in CI runs the shipped GNU zip under both
+PowerShell 7 and Windows PowerShell 5.1. The fallback parity harness runs under
+PowerShell 7; this is not a promise that every fallback script supports 5.1.
+If local policy blocks a reviewed .ps1 test, report it and rely on CI rather
+than changing policy. The bash shell suite and cross-CLI bash harness run in
+Unix CI; Windows contributors need not install WSL to submit a change.
+Native Windows/Warp CIB-010 manual verification remains a separate gate.
+
+#### macOS or Linux
+
+```bash
+pnpm install --frozen-lockfile
+pnpm --dir mcp install --frozen-lockfile
+pnpm lint
+./bin/aps lint plans
+./test/run.sh
+cargo fmt --manifest-path cli/Cargo.toml --check
+cargo clippy --manifest-path cli/Cargo.toml --locked --all-targets -- -D warnings
+cargo test --manifest-path cli/Cargo.toml --locked
+cargo build --manifest-path cli/Cargo.toml --locked
+APS_RUST_BIN=cli/target/debug/aps ./test/cli-parity.sh
+```
+
+For the REL-005 slice, use `cargo test --manifest-path cli/Cargo.toml --locked
+release::tests` as the focused check. For CIB-010, use `cargo test
+--manifest-path cli/Cargo.toml --locked setup` and the native manual check.
+With PowerShell installed, also run `pwsh -NoProfile -File test/ps-parity.ps1`.
+The parity harness skips its PowerShell leg when `pwsh` is absent; the shell
+suite skips MCP tests without MCP dependencies. Report skips explicitly, not
+as full coverage. Compare `rustc --version` and `cargo clippy --version` with
+CI before diagnosing a lint disagreement.
+
 ## Scope Guardrails
 
 APS is a specification format for planning and task authorisation.
@@ -75,7 +190,7 @@ These belong to downstream implementations and will not be accepted:
 
 - Runtime execution engines
 - IDE plugins or integrations
-- Project management tool integrations (Jira, Linear, etc.) **We may revist this in the future**
+- Project management tool integrations (Jira, Linear, etc.) **We may revisit this in the future**
 - AI model fine-tuning or training data
 
 If you're unsure whether something is in scope, open an issue to discuss
@@ -100,6 +215,20 @@ When using AI tools to contribute:
 - Follow the guidance in [AGENTS.md](AGENTS.md)
 - Ensure AI-generated content is reviewed and validated
 
+## Reporting and review context
+
+For bugs, include the command, CLI version or commit, OS, expected/actual
+output, and a minimal public plan fixture. Remove secrets and private material.
+Proposals should identify the owning APS module and which CLI surfaces change.
+PRs should list validation, skips, and the matching plan update; publishing
+access is not required for an ordinary contribution.
+
+Use [SECURITY.md](SECURITY.md) for private vulnerability reports, not a public
+issue. Participation follows the [code of conduct](CODE_OF_CONDUCT.md).
+Maintainers review scope and design decisions; a Draft proposal is not approval.
+See [context](CONTEXT.md) and [architecture](docs/architecture.md) before
+changing implementation boundaries.
+
 ## Questions?
 
 Open an issue for questions about contributing or the project.

diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ macOS / Linux:
 curl -fsSL https://raw.githubusercontent.com/EddaCraft/anvil-plan-spec/main/scaffold/install | bash
 ```
 
-Windows PowerShell:
+Windows PowerShell 5.1 or PowerShell 7 (native, no WSL/Git Bash):
 
 ```powershell
 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/EddaCraft/anvil-plan-spec/main/scaffold/install.ps1)))
@@ -72,6 +72,11 @@ See [docs/installation.md](docs/installation.md).
 
 ## The 5-minute tour
 
+The snippets below explain the format; they are not a runnable application.
+For a copy/paste CLI exercise with real files, use the
+[disposable walkthrough](docs/getting-started.md#try-the-cli-without-changing-your-project).
+You can also use APS as plain Markdown without installing any tooling.
+
 ### 1. Define the intent
 
 ```markdown
@@ -117,17 +122,25 @@ implementation.
 
 ### 3. Execute through the CLI
 
+The native commands below run in PowerShell as well as bash. For Windows path
+quoting, exit checks, and a real disposable plan, use the
+[PowerShell walkthrough](docs/getting-started.md#windows-powershell-51-or-powershell-7).
+
 ```bash
 aps lint plans/                       # validate every spec
 aps next                              # find the next ready work item
-aps start AUTH-003                    # claim it and build focused context
+aps start AUTH-003                    # record progress and build focused context
 aps complete AUTH-003 --learning "Revocation needed cache invalidation"
 aps graph auth                        # inspect dependencies
 ```
 
 `aps start` verifies that dependencies are Complete, marks the item In
 Progress, and writes a focused context package to `.aps/context/AUTH-003.md`.
-It includes module scope, decisions, upstream learnings, and related files.
+It is not an atomic claim or multi-user lock, and `complete` records your
+reported result rather than running the validation command. Run the work item's
+checks before recording completion.
+The context package includes module scope, decisions, upstream learnings,
+and related files.
 
 `aps complete` records the completion date and captures a learning that can be
 surfaced to downstream work. The implementation can change; the intent,
@@ -260,7 +273,7 @@ need one.
 | **Claude / ChatGPT** | Paste or attach the relevant specification and work item |
 | **Cursor / Copilot** | Keep plans in the repository and reference the work item |
 | **Claude Code / aider** | Point the agent at the plan and context package |
-| **Codex / OpenCode** | Use the agent definitions shipped in `agents/` |
+| **Codex / OpenCode** | Install generated roles with `aps setup codex` or `aps setup opencode` |
 | **Grok Build** | Let it discover `AGENTS.md` and `.agents/skills/` |
 | **Antigravity** | Let it discover `AGENTS.md` and `.agents/skills/` |
 | **Amp / Gemini CLI / Windsurf / Roo Code / OpenClaw** | Let them discover `AGENTS.md` and `.agents/skills/` |
@@ -297,8 +310,9 @@ an honest first-run:
 - **Windows first-run:** the PowerShell installer finds the published x64 zip
   on WOW64 and ARM64, replaces a loaded `aps.exe`, and keeps an existing
   native binary instead of claiming none exists. README Install is the first
-  section. Setup no longer double-steps on Windows key-release, and Left/Right
-  navigate steps.
+  section. Setup filters key-release events and adds Left/Right step
+  navigation; native Windows/Warp manual verification remains outstanding
+  in CIB-010.
 
 The v0.8 line:
 
@@ -338,6 +352,8 @@ Full notes: [CHANGELOG.md](CHANGELOG.md) ·
 
 ## Worked examples
 
+These are [planning examples](examples/README.md), not application source.
+
 - [User Authentication](examples/user-auth/): adding authentication to an
   existing application
 - [OpenCode Companion App](examples/opencode-companion/): building a companion
@@ -375,8 +391,19 @@ your-project/
 | **macOS** | Native `aps` binary through the install script or Cargo | Homebrew Bash is used for the optional fallback |
 | **Windows** | Native `aps.exe` through PowerShell or Scoop | WSL and Git Bash are not required |
 
-The native binary supports the complete user command surface on all listed
-platforms.
+The native binary provides the user command surface on all listed platforms.
+Windows CI runs the released-shape x64 GNU zip under PowerShell 7 and Windows
+PowerShell 5.1. The script fallback is not a replacement for the native TUI.
+Known exception: audit command execution currently invokes bash; use
+`aps audit --no-run` and run validation directly in PowerShell on Windows.
+This is implementation debt, not a reason to require WSL.
+See [Windows installation/PATH help](docs/installation.md#windows-details)
+and [native contributor checks](CONTRIBUTING.md#windows-native-powershell).
+
+For the implementation map and current limitations, see
+[Architecture](docs/architecture.md). `main` includes changes after v0.9.0;
+check the [unreleased archive](plans/completed.aps.md#unreleased) before
+assuming a source feature is present in a downloaded release.
 
 ## AI agent guidance
 
@@ -432,6 +459,10 @@ See [docs/workflow.md](docs/workflow.md) for the full lifecycle.
 - [Terminology](docs/TERMINOLOGY.md)
 - [Roadmap](ROADMAP.md)
 - [Contributing](CONTRIBUTING.md)
+- [Repository context](CONTEXT.md)
+- [Architecture and decisions](docs/architecture.md)
+- [Security reporting](SECURITY.md)
+- [Code of conduct](CODE_OF_CONDUCT.md)
 
 ## License
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -13,7 +13,8 @@ to plan APS.
 | **v0.5–v0.6 Monorepo**    | Federated nested plans, the tagged package tier, full-lifecycle tooling | Done    |
 | **v0.7 Team Foundations** | Managed skill freshness, JSON export, GitHub Action, MCP server         | Done    |
 | **v0.8 Harnesses**        | Twelve supported harnesses from one shared planning asset               | Done    |
-| **Near Term**             | Release tooling (`aps release`), plan-doctor accuracy, lint parity      | Current |
+| **v0.9 Diagnostics**      | Binary self-update, plan-doctor accuracy, release-lint parity            | Done    |
+| **Near Term**             | Three-CLI release tooling parity, Windows setup verification           | Current |
 | **Future**                | Team coordination plane, progress journals, profile-aware CLI           | Planned |
 
 ## Non-Goals