@khoavu882/doflow 2.0.0 → 2.0.2

package/src/lifecycle/coverage.js

@@ -2,7 +2,6 @@
 
 const crypto = require('node:crypto');
 const CLASS_ORDER = Object.freeze(['unknown', 'unsupported', 'observation', 'advisory', 'blocking']);
-const POLICY_ORDER = Object.freeze(['pre-implementation-gate', 'pre-bash-guard', 'session-context', 'mcp-tool-guard', 'stop-check']);
 const HARNESS_ORDER = Object.freeze(['claude', 'codex', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity']);
 const BEHAVIOUR_ORDER = Object.freeze(['context-authority', 'default-silence', 'summary-scope', 'summary-grant', 'identity', 'check-freshness']);
 const NEVER_BLOCKING_EVENTS = new Set([
@@ -43,32 +42,4 @@ function enforcementFor(coverage     , query
     reason: weakest ? `${weakest.class} at (${weakest.policy}, ${weakest.harness}, ${weakest.event}, ${weakest.profile})` : `unknown at (${query.policy}, ${query.harness}, *, ${query.profile ?? '*'})`,
   };
 }
-function renderEnforcementMatrix(coverage     )         {
-  const order = (items                   , value        ) => {
-    const index = items.indexOf(value);
-    return index < 0 ? items.length : index;
-  };
-  const rows = [...coverage.rows].sort((a     , b     ) => order(POLICY_ORDER, a.policy) - order(POLICY_ORDER, b.policy)
-    || order(HARNESS_ORDER, a.harness) - order(HARNESS_ORDER, b.harness)
-    || a.event.localeCompare(b.event) || a.profile.localeCompare(b.profile));
-  const lines = [`Schema ${coverage.schemaVersion}; revision ${coverage.revision}; ${coverage.rowsDigest}`, '| Policy | Harness | Native event | Profile | Class | Verification | Prerequisites | Does not cover |', '|---|---|---|---|---|---|---|---|'];
-  for (const row of rows) lines.push(`| ${row.policy} | ${row.harness} | ${row.event} | ${row.profile} | ${row.class} | ${row.verification} | ${(row.prerequisites || []).join(', ')} | ${(row.doesNotCover || []).join(', ')} |`);
-  return lines.join('\n');
-}
-// IC-019: one row per behaviour x harness, ordered by IC-018's behaviour list, then HARNESS_ORDER.
-function renderBehaviourMatrix(coverage     )         {
-  const order = (items                   , value        ) => {
-    const index = items.indexOf(value);
-    return index < 0 ? items.length : index;
-  };
-  const entries = [...(coverage.behaviours || [])].sort((a     , b     ) => order(BEHAVIOUR_ORDER, a.behaviour) - order(BEHAVIOUR_ORDER, b.behaviour)
-    || order(HARNESS_ORDER, a.harness) - order(HARNESS_ORDER, b.harness)
-    || a.behaviour.localeCompare(b.behaviour) || a.harness.localeCompare(b.harness));
-  const lines = [`Schema ${coverage.schemaVersion}; revision ${coverage.revision}`, '| Behaviour | Harness | Status | Limitation or tests |', '|---|---|---|---|'];
-  for (const entry of entries) {
-    const detail = entry.status === 'enforced' ? (entry.tests || []).join(', ') : (entry.limitation || '');
-    lines.push(`| ${entry.behaviour} | ${entry.harness} | ${entry.status} | ${detail} |`);
-  }
-  return lines.join('\n');
-}
-module.exports = { enforcementFor, renderEnforcementMatrix, renderBehaviourMatrix, BEHAVIOUR_ORDER, HARNESS_ORDER, rowsDigest, UnknownEnforcementTarget, NEVER_BLOCKING_EVENTS };
+module.exports = { enforcementFor, BEHAVIOUR_ORDER, HARNESS_ORDER, rowsDigest, UnknownEnforcementTarget, NEVER_BLOCKING_EVENTS };

package/src/lifecycle/hook-tier.js

@@ -39,13 +39,13 @@ function resolveHookTier({ env = process.env, loadSettings }
 }
 
 /** One WARN line per planned harness that gets no hooks although it is the primary session (claude)
- * or a worker the person configured: there it runs without DoFlow's destructive-command guard. */
+ * or a worker the person configured: there it runs without DoFlow's gates. */
 function hookTierWarnings(registry     , targets          , tier                                                   )           {
   const warnings           = [];
   for (const harness of registry.harnesses) {
     if (!targets.includes(harness.id) || tier.harnesses.includes(harness.id) || !getsHooks(registry, harness)) continue;
     const role = harness.id === 'claude' ? 'the primary session' : tier.workers?.includes(harness.id) ? `a worker in ${WORKERS_KEY}` : null;
-    if (role) warnings.push(`${harness.id} is ${role} but not in ${HOOKS_KEY}: it runs without DoFlow's hooks, gates or destructive-command guard`);
+    if (role) warnings.push(`${harness.id} is ${role} but not in ${HOOKS_KEY}: it runs without DoFlow's hooks or gates`);
   }
   return warnings;
 }

package/src/lifecycle/index.js

@@ -17,6 +17,7 @@ const { renderMcpIndex } = require('./mcp-index.js');
 const { hasBashCapableShell } = require('./bash-availability.js');
 const { planHookCompanions } = require('./hook-step.js');
 const { tieredRegistry, hookHoldersFromLedger, hooksTieredOff, withoutHookSources, planHookTierRemovals } = require('./hook-tier.js');
+const { forgetManifestTools } = require('../install/manifest.js');
 const { readLock, lockPackages } = require('../state/lockfile.js');
 const { resolveRegistrySource } = require('../adapters/resolve-source.js');
 const { planRetiredHarnesses, planHandovers, handoversFor, applyRetiredHarnesses, retiredReleaseKeys, claimKey } = require('./retired-harnesses.js');
@@ -118,6 +119,34 @@ function markUnownedAbsences(statuses     , ledger     , harness     ) {
   ));
 }
 
+/** An adapter verifies every asset the current source declares for it, comparing disk to source. For
+ * an asset the removal leaves this harness nothing to delete from, that is not its business: the
+ * files belong to another harness's rows (retained removals, or an older install that gave this
+ * harness no rows there: a v1.14.2 Pi install recorded none for the guidance, scripts and runtime
+ * trees) and so carry that install's legacy bytes. Those bytes read as conflicts on files this
+ * removal never touches, and the ones that do match source would be written back as NEW rows for
+ * the harness being removed. So for such an asset the `conflict` status, its `<assetId>: ...`
+ * conflict strings and its copy-tree resources are dropped. An asset the plan deletes from, or one
+ * where a ledger row has no removal, is judged exactly as before. Without a ledger nothing is
+ * proven settled, so the strict reading is kept. */
+function dropSettledAssetVerification(verification     , statuses     , conflicts     , removals     , ledger     ) {
+  const unchanged = { resources: verification.resources, statuses, conflicts };
+  if (!ledger) return unchanged;
+  const rows = (ledger.resources || []).filter((resource     ) => resource.harness === verification.harness);
+  const settled = (assetId     ) => !removals.some((change     ) => change.assetId === assetId && !change.retained)
+    && !rows.some((row     ) => row.assetId === assetId && !removals.some((change     ) => matchesChange(row, change)));
+  const settledAssets = new Set([
+    ...statuses.filter((status     ) => status?.status === 'conflict').map((status     ) => status.assetId),
+    ...verification.resources.filter((resource     ) => resource?.kind === 'copy-tree-file').map((resource     ) => resource.assetId),
+  ].filter((assetId     ) => assetId && settled(assetId)));
+  if (!settledAssets.size) return unchanged;
+  return {
+    resources: verification.resources.filter((resource     ) => !(resource?.kind === 'copy-tree-file' && settledAssets.has(resource.assetId))),
+    statuses: statuses.map((status     ) => (settledAssets.has(status?.assetId) && status.status === 'conflict' ? { ...status, status: 'not-managed' } : status)),
+    conflicts: conflicts.filter((reason     ) => ![...settledAssets].some((assetId) => String(reason).startsWith(`${assetId}: `))),
+  };
+}
+
 function normalizeRemovalVerification(verification     , changes     , ledger     ) {
   const removals = changes.filter((change     ) => change.operation === 'remove' && change.harness === verification.harness);
   if (!removals.length) return verification;
@@ -128,7 +157,9 @@ function normalizeRemovalVerification(verification     , changes     , ledger
   // before.
   const removed = removals.filter((change     ) => !change.retained);
   let statuses = [...verification.statuses];
-  const conflicts = [...(verification.conflicts || [])];
+  let conflicts = [...(verification.conflicts || [])];
+  let resources       ;
+  ({ resources, statuses, conflicts } = dropSettledAssetVerification(verification, statuses, conflicts, removals, ledger));
   for (const change of removed) {
     const outcome = reconcileRemovedChange(verification, statuses, change);
     if (outcome.conflict) { conflicts.push(outcome.conflict); continue; }
@@ -137,7 +168,7 @@ function normalizeRemovalVerification(verification     , changes     , ledger
   }
   // After reconciling the plan's own removals, so this only ever judges what the plan left over.
   statuses = markUnownedAbsences(statuses, ledger, verification.harness);
-  return { ...verification, statuses, conflicts, ok: removalVerificationOk(verification.ok, statuses, conflicts) };
+  return { ...verification, resources, statuses, conflicts, ok: removalVerificationOk(verification.ok, statuses, conflicts) };
 }
 
 /** An adapter may initially report ok:false because a now-removed resource is missing. Once
@@ -913,7 +944,15 @@ function updateLedger({ ledger, scope, scopeRoot, verifications, changes, recove
   // Record the relocation, then sweep the stale copy — but only when its bytes still hash to the
   // fingerprint DoFlow last verified there. A mismatch means someone edited that file after us:
   // their content outranks our tidiness, so the file stays and the unswept tombstone says why.
+  // An MCP entry is one member of a file the user shares, and the adapter has already taken it out
+  // of (or released it in) the old file by entry. A whole-file tombstone for it would carry the
+  // entry's fingerprint, never match the file's bytes and so stay unswept for good. Earlier runs
+  // left such rows behind for Pi's mcp.json (which borrows the guidance.codex-pointer asset id);
+  // they are retired here, and no file is touched.
+  next.tombstones = next.tombstones.filter((entry     ) => entry.sweptAt || entry.harness !== 'pi'
+    || entry.assetId !== 'guidance.codex-pointer' || path.basename(String(entry.fromTarget)) !== 'mcp.json');
   for (const resource of next.resources) {
+    if (resource.kind === 'mcp-server') continue;
     const prior = priorByIdentity.get(`${resource.harness}\u0000${resource.assetId}\u0000${resource.identity ?? ''}`);
     if (!prior || prior.target === resource.target) continue;
     if (!next.tombstones.some((entry     ) => entry.harness === resource.harness
@@ -925,6 +964,16 @@ function updateLedger({ ledger, scope, scopeRoot, verifications, changes, recove
       });
     }
   }
+  // A legacy retirement: an adapter removed an old projection that no row owned (its change carries
+  // `legacyRetirement.toTarget`, where the claim lives now). Journaled as a tombstone already swept.
+  for (const change of changes) {
+    if (!change.legacyRetirement || change.operation !== 'remove' || change.retained) continue;
+    const { harness, assetId, target: fromTarget, fingerprint } = change;
+    const toTarget = change.legacyRetirement.toTarget;
+    if (next.tombstones.some((entry     ) => entry.harness === harness && entry.fromTarget === fromTarget && entry.toTarget === toTarget)) continue;
+    const at = new Date().toISOString();
+    next.tombstones.push({ harness, assetId, fromTarget, toTarget, fingerprint, movedAt: at, sweptAt: at });
+  }
   const claims = new Set(next.resources.map((resource     ) => resource.target));
   for (const entry of next.tombstones) {
     if (entry.sweptAt || !fsImpl.existsSync(entry.fromTarget) || claims.has(entry.fromTarget)) continue;
@@ -1152,9 +1201,37 @@ function settleSuspendedProjection({ homeDir }     )       {
   }
 }
 
+/** Remove the directories a removal emptied, from each removed file's folder upward, tool root
+ * included (`.pi`, `.opencode`, `.agents`); `rmdir` refuses a folder that holds anything, so no
+ * file is touched. The walk stops at the scope root and never takes a shared `.config` folder. */
+function pruneEmptiedDirs(changes       , scopeRoot        , fsImpl      = fs) {
+  const root = path.resolve(scopeRoot);
+  for (const change of changes) {
+    if (change.operation !== 'remove' || change.retained || change.release || typeof change.target !== 'string') continue;
+    let dir = path.dirname(path.resolve(change.target));
+    if (!isUnder(dir, root)) continue;
+    // The removed file's own folders may already be gone; the first one still standing starts the walk.
+    while (dir !== root && isUnder(dir, root) && !fsImpl.existsSync(dir)) dir = path.dirname(dir);
+    while (dir !== root && isUnder(dir, root) && path.basename(dir) !== '.config') {
+      try { fsImpl.rmdirSync(dir); } catch { break; }
+      dir = path.dirname(dir);
+    }
+  }
+}
+
+/** Stop the install manifest listing a harness the removal left with no ownership row. */
+function forgetRemovedTools(targets          , ledger     , scopeRoot        ) {
+  const standing = new Set((ledger?.resources || []).map((resource     ) => resource.harness));
+  const gone = (targets || []).filter((harness) => !standing.has(harness));
+  if (gone.length) forgetManifestTools({ scopeRoot, tools: gone });
+}
+
 function removeLifecycle(options     ) {
   const plan = planLifecycle({ ...options, context: { ...(options.context || {}), operation: 'remove' } });
-  return applyLifecycle({ ...options, plan, mode: 'remove', acceptPrerequisites: options.acceptPrerequisites });
+  const result = applyLifecycle({ ...options, plan, mode: 'remove', acceptPrerequisites: options.acceptPrerequisites });
+  pruneEmptiedDirs(plan.targets.flatMap((target     ) => target.changes), plan.scopeRoot);
+  forgetRemovedTools(options.targets, result.ledger, plan.scopeRoot);
+  return result;
 }
 
 module.exports = { OPERATIONS, MCP_KEEP, recordMcpOwnership, isPackageAsset, registryScope, normalizeTargets, normalizeChange, matchesChange, normalizeRemovalVerification, adapterConflicts, planLifecycle, verifyLifecycle, applyLifecycle, removeLifecycle, updateLedger, mcpIndexPath, applyMcpIndex, targetNeedsHooks, assertBashAvailableForHooks, hookWiringStatus, markRetainedRemovals, retentionSummary, PRUNED_TREES, settleSuspendedProjection };

package/src/lifecycle/retired-harnesses.js

@@ -128,6 +128,20 @@ function markerState(text        )                              { return markedS
 /** Rule 3a's verdict for one retired row (IC-003, IC-007, design D7). */
                                                                                                                          
 
+/** The one rule for "the replacement manages this file": at project scope the replacement writes its
+ * declared instruction file whatever else shares it; at global scope it stays out while another live
+ * harness in `registry` declares the same file (that harness's adapter keeps it). The handover plan
+ * here and antigravity's `instructionTarget` both ask it, so a row is never released to a harness that
+ * then plans nothing. */
+function replacementManagesFile({ registry, harnessId, surface, target, scope, scopeRoot }     )          {
+  if (scope !== 'global') return true;
+  const declaredBy = (harness     ) => {
+    if (harness?.id === harnessId || !harness?.paths?.[surface]) return false;
+    try { return resolveHarnessPaths({ [surface]: harness.paths[surface] }, { scope: 'global', scopeRoot, homeDir: scopeRoot })[surface] === target; } catch { return false; }
+  };
+  return !(registry?.harnesses ?? []).some(declaredBy);
+}
+
 /**
  * Rule 3a, decided before the live harnesses plan, because the replacement needs the verdict to plan
  * its own change: `context.handovers` for each `to`. A retired row qualifies when a `removal.handover`
@@ -155,6 +169,7 @@ function planHandovers({ registry, ledger, scope, scopeRoot, planned = [], fsImp
       let declared                = null;
       try { declared = resolveHarnessPaths({ [entry.surface]: to.paths[entry.surface] }, { scope, scopeRoot, homeDir: scopeRoot })[entry.surface]; } catch { continue; }
       if (declared !== row.target || !fsImpl.existsSync(row.target) || !resolvesInPlace(row.target, scopeRoot, fsImpl)) continue;
+      if (!replacementManagesFile({ registry, harnessId: to.id, surface: entry.surface, target: declared, scope, scopeRoot })) continue;
       const base = { to: to.id, target: row.target, fromKey: ownershipKey(row) };
       if (plannedIds.has(to.id)) {
         decisions.set(base.fromKey, { action: 'handover', ...base, edited: sha256(fsImpl.readFileSync(row.target)) !== row.fingerprint });
@@ -315,4 +330,4 @@ function formatRetiredPlans(plans                      )           {
   ]);
 }
 
-module.exports = { planRetiredHarnesses, planHandovers, handoversFor, applyRetiredHarnesses, retiredReleaseKeys, formatRetiredPlans, claimKey };
+module.exports = { replacementManagesFile, planRetiredHarnesses, planHandovers, handoversFor, applyRetiredHarnesses, retiredReleaseKeys, formatRetiredPlans, claimKey };

package/src/lifecycle/view.js

@@ -19,6 +19,7 @@ const { createCopilotAdapter } = require('../adapters/copilot/index.js');
 const { createKiroAdapter } = require('../adapters/kiro/index.js');
 const { createAntigravityAdapter } = require('../adapters/antigravity/index.js');
 const { planLifecycle } = require('./index.js');
+const { canonicalPath, canonicalLedger } = require('../install/paths.js');
 const { formatRetiredPlans } = require('./retired-harnesses.js');
 const { resolveHookTier, hookTierWarnings } = require('./hook-tier.js');
 const { stateRoot, readLedger, defaultLedger } = require('../state/index.js');
@@ -51,9 +52,9 @@ function codexConfigResources(repoRoot     , fsImpl     ) {
  * reloaded — the same registry also resolves every harness's MCP selection for that command. */
 function registryLifecycleView({ registry, scope, targets, mcpSelections = {}, mcpAdoptable = {}, retainedMcpIds = [], operation, repoRoot, force = false, adopt = false, permissions = false, statusline = false, hookHarnesses, fsImpl = fs }     ) {
   const lifecycleScope = codexScope(scope);
-  const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
+  const scopeRoot = scope.global ? os.homedir() : canonicalPath(scope.projectRoot);
   const neutralStateRoot = stateRoot({ scope: lifecycleScope, projectRoot: scopeRoot, homeDir: scopeRoot });
-  const ledger = readLedger(neutralStateRoot) ?? defaultLedger({ scope: lifecycleScope, scopeRoot });
+  const ledger = canonicalLedger(readLedger(neutralStateRoot), scopeRoot) ?? defaultLedger({ scope: lifecycleScope, scopeRoot });
   const tier = hookHarnesses ? { harnesses: hookHarnesses, workers: null } : resolveHookTier();
   // Mirrors buildAdapterRegistry() in src/cli/shared.js — including the declared-paths wiring —
   // and is kept as a literal construction here because the registry guard pins every declared

package/src/registry/index.js

@@ -582,6 +582,8 @@ const WORKER_BILLING = new Set(['free', 'metered', 'unknown']);
 const WORKER_KEYS = Object.freeze(['profile', 'billing', ...Object.keys(WORKER_CAPABILITIES), 'modelChecks']);
 const WORKER_ALLOWED_KEYS = Object.freeze([...WORKER_KEYS, ...Object.keys(WORKER_OPTIONAL_CAPABILITIES), 'family']);
 const WORKER_ENTRY_FIELDS = new Set(['status', 'evidence', 'verification', 'verifiedOn', 'reason']);
+// Soft hyphen, Mongolian vowel separator, zero-width and directional marks, word joiner and invisible operators, BOM.
+const INVISIBLE_CHARACTER = /[\u00ad\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u206f\ufeff]/;
 const WORKER_RECIPE_FIELDS = new Set(['binary', 'versionArgv', 'argv', 'promptVia', 'parser', 'marker', 'quotaSignals']);
 const WORKER_QUOTA_SIGNALS_FIELDS = new Set(['signals', 'basis', 'evidence']);
 const WORKER_FACTS = new Set(['hooksLoaded', 'identityForwarded', 'guidanceLoaded', 'login']);
@@ -681,10 +683,25 @@ function validateWorker(value     , location        , errors          )       {
       else {
         for (const field of Object.keys(quota)) if (!WORKER_QUOTA_SIGNALS_FIELDS.has(field)) fail(key, `quotaSignals has unknown field '${field}'`);
         if (!Array.isArray(quota.signals) || quota.signals.length < 1 || quota.signals.length > 16) fail(key, 'quotaSignals.signals must contain 1 to 16 signals');
-        else for (const signal of quota.signals) {
-          if (typeof signal !== 'string' || signal !== signal.trim() || signal.length < 3 || signal.length > 64 || /[\u0000-\u001f\u007f]/.test(signal)) {
-            fail(key, 'quotaSignals.signals must be trimmed strings of 3 to 64 characters without control characters');
-            break;
+        else {
+          const folded = new Set        ();
+          for (const signal of quota.signals) {
+            if (typeof signal !== 'string' || signal !== signal.trim() || signal.length < 3 || signal.length > 64 || /[\u0000-\u001f\u007f]/.test(signal)) {
+              fail(key, 'quotaSignals.signals must be trimmed strings of 3 to 64 characters without control characters');
+              break;
+            }
+            // The matcher lowercases both sides, so a signal that differs only by case never adds a match; a
+            // zero-width or format character makes one that reads like another yet matches nothing.
+            if (INVISIBLE_CHARACTER.test(signal)) {
+              fail(key, 'quotaSignals.signals must not contain zero-width or invisible format characters');
+              break;
+            }
+            const lowered = signal.toLowerCase();
+            if (folded.has(lowered)) {
+              fail(key, `quotaSignals.signals has a duplicate signal '${signal}' (compared without letter case)`);
+              break;
+            }
+            folded.add(lowered);
           }
         }
         if (quota.basis !== 'unverified' && quota.basis !== 'transcript') fail(key, "quotaSignals.basis must be 'unverified' or 'transcript'");

package/src/release/docs-blocks.js

@@ -20,7 +20,6 @@ const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { REPO_ROOT } = require('../helper/repo-root.js');
-const { renderEnforcementMatrix, renderBehaviourMatrix } = require('../lifecycle/coverage.js');
 const { loadSettingsRegistry } = require('../runtime/settings/registry.js');
 const { REF_META } = require('../runtime/settings/refs.js');
 
@@ -36,13 +35,6 @@ const DOFLOW_RUN_BIN = 'core/shared/scripts/doflow/bin/doflow-run';
 
 const NUMBER_WORDS = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'];
 
-// Display labels for capability keys; a key without a label is shown capitalized, so a capability
-// added to the registry still gets its row.
-const CAPABILITY_LABELS                         = {
-  instructions: 'Instructions', skills: 'Skills', agents: 'Agents', scripts: 'Scripts', templates: 'Templates',
-  modes: 'Modes', settings: 'Settings', hooks: 'Hooks', mcp: 'MCP', plugin: 'Plugin / extension',
-};
-
                                                                                                                                       
                                                                                                
 
@@ -94,38 +86,8 @@ function table(headers          , rows            )         {
   ].join('\n');
 }
 
-/** A copy of registry data with every string made inert, for renderers that format cells themselves. */
-function inert(value     )      {
-  if (typeof value === 'string') return value === '' ? value : text(value);
-  if (Array.isArray(value)) return value.map(inert);
-  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, inert(entry)]));
-  return value;
-}
-
-function capitalize(text        )         {
-  return text ? text[0].toUpperCase() + text.slice(1) : text;
-}
-
 // ── Renderers (one pure function of the root per block id) ──────────────────────────────────────
 
-function renderCapabilityMatrix(root        )         {
-  const harnesses = readJson(root, 'core/registry/harnesses.json').harnesses;
-  if (!Array.isArray(harnesses) || harnesses.length === 0) throw new Error('harnesses.json has no harnesses');
-  const keys = Object.keys(harnesses[0].capabilities || {});
-  if (keys.length === 0) throw new Error('harnesses.json declares no capabilities');
-  const status = (harness     , key        )         => {
-    const value = harness.capabilities?.[key]?.status;
-    if (typeof value !== 'string' || !value) return '—';
-    const target = harness.nativeTargets?.[key];
-    const label = text(capitalize(value));
-    return target && (value === 'supported' || value === 'different') ? `${label} — ${code(target)}` : label;
-  };
-  return table(
-    ['Capability', ...harnesses.map((harness     ) => oneLine(harness.displayName))],
-    keys.map((key) => [text(CAPABILITY_LABELS[key] || capitalize(key)), ...harnesses.map((harness     ) => status(harness, key))]),
-  );
-}
-
 function renderTaskClasses(root        )         {
   const classes = readJson(root, 'core/registry/workflows.json').classes;
   const templates = new Set(Object.keys(readJson(root, 'core/registry/readiness-templates.json').templates || {}));
@@ -287,13 +249,31 @@ function renderCommandIndex(root        )         {
   ].join('\n');
 }
 
+/** One rule as a short phrase: its extensions, a name filter, and where it files or what it follows. */
+function ruleText(rule     )         {
+  const parts = [rule.extensions.map((ext        ) => `.${ext}`).join(' ')];
+  if (rule.namePattern) parts.push(`name matches ${rule.namePattern}`);
+  if (rule.companionOf) parts.push(`beside a ${rule.companionOf.map((ext        ) => `.${ext}`).join(' ')} file`);
+  if (rule.into) parts.push(`into ${rule.into}/`);
+  return parts.join(', ');
+}
+
+function renderIntakeCategories(root        )         {
+  const categories = readJson(root, 'core/registry/intake.json').categories;
+  if (!Array.isArray(categories) || categories.length === 0) throw new Error('intake.json has no categories');
+  return table(['Folder', 'Also accepted as', 'Takes', 'Purpose'], categories.map((category     ) => [
+    code(category.id),
+    text(category.names.join(', ')),
+    text(category.rules.map(ruleText).join('; ')),
+    text(category.summary),
+  ]));
+}
+
 const BLOCKS                   = Object.freeze([
-  { id: 'capability-matrix', page: 'capability-map.md', sources: ['core/registry/harnesses.json'], render: renderCapabilityMatrix },
-  { id: 'enforcement-matrix', page: 'capability-map.md', sources: ['core/registry/lifecycle.json'], render: (root        ) => renderEnforcementMatrix(inert(readJson(root, 'core/registry/lifecycle.json').coverage)) },
-  { id: 'context-behaviour-matrix', page: 'capability-map.md', sources: ['core/registry/lifecycle.json'], render: (root        ) => renderBehaviourMatrix(inert(readJson(root, 'core/registry/lifecycle.json').coverage)) },
   { id: 'task-classes', page: 'how-doflow-work.md', sources: ['core/registry/workflows.json', 'core/registry/readiness-templates.json'], render: renderTaskClasses },
   { id: 'settings-keys', page: 'settings.md', sources: ['core/registry/settings.json'], render: renderSettingsKeys },
   { id: 'command-index', page: 'reference.md', sources: [DOFLOW_BIN, DOFLOW_RUN_BIN], render: renderCommandIndex },
+  { id: 'intake-categories', page: 'guide.md', sources: ['core/registry/intake.json'], render: renderIntakeCategories },
 ]);
 
 function renderBlock(id        , root        )         {
@@ -380,7 +360,7 @@ function renderLlms(root        )         {
  * (a lone BEGIN or END, an END before its BEGIN, a doubled pair) or nested inside another span is an
  * orphan. Markers are whole lines only, so marker-shaped text inside a table row is never one.
  */
-function markerFindings(page        , text        )            {
+function markerFindings(page        , text        , blocks                   = BLOCKS)            {
   const markers = [...text.matchAll(MARKER_LIKE)].map((match) => ({ kind: match[1], id: match[2], index: match.index ?? 0, exact: match[0] === `<!-- ${match[1]} GENERATED:${match[2]} -->` }));
   const bad = new Set        (markers.filter((marker) => !marker.exact).map((marker) => marker.id));
   const counts = new Map                                        ();
@@ -401,7 +381,7 @@ function markerFindings(page        , text        )            {
   if (open !== null) bad.add(open);
   const findings            = [];
   for (const [id, { begin, end }] of counts) {
-    const registered = MARKER_ID.test(id) && BLOCKS.some((block) => block.id === id && block.page === page);
+    const registered = MARKER_ID.test(id) && blocks.some((block) => block.id === id && block.page === page);
     if (!registered || begin !== 1 || end !== 1 || bad.has(id)) findings.push({ page, id, kind: 'orphan' });
   }
   return findings;
@@ -422,15 +402,15 @@ function readDoc(root        , page        )                {
 }
 
 /** Every finding for the registered blocks and llms.txt; empty when the docs are current. */
-function checkAll(root        )            {
+function checkAll(root        , blocks                   = BLOCKS)            {
   const findings            = [];
-  const pages = [...new Set(BLOCKS.map((block) => block.page))];
+  const pages = [...new Set(blocks.map((block) => block.page))];
   const texts = new Map(pages.map((page) => [page, readDoc(root, page)]));
   for (const page of pages) {
     const text = texts.get(page);
-    if (text !== null && text !== undefined) findings.push(...markerFindings(page, text));
+    if (text !== null && text !== undefined) findings.push(...markerFindings(page, text, blocks));
   }
-  for (const block of BLOCKS) {
+  for (const block of blocks) {
     const text = texts.get(block.page);
     const span = typeof text === 'string' ? spanOf(text, block.id) : null;
     if (!span) {
@@ -456,11 +436,11 @@ function checkAll(root        )            {
 }
 
 /** Rewrites every well-formed span and llms.txt, then returns what `checkAll` still finds. */
-function writeAll(root        )            {
-  for (const block of BLOCKS) {
+function writeAll(root        , blocks                   = BLOCKS)            {
+  for (const block of blocks) {
     const file = path.join(root, 'docs', block.page);
     const text = readDoc(root, block.page);
-    if (text === null || markerFindings(block.page, text).some((f) => f.id === block.id)) continue;
+    if (text === null || markerFindings(block.page, text, blocks).some((f) => f.id === block.id)) continue;
     const span = spanOf(text, block.id);
     if (!span) continue;
     let rendered        ;
@@ -472,7 +452,7 @@ function writeAll(root        )            {
     const llms = renderLlms(root);
     if (readDoc(root, 'llms.txt') !== llms) fs.writeFileSync(path.join(root, 'docs', 'llms.txt'), llms);
   } catch { /* reported by checkAll as source-unreadable */ }
-  return checkAll(root);
+  return checkAll(root, blocks);
 }
 
 /** The CLI: 0 current (or written clean), 1 findings, 2 usage. */
@@ -483,10 +463,14 @@ function main(argv          , root         = REPO_ROOT)         {
   }
   const findings = argv[0] === '--write' ? writeAll(root) : checkAll(root);
   for (const finding of findings) process.stderr.write(`docs-blocks: ${finding.page}: ${finding.id}: ${finding.kind}${finding.detail ? ` (${oneLine(finding.detail)})` : ''}\n`);
-  if (findings.length && argv[0] === '--check') process.stderr.write('docs-blocks: run node src/release/docs-blocks.js --write, then review the diff\n');
+  if (findings.length && argv[0] === '--check') {
+    process.stderr.write('docs-blocks: run node src/release/docs-blocks.js --write, then review the diff\n');
+    // --write rewrites llms.txt from the pages; when the rewritten text is itself over the cap, only shorter descriptions fix it.
+    if (findings.some((f) => f.kind === 'over-cap')) process.stderr.write(`docs-blocks: llms.txt over ${LLMS_CAP} bytes: if --write leaves it over, shorten the page descriptions it is built from\n`);
+  }
   return findings.length ? 1 : 0;
 }
 
-module.exports = { BLOCKS, LLMS_CAP, MARKER_ID, markerFindings, text, code, inert, renderBlock, renderLlms, readNav, captureHelp, pageDescription, checkAll, writeAll, main };
+module.exports = { BLOCKS, LLMS_CAP, MARKER_ID, markerFindings, text, code, renderBlock, renderLlms, readNav, captureHelp, pageDescription, checkAll, writeAll, main };
 
 if (require.main === module) process.exitCode = main(process.argv.slice(2));

package/src/runtime/advice/doctor.js

@@ -116,12 +116,12 @@ async function buildAdviceDoctor({ repoRoot = REPO_ROOT, projectRoot = process.c
         decisionModels: [], lastCall: latestCall(window.records),
       };
     }
-    return { decisionModel, advice, _inspection: inspection, _offReason: setting.state === 'off' ? offReason(setting) : null };
+    return { decisionModel, advice, _inspection: inspection, _offReason: setting.state === 'off' ? (loaded.ok ? offReason(setting) : `unreadable advice registry: ${loaded.detail}`) : null };
   } catch (error     ) {
     return { decisionModel: { setting: { state: 'off', reason: 'config-invalid', decidedBy: { user: null, project: null }, modelFrom: null, notes: [error.message] },
       endpoint: { url: null, state: 'not-checked', version: null, minVersion: null, versionOk: false, message: null },
       model: { name: null, installed: false, decisionCapable: false }, decisionModels: [], lastCall: null },
-      advice: { windowDays: WINDOW_DAYS, store: 'advice-picks-user', kinds: [], unreadableLines: 0 }, _inspection: null, _offReason: 'unreadable setting in decision-model.json' };
+      advice: { windowDays: WINDOW_DAYS, store: 'advice-picks-user', kinds: [], unreadableLines: 0 }, _inspection: null, _offReason: `advice doctor could not complete: ${error.message}` };
   }
 }
 

package/src/runtime/brief-tools.js

@@ -328,7 +328,7 @@ function adviceRecord(result     ) {
 /**
  * The tier renderer remains synchronous/pure; optional local advice is requested afterward.
  */
-async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLevel, tasks, json = false, repoRoot = REPO_ROOT, projectRoot = process.cwd(), env = process.env, buildAdapters = null, probe = probeProviders, adviceClient = null }      = {}) {
+async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLevel, tasks, json = false, repoRoot = REPO_ROOT, projectRoot = process.cwd(), env = process.env, buildAdapters = null, probe = probeProviders, adviceClient = null, now = () => new Date() }      = {}) {
   if (!owner) return usageError('brief-tools', '--owner is required (the agent type the brief is for)', json);
   const level = headingLevel === undefined ? 2 : Number(headingLevel);
   if (level !== 2 && level !== 3) return usageError('brief-tools', `--heading-level must be 2 or 3, got '${headingLevel}'`, json);
@@ -349,6 +349,7 @@ async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLeve
     let markdown = rendered.markdown;
     const record      = rendered.record;
     record.missing.push(...notes);
+    record.createdAt = now().toISOString();
 
     const taskIds = Array.isArray(tasks) ? tasks : typeof tasks === 'string' ? tasks.split(',').filter(Boolean) : [];
     if (taskIds.length) {

package/src/runtime/capability-router.js

@@ -298,6 +298,15 @@ class CapabilityRouter {
     };
   }
 
+  /** The registry's `capabilities.mcp.toolName` template for a harness id, or null when it has none. */
+  harnessToolTemplate(harnessId        )                {
+    return this.harnessList().find((item     ) => item.id === harnessId)?.capabilities?.mcp?.toolName || null;
+  }
+
+  harnessList()        {
+    return parseYamlFile(path.join(this.registryDir, 'harnesses.json'), this.fsImpl).harnesses || [];
+  }
+
   /**
    * Formats concrete execution instructions for a provider based on intent parameters.
    *
@@ -320,7 +329,17 @@ class CapabilityRouter {
     // back to the registry entry with that id.
     const mcp = provider.mcp
       || Object.values(this.capabilities).flatMap((cap     ) => cap.providers || []).find((p     ) => p.id === provider.id && p.mcp)?.mcp;
-    const mcpTool = mcp ? { mcpTool: `mcp__${mcp.server}__${mcp.tool}` } : {};
+    // Default (no `params.harness`): the Claude tool-name form, unchanged. With a target harness:
+    // that harness's registry `capabilities.mcp.toolName` template, or — when it has no verified
+    // template — the neutral `{server, tool}` identifiers and no tool name.
+    let mcpTool      = {};
+    if (mcp && !params.harness) mcpTool = { mcpTool: `mcp__${mcp.server}__${mcp.tool}` };
+    else if (mcp) {
+      const template = this.harnessToolTemplate(params.harness);
+      mcpTool = template
+        ? { mcpTool: template.replace('{server}', () => mcp.server).replace('{tool}', () => mcp.tool) }
+        : { mcp: { server: mcp.server, tool: mcp.tool } };
+    }
     const withDisplay = (result     ) => ({ ...mcpTool, ...result, ...(result.argv ? { cliCommand: result.argv.map(shellQuote).join(' ') } : {}) });
 
     if (provider.id === 'semble.search') {
@@ -580,15 +599,19 @@ class CapabilityRouter {
  * @param {string} [options.projectRoot]
  * @returns {number} exit code
  */
-function handleRouteCommand({ intent, query, check = false, json = false, projectRoot }      = {})         {
+function handleRouteCommand({ intent, query, check = false, json = false, projectRoot, harness }      = {})         {
   const router = new CapabilityRouter({ repoRoot: REPO_ROOT, projectRoot });
   if (typeof intent !== 'string' || intent.trim() === '') {
     return usageError('route', `--intent is required. Declared intents: ${Object.keys(router.routes).join(', ')}`, json);
   }
 
+  if (harness !== undefined && !router.harnessList().some((item     ) => item.id === harness)) {
+    return usageError('route', `unknown --harness '${harness}'. Known harnesses: ${router.harnessList().map((item     ) => item.id).join(', ')}`, json);
+  }
+
   let resolution     ;
   try {
-    resolution = router.resolveIntent(intent, { query, path: projectRoot || '.' }, { deepCheck: check });
+    resolution = router.resolveIntent(intent, { query, path: projectRoot || '.', ...(harness ? { harness } : {}) }, { deepCheck: check });
   } catch (error     ) {
     return usageError('route', `${error.message}. Declared intents: ${Object.keys(router.routes).join(', ')}`, json, error);
   }