awslabs / awslabs/aidlc-workflows

Gap: application-design has no step/gate/sensor reconciling refined-mockups screens + navigation shell against the Client Components catalogue

Open
#540 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.