initiative discovery

Status-Based Directory Migration Tooling

Robert Matsuoka Updated 2026-03-11 apex apex-framework
apex tooling filesystem migration q1-2026

Initiative: Status-Based Directory Migration Tooling

The Bet

Following approval of the Status-Based Subdirectory Organization proposal, this initiative implements the tooling required to make the directory model work safely and sustainably.

The core principle: status changes are directory moves, managed by tooling that fixes all cross-references atomically.

Background

The Status-Based Subdirectory proposal (approved) defines a directory structure where initiative status is reflected in filesystem location:

Status Location
discovery, validated, delivery initiatives/{name}/ (active — stays flat)
deployed initiatives/deployed/{name}/
learning initiatives/learning/{name}/
success initiatives/success/{name}/
killed initiatives/killed/{name}/

Products follow a similar pattern: active products stay flat, maintenance/ and sunset/ subdirectories for inactive ones.

The risk without tooling: moving directories breaks relative paths in experiments, PRDs, meeting notes, and README tables. Manual fixes are error-prone and get missed.

Deliverables

1. One-Time Bulk Migration Script

File: scripts/apex/migrate_status_dirs.py

Scans all current initiatives, identifies those in non-active statuses (deployed, learning, success, killed), and migrates them to the correct subdirectory — updating all cross-references in one pass.

python scripts/apex/migrate_status_dirs.py --dry-run   # preview
python scripts/apex/migrate_status_dirs.py --execute   # apply

Responsibilities: - Uses git mv (preserves history) - Detects all reference types: relative paths, absolute paths, markdown links, README tables - Updates references in every affected file - Validates all links post-migration - Generates migration report

2. Per-Transition Status Change Tool

File: scripts/apex/migrate_initiative_status.py

Used for day-to-day status transitions. Engineers run this instead of manually editing frontmatter + moving directories.

# Preview
python scripts/apex/migrate_initiative_status.py \
  --initiative products/analytics/forecasting/initiatives/demand-forecasting \
  --new-status deployed \
  --dry-run

# Apply
python scripts/apex/migrate_initiative_status.py \
  --initiative products/analytics/forecasting/initiatives/demand-forecasting \
  --new-status deployed \
  --execute

The tool: 1. Validates the status transition is valid per APEX schema 2. Calculates new path 3. Moves with git mv 4. Updates all cross-references (relative, absolute, markdown, README tables) 5. Validates links 6. Stages all changes, prints summary

3. Pre-Commit Hook Update

File: scripts/hooks/validate-status-dirs.py (called from .pre-commit-config.yaml)

Detects when frontmatter status is inconsistent with directory location and blocks the commit, directing the engineer to the migration tool.

Pre-commit check failed:
  initiatives/demand-forecasting/Initiative.md
  Status in frontmatter: deployed
  Expected directory:    initiatives/deployed/demand-forecasting/

  Run: scripts/apex/migrate_initiative_status.py \
         --initiative ... --new-status deployed --execute

File: scripts/apex/validate_links.py

Standalone link checker integrated into CI. Validates all relative and absolute paths referenced in APEX markdown files.

python scripts/apex/validate_links.py          # validate all
python scripts/apex/validate_links.py --fix    # auto-fix common patterns

5. README Table Auto-Generation

Products' README.md initiative tables are auto-generated from directory structure by apex-update-initiative skill and CI. No manual table maintenance needed post-migration.

Success Metrics

Metric Target
Broken links after bulk migration 0
Time to safely transition one initiative < 2 min
CI catches broken links introduced by PR Yes
Pre-commit blocks manual directory moves Yes

Implementation Plan

Phase 1: Core Scripts (Days 1–3)

  • [ ] migrate_status_dirs.py — bulk migration, dry-run mode
  • [ ] migrate_initiative_status.py — per-transition tool
  • [ ] Reference detection (relative paths, absolute paths, markdown links)
  • [ ] git mv + reference rewrite + link validation in one atomic operation

Phase 2: Hooks & CI (Days 4–5)

  • [ ] Pre-commit hook: detect status/directory inconsistency
  • [ ] CI: run validate_links.py on every PR
  • [ ] Auto-fix for README tables in validate.py

Phase 3: Migration (Days 6–7)

  • [ ] Run bulk migration with --dry-run, review report
  • [ ] Execute migration on all current non-active initiatives
  • [ ] Verify CI passes, zero broken links
  • [ ] Update CONTRIBUTING.md with new status-change workflow

Risks

Risk Mitigation
Bulk migration misses reference type Comprehensive test against current repo before execute
Pre-commit hook false positives Test against all active branches before rollout
Nested relative paths (../../) harder to rewrite Normalize to repo-root-relative before rewriting