inter-hub/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**inter-hub** is the reference implementation of the **Interaction Hub Framework (IHF)** — a governed, observable interaction substrate for hub-based AI-enabled software systems. It treats every UI element as a governed artifact, creating a full traceability chain from rendered widget → user interaction → structured feedback → requirement candidate → decision record → implementation change → observed outcome.

**Current state:** Phases 1–12 complete. IHF v0.2 specification fully implemented. GAAF scorecard at 3.68 (Strong). The full learning loop is closed: Widget → Annotation → RequirementCandidate → Requirement → DecisionRecord → DeploymentRecord → OutcomeSignal → OutcomeCorrelation / PatternPerformanceRecord / InstitutionalKnowledgeEntry → AdaptiveThresholdConfig → improved routing and triage.

For situational context, read `SCOPE.md`. For architecture depth, read `specs/InteractionHubFrameworkSpecification_v0.1.md`.

## Stack

- **IHP** (Integrated Haskell Platform) v1.5 — full-stack Haskell web framework, server-rendered + optional realtime
- **Haskell** (GHC 9.10) — strongly typed, functional
- **PostgreSQL** — canonical datastore, managed via Nix (no manual DB setup)
- **Nix / devenv** — reproducible environment
- **Tailwind CSS** — see `specs/TailwindForInteractionHubs_v0.2.md` for IHF-specific conventions

## Development Setup

Requires Determinate Nix + direnv:

```bash
# One-time environment setup
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh
nix profile install nixpkgs#ihp-new
nix profile add nixpkgs#direnv

# Bootstrap IHP project (Phase 1, Task T01)
ihp-new inter-hub
cd inter-hub
devenv up
```

After `devenv up`:
- App server: `http://localhost:8000`
- IHP IDE + Schema Designer: `http://localhost:8001`

## Key Commands

```bash
devenv up          # Start dev environment (app + postgres + file watchers)
migrate            # Run pending migrations
test               # Run tests (auto-creates temp Postgres DB)
make static/prod.js static/prod.css   # Production asset bundle
deploy-to-nixos production            # NixOS deploy
```

Schema editing: use the IHP IDE at `localhost:8001` or edit `Application/Schema.sql` directly. Code generation via `localhost:8001/Generators`.

## Compilation Layers

IHP compiles ~180 Haskell modules as one GHC target. Module changes are incremental — only changed modules and their dependents recompile. **Never modify Layer 1 during error-fix loops** — a change to `Web/Types.hs` or `Generated/Types.hs` invalidates all 59 controllers and 120 views simultaneously.

```
Layer 1 — stable core (compile once):
  build/Generated/Types.hs      IHP auto-generated from Schema.sql
  Web/Types.hs                  controller type definitions

Layer 2 — helpers (only touch if Layer 1 is clean):
  Application/Helper/*.hs       12 helper modules

Layer 3 — working surface (most errors live here):
  Web/Controller/*.hs           59 controllers
  Web/View/**/*.hs              120 views

Layer 4 — wiring (fix last):
  Web/FrontController.hs
  Web/Routes.hs
```

**Compile tools** (run inside `devenv shell`):

```bash
scripts/compile-check          # full build via ghcid (all layers), log → /tmp/ihub-compile-errors.txt
scripts/compile-check --bg     # same, background-friendly (no colour/title)
scripts/compile-check-core     # Layer 1+2 only — verify clean base before touching Layer 3
```

**GHC compilation mode**: IHP uses `-fbyte-code` — GHCi compiles modules to bytecode in memory, not to persistent `.o` files. The `-fwrite-interface` flag writes `.hi` type-info files alongside source modules; these survive session restarts and skip re-type-checking of unchanged modules. Each ghcid restart regenerates bytecode for the full module graph. Expect 20–60 min on first build; restarts are somewhat faster due to `.hi` caching but not dramatically so. `.hi` files are written next to their source files (e.g. `Web/Controller/Sessions.hi`).

**Error-fix discipline**: fix bottom-up (Layer 1 → 4). Fix one module at a time; wait for ghcid to reload before moving on. See `workplans/IHUB-WP-0016-build-infrastructure-and-error-loop.md` for the full SOP.

## Architecture

### Core Domain Model (Phase 1)

| Entity | Role |
|--------|------|
| `Hub` | Bounded domain of responsibility (Dev Hub, Ops Hub, etc.) |
| `Widget` | Smallest semantically governable interaction unit with stable ID |
| `WidgetVersion` | Version history of widget definitions |
| `InteractionEvent` | Recorded user/agent interaction (viewed, clicked, submitted, etc.) — **append-only** (enforced by PostgreSQL trigger) |
| `Annotation` | Structured comment attached to a widget with category |
| `ViewContext` | Logical location in the UI |
| `CapabilityReference` | Link to hub capability |

### Traceability Chain

```
Widget → InteractionEvent / Annotation
       → RequirementCandidate (Phase 2)
       → DecisionRecord (Phase 3)
       → ImplementationChange → DeploymentRecord → OutcomeSignal
```

### IHP Conventions

- Controllers live in `Web/Controller/`, views in `Web/View/`, types in `Web/Types.hs`
- Schema changes go in `Application/Schema.sql`, then generate with IHP IDE
- Use `AutoRefresh` for operator dashboards (server push on DB change) — not DataSync or Server-Side Components in Phase 1
- See `docs/ihp-ihf-mapping.md` for how IHP capabilities map to IHF requirements

### Widget Envelope

Every rendered widget wraps its HSX in a `widgetEnvelope` helper (Task T08) that injects the stable `widget-id` and `view-context` attributes, enabling client-side event capture without coupling to implementation.

## UI Conventions

All hub interfaces follow the Tailwind layer model in `specs/TailwindForInteractionHubs_v0.2.md`:

```
Semantic Role → Visual Primitive → Tailwind Token → Screen Composition
```

Key rules:
- Every interactive element belongs to a named semantic role (`action-primary`, `nav-item`, `data-cell`, etc.)
- Use spacing rhythm from the spec; do not invent ad-hoc spacing
- State cues (hover, active, disabled, error) follow the defined color roles

## Required Environment Variables

| Variable | Purpose |
|----------|---------|
| `IHP_SESSION_SECRET` | Session encryption key |
| `DATABASE_URL` | Postgres connection string |
| `IHP_BASEURL` | External URL (e.g., `https://example.com`) |
| `IHP_ANTHROPIC_API_KEY` | Anthropic API key for Phase 5 agent-assisted distillation |

## Active Workplan

IHF v0.2 is complete. All 12 phases and the GAAF Compliance Foundation are implemented. No active workplan.

Completed workplans: IHUB-WP-0001 (Phase 1), IHUB-WP-0002 (Phase 2), IHUB-WP-0003 (Phase 3), IHUB-WP-0004 (Phase 4), IHUB-WP-0005 (Phase 5), IHUB-WP-0006 (Phase 6), IHUB-WP-0007 (Phase 7), IHUB-WP-0008 (Phase 8), IHUB-WP-0009 (GAAF Compliance Foundation), IHUB-WP-0010 (Phase 9 — External API Surface and Consumer SDKs), IHUB-WP-0011 (Phase 10 — Hub Registry and Widget Marketplace), IHUB-WP-0012 (Phase 11 — Advanced AI Federation), IHUB-WP-0013 (Phase 12 — Platform Memory and Continuous Learning).

## GAAF Architecture Rules (enforced from IHUB-WP-0009)

These rules apply to all code written after Phase 8 completion:

1. **Type discriminator columns** (`widget_type`, `event_type`, `category`, `policy_scope`) must reference a registry table or carry a CHECK constraint. No bare TEXT for new type discriminators.
2. **New hub-owned types** must be declared in the hub's `HubCapabilityManifest` before use. Register via the Extensions admin UI.
3. **Core tables** (`widgets`, `interaction_events`, `annotations`, `hubs`, and their Phase 1–4 dependents) must not have new columns added without a corresponding update to `/contracts/core/`.
4. **Append-only invariant** on `interaction_events` and `outcome_signals` is permanent. Never propose a migration that removes or bypasses those triggers.

## Key Reference Docs

| File | Purpose |
|------|---------|
| `SCOPE.md` | Situational guide — in/out of scope, terminology, entry points |
| `ARCHITECTURE-LAYERS.md` | GAAF-2026 layer map, scorecard, and compliance status |
| `specs/InteractionHubFrameworkSpecification_v0.1.md` | Full IHF spec (Phases 0–8, risks, design principles) |
| `specs/InteractionHubFrameworkSpecification_v0.2.md` | IHF extension spec (Phases 9–12) with GAAF foundation notes |
| `specs/GoodSoftwareArchitectureFramework_2026.md` | GAAF-2026 standard — the architectural compliance framework |
| `specs/TailwindForInteractionHubs_v0.2.md` | Agent-optimized Tailwind coding guide |
| `contracts/README.md` | Contract catalog — all IHF contracts by layer |
| `docs/domain-hub-extension-guide.md` | How to register a new domain hub (dev, ops, fin, sec) |
| `docs/functional-modules.md` | Functional module maturity register |
| `docs/ihp-overview.md` | IHP v1.5 fundamentals and dev workflow |
| `docs/ihp-data-and-queries.md` | Schema design, auto-generated types, query builder, migrations |
| `docs/ihp-controllers-views-forms.md` | Controller patterns, HSX, forms, validation, auth |
| `docs/ihp-realtime.md` | AutoRefresh vs DataSync vs HTMX decision guide |
| `docs/ihp-ihf-mapping.md` | IHP capability → IHF requirement mapping with schema templates |

## Related Repositories

- `hub-core` — planned shared Haskell library for domain hub bootstrapping; `HubCapabilityManifest` in inter-hub provides the DB-side registration contract until hub-core is implemented
- `the-custodian` — State Hub (decision records, workstreams) that IHF governance integrates with
- Downstream consumers: `dev-hub`, `ops-hub`, `fin-hub`, `sec-hub` — must register via `HubCapabilityManifest` before creating hub-owned type discriminators