generated from coulomb/repo-seed
Bernd Worsch
9265ca2d9c
Implements the final phase of the IHF v0.1 specification: - WidgetOwnership: delegated ownership registry (local/delegated/global), append-only audit artefacts, ownership badge on widget show page - HubRoutingRule + RoutingEngine: priority-ordered inter-hub routing engine; null-inclusive category/widget-type matching; RouteNowAction for manual re-evaluation; RoutedCandidates view per hub - FederatedPolicyOverlay: draft → active → retired lifecycle; activated overlays are immutable (same pattern as Phase 6 contracts); policy compliance dashboard with decision coverage metrics - StewardshipRole: named governance roles per hub; point-in-time revocation pattern; hub and ops-board integration - ArchiveRecord + is_archived: soft-delete on widgets; lineage inspector traces full traceability chain (Widget → Events → Annotations → Candidates → Requirements → Decisions → Deployments → Signals + ArchiveRecord) - FederatedGovernanceDashboard: 5-panel autoRefresh org-wide governance view (ownership coverage, routing activity, policy compliance, stewardship coverage, archive activity) Schema: widget_ownerships, hub_routing_rules, federated_policy_overlays, stewardship_roles, archive_records; ALTER widgets ADD is_archived; ALTER requirement_candidates ADD routed_to_hub_id Migration: 1743638400-ihf-phase8-federated-hub-maturity.sql Tests: Phase 8 integration tests appended to Test/Integration.hs Docs: docs/phase8-summary.md; SCOPE.md updated to Phase 8 complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
129 lines
6.9 KiB
Markdown
129 lines
6.9 KiB
Markdown
# 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 — federated hub maturity implemented; IHF v0.1 spec fully 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); 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
|
||
- 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).
|