@zyaiting/keelson 0.4.0

package/src/commands/status.js

@@ -0,0 +1,115 @@
+import path from 'node:path';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { readOr, listDirs } from '../lib/fs.js';
+import { loadConfig } from '../lib/config.js';
+import { loadAllChanges, sharedContracts } from '../lib/changes.js';
+import { evaluateLifecycle } from '../lib/lifecycle.js';
+import { readSession } from '../lib/session.js';
+import { worktreeFingerprint, headSha, lastTag, foldedSince, gitStatusShort, isGitRepo } from '../lib/git.js';
+import { heading, dim, warn } from '../lib/out.js';
+import { knowledgeHealth } from '../lib/health.js';
+import { maintainRuntime } from '../lib/maintenance.js';
+import { changeSpecDrift } from '../lib/specs.js';
+
+export function projectStatus(root) {
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  const changes = loadAllChanges(p.changes);
+  const fp = worktreeFingerprint(root);
+  const head = headSha(root);
+  const tag = lastTag(root);
+  const dirty = gitStatusShort(root) ?? [];
+  const session = readSession(root);
+  const focus = session.state?.change && changes.some((c) => c.name === session.state.change) ? session.state.change : null;
+  const activeNames = new Set(changes.map((c) => c.name));
+  const rows = changes.map((c) => {
+    const contractDrift = changeSpecDrift(c, p.specs);
+    const lifecycle = evaluateLifecycle(c, fp, { activeNames, contractDrift });
+    const verification = lifecycle.verification;
+    const blockedBy = lifecycle.blockedBy;
+    const handoff = c.handoff ? { updated: c.handoff.updated, at: c.handoff.at, headMoved: Boolean(c.handoff.at && head && !head.startsWith(c.handoff.at) && !c.handoff.at.startsWith(head)), next: c.handoff.next } : null;
+    return {
+      name: c.name,
+      tier: c.tier,
+      owner: c.owner,
+      branch: c.branch,
+      work: lifecycle.work,
+      verification,
+      gates: lifecycle.gates,
+      lifecycleWarnings: lifecycle.warnings,
+      release: c.release ?? 'unreleased',
+      progress: c.progress,
+      slices: c.slices,
+      acceptance: c.acceptanceProgress,
+      open: c.open,
+      assumed: c.assumed.length,
+      capabilities: c.capabilities,
+      depends: c.depends,
+      blockedBy,
+      handoff,
+      rulings: c.ledger.filter((e) => e.kind === 'ruling').length,
+      tasks: c.tasks,
+    };
+  });
+  const knowledgeFindings = knowledgeHealth(root, cfg, p).filter((h) => h.kind === 'budget' || h.kind === 'budget-hard');
+  const knowledge = {
+    critical: knowledgeFindings.filter((h) => h.level === 'error').length,
+    overBudget: knowledgeFindings.filter((h) => h.level === 'warn').length,
+    findings: knowledgeFindings.map((h) => ({ level: h.level, kind: h.kind, text: h.text })),
+  };
+  return {
+    root,
+    head,
+    fingerprint: fp,
+    dirty: dirty.length,
+    specs: listDirs(p.specs),
+    specsPath: p.specsRel,
+    now: readOr(p.now).trim(),
+    focus,
+    sessionAvailable: session.available,
+    changes: rows,
+    knowledge,
+    conflicts: sharedContracts(changes),
+    release: tag ? { lastTag: tag, landedSince: foldedSince(root, tag) } : null,
+  };
+}
+
+const GLYPH = { 'not-run': '·', passed: '✓', failed: '✗', stale: '~', partial: '?' };
+
+export async function status({ flags }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  maintainRuntime(root);
+  const s = projectStatus(root);
+  if (flags.json) {
+    console.log(JSON.stringify(s, null, 2));
+    return 0;
+  }
+  heading(`Keelson — ${path.basename(root)}`);
+  console.log(`${s.specs.length} capabilit${s.specs.length === 1 ? 'y' : 'ies'} in ${s.specsPath} · ${s.changes.length} active change${s.changes.length === 1 ? '' : 's'}${s.focus ? ` · focus ${s.focus}` : ''}${s.head ? ` · HEAD ${s.head}` : ''}${s.dirty ? ` · ${s.dirty} uncommitted` : ''}`);
+  console.log('');
+  if (!s.changes.length) console.log(dim('No change in flight.'));
+  for (const c of s.changes) {
+    const who = [c.owner, c.branch && c.branch !== 'main' && c.branch !== 'master' ? c.branch : null].filter(Boolean).join(' @ ');
+    console.log(`${c.name}  ${dim(`[${c.tier}]`)}  work: ${c.work}  verify: ${GLYPH[c.verification.state]} ${c.verification.state}  release: ${c.release}${who ? dim(`  (${who})`) : ''}`);
+    if (c.verification.state === 'stale') console.log(dim(`   ${c.verification.detail} — re-run \`keelson check --record\` before landing`));
+    if (c.blockedBy.length) console.log(dim(`   depends on active: ${c.blockedBy.join(', ')}`));
+    if (c.slices.length) for (const sl of c.slices) console.log(`   ${sl.done === sl.total && sl.total ? '✓' : '·'} slice ${sl.name} ${sl.done}/${sl.total}${sl.delivers ? dim(` — ${sl.delivers}`) : ''}`);
+    else for (const t of c.tasks) console.log(`   ${t.done ? '✓' : '·'} ${t.id ? t.id + ' ' : ''}${t.title}${t.effort ? dim(` (${t.effort})`) : ''}`);
+    if (c.acceptance.total) console.log(dim(`   acceptance ${c.acceptance.done}/${c.acceptance.total}`));
+    if (c.open.length) console.log(`   open: ${c.open.map((o) => `${o.text}${o.blocks.length ? ` (blocks ${o.blocks.join(', ')})` : ''}`).join('; ')}`);
+    if (c.assumed) console.log(dim(`   ${c.assumed} assumed decision${c.assumed > 1 ? 's' : ''} awaiting the owner`));
+    if (c.handoff) console.log(dim(`   handoff ${c.handoff.updated ?? ''}${c.handoff.at ? ` at ${c.handoff.at}` : ''}${c.handoff.headMoved ? ' — HEAD moved since; check the worktree before resuming' : ''}`));
+  }
+  if (s.conflicts.length) {
+    console.log('');
+    for (const k of s.conflicts) warn(`shared contract: ${k.a} and ${k.b} both touch ${[...k.capabilities.map((c) => `specs/${c}`), ...k.paths].join(', ')} — align the interface before implementing both`);
+  }
+  if (s.release) {
+    console.log('');
+    console.log(dim(`last release ${s.release.lastTag}; landed since: ${s.release.landedSince.length ? s.release.landedSince.join(', ') : 'none'}`));
+  }
+  console.log('');
+  heading('NOW.md');
+  console.log(s.now || dim('(empty)'));
+  return 0;
+}

package/src/commands/uninstall.js

@@ -0,0 +1,30 @@
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { rmrf, exists } from '../lib/fs.js';
+import { loadConfig } from '../lib/config.js';
+import { readManagedState, removeCanonicalRuntime, removeSurfaces } from '../platforms/index.js';
+import { ok, warn, heading, info } from '../lib/out.js';
+
+/** Remove generated surfaces (skills, resident blocks, hooks). Project facts in .keelson/ stay unless --purge. */
+export async function uninstall({ flags }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  const managed = readManagedState(root);
+  heading(`Uninstall Keelson surfaces from ${root}`);
+  const removed = removeSurfaces(root, cfg.tools ?? [], cfg);
+  for (const r of removed) ok(`removed ${r}`);
+  if (managed?.vendor === true) {
+    const canonical = removeCanonicalRuntime(root, { lang: cfg.lang, profile: cfg.profile, version: managed.packageVersion, guide: cfg.guide });
+    for (const r of canonical.removed) ok(`removed ${r}`);
+    for (const r of canonical.preserved) warn(`kept ${r}: it differs from the vendored Keelson output`);
+  }
+  if (exists(p.runtime)) {
+    rmrf(p.runtime);
+    ok('removed Keelson local runtime');
+  }
+  if (flags.purge) {
+    rmrf(p.keelson);
+    warn('removed .keelson/ entirely (INTENT, NOW, rules, changes). Specs outside .keelson/ are untouched.');
+  } else info('kept .keelson/ project facts (INTENT, NOW, ROADMAP, rules, specs, changes). Pass --purge to remove everything.');
+  return 0;
+}

package/src/commands/validate.js

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { exists, readOr, listDirs, walk, read } from '../lib/fs.js';
+import { loadConfig } from '../lib/config.js';
+import { parseRulesIndex } from '../lib/rules.js';
+import { parseSpec, parseDelta, parseFrontmatter, renderSpec, hasScenario, normalizeNewlines, requirementKey, hasSection, EFFORT_TIERS, ROOT_CAUSES, WORK_STATUSES } from '../lib/markdown.js';
+import { loadAllChanges } from '../lib/changes.js';
+import { datedIdPatterns } from '../lib/models.js';
+import { knowledgeHealth } from '../lib/health.js';
+import { readCapabilitySpec } from '../lib/specs.js';
+import { ok, fail, warn } from '../lib/out.js';
+
+export function validateProject(root) {
+  const errors = [];
+  const warnings = [];
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+
+  if (!exists(p.intent)) errors.push('missing .keelson/INTENT.md');
+  else if (/^One paragraph\./m.test(readOr(p.intent)) && !/^First contact with /m.test(readOr(p.now))) warnings.push('INTENT.md still contains template placeholder text (the agent drafts it on first contact; if that already happened, ask it to)');
+  if (!exists(p.now)) errors.push('missing .keelson/NOW.md');
+  if (!['lean', 'guided'].includes(cfg.profile)) errors.push(`config.profile must be lean|guided (got ${cfg.profile})`);
+  if (!['fold', 'keep'].includes(cfg.land)) errors.push(`config.land must be fold|keep (got ${cfg.land})`);
+  if (!exists(p.specs) && p.specsRel !== '.keelson/specs') warnings.push(`paths.specs points at ${p.specsRel}, which does not exist`);
+  for (const [k, v] of Object.entries(cfg.refs ?? {})) if (v && !/^https?:\/\//.test(v) && !exists(path.join(root, v))) warnings.push(`refs.${k} points at ${v}, which does not exist`);
+  const idx = parseRulesIndex(readOr(p.rulesIndex));
+  for (const e of idx) if (!exists(path.join(p.rules, e.file))) errors.push(`rules/index.md references missing file: ${e.file}`);
+  for (const f of walk(p.rules)) if (f !== 'index.md' && f.endsWith('.md') && !idx.some((e) => e.file === f)) warnings.push(`rules/${f} is not listed in rules/index.md (it will never be routed)`);
+
+  for (const cap of listDirs(p.specs)) {
+    const f = path.join(p.specs, cap, 'spec.md');
+    if (!exists(f)) {
+      errors.push(`${p.specsRel}/${cap}/ has no spec.md`);
+      continue;
+    }
+    const logical = readCapabilitySpec(p.specs, cap);
+    const s = parseSpec(logical);
+    if (renderSpec(s) !== normalizeNewlines(logical)) errors.push(`${p.specsRel}/${cap}/spec.md does not round-trip through the Markdown spec parser`);
+    if (!s.requirements.length) warnings.push(`${p.specsRel}/${cap}/spec.md has no Requirement sections`);
+    for (const r of s.requirements) {
+      if (!r.body.trim()) errors.push(`${p.specsRel}/${cap}: requirement "${r.name}" has an empty body`);
+      if (!hasScenario(r.body)) warnings.push(`${p.specsRel}/${cap}: requirement "${r.name}" has no scenario`);
+    }
+    const names = s.requirements.map((r) => requirementKey(r.name));
+    for (const n of new Set(names.filter((n, i) => names.indexOf(n) !== i))) errors.push(`${p.specsRel}/${cap}: duplicate requirement "${n}"`);
+  }
+
+  const active = loadAllChanges(p.changes);
+  for (const c of active) {
+    const tag = `changes/${c.name}`;
+    if (!['quick', 'spec'].includes(c.tier)) errors.push(`${tag}: tier must be quick|spec (got ${c.tier})`);
+    if (!WORK_STATUSES.includes(c.work)) errors.push(`${tag}: status must be one of ${WORK_STATUSES.join('|')}`);
+    for (const sec of ['Why', 'What']) if (!hasSection(c.body, sec)) errors.push(`${tag}/change.md: missing "## ${sec}"`);
+    if (c.tier === 'spec') {
+      for (const sec of ['How', 'Impact']) if (!hasSection(c.body, sec)) errors.push(`${tag}/change.md: spec tier requires "## ${sec}"`);
+      if (!c.deltaFiles.length) warnings.push(`${tag}: spec tier but no delta specs under specs/ (fine only if behaviour does not change)`);
+      if (!hasSection(c.body, 'Acceptance')) warnings.push(`${tag}/change.md: spec tier without "## Acceptance" — landing will refuse until each acceptance item maps to a check`);
+    }
+    for (const a of c.acceptance) if (!a.kind) warnings.push(`${tag}/change.md: acceptance "${a.text}" does not say how it is checked (— check: \`cmd\` | test: name | manual: how)`);
+    for (const o of c.open) if (!o.blocks.length) warnings.push(`${tag}/change.md: open question "${o.text}" does not say what it blocks (— blocks: <slice>)`);
+    for (const d of c.depends) if (!active.some((x) => x.name === d)) warnings.push(`${tag}: depends on "${d}", which is not an active change (landed, or a typo)`);
+    if (c.breaking && !c.hasRollout) warnings.push(`${tag}/change.md: **BREAKING** without "## Rollout" — landing will refuse`);
+    for (const t of c.tasks) {
+      if (t.effort && !EFFORT_TIERS.includes(t.effort)) errors.push(`${tag}/tasks.md: bad effort on "${t.title}"`);
+      if (!t.effort) warnings.push(`${tag}/tasks.md: "${t.title}" has no (effort: …) tag`);
+    }
+    for (const sl of c.slices) {
+      if (!sl.delivers) warnings.push(`${tag}/tasks.md: slice "${sl.name}" has no "Delivers:" line`);
+      if (/^(db|database|schema|backend|back-end|frontend|front-end|ui|api|model|models|storage|infra|infrastructure)( layer| only)?$/i.test(sl.name.trim())) warnings.push(`${tag}/tasks.md: slice "${sl.name}" is named after a layer; a slice should be one user-observable path through all layers (tracer bullet)`);
+    }
+    if (/\{\{\w+\}\}|^…$/m.test(c.body)) warnings.push(`${tag}/change.md still has template placeholders`);
+    for (const e of c.ledger) {
+      if (e.kind === 'verify' && (e.exit === null || !e.command)) errors.push(`${tag}/ledger.md: Verify entry "${e.title}" needs a \`command\` and "exit N"`);
+      if (e.kind === 'verify' && !e.tree) warnings.push(`${tag}/ledger.md: Verify entry "${e.title}" has no "tree <hash>", so staleness cannot be detected (use \`keelson check --record\`)`);
+      if (e.kind === 'dispatch' && e.result === null) warnings.push(`${tag}/ledger.md: Dispatch "${e.title}" has no "Result: pass|fail" line, so retro cannot count it`);
+      if (e.kind === 'root-cause' && !ROOT_CAUSES.includes(e.category)) errors.push(`${tag}/ledger.md: unknown root cause category "${e.category}"`);
+    }
+    for (const df of c.deltaFiles) {
+      const raw = read(path.join(c.dir, 'specs', df));
+      const d = parseDelta(parseFrontmatter(raw).body);
+      for (const issue of d.issues) errors.push(`${tag}/specs/${df}: malformed delta: ${issue}`);
+      const deltaRequirements = [...d.added, ...d.modified, ...d.removed];
+      const deltaNames = deltaRequirements.map((r) => requirementKey(r.name));
+      for (const n of new Set(deltaNames.filter((n, i) => deltaNames.indexOf(n) !== i))) errors.push(`${tag}/specs/${df}: duplicate delta requirement "${n}"`);
+      for (const r of [...d.added, ...d.modified]) if (!r.body.trim()) errors.push(`${tag}/specs/${df}: ${r.name} has an empty requirement body`);
+    }
+    if (c.handoff && !c.handoff.at) warnings.push(`${tag}/handoff.md has no "at:" commit; run \`keelson handoff ${c.name}\` to stamp it`);
+  }
+
+  for (const h of knowledgeHealth(root, cfg, p)) {
+    if (h.level === 'error') errors.push(`${h.kind}: ${h.text} → ${h.fix}`);
+  }
+
+  const patterns = datedIdPatterns();
+  for (const f of walk(p.keelson, { ignore: ['node_modules', '.git', '.local', '.runtime'] })) {
+    if (!/\.(md|yaml|yml|json)$/.test(f) || f.startsWith('hooks/')) continue;
+    const txt = read(path.join(p.keelson, f));
+    for (const re of patterns) {
+      const m = txt.match(re);
+      if (m) errors.push(`.keelson/${f}: dated model ID "${m[0]}" — use effort tiers (light|standard|deep) or floating aliases`);
+    }
+  }
+  return { errors, warnings };
+}
+
+export async function validate({ flags }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  const { errors, warnings } = validateProject(root);
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: !errors.length, errors, warnings }, null, 2));
+    return errors.length ? 1 : 0;
+  }
+  for (const w of warnings) warn(w);
+  for (const e of errors) fail(e);
+  if (!errors.length) ok(`valid${warnings.length ? ` (${warnings.length} warning${warnings.length > 1 ? 's' : ''})` : ''}`);
+  return errors.length ? 1 : 0;
+}

package/src/lib/args.js

@@ -0,0 +1,30 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const PLATFORM_FLAGS = Object.keys(require('../../registry/platforms.json').platforms);
+const RETIRED_PLATFORM_FLAGS = ['cursor', 'copilot', 'kilo', 'antigravity', 'devin', 'qoder', 'droid', 'ohmypi', 'reasonix', 'zcode', 'trae', 'grok', 'kimi', 'snow'];
+export const BOOLEAN_FLAGS = new Set(['all', 'list', 'irreversible', 'trust', 'vendor', 'session', 'json', 'force', 'dryRun', 'hooks', 'noHooks', 'onboard', 'refresh', 'detect', 'help', 'version', 'yes', 'keep', 'noProviders', 'quiet', 'confirmAssumptions', 'acceptDrift', 'worktree', 'purge', 'clear', 'auto', ...PLATFORM_FLAGS, ...RETIRED_PLATFORM_FLAGS]);
+
+/** Tiny argv parser: --flag, --key value, --key=value, positionals. */
+export function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith('--')) {
+      const [k, v] = a.slice(2).split(/=(.*)/s);
+      const key = k.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      if (v !== undefined) flags[key] = v;
+      else if (i + 1 < argv.length && !argv[i + 1].startsWith('--') && !BOOLEAN_FLAGS.has(key)) flags[key] = argv[++i];
+      else flags[key] = true;
+    } else if (a.startsWith('-') && a.length === 2) {
+      flags[a[1]] = true;
+    } else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+export const list = (v) => (v === undefined || v === true ? [] : String(v).split(',').map((s) => s.trim()).filter(Boolean));

package/src/lib/changes.js

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import { listDirs, readOr, exists, walk } from './fs.js';
+import { parseFrontmatter, parseTasks, parseSlices, parseLedger, parseAcceptance, parseOpenQuestions, parseDecisions, parseHandoff, hasSection, WORK_STATUSES } from './markdown.js';
+import { evaluateLifecycle } from './lifecycle.js';
+import { readDecisions } from './decisions.js';
+import { inspectEvidence } from './evidence.js';
+import { findProjectRoot, resolveWithin } from './paths.js';
+export { verificationStatus } from './lifecycle.js';
+
+export const TIERS = ['quick', 'spec'];
+
+export function listChanges(changesDir) {
+  return listDirs(changesDir).filter((d) => d !== 'archive' && exists(path.join(changesDir, d, 'change.md')));
+}
+
+const csv = (v) => (v ? String(v).replace(/^\[|\]$/g, '').split(',').map((s) => s.trim()).filter(Boolean) : []);
+
+export function loadChange(changesDir, name) {
+  if (typeof name !== 'string' || !name || name === '.' || name === '..' || /[/\\\0]/.test(name)) throw new Error('invalid change name');
+  const dir = resolveWithin(changesDir, name);
+  for (const file of walk(dir)) resolveWithin(dir, file);
+  if (!exists(path.join(dir, 'change.md'))) return null;
+  const { data, body } = parseFrontmatter(readOr(path.join(dir, 'change.md')));
+  const tasksText = readOr(path.join(dir, 'tasks.md'));
+  const tasks = parseTasks(tasksText);
+  const slices = parseSlices(tasksText);
+  const ledger = parseLedger(readOr(path.join(dir, 'ledger.md')));
+  const deltaFiles = walk(path.join(dir, 'specs')).filter((f) => f.endsWith('.md'));
+  const acceptance = parseAcceptance(body);
+  const open = parseOpenQuestions(body);
+  const decisions = parseDecisions(body);
+  const handoffText = readOr(path.join(dir, 'handoff.md'), '');
+  const handoff = handoffText ? parseHandoff(handoffText) : null;
+  const done = tasks.filter((t) => t.done).length;
+  const lastVerify = ledger.filter((e) => e.kind === 'verify').at(-1) ?? null;
+  const acceptanceDone = acceptance.filter((a) => a.done).length;
+
+  // Work status: explicit frontmatter wins; otherwise derived from the artifacts.
+  const storedWork = String(data.status ?? '').toLowerCase();
+  let work = storedWork;
+  if (!WORK_STATUSES.includes(work)) {
+    if (open.length && tasks.length === 0) work = 'clarifying';
+    else if (tasks.length === 0) work = 'clarifying';
+    else if (done < tasks.length) work = 'in-progress';
+    else work = lastVerify && lastVerify.exit === 0 ? 'in-review' : 'in-progress';
+  }
+  const capabilities = new Set(deltaFiles.map((f) => path.dirname(f).replace(/\\/g, '/')).filter((c) => c !== '.'));
+  for (const d of decisions) if (d.capability) capabilities.add(d.capability);
+
+  return {
+    name,
+    dir,
+    tier: (data.tier ?? 'quick').toLowerCase(),
+    created: data.created ?? null,
+    owner: data.owner ?? null,
+    branch: data.branch ?? null,
+    worktree: data.worktree ?? null,
+    depends: csv(data.depends),
+    touches: csv(data.touches),
+    release: data.release ?? null,
+    body,
+    tasks,
+    slices,
+    ledger,
+    deltaFiles,
+    capabilities: [...capabilities],
+    acceptance,
+    acceptanceProgress: { done: acceptanceDone, total: acceptance.length },
+    open,
+    decisions,
+    assumed: decisions.filter((d) => d.state === 'assumed'),
+    handoff,
+    progress: { done, total: tasks.length },
+    work,
+    storedWork: WORK_STATUSES.includes(storedWork) ? storedWork : null,
+    lastVerify,
+    decisionRecords: readDecisions(dir).decisions,
+    evidence: inspectEvidence(findProjectRoot(dir) ?? path.resolve(changesDir, '../..'), dir),
+    hasDecisions: hasSection(body, 'Decisions'),
+    hasRollout: hasSection(body, 'Rollout'),
+    // Only a bullet that starts with **BREAKING** counts, so the template's own hint does not.
+    breaking: /^\s*[-*]\s+\*\*BREAKING\*\*/m.test(body),
+  };
+}
+
+export function derivedWorkStatus(change, fingerprint, options = {}) {
+  return evaluateLifecycle(change, fingerprint, options).work;
+}
+
+export function loadAllChanges(changesDir) {
+  return listChanges(changesDir).map((n) => loadChange(changesDir, n)).filter(Boolean);
+}
+
+/** Pairs of active changes that touch the same capability or the same declared paths. */
+export function sharedContracts(changes) {
+  const out = [];
+  for (let i = 0; i < changes.length; i++) {
+    for (let j = i + 1; j < changes.length; j++) {
+      const a = changes[i];
+      const b = changes[j];
+      const caps = a.capabilities.filter((c) => b.capabilities.includes(c));
+      const paths = a.touches.filter((p) => b.touches.some((q) => p === q || p.startsWith(q.replace(/\/?\*\*$/, '')) || q.startsWith(p.replace(/\/?\*\*$/, ''))));
+      if (caps.length || paths.length) out.push({ a: a.name, b: b.name, capabilities: caps, paths });
+    }
+  }
+  return out;
+}
+
+export const slugify = (s) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);

package/src/lib/check-activity.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { exists, listFiles, readJson, withLock, writeJson } from './fs.js';
+import { runtimeDir } from './runtime-path.js';
+
+// The short shared lock makes registration atomic with respect to landing.
+// Checks may run concurrently; landing refuses while any check is in flight.
+export function beginCheck(root) {
+  const runtime = runtimeDir(root);
+  const marker = path.join(runtime, 'running-checks', `${crypto.randomUUID()}.json`);
+  withLock(path.join(runtime, 'landing'), () => writeJson(marker, { pid: process.pid, startedOn: new Date().toISOString() }));
+  return () => fs.rmSync(marker, { force: true });
+}
+
+export function activeChecks(root) {
+  const dir = path.join(runtimeDir(root), 'running-checks');
+  return listFiles(dir).filter((file) => {
+    const marker = path.join(dir, file);
+    if (!exists(marker)) return false;
+    const data = readJson(marker);
+    try { process.kill(data.pid, 0); return true; }
+    catch (error) {
+      if (error.code !== 'ESRCH') return true;
+      fs.rmSync(marker, { force: true });
+      return false;
+    }
+  });
+}

package/src/lib/config.js

@@ -0,0 +1,102 @@
+import YAML from 'yaml';
+import { readOr, write } from './fs.js';
+
+export const CONFIG_VERSION = 4;
+
+export const DEFAULT_CONFIG = {
+  version: CONFIG_VERSION,
+  tools: ['agents'],
+  lang: 'en',
+  profile: 'lean',
+  default_tier: 'auto',
+  confirm: { quick: 'proceed', spec: 'proceed' },
+  land: 'fold',
+  check: [],
+  guide: false,
+  hooks: true,
+  budgets: { INTENT: 120, ROADMAP: 80, NOW: 60, GLOSSARY: 200, spec: 250, rule: 120, change: 200, handoff: 100, 'always-on': 300 },
+  context: '',
+  paths: { specs: '.keelson/specs' },
+  refs: { architecture: null, decisions: null, tasks: null, ci: null },
+  models: {},
+  effort: { review_min: 'standard', plan_min: 'deep', verify_min: 'deep', escalate_after: 2 },
+};
+
+export function parseConfig(raw, configPath = 'config.yaml') {
+  let parsed = {};
+  if (raw.trim()) {
+    try {
+      parsed = YAML.parse(raw) ?? {};
+    } catch (e) {
+      throw new Error(`cannot parse ${configPath}: ${e.message}`);
+    }
+  }
+  return migrate(deepMerge(structuredClone(DEFAULT_CONFIG), parsed), parsed.version ?? 1);
+}
+
+export function loadConfig(configPath) {
+  return parseConfig(readOr(configPath, ''), configPath);
+}
+
+/** Bring older config shapes up to the current version. Pure; never touches disk. */
+export function migrate(cfg, fromVersion) {
+  const out = { ...cfg };
+  if (fromVersion < 2) {
+    out.paths = { ...DEFAULT_CONFIG.paths, ...(out.paths ?? {}) };
+    out.refs = { ...DEFAULT_CONFIG.refs, ...(out.refs ?? {}) };
+  }
+  if (fromVersion < 3) {
+    out.budgets = { ...DEFAULT_CONFIG.budgets, ...(out.budgets ?? {}) };
+    out.guide = Boolean(out.guide);
+  }
+  if (fromVersion < 4) {
+    out.hooks = out.hooks !== false;
+  }
+  out.version = CONFIG_VERSION;
+  return out;
+}
+
+export function saveConfig(configPath, cfg) {
+  write(configPath, renderConfig(cfg));
+}
+
+export function renderConfig(cfg) {
+  const doc = new YAML.Document(cfg);
+  return [
+    '# Keelson project configuration. Every key is optional; defaults are shown.',
+    '# paths.specs: where behaviour contracts live. refs.*: existing project material, referenced, never copied.',
+    '# check: commands (strings, or {name, command, kind}) that prove the code works. guide: learning mode. hooks: persist host hook installation.',
+    '# budgets: soft line budgets per document type; durable truth hard-fails at 2x, while temporary change/handoff files only warn.',
+    '# Docs: https://github.com/Atingaii/keelson/blob/main/docs/configuration.md',
+    doc.toString(),
+  ].join('\n');
+}
+
+function deepMerge(base, extra) {
+  if (Array.isArray(base) || Array.isArray(extra)) return extra ?? base;
+  if (typeof base !== 'object' || base === null) return extra ?? base;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(extra ?? {})) {
+    out[k] = typeof v === 'object' && v !== null && !Array.isArray(v) && typeof base[k] === 'object' && base[k] !== null ? deepMerge(base[k], v) : v;
+  }
+  return out;
+}
+
+/** Normalise `check:` entries: a string, or {name, command, kind}. */
+export function checkEntries(cfg) {
+  return (cfg.check ?? []).map((c, i) => {
+    if (typeof c === 'string') return { name: c, command: c, kind: guessKind(c) };
+    const command = c.command ?? c.cmd ?? '';
+    return { name: c.name ?? command ?? `check-${i + 1}`, command, kind: c.kind ?? guessKind(command) };
+  }).filter((c) => c.command);
+}
+
+function guessKind(cmd) {
+  const c = String(cmd).toLowerCase();
+  if (/lint|eslint|ruff|clippy|vet|fmt/.test(c)) return 'lint';
+  if (/tsc|typecheck|type-check|mypy|pyright/.test(c)) return 'typecheck';
+  if (/build|compile/.test(c)) return 'build';
+  if (/architecture|arch|depend|boundary|compat|contract/.test(c)) return 'fitness';
+  if (/test|spec|pytest|jest|vitest|mocha/.test(c)) return 'test';
+  return 'check';
+}

package/src/lib/decisions.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import { readJson, withLock, writeJson } from './fs.js';
+
+export function readDecisions(dir) {
+  const data = readJson(path.join(dir, 'decisions.json'), { schema: 1, decisions: [] });
+  validateDecisionData(data);
+  return data;
+}
+
+export function validateDecisionData(data) {
+  if (!data || data.schema !== 1 || !Array.isArray(data.decisions)) throw new Error('unsupported decisions schema; expected schema 1 and decisions array');
+  const ids = new Set();
+  for (const d of data.decisions) {
+    if (!d || typeof d.id !== 'string' || !/^[\p{L}\p{N}_-]+$/u.test(d.id) || ids.has(d.id)) throw new Error('decision IDs must be unique words');
+    ids.add(d.id);
+    if (!['user', 'agent', 'reality'].includes(d.owner) || !['open', 'settled', 'assumed', 'rejected'].includes(d.state) || typeof d.question !== 'string' || !d.question.trim() || !Array.isArray(d.depends)) throw new Error(`invalid decision ${d.id}`);
+    if (!Array.isArray(d.history)) throw new Error(`${d.id}: history must be an array`);
+    if (['settled', 'assumed'].includes(d.state) && (typeof d.answer !== 'string' || !d.answer.trim() || typeof d.basis !== 'string' || !d.basis.trim())) throw new Error(`${d.id}: answer and basis required`);
+    if (d.irreversible && d.state === 'assumed') throw new Error(`${d.id}: irreversible decision cannot be assumed`);
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(d) {
+    if (visiting.has(d.id)) throw new Error(`decision dependency cycle at ${d.id}`);
+    if (visited.has(d.id)) return;
+    visiting.add(d.id);
+    for (const id of d.depends) {
+      const dependency = data.decisions.find((x) => x.id === id);
+      if (!dependency) throw new Error(`${d.id}: missing dependency ${id}`);
+      visit(dependency);
+    }
+    visiting.delete(d.id); visited.add(d.id);
+  }
+  data.decisions.forEach(visit);
+  return data;
+}
+
+export function decisionFrontier(data, limit = 3) {
+  const ready = data.decisions.filter((d) => d.state === 'open' && d.depends.every((id) => data.decisions.some((x) => x.id === id && x.state === 'settled')));
+  return {
+    questions: ready.filter((d) => d.owner === 'user').slice(0, limit),
+    investigate: ready.filter((d) => d.owner !== 'user'),
+    blocked: data.decisions.filter((d) => d.state === 'open' && !ready.includes(d)),
+    assumptions: data.decisions.filter((d) => d.state === 'assumed'),
+    complete: data.decisions.every((d) => ['settled', 'rejected'].includes(d.state)),
+  };
+}
+
+export function updateDecisions(dir, mutate) {
+  const file = path.join(dir, 'decisions.json');
+  return withLock(file, () => {
+    const data = readDecisions(dir);
+    mutate(data);
+    // Validate before writing by sharing the validator without a temporary file.
+    validateDecisionData(data);
+    writeJson(file, data);
+    return data;
+  });
+}