@zyaiting/keelson 0.4.0

package/src/commands/land.js

@@ -0,0 +1,258 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { requireProjectRoot, projectPaths, resolveWithin } from '../lib/paths.js';
+import { exists, read, write, rmrf, mkdirp, readOr, withLock } from '../lib/fs.js';
+import { runtimeDir } from '../lib/runtime-path.js';
+import { recordStatement } from '../lib/evidence.js';
+import { activeChecks } from '../lib/check-activity.js';
+import { recoverLanding, landingTransaction } from '../lib/transaction.js';
+import { loadConfig } from '../lib/config.js';
+import { loadChange, loadAllChanges, sharedContracts } from '../lib/changes.js';
+import { evaluateLifecycle } from '../lib/lifecycle.js';
+import { parseSpec, parseDelta, renderSpec, parseFrontmatter } from '../lib/markdown.js';
+import { worktreeFingerprint } from '../lib/git.js';
+import { ok, warn, info, heading } from '../lib/out.js';
+import { clearChangeBindings, readSession } from '../lib/session.js';
+import { budgetStatus } from '../lib/health.js';
+import { readCapabilitySpec, planCapabilityStorage, writeCapabilityStorage, capabilityStorageOptions, changeSpecDrift } from '../lib/specs.js';
+
+export function mergeDelta(mainText, deltaText, capability) {
+  const main = mainText ? parseSpec(mainText) : { purpose: '', requirements: [], decisions: [] };
+  const d = parseDelta(parseFrontmatter(deltaText).body);
+  if (d.issues?.length) throw new Error(`malformed delta: ${d.issues.join('; ')}`);
+  const names = [...d.added, ...d.modified, ...d.removed].map((r) => r.name.normalize('NFC').toLowerCase());
+  if (new Set(names).size !== names.length) throw new Error('malformed delta: duplicate requirement');
+  if ([...d.added, ...d.modified].some((r) => !r.body.trim())) throw new Error('malformed delta: empty requirement body');
+  const reqs = [...main.requirements];
+  const report = { added: [], modified: [], removed: [], missing: [] };
+  for (const r of d.removed) {
+    const i = reqs.findIndex((x) => x.name.toLowerCase() === r.name.toLowerCase());
+    if (i === -1) report.missing.push(`REMOVED "${r.name}" not found`);
+    else {
+      reqs.splice(i, 1);
+      report.removed.push(r.name);
+    }
+  }
+  for (const r of d.modified) {
+    const i = reqs.findIndex((x) => x.name.toLowerCase() === r.name.toLowerCase());
+    if (i === -1) {
+      report.missing.push(`MODIFIED "${r.name}" not found; added instead`);
+      reqs.push(r);
+    } else {
+      reqs[i] = r;
+      report.modified.push(r.name);
+    }
+  }
+  for (const r of d.added) {
+    const i = reqs.findIndex((x) => x.name.toLowerCase() === r.name.toLowerCase());
+    if (i === -1) {
+      reqs.push(r);
+      report.added.push(r.name);
+    } else {
+      reqs[i] = r;
+      report.modified.push(`${r.name} (ADDED over existing)`);
+    }
+  }
+  return { text: renderSpec({ ...main, name: main.name || capability, requirements: reqs }), report };
+}
+
+export function appendDecisions(specText, capability, lines) {
+  const s = specText ? parseSpec(specText) : { purpose: '', requirements: [], decisions: [] };
+  const existing = new Set(s.decisions.map((d) => d.toLowerCase()));
+  const fresh = lines.filter((l) => !existing.has(`${capability}: ${l}`.toLowerCase()) && !existing.has(l.toLowerCase()));
+  return renderSpec({ ...s, name: s.name || capability, decisions: [...s.decisions, ...fresh.map((l) => `${capability}: ${l}`)] });
+}
+
+/** Everything that stops a landing. Pure; used by `land` and `doctor`. */
+export function landingBlockers(c, fingerprint, { confirmAssumptions = false, acceptDrift = false, specsDir, activeNames = [] } = {}) {
+  const contractDrift = specsDir ? changeSpecDrift(c, specsDir) : [];
+  return evaluateLifecycle(c, fingerprint, {
+    activeNames,
+    confirmAssumptions,
+    contractDrift,
+    acceptDrift,
+  }).blockers;
+}
+
+export async function land(args, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  return withLock(path.join(runtimeDir(root), 'landing'), () => {
+    if (activeChecks(root).length) throw new Error('cannot land while checks are running; wait for every active check to finish');
+    if (recoverLanding(root)) throw new Error('restored an interrupted landing; review the restored files and run checks again');
+    return landUnlocked(args, cwd);
+  });
+}
+
+function landUnlocked({ flags, positional }, cwd) {
+  const root = requireProjectRoot(cwd);
+  if (activeChecks(root).length) throw new Error('cannot land while checks are running; wait for every active check to finish');
+  if (flags.force && (typeof flags.reason !== 'string' || !flags.reason.trim())) throw new Error('--force requires --reason "<owner-authorized reason>"; every bypass is archived.');
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  let name = positional[0];
+  if (!name) {
+    const all = loadAllChanges(p.changes);
+    const focused = readSession(root).state?.change;
+    if (focused && all.some((c) => c.name === focused)) name = focused;
+    else if (all.length === 1) name = all[0].name;
+    else throw new Error(all.length ? `several active changes (${all.map((c) => c.name).join(', ')}); bind one with \`keelson focus <name>\` or name one` : 'no active change to land');
+  }
+  const allChanges = loadAllChanges(p.changes);
+  const c = loadChange(p.changes, name);
+  if (!c) throw new Error(`no change named "${name}"`);
+  const fp = worktreeFingerprint(root);
+  const activeNames = new Set(allChanges.map((x) => x.name));
+  const blockers = landingBlockers(c, fp, { confirmAssumptions: Boolean(flags.confirmAssumptions), acceptDrift: Boolean(flags.acceptDrift), specsDir: p.specs, activeNames });
+  if (blockers.length && !flags.force) throw new Error(`cannot land "${name}":\n  - ${blockers.join('\n  - ')}\nFix them, or pass --force if the user explicitly asked.`);
+  if (blockers.length) warn(`landing with --force despite:\n  - ${blockers.join('\n  - ')}`);
+  const uncheckedPlan = c.progress.total ? c.progress.total - c.progress.done : 0;
+  if (uncheckedPlan > 0) warn(`${uncheckedPlan} task(s) remain unchecked; tasks are planning notes, not landing gates. Reconcile or remove stale plan items if they still matter.`);
+
+  heading(`Landing ${name} (${c.tier})`);
+  const dry = Boolean(flags.dryRun);
+  for (const k of sharedContracts(allChanges).filter((k) => k.a === name || k.b === name)) {
+    const other = k.a === name ? k.b : k.a;
+    const o = loadChange(p.changes, other);
+    warn(`shared contract with active change ${other}${o?.owner ? ` (${o.owner})` : ''}: ${[...k.capabilities.map((cap) => `${p.specsRel}/${cap}`), ...k.paths].join(', ')} — its delta will drift after this landing and its owner must re-read the merged spec before landing`);
+  }
+  // Project every durable write before mutating project truth.
+  const projected = new Map();
+  const deltaReports = [];
+  for (const df of c.deltaFiles) {
+    const cap = path.dirname(df).replace(/\\/g, '/');
+    if (cap === '.' || cap.includes('<')) {
+      warn(`skipping delta at specs/${df}: capability directory is a placeholder`);
+      continue;
+    }
+    const mainPath = path.join(p.specs, cap, 'spec.md');
+    const baseText = projected.get(cap)?.text ?? readCapabilitySpec(p.specs, cap);
+    const { text, report } = mergeDelta(baseText, read(path.join(c.dir, 'specs', df)), cap);
+    projected.set(cap, { path: mainPath, text });
+    deltaReports.push({ cap, report });
+  }
+
+  const byCap = new Map();
+  for (const d of c.decisions) {
+    if (!d.capability) {
+      warn(`decision without capability prefix skipped: "${d.text}"`);
+      continue;
+    }
+    byCap.set(d.capability, [...(byCap.get(d.capability) ?? []), d.text]);
+  }
+  for (const [cap, lines] of byCap) {
+    const mainPath = path.join(p.specs, cap, 'spec.md');
+    const baseText = projected.get(cap)?.text ?? readCapabilitySpec(p.specs, cap);
+    projected.set(cap, { path: mainPath, text: appendDecisions(baseText, cap, lines) });
+  }
+
+  for (const [cap, item] of projected) {
+    resolveWithin(p.specs, cap);
+    const storage = planCapabilityStorage(cap, item.text, cfg.budgets?.spec, capabilityStorageOptions(p.specs, cap));
+    item.storage = storage;
+    if (storage.hardOver.length && !flags.force) {
+      const detail = storage.hardOver.map((f) => `${f.rel} ${f.lines} lines`).join(', ');
+      throw new Error(`cannot land "${name}": auto-sharding still leaves oversized spec shard(s) in ${p.specsRel}/${cap}: ${detail} (hard limit ${storage.hardLimit}). Semantically compact that requirement first; --force is only for an explicit owner override.`);
+    }
+    if (storage.mode === 'sharded') info(`${p.specsRel}/${cap}: auto-organize → bounded index + ${storage.files.length - 1} shard(s)`);
+    if (storage.hardOver.length) warn(`${p.specsRel}/${cap}: owner forced oversized shard(s): ${storage.hardOver.map((f) => f.rel).join(', ')}`);
+  }
+
+  let nextNowText = null;
+  if (flags.now) {
+    const body = String(flags.now).trim().replace(/^#\s*Now\s*\n+/i, '');
+    nextNowText = `# Now\n\n${body}\n`;
+    const pressure = budgetStatus(nextNowText, cfg.budgets?.NOW);
+    if (pressure.state === 'hard' && !flags.force) {
+      throw new Error(`cannot land "${name}": projected NOW.md is ${pressure.lines} lines, above hard limit ${pressure.hardLimit} (budget ${pressure.budget}). Rewrite NOW as current state only.`);
+    }
+  }
+
+  const mode = flags.keep || flags.force || exists(path.join(c.dir, 'ledger.jsonl')) ? 'keep' : cfg.land;
+  let dest = path.join(p.archive, `${new Date().toISOString().slice(0, 10)}-${name}`);
+  if (exists(dest)) dest += `-${Date.now()}`;
+  const apply = () => {
+  if (!dry && flags.force) {
+    const reason = String(flags.reason).trim();
+    const bypassed = [...blockers, ...[...projected].flatMap(([cap, item]) => item.storage.hardOver.map((f) => `oversized ${cap}/${f.rel}: ${f.lines} lines`))];
+    if (nextNowText !== null && budgetStatus(nextNowText, cfg.budgets?.NOW).state === 'hard') bypassed.push('NOW.md hard budget exceeded');
+    if (!bypassed.length) bypassed.push('explicit force requested (no lifecycle blockers)');
+    write(path.join(c.dir, 'forced.md'), `# Forced landing\n\nReason: ${reason}\n\n${bypassed.map((b) => `- ${b}`).join('\n')}\n`);
+    recordStatement(root, c.dir, {
+      _type: 'https://in-toto.io/Statement/v1',
+      subject: [{ name: 'worktree', digest: { [fp.length === 40 ? 'gitTree' : 'sha256']: fp } }],
+      predicateType: 'https://github.com/Atingaii/keelson/override/v1',
+      predicate: { reason, bypassed, timestamp: new Date().toISOString() },
+    });
+  }
+  for (const [cap, item] of projected) if (!dry) writeCapabilityStorage(p.specs, cap, item.storage);
+  for (const { cap, report } of deltaReports) {
+    ok(`${p.specsRel}/${cap}: +${report.added.length} added, ~${report.modified.length} modified, -${report.removed.length} removed${report.missing.length ? ` (${report.missing.join('; ')})` : ''}`);
+  }
+  for (const [cap, lines] of byCap) {
+    ok(`${p.specsRel}/${cap}: ${lines.length} decision line${lines.length > 1 ? 's' : ''} folded${c.assumed.length ? ` (${c.assumed.length} confirmed by --confirm-assumptions)` : ''}`);
+  }
+  if (mode === 'keep') {
+    if (!dry) {
+      mkdirp(p.archive);
+      write(path.join(c.dir, 'landed.json'), JSON.stringify({ status: 'integrated', change: name, at: new Date().toISOString(), forced: Boolean(flags.force) }) + '\n');
+      fs.renameSync(c.dir, dest);
+    }
+    ok(`archived → .keelson/changes/archive/${path.basename(dest)}`);
+  } else {
+    if (!dry) rmrf(c.dir);
+    ok(`removed .keelson/changes/${name} (ledger and handoff stay in git history)`);
+  }
+  if (!dry) clearChangeBindings(root, name);
+  if (nextNowText !== null) {
+    if (!dry) write(p.now, nextNowText);
+    ok('NOW.md rewritten');
+  } else info('session focus was cleared for the landed change; NOW.md is optional project-level context, not the source of work lifecycle state');
+  info('commit the landing together with the last code change; release status is derived from git tags');
+  if (dry) warn('dry run: nothing written');
+  return 0;
+  };
+  if (dry) return apply();
+  return landingTransaction(root, [
+    ...[...projected.keys()].map((cap) => resolveWithin(p.specs, cap)),
+    c.dir, dest, p.now, p.sessions,
+  ], apply);
+}
+
+export async function cancel(args, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  return withLock(path.join(runtimeDir(root), 'landing'), () => {
+    if (activeChecks(root).length) throw new Error('cannot cancel while checks are running; wait for them to finish');
+    if (recoverLanding(root)) throw new Error('restored an interrupted landing; review the files before cancelling');
+    return cancelUnlocked(args, cwd);
+  });
+}
+
+function cancelUnlocked({ flags, positional }, cwd) {
+  const root = requireProjectRoot(cwd);
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  let name = positional[0];
+  if (!name) {
+    const all = loadAllChanges(p.changes);
+    const focused = readSession(root).state?.change;
+    if (focused && all.some((c) => c.name === focused)) name = focused;
+    else if (all.length === 1) name = all[0].name;
+    else throw new Error('usage: keelson cancel <name> [--reason "<why>"]');
+  }
+  const c = loadChange(p.changes, name);
+  if (!c) throw new Error(`no change named "${name}"`);
+  const reason = flags.reason ? String(flags.reason) : 'no reason given';
+  let dest = path.join(p.archive, `${new Date().toISOString().slice(0, 10)}-${name}-cancelled`);
+  if (exists(dest)) dest += `-${Date.now()}`;
+  return landingTransaction(root, [c.dir, dest, p.sessions], () => {
+  const cm = path.join(c.dir, 'change.md');
+  write(cm, read(cm).replace(/^status:.*$/m, `status: cancelled`).replace(/\n*$/, `\n\n## Cancelled\n${new Date().toISOString().slice(0, 10)}: ${reason}\n`));
+  write(path.join(c.dir, 'landed.json'), JSON.stringify({ status: 'cancelled', change: name, at: new Date().toISOString() }) + '\n');
+  mkdirp(p.archive);
+  fs.renameSync(c.dir, dest);
+  clearChangeBindings(root, name);
+  ok(`cancelled ${name} → ${path.relative(root, dest)} (nothing merged into specs)`);
+  info('if a decision was ruled out for good, record it in the affected spec\'s Decisions so the path is not retried');
+  return 0;
+  });
+}

package/src/commands/models.js

@@ -0,0 +1,62 @@
+import { requireProjectRoot, findProjectRoot, projectPaths } from '../lib/paths.js';
+import { loadConfig } from '../lib/config.js';
+import { TIERS, resolveAll, resolveTier, detectAndCache, loadCache, refresh, loadRegistry, loadUserOverrides, saveUserOverrides, datedIdPatterns } from '../lib/models.js';
+import { PLATFORMS } from '../platforms/index.js';
+import { heading, ok, warn, info, dim } from '../lib/out.js';
+
+export async function models({ flags, positional }, cwd = process.cwd()) {
+  const root = findProjectRoot(cwd);
+  const cfg = root ? loadConfig(projectPaths(root).config) : null;
+  const platform = flags.platform ?? cfg?.tools?.[0] ?? 'claude';
+  if (!PLATFORMS[platform]) throw new Error(`unknown platform "${platform}"`);
+
+  if (positional[0] === 'rank') {
+    const [, alias, tier] = positional;
+    if (!alias || !TIERS.includes(tier)) throw new Error('usage: keelson models rank <alias> <light|standard|deep> [--platform <id>]');
+    for (const re of datedIdPatterns()) if (re.test(alias)) throw new Error(`"${alias}" looks like a dated model ID; use the family alias instead`);
+    const o = loadUserOverrides();
+    o[platform] ??= {};
+    o[platform][tier] = alias;
+    saveUserOverrides(o);
+    ok(`~/.keelson/models.yaml: ${platform}.${tier} = ${alias}`);
+    return 0;
+  }
+  if (flags.detect) {
+    const c = detectAndCache();
+    ok('detected and cached');
+    if (flags.json) console.log(JSON.stringify(c, null, 2));
+    else for (const [id, t] of Object.entries(c.tools)) console.log(`  ${id.padEnd(9)} ${t.installed ? `installed ${dim(t.version ?? '')}` : dim('not found')}${t.defaultModel ? `  default: ${t.defaultModel}` : ''}`);
+    return 0;
+  }
+  if (flags.refresh) {
+    const r = await refresh({ withProviders: !flags.noProviders });
+    ok(`registry: ${r.registry}`);
+    for (const [pid, s] of Object.entries(r.providers)) info(`${pid}: ${s}`);
+    if (r.newModels.length) {
+      warn(`${r.newModels.length} new model(s) seen in provider catalogues:`);
+      for (const m of r.newModels) console.log(`  ${m.id}  ${m.inferredTier ? dim(`inferred ${m.inferredTier}`) : dim('unranked — `keelson models rank <alias> <tier>` when the host supports it')}`);
+    }
+    return 0;
+  }
+  if (flags.resolve) {
+    const tier = String(flags.resolve);
+    const r = resolveTier(tier, { platform, projectModels: cfg?.models ?? {} });
+    if (flags.json) console.log(JSON.stringify({ platform, tier, ...r }));
+    else console.log(r.alias ?? '');
+    return r.alias ? 0 : 1;
+  }
+  // default: table
+  const cache = loadCache();
+  const reg = loadRegistry();
+  heading(`Keelson models — platform: ${platform} ${dim(`(registry ${reg.updated})`)}`);
+  const all = resolveAll(platform, cfg?.models ?? {});
+  for (const t of TIERS) console.log(`  ${t.padEnd(9)} → ${(all[t].alias ?? '—').padEnd(12)} ${dim(all[t].source)}`);
+  if (!PLATFORMS[platform] || !reg.platforms?.[platform]?.subagents) info(`${PLATFORMS[platform].label} has no subagent dispatch in the registry; tiers still guide inline effort`);
+  console.log('');
+  if (cache) {
+    console.log(dim(`local detection${cache.stale ? ' (stale, run --detect)' : ''}: ${Object.entries(cache.tools).filter(([, t]) => t.installed).map(([id, t]) => `${id}${t.defaultModel ? `=${t.defaultModel}` : ''}`).join(', ') || 'no tools found'}`));
+    if (cache.unranked?.length) warn(`${cache.unranked.length} unranked model(s) from provider catalogues: ${cache.unranked.map((m) => m.id).join(', ')}`);
+  } else info('no local detection yet — run `keelson models --detect`');
+  if (flags.json) console.log(JSON.stringify({ platform, tiers: all, cache }, null, 2));
+  return 0;
+}

package/src/commands/new.js

@@ -0,0 +1,70 @@
+import path from 'node:path';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { exists, write, read, mkdirp, readOr } from '../lib/fs.js';
+import { loadConfig } from '../lib/config.js';
+import { skillSource } from '../platforms/index.js';
+import { slugify, TIERS } from '../lib/changes.js';
+import { git, isGitRepo, currentBranch, gitUserName } from '../lib/git.js';
+import { list } from '../lib/args.js';
+import { ok, info, warn } from '../lib/out.js';
+import { bindSession } from '../lib/session.js';
+import { readCapabilitySpec, specFingerprint } from '../lib/specs.js';
+
+const fill = (tpl, vars) => tpl.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`);
+export const specBase = specFingerprint;
+
+export async function newChange({ flags, positional }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  const raw = positional[0] ?? flags.name;
+  if (!raw) throw new Error('usage: keelson new <name> [--tier quick|spec] [--capability a,b] [--touches src/api/**,...] [--depends other-change] [--worktree]');
+  const name = slugify(raw);
+  const tier = (flags.tier ?? 'quick').toLowerCase();
+  if (!TIERS.includes(tier)) throw new Error(`tier must be one of ${TIERS.join('|')}`);
+  const dir = path.join(p.changes, name);
+  if (exists(dir)) throw new Error(`change "${name}" already exists`);
+  const tpl = path.join(skillSource(cfg.lang), 'templates');
+  const caps = list(flags.capability).map(slugify);
+  const owner = flags.owner ?? gitUserName(root);
+  const branch = isGitRepo(root) ? currentBranch(root) : null;
+  const vars = { name, title: raw, tier, date: new Date().toISOString().slice(0, 10), capability: caps[0] ?? '<capability>' };
+
+  let worktree = null;
+  if (flags.worktree) {
+    if (!isGitRepo(root)) throw new Error('--worktree needs a git repository');
+    const wt = path.resolve(root, '..', `${path.basename(root)}-${name}`);
+    const out = git(root, ['worktree', 'add', '-b', name, wt], { allowFail: true });
+    if (out === null && !exists(wt)) throw new Error(`git worktree add failed for ${wt}`);
+    worktree = wt;
+    ok(`worktree ${wt} on branch ${name}`);
+  }
+
+  const front = [
+    `tier: ${tier}`,
+    `created: ${vars.date}`,
+    `status: ${tier === 'spec' ? 'clarifying' : 'in-progress'}`,
+    `owner: ${owner}`,
+    ...(worktree ? [`branch: ${name}`, `worktree: ${path.relative(root, worktree)}`] : branch ? [`branch: ${branch}`] : []),
+    ...(list(flags.depends).length ? [`depends: [${list(flags.depends).join(', ')}]`] : []),
+    ...(list(flags.touches).length ? [`touches: [${list(flags.touches).join(', ')}]`] : []),
+  ];
+  const body = fill(read(path.join(tpl, tier === 'quick' ? 'change-quick.md' : 'change.md')), vars).replace(/^---\n[\s\S]*?\n---\n/, '');
+  mkdirp(dir);
+  write(path.join(dir, 'change.md'), `---\n${front.join('\n')}\n---\n${body}`);
+  if (tier === 'spec') write(path.join(dir, 'tasks.md'), fill(read(path.join(tpl, 'tasks.md')), vars));
+  // ledger.md and handoff.md are event artifacts: create them only when evidence or a handoff actually exists.
+  for (const cap of caps) {
+    const main = readCapabilitySpec(p.specs, cap);
+    const delta = fill(read(path.join(tpl, 'delta-spec.md')), { ...vars, capability: cap });
+    // Stamp the base so `keelson land` can detect that the main spec moved while this delta was being written.
+    write(path.join(dir, 'specs', cap, 'spec.md'), `---\nbase: ${main ? specBase(main) : 'new'}\n---\n${delta}`);
+  }
+  ok(`created ${path.relative(root, dir)} (${tier}${owner ? `, owner ${owner}` : ''}${branch && !worktree ? `, branch ${branch}` : ''})`);
+  const focused = bindSession(root, name, { branch: worktree ? name : branch, source: 'new' });
+  if (focused) info(`session focus → ${name}`);
+  info(tier === 'spec' ? `fill change.md${caps.length ? ', specs/<capability>/spec.md' : ''}, then tasks.md — see references/plan.md` : 'fill change.md acceptance; tasks.md is optional for a quick change');
+  if (tier === 'spec' && !caps.length) warn('spec tier without --capability: add specs/<capability>/spec.md by hand if behaviour changes');
+  if (flags.json) console.log(JSON.stringify({ name, tier, dir, owner, branch: worktree ? name : branch, worktree, capabilities: caps, focused: Boolean(focused) }));
+  return 0;
+}

package/src/commands/platforms.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import { PLATFORMS, PLATFORM_IDS } from '../platforms/index.js';
+import { detectLocal } from '../lib/models.js';
+import { findProjectRoot, projectPaths } from '../lib/paths.js';
+import { loadConfig } from '../lib/config.js';
+import { exists } from '../lib/fs.js';
+import { heading, dim } from '../lib/out.js';
+
+export async function platforms({ flags }, cwd = process.cwd()) {
+  const root = findProjectRoot(cwd);
+  const cfg = root ? loadConfig(projectPaths(root).config) : null;
+  const det = detectLocal().tools;
+  const portableConfigured = Boolean(root && cfg?.tools?.includes('agents') && exists(path.join(root, 'AGENTS.md')) && exists(path.join(root, '.agents', 'skills', 'keelson', 'SKILL.md')));
+  const rows = PLATFORM_IDS.map((id) => {
+    const p = PLATFORMS[id];
+    const configured = id === 'agents' ? portableConfigured : cfg?.tools?.includes(id) ?? false;
+    const sessionFocus = p.sessionFocus ?? 'degraded';
+    const effectiveSessionFocus =
+      configured && cfg?.hooks === false && p.sessionAdapter && p.sessionAdapter !== 'pi-env'
+        ? 'degraded'
+        : sessionFocus;
+    return { id, label: p.label, support: p.support ?? 'first-class', sessionFocus, effectiveSessionFocus, instructions: p.instructions, skills: p.skillsDir, skillDiscovery: p.skillsDir, rules: p.rulesFile ?? null, hooks: p.hooks, confidence: p.confidence, examples: p.examples ?? null, installed: det[id]?.installed ?? null, configured };
+  });
+  if (flags.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  heading(`Keelson platforms (${rows.length})`);
+  console.log(dim('support: first-class = tested discovery/lifecycle contract · portable = standards fallback; sessionFocus shows effective project behavior (native|degraded)'));
+  console.log('');
+  const w = Math.max(...rows.map((r) => r.label.length));
+  for (const r of rows) {
+    const marks = [r.configured ? 'configured' : null, r.installed ? 'on this machine' : null].filter(Boolean).join(', ');
+    console.log(`  --${r.id.padEnd(12)} ${r.label.padEnd(w)}  ${r.instructions.padEnd(16)} ${r.skillDiscovery.padEnd(20)} ${(r.support ?? '').padEnd(11)} ${(r.effectiveSessionFocus ?? r.sessionFocus ?? 'degraded').padEnd(9)} ${r.hooks ? 'hooks ' : '      '} ${dim(r.confidence)}${marks ? dim(`  [${marks}]`) : ''}`);
+  }
+  console.log('');
+  console.log(dim('guidance stays in the installed package by default; use `keelson guide` or opt in to `keelson init --vendor` for a project copy'));
+  return 0;
+}

package/src/commands/retro.js

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { readOr, walk, listDirs, read, exists } from '../lib/fs.js';
+import { skillSource } from '../platforms/index.js';
+import { parseLedger, ROOT_CAUSES } from '../lib/markdown.js';
+import { loadAllChanges } from '../lib/changes.js';
+import { historicalLedgers } from '../lib/git.js';
+import { heading, info, warn, ok, dim } from '../lib/out.js';
+
+export function collectLedgers(root) {
+  const p = projectPaths(root);
+  const out = [];
+  for (const c of loadAllChanges(p.changes)) out.push({ source: `active:${c.name}`, entries: c.ledger });
+  for (const d of listDirs(p.archive)) {
+    const f = path.join(p.archive, d, 'ledger.md');
+    if (exists(f)) out.push({ source: `archive:${d}`, entries: parseLedger(read(f)) });
+  }
+  for (const h of historicalLedgers(root)) out.push({ source: `git:${h.commit.slice(0, 7)}`, entries: parseLedger(h.content) });
+  return out;
+}
+
+export function computeMetrics(ledgers) {
+  const entries = ledgers.flatMap((l) => l.entries);
+  const rootCauses = Object.fromEntries(ROOT_CAUSES.map((c) => [c, 0]));
+  for (const e of entries) if (e.kind === 'root-cause' && e.category in rootCauses) rootCauses[e.category]++;
+  const dispatches = entries.filter((e) => e.kind === 'dispatch');
+  const escalations = entries.filter((e) => e.kind === 'escalate');
+  const byTier = {};
+  for (const t of ['light', 'standard', 'deep']) {
+    const d = dispatches.filter((x) => x.tier === t);
+    const esc = escalations.filter((x) => x.from === t).length;
+    const fails = d.filter((x) => x.result === 'fail').length;
+    const passes = d.filter((x) => x.result === 'pass').length;
+    const known = passes + fails;
+    byTier[t] = { dispatches: d.length, failures: fails, unknown: d.length - known, escalatedFrom: esc, firstPass: known ? Math.round((passes / known) * 100) : null };
+  }
+  const verifies = entries.filter((e) => e.kind === 'verify');
+  return {
+    ledgers: ledgers.length,
+    entries: entries.length,
+    rulings: entries.filter((e) => e.kind === 'ruling').length,
+    rootCauses,
+    rootCauseTotal: Object.values(rootCauses).reduce((a, b) => a + b, 0),
+    byTier,
+    verifies: { total: verifies.length, failed: verifies.filter((v) => v.exit !== 0).length },
+  };
+}
+
+/** Parse guidance annotations from a vendored skill or the package guidance. */
+export function collectGuidance(root) {
+  const out = [];
+  const vendored = path.join(root, '.keelson', 'skill', 'references');
+  const dir = exists(vendored) ? vendored : path.join(skillSource('en'), 'references');
+  const relBase = exists(vendored) ? '.keelson/skill/references' : 'package:skills/keelson/references';
+  for (const f of walk(dir)) {
+    const txt = read(path.join(dir, f));
+    for (const m of txt.matchAll(/<!--\s*keelson:\s*id=([\w.-]+)\s*\|\s*without:\s*([^|]*?)\s*\|\s*sunset:\s*(.*?)\s*-->/g)) {
+      out.push({ id: m[1], without: m[2].trim(), sunset: m[3].trim(), file: `${relBase}/${f}` });
+    }
+  }
+  return out;
+}
+
+export function suggestions(metrics, guidance) {
+  const s = [];
+  const rc = metrics.rootCauses;
+  if (metrics.rootCauseTotal >= 20 && rc['guessed-fix'] === 0) s.push({ kind: 'prune', id: 'debug.reproduce-first', why: `0 guessed-fix in ${metrics.rootCauseTotal} root-cause entries; the reproduce-first guidance is no longer preventing anything` });
+  if (rc['cross-layer'] >= 3) s.push({ kind: 'rule', why: `${rc['cross-layer']} cross-layer root causes; add a contract rule or a spec requirement for the layers involved` });
+  if (rc['missing-rule'] >= 3) s.push({ kind: 'rule', why: `${rc['missing-rule']} bugs traced to a missing convention; check that each one produced a rule` });
+  if (rc['propagation'] >= 3) s.push({ kind: 'rule', why: `${rc['propagation']} propagation failures; add a "find all call sites" check to the relevant rules file` });
+  const light = metrics.byTier.light;
+  if (light.dispatches >= 20 && light.firstPass !== null && light.firstPass < 70) s.push({ kind: 'effort', why: `light-tier first-pass rate ${light.firstPass}% over ${light.dispatches} dispatches; tag fewer tasks as light or tighten the light criteria` });
+  if (light.dispatches >= 100 && light.firstPass >= 90) s.push({ kind: 'effort', id: 'plan.effort', why: `light-tier first-pass rate ${light.firstPass}% over ${light.dispatches} dispatches; light can take more than it does now` });
+  const std = metrics.byTier.standard;
+  if (std.dispatches >= 20 && std.escalatedFrom / std.dispatches > 0.3) s.push({ kind: 'effort', why: `standard escalates to deep ${Math.round((std.escalatedFrom / std.dispatches) * 100)}% of the time; route design-adjacent tasks to deep up front` });
+  if (metrics.verifies.total >= 10 && metrics.verifies.failed / metrics.verifies.total > 0.4) s.push({ kind: 'verify', why: `${metrics.verifies.failed}/${metrics.verifies.total} verify entries failed; checks may be flaky or tasks are being ticked before verification` });
+  for (const g of guidance) {
+    const m = g.sunset.match(/(guessed-fix|cross-layer|missing-rule|propagation|test-gap|implicit-assumption)\s*=\s*0\s*across the last\s*(\d+)/i);
+    if (m && metrics.rootCauseTotal >= Number(m[2]) && rc[m[1]] === 0 && !s.some((x) => x.id === g.id)) s.push({ kind: 'prune', id: g.id, why: `sunset condition met: ${g.sunset}` });
+  }
+  return s;
+}
+
+export async function retro({ flags }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  const ledgers = collectLedgers(root);
+  const metrics = computeMetrics(ledgers);
+  const guidance = collectGuidance(root);
+  const sug = suggestions(metrics, guidance);
+  if (flags.json) {
+    console.log(JSON.stringify({ metrics, guidance, suggestions: sug }, null, 2));
+    return 0;
+  }
+  heading('Keelson retro');
+  console.log(`${metrics.ledgers} ledgers (active + archive + git history) · ${metrics.entries} entries · ${metrics.rulings} rulings`);
+  console.log('');
+  heading('Root causes');
+  for (const [k, v] of Object.entries(metrics.rootCauses)) console.log(`  ${k.padEnd(20)} ${v}`);
+  console.log('');
+  heading('Effort tiers');
+  for (const [t, m] of Object.entries(metrics.byTier)) console.log(`  ${t.padEnd(9)} dispatches ${m.dispatches}  failures ${m.failures}${m.unknown ? `  no-result ${m.unknown}` : ''}  escalated ${m.escalatedFrom}  first-pass ${m.firstPass ?? '—'}${m.firstPass !== null ? '%' : ''}`);
+  console.log(`  verify entries ${metrics.verifies.total}, failed ${metrics.verifies.failed}`);
+  console.log('');
+  heading('Guidance with sunset conditions');
+  if (!guidance.length) console.log(dim('  none found in package guidance'));
+  for (const g of guidance) console.log(`  ${g.id.padEnd(26)} ${dim(g.sunset)}`);
+  console.log('');
+  heading('Suggestions');
+  if (!sug.length) console.log(dim('  nothing to change yet — keep working; suggestions need data'));
+  for (const s of sug) console.log(`  [${s.kind}] ${s.id ? s.id + ': ' : ''}${s.why}`);
+  if (metrics.entries === 0) warn('no ledger entries found. Ledgers are written during build/verify; see the skill references.');
+  else ok('done');
+  return 0;
+}