# 工件寻址契约（Core，后端中立）

> Core 原生契约（Increment 3，无 dogfood 对应源文件）。术语对照见
> `core/adapters/TERMINOLOGY.md`；本文所有实例路径以占位符表述
> （`<runs-root>` = 实例运行目录根），落地实例时按术语表绑定。

## 1. ref 语法

所有 Tier-2 工件的规范引用格式：

```
{backend}:{kind}/{owner}/{repo}/{id}#{anchor}
```

- `{backend}` — 工单后端标识（如 `gitea`）；由 adapter 层注册。
- `{kind}` — 工件类别，枚举见下表；新类别扩展时须同步各 adapter 的
  resolve 实现并在本表登记。
- `{owner}/{repo}` — 仓库坐标。
- `{id}` — 工件标识：issue/PR 用数字，wiki 页用页名（可含 `/`），
  评论用 `{issue-number}c{comment-id}`，commit-status 用 `{sha}@{context}`。
- `#{anchor}` — 可选锚点（页内段落、行号等），解析时透传不解释。

| kind            | 含义            | id 形态                |
| --------------- | --------------- | ---------------------- |
| `issue`         | 工单            | 数字                   |
| `issue-comment` | 工单评论        | `{issue}c{comment-id}` |
| `wiki-page`     | Tier-2 工件库页 | 页名（含 `/`）         |
| `commit-status` | 提交状态        | `{sha}@{context}`      |
| `pr`            | 合并请求        | 数字                   |

## 2. 页名文法（Core 契约）

Tier-2 工件库的**常规页名**：

```
{slug}/{type}-{seq:02d}-{title}
```

- `{slug}` 限 `[a-z0-9-]`；`{seq}` 两位零填充；`{title}` 限
  `[a-z0-9-]`（CJK 标题按 adapter 层编码规则处理）。

### 2.1 例外页（全枚举）

以下页名不受常规文法约束（勘自实例的全部真实约定）：

| 例外页               | 形态                                                                               | 说明                                                |
| -------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------- |
| 评审轮次页           | `{slug}/reviews/{stage}/round{N}/{page}`                                           | `page` ∈ `task-{ROLE}`、`revision-summary`          |
| 评审终报             | `{slug}/reviews/{stage}/final/report`                                              | 含 DAG task 变体 `…/final/report-task-{node-id}`    |
| 验证报告             | `{slug}/05-verify-iteration-{N}`                                                   | 常规前缀 + 无 title 段的变体                        |
| 验证报告（里程碑）   | `{epic-slug}/05-verify-milestone-{M-id}`                                           | 同上                                                |
| 验证报告（任务节点） | `{epic-slug}/05-verify-task-{node-id}`                                             | 同上                                                |
| DAG 工件             | `{epic-slug}/dag`、`{epic-slug}/dag-nodes/{node-id}`、`{epic-slug}/dag-coverage`   | 单门 DAG 管线工件                                   |
| DAG 共享契约         | `{epic-slug}/shared/{file}`                                                        | 跨会话契约                                          |
| bugfix 附件          | `{slug}/repro-notes`、`{slug}/test-report`、`{slug}/bugfix-report`、`{slug}/ABORT` | 单段固定名                                          |
| 原型/笔记            | `{slug}/prototype-debt`、`{slug}/spike-report`、`{slug}/impl-notes`                | 单段固定名                                          |
| 设计修订             | `{slug}/03-design-amendments`                                                      | 常规前缀 + 固定名                                   |
| 浏览器证据           | `{slug}/verify/evidence/{name}`                                                    | 验证证据页                                          |
| 审计轮次页           | `audit/{date}/round{N}/{page}`                                                     | 日期 slug 例外；`page` ∈ `synthesis`、`task-{ROLE}` |
| 审计终报             | `audit/{date}/final/report`                                                        | 日期 slug 例外                                      |
| 回顾报告             | `_retrospectives/{cycle-name}`                                                     | 跨 slug 命名空间例外                                |
| 技能评估             | `_evals/{skill-name}/{page}`                                                       | 评估命名空间例外                                    |
| 移植工件             | `port-{name}/source-analysis/{file}`、`port-{name}/self-check`                     | 移植命名空间例外                                    |
| 回顾归档             | `_archive/{slug}/…`                                                                | 归档命名空间例外                                    |

> 历史只读页名（旧管线产物，仍可读取）：`{slug}/01-stakeholder-interview`、
> `{slug}/02-requirements-index`、`{slug}/02-req-{seq:02d}-{title}`、
> `{slug}/02-03-req-design`、`{slug}/03-design-{seq:02d}-{title}`、
> `{slug}/03-adr-{NNNN}-{title}`、`{slug}/04-plan-index`、
> `{slug}/04-plan-{seq:02d}-{title}`、`{slug}/roadmap/{page}`。

### 2.2 kind ↔ type 映射

| 工件类别（kind 语境） | 页名 `{type}` 段                                                 |
| --------------------- | ---------------------------------------------------------------- |
| 验证报告              | `05-verify-iteration` / `05-verify-milestone` / `05-verify-task` |
| 设计文档              | `03-design` / `03-adr` / `03-design-amendments`                  |
| 计划文档              | `04-plan`                                                        |
| 需求文档              | `02-req` / `02-requirements-index`                               |
| 评审工件              | `reviews`（目录段，非前缀）                                      |
| DAG 工件              | `dag` / `dag-nodes` / `dag-coverage`                             |
| 审计工件              | `audit`（日期前缀命名空间）                                      |

## 3. Tier-1 ↔ Tier-2 映射

wiki 页 `{slug}/…` 与实例运行目录 `<runs-root>/{slug}/…`（Tier-1 本地
结构化工件，见 Two-Tier 规则）按 slug 一一对应：

- 页 `{slug}/reviews/{stage}/round{N}/findings-{DIM}.json` ↔ 本地
  `<runs-root>/{slug}/reviews/{stage}/round{N}/findings-{DIM}.json`；
- 页面正文承载 Tier-2 决策记录；原始发现、工作草稿留在 Tier-1 本地。

**文件名 URL 编码规则**：页名映射为本地文件名时 `/` → `%2F`
（逆向解码同理）；`.-` 尾缀是实例后端生成的 slug 产物，解码时剥除。

## 4. 双向链接不变量

1. **工件 ↔ 工单引用成对**：工件发布到工件库后，源工单侧必须有反向
   索引（工件索引评论）；工单侧索引的每一行必须指向真实存在的工件。
2. **单评论聚合**：一个源工单有且仅有一条工件索引评论，各技能只
   原位增改自己的行，绝不发第二条。
3. **归档补全**：工单关闭时，关闭方 agent 原位编辑索引评论——加归档
   横幅、全部行重读优先级置 `ARCHIVE`；不删行、不改位置列。

## 5. adapter 义务

每个工单后端 adapter 必须实现三个操作：

- **parse** — 解析 ref 字符串为 `{backend, kind, owner, repo, id, anchor}`；
- **resolve** — 把解析结果解析为该后端可调用的 API 形态（端点、工具名、
  参数），API 调用形态归 adapter 层，Core 不约束；
- **validate** — 校验页名符合第 2 节文法（含例外枚举）。

页名规范是**后端中立契约**；仓里的共用解析器
`script/resolve-artifact-ref.ts` 提供 parse 与页名/文件名编解码、
Tier-1 路径预测的中立实现，adapter 可复用。