docs: add foundational philosophy document

README.md

@@ -442,6 +442,8 @@ Override with environment variables: `SUPERVISOR_SURFACE_TYPE`, `SUPERVISOR_SURF
 
 ## Design Philosophy
 
+> **Foundational stance**: see [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) — why thin-supervisor watches but does not orchestrate.
+
 Inspired by [Anthropic's Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents):
 
 1. **The system's memory lives in SessionRun, not in the model's context.** Crashes don't lose history. Everything is in `session_log.jsonl`.

docs/PHILOSOPHY.md

@@ -0,0 +1,95 @@
+# thin-supervisor 的哲学
+
+## 核心公理
+
+**Worker 足够强。**
+
+我们不是在构建一个"让弱 agent 变强"的脚手架，而是在构建一个"让强 agent 可被信任"的见证人。
+
+这是一个赌。赌的是 coding agent 的能力在持续变强，不是停滞。过去两年每一次模型升级，agent 自己的规划、拆分、排序能力都在压过外部脚手架。我们选站在趋势这边。
+
+所有试图"替 agent 规划"的层，迟早会变成冗余——它们的决策质量早晚低于 agent 本身。
+
+## 三件事，仅此而已
+
+Worker 够强，意味着它能自己规划、自己决定下一步、自己写代码。这些**我们不介入**。我们只在三个时刻在场：
+
+1. **该停的时候让它停** — 当它要做不可逆或越权的事
+2. **该走的时候让它走** — 当它在问"要不要继续"但答案显然是 yes
+3. **说交付时替它判一下** — 因为"我做完了"是它结构性有偏的唯一判断
+
+这三件事有一个共同点：**它们都是 worker 结构性做不好的事，不是能力问题，是位置问题。**
+
+## 为什么只 gate，不 orchestrate
+
+Agent 的**能力**和**偏差**是两件不同的东西。能力随模型进步而长，偏差不会。
+
+- 规划、拆分、排序、选库——这些是**能力题**。Agent 越强做得越好，我们掺一脚只会拖后腿。
+- "我能做这个吗？""我做完了吗？""这是安全的吗？"——这些是**位置题**。它站在自己的位置上，永远有把答案说成 yes 的结构性压力。
+
+**编排是对能力题的外包；gate 是对位置题的纠偏。**
+
+前者会被能力增长蚕食，后者不会。模型再强，**它也没法同时当裁判和选手**——这是结构决定的，不是水平决定的。
+
+这就是为什么我们不做 plan 拆分、不做多 agent 编排、不做 context 管理。那些都是能力题，**agent 自己做只会越做越好**。而 gate 和 acceptance，agent 永远替代不了自己。
+
+## "薄"不是代码少，是信任密度高
+
+"thin" 真正的意思是**信任密度**。
+
+- **Fat supervisor** = 不信任 worker，每一步都要我过一遍。它假设 worker 是需要监工的实习生。
+- **Thin supervisor** = 信任 worker 的执行，但不信任它的自我评价。它假设 worker 是需要审计的专家。
+
+这两者对能力增长的响应完全相反：
+
+- Worker 变强 → **fat supervisor 价值下降**（实习生长大了，监工就多余了）
+- Worker 变强 → **thin supervisor 价值不变甚至上升**（专家水平越高，交付验收越重要——你越没法凭"看起来对"来判断它做对没做对）
+
+Fat 是在对冲 agent 的弱，强到一定程度就没对冲对象了。Thin 是在对冲 agent 的结构性偏差，agent 再强这个偏差也还在。
+
+## Gate vs. Drive：两种根本不同的东西
+
+| Orchestrator | Supervisor |
+|---|---|
+| 主动推动 | 被动制动 |
+| Happy path 里一直在 | Happy path 里近乎透明 |
+| 输出计划 | 输出证据 |
+| 决策驱动 | 契约驱动 |
+| 和 agent 同构（都在做 LLM 推理） | 和 agent 异构（做确定性验证） |
+
+一个好的 supervisor 在 90% 的时间里什么都不做。它像车上的 ABS——平时意识不到它存在，只在需要紧急制动时才显形。
+
+**推的东西会越来越像 agent 本身**，所以推的东西注定被 agent 淘汰。**制动的东西永远是外部的**，所以它不会被 agent 淘汰。
+
+## 我们不是什么（via negativa）
+
+克制的难处在于**每一个诱惑看起来都合理**。这些事我们明确**不做**：
+
+- 不当 coach（不教 agent 怎么做）
+- 不当 planner（不替它排顺序）
+- 不当 editor（不改它的 prompt）
+- 不当 PM（不跟踪里程碑）
+- 不当 context engineer（不管它 context 怎么用）
+
+我们只是一个**闸门 + 黑匣子**：
+
+- 闸门在边界上断路
+- 黑匣子 durable、append-only、可审计
+
+**飞机的黑匣子不会告诉飞行员怎么飞。**它只在事后告诉你发生过什么。这是一个特性，不是缺陷。
+
+## 克制是这个项目最难的工程
+
+能做的功能总是容易的。**不做是难的。**
+
+每次看到漂亮的"协作"或"编排"功能，都会有"我们也搞一个"的冲动。**抵抗这个冲动是这个项目的核心工程能力**，不是写代码的能力。
+
+理由很冷酷：**每加一层都是一次 LLM 调用，每一次 LLM 调用都可能出错。** 你为了修 LLM 的错而加的层，本身也是 LLM。加层的边际收益递减，边际成本不减。
+
+唯一打破这个递减规律的层是**确定性验证层**：跑测试、查文件、看 git 状态、hash 比对。这一层的可靠性不依赖 LLM。
+
+**这是我们唯一愿意往里加东西的地方。**
+
+## 一句话
+
+> 强 worker 需要的不是更好的教练，是更严格的裁判。