AI assistance and governance

Manual home · Role guides · Coverage · Gaps

Manual conventions and recovery apply to every workflow. Evidence level: code inspected; related tests were inspected, not executed.

flowchart TD
  A[Owner asks a question] --> B[Permission scoped retrieval]
  B --> C[Cited answer or uncertainty]
  C --> D{Action proposed?}
  D -->|Yes| E{Owner confirms?}
  E -->|Yes| F[Revalidate target and execute]
  E -->|No| G[Cancel or leave pending]
  C --> H[Rate answer]
  H --> I{Explicit excerpt sharing?}
  I -->|No| J[Metadata only quality review]
  I -->|Yes| K[Redacted expiring excerpt review]

ASK-01 — Ask a grounded question and manage private conversations

Status: Feature-gated. Verification: code inspected; no runtime completion claim.

Purpose: ask a grounded question and manage private conversations.

Actors and access: Authenticated user under the Ask router; tool execution checks the user's permissions; web and server feature gates must be enabled.

Prerequisites: ASK_SENTINEL_ENABLED and VITE_ASK_SENTINEL_ENABLED, configured model/worker and usage allowance.

Entry point: Ask Sentinel.

1. Start/open a private conversation and ask a question about accessible tenant records.
2. Monitor the answer run and inspect citations; follow supported permission-scoped sources.
3. Wait for the current answer before another question; retry only failed runs. Delete the conversation when no longer needed.

Result: Owner-scoped conversation turns contain a grounded answer or an explicit failure/uncertainty state.

Exceptions and recovery: Private conversations are not a quality-review inbox. Expired/inaccessible citations can cause prior answer content to be suppressed. Failed provider/usage runs require remediation before retry; no unavailable data should be invented.

Source evidence: services/api/src/ask-sentinel/routes.ts; services/api/src/ask-sentinel/tools.ts; apps/web/src/features/ask-sentinel/ask-sentinel.tsx.

ASK-02 — Confirm or cancel an Ask Sentinel action proposal

Status: Feature-gated. Verification: code inspected; no runtime completion claim.

Purpose: confirm or cancel an Ask Sentinel action proposal.

Actors and access: Conversation/action owner with the permissions required by the proposed operation.

Prerequisites: A pending proposal attached to an assistant turn in the owner's conversation.

Entry point: Ask Sentinel → proposed action.

1. Read the proposed action, target and current evidence.
2. Explicitly confirm to execute, or cancel it.
3. Inspect the resulting state/link and any stale/conflict response before continuing.

Result: Only a confirmed eligible action is executed; cancellation ends the pending proposal.

Exceptions and recovery: A question or generated proposal is not authorisation to mutate. Stale targets, non-pending proposals and missing permissions fail. Refresh/review a new proposal instead of repeatedly confirming an old one.

Source evidence: services/api/src/ask-sentinel/routes.ts; services/api/src/ask-sentinel/actions.ts; apps/web/src/features/ask-sentinel/ask-sentinel.tsx.

ASK-03 — Rate answers and conduct tenant/platform quality review

Status: Feature-gated. Verification: code inspected; no runtime completion claim.

Purpose: rate answers and conduct tenant/platform quality review.

Actors and access: Owner rates own assistant answer; ask:quality:review for tenant review; separate platform operator or platform:admin boundary for platform review.

Prerequisites: A stored answer; a current opt-in shared excerpt is required for content evaluation.

Entry point: Ask answer feedback; Ask quality review; platform quality console.

1. Submit a rating/reason; metadata is the default. Explicitly opt in if sharing a redacted question/answer excerpt.
2. Quality reviewers inspect aggregate trends and only permitted shared content.
3. Record the supported evaluation with reviewer identity; review expiry before using any excerpt for evaluation/import.

Result: Feedback and evaluations are stored separately from private conversations.

Exceptions and recovery: One owner rating per answer is enforced. Shared excerpts expire no later than their conversation; metadata review must not be described as private-conversation access. Missing/expired opt-in content prevents content evaluation.

Source evidence: services/api/src/ask-sentinel/routes.ts; services/api/src/platform/routes.ts; apps/web/src/features/ask-sentinel/quality-review.tsx.

ASK-04 — Review AI learning signals and activate tenant guidance

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: review AI learning signals and activate tenant guidance.

Actors and access: ask:quality:review or audits:manage, with platform override; local UI additionally requires intelligence access.

Prerequisites: Reviewed audit/correction/adjudication/feedback patterns and appropriate tenant evidence.

Entry point: AI learning.

1. Inspect source signals and create a draft guidance record for audit, Ask, live assist or all supported workflows.
2. Review/edit its versioned instruction and explicitly activate the approved version.
3. Create a revision or rollback draft when guidance changes, then review/activate deliberately.

Result: Only activated guidance can influence supported later AI processing.

Exceptions and recovery: A detected pattern is not automatically approved guidance. Keep sensitive content out of instructions. Rolling back through the supported version flow differs from editing active history in place.

Source evidence: services/api/src/ai-learning/routes.ts; apps/web/src/features/ai-learning/ai-learning.tsx; packages/contracts/src/ai-learning.ts.

ASK-05 — Run paired evaluations and approve or roll back a tenant AI pilot

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: run paired evaluations and approve or roll back a tenant AI pilot.

Actors and access: ask:quality:review or audits:manage, with platform override.

Prerequisites: Saved held-out cases; current reviewed opt-in content for imported cases; reachable baseline/candidate targets and usage allowance.

Entry point: AI learning → evaluations / Tenant pilot release.

1. Create/review evaluation cases and choose the candidate model/prompt against the active baseline.
2. Run paired evaluations and inspect agreement, citation correctness, unanswered rate and latency.
3. Approve only a qualifying candidate for the tenant pilot; roll back to a previous release when supported.

Result: A gated tenant release selects an evaluated candidate or restores its predecessor.

Exceptions and recovery: Approval requires improved held-out agreement and no citation regression, including perfect candidate citation correctness in the route gate. Missing targets/cases or no previous release prevents the corresponding action; a run alone does not promote.

Source evidence: services/api/src/ai-evaluation/routes.ts; apps/web/src/features/ai-learning/ai-learning.tsx; packages/contracts/src/ai-evaluation.ts.

ASK-06 — Use live assist and record suggestion feedback

Status: Incomplete. Verification: code inspected; no runtime completion claim.

Purpose: use live assist and record suggestion feedback.

Actors and access: qms:read and session ownership at tenant API; integration events use an integration credential. Local agent web access is limited (GAP-02).

Prerequisites: Published knowledge/active approved guidance; voice requires the live transcription gateway.

Entry point: Live assist; integration session-event API.

1. Start a chat or voice session. Deliver ordered redacted transcript events, or supported small audio segments with stable IDs/sequences.
2. Review cited suggestions and decide whether to use, dismiss or mark a false alert; inspect session metrics.
3. Close the session and record the supported outcome.

Result: A short-lived session retains redacted events and user decisions for its four-hour window.

Exceptions and recovery: Sequence gaps/conflicting replays, contact details, closed/expired sessions and event limits are handled explicitly. Retry failed voice segments with the same sequence. Live assistance is advisory; actual external agent desktop/telephony integration is unverified.

Source evidence: services/api/src/live-assist/routes.ts; services/api/src/live-assist/integration-routes.ts; apps/web/src/features/live-assist/live-assist.tsx.