# GCS-AUDIT-001 - Contract Implementation Audit

Spec ID      : GCS-AUDIT-001
Title        : Contract Implementation Audit
Version      : v1.0
Status       : Settled
Owner        : Phil
Approver     : Phil
Settled      : 2026-07-08
Depends on   : GCS-REGISTER-001, GCS-TEST-001
Supersedes   : -

## 1. Audit Table

| Contract | Implementation files governed | Positive tests | Negative tests | Validation command | Current status | Exact remediation |
| --- | --- | --- | --- | --- | --- | --- |
| GCS-REGISTER-001 | `contracts/GCS-*.md` | Registered Settled artifacts exist | Add unregistered `contracts/GCS-*.md` | `python3 -m tools.check_contracts --check` | Compliant | Keep register updated with every contract artifact |
| GCS-OVERVIEW-001 | `contracts/*.md`, phase docs | Overview opens only Phase 0B file-backed storage skeleton | Add app/runtime files outside Phase 0B allowlist | `python3 -m tools.check_contracts --check` | Compliant; Phase 0A complete | Keep overview aligned when Phase 0B exits |
| GCS-SYS-001 | Contracts and public claim language | Claims require concordance and primary records | Claim from single/ambient source | Human review plus future data gates | Compliant for contract surface | Add automated claim lint once data outputs exist |
| GCS-NAME-001 | `index.html`, `build/**/*.html`, `assets/*.js`, `tools/*.py`, workflow YAML | Required source headers present | Remove a required header label | `python3 -m tools.check_contracts --check` | Compliant | Keep source header labels exact; `build/` is the flagship instrument path |
| GCS-NAME-002 | Contract terms and future code names | Required vocabulary terms exist | Remove `no_async_queue` or `contract_header` | `python3 -m tools.check_contracts --check` | Compliant | Add vocabulary row before adding a new concept |
| GCS-STACK-001 | Study + `build/` instrument; `app/__init__.py`; `app/raw_store/`; `app/normalization/`; `app/sources/fixtures/`; future `app/persistence/`; future `migrations/`; Phase 0B and future Phase 0D tests | Product surface open; only Phase 0B storage paths and Phase 0D persistence paths are allowed under `app/` | Add `app/signals/`, `app/entity_resolution/`, `app/prediction/`, `api/`, invalid migration names, standalone SQL, active Compose, live clients, or queues | `python3 -m tools.check_contracts --check` | Compliant; product surface active; Phase 0D deferred | Prefer instrument deepening; amend stack before widening `app/` beyond physical persistence |
| GCS-DATA-002 | `app/normalization/`, `app/sources/fixtures/`, `tests/normalization/`, `tests/fixtures/` | Fixed metadata fixture normalizes deterministically with authority tier and source identifier | Missing `as_of_timestamp`, missing source authority tier, or future-known timestamp | `python3 -m unittest discover -s tests/normalization -v`; `python3 -m unittest discover -s tests/fixtures -v` | Compliant; Phase 0B complete for fixture-only metadata | Do not add live source clients or data pulls until Phase 1 is contract-opened |
| GCS-DATA-003 | `contracts/GCS-DATA-003_Persistence_Contract.md`, `app/raw_store/`, `app/normalization/point_in_time.py`, future `app/persistence/`, future `migrations/`, future `tests/persistence/` | Phase 0C physical inventory is present and Phase 0D implementation allowance is named | Remove a required inventory clause; add DB code outside persistence paths; add SQL, API, queues, containers, live clients, or invalid migrations | `python3 -m tools.check_contracts --check`; `python3 -m unittest discover -s tests/raw_store -v`; future `python3 -m unittest discover -s tests/persistence -v` | Compliant; Phase 0D implementation-eligible, not started | Implement Phase 0D only inside `app/persistence/`, `migrations/NNNN_<snake_case>.py`, and `tests/persistence/`; amend DEPLOY-002 before containers |
| GCS-SIG-003 | Signal contract only in Phase 0 | No causal claim rests on correlation | Add prediction output without OOS proof | Future signal tests | Compliant for contract surface | Implement only after DATA spine passes |
| GCS-API-001 | No API files in Phase 0 | No route/DTO implementation exists | Add `api/` without endpoint inventory | `python3 -m tools.check_contracts --check` | Compliant for Phase 0 | Amend endpoint inventory before API code |
| GCS-RUNTIME-001 | Source files, runtime config, `tests/fixtures/test_phase_0b_boundaries.py` | No queue/broker/runtime service code exists in Phase 0B | Add Celery/Redis/queue token or forbidden runtime service token | `python3 -m tools.check_contracts --check`; `python3 -m unittest discover -s tests/fixtures -v` | Compliant | Amend async contract before queues |
| GCS-DEPLOY-001 | Workflow and env examples | Env vars documented, no unmanaged runtime | Add undocumented `GCS_*` variable | `python3 -m tools.check_contracts --check` | Compliant | Add variable to `ops/local_variables.example` or remove it |
| GCS-DEPLOY-002 | Future Compose paths, ops examples | No active container drift | Add `container_name` or `gcs-redis` | `python3 -m tools.check_contracts --check` | Compliant for Phase 0 | Introduce Compose only under `gcs_project` rules |
| GCS-SEC-001 | Contracts, env examples, future sources | No secrets and source authority rules settled | Commit secret-like env value | `python3 -m tools.check_contracts --check` | Compliant for Phase 0 | Add leak scanning when secrets/runtime exist |
| GCS-TEST-001 | `tools/check_contracts.py`, CI workflow, `tests/raw_store/`, `tests/normalization/`, `tests/fixtures/`, future `tests/persistence/` | Checker enforces Phase 0B paths, Phase 0C inventory, and Phase 0D persistence-only allowance | Validator self-test mutation fails; invalid migration names, SQL, ORM drift outside persistence, queue, container, API, signal, prediction, and live-client samples fail | `python3 -m tools.check_contracts --self-test`; Phase 0B unittest commands; future persistence unittest command | Compliant; Phase 0D implementation-eligible, not started | Expand validator only by approved contract/frame amendment |
| GCS-IMPL-004 | Phase plan | Phase 0 blocks data before store | Start Phase 1 before Phase 0 exit gate | Contract review plus validator | Compliant | Keep phase gate current after implementation starts |
| GCS-IMPL-005 | `contracts/GCS-IMPL-005_Implementation_Sequence.md`; product surface; Phase 0B app/test paths; future Phase 0D persistence paths | Product surface deepening is primary; Phase 0D deferred | Add containers/API/queues/live clients or non-allowlisted `app/` paths before their contracts open | `python3 -m tools.check_contracts --check`; Phase 0B unittest commands; future persistence unittest command | Compliant; product-first next task; Phase 0D deferred | Next work deepens `index.html`/`build/`/`assets/`; resume Phase 0D only when multi-year PIT store is required |

## 2. Phase-0 Verdict

The repository is contract-governed for its current phase. It now includes the
Phase 0B file-backed point-in-time storage skeleton and still has no containers,
APIs, database persistence, migrations, live source clients, analytics, entity
resolution, or async queues. Those surfaces remain blocked until their
governing contracts and gates are amended.

## 3. Phase 0A Verdict

Phase 0A is complete when `python3 -m tools.check_contracts --check` and
`python3 -m tools.check_contracts --self-test` pass with the Phase 0B allowlist
active. The next implementation task is Phase 0B and may create only the paths
named in GCS-IMPL-005.

## 4. Phase 0B Verdict

Phase 0B is complete when the contract checker, checker self-test, raw-store
tests, normalization tests, fixture-boundary tests, and whitespace gate pass.
The implemented skeleton proves:

- Fixed local payload fixture plus source metadata produces one immutable raw
  payload digest.
- The same fixture normalizes to deterministic metadata containing
  `as_of_timestamp`, `fetch_timestamp`, `source_authority_tier`, source
  identifier, and normalization version.
- Missing point-in-time metadata, changed payload under a declared digest,
  future-known timestamp, live-client drift, queue/runtime drift, API drift,
  migration drift, database drift, and container drift are rejected.

Phase 0B opened Phase 0C, a design-only amendment to GCS-DATA-003 and the
checker before any physical database, migration, or persistence package is
introduced. Phase 0C status is recorded below.

## 5. Phase 0C Verdict

Phase 0C is complete when `GCS-DATA-003` names the future physical persistence
inventory and `tools/check_contracts.py` proves that inventory is present while
still blocking database implementation, migrations, SQL files, ORM code,
containers, APIs, queues, workers, schedulers, live source clients, ingestion,
entity resolution, signals, analytics, and prediction.

The implemented Phase 0C design proves:

- Required physical table, column, enum, natural key, idempotency key,
  constraint, and index names are settled for future Phase 0D.
- Migration order, rollback policy, point-in-time query rules, and future
  fixture-backed persistence tests are named.
- Checker self-tests reject missing table inventory, missing deterministic
  constraint naming, migrations, SQL files, ORM/database tokens, queues,
  live clients, and active Compose drift.

The primary workstream after Phase 0C is the **product surface** (study +
instrument). Phase 0D remains eligible but deferred.

## 6. Phase 0D Eligibility Verdict

Phase 0D is implementation-eligible but **deferred**, when `GCS-DATA-003`,
`GCS-TEST-001`, `GCS-IMPL-005`, and `tools/check_contracts.py` open only the
physical persistence surface while keeping every other runtime surface blocked.

The Phase 0D eligibility gate proves:

- Future persistence code may live only under `app/persistence/`.
- Future migration files may live only under `migrations/NNNN_<snake_case>.py`
  and standalone SQL remains blocked.
- Future persistence tests may live only under `tests/persistence/`.
- Database implementation tokens remain blocked outside Phase 0D persistence
  paths.
- API, container, queue, worker, scheduler, live-client, entity-resolution,
  production signal package, analytics, and production prediction surfaces
  remain blocked.

Product surface work under `index.html`, `build/`, and `assets/` does not
require Phase 0D completion. Resume Phase 0D only when multi-year
point-in-time queries beyond fixtures are required. Phase 0D is not complete
until the future persistence implementation and fixture-backed persistence
tests pass. If a database container is required, GCS-DEPLOY-002 must be
amended before introducing Compose or database container files.

## 7. Product Surface Verdict

The product surface is active when:

- `index.html` is an immersive study (not a contract register wall).
- `build/` hosts the flagship interactive instrument with topology, lineage,
  math, and decay-tagged next-move modes.
- Public method links emphasize SYS / SIG / SEC; engineering contracts are
  secondary.
- `conversations/03-product-charter.md` records product-first priority.
- Fixture pedagogy never presents itself as multi-bearing concordance.