@aiwg/cli 2026.9.24 → 2026.10.1

package/agentic/code/providers/capability-matrix.yaml

@@ -488,12 +488,13 @@ providers:
 
   muse:
     display_name: Muse Code
-    status: experimental
+    status: stable
     # Meta's terminal/CI coding agent (Muse Spark-powered). Explicitly not a
     # model-API surface: Glimmer/Image/Voice are out of scope.
     # Skill writer (.agents/skills + XDG user root), discover-first AGENTS.md
     # bridge, managed .muse/hooks.json, and opt-in MCP settings profile.
     # ADR: docs/architecture/adr-muse-provider-target.md · epic #223.
+    # #231: promoted stable — Linux PUW + security review; maintainer Linux-only waiver 2026-10-02.
     daemon_tier: unsupported
     daemon_pty_adapter: false
     artifact_paths:

package/dist/src/artifacts/discovery-shadow-evaluator.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { types as utilTypes } from 'node:util';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { admitEntry } from '../decision/entry.js';
+import { evaluateDecisionRuleset } from '../decision/evaluate.js';
+import { validateProjectionPolicy } from '../decision/projection.js';
+import { artifactPin, assertArtifactPin, validateAgainstSchema, validateBinding, validateDefinition, validateRuleset } from '../decision/validate.js';
+const hash = (value) => `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+const pinEqual = (a, b) => canonicalJson(a) === canonicalJson(b);
+const validPin = (pin) => Boolean(pin?.id && pin.version && /^sha256:[a-f0-9]{64}$/.test(pin.digest));
+const requestFields = ['query', 'candidates', 'options', 'definition', 'binding'];
+/** Strip only the trusted cancellation handle; reject accessors/proxies before reading data. */
+function payloadOf(request) {
+    if (!request || typeof request !== 'object' || utilTypes.isProxy(request)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(request)))
+        throw new Error('Invalid shadow request');
+    const descriptors = Object.getOwnPropertyDescriptors(request);
+    if (Reflect.ownKeys(request).some(key => typeof key !== 'string' || ![...requestFields, 'signal'].includes(key))) {
+        throw new Error('Unsupported shadow request field');
+    }
+    const data = {};
+    for (const key of requestFields) {
+        const descriptor = descriptors[key];
+        if (!descriptor || !('value' in descriptor) || !descriptor.enumerable)
+            throw new Error('Invalid shadow request field');
+        data[key] = descriptor.value;
+    }
+    admitEntry(data);
+    return structuredClone(data);
+}
+/** Concrete Decision runtime bridge, deliberately without an executor or transport shortcut.
+ * It supports one pinned option cardinality, one evaluation and one non-retrying target.
+ * Other candidate cardinalities fail closed and retain deterministic discovery. */
+export class DiscoveryShadowEvaluator {
+    profile;
+    calibration;
+    scheduler;
+    runtime;
+    registry;
+    alias;
+    options;
+    profileDigest;
+    constructor(config) {
+        const profile = { shadowPolicy: config.shadowPolicy, definition: config.definition, ruleset: config.ruleset, binding: config.binding,
+            projectionPolicy: config.projectionPolicy, policyPin: config.policyPin, receiptProjectId: config.receiptProjectId,
+            runId: config.runId, invocationScope: config.invocationScope };
+        admitEntry(profile);
+        this.profile = structuredClone(profile);
+        const p = this.profile;
+        validateDefinition(p.definition);
+        validateRuleset(p.ruleset);
+        validateBinding(p.binding, p.ruleset);
+        assertArtifactPin(p.definition, p.shadowPolicy.definition, 'discovery definition');
+        assertArtifactPin(p.binding, p.shadowPolicy.binding, 'discovery binding');
+        if (![p.runId, p.invocationScope, p.receiptProjectId].every(value => typeof value === 'string' && value.trim())
+            || !validPin(p.policyPin) || p.ruleset.spec.evaluations.length !== 1 || p.definition.spec.answer.kind !== 'choice') {
+            throw new Error('Shadow evaluator requires an identified single Choice profile');
+        }
+        if (!Number.isSafeInteger(p.shadowPolicy.ambiguity.maximumCandidates) || p.shadowPolicy.ambiguity.maximumCandidates < 1
+            || p.shadowPolicy.ambiguity.maximumCandidates > 100 || !Number.isSafeInteger(p.shadowPolicy.ambiguity.maximumTextBytes)
+            || p.shadowPolicy.ambiguity.maximumTextBytes < 1 || p.shadowPolicy.ambiguity.maximumTextBytes > 1_000_000
+            || !Number.isSafeInteger(p.shadowPolicy.maximumLatencyMs) || p.shadowPolicy.maximumLatencyMs < 1
+            || !Number.isSafeInteger(p.shadowPolicy.maximumTokens) || p.shadowPolicy.maximumTokens < 1
+            || !Number.isFinite(p.shadowPolicy.maximumCostUsd) || p.shadowPolicy.maximumCostUsd < 0) {
+            throw new Error('Invalid bounded shadow profile');
+        }
+        if (p.projectionPolicy.fields.length !== 2
+            || canonicalJson(p.projectionPolicy.fields.map(field => field.output).sort()) !== canonicalJson(['candidates', 'query'])
+            || p.projectionPolicy.fields.some(field => field.trust !== 'untrusted' || field.pointer !== `/${field.output}`)) {
+            throw new Error('Discovery query and candidates require the untrusted D10 projection');
+        }
+        const evaluation = p.ruleset.spec.evaluations[0];
+        this.alias = evaluation.alias;
+        if (evaluation.inputPointer !== '' || !pinEqual(evaluation.decision, artifactPin(p.definition)))
+            throw new Error('Shadow evaluation definition mismatch');
+        this.options = p.definition.spec.answer.options.map(option => option.id);
+        const candidates = this.options.slice(0, -1);
+        if (candidates.length < 1 || candidates.length > p.shadowPolicy.ambiguity.maximumCandidates
+            || this.options.at(-1) !== 'none' || candidates.some((id, i) => id !== `candidate_${i}`))
+            throw new Error('Invalid pinned shadow option domain');
+        const binding = p.binding.spec.evaluations[this.alias];
+        const target = binding.targets[0];
+        if (binding.targets.length !== 1 || binding.fallbackOn.length || target.retry.maxRetries !== 0
+            || p.binding.spec.maxAttempts !== 1 || p.binding.spec.concurrency !== 1
+            || p.binding.spec.totalTimeoutMs > p.shadowPolicy.maximumLatencyMs || target.timeoutMs > p.shadowPolicy.maximumLatencyMs
+            || target.acceptance.mode !== 'primitive-policy'
+            || !target.acceptance.compatibleUncertaintyProfiles.includes(p.shadowPolicy.uncertaintyProfile)) {
+            throw new Error('Shadow evaluator requires bounded single-target primitive acceptance');
+        }
+        if (!config.scheduler.enabled || !config.scheduler.estimate)
+            throw new Error('Shadow evaluator requires existing admission and cost/token estimates');
+        const { estimate, onEvidence, ...schedulerData } = config.scheduler;
+        admitEntry(schedulerData);
+        this.scheduler = { ...structuredClone(schedulerData), estimate, ...(onEvidence ? { onEvidence } : {}) };
+        // Shared host limits may be broader than this observer's per-invocation budget.
+        // Narrow every admission scope before resolution/dispatch, preserving stricter limits.
+        const bounded = (limits) => ({ ...limits,
+            maxTokens: Math.min(limits.maxTokens ?? p.shadowPolicy.maximumTokens, p.shadowPolicy.maximumTokens),
+            maxCostUsd: Math.min(limits.maxCostUsd ?? p.shadowPolicy.maximumCostUsd, p.shadowPolicy.maximumCostUsd),
+            allowUnknownCost: false,
+        });
+        this.scheduler.workspace.limits = bounded(this.scheduler.workspace.limits);
+        this.scheduler.principal.limits = bounded(this.scheduler.principal.limits);
+        this.scheduler.providers = Object.fromEntries(Object.entries(this.scheduler.providers).map(([id, limits]) => [id, bounded(limits)]));
+        admitEntry(config.calibration.artifact);
+        this.calibration = structuredClone(config.calibration.artifact);
+        this.registry = config.calibration.registry;
+        const registered = this.registry.artifactHistory().find(item => item.id === this.calibration.id);
+        const identity = this.calibration.identity;
+        if (!registered || hash(registered) !== hash(this.calibration) || this.calibration.digest !== p.shadowPolicy.calibrationDigest
+            || identity.definitionDigest !== artifactPin(p.definition).digest || identity.primitive !== 'choice'
+            || identity.provider !== target.adapter || identity.adapterVersion !== target.adapterVersion
+            || !p.shadowPolicy.allowedModels.includes(identity.actualModel))
+            throw new Error('Shadow calibration is not the registered pinned profile');
+        this.runtime = { adapters: { ...config.adapters }, resolveCredential: config.resolveCredential, receiptStore: config.receiptStore,
+            record: config.record, ...(config.now ? { now: config.now } : {}), ...(config.onProjectionEvidence ? { onProjectionEvidence: config.onProjectionEvidence } : {}) };
+        this.profileDigest = hash({ profile: p, calibration: this.calibration.digest, scheduler: schedulerData });
+    }
+    authorize(request) {
+        try {
+            this.checkedPayload(request);
+            validateProjectionPolicy(this.profile.projectionPolicy);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    record(receipt) { this.runtime.record(structuredClone(receipt)); }
+    async evaluate(request) {
+        const payload = this.checkedPayload(request);
+        const descriptor = Object.getOwnPropertyDescriptor(request, 'signal');
+        if (!descriptor || !('value' in descriptor) || !(descriptor.value instanceof AbortSignal))
+            throw new Error('Shadow evaluation requires a cancellation signal');
+        const signal = descriptor.value;
+        if (signal.aborted)
+            throw new Error('Shadow evaluation cancelled');
+        const p = this.profile;
+        const input = { query: payload.query, candidates: payload.candidates };
+        const invocationId = `discovery-shadow:${hash({ scope: p.invocationScope, profile: this.profileDigest, input }).slice(7)}`;
+        const evaluated = await evaluateDecisionRuleset({
+            ruleset: structuredClone(p.ruleset), binding: structuredClone(p.binding), definitions: { [p.definition.metadata.id]: structuredClone(p.definition) },
+            input, runId: p.runId, invocationId, signal, adapters: this.runtime.adapters, resolveCredential: this.runtime.resolveCredential,
+            receiptStore: this.runtime.receiptStore, receiptProjectId: p.receiptProjectId, policyPin: p.policyPin,
+            calibrationPin: { id: this.calibration.id, version: this.calibration.identity.calibrator.version, digest: this.calibration.digest },
+            calibrationCompatibility: { registry: this.registry, calibrationArtifactId: this.calibration.id,
+                policy: { unknown: 'defer', incompatible: 'fail', shadowRequired: 'shadow', unusableCalibration: 'require-approval' },
+                identityFor: ({ actualModel }) => ({ ...structuredClone(this.calibration.identity), actualModel }) },
+            projection: { resolve: () => structuredClone(p.projectionPolicy), ...(this.runtime.onProjectionEvidence ? { onEvidence: this.runtime.onProjectionEvidence } : {}) },
+            scheduler: this.scheduler, ...(this.runtime.now ? { now: this.runtime.now } : {}),
+        });
+        const receipt = await this.runtime.receiptStore.read(invocationId, p.receiptProjectId);
+        const decision = evaluated.spec.evaluations[this.alias];
+        if (!receipt || receipt.state !== 'completed' || !receipt.result || !decision
+            || !receipt.evaluations[this.alias] || hash(receipt.result) !== hash(evaluated) || hash(receipt.evaluations[this.alias]) !== hash(decision)) {
+            throw new Error('Shadow evaluation has no verified terminal receipt');
+        }
+        return { result: structuredClone(decision), receiptDigest: hash(receipt) };
+    }
+    checkedPayload(request) {
+        const payload = payloadOf(request);
+        const p = this.profile;
+        if (p.shadowPolicy.mode !== 'shadow' || !pinEqual(payload.definition, p.shadowPolicy.definition) || !pinEqual(payload.binding, p.shadowPolicy.binding)
+            || canonicalJson(payload.options) !== canonicalJson(this.options) || !Array.isArray(payload.candidates)
+            || payload.candidates.length !== this.options.length - 1 || typeof payload.query !== 'string' || !payload.query.trim()
+            || payload.candidates.some((c, i) => !c || c.option !== this.options[i] || Object.keys(c).sort().join(',') !== 'capability,id,name,option,type'
+                || [c.id, c.name, c.type, c.capability].some(value => typeof value !== 'string') || !c.id)
+            || new Set(payload.candidates.map(c => c.id)).size !== payload.candidates.length
+            || Buffer.byteLength(canonicalJson({ query: payload.query, candidates: payload.candidates })) > p.shadowPolicy.ambiguity.maximumTextBytes) {
+            throw new Error('Shadow request does not match pinned bounded domain');
+        }
+        validateAgainstSchema(p.ruleset.spec.inputSchema, { query: payload.query, candidates: payload.candidates }, 'shadow input');
+        validateAgainstSchema(p.definition.spec.inputSchema, { query: payload.query, candidates: payload.candidates }, 'shadow input');
+        return payload;
+    }
+}
+//# sourceMappingURL=discovery-shadow-evaluator.js.map

package/dist/src/artifacts/discovery-shadow.js

@@ -0,0 +1,195 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../security/artifact-trust.js';
+const finite = (n) => Number.isFinite(n) && n >= 0;
+function validatePolicy(policy) {
+    if (policy.version !== 'discovery-ambiguity/v1' || !finite(policy.minimumScore)
+        || !Number.isFinite(policy.minimumMargin) || policy.minimumMargin <= 0
+        || !Number.isSafeInteger(policy.maximumCandidates) || policy.maximumCandidates < 1 || policy.maximumCandidates > 100
+        || !Number.isSafeInteger(policy.maximumTextBytes) || policy.maximumTextBytes < 1 || policy.maximumTextBytes > 1_000_000) {
+        throw new Error('Invalid discovery ambiguity policy');
+    }
+}
+/** Retrieval order is authoritative, including ties; this function never sorts it. */
+export function discoveryAmbiguity(query, candidates, policy) {
+    validatePolicy(policy);
+    const answer = (reason, eligible = false) => ({ version: policy.version, eligible, reason });
+    if (typeof query !== 'string' || !query.trim() || !Array.isArray(candidates)
+        || candidates.some(c => !c || typeof c.id !== 'string' || !c.id || typeof c.name !== 'string'
+            || typeof c.type !== 'string' || typeof c.capability !== 'string' || !finite(c.score))
+        || new Set(candidates.map(c => c.id)).size !== candidates.length
+        || candidates.some((c, i) => i > 0 && c.score > candidates[i - 1].score)
+        || Buffer.byteLength(query + candidates.map(c => c.name + c.type + c.capability + c.id).join('')) > policy.maximumTextBytes) {
+        return answer('invalid-input');
+    }
+    if (!candidates.length)
+        return answer('no-candidates');
+    const normalized = query.trim().toLowerCase();
+    if (candidates.some(c => c.name.trim().toLowerCase() === normalized || c.id.toLowerCase() === normalized))
+        return answer('exact-name');
+    const first = candidates[0];
+    if (first.score < policy.minimumScore)
+        return answer('low-score', true);
+    const margin = first.score - (candidates[1]?.score ?? 0);
+    if (margin >= policy.minimumMargin)
+        return answer('high-margin');
+    return answer(candidates[1] && first.type !== candidates[1].type ? 'cross-type' : 'low-margin', true);
+}
+const digest = (value) => `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+const samePin = (a, b) => canonicalJson(a) === canonicalJson(b);
+/** One host-owned circuit per workload. Drift/quality controls can trip it without changing
+ * any index or active decision pins. Re-enabling requires a newly constructed route. */
+export class DiscoveryShadowRoute {
+    host;
+    policy;
+    stopped = false;
+    active = new Set();
+    constructor(policy, host) {
+        this.host = host;
+        validatePolicy(policy.ambiguity);
+        if (!['disabled', 'shadow'].includes(policy.mode) || !policy.allowedModels.length
+            || !policy.uncertaintyProfile || !/^sha256:[0-9a-f]{64}$/.test(policy.calibrationDigest)
+            || ![policy.minimumProbability, policy.minimumMargin].every(n => finite(n) && n <= 1)
+            || !Number.isSafeInteger(policy.maximumLatencyMs) || policy.maximumLatencyMs < 1
+            || !Number.isSafeInteger(policy.maximumTokens) || policy.maximumTokens < 1
+            || !finite(policy.maximumCostUsd)
+            || ![policy.definition, policy.binding].every(pin => pin && typeof pin.id === 'string' && pin.id.length > 0
+                && typeof pin.version === 'string' && pin.version.length > 0 && /^sha256:[0-9a-f]{64}$/.test(pin.digest))
+            || policy.allowedModels.some(model => typeof model !== 'string' || !model))
+            throw new Error('Invalid discovery shadow policy');
+        this.policy = structuredClone(policy);
+    }
+    disable() { this.stopped = true; for (const controller of this.active)
+        controller.abort(); }
+    get disabled() { return this.stopped || this.policy.mode === 'disabled'; }
+    /** Return metadata via the governed sink. Caller results always retain baseline order. */
+    async observe(query, baseline) {
+        const p = this.policy;
+        const gate = discoveryAmbiguity(query, baseline, p.ambiguity);
+        const selected = gate.reason === 'invalid-input' ? [] : baseline.slice(0, p.ambiguity.maximumCandidates);
+        const projection = {
+            query,
+            candidates: selected.map((c, i) => ({ option: `candidate_${i}`, id: c.id, name: c.name, type: c.type, capability: c.capability })),
+            options: [...selected.map((_, i) => `candidate_${i}`), 'none'],
+            definition: structuredClone(p.definition), binding: structuredClone(p.binding),
+        };
+        const receipt = {
+            schemaVersion: 'discovery-shadow/v1', route: 'deterministic-only', reason: 'privacy-denied',
+            ambiguityReason: gate.reason, candidatesDigest: digest(selected.map(c => c.id)), policyDigest: digest(p),
+            selection: null, resultDigest: null, servedModel: null, latencyMs: 0, usage: { tokens: null, costUsd: null },
+        };
+        const record = () => { try {
+            this.host.record(structuredClone(receipt));
+        }
+        catch {
+            this.disable();
+        } };
+        if (this.disabled || !gate.eligible) {
+            receipt.reason = this.stopped ? 'circuit-open' : p.mode === 'disabled' ? 'disabled' : gate.reason;
+            record();
+            return;
+        }
+        let authorized = false;
+        try {
+            authorized = this.host.authorize(structuredClone(projection)) === true;
+        }
+        catch { /* fail closed */ }
+        if (!authorized) {
+            record();
+            return;
+        }
+        const clock = this.host.clock ?? Date.now;
+        const start = clock();
+        if (!Number.isFinite(start)) {
+            this.disable();
+            return;
+        }
+        const controller = new AbortController();
+        this.active.add(controller);
+        let timedOut = false;
+        let onAbort;
+        let timer;
+        try {
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => { timedOut = true; controller.abort(); reject(new Error('deadline')); }, p.maximumLatencyMs);
+            });
+            const cancelled = new Promise((_, reject) => {
+                onAbort = () => reject(new Error('cancelled'));
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+            });
+            receipt.route = 'shadow';
+            const response = await Promise.race([this.host.evaluate({ ...structuredClone(projection), signal: controller.signal }), timeout, cancelled]);
+            if (this.stopped)
+                throw new Error('circuit-open');
+            const elapsed = clock() - start;
+            receipt.latencyMs = finite(elapsed) ? elapsed : p.maximumLatencyMs;
+            if (!finite(elapsed) || elapsed >= p.maximumLatencyMs) {
+                timedOut = true;
+                controller.abort();
+                throw new Error('deadline');
+            }
+            const r = response.result.spec;
+            receipt.resultDigest = /^sha256:[0-9a-f]{64}$/.test(response.receiptDigest) ? response.receiptDigest : null;
+            const attempts = r.attempts;
+            // Shared request accounting must remain at its owner; a per-item route cannot charge it again.
+            const ordinary = attempts.length > 0 && attempts.every(a => !a.batch);
+            const tokenKnown = ordinary && attempts.every(a => Number.isSafeInteger(a.usage.inputTokens) && a.usage.inputTokens >= 0
+                && Number.isSafeInteger(a.usage.outputTokens) && a.usage.outputTokens >= 0);
+            const costKnown = ordinary && attempts.every(a => a.usage.costUsd !== null && finite(a.usage.costUsd));
+            receipt.usage.tokens = tokenKnown ? attempts.reduce((n, a) => n + a.usage.inputTokens + a.usage.outputTokens, 0) : null;
+            receipt.usage.costUsd = costKnown ? attempts.reduce((n, a) => n + a.usage.costUsd, 0) : null;
+            if (receipt.usage.tokens === null || receipt.usage.costUsd === null || !Number.isSafeInteger(receipt.usage.tokens)
+                || receipt.usage.tokens > p.maximumTokens || receipt.usage.costUsd > p.maximumCostUsd) {
+                receipt.reason = 'budget-breach';
+                this.disable();
+                record();
+                return;
+            }
+            const last = attempts.at(-1);
+            const uncertainty = r.uncertainty;
+            const distribution = uncertainty?.distribution;
+            const probabilities = distribution && projection.options.every(option => Object.hasOwn(distribution, option))
+                && Object.keys(distribution).length === projection.options.length ? Object.values(distribution) : [];
+            const knownModel = last.actualModel !== null && p.allowedModels.includes(last.actualModel);
+            receipt.servedModel = knownModel ? last.actualModel : null;
+            const option = r.value;
+            let accept = r.status === 'success' && samePin(r.decision, p.definition) && samePin(r.binding, p.binding)
+                && knownModel && receipt.resultDigest !== null && r.acceptance?.disposition === 'act'
+                && r.calibrationCompatibility?.action === 'allow' && ['exact', 'approved-compatible'].includes(r.calibrationCompatibility.state)
+                && r.calibrationCompatibility.artifactDigest === p.calibrationDigest
+                && r.calibrationCompatibility.actualModel === last.actualModel
+                && r.calibrationCompatibility.runId === `${r.runId}:${r.invocationId}:${r.alias}`
+                && uncertainty?.source === 'provider' && uncertainty.profile === p.uncertaintyProfile
+                && probabilities.length > 0 && probabilities.every(v => finite(v) && v <= 1)
+                && Math.abs(probabilities.reduce((sum, v) => sum + v, 0) - 1) < 1e-6
+                && typeof option === 'string' && projection.options.includes(option);
+            if (accept && distribution && typeof option === 'string') {
+                const probability = distribution[option];
+                const competitor = Math.max(...Object.entries(distribution).filter(([key]) => key !== option).map(([, value]) => value));
+                accept = probability > competitor && probability >= p.minimumProbability && probability - competitor >= p.minimumMargin;
+            }
+            receipt.reason = accept ? 'accepted-shadow' : 'rejected-evidence';
+            if (!accept)
+                this.disable(); // quality/model/calibration breach restores deterministic-only routing
+            if (accept)
+                receipt.selection = option === 'none' ? { kind: 'none' } : { kind: 'candidate', ordinal: projection.options.indexOf(option) };
+        }
+        catch {
+            receipt.reason = timedOut ? 'budget-breach' : this.stopped ? 'circuit-open' : 'evaluation-failed';
+            const elapsed = clock() - start;
+            receipt.latencyMs = timedOut ? Math.max(p.maximumLatencyMs, finite(elapsed) ? elapsed : 0) : finite(elapsed) ? elapsed : 0;
+            receipt.selection = null;
+            if (timedOut)
+                this.disable();
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (onAbort)
+                controller.signal.removeEventListener('abort', onAbort);
+            this.active.delete(controller);
+        }
+        record();
+    }
+}
+export { DiscoveryShadowEvaluator } from './discovery-shadow-evaluator.js';
+//# sourceMappingURL=discovery-shadow.js.map

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

@@ -15,6 +15,7 @@ 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 { validateGateDocument } from '../gates/schema.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';
@@ -197,6 +198,42 @@ export function parseDecisionDoc(content, relativePath) {
         capability: purpose.slice(0, 240), tags: ['decision-system', value.kind], searchTerms: [...terms],
     };
 }
+/**
+ * Classify and schema-check authored gate-pack documents (#2830).
+ *
+ * Packs live in `<bundle>/gate-packs/*.gatepack.yaml|json` (never `gates/`,
+ * which agent-persistence HITL uses). The `.gatepack.` extension is the
+ * boundary: HITL `gates/*.yaml` files must never classify as `gate-pack`.
+ * Invalid packs return null so they are never discoverable; the bundle
+ * loader rejects them at load with a diagnostic.
+ */
+export function parseGatePackDoc(content, relativePath) {
+    if (!/\.gatepack\.(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);
+        validateGateDocument(document);
+    }
+    catch {
+        return null;
+    }
+    const value = document;
+    if (value.kind !== 'GatePack')
+        return null;
+    const description = value.metadata.description;
+    const terms = new Set([
+        value.kind, value.metadata.id, value.metadata.version, description,
+        ...(value.spec.gates ?? []).map(gate => String(gate.id ?? '')).filter(Boolean),
+        ...Object.keys(value.spec.metrics ?? {}),
+    ]);
+    return {
+        type: 'gate-pack', kind: 'GatePack', name: value.metadata.id, description,
+        capability: description.slice(0, 240), tags: ['gates', value.kind], searchTerms: [...terms],
+    };
+}
 function parseSchemaDoc(content, relativePath) {
     if (!/\.(json|ya?ml)$/i.test(relativePath))
         return null;
@@ -964,15 +1001,16 @@ export async function buildIndex(cwd, options = {}) {
             // become discoverable (#1540).
             const flow = parseFlowDoc(content, relativePath);
             const decision = flow ? null : parseDecisionDoc(content, relativePath);
+            const gatePack = flow || decision ? null : parseGatePackDoc(content, relativePath);
             const inferredType = inferType(data, relativePath);
             const physicalType = inferType({ ...data, type: undefined }, relativePath);
-            const runbook = flow || decision ? null : parseRunbookDoc(data, body, relativePath);
+            const runbook = flow || decision || gatePack ? null : parseRunbookDoc(data, body, relativePath);
             const schemaDoc = inferredType === 'schema' ? parseSchemaDoc(content, relativePath) : null;
-            const title = flow?.name ?? decision?.name ?? schemaDoc?.title ?? extractTitle(data, body);
+            const title = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.title ?? extractTitle(data, body);
             const phase = typeof data.phase === 'string' ? data.phase : inferPhase(relativePath);
-            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 type = flow?.type ?? decision?.type ?? gatePack?.type ?? (runbook ? 'runbook' : inferredType);
+            const tags = flow?.tags ?? decision?.tags ?? gatePack?.tags ?? (Array.isArray(data.tags) ? data.tags.map(String) : []);
+            const summary = flow?.description ?? decision?.description ?? gatePack?.description ?? schemaDoc?.capability ?? runbook?.capability ?? extractSummary(data, body);
             const dependencies = extractMentions(content);
             const markdownLinks = extractMarkdownLinks(content);
             // Discovery metadata (#1214, #1540, #1792) — meaningful for operational
@@ -982,10 +1020,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 ?? decision?.capability ?? schemaDoc?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
-            const kind = flow?.kind ?? decision?.kind ?? runbook?.kind;
+            const capability = flow?.capability ?? decision?.capability ?? gatePack?.capability ?? schemaDoc?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
+            const kind = flow?.kind ?? decision?.kind ?? gatePack?.kind ?? runbook?.kind;
             const sourceType = runbook && physicalType !== 'runbook' ? physicalType : undefined;
-            const searchTerms = flow?.searchTerms ?? decision?.searchTerms ?? schemaDoc?.searchTerms ?? runbook?.searchTerms;
+            const searchTerms = flow?.searchTerms ?? decision?.searchTerms ?? gatePack?.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;
@@ -994,7 +1032,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?.name ?? decision?.name ?? schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
+            const name = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
             entry = {
                 path: relativePath,
                 type,

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

@@ -1142,6 +1142,19 @@ export async function discoverCapability(cwd, params) {
     }
     const scored = dedupeDiscoverResults(await applyFacetFusion(Array.from(combinedByPath.values()).sort(compareDiscoverResults), candidates, params.phrase)).slice(0, limit);
     const relaxed = scored.some(result => !strictPaths.has(result.entry.path));
+    if (params.shadowRoute) {
+        try {
+            await params.shadowRoute.observe(params.phrase, scored.map(result => ({
+                id: discoveryIdForEntry(result.entry), name: result.entry.name ?? result.entry.title,
+                type: result.entry.type, capability: result.entry.capability ?? result.entry.summary,
+                score: result.score,
+            })));
+        }
+        catch {
+            // An optional observation failure must never replace deterministic discovery.
+            params.shadowRoute.disable();
+        }
+    }
     const queryTimeMs = Date.now() - startTime;
     /**
      * Resolve a stored framework-graph path to an absolute AIWG_ROOT
@@ -1474,7 +1487,15 @@ function findShowMatches(entries, types, needle) {
             const slugLayoutMatch = ((basename === 'SKILL.md' && e.type === 'skill') ||
                 (basename === 'BEHAVIOR.md' && e.type === 'behavior')) &&
                 dirStem === needle;
-            return slugLayoutMatch || fileStem === needle || e.name === needle;
+            if (slugLayoutMatch || fileStem === needle || e.name === needle)
+                return true;
+            if (e.type === 'gate-pack' && typeof e.name === 'string') {
+                const gateStem = fileStem.replace(/\.gatepack$/i, '');
+                const rest = e.name.includes(':') ? e.name.slice(e.name.indexOf(':') + 1) : e.name;
+                const short = rest.includes('/') ? rest.slice(rest.indexOf('/') + 1) : rest;
+                return gateStem === needle || rest === needle || short === needle;
+            }
+            return false;
         });
     }
     if (matches.length === 0) {
@@ -1526,6 +1547,68 @@ async function fortemiRecordForEntry(cwd, entry, sourcePaths) {
     const id = discoveryIdForEntry(entry);
     return loaded.exported.items.find((record) => record.id === id || record.source.path === entry.path) ?? null;
 }
+/**
+ * Scan bundle `gate-packs/` directories for a pack matching `needle` (#2830).
+ *
+ * Accepts the full namespaced id, the rest-path or the short pack name and
+ * probes `<bundle>/gate-packs/<pack>.gatepack.{yaml,yml,json}`. Never looks
+ * under `gates/`, which agent-persistence HITL owns.
+ */
+async function findGatePackInCorpus(groups, needle) {
+    const path = await import('node:path');
+    const fsp = (await import('node:fs')).promises;
+    const trimmed = needle.trim();
+    const rest = trimmed.includes(':') ? trimmed.slice(trimmed.indexOf(':') + 1) : trimmed;
+    const slash = rest.indexOf('/');
+    const wantedBundle = slash >= 0 ? rest.slice(0, slash) : null;
+    const wantedPack = slash >= 0 ? rest.slice(slash + 1) : rest;
+    if (!wantedPack || /\s/.test(wantedPack) || wantedPack.includes(':') || wantedPack.includes('/'))
+        return null;
+    const extensions = ['.gatepack.yaml', '.gatepack.yml', '.gatepack.json'];
+    const ordered = wantedBundle
+        ? groups.flatMap(group => [{ group, bundle: wantedBundle }])
+        : null;
+    const probe = async (group, bundle) => {
+        for (const extension of extensions) {
+            const candidate = path.join(group.dir, bundle, 'gate-packs', `${wantedPack}${extension}`);
+            try {
+                const stat = await fsp.stat(candidate);
+                if (stat.isFile())
+                    return { path: candidate, bundleKind: group.kind, bundleId: bundle };
+            }
+            catch {
+                // not present — continue
+            }
+        }
+        return null;
+    };
+    if (ordered) {
+        for (const { group, bundle } of ordered) {
+            const found = await probe(group, bundle);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    for (const group of groups) {
+        let bundles;
+        try {
+            bundles = (await fsp.readdir(group.dir, { withFileTypes: true }))
+                .filter(d => d.isDirectory())
+                .map(d => d.name)
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const bundle of bundles) {
+            const found = await probe(group, bundle);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
 /**
  * Scan the AIWG_ROOT corpus for an artifact matching `name` (#1221).
  *
@@ -1592,6 +1675,16 @@ async function findCorpusArtifact(aiwgRoot, name, typeFilter) {
             }
         }
     }
+    // Gate packs live in `<bundle>/gate-packs/*.gatepack.yaml|json` (never
+    // `gates/`, which agent-persistence HITL uses). The needle may be the full
+    // namespaced id (`aiwg:decision-engine/integrity-ceiling`), the rest-path
+    // (`decision-engine/integrity-ceiling`) or the short pack name
+    // (`integrity-ceiling`). (#2830)
+    if (typeFilter.length === 0 || typeFilter.includes('gate-pack')) {
+        const gateMatch = await findGatePackInCorpus(groups, name);
+        if (gateMatch)
+            return { ...gateMatch, type: 'gate-pack' };
+    }
     // Top-level agents live at `agentic/code/agents/<category>/<name>.md`
     // (e.g. `personas/aiwg-writer.md`) — a flat-under-category layout the
     // bundle groups above do not cover. Scan it directly so persona/agent

package/dist/src/artifacts/types.js

@@ -28,6 +28,7 @@ export const OPERATIONAL_DISCOVERY_TYPES = [
     'decision-definition',
     'decision-ruleset',
     'decision-binding',
+    'gate-pack',
     'flow',
     'runbook',
     'template',