@rowan-hiro/inkan 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hiro
+
+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,354 @@
+# Inkan
+
+[简体中文](README.zh.md)
+
+**Agents make promises. Inkan keeps the receipts.**
+
+*Seal what the work is meant to deliver. Then check that what landed is what was sealed.*
+
+Inkan is a small, zero-dependency CLI for repositories where coding agents
+do real work. It keeps a trustworthy record of what each piece of work was
+meant to deliver, how that intent changed along the way, and what was
+declared when it closed. It then binds each landing commit to that record,
+so anyone, human or agent, can ask later whether the commit is faithful to
+the promise.
+
+It is also a working prototype of a larger idea: one record that follows an
+agent's work through its whole lifecycle, from fixed intent to audited
+commit, and is never rewritten along the way.
+
+## The problem
+
+Long agent sessions lose the plot. Context gets compacted, a fresh session
+picks up a half-finished task, and the task gets quietly reinterpreted:
+scope narrows, a criterion is forgotten, A becomes B, and the final message
+still says "done". Tests do not catch this. Tests tell you the code works.
+They do not tell you it is the code you asked for.
+
+The usual answer is more checking: more tests, more gates, re-verification
+on every look at the log. That makes an agent re-check its own past work
+every time it re-reads history, and the loop never ends. Inkan takes the
+other route. It records what was declared and when, treats the record as
+fact, and leaves judging the result to the repository's own tests.
+
+## Three questions
+
+Inkan answers exactly three questions about a piece of work, and it refuses
+to grow beyond them.
+
+| Question | How Inkan answers it |
+|---|---|
+| Is the stored outcome still what was sealed? | One append-only file per outcome. A contract hash over the sealed text, its criteria, and every amendment. `inkan status` prints the seal verbatim with its hash. |
+| Is what got committed the sealed outcome? | Closing records the hash of the working tree. The landing commit carries an `Inkan-Outcome: <id>` trailer. `inkan check <commit>` compares trailer, recorded hash, and recorded tree against the commit itself. |
+| Was the outcome swapped mid-way without authorization? | The headline never changes. Criteria change only through `inkan amend --reason`. Closing requires a disposition for every live criterion. An outcome that was never closed stays visibly open; nothing closes it on anyone's behalf. |
+
+## Quick start
+
+Requires Node.js 22 or newer and git.
+
+```sh
+npm install --global @rowan-hiro/inkan
+```
+
+This installs `inkan` and its alias `ink`. They accept identical arguments.
+
+**1. Initialise the repository.**
+
+```sh
+inkan init
+```
+
+This writes a managed protocol block into `AGENTS.md` and creates `.inkan/`.
+Commit both; they are part of the code from here on. Add `--claude` to also
+link `CLAUDE.md` to `AGENTS.md`, so Claude Code reads the same policy from
+the same file.
+
+**2. Seal the outcome before touching code.**
+
+```sh
+inkan begin "Ship account recovery" \
+  --accept "expired links are rejected" \
+  --accept "a valid link resets the password"
+```
+
+```
+2026-09-03-0621-82qz
+```
+
+**3. When scope changes, amend. Never reinterpret.**
+
+```sh
+inkan amend --reason "Security review asked for rate limiting" \
+  "Rate-limit recovery requests per account" \
+  --accept "more than five requests per hour are rejected"
+```
+
+The original text stays. The amendment, its reason, and the new criterion
+are appended, and the contract hash moves with them.
+
+**4. Close with a disposition for every criterion.**
+
+```sh
+inkan end --met 1 --met 2 --unmet 3 --note "Rate limiting deferred to the next sprint"
+```
+
+```
+2026-09-03-0621-82qz partial
+Inkan-Outcome: 2026-09-03-0621-82qz
+```
+
+Status is derived, not chosen: every criterion met is `completed`, any
+unmet is `partial`. A truthful `partial` is a first-class result, and it is
+what an agent reports instead of stretching the definition of done.
+
+**5. Land it with the trailer.**
+
+```sh
+git commit -m "$(printf 'feat: account recovery\n\nInkan-Outcome: 2026-09-03-0621-82qz\n')"
+```
+
+The trailer goes in the last paragraph of the message, next to any other
+trailers such as `Co-Authored-By`, with no blank line between them. Git
+reads trailers only from that final paragraph; a trailer set apart by a
+blank line is silently not a trailer.
+
+**6. Ask, any time later, whether the commit kept its promise.**
+
+```sh
+inkan check HEAD
+```
+
+```
+b751a39  Inkan-Outcome: 2026-09-03-0621-82qz
+  outcome: present, closed (partial)
+  hash: matches refold
+  tree: matches commit tree
+consistent
+```
+
+## What a swap looks like
+
+Suppose the code is changed after the outcome closed and committed under
+the same trailer. The recorded tree no longer matches the commit:
+
+```
+c7f3a54  Inkan-Outcome: 2026-09-03-0621-82qz
+  outcome: present, closed (partial)
+  hash: matches refold
+  tree: differs from commit tree
+mismatch
+a mismatch is a fact about this commit; it is recorded, not repaired
+```
+
+Exit codes are 0 for consistent, 1 for mismatch, and 2 when the commit
+carries no `Inkan-Outcome` trailer at all. Nothing is repaired and nothing
+is blocked. `check` is a report about the past, which is exactly why it can
+run in a review or a CI job without turning into a gate.
+
+## After context loss
+
+A new session, a new day, a compacted context: instead of guessing what was
+in progress, ask.
+
+```sh
+inkan status
+inkan log -n 3
+```
+
+```
+[2026-09-03-0621-82qz] open
+  sealed: 2026-09-03T06:21:06.511Z
+  hash: 9850337661df733ec923efc25bf9fdcb85ce30a3bb4cb3c07d7c84dd4fcaff56
+  outcome: Ship account recovery
+  1. expired links are rejected
+  2. a valid link resets the password
+  3. more than five requests per hour are rejected
+  amend 2026-09-03T06:21:06.555Z: Security review asked for rate limiting
+    Rate-limit recovery requests per account
+```
+
+An open outcome that is your work is the task at hand: continue it, or close
+it with a note. One that is not your work belongs to another session: leave
+it alone, tell the person it is there, and ask whether your work should run
+in its own git worktree before beginning beside it. `log` prints one line
+per outcome, newest first, so re-anchoring costs a few lines of context, not
+a re-read of the history:
+
+```
+2026-09-03-0621-q51x  completed  Ship account recovery, second pass  (1/1 met)
+2026-09-03-0621-82qz  partial  Ship account recovery  (2/3 met)
+```
+
+## What Inkan refuses to do
+
+These are the product, not its limitations.
+
+- **It never runs anything.** No tests, no builds, no shell commands. The
+  only child process Inkan ever spawns is git, with a fixed argument list.
+  Whether the work is correct is the repository's job.
+- **It never gates.** Nothing in Inkan runs before or during `git commit`,
+  and `init` installs no hooks. `check` and `doctor` report on commits and
+  files that already exist.
+- **Closed is final.** There is no stale state, no invalidation, and no
+  notion that a closed outcome needs to be redone. Reviewing the log is
+  reading, not re-checking. If a past declaration now looks wrong, that is a
+  new outcome with its own seal.
+- **It never closes an outcome on anyone's behalf.** Several outcomes can be
+  open at once, one per session or branch. `begin` names the others and
+  leaves them alone. An outcome that was never closed is an honest record of
+  exactly that; why it stayed open is a question for a person to investigate,
+  not a judgment for an agent to make. Closing for the sake of closing would
+  only fill the log with junk records.
+- **The scenario is never rewritten.** An agent may challenge a decision when
+  circumstances change, by amendment or by a new decision record. It never
+  edits the text that records what was known and decided at the time.
+- **No moving parts.** No server, no database, no index, no lock, no sidecar
+  file, no environment variable. Everything is plain text under `.inkan/`,
+  committed with the code, and merged by ordinary git.
+
+## Built for agents
+
+`inkan init` writes a generated protocol block into `AGENTS.md`, the file
+coding agents already read. Five rules: seal before durable changes; the
+seal is a fact; close with dispositions, then commit with the trailer in the
+last paragraph of the message; re-anchor with `inkan status` after context
+loss and leave other sessions' outcomes alone; closed outcomes are final.
+The block carries a protocol number. `init`
+upgrades a block it generated under an earlier protocol in place and refuses
+to overwrite a block that was edited by hand, so the policy lives in exactly
+one place. `--lang <tag>` sets the language agents should write outcome
+prose in. `inkan init --claude` also creates `CLAUDE.md` as a symlink to
+`AGENTS.md`: Claude Code reads its own file name, and there is still one
+policy, not a copy.
+
+For agents that support skill files, the bundled `use-inkan` skill helps an
+agent locate Inkan and re-anchor. It only points at `AGENTS.md`; it does not
+restate or extend the protocol.
+
+```sh
+inkan skill install                 # .agents/skills/use-inkan, read by most agents
+inkan skill install --claude        # .claude/skills/use-inkan, for Claude Code
+inkan skill install --target <dir>  # anywhere else, including a global directory
+```
+
+## Decisions travel with the code
+
+Design choices are recorded as MADR (Markdown Architectural Decision
+Records) under `.inkan/decisions/`, one numbered `NNNN-slug.md` file each.
+`inkan decision add` writes one. Its Context and Decision Outcome sections
+record the scenario and the choice at the time, and they are never edited
+afterwards. To challenge a decision, `inkan decision update <id> --status
+<status> --reason "<text>"` appends a dated history entry, or a new record
+supersedes the old one.
+
+An outcome names the decisions it is bound by with `--decision <id>` on
+`begin` or `amend`. They are constraints on the work, never a gate on
+closing it.
+
+Inkan's own design is recorded this way, from the boundary in `0001`
+onward. There is no separate design document; `inkan decision list` prints
+the index.
+
+## A prototype for the whole lifecycle
+
+Inkan is also a working prototype of something larger: managing an agent's
+work across its whole lifecycle, from the moment intent is fixed to the
+moment a commit is audited, with one record that every stage writes to and
+no stage rewrites.
+
+| Stage | What is recorded | Command |
+|---|---|---|
+| Intent | What will be delivered and how it will be judged | `begin` |
+| Change | How the intent moved, and why | `amend --reason` |
+| Constraint | The decisions the work is bound by | `decision add`, `--decision` |
+| Close | A disposition per criterion and a derived, truthful status | `end` |
+| Delivery | The commit that landed the work, bound to the seal | `Inkan-Outcome` trailer |
+| Audit | Whether the commit and the record still agree | `check`, `doctor` |
+| Resume | Where a fresh session picks up | `status`, `log` |
+
+Inkan is built this way itself. Every commit in its repository after the
+first carries an `Inkan-Outcome` trailer, each milestone was sealed and
+closed as an outcome, and its design decisions live in `.inkan/decisions/`.
+The record is deliberately small. What the prototype tests is whether a
+lifecycle can be managed by a log of facts alone, with no runner and no
+gate in the loop.
+
+## Command reference
+
+| Command | Effect | Refuses when |
+|---|---|---|
+| `inkan init [--lang <tag>] [--claude]` | Writes or upgrades the managed block in `AGENTS.md`; creates `.inkan/`. `--claude` also links `CLAUDE.md` to `AGENTS.md`. | The block was hand-edited. A `CLAUDE.md` exists that is not that symlink. |
+| `inkan begin "<outcome>" [--accept <text>]... [--decision <id>]... [--lane <tag>]` | Seals a new outcome; prints its id. Any other open outcome is named in a notice on stderr and left untouched. | Never. |
+| `inkan amend --reason <text> [<addition>] [--accept <text>]... [--withdraw <n>]... [--decision <id>]... [<id>]` | Appends an amendment; prints the new contract hash. | No reason. No open outcome. Ambiguous open outcome without `<id>`. |
+| `inkan end [<id>] [--met <n>]... [--unmet <n>]... [-s abandoned] --note <text>` | Records dispositions and closes. Status is derived: all met is `completed`, any unmet is `partial`. Prints the commit trailer line. | A live criterion has no disposition, unless closing with `-s abandoned`. No note. |
+| `inkan status` | Prints every open outcome verbatim: sealed time, hash, lane, criteria with indexes, amendments with reasons, linked decisions. | Never. |
+| `inkan log [-n N] [--since <date>] [--grep <regex>] [--status <s>] [--decision <id>] [--lane <tag>] [<id>]` | One line per outcome, newest first, default 20. `<id>` prints one outcome in full, including dispositions, note, and recorded tree. Filters combine. | Never. |
+| `inkan check [<commit>]` | Read-only. Reads `Inkan-Outcome` trailers, loads each named outcome from the commit's own tree, refolds it, and reports trailer, closure, hash, and tree. Exit 0 consistent, 1 mismatch, 2 no trailer. | Never blocks anything. |
+| `inkan doctor` | Read-only. Folds every outcome and parses every decision; reports corrupt files, id mismatches, duplicate decision ids, and dangling decision links. Exit 0 clean, 1 problems. | Never. |
+| `inkan decision add "<title>" --context <text> --decision <text> [--driver <text>]... [--option <text>]... [--consequence <text>]... [-s <status>]` | Writes a numbered MADR file; prints its path. | Missing required sections. |
+| `inkan decision update <id> --status <status> --reason <text>` | Appends a dated history entry and sets the new status. Names the open outcome when there is one. Never edits Context or Decision Outcome. | Unknown id or status. |
+| `inkan decision list [-s <status>]` / `inkan decision show <id>` | Read-only. `show` accepts `2`, `02`, or `0002`. | Never. |
+| `inkan skill install [--claude \| --target <dir>]` | Copies the bundled skill to `.agents/skills/use-inkan/` under the repository root, to `.claude/skills/use-inkan/` with `--claude`, or to `<dir>/use-inkan/`; prints the destination. | The destination exists and differs from the bundled skill. `--claude` with `--target`. |
+
+Decision statuses are `proposed`, `accepted`, `rejected`, `deferred`,
+`deprecated`, and `superseded`.
+
+## How it works
+
+```
+.inkan/
+  outcomes/<id>.jsonl      one append-only file per outcome
+  decisions/NNNN-slug.md   MADR records
+```
+
+An outcome id such as `2026-09-03-1432-k7m2` is the UTC date and minute the
+outcome was begun plus four random characters, so ids sort chronologically
+and two branches essentially never collide. Each outcome file holds a
+`begin` event, any `amend` events, and at most one `end` event. An open
+outcome is simply a file with no `end` yet.
+
+The contract hash is a SHA-256 over the outcome text, its criteria with
+their withdrawn flags, the linked decisions, and every amendment's reason
+and addition. `end` records it, together with the git tree hash of the
+working tree with `.inkan/outcomes` excluded, so the log never perturbs the
+hash of the work it describes. `check` refolds the outcome as stored in the
+commit and compares both.
+
+Because each outcome is its own file, two branches never touch the same
+file and an ordinary merge brings them together. It also keeps review cheap
+without a cache: an unfiltered `log` reads only as many files as it prints, and the bundled
+benchmark (`npm run bench`) seeds ten thousand closed outcomes and holds
+`log -n 3` under 50 ms, `log --grep` under 1 s, and `doctor` under 2 s.
+
+## Status
+
+Inkan 0.1.0 is the first release, rebuilt from scratch as the successor to
+DriftSeal. Deliberately not in this release: an importer for DriftSeal
+history and an MCP server. Those are adapters and can follow without
+changing the record format. The only host-specific convenience is
+`--claude` on `init` and `skill install`; every other host reads
+`AGENTS.md` and `.agents/skills` as they are. Lanes exist only as an
+optional filing tag on `begin` and a filter on `log`.
+
+## Releasing
+
+Every push to `main` and every pull request runs the test suite on Node 22,
+24, and 26, the history benchmark, and a package smoke on Linux, macOS, and
+Windows that packs the tarball, installs it, and drives the installed
+`inkan` through a full outcome (`npm run test:package`).
+
+A release is a GitHub Release whose tag is `v` plus the version in
+`package.json`. Publishing the release runs the publish workflow, which
+checks that the tag and the version agree, runs the tests and the package
+smoke again, and publishes to npm with trusted publishing (OIDC). No npm
+token is stored anywhere. The one-time setup is on npmjs.com, in the
+package's settings: add a trusted publisher of type GitHub Actions with
+owner `rowan-hiro`, repository `inkan`, and workflow `publish.yml`. If
+npm does not let a trusted publisher be added to a package that has never
+been published, publish the first release by hand from a checkout of the
+tag with `npm publish --access public`; every release after that goes
+through the workflow.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,239 @@
+# Inkan
+
+[English](README.md) | 简体中文
+
+**Agent 许下承诺，Inkan 留下凭据。**
+
+*先把工作真正要交付的结果 seal 下来，再核对最终落地的内容有没有兑现承诺。*
+
+Inkan 是一款小巧、零依赖的 CLI，专为让 coding agent 真正参与开发的代码仓库而生。它会可靠地记录每项工作原本要交付什么、意图在过程中如何变化，以及工作结束时作出了怎样的声明；再把最终落地的每个 commit 与这份记录绑定。于是，无论人还是 agent，日后都能清楚回答：这个 commit，真的兑现了当初的承诺吗？
+
+它同时也是一个更宏大构想的可运行原型：用一份贯穿 agent 工作全生命周期的记录，从意图确定一路走到 commit 审计，并且全程只追加、不改写。
+
+## 问题所在
+
+漫长的 agent session 很容易偏离目标。Context 被压缩后，新 session 接手一项做到一半的任务，任务却在不知不觉间被重新解释：范围缩小了，一条验收标准被忘了，A 变成了 B，最终消息却依然写着“完成”。测试发现不了这种问题。测试能告诉你代码是否可用，却不能告诉你，这是不是你最初要求的那份代码。
+
+常见的解决办法是不断增加检查：更多测试、更多 gate，每次查看日志都重新验证一遍。这会让 agent 每次重读历史时，都再次检查自己过去的工作，最终陷入没有尽头的循环。Inkan 选择了另一条路：如实记录当时声明了什么、声明发生在何时，把记录本身视为事实，并把结果是否正确的判断交还给仓库自己的测试体系。
+
+## 三个问题
+
+对于一项工作，Inkan 只回答三个问题，并且刻意不越界。
+
+| 问题 | Inkan 如何回答 |
+|---|---|
+| 保存下来的 outcome 还是当初 seal 的那一个吗？ | 每个 outcome 都有自己的 append-only 文件。系统会根据 seal 的文本、验收标准和历次 amendment 计算 contract hash。`inkan status` 会逐字打印 seal 及其 hash。 |
+| commit 中落地的内容就是 seal 的 outcome 吗？ | 关闭 outcome 时会记录 working tree 的 hash。落地 commit 带有 `Inkan-Outcome: <id>` trailer。`inkan check <commit>` 会把 trailer、记录的 hash 和记录的 tree 与 commit 本身逐一比对。 |
+| outcome 是否在中途被擅自调换？ | 标题永远不变。验收标准只能通过 `inkan amend --reason` 修改。关闭时，每一条仍生效的标准都必须给出 disposition。从未关闭的 outcome 会一直明确显示为 open；Inkan 不会替任何人关闭它。 |
+
+## 快速开始
+
+需要 Node.js 22 或更高版本，以及 git。
+
+```sh
+npm install --global @rowan-hiro/inkan
+```
+
+这会安装 `inkan` 及其别名 `ink`，两者接受完全相同的参数。
+
+**1. 初始化仓库。**
+
+```sh
+inkan init
+```
+
+这条命令会把一段由 Inkan 管理的 protocol 写入 `AGENTS.md`，并创建 `.inkan/`。请把两者一并 commit；从这一刻开始，它们就是代码的一部分。加上 `--claude`，还会把 `CLAUDE.md` 软链到 `AGENTS.md`，让 Claude Code 从同一个文件读取同一份 policy。
+
+**2. 在动手修改代码之前 seal outcome。**
+
+```sh
+inkan begin "Ship account recovery" \
+  --accept "expired links are rejected" \
+  --accept "a valid link resets the password"
+```
+
+```
+2026-09-03-0621-82qz
+```
+
+**3. 范围发生变化时，明确 amend，绝不重新解释。**
+
+```sh
+inkan amend --reason "Security review asked for rate limiting" \
+  "Rate-limit recovery requests per account" \
+  --accept "more than five requests per hour are rejected"
+```
+
+原始文本会完整保留。amendment、变更原因和新增标准会被追加到记录中，contract hash 也会随之更新。
+
+**4. 关闭时，为每一条标准给出 disposition。**
+
+```sh
+inkan end --met 1 --met 2 --unmet 3 --note "Rate limiting deferred to the next sprint"
+```
+
+```
+2026-09-03-0621-82qz partial
+Inkan-Outcome: 2026-09-03-0621-82qz
+```
+
+状态由事实推导，而不是人为选择：所有标准均达成时为 `completed`，只要有一项未达成就是 `partial`。如实记录的 `partial` 是一种完整、正式的结果；agent 应当报告它，而不是为了声称“完成”而拉伸 done 的定义。
+
+**5. 带上 trailer，让工作落地。**
+
+```sh
+git commit -m "$(printf 'feat: account recovery\n\nInkan-Outcome: 2026-09-03-0621-82qz\n')"
+```
+
+trailer 必须放在 commit message 的最后一个段落，并与 `Co-Authored-By` 等其他 trailer 相邻，中间不能有空行。Git 只会把最后一个段落中的内容识别为 trailer；用空行单独隔开的 trailer，不会报错，却也不会被识别。
+
+**6. 日后随时检查：这个 commit 是否兑现了承诺？**
+
+```sh
+inkan check HEAD
+```
+
+```
+b751a39  Inkan-Outcome: 2026-09-03-0621-82qz
+  outcome: present, closed (partial)
+  hash: matches refold
+  tree: matches commit tree
+consistent
+```
+
+## 偷换 outcome 会是什么样
+
+假设 outcome 关闭后，代码又被修改，却仍使用同一个 trailer 提交。此时，记录中的 tree 将不再匹配这个 commit：
+
+```
+c7f3a54  Inkan-Outcome: 2026-09-03-0621-82qz
+  outcome: present, closed (partial)
+  hash: matches refold
+  tree: differs from commit tree
+mismatch
+a mismatch is a fact about this commit; it is recorded, not repaired
+```
+
+一致时退出码为 0，不匹配时为 1；如果 commit 完全没有 `Inkan-Outcome` trailer，则为 2。Inkan 不会修复任何内容，也不会阻塞任何操作。`check` 只是对过去作出报告——也正因为如此，它可以安心地运行在 code review 或 CI job 中，而不会摇身变成一道 gate。
+
+## Context 丢失之后
+
+新的 session、新的一天，或一次 context compaction 之后，不要靠猜来判断正在做什么，直接查询记录。
+
+```sh
+inkan status
+inkan log -n 3
+```
+
+```
+[2026-09-03-0621-82qz] open
+  sealed: 2026-09-03T06:21:06.511Z
+  hash: 9850337661df733ec923efc25bf9fdcb85ce30a3bb4cb3c07d7c84dd4fcaff56
+  outcome: Ship account recovery
+  1. expired links are rejected
+  2. a valid link resets the password
+  3. more than five requests per hour are rejected
+  amend 2026-09-03T06:21:06.555Z: Security review asked for rate limiting
+    Rate-limit recovery requests per account
+```
+
+如果一个 open outcome 属于你的工作，它就是当前任务：继续完成它，或者写明 note 后关闭。如果它不属于你，那就是另一个 session 的工作：不要动它；告诉负责人这里已有一项 open outcome，并在与它并行开始新工作前，询问是否应该使用独立的 git worktree。`log` 按从新到旧的顺序，每个 outcome 只打印一行。因此，重新锚定上下文只需要寥寥几行，而不必重读全部历史：
+
+```
+2026-09-03-0621-q51x  completed  Ship account recovery, second pass  (1/1 met)
+2026-09-03-0621-82qz  partial  Ship account recovery  (2/3 met)
+```
+
+## Inkan 坚决不做什么
+
+这些不是功能缺失，而是产品本身的边界。
+
+- **它绝不运行任何任务。** 不运行测试、build 或 shell command。Inkan 唯一会启动的 child process 是 git，而且参数列表固定。工作是否正确，应由仓库自己判断。
+- **它绝不充当 gate。** `git commit` 之前或期间不会运行任何 Inkan 操作，`init` 也不会安装 hook。`check` 和 `doctor` 只报告已经存在的 commit 和文件。
+- **关闭即最终状态。** 没有 stale state，没有 invalidation，也不存在已经关闭的 outcome 还需要重做的概念。查看日志就是阅读，而不是重新检查。如果过去的声明如今看来有误，那应当成为一项拥有独立 seal 的新 outcome。
+- **它绝不代替别人关闭 outcome。** 多个 outcome 可以同时 open，每个 session 或 branch 各自拥有一个。`begin` 会指出其他 outcome 的存在，但不会碰它们。从未关闭的 outcome，就是“它确实没有关闭”的诚实记录；为何一直 open，应由人来调查，而不是由 agent 擅自判断。仅仅为了关闭而关闭，只会让日志充斥无意义的记录。
+- **它绝不改写当时的场景。** 情况变化时，agent 可以通过 amendment 或新的 decision record 对既有决定提出挑战，但绝不会修改那段记录了当时所知信息与所作决定的文本。
+- **没有额外运转部件。** 没有 server、database、index、lock、sidecar file 或 environment variable。一切都是 `.inkan/` 下的纯文本，随代码一同 commit，并通过普通 git 操作完成 merge。
+
+## 为 agent 而生
+
+`inkan init` 会把生成好的 protocol block 写进 coding agent 本来就会读取的 `AGENTS.md`。其中只有五条规则：在 durable change 之前 seal；seal 是事实；先逐项 disposition 并关闭，再把 trailer 放在 commit message 的最后一段完成提交；context 丢失后用 `inkan status` 重新锚定，同时不碰其他 session 的 outcome；关闭即最终状态。
+
+protocol block 带有版本号。`init` 会原地升级由旧版 protocol 生成的 block，但拒绝覆盖经过手工编辑的 block，确保 policy 始终只有一个权威来源。`--lang <tag>` 用来设置 agent 撰写 outcome 文本时应使用的语言。`inkan init --claude` 还会把 `CLAUDE.md` 创建为指向 `AGENTS.md` 的 symlink：Claude Code 读的是自己认识的文件名，而 policy 依然只有一份，不是副本。
+
+对于支持 skill 文件的 agent，Inkan 内置的 `use-inkan` skill 可以帮助 agent 定位 Inkan 并重新锚定。它只会指向 `AGENTS.md`，不会复述或扩展 protocol。
+
+```sh
+inkan skill install                 # .agents/skills/use-inkan，大多数 agent 读取的路径
+inkan skill install --claude        # .claude/skills/use-inkan，给 Claude Code
+inkan skill install --target <dir>  # 其他任何位置，包括全局目录
+```
+
+## 让决策与代码同行
+
+设计选择以 MADR（Markdown Architectural Decision Records）的形式保存在 `.inkan/decisions/` 下，每条记录对应一个编号为 `NNNN-slug.md` 的文件。`inkan decision add` 用于创建记录。其中的 Context 和 Decision Outcome 部分会记下当时的场景与选择，之后永不改写。
+
+如果要挑战一项决定，可运行 `inkan decision update <id> --status <status> --reason "<text>"`，追加一条带日期的历史记录；也可以创建一条新记录来 supersede 旧记录。
+
+outcome 可以在 `begin` 或 `amend` 时通过 `--decision <id>` 指明自己受哪些 decision 约束。这些 decision 是工作的约束条件，但绝不是关闭工作的 gate。
+
+Inkan 自己的设计也用同样的方式记录，从 `0001` 中划定的边界一路延续至今。仓库没有单独的设计文档；`inkan decision list` 就是它的索引。
+
+## 面向完整生命周期的原型
+
+Inkan 还是一个更大构想的可运行原型：管理 agent 工作的完整生命周期，从意图确定的那一刻，到 commit 接受审计的那一刻。整个过程中，每个阶段都向同一份记录写入事实，没有任何阶段会改写过去。
+
+| 阶段 | 记录什么 | 命令 |
+|---|---|---|
+| 意图 | 要交付什么，以及如何判断是否达成 | `begin` |
+| 变更 | 意图如何变化，以及为什么变化 | `amend --reason` |
+| 约束 | 当前工作受哪些 decision 约束 | `decision add`、`--decision` |
+| 关闭 | 每条标准的 disposition，以及由此推导出的诚实状态 | `end` |
+| 交付 | 真正落地的 commit，并与 seal 绑定 | `Inkan-Outcome` trailer |
+| 审计 | commit 与记录是否仍然一致 | `check`、`doctor` |
+| 恢复 | 新 session 从哪里接手 | `status`、`log` |
+
+Inkan 本身就是这样构建的。仓库从第二个 commit 开始，每个 commit 都带有 `Inkan-Outcome` trailer；每个 milestone 都先作为 outcome 被 seal，随后关闭；所有设计决定都保存在 `.inkan/decisions/` 中。
+
+这份记录被刻意设计得很小。这个原型真正要验证的是：不在流程里加入 runner，也不设置 gate，仅凭一份只记录事实的日志，能否管理完整的生命周期。
+
+## 命令参考
+
+| 命令 | 作用 | 何时拒绝执行 |
+|---|---|---|
+| `inkan init [--lang <tag>] [--claude]` | 写入或升级 `AGENTS.md` 中由 Inkan 管理的 block；创建 `.inkan/`。`--claude` 还会把 `CLAUDE.md` 软链到 `AGENTS.md`。 | block 曾被手工编辑；已存在一个不是该 symlink 的 `CLAUDE.md`。 |
+| `inkan begin "<outcome>" [--accept <text>]... [--decision <id>]... [--lane <tag>]` | Seal 一个新 outcome，并打印其 id。其他 open outcome 会在 stderr 的 notice 中被点名，但不会受到任何改动。 | 永不拒绝。 |
+| `inkan amend --reason <text> [<addition>] [--accept <text>]... [--withdraw <n>]... [--decision <id>]... [<id>]` | 追加 amendment，并打印新的 contract hash。 | 没有 reason；没有 open outcome；存在多个 open outcome，却没有用 `<id>` 明确指定目标。 |
+| `inkan end [<id>] [--met <n>]... [--unmet <n>]... [-s abandoned] --note <text>` | 记录 disposition 并关闭 outcome。状态由结果推导：全部 met 为 `completed`，任一 unmet 为 `partial`。打印 commit trailer 行。 | 仍生效的标准缺少 disposition（以 `-s abandoned` 关闭时除外）；没有 note。 |
+| `inkan status` | 逐字打印所有 open outcome：seal 时间、hash、lane、带编号的标准、附 reason 的 amendment，以及关联的 decision。 | 永不拒绝。 |
+| `inkan log [-n N] [--since <date>] [--grep <regex>] [--status <s>] [--decision <id>] [--lane <tag>] [<id>]` | 每个 outcome 打印一行，最新的在前，默认 20 条。`<id>` 会完整打印一项 outcome，包括 disposition、note 和记录的 tree。filter 可以组合。 | 永不拒绝。 |
+| `inkan check [<commit>]` | 只读。从 commit 自身的 tree 中读取 `Inkan-Outcome` trailer 和对应 outcome，重新 fold 后报告 trailer、关闭状态、hash 与 tree。退出码：一致为 0，不匹配为 1，没有 trailer 为 2。 | 不会阻塞任何操作。 |
+| `inkan doctor` | 只读。Fold 所有 outcome 并解析所有 decision；报告损坏文件、id 不匹配、重复的 decision id，以及失效的 decision link。退出码：正常为 0，发现问题为 1。 | 永不拒绝。 |
+| `inkan decision add "<title>" --context <text> --decision <text> [--driver <text>]... [--option <text>]... [--consequence <text>]... [-s <status>]` | 写入一个带编号的 MADR 文件，并打印其路径。 | 缺少必要 section。 |
+| `inkan decision update <id> --status <status> --reason <text>` | 追加一条带日期的历史记录，并设置新状态。有 open outcome 时会指出它的名称。永不编辑 Context 或 Decision Outcome。 | id 或 status 未知。 |
+| `inkan decision list [-s <status>]` / `inkan decision show <id>` | 只读。`show` 接受 `2`、`02` 或 `0002`。 | 永不拒绝。 |
+| `inkan skill install [--claude \| --target <dir>]` | 把内置 skill 复制到仓库根目录下的 `.agents/skills/use-inkan/`；加 `--claude` 时复制到 `.claude/skills/use-inkan/`；指定 `--target` 时复制到 `<dir>/use-inkan/`。打印目标路径。 | 目标已存在，且与内置 skill 不同；`--claude` 与 `--target` 同时给出。 |
+
+Decision status 包括 `proposed`、`accepted`、`rejected`、`deferred`、`deprecated` 和 `superseded`。
+
+## 工作原理
+
+```
+.inkan/
+  outcomes/<id>.jsonl      每个 outcome 一个 append-only 文件
+  decisions/NNNN-slug.md   MADR 记录
+```
+
+`2026-09-03-1432-k7m2` 这样的 outcome id，由 outcome 开始时的 UTC 日期与分钟，加上四个随机字符组成。因此 id 可以按时间排序，两个 branch 也几乎不可能发生冲突。每个 outcome 文件包含一个 `begin` event、任意数量的 `amend` event，以及最多一个 `end` event。所谓 open outcome，就是一个尚无 `end` 的文件。
+
+contract hash 是一个 SHA-256，计算范围包括 outcome 文本、带 withdrawn 标记的验收标准、关联的 decision，以及每次 amendment 的 reason 和 addition。`end` 会记录这个 hash，同时记录 working tree 的 git tree hash；计算时会排除 `.inkan/outcomes`，因此日志本身不会扰动它所描述的工作 hash。`check` 会重新 fold commit 中保存的 outcome，并同时比较两者。
+
+由于每个 outcome 都有独立文件，两个 branch 永远不会改动同一个 outcome 文件，普通 merge 就能把记录自然汇合。这种设计不需要 cache，也能让 review 保持轻快：不带 filter 的 `log` 只读取实际要打印的文件数；内置 benchmark（`npm run bench`）会生成一万个已关闭的 outcome，并将 `log -n 3` 控制在 50 ms 以内、`log --grep` 控制在 1 秒以内、`doctor` 控制在 2 秒以内。
+
+## 当前状态
+
+Inkan 0.1.0 是首个正式版本，也是 DriftSeal 继任者的一次从零重构。本版本有意没有加入 DriftSeal 历史记录 importer 和 MCP server。这些都属于 adapter，可以后续补上，而无需改变记录格式。唯一针对特定 host 的便利是 `init` 和 `skill install` 的 `--claude`；其他 host 直接读取 `AGENTS.md` 和 `.agents/skills`，无需任何适配。Lane 目前只作为 `begin` 时可选的归档 tag，以及 `log` 的 filter。
+
+## License
+
+MIT

package/bin/ink.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/bin/inkan.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rowan-hiro/inkan",
+  "version": "0.1.0",
+  "description": "Seal the authoritative outcome; keep a trustworthy record of the process.",
+  "type": "module",
+  "bin": {
+    "inkan": "bin/inkan.js",
+    "ink": "bin/ink.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "Hiro <rowan_hiro@proton.me>",
+  "homepage": "https://github.com/rowan-hiro/inkan#readme",
+  "bugs": {
+    "url": "https://github.com/rowan-hiro/inkan/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rowan-hiro/inkan.git"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "bench": "node bench/history.js",
+    "test:package": "node scripts/test-package.mjs"
+  },
+  "keywords": [
+    "inkan",
+    "agents",
+    "agentic-coding",
+    "outcome-log",
+    "decision-log",
+    "madr"
+  ]
+}