roadmap-alignment.config.yaml

on } from './alignment-schema';

export function validateAlignment( goals: RoadmapGoal[], tasks: EngineeringTask[], sprintCapacity: number ): AlignmentValidation[] { return goals.map(goal => { const relatedTasks = tasks.filter(t => t.goalId === goal.id); const activeTasks = relatedTasks.filter(t => t.status === 'in-progress'); const completedTasks = relatedTasks.filter(t => t.status === 'done');

const totalCapacity = relatedTasks.reduce((sum, t) => sum + t.capacityUnits, 0);
const utilizedCapacity = activeTasks.reduce((sum, t) => sum + t.capacityUnits, 0);

const capacityUtilization = sprintCapacity > 0 ? utilizedCapacity / sprintCapacity : 0;
const outcomeMapped = relatedTasks.length > 0 && goal.outcomeMetric !== '';

// Drift calculation: unlinked tasks + capacity overflow + missing outcome mapping
const unlinkedRatio = relatedTasks.length === 0 ? 1 : 0;
const capacityOverload = capacityUtilization > 0.85 ? 0.3 : 0;
const missingOutcome = !outcomeMapped ? 0.4 : 0;
const driftScore = Math.min(1, unlinkedRatio + capacityOverload + missingOutcome);

return {
  goalId: goal.id,
  driftScore,
  capacityUtilization,
  outcomeMapped,
  blockers: driftScore > 0.3 ? ['Alignment drift detected'] : []
};

}); }

### Step 4: Integrate with Delivery Systems
Validation must gate delivery, not just report on it. Attach the engine to PR checks, sprint planning APIs, and webhook listeners. When drift exceeds thresholds, block merges or trigger planning reviews.

```typescript
// integration-gateway.ts
import { validateAlignment } from './validation-rules';

export async function handlePrCheck(
  repo: string,
  prTasks: string[],
  engine: import('./sync-pipeline').AlignmentSyncEngine
): Promise<{ approved: boolean; reason?: string }> {
  const { goals, tasks } = engine.getSnapshot();
  const filteredTasks = tasks.filter(t => prTasks.includes(t.id));
  const validations = validateAlignment(goals, filteredTasks, 100); // normalized capacity

  const criticalDrift = validations.find(v => v.driftScore > 0.6);
  if (criticalDrift) {
    return {
      approved: false,
      reason: `PR blocked: Goal ${criticalDrift.goalId} exceeds alignment threshold (${criticalDrift.driftScore.toFixed(2)})`
    };
  }

  return { approved: true };
}

Architecture Decisions & Rationale

• Config-as-Code over UI Dashboards: Roadmaps become version-controlled artifacts. Diff tracking, audit trails, and rollback capabilities replace manual spreadsheet edits.
• Event-Driven Sync: Webhooks from Linear/Jira/GitHub trigger idempotent ingestion. Polling is avoided to prevent stale state and API rate limits.
• Deterministic Validation: Rules use pure functions with explicit thresholds. No probabilistic models or LLM guessing. Predictability is required for CI gates.
• Capacity Normalization: Story points or engineering hours are normalized to a 0–1 scale per sprint. This enables cross-team comparison and prevents local optimization from masking global drift.
• Single Source of Truth: The alignment engine owns the canonical state. Downstream tools consume snapshots via read-only APIs or event streams.

Pitfall Guide

1. Treating Alignment as Static Roadmaps change. Validation rules that assume fixed scope produce false positives. Implement versioned goal contracts and delta-based drift calculation instead of absolute matching.

2. Ignoring Engineering Capacity Constraints Mapping goals to tasks without bounding capacity creates phantom alignment. Always normalize against sprint/iteration capacity. Overcommitment masks drift until delivery fails.

3. Over-Indexing on Output Metrics Shipping features does not equal alignment. If outcome metrics (conversion, latency, retention) are not explicitly linked to roadmap items, validation becomes a checkbox exercise. Enforce outcome mapping as a hard requirement.

4. Manual Sync Dependencies Spreadsheets, Slack updates, and weekly syncs introduce latency. Drift compounds during the gap. Automate ingestion via webhooks and run validation on every delivery event.

5. Segregating Technical Debt from Roadmaps Tech debt items that support roadmap outcomes must be explicitly linked. Isolated debt tracking creates hidden capacity drains. Model tech debt as goal-adjacent tasks with explicit outcome bridges.

6. No Feedback Loop from Delivery to Planning Alignment is bidirectional. If delivery systems report blocked tasks or scope changes, the roadmap engine must propagate updates upstream. Implement reverse-webhooks or status reconciliation jobs.

Production Best Practices:

• Run validation in CI/CD pipelines, not just dashboards.
• Use semantic versioning for roadmap contracts.
• Maintain idempotent ingestion endpoints.
• Set drift thresholds per team maturity; enforce stricter gates as velocity increases.
• Log validation decisions for audit and retrospective analysis.

Production Bundle

Action Checklist

• Define typed roadmap and task schemas with explicit outcome linkage
• Implement idempotent webhook ingestion for planning and delivery systems
• Build pure-function validation rules with capacity normalization and drift scoring
• Attach validation gates to PR checks and sprint planning APIs
• Configure reverse sync to propagate delivery blockers upstream
• Version-control roadmap contracts and enable diff tracking
• Set team-specific drift thresholds and enforce CI blocking above limits
• Log validation events for retrospective capacity and alignment analysis

Decision Matrix

Configuration Template

# roadmap-alignment.config.yaml
schema_version: "1.0"
sync:
  planning_source:
    type: linear
    webhook_secret_env: LINEAR_WEBHOOK_SECRET
    endpoint: /api/v1/ingest/goals
  delivery_source:
    type: github
    webhook_secret_env: GITHUB_WEBHOOK_SECRET
    endpoint: /api/v1/ingest/tasks
validation:
  drift_threshold: 0.4
  capacity_overload_limit: 0.85
  require_outcome_mapping: true
  sprint_capacity_normalized: 100
gates:
  pr_check:
    enabled: true
    block_on_critical_drift: true
  sprint_planning:
    enabled: true
    reject_overcommitted_epics: true
logging:
  level: info
  audit_trail: true
  retention_days: 90

Quick Start Guide

1. Initialize the engine: Clone the alignment repository and run npm install. The TypeScript compiler will validate schema contracts.
2. Configure webhooks: Set environment variables for LINEAR_WEBHOOK_SECRET and GITHUB_WEBHOOK_SECRET. Register /api/v1/ingest/* endpoints in your planning and delivery tools.
3. Run validation locally: Execute npm run validate -- --sprint-capacity 100. The engine ingests sample data, calculates drift scores, and outputs a JSON report.
4. Attach to CI: Add the PR check script to your workflow. When a pull request references tasks, the engine validates alignment and blocks merges if drift exceeds the configured threshold.
5. Monitor drift: Query /api/v1/alignment/snapshot for real-time alignment state. Integrate with your observability stack to alert on threshold breaches.

Roadmap alignment stops being a meeting cadence when it becomes a deterministic system. Type contracts, automated sync, and validation gates transform planning from an art into an engineering discipline.