fix: make SEC quality gating terminal-safe

docs/fundamentals-deployment.md

@@ -17,7 +17,9 @@ not add OS cron entries: the application scheduler owns both jobs.
   event. A failed validation does not promote partial data.
 - An SEC filing still missing after the short publication-lag window enters
   `sec_filing_gaps`. The daily importer retries it automatically; affected
-  tickers are excluded from actionable setups until a snapshot is recovered.
+  tickers are excluded from actionable setups until a snapshot is recovered or
+  a later valid 10-K/10-Q supersedes the gap. Migration `028` materializes older
+  promoted gaps into this queue once, so setup reads never scan import history.
 
 The systemd service uses one application worker. The import framework also holds
 a PostgreSQL advisory lock per source, so an overlapping manual/scheduled run is
@@ -86,7 +88,8 @@ In Admin → Jobs, wait until no other job is running, then:
 3. Check Admin → System Events. There should be no new import error.
 4. Confirm the next-run times correspond to 02:30 and 04:00 New York time.
 5. Open several ticker pages and confirm the fundamentals panel has populated
-   data and still handles partial/missing issuers cleanly.
+   data and still handles partial/missing issuers cleanly. A ticker held by the
+   quality gate should show **New setups paused** with the specific SEC reason.
 
 ## A5 parity observation window
 
@@ -235,8 +238,13 @@ least several scheduled cycles before A6 removes the legacy providers.
 - Inspect the job runtime, latest `data_import_runs.validation_json`, service
   logs, and Admin → System Events before retrying.
 - `unresolved_filing` is emitted once when a filing enters automatic retry. It
-  does not require a server command. Successful co-registrant recovery and new
-  registrants with no XBRL history are logged without recurring warning events.
+  does not require a server command. If the gap is still current after 14 days,
+  `filing_gap_aged` is emitted once with the CIK, accession, and parser/mapping
+  reason. A later valid 10-K/10-Q retires the gap even when the original SEC
+  accession never becomes usable.
+- Successful co-registrant recovery is logged without a warning. New registrants
+  with no XBRL history are also logged quietly, but their ticker page explains
+  that setups remain paused and that successor shells may need `sec_cik_overrides`.
 - Re-run `sudo -u deploy bash ./deploy/provision_fundamentals.sh --check` for
   binary, clone, permission, disk, or environment failures.
 - The Dolt clone is a reproducible cache and does not need a bespoke backup.