refactor check domain model

Author: easel

docs/helix/01-frame/feature-registry.md

@@ -24,3 +24,4 @@ This registry tracks the core Dun features and their current status.
 | F-019 | Installer + self-updater | P1 | Planned | One-line install + `dun update` |
 | F-020 | Generic command checks | P1 | Planned | Command checks + external plugin loading |
 | F-021 | Beads work routing | P1 | Planned | Surface ready Beads tasks in prompts |
+| F-023 | Check domain model | P1 | In progress | Registry-based check lifecycle, summaries, scoring |

docs/helix/01-frame/features/F-023-check-domain-model.md

@@ -0,0 +1,43 @@
+---
+dun:
+  id: F-023
+  depends_on:
+    - helix.prd
+  review:
+    self_hash: 9b5f839c24e68e270c4166652ec89c5334406b462deefe97ac09582d8ae6263e
+    deps:
+      helix.prd: 07d49919dec51a33254b7630622ee086a5108ed5deecd456f7228f03712e699d
+---
+# Feature Spec: F-023 Check Domain Model
+
+## Summary
+
+Make checks a first-class domain model with a consistent lifecycle (discover,
+plan, evaluate, summarize, prompt, score) so Dun can extend and reason about
+checks without special-case code.
+
+## Requirements
+
+- Represent checks as explicit domain objects with shared metadata and
+  type-specific configuration.
+- Provide a registry for check types so execution is data-driven (no monolithic
+  switch statements).
+- Standardize check results with summary, score, prompt metadata, and optional
+  update/freshness signals.
+- Preserve existing CLI behavior and check outputs while improving internal
+  structure.
+- Ensure prompt generation and task summaries remain bounded and deterministic.
+
+## Acceptance Criteria
+
+- Check planning uses a typed registry to decode and run checks.
+- Check results include a summary and score field (optional in output when
+  unset).
+- Check types that detect stale/missing artifacts surface update signals in a
+  consistent shape.
+- Existing checks and plugins continue to run without changes to plugin YAML.
+- `go test ./...` passes.
+
+## Gaps & Conflicts
+
+- None identified.

docs/helix/01-frame/user-stories/US-023-check-domain-model.md

@@ -0,0 +1,23 @@
+---
+dun:
+  id: US-023
+  depends_on:
+    - F-023
+  review:
+    self_hash: 68b0c2dbf86881914c5acbd5cbe3eefc20eee60ec8e0d3539b97a8ac11a53cfa
+    deps:
+      F-023: 9b5f839c24e68e270c4166652ec89c5334406b462deefe97ac09582d8ae6263e
+---
+# US-023: First-Class Check Domain Model
+
+As a maintainer, I want checks to be modeled as first-class domain objects so
+Dun can discover, evaluate, summarize, and score them consistently without
+special-case logic.
+
+## Acceptance Criteria
+
+- Check definitions are normalized into a common domain structure.
+- Check execution is routed through a check type registry.
+- Check results include summary and score fields.
+- Update/freshness signals are available for checks that detect staleness.
+- Existing plugin manifests remain compatible.

docs/helix/02-design/solution-designs/SD-023-check-domain-model.md

@@ -0,0 +1,42 @@
+---
+dun:
+  id: SD-023
+  depends_on:
+    - F-023
+  review:
+    self_hash: 08154ce72da29c20073be694be803ec654134d755e8b877ac69b03d8edd59dd2
+    deps:
+      F-023: 9b5f839c24e68e270c4166652ec89c5334406b462deefe97ac09582d8ae6263e
+---
+# Solution Design: Check Domain Model
+
+## Problem
+
+Check behavior is implemented through a monolithic config structure and a large
+switch statement, making new check types and consistent summarization difficult.
+
+## Goals
+
+- Introduce a clear check lifecycle: discover, plan, evaluate, summarize, prompt,
+  score.
+- Decouple check execution from the engine using a registry of check types.
+- Standardize result metadata without breaking existing outputs.
+
+## Approach
+
+- Keep plugin YAMLs intact, but normalize check definitions into a common
+  structure and decode type-specific configs via a registry.
+- Add a summarizer that sets `summary`, `score`, and optional update signals on
+  check results after evaluation.
+- Keep CLI rendering as a thin adapter over structured results.
+
+## Components
+
+- Check Registry: maps check types to type handlers.
+- Check Definition: normalized metadata shared across types.
+- Type Configs: per-check-type config structs.
+- Summarizer: derives summary/score/update signals from results.
+
+## Open Questions
+
+- None beyond technical design details.

docs/helix/02-design/technical-designs/TD-023-check-domain-model.md

@@ -0,0 +1,59 @@
+---
+dun:
+  id: TD-023
+  depends_on:
+    - US-023
+  review:
+    self_hash: 9522804907a7c19f06e7868543b17c4fb35218c841953b07a058ac5d8360f6c4
+    deps:
+      US-023: 68b0c2dbf86881914c5acbd5cbe3eefc20eee60ec8e0d3539b97a8ac11a53cfa
+---
+# TD-023: Check Domain Model + Registry
+
+## Overview
+
+Implement a registry-based check pipeline with typed configs and a consistent
+result schema that includes summary, score, and update signals.
+
+## Data Model
+
+- `CheckSpec`: raw manifest definition (YAML) used for decoding and plan
+  inspection.
+- `CheckDefinition`: normalized metadata (id, description, phase, priority,
+  conditions, plugin id).
+- `CheckConfig`: type-specific config struct decoded from `CheckSpec`.
+- `CheckResult`: status/signal/detail/issues plus optional `summary`, `score`,
+  and `update`.
+
+## Pipeline
+
+1. Load plugins and build plan from `CheckSpec`.
+2. Decode each `CheckSpec` using the registry into a typed config.
+3. Execute the check handler with `CheckDefinition`, config, and options.
+4. Post-process results with a summarizer (summary + score + update signals).
+
+## Registry Interface
+
+- `Type() string`
+- `Decode(CheckSpec) (CheckConfig, error)`
+- `Run(root, def, config, opts) (CheckResult, error)`
+
+Optional: `Explain(config) CheckExplain` for `dun explain` details.
+
+## Summarization
+
+- Summary: short, deterministic string derived from status + signal + detail.
+- Score: numeric score derived from status (pass > warn > fail/skip).
+- Update: optional structured signal for checks that detect staleness.
+
+## Backwards Compatibility
+
+- Plugin YAML structure stays unchanged.
+- CLI outputs remain compatible; new fields are additive.
+
+## Testing
+
+- Registry dispatch tests for each check type.
+- Config decode tests for representative check types.
+- Summary/score tests for status variants.
+- Full `go test ./...` pass.

docs/helix/03-test/test-plans/TP-023-check-domain-model.md

@@ -0,0 +1,32 @@
+---
+dun:
+  id: TP-023
+  depends_on:
+    - TD-023
+  review:
+    self_hash: cc509d37fd92febd897f7565e61a9da76ecba61c834f57c54c3e9e41fb8fbc26
+    deps:
+      TD-023: 9522804907a7c19f06e7868543b17c4fb35218c841953b07a058ac5d8360f6c4
+---
+# TP-023: Check Domain Model
+
+## Scope
+
+Verify registry-based execution, typed config decoding, summary/score fields,
+update signals, and backward compatibility.
+
+## Acceptance Criteria
+
+| ID | Criteria |
+|----|----------|
+| AC-1 | Registry dispatch runs all existing check types |
+| AC-2 | Typed config decode succeeds for representative check types |
+| AC-3 | Summary/score fields are populated and deterministic |
+| AC-4 | Update signals appear for stale/missing checks |
+| AC-5 | `go test ./...` passes |
+
+## Proposed Tests
+
+- Registry dispatch unit tests per check type.
+- Summarizer tests for each status value.
+- Golden test for `dun check --format=json` to ensure additive fields only.

docs/helix/04-build/implementation-plans/IP-023-check-domain-model.md

@@ -0,0 +1,26 @@
+---
+dun:
+  id: IP-023
+  depends_on:
+    - TD-023
+  review:
+    self_hash: 4b2a6fc43b11b206e13e208ea61a36f373a9ef8a2c3b6967e676864333c03ee1
+    deps:
+      TD-023: 9522804907a7c19f06e7868543b17c4fb35218c841953b07a058ac5d8360f6c4
+---
+# IP-023: Implement Check Domain Model
+
+## Steps
+
+1. Introduce `CheckDefinition`, `CheckSpec`, and a `CheckType` registry.
+2. Update engine planning/execution to use the registry.
+3. Create typed config structs for each check type and decode from `CheckSpec`.
+4. Add summary/score/update fields to `CheckResult` and implement summarizer.
+5. Update CLI rendering to prefer summaries and preserve existing output.
+6. Update tests and run `go test ./...`.
+
+## Acceptance
+
+- All existing checks execute with no behavior regressions.
+- Summary/score fields are present and deterministic.
+- Tests pass.

internal/dun/agent.go

@@ -42,7 +42,7 @@ type PromptContext struct {
 	AutomationMode string
 }
 
-func runAgentCheck(root string, plugin Plugin, check Check, opts Options) (CheckResult, error) {
+func runAgentCheck(root string, plugin Plugin, def CheckDefinition, config AgentCheckConfig, opts Options) (CheckResult, error) {
 	mode, err := normalizeAgentMode(opts.AgentMode)
 	if err != nil {
 		return CheckResult{}, err
@@ -52,21 +52,21 @@ func runAgentCheck(root string, plugin Plugin, check Check, opts Options) (Check
 		return CheckResult{}, err
 	}
 
-	envelope, err := buildPromptEnvelope(root, plugin, check, automation)
+	envelope, err := buildPromptEnvelope(root, plugin, def, config, automation)
 	if err != nil {
 		return CheckResult{}, err
 	}
 
 	if mode != "auto" {
-		return promptResult(check, envelope, "agent prompt ready", check.Description), nil
+		return promptResult(def, envelope, "agent prompt ready", def.Description), nil
 	}
 
 	agentCmd := opts.AgentCmd
 	if agentCmd == "" {
 		agentCmd = os.Getenv("DUN_AGENT_CMD")
 	}
 	if agentCmd == "" {
-		return promptResult(check, envelope, "agent not configured", "set --agent-cmd or DUN_AGENT_CMD to run in auto mode"), nil
+		return promptResult(def, envelope, "agent not configured", "set --agent-cmd or DUN_AGENT_CMD to run in auto mode"), nil
 	}
 
 	timeout := opts.AgentTimeout
@@ -84,7 +84,7 @@ func runAgentCheck(root string, plugin Plugin, check Check, opts Options) (Check
 	}
 
 	return CheckResult{
-		ID:     check.ID,
+		ID:     def.ID,
 		Status: resp.Status,
 		Signal: resp.Signal,
 		Detail: resp.Detail,
@@ -117,13 +117,13 @@ func normalizeAutomationMode(mode string) (string, error) {
 	}
 }
 
-func promptResult(check Check, envelope PromptEnvelope, signal string, detail string) CheckResult {
+func promptResult(def CheckDefinition, envelope PromptEnvelope, signal string, detail string) CheckResult {
 	next := envelope.Callback.Command
 	if next == "" {
-		next = fmt.Sprintf("dun respond --id %s --response -", check.ID)
+		next = fmt.Sprintf("dun respond --id %s --response -", def.ID)
 	}
 	return CheckResult{
-		ID:     check.ID,
+		ID:     def.ID,
 		Status: "prompt",
 		Signal: signal,
 		Detail: detail,
@@ -132,13 +132,13 @@ func promptResult(check Check, envelope PromptEnvelope, signal string, detail st
 	}
 }
 
-func buildPromptEnvelope(root string, plugin Plugin, check Check, automationMode string) (PromptEnvelope, error) {
-	inputs, err := resolveInputs(root, check.Inputs)
+func buildPromptEnvelope(root string, plugin Plugin, def CheckDefinition, config AgentCheckConfig, automationMode string) (PromptEnvelope, error) {
+	inputs, err := resolveInputs(root, config.Inputs)
 	if err != nil {
 		return PromptEnvelope{}, err
 	}
 
-	promptText, schemaText, err := renderPromptText(plugin, check, inputs, automationMode)
+	promptText, schemaText, err := renderPromptText(plugin, config, def.ID, inputs, automationMode)
 	if err != nil {
 		return PromptEnvelope{}, err
 	}
@@ -150,21 +150,21 @@ func buildPromptEnvelope(root string, plugin Plugin, check Check, automationMode
 
 	return PromptEnvelope{
 		Kind:           "dun.prompt.v1",
-		ID:             check.ID,
-		Title:          check.Description,
-		Summary:        check.Description,
+		ID:             def.ID,
+		Title:          def.Description,
+		Summary:        def.Description,
 		Prompt:         promptText,
 		Inputs:         inputPaths,
 		ResponseSchema: schemaText,
 		Callback: PromptCallback{
-			Command: fmt.Sprintf("dun respond --id %s --response -", check.ID),
+			Command: fmt.Sprintf("dun respond --id %s --response -", def.ID),
 			Stdin:   true,
 		},
 	}, nil
 }
 
-func renderPromptText(plugin Plugin, check Check, inputs []PromptInput, automationMode string) (string, string, error) {
-	tmplText, err := loadPromptTemplate(plugin, check.Prompt)
+func renderPromptText(plugin Plugin, config AgentCheckConfig, checkID string, inputs []PromptInput, automationMode string) (string, string, error) {
+	tmplText, err := loadPromptTemplate(plugin, config.Prompt)
 	if err != nil {
 		return "", "", err
 	}
@@ -176,7 +176,7 @@ func renderPromptText(plugin Plugin, check Check, inputs []PromptInput, automati
 
 	var buf bytes.Buffer
 	ctx := PromptContext{
-		CheckID:        check.ID,
+		CheckID:        checkID,
 		Inputs:         inputs,
 		AutomationMode: automationMode,
 	}
@@ -185,8 +185,8 @@ func renderPromptText(plugin Plugin, check Check, inputs []PromptInput, automati
 	}
 
 	var schemaText string
-	if check.ResponseSchema != "" {
-		loaded, err := loadPromptTemplate(plugin, check.ResponseSchema)
+	if config.ResponseSchema != "" {
+		loaded, err := loadPromptTemplate(plugin, config.ResponseSchema)
 		if err != nil {
 			return "", "", err
 		}