akm-cli 0.9.30 → 0.10.261001-beta

package/docs/plans/0.9.2-agent-command-workflow-plan.md

@@ -0,0 +1,423 @@
+# 0.9.2 Agent, Command, Task, Workflow, and Model Resolution Plan
+
+> **Historical implementation plan.** WP0-WP8 are implementation-complete for
+> the 0.9.2 release cut. Current public contracts live in
+> [Tasks](../reference/tasks.md) and
+> [Workflow Schema](../reference/workflow-schema.md). The sequencing and staged
+> checkpoint text below is preserved as historical evidence, not current
+> product status.
+
+**Status:** In progress; WP5 runtime lowering convergence is implemented, with
+WP6 task v3 and WP7 durable workflow IR work still outstanding
+
+**Decision date:** 2026-08-18
+
+**Target branch:** `release/0.9.2`
+
+**GitHub tracker:** [#801](https://github.com/itlackey/akm/issues/801)
+
+**Normative design:**
+[Agent, Command, Engine, and Model Resolution](../architecture/specs/agent-command-engine-model-design.md)
+
+**Implementation checkpoint (2026-08-19):** The reviewed WP5/#809 integration
+uses the active WP2/WP3 model-map and common-cascade resolver before runtime
+lowering. Canonical command and non-interactive agent dispatch, the existing
+task-v2 prompt arm, improve/proposal model-work adapters, current frozen
+workflow unit and judge dispatch, index passes, and the shared structured-LLM
+seam now enter the common resolved-request/lowerer path. This is runtime
+lowering convergence, not completion of the task-v3 source format (WP6) or the
+WP7 source-to-frozen durable workflow IR and resume-persistence design. Current
+workflow lowering notices are live diagnostics, not journaled result/evidence
+data. Full GitHub Actions execution remains out of scope.
+
+## 1. Outcome
+
+AKM 0.9.2 delivers one coherent execution model for direct command runs,
+scheduled tasks, and frozen workflows. The same source assets and configuration
+must resolve to the same command content, persona, engine, model, tools, and
+ordinary runtime settings regardless of entry point.
+
+The release also establishes GitHub-compatible task and workflow seams without
+claiming full GitHub Actions execution. Existing AKM Markdown workflows remain
+first-class. Native Claude and OpenCode files remain authoritative and are
+translated at runtime; AKM does not synchronize or write them.
+
+## 2. Definition of done
+
+0.9.2 is complete only when all of the following are true:
+
+1. `akm command run` is the only stored-command execution surface.
+2. Direct command runs, task runs, and workflow freeze call one resolver and
+   produce equivalent resolved requests for equivalent inputs.
+3. Commands and agents are read through their bundle adapters. Raw native file
+   bytes and frontmatter are never accidentally dispatched as user prompt
+   content.
+4. All registered agent harness profiles and direct LLM engines consume the
+   same resolved/lowered request contract.
+5. Task v3 uses the approved GitHub-step-compatible shape. V2 is rejected by
+   normal execution and handled by an explicit fail-closed migrator.
+6. AKM Markdown workflows and GitHub-shaped YAML compile into the same
+   versioned internal IR and freeze the same dispatch-significant state.
+7. Installed and user `models.json` layers resolve aliases deterministically,
+   with user values overlaying installed defaults by alias and field.
+8. Unsupported native template syntax, GitHub triggers, and adapter constructs
+   fail or emit notices according to the normative design; nothing is silently
+   ignored, guessed, synchronized, or partially expanded.
+9. Contract, unit, integration, migration, and release checks pass.
+
+## 3. Decisions fixed for this milestone
+
+| Area | 0.9.2 ruling |
+| --- | --- |
+| Scope | Full coherent MVP across direct invocation, tasks, and workflow freeze/resume |
+| Agents | Personas selected by `agent`; never executable `uses` targets |
+| Commands | Reusable prompt templates; inline prompt text is anonymous command content, not another executable type |
+| Native files | AKM-native, Claude, and OpenCode formats only; read and translated at runtime, never synchronized or written |
+| Engines | Every currently registered profile plus direct LLM engines uses the unified resolver/lowering boundary |
+| Cascade | Installation -> engine -> agent -> command -> task/workflow defaults -> current task/step/CLI; nearest explicit value wins |
+| Tools | Selected by the ordinary cascade, then checked separately against operator authorization |
+| Arguments | One exact-string, one-pass `$ARGUMENTS` substitution; unsupported native syntax fails before dispatch |
+| Sessions | Fresh one-shot execution; explicit resume remains deferred |
+| Models | Installed default `models.json` plus field-wise user overlay in the AKM config directory |
+| Task format | Breaking v3; GitHub-step-shaped `uses`/`run`; AKM-only fields namespaced under `akm` |
+| Shell | `run` is a shell string with compatible `shell` and `working-directory` controls |
+| Workflow formats | AKM Markdown remains supported indefinitely; GitHub-shaped YAML is a peer format |
+| Internal workflow form | Internal, versioned, GitHub-shaped IR with AKM freeze/journal data and adapter-owned extensions |
+| Local triggers | `schedule` -> OS scheduler; `workflow_dispatch` -> manual; unsupported service events fail explicitly |
+| GitHub direction | Consumption-first; no file generation or synchronization |
+| Future GitHub bridge | One package with typed `/command`, `/workflow`, and `/task` actions; no separate `/prompt` action |
+
+## 4. Architecture and data flow
+
+Every entry point must converge before engine dispatch:
+
+```text
+source adapter
+  -> typed agent/command/task/workflow source
+  -> invocation adapter
+  -> common cascade resolver
+  -> model alias expansion
+  -> authorization check
+  -> versioned resolved request / workflow IR
+  -> engine-specific optimistic lowering
+  -> harness, LLM provider, shell, or workflow scheduler
+```
+
+For direct commands and scheduled tasks, resolution occurs when execution
+starts. For workflows, the same resolver runs during plan creation and the
+complete resolved result is frozen. Resume consumes the frozen representation;
+it does not re-read current assets or config.
+
+No entry point may independently rebuild command arguments, choose a model,
+interpret tools, or construct agent prompts after this convergence point.
+
+## 5. Implementation work packages
+
+### WP0 - Characterization and contract fixtures
+
+Before changing behavior:
+
+- capture current direct-agent, command, task, workflow-freeze, model-alias,
+  and harness-lowering behavior;
+- add representative AKM, Claude, and OpenCode command/agent fixtures;
+- add task-v2 fixtures for every deterministic migration case and each
+  deliberately blocked case;
+- add equivalent Markdown and GitHub-shaped YAML workflow fixtures; and
+- define a normalized resolved-request projection used only by tests to prove
+  cross-entry-point equivalence.
+
+This package prevents cleanup from accidentally enshrining a 0.9.1 seam as
+the new contract.
+
+### WP1 - Shared source and resolved-execution types
+
+Introduce one internal source representation for:
+
+- adapter-rendered command content and metadata;
+- resolved persona content and metadata;
+- exact source ref, bundle, adapter, file identity, and content hash;
+- command argument input before and after substitution; and
+- ordinary unresolved execution defaults.
+
+Introduce one resolved request containing the dispatch-significant result:
+
+- final persona and command content;
+- selected engine and exact or aliased model input;
+- resolved inference settings;
+- selected tools and authorization result;
+- timeout, workspace, environment, and other shared runtime settings;
+- source identities/hashes; and
+- structured lowering notices.
+
+The type must not embed a static engine capability matrix. Unsupported-field
+handling belongs to lowering adapters.
+
+### WP2 - Model map files and alias expansion
+
+- Ship an immutable default `models.json` as a package/build asset.
+- Read an optional `models.json` from the normal AKM config directory.
+- Validate both files with one versioned schema.
+- Overlay user values over installed values by alias and nested field.
+- Keep engine-specific config overrides nearer than both files.
+- Support simple exact-model strings and structured inference profiles.
+- Recognize only aliases present in the merged registry. Pass unknown values
+  through as exact model identifiers; fail when a known alias lacks a mapping
+  for the selected engine.
+- Provide an explicit CLI operation to copy installed defaults into the user
+  config directory. It must not overwrite an existing user file without an
+  explicit confirmation flag.
+- Include the installed file in npm, standalone binary, Bun/Node, and Docker
+  packaging tests.
+
+Do not store authoritative defaults in the cache and do not add reusable
+mapping-pack installation in 0.9.2.
+
+### WP3 - Common cascade resolver and authorization boundary
+
+- Implement the far-to-near cascade once.
+- Preserve omitted versus explicit values, including explicit `false`, `0`,
+  empty allowed collections, and `null` where the schema assigns meaning.
+- Expand a structured model alias as defaults at the layer that selected it,
+  then apply explicit sibling and nearer fields.
+- Resolve tool selection using nearest-explicit-wins.
+- Perform machine/user authorization after selection and before dispatch.
+- Return an explicit policy failure rather than silently adding or removing
+  tools.
+- Produce stable, machine-readable provenance for each resolved field so
+  `--verbose`, dry-run, health, and tests can explain why a value won.
+
+### WP4 - Command execution surface
+
+- Add canonical `akm command run <ref>` dispatch.
+- Keep stored-command execution out of `akm agent`; do not add a compatibility
+  alias beside the canonical command surface.
+- Load commands and selected agents through bundle adapters.
+- Implement only one-pass `$ARGUMENTS` replacement.
+- Detect unsupported native template constructs before engine dispatch.
+- Support a built-in command action for anonymous inline command content.
+- Require exactly one of `with.ref` and `with.content`; accept
+  `with.arguments` as the exact portable argument string.
+- Preserve a persona on engines without a native system-prompt channel by
+  composing the specified deterministic persona block and emitting a lowering
+  notice.
+
+No code path may fall back to asking a harness to resolve an AKM command name.
+
+### WP5 - Engine lowering convergence
+
+- Route direct agent/command execution, improve/proposal agent execution,
+  tasks, and workflow steps through the resolved-request boundary.
+- Ensure configured model and inference settings reach every harness.
+- Update each registered execution profile to lower the fields it understands
+  and report untranslated fields.
+- Dispatch optimistically after lowering; provider/harness rejection remains a
+  runtime failure.
+- Remove pre-dispatch failures based only on hard-coded guesses about engine
+  capabilities.
+- Keep operator authorization and invalid configuration as hard pre-dispatch
+  failures.
+
+The conformance matrix must cover OpenCode, OpenCode SDK, Claude, Codex,
+Gemini, Aider, Copilot, Pi, Amazon Q, OpenHands, and direct LLM connections
+without adding native file-format adapters for those extra harnesses.
+
+**Implemented checkpoint (2026-08-19):** Engine lowering is an implementation
+registry derived from the harness registry, plus a direct-LLM lowerer; it is
+not a model/provider capability table. The common cascade resolves model-map
+aliases to exact model IDs and inference before lowering. Lowerers consume
+that exact selection, report translated and untranslated paths with stable,
+secret-free structured notices, and dispatch optimistically. Symbolic LLM and
+SDK-fallback credentials remain symbolic until the final runner dispatch.
+Already-frozen runner material uses the config-free lowering entry point, so
+it does not re-read config, aliases, environment variables, or credentials.
+The current task-v2 and workflow-engine adapters exercise this runtime seam;
+their WP6/WP7 replacement schemas and durable freeze/resume representation are
+not claimed by WP5.
+
+### WP6 - Task v3, adapters, migration, and scheduling
+
+Define and publish a strict v3 schema with:
+
+- exactly one executable `uses` or `run` selection;
+- GitHub-compatible `name`, `with`, `env`, `shell`, and
+  `working-directory` fields where applicable;
+- AKM-only scheduling and resolver overrides under `akm` for step-shaped
+  tasks; and
+- deterministic recognition of AKM refs versus GitHub action refs.
+
+Add adapters for:
+
+1. step plus `akm.schedule`;
+2. step plus GitHub-style `on`; and
+3. complete `on` plus `jobs` documents.
+
+A complete `on` plus `jobs` document becomes one workflow asset with an
+internal scheduler binding. It must not create a duplicate public task ref.
+
+The scheduler adapter supports time schedules and manual dispatch. It rejects
+locally unsupported GitHub service-event triggers with source-located
+diagnostics and never installs a watcher or polling daemon.
+
+The v2 migrator must:
+
+- offer a no-write preview using the same planner as execution;
+- back up each file immediately before replacement;
+- map v2 prompt content to anonymous command content;
+- map workflow refs and deterministic command strings to the v3 target;
+- stop on argv arrays or other shell-ambiguous constructs;
+- preserve schedules, enabled state, params, timeouts, redaction metadata, and
+  resolver overrides when their translation is exact;
+- validate the resulting v3 document before replacing the source; and
+- report every changed, skipped, and blocked file.
+
+Normal task execution rejects v2 with a direct migration hint.
+
+### WP7 - Multi-format workflow compile and freeze
+
+- Preserve the current AKM Markdown adapter as a first-class source format.
+- Add the GitHub-shaped YAML adapter for the approved 0.9.2 subset.
+- Compile both through one versioned IR builder.
+- Shape portable nodes around `jobs`, `needs`, `steps`, `uses`, `run`, `with`,
+  and `env` where doing so does not change AKM semantics.
+- Carry adapter-owned extensions explicitly rather than placing opaque native
+  metadata into the common source model.
+- Resolve command, persona, engine, model, tools, and source snapshots before
+  persisting a run plan.
+- Make resume consume only frozen dispatch inputs.
+- Reject unsupported GitHub expressions, contexts, actions, events, or runner
+  behavior explicitly in 0.9.2.
+
+Full GitHub Actions/workflow execution and remote action acquisition are not
+part of this work package.
+
+### WP8 - Documentation, diagnostics, and release gates
+
+- Update CLI, configuration, task, workflow, model, migration, and adapter
+  references.
+- Add a task-v2-to-v3 migration guide with before/after examples and blocked
+  argv-array examples.
+- Document every supported 0.9.2 workflow subset and every explicit 0.9.3
+  boundary.
+- Add `health` checks for unreadable/invalid user `models.json`, missing known
+  alias mappings, and unavailable explicitly selected engines.
+- Ensure dry-run and verbose output show resolved field provenance and lowering
+  notices without exposing secrets.
+- Run `bun run check`, build/package regression suites, and
+  `./tests/release-check.sh` before the release candidate.
+
+## 6. Sequencing and dependencies
+
+```text
+WP0 characterization
+  -> WP1 shared types
+      -> WP2 model maps
+      -> WP3 resolver/authorization
+          -> WP4 command surface
+          -> WP5 engine convergence
+          -> WP6 task v3 and migration
+          -> WP7 workflow compile/freeze
+              -> WP8 release gates
+```
+
+WP2 may proceed alongside the source-type portion of WP1 once its schema
+contract is pinned. WP6 and WP7 may proceed in parallel only after WP3's
+resolved-request contract is stable. Engine-specific work in WP5 can be split
+by harness after the common lowering interface and conformance fixture exist.
+
+## 7. GitHub milestone tracking
+
+The milestone parent is
+[#801](https://github.com/itlackey/akm/issues/801). Closing carryover defects
+does not complete this plan; every work package has its own issue and must link
+its implementation commits and verification evidence.
+
+| Work package | GitHub issue | Dependency role |
+| --- | --- | --- |
+| WP0 | [#803](https://github.com/itlackey/akm/issues/803) | Foundation for every later contract and conformance test |
+| WP1 | [#804](https://github.com/itlackey/akm/issues/804) | Depends on WP0 |
+| WP2 | [#802](https://github.com/itlackey/akm/issues/802) | May start after WP0 and the relevant WP1 schema contract are pinned |
+| WP3 | [#807](https://github.com/itlackey/akm/issues/807) | Depends on WP1 |
+| WP4 | [#806](https://github.com/itlackey/akm/issues/806) | Depends on WP3 and the WP1 source contract |
+| WP5 | [#809](https://github.com/itlackey/akm/issues/809) | Depends on WP3; coordinates with the WP4 invocation path |
+| WP6 | [#808](https://github.com/itlackey/akm/issues/808) | Depends on stable WP3; coordinates with WP4 and gated CI |
+| WP7 | [#805](https://github.com/itlackey/akm/issues/805) | Depends on stable WP3; coordinates with WP4 and WP6 |
+| WP8 | [#810](https://github.com/itlackey/akm/issues/810) | Collects evidence after WP0-WP7 and the release-hardening lanes |
+
+The milestone also contains parallel architecture, security, infrastructure,
+and product-correctness work. These issues do not substitute for a work
+package:
+
+| Issue | Plan relationship | Sequencing and release treatment |
+| --- | --- | --- |
+| [#744](https://github.com/itlackey/akm/issues/744) | Website-provider dependency-edge refactor | Separate architecture lane; land before WP1 if included, but make it a core dependency only when a concrete cycle or blocked adapter seam is demonstrated |
+| [#765](https://github.com/itlackey/akm/issues/765) | Dangerous environment-key audit during bundle update | Security hardening; stage and audit before publication or completely roll back content, lock/config state, and index |
+| [#767](https://github.com/itlackey/akm/issues/767) | Registry SSRF, DNS-rebinding, and redirect protection | Security hardening; inventory the complete registry fetch surface and document the private-registry compatibility policy |
+| [#811](https://github.com/itlackey/akm/issues/811) | Registry credential rejection and output redaction | Split from #767 so secret-handling and network-boundary behavior are independently testable |
+| [#784](https://github.com/itlackey/akm/issues/784) | Gated semantic, Docker, and native-scheduler CI | Foundation for WP6 and WP8; scheduled runs detect drift, while a manual run against the release-candidate SHA supplies release evidence |
+| [#794](https://github.com/itlackey/akm/issues/794) | Proven dead-code and fixture removal | Land as an isolated pre-WP0 cleanup so characterization does not preserve dead surfaces |
+| [#798](https://github.com/itlackey/akm/issues/798) | Transformers dependency advisories | Must use a remediation that affects installed consumers; root-only npm overrides are not a published-user fix; real embedding verification depends on #784 |
+| [#800](https://github.com/itlackey/akm/issues/800) | Effective, side-effect-free `improve --dry-run` planning | Separate improve lane using the same planner-for-preview-and-execution principle; complete before dogfood evidence is collected |
+| [#766](https://github.com/itlackey/akm/issues/766) | Git-backed walker symlink containment | Completed by `5f389979`; closed during milestone triage |
+
+Release readiness requires WP0-WP8 to be complete, the security issues to be
+resolved or covered by an explicit documented release decision, gated suites
+to pass against the release-candidate SHA, and `improve --dry-run` to be
+trustworthy for the dogfood period. Architecture cleanup may remain off the
+critical path only when it does not block those outcomes.
+
+## 8. Required contract tests
+
+At minimum, the suite must prove:
+
+1. Equivalent direct, task, and workflow inputs produce byte-equivalent
+   normalized resolved requests.
+2. Every cascade layer wins only over farther layers, including tools.
+3. Operator tool denial is explicit and independent of bundle provenance.
+4. Native command frontmatter is metadata, not prompt content.
+5. `$ARGUMENTS` expands exactly once and unsupported templates never dispatch.
+6. Installed model defaults, partial user overlays, structured profiles,
+   engine overrides, known-unmapped aliases, and exact unknown identifiers
+   behave as specified.
+7. Every registered engine profile receives the selected exact model and emits
+   notices for intentionally untranslated settings.
+8. All three scheduling source shapes produce the expected scheduler binding;
+   unsupported service triggers produce no registration side effect.
+9. Task migration preview performs no writes and matches the later execution
+   plan; ambiguous cases remain untouched.
+10. Equivalent Markdown and YAML workflows freeze equivalent portable IR.
+11. Resume does not observe subsequent edits to commands, agents, config, or
+    model maps.
+12. Native Claude/OpenCode bundles remain byte-for-byte unchanged throughout
+    indexing and execution.
+
+## 9. Explicitly out of scope
+
+- Portable positional or named command arguments
+- Expressions, loops, or recursive command-template expansion
+- Nested or separately journaled child workflows
+- Explicit native-session reuse
+- New native agent/command formats beyond AKM, Claude, and OpenCode
+- Reusable/distributed model mapping packs
+- Full GitHub expression, context, runner, action, and event semantics
+- Fetching or executing arbitrary remote GitHub actions
+- Publishing the future GitHub Action package
+- Generating, exporting, projecting, or synchronizing native/GitHub files
+
+These may become 0.9.3 work, but 0.9.2 must leave clean adapter and IR seams for
+them without claiming support early.
+
+## 10. Release evidence
+
+The 0.9.2 release PR and parent tracker
+[#801](https://github.com/itlackey/akm/issues/801) must include:
+
+- a work-package checklist linked to implementation commits or issues;
+- schema and migration examples;
+- the cross-entry-point resolver conformance report;
+- the all-engine lowering conformance report;
+- the task migration dry-run and execution parity report;
+- workflow Markdown/YAML IR equivalence evidence;
+- package-content evidence for the installed `models.json`;
+- the full release-check result; and
+- manual dogfood notes from direct commands, at least one scheduled task, and
+  a resumed workflow.

package/docs/posts/README.md

@@ -0,0 +1,30 @@
+# Posts
+
+Source articles for the dev.to publishing pipeline. Historical record --
+posts describe akm as it was at publication time and are not updated when
+the product changes.
+
+## Index
+
+- [What akm Actually Does: A Command-by-Command Tour](akm-command-tour.md)
+- [Belief-Aware Memory: Teaching Your Agent When Not to Write](belief-aware-memory-12.md)
+- [One Schema to Rule Them All: The Config v2 Rewrite](config-v2-lessons-16.md)
+- [The Improvement Loop: How akm Keeps Your Agent Sharp](improve-loop-autonomous-10.md)
+- [Your Agent Has a Memory That Runs While You Sleep](improve-pipeline-debugging-0803.md)
+- [Your AI Agent's Skill List Is Getting Out of Hand](intro-part-01.md)
+- [You Already Have Dozens of Agent Skills. You Just Can't Find Them.](intro-part-02.md)
+- [Your Agent's Memory Shouldn't Disappear When the Session Ends](intro-part-03.md)
+- [Your Agent Doesn't Know What the Community Already Figured Out](intro-part-04.md)
+- [From 30 Minutes to 8: How LLM-Mode Reflect Works](llm-mode-reflect-13.md)
+- [OpenPalm Used to Run a Container for Everything. Now It Runs on AKM.](openpalm-built-on-akm.md)
+- [Your Agent Loads 47 Skills at Startup. It Needs Three.](progressive-disclosure-06.md)
+- [The Proposal Queue Safety Net](proposal-safety-net-15.md)
+- [akm 0.5.0: Wikis, Workflows, Vaults, and a Writable Stash](release-0.5.0.md)
+- [akm 0.6.0: Clean Break to Stash, Quieter CLI, Easier Migration](release-0.6.0.md)
+- [akm 0.7.0: Proposal Queue, Reflection Commands, Lessons, and akm-bench](release-0.7.0.md)
+- [akm 0.8.0: CLI Redesign, Task Assets, and Belief-Aware Memory](release-0.8.0.md)
+- [Stop Copying Skills Between Claude Code, Cursor, and Codex](scattered-skills-05.md)
+- [Task Assets: Agent Workflows That Run While You Sleep](task-assets-persistent-workflows-11.md)
+- [Your Team's Agent Skills Are a Mess. Here's How to Fix It.](team-skills-07.md)
+- [Building Agent Knowledge Bases That Actually Scale](wiki-agent-knowledge-08.md)
+- [Agents That Remember Where They Were](workflows-vaults-09.md)