declare-cc 1.0.1 → 1.0.4

package/README.md

@@ -7,102 +7,83 @@
 [![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)
 
-```bash
-npx declare-cc@latest
-```
-
 *Declare what's true when this succeeds. The system derives the rest backward.*
 
 </div>
 
 ---
 
-## What This Is
-
-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 — visible in real time through a browser dashboard.
+## Setup
 
-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
+Add to your project:
 
-Originally forked from [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done). See [Fork Boundary](#fork-boundary) for details.
+```bash
+npm install --save-dev declare-cc
+```
 
----
+Add a script to `package.json`:
 
-## How It Works
+```json
+{
+  "scripts": {
+    "plan": "dcl"
+  }
+}
+```
 
-### 1. Initialize
+Run it:
 
-```
-/declare:init
+```bash
+npm run plan
 ```
 
-Scaffolds the project structure: `FUTURE.md`, `MILESTONES.md`, `.planning/` directory, and the graph config.
+This auto-initializes a `.planning/` directory if one doesn't exist, starts the Declare server, writes the port to `.planning/server.port`, and opens the dashboard in your browser.
 
-### 2. Declare Futures
+Or run directly:
 
-```
-/declare:future
+```bash
+npx dcl
 ```
 
-A guided conversation captures 3-5 declarations about your project's future. Each declaration is a present-tense statement of fact — not a goal, not a wish.
+Requires Node.js 18+.
 
-The system detects past-derived language ("I want to avoid...", "We need to fix...") and uses Socratic reframing to help you declare from the future rather than react to the past.
+---
 
-**Creates:** `FUTURE.md` with declarations (D-01, D-02, ...)
+## What This Is
 
-### 3. Derive Milestones
+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?"
 
-```
-/declare:milestones
-```
+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 spawns Claude Code agents to execute them — visible in real time through a browser dashboard.
 
-Works backward from declarations: "What must be true for D-01 to hold?" Each milestone maps to one or more declarations through causal edges in the DAG.
+---
 
-**Creates:** `MILESTONES.md` with milestones (M-01, M-02, ...)
+## How It Works
 
-### 4. Plan Actions
+Everything happens through the dashboard. `dcl` opens it, and you drive the workflow with keyboard shortcuts and card-based UI.
 
-```
-/declare:actions M-01
-```
+### 1. Declare Futures
 
-Or press **P** on any milestone card in the dashboard. The AI derives 2-5 concrete actions per milestone by asking "What work must be done to achieve this?" Actions are auto-accepted and appear as cards immediately — the action list IS the plan.
+Create declarations directly in the dashboard — present-tense statements about your project's future. Not goals, not wishes.
 
-Each action has a title and a "produces" field describing its deliverable. No separate exec-plan files — the milestone's action list is the execution plan.
+### 2. Derive Milestones
 
-**Creates:** `.planning/milestones/M-XX-*/PLAN.md`
+Press **P** on a declaration card. The AI works backward: "What must be true for this to hold?" Milestones appear as cards immediately.
 
-### 5. Review & Execute
+### 3. Plan Actions
 
-In the dashboard, review each action card. Press **A** to approve, **E** to edit, **D** to delete. Once all actions for a milestone are approved, press **E** to execute.
+Press **P** on a milestone card. The AI derives 2-5 concrete actions. Actions auto-accept and appear as cards — the action list IS the plan.
 
-The executor gets the full why-chain context: declaration statement → milestone description → action details + sibling actions. It reads your codebase, implements the changes, and commits.
+### 4. Review & Approve
 
-### 6. Verify & Complete
+Navigate with **Arrow keys**. Press **A** to approve, **E** to edit, **D** to delete. Milestones only move to "Ready to Execute" when all their actions are approved.
 
-```
-/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
-```
+### 5. Execute
 
-### 7. Navigate
-
-```
-/declare:trace A-03       # Why does this action exist? Walk the why-chain
-/declare:visualize        # ASCII tree of the full DAG with status markers
-/declare:prioritize M-01  # Rank actions by unblocking power
-/declare:status           # Layer counts, health indicators
-/declare:dashboard        # Live interactive DAG in the browser
-```
+Press **E** on an approved action. A Claude Code agent spawns with full context: declaration → milestone → action + sibling actions. It reads your codebase, implements changes, and commits.
 
 ---
 
-## The Three-Layer DAG
+## The DAG
 
 ```
 Declarations (D-XX)     "What is true when this succeeds"
@@ -114,159 +95,57 @@ Milestones (M-XX)       "What must be true" (derived backward)
 Actions (A-XX)          "What must be done" (derived backward)
 ```
 
-Each layer connects to the one above through causal edges. Every action traces back to a declaration. Orphan nodes (actions without a milestone, milestones without a declaration) are detected and flagged.
-
-The graph engine (`DeclareDag`) uses dual adjacency lists for O(1) bidirectional lookups — trace upward (why-chains) or traverse downward (what depends on this) with equal efficiency.
+Every action traces back to a declaration through causal edges.
 
 ---
 
 ## Dashboard
 
-```
-/declare:dashboard
-```
+### Lifecycle Stages
 
-Starts a local server and opens an interactive browser view. The dashboard is the primary interface for planning, review, and execution.
-
-### Lifecycle Column Browser
-
-Drill into the three-layer DAG: Declarations → Milestones → Actions. Each level groups cards into lifecycle stages:
+Cards are grouped into stages at each level:
 
 | Stage | Meaning |
 |-------|---------|
-| **Needs Planning** | Approved but no actions derived yet |
-| **Needs Approval** | Has unapproved items (milestones or actions) |
-| **Ready to Execute** | All items approved, ready to run |
-| **In Execution** | Currently being executed by an agent |
-| **Done** | Completed (collapsible) |
-
-Cards show inline status: title, description, status badges, action counts, and review state. The action buttons row (Plan, Edit, Delete, Approve, Execute) is always visible — no hidden menus.
+| **Needs Planning** | Approved, no actions yet |
+| **Needs Approval** | Has unapproved items |
+| **Ready to Execute** | All approved, ready to run |
+| **In Execution** | Agent running |
+| **Done** | Completed |
 
 ### Keyboard Shortcuts
 
-Single keys act on the focused card (use arrow keys to navigate):
-
 | Key | Action |
 |-----|--------|
-| **P** | Plan — derive actions/milestones |
-| **A** | Approve the focused card |
-| **E** | Edit (opens inline textarea) |
+| **P** | Plan (derive milestones/actions) |
+| **A** | Approve |
+| **E** | Edit / Execute |
 | **D** | Delete |
-| **Arrow Up/Down** | Move focus between cards |
-| **Arrow Right/Enter** | Drill into card |
-| **Arrow Left** | Go back one level |
+| **Arrow keys** | Navigate cards, drill in/out |
 | **Ctrl+Shift+A** | Approve all visible |
-| **Ctrl+Shift+P** | Global plan (top-right button) |
-
-### Activity Panel
+| **C** | Command bar |
 
-Right-side panel showing real-time agent activity. Every agent spawn — planning, execution, revision — appears as a persistent card with type, target, elapsed time, and status. Cards survive page refresh. Completed agents show "View Result".
+### Server Discovery
 
-### Command Bar
-
-Press **C** to open the command input at the bottom. Type natural language or slash commands. The command bar dispatches to the server API.
-
-### Mesh UI Integration
-
-The server writes `.planning/server.port` on startup (deleted on shutdown) so external tools like the Mesh UI Declare plugin can discover and embed the dashboard.
+On startup, the server writes the port number to `.planning/server.port` (plain text, e.g. `3847`). On shutdown, it deletes this file. External tools can read this file to embed the dashboard in an iframe.
 
 ---
 
-## Integrity & Alignment
-
-Declare doesn't just track what's done — it tracks whether commitments are being honored.
-
-### Integrity States
-
-| Status | Meaning |
-|--------|---------|
-| `KEPT` | Commitment fulfilled as declared |
-| `HONORED` | Commitment couldn't be kept, but the honor protocol was followed |
-| `BROKEN` | Commitment not fulfilled, no acknowledgment |
-| `RENEGOTIATED` | Commitment explicitly changed through renegotiation flow |
-
-The **honor protocol** for a commitment you can't keep: acknowledge the break, inform affected parties, clean up the mess, renegotiate a new commitment.
-
-### Alignment Monitoring
-
-- **Drift detection** — Are current actions still aligned with declared futures?
-- **Occurrence checks** — AI verifies declarations still hold at milestone completion
-- **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
-
----
-
-## Commands
-
-### Core Workflow
-
-| Command | What it does |
-|---------|--------------|
-| `/declare:init` | Scaffold project structure and install commands |
-| `/declare:future` | Guided conversation to capture declared futures |
-| `/declare:milestones` | Derive milestones backward from declarations |
-| `/declare:actions [M-XX]` | Derive actions for a milestone |
-| `/declare:execute [M-XX]` | Execute actions with full context |
-
-### Planning Support
-
-| Command | What it does |
-|---------|--------------|
-| `/declare:discuss [M-XX]` | Gather milestone context through adaptive questioning |
-| `/declare:research [M-XX]` | Spawn 4 parallel researchers, synthesize into RESEARCH.md |
-| `/declare:map-codebase` | Parallel codebase analysis → `.planning/codebase/` docs |
-
-### Quality Loop
-
-| Command | What it does |
-|---------|--------------|
-| `/declare:verify [M-XX]` | Conversational UAT — validates deliverables, spawns debuggers on failure |
-| `/declare:audit [M-XX]` | Cross-reference actions against declarations, identify gaps |
-| `/declare:debug` | Systematic debugging with scientific method and checkpoint persistence |
-
-### Navigation
-
-| Command | What it does |
-|---------|--------------|
-| `/declare:trace <node>` | Walk the why-chain from any node up to its declaration |
-| `/declare:visualize` | ASCII tree of the full DAG with status markers |
-| `/declare:prioritize [M-XX]` | Rank actions by dependency weight (unblocking power) |
-| `/declare:status` | Graph health, layer counts, integrity and alignment metrics |
-| `/declare:dashboard` | Live interactive DAG in the browser |
-
-### Productivity
-
-| Command | What it does |
-|---------|--------------|
-| `/declare:quick` | Ad-hoc task with atomic commit, outside milestone structure |
-| `/declare:add-todo` | Capture an idea or task for later |
-| `/declare:check-todos` | List pending todos, route to milestone or quick task |
-
-### Session Management
-
-| Command | What it does |
-|---------|--------------|
-| `/declare:progress` | Current position, recent work summary, route to next action |
-| `/declare:pause` | Snapshot work state to `.continue-here.md` for safe handoff |
-| `/declare:resume` | Restore full context from previous session |
-
-### Lifecycle
+## CLI Commands
 
-| Command | What it does |
-|---------|--------------|
-| `/declare:new-project` | Deep context gathering, PROJECT.md + STATE.md creation |
-| `/declare:new-cycle` | Archive declarations, reset for next cycle |
-| `/declare:complete-milestone` | Snapshot graph, tag release, prepare next cycle |
-
-### Maintenance
+The dashboard is the primary interface. All operations are also available as slash commands in Claude Code:
 
 | Command | What it does |
 |---------|--------------|
-| `/declare:health` | Diagnose `.planning/` directory health, repair issues |
-| `/declare:settings` | Configure workflow toggles interactively |
-| `/declare:set-profile` | Switch model profile (quality / balanced / budget) |
-| `/declare:update` | Update to latest npm version with local-patch preservation |
-| `/declare:reapply-patches` | Reapply local modifications after an update |
+| `/declare:future` | Guided conversation to capture futures |
+| `/declare:milestones` | Derive milestones from declarations |
+| `/declare:actions M-XX` | Derive actions for a milestone |
+| `/declare:execute M-XX` | Execute actions |
+| `/declare:verify M-XX` | Conversational UAT |
+| `/declare:audit M-XX` | Cross-reference against declarations |
+| `/declare:trace A-XX` | Walk the why-chain to its declaration |
+| `/declare:status` | Graph health and layer counts |
+| `/declare:dashboard` | Open the dashboard |
 | `/declare:help` | Show all commands |
 
 ---
@@ -274,172 +153,22 @@ The **honor protocol** for a commitment you can't keep: acknowledge the break, i
 ## Project Structure
 
 ```
-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.port                        # Active server port (auto-managed)
+├── server.port          # Active server port (auto-managed)
+├── config.json          # Settings
+├── agent-state.json     # Agent lifecycle state
 ├── milestones/
-│   ├── M-XX-slug/
-│   │   ├── PLAN.md                    # Actions for this milestone
-│   │   ├── execution.log             # Execution output log
-│   │   └── VERIFICATION.md           # Integrity proof after execution
-│   └── v1.0/                          # Archived milestone cycle
-└── codebase/                          # Codebase analysis artifacts
+│   └── M-XX-slug/
+│       └── PLAN.md      # Actions for this milestone
+FUTURE.md                # Declared futures
+MILESTONES.md            # Derived milestones
 ```
 
 ---
 
-## Getting Started
-
-### Install
-
-```bash
-npx declare-cc@latest
-```
-
-Or install globally:
-
-```bash
-npm install -g declare-cc
-declare                    # Opens dashboard for current directory
-```
-
-Requires Node.js 18+.
-
-### Quick Start
-
-```
-/declare:init                  # Scaffold the project
-/declare:future                # Declare 3-5 futures
-/declare:milestones            # Derive milestones backward
-/declare:dashboard             # Open the live dashboard
-```
-
-Then in the dashboard: press **P** to plan actions, **A** to approve, **E** to execute. Everything flows through the card-based UI.
-
-### Recommended: Skip Permissions Mode
-
-Declare spawns agents and runs CLI tools frequently. For frictionless operation:
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-<details>
-<summary><strong>Alternative: Granular Permissions</strong></summary>
-
-Add to `.claude/settings.json`:
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(node:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git status:*)",
-      "Bash(git log:*)",
-      "Bash(git diff:*)"
-    ]
-  }
-}
-```
-
-</details>
-
----
-
-## Architecture
-
-### Concurrent Planning
-
-Multiple milestones can be planned simultaneously. The action derivation runner uses a session Map — no singleton locks, no 409 errors. Each session broadcasts independently via SSE.
-
-### Rich Execution Context
-
-When an action executes, the AI agent receives the full why-chain:
-
-```
-Declaration: D-01 — "The system handles all edge cases gracefully"
-    ↓
-Milestone: M-03 — Error Recovery and Resilience
-    ↓
-Action: A-07 — Implement retry logic with exponential backoff
-    Produces: Retry wrapper for all external API calls
-
-Other actions (context only):
-- A-06: Add circuit breaker pattern [DONE]
-- A-08: Build error reporting dashboard
-```
-
-The executor reads the codebase, implements changes, verifies them, and commits — all autonomously.
-
-### Status Propagation
-
-The DAG maintains status consistency bottom-up:
-
-```
-Actions → check produced files exist → mark DONE
-    ↓
-Milestones → all actions DONE → mark DONE
-    ↓
-Declarations → all milestones DONE → mark DONE
-```
-
-### Atomic Git Commits
-
-Every action gets its own commit:
-
-```
-feat(M-01): create database schema
-feat(M-01): implement auth service
-feat(M-01): build API endpoints
-```
-
-Git bisect finds the exact failing action. Each action is independently revertable.
-
-### Zero Runtime Dependencies
-
-The entire CLI bundles to a single `dist/declare-tools.cjs` via esbuild. No `node_modules` at runtime.
-
----
-
-## Fork Boundary
-
-Declare is forked from [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done), a meta-prompting and context engineering system for Claude Code.
-
-### What's Carried Forward
-
-- **Agent orchestration** — Planner, executor, researcher, verifier agent patterns
-- **Slash command interface** — `.claude/commands/` directory, markdown meta-prompts
-- **esbuild bundling** — Single-file CJS distribution, zero runtime deps
-- **Markdown artifacts** — `.planning/` directory as source of truth
-- **Atomic git commits** — Every state change produces a traceable commit
-- **Context engineering** — Fresh context per agent, structured XML plans
-
-### What's Replaced
-
-| GSD | Declare | Why |
-|-----|---------|-----|
-| Linear phases (1, 2, 3...) | Three-layer DAG (D → M → A) | Phases are past-derived sequencing; DAGs represent causal structure |
-| `ROADMAP.md` | `FUTURE.md` + `MILESTONES.md` | The present is given by the future you're living into |
-| Separate EXEC-PLAN files per action | Action list IS the plan | Actions define what to do; the executor gets full context automatically |
-| Sequential execution | Concurrent planning + execution | Multiple milestones plan/execute in parallel |
-| Phase numbers | Milestone IDs (M-XX) | Milestones derive from declarations, not arbitrary ordering |
-
----
-
 ## License
 
-MIT License. See [LICENSE](LICENSE) for details.
-
----
+MIT — See [LICENSE](LICENSE).
 
 <div align="center">
 

package/dist/declare-tools.cjs

@@ -1552,7 +1552,7 @@ var require_help = __commonJS({
             usage: "/declare:help"
           }
         ],
-        version: "1.0.1"
+        version: "1.0.4"
       };
     }
     module2.exports = { runHelp: runHelp2 };
@@ -8905,13 +8905,17 @@ data: ${JSON.stringify({ reason: "delete", nodeId: id })}
       });
     }
     async function startServer(cwd, port) {
-      const preferredPort = port || parseInt(process.env.PORT || "", 10) || 3847;
-      const resolvedPort = await findFreePort(preferredPort);
-      const server = createServer(cwd, resolvedPort);
-      await new Promise((resolve) => {
-        server.listen(resolvedPort, "127.0.0.1", () => {
+      const preferredPort = port || parseInt(process.env.PORT || "", 10) || 0;
+      const listenPort = preferredPort === 0 ? 0 : await findFreePort(preferredPort);
+      const server = createServer(cwd, listenPort);
+      const resolvedPort = await new Promise((resolve) => {
+        server.listen(listenPort, "127.0.0.1", () => {
+          const assigned = (
+            /** @type {import('net').AddressInfo} */
+            server.address().port
+          );
           watchPlanning(cwd);
-          resolve(void 0);
+          resolve(assigned);
         });
       });
       const portFilePath = require("path").join(cwd, ".planning", "server.port");
@@ -8941,7 +8945,6 @@ data: ${JSON.stringify({ reason: "delete", nodeId: id })}
 var require_serve = __commonJS({
   "src/commands/serve.js"(exports2, module2) {
     "use strict";
-    var { spawn } = require("child_process");
     var { startServer } = require_server();
     function parsePortFlag(args) {
       const idx = args.indexOf("--port");
@@ -8950,13 +8953,8 @@ var require_serve = __commonJS({
       return Number.isNaN(value) ? void 0 : value;
     }
     async function runServe2(cwd, args) {
-      const port = parsePortFlag(args) || parseInt(process.env.PORT || "", 10) || 3847;
+      const port = parsePortFlag(args);
       const { server, port: resolvedPort, url } = await startServer(cwd, port);
-      const noOpen = args.includes("--no-open") || process.env.DECLARE_NO_OPEN;
-      if (!noOpen) {
-        const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-        spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
-      }
       process.on("SIGINT", () => {
         server.close(() => process.exit(0));
       });
@@ -8991,12 +8989,17 @@ var require_open = __commonJS({
         });
       });
     }
-    async function waitForServer(port, maxAttempts = 10, intervalMs = 100) {
+    async function waitForPortFile(portFile, maxAttempts = 30, intervalMs = 200) {
       for (let i = 0; i < maxAttempts; i++) {
-        if (await checkServer(port)) return true;
+        try {
+          const content = fs.readFileSync(portFile, "utf8").trim();
+          const port = parseInt(content, 10);
+          if (!isNaN(port) && port > 0) return port;
+        } catch (_) {
+        }
         await new Promise((r) => setTimeout(r, intervalMs));
       }
-      return false;
+      return null;
     }
     async function runOpen2(cwd, args) {
       const planningDir = path.join(cwd, ".planning");
@@ -9008,25 +9011,33 @@ var require_open = __commonJS({
         }
       }
       const portFile = path.join(cwd, ".planning", "server.port");
-      const port = fs.existsSync(portFile) ? parseInt(fs.readFileSync(portFile, "utf8").trim(), 10) : 3847;
-      const isRunning = await checkServer(port);
-      if (!isRunning) {
-        const bundlePath = path.resolve(__dirname, "declare-tools.cjs");
-        const child = spawn(process.execPath, [bundlePath, "serve", "--port", String(port)], {
-          cwd,
-          detached: true,
-          stdio: "ignore"
-        });
-        child.unref();
-        const ready = await waitForServer(port);
-        if (!ready) {
-          console.error("[declare] Warning: server may not be ready yet");
+      if (fs.existsSync(portFile)) {
+        const existingPort = parseInt(fs.readFileSync(portFile, "utf8").trim(), 10);
+        if (!isNaN(existingPort) && existingPort > 0) {
+          const isRunning = await checkServer(existingPort);
+          if (isRunning) {
+            console.log(`Dashboard: http://localhost:${existingPort}`);
+            return;
+          }
+          try {
+            fs.unlinkSync(portFile);
+          } catch (_) {
+          }
         }
       }
-      const url = `http://localhost:${port}`;
-      const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-      spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
-      console.log(`Dashboard: ${url}`);
+      const bundlePath = path.resolve(__dirname, "declare-tools.cjs");
+      const child = spawn(process.execPath, [bundlePath, "serve"], {
+        cwd,
+        detached: true,
+        stdio: "ignore"
+      });
+      child.unref();
+      const port = await waitForPortFile(portFile);
+      if (!port) {
+        console.error("[declare] Server failed to start (no port file after 6s)");
+        process.exit(1);
+      }
+      console.log(`Dashboard: http://localhost:${port}`);
     }
     module2.exports = { runOpen: runOpen2 };
   }

package/package.json

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

package/scripts/release.js

@@ -40,7 +40,7 @@ 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}`);
+run(`git tag -f v${version}`);
 
 console.log(`
 Done. To publish: