akm-cli 0.9.2-alpha.3 → 0.9.2-alpha.5

package/dist/commands/health/type-directory-check.js

@@ -0,0 +1,167 @@
+// 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/.
+/**
+ * `type-directory-disagreement` advisory for `akm health` (#831).
+ *
+ * The invariant "a file's directory declares its type" is load-bearing for
+ * refs, namespace listings, and `akm show` paths (see #824: three files
+ * written to `memories/` were indexed as `type: command`, moved their refs
+ * under `commands/memories/<slug>`, and silently vanished from the
+ * `memories/` namespace — nothing on any normal surface said so). This
+ * advisory re-checks that invariant against every currently indexed entry.
+ *
+ * Legitimate disagreements exist by design — a `knowledge/` file containing
+ * `$ARGUMENTS` is deliberately a `command`, and an `agents/` file with an
+ * `agent:` frontmatter key is deliberately a `command` (both asserted in
+ * `tests/integration/commands/show.test.ts`). So this is never a hard
+ * failure: every disagreement is reported with a `winner` naming which
+ * classifier signal produced the resolved type, so a deliberate override
+ * reads differently from an unexplained one.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+/**
+ * Directory → declared-type map, mirroring `DIR_TYPE_MAP` in
+ * `src/indexer/walk/matchers.ts` minus its per-directory extension test —
+ * this check only needs "which type does this directory declare", not which
+ * extensions it accepts. Keep in sync if `DIR_TYPE_MAP` gains, renames, or
+ * removes a directory.
+ */
+const DECLARED_DIR_TYPES = {
+    memories: "memory",
+    knowledge: "knowledge",
+    commands: "command",
+    agents: "agent",
+    workflows: "workflow",
+    facts: "fact",
+    lessons: "lesson",
+    sessions: "session",
+    instructions: "instruction",
+    scripts: "script",
+    env: "env",
+    secrets: "secret",
+    tasks: "task",
+};
+const realReadFile = (absPath) => {
+    try {
+        return fs.readFileSync(absPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The type a file's directory declares, mirroring the `classifyByDirectory` /
+ * `classifyByParentDirHint` precedence in matchers.ts: the immediate parent
+ * directory wins when it is itself typed (parentDirHint, specificity 15);
+ * otherwise the outermost typed ancestor wins (directoryMatcher, specificity
+ * 10, which walks root-to-leaf and returns on the first hit).
+ */
+function declaredTypeForPath(absPath) {
+    const segments = path
+        .dirname(absPath)
+        .split(path.sep)
+        .filter((seg) => seg.length > 0);
+    const immediateParent = segments.at(-1);
+    if (immediateParent) {
+        const parentType = DECLARED_DIR_TYPES[immediateParent];
+        if (parentType)
+            return { dir: immediateParent, type: parentType };
+    }
+    for (const seg of segments) {
+        const type = DECLARED_DIR_TYPES[seg];
+        if (type)
+            return { dir: seg, type };
+    }
+    return undefined;
+}
+/**
+ * Best-effort explanation for why `classifyBySmartMd` (matchers.ts) would
+ * have produced `resolvedType` for this content, in the SAME precedence
+ * order the real function checks them. Returns `undefined` when no known
+ * override signal is found — that absence is itself the accident signal:
+ * nothing in the file explains why its type disagrees with its directory.
+ *
+ * The numeric-placeholder branch is flagged `knownGoodOverride: false` on
+ * purpose: since #826, that heuristic is guarded to never fire when the file
+ * sits under a declared-type directory, so seeing it win here would mean the
+ * guard regressed, not that this is a sanctioned override.
+ */
+function explainOverride(resolvedType, content) {
+    const fm = parseFrontmatter(content).data;
+    if (fm.type === "workflow" && resolvedType === "workflow") {
+        return { winner: "smart-md:workflow-frontmatter", knownGoodOverride: true };
+    }
+    if ("tools" in fm && resolvedType === "agent") {
+        return { winner: "smart-md:tools-frontmatter", knownGoodOverride: true };
+    }
+    if ("agent" in fm && resolvedType === "command") {
+        return { winner: "smart-md:agent-frontmatter", knownGoodOverride: true };
+    }
+    if (resolvedType === "command" && content.includes("$ARGUMENTS")) {
+        return { winner: "smart-md:$ARGUMENTS", knownGoodOverride: true };
+    }
+    if (resolvedType === "command" && /\$[123](?!\d|[.,]\d)/.test(content)) {
+        return { winner: "smart-md:numeric-placeholder", knownGoodOverride: false };
+    }
+    if ("model" in fm && resolvedType === "agent") {
+        return { winner: "smart-md:model-frontmatter", knownGoodOverride: true };
+    }
+    return undefined;
+}
+/**
+ * Compare every indexed entry's resolved type against the type its
+ * directory declares (see {@link DECLARED_DIR_TYPES}), and return one
+ * {@link TypeDirectoryDisagreement} per mismatch, sorted by path. Entries
+ * outside any declared-type directory are not checked — this is only the
+ * "directory declares type" invariant.
+ */
+export function collectTypeDirectoryDisagreements(entries, readFile = realReadFile) {
+    const disagreements = [];
+    for (const entry of entries) {
+        const declared = declaredTypeForPath(entry.filePath);
+        if (!declared || declared.type === entry.type)
+            continue;
+        const content = readFile(entry.filePath);
+        const explanation = content === undefined ? undefined : explainOverride(entry.type, content);
+        disagreements.push({
+            path: entry.filePath,
+            resolved: entry.type,
+            expected: declared.type,
+            winner: explanation?.winner ?? "unknown",
+            knownGoodOverride: explanation?.knownGoodOverride ?? false,
+        });
+    }
+    return disagreements.sort((a, b) => a.path.localeCompare(b.path));
+}
+const MAX_DETAIL_LINES = 10;
+/**
+ * Build the `type-directory-disagreement` advisory, or `undefined` when
+ * every indexed entry agrees with its directory. Always `status: "warn"`
+ * (never `"fail"`) — a deliberate override is still a disagreement worth
+ * seeing, just not a gate.
+ */
+export function buildTypeDirectoryAdvisory(entries, readFile = realReadFile, displayPath = (p) => p) {
+    const disagreements = collectTypeDirectoryDisagreements(entries, readFile);
+    if (disagreements.length === 0)
+        return undefined;
+    const lines = disagreements.slice(0, MAX_DETAIL_LINES).map((d) => {
+        const note = d.knownGoodOverride ? " (known-good override)" : "";
+        return `${displayPath(d.path)} resolved=${d.resolved} expected=${d.expected} winner=${d.winner}${note}`;
+    });
+    if (disagreements.length > MAX_DETAIL_LINES) {
+        lines.push(`+${disagreements.length - MAX_DETAIL_LINES} more`);
+    }
+    return {
+        name: "type-directory-disagreement",
+        kind: "deterministic",
+        status: "warn",
+        confidence: "high",
+        message: `${disagreements.length} indexed asset(s) have a resolved type that disagrees with the type their directory declares: ${lines.join("; ")}`,
+        evidence: {
+            disagreements: disagreements.map((d) => ({ ...d, path: displayPath(d.path) })),
+        },
+    };
+}

package/dist/commands/health/windows.js

@@ -11,7 +11,7 @@ import { readEvents } from "../../core/events.js";
 import { buildTaskRunId, getLoggedRunIds } from "../../core/logs-db.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { queryTaskHistory } from "../../storage/repositories/task-history-repository.js";
-import { buildImproveSkipSummary, computeWallTimeStats, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./improve-metrics.js";
+import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./improve-metrics.js";
 import { readLlmUsageAggregate } from "./llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage } from "./metrics.js";
 import { buildPerRunSummaries } from "./task-runs.js";
@@ -148,14 +148,18 @@ export function buildWindowMetrics(db, stateDbPath, since, until, now = () => Da
     const failedTaskRows = taskRows.filter((row) => row.status === "failed");
     const activeRows = taskRows.filter((row) => row.status === "active" && row.completed_at === null);
     const stuckActiveRuns = activeRows.filter((row) => now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS).length;
-    const promptRows = taskRows.filter((row) => row.target_kind === "prompt");
-    const promptFailures = promptRows.filter((row) => {
+    // D8 (spec §5.3): a marked "command" row or a legacy (unmarked) "prompt"
+    // row is the agent/LLM arm; an unmarked "command" row is the legacy
+    // native shell/script arm and must not be counted here (see
+    // isAgentTaskHistoryRow's header comment for the full mapping).
+    const agentRows = taskRows.filter((row) => isAgentTaskHistoryRow(row));
+    const agentFailures = agentRows.filter((row) => {
         const detail = parseTaskMetadata(row).detail;
         return typeof detail?.reason === "string" && detail.reason.length > 0;
     });
     const logBackingRate = taskRowsWithLogs.length === 0 ? 1 : existingLogRows.length / taskRowsWithLogs.length;
     const taskFailRate = taskRows.length === 0 ? 0 : failedTaskRows.length / taskRows.length;
-    const agentFailureRate = promptRows.length === 0 ? 0 : promptFailures.length / promptRows.length;
+    const agentFailureRate = agentRows.length === 0 ? 0 : agentFailures.length / agentRows.length;
     const improveInvoked = readEvents({ since, type: "improve_invoked" }, { dbPath: stateDbPath }).events.filter((event) => new Date(event.ts ?? since).getTime() < new Date(until).getTime()).length;
     const improveCompletedEvents = readEvents({ since, type: IMPROVE_COMPLETED_EVENT }, { dbPath: stateDbPath }).events.filter((event) => new Date(event.ts ?? since).getTime() < new Date(until).getTime());
     const improveSkippedEvents = readEvents({ since, type: "improve_skipped" }, { dbPath: stateDbPath }).events.filter((event) => new Date(event.ts ?? since).getTime() < new Date(until).getTime());

package/dist/commands/health.js

@@ -15,15 +15,19 @@ import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { readSemanticStatus } from "../indexer/search/semantic-status.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
+import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
 import { queryTaskHistory } from "../storage/repositories/task-history-repository.js";
+import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
 import { HEALTH_CHECKS, runHealthEngineProbes } from "./health/checks.js";
-import { buildImproveSkipSummary, computeWallTimeStats, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./health/improve-metrics.js";
+import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./health/improve-metrics.js";
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
+import { collectPluginStalenessAdvisories } from "./health/plugin-staleness.js";
 import { collectStashExposureAdvisory } from "./health/stash-exposure.js";
 import { collectSurfacesAdvisories } from "./health/surfaces.js";
 import { buildPerRunSummaries } from "./health/task-runs.js";
+import { buildTypeDirectoryAdvisory } from "./health/type-directory-check.js";
 import { ACTIVE_RUN_WARN_MS, IMPROVE_COMPLETED_EVENT, MIN_ROWS_FOR_WORST_TASK_FAIL_RATE, } from "./health/types.js";
 import { buildWindowMetrics, computeDeltas, partitionLogBackedRows, resolveWindowCompare } from "./health/windows.js";
 const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
@@ -120,14 +124,18 @@ function gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now) {
     const failedTaskRows = taskRows.filter((row) => row.status === "failed");
     const activeRows = taskRows.filter((row) => row.status === "active" && row.completed_at === null);
     const stuckActiveRows = activeRows.filter((row) => now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS);
-    const promptRows = taskRows.filter((row) => row.target_kind === "prompt");
-    const promptFailures = promptRows.filter((row) => {
+    // D8 (spec §5.3): a marked "command" row or a legacy (unmarked) "prompt"
+    // row is the agent/LLM arm; an unmarked "command" row is the legacy
+    // native shell/script arm and must not be counted here (see
+    // isAgentTaskHistoryRow's header comment for the full mapping).
+    const agentRows = taskRows.filter((row) => isAgentTaskHistoryRow(row));
+    const agentFailures = agentRows.filter((row) => {
         const detail = parseTaskMetadata(row).detail;
         return typeof detail?.reason === "string" && detail.reason.length > 0;
     });
     const logBackingRate = taskRowsWithLogs.length === 0 ? 1 : existingLogRows.length / taskRowsWithLogs.length;
     const taskFailRate = taskRows.length === 0 ? 0 : failedTaskRows.length / taskRows.length;
-    const agentFailureRate = promptRows.length === 0 ? 0 : promptFailures.length / promptRows.length;
+    const agentFailureRate = agentRows.length === 0 ? 0 : agentFailures.length / agentRows.length;
     return {
         tableNames,
         missingTables,
@@ -227,11 +235,12 @@ function gatherImproveSummaryPhase(db, stateDbPath, since, now) {
     return { improveSummary, perRunSummaries };
 }
 /**
- * The three best-effort advisory groups beyond the health-check registry:
- * improve advisories, the `stash-git-exposure` probe, and the 08 surfaces
- * group (binary-config-skew, egress-endpoints). Order matches emission order in
- * the returned array. A probe/filesystem failure in either try/catch must not
- * abort the health report — each group degrades to "no advisory" independently.
+ * The four best-effort advisory groups beyond the health-check registry:
+ * improve advisories, the `stash-git-exposure` probe, the 08 surfaces group
+ * (binary-config-skew, egress-endpoints), and `plugin-version` (itlackey/akm#832).
+ * Order matches emission order in the returned array. A probe/filesystem
+ * failure in any try/catch must not abort the health report — each group
+ * degrades to "no advisory" independently.
  */
 function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView) {
     const advisories = [...collectImproveAdvisories(db, stateDbPath, since, improveSummary)];
@@ -269,8 +278,61 @@ function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, optio
     catch {
         // Non-fatal.
     }
+    // #831: flag indexed assets whose resolved type disagrees with the type
+    // their containing directory declares (see health/type-directory-check.ts).
+    // Best-effort — an unreadable index must not abort the health report.
+    try {
+        const typeDirMismatch = detectTypeDirectoryDisagreements(options.stashDir ?? resolveStashDir());
+        if (typeDirMismatch)
+            advisories.push(typeDirMismatch);
+    }
+    catch {
+        // Non-fatal.
+    }
+    // itlackey/akm#832: report installed Claude Code harness plugin version(s)
+    // and warn when stale or when the plugin's own akm-cli version range no
+    // longer admits this CLI. Best-effort — no plugin installed, an unreadable
+    // manifest, or a network failure while checking the newest tag must not
+    // abort the health report.
+    try {
+        advisories.push(...collectPluginStalenessAdvisories({ cliVersion: pkgVersion }));
+    }
+    catch {
+        // Non-fatal.
+    }
     return advisories;
 }
+/**
+ * Open index.db read-only, project every entry to `{ filePath, type }`, and
+ * build the `type-directory-disagreement` advisory. `stashRoot` is used only
+ * to shorten displayed paths (relative to the stash) when it's an ancestor of
+ * the entry's path; falls back to the absolute path otherwise. Returns
+ * `undefined` when the index is absent/unreadable or nothing disagrees —
+ * mirrors {@link detectIndexStateGenerationMismatch}'s best-effort shape.
+ */
+function detectTypeDirectoryDisagreements(stashRoot) {
+    let indexDb;
+    try {
+        indexDb = openReadonlyExistingDatabase(getDbPath());
+        if (!indexDb)
+            return undefined;
+        const entries = getAllEntries(indexDb).map((entry) => ({ filePath: entry.filePath, type: entry.type }));
+        return buildTypeDirectoryAdvisory(entries, undefined, (absPath) => absPath.startsWith(stashRoot) ? path.relative(stashRoot, absPath) : absPath);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (indexDb) {
+            try {
+                closeDatabase(indexDb);
+            }
+            catch {
+                // Best-effort advisory: a close failure must not abort health.
+            }
+        }
+    }
+}
 /**
  * Detect the durable signature of an interrupted cross-database update.
  *

package/dist/commands/improve/extract.js

@@ -377,7 +377,20 @@ function runPreLlmSessionGates(args) {
     if (!force && shouldSkipAlreadyExtractedSession(prior, contentHash)) {
         return { skip: alreadyExtractedResult(harness.name, sessionRef.sessionId, prior, contentHash) };
     }
-    const filtered = preFilterSession(data, {
+    // #840 — harvest-without-prompting hybrid: the LLM prompt is built only from
+    // parent-origin events (folding stays as infrastructure for hashing above
+    // and inline-ref harvesting on `data.inlineRefs`, both of which still see
+    // the FULL folded stream). Subagent-origin events never reach
+    // `preFilterSession`, so #839's `dedupeTaskNotifications` naturally becomes
+    // a no-op on this path — a subagent's own event can no longer be in the
+    // kept set for a notification to be deduped against, leaving the parent's
+    // `<task-notification>` (the only surviving trace of that delegated work)
+    // untouched. See docs/plans/subagent-extraction-design.md §6.
+    const parentOriginData = {
+        ...data,
+        events: data.events.filter((e) => e.filePath === data.ref.filePath),
+    };
+    const filtered = preFilterSession(parentOriginData, {
         ...(typeof maxTotalChars === "number" ? { maxTotalChars } : {}),
     });
     // #595/#596 — minContentChars gate: skip the LLM call for sessions whose RAW
@@ -388,6 +401,14 @@ function runPreLlmSessionGates(args) {
     // fix gated on `filtered.stats.inputCount`, which is an EVENT count, not a
     // char count — this port measures actual raw chars so the threshold matches
     // the config key's documented unit.
+    // #840 — deliberately measured on the FULL folded `data.events` (parent +
+    // subagents), not the parent-origin view above: narrowing this to
+    // parent-origin chars would newly skip delegation-heavy sessions with a
+    // thin parent transcript before extraction runs at all, even though their
+    // subagent work is still fully harvested via `data.inlineRefs` above. The
+    // full-stream measurement is today's unchanged behavior, so the worst case
+    // this preserves is an LLM call over a small parent-only prompt, not a
+    // missed extraction.
     const rawContentChars = data.events.reduce((sum, event) => sum + event.text.length, 0);
     if (minContentChars > 0 && rawContentChars < minContentChars) {
         return {

package/dist/commands/lint/index.js

@@ -18,7 +18,7 @@ import { warn } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail } from "../../tasks/source-v3.js";
 import { resolveWorkflowSourceDomains } from "../../workflows/source-files.js";
-import { compareWorkflowSourceCodePoints } from "../../workflows/source-ir/ordering.js";
+import { compareWorkflowSourceCodePoints } from "../../workflows/source-ir/compare.js";
 import { runBaseChecks } from "./base-linter.js";
 import { checkEnvForDangerousKeys } from "./env-key-rules.js";
 import { isAdvisoryLintIssue } from "./types.js";

package/dist/commands/migrate-cli.js

@@ -1,44 +1,149 @@
 // 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 { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { runMigrationTool } from "./migration-tool.js";
-/**
- * Run the task-only migrator and render its one JSON plan through the normal
- * output pipeline.
- */
-async function runMigrateSubcommand(command, args) {
-    const result = await runMigrationTool(args);
+async function callMigrateTool(args, runTool) {
+    const result = await runTool(args);
     if (result.stderr)
         process.stderr.write(result.stderr);
     const resultLine = result.stdout.trim();
-    if (resultLine) {
-        try {
-            output(command, JSON.parse(resultLine));
-        }
-        catch {
-            console.log(resultLine);
-        }
+    if (!resultLine)
+        return { status: result.status };
+    try {
+        return { status: result.status, plan: JSON.parse(resultLine) };
+    }
+    catch {
+        console.log(resultLine);
+        return { status: result.status };
+    }
+}
+function worstStatus(left, right) {
+    if (left === "blocked" || right === "blocked")
+        return "blocked";
+    if (left === "ready" || right === "ready")
+        return "ready";
+    return "current";
+}
+/**
+ * Resolve one generation's contribution to the combined status — fail
+ * CLOSED, never open (code-review finding: this tool advertises itself as
+ * "blocked-not-guessed").
+ *
+ * A generation that exited SUCCESS with no plan on stdout legitimately means
+ * "nothing to report" and defaults to `"current"`. A generation that exited
+ * NON-SUCCESS (by the caller's own guard, this can only be `EXIT_CODES.
+ * GENERAL` — the "blocked" code) with a parsed `plan.status` reports that
+ * status verbatim, same as before.
+ *
+ * The gap this closes: NON-SUCCESS with NO parseable plan at all —
+ * `runMigrationTool` coerces a `spawnSync` `status` of `null` (the child was
+ * killed by a signal — OOM, a timeout, a manual kill — never scheduled to
+ * exit) to `1`, indistinguishable from the migrator's own legitimate
+ * "blocked" exit code, and truncated/malformed stdout hits the same
+ * `JSON.parse` catch in `callMigrateTool`. Previously `?? "current"` silently
+ * read a crashed generation as "nothing to migrate"; this reports it as
+ * `"blocked"` with an explanatory blocker instead, so the combined exit code
+ * (`EXIT_CODES.GENERAL` below) actually reflects that the generation's real
+ * state is unknown, rather than reporting success at exit 0.
+ */
+export function resolveGenerationStatus(call, label) {
+    const planStatus = call.plan?.status;
+    if (planStatus !== undefined)
+        return { status: planStatus };
+    if (call.status !== EXIT_CODES.SUCCESS) {
+        return {
+            status: "blocked",
+            error: `${label}: the child process exited without printing a plan (exit status ${call.status}) — its real migration state is unknown.`,
+        };
     }
-    // R-067: `process.exitCode = …; return;` (not `process.exit()`) so the
-    // command's normal cleanup (`disposeDispatchResources()` in `runCommand`,
-    // src/cli.ts) still runs before the process exits with the child's status.
-    if (result.status !== 0) {
-        process.exitCode = result.status;
+    return { status: "current" };
+}
+/**
+ * Run BOTH migration generations — task-v2-to-v3, then task-v3-to-task-
+ * source-v4 — and print one combined plan (spec
+ * docs/plans/specs/p4-deletions-closeout.md §3.2.5, rows B-31/B-32).
+ *
+ * Each generation is its OWN subprocess call into the standalone migrator
+ * (`scripts/akm-migrate.ts`'s `status`/`apply` and `task-v4-status`/
+ * `task-v4-apply` verbs, UNCHANGED — row B-33), so each keeps its own
+ * `withConfigLock` + `O_EXCL` backup root + prevalidate + TOCTOU recheck +
+ * atomic replace + reverse rollback + convergence check, and the two are
+ * NEVER interleaved. The two calls are unconditional and independent of
+ * each other's outcome: a blocked (or otherwise incomplete) generation-1
+ * result does not stop generation 2 from running against whatever is
+ * already task source v4 — exactly `akm-migrate status`/`task-v4-status`
+ * (or `apply`/`task-v4-apply`) run back to back by hand. Only a genuine
+ * hard failure (a status neither SUCCESS nor the "blocked" GENERAL code —
+ * a config error, a crash) aborts the second call, since generation 1 never
+ * got to look at a stable tree in that case.
+ */
+export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runTool = runMigrationTool) {
+    const first = await callMigrateTool(genOneArgs, runTool);
+    if (first.status !== EXIT_CODES.SUCCESS && first.status !== EXIT_CODES.GENERAL) {
+        process.exitCode = first.status;
+        return;
+    }
+    const second = await callMigrateTool(genTwoArgs, runTool);
+    if (second.status !== EXIT_CODES.SUCCESS && second.status !== EXIT_CODES.GENERAL) {
+        process.exitCode = second.status;
+        return;
+    }
+    if (!first.plan && !second.plan) {
+        if (first.status !== EXIT_CODES.SUCCESS)
+            process.exitCode = first.status;
         return;
     }
+    const combined = combineMigrationPlans(first, second);
+    output(command, combined);
+    if (combined.status === "blocked")
+        process.exitCode = EXIT_CODES.GENERAL;
+}
+/**
+ * Merge both generations' plans into the one combined envelope the command
+ * prints. Deliberately PURE — every rule the combined plan encodes (the
+ * {@link worstStatus} rollup, the fail-closed
+ * {@link resolveGenerationStatus} contribution, and the blockers merge, which
+ * orders generation 1's own blockers after its resolution error and before
+ * generation 2's) is decided here from two plain values, so it is provable
+ * without a subprocess, a CLI dispatch, or an output-mode singleton. The
+ * caller keeps the only two effectful decisions: whether generation 2 runs at
+ * all, and the process exit code.
+ */
+export function combineMigrationPlans(first, second) {
+    const firstResolved = resolveGenerationStatus(first, "task-v2-to-v3");
+    const secondResolved = resolveGenerationStatus(second, "task-v3-to-task-source-v4");
+    return {
+        schemaVersion: 1,
+        status: worstStatus(firstResolved.status, secondResolved.status),
+        blockers: [
+            ...(firstResolved.error ? [firstResolved.error] : []),
+            ...(first.plan?.blockers ?? []),
+            ...(secondResolved.error ? [secondResolved.error] : []),
+            ...(second.plan?.blockers ?? []),
+        ],
+        taskV3Migration: first.plan?.taskV3Migration,
+        taskV4Migration: second.plan?.taskV4Migration,
+        ...(first.plan?.backupPath !== undefined ? { backupPath: first.plan.backupPath } : {}),
+        ...(first.plan?.applied !== undefined ? { applied: first.plan.applied } : {}),
+        ...(second.plan?.backupPath !== undefined ? { taskV4BackupPath: second.plan.backupPath } : {}),
+        ...(second.plan?.applied !== undefined ? { taskV4Applied: second.plan.applied } : {}),
+    };
 }
 export const migrateCommand = defineGroupCommand({
-    meta: { name: "migrate", description: "Inspect or apply task-v2 to task-v3 migrations" },
+    meta: { name: "migrate", description: "Inspect or apply task-v2 and task-v3 sources to task source v4" },
     subCommands: {
         status: defineJsonCommand({
-            meta: { name: "status", description: "Read-only task-v2 migration check" },
+            meta: { name: "status", description: "Read-only task-v2 and task-v3 migration check" },
             run() {
-                return runMigrateSubcommand("migrate-status", ["status"]);
+                return runMigrateSubcommand("migrate-status", ["status"], ["task-v4-status"]);
             },
         }),
         apply: defineJsonCommand({
-            meta: { name: "apply", description: "Back up and atomically convert task-v2 files to task v3" },
+            meta: {
+                name: "apply",
+                description: "Back up and atomically convert task-v2 and task-v3 files to task source v4",
+            },
             args: {
                 "dry-run": {
                     type: "boolean",
@@ -47,7 +152,8 @@ export const migrateCommand = defineGroupCommand({
                 },
             },
             run({ args }) {
-                return runMigrateSubcommand("migrate-apply", ["apply", ...(args.dryRun ? ["--dry-run"] : [])]);
+                const dryRunFlag = args.dryRun ? ["--dry-run"] : [];
+                return runMigrateSubcommand("migrate-apply", ["apply", ...dryRunFlag], ["task-v4-apply", ...dryRunFlag]);
             },
         }),
     },

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

@@ -5,7 +5,7 @@ import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { parseRefInput } from "../../../core/asset/resolve-ref.js";
 import { proposalContent } from "../../../core/file-change.js";
 import { lintLessonContent } from "../../../core/lesson-lint.js";
-import { parseTaskV3Yaml } from "../../../tasks/source-v3.js";
+import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
 import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
 import { defaultProposalQualityValidators } from "./proposal-quality-validators.js";
 const genericProposalValidator = {
@@ -52,7 +52,12 @@ const canonicalProposalValidators = {
         const name = ctx.parsedRef?.name;
         if (!name)
             return [];
-        parseTaskV3Yaml({
+        // Version-routing seam (spec docs/plans/specs/p2a-task-source-v4.md
+        // §3.6): a proposal body is validated by parsing alone — neither arm's
+        // parsed document is inspected further, so routing through the union is
+        // a pure swap; any parse failure (either version) is turned into an
+        // `invalid-task-structure` finding by the try/catch this call sits in.
+        parseTaskSource({
             yaml: proposalContent(proposal),
             filePath: proposal.changes[0]?.path || proposal.ref,
         });

package/dist/commands/read/remember-cli.js

@@ -7,7 +7,7 @@ import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich } from "../remember.js";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich, synthesizeMemoryDescription, } from "../remember.js";
 import { assertFlatAssetName, inferAssetName, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "./knowledge.js";
 import { akmSearch } from "./search.js";
 // ── Helper: similar memory search ────────────────────────────────────────────
@@ -189,7 +189,9 @@ export const rememberCommand = defineJsonCommand({
             // Phase 1B / Rec 7: even the zero-flag hot-path emits
             // `captureMode: hot` + `beliefState: asserted` so user-supplied
             // memories outrank background-derived ones during ranking.
+            // #834: `description` is synthesized deterministically (see synthesizeMemoryDescription) so the memory is indexable.
             const frontmatterBlock = buildMemoryFrontmatter({
+                description: synthesizeMemoryDescription(body),
                 captureMode: "hot",
                 beliefState: "asserted",
             });
@@ -264,6 +266,9 @@ export const rememberCommand = defineJsonCommand({
                 observed_at = enriched.observed_at;
             executionNotices = enriched.notices;
         }
+        // #834: no --description and no --enrich-derived one — synthesize deterministically (see zero-flag path above).
+        if (!description)
+            description = synthesizeMemoryDescription(body);
         // ── Required-field check (before any write) ───────────────────────────
         // Tags remain required when the user explicitly asked for tag-bearing
         // metadata (--tag / --enrich / --description / --source / --expires).