awslabs / awslabs/aidlc-workflows
Gap: application-design has no step/gate/sensor reconciling refined-mockups screens + navigation shell against the Client Components catalogue
- Dominant language
- TypeScript
- Stars
- 4.7k
- Forks
- 853
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 165
Description
## Affected
- **Stage:** `core/aidlc-common/stages/inception/application-design.md` (inception phase)
- **Sensors:** `core/sensors/aidlc-upstream-coverage.md` + tool `core/tools/aidlc-sensor-upstream-coverage.ts`
- **Harness:** harness-neutral (lives in `core/`, so all harnesses)
- **Type:** framework gap / enhancement
## The gap (framework terms)
The construction pipeline is a catalogue-driven decomposition: `application-design`
emits the Client Components catalogue (`components.md`), and every downstream stage
(`units-generation` → `delivery-planning` → `code-generation`) decomposes *from that
catalogue*. A component that never enters `components.md` is therefore structurally
invisible from that point on — no unit owns it, no Bolt sequences it, no code-gen
builds it.
For a UI-bearing project, `application-design` is a lossy chokepoint with nothing
guarding the loss of the navigable-app layer (screens + root navigator / app shell):
1. **No template step enforces screen/nav enumeration.** The only UI-specific
instruction is a single *optional* question bullet — `application-design.md:73`:
`"- UI component structure (if user-facing, informed by UX designer perspective)"`.
The catalogue-generation step (`application-design.md:86-90`) is generic
("Component names and purposes… boundaries and ownership") and never requires
enumerating each mockup screen as a component or defining the navigation shell /
root navigator as an owned component.
2. **The declared sensors can't see the omission.** The stage declares only
`required-sections` + `upstream-coverage` (`application-design.md:35-37`).
`required-sections` just counts headings (≥2 H2). `upstream-coverage` is a pure
textual reference-match, not a coverage check — `aidlc-sensor-upstream-coverage.ts:88-99`:
```js
const pattern = new RegExp(`\\b${escaped}\\b|\\[\\[${escaped}\\]\\]`, "i");
if (!pattern.test(body)) { unreferenced.push(slug); }
```
It only tests whether each `consumes:` slug appears somewhere in the prose.
3. **`application-design` doesn't even consume the mockups.** Its `consumes:` list
(`application-design.md:19-31`) is `requirements, stories, architecture,
component-inventory, team-practices` — `mockups`/`refined-mockups` is only a
`requires_stage:` ordering edge (`application-design.md:34`), confirmed by the
stage's own Sensors note (`application-design.md:155`: "this stage consumes
`requirements`, `stories`, `team-practices`"). So `upstream-coverage` never checks
a mockup reference at all — the guard is even weaker than a reference-match on screens.
**Net effect:** a project can pass every gate, produce built-and-tested individual
screens, and still ship a build where nothing mounts them — silent (no red gate, no
failing sensor) and terminal (undiscoverable until the app is run).
### Duplicate check
Searched open + closed issues/PRs (`navigation shell mockup screen coverage`,
`application-design screen catalogue`) — no existing coverage. Not a duplicate.
### Illustrative note (external project — not evidence about this repo)
An outside AI-DLC project (an Expo/React Native app) reported this firing end to end:
`refined-mockups` specified a bottom-tab shell, `application-design` dropped it from
the catalogue, and the finished MVP had all screens built and unit-tested but no
navigator and no host to mount them. Included only as a worked example; the framework
evidence above stands on this repo alone.
## Proposed fix (proposal only — not implemented here)
Three requirements a future PR would satisfy, scoped to what's verified missing:
1. **Non-optional template step in `application-design`** that requires the stage to
(a) enumerate *every* screen named in the refined-mockups artefacts as a first-class
entry in the Client Components catalogue, and (b) define the navigation shell / root
navigator as a first-class component with a named owner. An aggregate "Screens" box
must not satisfy it; a mockup screen or nav model absent from `components.md` is a
blocking omission, not a stylistic choice.
2. **Gate question at app-design:** *"Which component owns the navigation shell that
mounts these screens into a runnable app?"* — forcing the shell to surface as an
explicit, human-visible decision at the approval gate.
3. **New `mockup-screen-coverage` sensor** performing a real coverage check (not a
reference-match): every screen and every primary-navigation element named in the
refined-mockups artefacts maps to ≥1 enumerated component in `components.md`, and
(re-checked at `units-generation`) to ≥1 unit. Wired into both stages' `sensors:`
lists. Note: since `application-design` does not currently declare `mockups` in
`consumes:`, the PR must also add that consume edge (or give the sensor an explicit
mockups path) so the sensor has something to read.
## Open design question for maintainers
Does the repo have a **stable, machine-readable contract** for the screen and
navigation names inside the refined-mockups artefacts (`mockups.md`,
`design-system-mapping.md`, etc.) that a sensor could parse deterministically? Today
those appear to be free-form markdown. If there's no reliable structure to extract
screen/nav identifiers from, that's a **prerequisite** for a real coverage check (fix
#3) — the issue should be scoped to establish that contract first, rather than assume
the sensor can parse the current prose.
## Environment
- Repo branch: `v2`
- Harness: harness-neutral (`core/`); reproduced against the authored source, not a
specific CLI/model run.
Contributor guide
Research direction
Start with core/aidlc-common/stages/inception/application-design.md, core/sensors/aidlc-upstream-coverage.md, and core/tools/aidlc-sensor-upstream-coverage.ts, then inspect the refined-mockups artefacts and existing sensor wiring. Determine whether screen and navigation names have a stable machine-readable contract before scoping the template, gate, and coverage sensor changes. Done means the agreed coverage is enforceable in application-design and units-generation, with the relevant consume edge and sensors wired in.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, typescript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100