工件寻址契约（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. 双向链接不变量

工件 ↔ 工单引用成对：工件发布到工件库后，源工单侧必须有反向索引（工件索引评论）；工单侧索引的每一行必须指向真实存在的工件。
单评论聚合：一个源工单有且仅有一条工件索引评论，各技能只原位增改自己的行，绝不发第二条。
归档补全：工单关闭时，关闭方 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 可复用。

7.9 KiB Raw Permalink Blame History Unescape Escape