generated from coulomb/repo-seed
Bernd Worsch
54bf0d9357
Some checks failed
Test / test (push) Has been cancelled
- docs/phase1-summary.md: what was built, known limitations, Phase 2 readiness - SCOPE.md: current state updated to Phase 1 complete - All 12 workplan tasks marked done; workplan status set to done Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
68 lines
3.3 KiB
Markdown
68 lines
3.3 KiB
Markdown
# 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.
|