# docs/ —— 目录约定与索引（document-ahead-coding）

> 本目录按 **document-ahead-coding** 技能约定组织：文档先行、代码跟随；决策与
> 「为什么」留在 docs/，每处代码改动可追溯回授权它的任务文档。
> 2026-08-27 起生效；此前散放在 docs/ 根的历史文档已就地归位（章节号未改）。

## 目录布局

| 目录 | 放什么 | 现有内容 |
|---|---|---|
| `discussion/` | 讨论与裁决记录（含机制/上游调查报告）——回答「**为什么这样做**」 | `design.md`（v0.3–v0.28 合并裁决史，按 § 分话题）、`repeater-detect.md`、`context-archive-2026-08-27.md`、`dsh-bash-tool-stall-report.md` + `repro-pty-stall.mjs` |
| `principle/` | 跨任务律法——未来任务**必须遵守**的规则 | `architecture.md`、`client-half.md`、`host-half.md`、`dsh-boundary.md`、`testing.md` |
| `task/` | 任务拆解，一件工作一个文件（字段模板见下） | `01-context-archive.md`、`02-context-archive-visibility.md`、`03-context-archive-viewer-portal.md`、`04-context-archive-listall-on2.md`、`05-context-archive-auto-trigger.md`、`06-context-archive-user-force.md`、`07-context-archive-path-resolution.md`、`08-archive-force-command.md`、`09-context-archive-settings-trim.md` |
| `manual/` | 怎么使用 / 维护这个 codebase | `monorepo.md`（架构、契约、维护规则）、`dev-notes.md`（dsh 插件机制手册 + v0.5→v0.26 版本日志） |
| `temp/` | 明确不做 / 推迟的方向 + 原因（可逆决策墓场） | `why-not-context-archive-options.md` |

## 入口怎么走

- **用这个项目**：根 `README.md`（索引 / 安装 / 开发）→ `packages/<feature>/README.md`（单功能说明）。
- **改这个项目**：`manual/monorepo.md`（架构与维护规则）→ `principle/`（律法）→
  `manual/dev-notes.md`（机制细节与踩坑）。
- **查一个历史决策**：`discussion/`（按话题文件 → § 章节号）。
- **开一件新工作**：讨论达成共识后——`discussion/` 记录裁决 → 有可复用规则就蒸馏进
  `principle/` → `task/` 拆任务 → 才开始写代码；「决定不做」写 `temp/`。

## task/ 文件必填字段

| 字段 | 含义 |
|---|---|
| **Goal** | 什么叫做完 |
| **Why** | 链接到授权它的 discussion / principle |
| **Approach** | 有序的具体步骤 |
| **Files touched** | 预期改动面（让 scope 可评审） |
| **Acceptance criteria** | 如何验证 |
| **Status** | `todo` → `doing` → `done` |

命名：`NN-描述.md`；子任务 `NN-NN-描述.md`（一个任务大到无法一次评审时再拆）。

## 铁律

1. **文档先行**：写代码前，对应 task 文档必须已描述即将要做的事。
2. **现实与计划不符 → 先改文档**：计划变化要告知用户，推迟/放弃的方向记 `temp/`。
3. **文档过期不得标 `done`**。
4. **文档与代码冲突是 bug**：修文档、修代码、或都修，并说明改了哪个。

## 历史说明

v0.3–v0.28 的裁决与机制调查先于本约定存在，**未**按「一话题一文件」回溯拆分：
合并记录在 `discussion/design.md`（裁决）与 `manual/dev-notes.md`（机制与版本日志），
两者章节号保持原样，旧引用（含包内 README 与源码注释里的 `§` 编号）依然有效。
2026-08-27 之后的新工作一律走上表流程。