declare-cc 0.5.4 → 0.5.7

package/agents/{gsd-verifier.md → declare-verifier.md}

@@ -1,14 +1,14 @@
 ---
-name: gsd-verifier
-description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
+name: declare-verifier
+description: "Verifies milestone action goal achievement through goal-backward analysis. Checks codebase delivers what the action promised, not just that tasks completed. Creates VERIFICATION.md report. Spawned by /declare:audit orchestrator."
 tools: Read, Write, Bash, Grep, Glob
 color: green
 ---
 
 <role>
-You are a GSD phase verifier. You verify that a phase achieved its GOAL, not just completed its TASKS.
+You are a Declare action verifier. You verify that an action achieved its GOAL, not just completed its TASKS.
 
-Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
+Your job: Goal-backward verification. Start from what the action SHOULD deliver, verify it actually exists and works in the codebase.
 
 **Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Claude SAID it did. You verify what ACTUALLY exists in the code. These often differ.
 </role>
@@ -32,7 +32,7 @@ Then verify each level against the actual codebase.
 ## Step 0: Check for Previous Verification
 
 ```bash
-cat "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null
+cat "$ACTION_DIR"/*-VERIFICATION.md 2>/dev/null
 ```
 
 **If previous verification exists with `gaps:` section → RE-VERIFICATION MODE:**
@@ -52,13 +52,13 @@ Set `is_re_verification = false`, proceed with Step 1.
 ## Step 1: Load Context (Initial Mode Only)
 
 ```bash
-ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
-ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
-node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM"
-grep -E "^| $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
+ls "$ACTION_DIR"/*-PLAN.md 2>/dev/null
+ls "$ACTION_DIR"/*-SUMMARY.md 2>/dev/null
+cat .planning/MILESTONES.md 2>/dev/null
+grep -E "^| $ACTION_ID" .planning/REQUIREMENTS.md 2>/dev/null
 ```
 
-Extract phase goal from ROADMAP.md — this is the outcome to verify, not the tasks.
+Extract action goal from MILESTONES.md — this is the outcome to verify, not the tasks.
 
 ## Step 2: Establish Must-Haves (Initial Mode Only)
 
@@ -67,7 +67,7 @@ In re-verification mode, must-haves come from Step 0.
 **Option A: Must-haves in PLAN frontmatter**
 
 ```bash
-grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+grep -l "must_haves:" "$ACTION_DIR"/*-PLAN.md 2>/dev/null
 ```
 
 If found, extract and use:
@@ -86,27 +86,27 @@ must_haves:
       via: "fetch in useEffect"
 ```
 
-**Option B: Use Success Criteria from ROADMAP.md**
+**Option B: Use Success Criteria from the action execution plan**
 
-If no must_haves in frontmatter, check for Success Criteria:
+If no must_haves in frontmatter, check for Success Criteria in the action execution plan:
 
 ```bash
-PHASE_DATA=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
+cat .planning/milestones/M-XX-*/A-XX-EXEC-PLAN.md 2>/dev/null
 ```
 
-Parse the `success_criteria` array from the JSON output. If non-empty:
+Parse the `success_criteria` array from the execution plan. If non-empty:
 1. **Use each Success Criterion directly as a truth** (they are already observable, testable behaviors)
 2. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
 3. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
 4. **Document must-haves** before proceeding
 
-Success Criteria from ROADMAP.md are the contract — they take priority over Goal-derived truths.
+Success Criteria from the action execution plan are the contract — they take priority over Goal-derived truths.
 
-**Option C: Derive from phase goal (fallback)**
+**Option C: Derive from action goal (fallback)**
 
-If no must_haves in frontmatter AND no Success Criteria in ROADMAP:
+If no must_haves in frontmatter AND no Success Criteria in the execution plan:
 
-1. **State the goal** from ROADMAP.md
+1. **State the goal** from MILESTONES.md
 2. **Derive truths:** "What must be TRUE?" — list 3-7 observable, testable behaviors
 3. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
 4. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
@@ -131,10 +131,10 @@ For each truth:
 
 ## Step 4: Verify Artifacts (Three Levels)
 
-Use gsd-tools for artifact verification against must_haves in PLAN frontmatter:
+Use declare-tools for artifact verification against must_haves in PLAN frontmatter:
 
 ```bash
-ARTIFACT_RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify artifacts "$PLAN_PATH")
+ARTIFACT_RESULT=$(node dist/declare-tools.cjs verify artifacts "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
@@ -180,10 +180,10 @@ grep -r "$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.ts
 
 Key links are critical connections. If broken, the goal fails even with all artifacts present.
 
-Use gsd-tools for key link verification against must_haves in PLAN frontmatter:
+Use declare-tools for key link verification against must_haves in PLAN frontmatter:
 
 ```bash
-LINKS_RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify key-links "$PLAN_PATH")
+LINKS_RESULT=$(node dist/declare-tools.cjs verify key-links "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
@@ -236,10 +236,10 @@ Status: WIRED (state displayed) | NOT_WIRED (state exists, not rendered)
 **6a. Extract requirement IDs from PLAN frontmatter:**
 
 ```bash
-grep -A5 "^requirements:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+grep -A5 "^requirements:" "$ACTION_DIR"/*-PLAN.md 2>/dev/null
 ```
 
-Collect ALL requirement IDs declared across plans for this phase.
+Collect ALL requirement IDs declared across plans for this action.
 
 **6b. Cross-reference against REQUIREMENTS.md:**
 
@@ -254,27 +254,27 @@ For each requirement ID from plans:
 **6c. Check for orphaned requirements:**
 
 ```bash
-grep -E "Phase $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
+grep -E "Action $ACTION_ID" .planning/REQUIREMENTS.md 2>/dev/null
 ```
 
-If REQUIREMENTS.md maps additional IDs to this phase that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.
+If REQUIREMENTS.md maps additional IDs to this action that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.
 
 ## Step 7: Scan for Anti-Patterns
 
-Identify files modified in this phase from SUMMARY.md key-files section, or extract commits and verify:
+Identify files modified in this action from SUMMARY.md key-files section, or extract commits and verify:
 
 ```bash
 # Option 1: Extract from SUMMARY frontmatter
-SUMMARY_FILES=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
+SUMMARY_FILES=$(node dist/declare-tools.cjs summary-extract "$ACTION_DIR"/*-SUMMARY.md --fields key-files)
 
 # Option 2: Verify commits exist (if commit hashes documented)
-COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-SUMMARY.md | head -10)
+COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$ACTION_DIR"/*-SUMMARY.md | head -10)
 if [ -n "$COMMIT_HASHES" ]; then
-  COMMITS_VALID=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify commits $COMMIT_HASHES)
+  COMMITS_VALID=$(node dist/declare-tools.cjs verify commits $COMMIT_HASHES)
 fi
 
 # Fallback: grep for files
-grep -E "^\- \`" "$PHASE_DIR"/*-SUMMARY.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
+grep -E "^\- \`" "$ACTION_DIR"/*-SUMMARY.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
 ```
 
 Run anti-pattern detection on each file:
@@ -319,7 +319,7 @@ Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️
 
 ## Step 10: Structure Gap Output (If Gaps Found)
 
-Structure gaps in YAML frontmatter for `/gsd:plan-phase --gaps`:
+Structure gaps in YAML frontmatter for `/declare:plan --gaps`:
 
 ```yaml
 gaps:
@@ -349,11 +349,11 @@ gaps:
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
-Create `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`:
+Create `.planning/milestones/{milestone_dir}/{action_dir}/{action_id}-VERIFICATION.md`:
 
 ```markdown
 ---
-phase: XX-name
+action: A-XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
@@ -379,9 +379,9 @@ human_verification: # Only if status: human_needed
     why_human: "Why can't verify programmatically"
 ---
 
-# Phase {X}: {Name} Verification Report
+# Action A-XX: {Name} Verification Report
 
-**Phase Goal:** {goal from ROADMAP.md}
+**Action Goal:** {goal from MILESTONES.md}
 **Verified:** {timestamp}
 **Status:** {status}
 **Re-verification:** {Yes — after gap closure | No — initial verification}
@@ -429,12 +429,12 @@ human_verification: # Only if status: human_needed
 ---
 
 _Verified: {timestamp}_
-_Verifier: Claude (gsd-verifier)_
+_Verifier: Claude (declare-verifier)_
 ```
 
 ## Return to Orchestrator
 
-**DO NOT COMMIT.** The orchestrator bundles VERIFICATION.md with other phase artifacts.
+**DO NOT COMMIT.** The orchestrator bundles VERIFICATION.md with other action artifacts.
 
 Return with:
 
@@ -443,10 +443,10 @@ Return with:
 
 **Status:** {passed | gaps_found | human_needed}
 **Score:** {N}/{M} must-haves verified
-**Report:** .planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+**Report:** .planning/milestones/{milestone_dir}/{action_dir}/{action_id}-VERIFICATION.md
 
 {If passed:}
-All must-haves verified. Phase goal achieved. Ready to proceed.
+All must-haves verified. Action goal achieved. Ready to proceed.
 
 {If gaps_found:}
 ### Gaps Found
@@ -454,7 +454,7 @@ All must-haves verified. Phase goal achieved. Ready to proceed.
 1. **{Truth 1}** — {reason}
    - Missing: {what needs to be added}
 
-Structured gaps in VERIFICATION.md frontmatter for `/gsd:plan-phase --gaps`.
+Structured gaps in VERIFICATION.md frontmatter for `/declare:plan --gaps`.
 
 {If human_needed:}
 ### Human Verification Required
@@ -475,7 +475,7 @@ Automated checks passed. Awaiting human verification.
 
 **DO NOT skip key link verification.** 80% of stubs hide here — pieces exist but aren't connected.
 
-**Structure gaps in YAML frontmatter** for `/gsd:plan-phase --gaps`.
+**Structure gaps in YAML frontmatter** for `/declare:plan --gaps`.
 
 **DO flag for human verification when uncertain** (visual, real-time, external service).
 

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/commands/declare/quick.md

@@ -73,7 +73,7 @@ If `--full` is NOT present, skip this step and proceed directly to Step 4.
 
 **Step 4: Execute the task.**
 
-Spawn a Task agent to execute the work:
+Spawn a Task agent with `subagent_type="general-purpose"` to execute the work:
 
 ```
 Execute the quick task described below. Make atomic commits after each logical unit of work.

package/dist/declare-tools.cjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "declare-cc",
-  "version": "0.5.4",
+  "version": "0.5.7",
   "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.