akm-cli 0.9.3 → 0.9.5

package/dist/commands/read/search.js

@@ -14,13 +14,10 @@
 import { getSources, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { isTransientStashPath } from "../../core/paths.js";
 import { resolveReadSources } from "../../indexer/read-preflight.js";
 import { searchLocal } from "../../indexer/search/db-search.js";
 import { getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
 import { getEntryIdByFilePath, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
-import { bumpUtilityScoresBatch } from "../../storage/repositories/index-utility-repository.js";
-import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
 import "../../sources/providers/index.js";
@@ -188,7 +185,7 @@ function usageSearchMode(mode) {
 function maybeLogSearchEvent(input, query, response, mode) {
     if (input.skipLogging)
         return;
-    logSearchEvent(query, response, mode, input.eventSource, input.disableScopedUtility === true, input.attributionProjection);
+    logSearchEvent(query, response, mode, input.eventSource, input.attributionProjection);
 }
 /**
  * Resolve entry IDs by file_path lookup (exact match, not LIKE).
@@ -229,7 +226,7 @@ function resolveEntryIds(db, hits) {
  * Per-entry events are recorded only for stash hits because registry hits
  * have no local entry_id to reference.
  */
-function logSearchEvent(query, response, mode = "keyword", eventSource = "user", disableScopedUtility = false, attributionProjection = "full") {
+function logSearchEvent(query, response, mode = "keyword", eventSource = "user", attributionProjection = "full") {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
@@ -276,25 +273,18 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
                     source: eventSource,
                 });
             }, TELEMETRY_BUSY_TIMEOUT_MS);
-            // Bump utility scores for all resolved entries (MemRL retrieval signal).
-            // The indexer overwrites these at next reindex; bumps are temporary hints.
-            // Gated to user-sourced events: pipeline searches (improve probes, task
-            // runner) must not feed the utility signal (meta-review 05 DRIFT-6 —
-            // the bump previously fired unconditionally, so even correctly-tagged
-            // machine traffic inflated utility). utility_scores stays in index.db.
-            const resolvedIds = eventSource === "user" ? resolved.map((r) => r.entryId).filter((id) => id !== undefined) : [];
-            if (resolvedIds.length > 0) {
-                let scopeKey;
-                try {
-                    const stashPath = response.bundleDir;
-                    const disabled = disableScopedUtility || (stashPath && isTransientStashPath(stashPath));
-                    scopeKey = disabled ? undefined : getCurrentWorkflowScopeKey();
-                }
-                catch {
-                    // Non-fatal — fall back to global-only bumps on any error.
-                }
-                bumpUtilityScoresBatch(db, resolvedIds, 1.0, 0.1, scopeKey);
-            }
+            // No live utility_scores/utility_scores_scoped write here (#862): a
+            // search result is an impression, not a signal that the asset was
+            // useful. Rewarding every returned hit created a feedback loop where
+            // merely appearing in results inflated future ranking — assets
+            // surfaced because they'd surfaced before, not because a user acted
+            // on them. Retrieval counts are still recorded above via
+            // insertUsageEvent (search_count) and rolled into utility_scores by
+            // the offline `recomputeUtilityScores` pass (`akm index`), which uses
+            // the show/search *select rate* — a ratio that requires an actual
+            // `show`/select event, not raw impressions. Explicit signal comes
+            // from `akm feedback` (applyFeedbackToUtilityScore) and from
+            // selection (recordShowUsage / the `select` event derived from it).
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {

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

@@ -27,11 +27,11 @@
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineGroupCommand, defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { TASK_RUN_BOOLEAN_FLAGS, TASK_RUN_VALUE_FLAGS } from "../../tasks/task-run-reserved-flags.js";
 import { akmTaskExplain } from "./explain.js";
-import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksRun, akmTasksSync } from "./tasks.js";
+import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksPrune, akmTasksRun, akmTasksSync, akmTasksSyncPlan, } from "./tasks.js";
 /** Shared `--bundle <bundle>` arg wired onto every task subcommand. */
 const bundleArg = {
     bundle: {
@@ -303,6 +303,18 @@ const tasksHistoryCommand = defineJsonCommand({
         output("task-history", result);
     },
 });
+/**
+ * #849: `task sync --dry-run`'s exit-code contract, "non-zero when the plan
+ * contains removals" — factored out as a pure function (rather than left
+ * inline in the command's `run()`) so it's directly unit-testable without
+ * driving the whole CLI through a real scheduler backend. #867: also
+ * non-zero when any source failed to parse/prepare — sync degrades (still
+ * reconciles the tasks/workflows that DID parse) rather than rejecting the
+ * whole set, but a dropped source must still surface as a failing exit.
+ */
+export function taskSyncDryRunExitCode(preview) {
+    return preview.hasRemovals || (preview.failures?.length ?? 0) > 0 ? EXIT_CODES.GENERAL : undefined;
+}
 const tasksSyncCommand = defineJsonCommand({
     meta: {
         name: "sync",
@@ -315,11 +327,33 @@ const tasksSyncCommand = defineJsonCommand({
             description: "Replace installed bindings with the current invocation",
             default: false,
         },
+        "dry-run": {
+            type: "boolean",
+            description: "Compute and print the full reconcile plan (adds/updates/removes, with owning bundle on every " +
+                "removal) without touching the OS scheduler. Zero durable writes. Exits non-zero when the plan " +
+                "contains removals.",
+            default: false,
+        },
     },
     async run({ args }) {
         rejectRetiredTaskTargetFlag();
-        const result = await akmTasksSync({}, args.bundle, { rebind: args.rebind === true });
+        const rebind = args.rebind === true;
+        if (args["dry-run"] === true) {
+            const preview = await akmTasksSyncPlan({}, args.bundle, { rebind });
+            output("task-sync-dry-run", preview);
+            const exitCode = taskSyncDryRunExitCode(preview);
+            if (exitCode !== undefined)
+                process.exitCode = exitCode;
+            return;
+        }
+        const result = await akmTasksSync({}, args.bundle, { rebind });
         output("task-sync", result);
+        // #867: sync degrades — sources that failed to parse/prepare are
+        // excluded from reconciliation and reported in `result.failed` rather
+        // than poisoning the whole sync, but their presence must still fail
+        // the command's exit code so the breakage stays visible.
+        if (result.failed.length > 0)
+            process.exitCode = EXIT_CODES.GENERAL;
     },
 });
 // ── `akm task explain` — read-only introspection (P2b Lane B, spec
@@ -364,6 +398,49 @@ const tasksDoctorCommand = defineJsonCommand({
         output("task-doctor", result);
     },
 });
+/**
+ * #851: `akm task prune`'s exit-code contract mirrors `task sync --dry-run`'s
+ * (`taskSyncDryRunExitCode` above) — non-zero whenever the preview lists
+ * removals the invocation didn't (or couldn't, without `--yes`) execute, so
+ * `akm task prune` is usable as a CI/health check the same way `sync
+ * --dry-run` is.
+ */
+export function taskPruneExitCode(result) {
+    return result.dryRun && result.preview.hasRemovals ? EXIT_CODES.GENERAL : undefined;
+}
+const tasksPruneCommand = defineJsonCommand({
+    meta: {
+        name: "prune",
+        description: "Remove installed scheduler entries `sync` can never reclaim because their own descriptor no longer " +
+            "resolves to a live bundle (corrupt/missing --scheduler-context, or the owning bundle directory is " +
+            "gone). Defaults to a dry-run preview — zero scheduler writes. Requires --yes to remove anything; " +
+            "--id narrows removal to specific binding ids (comma-separated).",
+    },
+    args: {
+        yes: {
+            type: "boolean",
+            description: "Execute removal of every currently-computed orphan (the plan is still printed first)",
+            default: false,
+        },
+        id: {
+            type: "string",
+            description: "Comma-separated scheduler binding id(s) to limit pruning to (must already be orphan candidates)",
+        },
+    },
+    async run({ args }) {
+        const id = args.id
+            ? args.id
+                .split(",")
+                .map((value) => value.trim())
+                .filter(Boolean)
+            : undefined;
+        const result = await akmTasksPrune({}, { yes: args.yes === true, id });
+        output("task-prune", result);
+        const exitCode = taskPruneExitCode(result);
+        if (exitCode !== undefined)
+            process.exitCode = exitCode;
+    },
+});
 export const taskCommand = defineGroupCommand({
     meta: {
         name: "task",
@@ -375,6 +452,7 @@ export const taskCommand = defineGroupCommand({
         explain: tasksExplainCommand,
         history: tasksHistoryCommand,
         sync: tasksSyncCommand,
+        prune: tasksPruneCommand,
         doctor: tasksDoctorCommand,
     },
     // Bare `akm task` reports scheduler diagnostics. Inspection of individual

package/dist/commands/tasks/tasks.js

@@ -35,7 +35,8 @@ import { exitCodeForStatus } from "../../tasks/run/task-result.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/schedule.js";
 import { assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "../../tasks/scheduler-binding.js";
 import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
-import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
+import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, buildSchedulerRemoveOperation, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
+import { renderSchedulerPlanPreview, renderSchedulerSyncPlanPreview, } from "../../tasks/scheduler-sync-preview.js";
 import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
 import { projectTaskSourceV4 } from "../../tasks/source/project-v4.js";
 import { TASK_V3_MAX_SOURCE_BYTES } from "../../tasks/source-v3.js";
@@ -326,7 +327,16 @@ export async function akmTasksHistory(input) {
  * scans all bundles. Activation happens only through explicit `add --bundle`
  * (or `sync --bundle` on a bundle whose task files are already present).
  */
-export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
+/**
+ * Compute (but never apply) a scheduler sync plan: everything through
+ * `finalizeSchedulerSyncPlan`'s final call, stopping strictly before
+ * `applySchedulerSyncPlan`. Shared by `akmTasksSync` (applies the plan) and
+ * `akmTasksSyncPlan` (#849 `--dry-run`, never applies it) so the two paths
+ * can never drift on what "the plan" means. `prepared?.publish`, the one
+ * deferred write-producing closure in this pipeline, is returned but never
+ * invoked here — only `applySchedulerSyncPlan` may call it.
+ */
+async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
     const resolved = resolveTaskReadBundle(undefined, bundleTarget);
     const config = loadConfig();
     const stashDir = resolved.source.path;
@@ -393,6 +403,10 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
             }
             : {}),
     }, preparedSources);
+    return { sched, plan, prepared, warnings };
+}
+export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
+    const { sched, plan, prepared, warnings } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
     await applySchedulerSyncPlan(sched, plan, prepared?.publish && plan.operations.some((operation) => operation.kind !== "remove")
         ? prepared.publish
         : undefined);
@@ -403,9 +417,110 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
         unchanged: [...plan.unchanged],
         skipped: [],
         backend: sched.name,
+        failed: plan.failures.map((failure) => ({ ...failure })),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
+/**
+ * `akm task sync --dry-run` (#849): compute the exact same plan
+ * `akmTasksSync` would apply, then return a non-mutating preview instead of
+ * calling `applySchedulerSyncPlan`. `buildSchedulerSyncPlan` is shared with
+ * the real sync path specifically so this can never see a different plan
+ * than the one a real sync would apply — and specifically so this function
+ * never even holds a reference to a callable `publish` closure past this
+ * point: `prepared.publish`, if any, is dropped on the floor here, never
+ * invoked. Zero durable writes, mirroring `akm workflow plan`.
+ */
+export async function akmTasksSyncPlan(deps = {}, bundleTarget, options = {}) {
+    const { sched, plan } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
+    return renderSchedulerSyncPlanPreview(sched.name, plan);
+}
+/**
+ * Classify one installed scheduler binding as a prune candidate (#851), using
+ * the same two signals `doctor`'s `inspectInstalledBinding` already computes
+ * — deliberately narrower than that function's full `status` set. Only an
+ * entry whose ownership can NEVER be resolved (`invalid-context`) or whose
+ * resolved owner no longer exists on disk (`dead-bundle-path`) is a
+ * candidate; `missing-path` (e.g. the akm binary itself moved) is a
+ * different failure mode and is intentionally NOT folded in here, per the
+ * scoping in #851 — an entry that still resolves to a live bundle is never a
+ * candidate, full stop.
+ */
+function classifyPruneCandidate(entry) {
+    let ownerBundlePath;
+    try {
+        ownerBundlePath = validateSchedulerContextDescriptor(entry.contextPath).environment.AKM_BUNDLE_DIR;
+    }
+    catch {
+        return "invalid-context";
+    }
+    if (ownerBundlePath !== undefined && !fs.existsSync(ownerBundlePath))
+        return "dead-bundle-path";
+    return undefined;
+}
+async function buildTaskPrunePlan(deps = {}, options = {}) {
+    const sched = deps.backend ?? selectBackend();
+    if (!sched.inspectBindings) {
+        throw new ConfigError(`Scheduler backend "${sched.name}" cannot provide one coherent inspection for prune.`, "INVALID_CONFIG_FILE");
+    }
+    const inspection = await sched.inspectBindings({});
+    const candidates = new Map();
+    for (const entry of inspection.installed) {
+        const reason = classifyPruneCandidate(entry);
+        if (reason)
+            candidates.set(entry.id, reason);
+    }
+    const requestedIds = options.id?.filter((id) => id.length > 0) ?? [];
+    for (const id of requestedIds) {
+        if (!candidates.has(id)) {
+            throw new UsageError(`Scheduler binding ${JSON.stringify(id)} is not an orphaned prune candidate ` +
+                "(either not installed, or it still resolves to a live bundle) — refusing to prune it.", "INVALID_FLAG_VALUE");
+        }
+    }
+    const idFilter = requestedIds.length > 0 ? new Set(requestedIds) : undefined;
+    const resolved = resolveTaskReadBundle(undefined, undefined);
+    const bundleContext = {
+        adapterId: resolved.source.adapterId ?? detectAdapterId(resolved.source.path),
+        bundleName: resolved.source.name,
+    };
+    const operations = [];
+    for (const entry of inspection.installed) {
+        const reason = candidates.get(entry.id);
+        if (!reason)
+            continue;
+        if (idFilter && !idFilter.has(entry.id))
+            continue;
+        const operation = buildSchedulerRemoveOperation(entry.id, entry, inspection.artifacts, bundleContext);
+        operations.push(Object.freeze({ ...operation, reason }));
+    }
+    return { sched, operations: Object.freeze(operations) };
+}
+/**
+ * `akm task prune` (#851): remove installed scheduler bindings `sync` can
+ * never reclaim because their own `--scheduler-context` descriptor doesn't
+ * resolve to a live bundle. Defaults to dry-run — no `--yes` and no `--id`
+ * means zero backend calls that could mutate anything, matching
+ * `akmTasksSyncPlan`'s zero-write guarantee. `--id` (one or more) narrows
+ * execution to exactly those bindings; `--yes` alone executes every
+ * currently-computed candidate. Both still return the full preview so the
+ * plan is never silent about what it did.
+ */
+export async function akmTasksPrune(deps = {}, options = {}) {
+    const { sched, operations } = await buildTaskPrunePlan(deps, options);
+    const preview = renderSchedulerPlanPreview(sched.name, operations);
+    if (!options.yes) {
+        return { backend: sched.name, dryRun: true, preview, removed: [] };
+    }
+    await applySchedulerTransaction(sched, operations, {
+        initialExpectations: operations.map((operation) => operation.expected),
+    });
+    return {
+        backend: sched.name,
+        dryRun: false,
+        preview,
+        removed: operations.map((operation) => operation.id),
+    };
+}
 export async function akmTasksDoctor(deps = {}) {
     const warnings = [];
     let invocation = {

package/dist/core/adapter/adapters/akm-adapter.js

@@ -82,10 +82,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, } from "../../../indexer/passes/metadata.js";
-import { assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
+import { assetPathCandidatesForName, assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
-import { recognizeMatch, recognizePathCandidateMatches } from "../recognize-match.js";
+import { recognizeMatch } from "../recognize-match.js";
 import { perTypeValidateChecks, skillDirectoryDiagnostics, workflowYamlSourceDiagnostics } from "./akm-lint.js";
 import { applyFoldedMetadata, foldRecognizedMetadata } from "./akm-metadata.js";
 import { hashContent, runBaseValidateChecks } from "./shared.js";
@@ -223,6 +223,8 @@ function indexDocumentFromEntry(entry, base, rendererName) {
         doc.tags = entry.tags;
     if (entry.content !== undefined)
         doc.content = entry.content;
+    if (entry.contentTruncated !== undefined)
+        doc.contentTruncated = entry.contentTruncated;
     if (entry.aliases !== undefined)
         doc.aliases = entry.aliases;
     if (entry.searchHints !== undefined)
@@ -252,14 +254,6 @@ function conceptIdForRecognizedType(root, filePath, type) {
     const stashDir = stashDirFor(type);
     return stashDir !== undefined ? `${stashDir}/${canonicalName}` : canonicalName;
 }
-function recognizePathCandidates(c, file) {
-    if (isReservedFileName(file.fileName) || akmStashAbstains(c.root, file.absPath))
-        return [];
-    return recognizePathCandidateMatches(file).flatMap((match) => {
-        const conceptId = conceptIdForRecognizedType(c.root, file.absPath, match.type);
-        return conceptId === undefined ? [] : [conceptId];
-    });
-}
 function recognize(c, file) {
     // D-R6 (spec §5.1): `index.md` / `log.md` are OKF reserved structural files at
     // every depth — never items. Excluded BEFORE classification so a directory
@@ -481,9 +475,19 @@ export const akmAdapter = {
         ".kts",
     ],
     recognize,
-    recognizePathCandidates,
     renderExecutionSource,
     validate,
+    /**
+     * Closed-form owner candidates (#857): every physical path spelling that
+     * could claim `conceptId` without walking the bundle. `deriveCanonicalAssetNameFromStashRoot`
+     * (recognize's own conceptId derivation) is a pure function of (type,
+     * filePath); this is its inverse, enumerated for the two placements that
+     * function can produce for one conceptId — CANONICAL (authored under the
+     * type's own stash subdir) and the LOOSE FALLBACK (authored anywhere else
+     * in the bundle, so the canonical name is the file's full path relative to
+     * the bundle root instead of the stash subdir). `assetPathCandidatesForName`
+     * additionally expands `env`'s `.env`/`<name>.env` duality on each.
+     */
     readCandidates(c, conceptId) {
         const posix = conceptId.replace(/\\/g, "/");
         const slash = posix.indexOf("/");
@@ -492,9 +496,14 @@ export const akmAdapter = {
         const head = posix.slice(0, slash);
         const rest = posix.slice(slash + 1);
         const type = stashDirToType(head);
-        return type === undefined || rest.length === 0
-            ? []
-            : [{ path: assetPathForName(type, path.join(c.root, head), rest), conceptId: posix }];
+        if (type === undefined || rest.length === 0)
+            return [];
+        const canonical = assetPathCandidatesForName(type, path.join(c.root, head), rest);
+        const loose = assetPathCandidatesForName(type, c.root, rest);
+        return [...new Set([...canonical, ...loose])].map((candidatePath) => ({
+            path: candidatePath,
+            conceptId: posix,
+        }));
     },
     /**
      * Type-driven placement (§5.1), reproducing `path-resolver.ts#buildDiskCandidates`:

package/dist/core/adapter/adapters/akm-lint.js

@@ -57,6 +57,7 @@ import { taskSourceErrorDetail } from "../../../tasks/source-v3.js";
 import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
 import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
 import { conceptIdForStashFile } from "../../asset/resolve-ref.js";
+import { isAkmRegistryCachePath } from "../../common.js";
 /** Recommended `category` values for facts — `commands/lint/fact-linter.ts:9`. */
 const KNOWN_CATEGORIES = new Set(["personal", "team", "project", "convention", "meta"]);
 /** Placeholder markers a workflow stub carries — `commands/lint/workflow-linter.ts:10`. */
@@ -336,7 +337,7 @@ function lineOf(err) {
  * like the established Markdown frontend without inventing another parser.
  */
 export function workflowYamlSourceDiagnostics(relPath, raw, parsePath, workspaceRoot) {
-    if (parsePath.includes("/.cache/") || parsePath.includes("/registry/"))
+    if (isAkmRegistryCachePath(parsePath))
         return { errors: [], warnings: [] };
     const compiled = compileWorkflowSource(raw, { path: parsePath, workspaceRoot });
     if (compiled.ok)
@@ -369,7 +370,7 @@ export function workflowYamlSourceDiagnostics(relPath, raw, parsePath, workspace
  */
 export function workflowFrontendDiagnostics(relPath, raw, parsePath) {
     const none = { errors: [], warnings: [] };
-    if (parsePath.includes("/.cache/") || parsePath.includes("/registry/"))
+    if (isAkmRegistryCachePath(parsePath))
         return none;
     const errors = [];
     const warnings = [];

package/dist/core/adapter/adapters/akm-task-adapter.js

@@ -17,12 +17,15 @@
  * ── validate (spec §6 task validation column) ──
  *
  * Validation enters the canonical task source parser (`parseTaskSource`,
- * task source v4 only as of P4 — a `version: 3` or `version: 2` document now
- * fails closed with `TASK_SCHEMA_VERSION_UNSUPPORTED`). That parser owns the
- * closed key sets, the executable-selector XOR, hostile YAML policy, the
- * `akm/command` builtin, bounds, and physical `working-directory`
- * containment. The adapter only translates a parser failure into the
- * format-family diagnostic shape.
+ * task source v4 native as of P4 — a `version: 3` or `version: 2` document
+ * is auto-read through the in-memory migration shim in
+ * `parse-task-source.ts`; only a version the shim's deterministic planners
+ * cannot convert, or any other unsupported number, fails closed with
+ * `TASK_SCHEMA_VERSION_UNSUPPORTED`). That parser owns the closed key sets,
+ * the executable-selector XOR, hostile YAML policy, the `akm/command`
+ * builtin, bounds, and physical `working-directory` containment. The
+ * adapter only translates a parser failure into the format-family
+ * diagnostic shape.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens

package/dist/core/adapter/adapters/dotenv-adapter.js

@@ -29,7 +29,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { assetPathForName, typeForStashDir } from "../../asset/asset-placement.js";
+import { assetPathCandidatesForName, assetPathForName, typeForStashDir } from "../../asset/asset-placement.js";
 import { dangerousEnvKeyDiagnostics } from "./akm-lint.js";
 import { hashContent } from "./shared.js";
 /** A dotenv bundle is single-component; its one component is `main`. */
@@ -103,12 +103,6 @@ function conceptIdForPath(type, relativePath) {
     const stripped = posix.replace(/\.env$/i, "");
     return stripped.endsWith("/") ? `${stripped}default` : stripped;
 }
-function recognizePathCandidates(_c, file) {
-    const type = classify(file.relPath);
-    if (type === null || hasSensitiveMarker(file.absPath, type))
-        return [];
-    return [conceptIdForPath(type, file.relPath)];
-}
 function recognize(c, file) {
     const type = classify(file.relPath);
     if (type === null)
@@ -172,8 +166,15 @@ export const dotenvAdapter = {
     version: "0.9.0",
     extensions: [".env"],
     recognize,
-    recognizePathCandidates,
     validate,
+    /**
+     * Closed-form owner candidates (#857): `env`/`secret` are always authored
+     * directly under their own stash subdir (`classify` requires it — no
+     * off-canonical loose placement exists for this adapter), so there is no
+     * loose-fallback class to enumerate here, unlike `akm-adapter`.
+     * `assetPathCandidatesForName` expands `env`'s `.env`/`<name>.env` duality;
+     * the sensitive-marker sibling spellings are then layered on each.
+     */
     readCandidates(c, conceptId) {
         const posix = toPosix(conceptId);
         const slash = posix.indexOf("/");
@@ -184,10 +185,11 @@ export const dotenvAdapter = {
         const type = typeForStashDir(head);
         if ((type !== "env" && type !== "secret") || rest.length === 0)
             return [];
-        const primary = assetPathForName(type, path.join(c.root, head), rest);
-        return (type === "env"
+        const primaries = assetPathCandidatesForName(type, path.join(c.root, head), rest);
+        const expanded = primaries.flatMap((primary) => type === "env"
             ? [primary, primary.replace(/\.env$/i, ".sensitive")]
-            : [primary, `${primary}.sensitive`, `${primary}.lock`]).map((candidatePath) => ({ path: candidatePath, conceptId: posix }));
+            : [primary, `${primary}.sensitive`, `${primary}.lock`]);
+        return expanded.map((candidatePath) => ({ path: candidatePath, conceptId: posix }));
     },
     /**
      * env places to `env/<name>.env`, secret to `secrets/<name>` (identity join,

package/dist/core/adapter/recognize-match.js

@@ -1,7 +1,7 @@
 // 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 { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher, smartMdPathCandidates, } from "../../indexer/walk/matchers.js";
+import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher } from "../../indexer/walk/matchers.js";
 /**
  * The four builtin matchers, in registration order. The array index IS the
  * registration index `runMatchers` uses for tie-breaking. (The `wiki` matcher
@@ -46,22 +46,3 @@ export function recognizeMatch(file) {
     }
     return winningMatch(hits);
 }
-/**
- * Every AKM matcher winner possible from path fields alone. The three
- * path-only matchers run exactly as production does; each possible result of
- * the shared smart-Markdown fact table is then arbitrated at its real index.
- */
-export function recognizePathCandidateMatches(file) {
-    const fileContext = file;
-    const pathHits = [extensionMatcher, directoryMatcher, parentDirHintMatcher].flatMap((matcher, index) => {
-        const result = matcher(fileContext);
-        return result ? [{ result, index }] : [];
-    });
-    const smartCandidates = smartMdPathCandidates(file);
-    const variants = smartCandidates.length > 0 ? smartCandidates : [undefined];
-    const winners = variants.flatMap((smart) => {
-        const winner = winningMatch(smart ? [...pathHits, { result: smart, index: 3 }] : [...pathHits]);
-        return winner ? [winner] : [];
-    });
-    return [...new Map(winners.map((winner) => [`${winner.type}\0${winner.renderer}`, winner])).values()];
-}

package/dist/core/asset/asset-placement.js

@@ -151,10 +151,10 @@ const BUILTIN_PLACEMENT_SPECS = {
         isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".yml",
         toCanonicalName: (typeRoot, filePath) => {
             const rel = toPosix(path.relative(typeRoot, filePath));
-            return rel.endsWith(".yml") ? rel.slice(0, -4) : rel;
+            return rel.toLowerCase().endsWith(".yml") ? rel.slice(0, -4) : rel;
         },
         toAssetPath: (typeRoot, name) => {
-            const withExt = name.endsWith(".yml") ? name : `${name}.yml`;
+            const withExt = name.toLowerCase().endsWith(".yml") ? name : `${name}.yml`;
             return path.join(typeRoot, withExt);
         },
     },
@@ -241,3 +241,22 @@ export function assetPathForName(assetType, typeRoot, name) {
         throw new Error(`Unknown asset type: "${assetType}"`);
     return spec.toAssetPath(typeRoot, name);
 }
+/**
+ * Every physical path spelling that could own `name`, closed-form (#857).
+ * `toAssetPath` is a function, so it can only pick ONE spelling — but `env`'s
+ * "default" alias is genuinely dual-owned: both `<dir>/.env` and
+ * `<dir>/default.env` derive the same canonical name (`toCanonicalName`
+ * above), so a physical-owner lookup must consider both without reading
+ * either file. Every other placement type has exactly one inverse spelling.
+ */
+export function assetPathCandidatesForName(assetType, typeRoot, name) {
+    const primary = assetPathForName(assetType, typeRoot, name);
+    if (assetType !== "env")
+        return [primary];
+    const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;
+    if (base === undefined)
+        return [primary];
+    const dotForm = path.join(typeRoot, base, ".env");
+    const namedForm = path.join(typeRoot, base, "default.env");
+    return [...new Set([primary, dotForm, namedForm])];
+}

package/dist/core/common.js

@@ -5,7 +5,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "./errors.js";
-import { getConfigPath, getDefaultStashDir } from "./paths.js";
+import { getConfigPath, getDefaultStashDir, getRegistryCacheDir, getRegistryIndexCacheDir } from "./paths.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 // Moved to the platform leaf so paths.ts can use it without a common↔paths
 // cycle (chunk-8 WI-8.6, DoD 11); re-exported here for the existing surface.
@@ -382,6 +382,26 @@ export function isContainedRelativePath(value) {
 export function isWithin(candidate, root) {
     return isContainedResolvedPath(safeRealpath(candidate), safeRealpath(root));
 }
+/**
+ * True when `filePath` sits inside akm's OWN resolved registry-cache
+ * directories (`<cache>/registry`, `<cache>/registry-index` —
+ * {@link getRegistryCacheDir}/{@link getRegistryIndexCacheDir}), the
+ * read-only installed-source/registry-index copies that lint (and `--fix`)
+ * must never touch.
+ *
+ * This is the single source of truth for that exclusion — it replaces what
+ * used to be three independent unanchored substring checks
+ * (`posixPath.includes("/.cache/") || posixPath.includes("/registry/")`).
+ * That check matched ANY path merely containing the literal text `.cache` or
+ * `registry` anywhere in it — a normal XDG `~/.cache/...` user bundle, or a
+ * CI workspace checked out under a `.cache`-named directory, tripped it and
+ * silently got zero lint findings. Using {@link isWithin} (realpath +
+ * containment, not a string search) fixes that while still excluding the
+ * real cache content the check was meant to skip.
+ */
+export function isAkmRegistryCachePath(filePath) {
+    return isWithin(filePath, getRegistryCacheDir()) || isWithin(filePath, getRegistryIndexCacheDir());
+}
 /**
  * {@link isWithin} for callers that must not block the event loop (e.g. the
  * workflow exec dispatch path, which runs once per fan-out unit). Same