nitm-ai-dev-toolkit 4.0.0 → 5.0.1

package/src/repo/.claude/agents-snippets/factory-spec-writer.md

@@ -0,0 +1,117 @@
+# Factory Spec Writer
+
+You turn a feature request into a testable spec, and then into a plan. You are one agent in the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you. The task line names your mode: **spec** or **plan**.
+
+## Inputs
+
+Read these, in this order:
+
+1. The feature request in your prompt.
+2. The project's `AGENTS.md` (conventions and commands).
+3. The existing code the feature touches. Inspect it. Do not write a spec or plan from the request alone.
+4. [Feature spec template](../../templates/feature-spec.template.md) for the section structure.
+5. Any existing `spec.md`, `plan.md`, and `tasks.md` in the feature folder, and the change note the orchestrator gave you (`spec-<k>.md` in spec mode, `plan-<k>.md` in plan mode). Update them, do not start over blind.
+6. `intake.md` in the job folder, if the paths block lists it: the operator's answers to the intake questions. They clarify the request and win over the request text where they conflict.
+
+## Spec mode
+
+You write `spec.md` in the feature folder (paths block). Nothing else.
+
+Use this skeleton, keeping the template's section order and dropping sections that do not apply (Timeline, References, Changelog):
+
+```markdown
+# Feature Specification: <short title>
+
+## Summary
+
+One paragraph: what changes for whom.
+
+## Background
+
+- **Problem:** what is wrong or missing today.
+- **Current behavior:** what the code does now, with file references.
+
+## Requirements
+
+- **FR-1:** The system shall ...
+- **FR-2:** ...
+
+## Acceptance Criteria
+
+Numbered, each one testable by a command or an observable step.
+
+- **AC-1:** Given ..., when ..., then ... (verify: `<command or step>`)
+- **AC-2:** ...
+
+## Affected Code
+
+- `path/to/file`: why it changes
+
+## Out of Scope
+
+- ...
+
+## Assumptions
+
+- Technical assumption: ...
+- **[PRODUCT DECISION]** Assumption that a person must decide: ... (options: ...)
+
+## Open Questions
+
+- ... (or "None")
+```
+
+Rules for the spec:
+
+- Every acceptance criterion must be testable. Name the check (a test, a command, or an observable UI step). "Works well" is not testable.
+- Acceptance criteria are numbered `AC-n`, and requirements are numbered `FR-n`. Builders and reviewers refer to these numbers.
+- Keep scope to what the request asks. Put tempting extras under Out of Scope.
+- An assumption that a product owner should decide is flagged `[PRODUCT DECISION]`. Do not decide it silently. The spec gate collects the operator's answer, and the approver escalates only on `[PRODUCT DECISION]` items still open in the spec.
+- Prefer the smallest spec that covers the request. Ponytail applies to specs too: if the request is already one line of code, say so in Summary and keep the rest short.
+- Do not write a size line or a plan in the spec. Sizing happens in plan mode.
+
+## Plan mode
+
+You write `plan.md` in the feature folder, and `tasks.md` for large work. Nothing else. Do not change `spec.md`.
+
+`plan.md` is concise. Use this skeleton:
+
+```markdown
+# Plan: <short title>
+
+**Size:** small — one line of reason. (The word after `Size:` is exactly one of `small`, `large`, or `unclear`.)
+
+## Approach
+
+Short: how the change is built, and which files it touches.
+
+## Steps
+
+1. <step, in build order>
+2. ...
+
+## Checks
+
+- AC-n: <test or command that proves it>
+```
+
+Sizing: **small** is one or two steps, so write no `tasks.md` and delete a stale one. **Large** has more steps than that, so write `tasks.md`. **Unclear** means you cannot tell from the spec and the code. Say why in the Size line; the operator decides at the plan gate.
+
+`tasks.md` (large only) is a slim list, one line per task, with no per-task sections:
+
+```markdown
+# Tasks: <KEY-or-slug>
+- [ ] T1 <one-line task>
+- [ ] T2 <one-line task> [P]
+```
+
+Number tasks `T1`, `T2`, and so on in build order. Add `[P]` only to tasks that can run in parallel. Do not write ticket keys; the orchestrator adds them at tracking.
+
+On a re-plan, keep each existing task line that still applies, with its T-number, its text, and any ` — <KEY>` suffix, unchanged. Match a kept task by its T-number and text. Number new tasks after the highest existing number. A line that already has a ticket key keeps it, because that ticket exists.
+
+## Rules
+
+- A change note with `spec-<k>.md` or `plan-<k>.md` is the operator's request. Apply it, and keep everything else the operator already accepted.
+- When a change note answers a `[PRODUCT DECISION]` item, rewrite that item to start with `[DECIDED]` and the operator's answer, for example `[DECIDED] Free tier: 3 seats.`. Items the note does not answer stay `[PRODUCT DECISION]`. Never mark an item decided yourself.
+- Keep `spec.md` and `plan.md` free of tooling chatter. They are feature docs that merge with the code.
+- Do not modify code, tests, `build.md`, `job.json`, `qa.md`, or any file outside the feature folder. Your writes are `spec.md` (spec mode), or `plan.md` and `tasks.md` (plan mode), in the feature folder only.

package/src/repo/.claude/agents-snippets/feature-builder.md

@@ -34,7 +34,7 @@ For each feature request:
 
 When dispatching a specialist subagent, provide:
 
-1. Full task description and acceptance criteria
+1. Full task description (the `tasks.md` line) and the acceptance criteria from `spec.md` that it covers
 2. Relevant file paths and patterns from the codebase
 3. Related tasks already completed (for context)
 4. Testing expectations

package/src/repo/.claude/commands/assign-tasks.md

@@ -7,6 +7,7 @@ argument-hint: "requirements or task file path"
 # Create Tickets from Requirements
 
 ## Agent Dispatch
+
 > **Recommended agent:** `fixer`
 > Task assignment and execution
 

package/src/repo/.claude/commands/factory.md

@@ -0,0 +1,24 @@
+---
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, merge (local, or a merge request on the forge)"
+allowed-tools: "Read, Grep, Glob, Write, Edit, Bash(*), agent"
+argument-hint: "[--in-place] <feature request> | start [--in-place] <request | KEY | slug | job-id> | approve <job-id> | rework <job-id> <note> | abandon <job-id> | status [--all] | watch [--all] | archive [--all] [--dry-run] | prune [--all] [--abandoned] [--dry-run]"
+---
+
+# Factory
+
+## Agent Dispatch
+> **Run in the main session.** The orchestrator dispatches these agents; they cannot dispatch others.
+
+| Agent | When to use |
+|-------|-------------|
+| `factory-spec-writer` | Spec stage (`spec` mode) writes `spec.md`; plan stage (`plan` mode) writes `plan.md` and `tasks.md` |
+| `factory-builder` | Build, repair, and rework: writes `build.md` in the job folder; its code goes in the build location |
+| `factory-reviewer-code` | Review round, `code` lens |
+| `factory-reviewer-security` | Review round, `security` lens |
+| `factory-reviewer-ux` | Review round, `ux` lens (opt-in) |
+| `factory-reviewer-ui` | Review round, `ui` lens (opt-in) |
+| `factory-approver` | Approval gate: writes `decision.md` |
+
+Dispatch each agent by its kebab-case name, as in the first column. Copilot may show a display name; pick the agent with that name.
+
+Follow the prompt defined in [.claude/prompt-snippets/factory.md](../prompt-snippets/factory.md).

package/src/repo/.claude/commands/ponytail-review.md

@@ -1,6 +1,6 @@
 ---
 description: Review changes for over-engineering — find what can be deleted
-allowed-tools: "Read, Grep"
+allowed-tools: "Read, Grep, Bash(git diff:*), Bash(git status:*), Bash(git show:*)"
 argument-hint: "no arguments required"
 ---
 

package/src/repo/.claude/prompt-snippets/assign-tasks.md

@@ -50,9 +50,17 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
 1. **Parse Document**:
    - Load the specified document (.md, .txt, .json)
    - Detect document structure (headers, lists, task categories)
-   - Extract task hierarchy: Epic → Story → Task → Subtask
+   - For `tasks.md`, detect the format first:
+     - **Slim** (has `- [ ] T<n>` or `- [x] T<n>` lines): each such line is one task. The text after the ID is the summary. Sub-bullets, if any, are subtasks. A line already has a ticket only when it ends with ` — {{PROJECT_KEY}}-<digits>`; skip it then. Any other ` — ` suffix (e.g. ` — depends on T3`) is a note, not a key: keep the line
+     - **Legacy** (no slim lines; has `#{2,4} T<n>` headings, e.g. `## T01`, `### T001`): each `T<n>` heading is one task. Checkboxes beneath it are subtasks: put them in the ticket description, never as separate tickets. Skip a heading that contains `{{PROJECT_KEY}}-<digits>` anywhere (e.g. `## T001 (PROJ-256): …`); it already has a ticket
+     - **Mixed** (slim lines and legacy headings): treat as slim and say in the report that the headings were ignored
+     - **Neither**: treat as a requirement document
+     - Keys are always `{{PROJECT_KEY}}-<digits>`. Nothing else counts as a key
+   - For requirement documents: extract task hierarchy: Epic → Story → Task → Subtask
 
 2. **Consolidate First** (BEFORE creating tickets):
+   - **A slim `tasks.md` from `/tasks` is pre-consolidated**: one line = one ticket. Only merge lines that are clearly one deliverable; do not re-split them
+   - **A legacy `tasks.md` is not pre-consolidated**: one heading = one ticket. Never merge or re-split headings. If the count exceeds the Maximum Ticket Counts, stop and ask before creating anything
    - **Group related items** by component, feature area, or deliverable
    - **Merge small tasks** (< 2 SP) into related larger tasks
    - **Eliminate redundant subtasks** that are obvious steps
@@ -64,7 +72,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - **Task**: Implementation work, 2-8 story points (avoid < 2 SP)
    - **Subtask**: Only for complex tasks, 1-3 story points (use sparingly)
 
-4. **Estimate Effort**:
+4. **Estimate Effort** (`tasks.md` has no effort field: take hours from `plan.md` for the matching work, or estimate from the scope in `spec.md`):
    - 0.5-1 hours → **Merge with related task** (too small alone)
    - 2-3 hours → 2 story points
    - 4-6 hours → 3-5 story points
@@ -76,9 +84,13 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - Link child issues to parents
    - Set assignees, labels, and story points
    - Create dependency links where noted
+   - Ticket description: the task summary plus the acceptance criteria from `spec.md` for that deliverable
+   - **Slim `tasks.md`**: append ` — <KEY>` at the end of the task's line, after any notes (`- [ ] T1 Schema + migration — PROJ-124`)
+   - **Legacy `tasks.md`**: never write back. Record heading → ticket key in the report instead
 
 6. **Generate Report**:
    - List all created tickets with IDs
+   - **Legacy `tasks.md`**: heading → ticket key mapping, plus headings skipped because they already had a key
    - Show hierarchy and relationships
    - Report total story points
    - **Consolidation summary**: "Merged X raw items into Y tickets"
@@ -149,6 +161,8 @@ Creating tickets...
 
 ## Document Format Support
 
+**Legacy `tasks.md` worked example**: a file with 45 `## T<n>` / `### T<n>` headings and 266 checkboxes plans **45 tickets**, not 266. Each ticket's description lists that heading's checkboxes. If 2 headings already carry a `{{PROJECT_KEY}}-<digits>` key, plan 43. Do not modify the file; report the heading → key mapping.
+
 **Markdown Headers**:
 
 ```markdown

package/src/repo/.claude/prompt-snippets/bootstrap-patch.md

@@ -1,12 +1,12 @@
 # Bootstrap Patch
 
-Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit repository's `v4.x` branch and merge updated, new, or missing guidance into this project.
+Fetch the published toolkit templates for the target version (4.0.0 or later) from npm or the ai-assisted-dev-toolkit repository's `<version>` git tag, and merge updated, new, or missing guidance into this project.
 
 ## OpenCode version preflight (before any changes)
 
 - Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
-- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
-- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
 - If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
 - If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
@@ -25,6 +25,8 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
 /bootstrap-patch --category commands,prompts
 ```
 
+The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit patch --dry-run` previews changes, `--only <categories>` and `--exclude <categories>` narrow the scope, and `npx nitm-ai-dev-toolkit upgrade@<version>` (or `--version <version>`) pins the target version. Pinning a version does not skip the gates in Step 1.
+
 ## Process
 
 **Codex invocation and scope:** `/bootstrap-patch` is not a native Codex command. Ask Codex to read and follow this snippet as a task document. Identify the actual harness from session/runtime evidence or ask; scaffold directories do not prove use. Codex targets `AGENTS.md`, relevant nested instructions, `.agents/skills/`, and optional `.codex/config.toml`. Include `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources for Codex-scoped installs, not automatically loaded rules or evidence of Copilot/Claude use. Only include other harness command, agent, and config categories when those harnesses are confirmed in use.
@@ -33,33 +35,38 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
 
 1.  **Fetch Latest Templates**:
 
-    Fetch only the supported `v4.x` source branch:
+    **Resolve versions before any download.**
+    - **Installed version**: read `.toolkit-version` in the project root. If it is missing or unparseable, **STOP** and ask the user to confirm the installed version; absence alone does not prove a pre-3.0 installation.
+    - **Target version**: use the version the user pinned (`upgrade@<version>` or `--version <version>` in the CLI, or the version given to this task), validated as SemVer `X.Y.Z`. Otherwise use the latest published version from `npm view nitm-ai-dev-toolkit version`. If npm is unreachable or the output is unparseable, **STOP** and ask. Never guess a version.
+
+    **Fetch the matching release.** Try Option A first and use Option B only if `npm pack` fails (for example, the version is not on npm). Each download goes into a new, empty directory:
 
     ```bash
     set -e
-    TOOLKIT_TEMP=$(mktemp -d)
-    git clone --depth 1 --branch v4.x https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
+    TOOLKIT_TEMP=$(mktemp -d)   # removed in step 6
+    mkdir "$TOOLKIT_TEMP/pack" "$TOOLKIT_TEMP/unpacked"
+    # Option A (preferred): the published package, the same artifact users install
+    if (cd "$TOOLKIT_TEMP/pack" && npm pack "nitm-ai-dev-toolkit@<version>"); then
+      tar -xzf "$TOOLKIT_TEMP/pack/nitm-ai-dev-toolkit-<version>.tgz" -C "$TOOLKIT_TEMP/unpacked"
+      SOURCE_ROOT="$TOOLKIT_TEMP/unpacked/package"
+    else
+      # Option B (fallback): the git tag for that release (tags have no "v" prefix)
+      git clone --depth 1 --branch "<version>" https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP/git"
+      SOURCE_ROOT="$TOOLKIT_TEMP/git"
+    fi
     ```
 
-    **Source availability gate:** If the clone fails or `v4.x` is unavailable (for example, not yet published), **STOP** before diff/apply/version marking. Do not fall back to the default branch or V3, and do not push/publish a branch to unblock this task; ask for an approved available v4.x source.
+    **Source availability gate:** If both `npm pack` and the tag clone fail (the version is unpublished and the tag is missing), **STOP** before diff/apply/version marking. Do not fall back to the default branch, another version, or an older major, and do not publish anything to unblock this task; ask for an available source version.
 
-    Determine the correct source path based on project structure:
-    - **Single repo**: Use `$TOOLKIT_TEMP/src/repo/`
-    - **Monorepo**: Use `$TOOLKIT_TEMP/src/monorepo/`
+    Determine the correct source path based on project structure, under `$SOURCE_ROOT`:
+    - **Single repo**: `$SOURCE_ROOT/src/repo/`
+    - **Monorepo**: `$SOURCE_ROOT/src/monorepo/`
 
     Detection heuristic:
     - If `apps/` and `packages/` directories exist at root → monorepo
     - Otherwise → single repo
 
-    **Detect Toolkit Version:**
-
-    Check for a `.toolkit-version` file in the project root:
-    - If exists: Read the version string (e.g., `2.0.10`, `3.0.0`)
-    - If missing: Verify the installed version or legacy state with the user; absence alone does not prove a pre-3.0 installation
-
-    Read the toolkit's version from the `version` field in `$TOOLKIT_TEMP/package.json` to compare; `.toolkit-version` tracks the target project's installed version.
-
-    **Source version guard (before diff/apply/version marking):** Parse source/target versions as SemVer and compare them (major/minor/patch numerically). If the fetched package's major is not `4`, or its version is older than the target `.toolkit-version`, **STOP** without diffing, applying changes, or updating the marker. Unknown/unparseable versions must also **STOP** and ask rather than guess. Never auto-downgrade.
+    **Source version gate (before diff/apply/version marking):** Read the `version` field in `$SOURCE_ROOT/package.json` and parse it as SemVer. The fetched version must equal the target version exactly, its major must be greater than or equal to the installed major from `.toolkit-version`, and it must not be older than the installed `.toolkit-version`. If any check fails, or a version is unknown or unparseable, **STOP** without diffing, applying changes, or updating the marker. Never auto-downgrade, and never hard-code a major.
 
     **Version Comparison:**
     - **Same version**: No structural changes expected
@@ -102,9 +109,9 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
 
     - Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
     - The version preflight must pass before changes. Back up V1 before native conversion (converted files are incompatible with V1). Preserve models/providers/user-global plugins. Only with approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema keeps `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter.
-    - **Ponytail replacement (plan here; apply after backup and approval in Step 5):** Remove only known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies. Preserve unrelated local plugins. Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` registration in the local `plugins` array where appropriate, retaining other registrations/options; do not edit global config. Keep `opentmux` commented as V1-only. Do not port local APIs or add bridges; runtime integration is untested. Native local discovery needs no duplicate registration.
-    - `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text: explicitly read snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
-    - `--env opencode` supplies minimal shared references without other harness activation. Activate on the next run/restart and report only installed-V2 checks actually run, not assumed runtime validation. Publishing 4.0.0 has not been executed.
+    - **Obsolete Ponytail cleanup (plan here; apply after backup and approval in Step 5):** Remove only known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies. Preserve unrelated local plugins. The OpenCode Ponytail plugin is installed globally by the operator; never add it to project config. If it is not installed globally, tell the operator to install it globally. Do not edit global config. Keep `opentmux` commented as V1-only. Do not port local APIs or add bridges; runtime integration is untested.
+    - Ambient `AGENTS.md` works. `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@refs` are ordinary text: explicitly read snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
+    - `--env opencode` supplies minimal shared references without other harness activation. Activate on the next run/restart and report only installed-V2 checks actually run, not assumed runtime validation.
 
 3.  **Diff Analysis** (parallelizable — dispatch one subagent per category):
 
@@ -175,8 +182,8 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
       a. **New files**: Copy directly from template
       b. **Updated files (no customization)**: Replace with template version
       c. **Updated files (customized)**: Apply structural additions while preserving project values
-      d. **OpenCode plugins**: Apply only the approved Ponytail replacement above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins.
-      e. **Toolkit version**: Update `.toolkit-version` to the fetched toolkit version (`4.0.0` for this migration) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
+      d. **OpenCode plugins**: Apply only the approved obsolete Ponytail cleanup above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins. Never add Ponytail to project config.
+      e. **Toolkit version**: Keep the `.toolkit-version` value the CLI writes for the verified target version (the installed package version, 4.0.0 or later; never hard-coded) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
       f. **Git commit**: Stage and commit all changes with message:
       ```bash
       git add -A

package/src/repo/.claude/prompt-snippets/bootstrap-upgrade.md

@@ -1,12 +1,12 @@
-# Bootstrap Upgrade to v4.0
+# Bootstrap Upgrade to toolkit <version>
 
-Upgrade to toolkit 4.0.0, including native OpenCode V2 for confirmed OpenCode users. For pre-3.0 installations, also migrate inline content to snippet-based architecture and clean up duplicate skills. Only modify confirmed harness targets; preserve unrelated harness/Codex behavior.
+Upgrade to toolkit <version> (the installed package version), including native OpenCode V2 for confirmed OpenCode users (toolkit 4.0.0 and later). For pre-3.0 installations, also migrate inline content to snippet-based architecture and clean up duplicate skills. Only modify confirmed harness targets; preserve unrelated harness/Codex behavior.
 
 ## OpenCode version preflight (before any changes)
 
 - Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
-- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
-- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
 - If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
 - If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
@@ -21,7 +21,7 @@ Read `.toolkit-version` and select the route before dispatching agents or changi
 
 ## OpenCode migration guardrails
 
-Back up V1; native-converted files are incompatible with V1. Preserve models/providers/user-global plugins. Templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0`; obsolete toolkit-local Ponytail copies are replaced only after backup and approval (Step 7), with no API port or bridge. Keep `opentmux` commented as V1-only. Only with approval, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter. Activate on the next run/restart; plugin/runtime integration is untested and publishing 4.0.0 has not been executed.
+Back up V1; native-converted files are incompatible with V1. Preserve models/providers/user-global plugins. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator and is never registered by templates or project config; obsolete toolkit-local Ponytail copies are removed only after backup and approval (Step 7), with no API port or bridge. Keep `opentmux` commented as V1-only. Only with approval, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter. Activate on the next run/restart; plugin/runtime integration is untested.
 
 ## Usage
 
@@ -56,7 +56,7 @@ Run all checks before making any changes:
 3. **Confirm migration scope**:
 
    ```markdown
-   ## 🔄 Bootstrap Upgrade: toolkit v4.0.0
+   ## 🔄 Bootstrap Upgrade: toolkit <version>
 
     **Project type**: repo | monorepo
     **Current version**: <version or "none (legacy)">
@@ -68,7 +68,7 @@ Run all checks before making any changes:
     2.  Confirmed OpenCode only: merge native V2 host files and approved missing wrappers (Step 7)
     3.  Verified legacy only: approved hook installation and verified identical duplicate skill cleanup (Steps 8–10); preserve custom skills
     4.  Merge only applicable missing documentation and validate the selected route; v3 keeps existing snippet bodies/frontmatter unchanged
-    5.  Create `.toolkit-version` with `4.0.0` after the approved migration
+    5.  Keep the `.toolkit-version` the CLI writes (installed package version, 4.0.0 or later) after the approved migration
     6.  Commit all changes
 
    Proceed? (Y/n)
@@ -176,18 +176,17 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
      "$schema": "https://opencode.ai/config.json",
       "instructions": ["AGENTS.md", ".opencode/rules/*.md"],
       "skills": [".agents/skills"],
-      "plugins": ["@dietrichgebert/ponytail@4.12.0"],
       "lsp": true
    }
    ```
 
    Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published schema may describe V1; do not use it or a V1 API fetch as native V2 validation authority. Use `agents`/JSON `system` (Markdown bodies for file agents), `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
 
-   `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text, not attachments: wrappers must explicitly tell agents to read referenced snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics). `--env opencode` supplies minimal shared references without other harness activation. Verify using installed V2 after the next run/restart; report only checks actually run.
+   Ambient `AGENTS.md` works. `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@refs` are ordinary text, not attachments: wrappers must explicitly tell agents to read referenced snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics). `--env opencode` supplies minimal shared references without other harness activation. Verify using installed V2 after the next run/restart; report only checks actually run.
 
 2. **Replace obsolete toolkit Ponytail (backup and approval only)**:
    - Back up the local config and known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies; obtain approval before removing only those copies. Preserve unrelated local plugins.
-   - Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` package in the local `plugins` array where appropriate, preserving other registrations/options. Do not edit global config or overwrite global plugins. Keep `opentmux` commented as V1-only; do not copy local Ponytail source, port APIs, or introduce bridges. Native local discovery needs no duplicate explicit registration; runtime integration remains untested.
+   - The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator. Never add or pin it in the local `plugins` array. Check whether it is installed globally; if not, tell the operator to install it globally. Do not edit global config or overwrite global plugins. Keep `opentmux` commented as V1-only; do not copy local Ponytail source, port APIs, or introduce bridges. Runtime integration remains untested.
 
 3. **Create wrappers with explicit snippet-read instructions** — one file per snippet:
 
@@ -252,12 +251,13 @@ If `CLAUDE.md` is an applicable confirmed harness target and a thin redirect to
 
 See existing `CLAUDE.md` in the toolkit template (`src/repo/CLAUDE.md`) for the exact format.
 
-### 12. Create `.toolkit-version` File
+### 12. Check `.toolkit-version` File
 
 Only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope):
 
 ```bash
-echo "4.0.0" > .toolkit-version
+# Keep the value the CLI wrote (the installed package version). If it is missing, record it with the CLI:
+npx nitm-ai-dev-toolkit patch
 ```
 
 ### 13. Validation
@@ -277,13 +277,13 @@ If `--verbose`: log each check result with file paths.
 
 ### 14. Generate Upgrade Report
 
-Output the report to stdout (and optionally to `docs/upgrade-report-v4.md`). Include only operations/checks actually performed for the selected route; omit legacy extraction/cleanup rows on v3 and never pre-mark skipped checks as passed:
+Output the report to stdout (and optionally to `docs/upgrade-report-<version>.md`). Include only operations/checks actually performed for the selected route; omit legacy extraction/cleanup rows on v3 and never pre-mark skipped checks as passed:
 
 ```markdown
 ## 🚀 Bootstrap Upgrade Report
 
 **From**: detected installed version (include inline extraction only for pre-3.0)
-**To**: 4.0.0 (native V2 for confirmed OpenCode use; snippet conversion only for verified legacy)
+**To**: <version> (toolkit 4.0.0 or later; native V2 for confirmed OpenCode use; snippet conversion only for verified legacy)
 **Selected route**: verified legacy | v3 native OpenCode
 **Date**: {{DATE}}
 **Dry run**: yes | no
@@ -317,7 +317,7 @@ Output the report to stdout (and optionally to `docs/upgrade-report-v4.md`). Inc
 
 ### Files Created
 
-- `.toolkit-version` — 4.0.0
+- `.toolkit-version` — installed package version (written by the CLI)
 
 ### Validation
 
@@ -337,7 +337,7 @@ If not `--dry-run`, stage and commit all changes:
 
 ```bash
 git add -A
-git commit -m "chore: upgrade AI instructions to toolkit v4.0.0"
+git commit -m "chore: upgrade AI instructions to toolkit <version>"
 ```
 
 If `--dry-run`: skip commit, note in report: "Dry run — no changes committed."

package/src/repo/.claude/prompt-snippets/bootstrap.md

@@ -5,8 +5,8 @@ Analyze the project structure and customize AI instruction templates for this co
 ## OpenCode version preflight (before any changes)
 
 - Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
-- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
-- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
 - If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
 - If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
@@ -100,26 +100,36 @@ Detect the language ecosystem by checking for these files:
 
 Map discovered information to template variables:
 
-| Variable                    | Source                                                                      |
-| --------------------------- | --------------------------------------------------------------------------- |
-| `{{PROJECT_NAME}}`          | Config file name field or directory                                         |
-| `{{PROJECT_DESCRIPTION}}`   | Config description or README                                                |
-| `{{LANGUAGE}}`              | Detected language (TypeScript, PHP, C#, Python, etc.)                       |
-| `{{FRAMEWORK}}`             | Detected framework with version                                             |
-| `{{PACKAGE_MANAGER}}`       | Lock file or config (npm, composer, dotnet, pip, bundler, go, cargo, maven) |
-| `{{DEV_PORT}}`              | Scripts, config, or framework default                                       |
-| `{{SRC_DIR}}`               | Source directory structure                                                  |
-| `{{TEST_DIR}}`              | Test directory location                                                     |
-| `{{FILE_EXTENSION}}`        | Primary extension (ts, php, cs, py, rb, go, rs, java)                       |
-| `{{DATABASE}}`              | ORM/database dependencies                                                   |
-| `{{TEST_FRAMEWORK}}`        | Test framework                                                              |
-| `{{DEPLOY_PLATFORM}}`       | Deployment config files                                                     |
-| `{{RUNTIME_VERSION}}`       | Runtime version from config                                                 |
-| `{{ISSUE_TRACKER}}`         | Detected project management tool                                            |
-| `{{PM_URL}}`                | Project management tool URL/workspace (if applicable)                       |
-| `{{PROJECT_KEY}}`           | Project ID or workspace ID (if applicable)                                  |
-| `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###)                                           |
-| `{{NEW_RELEVANT_VARIABLE}}` | ...other inferred values...                                                 |
+| Variable                    | Source                                                                                                                                                                                                     |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{{PROJECT_NAME}}`          | Config file name field or directory                                                                                                                                                                        |
+| `{{PROJECT_DESCRIPTION}}`   | Config description or README                                                                                                                                                                               |
+| `{{LANGUAGE}}`              | Detected language (TypeScript, PHP, C#, Python, etc.)                                                                                                                                                      |
+| `{{FRAMEWORK}}`             | Detected framework with version                                                                                                                                                                            |
+| `{{PACKAGE_MANAGER}}`       | Lock file or config (npm, composer, dotnet, pip, bundler, go, cargo, maven)                                                                                                                                |
+| `{{SETUP_COMMAND}}`         | Install step from the lock file (`npm ci`, `pnpm install --frozen-lockfile`, `composer install`, `dotnet restore`, `pip install -r requirements.txt`); a `setup` script or Makefile target wins if present |
+| `{{DEV_PORT}}`              | Scripts, config, or framework default                                                                                                                                                                      |
+| `{{DEV_COMMAND}}`           | `dev` or `start` script, Makefile `dev` target, or framework CLI (`php artisan serve`, `dotnet run`, `cargo run`)                                                                                          |
+| `{{DEV_PORT_FLAG}}`         | Flag or env var that sets the dev port: `--port <port>`, `-- --port <port>` (npm script passthrough), or `PORT=<port>`; check the script and framework config. Ask if none                                 |
+| `{{SRC_DIR}}`               | Source directory structure                                                                                                                                                                                 |
+| `{{TEST_DIR}}`              | Test directory location                                                                                                                                                                                    |
+| `{{FILE_EXTENSION}}`        | Primary extension (ts, php, cs, py, rb, go, rs, java)                                                                                                                                                      |
+| `{{DATABASE}}`              | ORM/database dependencies                                                                                                                                                                                  |
+| `{{TEST_FRAMEWORK}}`        | Test framework                                                                                                                                                                                             |
+| `{{TEST_COMMAND}}`          | `test` script, or the runner (`vitest run`, `phpunit`, `pytest`, `go test ./...`, `cargo test`, `dotnet test`)                                                                                             |
+| `{{LINT_COMMAND}}`          | `lint` script, or the linter (ESLint, Biome, ruff, phpstan, golangci-lint, clippy, dotnet format)                                                                                                          |
+| `{{BUILD_COMMAND}}`         | `build` script, or the build tool (`go build ./...`, `cargo build`, `dotnet build`, `mvn package`)                                                                                                         |
+| `{{DEPLOY_PLATFORM}}`       | Deployment config files                                                                                                                                                                                    |
+| `{{RUNTIME_VERSION}}`       | Runtime version from config                                                                                                                                                                                |
+| `{{ISSUE_TRACKER}}`         | Detected project management tool                                                                                                                                                                           |
+| `{{PM_URL}}`                | Project management tool URL/workspace (if applicable)                                                                                                                                                      |
+| `{{PROJECT_KEY}}`           | Project ID or workspace ID (if applicable)                                                                                                                                                                 |
+| `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###)                                                                                                                                                                          |
+| `{{DEFAULT_BRANCH}}`        | `git symbolic-ref --short refs/remotes/origin/HEAD`, minus `origin/`; else `main`                                                                                                                          |
+| `{{FACTORY_PORT_BASE}}`     | Only if Factory is installed. Default `5100`                                                                                                                                                                                             |
+| `{{APPROVAL_MODE}}`         | Only if Factory is installed. Default `human`                                                                                                                                                                                            |
+| `{{FACTORY_REVIEW_LENSES}}` | Only if Factory is installed. Default `code, security`; add `ux, ui` only if the project has a UI and a browser tool is configured (for example a browser MCP server)                                                                    |
+| `{{NEW_RELEVANT_VARIABLE}}` | ...other inferred values...                                                                                                                                                                                |
 
 ### Step 2.5: Project Management Detection
 
@@ -242,23 +252,23 @@ Follow the official [V2 migration](https://opencode.ai/v2/docs/migrate-v1), [con
 
 - After the version preflight passes, use `agents` with JSON `system` or Markdown bodies; `request.body.temperature`; ordered `permissions` rules (`action`, `resource`, `effect`; `shell`/`subagent`; last match wins); `commands` with `subagent`; `plugins` with `{ "package": "…", "options": {} }`; `skills` as directory-path arrays; `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
 - Back up V1; native-converted files are incompatible with V1. Merge, don't clobber models/providers/user-global plugins. With approval only, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema retains its own `prompt`, `permission`, and `variant`; do not host-migrate it or upgrade the separate external starter silently.
-- Templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0` locally; no local Ponytail source is bundled or ported. Keep `opentmux` commented as V1-only. Native local discovery needs no duplicate registration; do not introduce API ports or bridges or claim tested runtime integration.
-- Config `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text: explicitly read referenced snippet docs. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`, but use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics).
-- `--env opencode` supplies minimal shared references without activating other harnesses. Activate on the next run/restart and report only checks actually run using installed V2; scaffold/placeholder checks are not runtime validation. Publishing 4.0.0 has not been executed.
+- The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`, the author's native V2 package) is installed globally by the operator. Templates do not register or pin it, and no local Ponytail source is bundled or ported. Keep `opentmux` commented as V1-only. Do not introduce API ports or bridges or claim tested runtime integration.
+- Ambient `AGENTS.md` works. Config `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@refs` are ordinary text: explicitly read referenced snippet docs. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`, but use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics).
+- `--env opencode` supplies minimal shared references without activating other harnesses. Activate on the next run/restart and report only checks actually run using installed V2; scaffold/placeholder checks are not runtime validation.
 
 **Ponytail pre-activation cleanup (confirmed OpenCode use only):**
 
 1. In this bootstrap flow, inspect `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` for existing-target leftovers. Verify obsolete toolkit ownership from contents/provenance, not filename alone; absent paths need no deletion. Preserve unrelated/custom plugins and global config.
 2. Back up the local config and verified obsolete toolkit copies, obtain explicit removal approval, then remove ONLY those copies. Do not automatically delete files in the CLI or remove custom plugins.
-3. With approval, merge/deduplicate upstream `@dietrichgebert/ponytail@4.12.0` registration locally where appropriate, preserving other registrations/options and leaving global config untouched. No API port or bridge.
+3. Never add `@dietrichgebert/ponytail` to project `.opencode/opencode.jsonc`. Check whether it is installed globally; if not, tell the operator to install it globally and leave global and project config untouched. No API port or bridge.
 4. If any present copy's ownership or safe removal is unverified, or required removal approval is denied, **STOP OpenCode activation and migration completion**; leave `.toolkit-version` unchanged and report blocked, not complete. Proceed/restart only after this gate passes; runtime integration remains untested.
 
 **Create Toolkit Version File:**
 
-Create a `.toolkit-version` file in the project root with the current toolkit version only after the OpenCode preflight and Ponytail cleanup gate pass (or OpenCode is confirmed out of scope):
+Confirm `.toolkit-version` in the project root. The CLI writes it on install and patch with the installed package version. For toolkit 4.0.0 or later, keep the value the CLI wrote; do not write it by hand or overwrite it with a hard-coded version. If it is missing, run `npx nitm-ai-dev-toolkit patch` only after the OpenCode preflight and Ponytail cleanup gate pass (or OpenCode is confirmed out of scope). Expected form:
 
 ```
-4.0.0
+<installed package version, for example 5.0.0>
 ```
 
 This file enables `bootstrap-patch` to detect version changes and apply migrations automatically.

package/src/repo/.claude/prompt-snippets/factory.md

@@ -0,0 +1,20 @@
+---
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, merge (local, or a merge request on the forge)"
+---
+
+You are the factory orchestrator for this session. Arguments: $ARGUMENTS
+
+Follow the [factory orchestrator skill](../../.agents/skills/factory/SKILL.md) exactly. It defines every invocation (`<request>` for intake, `start`, `approve`, `rework`, `abandon`, `status [--all]`, `watch [--all]`, `archive [--all] [--dry-run]`, `prune [--all] [--abandoned] [--dry-run]`), intake questions, feature folder resolution, the job layout, the spec and plan gates, tickets, the stages, the verdict rules, the paths block, and the merge procedure.
+
+Ground rules:
+
+- Run the orchestrator in this session. Dispatch the `factory-*` agents for every spec, plan, build, review, and approval step, and do not write their files yourself.
+- Only write `job.json`, `intake.md`, `spec-<k>.md`, `plan-<k>.md`, `rework-<k>.md`, the escalation `decision.md`, `merge-conflict.md`, `bootstrap.md`, the ticket keys in `tasks.md`, the feature folder rename or copy, the feature docs commit on the job branch, and worktree, branch, or merge steps, and the `archive` moves.
+- Intake asks in chat before any folder, job, or spec exists. Hold the intake gate: nothing is created until the operator picks to continue.
+- Hold the spec gate and the plan gate: nothing is planned, ticketed, or built until the operator confirms in chat. The spec cannot be confirmed while a `[PRODUCT DECISION]` item is open.
+- `--in-place` on the command, or the operator saying in place, builds in the main checkout instead of a worktree. Only a new job takes it.
+- `abandon <job-id>` closes a job without merging it. Ask first when an agent may still be running.
+- Local merges never push. With `MERGE_MODE` set to `push-mr`, the branch is pushed and its merge request opened only on `/factory approve` or an `auto` APPROVE, and never force-pushed.
+- `archive` moves closed jobs only, to `factory/archive/`. It deletes an abandoned job's branch and worktree only after the operator says yes.
+- `prune` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation in chat: merged jobs by default, and abandoned jobs too with `--abandoned`. It never touches an open job or the feature folders.
+- If `$ARGUMENTS` is empty, show the invocation list from the skill and ask which one the user wants.

package/src/repo/.claude/prompt-snippets/implement-feature.md

@@ -55,7 +55,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
    - Understand dependencies
 
    c. **Implement (TDD required)**:
-   - Follow acceptance criteria exactly
+   - Follow the acceptance criteria in `spec.md` for this task's deliverable
    - Use patterns from `AGENTS.md`
    - **Write a failing test first** — one behavior per test, clear name, real code
    - **Verify it fails** — watch it fail for the right reason (feature missing, not error)
@@ -85,7 +85,9 @@ Implement a feature by completing tasks sequentially with proper tracking.
    git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"
    ```
 
-   f. **Mark Task Complete**
+   f. **Mark Task Complete**:
+   - Slim `tasks.md`: tick `- [x]` on the task's line
+   - Legacy `tasks.md`: tick `- [x]` only on checkboxes under the current task's heading (until the next heading). Never tick checkboxes under other headings. If that heading has no checkboxes, report "no checkboxes under <heading>; nothing ticked" and continue
 
 5. **Post-Implementation Review**:
    - Dispatch **Reviewer** agent on all changes before proceeding