declare-cc 1.0.4 → 1.0.7

package/README.md

@@ -37,7 +37,7 @@ Run it:
 npm run plan
 ```
 
-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.
+This auto-initializes a `.planning/` directory if one doesn't exist, starts the Declare server on a random free port, writes the port to `.planning/server.port`, and prints the dashboard URL.
 
 Or run directly:
 
@@ -59,7 +59,7 @@ You declare present-tense statements of fact about your project's future. The sy
 
 ## How It Works
 
-Everything happens through the dashboard. `dcl` opens it, and you drive the workflow with keyboard shortcuts and card-based UI.
+Everything happens through the dashboard. `dcl` starts the server and prints the URL — click it to open.
 
 ### 1. Declare Futures
 
@@ -125,9 +125,94 @@ Cards are grouped into stages at each level:
 | **Ctrl+Shift+A** | Approve all visible |
 | **C** | Command bar |
 
-### Server Discovery
+---
+
+## Server & Port Discovery
+
+The Declare server uses OS-assigned ports so multiple projects can run simultaneously without collisions.
+
+### How it works
+
+1. `dcl` (or `dcl serve`) starts the server on **port 0** — the OS assigns a random free port
+2. After the server is listening, it writes the port number to `.planning/server.port` (plain text, e.g. `62964`)
+3. On shutdown (SIGINT, SIGTERM, process exit), the file is deleted
+4. Next time `dcl` runs, it reads the port file. If the server is still alive, it reuses it. If the file is stale (server crashed), it cleans up and starts fresh.
+
+### For external tools
+
+To discover a running Declare server for a project:
+
+```js
+const port = fs.readFileSync('<project>/.planning/server.port', 'utf8').trim();
+// Verify it's alive:
+// GET http://localhost:<port>/api/graph → 200 = running
+// Embed dashboard:
+// <iframe src="http://localhost:<port>/" />
+```
+
+If the file doesn't exist, the server isn't running. Start it:
+
+```bash
+cd <project> && npx dcl serve
+```
+
+Then poll for `.planning/server.port` to appear (~1 second).
+
+### Explicit port
+
+If you need a specific port:
+
+```bash
+dcl serve --port 4000
+```
+
+---
+
+## For Agents
+
+If you're an AI agent (Claude Code, Cursor, etc.) working in a project that uses Declare, here's what you need to know:
+
+### Project state lives in `.planning/`
+
+- **`FUTURE.md`** — Declared futures (present-tense statements about what's true when the project succeeds)
+- **`MILESTONES.md`** — Milestones derived backward from futures
+- **`.planning/milestones/M-XX-slug/PLAN.md`** — Actions for each milestone (title, produces, causes)
+- **`.planning/STATE.md`** — Current project state and decisions
+- **`.planning/PROJECT.md`** — Project context and background
+
+### The DAG structure
+
+Declarations (D-XX) → Milestones (M-XX) → Actions (A-XX). Each layer links to the one above via `realizes` (milestones → declarations) and `causes` (actions → milestones). Read the graph with:
+
+```bash
+node_modules/.bin/declare-cc load-graph
+```
+
+Returns JSON with `declarations`, `milestones`, `actions` arrays.
+
+### Slash commands available to you
+
+If you're running inside Claude Code with declare-cc installed, these slash commands are available:
+
+- `/declare:status` — See where the project stands
+- `/declare:execute M-XX` — Execute actions for a milestone
+- `/declare:verify M-XX` — Validate deliverables
+- `/declare:trace A-XX` — Understand why an action exists (walk the why-chain)
+- `/declare:progress` — Find the next thing to work on
+- `/declare:help` — See all commands
+
+### Dashboard API
+
+If the server is running (check `.planning/server.port`), you can use the HTTP API:
 
-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.
+| Method | Path | Returns |
+|--------|------|---------|
+| GET | `/api/graph` | Full DAG (declarations, milestones, actions) |
+| GET | `/api/status` | Integrity/alignment metrics |
+| GET | `/api/agents` | Running/completed agents |
+| GET | `/api/events` | SSE stream (real-time updates) |
+| POST | `/api/review` | Approve/reject a node |
+| POST | `/api/action/:id/execute` | Execute an action |
 
 ---
 
@@ -145,7 +230,7 @@ The dashboard is the primary interface. All operations are also available as sla
 | `/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:dashboard` | Start server and print URL |
 | `/declare:help` | Show all commands |
 
 ---

package/dist/declare-tools.cjs

@@ -1552,7 +1552,7 @@ var require_help = __commonJS({
             usage: "/declare:help"
           }
         ],
-        version: "1.0.4"
+        version: "1.0.7"
       };
     }
     module2.exports = { runHelp: runHelp2 };
@@ -4302,7 +4302,7 @@ var require_ai_runner = __commonJS({
         const env = { ...process.env };
         delete env.CLAUDECODE;
         const queryOpts = {
-          model: opts.model || "haiku",
+          model: opts.model || "sonnet",
           maxTurns: opts.maxTurns || 1,
           cwd: opts.cwd || process.cwd(),
           abortController,
@@ -4712,7 +4712,7 @@ data: ${JSON.stringify(data)}
         sessions.set(sessionId, { milestoneId: milestone.id, agentId, abortController, startTime: Date.now() });
         runAI(prompt, {
           cwd,
-          model: "haiku",
+          model: "opus",
           maxTurns: 1,
           abortController,
           onText: (text) => {
@@ -7396,7 +7396,7 @@ If the current version is already good, output exactly: LGTM \u2014 no changes n
         const isWriteMode = mode === "write";
         runAI(prompt, {
           cwd,
-          model: "haiku",
+          model: "opus",
           maxTurns: isWriteMode ? 10 : 1,
           withTools: isWriteMode,
           abortController,
@@ -7608,7 +7608,7 @@ The options array is optional \u2014 include it only when there are clear altern
         discussSession = { sessionId, nodeId: id, abortController, agentId };
         runAI(prompt, {
           cwd,
-          model: "haiku",
+          model: "opus",
           maxTurns: 1,
           abortController,
           onText: (text) => {
@@ -7944,7 +7944,7 @@ The options array is optional \u2014 include it only when there are clear altern
         persistOnboardSession(cwd);
         runAI(prompt, {
           cwd,
-          model: "haiku",
+          model: "opus",
           maxTurns: 1,
           abortController,
           onText: (text) => {
@@ -8723,6 +8723,10 @@ data: ${JSON.stringify({ reason: "delete", nodeId: id })}
         req.on("close", () => sseClients.delete(res));
         return;
       }
+      if (urlPath === "/api/version") {
+        sendJson(res, 200, { version: true ? "1.0.7" : "dev" });
+        return;
+      }
       if (urlPath === "/api/graph") {
         handleGraph(res, cwd);
         return;

package/dist/public/app.js

@@ -8722,8 +8722,6 @@ function cancelOnboard() {
 }
 
 function startOnboardApproving(mode) {
-  onboardPhase = 'approving';
-  onboardApproveIndex = 0;
   if (mode === 'all') {
     approveAllOnboard();
   } else {
@@ -8731,6 +8729,62 @@ function startOnboardApproving(mode) {
   }
 }
 
+async function approveOnboardByIndex(idx) {
+  if (!onboardProposals || idx >= onboardProposals.length) return;
+  const proposal = onboardProposals[idx];
+  if (proposal.approvedId) return; // already approved
+  try {
+    const resp = await fetch('/api/onboard/approve', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: proposal.title, statement: proposal.statement }),
+    });
+    const data = await resp.json();
+    if (data.id) proposal.approvedId = data.id;
+  } catch (_) {}
+
+  // Check if all done
+  const remaining = onboardProposals.filter(p => !p.approvedId).length;
+  if (remaining === 0) {
+    onboardPhase = 'idle';
+    onboardPrompt = null;
+    onboardQuestions = null;
+    onboardProposals = null;
+    fetch('/api/onboard/complete', { method: 'POST' }).catch(() => {});
+    loadData().then(() => renderDrillView());
+    loadActivity();
+  } else {
+    renderOnboardUI();
+  }
+}
+
+function editOnboardByIndex(idx) {
+  if (!onboardProposals || idx >= onboardProposals.length) return;
+  const proposal = onboardProposals[idx];
+  const card = document.querySelector(`[data-onboard-idx="${idx}"]`);
+  if (!card) return;
+  const body = card.querySelector('.drill-card-body');
+  if (!body) return;
+  body.innerHTML = `
+    <input class="onboard-title" value="${escHtml(proposal.title)}" style="width:100%;margin-bottom:4px" />
+    <textarea class="onboard-statement" rows="2" style="width:100%">${escHtml(proposal.statement)}</textarea>
+    <div style="margin-top:6px">
+      <button class="drill-review-btn approve-btn onboard-save-btn" data-onboard-idx="${idx}">Save</button>
+      <button class="drill-action-btn onboard-cancel-edit-btn" data-onboard-idx="${idx}">Cancel</button>
+    </div>
+  `;
+  const titleInput = body.querySelector('.onboard-title');
+  if (titleInput) titleInput.focus();
+  body.querySelector('.onboard-save-btn').addEventListener('click', () => {
+    proposal.title = body.querySelector('.onboard-title').value.trim() || proposal.title;
+    proposal.statement = body.querySelector('.onboard-statement').value.trim() || proposal.statement;
+    renderOnboardUI();
+  });
+  body.querySelector('.onboard-cancel-edit-btn').addEventListener('click', () => {
+    renderOnboardUI();
+  });
+}
+
 async function approveCurrentOnboard() {
   if (!onboardProposals || onboardApproveIndex >= onboardProposals.length) return;
 
@@ -8853,53 +8907,62 @@ function renderOnboardUI() {
       `;
     } else {
       let html = '<div class="onboard-phase-label">Proposed Declarations</div>';
+      html += '<div class="drill-cards onboard-cards">';
       onboardProposals.forEach((p, i) => {
-        html += `<div class="onboard-proposal">
-          <div class="op-header">
-            <span class="op-index">${i + 1}.</span>
+        const isApproved = !!p.approvedId;
+        html += `<div class="drill-card${isApproved ? '' : ' needs-review'}${!isApproved && i === 0 ? ' current-review' : ''}" data-onboard-idx="${i}">
+          <div class="drill-card-top">
+            <span class="drill-card-id">${isApproved ? escHtml(p.approvedId) : (i + 1) + '.'}</span>
+            <div class="drill-card-body">
+              <div class="drill-card-title">${escHtml(p.title)}</div>
+              <div class="drill-card-desc">${escHtml(p.statement)}</div>
+              ${p.reasoning ? `<div class="drill-card-desc" style="opacity:0.5;font-style:italic;margin-top:4px">${escHtml(p.reasoning)}</div>` : ''}
+            </div>
+          </div>
+          <div class="drill-card-actions">
+            ${isApproved
+              ? '<span style="color:var(--approved-color);font-weight:600;font-size:12px">Approved</span>'
+              : `<button class="drill-review-btn approve-btn" data-onboard-action="approve" data-onboard-idx="${i}"><kbd>A</kbd> Approve</button>
+                 <button class="drill-action-btn" data-onboard-action="edit" data-onboard-idx="${i}"><kbd>E</kbd> Edit</button>
+                 <button class="drill-action-btn drill-action-danger" data-onboard-action="delete" data-onboard-idx="${i}"><kbd>D</kbd> Delete</button>`
+            }
           </div>
-          <input class="onboard-title" value="${escHtml(p.title)}" />
-          <textarea class="onboard-statement" rows="2">${escHtml(p.statement)}</textarea>
-          <div class="onboard-reason">${escHtml(p.reasoning || '')}</div>
         </div>`;
       });
-      html += `<div class="onboard-actions">
-        <button class="onboard-btn-primary" onclick="startOnboardApproving('all')">Approve All</button>
-        <button class="onboard-btn-secondary" onclick="startOnboardApproving('one')">One by One</button>
-        <button class="onboard-btn-secondary" onclick="cancelOnboard()">Cancel</button>
-      </div>`;
+      html += '</div>';
+      const unapprovedCount = onboardProposals.filter(p => !p.approvedId).length;
+      if (unapprovedCount > 0) {
+        html += `<div class="onboard-actions">
+          <button class="onboard-btn-primary" onclick="startOnboardApproving('all')"><kbd>⌃⇧A</kbd> Approve All (${unapprovedCount})</button>
+          <button class="onboard-btn-secondary" onclick="cancelOnboard()">Cancel</button>
+        </div>`;
+      }
       container.innerHTML = html;
+
+      // Wire card buttons
+      setTimeout(() => {
+        container.querySelectorAll('[data-onboard-action]').forEach(btn => {
+          btn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            const idx = parseInt(btn.dataset.onboardIdx);
+            const action = btn.dataset.onboardAction;
+            if (action === 'approve') {
+              approveOnboardByIndex(idx);
+            } else if (action === 'edit') {
+              editOnboardByIndex(idx);
+            } else if (action === 'delete') {
+              onboardProposals.splice(idx, 1);
+              renderOnboardUI();
+            }
+          });
+        });
+      }, 0);
     }
   } else if (onboardPhase === 'approving') {
-    if (!onboardProposals) return;
-    let html = `<div class="onboard-phase-label">Approving Declarations</div>`;
-    html += `<div class="onboard-progress">${onboardApproveIndex} of ${onboardProposals.length} approved</div>`;
-    onboardProposals.forEach((p, i) => {
-      const isApproved = i < onboardApproveIndex || p.approvedId;
-      const isCurrent = i === onboardApproveIndex && !p.approvedId;
-      const cls = isApproved ? 'approved' : isCurrent ? 'current' : '';
-      html += `<div class="onboard-proposal ${cls}">
-        <div class="op-header">
-          ${isApproved ? '<span class="op-check">\u2713</span>' : `<span class="op-index">${i + 1}.</span>`}
-          ${p.approvedId ? `<span class="op-id">${escHtml(p.approvedId)}</span>` : ''}
-        </div>
-        ${isCurrent ? `
-          <input class="onboard-title" value="${escHtml(p.title)}" />
-          <textarea class="onboard-statement" rows="2">${escHtml(p.statement)}</textarea>
-        ` : `
-          <div style="font-weight:600;font-size:13px">${escHtml(p.title)}</div>
-          <div style="font-size:12px;color:var(--text-dim);margin-top:4px">${escHtml(p.statement)}</div>
-        `}
-        <div class="onboard-reason">${escHtml(p.reasoning || '')}</div>
-      </div>`;
-    });
-    if (onboardApproveIndex < onboardProposals.length) {
-      html += `<div class="onboard-actions">
-        <button class="onboard-btn-primary" onclick="approveCurrentOnboard()">Approve &amp; Next</button>
-        <button class="onboard-btn-secondary" onclick="cancelOnboard()">Cancel</button>
-      </div>`;
-    }
-    container.innerHTML = html;
+    // Redirect to proposals view — approving is now inline
+    onboardPhase = 'proposals';
+    renderOnboardUI();
+    return;
   }
 
   $drillList.appendChild(container);
@@ -9013,5 +9076,11 @@ loadData().then(() => {
 loadActivity();
 loadAgentCards();
 
+// Version label
+fetch('/api/version').then(r => r.json()).then(d => {
+  const el = document.getElementById('version-label');
+  if (el && d.version) el.textContent = 'v' + d.version;
+}).catch(() => {});
+
 // Poll agent cards every 3s as fallback if SSE agent events are missed
 setInterval(loadAgentCards, 3000);

package/dist/public/index.html

@@ -1187,6 +1187,15 @@
     @keyframes derive-spin {
       to { transform: rotate(360deg); }
     }
+    #version-label {
+      position: fixed;
+      bottom: 6px;
+      left: 8px;
+      font-size: 10px;
+      color: #555;
+      pointer-events: none;
+      z-index: 1;
+    }
     .derive-card-status {
       display: inline-flex;
       align-items: center;
@@ -4277,6 +4286,7 @@
   </div>
 </div>
 
-<script src="/public/app.js?v=25"></script>
+<div id="version-label"></div>
+<script src="/public/app.js?v=27"></script>
 </body>
 </html>

package/package.json

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