Upgrade Cliewen to 0.26.0

.agents/skills/clue-analysis/skill.md

@@ -1,6 +1,6 @@
 ---
 cliewen-skill: true
-version: 0.24.1
+version: 0.26.0
 ---
 
 <!-- Generated from Cliewen's canonical skill sources; edit those sources, not this file. -->

.agents/skills/clue-delta/references/challenge-commitments.md

@@ -0,0 +1,7 @@
+## Challenge a consequential commitment
+
+Before a consequential commitment, challenge it where the reviewer will read it: in the plan's prose for a plan, in `proposal.md` for a change. Name the assumption most likely to undermine the work, a credible alternative course, the cheapest useful test of that assumption, and the result that would stop or revise the work. Then ask what an implementation could look like that met every criterion and still failed the person the work is for — that is the failure a criterion-to-test thread cannot catch, because one author usually writes the criterion, its implementation, and its test in one sitting.
+
+A commitment is consequential when being wrong would cost more than finding out first: adopting or revising a plan's promise, starting a milestone whose approach is unsettled, choosing between credible courses in a decision, or a change to what adopters receive. Route first: simple work is never consequential, even when it touches a shipped surface. Work carrying out a course already challenged and understood, and work that can be undone within the same change at no more cost than the challenge, also proceed without a challenge and without a note explaining its absence.
+
+The proportionality limit is part of the rule, not an exemption from it: a challenge demanded of everything is written by habit, and a challenge written by habit is the confident, unexamined text this rule exists to interrupt. No prototype is ever universally required; a small path across the consequential boundaries is warranted only where the architecture is materially uncertain, and a milestone may deliver decision-changing evidence instead of a feature. Cite applicable repository experience when challenging assumptions, and treat it as evidence to reassess against the case in hand rather than as settled authority.

.agents/skills/clue-delta/references/change-loop.md

@@ -2,12 +2,20 @@
 
 Use when the user chooses the full Cliewen loop recommended for accepted-contract change. Simple work is recommended before this skill and does not invoke it. Apply [Decision records](decision-records.md), [Repository-local conventions](repository-local-conventions.md), and [Durable work state](durable-work-state.md) throughout the loop.
 
-1. **Branch:** Follow the review boundary, get the next CH identity with `clue id next CH`, and name the branch `ch-xxx-slug` with that identity. The command follows the ledger's tracked coordination mode. When it warns that allocation is local and contributors may work in parallel clones or worktrees, stop and either serialize allocation on the integration branch or have a maintainer enable Git coordination with `clue id coordinate` before contributors branch. A contributor given a preallocated identity runs `clue id sync`, uses that reservation, and never allocates independently from a stale local ledger. If remote allocation fails, do not guess, reuse, or edit the number by hand; retry or sync the allocator's permanent claims. Coordination settings live in `.clue/id-coordination.yaml`, not in the ledger; commit both after `clue id coordinate`, and treat a merge conflict in that file as the user's decision about which remote the team meant, never yours to resolve. Never re-point an established repository at a different remote. When a command reports that Git's union merge combined the ledger, the identities are intact: run `clue id repair`, or let the next command that saves the ledger rewrite it, and never hand-edit an append-only log. If two artifacts hold one identity, allocate a fresh one for the later artifact and update its references rather than renumbering either by hand.
+1. **Branch:** Follow the review boundary, get the next CH identity with `clue id next CH`, and name the branch `ch-xxx-slug` with that identity.
+   - The command follows the ledger's tracked coordination mode. When it warns that allocation is local and contributors may work in parallel clones or worktrees, stop and either serialize allocation on the integration branch or have a maintainer enable Git coordination with `clue id coordinate` before contributors branch. A contributor given a preallocated identity runs `clue id sync`, uses that reservation, and never allocates independently from a stale local ledger. If remote allocation fails, do not guess, reuse, or edit the number by hand; retry or sync the allocator's permanent claims.
+   - Coordination settings live in `.clue/id-coordination.yaml`, not in the ledger; commit both after `clue id coordinate`, and treat a merge conflict in that file as the user's decision about which remote the team meant, never yours to resolve. Never re-point an established repository at a different remote.
+   - When a command reports that Git's union merge combined the ledger, the identities are intact: run `clue id repair`, or let the next command that saves the ledger rewrite it, and never hand-edit an append-only log. If two artifacts hold one identity, allocate a fresh one for the later artifact and update its references rather than renumbering either by hand.
 2. **Propose:** Create `/changes/CH-xxx-slug/`, commit and push it before implementation, and open the draft PR under the review boundary:
    - `proposal.md` states what and why; its frontmatter `links` names the real plan item it serves or explicitly declares the change plan-less.
    - `tasks.md` is an ordered `- [ ]` checklist with dependencies first and at most one nested level. Mark an infeasible task `[-]` with its reason on the same line, whenever it is marked. A behavior-changing task names the acceptance-criterion IDs it serves; if none exists, add the criterion before implementation. Tests trace to criteria, never transient tasks.
-   - `open-questions.md` records blocking questions. When one appears, write it and stop; the human answer becomes a decision record.
+   - `open-questions.md` records blocking questions. When one appears, write it and stop; record the human answer as a decision only when it is future-shaping.
    - A human may opt into a spec-first pause after Propose. Record the pause in `tasks.md`, report briefly what the proposal says and what implementation involves, and ask whether implementation should begin — the proposal is already committed, pushed, and visible on the draft PR. Stop until the human directs work to continue; otherwise proceed directly to Implement.
-3. **Implement:** Update the permanent corpus. Before and after implementation, assess documentation impact: keep the required architecture and design overviews current when their structure or cross-cutting behaviour changes, update the relevant capability design or general design document when it answers a reader's question, and link rather than duplicate. State in the change or pull-request handoff which durable documentation changed, or why none was needed; do not create a permanent change-history document. Architecture owns actors, boundaries, and durable technology choices; `docs/design/README.md` owns cross-cutting flows and patterns; a capability's `design.md` owns local detail. Draft a missing overview from repository evidence, and ask the human only when a material boundary or intent remains unclear. Use Mermaid when a diagram materially clarifies a relationship, boundary, or flow; retain SVG only when Mermaid is inadequate. A relevant new or materially revised ADR or IDR links to the affected overview. Capabilities own README, criteria, and design files. Write criteria as Gherkin tagged with their canonical `<PREFIX>-<digits>[lowercase-suffix]` identity; every new or materially revised criterion declares `Test-type: Unit|Integration|E2E|Performance|Human` on the first line of its scenario body and gets focused positive and negative evidence in that class (or records `(single-direction)` when only one direction exists). `Human` needs no code evidence — the acceptance brief's criteria line is its proof; use it for a criterion deliberately verified by human judgment, never as a placeholder for a test not written. A criterion genuinely not yet proven carries `@draft` on its tag line instead, exempting only that criterion from the active-file test requirement — the capability itself does not need to stay `draft` because one criterion is unproven. Every test declares exactly one purpose: the criterion ID, `Unit`, `Sanity`, or `Arch`, using framework tags where available and the normalized test-name prefix in Go; AC evidence also carries its declared test type and direction. On the JVM, all three evidence parts attach to the same Java or Kotlin executable through literal JUnit method tags or the stable `test<PREFIX><digits>[lowercase-suffix]_<Type><Direction>_<description>` name; class tags, comments, and unrelated methods cannot supply missing parts. When a criterion's meaning changes, retire it with `@retired`, keep the tombstone, mint a new ID, and remove or retag its tests.
+3. **Implement:**
+   - Before starting or resuming work for a milestone, assess whether its plan still serves the goal, the milestone remains wanted and achievable, and the remaining dependencies and order still hold. Repeat the assessment when new evidence challenges the campaign. A passing assessment needs no record. When it fails, write the mismatch and options in `open-questions.md` and pause affected work for human direction. After direction, declare the selected revision in the plan; record it only when the selected course is future-shaping.
+   - Update the permanent corpus. Before and after implementation, assess documentation impact: keep the required architecture and design overviews current when their structure or cross-cutting behaviour changes, update the relevant capability design or general design document when it answers a reader's question, and link rather than duplicate. State in the change or pull-request handoff which durable documentation changed, or why none was needed; do not create a permanent change-history document. Architecture owns actors, boundaries, and durable technology choices; `docs/design/README.md` owns cross-cutting flows and patterns; a capability's `design.md` owns local detail. Draft a missing overview from repository evidence, and ask the human only when a material boundary or intent remains unclear. Use Mermaid when a diagram materially clarifies a relationship, boundary, or flow; retain SVG only when Mermaid is inadequate. A relevant new or materially revised ADR or IDR links to the affected overview.
+   - Capabilities own README, criteria, and design files. Write criteria as Gherkin tagged with their canonical `<PREFIX>-<digits>[lowercase-suffix]` identity; every new or materially revised criterion declares `Test-type: Unit|Integration|E2E|Performance|Human` on the first line of its scenario body and gets focused positive and negative evidence in that class (or records `(single-direction)` when only one direction exists). `Human` needs no code evidence — the acceptance brief's criteria line is its proof; use it for a criterion deliberately verified by human judgment, never as a placeholder for a test not written. A criterion genuinely not yet proven carries `@draft` on its tag line instead, exempting only that criterion from the active-file test requirement — the capability itself does not need to stay `draft` because one criterion is unproven.
+   - Every test declares exactly one purpose: the criterion ID, `Unit`, `Sanity`, or `Arch`, using framework tags where available and the normalized test-name prefix in Go; AC evidence also carries its declared test type and direction. On the JVM, all three evidence parts attach to the same Java or Kotlin executable through literal JUnit method tags or the stable `test<PREFIX><digits>[lowercase-suffix]_<Type><Direction>_<description>` name; class tags, comments, and unrelated methods cannot supply missing parts.
+   - When a criterion's meaning changes, retire it with `@retired`, keep the tombstone, mint a new ID, and remove or retag its tests.
 4. **Digest:** After every task is `[x]` or `[-]` with a reason, update permanent `/docs`, regenerate README indexes, apply repository-local digest conventions, record decisions, and update plan bookkeeping. Retiring a non-criterion artifact means deleting its file in this same digest — never leaving a `status: retired` file behind — and naming the dead ID in a `supersedes:` field on its successor or best live next stop; criteria tombstones (`@retired`, file kept so the test tag keeps failing) and completed plans (frozen, never deleted) are the named exceptions. Delete the change workspace. The digest is never a task in `tasks.md`; deletion is the digest, so a self-referential digest task cannot be completed honestly.
 5. **Verify, review, and propose for acceptance:** Run `clue-verify`, including its automatic agentic review loop on the verified committed candidate, then mark the draft PR ready under the [Review boundary](review-boundary.md). For a full change, fill the acceptance brief at the top of the PR body with the plan item and whether it remains wanted, every added or changed criterion and its scenario-resolution verdict — naming any newly or materially declared `Human`-class criterion there as its proof — and what merge binds or supersedes, including any authorized unmerged base and the meaning accepting this change would bind before that base is accepted; keep it to one screen and never leave template placeholders. Never ask the human to initiate the review. Merging accepts the change; decision provenance follows [Decision records](decision-records.md).

.agents/skills/clue-delta/references/change-scope-and-tiers.md

@@ -7,4 +7,4 @@ Before editing, inspect the smallest relevant context and tell the user `Recomme
 
 Paths, file counts, and changed-line counts may warn but never decide meaning. Reassess when a discovery expands semantic scope and against the complete diff before integration. If simple work grows into full work, pause and recommend the full loop. If the user explicitly declines, proceed as simple without making code, tests, or durable documentation untruthful, and add all three trailers to the final authored commit: `Cliewen-Route: simple`, `Cliewen-Recommendation: full`, and `Cliewen-Override: user chose simple; <concise risk>`. This records one integration authorization in Git history, not a corpus decision.
 
-A route does not authorize a push. Push directly to an integration branch only with explicit user authorization and repository permission; otherwise follow the repository's requested workflow. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact.
+A route does not authorize a push; the [Review boundary](review-boundary.md) states when an agent may push to an integration branch. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact.

.agents/skills/clue-delta/references/durable-work-state.md

@@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen
 
 A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens.
 
+A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy.
+
+An eligible discovery is captured under these rules:
+
+- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down.
+- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it.
+- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide.
+- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial.
+- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone.
+
 A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when.
 
-After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next.
+When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else.

.agents/skills/clue-delta/references/intent-model.md

@@ -36,6 +36,6 @@ Recommend for or against one, say why, and let the human decide. A use case is c
 
 ### Marking what is not yet confirmed
 
-Agent-drafted intent is `status: draft` with `provenance: inferred` and a stated `reversal-cost`, and its assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask.
+Agent-drafted intent is `status: draft` with `provenance: inferred` and `reversal-cost: low|high`; low explicitly permits deferral, while high can block an active capability that directly depends on the artifact. Once a human verifies the meaning, remove `reversal-cost`; it is no longer used. Assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask.
 
 **A full change's acceptance brief states the vision it proceeds under**, or states that the repository has none and that the change proceeds without one. When unresolved meaning would materially change what the system is for, stop and ask rather than deciding it inside an implementation.