@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/config/cli.js

@@ -19,12 +19,36 @@
  */
 import { fileURLToPath } from 'url';
 import path from 'path';
+import { isDeepStrictEqual } from 'node:util';
+import { normalizeProviderDefinitionId } from '../providers/provider-definitions.js';
 import { UserConfig } from './user-config.js';
 import { AiwgError, EXIT_CODES } from '../cli/errors.js';
 import { isInteractive } from '../cli/env.js';
 import { exitCodeForSpawnResult } from '../cli/child-process-result.js';
 import { projectControlPath, resolveProjectAiwgDir } from './project-artifacts.js';
 const _scriptDir = path.dirname(fileURLToPath(import.meta.url));
+function warnStaleParallelism(cfg, projectDir, key, before) {
+    if (key !== 'parallelism' && !key.startsWith('parallelism.'))
+        return;
+    if (isDeepStrictEqual(before, getDottedPath(cfg, key)))
+        return;
+    const configured = (cfg.providers ?? []).map(normalizeProviderDefinitionId).filter((id) => !!id);
+    const recorded = Object.values(cfg.installed ?? {}).flatMap(entry => Object.keys(entry.deployedTo ?? {}))
+        .map(normalizeProviderDefinitionId).filter((id) => !!id).sort();
+    const providers = [...new Set([...configured, ...recorded])];
+    const targets = providers.length ? providers : ['<provider>'];
+    const lines = [
+        `WARNING: ${key} changed project configuration; generated workspace/provider guidance may now be stale.`,
+        `From project root ${path.resolve(projectDir)}, preview and refresh every configured or recorded provider context:`,
+        ...targets.flatMap(provider => [
+            `  aiwg regenerate --workspace --provider ${provider} --dry-run`,
+            `  aiwg regenerate --workspace --provider ${provider}`,
+        ]),
+        '  aiwg workspace-context doctor',
+        `Shared parallelism defaults and labels use primary provider '${cfg.providers?.[0] ?? 'unknown'}' (providers[0]); --provider selects the adapter/context target.`,
+    ];
+    console.error(lines.join('\n'));
+}
 /**
  * Main CLI entry point for `aiwg config <subcommand> [args]`
  */
@@ -102,6 +126,11 @@ async function handleGet(config, args) {
         await projectConfigGet(key, args);
         return;
     }
+    if (key === 'rules' || key.startsWith('rules.')) {
+        const { loadRulePinConfigs } = await import('../rules/pins.mjs');
+        console.log(JSON.stringify(getDottedPath(loadRulePinConfigs(process.cwd(), undefined, config.getPath()).user, key)) ?? '(not set)');
+        return;
+    }
     const value = await config.get(key);
     if (value === undefined) {
         console.log(`(not set)`);
@@ -130,6 +159,11 @@ async function handleSet(config, args) {
         await projectConfigSet(key, value, args);
         return;
     }
+    if (key === 'rules' || key.startsWith('rules.')) {
+        await setRuleConfigKey(process.cwd(), 'user', key, value, config.getPath());
+        console.log(`Set --user ${key} = ${value}`);
+        return;
+    }
     await config.set(key, value);
     console.log(`Set ${key} = ${value}`);
 }
@@ -176,6 +210,7 @@ const ENUM_RULES = {
     'setup.worker_dispatch_offer': ['declined'],
 };
 const BOOLEAN_FIELDS = new Set([
+    'decision.enabled',
     'delivery.delete_branch_on_merge',
     'delivery.require_ci_green',
     'delivery.require_signed_commits',
@@ -194,6 +229,10 @@ const STRING_ARRAY_FIELDS = new Set([
 // Integer fields with valid range constraints. Validated at `aiwg config set`.
 // Bounds mirror the JSON schema (vscode-extension/schemas/aiwg.config.v1.json).
 const INTEGER_FIELDS = {
+    'decision.ask.passes': { min: 1, max: Number.MAX_SAFE_INTEGER },
+    'decision.ask.escalation_passes': { min: 1, max: Number.MAX_SAFE_INTEGER },
+    'decision.ask.savings.reasoning_tokens': { min: 0, max: 1_000_000 },
+    'decision.ask.savings.output_tokens': { min: 0, max: 1_000_000 },
     'parallelism.max_parallel_subagents': { min: 1, max: 50 },
     'parallelism.max_parallel_ralph_loops': { min: 1, max: 20 },
     'parallelism.max_parallel_mc_missions': { min: 1, max: 20 },
@@ -239,7 +278,7 @@ async function projectConfigGet(key, args) {
         console.log(String(value));
     }
 }
-async function projectConfigSet(key, raw, args) {
+async function projectConfigSet(key, raw, args, quiet = false) {
     assertSafeConfigPath(key);
     if (key === 'defaults' || key.startsWith('defaults.')) {
         throw new AiwgError({
@@ -270,7 +309,7 @@ async function projectConfigSet(key, raw, args) {
     }
     // Coerce booleans for known boolean fields
     let value = raw;
-    if (key === 'parallelism' || /^parallelism\.(worker_dispatch|worker_mode|groups|clis|admission|budgets|health|retry|activation)(\.|$)/.test(key)) {
+    if (key === 'rules' || key.startsWith('rules.') || key === 'parallelism' || /^parallelism\.(worker_dispatch|worker_mode|groups|clis|admission|budgets|health|retry|activation)(\.|$)/.test(key)) {
         try {
             value = JSON.parse(raw);
         }
@@ -340,7 +379,7 @@ async function projectConfigSet(key, raw, args) {
     const intRule = INTEGER_FIELDS[key];
     if (intRule) {
         const n = Number(raw);
-        if (!Number.isInteger(n) || n < intRule.min || n > intRule.max) {
+        if (!raw.trim() || !Number.isInteger(n) || n < intRule.min || n > intRule.max) {
             throw new AiwgError({
                 code: 'ERR_INVALID_VALUE',
                 message: `${key} must be an integer between ${intRule.min} and ${intRule.max}, got '${raw}'`,
@@ -350,9 +389,32 @@ async function projectConfigSet(key, raw, args) {
         }
         value = n;
     }
+    if (key === 'decision.ask.min_agreement' || key === 'decision.ask.agreement_confidence_floor') {
+        const n = Number(raw);
+        if (!raw.trim() || !Number.isFinite(n) || n < 0 || n > 1) {
+            throw new AiwgError({
+                code: 'ERR_INVALID_VALUE',
+                message: `${key} must be a probability from 0 to 1, got '${raw}'`,
+                exitCode: EXIT_CODES.USAGE,
+            });
+        }
+        value = n;
+    }
+    if (key === 'decision.ask.cost.llm_per_mtok' || key === 'decision.ask.cost.jev_per_mtok') {
+        const n = Number(raw);
+        if (!raw.trim() || !Number.isFinite(n) || n < 0 || n > 1_000_000) {
+            throw new AiwgError({ code: 'ERR_INVALID_VALUE', message: `${key} must be a non-negative number <= 1000000`, exitCode: EXIT_CODES.USAGE });
+        }
+        value = n;
+    }
     // Read-modify-write — preserve unrelated fields. emptyConfig() seeds the
     // base shape when no config file exists yet (e.g. brand-new project).
-    const cfg = (await readAiwgConfig(projectDir)) ?? emptyConfig();
+    const { existsSync, readFileSync } = await import('node:fs');
+    const file = projectControlPath(projectDir, 'aiwg.config');
+    const cfg = key === 'rules' || key.startsWith('rules.')
+        ? (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : emptyConfig())
+        : (await readAiwgConfig(projectDir)) ?? emptyConfig();
+    const before = structuredClone(getDottedPath(cfg, key));
     setDottedPath(cfg, key, value);
     const externalLinkErrors = validateExternalLinks(cfg.externalLinks);
     if (externalLinkErrors.length > 0) {
@@ -374,7 +436,10 @@ async function projectConfigSet(key, raw, args) {
         });
     }
     await writeAiwgConfig(projectDir, cfg);
-    console.log(`Set --project ${key} = ${raw}`);
+    if (!quiet)
+        console.log(`Set --project ${key} = ${raw}`);
+    if (!quiet)
+        warnStaleParallelism(cfg, projectDir, key, before);
 }
 /** Read a dotted path from a nested record. Returns undefined when any segment is missing. */
 function getDottedPath(obj, key) {
@@ -441,6 +506,16 @@ async function handleValidate(config, args) {
         return;
     }
     const issues = await config.validate();
+    try {
+        const { loadRulePinConfigs, installedRuleCapabilities, validateRulePinCapabilities } = await import('../rules/pins.mjs');
+        const configs = loadRulePinConfigs(process.cwd(), undefined, config.getPath());
+        for (const message of validateRulePinCapabilities(configs.user.rules, installedRuleCapabilities(configs), configs.project.rules?.pin_groups)) {
+            issues.push({ file: 'aiwg.config', severity: 'error', message });
+        }
+    }
+    catch (error) {
+        issues.push({ file: 'aiwg.config', severity: 'error', message: error instanceof Error ? error.message : String(error) });
+    }
     console.log(`Config directory: ${config.getPath()}\n`);
     if (issues.length === 0) {
         console.log('✓ All config files valid');
@@ -583,6 +658,7 @@ async function projectConfigReset(key, args) {
     }
     const primary = cfg.providers[0];
     const defaults = getProviderParallelismDefaults(primary);
+    const before = structuredClone(getDottedPath(cfg, key));
     if (key === 'parallelism') {
         cfg.parallelism = {
             max_parallel_subagents: defaults.max_parallel_subagents,
@@ -592,6 +668,7 @@ async function projectConfigReset(key, args) {
         };
         await writeAiwgConfig(projectDir, cfg);
         console.log(`Reset --project parallelism to provider default (${primary ?? 'unknown'})`);
+        warnStaleParallelism(cfg, projectDir, key, before);
         return;
     }
     if (key.startsWith('parallelism.')) {
@@ -606,6 +683,7 @@ async function projectConfigReset(key, args) {
                 delete current[last];
             await writeAiwgConfig(projectDir, cfg);
             console.log(`Reset --project ${key}`);
+            warnStaleParallelism(cfg, projectDir, key, before);
             return;
         }
         const field = key.slice('parallelism.'.length);
@@ -614,6 +692,7 @@ async function projectConfigReset(key, args) {
             cfg.parallelism[field] = defaults[field];
             await writeAiwgConfig(projectDir, cfg);
             console.log(`Reset --project ${key} to provider default (${defaults[field]})`);
+            warnStaleParallelism(cfg, projectDir, key, before);
             return;
         }
     }
@@ -872,4 +951,31 @@ Examples:
   aiwg config gitignore --fix
   aiwg config gitignore --check`);
 }
+/** Same configuration owner and validation used by the rules command wrappers. */
+export async function setRuleConfigKey(cwd, source, key, raw, userConfigDir) {
+    assertSafeConfigPath(key);
+    if (source === 'project') {
+        await projectConfigSet(key, raw, ['--project', '--target', cwd], true);
+        return;
+    }
+    const { loadRulePinConfigs, rulePinConfigPath, installedRuleCapabilities, validateRulePinCapabilities } = await import('../rules/pins.mjs');
+    const { mkdir, writeFile, rename } = await import('node:fs/promises');
+    const configs = loadRulePinConfigs(cwd, undefined, userConfigDir);
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        value = raw;
+    }
+    setDottedPath(configs.user, key, value);
+    const errors = validateRulePinCapabilities(configs.user.rules, installedRuleCapabilities(configs), configs.project.rules?.pin_groups);
+    if (errors.length)
+        throw new Error(errors.join('\n'));
+    const file = rulePinConfigPath(cwd, 'user', userConfigDir);
+    await mkdir(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    await writeFile(temp, JSON.stringify(configs.user, null, 2) + '\n');
+    await rename(temp, file);
+}
 //# sourceMappingURL=cli.js.map

package/dist/src/config/decision-config.js

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseYamlSimple } from './user-config.js';
+import { resolveUserConfigDir } from './user-config-dir.mjs';
+export function validateDecisionConfig(value) {
+    if (value === undefined)
+        return [];
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return ['decision must be an object'];
+    const errors = [];
+    const { enabled, ask, offload_report: report } = value;
+    if (enabled !== undefined && typeof enabled !== 'boolean')
+        errors.push('decision.enabled must be a boolean');
+    if (report !== undefined) {
+        if (!report || typeof report !== 'object' || Array.isArray(report))
+            errors.push('decision.offload_report must be an object');
+        else {
+            for (const key of ['window_hours', 'minimum_eligible', 'repeated_fallbacks']) {
+                const configured = report[key];
+                if (configured !== undefined && (!Number.isSafeInteger(configured) || configured < (key === 'minimum_eligible' ? 0 : 1))) {
+                    errors.push(`decision.offload_report.${key} must be a ${key === 'minimum_eligible' ? 'non-negative' : 'positive'} safe integer`);
+                }
+            }
+            if (report.minimum_attempt_rate !== undefined && (typeof report.minimum_attempt_rate !== 'number'
+                || !Number.isFinite(report.minimum_attempt_rate) || report.minimum_attempt_rate < 0 || report.minimum_attempt_rate > 1)) {
+                errors.push('decision.offload_report.minimum_attempt_rate must be a probability from 0 to 1');
+            }
+            for (const key of Object.keys(report))
+                if (!['window_hours', 'minimum_eligible', 'minimum_attempt_rate', 'repeated_fallbacks'].includes(key)) {
+                    errors.push(`unknown decision.offload_report.${key}`);
+                }
+        }
+    }
+    if (ask === undefined)
+        return errors;
+    if (!ask || typeof ask !== 'object' || Array.isArray(ask))
+        return [...errors, 'decision.ask must be an object'];
+    const sampling = [];
+    for (const key of ['passes', 'escalation_passes']) {
+        if (ask[key] !== undefined && (!Number.isSafeInteger(ask[key]) || ask[key] <= 0)) {
+            sampling.push(`decision.ask.${key} must be a positive safe integer`);
+        }
+    }
+    if (!sampling.length && ask.escalation_passes !== undefined && ask.escalation_passes < (ask.passes ?? 5)) {
+        sampling.push('decision.ask.escalation_passes must be >= decision.ask.passes');
+    }
+    for (const key of ['min_agreement', 'agreement_confidence_floor']) {
+        if (ask[key] !== undefined && (typeof ask[key] !== 'number' || !Number.isFinite(ask[key]) || ask[key] < 0 || ask[key] > 1)) {
+            sampling.push(`decision.ask.${key} must be a probability from 0 to 1`);
+        }
+    }
+    for (const section of ['cost', 'savings']) {
+        const settings = ask[section];
+        if (settings === undefined)
+            continue;
+        if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+            sampling.push(`decision.ask.${section} must be an object`);
+            continue;
+        }
+        const allowed = section === 'cost' ? ['llm_per_mtok', 'jev_per_mtok'] : ['caller_model_class', 'reasoning_tokens', 'output_tokens'];
+        for (const [key, value] of Object.entries(settings)) {
+            if (!allowed.includes(key))
+                sampling.push(`unknown decision.ask.${section}.${key}`);
+            else if (key === 'caller_model_class') {
+                if (value !== 'standard' && value !== 'reasoning')
+                    sampling.push('decision.ask.savings.caller_model_class must be standard or reasoning');
+            }
+            else if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1_000_000
+                || (section === 'savings' && !Number.isSafeInteger(value))) {
+                sampling.push(`decision.ask.${section}.${key} must be a non-negative ${section === 'savings' ? 'integer' : 'number'} <= 1000000`);
+            }
+        }
+    }
+    return [...errors, ...sampling];
+}
+function readEnabled(filePath, yaml = false) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    const config = (yaml ? parseYamlSimple(content) : JSON.parse(content));
+    const errors = validateDecisionConfig(config.decision);
+    if (errors.length)
+        throw new Error(`${filePath}: ${errors.join('; ')}`);
+    return config.decision?.enabled;
+}
+/** Resolve only enablement; never read credentials or probe a backend. */
+export function resolveDecisionEnablement(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.AIWG_DECISION_ENABLED === '0' || env.AIWG_DECISION_ENABLED === '1') {
+        return { enabled: env.AIWG_DECISION_ENABLED === '1', source: 'env' };
+    }
+    const project = readEnabled(path.join(options.cwd ?? process.cwd(), '.aiwg', 'aiwg.config'));
+    if (project !== undefined)
+        return { enabled: project, source: 'project' };
+    const user = readEnabled(path.join(resolveUserConfigDir({ env, homeDir: options.homeDir }), 'config.yaml'), true);
+    if (user !== undefined)
+        return { enabled: user, source: 'user' };
+    return { enabled: false, source: 'default' };
+}
+//# sourceMappingURL=decision-config.js.map

package/dist/src/config/dispatch-thresholds-runtime.d.mts

@@ -0,0 +1,8 @@
+import type { DispatchHostThresholds } from './aiwg-config.js';
+
+export const DEFAULT_DISPATCH_HOST_THRESHOLDS: Readonly<Required<Omit<DispatchHostThresholds, 'max_workers'>>>;
+export function resolveDispatchHostThresholds(
+  buildDispatch?: DispatchHostThresholds,
+  admissionHostResources?: DispatchHostThresholds,
+  overlay?: DispatchHostThresholds,
+): Required<Omit<DispatchHostThresholds, 'max_workers'>> & Pick<DispatchHostThresholds, 'max_workers'>;

package/dist/src/config/gitignore.js

@@ -8,9 +8,11 @@
  * @module src/config/gitignore
  */
 import * as fs from 'fs/promises';
+import { existsSync, realpathSync } from 'fs';
 import * as path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import { boundedSpawnSync } from '../process/bounded-child-process.mjs';
 const execFileAsync = promisify(execFile);
 const GITIGNORE_PROBE_BASENAME = '.aiwg-ignore-probe';
 // ===========================
@@ -205,4 +207,52 @@ export async function appendGitignore(projectRoot, patterns) {
         created: !fileExists && toAdd.length > 0,
     };
 }
+/**
+ * Drop files git ignores (#2555).
+ *
+ * Shared by lint and artifact discovery. `git check-ignore` is asked once for
+ * the whole set so the semantics are git's own (negations, nested
+ * `.gitignore`, `core.excludesFile`) rather than a re-implementation. Outside a
+ * repository, or without git, every file is kept. NUL delimiters preserve
+ * whitespace and quoting in filenames.
+ */
+export function dropGitignored(targetDir, files) {
+    if (files.length === 0)
+        return files;
+    try {
+        // Avoid starting Git for synthetic/source trees outside a repository. Resolve
+        // symlinked working directories just as Git does, and probe on every call so
+        // initializing a repository between scans takes effect immediately. Explicit
+        // Git environment and bare repositories still use Git's own discovery.
+        if (!process.env.GIT_DIR && !process.env.GIT_WORK_TREE && !process.env.GIT_COMMON_DIR) {
+            let directory = realpathSync(targetDir);
+            for (;;) {
+                if (existsSync(path.join(directory, '.git')) ||
+                    (existsSync(path.join(directory, 'HEAD')) &&
+                        (existsSync(path.join(directory, 'objects')) || existsSync(path.join(directory, 'commondir')))))
+                    break;
+                const parent = path.dirname(directory);
+                if (parent === directory)
+                    return files;
+                directory = parent;
+            }
+        }
+        const result = boundedSpawnSync('git', ['check-ignore', '-z', '--stdin'], 'quick', {
+            cwd: targetDir,
+            input: `${files.join('\0')}\0`,
+            encoding: 'utf8',
+        });
+        // 0 = some paths ignored, 1 = none ignored, anything else = not a repo or
+        // git unavailable, in which case nothing is filtered.
+        if (result.error || (result.status !== 0 && result.status !== 1))
+            return files;
+        const ignored = new Set((result.stdout ?? '').split('\0').filter(Boolean));
+        if (ignored.size === 0)
+            return files;
+        return files.filter((file) => !ignored.has(file));
+    }
+    catch {
+        return files;
+    }
+}
 //# sourceMappingURL=gitignore.js.map

package/dist/src/config/index-graph-overrides.js

@@ -0,0 +1,36 @@
+export const OVERRIDABLE_INDEX_GRAPHS = ['project', 'codebase'];
+/** Shared by config validation and graph loading, including non-CLI callers. */
+export function validateIndexGraphOverrides(overrides) {
+    if (overrides === undefined)
+        return [];
+    if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+        return ['index.graphOverrides: must be an object mapping supported built-in graph names to overrides'];
+    }
+    const errors = [];
+    for (const [name, raw] of Object.entries(overrides)) {
+        const where = `index.graphOverrides.${name}`;
+        if (!OVERRIDABLE_INDEX_GRAPHS.includes(name)) {
+            errors.push(`${where}: unsupported built-in graph override (supported: ${OVERRIDABLE_INDEX_GRAPHS.join(', ')})`);
+            continue;
+        }
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            errors.push(`${where}: must be an object`);
+            continue;
+        }
+        const override = raw;
+        for (const field of Object.keys(override)) {
+            if (field !== 'scanDirs' && field !== 'extensions') {
+                errors.push(`${where}.${field}: unknown field (supported: scanDirs, extensions)`);
+            }
+        }
+        for (const field of ['scanDirs', 'extensions']) {
+            const value = override[field];
+            if (value !== undefined && (!Array.isArray(value) || value.length === 0 ||
+                !value.every(item => typeof item === 'string' && item.trim().length > 0))) {
+                errors.push(`${where}.${field}: must be a non-empty array of strings`);
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=index-graph-overrides.js.map

package/dist/src/config/project-artifacts-health.d.mts

@@ -0,0 +1,37 @@
+export type ProjectArtifactHealthClassification =
+  | 'local'
+  | 'healthy-split-root'
+  | 'degraded-offline'
+  | 'legacy-missing-control-plane'
+  | 'duplicated-identical'
+  | 'duplicated-divergent';
+
+export interface ProjectControlFileHealth {
+  file: string;
+  local: boolean;
+  external: boolean;
+  identical: boolean | null;
+}
+
+export interface ProjectArtifactHealth {
+  classification: ProjectArtifactHealthClassification;
+  severity: 'ok' | 'warning' | 'error';
+  external_configured: boolean;
+  source: { kind: string; key?: string; path?: string };
+  local_control_root: string;
+  artifact_root: string;
+  external_reachable: boolean;
+  control_files: ProjectControlFileHealth[];
+  missing_local_control_files: string[];
+  divergent_control_files: string[];
+  duplicated_local_corpus_files: string[];
+  divergent_local_corpus_files: string[];
+  repairable: boolean;
+  action: string | null;
+}
+
+export const PROJECT_CONTROL_PLANE_FILES: readonly string[];
+export function auditProjectArtifactHealth(
+  projectDir: string,
+  env?: Record<string, string | undefined>,
+): ProjectArtifactHealth;

package/dist/src/config/project-artifacts-runtime.d.mts

@@ -0,0 +1,16 @@
+export const DEFAULT_PROJECT_AIWG_DIR: '.aiwg';
+export const AIWG_ARTIFACTS_PATH_ENV: 'AIWG_ARTIFACTS_PATH';
+export const PROJECT_AIWG_LOCATION_FILE: '.aiwg-location';
+
+export type ProjectArtifactEnv = Record<string, string | undefined>;
+
+export function expandProjectArtifactPath(pathValue: string, projectDir: string): string;
+export function parseProjectArtifactLocation(contents: string): string | null;
+export function readProjectArtifactLocation(projectDir: string): string | null;
+export function resolveProjectAiwgDir(projectDir: string, env?: ProjectArtifactEnv): string;
+export function isProjectArtifactRootExternal(projectDir: string, env?: ProjectArtifactEnv): boolean;
+export function resolveProjectAiwgDirForWrite(projectDir: string, env?: ProjectArtifactEnv): string;
+export function resolveProjectControlDir(projectDir: string): string;
+export function projectAiwgPath(projectDir: string, ...segments: string[]): string;
+export function projectAiwgWritePath(projectDir: string, ...segments: string[]): string;
+export function projectControlPath(projectDir: string, ...segments: string[]): string;

package/dist/src/config/user-config-dir.d.mts

@@ -0,0 +1,9 @@
+export interface UserConfigDirOptions {
+  configDir?: string;
+  env?: Record<string, string | undefined>;
+  homeDir?: string;
+  exists?: (path: string) => boolean;
+}
+
+export function resolveUserConfigDir(options?: UserConfigDirOptions): string;
+export function userConfigFile(name: string, options?: UserConfigDirOptions): string;

package/dist/src/config/user-config.js

@@ -24,6 +24,7 @@ import { resolveUserConfigDir } from './user-config-dir.mjs';
  */
 export const KNOWN_CONFIG_FILES = [
     { filename: 'config.yaml', description: 'Global AIWG user preferences' },
+    { filename: 'aiwg.config', description: 'Operator rule pins and capability groups' },
     { filename: 'models.json', description: 'Model tier and provider overrides' },
     { filename: 'ops.json', description: 'Ops workspace registry' },
     { filename: 'mcp-servers.json', description: 'MCP server registry (single source of truth)' },
@@ -122,7 +123,7 @@ export class UserConfig {
             try {
                 await access(filePath);
                 const content = await readFile(filePath, 'utf-8');
-                if (spec.filename.endsWith('.json')) {
+                if (spec.filename.endsWith('.json') || spec.filename === 'aiwg.config') {
                     result[spec.filename] = JSON.parse(content);
                 }
                 else {

package/dist/src/config/user-registry.js

@@ -12,7 +12,6 @@
  * --scope user` works from any cwd.
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { userScopeConfigPath } from '../cli/scope-resolver.js';
 /**
@@ -46,28 +45,37 @@ export function emptyUserRegistry() {
     return { version: '1', installed: {} };
 }
 /**
- * Read the per-user registry. Returns an empty registry when the file doesn't
- * exist — that's the normal case before the operator's first `aiwg use --scope
- * user`. On parse failure returns the empty registry and writes a stderr
- * warning (the broken file is preserved so the operator can inspect it).
+ * Read the user registry while preserving whether empty means absent or
+ * unreadable. Callers making adoption/readiness claims must not collapse a
+ * corrupt or inaccessible registry into proof that an addon is missing.
  */
-export async function readUserRegistry() {
-    const path = userRegistryPath();
-    if (!existsSync(path))
-        return emptyUserRegistry();
+export async function inspectUserRegistry() {
+    const registryFile = userRegistryPath();
     try {
-        const raw = await readFile(path, 'utf-8');
+        const raw = await readFile(registryFile, 'utf-8');
         const parsed = JSON.parse(raw);
-        if (!parsed.installed || typeof parsed.installed !== 'object') {
-            return emptyUserRegistry();
+        if (!parsed.installed || typeof parsed.installed !== 'object' || Array.isArray(parsed.installed)) {
+            throw new Error('installed must be an object');
         }
-        return { version: '1', installed: parsed.installed };
+        return { registry: { version: '1', installed: parsed.installed }, status: 'available' };
     }
     catch (err) {
-        process.stderr.write(`[user-registry] failed to parse ${path}: ${err instanceof Error ? err.message : String(err)} — using empty registry\n`);
-        return emptyUserRegistry();
+        if (err.code === 'ENOENT') {
+            return { registry: emptyUserRegistry(), status: 'absent' };
+        }
+        process.stderr.write(`[user-registry] failed to parse ${registryFile}: ${err instanceof Error ? err.message : String(err)} — using empty registry\n`);
+        return { registry: emptyUserRegistry(), status: 'unreadable' };
     }
 }
+/**
+ * Read the per-user registry. Returns an empty registry when the file doesn't
+ * exist — that's the normal case before the operator's first `aiwg use --scope
+ * user`. On parse failure returns the empty registry and writes a stderr
+ * warning (the broken file is preserved so the operator can inspect it).
+ */
+export async function readUserRegistry() {
+    return (await inspectUserRegistry()).registry;
+}
 /**
  * Persist the user registry. Creates the parent directory if missing.
  */

package/dist/src/config/user-state.js

@@ -0,0 +1,7 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Host-local AIWG state, shared by CLI telemetry and maintenance leases. */
+export function getUserStateDir(env = process.env) {
+    return path.join(env.XDG_STATE_HOME || path.join(env.HOME || os.homedir(), '.local', 'state'), 'aiwg');
+}
+//# sourceMappingURL=user-state.js.map