awslabs / awslabs/aidlc-workflows

[Feature]: Separate per-unit artifact folders from stage-diary folders under construction/

Open
#862 1 comment 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.