arkgate 3.6.1 → 3.7.0

package/bin/lib/design-smells.mjs

@@ -29,7 +29,7 @@ export const DESIGN_SMELL_OUTCOMES = Object.freeze({
   'io-under-application':
     'Business/application code reaches the database or external APIs directly — the AI will keep pasting I/O into the wrong place. Put data access behind a port/adapter.',
   'handler-in-persistence':
-    'HTTP handlers live under data/repository folders — names look like “storage” but they are routes. Move handlers to the API/UI layer so the AI stops mixing transport and storage.',
+    'Static framework HTTP imports or route definitions live under data/repository folders — names look like “storage” but the code still owns transport. Move HTTP handling to the API/UI layer so the AI stops mixing transport and storage.',
   'god-module':
     'A few huge files own too many responsibilities — the AI cannot safely edit one concern without breaking others. Split the pilot file by job (one export surface per concern).',
   'domain-logic-in-ui':
@@ -70,6 +70,12 @@ const IO_IMPORT_RE =
   /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|better-sqlite3|ioredis|redis)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm)/;
 const HANDLER_CONTENT_RE =
   /\b(?:@Controller|@Get|@Post|@Put|@Delete|Router\(\)|createRouter|express\.Router|fastify\.(?:get|post)|export\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b|export\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=)/;
+const FRAMEWORK_HTTP_IMPORT_RE =
+  /(?:^|[;\n])\s*(?:import\s+(?:type\s+)?(?:[^;]{0,512}?\s+from\s+)?|export\s+(?:type\s+)?[^;]{0,512}?\s+from\s+)['"]next\/server(?:\.js)?['"]/;
+const ROUTE_DEFINITION_CALL_RE =
+  /\bdefineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/;
+const ROUTE_DEFINITION_DECLARATION_RE =
+  /\b(?:export\s+)?(?:declare\s+)?(?:async\s+)?function\s+defineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/g;
 const DOMAIN_LOGIC_UI_RE =
   /\b(?:export\s+)?(?:async\s+)?function\s+(?:can|calculate|compute|should)[A-Z]\w*|\b(?:export\s+)?const\s+(?:can|calculate|compute|should)[A-Z]\w*\s*=/;
 const EXPORT_RE =
@@ -139,7 +145,33 @@ function isPresentationLayer(name) {
 function isPersistenceLayer(name) {
   return (
     typeof name === 'string' &&
-    (/persist|repository|infra|data.?access/i.test(name) || name === 'PersistenceAdapters')
+    /persist|repository|data.?access/i.test(name)
+  );
+}
+
+function stripObviousCommentsAndTemplates(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/\/\/[^\n]*/g, ' ')
+    .replace(/`(?:\\[\s\S]|[^\\`])*`/g, ' ');
+}
+
+function hasFrameworkHttpImport(source) {
+  return FRAMEWORK_HTTP_IMPORT_RE.test(stripObviousCommentsAndTemplates(source));
+}
+
+function hasRouteDefinitionCall(source) {
+  const code = stripObviousCommentsAndTemplates(source)
+    .replace(/(["'])(?:\\.|(?!\1)[^\\\r\n])*\1/g, ' ')
+    .replace(ROUTE_DEFINITION_DECLARATION_RE, 'function __ark_defineRoute_declaration__(');
+  return ROUTE_DEFINITION_CALL_RE.test(code);
+}
+
+function hasHollowPersistenceShape(source) {
+  return (
+    hasFrameworkHttpImport(source) ||
+    hasRouteDefinitionCall(source) ||
+    HANDLER_CONTENT_RE.test(source)
   );
 }
 
@@ -172,6 +204,24 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
     relFiles.push(rel);
   }
+  // Y02: the general scan cap must not hide Persistence candidates in large
+  // trees. Filter by the stable role/path heuristics first, then bound reads.
+  const persistenceUniverse = [];
+  for (const f of files) {
+    const rel = normalizeRel(resolvedRoot, f);
+    if (!rel || rel.startsWith('..')) continue;
+    if (!/\.(ts|tsx|js|jsx|mts|cts)$/.test(rel)) continue;
+    if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
+    persistenceUniverse.push(rel);
+  }
+  const allPersistenceCandidates = [...new Set(persistenceUniverse)].sort().filter(
+    (rel) =>
+      PERSISTENCE_PATH_RE.test(rel) ||
+      isPersistenceLayer(layerNameFor(resolvedRoot, rel, config))
+  );
+  const persistenceCandidates = allPersistenceCandidates.slice(0, MAX_SCAN_FILES);
+  const persistenceCandidatesTruncated =
+    allPersistenceCandidates.length - persistenceCandidates.length;
 
   // soft-contract: layers with files but no rule edges
   const withoutRules = Array.isArray(coverage?.layersWithoutRules)
@@ -220,8 +270,7 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     }
     if (/\/(?:domain|application|infrastructure|adapters)\//.test(rel)) hasHexPorts = true;
 
-    const abs = path.join(resolvedRoot, rel);
-    const source = readTextLimited(abs);
+    const source = readTextLimited(path.join(resolvedRoot, rel));
     if (source == null) continue;
 
     const layer = layerNameFor(resolvedRoot, rel, config);
@@ -232,13 +281,6 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
       godEvidence.push(rel);
     }
 
-    if (
-      (PERSISTENCE_PATH_RE.test(rel) || isPersistenceLayer(layer)) &&
-      HANDLER_CONTENT_RE.test(source)
-    ) {
-      handlerInPersist.push(rel);
-    }
-
     if ((UI_PATH_RE.test(rel) || isPresentationLayer(layer)) && DOMAIN_LOGIC_UI_RE.test(source)) {
       domainInUi.push(rel);
     }
@@ -257,6 +299,13 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     }
   }
 
+  for (const rel of persistenceCandidates) {
+    const source = readTextLimited(path.join(resolvedRoot, rel));
+    if (source != null && hasHollowPersistenceShape(source)) {
+      handlerInPersist.push(rel);
+    }
+  }
+
   if (!falseGreen?.risk && ioUnderAppFiles.length > 0) {
     smells.push(
       makeDesignSmell({
@@ -270,13 +319,17 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
   }
 
   if (handlerInPersist.length > 0) {
+    const capNote =
+      persistenceCandidatesTruncated > 0
+        ? `; ${persistenceCandidatesTruncated} more Persistence candidate(s) were not inspected by the bounded scan`
+        : '';
     smells.push(
       makeDesignSmell({
         id: 'handler-in-persistence',
         severity: 'warn',
-        message: `HTTP/route handler shape found under persistence/repository paths (${handlerInPersist.length} file(s)) — semantic false-green risk.`,
+        message: `Static framework HTTP import or route-definition/handler shape found in Persistence-role modules (${handlerInPersist.length} file(s)${capNote}) — semantic false-green risk.`,
         evidence: handlerInPersist.slice(0, 12),
-        fix: 'Move handlers to Presentation/API; keep Persistence as data access only (/ark-explore shape-focus).',
+        fix: 'Move HTTP imports and route definitions to Presentation/API; keep Persistence as data access only (/ark-explore shape-focus).',
       })
     );
   }
@@ -414,7 +467,7 @@ function successSignalFor(id) {
     case 'io-under-application':
       return '0 Application-layer files import prisma/supabase/drizzle/pg clients; I/O behind ports';
     case 'handler-in-persistence':
-      return '0 HTTP handler shapes under persistence/repository globs';
+      return '0 static framework HTTP imports or route-definition/handler shapes in Persistence-role modules';
     case 'god-module':
       return 'Pilot god module split; fan-in and export surface reduced without new edge violations';
     case 'domain-logic-in-ui':

package/bin/lib/doctor-advisories.mjs

@@ -1,6 +1,6 @@
 /**
- * Doctor's advisory sensors, aggregated (W01 contract health + U05 ambient
- * state + X04 physical cohesion). Advisory only: nothing here feeds a
+ * Doctor's advisory sensors, aggregated (W01 contract health, U05 ambient
+ * state, X04 physical cohesion, Y03 parse health). Nothing here feeds a
  * verdict, designFitness, or an exit code. One seam keeps doctor-plan.mjs
  * inside its module budget as new advisory surfaces land.
  */
@@ -8,17 +8,30 @@ import { computeAmbientState, printAmbientStateSection } from './ambient-state.m
 import { computeContractHealth, printContractHealthSection } from './contract-smells.mjs';
 import {
   computePhysicalCohesion,
-  computeReshapePilot,
   printPhysicalCohesionSection,
 } from './physical-cohesion.mjs';
+import {
+  computeDecisionAwareReshapePilot,
+  computeReshapeDecisionMemory,
+  printReshapeDecisionsSection,
+} from './reshape-decisions.mjs';
+import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 
-export function computeDoctorAdvisories(root, config, cov, rules, files, ts) {
+export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth) {
   const physicalCohesion = computePhysicalCohesion(root, files);
-  physicalCohesion.reshapePilot = computeReshapePilot(physicalCohesion, files, root);
+  const decisionMemory = computeReshapeDecisionMemory(root, files);
+  physicalCohesion.reshapeDecisions = decisionMemory.summary;
+  physicalCohesion.reshapePilot = computeDecisionAwareReshapePilot(
+    physicalCohesion,
+    files,
+    root,
+    decisionMemory
+  );
   return {
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
     physicalCohesion,
+    parseHealth: parseHealth ?? summarizeParseHealth(),
   };
 }
 
@@ -30,4 +43,6 @@ export function printDoctorAdvisories(advisories, io) {
     advisories.physicalCohesion?.reshapePilot,
     io
   );
+  printReshapeDecisionsSection(advisories.physicalCohesion?.reshapeDecisions, io);
+  printParseHealthSection(advisories.parseHealth, io);
 }

package/bin/lib/doctor-plan.mjs

@@ -424,7 +424,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     patternBets: patternBetsForLoop,
     designSmells,
   });
-  const { contractHealth, ambientState, physicalCohesion } = computeDoctorAdvisories(root, config, cov, rules, files, options.ts); // W01+U05+X04 advisories — never a verdict
+  const doctorAdvisories = computeDoctorAdvisories(root, config, cov, rules, files, options.ts, options.parseHealth); // advisory only — never a verdict
 
   if (asJson) {
     console.log(
@@ -461,11 +461,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             goldenPattern,
             // Q04: one-pilot loop (extraction card → re-doctor).
             pilotLoop,
-            // Advisories, never a verdict: W01 contract health, U05 ambient
-            // state (opt-in), X04 physical cohesion + proposed reshape pilot.
-            contractHealth,
-            ambientState,
-            physicalCohesion,
+            // Advisories, never a verdict: W01 contract health, U05 ambient state,
+            // X04 physical cohesion/reshape pilot, Y03 parse health.
+            ...doctorAdvisories,
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
@@ -647,7 +645,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   }
 
-  printDoctorAdvisories({ contractHealth, ambientState, physicalCohesion }, { line, warn, color }); // advisory sections
+  printDoctorAdvisories(doctorAdvisories, { line, warn, color }); // advisory sections
 
   console.log('');
   console.log(color.bold('Coverage'));

package/bin/lib/html-report-advisories.mjs

@@ -152,6 +152,46 @@ function ambientStateHtml(state) {
   </section>`;
 }
 
+function reshapeDecisionsHtml(memory) {
+  if (!memory) return '';
+  const lifecycle = memory.lifecycle ?? {};
+  const rows = [];
+  if (memory.decisionFile?.invalid) {
+    rows.push(
+      `<p><span class="tag warn">invalid</span> ${esc(memory.decisionFile.path)} is ignored; no reshape decision suppresses a pilot.</p>`
+    );
+  }
+  for (const decision of memory.current ?? []) {
+    const tag = decision.verdict === 'accepted' ? 'ok' : 'warn';
+    const review = decision.reviewBy ? ` · review-by ${esc(decision.reviewBy)}` : '';
+    rows.push(
+      `<p><span class="tag ${tag}">${esc(decision.verdict)}</span> <b>${esc(decision.concept)}</b>${review} — ${esc(decision.reason)}${decision.suppressesPilot ? ' Pilot pressure suppressed; mirror facts remain visible.' : ' Pilot remains available.'}</p>`
+    );
+  }
+  if ((memory.currentCount ?? 0) > (memory.current?.length ?? 0)) {
+    rows.push(`<p class="muted">…(+${memory.currentCount - memory.current.length} more current decision(s))</p>`);
+  }
+  if ((lifecycle.expiredCount ?? 0) > 0) {
+    rows.push(`<p><span class="tag warn">expired</span> ${lifecycle.expiredCount} decision(s) no longer apply; pilot pressure is active again.</p>`);
+  }
+  if ((lifecycle.malformedCount ?? 0) > 0) {
+    rows.push(`<p><span class="tag warn">malformed</span> ${lifecycle.malformedCount} review-by date(s) are invalid; those decisions are ignored.</p>`);
+  }
+  if ((lifecycle.staleCount ?? 0) > 0) {
+    const stale = (lifecycle.stale ?? [])
+      .slice(0, 4)
+      .map((decision) => `<code>${esc(decision.concept)}</code>`)
+      .join(' · ');
+    const more = lifecycle.staleCount > 4 ? ` …(+${lifecycle.staleCount - 4} more)` : '';
+    rows.push(`<p><span class="tag warn">stale</span> ${lifecycle.staleCount} decision(s) have a changed anchor set and no longer apply: ${stale}${more}</p>`);
+  }
+  if ((lifecycle.undated ?? 0) > 0) {
+    rows.push(`<p class="muted">${lifecycle.undated} current decision(s) have no review-by date.</p>`);
+  }
+  if (rows.length === 0) return '';
+  return `<div data-advisory="reshapeDecisions"><h3>Reshape decisions <span class="muted">(explicit; pilot pressure only)</span></h3>${rows.join('\n')}</div>`;
+}
+
 function physicalCohesionHtml(pc) {
   if (!pc) return '';
   const findings = Array.isArray(pc.findings) ? pc.findings : [];
@@ -173,10 +213,28 @@ function physicalCohesionHtml(pc) {
   <section data-advisory="physicalCohesion">
     <h2>Physical cohesion <span class="muted">(advisory — facts, not a score; the verdict is unchanged)</span></h2>
     ${body}
+    ${reshapeDecisionsHtml(pc.reshapeDecisions)}
     ${pilot}
   </section>`;
 }
 
+function parseHealthHtml(health) {
+  if (!health) return '';
+  const files = Array.isArray(health.files) ? health.files : [];
+  const body = health.available === false
+    ? '<p class="muted">Parse health was not available for this rendering — no clean claim is made.</p>'
+    : health.affectedFiles === 0
+    ? `<p class="muted">No parse diagnostics found across ${health.scannedFiles ?? 0} governed file(s) scanned.</p>`
+    : `<p><span class="tag warn">${health.affectedFiles} affected</span> ${health.diagnosticCount} parse diagnostic(s) across ${health.scannedFiles} governed file(s).</p>` +
+      `<ul>${files.map((f) => `<li><code>${esc(f.file)}</code> — ${f.diagnosticCount} parse diagnostic(s)</li>`).join('')}</ul>` +
+      (health.truncated > 0 ? `<p class="muted">…(+${health.truncated} more affected file(s); doctor list capped)</p>` : '');
+  return `
+  <section data-advisory="parseHealth">
+    <h2>Parse health <span class="muted">(advisory — unreadable syntax is never silently called clean)</span></h2>
+    ${body}
+  </section>`;
+}
+
 /**
  * Render every doctor advisory as report sections. Keys must cover everything
  * `computeDoctorAdvisories` returns — the parity guard enforces it.
@@ -189,6 +247,7 @@ export function renderAdvisorySections(advisories, escape) {
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),
+    parseHealthHtml(advisories.parseHealth),
   ]
     .filter(Boolean)
     .join('\n');

package/bin/lib/parse-health.mjs

@@ -0,0 +1,74 @@
+/**
+ * Y03 — parse honesty over the ASTs already created by architecture-scan.
+ * Advisory only: counts are transported, never raw TypeScript diagnostics.
+ */
+
+export const PARSE_HEALTH_FILE_CAP = 12;
+
+function unavailableParseHealth(scannedFiles = 0) {
+  return {
+    advisory: true,
+    available: false,
+    status: 'unavailable',
+    scannedFiles,
+    affectedFiles: 0,
+    diagnosticCount: 0,
+    files: [],
+    truncated: 0,
+    overflow: false,
+  };
+}
+
+/** Aggregate cached/per-file parse counts into a deterministic doctor surface. */
+export function summarizeParseHealth(scanned) {
+  if (!Array.isArray(scanned)) return unavailableParseHealth();
+  const rows = scanned
+    .map(({ relFile, entry }) => ({
+      file: relFile,
+      diagnosticCount: entry?.parseDiagnosticCount,
+    }));
+  if (rows.some(({ file, diagnosticCount }) =>
+    typeof file !== 'string' || file.length === 0 ||
+    !Number.isSafeInteger(diagnosticCount) || diagnosticCount < 0
+  )) return unavailableParseHealth(rows.length);
+  const affected = rows
+    .filter(({ diagnosticCount }) => diagnosticCount > 0)
+    .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  let diagnosticCount = 0;
+  for (const row of affected) {
+    if (!Number.isSafeInteger(diagnosticCount + row.diagnosticCount)) {
+      return unavailableParseHealth(rows.length);
+    }
+    diagnosticCount += row.diagnosticCount;
+  }
+  const truncated = Math.max(0, affected.length - PARSE_HEALTH_FILE_CAP);
+  return {
+    advisory: true,
+    available: true,
+    status: affected.length > 0 ? 'parse-diagnostics' : 'ok',
+    scannedFiles: rows.length,
+    affectedFiles: affected.length,
+    diagnosticCount,
+    files: affected.slice(0, PARSE_HEALTH_FILE_CAP),
+    truncated,
+    overflow: truncated > 0,
+  };
+}
+
+/** Human doctor section; clean parse health stays quiet. */
+export function printParseHealthSection(health, io) {
+  if (!health || health.affectedFiles === 0) return;
+  console.log('');
+  console.log(io.color.bold('Parse health (advisory)'));
+  io.line(
+    io.warn,
+    `${health.affectedFiles} governed file(s) carry ${health.diagnosticCount} parse diagnostic(s) across ${health.scannedFiles} scanned file(s).`
+  );
+  for (const finding of health.files ?? []) {
+    io.line(io.warn, `${finding.file} — ${finding.diagnosticCount} parse diagnostic(s)`);
+  }
+  if (health.truncated > 0) {
+    io.line(' ', io.color.dim(`…(+${health.truncated} more affected file(s); list capped)`));
+  }
+  io.line(' ', io.color.dim('advisory only — the gate verdict, design fitness, and pattern bets are unchanged'));
+}

package/bin/lib/reshape-decisions.mjs

@@ -0,0 +1,284 @@
+/**
+ * Y01 — explicit verdict memory for X04 reshape pilots.
+ *
+ * Decisions bind to a concept plus its complete, sorted anchor set. Counts,
+ * move samples, and change-map hashes are deliberately excluded: evidence may
+ * drift without overturning an adopter's verdict, while a changed physical
+ * layout makes the old record stale. Advisory only; mirror facts stay intact.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { classifyPhysical, computeReshapePilot } from './physical-cohesion.mjs';
+
+export const RESHAPE_DECISIONS_PATH = '.ark/reshape-decisions.json';
+
+const MAX_DECISION_BYTES = 64 * 1024;
+const MAX_DECISIONS = 200;
+const MAX_LIFECYCLE_ITEMS = 12;
+const MAX_ANCHOR_EVIDENCE = 20;
+const VERDICTS = new Set(['accepted', 'deferred', 'rejected']);
+
+function normalizeAnchor(raw) {
+  const portable = String(raw).trim().replace(/\\/g, '/');
+  if (portable === '.') return '.';
+  if (!portable || portable.startsWith('/') || /^[A-Za-z]:\//.test(portable) || portable.includes('\0')) {
+    return null;
+  }
+  const segments = portable.split('/');
+  if (segments.some((segment) => !segment || segment === '.' || segment === '..')) return null;
+  return segments.join('/');
+}
+
+function targetKey(concept, anchors) {
+  return JSON.stringify([concept, anchors]);
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function sameStrings(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function lifecycleStatus(decision, today) {
+  const reviewBy = decision.reviewBy;
+  if (reviewBy === undefined) return 'undated';
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(reviewBy)) return 'malformed';
+  const date = new Date(`${reviewBy}T00:00:00.000Z`);
+  if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== reviewBy) {
+    return 'malformed';
+  }
+  return typeof today === 'string' && reviewBy < today ? 'expired' : 'current';
+}
+
+/** Bounded, fail-loud loader. A broken file never suppresses a pilot. */
+export function loadReshapeDecisions(root) {
+  const relPath = RESHAPE_DECISIONS_PATH;
+  const abs = path.join(root, relPath);
+  let stats;
+  try {
+    stats = fs.statSync(abs);
+  } catch {
+    return { path: relPath, exists: false, decisions: [] };
+  }
+  const invalid = (error) => ({ path: relPath, exists: true, invalid: true, error, decisions: [] });
+  if (!stats.isFile()) return invalid('not a regular file');
+  if (stats.size > MAX_DECISION_BYTES) {
+    return invalid(`larger than ${MAX_DECISION_BYTES} bytes`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch (error) {
+    return invalid(error instanceof Error ? error.message : 'unreadable JSON');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return invalid('expected an object with decisions[]');
+  }
+  const unknownTop = Object.keys(parsed).filter((key) => !['schemaVersion', 'decisions'].includes(key));
+  if (unknownTop.length > 0) return invalid(`unknown field: ${unknownTop[0]}`);
+  if (parsed.schemaVersion !== undefined && parsed.schemaVersion !== '1') {
+    return invalid('schemaVersion must be "1" when present');
+  }
+  if (!Array.isArray(parsed.decisions)) return invalid('expected { decisions: [...] }');
+  if (parsed.decisions.length > MAX_DECISIONS) {
+    return invalid(`more than ${MAX_DECISIONS} entries`);
+  }
+
+  const decisions = [];
+  const seen = new Set();
+  for (const entry of parsed.decisions) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      return invalid('every decision must be an object');
+    }
+    const unknown = Object.keys(entry).filter((key) =>
+      !['concept', 'anchors', 'verdict', 'reason', 'reviewBy'].includes(key)
+    );
+    if (unknown.length > 0) return invalid(`decision has unknown field: ${unknown[0]}`);
+    const concept = typeof entry.concept === 'string' ? entry.concept.trim() : '';
+    const reason = typeof entry.reason === 'string' ? entry.reason.trim() : '';
+    if (!concept || !reason || !VERDICTS.has(entry.verdict)) {
+      return invalid('every decision needs concept, verdict (accepted/deferred/rejected), and reason');
+    }
+    if (entry.reviewBy !== undefined && typeof entry.reviewBy !== 'string') {
+      return invalid('reviewBy must be a string when present');
+    }
+    if (!Array.isArray(entry.anchors) || entry.anchors.length === 0) {
+      return invalid('every decision needs a non-empty anchors array');
+    }
+    if (entry.anchors.some((anchor) => typeof anchor !== 'string')) {
+      return invalid('every decision anchor must be a string');
+    }
+    const anchors = entry.anchors.map(normalizeAnchor);
+    if (anchors.some((anchor) => anchor === null)) {
+      return invalid('anchors must be canonical project-relative paths');
+    }
+    anchors.sort();
+    if (new Set(anchors).size !== anchors.length) return invalid('decision anchors must be unique');
+    const key = targetKey(concept, anchors);
+    if (seen.has(key)) return invalid('duplicate decision target');
+    seen.add(key);
+    decisions.push({
+      concept,
+      anchors,
+      verdict: entry.verdict,
+      reason,
+      ...(entry.reviewBy !== undefined ? { reviewBy: entry.reviewBy } : {}),
+    });
+  }
+  decisions.sort(
+    (left, right) =>
+      compareText(left.concept, right.concept) ||
+      compareText(targetKey(left.concept, left.anchors), targetKey(right.concept, right.anchors))
+  );
+  return { path: relPath, exists: true, decisions };
+}
+
+function anchorsByConcept(root, files) {
+  const result = new Map();
+  const resolvedRoot = path.resolve(root);
+  for (const file of Array.isArray(files) ? files : []) {
+    const abs = path.isAbsolute(file) ? path.resolve(file) : path.resolve(root, file);
+    const rel = path.relative(resolvedRoot, abs);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) continue;
+    const classified = classifyPhysical(rel);
+    if (!classified) continue;
+    if (!result.has(classified.concept)) result.set(classified.concept, new Set());
+    result.get(classified.concept).add(classified.anchor);
+  }
+  return new Map([...result].map(([concept, anchors]) => [concept, [...anchors].sort()]));
+}
+
+/** Pure lifecycle/staleness resolution; callers inject `today` in tests. */
+export function analyzeReshapeDecisions(
+  root,
+  files,
+  state = { path: RESHAPE_DECISIONS_PATH, exists: false, decisions: [] },
+  today = null
+) {
+  const anchorSets = anchorsByConcept(root, files);
+  const current = [];
+  const expired = [];
+  const malformed = [];
+  const stale = [];
+  for (const decision of state.invalid ? [] : state.decisions ?? []) {
+    const currentAnchors = anchorSets.get(decision.concept) ?? [];
+    if (!sameStrings(decision.anchors, currentAnchors)) {
+      stale.push({
+        ...decision,
+        currentAnchorCount: currentAnchors.length,
+        currentAnchors: currentAnchors.slice(0, MAX_ANCHOR_EVIDENCE),
+      });
+      continue;
+    }
+    const status = lifecycleStatus(decision, today);
+    if (status === 'expired') expired.push(decision);
+    else if (status === 'malformed') malformed.push(decision);
+    else {
+      current.push({
+        ...decision,
+        lifecycle: status,
+        suppressesPilot: decision.verdict === 'deferred' || decision.verdict === 'rejected',
+      });
+    }
+  }
+  const summary = {
+    advisory: true,
+    explicitOnly: true,
+    neverChangesFacts: true,
+    decisionFile: {
+      path: state.path ?? RESHAPE_DECISIONS_PATH,
+      present: state.exists === true,
+      invalid: state.invalid === true,
+      ...(state.invalid ? { error: state.error ?? 'invalid' } : {}),
+    },
+    currentCount: current.length,
+    current: current.slice(0, MAX_LIFECYCLE_ITEMS),
+    lifecycle: {
+      undated: current.filter((decision) => decision.lifecycle === 'undated').length,
+      malformedCount: malformed.length,
+      malformed: malformed.slice(0, MAX_LIFECYCLE_ITEMS),
+      expiredCount: expired.length,
+      expired: expired.slice(0, MAX_LIFECYCLE_ITEMS),
+      staleCount: stale.length,
+      stale: stale.slice(0, MAX_LIFECYCLE_ITEMS),
+    },
+  };
+  return { summary, current, anchorSets };
+}
+
+/** Filesystem/clock wrapper for doctor and report callers. */
+export function computeReshapeDecisionMemory(root, files, today = new Date().toISOString().slice(0, 10)) {
+  return analyzeReshapeDecisions(root, files, loadReshapeDecisions(root), today);
+}
+
+/** Select one actionable finding while respecting explicit current verdicts. */
+export function computeDecisionAwareReshapePilot(cohesion, files, root, analysis) {
+  const findings = Array.isArray(cohesion?.findings) ? cohesion.findings : [];
+  if (findings.length === 0) return null;
+  const currentByTarget = new Map(
+    analysis.current.map((decision) => [targetKey(decision.concept, decision.anchors), decision])
+  );
+  for (const finding of findings) {
+    const anchors = analysis.anchorSets.get(finding.concept) ?? [];
+    const decision = currentByTarget.get(targetKey(finding.concept, anchors));
+    if (decision?.suppressesPilot) continue;
+    const pilot = computeReshapePilot({ ...cohesion, findings: [finding] }, files, root);
+    if (!pilot?.nextPilot) return pilot;
+    return {
+      ...pilot,
+      ...(decision ? { decision } : {}),
+      nextPilot: {
+        ...pilot.nextPilot,
+        decisionTarget: { concept: finding.concept, anchors },
+        decisionFile: RESHAPE_DECISIONS_PATH,
+      },
+    };
+  }
+  return {
+    proposed: false,
+    applied: false,
+    neverMechanicalSafe: true,
+    nextPilot: null,
+    suppressedByDecision: true,
+    note: 'Every displayed reshape target has an explicit current rejected/deferred decision; mirror facts remain visible.',
+  };
+}
+
+/** Human doctor section; lifecycle stays visible even after the sensor quiets. */
+export function printReshapeDecisionsSection(memory, io) {
+  const lifecycle = memory?.lifecycle;
+  const hasContent =
+    memory?.decisionFile?.invalid ||
+    memory?.currentCount > 0 ||
+    lifecycle?.expiredCount > 0 ||
+    lifecycle?.malformedCount > 0 ||
+    lifecycle?.staleCount > 0;
+  if (!hasContent) return;
+  console.log('');
+  console.log(io.color.bold('Reshape decisions (advisory)'));
+  if (memory.decisionFile.invalid) {
+    io.line(io.warn, `${memory.decisionFile.path} is present but invalid — decisions are ignored.`);
+  }
+  for (const decision of memory.current.slice(0, 5)) {
+    const review = decision.reviewBy ? ` · review-by ${decision.reviewBy}` : '';
+    io.line(' ', `[${decision.concept}] ${decision.verdict}${review} — ${decision.reason}`);
+  }
+  if (memory.currentCount > memory.current.slice(0, 5).length) {
+    io.line(' ', io.color.dim(`…(+${memory.currentCount - 5} more current decision(s))`));
+  }
+  if (lifecycle.expiredCount > 0) {
+    io.line(io.warn, `${lifecycle.expiredCount} reshape decision(s) expired — pilot pressure is active again.`);
+  }
+  if (lifecycle.malformedCount > 0) {
+    io.line(io.warn, `${lifecycle.malformedCount} reshape decision(s) have malformed review-by dates — ignored.`);
+  }
+  if (lifecycle.staleCount > 0) {
+    io.line(io.warn, `${lifecycle.staleCount} reshape decision(s) have a changed anchor set — stale; update or delete them.`);
+  }
+  if (lifecycle.undated > 0) {
+    io.line(' ', io.color.dim(`${lifecycle.undated} current decision(s) have no review-by date.`));
+  }
+  io.line(' ', io.color.dim('explicit verdicts affect pilot pressure only; physical facts and the gate verdict are unchanged'));
+}