feat(concelier): blocked-readiness state for credential-gated sources (SRC-CREDS-005)

Closes the last open task in SPRINT_20260422_003. Persisted operator
enablement is now separated from runtime readiness so credential-gated
sources can show an explicit blocked state instead of collapsing into a
generic failed/disabled shape.

Readiness model:
- new SourceReadiness constants class: Disabled | Unsupported | Blocked | Ready
- ConfiguredAdvisorySourceStatus gains Readiness + BlockedReason alongside
  existing SyncState (kept as backward-compatible alias)
- enabled = persisted operator intent (untouched)
- readiness = blocked when persisted-enabled and credentials/URIs missing
- blockedReason = free-form list of missing fields
- blockingReason.errorCode = SOURCE_CONFIG_REQUIRED for structured drill-down

Endpoint propagation:
- /status: persisted enabled=true kept; readiness=blocked; readyForSync=false
- /{id}/enable: 200 with readiness=blocked; sourceRegistry left disabled
  until credentials land (pre-existing behaviour retained)
- /{id}/sync: 422 readiness=blocked + SOURCE_CONFIG_REQUIRED;
  **connector never invoked**, no job run created
- /sync (batch): per-result outcome=blocked with readiness/errorCode/
  blockedReason; excluded from totalTriggered; other sources proceed
- Transition: PUT /{id}/configuration with missing credential →
  runtimeOptionsInvalidator.Invalidate → next /status flips to ready.
  No disable/re-enable cycle needed.

Tests: 8 targeted xUnit methods via scripts/test-targeted-xunit.ps1,
8/8 pass. Includes: blocked status exposure, blocked-to-ready transition
on persisted credential, connector-not-invoked-when-blocked, plus 4
pre-existing SRC-CREDS-002 regression tests.

Docs:
- docs/modules/concelier/connectors.md — new "Blocked / sleeping
  readiness state" section with field contract, per-endpoint behaviour
  table, UI/CLI rendering guidance, resolution flow
- docs/modules/cli/guides/commands/db.md — short note under
  `db connectors configure` cross-linking the connectors.md contract

Sprint SPRINT_20260422_003 archived — all 5 tasks DONE.

New fields are additive; existing UI types in
source-management.api.ts ignore unknown fields so no UI breakage. A
future FE pass can wire explicit readiness/blockedReason rendering.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs-archived/implplan/SPRINT_20260422_003_Concelier_source_credential_entry_paths.md

@@ -0,0 +1,132 @@
+# Sprint 20260422_003 - Concelier Source Credential Entry Paths
+
+## Topic & Scope
+- Replace env-only/operator-host-only credential handling for advisory source connectors with persisted source settings that can be supplied through StellaOps UI and CLI flows.
+- Add explicit source configuration contracts for credentialed connectors so enable/check/sync surfaces can explain what is missing and what is already retained without leaking secrets.
+- Extend operator surfaces to configure advisory source credentials from the advisory/VEX console and setup-adjacent flows, then document the vendor login and credential acquisition steps.
+- Working directory: `src/Concelier`.
+- Expected evidence: backend/API contracts, persisted runtime configuration wiring, focused Web/CLI entry paths, updated docs, and targeted tests.
+- Cross-module touchpoints explicitly allowed for this sprint:
+  - `src/Web/StellaOps.Web/**`
+  - `src/Cli/StellaOps.Cli/**`
+  - `docs/modules/concelier/**`
+  - `docs/modules/cli/**`
+  - `docs/UI_GUIDE.md`
+  - `docs/README.md`
+  - `docs/implplan/**`
+
+## Dependencies & Concurrency
+- Depends on the completed runtime-alignment work in [SPRINT_20260421_003_Concelier_advisory_connector_runtime_alignment.md](/C:/dev/New%20folder/git.stella-ops.org/docs/implplan/SPRINT_20260421_003_Concelier_advisory_connector_runtime_alignment.md).
+- Safe parallelism: keep backend credential/runtime work centered in `src/Concelier`, Web changes centered in `src/Web/StellaOps.Web`, CLI changes centered in `src/Cli/StellaOps.Cli`, and docs aligned only after the contracts settle.
+- The repo worktree is already dirty; edits in touched files must preserve unrelated in-flight changes.
+
+## Documentation Prerequisites
+- [docs/README.md](/C:/dev/New%20folder/git.stella-ops.org/docs/README.md)
+- [docs/07_HIGH_LEVEL_ARCHITECTURE.md](/C:/dev/New%20folder/git.stella-ops.org/docs/07_HIGH_LEVEL_ARCHITECTURE.md)
+- [docs/modules/platform/architecture-overview.md](/C:/dev/New%20folder/git.stella-ops.org/docs/modules/platform/architecture-overview.md)
+- [docs/modules/concelier/architecture.md](/C:/dev/New%20folder/git.stella-ops.org/docs/modules/concelier/architecture.md)
+- [docs/modules/concelier/connectors.md](/C:/dev/New%20folder/git.stella-ops.org/docs/modules/concelier/connectors.md)
+- [docs/modules/cli/architecture.md](/C:/dev/New%20folder/git.stella-ops.org/docs/modules/cli/architecture.md)
+- [docs/UI_GUIDE.md](/C:/dev/New%20folder/git.stella-ops.org/docs/UI_GUIDE.md)
+- [src/Concelier/AGENTS.md](/C:/dev/New%20folder/git.stella-ops.org/src/Concelier/AGENTS.md)
+- [src/Web/AGENTS.md](/C:/dev/New%20folder/git.stella-ops.org/src/Web/AGENTS.md)
+- [src/Cli/AGENTS.md](/C:/dev/New%20folder/git.stella-ops.org/src/Cli/AGENTS.md)
+
+## Delivery Tracker
+
+### SRC-CREDS-001 - Add persisted advisory source configuration contracts
+Status: DONE
+Dependency: none
+Owners: Developer / Implementer
+Task description:
+- Concelier already persists arbitrary source config JSON, but the operator-facing source management contract only exposes env-var hints and the runtime only validates startup-bound options. Introduce a first-class source configuration contract that describes editable fields, retained secret state, and source-specific readiness requirements for credentialed connectors.
+- The resulting API must let UI and CLI surfaces fetch source config metadata, submit updates without requiring env vars, and distinguish between missing values, retained secrets, and source defaults without echoing secret values back to callers.
+
+Completion criteria:
+- [x] Source-management API exposes source-specific config schema and retained-secret state for credentialed connectors.
+- [x] Persisted source config updates can be written without using environment variables.
+- [x] Existing enable/check/sync surfaces use the new persisted config readiness model instead of env-only messages.
+
+### SRC-CREDS-002 - Wire persisted source settings into connector runtime
+Status: DONE
+Dependency: SRC-CREDS-001
+Owners: Developer / Implementer, QA
+Task description:
+- Credential entry paths are only useful if live connector runtime reads the persisted values. Refactor the affected connectors and support services so GHSA, Cisco, MSRC, Oracle, and any source touched in this sprint resolve runtime settings from persisted source config with safe fallbacks for existing host-bound options.
+- The runtime contract must support secret retention, minimal hot-reload semantics for operator changes, and deterministic readiness diagnostics.
+
+Completion criteria:
+- [x] Credentialed connectors can run from persisted source config supplied through Concelier APIs.
+- [x] Startup-bound options remain compatibility fallbacks rather than the only supported path.
+- [x] Targeted tests cover at least one persisted-config readiness path per credentialed source family.
+
+### SRC-CREDS-003 - Expose advisory source credential entry in Web and CLI
+Status: DONE
+Dependency: SRC-CREDS-001
+Owners: Developer / Implementer, Documentation author
+Task description:
+- Add operator-facing entry paths so source credentials can be supplied without editing env files. The Web advisory/VEX source catalog should expose editable source settings for connectors that require credentials or explicit URIs, and the CLI should gain matching commands that drive the same backend API.
+- UI/CLI behavior must preserve the backend truth model, indicate when a secret is retained server-side, and avoid forcing users to re-enter secrets on unrelated edits.
+
+Completion criteria:
+- [x] Web advisory-source management surface can view/edit persisted source config and retained-secret state.
+- [x] Setup-adjacent source flows no longer imply env-only remediation for credentialed connectors.
+- [x] CLI offers source config inspection/update commands against the backend API.
+
+### SRC-CREDS-004 - Document credential acquisition and Adobe/Chromium follow-through
+Status: DONE
+Dependency: SRC-CREDS-002
+Owners: Documentation author, QA
+Task description:
+- Write operator documentation under `docs/` that explains where to sign in for each supported credentialed source, what credential type to create, whether the source is paywall/partner limited, and where the new UI/CLI entry paths live.
+- Continue the Adobe/Chromium follow-through by validating that the canonical source docs and runtime surfaces remain aligned after the credential-path changes, then capture the test evidence in this sprint.
+
+Completion criteria:
+- [x] Docs describe the new UI/CLI credential entry paths and retained-secret behavior.
+- [x] Docs list the official operator login destinations and required credential types for supported credentialed sources.
+- [x] Adobe/Chromium source docs/runtime verification is rechecked after the credential-path rollout.
+
+### SRC-CREDS-005 - Surface blocked schedule state for credential-gated sources
+Status: DONE
+Dependency: SRC-CREDS-002
+Owners: Developer / Implementer, Documentation author
+Task description:
+- Credential-gated sources can now be configured through the product, but the steady-state source status still collapses "enabled but waiting on credentials" into a generic failed/disabled shape. Split persisted enablement from runtime readiness so the product can show an explicit blocked or sleeping state while preserving operator intent.
+- Sync attempts for blocked sources must explain that credentials or required URIs are missing instead of looking like a generic scheduler failure. The source-management API, focused tests, and operator docs all need to align on the blocked-state contract.
+
+Completion criteria:
+- [x] Source status responses preserve persisted enablement while exposing an explicit blocked readiness state and reason.
+- [x] Sync attempts for blocked sources report a blocked outcome with the missing-configuration reason attached.
+- [x] Docs explain the blocked or sleeping state for credential-gated sources.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-04-22 | Sprint created to replace env-only advisory source credential handling with persisted UI/CLI configuration paths and runtime-backed connector readiness. | Codex |
+| 2026-04-22 | Added persisted source-configuration schemas and runtime overlays for GHSA, Cisco, Microsoft, Oracle, Adobe, and Chromium so source settings can be supplied through Concelier rather than only through host env/yaml. | Codex |
+| 2026-04-22 | Updated Web and CLI operator surfaces plus Concelier/CLI/UI documentation with login destinations, credential types, retained-secret behavior, and Adobe/Chromium public-endpoint guidance. | Codex |
+| 2026-04-22 | Verification: `dotnet build src/Concelier/StellaOps.Concelier.WebService/StellaOps.Concelier.WebService.csproj -v minimal` succeeded; targeted xUnit helper run for 4 source-configuration methods passed (`Total: 4, Failed: 0`); `npm run build` in `src/Web/StellaOps.Web` succeeded. | Codex |
+| 2026-04-22 | Added blocked or sleeping source-state handling so persisted enablement survives missing credentials, sync attempts report blocked outcomes, targeted xUnit blocked-state coverage passed (`Total: 5, Failed: 0`), and the Web source catalog now renders blocked sources explicitly. | Codex |
+| 2026-04-22 | Formalised the readiness contract: added `SourceReadiness` constants + explicit `readiness` and `blockedReason` fields on `/status`, `/{id}/enable`, `/{id}/sync`, and `/sync` responses alongside the pre-existing `syncState`/`blockingReason` surface; authored two new focused regression tests (`StatusEndpoint_ExposesReadinessAliasAndBlockedReasonAlongsideSyncState`, `StatusEndpoint_TransitionsFromBlockedToReadyWhenCredentialsPersisted`, `SyncEndpoint_ConnectorNotInvokedWhenBlocked`); added a Blocked / sleeping section to `docs/modules/concelier/connectors.md` and a cross-link in `docs/modules/cli/guides/commands/db.md`. Targeted xUnit run across 8 readiness/sync blocked tests passed (`Total: 8, Failed: 0`); regression run across the 4 SRC-CREDS-002 source-configuration tests still passes (`Total: 4, Failed: 0`). | Codex |
+
+## Decisions & Risks
+- Decision: source credentials must be operator-supplied through StellaOps UI and CLI paths, with environment variables retained only as backward-compatible fallbacks.
+- Risk: MSRC and other singleton services currently cache startup-bound options, so persisted-config support requires refactoring the runtime settings resolution path instead of adding a thin API-only layer.
+- Risk: some upstream programs may require vendor accounts, approval, or terms acceptance even if StellaOps supports the connector path; docs must distinguish product integration support from upstream entitlement.
+- Decision: Adobe and Chromium now expose the same persisted UI/CLI configuration path as the credentialed connectors so mirrored public endpoints are no longer env-only overrides.
+- Decision: `additionalIndexUris` is normalized like the other multi-URI fields, so CLI and UI comma or semicolon input converges to a stable persisted shape.
+- Decision: persisted source `enabled` now represents operator intent, while source status exposes `syncState` and `blockingReason` so credential-gated connectors can remain enabled but blocked until credentials or required URIs are supplied.
+- Web fetch audit (user-requested upstream credential research):
+  - `https://docs.github.com/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token` - confirm current GitHub PAT creation path and policy notes.
+  - `https://docs.github.com/en/enterprise-cloud@latest/rest/security-advisories/global-advisories` - confirm GHSA REST authentication expectations and anonymous/fine-grained token support.
+  - `https://docs.github.com/articles/authorizing-a-personal-access-token-for-use-with-a-saml-single-sign-on-organization` - confirm SSO authorization requirement for PAT-backed org access.
+  - `https://developer.cisco.com/docs/psirt/authentication/` - confirm Cisco PSIRT openVuln app registration flow, grant type, and token issuance pattern.
+  - `https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app` - confirm Microsoft Entra app registration flow and IDs operators need to capture.
+  - `https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials` - confirm Microsoft client secret creation flow and current Microsoft guidance.
+  - `https://www.oracle.com/security-alerts/`, `https://helpx.adobe.com/security/security-bulletin.html`, `https://chromereleases.googleblog.com/atom.xml` - confirm Oracle, Adobe, and Chromium default public entry points remain unauthenticated.
+- Residual risk: the broader `AdvisorySourceEndpointsTests` class contains unrelated legacy failures outside this feature slice when run wholesale, so QA evidence for this sprint is the repo-approved targeted xUnit run against the exact connector-configuration methods rather than a class-wide pass count.
+
+## Next Checkpoints
+- 2026-04-22: land backend source configuration contracts and persisted runtime settings.
+- 2026-04-22: expose matching Web/CLI entry paths and update operator docs.
+- 2026-04-22: run targeted verification for credentialed connectors plus Adobe/Chromium regression checks.