akm-cli 0.9.2-alpha.2 → 0.9.2-alpha.4

package/CHANGELOG.md

@@ -6,9 +6,254 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.2-alpha.4] - 2026-08-26
+
+### Added
+
+- **`akm health`: flag assets whose resolved type disagrees with their
+  directory** (#837). Adds a `type-directory-disagreement` advisory that
+  compares every indexed asset's resolved type against the type its
+  `DIR_TYPE_MAP` directory declares (`memories/`, `knowledge/`, `commands/`,
+  `agents/`, `workflows/`, `facts/`, `lessons/`, `sessions/`,
+  `instructions/`, `scripts/`, `env/`, `secrets/`, `tasks/`). This is the
+  diagnostic that would have caught #824 (three `memories/` files silently
+  indexed as commands) the day it was introduced. Since `knowledge/` +
+  `$ARGUMENTS` and `agents/` + `agent:` frontmatter are deliberate command
+  overrides, the check never hard-fails: every disagreement is reported as a
+  warning naming the winning classifier signal, with a `knownGoodOverride`
+  flag so a sanctioned override reads differently from an unexplained one.
+- **`akm health`: report the Claude harness plugin's version and warn when
+  it's stale or out of range** (#838). Adds a `plugin-version` advisory that
+  reports each installed Claude Code `akm` plugin's version, warns when a
+  newer tag is published upstream (naming the update command), and warns
+  when the plugin's own declared `AKM_VERSION_RANGE` no longer admits the
+  running CLI — meaning the plugin has silently disabled itself. Makes an
+  outbound `git ls-remote` when network is available to check for a newer
+  tag; per owner decision, this is read-only and degrades to a benign pass
+  (no plugin, no marketplace clone, unreadable manifest, malformed range, or
+  a failed remote lookup) rather than crashing or blocking offline use.
+
+### Changed
+
+- **Extract: LLM prompt is now built from parent-origin events only —
+  "harvest-without-prompting hybrid" (#840).** #830 folds a session's
+  subagent transcripts into its event stream for hashing and inline-ref
+  harvesting; the prompt sent to the extraction LLM previously included that
+  folded subagent content too, competing with the parent's own transcript
+  for the 80,000-char pre-filter budget. #840's design-determination doc
+  (`docs/plans/subagent-extraction-design.md`) measured that this "fold"
+  approach evicts up to 28.6% of parent-origin content on real sessions to
+  make room for subagent noise that mostly gets evicted anyway, while a
+  "harvest-without-prompting hybrid" — keep folding for hashing/inline-ref
+  purposes, but filter the prompt down to `data.events` whose `filePath`
+  matches the session's own (`data.ref.filePath`) — matches or beats the
+  folded prompt's size with zero eviction on every session measured, and
+  recovers the exact same inline refs (`akm remember`/`akm feedback` calls
+  the agent made inside a subagent), because that harvesting already runs on
+  the raw stream independent of what reaches the prompt. Only
+  `runPreLlmSessionGates`'s call into `preFilterSession` changed; folding
+  (`session-log.ts`) and `buildExtractPrompt` are untouched.
+  - **No forced re-extraction wave.** `hashSessionContent` still hashes the
+    full folded `data` (parent + subagents), computed before the
+    parent-origin view is built — no previously-computed session hash
+    changes, so no session already extracted under the fold prompt shape is
+    automatically re-processed. Use `--force` to re-process a specific
+    session under the new, parent-only prompt shape.
+  - **`processes.extract.maxTotalChars` is unchanged in meaning and default**
+    — it still caps the single-call prompt built from parent-origin events;
+    it simply no longer has to compete against subagent-origin noise for
+    that budget.
+  - **`minContentChars`** (the raw-size skip gate, #595/#596) is still
+    measured on the FULL folded `data.events` (parent + subagents),
+    deliberately left unchanged: narrowing it to parent-origin chars would
+    newly skip delegation-heavy sessions with a thin parent transcript
+    before extraction runs at all, even though their subagent-origin work is
+    still fully harvested via inline refs. The full-stream measurement is
+    today's existing behavior; the worst case it preserves is an LLM call
+    over a small parent-only prompt, not a missed extraction.
+  - #839's task-notification dedupe (which stubs a parent's
+    `<task-notification>` only when the matching subagent's own event ALSO
+    survives into the same kept prompt set) composes safely with this
+    change without modification: subagent-origin events never reach
+    `preFilterSession` on this path, so the dedupe's own scoping check
+    naturally makes it a no-op — the parent's notification (the only
+    remaining trace of delegated work in the prompt) survives untouched.
+
+### Fixed
+
+- **`akm remember` synthesizes a description when the caller doesn't supply
+  one** (#835). Both the zero-flag hot path and the structured-args path
+  (e.g. `--tag`-only, with no `--description`/`--enrich`) previously wrote
+  memories with no `description:` and no `tags:`. akm's indexer covers only
+  synthesized frontmatter/headings, never body prose, so those memories were
+  retrievable only by whatever words survived into the auto-generated
+  filename — effectively write-only. Verified on a real stash: 272/3169
+  memories lacked a description, 100% of those written via `akm remember`.
+  The new `synthesizeMemoryDescription` (ported from akm-eval's
+  `firstSentencesCapped` rule, which independently arrived at the same fix)
+  is deterministic and makes no LLM call: it accumulates whole sentences
+  from the body up to `DESCRIPTION_MAX_CHARS`, skipping a leading markdown
+  heading so the description doesn't just repeat the title. Wired into both
+  write paths as a fallback only — a caller-supplied `--description` (or one
+  derived by `--enrich`) is never overwritten. Closes the write-only-memories
+  gap on 0.9.1 indexes.
+- **Extract: deduped the doubled subagent conclusion in the extraction prompt**
+  (#839). After #830 folded a session's subagent transcripts into its event
+  stream, a completed subagent's final report could appear twice in the same
+  extraction prompt: once as the subagent's own folded final message, once as
+  the parent's `<task-notification>` record of that same call (#836 measured
+  ~92-99% textual overlap on a real pair; reproduced here as a byte-identical
+  match after decoding the XML entities Claude Code escapes into `<result>`).
+  The parent's notification copy is now stubbed to `[subagent <agentId>
+  completed: <description>]` when its `<result>` is a near-duplicate
+  (Dice-bigram similarity ≥ 0.9) of a folded subagent transcript's own text;
+  the subagent's original is untouched, per #839's owner-decided direction
+  (the inverse — dropping the subagent's own terminal event — was evaluated
+  and rejected in #836 because some subagent transcripts consist only of
+  that one event). Matching is scoped by `<task-id>` to the one subagent
+  transcript it names and still requires content similarity, so an earlier
+  notification for a *resumed* agent (Claude Code re-notifies the same
+  task-id on each stop) that carries a genuinely different, intermediate
+  result is left alone.
+  **Scoped to the final, post-budget kept set — not the raw stream** (#840's
+  design-determination doc flagged this as a hazard while this PR was in
+  flight): the dedupe only fires when the subagent's own event ALSO survives
+  into the same kept set as the notification. #840 measured that today's
+  recency-biased 80k budget already evicts one side of nearly every raw
+  duplicate pair before dedupe would matter (0 of 89 raw pairs across four
+  real sessions had both sides survive); an unconditional raw-stream stub
+  would, under that same eviction pattern, sometimes delete a parent's
+  notification whose subagent copy never made the cut in the first place —
+  and would unconditionally delete the *only* surviving trace of delegated
+  work under #840's recommended future design (prompting from parent-origin
+  events only). Verified against the real session #836 and #839 both cite
+  (`4a0d9e9b…`): under the actual 80,000-char budget, 0 notifications are
+  stubbed today (consistent with #840's finding) because the cited pair's
+  subagent copy doesn't survive the budget; with the budget cap lifted,
+  1 of 10 raw duplicate pairs in that session both survive AND still exceed
+  the 0.9 similarity bar after the pre-filter's independent per-event
+  2000-char truncation (the other 9 exceed that per-event cap and truncate
+  down far enough to fall below the bar — a conservative miss, never a wrong
+  stub). The fix is real and correct for sessions/pairs small enough to avoid
+  both eviction and truncation, and is structurally inert wherever it would
+  be unsafe to fire.
+  Implemented in the pre-filter (`preFilterSession`), which runs AFTER
+  `hashSessionContent` — so **no `contentHash` moves and no re-extraction
+  wave is triggered** (unlike #830's own folding change, which changed the
+  raw event stream #602's hash covers).
+- **Extract: regression-tested the no-double-extraction guarantee** (#839).
+  Discovery-mode extraction over a project with a parent + subagent
+  transcripts now has an explicit end-to-end test proving exactly one
+  session is processed, that `--session-id agent-<hash>` resolves to the
+  not-found result rather than an extraction, and that folded subagent
+  content is attributed only to the parent's session/contentHash. Pins
+  behavior already true since #830 (`listSessions()` excludes `subagents/`
+  dirs for both discovery and `--session-id` lookup); nothing tested it
+  end-to-end before.
+
+### Documentation
+
+- **Measured whether subagent-transcript folding (#830) duplicates the
+  parent's own summary, and disclosed the one-time re-extraction cost
+  (#833).** Using the actual reader/pre-filter/prompt-builder code against 3
+  real sessions on this machine — no LLM calls; `contentHash`,
+  `preFilterSession`, and `buildExtractPrompt` are deterministic:
+  - Raw event counts grow 2x-12x once subagent transcripts are folded in
+    (measured: 1209 -> 14224; 1583 -> 6738, the exact session cited in
+    #829/#833's "1583 -> 6738" figure; 155 -> 2408). `contentHash` is
+    computed over that stream, so every previously-extracted session's hash
+    changes and the next `--since` run re-extracts all of them once, each
+    with a larger prompt (+1.2% to +5.2% prompt chars across the 3 sessions,
+    since the 80,000-char pre-filter budget caps how much of the growth
+    actually reaches the LLM).
+  - The result is a genuine tradeoff, not a clean win or loss. **Benefit:**
+    inline `akm remember`/`akm feedback` calls made *by subagents* are
+    recovered regardless of the budget cap (inline-ref extraction runs on
+    the raw event stream, not the pre-filtered one) — up to 162 refs
+    recovered on the largest session measured (was 2 without folding),
+    fixing #829's "delegated work is never harvested" defect. **Cost:** on
+    sessions whose raw content is near or under the pre-filter's character
+    budget, folding evicts a large share of the parent's own kept content to
+    make room for subagent tool-call trace — parent-origin kept events
+    dropped 27% and 71% respectively on the two smaller sessions measured.
+    On the largest session the budget was already saturated by the parent's
+    own tail, so folding changed nothing there. Duplication is real, not
+    hypothetical: on the smallest session, one subagent's conclusion appears
+    twice in the same prompt sent to the extraction LLM — once via its own
+    folded final message, once via the parent's own record of that
+    delegated call's result, which independently already captured ~92% of
+    the same text verbatim.
+  - A narrowing that drops a subagent transcript's terminal event (its
+    apparent "final report") to avoid this specific duplication was
+    considered and rejected: the existing #830 regression fixture has a
+    subagent transcript whose *only* event is that terminal turn (a single
+    delegated `akm remember` call) — the same rule would drop the only
+    content in short single-step delegations, undoing the harvesting #830
+    added.
+  - **Decision: keep folding as shipped.** The data does not cleanly favor
+    removing or narrowing it, and the one narrowing considered would cost
+    more than it fixes. #829's phantom-session exclusion is unaffected
+    either way.
+- Recorded the fold-vs-link subagent-extraction design determination in
+  `docs/plans/subagent-extraction-design.md` (#840). Measured four candidates
+  (fold+dedupe as shipped, link-only, a harvest-without-prompting hybrid, and
+  chunked map-reduce extraction) on the same real sessions #836 used plus one
+  added for scale. Headline: the hybrid recovers 100% of #830's inline-ref
+  harvesting (162/162, 38/38, 1/1, 8/8 across the four sessions) with zero
+  parent-content eviction (vs 27.5%/28.6% evicted under fold on two of the
+  four), and #839's dedupe was measured to have zero effect on the actual
+  LLM prompt on all four sessions (the flagged duplicate content is already
+  evicted by the recency-biased budget before dedupe would matter). Chunked
+  extraction was measured at 9x-229x more LLM calls per session on real
+  data and is not recommended. No behavior changes shipped in this PR.
+
+## [0.9.2-alpha.3] - 2026-08-26
+
+### Fixed
+
+- **Currency in prose no longer retypes an asset as a command** (#824). The
+  smart-Markdown classifier matched `$1`/`$2`/`$3` with a trailing word
+  boundary, and that boundary sits between the `2` and the comma in `$2,000` —
+  so any note quoting a price was indexed as a `command`, its ref moved to
+  `commands/<dir>/<slug>`, and it left its own namespace. Measured on a real
+  corpus, 3 of 51 memory documents were affected, and those 3 were exactly the
+  3 whose bodies matched. `$ARGUMENTS` is unambiguous and keeps its existing
+  precedence over a directory hint; the numeric placeholders now exclude a
+  following digit (or a `.`/`,` followed by one), and where they still
+  disagree with a directory that declares a type, the declaration wins. The
+  defect is present identically in 0.9.1 — it only became visible once the
+  0.9.2-alpha.2 retrieval work let mistyped assets surface in results.
+
+### Documentation
+
+- Recorded the 0.9.2 retrieval measurement in
+  `docs/plans/benchmark-tuning-findings.md` §2e (#825). Retrieval-only probes
+  with no model in the loop, identical corpora, only the CLI version differing:
+  LoCoMo zero-hit 75.0% -> 0.0% and evidence recall@5 0.154 -> 0.590;
+  LongMemEval zero-hit 100% -> 0.0% and recall@5 0.000 -> 1.000.
+
 ## [0.9.2-alpha.2] - 2026-08-25
 
-- TODO
+### Fixed
+
+- **Retrieval:** relaxed zero-hit lexical queries centrally, stabilized
+  relaxed-retrieval quality, and preserved name quality through relaxed
+  ranking. This is the change measured in §2e above — it is what lifted the
+  retrieval ceiling that had floored memory-backed evaluation.
+- **Indexing:** verify vec completeness before promotion; compare vec IDs as
+  exact sets; materialize vectors for targeted writes; make nested entry
+  mutation atomic; reconcile clean before final verification; restore static
+  embedding imports.
+- **Markdown projection:** parse nested links safely, parse destination
+  phases, and project with stateful delimiters.
+- **Sources:** reconcile local bundle updates and report incomplete filesystem
+  reconciliation.
+- **Extract:** keep malformed model output retryable.
+
+### Performance
+
+- Keep targeted embedding selection narrow and preserve targeted vec
+  degradation.
 
 ## [0.9.2-alpha.1] - 2026-08-24
 

package/dist/commands/health/plugin-staleness.js

@@ -0,0 +1,219 @@
+// 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/.
+/**
+ * `plugin-version` advisory for `akm health` (itlackey/akm#832).
+ *
+ * #828 was filed as a CLI bug — session extraction failing on 232/234 runs —
+ * and took a full investigation to resolve. The actual cause: the harness
+ * plugin (`akm@akm-plugins`, installed in Claude Code's plugin cache) was
+ * three days stale relative to the fix, and its own `AKM_VERSION_RANGE` gate
+ * had nothing to do with it — the plugin was simply running old code. Every
+ * fact needed to reach that conclusion in one step was already on disk:
+ *
+ *   - installed plugin version: `~/.claude/plugins/cache/<marketplace>/akm/<version>/.claude-plugin/plugin.json`
+ *   - the plugin's own akm-cli compatibility contract: `<pluginDir>/shared/akm-version.ts`'s `AKM_VERSION_RANGE`
+ *   - the running CLI's version: `../../version.ts`'s `pkgVersion`
+ *
+ * Nothing correlated them, so a stale plugin was indistinguishable from a
+ * broken CLI. This module closes that gap with three checks, one per
+ * detected plugin:
+ *
+ *   1. report the installed version;
+ *   2. compare it against the newest tag published to the plugin's git
+ *      remote, and warn (naming the update command) when behind;
+ *   3. the sharp one — check whether the *installed plugin's* declared
+ *      `AKM_VERSION_RANGE` admits the *running* CLI version. When it does
+ *      not, the plugin has silently disabled itself (both surfaces log
+ *      `version_out_of_range` / `akm_version_mismatch` and degrade quietly)
+ *      and there was previously no way to know that from the CLI side.
+ *
+ * Read-only: this never fetches, writes, or mutates the plugin cache or
+ * marketplace clone. Check 2 is the one deliberate exception to "`akm
+ * health` makes no network call" (see `./health-advisories.md`): a plugin's
+ * local marketplace clone is not proof of what is newest upstream — the
+ * incident above involved a clone that hadn't seen the fix's tag at all — so
+ * the only way to ever detect drift is to ask the remote what tags exist.
+ * That query is a `git ls-remote --tags` (lists refs; fetches nothing,
+ * writes nothing) with a short timeout, and any failure (offline, no
+ * remote, timeout) degrades to "installed version reported, no staleness
+ * claim" rather than a false positive or a hang.
+ *
+ * Every collector here is best-effort and silent on missing/unreadable
+ * input: no Claude plugin installed, no marketplace clone, an unreadable
+ * manifest, or a malformed version range must never crash `akm health` and
+ * must never produce a false "stale" or "inactive" warning.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isExactSemver, isSemverRange, maxSatisfying, satisfiesRange } from "../../registry/semver.js";
+/**
+ * Root directory holding Claude Code's plugin cache + marketplace clones.
+ * Resolved per call (not memoized) so `AKM_CLAUDE_PLUGINS_DIR` can be set
+ * after import — the override exists so tests point this at an empty
+ * fixture directory instead of the real `~/.claude/plugins`, matching
+ * `AKM_CLAUDE_PROJECTS_DIR` in `../../integrations/harnesses/claude/session-log.ts`.
+ */
+function claudePluginsDir() {
+    return process.env.AKM_CLAUDE_PLUGINS_DIR ?? path.join(os.homedir(), ".claude", "plugins");
+}
+/**
+ * Scan `<pluginsRoot>/cache/<marketplace>/akm/<version>/` for every
+ * `akm` plugin cache entry, picking the highest cached version per
+ * marketplace when more than one is present. Returns `[]` (never throws)
+ * when the cache directory is absent, empty, or unreadable — that is the
+ * ordinary "no Claude plugin installed" case, not an error.
+ */
+function detectInstalledPlugins(pluginsRoot) {
+    const cacheDir = path.join(pluginsRoot, "cache");
+    let marketplaces;
+    try {
+        marketplaces = fs.readdirSync(cacheDir);
+    }
+    catch {
+        return [];
+    }
+    const detected = [];
+    for (const marketplace of marketplaces) {
+        const pluginDir = path.join(cacheDir, marketplace, "akm");
+        let versions;
+        try {
+            versions = fs.readdirSync(pluginDir).filter(isExactSemver);
+        }
+        catch {
+            continue;
+        }
+        if (versions.length === 0)
+            continue;
+        const latest = maxSatisfying(versions, "*") ?? versions.sort().at(-1);
+        if (!latest)
+            continue;
+        const versionDir = path.join(pluginDir, latest);
+        const manifestPath = path.join(versionDir, ".claude-plugin", "plugin.json");
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+            if (typeof manifest.version !== "string")
+                continue;
+            detected.push({
+                harness: "claude",
+                marketplace,
+                pluginName: "akm",
+                version: manifest.version,
+                pluginDir: versionDir,
+            });
+        }
+        catch {
+            // Unreadable/malformed manifest — skip this entry rather than crash.
+        }
+    }
+    return detected;
+}
+/**
+ * Extract `AKM_VERSION_RANGE` from the installed plugin's vendored
+ * `shared/akm-version.ts`. Returns `undefined` when the file is missing,
+ * unreadable, or does not contain the expected declaration — callers must
+ * treat that as "compatibility unknown", never as a mismatch.
+ */
+function readVersionRange(pluginDir) {
+    const versionFilePath = path.join(pluginDir, "shared", "akm-version.ts");
+    let text;
+    try {
+        text = fs.readFileSync(versionFilePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const match = text.match(/export\s+const\s+AKM_VERSION_RANGE\s*=\s*["']([^"']+)["']/);
+    return match?.[1];
+}
+const LS_REMOTE_TIMEOUT_MS = 5_000;
+/**
+ * `git ls-remote --tags origin` against the marketplace clone's configured
+ * remote — lists refs only, fetches no objects, writes no local refs.
+ * Returns `undefined` (never throws) when the directory is not a git
+ * checkout, has no `origin` remote, or the command fails/times out (e.g.
+ * offline) — all "cannot determine availability", not "up to date".
+ */
+const realListRemoteTags = (marketplaceDir) => {
+    let result;
+    try {
+        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--tags", "origin"], {
+            encoding: "utf8",
+            timeout: LS_REMOTE_TIMEOUT_MS,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (result.status !== 0 || !result.stdout)
+        return undefined;
+    const tags = result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.split("\t")[1])
+        .filter((ref) => typeof ref === "string" && ref.startsWith("refs/tags/"))
+        .map((ref) => ref.replace(/^refs\/tags\//, "").replace(/\^\{\}$/, ""))
+        .map((tag) => tag.replace(/^v/, ""))
+        .filter(isExactSemver);
+    return [...new Set(tags)];
+};
+/**
+ * Build one `plugin-version` advisory per detected `akm` harness plugin.
+ * Returns `[]` when no plugin is installed — the benign, common case.
+ */
+export function collectPluginStalenessAdvisories(options) {
+    const pluginsRoot = options.pluginsRoot ?? claudePluginsDir();
+    const listRemoteTags = options.listRemoteTags ?? realListRemoteTags;
+    const plugins = detectInstalledPlugins(pluginsRoot);
+    return plugins.map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags));
+}
+function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags) {
+    const pluginRef = `${plugin.pluginName}@${plugin.marketplace}`;
+    // Point 2: newest available vs. installed, via the marketplace clone's remote.
+    const marketplaceDir = path.join(pluginsRoot, "marketplaces", plugin.marketplace);
+    let availableVersion;
+    try {
+        const tags = fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
+        availableVersion = tags && tags.length > 0 ? maxSatisfying(tags, "*") : undefined;
+    }
+    catch {
+        availableVersion = undefined;
+    }
+    const stale = availableVersion !== undefined &&
+        plugin.version !== availableVersion &&
+        maxSatisfying([plugin.version, availableVersion], "*") === availableVersion;
+    // Point 3: does the plugin's own declared range admit the running CLI?
+    const versionRange = readVersionRange(plugin.pluginDir);
+    const rangeKnown = versionRange !== undefined && isSemverRange(versionRange);
+    const admitted = rangeKnown ? satisfiesRange(cliVersion, versionRange) : undefined;
+    const messageParts = [`${pluginRef}: installed ${plugin.version}`];
+    if (availableVersion !== undefined) {
+        messageParts.push(stale ? `available ${availableVersion} (STALE)` : `available ${availableVersion} (up to date)`);
+    }
+    if (stale)
+        messageParts.push(`-> claude plugin update ${pluginRef}`);
+    if (rangeKnown && admitted === false) {
+        messageParts.push(`installed plugin requires akm-cli ${versionRange}; running ${cliVersion} -> NOT ADMITTED (plugin is inactive)`);
+    }
+    return {
+        name: "plugin-version",
+        kind: "deterministic",
+        status: stale || admitted === false ? "warn" : "pass",
+        confidence: "high",
+        message: messageParts.join(" — "),
+        evidence: {
+            harness: plugin.harness,
+            marketplace: plugin.marketplace,
+            plugin: plugin.pluginName,
+            installedVersion: plugin.version,
+            availableVersion: availableVersion ?? null,
+            stale,
+            versionRange: versionRange ?? null,
+            cliVersion,
+            admitted: admitted ?? null,
+        },
+    };
+}

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) })),
+        },
+    };
+}