akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/proposal/proposal-cli.js

@@ -8,7 +8,12 @@
  * migrated to `defineJsonCommand`, which wraps the body in `runWithJsonErrors`
  * and emits the same JSON envelope (stdout/stderr/exit-code) as the inline
  * `runWithJsonErrors` form it replaces.
+ *
+ * 0.9 CLI overhaul (S8): the former top-level `extract` and `propose`
+ * commands are absorbed here as `extract` and `new` — no top-level
+ * registration remains for either spelling.
  */
+import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
 import { resolveStashDir } from "../../core/common.js";
@@ -17,10 +22,26 @@ import { UsageError } from "../../core/errors.js";
 import { resolveTriageJudgmentRunner } from "../../integrations/agent/runner.js";
 import { installLlmUsagePersistenceIfAbsent } from "../../llm/usage-persist.js";
 import { withLlmStage } from "../../llm/usage-telemetry.js";
+import { extractCommand } from "../improve/extract-cli.js";
 import { resolveImproveStrategy } from "../improve/improve-strategies.js";
 import { drainProposals } from "./drain.js";
 import { resolveDrainPolicy } from "./drain-policies.js";
 import { akmProposalAccept, akmProposalDiff, akmProposalList, akmProposalReject, akmProposalRevert, akmProposalShow, bulkAdjudicateProposals, } from "./proposal.js";
+import { proposeCommand } from "./propose-cli.js";
+/**
+ * `--source` was renamed to `--generator` on `proposal accept`/`proposal
+ * reject` in 0.9 (WS3/S8 — "Removed in 0.9.0"). citty is non-strict, so the
+ * retired spelling is silently absorbed rather than rejected — a bulk
+ * accept/reject invoked with `--source <name>` then has neither `--generator`
+ * nor a positional id, and falls through to the single-proposal path, which
+ * throws MISSING_REQUIRED_ARGUMENT instead of running the bulk action the
+ * caller asked for. Reject it explicitly instead.
+ */
+function rejectRetiredProposalSourceFlag(subcommand) {
+    if (!getParsedInvocation().hasFlag("--source"))
+        return;
+    throw new UsageError(`\`akm proposal ${subcommand} --source\` was renamed to \`--generator\` in 0.9. Use \`--generator <name>\` instead.`, "INVALID_FLAG_VALUE");
+}
 /**
  * Parse + validate the shared bulk-adjudication filter flags
  * (`--max-diff-lines`, `--older-than`). Extracted from the two verbatim
@@ -54,6 +75,7 @@ function parseProposalStatus(raw) {
 const proposalListCommand = defineJsonCommand({
     meta: { name: "list", description: "List proposal queue entries" },
     args: {
+        queue: { type: "string", description: "Select the proposal queue by source name" },
         status: {
             type: "string",
             description: "Filter by status (pending|accepted|rejected|reverted)",
@@ -64,6 +86,7 @@ const proposalListCommand = defineJsonCommand({
     run({ args }) {
         const status = parseProposalStatus(args.status);
         const result = akmProposalList({
+            queue: args.queue,
             status,
             ref: args.ref,
             type: args.type,
@@ -73,30 +96,31 @@ const proposalListCommand = defineJsonCommand({
     },
 });
 const proposalAcceptCommand = defineJsonCommand({
-    meta: { name: "accept", description: "Accept a proposal and promote it into the stash" },
+    meta: { name: "accept", description: "Accept a proposal and promote it into the bundle" },
     args: {
         id: {
             type: "positional",
-            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream). Optional when --generator is provided.",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skills/akm-dream). Optional when --generator is provided.",
             required: false,
         },
-        target: { type: "string", description: "Override the write target by source name" },
+        queue: { type: "string", description: "Select the proposal queue by source name" },
+        target: { type: "string", description: "Write destination; must match the proposal's recorded target" },
         // F-6 / #393: Batch accept by generator, diff size, or age.
         generator: {
             type: "string",
-            description: "F-6: Bulk-accept all pending proposals from this generator (e.g. reflect, distill). Requires no positional id.",
+            description: "Bulk-accept all pending proposals from this generator (e.g. reflect, distill). Requires no positional id.",
         },
         "max-diff-lines": {
             type: "string",
-            description: "F-6: When bulk-accepting, only accept proposals whose content is <= this many lines. Skips larger proposals.",
+            description: "When bulk-accepting, only accept proposals whose content is <= this many lines. Skips larger proposals.",
         },
         "older-than": {
             type: "string",
-            description: "F-6: When bulk-accepting, only accept proposals created more than this many days ago (e.g. '7' for 7 days).",
+            description: "When bulk-accepting, only accept proposals created more than this many days ago (e.g. '7' for 7 days).",
         },
         "dry-run": {
             type: "boolean",
-            description: "F-6: List proposals that would be bulk-accepted without accepting them.",
+            description: "List proposals that would be bulk-accepted without accepting them.",
             default: false,
         },
         yes: {
@@ -107,6 +131,7 @@ const proposalAcceptCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
+        rejectRetiredProposalSourceFlag("accept");
         const generator = args.generator;
         // F-6 / #393: Bulk-accept when --generator is provided without a positional id.
         if (generator && !args.id) {
@@ -123,6 +148,7 @@ const proposalAcceptCommand = defineJsonCommand({
                 maxDiffLines,
                 olderThanMs,
                 dryRun: args["dry-run"],
+                queue: args.queue,
                 target: args.target,
             });
             output("proposal-accept-batch", { accepted: count, results, dryRun: args["dry-run"] });
@@ -131,7 +157,11 @@ const proposalAcceptCommand = defineJsonCommand({
         if (!args.id) {
             throw new UsageError("Usage: akm proposal accept <id>  OR  akm proposal accept --generator <generator>", "MISSING_REQUIRED_ARGUMENT");
         }
-        const result = await akmProposalAccept({ id: args.id, target: args.target });
+        const result = await akmProposalAccept({
+            id: args.id,
+            queue: args.queue,
+            target: args.target,
+        });
         output("proposal-accept", result);
     },
 });
@@ -140,26 +170,27 @@ const proposalRejectCommand = defineJsonCommand({
     args: {
         id: {
             type: "positional",
-            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream). Optional when --generator is provided.",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skills/akm-dream). Optional when --generator is provided.",
             required: false,
         },
         reason: { type: "string", description: "Reason for rejection (required)" },
+        queue: { type: "string", description: "Select the proposal queue by source name" },
         // F-6 / #393: Batch reject by generator, diff size, or age.
         generator: {
             type: "string",
-            description: "F-6: Bulk-reject all pending proposals from this generator (e.g. reflect, distill). Requires no positional id.",
+            description: "Bulk-reject all pending proposals from this generator (e.g. reflect, distill). Requires no positional id.",
         },
         "max-diff-lines": {
             type: "string",
-            description: "F-6: When bulk-rejecting, only reject proposals whose content is <= this many lines. Skips larger proposals.",
+            description: "When bulk-rejecting, only reject proposals whose content is <= this many lines. Skips larger proposals.",
         },
         "older-than": {
             type: "string",
-            description: "F-6: When bulk-rejecting, only reject proposals created more than this many days ago (e.g. '7' for 7 days).",
+            description: "When bulk-rejecting, only reject proposals created more than this many days ago (e.g. '7' for 7 days).",
         },
         "dry-run": {
             type: "boolean",
-            description: "F-6: List proposals that would be bulk-rejected without rejecting them.",
+            description: "List proposals that would be bulk-rejected without rejecting them.",
             default: false,
         },
         yes: {
@@ -170,6 +201,7 @@ const proposalRejectCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
+        rejectRetiredProposalSourceFlag("reject");
         const generator = args.generator;
         if (!args.reason || !String(args.reason).trim()) {
             throw new UsageError("Usage: akm proposal reject <id> --reason '<reason>'  OR  akm proposal reject --generator <generator> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
@@ -189,6 +221,7 @@ const proposalRejectCommand = defineJsonCommand({
                 maxDiffLines,
                 olderThanMs,
                 dryRun: args["dry-run"],
+                queue: args.queue,
                 reason: String(args.reason),
             });
             output("proposal-reject-batch", { rejected: count, results, dryRun: args["dry-run"] });
@@ -205,7 +238,11 @@ const proposalRejectCommand = defineJsonCommand({
             process.stderr.write("Aborted.\n");
             return;
         }
-        const result = await akmProposalReject({ id: args.id, reason: String(args.reason) });
+        const result = await akmProposalReject({
+            id: args.id,
+            queue: args.queue,
+            reason: String(args.reason),
+        });
         output("proposal-reject", result);
     },
 });
@@ -214,13 +251,14 @@ const proposalDiffCommand = defineJsonCommand({
     args: {
         id: {
             type: "positional",
-            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skills/akm-dream)",
             required: true,
         },
-        target: { type: "string", description: "Override the write target by source name" },
+        queue: { type: "string", description: "Select the proposal queue by source name" },
+        target: { type: "string", description: "Diff destination; must match the proposal's recorded target" },
     },
     run({ args }) {
-        const result = akmProposalDiff({ id: args.id, target: args.target });
+        const result = akmProposalDiff({ id: args.id, queue: args.queue, target: args.target });
         output("proposal-diff", result);
     },
 });
@@ -243,33 +281,34 @@ const proposalRevertCommand = defineJsonCommand({
     args: {
         id: {
             type: "positional",
-            description: "Proposal id (full uuid) or asset ref (e.g. skill:akm-dream). UUID prefixes are not supported for archived proposals — use the full UUID.",
+            description: "Proposal id (full uuid) or asset ref (e.g. skills/akm-dream). UUID prefixes are not supported for archived proposals — use the full UUID.",
             required: true,
         },
-        target: { type: "string", description: "Override the write target by source name" },
+        queue: { type: "string", description: "Select the proposal queue by source name" },
+        target: { type: "string", description: "Write destination; must match the proposal's recorded target" },
     },
     async run({ args }) {
         const result = await akmProposalRevert({
             id: args.id,
+            queue: args.queue,
             target: args.target,
         });
         output("proposal-revert", result);
     },
 });
 // `proposal show` (#225): show a single proposal with its validation findings.
-// `akmProposalShow` already backs `akm show proposal <id>` (now deprecated); this
-// is the canonical noun-group entry point.
 const proposalShowCommand = defineJsonCommand({
     meta: { name: "show", description: "Show a single proposal and its validation findings" },
     args: {
         id: {
             type: "positional",
-            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skills/akm-dream)",
             required: true,
         },
+        queue: { type: "string", description: "Select the proposal queue by source name" },
     },
     run({ args }) {
-        const result = akmProposalShow({ id: args.id });
+        const result = akmProposalShow({ id: args.id, queue: args.queue });
         output("proposal-show", result);
     },
 });
@@ -415,22 +454,17 @@ const proposalDrainCommand = defineJsonCommand({
         });
     },
 });
-// ── proposal noun group (#225 / 0.8 CLI stabilization) ────────────────────────
-//
-// `akm proposal <verb>` is the canonical grammar in 0.8. The flat verbs
-// (`proposals`/`accept`/`reject`/`diff`/`revert`) remain as deprecated aliases
-// that warn to stderr and delegate to the same command bodies; they are removed
-// in 0.9.0. Bare `akm proposal` behaves as `proposal list` (mirrors `akm env`).
+// ── proposal noun group ───────────────────────────────────────────────────────
 export const proposalCommand = defineGroupCommand({
-    meta: { name: "proposal", description: "Manage the proposal queue: list, show, diff, accept, reject, revert" },
-    args: {
-        status: {
-            type: "string",
-            description: "Filter by status (pending|accepted|rejected|reverted)",
-        },
-        ref: { type: "string", description: "Filter by asset ref ([bundle//]conceptId, e.g. knowledge/guide.md)" },
-        type: { type: "string", description: "Filter by asset type" },
+    meta: {
+        name: "proposal",
+        description: "Manage the proposal queue: list, show, diff, accept, reject, revert, extract, new, drain",
     },
+    // The group declared `--queue`/`--status`/`--ref`/`--type` only so the bare
+    // form could act as `proposal list`. That form is gone (see below), and
+    // `proposalListCommand` declares the identical set, so keeping them here
+    // would just advertise flags in `akm proposal --help` that no group-level
+    // body reads.
     subCommands: {
         list: proposalListCommand,
         show: proposalShowCommand,
@@ -439,16 +473,10 @@ export const proposalCommand = defineGroupCommand({
         reject: proposalRejectCommand,
         revert: proposalRevertCommand,
         drain: proposalDrainCommand,
+        extract: extractCommand,
+        new: proposeCommand,
     },
-    // Default body fires only for bare `akm proposal [--status …]`.
-    defaultRun({ args }) {
-        const status = parseProposalStatus(args.status);
-        const result = akmProposalList({
-            status,
-            ref: args.ref,
-            type: args.type,
-            includeArchive: status === "accepted" || status === "rejected" || status === "reverted",
-        });
-        output("proposal-list", result);
-    },
+    // No `defaultRun`: bare `akm proposal [--status …]` is a usage error (exit 2),
+    // the canonical bare-group behavior — owner ruling 12. `akm proposal list`
+    // takes the same flags and produces what the bare form used to.
 });

package/dist/commands/proposal/proposal.js

@@ -13,8 +13,9 @@
  */
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { createProposal, diffProposal, getProposal, isProposalSkipped, listProposals, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, revertProposal, } from "./repository.js";
+import { createProposal, diffProposal, isProposalSkipped, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, resolveProposalIdForReject, revertProposal, } from "./repository.js";
 import { validateProposal } from "./validators/proposals.js";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
@@ -22,6 +23,14 @@ function resolveStash(stashDir) {
         return stashDir;
     return resolveStashDir();
 }
+function resolveProposalQueue(stashDir, queue, config) {
+    if (stashDir)
+        return { stashDir };
+    if (!queue)
+        return { stashDir: resolveStash() };
+    const target = resolveWriteTarget(config ?? loadConfig(), queue);
+    return { stashDir: target.source.path, target };
+}
 /**
  * Thin in-process read of the pending proposal queue, used by the health HTML
  * report builder (#582) so it never shells out to `akm proposal list`.
@@ -34,7 +43,7 @@ export function listPendingProposals(stashDir) {
     return listProposals(resolveStash(stashDir), { status: "pending" });
 }
 export function akmProposalList(options = {}) {
-    const stash = resolveStash(options.stashDir);
+    const { stashDir: stash } = resolveProposalQueue(options.stashDir, options.queue, options.config);
     // `--status accepted|rejected|reverted` implies archive-inclusion since the
     // live queue only ever contains pending entries.
     const includeArchive = options.includeArchive === true ||
@@ -50,19 +59,37 @@ export function akmProposalList(options = {}) {
     return { schemaVersion: 1, totalCount: proposals.length, proposals };
 }
 export function akmProposalShow(options) {
-    const stash = resolveStash(options.stashDir);
-    const proposal = getProposal(stash, options.id);
+    const queue = resolveProposalQueue(options.stashDir, options.queue, options.config);
+    const stash = queue.stashDir;
+    const proposal = resolveProposalId(stash, options.id);
+    let validation = validateProposal(proposal);
+    // An explicit stashDir without config is an in-process storage test seam; it
+    // has no authenticated write-target context to preflight against.
+    if (validation.ok &&
+        proposal.status === "pending" &&
+        (options.config !== undefined || options.stashDir === undefined)) {
+        try {
+            preflightProposalPromotion(options.config ?? loadConfig(), proposal, { queueTarget: queue.target });
+        }
+        catch (error) {
+            validation = {
+                ok: false,
+                findings: [{ kind: "promotion", message: error instanceof Error ? error.message : String(error) }],
+            };
+        }
+    }
     return {
         schemaVersion: 1,
         proposal,
-        validation: validateProposal(proposal),
+        validation,
     };
 }
 export async function akmProposalAccept(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     const resolvedId = resolveProposalId(stash, options.id).id;
-    const result = await promoteProposal(stash, config, resolvedId, { target: options.target }, options.ctx);
+    const result = await promoteProposal(stash, config, resolvedId, { target: options.target, queueTarget: queue.target, gateDecision: options.gateDecision }, options.ctx);
     return {
         schemaVersion: 1,
         ok: true,
@@ -74,11 +101,14 @@ export async function akmProposalAccept(options) {
 }
 export async function akmProposalReject(options) {
     return withAssetMutationLease("proposal-reject", async () => {
-        const stash = resolveStash(options.stashDir);
         const config = options.config ?? loadConfig();
-        const proposalId = resolveProposalId(stash, options.id).id;
+        const { stashDir: stash } = resolveProposalQueue(options.stashDir, options.queue, config);
+        // resolveProposalIdForReject tolerates a legacy row whose metadata fails
+        // strict decoding — resolveProposalId's exact-UUID match would otherwise
+        // throw here, before the terminal-status machinery even runs.
+        const proposalId = resolveProposalIdForReject(stash, options.id, options.ctx);
         await recoverProposalTransactionsForStash(stash, config, options.ctx, proposalId);
-        const updated = rejectProposalDurably(stash, proposalId, options.reason, options.ctx);
+        const updated = rejectProposalDurably(stash, proposalId, options.reason, options.ctx, options.gateDecision);
         return {
             schemaVersion: 1,
             ok: true,
@@ -90,10 +120,11 @@ export async function akmProposalReject(options) {
     });
 }
 export function akmProposalDiff(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     const proposal = resolveProposalId(stash, options.id);
-    const diff = diffProposal(stash, config, proposal.id, { target: options.target });
+    const diff = diffProposal(stash, config, proposal.id, { target: options.target, queueTarget: queue.target });
     return {
         schemaVersion: 1,
         id: proposal.id,
@@ -104,12 +135,15 @@ export function akmProposalDiff(options) {
     };
 }
 export function akmProposalCreate(options) {
-    const stash = resolveStash(options.stashDir);
+    const queue = resolveProposalQueue(options.stashDir, options.queue, options.config);
+    const stash = queue.stashDir;
+    const target = options.target ?? (queue.target ? { source: queue.target.source.name, root: queue.target.source.path } : undefined);
     // Manual proposal creation (via `akm proposal create`) always bypasses
     // dedup/cooldown guards — the operator is explicitly requesting a proposal.
     const result = createProposal(stash, {
         ref: options.ref,
         source: options.source,
+        ...(target !== undefined ? { target } : {}),
         ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
         payload: options.payload,
         force: true,
@@ -137,10 +171,11 @@ export function akmProposalCreate(options) {
  * `rejected`.
  */
 export async function akmProposalRevert(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     const resolvedId = resolveProposalId(stash, options.id).id;
-    const result = await revertProposal(stash, config, resolvedId, { target: options.target }, options.ctx);
+    const result = await revertProposal(stash, config, resolvedId, { target: options.target, queueTarget: queue.target }, options.ctx);
     return {
         schemaVersion: 1,
         ok: true,
@@ -158,7 +193,8 @@ export async function akmProposalRevert(options) {
  * dry-run record shape. The destructive-confirmation prompt stays CLI-side.
  */
 export async function bulkAdjudicateProposals(options) {
-    const stashDir = resolveStash(options.stashDir);
+    const config = options.config ?? loadConfig();
+    const { stashDir } = resolveProposalQueue(options.stashDir, options.queue, config);
     const pending = listProposals(stashDir, { status: "pending" }).filter((p) => {
         if (p.source !== options.generator)
             return false;
@@ -180,10 +216,10 @@ export async function bulkAdjudicateProposals(options) {
             results.push({ id: proposal.id, ref: proposal.ref, source: proposal.source, dryRun: true });
         }
         else if (options.action === "accept") {
-            results.push(await akmProposalAccept({ id: proposal.id, target: options.target }));
+            results.push(await akmProposalAccept({ stashDir, id: proposal.id, queue: options.queue, target: options.target, config }));
         }
         else {
-            results.push(await akmProposalReject({ id: proposal.id, reason: options.reason }));
+            results.push(await akmProposalReject({ stashDir, id: proposal.id, queue: options.queue, reason: options.reason, config }));
         }
     }
     return { count: results.length, results };

package/dist/commands/proposal/propose-cli.js

@@ -0,0 +1,88 @@
+// 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/.
+/**
+ * `akm proposal new` — the asset-authoring entry point (formerly the
+ * top-level `akm propose`, moved under the `proposal` group per the 0.9 CLI
+ * overhaul, S8). Shares no private helper with the proposal MANAGEMENT
+ * family (list/show/accept/reject/…, `./proposal-cli.ts`) — its path/name
+ * helpers come from the shared src/core/asset/asset-create.ts module.
+ *
+ * Keeps the inline `runWithJsonErrors` form (branches on the result and sets
+ * `process.exitCode` conditionally on a failed proposal) rather than
+ * migrating to `defineJsonCommand`, matching the original contribute-cli.ts
+ * rationale: `process.exitCode` (not `process.exit()`) so the process still
+ * exits via natural event-loop drain rather than skipping pending cleanup.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { defineCommand } from "citty";
+import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
+import { UsageError } from "../../core/errors.js";
+import { akmPropose } from "./propose.js";
+const EXIT_GENERAL = EXIT_CODES.GENERAL;
+export const proposeCommand = defineCommand({
+    meta: {
+        name: "new",
+        description: "Ask the configured agent CLI to author a brand-new asset and queue it as a proposal",
+    },
+    // Raw defineCommand: declare the global output flags so their space-separated
+    // values are consumed rather than shifting the `type` / `name` positionals.
+    args: {
+        ...GLOBAL_OUTPUT_ARGS,
+        // Optional in citty so run() is invoked when omitted; we re-validate
+        // below to surface a structured UsageError (exit 2) instead of citty's
+        // default help-banner exit-0.
+        type: { type: "positional", description: "Asset type (skill, command, knowledge, lesson, ...)", required: false },
+        name: {
+            type: "positional",
+            description: "Asset name (flat, no '/'; use --path for a subdirectory)",
+            required: false,
+        },
+        path: {
+            type: "string",
+            description: "Relative subdirectory under the type dir to place the proposed asset in (e.g. 'release'). The filename comes from the name.",
+        },
+        task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
+        file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
+        engine: { type: "string", description: "Engine to use (defaults to defaults.engine)" },
+        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            // citty silently shows help and exits 0 when required positionals are
+            // omitted. Re-validate explicitly so the exit code is 2 (USAGE) and a
+            // structured JSON error reaches scripted callers.
+            const taskFromFlag = typeof args.task === "string" ? args.task : undefined;
+            const fileFromFlag = typeof args.file === "string" ? args.file : undefined;
+            if (!args.type || !args.name || (!taskFromFlag && !fileFromFlag)) {
+                throw new UsageError("Usage: akm proposal new <type> <name> (--task '<task>' | --file <path>).", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and exactly one of --task or --file.");
+            }
+            if (taskFromFlag && fileFromFlag) {
+                throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
+            }
+            // `name` is flat; subdirectory placement is `--path`'s job.
+            assertFlatAssetName(String(args.name));
+            const proposedName = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), String(args.name));
+            const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
+            const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
+            const result = await akmPropose({
+                type: String(args.type),
+                name: proposedName,
+                task: taskText,
+                engine: getStringArg(args, "engine"),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            });
+            output("proposal-new", result);
+            if (result.ok === false) {
+                // Same reasoning as agentCommand in contribute-cli.ts: output() already
+                // ran, this is the last statement in the handler, so process.exitCode +
+                // return is equivalent without skipping any pending cleanup.
+                process.exitCode = EXIT_GENERAL;
+                return;
+            }
+        });
+    },
+});

package/dist/commands/proposal/propose.js

@@ -20,12 +20,14 @@ import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
-import { deriveEntryProvenance, deriveInstallations, slugForPath } from "../../indexer/installations.js";
+import { warn } from "../../core/warn.js";
+import { deriveEntryProvenance } from "../../indexer/installations.js";
+import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { buildProposePrompt, parseAgentProposalPayload } from "../../integrations/agent/prompts.js";
 import { collectDispatchSensitiveValues, executeRunner } from "../../integrations/agent/runner-dispatch.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
-import { createProposal, isProposalSkipped, } from "./repository.js";
+import { createProposal, isProposalSkipped, resolveProposalQueueTarget, } from "./repository.js";
 function failureEnvelope(result, type, name, engine, fallbackReason = "non_zero_exit") {
     return {
         ...baseFailureFields(result, fallbackReason),
@@ -44,8 +46,7 @@ function failureEnvelope(result, type, name, engine, fallbackReason = "non_zero_
  * uses). Matches `createProposal`'s durable `proposals.ref` mint, so the entry
  * event, the fallback ref, and the stored proposal all carry one spelling.
  */
-function proposeItemRef(stashDir, type, name) {
-    const bundleId = deriveInstallations([{ path: stashDir, writable: true }])[0]?.id ?? slugForPath(stashDir);
+function proposeItemRef(bundleId, type, name) {
     return deriveEntryProvenance({ bundleId, componentId: bundleId, adapterId: "akm" }, type, name).itemRef;
 }
 /**
@@ -53,10 +54,10 @@ function proposeItemRef(stashDir, type, name) {
  * fully-qualified item_ref the durable proposal is minted under
  * (`proposeItemRef`), so the entry event and the stored proposal agree.
  */
-function emitProposeInvoked(stash, options) {
+function emitProposeInvoked(bundleId, options) {
     appendEvent({
         eventType: "propose_invoked",
-        ref: proposeItemRef(stash, options.type, options.name),
+        ref: proposeItemRef(bundleId, options.type, options.name),
         metadata: {
             type: options.type,
             name: options.name,
@@ -79,15 +80,21 @@ export async function akmPropose(options) {
         throw new UsageError(`propose: unknown asset type "${options.type}". Known types: ${[...placementTypes()].sort().join(", ")}.`, "INVALID_FLAG_VALUE");
     }
     const stash = options.stashDir ?? resolveStashDir();
-    // 1. Always emit `propose_invoked` (extracted: emitProposeInvoked).
-    emitProposeInvoked(stash, options);
-    // 2. Resolve the selected engine exactly once. Propose accepts either kind;
+    // 1. Resolve the selected engine and write target exactly once.
     // the LLM arm uses the caller-specific plain-chat handler below.
     const config = options.agentConfig ?? (await import("../../core/config/config.js")).loadConfig();
-    const engineName = options.engine ?? config.defaults?.engine;
+    const target = resolveProposalQueueTarget(stash, config);
+    emitProposeInvoked(target.source, options);
+    const { config: engineConfig, fallbackEngineName } = withEngineFallback(config);
+    const engineName = options.engine ?? engineConfig.defaults?.engine;
+    // Announced, never silent: `options.engine` outranks the default, so the
+    // fallback is only reportable when it is the engine actually selected.
+    const engineAnnouncement = fallbackAnnouncement(fallbackEngineName, engineName);
+    if (engineAnnouncement)
+        warn(engineAnnouncement);
     if (!engineName)
-        throw new ConfigError("propose requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
-    const runner = resolveEngine(engineName, config);
+        throw new ConfigError(`propose ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
+    const runner = resolveEngine(engineName, engineConfig);
     const profile = runner.kind === "llm" ? undefined : runner.profile;
     // 3. Build prompt.
     // Synthesize a temp draft path so opencode can write the asset content
@@ -158,7 +165,7 @@ export async function akmPropose(options) {
         const draftContent = fs.readFileSync(resolvedDraftPath, "utf8");
         fs.unlinkSync(resolvedDraftPath);
         payload = {
-            ref: proposeItemRef(stash, options.type, options.name), // WI-8.5a item_ref flip
+            ref: proposeItemRef(target.source, options.type, options.name),
             content: draftContent,
         };
     }
@@ -201,7 +208,7 @@ export async function akmPropose(options) {
     // 6. Insert the proposal. Note: we allow the agent's `ref` to normalise the
     // asset name (e.g. path-cleanup), but only after validating that the ref is
     // well-formed and the type still matches the requested type.
-    const expectedRef = proposeItemRef(stash, options.type, options.name); // WI-8.5a item_ref flip
+    const expectedRef = proposeItemRef(target.source, options.type, options.name);
     let ref = expectedRef;
     if (payload.ref) {
         let parsedRef;
@@ -236,12 +243,13 @@ export async function akmPropose(options) {
                 ...(result.stderr ? { stderr: result.stderr } : {}),
             };
         }
-        ref = proposeItemRef(stash, parsedRef.type, parsedRef.name); // WI-8.5a item_ref flip
+        ref = proposeItemRef(target.source, parsedRef.type, parsedRef.name);
     }
     const createInput = {
         ref,
         source: "propose",
         sourceRun: `propose-${Date.now()}`,
+        target,
         // User-initiated proposals always bypass dedup/cooldown guards — the
         // operator is explicitly asking for a new proposal.
         force: true,