awslabs / awslabs/aidlc-workflows
[Feature]: Separate per-unit artifact folders from stage-diary folders under construction/
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 827
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 165
Description
### Description
In v2, under a workflow's per-intent `construction/` record directory, two structurally *different* kinds of subfolder live at the **same level**:
- **Per-unit artifact folders**, named by unit slug — e.g. `construction/mined-value-schema/`, `construction/contract-synthesizer/` — each containing per-stage artifact subdirs (`functional-design/`, `nfr-design/`, `code-generation/`, ...) with the actual deliverables (`entities.md`, `rules.md`, `traceability.json`, etc.).
- **Stage-diary folders**, named by stage — e.g. `construction/functional-design/`, `construction/nfr-design/`, `construction/code-generation/` — that hold only the shared, cross-unit stage `memory.md` observation diary.
The two collide by name and by level. `construction/functional-design/memory.md` is the **shared stage diary**, while `construction//functional-design/` is **one unit's artifacts** for that same stage. Browsing `construction/`, you cannot tell a unit folder from a stage-diary folder without already knowing the unit slugs — and the identical inner stage names (`functional-design/` appearing both as a top-level diary folder and as a child of every unit) make it easy to open the wrong one.
Proposal: nest the two axes under **distinct roots** so they never share a level, e.g.
```
construction/
units/
mined-value-schema/
functional-design/ ...
contract-synthesizer/
functional-design/ ...
_stages/ # or fold the diary into each unit's stage dir
functional-design/memory.md
nfr-design/memory.md
```
The exact scheme is open (a `units/` + `_stages/` split, a prefix convention, or moving the diary into the per-unit stage dir) — the ask is simply that per-unit artifact folders and harness/stage-diary folders not be siblings at the same level.
### Use Case
Unit-major Construction with many units. On a live v2 run with 11 units, humans and reviewers browsing the record repeatedly mistake a stage-diary folder for a unit (and vice versa), because both sit directly under `construction/` and reuse the same stage names. A clear structural separation makes the record self-describing and navigable at a glance, and removes the "which `functional-design/` is this?" ambiguity.
This is orthogonal to:
- **#795** (units-major *parallelism* / teams owning units) — that is about execution ordering, not on-disk layout.
- **#126** (multi-intent namespacing, closed) — already solved by the `intents//` directory; this is purely the *intra-`construction/`* organization.
### Version
v2 (alpha)
### Area
Construction phase rules
### Additional Context
Observed on a real v2 unit-major run (Kiro IDE harness). The stage-diary folders are created lazily (only for stages that have run), so early in a run `construction/` shows a partial, mixed set of unit-slug and stage-name folders, which compounds the confusion. Backward-compatibility note: any change here touches the engine's artifact-path resolution (`produces[]` path templates + the stage `memory_path`), so it would want a migration/compat shim for in-flight workflows.
Contributor guide
Research direction
Start with the engine's artifact-path resolution, especially the produces[] path templates and the stage memory_path referenced in the issue. Define a layout that separates per-unit artifacts from stage diaries, then verify that new paths are self-describing and that a migration or compatibility path exists for in-flight workflows.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100