# Source Registry Admin Product Requirements V01

Issue: [#325](https://github.com/pinklon/ai-capability-discipline/issues/325)

Date: 2026-06-27

Repository: `pinklon/ai-capability-discipline`

Baseline commit: `f9e2e72a7a22b341fa2dbb5b1f964a967fdab7fb`

Status: product requirements and architecture definition only. This artifact does not implement the admin layer, mutate source registries, enable sources, disable sources, retire sources, promote sources, create Source Registry Admin child implementation issues, create extraction-profile implementation tickets, start #271, change runtime behavior, change package authority, use Cloudflare CLI or API, start Production apply, start OKF implementation, start Google SDLC implementation, start multi-agent orchestration implementation, or authorize `codex-automerge`.

## Purpose

Define Source Registry Admin as the governed source lifecycle administration capability for enrichment lanes.

The corrected product requirement is broader than steady-state administration for already-approved sources. Source Registry Admin must become the controlled administrative path for adding, approving, registering, documenting, enabling, disabling, retiring, and promoting enrichment sources while preserving source metadata, approval evidence, retrieval and extraction boundaries, environment eligibility, citation behavior, receipts, source history, and audit trail.

This artifact supersedes #269 as the product-requirements anchor for Source Registry Admin while preserving #269 as a closed completed planning/backlog artifact.

## Owner Decision

Tony clarified that Source Registry Admin is not only for already-approved sources.

Corrected product intent: Source Registry Admin should become the governed administrative path for adding, approving, registering, documenting, enabling, disabling, retiring, and promoting enrichment sources.

Adding a new source through this admin path means the source is approved through the governed workflow and recorded with source metadata, approval evidence, retrieval/extraction boundaries, environment eligibility, and citation/use documentation.

The workflow must remain controlled and bounded. It must not become arbitrary web search, user-provided URL retrieval, broad crawling, browser-side source fetch, or package-authority promotion.

## Product Definition

Source Registry Admin governs source lifecycle, approval, registration, activation, deactivation, retirement, promotion, rollback, and receipts for enrichment sources.

It must support:

1. Add/register new source.
2. Record approval.
3. Validate source metadata and boundaries.
4. Assign source authority lane.
5. Assign retrieval/extraction profile.
6. Enable source in Preview.
7. Disable source in Preview.
8. Promote eligible source to Production.
9. Disable source in Production.
10. Retire source.
11. Emergency disable source.
12. Roll back to last-known-good registry.
13. Generate receipts.
14. Document source use when the assistant calls upon it.
15. Preserve source history and audit trail.

Source Registry Admin is the control plane for the source lifecycle. It does not decide package authority, rewrite approved package content, perform arbitrary web retrieval, run broad crawls, or grant runtime mutation authority from this product-requirements ticket.

Current/public enrichment authority is the default lane for externally approved enrichment sources unless a separate owner-approved package-authority process grants a source different status.

## Non-Goals

This product-requirements ticket does not:

- implement Source Registry Admin commands
- create Source Registry Admin child implementation issues
- create extraction-profile implementation tickets
- start #271
- reopen #269
- close #269
- close #271
- mutate source registries
- enable, disable, retire, or promote any source
- use Cloudflare CLI or API
- change runtime behavior
- change package authority
- start Production apply
- start OKF implementation
- start Google SDLC implementation
- start multi-agent orchestration implementation
- approve browser-side source fetch
- approve browser-side provider calls
- approve browser-side current-source calls
- approve arbitrary web search
- approve user-provided URL retrieval outside the governed source-add workflow
- approve broad crawling
- approve wildcard origins
- approve undocumented source usage
- apply `codex-automerge`

## Relationship To #269

#269 remains closed as the original completed planning/backlog artifact.

This issue supersedes #269 as the product-requirements anchor for Source Registry Admin.

Do not reopen #269.

Do not close #269.

Historical #269 artifacts remain useful as prior Source Registry Admin architecture and implementation-slice evidence. They do not override the corrected owner decision captured here.

## Relationship To #271

#271 remains open and separate.

#271 extraction profiles define whether approved sources can produce substantive bounded cited content.

Source Registry Admin can register and approve sources, but a source should not become substantively useful for detailed enrichment until its retrieval/extraction profile passes validation.

#271 may be implemented before or in parallel with Source Registry Admin implementation slices. This product-requirements ticket does not start #271, does not create extraction-profile implementation tickets, and does not authorize substantive extraction behavior.

## Related References

- Refs #269
- Refs #271
- Refs #324
- Refs #323
- Refs #321
- Refs #320
- Refs #317
- Refs #316
- Refs #314
- Refs #310
- Refs #308
- Refs #306
- Refs #304

## Source Lifecycle Model

The lifecycle model must preserve these concepts:

- a source can be known but not active
- a source can be approved but not enabled
- a source can be enabled in Preview but not Production
- a source can be disabled without erasing history
- a source can be retired without deleting audit records

Minimum lifecycle states:

| State | Meaning | Activation boundary |
| --- | --- | --- |
| `proposed` | Source has been identified for possible governed addition. | Not approved and not active. |
| `approved` | Source passed owner or steward approval for a defined authority lane and use boundary. | Approved but not enabled. |
| `registered` | Source has required metadata, approval evidence, retrieval/extraction boundaries, citation fields, and receipt references in the governed source record. | Known and governed, but not automatically active. |
| `preview_enabled` | Source is active in Preview for bounded smoke and validation. | Preview only. |
| `production_eligible` | Source has passed required Preview evidence, metadata validation, retrieval/extraction validation, receipt checks, and environment eligibility review. | Eligible for Production, but not active in Production. |
| `production_enabled` | Source is active in Production under explicit environment eligibility, validation evidence, and receipt-backed promotion. | Production active. |
| `disabled` | Source is inactive in one or more environments while source history, approval evidence, and receipts remain preserved. | Disabled without deleting audit history. |
| `retired` | Source is no longer eligible for normal activation, but source records, history, and audit trail remain preserved. | Retired without deleting audit records. |

State transitions must be receipt-backed. A source must not skip from `proposed` to active runtime use without approval capture, registration, validation, environment eligibility, and receipt generation.

## Source Record Schema

Minimum required source metadata:

| Field | Required purpose |
| --- | --- |
| `source_id` | Stable source identifier used in registries, receipts, citations, and audit history. |
| `source_name` | Human-readable source name. |
| `source_version` or `publication_date` | Version or publication marker when available. |
| `source_type` | Source class, such as public standard, vendor documentation, government guidance, framework, or other approved class. |
| `authority_lane` | Authority lane, with current/public enrichment authority as the default lane for externally approved enrichment sources. |
| `canonical_url` or `document_location` | Canonical source location. |
| `allowed_origin` | Exact allowed origin. Wildcards are forbidden. |
| `allowed_path_prefix` | Exact allowed path prefix or document location boundary. |
| `retrieval_profile_id` | Retrieval profile that defines how bounded retrieval may occur. |
| `extraction_profile_id` | Extraction profile when different from retrieval profile or required for substantive bounded cited content. |
| `environment_eligibility` | Preview and Production eligibility markers and prerequisites. |
| `approval_status` | Approval status, including proposed, approved, rejected, disabled, or retired as applicable. |
| `approved_by` | Owner, steward, or approval role. |
| `approved_at` | Approval timestamp. |
| `approval_rationale` | Evidence-backed reason for approval and allowed use. |
| `source_owner` or `steward` | Accountable source steward. |
| `citation_label` | Human-readable citation label used in answers. |
| `citation_url` | Citation URL or document reference. |
| `last_validated_at` | Most recent validation timestamp. |
| `validation_status` | Validation result and state. |
| `active_environments` | Environments where the source is currently active. |
| `disable_reason` | Reason for disablement when applicable. |
| `retired_at` | Retirement timestamp when applicable. |
| `receipt_refs` | Receipt references for approval, validation, activation, disablement, rollback, retirement, and source-use documentation. |

The schema must preserve source history and audit trail. A source deletion that erases audit history is forbidden.

## Administrative Actions

Required admin actions:

| Action | Required behavior | Mutation boundary |
| --- | --- | --- |
| `add_source` | Create a proposed source record through the governed source-add workflow. | Does not activate the source. |
| `approve_source` | Record approval status, approver, approval rationale, allowed use, authority lane, and environment eligibility. | Does not activate the source. |
| `register_source` | Record complete source metadata, approval evidence, boundaries, profile IDs, citation fields, and receipt references. | Does not activate the source. |
| `validate_source` | Validate source metadata, allowed origin, allowed path prefix, environment eligibility, retrieval profile, extraction profile, and citation fields. | Validation only unless a later authorized action uses it. |
| `enable_preview` | Enable a registered and validated source in Preview with receipt generation and smoke evidence. | Preview only. |
| `disable_preview` | Disable a source in Preview without deleting audit history. | Preview only. |
| `mark_production_eligible` | Record that a source has met Production eligibility prerequisites. | Does not activate Production. |
| `promote_to_production` | Promote an eligible source to Production with explicit environment eligibility, validation, receipt generation, smoke, and rollback readiness. | Production only after explicit authorization. |
| `disable_production` | Disable a source in Production without deleting audit history. | Production only after explicit authorization or emergency criteria. |
| `emergency_disable` | Rapidly disable a source in Preview or Production, record trigger, environment, source ID, operator, rollback posture, and follow-up evidence. | Restricted emergency path. |
| `rollback_registry` | Restore last-known-good registry for a target environment and generate a rollback receipt. | Environment-scoped. |
| `retire_source` | Mark a source retired while preserving metadata, receipts, and audit records. | No deletion of audit history. |
| `list_sources` | List governed source records and lifecycle states. | Read-only. |
| `list_active_sources` | List active source IDs by environment. | Read-only. |
| `show_source_detail` | Show source metadata, approval evidence, boundaries, profiles, citation fields, environment status, and receipts. | Read-only. |
| `generate_receipt` | Generate receipt for an admin action, refusal, validation run, activation, disablement, rollback, or source-use event. | Receipt-only unless paired with authorized action. |
| `run_source_smoke` | Run bounded source smoke for metadata, retrieval/extraction profile, citation lane, and browser/provider boundary checks. | Smoke-only. |

Every apply-capable action must support dry-run output before mutation. This product-requirements ticket authorizes no apply-capable action.

## Environment Behavior

Environment behavior must be explicit and receipt-backed:

- A source can be registered without being active in any environment.
- Preview enablement does not imply Production enablement.
- Production activation requires explicit environment eligibility and validation.
- Production activation without explicit environment eligibility and validation is forbidden.
- Source activation without receipt generation is forbidden.
- Disablement must preserve source history, previous active state, reason, timestamp, and receipt references.
- Retirement must preserve audit records and must not delete source history.
- Rollback must restore the last-known-good registry for the target environment and generate a receipt.
- Emergency disable must record source ID, environment, trigger, operator or role, prior state, new state, and follow-up requirement.

Runtime/source mutation is not authorized by this product-requirements ticket.

## Approval Model

Source approval is captured inside the admin workflow when a source is added.

Approval must record:

- source identity
- source type
- authority lane
- approval status
- approver
- approval timestamp
- approval rationale
- source owner or steward
- allowed origin
- allowed path prefix
- allowed use
- excluded use
- retrieval profile
- extraction profile when required
- environment eligibility
- citation label
- citation URL
- receipt references

Approval does not grant package authority. Package authority is a separate approval process.

Approval does not automatically activate a source. Activation requires separate environment-scoped validation and receipts.

Candidate-only source activation is forbidden.

## Documentation And Citation Behavior

When the assistant calls upon a source, source-grounded answers must document:

- source ID
- source name
- authority lane
- whether each claim is package-grounded or current/public enrichment-grounded
- citation reference
- retrieval/extraction profile used
- timestamp or version marker where available
- refusal behavior when retrieved text is insufficient

No source use without citation/use documentation is allowed.

Undocumented source usage is forbidden.

If retrieved text is insufficient for a requested claim, the assistant must refuse, narrow the answer to supported statements, or state that the source does not provide enough evidence. It must not fill gaps from model memory.

## Extraction-Profile Dependency

#271 extraction profiles define whether approved sources can produce substantive bounded cited content.

Source Registry Admin can approve and register a source before #271 capability is complete, but substantive enrichment requires a validated retrieval/extraction profile.

The admin workflow must record the retrieval profile ID and extraction profile ID, or explicitly record that the source is not yet eligible for substantive extraction.

This artifact does not implement #271 and does not create extraction-profile implementation tickets.

## Guardrails

Source Registry Admin must explicitly preserve:

- no arbitrary web search
- no user-provided URL retrieval outside governed source-add workflow
- no broad crawling
- no wildcard origins
- no candidate-only source activation
- no browser-side source fetch
- no browser-side provider/current-source calls
- no package-authority promotion
- no undocumented source usage
- no source deletion that erases audit history
- no Production activation without explicit environment eligibility and validation
- no source activation without receipt generation
- no source use without citation/use documentation

Additional required refusals:

- unknown source IDs
- missing approval evidence
- missing owner or steward
- missing allowed origin
- missing allowed path prefix or document boundary
- missing retrieval profile
- missing extraction profile when substantive extraction is required
- unbounded redirects
- root-domain-only fetch scope
- non-HTTPS external source URLs unless separately owner-authorized
- credentialed source retrieval unless separately owner-authorized
- secret value logging
- apply mode without rollback target capture
- apply mode without a receipt target
- promotion when Preview smoke is missing or failed

Refusals should be receipt-worthy events.

## Candidate Implementation Roadmap

Candidate child tickets for a later owner decision, not created by this ticket:

1. Design Source Registry Admin command contract v01.
2. Define source registry schema and lifecycle states v01.
3. Add source record validation v01.
4. Add governed add/register source workflow v01.
5. Add source approval receipt workflow v01.
6. Add Preview enable/disable workflow v01.
7. Add Production eligibility and promotion workflow v01.
8. Add emergency disable and rollback workflow v01.
9. Add source-use documentation and citation-lane reporting v01.
10. Add admin smoke orchestration v01.
11. Add operator documentation v01.
12. Add minimal CLI/script implementation v01.
13. Consider UI/admin surface only after CLI/script path is proven.

This roadmap is candidate planning only. It does not create Source Registry Admin child implementation issues.

## Open Owner Decisions

Open owner decisions after this artifact lands:

1. Start #271 extraction-profile implementation first or create the first Source Registry Admin design child ticket first.
2. Decide whether historical #269 references remain archival metadata in future Source Registry Admin receipts.
3. Decide whether the first implementation child should be command contract design, schema definition, or source record validation.
4. Decide whether a JSON schema should become the authoritative source-record contract before any CLI/script implementation.
5. Decide when UI/admin surface work is allowed, after the CLI/script path is proven.

## Boundary Confirmations

- #269 remains closed.
- #269 was not reopened by this ticket.
- #269 was not closed by this ticket.
- #271 remains open and separate.
- #271 extraction-profile work was not started by this ticket.
- No Source Registry Admin child implementation issues were created.
- No extraction-profile implementation tickets were created.
- No existing issue or PR was relabeled.
- No source registries were mutated.
- No source was enabled.
- No source was disabled.
- No source was retired.
- No source was promoted.
- No Cloudflare CLI or API was used.
- No runtime behavior was changed.
- No package authority was changed.
- No Production apply was started.
- No OKF implementation was started.
- No Google SDLC implementation was started.
- No multi-agent orchestration implementation was started.
- `codex-automerge` was not applied.

## Recommended Next Action

After this product requirements artifact is merged and locally closed out, the next step is an explicit owner decision point:

Choose whether to start #271 extraction-profile implementation first or create the first Source Registry Admin design child ticket.

Do not start either path by assumption.