generated from coulomb/repo-seed
docs(spec): IHF specification v0.2 — Phases 9–12
Extends the framework beyond Phase 8 with four planned phases: - Phase 9: External API Surface and Consumer SDKs (OAuth, OpenAPI, TS/Python SDKs, webhooks) - Phase 10: Hub Registry and Widget Marketplace (pattern library, adoption tracking, governance templates) - Phase 11: Advanced AI Federation (agent registry, model routing, delegation, collective proposals) - Phase 12: Platform Memory and Continuous Learning (outcome correlation, adaptive thresholds, knowledge base) Includes dependency graph, v0.2 risk register additions, and extended success criteria. Status: draft — for review. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
437
specs/InteractionHubFrameworkSpecification_v0.2.md
Normal file
437
specs/InteractionHubFrameworkSpecification_v0.2.md
Normal file
@@ -0,0 +1,437 @@
|
||||
InteractionHubFramework
|
||||
|
||||
*Inter*
|
||||
|
||||
# Interaction Hub Framework (IHF)
|
||||
|
||||
*Formal Specification with Phased Implementation Plan*
|
||||
|
||||
**Version:** 0.2
|
||||
**Status:** Draft Extension Specification
|
||||
**Supersedes:** `InteractionHubFrameworkSpecification_v0.1.md`
|
||||
**Purpose:** Extend the IHF beyond Phase 8 into external platform maturity — public API surface, consumer SDKs, hub marketplace, and advanced AI federation.
|
||||
|
||||
---
|
||||
|
||||
## 1. Definition
|
||||
|
||||
The **Interaction Hub Framework (IHF)** is a platform framework for building **commentable, observable, governable, and evolvable user interaction systems**.
|
||||
|
||||
It provides a stable core for:
|
||||
|
||||
* addressing UI elements as governed platform assets
|
||||
* capturing user feedback and interaction signals in context
|
||||
* transforming observed friction and intent into structured requirements
|
||||
* connecting requirements to decisions, implementations, deployments, and outcomes
|
||||
* supporting multiple evolving UI technologies without losing semantic continuity
|
||||
* federating governance across hub boundaries in multi-team AI factory deployments
|
||||
|
||||
The IHF is intended to serve as the **interaction substrate** of a hub-based AI factory, especially in environments where product development, operations, governance, finance, security, and AI-assisted workflows interact continuously.
|
||||
|
||||
---
|
||||
|
||||
## 2. Design Intent
|
||||
|
||||
The framework is designed to support the following long-term properties:
|
||||
|
||||
**Stable semantic core**
|
||||
UI technologies may change, but interaction semantics, traceability, and governance remain stable.
|
||||
|
||||
**Antifragility**
|
||||
The system should improve through systematically captured friction, confusion, unmet expectations, and emergent user needs.
|
||||
|
||||
**Observability by design**
|
||||
Interaction, feedback, and governance events are first-class operational signals.
|
||||
|
||||
**Governance by design**
|
||||
Requirements, decisions, policy concerns, and implementation consequences remain linked and auditable.
|
||||
|
||||
**Agent compatibility**
|
||||
AI agents should be able to inspect, interpret, propose, implement, review, and monitor changes within explicit boundaries.
|
||||
|
||||
**Framework independence at the edge**
|
||||
Any UI technology that can emit the widget envelope is a first-class participant. The IHF does not mandate a particular frontend stack.
|
||||
|
||||
**Platform composability**
|
||||
The IHF should be consumable by external systems, third-party tooling, and downstream hubs via stable, versioned contracts. Internal governance state must not be a closed silo.
|
||||
|
||||
---
|
||||
|
||||
## 3. Scope
|
||||
|
||||
### In Scope
|
||||
|
||||
* Widget identity, lifecycle governance, and semantic addressability
|
||||
* Interaction event capture and contextual enrichment
|
||||
* Annotation and structured comment threads
|
||||
* 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-framework UI adapter protocol
|
||||
* Operational observability: friction scoring, bottleneck detection, health snapshots
|
||||
* Federated governance: ownership delegation, requirement routing, policy overlays, stewardship, archival
|
||||
* External API surface for third-party and inter-system consumption
|
||||
* Consumer SDKs for common platform integrations
|
||||
* Hub registry and marketplace for reusable widget and governance patterns
|
||||
* Advanced AI federation for multi-model, multi-agent governance workflows
|
||||
|
||||
### 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
|
||||
* Unrestricted autonomous AI decision-making on requirements
|
||||
* Mandatory single UI technology for all hub surfaces
|
||||
* General-purpose data warehouse or business intelligence platform
|
||||
|
||||
---
|
||||
|
||||
## 4. Core Concepts
|
||||
|
||||
*(Unchanged from v0.1 §4 — see `InteractionHubFrameworkSpecification_v0.1.md`)*
|
||||
|
||||
---
|
||||
|
||||
## 5. Phased Implementation Plan
|
||||
|
||||
The v0.1 specification defined Phases 0–8. Phases 0–7 are complete as reference implementation. Phase 8 (Federated Hub Maturity) is in progress.
|
||||
|
||||
This v0.2 specification extends the plan with Phases 9–12.
|
||||
|
||||
### Phase 0 — Concept Foundation *(complete)*
|
||||
### Phase 1 — Minimal Interaction Core *(complete)*
|
||||
### Phase 2 — Structured Feedback and Triage *(complete)*
|
||||
### Phase 3 — Governance and Decision Linkage *(complete)*
|
||||
### Phase 4 — Outcome Observation and Antifragility Loop *(complete)*
|
||||
### Phase 5 — Agent-Assisted Distillation and Suggestion *(complete)*
|
||||
### Phase 6 — Cross-Framework UI Adaptation Layer *(complete)*
|
||||
### Phase 7 — Advanced Observability and Operational Integration *(complete)*
|
||||
### Phase 8 — Federated Hub Maturity *(in progress)*
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — External API Surface and Consumer SDKs
|
||||
|
||||
### Goal
|
||||
|
||||
Make the IHF consumable by systems outside the reference IHP implementation.
|
||||
Phase 8 established federated governance within a single deployment. Phase 9
|
||||
exposes that governance state as a stable, versioned, authenticated REST API and
|
||||
ships consumer SDKs that make integration a day's work rather than a project.
|
||||
|
||||
### Scope
|
||||
|
||||
* Versioned REST API (`/api/v2/`) for all core IHF artifact types
|
||||
* OpenAPI 3.1 specification generated from the live schema
|
||||
* Authentication: OAuth 2.0 client credentials flow (superseding per-hub Bearer tokens)
|
||||
* API key management UI for external consumers
|
||||
* Consumer SDKs: TypeScript/Node, Python
|
||||
* Webhook delivery for interaction events, candidate creation, and decision records
|
||||
* API usage dashboard: request counts, error rates, consumer identity
|
||||
* Rate limiting and quota management per consumer
|
||||
|
||||
### Functional Capabilities
|
||||
|
||||
* External systems can read widget registry, interaction events, annotations,
|
||||
requirement candidates, decisions, deployments, and outcome signals
|
||||
* External systems can submit interaction events and annotations via the API
|
||||
* Downstream hubs can subscribe to governance events via webhooks
|
||||
* SDK consumers get type-safe access to IHF contracts without reading the spec
|
||||
* API consumers are tracked, quotaed, and auditable
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
* All core IHF artifact types are readable via `/api/v2/`
|
||||
* Interaction events and annotations are writable via `/api/v2/`
|
||||
* OpenAPI spec is generated and accurate
|
||||
* TypeScript SDK and Python SDK published (as static files or packages)
|
||||
* Webhook delivery confirmed for at least two event types
|
||||
* API usage dashboard renders correctly
|
||||
* OAuth token flow works end-to-end
|
||||
|
||||
### Data Artifacts Introduced
|
||||
|
||||
`ApiConsumer`, `ApiKey`, `WebhookSubscription`, `WebhookDelivery`
|
||||
|
||||
---
|
||||
|
||||
## Phase 10 — Hub Registry and Widget Marketplace
|
||||
|
||||
### Goal
|
||||
|
||||
Enable reuse of proven widget patterns, governance templates, and hub
|
||||
configurations across deployments. Phase 9 made the IHF externally consumable.
|
||||
Phase 10 makes it composable: hubs and widgets can be discovered, rated,
|
||||
adopted, and evolved as shared platform assets.
|
||||
|
||||
### Scope
|
||||
|
||||
* Hub registry: a catalog of registered hubs with public metadata, capability
|
||||
declarations, and health summaries
|
||||
* Widget pattern library: reusable widget definitions that can be instantiated
|
||||
into any hub
|
||||
* Governance template library: requirement distillation and decision templates
|
||||
that can be cloned across hubs
|
||||
* Widget ratings and adoption tracking: which widgets are in use where, with
|
||||
aggregated friction scores across deployments
|
||||
* Pattern versioning: widget patterns have explicit versions; hubs can pin or
|
||||
follow-latest
|
||||
* Marketplace dashboard: browse, search, and adopt patterns
|
||||
|
||||
### Functional Capabilities
|
||||
|
||||
* Hub operators can publish a widget pattern to the shared library
|
||||
* Hub operators can adopt a published pattern into their hub
|
||||
* Governance templates (requirement categories, decision checklists) can be
|
||||
cloned across hubs
|
||||
* Widget adoption across hubs is tracked for aggregate friction and outcome
|
||||
analysis
|
||||
* Pattern authors receive friction and outcome feedback from all adopter hubs
|
||||
(opt-in anonymised)
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
* Hub registry renders all registered hubs with capability metadata
|
||||
* Widget pattern library lists published patterns with version history
|
||||
* A pattern can be published from one hub and adopted into another
|
||||
* Adoption tracking shows which hubs use which patterns
|
||||
* Governance template cloning works end-to-end
|
||||
* Marketplace dashboard renders search and browse
|
||||
|
||||
### Data Artifacts Introduced
|
||||
|
||||
`WidgetPattern`, `WidgetPatternVersion`, `PatternAdoption`, `GovernanceTemplate`,
|
||||
`GovernanceTemplateClone`
|
||||
|
||||
---
|
||||
|
||||
## Phase 11 — Advanced AI Federation
|
||||
|
||||
### Goal
|
||||
|
||||
Move AI assistance from single-model, single-agent operation to a federated,
|
||||
multi-model, multi-agent architecture. Phase 5 introduced bounded AI support
|
||||
for distillation and suggestion. Phase 11 introduces agent specialisation,
|
||||
model routing, inter-agent delegation, and collective AI governance — while
|
||||
keeping humans firmly in control of final decisions.
|
||||
|
||||
### Scope
|
||||
|
||||
* Agent registry: named, versioned AI agents with declared capabilities and
|
||||
trust levels
|
||||
* Model routing: select model per task type based on cost, capability, and
|
||||
policy
|
||||
* Inter-agent delegation: an agent can spawn or invoke a specialist sub-agent
|
||||
with a bounded scope
|
||||
* Agent collaboration records: when multiple agents contribute to a single
|
||||
proposal, all contributions are attributed
|
||||
* Collective proposal review: proposals that require multi-agent consensus
|
||||
before human review
|
||||
* AI governance policies: per-hub rules controlling which agents may operate,
|
||||
on which artifact types, with what authority
|
||||
* Agent performance tracking: acceptance rate, revision rate, confidence
|
||||
calibration over time
|
||||
|
||||
### Functional Capabilities
|
||||
|
||||
* Hub operators can register and configure specialised agents (triage agent,
|
||||
synthesis agent, policy agent, implementation agent)
|
||||
* Agent tasks are routed to the lowest-cost model that meets capability and
|
||||
policy requirements
|
||||
* A delegating agent can hand off a subtask with a capped token budget and
|
||||
scoped context
|
||||
* All inter-agent delegations are recorded and auditable
|
||||
* Humans can inspect the full provenance of any AI output: which agents
|
||||
contributed, which models were used, in what order
|
||||
* AI governance policies can restrict specific agents to read-only or
|
||||
advisory-only roles per hub
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
* Agent registry lists all registered agents with capability and trust metadata
|
||||
* Model routing selects the correct model for at least three task types
|
||||
* Inter-agent delegation creates an auditable delegation record
|
||||
* Collective proposals show all contributing agents
|
||||
* AI governance policy blocks an out-of-scope agent action
|
||||
* Agent performance dashboard renders acceptance and calibration metrics
|
||||
|
||||
### Data Artifacts Introduced
|
||||
|
||||
`AgentRegistration`, `ModelRoutingPolicy`, `AgentDelegation`,
|
||||
`CollectiveProposal`, `AiGovernancePolicy`, `AgentPerformanceRecord`
|
||||
|
||||
---
|
||||
|
||||
## Phase 12 — Platform Memory and Continuous Learning
|
||||
|
||||
### Goal
|
||||
|
||||
Close the longest feedback loop in the IHF: from deployed outcome signals and
|
||||
accumulated governance history back to improved distillation, better routing,
|
||||
and sharper AI proposals. Phase 12 makes the IHF a learning platform, not
|
||||
merely a record-keeping one.
|
||||
|
||||
### Scope
|
||||
|
||||
* Long-term outcome correlation: connect deployment outcomes to the original
|
||||
requirement and annotation signals that drove them, across quarters
|
||||
* Pattern performance memory: track which widget patterns, governance templates,
|
||||
and routing rules have historically produced good outcomes
|
||||
* Adaptive friction thresholds: friction score weights and bottleneck thresholds
|
||||
adjust based on observed hub-specific outcome data
|
||||
* Institutional knowledge capture: significant decisions, their context, and
|
||||
their outcomes are distilled into a queryable knowledge base
|
||||
* Retroactive lineage enrichment: as new outcomes arrive, earlier records in
|
||||
the traceability chain are enriched with outcome metadata
|
||||
* Learning dashboard: shows what the platform has learned — best-performing
|
||||
patterns, most-predictive signals, longest-value decisions
|
||||
|
||||
### Functional Capabilities
|
||||
|
||||
* The platform can answer "which types of annotation predicted a negative outcome
|
||||
in this hub?"
|
||||
* Widget patterns are ranked by historical outcome quality, not just adoption
|
||||
* Friction thresholds for a hub can be calibrated from its own outcome history
|
||||
* Governance decisions are enriched with outcome summaries when signals arrive
|
||||
* A knowledge base of significant decisions is queryable by agents and operators
|
||||
* The learning dashboard shows platform-level insights with evidence links
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
* Long-term outcome correlation produces at least one actionable hub-specific
|
||||
insight from test data
|
||||
* Pattern performance ranking changes after seeding outcome data
|
||||
* Adaptive thresholds update friction scores after calibration run
|
||||
* Institutional knowledge base is queryable and returns relevant decisions
|
||||
* Retroactive lineage enrichment updates at least one decision record with
|
||||
outcome metadata
|
||||
* Learning dashboard renders all panels with correct evidence links
|
||||
|
||||
### Data Artifacts Introduced
|
||||
|
||||
`OutcomeCorrelation`, `PatternPerformanceRecord`, `AdaptiveThresholdConfig`,
|
||||
`InstitutionalKnowledgeEntry`, `LearningInsight`
|
||||
|
||||
---
|
||||
|
||||
## 6. Revised Phased Summary
|
||||
|
||||
| Phase | Title | Status |
|
||||
|-------|-------|--------|
|
||||
| 0 | Concept Foundation | complete |
|
||||
| 1 | Minimal Interaction Core | complete |
|
||||
| 2 | Structured Feedback and Triage | complete |
|
||||
| 3 | Governance and Decision Linkage | complete |
|
||||
| 4 | Outcome Observation and Antifragility | complete |
|
||||
| 5 | Agent-Assisted Distillation | complete |
|
||||
| 6 | Cross-Framework UI Adaptation | complete |
|
||||
| 7 | Advanced Observability | complete |
|
||||
| 8 | Federated Hub Maturity | in progress |
|
||||
| 9 | External API Surface and Consumer SDKs | planned |
|
||||
| 10 | Hub Registry and Widget Marketplace | planned |
|
||||
| 11 | Advanced AI Federation | planned |
|
||||
| 12 | Platform Memory and Continuous Learning | planned |
|
||||
|
||||
---
|
||||
|
||||
## 7. Dependency Graph (Phases 9–12)
|
||||
|
||||
```
|
||||
Phase 8 (Federated) ──→ Phase 9 (External API)
|
||||
│
|
||||
▼
|
||||
Phase 10 (Marketplace)
|
||||
│
|
||||
Phase 7 (Observability) ──→ Phase 11 (AI Federation)
|
||||
Phase 5 (Agent Assist) ──┘ │
|
||||
▼
|
||||
Phase 12 (Platform Memory)
|
||||
▲
|
||||
Phase 4 (Outcomes) ───────────┘
|
||||
```
|
||||
|
||||
- Phase 9 requires Phase 8 (stable federated schema, OAuth replaces per-hub
|
||||
Bearer tokens)
|
||||
- Phase 10 requires Phase 9 (marketplace API is built on v2 API surface)
|
||||
- Phase 11 requires Phase 5 (agent model) and Phase 7 (observability signals
|
||||
needed for model routing and performance tracking)
|
||||
- Phase 12 requires Phase 4 (outcome signals), Phase 7 (friction/health
|
||||
history), and Phase 11 (agent performance as a learning input)
|
||||
|
||||
---
|
||||
|
||||
## 8. Risks and Failure Modes (v0.2 additions)
|
||||
|
||||
### 8.1 API Surface Becoming a Governance Bypass
|
||||
|
||||
Risk: external consumers write interaction events or annotations without
|
||||
honouring the IHF envelope contract, polluting the governance record.
|
||||
Mitigation: the `/api/v2/` write endpoints validate against the active
|
||||
`InteractionReportingContract` and `EnvelopeEmissionContract`. Writes that
|
||||
fail validation return 422 with contract-referenced errors.
|
||||
|
||||
### 8.2 Marketplace Pattern Divergence
|
||||
|
||||
Risk: adopted widget patterns diverge from their source over time, breaking
|
||||
the aggregate friction and outcome correlation.
|
||||
Mitigation: `PatternAdoption` records the version pinned at adoption time.
|
||||
Pattern authors can issue new versions; adopters choose whether to migrate.
|
||||
Aggregate metrics are version-scoped.
|
||||
|
||||
### 8.3 AI Federation Complexity Outpacing Auditability
|
||||
|
||||
Risk: multi-agent delegation chains become too deep to audit meaningfully.
|
||||
Mitigation: `AgentDelegation` has a max depth field enforced at creation time
|
||||
(default: 2). Chains deeper than the hub's `AiGovernancePolicy.max_depth` are
|
||||
rejected with an audit record of the refusal.
|
||||
|
||||
### 8.4 Learning Feedback Loops Reinforcing Bias
|
||||
|
||||
Risk: outcome correlation training on biased historical data produces
|
||||
systematically wrong friction weight adjustments.
|
||||
Mitigation: `AdaptiveThresholdConfig` records the data window and sample size
|
||||
used for each calibration. Calibrations below a minimum sample threshold are
|
||||
flagged as `low_confidence` and do not apply automatically.
|
||||
|
||||
### 8.5 Knowledge Base Becoming Stale
|
||||
|
||||
Risk: `InstitutionalKnowledgeEntry` records reflect decisions that were later
|
||||
superseded, misleading agents and operators.
|
||||
Mitigation: entries link to their source `DecisionRecord`. When a decision is
|
||||
superseded (a new decision is linked to the same requirement), the knowledge
|
||||
entry is flagged `superseded` and a new entry is created for the successor.
|
||||
|
||||
---
|
||||
|
||||
## 9. Success Criteria (v0.2 additions)
|
||||
|
||||
The Interaction Hub Framework at v0.2 maturity is successful when:
|
||||
|
||||
* external systems can read and write IHF state via stable, versioned contracts
|
||||
* widget and governance patterns are reusable without copy-paste
|
||||
* multiple AI agents collaborate on proposals without reducing accountability
|
||||
* the platform visibly learns from its own outcome history
|
||||
* hub leaders can make evidence-based decisions about pattern adoption and
|
||||
agent configuration without reading source code
|
||||
* the IHF can be deployed across an organisation with clear ownership,
|
||||
policies, and audit trails at every layer
|
||||
|
||||
---
|
||||
|
||||
## 10. Short Strategic Summary
|
||||
|
||||
The Interaction Hub Framework v0.2 extends the governed interaction substrate
|
||||
into a **composable, federated, learning platform**.
|
||||
|
||||
Where v0.1 asked: *can we make interaction observable and governance auditable?*
|
||||
|
||||
v0.2 asks: *can the platform teach itself, share what it knows, and remain
|
||||
accountable while doing so?*
|
||||
|
||||
The answer depends on making every new capability — API surface, marketplace
|
||||
patterns, AI federation, outcome correlation — subject to the same contract
|
||||
discipline and human oversight that governs the core.
|
||||
|
||||
That continuity of principle is what makes the framework trustworthy at scale.
|
||||
Reference in New Issue
Block a user