@kontextmind/kxm 0.7.99 → 0.7.101

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.99",
+      "version": "0.7.101",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -319,6 +319,18 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **A local `kxm workflow add` writes only what the project loader accepts, where it reads
+  it.** Local scope needs a KXM project (`project_not_found` outside one, creating nothing)
+  and writes to the project root's `.kxm/workflows/` from any subdirectory. Before writing,
+  also under `--dry-run`, the project loader checks the project with the new document; if
+  it would not load, the command exits 2 with `workflow_invalid`, lists the issues and
+  writes nothing. A `--file` in the shape written through 0.7.92 is refused, and
+  `--overwrite` repairs a file left in that shape. See
+  `docs/reference/cli-reference.md#kxm-workflow-add`.
+- **`kxm workflow add --pick <global-id>` copies the global definition.** In local scope,
+  picking a global definition wrote the one-step scaffold under its id and reported
+  success. It now writes the global definition's content, with `--description` replacing
+  its description, and the loader check refuses one the project cannot load.
 - **Live `kxm runs drive` can author on an audited writer profile.** A write-repository
   step on pi (`-a`, with extensions, skills, and the session off) or grok
   (`--always-approve`, with subagents and web search off) runs against the checkout.
@@ -363,8 +375,9 @@ All notable user-facing changes are documented here. The project follows [Semant
   or the Claude MCP server send one hop past the inbound request being handled, so a
   chain of agents forwarding to each other stops at `hop_limit_reached`.
 - **Workflow prompts no longer point agents at `.kxm/config`**, a path KXM refuses.
-- **`kxm gate signal` and `kxm workflow wait` inside a KXM project reach the hub for hub
-  runs.** They go to the local Runtime only for a run its store holds.
+- **`kxm gate signal`, `kxm workflow wait` and `kxm role resume` inside a KXM project reach
+  the hub for hub runs.** They go to the local Runtime only for a run its store holds, and
+  the lookup leaves no files behind, so `--dry-run` changes nothing.
 - **`kxm peer inbox` lists the requests waiting for a named CLI agent.** It returned
   `{"messages":[]}` every time. The hub now serves `GET /v1/agents/:id/inbox`
   (agent-authenticated, project-scoped): the caller's queued and delivered requests,

package/docs/contributing/test-matrix.md

@@ -61,6 +61,8 @@ to run one file is in [Develop KXM](development.md#run-one-file-or-one-test).
 | Dispatch context: only committed, pinned memory and hash-verified promoted skills reach an agent; the rest is a `dispatch_context_*` gap | `engine.test.ts` ("dispatch context: agents receive only committed, pinned memory and verified skills; anything else is withheld with a gap and the step still completes") |
 | `kxm run` prints the simulated drive command for the new run | `cli.test.ts` ("kxm run prints the simulated drive command for the created run") |
 | `kxm workflow add --template` writes workflows that validate and plan; an impossible gate outcome is refused | `cli-experience.test.ts` ("workflow add templates validate and plan a run, and a gate outcome the step can never produce is refused") |
+| `kxm workflow add` writes a local workflow only where the loader reads it and only if the project still loads; outside a project it refuses | `role-and-workflow-manager.test.ts` ("workflow add writes only what the project loader accepts, at the project root, and loadKxmProject still loads") |
+| `kxm workflow add --pick <global-id>` copies the global definition into the project, not the scaffold, and the loader check refuses one that does not fit | `role-and-workflow-manager.test.ts` ("workflow add --pick <global-id> copies that global definition into the project, and refuses one the project loader rejects") |
 | `default.yaml` and the 13-step `fix.yaml` compile deterministically; back edges need budgets | `engine-compile.test.ts` |
 | Artifact gate: non-empty regular files pass; missing, empty, non-file and escaping paths fail | `artifacts-exist.test.ts` |
 | Vision gate: strict verdicts, admitted routes only, unreadable images fail closed | `vision-gate.test.ts` |

package/docs/reference/cli-reference.md

@@ -91,7 +91,7 @@ kxm -V
 - The `command` field is not always the words you typed: `hub stop` and `session stop` report `stop`, `session token` reports `auth token`, `routes admit` and `routes disable` report `routes admitted` and `routes disabled`, `models inventory-refresh` reports `models inventory refresh`, `workflow export` reports `retrospective export`, `gate degrade` reports `workflow degrade`, `gate signal` and `workflow signal` report `signal`, `gate github watch` reports `github watch`, `agent worker` reports `worker`, and `improve report` reports `improve`.
 - A result with `ok: false` is written to stderr in both text and JSON mode; everything else goes to stdout. `runtime status` is the exception: when the supervisor is down it prints `ok: true, running: false` on stdout and exits 1.
 - `peer` subcommands and `workflow checkpoint|record|wait` print the hub's result object as returned, tagged with `schema` but without `ok` or `command`. Their failures print `{"ok":false,"error":"command_failed","detail":"..."}`. Text mode prints the same JSON.
-- Several error paths ignore `--json` and print one plain line on stderr: argument checks in `agent worker`, `session start`, `workflow start`, `gate degrade`, `gate signal`, and `gate github watch`; every error from `config`, `role`, `workflow definitions|add|remove|modify` (except the three `workflow add --template` refusals, which honor `--json`), `goal`, `task`, `memory`, `skills` (other than `skills create --dry-run`), `suggest`, `studio`, and `completion`. Check the exit code before parsing stdout.
+- Several error paths ignore `--json` and print one plain line on stderr: argument checks in `agent worker`, `session start`, `workflow start`, `gate degrade`, `gate signal`, and `gate github watch`; every error from `config`, `role`, `workflow definitions|add|remove|modify` (except the `workflow add` refusals listed under it, which honor `--json`), `goal`, `task`, `memory`, `skills` (other than `skills create --dry-run`), `suggest`, `studio`, and `completion`. Check the exit code before parsing stdout.
 - Every `context` subcommand exits 1 with a Node.js stack trace and no JSON when the hub cannot be reached.
 - Output is redacted. Values of environment variables whose names contain `TOKEN`, `SECRET`, `KEY`, or `PASSWORD` are replaced with `[redacted]`, and 64-character hex strings are replaced unless they appear in a known digest field such as `configRevision` or `sha256`. `session brief` and `auth token` print the session token itself; treat their output as a credential.
 
@@ -1351,11 +1351,13 @@ kxm role resume <runId> [ruling]
 Resumes an audit-escalated run with an operator directive. The default ruling is `operator_ruling: waived and resumed`.
 
 - Arguments: `<runId>`; `[ruling]`, free text recorded with the decision.
-- For a KXM run ID (`run_` followed by 32 hex digits) inside a project, posts an `audit_escalation` signal with action `unblock` to the Runtime, starting the supervisor if needed. `--dry-run` plans the request without starting the supervisor. JSON keys: `runId`, `ruling`, `unblocked`.
-- For any other ID, updates the hub store at `.kxm/state/kxm.db` in the current directory directly (ignoring `--workspace` and `KXM_DATA_PATH`) and adds a `decision` journal entry. `--dry-run` reads the store read-only, reports the stage it would resume and the resulting `status`, and plans the write. JSON keys: `runId`, `stageId`, `ruling`, `status`.
+- Inside a project, a run that this project's Runtime store holds gets an `audit_escalation` signal with action `unblock` in the Runtime, starting the supervisor if needed. Hub workflow runs share the `run_` + 32-hex shape, so the store, not the ID, decides. `--dry-run` plans the request without starting the supervisor. JSON keys: `runId`, `ruling`, `unblocked`.
+- Any other run ID, including a hub workflow run of the same shape, updates the hub store at `.kxm/state/kxm.db` in the current directory directly (ignoring `--workspace` and `KXM_DATA_PATH`) and adds a `decision` journal entry. `--dry-run` reads the store read-only, reports the stage it would resume and the resulting `status`, and plans the write. JSON keys: `runId`, `stageId`, `ruling`, `status`.
 - The hub-run path bypasses the hub even while one is running: it writes SQLite directly, without authentication, in two statements outside one transaction. A running hub keeps runs in memory, so it does not see the change until it restarts, and its next write to that run overwrites it; it also pushes no event and sends the coordinator no resume message. Stop the hub first, or resume a live hub's run with a signed `audit_escalation` signal (see [Waits, signals and escalation](workflow-definitions.md#waits-signals-and-escalation)).
 - Errors: `resume_failed` (exit 1), or a plain `not found` line (exit 1).
 
+A run the project's Runtime holds:
+
 ```bash
 kxm role resume run_0123456789abcdef0123456789abcdef "waive the audit" --dry-run --json
 ```
@@ -1961,7 +1963,7 @@ WORKFLOW DEFINITIONS:
 kxm workflow add [workflowId] [--template <name> | --file <path> | --pick [selection]] [--description <text>] [--scope global|local] [--overwrite]
 ```
 
-Add a workflow definition to global or local configuration. With `--template <name>`, the named built-in template is written under the workflow ID. Without a workflow ID, or with `--pick`, you choose from the built-in templates and, for local scope, existing global definitions. With `--file`, the YAML file is copied as-is. Otherwise a one-step scaffold is written: one `implementer` agent step with write access to `control` that ends the run `completed` on `passed` and `failed` on `failed`.
+Add a workflow definition to global or local configuration. With `--template <name>`, the named built-in template is written under the workflow ID. Without a workflow ID, or with `--pick`, you choose from the built-in templates and, for local scope, existing global definitions; a global definition with a template's ID is not offered. The choice is written under its own ID with its content: the template, or a copy of the global definition's file, with `--description` replacing its description. With `--file`, the YAML file is copied as-is once it passes the local check below. Otherwise a one-step scaffold is written: one `implementer` agent step with write access to `control` that ends the run `completed` on `passed` and `failed` on `failed`.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -1975,7 +1977,8 @@ Add a workflow definition to global or local configuration. With `--template <na
 - Templates: `implement-and-verify` runs the `implementer` agent, then the project's `test` gate, and a failing gate (`implementation-failure`) sends the work back to `implement` at most twice. `dual-critic-review` adds two review steps between them, both run as the `coordinator` agent with read access; point `review-arch` and `review-cli` at your own agents for independent critics. `spec-and-plan` plans and then reviews the plan, both as `coordinator`, reading the repository only.
 - The templates and the scaffold are valid `kxm.workflow.v1` definitions that use only what `kxm init` creates: the `coordinator` and `implementer` agents, the `control` repository, and the `test` gate. Each was checked with `kxm init --json` and `kxm run <id> --dry-run` for this page. A new file under `.kxm/workflows/` is a permission expansion that `kxm trust check` asks you to review before you commit it.
 - Writes `<scope dir>/workflows/<id>.yaml`. `kxm run` loads only `.kxm/workflows/`, so a `--scope global` definition is not runnable until it is copied into a project. `--dry-run` plans the write and writes nothing.
-- `--template` refusals exit 2 and honor `--json`: `workflow_template_unknown` (the text names the three templates), `workflow_id_required` (no workflow ID), and `workflow_add_conflict` (combined with `--file` or `--pick`). An existing definition without `--overwrite` exits 1 with a plain `workflow add failed: workflow_already_exists: ...` line, also under `--dry-run`.
+- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/workflows/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new document in place of any file of that ID, using the parser, schema and bundle rules `kxm run` uses. If the project would not load, the command refuses with `workflow_invalid`, lists each issue and writes nothing, also under `--dry-run`. So `--file` or a picked global definition with a top-level `id` or a `role:` step, the shape `workflow add` wrote through 0.7.92, is refused, and `--overwrite` replaces a file left in that shape. Global scope is not checked, because no loader reads it.
+- Refusals exit 2 and honor `--json`: `workflow_template_unknown` (the text names the three templates), `workflow_id_required` (no workflow ID), `workflow_add_conflict` (`--template` combined with `--file` or `--pick`), `project_not_found`, and `workflow_invalid` (with `issues`, each `{phase, code, file, message}`). An existing definition without `--overwrite` exits 1 with a plain `workflow add failed: workflow_already_exists: ...` line, also under `--dry-run`.
 - JSON keys: `workflowId`, `id`, `filePath`, `scope`.
 
 Start a first workflow from a template:

package/docs/reference/config-reference.md

@@ -889,8 +889,10 @@ compiles and pins the plan, then drives it live, or without models with
 reads). Both are valid `kxm.workflow.v1` definitions that use only what
 `kxm init` creates: the `coordinator` and `implementer` agents, the `control`
 repository, and the `test` gate. The templates route gate failures on
-`implementation-failure`. Review the new file with `kxm trust check` before
-committing it.
+`implementation-failure`. A local add is checked by the project loader first:
+if the project would not load with the new file, it is refused with
+`workflow_invalid` and nothing is written. Review the new file with
+`kxm trust check` before committing it.
 
 ## `.kxm/gates.yaml` (`kxm.gate-registry.v1`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.99",
+  "version": "0.7.101",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.99",
+  "version": "0.7.101",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",