@zyaiting/keelson 0.4.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center"><img src="https://raw.githubusercontent.com/Atingaii/keelson/main/docs/assets/keelson-banner.png" alt="Keelson" width="620"></p>
 
-<p align="center"><strong>Start with a conversation. Leave work the next session can build on.</strong></p>
+<p align="center"><strong>Clarify the goal. Build to the contract. Keep what you learn.</strong></p>
 <p align="center">Project memory, engineering guidance, and acceptance checks for your coding agent. Describe the outcome; keep decisions and verification alongside the code.</p>
 
 <p align="center">
@@ -16,16 +16,13 @@
 <a href="https://github.com/Atingaii/keelson/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
 </p>
 
-<p align="center"><img src="https://raw.githubusercontent.com/Atingaii/keelson/main/docs/assets/keelson-demo.gif" alt="Real agent conversation replay: a task-filter request followed by implementation, verification, and archiving" width="100%"></p>
-<p align="center"><sub>Initialized example repository · Translated excerpts from a real session, with waits shortened · Just describe the task</sub></p>
-
 ## Why Keelson?
 
 Keelson brings software engineering practices into everyday agent conversations: agree on the outcome, preserve the reasoning, and check the result. It addresses four recurring problems.
 
 **1. The agent builds the wrong thing.**
 
-“Add a filter” leaves room for different defaults, edge cases, and compatibility choices. Keelson guides the agent to inspect the code and turn the request into concrete acceptance examples before implementation. This applies **behaviour-driven development**: use examples to expose disagreement early, asking only about choices that affect the direction.
+“Add a filter” leaves room for different defaults, edge cases, and compatibility choices. Keelson guides the agent to inspect the code, automatically investigate unclear goals and connected decisions, then turn the request into concrete acceptance examples before implementation. This applies **behaviour-driven development**: use examples to expose disagreement early, asking only about choices that affect the direction.
 
 **2. Every session needs the same explanation.**
 
@@ -47,7 +44,7 @@ Keelson combines an **Agent Skill + local CLI**. The skill guides the agent's wo
 - A coding agent that can read project files, make changes, and run commands.
 - A local project directory; Git is recommended for tracking code and project knowledge.
 
-Keelson generates integrations for Codex, Claude Code, OpenCode, Gemini CLI, and other hosts. See [Agent support](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md) for capabilities and validation coverage.
+Claude Code, Codex CLI and CodeBuddy CLI are the primary supported hosts. Keelson also generates integrations for other coding agents. See [Agent support](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md) for capabilities and validation coverage.
 
 ## Quick start
 
@@ -57,24 +54,30 @@ Keelson generates integrations for Codex, Claude Code, OpenCode, Gemini CLI, and
 npm install -g @zyaiting/keelson
 ```
 
-**2. Initialize your project**, using Codex here:
+**2. Initialize your project**, selecting your CLI:
 
 ```bash
 cd /path/to/your/project
-keelson init --codex
+keelson init --claude     # Claude Code
+# or: keelson init --codex
+# or: keelson init --codebuddy
 ```
 
 **3. Open your agent in that directory and describe the task.** Initialize once, then keep working through conversation.
 
-> Add a priority filter to the task list: show everything by default, with an option for high-priority tasks only. Keep existing calls compatible, add tests, and verify the result.
+> Add a priority filter to the task list.
 
 To upgrade, run `npm install -g @zyaiting/keelson@latest`, then `keelson update` in your project. See the [setup guide](https://github.com/Atingaii/keelson/blob/main/docs/getting-started.md) and [supported agents](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md).
 
 ## From request to completion
 
-**Understand → Scope → Implement and verify → Archive and resume**
+**Investigate → Decide → Implement → Independently review → Verify → Preserve knowledge**
+
+After initialization, ordinary requests trigger the relevant workflow automatically: investigate requirements, clarify material choices with recommendations, apply engineering and UI/UX guidance, implement, verify, and preserve the result for later sessions. You do not need to name a skill or manage workflow commands. Clear edits use a minimal change record. A simple gap gets one question; connected uncertainties get the whole ready decision frontier, with recommendations and reasons for each choice. The agent resumes authorized work once those choices are settled.
+
+Before implementation, the agent starts the settled change and loads its declared specs and rules. Review gets a separate context pack built from the request and contracts. Verified changes promote durable decisions into project specs, so later work starts with what the project has learned.
 
-The agent loads relevant guidance, maintains acceptance criteria, and runs project checks. It wraps up when the gates pass, asking for your input when a choice changes the plan. Small edits stay lightweight.
+Claude Code, Codex and CodeBuddy integrations restore workflow context and gate supported file edits. Codex requires the generated hooks to be trusted in `/hooks` when prompted; other host permissions remain in effect. Disabled hooks fall back to installed guidance and the shared CLI. See [automation and its boundaries](https://github.com/Atingaii/keelson/blob/main/docs/automation.md).
 
 You can also ask:
 
@@ -82,7 +85,7 @@ You can also ask:
 - **Improve an interface:** “Polish the settings page, keep our brand, preserve input when saving fails, and check the mobile flow.”
 - **Resume:** “Continue the previous change. First check what's left.”
 
-Frontend work has 22 composable [design actions](https://github.com/Atingaii/keelson/blob/main/docs/frontend.md), discoverable with `keelson design`, including critique, simplification, polish, and adaptation. Checking the actual interface requires the agent to use a browser.
+The agent automatically selects from 22 composable [design actions](https://github.com/Atingaii/keelson/blob/main/docs/frontend.md), discoverable with `keelson design`, including critique, simplification, polish, and adaptation when the work affects an interface. Checking the actual interface requires the agent to use a browser.
 
 ## What stays in your project?
 

package/README_CN.md

@@ -1,6 +1,6 @@
 <p align="center"><img src="https://raw.githubusercontent.com/Atingaii/keelson/main/docs/assets/keelson-banner.png" alt="Keelson" width="620"></p>
 
-<p align="center"><strong>在仓库里对话，让每次开发都有据可循、有处接续。</strong></p>
+<p align="center"><strong>让 Agent 先想清楚，再按规范做完，把经验留在仓库。</strong></p>
 <p align="center">为编码 Agent 提供项目记忆、工程方法和验收流程。你描述目标，Agent 推进实现，把决策与验证留在代码旁。</p>
 
 <p align="center">
@@ -16,16 +16,13 @@
 <a href="https://github.com/Atingaii/keelson/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
 </p>
 
-<p align="center"><img src="https://raw.githubusercontent.com/Atingaii/keelson/main/docs/assets/keelson-demo-zh.gif" alt="真实 Agent 对话回放：用户提出任务筛选需求，Agent 完成实现、验证与归档" width="100%"></p>
-<p align="center"><sub>已初始化的示例仓库 · 真实会话节选，等待已压缩 · 用户只需提出需求</sub></p>
-
 ## 为什么选择 Keelson？
 
 Keelson 将软件工程中的成熟做法带进日常 Agent 对话：先对齐结果，留下决策依据，再检查实际产出。它围绕四个常见问题展开。
 
 **1. Agent 做出来的，并不是你想要的。**
 
-“加个筛选”背后，还有默认行为、边界情况和兼容性。Keelson 引导 Agent 先读代码，把需求变成具体的验收示例，再开始实现。这借鉴了**行为驱动开发（BDD）**：通过例子尽早发现理解偏差，只对影响方向的选择提问。
+“加个筛选”背后，还有默认行为、边界情况和兼容性。Keelson 引导 Agent 先读代码，自动调查模糊目标和相互关联的选择，把需求变成具体的验收示例，再开始实现。这借鉴了**行为驱动开发（BDD）**：通过例子尽早发现理解偏差，只对影响方向的选择提问。
 
 **2. 换个会话，又得解释同一个项目。**
 
@@ -47,7 +44,7 @@ Keelson 由 **Agent Skill + 本地 CLI** 组成：Skill 指导 Agent 如何工
 - 一个能读取项目、修改文件并执行命令的编码 Agent。
 - 一个本地项目目录；建议使用 Git 管理代码和项目知识。
 
-支持生成 Codex、Claude Code、OpenCode、Gemini CLI 等宿主的集成入口；各宿主的能力与验证范围见 [Agent 支持](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md)。
+重点适配 **Claude Code、Codex CLI 和 CodeBuddy CLI**，也支持其他编码 Agent 的集成入口；各宿主的能力与验证范围见 [Agent 支持](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md)。
 
 ## 快速开始
 
@@ -57,24 +54,30 @@ Keelson 由 **Agent Skill + 本地 CLI** 组成：Skill 指导 Agent 如何工
 npm install -g @zyaiting/keelson
 ```
 
-**2. 在你的项目中初始化**，以 Codex 为例：
+**2. 在你的项目中初始化**，选择使用的 CLI：
 
 ```bash
 cd /path/to/your/project
-keelson init --codex --lang zh
+keelson init --claude --lang zh       # Claude Code
+# 或：keelson init --codex --lang zh
+# 或：keelson init --codebuddy --lang zh
 ```
 
 **3. 在这个目录启动 Agent，直接提出需求。** 初始化只需一次；后续正常对话即可。
 
-> 给任务列表加一个优先级筛选：默认显示全部，也能只看高优先级。保持现有调用兼容，补齐测试并完成验证。
+> 给任务列表加一个优先级筛选。
 
 升级 CLI：`npm install -g @zyaiting/keelson@latest`，然后在项目中运行 `keelson update`。更多设置见[上手教程](https://github.com/Atingaii/keelson/blob/main/docs/zh/getting-started.md)；其他宿主见 [Agent 支持](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md)。
 
 ## 从一句需求到一次完成
 
-**理解目标 → 明确范围 → 实现与验证 → 归档与接续**
+**调查 → 决策 → 实现 → 独立复核 → 验证 → 知识回写**
+
+初始化后，普通需求自动触发相应流程：调查需求、带着推荐澄清关键选择、应用工程与 UI/UX 指导、实现、验证，并保留结果供后续会话接续。你无需点名 Skill 或管理工作流命令。明确的小修改使用最小变更记录；简单缺口一次问一个，复杂问题一轮问完前提已明确的整组决定，每题给推荐与理由。决定明确后继续已授权的工作。
+
+实现前，Agent 自动启动已澄清的变更，加载声明的规范与规则；复核使用从原始需求和契约生成的独立上下文包。验收后，持久决策回写到项目规范，下次开发继续使用这些知识。
 
-Agent 按任务读取需要的指导，维护验收标准并执行项目检查；条件满足后自动收尾。遇到影响方案的选择时再与你确认，普通小修改保持轻量。
+Claude Code、Codex 和 CodeBuddy 集成均支持恢复流程上下文，并对受支持的文件修改执行启动门禁。Codex 首次提示时需在 `/hooks` 中信任生成的 hooks；各宿主原有权限确认继续生效。禁用 hooks 时，由已安装指导驱动相同 CLI。详见[自动化机制与边界](https://github.com/Atingaii/keelson/blob/main/docs/zh/automation.md)。
 
 你也可以这样说：
 
@@ -82,7 +85,7 @@ Agent 按任务读取需要的指导，维护验收标准并执行项目检查
 - **改善界面：**“优化设置页，保留品牌风格，保存失败时不要丢输入，并检查手机端体验。”
 - **接着开发：**“继续上次的改动，先确认还剩什么。”
 
-前端任务有 22 个可组合的[设计动作](https://github.com/Atingaii/keelson/blob/main/docs/zh/frontend.md)，可通过 `keelson design` 查看，包括审视、简化、打磨和适配。实际界面效果需要 Agent 使用浏览器检查。
+涉及界面的任务中，Agent 会从 22 个可组合的[设计动作](https://github.com/Atingaii/keelson/blob/main/docs/zh/frontend.md)中按需选择，包括审视、简化、打磨和适配；可通过 `keelson design` 查看。实际界面效果需要 Agent 使用浏览器检查。
 
 ## 项目里会留下什么？
 

package/hooks/codebuddy-session.mjs

@@ -1,16 +1,13 @@
 #!/usr/bin/env node
 // CodeBuddy session bridge for Keelson.
-// SessionStart/UserPromptSubmit: touch local session runtime and inject a tiny focus hint.
+// SessionStart/UserPromptSubmit: restore workflow and declared project contracts.
 // PreToolUse(Bash|PowerShell): deterministically prepend KEELSON_SESSION_ID to the command.
 // Raw CodeBuddy session ids are never written to disk.
-import crypto from 'node:crypto';
 import fs from 'node:fs';
-import path from 'node:path';
-import { runtimeDir } from '../src/lib/runtime-path.js';
+import { findProjectRoot } from '../src/lib/paths.js';
+import { hookEnvironment, sessionContext } from '../src/lib/hook-context.js';
+import { writeSession } from '../src/lib/session.js';
 
-const hash = (value, n) => crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, n);
-const readJson = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
-const writeJson = (p, v) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, JSON.stringify(v, null, 2) + '\n'); };
 const shellQuote = (v) => `'${String(v).replace(/'/g, "'\\''")}'`;
 
 let input = {};
@@ -19,17 +16,13 @@ try {
   if (raw.trim()) input = JSON.parse(raw);
 } catch {}
 
-const root = input.cwd || process.env.CODEBUDDY_PROJECT_DIR || process.cwd();
+const root = findProjectRoot(process.env.CODEBUDDY_PROJECT_DIR || input.cwd || process.cwd());
 const sessionId = typeof input.session_id === 'string' ? input.session_id.trim() : '';
-if (!sessionId || !fs.existsSync(path.join(root, '.keelson'))) process.exit(0);
+if (!sessionId || !root) process.exit(0);
 
-const opaque = hash(`codebuddy:${sessionId}`, 32);
-const key = hash(opaque, 24);
-const sessionFile = path.join(runtimeDir(root), 'sessions', `${key}.json`);
-const session = readJson(sessionFile) || { schema: 1, change: null, createdAt: new Date().toISOString() };
-session.updatedAt = new Date().toISOString();
-session.source = 'codebuddy';
-writeJson(sessionFile, session);
+const env = hookEnvironment('codebuddy', input);
+const opaque = env.KEELSON_SESSION_ID;
+writeSession(root, { source: 'codebuddy' }, env);
 
 const event = input.hook_event_name || '';
 if (event === 'PreToolUse' && ['bash', 'powershell'].includes(String(input.tool_name || '').toLowerCase())) {
@@ -44,8 +37,6 @@ if (event === 'PreToolUse' && ['bash', 'powershell'].includes(String(input.tool_
     continue: true,
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
-      permissionDecision: 'allow',
-      permissionDecisionReason: 'Keelson attached the opaque session identity used only for local work-focus routing.',
       modifiedInput: {
         ...input.tool_input,
         command: injected,
@@ -55,13 +46,7 @@ if (event === 'PreToolUse' && ['bash', 'powershell'].includes(String(input.tool_
   process.exit(0);
 }
 
-const changesDir = path.join(root, '.keelson', 'changes');
-const active = fs.existsSync(changesDir)
-  ? fs.readdirSync(changesDir, { withFileTypes: true })
-      .filter((d) => d.isDirectory() && d.name !== 'archive' && fs.existsSync(path.join(changesDir, d.name, 'change.md')))
-      .map((d) => d.name)
-  : [];
-const focused = session.change && active.includes(session.change) ? session.change : null;
-if (focused) process.stdout.write(`[keelson] session focus: ${focused}; use the existing change unless the user requests an independent outcome.\n`);
-else if (active.length === 1) process.stdout.write(`[keelson] resume candidate: ${active[0]}; bind only if this prompt continues that work.\n`);
-else if (active.length > 1) process.stdout.write(`[keelson] active changes: ${active.join(', ')}; no session focus, so do not guess.\n`);
+if (['SessionStart', 'UserPromptSubmit'].includes(event)) {
+  try { process.stdout.write(sessionContext(root, env, event, 'codebuddy') + '\n'); }
+  catch (error) { process.stdout.write(`[keelson] Context restoration needs attention: ${error.message}\n`); }
+}

package/hooks/codex-session.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { findProjectRoot } from '../src/lib/paths.js';
+import { hookEnvironment, sessionContext } from '../src/lib/hook-context.js';
+
+let input = {};
+try { input = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+const root = findProjectRoot(input.cwd || process.cwd());
+if (!root) process.exit(0);
+const event = input.hook_event_name || 'SessionStart';
+try {
+  const context = sessionContext(root, hookEnvironment('codex', input), event, 'codex');
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: context } }) + '\n');
+} catch (error) {
+  process.stdout.write(`[keelson] Context restoration needs attention: ${error.message}\n`);
+}

package/hooks/prompt-state.mjs

@@ -5,10 +5,10 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { runtimeDir } from '../src/lib/runtime-path.js';
+import { workflowHint } from '../src/lib/workflow.js';
 
 const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const k = path.join(root, '.keelson');
-const changesDir = path.join(k, 'changes');
 if (!fs.existsSync(k)) process.exit(0);
 
 const read = (p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n') : '');
@@ -35,32 +35,8 @@ if (sessionPath) {
   session.source = 'claude-prompt';
   writeJson(sessionPath, session);
 }
-if (!fs.existsSync(changesDir)) process.exit(0);
-
-const summarize = (name) => {
-  const dir = path.join(changesDir, name);
-  const change = read(path.join(dir, 'change.md'));
-  if (!change) return null;
-  const tasks = read(path.join(dir, 'tasks.md'));
-  const total = (tasks.match(/^\s*[-*]\s+\[[ xX]\]/gm) || []).length;
-  const done = (tasks.match(/^\s*[-*]\s+\[[xX]\]/gm) || []).length;
-  const ledger = read(path.join(dir, 'ledger.md'));
-  const verifies = [...ledger.matchAll(/^###\s+Verify:[\s\S]*?exit\s*(?:code)?\s*[:=]?\s*(\d+)/gim)];
-  const lastExit = verifies.length ? Number(verifies.at(-1)[1]) : null;
-  const explicit = (change.match(/^status:\s*([\w-]+)/m) || [])[1];
-  const verify = verifies.length ? (lastExit === 0 ? 'passed' : 'failed') : 'not-run';
-  const open = (change.match(/^##\s+Open questions?\s*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/im) || [])[1] || '';
-  const openCount = (open.match(/^\s*[-*]\s+(?!…|none)/gim) || []).length;
-  return `${name} · ${explicit || (total ? (done < total ? 'in-progress' : 'awaiting verification') : 'in-progress')} · verify ${verify}${total ? ` · ${done}/${total} tasks` : ''}${openCount ? ` · ${openCount} open` : ''}`;
-};
-
-if (session?.change) {
-  const line = summarize(session.change);
-  if (line) process.stdout.write(`[keelson] focus: ${line}\n`);
-  process.exit(0);
+try {
+  process.stdout.write(workflowHint(root, { ...process.env, ...(envIdentity ? { KEELSON_SESSION_ID: envIdentity } : {}) }) + '\n');
+} catch (error) {
+  process.stdout.write(`[keelson] Cannot restore workflow: ${error.message}. Run keelson doctor before implementation.\n`);
 }
-
-const names = fs.readdirSync(changesDir, { withFileTypes: true })
-  .filter((d) => d.isDirectory() && d.name !== 'archive' && fs.existsSync(path.join(changesDir, d.name, 'change.md')))
-  .map((d) => d.name);
-if (names.length === 1) process.stdout.write(`[keelson] resume candidate: ${summarize(names[0])}; bind only if this prompt continues that work\n`);

package/hooks/session-start.mjs

@@ -5,6 +5,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { runtimeDir } from '../src/lib/runtime-path.js';
+import { activeWorkflow, phaseContext, renderPhaseContext, workflowHint } from '../src/lib/workflow.js';
 
 const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const k = path.join(root, '.keelson');
@@ -57,6 +58,7 @@ if (sessionPath) {
   session = readJson(sessionPath) || { schema: 1, change: null, createdAt: new Date().toISOString() };
   session.updatedAt = new Date().toISOString();
   session.source = 'claude-session-start';
+  session.injectedContexts = []; // compact/resume must restore previously injected constraints.
   writeJson(sessionPath, session);
 }
 
@@ -91,4 +93,9 @@ if (ordered.length) {
   lines.push('', '--- Active work ---');
   for (const c of ordered.slice(0, 6)) lines.push(`${c.name}${c.name === focused ? ' [focus]' : ''}: ${c.tier}${c.status ? `, ${c.status}` : ''}${c.total ? `, ${c.done}/${c.total} tasks` : ''}${c.owner ? `, ${c.owner}` : ''}`);
 }
+try {
+  const env = { ...process.env, ...(envIdentity ? { KEELSON_SESSION_ID: envIdentity } : {}) };
+  lines.push('', workflowHint(root, env));
+  if (focused) lines.push(renderPhaseContext(phaseContext(root, activeWorkflow(root, focused, env))));
+} catch (error) { lines.push(`[keelson] Context restoration needs attention: ${error.message}`); }
 process.stdout.write(lines.join('\n') + '\n');

package/hooks/workflow-guard.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Host-specific file-tool gates and phase context injection. Shell/MCP writers
+// remain host-policy territory; this is a workflow guard, not a sandbox.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { findProjectRoot } from '../src/lib/paths.js';
+import { hookEnvironment } from '../src/lib/hook-context.js';
+import { readSession, writeSession } from '../src/lib/session.js';
+import { activeWorkflow, implementationBlockers, phaseContext, renderPhaseContext } from '../src/lib/workflow.js';
+
+let input = {};
+try { input = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(2); }
+const host = process.argv[2] || 'claude';
+const projectDir = host === 'claude' ? process.env.CLAUDE_PROJECT_DIR : host === 'codebuddy' ? process.env.CODEBUDDY_PROJECT_DIR : null;
+const root = findProjectRoot(projectDir || input.cwd || process.cwd());
+if (!root) process.exit(0);
+const env = hookEnvironment(host, input);
+const event = input.hook_event_name || 'PreToolUse';
+const tool = input.tool_name;
+const output = (fields) => process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, ...fields } }) + '\n');
+
+try {
+  const session = readSession(root, env);
+  const name = session.state?.change;
+  if (host === 'codex' && event === 'SubagentStart' && !name) {
+    // session_id is the root, not necessarily the spawning parent. Let the
+    // assigned task name its change rather than inheriting an unrelated focus.
+    output({ additionalContext: '[keelson] Preserve your assigned scope, including read-only work. If your task includes KEELSON_CHANGE=<name>, run `keelson focus <name>`, then `keelson context --phase check` for review or `--phase implement` for implementation before doing that work. Do not infer a task from the root session or sole repository candidate. Without a marker, keep discovery read-only; create or select a change only when the task explicitly requires implementation. These commands do not grant permission to edit.' });
+    process.exit(0);
+  }
+  const workflow = activeWorkflow(root, name, env);
+  // Never infer an unrelated session's change from the sole repository candidate.
+  if (!name) workflow.change = null;
+  const args = input.tool_input ?? {};
+  const file = args.file_path ?? args.notebook_path;
+  const patch = host === 'codex' && tool === 'apply_patch';
+  const editing = patch || ['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'NotebookWrite'].includes(tool);
+  const files = patch
+    ? [...String(args.command ?? '').matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)\r?$/gm)].map((m) => m[1].trim())
+    : typeof file === 'string' ? [file] : [];
+  const relative = files.map((f) => path.relative(root, path.resolve(input.cwd || root, f)).replace(/\\/g, '/'));
+  const planningOnly = relative.length > 0 && relative.every((f) => f.startsWith('.keelson/') && !f.split('/').includes('..'));
+  if (editing && !planningOnly) {
+    const blockers = implementationBlockers(workflow.change, workflow.changes);
+    if (blockers.length) {
+      output({ permissionDecision: 'deny', permissionDecisionReason: blockers.join(' ') + ' The agent should resolve this within existing authorization; do not ask the user to run workflow commands.' });
+      process.exit(0);
+    }
+  }
+  if (editing && planningOnly) process.exit(0);
+  if (!workflow.change) process.exit(0);
+  if (host === 'codex' && ['spawn_agent', 'Agent', 'Task'].includes(tool)) {
+    const markers = [...String(args.message ?? args.prompt ?? '').matchAll(/^\s*KEELSON_CHANGE=([^\s]+)[ \t]*$/gm)];
+    if (markers.length !== 1 || markers[0][1] !== name) {
+      output({ permissionDecision: 'deny', permissionDecisionReason: `Add the single line KEELSON_CHANGE=${name} to this child task so its own CLI session can bind the assigned change. Keep its phase, original instructions and any read-only scope. The agent should correct the task prompt; do not ask the user to run workflow commands.` });
+      process.exit(0);
+    }
+  }
+  const descriptor = `${input.agent_type ?? ''} ${args.subagent_type ?? args.agent_type ?? ''} ${args.description ?? ''} ${args.prompt ?? args.message ?? ''}`;
+  const reviewing = /KEELSON_PHASE=check|keelson-check|\breview\b|\breviewer\b|复核|审查/i.test(descriptor);
+  if (event === 'SubagentStart' && !reviewing && !/KEELSON_PHASE=implement|keelson-implement/i.test(descriptor)) {
+    // Generic agent_type carries no parent's prompt or reliable phase. The
+    // Agent/Task hook already injected the appropriate pack into that prompt.
+    const hint = '[keelson] Follow the phase and contracts in your task prompt. If they are missing, load `keelson context --phase check` for review or `--phase implement` for implementation. Preserve your assigned scope; context is not permission to edit.';
+    // A bound Codex child can safely receive its own packs. An unbound child
+    // received explicit binding instructions above, never a guessed root task.
+    const packs = host === 'codex' ? ['implement', 'check'].map((phase) => renderPhaseContext(phaseContext(root, workflow, phase))) : [];
+    output({ additionalContext: [hint, ...packs].join('\n\n') });
+    process.exit(0);
+  }
+  const phase = reviewing ? 'check' : 'implement';
+  const pack = phaseContext(root, workflow, phase, relative);
+  const context = renderPhaseContext(pack);
+  if (['Agent', 'Task'].includes(tool) && typeof args.prompt === 'string') {
+    // Preserve every original argument and normal host permission checks.
+    if (host === 'codex') output({ additionalContext: context });
+    else output({ [host === 'codebuddy' ? 'modifiedInput' : 'updatedInput']: { ...args, prompt: `${args.prompt}\n\n${context}` } });
+  } else if (event === 'SubagentStart') {
+    output({ additionalContext: context });
+  } else if (host === 'codex' && input.agent_id) {
+    // Codex does not emit SessionStart when a child compacts or resumes. Do
+    // not suppress the next contract pack on the basis of a pre-compact cache.
+    output({ additionalContext: context });
+  } else if (host !== 'codebuddy') {
+    const digest = crypto.createHash('sha256').update(`${input.agent_id ?? 'main'}\n${context}`).digest('hex');
+    if (!(session.state?.injectedContexts ?? []).includes(digest)) {
+      output({ additionalContext: context });
+      writeSession(root, { injectedContexts: [...(session.state?.injectedContexts ?? []).slice(-15), digest] }, env);
+    }
+  }
+} catch (error) {
+  if (event === 'PreToolUse') output({ permissionDecision: 'deny', permissionDecisionReason: `Keelson context could not be loaded: ${error.message}. Repair the declared context before retrying.` });
+  else output({ additionalContext: `Keelson context could not be loaded: ${error.message}. Investigate before implementation.` });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyaiting/keelson",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Local, verifiable check records and durable decisions for AI-assisted code changes.",
   "type": "module",
   "bin": {

package/registry/platforms.json

@@ -1,7 +1,7 @@
 {
   "version": 2,
-  "updated": "2026-09-20",
-  "note": "Adapters describe generated discovery paths, not a promise of live end-to-end host parity. Codex session identity has been exercised locally. Other hosts have adapter contract tests; hooks are supported only where listed. Native session identity sources include CODEX_THREAD_ID, Claude hooks, Pi environment and explicit KEELSON_SESSION_ID. No source means an honest degraded state. Default installation is lightweight; --vendor explicitly copies package guidance.",
+  "updated": "2026-09-21",
+  "note": "Adapters describe generated discovery paths, not a promise of live end-to-end host parity. Codex session identity has been exercised locally. Other hosts have adapter contract tests; Claude Code, Codex and CodeBuddy have workflow hook adapters; hook execution depends on the host version, trust and settings. Native session identity sources include CODEX_THREAD_ID, Claude hooks, Pi environment and explicit KEELSON_SESSION_ID. No source means an honest degraded state. Default installation is lightweight; --vendor explicitly copies package guidance.",
   "platforms": {
     "claude": {
       "label": "Claude Code",
@@ -19,7 +19,7 @@
       "bin": "codex",
       "instructions": "AGENTS.md",
       "skillsDir": ".agents/skills",
-      "hooks": false,
+      "hooks": true,
       "confidence": "verified",
       "support": "first-class",
       "sessionFocus": "native",
@@ -71,7 +71,7 @@
       "bin": "codebuddy",
       "instructions": "CODEBUDDY.md",
       "skillsDir": ".codebuddy/skills",
-      "hooks": false,
+      "hooks": true,
       "confidence": "documented",
       "support": "first-class",
       "sessionFocus": "native",

package/registry/runtime-hashes.json

@@ -0,0 +1,41 @@
+{
+  "source": "Generated from published @zyaiting/keelson 0.4.0 and 0.4.1 (English/Chinese, lean/guided, guide on/off). Hashes include paths and normalized file bytes; only exact generated content may be replaced.",
+  "versions": {
+    "0.4.0": {
+      "shims": [
+        "cebe268136c46d9b190f31d5521770a8fe81dd0aa53dfccfd1dfbf39dafa26e7",
+        "5cef12b9c5aec6410040c1f5033fc60cc76fd9837bc73abfef147e36096b981a"
+      ],
+      "skills": [
+        "490534b10c8f594cd8ca40dc4817f56f1d9e84bca1cff973c45d857f367269d1",
+        "a8cdf54fc5e68a03d74c4d8a8a1f714997c1340318b3c664fab1d3473c865dd7",
+        "7d56a7c7197f2363bbbace9149465ade63c8308eb2dfed15d76fbcf892dd5a58",
+        "4e2ca439e8e11683d8913ab72f05537cbbde4afa6d61ad0e0848a59f9cf7bae7"
+      ],
+      "workflows": [
+        "455f5bb4060b984cd1839aed452fb82cbc09101d81d28630bdaa9547aca6d050",
+        "9099f590ae1b8192de759cc9b9d2187d37961b841e80bedd6175c23eac752af1",
+        "73f8562e785d8259d853257d02ac1e0688a5882d8c8e701b42a4e289b317be31",
+        "ca267bd38b5353684e3deb7d1774bb75d25005381541ba67597cd9fb530ad538"
+      ]
+    },
+    "0.4.1": {
+      "shims": [
+        "4afd7eb69ca1ab1913c73737e56890ca6e363881b1cedc76e95f97b0e5d528e3",
+        "a2d88237dbaa7a9aa0fc5340e73690737a5c58f13013dff93604d2414f3fef38"
+      ],
+      "skills": [
+        "bc676907188784049abf44f271643ea726b82ad34eb3af994bbf1b382f8e3d5f",
+        "9f2a472f526646a3f1e180bb1cf9f1aaec74a0da5f4e937c9ca1ed5d88f11602",
+        "adb328b4553e9d3d5e1826f91ffd10528b7f7b6b04565e0c1801606d04509686",
+        "d7ac8d6b0e8c849cca28f574fc6fb355aa863f90c93fbf2165a43a1d14cabe34"
+      ],
+      "workflows": [
+        "455f5bb4060b984cd1839aed452fb82cbc09101d81d28630bdaa9547aca6d050",
+        "9099f590ae1b8192de759cc9b9d2187d37961b841e80bedd6175c23eac752af1",
+        "73f8562e785d8259d853257d02ac1e0688a5882d8c8e701b42a4e289b317be31",
+        "ca267bd38b5353684e3deb7d1774bb75d25005381541ba67597cd9fb530ad538"
+      ]
+    }
+  }
+}

package/skills/keelson/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keelson
-description: Engineering control plane for coding work in repositories with a .keelson/ directory. Use for exploring an idea, changing code, fixing/debugging, frontend design and UX review, continuing prior work, or improving recurring engineering failures. Keeps conversation sessions separate from durable work items so users can keep asking questions without having to announce when a task starts or ends.
+description: Engineering workflow for repositories with a .keelson/ directory. Apply automatically to ordinary requests to explore an idea, build or change a feature, fix a bug, create or improve an interface, continue prior work, or improve recurring engineering failures. Routes discovery, design, implementation, verification and project memory without requiring skill names or workflow commands.
 ---
 
 # Keelson
@@ -21,6 +21,8 @@ Completion is **not** an intent and never depends on the user saying “done”.
 
 - For interface design, review, interaction or responsive work, load `frontend.md`; use `keelson design` for focused action briefs. Keep browser observations distinct from code checks.
 
+Route from the requested outcome and repository evidence, not special vocabulary. Users describe work; the agent loads guidance and runs workflow commands. Automatically include `model.md` for conflicting terms or shared boundaries, `engineer.md` for non-obvious design choices, and `frontend.md` when the affected path includes a user interface, even without an explicit design request. During implementation use `build.md`; complete with `verify.md` → `land.md` → `reconcile.md` within existing authorization. `guide: true` adds teaching, not activation; both profiles use this workflow by default.
+
 ## Operating rules
 
 - A conversation/session is only a focus pointer. Ending a window, going idle, or continuing to ask questions MUST NOT mark a change complete.
@@ -28,9 +30,10 @@ Completion is **not** an intent and never depends on the user saying “done”.
 - On Resume, use `keelson focus --auto`; branch match or a sole active change may be suggested. Never silently bind an ambiguous session.
 - If `NOW.md` says “First contact”, infer and confirm `INTENT.md`; do not inventory the whole repository into specs/rules.
 - Non-trivial modifying work starts from current context; shared modules get `keelson impact <files>`.
-- Ask only at the decision frontier. Run the triggered blindspot pass, then use `interview.md`: up to three independent ready owner-owned decisions per round, skipping settled answers, concrete scenario/options, recommended default, and `not sure` as a valid route. Never ask what repo evidence, an experiment, or agent engineering judgment can settle.
+- Automatically assess discovery needs on new goals, material follow-ups and changed premises using `interview.md`; unresolved goals, connected product choices or high-impact commitments trigger deeper discovery without special wording. Clear tasks proceed directly. Ask one ready owner decision for a simple gap, or the whole ready frontier for connected uncertainty, with concrete options, a recommendation and reason; reuse settled answers and investigate facts yourself.
 - Route non-obvious mechanisms/architecture through `engineer.md`: reduce to facts, outcome, constraints, and invariants; state a falsifiable hypothesis; use the cheapest experiment/ablation that can discriminate; complexity must earn its keep with evidence.
-- Size only the work: trivial = direct edit; quick = lightweight change; spec = acceptance + behavior delta + plan within existing user authorization; clarify only unresolved owner choices.
+- Size only the work: trivial = minimal quick change; quick = lightweight change; spec = acceptance + behavior delta + plan within existing user authorization; clarify only unresolved owner choices.
+- Before product edits, automatically run `keelson start` for the focused change, then load `keelson context --phase implement`; after new material decisions, restart only once they are settled. Users need not run these commands.
 - Artifacts are information containers, not ceremony. Do not create empty roadmap/glossary/rule/task/ledger/handoff/spec files.
 - `tasks.md` is an execution plan, not completion authority. Unchecked plan items never override satisfied acceptance + fresh evidence; reconcile or remove stale tasks when the implementation path changes.
 - Knowledge maintenance is internal. During RECONCILE, automatically rewrite/split/dedupe pressured durable docs and let `land` auto-shard large specs; never ask the owner to maintain Keelson unless a product-semantic decision is required.

package/skills/keelson/references/build.md

@@ -2,6 +2,16 @@
 
 Execute `tasks.md` slice by slice. You choose how; these notes cover the parts that are easy to get wrong.
 
+## Enter implementation with the current plan
+<!-- keelson: id=build.start | without: an agent edits product files before resolving the plan or reads an unrelated change's rules | sunset: never -->
+
+For modifying work, create the smallest useful change, record concrete acceptance, and run `keelson start` automatically within the owner's existing authorization. Trivial work uses a minimal quick change without a separate plan or interview. Start rejects open decisions, assumptions, missing acceptance and active prerequisites; it records the current plan and declares phase context in `context.json`. Reopened decisions or changed plan/delta require resolving the affected branches and starting again. Do not ask the owner to operate the workflow.
+
+Read `keelson context --phase implement` before editing. The pack contains current and delta specs, relevant rules, decisions and checks; `context.json` can declare additional project-relative files per `implement`/`check` phase. Add newly affected paths to context routing. For spec work, retain the owner's original request and material follow-ups in `request.md` so the reviewer sees the actual requested outcome. Do not replace it with your implementation summary.
+
+Claude Code, Codex and CodeBuddy have native gates for supported file-editing tools and hooks for session context. Codex requires trusted hooks. Shell/MCP writers and other hosts must follow this same protocol through the agent. This is not a sandbox or proof of user authorization.
+
+
 ## Rulings, not stalls
 <!-- keelson: id=build.rulings | without: agent parks the session on questions the plan already answers; or decides silently and the reasoning is lost | sunset: never -->
 
@@ -21,6 +31,8 @@ When tasks are mostly independent and the host offers subagents, dispatch a fres
 
 More agents are not a linear throughput multiplier. When tasks share mutable state or the same contract, or need constant synchronization, coordination and merge cost can exceed the parallelism benefit; keep them sequential. Parallelize only when boundaries are clear, outputs are independently verifiable, and the merge contract is explicit. Do not try to rescue tightly coupled work by simply adding agents.
 
+For a tracked task, include a standalone `KEELSON_CHANGE=<change-name>` line and the phase in each child task. In Codex the child automatically runs `keelson focus <change-name>` and `keelson context --phase implement` (or `check` for review) before working. Each child has its own thread identity; never infer its task from the root session. Preserve assigned read-only scope. When resuming a child with an existing focus, retain it unless the new assignment explicitly changes it. Untracked read-only investigation needs no change or marker.
+
 After each task, a reviewer subagent (tier ≥ `standard`, never below the implementer) checks the diff against the spec and the rules. Record both in the ledger:
 
 ```markdown

package/skills/keelson/references/discover.md

@@ -1,6 +1,8 @@
 # Discovering what is wanted
 
-The user often cannot describe the whole requirement in the first sentence, and they should not need to know which engineering choice matters. Discovery finds the problem behind the request before anyone picks a database. Use `interview.md` for owner-owned uncertainty; load `design-lenses.md` only when the work triggers a real cross-domain risk.
+The user often cannot describe the whole requirement in the first sentence, and they should not need to know which engineering choice matters. Discovery finds the problem behind the request before anyone picks a database. Apply `interview.md` automatically to determine depth from the goal, unresolved choices and consequences, including when the user simply asks to build something. Load `design-lenses.md` only when the work triggers a real cross-domain risk.
+
+During read-only requests, reuse existing artifacts but keep all new write-backs, decisions and notes in the conversation, even when a change is active. The persistence steps below apply only within existing write authorization.
 
 ## Scenario before technology
 <!-- keelson: id=discover.scenario-first | without: the first question is a technology choice the owner cannot answer, and the product is shaped by whatever they guessed | sunset: never -->
@@ -42,11 +44,11 @@ Before asking, classify the gap by who can resolve it:
 |---|---|
 | Already established in repository/context | Use it; cite the source in the write-back |
 | Reality-owned (code behaviour, API contract, measurement, dependency capability) | Investigate or run a small experiment |
-| User-owned and load-bearing (goal, scope, acceptance, risk tolerance, public commitment) | Ask one question |
+| User-owned and load-bearing (goal, scope, acceptance, risk tolerance, public commitment) | Ask one question for a simple gap or the whole ready frontier for connected uncertainty |
 | Non-load-bearing or cheap to reverse | Decide under authorization, or leave unresolved for a later slice |
 | Evidence exhausted | Mark it UNKNOWN; do not convert uncertainty into a user belief |
 
-Choose the gap with the highest practical value of information: the answer most likely to change the next slice, weighted by the cost of being wrong. Before asking, apply the `interview.md` question protocol. After the answer, update the write-back and reassess the frontier. "Exactly one question" is a bottleneck for **blocking uncertainty**, not a ritual: when no user-owned load-bearing gap exists, ask nothing and proceed.
+Use `interview.md` to choose a single question for a simple gap or the whole ready frontier for connected uncertainty. Prioritize by practical value of information: the answer most likely to change the next slice, weighted by the cost of being wrong. Before asking, apply the `interview.md` question protocol. After the answer, update the write-back and reassess the frontier. Question count follows decision complexity: when no user-owned load-bearing gap exists, ask nothing and proceed.
 
 ## Scope guard
 <!-- keelson: id=discover.scope-guard | without: a first request asks for five independent domains at once, and integration risk, debugging cost, and requirement churn compound | sunset: never -->

package/skills/keelson/references/frontend.md

@@ -1,6 +1,6 @@
 # Frontend design
 
-Use for creating, improving, diagnosing or verifying an interface people see and operate. Keep the existing change lifecycle; add design judgment and observable interface acceptance.
+Apply automatically when the requested work or affected code creates, changes, diagnoses or verifies an interface people see and operate. Users need not request a design action or name this reference. Keep the existing change lifecycle; add design judgment and observable interface acceptance, scoped to the affected user journey.
 
 ## Route by the problem
 <!-- keelson: id=frontend.routing | without: Small UI fixes turn into broad redesigns and every request loads all guidance | sunset: never -->