whynot-cli 0.0.0-stage → 0.1.1

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,275 @@
-# Temporary Holding Version
+<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>
 
-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.
+<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>
+
+---
+
+<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>
+
+---
+
+## The problem
+
+You tried Redis for session storage. It failed at 8 seconds during a regional
+outage, so you moved to Postgres.
+
+Three weeks later, in a new session, your agent suggests Redis.
+
+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.
+
+**Code remembers what you chose. Nothing remembers what you rejected.**
+
+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.
+
+---
+
+## Install
+
+```bash
+npx whynot-cli init
+```
+
+Nothing to install globally, no account, no telemetry. Node 20+ is the only
+requirement.
+
+---
+
+## Quick start
+
+### 1. See what will never expire
+
+`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
+```
+
+```
+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. Create the store
+
+```bash
+npx whynot-cli init
+```
+
+This creates `.decisions/` and adds `*.md text eol=lf` to `.gitattributes`.
+
+### 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
+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. Give it to your agent
+
+Add the MCP server:
+
+```json
+{
+  "mcpServers": {
+    "whynot": {
+      "command": "npx",
+      "args": ["-y", "whynot-cli", "mcp"]
+    }
+  }
+}
+```
+
+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 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.
+
+---
+
+## How it works
+
+### Every entry expires
+
+| Type | Default lifetime |
+|---|---|
+| `rejected` | 90 days |
+| `decision` | 180 days |
+| `constraint` | 365 days |
+
+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.
+
+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.
+
+---
+
+## 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:
+
+- **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.
+
+Full results, methods, and reproduction scripts: [`docs/findings.md`](docs/findings.md).
+
+---
+
+## Docs
+
+| | |
+|---|---|
+| [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 |
+
+---
+
+## CLI reference
+
+```
+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
+```
+
+---
+
+## License
+
+MIT. No account, no telemetry, no paid tier, no closed binary.
+There is nothing to upsell you.
+
+---
+
+<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>