@dzhechkov/p-replicator 1.9.0 → 1.10.0

package/src/commands/verify.js

@@ -4,7 +4,7 @@ const path = require('path');
 const {
   green, red, yellow, cyan, bold, dim,
   info, success, error: logError,
-  readManifest, fileExists,
+  readManifest, fileExists, artifactState,
   COMPONENTS, getItemRelativePath,
 } = require('../utils');
 
@@ -44,8 +44,14 @@ function run(options) {
       const label = groupKey === 'commands'
         ? `/${itemKey}`
         : `${groupKey}: ${itemKey}`;
-      if (fileExists(full)) {
+      const state = artifactState(full);
+      if (state === 'present') {
         pass(`${label} ${dim('— ' + desc)}`);
+      } else if (state === 'empty') {
+        // NOT "missing". The cures differ: missing -> run `update`; empty -> something truncated
+        // your file, and `update` would silently repair it without you ever learning that. Naming
+        // both "missing" moves the silence up one level instead of removing it.
+        fail(`${label} — EMPTY, cannot load (${rel})`);
       } else {
         fail(`${label} — missing (${rel})`);
       }
@@ -91,6 +97,25 @@ function run(options) {
   console.log('');
 
   // ── Summary ─────────────────────────────────────────────────────────────
+  // The insights carrier: three states, none of them failing.
+  //
+  // FR-5 asks for three SURFACES, and the first pass shipped two — doctor and the statusline —
+  // leaving verify producing identical output for absent, empty and populated. Cross-family review
+  // caught it. A carrier that never existed must not read like one being used and found empty:
+  // that indistinguishability is what let 27 recorded insights become 0 across four real projects.
+  const insightsIndex = path.join(targetDir, '.claude', 'insights', 'index.md');
+  const insightsState = artifactState(insightsIndex);
+  if (insightsState === 'missing') {
+    hint('insights carrier: NOT STARTED — no .claude/insights/index.md. Record one with /myinsights');
+  } else if (insightsState === 'empty') {
+    hint('insights carrier: EXISTS but holds ZERO entries — nothing is injected at SessionStart');
+  } else {
+    const entries = (require('fs').readFileSync(insightsIndex, 'utf-8')
+      .match(/^##\s+\d{4}-\d{2}-\d{2}/gm) || []).length;
+    pass(`insights carrier: ${entries} entr${entries === 1 ? 'y' : 'ies'} recorded`);
+  }
+  console.log('');
+
   console.log(bold('─'.repeat(60)));
   if (issues === 0 && warnings === 0) {
     success(bold('All artifacts verified.'));

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);
@@ -524,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/hooks/check-docs-complete.cjs

@@ -36,7 +36,13 @@ const DOCS = [
   { file: 'Refinement.md' },
   { file: 'Completion.md' },
   { file: 'Research_Findings.md' },
-  { file: 'Final_Summary.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 },
 ];
@@ -88,6 +94,17 @@ 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 = [];
@@ -98,11 +115,21 @@ function scan(body) {
     }
   }
   const warn = [];
-  SUSPECT.lastIndex = 0;
-  for (let m = SUSPECT.exec(clean); m !== null && warn.length < 3; m = SUSPECT.exec(clean)) {
-    const t = m[0];
-    if (/^\[\^?\d+\]$/.test(t)) continue;          // a citation or footnote, not a placeholder
-    warn.push(t.slice(0, 40));
+  // 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 };
 }
@@ -127,6 +154,7 @@ function main() {
     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));

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 || '');
 }

package/templates/.claude/hooks/statusline.cjs

@@ -198,10 +198,19 @@ function parsePlans() {
   return safeListDir(dir).filter((f) => f.endsWith('.md')).length;
 }
 
+/**
+ * THREE states, because two were not enough.
+ *
+ * `{count:0}` was returned both for a carrier that does not exist and for one that exists and holds
+ * nothing — so a project that had never recorded an insight rendered identically to one being used
+ * and found empty. That indistinguishability is what let 27 recorded insights become 0 across four
+ * real projects without any surface saying so (MEASURED 2026-08-27).
+ */
 function parseInsights() {
   const p = path.join(CWD, '.claude', 'insights', 'index.md');
   const text = safeReadText(p);
-  if (!text) return { count: 0, lastDate: null };
+  if (text === null || text === undefined) return { count: 0, lastDate: null, started: false };
+  if (!text.trim()) return { count: 0, lastDate: null, started: true };
   const headings = text.match(/^##\s+\d{4}-\d{2}-\d{2}/gm) || [];
   // Last date: extract from last heading
   let lastDate = null;
@@ -210,7 +219,7 @@ function parseInsights() {
     const m = last.match(/\d{4}-\d{2}-\d{2}/);
     if (m) lastDate = m[0];
   }
-  return { count: headings.length, lastDate };
+  return { count: headings.length, lastDate, started: true };
 }
 
 function parseToolkit() {
@@ -467,7 +476,9 @@ function buildToolkit(toolkit, expected) {
 
 function buildStatus(insights, lastTest, mcpServers, settingsStatus, keysarium) {
   const parts = [];
-  parts.push(`💡 ${bold('Insights')} ${insights.count > 0 ? green('●' + insights.count) : '0'}` +
+  // '0' meant two different things: no carrier at all, and a carrier holding nothing. A dash
+  // says the first; a zero says the second. The reader can now tell which one they are looking at.
+  parts.push(`💡 ${bold('Insights')} ${insights.count > 0 ? green('●' + insights.count) : insights.started ? '0' : dim('—')}` +
     (insights.lastDate ? ` ${dim('(' + insights.lastDate + ')')}` : ''));
 
   if (lastTest && typeof lastTest.passed === 'number') {
@@ -498,7 +509,7 @@ function main() {
   const validation = safeRun(() => parseValidationScore(), null);
   const adrs = safeRun(() => parseAdrs(), 0);
   const plans = safeRun(() => parsePlans(), 0);
-  const insights = safeRun(() => parseInsights(), { count: 0, lastDate: null });
+  const insights = safeRun(() => parseInsights(), { count: 0, lastDate: null, started: false });
   const toolkit = safeRun(() => parseToolkit(), { skills: 0, commands: 0, agents: 0, rules: 0, hooks: 0 });
   const expected = parseExpectedToolkit();
   const settingsStatus = safeRun(() => parseSettingsStatus(manifest), null);

package/templates/.claude/skills/brutal-honesty-review/scripts/assess-code.sh

@@ -15,12 +15,34 @@ echo ""
 
 # Check if file argument provided
 if [ -z "$1" ]; then
+    echo "⚠️  check did NOT run: no argument given"
     echo "Usage: $0 <file-or-directory>"
-    exit 1
+    exit 2
 fi
 
 TARGET="$1"
 
+# ── Findings counter ─────────────────────────────────────────────────────────
+#
+# This script DETECTED correctly and could not FAIL. MEASURED 2026-08-27: deliberately awful input
+# produced red verdicts on screen and exit 0, while a nonexistent path exited 1 — "I could not
+# check" was louder than "I found violations", so any gate reading 1 could not tell them apart.
+#
+# Nothing about the detection changed. What was missing is that nobody counted.
+#
+#   0  ran, found nothing
+#   1  ran, found violations — the count is printed
+#   2  COULD NOT CHECK: no argument, or a target that does not exist
+FINDINGS=0
+finding() { FINDINGS=$((FINDINGS + 1)); }
+
+if [ ! -e "$TARGET" ]; then
+    echo "⚠️  check did NOT run: '$TARGET' does not exist"
+    echo "   → This is NOT a clean bill: nothing was examined."
+    exit 2
+fi
+
+
 # Function to assess correctness
 assess_correctness() {
     echo "📊 CORRECTNESS CHECK"
@@ -28,7 +50,7 @@ assess_correctness() {
 
     # Check for common bug patterns
     if grep -r "TODO\|FIXME\|BUG\|HACK" "$TARGET" 2>/dev/null; then
-        echo -e "${RED}🔴 FAILING: Found TODO/FIXME/BUG/HACK comments${NC}"
+        echo -e "${RED}🔴 FAILING: Found TODO/FIXME/BUG/HACK comments${NC}"; finding
         echo "   → This code admits it's broken. Fix it before review."
         return 0
     fi
@@ -51,14 +73,14 @@ assess_performance() {
     # Check for nested loops (potential O(n²))
     nested_loops=$(grep -r "for.*{" "$TARGET" | wc -l)
     if [ "$nested_loops" -gt 5 ]; then
-        echo -e "${RED}🔴 FAILING: Found $nested_loops loops${NC}"
+        echo -e "${RED}🔴 FAILING: Found $nested_loops loops${NC}"; finding
         echo "   → Are you creating O(n²) complexity where O(n) exists?"
         echo "   → Use hash maps, sets, or better algorithms."
     fi
 
     # Check for synchronous I/O in hot paths
     if grep -r "readFileSync\|writeFileSync" "$TARGET" 2>/dev/null; then
-        echo -e "${RED}🔴 FAILING: Synchronous file I/O detected${NC}"
+        echo -e "${RED}🔴 FAILING: Synchronous file I/O detected${NC}"; finding
         echo "   → You're blocking the event loop. Use async operations."
     fi
 
@@ -74,7 +96,7 @@ assess_error_handling() {
     # Check for try/catch usage
     try_count=$(grep -r "try\|catch" "$TARGET" 2>/dev/null | wc -l)
     if [ "$try_count" -eq 0 ]; then
-        echo -e "${RED}🔴 FAILING: No error handling found${NC}"
+        echo -e "${RED}🔴 FAILING: No error handling found${NC}"; finding
         echo "   → What happens when this code fails? It crashes."
     else
         echo -e "${GREEN}✓ Found error handling (verify it's sufficient)${NC}"
@@ -82,7 +104,7 @@ assess_error_handling() {
 
     # Check for empty catch blocks
     if grep -A 1 "catch" "$TARGET" 2>/dev/null | grep -q "^\s*}"; then
-        echo -e "${RED}🔴 FAILING: Empty catch blocks detected${NC}"
+        echo -e "${RED}🔴 FAILING: Empty catch blocks detected${NC}"; finding
         echo "   → Swallowing errors silently is worse than crashing."
     fi
 }
@@ -118,7 +140,7 @@ assess_testability() {
     if [ -d "tests" ] || [ -d "test" ] || [ -d "__tests__" ]; then
         echo -e "${GREEN}✓ Test directory exists${NC}"
     else
-        echo -e "${RED}🔴 FAILING: No test directory found${NC}"
+        echo -e "${RED}🔴 FAILING: No test directory found${NC}"; finding
         echo "   → Where are the tests? Did you even test this?"
     fi
 
@@ -177,3 +199,14 @@ echo "  - Tests exist and pass"
 echo "  - Code is clear and maintainable"
 echo ""
 echo "If you wouldn't deploy this to production, don't submit it for review."
+
+# ── Verdict ──────────────────────────────────────────────────────────────────
+# ADDED, never substituted: the closing prose above is this skill's character and a reader wants it.
+# What follows is the same answer in a form a gate can act on.
+echo ""
+if [ "$FINDINGS" -gt 0 ]; then
+    echo "VERDICT: $FINDINGS finding(s). Not ready."
+    exit 1
+fi
+echo "VERDICT: 0 findings."
+exit 0

package/templates/.claude/skills/brutal-honesty-review/scripts/assess-tests.sh

@@ -15,17 +15,33 @@ echo ""
 
 # Check if test directory argument provided
 if [ -z "$1" ]; then
+    echo "⚠️  check did NOT run: no argument given"
     echo "Usage: $0 <test-directory>"
-    exit 1
+    exit 2
 fi
 
 TEST_DIR="$1"
 
+# ── Findings counter ─────────────────────────────────────────────────────────
+#
+# This script DETECTED correctly and could not FAIL. MEASURED 2026-08-27: deliberately awful input
+# produced red verdicts on screen and exit 0, while a nonexistent path exited 1 — "I could not
+# check" was louder than "I found violations", so any gate reading 1 could not tell them apart.
+#
+# Nothing about the detection changed. What was missing is that nobody counted.
+#
+#   0  ran, found nothing
+#   1  ran, found violations — the count is printed
+#   2  COULD NOT CHECK: no argument, or a target that does not exist
+FINDINGS=0
+finding() { FINDINGS=$((FINDINGS + 1)); }
+
+
 # Check if test directory exists
 if [ ! -d "$TEST_DIR" ]; then
-    echo -e "${RED}🔴 FAILING: Test directory '$TEST_DIR' doesn't exist${NC}"
-    echo "   → Where are the tests? Did you even write any?"
-    exit 1
+    echo "⚠️  check did NOT run: test directory '$TEST_DIR' does not exist"
+    echo "   → This is NOT a clean bill: nothing was examined."
+    exit 2
 fi
 
 # Function to assess coverage
@@ -42,7 +58,7 @@ assess_coverage() {
         coverage=$(npm run test:coverage 2>&1 | grep -oP '\d+\.\d+(?=%)' | head -1 || echo "0")
 
         if (( $(echo "$coverage < 50" | bc -l) )); then
-            echo -e "${RED}🔴 RAW: ${coverage}% coverage${NC}"
+            echo -e "${RED}🔴 RAW: ${coverage}% coverage${NC}"; finding
             echo "   → This is embarrassing. You're barely testing anything."
         elif (( $(echo "$coverage < 80" | bc -l) )); then
             echo -e "${YELLOW}🟡 ACCEPTABLE: ${coverage}% coverage${NC}"
@@ -83,7 +99,7 @@ assess_edge_cases() {
     done
 
     if [ "$found_count" -eq 0 ]; then
-        echo -e "${RED}🔴 RAW: No edge cases tested${NC}"
+        echo -e "${RED}🔴 RAW: No edge cases tested${NC}"; finding
         echo "   → You're only testing the happy path. That's not testing."
     elif [ "$found_count" -lt 3 ]; then
         echo -e "${YELLOW}🟡 ACCEPTABLE: Found $found_count edge case patterns${NC}"
@@ -102,7 +118,7 @@ assess_clarity() {
     # Check for descriptive test names
     unclear_tests=$(grep -r "test('test" "$TEST_DIR" 2>/dev/null | wc -l)
     if [ "$unclear_tests" -gt 0 ]; then
-        echo -e "${RED}🔴 RAW: Found $unclear_tests unclear test names${NC}"
+        echo -e "${RED}🔴 RAW: Found $unclear_tests unclear test names${NC}"; finding
         echo "   → 'test1', 'test2' - What are you testing? Use descriptive names."
     fi
 
@@ -129,7 +145,7 @@ assess_speed() {
         duration=$((end_time - start_time))
 
         if [ "$duration" -gt 60 ]; then
-            echo -e "${RED}🔴 RAW: Tests took ${duration}s${NC}"
+            echo -e "${RED}🔴 RAW: Tests took ${duration}s${NC}"; finding
             echo "   → Unit tests should run in seconds, not minutes."
             echo "   → Are you calling real databases/networks?"
         elif [ "$duration" -gt 10 ]; then
@@ -139,7 +155,7 @@ assess_speed() {
             echo -e "${GREEN}🟢 MICHELIN STAR: Tests took ${duration}s${NC}"
         fi
     else
-        echo -e "${RED}🔴 FAILING: Tests don't even pass${NC}"
+        echo -e "${RED}🔴 FAILING: Tests don't even pass${NC}"; finding
         echo "   → Fix your broken tests before worrying about speed."
     fi
 }
@@ -152,7 +168,7 @@ assess_stability() {
 
     # Check for flaky patterns
     if grep -ri "setTimeout\|sleep\|wait" "$TEST_DIR" > /dev/null 2>&1; then
-        echo -e "${RED}🔴 RAW: Timing-based tests detected${NC}"
+        echo -e "${RED}🔴 RAW: Timing-based tests detected${NC}"; finding
         echo "   → You're creating flaky tests. Use proper async/await."
     fi
 
@@ -166,7 +182,7 @@ assess_stability() {
     done
 
     if [ "$failures" -gt 0 ]; then
-        echo -e "${RED}🔴 RAW: Tests failed $failures/3 times${NC}"
+        echo -e "${RED}🔴 RAW: Tests failed $failures/3 times${NC}"; finding
         echo "   → FLAKY TESTS. These are worse than no tests."
         echo "   → Fix the non-determinism before merging."
     else
@@ -221,3 +237,14 @@ echo "  - 0% flaky"
 echo "  - Independent tests"
 echo ""
 echo "You know what good tests look like. Why aren't you writing them?"
+
+# ── Verdict ──────────────────────────────────────────────────────────────────
+# ADDED, never substituted: the closing prose above is this skill's character and a reader wants it.
+# What follows is the same answer in a form a gate can act on.
+echo ""
+if [ "$FINDINGS" -gt 0 ]; then
+    echo "VERDICT: $FINDINGS finding(s). Not ready."
+    exit 1
+fi
+echo "VERDICT: 0 findings."
+exit 0

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/ddd-hooks-commands.md

@@ -70,13 +70,43 @@ Enhanced hooks and commands for DDD-aware Claude Code instruments.
 #!/bin/bash
 # Validates aggregate doesn't exceed size limits
 # Source: Fitness Function FF-02
+#
+# THREE exit codes, and the third is the point:
+#   0  within limits
+#   1  over the limit — the count and the limit are both reported
+#   2  THE CHECK DID NOT RUN — unreadable file, or an unsubstituted threshold
+#
+# A guard that answers "OK" when it could not look turns an unknown into a reassurance. MEASURED
+# before this contract existed: four declarations minified onto ONE line reported OK against a limit
+# of two, a missing file reported OK, and an unsubstituted {{...}} placeholder reported OK FOREVER —
+# `[ 4 -gt "{{MAX_ENTITIES_FROM_FITNESS}}" ]` is an invalid comparison, so the `if` is simply false.
 
 FILE="$1"
 MAX_ENTITIES={{MAX_ENTITIES_FROM_FITNESS}}
 MAX_METHODS={{MAX_METHODS_FROM_FITNESS}}
 
-# Count entities (rough heuristic)
-ENTITY_COUNT=$(grep -c "class.*Entity" "$FILE" 2>/dev/null || echo 0)
+if [ -z "$FILE" ]; then
+    echo "⚠️  check did NOT run: no file given (usage: $0 <file>)"
+    exit 2
+fi
+if [ ! -r "$FILE" ]; then
+    echo "⚠️  check did NOT run: cannot read $FILE"
+    exit 2
+fi
+# An unsubstituted placeholder must REFUSE, not pass. Otherwise a generator that failed to
+# substitute ships a guard that can never say no, and says nothing about it.
+case "$MAX_ENTITIES" in
+    ''|*[!0-9]*)
+        echo "⚠️  check did NOT run: MAX_ENTITIES is not a number ('$MAX_ENTITIES')."
+        echo "    The generator did not substitute {{MAX_ENTITIES_FROM_FITNESS}}."
+        exit 2
+        ;;
+esac
+
+# OCCURRENCES, not lines: `grep -c` counts matching LINES, so four declarations on one line count
+# as one. `|| true` because grep exits 1 when nothing matches, which is a legitimate count of zero.
+ENTITY_COUNT=$(grep -oE "class[A-Za-z0-9_ ]*Entity" "$FILE" | wc -l | tr -d ' ')
+[ -z "$ENTITY_COUNT" ] && ENTITY_COUNT=0
 
 if [ "$ENTITY_COUNT" -gt "$MAX_ENTITIES" ]; then
     echo "❌ VIOLATION: Aggregate has $ENTITY_COUNT entities (max: $MAX_ENTITIES)"
@@ -84,7 +114,7 @@ if [ "$ENTITY_COUNT" -gt "$MAX_ENTITIES" ]; then
     exit 1
 fi
 
-echo "✅ Aggregate size OK"
+echo "✅ Aggregate size OK ($ENTITY_COUNT entities, max $MAX_ENTITIES)"
 exit 0
 ```
 
@@ -114,7 +144,13 @@ if [ "$VIOLATIONS" -gt 0 ]; then
     echo "Found $VIOLATIONS potential DDD violations"
 fi
 
-exit 0  # Warnings only, don't block
+# ADVISORY, by design and stated out loud. This reporter never blocks: it prints what it noticed
+# and exits 0 whatever it found. That is a legitimate shape — but a reader must not mistake a
+# reporter for a gate, so it says so in its OWN OUTPUT rather than only in a comment nobody reads.
+echo ""
+echo "ℹ️  advisory only — this reporter never blocks (exit 0 regardless of findings)."
+echo "    For a check that can refuse, see validate-aggregate-size.sh (exit 0/1/2)."
+exit 0
 ```
 
 ---