# Knowledge Scenarios and ST-2802 PrivateLink Diagnosis

## Current Design

- Staging enables automatic coverage from the scenario and resolution lists in
  `deploy/app-delivery/.../configmap.yaml`; the worker persists the resulting
  Auto Coverage Gate row for reporting and Base sync.
- Dry-run uses the deterministic scenario classifier, while live automation
  uses the LLM classifier and then the deterministic policy boundary.
- Backend diagnostic materialization currently persists Investibook summaries.
  Clinic and Wetech are approved read-only agent skills selected by the
  scenario classification rather than backend-materialized providers.

## Risks

- Enabling broad knowledge scenarios can accidentally admit privileged actions
  if resolution and risk checks are weakened.
- The deterministic classifier currently matches `private` inside
  `PrivateLink`, incorrectly adding `private_or_preview_feature`.
- The live classifier can confuse a read-only PrivateLink incident diagnosis
  with a request to change a network resource.
- A Clinic query that is not selected by scenario classification would be an
  uncontrolled fallback and could overstate a metadata correlation as root
  cause.

## Target Contract

- Staging additionally enables `feature_usage_or_capability` and
  `security_or_access_control`; production remains unchanged.
- Existing resolution allowlists and hard stops remain authoritative. The
  change does not enable customer-visible replies or privileged operations.
- `PrivateLink` is not a private-preview signal. Only explicit private preview,
  experimental, feature-gate, special-build, or R&D-confirmation language sets
  `private_or_preview_feature`.
- A request to investigate a PrivateLink error is a read-only
  `cluster_runtime_issue`; it uses Clinic evidence for ST and is not an
  `operation_request` unless support is asked to create, modify, delete, or
  approve a real network resource.
- For an evidence-required ST diagnostic, an existing cluster, tenant, or org
  identifier is sufficient to select Clinic deterministically. Missing Jira
  `Account Alias` or `clusterId` must not reclassify that ST case as OP
  non-Wetech. APID and other non-ST cases retain the existing OP boundary.
- The scenario classification is the canonical provider selection. When it
  selects Clinic, the agent uses the installed read-only Clinic skill and
  records the checked scope and evidence limits in replay context. The reply
  must distinguish a metadata correlation from verified Endpoint Service, AWS
  event, or DNS evidence and must not approve a production connection change.

## Non-Goals

- Do not enable production automation or customer-visible Jira replies.
- Do not add AWS console, customer VPN, or personal credential access.
- Do not add Investibook or free-form agent querying as a fallback source;
  Clinic access is allowed only when the canonical classification selects it.
- Do not automatically change PrivateLink, DNS, routes, or connection strings.

## Implementation Steps

1. Add local classifier and prompt contract tests for an ST-2802-shaped case.
2. Narrow the private-preview matcher and clarify the live classifier prompt.
3. Deterministically preserve Clinic routing for ST diagnostics with existing
   cluster, tenant, or org context before applying the OP non-Wetech boundary.
4. Add the two knowledge scenarios to the staging app-delivery source template.
5. Run typecheck and the complete test suite.
6. Commit and use the repository workflow to create the app-delivery PR.
7. After deployment, verify pod env, gate behavior, DB state, and an ST-2802
   read-only dry-run.

## Verification Checklist

- APID-29171/29172-shaped knowledge cases can pass scenario coverage when their
  resolution is enabled and they carry no hard-stop risk.
- APID-29179-shaped audit guidance can pass as
  `security_or_access_control/direct_answer`.
- ST-2802-shaped input is `cluster_runtime_issue/evidence_assisted` with
  `evidenceProvider=clinic` and no private-preview flag.
- Requests to create or change PrivateLink remain
  `operation_request/human_required`.
- Staging pod env contains both new scenarios; prod files are unchanged.
- No Jira customer-visible comment, transition, or production operation occurs.