# GCS-IMPL-004 — Implementation Plan

**Document class:** Implementation & delivery plan
**Spec ID:** GCS-IMPL-004
**Version:** v1.0
**Status:** Settled
**Owner:** Phil
**Approver:** Phil
**Settled:** 2026-07-08
**Parent:** GCS-SYS-001
**Related:** GCS-REGISTER-001, GCS-DATA-002, GCS-DATA-003, GCS-SIG-003, GCS-TEST-001

---

## 0. How to read this

Seven phases, each with objective, concrete build steps, the specific public endpoints, deliverables, and an exit gate. Phases are sequenced so the make-or-break layer (entity resolution) is proven before analytics are built on it. Every output is demonstrated from the public record per the demonstration standard (GCS-SYS-001 §5); every phase inherits the acceptance criteria of its parent contract.

Ordering principle: **prove the spine before the muscle.** Historical (past) reconstruction is built first because present and short-term-future both depend on it and on the point-in-time store.

---

## Phase 0 — Foundation & scaffolding

**Objective:** repo, storage, and the point-in-time discipline that everything else depends on.

**Steps:**
1. Stand up storage with two layers: **raw store** (immutable, as-received filings/API responses with fetch-timestamp) and **normalized store** (re-runnable from raw). Postgres for normalized/relational + object storage for raw payloads is sufficient; add a graph store (or graph layer over Postgres) for the entity graph.
2. Enforce **as-of stamping** on every record at ingestion (GCS-DATA-002 §6). This is non-negotiable and must exist before any data lands — retrofitting point-in-time is the classic backtest-invalidating mistake.
3. Ingestion framework: idempotent, incremental, per-source scheduler keyed to each source's native clock.
4. Reconciliation harness skeleton (Tier 2 → Tier 1).

**Deliverable:** empty but correct pipeline with point-in-time guarantees.
**Exit gate:** a test filing round-trips raw→normalized with correct as-of stamp and no duplication on re-pull.

---

## Phase 1 — Monetary & fiscal input layer (fast input clock) — PAST + PRESENT

**Objective:** ingest the "money is printed and travels" clock. This is the cleanest data and validates the pipeline.

**Steps:**
1. **FRED API** — pull historical + ongoing: Fed balance sheet (WALCL / H.4.1 components), TGA (WTREGEN), reverse repo (RRPONTSYD), M2 (M2SL), effective rate. FRED is well-documented and stable; start here.
2. **US Treasury Fiscal Data API** — Daily Treasury Statement (outlays, TGA operating cash) at daily grain.
3. **TreasuryDirect** — auction results/settlement dates.
4. **FOMC calendar + statements** — meeting dates and decision timestamps for later high-frequency IV work (GCS-SIG-003 §3.3).
5. Normalize all to a common time axis; store with as-of stamps.

**Public endpoints:** FRED (`api.stlouisfed.org`), Treasury Fiscal Data (`api.fiscaldata.treasury.gov`), TreasuryDirect.
**Deliverable:** complete historical monetary/fiscal input series, queryable, point-in-time.
**Exit gate:** reconstruct the aggregate-balance-sheet and TGA-drawdown series historically; spot-check against published Fed figures.

---

## Phase 2 — Expenditure / capability layer (fast input clock) — PAST + PRESENT

**Objective:** money hitting named recipients — the FIC/MIC/TIC seam's disbursement side.

**Steps:**
1. **USASpending.gov API** — historical + ongoing federal contract obligations and assistance, by recipient (UEI/recipient ID), agency, NAICS, obligation date. This is the stream that ties Treasury outflow to named MIC primes and chip programs.
2. Capture recipient identifiers for the crosswalk (Phase 3): UEI, recipient name, parent.
3. Tag defense/tech-relevant NAICS (aircraft, guided-missile, semiconductor) for sector rollups.

**Public endpoint:** USASpending (`api.usaspending.gov`).
**Deliverable:** historical disbursement series by recipient and sector, point-in-time.
**Exit gate:** reproduce known annual DoD-obligation totals to the top primes; recipients carry stable IDs for crosswalk.

---

## Phase 3 — Entity-resolution graph (THE MAKE-OR-BREAK LAYER) — PAST + PRESENT

**Objective:** bind every stream to one entity model so a dollar is followable across complexes. ~80% of total effort concentrates here; do not shortcut it.

**Steps:**
1. **Identifier crosswalk** (GCS-DATA-002 §4.3): build the CIK ↔ ticker ↔ CUSIP ↔ LEI ↔ USASpending-UEI table. Seed from SEC's company tickers file and LEI reference data; extend with USASpending recipient records.
2. **Effective-dated corporate events:** encode mergers, renames, re-tickers with effective dates (Raytheon→RTX, Lockheed pension-trust structure, etc.). Every downstream join is effective-dated.
3. **Node/edge model** (GCS-DATA-002 §4.1–4.2): issuers, filers, funds, recipients, ultimate parents, sectors, government nodes; edges holds/votes/manages/sub-advises/disburses/is-parent-of/gates.
4. **Sector classification:** assign each issuer to FIC/MIC/TIC + sub-sector.
5. **The independence audit engine** (GCS-DATA-002 §4.4): resolve manages/sub-advises and fund-family/feeder edges so a sub-advised fund and its advisor collapse to one bearing. Output independence-adjusted holder sets.

**Deliverable:** the entity graph, with the independence audit runnable.
**Exit gate:** for a test issuer (e.g., a named prime), the graph correctly (a) resolves its ultimate parent, (b) lists holders with effective-dated stakes, (c) collapses a known sub-advisory relationship into a single bearing, (d) links its government disbursement edges. This gate proves the spine; do not proceed to analytics until it passes.

---

## Phase 4 — Corporate behavior + ownership layers — PAST + PRESENT

**Objective:** positions and fast behavioral signals, bound to the graph.

**Steps:**
1. **SEC EDGAR full-text + submissions API** — historical + ongoing pull of:
   - **13F** (holdings; full roster per issuer for concentration math),
   - **13D/13G** (5% crossings; tag control-intent vs. passive),
   - **Form 4** (insider transactions, ≤2-day latency),
   - **8-K** (material events; retain for engagement-window signatures in Phase 6).
2. Join every holding/transaction to the entity graph via CIK; compute per-issuer holder rosters.
3. Run the independence audit → produce **independence-adjusted bloc / dispersed tail / inert retail** per issuer (GCS-SIG-003 §2.1). This computes the number that adjudicates the concentration-vs-dispersion question.
4. Compute **common-ownership overlap** across FIC/MIC/TIC (GCS-SIG-003 §2.2).

**Public endpoint:** SEC EDGAR (`data.sec.gov`, `efts.sec.gov`) under fair-access rate limits.
**Deliverable:** historical ownership topology with independence-adjusted concentration and cross-complex overlap, point-in-time.
**Exit gate:** independently reproduce top-holder percentages for several named issuers across all three complexes and show the adjusted bloc vs. tail split.

---

## Phase 5 — Governance layer (THE DECISIVE LAYER) — PAST + PRESENT

**Objective:** the vote machinery — ballots, proposals, and how funds actually voted.

**Steps:**
1. **DEF 14A ingestion** — parse proxy statements for: director slate, shareholder proposals, comp items, **record dates**, meeting dates, and vote standard (plurality vs. majority) where stated.
2. **Shareholder proposal lifecycle** — track filed → withdrawn (DEFA14A / correspondence) → voted. Withdrawals are Phase-6 engagement signatures.
3. **Form N-PX ingestion (priority)** — normalize to `(fund, proposal, vote)` tuples; join to DEF 14A ballot items via the entity graph. This is the stream that makes "how the giants vote" a query.
4. **Vote outcomes** — capture resolved results from post-meeting 8-K / follow-ups.
5. **Proxy advisor policies** — ingest published ISS / Glass Lewis benchmark policy docs (Tier 2) to model the recommendation logic the dispersed tail follows.
6. Compute per-issuer: aligned-bloc voting behavior, with-vs-against-management rates, advisor-recommendation-vs-tail-vote correlation.

**Public endpoints:** SEC EDGAR (DEF 14A, DEFA14A, N-PX); ISS/Glass Lewis published policy documents.
**Deliverable:** historical governance record — every ballot, every fund vote, every outcome — bound to the graph, point-in-time.
**Exit gate:** for a completed proxy season, reconstruct the full ballot and the actual fund-by-fund vote for several issuers, and compute the advisor-vs-tail correlation.

---

## Phase 6 — Analytics: flow causality + engagement-channel inference — PAST→PRESENT understanding

**Objective:** turn the assembled record into causal flow signal and an estimate of the invisible engagement lever.

**Steps:**
1. **Baseline governance model** (GCS-SIG-003 §4.2) — build the natural-flow pattern (severity→opposition→outcome; advisor→tail) from the mass of ordinary cases. Foundation for everything in this phase.
2. **Engagement-channel signatures** (GCS-SIG-003 §4.3) — implement the four anti-pattern detectors as queries over the N-PX/proposal/8-K timing data: pre-emptive non-conflict (residual), window-clustered concessions, withdrawn proposals, engaged-vs-unengaged divergence.
3. **Deconvolution** (GCS-SIG-003 §4.1) — estimate true sentiment independently; solve for the engagement transfer function; produce quantified channel-effect estimates with reflexivity discount.
4. **Disaggregation rule** (GCS-SIG-003 §4.5) — split "voted with management" into acquiescence vs. pre-conceded win against the baseline.
5. **Flow causality** (GCS-SIG-003 §3) — implement, in priority order: high-frequency IV identification around FOMC windows; local projections / SVAR for shock→positioning impulse responses; HMM regime layer over the input→positioning coupling; Granger/transfer-entropy for edge screening; CCM/FCI for the common-cause discrimination, treating clean results skeptically.

**Deliverable:** quantified redistribution vectors (value/capability/control) + quantified engagement-channel estimate, each under concordance, each demonstrated from primary records per the demonstration standard.
**Exit gate:** the engagement channel is represented as an explicit modeled unknown with quantified effect and reflexivity decay; concentration and redistribution features each cite ≥2 independent bearings.

---

## Phase 7 — Prediction + validation (short-term FUTURE)

**Objective:** bounded, perishable, validated short-term forecasts.

**Steps:**
1. **Prediction targets** (GCS-SIG-003 §6): governance-event forecasts (opposition level / proposal outcome for upcoming meetings from record-date + filing + ISS policy + adjusted bloc); flow-rotation forecasts (sector positioning within lag L from issuance/disbursement + regime state); engagement-likelihood forecasts (probability an issue resolves off-record).
2. **Validation harness** (GCS-SIG-003 §7): mandatory out-of-sample on held-out time using point-in-time data only; in-sample-only signals rejected; reflexivity/decay monitoring; confound holdout via high-frequency IV.
3. **Output packaging:** every prediction ships CI + decay clause + regime tag.

**Deliverable:** short-term prediction service with an auditable out-of-sample track record.
**Exit gate:** predictions demonstrate out-of-sample skill on held-out time; any signal surviving only in-sample is removed; every prediction is traceable to point-in-time records and shipped with its uncertainty.

---

## Cross-cutting: review & compliance (every phase)

- **Demonstration review** (GCS-SYS-001 §5) on every analytical output — automated check + human sign-off. Reject anything not traceable to primary records, or that manufactures the content of an off-record deliberation rather than quantifying its effect.
- **Source-authority discipline** (GCS-DATA-002 §3) — every asserted number traces to Tier 1; aggregators flagged provisional; conspiracy/fabricated sources excluded outright.
- **Lawful-data discipline** (GCS-SYS-001 §7) — public data only; no leaked/hacked/scraped-in-violation sources; no personal surveillance.
- **Independence audit** run before any concordance claim.

---

## Sequencing summary

| Phase | Layer | Time-face | Depends on |
|---|---|---|---|
| 0 | Foundation / point-in-time | — | — |
| 1 | Monetary/fiscal input | Past+Present | 0 |
| 2 | Expenditure/capability | Past+Present | 0 |
| 3 | **Entity graph (spine)** | Past+Present | 1,2 |
| 4 | Behavior + ownership | Past+Present | 3 |
| 5 | **Governance (decisive)** | Past+Present | 3,4 |
| 6 | Causality + engagement inference | Past→Present | 4,5 |
| 7 | Prediction + validation | Short-term Future | 6 |

The spine (Phase 3) gates the muscle. The decisive layer (Phase 5) and the engagement inference (Phase 6) are where the real finding lives. Prediction (Phase 7) is deliberately last and deliberately bounded.

## Phase -1 - Contract Governance Gate

Before Phase 0 implementation work begins, the repository must satisfy the
contract stack:

- GCS-REGISTER-001 lists every contract artifact.
- GCS-NAME-001 and GCS-NAME-002 govern naming and vocabulary.
- GCS-STACK-001 defines allowed folders and runtime boundaries.
- GCS-RUNTIME-001 explicitly forbids queues in the current phase.
- GCS-DEPLOY-001 and GCS-DEPLOY-002 govern runtime/container absence and future names.
- GCS-TEST-001 defines the executable gates.

Positive verification: `python3 -m tools.check_contracts --check` passes.

Negative verification: adding an app, API, migration, queue, container, or
undocumented env var without the matching contract amendment fails the gate.

---

*End GCS-IMPL-004.*