No threads yet.
|]
+ else [hsx|
+
+ {forEach threads (renderThreadRow allAnnotations)}
+
+ |]}
+ |]
+
+renderThreadRow :: [Annotation] -> AnnotationThread -> Html
+renderThreadRow allAnnotations t =
+ let members = filter (\a -> a.threadId == Just t.id) allAnnotations
+ count = length members
+ severityBreakdown = buildSeverityBreakdown members
+ in [hsx|
+
+ {forEach nonZero (\(s, n) -> renderBarSegment s n total)}
+
+ |]
+
+renderBarSegment :: Text -> Int -> Int -> Html
+renderBarSegment sev n total =
+ let pct = (n * 100) `div` total
+ in [hsx|
+ " h-2 rounded"} style={"width: " <> show pct <> "px"} title={sev <> ": " <> show n}>
+
+|]
+
+barColor :: Text -> Text
+barColor "low" = "bg-gray-300"
+barColor "medium" = "bg-blue-400"
+barColor "high" = "bg-yellow-400"
+barColor "critical" = "bg-red-500"
+barColor _ = "bg-gray-300"
+
+dominantCategoryBadge :: [Annotation] -> Text
+dominantCategoryBadge [] = ""
+dominantCategoryBadge annotations =
+ let cats = map (.category) annotations
+ tally = map (\c -> (c, length $ filter (== c) cats)) (nub cats)
+ best = foldl1 (\(c1, n1) (c2, n2) -> if n2 > n1 then (c2, n2) else (c1, n1)) tally
+ in fst best
+
+severityClass :: Text -> Text
+severityClass "low" = "bg-gray-100 text-gray-500"
+severityClass "medium" = "bg-blue-100 text-blue-700"
+severityClass "high" = "bg-yellow-100 text-yellow-800"
+severityClass "critical" = "bg-red-100 text-red-800 font-semibold"
+severityClass _ = "bg-gray-100 text-gray-500"
diff --git a/Web/View/Annotations/Index.hs b/Web/View/Annotations/Index.hs
index 5eb74c9..1a96fca 100644
--- a/Web/View/Annotations/Index.hs
+++ b/Web/View/Annotations/Index.hs
@@ -43,6 +43,9 @@ renderAnnotation childrenOf a = [hsx|
This annotation has not been escalated yet.
+
+
+ Triage Dashboard
+
Edit
diff --git a/Web/View/Hubs/TriageDashboard.hs b/Web/View/Hubs/TriageDashboard.hs
new file mode 100644
index 0000000..b5b5310
--- /dev/null
+++ b/Web/View/Hubs/TriageDashboard.hs
@@ -0,0 +1,158 @@
+module Web.View.Hubs.TriageDashboard where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data TriageDashboardView = TriageDashboardView
+ { hub :: !Hub
+ , widgets :: ![Widget]
+ , allCandidates :: ![RequirementCandidate]
+ , triageQueue :: ![RequirementCandidate]
+ , recentEscalations :: ![RequirementCandidate]
+ , allAnnotations :: ![Annotation]
+ }
+
+instance View TriageDashboardView where
+ html TriageDashboardView { .. } = [hsx|
+ {autoRefreshMeta}
+
+
Hubs
+
/
+
{hub.name}
+
/
+
Triage Dashboard
+
+ {renderKpi "Open" "open" allCandidates "bg-blue-50 border-blue-200 text-blue-800"}
+ {renderKpi "In Review" "in_review" allCandidates "bg-yellow-50 border-yellow-200 text-yellow-800"}
+ {renderKpi "Accepted" "accepted" allCandidates "bg-green-50 border-green-200 text-green-800"}
+ {renderKpi "Rejected" "rejected" allCandidates "bg-red-50 border-red-200 text-red-800"}
+ {renderKpi "Deferred" "deferred" allCandidates "bg-gray-50 border-gray-200 text-gray-700"}
+
+
+
+
+
+ Triage Queue (Open)
+ {if null triageQueue
+ then [hsx|Queue empty.
|]
+ else [hsx|
+
+ {forEach triageQueue (renderQueueItem widgets)}
+
+ |]}
+
+
+
+
+ Recent Escalations
+ {if null recentEscalations
+ then [hsx|No escalations yet.
|]
+ else [hsx|
+
+ {forEach recentEscalations (renderEscalationItem widgets)}
+
+ |]}
+
+
Annotation Category Breakdown
+ {renderCategoryBreakdown allAnnotations}
+
+ |]
+
+renderKpi :: Text -> Text -> [RequirementCandidate] -> Text -> Html
+renderKpi label status candidates colorClass =
+ let n = length $ filter (\c -> c.status == status) candidates
+ in [hsx|
+ colorClass}>
+
{label}
+
{show n}
+
+
+
+ {maybe "—" (.name) mWidget}
+ ·
+ {c.category}
+
+
+
+ " text-xs px-2 py-0.5 rounded"}>{c.status}
+ {maybe "—" (.name) mWidget}
+
+
{c.title}
+
No annotations yet.
|]
+ else [hsx|
+
+
+ {forEach nonZero (renderCategoryBar total)}
+
+
+
Edit Candidate
+ {renderForm candidate widgets threads}
+
+ |]
+
+renderForm :: RequirementCandidate -> [Widget] -> [AnnotationThread] -> Html
+renderForm candidate widgets threads = formFor candidate [hsx|
+ {(textField #title) { fieldLabel = "Title" }}
+ {(textareaField #description) { fieldLabel = "Description" }}
+ {selectField #sourceWidgetId (widgetOptions widgets)}
+ {selectField #sourceThreadId (threadOptions threads)}
+ {selectField #category categoryOptions}
+ {submitButton}
+|]
+
+widgetOptions :: [Widget] -> [(Text, Text)]
+widgetOptions = map (\w -> (w.name, show w.id))
+
+threadOptions :: [AnnotationThread] -> [(Text, Text)]
+threadOptions threads = ("None", "") : map (\t -> (t.title, show t.id)) threads
+
+categoryOptions :: [(Text, Text)]
+categoryOptions =
+ [ ("Friction", "friction")
+ , ("Defect", "defect")
+ , ("Wish", "wish")
+ , ("Policy Concern", "policy_concern")
+ , ("Documentation Gap", "doc_gap")
+ , ("Trust", "trust")
+ , ("Other", "other")
+ ]
diff --git a/Web/View/RequirementCandidates/Index.hs b/Web/View/RequirementCandidates/Index.hs
new file mode 100644
index 0000000..a0d37cc
--- /dev/null
+++ b/Web/View/RequirementCandidates/Index.hs
@@ -0,0 +1,116 @@
+module Web.View.RequirementCandidates.Index where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data IndexView = IndexView
+ { candidates :: ![RequirementCandidate]
+ , assignments :: ![ReviewerAssignment]
+ , users :: ![User]
+ , widgets :: ![Widget]
+ , mStatusFilter :: !(Maybe Text)
+ }
+
+instance View IndexView where
+ html IndexView { .. } = [hsx|
+
+
Requirement Candidates
+
+
+ {renderFilterPills mStatusFilter}
+
+
+ {if null candidates
+ then [hsx|No candidates found.
|]
+ else [hsx|
+
+
+
+
+ | Title |
+ Widget |
+ Category |
+ Status |
+ Reviewer |
+ Created |
+
+
+
+ {forEach candidates (renderRow assignments users widgets)}
+
+
+
|]
+
+renderRow :: [ReviewerAssignment] -> [User] -> [Widget] -> RequirementCandidate -> Html
+renderRow assignments users widgets c =
+ let mAssignment = find (\ra -> ra.candidateId == c.id) assignments
+ mReviewer = mAssignment >>= \ra -> find (\u -> u.id == ra.userId) users
+ mWidget = find (\w -> w.id == c.sourceWidgetId) widgets
+ in [hsx|
+
+ |
+
+ {c.title}
+
+ |
+
+ {maybe "—" (.name) mWidget}
+ |
+
+ {c.category}
+ |
+
+ " text-xs px-2 py-0.5 rounded"}>{c.status}
+ |
+
+ {maybe "Unassigned" (.name) mReviewer}
+ |
+ {show c.createdAt} |
+
+|]
+
+statusClass :: Text -> Text
+statusClass "open" = "bg-blue-100 text-blue-700"
+statusClass "in_review" = "bg-yellow-100 text-yellow-800"
+statusClass "accepted" = "bg-green-100 text-green-800"
+statusClass "rejected" = "bg-red-100 text-red-800"
+statusClass "deferred" = "bg-gray-100 text-gray-600"
+statusClass _ = "bg-gray-100 text-gray-600"
diff --git a/Web/View/RequirementCandidates/New.hs b/Web/View/RequirementCandidates/New.hs
new file mode 100644
index 0000000..5ac7d6a
--- /dev/null
+++ b/Web/View/RequirementCandidates/New.hs
@@ -0,0 +1,52 @@
+module Web.View.RequirementCandidates.New where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data NewView = NewView
+ { candidate :: !RequirementCandidate
+ , widgets :: ![Widget]
+ , threads :: ![AnnotationThread]
+ }
+
+instance View NewView where
+ html NewView { .. } = [hsx|
+
+
+
New Requirement Candidate
+ {renderForm candidate widgets threads}
+
+ |]
+
+renderForm :: RequirementCandidate -> [Widget] -> [AnnotationThread] -> Html
+renderForm candidate widgets threads = formFor candidate [hsx|
+ {(textField #title) { fieldLabel = "Title" }}
+ {(textareaField #description) { fieldLabel = "Description" }}
+ {selectField #sourceWidgetId (widgetOptions widgets)}
+ {selectField #sourceThreadId (threadOptions threads)}
+ {selectField #category categoryOptions}
+ {submitButton}
+|]
+
+widgetOptions :: [Widget] -> [(Text, Text)]
+widgetOptions = map (\w -> (w.name, show w.id))
+
+threadOptions :: [AnnotationThread] -> [(Text, Text)]
+threadOptions threads = ("None", "") : map (\t -> (t.title, show t.id)) threads
+
+categoryOptions :: [(Text, Text)]
+categoryOptions =
+ [ ("Friction", "friction")
+ , ("Defect", "defect")
+ , ("Wish", "wish")
+ , ("Policy Concern", "policy_concern")
+ , ("Documentation Gap", "doc_gap")
+ , ("Trust", "trust")
+ , ("Other", "other")
+ ]
diff --git a/Web/View/RequirementCandidates/Show.hs b/Web/View/RequirementCandidates/Show.hs
new file mode 100644
index 0000000..9c6d74d
--- /dev/null
+++ b/Web/View/RequirementCandidates/Show.hs
@@ -0,0 +1,176 @@
+module Web.View.RequirementCandidates.Show where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data ShowView = ShowView
+ { candidate :: !RequirementCandidate
+ , widget :: !Widget
+ , triageStates :: ![TriageState]
+ , mAssignment :: !(Maybe ReviewerAssignment)
+ , users :: ![User]
+ , mSourceAnnotation :: !(Maybe Annotation)
+ , mSourceThread :: !(Maybe AnnotationThread)
+ }
+
+instance View ShowView where
+ html ShowView { .. } = [hsx|
+
+
Candidates
+
/
+
{candidate.title}
+
+
+
+
+
+
+
+ " text-xs px-2 py-0.5 rounded font-medium"}>
+ {candidate.status}
+
+
+ {candidate.category}
+
+
+ Widget: {widget.name}
+
+
+
{candidate.description}
+
+
+
+
+
Source
+ {renderSource mSourceAnnotation mSourceThread}
+
+
+
+
+
Triage
+ {renderTriageActions candidate}
+
+
+
+
+
Reviewer
+ {renderReviewerSection candidate mAssignment users}
+
+
+
+
+
Triage History
+ {if null triageStates
+ then [hsx|
No triage actions recorded yet.
|]
+ else [hsx|
+
+ {forEach triageStates renderTriageRow}
+
+ |]}
+
+
+ |]
+
+renderSource :: Maybe Annotation -> Maybe AnnotationThread -> Html
+renderSource Nothing Nothing = [hsx|
No source linked.
|]
+renderSource (Just a) _ = [hsx|
+
+
Source annotation:
+
"{a.body}"
+
+|]
+renderSource Nothing (Just t) = [hsx|
+
+
Source thread:
+
{t.title}
+
+|]
+
+renderTriageActions :: RequirementCandidate -> Html
+renderTriageActions c = [hsx|
+
+ {forEach (allowedNextStatuses c.status) (renderTriageButton c.id)}
+
+|]
+
+allowedNextStatuses :: Text -> [Text]
+allowedNextStatuses "open" = ["in_review"]
+allowedNextStatuses "in_review" = ["accepted", "rejected", "deferred"]
+allowedNextStatuses "deferred" = ["in_review"]
+allowedNextStatuses _ = []
+
+renderTriageButton :: Id RequirementCandidate -> Text -> Html
+renderTriageButton candidateId newStatus = [hsx|
+
+|]
+
+triageButtonClass :: Text -> Text
+triageButtonClass "accepted" = "text-sm px-3 py-1.5 rounded border bg-green-50 border-green-300 text-green-800 hover:bg-green-100"
+triageButtonClass "rejected" = "text-sm px-3 py-1.5 rounded border bg-red-50 border-red-300 text-red-800 hover:bg-red-100"
+triageButtonClass "deferred" = "text-sm px-3 py-1.5 rounded border bg-gray-50 border-gray-300 text-gray-700 hover:bg-gray-100"
+triageButtonClass _ = "text-sm px-3 py-1.5 rounded border bg-yellow-50 border-yellow-300 text-yellow-800 hover:bg-yellow-100"
+
+renderReviewerSection :: RequirementCandidate -> Maybe ReviewerAssignment -> [User] -> Html
+renderReviewerSection candidate mAssignment users = [hsx|
+
+
+ {case mAssignment of
+ Nothing -> [hsx|Unassigned|]
+ Just ra -> [hsx|{reviewerName ra users}|]}
+
+
+
+|]
+
+reviewerName :: ReviewerAssignment -> [User] -> Text
+reviewerName ra users =
+ maybe "Unknown" (.name) (find (\u -> u.id == ra.userId) users)
+
+renderTriageRow :: TriageState -> Html
+renderTriageRow ts = [hsx|
+
+ " text-xs px-2 py-0.5 rounded mt-0.5 shrink-0"}>
+ {ts.status}
+
+
+ {maybe mempty (\n -> [hsx|
{n}
|]) ts.notes}
+
{show ts.changedAt}
+
+|]
+
+statusClass :: Text -> Text
+statusClass "open" = "bg-blue-100 text-blue-700"
+statusClass "in_review" = "bg-yellow-100 text-yellow-800"
+statusClass "accepted" = "bg-green-100 text-green-800"
+statusClass "rejected" = "bg-red-100 text-red-800"
+statusClass "deferred" = "bg-gray-100 text-gray-600"
+statusClass _ = "bg-gray-100 text-gray-600"
diff --git a/docs/phase2-summary.md b/docs/phase2-summary.md
new file mode 100644
index 0000000..0282963
--- /dev/null
+++ b/docs/phase2-summary.md
@@ -0,0 +1,119 @@
+# IHF Phase 2 — Structured Feedback and Triage: Summary
+
+## What Was Built
+
+Phase 2 transforms raw annotations into governable, triageable feedback. It delivers five
+capabilities on top of the Phase 1 interaction core.
+
+### 1. Annotation Severity (`T01`, `T02`)
+
+Every annotation now carries a `severity` value (`low` / `medium` / `high` / `critical`,
+default `medium`). Severity is validated on create, displayed with Tailwind color cues
+(gray / blue / yellow / red), and visible throughout annotation index, show, and thread views.
+
+### 2. Annotation Threads (`T03`)
+
+`AnnotationThread` groups related annotations under a named thread scoped to a widget.
+Operators create threads manually, then assign individual annotations to them via
+`AssignAnnotationToThreadAction`. Thread views show a severity distribution bar and
+dominant category badge, giving a quick signal about the nature of the cluster.
+
+Routes: `/widgets/:widgetId/threads/`
+
+### 3. Requirement Candidates (`T04`, `T05`)
+
+`RequirementCandidate` is the first artifact in the IHF traceability chain beyond raw
+feedback. It can be created:
+
+- **Manually** via `/requirement-candidates/new` (operator selects widget, thread, category).
+- **By escalation** from an annotation detail page — `EscalateAnnotationAction` creates a
+ candidate pre-populated from the annotation and links `source_annotation_id`. Escalation
+ is idempotent: a second click redirects to the existing candidate.
+
+Candidates are never deleted; they can only be rejected or deferred to preserve the audit trail.
+
+### 4. Triage Lifecycle (`T06`)
+
+`TriageState` records every status transition as an append-only audit log. Allowed transitions:
+
+```
+open → in_review
+in_review → accepted | rejected | deferred
+deferred → in_review
+```
+
+`UpdateTriageStatusAction` validates the transition and returns 422 on invalid moves.
+The candidate's `status` column is kept in sync as a denormalised read-optimised cache;
+`triage_states` is the authoritative history.
+
+### 5. Reviewer Assignment & My Queue (`T07`)
+
+`ReviewerAssignment` tracks one reviewer per candidate (unique constraint). Assignment is
+an upsert (old record deleted, new inserted). `MyQueueAction` shows the current user's
+assigned open/in-review candidates.
+
+### 6. Triage Dashboard (`T08`)
+
+`TriageDashboardAction` (on `HubsController`) is wrapped with `autoRefresh do` for live
+push updates. It renders:
+
+- **KPI row** — counts per status (open / in\_review / accepted / rejected / deferred).
+- **Triage queue** — open candidates for the hub's widgets, oldest first.
+- **Recent escalations** — last 20 candidates across the hub.
+- **Category breakdown** — annotation counts per category as a horizontal bar chart.
+
+The `{autoRefreshMeta}` tag is emitted in the view head; morphdom.js handles DOM diffing
+on each WebSocket push.
+
+---
+
+## Files Created / Modified
+
+| Path | Change |
+|------|--------|
+| `Application/Schema.sql` | Added `annotation_threads`, `severity`/`thread_id` on `annotations`, `requirement_candidates`, `triage_states`, `reviewer_assignments` |
+| `Application/Migration/1743120000-ihf-phase2-feedback-triage.sql` | Phase 2 migration |
+| `Web/Types.hs` | Extended `AnnotationsController`; added `AnnotationThreadsController`, `RequirementCandidatesController`, `TriageDashboardAction` |
+| `Web/Routes.hs` | Registered Phase 2 controllers |
+| `Web/Controller/Annotations.hs` | Added `ShowAnnotationAction`, `EscalateAnnotationAction`, severity binding |
+| `Web/Controller/AnnotationThreads.hs` | New |
+| `Web/Controller/RequirementCandidates.hs` | New — full CRUD + triage + reviewer + my-queue |
+| `Web/Controller/Hubs.hs` | Added `TriageDashboardAction` |
+| `Web/View/Annotations/New.hs` | Added severity select |
+| `Web/View/Annotations/Index.hs` | Severity badges, Escalate/Details link |
+| `Web/View/Annotations/Show.hs` | New — annotation detail + escalation UI |
+| `Web/View/AnnotationThreads/{Index,New,Show}.hs` | New |
+| `Web/View/RequirementCandidates/{Index,New,Edit,Show}.hs` | New |
+| `Web/View/Hubs/Show.hs` | Triage Dashboard link |
+| `Web/View/Hubs/TriageDashboard.hs` | New |
+| `Test/Integration.hs` | Phase 2 integration tests |
+| `SCOPE.md` | Updated current state to Phase 2 complete |
+
+---
+
+## Known Limitations
+
+- **No HTMX partial swaps** — triage and escalation actions use full redirects rather than
+ HTMX in-place swaps. The architecture supports HTMX (types are `data`-driven), but the
+ Phase 2 target was to deliver correct behaviour; HTMX enhancement is Phase 3 polish.
+- **No duplicate-detection heuristics** — annotation threading is fully operator-driven.
+ Automated similarity/clustering is Phase 3+ scope per the workplan notes.
+- **My Queue is not linked from the nav** — accessible via `/my-queue`. A nav link should
+ be added in a follow-up.
+- **TriageState is never cleaned up** — by design (append-only audit trail). No archival
+ policy is defined yet.
+
+---
+
+## Phase 3 Readiness
+
+Phase 2 exit criteria are met:
+
+- [x] Feedback volume can be triaged rather than merely stored
+- [x] Multiple related comments can converge into a structured candidate
+- [x] Reviewers can track status and ownership
+
+Phase 3 (Decision Records) can begin. Prerequisites already in place:
+- `RequirementCandidate` with `accepted` status is the input artifact.
+- `source_widget_id`, `source_thread_id`, `source_annotation_id` provide full traceability back.
+- `triage_states` audit trail establishes provenance for any future `DecisionRecord`.
diff --git a/workplans/IHUB-WP-0002-ihf-phase2-structured-feedback-and-triage.md b/workplans/IHUB-WP-0002-ihf-phase2-structured-feedback-and-triage.md
index 93a4a18..15eab32 100644
--- a/workplans/IHUB-WP-0002-ihf-phase2-structured-feedback-and-triage.md
+++ b/workplans/IHUB-WP-0002-ihf-phase2-structured-feedback-and-triage.md
@@ -4,7 +4,7 @@ type: workplan
title: "IHF Phase 2 — Structured Feedback and Triage"
domain: custodian
repo: inter-hub
-status: active
+status: done
owner: custodian
topic_slug: custodian
created: "2026-03-28"
@@ -57,7 +57,7 @@ Reference: `docs/ihp-overview.md`, `docs/ihp-data-and-queries.md`,
```task
id: IHUB-WP-0002-T01
-status: todo
+status: done
priority: high
state_hub_task_id: "eb267a9e-7e80-4913-b7a3-7f5adb04a0f2"
```
@@ -80,7 +80,7 @@ Generate IHP types via the IDE code generator.
```task
id: IHUB-WP-0002-T02
-status: todo
+status: done
priority: high
state_hub_task_id: "fdcbf823-484e-4f0f-a0ca-28f9222520af"
```
@@ -99,7 +99,7 @@ with correct color coding in list and show views.
```task
id: IHUB-WP-0002-T03
-status: todo
+status: done
priority: high
state_hub_task_id: "35b989a0-5e2a-4300-990b-f43d67de0727"
```
@@ -118,7 +118,7 @@ thread; thread list shows per-thread aggregates.
```task
id: IHUB-WP-0002-T04
-status: todo
+status: done
priority: high
state_hub_task_id: "4eb2a51c-1b3f-4b36-b945-6bfb14c2e680"
```
@@ -138,7 +138,7 @@ render correctly.
```task
id: IHUB-WP-0002-T05
-status: todo
+status: done
priority: high
state_hub_task_id: "5c3a154b-38e0-4e40-9e97-57aae1dbc95d"
```
@@ -157,7 +157,7 @@ action; escalated annotations show a visual marker.
```task
id: IHUB-WP-0002-T06
-status: todo
+status: done
priority: high
state_hub_task_id: "cd8c3ef1-e0f7-435f-ae20-e0760df5da83"
```
@@ -176,7 +176,7 @@ full history visible on candidate show page.
```task
id: IHUB-WP-0002-T07
-status: todo
+status: done
priority: medium
state_hub_task_id: "3dc9bfdb-06d0-48a5-8973-2e39c6e0f78a"
```
@@ -195,7 +195,7 @@ for the logged-in reviewer.
```task
id: IHUB-WP-0002-T08
-status: todo
+status: done
priority: high
state_hub_task_id: "82498422-1626-4479-9daa-3d7c7e088d8e"
```
@@ -214,7 +214,7 @@ triage status change without page reload.
```task
id: IHUB-WP-0002-T09
-status: todo
+status: done
priority: high
state_hub_task_id: "935de4d7-867f-49aa-bddf-6ff9435215de"
```
diff --git a/workplans/IHUB-WP-0003-ihf-phase3-governance-and-decision-linkage.md b/workplans/IHUB-WP-0003-ihf-phase3-governance-and-decision-linkage.md
new file mode 100644
index 0000000..2fb8410
--- /dev/null
+++ b/workplans/IHUB-WP-0003-ihf-phase3-governance-and-decision-linkage.md
@@ -0,0 +1,350 @@
+---
+id: IHUB-WP-0003
+type: workplan
+title: "IHF Phase 3 — Governance and Decision Linkage"
+domain: inter_hub
+repo: inter-hub
+status: active
+owner: custodian
+topic_slug: inter_hub
+created: "2026-03-28"
+updated: "2026-03-28"
+state_hub_workstream_id: "5f201ee3-5922-4bdc-981d-e51db0a24f5e"
+---
+
+# IHF Phase 3 — Governance and Decision Linkage
+
+## Goal
+
+Make the framework governance-capable rather than feedback-capable only. Phase 2
+established structured, triageable feedback and requirement candidates. Phase 3
+promotes accepted candidates into formal Requirements, records the decisions that
+act on them, links decisions to policy constraints and implementation work items,
+and surfaces the resulting governance audit trail per hub.
+
+## Background
+
+Phase 1 (IHUB-WP-0001) delivered the Minimal Interaction Core. Phase 2
+(IHUB-WP-0002) delivered Structured Feedback and Triage — annotation severity,
+annotation threads, requirement candidates, triage lifecycle, reviewer assignment,
+and triage dashboard. All Phase 2 exit criteria are met.
+
+Phase 3 is the third of eight phases in the IHF specification
+(`specs/InteractionHubFrameworkSpecification_v0.1.md`, §14 Phase 3). It closes
+the central traceability chain:
+
+```
+Widget → InteractionEvent / Annotation
+ → RequirementCandidate (Phase 2)
+ → [accepted] → Requirement
+ → DecisionRecord ← PolicyReference
+ → ImplementationChangeReference
+ → DeploymentRecord → OutcomeSignal (Phase 4+)
+```
+
+**Technology stack:** IHP v1.5 (Haskell, Nix), PostgreSQL, AutoRefresh
+(governance dashboard), IHP forms (CRUD). Outcome immutability enforced at the
+controller level (no update after creation).
+
+Reference: `docs/ihp-overview.md`, `docs/ihp-data-and-queries.md`,
+`docs/ihp-controllers-views-forms.md`, `docs/ihp-realtime.md`.
+
+## Phase 3 Exit Criteria (from IHF spec §14 Phase 3)
+
+- The system can explain why a requirement was or was not acted upon
+- Governance records are linked to observed interaction issues (full traceability)
+- Decision history is inspectable per hub
+
+## Data Artifacts Introduced (Phase 3)
+
+`Requirement`, `DecisionRecord`, `PolicyReference`, `ImplementationChangeReference`
+
+Also extends: `RequirementCandidate` (adds `requirement_id` back-reference)
+
+---
+
+## Tasks
+
+### T01 — Schema: DecisionRecord, PolicyReference, Requirement, ImplementationChangeReference
+
+```task
+id: IHUB-WP-0003-T01
+status: todo
+priority: high
+state_hub_task_id: "829b1121-bde6-4d8e-8c82-2a2e2064f520"
+```
+
+Add Phase 3 tables to `Application/Schema.sql` and write migration:
+
+```sql
+CREATE TABLE requirements (
+ id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+ title TEXT NOT NULL,
+ description TEXT NOT NULL,
+ source_candidate_id UUID NOT NULL REFERENCES requirement_candidates(id) ON DELETE RESTRICT,
+ status TEXT NOT NULL DEFAULT 'active',
+ created_by UUID REFERENCES users(id),
+ created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX requirements_source_candidate_id_idx ON requirements (source_candidate_id);
+
+CREATE TABLE decision_records (
+ id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+ title TEXT NOT NULL,
+ rationale TEXT NOT NULL,
+ outcome TEXT NOT NULL,
+ requirement_id UUID REFERENCES requirements(id) ON DELETE SET NULL,
+ candidate_id UUID REFERENCES requirement_candidates(id) ON DELETE SET NULL,
+ decided_by UUID REFERENCES users(id),
+ decided_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
+ notes TEXT,
+ created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX decision_records_outcome_idx ON decision_records (outcome);
+CREATE INDEX decision_records_requirement_id_idx ON decision_records (requirement_id);
+
+CREATE TABLE policy_references (
+ id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+ decision_id UUID NOT NULL REFERENCES decision_records(id) ON DELETE CASCADE,
+ policy_scope TEXT NOT NULL,
+ constraint_note TEXT,
+ created_by UUID REFERENCES users(id),
+ created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX policy_references_decision_id_idx ON policy_references (decision_id);
+
+CREATE TABLE implementation_change_references (
+ id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+ decision_id UUID NOT NULL REFERENCES decision_records(id) ON DELETE CASCADE,
+ work_item_ref TEXT NOT NULL,
+ system TEXT NOT NULL DEFAULT 'github',
+ linked_by UUID REFERENCES users(id),
+ linked_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX impl_change_refs_decision_id_idx ON implementation_change_references (decision_id);
+
+-- Back-reference: track which candidate was promoted to a requirement
+ALTER TABLE requirement_candidates ADD COLUMN requirement_id UUID REFERENCES requirements(id) ON DELETE SET NULL;
+```
+
+- Valid `decision_records.outcome` values: `accepted`, `rejected`, `deferred`, `split`, `merged`, `reframed`
+- Valid `policy_references.policy_scope` values: `internal`, `external`, `regulatory`, `contractual`, `architectural`
+- Valid `requirements.status` values: `active`, `superseded`, `withdrawn`
+- Verify Haskell types are generated correctly
+
+**Exit criteria:** `migrate` runs cleanly; all Phase 3 types available in GHCi.
+
+---
+
+### T02 — Requirement promotion: RequirementCandidate → Requirement
+
+```task
+id: IHUB-WP-0003-T02
+status: todo
+priority: high
+state_hub_task_id: "9d1edd55-628c-4354-82c3-2bf273f1b827"
+```
+
+1. Add `PromoteToRequirementAction { candidateId }` (POST from candidate show page)
+2. Validate: candidate must have `status = 'accepted'`; return 422 with message otherwise
+3. Idempotent: if `candidate.requirement_id` already set, redirect to existing requirement
+4. On promotion: create `Requirement` record, set `candidate.requirement_id`
+5. Scaffold `RequirementsController`: index, show (no new/create — requirements come from promotion only)
+6. Show page: title, description, source candidate link, linked decision (if any), status badge
+7. Index: table with status, source candidate, linked decision, created_at
+
+**Exit criteria:** Accepted candidates can be promoted once; second promotion redirects; requirement visible in index and show.
+
+---
+
+### T03 — DecisionRecord controller and views
+
+```task
+id: IHUB-WP-0003-T03
+status: todo
+priority: high
+state_hub_task_id: "171b38ab-c6e7-4b0e-94c0-ebc35f07488a"
+```
+
+1. Scaffold `DecisionRecordsController`
+2. Actions: index, show, new, create, edit, update (no delete)
+3. Fields: `title`, `rationale` (textarea), `outcome` (select), `decidedBy` (user select), `notes` (optional textarea)
+4. Index view: table with outcome badge, linked requirement title, decided_by name, decided_at; filterable by outcome
+5. Show view: full detail + linked requirement + policy references section + implementation refs section + actor attribution
+
+**Exit criteria:** Decision records can be created manually, listed, filtered, and viewed with full context.
+
+---
+
+### T04 — Candidate → Decision linkage action
+
+```task
+id: IHUB-WP-0003-T04
+status: todo
+priority: high
+state_hub_task_id: "eb45a76b-fd75-4a6c-bec6-e47095d5fa36"
+```
+
+1. Add "Create Decision" button on `RequirementCandidate` show page (requires `status = 'accepted'`)
+2. `LinkToDecisionAction { candidateId }` (POST): creates a `DecisionRecord` pre-populated from candidate
+ - `title` = candidate title
+ - `rationale` seeded from candidate description
+ - `candidateId` set on the decision record
+ - If a promoted `Requirement` exists, set `requirementId` on the decision too
+3. Idempotent: if decision already linked to this candidate, redirect to existing decision
+4. Show "Linked Decision →" on candidate show page after linkage
+
+**Exit criteria:** Single-click decision creation from an accepted candidate; idempotent; link visible on candidate show page.
+
+---
+
+### T05 — PolicyReference: link decisions to policy scope
+
+```task
+id: IHUB-WP-0003-T05
+status: todo
+priority: medium
+state_hub_task_id: "4ef86992-d35e-4f62-a601-bd19e3ef63d3"
+```
+
+1. `AddPolicyReferenceAction { decisionId }` (POST from decision show page)
+2. Fields: `policyScope` (select: internal/external/regulatory/contractual/architectural), `constraintNote` (optional)
+3. Multiple policy refs per decision allowed
+4. List policy refs on decision show page: scope badge + constraint note + created_at
+5. Delete: `DeletePolicyReferenceAction` — policy refs may be removed (they are editorial, not audit-critical)
+
+**Exit criteria:** Policy references can be added and removed from decisions; multiple refs per decision supported.
+
+---
+
+### T06 — ImplementationChangeReference: link decisions to work items
+
+```task
+id: IHUB-WP-0003-T06
+status: todo
+priority: medium
+state_hub_task_id: "eac1baf2-9df7-48fd-880e-68d07e22a337"
+```
+
+1. `AddImplementationRefAction { decisionId }` (POST from decision show page)
+2. Fields: `workItemRef` (free text — e.g. `#1234`, `PROJ-456`), `system` (select: github/linear/jira/other)
+3. List refs on decision show page: system badge + ref text + linked_at
+4. No external API calls — refs are manual pointers only
+5. Delete: `DeleteImplementationRefAction` — refs are editorial, not audit-critical
+
+**Exit criteria:** Implementation refs can be added and removed; multiple refs per decision; no external API integration required.
+
+---
+
+### T07 — Decision outcomes: full outcome vocabulary
+
+```task
+id: IHUB-WP-0003-T07
+status: todo
+priority: high
+state_hub_task_id: "eaa425b3-42a7-4498-8aa6-1610959ce16b"
+```
+
+1. Validate outcome on create against allowed set: `accepted`, `rejected`, `deferred`, `split`, `merged`, `reframed`
+2. Outcome is **immutable** after creation — `UpdateDecisionRecordAction` may not change `outcome`
+3. Color roles per `specs/TailwindForInteractionHubs_v0.2.md`:
+ - `accepted` → green
+ - `rejected` → red
+ - `deferred` → gray
+ - `split` → purple
+ - `merged` → indigo
+ - `reframed` → orange/amber
+4. For `split` / `merged` outcomes: `notes` field should capture related candidate IDs or context
+5. Display outcome badge consistently across index, show, and governance dashboard views
+
+**Exit criteria:** All six outcomes render with correct color; outcome immutable after create; split/merged notes convention documented inline.
+
+---
+
+### T08 — Hub governance audit trail dashboard
+
+```task
+id: IHUB-WP-0003-T08
+status: todo
+priority: high
+state_hub_task_id: "6bd3f8f2-13c1-4f95-a1cf-53a210b8e366"
+```
+
+1. Add `GovernanceDashboardAction { hubId }` to `HubsController` wrapped with `autoRefresh do`
+2. Dashboard panels:
+ - **KPI row**: decision counts by outcome (accepted / rejected / deferred / split / merged / reframed)
+ - **Recent decisions** (last 20): title, outcome badge, widget origin (via requirement → candidate → widget), decided_at
+ - **Traceability coverage**: per widget — ✓/✗ for has annotation, has candidate, has decision
+ - **Open requirements awaiting decision**: requirements with no linked `decision_id`
+3. Link from hub Show page alongside "Triage Dashboard"
+
+**Exit criteria:** Dashboard live-updates on decision/requirement changes. Traceability coverage gives a quick health signal per widget.
+
+---
+
+### T09 — Phase 3 gate: tests, consistency, docs
+
+```task
+id: IHUB-WP-0003-T09
+status: todo
+priority: high
+state_hub_task_id: "6f1a08f1-c114-4a19-bf71-cbb2421171e1"
+```
+
+1. **Integration tests** (`Test/`):
+ - Requirement promotion: accepted candidate → requirement; unaccepted candidate → 422; duplicate → idempotent
+ - Decision create + link to candidate; link to requirement if promoted
+ - PolicyReference add + delete
+ - ImplementationChangeReference add + delete
+ - Outcome immutability: update attempt on outcome field rejected
+ - Governance dashboard: data fetch compiles and returns correct counts
+2. **Consistency sync:**
+ ```bash
+ cd ~/the-custodian && make fix-consistency REPO=inter-hub
+ ```
+ Or via State Hub MCP: `check_repo_consistency(repo_slug="inter-hub", fix=True)`
+3. **Documentation updates:**
+ - Update `SCOPE.md` current state section: Phase 3 complete
+ - Write `docs/phase3-summary.md`: what was built, known limitations, Phase 4 readiness
+4. **Smoke test checklist:**
+ - `devenv up` → clean start
+ - Accept a requirement candidate via triage
+ - Promote to requirement
+ - Create decision linked to candidate
+ - Add policy reference (regulatory)
+ - Add implementation ref (github, `#42`)
+ - Confirm governance dashboard shows decision and traceability coverage
+ - Confirm outcome cannot be changed after creation
+
+**Exit criteria:** All tests pass; consistency sync reports no errors; smoke test completed; SCOPE.md updated.
+
+---
+
+## Phase 3 Dependencies
+
+- Phase 2 schema stable (T01 depends on `requirement_candidates`, `users` from Phase 2)
+- `requirements` before `decision_records` FK reference (T01 ordering)
+- Schema (T01) before all controller work (T02–T08)
+- `Requirement` (T02) before `DecisionRecord` linkage (T04)
+- `DecisionRecord` (T03) before `PolicyReference` (T05), `ImplementationChangeReference` (T06), outcome vocabulary (T07)
+- All feature tasks (T01–T08) before gate (T09)
+
+## Notes
+
+- **Outcome is immutable.** Unlike `TriageState` (which appends rows), `DecisionRecord.outcome`
+ is set at creation and never changed. A wrong decision should be superseded by creating a new
+ decision record with a note referencing the original, not by editing the existing one.
+- **No delete on DecisionRecord or Requirement.** These are audit artifacts. Use `status =
+ 'withdrawn'` on Requirement or `outcome = 'rejected'` on DecisionRecord to express
+ nullification.
+- **PolicyReference and ImplementationChangeReference are editorial** — they may be added
+ and deleted freely. They do not constitute audit trail themselves; the DecisionRecord is
+ the audit artifact.
+- **Traceability coverage (T08)** is a spot-check UI, not an enforced constraint. Phase 4+
+ will introduce automated gap detection via outcome signals.
+- **No state-hub integration in Phase 3.** The `the-custodian` state-hub is a separate system;
+ cross-linking IHF decisions to state-hub decision records is Phase 5+ scope.