knowledge: compound refresh supervision cycle [2026-08-01]

Author: Your Name

docs/superskills/DPS_v5/knowledge/CONTEXT.md

@@ -1,5 +1,21 @@
 # CONTEXT.md — Domain Knowledge
 
+## Ubiquitous Language
+
+- **InputCatalog**: the shared inventory and fingerprint set for source files, coverage inputs, and non-source context/configuration that can change indexing semantics. <!-- from ADR: ADR-0001 -->
+- **Full reconciliation**: a refresh that compares durable input state and chooses changed-file, context rebuild, or full-index work instead of trusting an event path list. <!-- from ADR: ADR-0001 -->
+- **WatcherSupervisor**: the bounded-retry runtime that treats the OS file watcher as an accelerator and retains periodic reconciliation when observation is degraded. <!-- from ADR: ADR-0001 -->
+
+## Architectural Decisions
+
+- Filesystem events are an optimization; `calm-core` owns refresh classification and durable input fingerprints so missed events or input drift cannot silently establish freshness. <!-- from ADR: ADR-0001 -->
+- Watcher lifecycle/freshness health is separate from the last completed indexing phase and is exposed independently through `indexing_status`. <!-- from ADR: ADR-0001 -->
+
+## Domain Gotchas
+
+- `indexing_phase == ready` only describes the last completed build; it does not prove that future filesystem changes are currently observed. <!-- from ADR: ADR-0001 -->
+- Configuration and context files can change the meaning of unchanged source bytes; they must be included in refresh fingerprints and reconciliation decisions. <!-- from ADR: ADR-0001 -->
+
 <!-- Version: 1 — populate via domain-alignment skill, then keep updated via knowledge-compound -->
 
 ## Ubiquitous Language

docs/superskills/DPS_v5/knowledge/compound-wiki.md

@@ -1,5 +1,39 @@
 # Compound Wiki
 
+---
+date: 2026-08-01
+sprint: vheatm-tier2-refresh-supervision
+adr: ADR-0001 in docs/superskills/DPS_v5/ADR.md
+modules: [calm-core, calm-server, scip, watcher]
+---
+
+## Cycle: core-refresh-catalog-and-watcher-supervision
+
+### New Domain Terms Added to CONTEXT.md
+
+- `InputCatalog`: shared input inventory and fingerprints ✅
+- `Full reconciliation`: durable-input-aware refresh escalation ✅
+- `WatcherSupervisor`: bounded watcher retry and degraded fallback ✅
+
+### Bug Patterns
+
+- Missed filesystem events or non-source input drift can leave a completed index stale: observed and resolved in ADR-0001; no recurring PATTERN-DEBT entry created.
+
+### Gotchas Captured
+
+- A ready last build is not proof of future observation → added to `CONTEXT.md` Domain Gotchas ✅
+- Context/configuration changes can alter unchanged source semantics → added to `CONTEXT.md` Domain Gotchas ✅
+
+### Architectural Decisions Promoted
+
+- Core owns refresh classification and durable input fingerprints; watcher health is a separate axis → added to `CONTEXT.md` Architectural Decisions ✅
+
+### Nothing extracted
+
+No new PATTERN-DEBT entry was warranted by this single cycle.
+
+---
+
 Auto-populated by: knowledge-compound skill (run after every adr-commit)
 Queried by: kb-query skill
 MCP-ready: YAML frontmatter per entry for future semantic KB import