universal-dev-standards 5.15.1 → 5.16.0

package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml

@@ -108,6 +108,27 @@ standard:
         AC Coverage: <pct>% (<covered>/<implemented_total> implemented ACs)
         Status: BLOCKED by <not_impl_count> not_implemented AC(s)
 
+  user_doc_coverage:
+    description: "Second dimension: are user-facing AC also documented in the user guide? Extends the traceability spine past tests to the user guide (Forward Derivation Standards -> Terminal Projection: User Guide)"
+    user_facing_filter:
+      rule: "Apply only to user-facing AC — those an end user can directly observe or operate (UI flow, CLI command, user-facing API semantics)"
+      excluded: "Internal refactor/module contracts, performance thresholds, security/internal guardrails"
+      conservative_default: "When in doubt treat AC as user-facing; excluding requires explicit 'user_facing: false', never silent omission"
+    status:
+      - status: documented
+        symbol: "✅"
+        definition: "A user-guide step covers this AC, tagged with the AC's shared T-NNN"
+      - status: partial
+        symbol: "⚠️"
+        definition: "A user-guide step exists but is incomplete or ambiguously tagged"
+      - status: undocumented
+        symbol: "❌"
+        definition: "No user-guide step references this user-facing AC"
+    calculation: |
+      user_doc_coverage = (documented + partial × 0.5) / (user_facing_ac_count - not_implemented_count) × 100
+      non-user-facing AC counted in neither numerator nor denominator; partial = 0.5; not_implemented excluded from denominator
+    shared_ruler: "A user-guide step's T-NNN MUST equal a real journey/E2E test id (single spine: test + journey + user guide). A parallel id with no matching test is reported undocumented, never covered"
+
   quality_thresholds:
     defaults:
       - name: Minimum AC Coverage
@@ -222,6 +243,16 @@ standard:
       instruction: Validate generated AC against SMART criteria and testability
       priority: required
 
+    - id: user-doc-user-facing-only
+      trigger: computing the user-doc coverage dimension
+      instruction: "Apply user-doc coverage only to user-facing AC; when in doubt treat as user-facing, exclude only with an explicit 'user_facing: false' marking"
+      priority: recommended
+
+    - id: user-doc-shared-tnnn
+      trigger: linking a user-guide step to an AC
+      instruction: "A user-guide step's T-NNN must equal a real journey/E2E test id; a parallel id with no matching test is reported undocumented, never covered"
+      priority: required
+
 related_standards:
   - forward-derivation-standards.md
   - spec-driven-development.md

package/bundled/ai/standards/forward-derivation-standards.ai.yaml

@@ -99,6 +99,20 @@ ac_level_summary:
   description: "Output AC Level Summary at end of /derive all"
   format: "| AC | Suggested Level | Rationale |"
 
+# Terminal Projection: User Guide (extends the chain past tests)
+terminal_projection:
+  description: "The user guide is the terminal projection of the derivation chain — the human-readable view of the same workflow E2E/journey tests verify by machine"
+  single_source_of_truth: "AC spine — BDD, TDD/IT/E2E, ATDD, contracts, and the user guide are all projections of the same AC"
+  user_facing_filter:
+    rule: "A user-guide step is required only for an AC an end user can directly observe or operate (UI flow, CLI command, user-facing API semantics)"
+    excluded: "Purely internal AC (refactor, internal module contracts, performance thresholds, security controls) carry no user-guide obligation"
+    default: "When in doubt, treat the AC as user-facing; explicit marking is required to exclude"
+  shared_numbering:
+    rule: "Each user-guide step is tagged T-NNN, and that T-NNN MUST be the id of a real journey/E2E test"
+    ambiguous: "Ambiguous or missing tags are reported as uncovered (prefer redundancy over omission)"
+    violation: "Minting a parallel T-NNN-style series detached from the AC spine"
+  single_spine_principle: "Test and documentation sources are layered projections of one AC spine (N×1), not independent sources cross-checking one another pairwise (N×N); TDD/IT/E2E are pyramid layers of the same spine, not rival sources"
+
 # Certainty Framework
 certainty_framework:
   tags:
@@ -171,6 +185,15 @@ rules:
   - id: ac-level-summary
     instruction: Output AC Level Summary table at end of /derive all
     priority: recommended
+  - id: single-spine-no-parallel-numbering
+    instruction: Every test/doc artifact must trace back to the AC spine; never mint a parallel T-NNN-style series detached from it
+    priority: required
+  - id: user-guide-shared-tnnn
+    instruction: A user-guide step's T-NNN must equal a real journey/E2E test id; ambiguous or missing tags are reported as uncovered
+    priority: required
+  - id: user-facing-ac-conservative-default
+    instruction: User-guide obligation applies to user-facing AC only; when in doubt treat as user-facing, explicit marking to exclude
+    priority: recommended
 
 related_standards:
   - reverse-engineering-standards.md

package/bundled/ai/standards/knowledge-graph-memory.ai.yaml

@@ -62,7 +62,7 @@ standard:
       always_available: true
     service:
       description: "Graph engine indexed: a single multi-hop query (impact-analysis {nodeId, maxHops}) returns the full cross-domain chain"
-      example_engine: "CodeSage (@asiaostrich/codesage)"
+      example_engine: "EngramGraph (engramgraph)"
 
   confidence:
     optional: true

package/bundled/core/acceptance-criteria-traceability.md

@@ -140,6 +140,52 @@ The gate clears only when all `not_implemented` ACs are updated to `uncovered`,
 
 ---
 
+## User-Documentation Coverage | 使用者文件覆蓋
+
+The AC↔test matrix above verifies that AC are *tested*. A second dimension verifies that **user-facing AC are also documented** for the end user. This extends the traceability spine past tests to the user guide — see Forward Derivation Standards → *Terminal Projection: User Guide*. The user guide and the journey/E2E suite are two projections of one workflow, so they share one ruler: `T-NNN`.
+
+### User-Facing AC Filter
+
+Apply the user-doc dimension **only to user-facing AC** — those an end user can directly observe or operate. This prevents the dimension from degrading into a blanket documentation obligation on every internal AC.
+
+| AC kind | User-facing? |
+|---------|--------------|
+| UI flow, screen, navigation | Yes |
+| CLI command / flag a user runs | Yes |
+| User-facing API semantics (public contract a user calls) | Yes |
+| Internal refactor / module contract | No |
+| Performance threshold, capacity | No |
+| Security control, internal guardrail | No |
+
+**Conservative default**: when in doubt, treat the AC as user-facing. Excluding an AC requires **explicit marking** (e.g. `user_facing: false`), never silent omission.
+
+### User-Doc Status
+
+Reuse the same symbols, now answering "is this user-facing AC covered by a user-guide step?":
+
+| Status | Symbol | Definition |
+|--------|--------|------------|
+| **Documented** | ✅ | A user-guide step covers this AC, tagged with the AC's shared `T-NNN` |
+| **Partial** | ⚠️ | A user-guide step exists but is incomplete or ambiguously tagged |
+| **Undocumented** | ❌ | No user-guide step references this user-facing AC |
+
+`not_implemented` (🚫) AC are excluded from the user-doc denominator, exactly as in the test-coverage calculation.
+
+### User-Doc Coverage Calculation
+
+```
+User-Doc Coverage % = (documented + partial × 0.5) / (user_facing_ac_count - not_implemented_count) × 100
+
+Where:
+  user_facing_ac_count = count of AC classified user-facing (conservative default applies)
+  non-user-facing AC are counted in neither numerator nor denominator
+  partial counts as 0.5
+```
+
+> **Single ruler**: a user-guide step's `T-NNN` MUST equal a real journey/E2E test id (Forward Derivation Standards). This binds three projections of one AC — test, journey, and user guide — to a single spine. A user-guide step that mints a parallel id with no matching test is reported as **undocumented**, never as covered.
+
+---
+
 ## Quality Thresholds
 
 ### Default Thresholds

package/bundled/core/forward-derivation-standards.md

@@ -515,6 +515,25 @@ spec-review → forward-derivation → discovery
 
 ---
 
+## Terminal Projection: User Guide | 終端投影：使用者指南
+
+The derivation chain does not stop at tests. The **user guide is the terminal projection** of the same chain — the human-readable view of the very workflow that E2E/journey tests verify by machine. "What the user reads as steps" and "what E2E actually verifies as behavior" become one maintained invariant.
+
+- **Single source of truth**: the SPEC's acceptance criteria (AC). Every downstream artifact — BDD scenarios, TDD/IT/E2E skeletons, ATDD tables, contracts, **and the user guide** — is a projection of the same AC spine. The user guide is not a separate source to be cross-checked; it is one more projection.
+- **User-facing AC only**: a user-guide step is required only for an AC that an **end user can directly observe or operate** (UI flow, CLI command, user-facing API semantics). Purely internal AC (refactor, internal module contracts, performance thresholds, security controls) carry no user-guide obligation. **When in doubt, treat the AC as user-facing** — conservative default; explicit marking is required to exclude.
+- **Shared numbering (`T-NNN`)**: each user-guide step is tagged `T-NNN`, and that `T-NNN` MUST be the id of a real journey/E2E test. The user guide and the E2E suite are two projections of one workflow sharing one ruler. Ambiguous or missing tags are reported as **uncovered** (prefer redundancy over omission).
+  - ✅ user-guide step `T-012 "Create a project"` ↔ E2E test `T-012` in the journey spec.
+  - ❌ user guide invents `UG-3` with no corresponding test → drift, reported as uncovered.
+- **Drift example**: user guide says "2-click checkout" while E2E still verifies "3-step payment" — without shared numbering, no one notices. Shared `T-NNN` turns this drift into a reported coverage gap.
+
+### Single-Spine Principle (not parallel cross-check)
+
+Test and documentation sources are **multiple layered projections of one AC spine**, not independent sources of truth that cross-check one another. TDD/IT/E2E are pyramid *layers* of the same spine (see Test Level Decision Tree), not rival sources. Cross-checking N sources pairwise (N×N) breeds drift; projecting each artifact back to the single AC spine (N×1) eliminates it.
+
+> **Rule**: every test or documentation artifact MUST trace back to an AC. Minting a **parallel numbering scheme** — a second `T-NNN`-style series detached from the AC spine — is a VIOLATION. There is one ruler: the AC spine, with `T-NNN` shared between journey/E2E tests and the user guide.
+
+---
+
 ## Test Level Decision Tree
 
 根據 AC 的性質決定應生成哪種測試層級：

package/bundled/core/knowledge-graph-memory.md

@@ -13,7 +13,7 @@
 
 This standard defines a **relationship schema** so that specifications, decisions, and code can be traversed as a graph — answering questions like *"if I change `execute()`, which specs and decisions are affected?"*. It complements vector/semantic memory (which finds *similar* artifacts) with **structural traversal** (which finds *connected* artifacts).
 
-The schema is engine-agnostic: it is expressed as plain Markdown front-matter that an AI assistant can read directly (degraded mode), and that an optional graph engine (e.g. [CodeSage](https://github.com/AsiaOstrich/CodeSage)) can index for multi-hop queries (service mode).
+The schema is engine-agnostic: it is expressed as plain Markdown front-matter that an AI assistant can read directly (degraded mode), and that an optional graph engine (e.g. [EngramGraph](https://github.com/AsiaOstrich/EngramGraph)) can index for multi-hop queries (service mode).
 
 ---
 
@@ -60,7 +60,7 @@ related: [XSPEC-204]
 ```markdown
 ---
 id: DEC-069
-title: CodeSage Architecture
+title: EngramGraph Architecture
 date: 2026-05-27
 supersedes: [DEC-057]
 impacts: [XSPEC-237]

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.15.1
-translation_version: 5.15.1
-last_synced: 2026-05-31
+source_version: 5.16.0
+translation_version: 5.16.0
+last_synced: 2026-06-08
 status: current
 ---
 
@@ -17,6 +17,16 @@ status: current
 
 ## [Unreleased]
 
+## [5.16.0] - 2026-06-08
+
+### 新增 — 测试推导链延伸至用户指南（XSPEC-260）
+
+- **`core/forward-derivation-standards.md`**：新增 `## Terminal Projection: User Guide`（终端投影：用户指南）段 + `### Single-Spine Principle`（单一主干原则）。把推导管道从测试延伸到用户指南——用户指南是 journey／E2E 测试以机器验证的同一条 AC 主干的终端投影。定义共用 `T-NNN` 编号（用户指南步骤的 `T-NNN` 必须等于某个真实 journey／E2E 测试的 id）、user-facing AC 筛选与保守预设，以及单一主干原则：测试／文件来源是同一 AC 主干的 N×1 投影、非 N×N 平行对照；另立平行编号体系即为违规。
+- **`ai/standards/forward-derivation-standards.ai.yaml`**：对应 `terminal_projection` 区块 + 3 条 rules（`single-spine-no-parallel-numbering`、`user-guide-shared-tnnn`、`user-facing-ac-conservative-default`）。
+- **`core/acceptance-criteria-traceability.md`**：新增 `## User-Documentation Coverage`（用户文件覆盖）维度——追踪 user-facing AC 是否被用户指南记载。含 user-facing AC 筛选（保守预设：判不准归 user-facing）、沿用 ✅/⚠️/❌ 状态，及排除非 user-facing 与 `not_implemented` AC 的覆盖率公式。
+- **`ai/standards/acceptance-criteria-traceability.ai.yaml`**：对应 `user_doc_coverage` 区块 + 2 条 rules（`user-doc-user-facing-only`、`user-doc-shared-tnnn`）。
+- **zh-TW / zh-CN 语言版**：两标准的新段落均完整翻译。
+
 ## [5.15.0] - 2026-05-28
 
 ### 新增 — i18n 分层语言策略（XSPEC-239）

package/bundled/locales/zh-CN/README.md

@@ -14,7 +14,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 5.15.1 | **发布日期**: 2026-05-28 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 5.16.0 | **发布日期**: 2026-05-28 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 

package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md

@@ -116,6 +116,52 @@ Coverage = (5 + 2×0.5) / 8 = 6/8 = 75%
 
 ---
 
+## 用户文件覆盖
+
+上方的 AC↔测试矩阵验证 AC 是否被*测试*。第二个维度则验证 **user-facing AC 是否同时被用户指南记载**。这把可追溯主干从测试延伸到用户指南——见正向推演标准 →《终端投影：用户指南》。用户指南与 journey／E2E 套件是同一作业流程的两个投影，因此共用一把尺：`T-NNN`。
+
+### User-Facing AC 筛选
+
+此维度**只套用于 user-facing AC**——终端用户可直接观察或操作者。如此可避免此维度退化成对每个内部 AC 的全面文件义务。
+
+| AC 类型 | user-facing？ |
+|---------|--------------|
+| UI 流程、画面、导航 | 是 |
+| 用户执行的 CLI 指令／标志 | 是 |
+| 对外 API 的用户语义（用户调用的公开契约）| 是 |
+| 内部重构／模块契约 | 否 |
+| 性能门槛、容量 | 否 |
+| 安全内控、内部护栏 | 否 |
+
+**保守预设**：判不准时一律归 user-facing。排除某个 AC 必须**明确标记**（如 `user_facing: false`），绝不静默省略。
+
+### 用户文件状态
+
+沿用相同符号，改回答「此 user-facing AC 是否被某个用户指南步骤覆盖？」：
+
+| 状态 | 符号 | 定义 |
+|------|------|------|
+| **已记载** | ✅ | 有用户指南步骤覆盖此 AC，并标上该 AC 共用的 `T-NNN` |
+| **部分** | ⚠️ | 有用户指南步骤但不完整或标记模棱两可 |
+| **未记载** | ❌ | 无任何用户指南步骤引用此 user-facing AC |
+
+`not_implemented`（🚫）AC 排除于用户文件分母之外，与测试覆盖率计算一致。
+
+### 用户文件覆盖率计算
+
+```
+用户文件覆盖率 % = (已记载 + 部分 × 0.5) / (user_facing_ac_count - not_implemented_count) × 100
+
+其中：
+  user_facing_ac_count = 归类为 user-facing 的 AC 数（套用保守预设）
+  非 user-facing AC 不计入分子也不计入分母
+  部分计为 0.5
+```
+
+> **同一把尺**：用户指南步骤的 `T-NNN` 必须等于某个真实 journey／E2E 测试的 id（正向推演标准）。这把同一 AC 的三个投影——测试、journey、用户指南——绑到单一主干。自造平行 id 却无对应测试的用户指南步骤，一律报为**未记载**，绝不算覆盖。
+
+---
+
 ## 品质门槛
 
 ### 默认门槛

package/bundled/locales/zh-CN/core/forward-derivation-standards.md

@@ -333,6 +333,25 @@ spec-review → forward-derivation → discovery
 
 ---
 
+## 终端投影：用户指南
+
+推演链不止于测试。**用户指南是同一条链的终端投影**——E2E／旅程测试以机器验证的那条作业流程，其供人阅读的视图。「用户读到的操作步骤」与「E2E 实际验证的行为」因此成为一个被维持的不变量。
+
+- **单一真实来源**：SPEC 的验收条件（AC）。所有下游产物——BDD 场景、TDD／IT／E2E 骨架、ATDD 表格、契约，**以及用户指南**——都是同一条 AC 主干的投影。用户指南不是另一个要互相对照的来源，而是又一个投影。
+- **仅限 user-facing AC**：唯有**终端用户可直接观察或操作**的 AC（UI 流程、CLI 指令、对外 API 的用户语义）才需要用户指南步骤。纯内部 AC（重构、内部模块契约、性能门槛、安全内控）无用户指南义务。**判不准时一律归 user-facing**——保守预设；必须明确标记才能排除。
+- **共用编号（`T-NNN`）**：每个用户指南步骤标 `T-NNN`，且该 `T-NNN` 必须是某个真实 journey／E2E 测试的 id。用户指南与 E2E 套件是同一作业流程的两个投影、共用一把尺。模棱两可或未标记一律报为**未覆盖**（宁可冗余不要遗漏）。
+  - ✅ 用户指南步骤 `T-012「创建项目」` ↔ journey spec 中的 E2E 测试 `T-012`。
+  - ❌ 用户指南自造 `UG-3` 却无对应测试 → drift，报为未覆盖。
+- **Drift 反例**：用户指南写「2-click checkout」、E2E 却仍验「3-step payment」——没有共用编号就无人察觉。共用 `T-NNN` 把这种 drift 变成被报出的覆盖缺口。
+
+### 单一主干原则（非平行对照）
+
+测试与文件来源是**同一条 AC 主干的多层投影**，不是互相对照的独立真实来源。TDD／IT／E2E 是同一主干的金字塔**层级**（依 AC 性质分层），非彼此竞争的来源。两两对照 N 个来源（N×N）会滋生 drift；把每个产物投影回单一 AC 主干（N×1）则消除它。
+
+> **规则**：每个测试或文件产物都必须回溯到某个 AC。另立**平行编号体系**——一条脱离 AC 主干的第二套 `T-NNN` 系列——即为违规。只有一把尺：AC 主干，且 `T-NNN` 由 journey／E2E 测试与用户指南共用。
+
+---
+
 ## 命令
 
 ### 命令参考

package/bundled/locales/zh-CN/skills/ac-coverage/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: ac-coverage
+source: ../../../../skills/ac-coverage/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: f8358fa818e4
+scope: universal
+status: current
+description: "[UDS] 分析验收条件（AC）与测试之间的追踪关系并生成覆盖率报告"
+allowed-tools: Read, Grep, Glob
+argument-hint: "[规格文件路径]"
+---
+
+# AC 覆盖率助手
+
+> **语言**: [English](../../../../skills/ac-coverage/SKILL.md) | 简体中文
+
+分析验收条件（AC）与测试之间的追踪关系，并生成覆盖率报告。
+
+## 与 `/coverage` 的区别
+
+| 方面 | `/coverage` | `/ac-coverage` |
+|------|-------------|----------------|
+| **范围** | 代码层级（行数／分支／函数） | 需求层级（AC 对应测试） |
+| **输入** | 源代码 + 测试运行器 | SPEC 文件 + 测试标注 |
+| **问题** | 「代码测试了多少？」 | 「哪些 AC 有测试？」 |
+| **输出** | 覆盖率百分比 | 追踪矩阵 + 缺口报告 |
+
+## 工作流程
+
+1. **解析 SPEC** — 从规格文件中抽取 AC 定义（AC-1, AC-2, ...）
+2. **扫描测试** — 依标准链接约定搜索测试文件中的 `@AC` 与 `@SPEC` 标注
+3. **构建矩阵** — 将每个 AC 对应到其测试引用（文件、测试名称、行号）
+4. **分类状态** — 将每个 AC 标记为 ✅ 已覆盖、⚠️ 部分覆盖、或 ❌ 未覆盖
+5. **计算覆盖率** — 套用公式：`覆盖率 % = (已覆盖 + 部分覆盖 × 0.5) / 总数 × 100`
+6. **生成报告** — 输出标准化的 Markdown 报告
+
+## 链接标注约定
+
+测试**必须**使用标准标注引用其来源 AC：
+
+```typescript
+// TypeScript/JavaScript
+describe('AC-1: User login with valid credentials', () => {
+  // @AC AC-1
+  // @SPEC SPEC-001
+  it('should redirect to dashboard on successful login', () => { ... });
+});
+```
+
+```python
+# Python
+class TestAC1_UserLogin:
+    """AC-1: User login with valid credentials
+    @AC AC-1
+    @SPEC SPEC-001
+    """
+    def test_redirect_to_dashboard(self): ...
+```
+
+```gherkin
+# BDD Feature
+@SPEC-001 @AC-1
+Scenario: User login with valid credentials
+```
+
+## 覆盖率门槛
+
+| 门槛 | 默认值 | 强制等级 |
+|------|--------|----------|
+| **签入（Check-in）** | 80% | feature branch 合并必要条件 |
+| **发布（Release）** | 100% | 生产环境发布必要条件 |
+| **警告（Warning）** | 60% | 触发覆盖率警告 |
+
+门槛可通过 `--threshold` 参数或项目配置文件调整。
+
+## 四层追溯（`--full` 模式）
+
+使用 `--full` 标记将追溯从 2 层（AC→Test）扩展为 4 层。
+
+### 追溯层次
+
+```
+Layer 0：需求 / 用户故事 (REQ)
+    ↓ （定义）
+Layer 1：验收条件 (AC)
+    ↓ （@AC 标注）
+Layer 2：测试用例
+    ↓ （覆盖）
+Layer 3：源代码 (@implements)
+```
+
+### 各层标注约定
+
+```typescript
+// Layer 3→1：代码引用 AC
+// @implements AC-1, AC-2
+function authenticate(user: string, pass: string) { ... }
+```
+
+```markdown
+<!-- Layer 0→1：SPEC 中的需求 -->
+## Requirements
+### REQ-1：用户验证
+- AC-1: 给定有效凭证，当登录时，则验证通过
+- AC-2: 给定无效凭证，当登录时，则被拒绝
+```
+
+### 完整追溯报告
+
+```markdown
+## 四层追溯矩阵
+
+| 需求 | AC | 测试 | 代码 | 状态 |
+|------|-----|------|------|------|
+| REQ-1 | AC-1 | auth.test.ts:15 | auth.ts:42 | ✅ 完整 |
+| REQ-1 | AC-2 | auth.test.ts:30 | auth.ts:58 | ✅ 完整 |
+| REQ-2 | AC-3 | — | dashboard.ts:10 | ⚠️ 缺测试 |
+| REQ-3 | AC-4 | export.test.ts:5 | — | ⚠️ 缺代码 |
+
+### 缺口摘要
+- Layer 0→1: 2 个需求未对应 AC
+- Layer 1→2: 1 个 AC 未对应测试
+- Layer 2→3: 0 个测试未对应代码
+- Layer 3→1: 3 个代码文件未对应 AC
+```
+
+### 反向追溯
+
+使用 `--trace-code <path>` 从代码反向追溯到需求。
+
+```bash
+/ac-coverage --trace-code src/auth.ts
+# 输出：
+# src/auth.ts:42 → @implements AC-1 → REQ-1 (SPEC-AUTH-001)
+# src/auth.ts:58 → @implements AC-2 → REQ-1 (SPEC-AUTH-001)
+```
+
+## 报告格式
+
+生成的报告遵循 `core/acceptance-criteria-traceability.md` 的标准格式：
+
+```markdown
+# AC 覆盖率报告
+
+**规格**: SPEC-001 — 功能名称
+**生成时间**: 2026-03-18
+**覆盖率**: 75% (6/8 AC)
+
+## 摘要
+
+| 状态 | 数量 | 百分比 |
+|------|------|--------|
+| ✅ 已覆盖 | 5 | 62.5% |
+| ⚠️ 部分覆盖 | 2 | 25.0% |
+| ❌ 未覆盖 | 1 | 12.5% |
+
+## 追溯矩阵
+
+| AC-ID | 描述 | 状态 | 测试引用 |
+|-------|------|------|----------|
+| AC-1 | 以有效凭证登录 | ✅ | auth.test.ts:15 |
+| AC-2 | 拒绝无效凭证 | ✅ | auth.test.ts:32 |
+| ...   | ...           | ... | ... |
+
+## 缺口
+- **AC-8**: 社交登录 — 因 OAuth sandbox 未就绪受阻
+
+## 行动项目
+1. [ ] AC-8：搭建 OAuth sandbox（预计时间：待定）
+```
+
+## 下一步引导
+
+`/ac-coverage` 完成后，AI 助手应建议：
+
+> **AC 覆盖率分析完成。建议下一步：**
+> - 覆盖率达标 → 执行 `/checkin` 质量关卡
+> - 有未覆盖 AC → 执行 `/derive-tdd` 补齐测试 ⭐ **推荐**
+> - 有部分覆盖 AC → 检查缺少的边界情况
+> - 需要完整追溯 → 执行 `/ac-coverage --full`
+> - 反向追溯 → 执行 `/ac-coverage --trace-code <path>`
+
+## 参考
+
+- 核心标准：[acceptance-criteria-traceability.md](../../../../core/acceptance-criteria-traceability.md)
+- SPEC：[SPEC-AC-COVERAGE.md](../../../../docs/specs/skills/SPEC-AC-COVERAGE.md)
+- 相关：[test-coverage-assistant](../test-coverage-assistant/SKILL.md)（代码层级覆盖率）
+- 相关：[checkin-assistant](../checkin-assistant/SKILL.md)（质量关卡）
+
+## AI 代理行为
+
+> 完整的 AI 行为定义请参阅对应的命令文件：[`/ac-coverage`](../../../../skills/commands/ac-coverage.md#ai-agent-behavior--ai-代理行为)