Cory Policht
← All references
REF · US-OUI-2-9-VAULT-CONTEXT-SURFACES · STORY

Us Oui 2 9 Vault Context Surfaces

source: ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.9-Vault-Context-Engine-Surfaces.mdscrubbed extract
Cited by:the-platform-rises

Scrubbed extract of ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.9-Vault-Context-Engine-Surfaces.md — cited by the Chronicle (03-the-platform-rises). Redactions: phone / service detail / secrets / clearance / personal / internal hosts.

type: implementation-plan category: Work project: ADP-Orchestration-UI priority: Medium status: backlog created: 2026-05-14 epic: Epic-2-Orchestration-Dashboard user-story: US-OUI-2.9 effort: 8h precedence:

  • “[[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.3-Agent-Detail-Timeline]]”
  • “[[US-OUI-1.7-Sensitivity-Classification-UI]]” parallel_group: review-profile: standard source: wireframe-gap-analysis-2026-05 depends-on:
  • ADR-015
  • IVaultContextProvider tags:
  • implementation-plan
  • epic-2
  • vault
  • context-engine

US-OUI-2.9: Vault Context Engine Surfaces

Epic: [[README|Epic 2: Orchestration Dashboard]] Owner Agent: \xe2\x80\x94 Effort: 8h Priority: 🟡 Medium Status: 🔵 Backlog

Mission

Render the vault context surfaces called for in [[../Wireframe-Gap-Analysis|Wireframe Gap Analysis]] §5: vault sync state, vault document registry, injected-vs-loaded distinction, per-agent vault read log, vault citation linking, and the spawn-time context preview. All views consume the IVaultContextProvider interim stub from Q4 (AIS interim implementation; AMC later) — do not re-implement provider logic in the UI. Sensitive docs render with the badge primitive from US-OUI-1.7 across every surface; sensitive-doc reads in the per-agent log show metadata only (no content preview), enforced server-side by the redactor from ADR-015 §3e but mirrored client-side as defense-in-depth.

Context

The vault context engine is the platform’s other core differentiator (per §5) and currently has zero UI representation. AMC will eventually own the backing logic, but the dashboard surfaces are required regardless, so v1.0 consumes IVaultContextProvider exposed by AIS as an interim. This story is the renderer; provider work is tracked separately. Sensitivity rules from §10 / ADR-015 are inherited at every render site.

Context Bootstrap

  1. [[../../AI-Dev-Platform/ADR/ADR-017-Human-Review-Branching-And-TDD-Workflow|ADR-017]] — review profile, PR schema
  2. [[../../AI-Dev-Platform/ADR/ADR-015-Sensitive-Data-Classification-And-Handling|ADR-015]] — §3a interim AIS, §3e redactor, §3f embedding exclusion
  3. [[../../AI-Dev-Platform/ADR/ADR-011-Agent-Reasoning-Emission-Contract|ADR-011]] — VaultCitation schema (Path / SectionAnchor / ContentHash / Sensitivity)
  4. [[../Wireframe-Gap-Analysis|Wireframe Gap Analysis]] §5
  5. [[US-OUI-1.7-Sensitivity-Classification-UI]] — badg[[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.3-Agent-Detail-Timeline]]
  6. [[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.3-Agent-Detail-Timeline]] — host surface for the per-agent vault read log
  7. [[../_pkf|OUI _pkf]]

Gate Policy

Trigger Gate Type Condition / Reasoning
Vault citation rendered with content excerpt when Sensitivity === sensitive Trust Gate ADR-015 §3c/§3e; render metadata only
Vault registry column omits Sensitivity flag Trust Gate §5 capability table requires the flag column
Provider call bypasses IVaultContextProvider (direct filesystem or REST) Trust Gate Architectural breach; provider is the single integration point per Q4
ContentHash drift detected on a citation Confidence Gate Surface drift indicator; do not silently re-render
Test failure during Verify & Refactor Trust Gate —

Deliverables

src/vault/VaultSyncStatus.tsx (new)

  • Shows last sync timestamp, error count, conflict count from IVaultContextProvider.getSyncStatus()
  • Refreshes via WebSocket event vault.sync_updated

src/vault/VaultDocumentRegistry.tsx (new)

  • Tabular view of indexed docs: path, last modified, agent-injectable flag, authoritative-for, Sensitivity column (uses <SensitivityBadge>)
  • Filter by sensitivity, by injectable, by authoritative-for project

src/vault/InjectedBadge.tsx (new)

  • Renders INJECTED badge on docs the agent’s session received as injected context (distinct from LOADED/available-to-read)

src/vault/VaultReadLog.tsx (new)

  • Per-agent log: doc path, timestamp, content-hash short, redacted-flag if sensitive
  • Sensitive entries show metadata only (no body preview); rendered with <SensitivityBorder>
  • Renders inside the agent detail timeline from US-OUI-2.3

src/vault/VaultCitationLink.tsx (new)

  • Renders ↳ vault: <path>#<anchor> as a live link
  • Click opens the doc in a side panel or the user’s vault tool (configurable)
  • Shows drift indicator when ContentHash no longer matches the current file
  • Sensitive citations render path + [sensitive] with no excerpt per ADR-015 §3c

src/vault/SpawnTimeContextPreview.tsx (new)

  • Embedded in <SpawnDialog> (US-OUI-2.8) Context Selection panel
  • Shows preview of what context will be injected; allows trimming
  • Explicit confirmation required when any selected doc is sensitive; selection auto-forces local tier

src/vault/__tests__/vault-surfaces.test.tsx (new)

  • Sensitive citation never renders an excerpt
  • Registry exposes the Sensitivity column even when no sensitive docs are present
  • Drift indicator fires when provider reports currentHash !== citationHash
  • WebSocket sync event re-renders the sync status panel
  • All provider calls go through IVaultContextProvider (no direct fetch)

Execution Phases

TDD-ordered per ADR-017 §4.

  1. Branch Creation — agent/US-OUI-2.9-vault-context.
  2. Load Context — Read Context Bootstrap. (Plan Review.)
  3. Write Failing Tests — Tests above. (Test Review.)
  4. Implement — Surfaces above.
  5. Verify & Refactor — Pipeline green; status review.
  6. PR Submission — One PR. (PR Review.)

PR Submission Requirements

ADR-017 §5 schema: Reasoning Chain, Gate History, Citations, Review Profile (standard), Test Plan.

Implementation Notes

IVaultContextProvider shape

Interim AIS-side stub exposes:

  • getSyncStatus(): Promise<VaultSyncStatus>
  • listDocuments(filter?: VaultDocFilter): Promise<VaultDocument[]>
  • getReadLog(sessionId): Promise<VaultReadEntry[]>
  • resolveCitation(citation): Promise<{ doc: VaultDocument; currentHash: string }>

Designed for swap to AMC Memory Alignment Agent later; preserve the interface.

Files to Modify

  • src/vault/* — new files
  • src/spawn/SpawnDialog.tsx — wire <SpawnTimeContextPreview> into Context Selection
  • src/dashboard/AgentDetailTimeline.tsx — embed <VaultReadLog>
  • src/api/client.ts — provider adapter wrapping the AIS REST endpoints

Definition of Done

  • All Deliverables checked
  • Tests pass: pnpm test --run src/vault
  • Sensitive-citation no-excerpt invariant verified by test
  • Status updated to review
  • [[../../AI-Dev-Platform/ADR/ADR-015-Sensitive-Data-Classification-And-Handling|ADR-015]]
  • [[../../AI-Dev-Platform/ADR/ADR-011-Agent-Reasoning-Emission-Contract|ADR-011]] [[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.3-Agent-Detail-Timeline]]ation-UI]]
  • [[US-OUI-2.8-Agent-Spawn-Flow]]
  • [[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.3-Agent-Detail-Timeline]]
  • [[../Wireframe-Gap-Analysis|Wireframe Gap Analysis]] §5
  • [[../_pkf|OUI _pkf]]