arkgate 4.8.13 → 4.8.15

package/bin/ark-mcp-runtime.mjs

@@ -82,7 +82,10 @@ import {
   codexPatchWrites,
   proposedSource,
   emitHostAllow,
+  emitHostDeny,
   formatWriteGateDeny,
+  unclassifiedIncludedWriteDeny,
+  requiredOwnerWriteDeny,
 } from './lib/mcp-hook-payload.mjs';
 import {
   canonicalizeCandidateChanges,
@@ -257,6 +260,13 @@ function inferLayer(filePath, config, root) {
   return layerForFile(root, filePath, config.layers);
 }
 
+/** Pattern match only — layer.exclude is an intentional ungoverned hole, not a miss. */
+function layerPatternClaimsFile(filePath, config, root) {
+  if (!filePath) return false;
+  const layers = (config.layers ?? []).map((layer) => ({ ...layer, exclude: [] }));
+  return Boolean(layerForFile(root, filePath, layers));
+}
+
 async function loadArk() {
   const url = new URL('../dist/index.js', import.meta.url);
   if (!fs.existsSync(url)) {
@@ -472,6 +482,55 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     const governedWrites = canonicalSourceWrites.filter((change) =>
       isCandidateSourceInScope(config, change.path)
     );
+    const layerlessWrites = governedWrites.filter(
+      (change) =>
+        change.delete !== true &&
+        !inferLayer(change.path, config, args.root) &&
+        !layerPatternClaimsFile(change.path, config, args.root)
+    );
+    if (layerlessWrites.length > 0) {
+      const first = layerlessWrites[0];
+      const deny = unclassifiedIncludedWriteDeny(first.path);
+      const message = formatWriteGateDeny({
+        file: first.path,
+        reason: deny.message,
+        ruleId: deny.ruleId,
+        nextAction: deny.nextAction,
+      });
+      emitHostDeny(output, {
+        antigravityStyle,
+        cursorStyle,
+        grokStyle,
+        message,
+        file: first.path,
+      });
+      output.status(2);
+      return;
+    }
+    const unownedWrite = governedWrites.find((change) => {
+      if (change.delete === true) return false;
+      const house = inferLayer(change.path, config, args.root);
+      return Boolean(requiredOwnerWriteDeny(config, house, change.path));
+    });
+    if (unownedWrite) {
+      const house = inferLayer(unownedWrite.path, config, args.root);
+      const deny = requiredOwnerWriteDeny(config, house, unownedWrite.path);
+      const message = formatWriteGateDeny({
+        file: unownedWrite.path,
+        reason: deny.message,
+        ruleId: deny.ruleId,
+        nextAction: deny.nextAction,
+      });
+      emitHostDeny(output, {
+        antigravityStyle,
+        cursorStyle,
+        grokStyle,
+        message,
+        file: unownedWrite.path,
+      });
+      output.status(2);
+      return;
+    }
     const changes = governedWrites.map(({ path: relativePath, content, delete: deleted }) =>
       deleted ? { path: relativePath, delete: true } : { path: relativePath, content }
     );
@@ -608,6 +667,46 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
   }
 
   const layer = inferLayer(filePath, config, args.root);
+  if (
+    !layer &&
+    !layerPatternClaimsFile(filePath, config, args.root) &&
+    isCandidateSourceInScope(config, normalizedRel)
+  ) {
+    const deny = unclassifiedIncludedWriteDeny(normalizedRel);
+    const message = formatWriteGateDeny({
+      file: normalizedRel,
+      reason: deny.message,
+      ruleId: deny.ruleId,
+      nextAction: deny.nextAction,
+    });
+    emitHostDeny(output, {
+      antigravityStyle,
+      cursorStyle,
+      grokStyle,
+      message,
+      file: normalizedRel,
+    });
+    output.status(2);
+    return;
+  }
+  const ownerDeny = requiredOwnerWriteDeny(config, layer, normalizedRel);
+  if (ownerDeny) {
+    const message = formatWriteGateDeny({
+      file: normalizedRel,
+      reason: ownerDeny.message,
+      ruleId: ownerDeny.ruleId,
+      nextAction: ownerDeny.nextAction,
+    });
+    emitHostDeny(output, {
+      antigravityStyle,
+      cursorStyle,
+      grokStyle,
+      message,
+      file: normalizedRel,
+    });
+    output.status(2);
+    return;
+  }
   const validateOnce = (src) =>
     validateSnippetAnalysis({
       gate,
@@ -713,6 +812,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     ruleId: firstDiagnostic?.ruleId,
     nextAction: firstDiagnostic?.nextAction,
     extraLines: [
+      ...((result.completenessReasons ?? [])
+        .filter((reason) => reason.code === 'LEXICAL_EVIDENCE_INCOMPLETE')
+        .map((reason) => reason.message)
+        .filter(Boolean)),
       ...adapterResult.diagnostics.slice(1).map(
         (diagnostic) =>
           `[${diagnostic.ruleId}] ${diagnostic.message}${diagnostic.location.line ? ` (line ${diagnostic.location.line})` : ''}`
@@ -952,7 +1055,9 @@ function createResidentDoctorSession(args, config, ts) {
     config,
     manifest: args.projectManifest,
     rules,
-    files: before.files,
+    // Resident doctor is a full-tree snapshot. Do not pass the governed list
+    // as a --changed envelope (#212).
+    files: [],
     ts,
     args,
   });
@@ -1927,6 +2032,8 @@ export async function runArkMcp({ hookInput } = {}) {
         'Returns layer, mayImport / mustNotImport, forbiddenGlobals, and goldenPattern ' +
         '(load-bearing for NEW code when .ark/golden-pattern.json exists — adopt generates it). ' +
         'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
+        'When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. ' +
+        'When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. ' +
         'Call BEFORE writing a new file. ' +
         'Prefer ark_prepare_write when you already have the source snippet (place+validate+autoPatch in one call).',
       inputSchema: {
@@ -1953,7 +2060,9 @@ export async function runArkMcp({ hookInput } = {}) {
         'Also returns the versioned new/worsened designDelta for the proposed full file. ' +
         'Composes ark_place + write-gate — call BEFORE Write/Edit when you have the snippet. ' +
         'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
-        'Returns { filePath, layer, description?, valid, violations?, autoPatch?, judgmentBrief?, contentHash, ... }.',
+        'When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. ' +
+        'When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. ' +
+        'Returns { filePath, layer, description?, trustBoundary?, owners?, valid, violations?, autoPatch?, judgmentBrief?, contentHash, ... }.',
       inputSchema: {
         type: 'object',
         properties: {

package/bin/ark-shared.mjs

@@ -104,10 +104,85 @@ function mergeLayerPatterns(config, layerName, patterns, extras = {}) {
   }
 }
 
+/** Next-flavored start captions — applied only when Next is actually detected. */
+export const NEXT_LAYER_DESCRIPTIONS = Object.freeze({
+  ApplicationOrchestration:
+    'Use cases and services that coordinate the domain through ports. Next App Router API (`app/api/**`) and Pages API (`pages/api/**`) are orchestration shells, not UI.',
+  PresentationAdapters:
+    'Entrypoints — UI, framework app/pages dirs, controllers. Next `app/api` is Application, not this layer. Never bare lib/** (data clients are Persistence).',
+});
+
+/** Library / package-monorepo captions — no framework storefront. */
+export const LIBRARY_LAYER_DESCRIPTIONS = Object.freeze({
+  ApplicationOrchestration:
+    'Use cases and the package public surface that coordinate the domain. No I/O of its own.',
+  PresentationAdapters:
+    'Optional CLIs, docs, or demo UIs — not the published library core.',
+});
+
+function setLayerDescription(config, layerName, description) {
+  const layer = config.layers?.find((entry) => entry.name === layerName);
+  if (!layer || typeof description !== 'string' || description.length === 0) return;
+  layer.description = description;
+}
+
+/** packages/* (or similar) of published libraries — no app/cli units, no web framework. */
+export function isLibraryPackageMonorepo(signals) {
+  if (!signals || signals.nextFramework || signals.nestFramework || signals.expressLike) {
+    return false;
+  }
+  const units = Array.isArray(signals.repoUnits) ? signals.repoUnits : [];
+  const productive = units.filter(
+    (unit) => unit.root !== '.' && !['docs', 'example', 'test'].includes(unit.role)
+  );
+  if (productive.length === 0) return false;
+  return (
+    productive.some((unit) => unit.role === 'library') &&
+    !productive.some((unit) => unit.role === 'application' || unit.role === 'cli')
+  );
+}
+
+function applyFrameworkLayerCaptions(config, signals) {
+  const nextish = Boolean(
+    signals.nextFramework || (signals.ui && signals.toolHints?.includes('next'))
+  );
+  if (nextish) {
+    setLayerDescription(
+      config,
+      'ApplicationOrchestration',
+      NEXT_LAYER_DESCRIPTIONS.ApplicationOrchestration
+    );
+    setLayerDescription(
+      config,
+      'PresentationAdapters',
+      NEXT_LAYER_DESCRIPTIONS.PresentationAdapters
+    );
+    return;
+  }
+  if (
+    (signals.libraryOnly && !signals.nestFramework && !signals.expressLike) ||
+    isLibraryPackageMonorepo(signals)
+  ) {
+    setLayerDescription(
+      config,
+      'ApplicationOrchestration',
+      LIBRARY_LAYER_DESCRIPTIONS.ApplicationOrchestration
+    );
+    setLayerDescription(
+      config,
+      'PresentationAdapters',
+      LIBRARY_LAYER_DESCRIPTIONS.PresentationAdapters
+    );
+  }
+}
+
 /**
  * Framework-aware layout overlays. Detection uses collectRepoShapeSignals (deps + filenames).
- * Pure additive: never removes existing preset patterns. Goal: Nest/Next/express starters
- * reach meaningful governed% under hexagonal/layered without a hand-written adopt pass.
+ * Pure additive for patterns: never removes existing preset globs. Goal: Nest/Next/express
+ * starters reach meaningful governed% under hexagonal/layered without a hand-written adopt pass.
+ * Layer captions are the one replace: Next-flavored copy only when Next is present;
+ * library-native copy on library-only / library-package monorepos. Generic preset
+ * captions stay when neither applies.
  */
 export function applyFrameworkLayoutOverlays(config, root) {
   if (!config || !root) return config;
@@ -427,6 +502,7 @@ export function applyFrameworkLayoutOverlays(config, root) {
       : 'library';
   }
 
+  applyFrameworkLayerCaptions(next, signals);
   return withArkConfigMetadata(next);
 }
 
@@ -1082,7 +1158,9 @@ export function collectRepoShapeSignals(root) {
     return !excludedUnitRoots.some((prefix) => rel.startsWith(prefix));
   });
   const discoveredFileSet = new Set(sourceFiles.map((file) => path.resolve(file)));
-  const projectedGovernedCoverage = productionFiles.length === 0
+  // Files under detected source roots — NOT layer-governed coverage. User-facing
+  // "projected governed coverage" is computeCoverage (see projected-governed-coverage.mjs).
+  const discoveredSourceCoverage = productionFiles.length === 0
     ? 0
     : Math.round((productionFiles.filter((file) => discoveredFileSet.has(path.resolve(file))).length / productionFiles.length) * 100);
   const tinyTree = sourceFileCount < 3;
@@ -1261,7 +1339,7 @@ export function collectRepoShapeSignals(root) {
     libraryOnly,
     tinyTree,
     sourceFileCount,
-    projectedGovernedCoverage,
+    discoveredSourceCoverage,
     domain,
     application,
     domainHeavy,
@@ -1529,7 +1607,6 @@ export function scoreArchetypes(signals, playbook) {
       confidence,
       requiresConfirmation: true,
       confirmationReasons: [
-        `projected governed coverage is ${signals.projectedGovernedCoverage ?? 0}% (below 90%)`,
         'no archetype received a positive score',
       ],
       phases: fallback.phases,
@@ -1554,9 +1631,7 @@ export function scoreArchetypes(signals, playbook) {
     confidence = Math.min(confidence, 0.28);
   }
   const closeRecommendations = Boolean(second && top.score - second.score <= 2);
-  const lowProjectedCoverage = (signals.projectedGovernedCoverage ?? 0) < 90;
   if (closeRecommendations) confidence = Math.min(confidence, 0.49);
-  if (lowProjectedCoverage) confidence = Math.min(confidence, 0.49);
 
   return {
     ranked: scored,
@@ -1571,10 +1646,9 @@ export function scoreArchetypes(signals, playbook) {
             'TypeScript/JS surface is thin or missing — treat the archetype as a weak hint. Prefer ark-check --suggest-include / --adopt-contract on the real package roots before scaffolding.',
         }
       : {}),
-    requiresConfirmation: closeRecommendations || thinTs || lowProjectedCoverage,
+    requiresConfirmation: closeRecommendations || thinTs,
     confirmationReasons: [
       ...(closeRecommendations ? ['top recommendations are within 2 score points'] : []),
-      ...(lowProjectedCoverage ? [`projected governed coverage is ${signals.projectedGovernedCoverage}% (below 90%)`] : []),
       ...(thinTs ? ['the discovered source surface is thin'] : []),
     ],
     phases: top.phases,
@@ -1631,7 +1705,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
     policyPack: policyPackId,
     signals: {
       sourceFileCount: signals.sourceFileCount,
-      projectedGovernedCoverage: signals.projectedGovernedCoverage,
+      discoveredSourceCoverage: signals.discoveredSourceCoverage,
       discoveredRoots: signals.discoveredRoots,
       packageUnits: signals.repoUnits.map((unit) => ({
         root: unit.root,
@@ -1664,7 +1738,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
     // a thin slice and can mis-flag framework internals, so steer these to the adoption flow.
     mature: signals.sourceFileCount >= MATURE_REPO_FILE_THRESHOLD,
     initCommand: `${arkCommand(root, 'ark', `init --archetype ${result.archetype} --yes`)}`,
-    firstCommand: `${arkCommand(root, 'ark', `init --archetype ${result.archetype} --yes`)}`,
+    firstCommand: `${arkCommand(root, 'ark', `start --apply --archetype ${result.archetype}`)}`,
     adoptCommand: arkCommand(root, 'ark-check', '--recommend --write-plan'),
     recommendCommand: arkCommand(root, 'ark-check', '--recommend'),
     checkCommand: arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config'),
@@ -1705,6 +1779,49 @@ export function resolveArchetypePreset(archetypeId, playbookPath = defaultPlaybo
   };
 }
 
+/**
+ * Preset `ark start --internal-apply` / `--init` would write. Shared so recommend
+ * can project the same governed % start and doctor measure after that write.
+ */
+export function resolveStartInitPreset(root, rec = {}, archetype = rec.archetype) {
+  const presetFromArchetype =
+    archetype && isValidArchetypeId(archetype)
+      ? resolveArchetypePreset(archetype).preset
+      : undefined;
+  const preset = rec.preset || presetFromArchetype;
+  const includeRoots = resolveIncludeRoots(root);
+  const tsPackages = detectTsPackageRoots(root);
+  const nestedTsPackages = tsPackages.filter((entry) => entry !== '.');
+  const workspaces = detectWorkspaces(root);
+  const looksLikeMonorepo =
+    includeRoots.length > 0 ||
+    nestedTsPackages.length > 0 ||
+    workspaces.length > 0 ||
+    fs.existsSync(path.join(root, 'rush.json')) ||
+    fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) ||
+    fs.existsSync(path.join(root, 'lerna.json')) ||
+    fs.existsSync(path.join(root, 'apps')) ||
+    fs.existsSync(path.join(root, 'packages'));
+  if (rec.preset === 'vite-vercel-spa' || preset === 'vite-vercel-spa') {
+    return 'vite-vercel-spa';
+  }
+  if (looksLikeMonorepo && (rec.mature || includeRoots.length > 0 || tsPackages.length > 0)) {
+    const useUi =
+      rec.preset === 'feature-sliced' ||
+      rec.archetype === 'frontend-surface' ||
+      (nestedTsPackages.length > 0 && includeRoots.length === 0 && !rec.mature);
+    return useUi && nestedTsPackages.length <= 3 ? 'ui-surface' : 'monorepo';
+  }
+  return preset ?? null;
+}
+
+/** One-minute / preview footer when the coverage·confidence gate may refuse apply. */
+export const START_APPLY_REFUSE_FOOTER = [
+  'If apply refuses (coverage below 50% or weak shape), that lock is deliberate.',
+  'Lock the shape: --archetype <id>  ·  --preset <name>  ·  --force',
+  'Inspect ranked shapes: arkgate-check --recommend',
+].join('\n');
+
 export function mapWizardChoiceToArchetype(choiceKey) {
   const entry = INIT_WIZARD_CHOICES.find((c) => c.key === String(choiceKey).trim());
   if (!entry) return null;
@@ -1753,6 +1870,18 @@ export function formatArchitectureRecommendationHuman(recommendation) {
   lines.push('');
   lines.push(`Archetype: ${recommendation.archetype} — ${recommendation.label}`);
   lines.push(`Preset: ${recommendation.preset} (confidence ${recommendation.confidence})`);
+  const projected =
+    recommendation.projectedCoverage?.percent ??
+    recommendation.signals?.projectedGovernedCoverage;
+  if (typeof projected === 'number') {
+    const classified = recommendation.projectedCoverage?.classifiedFiles;
+    const total = recommendation.projectedCoverage?.totalFiles;
+    const counts =
+      typeof classified === 'number' && typeof total === 'number'
+        ? ` (${classified}/${total} files)`
+        : '';
+    lines.push(`Projected governed coverage: ${projected}%${counts}`);
+  }
   if (recommendation.requiresConfirmation) {
     lines.push('⚠ Confirmation required before applying this recommendation.');
     for (const reason of recommendation.confirmationReasons ?? []) lines.push(`  - ${reason}`);

package/bin/ark.mjs

@@ -8,10 +8,10 @@ import {
   arkCommand,
   buildArchitectureRecommendation,
   detectPackageManager,
-  detectWorkspaces,
   evaluateStartShapeConfidenceGate,
   resolveIncludeRoots,
   detectTsPackageRoots,
+  resolveStartInitPreset,
   INIT_WIZARD_CHOICES,
   isValidArchetypeId,
   mapWizardChoiceToArchetype,
@@ -586,41 +586,23 @@ async function start(args) {
     const configPath = path.join(root, 'ark.config.json');
     if (!fs.existsSync(configPath)) {
       const initArgs = ['--root', root, '--init'];
-      const preset = archetype ? resolveArchetypePreset(archetype).preset : undefined;
+      const startPreset = resolveStartInitPreset(root, rec ?? {}, archetype);
       const includeRoots = resolveIncludeRoots(root);
       const tsPackages = detectTsPackageRoots(root);
       const nestedTsPackages = tsPackages.filter((entry) => entry !== '.');
-      const workspaces = detectWorkspaces(root);
-      const looksLikeMonorepo =
-        includeRoots.length > 0 ||
-        nestedTsPackages.length > 0 ||
-        workspaces.length > 0 ||
-        fs.existsSync(path.join(root, 'rush.json')) ||
-        fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) ||
-        fs.existsSync(path.join(root, 'lerna.json')) ||
-        fs.existsSync(path.join(root, 'apps')) ||
-        fs.existsSync(path.join(root, 'packages'));
-      // SPA (Vite + root api/lib) wins over monorepo heuristics (NEW-SPA-DEFAULT-LAYOUT).
-      if (rec?.preset === 'vite-vercel-spa' || preset === 'vite-vercel-spa') {
+      if (startPreset === 'vite-vercel-spa') {
         initArgs.push('--preset', 'vite-vercel-spa');
         console.log('  Vite/Vercel SPA layout detected — include src,api,lib; api→Application; db clients→Persistence.');
-      } else if (looksLikeMonorepo && (rec?.mature || includeRoots.length > 0 || tsPackages.length > 0)) {
-        // Mature multi-package / nested-TS trees must NOT get a thin src/** starter (0 files).
-        // UI-heavy TS packages (Remotion/Vite) prefer ui-surface patterns when recommend says so.
-        const useUi =
-          rec?.preset === 'feature-sliced' ||
-          rec?.archetype === 'frontend-surface' ||
-          (nestedTsPackages.length > 0 && includeRoots.length === 0 && !rec?.mature);
-        initArgs.push('--preset', useUi && nestedTsPackages.length <= 3 ? 'ui-surface' : 'monorepo');
+      } else if (startPreset === 'monorepo' || startPreset === 'ui-surface') {
+        initArgs.push('--preset', startPreset);
         const shown = includeRoots.length > 0 ? includeRoots : nestedTsPackages;
         console.log(
           shown.length > 0
             ? `  Multi-package / TS package layout detected — profile include: ${shown.join(', ')}.`
             : '  Multi-package layout detected — using monorepo profile.'
         );
-      } else if (preset) {
-        // Prefer recommended preset even on mature single-package trees (avoid vacuum hexagonal).
-        initArgs.push('--preset', preset);
+      } else if (startPreset) {
+        initArgs.push('--preset', startPreset);
       }
       const status = runArkCheck(initArgs, { cwd: root });
       if (status !== 0) return status;

package/bin/lib/adr-presence.mjs

@@ -0,0 +1,97 @@
+/**
+ * Soft ADR / decision-note presence when gates are demanded.
+ * Tooling I/O. Never a gate fail. Absence is silent unless require-gates
+ * or adopted-strict (required-merge) is on.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Conventional homes a human already uses. First hit wins. No config key. */
+export const ADR_PRESENCE_HOMES = Object.freeze([
+  'docs/adr',
+  'docs/decisions',
+  'docs/adr.md',
+  'docs/decision-log.md',
+  'ADR.md',
+  'DECISIONS.md',
+]);
+
+export const ADR_PRESENCE_ASK =
+  'Gates are required here, but there is no short decision note yet.';
+
+export const ADR_PRESENCE_NEXT =
+  'Add a short note under docs/adr/ (or docs/decisions/) when you loosen a rule or add a real gate. Not every change.';
+
+function isNonEmptyMarkdownFile(file) {
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return false;
+  try {
+    return fs.readFileSync(file, 'utf8').trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function directoryHasMarkdown(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
+  try {
+    return fs.readdirSync(dir).some((name) => {
+      if (!name.toLowerCase().endsWith('.md')) return false;
+      return isNonEmptyMarkdownFile(path.join(dir, name));
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * First conventional decision-note home that already has a note.
+ * Empty folders and empty files do not count.
+ *
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function findAdrPresenceHome(root) {
+  if (typeof root !== 'string' || root.length === 0) return null;
+  for (const rel of ADR_PRESENCE_HOMES) {
+    const abs = path.join(root, rel);
+    if (rel.endsWith('.md')) {
+      if (isNonEmptyMarkdownFile(abs)) return rel;
+      continue;
+    }
+    if (directoryHasMarkdown(abs)) return rel;
+  }
+  return null;
+}
+
+/**
+ * Soft residual when gates are demanded and no decision-note home exists.
+ * `demanded` is --require-gates / --strict / --strict-merge, or doctor
+ * adopted === 'required-merge'. Off → null (silent).
+ *
+ * @param {{ root?: string, demanded?: boolean }} [input]
+ * @returns {{ missing: true, ask: string, nextAction: string } | null}
+ */
+export function collectAdrPresenceResidual(input = {}) {
+  if (input.demanded !== true) return null;
+  const home = findAdrPresenceHome(input.root ?? '');
+  if (home) return null;
+  return {
+    missing: true,
+    ask: ADR_PRESENCE_ASK,
+    nextAction: ADR_PRESENCE_NEXT,
+  };
+}
+
+/**
+ * Human hint for --require-gates. Never changes exit code.
+ *
+ * @param {string} root
+ * @param {(line: string) => void} write
+ */
+export function printAdrPresenceHint(root, write) {
+  const residual = collectAdrPresenceResidual({ root, demanded: true });
+  if (!residual || typeof write !== 'function') return;
+  write(residual.ask);
+  write(`Next: ${residual.nextAction}`);
+}

package/bin/lib/agent-projection-formatters.mjs

@@ -105,6 +105,8 @@ export function buildAgentProjectionBody(facts) {
         '',
         AGENT_PROJECTION_NON_ENFORCEMENT_LABEL,
         '',
+        'Contener · Guiar · Ordenar — contain the write, guide the next step, order leftover mess. Skills never enforce.',
+        '',
         `- **arkgateVersion:** \`${version}\` (must match the installed package; regenerate with \`ark agents-md --write\` after upgrade)`,
         `- **projectionSchema:** \`${ARK_AGENT_PROJECTION_SCHEMA_VERSION}\``,
         `- **profile:** \`${profile}\`${host ? ` · **host:** \`${host}\`` : ''}`,