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 8 complete + GAAF compliance foundation complete (IHUB-WP-0009) — type registries, extension manifests, architectural contracts, and CI fitness functions in place; ready for Phase 9 (API versioning)
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); Phase 6 complete (EnvelopeEmissionContract, InteractionReportingContract, WidgetAdapterSpec, REST API for cross-framework event submission, annotation launcher JS, React adapter, adapter compatibility dashboard); Phase 7 complete (FrictionScore, BottleneckRecord, HubHealthSnapshot, CrossHubPropagation, friction heatmap, bottleneck dashboard, hub health history, operational review board); Phase 8 complete (WidgetOwnership, HubRoutingRule, FederatedPolicyOverlay, StewardshipRole, ArchiveRecord, delegated ownership, inter-hub routing, federated governance dashboard, lineage inspector)
Stability: core artifact model and schema are stable; Phase 6 contracts and Phase 8 activated policy overlays are immutable once active; native IHP widgets unaffected; Phase 7 observability scores are recomputed (not append-only), health snapshots are append-only; Phase 8 ownership records are soft-audit (no delete), archival is soft-delete (is_archived flag)
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. Note: HubCapabilityManifest in inter-hub now provides the DB-side of capability registration; hub-core (when implemented) will provide the shared Haskell library that domain hubs compile against
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

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

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]

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).

7.2 KiB Raw Blame History Unescape Escape