Problem
Two related tracking-drift issues undermine the loop's ability to know what's done and what's next:
1. ROADMAP deliverable paths go stale on file renames
ROADMAP tasks reference specific file paths as deliverables (e.g., src/storage/file.ts). When files are renamed (as happened with the filename-match-export lint rule requiring file.ts → FileStorageBackend.ts), the ROADMAP paths become stale. There's no drift detection — agents or next-work could misreport task status.
Impact: High — stale paths cause next-work to report incomplete tasks that are actually done, or miss tasks entirely.
2. OpenSpec tasks and ROADMAP tasks aren't synced
The loop uses both OpenSpec (openspec/) and ROADMAP files for task tracking, but there's no bridge between them. An agent could mark a ROADMAP task done but forget to archive the OpenSpec change, or vice versa. Two parallel tracking systems with no sync mechanism.
Impact: High — divergent tracking means neither system is authoritative.
Suggested Fix
- Path drift: Add a
validate-roadmap command to forge-helper.sh that checks all deliverable paths exist. Run it as part of the loop's verification step.
- OpenSpec sync: Either make OpenSpec the single source of truth (and generate ROADMAP status from it), or add a sync check that warns when they disagree.
Files
/scripts/forge-helper.sh — Add validate-roadmap command/packages/telemetry/ROADMAP.md — Example of deliverable paths/ROADMAP.md — Root coordination ROADMAP/openspec/ — OpenSpec artifacts
Origin
Forge-loop retrospective — findings #3 and #4 (high impact).
Problem
Two related tracking-drift issues undermine the loop's ability to know what's done and what's next:
1. ROADMAP deliverable paths go stale on file renames
ROADMAP tasks reference specific file paths as deliverables (e.g.,
src/storage/file.ts). When files are renamed (as happened with thefilename-match-exportlint rule requiringfile.ts→FileStorageBackend.ts), the ROADMAP paths become stale. There's no drift detection — agents ornext-workcould misreport task status.Impact: High — stale paths cause
next-workto report incomplete tasks that are actually done, or miss tasks entirely.2. OpenSpec tasks and ROADMAP tasks aren't synced
The loop uses both OpenSpec (
openspec/) and ROADMAP files for task tracking, but there's no bridge between them. An agent could mark a ROADMAP task done but forget to archive the OpenSpec change, or vice versa. Two parallel tracking systems with no sync mechanism.Impact: High — divergent tracking means neither system is authoritative.
Suggested Fix
validate-roadmapcommand toforge-helper.shthat checks all deliverable paths exist. Run it as part of the loop's verification step.Files
/scripts/forge-helper.sh— Addvalidate-roadmapcommand/packages/telemetry/ROADMAP.md— Example of deliverable paths/ROADMAP.md— Root coordination ROADMAP/openspec/— OpenSpec artifactsOrigin
Forge-loop retrospective — findings #3 and #4 (high impact).