Files

Test / test (push) Has been cancelled

Details

feat(P5): IHF Phase 5 complete — agent-assisted distillation

Adds bounded AI support to the IHF governance loop. All AI outputs are
attributed (model_ref), reviewable (AgentReviewRecord), and reversible.
No autonomous decisions; no silent requirement promotion.

- T01: Schema — agent_proposals, agent_review_records,
  confidence_annotations (migration 1743379200)
- T02: AgentProposalsController (index/show/accept/reject, idempotent
  review guard), global nav "Agent" link
- T03: SummarizeClusterAction — Claude API cluster summary on widget show
- T04: DraftRequirementAction — AI requirement draft; acceptance creates
  RequirementCandidate (human-gated)
- T05: DetectDuplicatesAction — duplicate_flag proposal on candidate show
- T06: DetectPolicySensitivityAction — policy_flag with
  ConfidenceAnnotations per concern scope
- T07: ProposeImplementationAction — impl_proposal from decision show
- T08: AgentAuditDashboardAction — autoRefresh; KPI row, unreviewed queue,
  recent proposals, attribution log matrix
- T09: integration tests, SCOPE.md updated, phase5-summary.md, flake.nix
  adds http-conduit/aeson/string-conversions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-29 15:54:33 +00:00

6.1 KiB

Raw Blame History

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

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

6.1 KiB Raw Blame History Unescape Escape