## Artifact Management

### Directory Structure

All artifacts are written directly under DOCUMENT_DIR:

```
DOCUMENT_DIR/
├── tests/
│   ├── environment.md
│   ├── test-data.md
│   ├── blackbox-tests.md
│   ├── performance-tests.md
│   ├── resilience-tests.md
│   ├── security-tests.md
│   ├── resource-limit-tests.md
│   └── traceability-matrix.md
├── architecture.md
├── system-flows.md
├── data_model.md
├── deployment/
│   ├── containerization.md
│   ├── ci_cd_pipeline.md
│   ├── environment_strategy.md
│   ├── observability.md
│   └── deployment_procedures.md
├── risk_mitigations.md
├── risk_mitigations_02.md          (iterative, ## as sequence)
├── adr/
│   ├── 001_[decision_slug].md
│   ├── 002_[decision_slug].md
│   └── ...
├── components/
│   ├── 01_[name]/
│   │   ├── description.md
│   │   └── tests.md
│   ├── 02_[name]/
│   │   ├── description.md
│   │   └── tests.md
│   └── ...
├── common-helpers/
│   ├── 01_helper_[name]/
│   ├── 02_helper_[name]/
│   └── ...
├── diagrams/
│   ├── components.drawio
│   └── flows/
│       ├── flow_[name].md          (Mermaid)
│       └── ...
└── FINAL_report.md
```

### Save Timing

| Step | Save immediately after | Filename |
|------|------------------------|----------|
| Step 1 | Blackbox test environment spec | `tests/environment.md` |
| Step 1 | Blackbox test data spec | `tests/test-data.md` |
| Step 1 | Blackbox tests | `tests/blackbox-tests.md` |
| Step 1 | Blackbox performance tests | `tests/performance-tests.md` |
| Step 1 | Blackbox resilience tests | `tests/resilience-tests.md` |
| Step 1 | Blackbox security tests | `tests/security-tests.md` |
| Step 1 | Blackbox resource limit tests | `tests/resource-limit-tests.md` |
| Step 1 | Blackbox traceability matrix | `tests/traceability-matrix.md` |
| Step 2 | Architecture analysis complete | `architecture.md` |
| Step 2 | System flows documented | `system-flows.md` |
| Step 2 | Data model documented | `data_model.md` |
| Step 2 | Deployment plan complete | `deployment/` (5 files) |
| Step 3 | Each component analyzed | `components/[##]_[name]/description.md` |
| Step 3 | Common helpers generated | `common-helpers/[##]_helper_[name].md` |
| Step 3 | Diagrams generated | `diagrams/` |
| Step 4 | Risk assessment complete | `risk_mitigations.md` |
| Step 4.5 | Each ADR captured | `adr/NNN_[decision_slug].md` |
| Step 4.5 | ADR index updated | `adr/README.md` |
| Step 5 | Tests written per component | `components/[##]_[name]/tests.md` |
| Step 6 | Epics created in work item tracker | Tracker via MCP |
| Final | All steps complete | `FINAL_report.md` |

### Save Principles

1. **Save immediately**: write to disk as soon as a step completes; do not wait until the end
2. **Incremental updates**: same file can be updated multiple times; append or replace
3. **Preserve process**: keep all intermediate files even after integration into final report
4. **Enable recovery**: if interrupted, resume from the last saved artifact (see Resumability)

### Resumability

If DOCUMENT_DIR already contains artifacts:

1. List existing files and match them to the save timing table above
2. Identify the last completed step based on which artifacts exist
3. Resume from the next incomplete step
4. Inform the user which steps are being skipped

#### Step 4.5 (ADR Capture) resumption rule

ADR files have a `Status` field that disambiguates "step in progress" from "step done":

- `Status: Proposed` → Step 4.5 is **in progress**. The user has not yet hit the BLOCKING gate (or hit it and chose B/C/D, which kept files at `Proposed`). Resume Step 4.5 at Phase 4.5f and re-present the BLOCKING Choose to the user. Do NOT skip to Step 5.
- `Status: Accepted` AND `adr/README.md` index exists AND every Accepted ADR is referenced in the index → Step 4.5 is **done**. Skip to Step 5.
- `Status: Accepted` but `adr/README.md` is missing or out of date → Step 4.5 is **partially complete**. Resume at Phase 4.5d (Maintain the ADR Index) before moving on.
- Mixed `Proposed` + `Accepted` files in the same directory → Step 4.5 is **in progress** with prior partial confirmations. Resume at Phase 4.5f and re-present only the still-`Proposed` ADRs.
- Empty `adr/` directory or no `adr/` directory → Step 4.5 has not started yet. Begin at Phase 4.5a.

The `Date` field on every Accepted ADR is the date the user confirmed it; do not regenerate it during resumption.
