@klok-integration/cli 0.7.327 → 0.8.336

package/assets/agents/AGENTS.workspace.md

@@ -80,7 +80,7 @@ it when a task touches the platform:
 
 | File | Holds |
 |---|---|
-| `knowledge/platform-rules.md` | the current platform rules: principles, naming, route ids and legs, topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL |
+| `knowledge/platform-rules.md` | the current platform rules: principles, naming, route ids and legs, changes and work (change requests, implementation issues, beads), topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL |
 | `knowledge/glossary.md` | the Klok terms and what they mean |
 | `knowledge/kloker-identity.md` | Kloker's identity and writing style |
 | `knowledge/roles/` | the role handbooks of the Kloker role models |

package/assets/agents/knowledge/README.md

@@ -22,7 +22,7 @@ text of its own.
 | File | What it is | Composed into |
 |---|---|---|
 | `glossary.md` | the Klok terms and their meanings, with the rule never to guess a term | the role models `Kloker-Integration-Architect` and `Kloker-Integration-Developer` |
-| `platform-rules.md` | the current platform rules: principles, naming, route ids and legs, topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL | the agent runner's doctrine, the role models |
+| `platform-rules.md` | the current platform rules: principles, naming, route ids and legs, solutions, changes and work (change requests, implementation issues, beads), topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL | the agent runner's doctrine, the role models |
 | `kloker-identity.md` | who Kloker is, and the Unslop writing style | every request to the models `Kloker` and `Kloker-nothink` |
 | `roles/integration-architect.md`, `roles/integration-developer.md` | only what is specific to the role; the rules come from `platform-rules.md` | the role models `Kloker-Integration-Architect` and `Kloker-Integration-Developer` |
 | `retired-patterns.txt` | conventions the platform no longer has, one pattern per line with the reason | tests that fail when a prompt teaches a retired rule |

package/assets/agents/knowledge/glossary.md

@@ -24,6 +24,15 @@ it as the source does.
 | Tenant short name | `TENANTSHORT`, three upper case letters that start every solution and route id of a tenant: the first three consonants of the tenant's name (`KLK` for klok, `DGR` for degerfors), decided by the platform |
 | Solution | The business flow a set of routes implements; its id is the route id's prefix, for example `KLK007`. The id is allocated once, by a merge request in the tenant's `integration-solutions` registry, and never reused; a solution is reserved, active or retired |
 | Solution document | The `README.md` of a solution in the tenant's `integration-solutions` registry: its services, legs and flows, kept true to what is built |
+| Change request | A change to the integration landscape: an issue in the tenant's `integration-solutions` registry labelled `change-request`, named `<registry path>#<iid>`; its questions, design, issues, beads and merge requests link back to it |
+| Question | An issue in the registry labelled `question` and linked to a change request: something a person answers, in a comment, before the change can be planned |
+| Design merge request | The one merge request in the registry that designs a change request: it brings the solution document to the new steady state and adds the issue manifest |
+| Issue manifest | `ISSUE_MANIFEST.json` in `solutions/<KEY>_<slug>/changes/<iid>/` of the registry: the implementation issues a change request needs, each `planned`, or `approved` by a person; issues are made from it once it is on `main` |
+| Implementation issue | An issue in the project that does the work, made from an approved manifest item; it carries `solution:<KEY>`, a footer that names its change request, and a link to it |
+| `kloker`, `developer` | The labels of an implementation issue that say who builds it: Kloker, bead by bead, or a developer in a capable harness. Never both |
+| Bead | A file in `.beads/` of a repository that describes one small change of an implementation issue, small enough for Kloker with no judgement left (the bead sizing rules); it is done when the merge request that implements it merges |
+| Harness | The program a person runs a coding agent in, such as Claude Code, Codex, Copilot or OpenCode; only in this literal sense |
+| Background Kloker | The agent service's loop that follows a tenant's `kloker/policy.json` in Git: it repairs Kloker's merge requests and picks up the open beads of `kloker` issues |
 | Correlation id | `klok-correlation-id`: follows one business flow across routes and messages |
 | Task | Long-running work tracked by the platform (`KlokTaskV1` events, visible in klok.dev and the task API), for example an `ai.chat` task that asks Kloker for text |
 | Datamodel | A versioned data contract; the major version is in the name (`CustomerV1`). Classes: public (A), common (B) and domain (C) are XSD in a Git project of their own with generated Java, Python and TypeScript; system (X) models one external system and may be plain Java classes. All four classes may travel on the broker |

package/assets/agents/knowledge/platform-rules.md

@@ -96,6 +96,52 @@ documentation or the dependency catalog can give you.
 * New development and maintenance are one process: a change to a leg brings the solution document to the new steady
   state in the same change set, and `klok solutions check` compares the documents with the code on `main`.
 
+## Changes and work
+
+* A change to the integration landscape starts as a **change request**: an issue in `<tenant>/integration-solutions`
+  labelled `change-request`, `solution:<KEY>` (`solution:new` while the solution has no id) and `change:<kind>`, named
+  `<registry path>#<iid>` (`acme/integration-solutions#12`). Everything made for it links back to it. A question to a
+  person is an issue in the registry labelled `question` and linked to the change request; the answer is a comment, and
+  closing the question says it is answered. A comment a tool writes to say where a change stands carries
+  `<!-- klok:status -->`, and the planner reads past it.
+* **The design is one merge request** in the registry that mentions the change request (`Refs <registry>#<iid>`). It
+  brings the solution document to the new steady state, where every leg the change adds is `planned` on every line
+  that names it, and adds the plan: `solutions/<KEY>_<slug>/changes/<iid>/ISSUE_MANIFEST.json` with one
+  `issues/<stableKey>.md` per implementation issue. Planning again while it is open adds to the same merge request. A
+  person approves an item by setting it `approved` in the manifest; issues are created only from a plan on `main`, so
+  merging the design is what lets them be made.
+* **An implementation issue** lives in the project that does the work. It carries `solution:<KEY>`, a `relates_to` link
+  to the change request and to the issues it depends on, and a footer that names its change request, solution, stable
+  key, manifest path and dependencies. Every merge request Kloker opens carries `klok-integration-agent`; a draft whose
+  build never passed also `build-failed`.
+* **Kloker or a developer builds an issue, never both.** Bead creation either splits the issue into beads, labels it
+  `kloker` and opens a merge request with the bead files, or labels it `developer` and says in a comment why it cannot
+  be split. A developer builds a `developer` issue in a capable harness (Claude Code, Codex, Copilot, OpenCode), and
+  Kloker takes no bead of it.
+* **Claim before you start.** Whoever works on a bead reports it `in_progress` before the work starts and `open` again
+  when they let it go, and nobody starts a bead someone else holds. A bead with an open merge request is
+  `needs_review`.
+* **A bead is done when its merge request merges.** The merge request that implements a bead sets the bead file to
+  `done` with a progress entry, so the merge is what makes it done. A bead file on `main` that is `done` or `cancelled`
+  wins over any report, and a bead whose `dependsOn` are not all done on `main` waits.
+* **Two failures hand a bead to a developer.** When Kloker has failed on a bead twice since its file last changed, the
+  bead is reported `blocked`, its issue's label `kloker` is replaced by `developer`, and a comment says why and links
+  the draft merge requests. Changing the bead file gives Kloker two new attempts.
+* **The close rule.** A change request is ready to close when every implementation issue linked to it is closed and the
+  solution document on `main` describes what is built: no leg it added is still `planned`. A person closes it.
+
+**Bead sizing.** A bead is small enough for Kloker, a cheap model with no judgement left, or it is not a bead:
+
+* it changes one thing in one repository;
+* every decision is already named: the paths, the route id, the topics with their purpose, the datamodel and its
+  version, the configuration keys;
+* its acceptance criteria can be checked from the build and the diff;
+* it builds on its own;
+* it needs no missing fact and no step only a person may take (Vault, Ansible, Keycloak, a merge);
+* it is small, under a day's work for a person.
+
+An issue that cannot be split like that is a developer's.
+
 ## Topics and CloudEvents
 
 * `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]`. Production has no environment suffix

package/assets/agents/knowledge/retired-patterns.txt

@@ -46,6 +46,16 @@ topic-dlq # dead letters are <topic>_DLQ
 (?i)\ba topic created in advance # every topic is listed in its tenant's Pulsar file before it is used; "in advance" is the only way
 (?i)\b(enable|turn on|switch on) (automatic|auto-?)[ -]?topic[ -]creation # the Klok broker runs with allowAutoTopicCreation=false; request the topic in klok.dev
 #
+# klok.dev's work package model is retired (2026-10-29): a change request's work is implementation issues and beads in
+# GitLab, linked to the change request.
+(?i)\bwork[- ]packages?\b # the work package model is retired; a change request's work is implementation issues and beads in GitLab
+(?i)\bTodo 360\b # the work package model is retired; a change request's work is implementation issues and beads in GitLab
+# The planner loads the platform rules instead of restating the 11-step process of the old strategy chapter
+# (klok-integration-agent#47); issues are linked with relates_to, and an issue is split into beads, not planned again.
+(?i)\b11-step\b # the development process is described once, in the Klok user guide; a prompt loads the platform rules instead of restating a process
+(?i)\bGitLab Free has no issue links\b # implementation issues are linked to their change request and their dependencies with relates_to, which every GitLab edition has
+(?i)\blocal GSD\b # an implementation issue is split into beads by bead creation; there is no local planning step before it
+#
 # Framework classes that do not exist in the Quarkus extension 2.0 and later.
 KlokSoapApi # removed in 2.0; SOAP is a KlokCustomRoute with camel-cxf
 KlokTenantBridgeRoute # does not exist; a KlokProcessingRoute in the reading tenant maps a granted topic

package/assets/agents/skills/klok-cli/SKILL.md

@@ -30,12 +30,23 @@ CLI version, generated from the program itself; when it is missing (an installer
 | what a CI job is, whether a change is documentation only, where CI time goes | `klok ci env`, `klok ci docs-only`, `klok ci timings` |
 | a pipeline's image in its deploy manifest | `klok manifest update --dry-run` (CI runs it without) |
 | a release pinned in an infrastructure repository | `klok pin update ... --dry-run` |
+| a change request with its questions, design merge requests and implementation issues, and who builds each | `klok change show <registry>#<iid>` (or the URL of an implementation issue) |
+| a change request planned into its solution document and one issue manifest | `klok agent plan --change <registry>#<iid>` |
 | the beads of the current repository | `klok bead list`, `klok bead show <id>`, `klok bead report <id>` |
+| a bead taken before you start, let go, or done in the merge request that implements it | `klok bead claim <id>`, `klok bead release <id>`, `klok bead done <id> --merge-request <url>` |
 | the repository, root element and namespace a datamodel's class and name give | `klok datamodel names` |
 | an XSD checked the way the datamodel pipeline checks it | `klok datamodel validate` |
 | this repository's `klok-docs/` checked before the merge request | `klok docs build`, `klok docs verify` |
 | a sealing key for a tenant's klok-file-transfer, a secret sealed for a file flow, or flows written to the ODL from Git | `klok file-transfer keygen`, `seal`, `apply --dry-run` (then without) |
 
+## Working on a change request
+
+Who builds an implementation issue, when a bead is claimed and when it is done are in `knowledge/platform-rules.md`,
+*Changes and work*, next to `KLOK-AGENTS.md`. Follow it when a task names a change request, an implementation issue
+or a bead: `klok change show` reads where the change stands, `klok bead claim` takes a bead before you start (a bead
+someone else holds is refused), and `klok bead done --merge-request` sets it done in the merge request that implements
+it. Never take a bead of an issue labelled `developer` unless you are that developer.
+
 ## The workspace
 
 `klok sync pull` brings the workspace current before you read it: every repository under the workspace root (config

package/assets/agents/skills/klok-cli/reference.md

@@ -32,9 +32,12 @@ Examples:
   klok agent ask "Which legs consume InvoiceV1?"
   klok agent ask "..." --json | jq .task.resultSummary
   klok agent impact InvoiceV1 --change major --json
+  klok agent plan --change acme/integration-solutions#12
   klok agent plan KLK001 --change-request change.md
+  klok change show acme/integration-solutions#12
   klok agent serve
-  klok bead report fortnox-egress-1 --status done --message "Merged MR !12"
+  klok bead claim issue-4-route
+  klok bead done issue-4-route --merge-request https://git.klok.dev/acme/r/-/merge_requests/12
   klok code                       # the bundled terminal agent: tools in src/klokcode/, MCP from klokcode.jsonc
   klok agents init                # KLOK-AGENTS.md, harness rows, platform and tenant skills, the session hook
   klok agents update              # fetch the platform and tenant catalogs, write what moved, prune by marker
@@ -186,21 +189,33 @@ Impact analysis for a node id or datamodel name
 ### klok agent plan
 
 ```
-klok agent plan [options] <solutionKey>
+klok agent plan [options] [solutionKey]
 ```
 
-Plan a solution change from a change request file (or - for stdin)
+Plan a change request into its solution document and one issue manifest, delivered as the design merge request (--change), or a change written in a file (--change-request)
 
 | Argument | Description |
 |---|---|
-| `<solutionKey>` | required |
+| `[solutionKey]` | optional |
 
 | Option | Description |
 |---|---|
+| `--change <ref>` | The change request, <registry path>#<iid>; its issue, comments and questions are read |
 | `--change-request <file>` | Path to the change request text, or - for stdin |
 | `--answer <questionId=text...>` | Clarification answers |
+| `--git-url <url>` | GitLab base URL, to read the solution of --change (default: config gitUrl) |
+| `--token <token>` | GitLab personal access token, to read the solution of --change (default: KLOK_GIT_APIKEY, then config klokApiKey) |
 | `--no-wait` | Create the task and return immediately |
 
+```
+With --change, the solution is the change request's label solution:<KEY> unless [solutionKey] names it, and the plan
+goes onto the change request's open design merge request when it has one.
+
+Examples:
+  klok agent plan --change acme/integration-solutions#12
+  klok agent plan KLK001 --change-request change.md
+```
+
 ### klok agent implement
 
 ```
@@ -323,6 +338,80 @@ Print one bead
 |---|---|
 | `<beadId>` | required |
 
+### klok bead claim
+
+```
+klok bead claim [options] <beadId>
+```
+
+Take a bead before you start on it: report it in_progress to klok.dev, without changing its file
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--message <text>` | What you are about to do |
+| `--by <name>` | Reporter name; defaults to the logged-in user |
+| `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
+| `--force` | Claim it even though someone else holds it unfinished |
+
+```
+The agent service refuses the claim (409) when someone else holds the bead unfinished (in_progress or needs_review)
+in klok.dev; --force takes it anyway, so agree with them first.
+
+Examples:
+  klok bead claim issue-4-route
+  klok bead claim issue-4-route --message "Mapping the currency first"
+```
+
+### klok bead done
+
+```
+klok bead done [options] <beadId>
+```
+
+Set a bead to done in its file, for the merge request that implements it, and report the merge request
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--merge-request <url>` | The merge request that implements the bead |
+| `--message <text>` | What the merge request does |
+| `--by <name>` | Reporter name; defaults to the logged-in user |
+| `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
+| `--local-only` | Update the bead file without reporting to klok.dev |
+
+```
+A bead is done when the merge request that implements it merges: commit the changed bead file in that merge request.
+klok.dev shows the bead needs_review until then.
+
+Examples:
+  klok bead done issue-4-route --merge-request https://git.klok.dev/acme/integration/domain/finance/acme-fortnox-egress/-/merge_requests/7
+```
+
+### klok bead release
+
+```
+klok bead release [options] <beadId>
+```
+
+Let a bead go: report it open to klok.dev, so someone else or Kloker can take it
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--message <text>` | Why you let it go |
+| `--by <name>` | Reporter name; defaults to the logged-in user |
+| `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
+
 ### klok bead report
 
 ```
@@ -339,10 +428,46 @@ Append progress to a bead and report it to klok.dev
 |---|---|
 | `--status <status>` | open \| blocked \| in_progress \| needs_review \| done \| cancelled |
 | `--message <text>` | What happened |
+| `--merge-request <url>` | The merge request of the work |
 | `--by <name>` | Reporter name; defaults to the logged-in user |
 | `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
 | `--local-only` | Update the bead file without reporting to klok.dev |
 
+## klok change
+
+```
+klok change [options] [command]
+```
+
+Change requests: an issue in the solution registry, and the questions, design and issues linked to it
+
+### klok change show
+
+```
+klok change show [options] <target>
+```
+
+Print a change request, read from GitLab: its comments, questions, status, design merge requests and implementation issues with who builds each
+
+| Argument | Description |
+|---|---|
+| `<target>` | required |
+
+| Option | Description |
+|---|---|
+| `--git-url <url>` | GitLab base URL (default: config gitUrl) |
+| `--token <token>` | GitLab personal access token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+
+```
+<target> is the change request (<registry path>#<iid>), the URL of its issue, or the URL of an implementation issue,
+whose footer names its change request.
+
+Examples:
+  klok change show acme/integration-solutions#12
+  klok change show https://git.klok.dev/acme/integration/domain/finance/acme-fortnox-egress/-/issues/4
+  klok change show acme/integration-solutions#12 --json | jq '.changeRequest.implementationIssues'
+```
+
 ## klok agents
 
 ```

package/assets/agents/skills/klok-solution/SKILL.md

@@ -71,6 +71,15 @@ shared platform service) in `klok/integration-solutions`.
     carries `planned` in the Status column of its table row; `klok solutions check` relies on it. After the merges,
     run `klok solutions check` again.
 
+## Working on a change request
+
+A change often arrives as a change request: an issue in `<tenant>/integration-solutions` labelled `change-request`.
+How it becomes one design merge request with its plan under `changes/<iid>/`, implementation issues that Kloker or a
+developer builds, and beads that are done when their merge request merges, is in `knowledge/platform-rules.md`,
+*Changes and work*, next to `KLOK-AGENTS.md`. Read the change request with its comments and its linked `question`
+issues before step 3, and mention it (`Refs <registry>#<iid>`) in the merge request that brings the document to the new
+steady state.
+
 ## Maintenance is the same process
 
 * A fix or a change in one route starts at step 1: find its solution and read it before touching the code.