akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.7

package/dist/commands/improve/retrieval-gate.js

@@ -0,0 +1,127 @@
+// 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/.
+/**
+ * The retrieval regression gate (#722): a reflect rewrite of an existing asset
+ * must not grade lower on the queries that actually retrieved it.
+ *
+ * Measured before it was built: of 60 accepted reflect rewrites judged against
+ * their own queries, 14 graded lower (23%, 95% CI 14–35%) and 12 higher. The
+ * old and new content are graded one query at a time, blind, with the
+ * retrieval-eval judge's prompt (kappa 0.83 against human grades) and its
+ * document shape: type, ref, name, description and the first 1,500 characters
+ * of the body.
+ */
+import relevanceJudgePrompt from "../../assets/prompts/retrieval-relevance-judge.md" with { type: "text" };
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
+import { nonTaskInput } from "../../core/non-task-input.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { listRetrievalQueries } from "../../indexer/usage/usage-events.js";
+import { readLedgerDb, stripBundle } from "./ledger.js";
+import { callStage } from "./stage.js";
+/** Queries graded per rewrite, as measured. */
+const MAX_QUERIES = 5;
+/** The retrieval suite treats a longer input as a paste, not a query; the measurement did the same. */
+const MAX_QUERY_CHARS = 2000;
+/** The judge sees this much of the body, as in the retrieval eval. */
+const MAX_DOC_CHARS = 1500;
+const GRADE_SCHEMA = {
+    type: "object",
+    required: ["grade", "reason"],
+    additionalProperties: false,
+    properties: { grade: { type: "integer", minimum: 0, maximum: 3 }, reason: { type: "string" } },
+};
+/** Up to five distinct task queries, in the given order, whitespace collapsed. */
+export function usableRetrievalQueries(raw) {
+    const out = [];
+    for (const text of raw) {
+        const query = text.replace(/\s+/g, " ").trim();
+        if (!query || query.length > MAX_QUERY_CHARS || nonTaskInput(query) || out.includes(query))
+            continue;
+        out.push(query);
+        if (out.length === MAX_QUERIES)
+            break;
+    }
+    return out;
+}
+/** The asset's own retrieval queries from the usage log (none when state.db cannot be read). */
+export function loadRetrievalQueries(access, ref) {
+    try {
+        return usableRetrievalQueries(readLedgerDb(access, (db) => listRetrievalQueries(db, stripBundle(ref))) ?? []);
+    }
+    catch {
+        return [];
+    }
+}
+function judgeDocument(ref, raw) {
+    const conceptId = stripBundle(ref);
+    const parsed = parseRefInput(conceptId);
+    const { data, content } = parseFrontmatter(raw);
+    const text = content
+        .replace(/\n{3,}/g, "\n\n")
+        .trim()
+        .slice(0, MAX_DOC_CHARS);
+    const name = typeof data.name === "string" && data.name ? data.name : parsed.name;
+    const description = typeof data.description === "string" ? data.description : "";
+    return [
+        "Candidate asset:",
+        `Type: ${parsed.type}`,
+        `Ref: ${conceptId}`,
+        `Name: ${name}`,
+        `Description: ${description}`,
+        "",
+        "Content:",
+        text,
+    ].join("\n");
+}
+/**
+ * Grade `before` and `after` on each query; refuse the rewrite when the new
+ * content's mean grade is lower. Fails closed, like the quality judge: a grade
+ * that cannot be obtained refuses the rewrite.
+ */
+export async function runRetrievalRegressionGate(args) {
+    if (args.queries.length === 0)
+        return { pass: true, queries: 0, reason: "no retrieval queries to compare on" };
+    const documents = { old: judgeDocument(args.ref, args.before), new: judgeDocument(args.ref, args.after) };
+    const totals = { old: 0, new: 0 };
+    for (const query of args.queries) {
+        for (const version of ["old", "new"]) {
+            const outcome = await callStage({
+                feature: "proposal_quality_gate",
+                runner: args.runner,
+                system: relevanceJudgePrompt.trim(),
+                prompt: `Query: ${query}\n\n${documents[version]}`,
+                request: {
+                    enableThinking: false,
+                    temperature: 0,
+                    responseSchema: GRADE_SCHEMA,
+                    ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+                    ...(args.signal ? { signal: args.signal } : {}),
+                    ...(args.chat ? { chat: args.chat } : {}),
+                },
+                ...(args.onNotices ? { onNotices: args.onNotices } : {}),
+            });
+            const grade = outcome.ok ? parseEmbeddedJsonResponse(outcome.raw)?.grade : undefined;
+            if (typeof grade !== "number" || !Number.isInteger(grade) || grade < 0 || grade > 3) {
+                return {
+                    pass: false,
+                    queries: args.queries.length,
+                    reason: `retrieval check could not grade the ${version} content${outcome.ok ? "" : ` (${outcome.reason})`}`,
+                };
+            }
+            totals[version] += grade;
+        }
+    }
+    const oldMean = totals.old / args.queries.length;
+    const newMean = totals.new / args.queries.length;
+    const pass = newMean >= oldMean;
+    const grades = `${oldMean.toFixed(2)} -> ${newMean.toFixed(2)} over ${args.queries.length} retrieval ${args.queries.length === 1 ? "query" : "queries"}`;
+    return {
+        pass,
+        queries: args.queries.length,
+        oldMean,
+        newMean,
+        reason: pass ? `retrieval grade ${grades}` : `retrieval regression: grade ${grades}`,
+    };
+}

package/dist/commands/improve/retrieval-scope.js

@@ -0,0 +1,77 @@
+// 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/.
+/**
+ * What improve may rework (#986): an asset that retrieval returned inside the
+ * usage window, or newly captured material no improve stage has processed.
+ *
+ * Fresh feedback and an explicit `--scope <ref>` are usage evidence of their
+ * own, so the signal-delta and scope lanes need no check. The fallback lanes
+ * (proactive maintenance, high salience, forgetting safety) and consolidation
+ * pick assets without such evidence, so they pick only inside this scope.
+ */
+import fs from "node:fs";
+import { daysToMs } from "../../core/common.js";
+import { warn } from "../../core/warn.js";
+import { listUsedEntryRefs, USAGE_EVENT_RETENTION_DAYS } from "../../indexer/usage/usage-events.js";
+import { listImproveLedgerRows } from "../../storage/repositories/improve-ledger-repository.js";
+import { listProposalRefSources } from "../../storage/repositories/proposals-repository.js";
+import { readLedgerDb, stripBundle } from "./ledger.js";
+/**
+ * Ledger and proposal sources that bring material in. Every other source is an
+ * improve stage reworking an asset (reflect, distill, consolidate, schema repair).
+ */
+const CAPTURE_SOURCES = new Set(["extract", "propose", "remember", "import"]);
+/**
+ * Load the scope from state.db. The window is the usage log's retention: the
+ * log keeps nothing older, and anything shorter would drop assets read less
+ * often than the window. A `.derived` hit counts for its parent memory, whose
+ * facts it carries. `undefined` (every asset eligible, as before #986) only
+ * when state.db cannot be read.
+ */
+export function loadRetrievalScope(access, stashDir) {
+    const sinceMs = Date.now() - daysToMs(USAGE_EVENT_RETENTION_DAYS);
+    const used = new Set();
+    const processed = new Set();
+    try {
+        readLedgerDb(access, (db) => {
+            for (const entryRef of listUsedEntryRefs(db, new Date(sinceMs).toISOString())) {
+                const conceptId = stripBundle(entryRef);
+                used.add(conceptId);
+                if (conceptId.endsWith(".derived"))
+                    used.add(conceptId.slice(0, -".derived".length));
+            }
+            if (!stashDir)
+                return;
+            for (const row of [...listImproveLedgerRows(db, stashDir), ...listProposalRefSources(db, stashDir)]) {
+                if (!CAPTURE_SOURCES.has(row.source))
+                    processed.add(stripBundle(row.ref));
+            }
+        });
+    }
+    catch (error) {
+        warn(`[improve] usage history unreadable, so every asset stays eligible: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    return { used, processed, sinceMs };
+}
+/**
+ * Whether improve may rework `ref` (whose file is `filePath`) under `scope`. An
+ * unprocessed asset whose file cannot be read is left to the disk check that
+ * follows, which reports it as missing.
+ */
+export function isInRetrievalScope(scope, ref, filePath) {
+    if (!scope)
+        return true;
+    const conceptId = stripBundle(ref);
+    if (scope.used.has(conceptId))
+        return true;
+    if (scope.processed.has(conceptId))
+        return false;
+    try {
+        return filePath === undefined || fs.statSync(filePath).mtimeMs >= scope.sinceMs;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/commands/read/curate.js

@@ -18,6 +18,7 @@
 import { loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { nonTaskInput } from "../../core/non-task-input.js";
 import { redactCredentialPatterns } from "../../core/redaction.js";
 import { withStateDbTelemetry } from "../../core/state-db.js";
 import { searchHitContent } from "../../indexer/search/db-search.js";
@@ -33,8 +34,6 @@ import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const DEFAULT_CURATE_LIMIT = 4;
 const MAX_CURATE_SUPPORT_REFS = 2;
-/** The line of `src/assets/stash-skeleton/README.md` that reaches curate verbatim as a query. */
-const STASH_README_LINE = "This is an **AKM stash** — a structured knowledge repository that stores reusable";
 /** Fused candidates the reranker reorders when `search.curateRerank.topN` is unset. */
 const DEFAULT_CURATE_RERANK_TOP_N = 30;
 /** Characters of name, description and content sent to the reranker per candidate. */
@@ -131,21 +130,6 @@ export async function akmCurate(options) {
     }
     return result;
 }
-/**
- * What the (trimmed) curate input is when it is not a task, else undefined.
- * Harness and tool envelopes (`<task-notification>…`, `<system-reminder>…`,
- * `<cross-session-message …>…`) start with a tag and close one, and the stash
- * README line arrives verbatim; on the retrieval suite neither shape occurs in
- * a real query. Length is not a signal: prompts over 2,000 characters found
- * relevant assets at about the rate of shorter long prompts.
- */
-function nonTaskInput(query) {
-    if (query.startsWith("<") && query.includes("</"))
-        return "a harness or tool envelope";
-    if (query === STASH_README_LINE)
-        return "the akm stash README boilerplate";
-    return undefined;
-}
 export async function curateSearchResults(query, result, limit, selectedType, eventSource) {
     const allStashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];

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

@@ -435,17 +435,15 @@ const tasksDoctorCommand = defineJsonCommand({
     },
 });
 /**
- * #907: `akm task validate`'s exit-code contract — `valid` and `converts`
- * (a v2/v3 document the in-memory shim converted successfully) are both
- * successful (exit 0); `blocked`/`invalid`/`not-a-task` are diagnosed
- * defects the caller must act on (exit 1, mirroring `task sync`'s own
- * `failures.length > 0 -> EXIT_CODES.GENERAL`). A missing path or an
- * unreadable file never reaches this function at all — `akmTaskValidate`
- * throws a `UsageError` for those, which `defineJsonCommand`'s wrapping
- * already maps to exit 2.
+ * #907: `akm task validate`'s exit-code contract — `valid` succeeds (exit
+ * 0); `blocked`/`invalid`/`not-a-task` are diagnosed defects the caller must
+ * act on (exit 1, mirroring `task sync`'s own `failures.length > 0 ->
+ * EXIT_CODES.GENERAL`). A missing path or an unreadable file never reaches
+ * this function at all — `akmTaskValidate` throws a `UsageError` for those,
+ * which `defineJsonCommand`'s wrapping already maps to exit 2.
  */
 export function taskValidateExitCode(result) {
-    return result.outcome === "valid" || result.outcome === "converts" ? undefined : EXIT_CODES.GENERAL;
+    return result.outcome === "valid" ? undefined : EXIT_CODES.GENERAL;
 }
 const tasksValidateCommand = defineJsonCommand({
     meta: {
@@ -478,9 +476,9 @@ export function taskPruneExitCode(result) {
 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; " +
+        description: "Remove installed scheduler entries `sync` can never reclaim because they no longer resolve to a live " +
+            "bundle (the bundle directory a row names is gone, or an older row's --scheduler-context descriptor " +
+            "cannot be read). Defaults to a dry-run preview — zero scheduler writes. Requires --yes to remove anything; " +
             "--id narrows removal to specific binding ids (comma-separated).",
     },
     args: {

package/dist/commands/tasks/tasks.js

@@ -41,7 +41,7 @@ import { readTaskHistory } from "../../tasks/run/task-history.js";
 import { exitCodeForStatus } from "../../tasks/run/task-result.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/schedule.js";
 import { compileTaskSchedulerBindings, schedulerBindingNativeId, } from "../../tasks/scheduler-binding.js";
-import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
+import { readLegacySchedulerContext, scheduledRowEnvironment } from "../../tasks/scheduler-invocation.js";
 import { withSchedulerLock } from "../../tasks/scheduler-lock.js";
 import { compileSchedulerSources, installedRowNativeId, installedRowOwner, installedRowScope, planSchedulerSync, renderSchedulerPlanPreview, scheduledInvocationBundle, } from "../../tasks/scheduler-sync.js";
 import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
@@ -301,9 +301,7 @@ export async function akmTasksHistory(input) {
  */
 export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
     return withSchedulerLock(async () => {
-        const { sched, plan, publish, warnings } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
-        if (publish && plan.operations.some((operation) => operation.kind !== "remove"))
-            publish();
+        const { sched, plan, warnings } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
         const failed = new Set();
         const failures = [...plan.failures];
         for (const operation of plan.operations) {
@@ -343,7 +341,7 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
 }
 /**
  * `akm task sync --dry-run` (#849): the exact plan `akmTasksSync` would
- * apply, previewed. It writes nothing: no config, no descriptor, no row.
+ * apply, previewed. It writes nothing: no config, no row.
  */
 export async function akmTasksSyncPlan(deps = {}, bundleTarget, options = {}) {
     const { sched, plan } = await buildSchedulerSyncPlan(deps, bundleTarget, { ...options, dryRun: true });
@@ -440,7 +438,7 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
         installed,
         scopes,
         ...(sched.expectedSignature ? { expectedSignature: sched.expectedSignature.bind(sched) } : {}),
-        ...(runtime.options ? { installOptions: runtime.options } : {}),
+        installOptions: runtime.options,
         rebind: options.rebind === true,
         extraRemovals,
         keepRefs,
@@ -450,53 +448,45 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
         ? plan.operations.some((operation) => operation.kind !== "remove")
         : plan.installed.length > 0;
     if (runtime.via === "checkout" && writesLauncher) {
-        warnings.push(`Scheduled tasks now run akm from a source checkout (${runtime.options?.binding?.join(" ")}); they run whatever the checkout holds when they fire. Install akm with \`npm install --global akm-cli\` or a standalone release, then run \`akm task sync --rebind\`.`);
+        warnings.push(`Scheduled tasks now run akm from a source checkout (${runtime.options.binding?.join(" ")}); they run whatever the checkout holds when they fire. Install akm with \`npm install --global akm-cli\` or a standalone release, then run \`akm task sync --rebind\`.`);
     }
-    return {
-        sched,
-        plan: { ...plan, failures: [...failures, ...plan.failures] },
-        ...(runtime.publish ? { publish: runtime.publish } : {}),
-        warnings,
-    };
+    return { sched, plan: { ...plan, failures: [...failures, ...plan.failures] }, warnings };
 }
 /**
- * The launcher and descriptor rows are written with. The descriptor follows
- * the current policy on every sync; a row that is already installed keeps its
- * launcher unless `--rebind` (see `installOptionsFor`). An injected backend
- * (tests) renders with its own defaults.
+ * The launcher and environment rows are written with. The environment
+ * follows the current policy on every sync; a row that is already installed
+ * keeps its launcher unless `--rebind` (see `installOptionsFor`). An injected
+ * backend (tests) renders with its own launcher.
  */
 function prepareSchedulerRuntime(deps) {
+    const environment = scheduledRowEnvironment();
     if (deps.schedulerRuntime) {
         const runtime = deps.schedulerRuntime();
-        return {
-            options: { binding: runtime.binding, contextPath: runtime.contextPath },
-            ...(runtime.via ? { via: runtime.via } : {}),
-        };
+        return { options: { binding: runtime.binding, environment }, ...(runtime.via ? { via: runtime.via } : {}) };
     }
     if (deps.backend)
-        return {};
-    const descriptor = schedulerContextDescriptor();
+        return { options: { environment } };
     const invocation = resolveAkmInvocation();
-    return {
-        options: { binding: invocation.argv, contextPath: schedulerContextPath(descriptor) },
-        // The content-addressed descriptor is written once, before the first row that references it.
-        publish: () => {
-            writeSchedulerContextDescriptor(descriptor);
-        },
-        via: invocation.via,
-    };
+    return { options: { binding: invocation.argv, environment }, via: invocation.via };
 }
-/** One read of the akm-owned rows, each attributed to the bundle path its own descriptor names (#846). */
+/** One read of the akm-owned rows, each attributed to the bundle path it names (#846). */
 async function listInstalledRows(sched) {
     return (await sched.list()).map((row) => {
-        const ownerBundlePath = row.contextPath ? resolveInstalledOwnerPath(row.contextPath) : undefined;
+        const ownerBundlePath = installedRowBundleDir(row);
         return ownerBundlePath !== undefined ? { ...row, ownerBundlePath } : row;
     });
 }
-/** Best-effort recovery of an installed binding's owning bundle path (#846). */
-function resolveInstalledOwnerPath(contextPath) {
+/**
+ * The `AKM_BUNDLE_DIR` an installed row names: its inline one, or the one in
+ * the descriptor a row written before 0.9.17-alpha.7 references. Undefined
+ * when it names none, or its descriptor cannot be read — which never means
+ * "mine".
+ */
+function installedRowBundleDir(row) {
+    if (row.contextPath === undefined)
+        return row.environment?.AKM_BUNDLE_DIR;
     try {
-        return validateSchedulerContextDescriptor(contextPath).environment.AKM_BUNDLE_DIR;
+        return readLegacySchedulerContext(row.contextPath).AKM_BUNDLE_DIR;
     }
     catch {
         return undefined;
@@ -515,26 +505,34 @@ function installedSchedulerBundle(config, row) {
     return bundleKeyForContentRoot(config, row.ownerBundlePath);
 }
 /**
- * Why `akm task prune` (#851) would remove an installed row: its own
- * descriptor does not load (`invalid-context`) or names a bundle directory
- * that is gone (`dead-bundle-path`). A row that still resolves to a live
- * bundle is never a candidate.
+ * Why `akm task prune` (#851) would remove an installed row: a row written
+ * before 0.9.17-alpha.7 whose descriptor cannot be read (`invalid-context`),
+ * or one naming a bundle directory that is gone (`dead-bundle-path`). A row
+ * that still resolves to a live bundle is never a candidate.
  */
 function classifyPruneCandidate(entry) {
-    let ownerBundlePath;
-    try {
-        ownerBundlePath = validateSchedulerContextDescriptor(entry.contextPath).environment.AKM_BUNDLE_DIR;
+    let bundleDir;
+    if (entry.contextPath !== undefined) {
+        try {
+            bundleDir = readLegacySchedulerContext(entry.contextPath).AKM_BUNDLE_DIR;
+        }
+        catch {
+            return "invalid-context";
+        }
+        // Every descriptor akm wrote names the bundle; one that does not cannot be attributed.
+        if (bundleDir === undefined)
+            return "invalid-context";
     }
-    catch {
-        return "invalid-context";
+    else {
+        bundleDir = entry.environment?.AKM_BUNDLE_DIR;
     }
-    if (ownerBundlePath !== undefined && !fs.existsSync(ownerBundlePath))
+    if (bundleDir !== undefined && !fs.existsSync(bundleDir))
         return "dead-bundle-path";
     return undefined;
 }
 /**
  * `akm task prune` (#851): remove installed rows `sync` can never reclaim
- * because their descriptor no longer resolves to a live bundle. It scans
+ * because they no longer resolve to a live bundle. It scans
  * every installed row, not one bundle's. Without `--yes` it only previews and
  * writes nothing; `--id` narrows it to named candidates.
  */
@@ -655,7 +653,7 @@ function groupInstalledBindings(entries) {
         }
         groups.set(key, {
             argv,
-            contextPath: entry.contextPath,
+            ...(entry.contextPath !== undefined ? { contextPath: entry.contextPath } : {}),
             taskIds: [entry.id],
             status,
         });
@@ -669,13 +667,15 @@ function inspectInstalledBinding(entry) {
         status.push("checkout");
     if (binding.some((part) => part === "akm" || part === "bun" || part === "node"))
         status.push("path-selected");
-    try {
-        validateSchedulerContextDescriptor(entry.contextPath);
-    }
-    catch {
-        status.push("invalid-context");
+    if (entry.contextPath !== undefined) {
+        try {
+            readLegacySchedulerContext(entry.contextPath);
+        }
+        catch {
+            status.push("invalid-context");
+        }
     }
-    const absolutePaths = [...binding.filter((part) => path.isAbsolute(part)), entry.contextPath];
+    const absolutePaths = binding.filter((part) => path.isAbsolute(part));
     if (absolutePaths.some((part) => !fs.existsSync(part)))
         status.push("missing-path");
     if (status.length === 0)
@@ -734,8 +734,9 @@ export function resolveTaskReadBundle(refBundle, flagBundle) {
  * New scheduler bindings always carry a canonical `--bundle <owner>` token,
  * including an env-selected working stash. That stash need not be persisted in
  * config (CI, one-shot tools, and fresh installs commonly use only
- * AKM_BUNDLE_DIR), so its scheduled child must accept precisely its derived
- * owner name after the scheduler context restores the environment.
+ * AKM_BUNDLE_DIR), so its scheduled child — every row sets AKM_BUNDLE_DIR to
+ * the working stash it was synced from — must accept precisely its derived
+ * owner name.
  *
  * This is intentionally narrower than an unknown-bundle fallback: a configured
  * source always wins, and an unconfigured selector is accepted only when it is

package/dist/commands/tasks/validate.js

@@ -9,23 +9,20 @@
  * a bundle/adapter/concept id at all — it reads exactly the path it was
  * given and classifies it.
  *
- * Reuses the exact version-routing shim `parseTaskSource`
- * (`src/tasks/source/parse-task-source.ts`) already applies for every other
- * task-source reader (`akm task sync`'s `compileTaskSources` included) —
- * this module never forks a second parser or a second v2/v3 migration
- * planner. `readBoundedTaskSourceYaml` / `peekTaskSourceVersion` / `own` are
- * the SAME front-end helpers that shim itself calls first; they are used
- * here only to recover the file's ORIGINALLY DECLARED schema version for
- * the report, because `parseTaskSource`'s own `ParsedTaskSource.version` is
- * always `4` post-shim — it cannot answer "was this a v2/v3/v4 file?" on
- * its own once a v2/v3 source has been converted in memory.
+ * Reuses the exact version router `parseTaskSource`
+ * (`src/tasks/source/parse-task-source.ts`) every other task-source reader
+ * uses (`akm task sync`'s `compileTaskSources` included) — this module never
+ * forks a second parser. `readBoundedTaskSourceYaml` /
+ * `peekTaskSourceVersion` / `own` are the SAME front-end helpers the router
+ * calls first; they are used here only to recover the file's DECLARED schema
+ * version for the report and to tell `blocked` from `invalid`.
  *
  * Beyond parsing, this module also runs the SAME two per-source gates
  * `akm task sync`'s `compileTaskSources` runs before it ever installs a
  * schedule — `assertTaskScheduleInputsSatisfyContract` and
  * `assertTaskScheduleCronValid` (both extracted from `scheduler-sync.ts` for
  * exactly this reuse) — so a file `sync` would reject can never
- * be reported `valid`/`converts` here. Cron dialect is checked against
+ * be reported `valid` here. Cron dialect is checked against
  * `backendNameForPlatform()`, the same platform default `sync` falls back
  * to whenever it has no injected/native-inspected backend to hand (see
  * `akmTasksAdd`, `src/commands/tasks/tasks.ts`); a bare file was never
@@ -46,27 +43,18 @@
  *
  * Outcome classification (mirrors `parse-task-source.ts`'s own routing
  * table in its header, extended for the two gates above):
- *   - `valid`       — parses as task source v4 directly (declared `version: 4`)
- *                      and passes both sync gates.
- *   - `converts`    — declared `version: 2` or `3`; the deterministic
- *                      in-memory migrator produced a valid v4 document that
- *                      passes both sync gates. A declared `version: 4`
- *                      document whose only defect is a retired
- *                      `schedule[].enabled` key also reports `converts`
- *                      (`sourceVersion` is still `4`) — it read through the
- *                      same in-memory shim, not the direct v4 parse path.
- *   - `blocked`     — declared `version: 2` or `3`; the migrator itself
- *                      could not convert it (an ambiguous/unmigratable
- *                      shape) — the ONLY way `parseTaskSource` ever throws
- *                      for those two version numbers, so no message-text
- *                      sniffing is needed to tell this apart from `invalid`.
+ *   - `valid`       — parses as task source v4 and passes both sync gates.
+ *   - `blocked`     — declared `version: 2` or `3`, or a `version: 4`
+ *                      document still carrying the retired
+ *                      `schedule[].enabled`: what `akm migrate apply`
+ *                      rewrites. The runtime reads only v4 (#987), so the
+ *                      reason names that command.
  *   - `invalid`     — the document declares SOME version (`4`, or anything
  *                      other than 2/3/4) but fails to parse/validate, OR it
- *                      parsed (directly or via a SUCCESSFUL v2/v3
- *                      conversion) but fails one of the two sync gates
- *                      above, OR the YAML itself does not parse at all
- *                      (a genuine syntax error, not merely a non-task
- *                      shape) — reported with the parser's own reason.
+ *                      parsed but fails one of the two sync gates above, OR
+ *                      the YAML itself does not parse at all (a genuine
+ *                      syntax error, not merely a non-task shape) — reported
+ *                      with the parser's own reason.
  *   - `not-a-task`  — the document parses as YAML but never declares a
  *                      `version:` field at all (or isn't a YAML mapping) —
  *                      the strongest signal available that the file was
@@ -142,10 +130,11 @@ export async function akmTaskValidate(filePath) {
         if (!(cause instanceof UsageError))
             throw cause;
         const reason = cause.message;
-        // `parseTaskSource` only ever throws for a declared version 2/3 via the
-        // unmigratable-conversion branch (see this file's header) — no separate
-        // message check needed to recognize "blocked" here.
-        if (declaredVersion === 2 || declaredVersion === 3) {
+        // What `akm migrate apply` rewrites is the only refusal for these
+        // shapes (`parse-task-source.ts`), so no message-text sniffing is needed.
+        if (declaredVersion === 2 ||
+            declaredVersion === 3 ||
+            (declaredVersion === 4 && v4ScheduleHasRetiredEnabledKey(root))) {
             return { ok: false, path: resolvedPath, sourceVersion: declaredVersion, outcome: "blocked", reason };
         }
         if (peekFailed) {
@@ -163,13 +152,10 @@ export async function akmTaskValidate(filePath) {
         };
     }
     // Success is unreachable from any path that leaves `declaredVersion`
-    // undefined — the router requires a numeric 2/3/4 version to reach here.
+    // undefined — the router requires a numeric version 4 to reach here.
     const sourceVersion = declaredVersion ?? 4;
-    // The document itself parsed (directly, or via a successful v2/v3
-    // conversion) — now the two gates `compileTaskSources` runs before
-    // accepting it. A violation here is `invalid`, never `blocked`: the
-    // migrator already succeeded, so this is the same kind of defect a
-    // native v4 document with the identical schedule would have.
+    // The document itself parsed — now the two gates `compileTaskSources`
+    // runs before accepting it. A violation here is `invalid`.
     try {
         assertTaskScheduleInputsSatisfyContract(parsed.v4, resolvedPath);
         assertTaskScheduleCronValid(parsed.v4, backend);
@@ -179,17 +165,12 @@ export async function akmTaskValidate(filePath) {
             throw cause;
         return { ok: false, path: resolvedPath, sourceVersion, outcome: "invalid", reason: cause.message };
     }
-    // A declared `version: 4` document with a retired `schedule[].enabled`
-    // key parsed through `parseTaskSource`'s in-memory shim, not the direct
-    // v4 path, even though `sourceVersion` reads `4` — report it the same
-    // way a converted v2/v3 document is reported.
-    const convertedFromRetiredScheduleEnabled = sourceVersion === 4 && !peekFailed && v4ScheduleHasRetiredEnabledKey(root);
     const id = path.parse(resolvedPath).name;
     return {
         ok: true,
         path: resolvedPath,
         sourceVersion,
-        outcome: sourceVersion === 2 || sourceVersion === 3 || convertedFromRetiredScheduleEnabled ? "converts" : "valid",
+        outcome: "valid",
         resolved: buildResolved(id, parsed.v4),
     };
 }