arkgate 4.8.13 → 4.8.15

package/bin/lib/agent-skills-package.mjs

@@ -19,7 +19,74 @@ export const FLAT_SKILL_TEMPLATES_RELATIVE_ROOT = 'templates/skills';
 /** Required entry filename inside each skill directory (Agent Skills standard). */
 export const AGENT_SKILL_ENTRY_FILENAME = 'SKILL.md';
 /**
- * Closed skill-name freeze (ACS / ADR skill freeze). Exactly these 13 names ship.
+ * North-star filter for first-class doors. Not a score. Not enforcement.
+ * Skills speak these so an agent picks the right sibling.
+ */
+export const ARK_SKILL_NORTH_STAR = Object.freeze(['Contener', 'Guiar', 'Ordenar']);
+/**
+ * First-class doors. Each must have crisp when / not when / handoff.
+ * Sorted alphabetically.
+ */
+export const ARK_FIRST_CLASS_SKILL_NAMES = Object.freeze([
+    'ark-adopt',
+    'ark-autopilot',
+    'ark-coverage',
+    'ark-explain',
+    'ark-explore',
+    'ark-order',
+    'ark-place',
+    'ark-runtime',
+    'ark-upgrade',
+]);
+/**
+ * One-release redirect stubs. Muscle memory / old docs still resolve.
+ * Values are first-class doors. Capability surface must stay zero-loss.
+ */
+export const ARK_SKILL_STUB_REDIRECTS = Object.freeze({
+    'ark-architect': 'ark-adopt',
+    'ark-contract': 'ark-adopt',
+    'ark-fix': 'ark-autopilot',
+    'ark-loop': 'ark-autopilot',
+    'ark-think': 'ark-explore',
+});
+/**
+ * Product surface → first-class doors that exercise it.
+ * Standing check: every surface has at least one first-class door whose
+ * body mentions that surface. Table keys must match
+ * {@link ARK_SKILL_REQUIRED_SURFACES}.
+ */
+export const ARK_SKILL_CAPACITY = Object.freeze({
+    Layers: ['ark-adopt', 'ark-place', 'ark-explore', 'ark-autopilot', 'ark-coverage', 'ark-explain'],
+    ArkRules: ['ark-adopt', 'ark-explore', 'ark-autopilot'],
+    ArkRun: ['ark-adopt', 'ark-runtime', 'ark-place', 'ark-autopilot'],
+    ArkOrder: ['ark-adopt', 'ark-order', 'ark-place', 'ark-autopilot'],
+    Contener: ['ark-adopt', 'ark-place', 'ark-upgrade'],
+    Guiar: ['ark-explore', 'ark-autopilot', 'ark-explain', 'ark-coverage', 'ark-runtime'],
+    Ordenar: ['ark-order'],
+});
+/**
+ * Closed product + north-star surfaces the skill *set* must exercise.
+ * Independent of {@link ARK_SKILL_CAPACITY} so deleting a table key fails closed.
+ */
+export const ARK_SKILL_REQUIRED_SURFACES = Object.freeze([
+    'Layers',
+    'ArkRules',
+    'ArkRun',
+    'ArkOrder',
+    'Contener',
+    'Guiar',
+    'Ordenar',
+]);
+/** Named first-class door that must stay on these surfaces (no leftover substitute). */
+export const ARK_SKILL_CAPACITY_DEDICATED_DOORS = Object.freeze({
+    ArkRun: 'ark-runtime',
+    ArkOrder: 'ark-order',
+    Ordenar: 'ark-order',
+});
+const NORTH_STAR_PHRASE = 'Contener · Guiar · Ordenar';
+const FORBIDDEN_ORDER_FREEZE = 'Do not invent `/ark-order`';
+/**
+ * Closed shipped catalog (first-class + one-release stubs).
  * Sorted alphabetically for deterministic inventory diffs.
  */
 export const ARK_SKILL_NAMES = Object.freeze([
@@ -32,12 +99,13 @@ export const ARK_SKILL_NAMES = Object.freeze([
     'ark-explore',
     'ark-fix',
     'ark-loop',
+    'ark-order',
     'ark-place',
     'ark-runtime',
     'ark-think',
     'ark-upgrade',
 ]);
-/** Count of frozen skill names (must stay 13 until a ROADMAP item lifts the freeze). */
+/** Count of shipped skill names (first-class + stubs). */
 export const ARK_SKILL_NAME_COUNT = ARK_SKILL_NAMES.length;
 const AGENT_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
@@ -51,10 +119,20 @@ export function isValidAgentSkillName(name) {
         return false;
     return AGENT_SKILL_NAME_PATTERN.test(name);
 }
-/** True when `name` is one of the frozen 13 Ark skill names. */
+/** True when `name` is in the closed shipped catalog. */
 export function isArkSkillName(name) {
     return ARK_SKILL_NAMES.includes(name);
 }
+/** True when `name` is a first-class door (not a redirect stub). */
+export function isFirstClassArkSkillName(name) {
+    return ARK_FIRST_CLASS_SKILL_NAMES.includes(name);
+}
+/** First-class door a leftover name redirects to, or null. */
+export function arkSkillStubRedirect(name) {
+    if (!(name in ARK_SKILL_STUB_REDIRECTS))
+        return null;
+    return ARK_SKILL_STUB_REDIRECTS[name];
+}
 /**
  * Parse a skill markdown document with optional YAML frontmatter.
  * Supports the simple `key: value` / `key: "quoted"` form used by Ark templates
@@ -135,7 +213,7 @@ export function validateAgentSkillDocument(input) {
     else if (requireArk && !isArkSkillName(name)) {
         issues.push({
             code: 'UNKNOWN_SKILL_NAME',
-            message: `Skill name "${name}" is not in the frozen Ark 13-skill catalog (no new skill names).`,
+            message: `Skill name "${name}" is not in the closed Ark skill catalog (ARK_SKILL_NAMES).`,
             skillName: name,
         });
     }
@@ -163,7 +241,7 @@ export function validateAgentSkillDocument(input) {
     return issues;
 }
 /**
- * Validate a full Agent Skills package inventory against the frozen 13-name catalog.
+ * Validate a full Agent Skills package inventory against the closed catalog.
  * Detects missing, extra, duplicate, invalid, and (when supplied) flat-template drift.
  */
 export function validateAgentSkillsPackage(entries) {
@@ -201,7 +279,7 @@ export function validateAgentSkillsPackage(entries) {
         if (!seen.has(expected)) {
             issues.push({
                 code: 'MISSING_SKILL',
-                message: `Missing frozen skill "${expected}" from Agent Skills package.`,
+                message: `Missing catalog skill "${expected}" from Agent Skills package.`,
                 skillName: expected,
             });
         }
@@ -212,14 +290,14 @@ export function validateAgentSkillsPackage(entries) {
             if (!issues.some((i) => i.code === 'UNKNOWN_SKILL_NAME' && i.skillName === name)) {
                 issues.push({
                     code: 'EXTRA_SKILL',
-                    message: `Extra skill "${name}" is not in the frozen Ark 13-skill catalog.`,
+                    message: `Extra skill "${name}" is not in the closed Ark skill catalog.`,
                     skillName: name,
                 });
             }
             else {
                 issues.push({
                     code: 'EXTRA_SKILL',
-                    message: `Extra skill "${name}" is not in the frozen Ark 13-skill catalog.`,
+                    message: `Extra skill "${name}" is not in the closed Ark skill catalog.`,
                     skillName: name,
                 });
             }
@@ -234,6 +312,161 @@ export function validateAgentSkillsPackage(entries) {
         presentCount: names.length,
     };
 }
+function pushCapacityIssue(issues, issue) {
+    issues.push(issue);
+}
+function skillMentionsSurface(body, surface) {
+    return body.includes(surface);
+}
+/**
+ * Observe skill bodies (and optional hubs) against the closed product surfaces.
+ * Inventory/layout stay on {@link validateAgentSkillsPackage}. This is the
+ * fail-closed tooth so a plane cannot silently drop out of the skill set.
+ */
+export function validateSkillProductCapacity(input) {
+    const issues = [];
+    const skills = input.skills ?? {};
+    const tableKeys = Object.keys(ARK_SKILL_CAPACITY);
+    for (const surface of ARK_SKILL_REQUIRED_SURFACES) {
+        if (!tableKeys.includes(surface)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_SURFACE_MISSING',
+                surface,
+                message: `The capacity table dropped ${surface}. Skills must keep covering ` +
+                    `Layers, ArkRules, ArkRun, ArkOrder plus Contener · Guiar · Ordenar. ` +
+                    `Put ${surface} back on ARK_SKILL_CAPACITY.`,
+            });
+        }
+    }
+    for (const key of tableKeys) {
+        if (!ARK_SKILL_REQUIRED_SURFACES.includes(key)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_SURFACE_UNMAPPED',
+                surface: key,
+                message: `The capacity table lists ${key}, which is not a product surface. ` +
+                    `Keep the table to Layers, ArkRules, ArkRun, ArkOrder and Contener · Guiar · Ordenar.`,
+            });
+        }
+    }
+    for (const surface of ARK_SKILL_REQUIRED_SURFACES) {
+        const doors = ARK_SKILL_CAPACITY[surface];
+        if (!doors || doors.length === 0)
+            continue;
+        for (const door of doors) {
+            if (!isFirstClassArkSkillName(door)) {
+                pushCapacityIssue(issues, {
+                    code: 'CAPACITY_DOOR_NOT_FIRST_CLASS',
+                    surface,
+                    skillName: door,
+                    message: `/${door} is listed for ${surface} but is not a first-class door. ` +
+                        `Leftover names are shortcuts. Point ${surface} at a first-class skill.`,
+                });
+            }
+        }
+        const covering = doors.filter((door) => {
+            const body = skills[door];
+            return typeof body === 'string' && skillMentionsSurface(body, surface);
+        });
+        if (covering.length === 0) {
+            const hint = surface === 'ArkOrder' || surface === 'Ordenar'
+                ? ' — usually /ark-order'
+                : surface === 'ArkRun'
+                    ? ' — usually /ark-runtime'
+                    : '';
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_BODY_GAP',
+                surface,
+                message: `Skills no longer cover ${surface}. The product has four parts ` +
+                    `(Layers, ArkRules, ArkRun, ArkOrder) plus Contener · Guiar · Ordenar. ` +
+                    `Put ${surface} back in a first-class skill${hint} so agents still know when to use it.`,
+            });
+        }
+    }
+    for (const [surface, door] of Object.entries(ARK_SKILL_CAPACITY_DEDICATED_DOORS)) {
+        const doors = ARK_SKILL_CAPACITY[surface];
+        if (!doors?.includes(door) || !isFirstClassArkSkillName(door)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_DEDICATED_DOOR',
+                surface,
+                skillName: door,
+                message: `/${door} is the first-class door for ${surface}. Keep it on that surface. ` +
+                    `Leftover names like /ark-think are shortcuts, not a replacement.`,
+            });
+            continue;
+        }
+        const body = skills[door];
+        if (typeof body !== 'string' || !skillMentionsSurface(body, surface)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_DEDICATED_DOOR',
+                surface,
+                skillName: door,
+                message: `/${door} no longer talks about ${surface}. That door is how agents reach ` +
+                    `this part of the product. Put ${surface} back in the skill body.`,
+            });
+        }
+    }
+    for (const name of ARK_FIRST_CLASS_SKILL_NAMES) {
+        const body = skills[name];
+        if (typeof body !== 'string') {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_ROUTING_GAP',
+                skillName: name,
+                message: `/${name} is a first-class door but has no skill body in this check. ` +
+                    `Ship the template so agents know when to use it.`,
+            });
+            continue;
+        }
+        const hasNorthStar = body.includes(NORTH_STAR_PHRASE);
+        const hasWhen = /When \/ not when|\*\*When:\*\*/.test(body);
+        const hasNotWhen = /Not when|Do \*\*not\*\* use|Prefer instead/.test(body);
+        const hasHandoff = /Handoff|hand off|`\/ark-/i.test(body);
+        if (!hasNorthStar || !hasWhen || !hasNotWhen || !hasHandoff) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_ROUTING_GAP',
+                skillName: name,
+                message: `/${name} is missing when / not when / handoff or Contener · Guiar · Ordenar. ` +
+                    `First-class skills must say when to use them and which sibling to call next.`,
+            });
+        }
+        if (body.includes(FORBIDDEN_ORDER_FREEZE)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_ROUTING_GAP',
+                skillName: name,
+                message: `/${name} still says not to invent /ark-order. That freeze is outdated — ` +
+                    `/ark-order is a first-class door.`,
+            });
+        }
+    }
+    const hubs = input.hubs ?? {};
+    for (const [hub, text] of Object.entries(hubs)) {
+        const body = String(text ?? '');
+        if (!body.includes('/ark-order')) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_HUB_GAP',
+                hub,
+                message: `${hub} no longer names /ark-order. Host instructions must stay at 100% of ` +
+                    `the product. Add /ark-order back, or you left the order plane behind.`,
+            });
+        }
+        if (!body.includes(NORTH_STAR_PHRASE)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_HUB_GAP',
+                hub,
+                message: `${hub} no longer says Contener · Guiar · Ordenar. Keep that filter in the ` +
+                    `living docs so agents pick the right sibling.`,
+            });
+        }
+        if (body.includes(FORBIDDEN_ORDER_FREEZE)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_HUB_GAP',
+                hub,
+                message: `${hub} still says not to invent /ark-order. That freeze is outdated — ` +
+                    `/ark-order is a first-class door.`,
+            });
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
 /**
  * Visible package stamp at the start of Agent Skills `description`.
  * Hosts show `description` in the picker; `arkVersion:` in YAML is invisible there.

package/bin/lib/analysis-completeness.mjs

@@ -60,8 +60,15 @@ export const EMPTY_ANALYSIS_RULE_ID = 'ANALYSIS_COVERS_NO_FILES';
  * `countUngovernedSourceFiles` in scan-files.mjs. Feeding it a count that honours
  * `config.exclude` reopens the false green through `exclude: ["**"]`.
  *
+ * `classifiedFileCount` is optional. When omitted, included files are treated as
+ * classified (the historical meaning of `governedFileCount`). When provided and
+ * zero while include still matched files, this is the same vacuous green: import
+ * rules cannot run on unclassified source. Omit the count when `layers` is empty
+ * so `CONFIG_NO_LAYERS` stays the next step. Partial unclassified stays a warning.
+ *
  * @param {{
  *   governedFileCount?: number,
+ *   classifiedFileCount?: number,
  *   ungovernedSourceCount?: number,
  *   ungovernedSourceCap?: number,
  *   root?: string,
@@ -72,8 +79,29 @@ export const EMPTY_ANALYSIS_RULE_ID = 'ANALYSIS_COVERS_NO_FILES';
  * @returns {{ ruleId: string, message: string, nextAction: string } | null}
  */
 export function emptyAnalysisRefusal(input = {}) {
-  const count = Number(input.governedFileCount);
-  if (!Number.isFinite(count) || count !== 0) return null;
+  const included = Number(input.governedFileCount);
+  if (!Number.isFinite(included)) return null;
+
+  const classifiedRaw = input.classifiedFileCount;
+  const classifiedProvided =
+    classifiedRaw !== undefined && classifiedRaw !== null && Number.isFinite(Number(classifiedRaw));
+  const classified = classifiedProvided ? Number(classifiedRaw) : included;
+
+  if (included > 0 && classified === 0) {
+    const root = String(input.root ?? '');
+    const configPath = String(input.configPath ?? '');
+    const message =
+      `Analysis covered 0 files: ${included} included file(s) exist under ${root} but none ` +
+      `matched a layer pattern in ${configPath}. Every rule is vacuously satisfied on an empty ` +
+      'set, so a pass here would certify nothing.';
+    const nextAction =
+      `Extend layer patterns or narrow include in ${configPath} so every included file has a ` +
+      'layer. `npx arkgate-check --root . --coverage` lists unclassified files, and `/ark-place` ' +
+      'picks a folder. `--plan` and `--doctor` report this without refusing.';
+    return { ruleId: EMPTY_ANALYSIS_RULE_ID, message, nextAction };
+  }
+
+  if (included !== 0) return null;
 
   const ungoverned = Math.max(0, Number(input.ungovernedSourceCount) || 0);
   const cap = Math.max(0, Number(input.ungovernedSourceCap) || 0);
@@ -112,3 +140,11 @@ export function emptyAnalysisRefusal(input = {}) {
 
   return { ruleId: EMPTY_ANALYSIS_RULE_ID, message, nextAction };
 }
+
+/** Path-only classified count. `undefined` when no layers — caller keeps the include-only meaning. */
+export function classifiedCountFromFiles(files, layers, layerForFile, root) {
+  if (!Array.isArray(layers) || layers.length === 0 || typeof layerForFile !== 'function') {
+    return undefined;
+  }
+  return files.filter((abs) => layerForFile(root, abs, layers)).length;
+}