nitm-ai-dev-toolkit 5.1.1 → 5.1.3

package/bin/relevance.js

@@ -0,0 +1,306 @@
+'use strict';
+
+// Relevance-aware patch and doctor. This module decides; bin/cli.js plans and writes.
+//   - .nitm/retired.json: paths the project retired (never re-added) and an optional tracker override
+//   - detectProject(): trackers, Playwright, Prisma, UI and stack facts read from the project
+//   - relevanceOf(): add | irrelevant | review for one template path
+//   - auditWrapper(): whether a harness wrapper is thin (link to its snippet plus key points) or inlines policy
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const RETIRED_FILE = path.join('.nitm', 'retired.json');
+const TRACKERS = ['github', 'gitlab', 'bitbucket', 'jira', 'linear'];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MAX_KEY_POINTS = 5;
+const MAX_SUMMARY_WORDS = 30;
+
+// Tracker CLI skills ship only for the tracker they talk to. gh-cli also covers GitHub pull requests.
+const TRACKER_SKILLS = { 'gh-cli': 'github', 'glab-cli': 'gitlab', 'bkt-cli': 'bitbucket', acli: 'jira', 'linear-cli': 'linear' };
+// Files named after a tool or stack. They apply only when that tool or stack is detected.
+const STEM_TOPICS = {
+  'playwright-test': 'playwright',
+  'prisma-migrations': 'prisma',
+  'component-structure': 'ui',
+  'ui-accessibility': 'ui',
+};
+const TOPIC_NOTES = {
+  playwright: 'no Playwright setup detected',
+  prisma: 'no Prisma setup detected',
+  ui: 'no UI framework detected',
+};
+// Empty MCP templates ship no servers, so a missing copy adds nothing.
+const MCP_TEMPLATES = ['.mcp.json', '.cursor/mcp.json', '.vscode/mcp.json'];
+
+const HOST_TRACKERS = { 'github.com': 'github', 'gitlab.com': 'gitlab', 'bitbucket.org': 'bitbucket' };
+const UI_DEPS = ['react', 'react-dom', 'react-native', 'expo', 'next', 'vue', 'nuxt', 'svelte', '@sveltejs/kit',
+  '@angular/core', 'solid-js', 'astro', 'preact'];
+const PLAYWRIGHT_DEPS = ['playwright', '@playwright/test'];
+const PLAYWRIGHT_CONFIGS = ['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+const PRISMA_DEPS = ['prisma', '@prisma/client'];
+const PRISMA_FILES = ['schema.prisma', path.join('prisma', 'schema.prisma')];
+// Root manifests that prove a stack exists (for ui decisions) and that may name Playwright.
+const STACK_MANIFESTS = ['package.json', 'pyproject.toml', 'requirements.txt', 'setup.py', 'composer.json',
+  'go.mod', 'Cargo.toml', 'Gemfile', 'pom.xml', 'build.gradle', 'build.gradle.kts'];
+
+// Harness wrappers and the shared source each one links to. Snippets hold the policy; a skill with the
+// same name (orient-to-recent-work) is the source when no snippet exists.
+const WRAPPER_KINDS = [
+  { dir: '.claude/rules', snippets: 'rules-snippets' },
+  { dir: '.claude/commands', snippets: 'prompt-snippets' },
+  { dir: '.claude/agents', snippets: 'agents-snippets' },
+  { dir: '.cursor/rules', snippets: 'rules-snippets' },
+  { dir: '.cursor/commands', snippets: 'prompt-snippets' },
+  { dir: '.cursor/agents', snippets: 'agents-snippets' },
+  { dir: '.github/instructions', snippets: 'rules-snippets' },
+  { dir: '.github/prompts', snippets: 'prompt-snippets' },
+  { dir: '.github/agents', snippets: 'agents-snippets' },
+  { dir: '.opencode/rules', snippets: 'rules-snippets' },
+  { dir: '.opencode/commands', snippets: 'prompt-snippets' },
+  { dir: '.opencode/agents', snippets: 'agents-snippets' },
+];
+
+function readJsonFile(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+}
+
+function readText(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch (_) { return ''; }
+}
+
+// ---- retirement list ----
+
+// Canonical form: forward slashes, no leading ./, no doubled or inner / segments, no trailing /. Climbing
+// segments and absolute paths are refused on the raw input, before normalising could fold them away.
+function safeRetiredPath(value, where) {
+  const raw = typeof value === 'string' ? value.replace(/\\/g, '/') : '';
+  const absolute = path.posix.isAbsolute(raw) || path.win32.isAbsolute(raw);
+  const climbs = raw.split('/').includes('..');
+  const rel = raw ? path.posix.normalize(raw).replace(/^(\.\/)+/, '').replace(/\/+$/, '') : '';
+  if (!rel || rel === '.' || absolute || climbs) {
+    throw new Error(`${where}.path must be a relative path inside the project (got ${JSON.stringify(value)})`);
+  }
+  return rel;
+}
+
+function normalizeRetired(entry, index) {
+  const where = `${RETIRED_FILE} retired[${index}]`;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error(`${where} must be an object with path, reason and date`);
+  }
+  const rel = safeRetiredPath(entry.path, where);
+  if (typeof entry.reason !== 'string' || !entry.reason.trim()) {
+    throw new Error(`${where}.reason is required: say why the file was retired`);
+  }
+  if (typeof entry.date !== 'string' || !DATE_RE.test(entry.date)) {
+    throw new Error(`${where}.date is required as YYYY-MM-DD`);
+  }
+  return { path: rel, reason: entry.reason.trim(), date: entry.date };
+}
+
+// Reads .nitm/retired.json. Absent means nothing retired. A file that exists but is invalid throws, so
+// patch never falls back to re-adding files the project retired.
+function readRetired(cwd) {
+  const p = path.join(cwd, RETIRED_FILE);
+  if (!fs.existsSync(p)) return { trackers: undefined, entries: [] };
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (ex) {
+    throw new Error(`${RETIRED_FILE} exists but is not valid JSON (${ex.message}). Fix or remove it; nothing was written.`);
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error(`${RETIRED_FILE} must be a JSON object with "retired" and optional "trackers"`);
+  }
+  let trackers;
+  if (data.trackers !== undefined && data.trackers !== null) {
+    if (!Array.isArray(data.trackers) || data.trackers.some((t) => !TRACKERS.includes(t))) {
+      throw new Error(`${RETIRED_FILE}: "trackers" must be a list drawn from ${TRACKERS.join(', ')} (use [] for none)`);
+    }
+    trackers = [...new Set(data.trackers)];
+  }
+  const list = data.retired === undefined ? [] : data.retired;
+  if (!Array.isArray(list)) throw new Error(`${RETIRED_FILE}: "retired" must be a list`);
+  return { trackers, entries: list.map(normalizeRetired) };
+}
+
+// The retirement entry covering a template path (exact file, or any file under a retired directory).
+function retiredFor(key, entries) {
+  return entries.find((e) => key === e.path || key.startsWith(e.path + '/')) || null;
+}
+
+// ---- project facts ----
+
+// package.json at the root and one level down (apps/*, packages/*), so monorepo dependencies count.
+function packageJsons(cwd) {
+  const out = [];
+  const pkg = readJsonFile(path.join(cwd, 'package.json'));
+  if (pkg) out.push(pkg);
+  for (const parent of ['apps', 'packages']) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(path.join(cwd, parent), { withFileTypes: true });
+    } catch (_) { continue; }
+    for (const e of entries) {
+      const child = readJsonFile(path.join(cwd, parent, e.name, 'package.json'));
+      if (e.isDirectory() && child) out.push(child);
+    }
+  }
+  return out;
+}
+
+function dependencyNames(cwd) {
+  const names = new Set();
+  for (const pkg of packageJsons(cwd)) {
+    for (const name of [...Object.keys(pkg.dependencies || {}), ...Object.keys(pkg.devDependencies || {})]) {
+      names.add(name);
+    }
+  }
+  return names;
+}
+
+// The tracker implied by the git origin host, or null when there is no origin or the host is unknown.
+function remoteTrackers(cwd) {
+  let url;
+  try {
+    url = execFileSync('git', ['-C', cwd, 'remote', 'get-url', 'origin'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+  } catch (_) {
+    return null;
+  }
+  const match = url.match(/^(?:[a-z][a-z0-9+.-]*:\/\/)?(?:[^@/]+@)?([^/:]+)/i);
+  const tracker = match && HOST_TRACKERS[match[1].toLowerCase()];
+  return tracker ? [tracker] : null;
+}
+
+// Facts the relevance rules read. `trackers` is null when unknown (the rules then ask for a decision),
+// an array otherwise (possibly empty when the project has no tracker).
+function detectProject(cwd, retired) {
+  const deps = dependencyNames(cwd);
+  const rootManifests = STACK_MANIFESTS.map((f) => readText(path.join(cwd, f))).join('\n').toLowerCase();
+  const configured = retired && retired.trackers !== undefined;
+  const trackers = configured ? retired.trackers : remoteTrackers(cwd);
+  const trackerSource = configured ? `configured in ${RETIRED_FILE}` : (trackers ? 'git origin' : 'not detected');
+  return {
+    trackers,
+    trackerSource,
+    playwright: PLAYWRIGHT_DEPS.some((d) => deps.has(d)) || /playwright/.test(rootManifests)
+      || PLAYWRIGHT_CONFIGS.some((f) => fs.existsSync(path.join(cwd, f))),
+    prisma: PRISMA_DEPS.some((d) => deps.has(d)) || PRISMA_FILES.some((f) => fs.existsSync(path.join(cwd, f))),
+    ui: UI_DEPS.some((d) => deps.has(d)),
+    stackKnown: STACK_MANIFESTS.some((f) => fs.existsSync(path.join(cwd, f))),
+  };
+}
+
+// ---- relevance ----
+
+// What a template path depends on: 'tracker:<name>', 'playwright', 'prisma', 'ui', 'mcp', or null (generic).
+function topicOf(rel) {
+  const n = rel.split(path.sep).join('/');
+  if (MCP_TEMPLATES.includes(n)) return 'mcp';
+  const skill = /^\.agents\/skills\/([^/]+)\//.exec(n);
+  if (skill && TRACKER_SKILLS[skill[1]]) return `tracker:${TRACKER_SKILLS[skill[1]]}`;
+  return STEM_TOPICS[path.posix.basename(n).split('.')[0]] || null;
+}
+
+// 'add' applies to the project; 'irrelevant' does not (never added); 'review' cannot be decided from the
+// project yet (never added until someone decides).
+function relevanceOf(rel, facts) {
+  const topic = topicOf(rel);
+  if (!topic) return { status: 'add', reason: '' };
+  if (topic === 'mcp') return { status: 'irrelevant', reason: 'empty MCP template, no servers configured' };
+  if (topic.startsWith('tracker:')) {
+    const tracker = topic.slice('tracker:'.length);
+    if (facts.trackers === null) {
+      return { status: 'review', reason: `tracker not detected; set "trackers" in ${RETIRED_FILE}` };
+    }
+    if (facts.trackers.includes(tracker)) return { status: 'add', reason: '' };
+    return { status: 'irrelevant', reason: `project tracker is ${facts.trackers.join(', ') || 'none'}` };
+  }
+  const detected = { playwright: facts.playwright, prisma: facts.prisma, ui: facts.ui }[topic];
+  if (detected) return { status: 'add', reason: '' };
+  if (topic === 'ui' && !facts.stackKnown) return { status: 'review', reason: 'no stack manifest found' };
+  return { status: 'irrelevant', reason: TOPIC_NOTES[topic] };
+}
+
+// ---- thin wrappers ----
+
+// The wrapper's kind and the sources it must link to: its snippet, then a same-named skill.
+function wrapperSources(rel) {
+  const n = rel.split(path.sep).join('/');
+  const kind = WRAPPER_KINDS.find((k) => n.startsWith(k.dir + '/') && !n.slice(k.dir.length + 1).includes('/'));
+  if (!kind) return null;
+  const base = path.posix.basename(n);
+  const name = base.replace(/\.(agent|instructions|prompt)\.md$/, '').replace(/\.mdc$/, '').replace(/\.md$/, '');
+  const snippet = `.claude/${kind.snippets}/${name}.md`;
+  const skill = `.agents/skills/${name}/SKILL.md`;
+  return [{ rel: snippet, needle: `${kind.snippets}/${name}.md` }, { rel: skill, needle: skill }];
+}
+
+function bodyOf(content) {
+  if (!content.startsWith('---\n')) return content;
+  const end = content.indexOf('\n---', 3); // the closing delimiter; empty frontmatter ("---\n---") included
+  return end < 0 ? content : content.slice(end + 4);
+}
+
+// `targets` are the sources that exist in the project, each as { rel, needle }.
+// thin: links a source, with at most one short summary line, a few key points and no table or other policy
+// text; inlined: more prose, a table or too many key points outside the link; diverged: links no existing source.
+function auditWrapper(content, targets) {
+  const linked = targets.find((t) => bodyOf(content).includes(t.needle));
+  if (!linked) return { status: 'diverged', reason: `does not link ${targets.map((t) => t.rel).join(' or ')}` };
+  const prose = [];
+  let bullets = 0;
+  // "Agent Dispatch" names the agent to activate and "Arguments" the command syntax: both are activation metadata.
+  let metadata = false;
+  for (const raw of bodyOf(content).split('\n')) {
+    const line = raw.trim();
+    if (/^#+\s/.test(line)) { metadata = /^#+\s+(agent dispatch|arguments)\b/i.test(line); continue; }
+    if (metadata || line === '$ARGUMENTS') continue;
+    if (!line || line.startsWith('>') || line.includes(linked.needle)) continue;
+    if (/^([-*]|\d+\.)\s/.test(line)) { bullets++; continue; }
+    if (/:$/.test(line) && line.split(/\s+/).length <= 3) continue; // a label such as "Key points:"
+    prose.push(line);
+  }
+  const summaryOnly = prose.length === 1 && prose[0].split(/\s+/).length <= MAX_SUMMARY_WORDS;
+  if (prose.length > 0 && !summaryOnly) {
+    return { status: 'inlined', reason: `${prose.length} line(s) of policy text or table outside the link` };
+  }
+  if (bullets > MAX_KEY_POINTS) {
+    return { status: 'inlined', reason: `${bullets} key points (max ${MAX_KEY_POINTS}); move the rest into the source` };
+  }
+  return { status: 'thin', reason: '' };
+}
+
+// Wrappers among the planned entries that exist in the project and are not thin. Read-only: the caller
+// reports them and proposes moving the inlined content into the snippet.
+function auditWrappers(cwd, plan) {
+  const out = [];
+  for (const e of plan) {
+    if (e.action === 'retired') continue;
+    const sources = wrapperSources(e.rel);
+    const file = path.join(cwd, e.rel);
+    if (!sources || !fs.existsSync(file)) continue;
+    const targets = sources.filter((s) => fs.existsSync(path.join(cwd, s.rel)));
+    const result = targets.length
+      ? auditWrapper(fs.readFileSync(file, 'utf8'), targets)
+      : { status: 'diverged', reason: `no ${sources[0].rel} or ${sources[1].rel} to link` };
+    if (result.status !== 'thin') out.push({ rel: e.rel, status: result.status, reason: result.reason });
+  }
+  return out;
+}
+
+module.exports = {
+  RETIRED_FILE,
+  TRACKERS,
+  MAX_KEY_POINTS,
+  readRetired,
+  retiredFor,
+  detectProject,
+  topicOf,
+  relevanceOf,
+  wrapperSources,
+  auditWrapper,
+  auditWrappers,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "5.1.1",
+  "version": "5.1.3",
   "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode, Codex) into any repo, then hand off to your AI agent to finish setup.",
   "bin": {
     "nitm-ai-dev-toolkit": "bin/cli.js"

package/src/monorepo/.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 (the git root, inside the repo folder). Record its absolute path in `worktree_path`.
+- Path `.worktrees/<id>/` at the root of the main checkout (the git root, 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/monorepo/.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/monorepo/.claude/prompt-snippets/bootstrap-patch.md

@@ -115,11 +115,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**:
@@ -130,7 +132,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
@@ -144,13 +146,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           |
     | -------------------------------------------------------- | ------------------------------ | -------------- |
@@ -161,16 +163,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
     ```
 
@@ -178,9 +194,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/monorepo/.claude/prompt-snippets/bootstrap-upgrade.md

@@ -255,6 +255,8 @@ Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/r
 
 ### Step 7: Create .opencode/ Directory (confirmed OpenCode use only)
 
+Create wrappers below only for entries the patch plan classifies *add* (never retired or not-relevant snippets). Each wrapper stays thin (see Thin Wrapper Policy in `bootstrap.md`).
+
 For the v3 route, merge only relevant native OpenCode host fields; preserve existing wrapper bodies, modes, unrelated frontmatter, and shared snippet bodies/frontmatter. The wrapper examples below apply only to approved missing files, not replacement of existing wrappers.
 
 1. Merge `.opencode/opencode.jsonc` using native V2 fields:
@@ -312,12 +314,13 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
 
 ### Step 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
    ```
@@ -330,10 +333,12 @@ This enforces:
 
 Use `git commit --no-verify` to bypass.
 
-### Step 9: Install Project Hooks
+### Step 9: Install Project Hooks (only with approval)
+
+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/` directory in the target project
-2. Copy all files from the template's `hooks/*` directory (preserve sub-structure)
+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`
 
 ### Step 10: Clean Up Duplicate Skills