doc-bdd-fixer（文档 bdd 修复程序）

doc-bdd-fixer

Purpose

Automated fix skill that reads the latest audit/review report and applies fixes to BDD (Behavior-Driven Development) documents. This skill bridges the gap between doc-bdd-reviewer/doc-bdd-audit (which identify issues) and the corrected BDD, enabling iterative improvement cycles.

Layer: 4 (BDD Quality Improvement)

Upstream: BDD document, Audit/Review Report (BDD-NN.A_audit_report_vNNN.md preferred, BDD-NN.R_review_report_vNNN.md legacy), EARS (source requirements)

Downstream: Fixed BDD, Fix Report (BDD-NN.F_fix_report_vNNN.md)

When to Use This Skill

Use doc-bdd-fixer when:

• After Review: Run after doc-bdd-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 BDD based on review reports

Do NOT use when:

• No audit/review report exists (run doc-bdd-audit or doc-bdd-reviewer first)
• Creating new BDD (use doc-bdd or doc-bdd-autopilot)
• Only need validation (use doc-bdd-validator)

Skill Dependencies

Workflow Overview

flowchart TD
  A[Input: BDD Path] --> B[Find Latest Audit/Review Report]
  B --> C{Report Found?}
  C -->|No| D[Run doc-bdd-audit or doc-bdd-reviewer First]
  C -->|Yes| E[Parse 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 BDD]
    L --> M[Generate Fix Report]
    M --> N{Re-run Review?}
    N -->|Yes| O[Invoke doc-bdd-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)

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

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

Required Structure:

Fix Actions:

Structure Fix Workflow:

def fix_bdd_structure(bdd_path: str) -> list[Fix]:
    """Fix BDD structure violations."""
    fixes = []

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

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

    bdd_id = match.group(1)
    slug = match.group(2)
    expected_folder = f"BDD-{bdd_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(bdd_path, new_path)
        fixes.append(f"Moved {bdd_path} to {new_path}")

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

    return fixes

Link Path Updates After Move:

Phase 1: Create Missing Files

Creates files that are referenced but don't exist.

Scope:

BDD Glossary Template:

---
title: "BDD-00: Behavior Glossary"
tags:
  - bdd
  - glossary
  - reference
custom_fields:
  document_type: glossary
  artifact_type: BDD-REFERENCE
  layer: 4
---

# BDD-00: Behavior Glossary

Common terminology used across all BDD Feature Documents.

## Gherkin Keywords

| Term | Definition | Context |
|------|------------|---------|
| Feature | High-level behavior description | Feature header |
| Scenario | Specific test case | Test definition |
| Scenario Outline | Parameterized scenario | Data-driven tests |
| Given | Precondition setup | Context |
| When | Action trigger | Event |
| Then | Expected outcome | Assertion |
| And | Additional step | Continuation |
| But | Negative continuation | Exception |
| Background | Shared preconditions | Reusable setup |
| Examples | Data table for outlines | Test data |

## Step Definition Terms

| Term | Definition | Context |
|------|------------|---------|
| Step Definition | Code binding for Gherkin step | Implementation |
| World | Shared context object | State management |
| Hook | Before/After lifecycle method | Setup/teardown |
| Tag | Scenario/Feature annotation | Filtering |

## Domain Terms

<!-- Add project-specific terminology below -->

| Term | Definition | Context |
|------|------------|---------|
| [Term] | [Definition] | [Where used] |

Feature Placeholder Template:

# language: en
# encoding: UTF-8

@placeholder @needs-completion
Feature: [Feature Name]
  As a [role]
  I want [capability]
  So that [benefit]

  # TODO: Created by doc-bdd-fixer as placeholder
  # Complete this feature file to resolve broken link issues

  Background:
    Given [TODO: Define shared preconditions]

  @todo
  Scenario: [TODO: Define scenario name]
    Given [TODO: Define precondition]
    When [TODO: Define action]
    Then [TODO: Define expected outcome]

Step Definitions Placeholder Template:

---
title: "BDD Step Definitions: [Module Name]"
tags:
  - bdd
  - step-definitions
  - reference
custom_fields:
  document_type: step-definitions
  status: placeholder
  created_by: doc-bdd-fixer
---

# BDD Step Definitions: [Module Name]

> **Status**: Placeholder - Requires completion

## 1. Overview

[TODO: Document step definitions overview]

## 2. Given Steps

| Step Pattern | Implementation | Status |
|--------------|----------------|--------|
| `Given [pattern]` | [TODO] | Placeholder |

## 3. When Steps

| Step Pattern | Implementation | Status |
|--------------|----------------|--------|
| `When [pattern]` | [TODO] | Placeholder |

## 4. Then Steps

| Step Pattern | Implementation | Status |
|--------------|----------------|--------|
| `Then [pattern]` | [TODO] | Placeholder |

## 5. Shared Helpers

[TODO: Document shared helper functions]

---

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

Phase 2: Fix Broken Links

Updates links to point to correct locations.

Fix Actions:

Path Resolution Logic:

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

    # Monolithic BDD: docs/04_BDD/BDD-01.md
    # Sectioned BDD: docs/04_BDD/BDD-01_slug/BDD-01.3_section.md
    # Feature files: tests/bdd/features/*.feature

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

EARS Link Fix:

Feature File Link Fix:

Phase 3: Fix Element IDs

Converts invalid element IDs to correct format.

Conversion Rules:

Type Code Mapping (BDD-specific valid codes: 35, 36, 37):

Regex Patterns:

# Find element IDs with invalid type codes for BDD
invalid_bdd_type_01 = r'BDD\.(\d{2})\.01\.(\d{2})'
replacement_01 = r'BDD.\1.35.\2'

invalid_bdd_type_25 = r'BDD\.(\d{2})\.25\.(\d{2})'
replacement_25 = r'BDD.\1.36.\2'

invalid_bdd_type_22 = r'BDD\.(\d{2})\.22\.(\d{2})'
replacement_22 = r'BDD.\1.37.\2'

# Find legacy patterns
legacy_feat = r'###\s+FEAT-(\d+):'
legacy_scen = r'###\s+SCEN-(\d+):'
legacy_step = r'###\s+STEP-(\d+):'

Phase 4: Fix Content Issues

Addresses placeholders, incomplete content, and BDD-specific syntax issues.

Fix Actions:

Auto-Replacements:

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'),
    '[Feature Name]': extract_feature_name_from_metadata(),
}

Gherkin Structure Validation:

Phase 5: Update References

Ensures traceability and cross-references are correct.

Fix Actions:

Traceability Format:

<!-- Traceability to EARS -->
@trace: EARS-01.25.01 -> BDD-01.35.01

<!-- Reference to upstream -->
@ref: [EARS-01 Section 3](../03_EARS/EARS-01.md#3-functional-requirements)

Tag Traceability in Feature Files:

@trace:EARS-01.25.01 @feature:BDD-01.35.01
Feature: User Authentication

Phase 6: Handle Upstream Drift (Auto-Merge)

Addresses issues where upstream EARS documents have changed since BDD creation. Uses a tiered auto-merge system based on change percentage to automatically incorporate new requirements.

6.0.1 Hash Validation Fixes

FIX-H001: Invalid Hash Placeholder

Trigger: Hash contains placeholder instead of SHA-256

Fix:

sha256sum <upstream_file_path> | cut -d' ' -f1

Update cache with: sha256:<64_hex_output>

FIX-H002: Missing Hash Prefix

Trigger: 64 hex chars but missing sha256: prefix

Fix: Prepend sha256: to value

FIX-H003: Upstream File Not Found

Trigger: Cannot compute hash (file missing)

Fix: Set drift_detected: true, add to manual review

Upstream: EARS (Layer 3) Downstream: ADR (Layer 5)

6.1 Change Percentage Calculation

Calculate drift percentage by comparing EARS content hashes:

def calculate_change_percentage(
    original_ears_hash: str,
    current_ears_hash: str,
    original_content: str,
    current_content: str
) -> float:
    """Calculate percentage of content changed in upstream EARS."""

    if original_ears_hash == current_ears_hash:
        return 0.0

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

    added_lines = current_lines - original_lines
    removed_lines = original_lines - current_lines

    total_original = len(original_lines)
    if total_original == 0:
        return 100.0 if current_lines else 0.0

    change_percentage = (len(added_lines) + len(removed_lines)) / total_original * 100
    return round(change_percentage, 2)

6.2 Tiered Auto-Merge Thresholds

6.3 Tier 1: Minor Drift (< 5%)

Trigger: Small additions or clarifications in upstream EARS.

Actions:

1. Parse new EARS requirements not covered by existing BDD scenarios
2. Generate new scenarios with auto-generated tags
3. Append to appropriate feature file
4. Increment patch version

Auto-Generated Scenario Tag Format:

@BDD-{NN}-SC-{SS}

Where:

• NN = BDD document number (01-99)
• SC = Scenario identifier
• SS = Sequential scenario number (01-99)

Example:

# Auto-merged from EARS-01 drift (2026-02-10)
@BDD-01-SC-13 @auto-merged @trace:EARS-01.25.12
Scenario: User receives notification on password expiry
  Given a user with password expiring in 7 days
  When the daily notification job runs
  Then the user receives an expiry warning email

Tier 1 Changelog Entry:

### v1.0.1 (2026-02-10) - Patch

**Drift Merge**: Tier 1 (3.2% change detected in EARS-01)

| Added Scenarios | Tag | Source |
|-----------------|-----|--------|
| User receives notification on password expiry | @BDD-01-SC-13 | EARS-01.25.12 |

6.4 Tier 2: Moderate Drift (5-15%)

Trigger: Significant additions or modifications in upstream EARS.

Actions:

1. Parse all new/modified EARS requirements
2. Generate new scenarios for additions
3. Mark existing scenarios for review if source requirement modified
4. Generate detailed changelog
5. Increment minor version

Detailed Changelog Format:

### v1.1.0 (2026-02-10) - Minor

**Drift Merge**: Tier 2 (8.7% change detected in EARS-01, EARS-02)

#### New Scenarios Added

| Scenario | Tag | Feature File | Source |
|----------|-----|--------------|--------|
| User receives notification on password expiry | @BDD-01-SC-13 | auth.feature | EARS-01.25.12 |
| Admin can force password reset | @BDD-01-SC-14 | auth.feature | EARS-01.25.13 |
| Session timeout configurable per role | @BDD-01-SC-15 | session.feature | EARS-02.25.05 |

#### Scenarios Marked for Review

| Scenario | Tag | Reason | Source Change |
|----------|-----|--------|---------------|
| User authenticates with valid credentials | @BDD-01-SC-01 | Source requirement modified | EARS-01.25.01 v2 |

#### Upstream Changes Summary

| Document | Sections Changed | Lines Added | Lines Removed |
|----------|------------------|-------------|---------------|
| EARS-01.md | 3.1, 3.5, 4.2 | 24 | 6 |
| EARS-02.md | 5.1 | 8 | 0 |

Review Marker for Modified Source:

# REVIEW: Source requirement EARS-01.25.01 modified on 2026-02-10
# Original: "User must authenticate with username and password"
# Updated: "User must authenticate with username and password or SSO"
@BDD-01-SC-01 @needs-review @trace:EARS-01.25.01
Scenario: User authenticates with valid credentials
  # ... existing steps ...

6.5 Tier 3: Major Drift (> 15%)

Trigger: Substantial changes indicating major requirement evolution.

Actions:

1. Archive current BDD version
2. Create archive manifest
3. Trigger regeneration workflow
4. Increment major version

No Deletion Policy:

Existing scenarios are NEVER deleted. Instead:

# DEPRECATED: Superseded by EARS-01 v3 changes (2026-02-10)
# Reason: Authentication flow redesigned to support SSO-only mode
# Archive: BDD-01_v1.1.0_archive/auth.feature
@BDD-01-SC-01 @deprecated @archive:v1.1.0
Scenario: User authenticates with username and password
  # ... existing steps preserved ...

Archive Manifest Creation:

Location: docs/04_BDD/BDD-{NN}_v{X.Y.Z}_archive/MANIFEST.md

---
title: "BDD-01 Archive Manifest v1.1.0"
tags:
  - bdd
  - archive
  - manifest
custom_fields:
  archive_date: "2026-02-10T16:00:00"
  archive_reason: "Tier 3 drift (22.4% change in EARS-01)"
  original_version: "1.1.0"
  new_version: "2.0.0"
  triggering_upstream: "EARS-01 v3"
---

# BDD-01 Archive Manifest v1.1.0

## Archive Summary

| Field | Value |
|-------|-------|
| Archived Version | 1.1.0 |
| Archive Date | 2026-02-10T16:00:00 |
| Reason | Tier 3 upstream drift (22.4% change) |
| Triggering Upstream | EARS-01 v3 |
| New Version | 2.0.0 (regeneration triggered) |

## Archived Files

| File | Scenarios | Status |
|------|-----------|--------|
| BDD-01.md | - | Archived |
| auth.feature | 5 | 3 deprecated, 2 preserved |
| session.feature | 3 | 1 deprecated, 2 preserved |
| api.feature | 8 | 4 deprecated, 4 preserved |

## Deprecated Scenarios

| Tag | Scenario | Deprecation Reason |
|-----|----------|-------------------|
| @BDD-01-SC-01 | User authenticates with username and password | SSO-only authentication in v3 |
| @BDD-01-SC-02 | User fails authentication with wrong password | Replaced by SSO error handling |
| @BDD-01-SC-05 | Password complexity validation | Removed - SSO handles auth |

## Preserved Scenarios

| Tag | Scenario | Preserved In |
|-----|----------|--------------|
| @BDD-01-SC-03 | User session expires after timeout | BDD-01 v2.0.0 |
| @BDD-01-SC-04 | User can logout from all devices | BDD-01 v2.0.0 |

## Regeneration Trigger

Command to regenerate BDD from updated EARS:

/doc-bdd-autopilot EARS-01 --version 2.0.0 --preserve-from BDD-01_v1.1.0_archive

6.6 Enhanced Drift Cache

After processing drift issues, update .drift_cache.json:

{
  "bdd_id": "BDD-01",
  "bdd_version": "1.1.0",
  "bdd_updated": "2026-02-10T16:00:00",
  "drift_reviewed": "2026-02-10T16:00:00",
  "upstream_type": "EARS",
  "downstream_type": "ADR",
  "upstream_hashes": {
    "EARS-01.md": {
      "hash": "a1b2c3d4e5f6...",
      "version": "2.0",
      "last_checked": "2026-02-10T16:00:00"
    },
    "EARS-02.md": {
      "hash": "e5f6g7h8i9j0...",
      "version": "1.5",
      "last_checked": "2026-02-10T16:00:00"
    }
  },
  "merge_history": [
    {
      "date": "2026-02-08T10:00:00",
      "tier": 1,
      "change_percentage": 3.2,
      "version_before": "1.0.0",
      "version_after": "1.0.1",
      "scenarios_added": ["@BDD-01-SC-10"],
      "scenarios_deprecated": [],
      "upstream_trigger": "EARS-01 v1.8"
    },
    {
      "date": "2026-02-10T16:00:00",
      "tier": 2,
      "change_percentage": 8.7,
      "version_before": "1.0.1",
      "version_after": "1.1.0",
      "scenarios_added": ["@BDD-01-SC-13", "@BDD-01-SC-14", "@BDD-01-SC-15"],
      "scenarios_deprecated": [],
      "upstream_trigger": "EARS-01 v2.0, EARS-02 v1.5"
    }
  ],
  "acknowledged_drift": [
    {
      "document": "EARS-03.md",
      "acknowledged_date": "2026-02-09",
      "reason": "Documentation-only change - no BDD impact"
    }
  ],
  "next_scenario_number": 16
}

6.7 Auto-Merge Workflow

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

    C -->|Yes| D[Tier 1: Auto-Merge]
    D --> D1[Generate new scenarios]
    D1 --> D2[Add @BDD-NN-SC-SS tags]
    D2 --> D3[Increment patch version]
    D3 --> E[Update drift cache]

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

    F -->|Yes| G[Tier 2: Auto-Merge + Changelog]
    G --> G1[Generate new scenarios]
    G1 --> G2[Mark modified for review]
    G2 --> G3[Generate detailed changelog]
    G3 --> G4[Increment minor version]
    G4 --> E

    F -->|No| H[Tier 3: Archive + Regenerate]
    H --> H1[Archive current version]
    H1 --> H2[Create archive manifest]
    H2 --> H3[Mark deprecated scenarios]
    H3 --> H4[Trigger regeneration]
    H4 --> H5[Increment major version]
    H5 --> E

    E --> I[Update .drift_cache.json]
    I --> J[Generate Fix Report]

6.8 Drift Issue Codes

6.9 Drift Acknowledgment Workflow

When drift is flagged but no BDD update is needed:

1. Run /doc-bdd-fixer BDD-01 --acknowledge-drift
2. Fixer prompts: "Review drift for EARS-01.md?"
3. User confirms no BDD changes needed
4. Fixer adds to acknowledged_drift array
5. Future reviews skip this drift until upstream changes again

Command Usage

Basic Usage

# Fix BDD based on latest review
/doc-bdd-fixer BDD-01

# Fix with explicit review report (legacy)
/doc-bdd-fixer BDD-01 --review-report BDD-01.R_review_report_v001.md

# Fix with explicit audit report (preferred)
/doc-bdd-fixer BDD-01 --review-report BDD-01.A_audit_report_v001.md

# Fix and re-run review
/doc-bdd-fixer BDD-01 --revalidate

# Fix with iteration limit
/doc-bdd-fixer BDD-01 --revalidate --max-iterations 3

Options

Report Selection Precedence:

1. Select latest report by timestamp.
2. If timestamps are equal, prefer BDD-NN.A_audit_report_vNNN.md over BDD-NN.R_review_report_vNNN.md.

Fix Types

Output Artifacts

Fix Report

Nested Folder Rule: ALL BDD suites use nested folders (BDD-NN_{slug}/). Fix reports are stored alongside the BDD feature files in the nested folder.

File Naming: BDD-NN.F_fix_report_vNNN.md

Location: Inside the BDD nested folder: docs/04_BDD/BDD-NN_{slug}/

Structure:

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

# BDD-NN Fix Report v001

## Summary

| Metric | Value |
|--------|-------|
| Source Review | BDD-NN.A_audit_report_v001.md (or legacy `BDD-NN.R_review_report_v001.md`) |
| Issues in Review | 12 |
| Issues Fixed | 10 |
| Issues Remaining | 2 (manual review required) |
| Files Created | 3 |
| Files Modified | 5 |
| Feature Files Fixed | 2 |

## Files Created

| File | Type | Location |
|------|------|----------|
| BDD-00_GLOSSARY.md | Behavior Glossary | docs/04_BDD/ |
| BDD-01_STEP_DEFS.md | Step Definitions Placeholder | docs/04_BDD/ |
| auth_placeholder.feature | Feature Placeholder | tests/bdd/features/ |

## Fixes Applied

| # | Issue Code | Issue | Fix Applied | File |
|---|------------|-------|-------------|------|
| 1 | REV-L001 | Broken glossary link | Created BDD-00_GLOSSARY.md | BDD-01.3_scenarios.md |
| 2 | REV-L004 | Broken EARS reference | Updated path to ../03_EARS/EARS-01.md | BDD-01.1_core.md |
| 3 | REV-N004 | Element type 01 invalid | Converted to type 35 | BDD-01.1_core.md |
| 4 | REV-L005 | Broken feature file link | Created auth_placeholder.feature | BDD-01.2_features.md |

## Feature File Fixes

| File | Fixes Applied |
|------|---------------|
| auth.feature | Added @trace tag, fixed step reference |
| api.feature | Updated Examples table format |

## Issues Requiring Manual Review

| # | Issue Code | Issue | Location | Reason |
|---|------------|-------|----------|--------|
| 1 | REV-B001 | Missing Gherkin keyword | BDD-01.2:L45 | Scenario syntax needed |
| 2 | REV-B003 | Missing Given/When/Then | auth.feature:L32 | Step structure required |

## Validation After Fix

| Metric | Before | After | Delta |
|--------|--------|-------|-------|
| Review Score | 92 | 97 | +5 |
| Errors | 2 | 0 | -2 |
| Warnings | 4 | 1 | -3 |

## Next Steps

1. Complete BDD-01_STEP_DEFS.md placeholder
2. Complete auth_placeholder.feature with proper scenarios
3. Address missing Gherkin keywords in flagged scenarios
4. Run `/doc-bdd-reviewer BDD-01` to verify fixes

Integration with Autopilot

This skill is invoked by doc-bdd-autopilot in the Review -> Fix cycle:

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

Autopilot Integration Points:

Error Handling

Recovery Actions

Backup Strategy

Before applying any fixes:

1. Create backup in tmp/backup/BDD-NN_YYYYMMDD_HHMMSS/
2. Copy all BDD files and linked feature files to backup location
3. Apply fixes to original files
4. If error during fix, restore from backup

Related Skills

Version History

Implementation Plan Consistency (IPLAN-004)

• Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.
• Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt.
• Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.
• Do not introduce legacy fallback paths such as docs-v2.0/00_REF.