nitm-ai-dev-toolkit 5.1.1 → 5.1.3

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

@@ -20,6 +20,28 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 - Codex MCP uses native `[mcp_servers.name]` TOML, not `.mcp.json`. Treat other harness MCP templates as references only; do not activate servers, copy credentials, or install hooks automatically.
 - Update and audit only confirmed harness targets. For Codex-only setup, the native targets are root/nested `AGENTS.md`, `.agents/skills/`, and `.codex/config.toml`. `--env codex` also includes `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources, not automatically loaded rules or evidence of Copilot/Claude use; other harness command, agent, and config directories are excluded. Tool-specific steps below are conditional.
 
+## Thin Wrapper Policy
+
+Canonical policy lives only in `.claude/rules-snippets/`, `.claude/prompt-snippets/`, and `.claude/agents-snippets/`. Every harness wrapper (`.claude/{rules,commands,agents}/`, `.cursor/{rules,commands,agents}/`, `.github/{instructions,prompts,agents}/`, `.opencode/{rules,commands,agents}/`, and Codex and Copilot entry files) is a thin link to its snippet: frontmatter, a title, the link line, at most five key points, and optionally one short summary line. Its agent-dispatch table is activation metadata and may stay.
+
+- **Create or change policy in the snippet first, then the wrapper.** Never write a wrapper with a copy of the policy, and never let a wrapper diverge from its snippet.
+- **Skills that restate a snippet's policy point to the snippet** (or, where the skill is the source, the snippet points to the skill). Keep one source of policy text.
+- **Existing wrappers that inline policy or diverge from their snippet** are reported (`npx nitm-ai-dev-toolkit doctor` lists them). Propose moving the content into the snippet and reducing the wrapper to a link. Change nothing without the operator's approval.
+
+## Relevance and Retirement
+
+The template ships files for every stack, tracker and test tool. Decide what applies to this monorepo and each app; do not copy the whole template.
+
+- **Relevance comes from the project:** the tracker (git origin host, or `"trackers"` in `.nitm/retired.json`), Playwright, Prisma, the UI framework (read from the root and `apps/*`, `packages/*` package manifests), and whether MCP servers are configured. `npx nitm-ai-dev-toolkit patch --dry-run` prints each template file's classification with its reason (add, update, needs review, not relevant, retired). Use that plan; do not copy template files by hand.
+- **Retire what does not apply** by recording it in `.nitm/retired.json` after the operator agrees, with a reason and date:
+
+  ```json
+  { "retired": [{ "path": ".agents/skills/linear-cli", "reason": "GitHub Issues is the tracker", "date": "2026-10-27" }] }
+  ```
+
+  A directory path retires every file under it. Patch and upgrade never re-add retired paths, and doctor reports them as retired, not missing. Never delete files to retire them.
+- **Override tracker detection** with `"trackers": ["github"]` (or `[]` for none) when the git origin does not name the tracker.
+
 ## Your Task
 
 1. **Analyze the Monorepo**:
@@ -333,11 +355,16 @@ Present the replacements and confirm before applying.
 
 10. **Recommend and Install AI Agent Skills**:
 
-Based on detected ecosystem and frameworks, recommend relevant skills from [skills.sh](https://skills.sh/) and [agentskills.io](https://agentskills.io/).
+Recommend skills from [skills.sh](https://skills.sh/) and [agentskills.io](https://agentskills.io/) only for needs this monorepo or app has: its tracker, framework, language, and test tooling. Never install a whole repository with `--skill '*'`. The toolkit already ships the core workflow skills (TDD, debugging, planning, review) in `.agents/skills/`, so do not recommend them again.
+
+**Rules for every recommendation:**
+- One named skill per install (`--skill <name>`). Confirm the name exists in its source repository first. If you cannot confirm it, leave that install out and say so.
+- List the detected need next to each skill. Recommend nothing without a need.
+- Install nothing before the operator approves that skill. Approving one skill does not approve the others.
 
 **Important:** Use the detected agent flags from step 9 in all `npx skills add` commands. This prevents creating unnecessary configurations for agents the user doesn't have installed.
 
-**Core Skills (Always Recommend):**
+**Generic workflow skills (optional; the toolkit already ships equivalents):**
 
 | Skill Repository           | Purpose                                            |
 | -------------------------- | -------------------------------------------------- |
@@ -348,8 +375,7 @@ Based on detected ecosystem and frameworks, recommend relevant skills from [skil
 **Example commands** (replace `{{AGENT_FLAGS}}` with confirmed harness flags from step 9, e.g., `-a codex`):
 
 ```bash
-npx -y skills add {{AGENT_FLAGS}} obra/superpowers --skill '*'
-npx -y skills add {{AGENT_FLAGS}} trailofbits/skills --skill '*'
+npx -y skills add {{AGENT_FLAGS}} <owner/repo> --skill <confirmed name>   # one line per approved skill
 ```
 
 **Issue Tracker Skills Health Check (if {{ISSUE_TRACKER}} is configured):**
@@ -373,10 +399,10 @@ This template bundles issue tracker skills in `.agents/skills/`. Verify the corr
     - Configured tracker: Linear
     - Found skill: acli (not matching)
     - Expected skill: linear-cli
-    Remove acli and keep linear-cli? (Y/n)
+    Retire acli and keep linear-cli? (Y/n)
     ```
-4.  **Prune unused CLI skills:** On confirmation, delete the mismatched skill directory and update AGENTS.md Skills table
-5.  **If missing:** Warn that the expected CLI skill is not present and offer to copy it from the template bundle
+4.  **Retire mismatched CLI skills:** On confirmation, record each in `.nitm/retired.json` (reason and date) and update the AGENTS.md Skills table. Delete a directory only with separate approval and a backup
+5.  **If missing:** Warn that the expected CLI skill is not present; add it only when `patch --dry-run` shows it applies and the operator approves
 
 **Framework-Specific Skills:**
 
@@ -411,13 +437,13 @@ When recommending framework-specific skills, include the detected agent flags. E
 | React              | `vercel-labs/agent-skills`            | `npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill "vercel-react-best-practices"` |
 | Vue                | `onmax/nuxt-skills` (vue)             | `npx -y skills add {{AGENT_FLAGS}} onmax/nuxt-skills --skill "vue"` |
 | Nuxt               | `onmax/nuxt-skills` (nuxt)            | `npx -y skills add {{AGENT_FLAGS}} onmax/nuxt-skills --skill "nuxt"` |
-| Expo               | `expo/skills`                         | `npx -y skills add {{AGENT_FLAGS}} expo/skills --skill '*'` |
-| TypeScript         | `pproenca/dot-skills` (typescript)    | `npx -y skills add {{AGENT_FLAGS}} pproenca/dot-skills --skill '*'` |
-| Advanced Types     | `wshobson/agents` (ts-advanced-types) | `npx -y skills add {{AGENT_FLAGS}} wshobson/agents --skill '*'` |
+| Expo               | `expo/skills`                         | `npx -y skills add {{AGENT_FLAGS}} expo/skills --skill <name confirmed in the repository>` |
+| TypeScript         | `pproenca/dot-skills` (typescript)    | `npx -y skills add {{AGENT_FLAGS}} pproenca/dot-skills --skill "typescript"` |
+| Advanced Types     | `wshobson/agents` (ts-advanced-types) | `npx -y skills add {{AGENT_FLAGS}} wshobson/agents --skill "ts-advanced-types"` |
 
 **Skill Creation for Unsupported Frameworks:**
 
-Use `npx -y skills add {{AGENT_FLAGS}} anthropics/skills --skill '*'` (includes `skill-creator`) to create custom skills.
+To create a custom skill for an unsupported framework, install only `skill-creator` from `anthropics/skills`: `npx -y skills add {{AGENT_FLAGS}} anthropics/skills --skill "skill-creator"`.
 
 **Monorepo-Specific Considerations:**
 
@@ -438,28 +464,26 @@ Using flags: {{AGENT_FLAGS}}
 
 Based on your monorepo ({{BUILD_SYSTEM}}/{{LANGUAGE}}):
 
-Core Skills (recommended for all projects):
-npx -y skills add {{AGENT_FLAGS}} obra/superpowers --skill '*'
-npx -y skills add {{AGENT_FLAGS}} trailofbits/skills --skill '*'
-npx -y skills add {{AGENT_FLAGS}} softaworks/agent-toolkit --skill '*'
+Approved installs (none until the operator approves each one):
+npx -y skills add {{AGENT_FLAGS}} <owner/repo> --skill <confirmed name>   # one line per approved skill
 
 Issue Tracker Skills (bundled — {{ISSUE_TRACKER}}):
 ✅ .agents/skills/issue-tracker/SKILL.md (shared strategy)
 ✅ Matching CLI reference: .agents/skills/acli/SKILL.md, .agents/skills/gh-cli/SKILL.md, or .agents/skills/linear-cli/SKILL.md
-⚠️ Prune any issue-tracker CLI skills that do not match {{ISSUE_TRACKER}} (if any)
+⚠️ Retire any issue-tracker CLI skills that do not match {{ISSUE_TRACKER}} (if any; record them in .nitm/retired.json)
 
-Framework-Specific Skills:
-- web (Next.js): npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill '*'
-- api (Hono): npx -y skills add {{AGENT_FLAGS}} elysiajs/skills --skill '*'
+Framework-Specific Skills (one named skill each, after confirming its name):
+- web (Next.js): npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill <confirmed name>
+- api (Hono): npx -y skills add {{AGENT_FLAGS}} elysiajs/skills --skill <confirmed name>
 
-Install All? (Y/n)
+Approve each skill by name (or none). Nothing is installed without approval.
 ```
 
 **Example with detected agents:**
 
 - If Cursor and Copilot are confirmed: `AGENT_FLAGS="-a cursor -a github-copilot"`
 - If only Codex is confirmed: `AGENT_FLAGS="-a codex"`
-- Codex-only command: `npx -y skills add -a codex obra/superpowers --skill '*'`
+- Codex-only command: `npx -y skills add -a codex <owner/repo> --skill <confirmed name>`
 
 **On Confirmation:**
 
@@ -530,11 +554,12 @@ Next Steps:
    | django-expert | Django patterns | No Django apps detected |
    | php | PHP patterns | JavaScript/TypeScript monorepo |
 
-   Remove flagged skills? (Y/n)
+   Retire flagged skills? (Y/n)
    ```
 
    **On Confirmation:**
-   - Remove unnecessary skill directories
+   - Record each approved skill in `.nitm/retired.json` (reason and date) so `patch` leaves it out; this removes nothing from the template
+   - Delete a skill directory only with separate approval and a backup
    - Update root AGENTS.md to remove references
    - Report cleanup results
 
@@ -566,8 +591,8 @@ Next Steps:
     ```
 
     **On Confirmation (only if Copilot is confirmed in use):**
-    - Generate missing Copilot instruction files with appropriate templates; skip creation for a Codex-only audit even when shared reference standards are present
-    - Include app-specific scoping (applyTo paths)
+    - Write the policy of each missing Copilot instruction into `.claude/rules-snippets/<name>.md` first, then create `.github/instructions/<name>.instructions.md` as a thin wrapper (frontmatter with `applyTo`, a title, a link to the snippet, at most five key points); skip creation for a Codex-only audit even when shared reference standards are present
+    - Include app-specific scoping (applyTo paths) in the wrapper frontmatter only
     - Include framework-specific patterns from skills
     - Report created files
 

package/src/monorepo/.claude/skills/README.md

@@ -1,6 +1,6 @@
 # Claude Code Skills
 
-This folder is for skills installed via `npx -y skills add -a claude-code <owner/repo> --skill '*'`.
+This folder is for skills installed via `npx -y skills add -a claude-code <owner/repo> --skill <confirmed name>`.
 
 ## About Skills
 
@@ -12,10 +12,10 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a claude-code` f
 
 ```bash
 # For Claude Code only
-npx -y skills add -a claude-code <owner/repo> --skill '*'
+npx -y skills add -a claude-code <owner/repo> --skill <confirmed name>
 
 # For multiple agents (e.g., Claude Code + GitHub Copilot)
-npx -y skills add -a claude-code -a github-copilot <owner/repo> --skill '*'
+npx -y skills add -a claude-code -a github-copilot <owner/repo> --skill <confirmed name>
 ```
 
 **Tip:** The skills CLI automatically detects installed agents. If you omit `-a claude-code`, you'll be prompted to choose from detected agents.
@@ -37,14 +37,14 @@ Universal workflow skills are pre-installed in `.agents/skills/`. These include:
 
 ```bash
 # Frontend skills
-npx -y skills add -a claude-code onmax/nuxt-skills --skill '*'
-npx -y skills add -a claude-code vercel-labs/agent-skills --skill '*'
+npx -y skills add -a claude-code onmax/nuxt-skills --skill vue
+npx -y skills add -a claude-code vercel-labs/agent-skills --skill vercel-react-best-practices
 
 # Security skills
-npx -y skills add -a claude-code trailofbits/skills --skill '*'
+npx -y skills add -a claude-code trailofbits/skills --skill <confirmed name>
 
 # Framework-specific
-npx -y skills add -a claude-code better-auth/skills --skill '*'
+npx -y skills add -a claude-code better-auth/skills --skill <confirmed name>
 ```
 
 See the main README.md for a full list of recommended skills.

package/src/monorepo/.cursor/skills/README.md

@@ -1,6 +1,6 @@
 # Cursor Skills
 
-This folder is for skills installed via `npx -y skills add <owner/repo> --skill '*' --agent github-copilot cursor`.
+This folder is for skills installed via `npx -y skills add <owner/repo> --skill <confirmed name> --agent github-copilot cursor`.
 
 ## About Skills
 
@@ -12,13 +12,13 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a cursor` flag:
 
 ```bash
 # For Cursor only
-npx -y skills add -a cursor <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 
 # For multiple agents (e.g., Cursor + GitHub Copilot)
-npx -y skills add -a cursor -a github-copilot <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor -a github-copilot <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 ```
 
-**Tip:** The skills CLI automatically detects installed agents. If you omit `-a cursor`, you'll be prompted to choose from detected agents. Use `--skill '*' --agent github-copilot cursor` to avoid skill-selection prompts when installing from a repo.
+**Tip:** The skills CLI automatically detects installed agents. If you omit `-a cursor`, you'll be prompted to choose from detected agents. Use `--skill <confirmed name> --agent github-copilot cursor` when installing one named skill from a repo.
 
 **Important:** Always use `-a cursor` to install only for Cursor (or add multiple `-a` flags if you use multiple agents). This prevents creating unnecessary configuration files for other agents.
 
@@ -37,14 +37,14 @@ Universal workflow skills are pre-installed in `.agents/skills/`. These include:
 
 ```bash
 # Frontend skills
-npx -y skills add -a cursor onmax/nuxt-skills --skill '*' --agent github-copilot cursor
-npx -y skills add -a cursor vercel-labs/agent-skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor onmax/nuxt-skills --skill vue --agent github-copilot cursor
+npx -y skills add -a cursor vercel-labs/agent-skills --skill vercel-react-best-practices --agent github-copilot cursor
 
 # Security skills
-npx -y skills add -a cursor trailofbits/skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor trailofbits/skills --skill <confirmed name> --agent github-copilot cursor
 
 # Framework-specific
-npx -y skills add -a cursor better-auth/skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor better-auth/skills --skill <confirmed name> --agent github-copilot cursor
 ```
 
 See the main README.md for a full list of recommended skills.

package/src/monorepo/.github/skills/README.md

@@ -1,6 +1,6 @@
 # GitHub Copilot Skills
 
-This folder is for skills installed via `npx -y skills add <owner/repo> --skill '*' --agent github-copilot cursor` when using GitHub Copilot.
+This folder is for skills installed via `npx -y skills add <owner/repo> --skill <confirmed name> --agent github-copilot cursor` when using GitHub Copilot.
 
 ## About Skills
 
@@ -12,13 +12,13 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a github-copilot
 
 ```bash
 # For GitHub Copilot only
-npx -y skills add -a github-copilot <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a github-copilot <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 
 # For multiple agents (e.g., Copilot + Cursor)
-npx -y skills add -a github-copilot -a cursor <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a github-copilot -a cursor <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 ```
 
-**Tip:** The skills CLI automatically detects installed agents. If you omit `-a github-copilot`, you'll be prompted to choose from detected agents. Use `--skill '*' --agent github-copilot cursor` to avoid skill-selection prompts when installing from a repo.
+**Tip:** The skills CLI automatically detects installed agents. If you omit `-a github-copilot`, you'll be prompted to choose from detected agents. Use `--skill <confirmed name> --agent github-copilot cursor` when installing one named skill from a repo.
 
 **Important:** Always use `-a github-copilot` to install only for GitHub Copilot (or add multiple `-a` flags if you use multiple agents). This prevents creating unnecessary configuration files for other agents.
 

package/src/monorepo/.opencode/commands/review-staged.md

@@ -9,3 +9,7 @@ description: "Review currently staged files before committing"
 |-------|-------------|
 | `reviewer` | Standard pre-commit review — correctness, style, patterns |
 | `oracle` | Complex staged change — trade-offs, security, scalability |
+
+Read and follow `.claude/prompt-snippets/review-staged.md` before executing this command.
+
+$ARGUMENTS

package/src/monorepo/factory/README.md

@@ -99,6 +99,8 @@ Any value other than exactly `auto` is treated as `human`.
 
 By default each job builds in its own git worktree on branch `factory/<id>`, so the main checkout stays free. A job's `job.json` records this in `worktree` (`true`) and the worktree path in `worktree_path`. Worktrees live in `.worktrees/<id>/` at the git root; the factory adds `.worktrees/` to `.gitignore` if it is missing.
 
+Tools that do not honor `.gitignore` (Jest/Vitest test discovery, ESLint, `tsc`, workspace globs) should exclude `.worktrees/`. The local merge runs tests in the main checkout while other job worktrees may still exist.
+
 ### Worktree bootstrap
 
 Before the builder starts in a new worktree, the factory runs the steps listed in `factory/worktree-bootstrap.md`: one shell command per line, in order, from the worktree root. Typical steps install dependencies or vendored packages, copy `.env` from the main checkout, and create or migrate a database for the job. The file ships with no active steps, so edit it for your project. Each step receives `FACTORY_JOB_ID`, `FACTORY_PORT_BUILDER`, `FACTORY_WORKTREE`, and `FACTORY_MAIN_CHECKOUT`.

package/src/repo/.agents/skills/factory/SKILL.md

@@ -294,7 +294,8 @@ If a ticket cannot be created, stop at `awaiting-plan`. Report the lines that ha
 The default build location. Follow the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill. Factory always takes its project-local `.worktrees/` default and never the global `~/.worktrees` option, without asking.
 
 - Branch `factory/<id>` from `{{DEFAULT_BRANCH}}`.
-- Path `.worktrees/<id>/` at the root of the main checkout (inside the repo folder). Record its absolute path in `worktree_path`.
+- Path `.worktrees/<id>/` at the root of the main checkout (inside the repo folder). The folder is named by the job id, never by the branch: branch `factory/<id>` must not produce `.worktrees/factory/<id>`. Record its absolute path in `worktree_path`.
+- `factory/worktree-bootstrap.md` replaces the worktree skill's project-setup and baseline-test steps. Factory does not run those.
 - Before the first worktree, run that skill's `.gitignore` check. If it had to add `.worktrees/`, commit that on `{{DEFAULT_BRANCH}}` or tell the operator to.
 - Create it at the start of the build stage, after the plan gate and tracking. Reuse it if it exists (rework and repair).
 - Copy the job's `spec.md`, `plan.md`, and `tasks.md` (if any) from the main checkout's feature folder into the same relative path in the worktree. The builder ticks `tasks.md` there. Then run the bootstrap (next subsection) and make the feature docs commit.

package/src/repo/.agents/skills/using-git-worktrees/SKILL.md

@@ -37,11 +37,10 @@ Follow this priority order:
 
 ```bash
 # Check in priority order
-ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-ls -d worktrees 2>/dev/null      # Alternative
+ls -d .worktrees 2>/dev/null
 ```
 
-**If found:** Use that directory. If both exist, `.worktrees` wins.
+**If found:** Use that directory.
 
 ### 2. Check Project Configuration
 
@@ -67,21 +66,21 @@ Which would you prefer?
 
 ## Safety Verification
 
-### For Project-Local Directories (.worktrees or worktrees)
+### For Project-Local Directories (.worktrees)
 
 **MUST verify directory is ignored before creating worktree:**
 
 ```bash
 # Check if directory is ignored (respects local, global, and system gitignore)
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+git check-ignore -q .worktrees 2>/dev/null
 ```
 
 **If NOT ignored:**
 
 Fix immediately before proceeding:
 
-1. Add appropriate line to .gitignore
-2. Commit the change
+1. Add `.worktrees/` to .gitignore
+2. Commit the change on the default branch
 3. Proceed with worktree creation
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.
@@ -103,11 +102,11 @@ project=$(basename "$(git rev-parse --show-toplevel)")
 ```bash
 # Determine full path
 case $LOCATION in
-  .worktrees|worktrees)
+  .worktrees)
     path="$LOCATION/$BRANCH_NAME"
     ;;
   ~/.worktrees/*)
-    path="~/.worktrees/$project/$BRANCH_NAME"
+    path="$HOME/.worktrees/$project/$BRANCH_NAME"
     ;;
 esac
 
@@ -164,8 +163,6 @@ Ready to implement <feature-name>
 | Situation                  | Action                          |
 | -------------------------- | ------------------------------- |
 | `.worktrees/` exists       | Use it (verify ignored)         |
-| `worktrees/` exists        | Use it (verify ignored)         |
-| Both exist                 | Use `.worktrees/`               |
 | Neither exists             | Check project config → Ask user |
 | Directory not ignored      | Add to .gitignore + commit      |
 | Tests fail during baseline | Report failures + ask           |

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

@@ -117,11 +117,13 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     For each category, compare template files against project files:
 
-    a. **Classify each file**:
-    - **🆕 New**: Exists in template but not in project → candidate for addition
-    - **📝 Updated**: Exists in both but template has newer content → candidate for merge
-    - **✅ Current**: Exists in both and content matches → no action needed
-    - **🔧 Customized**: Exists in both, project version has non-placeholder customizations → careful merge
+    a. **Classify each file** (relevance-aware; never a wholesale copy). `npx nitm-ai-dev-toolkit patch --dry-run` makes this classification and prints each reason. Read that plan before deciding anything, and see Relevance and Retirement in `bootstrap.md`:
+    - **add**: missing, and it applies to this project (tracker, Playwright, Prisma, UI, and MCP relevance)
+    - **update**: the toolkit wrote it and the project has not changed it since; the new template replaces it
+    - **current**: identical to the template; no action
+    - **needs review**: differs from the template (locally changed), or missing while relevance is undecided; never overwritten, and never added without a decision
+    - **not relevant**: does not apply to this project; never added. A present copy is a retirement candidate
+    - **retired**: listed in `.nitm/retired.json`; never added, updated or overwritten
     - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is except the approved obsolete toolkit Ponytail removal above
 
     b. **For updated files, generate a structured diff**:
@@ -132,7 +134,7 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     c. **Smart Merge Rules**:
     - **Never overwrite** project-specific values that replaced `{{PLACEHOLDER}}`
-    - **Always add** new files that don't exist in the project
+    - **Add only** files classified *add*. Never add a not-relevant or retired file, and never add a file whose relevance is undecided without the operator's decision
     - **Merge structural additions** into existing customized files
     - **Flag for review** any removals from files that have been customized
     - **Preserve custom agents/skills** that were added by the project
@@ -146,13 +148,13 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
     **Project Type**: repo | monorepo
     **Categories Scanned**: [list]
 
-    ### 🆕 New Files (X files)
+    ### 🆕 Add (X files; apply to this project)
 
     | File                         | Category | Description              |
     | ---------------------------- | -------- | ------------------------ |
     | `.cursor/rules/new-rule.mdc` | Rules    | New coding standard rule |
 
-    ### 📝 Updated Files (X files)
+    ### 📝 Update (X files; unchanged since the toolkit wrote them)
 
     | File                            | Changes                       | Risk           |
     | ------------------------------- | ----------------------------- | -------------- |
@@ -162,16 +164,30 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     [No action needed]
 
-    ### 🔧 Customized Files Requiring Review (X files)
+    ### 🔧 Needs Review (X files; locally changed or undecided; not written)
 
     | File        | Template Changes  | Project Customizations       | Merge Strategy |
     | ----------- | ----------------- | ---------------------------- | -------------- |
     | `AGENTS.md` | New section added | Has project-specific content | Manual merge   |
 
+    ### 🚫 Not Relevant or Retired (X files; not written)
+
+    | File                                   | Reason                              | Action                              |
+    | -------------------------------------- | ----------------------------------- | ----------------------------------- |
+    | `.claude/commands/playwright-test.md`  | No Playwright setup detected        | Keep out; retire if present (approval) |
+    | `.agents/skills/linear-cli/SKILL.md`   | Project tracker is GitHub           | Retire in `.nitm/retired.json`      |
+
+    ### 🩹 Harness Wrappers to Review (X files; proposals only)
+
+    | Wrapper                     | Finding                              | Proposal                                  |
+    | --------------------------- | ------------------------------------ | ----------------------------------------- |
+    | `.claude/rules/api-server.md` | Policy text outside the snippet link | Move the text into its snippet; keep a thin link |
+
     ### Summary
 
-    - **Auto-apply**: X new files + Y updated files with no conflicts
-    - **Review needed**: Z customized files with structural changes
+    - **Auto-apply**: X add + Y update entries, as printed by `patch`
+    - **Review needed**: Z needs-review files and W wrapper proposals
+    - **Not written**: N not-relevant or retired entries
     - **No action**: W files already current
     ```
 
@@ -179,9 +195,9 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
     - If `--dry-run` flag: Output the report without making changes
     - Otherwise: Present the report and ask the user to confirm with (Y/n)
     - On confirmation:
-      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
+      a. **Add and update**: run `npx nitm-ai-dev-toolkit patch`. It writes only the add and update entries it printed; do not copy template files by hand
+      b. **Retirements**: after approval, record each path in `.nitm/retired.json` with a reason and date. Do not delete files to retire them
+      c. **Needs review**: propose a merge per file (structural additions, preserved project values) and apply it only after the operator approves that file. Wrappers that inline policy: propose moving the content into the snippet and reducing the wrapper to a thin link (see Thin Wrapper Policy in `bootstrap.md`)
       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:

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

@@ -104,7 +104,7 @@ For each file: read → extract body after frontmatter → write to snippet dest
 
 **Parallelizable**: Process rules, commands, and agents independently.
 
-Replace each file's body with a wrapper that preserves frontmatter and references the snippet:
+Replace each file's body with a thin wrapper (see Thin Wrapper Policy in `bootstrap.md`) that preserves frontmatter and references the snippet. Move any policy text into the snippet first; the wrapper keeps only the link, a title and at most five key points:
 
 | File Type                   | Frontmatter to Keep                             | Reference Line                                                                                 |
 | --------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
@@ -188,7 +188,7 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
    - 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.
    - 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:
+3. **Create wrappers with explicit snippet-read instructions** — only for entries the patch plan classifies *add* (never retired or not-relevant snippets), each one thin (see Thin Wrapper Policy in `bootstrap.md`), one file per snippet:
 
    | Directory                 | Source Snippets            | Wrapper Body                         |
    | ------------------------- | -------------------------- | ------------------------------------ |
@@ -210,12 +210,13 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
 
 ### 8. Install Pre-Commit Hook
 
-Install the CHANGELOG/secrets enforcement hook to run before every commit:
+Install the CHANGELOG/secrets enforcement hook before every commit, only with the operator's approval, only in a git repository, and never over an existing `.git/hooks/pre-commit`. If one exists, show the difference and propose chaining or merging instead:
 
 1. Copy `scripts/pre-commit-check.sh` from the template to the target project's `scripts/` directory
 2. Install as a git hook:
 
    ```bash
+   # only when .git/hooks/pre-commit does not exist yet
    cp scripts/pre-commit-check.sh .git/hooks/pre-commit
    chmod +x .git/hooks/pre-commit
    ```
@@ -228,10 +229,12 @@ This enforces:
 
 Use `git commit --no-verify` to bypass.
 
-### 9. Install Project Hooks
+### 9. Install Project Hooks (only with approval)
 
-1. Create `hooks/` directory in the target project
-2. Copy all files from the template's `hooks/*` directory (preserve sub-structure)
+The `hooks/` files are Claude Code plugin hooks (`${CLAUDE_PLUGIN_ROOT}`) and the Ponytail runtime. They fire only when installed through the Ponytail plugin, not from project settings. Copy only the files the operator approves for a project that uses that plugin, and never overwrite an existing hook file.
+
+1. Create `hooks/` in the target project when copying
+2. Copy the approved files from the template's `hooks/*` directory (preserve sub-structure); skip any file that already exists
 3. Make `.js` files executable on Unix: `chmod +x hooks/*.js`
 
 ### 10. Clean Up Duplicate Skills