# Status Workflow

## Purpose

This document defines the status synchronization workflow for the assessment
artifacts. The goal is to keep narrative documents aligned with one canonical,
machine-readable source.

## Canonical Source

Canonical source of truth: [artifacts/status-matrix.csv](artifacts/status-matrix.csv:1)

The CSV tracks:
- methodology phases;
- exposure categories;
- open, partial, closed, and blocked gaps;
- artifact-level status;
- selected dataset-processing gaps.

If a narrative document and `status-matrix.csv` disagree, `status-matrix.csv`
wins.

## Status Vocabulary

- `closed`: deliverable or gap is complete
- `partial`: meaningful coverage exists, but significant work remains
- `open`: work is incomplete and not externally blocked
- `blocked`: work cannot currently proceed because of encryption, ethics, or a similar external constraint

## Managed Files

Generated from `status-matrix.csv`:
- [artifacts/gap-analysis.md](artifacts/gap-analysis.md:278)
  This file contains a managed block between `<!-- status-summary:start -->` and `<!-- status-summary:end -->`.

Validated against `status-matrix.csv`:
- [artifacts/gap-analysis.md](artifacts/gap-analysis.md:1)
- [artifacts/credential-scope-assessment.md](artifacts/credential-scope-assessment.md:742)

## Commands

```bash
make sync-status
make status-report
```

`make sync-status` runs:
- `python3 scripts/generate_status_summary.py`
- `python3 scripts/validate_status_matrix.py`

`make status-report` runs:
- `python3 scripts/status_report.py`

## Scripts

- [scripts/generate_status_summary.py](scripts/generate_status_summary.py:1)
  Regenerates the managed summary block in `artifacts/gap-analysis.md`.

- [scripts/validate_status_matrix.py](scripts/validate_status_matrix.py:1)
  Validates CSV structure, allowed status values, parent references, source file references, narrative phase/category status sync, and freshness of the managed block.

- [scripts/status_report.py](scripts/status_report.py:1)
  Prints a read-only operational summary of `closed` / `partial` / `open` / `blocked` items and high-signal gaps.

## Editing Rules

When changing status:
1. Update `artifacts/status-matrix.csv`.
2. Run `make sync-status`.
3. Review the resulting diff in `artifacts/gap-analysis.md`.

Do not edit the managed status-summary block in `artifacts/gap-analysis.md`
manually. It is owned by `scripts/generate_status_summary.py`.

Narrative prose outside the managed block may be edited manually, but it must
not contradict the CSV.

## Current Scope

This workflow currently manages status synchronization, not full narrative
generation. The canonical CSV does not yet regenerate
`artifacts/credential-scope-assessment.md` or other deliverables beyond the
managed block in `gap-analysis.md`.