@planu/cli 4.12.3 → 4.14.1

package/dist/config/product-public.json

@@ -0,0 +1,312 @@
+{
+  "schemaVersion": 1,
+  "website": {
+    "baseUrl": "https://planu.dev",
+    "defaultLocale": "en",
+    "theme": {
+      "defaultAppearance": "system",
+      "allowUserToggle": true
+    },
+    "disabledRouteSegments": ["pricing"],
+    "locales": [
+      {
+        "id": "en",
+        "contentLocale": "en",
+        "label": "🇺🇸 English",
+        "lang": "en",
+        "hreflang": "en",
+        "ogLocale": "en_US",
+        "nav": [
+          { "text": "Guide", "path": "guide/getting-started" },
+          { "text": "Tools", "path": "tools/" },
+          { "text": "Recipes", "path": "recipes/new-feature" },
+          { "text": "Blog", "path": "blog/" }
+        ],
+        "chrome": {
+          "footerLead": "Free tier available",
+          "support": "Support Planu",
+          "changelog": "Changelog",
+          "reportBug": "Report a bug",
+          "appearance": "Appearance",
+          "lightTheme": "Switch to light theme",
+          "darkTheme": "Switch to dark theme",
+          "sidebar": "Menu",
+          "top": "Return to top",
+          "language": "Change language",
+          "skip": "Skip to content",
+          "outline": "On this page",
+          "previous": "Previous page",
+          "next": "Next page",
+          "search": "Search",
+          "noResults": "No results found"
+        }
+      },
+      {
+        "id": "es",
+        "contentLocale": "es",
+        "label": "🌎 Español (Latinoamérica)",
+        "lang": "es-419",
+        "hreflang": "es-419",
+        "ogLocale": "es_419",
+        "nav": [
+          { "text": "Guía", "path": "guide/getting-started" },
+          { "text": "Herramientas", "path": "tools/" },
+          { "text": "Recetas", "path": "recipes/new-feature" },
+          { "text": "Blog", "path": "blog/" }
+        ],
+        "chrome": {
+          "footerLead": "Plan gratuito disponible",
+          "support": "Apoyar Planu",
+          "changelog": "Cambios",
+          "reportBug": "Reportar un error",
+          "appearance": "Apariencia",
+          "lightTheme": "Cambiar al tema claro",
+          "darkTheme": "Cambiar al tema oscuro",
+          "sidebar": "Menú",
+          "top": "Volver arriba",
+          "language": "Cambiar idioma",
+          "skip": "Saltar al contenido",
+          "outline": "En esta página",
+          "previous": "Página anterior",
+          "next": "Página siguiente",
+          "search": "Buscar",
+          "noResults": "No se encontraron resultados"
+        }
+      },
+      {
+        "id": "es-ES",
+        "contentLocale": "es",
+        "label": "🇪🇸 Español (España)",
+        "lang": "es-ES",
+        "hreflang": "es-ES",
+        "ogLocale": "es_ES",
+        "nav": [
+          { "text": "Guía", "path": "/es/guide/getting-started" },
+          { "text": "Herramientas", "path": "/es/tools/" },
+          { "text": "Recetas", "path": "/es/recipes/new-feature" },
+          { "text": "Blog", "path": "/es/blog/" }
+        ],
+        "chrome": {
+          "footerLead": "Plan gratuito disponible",
+          "support": "Apoyar Planu",
+          "changelog": "Cambios",
+          "reportBug": "Informar de un error",
+          "appearance": "Apariencia",
+          "lightTheme": "Cambiar al tema claro",
+          "darkTheme": "Cambiar al tema oscuro",
+          "sidebar": "Menú",
+          "top": "Volver arriba",
+          "language": "Cambiar idioma",
+          "skip": "Saltar al contenido",
+          "outline": "En esta página",
+          "previous": "Página anterior",
+          "next": "Página siguiente",
+          "search": "Buscar",
+          "noResults": "No se han encontrado resultados"
+        }
+      },
+      {
+        "id": "pt",
+        "contentLocale": "pt",
+        "label": "🇧🇷 Português",
+        "lang": "pt-BR",
+        "hreflang": "pt-BR",
+        "ogLocale": "pt_BR",
+        "nav": [
+          { "text": "Guia", "path": "guide/getting-started" },
+          { "text": "Ferramentas", "path": "tools/" },
+          { "text": "Receitas", "path": "recipes/new-feature" },
+          { "text": "Comparação", "path": "comparison" }
+        ],
+        "chrome": {
+          "footerLead": "Plano gratuito disponível",
+          "support": "Apoiar o Planu",
+          "changelog": "Novidades",
+          "reportBug": "Reportar um erro",
+          "appearance": "Aparência",
+          "lightTheme": "Mudar para o tema claro",
+          "darkTheme": "Mudar para o tema escuro",
+          "sidebar": "Menu",
+          "top": "Voltar ao topo",
+          "language": "Mudar idioma",
+          "skip": "Ir para o conteúdo",
+          "outline": "Nesta página",
+          "previous": "Página anterior",
+          "next": "Próxima página",
+          "search": "Pesquisar",
+          "noResults": "Nenhum resultado encontrado"
+        }
+      },
+      {
+        "id": "fr",
+        "contentLocale": "fr",
+        "label": "🇫🇷 Français",
+        "lang": "fr",
+        "hreflang": "fr",
+        "ogLocale": "fr_FR",
+        "nav": [
+          { "text": "Guide", "path": "guide/getting-started" },
+          { "text": "Outils", "path": "tools/" },
+          { "text": "Recettes", "path": "recipes/new-feature" },
+          { "text": "Comparatif", "path": "comparison" }
+        ],
+        "chrome": {
+          "footerLead": "Offre gratuite disponible",
+          "support": "Soutenir Planu",
+          "changelog": "Nouveautés",
+          "reportBug": "Signaler un bug",
+          "appearance": "Apparence",
+          "lightTheme": "Passer au thème clair",
+          "darkTheme": "Passer au thème sombre",
+          "sidebar": "Menu",
+          "top": "Retour en haut",
+          "language": "Changer de langue",
+          "skip": "Aller au contenu",
+          "outline": "Sur cette page",
+          "previous": "Page précédente",
+          "next": "Page suivante",
+          "search": "Rechercher",
+          "noResults": "Aucun résultat trouvé"
+        }
+      },
+      {
+        "id": "de",
+        "contentLocale": "de",
+        "label": "🇩🇪 Deutsch",
+        "lang": "de",
+        "hreflang": "de",
+        "ogLocale": "de_DE",
+        "nav": [
+          { "text": "Anleitung", "path": "guide/getting-started" },
+          { "text": "Tools", "path": "tools/" },
+          { "text": "Rezepte", "path": "recipes/new-feature" },
+          { "text": "Vergleich", "path": "comparison" }
+        ],
+        "chrome": {
+          "footerLead": "Kostenloser Tarif verfügbar",
+          "support": "Planu unterstützen",
+          "changelog": "Änderungen",
+          "reportBug": "Fehler melden",
+          "appearance": "Darstellung",
+          "lightTheme": "Zum hellen Design wechseln",
+          "darkTheme": "Zum dunklen Design wechseln",
+          "sidebar": "Menü",
+          "top": "Nach oben",
+          "language": "Sprache ändern",
+          "skip": "Zum Inhalt springen",
+          "outline": "Auf dieser Seite",
+          "previous": "Vorherige Seite",
+          "next": "Nächste Seite",
+          "search": "Suchen",
+          "noResults": "Keine Ergebnisse gefunden"
+        }
+      },
+      {
+        "id": "zh",
+        "contentLocale": "zh",
+        "label": "🇨🇳 中文",
+        "lang": "zh-CN",
+        "hreflang": "zh-CN",
+        "ogLocale": "zh_CN",
+        "nav": [
+          { "text": "指南", "path": "guide/getting-started" },
+          { "text": "工具", "path": "tools/" },
+          { "text": "实践", "path": "recipes/new-feature" },
+          { "text": "对比", "path": "comparison" }
+        ],
+        "chrome": {
+          "footerLead": "提供免费方案",
+          "support": "支持 Planu",
+          "changelog": "更新日志",
+          "reportBug": "报告问题",
+          "appearance": "外观",
+          "lightTheme": "切换到浅色主题",
+          "darkTheme": "切换到深色主题",
+          "sidebar": "菜单",
+          "top": "返回顶部",
+          "language": "切换语言",
+          "skip": "跳到正文",
+          "outline": "本页内容",
+          "previous": "上一页",
+          "next": "下一页",
+          "search": "搜索",
+          "noResults": "未找到结果"
+        }
+      }
+    ],
+    "newsletter": {
+      "enabled": false,
+      "provider": "none",
+      "signupUrl": null
+    },
+    "sponsors": {
+      "enabled": true,
+      "pagePath": "/en/sponsors",
+      "githubUrl": "https://github.com/sponsors/planu-dev",
+      "contactEmail": "sponsors@planu.dev"
+    }
+  },
+  "donations": [
+    {
+      "id": "btc",
+      "symbol": "BTC",
+      "network": "Bitcoin mainnet",
+      "address": "bc1q0wpklyw24krxpzy52g8fu6tgtyvws7v3etc40p",
+      "qrPath": "/donations/btc-qr.svg",
+      "walletUri": "bitcoin:bc1q0wpklyw24krxpzy52g8fu6tgtyvws7v3etc40p"
+    },
+    {
+      "id": "eth",
+      "symbol": "ETH",
+      "network": "Ethereum mainnet",
+      "address": "0xe26326f8bA13Ae7C6Eee79A10A7f3ad696Ebb5bB",
+      "qrPath": "/donations/eth-qr.svg",
+      "walletUri": null
+    },
+    {
+      "id": "sol",
+      "symbol": "SOL",
+      "network": "Solana mainnet",
+      "address": "A6ujVihGksWwF1NRVDBgGtNeqPXnN5vFpwLtXhANqXY3",
+      "qrPath": "/donations/sol-qr.svg",
+      "walletUri": null
+    }
+  ],
+  "claims": {
+    "installCommand": "npx -y @planu/cli@latest install",
+    "publicToolInventory": [
+      "planu_status",
+      "facilitate",
+      "init_project",
+      "clarify_requirements",
+      "create_spec",
+      "list_specs",
+      "challenge_spec",
+      "check_readiness",
+      "update_status",
+      "update_status_batch",
+      "package_handoff",
+      "validate",
+      "get_job",
+      "watch_job",
+      "cancel_job",
+      "restart_job",
+      "reconcile_spec",
+      "create_rule",
+      "create_skill",
+      "skill_search",
+      "configure_code_graph",
+      "code_graph_status",
+      "submit_feedback",
+      "triage_feedback",
+      "resolve_feedback",
+      "sync_feedback",
+      "feedback_status"
+    ],
+    "registryReadmeBaseline": {
+      "package": "@planu/cli",
+      "version": "4.13.0",
+      "sha256": "c3faa711117966434fed16c2102e11aa1f2a90f32af762f80f1e3af5ffbc582f"
+    }
+  }
+}

package/dist/config/product-public.ts

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import rawProductPublic from './product-public.json' with { type: 'json' };
+import type { ProductPublicManifest } from '../types/product-public.js';
+
+const nonBlank = z.string().trim().min(1).max(512);
+const pathSegment = z.string().regex(/^[A-Za-z0-9-]+$/u);
+const navItemSchema = z.object({ text: nonBlank, path: nonBlank }).strict();
+const chromeSchema = z
+  .object({
+    footerLead: nonBlank,
+    support: nonBlank,
+    changelog: nonBlank,
+    reportBug: nonBlank,
+    appearance: nonBlank,
+    lightTheme: nonBlank,
+    darkTheme: nonBlank,
+    sidebar: nonBlank,
+    top: nonBlank,
+    language: nonBlank,
+    skip: nonBlank,
+    outline: nonBlank,
+    previous: nonBlank,
+    next: nonBlank,
+    search: nonBlank,
+    noResults: nonBlank,
+  })
+  .strict();
+const localeSchema = z
+  .object({
+    id: pathSegment,
+    contentLocale: z.enum(['en', 'es', 'pt', 'fr', 'de', 'zh']),
+    label: nonBlank,
+    lang: nonBlank,
+    hreflang: nonBlank,
+    ogLocale: nonBlank,
+    nav: z.array(navItemSchema).length(4),
+    chrome: chromeSchema,
+  })
+  .strict();
+const donationSchema = z
+  .object({
+    id: z.enum(['btc', 'eth', 'sol']),
+    symbol: nonBlank,
+    network: nonBlank,
+    address: nonBlank,
+    qrPath: z.string().regex(/^\/donations\/[a-z0-9-]+\.svg$/u),
+    walletUri: z.url().nullable(),
+  })
+  .strict();
+
+export const productPublicSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    website: z
+      .object({
+        baseUrl: z.url(),
+        defaultLocale: pathSegment,
+        theme: z
+          .object({
+            defaultAppearance: z.literal('system'),
+            allowUserToggle: z.boolean(),
+          })
+          .strict(),
+        disabledRouteSegments: z.array(pathSegment).min(1),
+        locales: z.array(localeSchema).min(2),
+        newsletter: z
+          .object({
+            enabled: z.boolean(),
+            provider: z.enum(['none']),
+            signupUrl: z.url().nullable(),
+          })
+          .strict(),
+        sponsors: z
+          .object({
+            enabled: z.boolean(),
+            pagePath: z.string().startsWith('/'),
+            githubUrl: z.url(),
+            contactEmail: z.email(),
+          })
+          .strict(),
+      })
+      .strict(),
+    donations: z.array(donationSchema).length(3),
+    claims: z
+      .object({
+        installCommand: nonBlank,
+        publicToolInventory: z.array(pathSegment.or(z.string().regex(/^[a-z][a-z0-9_]+$/u))).min(1),
+        registryReadmeBaseline: z
+          .object({
+            package: z.literal('@planu/cli'),
+            version: z.string().regex(/^\d+\.\d+\.\d+$/u),
+            sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+          })
+          .strict(),
+      })
+      .strict(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const localeIds = value.website.locales.map(({ id }) => id);
+    const donationIds = value.donations.map(({ id }) => id);
+    const tools = value.claims.publicToolInventory;
+    for (const [items, path] of [
+      [localeIds, ['website', 'locales']],
+      [donationIds, ['donations']],
+      [tools, ['claims', 'publicToolInventory']],
+    ] as [string[], (string | number)[]][]) {
+      if (new Set(items).size !== items.length) {
+        context.addIssue({ code: 'custom', message: 'Entries must be unique', path });
+      }
+    }
+    if (!localeIds.includes(value.website.defaultLocale)) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Default locale must reference a declared locale',
+        path: ['website', 'defaultLocale'],
+      });
+    }
+    if (value.website.newsletter.enabled || value.website.newsletter.signupUrl !== null) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Newsletter provider must be configured before enabling subscriptions',
+        path: ['website', 'newsletter'],
+      });
+    }
+  });
+
+let cachedManifest: ProductPublicManifest | undefined;
+
+export function parseProductPublicManifest(input: unknown): ProductPublicManifest {
+  const result = productPublicSchema.safeParse(input);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const issuePath = issue?.path.join('.');
+    const location = issuePath?.length ? issuePath : 'root';
+    throw new Error(
+      `[Planu] Invalid public product manifest at ${location}: ${issue?.message ?? 'unknown error'}`,
+    );
+  }
+  return result.data;
+}
+
+export function getProductPublicManifest(): ProductPublicManifest {
+  cachedManifest ??= parseProductPublicManifest(rawProductPublic);
+  return cachedManifest;
+}
+
+export const productPublic = getProductPublicManifest();

package/dist/config/release-compatibility.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "nativeManifestSchema": 2,
+  "protocolAbi": 1,
+  "capabilityAbi": 2,
+  "nodeApiAbi": 4,
+  "storageSchema": { "minimum": 4, "maximum": 4 },
+  "sbom": { "format": "CycloneDX", "specVersion": "1.5" },
+  "capabilities": {
+    "base": ["core-acceleration-v1", "project-graph-v1"],
+    "byPlatform": { "darwin": ["macos-keychain-v1"] }
+  }
+}

package/dist/config/release-policy.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 1,
+  "supportedNativeTargets": 8,
+  "quality": { "branchCoverageMinimum": 88.1, "mutationScoreMinimum": 80 },
+  "native": {
+    "blockingCommands": [
+      "cargo fmt --manifest-path rust/planu-core/Cargo.toml --all -- --check",
+      "cargo clippy --manifest-path rust/planu-core/Cargo.toml --all-targets --all-features -- -D warnings",
+      "cargo test --manifest-path rust/planu-core/Cargo.toml --all-features",
+      "cargo test --manifest-path rust/planu-core/Cargo.toml --test property_invariants",
+      "cargo audit --file rust/planu-core/Cargo.lock",
+      "cargo deny check --config deny.toml"
+    ],
+    "performance": { "samples": 30, "warmups": 5, "p95RatioMaximum": 1.1, "rssP95RatioMaximum": 1.15 }
+  },
+  "workflowActions": {
+    "actions/checkout": "d23441a48e516b6c34aea4fa41551a30e30af803",
+    "actions/setup-node": "249970729cb0ef3589644e2896645e5dc5ba9c38",
+    "actions/upload-artifact": "b7c566a772e6b6bfb58ed0dc250532a479d7789f",
+    "actions/download-artifact": "018cc2cf5baa6db3ef3c5f8a56943fffe632ef53",
+    "actions/attest": "f7c74d28b9d84cb8768d0b8ca14a4bac6ef463e6",
+    "pnpm/action-setup": "fc06bc1257f339d1d5d8b3a19a8cae5388b55320",
+    "dtolnay/rust-toolchain": "2c7215f132e9ebf062739d9130488b56d53c060c",
+    "Swatinem/rust-cache": "e18b497796c12c097a38f9edb9d0641fb99eee32"
+  }
+}

package/dist/config/runtime-policy.json

@@ -0,0 +1,44 @@
+{
+  "acknowledgementBudgetMs": 200,
+  "toolExecution": {
+    "defaultTimeoutMs": 55000,
+    "minimumTimeoutMs": 1,
+    "maximumTimeoutMs": 600000,
+    "safetyMarginRatio": 0.05,
+    "safetyMarginMaximumMs": 500
+  },
+  "qualityAssurance": {
+    "defaultTimeoutMs": 300000,
+    "minimumTimeoutMs": 1000,
+    "maximumTimeoutMs": 900000,
+    "maximumOutputBufferBytes": 67108864
+  },
+  "lintValidation": {
+    "defaultTimeoutMs": 90000,
+    "minimumTimeoutMs": 1000,
+    "maximumTimeoutMs": 1800000
+  },
+  "createSpec": {
+    "criticalTimeoutMs": 25000,
+    "inlineAnalysisBudgetMs": 40,
+    "idempotencyClaimStaleMs": 60000,
+    "idempotencyClaimWaitMs": 25000,
+    "idempotencyClaimPollMs": 20,
+    "idempotencyMatchWindowMs": 600000
+  },
+  "validation": {
+    "defaultDeadlineMs": 1800000,
+    "submissionLockWaitMs": 180,
+    "submissionLockPollMs": 5,
+    "workerLeaseMs": 30000,
+    "workerHeartbeatMs": 1000,
+    "workerConcurrency": 2
+  },
+  "postCommit": {
+    "defaultTaskTimeoutMs": 10000,
+    "minimumLeaseMs": 30000,
+    "leaseMultiplier": 3,
+    "maximumRememberedTransitions": 1000,
+    "minimumHeartbeatMs": 1000
+  }
+}

package/dist/config/skill-templates/planu-validate.md

@@ -24,10 +24,12 @@ Use this skill after implementation is complete, before marking a spec as done,
 ## How it works
 
 1. **Find active spec** — calls `planu_status` to identify the current `implementing` spec
-2. **Run validation** — calls `validate({ specId })` which checks each acceptance criterion
-3. **Health check** — calls `spec_health_check({ specId })` for structural quality
-4. **Auto-fix** — calls `auto_fix_validation` for automatically fixable issues
-5. **Report** — presents a structured pass/fail report with next steps for each failure
+2. **Submit validation** — call `validate({ specId })` and capture its durable acknowledgement: `operationId`, `projectId`, `workspaceId`, and `cursor`
+3. **Wait for completion** — call `watch_job` with those identifiers and the latest cursor; repeat while state is non-terminal
+4. **Inspect the result** — require state `completed`, then read `job.result.structuredContent`; stop and report `failed`, `dead-letter`, or `cancelled` jobs
+5. **Health check** — call `spec_health_check({ specId })` for structural quality
+6. **Auto-fix** — call `auto_fix_validation` for automatically fixable issues, then submit and await a new validation job
+7. **Report** — present a structured pass/fail report from the completed job result
 
 ## Output format
 
@@ -53,4 +55,5 @@ Failures:
 
 - Run this skill before every commit on an implementing spec
 - If validation fails, fix the gaps and re-run — don't proceed to `done` with failures
+- Never interpret the initial `validate` acknowledgement as a pass; only `job.result.structuredContent` from a `completed` job is authoritative
 - Use the Planu Validator agent for a deeper analysis with fix suggestions

package/dist/config/subagent-templates/planu-spec-implementer.md

@@ -11,6 +11,8 @@ tools:
   - mcp__planu__list_specs
   - mcp__planu__update_status
   - mcp__planu__validate
+  - mcp__planu__get_job
+  - mcp__planu__watch_job
   - mcp__planu__check_readiness
   - mcp__planu__tdd_scaffold
 ---
@@ -33,9 +35,10 @@ You are an autonomous implementation agent for Spec Driven Development. Your job
 5. **Scaffold TDD tests** — call `tdd_scaffold` to generate test stubs from acceptance criteria.
 6. **Implement** — write all source files in dependency order: types → engine → storage → tools/resources. Follow Clean Architecture (types layer imports nothing; tools import engine+storage+types).
 7. **Run tests** — `pnpm typecheck && pnpm lint && pnpm test:coverage`. Fix all failures.
-8. **Validate** — call `validate({ specId })`. Fix any failing criteria.
-9. **Commit** — `git add <files> && git commit -m "feat(SPEC-NNN): <title>"`.
-10. **Update status to `done`** — call `update_status({ specId, status: "done" })`.
+8. **Submit validation** — call `validate({ specId })` and capture `operationId`, `projectId`, `workspaceId`, and `cursor` from the durable acknowledgement.
+9. **Await and inspect** — call `watch_job` with those identifiers and the latest cursor until terminal. Require `completed`, then inspect `job.result.structuredContent`. Stop on `failed`, `dead-letter`, or `cancelled`; fix failures and submit a new validation job.
+10. **Commit** — only after the completed validation result reports `ready: true`, `status: "passing"`, and passing quality gates, run `git add <files> && git commit -m "feat(SPEC-NNN): <title>"`.
+11. **Update status to `done`** — call `update_status({ specId, status: "done" })` only after that completed passing result.
 
 ## Rules
 
@@ -46,3 +49,4 @@ You are an autonomous implementation agent for Spec Driven Development. Your job
 - All Zod schemas must have `.describe()` on every field
 - Error messages must be actionable: "What failed + Why + What to do next"
 - Coverage must be ≥95% on new files before marking done
+- NEVER treat the initial `validate` acknowledgement as validation success

package/dist/config/subagent-templates/planu-validator.md

@@ -7,6 +7,8 @@ tools:
   - Glob
   - Grep
   - mcp__planu__validate
+  - mcp__planu__get_job
+  - mcp__planu__watch_job
   - mcp__planu__list_specs
   - mcp__planu__spec_health_check
   - mcp__planu__check_readiness
@@ -26,14 +28,16 @@ You are a validation specialist. Your job is to verify that implemented code sat
 ## Workflow
 
 1. **Load spec** — call `list_specs` and read `spec.md` for all acceptance criteria.
-2. **Run validation** — call `validate({ specId })`. Read the full output.
-3. **Run health check** — call `spec_health_check({ specId })` for structural issues.
-4. **Assess gaps** — for each failing criterion:
+2. **Submit validation** — call `validate({ specId })` and capture `operationId`, `projectId`, `workspaceId`, and `cursor` from the durable acknowledgement.
+3. **Wait for the terminal result** — call `watch_job` with those identifiers and the latest cursor. Repeat while state is `accepted`, `running`, or `checkpointed`. Require `completed`; stop and report `failed`, `dead-letter`, or `cancelled`.
+4. **Read the validation result** — inspect `job.result.structuredContent`. The acknowledgement is not a pass/fail result.
+5. **Run health check** — call `spec_health_check({ specId })` for structural issues.
+6. **Assess gaps** — for each failing criterion:
    - Identify which source files are responsible
    - Diagnose the root cause (missing logic, wrong condition, untested branch)
    - Propose a minimal fix
-5. **Auto-fix when safe** — call `auto_fix_validation` for fixable issues.
-6. **Report** — provide a summary with: passing count, failing count, and concrete next steps for each failure.
+7. **Auto-fix when safe** — call `auto_fix_validation` for fixable issues, then submit and await a new validation job.
+8. **Report** — provide a summary with: passing count, failing count, and concrete next steps for each failure.
 
 ## Output format
 
@@ -50,5 +54,6 @@ You are a validation specialist. Your job is to verify that implemented code sat
 ## Rules
 
 - Never mark a spec as done unless ALL criteria pass validation
+- Never mark a spec as done from a validate acknowledgement; require a `completed` job and inspect `job.result.structuredContent`
 - Never accept "mostly works" — every criterion is a contract
 - Flag ambiguous criteria as "needs clarification" rather than inventing semantics