# 四类文档

> PRD / SDD / units.json / runs/result.json — 它们之间是**派生关系**，构成系统的唯一真源。本页给出完整 schema 与示例。

## 派生关系

<!-- 图见原 HTML -->

## 四个文档逐一

<button role="tab" aria-selected="true"  aria-controls="t-prd">prd.html</button>
<button role="tab" aria-selected="false" aria-controls="t-sdd">sdd.html</button>
<button role="tab" aria-selected="false" aria-controls="t-units">units.json</button>
<button role="tab" aria-selected="false" aria-controls="t-run">runs/result.json</button>

```js
<!-- PM Agent 维护，每次人类反馈追加 section -->

  <h1>Auto Auth System</h1>

  

    
### 登录

    
用户名密码登录，会话 7 天有效。

  

  

    
### OAuth 登录

    
支持 GitHub OAuth。Token 刷新 ≤ 5s。

  

  

    
rev 1 · init · 邮箱密码登录

    
rev 2 · yibo · 加个人主页

    
rev 3 · yibo · GitHub OAuth

  

```

```js
<!-- Architect 生成；嵌入可机读 unit 元数据 -->

  

    
### Unit · auth-be

    
提供登录 / 注册 / token 校验端点

    
```
POST /api/auth/login
request:  { email, password }
response: 200 { token } | 401 { error:"invalid_credentials" }
```

    
- 有效凭据 → 200 + JWT
- user 不存在 → 401 invalid_credentials

  

  <!-- 更多 section ... -->

```

```js
{
  "project_id": "p-001",
  "prd_rev": "3",
  "sdd_rev": "5",
  "units": [
    {
      "id": "auth-be",
      "type": "be",
      "status": "passed",
      "depends_on": [],
      "retries": 1,
      "retry_budget": 5,
      "contract_hash": "sha256:7f3a...",
      "last_run": "run-20260513-0731"
    },
    {
      "id": "auth-fe",
      "type": "fe",
      "status": "testing",
      "depends_on": ["auth-be"],
      "retries": 0,
      "retry_budget": 5,
      "contract_hash": "sha256:9c1d..."
    }
  ],
  "l2_rounds": 0,
  "l2_budget": 3
}
```

```js
{
  "run_id": "run-20260513-0731",
  "loop": "L1",
  "unit_id": "auth-be",
  "agent": "tester",
  "attempt": 2,
  "summary": { "total": 8, "passed": 7, "failed": 1 },
  "ok": false,
  "failures": [
    { "test": "login.invalid-pwd",
      "expected": 401, "got": 500,
      "stack": "TypeError: ...",
      "hint": "先查 user 再 bcrypt 比对" }
  ],
  "next_action": "retry_coder",
  "retry_budget_left": 3,
  "duration_ms": 1245
}
```

## 谁能写谁

| 文档 | 写入者 | 读取者 |
| --- | --- | --- |
| `prd.html` | PM (通过 DocStore) | Architect · Dashboard |
| `sdd.html` | Architect (通过 DocStore) | Coder · Tester · Integrator · Triager · Dashboard |
| `units.json` | Architect (字段) + UnitRegistry (status) | 所有 |
| `integration/spec.json` | Architect | Integrator |
| `units/{id}/code/**` | Coder | Tester · Integrator · Triager (只读) |
| `units/{id}/contract.json` | Coder | Tester · 其他 Unit Coder · Triager |
| `units/{id}/tests/**` | Tester | Integrator |
| `runs/{id}/result.json` | Tester (L1) / Integrator (L2) | LoopController · Triager · Dashboard |
| `triage.json` | BugTriager | LoopController · Architect |
| `history/**` | DocStore.archive() | Dashboard diff 视图 |
| `agent-state/{agent}.json` | LoopController + Agent 工具 | Dashboard · recoverOnBoot |
| `agent-state/{agent}-todo.json` | Agent (write_todolist · update_todo_item 工具) | Dashboard · getProgress |
| `agent-state/snapshots/*` | LoopController | retry 时回放 · recover |
| `timeline.ndjson` | TimelineLogger (所有 source append) | Dashboard 时间线 · audit |
| `memory/devloop/{agent}/*.md` | Agent (record_memory 工具) | Agent 启动时注入 prompt |

## 归档策略

每次 prd / sdd / units.json 被写时，旧版本自动移到 `history/`，命名规则：

- `history/prd-rev-{N}.html`
- `history/sdd-rev-{N}.html`
- `history/units-rev-{N}.json`

Dashboard 的 PRD diff 视图直接读 history 做 section diff。无需 git。