Alignment Review: Repository

Review Metadata

Review Date: 2026-04-10
Scope: repo
Status: complete
Review Epic: helix-a01d3f01
Primary Governing Artifact: workflows/README.md (helix.workflow)
Governing Bead: helix-93e11c09
Review Issue: helix-a295cd39 - workflow and CLI contract
Review Issue: helix-ae3c2e23 - DDx execution boundary and loop delegation
Review Issue: helix-4ed9af82 - FEAT-006 queue metadata propagation
Review Issue: helix-fffdc7e2 - public documentation contract
Review Issue: helix-7be9d4a9 - microsite and demo surfaces
This pass supersedes the earlier 2026-04-10 repo review content previously recorded in this file.

Scope and Governing Artifacts

Scope

Workflow and CLI contract
DDx execution boundary and loop delegation
FEAT-006 queue metadata propagation
Public documentation contract
Microsite and demo surfaces

Governing Artifacts

docs/helix/00-discover/product-vision.md:5-12
docs/helix/00-discover/product-vision.md:117-136
docs/helix/01-frame/prd.md:14-20
docs/helix/01-frame/prd.md:87-130
docs/helix/01-frame/features/FEAT-002-helix-cli.md:10-30
docs/helix/01-frame/features/FEAT-002-helix-cli.md:82-123
docs/helix/01-frame/features/FEAT-006-concerns-practices-context-digest.md:15-24
docs/helix/01-frame/features/FEAT-006-concerns-practices-context-digest.md:241-260
docs/helix/01-frame/features/FEAT-007-microsite-and-demos.md:73-97
docs/helix/01-frame/features/FEAT-011-slider-autonomy.md:82-97
docs/helix/01-frame/features/FEAT-011-slider-autonomy.md:141-162
docs/helix/02-design/contracts/CONTRACT-001-ddx-helix-boundary.md:32-40
docs/helix/02-design/contracts/CONTRACT-001-ddx-helix-boundary.md:153-190
docs/helix/02-design/technical-designs/TD-011-slider-autonomy-implementation.md:206-233
docs/helix/03-test/test-plans/TP-002-helix-cli.md:34-45
docs/helix/03-test/test-plans/TP-002-helix-cli.md:46-83
docs/helix/04-build/implementation-plan.md:49-58
workflows/README.md:20-32
workflows/README.md:83-98
workflows/actions/reconcile-alignment.md:61-135
workflows/actions/reconcile-alignment.md:196-247
workflows/references/context-digest.md:20-67
workflows/actions/fresh-eyes-review.md:186-225
docs/helix/01-frame/concerns.md:3-28
.github/workflows/pages.yml:65-87
website/content/docs/demos/_index.md:9-15
website/playwright.config.ts:3-25
website/e2e/microsite.spec.ts:188-206
docs/demos/helix-interactive/README.md:3-5

Intent Summary

Vision: HELIX is a supervised autopilot where the tracker is the steering wheel, planning and execution interleave as a double helix, and DDx owns the managed execution substrate beneath HELIX workflow semantics (docs/helix/00-discover/product-vision.md:5-12, docs/helix/00-discover/product-vision.md:117-136).
Requirements: The repo must keep retained HELIX command surfaces thin, route managed execution through DDx, preserve deterministic bead context and area labels, and keep public docs and demos synchronized with the live workflow contract (docs/helix/01-frame/prd.md:42-50, docs/helix/01-frame/prd.md:111-130).
Features / Stories: FEAT-002 governs the CLI compatibility surface, FEAT-006 governs concerns/practices/context digests, FEAT-007 governs the public microsite and demo inventory, and FEAT-011 governs sparse-intent intake plus the DDx handoff model (docs/helix/01-frame/features/FEAT-002-helix-cli.md:10-30, docs/helix/01-frame/features/FEAT-006-concerns-practices-context-digest.md:15-24, docs/helix/01-frame/features/FEAT-007-microsite-and-demos.md:73-97, docs/helix/01-frame/features/FEAT-011-slider-autonomy.md:82-97).
Architecture / ADRs: CONTRACT-001 and TD-011 define the live boundary: DDx owns execute-bead and execute-loop; HELIX owns workflow routing, review, alignment, and interpretation of DDx outcomes (docs/helix/02-design/contracts/CONTRACT-001-ddx-helix-boundary.md:32-40, docs/helix/02-design/contracts/CONTRACT-001-ddx-helix-boundary.md:153-190, docs/helix/02-design/technical-designs/TD-011-slider-autonomy-implementation.md:206-233).
Technical Design: Retained planning surfaces such as helix align must be bead-governed prompt launchers, and compatibility execution wrappers must delegate to DDx without recreating a parallel claim/execute/close contract (docs/helix/01-frame/features/FEAT-002-helix-cli.md:86-119, docs/helix/01-frame/features/FEAT-011-slider-autonomy.md:94-97).
Test Plans: TP-002 requires deterministic proof for wrapper help, alignment-bead acquisition, queue-drain delegation, and queue/claim behavior, while the context-digest validator enforces live queue metadata hygiene (docs/helix/03-test/test-plans/TP-002-helix-cli.md:34-83).
Implementation Plans: The implementation plan explicitly says it is a mutable queue snapshot that must be rebuilt whenever tracker state or command surface changes, so stale counts and stale backlog IDs are contract drift, not harmless lag (docs/helix/04-build/implementation-plan.md:49-58).

Planning Stack Findings

Finding	Type	Evidence	Impact	Review Issue
The retained `helix align` surface is required to create or claim the governing align bead and refresh deterministic context before the stored prompt runs, but `find_alignment_bead` still treats any non-closed bead as reusable and `ensure_alignment_bead` still creates new governing beads without a digest or scope-derived area labels	downstream-mismatch	`docs/helix/01-frame/features/FEAT-011-slider-autonomy.md:94-97`; `workflows/actions/reconcile-alignment.md:107-146`; `workflows/references/context-digest.md:20-67`; `scripts/helix:792-842`	High: the wrapper now owns bead acquisition, but its edge-case handling still violates the stored action contract	`helix-a295cd39`
FEAT-011, CONTRACT-001, and TD-011 say HELIX may delegate queue draining to `ddx agent execute-loop`, but HELIX still performs post-cycle bookkeeping against its locally selected bead while `execute-loop` is invoked with no supported selector or returned bead identity	contradiction	`docs/helix/01-frame/features/FEAT-011-slider-autonomy.md:141-162`; `docs/helix/02-design/contracts/CONTRACT-001-ddx-helix-boundary.md:153-190`; `docs/helix/02-design/technical-designs/TD-011-slider-autonomy-implementation.md:214-267`; `scripts/helix:1111-1112`; `scripts/helix:3083-3089`; `tests/helix-cli.sh:371-376`	High: HELIX can mark the wrong bead as failed, blocked, reviewed, or promoted when DDx drains a different ready item	`helix-ae3c2e23`
The FEAT-002 compatibility contract says `helix build` should resolve a matching execution-ready bead before calling `ddx agent execute-bead`, but `resolve_execution_target` still accepts any bead ID that exists in the tracker, including closed beads	downstream-mismatch	`docs/helix/01-frame/features/FEAT-002-helix-cli.md:108-119`; `scripts/helix:1031-1050`; `HELIX_EXEC_CONTEXT=1 bash scripts/helix build --dry-run helix-9efef95b` on 2026-04-10 printed `ddx agent execute-bead helix-9efef95b ...` even though `helix-9efef95b` is closed	Medium: a compatibility wrapper can dispatch non-ready work into DDx-managed execution	`helix-ae3c2e23`
The public tracker-default contract is still inconsistent: `scripts/helix` resolves `${target_root}/.ddx` by default, but live help text and the execution guide still document `HELIX_TRACKER_DIR` as defaulting to `.helix/`	contradiction	`scripts/helix:28-30`; `scripts/helix:311-320`; `workflows/EXECUTION.md:482-489`; `bash scripts/helix help` on 2026-04-10	Medium: public docs still advertise the wrong built-in tracker root for the canonical bead store	`helix-fffdc7e2`
The implementation plan explicitly says it must be rebuilt from `ddx bead status`, `ddx bead list --status open --json`, and `bash scripts/helix help`, but the current queue snapshot and backlog references still point at older counts and stale issue IDs	stale	`docs/helix/04-build/implementation-plan.md:49-58`; `docs/helix/04-build/implementation-plan.md:91-110`; `ddx bead status` on 2026-04-10 reported `37` open / `35` ready / `2` blocked during this pass, with review-control beads included	Medium: the implementation plan is again unreliable as a public queue-steering artifact	`helix-fffdc7e2`

Implementation Map

Topology: Shell orchestration and wrappers live in scripts/helix and bin/helix; workflow contracts live in workflows/; governing artifacts live in docs/helix/; deterministic verification lives in tests/; the microsite lives in website/; scripted demos live in docs/demos/.
Entry Points: scripts/helix, bin/helix, .claude-plugin/plugin.json, skills/*/SKILL.md, the numbered docs/helix/ artifact stack, and the Hugo site under website/content/docs/.
Test Surfaces: bash tests/helix-cli.sh; bash tests/validate-context-digests.sh; website/playwright.config.ts; website/e2e/microsite.spec.ts; .github/workflows/pages.yml.
Public Interfaces: CLI help output, the built-in tracker at .ddx/beads.jsonl, published workflow docs under workflows/, the implementation plan under docs/helix/04-build/implementation-plan.md, and the public demos page under website/content/docs/demos/_index.md.
Build and Deploy Surfaces: ddx bead queue state, DDx-managed execute-bead / execute-loop dispatch from the wrapper, Hugo Pages publishing, and Playwright microsite coverage.
Unplanned Areas: No current unplanned public demo surface was found. docs/demos/helix-interactive/ is now explicitly marked experimental/internal and excluded from the shipped public inventory (docs/demos/helix-interactive/README.md:3-5).

Acceptance Criteria Status

Story / Feature	Criterion	Test Reference	Status	Evidence
FEAT-002	`helix help` shows the current command surface and key options, including `helix input` and DDx-managed wrapper guidance	`bash tests/helix-cli.sh`	SATISFIED	`scripts/helix:243-320`; `bash scripts/helix help` on 2026-04-10; `bash tests/helix-cli.sh` passed 126 tests
FEAT-002 / FEAT-011	`helix align` creates or claims a governing `kind:planning,action:align` bead before dispatching the stored prompt	`bash tests/helix-cli.sh`	SATISFIED	`scripts/helix:1588-1607`; `scripts/helix:2185-2195`; `tests/helix-cli.sh:2174-2175`; `bash tests/helix-cli.sh` passed
Reconcile-alignment / context-digest contract	A newly created or reused governing align bead is safe to reuse and already carries deterministic digest/area context before the prompt begins	none	UNIMPLEMENTED	`workflows/actions/reconcile-alignment.md:120-146`; `scripts/helix:796-842` still reuses in-progress beads and creates new ones without digest refresh in the wrapper path
FEAT-011 / CONTRACT-001	`helix run` delegates queue-drain execution to DDx-managed `execute-loop`	`bash tests/helix-cli.sh`	SATISFIED	`scripts/helix:3083-3085`; `scripts/helix:1111-1112`; `bash tests/helix-cli.sh` includes `run delegates build cycles to execute-loop` and passed
CONTRACT-001 / TD-011	HELIX applies drift handling, review, and bookkeeping to the bead DDx actually executed	none	UNIMPLEMENTED	`scripts/helix:1111-1112`; `scripts/helix:3083-3089`; `tests/helix-cli.sh:371-376` still masks the selection mismatch through `HELIX_SELECTED_ISSUE`
FEAT-002	`helix build <selector>` rejects closed, blocked, or non-execution-ready beads before DDx dispatch	none	UNIMPLEMENTED	`docs/helix/01-frame/features/FEAT-002-helix-cli.md:108-119`; `scripts/helix:1031-1050`; dry-run against closed `helix-9efef95b` still dispatched `ddx agent execute-bead helix-9efef95b ...`
FEAT-006	Open HELIX beads carry current `<context-digest>` blocks and live review findings carry `area:*` labels	`bash tests/validate-context-digests.sh`	SATISFIED	Open-queue audit on 2026-04-10 found `0` open non-review/non-planning beads missing digests and `0` review-finding beads missing `area:*`; `bash tests/validate-context-digests.sh` passed
FEAT-007	The shipped public demo inventory is quickstart, concerns, evolve, and experiment, while `helix-interactive` remains explicitly out of scope for the public site and Pages recording	`website/e2e/microsite.spec.ts:188-206`	SATISFIED	`docs/helix/01-frame/features/FEAT-007-microsite-and-demos.md:84-97`; `docs/helix/01-frame/concerns.md:22-28`; `.github/workflows/pages.yml:72-75`; `website/content/docs/demos/_index.md:11-15`; `docs/demos/helix-interactive/README.md:3-5`
Implementation plan contract	The implementation plan queue snapshot is refreshed when tracker state or command surface changes	none	UNIMPLEMENTED	`docs/helix/04-build/implementation-plan.md:49-58`; `docs/helix/04-build/implementation-plan.md:91-110`; current tracker counts and open issue set have drifted

Gap Register

Area	Classification	Planning Evidence	Implementation Evidence	Resolution Direction	Issue
Workflow and CLI contract	DIVERGENT	`docs/helix/01-frame/features/FEAT-002-helix-cli.md:86-119`; `docs/helix/01-frame/features/FEAT-011-slider-autonomy.md:94-97`; `workflows/actions/reconcile-alignment.md:120-146`	`scripts/helix:792-842`; `scripts/helix:311-320`; `bash scripts/helix help` on 2026-04-10	code-to-plan	`helix-a295cd39`
DDx execution boundary and loop delegation	DIVERGENT	`docs/helix/02-design/contracts/CONTRACT-001-ddx-helix-boundary.md:153-190`; `docs/helix/02-design/technical-designs/TD-011-slider-autonomy-implementation.md:214-267`; `docs/helix/01-frame/features/FEAT-002-helix-cli.md:108-119`	`scripts/helix:1031-1050`; `scripts/helix:1111-1112`; `scripts/helix:3083-3089`; `tests/helix-cli.sh:371-376`; `HELIX_EXEC_CONTEXT=1 bash scripts/helix build --dry-run helix-9efef95b` on 2026-04-10	code-to-plan	`helix-ae3c2e23`
FEAT-006 queue metadata propagation	ALIGNED	`docs/helix/01-frame/features/FEAT-006-concerns-practices-context-digest.md:241-260`; `workflows/actions/fresh-eyes-review.md:186-225`	Open-queue audit on 2026-04-10 found `0` missing digests and `0` unlabeled review findings; `bash tests/validate-context-digests.sh` passed	quality-improvement	`helix-4ed9af82`
Public documentation contract	STALE_PLAN	`docs/helix/04-build/implementation-plan.md:49-58`; `docs/helix/04-build/implementation-plan.md:91-110`; `workflows/EXECUTION.md:482-489`	`ddx bead status` on 2026-04-10; `bash scripts/helix help` on 2026-04-10; `scripts/helix:28-30`; `scripts/helix:311-320`	plan-to-code	`helix-fffdc7e2`
Microsite and demo surfaces	ALIGNED	`docs/helix/01-frame/features/FEAT-007-microsite-and-demos.md:84-97`; `docs/helix/01-frame/concerns.md:22-28`	`.github/workflows/pages.yml:72-75`; `website/content/docs/demos/_index.md:11-15`; `website/e2e/microsite.spec.ts:188-206`; `docs/demos/helix-interactive/README.md:3-5`	quality-improvement	`helix-7be9d4a9`

Quality Findings

Area	Dimension	Concern	Severity	Resolution	Issue
Workflow and CLI contract	Robustness	Plugin-wrapper delegation still lacks full deterministic proof coverage for `bin/helix`, so part of FEAT-004 remains inspection-backed rather than test-backed	Medium	quality-improvement	`helix-0d48272d`
DDx execution boundary and loop delegation	Robustness	The deterministic wrapper harness still relies on the private `HELIX_SELECTED_ISSUE` environment variable in its DDx test double, which hides the exact queue-drain identity mismatch this review found	High	quality-improvement	`helix-4243dd31`
FEAT-006 queue metadata propagation	Maintainability	The live queue is clean, but dedicated deterministic proof for review-finding `area:*` filing and backfill remains open, so this alignment remains partially audit-backed	Medium	quality-improvement	`helix-0ddcae85`

Traceability Matrix

Vision	Requirement	Feature/Story	Arch/ADR	Design	Tests	Impl Plan	Code Status	Classification
Supervisory autopilot with tracker-first steering	Thin retained HELIX surfaces over DDx-managed execution	FEAT-002, FEAT-011	CONTRACT-001	TD-011 retained-surface rules	`bash tests/helix-cli.sh`; `TP-002`	`docs/helix/04-build/implementation-plan.md`	Help and bead acquisition exist, but retained align wrapper edge cases still violate the stored action contract	DIVERGENT
DDx owns queue drain and bounded execution; HELIX owns supervision	`execute-loop` / `execute-bead` are the managed execution primitives	FEAT-002, FEAT-011	CONTRACT-001	TD-011 handoff flow	`bash tests/helix-cli.sh`	same implementation plan	Delegation exists, but HELIX still assumes its preselected bead is what DDx executed and still accepts closed/non-ready build selectors	DIVERGENT
Beads re-enter execution with current context and concern metadata	FEAT-006 digests and area labels remain current on open work	FEAT-006	concern-resolution / fresh-eyes review contract	context-digest reference	`bash tests/validate-context-digests.sh`	same implementation plan	Live queue metadata is now clean; only residual proof-lane debt remains	ALIGNED
Public docs should describe the live tracker and queue state	Queue snapshot and tracker defaults must match current code	supporting repo docs	`helix.workflow`	implementation plan / EXECUTION docs	`bash scripts/helix help`; `ddx bead status`	`docs/helix/04-build/implementation-plan.md`	Queue counts, backlog references, and tracker-default docs are stale	STALE_PLAN
Public microsite and demos should match the governed public inventory	FEAT-007 required demos and interactive-demo status stay synchronized across docs, site, and CI	FEAT-007	hugo-hextra / demo-asciinema / e2e-playwright concerns	demos page + Pages workflow	`website/e2e/microsite.spec.ts:188-206`	n/a	Public demo inventory and interactive-demo status are aligned	ALIGNED

Review Issue Summary

Review Issue	Area	Summary
`helix-a295cd39`	Workflow and CLI contract	The retained align wrapper is now bead-governed, but it still mishandles in-progress governing beads and still creates new align beads without deterministic digest/area context
`helix-ae3c2e23`	DDx execution boundary and loop delegation	DDx delegation exists, but HELIX bookkeeping still assumes local issue selection survives `execute-loop`, and `build` still accepts closed or non-ready selectors
`helix-4ed9af82`	FEAT-006 queue metadata propagation	The live queue now satisfies digest and area-label expectations; only residual proof-lane hardening remains
`helix-fffdc7e2`	Public documentation contract	Help text, execution-guide tracker defaults, and the implementation-plan queue snapshot still drift from the live repo behavior
`helix-7be9d4a9`	Microsite and demo surfaces	The shipped public demos, Pages workflow, site content, and interactive-demo status are now aligned

Execution Issues Generated

No new execution issues were required. This pass reused the existing open issue set for the real gaps:

Issue ID	Type	Labels	Goal	Dependencies	Verification
`helix-bec526ad`	task	`phase:build,review-finding,area:cli,area:workflow`	Stop `helix align` from reusing an in-progress governing bead owned by another actor	none	`helix align repo` behavior against open vs in-progress governing beads
`helix-674b1b42`	task	`phase:build,review-finding,area:cli,area:workflow`	Ensure freshly created align beads carry deterministic `area:*` labels and digest context before prompt dispatch	none	new align bead creation plus digest refresh evidence
`helix-4243dd31`	task	`phase:build,review-finding,area:cli,area:testing,area:workflow`	Align HELIX bookkeeping with the bead DDx actually executes	none	deterministic wrapper regression without `HELIX_SELECTED_ISSUE` crutch
`helix-ded1e007`	task	`phase:build,review-finding,area:cli,area:testing,area:workflow`	Reject closed, blocked, or non-ready selectors before `execute-bead` dispatch	none	regression case for closed selector
`helix-c28ea8af`	task	`phase:build,review-finding,area:cli,area:docs,area:workflow`	Align help text and execution-guide tracker defaults with `.ddx`	none	`bash scripts/helix help`; `workflows/EXECUTION.md`; `git diff --check`
`helix-c3ff5fdf`	task	`phase:build,kind:docs,area:cli,area:docs,area:workflow`	Refresh implementation-plan queue snapshot and stale backlog references	depends on `helix-268c54ee`	`ddx bead status`; `ddx bead list --status open --json`; `git diff --check`

Issue Coverage Verification

Gap / Criterion	Covering Issue	Status
Align wrapper must not silently reuse an in-progress governing bead	`helix-bec526ad`	covered
New align governing beads need deterministic digest and area context before the prompt runs	`helix-674b1b42`	covered
`execute-loop` bookkeeping must use the bead DDx actually executed	`helix-4243dd31`	covered
`helix build <selector>` must reject closed or non-ready beads	`helix-ded1e007`	covered
Public tracker-default docs must match `.ddx` semantics	`helix-c28ea8af`	covered
Implementation-plan queue snapshot must be refreshed	`helix-c3ff5fdf`	covered
FEAT-006 queue metadata propagation	existing queue state plus `helix-0ddcae85` quality hardening	covered

Execution Order

helix-bec526ad and helix-674b1b42
helix-4243dd31 and helix-ded1e007
helix-c28ea8af
helix-c3ff5fdf

Critical Path: helix-bec526ad / helix-674b1b42 -> helix-4243dd31 / helix-ded1e007 -> helix-c28ea8af -> helix-c3ff5fdf Parallel: helix-bec526ad with helix-674b1b42; helix-4243dd31 with helix-ded1e007; helix-c28ea8af may proceed independently of the align-wrapper fixes Blockers: helix-c3ff5fdf still depends on helix-268c54ee; wrapper-bookkeeping work remains riskier until DDx exposes or HELIX consumes a supported bead-identity handoff First Recommended Execution Set: helix-bec526ad, helix-674b1b42, and helix-c28ea8af

Open Decisions

Decision	Why Open	Governing Artifacts	Recommended Owner
Should `helix run` keep preselecting a bead locally before calling `ddx agent execute-loop --once`, or should HELIX instead consume an explicit bead-identity/result surface from DDx and stop assuming local selection survives delegation?	The current contract requires DDx-owned queue drain, but the exact supported identity handoff is still not codified in the live wrapper contract	`CONTRACT-001`; `TD-011`; `FEAT-002`; `FEAT-011`	HELIX and DDx maintainers

Queue Health and Exhaustion Assessment

During this pass, ddx bead status reported 37 open, 35 ready, and 2 blocked. Those counts include the governing align bead plus the review epic and five review issues created for this alignment pass.
After recording measurement results, closing the review-control beads, and closing the two stale satisfied findings (helix-6132f8fa, helix-9e38e71e), ddx bead status reported 29 open, 27 ready, and 2 blocked.
Excluding review-control work, the live queue still has concentrated workflow/docs drift rather than broad feature breakage. FEAT-006 propagation debt and FEAT-007 public demo inventory drift are no longer driving the queue.
Queue noise remains moderate because at least two open execution beads are now stale relative to current behavior: helix-6132f8fa (help now exposes helix input) and helix-9e38e71e (core align bead acquisition now exists). This pass closes them after measurement.
Exhaustion risk is low for the public-doc fixes and medium for the DDx-boundary fixes, because the remaining wrapper gaps sit at the HELIX/DDx seam and require careful deterministic proof.

Measurement Results

Completeness: PASS - all five functional areas in scope were classified.
Traceability: PASS - each material finding cites governing planning evidence plus current implementation, test, site, CI, or tracker evidence.
Issue coverage: PASS - every non-ALIGNED gap is covered by an existing open execution issue set; no prose-only follow-up remains.
Concern drift: PASS - the live queue now satisfies FEAT-006 digest and area-label expectations, and the public demo inventory is consistent across concerns, site, Pages, and the interactive-demo README.
Verification evidence: bash tests/helix-cli.sh passed (PASS: 126 helix wrapper tests), bash tests/validate-context-digests.sh passed, and the closed-selector dry-run reproduced the remaining build selector bug.

Follow-On Beads Created

None. This pass reused the existing open execution issue set and closed stale satisfied findings instead of creating duplicate work.

ALIGN_STATUS: COMPLETE GAPS_FOUND: 3 EXECUTION_ISSUES_CREATED: 0 MEASURE_STATUS: PASS BEAD_ID: helix-93e11c09 FOLLOW_ON_CREATED: 0