whynot-cli 0.0.0-stage → 0.1.0

package/AGENTS.snippet.md

@@ -0,0 +1,69 @@
+# whynot — paste this block into your AGENTS.md / CLAUDE.md
+
+The block below is the *behavioral* half of whynot. The MCP server gives the
+agent the ability to read and write decisions; this text is what makes it
+actually do so. Copy it verbatim.
+
+---
+
+## Recorded decisions (`.decisions/`)
+
+This repository keeps a record of settled decisions — especially approaches
+that were **tried and rejected** — in `.decisions/`.
+
+**At the start of a session**, call `decisions_check` with no arguments. You get
+a compact index (id, type, title, tags) of everything already settled. It is
+short by design — read it once.
+
+**Before proposing a technical approach**, call `decisions_check` with keywords
+for what you are about to suggest, and read the full entries that come back. If
+the topic is covered, do not re-propose the rejected option. You may propose it
+again only if you can point to concrete evidence that the stated `revisit_when`
+condition has now been met.
+
+Matching is keyword-based, so **query with the nouns the entry would use**, and
+try more than one phrasing before concluding nothing is recorded. An empty
+result means "nothing found", not "nothing decided".
+
+**When the user rejects one of your suggestions**, or when you discover that an
+approach does not work, call `decisions_record` with:
+- `title` — what was ruled out
+- `why` — the specific reason it failed (not "it didn't work"; say what broke)
+- `type: rejected`
+- `evidence` — a commit sha, PR number, or URL a human can check later
+- `revisit_when` — strongly preferred: the condition that would change the answer
+
+Every entry expires (90 days for a rejection by default) and then stops being
+shown to you. If a decision is genuinely permanent, say so to the user and let
+them decide — do not set a long TTL yourself to work around this.
+
+**When you are asked to plan or design**, call `decisions_stale` first and
+surface anything that needs re-confirmation. Do not silently follow a stale
+entry; ask. A stale entry is a question for the user, not an instruction.
+
+Never invent an entry, and never record something the user did not actually
+decide. A wrong entry is worse than a missing one, because it will be trusted
+for months.
+
+---
+
+## Registering the MCP server
+
+`decisions_check` / `decisions_record` / `decisions_stale` come from the whynot
+MCP server. Add it to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
+
+If your agent reads `AGENTS.md` but not MCP, the fallback still works: the
+entries are plain Markdown in `.decisions/`, so the agent can read and grep them
+directly. That is intentional — the format is the product, and it keeps working
+without the tool.

package/AGENTS.snippet.zh-CN.md

@@ -0,0 +1,60 @@
+# whynot —— 把这段粘进你的 AGENTS.md / CLAUDE.md
+
+下面这段是 whynot 的**行为部分**。MCP server 只是让 agent 有能力读写；真正让它
+主动去做的，是这段文字。请原样复制。
+
+---
+
+## 已记录的决策（`.decisions/`）
+
+这个仓库在 `.decisions/` 里记录已经定下来的决策——尤其是**试过并否决**的方案。
+
+**每次会话开始时**，不带参数调用 `decisions_check`。你会得到一个紧凑的索引
+（id、类型、标题、标签），里面是已经定下的所有事。它故意做得很短——读一遍就行。
+
+**在提出技术方案之前**，用描述你即将建议的关键词调用 `decisions_check`，然后把
+返回的完整条目读完。如果这个话题已经被覆盖，不要再提被否决的选项。除非你能
+指出明确证据说明 `revisit_when` 条件已经满足，否则不要重新提议。
+
+匹配是基于关键词的，所以**用条目里可能出现的名词去查**，并且在得出「没有记录」
+之前，换几种说法再试一次。返回空表示「没找到」，不表示「没定过」。
+
+**当用户否决了你的某个建议**，或者你发现某个方案行不通时，调用 `decisions_record`：
+
+- `title` —— 被否决的是什么
+- `why` —— 具体是什么失败了（不要写「它不工作」；说清楚哪里崩了）
+- `type: rejected`
+- `evidence` —— 一条 commit sha、PR 号，或者一个 URL，让人以后能核对
+- `revisit_when` —— 强烈建议填写：什么条件会改变这个结论
+
+每条记录都会过期（否决类默认 90 天），过期后就不再展示给你。如果某个决策确实
+永久有效，告诉用户，让他们决定——不要自己设一个超长 TTL 来绕过这个机制。
+
+**当你被要求做规划或设计时**，先调用 `decisions_stale`，把需要重新确认的东西
+摆出来。不要默默遵循一条过期条目；先问。**过期条目是给用户的问题，不是给你的
+指令。**
+
+永远不要编造条目，也不要把用户没有真正决定过的事记进去。一条错误的记录比没有
+记录更糟，因为它会被信任好几个月。
+
+---
+
+## 注册 MCP server
+
+`decisions_check` / `decisions_record` / `decisions_stale` 来自 whynot 的 MCP
+server。在你的 agent 的 MCP 配置里加上：
+
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
+
+如果你的 agent 读 `AGENTS.md` 但不用 MCP，降级方案依然成立：记录就是
+`.decisions/` 里的普通 Markdown，agent 可以直接读、直接 grep。这是刻意的设计
+——**格式本身就是产品**，所以没有工具它也能工作。

package/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing
+
+Thanks for looking. This project is small on purpose, and a few design
+decisions are not open for negotiation. Read this before opening a PR.
+
+## The four constraints
+
+These are the reason the tool exists. A PR that breaks one will be declined,
+even if it is well written and useful in isolation.
+
+1. **The data stays plain Markdown in git.** No database, no binary format, no
+   schema that requires the tool to read. If this project dies, users must be
+   able to `grep` their own files.
+
+2. **No vector store, no embeddings, no model call on the write path.**
+   Retrieval quality is not the bottleneck; auditability is. Vector stores and
+   LLM-extracted memories are the failure modes this project is a response to.
+
+3. **No daemon, no background process, no file watching.** The tool runs when
+   it is called. Background processes are how these tools become unreliable and
+   then abandoned.
+
+4. **No hosted service, no telemetry, no account.** Decisions about someone's
+   codebase are the most sensitive thing in their repository. They stay on the
+   user's machine.
+
+If you think one of these should change, open an issue and make the argument
+with evidence. The constraints are load-bearing, not aesthetic.
+
+## What is welcome
+
+- Bug fixes, especially cross-platform ones.
+- Better heuristics for `whynot audit`, with tests.
+- Documentation that is shorter or clearer than what it replaces.
+- Additional agent integrations that reuse the existing file format.
+- Reproductions of the validation experiments on other models. If a model
+  behaves differently from what `docs/validation.md` reports, that is a useful
+  finding — please share it.
+
+## What will be declined
+
+- Anything that makes the tool heavier without removing a reported problem.
+- New configuration surface. Every option is a thing someone has to understand.
+- "Make it work for teams" features that require a server.
+- PRs that rewrite the README into marketing copy.
+
+## Before you send a PR
+
+```bash
+node --test "test/*.test.js"
+```
+
+There are no dependencies to install. If a test fails on your machine but not
+in CI, that is a bug worth reporting — the project claims to work on Windows,
+macOS, and Linux.
+
+Keep commits focused. One change per PR. Explain *what problem it removes*, not
+what feature it adds.
+
+## Style
+
+- Plain language in docs. Short sentences. No superlatives.
+- Comments explain *why*, not *what*. If the code needs a comment to say what it
+  does, rename something instead.
+- No emoji in source files.
+- Chinese and English docs are kept in sync. If you change one, change both or
+  flag it in the PR.
+
+## Security and privacy
+
+Do not include personal paths, usernames, API keys, or the contents of anyone's
+`~/.codex` or `~/.claude` directory in a PR or an issue. `experiments/out/` is
+gitignored for this reason; keep it that way.
+
+If you find a leak, open an issue without pasting the leaked value.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stakenshake
+
+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

@@ -1,3 +1,247 @@
-# Temporary Holding Version
+# whynot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Record what you ruled out — and why — so your coding agent stops re-suggesting it.**
+
+Your agent starts every session from zero. The approach you rejected last week,
+it will propose again this week. Three months from now, you will not remember
+why you rejected it either.
+
+Memory tools record **what you did**. That is already in your code, your
+commits, and your pull requests. What exists nowhere is **why you did not do
+something** — and it lives only in your head, decaying.
+
+`whynot` is a folder of Markdown files in your repo, plus a thin MCP server.
+
+---
+
+## What we found
+
+Six experiments, three model families, mostly n=20 per cell. Full write-ups and
+scripts are in [`docs/`](docs/) and [`experiments/`](experiments/).
+
+### Age does not matter. Presence does
+
+A recorded decision is followed at the same rate whether it was written a month
+ago or seven years ago:
+
+| Age of the decision | Recommends the rejected option |
+|---|---|
+| none (baseline) | 100% |
+| 30 days | **0%** |
+| 1 year | **0%** |
+| 7 years | **0%** |
+| 7 years, expired and hidden | **100%** |
+
+Same decision text every time; only the `created` date changed. The model does
+not discount old records — it treats every record as current.
+
+Adding "this is old, be skeptical" to the prompt did not help. Hiding the
+expired entry did. That is why expiry is the core of this tool.
+
+### Recording a rejection changes the answer
+
+At n=20 across three families, a recorded rejection moved the recommendation by
+78–87 percentage points (Fisher p < 0.0001).
+
+### Two honest qualifications
+
+- **Not every model obeys equally.** With real code in context, one model
+  inferred the answer from the repository and ignored the record; another still
+  preferred the rejected option until the record stopped it.
+- **The stated reason matters more than the date.** When the record said "the
+  team did not know TypeScript", about one in five responses attacked that
+  premise and recommended TypeScript anyway. When it said "this project's
+  fields change constantly", obedience was total. A reason that names a
+  *condition* invites re-checking; a reason that states a *property* does not.
+
+### What is not tested
+
+**We have not measured whether this helps a developer in real use.** Every
+experiment here is a controlled, single-turn task. The number that matters —
+how often an agent re-proposes something you already rejected, over weeks of
+real work — has not been measured, and this project does not claim it.
+
+The claim we do make: *the mechanism works under test, and the scripts are here
+so you can check.*
+
+---
+
+## Install
+
+```bash
+npx whynot-cli init
+```
+
+Then paste the block from [`AGENTS.snippet.md`](AGENTS.snippet.md) into your
+`AGENTS.md` or `CLAUDE.md`, and register the MCP server.
+
+Node 20+. Nothing else. No global install, no account, no telemetry.
+
+### Register the MCP server
+
+The same shape works for Claude Code, Claude Desktop, Cursor, and most other
+MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Use
+
+```bash
+npx whynot-cli audit              # scan your existing rules for ones that will never expire
+npx whynot-cli init               # create .decisions/
+npx whynot-cli add --title "..." --why "..."
+npx whynot-cli check redis        # is this already settled?
+npx whynot-cli stale              # what needs a human decision
+npx whynot-cli renew 0001         # it still holds — extend it
+npx whynot-cli retire 0002        # it no longer holds — archive it
+```
+
+Most of the time you will not run these by hand. The agent calls
+`decisions_record` when it discovers something does not work, and
+`decisions_check` before proposing an approach.
+
+### Start with `audit`
+
+`audit` is read-only. It scans `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`,
+`.cursor/rules/*`, and `.github/copilot-instructions.md` for absolute rules
+that state no condition — the kind that get obeyed forever.
+
+```
+Scanned 2 agent config files:
+  AGENTS.md  (last changed 412d ago)
+  CLAUDE.md  (last changed 8d ago)
+
+4 rules look like permanent constraints:
+
+  AGENTS.md:3
+    "Never use TypeScript in this repo."
+    → absolute rule with no stated condition; unchanged for 412 days
+```
+
+It is a heuristic, not a verdict. If it finds nothing, that is useful too.
+
+---
+
+## The format
+
+```
+.decisions/
+└── 0001-session-not-redis.md
+```
+
+```markdown
+---
+id: 0001
+title: session 不存 Redis
+type: rejected            # rejected | decision | constraint
+status: live              # live | retired
+created: 2026-10-14
+expires_on: 2027-01-12
+revisit_when: "Redis 支持跨区域强一致时"
+evidence:
+  - "pr:412"
+tags: [infra, session]
+---
+
+## 结论
+不能把 session 存 Redis。
+
+## 为什么
+试过 Redis + 单写区域。us-east 故障时读延迟飙到 8s，SLO 要求 p99 < 500ms。
+```
+
+`rejected` entries are the valuable ones. They are the only kind that cannot be
+recovered from the code.
+
+### Expiry
+
+Every entry expires: 90 days for a rejection, 180 for a decision, 365 for a
+constraint.
+
+When an entry expires it **stops being shown to the agent**. It is not deleted.
+`whynot stale` lists it, and you either renew it or retire it.
+
+This is the whole safety mechanism. An expired entry is invisible, because
+telling an agent "this is old, be skeptical" was tested and does not work.
+
+If something genuinely never expires, write `expires_on: never`. It should be
+rare, and it should be a deliberate decision.
+
+---
+
+## Why this shape
+
+- **Markdown in git, not a database.** You can read it, diff it, review it,
+  revert it. If this tool disappears tomorrow, `grep` still works.
+- **No vector store, no embeddings, no model call when writing.** Each of those
+  is a failure mode we saw in existing tools: index staleness, write-path cost,
+  and results nobody can audit.
+- **Expiry is the default.** This is the part that differs from every other
+  memory tool. See [docs/validation.md](docs/validation.md) for the experiment.
+- **The format works without the tool.** The agent can read `.decisions/`
+  directly if MCP is unavailable. This was observed, not just designed.
+
+---
+
+## What this is not
+
+- Not a vector database or a retrieval engine.
+- Not a hosted service. Your reasoning about your own codebase stays on your
+  machine.
+- Not a replacement for `AGENTS.md`. That tells the agent how to behave; this
+  records what has already been settled.
+- Not automatic. If nobody records anything, it does nothing.
+
+---
+
+## Cross-platform notes
+
+Tested on Windows, macOS, and Linux.
+
+- `init` writes `*.md text eol=lf` to `.gitattributes`. Without it, Windows
+  checkouts write CRLF and every diff shows the whole file as changed.
+- Filenames are slugged to `[a-z0-9]` plus CJK. Windows forbids
+  `\ / : * ? " < > |` and both Windows and macOS are case-insensitive, so
+  filenames that work on Linux can break elsewhere.
+- No daemon and no file watching. The tool runs when it is called.
+- If you use non-ASCII filenames, run `git config core.quotepath false`.
+
+---
+
+## Verify it yourself
+
+```bash
+npm test                         # 29 tests, no dependencies
+node experiments/e3/run.mjs      # the statistical-power experiment
+node experiments/e4/run.mjs      # the age / expiry experiment
+node experiments/e5/run.mjs      # a real agent across real sessions
+```
+
+See [`experiments/README.md`](experiments/README.md) for all six and for the
+conventions they follow.
+
+The experiments call models through an OpenAI-compatible endpoint. Set
+`MAGPIE_URL` or edit the gateway constant at the top of each script. They are
+not part of the tool; they are how we checked the claims.
+
+---
+
+## License
+
+MIT. No account, no telemetry, no paid tier, no closed binary.
+There is nothing to upsell you.
+
+---
+
+[中文说明](README.zh-CN.md) · [Design](docs/design.md) · [Validation](docs/validation.md)

package/README.zh-CN.md

@@ -0,0 +1,204 @@
+# whynot
+
+**记下你否决了什么、为什么否决——让你的编码 agent 不再重提。**
+
+你的 agent 每次开新会话都从零开始。你上周否决的方案，它这周还会再提一遍。三个月后，你自己也忘了当初为什么否决。
+
+记忆类工具记录的是「**你做了什么**」。那些在代码、commit、PR 里都已经有了。真正哪儿都不存在的是「**你为什么没做**」——它只在你脑子里，而且在慢慢腐烂。
+
+`whynot` 就是你仓库里一个放 Markdown 的文件夹，外加一个很薄的 MCP server。
+
+---
+
+## 我们测到了什么
+
+六个实验，三个模型家族，多数条件 n=20。完整写稿和脚本在 [`docs/`](docs/) 和 [`experiments/`](experiments/)。
+
+### 年龄不重要，存在本身重要
+
+同一条决策，只改创建日期，被遵循的比例完全一样：
+
+| 决策的年龄 | 推荐被否决的选项 |
+|---|---|
+| 没有记录（基线） | 100% |
+| 30 天 | **0%** |
+| 1 年 | **0%** |
+| 7 年 | **0%** |
+| 7 年，已过期不可见 | **100%** |
+
+**模型不按年龄打折——它把每一条记录都当成现行的。**
+
+在提示词里加「这条很旧，请保持怀疑」没有用；**让过期条目不可见**才有用。这就是为什么「过期」是这个工具的核心，而不是可选项。
+
+### 记录一条否决，会实质改变结论
+
+n=20、三个模型家族合并：一条被记录的否决把推荐改变 **78–87 个百分点**（Fisher p < 0.0001）。
+
+### 两个必须说的限定
+
+- **不是所有模型都一样服从。** 当真实代码摆在面前时，一个模型直接从仓库推断出答案、无视了记录；另一个仍然倾向于被否决的方案，直到记录拦住它。
+- **写的理由比日期更重要。** 当记录写的是「团队当时不会 TS」，约五分之一的回复会攻击这个前提、照样推荐 TypeScript；当写的是「这个项目字段变更频繁」，服从是 100%。**命名了「条件」的理由会邀请复核，陈述了「属性」的理由不会。**
+
+### 没有测的东西
+
+**我们没有测过它在真实使用中是否帮得上忙。** 这里每个实验都是受控的单轮任务。真正重要的那个数字——几周真实工作里，agent 重提已否决方案的次数有没有下降——没有测，这个项目也不声称它。
+
+我们声称的是：**机制在测试条件下有效，而且脚本都在，你可以自己查。**
+
+---
+
+## 安装
+
+```bash
+npx whynot-cli init
+```
+
+然后把 [`AGENTS.snippet.md`](AGENTS.snippet.md) 里的那一段粘进你的 `AGENTS.md` 或 `CLAUDE.md`，再注册 MCP server。
+
+需要 Node 20+。没有别的依赖。不用全局安装，不用注册账号，没有遥测。
+
+### 注册 MCP server
+
+Claude Code、Claude Desktop、Cursor 以及大多数 MCP 客户端都用同样的格式：
+
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 使用
+
+```bash
+npx whynot-cli audit              # 扫描你现有的规则，找出永远不会过期的那些
+npx whynot-cli init               # 创建 .decisions/
+npx whynot-cli add --title "..." --why "..."
+npx whynot-cli check redis        # 这件事是不是已经定了？
+npx whynot-cli stale              # 哪些需要人来决定
+npx whynot-cli renew 0001         # 仍然成立 —— 续期
+npx whynot-cli retire 0002        # 不再成立 —— 归档
+```
+
+大多数时候你不会手动跑这些。agent 在发现某个方案行不通时会调 `decisions_record`，在提议方案之前会调 `decisions_check`。
+
+### 从 `audit` 开始
+
+`audit` 是只读的。它扫描 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.cursor/rules/*`、`.github/copilot-instructions.md`，找出那些**用绝对语气、但没写任何条件**的规则——也就是会被永久遵守的那一类。
+
+```
+Scanned 2 agent config files:
+  AGENTS.md  (last changed 412d ago)
+  CLAUDE.md  (last changed 8d ago)
+
+4 rules look like permanent constraints:
+
+  AGENTS.md:3
+    "Never use TypeScript in this repo."
+    → absolute rule with no stated condition; unchanged for 412 days
+```
+
+这是启发式检查，不是判决。**扫出来是 0 条，也是有用的信息。**
+
+---
+
+## 格式
+
+```
+.decisions/
+└── 0001-session-不存-redis.md
+```
+
+```markdown
+---
+id: 0001
+title: session 不存 Redis
+type: rejected            # rejected | decision | constraint
+status: live              # live | retired
+created: 2026-10-14
+expires_on: 2027-01-12
+revisit_when: "Redis 支持跨区域强一致时"
+evidence:
+  - "pr:412"
+tags: [infra, session]
+---
+
+## 结论
+不能把 session 存 Redis。
+
+## 为什么
+试过 Redis + 单写区域。us-east 故障时读延迟飙到 8s，SLO 要求 p99 < 500ms。
+```
+
+`rejected`（已否决）是最值钱的一类。它是唯一无法从代码里恢复出来的东西。
+
+### 过期
+
+每条记录都会过期：否决类 90 天，决策类 180 天，约束类 365 天。
+
+过期之后，它**不再展示给 agent**，但**不会被删除**。`whynot stale` 会列出来，你决定续期还是归档。
+
+这就是整个安全机制。过期条目是**不可见**的——因为「告诉 agent 这条很旧、请怀疑它」已经被实验证明不管用。
+
+如果某件事真的永远不过期，写 `expires_on: never`。这应该很少见，而且应该是一个刻意的决定。
+
+---
+
+## 为什么是这个形态
+
+- **Markdown 放在 git 里，不是数据库。** 你能读、能 diff、能 review、能回滚。就算这个工具明天消失，`grep` 依然能用。
+- **不用向量库、不用 embedding、写入时不调模型。** 这每一条都是我们在现有工具里实际看到的失败模式：索引过期、写入成本、以及没人能审计的结果。
+- **默认过期。** 这是它和其他所有记忆工具最不一样的地方。实验见 [docs/validation.zh-CN.md](docs/validation.zh-CN.md)。
+- **没有工具时格式依然可用。** MCP 不可用时，agent 可以直接读 `.decisions/`。这一点是观察到的，不只是设计出来的。
+
+---
+
+## 它不是什么
+
+- 不是向量数据库，也不是检索引擎。
+- 不是托管服务。你对自己代码库的推理过程留在你自己的机器上。
+- 不替代 `AGENTS.md`。那个告诉 agent 该怎么做事；这个记录哪些事已经定了。
+- 不是全自动的。没人记，它就什么也不做。
+
+---
+
+## 跨平台说明
+
+Windows / macOS / Linux 都测过。
+
+- `init` 会往 `.gitattributes` 写 `*.md text eol=lf`。不写的话，Windows 上会写入 CRLF，每次 diff 都显示整个文件被改。
+- 文件名会被 slug 成 `[a-z0-9]` 加中日韩字符。Windows 禁止 `\ / : * ? " < > |`，而且 Windows 和 macOS 大小写不敏感——在 Linux 上正常的文件名，换个系统就崩。
+- 没有常驻进程，没有文件监听。只有被调用时才运行。
+- 如果用非 ASCII 文件名，执行 `git config core.quotepath false`，否则 git 会把中文路径显示成八进制转义。
+
+---
+
+## 自己验证
+
+```bash
+npm test                         # 29 个测试，零依赖
+node experiments/e3/run.mjs      # 统计功效实验
+node experiments/e4/run.mjs      # 年龄 / 过期实验
+node experiments/e5/run.mjs      # 真实 agent 的跨会话实验
+```
+
+六个实验和它们遵循的约定见 [`experiments/README.md`](experiments/README.md)。
+
+实验通过一个 OpenAI 兼容端点调用模型。设置 `MAGPIE_URL`，或者改每个脚本顶部的网关地址。它们不属于工具本身，是我们验证结论用的。
+
+---
+
+## 许可证
+
+MIT。没有账号、没有遥测、没有付费档、没有闭源二进制。
+**没有任何东西要卖给你。**
+
+---
+
+[English](README.md) · [设计](docs/design.zh-CN.md) · [验证](docs/validation.zh-CN.md)

package/bin/whynot.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main();