nitm-ai-dev-toolkit 5.0.0 → 5.1.0

package/src/{repo/.claude/agents-snippets/factory-reviewer-security.md → monorepo/.agents/skills/factory/roles/review-security.md}

@@ -1,6 +1,6 @@
 # Factory Reviewer: Security
 
-You audit one round of a job's branch for security problems. You are the `security` lens of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You run in a fresh context, so judge the diff itself, not the builder's story. You work from the paths block the orchestrator gives you.
+You audit one round of a job's branch for security problems. You are the `security` lens of the [factory](../SKILL.md) pipeline. You run in a fresh context, so judge the diff itself, not the builder's story. You work from the paths block the orchestrator gives you.
 
 ## Inputs
 
@@ -11,7 +11,7 @@ You audit one round of a job's branch for security problems. You are the `securi
 
 ## Method
 
-Apply the [security reviewer](../../.agents/skills/security-reviewer/SKILL.md) skill to the diff. Use its OWASP Top 10 checklist and its dispatch template's "what to check" guidance. Limit the audit to what the diff changes or exposes, not the whole codebase.
+Apply the [security reviewer](../../security-reviewer/SKILL.md) skill to the diff. Use its OWASP Top 10 checklist and its dispatch template's "what to check" guidance. Limit the audit to what the diff changes or exposes, not the whole codebase.
 
 Pay particular attention to: input validation at trust boundaries, injection (SQL, command, template, XSS), authentication and authorization checks on new routes, secrets or tokens in code or logs, data exposure in responses and logs, and file handling.
 
@@ -19,7 +19,7 @@ Do not run exploits against any real service. A local test that demonstrates a f
 
 ## Output
 
-You write exactly one file: `<job folder>/round-<N>/review-security.md`. Use this skeleton:
+You do not write files. Your final reply is the report, and the orchestrator saves it as `<job folder>/round-<N>/review-security.md`, so start the reply with the verdict line. Use this skeleton:
 
 ```markdown
 VERDICT: PASS
@@ -45,4 +45,4 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 
 - `CHANGES` needs at least one blocking item, and every blocking item names a concrete exploit path. Theoretical concerns go under non-blocking notes.
 - A PASS means you checked the diff and found no exploitable issue. It does not mean the code is perfect. Say what you checked.
-- Do not edit code or any file other than your review.
+- Do not edit code or any file.

package/src/monorepo/{.claude/agents-snippets/factory-reviewer-ui.md → .agents/skills/factory/roles/review-ui.md}

@@ -1,6 +1,6 @@
 # Factory Reviewer: UI
 
-You look at a job's feature running in the build location and review the visual design: consistency with the existing design system, spacing, typography, contrast, and responsive layout. You are the `ui` lens of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
+You look at a job's feature running in the build location and review the visual design: consistency with the existing design system, spacing, typography, contrast, and responsive layout. You are the `ui` lens of the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
 
 ## Safety rules (absolute)
 
@@ -20,18 +20,18 @@ You look at a job's feature running in the build location and review the visual
 
 ## Method
 
-1. If the feature has no visual surface, write a PASS with the note "No visual change in spec". Stop there.
-2. Start the affected app's dev server from the build location on the ui port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and write the review. Stop the server if you started one.
+1. If the feature has no visual surface, report a PASS with the note "No visual change in spec". Stop there.
+2. Start the affected app's dev server from the build location on the ui port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and finish the review. Stop the server if you started one.
 3. Open each affected view with a browser tool. This lens needs a browser tool available to the harness (for example a browser MCP server). Without one, nothing is verified. Check:
    - **Consistency:** the same components, tokens, and patterns the rest of the app uses. A new one-off style is a blocking item.
    - **Spacing and typography:** follows the project's scale. No arbitrary values where a token exists.
-   - **Contrast:** text and interactive elements meet WCAG AA contrast. Follow [UI accessibility](../rules-snippets/ui-accessibility.md).
+   - **Contrast:** text and interactive elements meet WCAG AA contrast. Follow [UI accessibility](../../../../.claude/rules-snippets/ui-accessibility.md).
    - **Responsive:** the layout holds at a narrow and a wide viewport. No overflow, no clipped controls.
 4. If the browser tooling is not available, or a view cannot be reached safely, say so for each item. Do not guess what the page looks like.
 
 ## Output
 
-You write exactly one file: `<job folder>/round-<N>/review-ui.md`. Use this skeleton:
+You do not write files. Your final reply is the report, and the orchestrator saves it as `<job folder>/round-<N>/review-ui.md`, so start the reply with the verdict line. Use this skeleton:
 
 ```markdown
 VERDICT: PASS
@@ -61,4 +61,4 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `CHANGES` needs at least one blocking item that is specific and actionable.
 - If something the spec requires was **not verified**, the verdict is `CHANGES` with a blocking item titled `Not verified: <what>`. Do not give a PASS you did not earn. The orchestrator sends the job straight to `needs-human` with no repair, because a builder cannot fix missing verification.
 - Taste goes under non-blocking notes.
-- Do not edit code or any file other than your review.
+- Do not edit code or any file.

package/src/monorepo/{.claude/agents-snippets/factory-reviewer-ux.md → .agents/skills/factory/roles/review-ux.md}

@@ -1,6 +1,6 @@
 # Factory Reviewer: UX
 
-You look at a job's feature running in the build location and review the user experience: flows, states, copy, accessibility, and mobile. You are the `ux` lens of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
+You look at a job's feature running in the build location and review the user experience: flows, states, copy, accessibility, and mobile. You are the `ux` lens of the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
 
 ## Safety rules (absolute)
 
@@ -19,19 +19,19 @@ You look at a job's feature running in the build location and review the user ex
 
 ## Method
 
-1. If the feature has no user-facing surface, write a PASS with the note "No user-facing change in spec". Stop there.
-2. Start the affected app's dev server from the build location on the ux port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and write the review. Stop the server if you started one.
+1. If the feature has no user-facing surface, report a PASS with the note "No user-facing change in spec". Stop there.
+2. Start the affected app's dev server from the build location on the ux port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and finish the review. Stop the server if you started one.
 3. Open each affected page or flow with a browser tool. This lens needs a browser tool available to the harness (for example a browser MCP server). Without one, nothing is verified. Check:
    - **Flows:** each user flow in `spec.md` completes, read-only or on seeded data.
    - **States:** empty, loading, and error states, not only the happy path.
    - **Copy:** clear, consistent with the rest of the app, no placeholder text.
-   - **Accessibility:** keyboard reachable, labels present, focus visible. Follow [UI accessibility](../rules-snippets/ui-accessibility.md).
+   - **Accessibility:** keyboard reachable, labels present, focus visible. Follow [UI accessibility](../../../../.claude/rules-snippets/ui-accessibility.md).
    - **Mobile:** the flow works at a narrow viewport.
 4. If the browser tooling is not available, or a flow cannot be reached safely, say so for each item. Do not guess what the page looks like.
 
 ## Output
 
-You write exactly one file: `<job folder>/round-<N>/review-ux.md`. Use this skeleton:
+You do not write files. Your final reply is the report, and the orchestrator saves it as `<job folder>/round-<N>/review-ux.md`, so start the reply with the verdict line. Use this skeleton:
 
 ```markdown
 VERDICT: PASS
@@ -61,4 +61,4 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `CHANGES` needs at least one blocking item that is specific and actionable.
 - If something the spec requires was **not verified**, the verdict is `CHANGES` with a blocking item titled `Not verified: <what>`. Do not give a PASS you did not earn. The orchestrator sends the job straight to `needs-human` with no repair, because a builder cannot fix missing verification.
 - Taste goes under non-blocking notes.
-- Do not edit code or any file other than your review.
+- Do not edit code or any file.

package/src/monorepo/{.claude/agents-snippets/factory-spec-writer.md → .agents/skills/factory/roles/spec.md}

@@ -1,6 +1,6 @@
 # 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**.
+You turn a feature request into a testable spec, and then into a plan. You are one agent in the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you. The task line names your mode: **spec** or **plan**.
 
 ## Inputs
 
@@ -10,7 +10,7 @@ Read these, in this order:
 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. The `AGENTS.md` of each affected app or package, for its patterns and commands.
-5. [Feature spec template](../../templates/feature-spec.template.md) for the section structure.
+5. [Feature spec template](../../../../templates/feature-spec.template.md) for the section structure.
 6. 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.
 7. `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.
 

package/src/monorepo/.claude/agents/implementer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: implementer
 description: "Implement code changes for a specific task. Follow TDD, write tests alongside code, and self-review before reporting completion."
-tools: ["Read", "Grep", "Write", "Edit", "Bash(*)"]
+tools: ["Read", "Grep", "Glob", "Write", "Edit", "Bash(*)"]
 user-invocable: false
 ---
 

package/src/monorepo/.claude/agents/planner.agent.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: "Break down feature requests into implementation tasks. Read specifications, analyze codebase patterns, and produce structured plans with dependencies."
-tools: ["Read", "Grep", "Write", "Bash(*)"]
+tools: ["Read", "Grep", "Glob", "Write", "Bash(*)"]
 user-invocable: false
 ---
 

package/src/monorepo/.claude/agents/reviewer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: "Review code changes for correctness, code quality, security, and adherence to project patterns. Provide actionable feedback with specific file and line references. Use immediately after writing or modifying code, or as a quality gate in orchestrated workflows."
-tools: ["Read", "Grep", "Bash(*)"]
+tools: ["Read", "Grep", "Glob", "Bash(*)"]
 ---
 
 # Reviewer Agent

package/src/monorepo/.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/monorepo/.claude/commands/factory.md

@@ -1,5 +1,5 @@
 ---
-description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+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]"
 ---
@@ -11,14 +11,14 @@ argument-hint: "[--in-place] <feature request> | start [--in-place] <request | K
 
 | 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` |
+| `planner` | Spec writer. Spec stage (`spec` mode) writes `spec.md`; plan stage (`plan` mode) writes `plan.md` and `tasks.md`. Brief: `.agents/skills/factory/roles/spec.md` |
+| `implementer` | Builder. Build, repair, and rework: writes `build.md` in the job folder; its code goes in the build location. Brief: `.agents/skills/factory/roles/build.md` |
+| `reviewer` | Code reviewer. Review round, `code` lens. Brief: `.agents/skills/factory/roles/review-code.md` |
+| `reviewer` | Security reviewer, fresh context. Review round, `security` lens. Brief: `.agents/skills/factory/roles/review-security.md` |
+| `reviewer` | UX reviewer. Review round, `ux` lens (opt-in). Brief: `.agents/skills/factory/roles/review-ux.md` |
+| `reviewer` | UI reviewer. Review round, `ui` lens (opt-in). Brief: `.agents/skills/factory/roles/review-ui.md` |
+| `reviewer` | Approver, fresh context. Approval gate: returns the decision, which the orchestrator saves as `decision.md`. Brief: `.agents/skills/factory/roles/approve.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.
+Dispatch each native agent by the name in the first column, and tell it to read the brief in the last column first. Reviewers and the approver return their report, and the orchestrator saves it. 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/monorepo/.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/monorepo/.claude/prompt-snippets/assign-tasks.md

@@ -48,11 +48,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)
-   - For `tasks.md`: each `- [ ]` line is one task. The text after the ID is the summary. A trailing ` — <KEY>` means a ticket already exists, so skip that line. Sub-bullets, if any, are subtasks
+   - 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 & Classify** (do this BEFORE creating tickets):
-   - **A `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 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
@@ -77,10 +83,12 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - 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
-   - Write each ticket key back to its `tasks.md` line after the em dash (`- [ ] T1 Schema + migration — PROJ-124`)
+   - **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
    - **Show consolidation summary**: "Merged X items into Y tickets"
@@ -149,6 +157,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/monorepo/.claude/prompt-snippets/bootstrap-patch.md

@@ -1,10 +1,10 @@
-You are helping to patch AI instructions by comparing against supported toolkit v4.x templates from the ai-assisted-dev-toolkit repository's `v4.x` branch and merging updates into this project.
+You are helping to patch AI instructions by comparing against 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 merging updates 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.
 
@@ -23,6 +23,8 @@ You are helping to patch AI instructions by comparing against supported toolkit
 /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 root/nested `AGENTS.md`, `.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.
@@ -31,33 +33,38 @@ You are helping to patch AI instructions by comparing against supported toolkit
 
 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
@@ -98,11 +105,11 @@ You are helping to patch AI instructions by comparing against supported toolkit
 
     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; neither it nor a V1 API fetch validates native V2. Plural keys are intentional.
 
-    - 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`.
+    - Use `agents`/`system`, 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 root/nested `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 workspace 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 root/nested `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. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`; use workspace 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):
 
@@ -174,8 +181,8 @@ You are helping to patch AI instructions by comparing against supported toolkit
       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/monorepo/.claude/prompt-snippets/bootstrap-upgrade.md

@@ -1,12 +1,12 @@
 # Bootstrap Upgrade — Monorepo
 
-Upgrade this monorepo 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. Only modify confirmed harness targets; preserve unrelated harness/Codex behavior.
+Upgrade this monorepo 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. 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.
 
 ## Orchestrator Checkpoint
 
@@ -71,7 +71,7 @@ Back up V1; native-converted files are incompatible with V1. Preserve models/pro
 5. **Present summary and ask for confirmation**:
 
    ```markdown
-    ## 🔄 Monorepo Upgrade: toolkit v4.0.0
+    ## 🔄 Monorepo Upgrade: toolkit <version>
 
     **Selected route**: verified legacy | v3 native OpenCode
 
@@ -81,7 +81,7 @@ Back up V1; native-converted files are incompatible with V1. Preserve models/pro
     - Confirmed OpenCode only: merge native V2 host files and approved missing wrappers (Step 7)
     - Verified legacy only: approved hook installation and verified identical duplicate skill cleanup (Steps 8–10); preserve custom skills
     - Merge only applicable missing documentation and validate the selected route; v3 keeps existing snippet bodies/frontmatter unchanged
-   - Write `.toolkit-version` with `4.0.0` after the approved migration
+   - Keep the `.toolkit-version` the CLI writes (installed package version, 4.0.0 or later) after the approved migration
 
    ### Monorepo-specific changes
 
@@ -264,18 +264,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`.
+   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), 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 root/nested `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 workspace 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 root/nested `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. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`; use workspace 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 `.opencode/commands/*.md` — one thin wrapper per `.claude/commands/*.md`:
 
@@ -379,7 +378,7 @@ If `CLAUDE.md` is an applicable confirmed harness target, merge only missing rel
 
 ### Step 12: Create .toolkit-version File
 
-Write `4.0.0` to `.toolkit-version` only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
+Keep the `.toolkit-version` value the CLI writes (the installed package version, 4.0.0 or later); do not write `4.0.0` by hand. Only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope). If the file is missing, run `npx nitm-ai-dev-toolkit patch` to record it.
 
 ### Step 13: Validation
 
@@ -399,7 +398,7 @@ If `--verbose`: log each check result.
 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
-## ✅ Monorepo Upgrade Complete: v4.0.0
+## ✅ Monorepo Upgrade Complete: toolkit <version>
 
 ### Build System: {{BUILD_SYSTEM}}
 
@@ -435,7 +434,7 @@ Include only operations/checks actually performed for the selected route; omit l
 | File                       | Purpose                    |
 | -------------------------- | -------------------------- |
 | `.opencode/opencode.jsonc` | OpenCode configuration     |
-| `.toolkit-version`         | Version tracking (`4.0.0`) |
+| `.toolkit-version`         | Version tracking (installed package version) |
 
 ### Validation Results
 
@@ -464,7 +463,7 @@ Include only operations/checks actually performed for the selected route; omit l
 
 ```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>"
 ```
 
 ## Error Handling

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

@@ -5,8 +5,8 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 ## 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.
 
@@ -68,9 +68,9 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
    | `{{PM_URL}}`                | Project management URL (if applicable)                                                                                                          |
    | `{{PROJECT_KEY}}`           | Project/workspace ID (if applicable)                                                                                                            |
    | `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###, #42)                                                                                                          |
-   | `{{FACTORY_PORT_BASE}}`     | Default `5100`                                                                                                                                  |
-   | `{{APPROVAL_MODE}}`         | Default `human`                                                                                                                                 |
-   | `{{FACTORY_REVIEW_LENSES}}` | 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)         |
+   | `{{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)         |
 
 3. **Analyze Apps**:
 
@@ -178,25 +178,25 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 
    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, not V1 API/schema fetches. The published schema may describe V1; do not reject native plural keys based on it.
 
-   - After the version preflight passes, 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`.
+   - After the version preflight passes, use `agents`/JSON `system` (Markdown bodies for file agents), 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`.
    - Back up V1; native-converted files are incompatible with V1. Merge rather than clobber models/providers/user-global plugins. Only with approval, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema retains `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter.
-   - 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 not loaded; ambient root/nested `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 workspace 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; report only checks actually run with 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 root/nested `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 snippets. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`; use workspace 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; report only checks actually run with 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/monorepo/.claude/prompt-snippets/factory.md

@@ -1,5 +1,5 @@
 ---
-description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+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
@@ -8,13 +8,13 @@ Follow the [factory orchestrator skill](../../.agents/skills/factory/SKILL.md) e
 
 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`, 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.
+- Run the orchestrator in this session. Dispatch the native agents (`planner`, `implementer`, `reviewer`, see the skill's Subagent dispatch) for every spec, plan, build, review, and approval step, and do not write their files yourself. Reviewers and the approver return their reports, which you save.
+- Only write `job.json`, `intake.md`, `spec-<k>.md`, `plan-<k>.md`, `rework-<k>.md`, the review files and `decision.md` from the reviewer and approver replies, 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.
-- Never push. Merges stay local.
+- 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 `docs/features/`.
+- `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/monorepo/.claude/prompt-snippets/implement-feature.md

@@ -79,7 +79,9 @@ Implement a feature by completing tasks sequentially with proper tracking.
    git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"
    ```
 
-   f. **Mark Task Complete**: tick `- [x]` for the task in `tasks.md`
+   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