# Ultra-sensitive command-dashboard metadata probe

Use when adding a read-only integration for domains where even live read-only data is too sensitive to expose directly (for example Health/medical systems). This is a gate before any deeper adapter or UI work.

## Core principle

Do not build a live content adapter first. Build a `mock | disabled | local_probe` metadata-only adapter and a safe inventory contract. Treat runtime data as forbidden unless a later, explicit gate creates a dedicated safe-summary API.

## Allowed discovery

- Inspect code, README, runbooks, script names, package files, tests, and schema-only docs.
- Classify source categories structurally: scripts, cron, config, runtime directories, backup markers, report generators, exports, logs, DBs.
- For runtime probes, read only metadata: existence, bounded file count, extension count, size bucket, mtime/freshness, coarse success/failure marker, and status flag.
- Keep local runtime paths out of API output and committed docs.

## Forbidden discovery / adapter inputs

Never read or surface:

- Productive DB rows or count queries unless separately approved by a safe-summary design.
- PDFs, OCR outputs, reports, report summaries, chart data, tracker exports, raw JSON/CSV, logs, Drive docs/links/IDs.
- Medical values, diagnoses, medications, symptoms, findings, patient/clinician details, filenames with patient context, local paths.

## Contract shape

Keep the existing `ModuleSnapshot` contract. Allow at most three safe KPIs such as:

- Pipeline freshness: `fresh | stale | unknown`.
- Backup freshness: `fresh | stale | unknown`.
- Review count: bounded integer, count only.
- Source reachable: `yes | no | unknown`.

Allowed attention items are generic: pipeline stale, review required, backup stale, source offline. No source labels, filenames, dates from records, or medical terms.

## Safe status marker bridge pattern

When the next gate is safer than even metadata probing, add a dedicated status-marker adapter instead of widening `local_probe`:

1. Keep default adapter mode as `mock`; add explicit opt-in mode such as `safe_marker` plus a runtime-only marker path env var and max-age env var.
2. Define a strict JSON Schema with `additionalProperties: false`, no freetext fields, no dynamic keys, no nested raw objects, bounded counts, and enums for every status category.
3. Implement fail-closed behavior: missing path, unreadable marker, broken JSON, schema violation, forbidden terms, path/filename leak, or old marker all produce a degraded/offline `ModuleSnapshot`; overview endpoints must not crash.
4. Map only approved enum/count fields into at most three KPIs and enum-derived attention items. Never emit marker path, filename, runtime path, source document metadata, or domain content.
5. Add a producer handoff doc for the source system: allowed fields, forbidden inputs, schema link, synthetic example, and atomic write protocol (`.tmp` sibling then rename). Do not modify the source system in this gate unless explicitly approved.
6. Add synthetic valid/invalid fixtures, redaction tests, overview resilience tests, and an optional smoke that creates its own temporary synthetic marker under ignored `.tmp/`. Keep smoke outside fast `make verify`.
7. Regenerate contract schemas/OpenAPI if Pydantic contracts changed, and update frontend source-type unions minimally if the UI displays source type.

## Tests to add

- Inventory matrix/categories are documented: `allowed_metadata_only`, `future_gate_required`, `blocked`, `forbidden`.
- Future-gated and forbidden sources are not used by the adapter.
- `local_probe` does not call content readers (`read_text`, `open`, JSON/CSV parsers, sqlite, PDF tooling) for runtime data.
- For safe-marker bridges: valid fresh marker creates a safe snapshot; stale marker creates attention; degraded marker remains contract-conform; unknown fields, freetext, paths, and dirty domain terms are rejected/redacted; marker path/name never appears in output; broken/missing/old marker fails closed.
- API output contains no forbidden domain strings, paths, filenames, raw errors, or detail links.
- Dirty synthetic fixtures with forbidden terms are fully blocked.
- Fast `make verify` works without runtime data; optional local/safe-marker smoke remains outside CI/verify.

## CI / safety pitfalls

- Add targeted repo-safety allowlist entries only for sanitizer files, dirty fixtures, and tests that intentionally contain forbidden synthetic terms. Never allowlist whole directories.
- Remove `.tmp`, build output, Playwright artifacts, logs, screenshots, runtime files, and raw data before committing.
- If CI status APIs return 403, report that Actions/Checks read permission is missing; do not claim the workflow is green from local checks alone.