arkgate 4.8.6 → 4.8.7

package/bin/lib/doctor-human.mjs

@@ -118,6 +118,9 @@ export function printDoctorCompactHuman(view) {
         ? ok
         : warn;
   line(govMark, `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`);
+  for (const row of cov.layers ?? []) {
+    if (row.description) line(' ', `${row.name} — ${row.description}`);
+  }
 
   const hostRed =
     gatesMissing.length > 0 ||
@@ -230,6 +233,12 @@ export function printDoctorDetailsHuman(view) {
     );
   }
   if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) line(ok, 'Every layer classifies files; no empty layers');
+  const captioned = (cov.layers ?? []).filter((row) => row.description);
+  if (captioned.length > 0) {
+    console.log('');
+    console.log(color.bold('Layers'));
+    for (const row of captioned) line(' ', `${row.name} — ${row.description}`);
+  }
 
   if (packageVersionTruth?.dualTruth) {
     console.log('');

package/bin/lib/doctor-plan.mjs

@@ -15,6 +15,7 @@ import { describePackageVersionDualTruth } from './field-install.mjs';
 import { detectAgentHomeGaps } from './agent-homes.mjs';
 import { collectDoctorNextActions } from './doctor-next-actions.mjs';
 import { printDoctorCompactHuman, printDoctorDetailsHuman } from './doctor-human.mjs';
+import { placementDescriptionFields } from './layer-description.mjs';
 export { printDoctorCompactHuman, printDoctorDetailsHuman };
 export { summarizeRulesUnderContract };
 
@@ -117,6 +118,7 @@ export function computeCoverage(root, config, files, rules) {
     name: layer.name,
     patterns: layer.patterns ?? [],
     files: counts.get(layer.name) ?? 0,
+    ...placementDescriptionFields(layer),
   }));
   // A layer whose patterns match zero files is dead config — it enforces nothing, usually a
   // wrong glob (the #1 monorepo mistake). A layer with no rule edge can import anything.
@@ -171,7 +173,8 @@ export function runCoverage(root, config, files, rules, asJson) {
   console.log(`  ${pad('Layer')}  Files`);
   for (const row of layerRows) {
     const flag = row.files === 0 ? '   (pattern matches nothing)' : '';
-    console.log(`  ${pad(row.name)}  ${String(row.files).padStart(5)}${flag}`);
+    const caption = row.description ? `  ${row.description}` : '';
+    console.log(`  ${pad(row.name)}  ${String(row.files).padStart(5)}${flag}${caption}`);
   }
   console.log(`  ${pad('(unclassified)')}  ${String(unclassified.length).padStart(5)}`);
   console.log('');
@@ -758,6 +761,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             productHonesty,
             governed: cov.governed,
             coverageHonesty,
+            layers: cov.layers,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
             ungovernedDirs: cov.suggestions.length,

package/bin/lib/html-report.mjs

@@ -25,6 +25,7 @@ import { capabilityBadgesFor, renderAdvisorySections } from './html-report-advis
 import { renderEvolutionSection } from './html-report-evolution.mjs';
 import { arkGitignoreAppendDecision } from './ark-gitignore.mjs';
 import { captureGitSnapshot } from './report-snapshot-context.mjs';
+import { layerDescriptionCaption } from './layer-description.mjs';
 
 export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
@@ -405,7 +406,7 @@ export function renderBeginnerHtmlReport({ root, config, violations, ok, version
 
   const placementRows = layers
     .map((layer) => {
-      const purpose = layer.description || 'See ark.config.json';
+      const purpose = layerDescriptionCaption(layer) || 'See ark.config.json';
       const folders = (layer.patterns || []).join(', ') || '—';
       return `<tr><td><strong>${esc(layer.name)}</strong></td><td>${esc(purpose)}</td><td><code>${esc(folders)}</code></td></tr>`;
     })
@@ -762,9 +763,10 @@ export function renderHtmlReport({
       ].join(' ');
       const example = exampleByLayer?.get?.(layer.name);
       const files = counts.get(layer.name) || 0;
+      const caption = layerDescriptionCaption(layer);
       return `<tr>
         <td class="ln">${esc(layer.name)}<div class="tags">${tags}</div></td>
-        <td>${layer.description ? esc(layer.description) : '<span class="dim">—</span>'}</td>
+        <td>${caption ? esc(caption) : '<span class="dim">—</span>'}</td>
         <td class="num">${files}</td>
         <td><code class="pat">${(layer.patterns || []).map(esc).join('<br>') || '—'}</code></td>
         <td>${example ? `<code>${esc(example)}</code>` : '<span class="dim">no files yet</span>'}</td>

package/bin/lib/layer-description.mjs

@@ -0,0 +1,27 @@
+/**
+ * App-context caption from `layers[].description`.
+ * Metadata only — callers project it; policyHash strips it elsewhere.
+ * Present non-empty string is returned; absence/empty/non-string is undefined.
+ *
+ * @param {{ description?: unknown } | null | undefined} layerOrPlacement
+ * @returns {string | undefined}
+ */
+export function layerDescriptionCaption(layerOrPlacement) {
+  const caption =
+    layerOrPlacement && typeof layerOrPlacement === 'object'
+      ? layerOrPlacement.description
+      : undefined;
+  return typeof caption === 'string' && caption.length > 0 ? caption : undefined;
+}
+
+/**
+ * Project the caption onto place / prepare-write / coverage / doctor JSON.
+ * Absence omits the field (never empty string).
+ *
+ * @param {{ description?: unknown } | null | undefined} layerOrPlacement
+ * @returns {{ description: string } | {}}
+ */
+export function placementDescriptionFields(layerOrPlacement) {
+  const caption = layerDescriptionCaption(layerOrPlacement);
+  return caption ? { description: caption } : {};
+}

package/bin/lib/prepare-write.mjs

@@ -7,6 +7,12 @@
 import crypto from 'node:crypto';
 import { validateWithAutoPatch } from './auto-patch.mjs';
 import { classifyRemediation, enrichViolationWithFixClass } from './remediation.mjs';
+import {
+  layerDescriptionCaption,
+  placementDescriptionFields,
+} from './layer-description.mjs';
+
+export { layerDescriptionCaption, placementDescriptionFields };
 
 /**
  * Stable content identity for host commit / cache keys.
@@ -114,7 +120,7 @@ export function composePrepareWrite(opts) {
     ...(placement?.suggestedLayers ? { suggestedLayers: placement.suggestedLayers } : {}),
     ...(placement?.message ? { placementMessage: placement.message } : {}),
     ...(placement?.note ? { placementNote: placement.note } : {}),
-    ...(placement?.description ? { description: placement.description } : {}),
+    ...placementDescriptionFields(placement),
     // Q03: pass through golden pattern from ark_place (advisory; absent is normal).
     ...(placement?.goldenPattern ? { goldenPattern: placement.goldenPattern } : {}),
     mode: gate.mode,

package/dist/{configTypes-dy5PfTqS.d.ts → configTypes-0eHpocR3.d.ts}

@@ -16,6 +16,10 @@ type ArkConfigLayer = {
     patterns: string[];
     exclude?: string[];
     intentPrefixes?: string[];
+    /**
+     * App-context caption for this layer.
+     * Metadata — excluded from policy hash. Absence is silent.
+     */
     description?: string;
     forbiddenGlobals?: string[];
     /** ADR 0009 D2 — opt-in effect-capability walls; absence changes no verdict. */

package/dist/{diagnosticCatalog-D_DI7qrZ.d.ts → diagnosticCatalog-wDAH08gH.d.ts}

@@ -1,5 +1,5 @@
-import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-BuM8WNqe.js';
-import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-dy5PfTqS.js';
+import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-BK47clMl.js';
+import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-0eHpocR3.js';
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 /**
@@ -409,7 +409,7 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
 };
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.6";
+declare const version = "4.8.7";
 
 /**
  * AI Code Gate (basic).

package/dist/eslint/index.d.ts

@@ -1,4 +1,4 @@
-import { A as ArkConfig } from '../configTypes-dy5PfTqS.js';
+import { A as ArkConfig } from '../configTypes-0eHpocR3.js';
 
 type RuleContext$1 = {
     report(descriptor: Record<string, unknown>): void;