whynot-cli 0.1.0 → 0.1.1

package/README.md

@@ -1,68 +1,66 @@
-# whynot
-
-**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.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/icon-dark.svg">
+    <img src="assets/icon-light.svg" alt="whynot" width="88">
+  </picture>
+</p>
+
+<h1 align="center">whynot</h1>
+
+<p align="center">
+  <b>Your agent keeps re-suggesting what you already rejected.</b><br>
+  Record the rejection once. It expires. Your agent stops bringing it up.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/whynot-cli"><img src="https://img.shields.io/npm/v/whynot-cli?style=flat-square&color=111111&label=npm" alt="npm"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT">
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=flat-square" alt="node 20+">
+  <img src="https://img.shields.io/badge/tests-29%20passing-brightgreen?style=flat-square" alt="29 tests passing">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square" alt="zero dependencies">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square" alt="platforms">
+  <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" alt="MCP compatible">
+  <img src="https://img.shields.io/badge/Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Cursor%20%C2%B7%20Gemini%20CLI-supported-informational?style=flat-square" alt="agent support">
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a>
+</p>
 
 ---
 
-## 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%** |
+<p align="center">
+  <a href="#the-problem">The problem</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#what-the-evidence-says">Evidence</a> ·
+  <a href="#docs">Docs</a> ·
+  <a href="#license">License</a>
+</p>
 
-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).
+## The problem
 
-### Two honest qualifications
+You tried Redis for session storage. It failed at 8 seconds during a regional
+outage, so you moved to Postgres.
 
-- **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.
+Three weeks later, in a new session, your agent suggests Redis.
 
-### What is not tested
+You explain again. A month after that you switch from Claude Code to Codex, and
+explain a third time. Six months later you no longer remember why Redis was
+rejected — and neither does anyone else on the team.
 
-**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.
+**Code remembers what you chose. Nothing remembers what you rejected.**
 
-The claim we do make: *the mechanism works under test, and the scripts are here
-so you can check.*
+Memory tools record what happened. That is already in your commits, your pull
+requests, and the code itself. `whynot` records the other half: the options you
+ruled out, and the reason, in a file your agent reads before it proposes
+anything.
 
 ---
 
@@ -72,82 +70,63 @@ so you can check.*
 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
+Nothing to install globally, no account, no telemetry. Node 20+ is the only
+requirement.
 
-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"]
-    }
-  }
-}
-```
+## Quick start
 
----
+### 1. See what will never expire
 
-## Use
+`audit` is read-only. It scans your existing `AGENTS.md`, `CLAUDE.md`, and
+`.cursor/rules` for absolute rules that state no condition — the ones that will
+be obeyed forever.
 
 ```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
+npx whynot-cli audit
 ```
 
-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:
+3 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.
+### 2. Create the store
 
----
+```bash
+npx whynot-cli init
+```
 
-## The format
+This creates `.decisions/` and adds `*.md text eol=lf` to `.gitattributes`.
 
-```
-.decisions/
-└── 0001-session-not-redis.md
+### 3. Record a rejection
+
+```bash
+npx whynot-cli add \
+  --title "session 不存 Redis" \
+  --why "us-east 故障时读延迟 8s，SLO 要求 p99 < 500ms" \
+  --type rejected \
+  --revisit "Redis 支持跨区域强一致时" \
+  --evidence pr:412 \
+  --tags infra,session
 ```
 
 ```markdown
 ---
 id: 0001
 title: session 不存 Redis
-type: rejected            # rejected | decision | constraint
-status: live              # live | retired
-created: 2026-10-14
-expires_on: 2027-01-12
+type: rejected
+status: live
+created: 2026-09-21
+expires_on: 2026-12-20
 revisit_when: "Redis 支持跨区域强一致时"
 evidence:
   - "pr:412"
@@ -161,79 +140,126 @@ tags: [infra, session]
 试过 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.
+### 4. Give it to your agent
 
-### Expiry
+Add the MCP server:
 
-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.
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
 
-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.
+Then paste the block from [`AGENTS.snippet.md`](AGENTS.snippet.md) into your
+`AGENTS.md` or `CLAUDE.md`. The MCP server gives the agent the tools; the
+snippet is what makes it actually use them.
 
-If something genuinely never expires, write `expires_on: never`. It should be
-rare, and it should be a deliberate decision.
+> **If MCP is unavailable, the format still works.** `.decisions/` is plain
+> Markdown, so the agent can read and grep it directly. This was observed in the
+> real-agent test, not assumed.
 
 ---
 
-## Why this shape
+## How it works
 
-- **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.
+### Every entry expires
 
----
+| Type | Default lifetime |
+|---|---|
+| `rejected` | 90 days |
+| `decision` | 180 days |
+| `constraint` | 365 days |
 
-## What this is not
+When an entry lapses it **stops reaching your agent**. Not annotated, not
+warned about — absent. `whynot stale` lists it, and you either renew it or
+retire it.
 
-- 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.
+This is the core of the design. Telling an agent "this note is old, be
+skeptical" was tested and does not work. Removing the note from view does.
+
+### Three entry types
+
+| Type | Use it for |
+|---|---|
+| **`rejected`** | An approach you tried and abandoned. The most valuable kind — nothing else in the repository remembers it. |
+| `decision` | A choice between viable options, with the reason |
+| `constraint` | A hard requirement the project must satisfy |
+
+### Written for humans, by design
+
+- **Markdown in git.** Read it, diff it, review it, revert it. If this tool
+  disappears, `grep` still works.
+- **No vector store, no embeddings, no model call on write.** Each of those is
+  a failure mode: index staleness, write-path cost, and results nobody can
+  audit.
+- **No daemon, no telemetry, no hosted service.** Your reasoning about your own
+  codebase stays on your machine.
 
 ---
 
-## Cross-platform notes
+## What the evidence says
+
+Six experiments, three model families, mostly n=20 per cell.
+
+| Question | Result |
+|---|---|
+| Does the age of a decision matter? | **No.** 30 days and 7 years were obeyed at the same rate (0/12 each). Expired → 12/12. |
+| Does recording a rejection change the answer? | **Yes.** 78–87 percentage points, p < 0.0001. |
+| Does an irrelevant record distort unrelated work? | **No.** 0/30. |
+| Does a real agent use it across sessions? | **Yes.** Codex respected the decision in 9/9 sessions. |
+
+Two qualifications worth knowing before you install:
 
-Tested on Windows, macOS, and Linux.
+- **About one in five responses resisted a stale record** — by attacking its
+  stated reason. A reason that names a *condition* ("the team did not know
+  TypeScript") invites re-checking; one that states a *property* ("this project
+  changes constantly") does not.
+- **With real code in context, some agents infer the answer from the repository**
+  and ignore the record. Records matter most for what code cannot express: the
+  option you rejected.
 
-- `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`.
+Full results, methods, and reproduction scripts: [`docs/findings.md`](docs/findings.md).
 
 ---
 
-## Verify it yourself
+## Docs
 
-```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
-```
+| | |
+|---|---|
+| [Design](docs/design.md) | Why the tool looks like this |
+| [Findings](docs/findings.md) | Every experiment, what it found, what it did not |
+| [Validation](docs/validation.md) | Index of the detailed write-ups |
+| [Pre-registration](docs/preregistration.md) | Decision rules fixed before the data |
+| [Contributing](CONTRIBUTING.md) | The four design constraints that are not negotiable |
+| [AGENTS snippet](AGENTS.snippet.md) | The block that makes your agent use this |
 
-See [`experiments/README.md`](experiments/README.md) for all six and for the
-conventions they follow.
+---
+
+## CLI reference
 
-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.
+```
+whynot init                     Create .decisions/ and the .gitattributes rule
+whynot add --title T --why W    Record an entry
+      [--type rejected|decision|constraint]
+      [--revisit "condition"]   When to reconsider
+      [--ttl N]                 Days until it expires
+      [--expires never]         Explicitly permanent
+      [--evidence pr:412]       Repeatable
+      [--tags infra,session]
+whynot list [--all]             List live entries
+whynot check "<query>"          Show live entries matching a query
+whynot stale                    Entries needing a human decision
+whynot renew <id> [--days N]    Extend an entry's life
+whynot retire <id>              Archive an entry (never deletes)
+whynot audit [--days N]         Scan agent config files (read-only)
+whynot doctor                   Validate the store
+whynot mcp                      Run the MCP server on stdio
+```
 
 ---
 
@@ -244,4 +270,6 @@ There is nothing to upsell you.
 
 ---
 
-[中文说明](README.zh-CN.md) · [Design](docs/design.md) · [Validation](docs/validation.md)
+<p align="center">
+  <sub><a href="README.zh-CN.md">简体中文</a> · <a href="https://github.com/Stakenshake/whynot">GitHub</a> · <a href="https://www.npmjs.com/package/whynot-cli">npm</a></sub>
+</p>

package/README.zh-CN.md

@@ -1,128 +1,126 @@
-# whynot
-
-**记下你否决了什么、为什么否决——让你的编码 agent 不再重提。**
-
-你的 agent 每次开新会话都从零开始。你上周否决的方案，它这周还会再提一遍。三个月后，你自己也忘了当初为什么否决。
-
-记忆类工具记录的是「**你做了什么**」。那些在代码、commit、PR 里都已经有了。真正哪儿都不存在的是「**你为什么没做**」——它只在你脑子里，而且在慢慢腐烂。
-
-`whynot` 就是你仓库里一个放 Markdown 的文件夹，外加一个很薄的 MCP server。
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/icon-dark.svg">
+    <img src="assets/icon-light.svg" alt="whynot" width="88">
+  </picture>
+</p>
+
+<h1 align="center">whynot</h1>
+
+<p align="center">
+  <b>你的 agent 一直在重提你已经否决过的方案。</b><br>
+  把它记一次。它会过期。agent 就不再提了。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/whynot-cli"><img src="https://img.shields.io/npm/v/whynot-cli?style=flat-square&color=111111&label=npm" alt="npm"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT">
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=flat-square" alt="node 20+">
+  <img src="https://img.shields.io/badge/tests-29%20passing-brightgreen?style=flat-square" alt="29 tests passing">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square" alt="zero dependencies">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square" alt="platforms">
+  <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" alt="MCP compatible">
+  <img src="https://img.shields.io/badge/Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Cursor%20%C2%B7%20Gemini%20CLI-supported-informational?style=flat-square" alt="agent support">
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a>
+</p>
 
 ---
 
-## 我们测到了什么
-
-六个实验，三个模型家族，多数条件 n=20。完整写稿和脚本在 [`docs/`](docs/) 和 [`experiments/`](experiments/)。
-
-### 年龄不重要，存在本身重要
-
-同一条决策，只改创建日期，被遵循的比例完全一样：
-
-| 决策的年龄 | 推荐被否决的选项 |
-|---|---|
-| 没有记录（基线） | 100% |
-| 30 天 | **0%** |
-| 1 年 | **0%** |
-| 7 年 | **0%** |
-| 7 年，已过期不可见 | **100%** |
+<p align="center">
+  <a href="#problem">问题</a> ·
+  <a href="#install">安装</a> ·
+  <a href="#quick-start">快速开始</a> ·
+  <a href="#how-it-works">工作原理</a> ·
+  <a href="#evidence">证据</a> ·
+  <a href="#docs">文档</a> ·
+  <a href="#license">许可证</a>
+</p>
 
-**模型不按年龄打折——它把每一条记录都当成现行的。**
-
-在提示词里加「这条很旧，请保持怀疑」没有用；**让过期条目不可见**才有用。这就是为什么「过期」是这个工具的核心，而不是可选项。
-
-### 记录一条否决，会实质改变结论
+---
 
-n=20、三个模型家族合并：一条被记录的否决把推荐改变 **78–87 个百分点**（Fisher p < 0.0001）。
+<a id="problem"></a>
+## 问题
 
-### 两个必须说的限定
+你试过用 Redis 存 session。一次区域故障时它读到 8 秒，于是你换成了 Postgres。
 
-- **不是所有模型都一样服从。** 当真实代码摆在面前时，一个模型直接从仓库推断出答案、无视了记录；另一个仍然倾向于被否决的方案，直到记录拦住它。
-- **写的理由比日期更重要。** 当记录写的是「团队当时不会 TS」，约五分之一的回复会攻击这个前提、照样推荐 TypeScript；当写的是「这个项目字段变更频繁」，服从是 100%。**命名了「条件」的理由会邀请复核，陈述了「属性」的理由不会。**
+三周后，一个新会话里，你的 agent 建议用 Redis。
 
-### 没有测的东西
+你又解释了一遍。一个月后你从 Claude Code 换到 Codex，第三次解释。半年后，你自己也记不清当初为什么否决 Redis 了——团队里其他人更不知道。
 
-**我们没有测过它在真实使用中是否帮得上忙。** 这里每个实验都是受控的单轮任务。真正重要的那个数字——几周真实工作里，agent 重提已否决方案的次数有没有下降——没有测，这个项目也不声称它。
+**代码记得住你选了什么。没有任何东西记得住你否决了什么。**
 
-我们声称的是：**机制在测试条件下有效，而且脚本都在，你可以自己查。**
+记忆类工具记录的是「发生了什么」，那些在 commit、PR 和代码里本来就有。`whynot` 记录另一半：**你排除了哪些方案、为什么**，放在一个 agent 提议任何东西之前会读的文件里。
 
 ---
 
+<a id="install"></a>
 ## 安装
 
 ```bash
 npx whynot-cli init
 ```
 
-然后把 [`AGENTS.snippet.md`](AGENTS.snippet.md) 里的那一段粘进你的 `AGENTS.md` 或 `CLAUDE.md`，再注册 MCP server。
+不需要全局安装，不用注册账号，没有遥测。只需要 Node 20+。
 
-需要 Node 20+。没有别的依赖。不用全局安装，不用注册账号，没有遥测。
+---
 
-### 注册 MCP server
+<a id="quick-start"></a>
+## 快速开始
 
-Claude Code、Claude Desktop、Cursor 以及大多数 MCP 客户端都用同样的格式：
+### 1. 先看哪些规则永远不会过期
 
-```json
-{
-  "mcpServers": {
-    "whynot": {
-      "command": "npx",
-      "args": ["-y", "whynot-cli", "mcp"]
-    }
-  }
-}
-```
-
----
-
-## 使用
+`audit` 是只读的。它扫描你现有的 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules`，找出那些**用绝对语气、却没写任何条件**的规则——会被永久遵守的那些。
 
 ```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        # 不再成立 —— 归档
+npx whynot-cli audit
 ```
 
-大多数时候你不会手动跑这些。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:
+3 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 条，也是有用的信息。**
+### 2. 创建记录目录
 
----
+```bash
+npx whynot-cli init
+```
 
-## 格式
+创建 `.decisions/`，并往 `.gitattributes` 写入 `*.md text eol=lf`。
 
-```
-.decisions/
-└── 0001-session-不存-redis.md
+### 3. 记录一条否决
+
+```bash
+npx whynot-cli add \
+  --title "session 不存 Redis" \
+  --why "us-east 故障时读延迟 8s，SLO 要求 p99 < 500ms" \
+  --type rejected \
+  --revisit "Redis 支持跨区域强一致时" \
+  --evidence pr:412 \
+  --tags infra,session
 ```
 
 ```markdown
 ---
 id: 0001
 title: session 不存 Redis
-type: rejected            # rejected | decision | constraint
-status: live              # live | retired
-created: 2026-10-14
-expires_on: 2027-01-12
+type: rejected
+status: live
+created: 2026-09-21
+expires_on: 2026-12-20
 revisit_when: "Redis 支持跨区域强一致时"
 evidence:
   - "pr:412"
@@ -136,64 +134,117 @@ tags: [infra, session]
 试过 Redis + 单写区域。us-east 故障时读延迟飙到 8s，SLO 要求 p99 < 500ms。
 ```
 
-`rejected`（已否决）是最值钱的一类。它是唯一无法从代码里恢复出来的东西。
-
-### 过期
+### 4. 交给你的 agent
 
-每条记录都会过期：否决类 90 天，决策类 180 天，约束类 365 天。
+加上 MCP server：
 
-过期之后，它**不再展示给 agent**，但**不会被删除**。`whynot stale` 会列出来，你决定续期还是归档。
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
 
-这就是整个安全机制。过期条目是**不可见**的——因为「告诉 agent 这条很旧、请怀疑它」已经被实验证明不管用。
+然后把 [`AGENTS.snippet.zh-CN.md`](AGENTS.snippet.zh-CN.md) 里的那一段粘进你的 `AGENTS.md` 或 `CLAUDE.md`。MCP server 提供工具，这段指令才让 agent 真的去用。
 
-如果某件事真的永远不过期，写 `expires_on: never`。这应该很少见，而且应该是一个刻意的决定。
+> **MCP 不可用时，格式依然能用。** `.decisions/` 就是普通 Markdown，agent 可以直接读、直接 grep。这一条在真实 agent 测试里被观察到，不是假设。
 
 ---
 
-## 为什么是这个形态
+<a id="how-it-works"></a>
+## 工作原理
 
-- **Markdown 放在 git 里，不是数据库。** 你能读、能 diff、能 review、能回滚。就算这个工具明天消失，`grep` 依然能用。
-- **不用向量库、不用 embedding、写入时不调模型。** 这每一条都是我们在现有工具里实际看到的失败模式：索引过期、写入成本、以及没人能审计的结果。
-- **默认过期。** 这是它和其他所有记忆工具最不一样的地方。实验见 [docs/validation.zh-CN.md](docs/validation.zh-CN.md)。
-- **没有工具时格式依然可用。** MCP 不可用时，agent 可以直接读 `.decisions/`。这一点是观察到的，不只是设计出来的。
+### 每条记录都会过期
 
----
+| 类型 | 默认有效期 |
+|---|---|
+| `rejected`（已否决） | 90 天 |
+| `decision`（决策） | 180 天 |
+| `constraint`（约束） | 365 天 |
 
-## 它不是什么
+到期后，它**不再到达你的 agent**。不加注释、不加警告——直接不存在。`whynot stale` 会列出来，你决定续期还是归档。
 
-- 不是向量数据库，也不是检索引擎。
-- 不是托管服务。你对自己代码库的推理过程留在你自己的机器上。
-- 不替代 `AGENTS.md`。那个告诉 agent 该怎么做事；这个记录哪些事已经定了。
-- 不是全自动的。没人记，它就什么也不做。
+这是整个设计的核心。让 agent「对旧笔记保持怀疑」被实测证明没有用；**把它从视野里移走**才有用。
+
+### 三种记录
+
+| 类型 | 用来记什么 |
+|---|---|
+| **`rejected`** | 试过并放弃的方案。**最值钱的一类**——仓库里没有别的东西记得它。 |
+| `decision` | 在几个可行方案之间做的选择，附理由 |
+| `constraint` | 项目必须满足的硬约束 |
+
+### 刻意做得很轻
+
+- **Markdown 放在 git 里。** 能读、能 diff、能 review、能回滚。工具消失了，`grep` 依然能用。
+- **不用向量库、不用 embedding、写入时不调模型。** 每一条都是失败模式：索引过期、写入成本、没人能审计的结果。
+- **没有守护进程、没有遥测、没有托管服务。** 你对自己代码库的推理留在你自己的机器上。
 
 ---
 
-## 跨平台说明
+<a id="evidence"></a>
+## 证据
+
+六个实验，三个模型家族，多数条件 n=20。
+
+| 问题 | 结果 |
+|---|---|
+| 决策的年龄重要吗？ | **不重要。** 30 天和 7 年被遵循的比例完全一样（各 0/12）。过期后 → 12/12。 |
+| 记录否决会改变结论吗？ | **会。** 78–87 个百分点，p < 0.0001。 |
+| 不相关的记录会扭曲无关工作吗？ | **不会。** 0/30。 |
+| 真实 agent 会跨会话使用它吗？ | **会。** Codex 在 9/9 个会话里遵守了决策。 |
+
+安装之前，有两条需要知道：
 
-Windows / macOS / Linux 都测过。
+- **约五分之一的回复抵抗了陈旧记录**——方式是攻击记录里写的原因。命名了**「条件」**的理由（「团队当时不会 TS」）会邀请复核；陈述了**「属性」**的理由（「这个项目变更频繁」）不会。
+- **当真实代码在上下文里时，有些 agent 会直接从仓库推断答案**、无视记录。记录最有价值的地方，是代码表达不了的东西：**你否决掉的方案**。
 
-- `init` 会往 `.gitattributes` 写 `*.md text eol=lf`。不写的话，Windows 上会写入 CRLF，每次 diff 都显示整个文件被改。
-- 文件名会被 slug 成 `[a-z0-9]` 加中日韩字符。Windows 禁止 `\ / : * ? " < > |`，而且 Windows 和 macOS 大小写不敏感——在 Linux 上正常的文件名，换个系统就崩。
-- 没有常驻进程，没有文件监听。只有被调用时才运行。
-- 如果用非 ASCII 文件名，执行 `git config core.quotepath false`，否则 git 会把中文路径显示成八进制转义。
+完整结果、方法和复现脚本：[`docs/findings.zh-CN.md`](docs/findings.zh-CN.md)。
 
 ---
 
-## 自己验证
+<a id="docs"></a>
+## 文档
 
-```bash
-npm test                         # 29 个测试，零依赖
-node experiments/e3/run.mjs      # 统计功效实验
-node experiments/e4/run.mjs      # 年龄 / 过期实验
-node experiments/e5/run.mjs      # 真实 agent 的跨会话实验
-```
+| | |
+|---|---|
+| [设计](docs/design.zh-CN.md) | 为什么是这个形态 |
+| [结论汇总](docs/findings.zh-CN.md) | 每个实验发现了什么、没发现什么 |
+| [验证索引](docs/validation.zh-CN.md) | 详细写稿的入口 |
+| [预注册](docs/preregistration.md) | 在数据之前定好的判据 |
+| [贡献指南](CONTRIBUTING.md) | 四条不可协商的设计约束 |
+| [AGENTS 片段](AGENTS.snippet.zh-CN.md) | 让 agent 真正用起来的那段指令 |
 
-六个实验和它们遵循的约定见 [`experiments/README.md`](experiments/README.md)。
+---
+
+## 命令行
 
-实验通过一个 OpenAI 兼容端点调用模型。设置 `MAGPIE_URL`，或者改每个脚本顶部的网关地址。它们不属于工具本身，是我们验证结论用的。
+```
+whynot init                     创建 .decisions/ 和 .gitattributes 规则
+whynot add --title T --why W    记录一条
+      [--type rejected|decision|constraint]
+      [--revisit "条件"]         什么时候该重新考虑
+      [--ttl N]                 多少天后过期
+      [--expires never]         显式设为永久
+      [--evidence pr:412]       可重复
+      [--tags infra,session]
+whynot list [--all]             列出有效记录
+whynot check "<查询>"           查某件事是不是已经定了
+whynot stale                    需要人决定的记录
+whynot renew <id> [--days N]    续期
+whynot retire <id>              归档（不删除）
+whynot audit [--days N]         扫描 agent 配置文件（只读）
+whynot doctor                   校验记录
+whynot mcp                      运行 MCP server（stdio）
+```
 
 ---
 
+<a id="license"></a>
 ## 许可证
 
 MIT。没有账号、没有遥测、没有付费档、没有闭源二进制。
@@ -201,4 +252,6 @@ MIT。没有账号、没有遥测、没有付费档、没有闭源二进制。
 
 ---
 
-[English](README.md) · [设计](docs/design.zh-CN.md) · [验证](docs/validation.zh-CN.md)
+<p align="center">
+  <sub><a href="README.md">English</a> · <a href="https://github.com/Stakenshake/whynot">GitHub</a> · <a href="https://www.npmjs.com/package/whynot-cli">npm</a></sub>
+</p>

package/assets/icon-dark.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" fill="none" role="img" aria-label="whynot">
+  <g stroke="#F5F5F5" stroke-width="7" stroke-linecap="round">
+    <path d="M20 60h30"/>
+    <path d="M50 60 84 32"/>
+    <path d="M50 60 84 88"/>
+    <path d="M90 26l14 14"/>
+    <path d="M104 26 90 40"/>
+  </g>
+  <circle cx="20" cy="60" r="8" fill="#F5F5F5"/>
+  <circle cx="92" cy="94" r="8" fill="#F5F5F5"/>
+</svg>

package/assets/icon-light.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" fill="none" role="img" aria-label="whynot">
+  <g stroke="#111111" stroke-width="7" stroke-linecap="round">
+    <path d="M20 60h30"/>
+    <path d="M50 60 84 32"/>
+    <path d="M50 60 84 88"/>
+    <path d="M90 26l14 14"/>
+    <path d="M104 26 90 40"/>
+  </g>
+  <circle cx="20" cy="60" r="8" fill="#111111"/>
+  <circle cx="92" cy="94" r="8" fill="#111111"/>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whynot-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Record what you ruled out, and why, so your coding agent stops re-suggesting it.",
   "type": "module",
   "author": "Stakenshake",
@@ -23,6 +23,7 @@
   "files": [
     "bin",
     "src",
+    "assets",
     "docs/design.md",
     "docs/design.zh-CN.md",
     "docs/findings.md",