Skip to content

STRATEGY-four-parallel-workstreams.md

Latest commit

 

History

History
388 lines (290 loc) · 12.4 KB

STRATEGY-four-parallel-workstreams.md

File metadata and controls

388 lines (290 loc) · 12.4 KB

Implementation Strategy: Parallel Four-Workstream Orchestration

ADR Metadata & Feature Improvements — April 2026

Status: Design phase (planning) Target: Execute four independent workstreams in parallel, merge to main serially with clean sequencing

Overview

This document details a strategy to execute four independent workstreams that converge cleanly back to main:

  1. WS-0400 (5 min) — ADR Status Updates: Mark ADR 0058 & 0061 as "Superseded"
  2. WS-0401 (30 min) — ADR Scanner: Auto-detect implementation status from code
  3. WS-0402 (20 min) — ADR 0243 Assessment: Evaluate codex/ws-0243-live-apply branch
  4. WS-0403 (45 min) — ADR 0025 Deep Dive: Trace Compose stack gaps, plan systemd integration

Key design principle: Each workstream owns exclusive file surfaces → zero merge conflicts → clean serial integration to main.

1. Git Branching & Worktree Strategy

Each workstream gets a dedicated worktree and branch:

main (current: 0.178.37)
 ├─ claude/ws-0400-adr-status
 │  └─ .claude/worktrees/ws-0400-adr-status/
 ├─ claude/ws-0401-adr-scanner
 │  └─ .claude/worktrees/ws-0401-adr-scanner/
 ├─ claude/ws-0402-assess-0243
 │  └─ .claude/worktrees/ws-0402-assess-0243/
 └─ claude/ws-0403-adr0025-dive
    └─ .claude/worktrees/ws-0403-adr0025-dive/

Creation Steps (for each workstream)

# From main worktree
git worktree add .claude/worktrees/ws-0400-adr-status -b claude/ws-0400-adr-status
cd .claude/worktrees/ws-0400-adr-status

# [Do work here]

git push -u origin claude/ws-0400-adr-status

Why worktrees: Isolated filesystems prevent cross-contamination of node_modules, build artifacts, VERSION files, and .local/ secrets.

2. File Ownership Matrix (Zero Conflicts)

Workstream Owns Never Touches
WS-0400 docs/adr/005[18]*.md + auto-gen index shards VERSION, changelog.md, RELEASE.md
WS-0401 scripts/adr_implementation_scanner.py, docs/adr/implementation-status/ VERSION, changelog.md, RELEASE.md
WS-0402 docs/workstreams/ws-0402-assess-0243-branch.md VERSION, changelog.md, RELEASE.md
WS-0403 docs/adr/0025-implementation-roadmap.md VERSION, changelog.md, RELEASE.md

No two workstreams modify the same file → Merge conflicts are impossible.

3. Task Decomposition

WS-0400: ADR Status Updates (5 min)

What: Mark ADR 0058 (NATS JetStream) and ADR 0061 (GlitchTip) as "Superseded"

Steps:

  1. Edit docs/adr/0058-*.md: Change Status: Proposed → Status: Superseded
  2. Edit docs/adr/0061-*.md: Change status + add reason
  3. Run python scripts/generate_adr_index.py --write (auto-regenerates shards)
  4. Commit: [adr] Mark ADR 0058 and 0061 as Superseded due to <reason>
  5. Push: git push origin claude/ws-0400-adr-status

Files: 2 ADR markdown + auto-gen shards

WS-0401: Build ADR Scanner (30 min)

What: Create scripts/adr_implementation_scanner.py to auto-detect ADR implementation status

Steps:

  1. Design heuristics: ADR number → code pattern mapping
    • Example: ADR 0025 (Compose) → look for docker-compose.yml, /srv/ paths
    • Example: ADR 0058 (NATS) → grep for nats image references
  2. Implement scanner with output format: docs/adr/implementation-status/<adr>.yaml
  3. Generate docs/adr/implementation-status/INDEX.md (summary report)
  4. Commit: [adr-scanner] Implement auto-detection and generate reports
  5. Push: git push origin claude/ws-0401-adr-scanner

Files: 1 script + N report files (auto-generated or committed templates)

WS-0402: Assess ADR 0243 Branch (20 min)

What: Evaluate origin/codex/ws-0243-live-apply for merge readiness

Key facts: 1086 commits ahead of main; covers Storybook + Playwright + axe-core UI testing

Steps:

  1. Fetch & inspect: git log main..origin/codex/ws-0243-live-apply --oneline | head -30
  2. Look for:
    • Gate bypass receipts (indicate failures)
    • Incomplete TODOs or FIXMEs
    • Rebase conflicts with current main
  3. Document findings in docs/workstreams/ws-0402-assess-0243-branch.md:
    • Scope summary
    • Any blockers identified
    • Merge-readiness recommendation
  4. Commit: [ws-0402] Assess ADR 0243 branch; document findings
  5. Push: git push origin claude/ws-0402-assess-0243

Files: 1 assessment document

WS-0403: ADR 0025 Deep Dive (45 min)

What: Trace ADR 0025 (Compose stacks) implementation gaps; plan systemd integration

Steps:

  1. Discovery (15 min):

    • Where is Compose used? grep -r "docker.compose" roles/
    • Current /srv/ layout? ls -R /srv/ 2>/dev/null
    • Systemd units for Compose? find roles/ -name "*.service" | xargs grep -l compose

  2. Gap analysis (15 min):

    • Create matrix of stacks (mail, keycloak, etc.) vs. systemd coverage
    • What's missing: service units, runbook templates, boot-time start policy?

  3. Roadmap (15 min):

    • Create docs/adr/0025-implementation-roadmap.md with phases:
      • Phase 1: Systemd service template for docker-compose
      • Phase 2: Stack registry (vars/docker_stacks.yaml)
      • Phase 3: Runbook generation templates
      • Phase 4: Ansible integration task

  4. Commit: [adr-0025] Trace implementation gaps; draft systemd roadmap

  5. Push: git push origin claude/ws-0403-adr0025-dive

Files: 1 roadmap document

4. Merge Sequence (Serial, One Per VERSION Bump)

After all four workstreams complete their development:

WS-0400 → bump VERSION (0.178.37 → 0.178.38) → merge to main
WS-0401 → bump VERSION (0.178.38 → 0.178.39) → merge to main
WS-0402 → bump VERSION (0.178.39 → 0.178.40) → merge to main
WS-0403 → bump VERSION (0.178.40 → 0.178.41) → merge to main

Each merge cycle:

  1. Rebase workstream onto current main
  2. Merge with --no-ff (explicit merge commit)
  3. Bump VERSION file
  4. Add changelog entry
  5. Regenerate platform artifacts (CLAUDE.md Section 4d)
  6. Commit integration
  7. Push to main

Example (WS-0400):

git checkout main && git pull origin main
git merge claude/ws-0400-adr-status --no-ff -m "[merge] WS-0400 — ADR status updates"

echo "0.178.38" > VERSION
echo "- ADR 0058 and 0061 marked as Superseded" >> changelog.md

# Regenerate (CLAUDE.md Section 4d)
python scripts/platform_manifest.py --write
python scripts/generate_discovery_artifacts.py --write

git add VERSION changelog.md RELEASE.md docs/release-notes/ build/platform-manifest.json build/onboarding/
git commit -m "[release] Bump to 0.178.38 — ADR status updates"
git push origin main

5. Pre-Merge Verification Checklist

All Workstreams

  • Git status clean (no untracked files except receipts/, sbom/)
  • No modifications to VERSION, changelog.md, RELEASE.md on branch
  • Pre-push gate passes or skipped with documented reason code

WS-0400

  • grep "Status: Superseded" docs/adr/005[18]*.md returns matches
  • Index regeneration committed: python scripts/generate_adr_index.py --write
  • ADR shards updated in git log

WS-0401

  • Scanner script is syntactically valid: python -m py_compile scripts/adr_implementation_scanner.py
  • Sample report is valid YAML: python -c "import yaml; yaml.safe_load(open('docs/adr/implementation-status/0025.yaml'))"
  • Index.md is well-formed Markdown

WS-0402

  • Assessment document exists: test -f docs/workstreams/ws-0402-assess-0243-branch.md
  • No code changes (docs only): git diff origin/main -- . --not -- docs/ | wc -l ≈ 0

WS-0403

  • Roadmap document is valid Markdown: pandoc docs/adr/0025-implementation-roadmap.md -t plain > /dev/null
  • Phases are clearly numbered and actionable

6. Pre-Push Gate Handling

The repo has a pre-push hook that validates schema, ADR index freshness, and platform manifest.

If gate fails:

git push origin claude/ws-040X-name 2>&1 | tee push.log

if grep -q "gate failed" push.log; then
  # Determine reason (e.g., "adr_index_stale", "schema_invalid")
  REASON="adr_index_stale"

  # Skip gate with documented reason
  SKIP_REMOTE_GATE=1 GATE_BYPASS_REASON_CODE="$REASON" \
    git push origin claude/ws-040X-name

  # Receipt is auto-created in receipts/gate-bypasses/
fi

Expected gate checks:

  • ADR index freshness (WS-0400 must pass; others should auto-pass)
  • Schema validation (all should pass; no schema changes)
  • Platform manifest consistency (all should pass)
  • No .local/ in index (all should pass)

7. Workstream Registration (Before Real Work)

Create docs/workstreams/active/<id>.yaml for each workstream.

Example (WS-0400):

id: ws-0400-adr-status-updates
adr: '0164'  # Workstream governance ADR
title: Mark ADR 0058 and 0061 as Superseded
status: planned
owner: claude
branch: claude/ws-0400-adr-status
worktree_path: .claude/worktrees/ws-0400-adr-status
doc: docs/workstreams/ws-0400-adr-status-updates.md
depends_on: []
conflicts_with: []
owned_surfaces:
  - id: adr_0058_0061_docs
    paths:
      - docs/adr/0058-*.md
      - docs/adr/0061-*.md
    mode: exclusive
  - id: adr_index_shards
    paths:
      - docs/adr/.index.yaml
      - docs/adr/index/by-status/*.yaml
    mode: auto_generated

Then regenerate registry:

python3 scripts/workstream_registry.py --write

8. Success Criteria

WS-0400 (ADR Status)

  • ADR 0058, 0061 marked "Superseded" with reason
  • Index shards regenerated and committed
  • Merges cleanly to main
  • VERSION 0.178.38 set on main after merge

WS-0401 (ADR Scanner)

  • Scanner script exists and runs without errors
  • docs/adr/implementation-status/ populated with reports
  • Sample ADR (0025) correctly detected as "Partial"
  • Merges cleanly to main
  • VERSION 0.178.39 set on main after merge

WS-0402 (0243 Assessment)

  • Assessment doc includes scope, blockers, merge recommendation
  • No code changes (documentation only)
  • Merges cleanly to main
  • VERSION 0.178.40 set on main after merge

WS-0403 (ADR 0025 Deep Dive)

  • Roadmap doc includes 4+ phases with actionable steps
  • Gap analysis identifies which stacks need systemd coverage
  • Merges cleanly to main
  • VERSION 0.178.41 set on main after merge

Final Integration

  • All four workstreams merged in sequence
  • VERSION advanced 0.178.37 → 0.178.41 (4 bumps, one per workstream)
  • changelog.md has entries for all four merges
  • Release notes generated for 0.178.38, 0.178.39, 0.178.40, 0.178.41
  • Clean git log with explicit merge commits

9. Rollback Procedure

If a merge fails:

# On main
git merge --abort
git reset --hard origin/main

# Investigate in the failing worktree
cd .claude/worktrees/<name>
git log --oneline -5
git diff origin/main

If abandoning a workstream:

# Remove worktree
git worktree remove .claude/worktrees/<name>

# Delete branches
git branch -D claude/ws-040X-*
git push origin --delete claude/ws-040X-*  # Optional, cleanup

10. Critical Files for This Strategy

Files to Create (New)

  • docs/workstreams/active/ws-0400-adr-status-updates.yaml
  • docs/workstreams/active/ws-0401-adr-implementation-scanner.yaml
  • docs/workstreams/active/ws-0402-assess-0243-branch.yaml
  • docs/workstreams/active/ws-0403-adr0025-deep-dive.yaml
  • scripts/adr_implementation_scanner.py
  • docs/adr/implementation-status/INDEX.md
  • docs/workstreams/ws-0402-assess-0243-branch.md
  • docs/adr/0025-implementation-roadmap.md

Files to Modify

  • docs/adr/0058-nats-jetstream-for-internal-event-bus-and-agent-coordination.md
  • docs/adr/0061-glitchtip-for-application-exceptions-and-task-failures.md

Files Auto-Generated (After WS-0400)

  • docs/adr/.index.yaml
  • docs/adr/index/by-status/proposed.yaml
  • docs/adr/index/by-status/deprecated.yaml
  • workstreams.yaml

Files Bumped on Main (Integration Only)

  • VERSION
  • changelog.md
  • RELEASE.md
  • build/platform-manifest.json
  • build/onboarding/*.yaml

Summary

Strategy: Four independent, parallel workstreams with exclusive file ownership → serial merge-to-main with VERSION bumps.

Execution time: ~90 min (60 min parallel work + 20 min serial integration)

Key success factors:

  1. Strict file ownership (no overlap between workstreams)
  2. Workstream registration before real work
  3. Pre-push gate compliance (bypass only when justified)
  4. Serial integration (one merge per VERSION bump)
  5. Clean worktree isolation

Result: All four improvements land on main cleanly, with clear audit trail and no conflicts.