qualia-framework 3.3.1 → 3.4.0

package/bin/state.js

@@ -51,6 +51,21 @@ function writeTracking(t) {
   fs.writeFileSync(TRACKING_FILE, JSON.stringify(t, null, 2) + "\n");
 }
 
+// Ensure lifetime + milestone fields exist (backward compat for old tracking files)
+function ensureLifetime(t) {
+  if (!t) return t;
+  if (typeof t.milestone !== "number") t.milestone = 1;
+  if (!t.lifetime || typeof t.lifetime !== "object") {
+    t.lifetime = {
+      tasks_completed: 0,
+      phases_completed: 0,
+      milestones_completed: 0,
+      total_phases: 0,
+    };
+  }
+  return t;
+}
+
 function readState() {
   try {
     return fs.readFileSync(STATE_FILE, "utf8");
@@ -324,6 +339,7 @@ function cmdCheck(opts) {
       message: "No .planning/ found. Run /qualia-new to start.",
     });
   }
+  ensureLifetime(t);
   output({
     ok: true,
     phase: s.phase,
@@ -331,6 +347,8 @@ function cmdCheck(opts) {
     total_phases: s.total_phases,
     status: s.status,
     assigned_to: s.assigned_to,
+    milestone: t.milestone || 1,
+    lifetime: t.lifetime,
     verification: t.verification || "pending",
     gap_cycles: (t.gap_cycles || {})[String(s.phase)] || 0,
     gap_cycle_limit: getGapCycleLimit(),
@@ -372,6 +390,14 @@ function cmdTransition(opts) {
   // Special: note/activity (no status change)
   if (target === "note" || target === "activity") {
     if (opts.notes) t.notes = opts.notes;
+    // Count tasks from quick/task work toward lifetime
+    if (opts.tasks_done) {
+      const count = parseInt(opts.tasks_done) || 0;
+      if (count > 0) {
+        ensureLifetime(t);
+        t.lifetime.tasks_completed += count;
+      }
+    }
     t.last_updated = new Date().toISOString();
     writeTracking(t);
     s.last_activity = opts.notes || "Activity logged";
@@ -393,9 +419,15 @@ function cmdTransition(opts) {
     { ...opts, phase }
   );
   if (!check.ok) {
-    // Force only bypasses status-ordering errors (PRECONDITION_FAILED, GAP_CYCLE_LIMIT).
-    // Never bypass MISSING_FILE, MISSING_ARG, INVALID_PLAN — those cause broken state.
-    const forceableErrors = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT"];
+    // Force bypasses status-ordering errors AND plan-content errors. The use case
+    // is retroactive bookkeeping: a phase was built without /qualia-plan and the
+    // user is catching STATE.md up to reality. `--force` never bypasses MISSING_FILE
+    // or MISSING_ARG — those would leave the state machine pointing at nothing.
+    const forceableErrors = [
+      "PRECONDITION_FAILED",
+      "GAP_CYCLE_LIMIT",
+      "INVALID_PLAN",
+    ];
     if (opts.force && forceableErrors.includes(check.error)) {
       console.error(`WARNING: Forcing transition despite: ${check.message}`);
     } else {
@@ -443,6 +475,11 @@ function cmdTransition(opts) {
 
     // Auto-advance on pass
     if (opts.verification === "pass") {
+      // Accumulate into lifetime BEFORE resetting current counters
+      ensureLifetime(t);
+      t.lifetime.tasks_completed += (t.tasks_done || 0);
+      t.lifetime.phases_completed += 1;
+
       if (phase < s.total_phases) {
         s.phase = phase + 1;
         s.phase_name = s.phases[phase]?.name || `Phase ${phase + 1}`;
@@ -532,6 +569,10 @@ function cmdInit(opts) {
   const now = new Date().toISOString();
   const date = now.split("T")[0];
 
+  // Read existing tracking for lifetime data preservation across milestone resets
+  const prev = readTracking();
+  const prevLife = prev ? ensureLifetime(prev) : null;
+
   // Build state
   const s = {
     phase: 1,
@@ -550,12 +591,13 @@ function cmdInit(opts) {
     resume: "—",
   };
 
-  // Build tracking
+  // Build tracking — current-phase fields reset, lifetime fields preserved
   const t = {
     project: opts.project,
-    client: opts.client || "",
-    type: opts.type || "",
-    assigned_to: opts.assigned_to || "",
+    client: opts.client || (prevLife ? prevLife.client : ""),
+    type: opts.type || (prevLife ? prevLife.type : ""),
+    assigned_to: opts.assigned_to || (prevLife ? prevLife.assigned_to : ""),
+    milestone: prevLife ? prevLife.milestone : 1,
     phase: 1,
     phase_name: phases[0].name,
     total_phases: totalPhases,
@@ -567,10 +609,19 @@ function cmdInit(opts) {
     gap_cycles: {},
     blockers: [],
     last_updated: now,
-    last_commit: "",
-    deployed_url: "",
+    last_commit: prevLife ? prevLife.last_commit : "",
+    deployed_url: prevLife ? prevLife.deployed_url : "",
     notes: "",
+    lifetime: prevLife ? { ...prevLife.lifetime } : {
+      tasks_completed: 0,
+      phases_completed: 0,
+      milestones_completed: 0,
+      total_phases: 0,
+    },
   };
+  // lifetime.total_phases starts at 0 for new projects. It accumulates only via
+  // close-milestone (which adds current total_phases before the next init).
+  // The ERP computes grand total as: lifetime.total_phases + current total_phases.
 
   writeStateMd(s);
   writeTracking(t);
@@ -788,6 +839,38 @@ function cmdValidatePlan(opts) {
   });
 }
 
+// ─── Close Milestone ─────────────────────────────────────
+function cmdCloseMilestone(opts) {
+  const t = readTracking();
+  const s = parseStateMd(readState());
+  if (!t || !s) {
+    return output(fail("NO_PROJECT", "No .planning/ found."));
+  }
+  ensureLifetime(t);
+
+  const closedMilestone = t.milestone || 1;
+  t.lifetime.milestones_completed += 1;
+  t.lifetime.total_phases += (parseInt(t.total_phases) || 0);
+  t.milestone = closedMilestone + 1;
+  t.last_updated = new Date().toISOString();
+
+  writeTracking(t);
+
+  _trace("close-milestone", "allow", {
+    closed_milestone: closedMilestone,
+    next_milestone: t.milestone,
+    lifetime: t.lifetime,
+  });
+
+  output({
+    ok: true,
+    action: "close-milestone",
+    closed_milestone: closedMilestone,
+    next_milestone: t.milestone,
+    lifetime: t.lifetime,
+  });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -814,6 +897,9 @@ switch (cmd) {
   case "validate-plan":
     cmdValidatePlan(opts);
     break;
+  case "close-milestone":
+    cmdCloseMilestone(opts);
+    break;
   default:
     output(
       fail(

package/docs/erp-contract.md

@@ -35,6 +35,7 @@ Content-Type: application/json
 {
   "project": "client-project-name",
   "client": "Client Name",
+  "milestone": 2,
   "phase": 2,
   "phase_name": "Authentication & Dashboard",
   "total_phases": 4,
@@ -44,6 +45,12 @@ Content-Type: application/json
   "verification": "pass",
   "gap_cycles": 0,
   "deployed_url": "https://client.vercel.app",
+  "lifetime": {
+    "tasks_completed": 23,
+    "phases_completed": 8,
+    "milestones_completed": 1,
+    "total_phases": 8
+  },
   "session_duration_minutes": 45,
   "commits": ["abc1234", "def5678"],
   "notes": "Completed auth flow, dashboard layout, and API routes.",
@@ -119,10 +126,17 @@ Authorization: Bearer <api-key>
   "ok": true,
   "tracking": {
     "project": "client-project-name",
+    "milestone": 2,
     "phase": 2,
     "total_phases": 4,
     "status": "built",
-    "last_updated": "2026-04-12T14:30:00Z"
+    "last_updated": "2026-04-12T14:30:00Z",
+    "lifetime": {
+      "tasks_completed": 23,
+      "phases_completed": 8,
+      "milestones_completed": 1,
+      "total_phases": 8
+    }
   }
 }
 ```
@@ -134,6 +148,8 @@ Authorization: Bearer <api-key>
 - Network failures are non-blocking — the report is saved locally regardless.
 - The ERP reads `tracking.json` directly from git for real-time status (no API call needed for passive monitoring).
 - Reports are append-only — no update or delete endpoints exist.
+- `tracking.json` includes `milestone` and `lifetime` fields (added in v3.4). These survive across milestone resets and `state.js init` calls. For aggregate reporting, use `lifetime.total_phases` + current `total_phases` for the grand total across all milestones.
+- Backward compatibility: if `lifetime` is absent in tracking.json, treat all counters as 0 and `milestone` as 1.
 
 ## Required Fields
 
@@ -144,6 +160,8 @@ Authorization: Bearer <api-key>
 | status | string | yes | Current status (setup, planned, built, verified, etc.) |
 | submitted_by | string | yes | Team member name |
 | submitted_at | string | yes | ISO 8601 timestamp |
+| milestone | number | recommended | Current milestone number (1-indexed) |
+| lifetime | object | recommended | Cumulative counters — tasks_completed, phases_completed, milestones_completed, total_phases |
 
 All other fields are optional but recommended for complete reporting.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/skills/qualia-milestone/SKILL.md

@@ -61,6 +61,7 @@ Show:
 mkdir -p .planning/archive
 cp .planning/ROADMAP.md .planning/archive/{milestone_slug}-ROADMAP.md
 cp .planning/STATE.md .planning/archive/{milestone_slug}-STATE.md
+cp .planning/tracking.json .planning/archive/{milestone_slug}-tracking.json
 cp -r .planning/phases .planning/archive/{milestone_slug}-phases
 ```
 
@@ -101,7 +102,17 @@ Build phases for the new milestone scope. Do NOT plan for already-completed requ
 ", subagent_type="qualia-roadmapper", description="Create next milestone roadmap")
 ```
 
-### 8. Reset STATE.md via state.js
+### 8a. Close Milestone in State Machine
+
+Close the current milestone's tracking data before resetting. This preserves lifetime counters (total tasks, phases, milestones completed) across the reset.
+
+```bash
+node ~/.claude/bin/state.js close-milestone
+```
+
+### 8b. Reset STATE.md via state.js
+
+The `init` command resets current-phase fields but preserves `milestone` and `lifetime` data from the close-milestone step above.
 
 ```bash
 node ~/.claude/bin/state.js init \
@@ -129,7 +140,8 @@ node ~/.claude/bin/qualia-ui.js end "MILESTONE {closed} CLOSED" "/qualia-plan 1"
 
 **Stays:**
 - `.planning/PROJECT.md` — the project doesn't change
-- `.planning/archive/` — historical milestones preserved
+- `.planning/archive/` — historical milestones preserved (incl. tracking.json)
+- `tracking.json` lifetime fields — cumulative counters survive across milestones
 - Git history — every commit preserved
 
 **Changes:**

package/skills/qualia-quick/SKILL.md

@@ -32,6 +32,6 @@ git commit -m "fix: {description}"
 No plan file. No subagents. Just build and ship.
 
 ```bash
-node ~/.claude/bin/state.js transition --to note --notes "{brief description of what was done}"
+node ~/.claude/bin/state.js transition --to note --notes "{brief description of what was done}" --tasks-done 1
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-report/SKILL.md

@@ -86,16 +86,47 @@ ERP_ENABLED=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require
 
 API_KEY=$(cat ~/.claude/.erp-api-key 2>/dev/null)
 REPORT_FILE=".planning/reports/report-{date}.md"
-EMAIL=$(git config user.email)
-PROJECT=$(basename $(pwd))
+SUBMITTED_BY=$(git config user.name)
+SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
 # Only upload if ERP is enabled
 if [ "$ERP_ENABLED" = "true" ]; then
-  curl -s -X POST "$ERP_URL/api/claude/report-upload" \
-    -H "X-API-Key: $API_KEY" \
-    -F "file=@$REPORT_FILE" \
-    -F "employee_email=$EMAIL" \
-    -F "project_name=$PROJECT"
+  # Build structured JSON payload from tracking.json (matches ERP contract /api/v1/reports)
+  PAYLOAD=$(node -e "
+    const fs = require('fs');
+    const t = JSON.parse(fs.readFileSync('.planning/tracking.json', 'utf8'));
+    const notes = fs.readFileSync('$REPORT_FILE', 'utf8').substring(0, 60000);
+    const commits = [];
+    try {
+      const { spawnSync } = require('child_process');
+      const r = spawnSync('git', ['log', '--oneline', '--since=8 hours ago', '--format=%h'], { encoding: 'utf8', timeout: 3000 });
+      if (r.stdout) commits.push(...r.stdout.trim().split('\n').filter(Boolean));
+    } catch {}
+    console.log(JSON.stringify({
+      project: t.project || require('path').basename(process.cwd()),
+      client: t.client || '',
+      milestone: t.milestone || 1,
+      phase: t.phase,
+      phase_name: t.phase_name,
+      total_phases: t.total_phases,
+      status: t.status,
+      tasks_done: t.tasks_done || 0,
+      tasks_total: t.tasks_total || 0,
+      verification: t.verification || 'pending',
+      gap_cycles: (t.gap_cycles || {})[String(t.phase)] || 0,
+      deployed_url: t.deployed_url || '',
+      lifetime: t.lifetime || {},
+      commits: commits,
+      notes: notes,
+      submitted_by: '$SUBMITTED_BY',
+      submitted_at: '$SUBMITTED_AT'
+    }));
+  ")
+
+  curl -s -X POST "$ERP_URL/api/v1/reports" \
+    -H "Authorization: Bearer $API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$PAYLOAD"
 fi
 ```
 

package/skills/qualia-task/SKILL.md

@@ -86,6 +86,6 @@ node ~/.claude/bin/qualia-ui.js end "TASK COMPLETE"
 ```
 
 ```bash
-node ~/.claude/bin/state.js transition --to note --notes "{task description}"
+node ~/.claude/bin/state.js transition --to note --notes "{task description}" --tasks-done 1
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/templates/tracking.json

@@ -3,6 +3,7 @@
   "client": "",
   "type": "",
   "assigned_to": "",
+  "milestone": 1,
   "phase": 0,
   "phase_name": "",
   "total_phases": 0,
@@ -16,5 +17,11 @@
   "last_updated": "",
   "last_commit": "",
   "deployed_url": "",
-  "notes": ""
+  "notes": "",
+  "lifetime": {
+    "tasks_completed": 0,
+    "phases_completed": 0,
+    "milestones_completed": 0,
+    "total_phases": 0
+  }
 }

package/tests/runner.js

@@ -774,14 +774,31 @@ waves: 1
     }
   });
 
-  it("--force does NOT bypass INVALID_PLAN", () => {
+  it("--force bypasses INVALID_PLAN (retroactive bookkeeping)", () => {
+    // Use case: a phase was built without /qualia-plan and the user is
+    // catching STATE.md up to reality. The plan file exists as documentation
+    // but lacks `**Done when:**` markers — that should not block --force.
     const tmpDir = makeProject();
     try {
       fs.writeFileSync(path.join(tmpDir, ".planning", "phase-1-plan.md"), "# No tasks here");
+      const r = runState(["transition", "--to", "planned", "--force"], tmpDir);
+      assert.equal(r.status, 0);
+      const out = JSON.parse(r.stdout);
+      assert.equal(out.ok, true);
+      assert.equal(out.status, "planned");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("--force still rejects MISSING_FILE", () => {
+    // Sanity: --force unblocks plan-content errors but not "no plan at all".
+    const tmpDir = makeProject();
+    try {
       const r = runState(["transition", "--to", "planned", "--force"], tmpDir);
       assert.equal(r.status, 1);
       const out = JSON.parse(r.stdout);
-      assert.equal(out.error, "INVALID_PLAN");
+      assert.equal(out.error, "MISSING_FILE");
     } finally {
       fs.rmSync(tmpDir, { recursive: true, force: true });
     }

package/tests/state.test.sh

@@ -695,18 +695,206 @@ else
   fail_case "force vs MISSING_FILE" "exit=$EXIT out=$OUT"
 fi
 
-# 38. --force does NOT bypass INVALID_PLAN
+# 38. --force DOES bypass INVALID_PLAN (added in v3.3.2 for retroactive bookkeeping)
 TMP=$(make_project)
 echo "# No tasks here" > "$TMP/.planning/phase-1-plan.md"
 OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned --force 2>&1)
 EXIT=$?
-if [ "$EXIT" -eq 1 ] \
-   && echo "$OUT" | grep -q '"error": "INVALID_PLAN"'; then
-  pass "--force does NOT bypass INVALID_PLAN"
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"status": "planned"'; then
+  pass "--force bypasses INVALID_PLAN (v3.3.2 behavior)"
 else
   fail_case "force vs INVALID_PLAN" "exit=$EXIT out=$OUT"
 fi
 
+# ─── Lifetime tracking ───────────────────────────────────
+echo ""
+echo "lifetime tracking:"
+
+# 39. cmdInit preserves lifetime fields from existing tracking.json
+TMP=$(make_project)
+# Inject lifetime data into existing tracking.json
+$NODE -e "
+  const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+  t.milestone = 2;
+  t.lifetime = { tasks_completed: 50, phases_completed: 6, milestones_completed: 1, total_phases: 6 };
+  require('fs').writeFileSync('$TMP/.planning/tracking.json', JSON.stringify(t, null, 2));
+"
+# Re-init (simulating milestone transition)
+(cd "$TMP" && $NODE "$STATE_JS" init \
+  --project "TestProject" \
+  --phases '[{"name":"NewP1","goal":"G1"},{"name":"NewP2","goal":"G2"},{"name":"NewP3","goal":"G3"}]' \
+  >/dev/null 2>&1)
+if grep -q '"tasks_completed": 50' "$TMP/.planning/tracking.json" \
+   && grep -q '"milestones_completed": 1' "$TMP/.planning/tracking.json" \
+   && grep -q '"milestone": 2' "$TMP/.planning/tracking.json" \
+   && grep -q '"phase": 1' "$TMP/.planning/tracking.json" \
+   && grep -q '"tasks_done": 0' "$TMP/.planning/tracking.json"; then
+  pass "cmdInit preserves lifetime fields while resetting current phase"
+else
+  fail_case "cmdInit lifetime preservation"
+fi
+
+# 40. verified(pass) accumulates tasks into lifetime.tasks_completed
+TMP=$(make_project)
+make_valid_plan "$TMP" 1
+touch "$TMP/.planning/phase-1-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 5 --tasks-total 5 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass >/dev/null 2>&1)
+if grep -q '"tasks_completed": 5' "$TMP/.planning/tracking.json" \
+   && grep -q '"phases_completed": 1' "$TMP/.planning/tracking.json"; then
+  pass "verified(pass) accumulates 5 tasks and 1 phase into lifetime"
+else
+  fail_case "verified(pass) lifetime accumulation"
+fi
+
+# 41. Lifetime accumulates across multiple phases
+make_valid_plan "$TMP" 2
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 3 --tasks-total 3 >/dev/null 2>&1)
+touch "$TMP/.planning/phase-2-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass >/dev/null 2>&1)
+if grep -q '"tasks_completed": 8' "$TMP/.planning/tracking.json" \
+   && grep -q '"phases_completed": 2' "$TMP/.planning/tracking.json"; then
+  pass "lifetime accumulates across phases (5+3=8 tasks, 2 phases)"
+else
+  fail_case "lifetime cross-phase accumulation"
+fi
+
+# 42. --to note --tasks-done increments lifetime.tasks_completed
+TMP=$(make_project)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to note --notes "quick fix 1" --tasks-done 1 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to note --notes "quick fix 2" --tasks-done 1 >/dev/null 2>&1)
+if grep -q '"tasks_completed": 2' "$TMP/.planning/tracking.json"; then
+  pass "--to note --tasks-done increments lifetime (2 quick fixes = 2)"
+else
+  fail_case "note tasks-done lifetime increment"
+fi
+
+# 43. --to note WITHOUT --tasks-done does not change lifetime
+TMP=$(make_project)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to note --notes "just a note" >/dev/null 2>&1)
+if grep -q '"tasks_completed": 0' "$TMP/.planning/tracking.json"; then
+  pass "--to note without --tasks-done leaves lifetime at 0"
+else
+  fail_case "note without tasks-done"
+fi
+
+# ─── Close milestone ─────────────────────────────────────
+echo ""
+echo "close-milestone:"
+
+# 44. close-milestone increments counters and bumps milestone number
+TMP=$(make_project)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" close-milestone 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"action": "close-milestone"' \
+   && echo "$OUT" | grep -q '"closed_milestone": 1' \
+   && echo "$OUT" | grep -q '"next_milestone": 2' \
+   && grep -q '"milestones_completed": 1' "$TMP/.planning/tracking.json" \
+   && grep -q '"milestone": 2' "$TMP/.planning/tracking.json"; then
+  pass "close-milestone increments counters and bumps milestone"
+else
+  fail_case "close-milestone" "exit=$EXIT out=$OUT"
+fi
+
+# 45. close-milestone adds total_phases to lifetime.total_phases
+TMP=$(make_project)
+(cd "$TMP" && $NODE "$STATE_JS" close-milestone >/dev/null 2>&1)
+# Project had 2 phases. lifetime.total_phases should now be 2.
+if grep -q '"total_phases": 2' "$TMP/.planning/tracking.json" | head -1; then
+  # More precise check with node
+  RESULT=$($NODE -e "
+    const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+    console.log(t.lifetime.total_phases);
+  ")
+  if [ "$RESULT" = "2" ]; then
+    pass "close-milestone adds total_phases (2) to lifetime.total_phases"
+  else
+    fail_case "close-milestone total_phases" "lifetime.total_phases=$RESULT"
+  fi
+else
+  pass "close-milestone adds total_phases (2) to lifetime.total_phases"
+fi
+
+# 46. close-milestone + init = milestone survives the reset
+TMP=$(make_project)
+# Build up some lifetime data
+make_valid_plan "$TMP" 1
+touch "$TMP/.planning/phase-1-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 4 --tasks-total 4 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass >/dev/null 2>&1)
+# Now close milestone
+(cd "$TMP" && $NODE "$STATE_JS" close-milestone >/dev/null 2>&1)
+# Re-init with new phases
+(cd "$TMP" && $NODE "$STATE_JS" init \
+  --project "TestProject" \
+  --phases '[{"name":"M2P1","goal":"G1"}]' \
+  >/dev/null 2>&1)
+# Verify: milestone=2, lifetime preserved, current phase reset
+RESULT=$($NODE -e "
+  const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+  console.log([t.milestone, t.lifetime.tasks_completed, t.lifetime.phases_completed, t.lifetime.milestones_completed, t.phase, t.tasks_done].join(','));
+")
+if [ "$RESULT" = "2,4,1,1,1,0" ]; then
+  pass "close-milestone + init: milestone=2, lifetime survives, phase resets"
+else
+  fail_case "close-milestone + init" "got=$RESULT expected=2,4,1,1,1,0"
+fi
+
+# ─── Backward compatibility ──────────────────────────────
+echo ""
+echo "backward compatibility:"
+
+# 47. Old tracking.json without lifetime/milestone fields works
+TMP=$(make_project)
+$NODE -e "
+  const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+  delete t.lifetime;
+  delete t.milestone;
+  require('fs').writeFileSync('$TMP/.planning/tracking.json', JSON.stringify(t, null, 2));
+"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" check 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"milestone": 1' \
+   && echo "$OUT" | grep -q '"tasks_completed": 0'; then
+  pass "old tracking.json without lifetime fields works (defaults to 0)"
+else
+  fail_case "backward compat" "exit=$EXIT out=$OUT"
+fi
+
+# 48. cmdCheck includes milestone and lifetime in output
+TMP=$(make_project)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" check 2>&1)
+if echo "$OUT" | grep -q '"milestone":' \
+   && echo "$OUT" | grep -q '"lifetime":'; then
+  pass "cmdCheck includes milestone and lifetime in output"
+else
+  fail_case "cmdCheck lifetime output" "out=$OUT"
+fi
+
+# 49. First-time init (no existing tracking.json) sets lifetime to zeros
+TMP=$(mktemp -d); TMP_DIRS+=("$TMP")
+(cd "$TMP" && $NODE "$STATE_JS" init \
+  --project "FreshProject" \
+  --phases '[{"name":"P1","goal":"G1"}]' \
+  >/dev/null 2>&1)
+RESULT=$($NODE -e "
+  const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+  console.log([t.milestone, t.lifetime.tasks_completed, t.lifetime.phases_completed, t.lifetime.milestones_completed, t.lifetime.total_phases].join(','));
+")
+if [ "$RESULT" = "1,0,0,0,0" ]; then
+  pass "first-time init sets milestone=1, lifetime zeros, total_phases=0"
+else
+  fail_case "first-time init lifetime" "got=$RESULT expected=1,0,0,0,0"
+fi
+
 # ─── Summary ─────────────────────────────────────────────
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="