dsh-plugin-teamflow 0.1.0

package/docs/adr/0006-cognition-architecture-rework.md

@@ -0,0 +1,67 @@
+# ADR-0006：流水线「认知前置 + 架构落地」重构（质量优先于 token）
+
+- 状态：已接受（Accepted）
+- 日期：2026-08（v0.1.0）
+- 关联：`host/core/sanity.ts`（新）、`host/core/pipeline.ts`、`host/core/state.ts`、`host/core/triage.ts`、`host/util.ts`、`host/prompts/index.ts`、`store.ts`
+
+## 背景
+
+对同一持久化需求的 A/B 实测（见 `docs/benchmarks/pipeline-vs-native.md`）暴露根本问题：
+- **功能等价 ≠ 代码质量等价**。流水线 dev 输出 game.js/audio.js 两套几乎重复的 safeStorage 适配器、键名分散；原生 DSH 输出独立 storage.js + PERSIST_DEFS 单一事实来源 + verify-storage 专测。
+- 根因不是「流水线 vs 原生」，而是流水线**跳过了「建全局认知 → 架构决策」**：TOKEN_HYGIENE 让 dev「只读任务内文件」，state 只传"结论摘要"不传"架构蓝图" → dev 在无全局视野、无设计引导下散落实现。
+
+原生工作流实证（`docs/benchmarks/native-workflow.md`）：原生高质量 = 环境探索 → 全局 READ → **Design Decision** → 基线验证 → 实现，**次序不可跳过**。而流水线为省 token 压掉了这个自然涌现。
+
+DSH 无内置"认知构建"机制（standard preset persona 只有一句身份；仅 plan-mode 有 "Explore first"）。所以流水线**必须显式化**这套认知流程，不能指望模型自觉。
+
+## 决策
+
+### 三情况协议（认知传递的总原则）
+- 情况一（全新会话 0 认知）：读索引减量 + 定向精读，建认知。
+- 情况二（续会话）：**默认认知已过期**（多人/场外提交/非流水线改动）→ 先状态核对再复用。
+- 情况三（新会话处理新需求）：共用 state/记忆减量 + 轻量核对现状。
+- 核心：**认知资产可复用"减量"，但永不能替代"对代码库当前真实状态的核对"**。
+
+### M0 状态核对（`core/sanity.ts`）
+- `executePipeline` 开头（PRD 前）host 侧直接跑 `git branch/status/log`，产出 `externalDiffs` 摘要。
+- 注入所有后续阶段 prompt（经 `state.__runCtx.sanity`，`stateSliceFor` 统一渲染）。
+- 持久化到 `journal.sanity`（审计）。失败优雅降级为"无法核对"，不阻断流程。
+
+### M1 架构阶段全模式启用
+- `lite/tech/patch` 不再跳过技术/架构阶段——改为**轻量架构蓝图**（`architectPrompt`，只产蓝图 JSON，不写文档）；`full/medium` 由 `techPrompt` 产蓝图 + 完整文档。
+- `architectPrompt` 明确**允许整文件 read 关键源文件**（豁免 TOKEN_HYGIENE「别整读」——架构决策需要全局视野），先读状态核对，再建全局认知，最后输出结构化蓝图。
+- 架构蓝图 = `<!-- blueprint -->{json}<!-- /blueprint -->` 块，host 用 `extractBlueprint` 解析，`render` 注入 `state.__runCtx.blueprint`。
+
+### M2 dev 继承蓝图 + 自动拆任务
+- `devPrompt` 注入架构蓝图，契约升级为"按蓝图在既有架构上实现"，允许小范围核实（不整读）。
+- dev 任务来源优先级：**蓝图 tasks（架构师自动拆，按文件边界）> 调用方 tasks > 整体开发**。
+- 冲突检测：蓝图任务 files 有交集 → 合并（保证并发不写同一文件）；无交集才并行。
+
+### M3 质量门禁
+- QA/验收 prompt 加「架构核验」：核对是否遵循蓝图、有无重复实现/适配器漂移/该抽象未抽象。
+- `parseAcceptanceVerdict` 扩展：命中架构打回信号（架构返工/重复实现/偏离蓝图/该拆未拆/该抽象未抽象/破坏既有结构）→ `rework`，即使结论行写"通过"。
+- 验收不再是"verify 全绿即通过"；架构偏离 → 有条件通过（返工）或打回。
+
+### triage 配套
+- SIGNALS 增架构性词（持久化/localStorage/存储/独立模块/抽象/跨模块等）。
+- 架构护栏：命中架构性信号且判 lite/tech/patch → **强制 medium**（必须有架构阶段）。
+- TRIAGE_PROMPT 增第 5 条架构判据。
+
+## 理由（质量优先于 token）
+
+- **代码质量是生产底线**：不能为省 token 放弃架构。省 token 的正确方式是把建认知+出设计做成**一次共享**（tech→蓝图→dev 继承），而不是让每个 dev 各读一遍（重复）或都不读（没认知）。
+- 让「架构阶段」全模式存在，是把原生工作流最值钱的「全局读 → Design Decision」固化成一个真实阶段 + 一种共享数据（蓝图）。
+- 验收加架构门禁，把"防重复/防散落"变成可判定的门禁，而非靠各 agent 自觉。
+
+## 影响
+
+- lite 语义变化：仍跑轻量架构阶段（产蓝图不写文档）；triage 对架构性需求强升 medium。
+- dev 任务可能被蓝图自动拆解（架构性需求不再退化为"整体开发"单任务）。
+- 验收更严格：架构偏离会打回（首次可能增多返工，但这是质量投入）。
+- `journal.sanity`/`journal.blueprint` 新增字段；`state.__runCtx` 为运行时注入（不持久化）。
+
+## 后续
+
+- 用「持久化」类需求重跑，验证：M0 状态核对注入、M1 蓝图产出、M2 dev 按蓝图拆任务、M3 验收架构核验效果。
+- full/medium 阶段集差异执行仍待做（ADR-0004 §影响）。
+- 认知传递的更深层（如共享向量/结构化知识）依赖 DSH 未来能力，当前用"蓝图 + 状态核对"显式化已覆盖根因。

package/docs/adr/0007-qa-rework-loop.md

@@ -0,0 +1,65 @@
+# ADR-0007：QA 发现缺陷 → 打回开发修复 → 复验 → 干净才验收（有界循环 + 人工兜底）
+
+- 状态：已接受（Accepted）
+- 日期：2026-08（v0.1.0）
+- 关联：`host/core/pipeline.ts`、`host/core/backlog.ts`、`host/constants.ts`、`host/prompts/index.ts`、`test/smoke.js`
+
+## 背景
+
+对照实验 run `tf-mt317a5e-0iwvuy`（干净分支 feat/persistence-localStorage2，tech 档）实测暴露两个流程缺陷：
+
+1. **QA 发现的缺陷没有被解析**。QA 报告缺陷行按 markdown 加粗写严重级（`| BUG-P1-1 | **P1** | …`），
+   `parseDefects` 旧正则是 `(P[0-3])\s*\|`，要求严重级后**紧跟管道符** → `**P1**` 匹配失败 → 缺陷 0 条。
+   于是日志记录「QA 未发现 P0/P1/P2 缺陷（未登记 Bug）」，任务静默进入 `pending-acceptance`。
+2. **没有 QA→开发 打回闭环**。即使解析出缺陷，旧逻辑也只是登记 bug 后照样进产品验收；
+   QA 的负向结论要等到验收（PM）再拦一次（本次是资深 PM 源码复核拦下的），
+   既浪费一次验收调用，也让「QA 报告已给出可执行缺陷」的事实被流程白白放过。
+
+用户反馈明确要求：QA 发现缺陷 → **打回开发确认是否属实 → 属实则直接修复 → 复验 QA →
+QA 干净才到产品最终验收**；该循环需**限制轮次上限**（防无限循环），超限才转人工介入。
+
+## 决策
+
+### 1. 修复缺陷解析（`backlog.ts` `parseDefects`）
+- 改为按管道单元格解析：容忍 markdown 加粗（`**P1**`）、反引号、行首 `|` 偏移；不再要求固定列数。
+- 只认「三要素齐全（id / P0-P3 严重级 / 模块）+ 非表头 + 非 OBS」的行 → 真实缺陷（含 `**P1**`）必被解析。
+- 语义保持不变：P0/P1/P2 = 阻断缺陷；P3 = 观察项（非阻断）。
+
+### 2. QA→开发→复验 有界闭环（`pipeline.ts`）
+- QA 阶段改为 `do…while` 循环，最多 `1 + QA_REWORK_LIMIT` 轮：
+  - 第一轮：常规 QA（label「QA 测试工程师 · 功能测试」）。
+  - 解析缺陷 → 阻断缺陷（P0-P2）> 0：
+    - 未超上限 → `advanceTask('rework')`，启动开发修复子代理（新 prompt `qaFixPrompt`，
+      指令「**先确认缺陷是否属实 → 属实在既有架构上修复 → 交还复验**」，防"修错/臆造/无视误报"）。
+    - 修复摘要拼接进下一轮 QA 的开发结果上下文 → 复验（label「QA 复验 · 第N轮修复后」）。
+    - 复验无阻断缺陷 → `verifyReqBugs` 关单 + `advanceTask('pending-acceptance')` → 进入产品验收。
+- **QA 干净是进产品验收的充分条件**：验收块由 `if (!qaBlocked)` 门控；QA 不干净绝不自动跑验收，
+  杜绝「QA 报告已列缺陷 → 还进验收 → 验收再打回」的浪费。
+
+### 3. 轮次上限 + 人工兜底（`constants.ts` / `pipeline.ts`）
+- `QA_REWORK_LIMIT = 2`：最多 2 轮「打回开发修复 + 复验」；配合首轮共 3 次 QA 执行，防无限循环。
+- 超限 → `qaBlocked = true`：task/req 置 `needs-human`、`humanIntervention = true`、
+  日志明示「超出复验上限，需人工介入」，跳过产品验收，流水线以需人工收尾。
+
+### 4. 缺陷单幂等 + 关单（`backlog.ts`）
+- `syncQaDefects`：按 `reqId + defectId` 幂等登记（多轮复验同一缺陷不重复建卡，只刷新严重级/状态）。
+- `verifyReqBugs`：QA 复验通过 / 验收通过时，关闭该需求全部 open 的 P0-P2 缺陷（P3 观察项保留）。
+- 验收通过分支复用 `verifyReqBugs`（原「存在未关闭缺陷 → pending-acceptance」逻辑中避免遗留僵尸 open 单）。
+
+## 理由
+
+- **QA 是第一质量门禁**：它的负向结论应当驱动最近的正向反馈环（开发修复），而不是被推给下一阶段的验收。
+- **有界性是必须的**：无限复议 = 无限 token 烧毁 + 任务无终止；上限处转人工，让"工具化复盘"让位于"人的判断"。
+- 与 ADR-0006 一脉相承：M3 门禁管"验收拦截"，本 ADR 管"QA 打回后快速自愈"，两处都不可省。
+
+## 影响
+
+- QA 阶段可能多次执行（最多 3 轮），token/调用数上升是**可预期成本**，换取「缺陷在 QA 内闭环」。
+- `advanceTask('rework')` 现用于 QA 打回（此前仅验收 rework 用）；任务卡状态机本就含 `rework`，无需扩展。
+- `parseDefects` 行为收紧：表头/观察项/非管道行不再可能被误认作缺陷。
+- run 日志可见「QA 打回开发修复（第 N/N+1 轮）」「QA 复验通过（第 N 轮修复后）」等新阶段轨迹。
+
+## 后续
+
+- 用「持久化修复」类需求实测一条完整打回链：QA 报 P1 → 开发修复 → 复验通过 → 验收 ✅，验证闭环行为与 token 成本。
+- 观察超限打回（needs-human）的人工介入路径是否顺畅（`teamflow_update`/认领后重跑）。

package/docs/adr/0008-task-folder-docs.md

@@ -0,0 +1,103 @@
+# ADR-0008：文档层重构——活文档版本制 → 任务夹收口制（日期+需求+slug，历史不可变）
+
+- 状态：已接受（Accepted）
+- 日期：2026-08（v0.1.0）
+- 关联：`host/core/pipeline.ts`、`host/core/triage.ts`、`host/core/state.ts`、`host/core/backlog.ts`、`host/core/sanity.ts`、`host/prompts/index.ts`、`host/constants.ts`、`store.ts`、client 展示层、全部 smoke 断言
+
+## 背景
+
+现行文档层是「活文档 + 版本切片」模型：PRD/TECHNICAL/QA 等固定在 `docs/teamflow/{prd,technical,qa}/` 单一路径，
+每次迭代先 mv 旧版到 `history/v<旧版本号>/` 再写新版，靠 prompt 纪律约束模型执行。实测暴露四类结构性缺陷：
+
+1. **双归档升版**（实锤 tetris）：阶段重试或断点续跑重入 PRD 阶段时，把自己上次的产物当「旧版」再归档一次，
+   版本号凭空 +1——已用「防双归档」prompt 补丁缓解，但补丁是概率性的。
+2. **memory.md 段落堆积**（实锤 8 段「当前迭代记忆」并存）：「更新记忆」语义模糊导致追加而非替换，
+   多段自称"当前"，版本互相矛盾——同样只能靠 prompt 补丁。
+3. **全局串行版本假设脆弱**：v2.* 隐含"所有变更排一条时间线"。多人并行、场外改动（不走流水线的功能）、
+   多分支开发任一发生，版本号即失真。tetris 三模块代码头 2.3.0/2.3.0/2.6.0 与文档 v2.9 三方漂移即实证。
+4. **并行分支合并冲突**：两个分支各自迭代必然改同一份 PRD.md 的同区域（修订表/AC 清单）+ 同一份 memory.md
+   ——文档层合并冲突在活文档模型下是结构必然而非偶然。
+
+根因判断：**版本号是隐含全局锁的共享可变状态；归档是依赖模型自觉的写时动作**。两者都违背
+「结构保证优于提示词恳求」原则（与 ADR-0007 同一哲学）。
+
+## 决策
+
+### 1. 任务夹 = 需求级档案单元
+
+```
+docs/teamflow/
+├── 20260825-r8-wallkick-toggle/   ← 任务夹（建后不可变；阶段重试/断点续跑复用同夹）
+│   ├── meta.json                  ← host 写：{reqId,runId,title,slug,mode,createdAt} 静态标识卡（建夹即定；status/endedAt 权威在 runs/<runId>.json journal，不落 meta——终态回写已废：避免「提交后再脏」与 run 误判时快照过时）
+│   ├── PRD.md                     ← 模型写：meta 头 + 基线声明/取代声明 + 本地 AC 编号(AC-1..n)
+│   ├── DESIGN.md / TECHNICAL.md   ← 按档位出现（needDesign/非 lite），不再归档
+│   ├── QA-REPORT.md
+│   └── ACCEPTANCE.md              ← 验收报告进夹（废除独立 acceptance/ 目录）
+├── memory.md                      ← 收窄为产品约定层（技术栈/团队规矩），低频幂等更新
+└── （SUMMARY.md 废除：由 host 扫描各夹 meta.json 聚合，工作台渲染）
+```
+
+- 命名 `<yyyyMMdd>-r<N>[-<slug>]`：日期=需求创建日；`r<N>` 为 reqId 序号（防撞兜底，triage 无 slug 时退化
+  为 `20260825-r9/`）；slug 由 triage 新增输出（正则 `[a-z0-9-]{3,24}` 校验，非法降级）。
+- **身份 = reqId**：夹名在建夹时刻固定并持久化到 `journal.runDocs`；重试、续跑、隔天重跑一律复用同夹
+  ——幂等性由「夹已存在直接复用」的结构规则保证，不再依赖模型自觉。
+
+### 2. 共享写点清零策略
+
+| 旧共享写点 | 新方案 |
+|---|---|
+| prd/PRD.md（每分支必改） | 各分支写各的任务夹，路径不相交 |
+| memory.md 当前迭代段落 | 「当前迭代」制度废除——迭代细节天然在夹内；memory 收窄为约定层 |
+| SUMMARY.md 登记表 | 废除静态文件：host 扫描 meta.json 聚合，工作台按需渲染 |
+
+memory.md 仅在真正新增团队约定时追加一行（幂等：同主题替换），写入频率从每迭代一次降到偶发。
+
+### 3. 回归基线：局部编号 + 显式指针 + 硬保障在代码层
+
+- AC 编号回归需求本体（夹内 AC-1..n），废除全局账本（中央登记表会重新引入共享写点）。
+- 新 PRD 头部两行声明：
+  - `基线依赖：<其他任务夹名列表>（其既定行为不得回退）`
+  - `取代：<某夹>#AC-n（语义变更说明）`——历史夹永不改动；查最新真相 = 按日期倒序找最后一条取代链。
+- 回归的硬保障仍是项目 verify-* 可执行套件（本就不依赖文档编号）；QA 阶段照旧全量运行。
+
+### 4. host/model 职责切分：结构归 host，内容归 model
+
+- host：建夹、命名、meta.json 静态标识卡（建夹一次写入，无终态回写）、journal.runDocs/state.__runCtx 注入；动态状态（status/endedAt）唯一权威 = runs/<runId>.json，目录聚合扫描时以 journal 为准。
+- model：只写自己夹内的产物文件；对索引零写入权。PRD 头部输出一行机器可读 meta
+  （`<!-- meta: summary="…" -->`）供未来聚合使用（YAGNI：本轮不做解析消费）。
+
+### 5. 代码头 VERSION 解耦
+
+devPrompt 明确：模块头部 VERSION 是发布版本，仅对外发版时升位；流水线迭代不碰。
+（修复 game.js 2.3.0 型漂移的再发——迭代计数器不得误植进代码。）
+
+### 6. 存量过渡：零迁移
+
+旧 `prd/`、`technical/`、`history/`、既有 SUMMARY.md 原样留存（历史可追溯性不受影响）；
+新需求自然落新夹。项目侧 verify 脚本的文档路径断言由项目自行调整（不在插件范围）。
+
+## 理由
+
+- **结构消灭 bug 类别**：双归档/版本虚增/memory 堆积的全部前提是「固定路径上的覆盖式写入」；
+  任务夹让该前提取消，prompt 补丁（防双归档条款等）随之整体删除而非叠加。
+- **容忍乱序与旁路**：日期命名不假设任何全局顺序；场外改动、多分支、多团队并行都不再使任何计数器失真。
+- **审计单元对齐心智**：「一个需求的所有产物在一个文件夹」与 backlog req/task、journal run 天然一一对应；
+  review/回滚/交接以文件夹为单位。
+- **已有先例**：`logs/teamflow/<runId>/` 早已是 per-run 收口模式，docs 对齐反而统一。
+- **resume 不受影响**：断点续跑的产物重建走 journal stage.output 全文，不依赖文档路径——改造影响面收敛在
+  prompt 注入与展示层。
+
+## 影响
+
+- 全部 10 个 prompt 的路径注入改为 `TF_RUN_DOCS`（本任务夹）+ `TF_PRODUCT_DOCS`（memory 层）两个变量。
+- triage 输出协议扩展 `slug` 字段（向后兼容：缺省为空）。
+- state.json `product.currentVersion` 废弃，改记 `lastRunFolder`。
+- client 文档引用路径跟随 journal.runDocs；目录浏览器不做（YAGNI）。
+- smoke 断言大改：删除版本切片/mv 归档/防双归档族断言，新增 runDocs 注入/meta.json/命名格式断言。
+- 单 commit 可整体回滚；运行中流水线不受影响，重启宿主生效。
+
+## 后续
+
+- 用下一条真实需求实测完整生命周期：建夹命名 → 各阶段产物落位 → 续跑复用同夹 → 验收后由 runs/<runId>.json 反映终态。
+- 观察两分支并行迭代的真实合并场景，确认文档层零冲突。
+- 工作台聚合视图（扫 meta.json 渲染产品时间线）作为后续增强候选，本轮不做。