qualia-framework 3.6.0 → 4.0.0

package/bin/state.js

@@ -140,6 +140,8 @@ function writeTracking(t) {
 function ensureLifetime(t) {
   if (!t) return t;
   if (typeof t.milestone !== "number") t.milestone = 1;
+  if (typeof t.milestone_name !== "string") t.milestone_name = "";
+  if (!Array.isArray(t.milestones)) t.milestones = [];
   if (!t.lifetime || typeof t.lifetime !== "object") {
     t.lifetime = {
       tasks_completed: 0,
@@ -345,9 +347,13 @@ function checkPreconditions(current, target, opts) {
     const taskHeaders = planContent.match(/^## Task \d+/gm);
     if (!taskHeaders || taskHeaders.length === 0)
       return fail("INVALID_PLAN", "Plan file has no task headers (expected '## Task N')");
+    // Accept either legacy "**Done when:**" or story-file "**Acceptance Criteria:**"
+    // so old in-flight plans don't break on upgrade.
     const doneWhenCount = (planContent.match(/\*\*Done when:\*\*/g) || []).length;
-    if (doneWhenCount < taskHeaders.length)
-      return fail("INVALID_PLAN", `${taskHeaders.length} tasks but only ${doneWhenCount} 'Done when:' entries`);
+    const acCount = (planContent.match(/\*\*Acceptance Criteria:\*\*/g) || []).length;
+    const anchors = doneWhenCount + acCount;
+    if (anchors < taskHeaders.length)
+      return fail("INVALID_PLAN", `${taskHeaders.length} tasks but only ${anchors} 'Done when:' or 'Acceptance Criteria:' anchors`);
   }
 
   if (target === "verified") {
@@ -436,6 +442,8 @@ function cmdCheck(opts) {
     status: s.status,
     assigned_to: s.assigned_to,
     milestone: t.milestone || 1,
+    milestone_name: t.milestone_name || "",
+    milestones: t.milestones || [],
     lifetime: t.lifetime,
     verification: t.verification || "pending",
     gap_cycles: (t.gap_cycles || {})[String(s.phase)] || 0,
@@ -550,6 +558,7 @@ function cmdTransition(opts) {
     t.tasks_done = parseInt(opts.tasks_done) || 0;
     t.tasks_total = parseInt(opts.tasks_total) || 0;
     t.wave = parseInt(opts.wave) || 0;
+    t.build_count = (parseInt(t.build_count) || 0) + 1;
     s.last_activity = `Phase ${phase} built (${t.tasks_done}/${t.tasks_total} tasks)`;
     if (s.phases[phase - 1]) s.phases[phase - 1].status = "built";
   }
@@ -601,6 +610,7 @@ function cmdTransition(opts) {
 
   if (target === "shipped") {
     t.deployed_url = opts.deployed_url || "";
+    t.deploy_count = (parseInt(t.deploy_count) || 0) + 1;
   }
 
   // Write both files
@@ -712,6 +722,9 @@ function cmdInit(opts) {
     ? { ...defaultLifetime, ...(prevLife.lifetime || {}) }
     : { ...defaultLifetime };
 
+  // Preserve milestones array across re-init (v4: milestone summaries for ERP tree).
+  const prevMilestones = (prevLife && Array.isArray(prevLife.milestones)) ? prevLife.milestones : [];
+
   // Build tracking — current-phase fields reset, lifetime + identity preserved
   const t = {
     project: opts.project,
@@ -722,6 +735,8 @@ function cmdInit(opts) {
     project_id: opts.project_id || (prevLife ? prevLife.project_id || "" : ""),
     git_remote: opts.git_remote || (prevLife ? prevLife.git_remote || "" : ""),
     milestone: prevLife ? prevLife.milestone : 1,
+    milestone_name: opts.milestone_name || (prevLife ? prevLife.milestone_name || "" : ""),
+    milestones: prevMilestones,
     phase: 1,
     phase_name: phases[0].name,
     total_phases: totalPhases,
@@ -854,12 +869,15 @@ function cmdValidatePlan(opts) {
     errors.push("No task headers found (expected '## Task N — title')");
   }
 
-  // Check "Done when" exists for each task
+  // Check "Done when" OR "Acceptance Criteria" anchor exists for each task
+  // (story-file format uses Acceptance Criteria; legacy format uses Done when)
   const taskCount = taskHeaders ? taskHeaders.length : 0;
   const doneWhenCount = (content.match(/\*\*Done when:\*\*/g) || []).length;
-  if (doneWhenCount < taskCount) {
+  const acCount = (content.match(/\*\*Acceptance Criteria:\*\*/g) || []).length;
+  const anchors = doneWhenCount + acCount;
+  if (anchors < taskCount) {
     errors.push(
-      `${taskCount} tasks but only ${doneWhenCount} 'Done when:' entries`
+      `${taskCount} tasks but only ${anchors} 'Done when:' or 'Acceptance Criteria:' anchors`
     );
   }
 
@@ -958,6 +976,7 @@ function cmdValidatePlan(opts) {
     phase,
     task_count: taskCount,
     done_when_count: doneWhenCount,
+    ac_count: acCount,
     contract_count: contractCount,
     warnings: warnings.length > 0 ? warnings : undefined,
   });
@@ -990,10 +1009,76 @@ function cmdCloseMilestone(opts) {
     );
   }
 
+  // ─── v4 guard rails ─────────────────────────────────────
+  // A milestone is only closable if it actually acted like one:
+  //   (a) all its phases are verified/polished/completed, AND
+  //   (b) it had ≥ 2 phases (so a 1-phase "milestone" is forced back to being a phase).
+  // Both guards are bypassable with --force for retroactive bookkeeping.
+  if (!opts.force) {
+    const totalPhases = parseInt(t.total_phases) || s.phases.length || 0;
+    if (totalPhases < 2) {
+      return output(
+        fail(
+          "MILESTONE_TOO_SMALL",
+          `Milestone ${closedMilestone} has only ${totalPhases} phase(s). A milestone needs ≥ 2 phases OR must be a shipped release gate. Use --force if this is intentional (e.g. a preview/demo milestone).`
+        )
+      );
+    }
+    const unfinished = s.phases.filter((p) => {
+      const st = (p.status || "").toLowerCase();
+      return !(st === "verified" || st === "polished" || st === "completed" || st === "complete");
+    });
+    if (unfinished.length > 0) {
+      return output(
+        fail(
+          "MILESTONE_NOT_READY",
+          `Milestone ${closedMilestone} has ${unfinished.length} unfinished phase(s): ${unfinished.map((p) => `${p.num}:${p.name}`).join(", ")}. Verify them first, or use --force.`
+        )
+      );
+    }
+  }
+
+  // ─── Append a summary to milestones[] so the ERP can render the tree ──
+  // This is the minimal metadata needed to reconstruct "milestone N of the
+  // project contained these phases" without replaying git history.
+  const phasesCompleted = s.phases.filter((p) => {
+    const st = (p.status || "").toLowerCase();
+    return st === "verified" || st === "polished" || st === "completed" || st === "complete";
+  }).length;
+  // tasks_completed for THIS milestone = lifetime.tasks_completed minus the
+  // sum of tasks already counted in prior milestones[] entries. This gives
+  // the correct per-milestone count even though `t.tasks_done` only reflects
+  // the current phase, not the cumulative milestone total.
+  const priorMilestoneTasks = Array.isArray(t.milestones)
+    ? t.milestones.reduce((sum, m) => sum + (parseInt(m && m.tasks_completed) || 0), 0)
+    : 0;
+  const tasksCompletedThisMilestone = Math.max(
+    0,
+    (parseInt(t.lifetime && t.lifetime.tasks_completed) || 0) - priorMilestoneTasks
+  );
+  const summary = {
+    num: closedMilestone,
+    name: t.milestone_name || `Milestone ${closedMilestone}`,
+    total_phases: parseInt(t.total_phases) || s.phases.length || 0,
+    phases_completed: phasesCompleted,
+    tasks_completed: tasksCompletedThisMilestone,
+    shipped_url: t.deployed_url || "",
+    closed_at: new Date().toISOString(),
+  };
+  t.milestones = Array.isArray(t.milestones) ? t.milestones : [];
+  // Idempotency: don't duplicate if the same milestone number is already logged.
+  const existing = t.milestones.findIndex((m) => m && m.num === closedMilestone);
+  if (existing >= 0) {
+    t.milestones[existing] = summary;
+  } else {
+    t.milestones.push(summary);
+  }
+
   t.lifetime.milestones_completed += 1;
   t.lifetime.total_phases += (parseInt(t.total_phases) || 0);
   t.lifetime.last_closed_milestone = closedMilestone;
   t.milestone = closedMilestone + 1;
+  t.milestone_name = ""; // cleared; /qualia-milestone reads next one from JOURNEY.md
   t.last_updated = new Date().toISOString();
 
   writeTracking(t);

package/guide.md

@@ -1,63 +1,126 @@
-# Qualia Developer Guide
+# Qualia Developer Guide (v4)
 
 > Follow the road. Type the commands. The framework handles the rest.
+> v4 adds a `--auto` flag that chains the whole road end-to-end with only two human checkpoints per project.
 
 ## The Road
 
 ```
-/qualia-new          ← Set up project (once)
+/qualia-new                ← Set up project (once). Produces JOURNEY.md — all milestones to handoff.
      ↓
-For each phase:
-  /qualia-plan       ← Plan it (planner agent)
-  /qualia-build      ← Build it (builder subagents)
-  /qualia-verify     ← Verify it works (verifier agent)
+For each phase of the current milestone:
+  /qualia-plan             ← Plan it (planner + plan-checker, story-file format)
+  /qualia-build            ← Build it (builder subagents with pre-inlined context)
+  /qualia-verify           ← Check it actually works (goal-backward + per-task AC)
      ↓
-/qualia-polish       ← Design pass
-/qualia-ship         ← Deploy to production
-/qualia-handoff      ← Deliver to client
+/qualia-milestone          ← Close milestone, open next from JOURNEY.md
+     ↓
+...repeat per milestone until the Handoff milestone...
+     ↓
+/qualia-polish             ← Design pass (part of Handoff milestone)
+/qualia-ship               ← Deploy to production
+/qualia-handoff            ← Enforce the 4 handoff deliverables
      ↓
 Done.
 ```
 
+## Auto Mode (v4)
+
+Append `--auto` to `/qualia-new` and the framework chains every step:
+
+```
+/qualia-new --auto
+  → research runs → JOURNEY.md written → approve the whole journey ONCE
+  → auto: plan 1 → build 1 → verify 1 → plan 2 → build 2 → verify 2 → ...
+  → pause at each milestone boundary: "Continue to M{N+1}?"
+  → resume: plan 1 → build 1 → ... of new milestone
+  → eventually reaches Handoff milestone's last phase → ship → handoff → report → done
+```
+
+**Human gates in auto mode (total: 2 per project):**
+1. Journey approval after `/qualia-new` research
+2. Each milestone boundary
+
+**Plus one halt case:** if a phase fails verification beyond the gap-cycle limit (default 2), the chain stops and asks for human intervention.
+
 ## The 10 Commands
 
 | When | Command | What it does |
 |------|---------|-------------|
-| Starting | `/qualia-new` | Set up project from scratch |
+| Starting | `/qualia-new` | Set up project with full journey (all milestones → Handoff) |
+| Starting (auto) | `/qualia-new --auto` | Same + chain through building automatically |
 | Building | `/qualia-plan` | Plan the current phase |
 | | `/qualia-build` | Build it (parallel tasks) |
 | | `/qualia-verify` | Check it actually works |
+| Milestone | `/qualia-milestone` | Close current, open next from JOURNEY.md |
 | Quick fix | `/qualia-quick` | Skip planning, just do it |
 | Finishing | `/qualia-polish` | Design and UX pass |
 | | `/qualia-ship` | Deploy to production |
-| | `/qualia-handoff` | Deliver to client |
-| Reporting | `/qualia-report` | Log what you did (mandatory) |
-| **Lost?** | **`/qualia`** | **Tells you the exact next command** |
+| | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
+| Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
+| Lost? | `/qualia` | Mechanical next-command router |
+| Confused? | `/qualia-idk` | Diagnostic — scans planning + code, explains what's going on |
+
+## Full Journey Hierarchy (v4)
+
+```
+Project
+└─ Journey           (the whole arc — mapped upfront by /qualia-new, lives in .planning/JOURNEY.md)
+   └─ Milestone      (a release — 2-5 total, Handoff is always last)
+      └─ Phase       (a feature-sized deliverable, 2-5 tasks)
+         └─ Task     (atomic unit, one commit, one verification contract)
+```
+
+Hard rules (enforced by `state.js` and the roadmapper):
+- **Milestone count: 2 to 5.** Final milestone is always literally named "Handoff".
+- **≥ 2 phases per non-Handoff milestone** (single-phase "milestones" are phases, not milestones).
+- **Milestone numbering is contiguous** — no skipped numbers.
+- **Handoff milestone has fixed 4 phases:** Polish, Content + SEO, Final QA, Handoff (credentials + walkthrough + archive + ERP report).
 
 ## Rules
 
 1. **Feature branches only** — never push to main
 2. **Read before write** — don't edit files you haven't read
 3. **MVP first** — build what's asked, nothing extra
-4. **`/qualia` is your friend** — lost? type it
+4. **Every task has a `Why`** (story-file format) — if you can't explain why a task matters in one sentence, it probably shouldn't exist
+5. **`/qualia` is your friend** — lost? type it
+6. **`/qualia-idk` is your deeper friend** — not lost on "what command", but confused about the *situation*? Type `idk`.
 
 ## When You're Stuck
 
 ```
-/qualia       ← "what's next?"
+/qualia       ← "what command should I run next?" (state-driven, instant)
+/qualia-idk   ← "what's actually going on here?" (diagnostic, scans planning + code, ~30s)
 ```
 
-If that doesn't help, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
+If neither helps, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
 
 ## Session Start / End
 
-**Start:** Claude loads your project context automatically.
-**End:** Run `/qualia-report` — this is mandatory before clock-out.
+**Start:** Claude loads your project context automatically. The router banner shows your journey position ("M2 of 4 · P2 of 3").
+**End:** Run `/qualia-report` — this is mandatory before clock-out. The report is committed to git and (if ERP is enabled) uploaded to https://portal.qualiasolutions.net.
 
 ## How It Works (you don't need to know this, but if curious)
 
+- **Journey-first planning:** `/qualia-new` produces JOURNEY.md listing every milestone from kickoff to Handoff with exit criteria and phase sketches. The whole team sees the path on day 1.
 - **Context isolation:** Each task runs in a fresh AI brain. Task 50 gets the same quality as Task 1.
-- **Goal-backward verification:** The verifier doesn't trust "I built it." It greps the code to check if things actually work.
-- **Plans are prompts:** The plan file IS what the builder reads. No translation loss.
+- **Pre-inlined context at dispatch:** The builder starts with PROJECT.md, DESIGN.md, and all Context @files already loaded — no wasted orientation reads.
+- **Goal-backward verification:** The verifier doesn't trust "I built it." It greps the code to check if things actually work AND walks every task's Acceptance Criteria.
+- **Story-file plans:** Every task has Why / Acceptance Criteria / Depends on / Validation inline — the plan IS the brief.
 - **Wave execution:** Independent tasks run in parallel. Dependent tasks wait.
-- **tracking.json:** Updated on every push. The ERP reads it automatically.
+- **Milestone-boundary pauses:** In `--auto` mode, the framework pauses only at real decision points. Everything else runs on rails.
+- **tracking.json:** Updated on every push. The ERP reads it automatically. v4 adds `milestone_name` + `milestones[]` so the ERP renders a proper tree instead of a flat list.
+
+## Quick Reference
+
+| Situation | Run |
+|---|---|
+| Starting a new client project | `/qualia-new` (or `/qualia-new --auto` to roll end-to-end) |
+| Starting a quick throwaway | `/qualia-new --quick` |
+| Brownfield project | `/qualia-map` first, then `/qualia-new` |
+| Stuck picking next command | `/qualia` |
+| Confused about the situation | `/qualia-idk` |
+| Finished the last phase of a milestone | `/qualia-milestone` |
+| About to ship | `/qualia-ship` |
+| Client is ready to take over | `/qualia-handoff` |
+| End of workday | `/qualia-report` (mandatory) |

package/package.json

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

package/skills/qualia/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia
-description: "Smart router — reads project state, classifies your situation, tells you the exact next command. Use whenever you type /qualia, 'what next', 'next', 'idk', 'what now', 'what should I do', 'I'm stuck', 'help me decide', 'lost', 'confused', or are unsure about your next step."
+description: "Smart router — reads project state (state.js), classifies the situation mechanically, returns the exact next command. Use whenever you type /qualia, 'what next', 'next', 'what now', 'what should I do next', 'what command now'. For deeper 'I don't understand what's going on' / 'something feels off' situations, use /qualia-idk instead — that one actually scans the planning folder and codebase to diagnose the confusion."
 ---
 
 # /qualia — What's Next?
@@ -56,6 +56,8 @@ Use the state.js JSON output plus gathered context:
 **Clear next step** (use the UI helper — it reads state.js itself):
 ```bash
 node ~/.claude/bin/qualia-ui.js banner router
+# If a project is loaded, show the journey position first (one-glance orientation)
+test -f .planning/JOURNEY.md && node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
 node ~/.claude/bin/qualia-ui.js next "{next_command from state.js}"
 ```
 

package/skills/qualia-build/SKILL.md

@@ -10,6 +10,7 @@ Execute the phase plan. Each task runs in a fresh subagent context. Independent
 ## Usage
 `/qualia-build` — build the current planned phase
 `/qualia-build {N}` — build specific phase
+`/qualia-build {N} --auto` — build + chain into `/qualia-verify {N} --auto` when done (no human gate between build and verify)
 
 ## Process
 
@@ -57,22 +58,44 @@ node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
 node ~/.claude/bin/qualia-ui.js task {task_num} "{task title}"
 ```
 
+**Pre-inline context before spawning** (saves 3-5 Read calls inside each builder subagent — GSD-style dispatch):
+
+1. Parse the task's `Context:` field to get `@file` references
+2. Read PROJECT.md
+3. Read DESIGN.md if any file in the task is `.tsx`, `.jsx`, `.css`, `.scss`
+4. Read each `@file` referenced in Context
+5. Inline all of the above into the agent prompt under `<pre-loaded-context>` so the builder starts with full context
+
 Spawn a fresh builder subagent:
 
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/builder.md
 
-Project context:
-@.planning/PROJECT.md
+<pre-loaded-context>
+# PROJECT.md
+{inlined contents of .planning/PROJECT.md}
+
+# DESIGN.md (if frontend task)
+{inlined contents of .planning/DESIGN.md}
+
+# {each @file from task.Context}
+{inlined contents}
+</pre-loaded-context>
 
 YOUR TASK:
-{paste the single task block from the plan — title, files, action, context refs, done-when}
+{paste the single task block from the plan — title, wave, persona, files, depends-on, why, acceptance-criteria, action, validation, context}
 
-Execute this task. Read all @file references before writing. Commit when done.
+All files in <pre-loaded-context> are already in your working memory — do NOT
+re-Read them. Only Read files NOT in the pre-loaded context (e.g. existing
+project code you need to modify).
+
+Execute the task. Commit when done.
 ", subagent_type="qualia-builder", description="Task {N}: {title}")
 ```
 
+**Why pre-inline:** without it, the builder's first actions are 3-5 Read tool calls to orient itself (PROJECT.md, DESIGN.md, context files). With pre-inline, the builder starts already oriented and spends its context budget on the actual task.
+
 **After each task completes:**
 - Verify the commit exists: `git log --oneline -1`
 - Show result:
@@ -110,6 +133,18 @@ node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done
 If state.js returns an error, show it to the employee and stop.
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
+### 6. Route (auto-chain aware)
+
+**If invoked with `--auto`:** immediately invoke `/qualia-verify {N} --auto` inline. No pause, no permission ask. Verify will either chain into the next phase (if PASS), into gap closure (if FAIL and gap cycles remain), or halt with clear escalation (if gap limit reached).
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-verify {N}"
+```
+
+Then invoke the `qualia-verify` skill inline with the same `--auto` flag.
+
+**Otherwise (default guided mode):** stop and show the next step:
+
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"
 ```

package/skills/qualia-handoff/SKILL.md

@@ -1,11 +1,26 @@
 ---
 name: qualia-handoff
-description: "Client delivery — credentials, handover doc, final update. Use after shipping."
+description: "Client delivery — produces the 4 mandatory Handoff deliverables (production URL, documentation, client assets archive, ERP finalization). Triggered at the end of the Handoff milestone."
 ---
 
 # /qualia-handoff — Client Delivery
 
-Prepare and deliver the finished project to the client.
+Finishes a project by producing the 4 mandatory Handoff deliverables defined in `JOURNEY.md`'s Handoff milestone. Every Qualia client project ends with this skill.
+
+## When to Use
+
+- After `/qualia-ship` on the final phase of the Handoff milestone
+- Invoked automatically at the end of `/qualia-new --auto` chain
+- Can also be run manually if the project deviated from auto mode
+
+## The 4 Deliverables
+
+Every Handoff milestone must produce these. They are checked against in `REQUIREMENTS.md` as `HAND-10..HAND-15`.
+
+1. **Production URL verified** — HTTP 200, auth flow, latency under 500ms
+2. **Documentation** — README with architecture, setup, API docs
+3. **Client Assets** — `.planning/archive/` contains every milestone's verification reports + credentials doc + recorded walkthrough
+4. **ERP Finalization** — final `/qualia-report` with `lifetime.milestones_completed` incremented
 
 ## Process
 
@@ -13,7 +28,35 @@ Prepare and deliver the finished project to the client.
 node ~/.claude/bin/qualia-ui.js banner handoff
 ```
 
-### 1. Generate Handover Doc
+### 1. Verify Production URL (Deliverable 1)
+
+```bash
+URL=$(node -e "const t=JSON.parse(require('fs').readFileSync('.planning/tracking.json','utf8'));console.log(t.deployed_url||'')")
+if [ -z "$URL" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "No deployed_url — run /qualia-ship first"
+  exit 1
+fi
+HTTP=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
+LATENCY=$(curl -s -o /dev/null -w "%{time_total}" "$URL")
+AUTH=$(curl -s -o /dev/null -w "%{http_code}" "$URL/api/auth/callback" 2>/dev/null || echo "N/A")
+node ~/.claude/bin/qualia-ui.js ok "URL: $URL (HTTP $HTTP, ${LATENCY}s, auth:$AUTH)"
+```
+
+If HTTP is not 2xx or latency > 1.0s → halt; deliverable fails.
+
+### 2. Update Documentation (Deliverable 2)
+
+Ensure the repo's `README.md` has:
+- **Overview** — what the project does
+- **Architecture** — stack summary, key services (Supabase / Vercel / third-party)
+- **Setup** — how to run locally (clone, env, `npm install`, `npm run dev`)
+- **Env vars** — list from `.env.local.example` (mask values)
+- **Deploy** — "Production deploys via `vercel --prod`. GitHub auto-deploy is DISABLED."
+- **Support** — contact: Fawzi Goussous, fawzi@qualiasolutions.net
+
+If README is stale or missing sections, update it and commit.
+
+### 3. Generate Handover Doc + Archive (Deliverable 3)
 
 Create `.planning/HANDOFF.md`:
 
@@ -21,46 +64,78 @@ Create `.planning/HANDOFF.md`:
 # {Project Name} — Handover
 
 ## What Was Built
-{3-5 bullet summary of delivered features}
+{3-5 bullet summary of delivered features, pulled from JOURNEY.md milestone exit criteria}
 
 ## Access
 - **URL:** {production URL}
-- **Admin login:** {credentials or where to find them}
+- **Admin login:** {credentials doc location — typically `.planning/credentials.md` (git-ignored)}
 - **Supabase:** {project ref}
 - **GitHub:** {repo URL}
 - **Vercel:** {project URL}
+- **Walkthrough:** {Loom or video link — recorded demo of primary flows}
 
 ## How to Use
 {Brief walkthrough of the main user flows}
 
 ## Known Limitations
-{Anything not in scope or deferred}
+{Anything not in scope or deferred, copied from REQUIREMENTS.md Out of Scope + Post-Handoff v2}
 
 ## Maintenance
-- Hosting: Vercel (auto-deploys from main branch)
+- Hosting: Vercel (MANUAL deploys via `vercel --prod`)
 - Database: Supabase ({region})
 - Domain: {domain provider if applicable}
+- Monitoring: UptimeRobot status page https://stats.uptimerobot.com/bKudHy1pLs
+
+## Milestones Shipped
+{Summary pulled from tracking.json milestones[] — one line per closed milestone with date and phase count}
 
 ## Support
 Contact: Fawzi Goussous — fawzi@qualiasolutions.net
+Standard support window: 30 days post-handoff.
+```
+
+Also ensure `.planning/archive/` contains every milestone's phase verification reports (qualia-milestone moves them there on close — verify they're present).
+
+```bash
+ls -la .planning/archive/ 2>/dev/null
 ```
 
-### 2. Commit
+If `.planning/archive/` is empty, something went wrong — milestones should have been archived on close. Investigate and recover from git history if needed.
+
+### 4. Commit + Push
 
 ```bash
-git add .planning/HANDOFF.md
-git commit -m "docs: client handoff document"
+git add .planning/HANDOFF.md README.md
+git commit -m "docs: client handoff — {project name}"
 git push
 ```
 
-### 3. Update State
+### 5. Update State
 
 ```bash
 node ~/.claude/bin/state.js transition --to handed_off
 ```
+
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
+### 6. ERP Finalization (Deliverable 4)
+
+Trigger the final `/qualia-report`. This uploads the closing state to the ERP with `lifetime.milestones_completed` incremented by the Handoff close that just happened.
+
+In `--auto` mode, inline-invoke `/qualia-report` now. In guided mode, show the next step:
+
 ```bash
-node ~/.claude/bin/qualia-ui.js ok "{Project Name} handed off to {client}"
+node ~/.claude/bin/qualia-ui.js ok "Production URL verified"
+node ~/.claude/bin/qualia-ui.js ok "Documentation updated"
+node ~/.claude/bin/qualia-ui.js ok "Client assets archived + handoff doc written"
+node ~/.claude/bin/qualia-ui.js ok "Ready for final ERP report"
 node ~/.claude/bin/qualia-ui.js end "DELIVERED" "/qualia-report"
 ```
+
+## Rules
+
+1. **No handoff without verified production URL.** Step 1 halts if URL is down or latency > 1s.
+2. **Archive is mandatory.** `.planning/archive/` must contain every closed milestone's phase artifacts. If empty, the project was handled outside the framework — recover from git history.
+3. **README is the public face.** If it's stale, fix it before handoff. Client reads it first.
+4. **Credentials never in the repo.** `.planning/credentials.md` is git-ignored. Deliver credentials via secure channel (1Password shared vault, encrypted email).
+5. **Support clause is 30 days by default.** If the client contract says otherwise, override it in HANDOFF.md.