Alignment Review: Repository
Alignment Review: Repository
Review Date: 2026-04-04 Scope: Full repository Status: complete Review Epic: helix-71894dd3 Primary Governing Artifact: helix.prd
Scope and Governing Artifacts
Scope
- Supervisory control and CLI (FEAT-001, FEAT-002)
- First-class principles (FEAT-003)
- Plugin packaging (FEAT-004)
- Execution-backed skill output (FEAT-005)
- Tracker queue hygiene
- Skill packaging and validation
Governing Artifacts
docs/helix/00-discover/product-vision.mddocs/helix/01-frame/prd.mddocs/helix/01-frame/features/FEAT-001-helix-supervisory-control.mddocs/helix/01-frame/features/FEAT-002-helix-cli.mddocs/helix/01-frame/features/FEAT-003-principles.mddocs/helix/01-frame/features/FEAT-004-plugin-packaging.mddocs/helix/01-frame/features/FEAT-005-execution-backed-output.mddocs/helix/02-design/adr/ADR-001-supervisory-control-model.mddocs/helix/02-design/adr/ADR-002-tracker-write-safety-model.mddocs/helix/02-design/solution-designs/SD-001-helix-supervisory-control.mddocs/helix/02-design/solution-designs/SD-002-first-class-principles.mddocs/helix/02-design/technical-designs/TD-002-helix-cli.mddocs/helix/02-design/contracts/API-001-helix-tracker-mutation.mddocs/helix/03-test/test-plans/TP-002-helix-cli.mddocs/helix/04-build/implementation-plan.md
Intent Summary
- Vision: HELIX is a supervised autopilot that advances the weakest ready layer of the development stack until human input is needed. Year 1 target: reliable autopilot with core workflow, tracker, CLI, and mirrored skills.
- Requirements: PRD defines
helix-runas supervisory autopilot with least-power action selection, tracker-first execution, concurrent interactive operation, plugin packaging, first-class principles, and execution-backed output. 5 features specified. - Features / Stories: FEAT-001 (P0, specified), FEAT-002 (P0, backfilled), FEAT-003 (P1, draft), FEAT-004 (P1, draft), FEAT-005 (P1, draft).
- Architecture / ADRs: ADR-001 establishes supervisory control model. ADR-002 defines tracker write safety (context now stale after DDx migration).
- Technical Design: TD-002 defines CLI orchestration contract, state machine, recovery, concurrency, review handling, and commit flow.
- Test Plans: TP-002 covers 133 deterministic tests for CLI wrapper.
- Implementation Plans: Implementation plan defines 3 build slices with
ordering constraints. References stale
workflows/TRACKER.md.
Planning Stack Findings
| Finding | Type | Evidence | Impact | Review Issue |
|---|---|---|---|---|
ADR-002 references .helix/issues.jsonl and self-contained tracker | stale | ADR-002:10-12 | Low | helix-c5864cc0 |
TD-002 references scripts/tracker.sh (deleted) with line numbers | stale | TD-002:324-410 | Medium | helix-c5864cc0 |
SD-001 references .helix/issues.jsonl | stale | SD-001:52 | Low | helix-c5864cc0 |
Implementation plan cites workflows/TRACKER.md (deleted) | stale | implementation-plan.md:29 | Medium | helix-c5864cc0 |
plugin.json missing skills and hooks fields | missing-link | FEAT-004 design vs .claude-plugin/plugin.json | Medium | helix-b21504cb |
bin/helix plugin CLI wrapper does not exist | missing-link | FEAT-004 design | Medium | helix-b21504cb |
workflows/references/ directory does not exist | missing-link | SD-002 specifies principles-resolution.md there | Low | helix-18af7317 |
| No principles injection in any action prompt | missing-link | SD-002 injection plan | Expected (FEAT-003 not started) | helix-18af7317 |
workflows/principles.md contains workflow rules, not design principles | stale | FEAT-003 FR-1/FR-2 | Expected (FEAT-003 not started) | helix-18af7317 |
validate-skills.sh fails on helix-implement symlink alias | contradiction | Symlink helix-implement -> helix-build | Low | helix-14b95aac |
Implementation Map
- Topology: Shell CLI (
scripts/helix, ~2424 lines), skill pack (skills/, 17+ entries including 2 alias symlinks), workflow actions (workflows/actions/, 10 action prompts), plugin manifest (.claude-plugin/plugin.json, partial) - Entry Points:
scripts/helix(CLI),skills/*/SKILL.md(agent skills),.claude-plugin/plugin.json(partial plugin) - Test Surfaces:
tests/helix-cli.sh(133 deterministic tests),tests/validate-skills.sh(skill validation, currently failing on alias) - Unplanned Areas: ~15 test/junk tracker issues polluting the ready queue
Acceptance Criteria Status
| Story / Feature | Criterion | Test Reference | Status | Evidence |
|---|---|---|---|---|
| US-001 [FEAT-001] | helix-run advances next bounded layer | tests/helix-cli.sh | SATISFIED | NEXT_ACTION dispatch tested |
| US-001 [FEAT-001] | Functionality change routes to align/evolve/design | workflows/actions/check.md | SATISFIED | check defines routing |
| US-002 [FEAT-001] | Direct layer invocation works | tests/helix-cli.sh dry-run tests | SATISFIED | Each command invocable |
| FEAT-002 | helix help shows commands | tests/helix-cli.sh | SATISFIED | Help test passes |
| FEAT-002 | helix status structured snapshot | tests/helix-cli.sh | SATISFIED | Status test passes |
| FEAT-002 | helix run NEXT_ACTION contract | tests/helix-cli.sh | SATISFIED | All 8 codes tested |
| FEAT-002 | helix run --summary | tests/helix-cli.sh | SATISFIED | Summary mode tested |
| FEAT-002 | Exponential backoff correct | tests/helix-cli.sh | SATISFIED | 5/10/20/40 verified |
| FEAT-002 | Epic focus maintained | tests/helix-cli.sh | SATISFIED | Focus and blocking tested |
| FEAT-002 | Orphan recovery with PID/claim-age | tests/helix-cli.sh | SATISFIED | Recovery tested |
| FEAT-002 | Context refresh every 5 cycles | tests/helix-cli.sh | SATISFIED | Refresh tested |
| FEAT-002 | helix commit build gate | tests/helix-cli.sh | SATISFIED | Commit flow tested |
| FEAT-002 | DDx bead delegation | tests/helix-cli.sh | SATISFIED | 133 tests pass through adapter |
| US-001 [FEAT-003] | helix frame bootstraps principles | none | UNIMPLEMENTED | Not started |
| US-002 [FEAT-003] | Judgment skills include principles | none | UNIMPLEMENTED | No injection |
| US-003 [FEAT-003] | Tension detection on add | none | UNIMPLEMENTED | Not started |
| US-004 [FEAT-003] | HELIX defaults when no project file | none | UNIMPLEMENTED | Defaults still workflow rules |
| US-001 [FEAT-004] | --plugin-dir makes skills available | none | UNTESTED | Manifest incomplete |
| US-002 [FEAT-004] | New skill available without reinstall | none | UNTESTED | Manifest lacks skills path |
| US-004 [FEAT-004] | Validator catches broken plugin | tests/validate-skills.sh | TESTED_NOT_PASSING | Fails on alias symlink |
| US-001 [FEAT-005] | Query execution history | none | UNIMPLEMENTED | DDx FEAT-010 dependency |
| US-002 [FEAT-005] | Durable evolution report | none | UNIMPLEMENTED | DDx FEAT-010 dependency |
| US-003 [FEAT-005] | helix status shows recent actions | none | UNIMPLEMENTED | DDx FEAT-010 dependency |
Gap Register
| Area | Classification | Planning Evidence | Implementation Evidence | Resolution Direction | Issue |
|---|---|---|---|---|---|
| Supervisory control (FEAT-001) | ALIGNED | FEAT-001, ADR-001, SD-001, TD-002 | scripts/helix run loop, 133 tests | n/a | helix-c5864cc0 |
| CLI surface (FEAT-002) | ALIGNED | FEAT-002, TD-002, TP-002, API-001 | scripts/helix ~2424 lines, DDx bead delegation | n/a | helix-c5864cc0 |
| TD-002 stale evidence refs | STALE_PLAN | TD-002:324-410 | scripts/tracker.sh deleted | plan-to-code | helix-c5864cc0 |
| Implementation plan stale ref | STALE_PLAN | implementation-plan.md:29 | workflows/TRACKER.md deleted | plan-to-code | helix-c5864cc0 |
| ADR-002 stale context | STALE_PLAN | ADR-002 references self-contained tracker | DDx bead delegation | plan-to-code | helix-c5864cc0 |
| First-class principles (FEAT-003) | INCOMPLETE | FEAT-003, SD-002 fully specified | No implementation; scaffolding outdated | code-to-plan | helix-18af7317 |
| Plugin packaging (FEAT-004) | INCOMPLETE | FEAT-004 fully specified | Manifest partial; bin/helix missing; validator not updated | code-to-plan | helix-b21504cb |
| Execution-backed output (FEAT-005) | INCOMPLETE | FEAT-005 fully specified | No implementation; blocked on DDx FEAT-010 | code-to-plan | helix-30e00d6b |
| Tracker queue hygiene | DIVERGENT | PRD expects clean tracker state | ~15 junk issues in ready queue | quality-improvement | helix-25836a2d |
| Skill validator alias handling | INCOMPLETE | FEAT-002 alias contract | validate-skills.sh fails on symlinks | code-to-plan | helix-14b95aac |
Quality Findings
| Area | Dimension | Concern | Severity | Resolution | Issue |
|---|---|---|---|---|---|
| Tracker | Maintainability | ~15 junk/test issues inflate ready queue | Medium | quality-improvement | helix-5f53e5ca |
| CLI | Robustness | validate-skills.sh fails on alias symlinks | Medium | quality-improvement | helix-14b95aac |
| Docs | Maintainability | TD-002 evidence section cites deleted file | Low | quality-improvement | helix-66762d1c |
| Docs | Maintainability | Implementation plan cites deleted TRACKER.md | Low | quality-improvement | helix-66762d1c |
Traceability Matrix
| Vision | Requirement | Feature/Story | Arch/ADR | Design | Tests | Impl Plan | Code Status | Classification |
|---|---|---|---|---|---|---|---|---|
| Supervised autopilot | PRD P0-1..P0-7 | FEAT-001 | ADR-001 | SD-001, TD-002 | TP-002 | Slice 2,3 | Implemented | ALIGNED |
| CLI command surface | PRD P0-1..P0-9 | FEAT-002 | ADR-001 | TD-002 | TP-002 | Slice 1,2 | Implemented | ALIGNED |
| Tracker-first execution | PRD P0-7 | FEAT-002 | ADR-002 | TD-002, API-001 | TP-002 | Slice 1 | DDx delegated | ALIGNED |
| First-class principles | PRD P1-10 | FEAT-003 | n/a | SD-002 | none | not in plan | Not started | INCOMPLETE |
| Plugin packaging | PRD P0-8..P0-10, P1-5 | FEAT-004 | n/a | FEAT-004 | none | not in plan | Partial | INCOMPLETE |
| Execution-backed output | PRD Obs-5,6 | FEAT-005 | n/a | FEAT-005 | none | not in plan | Not started | INCOMPLETE |
| Cross-model review | PRD P1-8 | FEAT-001/002 | ADR-001 | TD-002 | TP-002 | n/a | Implemented | ALIGNED |
| Interactive entry | PRD P0-6 | FEAT-001/US-002 | ADR-001 | SD-001 | TP-002 | n/a | Implemented | ALIGNED |
Execution Issues Generated
| Issue ID | Type | Labels | Goal | Dependencies | Verification |
|---|---|---|---|---|---|
| helix-ddde7400 | task | phase:build,FEAT-003 | Rewrite principles defaults | none (ready) | Content review |
| helix-43b1a2d0 | task | phase:build,FEAT-003 | Relocate workflow rules | none (ready) | grep audit |
| helix-e186ec28 | task | phase:build,FEAT-003 | Update principles scaffolding | none (ready) | Validation |
| helix-aac2bc6a | task | phase:build,FEAT-003 | Principles resolution + injection | blocked | Prompt audit |
| helix-9222038c | task | phase:build,FEAT-003 | Bootstrap in helix frame | blocked | E2E test |
| helix-d70303de | task | phase:build,FEAT-003 | Tension detection + size ceiling | blocked | Pair test |
| helix-8efeb583 | task | phase:build | Complete plugin manifest | none (ready) | JSON validation |
| helix-347a49df | task | phase:build | Create bin/helix wrapper | none (ready) | Executable test |
| helix-604b0e3d | task | phase:build | Validator plugin layout | none (ready) | validate-skills passes |
| helix-b821376f | task | phase:build | Execution definitions | none (ready) | DDx-compatible |
| helix-ee13947a | task | phase:build | Wire CLI to ddx exec | blocked (DDx) | Run records persist |
| hx-8447a41c | task | phase:build | Refresh implementation plan | none (ready) | Plan cites current slices |
| helix-5f53e5ca | chore | phase:iterate,area:tracker | Clean up junk issues | none (ready) | Ready count drops |
| helix-66762d1c | task | phase:build,area:docs | Update TD-002 evidence for DDx | none (ready) | No deleted file refs |
Issue Coverage
| Gap / Criterion | Covering Issue | Status |
|---|---|---|
| FEAT-003 defaults rewrite | helix-ddde7400 | covered |
| FEAT-003 rule relocation | helix-43b1a2d0 | covered |
| FEAT-003 scaffolding | helix-e186ec28 | covered |
| FEAT-003 resolution + injection | helix-aac2bc6a | covered |
| FEAT-003 frame bootstrap | helix-9222038c | covered |
| FEAT-003 tension detection | helix-d70303de | covered |
| FEAT-004 manifest | helix-8efeb583 | covered |
| FEAT-004 bin/helix | helix-347a49df | covered |
| FEAT-004 validator | helix-604b0e3d | covered |
| FEAT-005 definitions | helix-b821376f | covered |
| FEAT-005 CLI wiring | helix-ee13947a | covered (blocked DDx) |
| TD-002 stale evidence | helix-66762d1c | covered |
| Implementation plan stale ref | hx-8447a41c | covered |
| Tracker junk issues | helix-5f53e5ca | covered |
| Skill validator alias | helix-604b0e3d | covered |
| FEAT-005 status history | helix-6ae1e84c | covered |
| FEAT-003 research | helix-5688e5bd | covered (blocked) |
Execution Order
Critical Path
- FEAT-003 Slice 1 (parallel, ready now):
- helix-ddde7400: Rewrite principles defaults
- helix-43b1a2d0: Relocate workflow rules
- helix-e186ec28: Update scaffolding
- FEAT-003 Slice 2 (depends on Slice 1):
- helix-aac2bc6a: Create resolution reference + inject into prompts
- FEAT-003 Slice 3 (depends on Slice 2):
- helix-9222038c: Bootstrap in helix frame
- helix-d70303de: Tension detection + size ceiling
Parallel Work (independent of FEAT-003)
- helix-8efeb583: Complete plugin manifest (FEAT-004)
- helix-347a49df: Create bin/helix wrapper (FEAT-004)
- helix-604b0e3d: Update validator for plugin layout (FEAT-004)
- helix-5f53e5ca: Clean up tracker junk issues
- helix-66762d1c: Update TD-002 evidence section
- hx-8447a41c: Refresh implementation plan
Blocked
- helix-ee13947a: Wire CLI to ddx exec (needs DDx FEAT-010)
- helix-6ae1e84c: Execution history in status (needs ddx exec)
- helix-5688e5bd: Principles injection research (needs injection baseline)
First Recommended Execution Set
- helix-5f53e5ca (tracker cleanup — improves queue signal immediately)
- helix-ddde7400 + helix-43b1a2d0 + helix-e186ec28 (FEAT-003 Slice 1, parallel)
- helix-8efeb583 + helix-347a49df (FEAT-004 manifest + wrapper, parallel)
- helix-66762d1c + hx-8447a41c (stale doc fixes, parallel)
Open Decisions
| Decision | Why Open | Governing Artifacts | Recommended Owner |
|---|---|---|---|
Does ${CLAUDE_PLUGIN_ROOT} resolve in SKILL.md reference paths? | Determines FEAT-004 resource resolution strategy | FEAT-004 Open Questions | HELIX maintainers |
| Should HELIX use a DDx exec shim before FEAT-010 ships? | Determines FEAT-005 timing | FEAT-005 Open Questions | HELIX maintainers + DDx maintainers |
| DDx document graph features for principles staleness tracking | Determines FEAT-003 Slice 6 feasibility | SD-002 Gaps | DDx maintainers |
Queue Health and Exhaustion Assessment
Queue state: 45 open issues, 38 ready, 7 blocked.
Signal quality: Degraded. ~15 junk/test issues inflate the ready queue. After cleanup, expect ~23 genuine ready issues.
Feature coverage:
- FEAT-001/FEAT-002: ALIGNED. Remaining work is incremental (hx-85f28129 epic, hx-8447a41c implementation plan refresh, stale doc fixes).
- FEAT-003: INCOMPLETE but fully decomposed. 7 issues, 3 ready (Slice 1), 4 blocked on Slice 1 completion.
- FEAT-004: INCOMPLETE. 4 issues, 3 ready.
- FEAT-005: INCOMPLETE. 4 issues, 2 ready (definitions), 2 blocked on DDx.
Exhaustion risk: Low for FEAT-003 and FEAT-004 (clear path). Medium for
FEAT-005 (external DDx dependency). The tracker has enough work for multiple
helix run sessions. The first execution set should prioritize queue cleanup
then FEAT-003 Slice 1 for maximum planning-stack improvement.