# SCOPE > This file helps you quickly understand what this repository is about, > when it is relevant, and when it is not. > It is intentionally lightweight and may be incomplete. --- ## One-liner Specification and reference implementation of the Interaction Hub Framework (IHF) — a governed, observable interaction substrate for hub-based AI-enabled software systems. --- ## Core Idea IHF treats every meaningful UI element as a **governed interaction artifact** rather than mere markup. It connects the full traceability chain from rendered widget → user interaction → structured feedback → requirement candidate → decision record → implementation change → observed outcome. This makes interaction observable, frustration actionable, and UI evolution evidence-based. --- ## In Scope - Widget identity, lifecycle governance, and semantic addressability - Interaction event capture and contextual enrichment - Annotation and structured comment threads attached to widgets - Requirements distillation from raw feedback clusters - Governance ledger: decision records linked to requirements and implementations - Outcome observation and pre/post change comparison - AI-assisted distillation (bounded, attributable, reviewer-controlled) - Cross-hub integration of interaction signals - Platform APIs and conventions for framework-agnostic UI integration - IHF specification documents and canonical artifact type definitions --- ## Out of Scope - A complete universal frontend framework or design system - Pixel-level visual design or CSS conventions - Full product management methodology - Replacement for DevOps observability tooling (ops-hub handles that) - Unrestricted autonomous AI decision-making on requirements - Mandatory single UI technology for all hub surfaces --- ## Relevant When - Building or reviewing any hub dashboard or operator surface (dev-hub, ops-hub, fin-hub) - Capturing and triaging user/operator feedback on existing hub UIs - Defining governed widget identity for a new capability surface - Implementing structured requirements distillation from interaction signals - Designing cross-hub feedback routing or policy-linked decisions --- ## Not Relevant When - Backend API development with no interaction surface - Infrastructure provisioning or cluster operations (see railiance-*, ops-bridge) - Data pipeline or SBOM work (see state-hub / dev-hub) - One-off scripts or tooling with no end-user UI --- ## Current State - Status: Phase 5 complete — agent-assisted distillation and suggestion implemented - Implementation: Phase 0 complete (specification); Phase 1 complete (widget registry, event capture, annotations, hub dashboard, auth); Phase 2 complete (annotation severity, annotation threads, requirement candidates, triage lifecycle, reviewer assignment, triage dashboard); Phase 3 complete (requirement promotion, decision records, policy references, implementation change references, governance dashboard); Phase 4 complete (deployment records, outcome signals, pre/post comparison, regression detection, change evaluation, recurrence tracking, antifragility dashboard); Phase 5 complete (agent proposals, review records, confidence annotations, cluster summarization, requirement drafting, duplicate detection, policy sensitivity, implementation proposals, agent audit dashboard) - Stability: core artifact model and schema are stable; Phase 5 data model (AgentProposal, AgentReviewRecord, ConfidenceAnnotation) is additive; all AI outputs are attributed and reviewer-controlled - Usage: reference implementation running on IHP v1.5 + PostgreSQL; `devenv up` to start --- ## How It Fits - Upstream dependencies: hub-core (for base models, domain/capability registration, MCP tools) — see CUST-WP-0025 - Downstream consumers: dev-hub, ops-hub, fin-hub — any hub with an operator-facing surface - Often used with: kaizen-agentic (agent-assist module), state-hub (decision records, requirement linkage) --- ## Terminology - Preferred terms: Widget, Widget Envelope, Interaction Event, Annotation, Requirement Candidate, Decision Record, Outcome Signal - Also known as: IHF, inter-hub - Potentially confusing terms: "Hub" here = bounded domain of responsibility (Dev Hub, Ops Hub, etc.) — not the GitHub feature; "Widget" = governed semantic unit, not a visual component library widget --- ## Related / Overlapping Repositories - `the-custodian` — provides state-hub (decision records, workstreams) that IHF governance ledger will integrate with - `ops-bridge` — tunnel connectivity for remote hub surfaces - `kaizen-agentic` — agent personas that map to IHF's Agent Integration Module (§9.8) - `hub-core` — planned shared base package that IHF will depend on for domain/capability plumbing --- ## Getting Oriented - Start with: `specs/InteractionHubFrameworkSpecification_v0.1.md` — the full IHF spec (19 sections) - Key files / directories: `specs/` (specifications), root `SCOPE.md` (this file) - Entry points: read IHF spec §6 (Key Concepts), §9 (Core Modules), §14 (Phased Implementation Plan) --- ## Provided Capabilities ```capability type: framework title: Governed interaction substrate description: Provides widget registry, interaction event capture, annotation, and requirements distillation for hub-based AI systems. keywords: [widget, interaction, feedback, annotation, requirements, governance, traceability] ``` ```capability type: specification title: IHF specification and artifact model description: Canonical artifact types and traceability chain from Widget → InteractionEvent → RequirementCandidate → DecisionRecord → OutcomeSignal. keywords: [spec, artifact, traceability, widget, decision, outcome] ``` --- ## Notes Phase 0 (specification), Phase 1 (Minimal Interaction Core), Phase 2 (Structured Feedback and Triage), and Phase 3 (Governance and Decision Linkage) are complete. Phase 4 target: Outcome Signals — DeploymentRecord, ObservedOutcome, and automated gap detection closing the traceability chain. The spec is intentionally broader than the first three implementations — IHP is the reference technology for Phases 1–3, but the framework is designed to survive UI technology changes (§12.7, §Phase 6).