@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/providers/grok-build-inspect.js

@@ -177,6 +177,7 @@ export function runGrokInspect(envOrOptions = process.env) {
             // npm exposes Grok through a .cmd shim on Windows; Node requires a shell
             // for .cmd/.bat launchers. Native .exe installs stay shell-free.
             shell: process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(binary),
+            killSignal: 'SIGKILL',
         });
         if (result.error && result.error.code === 'ENOENT') {
             return { status: 'absent', remediation: ABSENT_REMEDIATION };

package/dist/src/providers/omp-agent.d.mts

@@ -0,0 +1,8 @@
+export interface OmpAgentOptions {
+  diagnostics?: string[];
+  quiet?: boolean;
+  modelsConfig?: Record<string, any>;
+  modelConfig?: Record<string, any>;
+}
+export function transformAgent(src: string, content: string, opts?: OmpAgentOptions): string;
+export function mapModel(model: string | undefined, config?: Record<string, any>): string | undefined;

package/dist/src/providers/omp-diagnostics.d.mts

@@ -0,0 +1 @@
+export function diagnoseOmpRuntime(options?: {cwd?: string; env?: NodeJS.ProcessEnv; binary?: string; runner?: (...args: any[]) => Promise<{stdout: string}>}): Promise<{executable: string; available: boolean; version: string | null; paths: ReturnType<typeof import('./omp-paths.mjs').resolveOmpPaths>; reason: string | null}>;

package/dist/src/providers/omp-paths.d.mts

@@ -0,0 +1,13 @@
+export interface OmpPathOptions {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  cwd?: string;
+  platform?: string;
+  exists?: (path: string) => boolean;
+}
+export function normalizeOmpProfile(value?: string): string | undefined;
+export function resolveOmpPaths(options?: OmpPathOptions): {
+  profile?: string; configRoot: string; agentDir: string; projectDir: string;
+  resourceDirs: { agents: string; skills: string; commands: string; rules: string; behaviors: string };
+  dataDir: string; stateDir: string; cacheDir: string; sessionsDir: string;
+};

package/dist/src/providers/provider-definitions.js

@@ -362,7 +362,15 @@ const BUILT_IN_SEEDS = [
         builtIn: true,
         surfaces: { primary: 'claude-code', compatibility: ['claude'], precedence: ['.claude/', 'CLAUDE.md'], related: [] },
         detection: {
-            env: ['CLAUDE_CODE_VERSION', 'ANTHROPIC_API_KEY'],
+            // CLAUDECODE / CLAUDE_CODE_ENTRYPOINT / CLAUDE_CODE_DESKTOP_APP_VERSION
+            // are the markers current Claude Code (CLI and Desktop Code tab)
+            // actually sets; confirmed empirically in both a CLI session and a
+            // Desktop Code-tab session (docs/planning/claude-desktop-provider/
+            // assessment-and-issue-plan.md §2.1). `CLAUDE_CODE_VERSION` is not set
+            // by current Claude Code, and `ANTHROPIC_API_KEY` is a false-positive
+            // signal — any non-Claude session with that key set would otherwise
+            // identify as `claude` (#2627).
+            env: ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CLAUDE_CODE_DESKTOP_APP_VERSION'],
             process: ['claude-code', 'claude'],
             capabilityId: 'claude-code',
             runtimeEnvPriority: 100,

package/dist/src/providers/provider-definitions.mjs

@@ -26,9 +26,9 @@ const MCP_INJECTION_DEFINITIONS = [
       providerId: 'claude-code',
       includeInSupportedProviders: true,
       configFormat: 'json',
-      serverConfigFormat: 'standard',
+      serverConfigFormat: 'claude-code',
       serversKey: 'mcpServers',
-      configPath: { scope: 'project', path: '.claude/settings.local.json' },
+      configPath: { scope: 'project', path: '.mcp.json' },
       supportsEphemeral: true,
     },
   },
@@ -178,10 +178,17 @@ export function listMcpInjectProviderIds() {
 }
 
 export function resolveMcpConfigPath(provider, projectDir = '.', options = {}) {
+  if (normalizeRuntimeProviderId(provider) === 'codex' && process.env.CODEX_HOME) {
+    return resolve(process.env.CODEX_HOME, 'config.toml');
+  }
   if (normalizeRuntimeProviderId(provider) === 'antigravity' && options.scope === 'user') {
     const home = process.env.HOME || process.env.USERPROFILE || homedir();
     return resolve(home, '.gemini/config/mcp_config.json');
   }
+  if (normalizeRuntimeProviderId(provider) === 'claude-code' && options.scope === 'user') {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    return resolve(home, '.claude.json');
+  }
   if (normalizeRuntimeProviderId(provider) === 'omp' && options.scope === 'user') {
     return resolve(resolveOmpPaths(options).agentDir, 'mcp.json');
   }

package/dist/src/providers/skill-ownership.d.mts

@@ -0,0 +1,9 @@
+export interface SkillReceipt {
+  skillSource?: string;
+  managed?: Record<string, { hash: string; frameworkSlug?: string; source?: string; version?: string }>;
+}
+export function extractFrameworkSlug(source: string): string | null;
+export function sameSkillOwner(receipt: SkillReceipt | null, skillSource: string, frameworkSlug?: string | null): boolean;
+export function canDeploySkill(receipt: SkillReceipt | null, skillSource: string, opts?: { force?: boolean }): boolean;
+export function pruneRecordedSkillFiles(skillDir: string, managed: SkillReceipt['managed'], desired: Set<string>, opts?: { dryRun?: boolean }): void;
+export function releaseSkillOwnership(skillDir: string, owner: { frameworkSlug?: string; skillSource?: string; sourceRoot?: string }, opts?: { dryRun?: boolean }): boolean | null;

package/dist/src/providers/skill-ownership.mjs

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+/** Identify a bundled owner independently of the installation prefix. */
+export function extractFrameworkSlug(source) {
+  if (typeof source !== 'string') return null;
+  return source.replace(/\\/g, '/').match(/agentic\/code\/(?:frameworks|addons)\/([^/]+)\//)?.[1] ?? null;
+}
+
+function sourceSegment(source) {
+  if (!source) return null;
+  const normalized = source.replace(/\\/g, '/');
+  return normalized.match(/(?:agentic\/code|\.aiwg)\/(?:frameworks|addons|extensions)\/.+$/)?.[0]
+    ?? normalized.match(/[^/]+\/skills\/[^/]+$/)?.[0] ?? null;
+}
+
+/** Slugs survive install moves; legacy receipts fall back to source identity. */
+export function sameSkillOwner(receipt, skillSource, frameworkSlug = extractFrameworkSlug(`${skillSource}/SKILL.md`)) {
+  const existingSlug = receipt?.managed?.['SKILL.md']?.frameworkSlug;
+  if (existingSlug && frameworkSlug) return existingSlug === frameworkSlug;
+  if (receipt?.skillSource && path.resolve(receipt.skillSource) === path.resolve(skillSource)) return true;
+  if (existingSlug || frameworkSlug || !receipt?.skillSource) return false;
+  const segment = sourceSegment(skillSource);
+  return Boolean(segment && path.basename(receipt.skillSource) === path.basename(skillSource)
+    && sourceSegment(receipt.skillSource) === segment);
+}
+
+/** Frameworks outrank addons; peers retain ownership unless explicitly forced. */
+export function canDeploySkill(receipt, skillSource, { force = false } = {}) {
+  const owner = receipt?.managed?.['SKILL.md']?.frameworkSlug || receipt?.skillSource;
+  if (!owner || sameSkillOwner(receipt, skillSource)) return true;
+  const incoming = extractFrameworkSlug(`${skillSource}/SKILL.md`) || skillSource;
+  const isFramework = /(?:^|\/)agentic\/code\/frameworks\//.test(skillSource.replace(/\\/g, '/'));
+  const wasAddon = /(?:^|\/)agentic\/code\/addons\//.test((receipt.skillSource || '').replace(/\\/g, '/'));
+  const replace = force || (isFramework && wasAddon);
+  console.warn(`Skill deploy collision: '${path.basename(skillSource)}' is owned by ${owner}; ${incoming} ${replace ? 'taking ownership' : 'skipped'}`);
+  return replace;
+}
+
+/** Remove unchanged recorded files, allowing symlinks above (but never inside) the skill root. */
+export function pruneRecordedSkillFiles(skillDir, managed, desired, opts = {}) {
+  if (opts.dryRun) return;
+  for (const [relative, record] of Object.entries(managed || {})) {
+    if (desired.has(relative)) continue;
+    const target = path.resolve(skillDir, relative);
+    if (!target.startsWith(`${path.resolve(skillDir)}${path.sep}`)) continue;
+    try {
+      const expected = path.resolve(fs.realpathSync(skillDir), relative);
+      let current = target;
+      let symlink = false;
+      while (current !== path.resolve(skillDir)) {
+        if (fs.lstatSync(current).isSymbolicLink()) { symlink = true; break; }
+        current = path.dirname(current);
+      }
+      if (symlink || fs.realpathSync(target) !== expected || !fs.lstatSync(target).isFile()) continue;
+      if (`sha256:${createHash('sha256').update(fs.readFileSync(target)).digest('hex')}` !== record.hash) continue;
+      fs.unlinkSync(target);
+      let parent = path.dirname(target);
+      while (parent !== path.resolve(skillDir)) {
+        try { fs.rmdirSync(parent); } catch { break; }
+        parent = path.dirname(parent);
+      }
+    } catch { /* missing, modified, or unreadable files are left alone */ }
+  }
+}
+
+/** Release only the receipt's owner. Return null for foreign/unrecorded skills. */
+export function releaseSkillOwnership(skillDir, owner, opts = {}) {
+  if (!fs.existsSync(skillDir) || !fs.lstatSync(skillDir).isDirectory()) return null;
+  const manifestPath = path.join(skillDir, '.aiwg-manifest.json');
+  let receipt;
+  try { receipt = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); } catch { return null; }
+  if (!receipt.managed?.['SKILL.md']) return null;
+  const slug = receipt.managed['SKILL.md'].frameworkSlug;
+  // A bundle owns every receipt whose source lies inside its root, wherever
+  // its layout (plugin payloads included) puts the skill directory.
+  const insideRoot = owner.sourceRoot && receipt.skillSource
+    && !path.relative(path.resolve(owner.sourceRoot), path.resolve(receipt.skillSource)).startsWith('..')
+    && !path.isAbsolute(path.relative(path.resolve(owner.sourceRoot), path.resolve(receipt.skillSource)));
+  if (!insideRoot && (slug ? slug !== owner.frameworkSlug
+    : !owner.skillSource || !sameSkillOwner(receipt, owner.skillSource, null))) return null;
+  if (opts.dryRun) return false;
+  pruneRecordedSkillFiles(skillDir, receipt.managed, new Set(), opts);
+  fs.rmSync(manifestPath, { force: true });
+  fs.rmSync(path.join(skillDir, '.aiwg-managed'), { force: true });
+  try { fs.rmdirSync(skillDir); return true; } catch { return false; }
+}

package/dist/src/rules/activation.d.mts

@@ -0,0 +1,21 @@
+export type RuleActivation = 'kernel' | 'summary' | 'bound' | 'paths' | 'on-demand';
+export type RuleBindingKey = 'skills' | 'agents' | 'flows';
+export interface RuleBindings { skills: string[]; agents: string[]; flows: string[] }
+export interface RuleFrontmatter extends Record<string, unknown> {
+  activation: RuleActivation;
+  tagged: boolean;
+  summary?: string;
+  bound_to: RuleBindings;
+  paths?: string[];
+  enforcedBy?: unknown;
+}
+export interface RuleDiagnostic { severity: 'error' | 'warn' | 'info'; code: string; message: string }
+export type RuleValidationResult =
+  | { valid: true; diagnostics: RuleDiagnostic[]; rule: RuleFrontmatter }
+  | { valid: false; diagnostics: RuleDiagnostic[]; rule?: never };
+export const RULE_ACTIVATIONS: readonly RuleActivation[];
+export const RULE_BINDING_TYPES: Readonly<{ skills: 'skill'; agents: 'agent'; flows: 'flow' }>;
+export const ruleFrontmatterSchema: Record<string, unknown>;
+export function inferRuleActivation(enforcement: unknown): 'kernel' | 'on-demand';
+export function validateRuleFrontmatter(data: unknown): RuleValidationResult;
+export function parseRuleFrontmatter(content: string): RuleValidationResult & { data: unknown; body: string };

package/dist/src/rules/activation.mjs

@@ -0,0 +1,62 @@
+/** Shared source frontmatter contract for lint, deployment, and show/MCP (#2938). */
+import { readFileSync } from 'node:fs';
+import Ajv from 'ajv';
+import { parse } from 'yaml';
+
+export const RULE_ACTIVATIONS = Object.freeze(['kernel', 'summary', 'bound', 'paths', 'on-demand']);
+export const RULE_BINDING_TYPES = Object.freeze({ skills: 'skill', agents: 'agent', flows: 'flow' });
+export const ruleFrontmatterSchema = JSON.parse(readFileSync(new URL('./rule-frontmatter.schema.json', import.meta.url), 'utf8'));
+const ajv = new Ajv({ strict: true, allErrors: true });
+const validate = ajv.compile(ruleFrontmatterSchema);
+// Legacy paths/applies_to/scope never become activation inputs during migration.
+const validateLegacy = ajv.compile({ type: 'object', properties: ruleFrontmatterSchema.properties });
+
+export function inferRuleActivation(enforcement) {
+  return typeof enforcement === 'string' && ['medium', 'low'].includes(enforcement.trim().toLowerCase())
+    ? 'on-demand' : 'kernel';
+}
+
+/** Validate a parsed YAML mapping. Invalid explicit activation never falls back. */
+export function validateRuleFrontmatter(data) {
+  const diagnostics = [];
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return { valid: false, diagnostics: [{ severity: 'error', code: 'frontmatter', message: 'Rule frontmatter must be a mapping.' }] };
+  }
+  const tagged = Object.hasOwn(data, 'activation');
+  const checker = tagged ? validate : validateLegacy;
+  if (!checker(data)) {
+    for (const error of checker.errors ?? []) diagnostics.push({
+      severity: 'error', code: 'frontmatter',
+      message: `${error.instancePath || '/'} ${error.message}${error.params.missingProperty ? `: ${error.params.missingProperty}` : ''}`,
+    });
+  }
+  if (!tagged) diagnostics.push({ severity: 'warn', code: 'missing-activation',
+    message: `Missing activation; inferred ${inferRuleActivation(data.enforcement)} delivery from legacy enforcement (migration fallback).` });
+  if (Object.hasOwn(data, 'enforcedBy')) diagnostics.push({ severity: 'info', code: 'reserved-enforcedBy',
+    message: 'enforcedBy is opaque reserved metadata (#2839); it has no effect.' });
+  const valid = !diagnostics.some(item => item.severity === 'error');
+  return {
+    valid, diagnostics,
+    ...(valid ? { rule: {
+      ...data,
+      activation: tagged ? data.activation : inferRuleActivation(data.enforcement),
+      tagged,
+      ...(typeof data.summary === 'string' ? { summary: data.summary.trim() } : {}),
+      bound_to: { skills: [], agents: [], flows: [], ...data.bound_to },
+    } } : {}),
+  };
+}
+
+/** Parse complete Markdown source, preserving authored body and opaque metadata. */
+export function parseRuleFrontmatter(content) {
+  const source = content.replace(/^\uFEFF/, '');
+  if (!/^---\r?\n/.test(source)) return { ...validateRuleFrontmatter({}), data: {}, body: content };
+  const match = source.match(/^---\r?\n([\s\S]*?)^---[ \t]*\r?$(?:\n)?/m);
+  if (!match) return { valid: false, diagnostics: [{ severity: 'error', code: 'frontmatter', message: 'Unterminated rule frontmatter.' }], data: {}, body: content };
+  try {
+    const data = match[1].trim() ? parse(match[1]) : {};
+    return { ...validateRuleFrontmatter(data), data, body: source.slice(match[0].length) };
+  } catch (error) {
+    return { valid: false, diagnostics: [{ severity: 'error', code: 'frontmatter', message: `Invalid rule YAML: ${error.message}` }], data: {}, body: content };
+  }
+}

package/dist/src/rules/inline-budget.d.mts

@@ -0,0 +1,26 @@
+import type { RuleDiagnostic } from './activation.mjs';
+export interface RulePinSelector { rules?: string[]; enforcement?: Array<'critical' | 'high' | 'medium' | 'low'>; capabilities?: string[]; group?: string; all?: true }
+export interface RulesConfig { inline_budget_tokens?: number; always_load?: RulePinSelector[]; pin_groups?: Record<string, string[]> }
+export interface InlineBudgetConfig { rules?: RulesConfig }
+export interface StartupContributor { path: string; bytes?: number; content?: string }
+export interface InlineBudgetReport {
+  provider: string;
+  limit: number;
+  selected_bytes: number;
+  selected_tokens: number;
+  estimate: string;
+  disabled: boolean;
+  exceeded: boolean;
+  contributors: Array<{ path: string; bytes: number; estimated_tokens: number }>;
+}
+export interface InlineBudgetOptions {
+  provider: string;
+  files: readonly StartupContributor[];
+  config?: InlineBudgetConfig;
+  env?: Record<string, string | undefined>;
+  reportOnly?: boolean;
+}
+export const DEFAULT_RULES_INLINE_BUDGET_TOKENS: 64000;
+export function validateRulesConfig(rules: unknown): string[];
+export function resolveRulesInlineBudget(config?: InlineBudgetConfig, env?: Record<string, string | undefined>): number;
+export function guardRulesInlineBudget(options: InlineBudgetOptions): { report: InlineBudgetReport; diagnostics: RuleDiagnostic[]; passed: boolean };

package/dist/src/rules/inline-budget.mjs

@@ -0,0 +1,66 @@
+/** Configurable lint guard only. Call with the complete projected startup set. */
+export const DEFAULT_RULES_INLINE_BUDGET_TOKENS = 64000;
+
+export function validateRulesConfig(rules) {
+  if (rules === undefined) return [];
+  if (rules === null || typeof rules !== 'object' || Array.isArray(rules)) return ['rules: must be an object'];
+  const errors = Object.keys(rules).filter(key => !['inline_budget_tokens', 'always_load', 'pin_groups'].includes(key)).map(key => `rules.${key}: unknown field`);
+  if (rules.inline_budget_tokens !== undefined && (!Number.isSafeInteger(rules.inline_budget_tokens) || rules.inline_budget_tokens < 0)) {
+    errors.push('rules.inline_budget_tokens: must be a non-negative safe integer');
+  }
+  const strings = value => Array.isArray(value) && value.length > 0 && value.every(id => typeof id === 'string' && id.trim() && !['__proto__', 'prototype', 'constructor'].includes(id));
+  if (rules.pin_groups !== undefined) {
+    if (!rules.pin_groups || typeof rules.pin_groups !== 'object' || Array.isArray(rules.pin_groups)) errors.push('rules.pin_groups: must be an object');
+    else for (const [name, ids] of Object.entries(rules.pin_groups)) {
+      if (!/^[a-zA-Z0-9_-]+$/.test(name) || ['__proto__', 'prototype', 'constructor'].includes(name) || !strings(ids)) errors.push(`rules.pin_groups.${name}: must contain capability ids`);
+    }
+  }
+  if (rules.always_load !== undefined) {
+    if (!Array.isArray(rules.always_load)) errors.push('rules.always_load: must be an array');
+    else for (const selector of rules.always_load) {
+      if (!selector || typeof selector !== 'object' || Array.isArray(selector) || !Object.keys(selector).length) { errors.push('rules.always_load: each selector must be a non-empty object'); continue; }
+      for (const key of Object.keys(selector)) if (!['rules', 'enforcement', 'capabilities', 'group', 'all'].includes(key)) errors.push(`rules.always_load.${key}: unknown selector field`);
+      for (const key of ['rules', 'enforcement', 'capabilities']) if (selector[key] !== undefined && !strings(selector[key])) errors.push(`rules.always_load.${key}: must be a non-empty array of ids`);
+      if (Array.isArray(selector.enforcement) && selector.enforcement.some(tier => !['critical', 'high', 'medium', 'low'].includes(tier))) errors.push('rules.always_load.enforcement: expected critical, high, medium, low');
+      if (selector.group !== undefined && (typeof selector.group !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(selector.group) || ['__proto__', 'prototype', 'constructor'].includes(selector.group))) errors.push('rules.always_load.group: expected a group name');
+      if (selector.all !== undefined && (selector.all !== true || Object.keys(selector).length !== 1)) errors.push('rules.always_load.all: true must be the only selector field');
+      if (selector.group !== undefined && selector.capabilities !== undefined) errors.push('rules.always_load: group and capabilities are mutually exclusive');
+    }
+  }
+  return errors;
+}
+
+export function resolveRulesInlineBudget(config = {}, env = process.env) {
+  const errors = validateRulesConfig(config.rules);
+  if (errors.length) throw new Error(errors.join('\n'));
+  const override = env.AIWG_RULES_INLINE_BUDGET_TOKENS;
+  if (override !== undefined) {
+    if (!/^\d+$/.test(override) || !Number.isSafeInteger(Number(override))) {
+      throw new Error('AIWG_RULES_INLINE_BUDGET_TOKENS: must be a non-negative safe integer');
+    }
+    return Number(override);
+  }
+  return config.rules?.inline_budget_tokens ?? DEFAULT_RULES_INLINE_BUDGET_TOKENS;
+}
+
+/** No filesystem writes or activation/selection changes. Provider hard caps are separate. */
+export function guardRulesInlineBudget({ provider, files, config = {}, env = process.env, reportOnly = false }) {
+  if (typeof provider !== 'string' || !provider.trim() || !Array.isArray(files)) {
+    throw new Error('Startup budget requires a provider and the complete projected files array.');
+  }
+  const limit = resolveRulesInlineBudget(config, env);
+  const contributors = files.map(file => {
+    if (!file || typeof file.path !== 'string' || !file.path.trim()) throw new Error('Startup contributor requires a path');
+    const bytes = file.bytes ?? (typeof file.content === 'string' ? Buffer.byteLength(file.content, 'utf8') : undefined);
+    if (!Number.isSafeInteger(bytes) || bytes < 0) throw new Error(`Invalid startup byte count for ${file.path}`);
+    return { path: file.path, bytes, estimated_tokens: bytes / 4 };
+  }).sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
+  const selected_bytes = contributors.reduce((total, file) => total + file.bytes, 0);
+  if (!Number.isSafeInteger(selected_bytes)) throw new Error('Startup byte total exceeds safe integer range');
+  const selected_tokens = selected_bytes / 4;
+  const exceeded = limit > 0 && selected_tokens > limit;
+  const report = { provider, limit, selected_bytes, selected_tokens, estimate: 'UTF-8 bytes / 4', disabled: limit === 0, exceeded, contributors };
+  const diagnostics = exceeded ? [{ severity: reportOnly ? 'warn' : 'error', code: 'inline-budget',
+    message: `Rules startup budget exceeded for ${provider}: ${selected_tokens} estimated tokens (${selected_bytes} bytes) selected; limit ${limit}. Contributors: ${contributors.map(file => `${file.path}: ${file.bytes} bytes (${file.estimated_tokens} tokens)`).join(', ')}. Activation-selected content is preserved.` }] : [];
+  return { report, diagnostics, passed: !exceeded || reportOnly };
+}

package/dist/src/rules/inventory.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRelations } from '../artifacts/relations.js';
+import { parseRuleFrontmatter, inferRuleActivation } from './activation.mjs';
+import { capabilityId, loadRulePinConfigs, resolveRulePins } from './pins.mjs';
+import { ruleFiles, rulePinState } from './pin-state.js';
+import { readUserRegistry } from '../config/user-registry.js';
+function includedByAll(root, cap) {
+    for (const kind of ['frameworks', 'addons', 'extensions']) {
+        const dir = path.join(root, 'agentic/code', kind, cap);
+        if (!fs.existsSync(dir) || cap === 'aiwg-dev')
+            continue;
+        const file = path.join(dir, 'manifest.json');
+        const manifest = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+        return !manifest.devOnly && !manifest.explicitInstall;
+    }
+    return false;
+}
+/** Read source metadata only. Catalog membership is availability, not applicability. */
+export async function ruleInventory(cwd, root, options) {
+    const configs = loadRulePinConfigs(cwd);
+    const selected = options.scope === 'user' ? { project: {}, user: configs.user } : configs;
+    const state = rulePinState(cwd, root, selected, true, false);
+    const relations = loadRelations(cwd, cwd, false) ?? loadRelations(root, cwd, false);
+    const userRegistry = await readUserRegistry();
+    const inventory = [...state.inventory];
+    if (options.scope === 'catalog') {
+        const known = new Set(inventory.map(rule => rule.path));
+        for (const kind of ['frameworks', 'addons', 'extensions', 'plugins']) {
+            const base = path.join(root, 'agentic/code', kind);
+            if (!fs.existsSync(base))
+                continue;
+            for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                for (const file of ruleFiles(path.join(base, entry.name, 'rules'))) {
+                    if (known.has(file))
+                        continue;
+                    const content = fs.readFileSync(file, 'utf8');
+                    const parsed = parseRuleFrontmatter(content);
+                    if (!parsed.valid)
+                        throw new Error(`${file}: ${parsed.diagnostics.map(d => d.message).join('; ')}`);
+                    const data = parsed.data;
+                    const enforcement = String(data.enforcement ?? content.match(/^\*\*Enforcement Level\*\*:\s*([A-Za-z]+)/m)?.[1] ?? '').toLowerCase() || null;
+                    inventory.push({ id: file, path: file, name: String(data.name || path.basename(file, '.md')), capability: entry.name,
+                        activation: parsed.rule.tagged ? parsed.rule.activation : inferRuleActivation(enforcement), enforcement });
+                    known.add(file);
+                }
+            }
+        }
+    }
+    const warnings = [...state.warnings];
+    if (!relations)
+        warnings.push('Relationship index unavailable; resolved bindings and indexed missing-source checks are unknown.');
+    if (options.provider)
+        warnings.push('Provider filter uses recorded capability deployments; missing records do not prove non-delivery.');
+    for (const capability of state.installed)
+        if (!state.inventory.some(rule => capabilityId(rule.capability) === capability)) {
+            warnings.push(`No rule sources found for installed capability '${capability}'; it may have no rules or its source may be unavailable.`);
+        }
+    if (relations)
+        for (const item of Object.values(relations.index.rules)) {
+            if (item.type !== 'rule' || !state.installed.includes(capabilityId(item.capability) ?? ''))
+                continue;
+            const file = path.resolve(root, item.path);
+            if (!fs.existsSync(file)) {
+                const message = `Installed indexed rule is missing: ${file}`;
+                if (options.bodies)
+                    throw new Error(message);
+                warnings.push(message);
+            }
+        }
+    const source = new Map(inventory.map(rule => {
+        const content = fs.readFileSync(rule.path, 'utf8');
+        const parsed = parseRuleFrontmatter(content);
+        if (!parsed.valid)
+            throw new Error(`${rule.path}: ${parsed.diagnostics.map(d => d.message).join('; ')}`);
+        const data = parsed.data;
+        const enforcement = String(data.enforcement ?? content.match(/^\*\*Enforcement Level\*\*:\s*([A-Za-z]+)/m)?.[1] ?? '').toLowerCase() || null;
+        const activation = parsed.rule.tagged ? parsed.rule.activation : inferRuleActivation(enforcement);
+        if (enforcement !== rule.enforcement)
+            warnings.push(`Stale enforcement metadata for ${rule.path}; canonical source used`);
+        if (activation !== rule.activation)
+            warnings.push(`Stale activation metadata for ${rule.path}; canonical source used`);
+        return [rule.path, { content, parsed, enforcement, activation }];
+    }));
+    // Resolve pins against source metadata, not potentially stale relation tiers.
+    const canonicalRules = inventory.map(rule => ({ ...rule, enforcement: source.get(rule.path).enforcement, activation: source.get(rule.path).activation }));
+    const canonicalPins = resolveRulePins({ rules: canonicalRules, configs: selected, installed: state.installed });
+    const pins = new Map(canonicalPins.rules.map(rule => [rule.path, rule]));
+    const rules = inventory.flatMap(rule => {
+        const cap = capabilityId(rule.capability) ?? '';
+        if (options.capability && !options.capability.some(value => capabilityId(value) === cap))
+            return [];
+        const pin = pins.get(rule.path);
+        const { content, parsed, enforcement, activation: canonical } = source.get(rule.path);
+        if (options.enforcement && !options.enforcement.includes(enforcement ?? ''))
+            return [];
+        const effective = pin?.activation ?? canonical;
+        if (options.activation && !options.activation.includes(effective))
+            return [];
+        const relation = relations && Object.entries(relations.index.rules).find(([, item]) => path.resolve(root, item.path) === rule.path);
+        const stableId = relation?.[0] ?? null;
+        const installed = state.installed.includes(cap);
+        const layers = [
+            { source: 'user-registry', entries: userRegistry.installed },
+            { source: 'user-config', entries: configs.user.installed ?? {} },
+            ...(options.scope === 'user' ? [] : [{ source: 'workspace-config', entries: configs.project.installed ?? {} }]),
+        ];
+        const hasBulkMembership = includedByAll(root, cap);
+        const configuredBy = layers.filter(layer => layer.entries[cap] || (hasBulkMembership && layer.entries.all)).map(layer => layer.source);
+        const entries = layers.flatMap(layer => [layer.entries[cap], ...(hasBulkMembership ? [layer.entries.all] : [])]);
+        const configuredProviders = [...new Set(entries.flatMap(entry => Object.keys(entry?.deployedTo ?? {})))].sort();
+        if (options.provider && !configuredProviders.includes(options.provider))
+            return [];
+        return [{ id: stableId, name: rule.name, capability: cap, source: rule.path, summary: parsed.rule.summary ?? null,
+                configured: installed, configured_by: configuredBy, applicable: installed ? 'conditional' : 'not-configured',
+                canonical_activation: canonical, effective_activation: installed ? effective : null,
+                enforcement, pin_reasons: pin?.matches ?? [],
+                bindings: relation ? relation[1].targets : null, binding_evidence: relation ? 'relationship-index' : 'unknown', bound_to: parsed.rule.bound_to, paths: parsed.rule.paths ?? [],
+                fetch_command: stableId ? `aiwg show rule ${stableId}` : null,
+                configured_providers: configuredProviders, delivery_evidence: configuredProviders.length ? 'capability deployment recorded; per-rule delivery unverified' : 'none', delivery: 'unknown', session_loaded: 'unknown',
+                ...(options.bodies ? { content } : {}) }];
+    }).sort((a, b) => a.capability.localeCompare(b.capability) || a.source.localeCompare(b.source));
+    return { scope: options.scope, scope_description: options.scope === 'workspace' ? 'current repository/workspace and user configuration' :
+            options.scope === 'user' ? 'user configuration and user installation registry' : options.scope === 'installation' ? 'configured installed capabilities' : 'available installation catalog; configured flags are contextual',
+        rules, warnings };
+}
+//# sourceMappingURL=inventory.js.map

package/dist/src/rules/pin-state.js

@@ -0,0 +1,73 @@
+/** Shared read-only inventory for pin commands, discovery, status, doctor and show. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRelations } from '../artifacts/relations.js';
+import { parseRuleFrontmatter, inferRuleActivation } from './activation.mjs';
+import { loadRulePinConfigs, installedRuleCapabilities, resolveRulePins, capabilityId } from './pins.mjs';
+export function ruleFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => entry.isDirectory()
+        ? ruleFiles(path.join(dir, entry.name)) : entry.name.endsWith('.md') && !/^RULES-(INDEX|ONDEMAND)/.test(entry.name) ? [path.join(dir, entry.name)] : []);
+}
+function localRuleSource(cwd, localPath) {
+    const wrapper = path.resolve(cwd, localPath);
+    const manifest = path.join(wrapper, 'manifest.json');
+    if (!fs.existsSync(manifest))
+        return wrapper;
+    const payload = JSON.parse(fs.readFileSync(manifest, 'utf8')).pluginConfig?.payloadPath;
+    if (!payload)
+        return wrapper;
+    const source = path.resolve(wrapper, payload);
+    const relative = path.relative(wrapper, source);
+    if (!relative || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative))
+        throw new Error(`${manifest}: plugin payload must remain beneath its wrapper`);
+    const realRelative = path.relative(fs.realpathSync(wrapper), fs.realpathSync(source));
+    if (realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative))
+        throw new Error(`${manifest}: plugin payload escapes its wrapper`);
+    return source;
+}
+export function rulePinState(cwd, root, configs = loadRulePinConfigs(cwd), requireInventory = false, cacheSourceDigest = true) {
+    const installed = installedRuleCapabilities(configs);
+    if (!requireInventory && !configs.project.rules?.always_load?.length && !configs.user.rules?.always_load?.length) {
+        return { ...resolveRulePins({ rules: [], configs, installed }), installed, configs, inventory: [] };
+    }
+    const relations = loadRelations(cwd, cwd, cacheSourceDigest) ?? loadRelations(root, cwd, cacheSourceDigest);
+    const rules = [];
+    const seen = new Set();
+    if (relations)
+        for (const [id, rule] of Object.entries(relations.index.rules)) {
+            if (!installed.includes(capabilityId(rule.capability) ?? '') || rule.type !== 'rule')
+                continue;
+            const file = path.resolve(root, rule.path);
+            // A stale sidecar must never retain an uninstalled or removed body.
+            if (!fs.existsSync(file))
+                continue;
+            seen.add(file);
+            rules.push({ ...rule, id, indexedPath: rule.path, path: file, file });
+        }
+    for (const capability of installed) {
+        const entry = configs.project.installed?.[capability];
+        const dirs = entry?.localPath ? [localRuleSource(cwd, entry.localPath)]
+            : ['frameworks', 'addons', 'extensions', 'plugins'].map(kind => path.join(root, 'agentic/code', kind, capability));
+        for (const dir of dirs)
+            for (const file of ruleFiles(path.join(dir, 'rules'))) {
+                if (seen.has(file))
+                    continue;
+                const content = fs.readFileSync(file, 'utf8');
+                const parsed = parseRuleFrontmatter(content);
+                if (!parsed.valid)
+                    throw new Error(`${file}: ${parsed.diagnostics.map(d => d.message).join('; ')}`);
+                const data = parsed.data;
+                const enforcement = String(data.enforcement ?? content.match(/^\*\*Enforcement Level\*\*:\s*([A-Za-z]+)/m)?.[1] ?? '').toLowerCase() || null;
+                rules.push({ id: file, name: String(data.name || path.basename(file, '.md')), path: file, file,
+                    indexedPath: path.relative(root, file), capability, enforcement,
+                    activation: parsed.rule.tagged ? parsed.rule.activation : inferRuleActivation(enforcement) });
+                seen.add(file);
+            }
+    }
+    // The source fallback covers project-local bundles or a fresh install with no sidecar.
+    const effective = resolveRulePins({ rules, configs, installed, relations });
+    return { ...effective, installed, configs, inventory: rules };
+}
+//# sourceMappingURL=pin-state.js.map

package/dist/src/rules/pins.d.mts

@@ -0,0 +1,14 @@
+import type { RulePinSelector, RulesConfig } from './inline-budget.mjs';
+import type { RelationsReader } from '../artifacts/relations.js';
+export interface PinConfig { installed?: Record<string, unknown>; providers?: string[]; rules?: RulesConfig }
+export interface PinConfigs { project: PinConfig; user: PinConfig }
+export interface PinRule { id: string; name: string; path: string; capability: string | null; activation: string | null; enforcement: string | null; type?: string; file?: string; indexedPath?: string; behavior?: boolean }
+export interface PinnedRule extends PinRule { canonical_activation: string | null; activation: 'kernel'; matches: Array<{ source: 'user' | 'project'; selector: RulePinSelector }> }
+export const RULE_PIN_TIERS: string[];
+export function rulePinConfigPath(cwd: string, source?: 'user' | 'project', userConfigDir?: string): string;
+export function loadRulePinConfigs(cwd: string, project?: PinConfig, userConfigDir?: string): PinConfigs;
+export function capabilityId(id: string | null): string | null;
+export function installedRuleCapabilities(configs: PinConfigs): string[];
+export function validateRulePinCapabilities(rules: unknown, installed: string[], groups?: Record<string, string[]>): string[];
+export function selectorKey(selector: RulePinSelector): string;
+export function resolveRulePins(options: { rules: PinRule[]; configs: PinConfigs; installed?: string[]; relations?: RelationsReader | null }): { rules: PinnedRule[]; warnings: string[] };