@zyaiting/keelson 0.4.0

package/src/commands/attest.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { loadAllChanges, loadChange } from '../lib/changes.js';
+import { listDirs, readOr } from '../lib/fs.js';
+import { verificationStatus } from '../lib/lifecycle.js';
+import { worktreeFingerprint } from '../lib/git.js';
+
+const escaped = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function archivedChangeName(archiveDir, directory) {
+  const landed = readOr(path.join(archiveDir, directory, 'landed.json')).trim();
+  if (!landed) return null;
+  try {
+    const data = JSON.parse(landed);
+    return typeof data.change === 'string' && data.change ? data.change : null;
+  } catch {
+    return null;
+  }
+}
+
+function legacyArchiveMatches(directory, name) {
+  // A plain dated legacy directory is the only shape that proves its original
+  // name. A "-cancelled" or numeric suffix can itself be part of that name.
+  return new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escaped(name)}$`).test(directory);
+}
+
+function uncertainLegacyArchives(directory, name) {
+  return new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escaped(name)}(?:-cancelled|-\\d+)(?:-\\d+)?$`).test(directory);
+}
+
+function resolveArchivedChange(archiveDir, name) {
+  const exact = loadChange(archiveDir, name);
+  if (exact) return exact;
+
+  const candidates = listDirs(archiveDir)
+    .map((directory) => ({
+      directory,
+      recorded: archivedChangeName(archiveDir, directory),
+      change: loadChange(archiveDir, directory),
+    }))
+    .filter(({ change }) => change);
+  const matches = candidates
+    .filter(({ recorded, directory: archiveName }) => {
+      return recorded === name || (!recorded && legacyArchiveMatches(archiveName, name));
+    });
+  const uncertain = candidates.filter(({ recorded, directory }) => !recorded && uncertainLegacyArchives(directory, name));
+  if (uncertain.length) {
+    throw new Error(`cannot prove original name "${name}" from legacy archive suffixes; specify an exact archive directory: ${uncertain.map(({ directory }) => directory).join(', ')}`);
+  }
+  if (matches.length === 1) return matches[0].change;
+  if (matches.length > 1) {
+    throw new Error(`ambiguous archived change "${name}"; specify an exact archive directory: ${matches.map(({ directory }) => directory).join(', ')}`);
+  }
+  return null;
+}
+
+export async function attest({ positional }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  const p = projectPaths(root);
+  const changes = loadAllChanges(p.changes);
+  const name = positional[0] ?? (changes.length === 1 ? changes[0].name : null);
+  if (!name) throw new Error('usage: keelson attest <change>');
+  // An active change always wins. Archived changes may be addressed by their
+  // exact directory, or by the original change name only when it is unique.
+  const c = loadChange(p.changes, name) ?? resolveArchivedChange(p.archive, name);
+  if (!c) throw new Error(`no change named ${name}`);
+  const verification = verificationStatus(c, worktreeFingerprint(root));
+  const envelopes = readOr(path.join(c.dir, 'ledger.jsonl')).trim().split('\n').filter(Boolean).map((line) => JSON.parse(line));
+  console.log(JSON.stringify({ change: name, verification, trust: 'local-machine; exported key is not an independent trust anchor', publicKey: readOr(path.join(c.dir, 'evidence', 'public-key.pem')), envelopes }, null, 2));
+  return verification.state === 'passed' ? 0 : 1;
+}

package/src/commands/check.js

@@ -0,0 +1,127 @@
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { loadConfig, checkEntries } from '../lib/config.js';
+import { append, write } from '../lib/fs.js';
+import { loadAllChanges, loadChange } from '../lib/changes.js';
+import { evaluateLifecycle } from '../lib/lifecycle.js';
+import { changeSpecDrift } from '../lib/specs.js';
+import { worktreeFingerprint } from '../lib/git.js';
+import { readSession } from '../lib/session.js';
+import { contractFingerprint, recordStatement, sha256, trustCommands, verificationStatement } from '../lib/evidence.js';
+import { beginCheck } from '../lib/check-activity.js';
+
+export function verifyLine(claim, results, tree) {
+  return `### Verify: ${String(claim).replace(/[\r\n]/g, ' ')}\n${results.map((r) => `\`${r.cmd}\` exit ${r.exit}`).join('; ')}${tree ? ` · tree ${tree}` : ''}`;
+}
+
+/** Kill the process group on deadline, including shell descendants holding pipes. */
+export function runCommand(cmd, root, timeout) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn(cmd, { cwd: root, shell: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' } });
+    let output = '';
+    let timedOut = false;
+    let truncated = false;
+    let size = 0;
+    let errorText = '';
+    let settled = false;
+    let forcedClose;
+    const finish = (code, signal, terminationUnconfirmed = false) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(forcedClose);
+      const exit = timedOut ? 124 : truncated ? 125 : code ?? 1;
+      resolve({ exit, signal, timedOut, truncated, terminationUnconfirmed, durationMs: Date.now() - started, output: output + (errorText ? `\n${errorText}\n` : '') });
+    };
+    const kill = () => {
+      // An escaped descendant can retain the pipes even after its original
+      // process group exits. Bound our wait too; do not claim it was reaped.
+      forcedClose ??= setTimeout(() => {
+        child.stdout.destroy();
+        child.stderr.destroy();
+        child.unref();
+        finish(null, null, true);
+      }, 250);
+      if (!child.pid) return;
+      try {
+        if (process.platform === 'win32') spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', timeout: 5000 });
+        else process.kill(-child.pid, 'SIGKILL');
+      } catch { try { child.kill('SIGKILL'); } catch { /* deadline still bounds this process */ } }
+    };
+    const timer = setTimeout(() => { timedOut = true; kill(); }, timeout);
+    const consume = (chunk) => {
+      size += Buffer.byteLength(chunk);
+      if (size <= 2 * 1024 * 1024) output += chunk;
+      else if (!truncated) { truncated = true; output += '\n[output limit exceeded]\n'; kill(); }
+    };
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', consume);
+    child.stderr.on('data', consume);
+    child.on('error', (error) => { errorText = error.message; });
+    child.on('close', (code, signal) => finish(code, signal));
+  });
+}
+
+export async function check({ flags, positional }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  const configured = checkEntries(cfg);
+  const entries = positional.length ? [{ name: positional.join(' '), command: positional.join(' '), kind: 'check' }] : configured;
+  if (!entries.length) throw new Error('no check commands configured. Add `check:` commands to .keelson/config.yaml before claiming completion.');
+  const timeout = Number(flags.timeout ?? cfg.check_timeout_ms ?? 600000);
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 86400000) throw new Error('--timeout must be an integer in milliseconds (1..86400000)');
+  // Register before resolving a change: otherwise landing could archive it
+  // between lookup and registration and the check would recreate its old path.
+  const finish = beginCheck(root);
+  try {
+    let change;
+    if (flags.record !== undefined) {
+      const all = loadAllChanges(p.changes);
+      const focused = readSession(root).state?.change;
+      const name = flags.change ?? (all.some((c) => c.name === focused) ? focused : all.length === 1 ? all[0].name : null);
+      change = all.find((c) => c.name === name);
+      if (!change) throw new Error('recording requires one active change; use `keelson new <name>` or `--change <name>`');
+    }
+    trustCommands(root, entries.map((e) => e.command), Boolean(flags.trust));
+    const dir = change?.dir ?? p.runtime;
+    const before = { tree: worktreeFingerprint(root), contract: contractFingerprint(root, dir) };
+    const startedOn = new Date().toISOString();
+    const results = [];
+    for (const entry of entries) {
+      const run = await runCommand(entry.command, root, timeout);
+      const log = `$ ${entry.command}\nexit ${run.exit}\n\n${run.output}`;
+      const logDigest = sha256(log);
+      const file = path.join(dir, 'evidence', `${logDigest}.log`);
+      write(file, log);
+      const { output, ...metadata } = run;
+      results.push({ cmd: entry.command, name: entry.name, kind: entry.kind, ...metadata, logDigest });
+      if (!flags.json && !flags.quiet && output) process.stdout.write(output);
+      if (!flags.json) console.log(`${run.exit ? '✗' : '✓'} ${entry.name}: exit ${run.exit}${run.timedOut ? ' (timeout)' : ''}`);
+    }
+    const unchanged = before.tree === worktreeFingerprint(root) && before.contract === contractFingerprint(root, dir);
+    const complete = JSON.stringify(entries.map((e) => e.command)) === JSON.stringify(configured.map((e) => e.command));
+    const passed = unchanged && results.every((r) => r.exit === 0);
+    const claim = typeof flags.record === 'string' ? flags.record : passed ? 'checks pass' : 'checks failed';
+    if (change) {
+      recordStatement(root, dir, verificationStatement({ ...before, results, claim, startedOn, unchanged, complete, model: typeof flags.model === 'string' ? flags.model : null, host: process.env.CODEX_THREAD_ID ? 'codex' : null }));
+      append(path.join(dir, 'ledger.md'), `\n${verifyLine(claim, results, before.tree)}\n`);
+    }
+    const result = { ok: passed, complete, unchanged, tree: before.tree, contract: before.contract, results, record: change ? path.relative(root, path.join(dir, 'ledger.jsonl')) : null };
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(passed ? 'all checks passed' : unchanged ? 'checks failed' : 'inputs changed during checking; re-run checks');
+      if (change) console.log(`recorded in ${result.record}`);
+      if (!complete) console.log('partial suite: this run cannot authorize landing');
+      if (change && passed && complete) {
+        const current = loadChange(p.changes, change.name);
+        const lifecycle = evaluateLifecycle(current, before.tree, { activeNames: loadAllChanges(p.changes).map((c) => c.name), contractDrift: changeSpecDrift(current, p.specs) });
+        if (lifecycle.work === 'ready') console.log(`${change.name}: ready → run \`keelson land ${change.name}\``);
+      }
+    }
+    return passed ? 0 : 1;
+  } finally { finish(); }
+}

package/src/commands/context.js

@@ -0,0 +1,95 @@
+import path from 'node:path';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { readOr, listDirs, exists } from '../lib/fs.js';
+import { loadConfig } from '../lib/config.js';
+import { matchRules } from '../lib/rules.js';
+import { loadAllChanges } from '../lib/changes.js';
+import { evaluateLifecycle } from '../lib/lifecycle.js';
+import { readSession } from '../lib/session.js';
+import { gitStatusShort, recentCommits, worktreeFingerprint } from '../lib/git.js';
+import { list } from '../lib/args.js';
+import { knowledgeHealth } from '../lib/health.js';
+import { maintainRuntime } from '../lib/maintenance.js';
+import { changeSpecDrift } from '../lib/specs.js';
+
+export async function context({ flags, positional }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  maintainRuntime(root);
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  const paths = [...list(flags.paths), ...positional].map((x) => path.relative(root, path.resolve(root, x)).replace(/\\/g, '/'));
+  const rules = matchRules(p.rules, paths);
+  const fp = worktreeFingerprint(root);
+  const changes = loadAllChanges(p.changes);
+  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 orderedChanges = focus ? [...changes].sort((a, b) => (a.name === focus ? -1 : b.name === focus ? 1 : 0)) : changes;
+  const specs = listDirs(p.specs);
+  const refs = Object.entries(cfg.refs ?? {}).filter(([, v]) => v);
+  const knowledgeFindings = knowledgeHealth(root, cfg, p);
+  const data = {
+    root,
+    intent: readOr(p.intent).trim(),
+    now: readOr(p.now).trim(),
+    roadmap: exists(p.roadmap) ? readOr(p.roadmap).trim() : '',
+    glossary: exists(p.glossary) && !/^- …/m.test(readOr(p.glossary)) ? readOr(p.glossary).trim() : '',
+    guide: Boolean(cfg.guide),
+    context: cfg.context?.trim() ?? '',
+    refs: Object.fromEntries(refs),
+    paths,
+    rules: rules.map((r) => ({ file: `.keelson/rules/${r.file}`, globs: r.globs, content: r.content.trim(), missing: !r.exists })),
+    specs: specs.map((s) => `${p.specsRel}/${s}/spec.md`),
+    focus,
+    sessionAvailable: session.available,
+    knowledge: {
+      critical: knowledgeFindings.filter((h) => h.level === 'error').length,
+      overBudget: knowledgeFindings.filter((h) => h.level === 'warn').length,
+      maintenance: knowledgeFindings.slice(0, 8).map((h) => ({ level: h.level, kind: h.kind, text: h.text, fix: h.fix })),
+    },
+    changes: orderedChanges.map((c) => {
+      const contractDrift = changeSpecDrift(c, p.specs);
+      const lifecycle = evaluateLifecycle(c, fp, { activeNames, contractDrift });
+      return { name: c.name, tier: c.tier, owner: c.owner, work: lifecycle.work, verification: lifecycle.verification.state, blockedBy: lifecycle.blockedBy, progress: c.progress, open: c.open.map((o) => o.text), handoffNext: c.handoff?.next ?? null };
+    }),
+    git: { dirty: gitStatusShort(root), recent: recentCommits(root, 5) },
+  };
+  if (flags.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return 0;
+  }
+  const out = [`# Keelson context — ${path.basename(root)}`, ''];
+  if (data.context) out.push('## Project context (config.yaml)', '', data.context, '');
+  out.push('## INTENT.md', '', data.intent || '(empty — fill in .keelson/INTENT.md)', '');
+  if (data.roadmap) out.push('## ROADMAP.md', '', data.roadmap, '');
+  if (data.glossary) out.push('## GLOSSARY.md', '', data.glossary, '');
+  if (data.guide) out.push('Guided mode is on: keep normal accessible questioning, and add concise teaching about the engineering ideas and constraint rationale behind settled decisions.', '');
+  out.push('## NOW.md', '', data.now || '(empty)', '');
+  if (data.knowledge.maintenance.length) {
+    out.push('## Internal knowledge maintenance', '');
+    out.push('Handle these automatically during RECONCILE; do not ask the owner to run maintenance or report budget mechanics unless a semantic product decision is required.');
+    for (const item of data.knowledge.maintenance.slice(0, 8)) out.push(`- ${item.text} → ${item.fix}`);
+    out.push('');
+  }
+  if (refs.length) out.push('## Existing project material (read, do not duplicate)', '', ...refs.map(([k, v]) => `- ${k}: ${v}`), '');
+  out.push(`## Active changes${data.focus ? ` (session focus: ${data.focus})` : ''}`, '');
+  if (!data.changes.length) out.push('none');
+  for (const c of data.changes) {
+    out.push(`- ${c.name} · ${c.tier} · work ${c.work} · verify ${c.verification} · ${c.progress.done}/${c.progress.total} tasks${c.owner ? ` · ${c.owner}` : ''}`);
+    if (c.blockedBy?.length) out.push(`  depends on active: ${c.blockedBy.join(', ')}`);
+    if (c.open.length) out.push(`  open: ${c.open.join('; ')}`);
+    if (c.handoffNext) out.push(`  handoff next: ${c.handoffNext.split('\n')[0]}`);
+  }
+  out.push('');
+  out.push(`## Capabilities with specs (${p.specsRel})`, '', specs.length ? specs.map((s) => `- ${s}`).join('\n') : 'none yet', '');
+  out.push(`## Rules matched${paths.length ? ` for ${paths.join(', ')}` : ' (always-on only; pass --paths to route)'}`, '');
+  if (!rules.length) out.push('none');
+  for (const r of rules) {
+    out.push(`### .keelson/rules/${r.file}  (${r.globs.join(', ')})`, '');
+    out.push(r.exists ? r.content.trim() : '(file missing — referenced in index.md but not found)', '');
+  }
+  if (paths.length) out.push('Path routing is navigation, not proof: run `keelson impact <files>` for callers and affected specs, then check other entry points by reading.', '');
+  if (data.git.dirty?.length) out.push('## Uncommitted', '', ...data.git.dirty.slice(0, 20).map((l) => `- ${l}`), '');
+  console.log(out.join('\n'));
+  return 0;
+}

package/src/commands/design.js

@@ -0,0 +1,63 @@
+import { guidanceOptions, readGuidance } from './guide.js';
+
+// A brief is input to the host agent, never a claim that an audit already ran.
+const actions = [
+  ['plan', 'frontend', 'Plan the experience', '规划体验', 'Map the primary task, constraints, screen structure and acceptance before implementation.', '先明确主要任务、约束、页面结构和验收，再实施。'],
+  ['build', 'frontend', 'Build a complete interface', '构建完整界面', 'Implement a working vertical slice, including real states and browser verification.', '实现能走通的完整任务，补齐真实状态并在浏览器验收。'],
+  ['audit', 'frontend-review', 'Audit interface quality', '审查界面质量', 'Inspect the running interface for accessibility, responsive, state and performance failures; report evidence before changing code.', '检查运行中的可访问性、响应式、状态与性能问题；先报告证据。'],
+  ['critique', 'frontend-review', 'Review the design', '评审设计', 'Explain how hierarchy, composition and interaction help or obstruct the primary task.', '指出层级、构图与交互如何帮助或阻碍主要任务。'],
+  ['polish', 'frontend-review', 'Finish the interface', '打磨界面', 'Fix the highest-impact inconsistencies, then repeat the task and visual checks.', '修复影响最大的细节不一致，再复测任务与视觉表现。'],
+  ['simplify', 'frontend-visual', 'Simplify the surface', '简化界面', 'Remove redundant decoration and choices while preserving information, discoverability and function.', '去掉冗余装饰和选择，保留信息、可发现性和功能。'],
+  ['bolder', 'frontend-visual', 'Strengthen the expression', '增强表现力', 'Make a deliberate focal point through scale, composition or color without competing with the task.', '通过比例、构图或颜色建立明确焦点，服务主要任务。'],
+  ['quieter', 'frontend-visual', 'Reduce visual noise', '收敛视觉噪声', 'Reduce competing emphasis and ornament while retaining hierarchy and brand recognition.', '减少互相争抢的强调与装饰，保留层级和品牌识别。'],
+  ['typeset', 'frontend-visual', 'Refine typography', '优化排版', 'Establish readable type roles, hierarchy, line length and robust fallback fonts.', '建立可读的字体角色、层级、行长和可靠回退。'],
+  ['color', 'frontend-visual', 'Refine color', '优化配色', 'Use semantic color roles and verify contrast and non-color state cues.', '使用语义色彩角色，验证对比度与非颜色状态提示。'],
+  ['layout', 'frontend-visual', 'Refine layout', '优化布局', 'Improve grouping, alignment, density and responsive reading order.', '改进分组、对齐、密度和响应式阅读顺序。'],
+  ['animate', 'frontend-visual', 'Add purposeful motion', '完善动效', 'Clarify transitions and feedback with interruptible motion and a reduced-motion path.', '用可中断动效说明转换与反馈，并提供减少动态效果路径。'],
+  ['clarify', 'frontend-interaction', 'Clarify interface copy', '优化界面文案', 'Make labels, actions, errors and recovery specific to what the user is doing.', '让标签、操作、错误与恢复文案准确对应用户任务。'],
+  ['onboard', 'frontend-interaction', 'Improve first use', '完善首次使用', 'Create a short path from an honest empty state to the first useful outcome.', '从真实空状态出发，以最短路径得到首个有用结果。'],
+  ['harden', 'frontend-interaction', 'Harden interactions', '补齐交互边界', 'Exercise failures, retries, permissions, slow work, long content and localization.', '覆盖失败、重试、权限、慢操作、长内容与本地化。'],
+  ['adapt', 'frontend-delivery', 'Adapt across devices', '适配设备', 'Preserve the primary task across content-driven breakpoints, input modes and zoom.', '在由内容决定的断点、输入方式和缩放下保留主要任务。'],
+  ['optimize', 'frontend-delivery', 'Improve measured performance', '改进实测性能', 'Measure the affected journey, fix the dominant bottleneck, then remeasure correctness and speed.', '测量受影响流程，修复主要瓶颈，再复测正确性和速度。'],
+  ['extract', 'frontend-delivery', 'Extract reusable design', '提取复用设计', 'Consolidate repeated stable tokens or components while preserving their behavior.', '提取已稳定重复的 token 或组件，并保持行为一致。'],
+  ['document', 'frontend-delivery', 'Document the design system', '记录设计系统', 'Record observed tokens, components, states and usage decisions in existing project docs.', '在现有文档记录观察到的 token、组件、状态和使用决策。'],
+  ['explore', 'frontend-delivery', 'Explore visual directions', '探索视觉方向', 'Compare materially different compositions on the same real content and task; label tradeoffs.', '用相同真实内容与任务比较明显不同的构图，并说明取舍。'],
+  ['iterate', 'frontend-delivery', 'Iterate in the browser', '浏览器迭代', 'Observe, change one coherent area, reload, compare and repeat until acceptance is met.', '观察、修改一个完整区域、重载对照，直到满足验收。'],
+  ['delight', 'frontend-visual', 'Add a thoughtful detail', '增加体验细节', 'Add a small context-appropriate moment that rewards progress without delaying the task.', '增加契合场景的小反馈，回应进展而不拖慢任务。'],
+];
+
+export async function design({ positional = [], flags = {} }, cwd = process.cwd()) {
+  const options = guidanceOptions(flags, cwd);
+  const zh = options.lang === 'zh';
+  const catalog = actions.map(([name, reference, en, cn, goal, goalZh]) => ({ name, reference, title: zh ? cn : en, objective: zh ? goalZh : goal }));
+  const [action, ...parts] = positional;
+  if (!action) {
+    if (flags.json) console.log(JSON.stringify({ kind: 'design-catalog', lang: options.lang, actions: catalog }, null, 2));
+    else console.log([
+      zh ? 'Keelson 前端设计' : 'Keelson frontend design', '',
+      'Usage: keelson design <action> [target] [--lang en|zh] [--json]', '',
+      ...catalog.map(({ name, title }) => `  ${name.padEnd(12)} ${title}`), '',
+      zh ? '命令生成 Agent 执行指导；宿主 Agent 负责修改和浏览器验证。' : 'Commands prepare agent guidance; the host agent implements and verifies in the browser.',
+      zh ? '例如：keelson design harden "设置表单"' : 'Example: keelson design harden "settings form"',
+    ].join('\n'));
+    return 0;
+  }
+  const selected = catalog.find((entry) => entry.name === action);
+  if (!selected) throw new Error(`unknown design action "${action}". Run \`keelson design\` to list actions.`);
+  const references = [...new Set(['frontend', selected.reference])];
+  const brief = {
+    kind: 'design-brief', lang: options.lang, action,
+    target: parts.join(' ').trim() || (zh ? '当前请求涉及的界面' : 'the interface in the current request'),
+    title: selected.title, objective: selected.objective,
+    execution: zh ? '这是指导，尚未执行审查或修改。由宿主 Agent 使用项目代码和可用浏览器工具完成；目标文本不是 shell 命令。' : 'Guidance only; no audit or modification has run. The host agent uses project code and available browser tools. The target is text, not a shell command.',
+    mode: ['audit', 'critique', 'plan', 'explore'].includes(action) ? 'review' : 'change',
+    references: references.map((name) => ({ name, content: readGuidance(name, options) })),
+  };
+  if (flags.json) console.log(JSON.stringify(brief, null, 2));
+  else console.log([
+    `# ${brief.title}`, '', `${zh ? '目标' : 'Target'}: ${brief.target}`, '', brief.objective, '', brief.execution,
+    ...(brief.mode === 'review' ? ['', zh ? '先诊断或提出方案；仅在已有修改授权范围内改动。' : 'Start with findings or a proposal; modify only within existing authorization.'] : []),
+    ...brief.references.flatMap(({ name, content }) => ['', `--- ${name} ---`, '', content.trimEnd()]),
+  ].join('\n'));
+  return 0;
+}

package/src/commands/doctor.js

@@ -0,0 +1,157 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { exists, readOr, readJson, walk } from '../lib/fs.js';
+import { loadConfig, CONFIG_VERSION } from '../lib/config.js';
+import { PLATFORMS, installTargets, managedStateMatches, readManagedState, renderSkillFiles, renderSkillShim, residentBlock, workflowContent, sessionAdapterProblems } from '../platforms/index.js';
+import { validateProject } from './validate.js';
+import { projectStatus } from './status.js';
+import { parseFrontmatter } from '../lib/markdown.js';
+import { detectLocal } from '../lib/models.js';
+import { knowledgeHealth } from '../lib/health.js';
+import { listSessionStates, readSession } from '../lib/session.js';
+import { maintainRuntime } from '../lib/maintenance.js';
+import { ok, warn, fail, heading, dim } from '../lib/out.js';
+
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../../package.json');
+
+export async function doctor({ flags }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  maintainRuntime(root);
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  const findings = [];
+  const add = (level, text) => findings.push({ level, text });
+
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  (nodeMajor >= 20 ? ok : fail)(`node ${process.versions.node}`);
+  if (nodeMajor < 20) add('error', 'Node 20 or newer is required');
+
+  const rawVersion = Number((readOr(p.config, '').match(/^version:\s*(\d+)/m) || [])[1] ?? 1);
+  if (rawVersion < CONFIG_VERSION) add('warn', `config.yaml is v${rawVersion}; run \`keelson update\` to migrate to v${CONFIG_VERSION}`);
+
+  const managed = readManagedState(root);
+  const vendor = cfg.vendor === true || managed?.vendor === true;
+  const normalize = (text) => String(text ?? '').replace(/\r\n?/g, '\n');
+  if (vendor) {
+    const expectedSkillFiles = renderSkillFiles(cfg.lang, cfg.profile, PKG_VERSION);
+    const expectedSkillPaths = expectedSkillFiles.map((f) => f.rel).sort();
+    const actualSkillPaths = walk(p.skill);
+    if (JSON.stringify(actualSkillPaths) !== JSON.stringify(expectedSkillPaths)) add('error', 'canonical skill file set drifted from this CLI version (run `keelson update`)');
+    for (const file of expectedSkillFiles) {
+      const actual = readOr(path.join(p.skill, file.rel), null);
+      if (actual !== null && normalize(actual) !== file.content) add('error', `canonical skill drift: .keelson/skill/${file.rel} (run \`keelson update\`)`);
+    }
+    if (exists(p.workflow) && normalize(readOr(p.workflow)) !== workflowContent(cfg.lang, cfg.guide)) add('error', 'canonical workflow drifted from config/profile (run `keelson update`)');
+    for (const suffix of ['.keelson-tmp', '.keelson-bak']) if (exists(p.skill + suffix)) add('warn', `interrupted runtime replacement residue: .keelson/skill${suffix.replace('.keelson', '')} (run \`keelson update\`)`);
+    const canonicalSkill = path.join(p.skill, 'SKILL.md');
+    if (!exists(canonicalSkill)) add('error', 'canonical skill missing at .keelson/skill/SKILL.md (run `keelson update`)');
+    else {
+      const v = parseFrontmatter(readOr(canonicalSkill)).data.version ?? null;
+      if (v && v !== PKG_VERSION) add('warn', `canonical skill is ${v}, CLI is ${PKG_VERSION} (run \`keelson update\`)`);
+    }
+    if (!exists(p.workflow)) add('error', 'canonical workflow missing at .keelson/workflow.md (run `keelson update`)');
+  }
+
+  for (const t of cfg.tools ?? []) if (!PLATFORMS[t]) add('error', `unknown tool "${t}" in config.yaml`);
+  const currentTargets = installTargets((cfg.tools ?? []).filter((t) => PLATFORMS[t]), cfg);
+  if (!managed) add('warn', 'generated-surface ownership manifest is missing (run `keelson update`)');
+  else {
+    if (managed.packageVersion && managed.packageVersion !== PKG_VERSION) add('warn', `managed surfaces were last written by Keelson ${managed.packageVersion}; CLI is ${PKG_VERSION}`);
+    if (!managedStateMatches(root, currentTargets)) add('error', 'configured tools and generated-surface ownership differ (run `keelson update` to reconcile stale adapters)');
+  }
+  const expectedBlock = normalize(residentBlock(cfg.lang).trim());
+  for (const pl of currentTargets) {
+    const skill = path.join(root, pl.skillsDir, 'keelson', 'SKILL.md');
+    if (!exists(skill)) add('error', `${pl.label}: skill shim missing at ${pl.skillsDir}/keelson (run \`keelson update\`)`);
+    else {
+      const shimText = readOr(skill);
+      const v = parseFrontmatter(shimText).data.version ?? null;
+      if (v && v !== PKG_VERSION) add('warn', `${pl.label}: installed shim is ${v}, CLI is ${PKG_VERSION} (run \`keelson update\`)`);
+      if (normalize(shimText) !== renderSkillShim(cfg.lang, PKG_VERSION)) add('error', `${pl.label}: skill discovery shim drifted (run \`keelson update\`)`);
+    }
+    const ins = path.join(root, pl.instructions);
+    const insText = readOr(ins, '');
+    if (pl.instructionsFormat === 'kiro' ? !insText.includes('Keelson') : !insText.includes('<!-- keelson:start -->')) add('error', `${pl.label}: discovery block missing from ${pl.instructions}`);
+    else if (pl.instructionsFormat !== 'kiro') {
+      const found = normalize(insText).match(/<!-- keelson:start -->[\s\S]*?<!-- keelson:end -->/)?.[0] ?? '';
+      if (found.trim() !== expectedBlock) add('error', `${pl.label}: discovery block drifted in ${pl.instructions} (run \`keelson update\`)`);
+    }
+    if (pl.rulesFile) {
+      const rules = path.join(root, pl.rulesFile);
+      if (!exists(rules)) add('error', `${pl.label}: discovery rules file missing at ${pl.rulesFile} (run \`keelson update\`)`);
+      else if (!readOr(rules).includes('.keelson/workflow.md')) add('error', `${pl.label}: discovery rules file does not point to .keelson/workflow.md`);
+    }
+    if (pl.confidence === 'convention') add('info', `${pl.label}: file locations follow the tool's convention and have not been exercised by the maintainers; if the agent does not pick up the skill, override platforms.${pl.id} in config.yaml`);
+    for (const problem of sessionAdapterProblems(root, pl)) add('error', `${problem} (run \`keelson update\`)`);
+    if (pl.hooks) {
+      const settings = readJson(path.join(root, '.claude', 'settings.json'), {}) ?? {};
+      const has = (ev, script) => (settings.hooks?.[ev] ?? []).some((g) => (g.hooks ?? []).some((h) => String(h.command ?? '').includes(script)));
+      const registrations = [
+        ['SessionStart', 'session-start'],
+        ['UserPromptSubmit', 'prompt-state'],
+      ];
+      for (const [event, script] of registrations) {
+        const registered = has(event, script);
+        if (!registered) {
+          add('warn', `${pl.label}: ${event} hook not registered (fine after init --no-hooks; the agent falls back to the discovery workflow)`);
+          continue;
+        }
+      }
+    }
+  }
+
+  const { errors, warnings } = validateProject(root);
+  for (const e of errors) add('error', `validate: ${e}`);
+  for (const w of warnings) add('warn', `validate: ${w}`);
+
+  const st = projectStatus(root);
+  for (const c of st.changes) {
+    if (c.verification.state === 'stale') add('warn', `${c.name}: verification is stale (${c.verification.detail})`);
+    if (c.handoff?.headMoved) add('warn', `${c.name}: HEAD moved since its handoff; check the worktree before resuming`);
+    if (c.blockedBy.length) add('info', `${c.name}: waits on ${c.blockedBy.join(', ')}`);
+  }
+  for (const k of st.conflicts) add('warn', `shared contract between ${k.a} and ${k.b}: ${[...k.capabilities, ...k.paths].join(', ')}`);
+
+  const activeNames = new Set(st.changes.map((c) => c.name));
+  for (const session of listSessionStates(root)) {
+    if (session.change && !activeNames.has(session.change)) add('warn', `stale session focus points to missing change "${session.change}" in Keelson local runtime`);
+  }
+
+  let sessionStatus = null;
+  if (flags.session) {
+    const current = readSession(root);
+    sessionStatus = { current: { available: current.available, source: current.source, focusedChange: current.state?.change ?? null }, tools: [] };
+    for (const tool of cfg.tools ?? []) {
+      if (tool === 'codex') {
+        const available = Boolean(process.env.CODEX_THREAD_ID);
+        sessionStatus.tools.push({ tool, available, mode: available ? 'native' : 'degraded', source: available ? 'CODEX_THREAD_ID' : null, reason: available ? null : 'CODEX_THREAD_ID is unavailable in this process' });
+      } else if (tool === 'pi') {
+        const available = Boolean(process.env.PI_SESSION_ID);
+        sessionStatus.tools.push({ tool, available, mode: available ? 'native' : 'degraded', source: available ? 'PI_SESSION_ID' : null, reason: available ? null : 'PI_SESSION_ID is unavailable in this process' });
+      } else if (tool === 'claude' || tool === 'codebuddy') {
+        const available = Boolean(process.env.KEELSON_SESSION_ID);
+        sessionStatus.tools.push({ tool, available, mode: available ? 'bridge' : 'degraded', source: available ? 'KEELSON_SESSION_ID' : null, reason: available ? null : 'this command did not receive a bridge session identity' });
+      } else sessionStatus.tools.push({ tool, available: false, mode: 'degraded', source: null, reason: 'this host has no zero-copy session bridge' });
+    }
+    for (const item of sessionStatus.tools) add('info', `session ${item.tool}: ${item.mode}${item.source ? ` via ${item.source}` : ` — ${item.reason}`}`);
+  }
+
+  const health = knowledgeHealth(root, cfg, p);
+  // Critical budget findings already arrive through validateProject; add the
+  // advisory health findings here without duplicating hard-limit errors.
+  for (const h of health) if (h.level !== 'error') add(h.level, `${h.kind}: ${h.text} → ${h.fix}`);
+
+  const det = detectLocal();
+  for (const t of cfg.tools ?? []) if (det.tools[t] && !det.tools[t].installed) add('info', `${PLATFORMS[t]?.label ?? t} CLI not found on PATH (fine if you use it through an IDE)`);
+
+  heading(`keelson doctor — ${path.basename(root)} ${dim(`(keelson ${PKG_VERSION})`)}`);
+  if (health.length) console.log(dim('knowledge health: structural maintenance is automatic; remaining findings are internal Agent reconciliation signals unless semantics require owner input'));
+  for (const f of findings) (f.level === 'error' ? fail : f.level === 'warn' ? warn : ok)(f.text);
+  const errs = findings.filter((f) => f.level === 'error').length;
+  if (!findings.length) ok('everything in place');
+  else console.log(`${errs} error${errs === 1 ? '' : 's'}, ${findings.filter((f) => f.level === 'warn').length} warnings`);
+  if (flags.json) console.log(JSON.stringify({ ok: !errs, version: PKG_VERSION, findings, session: sessionStatus }, null, 2));
+  return errs ? 1 : 0;
+}

package/src/commands/focus.js

@@ -0,0 +1,84 @@
+import { requireProjectRoot, projectPaths } from '../lib/paths.js';
+import { loadConfig } from '../lib/config.js';
+import { loadAllChanges, loadChange } from '../lib/changes.js';
+import { currentBranch } from '../lib/git.js';
+import { bindSession, clearSession, readSession } from '../lib/session.js';
+import { ok, info, warn } from '../lib/out.js';
+
+function candidatesFor(root, changes) {
+  const branch = currentBranch(root);
+  const branchMatches = branch ? changes.filter((c) => c.branch === branch) : [];
+  if (branchMatches.length === 1) return { preferred: branchMatches[0], reason: `branch ${branch}` };
+  if (changes.length === 1) return { preferred: changes[0], reason: 'only active change' };
+  return { preferred: null, reason: null };
+}
+
+export async function focus({ flags, positional }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  const cfg = loadConfig(projectPaths(root).config);
+  const p = projectPaths(root, cfg);
+  const changes = loadAllChanges(p.changes);
+  const session = readSession(root);
+
+  if (!session.available) {
+    const candidate = candidatesFor(root, changes);
+    const requested = positional[0] ?? null;
+    if (requested && !loadChange(p.changes, requested)) throw new Error(`no active change named "${requested}"`);
+    const suggested = requested ?? (flags.auto ? candidate.preferred?.name ?? null : null);
+    const payload = { available: false, focus: null, suggested, reason: requested ? 'explicit' : candidate.reason, candidates: changes.map((c) => c.name) };
+    if (flags.json) console.log(JSON.stringify(payload, null, 2));
+    else {
+      warn('session identity is unavailable; Keelson will not persist a shared/global focus because parallel sessions could cross-wire');
+      if (suggested) info(`use ${suggested} explicitly for this work (${requested ? 'requested' : candidate.reason}); commands accept a change name/--change where needed`);
+      else if (changes.length) info(`active changes: ${changes.map((c) => c.name).join(', ')}`);
+    }
+    return 0;
+  }
+
+  if (flags.clear) {
+    clearSession(root);
+    if (flags.json) console.log(JSON.stringify({ available: true, focus: null, cleared: true }));
+    else ok('session focus cleared; active changes themselves are unchanged');
+    return 0;
+  }
+
+  let name = positional[0] ?? null;
+  if (!name && flags.auto) {
+    if (session.state?.change && loadChange(p.changes, session.state.change)) name = session.state.change;
+    else {
+      const candidate = candidatesFor(root, changes);
+      if (candidate.preferred) {
+        name = candidate.preferred.name;
+        if (!flags.json) info(`resume candidate selected from ${candidate.reason}: ${name}`);
+      }
+    }
+  }
+
+  if (name) {
+    const change = loadChange(p.changes, name);
+    if (!change) throw new Error(`no active change named "${name}"`);
+    const bound = bindSession(root, name, { branch: currentBranch(root), source: flags.auto ? 'auto' : 'focus' });
+    const payload = { available: true, focus: name, key: bound?.key ?? session.key };
+    if (flags.json) console.log(JSON.stringify(payload, null, 2));
+    else ok(`session focus → ${name}`);
+    return 0;
+  }
+
+  const active = session.state?.change && loadChange(p.changes, session.state.change) ? session.state.change : null;
+  const candidate = candidatesFor(root, changes);
+  const payload = {
+    available: true,
+    focus: active,
+    updatedAt: session.state?.updatedAt ?? null,
+    suggested: active ? null : candidate.preferred?.name ?? null,
+    candidates: changes.map((c) => c.name),
+  };
+  if (flags.json) console.log(JSON.stringify(payload, null, 2));
+  else if (active) console.log(active);
+  else {
+    console.log('no session focus');
+    if (candidate.preferred) info(`suggested resume: ${candidate.preferred.name} (${candidate.reason}); run \`keelson focus ${candidate.preferred.name}\` to bind it`);
+    else if (changes.length) info(`active changes: ${changes.map((c) => c.name).join(', ')}`);
+  }
+  return 0;
+}