@zyaiting/keelson 0.4.0 → 0.5.0

package/README.md

@@ -1,33 +1,40 @@
 <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">
-<a href="README_CN.md">简体中文</a> ·
+<a href="https://github.com/Atingaii/keelson/blob/main/README_CN.md">简体中文</a> ·
 <a href="#quick-start">Quick start</a> ·
-<a href="docs/README.md">Documentation</a> ·
-<a href="docs/platforms.md">Agent support</a>
+<a href="https://github.com/Atingaii/keelson/blob/main/docs/README.md">Documentation</a> ·
+<a href="https://github.com/Atingaii/keelson/blob/main/docs/platforms.md">Agent support</a>
 </p>
 
 <p align="center">
+<a href="https://www.npmjs.com/package/@zyaiting/keelson"><img src="https://img.shields.io/npm/v/%40zyaiting%2Fkeelson" alt="npm version"></a>
 <a href="https://github.com/Atingaii/keelson/actions/workflows/ci.yml"><img src="https://github.com/Atingaii/keelson/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
-<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
+<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?
 
-Coding agents can write code. Ongoing development also needs shared context, clear boundaries, and a reliable way to establish that work is done.
+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.
 
-| A familiar problem | How Keelson helps |
-| --- | --- |
-| Every new session starts with another project explanation | Goals, decisions, and unfinished work stay in the repository for the next session. |
-| Implementation starts before the request is understood | The agent reads existing code, defines acceptance, and asks about decisions that change the direction. |
-| The code is written, but completion is unclear | Check records track the inputs they verified, keeping implementation, verification, and completion distinct. |
-| The page works, but its design and interactions feel unfinished | Design guidance covers typography, color, feedback, responsive behavior, and accessibility, with browser acceptance. |
+**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, 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.**
+
+The next agent sees the code but may miss what “member” means or why an alternative was rejected. Keelson keeps domain terms, decisions, and unfinished work alongside the code. **Ubiquitous language** and **decision records** give later sessions shared vocabulary and reasons to work from, reducing repeated explanations.
+
+**3. “Done” does not say what was checked.**
+
+A passing test can miss the requested behaviour; an old result can describe old code. Keelson guides small implementation steps and acceptance review, and ties check records to the inputs they verified. **Short feedback loops** become a concrete completion gate: missing or stale verification blocks normal archiving.
+
+**4. The page works, but using it feels rough.**
+
+Unclear feedback, lost form input, and awkward mobile controls are usability problems. Keelson turns **usability heuristics** into guidance for hierarchy, interaction, responsive behaviour, and accessibility. The agent reviews the actual interface in a browser and checks real interactions, alongside code checks.
 
 Keelson combines an **Agent Skill + local CLI**. The skill guides the agent's work; the CLI manages project state and verification records. Use it for features, bug fixes, refactoring, and frontend improvements.
 
@@ -37,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](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
 
@@ -47,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](docs/getting-started.md) and [supported agents](docs/platforms.md).
+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.
 
-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.
+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.
+
+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:
 
@@ -72,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](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?
 
@@ -85,17 +98,22 @@ Initialization creates a small foundation. Further documents appear as the work
 | `.keelson/changes/`, `.keelson/specs/`, `.keelson/rules/` | Changes, behavior contracts, and project rules created as needed. |
 | Host entry points such as `AGENTS.md` | Direct the agent to Keelson. |
 
-Guidance comes from the installed package by default. Use `--vendor` when you want to commit a copy alongside your project. See [configuration](docs/configuration.md) for paths and options.
+Guidance comes from the installed package by default. Use `--vendor` when you want to commit a copy alongside your project. See [configuration](https://github.com/Atingaii/keelson/blob/main/docs/configuration.md) for paths and options.
 
 ## Engineering principles
 
-- **Start with the problem.** Establish outcomes, constraints, and invariants before choosing mechanisms. Additional complexity must earn its place.
-- **Load and retain what matters.** Small edits move directly; larger work adds contracts and plans. Preserve knowledge the next change will need.
-- **Build through feedback.** Use small steps, independent review, and focused checks. Record test results separately from browser observations.
-- **Ground completion in evidence.** Check records are tied to verified inputs; changed code needs fresh verification. Ending a conversation does not finish a task.
+The ideas above come from established engineering and interaction design practices. Keelson adapts them to repository work:
+
+| Principle | How it appears in Keelson |
+| --- | --- |
+| [Behaviour-driven development](https://cucumber.io/docs/bdd/) | Describe observable behaviour with acceptance examples; use them to guide implementation and review. |
+| [Ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html), from domain-driven design | Keep project terms and code-name mappings in a glossary as needed, so conversation and code use the same meanings. |
+| [Architecture decision records](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) | Keep concise decisions and trade-offs in the repository, with their context available to the next session. |
+| [Small iterations and feedback](https://agilemanifesto.org/principles.html) | Build a working slice, check it, and adjust; keep small changes lightweight and add planning when complexity warrants it. |
+| [Usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) | Review visible status, consistent language, error recovery, and user control through actual interface interactions. |
 
-Review commands in `.keelson/config.yaml` before their first execution. The agent runs and records checks with `keelson check --trust --record`; passing exit codes still need an acceptance review. See [verification and trust](docs/verification.md).
+Review commands in `.keelson/config.yaml` before their first execution. The agent runs and records checks with `keelson check --trust --record`; passing exit codes still need an acceptance review. See [verification and trust](https://github.com/Atingaii/keelson/blob/main/docs/verification.md).
 
 ## Documentation and contributing
 
-[Documentation](docs/README.md) · [CLI reference](docs/cli.md) · [Frontend design](docs/frontend.md) · [Contributing](CONTRIBUTING.md) · [Report an issue](https://github.com/Atingaii/keelson/issues) · [MIT](LICENSE)
+[Documentation](https://github.com/Atingaii/keelson/blob/main/docs/README.md) · [CLI reference](https://github.com/Atingaii/keelson/blob/main/docs/cli.md) · [Frontend design](https://github.com/Atingaii/keelson/blob/main/docs/frontend.md) · [Contributing](https://github.com/Atingaii/keelson/blob/main/CONTRIBUTING.md) · [Report an issue](https://github.com/Atingaii/keelson/issues) · [MIT](https://github.com/Atingaii/keelson/blob/main/LICENSE)

package/README_CN.md

@@ -1,33 +1,40 @@
 <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">
-<a href="README.md">English</a> ·
+<a href="https://github.com/Atingaii/keelson/blob/main/README.md">English</a> ·
 <a href="#快速开始">快速开始</a> ·
-<a href="docs/zh/README.md">文档</a> ·
-<a href="docs/platforms.md">Agent 支持</a>
+<a href="https://github.com/Atingaii/keelson/blob/main/docs/zh/README.md">文档</a> ·
+<a href="https://github.com/Atingaii/keelson/blob/main/docs/platforms.md">Agent 支持</a>
 </p>
 
 <p align="center">
+<a href="https://www.npmjs.com/package/@zyaiting/keelson"><img src="https://img.shields.io/npm/v/%40zyaiting%2Fkeelson" alt="npm 版本"></a>
 <a href="https://github.com/Atingaii/keelson/actions/workflows/ci.yml"><img src="https://github.com/Atingaii/keelson/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
-<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
+<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？
 
-编码 Agent 能写代码，但长期开发还需要持续的上下文、明确的边界和可信的验收。
+Keelson 将软件工程中的成熟做法带进日常 Agent 对话：先对齐结果，留下决策依据，再检查实际产出。它围绕四个常见问题展开。
 
-| 开发中遇到的问题 | Keelson 如何处理 |
-| --- | --- |
-| 换个会话，又要解释整个项目 | 将目标、决策和未完成工作保存在仓库，下次继续读取。 |
-| 需求说完就开写，结果偏离预期 | 先读现有实现，明确验收；只对影响方向的关键选择提问。 |
-| 代码写完了，却不知道是否真的完成 | 保存与当前代码对应的检查记录，区分实现、验证和完成。 |
-| 页面能用，却缺少设计与交互细节 | 提供设计指导，覆盖排版、配色、状态反馈、响应式和无障碍，并要求浏览器验收。 |
+**1. Agent 做出来的，并不是你想要的。**
+
+“加个筛选”背后，还有默认行为、边界情况和兼容性。Keelson 引导 Agent 先读代码，自动调查模糊目标和相互关联的选择，把需求变成具体的验收示例，再开始实现。这借鉴了**行为驱动开发（BDD）**：通过例子尽早发现理解偏差，只对影响方向的选择提问。
+
+**2. 换个会话，又得解释同一个项目。**
+
+新 Agent 看得到代码，却未必知道“成员”的业务含义，也不知道某个方案为什么被否决。Keelson 将领域术语、决策和未完成工作留在仓库。**统一语言**与**决策记录**让后续会话沿用已有词汇和理由，减少重复解释。
+
+**3. 说“完成了”，却不知道验证了什么。**
+
+测试通过可能没有覆盖原始需求，旧结果也可能对应旧代码。Keelson 引导小步实现、逐项验收，并将检查记录绑定到受检输入。**短反馈循环**由此落实到完成条件：验证缺失或过期时，正常归档会被阻止。
+
+**4. 页面能用，但用起来不顺手。**
+
+反馈不清楚、保存失败丢输入、手机上操作别扭，都是可用性问题。Keelson 将**可用性启发式原则**转成层级、交互、响应式和无障碍指导，由 Agent 在浏览器中观察界面、实际操作，并结合代码检查验收。
 
 Keelson 由 **Agent Skill + 本地 CLI** 组成：Skill 指导 Agent 如何工作，CLI 管理项目状态与验证记录。适用于新功能、问题修复、重构和前端体验优化。
 
@@ -37,7 +44,7 @@ Keelson 由 **Agent Skill + 本地 CLI** 组成：Skill 指导 Agent 如何工
 - 一个能读取项目、修改文件并执行命令的编码 Agent。
 - 一个本地项目目录；建议使用 Git 管理代码和项目知识。
 
-支持生成 Codex、Claude Code、OpenCode、Gemini CLI 等宿主的集成入口；各宿主的能力与验证范围见 [Agent 支持](docs/platforms.md)。
+重点适配 **Claude Code、Codex CLI 和 CodeBuddy CLI**，也支持其他编码 Agent 的集成入口；各宿主的能力与验证范围见 [Agent 支持](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md)。
 
 ## 快速开始
 
@@ -47,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`。更多设置见[上手教程](docs/zh/getting-started.md)；其他宿主见 [Agent 支持](docs/platforms.md)。
+升级 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)。
 
 你也可以这样说：
 
@@ -72,7 +85,7 @@ Agent 按任务读取需要的指导，维护验收标准并执行项目检查
 - **改善界面：**“优化设置页，保留品牌风格，保存失败时不要丢输入，并检查手机端体验。”
 - **接着开发：**“继续上次的改动，先确认还剩什么。”
 
-前端任务有 22 个可组合的[设计动作](docs/zh/frontend.md)，可通过 `keelson design` 查看，包括审视、简化、打磨和适配。实际界面效果需要 Agent 使用浏览器检查。
+涉及界面的任务中，Agent 会从 22 个可组合的[设计动作](https://github.com/Atingaii/keelson/blob/main/docs/zh/frontend.md)中按需选择，包括审视、简化、打磨和适配；可通过 `keelson design` 查看。实际界面效果需要 Agent 使用浏览器检查。
 
 ## 项目里会留下什么？
 
@@ -85,17 +98,22 @@ Agent 按任务读取需要的指导，维护验收标准并执行项目检查
 | `.keelson/changes/`、`.keelson/specs/`、`.keelson/rules/` | 按需建立的变更、行为契约和项目规则。 |
 | 宿主入口，如 `AGENTS.md` | 引导 Agent 加载 Keelson。 |
 
-默认从已安装的包读取指导。需要把指导副本一并提交时，才使用 `--vendor`。目录与选项详见[配置文档](docs/zh/configuration.md)。
+默认从已安装的包读取指导。需要把指导副本一并提交时，才使用 `--vendor`。目录与选项详见[配置文档](https://github.com/Atingaii/keelson/blob/main/docs/zh/configuration.md)。
 
 ## 工程学原理
 
-- **从问题出发。** 先确认结果、约束和不变量，再选择技术方案；额外机制必须证明有用。
-- **按需加载，逐步沉淀。** 小改动直接推进，复杂任务补充契约与计划；只保留下一次开发需要的知识。
-- **用反馈推动实现。** 小步实现、独立审阅、针对性验证；测试结果与界面观察分别记录。
-- **让完成有证据。** 检查记录绑定受检输入，代码变化后需要重新验证；结束对话不等于完成任务。
+前面的做法来自已有的软件工程与交互设计知识。Keelson 将它们用于仓库中的具体工作：
+
+| 原理 | 在 Keelson 中如何落地 |
+| --- | --- |
+| [行为驱动开发（BDD）](https://cucumber.io/docs/bdd/) | 用验收示例描述可观察的行为，指导实现和需求核对。 |
+| 领域驱动设计中的[统一语言](https://martinfowler.com/bliki/UbiquitousLanguage.html) | 按需记录业务术语及代码名称映射，让对话和代码中的词含义一致。 |
+| [架构决策记录（ADR）](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) | 在仓库保留简短决策与取舍，让后续会话理解当时的背景。 |
+| [小步迭代与反馈](https://agilemanifesto.org/principles.html) | 先做出可工作的切片，检查后调整；小改动保持轻量，复杂时再补充计划。 |
+| [可用性启发式原则](https://www.nngroup.com/articles/ten-usability-heuristics/) | 通过实际界面操作，检查状态是否可见、用词是否一致、错误能否恢复、用户能否掌控操作。 |
 
-首次执行前应审阅 `.keelson/config.yaml` 中的检查命令。Agent 使用 `keelson check --trust --record` 运行并记录检查；退出码通过仍需对照验收标准。详见[验证与信任](docs/zh/verification.md)。
+首次执行前应审阅 `.keelson/config.yaml` 中的检查命令。Agent 使用 `keelson check --trust --record` 运行并记录检查；退出码通过仍需对照验收标准。详见[验证与信任](https://github.com/Atingaii/keelson/blob/main/docs/zh/verification.md)。
 
 ## 文档与参与
 
-[完整文档](docs/zh/README.md) · [命令参考](docs/zh/cli.md) · [前端设计](docs/zh/frontend.md) · [贡献指南](CONTRIBUTING.md) · [反馈问题](https://github.com/Atingaii/keelson/issues) · [MIT](LICENSE)
+[完整文档](https://github.com/Atingaii/keelson/blob/main/docs/zh/README.md) · [命令参考](https://github.com/Atingaii/keelson/blob/main/docs/zh/cli.md) · [前端设计](https://github.com/Atingaii/keelson/blob/main/docs/zh/frontend.md) · [贡献指南](https://github.com/Atingaii/keelson/blob/main/CONTRIBUTING.md) · [反馈问题](https://github.com/Atingaii/keelson/issues) · [MIT](https://github.com/Atingaii/keelson/blob/main/LICENSE)

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.0",
+  "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",