contextdevkit 1.8.1 → 1.9.0

package/templates/contextkit/tools/scripts/draft-changelog.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * `/draft-changelog` — build a `[Unreleased]` skeleton from Conventional Commits
+ * since the last tag (ADR-0030, OSS repo-ops).
+ *
+ * Reads `git log <lastTag>..HEAD`, parses Conventional Commit subjects, and groups
+ * them into Keep-a-Changelog sections (Added / Changed / Fixed / …). It DRAFTS —
+ * it never writes `docs/CHANGELOG.md`; the human reviews and pastes. Local git only
+ * (no network), every git call is timed out + defensive (rule 2): a non-repo or a
+ * git error prints a clean message, never a stack trace.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/draft-changelog.mjs           # since last tag
+ *   node contextkit/tools/scripts/draft-changelog.mjs --since v1.7.0
+ *   node contextkit/tools/scripts/draft-changelog.mjs --json
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Conventional-commit type → Keep-a-Changelog section. */
+const SECTION = {
+  feat: 'Added',
+  fix: 'Fixed',
+  perf: 'Changed',
+  refactor: 'Changed',
+  revert: 'Removed',
+  security: 'Security',
+  docs: 'Documentation',
+  chore: 'Chores',
+  build: 'Chores',
+  ci: 'Chores',
+  test: 'Chores',
+  style: 'Chores',
+};
+const ORDER = ['Added', 'Changed', 'Fixed', 'Removed', 'Deprecated', 'Security', 'Documentation', 'Chores', 'Other'];
+
+/** Runs git with a hard timeout; returns stdout or null on any failure. */
+function git(args) {
+  const res = spawnSync('git', args, { encoding: 'utf-8', timeout: 5000 });
+  return res.status === 0 ? (res.stdout || '').trim() : null;
+}
+
+function lastTag() {
+  return git(['describe', '--tags', '--abbrev=0']);
+}
+
+/** Parses a `feat(scope)!: subject` line into { section, scope, breaking, text }. */
+function parse(subject) {
+  const m = subject.match(/^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.+)$/);
+  if (!m) return { section: 'Other', scope: null, breaking: false, text: subject };
+  const [, type, scope, bang, text] = m;
+  return { section: SECTION[type.toLowerCase()] || 'Other', scope: scope || null, breaking: Boolean(bang), text };
+}
+
+function collect(since) {
+  if (git(['rev-parse', '--is-inside-work-tree']) !== 'true') return { error: 'not a git repository' };
+  const range = since ? `${since}..HEAD` : null;
+  const args = ['log', '--no-merges', '--pretty=%s'];
+  if (range) args.splice(1, 0, range);
+  const out = git(args);
+  if (out === null) return { error: since ? `git log failed for range ${range}` : 'git log failed' };
+  const subjects = out.split('\n').filter(Boolean);
+  const groups = {};
+  for (const s of subjects) {
+    const p = parse(s);
+    (groups[p.section] ||= []).push(p);
+  }
+  return { since, count: subjects.length, groups };
+}
+
+function render(result) {
+  if (result.error) return `ℹ️  ${result.error} — nothing to draft.`;
+  const lines = ['## [Unreleased]', ''];
+  if (result.count === 0) {
+    lines.push(`_No commits since ${result.since || 'the start'}._`);
+    return lines.join('\n');
+  }
+  for (const section of ORDER) {
+    const items = result.groups[section];
+    if (!items || items.length === 0) continue;
+    lines.push(`### ${section}`);
+    for (const it of items) {
+      const scope = it.scope ? `**${it.scope}:** ` : '';
+      const breaking = it.breaking ? '⚠️ BREAKING — ' : '';
+      lines.push(`- ${breaking}${scope}${it.text}`);
+    }
+    lines.push('');
+  }
+  lines.push(`_Drafted from ${result.count} commit(s) since ${result.since || 'the first commit'}. Review before pasting into docs/CHANGELOG.md — this command never writes it._`);
+  return lines.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const wantJson = argv.includes('--json');
+  const sinceIdx = argv.indexOf('--since');
+  const since = sinceIdx !== -1 && argv[sinceIdx + 1] ? argv[sinceIdx + 1] : lastTag();
+  const result = collect(since);
+  console.log(wantJson ? JSON.stringify(result, null, 2) : render(result));
+}
+
+main();

package/templates/contextkit/tools/scripts/validate-doc.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * `/validate-doc` — quality gate for OUR OWN planning artifacts (ADR-0030).
+ *
+ * Adapts EVO-METHOD/BMAD's `steps-v` document-validation chain (MIT) to
+ * ContextDevKit's artifacts: an ADR must pose its problem, decide plainly, and own
+ * its trade-offs; a roadmap must be measurable, not aspirational. The kit already
+ * validates *code wiring* (selfcheck) — this validates the *prose* of the decisions
+ * those tests are built on.
+ *
+ * Report-only by design (constitution §8 — never a false "pass", but also never a
+ * push-blocker): it prints findings and exits non-zero only so CI *could* gate on
+ * it; the slash command is advisory. Zero runtime deps (rule 1).
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/validate-doc.mjs <file.md>
+ *   node contextkit/tools/scripts/validate-doc.mjs <file.md> --json
+ *   node contextkit/tools/scripts/validate-doc.mjs --adr <file.md>      # force ADR rubric
+ *   node contextkit/tools/scripts/validate-doc.mjs --roadmap <file.md>  # force roadmap rubric
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+
+/** Leftover template tokens that mean the artifact was never filled in. */
+const PLACEHOLDERS = [/<short decision title>/i, /\bNNNN\b/, /YYYY-MM-DD/, /<who>/i, /<what we will do/i, /ADR-XXXX/];
+/** Words that signal a real trade-off was considered (Consequences quality). */
+const TRADEOFF_HINTS = /(trade-?off|negative|risk|harder|downside|we give up|cost)/i;
+/** Tokens that make a roadmap line measurable rather than aspirational. */
+const MEASURABLE_HINTS = /(\d|%|by\s+\w+|target|metric|KPI|reduce|increase|within|ship|release)/i;
+
+/** Splits a markdown doc into `## Heading` → body. Zero-dep, defensive. */
+function sections(text) {
+  const out = {};
+  const re = /^#{2,3}\s+(.+?)\s*$/gm;
+  const heads = [];
+  let m;
+  while ((m = re.exec(text))) heads.push({ title: m[1].trim(), start: m.index + m[0].length });
+  heads.forEach((h, i) => {
+    const end = i + 1 < heads.length ? heads[i + 1].start : text.length;
+    out[h.title.toLowerCase()] = text.slice(h.start, end).trim();
+  });
+  return out;
+}
+
+/** Detects the rubric to apply from the path + content. */
+function detectType(file, text) {
+  const name = basename(file).toLowerCase();
+  if (/\/decisions\//.test(file.replace(/\\/g, '/')) || /^\d{4}-/.test(name) || /\*\*Status\*\*/i.test(text)) return 'adr';
+  if (/roadmap/.test(name)) return 'roadmap';
+  return 'generic';
+}
+
+function err(code, message) {
+  return { level: 'error', code, message };
+}
+function warn(code, message) {
+  return { level: 'warn', code, message };
+}
+
+/** ADR rubric — sections present, status valid, no placeholders, trade-offs owned. */
+function validateAdr(text) {
+  const findings = [];
+  const sec = sections(text);
+  const has = (name) => Object.keys(sec).some((k) => k === name || k.startsWith(name));
+  for (const required of ['context', 'decision', 'consequences']) {
+    if (!has(required)) findings.push(err('MISSING_SECTION', `ADR is missing a "## ${required[0].toUpperCase() + required.slice(1)}" section.`));
+  }
+  if (!/\*\*status\*\*\s*:/i.test(text)) findings.push(err('NO_STATUS', 'ADR has no "**Status**:" line.'));
+  else if (!/\*\*status\*\*\s*:\s*(proposed|accepted|superseded)/i.test(text)) findings.push(warn('STATUS_VALUE', 'Status is not one of Proposed / Accepted / Superseded.'));
+  for (const re of PLACEHOLDERS) {
+    if (re.test(text)) findings.push(err('PLACEHOLDER', `Unfilled template placeholder still present: ${re}`));
+  }
+  const context = sec['context'] || '';
+  if (context && context.length < 200) findings.push(warn('THIN_CONTEXT', `Context is thin (${context.length} chars) — it should state the forces WITHOUT already giving the answer.`));
+  const consequences = Object.entries(sec).find(([k]) => k.startsWith('consequences'))?.[1] || '';
+  if (consequences && !TRADEOFF_HINTS.test(consequences)) findings.push(warn('NO_TRADEOFFS', 'Consequences states no trade-off / negative / risk — a decision with only upsides is usually under-examined.'));
+  if (!/follow-?up/i.test(text)) findings.push(warn('NO_FOLLOWUPS', 'No follow-ups noted — what does this decision obligate next?'));
+  return findings;
+}
+
+/** Roadmap rubric — items exist and read as measurable, not aspirational. */
+function validateRoadmap(text) {
+  const findings = [];
+  const items = text.split('\n').filter((l) => /^\s*[-*]\s+/.test(l) || /^\s*\d+\.\s+/.test(l));
+  if (items.length === 0) findings.push(warn('NO_ITEMS', 'No list items detected — is the roadmap populated?'));
+  const vague = items.filter((l) => l.replace(/^\s*[-*\d.]+\s*/, '').length > 12 && !MEASURABLE_HINTS.test(l));
+  if (items.length && vague.length / items.length > 0.5) {
+    findings.push(warn('NOT_MEASURABLE', `${vague.length}/${items.length} items read as aspirational (no number / date / target). Make outcomes measurable.`));
+  }
+  for (const re of PLACEHOLDERS) {
+    if (re.test(text)) findings.push(warn('PLACEHOLDER', `Template placeholder still present: ${re}`));
+  }
+  return findings;
+}
+
+function validate(file, forced) {
+  const text = readFileSync(file, 'utf-8').replace(/^/, '');
+  const type = forced || detectType(file, text);
+  const findings = type === 'adr' ? validateAdr(text) : type === 'roadmap' ? validateRoadmap(text) : validateRoadmap(text);
+  return { file, type, findings };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const wantJson = argv.includes('--json');
+  let forced = null;
+  if (argv.includes('--adr')) forced = 'adr';
+  if (argv.includes('--roadmap')) forced = 'roadmap';
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (!file) {
+    console.error('Usage: validate-doc.mjs <file.md> [--adr|--roadmap] [--json]');
+    process.exit(2);
+  }
+  if (!existsSync(file)) {
+    console.error(`File not found: ${file}`);
+    process.exit(2);
+  }
+  const report = validate(file, forced);
+  const errors = report.findings.filter((f) => f.level === 'error');
+  const warns = report.findings.filter((f) => f.level === 'warn');
+
+  if (wantJson) {
+    console.log(JSON.stringify({ ...report, errorCount: errors.length, warnCount: warns.length }, null, 2));
+  } else {
+    console.log(`\n📋 validate-doc — ${basename(file)} (${report.type} rubric)`);
+    console.log('─'.repeat(56));
+    if (report.findings.length === 0) console.log('  ✅ No issues — the artifact passes the rubric.');
+    for (const f of errors) console.log(`  ❌ [${f.code}] ${f.message}`);
+    for (const f of warns) console.log(`  ⚠️  [${f.code}] ${f.message}`);
+    console.log(`\n  ${errors.length} error(s), ${warns.length} warning(s). (advisory — never blocks a push)`);
+  }
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+main();

package/tools/integration-test-tooling.mjs

@@ -22,7 +22,7 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { KIT, run, readJson, reporter, installFixture } from './it-helpers.mjs';
+import { KIT, run, git, readJson, reporter, installFixture } from './it-helpers.mjs';
 
 const rep = reporter();
 const { ok, bad } = rep;
@@ -48,6 +48,30 @@ try {
   (() => { try { const g = JSON.parse(gitStatus.stdout); return g.isRepo === true && g.remoteUrl === null; } catch { return false; } })()
     ? ok('git.mjs reports repo + missing remote') : bad(`git.mjs failed: ${gitStatus.stdout || gitStatus.stderr}`);
 
+  // ADR-0030 — complexity rubric: regulated domain auto-routes + forces architectural tier.
+  const clsLgpd = script('complexity-rubric.mjs', 'classify', 'store user CPF and consent', '--json');
+  (() => { try { const j = JSON.parse(clsLgpd.stdout); return j.domain === 'lgpd' && j.requiredAgents.includes('privacy-lgpd') && j.tier === 'architectural' && j.needsAdr === true; } catch { return false; } })()
+    ? ok('complexity-rubric routes a regulated (LGPD) task to privacy-lgpd + architectural tier')
+    : bad(`complexity-rubric LGPD classify failed: ${clsLgpd.stdout || clsLgpd.stderr}`);
+  const clsTrivial = script('complexity-rubric.mjs', 'classify', 'fix typo in readme', '--json');
+  (() => { try { const j = JSON.parse(clsTrivial.stdout); return j.tier === 'trivial' && j.needsAdr === false && j.domain === 'general'; } catch { return false; } })()
+    ? ok('complexity-rubric classifies a trivial task with no ceremony')
+    : bad(`complexity-rubric trivial classify failed: ${clsTrivial.stdout || clsTrivial.stderr}`);
+
+  // ADR-0030 — validate-doc flags an unfilled ADR template (placeholders), runs the adr rubric.
+  const vdTpl = script('validate-doc.mjs', 'contextkit/memory/decisions/_TEMPLATE.md', '--json');
+  (() => { try { const j = JSON.parse(vdTpl.stdout); return j.type === 'adr' && j.errorCount > 0 && j.findings.some((f) => f.code === 'PLACEHOLDER'); } catch { return false; } })()
+    ? ok('validate-doc flags an unfilled ADR template (placeholders)')
+    : bad(`validate-doc template check failed: ${vdTpl.stdout || vdTpl.stderr}`);
+
+  // ADR-0030 — draft-changelog groups Conventional Commits since the last tag.
+  git(['add', '-A'], proj);
+  git(['commit', '-m', 'feat(x): add a thing', '--no-verify'], proj);
+  const dc = script('draft-changelog.mjs', '--json');
+  (() => { try { const j = JSON.parse(dc.stdout); return Array.isArray(j.groups?.Added) && j.groups.Added.some((i) => i.text.includes('add a thing')); } catch { return false; } })()
+    ? ok('draft-changelog groups Conventional Commits into Keep-a-Changelog sections')
+    : bad(`draft-changelog failed: ${dc.stdout || dc.stderr}`);
+
   // DevPipeline tests live in `integration-test-tooling-pipeline.mjs` (sibling).
 
   // Deep analysis: aggregates the deterministic scanners into one report.

package/tools/selfcheck-source.mjs

@@ -18,6 +18,7 @@
  * Every function takes the reporter `rep` ({ ok, bad }) plus only what it
  * needs. Entry point: `runSourceChecks(rep, ctx)` where `ctx = { KIT }`.
  */
+import { existsSync } from 'node:fs';
 import { readFile, readdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
@@ -268,6 +269,38 @@ async function checkSourceInvariants(rep, KIT) {
     ['/ship scopes via the ADR catalog (ADR-0027)', 'templates/claude/commands/pipeline/ship.md', /adr-digest\.mjs/],
     ['/new-adr checks for an existing decision first (ADR-0027)', 'templates/claude/commands/new-adr.md', /adr-digest\.mjs/],
     ['/deep-analysis scans existing ADRs before drafting (ADR-0027)', 'templates/claude/commands/audit/deep-analysis.md', /adr-digest\.mjs/],
+    // ADR-0030 — per-task complexity rubric (EVO-METHOD/BMAD-derived, MIT).
+    ['complexity-rubric loader exports classify (ADR-0030)', 'templates/contextkit/tools/scripts/complexity-rubric.mjs', /export function classify/],
+    ['complexity-rubric loader exports loadRubric', 'templates/contextkit/tools/scripts/complexity-rubric.mjs', /export function loadRubric/],
+    ['complexity-rubric falls back to an embedded default (never throws)', 'templates/contextkit/tools/scripts/complexity-rubric.mjs', /DEFAULT_RUBRIC/],
+    ['complexity-rubric single-sources the path via pathsFor (rule 4)', 'templates/contextkit/tools/scripts/complexity-rubric.mjs', /pathsFor\(root\)\.complexityRubric/],
+    ['rubric seed declares the lgpd domain → privacy-lgpd (ADR-0030)', 'templates/contextkit/policy/complexity-rubric.json', /"lgpd":[\s\S]*"privacy-lgpd"/],
+    ['rubric seed declares the three ceremony tiers', 'templates/contextkit/policy/complexity-rubric.json', /"trivial":[\s\S]*"feature":[\s\S]*"architectural":/],
+    ['paths.mjs exposes complexityRubric (ADR-0030)', 'templates/contextkit/runtime/config/paths.mjs', /complexityRubric:/],
+    ['/dev-start right-sizes via the complexity rubric (ADR-0030)', 'templates/claude/commands/pipeline/dev-start.md', /complexity-rubric\.mjs classify/],
+    ['/dev-start has a correct-course checkpoint (ADR-0030)', 'templates/claude/commands/pipeline/dev-start.md', /Correct-course checkpoint/],
+    ['/ship right-sizes via the complexity rubric (ADR-0030)', 'templates/claude/commands/pipeline/ship.md', /complexity-rubric\.mjs classify/],
+    ['/pipeline right-sizes a new task (ADR-0030)', 'templates/claude/commands/pipeline/pipeline.md', /complexity-rubric\.mjs classify/],
+    ['installer seeds the complexity rubric (ADR-0030)', 'install.mjs', /policy\/complexity-rubric\.json/],
+    ['installer seeds review-protocol.md — closes ADR-0029 gap (ADR-0030)', 'install.mjs', /'review-protocol\.md'/],
+    // ADR-0030 — document-quality validation (EVO steps-v adaptation, MIT).
+    ['validate-doc validates ADR sections (ADR-0030)', 'templates/contextkit/tools/scripts/validate-doc.mjs', /function validateAdr/],
+    ['validate-doc flags template placeholders', 'templates/contextkit/tools/scripts/validate-doc.mjs', /PLACEHOLDERS/],
+    ['validate-doc checks consequences own a trade-off', 'templates/contextkit/tools/scripts/validate-doc.mjs', /TRADEOFF_HINTS/],
+    ['validate-doc is advisory — never blocks (rule 8)', 'templates/contextkit/tools/scripts/validate-doc.mjs', /never blocks a push/],
+    ['/validate-doc command briefing ships (ADR-0030)', 'templates/claude/commands/audit/validate-doc.md', /document-quality rubric/],
+    // ADR-0030 — OSS repo-ops (gh-triage / draft-changelog / changelog-social + RCA).
+    ['draft-changelog groups Conventional Commits (ADR-0030)', 'templates/contextkit/tools/scripts/draft-changelog.mjs', /const SECTION = \{/],
+    ['draft-changelog times out git calls (rule 2)', 'templates/contextkit/tools/scripts/draft-changelog.mjs', /timeout:\s*\d/],
+    ['draft-changelog never writes the file (drafts only)', 'templates/contextkit/tools/scripts/draft-changelog.mjs', /never writes/],
+    ['/draft-changelog command briefing ships', 'templates/claude/commands/vcs/draft-changelog.md', /Draft a \[Unreleased\]/i],
+    ['/gh-triage classifies via the complexity rubric (ADR-0030)', 'templates/claude/commands/vcs/gh-triage.md', /complexity-rubric\.mjs classify/],
+    ['/gh-triage degrades cleanly without gh (rule 8)', 'templates/claude/commands/vcs/gh-triage.md', /skip, never fake/],
+    ['/changelog-social drafts only — never posts', 'templates/claude/commands/vcs/changelog-social.md', /never posts/i],
+    ['bug-hunt emits a structured RCA writeup (ADR-0030)', 'templates/claude/commands/bug-hunt.md', /root-cause analysis/i],
+    // ADR-0030 — mid-flight elicitation (advanced-elicitation + correct-course).
+    ['/roadmap new does advanced elicitation (ADR-0030)', 'templates/claude/commands/roadmap.md', /Advanced elicitation/],
+    ['/forge-new does advanced elicitation (ADR-0030)', 'templates/claude/commands/forge/forge-new.md', /Advanced elicitation/],
   ];
   for (const [label, rel, re] of cases) {
     re.test(await srcText(rel)) ? ok(label) : bad(`${label} — pattern ${re} missing in ${rel}`);
@@ -318,9 +351,48 @@ async function checkWorkflowsPinned(rep, KIT) {
     ? ok('ci.yml declares least-privilege permissions (contents: read)') : bad('ci.yml missing contents:read permissions');
 }
 
+/**
+ * ADR-0030 — cross-doc link integrity. Scans the seeded top-level engine docs for
+ * relative markdown links to other `.md` files and asserts each target exists, so a
+ * deleted/renamed doc (the kind of rot the `review-protocol.md` seed gap caused)
+ * fails the build instead of shipping a dangling link. Scoped to the controlled set
+ * `templates/contextkit/*.md`; widening to `docs/` is an ADR-0030 follow-up.
+ */
+async function checkDocLinks(rep, KIT) {
+  const { ok, bad } = rep;
+  console.log('Checking cross-doc markdown links resolve (ADR-0030)...');
+  const dir = resolve(KIT, 'templates/contextkit');
+  const linkRe = /\[[^\]]*\]\(([^)]+)\)/g;
+  const offenders = [];
+  let checked = 0;
+  let entries = [];
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    /* no dir — nothing to check */
+  }
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith('.md')) continue;
+    const text = await readFile(resolve(dir, e.name), 'utf-8').catch(() => '');
+    let m;
+    while ((m = linkRe.exec(text))) {
+      let target = m[1].trim().split(/\s+/)[0]; // drop an optional "title"
+      if (!target || target.startsWith('http') || target.startsWith('#') || target.startsWith('<')) continue;
+      target = target.split('#')[0]; // strip an anchor
+      if (!target.endsWith('.md')) continue;
+      checked += 1;
+      if (!existsSync(resolve(dir, target))) offenders.push(`${e.name} → ${target}`);
+    }
+  }
+  offenders.length === 0
+    ? ok(`cross-doc markdown links resolve (${checked} checked)`)
+    : offenders.forEach((o) => bad(`dangling doc link: ${o}`));
+}
+
 /** Runs every source/structural check in order. `ctx` = { KIT }. */
 export async function runSourceChecks(rep, { KIT }) {
   await checkSourceInvariants(rep, KIT);
   await checkNoHardcodedPaths(rep, KIT);
   await checkWorkflowsPinned(rep, KIT);
+  await checkDocLinks(rep, KIT);
 }