Output storage conventions

This project stores analysis data in a repo-centric layout instead of a date-centric snapshot layout. The goal is to keep repository state easy to inspect, easy to monitor over time, and safe to reuse across repeated runs.

Repository-centric layout

Each repository gets a stable folder under the configured output root. The folder contains the current state, event history, archived analysis payloads, and any issue metadata for that repository.

Typical layout:

outputs/
└── batch-a/
    ├── run_report.json
    ├── config.json
    └── github_com_example_repo/
        ├── current-state.json
        ├── event-log.jsonl
        ├── somef_output.json
        ├── pitfall.jsonld
        ├── report.json
        ├── issue_report.md
        ├── analyses/
        │   └── <commit_or_timestamp>_analysis.json
        └── issues/
            └── issue_123.json

Important rules

  • The repository directory is the primary unit of storage.

  • The run directory remains useful for grouping runs and keeping snapshot metadata.

  • Snapshot tags such as 202603 are still used for reproducibility and run identity, but they should not force a date-centric repository layout.

  • Repeated weekly or periodic analyses should append or update the repository state in place rather than creating a new repo tree per date.

Legacy snapshot detection

Legacy output trees are still accepted only through an explicit migration step. Modern commands must reject a legacy snapshot directory and tell the user to run convert-legacy first.

This protects the project from accidentally running new analysis logic on output structures that are no longer the canonical format.

The rule is:

  • if the input path still looks like a dated snapshot tree, stop and suggest conversion;

  • if the path already contains repo-centric files such as current-state.json or event-log.jsonl, continue normally.

Conversion workflow

The conversion command accepts one concrete legacy snapshot directory and migrates its repository entries into the repo-centric layout.

Example:

uv run sw-metadata-bot convert-legacy outputs/legacy_batch/202603 --target-root outputs/converted

Do not pass a parent folder that contains multiple dated snapshots. The command expects a single snapshot root.

The converted repository folders keep the repository identity and add the repo-centric metadata files. The original run report is mirrored to the target root when present.

Flattened vs nested layout

The config option flatten_repo_layout controls whether repo directories are stored directly under the run root or nested under the snapshot directory.

  • False: keep repo directories under the snapshot directory;

  • True: flatten repo directories under the run root while still retaining run metadata and snapshot identity.

This option is a convenience for organizational preferences; it does not change how the project interprets repository state.

Operational conventions

  • run-analysis creates or updates analysis data without publishing live issues.

  • publish consumes the recorded decisions and creates or updates issues.

  • fetch checks existing issue status and updates repository state.

  • query-history reads the repository event log for debugging and monitoring.

  • report-summary reads the run report for dashboard-style summaries.

These commands must all operate on repo-centric paths, not on legacy date-based snapshot trees.

Why this design

The repo-centric model makes it easier to:

  • follow the current state of a repository,

  • inspect its event history,

  • monitor repeated analyses over time,

  • keep archive payloads close to each repository,

  • compare run-level metadata without losing repository-level continuity.

The run-level snapshot metadata remains important for reproducibility, but it is stored as metadata surrounding the repo-centric state rather than as the primary organization of the data itself.