akm-cli 0.10.261126 → 0.10.261127

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/dist/commands/health/improve-metrics.js +23 -3
  3. package/dist/commands/health/md-report.js +4 -3
  4. package/dist/commands/improve/consolidate/pair-pass.js +52 -27
  5. package/dist/commands/improve/loop-stages.js +3 -2
  6. package/dist/commands/lint/base-linter.js +23 -20
  7. package/dist/commands/lint/index.js +26 -4
  8. package/dist/commands/sources/plugin-upgrade.js +23 -3
  9. package/dist/core/adapter/adapters/akm-lint.js +35 -12
  10. package/dist/core/adapter/adapters/shared.js +11 -22
  11. package/dist/core/asset/asset-ref.js +3 -2
  12. package/dist/core/asset/frontmatter-lint.js +17 -22
  13. package/dist/core/asset/lint-text.js +50 -0
  14. package/dist/indexer/indexer.js +5 -0
  15. package/dist/output/text/command-format.js +2 -1
  16. package/dist/scripts/akm-migrate-node.js +86 -37
  17. package/dist/scripts/akm-migrate.js +86 -37
  18. package/dist/storage/repositories/index-layout-repository.js +81 -0
  19. package/dist/storage/repositories/index-schema.js +18 -0
  20. package/dist/storage/repositories/task-history-repository.js +28 -0
  21. package/dist/storage/repositories/workflow-runs-repository.js +25 -0
  22. package/dist/tasks/run/attempt-lifecycle.js +8 -1
  23. package/dist/tasks/run/reconcile-abandoned.js +75 -0
  24. package/dist/tasks/run/run-task.js +9 -1
  25. package/dist/tasks/run/task-result.js +2 -0
  26. package/dist/workspace/graph-duplicates.js +124 -28
  27. package/dist/workspace/graph.js +39 -7
  28. package/docs/architecture/internals/health-advisories.md +1 -1
  29. package/docs/architecture/internals/improve-workflow.md +1 -1
  30. package/docs/architecture/internals/indexing.md +2 -2
  31. package/docs/architecture/internals/storage-locations.md +23 -4
  32. package/docs/reference/cli.md +7 -2
  33. package/docs/reference/workspace.md +11 -8
  34. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.10.261127] - 2026-11-15
10
+
11
+ ### Added
12
+
13
+ - AKM Desktop's library map draws every embedded asset in 3D, grouped by meaning instead of by bundle or type, when the index holds groups: each group is named by the tags its assets carry most particularly, and choosing a group or an asset flies to it and draws its links and near-duplicates. Inside a group, assets read lately sit at the front and never-read or outdated ones at the back. Flat switches to the mind map. The 3D view needs WebGL.
14
+ - `akm-cli/workspace`: `assets.graph()` returns `groups`, each asset's group by meaning and its place in 3D.
15
+
16
+ ### Fixed
17
+
18
+ - `akm migrate` (and the migration every `akm upgrade` runs) rewrote legacy asset refs inside any file a bundle's adapter recognized, so in a bundle read with `generic-files` it changed frozen benchmark JSON, captured results and scripts, which then blocked `akm bundle update`. It now rewrites refs only in markdown and YAML files; everything else stays byte-for-byte. Files an earlier run already rewrote are not restored: restore them from git or from the run's backup under `$DATA/backups/asset-content-refs/`.
19
+ - A consolidate pair judgment that failed (transport error, an unparseable verdict after the retry, cancellation, or a failed proposal mint) kept no reason. The pair pass result now carries `failureKinds` and up to 20 `failures`, each with a clipped one-line reason and no prompt or reply text; the run gets a warning, and `akm health` counts failed pairs (`consolidation.failedPairs`) and lists the run among failed runs. The pairs are still retried next run.
20
+ - An improve run whose reflection candidates the quality judge rejected (churn, unsupported claims, lost specificity) was reported as failed by `akm health`. A quality rejection is now `reflect-guard-rejected` and counted as `reflect.rejected` (also for older runs that recorded it as `reflect-failed`), not as a failure; runtime and persistence failures still are. The candidates stay unapplied.
21
+ - A task attempt whose process crashed stayed `active` in task history forever, and workflow units stayed `running` under a run that had failed. Each task run now marks an attempt `interrupted` when its owner is provably gone (a different boot, a dead or reused pid), and settles units still running under a finished run that no process drives any more as failed with reason `interrupted`. An attempt whose owner is alive, or on another host, is left as it is however long it runs; no history is deleted.
22
+ - `akm lint` and bundle validation no longer report: a description that parses as valid YAML (a URL, `admin:snapshot`) as an unquoted colon; a grouping directory such as `skills/personal/` that holds skills as a skill without `SKILL.md` (an incomplete skill inside a group is reported by its own path); `[REDACTED]` inside code, quotes or a blockquote as damaged content; sentence punctuation after a ref as part of it (`tasks/x.` looked for `x..md`); or a missing path on a line or under a heading that presents it as history or an example, or under another host's home directory. Malformed YAML, incomplete skills, broken refs and missing current paths are still reported.
23
+ - `akm upgrade` printed a plugin left on its own channel as just "current" and did not say when its bundled akm differed from the CLI. A plugin is now "current within its configured channel", a skipped plugin keeps its reason in AKM Desktop too, and a plugin whose bundled akm differs from the CLI names the engine skew `akm health` reports, in the CLI, its JSON and AKM Desktop alike. Channels are still never switched without `--channel`.
24
+
25
+ ### Changed
26
+
27
+ - `akm index` groups the embedded assets by meaning and finds the near-duplicate pairs at the end of a build whose vectors changed, and stores them in `index.db` (`entry_layout`, `duplicate_pairs`); `assets.graph` reads them instead of computing them, so a library map read of 16,000 assets takes about one second instead of six. Near-duplicates are now compared across all embedded assets and filtered to the enabled bundles, and they and `groups` are `null` until the first `akm index` of this release.
28
+
9
29
  ## [0.10.261126] - 2026-11-15
10
30
 
11
31
  ### Changed
@@ -81,7 +81,7 @@ export function emptyImproveMetrics() {
81
81
  skipReasons: {},
82
82
  resultRows: { total: 0, included: 0, skipped: { invalid: 0 } },
83
83
  actions: {
84
- reflect: { ok: 0, failed: 0, cooldown: 0, skipped: 0 },
84
+ reflect: { ok: 0, failed: 0, cooldown: 0, skipped: 0, rejected: 0 },
85
85
  distill: {
86
86
  queued: 0,
87
87
  llmFailed: 0,
@@ -106,6 +106,8 @@ export function emptyImproveMetrics() {
106
106
  judgedNoAction: 0,
107
107
  failedChunks: 0,
108
108
  totalChunks: 0,
109
+ pairsJudged: 0,
110
+ failedPairs: 0,
109
111
  durationMs: 0,
110
112
  },
111
113
  memoryInference: {
@@ -137,8 +139,17 @@ function applyAction(metrics, action) {
137
139
  case "reflect":
138
140
  metrics.actions.reflect.ok += 1;
139
141
  break;
140
- case "reflect-failed":
141
- metrics.actions.reflect.failed += 1;
142
+ case "reflect-failed": {
143
+ // Runs recorded before a quality rejection had its own mode carry it as `reflect-failed`.
144
+ const result = action.result;
145
+ if (result?.reason === "quality_rejected")
146
+ metrics.actions.reflect.rejected += 1;
147
+ else
148
+ metrics.actions.reflect.failed += 1;
149
+ break;
150
+ }
151
+ case "reflect-guard-rejected":
152
+ metrics.actions.reflect.rejected += 1;
142
153
  break;
143
154
  case "reflect-cooldown":
144
155
  metrics.actions.reflect.cooldown += 1;
@@ -218,6 +229,11 @@ function projectRunMetrics(result) {
218
229
  cons.failedChunks += toFiniteNumber(consolidation.failedChunks);
219
230
  cons.totalChunks += toFiniteNumber(consolidation.totalChunks);
220
231
  cons.durationMs += toFiniteNumber(consolidation.durationMs);
232
+ const pairPass = consolidation.pairPass;
233
+ if (pairPass) {
234
+ cons.pairsJudged += toFiniteNumber(pairPass.pairsJudged);
235
+ cons.failedPairs += toFiniteNumber(pairPass.failedJudgments);
236
+ }
221
237
  }
222
238
  const memoryInference = result.memoryInference;
223
239
  if (memoryInference) {
@@ -250,6 +266,7 @@ function mergeImproveMetrics(dst, src) {
250
266
  dst.actions.reflect.failed += src.actions.reflect.failed;
251
267
  dst.actions.reflect.cooldown += src.actions.reflect.cooldown;
252
268
  dst.actions.reflect.skipped += src.actions.reflect.skipped;
269
+ dst.actions.reflect.rejected += src.actions.reflect.rejected;
253
270
  dst.actions.distill.queued += src.actions.distill.queued;
254
271
  dst.actions.distill.llmFailed += src.actions.distill.llmFailed;
255
272
  dst.actions.distill.judgeRejected += src.actions.distill.judgeRejected;
@@ -272,6 +289,8 @@ function mergeImproveMetrics(dst, src) {
272
289
  dst.consolidation.judgedNoAction += src.consolidation.judgedNoAction;
273
290
  dst.consolidation.failedChunks += src.consolidation.failedChunks;
274
291
  dst.consolidation.totalChunks += src.consolidation.totalChunks;
292
+ dst.consolidation.pairsJudged += src.consolidation.pairsJudged;
293
+ dst.consolidation.failedPairs += src.consolidation.failedPairs;
275
294
  dst.consolidation.durationMs += src.consolidation.durationMs;
276
295
  dst.memoryInference.considered += src.memoryInference.considered;
277
296
  dst.memoryInference.freshAttempts += src.memoryInference.freshAttempts;
@@ -321,6 +340,7 @@ export function summarizeImproveRuns(db, since, until) {
321
340
  perRow.actions.distill.llmFailed > 0 ||
322
341
  perRow.actions.error > 0 ||
323
342
  perRow.consolidation.failedChunks > 0 ||
343
+ perRow.consolidation.failedPairs > 0 ||
324
344
  perRow.memoryInference.skippedNoFacts > 0 ||
325
345
  (!interrupted && (!row.ok || terminationReason !== undefined))) {
326
346
  outcomes.failedRunIds.push(row.id);
@@ -18,7 +18,7 @@ function renderTable(headers, rows) {
18
18
  * Render `--detail per-run` rows as a TSV-ish aligned table. The column
19
19
  * shape is stable so repeated operator reports remain easy to compare.
20
20
  *
21
- * Columns: ts | ok | actions | refl_ok/fail/cd/skip |
21
+ * Columns: ts | ok | actions | refl_ok/fail/cd/skip/rej |
22
22
  * distill_q/llm-fail/qrej/cfg/skip | cons_proc/promo/merge/del |
23
23
  * mem_cons/written/nochange/skip | orphans | lint_f/fl
24
24
  */
@@ -28,7 +28,7 @@ export function renderRunsDetailMd(runs) {
28
28
  "ok",
29
29
  "strategy",
30
30
  "actions",
31
- "refl_ok/fail/cd/skip",
31
+ "refl_ok/fail/cd/skip/rej",
32
32
  "distill_q/llm-fail/judge/validator/cfg/skip",
33
33
  "cons_proc/promo/merge/del",
34
34
  "mem_cons/written/nochange/skip",
@@ -41,6 +41,7 @@ export function renderRunsDetailMd(runs) {
41
41
  r.actions.reflect.failed +
42
42
  r.actions.reflect.cooldown +
43
43
  r.actions.reflect.skipped +
44
+ r.actions.reflect.rejected +
44
45
  r.actions.distill.queued +
45
46
  r.actions.distill.llmFailed +
46
47
  r.actions.distill.judgeRejected +
@@ -55,7 +56,7 @@ export function renderRunsDetailMd(runs) {
55
56
  String(r.ok),
56
57
  r.strategy ?? "",
57
58
  String(totalActions),
58
- `${r.actions.reflect.ok}/${r.actions.reflect.failed}/${r.actions.reflect.cooldown}/${r.actions.reflect.skipped}`,
59
+ `${r.actions.reflect.ok}/${r.actions.reflect.failed}/${r.actions.reflect.cooldown}/${r.actions.reflect.skipped}/${r.actions.reflect.rejected}`,
59
60
  `${r.actions.distill.queued}/${r.actions.distill.llmFailed}/${r.actions.distill.judgeRejected}/${r.actions.distill.validatorRejected}/${r.actions.distill.configDisabled}/${r.actions.distill.skipped}`,
60
61
  `${r.consolidation.processed}/${r.consolidation.promoted}/${r.consolidation.merged}/${r.consolidation.deleted}`,
61
62
  `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.noChange}/${r.memoryInference.skippedNoFacts}`,
@@ -38,6 +38,7 @@ import { SHIPPED_ALIAS } from "../../../core/config/model-aliases.js";
38
38
  import { UsageError } from "../../../core/errors.js";
39
39
  import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
40
40
  import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
41
+ import { redactErrorBody } from "../../../core/redaction.js";
41
42
  import { warnOnce } from "../../../core/warn.js";
42
43
  import { sameScope, scopeFromFrontmatter } from "../../../indexer/passes/metadata.js";
43
44
  import { runGit } from "../../../sources/providers/git-install.js";
@@ -582,8 +583,9 @@ export const pairJudge = {
582
583
  parse: parsePairJudgeResponse,
583
584
  ...(call.onNotices ? { onNotices: call.onNotices } : {}),
584
585
  });
585
- if (!outcome.ok)
586
- return { outcome: "error", reason: outcome.error };
586
+ if (!outcome.ok) {
587
+ return { outcome: "error", reason: outcome.error, ...(outcome.reason === "aborted" ? { aborted: true } : {}) };
588
+ }
587
589
  const verdict = parsePairJudgeResponse(outcome.raw);
588
590
  if (!verdict)
589
591
  return { outcome: "unparseable", reason: "the reply held no verdict in the expected shape" };
@@ -648,6 +650,15 @@ async function confirmNothingLost(ctx, retired, successor) {
648
650
  return false;
649
651
  return claimList(parseEmbeddedJsonResponse(outcome.raw)?.missing)?.length === 0;
650
652
  }
653
+ const PAIR_FAILURES_REPORTED_MAX = 20;
654
+ /** A bounded one-line reason with URLs and credentials removed; never the prompt or the reply. */
655
+ function failedPair(kind, reason) {
656
+ const line = reason
657
+ .replace(/https?:\/\/\S+/g, "<url>")
658
+ .replace(/\s+/g, " ")
659
+ .trim();
660
+ return { failure: { kind, reason: redactErrorBody(line) } };
661
+ }
651
662
  /**
652
663
  * One pair: judge it, then (for a retire class) apply the guards and mint
653
664
  * the proposal. Never throws — a failure is counted in `failedJudgments` or
@@ -657,10 +668,10 @@ async function judgeOne(ctx, candidate) {
657
668
  const initiatorSide = loadSide(candidate.initiator, ctx.gitFirstAdded, ctx.stashDir);
658
669
  const otherSide = loadSide(candidate.other, ctx.gitFirstAdded, ctx.stashDir);
659
670
  if (!initiatorSide || !otherSide)
660
- return { failed: false }; // unreadable since selection — skip, not a judge failure
671
+ return {}; // unreadable since selection — skip, not a judge failure
661
672
  const judgedScope = scopeFromFrontmatter(initiatorSide.frontmatter);
662
673
  if (!sameScope(judgedScope, scopeFromFrontmatter(otherSide.frontmatter)))
663
- return { failed: false };
674
+ return {};
664
675
  const scopesStillFresh = () => [initiatorSide, otherSide].every((side) => {
665
676
  const live = loadSide(side.asset, ctx.gitFirstAdded, ctx.stashDir);
666
677
  return live !== undefined && sameScope(judgedScope, scopeFromFrontmatter(live.frontmatter));
@@ -675,7 +686,7 @@ async function judgeOne(ctx, candidate) {
675
686
  const otherHash = contentHash(otherSide.raw, "body");
676
687
  if (ctx.rejectedPairKeys.has(rejectedPairKey(initiatorSide.asset.ref, otherSide.asset.ref, initiatorHash, otherHash)) ||
677
688
  ctx.rejectedPairKeys.has(rejectedPairKey(otherSide.asset.ref, initiatorSide.asset.ref, otherHash, initiatorHash))) {
678
- return { failed: false };
689
+ return {};
679
690
  }
680
691
  const { older, newer } = orderByAge(initiatorSide, otherSide);
681
692
  const judged = await pairJudge.run({ a: pairNoteOf(older), b: pairNoteOf(newer) }, {
@@ -684,24 +695,26 @@ async function judgeOne(ctx, candidate) {
684
695
  ...(ctx.chat ? { chat: ctx.chat } : {}),
685
696
  ...(ctx.opts.onNotices ? { onNotices: ctx.opts.onNotices } : {}),
686
697
  });
687
- if (judged.outcome !== "verdict")
688
- return { failed: true };
698
+ if (judged.outcome === "unparseable")
699
+ return failedPair("parse", judged.reason);
700
+ if (judged.outcome === "error")
701
+ return failedPair(judged.aborted ? "cancelled" : "transport", judged.reason);
689
702
  const { verdict } = judged;
690
703
  ctx.labelCounts[verdict.relation]++;
691
704
  if (verdict.relation === "contradicts")
692
- return { failed: false }; // counted; stays human — no proposal, no belief write
705
+ return {}; // counted; stays human — no proposal, no belief write
693
706
  if (!isRetireLabel(verdict.relation))
694
- return { failed: false }; // overlap / unrelated: judged_no_action
707
+ return {}; // overlap / unrelated: judged_no_action
695
708
  const decision = decideRetirement(verdict.relation, verdict.redundant, older, newer, verdict);
696
709
  if (!decision)
697
- return { failed: false };
710
+ return {};
698
711
  let { retired, successor } = decision;
699
712
  // Owner rule (#1092): knowledge is never replaced with a memory (a `.derived` memory is a memory). When the memory
700
713
  // holds nothing the note lacks, retire the memory in favour of the note instead; otherwise leave the pair alone.
701
714
  // The flipped pair then runs every guard below like any memory retirement.
702
715
  if (retired.asset.type === "knowledge" && successor.asset.type === "memory") {
703
716
  if ((successor === older ? verdict.onlyInA : verdict.onlyInB).length > 0)
704
- return { failed: false };
717
+ return {};
705
718
  [retired, successor] = [successor, retired];
706
719
  }
707
720
  // Guards (plan §5.2 step 4 / brief §A "Guards").
@@ -712,7 +725,7 @@ async function judgeOne(ctx, candidate) {
712
725
  // ends in "sub") with it used to double the subfolder segment.
713
726
  const parentPath = retired.asset.filePath.replace(/\.derived\.md$/, ".md");
714
727
  if (fs.existsSync(parentPath))
715
- return { failed: false }; // never retire a .derived memory whose parent still exists
728
+ return {}; // never retire a .derived memory whose parent still exists
716
729
  }
717
730
  const retiredHash = contentHash(retired.raw, "body");
718
731
  const successorHash = contentHash(successor.raw, "body");
@@ -727,15 +740,16 @@ async function judgeOne(ctx, candidate) {
727
740
  // conflicting retirement has been reviewed, may well mint it. Counted as
728
741
  // failed so its initiator gets no row (real data: night 1 alone judged 177
729
742
  // duplicate verdicts into only 59 proposals — 118 silently abandoned).
730
- if (ctx.retiredThisRun.has(retiredKey) || ctx.retiredThisRun.has(successorKey))
731
- return { failed: true };
743
+ if (ctx.retiredThisRun.has(retiredKey) || ctx.retiredThisRun.has(successorKey)) {
744
+ return failedPair("other", "a note in this pair was already retired earlier in this run");
745
+ }
732
746
  ctx.retiredThisRun.add(retiredKey);
733
747
  ctx.retiredThisRun.add(successorKey);
734
748
  const reason = tombstoneReason(verdict.relation);
735
749
  if (ctx.opts.dryRun) {
736
750
  ctx.retired.push(`${retired.asset.ref} -> ${successor.asset.ref}`);
737
751
  ctx.perInitiatorProposed.add(candidate.initiator.ref);
738
- return { failed: false };
752
+ return {};
739
753
  }
740
754
  // Continuity check (plan §5.4, rule R3): replay the retired asset's own
741
755
  // past queries and flag, but do not block, a pair where the successor
@@ -751,7 +765,7 @@ async function judgeOne(ctx, candidate) {
751
765
  search: ctx.continuitySearch,
752
766
  });
753
767
  if (!scopesStillFresh())
754
- return { failed: true };
768
+ return failedPair("other", "a note changed scope while the pair was being judged");
755
769
  const retirement = {
756
770
  judgedScope,
757
771
  retiredRef: retired.asset.ref,
@@ -802,14 +816,14 @@ async function judgeOne(ctx, candidate) {
802
816
  contentHash: proposalContentHash(proposal),
803
817
  }, ctx.opts.proposalsCtx);
804
818
  }
805
- return { failed: false };
819
+ return {};
806
820
  }
807
821
  catch (error) {
808
822
  ctx.warnings.push(`Pair pass: could not mint a retire proposal for ${retired.asset.ref}: ${error instanceof Error ? error.message : String(error)}`);
809
823
  // A mint failure is transient (a lock, a disk error, a
810
824
  // validation hiccup) — treated the same as a same-run drop, so no row is
811
825
  // written and the pair is retried next run instead of abandoned.
812
- return { failed: true };
826
+ return failedPair("other", error instanceof Error ? error.message : String(error));
813
827
  }
814
828
  }
815
829
  const emptyLabelCounts = () => ({
@@ -943,7 +957,7 @@ seams = {}) {
943
957
  // every remaining query in this run, not just one proposal's own five.
944
958
  continuitySearch: seams.continuitySearch ?? createContinuitySearch(stashDir, config),
945
959
  };
946
- let failedJudgments = 0;
960
+ const failures = [];
947
961
  // An initiator with any failed (or never-sent) judge call
948
962
  // gets no ledger row — a failure attempted nothing conclusive, so writing
949
963
  // one would mean the pair is never retried.
@@ -951,14 +965,14 @@ seams = {}) {
951
965
  if (judgeable.length > 0) {
952
966
  const results = await concurrentMap(judgeable, (candidate) => judgeOne(ctx, candidate), (llmRunner.kind === "connection" ? llmRunner.concurrency : undefined) ?? 1, { signal: opts.signal });
953
967
  results.forEach((r, idx) => {
954
- // `concurrentMap` leaves an entry `undefined` for a call an
955
- // aborted run never sent at all — `r?.failed === true` reads that as
956
- // `undefined === true` (false), so an unsent call counted as a clean
957
- // "no action" verdict. Explicit `undefined` check closes that gap.
958
- if (r === undefined || r.failed === true) {
959
- failedJudgments++;
960
- failedInitiators.add(judgeable[idx].initiator.ref);
961
- }
968
+ // `concurrentMap` leaves an entry `undefined` for a call an aborted run never sent at all: that pair did not
969
+ // settle either, so it is counted as cancelled rather than as a clean "no action" verdict.
970
+ const failure = r === undefined ? { kind: "cancelled", reason: "not sent: the run was cancelled" } : r.failure;
971
+ if (!failure)
972
+ return;
973
+ const candidate = judgeable[idx];
974
+ failedInitiators.add(candidate.initiator.ref);
975
+ failures.push({ initiator: candidate.initiator.ref, other: candidate.other.ref, ...failure });
962
976
  });
963
977
  }
964
978
  // S1: a ledger row is written for an initiator only once ALL of its OWN
@@ -992,6 +1006,16 @@ seams = {}) {
992
1006
  }));
993
1007
  recordLedgerAttempt({ proposalsCtx: opts.proposalsCtx }, ledgerInputs);
994
1008
  }
1009
+ const failedJudgments = failures.length;
1010
+ const failureKinds = {};
1011
+ for (const { kind } of failures)
1012
+ failureKinds[kind] = (failureKinds[kind] ?? 0) + 1;
1013
+ if (failedJudgments > 0) {
1014
+ const kinds = Object.entries(failureKinds)
1015
+ .map(([kind, n]) => `${kind} ${n}`)
1016
+ .join(", ");
1017
+ warnings.push(`Pair pass: ${failedJudgments} of ${judgeable.length} pair judgments did not settle (${kinds}); they are retried next run.`);
1018
+ }
995
1019
  return {
996
1020
  initiators: initiators.length,
997
1021
  initiatorsBacklog,
@@ -1002,5 +1026,6 @@ seams = {}) {
1002
1026
  labelCounts: ctx.labelCounts,
1003
1027
  retired: ctx.retired,
1004
1028
  failedJudgments,
1029
+ ...(failedJudgments > 0 ? { failureKinds, failures: failures.slice(0, PAIR_FAILURES_REPORTED_MAX) } : {}),
1005
1030
  };
1006
1031
  }
@@ -158,13 +158,14 @@ async function runLoopReflectPass(planned, env, tally) {
158
158
  const result = await attributeStage(resolvedPlan, "reflect", () => env.reflectFn(reflectArgs));
159
159
  const reason = result.ok ? undefined : result.reason;
160
160
  // A refused type or an unchanged asset is a deterministic skip, not an LLM
161
- // fault; a guard rejection (size rail) gets its own bucket for health.
161
+ // fault; a guard or quality-judge rejection is a verdict on produced content,
162
+ // not an execution failure, and gets its own bucket for health.
162
163
  const skipped = reason === "unsupported_type" || reason === "no_change";
163
164
  tally.actions.push({
164
165
  ref: planned.ref,
165
166
  mode: result.ok
166
167
  ? "reflect"
167
- : reason === "content_policy_reject"
168
+ : reason === "content_policy_reject" || reason === "quality_rejected"
168
169
  ? "reflect-guard-rejected"
169
170
  : skipped
170
171
  ? "reflect-skipped"
@@ -38,6 +38,7 @@ import { assetPathCandidatesForName, assetPathForName, filesForRef, stashDirFor,
38
38
  import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
39
39
  import { removeFrontmatterListValues, rewriteFrontmatterListValue, spliceFrontmatterLine, } from "../../core/asset/frontmatter.js";
40
40
  import { checkUnquotedDescriptionColon } from "../../core/asset/frontmatter-lint.js";
41
+ import { findCurrentPathReferences, homeRootOf } from "../../core/asset/lint-text.js";
41
42
  import { isArchivedRelPath } from "../../core/asset/memory-archive.js";
42
43
  import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
43
44
  import { localDateStamp } from "../../core/common.js";
@@ -135,27 +136,17 @@ function fixMissingUpdated(raw, mtime) {
135
136
  }
136
137
  // ── stale-path helpers ────────────────────────────────────────────────────────
137
138
  /**
138
- * A path segment shaped like a run-time filename template rather than a
139
- * literal reference: `<timestamp>`-style angle brackets, `{stamp}`/`${VAR}`
140
- * braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters, or a glob
141
- * character. Such a path never exists under its literal spelling, so
142
- * `stale-path` skips it instead of flagging it.
139
+ * Absolute paths presented as current guidance that do not exist on this host.
140
+ * Paths under a home directory this host does not have belong to another host
141
+ * or user and are not checked.
143
142
  */
144
- const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
145
143
  function checkStalePath(body) {
146
- const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
147
- let match;
148
- const stale = [];
149
- // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
150
- while ((match = pathRe.exec(body)) !== null) {
151
- const candidate = match[0];
152
- if (PATH_PLACEHOLDER_PATTERN.test(candidate))
153
- continue;
154
- if (!fs.existsSync(candidate)) {
155
- stale.push(candidate);
156
- }
157
- }
158
- return stale;
144
+ return findCurrentPathReferences(body).filter((candidate) => {
145
+ const home = homeRootOf(candidate);
146
+ if (home !== undefined && !fs.existsSync(home))
147
+ return false;
148
+ return !fs.existsSync(candidate);
149
+ });
159
150
  }
160
151
  // ── fence-strip helper ────────────────────────────────────────────────────────
161
152
  /**
@@ -173,6 +164,18 @@ function stripFencedBlocks(body) {
173
164
  }
174
165
  return lines.join("\n");
175
166
  }
167
+ /**
168
+ * `raw` without fenced code blocks, inline code spans, double-quoted text and
169
+ * blockquote lines: places where `[REDACTED]` is documented or quoted as an
170
+ * example rather than left behind by damaged content.
171
+ */
172
+ function stripQuotedExamples(raw) {
173
+ return stripFencedBlocks(raw)
174
+ .split("\n")
175
+ .filter((line) => !/^\s*>/.test(line))
176
+ .join("\n")
177
+ .replace(/`[^`\n]*`|"[^"\n]*"|\u201c[^\u201d\n]*\u201d/g, "");
178
+ }
176
179
  // ── missing-ref helpers ───────────────────────────────────────────────────────
177
180
  /**
178
181
  * Map from ref type to relative path pattern within stashRoot. Returns null to
@@ -646,7 +649,7 @@ export function runBaseChecks(ctx) {
646
649
  .map((v) => String(v).trim())
647
650
  .filter(Boolean);
648
651
  const shouldRun = (issueType) => !lintSkip.includes(issueType);
649
- if (shouldRun("redacted-content") && containsRedactedContent(currentRaw)) {
652
+ if (shouldRun("redacted-content") && containsRedactedContent(stripQuotedExamples(currentRaw))) {
650
653
  issues.push({
651
654
  file: ctx.relPath,
652
655
  issue: "redacted-content",
@@ -3,7 +3,7 @@
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  import fs from "node:fs";
5
5
  import path from "node:path";
6
- import { factDiagnostics, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowFrontendDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
6
+ import { factDiagnostics, MAX_SKILL_GROUP_DEPTH, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowFrontendDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
7
7
  import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
8
8
  import { adapterForId } from "../../core/adapter/registry.js";
9
9
  import { createValidateContext } from "../../core/adapter/validate-context.js";
@@ -403,15 +403,37 @@ function isFileDeletion(issue) {
403
403
  // MemoryLinter/WorkflowLinter `--fix` behavior byte-for-byte.
404
404
  /**
405
405
  * Reproduce `SkillLinter.lintDirectory`: a skill subdirectory with no
406
- * `SKILL.md` is flagged `missing-skill-md` (never auto-fixable). Exported for
407
- * the lint-parity golden (`tests/integration/goldens-lint-output.test.ts`).
406
+ * `SKILL.md` is flagged `missing-skill-md` (never auto-fixable). A directory
407
+ * that has none itself but holds skill packages is a grouping directory: it is
408
+ * not flagged, its children are checked instead. Exported for the lint-parity
409
+ * golden (`tests/integration/goldens-lint-output.test.ts`).
408
410
  */
409
- export function lintSkillDirectory(subdirPath, stashRoot) {
411
+ export function lintSkillDirectory(subdirPath, stashRoot, depth = 1) {
410
412
  if (fs.existsSync(path.join(subdirPath, "SKILL.md")))
411
413
  return [];
414
+ const children = depth < MAX_SKILL_GROUP_DEPTH
415
+ ? fs
416
+ .readdirSync(subdirPath, { withFileTypes: true })
417
+ .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
418
+ .map((entry) => path.join(subdirPath, entry.name))
419
+ : [];
420
+ if (children.some((child) => containsSkillManifest(child, depth + 1))) {
421
+ return children.flatMap((child) => lintSkillDirectory(child, stashRoot, depth + 1));
422
+ }
412
423
  const relDir = path.relative(stashRoot, subdirPath);
413
424
  return [{ file: relDir, issue: "missing-skill-md", detail: `no SKILL.md in ${relDir}/`, fixed: false }];
414
425
  }
426
+ function containsSkillManifest(dir, depth) {
427
+ if (fs.existsSync(path.join(dir, "SKILL.md")))
428
+ return true;
429
+ if (depth >= MAX_SKILL_GROUP_DEPTH)
430
+ return false;
431
+ return fs
432
+ .readdirSync(dir, { withFileTypes: true })
433
+ .some((entry) => entry.isDirectory() &&
434
+ !entry.name.startsWith(".") &&
435
+ containsSkillManifest(path.join(dir, entry.name), depth + 1));
436
+ }
415
437
  /** MemoryLinter's `orphaned-stub` check WITH its `--fix` delete (memory-linter.ts:19-65). */
416
438
  function appendMemoryStubIssue(ctx, issues) {
417
439
  if (ctx.lintSkip?.includes("orphaned-stub") || !memoryOrphanStubApplies(ctx.data, ctx.body))
@@ -20,6 +20,7 @@ import { opencodeCacheDir, opencodeConfigDir } from "../../integrations/harnesse
20
20
  import { detectOpencodeMajor, OPENCODE_BIN, resolveOpencodeBin } from "../../integrations/harnesses/opencode/version.js";
21
21
  import { isExactSemver, isPrerelease } from "../../registry/semver.js";
22
22
  import { semverOrder } from "../../runtime.js";
23
+ import { collectPluginStalenessAdvisories } from "../health/plugin-staleness.js";
23
24
  import { ChannelWriteError, claudeChannelEdits, codexChannelEdit, codexMarketplace, editChannelJson, writeChannelEdits, } from "./plugin-channels.js";
24
25
  const MARKETPLACE = "akm-plugins";
25
26
  const PLUGIN_ID = `akm@${MARKETPLACE}`;
@@ -536,6 +537,25 @@ export function upgradePlugins(opts) {
536
537
  ...(entry.channel && opts.currentChannel ? { channelMismatch: entry.channel !== opts.currentChannel } : {}),
537
538
  }));
538
539
  }
540
+ const SKEW_ADVISORY_HARNESS = {
541
+ "plugin-version": "claude-code",
542
+ "opencode-plugin-version": "opencode",
543
+ "opencode-v2-plugin-version": "opencode-v2",
544
+ };
545
+ /** Adds the `akm health` verdict to a plugin whose bundled akm-cli differs from the CLI, so the upgrade names the skew it leaves. */
546
+ function withEngineSkew(entries, cliVersion) {
547
+ const skew = new Map();
548
+ // Codex records no engine version, so its reader (a `codex plugin list` spawn) is skipped.
549
+ for (const advisory of collectPluginStalenessAdvisories({ cliVersion, probe: false, readCodex: () => undefined })) {
550
+ const harness = SKEW_ADVISORY_HARNESS[advisory.name];
551
+ if (advisory.status === "warn" && harness && !skew.has(harness))
552
+ skew.set(harness, advisory.message);
553
+ }
554
+ return entries.map((entry) => {
555
+ const note = skew.get(entry.harness);
556
+ return note ? { ...entry, message: `${entry.message ? `${entry.message}; ` : ""}engine skew: ${note}` } : entry;
557
+ });
558
+ }
539
559
  /**
540
560
  * Which build of one OpenCode plugin refreshes, and which cache.
541
561
  * Under `--next` that is `<pkg>@next`, but only when the user's OpenCode
@@ -742,7 +762,7 @@ export async function runUpgrade(args, currentVersion, deps) {
742
762
  mode: "check",
743
763
  result: {
744
764
  ...check,
745
- plugins: upgradePlugins({ dryRun: true, next, openCode, channel: switchChannel, currentChannel }),
765
+ plugins: withEngineSkew(upgradePlugins({ dryRun: true, next, openCode, channel: switchChannel, currentChannel }), currentVersion),
746
766
  },
747
767
  };
748
768
  }
@@ -782,14 +802,14 @@ export async function runUpgrade(args, currentVersion, deps) {
782
802
  failed: true,
783
803
  };
784
804
  }
785
- const plugins = upgradePlugins({
805
+ const plugins = withEngineSkew(upgradePlugins({
786
806
  dryRun: false,
787
807
  next,
788
808
  openCode,
789
809
  channel: switchChannel,
790
810
  keep,
791
811
  currentChannel: upgraded.upgraded ? (isPrerelease(upgraded.newVersion) ? "next" : "latest") : currentChannel,
792
- });
812
+ }), upgraded.upgraded ? upgraded.newVersion : currentVersion);
793
813
  const result = {
794
814
  ...upgraded,
795
815
  channel,
@@ -173,13 +173,32 @@ export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
173
173
  // ── skill directory check (SkillLinter.lintDirectory) ────────────────────────
174
174
  /** The akm-native skill placement dir — the default gate for {@link skillDirectoryDiagnostics}. */
175
175
  const AKM_SKILL_DIRS = new Set(["skills"]);
176
+ /** How many directory levels below `skills/` a skill package may sit (`skills/<group>/<name>`). */
177
+ export const MAX_SKILL_GROUP_DEPTH = 3;
178
+ /** True when a skill package (a `SKILL.md`) sits somewhere below `dir`, which is `depth` levels under the type dir. */
179
+ async function hasSkillBelow(dir, depth, ctx) {
180
+ if (depth >= MAX_SKILL_GROUP_DEPTH)
181
+ return false;
182
+ for (const entry of await ctx.list(dir)) {
183
+ if (entry.startsWith("."))
184
+ continue;
185
+ const child = `${dir}/${entry}`;
186
+ if ((await ctx.readFile(`${child}/SKILL.md`)) !== null)
187
+ return true;
188
+ if (await hasSkillBelow(child, depth + 1, ctx))
189
+ return true;
190
+ }
191
+ return false;
192
+ }
176
193
  /**
177
194
  * Reproduce `SkillLinter.lintDirectory` (`skill-linter.ts:31-45`) in the
178
195
  * change-set model: for a change under `<skillDir>/<name>/…`, emit
179
- * `missing-skill-md` when `<skillDir>/<name>/SKILL.md` is absent from the
180
- * overlay. `seen` dedups so a dir with multiple changed files reports once
181
- * (matching the per-subdir call). `file`/`detail` mirror the live check exactly
182
- * (relDir + `no SKILL.md in <relDir>/`).
196
+ * `missing-skill-md` for the skill directory that owns the changed file when
197
+ * it has no `SKILL.md` in the overlay. A directory with skill packages below
198
+ * it is a grouping directory, not a skill: the check moves to the child that
199
+ * owns the file. `seen` dedups per reported directory (matching the per-subdir
200
+ * call). `file`/`detail` mirror the live check exactly (relDir + `no SKILL.md
201
+ * in <relDir>/`).
183
202
  *
184
203
  * `skillDirs` defaults to the akm-native `skills/` placement dir. Tool-dir
185
204
  * adapters pass their own canonical placement directory.
@@ -191,14 +210,18 @@ export async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs =
191
210
  .filter((s) => s.length > 0);
192
211
  if (segments.length < 3 || !skillDirs.has(segments[0]))
193
212
  return []; // must be <skillDir>/<name>/<file…>
194
- const skillDir = `${segments[0]}/${segments[1]}`;
195
- if (seen.has(skillDir))
196
- return [];
197
- seen.add(skillDir);
198
- const skillMd = await ctx.readFile(`${skillDir}/SKILL.md`);
199
- if (skillMd !== null)
200
- return [];
201
- return [{ file: skillDir, issue: "missing-skill-md", detail: `no SKILL.md in ${skillDir}/`, fixed: false }];
213
+ for (let depth = 2; depth < segments.length; depth++) {
214
+ const dir = segments.slice(0, depth).join("/");
215
+ if ((await ctx.readFile(`${dir}/SKILL.md`)) !== null)
216
+ return [];
217
+ if (await hasSkillBelow(dir, depth - 1, ctx))
218
+ continue; // grouping directory
219
+ if (seen.has(dir))
220
+ return [];
221
+ seen.add(dir);
222
+ return [{ file: dir, issue: "missing-skill-md", detail: `no SKILL.md in ${dir}/`, fixed: false }];
223
+ }
224
+ return [];
202
225
  }
203
226
  /**
204
227
  * The winning `type`'s per-type EXTRA validate checks (base checks run