declare-cc 0.5.9 → 1.0.0

package/README.md

@@ -4,8 +4,6 @@
 
 **A future-driven meta-prompting engine for agentic development.**
 
-Forked from [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done) — replaces linear phase-based planning with a three-layer DAG rooted in declared futures.
-
 [![npm](https://img.shields.io/npm/v/declare-cc?style=for-the-badge&color=7c3aed)](https://www.npmjs.com/package/declare-cc)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
@@ -23,14 +21,14 @@ npx declare-cc@latest
 
 Most planning tools start from the present and work forward — "what should we do first?" Declare starts from the future and works backward — "what must be true for this to succeed?"
 
-You declare present-tense statements of fact about your project's future. The system derives milestones ("what must be true?") and actions ("what must be done?") through causal structure, then executes them in topological order with wave-based parallelism.
+You declare present-tense statements of fact about your project's future. The system derives milestones ("what must be true?") and actions ("what must be done?") through causal structure, then executes them in topological order with wave-based parallelism — visible in real time through a browser-based dashboard.
 
 Built on the Erhard/Jensen/Zaffron ontological model:
 - **Integrity** as wholeness and completeness (not morality)
 - **Alignment** as shared future (not agreement)
 - **Performance** as the product of both
 
-This is a fork of [GSD](https://github.com/gsd-build/get-shit-done). It carries forward GSD's agent orchestration, slash command patterns, esbuild bundling, markdown artifacts, and atomic git commits — but replaces the linear phase model with a declarative graph structure. See [Fork Boundary](#fork-boundary) for details.
+Originally forked from [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done). See [Fork Boundary](#fork-boundary) for details.
 
 ---
 
@@ -42,7 +40,7 @@ This is a fork of [GSD](https://github.com/gsd-build/get-shit-done). It carries
 /declare:init
 ```
 
-Scaffolds the project structure: `FUTURE.md`, `MILESTONES.md`, `.planning/` directory, and the graph config. Installs slash commands if needed.
+Scaffolds the project structure: `FUTURE.md`, `MILESTONES.md`, `.planning/` directory, and the graph config.
 
 ### 2. Declare Futures
 
@@ -69,24 +67,25 @@ Works backward from declarations: "What must be true for D-01 to hold?" Each mil
 ### 4. Plan & Execute
 
 ```
+/declare:actions M-01     # Derive actions for the milestone
 /declare:plan M-01        # Research → plan → verify loop (planner + checker agents)
 /declare:execute M-01     # Wave-based execution with parallel agents
 ```
 
 The planner agent derives concrete actions, the checker agent validates them, and the executor runs them in topological waves. Each action gets its own atomic commit.
 
+Or use the dashboard — review plans in the column browser, approve them, then hit Go in execution mode. The pipeline runner handles wave scheduling, progress tracking, and failure recovery.
+
 **Creates:** `.planning/milestones/M-XX-*/PLAN.md` and `EXEC-PLAN-*.md` files
 
-### 5. Verify & Sync
+### 5. Verify & Complete
 
 ```
-/declare:verify M-01      # Conversational UAT — validates deliverables
-/declare:audit M-01       # Cross-reference actions against declarations
-node dist/declare-tools.cjs sync-status   # Propagate DONE bottom-up through the graph
+/declare:verify M-01              # Conversational UAT — validates deliverables
+/declare:audit M-01               # Cross-reference actions against declarations
+/declare:complete-milestone M-01  # Archive, tag release, prepare next cycle
 ```
 
-`sync-status` walks the DAG bottom-up: marks actions DONE (by file existence or milestone status), then milestones (all actions DONE), then declarations (all milestones DONE). Run it after any verification pass.
-
 ### 6. Navigate
 
 Understand your graph at any point:
@@ -119,19 +118,37 @@ The graph engine (`DeclareDag`) uses dual adjacency lists for O(1) bidirectional
 
 ---
 
-## Live DAG Dashboard
+## Dashboard
 
 ```
 /declare:dashboard
 ```
 
-Starts a local server and opens an interactive browser view of your full graph. Nodes are rendered in three layers (Declarations → Milestones → Actions) with live status colors.
+Starts a local server and opens an interactive browser view of your project. The dashboard is the primary interface for planning and execution.
+
+### Column Browser (Planning Mode)
+
+The three-layer DAG rendered as a navigable column browser — Declarations on the left, Milestones in the center, Actions on the right. Click any node to see its detail panel with full causal chain, context, and status. Chain nodes are clickable for navigation.
+
+Declarations, milestones, and actions can be created, reviewed, and approved directly in the browser. The review/annotation panel supports iterative cycles: generate plan, annotate corrections, send back for revision, repeat until approved.
+
+### Execution Mode
+
+When all plans in scope are approved, transition to execution mode — a dedicated full-screen view showing the ordered execution pipeline. Features include:
 
-**Focus mode:** Click any node to filter the graph to its causal chain. The surrounding nodes slide out, the relevant subtree centers itself with smooth FLIP animations. Click again or press Esc to exit.
+- **Pre-execution wave order** — Review the execution sequence before starting, with drag-to-reorder within dependency constraints
+- **Pipeline runner** — Manifest-driven execution with wave scheduling, transient retry, and execution reports
+- **Live progress** — Progress bar, status dots per action, elapsed time
+- **Failure handling** — Pause-on-failure with View Output, Skip, and Stop options
+- **State persistence** — Execution state survives browser refresh
 
-**Sidebar:** Click any node to see its full causal chain — declaration → milestone → action — with context and status. Chain nodes are clickable.
+### Activity Panel
 
-**Status colors:** DONE nodes retain their type hue (dimmed blue for declarations, dimmed purple for milestones, dimmed green for actions) so the graph stays readable as a living document rather than collapsing to grey.
+A right-side panel showing real-time agent activity. Every agent spawn — execution, revision, research — appears as a persistent activity card showing agent type, target node, elapsed time, and live status. Cards survive page refresh and navigation. Completed agents show a "View Result" button that navigates to the produced output.
+
+### Status Colors
+
+DONE nodes retain their type hue (dimmed blue for declarations, dimmed purple for milestones, dimmed green for actions) so the graph stays readable as a living document rather than collapsing to grey. Integrity state is visualized per-node with wholeness indicators.
 
 ---
 
@@ -156,8 +173,9 @@ The **honor protocol** for a commitment you can't keep: acknowledge the break, i
 
 - **Drift detection** — Are current actions still aligned with declared futures?
 - **Occurrence checks** — AI verifies declarations still hold at milestone completion
-- **Performance scoring** — Alignment × Integrity as qualitative HIGH/MEDIUM/LOW (never numeric scores)
+- **Performance scoring** — Alignment x Integrity as qualitative HIGH/MEDIUM/LOW (never numeric scores)
 - **Renegotiation flow** — When a declaration no longer fits, renegotiate it into `FUTURE-ARCHIVE.md`
+- **Wholeness visualization** — Each node shows its computed wholeness state in the dashboard
 
 ---
 
@@ -221,7 +239,7 @@ The **honor protocol** for a commitment you can't keep: acknowledge the break, i
 | Command | What it does |
 |---------|--------------|
 | `/declare:new-project` | Deep context gathering, PROJECT.md + STATE.md creation |
-| `/declare:new-milestone` | Archive declarations, reset for next milestone cycle |
+| `/declare:new-cycle` | Archive declarations, reset for next cycle |
 | `/declare:complete-milestone` | Snapshot graph, tag release, prepare next cycle |
 
 ### Maintenance
@@ -240,38 +258,49 @@ The **honor protocol** for a commitment you can't keep: acknowledge the break, i
 ## Project Structure
 
 ```
-FUTURE.md                              # Declared futures (D-01, D-02, ...)
-MILESTONES.md                          # Derived milestones (M-01, M-02, ...)
+FUTURE.md                              # Active declared futures
+MILESTONES.md                          # Active milestones
+FUTURE-ARCHIVE.md                      # Completed cycle declarations
 
 .planning/
 ├── PROJECT.md                         # Project context and goals
 ├── STATE.md                           # Current work state
 ├── config.json                        # Project settings
+├── agent-state.json                   # Agent lifecycle state (server-side tracking)
 ├── milestones/
-│   └── M-XX-slug/
-│       ├── PLAN.md                    # Actions for this milestone
-│       ├── EXEC-PLAN-*.md             # Per-action execution plans
-│       └── VERIFICATION.md            # Integrity proof after execution
+│   ├── M-XX-slug/
+│   │   ├── PLAN.md                    # Actions for this milestone
+│   │   ├── EXEC-PLAN-*.md            # Per-action execution plans
+│   │   └── VERIFICATION.md           # Integrity proof after execution
+│   └── v1.0/                          # Archived milestone cycle
 └── codebase/                          # Codebase analysis artifacts
 
-agents/                                # Declare-specific agent definitions
+agents/                                # Agent definitions (10 specialized agents)
 ├── declare-planner.md
 ├── declare-plan-checker.md
+├── declare-executor.md
 ├── declare-researcher.md
 ├── declare-research-synthesizer.md
 ├── declare-codebase-mapper.md
+├── declare-roadmapper.md
+├── declare-verifier.md
+├── declare-integration-checker.md
 └── declare-debugger.md
 
-workflows/
-├── discuss.md                         # Context capture workflow
-└── verify.md                         # UAT workflow
+workflows/                             # Conversational workflow definitions
+├── actions.md
+├── discuss.md
+├── future.md
+├── milestones.md
+├── scope.md
+└── verify.md
 
 dist/declare-tools.cjs                 # Bundled CLI (zero runtime deps)
-src/                                   # Source (Node.js, CJS)
+src/                                   # Source (~26K LOC)
 ├── graph/engine.js                    # DeclareDag — dual adjacency lists, Kahn's sort
 ├── artifacts/                         # Markdown parsers/writers
-├── commands/                          # CLI command implementations
-└── server/                            # DAG web server + dashboard frontend
+├── commands/                          # 40+ CLI command implementations
+└── server/                            # HTTP API, SSE streaming, dashboard frontend
 ```
 
 ---
@@ -284,6 +313,13 @@ src/                                   # Source (Node.js, CJS)
 npx declare-cc@latest
 ```
 
+Or install globally:
+
+```bash
+npm install -g declare-cc
+declare                    # Opens dashboard for current directory
+```
+
 Or clone and install locally:
 
 ```bash
@@ -357,9 +393,13 @@ WAVE 1 (parallel)        WAVE 2 (parallel)        WAVE 3
 
 Each agent gets a fresh context window. Your main session stays light.
 
+### Agent Lifecycle Tracking
+
+Every spawned agent is tracked server-side with full lifecycle state: spawn, progress, completion. The `AgentRegistry` persists state to disk so agents survive server restarts and browser refreshes. The HTTP API exposes agent state for the dashboard's activity panel.
+
 ### Status Propagation
 
-The DAG maintains status consistency bottom-up. Run `sync-status` after any verification pass:
+The DAG maintains status consistency bottom-up:
 
 ```
 Actions → check produced files exist → mark DONE

package/bin/declare.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const bundlePath = path.resolve(__dirname, '../dist/declare-tools.cjs');
+
+if (!fs.existsSync(bundlePath)) {
+  console.error('[declare] Bundle not found: ' + bundlePath);
+  console.error('[declare] Run `npm run build` in the declare-cc package directory.');
+  process.exit(1);
+}
+
+// Forward argv as-is — declare-tools.cjs reads process.argv
+require(bundlePath);

package/commands/declare/complete-milestone.md

@@ -144,7 +144,7 @@ Locate or create a `## Current State` section. Update it to reflect the complete
 **Version shipped:** vX.Y (YYYY-MM-DD)
 **Milestones completed:** [N] ([M-01, M-02, ...])
 **Known gaps:** [list incomplete milestones, or "None"]
-**Next step:** Run /declare:new-milestone to start vX.Z cycle
+**Next step:** Run /declare:new-cycle to start vX.Z cycle
 ```
 
 If the section already exists, update it in place. If it does not exist, append it after the last section.
@@ -197,7 +197,7 @@ git commit -m "chore: archive vX.Y milestone snapshot
 
 Next: Start the next milestone cycle.
 
-Run /declare:new-milestone
+Run /declare:new-cycle
 ```
 
 **Error handling:**
@@ -212,4 +212,4 @@ Run /declare:new-milestone
 - Archive is a snapshot, not a destructive operation — FUTURE.md and MILESTONES.md remain in place.
 - PROJECT.md is the persistent memory across versions — always update it.
 - Git tag marks the historical release point for the snapshot.
-- This command archives only — use /declare:new-milestone to reset for the next cycle.
+- This command archives only — use /declare:new-cycle to reset for the next cycle.

package/commands/declare/execute.md

@@ -126,7 +126,7 @@ Spawning [count] agent(s)...
 
 **3c. Spawn executor agents in parallel using the Task tool:**
 
-For each action in the wave, spawn a Task with instructions like:
+For each action in the wave, spawn a Task with `model: "opus"` and instructions like:
 
 ```
 Execute the plan at [outputPath].

package/commands/declare/{new-milestone.md → new-cycle.md}

@@ -1,5 +1,5 @@
 ---
-description: Start a new Declare milestone cycle — archive declarations, reset FUTURE.md and MILESTONES.md, preserve PROJECT.md and STATE.md
+description: Start a new Declare cycle — archive current declarations to FUTURE-ARCHIVE.md, reset FUTURE.md and MILESTONES.md, preserve PROJECT.md and STATE.md
 allowed-tools:
   - Read
   - Write

package/commands/declare/plan.md

@@ -77,6 +77,7 @@ Display: `Running /declare:discuss [M-XX]...`
 
 Spawn a Task agent:
 - subagent_type: `general-purpose`
+- model: `opus`
 - description: `Discuss M-XX implementation decisions`
 - prompt:
   ```
@@ -123,7 +124,7 @@ Also read the milestone's PLAN.md (at `milestoneFolderPath/PLAN.md`) for action
 
 **Step 6: Spawn declare-planner.**
 
-Spawn a Task agent using `agents/declare-planner.md` with the following prompt:
+Spawn a Task agent using `agents/declare-planner.md` with `model: "opus"` and the following prompt:
 
 ```
 Plan milestone ${MILESTONE} actions.
@@ -150,7 +151,7 @@ Wait for the planner to complete.
 
 **Step 7: Spawn declare-plan-checker.**
 
-After planner completes, spawn a Task agent using `agents/declare-plan-checker.md` with the following prompt:
+After planner completes, spawn a Task agent using `agents/declare-plan-checker.md` with `model: "haiku"` and the following prompt:
 
 ```
 Verify EXEC-PLAN files for milestone ${MILESTONE}.
@@ -183,7 +184,7 @@ If **ISSUES FOUND**: proceed to Step 9 (revision loop).
 
 Track revision count. If revision count >= 3, skip to Step 9 with a warning.
 
-Spawn declare-planner again in revision mode:
+Spawn declare-planner again in revision mode with `model: "opus"`:
 
 ```
 Revise EXEC-PLAN files for milestone ${MILESTONE} based on checker feedback.
@@ -283,6 +284,7 @@ After displaying the summary, reload the graph and check for milestones that sti
   For each wave, spawn one Task agent per milestone **in the same response** so they execute in parallel:
 
   Subagent type: `gsd-executor`
+  model: `opus`
   Prompt per milestone:
   ```
   Execute milestone [M-XX] "[title]" for the Declare project.

package/commands/declare/progress.md

@@ -89,11 +89,11 @@ Evaluate project state and present the appropriate option(s):
 
 **Route C — All milestones for active declarations complete:**
 - "All milestones for the current declaration wave are complete."
-- Offer: "Run `/declare:complete-milestone` or plan the next milestone with `/declare:new-milestone`"
+- Offer: "Run `/declare:complete-milestone` or plan the next milestone with `/declare:new-cycle`"
 
 **Route D — No active milestone:**
 - "No active milestone found."
-- Offer: "Run `/declare:new-milestone` to plan the next milestone, or `/declare:status` to review the full graph"
+- Offer: "Run `/declare:new-cycle` to plan the next milestone, or `/declare:status` to review the full graph"
 
 **Route E — No declarations exist:**
 - "No declarations found. Start by defining what you want to be true."

package/commands/declare/research.md

@@ -62,9 +62,9 @@ Spawning 4 researchers: STACK, FEATURES, ARCHITECTURE, PITFALLS...
 
 Spawn all 4 Task agents in the same response so they run in parallel. Each agent researches a specific domain.
 
-For each researcher, the prompt follows this pattern (fill in milestone-specific context):
+For each researcher, the prompt follows this pattern (fill in milestone-specific context). Each researcher Task is spawned with `model: "sonnet"`.
 
-**STACK researcher:**
+**STACK researcher** (model: `sonnet`):
 
 ```
 First, read agents/declare-researcher.md for your role and instructions.
@@ -91,7 +91,7 @@ Do NOT commit — the synthesizer will commit everything together.
 </output>
 ```
 
-**FEATURES researcher:**
+**FEATURES researcher** (model: `sonnet`):
 
 ```
 First, read agents/declare-researcher.md for your role and instructions.
@@ -118,7 +118,7 @@ Do NOT commit — the synthesizer will commit everything together.
 </output>
 ```
 
-**ARCHITECTURE researcher:**
+**ARCHITECTURE researcher** (model: `sonnet`):
 
 ```
 First, read agents/declare-researcher.md for your role and instructions.
@@ -145,7 +145,7 @@ Do NOT commit — the synthesizer will commit everything together.
 </output>
 ```
 
-**PITFALLS researcher:**
+**PITFALLS researcher** (model: `sonnet`):
 
 ```
 First, read agents/declare-researcher.md for your role and instructions.
@@ -191,7 +191,7 @@ Spawning synthesizer...
 
 If any researcher returned `## RESEARCH BLOCKED`, surface the blocker to the user before spawning the synthesizer. Ask whether to continue with partial research or abort.
 
-**Step 7: Spawn declare-research-synthesizer.**
+**Step 7: Spawn declare-research-synthesizer** (model: `sonnet`).
 
 ```
 First, read agents/declare-research-synthesizer.md for your role and instructions.

package/commands/declare/resume.md

@@ -118,7 +118,7 @@ Evaluate the current project state and present the most relevant next step:
 
 **Route D — No active milestone:**
 - "No active milestone found."
-- Offer: "`/declare:new-milestone` to plan next milestone" or "`/declare:status` to review graph"
+- Offer: "`/declare:new-cycle` to plan next milestone" or "`/declare:status` to review graph"
 
 **Route E — No project initialized:**
 - "Project not initialized."

package/commands/declare/verify.md

@@ -51,6 +51,7 @@ node dist/declare-tools.cjs commit "test(${MILESTONE_ID}): complete UAT - ${PASS
 **On gaps found — spawn parallel declare-debugger agents (one per gap):**
 
 For each gap in the UAT Gaps section, spawn a declare-debugger agent with:
+- `model: "opus"`
 - `symptoms_prefilled: true` (skip symptom gathering)
 - `goal: find_root_cause_only` (diagnose but don't fix)
 - Pre-filled symptoms from the gap's test_id, expected, and actual fields