Expand doc DAG inputs and test plan

Author: easel

docs/helix/01-frame/features/F-016-doc-dag.md

@@ -13,7 +13,15 @@ stamps.
   - `depends_on` relationships
   - `prompt` and `inputs`
   - `review` stamps
-- Support an optional graph file for required roots and default prompts.
+- Support an optional graph file for required roots, ID mappings, and default
+  prompts.
+- Resolve dynamic inputs deterministically with the following selectors:
+  - `node:<id>` (explicit node reference)
+  - `refs:<id>` (IDs extracted from a referenced document)
+  - `code_refs:<id>` (ID references in code paths)
+  - `paths:<glob>` (explicit path globs)
+- Provide an ID map for `refs` and `node` resolution (e.g. `US-{id}` to
+  `docs/helix/01-frame/user-stories/US-{id}-*.md`).
 - Compute deterministic content hashes that include frontmatter (excluding
   `dun.review`).
 - Determine stale documents when parent hashes differ from `review.deps`.
@@ -23,6 +31,8 @@ stamps.
   prompt settings or graph defaults.
 - Provide `dun stamp` to update `dun.review` fields in docs.
 - Keep output deterministic for a given repo state.
+- Prompt templates must require a "Gaps & Conflicts" section and instruct the
+  agent to flag unresolved conflicts before proceeding.
 
 ## Inputs
 
@@ -37,6 +47,8 @@ stamps.
   to create it.
 - `dun stamp` updates `dun.review.self_hash` and `dun.review.deps`.
 - Prompt envelopes include parent context inputs by default.
+- Prompt envelopes include resolved requirements, ADRs, and code references
+  when selectors are configured.
 - Results are stable across repeated runs with the same repo state.
 
 ## Traceability

docs/helix/01-frame/user-stories/US-013-doc-dag.md

@@ -8,4 +8,7 @@ stale when upstream requirements change.
 
 - A document with a changed parent is flagged as stale until re-stamped.
 - Required documents missing from the DAG are reported as missing.
-- Dun emits prompts for stale or missing documents with parent context.
+- Dun emits prompts for stale or missing documents with parent context,
+  including related requirements, ADRs, and code references.
+- If conflicts or gaps are detected, the prompt requires they are flagged
+  before proceeding.

docs/helix/02-design/solution-designs/SD-013-doc-dag.md

@@ -16,19 +16,23 @@ which artifacts are missing or stale when upstream docs change.
 
 1. **Frontmatter parsing**: read `dun` blocks from Markdown to register nodes.
 2. **Optional graph defaults**: load `.dun/graphs/*.yaml` for required roots
-   and default prompts for missing docs.
-3. **Hashing**: compute a stable hash of each doc including frontmatter,
+   ID mappings, and default prompts for missing docs.
+3. **Input resolution**: resolve deterministic inputs via selectors:
+   `node:<id>`, `refs:<id>`, `code_refs:<id>`, `paths:<glob>`.
+4. **Hashing**: compute a stable hash of each doc including frontmatter,
    excluding `dun.review`.
-4. **Staleness**: compare parent hashes to `dun.review.deps`.
-5. **Missing detection**: flag required roots or required descendants with no
+5. **Staleness**: compare parent hashes to `dun.review.deps`.
+6. **Missing detection**: flag required roots or required descendants with no
    files.
-6. **Prompting**: emit prompts for missing or stale docs with parent inputs.
-7. **Stamping**: `dun stamp` writes updated review hashes to frontmatter.
+7. **Prompting**: emit prompts for missing or stale docs with parent inputs
+   and require gaps/conflicts to be flagged before implementation steps.
+8. **Stamping**: `dun stamp` writes updated review hashes to frontmatter.
 
 ## Components
 
 - **Frontmatter Reader**: extracts `dun` config and review stamps.
 - **Doc Graph Builder**: builds the DAG from frontmatter + graph defaults.
+- **Input Resolver**: expands selectors into ordered input paths.
 - **Hasher**: computes doc content hashes.
 - **Doc-DAG Check**: emits missing/stale issues and prompts.
 - **Stamp Command**: updates review stamps in files.
@@ -37,14 +41,16 @@ which artifacts are missing or stale when upstream docs change.
 
 1. `dun check` runs `doc-dag` check.
 2. Frontmatter reader registers nodes and dependencies.
-3. Graph builder adds required roots/defaults.
-4. Hasher computes current hashes.
-5. Staleness/missing detection runs.
-6. Prompt envelopes are emitted for actionable nodes.
+3. Graph builder adds required roots/defaults and ID map.
+4. Input resolver expands selectors to a sorted input list.
+5. Hasher computes current hashes.
+6. Staleness/missing detection runs.
+7. Prompt envelopes are emitted for actionable nodes.
 
 ## Data Model
 
 - **Node**: id, path, depends_on, prompt, inputs, review
+- **Input selector**: node, refs, code_refs, paths
 - **Review**: self_hash, deps map, reviewed_at
 - **Edge**: parent -> child from `depends_on`
 
@@ -61,11 +67,13 @@ which artifacts are missing or stale when upstream docs change.
 - New check type: `doc-dag`.
 - New command: `dun stamp`.
 - Optional graph files: `.dun/graphs/*.yaml`.
+- Optional ID map in graph file for resolving refs.
 
 ## Files (Planned)
 
 - `internal/dun/doc_dag.go` (graph build + staleness detection)
 - `internal/dun/frontmatter.go` (parse/serialize frontmatter)
+- `internal/dun/input_resolver.go` (resolve selectors to inputs)
 - `internal/dun/hash.go` (doc hashing)
 - `internal/dun/stamp.go` (stamp logic)
 - `cmd/dun/main.go` (wire `dun stamp`)

docs/helix/03-test/test-plans/TP-013-doc-dag.md

@@ -14,7 +14,8 @@ From US-013:
 |----|---------------------|
 | AC-1 | A document with a changed parent is flagged as stale until re-stamped |
 | AC-2 | Required documents missing from the DAG are reported as missing |
-| AC-3 | Dun emits prompts for stale/missing docs with parent context |
+| AC-3 | Dun emits prompts for stale/missing docs with parent context, related requirements, ADRs, and code references, and requires gaps/conflicts to be flagged |
+| AC-4 | Dynamic input selectors resolve deterministically (node, refs, code_refs, paths) |
 
 ## 2. Existing Test Coverage
 
@@ -39,13 +40,14 @@ No existing tests cover doc-DAG behavior. All acceptance criteria are gaps.
 | GAP-001 | No test for cascade stale detection | P0 | AC-1 |
 | GAP-002 | No test for missing required roots | P0 | AC-2 |
 | GAP-003 | No test for prompt envelope content | P0 | AC-3 |
+| GAP-004 | No test for dynamic input selector resolution | P0 | AC-4 |
 
 ### 3.2 Secondary Gaps (P1)
 
 | Gap ID | Description | Priority | Acceptance Criteria |
 |--------|-------------|----------|---------------------|
-| GAP-004 | No test for `dun stamp` updating review deps | P1 | AC-1 |
-| GAP-005 | No test for deterministic ordering | P1 | AC-3 |
+| GAP-005 | No test for `dun stamp` updating review deps | P1 | AC-1 |
+| GAP-006 | No test for deterministic ordering | P1 | AC-3 |
 
 ## 4. Proposed Test Cases
 
@@ -88,7 +90,19 @@ func TestDocDagMissingRequiredRoot(t *testing.T) {
 }
 ```
 
-#### TC-004: Stamp Updates Review Deps
+#### TC-004: Input Selector Resolution
+**File**: `internal/dun/input_resolver_test.go`
+**Priority**: P0
+**Covers**: AC-4
+
+```go
+func TestInputSelectorsResolveDeterministically(t *testing.T) {
+    // Given: node, refs, code_refs, and paths selectors
+    // Then: resolved inputs are stable, deduped, and ordered
+}
+```
+
+#### TC-005: Stamp Updates Review Deps
 **File**: `internal/dun/stamp_test.go`
 **Priority**: P1
 **Covers**: AC-1
@@ -103,16 +117,16 @@ func TestStampUpdatesReviewDeps(t *testing.T) {
 
 ### 4.2 Integration Tests (Required for Day 1)
 
-#### TC-005: Cascade Stale Detection (End-to-End)
+#### TC-006: Cascade Stale Detection (End-to-End)
 **File**: `internal/dun/engine_test.go`
 **Priority**: P0
-**Covers**: AC-1, AC-3
+**Covers**: AC-1, AC-3, AC-4
 
 ```go
 func TestDocDagCascadeStale(t *testing.T) {
     // Given: fixture repo with parent+child, stamped
     // When: parent changes
-    // Then: child is stale and prompt is emitted
+    // Then: child is stale and prompt is emitted with related inputs
 }
 ```
 
@@ -124,9 +138,10 @@ func TestDocDagCascadeStale(t *testing.T) {
 **Expected**:
 - `doc-dag` check status = warn/fail
 - Issue `stale:helix.architecture`
-- Prompt envelope includes PRD content as input
+- Prompt envelope includes PRD content plus resolved ADR/code refs
+- Prompt requires "Gaps & Conflicts" section
 
-#### TC-006: Missing Required Doc Prompt
+#### TC-007: Missing Required Doc Prompt
 **File**: `internal/dun/engine_test.go`
 **Priority**: P0
 **Covers**: AC-2, AC-3