@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

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

@@ -0,0 +1,883 @@
+/**
+ * Project-Level AIWG Config
+ *
+ * Manages `.aiwg/aiwg.config` — the project-level record of:
+ *   - Which AI provider toolchains this project targets
+ *   - Which frameworks/addons are deployed (with uninstall metadata)
+ *   - User-defined scripts callable via `aiwg run`
+ *
+ * @implements #621
+ */
+import { readFile, writeFile, mkdir, access, readdir, rename, unlink } from 'fs/promises';
+import { createHash, randomBytes } from 'crypto';
+import { resolve, join, isAbsolute } from 'path';
+import { normalizeNamedCaptures } from '../artifacts/index-builder.js';
+import { getProviderDefinition, PROVIDER_IDS, resolveProviderPathValue, } from '../providers/provider-definitions.js';
+import { validateAuthorization, } from '../policy/authorization.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from './project-artifacts.js';
+const CONFIG_FILENAME = 'aiwg.config';
+/**
+ * Operations that a workspace may authorize for one member repository.
+ * Filesystem/tool capability never implies authorization; unlisted members
+ * and actions are denied by the workspace resolver.
+ *
+ * @implements #1764
+ */
+export const WORKSPACE_REPO_ACTIONS = [
+    'read',
+    'write',
+    'commit',
+    'push',
+    'issue-comment',
+    'service-action',
+    'destructive',
+];
+const DEFAULT_BRANCH_NAMING = {
+    prefix_by_type: {
+        feat: 'feat/{issue}-{slug}',
+        fix: 'fix/{issue}-{slug}',
+        docs: 'docs/{slug}',
+        chore: 'chore/{slug}',
+        refactor: 'refactor/{slug}',
+        test: 'test/{slug}',
+    },
+};
+/**
+ * Resolve the delivery policy with defaults applied.
+ *
+ * Defaults are intentionally conservative — they match what AIWG agents
+ * naturally do today (PR-required, rebase-merge, no force pushes, post issue
+ * comments) so that adding the schema doesn't shift behavior for existing
+ * projects.
+ */
+export function resolveDelivery(delivery) {
+    return {
+        mode: delivery?.mode ?? 'pr-required',
+        default_branch: delivery?.default_branch ?? 'main',
+        branch_naming: {
+            prefix_by_type: {
+                ...DEFAULT_BRANCH_NAMING.prefix_by_type,
+                ...(delivery?.branch_naming?.prefix_by_type ?? {}),
+            },
+        },
+        merge_style: delivery?.merge_style ?? 'rebase-merge',
+        delete_branch_on_merge: delivery?.delete_branch_on_merge ?? true,
+        require_ci_green: delivery?.require_ci_green ?? true,
+        require_signed_commits: delivery?.require_signed_commits ?? false,
+        committer: delivery?.committer,
+        signing: delivery?.signing,
+        release_signing: delivery?.release_signing,
+        force_push_policy: delivery?.force_push_policy ?? 'never',
+        auto_close_issues: delivery?.auto_close_issues ?? true,
+        issue_comment_on_cycle: delivery?.issue_comment_on_cycle ?? true,
+    };
+}
+/**
+ * Per-provider parallelism defaults. Conservative numbers for Anthropic-backed
+ * providers reflect Pro/Team-plan rate limits — operators on Enterprise tiers
+ * should bump via `aiwg config set --project parallelism.max_parallel_subagents N`.
+ *
+ * Sources for the numbers:
+ *   - claude / claude-code: Anthropic per-key throttling at higher concurrency
+ *   - codex / copilot / etc.: OpenAI / GitHub quotas are generally per-org and
+ *     less aggressive at small fan-outs (10 is a safe middle ground)
+ *   - hermes: MCP sidecar; rate-limit depends on upstream provider, operator
+ *     should tune. Conservative 10 default.
+ *   - unknown: conservative 4 default.
+ */
+export const PROVIDER_PARALLELISM_DEFAULTS = {
+    claude: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
+    codex: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    copilot: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    cursor: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    factory: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    opencode: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    warp: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    windsurf: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    openclaw: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    hermes: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+};
+const UNKNOWN_PROVIDER_PARALLELISM = {
+    max_parallel_subagents: 4,
+    max_parallel_ralph_loops: 2,
+    max_parallel_mc_missions: 4,
+};
+/**
+ * Return the provider's parallelism defaults, or the conservative fallback
+ * when the provider is unknown.
+ */
+export function getProviderParallelismDefaults(provider) {
+    if (!provider)
+        return UNKNOWN_PROVIDER_PARALLELISM;
+    return PROVIDER_PARALLELISM_DEFAULTS[provider] ?? UNKNOWN_PROVIDER_PARALLELISM;
+}
+/**
+ * Resolve the parallelism caps with provider-aware defaults applied. The
+ * primary provider drives the default — typically the first entry in the
+ * project's `providers` array.
+ *
+ * When `parallelism` has explicit values, they override the provider default
+ * field-by-field. When no provider is supplied (or it's not in the defaults
+ * map), the conservative 4-subagent fallback applies.
+ *
+ * @implements #1359
+ */
+export function resolveParallelism(parallelism, primaryProvider) {
+    const defaults = getProviderParallelismDefaults(primaryProvider);
+    const resolved = {
+        max_parallel_subagents: parallelism?.max_parallel_subagents ?? defaults.max_parallel_subagents,
+        max_parallel_ralph_loops: parallelism?.max_parallel_ralph_loops ?? defaults.max_parallel_ralph_loops,
+        max_parallel_mc_missions: parallelism?.max_parallel_mc_missions ?? defaults.max_parallel_mc_missions,
+    };
+    if (parallelism?.rationale !== undefined)
+        resolved.rationale = parallelism.rationale;
+    return resolved;
+}
+const GRAPH_BACKENDS = ['json', 'graphology', 'sqlite'];
+const NODE_STRATEGIES = ['default', 'filename-metadata'];
+const BUILD_TIERS = ['lightweight', 'standard', 'heavy'];
+/**
+ * Validate an `index` config block, returning a list of human-readable error
+ * messages (empty = valid). Hand-rolled rather than ajv because aiwg.config has
+ * no runtime schema-validation pipeline and the codebase deliberately avoids
+ * pulling a validator dependency for config parsing (#1491).
+ *
+ * Catches the failure modes #1491 calls out: unknown graph type, missing
+ * scanDirs, bad regex, typo'd keys, malformed manifest. `aiwg index build` and
+ * `aiwg doctor` surface these at validate time instead of at runtime.
+ *
+ * @param index The value of `aiwg.config.index` (untrusted shape).
+ * @returns Array of error strings; empty when the block is valid or absent.
+ */
+export function validateIndexConfig(index) {
+    const errors = [];
+    if (index === undefined || index === null)
+        return errors;
+    if (typeof index !== 'object' || Array.isArray(index)) {
+        return ['index: must be an object'];
+    }
+    const graphs = index.graphs;
+    if (graphs === undefined)
+        return errors; // index with no graphs is permissible
+    if (typeof graphs !== 'object' || graphs === null || Array.isArray(graphs)) {
+        return ['index.graphs: must be an object mapping graph names to definitions'];
+    }
+    const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+    for (const [name, rawDef] of Object.entries(graphs)) {
+        const where = `index.graphs.${name}`;
+        if (typeof rawDef !== 'object' || rawDef === null || Array.isArray(rawDef)) {
+            errors.push(`${where}: must be an object`);
+            continue;
+        }
+        const def = rawDef;
+        if (name === 'indices') {
+            // Markdown-view manifest (build.py).
+            const manifest = def.manifest;
+            if (!Array.isArray(manifest)) {
+                errors.push(`${where}.manifest: must be an array`);
+                continue;
+            }
+            manifest.forEach((entry, i) => {
+                if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+                    errors.push(`${where}.manifest[${i}]: must be an object`);
+                    return;
+                }
+                const e = entry;
+                if (typeof e.name !== 'string' || e.name.trim() === '') {
+                    errors.push(`${where}.manifest[${i}]: 'name' is required and must be a non-empty string (it selects the renderer)`);
+                }
+                if (e.output !== undefined && typeof e.output !== 'string') {
+                    errors.push(`${where}.manifest[${i}].output: must be a string`);
+                }
+            });
+            continue;
+        }
+        // JSON node/edge graph def.
+        if (!isStringArray(def.scanDirs) || def.scanDirs.length === 0) {
+            errors.push(`${where}.scanDirs: required, must be a non-empty array of strings`);
+        }
+        if (def.extensions !== undefined && !isStringArray(def.extensions)) {
+            errors.push(`${where}.extensions: must be an array of strings`);
+        }
+        if (def.nodeStrategy !== undefined && !NODE_STRATEGIES.includes(def.nodeStrategy)) {
+            errors.push(`${where}.nodeStrategy: must be one of ${NODE_STRATEGIES.join(' | ')}`);
+        }
+        if (def.graphBackend !== undefined && !GRAPH_BACKENDS.includes(def.graphBackend)) {
+            errors.push(`${where}.graphBackend: must be one of ${GRAPH_BACKENDS.join(' | ')}`);
+        }
+        if (def.buildTier !== undefined && !BUILD_TIERS.includes(def.buildTier)) {
+            errors.push(`${where}.buildTier: must be one of ${BUILD_TIERS.join(' | ')}`);
+        }
+        if (def.buildOrder !== undefined && (typeof def.buildOrder !== 'number' || !Number.isFinite(def.buildOrder))) {
+            errors.push(`${where}.buildOrder: must be a finite number`);
+        }
+        if (def.nodeStrategy === 'filename-metadata') {
+            if (typeof def.filenamePattern !== 'string' || def.filenamePattern.trim() === '') {
+                errors.push(`${where}.filenamePattern: required when nodeStrategy is 'filename-metadata'`);
+            }
+        }
+        if (def.filenamePattern !== undefined && typeof def.filenamePattern === 'string') {
+            try {
+                // Apply the same Python→JS named-capture normalization the builder uses
+                // (index-builder.ts buildFilenameMetadataEntry) so the validator doesn't
+                // reject patterns the builder would happily compile. Fixes #1514 —
+                // `aiwg` workspace refresh emits Python-style `(?P<name>)` patterns
+                // (port residue from the Python build.py); the builder is lenient, the
+                // validator wasn't, so legit configs failed up front.
+                // eslint-disable-next-line no-new
+                new RegExp(normalizeNamedCaptures(def.filenamePattern));
+            }
+            catch (err) {
+                errors.push(`${where}.filenamePattern: not a valid regular expression (${err.message})`);
+            }
+        }
+        if (def.edgeExtraction !== undefined) {
+            const ee = def.edgeExtraction;
+            if (typeof ee !== 'object' || ee === null || Array.isArray(ee)) {
+                errors.push(`${where}.edgeExtraction: must be an object`);
+            }
+            else {
+                const eo = ee;
+                if (eo.parser !== 'citation-sidecar') {
+                    errors.push(`${where}.edgeExtraction.parser: must be 'citation-sidecar'`);
+                }
+                if (!Array.isArray(eo.edges)) {
+                    errors.push(`${where}.edgeExtraction.edges: must be an array`);
+                }
+                else {
+                    eo.edges.forEach((edge, i) => {
+                        if (typeof edge !== 'object' || edge === null) {
+                            errors.push(`${where}.edgeExtraction.edges[${i}]: must be an object`);
+                            return;
+                        }
+                        const ed = edge;
+                        for (const k of ['type', 'source', 'target']) {
+                            if (typeof ed[k] !== 'string' || ed[k].trim() === '') {
+                                errors.push(`${where}.edgeExtraction.edges[${i}].${k}: required, must be a non-empty string`);
+                            }
+                        }
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+}
+const EXTERNAL_LINK_KEY_PATTERN = /^[a-z][a-z0-9_-]*$/;
+/**
+ * Validate project-defined external links without performing network access.
+ */
+export function validateExternalLinks(externalLinks) {
+    if (externalLinks === undefined || externalLinks === null)
+        return [];
+    if (typeof externalLinks !== 'object' || Array.isArray(externalLinks)) {
+        return ['externalLinks: must be an object mapping stable identifiers to link definitions'];
+    }
+    const errors = [];
+    for (const [key, rawLink] of Object.entries(externalLinks)) {
+        const where = `externalLinks.${key}`;
+        if (!EXTERNAL_LINK_KEY_PATTERN.test(key)) {
+            errors.push(`${where}: key must start with a lowercase letter and contain only lowercase letters, numbers, underscores, or hyphens`);
+        }
+        if (!rawLink || typeof rawLink !== 'object' || Array.isArray(rawLink)) {
+            errors.push(`${where}: must be an object`);
+            continue;
+        }
+        const link = rawLink;
+        const allowedFields = new Set(['label', 'url', 'description', 'category', 'audience']);
+        for (const field of Object.keys(link)) {
+            if (!allowedFields.has(field)) {
+                errors.push(`${where}.${field}: unknown field`);
+            }
+        }
+        if (typeof link.label !== 'string' || link.label.trim() === '') {
+            errors.push(`${where}.label: required, must be a non-empty string`);
+        }
+        else if (link.label.length > 200) {
+            errors.push(`${where}.label: must be at most 200 characters`);
+        }
+        if (typeof link.url !== 'string' || link.url.trim() === '') {
+            errors.push(`${where}.url: required, must be an absolute HTTP(S) URL`);
+        }
+        else {
+            try {
+                const parsed = new URL(link.url);
+                if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+                    errors.push(`${where}.url: protocol must be http or https`);
+                }
+                if (parsed.username || parsed.password) {
+                    errors.push(`${where}.url: embedded credentials are not allowed`);
+                }
+            }
+            catch {
+                errors.push(`${where}.url: must be a valid absolute URL`);
+            }
+        }
+        for (const field of ['description', 'category', 'audience']) {
+            const value = link[field];
+            if (value !== undefined && (typeof value !== 'string' || value.trim() === '')) {
+                errors.push(`${where}.${field}: must be a non-empty string when provided`);
+            }
+            else if (typeof value === 'string' && value.length > 500) {
+                errors.push(`${where}.${field}: must be at most 500 characters`);
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Validate the general workspace-of-repositories blocks.
+ *
+ * This is intentionally runtime validation as well as schema documentation:
+ * CLI callers may not have editor/schema support, and authorization data must
+ * fail closed when malformed.
+ *
+ * @implements #1764
+ */
+export function validateWorkspaceConfig(workspace, repos) {
+    const errors = [];
+    if (workspace === undefined && repos === undefined)
+        return errors;
+    if (!workspace || typeof workspace !== 'object' || Array.isArray(workspace)) {
+        return ['workspace: must be an object when workspace or repos is configured'];
+    }
+    const metadata = workspace;
+    for (const field of ['name', 'root', 'member_of']) {
+        if (metadata[field] !== undefined && (typeof metadata[field] !== 'string' || !metadata[field].trim())) {
+            errors.push(`workspace.${field}: must be a non-empty string`);
+        }
+    }
+    if (metadata.member_of !== undefined && repos !== undefined) {
+        errors.push('workspace.member_of: member back-references must not also declare repos');
+    }
+    if (repos === undefined)
+        return errors;
+    if (typeof metadata.name !== 'string' || !metadata.name.trim()) {
+        errors.push('workspace.name: required when repos is configured');
+    }
+    if (!Array.isArray(repos) || repos.length === 0) {
+        errors.push('repos: must be a non-empty array');
+        return errors;
+    }
+    const names = new Set();
+    const paths = new Set();
+    const allowedActions = new Set(WORKSPACE_REPO_ACTIONS);
+    repos.forEach((raw, index) => {
+        const where = `repos[${index}]`;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push(`${where}: must be an object`);
+            return;
+        }
+        const repo = raw;
+        if (typeof repo.name !== 'string' || !repo.name.trim()) {
+            errors.push(`${where}.name: required and must be a non-empty string`);
+        }
+        else if (names.has(repo.name.trim())) {
+            errors.push(`${where}.name: duplicate member name '${repo.name.trim()}'`);
+        }
+        else {
+            names.add(repo.name.trim());
+        }
+        if (typeof repo.path !== 'string' || !repo.path.trim()) {
+            errors.push(`${where}.path: required and must be a non-empty string`);
+        }
+        else if (paths.has(repo.path.trim())) {
+            errors.push(`${where}.path: duplicate member path '${repo.path.trim()}'`);
+        }
+        else {
+            paths.add(repo.path.trim());
+        }
+        if (!Array.isArray(repo.allowed) || repo.allowed.length === 0) {
+            errors.push(`${where}.allowed: must be a non-empty array`);
+        }
+        else {
+            for (const action of repo.allowed) {
+                if (typeof action !== 'string' || !allowedActions.has(action)) {
+                    errors.push(`${where}.allowed: invalid operation '${String(action)}'`);
+                }
+            }
+        }
+        if (repo.provider !== undefined && !['gitea', 'github', 'gitlab'].includes(String(repo.provider))) {
+            errors.push(`${where}.provider: must be gitea, github, or gitlab`);
+        }
+        if (repo.notes !== undefined && typeof repo.notes !== 'string') {
+            errors.push(`${where}.notes: must be a string`);
+        }
+    });
+    return errors;
+}
+/**
+ * Read the `index` block, preferring `.aiwg/aiwg.config` (the consolidated
+ * home, #1491) and falling back to the legacy `.aiwg/config.yaml` `index:`
+ * block. Returns `{ index, source }` where source is 'aiwg.config',
+ * 'config.yaml' (deprecated), or 'none'.
+ *
+ * The fallback keeps un-migrated corpora working; callers should surface a
+ * deprecation notice when `source === 'config.yaml'`.
+ */
+export async function readIndexConfig(projectDir) {
+    const cfg = await readAiwgConfig(projectDir);
+    if (cfg?.index && typeof cfg.index === 'object') {
+        return { index: cfg.index, source: 'aiwg.config' };
+    }
+    // Fallback: legacy config.yaml in the resolved AIWG artifact directory (deprecated).
+    const yamlPath = projectAiwgPath(projectDir, 'config.yaml');
+    try {
+        await access(yamlPath);
+        const { load: loadYaml } = await import('js-yaml');
+        const raw = loadYaml(await readFile(yamlPath, 'utf-8'));
+        const idx = raw?.index;
+        if (idx && typeof idx === 'object') {
+            return { index: idx, source: 'config.yaml' };
+        }
+    }
+    catch {
+        /* no config.yaml or unreadable */
+    }
+    return { index: undefined, source: 'none' };
+}
+/**
+ * Provider tag for a given remote URL. Used by skills (issue-create,
+ * pr-review, commit-and-push) to pick the right CLI / MCP client when
+ * the operator didn't pass `--provider` explicitly.
+ *
+ * Recognized hosts:
+ *   - github.com         → 'github'
+ *   - gitlab.com / gitlab.* → 'gitlab'
+ *   - any host containing 'gitea' (or matching the typical Gitea path shape) → 'gitea'
+ *
+ * Returns 'unknown' for self-hosted instances we can't classify by host alone —
+ * callers should then prompt the operator or fall back to the configured
+ * AIWG provider list.
+ *
+ * @implements #997
+ */
+export function resolveRemoteProvider(remoteUrl) {
+    if (!remoteUrl)
+        return 'unknown';
+    const lower = remoteUrl.toLowerCase();
+    // github.com (or git@github.com:owner/repo.git form)
+    if (/(^|[/@])github\.com[:/]/.test(lower))
+        return 'github';
+    // gitlab.com or self-hosted gitlab
+    if (/(^|[/@])gitlab\./.test(lower) || lower.includes('/gitlab/'))
+        return 'gitlab';
+    // gitea — identified by hostname token. Self-hosted Gitea instances often
+    // don't include 'gitea' in their hostname (e.g. corporate git servers), so
+    // 'unknown' is the honest answer there — callers should consult the
+    // configured AIWG provider list rather than guess.
+    if (lower.includes('gitea'))
+        return 'gitea';
+    return 'unknown';
+}
+/**
+ * Resolve the repo remote topology with defaults applied.
+ *
+ * Defaults:
+ *   - `primary` defaults to "origin"
+ *   - `issue_tracker` defaults to `primary`
+ *   - `ci` defaults to `primary`
+ *   - `secondary` defaults to `[]`
+ *
+ * Pass an absent or partial `remotes` block — every field comes back populated.
+ */
+export function resolveRemotes(remotes) {
+    const primary = remotes?.primary ?? 'origin';
+    return {
+        primary,
+        issue_tracker: remotes?.issue_tracker ?? primary,
+        ci: remotes?.ci ?? primary,
+        tracker_actor: remotes?.tracker_actor,
+        transport: remotes?.transport,
+        secondary: remotes?.secondary ?? [],
+    };
+}
+/**
+ * Resolve stable semantic label roles to provider-native label strings.
+ * The same role therefore drives Gitea, GitHub, and local issue-store flows.
+ */
+export function resolveIssueLabels(issues, provider) {
+    const diagnostics = validateIssueLabels(issues, { provider });
+    if (!issues?.labels) {
+        return {
+            labels: {},
+            diagnostics: [{
+                    severity: 'warning',
+                    code: 'fallback',
+                    message: 'issues.labels is not configured; issue workflows retain legacy label-name behavior and must warn before guessing or provisioning labels.',
+                }],
+        };
+    }
+    const labels = Object.fromEntries(Object.entries(issues.labels).map(([role, definition]) => [
+        role,
+        {
+            ...definition,
+            role,
+            provider,
+            resolved_name: definition.provider_names?.[provider] ?? definition.name,
+        },
+    ]));
+    return { labels, diagnostics };
+}
+/**
+ * Validate taxonomy structure and, when supplied, tracker availability.
+ * This function is read-only: ordinary issue processing never provisions
+ * missing labels implicitly.
+ */
+export function validateIssueLabels(issues, options = {}) {
+    if (!issues?.labels)
+        return [];
+    const diagnostics = [];
+    const seenNames = new Map();
+    const roles = new Set(Object.keys(issues.labels));
+    const available = options.availableLabels ? new Set(options.availableLabels) : undefined;
+    const categories = new Set([
+        'type', 'area', 'priority', 'lifecycle', 'blocked-reason',
+        'review-approval', 'ownership', 'automation-eligibility', 'human-interaction',
+    ]);
+    for (const [role, definition] of Object.entries(issues.labels)) {
+        const where = `issues.labels.${role}`;
+        if (!definition.name?.trim() || !definition.description?.trim() || !definition.category) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'missing',
+                role,
+                message: `${where} must define non-empty name, description, and category fields.`,
+            });
+            continue;
+        }
+        if (!categories.has(definition.category)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'conflict',
+                role,
+                message: `${where}.category '${definition.category}' is not a supported semantic category.`,
+            });
+        }
+        if (typeof definition.requires_human !== 'boolean' || typeof definition.blocks_automation !== 'boolean') {
+            diagnostics.push({
+                severity: 'error',
+                code: 'missing',
+                role,
+                message: `${where} must explicitly define requires_human and blocks_automation booleans.`,
+            });
+        }
+        if (definition.blocks_automation && !definition.requires_human && !definition.resume_when) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'conflict',
+                role,
+                message: `${where} blocks automation but declares neither human action nor a resume condition.`,
+            });
+        }
+        if (definition.blocks_automation && !definition.resume_when?.trim()) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'missing',
+                role,
+                message: `${where}.resume_when is required when blocks_automation is true.`,
+            });
+        }
+        if (definition.transition_to && !roles.has(definition.transition_to)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'conflict',
+                role,
+                message: `${where}.transition_to references unknown semantic role '${definition.transition_to}'.`,
+            });
+        }
+        const resolvedName = options.provider
+            ? definition.provider_names?.[options.provider] ?? definition.name
+            : definition.name;
+        const normalized = resolvedName.trim().toLocaleLowerCase();
+        const previousRole = seenNames.get(normalized);
+        if (previousRole) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'duplicate',
+                role,
+                message: `${where} resolves to '${resolvedName}', already used by role '${previousRole}'.`,
+            });
+        }
+        else {
+            seenNames.set(normalized, role);
+        }
+        if (available && !available.has(resolvedName)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'unavailable',
+                role,
+                message: `${where} resolves to unavailable tracker label '${resolvedName}'; provision it explicitly before issue processing.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+export const VALID_PROVIDERS = PROVIDER_IDS.filter((provider) => provider !== 'generic');
+/**
+ * Empty config template.
+ *
+ * Includes an explicit `delivery` block defaulting to `pr-required`. The
+ * runtime default in {@link resolveDelivery} is the same, so this is purely
+ * for visibility — new projects ship with the policy written down so users
+ * can see what their agents will do, and switch via `aiwg config set` or
+ * the AIWG Steward agent without first having to discover the field exists.
+ */
+export function emptyConfig(providers = ['claude']) {
+    const primaryProvider = providers[0];
+    const parDefaults = getProviderParallelismDefaults(primaryProvider);
+    const knownProvider = primaryProvider && primaryProvider in PROVIDER_PARALLELISM_DEFAULTS;
+    return {
+        $schema: 'https://aiwg.io/schemas/aiwg.config.v1.json',
+        version: '1',
+        providers,
+        installed: {},
+        scripts: {},
+        delivery: {
+            mode: 'pr-required',
+            default_branch: 'main',
+            require_ci_green: true,
+            auto_close_issues: true,
+            issue_comment_on_cycle: true,
+            force_push_policy: 'never',
+        },
+        parallelism: {
+            max_parallel_subagents: parDefaults.max_parallel_subagents,
+            max_parallel_ralph_loops: parDefaults.max_parallel_ralph_loops,
+            max_parallel_mc_missions: parDefaults.max_parallel_mc_missions,
+            rationale: knownProvider
+                ? `Provider default for ${primaryProvider} — adjust via 'aiwg config set --project parallelism.max_parallel_subagents N'`
+                : `Conservative default (unknown provider) — adjust via 'aiwg config set --project parallelism.max_parallel_subagents N'`,
+        },
+    };
+}
+/**
+ * Resolve path to the project-level AIWG config.
+ *
+ * Defaults to `<project>/.aiwg/aiwg.config`; honors `AIWG_ARTIFACTS_PATH` so
+ * projects can rename or relocate the AIWG artifact directory.
+ */
+export function getConfigPath(projectDir) {
+    return projectAiwgPath(projectDir, CONFIG_FILENAME);
+}
+/**
+ * Resolve the project directory for a handler invocation.
+ *
+ * Precedence:
+ *   1. `--target <path>` or `--prefix <path>` flag in args
+ *   2. The HandlerContext `cwd`, if provided
+ *   3. `process.cwd()`
+ *
+ * All three variants existed scattered across handlers (#919 cleanup).
+ * Use this helper so we have one authoritative resolution.
+ */
+export function getProjectDir(ctx, args = []) {
+    const targetIdx = args.findIndex(a => a === '--target' || a === '--prefix');
+    const targetValue = targetIdx >= 0 ? args[targetIdx + 1] : undefined;
+    return targetValue || ctx?.cwd || process.cwd();
+}
+/**
+ * Read .aiwg/aiwg.config.
+ * Returns null if the file does not exist.
+ */
+export async function readAiwgConfig(projectDir) {
+    const filePath = getConfigPath(projectDir);
+    try {
+        await access(filePath);
+    }
+    catch {
+        return null;
+    }
+    const content = await readFile(filePath, 'utf-8');
+    const parsed = JSON.parse(content);
+    // Ensure required fields exist (forward-compat)
+    if (!parsed.providers)
+        parsed.providers = ['claude'];
+    if (!parsed.installed)
+        parsed.installed = {};
+    if (!parsed.scripts)
+        parsed.scripts = {};
+    const externalLinkErrors = validateExternalLinks(parsed.externalLinks);
+    if (externalLinkErrors.length > 0) {
+        throw new Error(`Invalid .aiwg/aiwg.config:\n${externalLinkErrors.join('\n')}`);
+    }
+    const workspaceErrors = validateWorkspaceConfig(parsed.workspace, parsed.repos);
+    if (workspaceErrors.length > 0) {
+        throw new Error(`Invalid .aiwg/aiwg.config:\n${workspaceErrors.join('\n')}`);
+    }
+    const authorizationErrors = parsed.authorization
+        ? validateAuthorization(parsed.authorization).filter(item => item.severity === 'error')
+        : [];
+    if (authorizationErrors.length > 0) {
+        throw new Error(`Invalid .aiwg/aiwg.config:\n${authorizationErrors.map(item => item.message).join('\n')}`);
+    }
+    return parsed;
+}
+/**
+ * Write aiwg.config, creating the resolved AIWG artifact directory if needed.
+ */
+export async function writeAiwgConfig(projectDir, config) {
+    const dir = resolveProjectAiwgDir(projectDir);
+    await mkdir(dir, { recursive: true });
+    const filePath = join(dir, CONFIG_FILENAME);
+    // Atomic write: emit to a temp sibling, fsync-ish via rename. Prevents a
+    // crash or kill mid-write from corrupting the config file. Rename is
+    // atomic on POSIX and on NTFS when both paths are on the same volume.
+    // The random suffix avoids collisions if two concurrent writers run.
+    const tmpPath = `${filePath}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        await writeFile(tmpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        await rename(tmpPath, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of the temp file on failure, ignoring ENOENT.
+        try {
+            await unlink(tmpPath);
+        }
+        catch {
+            /* ignore */
+        }
+        throw err;
+    }
+}
+/**
+ * Update the `installed` record for a framework after a successful deployment.
+ * Returns the updated config (does not write to disk — caller must call writeAiwgConfig).
+ */
+export function updateInstalled(config, name, provider, counts, opts) {
+    // Project-local invariant: `source: 'project-local'` requires localPath + localType
+    // (per ADR adr-unified-registry-shape §6 risk mitigation).
+    if (opts.source === 'project-local') {
+        if (!opts.localPath || !opts.localType) {
+            throw new Error(`updateInstalled: source 'project-local' requires localPath and localType (got ${JSON.stringify({ localPath: opts.localPath, localType: opts.localType })})`);
+        }
+    }
+    const existing = config.installed[name] ?? {
+        version: opts.version,
+        source: opts.source,
+        installedAt: new Date().toISOString(),
+        deployedTo: {},
+        manifestHash: opts.manifestHash,
+    };
+    existing.version = opts.version;
+    existing.source = opts.source;
+    existing.installedAt = new Date().toISOString();
+    existing.deployedTo[provider] = counts;
+    if (opts.manifestHash)
+        existing.manifestHash = opts.manifestHash;
+    if (opts.source === 'project-local') {
+        existing.localPath = opts.localPath;
+        existing.localType = opts.localType;
+        if (opts.manifestVersion)
+            existing.manifestVersion = opts.manifestVersion;
+        if (opts.artifactHashes)
+            existing.artifactHashes = opts.artifactHashes;
+    }
+    else {
+        // Clear stale project-local fields if a previously project-local entry is
+        // being overwritten by a non-project-local source.
+        delete existing.localPath;
+        delete existing.localType;
+        delete existing.manifestVersion;
+        delete existing.artifactHashes;
+    }
+    config.installed[name] = existing;
+    return config;
+}
+/**
+ * Aggregate deployment counts across all installed frameworks for a given provider.
+ * Returns the totals for agents, commands, skills, and rules.
+ * If no provider is specified, uses the first configured provider.
+ */
+export function getDeploymentSummary(config, provider) {
+    const targetProvider = provider ?? config.providers[0] ?? 'claude';
+    const totals = { agents: 0, commands: 0, skills: 0, rules: 0 };
+    for (const entry of Object.values(config.installed)) {
+        const counts = entry.deployedTo[targetProvider];
+        if (!counts)
+            continue;
+        totals.agents += counts.agents;
+        totals.commands += counts.commands;
+        totals.skills += counts.skills;
+        totals.rules += counts.rules;
+    }
+    return totals;
+}
+/**
+ * Compute SHA-256 hash of a manifest.json file.
+ * Returns undefined if the file cannot be read.
+ */
+export async function hashManifest(manifestPath) {
+    try {
+        const content = await readFile(manifestPath, 'utf-8');
+        return 'sha256:' + createHash('sha256').update(content).digest('hex');
+    }
+    catch {
+        return undefined;
+    }
+}
+function getProviderDeployDirs(provider, projectDir) {
+    const artifacts = getProviderDefinition(provider)?.paths.artifacts;
+    if (!artifacts)
+        return null;
+    return {
+        agents: resolveProviderPathValue(artifacts.agents, projectDir),
+        skills: resolveProviderPathValue(artifacts.skills, projectDir),
+        commands: resolveProviderPathValue(artifacts.commands, projectDir),
+        rules: resolveProviderPathValue(artifacts.rules, projectDir),
+    };
+}
+/**
+ * Count .md files or subdirectories in a deployment directory.
+ * Returns 0 if the directory does not exist.
+ */
+async function countDeployedInDir(projectDir, relOrAbsDir, mode) {
+    if (!relOrAbsDir)
+        return 0;
+    const dir = isAbsolute(relOrAbsDir) ? relOrAbsDir : resolve(projectDir, relOrAbsDir);
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        if (mode === 'md')
+            return entries.filter(e => e.isFile() && e.name.endsWith('.md')).length;
+        return entries.filter(e => e.isDirectory()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Scan actual deployment directories and populate `deployedTo` for any
+ * `installed` entries that have an empty `deployedTo` map.
+ *
+ * Called by `aiwg init` when migrating a project that already has frameworks
+ * deployed but whose config was created before deployment-tracking was added.
+ *
+ * @implements #721
+ */
+export async function populateDeployedTo(config, projectDir) {
+    const entriesNeedingPopulation = Object.entries(config.installed).filter(([, entry]) => Object.keys(entry.deployedTo).length === 0);
+    if (entriesNeedingPopulation.length === 0)
+        return config;
+    for (const provider of config.providers) {
+        const dirs = getProviderDeployDirs(provider, projectDir);
+        if (!dirs)
+            continue;
+        const counts = {
+            agents: await countDeployedInDir(projectDir, dirs.agents, 'md'),
+            commands: await countDeployedInDir(projectDir, dirs.commands, 'md'),
+            skills: await countDeployedInDir(projectDir, dirs.skills, 'dirs'),
+            rules: await countDeployedInDir(projectDir, dirs.rules, 'md'),
+        };
+        // Only populate if at least one artifact type is present
+        if (counts.agents + counts.commands + counts.skills + counts.rules === 0)
+            continue;
+        for (const [name, entry] of entriesNeedingPopulation) {
+            if (Object.keys(entry.deployedTo).length === 0) {
+                entry.deployedTo[provider] = counts;
+                config.installed[name] = entry;
+            }
+        }
+    }
+    return config;
+}
+//# sourceMappingURL=aiwg-config.js.map