@aiwg/cli 2026.9.18 → 2026.9.20

package/dist/src/api/index.d.ts

@@ -24,6 +24,7 @@ export * from '../writing/contextual-diagnostics.js';
 export * from '../schema/index.js';
 export * from '../dataset/index.js';
 export * from '../network-analysis/index.js';
+export * from '../decision/index.js';
 export { ARTIFACT_TRUST_ROOT_MEDIA_TYPE, ARTIFACT_TRUST_ROOT_SCHEMA_VERSION, ARTIFACT_TRUST_STATE_SCHEMA_VERSION, bootstrapTrustRoot, parseTrustRoot, parseTrustState, readTrustState, validateTrustRoot, validateTrustState, verifyRootTransition, writeTrustState, channelStateKey, canonicalJson, dssePae, publicKeyFingerprint, sha256, type ArtifactTrustRoot, type ArtifactTrustState, type RootBootstrapResult, type RootTransitionResult, type ArtifactTrustPolicySettings, type TrustedChannelState, } from '../security/artifact-trust.js';
 export * from '../writing/writer-profile.js';
 export * from '../writing/writer-profile-store.js';

package/dist/src/api/index.js

@@ -24,6 +24,7 @@ export * from '../writing/contextual-diagnostics.js';
 export * from '../schema/index.js';
 export * from '../dataset/index.js';
 export * from '../network-analysis/index.js';
+export * from '../decision/index.js';
 export { ARTIFACT_TRUST_ROOT_MEDIA_TYPE, ARTIFACT_TRUST_ROOT_SCHEMA_VERSION, ARTIFACT_TRUST_STATE_SCHEMA_VERSION, bootstrapTrustRoot, parseTrustRoot, parseTrustState, readTrustState, validateTrustRoot, validateTrustState, verifyRootTransition, writeTrustState, channelStateKey, canonicalJson, dssePae, publicKeyFingerprint, sha256, } from '../security/artifact-trust.js';
 export * from '../writing/writer-profile.js';
 export * from '../writing/writer-profile-store.js';

package/dist/src/artifacts/index-builder.js

@@ -13,6 +13,8 @@ import fs from 'fs';
 import path from 'path';
 import { createHash } from 'crypto';
 import { load as loadYaml } from 'js-yaml';
+import { validateDecisionDocument } from '../decision/validate.js';
+import { parseDecisionJson, parseDecisionYaml } from '../decision/entry.js';
 import { DEFAULT_INDEX_EXTENSIONS, INDEX_EXTRACTOR_VERSION, INDEX_VERSION, INDEX_DIR, OPERATIONAL_DISCOVERY_TYPES, PHASE_DIRECTORIES, GRAPH_CONFIGS, TEMPLATE_INDEX_EXTENSIONS, resolveGraphScanDir, loadUserGraphConfigs, loadGlobalGraphConfigs, } from './types.js';
 import { parseCitationSidecar, citationResultToEdges, buildRefToPathMap } from './citation-parser.js';
 import { writeIndexFile, resolveIndexDir, loadGraphIndexFile } from './index-reader.js';
@@ -163,6 +165,38 @@ function extractSummary(data, body) {
     const lines = body.split('\n').filter(l => l.trim() && !l.startsWith('#'));
     return lines.slice(0, 5).join(' ').slice(0, 500).trim();
 }
+/** Classify and schema-check authored decision-system documents. */
+export function parseDecisionDoc(content, relativePath) {
+    if (!/\.(json|ya?ml)$/i.test(relativePath))
+        return null;
+    if (Buffer.byteLength(content, 'utf8') > 262_144)
+        return null;
+    let document;
+    try {
+        document = /\.json$/i.test(relativePath) ? parseDecisionJson(content) : parseDecisionYaml(content);
+        validateDecisionDocument(document);
+    }
+    catch {
+        return null;
+    }
+    const value = document;
+    if (!['DecisionDefinition', 'DecisionRuleset', 'DecisionBinding'].includes(value.kind))
+        return null;
+    const type = {
+        DecisionDefinition: 'decision-definition',
+        DecisionRuleset: 'decision-ruleset',
+        DecisionBinding: 'decision-binding',
+    }[value.kind];
+    const purpose = typeof value.spec.purpose === 'string' ? value.spec.purpose : value.metadata.description;
+    const terms = new Set([
+        value.kind, value.metadata.id, value.metadata.version, purpose,
+        ...Object.keys(value.spec),
+    ]);
+    return {
+        type, kind: value.kind, name: value.metadata.id, description: value.metadata.description,
+        capability: purpose.slice(0, 240), tags: ['decision-system', value.kind], searchTerms: [...terms],
+    };
+}
 function parseSchemaDoc(content, relativePath) {
     if (!/\.(json|ya?ml)$/i.test(relativePath))
         return null;
@@ -929,15 +963,16 @@ export async function buildIndex(cwd, options = {}) {
             // markdown+frontmatter — detect them up front so they classify and
             // become discoverable (#1540).
             const flow = parseFlowDoc(content, relativePath);
+            const decision = flow ? null : parseDecisionDoc(content, relativePath);
             const inferredType = inferType(data, relativePath);
             const physicalType = inferType({ ...data, type: undefined }, relativePath);
-            const runbook = flow ? null : parseRunbookDoc(data, body, relativePath);
+            const runbook = flow || decision ? null : parseRunbookDoc(data, body, relativePath);
             const schemaDoc = inferredType === 'schema' ? parseSchemaDoc(content, relativePath) : null;
-            const title = flow?.name ?? schemaDoc?.title ?? extractTitle(data, body);
+            const title = flow?.name ?? decision?.name ?? schemaDoc?.title ?? extractTitle(data, body);
             const phase = typeof data.phase === 'string' ? data.phase : inferPhase(relativePath);
-            const type = flow?.type ?? (runbook ? 'runbook' : inferredType);
-            const tags = flow ? flow.tags : (Array.isArray(data.tags) ? data.tags.map(String) : []);
-            const summary = flow?.description ?? schemaDoc?.capability ?? runbook?.capability ?? extractSummary(data, body);
+            const type = flow?.type ?? decision?.type ?? (runbook ? 'runbook' : inferredType);
+            const tags = flow?.tags ?? decision?.tags ?? (Array.isArray(data.tags) ? data.tags.map(String) : []);
+            const summary = flow?.description ?? decision?.description ?? schemaDoc?.capability ?? runbook?.capability ?? extractSummary(data, body);
             const dependencies = extractMentions(content);
             const markdownLinks = extractMarkdownLinks(content);
             // Discovery metadata (#1214, #1540, #1792) — meaningful for operational
@@ -947,10 +982,10 @@ export async function buildIndex(cwd, options = {}) {
             // Declarative processes have no trigger phrases — they rely on their
             // capability and structure-aware search terms.
             const triggers = isDiscoverable && !flow ? extractTriggers(body, data) : undefined;
-            const capability = flow?.capability ?? schemaDoc?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
-            const kind = flow?.kind ?? runbook?.kind;
+            const capability = flow?.capability ?? decision?.capability ?? schemaDoc?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
+            const kind = flow?.kind ?? decision?.kind ?? runbook?.kind;
             const sourceType = runbook && physicalType !== 'runbook' ? physicalType : undefined;
-            const searchTerms = flow?.searchTerms ?? schemaDoc?.searchTerms ?? runbook?.searchTerms;
+            const searchTerms = flow?.searchTerms ?? decision?.searchTerms ?? schemaDoc?.searchTerms ?? runbook?.searchTerms;
             const kernel = data.kernel === true || data.kernel === 'true' ? true : undefined;
             // Script entrypoint metadata is meaningful for skills only (#1227).
             const script = type === 'skill' ? extractSkillScript(data) : undefined;
@@ -959,7 +994,7 @@ export async function buildIndex(cwd, options = {}) {
             // Canonical short name (#1233) — used by the scorer to floor exact-name
             // queries to 1.0 so hyphenated kernel-skill names like `aiwg-doctor`
             // remain searchable even when the rendered title strips the hyphen.
-            const name = flow ? flow.name : schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
+            const name = flow?.name ?? decision?.name ?? schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
             entry = {
                 path: relativePath,
                 type,

package/dist/src/artifacts/query-engine.js

@@ -1549,6 +1549,9 @@ async function findCorpusArtifact(aiwgRoot, name, typeFilter) {
         { sub: 'behaviors', type: 'behavior', layout: 'flat' },
         { sub: 'flows', type: 'flow', layout: 'flat' },
         { sub: 'runbooks', type: 'runbook', layout: 'flat' },
+        { sub: 'decisions', type: 'decision-definition', layout: 'flat', extension: '.json' },
+        { sub: 'rulesets', type: 'decision-ruleset', layout: 'flat', extension: '.json' },
+        { sub: 'bindings', type: 'decision-binding', layout: 'flat', extension: '.json' },
     ];
     for (const group of groups) {
         let bundles;
@@ -1566,7 +1569,7 @@ async function findCorpusArtifact(aiwgRoot, name, typeFilter) {
                     continue;
                 const candidate = t.layout === 'slug'
                     ? path.join(group.dir, bundle, t.sub, name, 'SKILL.md')
-                    : path.join(group.dir, bundle, t.sub, `${name}.md`);
+                    : path.join(group.dir, bundle, t.sub, `${name}${t.extension ?? '.md'}`);
                 try {
                     const stat = await fsp.stat(candidate);
                     if (stat.isFile()) {

package/dist/src/artifacts/types.js

@@ -25,6 +25,9 @@ export const OPERATIONAL_DISCOVERY_TYPES = [
     'command',
     'rule',
     'schema',
+    'decision-definition',
+    'decision-ruleset',
+    'decision-binding',
     'flow',
     'runbook',
     'template',

package/dist/src/cli/handlers/bot-handoff.js

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { renderBotHandoff } from '../../providers/bot-handoff.js';
+import { providerCommandOptions } from './provider-command-options.js';
+export const botHandoffHandler = {
+    id: 'bot-handoff', name: 'Bot Handoff', category: 'utility', aliases: [],
+    description: 'Generate provider-aware review drafts and let the selected provider handle native execution',
+    async help() {
+        return { exitCode: 0, rawOutput: true, message: [
+                'aiwg bot-handoff --input <proposal.json> [--provider <id>] [--dry-run]',
+                'Supports every registered provider. Uses the active provider if unambiguous; specify --provider in CI.',
+                'Prints a Markdown review draft to stdout. Does not write provider state or call a product API.',
+                'Fields: surface (routines|teammates|connectors|memory), name, summary (max 280 characters), references (1–10 pointers).',
+                'Routines also require schedule and timezone. Use an IANA timezone, e.g. America/New_York.',
+                'References: file paths, HTTP(S) URLs without credentials/query/fragment, or aiwg show pointers.',
+                'Only the supplied JSON is read. Referenced sources are never read or executed. Do not include secrets.',
+                'See docs/integrations/bot-handoff.md for examples and artifact export.',
+            ].join('\n') };
+    },
+    async execute(ctx) {
+        try {
+            const { provider, flags } = await providerCommandOptions(ctx.args.filter(arg => arg !== '--dry-run'), ctx.cwd, ['--input']);
+            if (!flags['--input'])
+                throw new Error('Input is required');
+            const source = await readFile(path.resolve(ctx.cwd, flags['--input']), 'utf8');
+            if (Buffer.byteLength(source) > 16_384)
+                throw new Error('Proposal too large');
+            return { exitCode: 0, rawOutput: true, message: renderBotHandoff(JSON.parse(source), provider) };
+        }
+        catch {
+            return { exitCode: 1, message: 'Cannot generate handoff: select a registered --provider and check the proposal file/options with --help. Input content is omitted.' };
+        }
+    },
+};
+//# sourceMappingURL=bot-handoff.js.map

package/dist/src/cli/handlers/build-verify.js

@@ -0,0 +1,50 @@
+import { providerCommandOptions } from './provider-command-options.js';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { verifyProviderDeployment } from '../services/deployment-verification.js';
+export const buildVerifyHandler = {
+    id: 'build-verify', name: 'Build Verification', category: 'utility', aliases: [],
+    description: 'Verify AIWG deployment before a provider runs a build or CI task',
+    async help() {
+        return { exitCode: 0, rawOutput: true, message: [
+                'aiwg build-verify [--provider <id>]',
+                'Run from the project root. Uses the shared provider deployment, registry, context and discovery checks.',
+                'Uses the active provider if unambiguous; specify --provider in CI.',
+                'Documented native inspection is required when the provider adapter supports it.',
+                'Other providers report deployment-only verification; no native execution or model compliance is claimed.',
+                'Prints JSON and fails for missing deployment or blocking findings. Does not run build commands or inference.',
+                'See docs/integrations/build-verify.md.',
+            ].join('\n') };
+    },
+    async execute(ctx) {
+        try {
+            if (ctx.dryRun)
+                throw new Error('Verification is already read-only');
+            const { provider } = await providerCommandOptions(ctx.args, ctx.cwd);
+            const config = await readAiwgConfig(ctx.cwd);
+            const bundles = Object.entries(config?.installed ?? {})
+                .filter(([, bundle]) => Boolean(bundle.deployedTo?.[provider.id])).map(([name]) => name);
+            if (!bundles.length) {
+                return { exitCode: 1, rawOutput: true, message: JSON.stringify({
+                        schema: 'aiwg.build.verify.v1', provider: provider.id, status: 'failed',
+                        message: `No project deployment recorded. Run aiwg use all --provider ${provider.id} --scope project first.`,
+                    }) };
+            }
+            const result = await verifyProviderDeployment({
+                projectRoot: ctx.cwd, frameworkRoot: ctx.frameworkRoot, provider: provider.id,
+                scope: 'project', requestedBundles: bundles, requireNativeInspection: true,
+            });
+            const failed = result.findings.some(finding => finding.severity === 'blocking');
+            return { exitCode: failed ? 1 : 0, rawOutput: true, message: JSON.stringify({
+                    schema: 'aiwg.build.verify.v1', provider: provider.id,
+                    status: failed ? 'failed' : 'ready', verification: result.verificationLevel,
+                    restartRequired: result.restartRequired, restartAction: result.restartAction,
+                    // Do not echo raw provider output or configuration values into CI logs.
+                    findings: result.findings.map(({ id, severity, message, remediation }) => ({ id, severity, message, remediation })),
+                }, null, 2) };
+        }
+        catch {
+            return { exitCode: 1, message: 'Cannot verify build readiness. Select a registered --provider, check project configuration, and see build-verify --help.' };
+        }
+    },
+};
+//# sourceMappingURL=build-verify.js.map

package/dist/src/cli/handlers/index.js

@@ -65,6 +65,8 @@ import { evidenceHandler } from './evidence.js';
 import { artifactVerifyHandler } from './artifact-verify.js';
 import { writingHandler } from './writing.js';
 import { writerProfileHandler } from './writer-profile.js';
+import { botHandoffHandler } from './bot-handoff.js';
+import { buildVerifyHandler } from './build-verify.js';
 import { outputModeHandler } from './output-mode.js';
 import { installationHandler } from './installation.js';
 import { uhpHandler } from './uhp.js';
@@ -75,7 +77,7 @@ export {
 // Maintenance
 helpHandler, versionHandler, authHandler, doctorHandler, contextFirewallHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, writerProfileHandler, writingHandler, schemaHandler, datasetHandler, installationHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, writerProfileHandler, botHandoffHandler, buildVerifyHandler, writingHandler, schemaHandler, datasetHandler, installationHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -161,6 +163,8 @@ export const allHandlers = [
     artifactVerifyHandler,
     outputModeHandler,
     writerProfileHandler,
+    botHandoffHandler,
+    buildVerifyHandler,
     writingHandler,
     schemaHandler,
     datasetHandler,

package/dist/src/cli/handlers/provider-command-options.js

@@ -0,0 +1,24 @@
+import { getProviderDefinition } from '../../providers/provider-definitions.js';
+import { resolveActiveProvider } from '../provider-resolution.js';
+/** Shared strict provider selection for commands that act on one provider. */
+export async function providerCommandOptions(args, cwd, valueFlags = []) {
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (![...valueFlags, '--provider'].includes(flag) || flags[flag] !== undefined)
+            throw new Error('Unknown or duplicate option');
+        const value = args[++i];
+        if (!value || value.startsWith('--'))
+            throw new Error('Missing option value');
+        flags[flag] = value;
+    }
+    // resolveActiveProvider falls back for unknown explicit IDs; commands must not.
+    if (flags['--provider'] && !getProviderDefinition(flags['--provider']))
+        throw new Error('Unknown provider');
+    const resolved = await resolveActiveProvider({ cwd, explicitProvider: flags['--provider'] });
+    const provider = resolved.provider && getProviderDefinition(resolved.provider);
+    if (!provider)
+        throw new Error('Select one provider with --provider');
+    return { provider, flags };
+}
+//# sourceMappingURL=provider-command-options.js.map

package/dist/src/cli/services/deployment-verification.js

@@ -347,6 +347,7 @@ async function collectRegistryFindings(options, provider, actualCounts) {
     return findings;
 }
 export async function verifyProviderDeployment(options) {
+    let verificationLevel = 'deployment';
     const normalized = normalizeProviderDefinitionId(options.provider) ?? options.provider;
     const definition = getProviderDefinition(normalized);
     const findings = [];
@@ -462,19 +463,19 @@ export async function verifyProviderDeployment(options) {
             const inspect = runGrokInspect({
                 cwd: options.projectRoot,
                 expected: {
-                    instructionPaths: ['AGENTS.md'],
-                    skillNames: expectedSkillNames.slice(0, 32),
+                    instructionPaths: options.requireNativeInspection ? [path.join(options.projectRoot, 'AGENTS.md')] : ['AGENTS.md'],
+                    skillNames: options.requireNativeInspection ? expectedSkillNames : expectedSkillNames.slice(0, 32),
                 },
             });
             if (inspect.status === 'absent') {
-                findings.push(finding(normalized, 'grok-inspect-absent', 'advisory', 'Grok Build CLI (`grok`) is not on PATH; skipped `grok inspect`.', inspect.remediation, { grokHome: resolveGrokHome(), cwd: options.projectRoot }));
+                findings.push(finding(normalized, 'grok-inspect-absent', options.requireNativeInspection ? 'blocking' : 'advisory', 'Grok Build CLI (`grok`) is not on PATH; skipped `grok inspect`.', inspect.remediation, { grokHome: resolveGrokHome(), cwd: options.projectRoot }));
             }
             else if (inspect.status === 'failed') {
                 const mismatchSummary = (inspect.mismatches ?? [])
                     .slice(0, 8)
                     .map((item) => `${item.kind}:${item.expected}`)
                     .join('; ');
-                findings.push(finding(normalized, 'grok-inspect-failed', 'advisory', mismatchSummary
+                findings.push(finding(normalized, 'grok-inspect-failed', options.requireNativeInspection ? 'blocking' : 'advisory', mismatchSummary
                     ? `\`grok inspect\` did not confirm expected AIWG artifacts (${mismatchSummary}).`
                     : `\`grok inspect\` exited ${inspect.exitCode ?? 'unknown'}.`, 'Fix the Grok Build installation or redeploy, then re-run aiwg status --probe or aiwg use for grok-build.', {
                     exitCode: inspect.exitCode,
@@ -484,11 +485,12 @@ export async function verifyProviderDeployment(options) {
                 }));
             }
             else {
+                verificationLevel = 'native-inspection';
                 findings.push(finding(normalized, 'grok-inspect-ok', 'info', '`grok inspect` confirmed expected AIWG artifacts in the deployment target.', 'No action required; restart the Grok Build session if newly deployed skills are not visible.', {
                     binary: inspect.binary,
                     cwd: inspect.cwd,
                     parsedKeys: Object.keys(inspect.parsed).slice(0, 20),
-                    checkedSkills: expectedSkillNames.slice(0, 32),
+                    checkedSkills: options.requireNativeInspection ? expectedSkillNames : expectedSkillNames.slice(0, 32),
                 }));
             }
         }
@@ -599,6 +601,7 @@ export async function verifyProviderDeployment(options) {
     ];
     return {
         provider: normalized,
+        verificationLevel,
         scope: options.scope,
         outcome,
         restartRequired,