akm-cli 0.9.31 → 0.10.26101002-alpha

package/dist/workflows/runtime/run-plan.js

@@ -5,9 +5,10 @@
  * Reading a run row's frozen plan: the ONE plan decoder and its tolerant
  * row-level wrapper.
  *
- * {@link decodeWorkflowPlan} accepts every plan shape a release has stored —
- * irVersion 4 and 5 (with their `sourceReadSet` and host-identity fields) as
- * well as the current one — and keeps keys it does not know rather than
+ * {@link decodeWorkflowPlan} accepts every plan shape a release at or above
+ * the 0.9.15 floor has stored — irVersion 5 (with its `sourceReadSet` and
+ * host-identity fields, which 0.9.15 and 0.9.16 wrote) as well as the current
+ * one — and keeps keys it does not know rather than
  * refusing them. It rejects only a plan it cannot run: no steps, a unit with
  * no frozen target, a request that does not decode. `plan_ir_version` and
  * `plan_hash` are informational columns: neither gates execution. A plan that
@@ -62,30 +63,17 @@ export function frozenStepRows(plan) {
             ? step.root.kind === "map"
                 ? step.root.template.instructions
                 : step.root.instructions
-            : routeInstructions(step.route),
+            : "",
         completionJson: step.gate.criteria.length > 0 ? JSON.stringify(step.gate.criteria) : null,
         sequenceIndex: step.sequenceIndex,
     }));
 }
-function routeInstructions(route) {
-    const branches = Object.entries(route.when)
-        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-        .map(([match, stepId]) => `"${match}" -> ${stepId}`);
-    if (route.defaultStepId !== undefined)
-        branches.push(`default -> ${route.defaultStepId}`);
-    return `Route on ${route.input}: ${branches.join(", ")}.`;
-}
 /** Decode a stored plan (any release's) into the one plan type. */
 export function decodeWorkflowPlan(input, options = {}) {
     const raw = record(input, "plan");
     if (!Array.isArray(raw.steps) || raw.steps.length === 0)
         fail("steps must be a non-empty array");
     const steps = raw.steps.map((value, index) => decodeStep(value, index));
-    if (raw.outputs !== undefined) {
-        for (const [name, entry] of Object.entries(record(raw.outputs, "outputs"))) {
-            string(record(entry, `outputs.${name}`).from, `outputs.${name}.from`);
-        }
-    }
     const sourceHash = typeof raw.sourceHash === "string" ? raw.sourceHash : legacySourceHash(raw.sourceReadSet, options.workflowRef);
     return {
         ...raw,
@@ -109,28 +97,18 @@ function legacySourceHash(readSet, workflowRef) {
 function decodeStep(value, index) {
     const step = record(value, `step ${index}`);
     const stepId = string(step.stepId, `step ${index} stepId`);
-    const route = step.route === undefined ? undefined : decodeRoute(step.route, stepId);
-    const root = step.root === undefined ? undefined : decodeNode(step.root, stepId);
-    if (!root && !route)
-        fail(`step ${stepId} has neither a frozen root nor a route`);
+    if (step.root === undefined)
+        fail(`step ${stepId} has no frozen root`);
+    const root = decodeNode(step.root, stepId);
     return {
         ...step,
         stepId,
         title: typeof step.title === "string" ? step.title : stepId,
         sequenceIndex: index,
-        ...(root ? { root } : {}),
-        ...(route ? { route } : {}),
+        root,
         gate: decodeGate(step.gate, stepId),
     };
 }
-function decodeRoute(value, stepId) {
-    const route = record(value, `step ${stepId} route`);
-    string(route.input, `step ${stepId} route.input`);
-    const when = record(route.when, `step ${stepId} route.when`);
-    for (const target of Object.values(when))
-        string(target, `step ${stepId} route target`);
-    return route;
-}
 function decodeNode(value, stepId) {
     const node = record(value, `step ${stepId} root`);
     if (node.kind !== "map")
@@ -154,7 +132,6 @@ function decodeUnit(node, stepId) {
         id,
         instructions: typeof node.instructions === "string" ? node.instructions : "",
         onError: node.onError === "continue" ? "continue" : "fail",
-        isolation: node.isolation === "worktree" ? "worktree" : "none",
         frozenTarget: decodeTarget(node.frozenTarget, label),
         environment: Array.isArray(node.environment)
             ? node.environment.map((binding, index) => decodeEnvironmentBinding(binding, `${label} environment[${index}]`))
@@ -180,11 +157,7 @@ function decodeGate(value, stepId) {
 function decodeTarget(value, label) {
     const target = record(value, `${label} frozenTarget`);
     const inputBindings = decodeInputBindings(target.inputBindings, label);
-    const gitCommitOid = typeof target.gitCommitOid === "string" ? target.gitCommitOid : undefined;
-    const optional = {
-        ...(gitCommitOid ? { gitCommitOid } : {}),
-        ...(inputBindings ? { inputBindings } : {}),
-    };
+    const optional = inputBindings ? { inputBindings } : {};
     switch (target.kind) {
         case "command":
             return decodeCommandTarget(target, label);
@@ -196,20 +169,6 @@ function decodeTarget(value, label) {
                 cwdIdentity: record(target.cwdIdentity, `${label} cwdIdentity`),
                 ...optional,
             };
-        case "script":
-            return {
-                kind: "script",
-                ref: string(target.ref, `${label} script ref`),
-                contentHash: string(target.contentHash, `${label} contentHash`),
-                exec: decodeExec(target.exec, label),
-                interpreter: string(target.interpreter, `${label} interpreter`),
-                extension: string(target.extension, `${label} extension`),
-                bytesBase64: typeof target.bytesBase64 === "string" ? target.bytesBase64 : fail(`${label} has no script bytes`),
-                byteLength: typeof target.byteLength === "number" ? target.byteLength : 0,
-                cwdIdentity: record(target.cwdIdentity, `${label} cwdIdentity`),
-                materialization: "ephemeral-0700-delete",
-                ...optional,
-            };
         case "child-workflow":
             return {
                 kind: "child-workflow",
@@ -217,7 +176,7 @@ function decodeTarget(value, label) {
                 planHash: string(target.planHash, `${label} planHash`),
                 frozenPlan: decodeWorkflowPlan(target.frozenPlan),
                 contentHash: string(target.contentHash, `${label} contentHash`),
-                via: target.via === "task" ? "task" : "direct",
+                ...(target.via === "task" || target.via === "direct" ? { via: target.via } : {}),
                 ...(typeof target.taskRef === "string" ? { taskRef: target.taskRef } : {}),
                 ...(inputBindings ? { inputBindings } : {}),
             };
@@ -247,7 +206,6 @@ function decodeCommandTarget(target, label) {
         ...(target.cwdIdentity && typeof target.cwdIdentity === "object"
             ? { cwdIdentity: target.cwdIdentity }
             : {}),
-        ...(typeof target.gitCommitOid === "string" ? { gitCommitOid: target.gitCommitOid } : {}),
         ...(inputBindings ? { inputBindings } : {}),
     };
 }

package/dist/workflows/runtime/runs.js

@@ -13,12 +13,11 @@ import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
 import { frozenSummaryJudge } from "../exec/frozen-judge.js";
 import { detectSecretShapedParams } from "../exec/param-secrets.js";
 import { freezeWorkflow } from "../freeze/freeze.js";
-import { materializeWorkflowParameterFlags, validateWorkflowParams } from "../ir/params.js";
+import { applyWorkflowParamDefaults, materializeWorkflowParameterFlags, validateWorkflowParams, } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
 import { clip, WORKFLOW_UNIT_DIAGNOSTIC_CLIP } from "../resource-limits.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
-import { resolveWorkflowRunOutputs } from "./run-outputs.js";
 import { frozenStepRows, readRunPlan } from "./run-plan.js";
 import { canonicalizeWorkflowRefInput, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
 /**
@@ -76,9 +75,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
     if (options?.parameterFlags?.length && Object.keys(params).length > 0) {
         throw new UsageError("Workflow parameters must use either an object or per-parameter flags, not both.");
     }
-    const effectiveParams = options?.parameterFlags?.length
-        ? materializeWorkflowParameterFlags(plan, options.parameterFlags)
-        : params;
+    const effectiveParams = applyWorkflowParamDefaults(plan, options?.parameterFlags?.length ? materializeWorkflowParameterFlags(plan, options.parameterFlags) : params);
     // Non-fatal WARNINGS: untyped-step and undeclared-param advisories surface
     // as `warn()` lines at start (stderr, consistent with the repo's other
     // author-facing warnings) without blocking the run.
@@ -394,10 +391,9 @@ export async function completeWorkflowStep(input) {
     return withWorkflowRunsRepo((repo) => {
         let updatedRun;
         let refreshedSteps = [];
-        let outputWarnings;
         repo.transaction(() => {
             const run = readWorkflowRun(repo, input.runId);
-            const plan = requireRunPlan(run);
+            const _plan = requireRunPlan(run);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
@@ -428,15 +424,6 @@ export async function completeWorkflowStep(input) {
             });
             refreshedSteps = readWorkflowRunSteps(repo, run.id);
             const state = deriveRunState(refreshedSteps);
-            // Declared outputs resolve inside this transaction once the run
-            // completes; a failure rolls the step completion back whole.
-            let outputsJson; // undefined = untouched, keep the row's existing value
-            if (state.status === "completed" && plan.outputs) {
-                const resolved = resolveWorkflowRunOutputs(plan, refreshedSteps);
-                outputsJson = JSON.stringify(resolved.outputs);
-                repo.setRunOutputs(run.id, outputsJson);
-                outputWarnings = resolved.errors;
-            }
             repo.updateRunState({
                 status: state.status,
                 currentStepId: state.currentStepId,
@@ -450,16 +437,9 @@ export async function completeWorkflowStep(input) {
                 current_step_id: state.currentStepId,
                 updated_at: completedAt,
                 completed_at: state.completedAt,
-                ...(outputsJson !== undefined ? { outputs_json: outputsJson } : {}),
             };
         });
         const detail = buildWorkflowRunDetail(repo, updatedRun, refreshedSteps);
-        if (outputWarnings?.length) {
-            const messages = outputWarnings.map((e) => `Workflow run ${input.runId} declared ${e}`);
-            for (const message of messages)
-                warn(message);
-            detail.warnings = [...(detail.warnings ?? []), ...messages];
-        }
         // #11: emit `workflow_step_completed` ONLY for a genuine `completed`
         // transition; every other non-pending status (failed/skipped/blocked)
         // carries the honest `workflow_step_updated` name. The status is ALWAYS
@@ -680,10 +660,7 @@ function toWorkflowRunSummary(run) {
         agentHarness: run.agent_harness ?? null,
         agentSessionId: run.agent_session_id ?? null,
         planIrVersion: run.plan_ir_version ?? null,
-        // P3b: all three optional and conditionally spread, so every
-        // pre-existing (non-child, no-outputs-declared) run's envelope is
-        // byte-identical.
-        ...(run.outputs_json ? { outputs: parseJsonObject(run.outputs_json) ?? {} } : {}),
+        // Optional and conditionally spread, so a non-child run's envelope is unchanged.
         ...(run.parent_run_id ? { parentRunId: run.parent_run_id } : {}),
         ...(run.parent_unit_id ? { spawnedByUnitId: run.parent_unit_id } : {}),
     };

package/dist/workflows/source-files.js

@@ -4,11 +4,9 @@
 /**
  * Authoritative workflow-source ownership.
  *
- * Markdown and the bounded GitHub-shaped YAML subset are peer authoring
- * formats, but one canonical workflow ref must have exactly one source file.
- * This module is the shared filesystem arbitration point used before indexing,
- * cache reuse, lookup/show, and runtime load/start. It never chooses one
- * extension by priority: two recognized siblings are a hard collision.
+ * One canonical workflow ref must have exactly one source file. This module
+ * is the shared filesystem arbitration point used before indexing, cache
+ * reuse, lookup/show, and runtime load/start.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -29,7 +27,7 @@ export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
     constructor(canonicalName, sourcePaths) {
         const sorted = [...sourcePaths].sort(compareCodePoints);
         super(`Workflow "${canonicalName}" resolves to multiple workflow source files: ${sorted.join(", ")}. ` +
-            "A canonical workflow ref must be owned by exactly one recognized .md or .yml source; remove or rename the duplicate.", "RESOURCE_ALREADY_EXISTS", sorted);
+            "A canonical workflow ref must be owned by exactly one recognized .md source; remove or rename the duplicate.", "RESOURCE_ALREADY_EXISTS", sorted);
         this.name = "WorkflowSourceCollisionError";
         this.canonicalName = canonicalName;
         Object.setPrototypeOf(this, new.target.prototype);
@@ -46,15 +44,15 @@ export class WorkflowSourceIdentityError extends UsageError {
 export class WorkflowSourceNameError extends WorkflowSourceRejectionError {
     constructor(sourcePath, nestedSuffix) {
         super(`Workflow source filename ${sourcePath} has an extensionless stem ending in recognized workflow suffix "${nestedSuffix}". ` +
-            "Nested workflow suffixes are invalid; remove the inner .md or .yml suffix instead of relying on repeated stripping.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
+            "Nested workflow suffixes are invalid; remove the inner .md suffix instead of relying on repeated stripping.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
         this.name = "WorkflowSourceNameError";
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 export class WorkflowSourceLinkIdentityError extends WorkflowSourceRejectionError {
     constructor(sourcePath, targetPath) {
-        super(`Workflow source ${sourcePath} resolves through a symlink to ${targetPath} with a different source format. ` +
-            "The authored workflow path and resolved source must use the same .md or .yml format.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
+        super(`Workflow source ${sourcePath} resolves through a symlink to ${targetPath} with a different extension. ` +
+            "The authored workflow path and resolved source must both be .md.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
         this.name = "WorkflowSourceLinkIdentityError";
         Object.setPrototypeOf(this, new.target.prototype);
     }
@@ -240,13 +238,13 @@ function inspectWorkflowSourceDomain(candidates, canonicalName, realRoot) {
 function pickWorkflowSource(adapterId, canonicalName, sources) {
     if (sources.length <= 1)
         return sources[0];
-    const winner = [...sources].sort((left, right) => left.format === right.format ? 0 : left.format === "markdown" ? -1 : 1)[0];
+    const winner = sources[0];
     const shadowed = sources.filter((source) => source !== winner);
     const displayName = adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName;
-    warnOnce(`workflow-source-collision:${displayName}`, `Workflow "${displayName}" has both a .md and .yml source (${shadowed
+    warnOnce(`workflow-source-collision:${displayName}`, `Workflow "${displayName}" has several sources (${shadowed
         .map((source) => source.relativePath)
-        .join(", ")} shadowed by ${winner?.relativePath}); using the .md source. Remove the shadowed sibling to ` +
-        "silence this warning.");
+        .join(", ")} shadowed by ${winner?.relativePath}); using ${winner?.relativePath}. Remove the shadowed ` +
+        "sibling to silence this warning.");
     return winner;
 }
 function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
@@ -297,7 +295,6 @@ function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
             realPath,
             relativePath: candidate.relativePath,
             canonicalName,
-            format: candidate.lowerExtension === ".md" ? "markdown" : "github-yaml",
         },
     };
 }
@@ -321,8 +318,7 @@ export function assertIndexedWorkflowSourceIdentity(ref, indexedPath, authoritat
         throw new WorkflowSourceIdentityError(ref, indexedPath, authoritative.path);
     }
     const indexedExtension = path.extname(indexedPath).toLowerCase();
-    const authoritativeExtension = authoritative.format === "markdown" ? ".md" : ".yml";
-    if (indexedExtension !== authoritativeExtension) {
+    if (indexedExtension !== ".md") {
         throw new WorkflowSourceIdentityError(ref, indexedPath, authoritative.path);
     }
 }

package/dist/workflows/source-semantics.js

@@ -1,12 +1,9 @@
 // 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/.
-/** Semantic checks shared by the workflow grammars (`parser.ts`, `github-yaml.ts`) and freeze. */
+/** Semantic checks for the Markdown workflow grammar (`parser.ts`). */
 import fs from "node:fs";
 import path from "node:path";
-import { parseBuiltinCommandAction } from "../commands/command/builtin-action.js";
-import { classifyTargetRef } from "../execution/target-ref.js";
-import { parseSchedule } from "../tasks/schedule.js";
 export class WorkflowSourceSemanticError extends Error {
     code;
     constructor(code, message) {
@@ -15,36 +12,6 @@ export class WorkflowSourceSemanticError extends Error {
         this.name = "WorkflowSourceSemanticError";
     }
 }
-/** The argv a `run:` string executes under `shell`. */
-export function workflowShellCommand(shell, content) {
-    if (shell === "cmd")
-        return ["cmd", "/d", "/s", "/c", content];
-    if (shell === "pwsh" || shell === "powershell")
-        return [shell, "-Command", content];
-    return [shell, "-c", content];
-}
-export function canonicalizeWorkflowCron(value) {
-    const canonical = value.trim().split(/\s+/).join(" ");
-    if (canonical.startsWith("@") || canonical.split(" ").length !== 5) {
-        throw new WorkflowSourceSemanticError("invalid-cron", "GitHub schedule cron must use exactly five fields.");
-    }
-    try {
-        parseSchedule(canonical, "cron");
-    }
-    catch (cause) {
-        throw new WorkflowSourceSemanticError("invalid-cron", cause instanceof Error ? cause.message : "Invalid cron schedule.");
-    }
-    return canonical;
-}
-export function canonicalizeWorkflowRun(value) {
-    if (value.includes("${{")) {
-        throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions and contexts are not supported.");
-    }
-    if (value.includes("\0")) {
-        throw new WorkflowSourceSemanticError("invalid-exec-argv", "Local run may not contain NUL bytes.");
-    }
-    return value;
-}
 export function canonicalizeWorkflowWorkingDirectory(value, workspaceRoot) {
     if (hasControlCharacter(value)) {
         throw new WorkflowSourceSemanticError("working-directory-control-character", "working-directory may not contain NUL or control characters.");
@@ -74,65 +41,6 @@ function hasControlCharacter(value) {
     }
     return false;
 }
-export function classifyWorkflowStepUses(value) {
-    if (value.includes("${{")) {
-        throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions are unsupported in uses.");
-    }
-    if (value.length === 0 || value.trim() !== value || /\s/.test(value)) {
-        throw new WorkflowSourceSemanticError("unsupported-uses-target", "uses must be one exact, non-empty executable ref");
-    }
-    if (value === "akm/command")
-        return { kind: "builtin-command", ref: "akm/command" };
-    try {
-        return classifyTargetRef(value);
-    }
-    catch (cause) {
-        throw usesFailure(value, cause);
-    }
-}
-/**
- * Validate AKM's built-in command action at the shared source/decoder boundary.
- *
- * Inline YAML actions are portable templates and therefore use WP4's one
- * authoritative template validator. Markdown prose is explicitly `literal`,
- * while a stored ref remains resolution-owned because its template bytes are
- * not available until the later resolver loads the command asset.
- */
-export function validateWorkflowBuiltinCommand(value, mode) {
-    let action;
-    try {
-        action = parseBuiltinCommandAction(value);
-    }
-    catch (cause) {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", cause instanceof Error ? cause.message : "Invalid akm/command inputs.");
-    }
-    const expectedMode = action.kind === "stored" ? "stored-ref" : "portable-template";
-    const effectiveMode = mode ?? expectedMode;
-    if (action.kind === "stored") {
-        if (effectiveMode !== "stored-ref") {
-            throw new WorkflowSourceSemanticError("builtin-command-inputs", "Stored akm/command refs require commandMode stored-ref.");
-        }
-        return action;
-    }
-    if (effectiveMode === "stored-ref") {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", "Inline akm/command content cannot use commandMode stored-ref.");
-    }
-    if (effectiveMode === "literal" && action.arguments !== undefined) {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", "Literal akm/command content cannot declare arguments because no substitution occurs.");
-    }
-    return action;
-}
-function usesFailure(value, cause) {
-    const message = cause instanceof Error ? cause.message : String(cause);
-    const code = value.startsWith("docker://")
-        ? "docker-action-unsupported"
-        : value.startsWith("./") || value.startsWith("../") || value.startsWith("/")
-            ? "local-action-path-unsupported"
-            : /^(?:[A-Za-z0-9][A-Za-z0-9._-]*\/\/)?agents\//.test(value)
-                ? "non-executable-asset-ref"
-                : "unsupported-uses-target";
-    return new WorkflowSourceSemanticError(code, message);
-}
 function verifyPhysicalContainment(workspaceRoot, relative) {
     let root;
     try {

package/docs/README.md

@@ -17,7 +17,7 @@ Full per-directory indexes: [Guides](guides/README.md),
 - [Getting Started](guides/getting-started.md) -- Install akm, connect a source, and pull a curated shortlist in five to seven minutes
 - [Concepts](guides/concepts.md) -- Capabilities, bundles, adapters, asset types, and refs -- the mental model in one page
 - [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated (non-interactive) install for agents
-- `akm help agents` (short guide by default; `akm help agents --full` for the complete guide) -- The CLI reference agents load to use akm; always the embedded corpus at `src/assets/hints/cli-hints-{full,short}.md`
+- `akm hints` (complete guide by default; `akm hints --detail brief` for the short one) -- The CLI reference agents load to use akm; always the embedded corpus at `src/assets/hints/cli-hints-{full,short}.md`
 
 ## Use
 

package/docs/agents/README.md

@@ -3,8 +3,8 @@
 Documentation for wiring AI agents into akm.
 
 Run `akm hints` for the complete CLI reference agents should load into a
-system prompt, or `akm help agents` for the compact guide.
-(the short form is the default; pass `--full` for the complete guide). It always prints the embedded
+system prompt, or `akm hints --detail brief` for the compact guide.
+It always prints the embedded
 corpus at `src/assets/hints/cli-hints-full.md` / `cli-hints-short.md` --
 browse those files directly if you want to read the reference without running
 the CLI. There used to be a separate `docs/agents/AGENTS.md` /
@@ -12,4 +12,4 @@ the CLI. There used to be a separate `docs/agents/AGENTS.md` /
 re-diverging from the embedded copy with no test to catch it, so it was
 deleted and its still-true unique content was merged into the embedded files.
 
-- [Agent Install Guide](agent-install.md) -- Short redirect covering the install shape (binary, `akm setup --yes`, a source, an index, `akm help agents`); for the exact no-prompts command sequence, see the [headless install recipe](../guides/recipes/headless-install.md)
+- [Agent Install Guide](agent-install.md) -- Short redirect covering the install shape (binary, `akm setup --yes`, a source, an index, `akm hints`); for the exact no-prompts command sequence, see the [headless install recipe](../guides/recipes/headless-install.md)

package/docs/agents/agent-install.md

@@ -2,7 +2,7 @@
 
 `akm` is a portable capability library agents install and configure without
 interactive prompts: install the binary, run `akm setup --yes`, add a source,
-build the index, then expose `akm help agents` output to the agent so it
+build the index, then expose `akm hints` output to the agent so it
 knows how to search and load bundle content. Configuration lives in
 top-level keys validated against the config schema, and semantic search can
 run on local embeddings or a remote endpoint depending on what the host

package/docs/architecture/adapters.md

@@ -101,23 +101,21 @@ interface BundleAdapter {
   // reading authored bytes or walking the bundle.
   readCandidates?(c: BundleComponent, conceptId: string): Array<{ path: string; conceptId: string }>;
 
-  // OPTIONAL — placement / discovery.
-  placeNew?(c: BundleComponent, conceptId: string): string;   // where a new item would live
+  // OPTIONAL — discovery.
   directoryList?(c: BundleComponent): string[];               // owned dirs; feeds git exact-path staging
   looksLikeRoot?(root: string): boolean;                      // install-time probe
 }
 ```
 
 `recognize` and `validate` are required on every adapter; `index`,
-`affectedItems`, `readCandidates`, `placeNew`, `directoryList`, and
+`affectedItems`, `readCandidates`, `directoryList`, and
 `looksLikeRoot` are optional capability methods. An adapter overriding `index()` must keep
 `recognize()` coherent with it (conformance: `index()` == fold of
 `recognize()` over the core walk) or declare component-level
 incrementality.
 
-`readCandidates` is intentionally distinct from both `extensions` and
-`placeNew`: extensions are non-exhaustive walk hints, while placement is a
-write-normalization policy. Read candidates preserve canonical directory
+`readCandidates` is intentionally distinct from `extensions`: extensions are
+non-exhaustive walk hints. Read candidates preserve canonical directory
 manifests (for example `skills/<name>/SKILL.md`) so lookup, index-backed show, and workflow runtime share one
 physical-owner decision. Each candidate carries its canonical concept identity,
 so a byte-denying ownership probe never has to infer identity from the query.
@@ -145,30 +143,21 @@ concern.
 
 ---
 
-## `placeNew()` wiring status
+## Placement
 
-The interface declares `placeNew()` as an optional capability method, and 9
-of the 11 built-in adapters already implement it — all but `okf` and
-`website-snapshot` (`claude` and `opencode` inherit theirs from the shared
-tool-dir factory). **Nothing in the write path calls it yet**: AKM-native
-writes still resolve through AKM's own flat type→directory placement table
-(`src/core/asset/asset-placement.ts`'s `PLACEMENT_SPECS`), not through the
-owning adapter's `placeNew()`.
-
-Placement for every existing bundle is already correct today — this is a
-deliberately sequenced routing change, not unfinished behavior. It's
-scoped out of 0.9.0 by
-[D12](../architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010)
-and deferred to 0.10; nothing user-visible changes in 0.10 for this alone.
-See [STABILITY.md](../../STABILITY.md) ("On the horizon") for the
-up-to-date status if this changes.
+Adapters do not place new items. AKM-native writes resolve through AKM's own
+flat type→directory placement table (`src/core/asset/asset-placement.ts`'s
+`PLACEMENT_SPECS`), which is correct for akm-layout bundles — the only bundles
+the write commands touch in practice. A per-adapter `placeNew()` existed
+through 0.9 but nothing called it, and it was removed in 0.10. Supporting
+writable bundles in another layout would need it back: see
+[#1163](https://github.com/itlackey/akm/issues/1163).
 
 ---
 
 ## Write allowlists
 
-`placeNew()` wiring is a separate question from **which bundles AKM-native
-write commands are allowed to touch at all** — that's decided today by a
+Which bundles AKM-native write commands are allowed to touch at all is decided by a
 small allowlist check, `assertAkmAssetWrite` (`src/core/write-source.ts`),
 run before any write command touches the filesystem. It compares the target
 bundle's detected (or configured) adapter id against an allowlist and throws
@@ -181,12 +170,10 @@ The default allowlist is `["akm"]`. Two command families widen it explicitly:
 | `akm env create` / `env remove` / `secret set` | `dotenv` |
 | `akm workflow create` | `akm-workflow` |
 
-Every other adapter — including every adapter that already implements
-`placeNew()` (`agent-skills`, `claude`, `opencode`, `akm-task`,
-`generic-files`) — is rejected by every AKM-native write command in 0.9.0.
+Every other adapter (`agent-skills`, `claude`, `opencode`, `akm-task`,
+`generic-files`, and so on) is rejected by every AKM-native write command.
 `akm task add` in particular uses the *default* allowlist (`akm` only), so a
-standalone `akm-task` bundle is read-only through AKM-native write commands
-even though `akm-task`'s own `placeNew()` is implemented.
+standalone `akm-task` bundle is read-only through AKM-native write commands.
 
 Reading, searching, and `akm lint` are unaffected by this allowlist — only
 creating, editing, or deleting through AKM's own commands is restricted.
@@ -197,8 +184,7 @@ This allowlist boundary is also where AKM's [execution
 boundary](../guides/concepts.md) principle shows up on the write side: AKM
 retrieves and validates every supported format, but it only lets its own
 write commands mutate a narrow, explicitly-declared set of targets — it
-does not widen write access to a format just because that format's adapter
-happens to expose a `placeNew()` implementation.
+does not widen write access to a format just because it can read it.
 
 ---
 

package/docs/architecture/architecture.md

@@ -260,8 +260,7 @@ schema (`src/core/config/schema/sources-bundles.ts`).
 refresh.
 
 Write-target resolution (`resolveWriteTarget`) follows: an explicit
-destination flag (`--bundle` on `remember`/`clone`/`improve`, `--target` on
-`import`/env/secret mutations) -> `config.defaultWriteTarget` -> working
+destination flag (`--bundle`) -> `config.defaultWriteTarget` -> working
 bundle (`defaultBundle`) -> `ConfigError`. The resolved target keeps the
 optional configured selector separate from the stable `source.name`: APIs
 that must re-resolve a destination use the selector, while durable refs and
@@ -299,8 +298,8 @@ whose proposal queue is read or adjudicated; it does not override the proposal's
 write destination. Qualified proposals and unqualified proposals created in a
 configured secondary queue record the destination source name and materialized
 root. Diff, accept, and revert use that binding by default and reject an explicit
-`--target` that resolves elsewhere. An unbound short proposal requires either
-an explicit `--target` or an authenticated `--queue` context; it does not
+`--bundle` that resolves elsewhere. An unbound short proposal requires either
+an explicit `--bundle` or an authenticated `--queue` context; it does not
 inherit a default write target.
 
 ---
@@ -442,7 +441,7 @@ An explicit missing or incompatible engine is an error and never falls
 through to another configured engine.
 
 Task-v3 execution and durable workflow-v4 dispatch use this runtime boundary.
-Markdown and GitHub-shaped YAML compile through source IR v1; new starts freeze
+Markdown workflows compile through source IR v1; new starts freeze
 v4-family `irVersion: 5`. A stored plan that decodes runs whatever release
 froze it; one that does not is marked abandoned and `akm workflow run <ref>`
 starts afresh. Only a plan a newer akm froze is refused, naming the upgrade.