# 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: concept / early spec
- Implementation: Phase 0 complete (specification written); Phase 1 (Minimal Interaction Core) not yet started
- Stability: spec is draft — artifact model and vocabulary are stable enough for repo creation
- Usage: none yet; reference implementation target is IHP + PostgreSQL

---

## 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 is complete (specification foundation). Implementation begins at Phase 1 (widget registry + interaction event capture). The spec is intentionally broader than the first implementation — IHP is the reference technology for Phase 1, but the framework is designed to survive UI technology changes (§12.7, §Phase 6).