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

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -57,7 +57,9 @@ pace: an unmigrated v2/v3 task source keeps reading and running through the
 in-memory read shim, with a one-line deprecation warning, until you migrate
 it (nothing silently breaks or half-runs, and only a genuinely unmigratable
 shape fails closed with an actionable hint), and pre-`irVersion`-5 runs stay
-inspectable indefinitely.
+inspectable indefinitely. (0.9.17-alpha.7 removed that shim: a v2/v3 task
+source now fails on its own, naming `akm migrate apply`, which `akm upgrade`
+runs after an install.)
 
 ## Task sources
 
@@ -72,7 +74,9 @@ apply` remains the way to rewrite the file on disk and silence the warning.
 current grammar — extended the same kind of shim to a `version: 4` document
 whose `schedule[]` still carries a per-entry `enabled` key, retired from
 task source v4's own grammar since; the field is stripped without being
-read, never re-added.)
+read, never re-added. 0.9.17-alpha.7 removed both shims: akm now reads only
+task source v4, and each older file fails on its own, naming
+`akm migrate apply`.)
 
 **Before — 0.9.1 task v2:**
 
@@ -679,7 +683,7 @@ phase-specific code:
 | Code | Domain |
 |---|---|
 | `TASK_SOURCE_INVALID` | A task document's field- or semantic-level validation failure, or a malformed/oversized/too-deep YAML front end failure. |
-| `TASK_SCHEMA_VERSION_UNSUPPORTED` | A task document's `version:` is `3` or `2` and the in-memory read shim's deterministic conversion cannot resolve it — a human decision is needed (see [Task sources](#task-sources)); a convertible v2/v3 document reads through the shim instead of failing. |
+| `TASK_SCHEMA_VERSION_UNSUPPORTED` | A task document's `version:` is `3` or `2` and the in-memory read shim's deterministic conversion cannot resolve it — a human decision is needed (see [Task sources](#task-sources)); a convertible v2/v3 document reads through the shim instead of failing. From 0.9.17-alpha.7, every v2/v3 document fails this way, naming `akm migrate apply`. |
 | `TARGET_REF_INVALID` | A value is not a canonical `commands/`, `scripts/`, `tasks/`, or `workflows/` asset ref (malformed shapes, GitHub locators, other asset families). |
 | `WORKFLOW_SOURCE_INVALID` | A workflow-source compile failure other than the one below. |
 | `COMPOSITION_INVALID` | A composition-policy rejection: a rejected `with:`, a multi-job document, a composition cycle/depth/size violation. |

package/docs/reference/cli.md

@@ -104,7 +104,7 @@ with an `INVALID_SHAPE_VALUE` usage error (exit 2) — an honest rejection rathe
 than a silent fallback. It returns a compact view suitable for capability
 discovery:
 
-- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `related`
+- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `related`, `links`
 
 ## Exit Codes and Error Envelope
 
@@ -331,7 +331,7 @@ Returns a JSON object with:
 | `semanticSearch` | Semantic search status: `mode`, `status`, and optional `reason`/`message` |
 | `registries` | Configured registries |
 | `sourceProviders` | Configured sources (filesystem, git, website, npm) |
-| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `lastBuiltAt`, `hasEmbeddings` |
+| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `links` (declared links per kind with `total` and `unresolved`; absent when the index holds none), `lastBuiltAt`, `hasEmbeddings` |
 
 `semanticSearch.status` values:
 - `"ready-js"` — every entry has a vector; semantic search is active (the name is historical: `"ready-vec"`, the sqlite-vec variant, is gone)
@@ -436,7 +436,8 @@ The indexed entity graph (entities/relations extracted from bundle assets) has
 no dedicated inspection command; its summary counts surface as an info-level
 metric in `akm health`. Graph data is automatically re-extracted on the first
 `akm improve` cycle after a `DB_VERSION` upgrade. The graph backs `akm show`'s
-`related` list and curate's support refs; it does not affect search ranking.
+`related` list; it does not affect search ranking. Curate's support refs come
+from declared links (`akm show`'s `links`), not from this graph.
 
 ### search
 
@@ -595,10 +596,13 @@ akm curate "learn the release workflow" --from all --format text
 | `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 
 `akm curate` takes the top `--limit` hits of one search, in search order, and
-enriches each with a preview, run details and up to two graph-related support
-refs. With `search.curateRerank.enabled`, a cross-encoder first reorders the
-top 30 fused candidates (`search.curateRerank.topN`) by name, description and
-the start of each asset's indexed content. Curate includes direct follow-up
+enriches each with a preview, run details and up to two support refs: the
+assets the hit's declared links name (`xrefs:`, `supersededBy:` and the other
+kinds `akm show` lists under `links`), what it links to before what links to
+it, skipping assets curate already selected. With
+`search.curateRerank.enabled`, a cross-encoder first reorders the top 30 fused
+candidates (`search.curateRerank.topN`) by name, description and the start of
+each asset's indexed content. Curate includes direct follow-up
 commands such as `akm show <ref>` or `akm bundle add <ref>` so you can
 immediately inspect or install what it found.
 `--detail` and `--shape agent` both work on curate output; `--shape summary`
@@ -691,6 +695,17 @@ returns a compact view with `type`, `name`, `ref`, `description`, `tags`,
 `parameters`, `workflowTitle`, `action`, `run`, `origin`, and `keys`, plus the
 optional fragment metadata described below.
 
+`links` lists the asset's declared links, grouped by kind: `outgoing` (the
+assets its own `xrefs:`, `supersededBy:`, `contradictedBy:`,
+`currentBeliefRefs:`, wiki `sources:`, `.derived` parent, page links, or
+workflow and task targets name), `incoming` (the assets that name it), and
+`unresolved` (tokens it names that match no indexed asset, as written). Each
+kind is `{ "total": n, "refs": [...] }` with at most 10 refs; `total` counts
+them all. The field is omitted when nothing links either way. Links are read
+from frontmatter and parsed structure at index time, with no model; they do
+not affect search ranking. `related` is separate: the LLM entity graph's
+shared-entity neighbours.
+
 Opaque fragment shows and `--context lead` keep `ref` as the canonical parent
 identity and add
 `selectedRef`, `parentRef`, one-based `fragmentOrdinal`, `fragmentCount`,
@@ -2980,9 +2995,10 @@ crontab whose akm markers are malformed is refused unmodified, and another
 akm process holding the scheduler lock makes sync exit 75 (retry shortly).
 
 `akm task prune` reclaims installed scheduler entries that `sync` can never
-clean up on its own: entries whose own `--scheduler-context` descriptor no
-longer resolves to a live bundle (a corrupt/missing descriptor, or the
-bundle directory it pointed at is gone). It never touches an entry that
+clean up on its own: entries that no longer resolve to a live bundle (a row
+whose `AKM_BUNDLE_DIR` names a directory that is gone, or a row written
+before 0.9.17-alpha.7 whose `--scheduler-context` descriptor cannot be
+read). It never touches an entry that
 still resolves to a live bundle — that's `sync`'s job. Like `sync
 --dry-run`, the default is a dry-run preview (zero scheduler writes) that
 exits non-zero when there are candidates to remove; `--yes` executes the

package/docs/reference/tasks.md

@@ -5,27 +5,22 @@ Task assets are strict, local automation sources. They live at
 launchd, or Windows Task Scheduler with `akm task sync`. The task file is
 authored source; scheduler entries are derived OS state.
 
-**Task source v4 (`version: 4`) is the current task source grammar.** A
-document with `version: 3` or `version: 2` still reads and runs: an
-in-memory shim converts it to v4 on the same bytes `akm migrate apply`
-would produce, prints a one-line stderr deprecation warning (once per file
-per process), and never writes anything to disk. Only a v2/v3 document the
-deterministic conversion itself cannot resolve (an ambiguous shell command,
-say) fails to load, with `UsageError` code `TASK_SCHEMA_VERSION_UNSUPPORTED`
-naming the specific blocked reason and the human decision it needs. A
-declared `version: 4` document whose `schedule[]` still carries a
-per-entry `enabled` key — 0.9.15's v4 grammar accepted it, this release's
-does not — reads through the same kind of in-memory shim: the key is
-stripped without ever being read (activation is host-local, below) and the
-same one-line deprecation warning is printed. Task source v4 adds typed
-`inputs:` and a single bounded `output:` schema (command targets only), and
-makes scheduling OPTIONAL rather than mandatory. `akm task add` authors
-task source v4 directly.
+**Task source v4 (`version: 4`) is the only task source grammar akm reads.**
+A document with `version: 3` or `version: 2` fails to load with `UsageError`
+code `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming `akm migrate apply`, which
+converts it. A declared `version: 4` document whose `schedule[]` still
+carries a per-entry `enabled` key — 0.9.15's v4 grammar accepted it, this
+release's does not — fails the same way with `TASK_SOURCE_INVALID`
+(activation is host-local, below). Each such file fails on its own:
+`akm task sync` reports it and keeps reconciling every other task. Task
+source v4 adds typed `inputs:` and a single bounded `output:` schema
+(command targets only), and makes scheduling OPTIONAL rather than
+mandatory. `akm task add` authors task source v4 directly.
 
 If you have `version: 3` or `version: 2` files on disk (from an earlier
 akm release), see [Migrating to task source v4](#migrating-to-task-source-v4)
 below — `akm migrate apply` converts both generations in one pass and
-rewrites the file on disk, silencing the read-time deprecation warning. The
+rewrites the file on disk (`akm upgrade` runs it after an install). The
 retired v3 grammar itself is documented at the bottom of this page
 ([Task v3 (retired): grammar reference for migration](#task-v3-retired-grammar-reference-for-migration))
 purely so you can read an old file while migrating it; it is no longer
@@ -38,10 +33,9 @@ indexed, scheduled, or run. Every task should declare `version: 4`; a
 document with no `version:` key, or a `version:` that is not a number,
 fails with `TASK_SOURCE_INVALID` (`must be exactly 4.` / `is required and
 must be exactly 4.`) — a genuinely malformed v4 document, not a legacy one.
-`version: 3` and `version: 2` read via the in-memory deprecation shim
-described above and, only when the deterministic conversion itself cannot
-resolve the document, fail with `TASK_SCHEMA_VERSION_UNSUPPORTED` instead
-(see [Migrating to task source v4](#migrating-to-task-source-v4)).
+`version: 3` and `version: 2` fail with `TASK_SCHEMA_VERSION_UNSUPPORTED`
+naming `akm migrate apply` (see
+[Migrating to task source v4](#migrating-to-task-source-v4)).
 The published [task schema](../../schemas/akm-task.json) describes the
 hand-authored contract; `src/tasks/source/task-source-v4.ts` is the
 authoritative bounded parser.
@@ -414,17 +408,14 @@ for full before/after examples and recovery guidance.
   anything — see [`akm task explain`](#akm-task-explain) above.
 - `akm task validate <path>` parses one task file by filesystem path (the
   file need not live in a configured bundle) and reports the same
-  `valid`/`converts`/`blocked`/`invalid`/`not-a-task` diagnostic
+  `valid`/`blocked`/`invalid`/`not-a-task` diagnostic
   `akm task sync` would produce for it — including sync's own cron-dialect
   check and its per-schedule-entry input-contract check — without touching
   the scheduler and without requiring a configured engine, even for a
   command-kind task. The envelope's own `sourceVersion` field names the
-  file's declared schema version. A version 2/3 file the in-memory shim
-  converts reports `converts` (exit 0); one the shim's deterministic
-  planner cannot resolve reports `blocked` (exit 1) naming the human
-  decision it needs. A `version: 4` file whose only defect is a retired
-  `schedule[].enabled` also reports `converts` (`sourceVersion` still `4`)
-  — it read through the shim too, not the direct v4 path.
+  file's declared schema version. A version 2/3 file, and a `version: 4`
+  file still carrying a retired `schedule[].enabled`, report `blocked`
+  (exit 1) naming `akm migrate apply`, which converts them.
 - `akm task add` validates a task source v4 document, writes it, adds its ref
   to local scheduler activation, and syncs its bundle. `--params` renders
   typed `inputs:` declarations instead of a `with:` bag; `--schedule` is
@@ -443,8 +434,8 @@ for full before/after examples and recovery guidance.
   A row that fails to install or remove is reported in `failures` and every
   other row still applies. A source that fails to parse is reported the same
   way, and its installed row is left exactly as it is. Rows akm cannot attribute to a bundle this sync covers —
-  another bundle's, another installation's (the row's own descriptor names a
-  different bundle path), or anything outside akm's `# akm:task` markers,
+  another bundle's, another installation's (the row's `AKM_BUNDLE_DIR`
+  names a different working stash), or anything outside akm's `# akm:task` markers,
   `com.akm.task.` labels, or `\akm\` task folder — are never touched. A
   Task Scheduler row is compared by the fingerprint akm writes into its
   `<Source>` plus its enabled state, so an edit made in Task Scheduler that
@@ -457,9 +448,10 @@ for full before/after examples and recovery guidance.
   removals annotated with their owning bundle) without writing to the
   scheduler; exits non-zero when removals are pending.
 - `akm task prune` removes installed scheduler entries `sync` cannot reach
-  because their own descriptor no longer resolves to a live bundle
-  (corrupt/missing `--scheduler-context`, or the owning bundle directory is
-  gone). It never touches an entry that still resolves to a live bundle.
+  because they no longer resolve to a live bundle: a row whose
+  `AKM_BUNDLE_DIR` names a directory that is gone, or a row written before
+  0.9.17-alpha.7 whose `--scheduler-context` descriptor cannot be read. It
+  never touches an entry that still resolves to a live bundle.
   Defaults to a dry-run preview (zero writes); `--yes` executes it; `--id
   <id1,id2,...>` scopes to specific ids and refuses any id that isn't a
   current orphan candidate.
@@ -473,13 +465,39 @@ for full before/after examples and recovery guidance.
   section directly above the first akm task block in the crontab (on macOS,
   an `EnvironmentVariables` entry in each plist). It is the PATH of the shell
   that ran the sync, rewritten on every crontab write and removed with the
-  last akm block; cron applies it to every row below it. The
-  `--scheduler-context` descriptor a row references holds directories only:
-  the bundle path, plus any `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR`
-  or `AKM_STATE_DIR` that shell had set explicitly. Defaults resolve at fire
-  time, so a scheduled run uses the same state, data and cache directories an
-  interactive command does. Run the sync from a shell whose environment you
-  would want scheduled.
+  last akm block; cron applies it to every row below it.
+- A task's row is its command plus its schedule:
+  `<launcher> task run <id> --bundle <bundle> --scheduled`, and it sets its
+  own environment. Every row sets `AKM_BUNDLE_DIR` to the working stash of
+  the shell that ran the sync (its `AKM_BUNDLE_DIR`, or the default bundle),
+  so the scheduled run uses the same working stash, `--bundle` finds a stash
+  no config names, and sync tells rows of other installations sharing the
+  scheduler apart (#846). Rows synced from a shell that set
+  `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` or `AKM_STATE_DIR`
+  explicitly set those too. Each backend does it its own way: a
+  `VAR=value` prefix in the crontab, an `EnvironmentVariables` entry in the
+  plist, a `$env:VAR='value';` assignment ahead of the command in Task
+  Scheduler. Other defaults resolve at fire time, so a scheduled run uses
+  the same state, data and cache directories an interactive command does.
+  Run the sync from a shell whose environment you would want scheduled.
+
+  ```text
+  15 2 * * * AKM_BUNDLE_DIR=/home/u/akm /home/u/.bun/bin/bun /home/u/.bun/lib/node_modules/akm-cli/dist/akm task run nightly --bundle work --scheduled > /home/u/.cache/akm/tasks/logs/nightly.log 2>&1
+  ```
+
+  A row whose command is over 1,000 bytes runs a wrapper script under the
+  log directory instead (`sh <log dir>/.akm-cron-wrapper-<id>-<hash>.sh`);
+  sync reads the script to tell which task the row runs.
+
+  Releases 0.9.0 through 0.9.17-alpha.6 wrote a `--scheduler-context
+  <file>` argument into each row instead, naming a descriptor file under
+  `$DATA/tasks/context/` that held the same values. akm still applies that
+  file when such a row fires, and the first `akm task sync` after upgrading
+  rewrites each row in place: it shows as an update, keeps the row's
+  launcher and schedule, and sets the values inline. A row the sync leaves as it is (its task file failed to load, or
+  a `--bundle` sync did not cover it) still names its file; once
+  `akm task doctor` lists no binding with a `contextPath`, the old descriptor
+  files are not read and can be deleted.
 
 Scheduler execution is at least once. Backends provide a stable invocation
 identity and AKM fences stale attempts, but an ambiguous process crash can be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.17-alpha.6",
+  "version": "0.9.17-alpha.8",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [