doc-adr-fixer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

doc-adr-fixer

Purpose

用途

Automated fix skill that reads the latest review report and applies fixes to ADR (Architecture Decision Record) documents. This skill bridges the gap between

doc-adr-reviewer

(which identifies issues) and the corrected ADR, enabling iterative improvement cycles.

Layer: 5 (ADR Quality Improvement)

Upstream: ADR document, Review Report (

ADR-NN.R_review_report_vNNN.md

), BDD (for behavior alignment), BRD (for topic alignment)

Downstream: Fixed ADR, Fix Report (

ADR-NN.F_fix_report_vNNN.md

)

自动化fix skill，可读取最新的评审报告，对ADR（架构决策记录）文档执行修复操作。该skill填补了

doc-adr-reviewer

（负责识别问题）和修正后ADR之间的流程缺口，可实现迭代优化循环。

层级：5（ADR质量优化层）

上游依赖：ADR文档、评审报告（

ADR-NN.R_review_report_vNNN.md

）、BDD（用于行为对齐）、BRD（用于主题对齐）

下游产出：修复后的ADR、修复报告（

ADR-NN.F_fix_report_vNNN.md

）

When to Use This Skill

何时使用该Skill

Use

doc-adr-fixer

when:

After Review: Run after
```
doc-adr-reviewer
```
identifies issues
Iterative Improvement: Part of Review -> Fix -> Review cycle
Automated Pipeline: CI/CD integration for quality gates
Batch Fixes: Apply fixes to multiple ADRs based on review reports

Do NOT use when:

No review report exists (run
```
doc-adr-reviewer
```
first)
Creating new ADR (use
```
doc-adr
```
or
```
doc-adr-autopilot
```
)
Only need validation (use
```
doc-adr-validator
```
)

当出现以下场景时使用

doc-adr-fixer

：

评审后执行：在
```
doc-adr-reviewer
```
识别出问题后运行
迭代优化：作为「评审→修复→评审」循环的组成部分
自动化流水线：集成到CI/CD中作为质量门禁
批量修复：基于评审报告对多个ADR执行批量修复

请勿在以下场景使用：

不存在评审报告时（请先运行
```
doc-adr-reviewer
```
）
创建新ADR时（请使用
```
doc-adr
```
或
```
doc-adr-autopilot
```
）
仅需要校验时（请使用
```
doc-adr-validator
```
）

Skill Dependencies

Skill依赖

Skill	Purpose	When Used
`doc-adr-reviewer`	Source of issues to fix	Input (reads review report)
`doc-naming`	Element ID standards	Fix element IDs
`doc-adr`	ADR creation rules	Create missing sections
`doc-bdd`	BDD alignment reference	Verify behavior traceability

Skill	用途	调用时机
`doc-adr-reviewer`	待修复问题的来源	输入侧（读取评审报告）
`doc-naming`	元素ID规范	修复元素ID时
`doc-adr`	ADR创建规则	补全缺失章节时
`doc-bdd`	BDD对齐参考	验证行为可追溯性时

Workflow Overview

工作流概览

mermaid

flowchart TD
    A[Input: ADR Path] --> B[Find Latest Review Report]
    B --> C{Review Found?}
    C -->|No| D[Run doc-adr-reviewer First]
    C -->|Yes| E[Parse Review Report]

    E --> F[Categorize Issues]

    subgraph FixPhases["Fix Phases"]
        F --> F0[Phase 0: Fix Structure Violations]
        F0 --> G[Phase 1: Create Missing Files]
        G --> H[Phase 2: Fix Broken Links]
        H --> I[Phase 3: Fix Element IDs]
        I --> J[Phase 4: Fix Content Issues]
        J --> K[Phase 5: Update References]
        K --> K2[Phase 6: Handle Upstream Drift]
    end

    K2 --> L[Write Fixed ADR]
    L --> M[Generate Fix Report]
    M --> N{Re-run Review?}
    N -->|Yes| O[Invoke doc-adr-reviewer]
    O --> P{Score >= Threshold?}
    P -->|No, iterations < max| F
    P -->|Yes| Q[COMPLETE]
    N -->|No| Q

mermaid

flowchart TD
    A[Input: ADR Path] --> B[Find Latest Review Report]
    B --> C{Review Found?}
    C -->|No| D[Run doc-adr-reviewer First]
    C -->|Yes| E[Parse Review Report]

    E --> F[Categorize Issues]

    subgraph FixPhases["Fix Phases"]
        F --> F0[Phase 0: Fix Structure Violations]
        F0 --> G[Phase 1: Create Missing Files]
        G --> H[Phase 2: Fix Broken Links]
        H --> I[Phase 3: Fix Element IDs]
        I --> J[Phase 4: Fix Content Issues]
        J --> K[Phase 5: Update References]
        K --> K2[Phase 6: Handle Upstream Drift]
    end

    K2 --> L[Write Fixed ADR]
    L --> M[Generate Fix Report]
    M --> N{Re-run Review?}
    N -->|Yes| O[Invoke doc-adr-reviewer]
    O --> P{Score >= Threshold?}
    P -->|No, iterations < max| F
    P -->|Yes| Q[COMPLETE]
    N -->|No| Q

Fix Phases

修复阶段

Phase 0: Fix Structure Violations (CRITICAL)

阶段0：修复结构违规（CRITICAL）

Fixes ADR documents that are not in nested folders. This phase runs FIRST because all subsequent phases depend on correct folder structure.

Nested Folder Rule: ALL ADR documents MUST be in nested folders regardless of document size.

Required Structure:

ADR Type	Required Location
Monolithic	`docs/05_ADR/ADR-NN_{slug}/ADR-NN_{slug}.md`

Fix Actions:

Issue Code	Issue	Fix Action
REV-STR001	ADR not in nested folder	Create folder, move file, update all links
REV-STR002	ADR folder name doesn't match ADR ID	Rename folder to match
REV-STR003	Monolithic ADR >25KB should be sectioned	Flag for manual review

Structure Fix Workflow:

python

def fix_adr_structure(adr_path: str) -> list[Fix]:
    """Fix ADR structure violations."""
    fixes = []

    filename = os.path.basename(adr_path)
    parent_folder = os.path.dirname(adr_path)

    # Extract ADR ID and slug from filename
    match = re.match(r'ADR-(\d+)_([^/]+)\.md', filename)
    if not match:
        return []  # Cannot auto-fix invalid filename

    adr_id = match.group(1)
    slug = match.group(2)
    expected_folder = f"ADR-{adr_id}_{slug}"

    # Check if already in nested folder
    if os.path.basename(parent_folder) != expected_folder:
        # Create nested folder
        new_folder = os.path.join(os.path.dirname(parent_folder), expected_folder)
        os.makedirs(new_folder, exist_ok=True)

        # Move file
        new_path = os.path.join(new_folder, filename)
        shutil.move(adr_path, new_path)
        fixes.append(f"Moved {adr_path} to {new_path}")

        # Update upstream links in moved file
        content = Path(new_path).read_text()
        updated_content = content.replace('../04_BDD/', '../../04_BDD/')
        updated_content = updated_content.replace('../03_EARS/', '../../03_EARS/')
        updated_content = updated_content.replace('../01_BRD/', '../../01_BRD/')
        Path(new_path).write_text(updated_content)
        fixes.append(f"Updated relative links for nested folder structure")

    return fixes

Link Path Updates After Move:

Original Path	Updated Path
`../04_BDD/BDD-01_slug/BDD-01.md`	`../../04_BDD/BDD-01_slug/BDD-01.md`
`../01_BRD/BRD-01_slug/BRD-01.md`	`../../01_BRD/BRD-01_slug/BRD-01.md`

修复未存放在嵌套文件夹中的ADR文档。该阶段优先运行，因为后续所有阶段都依赖正确的文件夹结构。

嵌套文件夹规则：无论文档大小，所有ADR文档必须存放在嵌套文件夹中。

要求结构：

ADR类型	要求存放位置
单文件ADR	`docs/05_ADR/ADR-NN_{slug}/ADR-NN_{slug}.md`

修复操作：

问题编码	问题描述	修复动作
REV-STR001	ADR未存放在嵌套文件夹中	创建文件夹，移动文件，更新所有链接
REV-STR002	ADR文件夹名称与ADR ID不匹配	重命名文件夹使其匹配
REV-STR003	大小超过25KB的单文件ADR应拆分章节	标记为需人工评审

结构修复工作流：

python

def fix_adr_structure(adr_path: str) -> list[Fix]:
    """Fix ADR structure violations."""
    fixes = []

    filename = os.path.basename(adr_path)
    parent_folder = os.path.dirname(adr_path)

    # Extract ADR ID and slug from filename
    match = re.match(r'ADR-(\d+)_([^/]+)\.md', filename)
    if not match:
        return []  # Cannot auto-fix invalid filename

    adr_id = match.group(1)
    slug = match.group(2)
    expected_folder = f"ADR-{adr_id}_{slug}"

    # Check if already in nested folder
    if os.path.basename(parent_folder) != expected_folder:
        # Create nested folder
        new_folder = os.path.join(os.path.dirname(parent_folder), expected_folder)
        os.makedirs(new_folder, exist_ok=True)

        # Move file
        new_path = os.path.join(new_folder, filename)
        shutil.move(adr_path, new_path)
        fixes.append(f"Moved {adr_path} to {new_path}")

        # Update upstream links in moved file
        content = Path(new_path).read_text()
        updated_content = content.replace('../04_BDD/', '../../04_BDD/')
        updated_content = updated_content.replace('../03_EARS/', '../../03_EARS/')
        updated_content = updated_content.replace('../01_BRD/', '../../01_BRD/')
        Path(new_path).write_text(updated_content)
        fixes.append(f"Updated relative links for nested folder structure")

    return fixes

文件移动后的链接路径更新：

原路径	更新后路径
`../04_BDD/BDD-01_slug/BDD-01.md`	`../../04_BDD/BDD-01_slug/BDD-01.md`
`../01_BRD/BRD-01_slug/BRD-01.md`	`../../01_BRD/BRD-01_slug/BRD-01.md`

Phase 1: Create Missing Files

阶段1：创建缺失文件

Creates files that are referenced but don't exist.

Scope:

Missing File	Action	Template Used
`ADR-00_INDEX.md`	Create ADR index	Index template
`ARCH_*.md`	Create placeholder architecture doc	ARCH template
Reference docs ( `_REF_.md` )	Create placeholder	REF template

ADR Index Template:

markdown

---
title: "ADR-00: Architecture Decision Records Index"
tags:
  - adr
  - index
  - reference
custom_fields:
  document_type: index
  artifact_type: ADR-REFERENCE
  layer: 5
---

创建被引用但不存在的文件。

处理范围：

缺失文件	操作	使用模板
`ADR-00_INDEX.md`	创建ADR索引	索引模板
`ARCH_*.md`	创建架构文档占位符	ARCH模板
参考文档（ `_REF_.md` ）	创建占位符	REF模板

ADR索引模板：

markdown

---
title: "ADR-00: Architecture Decision Records Index"
tags:
  - adr
  - index
  - reference
custom_fields:
  document_type: index
  artifact_type: ADR-REFERENCE
  layer: 5
---

ADR-00: Architecture Decision Records Index

Master index of all Architecture Decision Records for this project.

Active Decisions

ADR ID	Title	Status	Date	Impact
ADR-01	[Title]	Accepted	YYYY-MM-DD	High/Medium/Low

ADR ID	Title	Status	Date	Impact
ADR-01	[Title]	Accepted	YYYY-MM-DD	High/Medium/Low

Superseded Decisions

ADR ID	Title	Superseded By	Date
[None]

ADR ID	Title	Superseded By	Date
[None]

Decision Categories

Category	ADR IDs	Description
Infrastructure		Infrastructure-related decisions
Security		Security architecture decisions
Integration		External integration decisions
Data		Data management decisions

Maintained by doc-adr-fixer. Update when adding new ADRs.


**Architecture Placeholder Template**:

```markdown
---
title: "Architecture Document: [Component Name]"
tags:
  - architecture
  - reference
custom_fields:
  document_type: architecture
  status: placeholder
  created_by: doc-adr-fixer
---

Category	ADR IDs	Description
Infrastructure		Infrastructure-related decisions
Security		Security architecture decisions
Integration		External integration decisions
Data		Data management decisions

Maintained by doc-adr-fixer. Update when adding new ADRs.


**架构文档占位符模板**：

```markdown
---
title: "Architecture Document: [Component Name]"
tags:
  - architecture
  - reference
custom_fields:
  document_type: architecture
  status: placeholder
  created_by: doc-adr-fixer
---

Architecture Document: [Component Name]

Status: Placeholder - Requires completion

1. Overview

[TODO: Document architecture overview]

2. Components

Component	Description	Responsibility
[Name]	[Description]	[What it does]

Component	Description	Responsibility
[Name]	[Description]	[What it does]

3. Interfaces

[TODO: Document component interfaces]

4. Design Decisions

[TODO: Link to relevant ADRs]

Created by doc-adr-fixer as placeholder. Complete this document to resolve broken link issues.

---

[TODO: Link to relevant ADRs]

Created by doc-adr-fixer as placeholder. Complete this document to resolve broken link issues.

---

Phase 2: Fix Broken Links

阶段2：修复断链

Updates links to point to correct locations.

Fix Actions:

Issue Code	Issue	Fix Action
REV-L001	Broken internal link	Update path or create target file
REV-L002	External link unreachable	Add warning comment, keep link
REV-L003	Absolute path used	Convert to relative path
REV-L004	Missing BDD traceability link	Add link to corresponding BDD scenario

Path Resolution Logic:

python

def fix_link_path(adr_location: str, target_path: str) -> str:
    """Calculate correct relative path based on ADR location."""

    # Monolithic ADR: docs/05_ADR/ADR-01.md
    # Sectioned ADR: docs/05_ADR/ADR-01_slug/ADR-01.3_section.md

    if is_sectioned_adr(adr_location):
        # Need to go up one more level
        return "../" + calculate_relative_path(adr_location, target_path)
    else:
        return calculate_relative_path(adr_location, target_path)

Cross-Layer Link Fix:

Source	Target	Link Pattern
ADR	BDD	`../04_BDD/BDD-NN.feature`
ADR	BRD	`../01_BRD/BRD-NN.md`
ADR	SYS	`../06_SYS/SYS-NN.md`

更新链接使其指向正确位置。

修复操作：

问题编码	问题描述	修复动作
REV-L001	内部链接失效	更新路径或创建目标文件
REV-L002	外部链接无法访问	添加警告注释，保留原链接
REV-L003	使用了绝对路径	转换为相对路径
REV-L004	缺少BDD可追溯链接	添加指向对应BDD场景的链接

路径解析逻辑：

python

def fix_link_path(adr_location: str, target_path: str) -> str:
    """Calculate correct relative path based on ADR location."""

    # Monolithic ADR: docs/05_ADR/ADR-01.md
    # Sectioned ADR: docs/05_ADR/ADR-01_slug/ADR-01.3_section.md

    if is_sectioned_adr(adr_location):
        # Need to go up one more level
        return "../" + calculate_relative_path(adr_location, target_path)
    else:
        return calculate_relative_path(adr_location, target_path)

跨层级链接修复：

源文档	目标文档	链接格式
ADR	BDD	`../04_BDD/BDD-NN.feature`
ADR	BRD	`../01_BRD/BRD-NN.md`
ADR	SYS	`../06_SYS/SYS-NN.md`

Phase 3: Fix Element IDs

阶段3：修复元素ID

Converts invalid element IDs to correct format.

Conversion Rules:

Pattern	Issue	Conversion
`ADR.NN.01.SS`	Code 01 invalid for ADR	`ADR.NN.13.SS` (Decision Context)
`DEC-XXX`	Legacy pattern	`ADR.NN.14.SS`
`OPT-XXX`	Legacy pattern	`ADR.NN.15.SS`
`CON-XXX`	Legacy pattern	`ADR.NN.16.SS`

Type Code Mapping (ADR-specific valid codes: 13, 14, 15, 16):

Code	Element Type	Description
13	Decision Context	Background and problem statement
14	Decision Statement	The actual decision made
15	Option Considered	Alternative options evaluated
16	Consequence	Implications of the decision

Invalid Code Conversions:

Invalid Code	Valid Code	Element Type
01	13	Decision Context (was Functional Requirement)
05	14	Decision Statement (was Use Case)
06	16	Consequence (was Acceptance Criteria)

Regex Patterns:

python

undefined

将无效的元素ID转换为正确格式。

转换规则：

格式	问题	转换后格式
`ADR.NN.01.SS`	ADR的类型码01无效	`ADR.NN.13.SS` （决策上下文）
`DEC-XXX`	旧格式	`ADR.NN.14.SS`
`OPT-XXX`	旧格式	`ADR.NN.15.SS`
`CON-XXX`	旧格式	`ADR.NN.16.SS`

类型码映射（ADR专用有效码：13、14、15、16）：

编码	元素类型	描述
13	决策上下文	背景与问题描述
14	决策声明	实际做出的决策内容
15	备选方案评估	评估过的替代方案
16	决策影响	决策带来的后续影响

无效编码转换：

无效编码	有效编码	元素类型
01	13	决策上下文（原功能需求）
05	14	决策声明（原用例）
06	16	决策影响（原验收标准）

正则匹配规则：

python

undefined

Find element IDs with invalid type codes for ADR

invalid_adr_type_01 = r'ADR.(\d{2}).01.(\d{2})' replacement_01 = r'ADR.\1.13.\2'

invalid_adr_type_05 = r'ADR.(\d{2}).05.(\d{2})' replacement_05 = r'ADR.\1.14.\2'

invalid_adr_type_01 = r'ADR.(\d{2}).01.(\d{2})' replacement_01 = r'ADR.\1.13.\2'

invalid_adr_type_05 = r'ADR.(\d{2}).05.(\d{2})' replacement_05 = r'ADR.\1.14.\2'

Find legacy patterns

legacy_dec = r'###\s+DEC-(\d+):' legacy_opt = r'###\s+OPT-(\d+):' legacy_con = r'###\s+CON-(\d+):'

---

legacy_dec = r'###\s+DEC-(\d+):' legacy_opt = r'###\s+OPT-(\d+):' legacy_con = r'###\s+CON-(\d+):'

---

Phase 4: Fix Content Issues

阶段4：修复内容问题

Addresses placeholders and incomplete content.

Fix Actions:

Issue Code	Issue	Fix Action
REV-P001	`[TODO]` placeholder	Flag for manual completion (cannot auto-fix)
REV-P002	`[TBD]` placeholder	Flag for manual completion (cannot auto-fix)
REV-P003	Template date `YYYY-MM-DD`	Replace with current date
REV-P004	Template name `[Name]`	Replace with metadata author or flag
REV-P005	Empty section	Add minimum template content
REV-P006	Missing decision status	Add "Proposed" as default status

Auto-Replacements:

python

replacements = {
    'YYYY-MM-DDTHH:MM:SS': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    'YYYY-MM-DD': datetime.now().strftime('%Y-%m-%d'),
    'MM/DD/YYYY': datetime.now().strftime('%m/%d/%Y'),
    '[Current date]': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    '[Status]': 'Proposed',
}

ADR-Specific Content Fixes:

Section	Missing Content	Auto-Fill
Status	Empty	"Proposed"
Decision Date	Empty	Current date
Deciders	Empty	"[Pending assignment]"

处理占位符和不完整内容。

修复操作：

问题编码	问题描述	修复动作
REV-P001	存在 `[TODO]` 占位符	标记为需人工补全（无法自动修复）
REV-P002	存在 `[TBD]` 占位符	标记为需人工补全（无法自动修复）
REV-P003	模板日期 `YYYY-MM-DD`	替换为当前日期
REV-P004	模板名称 `[Name]`	替换为元数据中的作者信息或标记待补全
REV-P005	章节为空	添加最小模板内容
REV-P006	缺少决策状态	添加默认状态「Proposed」

自动替换规则：

python

replacements = {
    'YYYY-MM-DDTHH:MM:SS': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    'YYYY-MM-DD': datetime.now().strftime('%Y-%m-%d'),
    'MM/DD/YYYY': datetime.now().strftime('%m/%d/%Y'),
    '[Current date]': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    '[Status]': 'Proposed',
}

ADR专属内容修复：

章节	缺失内容	自动填充值
状态	为空	"Proposed"
决策日期	为空	当前日期
决策人	为空	"[Pending assignment]"

Phase 5: Update References

阶段5：更新引用

Ensures traceability and cross-references are correct.

Fix Actions:

Issue	Fix Action
Missing `@ref:` for created files	Add reference tag
Incorrect cross-ADR path	Update to correct relative path
Missing BDD traceability	Add `@trace: BDD-NN.SS` tag
Missing BRD alignment	Add `@trace: BRD-NN.SS` tag

Traceability Matrix Update:

markdown

undefined

确保可追溯性和交叉引用正确。

修复操作：

问题	修复动作
已创建文件缺少 `@ref:` 标记	添加引用标签
跨ADR路径不正确	更新为正确的相对路径
缺少BDD追溯关系	添加 `@trace: BDD-NN.SS` 标签
缺少BRD对齐关系	添加 `@trace: BRD-NN.SS` 标签

追溯矩阵更新：

markdown

undefined

Traceability

ADR Element	Traces To	Type
ADR.01.14.01	BDD.01.09.03	Behavior Implementation
ADR.01.13.01	BRD.01.22.05	Business Context

---

ADR Element	Traces To	Type
ADR.01.14.01	BDD.01.09.03	Behavior Implementation
ADR.01.13.01	BRD.01.22.05	Business Context

---

Phase 6: Handle Upstream Drift (Auto-Merge)

阶段6：处理上游漂移（自动合并）

Addresses issues where upstream source documents (BDD) have changed since ADR creation. Implements tiered auto-merge with version management.

Upstream/Downstream Context:

Direction	Layer	Artifact	Relationship
Upstream	4	BDD	Provides behavior specifications that drive decisions
Current	5	ADR	Architecture Decision Records
Downstream	6	SYS	System design implementing decisions

ADR ID Pattern:

ADR-NN-SS

where:

```
NN
```
= Module number (01-99)
```
SS
```
= Sequence number within module (01-99)
Example:
```
ADR-01-15
```
= Module 01, Decision 15

解决ADR创建后上游源文档（BDD）发生变更的问题，实现带版本管理的分层自动合并。

上游/下游上下文：

方向	层级	产物	关系
上游	4	BDD	提供驱动决策的行为规范
当前	5	ADR	架构决策记录
下游	6	SYS	实现决策的系统设计

ADR ID格式：

ADR-NN-SS

，其中：

```
NN
```
= 模块编号（01-99）
```
SS
```
= 模块内序号（01-99）
示例：
```
ADR-01-15
```
= 模块01，第15条决策

Tiered Auto-Merge System

分层自动合并系统

Change Percentage Calculation:

python

def calculate_drift_percentage(current_hash: str, upstream_hash: str,
                                current_content: str, upstream_content: str) -> float:
    """Calculate percentage of content change between versions."""
    if current_hash == upstream_hash:
        return 0.0

    # Line-based diff calculation
    current_lines = set(current_content.strip().split('\n'))
    upstream_lines = set(upstream_content.strip().split('\n'))

    added = upstream_lines - current_lines
    removed = current_lines - upstream_lines
    total_changes = len(added) + len(removed)
    total_lines = max(len(current_lines), len(upstream_lines), 1)

    return (total_changes / total_lines) * 100

Tier Definitions:

Tier	Change %	Action	Version Increment	Human Review
Tier 1	< 5%	Auto-merge decision updates	Patch (x.x.+1)	No
Tier 2	5-15%	Auto-merge with changelog	Minor (x.+1.0)	No
Tier 3	> 15%	Archive + regenerate	Major (+1.0.0)	Yes

变更比例计算：

python

def calculate_drift_percentage(current_hash: str, upstream_hash: str,
                                current_content: str, upstream_content: str) -> float:
    """Calculate percentage of content change between versions."""
    if current_hash == upstream_hash:
        return 0.0

    # Line-based diff calculation
    current_lines = set(current_content.strip().split('\n'))
    upstream_lines = set(upstream_content.strip().split('\n'))

    added = upstream_lines - current_lines
    removed = current_lines - upstream_lines
    total_changes = len(added) + len(removed)
    total_lines = max(len(current_lines), len(upstream_lines), 1)

    return (total_changes / total_lines) * 100

分层定义：

层级	变更占比	操作	版本号递增规则	人工评审
层级1	< 5%	自动合并决策更新	补丁版本（x.x.+1）	不需要
层级2	5-15%	自动合并并生成变更日志	次版本（x.+1.0）	不需要
层级3	> 15%	归档+重新生成	主版本（+1.0.0）	需要

Tier 1: Minor Updates (< 5% change)

层级1：小幅更新（<5%变更）

Trigger: Small upstream modifications (typos, clarifications, minor additions)

Auto-Merge Actions:

Update affected
```
@ref:
```
tags with new upstream version
Refresh decision context if wording changed
Increment ADR patch version (e.g.,
```
1.0.0
```
->
```
1.0.1
```
)
Log change in drift cache

Example Tier 1 Fix:

markdown

<!-- Before -->
@ref: BDD-01.09.03 (v1.2.0)

<!-- After (auto-merged) -->
@ref: BDD-01.09.03 (v1.2.1)
<!-- Tier 1 auto-merge: Minor upstream update (2.3% change) - 2026-02-10 -->

触发条件：上游小幅修改（拼写错误、表述澄清、小幅新增内容）

自动合并操作：

更新受影响的
```
@ref:
```
标签为新的上游版本
如果表述发生变更则刷新决策上下文
递增ADR补丁版本（例如
```
1.0.0
```
->
```
1.0.1
```
）
在漂移缓存中记录变更

层级1修复示例：

markdown

<!-- Before -->
@ref: BDD-01.09.03 (v1.2.0)

<!-- After (auto-merged) -->
@ref: BDD-01.09.03 (v1.2.1)
<!-- Tier 1 auto-merge: Minor upstream update (2.3% change) - 2026-02-10 -->

Tier 2: Moderate Updates (5-15% change)

层级2：中度更新（5-15%变更）

Trigger: Meaningful upstream changes (new scenarios, modified behaviors)

Auto-Merge Actions:

Apply all Tier 1 actions
Generate detailed changelog section
Update decision rationale if affected
Mark decisions as needing review with
```
[REVIEW-SUGGESTED]
```
Increment ADR minor version (e.g.,
```
1.0.1
```
->
```
1.1.0
```
)
Add changelog block to ADR

Changelog Block Format:

markdown

undefined

触发条件：上游有实质变更（新增场景、修改行为）

自动合并操作：

执行所有层级1的操作
生成详细的变更日志章节
如果受影响则更新决策依据
用
```
[REVIEW-SUGGESTED]
```
标记需要评审的决策
递增ADR次版本（例如
```
1.0.1
```
->
```
1.1.0
```
）
向ADR中添加变更日志块

变更日志块格式：

markdown

undefined

Upstream Change Log

Version 1.1.0 (2026-02-10)

Source: BDD-01.feature (v1.3.0) Change Percentage: 8.7% Auto-Merge Tier: 2

Change Type	Description	ADR Impact
Added	Scenario: Error handling for timeout	Decision ADR-01-03 context updated
Modified	Scenario: Authentication flow steps	Decision ADR-01-01 rationale refreshed
Removed	None	N/A

Decisions Flagged for Review:

ADR-01-03 [REVIEW-SUGGESTED]: New error handling scenario may affect retry strategy

---

Source: BDD-01.feature (v1.3.0) Change Percentage: 8.7% Auto-Merge Tier: 2

Change Type	Description	ADR Impact
Added	Scenario: Error handling for timeout	Decision ADR-01-03 context updated
Modified	Scenario: Authentication flow steps	Decision ADR-01-01 rationale refreshed
Removed	None	N/A

Decisions Flagged for Review:

ADR-01-03 [REVIEW-SUGGESTED]: New error handling scenario may affect retry strategy

---

Tier 3: Major Updates (> 15% change)

层级3：重大更新（>15%变更）

Trigger: Substantial upstream restructuring or new requirements

Actions (Requires Human Review):

Archive current ADR version (no deletion)
Create archive manifest
Mark all decisions as
```
[SUPERSEDED]
```
(not deleted)
Trigger regeneration workflow
Increment major version (e.g.,
```
1.1.0
```
->
```
2.0.0
```
)
Generate new ADR with fresh decision IDs

No Deletion Policy:

Decisions are NEVER deleted. Instead, they are marked as superseded:

markdown

undefined

触发条件：上游发生大幅结构调整或新增需求

操作（需要人工评审）：

归档当前ADR版本（不删除）
创建归档清单
将所有决策标记为
```
[SUPERSEDED]
```
（不删除）
触发重新生成工作流
递增主版本（例如
```
1.1.0
```
->
```
2.0.0
```
）
生成带新决策ID的ADR

永不删除政策：决策永远不会被删除，只会被标记为已替代：

markdown

undefined

ADR-01-05: Authentication Token Strategy [SUPERSEDED]

Superseded by: ADR-01-15 (v2.0.0) Superseded date: 2026-02-10 Reason: Upstream BDD restructured authentication flow

Original Decision (preserved for audit): ...


**Archive Manifest Format** (`ADR-NN_archive_manifest.json`):

```json
{
  "archive_version": "1.0",
  "archive_date": "2026-02-10T16:00:00",
  "archived_adr": "ADR-01",
  "archived_version": "1.1.0",
  "new_version": "2.0.0",
  "trigger": {
    "type": "tier_3_drift",
    "upstream_document": "BDD-01.feature",
    "change_percentage": 23.5,
    "upstream_version_before": "1.2.0",
    "upstream_version_after": "2.0.0"
  },
  "superseded_decisions": [
    {
      "id": "ADR-01-05",
      "title": "Authentication Token Strategy",
      "superseded_by": "ADR-01-15",
      "reason": "Upstream BDD restructured authentication flow"
    },
    {
      "id": "ADR-01-07",
      "title": "Session Management Approach",
      "superseded_by": "ADR-01-16",
      "reason": "New session requirements in BDD"
    }
  ],
  "preserved_decisions": [
    {
      "id": "ADR-01-01",
      "title": "Database Selection",
      "status": "unchanged",
      "carried_forward_as": "ADR-01-01"
    }
  ],
  "archive_location": "docs/05_ADR/archive/ADR-01_v1.1.0/"
}

Superseded by: ADR-01-15 (v2.0.0) Superseded date: 2026-02-10 Reason: Upstream BDD restructured authentication flow

Original Decision (preserved for audit): ...


**归档清单格式**（`ADR-NN_archive_manifest.json`）：

```json
{
  "archive_version": "1.0",
  "archive_date": "2026-02-10T16:00:00",
  "archived_adr": "ADR-01",
  "archived_version": "1.1.0",
  "new_version": "2.0.0",
  "trigger": {
    "type": "tier_3_drift",
    "upstream_document": "BDD-01.feature",
    "change_percentage": 23.5,
    "upstream_version_before": "1.2.0",
    "upstream_version_after": "2.0.0"
  },
  "superseded_decisions": [
    {
      "id": "ADR-01-05",
      "title": "Authentication Token Strategy",
      "superseded_by": "ADR-01-15",
      "reason": "Upstream BDD restructured authentication flow"
    },
    {
      "id": "ADR-01-07",
      "title": "Session Management Approach",
      "superseded_by": "ADR-01-16",
      "reason": "New session requirements in BDD"
    }
  ],
  "preserved_decisions": [
    {
      "id": "ADR-01-01",
      "title": "Database Selection",
      "status": "unchanged",
      "carried_forward_as": "ADR-01-01"
    }
  ],
  "archive_location": "docs/05_ADR/archive/ADR-01_v1.1.0/"
}

Enhanced Drift Cache

增强型漂移缓存

Updated
.drift_cache.json
Structure:

json

{
  "cache_version": "2.0",
  "adr_id": "ADR-01",
  "adr_version": "1.1.0",
  "adr_updated": "2026-02-10T16:00:00",
  "drift_reviewed": "2026-02-10T16:00:00",
  "upstream_tracking": {
    "BDD": {
      "document": "../../04_BDD/BDD-01.feature",
      "tracked_version": "1.3.0",
      "content_hash": "a1b2c3d4e5f6...",
      "last_sync": "2026-02-10T16:00:00"
    }
  },
  "downstream_tracking": {
    "SYS": {
      "document": "../../06_SYS/SYS-01.md",
      "notified_version": "1.1.0",
      "notification_date": "2026-02-10T16:00:00"
    }
  },
  "merge_history": [
    {
      "date": "2026-02-10T16:00:00",
      "tier": 2,
      "change_percentage": 8.7,
      "upstream_document": "BDD-01.feature",
      "version_before": "1.0.1",
      "version_after": "1.1.0",
      "decisions_updated": ["ADR-01-01", "ADR-01-03"],
      "decisions_flagged": ["ADR-01-03"],
      "auto_merged": true
    },
    {
      "date": "2026-02-08T10:00:00",
      "tier": 1,
      "change_percentage": 2.3,
      "upstream_document": "BDD-01.feature",
      "version_before": "1.0.0",
      "version_after": "1.0.1",
      "decisions_updated": ["ADR-01-02"],
      "decisions_flagged": [],
      "auto_merged": true
    }
  ],
  "acknowledged_drift": [
    {
      "document": "BDD-01.feature",
      "acknowledged_date": "2026-02-07",
      "acknowledged_version": "1.1.5",
      "reason": "Reviewed - documentation-only changes, no ADR impact"
    }
  ]
}

更新后的
.drift_cache.json
结构：

json

{
  "cache_version": "2.0",
  "adr_id": "ADR-01",
  "adr_version": "1.1.0",
  "adr_updated": "2026-02-10T16:00:00",
  "drift_reviewed": "2026-02-10T16:00:00",
  "upstream_tracking": {
    "BDD": {
      "document": "../../04_BDD/BDD-01.feature",
      "tracked_version": "1.3.0",
      "content_hash": "a1b2c3d4e5f6...",
      "last_sync": "2026-02-10T16:00:00"
    }
  },
  "downstream_tracking": {
    "SYS": {
      "document": "../../06_SYS/SYS-01.md",
      "notified_version": "1.1.0",
      "notification_date": "2026-02-10T16:00:00"
    }
  },
  "merge_history": [
    {
      "date": "2026-02-10T16:00:00",
      "tier": 2,
      "change_percentage": 8.7,
      "upstream_document": "BDD-01.feature",
      "version_before": "1.0.1",
      "version_after": "1.1.0",
      "decisions_updated": ["ADR-01-01", "ADR-01-03"],
      "decisions_flagged": ["ADR-01-03"],
      "auto_merged": true
    },
    {
      "date": "2026-02-08T10:00:00",
      "tier": 1,
      "change_percentage": 2.3,
      "upstream_document": "BDD-01.feature",
      "version_before": "1.0.0",
      "version_after": "1.0.1",
      "decisions_updated": ["ADR-01-02"],
      "decisions_flagged": [],
      "auto_merged": true
    }
  ],
  "acknowledged_drift": [
    {
      "document": "BDD-01.feature",
      "acknowledged_date": "2026-02-07",
      "acknowledged_version": "1.1.5",
      "reason": "Reviewed - documentation-only changes, no ADR impact"
    }
  ]
}

Auto-Merge Decision Flow

自动合并决策流程

mermaid

flowchart TD
    A[Detect Upstream Drift] --> B[Calculate Change %]
    B --> C{Change < 5%?}

    C -->|Yes| D[Tier 1: Auto-Merge]
    D --> D1[Update @ref tags]
    D1 --> D2[Increment patch version]
    D2 --> D3[Log to drift cache]
    D3 --> Z[Complete]

    C -->|No| E{Change 5-15%?}

    E -->|Yes| F[Tier 2: Auto-Merge + Changelog]
    F --> F1[Apply Tier 1 actions]
    F1 --> F2[Generate changelog block]
    F2 --> F3[Mark REVIEW-SUGGESTED]
    F3 --> F4[Increment minor version]
    F4 --> F5[Log to merge history]
    F5 --> Z

    E -->|No| G[Tier 3: Archive + Regenerate]
    G --> G1[Create archive manifest]
    G1 --> G2[Archive current version]
    G2 --> G3[Mark decisions SUPERSEDED]
    G3 --> G4[Increment major version]
    G4 --> G5[Trigger regeneration]
    G5 --> G6[Notify downstream SYS]
    G6 --> H[Human Review Required]

mermaid

flowchart TD
    A[Detect Upstream Drift] --> B[Calculate Change %]
    B --> C{Change < 5%?}

    C -->|Yes| D[Tier 1: Auto-Merge]
    D --> D1[Update @ref tags]
    D1 --> D2[Increment patch version]
    D2 --> D3[Log to drift cache]
    D3 --> Z[Complete]

    C -->|No| E{Change 5-15%?}

    E -->|Yes| F[Tier 2: Auto-Merge + Changelog]
    F --> F1[Apply Tier 1 actions]
    F1 --> F2[Generate changelog block]
    F2 --> F3[Mark REVIEW-SUGGESTED]
    F3 --> F4[Increment minor version]
    F4 --> F5[Log to merge history]
    F5 --> Z

    E -->|No| G[Tier 3: Archive + Regenerate]
    G --> G1[Create archive manifest]
    G1 --> G2[Archive current version]
    G2 --> G3[Mark decisions SUPERSEDED]
    G3 --> G4[Increment major version]
    G4 --> G5[Trigger regeneration]
    G5 --> G6[Notify downstream SYS]
    G6 --> H[Human Review Required]

Downstream Notification

下游通知

When ADR changes (any tier), notify downstream SYS documents:

markdown

<!-- Downstream notification added to SYS-01.md -->
<!-- ADR-DRIFT-NOTIFICATION: ADR-01 updated to v1.1.0 (2026-02-10) -->
<!-- Tier 2 merge: 8.7% upstream change from BDD-01.feature -->
<!-- Decisions potentially affecting this SYS: ADR-01-01, ADR-01-03 -->
<!-- Review recommended for: Section 4 (Authentication Design) -->

当ADR发生变更（任意层级）时，向下游SYS文档发送通知：

markdown

<!-- Downstream notification added to SYS-01.md -->
<!-- ADR-DRIFT-NOTIFICATION: ADR-01 updated to v1.1.0 (2026-02-10) -->
<!-- Tier 2 merge: 8.7% upstream change from BDD-01.feature -->
<!-- Decisions potentially affecting this SYS: ADR-01-01, ADR-01-03 -->
<!-- Review recommended for: Section 4 (Authentication Design) -->

Command Options for Phase 6

阶段6命令选项

Option	Default	Description
`--auto-merge`	true	Enable tiered auto-merge system
`--merge-tier-override`	none	Force specific tier (1, 2, or 3)
`--skip-archive`	false	Skip archiving for Tier 3 (not recommended)
`--notify-downstream`	true	Send notifications to SYS documents
`--generate-changelog`	true	Generate changelog for Tier 2+
`--preserve-superseded`	true	Keep superseded decisions (required)

选项	默认值	描述
`--auto-merge`	true	启用分层自动合并系统
`--merge-tier-override`	none	强制指定合并层级（1、2或3）
`--skip-archive`	false	层级3变更时跳过归档（不推荐）
`--notify-downstream`	true	向SYS文档发送通知
`--generate-changelog`	true	层级2及以上变更时生成变更日志
`--preserve-superseded`	true	保留已替代的决策（必填）

Command Usage

命令用法

Basic Usage

基础用法

bash

undefined

bash

undefined

Fix ADR based on latest review

/doc-adr-fixer ADR-01

Fix with explicit review report

/doc-adr-fixer ADR-01 --review-report ADR-01.R_review_report_v001.md

Fix and re-run review

/doc-adr-fixer ADR-01 --revalidate

Fix with iteration limit

/doc-adr-fixer ADR-01 --revalidate --max-iterations 3

undefined

/doc-adr-fixer ADR-01 --revalidate --max-iterations 3

undefined

Options

选项

Option	Default	Description
`--review-report`	latest	Specific review report to use
`--revalidate`	false	Run reviewer after fixes
`--max-iterations`	3	Max fix-review cycles
`--fix-types`	all	Specific fix types (comma-separated)
`--create-missing`	true	Create missing reference files
`--backup`	true	Backup ADR before fixing
`--dry-run`	false	Preview fixes without applying
`--acknowledge-drift`	false	Interactive drift acknowledgment mode
`--update-drift-cache`	true	Update .drift_cache.json after fixes

选项	默认值	描述
`--review-report`	latest	指定要使用的评审报告
`--revalidate`	false	修复完成后运行评审工具
`--max-iterations`	3	最大修复-评审循环次数
`--fix-types`	all	指定修复类型（逗号分隔）
`--create-missing`	true	创建缺失的参考文件
`--backup`	true	修复前备份ADR
`--dry-run`	false	预览修复内容不实际执行
`--acknowledge-drift`	false	交互式漂移确认模式
`--update-drift-cache`	true	修复完成后更新.drift_cache.json

Fix Types

修复类型

Type	Description
`missing_files`	Create missing index, architecture docs
`broken_links`	Fix link paths
`element_ids`	Convert invalid/legacy element IDs
`content`	Fix placeholders, dates, status
`references`	Update traceability and cross-references
`drift`	Handle upstream drift detection issues
`all`	All fix types (default)

类型	描述
`missing_files`	创建缺失的索引、架构文档
`broken_links`	修复链接路径
`element_ids`	转换无效/旧版元素ID
`content`	修复占位符、日期、状态
`references`	更新追溯关系和交叉引用
`drift`	处理上游漂移检测问题
`all`	所有修复类型（默认）

Output Artifacts

输出产物

Fix Report

修复报告

Nested Folder Rule: ALL ADRs use nested folders (

ADR-NN_{slug}/

) regardless of size. Fix reports are stored alongside the ADR document in the nested folder.

File Naming:

ADR-NN.F_fix_report_vNNN.md

Location: Inside the ADR nested folder:

docs/ADR/ADR-NN_{slug}/

Structure:

markdown

---
title: "ADR-NN.F: Fix Report v001"
tags:
  - adr
  - fix-report
  - quality-assurance
custom_fields:
  document_type: fix-report
  artifact_type: ADR-FIX
  layer: 5
  parent_doc: ADR-NN
  source_review: ADR-NN.R_review_report_v001.md
  fix_date: "YYYY-MM-DDTHH:MM:SS"
  fix_tool: doc-adr-fixer
  fix_version: "1.0"
---

嵌套文件夹规则：无论大小，所有ADR都使用嵌套文件夹（

ADR-NN_{slug}/

）存储。修复报告与ADR文档同存放在嵌套文件夹中。

文件命名：

ADR-NN.F_fix_report_vNNN.md

存储位置：ADR嵌套文件夹内：

docs/ADR/ADR-NN_{slug}/

结构：

markdown

---
title: "ADR-NN.F: Fix Report v001"
tags:
  - adr
  - fix-report
  - quality-assurance
custom_fields:
  document_type: fix-report
  artifact_type: ADR-FIX
  layer: 5
  parent_doc: ADR-NN
  source_review: ADR-NN.R_review_report_v001.md
  fix_date: "YYYY-MM-DDTHH:MM:SS"
  fix_tool: doc-adr-fixer
  fix_version: "1.0"
---

ADR-NN Fix Report v001

Summary

Metric	Value
Source Review	ADR-NN.R_review_report_v001.md
Issues in Review	12
Issues Fixed	10
Issues Remaining	2 (manual review required)
Files Created	2
Files Modified	3

Metric	Value
Source Review	ADR-NN.R_review_report_v001.md
Issues in Review	12
Issues Fixed	10
Issues Remaining	2 (manual review required)
Files Created	2
Files Modified	3

Files Created

File	Type	Location
ADR-00_INDEX.md	ADR Index	docs/05_ADR/
ARCH_Authentication.md	Arch Placeholder	docs/00_REF/architecture/

File	Type	Location
ADR-00_INDEX.md	ADR Index	docs/05_ADR/
ARCH_Authentication.md	Arch Placeholder	docs/00_REF/architecture/

Fixes Applied

#	Issue Code	Issue	Fix Applied	File
1	REV-L001	Broken index link	Created ADR-00_INDEX.md	ADR-01.md
2	REV-L001	Broken arch link	Created placeholder ARCH file	ADR-01.md
3	REV-N004	Element type 01 invalid	Converted to type 13	ADR-01.md
4	REV-L003	Absolute path used	Converted to relative	ADR-02.md

#	Issue Code	Issue	Fix Applied	File
1	REV-L001	Broken index link	Created ADR-00_INDEX.md	ADR-01.md
2	REV-L001	Broken arch link	Created placeholder ARCH file	ADR-01.md
3	REV-N004	Element type 01 invalid	Converted to type 13	ADR-01.md
4	REV-L003	Absolute path used	Converted to relative	ADR-02.md

Issues Requiring Manual Review

#	Issue Code	Issue	Location	Reason
1	REV-P001	[TODO] placeholder	ADR-01:L45	Architecture expertise needed
2	REV-D001	BDD drift detected	ADR-01:L120	Review behavior changes

#	Issue Code	Issue	Location	Reason
1	REV-P001	[TODO] placeholder	ADR-01:L45	Architecture expertise needed
2	REV-D001	BDD drift detected	ADR-01:L120	Review behavior changes

Validation After Fix

Metric	Before	After	Delta
Review Score	88	95	+7
Errors	3	0	-3
Warnings	5	2	-3

Metric	Before	After	Delta
Review Score	88	95	+7
Errors	3	0	-3
Warnings	5	2	-3

Next Steps

Complete ARCH_Authentication.md placeholder
Address remaining [TODO] placeholders
Review BDD drift and update decision if needed
Run
```
/doc-adr-reviewer ADR-01
```
to verify fixes

---

Complete ARCH_Authentication.md placeholder
Address remaining [TODO] placeholders
Review BDD drift and update decision if needed
Run
```
/doc-adr-reviewer ADR-01
```
to verify fixes

---

Integration with Autopilot

与Autopilot集成

This skill is invoked by

doc-adr-autopilot

in the Review -> Fix cycle:

mermaid

flowchart LR
    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        A[doc-adr-reviewer] --> B{Score >= 90?}
        B -->|No| C[doc-adr-fixer]
        C --> D{Iteration < Max?}
        D -->|Yes| A
        D -->|No| E[Flag for Manual Review]
        B -->|Yes| F[PASS]
    end

Autopilot Integration Points:

Phase	Action	Skill
Phase 5a	Run initial review	`doc-adr-reviewer`
Phase 5b	Apply fixes if issues found	`doc-adr-fixer`
Phase 5c	Re-run review	`doc-adr-reviewer`
Phase 5d	Repeat until pass or max iterations	Loop

该skill会在「评审→修复」循环中被

doc-adr-autopilot

调用：

mermaid

flowchart LR
    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        A[doc-adr-reviewer] --> B{Score >= 90?}
        B -->|No| C[doc-adr-fixer]
        C --> D{Iteration < Max?}
        D -->|Yes| A
        D -->|No| E[Flag for Manual Review]
        B -->|Yes| F[PASS]
    end

Autopilot集成点：

阶段	操作	Skill
阶段5a	运行初始评审	`doc-adr-reviewer`
阶段5b	发现问题后执行修复	`doc-adr-fixer`
阶段5c	重新运行评审	`doc-adr-reviewer`
阶段5d	重复直到通过或达到最大迭代次数	循环

Error Handling

错误处理

Recovery Actions

恢复操作

Error	Action
Review report not found	Prompt to run `doc-adr-reviewer` first
Cannot create file (permissions)	Log error, continue with other fixes
Cannot parse review report	Abort with clear error message
Max iterations exceeded	Generate report, flag for manual review

错误	处理动作
未找到评审报告	提示先运行 `doc-adr-reviewer`
无法创建文件（权限问题）	记录错误，继续执行其他修复
无法解析评审报告	终止并返回清晰的错误信息
超过最大迭代次数	生成报告，标记为需人工评审

Backup Strategy

备份策略

Before applying any fixes:

Create backup in
```
tmp/backup/ADR-NN_YYYYMMDD_HHMMSS/
```
Copy all ADR files to backup location
Apply fixes to original files
If error during fix, restore from backup

应用任何修复前：

在
```
tmp/backup/ADR-NN_YYYYMMDD_HHMMSS/
```
路径下创建备份
复制所有ADR文件到备份位置
对原文件执行修复
如果修复过程中发生错误，从备份恢复

Related Skills

Version History

版本历史

Version	Date	Changes
2.1	2026-02-11	Structure Compliance: Added Phase 0 for nested folder rule enforcement (REV-STR001-STR003); Runs FIRST before other fix phases
2.0	2026-02-10	Enhanced Phase 6 with tiered auto-merge system; Three-tier thresholds (Tier 1 <5%, Tier 2 5-15%, Tier 3 >15%); No deletion policy - superseded decisions preserved; Archive manifest for Tier 3; Enhanced drift cache with merge history; Auto-generated ADR IDs (ADR-NN-SS pattern); Downstream SYS notification; Change percentage calculation
1.0	2026-02-10	Initial skill creation; 6-phase fix workflow; ADR Index and Architecture file creation; Element ID conversion (types 13, 14, 15, 16); Broken link fixes; BDD/BRD upstream drift handling; Integration with autopilot Review->Fix cycle

版本	日期	变更内容
2.1	2026-02-11	结构合规：新增阶段0强制执行嵌套文件夹规则（REV-STR001-STR003），优先于其他修复阶段运行
2.0	2026-02-10	阶段6新增分层自动合并系统；三级阈值（层级1<5%、层级2 5-15%、层级3>15%）；永不删除政策，保留已替代决策；层级3变更生成归档清单；增强型漂移缓存带合并历史；自动生成ADR ID（ADR-NN-SS格式）；下游SYS通知；变更比例计算
1.0	2026-02-10	初始skill创建；6阶段修复工作流；ADR索引和架构文件创建；元素ID转换（类型13、14、15、16）；断链修复；BDD/BRD上游漂移处理；与autopilot的「评审→修复」循环集成

Skill	Relationship
`doc-adr-reviewer`	Provides review report (input)
`doc-adr-autopilot`	Orchestrates Review -> Fix cycle
`doc-adr-validator`	Structural validation
`doc-naming`	Element ID standards
`doc-adr`	ADR creation rules
`doc-bdd`	Upstream behavior reference
`doc-brd`	Upstream business context

Skill	关系
`doc-adr-reviewer`	提供评审报告（输入）
`doc-adr-autopilot`	编排「评审→修复」循环
`doc-adr-validator`	结构校验
`doc-naming`	元素ID规范
`doc-adr`	ADR创建规则
`doc-bdd`	上游行为参考
`doc-brd`	上游业务上下文