whynot-cli 0.0.0-stage → 0.1.1

package/README.zh-CN.md

@@ -0,0 +1,257 @@
+<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>
+
+---
+
+<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>
+
+---
+
+<a id="problem"></a>
+## 问题
+
+你试过用 Redis 存 session。一次区域故障时它读到 8 秒，于是你换成了 Postgres。
+
+三周后，一个新会话里，你的 agent 建议用 Redis。
+
+你又解释了一遍。一个月后你从 Claude Code 换到 Codex，第三次解释。半年后，你自己也记不清当初为什么否决 Redis 了——团队里其他人更不知道。
+
+**代码记得住你选了什么。没有任何东西记得住你否决了什么。**
+
+记忆类工具记录的是「发生了什么」，那些在 commit、PR 和代码里本来就有。`whynot` 记录另一半：**你排除了哪些方案、为什么**，放在一个 agent 提议任何东西之前会读的文件里。
+
+---
+
+<a id="install"></a>
+## 安装
+
+```bash
+npx whynot-cli init
+```
+
+不需要全局安装，不用注册账号，没有遥测。只需要 Node 20+。
+
+---
+
+<a id="quick-start"></a>
+## 快速开始
+
+### 1. 先看哪些规则永远不会过期
+
+`audit` 是只读的。它扫描你现有的 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules`，找出那些**用绝对语气、却没写任何条件**的规则——会被永久遵守的那些。
+
+```bash
+npx whynot-cli audit
+```
+
+```
+Scanned 2 agent config files:
+  AGENTS.md  (last changed 412d ago)
+  CLAUDE.md  (last changed 8d ago)
+
+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
+```
+
+### 2. 创建记录目录
+
+```bash
+npx whynot-cli init
+```
+
+创建 `.decisions/`，并往 `.gitattributes` 写入 `*.md text eol=lf`。
+
+### 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
+status: live
+created: 2026-09-21
+expires_on: 2026-12-20
+revisit_when: "Redis 支持跨区域强一致时"
+evidence:
+  - "pr:412"
+tags: [infra, session]
+---
+
+## 结论
+不能把 session 存 Redis。
+
+## 为什么
+试过 Redis + 单写区域。us-east 故障时读延迟飙到 8s，SLO 要求 p99 < 500ms。
+```
+
+### 4. 交给你的 agent
+
+加上 MCP server：
+
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
+
+然后把 [`AGENTS.snippet.zh-CN.md`](AGENTS.snippet.zh-CN.md) 里的那一段粘进你的 `AGENTS.md` 或 `CLAUDE.md`。MCP server 提供工具，这段指令才让 agent 真的去用。
+
+> **MCP 不可用时，格式依然能用。** `.decisions/` 就是普通 Markdown，agent 可以直接读、直接 grep。这一条在真实 agent 测试里被观察到，不是假设。
+
+---
+
+<a id="how-it-works"></a>
+## 工作原理
+
+### 每条记录都会过期
+
+| 类型 | 默认有效期 |
+|---|---|
+| `rejected`（已否决） | 90 天 |
+| `decision`（决策） | 180 天 |
+| `constraint`（约束） | 365 天 |
+
+到期后，它**不再到达你的 agent**。不加注释、不加警告——直接不存在。`whynot stale` 会列出来，你决定续期还是归档。
+
+这是整个设计的核心。让 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 个会话里遵守了决策。 |
+
+安装之前，有两条需要知道：
+
+- **约五分之一的回复抵抗了陈旧记录**——方式是攻击记录里写的原因。命名了**「条件」**的理由（「团队当时不会 TS」）会邀请复核；陈述了**「属性」**的理由（「这个项目变更频繁」）不会。
+- **当真实代码在上下文里时，有些 agent 会直接从仓库推断答案**、无视记录。记录最有价值的地方，是代码表达不了的东西：**你否决掉的方案**。
+
+完整结果、方法和复现脚本：[`docs/findings.zh-CN.md`](docs/findings.zh-CN.md)。
+
+---
+
+<a id="docs"></a>
+## 文档
+
+| | |
+|---|---|
+| [设计](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 真正用起来的那段指令 |
+
+---
+
+## 命令行
+
+```
+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。没有账号、没有遥测、没有付费档、没有闭源二进制。
+**没有任何东西要卖给你。**
+
+---
+
+<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/bin/whynot.js

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

package/docs/design.md

@@ -0,0 +1,139 @@
+# Design
+
+Why the tool looks like this.
+
+## The problem
+
+A coding agent has no memory of last week. Every session starts from nothing.
+That is mostly fine: the code is the state, and the agent can read it. What it
+cannot read is **why you rejected an approach**.
+
+That knowledge has three properties that make it hard:
+
+- It does not exist in the repository. It exists in someone's head.
+- It decays. Six months later, the person remembers "we tried something" but
+  not what broke.
+- It is expensive to rediscover. The agent will happily spend tokens walking
+  the same dead end again.
+
+## The finding that shaped the design
+
+We recorded a 2019 decision — "do not use TypeScript, the team does not know
+it" — and asked two model families to choose a stack for a brand-new 2026
+service. Every response followed the seven-year-old note. Adding a warning to
+the prompt ("this is old, be skeptical") did not fix it. Making the entry
+expire did.
+
+The full numbers are in [validation.md](validation.md).
+
+The conclusion: **an agent cannot be relied on to weigh a stale instruction
+correctly.** So the design does not ask it to. An expired entry is not shown to
+the agent at all.
+
+This one decision explains most of the rest of the design.
+
+## Four decisions
+
+### 1. Data is Markdown in git
+
+Everything else follows from this.
+
+- A human can read and edit it without the tool.
+- `git diff` gives review for free.
+- `git revert` gives an undo for free.
+- If the project is abandoned, the data is still usable with `grep`.
+
+Most tools in this space store decisions in a database or a vector index. When
+those projects die, users lose the data along with the tool. This project is
+designed so that cannot happen.
+
+### 2. Expiry is the default
+
+Every entry carries an expiry date. `rejected` entries last 90 days, `decision`
+180, `constraint` 365. When it lapses, the entry stops reaching the agent.
+
+An expired entry is not deleted. `whynot stale` surfaces it, and a human either
+renews it or retires it. Both are explicit actions.
+
+`expires_on: never` exists for genuinely permanent constraints, but it must be
+written deliberately. Permanence should be a decision, not a default.
+
+### 3. No embeddings, no model calls on write
+
+Retrieval is deliberately simple: case-insensitive keyword matching over titles,
+tags, and bodies, scored by how many query terms hit.
+
+Two reasons:
+
+- **Auditability.** When an entry appears in the agent's context, it is obvious
+  why: the words matched. With embeddings, nobody can explain it.
+- **Cost and failure modes.** Vector indexing goes stale. LLM extraction is
+  expensive and is the main source of corrupted memories in the tools that use
+  it. Both are avoidable here, so they are avoided.
+
+The trade-off is real: keyword matching misses paraphrases. That is why
+`decisions_check` with no query returns a compact index of everything live, so
+the agent can see the full list cheaply before narrowing down.
+
+### 4. The format works without the tool
+
+The agent gets `decisions_check` through MCP. If MCP is unavailable, it can
+still read `.decisions/` directly — that is just Markdown.
+
+This was not a theoretical property. In the Codex integration test, the MCP
+call was blocked by an approval policy, and the agent fell back to reading the
+files and still respected the decision.
+
+## Form factor: four layers, not one
+
+A common mistake in this category is picking one form and forcing everything
+through it. Each concern here belongs to a different layer:
+
+| Layer | Form | Why it has to be this |
+|---|---|---|
+| Data | `.decisions/*.md` in git | Works with zero tooling. The durable asset. |
+| Behaviour | A block in `AGENTS.md` | Making an agent *proactively record* a rejection is an instruction, not an API. |
+| Capability | MCP server | Pull-based, structured, works across agents. |
+| Human loop | CLI | Renewing and retiring are human decisions. |
+| Distribution | npm and agent plugins | Zero-install; meets people where they already are. |
+| **Not** | Hosted API | Decisions about a codebase are the most sensitive artifact in the repo. Hosting them defeats the purpose. |
+
+## Cross-platform
+
+The project targets Windows, macOS, and Linux, because the failure modes are
+different on each.
+
+- **Line endings.** `init` writes `*.md text eol=lf` to `.gitattributes`.
+  Without it, Windows checkouts write CRLF and every diff shows the whole file.
+- **Filenames.** Windows forbids `\ / : * ? " < > |`, and Windows and macOS are
+  case-insensitive. Filenames are slugged to `[a-z0-9]` plus CJK, which
+  eliminates a class of "works on Linux" bugs.
+- **No background process.** Windows file watching is unreliable and needs
+  native dependencies. The tool is invoked, never resident.
+- **No git hooks.** Cross-platform shell in hooks is a minefield. Not used.
+
+## Deliberately not built
+
+- Vector search or embeddings.
+- Any model call in the write path.
+- A daemon or file watcher.
+- A web UI.
+- Automatic detection of rejections (a hook is possible later, but it is not
+  required for the core loop).
+- Team sync. `git` already does this.
+- Multi-repo aggregation.
+
+Each one is a real feature someone has asked for. Each one also makes the tool
+heavier, and this category has a graveyard full of heavier tools.
+
+## Open questions
+
+- **Does the repeated-mistake rate actually drop in real use?** The experiments
+  measure single-turn behaviour. The claim that matters is longitudinal and has
+  not been measured yet.
+- **How often does expiry lose knowledge people still need?** The trade is
+  deliberate, but the ratio is unknown. `whynot stale` is where that shows up.
+- **Does this survive being used by a team?** The design assumes one person
+  curating. With five people, who renews what?
+- **Is 90 days right for a rejection?** It is a guess. Different codebases move
+  at different speeds.

package/docs/design.zh-CN.md

@@ -0,0 +1,102 @@
+# 设计说明
+
+这个工具为什么长这样。
+
+## 问题
+
+编码 agent 对上周发生的事没有记忆。每次会话都从零开始。这本身问题不大——代码就是状态，agent 可以自己读。但它读不到的是：**你为什么否决了某个方案。**
+
+这类知识有三个麻烦的性质：
+
+- 它不在仓库里，在某个人脑子里。
+- 它会腐烂。半年后，那个人只记得「当时好像试过」，不记得具体哪里崩了。
+- 重新发现它的代价很高。agent 会毫不心疼地再走一遍那条死路。
+
+## 决定了整个设计的那个发现
+
+我们记录了一条 2019 年的决策——「不要用 TypeScript，团队没人会」——然后让两个模型家族给一个 **2026 年的全新服务**做技术选型。**每一次回复都遵循了那条七年前的笔记。** 在提示词里加一句「这条很旧，请保持怀疑」没有修好。让条目过期，才修好。
+
+完整数字见 [validation.zh-CN.md](validation.zh-CN.md)。
+
+结论是：**不能指望 agent 正确地权衡一条陈旧指令。** 所以设计上干脆不要求它权衡——**过期条目根本不出现在 agent 的视野里。**
+
+这一条决定了后面大部分设计。
+
+## 四个决定
+
+### 1. 数据是 git 里的 Markdown
+
+其他一切都由此而来。
+
+- 人不用工具也能读、能改。
+- `git diff` 免费提供 review。
+- `git revert` 免费提供撤销。
+- 就算项目被放弃，数据依然能用 `grep` 检索。
+
+这个领域里大多数工具把决策存进数据库或向量索引。那些项目死掉时，用户会连数据一起丢。这个项目从设计上就不允许这种事发生。
+
+### 2. 默认过期
+
+每条记录都带一个到期日。否决类 90 天，决策类 180 天，约束类 365 天。到期后，条目不再到达 agent。
+
+过期条目**不会被删除**。`whynot stale` 会把它列出来，由人决定续期还是归档。两者都是显式动作。
+
+`expires_on: never` 是为真正永久的约束准备的，但必须刻意写出来。**永久应该是一个决定，不是一个默认值。**
+
+### 3. 不用 embedding，写入时不调模型
+
+检索刻意做得很简单：对标题、标签、正文做大小写不敏感的关键词匹配，按命中的查询词数量排序。
+
+两个理由：
+
+- **可审计。** 当一条记录出现在 agent 的上下文里，原因一目了然：词对上了。用 embedding 的话，没人解释得清它为什么在那儿。
+- **成本与失败模式。** 向量索引会过期。用 LLM 抽取记忆很贵，而且正是这类工具里记忆被污染的主要来源。这两样在这里都可以避免，所以就不做。
+
+代价是真实的：关键词匹配会漏掉改写的说法。所以 `decisions_check` 在不带查询条件时会返回一个紧凑的索引，让 agent 先廉价地看到全貌，再往下缩小范围。
+
+### 4. 没有工具时，格式依然可用
+
+agent 通过 MCP 调用 `decisions_check`。如果 MCP 不可用，它仍然可以直接读 `.decisions/`——那不过是 Markdown。
+
+这不是理论上的性质。在 Codex 集成测试里，MCP 调用被审批策略拦住了，agent 自动降级去读文件，并且**依然遵守了那条决策**。
+
+## 形态：四层，不是一个
+
+这个品类里一个常见的错误是选一种形态，然后把所有事都塞进去。这里的每件事属于不同的层：
+
+| 层 | 形态 | 为什么必须是这个 |
+|---|---|---|
+| 数据 | git 里的 `.decisions/*.md` | 零工具依赖也能用。这是唯一不会死的资产。 |
+| 行为 | `AGENTS.md` 里的一段指令 | 让 agent **主动记录**否决，是指令问题，不是 API 能力问题。 |
+| 能力 | MCP server | 拉取式、结构化、跨 agent 通用。 |
+| 人的回路 | CLI | 续期和归档是人的决定。 |
+| 分发 | npm + agent 插件 | 零安装，在用户已经在的地方出现。 |
+| **不是** | 托管 API | 关于代码库的决策是仓库里最敏感的东西。托管它就等于毁掉整个前提。 |
+
+## 跨平台
+
+目标平台是 Windows、macOS、Linux，因为三者的坑不一样。
+
+- **换行符。** `init` 会往 `.gitattributes` 写 `*.md text eol=lf`。不写的话，Windows 上会写入 CRLF，每次 diff 都显示整个文件被改。
+- **文件名。** Windows 禁止 `\ / : * ? " < > |`，而且 Windows 和 macOS 大小写不敏感。文件名会被 slug 成 `[a-z0-9]` 加中日韩字符，从根上消除一整类「Linux 上好的、换个系统就崩」的问题。
+- **没有常驻进程。** Windows 的文件监听不可靠且需要原生依赖。工具只被调用，不常驻。
+- **不用 git hooks。** 跨平台的 shell 在 hook 里是雷区。所以不用。
+
+## 刻意不做的东西
+
+- 向量检索 / embedding
+- 写入路径上的任何模型调用
+- 守护进程或文件监听
+- Web UI
+- 自动检测否决（以后可以用 hook，但核心闭环不依赖它）
+- 团队同步。`git` 本身就是。
+- 多仓库聚合
+
+每一条都是真的有人要过的功能。每一条也都会让工具更重，而这个品类的坟场里全是更重的工具。
+
+## 还没有答案的问题
+
+- **真实使用中，重复犯错率真的会降吗？** 实验测的是单轮行为。真正重要的主张是长期的，而那个还没测。
+- **过期多久会丢掉人还需要的信息？** 这是一个刻意的取舍，但比例未知。`whynot stale` 是它显现的地方。
+- **团队用它撑得住吗？** 设计假设是一个人维护。五个人时，谁负责续期？
+- **否决类 90 天合适吗？** 这是猜的。不同代码库的节奏不一样。