# Curated Enrichment And Admin Source Management Direction

Issue: #235

Status: design direction only. This document does not change runtime behavior, source enablement, Cloudflare configuration, provider configuration, or package authority.

## Purpose

Capture the long-term product direction for a governed knowledge package that remains package-first while allowing tightly curated current/public sources to enrich, compare, verify, challenge, and propose human-approved updates to the canonical playbook.

This note preserves the intended product shape so later work does not collapse the design into generic browsing, generic RAG, model-memory answers, or silent authority mutation.

## Product Thesis

The durable product is the governed knowledge package: authored source, provenance, receipts, validation, generated artifacts, and explicit source boundaries.

The assistant is an interpretation surface over that package. Current/public sources can add useful external context, but they do not become package authority unless a human-reviewed package update moves through issue, PR, validation, receipt, and release discipline.

## Current State

- Package-only mode remains the default.
- Package-only answers must use approved package material or refuse.
- Package + current context is explicit and opt-in.
- Persistent current/public retrieval is enabled for NIST AI RMF only.
- Expanded authoritative candidates exist as candidate-only review evidence.
- Expanded current/public source catalog entries exist as candidate-only governance evidence.
- Candidate entries remain `approval_status: "candidate_only"` and `retrieval_enabled: false`.
- Current/public citations remain distinct from package citations.
- Current/public sources are context, not approved package authority.
- Runtime source enablement is deployment configuration, not repository-side source text.

## Target Pattern

The target pattern has four answer lanes:

1. `Package says`
2. `Current/public source says`
3. `Synthesis / implications`
4. `Divergence / update candidate`

The package lane remains canonical. The current/public lane is allowed only from reviewed and allowlisted sources. The synthesis lane explains implications without merging authority. The divergence lane names gaps or conflicts and can create update candidates, but it cannot rewrite package authority.

## Package Authority Lane

The package authority lane answers from the approved package only.

It must:

- cite approved package sources
- preserve source family, source quality, claim boundary, and reader target metadata
- refuse when approved package support is absent
- keep model memory out of source authority
- avoid treating current/public sources as package evidence
- avoid treating generated summaries as source evidence

It must not:

- browse
- retrieve arbitrary URLs
- use user-provided URLs
- use private files
- treat model memory as evidence
- approve tools, data classes, workflows, production use, providers, or models

## Current/Public Enrichment Lane

The current/public enrichment lane supplies separately cited context from reviewed and allowlisted public sources.

It must:

- run only after approved package support exists
- use server-side retrieval only
- use only owner-reviewed, narrow-origin, narrow-path sources
- keep current/public citations visually and semantically separate from package citations
- label trust, freshness, source type, and claim boundary
- preserve `not_package_authority` boundaries
- remain explicitly opt-in from the user-facing mode

It must not:

- enable generic web search
- fetch from browser-side JavaScript
- accept arbitrary user URLs
- retrieve from wildcard domains
- retrieve from private or internal hosts
- turn current/public source text into approved package authority

## Synthesis Lane

The synthesis lane explains how package guidance and current/public context relate.

It should use this structure:

- `Package says`: the approved package position, with package citations.
- `Current/public source says`: the external source position, with current/public citations.
- `Synthesis / implications`: bounded interpretation that names alignment, implications, and caveats.
- `Divergence / update candidate`: gaps, conflicts, outdated package material, or candidate changes.

Synthesis must not collapse the source lanes. When the package and current/public source both support a conclusion, the answer should still identify which lane provides which evidence.

## Divergence And Update-Candidate Lane

Divergence handling is a product feature, not a defect.

When package guidance and current/public source guidance differ, the assistant should:

- state the divergence explicitly
- cite the package lane separately
- cite the current/public lane separately
- explain whether the divergence is a gap, stale package guidance, source-scope mismatch, stronger external framing, or unresolved conflict
- avoid choosing a winner unless the approved package or owner validation provides a decision rule
- propose a human-reviewed update candidate when appropriate

Update candidates can include:

- new package wording
- changed claim boundaries
- new glossary entries
- new validation receipt needs
- new source review needs
- deprecated or stale guidance markers
- stronger source-quality or owner-validation labels

Update candidates must not silently mutate the package.

## Source Tiering Model

| Tier | Examples | Intended use |
| --- | --- | --- |
| Authoritative official | NIST, CISA, regulators, standards bodies | Strong current/public evidence |
| Regulated life sciences / GxP / medical device authority | FDA, EU/EMA/EudraLex, ICH, official standards metadata, PIC/S, WHO, ISPE public metadata | High-consequence regulated context only after exact source verification and owner review |
| Security / engineering frameworks | OWASP, MITRE ATLAS, CNCF, SEI, mature engineering bodies | Strong practice/risk context |
| Vendor factual documentation | OpenAI, Cloudflare, Microsoft, Anthropic, AWS, Google | Platform-specific facts only |
| Signal / discovery sources | YouTube, Reddit, Substack, blogs, forums | Discovery/watchlist only, not answer authority unless promoted |

Tiering is not approval. A source still needs exact URL review, owner approval, allowed origin and path constraints, freshness posture, and source-lane labeling before use in Package + current context.

## Expanded Source Catalog Relationship

Issue #244 adds the expanded current/public source catalog as the source-class and approval-matrix layer for future admin-source-management work.

The catalog should become the admin model for:

- source class/type
- claim boundary
- citation boundary and citation label
- allowed use
- source owner
- approver placeholder or approved approver
- review cadence
- verification status
- enablement status
- rollback metadata
- source-watch and update-candidate relationship

Catalog inclusion does not mean runtime enablement.

Current/public source inclusion does not mean package authority.

No admin workflow should silently promote current/public source material into package authority. A package update still requires issue, branch, PR, validation, receipt, and release discipline.

## Source Watch/Refresh Loop

Future refresh loops may monitor curated sources for changes.

A safe watch loop should:

- monitor only curated sources or discovery watchlists approved for monitoring
- record source URL, retrieval timestamp, observed change, and freshness signal
- avoid using signal/discovery sources as answer authority
- generate candidate issues or review packets instead of changing package text
- identify whether a change affects package claims, examples, definitions, validation, or receipts
- keep source-watch artifacts separate from package authority

The watch loop should not add durable telemetry, database, vector store, Supabase, uploads, or session attachments until those surfaces have separate approved architecture.

## Human-Approved Playbook Update Loop

Current/public enrichment can reveal that the canonical package should change.

The update loop should be:

1. Current/public source or watch loop identifies a gap, change, or divergence.
2. The assistant or operator creates an update candidate with separate package and external citations.
3. A human owner reviews whether the candidate belongs in the package.
4. Approved changes move through issue, branch, PR, validation, receipt, and release discipline.
5. The context pack and published mirrors are regenerated.
6. Receipts record what changed, why, and which source lane supported the change.

No runtime path may rewrite package authority directly.

## Future Admin Panel

The future admin panel is an operator surface for governed source and configuration management. It exists because long-term source operations should not require every common action to happen through Codex, Git, or an IDE.

The admin panel should help administrators manage:

- source registry entries
- source class/type
- source claim boundary
- source citation boundary and citation label
- source allowed use
- source approval status
- source enable/disable state
- source priority
- source type, trust, and freshness labels
- allowed origin and path constraints
- review due dates
- source owner and approver metadata
- verification status
- rollback metadata
- source watch/update-candidate relationships
- current-source smoke status
- rollback controls or rollback instructions
- package/current synthesis settings
- safe model/provider display settings
- telemetry and receipt visibility settings
- candidate update queue
- human approval workflow links

The admin panel should generate controlled configuration changes, issues, PRs, receipts, or approved deployment actions. It must not mutate source authority silently.

## Admin Panel Non-Goals

The admin panel must not:

- expose secret values
- bypass owner approval
- bypass issue/PR/review/validation/receipt gates
- promote current/public sources into package authority
- allow arbitrary web search as answer authority
- allow user-provided URL retrieval as answer authority
- directly change Cloudflare Access or WAF
- directly change provider/model secrets or unsafe provider settings
- create durable telemetry, database, vector store, Supabase, uploads, or session attachments without separate approval
- hide divergence or source-lane boundaries from users

## Governance Invariants

- Package-only remains default.
- Package-only answers from approved package sources or refuses.
- Package + current context remains explicit.
- Current/public sources are separately cited context.
- Current/public sources do not become approved package authority.
- NIST AI RMF remains the only enabled current/public source until another source is separately approved and configured.
- Expanded candidates remain candidate-only until a future issue changes their status.
- Regulated life sciences / GxP / medical device candidates remain candidate-only until exact public/legal source access, source scope, owner approval, and production smoke are separately approved.
- Paywalled or incorporated-by-reference standards remain metadata-only unless legally available public text is verified.
- Cloudflare env/config changes remain out of repo and require separate approval.
- Cloudflare Access/WAF changes require separate approval.
- Provider/model secrets and config require separate approval.
- No source lane may expose secrets.
- No source lane may silently mutate package authority.

## Sequencing Roadmap

1. Package + current synthesis v01.
2. Expanded authoritative source enablement one source at a time.
3. Divergence detection and update-candidate output.
4. Human-approved playbook refresh workflow.
5. Source-watch loop.
6. Admin panel design.
7. Admin panel implementation.

Each step should have its own issue, branch, validation receipt, and explicit non-goals.

## Open Questions

- What answer format should Package + current synthesis use before full provider synthesis is enabled for current context?
- Who is the named approver for each source tier?
- What freshness signal is enough to require a human review?
- Which source-watch artifacts are safe to publish?
- Which admin panel actions should generate PRs versus deployment tasks?
- What minimum audit receipt is required for an admin-triggered source enablement?
- Which model/provider metadata is safe to display without exposing secrets or implying approval?
- How should divergence candidates be prioritized against existing backlog work?

## Explicit Non-Goals

This design note does not:

- change runtime behavior
- enable or disable any source
- change Cloudflare env/config
- change Cloudflare Access/WAF
- change provider/model secrets or provider/model config
- add arbitrary web search
- add browser-side current-source fetches
- add user-provided URL retrieval
- add durable telemetry, database, vector store, Supabase, uploads, or session attachments
- expose secrets
- promote current/public sources into approved package authority
- authorize `codex-automerge`
- start admin panel implementation