# Artifacts and garbage collection

Reflection writes every run as a reviewable artifact bundle. The bundle is designed for humans, agents, and CI systems to inspect after success or failure.

## Default artifact roots

| Context | Default root |
| --- | --- |
| Local run | `.reflection` |
| CI run with `--ci` | `artifacts/reflection` |
| Explicit override | `--report-dir <path>` |

A run is written under:

```text
<report-root>/runs/<run-id>/
```

The latest run pointer is:

```text
<report-root>/runs/latest
```

## Run bundle layout

Typical files:

```text
.reflection/runs/<run-id>/
  report.html
  report.md
  report.json
  manifest.json
  browser/
    <route-id>/
      <viewport>/
        actual.png
        metadata.json
  visual/
    <case-id>/
      expected.png
      actual.png
      diff.png
  server/
    app.log
    storybook.log
    portal/
      index.html
      reflection-portal.js
```

Not every run contains every folder. For example, a browser-only run may have screenshots but no component visual artifacts. Portal component runs keep the generated wrapper under `server/portal/` so the exact runtime shell used for the capture is available for inspection.

## `report.json`

`report.json` is the stable machine-readable summary for agents and CI. It includes:

- `runId`, `project`, mode, CI flag, and environment metadata;
- overall status: `pass`, `pass-with-review`, `fail`, or `error`;
- structured checks with `id`, `suite`, `target`, `status`, `severity`, artifacts, metadata, diagnostics, evidence, recommendations, and suggested next steps;
- optional `failureClass` and `confidence` fields for classified visual/component failures;
- top-level artifact references.

Use `reflection review --json` rather than hand-parsing reports when an agent needs a compact summary of latest evidence.

## `report.html`

`report.html` is the friendly static report portal for humans. It is generated beside
the JSON and Markdown reports and can be opened directly from the run directory or
uploaded as a CI artifact with the rest of the run bundle.

The portal embeds the report data and links to run-local artifacts such as
`expected.png`, `actual.png`, and `diff.png`. Keep the full run folder together
when sharing it so image previews and artifact links resolve correctly.

## `report.md`

`report.md` is the human-readable run summary. It links to `report.json` and keeps the PR/task surface compact:

- run identity and status;
- summary counts;
- suite-level counts;
- blocking failures and review items, when present;
- highest visual threshold usage;
- suggested next steps.

Use `report.json` for the complete check list, artifact paths, hashes, metadata, and diagnostics.

## `manifest.json`

`manifest.json` records the report files currently tracked for run retention plus whether the run is pinned.

Garbage collection uses this manifest to decide whether a run directory is eligible for deletion. Runs with missing or malformed manifests are skipped rather than deleted. Runtime evidence such as browser screenshots, visual artifacts, and logs still belongs to the run directory even though the current manifest only enumerates report files.

## Evidence artifacts

Evidence artifacts are run-scoped and safe to regenerate:

- screenshots from browser and component checks;
- visual `expected`, `actual`, and `diff` images copied or generated for the run;
- server logs;
- reports and metadata.

Evidence artifacts are not approved baselines. Approved baselines live outside run directories in the configured baseline root.

## Garbage collection

Use GC to clean old run artifacts without touching baselines:

```bash
reflection gc --dry-run
reflection gc --delete
```

With a custom report root:

```bash
reflection gc --report-dir artifacts/reflection --dry-run
```

Safety behavior:

- GC only operates under `<report-root>/runs`.
- `latest` is never treated as a run directory.
- Symlinked `runs` directories are refused.
- Symlinked run directories are skipped.
- Runs with missing, invalid, mismatched, or pinned manifests are skipped.
- Baseline roots are not part of GC.

Use `--dry-run` first in local development and CI diagnostics. Use `--delete` only when the listed eligible run directories are safe to remove.

## What to commit

Usually commit:

- `reflection.config.ts`;
- baseline images after explicit approval;
- docs or agent pointer sections;
- workflow files that run Reflection.

Usually do not commit:

- `.reflection/runs/**`;
- `artifacts/reflection/runs/**`;
- server logs;
- transient screenshots and visual diffs.

CI should upload run artifacts even when validation fails so humans and agents can inspect evidence.