Convergent Coding positioning + blueprint gap detection and scaffolding

README.md

@@ -1,14 +1,18 @@
-# CodeRail
+# CodeRail — Convergent Coding
 
 ![version](https://img.shields.io/badge/version-v0.7.3-2f80ed)
 ![license](https://img.shields.io/badge/license-MIT-27ae60)
 ![python](https://img.shields.io/badge/python-3.x-ffd43b)
 ![agent](https://img.shields.io/badge/agent--ready-Codex%20%7C%20Claude-8e44ad)
 ![scope](https://img.shields.io/badge/scope-repo--local-16a085)
 
-**Your AI coding assistant stops drifting, stops declaring victory too early, and always leaves a project state the next session can pick up.**
+**Spec is the output, not the input.**
 
-**让 AI 编码助手不再跑偏、不再过早宣布完成、并且永远留下下一个会话能接得住的项目状态。**
+**Spec 是产出，不是前提。**
+
+Vibe coding explores; CodeRail converges. As you build, discover, and change your mind, the tool quietly turns what you learned into guardrails — so exploration compounds instead of unravelling. Your AI assistant stops drifting, stops declaring victory too early, and always leaves a state the next session can pick up.
+
+Vibe coding 负责发散探索，CodeRail 负责收敛。你一边做、一边发现、一边改主意，工具在背后把你学到的东西悄悄追认为护栏——让探索层层累积，而不是层层瓦解。你的 AI 助手不再跑偏、不再过早宣布完成、并且永远留下下一个会话能接得住的项目状态。
 
 No server. No accounts. No new methodology to learn. Just three commands and a `docs/` folder that stays honest.
 
@@ -45,15 +49,19 @@ That is the whole interface. Your AI assistant reads the installed `AGENTS.md` a
 
 **`done`** — 安全网。它验证测试通过（或你明确记录了人工检查）、确认改动没超出承诺的文件、同步文档、只提交安全的任务相关文件，然后告诉你下一步。有问题它会拒绝并明确说出要修什么——AI 助手无法用话术绕过它。
 
-## Why / 为什么需要它
+## Why "Convergent Coding" / 为什么叫"收敛式编码"
+
+Vibe coding is fast and creative — until the project grows. Then docs rot, the assistant drifts from the goal, sessions forget each other, and "done" stops meaning done. The usual fix is spec-driven development: write the spec first, then build. But that assumes you already know what you want — and vibe coders discover what they want *by building*. Spec-first is not too hard for them; it points the wrong way.
+
+Vibe coding 又快又自由——直到项目变大。然后文档腐烂、助手偏离目标、会话之间互相失忆、"完成"不再意味着真的完成。常规解法是 spec 驱动开发：先写规格、再动手。但它假设你早就知道自己要什么——而 vibe coder 恰恰是**做出来才知道要什么**。spec 前置对他们不是太难，是方向反了。
 
-Vibe coding is fast and creative — until the project grows. Then docs rot, the assistant drifts from the goal, sessions forget each other, and "done" stops meaning done. Heavyweight spec-driven processes fix this but demand expertise most vibe coders do not have.
+Convergent Coding inverts the arrow. You explore freely; each time something proves true — a task verified, a decision made, a boundary learned — the tool records it as a constraint the next round of exploration must respect. The spec accumulates behind you instead of blocking the road ahead. Exploration stays free; the project stops oscillating and starts converging. When repeated fixing fails to converge, the tool says so and points one level up: rethink the design, or rethink the goal.
 
-Vibe coding 又快又自由——直到项目变大。然后文档腐烂、助手偏离目标、会话之间互相失忆、"完成"不再意味着真的完成。重型 spec 流程能解决这些，但它要求的工程素养恰恰是 vibe coder 不具备的。
+Convergent Coding 把箭头倒过来。你自由探索；每当一件事被证实——一个任务通过验证、一个决策被做出、一条边界被踩明白——工具就把它记录为下一轮探索必须尊重的约束。spec 在你身后累积，而不是挡在你前面。探索依旧自由，项目却不再震荡、开始收敛。当反复修补无法收敛时，工具会直说，并把你的注意力抬高一层：重新想设计，或者重新想目标。
 
-CodeRail takes a third path: the discipline runs automatically behind three plain commands. You never write a spec; the tool quietly maintains one for you (goal, task list, decision log, change history) and refuses to let anyone — human or AI — skip verification.
+In short: discipline runs automatically behind three plain commands. You never write a spec; the tool quietly maintains one for you (goal, task list, decision log, change history) and refuses to let anyone — human or AI — skip verification.
 
-CodeRail 走第三条路：纪律在三个命令背后自动运行。你从不写 spec，工具在背后悄悄替你维护（目标、任务清单、决策记录、变更历史），并且拒绝让任何人——无论人类还是 AI——跳过验证。
+一句话：纪律在三个命令背后自动运行。你从不写 spec，工具在背后悄悄替你维护（目标、任务清单、决策记录、变更历史），并且拒绝让任何人——无论人类还是 AI——跳过验证。
 
 ## What lives in your repo / 装进仓库的是什么
 
@@ -89,9 +97,9 @@ The three commands are a facade over a deeper kernel: verification gates, TDD ev
 python .coderail/coderail.py --help    # lists advanced commands
 ```
 
-Deep documentation lives in [`references/`](references/). Install details in [`INSTALL.md`](INSTALL.md). Skills for Claude Code / Codex live in [`skills/`](skills/).
+The idea behind the tool — Convergent Coding — is written up in [`references/CONVERGENT_CODING.md`](references/CONVERGENT_CODING.md). Deep documentation lives in [`references/`](references/). Install details in [`INSTALL.md`](INSTALL.md). Skills for Claude Code / Codex live in [`skills/`](skills/).
 
-深度文档见 [`references/`](references/)，安装细节见 [`INSTALL.md`](INSTALL.md)，Claude Code / Codex 的 skills 见 [`skills/`](skills/)。
+工具背后的思想——Convergent Coding（收敛式编码）——完整阐述见 [`references/CONVERGENT_CODING.md`](references/CONVERGENT_CODING.md)。深度文档见 [`references/`](references/)，安装细节见 [`INSTALL.md`](INSTALL.md)，Claude Code / Codex 的 skills 见 [`skills/`](skills/)。
 
 ## License
 

project-template/AGENTS.md

@@ -3,6 +3,13 @@
 This project uses CodeRail to keep AI-assisted work on track. The rules below
 are written in plain language. You do not need to learn any special terminology.
 
+One principle governs everything here: **spec is the output, not the input**.
+The user explores and discovers what they want by building; your job is to help
+them converge — each verified task, recorded decision, and learned boundary
+becomes a constraint the next round of work must respect. Never demand an
+upfront specification from the user, and never violate what has already been
+ratified in `docs/`.
+
 ## The three commands
 
 There is one entry point with three everyday commands:
@@ -92,6 +99,17 @@ The pattern behind this: when repeated fixing does not converge, the bug is
 almost never at the level where you are fixing. It lives one level up — in
 the design, or in the requirement itself.
 
+## When the tool says "Blueprints"
+
+`check` and `done` watch the codebase shape; when it grows a new layer they
+list the diagrams now needed (4 layers / 11 classes). When you see the notice,
+run `python .coderail/coderail.py blueprint --scaffold` — it creates Mermaid
+stubs under `docs/blueprints/`, marked `planned` in `docs/BLUEPRINTS.md`.
+Replace placeholders with the REAL structure (small enough that a newcomer
+understands without guesswork), then set the row to `current`. When a change
+invalidates a diagram, mark it `stale` in the same commit. Diagrams are
+ratified from what was built — never drawn ahead of the code.
+
 ## Honesty rules (non-negotiable)
 
 - Do not claim tests passed if you did not run them.
@@ -107,7 +125,6 @@ status with `python .coderail/coderail.py inspect`.
 
 ## Advanced
 
-Power users and long-running autonomous sessions can use the advanced
-commands (`doctor`, `drive`, `inspect`, `trace`, `blueprint`, `finish`, ...).
-Run `python .coderail/coderail.py --help` to list them. They are optional;
-the three everyday commands cover normal work.
+Power users and long-running autonomous sessions can use advanced commands
+(`doctor`, `drive`, `inspect`, `trace`, `finish`, ...); run
+`python .coderail/coderail.py --help` to list them. They are optional.

references/CONVERGENT_CODING.md

@@ -0,0 +1,119 @@
+# Convergent Coding / 收敛式编码
+
+> Spec is the output, not the input.
+> Spec 是产出，不是前提。
+
+This document defines the idea behind CodeRail. It is a positioning statement,
+not a methodology to study — the tool applies it automatically.
+
+本文定义 CodeRail 背后的思想。它是一份定位陈述，不是需要学习的方法论——工具会自动应用它。
+
+## The problem / 问题
+
+Two camps dominate how people build software with AI:
+
+- **Vibe coding**: describe, generate, look, react. Fast, creative, and honest
+  about how amateurs actually work — but it does not converge. Docs rot,
+  assistants drift, sessions forget each other, and late in the project the
+  owner loses the ability to judge what is going on.
+- **Spec-driven development**: write the specification first, then build.
+  It converges — but it assumes you already know what you want. Amateur
+  builders discover what they want *by building*. For them spec-first is not
+  merely difficult; the arrow points the wrong way.
+
+当下用 AI 造软件的两大阵营：
+
+- **Vibe coding**：描述、生成、看、反应。快、有创造力、忠于业余开发者的真实
+  工作方式——但它不收敛。文档腐烂、助手漂移、会话失忆，项目后期连项目
+  拥有者自己都失去了判断力。
+- **Spec 驱动开发**：先写规格再动手。它收敛——但它假设你早就知道自己要
+  什么。业余开发者恰恰是**做出来才知道要什么**。对他们来说 spec 前置不是
+  太难，是方向反了。
+
+## The idea / 思想
+
+Convergent Coding keeps vibe coding's direction of discovery and adds the one
+thing it lacks: a mechanism that makes exploration accumulate instead of
+unravel.
+
+The loop has three beats:
+
+1. **Explore** — build freely, in whatever language you think in
+   ("make the button do X"). No upfront modelling required.
+2. **Ratify** — each time something proves true — a task verified, a decision
+   made, a boundary learned the hard way — the tool records it as a
+   constraint. The spec grows *behind* you, assembled from verified facts,
+   never written in advance.
+3. **Converge or escalate** — feedback is compared against what was ratified.
+   If the work drifts, the tool says so. If repeated fixing fails to converge,
+   that is itself a signal (Wiener's second-order feedback): the problem lives
+   one level up. The tool then points there explicitly — rethink the design,
+   or rethink the goal.
+
+Convergent Coding 保留 vibe coding 的发现方向，补上它唯一缺失的东西：一个让
+探索层层累积、而非层层瓦解的机制。
+
+循环有三拍：
+
+1. **探索**——用你自己的语言自由地做（"让这个按钮做 X"），不要求任何前置建模。
+2. **追认**——每当一件事被证实——任务通过验证、决策被做出、边界被踩明白——
+   工具就把它记录为约束。spec 在你**身后**生长，由被验证过的事实拼装而成，
+   从不预先书写。
+3. **收敛或升层**——反馈与已追认的约束对照。工作跑偏，工具直说。反复修补
+   仍不收敛，这本身就是信号（维纳的二阶反馈）：问题在上一层。工具会明确
+   指过去——重新想设计，或重新想目标。
+
+## What it borrows, and what it changes / 借用与改造
+
+Convergent Coding is not a rejection of existing ideas. It extracts the
+smallest effective ingredient from each and re-mounts them on the
+explore–ratify–converge loop:
+
+| Source | Ingredient kept | Change made |
+|---|---|---|
+| Spec-driven | Explicit goal, scope, done-criteria | Shrunk to three lines per task; produced during work, not before it |
+| TDD | "State the expectation verifiably before claiming success" | Enforced only where correctness matters (bugs, parsers, domain logic, APIs); waived for exploration |
+| Domain-driven design | A shared reference the whole project aligns to | Reduced to one plain-language North Star; alignment triggered by non-convergence, not by ceremony |
+| Cybernetics (Wiener) | Feedback against a reference signal; escalate when feedback fails to converge | Implemented as deterministic counters, never LLM judgment |
+
+Convergent Coding 不是对既有思想的否定。它从每一种思想中萃取最小有效成分，
+重新装配在"探索—追认—收敛"循环上：
+
+| 来源 | 保留的成分 | 所做的改造 |
+|---|---|---|
+| Spec 驱动 | 显式的目标、范围、完成标准 | 缩到每任务三行；在工作中产出，而非工作前 |
+| TDD | "在宣称成功前，用可验证的语言说清期望" | 只在正确性敏感处强制（bug、解析器、领域逻辑、API）；探索性工作自动豁免 |
+| 领域驱动设计 | 全项目对齐的共同参照 | 退化为一段人话 North Star；由"不收敛"触发对齐，而非仪式 |
+| 控制论（维纳） | 对照参考信号的反馈；反馈不收敛时升层 | 以确定性计数实现，绝不依赖 LLM 判断 |
+
+## Design commitments / 设计承诺
+
+Any tool claiming to implement Convergent Coding should honor these:
+
+1. **The user never writes a spec.** The tool assembles one from verified work.
+2. **Ratified facts are cheap to create and hard to violate.** Three lines to
+   start a task; a gate that cannot be talked past to finish one.
+3. **Escalation is counted, not felt.** "You are going in circles" comes from
+   arithmetic on the history, never from a model's mood.
+4. **Every report is decodable by the owner.** Plain language, three questions:
+   what changed, how it was verified, what's next. An owner who can always
+   decode the feedback never loses judgment.
+5. **Everything lives in the repo as plain text.** Delete the folder and the
+   tool is gone; the ratified history remains readable.
+
+任何声称实现 Convergent Coding 的工具都应遵守：
+
+1. **用户从不写 spec。**工具从被验证的工作中拼装出 spec。
+2. **追认的事实创建成本极低、违反成本极高。**开始任务只需三行；结束任务
+   要过一道无法用话术绕过的门。
+3. **升层靠计数，不靠感觉。**"你在原地打转"来自对历史的算术，绝不来自
+   模型的情绪。
+4. **每一份汇报都是项目拥有者可解码的。**人话、三个问题：改了什么、怎么
+   验证的、下一步是什么。永远能解码反馈的人，永远不会失去判断力。
+5. **一切以纯文本存在于仓库中。**删掉目录工具即卸载，被追认的历史依然可读。
+
+## One sentence / 一句话
+
+Vibe coding explores; Convergent Coding makes exploration converge.
+
+Vibe coding 负责发散，Convergent Coding 让发散收敛。