akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/integrations/agent/engine-resolution.js

@@ -0,0 +1,231 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import path from "node:path";
+import { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { ConfigError } from "../../core/errors.js";
+import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
+import { collectSensitiveValues } from "../../core/redaction.js";
+import { getHarness } from "../harnesses/index.js";
+import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
+import { resolveLlmModel, resolveModel } from "./model-aliases.js";
+import { getBuiltinAgentProfile } from "./profiles.js";
+function hasOwn(value, key) {
+    return Object.hasOwn(value, key);
+}
+function envName(reference) {
+    const match = /^\$(?:\{)?([A-Za-z_][A-Za-z0-9_]*)(?:\})?$/.exec(reference);
+    return match?.[1];
+}
+function selectedEngineName(config, layers, llmOnly) {
+    for (let index = layers.length - 1; index >= 0; index--) {
+        if (layers[index]?.engine !== undefined)
+            return layers[index]?.engine;
+    }
+    return llmOnly ? config.defaults?.llmEngine : config.defaults?.engine;
+}
+function resolveEngineConfig(name, config) {
+    const engine = config.engines?.[name];
+    if (!engine) {
+        throw new ConfigError(`Engine "${name}" is not configured.`, "INVALID_CONFIG_FILE");
+    }
+    return engine;
+}
+function resolveCredential(name, engine, config) {
+    if (engine.apiKey !== undefined) {
+        const explicit = envName(engine.apiKey);
+        if (!explicit)
+            throw new ConfigError(`Engine "${name}" has an invalid symbolic apiKey reference.`, "INVALID_CONFIG_FILE");
+        return { names: [explicit], required: true };
+    }
+    const specific = `AKM_ENGINE_${name.toUpperCase().replaceAll("-", "_")}_API_KEY`;
+    return config.defaults?.llmEngine === name
+        ? { names: [specific, "AKM_LLM_API_KEY"], required: false }
+        : { names: [specific], required: false };
+}
+/** Collect materialized engine credentials for output and persistence redaction. */
+export function collectEngineCredentialValues(config, envSource = process.env) {
+    const values = new Set();
+    for (const [name, engine] of Object.entries(config.engines ?? {})) {
+        if (engine.kind !== "llm")
+            continue;
+        for (const envVar of resolveCredential(name, engine, config)?.names ?? []) {
+            const value = envSource[envVar]?.trim();
+            if (value)
+                values.add(value);
+        }
+    }
+    return collectSensitiveValues(values);
+}
+function effectiveTimeout(engine, layers, fallback) {
+    for (let index = layers.length - 1; index >= 0; index--) {
+        if (hasOwn(layers[index] ?? {}, "timeoutMs"))
+            return layers[index]?.timeoutMs ?? null;
+    }
+    return hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : fallback;
+}
+export function resolveLlmEngineUse(config, layers, options = {}) {
+    const name = selectedEngineName(config, layers, true);
+    if (!name) {
+        if (options.optional)
+            return undefined;
+        throw new ConfigError("No LLM engine is selected. Set defaults.llmEngine or specify engine.", "LLM_NOT_CONFIGURED");
+    }
+    const engine = resolveEngineConfig(name, config);
+    if (engine.kind !== "llm") {
+        throw new ConfigError(`Engine "${name}" is not an LLM engine.`, "INVALID_CONFIG_FILE");
+    }
+    let connection = {
+        provider: engine.provider,
+        endpoint: engine.endpoint,
+        model: engine.model,
+        temperature: engine.temperature,
+        maxTokens: engine.maxTokens,
+        supportsJsonSchema: engine.supportsJsonSchema,
+        extraParams: engine.extraParams,
+        contextLength: engine.contextLength,
+        enableThinking: engine.enableThinking,
+    };
+    for (const layer of layers) {
+        if (layer.llm)
+            connection = deepMergeConfig(connection, layer.llm);
+        if (layer.model !== undefined)
+            connection.model = layer.model;
+    }
+    for (const key of Object.keys(connection)) {
+        if (connection[key] === undefined)
+            delete connection[key];
+    }
+    connection.model = resolveLlmModel(connection.model, name, config.modelAliases);
+    return {
+        engine: name,
+        connection: connection,
+        credential: resolveCredential(name, engine, config),
+        timeoutMs: effectiveTimeout(engine, layers, DEFAULT_LLM_TIMEOUT_MS),
+    };
+}
+/** Read a resolved symbolic credential only at the runtime dispatch boundary. */
+export function materializeLlmConnection(resolved) {
+    if (resolved.connection.extraParams !== undefined) {
+        const issue = validateExtraParams(resolved.connection.extraParams)[0];
+        if (issue) {
+            throw new ConfigError(formatExtraParamsIssue(`Engine "${resolved.engine}" extraParams`, issue), "INVALID_CONFIG_FILE");
+        }
+    }
+    let apiKey;
+    for (const name of resolved.credential?.names ?? []) {
+        const candidate = process.env[name]?.trim();
+        if (candidate) {
+            apiKey = candidate;
+            break;
+        }
+    }
+    if (resolved.credential?.required && !apiKey) {
+        throw new ConfigError(`Required engine credential ${resolved.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    }
+    return {
+        ...resolved.connection,
+        ...(apiKey ? { apiKey } : {}),
+        timeoutMs: resolved.timeoutMs,
+    };
+}
+function lowerAgentEngine(name, engine, config) {
+    const harness = getHarness(engine.platform);
+    if (!harness?.capabilities.agentDispatch) {
+        throw new ConfigError(`Engine "${name}" names a platform that cannot dispatch agents: ${engine.platform}.`, "INVALID_CONFIG_FILE");
+    }
+    const platform = harness.id;
+    const sdk = platform === "opencode-sdk";
+    const builtin = getBuiltinAgentProfile(platform);
+    const profile = {
+        name,
+        platform,
+        bin: engine.bin ?? builtin?.bin ?? (sdk ? "opencode" : platform),
+        args: engine.args ?? builtin?.args ?? [],
+        stdio: "captured",
+        ...(builtin?.env ? { env: builtin.env } : {}),
+        envPassthrough: builtin?.envPassthrough ?? [],
+        parseOutput: "text",
+        ...(engine.workspace ? { workspace: path.resolve(engine.workspace) } : {}),
+        ...(engine.model
+            ? {
+                model: resolveModel(engine.model, platform, engine.modelAliases, config.modelAliases),
+                modelIsExact: true,
+            }
+            : {}),
+        ...(engine.modelAliases ? { modelAliases: engine.modelAliases } : {}),
+        ...(config.modelAliases ? { globalModelAliases: config.modelAliases } : {}),
+    };
+    if (!sdk) {
+        return {
+            kind: "agent",
+            engine: name,
+            profile,
+            timeoutMs: hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : DEFAULT_AGENT_TIMEOUT_MS,
+        };
+    }
+    const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
+    const fallback = fallbackName
+        ? resolveLlmEngineUse(config, [{ engine: fallbackName }], { optional: true })
+        : undefined;
+    return {
+        kind: "sdk",
+        engine: name,
+        profile,
+        ...(fallback
+            ? {
+                fallbackConnection: fallback.connection,
+                ...(fallback.credential ? { fallbackCredential: fallback.credential } : {}),
+                fallbackTimeoutMs: fallback.timeoutMs,
+            }
+            : {}),
+        timeoutMs: hasOwn(engine, "timeoutMs")
+            ? (engine.timeoutMs ?? null)
+            : (fallback?.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS),
+    };
+}
+/** Lower a named engine through the canonical harness platform. */
+export function resolveEngine(name, config) {
+    const engine = resolveEngineConfig(name, config);
+    if (engine.kind === "llm") {
+        const resolved = resolveLlmEngineUse(config, [{ engine: name }]);
+        if (!resolved)
+            throw new ConfigError(`LLM engine "${name}" could not be resolved.`, "LLM_NOT_CONFIGURED");
+        return {
+            kind: "llm",
+            engine: name,
+            connection: resolved.connection,
+            ...(resolved.credential ? { credential: resolved.credential } : {}),
+            timeoutMs: resolved.timeoutMs,
+        };
+    }
+    return lowerAgentEngine(name, engine, config);
+}
+export function resolveDefaultEngine(config) {
+    const name = config.defaults?.engine;
+    if (!name)
+        throw new ConfigError("No default engine is configured.", "INVALID_CONFIG_FILE");
+    return resolveEngine(name, config);
+}
+// ── AkmConfig convenience wrappers (moved from core/config/config.ts, WI-9.8
+// KILL 3, D.3 edge A) ────────────────────────────────────────────────────────
+//
+// Moved verbatim: `config.ts` previously called `materializeLlmConnection` +
+// `resolveLlmEngineUse` directly for these two wrappers, which is what made
+// config.ts import this module — and this module imported `LlmConnectionConfig`
+// back from config.ts, closing a 2-file cycle. config.ts CANNOT re-export
+// these (a re-export is still a graph edge to this file), so the small number
+// of call sites that used to import them from "core/config/config" now import
+// them from here instead (see D.3 edge A "callers compose instead").
+/** Resolve and materialize the configured default LLM engine at dispatch time. */
+export function requireLlmConfig(config) {
+    return materializeLlmConnection(resolveLlmEngineUse(config, []));
+}
+/**
+ * Like {@link requireLlmConfig} but returns `undefined` instead of throwing
+ * when no LLM is configured. Use in code paths where the LLM is optional.
+ */
+export function getDefaultLlmConfig(config) {
+    const resolved = resolveLlmEngineUse(config, [], { optional: true });
+    return resolved ? materializeLlmConnection(resolved) : undefined;
+}

package/dist/integrations/agent/index.js

@@ -2,9 +2,8 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 export { getCommandBuilder } from "./builders.js";
-export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config.js";
+export { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
 export { _setAgentDetectForTests, defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
 export { listBuiltinModelAliases, resolveModel } from "./model-aliases.js";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
 export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "./prompts.js";
-export { runAgent } from "./spawn.js";

package/dist/integrations/agent/model-aliases.js

@@ -13,7 +13,7 @@
 const BUILTIN_ALIASES = [
     {
         // Anthropic's Mythos-class tier above Opus — the recommended resolution
-        // target for the `deep` workflow tier (see docs/features/workflows.md).
+        // target for the `deep` workflow tier (see docs/reference/workflows.md).
         alias: "fable",
         platforms: {
             claude: "claude-fable-5",
@@ -50,19 +50,24 @@ const BUILTIN_ALIASES = [
  * @param platform Builder platform name ("claude", "opencode", ...).
  * @param custom  Profile-level aliases from config.json — take priority over globals and builtins.
  * @param global  Config-root `modelAliases` tier table (alias → platform → model, `"*"` fallback).
+ * @param fallbackPlatforms Additional global tier columns checked after `platform` and before `"*"`.
  * @returns Resolved model string, or `model` verbatim when no alias matches.
  */
-export function resolveModel(model, platform, custom, global) {
+export function resolveModel(model, platform, custom, global, fallbackPlatforms = []) {
     const key = model.toLowerCase();
     if (custom?.[key])
         return custom[key];
     const tier = global?.[key];
-    const fromGlobal = tier?.[platform] ?? tier?.["*"];
+    const fromGlobal = tier?.[platform] ?? fallbackPlatforms.map((fallback) => tier?.[fallback]).find(Boolean) ?? tier?.["*"];
     if (fromGlobal)
         return fromGlobal;
     const entry = BUILTIN_ALIASES.find((a) => a.alias === key);
     return entry?.platforms[platform] ?? model;
 }
+/** Resolve a direct/fallback LLM model through engine-specific, `llm`, then `*` tiers. */
+export function resolveLlmModel(model, engine, global) {
+    return resolveModel(model, engine, undefined, global, ["llm"]);
+}
 /** Return all built-in alias entries (for tests and documentation). */
 export function listBuiltinModelAliases() {
     return BUILTIN_ALIASES;

package/dist/integrations/agent/profiles.js

@@ -14,7 +14,7 @@ const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "T
  * amazonq, openhands — plan §"Capability matrix"). The fields here are
  * conservative defaults — every value is overridable from user config.
  *
- * For headless/automation use (propose, reflect, tasks), use the '-headless' variant.
+ * Engine lowering selects captured stdio for unattended dispatch.
  */
 const BUILTINS = {
     opencode: {
@@ -91,108 +91,15 @@ const BUILTINS = {
         parseOutput: "text",
     },
 };
-/**
- * Headless variants of the base profiles for automation use (propose, reflect, tasks).
- *
- * These profiles use `stdio: "captured"` and `parseOutput: "json"` so the
- * agent's response can be read from stdout. They share the same `bin` and
- * `envPassthrough` as the corresponding base profile but are intentionally
- * kept out of `BUILTIN_AGENT_PROFILE_NAMES` (and therefore out of CLI
- * detection/enumeration) to avoid showing up as separate installable profiles.
- *
- * Users may reference them by name via `--profile opencode-headless` or by
- * setting `agent.default: "opencode-headless"` in config.json.
- */
-const HEADLESS_BUILTINS = {
-    "opencode-headless": {
-        name: "opencode-headless",
-        bin: "opencode",
-        args: ["run"],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG"],
-        parseOutput: "json",
-    },
-    "claude-headless": {
-        name: "claude-headless",
-        bin: "claude",
-        args: [],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "ANTHROPIC_API_KEY", "CLAUDE_CONFIG"],
-        parseOutput: "json",
-    },
-    "codex-headless": {
-        name: "codex-headless",
-        bin: "codex",
-        args: [],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "CODEX_CONFIG"],
-        parseOutput: "json",
-    },
-    "gemini-headless": {
-        name: "gemini-headless",
-        bin: "gemini",
-        args: [],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "GEMINI_API_KEY", "GOOGLE_API_KEY"],
-        parseOutput: "json",
-    },
-    "aider-headless": {
-        name: "aider-headless",
-        bin: "aider",
-        args: ["--no-auto-commits"],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
-        parseOutput: "json",
-    },
-    // ── P2 harness-adapter headless variants (plan §"Capability matrix") ───────
-    "copilot-headless": {
-        name: "copilot-headless",
-        bin: "copilot",
-        args: [],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "GH_TOKEN", "GITHUB_TOKEN"],
-        parseOutput: "json",
-    },
-    "pi-headless": {
-        name: "pi-headless",
-        bin: "pi",
-        args: [],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "PI_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
-        parseOutput: "json",
-    },
-    "amazonq-headless": {
-        name: "amazonq-headless",
-        bin: "q",
-        args: [],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "AWS_PROFILE", "AWS_REGION"],
-        parseOutput: "json",
-    },
-    "openhands-headless": {
-        name: "openhands-headless",
-        bin: "openhands",
-        args: [],
-        stdio: "captured",
-        envPassthrough: [...COMMON_PASSTHROUGH, "LLM_MODEL", "LLM_API_KEY", "LLM_BASE_URL"],
-        parseOutput: "json",
-    },
-};
-/**
- * Names of the primary built-in profiles. Stable, sorted. Does NOT
- * include the `-headless` variants (those are resolvable by name but are
- * excluded from detection/enumeration flows).
- */
+/** Names of the canonical built-in harness descriptors. Stable, sorted. */
 export const BUILTIN_AGENT_PROFILE_NAMES = Object.freeze(Object.keys(BUILTINS).sort());
-/** Returns the built-in profile by name (including headless variants), or `undefined` if not found. */
+/** Returns the built-in descriptor for a canonical harness id. */
 export function getBuiltinAgentProfile(name) {
-    return BUILTINS[name] ?? HEADLESS_BUILTINS[name];
+    return BUILTINS[name];
 }
 /**
- * Return a deep copy of every primary built-in profile keyed by name.
- * Headless variants are NOT included — use `getBuiltinAgentProfile(name)`
- * to look them up by name. Callers should not assume reference equality with
- * subsequent calls.
+ * Return a copy of every canonical built-in descriptor keyed by harness id.
+ * Callers should not assume reference equality with subsequent calls.
  */
 export function listBuiltinAgentProfiles() {
     const out = {};

package/dist/integrations/agent/prompts.js

@@ -6,17 +6,17 @@
  *
  * `akm reflect` and `akm propose` both shell out to the configured agent CLI
  * (via {@link runAgent}) and ask it for a structured proposal payload. The
- * prompts are intentionally similar — both ask the agent to return a single
- * JSON object containing `ref`, `content`, and (optionally) `frontmatter` —
- * so we share the construction here. Keeping the prompt builders in
+ * prompts are intentionally similar and share their construction here. Agent
+ * and SDK stdout keeps the JSON/file-write contracts; direct LLM reflect adds
+ * native-schema and framed-markdown contracts. Keeping the prompt builders in
  * `src/integrations/agent/` rather than `src/llm/` is deliberate: these are
  * shell-out prompts targeting an agent CLI, not in-tree LLM API calls.
  *
- * The output the agent must produce is a *strict* JSON object:
+ * The stdout output an agent must produce is a strict JSON object:
  *
  * ```json
  * {
- *   "ref": "lesson:my-lesson",
+ *   "ref": "lessons/my-lesson",
  *   "content": "---\ndescription: ...\nwhen_to_use: ...\n---\n\nbody",
  *   "frontmatter": { "description": "...", "when_to_use": "..." }
  * }
@@ -25,7 +25,11 @@
  * `frontmatter` is optional — the proposal queue parses it from `content`
  * during validation. We carry it through if the agent supplies it.
  */
-import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import reflectLlmFramedContract from "../../assets/prompts/reflect-llm-framed-contract.md" with { type: "text" };
+import reflectLlmSchemaContract from "../../assets/prompts/reflect-llm-schema-contract.md" with { type: "text" };
+import reflectOutputRepair from "../../assets/prompts/reflect-output-repair.md" with { type: "text" };
+import { placementTypes } from "../../core/asset/asset-placement.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { authoringRulesForType, DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, requiresDescription, } from "../../core/authoring-rules.js";
 import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
@@ -42,7 +46,7 @@ const TYPE_HINTS = {
     memory: "memory assets are short factual notes the user wants persisted across sessions. Frontmatter usually includes `description`.",
     workflow: "workflow assets are markdown describing a multi-step process. Include `# <Title>` and ordered `## Step N` sections.",
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
-    env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>`; prefer `--clean` in agent contexts so the child starts from a minimal inherited environment. AKM itself does not print values, but the child command can print its environment, so do not run `env`, `printenv`, shell tracing, or similar diagnostics when secrets are in scope. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
+    env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env/<name> -- <cmd>`; prefer `--clean` in agent contexts so the child starts from a minimal inherited environment. AKM itself does not print values, but the child command can print its environment, so do not run `env`, `printenv`, shell tracing, or similar diagnostics when secrets are in scope. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
     fact: "fact assets are durable stash-level facts (personal/team/project details, coding conventions, stash-meta). Frontmatter SHOULD include `description` and a `category` (personal|team|project|convention|meta); set `pinned: true` only for the small always-injected core. Keep each fact short, high-signal, and self-contained — it is durable context, not an episodic note.",
 };
@@ -50,7 +54,7 @@ function hintForType(type) {
     return TYPE_HINTS[type] ?? `assets of type "${type}" — produce sensible markdown with optional frontmatter.`;
 }
 function knownTypeList() {
-    return Object.keys(TYPE_DIRS).sort().join(", ");
+    return [...placementTypes()].sort().join(", ");
 }
 /**
  * Common envelope every prompt asks the agent to honour when NO draft file
@@ -60,7 +64,10 @@ function knownTypeList() {
  */
 const RESPONSE_CONTRACT_JSON = [
     "Respond ONLY with a single JSON object. No prose before or after.",
-    'Shape: {"ref": "<type>:<name>", "content": "<full file contents>", "frontmatter": {...}, "confidence": <number 0..1>}',
+    // Slash conceptId, not the retired `<type>:<name>` colon grammar (Q-02/Q-08).
+    // This contract is the schema an agent copies from, so a stale spelling here
+    // teaches every proposal to use a ref form the CLI now rejects outright.
+    'Shape: {"ref": "<type>/<name>", "content": "<full file contents>", "frontmatter": {...}, "confidence": <number 0..1>}',
     "`content` is the full file body that will be written if accepted.",
     "`frontmatter` is optional — include it if `content` starts with `---` so reviewers can sanity-check the keys.",
     "`confidence` is REQUIRED. Self-rate this proposal on [0, 1] by how certain you are it materially improves the source asset. Calibrate honestly:",
@@ -68,7 +75,7 @@ const RESPONSE_CONTRACT_JSON = [
     "  • 0.70–0.89 — clear improvement, but a reviewer might reasonably prefer different framing or scope.",
     "  • 0.50–0.69 — marginal / judgment call; might help, might not be worth the churn.",
     "  • Below 0.50 — you are not confident this improves on the source. Prefer returning the source body roughly unchanged with a low score over inventing changes.",
-    "Auto-accept gates on confidence ≥ 0.80 by default. Overclaiming ships low-quality changes; underclaiming leaves good ones stuck in queue. Be honest.",
+    "Reviewers and the triage judge read this score when adjudicating the proposal queue. Overclaiming erodes trust in your proposals; underclaiming buries good ones. Be honest.",
 ].join("\n");
 /**
  * Response contract used when a draft file path is available. Instructs the
@@ -86,14 +93,14 @@ function fileWriteContract(draftFilePath) {
         "  • 0.70–0.89 — clear improvement, but a reviewer might prefer different framing.",
         "  • 0.50–0.69 — marginal / judgment call.",
         "  • Below 0.50 — not confident; prefer not writing changes at all.",
-        "Auto-accept gates on confidence ≥ 0.80. Overclaim → low-quality changes land; underclaim → good changes stuck in queue.",
+        "Reviewers and the triage judge read this score during adjudication. Overclaim → trust erodes; underclaim → good changes buried.",
     ].join("\n");
 }
 /**
  * Extract a confidence score from a `DRAFT_WRITTEN confidence=<n>` line emitted
  * by an agent following {@link fileWriteContract}. Tolerates trailing prose,
  * surrounding log lines, and missing/invalid confidence (returns `undefined`
- * so callers can keep the proposal but skip auto-accept).
+ * so callers can keep the proposal without a score).
  *
  * Matched forms (case-insensitive, anywhere in stdout):
  *   - `DRAFT_WRITTEN confidence=0.85`
@@ -111,6 +118,27 @@ export function extractDraftConfidence(stdout) {
         return undefined;
     return value;
 }
+export function reflectLlmResponseContract(mode, targetScoped) {
+    if (mode === "json_schema") {
+        return reflectLlmSchemaContract
+            .replace("{{FIELD_RULE}}", targetScoped
+            ? "The response has exactly the required fields `content`, `confidence`, and `frontmatterPatch`; do not echo `ref` or arbitrary `frontmatter`."
+            : "The response has exactly the required fields `ref`, `content`, `confidence`, and `frontmatterPatch`; `ref` must identify the selected asset.")
+            .trim();
+    }
+    const refLine = targetScoped ? "" : "AKM_REFLECT_REF: <selected asset ref>\n";
+    return reflectLlmFramedContract.replace("{{REF_LINE}}", refLine).trim();
+}
+export function buildReflectOutputRepairPrompt(mode, targetScoped) {
+    return reflectOutputRepair.replace("{{OUTPUT_CONTRACT}}", reflectLlmResponseContract(mode, targetScoped)).trim();
+}
+function reflectResponseContract(input) {
+    if (input.draftFilePath)
+        return fileWriteContract(input.draftFilePath);
+    if (input.outputMode)
+        return reflectLlmResponseContract(input.outputMode, input.ref !== undefined);
+    return RESPONSE_CONTRACT_JSON;
+}
 /**
  * Whether the source asset content has a non-empty `description:` key in its
  * YAML frontmatter. Used by {@link buildReflectPrompt} (#636) to decide whether
@@ -150,7 +178,7 @@ export function buildReflectPrompt(input) {
         const goalSentence = isLesson
             ? `Your task is to distill what usage signals reveal about this ${input.type} asset — when to reach for it, what goes wrong without it, and what real use has revealed that the asset itself does not say. Do not reproduce the source content; your proposal must add information the source does not contain.`
             : isSkill
-                ? "Your task is to review this skill asset, identify what the feedback and related distilled lessons show is broken, missing, unclear, or durable enough to promote into long-term documentation, and produce a single improved proposal. If the strongest evidence points to companion reference material rather than the main SKILL.md, you may instead propose a skill-adjacent knowledge doc such as `knowledge:skills/<skill>/references/<topic>`."
+                ? "Your task is to review this skill asset, identify what the feedback and related distilled lessons show is broken, missing, unclear, or durable enough to promote into long-term documentation, and produce a single improved proposal. If the strongest evidence points to companion reference material rather than the main SKILL.md, you may instead propose a skill-adjacent knowledge doc such as `knowledge/skills/<skill>/references/<topic>`."
                 : `Your task is to review this ${input.type} asset, identify what the feedback signals as broken, missing, or unclear, and produce an improved version. Do not reproduce the source content unchanged; your proposal must correct or add something the source lacks.`;
         sections.push(goalSentence);
         sections.push(`Target ref: ${input.ref}`);
@@ -186,7 +214,7 @@ export function buildReflectPrompt(input) {
         sections.push(input.standardsContext.trim());
     }
     {
-        const resolvedType = input.type ?? (input.ref?.includes(":") ? input.ref.split(":")[0] : "");
+        const resolvedType = input.type ?? (input.ref ? parseRefInput(input.ref).type : "");
         const authoringRules = resolvedType ? authoringRulesForType(resolvedType) : "";
         if (authoringRules) {
             sections.push(authoringRules);
@@ -244,7 +272,7 @@ export function buildReflectPrompt(input) {
         }
         sections.push("Evaluate whether these lessons contain strong evidence of factual, repeatable guidance that should be promoted into long-term skill documentation.");
         sections.push("Promote only guidance that is durable, generally applicable, and supported by repeated evidence. Do not copy anecdotal details, one-off incidents, or duplicate wording verbatim.");
-        sections.push("If the guidance belongs in the main skill instructions, update the skill proposal. If it belongs in a companion reference document, return a `knowledge:skills/<skill>/references/<topic>` proposal instead.");
+        sections.push("If the guidance belongs in the main skill instructions, update the skill proposal. If it belongs in a companion reference document, return a `knowledge/skills/<skill>/references/<topic>` proposal instead.");
     }
     if (input.rejectedProposals && input.rejectedProposals.length > 0) {
         const lines = ["## Previously Rejected Proposals"];
@@ -319,12 +347,12 @@ export function buildReflectPrompt(input) {
             "5. Improve clarity of surrounding prose, fix structural issues, add missing required frontmatter fields. Do NOT rewrite a runbook into an essay.",
         ].join("\n"));
     }
-    if (!input.draftFilePath && input.ref) {
+    if (!input.draftFilePath && !input.outputMode && input.ref) {
         // Reinforce that the `ref` field is mandatory and must exactly match the target.
         // Small models frequently omit `ref` from the response JSON, causing parse errors.
         sections.push(`IMPORTANT: The JSON "ref" field is REQUIRED. It MUST be exactly: "${input.ref}"`);
     }
-    sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
+    sections.push(reflectResponseContract(input));
     return { prompt: sections.join("\n\n"), ...(maxOutputChars !== undefined ? { maxOutputChars } : {}) };
 }
 /**
@@ -399,7 +427,7 @@ export function buildSchemaRepairPrompt(input) {
  * can map to {@link AgentFailureReason} `parse_error`.
  *
  * Resilient to two common local-LLM failure modes:
- *  1. `<think>…</think>` blocks emitted before the JSON (stripped by `stripJsonFences`).
+ *  1. `<think>…</think>` blocks emitted before the JSON (stripped before parsing).
  *  2. Prose preamble / postamble around the JSON object (handled by `extractEmbeddedJson`).
  */
 export function parseAgentProposalPayload(stdout) {