declare-cc 0.3.9 → 0.4.3

package/commands/declare/actions.md

@@ -1,5 +1,5 @@
 ---
-description: Derive action plans per milestone
+description: Define actions per milestone — what must be done and what each produces (creates PLAN.md)
 allowed-tools:
   - Read
   - Write
@@ -96,4 +96,13 @@ node dist/declare-tools.cjs load-graph
 ```
 
 2. Show summary: milestones processed, plans created, total actions derived.
-3. Suggest: "Run `/declare:status` to see coverage and health."
+3. Suggest the next step clearly:
+
+```
+Actions defined. Next: create executable plans.
+
+  /declare:plan M-XX    — research + planner + checker loop → EXEC-PLAN files
+  /declare:execute M-XX — once plans exist, execute with wave scheduling
+```
+
+If multiple milestones were planned, list each one with its suggested next command.

package/commands/declare/plan.md

@@ -45,16 +45,16 @@ Check if `--skip-research` is present in `$ARGUMENTS`.
 **Step 2: Load milestone data.**
 
 ```bash
-node dist/declare-tools.cjs load-graph --milestone M-XX
+node dist/declare-tools.cjs load-graph
 ```
 
-Parse the JSON output. Extract:
-- `milestone`: milestone ID and title
-- `declarations`: array of declaration IDs and statements
-- `actions`: array of `{id, title, produces, dependsOn, status}`
-- `milestoneFolderPath`: path to the milestone planning folder
-- `researchPath`: path to RESEARCH.md if it exists
-- `contextPath`: path to CONTEXT.md if it exists
+Parse the JSON output. Find the milestone matching the ID. Extract:
+- `milestone`: milestone ID and title (from `milestones` array)
+- `declarations`: upstream declarations that realize this milestone (trace via `realizes` field)
+- `actions`: all actions whose `causes` array includes this milestone ID
+- `milestoneFolderPath`: derive as `.planning/milestones/M-XX-<slug>/`
+- `researchPath`: `.planning/milestones/M-XX-<slug>/RESEARCH.md` if it exists
+- `contextPath`: `.planning/milestones/M-XX-<slug>/CONTEXT.md` if it exists
 
 If no actions found, display: "No actions found for M-XX. Run `/declare:actions M-XX` first to create the milestone plan." and exit.
 
@@ -181,10 +181,14 @@ Repeat until VERIFICATION PASSED or revision count reaches 3.
 
 **Step 9: Commit EXEC-PLANs.**
 
+Pass each file as a separate `--files` argument (not space-separated in one argument):
+
 ```bash
-node dist/declare-tools.cjs commit "docs(${MILESTONE}): create exec-plans for milestone actions" --files [space-separated list of EXEC-PLAN file paths]
+node dist/declare-tools.cjs commit "docs(${MILESTONE}): create exec-plans for milestone actions" --files [path/to/A-01-EXEC-PLAN.md] --files [path/to/A-02-EXEC-PLAN.md]
 ```
 
+If the commit reports `nothing_to_commit`, the planner already committed the files — that is fine, continue.
+
 **Step 10: Present results.**
 
 Display final summary:
@@ -211,11 +215,59 @@ Display final summary:
 
 ### Next Steps
 
-Execute: `/declare:execute M-XX`
-
-/clear first — fresh context window
 ```
 
+After displaying the summary, reload the graph and check for milestones that still have no EXEC-PLANs (hasPlan is false OR actions array for that milestone has no EXEC-PLAN files):
+
+- If **other milestones still need planning**, list them and suggest planning those next:
+  ```
+  Remaining milestones to plan:
+    /declare:plan M-02  — [title]
+    /declare:plan M-03  — [title]
+
+  Plan all milestones before executing. Run /declare:execute only when all are planned.
+  ```
+
+- If **this was the last milestone to plan**, compute dependency waves before spawning anything — do not blindly parallelize all milestones.
+
+  **Step A: Compute milestone dependency waves.**
+
+  Load the graph, then read each milestone's PLAN.md. For each action, check its `dependsOn` field. If an action in M-02 lists `dependsOn: ["A-01"]` and A-01 belongs to M-01, then M-02 depends on M-01.
+
+  Build a milestone-level dependency graph from these cross-milestone action references. Run a topological sort (Kahn's algorithm) to group milestones into waves:
+  - Wave 1: milestones with no dependencies on other pending milestones
+  - Wave 2: milestones whose dependencies are all in wave 1
+  - …and so on
+
+  If no cross-milestone `dependsOn` edges exist, all milestones go into wave 1 (full parallelism). Show the wave plan before executing:
+
+  ```
+  ## Milestone Execution Waves
+
+  Wave 1 (parallel): M-01 [title], M-03 [title]
+  Wave 2 (after wave 1): M-02 [title]
+  ```
+
+  **Step B: Execute wave by wave using the Task tool.**
+
+  For each wave, spawn one Task agent per milestone **in the same response** so they execute in parallel:
+
+  Subagent type: `gsd-executor`
+  Prompt per milestone:
+  ```
+  Execute milestone [M-XX] "[title]" for the Declare project.
+  Working directory: [absolute path to cwd]
+  Run: /declare:execute [M-XX]
+  EXEC-PLANs are in: [absolute path to milestone folder]
+  ```
+
+  Wait for the entire wave to complete before spawning the next wave.
+
+  After all waves finish, propagate statuses:
+  ```bash
+  node dist/declare-tools.cjs sync-status
+  ```
+
 If max revisions reached with issues remaining, display blocker list prominently:
 
 ```

package/dist/declare-tools.cjs

@@ -1329,7 +1329,7 @@ var require_help = __commonJS({
             usage: "/declare:help"
           }
         ],
-        version: "0.3.9"
+        version: "0.4.0"
       };
     }
     module2.exports = { runHelp: runHelp2 };
@@ -1537,7 +1537,8 @@ var require_add_milestones_batch = __commonJS({
         dag.addNode(m.id, "milestone", m.title, m.status || "PENDING");
       }
       for (let i = 0; i < inputs.length; i++) {
-        const realizes = inputs[i].realizes.split(",").map((s) => s.trim()).filter(Boolean);
+        const realizesRaw = inputs[i].realizes;
+        const realizes = Array.isArray(realizesRaw) ? realizesRaw.map((s) => String(s).trim()).filter(Boolean) : String(realizesRaw).split(",").map((s) => s.trim()).filter(Boolean);
         for (const declId of realizes) {
           if (!dag.getNode(declId)) {
             return { error: `Item ${i}: declaration not found: ${declId}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "declare-cc",
-  "version": "0.3.9",
+  "version": "0.4.3",
   "description": "A future-driven meta-prompting engine for agentic development, rooted in declared futures and causal graph structure.",
   "bin": {
     "declare-cc": "bin/install.js"