@dzhechkov/p-replicator 1.6.0 → 1.10.0

package/src/utils.js

@@ -94,6 +94,30 @@ function copyDirFiltered(src, dest, filterFn) {
 /**
  * Returns true if the path exists.
  */
+/**
+ * Three states, because two were not enough.
+ *
+ * `fileExists` answers about PRESENCE and is deliberately left alone — it has 31 call sites, several
+ * of which ask a genuine presence question about files that may legitimately hold nothing. This is
+ * the predicate for the different question: is this artifact USABLE?
+ *
+ * MEASURED 2026-08-27: 31 artifacts truncated to zero bytes — every SKILL.md, command, rule and
+ * agent — and both `verify` and `doctor` reported clean with exit 0. Deleting one was caught. The
+ * gap was exactly this: accessSync asks whether the path resolves, never what is in it.
+ *
+ * Whitespace counts as empty. A file holding a newline is exactly as dead as one holding nothing,
+ * and a size check alone would pass it.
+ */
+function artifactState(filePath) {
+  let body;
+  try {
+    body = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return 'missing';
+  }
+  return body.trim().length === 0 ? 'empty' : 'present';
+}
+
 function fileExists(filePath) {
   try {
     fs.accessSync(filePath);
@@ -334,6 +358,8 @@ const COMPONENTS = {
       '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) ───────────
@@ -522,6 +548,7 @@ function getItemRelativePath(comp, itemKey) {
 // ===========================================================================
 
 module.exports = {
+  artifactState,
   // Colors
   green, red, yellow, blue, cyan, bold, dim, gray,
 

package/templates/.claude/commands/myinsights.md

@@ -1,5 +1,5 @@
 ---
-description: Capture and recall development insights. Append a new insight to `.claude/insights/index.md` with structured fields (problem, solution, tags). Auto-injected into context on SessionStart for relevant tasks.
+description: Capture and recall development insights. Append a new insight to `.claude/insights/index.md` with structured fields (problem, solution, tags). The three most recent are injected into context at SessionStart.
 argument-hint: '[recall <query> | <free-form insight>]'
 ---
 
@@ -8,9 +8,24 @@ argument-hint: '[recall <query> | <free-form insight>]'
 ## Purpose
 
 Build a project-local knowledge base of "грабли" (rakes) — errors, workarounds,
-discoveries — so they don't have to be re-learned. Insights are auto-loaded
-into Claude Code context on each session start (via `SessionStart` hook in
-`.claude/settings.json`) when their tags match the current task.
+discoveries — so they don't have to be re-learned.
+
+**What actually happens, stated exactly.** The `SessionStart` hook
+(`.claude/hooks/session-insights.cjs`, wired in `.claude/settings.json`) reads
+`.claude/insights/index.md` and injects the **three most recent entries**, by their
+order in the file. It prints them under the heading *"Recent project insights"* —
+which is what they are.
+
+**There is no tag matching, and it is not an omission.** The hook fires at
+`SessionStart`, BEFORE you have said anything, so there is no current task to match
+tags against. Tags remain useful for a human reading or grepping the file, and for
+`/myinsights recall <query>`, which searches on demand — when a query exists.
+
+**The consequence, so nobody is surprised by it.** The file is append-only and the
+hook takes the LAST three. As a project accumulates entries — `insights-capture.md`
+plans for 50+ — earlier ones stop being injected. Selection by relevance would need
+to happen at a moment when a task is known; that is a separate design question, and
+it is filed rather than quietly implied here.
 
 ## Modes
 
@@ -69,4 +84,6 @@ mistakes without manual recall.
 
 - `.claude/rules/insights-capture.md` — when/how to capture
 - `.claude/hooks/session-insights.cjs` — session injection
-- `/harvest` — extracts reusable patterns from insights at project end
+- `/harvest` — extracts reusable knowledge at project end. **Honest limit:** it does
+  NOT read `.claude/insights/index.md` today (`grep -ci insight` over `harvest.md`
+  returns 0). The capture→harvest link is a stated intention, not a wired path.

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

@@ -181,7 +181,22 @@ 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:** Product Discovery Brief → passed as pre-filled context to Phase 1
+**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:**
 ```
@@ -253,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.

package/templates/.claude/hooks/check-docs-complete.cjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * check-docs-complete.cjs — the cheap question, asked before the expensive one.
+ *
+ * Phase 2 of /replicate launches a SWARM of validation agents over whatever Phase 1 produced. Between
+ * the two there was nothing: existence, emptiness and unfilled placeholders are decidable by this
+ * script, and sending a multi-agent swarm to discover them is a layer-1 check living at layer 3.
+ *
+ * NOT an event hook, like `state-update.cjs`, `check-ports.cjs` and `check-growth-trace.cjs`. This
+ * package's hooks are NON-BLOCKING by contract, so a hook could print but never refuse. Invoke it:
+ *
+ *   node .claude/hooks/check-docs-complete.cjs [path-to-project]
+ *
+ * Exit codes:
+ *   0  every required document exists, has content, and carries no unfilled placeholder
+ *   1  a NAMED document is missing, empty, or still a template
+ *   2  THE CHECK DID NOT RUN — no docs/ directory, or it could not be read
+ *
+ * Honest limit, and it is printed on the passing path: this proves the documents were WRITTEN, not
+ * that they are correct. Correctness is what the Phase-2 swarm is for; this only stops the swarm
+ * being spent discovering an empty file.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** What Phase 1 writes. `optional: true` mirrors replicate.md's own `(if applicable)`. */
+const DOCS = [
+  { file: 'PRD.md' },
+  { file: 'Solution_Strategy.md' },
+  { file: 'Specification.md' },
+  { file: 'Pseudocode.md' },
+  { file: 'Architecture.md' },
+  { file: 'Refinement.md' },
+  { file: 'Completion.md' },
+  { file: 'Research_Findings.md' },
+  // REPORTED, not required. MEASURED 2026-08-27 against a real completed /replicate project:
+  // 8 of 9 promised documents were produced and this one was NOT, though replicate.md and
+  // sparc-prd-mini both promise it (three places, including a whole SYNTHESIS phase). One project
+  // is not enough evidence to decide whether the pipeline is broken or the document is optional in
+  // practice — and blocking on it would have refused every project that ran like that one.
+  // The discrepancy is filed; until it is settled this reports rather than refuses.
+  { file: 'Final_Summary.md', optional: true, expected: true },
+  { file: 'C4_Diagrams.md', optional: true },
+  { file: 'ADR.md', optional: true },
+];
+
+/** Below this a document has a heading and nothing under it. */
+const MIN_CHARS = 200;
+
+function say(s) { process.stdout.write(s + '\n'); }
+
+function cannotCheck(reason, hint) {
+  say('⚠️  проверка НЕ выполнена: ' + reason);
+  if (hint) say('    ' + hint);
+  process.exit(2);
+}
+
+/**
+ * Unfilled placeholders — and the reason this is split into two confidence levels.
+ *
+ * The first version used one rule: a bracketed token not followed by `(`. Cross-family review
+ * destroyed it with two inputs, both REPRODUCED before this rewrite:
+ *
+ *   1. `A[Web App]` — a mermaid node. The BUNDLED sparc-prd-mini skill REQUIRES mermaid diagrams in
+ *      Architecture.md (SKILL.md:570-583), so the gate blocked every normally generated project.
+ *   2. `[GAP: needs performance targets]` — which Phase 1 writes DELIBERATELY in --from-docs mode for
+ *      Phase 2 to resolve (replicate.md:82-94). Blocking on it deadlocks the documented flow: the
+ *      only step that can clear the marker is the one the gate refuses to start.
+ *
+ * The lesson is about CONFIDENCE, not about patterns. A false block here stops the whole pipeline,
+ * which is worse than a missed placeholder the Phase-2 swarm would have caught anyway. So:
+ *
+ *   BLOCKING  — shapes that cannot be anything else: `{{…}}`, TODO/TBD/XXX/FIXME.
+ *   WARNING   — bracketed prose. Reported by name, never blocking, because this script cannot tell
+ *               `[описание продукта]` from a diagram label or a citation without understanding the
+ *               document, and guessing wrong costs more than staying quiet.
+ */
+
+/** Fenced code blocks hold mermaid, arrays and code — none of it prose, none of it ours to judge. */
+function stripFences(body) {
+  return body.replace(/^```[\s\S]*?^```/gm, '').replace(/`[^`\n]*`/g, '');
+}
+
+const BLOCKING = [
+  { re: /\{\{[^}\n]{1,80}\}\}/g, what: 'незаполненный {{шаблон}}' },
+  { re: /(?<![\p{L}\p{N}])(TODO|TBD|XXX|FIXME)(?![\p{L}\p{N}])/giu, what: 'маркер TODO/TBD/XXX' },
+];
+
+/** A structured marker Phase 2 OWNS. It must reach Phase 2, so it is never a finding here. */
+const GAP = /\[GAP:[^\]\n]*\]/g;
+
+const SUSPECT = /\[[^\]\n]{1,80}\](?![(\[])/g;
+
+/**
+ * A markdown TASK-LIST CHECKBOX is not a placeholder.
+ *
+ * MEASURED 2026-08-27 against a real project: `- [ ] AC покрыты автотестами` and 16 siblings were
+ * reported as "possibly unfilled". Worse, that project's own Completion.md TEACHES the convention —
+ * "флажки `[ ]` при каждом FR-GROWTH-00N" — so this warning fired on the notation the pipeline
+ * itself prescribes. Noise on a legitimate convention trains people to ignore warnings, which is
+ * the failure this whole checker exists to prevent, one level down.
+ */
+const CHECKBOX = /^\s*(?:[-*+]\s+)?\[[ xX]?\]/;
+
+function scan(body) {
+  const clean = stripFences(body).replace(GAP, '');
+  const blocking = [];
+  for (const { re, what } of BLOCKING) {
+    re.lastIndex = 0;
+    for (let m = re.exec(clean); m !== null && blocking.length < 3; m = re.exec(clean)) {
+      blocking.push(what + ' «' + m[0].slice(0, 40) + '»');
+    }
+  }
+  const warn = [];
+  // Line-wise, so a checkbox can be recognised by its POSITION in the line — `[ ]` anywhere else
+  // is not a task item. A table cell holding `| [ ] |` counts too: the same convention, in a table.
+  for (const line of clean.split('\n')) {
+    if (warn.length >= 3) break;
+    // STRIP the checkbox, do not skip the LINE. Skipping it would be an escape hatch: a genuine
+    // placeholder could hide behind a checkbox prefix, which is exactly what the test found when
+    // the first version skipped whole lines.
+    const rest = line.replace(CHECKBOX, '').replace(/\|\s*\[[ xX]?\]\s*\|/g, '| |');
+    SUSPECT.lastIndex = 0;
+    for (let m = SUSPECT.exec(rest); m !== null && warn.length < 3; m = SUSPECT.exec(rest)) {
+      const t = m[0];
+      if (/^\[\^?\d+\]$/.test(t)) continue;        // a citation or footnote
+      if (/^\[[ xX]?\]$/.test(t)) continue;          // a bare checkbox mid-line
+      warn.push(t.slice(0, 40));
+    }
+  }
+  return { blocking, warn };
+}
+
+function main() {
+  const root = process.argv[2] || '.';
+  const docs = path.join(root, 'docs');
+  let st;
+  try { st = fs.statSync(docs); } catch {
+    cannotCheck('нет каталога ' + docs,
+      'Фаза 1 ещё не отработала — это НЕ «документы неполны», это «проверять нечего»');
+  }
+  if (!st.isDirectory()) cannotCheck(docs + ' существует, но это не каталог');
+
+  const problems = [];
+  const warnings = [];
+  let checked = 0;
+
+  for (const d of DOCS) {
+    const abs = path.join(docs, d.file);
+    let body;
+    try { body = fs.readFileSync(abs, 'utf-8'); } catch (e) {
+      if (e && e.code === 'ENOENT') {
+        if (!d.optional) problems.push(d.file + ': отсутствует');
+        else if (d.expected) warnings.push(d.file + ': отсутствует, хотя конвейер его обещает');
+        continue;                                  // an optional absence is a legitimate answer
+      }
+      cannotCheck('не читается ' + d.file + ': ' + ((e && e.message) || e));
+    }
+    checked++;
+    if (body.trim().length < MIN_CHARS) {
+      problems.push(d.file + ': пуст или почти пуст (' + body.trim().length + ' симв., порог '
+        + MIN_CHARS + ')');
+      continue;
+    }
+    const { blocking, warn } = scan(body);
+    if (blocking.length) problems.push(d.file + ': остались ' + blocking.join(', '));
+    if (warn.length) warnings.push(d.file + ': возможно незаполнено — ' + warn.join(', '));
+  }
+
+  if (!checked) {
+    cannotCheck('в ' + docs + ' не нашлось ни одного SPARC-документа',
+      'каталог есть, но пуст — это не «всё в порядке»');
+  }
+
+  const sayWarnings = () => {
+    if (!warnings.length) return;
+    say('⚠️  на глаз (НЕ блокирует — скрипт не отличает шаблон от подписи к диаграмме):');
+    for (const w of warnings) say('   • ' + w);
+  };
+
+  if (problems.length) {
+    sayWarnings();
+    say('❌ документы Фазы 1 не готовы к валидации (' + problems.length + '):');
+    for (const p of problems) say('   • ' + p);
+    say('   Рой валидации запускать рано: он потратит агентов на то, что видно отсюда.');
+    process.exit(1);
+  }
+
+  sayWarnings();
+  say('✅ все обязательные документы на месте, непусты и без незаполненных шаблонов ('
+    + checked + ' проверено)');
+  say('   Ограничение: это доказывает, что документы НАПИСАНЫ, а не что они верны.');
+  say('   Верность — работа роя валидации Фазы 2; проверка лишь не даёт потратить его впустую.');
+  process.exit(0);
+}
+
+try { main(); } catch (err) {
+  cannotCheck('внутренняя ошибка проверки: ' + String((err && err.message) || err));
+}

package/templates/.claude/hooks/check-growth-trace.cjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * check-growth-trace.cjs — did the M5 growth analysis survive into the Specification, or was it
+ * analysed and dropped?
+ *
+ * NOT an event hook. Like `state-update.cjs` and `check-ports.cjs`, it lives here because this
+ * directory already carries plain Node utilities; nothing registers it in settings.json. This is
+ * deliberate and load-bearing: this package's hooks are NON-BLOCKING by contract (pinned by
+ * tests/unit/hooks-project-anchored.test.js, which requires exit 0), so a hook could never refuse
+ * anything — it could only print. Invoke it:
+ *
+ *   node .claude/hooks/check-growth-trace.cjs [path-to-project]
+ *
+ * Exit codes — three, and the third is the point:
+ *   0  every seed row is traced into docs/Specification.md, or rejected on the record
+ *   1  the seed table carries rows and the Specification traces none of them
+ *   2  THE CHECK DID NOT RUN — no brief, no Specification, or a seed table that would not parse
+ *
+ * A checker that answers "clean" when it could not look converts an unknown into a reassurance.
+ * An ABSENT brief means Phase 0 never ran (the --from-docs entry skips it); that is exit 2, never 0
+ * and never 1. "Phase 0 did not run" is not "nothing is missing".
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BRIEF = path.join('docs', 'product-discovery-brief.md');
+const SPEC = path.join('docs', 'Specification.md');
+
+/** The exact token, case-sensitive. Not a title, not a paraphrase — the same definition the
+ *  validator's prose gate uses, so the two cannot disagree about what a mention is. */
+const ID = /\bFR-GROWTH-(\d{3})\b/g;
+
+/** A line that refuses an obligation. Shared by mentioned() and rejected() so the two rules cannot
+ *  disagree about what a refusal looks like. */
+const REJECT_WORD = /(отклон\w*|не берём|не беремся|не берем|rejected|declined|out of scope|вне области)/i;
+
+function say(s) { process.stdout.write(s + '\n'); }
+
+/** Exit 2 with a reason. Never merged with "clean": not-run and not-violated are different facts. */
+function cannotCheck(reason, hint) {
+  say('⚠️  проверка НЕ выполнена: ' + reason);
+  if (hint) say('    ' + hint);
+  process.exit(2);
+}
+
+/**
+ * Read one required file. Asks about the EXACT path — never lists a directory and matches names
+ * against the listing, because a listing answers a different question than "does this file exist"
+ * and the two diverge on case, symlinks and unicode normalisation.
+ */
+function readRequired(root, rel, absentReason, hint) {
+  const abs = path.join(root, rel);
+  let st;
+  try { st = fs.statSync(abs); } catch { cannotCheck(absentReason, hint); }
+  if (!st.isFile()) cannotCheck(rel + ' существует, но это не файл');
+  try { return fs.readFileSync(abs, 'utf-8'); } catch (e) {
+    cannotCheck('не читается ' + rel + ': ' + ((e && e.message) || e));
+  }
+  return '';
+}
+
+/**
+ * The seed rows, as the brief records them.
+ *
+ * A row is a markdown table row whose FIRST cell is an id. The template ships an example row with
+ * a placeholder id inside the module, so a row whose requirement cell is still a bracketed
+ * placeholder is a TEMPLATE row, not a real obligation, and counting it would let an untouched
+ * template look like a filled-in one.
+ */
+function seedRows(brief) {
+  const rows = [];
+  for (const raw of brief.split('\n')) {
+    const line = raw.trim();
+    if (!line.startsWith('|')) continue;
+    const cells = line.split('|').map((c) => c.trim());
+    // cells[0] is '' for a leading pipe; the id lives in cells[1]
+    const m = /^FR-GROWTH-(\d{3})$/.exec(cells[1] || '');
+    if (!m) continue;
+    const requirement = cells[2] || '';
+    const isPlaceholder = /^\[.*\]$/.test(requirement) || requirement === '...' || requirement === '';
+    if (isPlaceholder) continue;
+    const status = (cells[5] || cells[4] || '').toUpperCase();
+    rows.push({ id: cells[1], speculative: status.includes('SPECULATIVE') });
+  }
+  return rows;
+}
+
+/**
+ * Ids the Specification mentions, by the same definition the validator's prose gate uses.
+ *
+ * A REJECTION LINE IS NOT A MENTION. The two rules overlap on exactly the case that matters: a line
+ * reading `FR-GROWTH-001 rejected` contains the exact token, so a naive mention rule reports the
+ * obligation as carried forward — and the reason requirement on the rejection path is never reached.
+ * MEASURED before this fix: that line exited 0. Cross-family review found the reason-check hole; the
+ * hole was one layer deeper, in which of the two rules got to answer first.
+ */
+function mentioned(spec) {
+  const out = new Set();
+  for (const line of spec.split('\n')) {
+    if (REJECT_WORD.test(line)) continue;   // a refusal is decided by rejected(), which wants a reason
+    ID.lastIndex = 0;
+    for (let m = ID.exec(line); m !== null; m = ID.exec(line)) out.add(m[0]);
+  }
+  return out;
+}
+
+/**
+ * A row may also be REJECTED on the record instead of traced — the validator's prose gate says the
+ * same. A rejection is a line naming the id together with a rejection word AND a reason marker,
+ * because "FR-GROWTH-004 не берём" with nothing after it is indistinguishable from forgetting.
+ */
+function rejected(brief, spec, id) {
+  const re = new RegExp('^.*\\b' + id + '\\b.*$', 'gm');
+  for (const hay of [brief, spec]) {
+    for (const line of hay.match(re) || []) {
+      const m = REJECT_WORD.exec(line);
+      if (!m) continue;
+      // The reason must live AFTER the rejection word. Scanning the whole line was a false-clean:
+      // cross-family review found that `FR-GROWTH-001 rejected` passed, because the reason pattern
+      // included a bare hyphen and the IDENTIFIER contains two of them. MEASURED before the fix —
+      // that exact line exited 0. So: look only at the tail, and never at punctuation alone.
+      const tail = line.slice(m.index + m[0].length);
+      // A reason is WORDS, not a dash. A separator may introduce it but can never be it.
+      const hasReason = /[\p{L}\p{N}][\p{L}\p{N}\s]{6,}/u.test(tail.replace(/^[\s:—–-]+/, ''));
+      if (hasReason) return true;
+    }
+  }
+  return false;
+}
+
+function main() {
+  const root = process.argv[2] || '.';
+  try { if (!fs.statSync(root).isDirectory()) cannotCheck('это не каталог: ' + root); }
+  catch { cannotCheck('путь не существует: ' + root); }
+
+  const brief = readRequired(root, BRIEF,
+    'нет файла ' + BRIEF,
+    'это значит, что Фаза 0 не запускалась (вход --from-docs её пропускает) — а НЕ что требований по росту не нужно');
+
+  const rows = seedRows(brief);
+
+  // A REUSED id makes the brief malformed, and malformed is exit 2 — never a pass. The module's own
+  // rule is that a number is never reused; when it is, two distinct obligations share one token and
+  // a SINGLE mention in the Specification marks BOTH traced. Cross-family review found this, and it
+  // is the recurring shape: coverage counted over usable ITEMS instead of per POSITION.
+  const dupes = [...new Set(rows.map((r) => r.id).filter((id, i, a) => a.indexOf(id) !== i))];
+  if (dupes.length) {
+    cannotCheck('в таблице-семени повторяются идентификаторы: ' + dupes.join(', '),
+      'номер FR-GROWTH-nnn не переиспользуется — пока дубли не разведены, одно упоминание в '
+      + 'Specification.md зачло бы сразу два разных требования');
+  }
+
+  if (!rows.length) {
+    // An empty seed is a legitimate answer ("нет"), but it is not this checker's business: there is
+    // nothing to trace. Saying "clean" here would claim a check that did not happen.
+    cannotCheck('в брифе нет ни одной заполненной строки FR-GROWTH-nnn',
+      'либо M5 не запускался, либо таблица-семя осталась шаблоном — проверять нечего');
+  }
+
+  const spec = readRequired(root, SPEC, 'нет файла ' + SPEC,
+    'без спецификации не с чем сверять — это не «всё прослежено»');
+
+  const seen = mentioned(spec);
+  const missing = rows.filter((r) => !seen.has(r.id) && !rejected(brief, spec, r.id));
+
+  if (missing.length === rows.length) {
+    say('❌ ни одно требование по росту не доехало до ' + SPEC + ':');
+    for (const r of missing) say('   • ' + r.id + (r.speculative ? ' (SPECULATIVE)' : ''));
+    say('   Разбор роста сделан и выброшен — это ровно тот класс потерь, который ловит проверка.');
+    process.exit(1);
+  }
+  if (missing.length) {
+    say('❌ часть требований по росту потеряна (' + missing.length + ' из ' + rows.length + '):');
+    for (const r of missing) say('   • ' + r.id + (r.speculative ? ' (SPECULATIVE)' : ''));
+    say('   Каждое надо либо перенести в ' + SPEC + ', либо отклонить С ПРИЧИНОЙ — молча уронить нельзя.');
+    process.exit(1);
+  }
+  say('✅ все ' + rows.length + ' требований по росту прослежены в ' + SPEC + ' либо отклонены с причиной');
+  say('   Ограничение: это доказывает, что обязательство ДОНЕСЛИ, а не что его построили.');
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  // Even an unexpected failure must not read as "clean".
+  cannotCheck('внутренняя ошибка проверки: ' + String((err && err.message) || err));
+}

package/templates/.claude/hooks/check-ports.cjs

@@ -59,8 +59,19 @@ function cannotCheck(reason, hint) {
   process.exit(2);
 }
 
+/**
+ * Absolutise ONCE, at the boundary.
+ *
+ * The invariant this restores: one frame of reference per path. A relative `-f` handed to a
+ * subprocess whose cwd we also override is resolved TWICE against two different origins, and the
+ * directory component appears twice. Keeping the argument relative past this point is what made
+ * `check-ports.cjs projects/01` report `.../projects/01/projects/01/docker-compose.yml`.
+ *
+ * Absolute from here on means the existence checks, the `-f` argument and the printed cure all name
+ * the same object — so the cure REPRODUCES the failure instead of refuting it.
+ */
 function resolveCompose(arg) {
-  const target = arg || '.';
+  const target = path.resolve(process.cwd(), arg || '.');
   let file = target;
   try {
     if (fs.statSync(target).isDirectory()) file = path.join(target, 'docker-compose.yml');
@@ -74,16 +85,37 @@ function resolveCompose(arg) {
 /** The normalised config. Parsing the raw YAML would re-implement `extends`, interpolation and the
  *  short `"5432:5432"` form — and the short form is exactly where a hand parser gets host_ip wrong. */
 function normalisedConfig(file) {
-  const r = spawnSync('docker', ['compose', '-f', file, 'config'],
-    { encoding: 'utf8', cwd: path.dirname(path.resolve(file)) });
+  // NO cwd override — deliberately, and the deletion is the fix rather than a tidy-up.
+  //
+  // It used to be `cwd: path.dirname(path.resolve(file))`, which is how the doubling happened: `-f`
+  // was relative and got re-resolved against the cwd this very option installed. Absolutising `file`
+  // alone would have made the line harmless while leaving the false premise that compose needs its
+  // cwd set — and the next relative path added here would reopen the class.
+  //
+  // MEASURED (Compose v5.1.1), same absolute -f from two different cwds, byte-identical output:
+  //   project name        -> from the file's directory, not cwd
+  //   build: ./app        -> context resolved under the file's directory
+  //   .env discovery      -> the project-dir .env won; the cwd's .env was NOT even a fallback
+  //   env_file: ./x.env   -> compose still demanded the project-dir copy
+  // All three candidate justifications are project-directory-derived, and the project directory
+  // comes from the -f path. Scoped honestly: this is Compose v2+ semantics; v1 differed.
+  const r = spawnSync('docker', ['compose', '-f', file, 'config'], { encoding: 'utf8' });
   if (r.error && r.error.code === 'ENOENT') {
     cannotCheck('docker недоступен на этой машине',
       'без него нормализованный конфиг получить нечем, а разбирать YAML руками — значит ошибиться на короткой форме портов');
   }
   if (r.status !== 0) {
+    // Report, do not guess. The old hint said "обычно это незаданная переменная" — a cause that
+    // CANNOT produce this exit: a plain unset ${VAR} makes `docker compose config` exit 0 with a
+    // warning; only the required form ${VAR:?msg} exits 1. It named a subset of an already-narrow
+    // class while the actual cause was this checker's own invocation.
+    //
+    // And the cure now carries the ABSOLUTE path actually passed. It used to print the relative form
+    // without the cwd override — i.e. the invocation that SUCCEEDS — so the tool handed the user a
+    // reproducer that refuted it.
     const why = String(r.stderr || '').trim().split('\n')[0] || 'причина неизвестна';
     cannotCheck('docker compose config вернул ошибку: ' + why,
-      'обычно это незаданная переменная; посмотреть: docker compose -f ' + file + ' config');
+      'повторить ровно то, что делали мы: docker compose -f ' + file + ' config');
   }
   return String(r.stdout || '');
 }