@ngockhoale/ukit 3.0.0 → 3.0.2

package/{templates → template_project}/.claude/hooks/handoff-model-guard.sh

@@ -238,7 +238,7 @@ if (toolName === 'Write' || toolName === 'Edit') {
           const specText = await fsp.readFile(specPath, 'utf8');
           let templateText = null;
           try {
-            templateText = await fsp.readFile(path.join(projectRoot, 'templates/docs/AI_HANDOFF/SPEC.md'), 'utf8');
+            templateText = await fsp.readFile(path.join(projectRoot, 'template_project/docs/AI_HANDOFF/SPEC.md'), 'utf8');
           } catch {}
           specOk = specText.length > 500 && specText !== templateText;
         } catch {}

package/{templates → template_project}/.claude/hooks/skill-router.sh

@@ -2235,10 +2235,10 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     /^src\/index\//,
     /^src\/core\/(runInstallPipeline|applyPlan|buildPlan|diffPlan|metadata|migrateLegacy|uninstall|runtimeConfig|runtimePaths)\.js$/,
     /^src\/core\/(output|token|compact)\//,
-    /^templates\/\.claude\/hooks\//,
-    /^templates\/\.claude\/ukit\//,
+    /^template_project\/\.claude\/hooks\//,
+    /^template_project\/\.claude\/ukit\//,
     /^manifests\/platform\.full\.yaml$/,
-    /^templates\//,
+    /^template_project\//,
   ];
 
   function isSharedImpactFile(filePath) {

package/{templates → template_project}/.claude/skills/skill-quality/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-quality
-description: Use when creating or editing a UKit template skill/agent (templates/.claude/skills or templates/.claude/agents), before shipping the change, to pressure-test compliance and trigger accuracy. Maintainer-only.
+description: Use when creating or editing a UKit template skill/agent (template_project/.claude/skills or template_project/.claude/agents), before shipping the change, to pressure-test compliance and trigger accuracy. Maintainer-only.
 ---
 
 # Skill Quality

package/{templates → template_project}/.claude/skills/skill-quality/pressure-scenario-template.md

@@ -10,7 +10,7 @@
 
 ## Worked example — don't copy it here, read the original
 
-Rather than duplicating a worked scenario in this file, reuse the one already written and already run in this repo: `templates/.claude/skills/systematic-debugging/test-pressure-1.md` (economic + authority + time + sunk-cost pressure, A/B/C choice, passed against `systematic-debugging`). Open it directly, swap the skill name and domain details for the skill you're testing. See its sibling `CREATION-LOG.md` → "Bulletproofing Elements" for the language choices (ALWAYS/NEVER, explicit "even if faster") that made the original pass.
+Rather than duplicating a worked scenario in this file, reuse the one already written and already run in this repo: `template_project/.claude/skills/systematic-debugging/test-pressure-1.md` (economic + authority + time + sunk-cost pressure, A/B/C choice, passed against `systematic-debugging`). Open it directly, swap the skill name and domain details for the skill you're testing. See its sibling `CREATION-LOG.md` → "Bulletproofing Elements" for the language choices (ALWAYS/NEVER, explicit "even if faster") that made the original pass.
 
 ## Producing your own scenario (when the worked example doesn't fit the skill's domain)
 

package/template_project/.claude/ukit/index/handoff-doc-validator.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// handoff-doc-validator.mjs — TASK-004 / Cycle C50 (shipped CLI twin)
+//
+// Self-contained twin of src/core/handoffDocValidator.js for user installs (no `src/`).
+// The logic below is a literal port — keep the two files behavior-identical when editing.
+//
+// REAL GATE — unlike task-budget-validator.mjs (advisory, always exit 0), this
+// script exits 1 on any violation. Do not "fix" the exit code.
+//
+// Usage:
+//   node .claude/ukit/index/handoff-doc-validator.mjs <file.md> [file.md...]
+//
+// Kind detection per file: basename PLAN.md → 'plan'; TASK-*.md → 'task';
+// otherwise content sniffing (`## §1` → plan, `## Goal` → task, else
+// executor-report). Task files carrying `## Executor Report` are also checked
+// against the report header contract.
+//
+// Output:
+//   `PASS <file>` when clean; one `FAIL <file>: <rule>` line per violation.
+//   Exit 0 when every file passes, 1 otherwise, 2 on usage/read errors.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+const PLAN_SECTIONS = ['§1', '§2', '§3', '§4', '§5', '§6'];
+
+const TASK_SECTIONS = [
+  'Goal',
+  'Target Files',
+  'Test Cases',
+  'Test Files',
+  'Verification Commands',
+  'Acceptance Criteria',
+  'Dependencies',
+  'Interfaces',
+];
+
+const REPORT_FIELDS = ['EXECUTOR_TOOL', 'EXECUTOR_MODEL', 'EXECUTOR_SUBAGENT', 'RED_OUTPUT'];
+
+// Section helpers. Any line starting with `## ` opens a section; the body runs
+// until the next `## ` line or EOF. Returns [{ name, body, pos }] in file order.
+function splitSections(markdown) {
+  const sections = [];
+  const lines = String(markdown).split('\n');
+  let current = null;
+  lines.forEach((line, idx) => {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      current = { name: m[1], body: '', pos: idx };
+      sections.push(current);
+    } else if (current) {
+      current.body += line + '\n';
+    }
+  });
+  return sections;
+}
+
+// Positions of `## §<n>` headings, keyed by the literal token ('§1'..'§6').
+// A heading matches when its name starts with the token (`## §1 Intent`).
+function planSectionPositions(sections) {
+  const positions = new Map();
+  for (const s of sections) {
+    for (const token of PLAN_SECTIONS) {
+      if (!positions.has(token) && s.name.startsWith(token)) positions.set(token, s.pos);
+    }
+  }
+  return positions;
+}
+
+function hasSection(sections, name) {
+  return sections.some((s) => s.name === name || s.name.startsWith(`${name} `) || s.name.startsWith(`${name}(`));
+}
+
+function getSection(sections, name) {
+  return sections.find((s) => s.name === name || s.name.startsWith(`${name} `) || s.name.startsWith(`${name}(`));
+}
+
+function validatePlan(markdown) {
+  const failures = [];
+  const sections = splitSections(markdown);
+  const positions = planSectionPositions(sections);
+
+  for (const token of PLAN_SECTIONS) {
+    if (!positions.has(token)) failures.push(`missing required section heading "## ${token}"`);
+  }
+
+  // Order check over the sections that exist: each must appear after the
+  // highest position seen so far.
+  let maxPos = -1;
+  for (const token of PLAN_SECTIONS) {
+    const pos = positions.get(token);
+    if (pos === undefined) continue;
+    if (pos < maxPos) {
+      failures.push(`section order violation: "## ${token}" appears after a later section`);
+    } else {
+      maxPos = pos;
+    }
+  }
+
+  const report = getSection(sections, 'Planner Report');
+  if (!report) {
+    failures.push('missing required section "## Planner Report"');
+  } else if (!/^PLANNER_MODEL\s*:/m.test(report.body)) {
+    failures.push('missing required field "PLANNER_MODEL:" inside "## Planner Report"');
+  }
+
+  return failures;
+}
+
+function validateExecutorReportFields(markdown, prefix) {
+  const failures = [];
+  for (const field of REPORT_FIELDS) {
+    if (!new RegExp(`^${field}\\s*:`, 'm').test(markdown)) {
+      failures.push(`${prefix}missing required field "${field}:"`);
+    }
+  }
+  return failures;
+}
+
+function validateTask(markdown) {
+  const failures = [];
+  const sections = splitSections(markdown);
+
+  for (const name of TASK_SECTIONS) {
+    if (!hasSection(sections, name)) failures.push(`missing required section "## ${name}"`);
+  }
+  if (!/^\s*-?\s*Status\s*:/m.test(markdown)) {
+    failures.push('missing required field "Status:"');
+  }
+
+  // A task file that already carries an Executor Report must satisfy the
+  // report header contract too (FR-007).
+  const report = getSection(sections, 'Executor Report');
+  if (report) {
+    failures.push(...validateExecutorReportFields(report.body, 'executor-report: '));
+  }
+
+  return failures;
+}
+
+export function validateHandoffDoc(markdown, kind) {
+  const text = String(markdown ?? '');
+  let failures;
+  if (kind === 'plan') failures = validatePlan(text);
+  else if (kind === 'task') failures = validateTask(text);
+  else if (kind === 'executor-report') failures = validateExecutorReportFields(text, '');
+  else failures = [`unknown kind "${kind}" (expected plan|task|executor-report)`];
+  return { ok: failures.length === 0, failures };
+}
+
+// CLI-only helpers below (not part of the canonical module).
+
+function detectKind(filePath, markdown) {
+  const base = path.basename(filePath);
+  if (/^PLAN\.md$/i.test(base)) return 'plan';
+  if (/^TASK-.*\.md$/i.test(base)) return 'task';
+  if (/^##\s+§1/m.test(markdown)) return 'plan';
+  if (/^##\s+Goal\b/m.test(markdown)) return 'task';
+  return 'executor-report';
+}
+
+function main() {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.error('usage: handoff-doc-validator.mjs <file.md> [file.md...]');
+    process.exit(2);
+  }
+  let failed = false;
+  for (const file of files) {
+    let markdown;
+    try {
+      markdown = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      console.log(`FAIL ${file}: unreadable (${err.message})`);
+      failed = true;
+      continue;
+    }
+    const { ok, failures } = validateHandoffDoc(markdown, detectKind(file, markdown));
+    if (ok) {
+      console.log(`PASS ${file}`);
+    } else {
+      failed = true;
+      for (const f of failures) console.log(`FAIL ${file}: ${f}`);
+    }
+  }
+  process.exit(failed ? 1 : 0);
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main();
+}

package/{templates → template_project}/.claude/ukit/index/lib/index-core.mjs

@@ -4037,56 +4037,56 @@ const IMPACT_SHARED_PATTERNS = [
     label: 'shared-install-runtime',
   },
   { regex: /^src\/core\/(output|token|compact)\//, label: 'shared-token-runtime' },
-  { regex: /^templates\/\.claude\/hooks\//, label: 'installed-hook-runtime' },
-  { regex: /^templates\/\.claude\/ukit\//, label: 'installed-helper-runtime' },
+  { regex: /^template_project\/\.claude\/hooks\//, label: 'installed-hook-runtime' },
+  { regex: /^template_project\/\.claude\/ukit\//, label: 'installed-helper-runtime' },
   { regex: /^manifests\/platform\.full\.yaml$/, label: 'install-manifest' },
-  { regex: /^templates\//, label: 'published-template-surface' },
+  { regex: /^template_project\//, label: 'published-template-surface' },
 ];
 
 const IMPACT_MIRROR_PAIRS = [
   {
     source: 'src/index/buildIndex.js',
-    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    mirror: 'template_project/.claude/ukit/index/lib/index-core.mjs',
     reason: 'installed index-core mirror embeds source index behavior',
   },
   {
     source: 'src/index/queryIndex.js',
-    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    mirror: 'template_project/.claude/ukit/index/lib/index-core.mjs',
     reason: 'installed index-core mirror embeds source query behavior',
   },
   {
     source: 'src/index/resolveContext.js',
-    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    mirror: 'template_project/.claude/ukit/index/lib/index-core.mjs',
     reason: 'installed index-core mirror embeds context resolution behavior',
   },
   {
     source: 'src/index/verificationPlan.js',
-    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    mirror: 'template_project/.claude/ukit/index/lib/index-core.mjs',
     reason: 'installed index-core mirror embeds verification planning behavior',
   },
   {
     source: 'src/index/taskRouting.js',
-    mirror: 'templates/.claude/ukit/index/route-task.mjs',
+    mirror: 'template_project/.claude/ukit/index/route-task.mjs',
     reason: 'installed route-task helper mirrors source task routing behavior',
   },
   {
     source: 'src/index/routeCatalog.js',
-    mirror: 'templates/.claude/ukit/index/route-catalog.mjs',
+    mirror: 'template_project/.claude/ukit/index/route-catalog.mjs',
     reason: 'installed route catalog must match source route catalog',
   },
   {
     source: 'src/core/output/index.js',
-    mirror: 'templates/.claude/ukit/runtime/output-compression.mjs',
+    mirror: 'template_project/.claude/ukit/runtime/output-compression.mjs',
     reason: 'source output compression runtime should stay aligned with installed hook runtime',
   },
   {
     source: 'src/core/token/index.js',
-    mirror: 'templates/.claude/ukit/runtime/token-utils.mjs',
+    mirror: 'template_project/.claude/ukit/runtime/token-utils.mjs',
     reason: 'source token runtime should stay aligned with installed token utilities',
   },
   {
     source: 'src/core/compact/threshold.js',
-    mirror: 'templates/.claude/ukit/runtime/compact-threshold.mjs',
+    mirror: 'template_project/.claude/ukit/runtime/compact-threshold.mjs',
     reason: 'source compact threshold runtime should stay aligned with installed compact threshold hook',
   },
 ];

package/template_project/.claude/ukit/index/review-panel-aggregate.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// review-panel-aggregate.mjs — TASK-004 / Cycle C50 (shipped CLI twin)
+//
+// Self-contained twin of src/core/reviewPanelAggregate.js for user installs (no `src/`).
+// The logic below is a literal port — keep the two files behavior-identical when editing.
+//
+// ADVISORY — always exits 0. Aggregation output feeds the lead reviewer's
+// AGREEMENT_MAP field and the orchestrator's INDEX status update; it must never
+// break a pipeline.
+//
+// Usage:
+//   node .claude/ukit/index/review-panel-aggregate.mjs <TASK-xxx.md> [TASK-xxx.md...]
+//
+// Reads every `## Reviewer Verdict` block from the given task files, then prints:
+//   AGREEMENT_MAP: finding → member, member   (one line per finding)
+//   HIGH_SIGNAL:   finding → member, member   (≥2 members or any critical)
+//   UNPARSED:      <file>#verdict[<i>]         (blocks with no VERDICT line)
+//   VERDICT: approved | approved_minor | changes_requested
+
+import fs from 'node:fs';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+const SEVERITIES = ['critical', 'important', 'minor'];
+
+// Parse one `## Reviewer Verdict` block (format: code-reviewer.md §Output).
+// Returns null when no recognizable VERDICT line exists — the block is then
+// counted as absent and named in `unparsed`.
+export function parseVerdictBlock(text) {
+  const src = String(text ?? '');
+  const verdictMatch = src.match(/^VERDICT\s*:\s*(APPROVED-WITH-MINOR|APPROVED|CHANGES-REQUESTED|CRITICAL)\s*$/im);
+  if (!verdictMatch) return null;
+
+  const memberMatch = src.match(/^PANEL_MEMBER\s*:\s*(\S+)\s*$/im);
+  const member = memberMatch && memberMatch[1] !== '-' ? memberMatch[1] : null;
+
+  const findings = { critical: [], important: [], minor: [] };
+  const findingsMatch = src.match(/^FINDINGS:\s*$/im);
+  if (findingsMatch) {
+    const rest = src.slice(findingsMatch.index + findingsMatch[0].length);
+    let severity = null;
+    for (const line of rest.split('\n')) {
+      if (/^\S/.test(line)) break; // next top-level field ends FINDINGS
+      const sev = line.match(/^\s{2}(critical|important|minor)\s*:/);
+      if (sev) {
+        severity = sev[1];
+        continue;
+      }
+      const item = line.match(/^\s{4}-\s+(.+?)\s*$/);
+      if (item && severity) {
+        const text2 = item[1];
+        if (text2 !== 'none' && text2 !== '-') findings[severity].push(text2);
+      }
+    }
+  }
+
+  return { member, verdict: verdictMatch[1].toUpperCase(), findings };
+}
+
+// Normalize a finding bullet for identity comparison: two members report the
+// "identical finding" when the normalized text matches.
+function normalizeFinding(text) {
+  return String(text).replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+export function aggregatePanelVerdicts(verdicts) {
+  const list = Array.isArray(verdicts) ? verdicts : [];
+  const parsed = [];
+  const unparsed = [];
+
+  list.forEach((block, i) => {
+    const p = parseVerdictBlock(block);
+    if (p) parsed.push({ ...p, label: p.member || `verdict[${i}]` });
+    else unparsed.push(`verdict[${i}]`);
+  });
+
+  // Agreement Map: finding → set of panel members reporting it.
+  const map = new Map(); // normalized → { finding, members:Set, critical:boolean }
+  for (const p of parsed) {
+    for (const sev of SEVERITIES) {
+      for (const f of p.findings[sev]) {
+        const key = normalizeFinding(f);
+        let entry = map.get(key);
+        if (!entry) {
+          entry = { finding: f, members: new Set(), critical: sev === 'critical' };
+          map.set(key, entry);
+        }
+        entry.members.add(p.label);
+        if (sev === 'critical') entry.critical = true;
+      }
+    }
+  }
+
+  const agreementMap = [...map.values()].map((e) => ({
+    finding: e.finding,
+    members: [...e.members],
+  }));
+  const highSignal = [...map.values()]
+    .filter((e) => e.members.size >= 2 || e.critical)
+    .map((e) => ({ finding: e.finding, members: [...e.members] }));
+
+  const approvals = parsed.filter((p) => p.verdict === 'APPROVED').length;
+  const changeRequests = parsed.filter((p) => p.verdict === 'CHANGES-REQUESTED').length;
+  const hasCritical =
+    parsed.some((p) => p.verdict === 'CRITICAL') || parsed.some((p) => p.findings.critical.length > 0);
+
+  let verdict;
+  if (hasCritical || changeRequests >= 2) verdict = 'changes_requested';
+  else if (approvals >= 2) verdict = 'approved';
+  else verdict = 'approved_minor';
+
+  return { agreementMap, verdict, highSignal, unparsed };
+}
+
+// CLI-only helpers below (not part of the canonical module).
+
+// Extract every `## Reviewer Verdict` block from a task file. A block runs from
+// its heading to the next `## ` heading or EOF.
+function extractVerdictBlocks(markdown) {
+  const blocks = [];
+  const re = /^##\s+Reviewer Verdict\s*$/gm;
+  let m;
+  while ((m = re.exec(markdown)) !== null) {
+    const start = m.index;
+    const rest = markdown.slice(start + m[0].length);
+    const next = rest.search(/^##\s+/m);
+    blocks.push(next === -1 ? rest : rest.slice(0, next));
+  }
+  return blocks;
+}
+
+function main() {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.error('usage: review-panel-aggregate.mjs <TASK-xxx.md> [TASK-xxx.md...]');
+    process.exit(0); // advisory — never break a pipeline
+  }
+
+  const blocks = [];
+  const labels = [];
+  for (const file of files) {
+    let markdown;
+    try {
+      markdown = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      console.log(`UNPARSED: ${file} (unreadable: ${err.message})`);
+      continue;
+    }
+    for (const block of extractVerdictBlocks(markdown)) {
+      labels.push(file);
+      blocks.push(block);
+    }
+  }
+
+  const { agreementMap, verdict, highSignal, unparsed } = aggregatePanelVerdicts(blocks);
+
+  console.log('AGREEMENT_MAP:');
+  for (const e of agreementMap) console.log(`  ${e.finding} → ${e.members.join(', ')}`);
+  if (agreementMap.length === 0) console.log('  (none)');
+  console.log('HIGH_SIGNAL:');
+  for (const e of highSignal) console.log(`  ${e.finding} → ${e.members.join(', ')}`);
+  if (highSignal.length === 0) console.log('  (none)');
+  if (unparsed.length === 0) console.log('UNPARSED: (none)');
+  for (const u of unparsed) {
+    const idx = Number(u.slice('verdict['.length, -1));
+    console.log(`UNPARSED: ${labels[idx] ?? '?'}#${u}`);
+  }
+  console.log(`VERDICT: ${verdict}`);
+  process.exit(0);
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main();
+}