awslabs / awslabs/aidlc-workflows

[Bug]: bolt-plan.md is descriptive-only — Construction executes horizontally, never as the planned vertical Bolts

Open
#985 0 comments 0 reactions 1 assignee Claimed by @apackeer View on GitHub
Dominant language
TypeScript
Stars
4.6k
Forks
827
Avg merge
1d 17h
Merged PRs (30d)
158

Description

# [Bug]: `bolt-plan.md` is descriptive-only — Construction executes horizontally, never as the planned vertical Bolts

## Problem

Delivery Planning (2.9) produces `bolt-plan.md`: an ordered sequence of **Bolts**, each a vertical slice with a walking-skeleton marker, a Definition of Done, and an expected demo. But the Construction walk never executes those Bolts. It batches **Units** from `unit-of-work-dependency.md` and iterates them `unit-major` or `stage-major` — both **horizontal**. There is no `bolt-major`/vertical mode, and nothing reconciles the Bolt plan with the iteration field.

Result: a team can approve a correct walking-skeleton-first Bolt plan and still get strictly horizontal delivery (one whole unit, or one whole stage across all units) — with no runnable/reviewable increment until the end. The walking skeleton, and each Bolt's `demo` DoD, are never the unit of execution or of review.

## Source (v2)

`core/aidlc-common/stages/inception/delivery-planning.md`, Bolt glossary:
> The engine does not consume `bolt-plan.md` for Unit grouping or walk order; runtime batches come from `unit-of-work-dependency.md`.

`core/tools/aidlc-state.ts`:
```
const constructionIterationValues = ["unit-major", "stage-major"]; // both horizontal
```

## Suggested fix (additive; either helps)

1. **Reconciliation guard (cheap):** at Delivery Planning completion, if `bolt-plan.md` is walking-skeleton-first but `Construction Iteration` is horizontal, warn/block so the facilitator resolves the contradiction instead of silently getting horizontal delivery.
2. **Vertical walk (larger):** let Construction optionally slice by Bolt — build a Bolt's units to its DoD, ending in its demo, before the next — making `bolt-plan.md` load-bearing rather than descriptive.

Shipping only #1 already prevents approving a vertical plan you'll never receive.

## Environment

v2 branch (observed at dist 2.6.121; lines present through 2.6.124). Surfaced during a full Inception→Construction run of the `workshop` scope.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.