arkgate 4.6.7 → 4.7.1

package/bin/lib/resolved-candidate-facts.mjs

@@ -8,7 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { isScanExcludedRelative } from '../ark-shared.mjs';
+import { globToRegExp, isScanExcludedRelative } from '../ark-shared.mjs';
 import {
   AMBIENT_CAPABILITY_ENTRIES,
   collectCapabilityUses,
@@ -35,6 +35,11 @@ import {
 } from './ast-scan.mjs';
 import { provePortProofInject } from './port-proof.mjs';
 import { extractClassShapesFromSource } from './arkrules-sensors.mjs';
+import {
+  extractArkRunDeclarationsFromSource,
+  extractArkRunKernelCallsFromSource,
+  extractArkRunManagedNewsFromSource,
+} from './ark-run-facts.mjs';
 import {
   collectGovernedFiles,
   isGovernableSourceFile,
@@ -998,6 +1003,12 @@ export function resolveCandidateFacts({
   const safetyUses = [];
   /** ADR 0013 class-shape facts for ArkRules structure sensors. */
   const classShapes = [];
+  /** ADR 0022 / RN03 — syntax evidence only; sensors emit in RN04. */
+  const arkRunKernelCalls = [];
+  const arkRunManagedNews = [];
+  const arkRunCompositionRootHits = [];
+  const arkRunDeclarations = [];
+  const compositionRootPatterns = [...(config.arkRun?.compositionRoots ?? [])];
 
   for (const candidate of candidateFiles) {
     const sourceFile = ts.createSourceFile(
@@ -1087,6 +1098,56 @@ export function resolveCandidateFacts({
       } catch {
         // Never fail the resolver for shape extraction; sensors stay silent on this file.
       }
+      try {
+        arkRunKernelCalls.push(
+          ...extractArkRunKernelCallsFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkRun call extraction.
+      }
+      try {
+        arkRunDeclarations.push(
+          ...extractArkRunDeclarationsFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkRun declaration extraction.
+      }
+    }
+  }
+
+  const admittedTypeNames = new Set(classShapes.map((shape) => shape.className));
+  for (const candidate of candidateFiles) {
+    if (!/\.(tsx?|mts|cts)$/i.test(candidate.path)) continue;
+    try {
+      arkRunManagedNews.push(
+        ...extractArkRunManagedNewsFromSource(
+          candidate.path,
+          candidate.content,
+          admittedTypeNames
+        )
+      );
+    } catch {
+      // Never fail the resolver for managed-new extraction.
+    }
+  }
+
+  if (compositionRootPatterns.length > 0) {
+    const factoryFiles = new Set(
+      arkRunKernelCalls.filter((call) => call.kind === 'factory').map((call) => call.file)
+    );
+    for (const candidate of candidateFiles) {
+      for (const pattern of compositionRootPatterns) {
+        try {
+          if (!globToRegExp(pattern).test(candidate.path)) continue;
+        } catch {
+          continue;
+        }
+        arkRunCompositionRootHits.push({
+          file: candidate.path,
+          matchedRoot: pattern,
+          hasKernelFactory: factoryFiles.has(candidate.path),
+        });
+      }
     }
   }
 
@@ -1152,7 +1213,7 @@ export function resolveCandidateFacts({
 
   const projectPackageName = readPackageName(canonicalRoot, observeInput);
   return createTrustedResolvedCandidateFacts({
-    schemaVersion: '1.1',
+    schemaVersion: '1.2',
     completeness: completenessReasons.length === 0 ? 'complete' : 'partial',
     completenessReasons,
     resolverIdentity: RESOLVED_FACTS_RESOLVER_IDENTITY,
@@ -1169,5 +1230,9 @@ export function resolveCandidateFacts({
     intentReferences,
     safetyUses,
     classShapes,
+    arkRunKernelCalls,
+    arkRunManagedNews,
+    arkRunCompositionRootHits,
+    arkRunDeclarations,
   });
 }

package/bin/lib/rules-under-contract.mjs

@@ -7,6 +7,11 @@
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import {
+  EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
+  composeMergePlanesHonesty,
+  demoteExtraPlaneTeethUnderClassificationFloor,
+} from './extra-merge-teeth.mjs';
 
 /**
  * Cap long catalogs in doctor JSON (and HTML, which consumes the same summary).
@@ -16,12 +21,11 @@ const COVERED_SAMPLE_MAX = 24;
 const STRUCTURE_CATALOG_MAX = 40;
 const UNCOVERED_CATALOG_MAX = 30;
 
-/** Minimum governed % before enforced ArkRules may arm extra merge teeth (P1M / FG-EXTRATEETH). */
-export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
+export { EXTRA_MERGE_TEETH_GOVERNED_FLOOR };
 
 /**
  * P1M / extraMergeTeeth: under the classification floor, demote enforced ArkRules
- * structure/invariant findings so merge matches doctor stamp (layer graph only).
+ * and ArkRun findings so merge matches doctor stamp (layer graph only).
  * Unknown classification (null/null) → do not demote (contract-only callers).
  *
  * @param {object[]} violations
@@ -29,28 +33,7 @@ export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
  * @returns {object[]}
  */
 export function demoteArkRuleTeethUnderClassificationFloor(violations, classification = {}) {
-  if (!Array.isArray(violations)) return violations;
-  const governed =
-    typeof classification.governedPercent === 'number' ? classification.governedPercent : null;
-  const populated =
-    typeof classification.populatedLayerCount === 'number'
-      ? classification.populatedLayerCount
-      : null;
-  if (governed == null && populated == null) return violations;
-  const allowsTeeth =
-    (governed ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR && (populated ?? 0) >= 1;
-  if (allowsTeeth) return violations;
-  for (const v of violations) {
-    const isArkRule =
-      v?.arkruleId != null ||
-      (typeof v?.ruleId === 'string' &&
-        (v.ruleId.startsWith('ARKRULE') || v.ruleId.startsWith('arkrule')));
-    if (isArkRule && v.failsStrict !== false) {
-      v.failsStrict = false;
-      if (v.severity === 'error') v.severity = 'warning';
-    }
-  }
-  return violations;
+  return demoteExtraPlaneTeethUnderClassificationFloor(violations, classification);
 }
 
 /**
@@ -63,6 +46,18 @@ export function demoteArkRuleTeethUnderClassificationFloor(violations, classific
  *   classifiedFiles?: number | null,
  * }} [classification] layer-plane coverage (when known)
  */
+function arkRunMergeInput(config, residualCount = 0) {
+  const extra = config?.arkRun;
+  if (!extra || typeof extra !== 'object') {
+    return { present: false, mode: null, residualCount: 0 };
+  }
+  return {
+    present: true,
+    mode: extra.mode === 'enforced' || extra.mode === 'advisory' ? extra.mode : null,
+    residualCount: Number(residualCount) || 0,
+  };
+}
+
 export function summarizeRulesUnderContract(root, config, facts, classification) {
   if (!config?.arkRules || Object.keys(config.arkRules).length === 0) {
     return {
@@ -71,6 +66,11 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       invariants: 0,
       coveredInvariants: 0,
       uncoveredInvariants: 0,
+      mergePlanes: composeMergePlanesHonesty({
+        classification,
+        arkRules: { active: false },
+        arkRun: arkRunMergeInput(config),
+      }),
       notAScore: true,
       note: 'No arkRules map — intra-layer ArkRules are opt-in.',
     };
@@ -162,73 +162,21 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const invariantAdvisory = invariants - invariantEnforced;
     const coveredInvariants = coverage.coverage.filter((c) => c.covered).length;
     const uncoveredInvariants = coverage.coverage.filter((c) => !c.covered).length;
-    const hasEnforcedTeeth = structureEnforced > 0 || invariantEnforced > 0;
-    // P1M-EXTRATEETH-EMPTY-GRAPH / FG-EXTRATEETH-EMPTY-CLASSIFICATION:
-    // Do not arm structure/invariant merge teeth when the layer plane is empty or
-    // barely classified (e.g. 0% governed). Classification unknown → allow teeth
-    // (contract-only callers / unit tests without coverage).
-    const governedPercent =
-      classification && typeof classification.governedPercent === 'number'
-        ? classification.governedPercent
-        : null;
-    const populatedLayerCount =
-      classification && typeof classification.populatedLayerCount === 'number'
-        ? classification.populatedLayerCount
-        : classification && typeof classification.classifiedFiles === 'number'
-          ? classification.classifiedFiles > 0
-            ? 1
-            : 0
-          : null;
-    const classificationKnown = governedPercent != null || populatedLayerCount != null;
-    const classificationAllowsTeeth = !classificationKnown
-      ? true
-      : (governedPercent ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR &&
-        (populatedLayerCount ?? 0) >= 1;
-    const extraMergeTeeth = hasEnforcedTeeth && classificationAllowsTeeth;
-    const teethDeferredForClassification =
-      hasEnforcedTeeth && classificationKnown && !classificationAllowsTeeth;
-    // P1-M — which plane can fail merge (layers vs enforced structure vs invariants).
-    const mergePlanes = {
-      layers: {
-        role: 'inter-layer-edges',
-        alwaysOnGate: true,
-        note: 'Import/export layer graph — the default merge plane. Absent arkRules changes nothing here.',
-      },
-      structureSensors: {
-        role: 'intra-layer-heuristics',
-        total: structureRules,
-        enforced: structureEnforced,
-        advisory: structureAdvisory,
-        note: 'Structure sensors are heuristics (prefer false negatives). Only mode:enforced fails merge; noisy sensors stay advisory by default. Advisory-only packs never add merge teeth (FG-ARKRULES-ADVISORY-ONLY).',
-      },
-      invariants: {
-        role: 'catalog-plus-coverage',
-        total: invariants,
-        enforced: invariantEnforced,
-        advisory: invariantAdvisory,
+    const mergePlanes = composeMergePlanesHonesty({
+      classification,
+      arkRules: {
+        active: true,
+        structureEnforced,
+        structureTotal: structureRules,
+        structureAdvisory,
+        invariantEnforced,
+        invariantTotal: invariants,
+        invariantAdvisory,
         covered: coveredInvariants,
         uncovered: uncoveredInvariants,
-        note: 'Invariants are catalog + coverage evidence, not a business runtime. Enforced + proven-uncovered fails merge; absence of enforced rules adds no extra teeth.',
       },
-      dualPlaneStamp:
-        'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime). The two planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth.',
-      extraMergeTeeth,
-      ...(classificationKnown
-        ? {
-            classificationGate: {
-              governedPercent: governedPercent ?? null,
-              populatedLayerCount: populatedLayerCount ?? null,
-              floorPercent: EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
-              allowsTeeth: classificationAllowsTeeth,
-            },
-          }
-        : {}),
-      failMergeWhen: extraMergeTeeth
-        ? 'Layer graph failures plus enforced structure/invariant findings (advisory sensors never fail merge alone).'
-        : teethDeferredForClassification
-          ? `Layer graph only — enforced ArkRules structure/invariant findings are demoted under the teeth floor (need ≥${EXTRA_MERGE_TEETH_GOVERNED_FLOOR}% governed and ≥1 populated layer); they do not merge-block until classification is honest.`
-          : 'Layer graph only — no enforced ArkRules structure/invariant teeth on this tree. Advisory packs do not arm merge teeth.',
-    };
+      arkRun: arkRunMergeInput(config),
+    });
 
     return {
       active: true,

package/bin/lib/skill-catalog-apply.mjs

@@ -0,0 +1,126 @@
+/**
+ * HS post-write skill catalog: adapters, home skip/prune, Claude/Grok home skip.
+ * Kept out of install-migrate so that file stays inside its module budget.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { installRequestedAgentHomes } from './agent-homes.mjs';
+import { codexSkillsDir } from './codex-home.mjs';
+import {
+  canonicalSkillPath,
+  linkSkillHostAdapters,
+  pruneHomeArkSkillDuplicates,
+  skillTemplateNames,
+} from './skill-install.mjs';
+import { installSkillCatalog, skillInstallLine } from './skill-write.mjs';
+
+function skillName(skill) {
+  return Array.isArray(skill) ? skill[0] : skill?.name || skill;
+}
+
+export function projectCatalogReady(root, skillNames) {
+  return skillNames.some((name) => fs.existsSync(path.join(root, canonicalSkillPath(name))));
+}
+
+export function applySkillCatalogFollowup({
+  root,
+  tools,
+  skills,
+  version,
+  args,
+}) {
+  const skillNames = skills.map(skillName);
+  if (!args.compact && skillNames.length > 0) {
+    const adapterResults = linkSkillHostAdapters(root, tools, skillNames, Boolean(args.force));
+    for (const row of adapterResults) {
+      if (row.status === 'linked' || row.status === 'copied') {
+        console.log(
+          `  ${row.status.padEnd(7)} ${row.relativePath}  (adapter → .agents/skills/${row.name})`
+        );
+      }
+    }
+  }
+  if (args.pruneHomeDuplicates) {
+    const pruned = pruneHomeArkSkillDuplicates(
+      root,
+      skillNames.length ? skillNames : skillTemplateNames()
+    );
+    if (!pruned.ok) {
+      console.log('  skip    --prune-home-duplicates (no project .agents/skills catalog yet)');
+    } else if (pruned.removed.length === 0) {
+      console.log('  skip    --prune-home-duplicates (no home ark-* copies)');
+    } else {
+      console.log(`  pruned  ${pruned.removed.length} home ark-* path(s) (project catalog is enough)`);
+    }
+  }
+
+  const homeResults = [];
+  if (args.codexHome) {
+    const dir = codexSkillsDir();
+    console.log('');
+    console.log(
+      `Codex home skills (scope=home-shared; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}; target=${dir}/<name>/SKILL.md):`
+    );
+    console.log(
+      '  Compatibility: monotonic downgrade protection requires every shared-catalog writer ' +
+        'to use ArkGate 4.2.0+; pre-4.2 --codex-home ignores this catalog. Upgrade legacy repos first.'
+    );
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (error) {
+      console.error(`  FAILED to create ${dir} (${error.message})`);
+      homeResults.push({ relativePath: dir, status: 'failed' });
+    }
+    if (homeResults.length === 0) {
+      const hasCatalog = skills.some((skill) =>
+        fs.existsSync(path.join(root, '.agents', 'skills', skillName(skill), 'SKILL.md'))
+      );
+      if (hasCatalog) {
+        console.log(
+          '  Skip home write — project .agents/skills is the catalog. Codex lists user+repo; a home copy duplicates every /ark-*.'
+        );
+        console.log(
+          `  Remove leftover home copies: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --prune-home-duplicates')}`
+        );
+      } else {
+        for (const result of installSkillCatalog({
+          directory: dir,
+          skills,
+          packageVersion: version,
+          force: args.force,
+          scope: 'home',
+        })) {
+          console.log(skillInstallLine(result));
+          homeResults.push(result);
+        }
+      }
+    }
+  }
+
+  const catalogReady = projectCatalogReady(root, skillNames);
+  if ((args.claudeHome || args.grokHome || args.agentHomes) && catalogReady) {
+    if (!args.json) {
+      console.log('');
+      console.log(
+        'Skip Claude/Grok home skill write — project .agents/skills + adapters are the catalog. Home ark-* copies override or duplicate.'
+      );
+      console.log(
+        `  Remove leftover home copies: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --prune-home-duplicates')}`
+      );
+    }
+  } else {
+    installRequestedAgentHomes({
+      root,
+      skills,
+      version,
+      force: args.force,
+      claudeHome: args.claudeHome,
+      grokHome: args.grokHome,
+      agentHomes: args.agentHomes,
+      json: args.json,
+    });
+  }
+
+  return { skillNames, homeResults };
+}