inter-hub-haskell/SCOPE.md

# 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 7 complete — advanced observability and operational integration 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); 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)
- Stability: core artifact model and schema are stable; Phase 6 contracts are immutable once active; native IHP widgets unaffected; Phase 7 observability scores are recomputed (not append-only), health snapshots are append-only
- 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).