akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -0,0 +1,150 @@
+# Migrating from akm 0.9.1 to 0.9.2
+
+AKM 0.9.2 makes task v3 the only executable task source and introduces peer
+Markdown and GitHub-shaped YAML workflow sources. Authored task-v2 files
+require an explicit, fail-closed migration. Durable workflow plans created by
+0.9.1 are pre-v4 and cannot resume in 0.9.2; restart those runs from the current
+authored workflow source so AKM can freeze a new v4 plan.
+
+The released 0.9.1 state ledger already includes historical migration 018, so
+the normal 0.9.1→0.9.2 database step is additive and automatic. If a pre-release
+database has an exact prefix before 018, ordinary commands stop before its
+destructive dead-lane cleanup. Run `akm upgrade --force`; after successful
+executable replacement AKM creates and verifies a sibling pre-018 SQLite safety
+copy before applying that immutable released migration. Its locked ledger
+recheck, snapshot, and migration share one writer-exclusion window, so another
+WAL writer cannot commit between the copy and 018. Unknown or divergent ledgers
+remain unsupported.
+
+## Before: 0.9.1 task v2
+
+A 0.9.1 inline prompt task could look like this:
+
+```yaml
+version: 2
+name: Contract review
+schedule: "15 4 * * 1"
+prompt: Review the execution contract.
+enabled: false
+engine: reviewer
+model: exact-model-id
+timeoutMs: 45000
+redact: [REVIEW_TOKEN]
+```
+
+Normal 0.9.2 execution rejects v2. It never guesses how to execute an old
+target or rewrites a task as a side effect of `run`, `sync`, or `doctor`.
+
+## After: 0.9.2 task v3
+
+After migration, the 0.9.2 task v3 result uses the built-in command action and moves
+AKM-specific scheduling and resolver controls under `akm`:
+
+```yaml
+version: 3
+name: Contract review
+uses: akm/command
+with:
+  content: Review the execution contract.
+akm:
+  schedule: "15 4 * * 1"
+  enabled: false
+  engine: reviewer
+  model: exact-model-id
+  timeout: 45000
+  redact: [REVIEW_TOKEN]
+```
+
+Workflow refs become `uses: workflows/<name>` with the old `params` mapping
+preserved as `with`. Deterministic command strings become `run`. Command refs
+become `uses: commands/<name>`.
+
+## Safe migration procedure: preview, then apply
+
+1. Commit or otherwise snapshot your authored bundles.
+2. Preview the pure migration plan. This performs no source write:
+
+   ```sh
+   akm migrate apply --dry-run
+   ```
+
+3. Review every input file. The report is stable and names an exact status for
+   each file: `changed`, `skipped`, or `blocked`.
+4. Resolve every blocked file manually, then preview again.
+5. Apply the same planner:
+
+   ```sh
+   akm migrate apply
+   ```
+
+For each `changed` file, AKM validates the complete v3 bytes before replacement.
+At apply time it rechecks the planned generation,
+backs up that file immediately before replacement, preserves its file mode,
+and then installs the validated replacement. A race or validation failure
+stops instead of applying stale output.
+
+Exact translations preserve the schedule. They preserve enabled state and params.
+They preserve timeout and redaction names. They preserve resolver overrides
+(engine, model, inference, tools, and agent where admitted). Empty
+collections, explicit false/zero, and meaningful null values remain distinct
+when the v3 contract supports them.
+
+## Blocked files and manual review
+
+The migrator blocks any case whose execution meaning is not provably portable.
+In particular, a v2 argv array has no unambiguous v3 shell-string equivalent:
+
+```yaml
+version: 2
+schedule: "@daily"
+command: [node, scripts/release.js, "--exact value"]
+```
+
+Shell-sensitive strings—assignments, shell builtins, reserved words, and
+similar constructs—are also blocked when translating them would invent shell
+semantics. The original bytes remain untouched. Author a v3 `run` string or a
+script/command asset deliberately, validate it, and rerun the preview.
+
+## Workflow cutover
+
+Markdown `.md` and GitHub-shaped `.yml` are peer workflow source formats in
+0.9.2 and compile to source IR version 1. New workflow starts freeze durable
+plan IR v4, the sole executable plan format. Pre-v4 stored plans are rejected;
+start a new run from current source. A v4 resume does not re-read authored
+workflow/command/agent source, configuration, model maps, or the asset index.
+
+The `inherit_env` removal is breaking because every new v4 start rejects it.
+Use named environment bindings and `pass_env` as the bounded replacement for fixed, secret, and per-machine values.
+There is no compatibility reader for the historical flag or pre-v4 plans.
+
+The GitHub-shaped source format is intentionally local and bounded. It accepts
+schedule and empty `workflow_dispatch` triggers, `runs-on: [self-hosted]`, and
+the documented local step subset. Full expressions, contexts, remote/local or
+Docker actions, nested workflows, service-event automation, and arbitrary
+runners remain unsupported.
+
+## Improve triage judgment
+
+`improve.strategies.<name>.processes.triage.judgment` now accepts an explicit
+boolean or object. Set `judgment: false` to disable the judgment pass without
+requiring an engine or credentials. Object form defaults to enabled for newly
+authored configuration and rejects unknown object keys. The standalone
+`akm proposal ... --judgment` option remains an explicit invocation override;
+it does not silently rewrite the configured strategy.
+
+## Validate the upgrade
+
+After migration:
+
+```sh
+akm index
+akm task sync
+akm task doctor
+akm health
+```
+
+Review scheduler changes before activation. Use `akm task sync --rebind` only
+when the installed runtime path intentionally changed.
+
+See [Tasks](../reference/tasks.md), [Workflow schema](../reference/workflow-schema.md),
+and the [0.9.2 terminal migration note](release-notes/0.9.2.md).

package/docs/reference/README.md

@@ -6,6 +6,7 @@ Authoritative reference documentation for the akm CLI and its data.
 - [CLI](cli.md) -- All `akm` commands and flags
 - [Configuration](configuration.md) -- Engines, strategies, bundles, and settings
 - [Supported Formats](supported-formats.md) -- Formats akm can index, from its own bundle layout to other tools' existing asset directories
+- [Tasks](tasks.md) -- Strict task-v3 source grammar, executable targets, triggers, migration, and scheduler operations
 - [Workflow Schema](workflow-schema.md) -- Authoritative reference for a workflow asset's exact frontmatter and body syntax
 - [Workflows](workflows.md) -- Map of the workflow documentation: running, authoring, the schema, and the engine
 - [Memory](https://github.com/itlackey/akm/blob/main/docs/reference/memory.md) -- The `memory` asset type: capture, belief states, and derived memories