Retro Scan S028

retro-scan-s028 — One-shot S028 Retro Baseline Scanner

Purpose (design §10.1, §7.5)

G_CONTRACT_SCOPE (the live gate from S029 WP-3) blocks every undeclared artifact at WP boundary + INTEGRATED→VERIFIED. That works for new runs. But the S028 ecosystem-keystone landed before S029 existed; its 10 INTEGRATED components carry undeclared artifacts that pre-date the gate.

The Q2 = Codex Option F policy threads the needle:

• Pre-existing artifacts that match CONTRACT_SCOPE_CRITICAL_GLOBS are added to baseline_critical_paths — they ALWAYS block recurrence (Q2 #4: critical findings always block).
• Pre-existing advisory findings are documented as a baseline snapshot but DO NOT block #45 Phase-5b thin-coverage remediation (Q2 #2: pre-existing advisory grandfathered).
• Anything newly introduced or touched during #45 still blocks (handled by the live gate, not this skill).

This skill produces the baseline.

Invocation contract

Single canonical entry point:

python3 ~/.claude/skills/retro-scan-s028/scripts/scan.py <project_root>

The scanner walks the workspace (skipping .git, .ledger, .forge, .design-ledger, __pycache__, node_modules, .venv, venv, .tox, .mypy_cache, .pytest_cache — same skip set as gates._gcs_walk_workspace), reads progress/contract-map.yaml, classifies each path, and writes progress/retro-scan-S028.yaml. Re-runs OVERWRITE (single canonical output per spec-review minor; git history preserves prior versions).

Exit codes:

• 0 — scan succeeded; output written; advisory summary printed to stdout
• 2 — env error (contract-map missing, parse failure, etc.); diagnostic on stderr

The scanner does NOT exit non-zero based on findings count or severity. Findings are an artifact for user review, not a gate verdict. (Non-blocking invariant per design §7.5.)

Output schema

The output conforms to ~/.claude/skills/_meta/schemas/retro_scan.v1.json (symlinked from schemas/retro_scan.v1.json in this skill). One source of truth — the schema is owned by S029 WP-2 and lives in _meta/schemas/.

Top-level structure:

schema_version: retro_scan.v1
generated_at: <ISO8601 Z>
generated_by: retro-scan-s028
contract_map_hash: sha256:<hex>
contract_map_revision: <int>
components:
  - component_id: <kebab-case>
    declared_source_paths: [...]
    actual_paths: [...]
    findings:
      - path: <project-relative>
        artifact_kind: <secret|db_migration|env_var|public_api|config_key|generated_artifact|file>
        in_declared: <bool>            # path is in the component's declared source_paths
        severity: pre_existing_critical | pre_existing_advisory
baseline_summary:
  total_findings: <int>
  pre_existing: <int>          # = total_findings (everything in a baseline is, by definition, pre-existing)
  pre_existing_critical: <int>
  pre_existing_advisory: <int>
  newly_introduced: 0          # always 0 in a baseline run
baseline_critical_paths: [...]  # paths classified pre_existing_critical (Q2 #4 enforcement list)

Stdout summary line example:

retro-scan-s028: 47 findings, 8 critical, 39 advisory across 10 components

Behavior (design §10.1)

For each component declared in progress/contract-map.yaml:

1. Glob each source_paths[] entry; collect actual_paths from the workspace.
2. Compute declared_set = source_paths (the component's authority). excluded_paths from the map root applies UNLESS the path is in CONTRACT_SCOPE_CRITICAL_GLOBS (M4 precedence preserved — same rule as the live gate).
3. For each actual path NOT in declared_set AND NOT in excluded_paths (with M4 carve-out): classify via extractors.first_match(project_root, path, "added"). Severity = pre_existing_critical iff path matches CONTRACT_SCOPE_CRITICAL_GLOBS, else pre_existing_advisory.
4. Aggregate across all components into baseline_summary and baseline_critical_paths.
5. Atomic-write to progress/retro-scan-S028.yaml.

Implementation detail: re-uses gates._gcs_glob_to_regex / _gcs_glob_match / _gcs_walk_workspace / _gcs_matches_critical / _gcs_in_universe directly. ** recursive-glob semantics are NOT expressible via fnmatch, so importing the gate's helpers is mandatory (spawn-2 noted this explicitly).

Invariants (design §7.5)

When NOT to invoke

• Mid-execution of #45 Phase-5b — too late; live G_CONTRACT_SCOPE is the authority once Phase-5b starts.
• On a project that has no progress/contract-map.yaml — the scanner exits 2 with a diagnostic.
• Repeatedly during a single session — the output is a baseline snapshot, not an audit trail.

Tests

tests/contract-scope/test_retro_baseline.py — 10 unit tests covering:

• TS-RS-01: clean baseline (all paths declared) → 0 findings, summary all-zero
• TS-RS-02: critical undeclared (synthetic migrations/001-x.sql) → severity=pre_existing_critical
• TS-RS-03: advisory undeclared (random .md not in CRITICAL_GLOBS) → severity=pre_existing_advisory
• TS-RS-04: M4 precedence — path matches BOTH a critical glob AND excluded_paths → critical wins
• TS-RS-05: removed-symbol case (DEFERRED per §17 OQ2; v1 file-level only) — test documents the deferral
• TS-RS-06: multi-component (2+ synthetic components, each with own findings) → output groups by component
• TS-RS-07: re-run overwrites previous output (idempotency)
• TS-RS-08: schema conformance — output validates against retro_scan.v1.json
• TS-RS-09: empty contract-map → empty output (no crash)
• TS-RS-10: glob expansion correctness with ** (uses gate's _gcs_glob_to_regex)

Provenance

• Design: docs/plans/2026-04-26-contract-scope-enforcement-keystone-design.md §7.5, §10.1, §11 WP-8 row, §17 OQ2
• Contract: progress/contract-map.yaml component retro-scan-s028-skill
• Owner: bob (S029 WP-8)
• Schema source of truth: ~/.claude/skills/_meta/schemas/retro_scan.v1.json