## 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)
├── 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 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
