add-coder 0.3.35 → 0.3.38

package/README.en.md

@@ -48,32 +48,73 @@ ADD paradigm + Qoder:       cache hit rate 99.31%, only 2,426 MISS tokens/req
 
 ### ③ Gateway-Driven, Not Free-Form Conversation
 
-Traditional AI coding is "you say, I do" — quality depends entirely on the LLM's state that day. add-coder embeds **dual quality gateways** into the architecture:
-
-```
-DPS (Design-Process Symmetry)  — Design / Implementation / Docs / Audit, each weighted 25%, < 85% BLOCKED
-RAHS (Runtime Architecture Health Score) — Runtime architecture health, < 90% BLOCKED
+> **Others retry; add-coder gates.** Quality should not depend on the model's mood that day.
+
+Traditional AI coding is "you say, I do" — quality rests entirely on the LLM's form in the moment. add-coder embeds **dual quality gateways** in the architecture — not "suggestions" but **architectural blocks**: without passing the gate, a Step cannot advance.
+
+| Dimension | Typical practice | add-coder's dual gateways |
+|-----------|------------------|---------------------------|
+| **Basis** | Model self-assessment / human eyeballing | **DPS**: semantics (TF-IDF/Jaccard) + entropy (Shannon/Deng) + CPM critical path + structural completeness; **RAHS**: scope fidelity / type safety / audit completeness / Spec compliance / phase symmetry |
+| **Force** | "Please make sure…" in a prompt | Cannot enter Step 1 without passing DPS (`PASS=80`, threshold sourced from `dps-scoring-rules.toml`); nothing is released without RAHS (≥90) |
+| **Reproducibility** | Ask the model twice, get two answers | Same document + same parameters = same score; per-dimension scores plus a weakness list — explainable, comparable, regression-testable |
+| **Tuning** | Edit code, edit prompts, re-release | **caijuehub TOML declarations**: score → read weaknesses → tune → re-score, without touching code |
+| **Weights** | Hand-tuned once, then frozen | **FFT adaptive weights** that evolve with audit data — DPS parameters are data, not magic numbers |
+| **Negative feedback** | "Just regenerate it" | A failed gate pinpoints the weak dimension; gate results are collected idempotently (Gate → `MetricSnapshot`) into the memory loop for review |
+
+```text
+DPS (Documentation Precision Score) — semantics + entropy + CPM critical path + structural completeness → 4-dimension composite + FFT adaptive weights
+RAHS (Runtime Architecture Health Score) — scope fidelity + type safety + audit completeness + Spec compliance + phase symmetry → ≥ 90 passes
 ```
 
-These are not "suggestions" — they are **architectural blocks**. A Step cannot advance without passing its gateway.
+> Thresholds and parameters live in a readable TOML source of truth (`dps-scoring-rules.toml`), not magic numbers; `check_dps` resolves spec references across five adapters (qoder / claude / add / vscode / codex·trae, covered by `tests/dps-adapter.test.ts`).
 
 ### ④ Cross-Session Memory, Not Per-Session Amnesia
 
-The fatal flaw of AI conversations: architectural decisions from last session, bugs fixed, agreements reached — all forgotten in the next conversation. add-coder solves this at the architecture level:
+> **Other tools "remember". add-coder governs memory.** Memory is not a context-engineering problem — it is a governance problem.
 
-- **Handoff Documents** — Automatically generated structured handoff at the end of each session, auto-loaded by the next session
-- **Plan Index** — All Plans are centrally indexed via `index.md`, supporting fuzzy-match quick lookup
-- **DevLog Timeline** — Every operation is written to the `{YYYY-MM}/{DD}/` timeline, enabling full historical state traceability
+The fatal flaw of AI conversations: architectural decisions from last session, bugs fixed, agreements reached — all forgotten in the next conversation. Most AI coding tools treat "memory" as **session/repo-level text excerpts plus vector search** — pasting slices of old chats or files back into context. That answers "was it seen", not "does it count, should it be injected, who is accountable when it is wrong". add-coder's memory is a **governed knowledge layer**: every conclusion carries evidence, every recall can be replayed, every revision leaves a trace, every cross-boundary leak can be sampled.
 
-### ⑤ Policy-Update-Loop: Self-Evolving Governance (the scaffold itself does not include this architectural capability; a DEMO repo will be provided next to better illustrate the Policy-Update-Loop and Report system)
+**The gap is structural, not a recall-rate gap**
 
-Not a static template, but a **closed-loop adaptive system**:
+| Dimension | Typical "memory" | add-coder memory loop (since v0.3.35) |
+|-----------|------------------|---------------------------------------|
+| **Write path** | Auto-extract, active immediately | **Candidate-only**: `propose_memory` lands CANDIDATE (dedup + secret scan + conflict detection); it turns ACTIVE only after human adjudication via `resolve_memory`, and `approve` requires ≥1 piece of evidence |
+| **Grounding** | The memory text is its own justification | **Evidence chain**: conclusions and sources are separated; collection is idempotent (`sourceRef=<gate>:<planKeyword>:<runId>`; replays never duplicate); `get_memory` exposes provenance and the supersession chain |
+| **Timing** | Similarity-triggered, can fire anytime | **Deterministic waypoint recall**: fires on ADD stage waypoints only (Plan draft / Spec draft / DPS / RAHS / Handoff), specificity-first word lists; produced synchronously on the Hook side, executed on the MCP side |
+| **Retrieval** | Single-channel vector similarity | **FTS × vector, RRF-fused, then governed rerank** (scope / kind / importance / confidence / mandatory constraints − stale / conflict / redundancy), trimmed to a token budget |
+| **Explainability** | Result only | Every hit carries `whySelected` / `scoreBreakdown` / `recallId`; `rankingVersion` stores the config snapshot — **the same recall can be replayed** |
+| **Degradation** | No explicit contract | Without pgvector / sqlite-vec it runs FTS-only and returns `degradedMode` explicitly — never silently distorted |
+| **Correction** | Delete or overwrite | **Governance state machine**: submit_review / approve / reject / stale / supersede / archive / restore, with scope-compatible supersession — memory can be *falsified*, not merely overwritten |
+| **Boundaries** | No scope isolation | Eight-level scope isolation (ORGANIZATION / REPOSITORY / BRANCH / MODULE / PATH / SYMBOL / PLAN / SPEC) + cross-repo leakage sampling in `get_memory_health` |
+| **Weighting** | Hard-coded weights | Feedback stats (channel × rank × outcome) / cold-start fitting / Kalman online estimation / FFT cadence diagnostics (never direct ranking); **the weight snapshot is the single source of truth for ranking parameters** |
 
-```
+**Two layers**
+
+- **Document layer** (since v0.3.25) — Handoff documents (auto-generated each session end, auto-loaded next session) · Plan index (`index.md`, fuzzy lookup) · DevLog timeline (`{YYYY-MM}/{DD}/`, fully traceable)
+- **Knowledge layer** (the v0.3.35 memory loop) — candidate-only intake → idempotent evidence collection (whitelisted tool events → `evidence-queue.jsonl` → async consumption → `MetricSnapshot`) → waypoint recall → hybrid recall + governed rerank → feedback-driven calibration, every step on the record
+
+**Switches**: `ADD_MEMORY_RECALL_MODE=off|shadow|inject` (default `shadow`: recall runs and is audited, but is not injected yet) · `ADD_MEMORY_MAX_TOKENS` (default 600) · `ADD_MEMORY_EVIDENCE` (default `on`).
+
+> Honest disclosure: measured Hybrid `MRR@5` 0.4867 < the 0.75 threshold (FTS-only 0.6551, Recall@5 0.9592) — the threshold stays put; data-driven calibration replaces hand-tuning. The capability runs, can be inspected and can be adjudicated — no metric inflation.
+> Source layout, tables and dev workflow: [DEVELOPMENT.md](./DEVELOPMENT.md) §十七.
+
+### ⑤ Policy-Update-Loop: Self-Evolving Governance
+
+> **Static templates rot; closed-loop governance evolves.** Rules are not frozen constants — they are parameters that audit data can move.
+> (The scaffold itself does not include the end-to-end boundary-report loop yet; a DEMO repo will illustrate the Policy-Update-Loop and Report system.)
+
+```text
 Execute → Audit → Boundary Report → Rule Adjustment → Next Execution
 ```
 
-Runtime-generated Reports feed back into governance rules, enabling continuous evolution of governance strategies.
+| Dimension | Static rules / templates | add-coder Policy-Update-Loop |
+|-----------|--------------------------|------------------------------|
+| **Where rules live** | Hard-coded in code and prompts; changing them means a release | caijuehub TOML declarations: rule sources → generated constants → inlined into artifacts; **edit rules, not code** |
+| **Where rules come from** | Thresholds picked by intuition | Fed by audit data: DPS **FFT adaptive weights**; `check_doc_similarity` quantitatively re-checks look-alike documents |
+| **Feedback loop** | None | **Execute → Audit (✓ live)**: hook interception / file-write events → jsonl → MCP resident consumer → DevOperation persistence (`HOOK_INTERCEPT`, idempotent dedup) |
+| **Consistency** | Each endpoint implements its own, behaviour drifts | One governance contract layer + a five-endpoint consistency matrix asserting each behaviour (dangerous-command blocking / sensitive-file anchoring / audit event surface / protocol shape / zero governance duplication) |
+| **Evidence of evolution** | No trail | Every interception, score and adjudication lands in the audit store — queryable, countable, reproducible |
+| **Not closed yet** | — | Boundary reports (Runtime Report) end-to-end pending the DEMO repo (disclosed as-is) |
 
 ### ⑥ Multi-IDE Hooks as the Governance Layer
 
@@ -88,13 +129,28 @@ Hooks are not "notification push" — they are the **IDE runtime interception la
 
 Each IDE（Claude Code / Qoder CN / VS Code Copilot / Trae / Codex）has its own hook implementation, but the **governance logic is unified** — the architecture is consistent, only the adapter layer differs.
 
-| IDE | Governance Doc | Events Covered | Hook Config |
+| IDE | Governance Doc | Registrable events | Hook Config (direct node invocation) |
 |---|---|---|---|
-| Claude Code | [ADD-governance-claude-code.md](./templates/core/docs/ADD-governance-claude-code.md) | 14/17 | `.claude/hooks/*.sh` |
-| Qoder CN | [ADD-governance-qoder-cn.md](./templates/core/docs/ADD-governance-qoder-cn.md) | 10/17 | `.qoder/hooks/*.sh` |
-| VS Code Copilot | [ADD-governance-vscode-copilot.md](./templates/core/docs/ADD-governance-vscode-copilot.md) | 10/17 | `.github/hooks/*.json` → `.vscode/hooks/*.sh` |
-| Trae | [ADD-governance-trae.md](./templates/core/docs/ADD-governance-trae.md) | 6/17 | `hooks.json` → `.trae/hooks/*.sh` |
-| Codex | [ADD-governance-codex.md](./templates/core/docs/ADD-governance-codex.md) | 0 native / 14 (via Claude import) | `.codex/hooks.json` |
+| Claude Code | [ADD-governance-claude-code.md](./templates/core/docs/ADD-governance-claude-code.md) | 11/16 | `.claude/hooks/*.mjs` (settings.json command) |
+| Qoder CN | [ADD-governance-qoder-cn.md](./templates/core/docs/ADD-governance-qoder-cn.md) | 11/16 | `.qoder/hooks/*.mjs` (settings.json command) |
+| VS Code Copilot | [ADD-governance-vscode-copilot.md](./templates/core/docs/ADD-governance-vscode-copilot.md) | 10/16 | `.vscode/hooks/*.mjs` (Agent Host dual channel) |
+| Trae | [ADD-governance-trae.md](./templates/core/docs/ADD-governance-trae.md) | 6/16 | `hooks.json` → `.trae/hooks/*.mjs` |
+| Codex | [ADD-governance-codex.md](./templates/core/docs/ADD-governance-codex.md) | 5/16 | `.codex/hooks.json` → `.codex/hooks/*.mjs` |
+
+### ⑦ Codex Native Integration (v0.3.25)
+
+> **Not a bolted-on MCP server, but governance landing natively.** "Templates generated" ≠ "end-to-end verified" — this is a 6-step path that has actually been exercised.
+
+| Dimension | Typical integration | add-coder × Codex |
+|-----------|--------------------|-------------------|
+| **Setup cost** | Hand-written launcher scripts | Three CLI steps: `init --adapter=codex` → `--print-mcp-config` (no writes, no project init) → paste, or `--write-user-config` (backup first, duplicate-safe) |
+| **Governance surface** | Tool calls only, no lifecycle governance | **Native hooks**: `.codex/hooks.json` → `.codex/hooks/*.mjs` (14 entry artifacts pre-baked in the package, invoked by `node`; 5/16 native events registrable today, the rest already placeheld, enabled with zero code once the event model grows) |
+| **Approval** | Ask in chat | **Native HITL**: `create_hitl` takes the MCP Apps branch (no high-dimensional `inputRequired` in Codex); when the panel cannot render, it falls back to a markdown proposal + instance HTML, and verdicts are still persisted |
+| **Runtime state** | No way to tell whether the new artifacts are running | **Four-state artifact/process freshness** + `.mcp-restart-required` marker: `sync` names the server that needs a restart |
+| **Multi-project** | A pasted-wrong config silently connects to the wrong DB | `env.PROJECT_ROOT` injected at render time; a mismatched config makes mcp-server exit on startup (process-layer contract §4) |
+| **Platform** | WSL required / paths patched by hand | win32 automatically emits a native `cmd /c npx.cmd` branch |
+
+> Disclosed as-is: some Codex builds (measured `26.908`) do not render the approval widget; approval then goes through the markdown proposal + instance HTML + a chat verdict — the path works and verdicts are still persisted.
 
 ---
 
@@ -205,7 +261,7 @@ npx add-coder init
 ┌──────┐ ┌──────┐ ┌──────────┐ ┌──────┐ ┌──────┐
 │Claude│ │Qoder │ │ VS Code  │ │ Trae │ │Codex │
 │Hooks │ │Hooks │ │  Config  │ │Hooks │ │Hooks │
-│14/17 │ │10/17 │ │  10/17   │ │ 6/17 │ │ 6/17 │
+│11/16 │ │11/16 │ │  10/16   │ │ 6/16 │ │ 5/16 │
 └──────┘ └──────┘ └──────────┘ └──────┘ └──────┘
                            │
               ┌────────────┘
@@ -227,7 +283,7 @@ npx add-coder init
 > **Recommended**: Run PostgreSQL via Podman/Docker, reference config:
 > ```yaml
 > postgres:
->   image: docker.io/postgres:16-alpine
+>   image: docker.io/pgvector/pgvector:pg16
 >   ports: ["127.0.0.1:5433:5432"]
 >   environment:
 >     POSTGRES_DB: mydb
@@ -245,8 +301,22 @@ npx add-coder init
 | Plan | Description |
 |------|-------------|
 | Demo Repo | A full example repository showcasing end-to-end closed-loop practice of Policy-Update-Loop and the Report system |
-| MCP Restructure | MCP toolchain architecture upgrade, improving audit and gateway tool extensibility and standalone deployment capability |
-| Memory Enhancement | Long-term project knowledge memory and plan-level sparse memory |
+| ~~MCP Restructure~~ | ✅ v0.2.9 MCP toolchain architecture upgrade, improving audit and gateway tool extensibility and standalone deployment capability |
+| ~~Memory Enhancement~~ | ✅ **v0.3.35→v0.3.37 Governance memory**: idempotent evidence collection + deterministic waypoint recall + hybrid FTS×vector recall (RRF fusion + governed rerank) + Handoff Digest candidates + a ranking calibration foundation; native layer (SQLite FTS5 tables + triggers) auto-applied by `init`/`db-ensure` with `memory:reindex` self-heal; defaults to `shadow` mode (recall runs and is audited, not injected yet) |
+
+---
+
+## 🙏 Acknowledgements
+
+A paradigm is worth what people make of it — including the problems they find in it. The **contributor wall** lives in **[CONTRIBUTING.md §贡献者墙](./CONTRIBUTING.md#-贡献者墙)**; the item-by-item detail (in Chinese) lives in **[docs/ACKNOWLEDGEMENTS.md](./docs/ACKNOWLEDGEMENTS.md)**.
+
+| Contributor | Contribution | What it left behind |
+|-------------|--------------|---------------------|
+| [@iopzhu](https://github.com/iopzhu) | Memory rotation on the `memory_cache` branch (`357b215`, 48 files / +5877 −33) | The retrieval and tooling backbone of the memory loop: `retrieval/pipeline`, RRF fusion, governed rerank, dual FTS channels, evidence/snapshot jobs, `tools/memory.ts` (609 lines) plus a 909-line recall evaluation set |
+| [@Milkycoffees](https://github.com/Milkycoffees) | Ecosystem work: [`add-coder-flash`](https://www.npmjs.com/package/add-coder-flash) (npm `1.0.4`, 5 releases, plus a [public GitHub repo](https://github.com/Milkycoffees/add-coder-flash)) | A zero-dependency lightweight distribution: pure-`.mjs` hooks, no database required, assets laid down by `npm install`; auto-generates `.qoder-cn/mcp.json` and fed real constraints back (QoderCN config location, pnpm `allowBuilds`, MCP name length) |
+| [@albertm88](https://github.com/albertm88) | Relentless issue reporting (#5–#7, #10–#20 — 14 issues, all closed) | Cross-session memory, 429 storms, Windows stability, native Codex adaptation, port drift, non-interactive hangs, first-run HITL approval… walking the edge cases so nobody else has to |
+
+> Want on the wall? The criteria live in [CONTRIBUTING.md §贡献者墙](./CONTRIBUTING.md#-贡献者墙) — file an [issue](https://github.com/xiaomingming92/add-coder/issues) (reproducible problems, real logs, platform differences) or open a [PR](https://github.com/xiaomingming92/add-coder/pulls); both count as hard contribution.
 
 ---
 <details id="chinese-readme">
@@ -270,31 +340,34 @@ npx add-coder init
 | 无关联性 | Plan → Spec → Task → Step → Tool Call，形成完整证据链 |
 
 ### ② 门禁驱动，而非自由对话
-```
-DPS (Design-Process Symmetry)  — 设计/实现/文档/审计 四维各 25%，< 85% BLOCKED
-RAHS (Runtime Architecture Health Score) — 运行时架构健康度，< 90% BLOCKED
-```
-这不是「建议」，是**架构阻断** — 不通过闸门的 Step 无法推进到下一步。
+
+> **别的工具靠「再试一次」，add-coder 靠「先过闸门」。**
+
+DPS（Documentation Precision Score）= 语义 + 熵 + CPM 关键路径 + 结构完整度四维复合 + FFT 自适应权重（`PASS=80`）；RAHS = 范围保真 / 类型安全 / 审计完整 / Spec 合规 / 阶段对称（≥90）。这不是「建议」，是**架构阻断**——不过闸门，Step 推进不了；阈值与权重都是可读 TOML 真源（`dps-scoring-rules.toml`），改规则不改代码。
 
 ### ③ 跨轮记忆，而非每轮失忆
-- **Handoff 文档** — 每轮 Session 结束时自动生成结构化交接文档
-- **Plan 索引** — 所有 Plan 通过 `index.md` 集中索引
-- **DevLog 时序记录** — 每一步操作写入 `{YYYY-MM}/{DD}/` 时间轴
+
+> **别的工具在「记」，add-coder 在「治理记忆」。** 记忆不是上下文工程，是治理工程。
+
+多数工具的记忆 = 会话/仓库级文本摘录 + 向量检索（解决「看过」）；add-coder 是**受治理的知识层**：候选制入库（approve 需 ≥1 证据）· 证据链 + 幂等采证 · 位点确定性召回 · FTS×向量 RRF 融合 + 治理重排 · 召回可重放（`recallId` / `rankingVersion`）· 治理状态机可证伪（supersede 强制 scope 兼容）· 八级 scope 隔离 + 越库泄漏抽查 · 权重快照即排序参数单一事实源。
+
+**落地**：文档层（Handoff / Plan 索引 / DevLog 时序）+ 知识层（v0.3.35 记忆闭环，全链条留痕）；开关 `ADD_MEMORY_RECALL_MODE` 默认 `shadow`（召回照跑照审计、暂不注入）。
+**如实登记**：Hybrid `MRR@5` 0.4867 < 0.75 门槛，门槛不下调，由排序校准线程以数据校准替代手调。
 
 ### ④ Policy-Update-Loop：治理自我进化
-```
-执行 → 审计 → 边界报告 → 规则调整 → 下一轮执行
-```
-运行时产生的 Report 会反过来更新 governance rules。
+
+> **静态模板会腐化，闭环治理会进化。**
+
+执行 → 审计（✓ 已接入：hook 拦截 / 文件写入 → jsonl → MCP 常驻消费 → DevOperation 幂等落库）→ 规则调整（✓ 已接入：caijuehub 改规则不改代码 · DPS FFT 自适应权重 · `check_doc_similarity` 量化复检）；边界报告（Runtime Report）端到端实践待 DEMO 仓库演示。
 
 ### ⑤ 多 IDE 的 Hook 即治理层
 | IDE | 治理文档 | 覆盖事件 | Hook 配置 |
 |---|---|---|---|
-| Claude Code | [ADD-governance-claude-code.md](./templates/core/docs/ADD-governance-claude-code.md) | 14/17 | `.claude/hooks/*.sh` |
-| Qoder CN | [ADD-governance-qoder-cn.md](./templates/core/docs/ADD-governance-qoder-cn.md) | 10/17 | `.qoder/hooks/*.sh` |
-| VS Code Copilot | [ADD-governance-vscode-copilot.md](./templates/core/docs/ADD-governance-vscode-copilot.md) | 10/17 | `.github/hooks/*.json` → `.vscode/hooks/*.sh` |
-| Trae | [ADD-governance-trae.md](./templates/core/docs/ADD-governance-trae.md) | 6/17 | `hooks.json` → `.trae/hooks/*.sh` |
-| Codex | [ADD-governance-codex.md](./templates/core/docs/ADD-governance-codex.md) | 0 (原生) / 14 (导入 Claude) | `.codex/hooks.json` |
+| Claude Code | [ADD-governance-claude-code.md](./templates/core/docs/ADD-governance-claude-code.md) | 11/16 | `.claude/hooks/*.mjs`（settings.json command） |
+| Qoder CN | [ADD-governance-qoder-cn.md](./templates/core/docs/ADD-governance-qoder-cn.md) | 11/16 | `.qoder/hooks/*.mjs`（settings.json command） |
+| VS Code Copilot | [ADD-governance-vscode-copilot.md](./templates/core/docs/ADD-governance-vscode-copilot.md) | 10/16 | `.vscode/hooks/*.mjs`（Agent Host 双通道） |
+| Trae | [ADD-governance-trae.md](./templates/core/docs/ADD-governance-trae.md) | 6/16 | `hooks.json` → `.trae/hooks/*.mjs` |
+| Codex | [ADD-governance-codex.md](./templates/core/docs/ADD-governance-codex.md) | 5/16 | `.codex/hooks.json` → `.codex/hooks/*.mjs` |
 
 ## 快速开始
 ```bash
@@ -318,7 +391,7 @@ npx add-coder init
 |---|---|
 | `record_dev_operation` | 记录开发操作审计 |
 | `query_audit_logs` | 按 planKeyword / targetId 查询审计记录 |
-| `check_dps` | DPS 闸门（< 85% BLOCKED） |
+| `check_dps` | DPS 闸门（`PASS=80`，阈值以 `dps-scoring-rules.toml` 为准） |
 | `check_rahs` | RAHS 闸门（< 90% BLOCKED） |
 
 ## 前置条件
@@ -329,7 +402,7 @@ npx add-coder init
 |---|---|
 | Demo 仓库演示 | Policy-Update-Loop 与 Report 体系端到端闭环实践 |
 | MCP 能力重构 | MCP 工具链架构升级 |
-| 对话记忆增强 | 长期项目知识记忆和 plan 级别的稀疏记忆 |
+| 对话记忆增强 | ✅ **v0.3.35 记忆闭环落地**：幂等采证 + 位点确定性召回 + FTS×向量混合召回 + Handoff Digest 候选 + 排序校准基座；默认 `shadow` 模式 |
 
 > 📦 [更新日志](./CHANGELOG.md)
 </details>

package/README.md

@@ -95,7 +95,18 @@ ADD 范式 + Qoder:     cache 命中率 99.31%, 每次请求 MISS 仅 2,426 toke
 
 ### ④ 门禁驱动，而非自由对话
 
-传统 AI coding 是「你说我做」，质量完全依赖 LLM 当天状态。add-coder 在架构中嵌入了 **双质量闸门**，不是「建议」，是**架构阻断**：
+> **别的工具靠「再试一次」，add-coder 靠「先过闸门」。** 质量不该取决于模型当天的状态。
+
+传统 AI coding 是「你说我做」，质量完全依赖 LLM 当下的发挥。add-coder 在架构里嵌入**双质量闸门**——不是「建议」，是**架构阻断**：不过闸门，Step 推进不了。
+
+| 维度 | 常见做法 | add-coder 双闸门 |
+|------|---------|------------------|
+| **判据** | 模型自评 / 人工肉眼 | **DPS**：语义（TF-IDF/Jaccard）+ 熵（香农/Deng）+ CPM 关键路径 + 结构完整度四维复合；**RAHS**：范围保真 / 类型安全 / 审计完整 / Spec 合规 / 阶段对称五维 |
+| **强制力** | 提示词里的「请确保…」 | 未过 DPS（`PASS=80`，阈值以 `dps-scoring-rules.toml` 为准）进不了 Step 1；未过 RAHS（≥90）不放行 |
+| **可复现** | 每次问模型答案都不一样 | 同一文档 + 同一参数 = 同一分数；分维分值 + 弱项清单，可解释、可对比、可回归 |
+| **调参** | 改代码、改提示词、重发版 | **caijuehub TOML 声明**：跑分 → 看弱项 → 调参 → 再跑分，改规则不改代码 |
+| **权重** | 手调一次就固化 | **FFT 自适应权重**：随审计数据演进——DPS 参数是数据，不是魔数 |
+| **负反馈** | 只能「再生成一遍」 | 门禁失败直接定位弱项维度；门禁结果幂等采证（Gate → `MetricSnapshot`）进入记忆闭环复盘 |
 
 ```
 DPS (Documentation Precision Score) — TF-IDF/Jaccard 语义 + 香农/Deng 熵 + CPM 关键路径 + 结构完整度
@@ -104,29 +115,54 @@ RAHS (Runtime Architecture Health Score) — 运行时架构健康度
   → 五维判定：范围保真 + 类型安全 + 审计完整 + Spec 合规 + 阶段对称，≥ 90 通过
 ```
 
-DPS 全部参数由 caijuehub TOML 驱动——AI 可以跑分→看弱项→调参→再跑分，全程不改代码。
+> 阈值与参数都是可读的 TOML 真源（`dps-scoring-rules.toml`），不是魔数；`check_dps` 已适配五端 spec 引用解析（qoder / claude / add / vscode / codex·trae，`tests/dps-adapter.test.ts` 覆盖）。
 
 ### ⑤ 跨轮记忆，而非每轮失忆
 
-AI 对话的致命缺陷：上次讨论的架构决策、已修复的 Bug、达成的约定，下轮对话全部遗忘。add-coder 在架构层面解决：
+> **别的工具在「记」，add-coder 在「治理记忆」。** 记忆不是上下文工程，是治理工程。
+
+AI 对话的致命缺陷：上次讨论的架构决策、已修复的 Bug、达成的约定，下轮对话全部遗忘。多数 AI 编码工具的「记忆」是**会话/仓库级文本摘录 + 向量检索**——把历史对话或文件切片塞回上下文，解决的是「看过」，不解决「算不算数、该不该带、带错了谁负责」。add-coder 的记忆是**受治理的知识层**：每条结论有证据、每次召回可重放、每次修订留痕迹、每次越界可抽查。
+
+**差距在结构，不在召回率**
+
+| 维度 | 常见「记忆」做法 | add-coder 记忆闭环（v0.3.35 起） |
+|------|------------------|-----------------------------------|
+| **写入** | 自动摘录，直接生效 | **候选制**：`propose_memory` 落 CANDIDATE（去重 + 密钥扫描 + 冲突检测），人工裁决 `resolve_memory` 后才 ACTIVE，approve 需 ≥1 条证据 |
+| **依据** | 记忆文本本身即依据 | **证据链**：结论与来源分离，采证幂等（`sourceRef=<gate>:<planKeyword>:<runId>`，重放不重复入库），`get_memory` 可查 provenance 与 supersession 链 |
+| **时机** | 相似度触发，随时可能召回 | **位点确定性召回**：命中 ADD 阶段位点（Plan 起草 / Spec 起草 / DPS / RAHS / Handoff）才触发，词表按特异性优先；Hook 侧同步产出、MCP 侧执行 |
+| **召回** | 单通道向量相似度 | **FTS × 向量双通道 RRF 融合 + 治理重排**（scope / kind / 重要度 / 置信度 / 强约束 − stale / 冲突 / 冗余），token 预算裁剪后注入 |
+| **可解释** | 只给结果 | 每条结果带 `whySelected` / `scoreBreakdown` / `recallId`，`rankingVersion` 记录配置快照——**同一次召回可以重放** |
+| **降级** | 无显式契约 | 无 pgvector / sqlite-vec 环境按 FTS-only 运行并显式返回 `degradedMode`，不静默失真 |
+| **纠错** | 只能删或覆盖 | **治理状态机**：submit_review / approve / reject / stale / supersede / archive / restore，supersede 强制 scope 兼容——记忆可以「被证伪」，不是只能被覆盖 |
+| **越界** | 无 scope 隔离 | 八级 scope 隔离（ORGANIZATION / REPOSITORY / BRANCH / MODULE / PATH / SYMBOL / PLAN / SPEC）+ `get_memory_health` 越库泄漏抽查 |
+| **调权** | 权重写死 | 反馈统计（通道 × 位次 × outcome）/ 冷启动拟合 / Kalman 在线估计 / FFT 节奏诊断（不直接产出排序）；**权重快照即排序参数单一事实源** |
+
+**两层落地**
+
+- **文档层**（v0.3.25 起）—— Handoff 文档（每轮 Session 结束自动生成、下轮自动加载）· Plan 索引（`index.md` 集中索引 + 模糊匹配）· DevLog 时序（`{YYYY-MM}/{DD}/` 全量可回溯）
+- **知识层**（v0.3.35 记忆闭环）—— 候选制入库 → 幂等采证（白名单工具事件 → `evidence-queue.jsonl` → 异步消费 → `MetricSnapshot`）→ 位点召回 → 混合召回 + 治理重排 → 反馈回流校准，全链条留痕
+
+**开关**：`ADD_MEMORY_RECALL_MODE=off|shadow|inject`（默认 `shadow`：召回照跑照审计、暂不注入上下文）· `ADD_MEMORY_MAX_TOKENS`（默认 600）· `ADD_MEMORY_EVIDENCE`（默认 `on`）。
 
-- **Handoff 文档** — 每轮 Session 结束时自动生成结构化交接文档，下轮会话自动加载
-- **Plan 索引** — 所有 Plan 通过 `index.md` 集中索引，支持模糊匹配快速定位
-- **DevLog 时序记录** — 每一步操作写入 `{YYYY-MM}/{DD}/` 时间轴，可回溯任意历史状态
+> 如实登记：Hybrid `MRR@5` 实测 0.4867 < 0.75 门槛（FTS-only 0.6551、Recall@5 0.9592）——**门槛不下调**，由排序校准线程以数据校准替代手调：记忆能力可跑、可查、可裁决，不靠指标注水。
+> 真源落点、表结构、开发流程见 [DEVELOPMENT.md](./DEVELOPMENT.md) §十七。
 
 ### ⑥ Policy-Update-Loop：治理自我进化
 
-不是静态模板，而是**闭环自适应系统**：
+> **静态模板会腐化，闭环治理会进化。** 规则不是写死的常量，是能被审计数据推动的参数。
 
 ```
 执行 → 审计 → 边界报告 → 规则调整 → 下一轮执行
 ```
 
-**已落地的闭环环节**：
-
-- **执行 → 审计（✓ 已接入）**：hook 拦截 / 文件写入事件 → jsonl → MCP 常驻消费 → DevOperation 落库（`HOOK_INTERCEPT`，幂等去重）——每个治理动作自动留痕，可回查可追溯
-- **审计 → 规则调整（✓ 已接入）**：caijuehub 规则中心改规则不改代码——DPS 四维评分 **FFT 自适应权重**（随历史数据自动调权）、`check_doc_similarity` 量化复检（形似义异文档自动识别）——审计数据驱动治理规则演进
-- **边界报告（Report 体系）**：Runtime 边界报告闭环待 DEMO 仓库演示——Policy-Update-Loop 与 Report 体系端到端实践
+| 维度 | 静态规则 / 模板 | add-coder Policy-Update-Loop |
+|------|----------------|------------------------------|
+| **规则载体** | 写死在代码与提示词里，改动要发版 | caijuehub TOML 声明式：规则真源 → 生成常量 → 产物内联，**改规则不改代码** |
+| **规则来源** | 拍脑袋定阈值 | 审计数据反哺：DPS 四维 **FFT 自适应权重**随历史调权；`check_doc_similarity` 量化复检形似义异文档 |
+| **反馈回路** | 无 | **执行 → 审计（✓ 已接入）**：hook 拦截 / 文件写入事件 → jsonl → MCP 常驻消费 → DevOperation 落库（`HOOK_INTERCEPT` 幂等去重） |
+| **一致性** | 各端各自实现，行为漂移 | 治理契约层单一实现 + 五端一致性矩阵逐项断言（危险命令拦截 / 敏感文件锚定 / 审计事件面 / 协议形态 / 治理零复制） |
+| **演进证据** | 无留痕 | 每次拦截、每次判分、每次裁决都进审计库——可回查、可统计、可复算 |
+| **尚未闭环** | — | 边界报告（Runtime Report）端到端实践待 [DEMO 仓库](#-预告)演示（如实登记） |
 
 ### ⑦ 多 IDE 的 Hook 即治理层
 
@@ -185,7 +221,16 @@ tasks.md §IDE JSON → TodoWrite → IDE 面板
 
 ### ⑪ Codex MCP 原生接入（v0.3.25）
 
-> **状态区分**："已生成 Codex 模板" ≠ "Codex MCP 端到端已验证"——以下 6 步是**已验证闭环**，不写自定义脚本即可完成接入。
+> **不是给 Codex 外挂一个 MCP，而是把治理原生落进去。** 「已生成模板」≠「端到端已验证」——以下是**实测打通的 6 步**。
+
+| 维度 | 常见接入方式 | add-coder × Codex |
+|------|-------------|-------------------|
+| **接入成本** | 手写启动脚本、自己包装 | 三步 CLI：`init --adapter=codex` → `--print-mcp-config`（不写盘、不初始化项目）→ 粘贴或 `--write-user-config`（先备份 + 防重复） |
+| **治理面** | 只有工具调用，没有生命周期治理 | **原生 hooks**：`.codex/hooks.json` → `.codex/hooks/*.mjs`（14 个入口产物随包预烘焙、`node` 直调；Codex 原生事件可注册 5/16，其余产物已占位，事件扩展后零代码启用） |
+| **审批** | 只能在聊天里问一句 | **HITL 原生**：`create_hitl` 走 MCP Apps 分流（不在 Codex 展开高维 `inputRequired`），面板不可用时回退 markdown 提案 + 实例 HTML，结论照常落库 / 落文档 |
+| **运行态** | 改完产物，不知道跑的是不是新码 | **产物-进程新鲜度四态** + 重启标记 `.mcp-restart-required`：`sync` 后点名告警该重启哪个 server |
+| **多项目** | 配置粘错就连错库且无感 | `env.PROJECT_ROOT` 渲染时注入；错配时 mcp-server 启动即校验退出（进程层契约 §4） |
+| **平台** | 依赖 WSL / 手工改路径 | win32 自动输出 `cmd /c npx.cmd` 原生分支（PowerShell 场景不再绕 WSL） |
 
 ```bash
 # 1. 安装 add-coder（已安装可跳过）
@@ -206,9 +251,9 @@ add-coder init --adapter=codex --write-user-config
 # 6. 验证：Codex 中发现 add_coder MCP Server，完整工具集可调用（29 tools）
 ```
 
-**Windows 分支**：`--print-mcp-config` 在 win32 平台自动输出 `cmd /c npx.cmd` 启动分支（原生 PowerShell 场景，不依赖 WSL）。
+**命名兼容**：MCP Server ID 归一化为 `add_coder`（连字符→下划线，Codex 约束）。
 
-**命名兼容**：MCP Server ID 归一化为 `add_coder`（连字符→下划线，Codex 约束）；`env.PROJECT_ROOT` 由渲染时注入，多项目粘贴错误配置时 mcp-server 启动即校验退出（进程层契约 §4）。
+> 如实登记：Codex 部分 build（实测 `26.908`）不渲染审批 widget，此时审批走 markdown 提案 + 实例 HTML + 聊天拍板——链路可用，结论照常落库 / 落文档。
 
 ---
 
@@ -436,7 +481,7 @@ Tasks (实验性)     双向              ✅ 已实现      长任务持久化
 > **推荐**：使用 Podman/Docker 运行 PostgreSQL，参考配置：
 > ```yaml
 > postgres:
->   image: docker.io/postgres:16-alpine
+>   image: docker.io/pgvector/pgvector:pg16
 >   ports: ["127.0.0.1:5433:5432"]
 >   environment:
 >     POSTGRES_DB: <your-db>
@@ -454,10 +499,10 @@ Tasks (实验性)     双向              ✅ 已实现      长任务持久化
 | 计划 | 说明 |备注|
 |------|------|------|
 | Demo 仓库演示 | 提供完整示例仓库，展示 Policy-Update-Loop 与 Report 体系的端到端闭环实践 |--|
-| MCP 能力重构 | ✅ v0.2.9 MCP 工具链架构升级，提升审计与门禁工具的可扩展性和独立部署能力 | 2026-07/23/add-coder-mcp-restructure-plan-v1.md |
-| Hook 通知升级 | ✅ v0.2.9 Hook 拦截事件 jsonl → fs.watch → record_dev_operation 落库 + Notification + 治理信号 | 2026-07/24/add-coder-hook-notify-upgrade-plan-v1.md |
+| ~~MCP 能力重构~~ | ✅ v0.2.9 MCP 工具链架构升级，提升审计与门禁工具的可扩展性和独立部署能力 | 2026-07/23/add-coder-mcp-restructure-plan-v1.md |
+| ~~Hook 通知升级~~ | ✅ v0.2.9 Hook 拦截事件 jsonl → fs.watch → record_dev_operation 落库 + Notification + 治理信号 | 2026-07/24/add-coder-hook-notify-upgrade-plan-v1.md |
 | ide插件 | 解耦ADD范式代码和被治理项目的代码 |在做了,大家拭目以待吧,让编程更有趣,我的目标其实不在于IDE,我的工作顺手的事情 |
-| 对话记忆增强 | 长期项目知识记忆和plan级别的稀疏记忆 |--|
+| ~~对话记忆增强~~ | ✅ **v0.3.35→v0.3.37 记忆闭环落地**：幂等采证 + 位点确定性召回 + FTS×向量混合召回（RRF 融合 + 治理重排）+ Handoff Digest 候选 + 排序权重校准基座；默认 `shadow` 模式（召回照跑照审计、暂不注入）；v0.3.37 起原生层（SQLite FTS5 虚表 + 触发器）由 init/db-ensure 自动应用，`memory:reindex` 自助修复 | 门槛未下调：Hybrid MRR@5 0.4867 < 0.75，由校准线程以数据逼近 |
 
 ---
 
@@ -905,7 +950,7 @@ npx add-coder stack --clear       # clear tech-stack setting (neutral)
 > **Recommended**: Run PostgreSQL via Podman/Docker, reference config:
 > ```yaml
 > postgres:
->   image: docker.io/postgres:16-alpine
+>   image: docker.io/pgvector/pgvector:pg16
 >   ports: ["127.0.0.1:5433:5432"]
 >   environment:
 >     POSTGRES_DB: mydb
@@ -925,10 +970,24 @@ npx add-coder stack --clear       # clear tech-stack setting (neutral)
 | Demo Repo | Full example repository showcasing Policy-Update-Loop with Report system end-to-end | 📋 |
 | ~~MCP Restructure~~ | ✅ v0.2.9 3,467-line monolith → 27 modules covering all six MCP primitives | 2026-07/23/... |
 | ~~Hook Notification Upgrade~~ | ✅ v0.2.9 ~36 files: hook intercept → jsonl → fs.watch → record_dev_operation | 2026-07/24/... |
-| Memory Enhancement | Long-term project knowledge memory and plan-level sparse memory | 📋 |
+| ~~Memory Enhancement~~ | ✅ v0.3.35→v0.3.37 **Governance memory**: idempotent evidence collection + deterministic waypoint recall + hybrid FTS×vector recall (RRF fusion + governed rerank) + Handoff Digest candidates + ranking-calibration foundation; SQLite FTS5 native layer auto-applied by `init`/`db-ensure` + `memory:reindex` self-heal; defaults to `shadow` mode | 2026-09/15/... |
 
 ---
 
 My hometown 
 
 <img width="720"  alt="hometown outside" src="https://github.com/user-attachments/assets/7aad93de-9cea-4194-b09d-cbd892d61cc2" />
+
+---
+
+## 🙏 致谢 / Acknowledgements
+
+范式的价值来自把它用出问题的人。**贡献者墙**见 **[CONTRIBUTING.md §贡献者墙](./CONTRIBUTING.md#-贡献者墙)**，逐项明细与证据见 **[docs/ACKNOWLEDGEMENTS.md](./docs/ACKNOWLEDGEMENTS.md)**。
+
+| 贡献者 | 贡献形态 | 留下了什么 |
+|--------|---------|-----------|
+| [@iopzhu](https://github.com/iopzhu) | 记忆轮动（`memory_cache` 分支 `357b215`，48 文件 / +5877 −33） | 记忆闭环的检索层与工具层主体：`retrieval/pipeline`、RRF 融合、治理重排、FTS 双通道、采证与快照作业、`tools/memory.ts`（609 行）+ 评测标注集（909 行） |
+| [@Milkycoffees](https://github.com/Milkycoffees) | 生态贡献：[`add-coder-flash`](https://www.npmjs.com/package/add-coder-flash)（npm `1.0.4` / 5 个版本 + [GitHub 开源](https://github.com/Milkycoffees/add-coder-flash)） | 零依赖轻量发行版：hooks 纯 `.mjs`、不需要数据库，`npm install` 即铺设；自动生成 `.qoder-cn/mcp.json`，并回吐 QoderCN 加载位置、pnpm `allowBuilds`、MCP 名长度等真实约束 |
+| [@albertm88](https://github.com/albertm88) | 持续输出 issue（#5–#7、#10–#20，14 条全部闭环） | 跨会话记忆、429 并发、Windows 稳定性、Codex 原生适配、端口漂移、非交互挂起、HITL 首次审批……把边界条件替所有人先踩了一遍 |
+
+> 想上墙？上榜标准在 [CONTRIBUTING.md §贡献者墙](./CONTRIBUTING.md#-贡献者墙)——提 [Issue](https://github.com/xiaomingming92/add-coder/issues)（可复现的问题、实测日志、平台差异）或 [PR](https://github.com/xiaomingming92/add-coder/pulls) 都算硬贡献。