inter-hub/docs/phase5-summary.md

Phase 5 Summary — Agent-Assisted Distillation and Suggestion

Workplan: IHUB-WP-0005 Completed: 2026-03-29 Phase: 5 of 8 in the IHF specification

---

What Was Built

Phase 5 introduces bounded AI support into the IHF governance loop. All AI outputs are attributed (model_ref recorded), reviewable (AgentReviewRecord), and reversible (proposals can be rejected). No autonomous final decisions. No silent requirement promotion.

T01 — Schema

Three new tables:

• agent_proposals — stores every AI-generated output (summary, requirement_draft, duplicate_flag, policy_flag, impl_proposal). Status: pending → accepted | rejected | superseded. model_ref and optional confidence on every row.
• agent_review_records — one per proposal (UNIQUE on proposal_id). Human decision: accepted | rejected | modified. Idempotent: second accept/reject returns "Already reviewed".
• confidence_annotations — per-dimension breakdown of AI confidence (accuracy, relevance, completeness, policy_alignment). Linked to proposal via FK.

T02 — AgentProposalsController

AgentProposalsAction (index filterable by type and status), ShowAgentProposalAction, AcceptProposalAction, RejectProposalAction. Proposals are immutable audit artifacts — no update/delete. Global nav "Agent" link added.

T03 — Cluster Summarization

SummarizeClusterAction (POST from widget show page). Fetches last 20 annotations + threads, calls claude-sonnet-4-6 with a factual distillation prompt (max_tokens=300), creates a summary AgentProposal. "Summarize Feedback" button on widget show page. API errors produce a user-visible flash message.

T04 — AI-Drafted Requirement Candidate

DraftRequirementAction (POST from widget show page, gated on ≥ 3 annotations). Prompts Claude for JSON {title, description}. Creates a requirement_draft AgentProposal. On AcceptProposalAction for a requirement_draft: parses JSON and creates a RequirementCandidate with category="friction", status="open". No candidate is created without human acceptance.

T05 — Duplicate Candidate Detection

DetectDuplicatesAction (POST from candidate show page). Sends target candidate + all others to Claude, requests JSON {duplicates: [{id, reason}]}. Creates a duplicate_flag AgentProposal. Informational only — no automated merging.

T06 — Policy-Sensitive Issue Detection

DetectPolicySensitivityAction (POST from candidate show page). Sends candidate + widget policy_scope context to Claude, requests JSON {concerns: [{scope, note}], severity}. Creates a policy_flag AgentProposal with numeric confidence (low=0.3, medium=0.6, high=0.9). Creates one ConfidenceAnnotation per concern scope. Amber badge if concerns, green if clean.

T07 — Implementation Path Proposal

ProposeImplementationAction (POST from decision show page). Fetches decision + requirement + existing impl refs, prompts Claude for JSON {proposals: [{work_item_ref, system, rationale}]}. Creates an impl_proposal AgentProposal. "Propose Implementation" button on decision show page.

T08 — Agent Audit Dashboard

AgentAuditDashboardAction wrapped with autoRefresh do. Five panels:

1. KPI row: total proposals / pending count / acceptance rate / rejection rate
2. Proposals by type: count per type with color badges
3. Unreviewed queue: pending proposals oldest-first with "Review" links
4. Recent proposals (last 20): type, source widget, status, confidence, age
5. Attribution log: model_ref × proposal_type count matrix

Linked from hub show page (purple "Agent Audit" button).

---

Governance Constraints Upheld

• Attributability: every AgentProposal records model_ref. Reviewers see exactly which model produced the output.
• Human control: no proposal auto-promotes. requirement_draft → RequirementCandidate only after explicit acceptance via AcceptProposalAction.
• Idempotency: UNIQUE (proposal_id) on agent_review_records. Second accept/reject returns "Already reviewed" — no double-review.
• Error isolation: all Claude API calls are wrapped; failures produce a flash message and redirect, never a 500.
• Confidence is optional: AgentProposal.confidence is nullable. Summaries have no numeric score; policy flags derive confidence from severity.

---

Known Limitations

• No streaming: Claude API calls are synchronous within the controller action. For large annotation sets this may cause slow response times. Future work: background job with status polling.
• Confidence annotations for T06 use same score for all dimensions: each concern dimension gets the overall severity score, not a per-dimension score from Claude. A refined prompt could request per-dimension scores.
• Duplicate detection scales linearly: the full candidate list is sent to Claude. For large datasets (>100 candidates) the prompt will be large. Future work: embedding-based pre-filtering.
• No embeddings storage: all intelligence is delegated to the Anthropic API. Phase 5 adds no local model serving or vector store.

---

Phase 6 Readiness

Phase 6 (Cross-Hub Integration) can build on:

• AgentProposal as a structured output artifact that can be routed across hubs
• ConfidenceAnnotation as a per-dimension quality signal for cross-hub filtering
• The attribution log as an audit trail for multi-hub AI operations
• All Phase 1–5 traceability chain intact: Widget → Annotation → Candidate → Decision → Deployment → OutcomeSignal → AgentProposal