Skip to content

Commit d231f76

Browse files
easelclaude
easel
and
claude
committed
chore(docs): backfill feature specs for F-008, F-009, F-012 [hx-03acd2e5]
Create spec files for three features that were implemented without formal specs. Update feature-registry.md to reflect "Implemented" status. - F-008: Deterministic check plan (engine.go sortPlan) - F-009: Helix plugin (builtin/helix/ docs + gates) - F-012: External plugin loading (LoadExternalPlugins) Governing artifact: helix.prd Verification: spec files exist, registry updated, go build passes Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 18c6b7d commit d231f76

4 files changed

Lines changed: 182 additions & 3 deletions

File tree

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,11 @@ This registry tracks the core Dun features and their current status.
1111
| F-005 | Git Hygiene | P0 | In progress | Ensure clean working tree + hook checks |
1212
| F-006 | Doc Reconciliation | P0 | In progress | Detect drift and propagate updates |
1313
| F-007 | Automation Slider | P0 | In progress | Manual <-> yolo execution policy |
14-
| F-008 | Deterministic check plan | P0 | Planned | Stable ordering and IDs (no spec file yet) |
15-
| F-009 | Helix plugin (docs + gates) | P0 | Planned | Validate Helix artifacts and gates (no spec file yet) |
14+
| F-008 | Deterministic check plan | P0 | Implemented | Stable ordering and IDs via sortPlan |
15+
| F-009 | Helix plugin (docs + gates) | P0 | Implemented | Validate Helix artifacts and gates |
1616
| F-010 | Changed-only checks | P1 | Planned | Scope checks to git diff (no spec file yet) |
1717
| F-011 | Quality ratchet | P1 | Planned | Baseline compare to prevent regressions (no spec file yet) |
18-
| F-012 | External plugin loading | P2 | Planned | Load plugin dirs via config (no spec file yet) |
18+
| F-012 | External plugin loading | P2 | Implemented | Load plugin dirs from user and project paths |
1919
| F-013 | Reserved | - | Planned | (no spec file yet) |
2020
| F-014 | Go Quality Checks | P0 | In progress | Tests, coverage, vet, staticcheck |
2121
| F-016 | Doc DAG + Review Stamps | P0 | Planned | Frontmatter DAG, stale detection, stamp command |

‎docs/helix/01-frame/features/F-008-deterministic-check-plan.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
dun:
3+
id: F-008
4+
depends_on:
5+
- helix.prd
6+
- F-001
7+
- F-003
8+
---
9+
# Feature Spec: F-008 Deterministic Check Plan
10+
11+
## Summary
12+
13+
Produce a stable, deterministic ordering of checks so that repeated runs
14+
against the same repo state yield identical check plans. This ensures
15+
predictable output for agents and operators.
16+
17+
## Requirements
18+
19+
- Sort the check plan deterministically after discovery and filtering.
20+
- Order by plugin priority (manifest `priority` field, default 50).
21+
- Break ties by check priority (check-level `priority` field, default 50).
22+
- Break further ties by HELIX phase order (frame < design < test < build <
23+
deploy < iterate).
24+
- Break final ties alphabetically by check ID.
25+
- Produce identical ordering for the same set of active plugins and checks.
26+
27+
## Inputs
28+
29+
- Active plugins with their manifest priority values.
30+
- Planned checks with per-check priority, phase, and ID fields.
31+
32+
## Acceptance Criteria
33+
34+
- `sortPlan` produces identical ordering across multiple runs for the same
35+
input.
36+
- Plugin priority takes precedence over check priority.
37+
- Check priority takes precedence over phase order.
38+
- Phase order takes precedence over alphabetical ID.
39+
- Default priority (50) is applied when priority is unset.
40+
- Empty or single-element plans do not panic.
41+
42+
## Gaps & Conflicts
43+
44+
- No gaps identified. The implementation in `engine.go:sortPlan` fully
45+
satisfies the requirements above.
46+
- No conflicts with governing artifacts.
47+
48+
## Traceability
49+
50+
- Supports PRD goal for "deterministic, agent-friendly output that is easy
51+
to parse" by ensuring stable check ordering.
52+
- Supports F-001 Auto-Discovery acceptance criterion: "Check IDs and ordering
53+
are stable across runs for the same repo state."
54+
- Supports F-003 Plugin System acceptance criterion: "Plugin discovery and
55+
ordering are deterministic for a given repo state."
56+
- Implementation: `internal/dun/engine.go:sortPlan`.
57+
- Tests: `internal/dun/engine_sort_test.go`.

‎docs/helix/01-frame/features/F-009-helix-plugin.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
dun:
3+
id: F-009
4+
depends_on:
5+
- helix.prd
6+
- F-003
7+
---
8+
# Feature Spec: F-009 Helix Plugin
9+
10+
## Summary
11+
12+
Provide a built-in Helix plugin that validates HELIX workflow artifacts and
13+
enforces phase gates when `docs/helix/` is present. The plugin ships embedded
14+
in the Dun binary and activates automatically via auto-discovery.
15+
16+
## Requirements
17+
18+
- Activate when `docs/helix/` exists in the repository root.
19+
- Validate HELIX workflow state progression via state rules.
20+
- Validate HELIX phase gates (input and exit gates for all six phases).
21+
- Provide agent prompts for architecture creation, feature spec creation,
22+
spec alignment, and stack reconciliation.
23+
- Verify spec-to-implementation bindings via spec-binding checks.
24+
- Detect missing or stale Helix docs via doc-DAG checks.
25+
- Verify downstream updates when upstream docs change via change-cascade
26+
checks.
27+
- Verify integration contracts and dependencies.
28+
- Detect overlapping agent work via conflict-detection checks.
29+
30+
## Inputs
31+
32+
- Repository file tree (trigger: `docs/helix/` path exists).
33+
- HELIX artifact files: PRD, architecture, feature specs, user stories,
34+
solution designs, technical designs, test plans.
35+
- Phase gate definitions in `gates/` YAML files.
36+
- State rules in `state-rules.yml`.
37+
- Agent prompt templates in `prompts/`.
38+
39+
## Acceptance Criteria
40+
41+
- Helix plugin activates when `docs/helix/` exists.
42+
- State-rules check validates workflow progression.
43+
- Gate checks validate input and exit gates for all six HELIX phases
44+
(frame, design, test, build, deploy, iterate).
45+
- Agent prompts emit prompt envelopes for architecture creation, feature spec
46+
creation, spec alignment, and stack reconciliation.
47+
- Spec-binding check verifies user story implementations.
48+
- Doc-DAG check detects missing or stale docs.
49+
- Change-cascade check detects drift when PRD changes.
50+
- Plugin runs without custom configuration.
51+
52+
## Gaps & Conflicts
53+
54+
- No gaps identified. The plugin manifest at
55+
`internal/plugins/builtin/helix/plugin.yaml` defines all checks listed
56+
above.
57+
- Integration-contract and conflict-detection checks depend on optional
58+
artifacts (`integration-map.yaml`, `work-in-progress.yaml`) and activate
59+
conditionally.
60+
- No conflicts with governing artifacts.
61+
62+
## Traceability
63+
64+
- Supports PRD scope: "Built-in Helix plugin for doc and gate validation."
65+
- Supports F-003 Plugin System: "Include a built-in Helix plugin for
66+
documentation and gate validation."
67+
- Supports F-001 Auto-Discovery: "Detect Helix workflow via `docs/helix/`."
68+
- Implementation: `internal/plugins/builtin/helix/plugin.yaml` and
69+
associated gate, state-rule, and prompt files.
70+
- Tests: plugin activation tested via `internal/dun/engine_test.go`.

‎docs/helix/01-frame/features/F-012-external-plugin-loading.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
dun:
3+
id: F-012
4+
depends_on:
5+
- helix.prd
6+
- F-003
7+
---
8+
# Feature Spec: F-012 External Plugin Loading
9+
10+
## Summary
11+
12+
Allow users to extend Dun with external plugins loaded from user-level and
13+
project-level directories. Project plugins override user plugins with the
14+
same ID, enabling per-repo customization.
15+
16+
## Requirements
17+
18+
- Load external plugins from user directory (`~/.dun/plugins/*/plugin.yaml`).
19+
- Load external plugins from project directory (`.dun/plugins/*/plugin.yaml`).
20+
- Project plugins override user plugins with the same plugin ID.
21+
- Skip invalid plugin directories with a warning log, without failing the
22+
overall load.
23+
- Require `id` and `version` fields in plugin manifests.
24+
- Merge external plugins with built-in plugins during discovery.
25+
26+
## Inputs
27+
28+
- User home directory for user-level plugin path.
29+
- Project working directory for project-level plugin path.
30+
- Plugin manifest files (`plugin.yaml`) in each plugin subdirectory.
31+
32+
## Acceptance Criteria
33+
34+
- Plugins in `~/.dun/plugins/*/plugin.yaml` are loaded and available.
35+
- Plugins in `.dun/plugins/*/plugin.yaml` are loaded and available.
36+
- A project plugin with the same ID as a user plugin replaces it.
37+
- Invalid plugin directories are skipped with a warning, not an error.
38+
- Missing plugin directories are silently ignored.
39+
- Loaded external plugins participate in normal discovery and plan building.
40+
41+
## Gaps & Conflicts
42+
43+
- No gaps identified. The implementation in `plugin_loader.go` fully
44+
satisfies the requirements above.
45+
- No conflicts with governing artifacts.
46+
47+
## Traceability
48+
49+
- Supports PRD scope: "Extensible plugin system for future workflows."
50+
- Supports F-003 Plugin System: "Provide an extensible plugin system."
51+
- Implementation: `internal/dun/plugin_loader.go:LoadExternalPlugins`.
52+
- Tests: `internal/dun/plugin_loader_test.go:TestLoadExternalPlugins`.

0 commit comments

Comments
 (0)