npm - qualia-framework - Versions diffs - 6.8.1 → 6.9.0 - Mend

qualia-framework 6.8.1 → 6.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/templates/stacks/internal-tool/scaffold/app/layout.tsx ADDED Viewed

@@ -0,0 +1,20 @@
+import type { Metadata } from "next";
+import "./globals.css";
+export const metadata: Metadata = {
+  title: "Internal Tool",
+  // Internal portal — keep it out of search indexes.
+  robots: { index: false, follow: false },
+};
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/stacks/internal-tool/scaffold/app/page.tsx ADDED Viewed

@@ -0,0 +1,22 @@
+import { createClient } from "@/lib/supabase/server";
+export default async function Home() {
+  const supabase = await createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+  // Role lives in app_metadata (never user_metadata).
+  const role = (user?.app_metadata?.role as string | undefined) ?? "none";
+  return (
+    <main className="mx-auto flex min-h-dvh max-w-3xl flex-col justify-center gap-6 px-6">
+      <h1 className="text-4xl font-semibold tracking-tight">Internal Tool</h1>
+      <p className="text-lg text-neutral-600">
+        {user
+          ? `Signed in as ${user.email} (role: ${role}).`
+          : "Staff only — invite required. Wire portal auth + role gating in Phase 1."}
+      </p>
+    </main>
+  );
+}

package/templates/stacks/internal-tool/scaffold/lib/supabase/client.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import { createBrowserClient } from "@supabase/ssr";
+// Client-side Supabase adapter — publishable key only. RLS protects data.
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
+  );
+}

package/templates/stacks/internal-tool/scaffold/lib/supabase/server.ts ADDED Viewed

@@ -0,0 +1,28 @@
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+// Server-side Supabase adapter — all mutations and RLS-protected reads.
+export async function createClient() {
+  const cookieStore = await cookies();
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll();
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            );
+          } catch {
+            // Server Component context — middleware refreshes the session.
+          }
+        },
+      },
+    }
+  );
+}

package/templates/stacks/internal-tool/scaffold/next.config.mjs ADDED Viewed

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Internal portal — no public SEO. The root layout sets robots: noindex.
+};
+export default nextConfig;

package/templates/stacks/internal-tool/scaffold/package.json ADDED Viewed

@@ -0,0 +1,29 @@
+{
+  "name": "internal-tool",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@supabase/supabase-js": "^2.45.0",
+    "@supabase/ssr": "^0.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "postcss": "^8.4.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/stacks/internal-tool/scaffold/postcss.config.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+export default config;

package/templates/stacks/internal-tool/scaffold/supabase/migrations/0001_init.sql ADDED Viewed

@@ -0,0 +1,28 @@
+-- Initial migration. Internal portal: roles gate everything; RLS on every
+-- table from the first migration. Replace `records` with your real domain.
+create table if not exists public.records (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid references auth.users (id) on delete set null,
+  title text not null,
+  status text not null default 'open',
+  deleted_at timestamptz,             -- soft-delete (constitution: where flagged)
+  created_at timestamptz not null default now()
+);
+alter table public.records enable row level security;
+-- Authenticated staff may read non-deleted records.
+create policy "records_select_staff"
+  on public.records for select
+  using (auth.role() = 'authenticated' and deleted_at is null);
+-- Admins (role in app_metadata) may write. Matching SELECT exists above.
+create policy "records_write_admin"
+  on public.records for all
+  using (
+    coalesce(auth.jwt() -> 'app_metadata' ->> 'role', '') = 'admin'
+  )
+  with check (
+    coalesce(auth.jwt() -> 'app_metadata' ->> 'role', '') = 'admin'
+  );

package/templates/stacks/internal-tool/scaffold/tsconfig.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/stacks/internal-tool/stack.json ADDED Viewed

@@ -0,0 +1,9 @@
+{
+  "id": "internal-tool",
+  "title": "Internal Tool",
+  "description": "Staff-facing portal — Supabase auth (invite/SSO, no public signup), role-gated dashboard, Tailwind, Vercel. Built for a known set of internal users.",
+  "archetype": "web-app",
+  "defaultStack": "Next.js 16 (App Router) · Supabase (portal auth + RLS) · Tailwind · Vercel",
+  "scaffoldEntry": "app/page.tsx",
+  "whenToUse": "Admin panel, ops dashboard, internal CRM — a known set of staff users, no public signup. Pick this over full-app when the audience is employees, access is invite-only, and roles gate everything."
+}

package/templates/stacks/internal-tool/verify-checklist.md ADDED Viewed

@@ -0,0 +1,31 @@
+# Internal Tool — Definition of Done
+Per-stack verify checklist. Inherits `rules/constitution.md` and the `web-app` archetype DoD.
+Internal/living product → runs as a **rolling release**; each increment clears this DoD, no terminal Handoff.
+## Portal auth & access (constitution)
+- [ ] Public signup disabled — staff join by invite / SSO only.
+- [ ] Roles stored in `app_metadata` (never `user_metadata`); role-based routing in middleware AND data layer.
+- [ ] **RLS enabled on every table**; verified as two roles — each sees only its scope.
+- [ ] Every UPDATE policy has a matching SELECT policy.
+- [ ] Postgres views set `security_invoker = true`.
+- [ ] Sessions revoked before a user is deleted/deactivated.
+## Security
+- [ ] `SUPABASE_SERVICE_ROLE_KEY` server-only; used only in server actions (e.g. inviting users).
+- [ ] Mutations use `lib/supabase/server.ts`; inputs validated with Zod.
+- [ ] Security headers (HSTS); MFA on Supabase/Vercel accounts.
+## App quality
+- [ ] Loading / empty / error states on every async surface.
+- [ ] Destructive actions confirm; soft-delete + audit where flagged.
+- [ ] Rate limiting on mutating endpoints; no N+1 on list views.
+## Schema flow
+- [ ] All schema changes are migrations in `supabase/migrations/`.
+- [ ] `npx supabase gen types` run after schema changes.
+## Build & Deploy
+- [ ] `npx tsc --noEmit` exits 0; `next build` succeeds.
+- [ ] Deploys to Vercel; HTTP 200; auth callback + role isolation verified.
+- [ ] Design anti-slop bar met; a11y AA.

package/templates/stacks/landing-page/env.required.json ADDED Viewed

@@ -0,0 +1,8 @@
+[
+  {
+    "name": "NEXT_PUBLIC_ANALYTICS_ID",
+    "purpose": "Optional analytics/measurement id for the marketing site (e.g. Plausible domain, GA4 id). The landing page runs without it.",
+    "howToObtain": "Create a property in your analytics provider and copy the site/measurement id. Skip if you are not tracking conversions yet.",
+    "ownerIssued": false
+  }
+]

package/templates/stacks/landing-page/phases.md ADDED Viewed

@@ -0,0 +1,42 @@
+# Landing Page — Phase Plan
+Stack: Next.js 16 (App Router, SSG) · Tailwind · Vercel. No database, no auth.
+Archetype: `website`. This is the seed plan `/qualia-new` copies into ROADMAP.md.
+## Phase 1: Foundation & Design System
+**Goal:** The site renders on a Vercel preview URL with the design system wired (tokens, fonts, OKLCH palette) and a base layout (nav + footer).
+**Success criteria:**
+1. `npm run dev` renders the homepage with no console errors.
+2. DESIGN.md tokens are live (CSS variables, distinctive type pair — never Inter/Arial/system-ui).
+3. Nav + footer render and are responsive at 375px and 1440px.
+4. Deploys to a Vercel preview URL.
+## Phase 2: Hero & Core Sections
+**Goal:** The above-the-fold hero plus the primary value sections (features, social proof) are built with real copy.
+**Success criteria:**
+1. Hero communicates the offer in one glance; primary CTA is present and reachable.
+2. Feature/benefit sections render with real copy — no lorem ipsum.
+3. All sections responsive, with loading-free SSG output.
+## Phase 3: Conversion & Contact
+**Goal:** The conversion path works — CTA → contact form or external link, with success/error states.
+**Success criteria:**
+1. Contact form (or CTA link) submits and shows a success state; errors are handled.
+2. If a form posts anywhere, it validates client-side (Zod or equivalent) — no DB needed.
+3. Analytics event fires on the primary CTA.
+## Phase 4: Polish & Launch
+**Goal:** Production-ready — SEO meta, a11y, performance, custom domain.
+**Success criteria:**
+1. SEO: title/description/OG tags per page; sitemap; favicon.
+2. a11y: alt text, labels, keyboard nav, AA contrast.
+3. Lighthouse performance/SEO green on the homepage.
+4. Custom domain wired; production deploy + smoke (HTTP 200).

package/templates/stacks/landing-page/scaffold/.env.example ADDED Viewed

@@ -0,0 +1,3 @@
+# Landing Page — no database, no auth. Nothing required to run locally.
+# Optional analytics (uncomment if you wire it):
+# NEXT_PUBLIC_ANALYTICS_ID=

package/templates/stacks/landing-page/scaffold/README.md ADDED Viewed

@@ -0,0 +1,25 @@
+# Landing Page
+Static/SSG marketing site — Next.js 16 + Tailwind + Vercel. No database, no auth.
+## Run
+```bash
+npm install
+npm run dev      # http://localhost:3000
+```
+## Ship
+```bash
+npm run build
+vercel --prod
+```
+## Where things live
+- `app/page.tsx` — the landing page itself (replace the hero copy).
+- `app/globals.css` — OKLCH design tokens. Source of truth is `.planning/DESIGN.md`.
+- `.env.example` — nothing required; copy to `.env.local` only if you add analytics.
+This is an MVP skeleton. Build the real sections per `.planning/ROADMAP.md`.

package/templates/stacks/landing-page/scaffold/app/globals.css ADDED Viewed

@@ -0,0 +1,14 @@
+@import "tailwindcss";
+/* Define your OKLCH palette here. Neutrals tinted toward the brand hue.
+   NEVER raw #000 / #fff. See .planning/DESIGN.md for the committed tokens. */
+:root {
+  --brand: oklch(0.62 0.18 264);
+  --ink: oklch(0.21 0.01 264);
+  --paper: oklch(0.99 0.004 264);
+}
+body {
+  background: var(--paper);
+  color: var(--ink);
+}

package/templates/stacks/landing-page/scaffold/app/layout.tsx ADDED Viewed

@@ -0,0 +1,19 @@
+import type { Metadata } from "next";
+import "./globals.css";
+export const metadata: Metadata = {
+  title: "Landing Page",
+  description: "Replace with your product's one-sentence pitch.",
+};
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/stacks/landing-page/scaffold/app/page.tsx ADDED Viewed

@@ -0,0 +1,21 @@
+export default function Home() {
+  return (
+    <main className="mx-auto flex min-h-dvh max-w-3xl flex-col justify-center gap-6 px-6">
+      <h1 className="text-balance text-4xl font-semibold tracking-tight sm:text-6xl">
+        Your one-sentence pitch goes here.
+      </h1>
+      <p className="text-lg text-neutral-600">
+        Replace this hero with real copy. No lorem ipsum — the page is the
+        product.
+      </p>
+      <div>
+        <a
+          href="#contact"
+          className="inline-flex h-11 items-center rounded-md bg-neutral-900 px-6 font-medium text-white"
+        >
+          Primary CTA
+        </a>
+      </div>
+    </main>
+  );
+}

package/templates/stacks/landing-page/scaffold/next.config.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Marketing site: keep it static where possible. Add `output: "export"`
+  // if the host is purely static (no Vercel server runtime needed).
+};
+export default nextConfig;

package/templates/stacks/landing-page/scaffold/package.json ADDED Viewed

@@ -0,0 +1,26 @@
+{
+  "name": "landing-page",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "postcss": "^8.4.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/stacks/landing-page/scaffold/postcss.config.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+export default config;

package/templates/stacks/landing-page/scaffold/tsconfig.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/stacks/landing-page/stack.json ADDED Viewed

@@ -0,0 +1,9 @@
+{
+  "id": "landing-page",
+  "title": "Landing Page",
+  "description": "A static/SSG marketing site — hero, features, CTA, contact. No database, no auth. Built to convert, fast to ship.",
+  "archetype": "website",
+  "defaultStack": "Next.js 16 (App Router, SSG) · Tailwind · Vercel",
+  "scaffoldEntry": "app/page.tsx",
+  "whenToUse": "Marketing site, product landing, portfolio, throwaway prototype. Pick this when there is no logged-in user and no persistent data — the page IS the product."
+}

package/templates/stacks/landing-page/verify-checklist.md ADDED Viewed

@@ -0,0 +1,28 @@
+# Landing Page — Definition of Done
+Per-stack verify checklist. Inherits `rules/constitution.md` and the `website` archetype DoD.
+## Build & Deploy
+- [ ] `npx tsc --noEmit` exits 0.
+- [ ] `next build` succeeds; output is static/SSG (no accidental server-only data fetch on a marketing page).
+- [ ] Deploys to Vercel; homepage returns HTTP 200.
+- [ ] Custom domain wired (production).
+## Design (anti-slop)
+- [ ] DESIGN.md committed; distinctive type pair (NOT Inter/Roboto/Arial/Helvetica/system-ui).
+- [ ] OKLCH palette; neutrals tinted toward brand hue; no raw `#000`/`#fff`.
+- [ ] 8px spacing grid + fluid `clamp()` page padding.
+- [ ] Responsive at 375px and 1440px; touch targets ≥44px.
+## Content & Conversion
+- [ ] Real copy — zero "lorem ipsum", zero placeholder text.
+- [ ] Primary CTA present, reachable, and instrumented with an analytics event.
+- [ ] Contact form (if any) validates client-side and has success + error states.
+## SEO & a11y
+- [ ] Per-page title + meta description + OG tags; sitemap + favicon present.
+- [ ] Alt text on every image; labels on every input; keyboard navigable.
+- [ ] AA contrast verified.
+## Out of scope (by design)
+- No Supabase, no auth, no `SUPABASE_SERVICE_ROLE_KEY`. If the project needs accounts or persisted data, it is a `full-app`, not a `landing-page`.

package/tests/bin.test.sh CHANGED Viewed

@@ -1466,10 +1466,10 @@ mkdir -p "$TMP/.codex"
 echo "OLD USER CONTENT" > "$TMP/.codex/AGENTS.md"
 printf 'QS-FAWZI-11\n2\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
 EXIT=$?
-BAK_COUNT=$(ls "$TMP/.codex/"AGENTS.md.bak.* 2>/dev/null | wc -l)
+BAK_COUNT=$(ls "$TMP/.codex/backups/"AGENTS.md.bak.* 2>/dev/null | wc -l)
 if [ "$EXIT" -eq 0 ] \
    && [ "$BAK_COUNT" -ge 1 ] \
-   && grep -q "OLD USER CONTENT" "$TMP/.codex/"AGENTS.md.bak.* \
+   && grep -q "OLD USER CONTENT" "$TMP/.codex/backups/"AGENTS.md.bak.* \
    && ! grep -q "OLD USER CONTENT" "$TMP/.codex/AGENTS.md"; then
   pass "Codex AGENTS.md backup-before-overwrite preserves prior content"
 else
@@ -1482,7 +1482,7 @@ TMP=$(mktmp)
 printf 'QS-FAWZI-11\n2\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
 # Re-run with same input — content should be identical, no new backup.
 printf 'QS-FAWZI-11\n2\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log2.txt" 2>&1
-BAK_COUNT=$(ls "$TMP/.codex/"AGENTS.md.bak.* 2>/dev/null | wc -l)
+BAK_COUNT=$(ls "$TMP/.codex/backups/"AGENTS.md.bak.* 2>/dev/null | wc -l)
 if [ "$BAK_COUNT" -eq 0 ]; then
   pass "Codex re-install with identical content → no redundant .bak"
 else

package/tests/state.test.sh CHANGED Viewed

@@ -1011,6 +1011,89 @@ else
   fail_case "close-milestone + init" "got=$RESULT expected=2,4,1,1,1,0"
 fi
+# 46b. close-milestone resolves the REAL milestone name from JOURNEY.md
+# instead of emitting a "Milestone N" placeholder when tracking.json has
+# no (or a placeholder) milestone_name.
+TMP=$(make_project)
+cat > "$TMP/.planning/JOURNEY.md" <<'JOURNEY'
+# Journey
+## Milestone 1 · Foundation Arc
+Some prose.
+## Milestone 2 · Core Features
+JOURNEY
+$NODE -e "
+  const fs = require('fs');
+  const t = JSON.parse(fs.readFileSync('$TMP/.planning/tracking.json','utf8'));
+  t.milestone_name = 'Milestone 1'; // placeholder — must lose to JOURNEY.md
+  fs.writeFileSync('$TMP/.planning/tracking.json', JSON.stringify(t, null, 2));
+"
+(cd "$TMP" && $NODE "$STATE_JS" close-milestone --force >/dev/null 2>&1)
+RESULT=$($NODE -e "
+  const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+  console.log(t.milestones[0].name + '|' + t.milestone_name);
+")
+if [ "$RESULT" = "Foundation Arc|Core Features" ]; then
+  pass "close-milestone resolves real name from JOURNEY.md (no placeholder)"
+else
+  fail_case "close-milestone JOURNEY name resolution" "got=$RESULT expected='Foundation Arc|Core Features'"
+fi
+# 46c. close-milestone dedupes: same real name already logged under a
+# different (legacy string) num updates that entry instead of pushing a
+# duplicate.
+TMP=$(make_project)
+cat > "$TMP/.planning/JOURNEY.md" <<'JOURNEY'
+## Milestone 1 · Foundation Arc
+JOURNEY
+$NODE -e "
+  const fs = require('fs');
+  const t = JSON.parse(fs.readFileSync('$TMP/.planning/tracking.json','utf8'));
+  t.milestone_name = '';
+  t.milestones = [{ num: '9', name: 'Foundation Arc', total_phases: 2, phases_completed: 2, tasks_completed: 0, shipped_url: '', closed_at: '' }];
+  fs.writeFileSync('$TMP/.planning/tracking.json', JSON.stringify(t, null, 2));
+"
+(cd "$TMP" && $NODE "$STATE_JS" close-milestone --force >/dev/null 2>&1)
+RESULT=$($NODE -e "
+  const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+  console.log(t.milestones.length + '|' + t.milestones[0].num + '|' + t.milestones[0].name);
+")
+if [ "$RESULT" = "1|1|Foundation Arc" ]; then
+  pass "close-milestone dedupes same-name entry under different num"
+else
+  fail_case "close-milestone name dedupe" "got=$RESULT expected='1|1|Foundation Arc'"
+fi
+# 46d. backfill-milestones repairs a placeholder-named real-close entry in
+# place (fixes the name, keeps the richer close data like tasks_completed).
+TMP=$(make_project)
+cat > "$TMP/.planning/JOURNEY.md" <<'JOURNEY'
+# Journey
+| # | Milestone | Status | Phases | Closed |
+|---|-----------|--------|--------|--------|
+| 1 | Foundation Arc | CLOSED | 1–2 | 2026-01-01 |
+| 2 | Core Features | OPEN | rolling | — |
+JOURNEY
+$NODE -e "
+  const fs = require('fs');
+  const t = JSON.parse(fs.readFileSync('$TMP/.planning/tracking.json','utf8'));
+  t.milestones = [{ num: '1', name: 'Milestone 1', total_phases: 2, phases_completed: 2, tasks_completed: 7, shipped_url: 'https://x.test', closed_at: '2026-01-01T00:00:00.000Z' }];
+  fs.writeFileSync('$TMP/.planning/tracking.json', JSON.stringify(t, null, 2));
+"
+(cd "$TMP" && $NODE "$STATE_JS" backfill-milestones >/dev/null 2>&1)
+RESULT=$($NODE -e "
+  const t = JSON.parse(require('fs').readFileSync('$TMP/.planning/tracking.json','utf8'));
+  console.log(t.milestones.length + '|' + t.milestones[0].name + '|' + t.milestones[0].tasks_completed + '|' + t.milestone_name);
+")
+if [ "$RESULT" = "1|Foundation Arc|7|Core Features" ]; then
+  pass "backfill-milestones repairs placeholder name, keeps real close data"
+else
+  fail_case "backfill-milestones placeholder repair" "got=$RESULT expected='1|Foundation Arc|7|Core Features'"
+fi
 # ─── Backward compatibility ──────────────────────────────
 echo ""
 echo "backward compatibility:"