Implementation Plan: Technical Debt Resolution

Phase 0 Artifact — Clears specification debt before feature work per ENGINEERING.SOP.md.

✅ EXECUTED 2025-12-31 — All 47 issues resolved. Verification: node scripts/spec-cross-check.js → 0 errors.

Purpose

Systematically resolve 47 identified issues across plans and specs: superseded references, missing specifications, broken traceability, and naming inconsistencies. This plan ensures the specification layer is clean before proceeding with implementation plans.

Debt Summary

Supersession Registry (Authoritative)

MUST use this table when updating references.

Proposed Cycles (Worktree-First)

Task Breakdown

Wave 1: Critical Reference Cleanup (Parallel)

Goal: Eliminate all references to superseded specifications.

D1A: Global Superseded Reference Cleanup

• Priority: 🔴 Critical
• Estimated Time: 2 hours
• Files to Modify:

• Bulk Commands:

  1
  2
  3
  4
  5
  6
  7
  8
  9
  # Run from repo root
  find docs/plans -name "*.md" -exec sed -i 's/SDS-017/SDS-050/g' {} \;
  find docs/plans -name "*.md" -exec sed -i 's/SDS-037/SDS-051/g' {} \;
  find docs/plans -name "*.md" -exec sed -i 's/SDS-043/SDS-047/g' {} \;
  find docs/plans -name "*.md" -exec sed -i 's/SDS-042/SDS-047/g' {} \;
  find docs/plans -name "*.md" -exec sed -i 's/SDS-004/SDS-051/g' {} \;
  find docs/plans -name "*.md" -exec sed -i 's/SDS-014/SDS-045/g' {} \;
  find docs/plans -name "*.md" -exec sed -i 's/SDS-035/REF-012 §10/g' {} \;
  find docs/plans -name "*.md" -exec sed -i 's/ADR-020/ADR-030/g' {} \;
  

• Verification:

  1
  2
  3
  # Ensure no superseded refs remain
  grep -r "SDS-017\|SDS-037\|SDS-043\|SDS-042\|SDS-004\|SDS-014\|SDS-035\|SDS-034\|SDS-041\|ADR-020" docs/plans/
  # Should return empty or only historical notes
  

D1B: Update Traceability Matrix

• Priority: 🔴 Critical
• Estimated Time: 1 hour
• File: docs/specs/shared/reference/009-traceability-matrix.md

Actions:

1. Remove rows for superseded SDS (004, 014, 017, 034, 035, 037, 041, 042, 043)
2. Add rows for new SDS (045, 047, 050, 051, 052)
3. Update PRD → SDS mappings:
   • PRD-001 → SDS-002, SDS-051
   • PRD-003 → SDS-050, SDS-018
   • PRD-010 → SDS-047 (not SDS-042, SDS-043)
   • PRD-020 → SDS-045
   • PRD-021 → SDS-046, SDS-047
4. Mark superseded specs in “Notes” column

D1C: Update System Context Map

• Priority: 🔴 Critical
• Estimated Time: 1 hour
• File: docs/specs/00_system_context_map.md

Actions:

1. Update SDS-017 row: Add “→ SUPERSEDED by SDS-050”
2. Update SDS-037 row: Add “→ SUPERSEDED by SDS-051”
3. Add rows for SDS-050, SDS-051, SDS-052
4. Verify all 52+ active SDS are listed
5. Mark Context Analyzer entries as superseded

Wave 2: Missing Specifications (Parallel, depends on Wave 1)

Goal: Create missing PRD/SDS for plans without spec coverage.

D2A: Create Simulation & Replay Specs

• Priority: 🔴 Critical
• Estimated Time: 3 hours
• Creates:
  • docs/specs/shared/adr/036-simulation-replay-architecture.md
  • docs/specs/shared/prd/024-simulation-replay-platform.md
  • docs/specs/shared/sds/053-simulation-replay-service.md

PRD-024 Skeleton:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# PRD-024: Simulation & Replay Platform

Satisfies: ADR-036

## Requirements

### REQ-SIM-001 (functional)
When a user requests a simulation, the system shall create a deterministic
snapshot and execute the scenario without affecting production state.

### REQ-SIM-002 (functional)
When a simulation completes, the system shall compare results against
historical patterns from the Pattern Oracle.

### REQ-SIM-003 (nonfunctional)
Simulation replay shall be deterministic: identical inputs yield identical outputs.

D2B: Create Workbench UI Specs

• Priority: 🔴 Critical
• Estimated Time: 2 hours
• Creates:
  • docs/specs/shared/prd/025-workbench-ui.md
  • docs/specs/shared/sds/054-workbench-ui-service.md

PRD-025 Skeleton:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# PRD-025: Workbench UI

Satisfies: ADR-007

## Requirements

### REQ-WB-001 (functional)
The Workbench shall provide a Knowledge Graph explorer for navigating
semantic relationships.

### REQ-WB-002 (functional)
The Workbench shall display manifest inspection for generated artifacts.

### REQ-WB-003 (functional)
The Workbench shall integrate the Governance Console for policy management.

D2C: Create Case Management PRD

• Priority: 🟠 High
• Estimated Time: 1.5 hours
• Creates:
  • docs/specs/cognitive-extension/prd/010-case-management.md

PRD-010-CE Skeleton:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# PRD-010: Case Management Platform

Satisfies: ADR-021

## Requirements

### REQ-CM-001 (functional)
The system shall support CMMN-based case lifecycle management.

### REQ-CM-002 (functional)
Cases shall integrate with the Artifact Pipeline for document generation.

### REQ-CM-003 (functional)
PM-Agent shall orchestrate task assignments within case contexts.

Wave 3: Structural Cleanup (Parallel, depends on Wave 2)

Goal: Fix naming conventions and consolidate duplicates.

D3A: Align Plan File Numbering

• Priority: 🟠 High
• Estimated Time: 1 hour

Option A (Recommended): Rename files to match plan_ids

1
2
3
4
# Example renames
mv docs/plans/17_SimulationAndReplay.plan.md docs/plans/11_SimulationAndReplay.plan.md
mv docs/plans/21_WorkbenchUI.plan.md docs/plans/14_WorkbenchUI.plan.md
# ... etc

Option B: Update NFO.md with explicit mapping table

1
2
3
4
| File Number | plan_id | Title |
|-------------|---------|-------|
| 17 | P011 | Simulation & Replay |
| 21 | P014 | Workbench UI |

Decision: Choose Option A for consistency.

New Mapping: | Current File | plan_id | New File | |————–|———|———-| | 17_SimulationAndReplay | P011 | 11b_SimulationAndReplay | | 18_SemanticDebtAndIncidents | P022 | 22_SemanticDebtAndIncidents | | 19_DocumentationSystem | P023 | 23_DocumentationSystem | | 20_PlatformUIIntegration | P024 | 24_PlatformUIIntegration | | 21_WorkbenchUI | P014 | 14b_WorkbenchUI | | 22_PetTrainingApp | P025 | 25_PetTrainingApp | | 23_CaseManagement | P027 | 27_CaseManagement | | 24_UserFeedbackLoop | P028 | 28_UserFeedbackLoop | | 25_MeceQuadrantIntegration | P026 | 26_MeceQuadrantIntegration | | 26_VibesPro™Integration | P029 | 29_VibesPro™Integration |

D3B: Consolidate .internal/ Duplicates

• Priority: 🟠 High
• Estimated Time: 1 hour
• Directory: docs/specs/.internal/

Actions:

1. Remove duplicate 050-semantic-identity-provenance.md from .internal/ (keep shared/sds/050-*)
2. Move 012-invariant-regime.md to docs/specs/shared/reference/012-invariant-regime.md
3. Remove duplicate 035-governance-invariants.md from .internal/
4. Update all references to use canonical paths:

   1
   find docs -name "*.md" -exec sed -i 's|.internal/012-invariant-regime|shared/reference/012-invariant-regime|g' {} \;
   

Wave 4: Tooling & Cleanup (Depends on Wave 3)

Goal: Update automated tooling and clean up minor issues.

D4A: Update spec-cross-check.js

• Priority: 🟡 Medium
• Estimated Time: 1 hour
• File: scripts/spec-cross-check.js

Actions:

1. Add supersession chain handling:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   const SUPERSEDED_SPECS = {
     'SDS-004': 'SDS-051',
     'SDS-014': 'SDS-045',
     'SDS-017': 'SDS-050',
     'SDS-034': 'SDS-050',
     'SDS-035': 'REF-012',
     'SDS-037': 'SDS-051',
     'SDS-041': 'SDS-052',
     'SDS-042': 'SDS-047',
     'SDS-043': 'SDS-047',
     'ADR-020': 'ADR-030',
   };
   

2. Add check for superseded references
3. Update exclude lists to remove superseded specs
4. Add warning when superseded spec is referenced

D4B: Minor Cleanup

• Priority: 🟢 Low
• Estimated Time: 1 hour

Actions:

1. Clean up answered Open Questions in:
   • 5_KnowledgeGraphRuntime.plan.md
   • 6_RuntimeKernel.plan.md
   • 9_SemanticIdentity.plan.md
   • 11_ObservabilityAndEvidence.plan.md
2. Add consistent version fields to all plans:

   1
   version: 1.0.0
   

3. Update Architecture Container Diagram:
   • File: docs/specs/shared/architecture/001-sea-v5-container-diagram.md
   • Replace “Context Analyzer” → “Universal Context Service”
   • Replace “Project Context Analyzer” → “Universal Context Service”
4. Fill cognitive-extension SDS numbering gap:
   • SDS-010 is unused; reserve for future or document as skipped

Validation & Verification

After Wave 1

1
2
3
4
5
6
# No superseded references in plans
grep -rE "SDS-0(04|14|17|34|35|37|41|42|43)|ADR-020" docs/plans/ | grep -v "SUPERSEDED"
# Expected: empty

# Context map is current
just spec-check

After Wave 2

1
2
3
4
# All plans have spec coverage
for plan in docs/plans/*.plan.md; do
  grep -q "PRD-" "$plan" && grep -q "SDS-" "$plan" || echo "Missing specs: $plan"
done

After Wave 3

1
2
3
4
5
6
# No duplicates in .internal/
ls docs/specs/.internal/
# Expected: Only files not in shared/

# Plan files match plan_ids
grep -h "^plan_id:" docs/plans/*.plan.md | sort -u

After Wave 4

1
2
3
4
5
6
# spec-cross-check passes
node scripts/spec-cross-check.js --mode staging --dir docs/specs
# Expected: Exit 0

# No open questions with inline answers
grep -B2 "Resolved\|Answer:" docs/plans/*.plan.md

Acceptance Criteria

• Zero references to superseded SDS (004, 014, 017, 034, 035, 037, 041, 042, 043)
• Zero references to superseded ADR (020)
• All 26 plans have at least one PRD and one SDS reference
• Traceability matrix is current with all active specs
• System context map lists all 52+ active SDS
• .internal/ contains no duplicates of shared/ files
• spec-cross-check.js passes in staging mode
• Plan file numbers align with plan_ids (or mapping documented)

Risks & Mitigation

Timeline

Related Documents