P3.2: Automatic Drift Remediation — Implementation Plan

Created: 2026-01-22
Status: ✅ Approved
Dependency: P3.1 Provenance Tracking System (complete)

Goal

Implement an intelligent drift remediation system that detects, analyzes, and proposes fixes for spec→code misalignments. The system enables:

  1. Proactive spec suggestions when drift is detected
  2. Automated PR generation for simple remediations
  3. CI integration for drift-aware merge workflows

[!IMPORTANT] This builds on the P3.1 Provenance System. All drift detection leverages the existing lineage graph to trace generated code back to source specs.

User Review Required

Design Decisions

  1. Conservative Auto-Fix Scope: Auto-generated PRs are limited to regeneration from specs (no direct code patching). Complex semantic drift requires human review.

  2. Dual-Mode Architecture: The system operates in both CI (blocking/advisory) and Workbench UI (interactive) modes.

  3. GitHub Integration First: PR automation targets GitHub API. GitLab/Bitbucket adapters are out of scope but interface is extensible.

Architecture Overview

flowchart TD
    subgraph Detection["Drift Detection Layer"]
        DD[DriftDetector] --> |hash compare| PC[ProvenanceComparator]
        DD --> |semantic diff| SD[SemanticDiffer]
    end

    subgraph Analysis["Analysis & Suggestion Layer"]
        AN[DriftAnalyzer] --> |classify| CL{DriftType}
        CL --> |benign| BEN[FormatDrift]
        CL --> |spec_stale| STALE[SpecSuggestion]
        CL --> |code_stale| CODE[RegenSuggestion]
        CL --> |semantic| SEM[ManualReviewRequired]
    end

    subgraph Remediation["Remediation Layer"]
        REM[RemediationEngine] --> |generate| REGEN[RegenerationRunner]
        REM --> |create| PR[PRCreator]
        REM --> |notify| UI[WorkbenchNotifier]
    end

    Detection --> Analysis --> Remediation

Proposed Changes

Drift Detection Service (Python)

New service module under services/workbench-bff/ for drift detection and remediation orchestration.

[NEW] drift_detector.py

Core drift detection engine leveraging the provenance graph.

Key Classes:

Features:

[NEW] drift_analyzer.py

Intelligent drift classification and suggestion generation.

Key Classes:

Features:

[NEW] remediation_engine.py

Orchestrates remediation actions including PR creation.

Key Classes:

Features:

Auto-Fix Safety Policy:

[NEW] pr_creator.py

GitHub PR automation following the port/adapter pattern.

Port Interface:

1
2
3
4
5
6
7
8

class PRCreatorPort(Protocol):
    def create_remediation_pr(
        self,
        title: str,
        body: str,
        branch: str,
        changes: list[FileChange],
    ) -> PRResult: ...

Adapter Implementation:

API Routes

[NEW] drift_routes.py

REST endpoints for drift detection and remediation.

Cross-cutting concerns:

Endpoints: | Method | Path | Description | |——–|——|————-| | GET | /drift/scan | Scan all contexts for drift | | GET | /drift/context/{context} | Get drift status for specific context | | GET | /drift/report/{node_id} | Detailed drift report for a node | | POST | /drift/analyze | Analyze drift and get suggestions | | POST | /drift/remediate | Execute remediation action | | GET | /drift/history | Get remediation audit history |

API constraints:

Pydantic Models

[MODIFY] models.py

Add drift-related API models:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

class DriftType(str, Enum):
    NONE = "none"
    BENIGN = "benign"
    SPEC_STALE = "spec_stale"
    CODE_STALE = "code_stale"
    SEMANTIC = "semantic"

class DriftReportModel(BaseModel):
    nodeId: str
    nodeType: str
    context: str
    driftType: DriftType
    confidence: float  # 0.0-1.0
    specHash: str | None
    codeHash: str | None
    lastSyncedAt: str | None
    suggestions: list[DriftSuggestionModel]

class DriftSuggestionModel(BaseModel):
    suggestionId: str
    action: Literal["regenerate", "update_spec", "manual_review"]
    description: str
    confidence: float
    autoFixable: bool
    estimatedImpact: str  # "low" | "medium" | "high"
    command: str | None  # e.g., "just pipeline semantic-core"

class RemediationRequestModel(BaseModel):
    nodeId: str
    suggestionId: str
    createPR: bool = True
    draftPR: bool = True

class RemediationResultModel(BaseModel):
    success: bool
    action: str
    prUrl: str | None
    errorMessage: str | None
    auditId: str

Workbench UI Components (TypeScript/React)

[NEW] drift-api.ts

Frontend API client for drift endpoints.

1
2
3
4
5
6

export function scanForDrift(): Promise<DriftScanResult>;
export function getContextDrift(context: string): Promise<DriftReport[]>;
export function getDriftReport(nodeId: string): Promise<DriftReport>;
export function analyzeDrift(nodeId: string): Promise<DriftAnalysis>;
export function executeRemediation(request: RemediationRequest): Promise<RemediationResult>;
export function getDriftHistory(): Promise<DriftAuditEntry[]>;

[NEW] DriftDashboard.tsx

Main UI for drift visualization and remediation.

Features:

[NEW] DriftReportCard.tsx

Component displaying individual drift reports.

Shows:

[NEW] drift.ts

TypeScript type definitions mirroring backend models.

[MODIFY] App.tsx

Add route for Drift Dashboard:

1

<Route path="/drift" element={<DriftDashboard />} />

[MODIFY] [Navigation components]

Add navigation link to Drift Dashboard in sidebar/header.

CI Integration

[NEW] drift_check.sh

CI guard script for drift-aware merges.

Modes:

Safety gates:

Integration:

1
2
3

# .github/workflows/ci.yml addition
- name: Drift Check
  run: ./scripts/ci/drift_check.sh --fail

[NEW] auto_remediate.yml

GitHub Actions workflow for automated remediation PRs.

Token configuration:

1
2
3
4
5
6
7
8
9

permissions:
  contents: write
  pull-requests: write

steps:
  - name: Drift Check (auto-remediate)
    run: ./scripts/ci/drift_check.sh --auto-remediate --confirm
    env:
      GITHUB_TOKEN: $

Triggers:

Actions:

CLI Tooling

[NEW] drift_heal.py

Command-line interface for drift operations.

Commands:

1
2
3
4
5
6
7
8
9
10
11

# Scan all contexts
python tools/drift_heal.py scan

# Check specific context
python tools/drift_heal.py check semantic-core

# Apply remediation
    python tools/drift_heal.py remediate <node-id> --type=regenerate [--dry-run] [--force]

# Generate report
python tools/drift_heal.py report --format=json > drift-report.json

Remediate behavior:

[MODIFY] justfile

Add drift-related recipes:

# Scan all contexts for drift
drift-scan:
    python tools/drift_heal.py scan

# Check drift for specific context
drift-check context:
    python tools/drift_heal.py check 

# Auto-remediation preview (regenerate/update-spec only)
drift-heal:
    python tools/drift_heal.py remediate --auto --dry-run

# Generate drift report
drift-report:
    python tools/drift_heal.py report --format=markdown

Value-Add Enhancements

1. Smart Suggestion Ranking

Suggestions are ranked by:

2. Batch Remediation

One-click “Fix All Safe Issues” that:

3. Drift Trend Analytics

Dashboard shows:

4. Integration with Provenance Explorer

From ProvenanceExplorer:

5. Pre-commit Hook Support

1
2
3
4
5
6
7

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: drift-check
      name: Drift Check
      entry: python tools/drift_heal.py check --fail-on-semantic
      language: system

File Summary

Category New Files Modified Files
Backend Adapters 4 0
API Routes 1 0
Models 0 1
Frontend Pages 1 1
Frontend Components 1 0
Frontend Types/API 2 0
CI Scripts 1 0
GitHub Actions 1 0
CLI Tools 1 0
Build Config 0 1
Total 12 3

Verification Plan

Automated Tests

Python Unit Tests

File: services/workbench-bff/tests/test_drift_detector.py

1
2

# Run drift detector tests
cd services/workbench-bff && python -m pytest tests/test_drift_detector.py -v

Test Cases:

Python Integration Tests

File: services/workbench-bff/tests/test_drift_api.py

1
2

# Run drift API integration tests
cd services/workbench-bff && python -m pytest tests/test_drift_api.py -v

Test Cases:

TypeScript Component Tests

File: apps/workbench/src/pages/__tests__/DriftDashboard.test.tsx

1
2

# Run Workbench tests
pnpm nx test workbench --testFile=DriftDashboard

Test Cases:

CI Script Validation

1
2
3
4
5
6
7

# Test drift_check.sh in warn mode (should always pass)
./scripts/ci/drift_check.sh --warn

# Test with intentional drift (create temp file in gen/)
touch libs/semantic-core/domain/src/gen/temp_test_file.ts
./scripts/ci/drift_check.sh --warn  # Should report drift
rm libs/semantic-core/domain/src/gen/temp_test_file.ts

Manual Verification

Workbench UI Flow

  1. Start dev environment: just dev-up && just workbench-dev
  2. Navigate to http://localhost:3000/drift
  3. Verify:

CLI Tooling

1
2
3
4

# Verify CLI commands work
python tools/drift_heal.py scan
python tools/drift_heal.py check semantic-core
python tools/drift_heal.py report --format=markdown

Just Recipes

1
2
3
4
5
6

# Verify just recipes are registered
just --list | grep drift

# Run recipes
just drift-scan
just drift-report

Dependencies

Dependency Version Purpose
pygithub ^2.1.0 GitHub API for PR creation
difflib stdlib Semantic diff generation
humanize ^4.9.0 Human-readable time formatting

Out of Scope

Risk Mitigation

Risk Mitigation
False positives in drift detection Conservative thresholds + human review gate
Accidental code overwrites Draft PRs only, no direct commits
GitHub API rate limits Caching + exponential backoff
Large diffs causing timeouts Pagination + summary-first approach

Timeline Estimate

Phase Duration Deliverables
Backend Core 3 days Detector, Analyzer, Engine
API + Models 1 day Routes, Pydantic models
CI Integration 1 day Guard script, GH Action
Workbench UI 2 days Dashboard, Components
CLI + Just 0.5 days Tool, Recipes
Testing 2 days Unit, Integration, Manual
Polish 0.5 days Docs, Edge cases
Total 10 days Production-ready P3.2

References