docs: refresh helix specs and plans

Author: easel

docs/helix/01-frame/features/F-001-auto-discovery.md

@@ -1,3 +1,13 @@
+---
+dun:
+  id: F-001
+  depends_on:
+    - helix.prd
+  review:
+    self_hash: 1490cef1b15ca48c530d4f0c4eae1e5e9912c5d3a7dfa1aa0343e7c59290dd78
+    deps:
+      helix.prd: 58d3c4be8edb0a0be9d01a3325824c9b350f758a998d02f16208525949c4f1ad
+---
 # Feature Spec: F-001 Auto-Discovery
 
 ## Summary
@@ -7,12 +17,39 @@ manual configuration.
 
 ## Requirements
 
-- Detect Go repositories via `go.mod`.
-- Detect Helix workflow via `docs/helix/`.
-- Produce a deterministic set of checks for the repo state.
+- Discover core checks from repo signals (files and conventions).
+- Detect Go repositories via `go.mod` to enable baseline Go quality checks.
+- Detect Helix workflow via `docs/helix/` to enable doc/gate validation checks.
+- Produce a deterministic set of checks for the same repo state.
+- Require no manual configuration for core discovery.
+
+## Inputs
+
+- Repository root file tree.
+- `go.mod` (Go detection signal).
+- `docs/helix/` (Helix workflow detection signal).
 
 ## Acceptance Criteria
 
-- `dun check` lists checks based on detected repo signals.
+- `dun check` selects Go quality checks when `go.mod` is present.
+- `dun check` selects Helix doc/gate checks when `docs/helix/` is present.
 - Check IDs and ordering are stable across runs for the same repo state.
 - No user configuration is required for core discovery.
+
+## Gaps & Conflicts
+
+- Missing canonical registry of check IDs and their discovery rules (depends on
+  F-003 Plugin System).
+- Missing ordering rules when multiple signals match (priority and grouping).
+- Missing definition of baseline Go quality checks to enable (depends on
+  F-014 Go Quality Checks).
+- Missing definition of how discovery hooks into doc drift detection (depends
+  on F-006 Doc Reconciliation and F-016 Doc DAG).
+- No conflicts identified in the provided inputs.
+
+## Traceability
+
+- Supports PRD goals for "one command that discovers and runs the right
+  checks" and deterministic output.
+- Supports PRD scope for built-in Helix doc validation and baseline Go quality
+  checks by using repo signals for discovery.

docs/helix/01-frame/features/F-002-output-formats.md

@@ -1,3 +1,13 @@
+---
+dun:
+  id: F-002
+  depends_on:
+    - helix.prd
+  review:
+    self_hash: 83b2a3c2ac4e9a760bd04598c3ff9c3ea3504c0f49e8d246cd9a61d540e87898
+    deps:
+      helix.prd: 58d3c4be8edb0a0be9d01a3325824c9b350f758a998d02f16208525949c4f1ad
+---
 # Feature Spec: F-002 Output Formats
 
 ## Summary
@@ -12,12 +22,29 @@ consumption by humans and tools.
 - Provide `--format=json` for structured results.
 - Output is deterministic and stable for a given repo state.
 
+## Inputs
+
+- Check results emitted by `dun check`.
+- Repository state that drives deterministic ordering.
+- PRD goals for deterministic, agent-friendly output formats.
+
 ## Acceptance Criteria
 
 - `dun check` emits prompt envelopes by default when agent checks are present.
 - `dun check --format=llm` prints concise summaries.
 - `dun check --format=json` emits structured JSON output.
 
+## Gaps & Conflicts
+
+- Missing formal schema for the JSON output format (field names, ordering,
+  error model).
+- Missing definition of the prompt envelope structure and how callbacks are
+  encoded for agent checks.
+- Missing length and content guidelines for `--format=llm` summaries.
+- Missing rules for how multi-check results are ordered and grouped across
+  formats.
+- No conflicts identified in the provided inputs.
+
 ## Traceability
 
 - Supports success metrics for time to first output and median run time by

docs/helix/01-frame/features/F-003-plugin-system.md

@@ -1,24 +1,59 @@
+---
+dun:
+  id: F-003
+  depends_on:
+    - helix.prd
+  review:
+    self_hash: 8bbe08567869ffbb1fa3c56eb1af0d585f1918acb50240d7c541a86b4ace030e
+    deps:
+      helix.prd: 58d3c4be8edb0a0be9d01a3325824c9b350f758a998d02f16208525949c4f1ad
+---
 # Feature Spec: F-003 Plugin System
 
 ## Summary
 
-Support manifest-defined checks so Dun can detect and run workflow-specific
-rules (including Helix).
+Provide an extensible plugin system so Dun can ship built-in workflows
+(including Helix doc and gate validation) and add future workflow-specific
+checks while keeping discovery deterministic.
 
 ## Requirements
 
+- Provide an extensible plugin system for future workflows.
+- Include a built-in Helix plugin for documentation and gate validation.
 - Load built-in plugin manifests embedded in the binary.
 - Activate plugins via repo signals (paths/globs).
 - Support check types: rule-set, gates, state-rules, agent prompts.
-- Maintain deterministic check ordering.
+- Maintain deterministic plugin and check ordering.
+
+## Inputs
+
+- PRD goals for an extensible plugin system and built-in Helix plugin.
+- Repository signals used to activate plugins.
+- Built-in plugin manifests shipped with the CLI.
 
 ## Acceptance Criteria
 
 - Helix plugin activates when `docs/helix/` exists.
 - Gate and state rules run without custom config.
 - Agent prompts emit prompt envelopes with callbacks.
+- Plugin discovery and ordering are deterministic for a given repo state.
+
+## Gaps & Conflicts
+
+- The PRD does not define the plugin manifest schema, validation rules, or
+  where manifests live on disk versus embedded in the binary.
+- The activation signal format (paths/globs), precedence rules, and failure
+  behavior are unspecified.
+- The supported check types (rule-set, gates, state-rules, agent prompts) are
+  listed here but lack definitions and lifecycle requirements.
+- The scope of the Helix plugin's doc and gate validation is not specified
+  (which checks, inputs, or outputs it owns).
+- No conflicts identified in the provided inputs.
 
 ## Traceability
 
 - Supports adoption success metric by enabling reuse across repos.
+- Supports PRD scope for a built-in Helix plugin for doc and gate validation.
+- Supports PRD scope for an extensible plugin system for future workflows.
+- Supports deterministic output goals by requiring stable plugin discovery.
 - Primary personas: agent operators and engineering leads.

docs/helix/01-frame/features/F-004-install-command.md

@@ -1,17 +1,73 @@
+---
+dun:
+  id: F-004
+  depends_on:
+    - helix.prd
+  review:
+    self_hash: f0ee8193702c1900c29140bab9213036a72b8ba2c411b55bfb63c03a23329d3e
+    deps:
+      helix.prd: 58d3c4be8edb0a0be9d01a3325824c9b350f758a998d02f16208525949c4f1ad
+---
 # Feature Spec: F-004 Install Command
 
 ## Summary
 
-Provide a `dun install` command that inserts AGENTS.md guidance for agent loops.
+Provide a `dun install` command that seeds AGENTS guidance and default Dun
+configuration in a repository.
 
 ## Requirements
 
-- Idempotently insert a Dun tool snippet in AGENTS.md.
-- Support `--dry-run` to show planned changes.
-- Avoid destructive edits; use marker blocks.
+- Provide a local CLI command named `dun install`.
+- Seed AGENTS guidance in the target repo using a marker-delimited template.
+- Create `.dun/config.yaml` when missing.
+- Be idempotent and safe to re-run.
+- Support `--dry-run` to show planned changes without writing.
+- Keep output deterministic and agent-friendly.
+
+## Gaps & Conflicts
+
+- The PRD does not mention creating `.dun/config.yaml`; confirm this behavior
+  remains desired.
+- There is no defined backup or undo behavior for AGENTS edits.
+- The install command only targets the repo root; no guidance exists for
+  multi-root or monorepo installs.
+
+## Template
+
+`dun install` inserts or updates the following marker-delimited block in
+`AGENTS.md`:
+
+```
+<!-- DUN:BEGIN -->
+- **dun**: Development quality checker with autonomous loop support
+
+  Quick commands:
+  - `dun check` - Run all quality checks
+  - `dun check --prompt` - Get work list as a prompt (pick ONE task, complete it, exit)
+  - `dun loop --harness claude` - Run autonomous loop with Claude
+  - `dun loop --harness gemini` - Run autonomous loop with Gemini
+  - `dun help` - Full documentation
+
+  Autonomous iteration pattern:
+  1. Run `dun check --prompt` to see available work
+  2. Pick ONE task with highest impact
+  3. Complete that task fully (edit files, run tests)
+  4. Exit - the loop will call you again for the next task
+<!-- DUN:END -->
+```
+
+## Insertion Rules
+
+- If `AGENTS.md` already contains the marker block, replace the block content.
+- If `AGENTS.md` contains a `## Tools` header, insert the block immediately
+  after the header (preserve existing content).
+- Otherwise, append a new `## Tools` section with the block at the end.
 
 ## Acceptance Criteria
 
-- `dun install` writes AGENTS.md if missing.
-- `dun install --dry-run` shows planned steps without changes.
-- Re-running `dun install` is safe and idempotent.
+- `dun install` is available in the CLI and documents its usage.
+- Running `dun install` creates `.dun/config.yaml` when missing.
+- Running `dun install` results in AGENTS guidance being seeded in the repo
+  using the defined template and insertion rules.
+- Re-running `dun install` does not change files when no updates are needed.
+- `dun install --dry-run` emits the planned steps without writing.

docs/helix/01-frame/features/F-005-git-hygiene.md

@@ -1,3 +1,13 @@
+---
+dun:
+  id: F-005
+  depends_on:
+    - helix.prd
+  review:
+    self_hash: b98c3a3624a6c461688e617b70892cd2bbb0cf1b990ebefdbf350ee1fa8c6cdc
+    deps:
+      helix.prd: 58d3c4be8edb0a0be9d01a3325824c9b350f758a998d02f16208525949c4f1ad
+---
 # Feature Spec: F-005 Git Hygiene and Hook Checks
 
 ## Summary
@@ -16,7 +26,16 @@ committing after manual approval.
   command.
 - If a hook tool is configured but missing, emit a warning with a clear next
   step (install tool or skip).
-- Keep the check fast and local-only.
+- Keep the check fast, local-only, and deterministic.
+
+## Gaps & Conflicts
+
+- Exit code behavior for warning-only checks is not defined in the PRD or
+  F-015; confirm whether warnings should still return exit code 0.
+- Hook support beyond lefthook and pre-commit (for example, husky or
+  lint-staged) is not specified.
+- The PRD does not specify whether a dirty working tree should be a warning or
+  failure; this spec defaults to **warn** so other checks can still run.
 
 ## Detection
 
@@ -31,7 +50,7 @@ committing after manual approval.
 
 - Use `git status --porcelain` to detect uncommitted changes.
 - **Pass**: no changes.
-- **Fail**: working tree dirty; include a list of changed paths in issues.
+- **Warn**: working tree dirty; include a list of changed paths in issues.
 
 ### Hook Check (Optional)
 

docs/helix/01-frame/features/F-006-doc-reconciliation.md

@@ -1,17 +1,33 @@
+---
+dun:
+  id: F-006
+  depends_on:
+    - helix.prd
+  review:
+    self_hash: c0cc87165a06f1ff8b90f446f9ae6723319287c7645b0f1659aa3ee618eb4962
+    deps:
+      helix.prd: 58d3c4be8edb0a0be9d01a3325824c9b350f758a998d02f16208525949c4f1ad
+---
 # Feature Spec: F-006 Doc and Code Reconciliation
 
 ## Summary
 
-Detect documentation drift across the Helix stack and propose downstream
-changes from PRD to implementation.
+Detect documentation and implementation drift across the Helix stack and emit
+a deterministic, ordered reconciliation plan for downstream updates.
 
 ## Requirements
 
-- Compare PRD, feature specs, user stories, design docs, ADRs, test plans, and
-  implementation for drift.
-- Emit a structured plan that lists required downstream updates.
-- Support both documentation-only drift and implementation drift.
-- Keep the analysis deterministic and reproducible.
+- Build a deterministic inventory of artifacts: PRD, feature specs, user
+  stories, design docs, ADRs, test plans, and implementation markers.
+- Detect drift types: missing artifacts, stale artifacts due to upstream
+  changes, and implementation drift relative to docs.
+- Emit a structured reconciliation plan as ordered issues with clear next
+  steps per artifact.
+- Order the plan from upstream to downstream so operators update artifacts in
+  dependency order.
+- Support automation modes for reconciliation (plan vs yolo) as part of the
+  run context.
+- Keep the analysis deterministic and reproducible for the same repo state.
 
 ## Inputs
 
@@ -21,10 +37,33 @@ changes from PRD to implementation.
 - `docs/helix/02-design/**/*.md`
 - `docs/helix/03-test/test-plan.md`
 - Source code paths (e.g., `cmd/`, `internal/`) as needed by the agent
+- Automation mode configuration (CLI/config) for plan vs yolo behavior
 
 ## Acceptance Criteria
 
 - When a PRD change is detected, Dun emits a drift plan listing impacted
-  artifacts in order.
+  artifacts in deterministic dependency order.
+- The plan includes updates for feature specs, design docs, ADRs, test plans,
+  and implementation artifacts; user stories are included when present.
 - Drift output is structured as issues with clear next steps.
-- The plan traces updates all the way to implementation and tests.
+- Automation mode `plan` emits the reconciliation plan without edits; `yolo`
+  allows agents to complete missing artifacts per policy.
+
+## Gaps & Conflicts
+
+- Conflicts: none identified in the provided inputs.
+- Missing definition of the drift detection method (hashing, stamps, or diff
+  strategy) and how implementation drift is identified.
+- Missing ordering rules for artifacts at the same layer and how user stories
+  interleave with feature specs.
+- Missing plan schema (fields, IDs, severity) and mapping to output formats
+  (prompt envelopes vs JSON).
+- Missing rules for code scope selection and how much code context to include.
+- Dependencies: automation mode policy (F-007), doc dependency tracking
+  (F-016), and output format rules (F-002).
+
+## Traceability
+
+- Supports PRD goals for deterministic, agent-friendly output and doc-to-code
+  reconciliation with plan and yolo modes.
+- Supports US-005 by emitting ordered downstream updates from PRD changes.