@decantr/cli 3.4.2 → 3.5.1

package/README.md

@@ -22,7 +22,7 @@ Use `decantr setup` when you are unsure which path applies. It detects whether t
 Use `decantr scan` when you want a zero-commit Brownfield preview. It reads local files, detects framework/routes/styling/static-hosting/assistant-rule signals, previews typed Contract graph readiness in memory when a Decantr contract already exists, reports the contract capsule source-handle count and limit, prints a terminal report, and writes no `.decantr` files or report artifacts. Add `--json` when automation needs the `ScanReportV1` payload.
 Use `decantr new` for a greenfield workspace in a fresh directory. With a starter-kit blueprint or archetype it uses the runnable adapter and Decantr CSS; without certified vocabulary content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
 Use `decantr adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, hydrates hosted execution packs when online, and only applies the contract when you explicitly accept or merge it.
-Use `decantr studio` after adoption when you want a local visual view of routes, findings, and attention areas. Use `decantr doctor` when the next step is unclear, `decantr task <route> "<intent>"` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. If runtime source and Decantr context disagree, report the drift instead of guessing; in Brownfield the existing source is observed truth, accepted local law/style bridge is project authority where present, Essence V4 is the structural contract, and hosted packs stay advisory until mapped into local law. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
+Use `decantr studio` after adoption when you want a local Control Room for routes, findings, evidence, authority, and next actions. Use `decantr doctor` when the next step is unclear, `decantr task <route> "<intent>"` before asking an LLM to modify a route, `decantr verify` after the edit, `decantr resolve` when source and contract disagree, and `decantr ci` in required automation. If runtime source and Decantr context disagree, report the drift instead of guessing; in Brownfield the existing source is observed truth, accepted local law/style bridge is project authority where present, Essence V4 is the structural contract, and hosted packs stay advisory until mapped into local law. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Route and impact ranking use deterministic weighted traversal plus local personalized PageRank and task boosts. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
 In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`. In contract-only/offline Brownfield, deferred hosted packs are optional context unless a present manifest references missing files.
 Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
@@ -50,6 +50,7 @@ decantr studio
 decantr doctor
 decantr ci --fail-on error
 decantr ci init
+decantr resolve
 decantr codify --from-audit --style-bridge
 decantr codify --map-pattern hero
 decantr codify --accept
@@ -130,6 +131,7 @@ decantr adopt --yes
 decantr adopt --project apps/web --yes
 decantr doctor
 decantr doctor --project apps/web
+decantr resolve --project apps/web
 decantr codify --from-audit --style-bridge
 decantr codify --map-pattern hero --project apps/web
 decantr codify --accept
@@ -182,7 +184,7 @@ decantr showcase verification --json
 
 `decantr ci` is the blessed non-mutating automation gate. It runs the Project Health surface with adoption-mode-aware local law checks and emits a schema-backed CI report. `decantr ci init` writes root GitHub workflows or portable generic snippets using the detected package manager and pinned local CLI command instead of `@latest`; if the root manifest has not pinned Decantr yet, it prints the exact install command first.
 
-`decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, component reuse drift, accepted style bridge drift, accepted behavior-obligation checks, typed Contract graph freshness, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, stable diagnostic codes, typed repair IDs, and AI-ready remediation prompts. The graph freshness slice emits `GRAPH001` / `regenerate-typed-graph` when an attached app has missing, stale, or non-derivable `.decantr/graph` artifacts. The component reuse slice emits `COMP001` / `import-existing-component` when production source locally redeclares a common primitive that already exists as an exported reusable component, and `COMP010` / `replace-raw-control-with-local-component` when production JSX renders raw controls such as `<button>` while the project already owns a reusable primitive. The behavior-obligation slice emits `A11Y010`, `A11Y011`, `INT010`, `INT011`, `INT012`, `INT013`, and `COMP020` for high-confidence dialog/form regressions such as missing accessible names, missing label associations, missing visible destructive consequence copy, missing cancel affordances, missing submitting guards, implicit form button types, or bypassed project-owned interaction primitives. The style bridge slice emits `TOKEN010` / `replace-arbitrary-style-with-bridge-token` when production JSX, common class helpers, hardcoded inline color styles, or hardcoded visual values in CSS/module stylesheets bypass `.decantr/style-bridge.json` after it has been accepted as project-owned style authority. The baseline slice emits `VISUAL010` / `review-visual-baseline-drift` when `--since-baseline` detects changed screenshot hashes. When `.decantr/graph/graph.snapshot.json` exists, each finding is anchored to the most specific graph node Decantr can resolve, and JSON, markdown, text output, repair prompts, and Evidence Bundles carry that anchor. `decantr graph` also writes content-addressed history snapshots under `.decantr/graph/snapshots/` so repeated graph runs can be replayed across an AI edit sequence. When `.decantr/analysis.json` exists, `decantr graph` links observed routes/pages to implementation source artifacts and links exported reusable component declarations to their source files. When browser evidence writes `.decantr/evidence/visual-manifest.json`, `decantr graph` ingests it as local route/page Evidence nodes without uploading screenshots. When `.decantr/evidence/latest.json` exists, `decantr graph` can also materialize saved findings, evidence strings, graph anchors, repair IDs, and referenced repair/read target files as typed graph nodes and edges. When `.decantr/health-baseline-diff.json` exists, baseline changed files become file-level temporal evidence in the graph.
+`decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, component reuse drift, accepted style bridge drift, accepted behavior-obligation checks, typed Contract graph freshness, and execution-pack files into a v2 `ProjectHealthReport` with status, score, route summary, pack summary, findings, stable diagnostic codes, typed repair IDs, evidence tier, authority resolution, loop readiness, and AI-ready remediation prompts. The graph freshness slice emits `GRAPH001` / `regenerate-typed-graph` when an attached app has missing, stale, or non-derivable `.decantr/graph` artifacts. The component reuse slice emits `COMP001` / `import-existing-component` when production source locally redeclares a common primitive that already exists as an exported reusable component, and `COMP010` / `replace-raw-control-with-local-component` when production JSX renders raw controls such as `<button>` while the project already owns a reusable primitive. The behavior-obligation slice emits `A11Y010`, `A11Y011`, `INT010`, `INT011`, `INT012`, `INT013`, and `COMP020` for high-confidence dialog/form regressions such as missing accessible names, missing label associations, missing visible destructive consequence copy, missing cancel affordances, missing submitting guards, implicit form button types, or bypassed project-owned interaction primitives. The style bridge slice emits `TOKEN010` / `replace-arbitrary-style-with-bridge-token` when production JSX, common class helpers, hardcoded inline color styles, or hardcoded visual values in CSS/module stylesheets bypass `.decantr/style-bridge.json` after it has been accepted as project-owned style authority. The baseline slice emits `VISUAL010` / `review-visual-baseline-drift` when `--since-baseline` detects changed screenshot hashes. When `.decantr/graph/graph.snapshot.json` exists, each finding is anchored to the most specific graph node Decantr can resolve, and JSON, markdown, text output, repair prompts, and Evidence Bundles carry that anchor. `decantr graph` also writes content-addressed history snapshots under `.decantr/graph/snapshots/` so repeated graph runs can be replayed across an AI edit sequence. When `.decantr/analysis.json` exists, `decantr graph` links observed routes/pages to implementation source artifacts and links exported reusable component declarations to their source files. When browser evidence writes `.decantr/evidence/visual-manifest.json`, `decantr graph` ingests it as local route/page Evidence nodes without uploading screenshots. When `.decantr/evidence/latest.json` exists, `decantr graph` can also materialize saved findings, evidence strings, graph anchors, repair IDs, and referenced repair/read target files as typed graph nodes and edges. When `.decantr/health-baseline-diff.json` exists, baseline changed files become file-level temporal evidence in the graph.
 
 ```bash
 decantr verify
@@ -230,7 +232,7 @@ decantr verify --workspace --changed --since origin/main
 
 In observed Brownfield projects, common section shorthands are accepted for page and feature additions when they resolve unambiguously. For example, `decantr add page app/settings --route /settings --project apps/web` and `decantr add feature saved-recipes --section app --project apps/web` resolve `app` to the single primary section, such as `observed-primary`, so docs and LLM prompts do not have to guess generated section IDs first.
 
-`decantr studio` starts a local-only dashboard powered by the same report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, and `POST /api/refresh`.
+`decantr studio` starts a local-only Control Room powered by the same v2 report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, `GET /api/control-room`, `GET /api/resolve`, `GET /api/evidence`, `GET /api/graph-impact`, `GET /api/task-preview`, `GET /api/proof`, and `POST /api/refresh`.
 
 ```bash
 decantr studio
@@ -239,7 +241,7 @@ decantr studio --report decantr-health.json
 decantr studio --workspace
 ```
 
-Studio is for local triage, not Decantr admin telemetry. The Overview keeps the first decision simple: pick the issue to fix first, review the full AI repair prompt before copying it, switch to manual guidance or commands, and expand project details when route/runtime/pack evidence matters. The tabs cover Overview, Routes, Drift, Findings, Remediation, CI, and Packs without uploading source code, prompts, file paths, or project data.
+Studio is for local triage, not Decantr admin telemetry. The Control Room keeps the first decision simple: inspect loop state, next action, authority lane, blocking findings, evidence tier, graph impact, and copyable commands. The views cover Control Room, Routes, Graph Impact, Authority Resolver, Evidence, Repairs, and CI/Benchmarks without uploading source code, prompts, file paths, or project data.
 
 Workspace Studio uses `decantr workspace health` behind `GET /api/workspace` and `POST /api/workspace/refresh` so large monorepos can triage many Decantr projects from one local dashboard.
 

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-32WTNJQU.js";
+import "./chunk-S3ZDXBRM.js";
 import "./chunk-SIDKK73N.js";
-import "./chunk-BDA6TWV3.js";
-import "./chunk-PQKTJGYL.js";
-import "./chunk-2GCVVEQC.js";
+import "./chunk-MDQSTAP5.js";
+import "./chunk-EUEQMXN5.js";
+import "./chunk-PM7DKABI.js";

package/dist/{chunk-PQKTJGYL.js → chunk-EUEQMXN5.js}

@@ -3,7 +3,7 @@ import {
   sendProjectHealthCiFailedTelemetry,
   sendProjectHealthPromptTelemetry,
   sendProjectHealthReportTelemetry
-} from "./chunk-2GCVVEQC.js";
+} from "./chunk-PM7DKABI.js";
 
 // src/commands/health.ts
 import { execFileSync as execFileSync2 } from "child_process";
@@ -16,10 +16,14 @@ import {
   anchorFindingsToGraph,
   auditProject,
   buildProjectHealthRepairPlan,
+  createAuthorityResolution,
   createContractAssertions,
   createEvidenceBundle,
+  createEvidenceTier,
+  createLoopReadiness,
   deriveVerificationDiagnostic,
-  KNOWN_VERIFICATION_DIAGNOSTICS
+  KNOWN_VERIFICATION_DIAGNOSTICS,
+  PROJECT_HEALTH_REPORT_V2_SCHEMA_URL
 } from "@decantr/verifier";
 
 // src/workspace.ts
@@ -2729,18 +2733,20 @@ function buildGraphArtifacts(projectRoot, options = {}) {
   const sources = sourceArtifacts(projectRoot, componentReuseAudit);
   const combinedSourceHash = sourceHash(sources);
   const previousSnapshot = readJsonFile3(paths.snapshot);
-  const createdAt = previousSnapshot?.source_hash === combinedSourceHash ? previousSnapshot.created_at : (/* @__PURE__ */ new Date()).toISOString();
+  const previousDiff = readJsonFile3(paths.diff);
+  const sourceUnchanged = previousSnapshot?.source_hash === combinedSourceHash;
+  const createdAt = sourceUnchanged ? previousSnapshot.created_at : (/* @__PURE__ */ new Date()).toISOString();
   const snapshotId = `graph:${combinedSourceHash.replace(/^sha256:/, "").slice(0, 12)}`;
   paths = withSnapshotHistoryPath(paths, snapshotId);
   const baseSnapshot = buildGraphSnapshotFromEssence(essence, {
     snapshotId,
-    parentId: previousSnapshot && previousSnapshot.id !== snapshotId ? previousSnapshot.id : void 0,
+    parentId: sourceUnchanged ? previousSnapshot.parent_id : previousSnapshot ? previousSnapshot.id : void 0,
     sourceHash: combinedSourceHash,
     createdAt,
     sourceArtifact: sources[0]
   });
   const snapshot = augmentProjectGraph(baseSnapshot, projectRoot, sources, componentReuseAudit);
-  const diff = previousSnapshot ? diffGraphSnapshots(previousSnapshot, snapshot) : {
+  const diff = sourceUnchanged && previousDiff?.to === snapshot.id ? previousDiff : previousSnapshot ? diffGraphSnapshots(previousSnapshot, snapshot) : {
     $schema: GRAPH_DIFF_SCHEMA_URL,
     id: `diff:${snapshot.id}:${snapshot.id}`,
     from: snapshot.id,
@@ -3210,7 +3216,7 @@ var RED2 = "\x1B[31m";
 var GREEN2 = "\x1B[32m";
 var CYAN = "\x1B[36m";
 var YELLOW = "\x1B[33m";
-var PROJECT_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/project-health-report.v1.json";
+var PROJECT_HEALTH_SCHEMA_URL = PROJECT_HEALTH_REPORT_V2_SCHEMA_URL;
 var DEFAULT_HEALTH_CI_WORKFLOW_PATH = ".github/workflows/decantr-health.yml";
 var DEFAULT_HEALTH_CI_REPORT_PATH = "decantr-health.md";
 var DEFAULT_HEALTH_CI_JSON_PATH = "decantr-health.json";
@@ -4860,7 +4866,7 @@ async function createProjectHealthReport(projectRoot = process.cwd(), options =
   }));
   const finalCounts = countFindings(repairPlanFindings);
   const commandContext = commandContextForProject(projectRoot);
-  return {
+  const baseReport = {
     $schema: PROJECT_HEALTH_SCHEMA_URL,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     projectRoot,
@@ -4901,6 +4907,33 @@ async function createProjectHealthReport(projectRoot = process.cwd(), options =
     },
     findings: repairPlanFindings
   };
+  const evidenceTier = createEvidenceTier(baseReport, {
+    runtimeProbeCount: browserVerification ? Math.max(1, browserVerification.evidence.screenshots.length) : void 0,
+    visualArtifactCount: browserVerification?.evidence.screenshots.length ?? 0
+  });
+  const authority = createAuthorityResolution(baseReport);
+  const loop = createLoopReadiness(baseReport, authority, evidenceTier);
+  return {
+    ...baseReport,
+    evidenceTier,
+    authority,
+    loop,
+    findings: repairPlanFindings.map((finding) => {
+      const conflict = authority.conflicts.find((entry) => entry.id === finding.id);
+      return {
+        ...finding,
+        evidenceTier,
+        authorityLane: conflict?.lane ?? authority.activeLane,
+        resolutionActions: conflict?.recommendedActions,
+        privacy: {
+          sourceIncluded: false,
+          redacted: true,
+          localOnly: true
+        },
+        loopVerdict: loop.state
+      };
+    })
+  };
 }
 function colorForStatus(status) {
   if (status === "healthy") return GREEN2;
@@ -4954,6 +4987,11 @@ function formatProjectHealthText(report) {
     `  Packs: manifest ${report.packs.manifestPresent ? "present" : "missing"} | review ${report.packs.reviewPackPresent ? "present" : "missing"} | pages ${report.packs.pagePackCount}`,
     `  Graph: ${report.graph.current === null ? "not attached" : report.graph.current ? "current" : "stale"} | capsule ${report.graph.capsulePresent ? "present" : "missing"} | sources ${report.graph.sourceArtifactCount}`,
     "",
+    `${BOLD}Control loop:${RESET2}`,
+    `  State: ${report.loop.state} | evidence ${report.evidenceTier.confidence.level} (${report.evidenceTier.confidence.score})`,
+    `  Authority: ${report.authority.activeLane} \u2014 ${report.authority.summary}`,
+    `  Next: ${report.loop.nextActions[0] ?? report.loop.verifyCommand}`,
+    "",
     `${BOLD}Findings:${RESET2}`
   ];
   if (report.findings.length === 0) {
@@ -4986,6 +5024,7 @@ function formatProjectHealthText(report) {
   }
   lines.push("");
   lines.push(`${BOLD}CI:${RESET2} ${report.ci.recommendedCommand}`);
+  lines.push(`${BOLD}Loop verify:${RESET2} ${report.loop.verifyCommand}`);
   return `${lines.join("\n")}
 `;
 }
@@ -5001,6 +5040,9 @@ function formatProjectHealthMarkdown(report) {
     `- Runtime audit: ${report.summary.runtimeAuditChecked ? report.summary.runtimePassed ? "passed" : "failed" : "not checked"}`,
     `- Packs: manifest ${report.packs.manifestPresent ? "present" : "missing"}, review ${report.packs.reviewPackPresent ? "present" : "missing"}`,
     `- Graph: ${report.graph.current === null ? "not attached" : report.graph.current ? "current" : "stale"}, capsule ${report.graph.capsulePresent ? "present" : "missing"}, sources ${report.graph.sourceArtifactCount}`,
+    `- Loop: **${report.loop.state}** (${report.loop.status})`,
+    `- Evidence tier: **${report.evidenceTier.stage}** / ${report.evidenceTier.confidence.level}`,
+    `- Authority: **${report.authority.activeLane}**`,
     "",
     "## Findings",
     ""
@@ -5084,6 +5126,12 @@ function formatDiagnosticCatalogText() {
 async function createProjectEvidenceBundle(projectRoot, report, options = {}) {
   const audit = await auditProject(projectRoot);
   const assertions = createContractAssertions(projectRoot, audit);
+  const visualManifestPath = join5(projectRoot, ".decantr", "evidence", "visual-manifest.json");
+  const browserEvidence = await browserEvidenceFromOptions(
+    projectRoot,
+    options,
+    report.routes.declared
+  );
   return createEvidenceBundle({
     projectRoot,
     report,
@@ -5091,7 +5139,36 @@ async function createProjectEvidenceBundle(projectRoot, report, options = {}) {
     assertions,
     workspaceConfigPath: existsSync5(join5(projectRoot, ".decantr", "workspace.json")) ? join5(projectRoot, ".decantr", "workspace.json") : null,
     designTokensPath: resolveOptionalPath(projectRoot, options.designTokensPath) ?? null,
-    browser: await browserEvidenceFromOptions(projectRoot, options, report.routes.declared),
+    visualManifestPath: existsSync5(visualManifestPath) ? visualManifestPath : null,
+    artifacts: [
+      {
+        id: "artifact:evidence-bundle",
+        kind: "evidence-bundle",
+        path: ".decantr/evidence/evidence-bundle.json",
+        hash: null,
+        localOnly: true,
+        redacted: true
+      },
+      ...existsSync5(visualManifestPath) ? [
+        {
+          id: "artifact:visual-manifest",
+          kind: "visual-manifest",
+          path: ".decantr/evidence/visual-manifest.json",
+          hash: null,
+          localOnly: true,
+          redacted: true
+        }
+      ] : [],
+      ...(browserEvidence?.screenshots ?? []).map((screenshot, index) => ({
+        id: `artifact:screenshot:${index + 1}`,
+        kind: "screenshot",
+        path: screenshot,
+        hash: null,
+        localOnly: true,
+        redacted: false
+      }))
+    ],
+    browser: browserEvidence,
     designTokens: collectDesignTokenEvidence(projectRoot, options.designTokensPath)
   });
 }

package/dist/{chunk-BDA6TWV3.js → chunk-MDQSTAP5.js}

@@ -1,19 +1,20 @@
 import {
   createProjectHealthReport,
   listWorkspaceAppCandidates
-} from "./chunk-PQKTJGYL.js";
+} from "./chunk-EUEQMXN5.js";
 
 // src/commands/workspace.ts
 import { execFileSync } from "child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join, relative, resolve } from "path";
+import { WORKSPACE_HEALTH_REPORT_V2_SCHEMA_URL } from "@decantr/verifier";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
 var GREEN = "\x1B[32m";
 var RED = "\x1B[31m";
 var YELLOW = "\x1B[33m";
 var RESET = "\x1B[0m";
-var WORKSPACE_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/workspace-health-report.v1.json";
+var WORKSPACE_HEALTH_SCHEMA_URL = WORKSPACE_HEALTH_REPORT_V2_SCHEMA_URL;
 var DEFAULT_IGNORES = /* @__PURE__ */ new Set([
   ".git",
   ".next",
@@ -181,7 +182,9 @@ async function createWorkspaceHealthReport(root = process.cwd(), options = {}) {
         durationMs: Date.now() - startedAt,
         changed: options.changedOnly ? projectChanged(project, changed) : false,
         source: project.source,
-        error: null
+        error: null,
+        loopState: report.loop.state,
+        loopNextAction: report.loop.nextActions[0] ?? null
       };
     } catch (error) {
       return {
@@ -196,23 +199,44 @@ async function createWorkspaceHealthReport(root = process.cwd(), options = {}) {
         durationMs: Date.now() - startedAt,
         changed: options.changedOnly ? projectChanged(project, changed) : false,
         source: project.source,
-        error: error.message
+        error: error.message,
+        loopState: "blocked_missing_context",
+        loopNextAction: "Fix the project health failure, then rerun workspace health."
       };
     }
   });
+  const summary = {
+    projectCount: allProjects.length,
+    checkedCount: checked.length,
+    healthyCount: checked.filter((project) => project.status === "healthy").length,
+    warningCount: checked.filter((project) => project.status === "warning").length,
+    errorCount: checked.filter((project) => project.status === "error").length,
+    failedCount: checked.filter((project) => project.status === "failed").length
+  };
+  const blockedCount = checked.filter(
+    (project) => project.loopState?.startsWith("blocked") || project.loopState === "human_resolution_required"
+  ).length;
+  const repairRequiredCount = checked.filter(
+    (project) => project.loopState === "repair_required"
+  ).length;
+  const workspaceLoopState = checked.length === 0 ? "needs_context" : blockedCount > 0 ? "human_resolution_required" : repairRequiredCount > 0 || summary.errorCount > 0 || summary.warningCount > 0 ? "repair_required" : "verified";
+  const workspaceLoopStatus = workspaceLoopState === "human_resolution_required" || workspaceLoopState.startsWith("blocked") ? "blocked" : summary.errorCount > 0 || summary.failedCount > 0 ? "error" : summary.warningCount > 0 ? "warning" : "healthy";
   return {
     $schema: WORKSPACE_HEALTH_SCHEMA_URL,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     workspaceRoot,
     changedOnly: options.changedOnly ?? false,
     since: options.changedOnly ? since : null,
-    summary: {
-      projectCount: allProjects.length,
-      checkedCount: checked.length,
-      healthyCount: checked.filter((project) => project.status === "healthy").length,
-      warningCount: checked.filter((project) => project.status === "warning").length,
-      errorCount: checked.filter((project) => project.status === "error").length,
-      failedCount: checked.filter((project) => project.status === "failed").length
+    summary,
+    loop: {
+      state: workspaceLoopState,
+      status: workspaceLoopStatus,
+      projectCount: checked.length,
+      blockedCount,
+      repairRequiredCount,
+      nextActions: [
+        workspaceLoopState === "verified" ? "Workspace loop verified." : 'Open the highest-risk project, run `decantr task <route> "<intent>"`, repair, then rerun `decantr verify`.'
+      ]
     },
     projects: checked
   };
@@ -223,6 +247,7 @@ function formatWorkspaceHealthText(report) {
     "",
     `Projects: ${report.summary.checkedCount}/${report.summary.projectCount}`,
     `Healthy: ${report.summary.healthyCount} | Warnings: ${report.summary.warningCount} | Errors: ${report.summary.errorCount} | Failed: ${report.summary.failedCount}`,
+    `Loop: ${report.loop.state} | blocked ${report.loop.blockedCount} | repair ${report.loop.repairRequiredCount}`,
     ""
   ];
   for (const project of report.projects) {

package/dist/{chunk-2GCVVEQC.js → chunk-PM7DKABI.js}

@@ -562,6 +562,11 @@ function detectPathnameBranchRoutes(content) {
   if (strongMatches > 0 || hasPathnameSignal) {
     collectRouteLiterals(/\b(?:href|to)\s*=\s*["'`](\/[^"'`]+)["'`]/g, content, routes);
   }
+  if (hasPathnameSignal && (/\?\s*["'`]\/["'`]\s*:/.test(content) || /\|\|\s*["'`]\/["'`]/.test(content) || /\b(?:defaultRoute|defaultPath|fallbackRoute|fallbackPath)\s*[:=]\s*["'`]\/["'`]/.test(
+    content
+  ))) {
+    routes.add("/");
+  }
   return [...routes];
 }
 function hasReactRouterDependency(projectRoot) {
@@ -1441,6 +1446,18 @@ function loadJsonEntries(dir) {
     return [];
   }
 }
+function readJson(path) {
+  if (!existsSync7(path)) return null;
+  try {
+    return JSON.parse(readFileSync7(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function addPattern(registry, id, source, data = null) {
+  if (typeof id !== "string" || !id.trim() || registry.has(id)) return;
+  registry.set(id, data ?? { id, source });
+}
 function buildGuardRegistryContext(projectRoot = process.cwd()) {
   const themeRegistry = /* @__PURE__ */ new Map();
   const patternRegistry = /* @__PURE__ */ new Map();
@@ -1461,21 +1478,22 @@ function buildGuardRegistryContext(projectRoot = process.cwd()) {
     }
   }
   for (const data of loadJsonEntries(join7(cacheDir, "@official", "patterns"))) {
-    if (typeof data.id === "string" && !patternRegistry.has(data.id)) {
-      patternRegistry.set(data.id, data);
-    }
+    addPattern(patternRegistry, data.id, "cache", data);
   }
   for (const entry of loadBundledContentList("patterns")) {
     const data = entry.data;
     const id = typeof data.id === "string" ? data.id : entry.id;
-    if (!patternRegistry.has(id)) {
-      patternRegistry.set(id, data);
-    }
+    addPattern(patternRegistry, id, "bundled", data);
   }
   for (const data of loadJsonEntries(join7(customDir, "patterns"))) {
-    if (typeof data.id === "string") {
-      patternRegistry.set(data.id, data);
-    }
+    addPattern(patternRegistry, data.id, "custom", data);
+  }
+  const localPatterns = readJson(join7(projectRoot, ".decantr", "local-patterns.json"));
+  const patterns = Array.isArray(localPatterns?.patterns) ? localPatterns.patterns : [];
+  for (const pattern of patterns) {
+    if (!pattern || typeof pattern !== "object") continue;
+    const data = pattern;
+    addPattern(patternRegistry, data.id, "local-law", data);
   }
   return { themeRegistry, patternRegistry };
 }