declare-cc 0.5.3 → 0.5.6

package/commands/declare/milestones.md

@@ -24,12 +24,24 @@ If no declarations exist in the graph, tell the user to run `/declare:future` fi
 
 Note all declarations and milestones from the graph -- the workflow needs full context.
 
-**Step 2: Determine scope.**
+**Step 2: Scope review (first-time derivation only).**
+
+Skip this step if `$ARGUMENTS` contains a specific declaration ID (e.g., `D-01`) — targeted re-derivation skips scope review.
+
+Otherwise, check if any milestones already exist in the graph. If milestones already exist, this is a re-derivation — skip scope review and proceed to Step 3.
+
+If this is the first time deriving milestones (no milestones in the graph yet), run the scope review workflow before deriving anything:
+
+@workflows/scope.md
+
+Pass all declarations from the loaded graph into the scope workflow. After the scope is confirmed, continue to Step 3.
+
+**Step 3: Determine derivation scope.**
 
 - If `$ARGUMENTS` contains a declaration ID (e.g., `D-01`), derive only for that specific declaration.
 - Otherwise, derive for all declarations that have no milestones yet (declarations with empty milestones arrays in the graph).
 
-**Step 3: Follow the milestone derivation workflow.**
+**Step 4: Follow the milestone derivation workflow.**
 
 Read and follow the full workflow instructions:
 
@@ -37,7 +49,7 @@ Read and follow the full workflow instructions:
 
 Pass the loaded graph state into the workflow so it knows about existing declarations and milestones.
 
-**Step 4: Per-declaration milestone confirmation with checkboxes.**
+**Step 5: Per-declaration milestone confirmation with checkboxes.**
 
 After the workflow proposes milestones for a declaration, present them using AskUserQuestion with multi-select checkboxes:
 
@@ -50,7 +62,7 @@ Which of these milestones should we create for D-XX?
 - [ ] Milestone C -- because [reason]
 ```
 
-**Step 5: Persist all accepted milestones in one batch call.**
+**Step 6: Persist all accepted milestones in one batch call.**
 
 Build a JSON array of the checked milestones, then create them all at once:
 
@@ -60,7 +72,7 @@ node dist/declare-tools.cjs add-milestones --json '[{"title":"Milestone A","real
 
 This creates all milestones and makes a single git commit. Parse the JSON output — it returns `{ milestones: [{ id, title, realizes, status }], committed, hash }`.
 
-**Step 6: Inconsistency flagging.**
+**Step 7: Inconsistency flagging.**
 
 If milestones already exist for a declaration being processed (re-derivation case):
 - Show existing milestones for that declaration
@@ -68,7 +80,7 @@ If milestones already exist for a declaration being processed (re-derivation cas
 - Offer to keep, re-derive, or adjust
 - Do NOT auto-reconcile -- the user decides what to update
 
-**Step 7: Show summary and suggest next step.**
+**Step 8: Show summary and suggest next step.**
 
 After all declarations processed:
 

package/commands/declare/plan.md

@@ -60,7 +60,37 @@ If no actions found, display: "No actions found for M-XX. Run `/declare:actions
 
 If all actions already have EXEC-PLANs and status is not PENDING, display: "All actions for M-XX already have EXEC-PLANs. Use `/declare:execute M-XX` to run them." and exit.
 
-**Step 3: Research check (unless --skip-research).**
+**Step 3: Ensure milestone context exists.**
+
+Check if CONTEXT.md exists at `milestoneFolderPath/CONTEXT.md`.
+
+If CONTEXT.md does **not** exist, use AskUserQuestion:
+- header: "Context"
+- question: "Milestone [M-XX] has no implementation context yet. Discussing decisions now gives the planner the information it needs to create better EXEC-PLANs."
+- options:
+  - "Discuss first (Recommended)" — Run discuss workflow, then proceed to planning
+  - "Plan without context" — Skip; planner will use its own judgment
+
+If "Discuss first":
+
+Display: `Running /declare:discuss [M-XX]...`
+
+Spawn a Task agent:
+- subagent_type: `general-purpose`
+- description: `Discuss M-XX implementation decisions`
+- prompt:
+  ```
+  Run /declare:discuss [M-XX] for the Declare project.
+  Working directory: [absolute cwd]
+  Follow all instructions in commands/declare/discuss.md.
+  After capturing context, return DONE.
+  ```
+
+Wait for the task to complete. Then reload `contextPath` — CONTEXT.md should now exist.
+
+If "Plan without context": continue to Step 4.
+
+**Step 4: Research check (unless --skip-research).**
 
 If `researchPath` exists, display:
 ```
@@ -79,7 +109,7 @@ If `researchPath` does not exist, assess whether research is needed:
 
 - If actions are purely internal (refactoring, adding features to existing patterns, docs) → skip silently.
 
-**Step 4: Load context files.**
+**Step 5: Load context files.**
 
 ```bash
 cat [contextPath] 2>/dev/null          # CONTEXT.md if exists
@@ -91,7 +121,7 @@ cat .planning/STATE.md 2>/dev/null     # Current position and decisions
 
 Also read the milestone's PLAN.md (at `milestoneFolderPath/PLAN.md`) for action details.
 
-**Step 5: Spawn declare-planner.**
+**Step 6: Spawn declare-planner.**
 
 Spawn a Task agent using `agents/declare-planner.md` with the following prompt:
 
@@ -118,7 +148,7 @@ Return: PLANNING COMPLETE with wave structure and EXEC-PLANs created.
 
 Wait for the planner to complete.
 
-**Step 6: Spawn declare-plan-checker.**
+**Step 7: Spawn declare-plan-checker.**
 
 After planner completes, spawn a Task agent using `agents/declare-plan-checker.md` with the following prompt:
 
@@ -141,15 +171,15 @@ Return: VERIFICATION PASSED or ISSUES FOUND with structured issues YAML.
 
 Wait for the checker to complete.
 
-**Step 7: Evaluate checker result.**
+**Step 8: Evaluate checker result.**
 
 Parse the checker's return.
 
-If **VERIFICATION PASSED**: proceed to Step 9.
+If **VERIFICATION PASSED**: proceed to Step 10.
 
-If **ISSUES FOUND**: proceed to Step 8 (revision loop).
+If **ISSUES FOUND**: proceed to Step 9 (revision loop).
 
-**Step 8: Revision loop (max 3 iterations).**
+**Step 9: Revision loop (max 3 iterations).**
 
 Track revision count. If revision count >= 3, skip to Step 9 with a warning.
 
@@ -175,11 +205,11 @@ Make targeted fixes only — do not rewrite working plans.
 Return: REVISION COMPLETE with changes made.
 ```
 
-After revision, re-run checker (Step 6). Increment revision count.
+After revision, re-run checker (Step 7). Increment revision count.
 
 Repeat until VERIFICATION PASSED or revision count reaches 3.
 
-**Step 9: Commit EXEC-PLANs.**
+**Step 10: Commit EXEC-PLANs.**
 
 Pass each file as a separate `--files` argument (not space-separated in one argument):
 
@@ -189,7 +219,7 @@ node dist/declare-tools.cjs commit "docs(${MILESTONE}): create exec-plans for mi
 
 If the commit reports `nothing_to_commit`, the planner already committed the files — that is fine, continue.
 
-**Step 10: Present results.**
+**Step 11: Present results.**
 
 Display final summary:
 

package/dist/declare-tools.cjs

@@ -1329,7 +1329,7 @@ var require_help = __commonJS({
             usage: "/declare:help"
           }
         ],
-        version: "0.5.2"
+        version: "0.5.6"
       };
     }
     module2.exports = { runHelp: runHelp2 };

package/hooks/declare-server.js

@@ -86,17 +86,15 @@ function killPort(port) {
  * Start the dashboard server for this project in the background.
  */
 function startServer() {
+  // Write port file before spawning so /declare:dashboard always finds it
+  try { fs.writeFileSync(portFile, String(port)); } catch {}
+
   const child = cp.spawn(process.execPath, [bundle, 'serve', '--port', String(port)], {
     cwd,
     detached: true,
     stdio: 'ignore',
   });
   child.unref();
-
-  // Write port file so /declare:dashboard knows where to open
-  setTimeout(() => {
-    try { fs.writeFileSync(portFile, String(port)); } catch {}
-  }, 800);
 }
 
 // Check if something is already running on this port
@@ -111,6 +109,8 @@ checkRunningServer(port, status => {
 
   // Nothing running (or non-Declare process) — kill whatever is there and start fresh
   killPort(port);
-  setTimeout(startServer, 300);
-  process.exit(0);
+  setTimeout(() => {
+    startServer();
+    process.exit(0);
+  }, 300);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "declare-cc",
-  "version": "0.5.3",
+  "version": "0.5.6",
   "description": "A future-driven meta-prompting engine for agentic development, rooted in declared futures and causal graph structure.",
   "bin": {
     "declare-cc": "bin/install.js"
@@ -43,6 +43,7 @@
   },
   "scripts": {
     "test": "node --test src/graph/engine.test.js",
-    "build": "node esbuild.config.js"
+    "build": "node esbuild.config.js",
+    "release": "node scripts/release.js"
   }
 }

package/scripts/release.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Release script: bump version, build, commit, tag.
+// Usage: npm run release -- <version>
+// Example: npm run release -- 0.5.6
+//
+// After this runs, publish manually:
+//   npm publish --otp=<your-2fa-code>
+//   git push && git push --tags
+
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const version = process.argv[2];
+if (!version || !/^\d+\.\d+\.\d+$/.test(version)) {
+  console.error('Usage: npm run release -- <version>  (e.g. 0.5.6)');
+  process.exit(1);
+}
+
+const root = path.join(__dirname, '..');
+const pkgPath = path.join(root, 'package.json');
+
+function run(cmd) {
+  console.log(`> ${cmd}`);
+  execSync(cmd, { cwd: root, stdio: 'inherit' });
+}
+
+// 1. Bump version in package.json
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+const prev = pkg.version;
+pkg.version = version;
+fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+console.log(`Bumped ${prev} → ${version}`);
+
+// 2. Build
+run('npm run build');
+
+// 3. Commit + tag
+run(`git add package.json package-lock.json dist/`);
+run(`git commit -m "chore: bump version to ${version}"`);
+run(`git tag v${version}`);
+
+console.log(`
+Done. To publish:
+
+  npm publish --otp=<your-2fa-code>
+  git push && git push --tags
+`);

package/workflows/scope.md

@@ -0,0 +1,94 @@
+# Declaration Scope Review
+
+You are reviewing the full set of declared futures with the user before deriving milestones. This is a synthesis checkpoint — confirm the foundation is solid so milestone derivation builds on the right ground.
+
+## Purpose
+
+Before working backward to milestones, establish:
+1. The declarations collectively tell a coherent story
+2. The scope boundary is clear (what's in, what's out)
+3. No important futures are missing or redundant
+4. The framing reflects what the user actually intends to build
+
+## Opening
+
+Synthesize all declarations into a scope statement. Do not simply list them — draw out what they *mean together*:
+
+```
+Looking at your declarations as a whole:
+
+[D-01]: [statement]
+[D-02]: [statement]
+...
+
+Here's the scope I see:
+
+[2-3 sentence synthesis: what this project creates, who it serves, what fundamentally changes]
+
+In scope: [concrete things the declarations cover]
+Assumed out of scope: [what the declarations imply is NOT the focus]
+
+Does this framing match your intent?
+```
+
+Present this as text, then use AskUserQuestion:
+
+- header: "Scope"
+- question: "Does this framing capture what you're building?"
+- options:
+  - "Yes, this is right — derive milestones" (Recommended)
+  - "A declaration needs adjusting"
+  - "Something important is missing"
+  - "The scope feels off"
+
+## If "A declaration needs adjusting"
+
+Ask which declaration and what's off. Work through the refinement conversationally. If the updated statement is meaningfully different:
+
+```bash
+node dist/declare-tools.cjs add-declaration --title "[revised title]" --statement "[revised statement]"
+```
+
+Note: if removing the old version matters, flag it to the user — they can delete the old declaration or keep both if they serve different purposes.
+
+After the change, re-synthesize and confirm once more.
+
+## If "Something important is missing"
+
+Guide the user to state the missing future using the same language principles as in `/declare:future`: present-tense, stated as fact, not goal language. Validate and add:
+
+```bash
+node dist/declare-tools.cjs add-declaration --title "[title]" --statement "[statement]"
+```
+
+After adding, re-synthesize and confirm.
+
+## If "The scope feels off"
+
+Probe what specifically feels wrong:
+
+- Too broad? — Help identify which declarations to narrow or which to defer
+- Too narrow? — Something missing (redirect to above)
+- Wrong framing? — Rephrase the synthesis, not the declarations, and re-confirm
+
+One pass of adjustment is enough. After a second confirmation attempt, proceed.
+
+## After Confirmation
+
+Once framing is confirmed, briefly acknowledge it and move forward:
+
+```
+Scope confirmed.
+
+[N] declarations covering [core theme]. Deriving milestones by working backward from each.
+```
+
+Then immediately proceed to milestone derivation — do not ask more questions here.
+
+## Design Principles
+
+- **Synthesize, don't list.** The user already saw their declarations. Show what they mean together.
+- **Name what's out.** Explicit scope exclusions prevent milestone sprawl during derivation.
+- **One round of adjustment.** If the user modifies and re-confirms, proceed. Don't loop more than twice.
+- **Be concrete.** Don't say "the project creates value" — say "the project gives developers a self-hosted AI coding workflow that runs without a cloud dependency."
+- **No emojis.** Keep tone grounded.