@zyaiting/keelson 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atingaii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+<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">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="#quick-start">Quick start</a> ·
+<a href="docs/README.md">Documentation</a> ·
+<a href="docs/platforms.md">Agent support</a>
+</p>
+
+<p align="center">
+<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>
+</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.
+
+| 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. |
+
+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.
+
+## Requirements
+
+- **Node.js 20+**, npm, and Git.
+- 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.
+
+## Quick start
+
+**1. Install the CLI:**
+
+```bash
+npm install -g @zyaiting/keelson
+```
+
+**2. Initialize your project**, using Codex here:
+
+```bash
+cd /path/to/your/project
+keelson init --codex
+```
+
+**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.
+
+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).
+
+## From request to completion
+
+**Understand → Scope → Implement and verify → Archive and resume**
+
+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.
+
+You can also ask:
+
+- **Explore:** “Find where this feature belongs. Don't change code yet.”
+- **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.
+
+## What stays in your project?
+
+Initialization creates a small foundation. Further documents appear as the work needs them:
+
+| Location | Purpose |
+| --- | --- |
+| `.keelson/INTENT.md`, `.keelson/NOW.md` | Project goals, constraints, and current progress. |
+| `.keelson/config.yaml` | Project check commands and workflow configuration. |
+| `.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.
+
+## 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.
+
+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).
+
+## 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)

package/README_CN.md

@@ -0,0 +1,101 @@
+<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">为编码 Agent 提供项目记忆、工程方法和验收流程。你描述目标，Agent 推进实现，把决策与验证留在代码旁。</p>
+
+<p align="center">
+<a href="README.md">English</a> ·
+<a href="#快速开始">快速开始</a> ·
+<a href="docs/zh/README.md">文档</a> ·
+<a href="docs/platforms.md">Agent 支持</a>
+</p>
+
+<p align="center">
+<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>
+</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 如何处理 |
+| --- | --- |
+| 换个会话，又要解释整个项目 | 将目标、决策和未完成工作保存在仓库，下次继续读取。 |
+| 需求说完就开写，结果偏离预期 | 先读现有实现，明确验收；只对影响方向的关键选择提问。 |
+| 代码写完了，却不知道是否真的完成 | 保存与当前代码对应的检查记录，区分实现、验证和完成。 |
+| 页面能用，却缺少设计与交互细节 | 提供设计指导，覆盖排版、配色、状态反馈、响应式和无障碍，并要求浏览器验收。 |
+
+Keelson 由 **Agent Skill + 本地 CLI** 组成：Skill 指导 Agent 如何工作，CLI 管理项目状态与验证记录。适用于新功能、问题修复、重构和前端体验优化。
+
+## 环境要求
+
+- **Node.js 20+**，以及 npm、Git。
+- 一个能读取项目、修改文件并执行命令的编码 Agent。
+- 一个本地项目目录；建议使用 Git 管理代码和项目知识。
+
+支持生成 Codex、Claude Code、OpenCode、Gemini CLI 等宿主的集成入口；各宿主的能力与验证范围见 [Agent 支持](docs/platforms.md)。
+
+## 快速开始
+
+**1. 安装 CLI：**
+
+```bash
+npm install -g @zyaiting/keelson
+```
+
+**2. 在你的项目中初始化**，以 Codex 为例：
+
+```bash
+cd /path/to/your/project
+keelson init --codex --lang zh
+```
+
+**3. 在这个目录启动 Agent，直接提出需求。** 初始化只需一次；后续正常对话即可。
+
+> 给任务列表加一个优先级筛选：默认显示全部，也能只看高优先级。保持现有调用兼容，补齐测试并完成验证。
+
+升级 CLI：`npm install -g @zyaiting/keelson@latest`，然后在项目中运行 `keelson update`。更多设置见[上手教程](docs/zh/getting-started.md)；其他宿主见 [Agent 支持](docs/platforms.md)。
+
+## 从一句需求到一次完成
+
+**理解目标 → 明确范围 → 实现与验证 → 归档与接续**
+
+Agent 按任务读取需要的指导，维护验收标准并执行项目检查；条件满足后自动收尾。遇到影响方案的选择时再与你确认，普通小修改保持轻量。
+
+你也可以这样说：
+
+- **讨论方案：**“先看看这个功能应该放在哪里，暂时不改代码。”
+- **改善界面：**“优化设置页，保留品牌风格，保存失败时不要丢输入，并检查手机端体验。”
+- **接着开发：**“继续上次的改动，先确认还剩什么。”
+
+前端任务有 22 个可组合的[设计动作](docs/zh/frontend.md)，可通过 `keelson design` 查看，包括审视、简化、打磨和适配。实际界面效果需要 Agent 使用浏览器检查。
+
+## 项目里会留下什么？
+
+初始化保留最少的项目文件，后续随实际开发补充：
+
+| 位置 | 用途 |
+| --- | --- |
+| `.keelson/INTENT.md`、`.keelson/NOW.md` | 项目目标、约束与当前进展。 |
+| `.keelson/config.yaml` | 项目检查命令和工作流配置。 |
+| `.keelson/changes/`、`.keelson/specs/`、`.keelson/rules/` | 按需建立的变更、行为契约和项目规则。 |
+| 宿主入口，如 `AGENTS.md` | 引导 Agent 加载 Keelson。 |
+
+默认从已安装的包读取指导。需要把指导副本一并提交时，才使用 `--vendor`。目录与选项详见[配置文档](docs/zh/configuration.md)。
+
+## 工程学原理
+
+- **从问题出发。** 先确认结果、约束和不变量，再选择技术方案；额外机制必须证明有用。
+- **按需加载，逐步沉淀。** 小改动直接推进，复杂任务补充契约与计划；只保留下一次开发需要的知识。
+- **用反馈推动实现。** 小步实现、独立审阅、针对性验证；测试结果与界面观察分别记录。
+- **让完成有证据。** 检查记录绑定受检输入，代码变化后需要重新验证；结束对话不等于完成任务。
+
+首次执行前应审阅 `.keelson/config.yaml` 中的检查命令。Agent 使用 `keelson check --trust --record` 运行并记录检查；退出码通过仍需对照验收标准。详见[验证与信任](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)

package/bin/keelson.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+// Set the exit code and let the process drain stdout on its own. On macOS a pipe is asynchronous,
+// so calling process.exit() right after a large --json print would truncate the output.
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code ?? 0;
+  },
+  (err) => {
+    console.error(`keelson: ${err?.message ?? err}`);
+    if (process.env.KEELSON_DEBUG) console.error(err?.stack);
+    process.exitCode = err?.exitCode ?? 1;
+  },
+);

package/hooks/codebuddy-session.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// CodeBuddy session bridge for Keelson.
+// SessionStart/UserPromptSubmit: touch local session runtime and inject a tiny focus hint.
+// 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';
+
+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 = {};
+try {
+  const raw = fs.readFileSync(0, 'utf8');
+  if (raw.trim()) input = JSON.parse(raw);
+} catch {}
+
+const root = input.cwd || process.env.CODEBUDDY_PROJECT_DIR || process.cwd();
+const sessionId = typeof input.session_id === 'string' ? input.session_id.trim() : '';
+if (!sessionId || !fs.existsSync(path.join(root, '.keelson'))) 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 event = input.hook_event_name || '';
+if (event === 'PreToolUse' && ['bash', 'powershell'].includes(String(input.tool_name || '').toLowerCase())) {
+  const command = input.tool_input?.command;
+  if (typeof command !== 'string' || !command.trim()) process.exit(0);
+  if (/\bKEELSON_SESSION_ID\s*=/.test(command.slice(0, 180))) process.exit(0);
+  const tool = String(input.tool_name || '').toLowerCase();
+  const injected = tool === 'powershell'
+    ? `$env:KEELSON_SESSION_ID='${opaque}'; ${command}`
+    : `export KEELSON_SESSION_ID=${shellQuote(opaque)}; ${command}`;
+  process.stdout.write(JSON.stringify({
+    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,
+      },
+    },
+  }));
+  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`);

package/hooks/opencode-session.mjs

@@ -0,0 +1,65 @@
+import crypto from 'node:crypto';
+
+const hash = (value, n) => crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, n);
+const stringValue = (value) => typeof value === 'string' && value.trim() ? value.trim() : null;
+
+function lookupSession(input) {
+  if (!input || typeof input !== 'object') return null;
+  for (const key of ['session_id', 'sessionId', 'sessionID']) {
+    const value = stringValue(input[key]);
+    if (value) return value;
+  }
+  for (const key of ['input', 'event', 'properties', 'hook_input', 'hookInput']) {
+    const value = lookupSession(input[key]);
+    if (value) return value;
+  }
+  return null;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function powershellQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function shellBase(value) {
+  return String(value ?? '').replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+}
+
+function windowsPosix(env) {
+  if (env?.MSYSTEM || env?.MINGW_PREFIX || env?.OPENCODE_GIT_BASH_PATH) return true;
+  if (/(msys|mingw|cygwin)/i.test(env?.OSTYPE ?? '')) return true;
+  return /^(bash|sh|zsh)(\.exe)?$/.test(shellBase(env?.SHELL));
+}
+
+function prefix(identity, platform, env) {
+  if (platform === 'win32' && !windowsPosix(env)) return `$env:KEELSON_SESSION_ID = ${powershellQuote(identity)}; `;
+  return `export KEELSON_SESSION_ID=${shellQuote(identity)}; `;
+}
+
+function alreadyInjected(command) {
+  const first = String(command).trimStart().split(/[;&|]/, 1)[0].trimStart();
+  return /^KEELSON_SESSION_ID\s*=/.test(first) ||
+    /^export\s+KEELSON_SESSION_ID\s*=/.test(first) ||
+    /^env\s+.*KEELSON_SESSION_ID\s*=/.test(first) ||
+    /^\$env:KEELSON_SESSION_ID\s*=/i.test(first);
+}
+
+// Project-local OpenCode plugin. It does one thing: carry the current OpenCode
+// session identity into shell commands so Keelson CLI calls resolve the same
+// private keelson-runtime/sessions/<key>.json pointer. It never decides work status.
+export default async ({ platform = process.platform, env = process.env } = {}) => ({
+  'tool.execute.before': async (input, output) => {
+    if (String(input?.tool ?? '').toLowerCase() !== 'bash') return;
+    const args = output?.args;
+    if (!args || typeof args !== 'object') return;
+    const key = typeof args.command === 'string' ? 'command' : typeof args.cmd === 'string' ? 'cmd' : null;
+    if (!key || !args[key].trim() || alreadyInjected(args[key])) return;
+    const raw = lookupSession(input);
+    if (!raw) return;
+    const opaque = hash(`opencode:${raw}`, 32);
+    args[key] = prefix(opaque, platform, env) + args[key];
+  },
+});

package/hooks/prompt-state.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Keelson per-prompt state hint.
+// Touches session-local runtime state and emits only the current focus when one exists.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { runtimeDir } from '../src/lib/runtime-path.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') : '');
+const readJson = (p) => { try { return JSON.parse(read(p)); } catch { return null; } };
+const writeJson = (p, value) => {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(value, null, 2) + '\n');
+};
+const hash = (s, n) => crypto.createHash('sha256').update(String(s)).digest('hex').slice(0, n);
+
+let input = {};
+try {
+  const raw = fs.readFileSync(0, 'utf8');
+  if (raw.trim()) input = JSON.parse(raw);
+} catch {}
+const hostSession = input.session_id || input.sessionId || null;
+const envIdentity = hostSession ? hash(`claude:${hostSession}`, 32) : (process.env.KEELSON_SESSION_ID || null);
+const sessionKey = envIdentity ? hash(envIdentity, 24) : null;
+const sessionPath = sessionKey ? path.join(runtimeDir(root), 'sessions', `${sessionKey}.json`) : null;
+let session = sessionPath ? readJson(sessionPath) : null;
+if (sessionPath) {
+  session ||= { schema: 1, change: null, createdAt: new Date().toISOString() };
+  session.updatedAt = new Date().toISOString();
+  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);
+}
+
+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

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// Keelson SessionStart hook.
+// Tracks session-local work focus in Keelson's local runtime and prints a compact project snapshot.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { runtimeDir } from '../src/lib/runtime-path.js';
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const k = path.join(root, '.keelson');
+if (!fs.existsSync(k)) process.exit(0);
+
+const read = (p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n') : '');
+const readJson = (p) => {
+  try { return JSON.parse(read(p)); } catch { return null; }
+};
+const writeJson = (p, value) => {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(value, null, 2) + '\n');
+};
+const clip = (s, n) => (s.length > n ? s.slice(0, n).replace(/\s+\S*$/, '') + ' …' : s);
+const section = (text, re) => {
+  const m = text.match(new RegExp(`^##\\s+(?:${re})[^\\n]*\\n([\\s\\S]*?)(?=^##\\s|(?![\\s\\S]))`, 'im'));
+  return m ? m[1].trim() : '';
+};
+const hash = (s, n) => crypto.createHash('sha256').update(String(s)).digest('hex').slice(0, n);
+
+let input = {};
+try {
+  const raw = fs.readFileSync(0, 'utf8');
+  if (raw.trim()) input = JSON.parse(raw);
+} catch {}
+
+const hostSession = input.session_id || input.sessionId || null;
+// Never persist the host's raw session id. The exported identity is already opaque.
+const envIdentity = hostSession ? hash(`claude:${hostSession}`, 32) : (process.env.KEELSON_SESSION_ID || null);
+const sessionKey = envIdentity ? hash(envIdentity, 24) : null;
+const sessionsDir = path.join(runtimeDir(root), 'sessions');
+const sessionPath = sessionKey ? path.join(sessionsDir, `${sessionKey}.json`) : null;
+
+if (envIdentity && process.env.CLAUDE_ENV_FILE) {
+  const line = `export KEELSON_SESSION_ID=${envIdentity}`;
+  try {
+    let last = null;
+    if (fs.existsSync(process.env.CLAUDE_ENV_FILE)) {
+      for (const raw of fs.readFileSync(process.env.CLAUDE_ENV_FILE, 'utf8').split(/\r?\n/)) {
+        const t = raw.trim();
+        if (t.startsWith('export KEELSON_SESSION_ID=')) last = t;
+      }
+    }
+    if (last !== line) fs.appendFileSync(process.env.CLAUDE_ENV_FILE, line + '\n');
+  } catch {}
+}
+
+let session = null;
+if (sessionPath) {
+  session = readJson(sessionPath) || { schema: 1, change: null, createdAt: new Date().toISOString() };
+  session.updatedAt = new Date().toISOString();
+  session.source = 'claude-session-start';
+  writeJson(sessionPath, session);
+}
+
+const now = read(path.join(k, 'NOW.md')).trim();
+const roadmapNow = section(read(path.join(k, 'ROADMAP.md')), 'Now');
+const changesDir = path.join(k, '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) => {
+        const dir = path.join(changesDir, d.name);
+        const change = read(path.join(dir, 'change.md'));
+        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 tier = (change.match(/^tier:\s*(\w+)/m) || [])[1] || 'quick';
+        const status = (change.match(/^status:\s*([\w-]+)/m) || [])[1] || null;
+        const owner = (change.match(/^owner:\s*(.+)$/m) || [])[1] || null;
+        return { name: d.name, tier, status, owner, done, total };
+      })
+  : [];
+
+const focused = session?.change && active.some((c) => c.name === session.change) ? session.change : null;
+const ordered = focused ? [...active].sort((a, b) => (a.name === focused ? -1 : b.name === focused ? 1 : 0)) : active;
+const lines = ['[keelson] Canonical project facts/runtime live under .keelson/. Session focus is local and never marks a change complete.'];
+if (focused) lines.push(`Session focus: ${focused}`);
+else if (active.length === 1) lines.push(`Resume candidate: ${active[0].name} (bind with \`keelson focus --auto\` only if this request continues that work)`);
+else if (active.length > 1) lines.push(`Active changes: ${active.map((c) => c.name).join(', ')} (no session focus)`);
+if (roadmapNow && !/^…/.test(roadmapNow)) lines.push('', '--- ROADMAP.md · Now ---', clip(roadmapNow, 350));
+if (now) lines.push('', '--- NOW.md ---', clip(now, 650));
+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}` : ''}`);
+}
+process.stdout.write(lines.join('\n') + '\n');

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@zyaiting/keelson",
+  "version": "0.4.0",
+  "description": "Local, verifiable check records and durable decisions for AI-assisted code changes.",
+  "type": "module",
+  "bin": {
+    "keelson": "bin/keelson.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "hooks",
+    "registry",
+    "README.md",
+    "README_CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "node scripts/check-syntax.js",
+    "validate": "node bin/keelson.js validate",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "opencode",
+    "gemini-cli",
+    "kiro",
+    "codebuddy",
+    "pi-agent",
+    "agent-skills",
+    "spec-driven",
+    "workflow",
+    "session",
+    "verification"
+  ],
+  "author": "Atingaii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atingaii/keelson.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Atingaii/keelson/issues"
+  },
+  "homepage": "https://github.com/Atingaii/keelson#readme",
+  "devDependencies": {
+    "fast-check": "^4.10.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}