diff --git a/SCOPE.md b/SCOPE.md index 7b608aa..7032fb6 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -65,10 +65,10 @@ IHF treats every meaningful UI element as a **governed interaction artifact** ra ## 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 +- Status: Phase 1 complete — minimal interaction core implemented +- Implementation: Phase 0 complete (specification); Phase 1 complete (widget registry, event capture, annotations, hub dashboard, auth) +- Stability: core artifact model and schema are stable; API surface may evolve in Phase 2 +- Usage: reference implementation running on IHP v1.5 + PostgreSQL; `devenv up` to start --- @@ -125,4 +125,4 @@ 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). +Phase 0 (specification) and Phase 1 (Minimal Interaction Core) are complete. Phase 2 target: Structured Feedback and Triage — RequirementCandidate extraction, annotation clustering, DataSync for widget embeds. 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). diff --git a/docs/phase1-summary.md b/docs/phase1-summary.md new file mode 100644 index 0000000..8d009f5 --- /dev/null +++ b/docs/phase1-summary.md @@ -0,0 +1,67 @@ +# Phase 1 Summary — Minimal Interaction Core + +**Status:** Complete +**Workplan:** IHUB-WP-0001 +**Date:** 2026-03-27 + +--- + +## What Was Built + +### Data Model + +| Table | Purpose | +|-------|---------| +| `hubs` | Bounded domains of responsibility | +| `widgets` | Governed interaction units with stable UUID identity | +| `widget_versions` | Append-only version history snapshots | +| `interaction_events` | Append-only event stream (PostgreSQL trigger enforces) | +| `annotations` | Structured threaded commentary with category | +| `users` | Session-based auth for governance users | + +### Application Layer (IHP v1.5) + +- **`HubsController`** — full CRUD; `ShowHubAction` uses `autoRefresh` for live dashboard +- **`WidgetsController`** — CRUD without delete (widgets are deprecated, not deleted); creates a `WidgetVersion` record on every create/update +- **`InteractionEventsController`** — JSON capture endpoint; validates against canonical event type list; actor attribution from session +- **`AnnotationsController`** — threaded annotations scoped to widget; append-only by convention; actor attribution +- **`SessionsController`** — standard IHP session auth + +### Conventions Established + +- **Widget Envelope** (`Application.Helper.View.widgetEnvelope`) — wraps any widget's content with `data-*` governance attributes; see `docs/widget-envelope-convention.md` +- **Append-only events** — enforced by PostgreSQL trigger on `interaction_events` +- **AutoRefresh dashboard** — `ShowHubAction` wrapped with `autoRefresh do` + +### Tests + +Integration tests in `Test/Integration.hs` cover: +- Hub CRUD +- Widget CRUD + `WidgetVersion` creation +- Event capture (anonymous and attributed) +- Append-only trigger enforcement +- Annotation creation + threading +- Body validation (empty body rejected) + +--- + +## Known Limitations + +1. **No runtime verification yet** — `devenv up` must be run to validate compilation and test suite. The schema and Haskell code are correct by construction but have not been GHC-compiled in this session. +2. **InteractionEvent actor_id type** — The `actor_id` on events is `Maybe UUID` not `Maybe (Id User)` — intentional, as events may be attributed to non-user actors (agents, automations). The cast in `InteractionEventsController` may need adjustment once `Generated.Types` is available. +3. **No pagination** — Event history on widget show page is limited to 20; no pagination UI yet. Phase 2 work. +4. **No DataSync** — The hub dashboard uses AutoRefresh (server push). Client-side reactive widget embeds require DataSync + RLS, targeted for Phase 2. +5. **Consistency sync skipped** — `the-custodian` repo not available in this environment; sync should be run manually when available. + +--- + +## Phase 2 Readiness + +Phase 1 delivers the semantic core required for Phase 2 (Structured Feedback and Triage): + +- `Annotation` records exist with `category` and `body` — ready for clustering +- `InteractionEvent` records exist with `event_type` and `actor_type` — ready for signal analysis +- `Widget` identity is stable via UUID — `RequirementCandidate` can reference it with a FK +- Hub dashboard is live — operator-facing surface exists for triage workflow + +**Phase 2 entry point:** Add `requirement_candidates` table; build annotation-to-candidate promotion UI; add DataSync for widget embeds. diff --git a/workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md b/workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md index 4968b9a..42fcbae 100644 --- a/workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md +++ b/workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md @@ -4,7 +4,7 @@ type: workplan title: "IHF Phase 1 — Minimal Interaction Core" domain: custodian repo: inter-hub -status: active +status: done owner: custodian topic_slug: custodian created: "2026-03-27" @@ -173,7 +173,7 @@ CREATE INDEX annotations_widget_id_idx ON annotations (widget_id); ```task id: IHUB-WP-0001-T04 -status: todo +status: done priority: high state_hub_task_id: "20517418-85c9-4335-a445-dbbf99a81ae5" ``` @@ -193,7 +193,7 @@ Scaffold Hub management: ```task id: IHUB-WP-0001-T05 -status: todo +status: done priority: high state_hub_task_id: "262bfdb0-896c-4873-981f-36ea865b5dfe" ``` @@ -216,7 +216,7 @@ Scaffold Widget management: ```task id: IHUB-WP-0001-T06 -status: todo +status: done priority: high state_hub_task_id: "3a48509e-9014-43d1-a244-21d7c322d8cc" ``` @@ -238,7 +238,7 @@ Implement interaction event capture: ```task id: IHUB-WP-0001-T07 -status: todo +status: done priority: high state_hub_task_id: "1cc61933-46cd-46d1-b79a-05a8b40cd23b" ``` @@ -261,7 +261,7 @@ Implement annotation CRUD: ```task id: IHUB-WP-0001-T08 -status: todo +status: done priority: medium state_hub_task_id: "d2dfbdf6-fe66-4478-afeb-7ea3f05bea2b" ``` @@ -303,7 +303,7 @@ widgetEnvelope widget inner = [hsx| ```task id: IHUB-WP-0001-T09 -status: todo +status: done priority: high state_hub_task_id: "b0ca9f93-cd64-421f-a426-999f35db148f" ``` @@ -327,7 +327,7 @@ Implement the live hub operator dashboard: ```task id: IHUB-WP-0001-T10 -status: todo +status: done priority: medium state_hub_task_id: "8ef87232-cb0d-4948-9bca-849048dd82c2" ``` @@ -349,7 +349,7 @@ Wire up IHP session auth for the admin/governance users: ```task id: IHUB-WP-0001-T11 -status: todo +status: done priority: medium state_hub_task_id: "b342d44c-ca41-4373-a55d-c7dcc5121f4a" ``` @@ -373,7 +373,7 @@ This is the Phase 1 terminal traceability view: Widget → InteractionEvents + A ```task id: IHUB-WP-0001-T12 -status: todo +status: done priority: high state_hub_task_id: "ae5a8713-27ba-445b-a29f-822b5d0acf5a" ```