@zyaiting/keelson 0.4.0 → 0.5.0

package/src/cli.js

@@ -5,7 +5,7 @@ const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 
 const COMMANDS = {
-  ask: ['ask <add|frontier|list|settle|assume|reject|reopen> [id] [--change name] [--json]', 'Persist decisions and show up to three ready owner questions', () => import('./commands/ask.js').then((m) => m.ask)],
+  ask: ['ask <add|frontier|list|settle|assume|reject|reopen> [id] [--change name] [--all|--limit n] [--json]', 'Persist decisions and show ready owner questions; --all returns the whole frontier', () => import('./commands/ask.js').then((m) => m.ask)],
   design: ['design [action] [target] [--lang en|zh] [--json]', 'Prepare focused frontend design guidance for your agent', () => import('./commands/design.js').then((m) => m.design)],
   guide: ['guide [reference] [--list] [--json] [--lang en|zh]', 'Read the installed workflow or one reference on demand', () => import('./commands/guide.js').then((m) => m.guide)],
   hook: ['hook <event>', 'Run an installed host adapter', () => import('./commands/hook.js').then((m) => m.hook)],
@@ -13,10 +13,11 @@ const COMMANDS = {
   init: ['init [--<platform> ...] [--tools a,b] [--guide] [--profile lean|guided] [--lang en|zh] [--no-hooks] [--vendor] [--dry-run]', 'Set up the minimal .keelson/ control plane and host discovery. Project artifacts grow only when the work needs them', () => import('./commands/init.js').then((m) => m.init)],
   platforms: ['platforms [--json]', 'List supported coding tools, their file locations, and which are installed or configured', () => import('./commands/platforms.js').then((m) => m.platforms)],
   update: ['update [--vendor] [--dry-run]', 'Refresh owned host shims and configuration; --vendor opts into copied guidance', () => import('./commands/init.js').then((m) => m.init)],
-  context: ['context [--paths a/,b/**] [--json]', 'Print INTENT, ROADMAP, NOW, active changes, existing references, and the rules matching the given paths', () => import('./commands/context.js').then((m) => m.context)],
+  context: ['context [--paths a/,b/**] [--change name] [--phase implement|check] [--json]', 'Print INTENT, ROADMAP, NOW, active changes, existing references, and the rules matching the given paths', () => import('./commands/context.js').then((m) => m.context)],
   impact: ['impact <file> [file...] [--json]', 'Mechanical impact hints: importers, specs and rules that may be affected, active changes that overlap', () => import('./commands/impact.js').then((m) => m.impact)],
   focus: ['focus [change] [--auto|--clear] [--json]', 'Bind this AI session to one active change without changing the change lifecycle', () => import('./commands/focus.js').then((m) => m.focus)],
   new: ['new <name> [--tier quick|spec] [--capability a,b] [--touches globs] [--depends change] [--worktree]', 'Scaffold a change directory (owner, branch, delta base recorded)', () => import('./commands/new.js').then((m) => m.newChange)],
+  start: ['start [change] [--json]', 'Enter implementation after the decision and plan gates pass; run by the agent', () => import('./commands/start.js').then((m) => m.start)],
   status: ['status [--json]', 'Work, verification, and release status per change; slices, open questions, conflicts, handoffs', () => import('./commands/status.js').then((m) => m.status)],
   handoff: ['handoff [name] [--by who]', 'Create or re-stamp handoff.md for a change (at, updated, by)', () => import('./commands/handoff.js').then((m) => m.handoff)],
   validate: ['validate [--json]', 'Check .keelson/ structure, specs, changes, ledgers; non-zero on errors', () => import('./commands/validate.js').then((m) => m.validate)],
@@ -33,7 +34,7 @@ const COMMANDS = {
 
 const COMMAND_GROUPS = [
   ['Your commands', ['init', 'design', 'status', 'doctor', 'update', 'platforms', 'uninstall']],
-  ['Agent workflow', ['ask', 'context', 'impact', 'focus', 'new', 'check', 'handoff', 'validate', 'land', 'cancel']],
+  ['Agent workflow', ['ask', 'context', 'impact', 'focus', 'new', 'start', 'check', 'handoff', 'validate', 'land', 'cancel']],
   ['Maintenance / advanced', ['guide', 'attest', 'retro', 'models', 'ablate', 'restore']],
 ];
 

package/src/commands/ablate.js

@@ -29,8 +29,9 @@ export async function ablate({ flags }, cwd = process.cwd()) {
   for (const pl of surfaceTargets) {
     surfaces.push(pl.instructions, path.join(pl.skillsDir, 'keelson'));
     if (pl.rulesFile) surfaces.push(pl.rulesFile);
-    if (pl.hooks) surfaces.push('.claude/settings.json');
+    if (pl.hooks && pl.id === 'claude') surfaces.push('.claude/settings.json');
     if (pl.sessionAdapter === 'opencode-plugin') surfaces.push('.opencode/plugins/keelson-session.js');
+    if (pl.sessionAdapter === 'codex-thread-env') surfaces.push('.codex/hooks.json');
     if (pl.sessionAdapter === 'codebuddy-hooks') surfaces.push('.codebuddy/settings.json');
   }
   // Canonical runtime, hook scripts, session runtime and project facts are

package/src/commands/ask.js

@@ -18,6 +18,8 @@ function askUnlocked({ positional, flags }, cwd) {
   const change = changes.find((c) => c.name === name);
   if (!change) throw new Error('choose an active change with --change <name>');
   const [action = 'frontier', id] = positional;
+  const limit = flags.all ? Infinity : flags.limit === undefined ? 3 : Number(flags.limit);
+  if (limit !== Infinity && (!Number.isInteger(limit) || limit < 1)) throw new Error('--limit must be a positive integer; use --all for the whole ready frontier');
   let data = readDecisions(change.dir);
   const text = (value, label) => {
     if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} is required`);
@@ -52,11 +54,12 @@ function askUnlocked({ positional, flags }, cwd) {
       }
     });
   } else if (!['frontier', 'list'].includes(action)) throw new Error('usage: keelson ask <add|frontier|list|settle|assume|reject|reopen> [id] --change <name>');
-  const result = action === 'list' ? data : decisionFrontier(data);
+  const result = action === 'list' ? data : decisionFrontier(data, limit);
   if (flags.json) console.log(JSON.stringify(result, null, 2));
   else if (action === 'list') for (const d of data.decisions) console.log(`${d.id} [${d.owner}/${d.state}] ${d.question}${d.answer ? ` → ${d.answer}` : ''}`);
   else {
     for (const d of result.questions) console.log(`${d.id}. ${d.question}${d.recommended ? ` (recommended: ${d.recommended})` : ''}`);
+    if (result.remaining.length) console.log(`${result.remaining.length} more ready owner decision(s); use --all for a complex interview round.`);
     for (const d of result.investigate) console.log(`Investigate ${d.id} (${d.owner}): ${d.question}`);
     if (!result.questions.length) console.log(result.complete ? 'Decision frontier complete.' : 'No owner question is ready; resolve investigations, dependencies or assumptions.');
   }

package/src/commands/context.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { activeWorkflow, phaseContext, renderPhaseContext } from '../lib/workflow.js';
 import { requireProjectRoot, projectPaths } from '../lib/paths.js';
 import { readOr, listDirs, exists } from '../lib/fs.js';
 import { loadConfig } from '../lib/config.js';
@@ -14,6 +15,12 @@ import { changeSpecDrift } from '../lib/specs.js';
 
 export async function context({ flags, positional }, cwd = process.cwd()) {
   const root = requireProjectRoot(cwd);
+  if (flags.phase) {
+    const workflow = activeWorkflow(root, flags.change);
+    const pack = phaseContext(root, workflow, flags.phase, [...list(flags.paths), ...positional]);
+    console.log(flags.json ? JSON.stringify(pack, null, 2) : renderPhaseContext(pack));
+    return 0;
+  }
   maintainRuntime(root);
   const cfg = loadConfig(projectPaths(root).config);
   const p = projectPaths(root, cfg);

package/src/commands/doctor.js

@@ -85,12 +85,14 @@ export async function doctor({ flags }, cwd = process.cwd()) {
     }
     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) {
+    if (pl.hooks && pl.id === 'claude') {
       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'],
+        ['PreToolUse', 'workflow-guard'],
+        ['SubagentStart', 'workflow-guard'],
       ];
       for (const [event, script] of registrations) {
         const registered = has(event, script);

package/src/commands/hook.js

@@ -5,6 +5,10 @@ import { PKG_ROOT } from '../lib/paths.js';
 const HOOKS = new Map([
   ['session-start', 'session-start.mjs'],
   ['prompt-state', 'prompt-state.mjs'],
+  ['workflow-guard', 'workflow-guard.mjs'],
+  ['codex-workflow', 'workflow-guard.mjs'],
+  ['codebuddy-workflow', 'workflow-guard.mjs'],
+  ['codex-session', 'codex-session.mjs'],
   ['codebuddy-session', 'codebuddy-session.mjs'],
 ]);
 
@@ -13,7 +17,8 @@ export async function hook({ positional = [] }, cwd = process.cwd()) {
   const name = positional[0];
   const file = HOOKS.get(name);
   if (!file) throw new Error(`unknown hook "${name}". Supported hooks: ${[...HOOKS.keys()].join(', ')}`);
-  const child = spawnSync(process.execPath, [path.join(PKG_ROOT, 'hooks', file)], {
+  const hostArgs = name === 'codex-workflow' ? ['codex'] : name === 'codebuddy-workflow' ? ['codebuddy'] : [];
+  const child = spawnSync(process.execPath, [path.join(PKG_ROOT, 'hooks', file), ...hostArgs], {
     cwd,
     env: process.env,
     stdio: 'inherit',

package/src/commands/init.js

@@ -4,7 +4,7 @@ import { createRequire } from 'node:module';
 import { projectPaths, findProjectRoot } from '../lib/paths.js';
 import { exists, write, read, mkdirp, readOr } from '../lib/fs.js';
 import { loadConfig, saveConfig, DEFAULT_CONFIG, CONFIG_VERSION } from '../lib/config.js';
-import { PLATFORMS, PLATFORM_IDS, RETIRED_PLATFORM_IDS, installTargets, installCanonicalSkill, installSkill, installWorkflow, installInstructions, installHooks, installSessionAdapter, skillSource, plannedCanonicalSkillFiles, plannedSkillFiles, plannedWorkflowFile, plannedManagedRemovals, plannedSessionAdapterFiles, readManagedState, reconcileManagedTargets, removeCanonicalRuntime, removeLegacyCopiedHooks, writeManagedState, assertSkillsInstallable } from '../platforms/index.js';
+import { PLATFORMS, PLATFORM_IDS, RETIRED_PLATFORM_IDS, installTargets, installCanonicalSkill, installSkill, installWorkflow, installInstructions, installHooks, installSessionAdapter, skillSource, plannedCanonicalSkillFiles, plannedSkillFiles, plannedWorkflowFile, plannedManagedRemovals, plannedSessionAdapterFiles, readManagedState, reconcileManagedTargets, removeCanonicalRuntime, removeLegacyCopiedHooks, writeManagedState, assertSkillsInstallable, assertCanonicalSkillInstallable, assertWorkflowInstallable } from '../platforms/index.js';
 import { list } from '../lib/args.js';
 import { ok, info, warn, heading, dim } from '../lib/out.js';
 import { detectAndCache, detectLocal } from '../lib/models.js';
@@ -149,7 +149,11 @@ export async function init({ flags }, cwd = process.cwd()) {
 
   heading(`Keelson ${fresh ? 'init' : 'update'} in ${root}`);
   // Refuse a protected shim before changing config or removing v0.3 runtime.
-  assertSkillsInstallable(root, targets, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, force: flags.force });
+  assertSkillsInstallable(root, targets, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, previousState: priorManaged, force: flags.force });
+  if (cfg.vendor) {
+    assertWorkflowInstallable(root, { lang: cfg.lang, guide: cfg.guide, previousState: priorManaged, force: flags.force });
+    assertCanonicalSkillInstallable(root, { lang: cfg.lang, profile: cfg.profile, version: PKG_VERSION, previousState: priorManaged, force: flags.force });
+  }
   if (retiredFromConfig.length) warn(`retired host adapters removed from config: ${retiredFromConfig.join(', ')}; use the portable agents layer or select one of: ${PLATFORM_IDS.filter((id) => id !== 'agents').join(', ')}`);
   if (retiredOverrides.length) warn(`retired platform overrides removed: ${retiredOverrides.join(', ')}`);
   if (retiredModelOverrides.length) warn(`retired model overrides removed: ${retiredModelOverrides.join(', ')}`);
@@ -201,8 +205,8 @@ export async function init({ flags }, cwd = process.cwd()) {
   }
 
   if (cfg.vendor) {
-    const workflowPath = installWorkflow(root, { lang: cfg.lang, guide: cfg.guide, force: flags.force });
-    const canonicalSkillPath = installCanonicalSkill(root, { lang: cfg.lang, profile: cfg.profile, version: PKG_VERSION, force: flags.force });
+    const workflowPath = installWorkflow(root, { lang: cfg.lang, guide: cfg.guide, previousState: priorManaged, force: flags.force });
+    const canonicalSkillPath = installCanonicalSkill(root, { lang: cfg.lang, profile: cfg.profile, version: PKG_VERSION, previousState: priorManaged, force: flags.force });
     ok(`vendored guidance → ${workflowPath}; ${canonicalSkillPath}`);
   } else info('guidance stays in the installed package; agents load it with `keelson guide`');
 
@@ -211,18 +215,19 @@ export async function init({ flags }, cwd = process.cwd()) {
     const discoveryKey = `${t.instructions}|${t.skillsDir}|${t.rulesFile ?? ''}`;
     if (!discoveryInstalled.has(discoveryKey)) {
       discoveryInstalled.add(discoveryKey);
-      const skillPath = installSkill(root, t, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, force: flags.force });
+      const skillPath = installSkill(root, t, { lang: cfg.lang, version: PKG_VERSION, legacyVersion, previousVersion, previousState: priorManaged, force: flags.force });
       const files = installInstructions(root, t, { lang: cfg.lang });
       ok(`${t.label}: discovery shim → ${skillPath}; instructions → ${files.join(', ')}${t.confidence === 'convention' ? dim(' (path by convention; run `keelson doctor` after your first session)') : ''}`);
     } else {
       info(`${t.label}: reuses existing discovery surface ${t.instructions} + ${t.skillsDir}/keelson`);
     }
-    if (t.hooks) {
+    if (t.hooks && t.id === 'claude') {
       installHooks(root);
-      ok(`${t.label}: hooks → .claude/settings.json (session snapshot + per-prompt state line)`);
+      ok(`${t.label}: hooks → .claude/settings.json (workflow restore + file-tool gate + phase context injection)`);
     }
     const sessionFiles = installSessionAdapter(root, t);
     if (sessionFiles.length) ok(`${t.label}: native session adapter → ${sessionFiles.join(', ')}`);
+    if (t.sessionAdapter === 'codex-thread-env') info('Codex: review and trust the generated project hooks in /hooks when prompted; host permissions stay in control');
     else if (t.sessionAdapter === 'pi-env') info(`${t.label}: native session focus uses PI_SESSION_ID; no adapter file needed`);
   }
   writeManagedState(root, targets, PKG_VERSION, { vendor: cfg.vendor });

package/src/commands/new.js

@@ -43,7 +43,7 @@ export async function newChange({ flags, positional }, cwd = process.cwd()) {
   const front = [
     `tier: ${tier}`,
     `created: ${vars.date}`,
-    `status: ${tier === 'spec' ? 'clarifying' : 'in-progress'}`,
+    'status: clarifying',
     `owner: ${owner}`,
     ...(worktree ? [`branch: ${name}`, `worktree: ${path.relative(root, worktree)}`] : branch ? [`branch: ${branch}`] : []),
     ...(list(flags.depends).length ? [`depends: [${list(flags.depends).join(', ')}]`] : []),

package/src/commands/platforms.js

@@ -16,7 +16,7 @@ export async function platforms({ flags }, cwd = process.cwd()) {
     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'
+      configured && cfg?.hooks === false && p.sessionAdapter && !['pi-env', 'codex-thread-env'].includes(p.sessionAdapter)
         ? '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 };

package/src/commands/start.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { requireProjectRoot } from '../lib/paths.js';
+import { exists, read, write, writeJson, withLock } from '../lib/fs.js';
+import { runtimeDir } from '../lib/runtime-path.js';
+import { bindSession } from '../lib/session.js';
+import { activeWorkflow, planningBlockers, planFingerprint, phaseContext } from '../lib/workflow.js';
+
+export async function start({ positional = [], flags = {} }, cwd = process.cwd()) {
+  const root = requireProjectRoot(cwd);
+  return withLock(path.join(runtimeDir(root), 'landing'), () => {
+    const workflow = activeWorkflow(root, positional[0] ?? flags.change);
+    const blockers = planningBlockers(workflow.change, workflow.changes);
+    if (blockers.length) throw new Error(`cannot start implementation: ${blockers.join(' ')}`);
+    const { change } = workflow;
+    const pack = phaseContext(root, workflow); // Validate before changing state.
+    const file = path.join(change.dir, 'change.md');
+    const text = read(file);
+    const updated = /^status:/m.test(text.split('\n---')[0])
+      ? text.replace(/^status:.*$/m, 'status: in-progress')
+      : text.replace(/^---\r?\n/, '---\nstatus: in-progress\n');
+    write(file, updated);
+    writeJson(path.join(change.dir, 'execution.json'), { schema: 1, plan: planFingerprint(change), startedAt: new Date().toISOString() });
+    bindSession(root, change.name, { source: 'start' });
+    const contextFile = path.join(change.dir, 'context.json');
+    if (!exists(contextFile)) {
+      const files = pack.files.map(({ file }) => file.replace(' (including shards)', ''));
+      writeJson(contextFile, { schema: 1, implement: files, check: files });
+    }
+    const result = { change: change.name, state: 'in-progress' };
+    console.log(flags.json ? JSON.stringify(result) : `Started ${change.name}; follow \`keelson context --phase implement\` before editing.`);
+    return 0;
+  });
+}

package/src/commands/uninstall.js

@@ -14,7 +14,7 @@ export async function uninstall({ flags }, cwd = process.cwd()) {
   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 });
+    const canonical = removeCanonicalRuntime(root, { lang: cfg.lang, profile: cfg.profile, version: managed.packageVersion, guide: cfg.guide, previousState: managed });
     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`);
   }

package/src/lib/decisions.js

@@ -37,8 +37,10 @@ export function validateDecisionData(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')));
+  const ownerReady = ready.filter((d) => d.owner === 'user');
   return {
-    questions: ready.filter((d) => d.owner === 'user').slice(0, limit),
+    questions: ownerReady.slice(0, limit),
+    remaining: ownerReady.slice(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'),

package/src/lib/hook-context.js

@@ -0,0 +1,30 @@
+import crypto from 'node:crypto';
+import { readSession, writeSession } from './session.js';
+import { activeWorkflow, phaseContext, renderPhaseContext, workflowHint } from './workflow.js';
+
+/** Match the identity exported to each host's CLI tools, without persisting raw IDs. */
+export function hookEnvironment(host, input, inherited = process.env) {
+  const env = { ...inherited };
+  // Codex child events identify the child thread with agent_id; session_id
+  // identifies the shared root. Match the child's CODEX_THREAD_ID in shell tools.
+  const child = host === 'codex' && typeof input.agent_id === 'string' ? input.agent_id.trim() : '';
+  const id = child || (typeof input.session_id === 'string' ? input.session_id.trim() : '');
+  if (id) {
+    const namespace = host === 'codex' ? 'codex_thread_id' : host;
+    env.KEELSON_SESSION_ID = crypto.createHash('sha256').update(`${namespace}:${id}`).digest('hex').slice(0, 32);
+  }
+  return env;
+}
+
+export function sessionContext(root, env, event, host) {
+  const session = writeSession(root, {
+    source: `${host}-hook`, ...(event === 'SessionStart' ? { injectedContexts: [] } : {}),
+  }, env);
+  const lines = [workflowHint(root, env)];
+  const focus = session?.state.change ?? readSession(root, env).state?.change;
+  if (focus) {
+    const workflow = activeWorkflow(root, focus, env);
+    if (workflow.change) lines.push(renderPhaseContext(phaseContext(root, workflow)));
+  }
+  return lines.join('\n\n');
+}

package/src/lib/markdown.js

@@ -200,7 +200,7 @@ export function parseLedger(text) {
       const exits = [...s.body.matchAll(/exit\s*(?:code)?\s*[:=]?\s*(\d+)/gi)].map((m) => Number(m[1]));
       entry.exit = exits.length ? Math.max(...exits) : null;
       entry.command = (s.body.match(/`([^`]+)`/) || [])[1] ?? null;
-      entry.tree = (s.body.match(/\btree\s*[:=]?\s*([0-9a-f]{7,40})\b/i) || [])[1] ?? null;
+      entry.tree = (s.body.match(/\btree\s*[:=]?\s*([0-9a-f]{7,64})\b/i) || [])[1] ?? null;
     }
     if (kind === 'dispatch') {
       const dm = entry.title.match(/(light|standard|deep)/i);

package/src/lib/rules.js

@@ -12,12 +12,20 @@ export function parseRulesIndex(text) {
   return entries;
 }
 
-export function matchRules(rulesDir, paths) {
+// Declared touches can themselves be globs. Keep every rule whose literal
+// prefix can overlap; extra context is preferable to silently missing a rule.
+function mayOverlap(a, b) {
+  const prefix = (s) => s.replace(/^\.\//, '').split(/[*?{]/, 1)[0].replace(/\/$/, '');
+  const x = prefix(a), y = prefix(b);
+  return x.startsWith(y) || y.startsWith(x);
+}
+
+export function matchRules(rulesDir, paths, { patterns = false } = {}) {
   const index = parseRulesIndex(readOr(path.join(rulesDir, 'index.md')));
   const hits = new Map();
   for (const e of index) {
     const always = e.glob === '**' || e.glob === '*';
-    const matched = always || paths.some((p) => globMatch(e.glob, p));
+    const matched = always || paths.some((p) => globMatch(e.glob, p) || (patterns && /[*?{]/.test(p) && mayOverlap(e.glob, p)));
     if (!matched) continue;
     const f = path.join(rulesDir, e.file);
     if (!hits.has(e.file)) hits.set(e.file, { file: e.file, globs: [], exists: exists(f), content: readOr(f) });

package/src/lib/workflow.js

@@ -0,0 +1,102 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { exists, read, readJson } from './fs.js';
+import { projectPaths, resolveWithin } from './paths.js';
+import { loadConfig } from './config.js';
+import { loadAllChanges } from './changes.js';
+import { readSession } from './session.js';
+import { decisionFrontier } from './decisions.js';
+import { matchRules } from './rules.js';
+import { readCapabilitySpec } from './specs.js';
+
+export function activeWorkflow(root, name, env = process.env) {
+  const cfg = loadConfig(projectPaths(root).config);
+  const paths = projectPaths(root, cfg);
+  const changes = loadAllChanges(paths.changes);
+  const focused = name ?? readSession(root, env).state?.change;
+  // A sole change is a CLI convenience, not permission for an unrelated host
+  // session to start writing. Hooks require an explicit session binding.
+  const change = changes.find((c) => c.name === (focused ?? (changes.length === 1 ? changes[0].name : null)));
+  return { cfg, paths, changes, change };
+}
+
+export function planFingerprint(change) {
+  return crypto.createHash('sha256').update(JSON.stringify({
+    body: change.body.replace(/\[[xX ]\]/g, '[ ]'),
+    decisions: change.decisionRecords,
+    depends: change.depends, touches: change.touches,
+    deltas: change.deltaFiles.map((file) => [file, read(path.join(change.dir, 'specs', file)).replace(/\r\n?/g, '\n')]),
+  })).digest('hex');
+}
+
+export function planningBlockers(change, changes = []) {
+  if (!change) return ['No active change. Create the smallest useful change and run `keelson start <name>`.'];
+  const blocked = [];
+  if (['blocked', 'cancelled', 'integrated'].includes(change.storedWork)) blocked.push(`Change is ${change.storedWork}.`);
+  if (!decisionFrontier({ decisions: change.decisionRecords }, Infinity).complete) blocked.push('Resolve the registered decision tree with `keelson ask frontier --all`.');
+  if (change.open.length || change.assumed.length) blocked.push('Resolve the change\'s open questions and unconfirmed assumptions.');
+  if (!change.acceptance.length || change.acceptance.some((a) => /^\s*(?:…|<[^>]+>)(?:\s|$)/.test(a.text))) blocked.push('Write concrete acceptance checks in change.md.');
+  if (change.depends.some((name) => changes.some((c) => c.name === name))) blocked.push('Finish the prerequisite changes first.');
+  return blocked;
+}
+
+export function implementationBlockers(change, changes = []) {
+  const blockers = planningBlockers(change, changes);
+  if (!change) return blockers;
+  const receipt = readJson(path.join(change.dir, 'execution.json'), null);
+  if (receipt?.schema !== 1 || receipt.plan !== planFingerprint(change)) blockers.push('Run `keelson start` after settling the current plan; its start record is missing or stale.');
+  if (change.storedWork !== 'in-progress') blockers.push('Implementation requires the in-progress state set by `keelson start`.');
+  return blockers;
+}
+
+/** Declarative additions augment mandatory context; they cannot omit a contract. */
+export function phaseContext(root, workflow, phase = 'implement', touched = []) {
+  if (!['implement', 'check'].includes(phase)) throw new Error('phase must be implement or check');
+  const { cfg, paths, change } = workflow;
+  const files = new Map();
+  const add = (file, required = false) => {
+    const rel = path.relative(root, file).replace(/\\/g, '/');
+    const safe = resolveWithin(root, rel);
+    if (exists(safe)) files.set(rel, read(safe).trim());
+    else if (required) throw new Error(`declared context file ${rel} is missing; restore it or correct context.json`);
+  };
+  add(paths.intent);
+  if (change) {
+    for (const name of ['request.md', 'change.md', 'decisions.json', 'tasks.md']) add(path.join(change.dir, name));
+    for (const file of change.deltaFiles) add(path.join(change.dir, 'specs', file), true);
+    for (const cap of change.capabilities) {
+      const logical = readCapabilitySpec(paths.specs, cap);
+      if (logical) files.set(`${paths.specsRel}/${cap}/spec.md (including shards)`, logical);
+    }
+    const manifestPath = path.join(change.dir, 'context.json');
+    if (exists(manifestPath)) {
+      const manifest = JSON.parse(read(manifestPath));
+      if (manifest.schema !== 1 || !['implement', 'check'].every((key) => Array.isArray(manifest[key]) && manifest[key].every((v) => typeof v === 'string'))) throw new Error('context.json requires schema 1 and implement/check path arrays');
+      for (const rel of manifest[phase]) add(resolveWithin(root, rel), true);
+    }
+  }
+  for (const rule of matchRules(paths.rules, [...(change?.touches ?? []), ...touched], { patterns: true })) add(path.join(paths.rules, rule.file), true);
+  const instructions = phase === 'check'
+    ? 'Review the original request, acceptance, current/delta specs and diff in a fresh context. Find uncovered behavior and risky assumptions. Report findings with evidence; implementation owns repairs, then re-review the affected result. Do not treat the implementer\'s summary as proof.'
+    : 'Resolve owner decisions before dependent implementation. Follow the supplied contracts, run relevant checks, and send material changes to an independent reviewer. Continue within existing authorization.';
+  return {
+    phase, change: change?.name ?? null, instructions,
+    checks: cfg.check ?? [],
+    files: [...files].map(([file, content]) => ({ file, content })),
+  };
+}
+
+export function renderPhaseContext(pack) {
+  return [`[keelson] ${pack.phase} context${pack.change ? `: ${pack.change}` : ''}`, pack.instructions,
+    `Configured checks (review trust before running): ${JSON.stringify(pack.checks)}`,
+    ...pack.files.map(({ file, content }) => `\n--- ${file} ---\n${content}`)].join('\n');
+}
+
+export function workflowHint(root, env = process.env) {
+  const focus = readSession(root, env).state?.change;
+  if (!focus) return '[keelson] Read `keelson guide` for this request. Investigate facts first; use one question for a simple gap or the whole ready frontier for connected uncertainty. Before modifying files, create/focus a change and run `keelson start`; keep read-only requests read-only.';
+  const workflow = activeWorkflow(root, focus, env);
+  if (!workflow.change) return '[keelson] Previous focus is no longer active. Re-read context and select work for the current request.';
+  const blocked = implementationBlockers(workflow.change, workflow.changes);
+  return `[keelson] ${focus}: ${blocked.length ? 'planning — ' + blocked.join(' ') : 'implement — follow the current context, then independent review → fresh checks → land → reconcile.'} Verification is determined by signed current-tree evidence in \`keelson status\`, never by handwritten ledger text.`;
+}