@dzhechkov/p-replicator 1.5.18 → 1.9.0

package/src/utils.js

@@ -308,6 +308,7 @@ const COMPONENTS = {
       'git-workflow':             'Commit/push discipline, branch strategy, semantic messages',
       'insights-capture':         'When and how to capture development insights to knowledge base',
       'feature-lifecycle':        '/feature phases (PLAN → VALIDATE → IMPLEMENT → REVIEW), checkpoints, scoring',
+      'docker-ports':             'Правило №0: storage ports are not published outward; loopback bind is the exception',
     },
   },
   settings: {
@@ -332,6 +333,9 @@ const COMPONENTS = {
       'autocommit-plans':    'Auto-commit docs/plans/ on Stop hook',
       'statusline':          'Multi-line dashboard (pipeline, roadmap, toolkit) for Claude Code statusLine',
       'state-update':        'Argv-driven helper for pipeline commands to publish current command + phase + progress',
+      'check-ports':              'Enforce docker-ports Правило №0 against a real compose (invoke deliberately; exits 0/1/2)',
+      'check-growth-trace':       'Did the M5 growth seed reach docs/Specification.md (invoke deliberately; exits 0/1/2)',
+      'check-docs-complete':      'Are Phase-1 documents written and placeholder-free, before the Phase-2 swarm (invoke deliberately; exits 0/1/2)',
     },
   },
   // ─── Project-generated groups (created by /replicate Phase 3) ───────────

package/templates/.claude/agents/doc-validator.md

@@ -15,7 +15,7 @@ Read from: `.claude/skills/requirements-validator/SKILL.md`
 
 ## Swarm Strategy
 
-Launch 5 parallel validation agents using Task tool:
+Launch 6 parallel validation agents using Task tool:
 
 | Agent | Scope | Criteria | Tool |
 |-------|-------|----------|------|
@@ -24,6 +24,7 @@ Launch 5 parallel validation agents using Task tool:
 | `validator-architecture` | Architecture.md | Target constraints compliance, completeness | Task |
 | `validator-pseudocode` | Pseudocode.md | Story coverage, implementability | Task |
 | `validator-coherence` | Cross-document | Consistency, no contradictions | Task |
+| `validator-dependencies` | `Architecture.md` → `## External Dependencies` | Every external capability a requirement relies on has a verdict and, where CONFIRMED, evidence that names that capability | Task |
 
 ## Scoring System
 

package/templates/.claude/agents/product-discoverer.md

@@ -19,7 +19,7 @@ Read from: `.claude/skills/reverse-engineering-unicorn/SKILL.md`
 | M2: Product & Customers | Always | JTBD, Value Prop, segments |
 | M3: Market & Competition | Always | TAM/SAM, competitors, Blue Ocean Canvas |
 | M4: Business & Finance | If monetization model needed | Unit economics |
-| M5: Growth Engine | If B2C/PLG | Channels, integrations, viral loops |
+| M5: Growth Engine | If acquisition/adoption in scope (incl. B2B) | Channels, integrations, viral loops |
 
 ## Output Format
 

package/templates/.claude/commands/next.md

@@ -81,6 +81,22 @@ Blocked: <count> (run /next blocked to see)
 
 ### Schema fields (post v1.5.0)
 
+**This table is THE schema for `.claude/feature-roadmap.json`.** It is the only one: any other
+document that shows the file's fields must point here rather than restate them, because two
+descriptions of one file are two chances to be wrong and only one of them can be right.
+
+**Who creates the file** — both answers are true, in different modes, and this is the one place that
+says so:
+
+- after `/replicate`, Phase 3 generates it from the PRD MVP scope;
+- in Mode 2 (an existing project where `init` added the toolkit and `/replicate` never ran), the user
+  writes it by hand if they want batch automation via `/run mvp`; ad-hoc `/feature <id>` needs no
+  roadmap at all.
+
+`priority` is a CLOSED set — `mvp`, `high`, `medium`, `low`. A value outside it is not a new priority,
+it is a roadmap this toolkit cannot read: the status line counts MVP by `priority === 'mvp'` and will
+mark the file rather than quietly report zero.
+
 | Field | Required | Populated by | Purpose |
 |-------|----------|--------------|---------|
 | `id` | yes | initial roadmap generation | Stable kebab-case slug |

package/templates/.claude/commands/replicate.md

@@ -166,9 +166,37 @@ Read the skill: `.claude/skills/reverse-engineering-unicorn/SKILL.md`
 | M2: Product & Customers | Always | JTBD, Value Prop, segments |
 | M3: Market & Competition | Always | TAM/SAM, competitors, Blue Ocean |
 | M4: Business & Finance | If monetization | Unit economics |
-| M5: Growth Engine | If B2C/PLG | Channels, integrations |
+| M5: Growth Engine | If acquisition/adoption in scope (incl. B2B) | Channels, integrations |
 
-**Output:** Product Discovery Brief → passed as pre-filled context to Phase 1
+M5 is no longer gated on PRODUCT TYPE. The module branches on type itself — *«Если B2B → sales-led
+growth, не product-led»* — so gating it outside disabled the one branch it declares, and every B2B
+project got an empty `### Growth Channels` slot.
+
+The condition is APPLICABILITY, not type, and the difference matters in both directions: `Always`
+would over-promise, because M5's outputs are CAC, channels and loops, and an internal tool with no
+acquisition objective has nothing to put in them. So: run it whenever acquisition or adoption is in
+scope — which includes B2B — and skip it when neither is. The cost is visible rather than
+discovered: a B2B run now spends M5's time.
+
+Honest limit: line 62 of the module says to *switch* to a sales-led framework; it does not define
+one. A B2B run gets the type-appropriate instruction, not a type-appropriate playbook.
+
+**Output — WRITE FIRST, then hand off. Both, in this order:**
+
+1. **Write** the full Product Discovery Brief to `docs/product-discovery-brief.md`.
+2. **Then** pass it to Phase 1 as pre-filled context, exactly as before.
+
+The hand-off is unchanged; the file is an ADDITION. Until this was added the brief existed only in
+the conversation — it made Phase 1 skip its own Phase 0 (`sparc-prd-mini/SKILL.md:993-999`) and then
+vanished, so the M5 growth analysis had no artifact any later step could read. Nothing downstream was
+ignoring it: there was nothing to ignore.
+
+The file MUST include M5's `Growth Requirements Seed` table verbatim when M5 ran — that table is the
+only place `FR-GROWTH-nnn` obligations exist before Phase 1 promotes them.
+
+**When this file is absent it means Phase 0 did not run** — the `--from-docs` / `--skip-discovery`
+entry skips Phase 0 entirely (see the alternative-entry section). Absence is NOT evidence that the
+project has no growth requirements, and no consumer may read it that way.
 
 **Checkpoint:**
 ```
@@ -240,8 +268,49 @@ Created [N] documents in docs/
 ═══════════════════════════════════════════════════════════════
 ```
 
+### Прерванный прогон: как продолжить с того места
+
+`/replicate` — интерактивный конвейер с четырьмя чекпоинтами, и продолжить его можно **уже сейчас,
+без всякой новой машинерии**. Три сигнала, каждый существует независимо от этого раздела:
+
+| Вопрос | Чем отвечается |
+|---|---|
+| До какой фазы дошли? | `git log --oneline` — после КАЖДОЙ фазы делается свой коммит (`docs: SPARC…`, `docs: validation report…`, `feat: Claude Code toolkit…`, `chore: initial project setup…`) |
+| Документы Фазы 1 дописаны? | `node .claude/hooks/check-docs-complete.cjs .` — `0` дописаны, `1` названо, чего не хватает, `2` Фаза 1 не запускалась |
+| Тулкит Фазы 3 сгенерирован? | `npx @dzhechkov/p-replicator verify` — раздел «Post-/replicate» |
+
+**Как продолжить:** посмотрите последний коммит фазы, затем скажите `/replicate` прямым текстом:
+*«продолжай с Фазы 3, Фазы 0-2 уже сделаны»*. Конвейер интерактивный — человек на чекпоинте и есть
+механизм возобновления.
+
+**Почему здесь нет автоматического определения фазы.** Оно рассматривалось (бэклог `58575b07`) и
+сознательно НЕ реализовано: три сигнала выше уже дают ответ, а свежая логика ветвления в
+интерактивном конвейере — это то, что может сработать неверно ровно тогда, когда прогон и так пошёл
+не по плану. Запись решения важнее самого решения: если вы вернётесь к этому вопросу, начинайте с
+того, что перечисленного выше оказалось недостаточно.
+
 ### Phase 2: VALIDATION
 
+**Шаг 2.0 — ДЕТЕРМИНИРОВАННАЯ ПРОВЕРКА ПОЛНОТЫ. Выполняется ПЕРВОЙ, до запуска роя.**
+
+```bash
+node .claude/hooks/check-docs-complete.cjs .
+```
+
+| Код | Что делать |
+|:---:|---|
+| `0` | продолжайте — рой валидации запускается |
+| `1` | **НЕ запускайте рой.** Вернитесь в Фазу 1 и допишите названные документы |
+| `2` | проверка не выполнена — почините вызов и повторите; это НЕ «всё в порядке» |
+
+Причина, по которой шаг стоит здесь, а не внутри роя: существование файла, его пустота и
+незаполненный шаблон решаются сорока строками кода. Отправлять на этот вопрос рой агентов — значит
+платить вероятностной проверкой за то, что решается детерминированно. Рою остаётся то, ради чего он
+и нужен: тестируемость, полнота требований, реализуемость.
+
+Ограничение, которое проверка печатает сама: она доказывает, что документы НАПИСАНЫ, а не что они
+верны. Верность — работа роя.
+
 Read the skill: `.claude/skills/requirements-validator/SKILL.md`
 
 **Goal:** Verify all documentation for completeness, testability, and implementation readiness.
@@ -255,6 +324,10 @@ Read the skill: `.claude/skills/requirements-validator/SKILL.md`
 | `validator-architecture` | Architecture.md | Target constraints, completeness |
 | `validator-pseudocode` | Pseudocode.md | Story coverage, implementability |
 | `validator-coherence` | Cross-document | Consistency, no contradictions |
+| `validator-dependencies` | `Architecture.md` → `## External Dependencies` | Every external capability a requirement relies on has a verdict and, where CONFIRMED, evidence that names that capability |
+
+The sixth lens is the only one that looks OUTSIDE the documents. The other five compare our own
+output with our own output, which cannot discover that a service does not do what we assumed.
 
 **Process (iterative, max 3 iterations):**
 
@@ -270,7 +343,16 @@ Read the skill: `.claude/skills/requirements-validator/SKILL.md`
 - Happy path (1-2), Error handling (2-3), Edge cases (1-2), Security
 - Save as `docs/test-scenarios.md`
 
-**Save validation report:** `docs/validation-report.md`
+**Save validation report:** `docs/validation-report.md`. Its **first line** must be exactly one of
+
+```
+**Verdict:** 🟢 READY
+**Verdict:** 🟡 CAVEATS
+**Verdict:** 🔴 NEEDS WORK
+```
+
+and no other line in the file may begin with `**Verdict:**`. Phase 3 reads that one line and nothing
+else — an unanchored verdict is a verdict Phase 3 can find in an example or a quoted history.
 
 Git commit: `docs: validation report and BDD scenarios`
 
@@ -278,9 +360,85 @@ Git commit: `docs: validation report and BDD scenarios`
 
 | Verdict | Conditions | Action |
 |---------|-----------|--------|
-| 🟢 READY | All scores ≥50, average ≥70, no contradictions | → Phase 3 |
-| 🟡 CAVEATS | Warnings exist, no blocked, limitations described | → Phase 3 with notes |
-| 🔴 NEEDS WORK | Blocked items exist | → Return to Phase 1 |
+| 🟢 READY | All scores ≥50, average ≥70, no contradictions, **no item on the blocking floor**, **no external dependency `UNCONFIRMED` or `CONTRADICTED`** | → Phase 3 |
+| 🟡 CAVEATS | Warnings exist, no blocked, limitations described, **every `UNCONFIRMED` dependency NAMED row by row** | → Phase 3 with notes |
+| 🔴 NEEDS WORK | Blocked items exist, **or any item has `Testable = 0` or `Completeness = 0`**, **or any external dependency is `CONTRADICTED`** | → Return to Phase 1 |
+
+**The blocking floor** (`skills/requirements-validator/references/scoring-system.md` → "Blocking
+floor"): the weakest link decides, never the average. An item with no acceptance criteria totals
+72/100 and would otherwise read as READY.
+
+**Шаг 2.9 — ПОКРЫТИЕ РЕШЕНИЙ (обязательный, до чекпойнта).**
+
+Every decision in `docs/ADR.md` carries an id `ADR-<nnn>` — three digits, assigned in order, never
+reused even after a decision is superseded.
+
+**Where to look, named file by file.** «Across the docs» is not an instruction. Search EXACTLY these,
+and no others:
+
+```
+docs/PRD.md · docs/Solution_Strategy.md · docs/Specification.md · docs/Pseudocode.md
+docs/Architecture.md · docs/Refinement.md · docs/Completion.md · docs/C4_Diagrams.md
+```
+
+**Two files are EXCLUDED, and the first exclusion is the one that makes this check work at all:**
+
+- `docs/ADR.md` itself. Its own headings contain every id, so counting them would make every decision
+  appear named and the check would pass by construction — always, on any project.
+- `docs/validation-report.md`. This step WRITES into it. Counting it would let the previous run's
+  output satisfy the next run: the check would start proving itself.
+
+**What counts as a mention.** The exact token `ADR-<nnn>`, case-sensitive, in one of the files above.
+Not a title, not a paraphrase, not a link whose text merely resembles it. One occurrence is enough;
+repeats are not counted twice.
+
+**A superseded decision needs no current mention.** If a decision's own entry says it is superseded,
+list it in a third column rather than as a gap — it was replaced, not forgotten.
+
+Write a `## Decision Coverage` block into `docs/validation-report.md` — **in every case**, including
+the one where everything is covered, because an absent block and a block saying "all covered" are
+indistinguishable to the next reader:
+
+```
+## Decision Coverage
+
+Decisions in docs/ADR.md: [N]  ·  named downstream: [M]  ·  superseded: [S]
+
+Recorded but named nowhere:
+| Decision | Title |
+|---|---|
+| ADR-… | … |
+
+Named downstream but absent from docs/ADR.md:
+| Reference | Where |
+|---|---|
+| ADR-… | docs/… |
+```
+
+**Both tables are required, and both may be the single word `none`.** A one-way check is half a
+check: without the second table, a document referring to `ADR-009` that nobody ever wrote reads
+exactly like coverage. `none` is written out rather than left blank, because an empty table and a
+forgotten table look identical.
+
+**Three states of the ADR file, and each has its own line — the block is written in all three:**
+
+| State | What to write in the block |
+|---|---|
+| `docs/ADR.md` absent | *"docs/ADR.md is absent, so no decision ids were collected from it. The second table below still applies."* |
+| present but containing no `ADR-<nnn>` id | *"docs/ADR.md exists but records no decision ids."* |
+| present with ids | the counts and the two tables above |
+
+Note what the first line does NOT say. It says the FILE is absent — not that the project recorded no
+architectural decisions. Decisions may live somewhere this pipeline does not look, and claiming
+otherwise would be asserting something this step cannot see. **In all three states the second table
+still runs**: a downstream reference to a decision that does not exist is a defect whether or not an
+ADR file was ever written.
+
+**What this establishes, and what it does not.** It establishes that a decision is NAMED somewhere
+downstream. It does NOT establish that the decision was implemented — no comparison of identifiers
+can. So it catches *"the decision was written down and then forgotten"*; it does not catch *"someone
+mentioned it in a sentence and built something else"*. Say so here rather than letting a later reader
+assume the stronger thing.
 
 **Checkpoint:**
 ```
@@ -295,6 +453,18 @@ Iterations: N/3
 
 ### Phase 3: TOOLKIT GENERATION
 
+**Precondition — check it before reading anything else. The toolkit is built ON the validated docs,
+so an unvalidated input is not a smaller toolkit, it is a wrong one:**
+
+1. `docs/validation-report.md` must EXIST. If it is absent, Phase 2 did not run or did not finish —
+   do NOT generate anything; return to Phase 2 and say so.
+2. Its **first line** must be `**Verdict:**` followed by 🟢 READY or 🟡 CAVEATS. Read ONLY that
+   line: a verdict word anywhere else in the document — an example, a quoted history, a summary —
+   is NOT the verdict. On 🔴 NEEDS WORK, on no such first line, or on more than one line starting
+   with `**Verdict:**`, do NOT generate anything; return to Phase 2 and say which of the four it was.
+3. On 🟡, carry the report's stated limitations into the toolkit's own notes — a caveat that stops at
+   the phase boundary was never recorded.
+
 Read the skill: `.claude/skills/cc-toolkit-generator-enhanced/SKILL.md`
 
 **Goal:** Generate project-specific Claude Code instruments IN-PLACE.
@@ -305,7 +475,7 @@ Read the skill: `.claude/skills/cc-toolkit-generator-enhanced/SKILL.md`
 - **Pre-shipped by `npx p-replicator init` — do NOT overwrite or regenerate:**
   - All 10 skills in `.claude/skills/`
   - All 11 commands: `/replicate`, `/harvest`, `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy`
-  - All 5 rules: `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle`
+  - All 6 rules: `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle`, `docker-ports`
   - All 4 pipeline agents: `replicate-coordinator`, `product-discoverer`, `doc-validator`, `harvest-coordinator`
   - `.claude/settings.json` + cross-platform Node hook scripts in `.claude/hooks/`
 - Phase 3 generates ONLY project-specific artifacts derived from SPARC docs (see below).
@@ -369,11 +539,15 @@ Git commit: `feat: Claude Code toolkit for [project-name]`
 
 **Generate scaffold files:**
 
-1. `docker-compose.yml` — from Architecture.md services
+1. `docker-compose.yml` — from Architecture.md services, **if not exists** (a run over a tree that already has one must not discard it either — the guard is symmetric)
 2. `Dockerfile` — from Architecture.md tech stack
 3. `.gitignore` — if not exists
 4. `docs/features/` — create empty directory for future features
 
+> `docker-compose.yml`, `.gitignore` и `README.md` позже читает `/start` (Phase 1). Он обязан их СОХРАНИТЬ и
+> менять только по названной причине — правило `if not exists` записано на его стороне. Оба конца
+> рекомендованной последовательности договорены в тексте, а не совпадают по случайности.
+
 **Git operations:**
 ```bash
 git add .
@@ -467,7 +641,7 @@ PRINCIPLE: User enters keys via UI → stored encrypted in browser → NEVER sen
 
 ### NEVER
 - Don't duplicate explore/research phases — sparc-prd-mini does this internally
-- Never skip validation — toolkit is built on validated docs
+- Never skip validation — toolkit is built on validated docs. The enforcing check is Phase 3's precondition, which reads the first `**Verdict:**` line of `docs/validation-report.md`
 - Never use base cc-toolkit-generator — only enhanced version
 - Don't overwrite template files (generic commands, rules, settings.json)
 

package/templates/.claude/commands/start.md

@@ -33,7 +33,25 @@ via `Task` tool, commits per logical change for safe error recovery.
 2. **Generate root configs:** `package.json` (monorepo workspaces),
    `docker-compose.yml`, `.env.example`, `.gitignore`, `tsconfig.base.json`.
 
-3. **Git commit:** `chore: project root configuration`
+   **Два из них `/replicate` уже мог записать.** Штатная последовательность — `/replicate`, затем
+   `/start`, а Phase 4 команды `/replicate` создаёт `docker-compose.yml` и `.gitignore` из того же
+   `Architecture.md`. Значит это не два разных файла, а один, выведенный дважды, и слепая
+   перегенерация молча выбросит всё, что между двумя запусками правили руками.
+
+   Для `docker-compose.yml`, `.gitignore` и `README.md` действует правило `if not exists`:
+   - файла НЕТ → создать, как обычно;
+   - файл ЕСТЬ → **не перегенерировать**. Прочитать его и оставить; внести только МИНИМАЛЬНУЮ
+     точечную правку, которой требует названное требование из документов (появился пакет, которого
+     в файле нет; порт из `Architecture.md` не проброшен). Всё, что к этому требованию не относится,
+     сохраняется без изменений.
+   - Перед коммитом ПОСМОТРЕТЬ ДИФ и НАЗВАТЬ каждый изменённый фрагмент и его причину. «Добавил
+     недостающий порт», под которым лежит переписанный целиком файл, — это и есть та потеря,
+     которую правило предотвращает; диф отличает одно от другого, а обещание не отличает.
+
+3. **Git commit:** `chore: project root configuration`. Если на шаге 2 менялся уже существовавший
+   `docker-compose.yml`, `.gitignore` или `README.md` — тело коммита перечисляет каждый изменённый
+   фрагмент и причину. Фиксированный заголовок не отменяет этого перечня: заголовок говорит, ЧТО за
+   шаг, тело — что именно он тронул в чужом файле.
 
 ### Phase 2: Packages (PARALLEL via Task tool ⚡)
 

package/templates/.claude/hooks/autocommit-insights.cjs

@@ -10,30 +10,115 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 
-const TARGET_DIR = path.resolve(process.cwd(), '.claude', 'insights');
-const RELATIVE = path.relative(process.cwd(), TARGET_DIR);
-const SILENT = { stdio: 'ignore' };
+// The project root, never the process cwd: a `cd` inside any tool call moves cwd for the rest of
+// the session, and these hooks are non-blocking, so a wrong anchor fails SILENTLY. CLAUDE_PROJECT_DIR
+// first — the host is authoritative about what the project is. `__dirname` second: a hook always
+// lives at <project>/.claude/hooks/<x>.cjs, so its own location settles the root with no cooperation
+// from anyone, which is what keeps this working when the variable is absent (hand-run, older host).
+const ENV_ROOT = process.env.CLAUDE_PROJECT_DIR;
+// isAbsolute, not just truthy: a RELATIVE value would still be resolved against the drifting
+// cwd, which is the very bug this anchor exists to remove.
+const ROOT = (ENV_ROOT && path.isAbsolute(ENV_ROOT))
+  ? ENV_ROOT
+  : path.resolve(__dirname, '..', '..');
+
+const TARGET_DIR = path.resolve(ROOT, '.claude', 'insights');
+const RELATIVE = path.relative(ROOT, TARGET_DIR);
+// cwd: ROOT — the paths below are relative to ROOT, so git must run there too.
+// stderr is PIPED, not ignored: on success nothing is printed anyway, and on failure git's
+// own words are the only thing that tells a reader WHY. Discarding them leaves a report that
+// names what failed and not why, which is half a report.
+const SILENT = { stdio: ['ignore', 'pipe', 'pipe'], cwd: ROOT };
+
+// What the hook was DOING when it failed. The outer catch also sees staging failures and a
+// missing git binary, and reporting either of those as "could not commit" would send the reader
+// looking in the wrong place.
+let stage = 'start';
 
 function git(args) {
   return execFileSync('git', args, SILENT);
 }
 
 try {
-  if (!fs.existsSync(TARGET_DIR)) process.exit(0);
-  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+  // The repository probe comes FIRST now, because the absence check below needs to ask git a
+  // question and there is no point asking outside a repository.
+  stage = 'inspect the repository';
+  try {
+    git(['rev-parse', '--git-dir']);
+  } catch (probeErr) {
+    // "Not a git repository" is the ordinary case and stays silent. Everything else — no git on
+    // PATH, dubious ownership, a permission error — is a real failure that used to look exactly
+    // like it, which is how a broken machine and an ordinary directory became indistinguishable.
+    const why = String((probeErr && probeErr.stderr) || '').trim();
+    if (!why || /not a git repository/i.test(why)) process.exit(0);
+    throw probeErr;
+  }
+
+  // Absent — but absent HOW? A path that never existed is nothing to do, as before. A path git
+  // still tracks is a DELETION, and a deletion is exactly the change this hook exists to record.
+  //
+  // `git ls-files` is the discriminator, and it must run BEFORE staging: staging a deletion
+  // removes the entry from the index, after which the same question answers "not tracked".
+  // CORRECTION, measured: `--error-unmatch` also discriminates correctly here, for files AND for
+  // directories — 0 for a deleted-but-tracked path, 1 for one that never existed. An earlier note
+  // here claimed otherwise; that claim came from measuring it AFTER staging, which is what made it
+  // fail, not the directory-ness. `ls-files --` is preferred only because it answers with DATA
+  // (empty or not) instead of by throwing, so the ordinary case needs no exception handling.
+  //
+  // Simply DELETING the existence guard would have been the naive fix and would have broken the
+  // reporting that shipped yesterday: `git add` on a path that never existed exits 128, so every
+  // session stop in every project without this artifact would print a failure line. MEASURED.
+  if (!fs.existsSync(TARGET_DIR)) {
+    // A bare `catch { tracked = '' }` here would turn a REAL git failure into "never existed"
+    // and skip a deletion that should have been recorded — a silent bypass of the very thing
+    // this feature adds. A failure is rethrown into the reporting path; only a genuinely
+    // empty answer means the artifact never lived here.
+    const tracked = String(git(['ls-files', '--', RELATIVE]) || '').trim();
+    if (!tracked) process.exit(0);   // never existed here — silent, exactly as before
+  }
 
+  stage = 'stage the change';
   git(['add', '--', RELATIVE]);
 
-  let hasDiff = false;
+  // Ask git WHAT it staged, not merely WHETHER something changed — same subprocess, strictly
+  // more information. Deriving "this is a removal" from whether the path still exists was
+  // wrong for a directory: deleting ONE file inside it, or deleting every tracked file while
+  // an ignored one keeps the directory present, would have been committed as an update and
+  // defeated the very search this feature promises.
+  let staged = '';
   try {
-    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+    staged = String(git(['diff', '--cached', '--name-status', '--', RELATIVE]) || '').trim();
   } catch {
-    hasDiff = true;
+    // No HEAD yet (an unborn repository): there is no history to record a removal against.
+    staged = '';
   }
+  const deleted = staged.split('\n').some((l) => /^D/.test(l.trim()));
+  const hasDiff = staged.length > 0;
 
   if (hasDiff) {
-    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(insights): auto-capture']);
+    // -m BEFORE the `--`: everything after `--` is a PATHSPEC, so the old order made git
+    // look for files literally named '-m' and 'docs(insights): auto-capture' — it failed every
+    // time, from every directory, and this hook exits 0 on failure, so nobody saw it.
+    stage = 'commit';
+    // A deletion gets its own subject, so the event is findable in `git log` without
+    // reading diffs — which is the whole point of recording it.
+    git(['commit', '-m', deleted ? 'docs(insights): auto-remove' : 'docs(insights): auto-capture', '--only', '--', RELATIVE]);
   }
-} catch (_err) {
+} catch (err) {
+  // Best-effort — never break the Claude session on commit failures. But "not breaking the session"
+  // and "saying nothing" are different things, and only the first one is the contract: it is about
+  // the EXIT CODE. Silence is what let a permanent defect live here undetected — `-m` after `--`
+  // made every commit fail, from every directory, forever, and nothing said so.
+  //
+  // A held index.lock, a missing user.email, a repository pre-commit hook that rejected the commit,
+  // an ignored target: each now costs one line and still exits 0. The ordinary "nothing to commit"
+  // path never reaches here, deliberately — a notice that fires when nothing is wrong trains people
+  // to ignore notices, and the next real failure scrolls past with them.
+  const artifactName = '.claude/insights/';
+  const gitSaid = err && err.stderr ? String(err.stderr).trim() : '';
+  const detail = (gitSaid || String((err && err.message) || err)).split('\n')
+    .map((l) => l.trim()).filter(Boolean)[0] || 'unknown error';
+  process.stdout.write('[autocommit-insights] could not ' + stage + ' — ' + artifactName + ': '
+    + detail.slice(0, 200) + '\n');
   process.exit(0);
 }

package/templates/.claude/hooks/autocommit-plans.cjs

@@ -10,30 +10,115 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 
-const TARGET_DIR = path.resolve(process.cwd(), 'docs', 'plans');
-const RELATIVE = path.relative(process.cwd(), TARGET_DIR);
-const SILENT = { stdio: 'ignore' };
+// The project root, never the process cwd: a `cd` inside any tool call moves cwd for the rest of
+// the session, and these hooks are non-blocking, so a wrong anchor fails SILENTLY. CLAUDE_PROJECT_DIR
+// first — the host is authoritative about what the project is. `__dirname` second: a hook always
+// lives at <project>/.claude/hooks/<x>.cjs, so its own location settles the root with no cooperation
+// from anyone, which is what keeps this working when the variable is absent (hand-run, older host).
+const ENV_ROOT = process.env.CLAUDE_PROJECT_DIR;
+// isAbsolute, not just truthy: a RELATIVE value would still be resolved against the drifting
+// cwd, which is the very bug this anchor exists to remove.
+const ROOT = (ENV_ROOT && path.isAbsolute(ENV_ROOT))
+  ? ENV_ROOT
+  : path.resolve(__dirname, '..', '..');
+
+const TARGET_DIR = path.resolve(ROOT, 'docs', 'plans');
+const RELATIVE = path.relative(ROOT, TARGET_DIR);
+// cwd: ROOT — the paths below are relative to ROOT, so git must run there too.
+// stderr is PIPED, not ignored: on success nothing is printed anyway, and on failure git's
+// own words are the only thing that tells a reader WHY. Discarding them leaves a report that
+// names what failed and not why, which is half a report.
+const SILENT = { stdio: ['ignore', 'pipe', 'pipe'], cwd: ROOT };
+
+// What the hook was DOING when it failed. The outer catch also sees staging failures and a
+// missing git binary, and reporting either of those as "could not commit" would send the reader
+// looking in the wrong place.
+let stage = 'start';
 
 function git(args) {
   return execFileSync('git', args, SILENT);
 }
 
 try {
-  if (!fs.existsSync(TARGET_DIR)) process.exit(0);
-  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+  // The repository probe comes FIRST now, because the absence check below needs to ask git a
+  // question and there is no point asking outside a repository.
+  stage = 'inspect the repository';
+  try {
+    git(['rev-parse', '--git-dir']);
+  } catch (probeErr) {
+    // "Not a git repository" is the ordinary case and stays silent. Everything else — no git on
+    // PATH, dubious ownership, a permission error — is a real failure that used to look exactly
+    // like it, which is how a broken machine and an ordinary directory became indistinguishable.
+    const why = String((probeErr && probeErr.stderr) || '').trim();
+    if (!why || /not a git repository/i.test(why)) process.exit(0);
+    throw probeErr;
+  }
+
+  // Absent — but absent HOW? A path that never existed is nothing to do, as before. A path git
+  // still tracks is a DELETION, and a deletion is exactly the change this hook exists to record.
+  //
+  // `git ls-files` is the discriminator, and it must run BEFORE staging: staging a deletion
+  // removes the entry from the index, after which the same question answers "not tracked".
+  // CORRECTION, measured: `--error-unmatch` also discriminates correctly here, for files AND for
+  // directories — 0 for a deleted-but-tracked path, 1 for one that never existed. An earlier note
+  // here claimed otherwise; that claim came from measuring it AFTER staging, which is what made it
+  // fail, not the directory-ness. `ls-files --` is preferred only because it answers with DATA
+  // (empty or not) instead of by throwing, so the ordinary case needs no exception handling.
+  //
+  // Simply DELETING the existence guard would have been the naive fix and would have broken the
+  // reporting that shipped yesterday: `git add` on a path that never existed exits 128, so every
+  // session stop in every project without this artifact would print a failure line. MEASURED.
+  if (!fs.existsSync(TARGET_DIR)) {
+    // A bare `catch { tracked = '' }` here would turn a REAL git failure into "never existed"
+    // and skip a deletion that should have been recorded — a silent bypass of the very thing
+    // this feature adds. A failure is rethrown into the reporting path; only a genuinely
+    // empty answer means the artifact never lived here.
+    const tracked = String(git(['ls-files', '--', RELATIVE]) || '').trim();
+    if (!tracked) process.exit(0);   // never existed here — silent, exactly as before
+  }
 
+  stage = 'stage the change';
   git(['add', '--', RELATIVE]);
 
-  let hasDiff = false;
+  // Ask git WHAT it staged, not merely WHETHER something changed — same subprocess, strictly
+  // more information. Deriving "this is a removal" from whether the path still exists was
+  // wrong for a directory: deleting ONE file inside it, or deleting every tracked file while
+  // an ignored one keeps the directory present, would have been committed as an update and
+  // defeated the very search this feature promises.
+  let staged = '';
   try {
-    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+    staged = String(git(['diff', '--cached', '--name-status', '--', RELATIVE]) || '').trim();
   } catch {
-    hasDiff = true;
+    // No HEAD yet (an unborn repository): there is no history to record a removal against.
+    staged = '';
   }
+  const deleted = staged.split('\n').some((l) => /^D/.test(l.trim()));
+  const hasDiff = staged.length > 0;
 
   if (hasDiff) {
-    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(plan): auto-save']);
+    // -m BEFORE the `--`: everything after `--` is a PATHSPEC, so the old order made git
+    // look for files literally named '-m' and 'docs(plan): auto-save' — it failed every
+    // time, from every directory, and this hook exits 0 on failure, so nobody saw it.
+    stage = 'commit';
+    // A deletion gets its own subject, so the event is findable in `git log` without
+    // reading diffs — which is the whole point of recording it.
+    git(['commit', '-m', deleted ? 'docs(plan): auto-remove' : 'docs(plan): auto-save', '--only', '--', RELATIVE]);
   }
-} catch (_err) {
+} catch (err) {
+  // Best-effort — never break the Claude session on commit failures. But "not breaking the session"
+  // and "saying nothing" are different things, and only the first one is the contract: it is about
+  // the EXIT CODE. Silence is what let a permanent defect live here undetected — `-m` after `--`
+  // made every commit fail, from every directory, forever, and nothing said so.
+  //
+  // A held index.lock, a missing user.email, a repository pre-commit hook that rejected the commit,
+  // an ignored target: each now costs one line and still exits 0. The ordinary "nothing to commit"
+  // path never reaches here, deliberately — a notice that fires when nothing is wrong trains people
+  // to ignore notices, and the next real failure scrolls past with them.
+  const artifactName = 'docs/plans/';
+  const gitSaid = err && err.stderr ? String(err.stderr).trim() : '';
+  const detail = (gitSaid || String((err && err.message) || err)).split('\n')
+    .map((l) => l.trim()).filter(Boolean)[0] || 'unknown error';
+  process.stdout.write('[autocommit-plans] could not ' + stage + ' — ' + artifactName + ': '
+    + detail.slice(0, 200) + '\n');
   process.exit(0);
 }