All runbooks
evidenceuai-explorerredacted view

Final QA/QoL Punch List Evidence

Synced UAI Explorer evidence documentation from docs/evidence/final-qaqc-qol-punch-list-2026-06-21.md.

Updated 2026-06-21·Freshness: Reference·Sensitive tokens or credentials were hidden before display.

Final QA/QoL Punch List Evidence

Date: 2026-06-21
Timezone: America/St_Johns

Kind: uai-final-qaqc-qol-punch-list

Scope

Final agent-team QA/QoL pass for the UAI Explorer AI bootstrap patch.

Review lanes:

  • API/security boundary review.
  • Documentation and agent-lane review.
  • UX/QoL review.

Punch-Out Status

Punch-out status: completed

Item Status Patch result
Optional UAI-wide agent feedback lane. Punched out. Added product-scoped POST /api/ai/feedback, uai_submit_feedback, admin review, redaction, audit, convention runbook, and tests.
Admin must not be used as AI adapter identity. Punched out. /api/ai/bootstrap, /api/ai/catalog, /api/ai/context/{slug}, and /api/ai/feedback now require role=ai; admin reviews through admin surfaces.
Denied raw/sanitized lanes must not become catalog content. Punched out. Catalog seed, admin create/patch, access checks, and content reads refuse raw-survey-zone, sanitized-exports, uploads, test data, and denied runtime lanes.
Feedback metadata must be safe. Punched out. Feedback source and body are redacted before storage and display.
Boundary denials need audit coverage. Punched out. Human/AI surface denials now create audit rows for catalog/content/AI lane role mismatches.
Cortex memory and embedding query instructions. Punched out. Added [REDACTED:high-entropy].md with Cortex memory, knowledge base refresh, and embedding query rules.
Beacon and Mesh boundaries. Punched out. Beacon is read-only unless cataloged/approved; Mesh runtime/node work remains outside UAI Explorer AI lanes.
AI lane versus direct repo access exception model. Punched out. Rules now say agents use AI lanes whenever possible; direct repo access is only for explicit local code/docs/verification assignments.
AI UX quality. Punched out. AI users land on AI Context; packet view shows title, audit ID, char cap, redaction boundary, and copy action; review queue includes agent-feedback triage.
Tiny agent task prompt UX. Punched out. /api/ai/bootstrap returns task_prompt_contract; the AI Context view exposes copyable full and quick prompts so operators provide product, task, authority, and done condition instead of long rule prompts.
Basic AI API key lane. Punched out. Added revocable role=ai bearer API keys issued through /api/admin/access-tokens, with one-time key visibility, AI-lane inheritance, redaction coverage, and tests.
Redaction breadth tests. Punched out. Added direct tests for private keys, webhooks, database URLs, credential URLs, and feedback metadata.

Agent Feedback Convention

Agents may submit optional feedback when a UAI product lane is beneficial, missing context, confusing, blocked, or worth improving. This is a product feedback lane for uai-explorer, cortex, beacon, mesh, cadence, devine, and future UAI products.

Convention runbook:

  • [REDACTED:high-entropy].md

Endpoint:

POST /api/ai/feedback

Suggested safe content:

  • product key,
  • observation,
  • blocked-on item,
  • suggested next action,
  • related catalog slug,
  • safe evidence or audit ID.

Forbidden content:

  • credentials,
  • session cookies,
  • tokens,
  • private paths,
  • raw content,
  • direct personal/contact/payment data.

Feedback is append-only. Do not edit or delete another agent's feedback. Duplicate feedback should reference the existing issue and add only new signal. No feedback means the current lane works as-is.

Out-Of-Scope vNext Improvements

  • First-class semantic search endpoint over AI-visible catalog packets.
  • Cortex-specific saved query and namespace model.
  • Native embedding index refresh job with freshness/staleness dashboard.
  • Beacon and Mesh dedicated runbooks with tags, allowed tools, and stronger no-change boundaries.
  • Review-queue state with owner, priority, status, evidence links, and close reasons.
  • External exposure hardening before public internet access: secure cookies behind HTTPS, CSRF protection, rate limiting, and explicit CORS credential posture.
  • Automated stale-evidence ranking so bootstrap prefers current truth over historical lineage.

Verification Targets

  • [REDACTED:high-entropy]
  • [REDACTED:high-entropy]
  • [REDACTED:high-entropy]
  • test_surface_denials_are_audited
  • [REDACTED:high-entropy]

Local verification:

  • python -m py_compile over server.py, tools/*.py, and tests/*.py passed.
  • python -m unittest discover -s tests -v passed with 55 tests.
  • node --check static/js/app.js passed.
  • bash -n passed for deployment/sync scripts.
  • Public Markdown secret scan passed across 60 files.

Final local and container verification is recorded in the final completion audit and finish status packet after sync.