chore: upgrade clue managed carriers to 0.21.0

Author: flemming-n-larsen

.agents/skills/clue-analysis/references/decision-records.md

@@ -10,4 +10,6 @@ Agent-authored decisions start `status: inferred` and `author: agent`. Merging m
 
 Every new or modified decision record is timeless and compact: keep enduring context and the decision; add considered alternatives only when they materially explain the choice, and consequences only when they help a future reader act on it. Keep triggering incidents, chronology, conversations, carrier inventories, implementation walkthroughs, and review history in findings, the change workspace, the PR, and Git history.
 
+An ADR or IDR that changes system structure or cross-cutting design links in its body to the affected `docs/architecture/README.md` or `docs/design/README.md`; the decision states why the choice constrains future work and does not repeat the overview. A PDR links there only when it governs the documentation methodology.
+
 A decision that changes a methodology contract inventories every live carrier that states the affected contract and updates that complete inventory in the same change. Live carriers include current corpus truth, canonical and generated skills, templates, public or contributor guidance, implementation explanations, CLI text, and distribution metadata. Historical analyses, completed plans, and changelog entries remain pinned history. Add focused guards for stable repaired claims, but do not present those anchors as proof that an arbitrary future carrier inventory is complete; that general obligation remains agent-enforced until a mechanism can derive it.

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

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

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

@@ -8,6 +8,6 @@ Use when the user chooses the full Cliewen loop recommended for accepted-contrac
    - `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.
    - 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. 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 yet 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:** 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/decision-records.md

@@ -10,4 +10,6 @@ Agent-authored decisions start `status: inferred` and `author: agent`. Merging m
 
 Every new or modified decision record is timeless and compact: keep enduring context and the decision; add considered alternatives only when they materially explain the choice, and consequences only when they help a future reader act on it. Keep triggering incidents, chronology, conversations, carrier inventories, implementation walkthroughs, and review history in findings, the change workspace, the PR, and Git history.
 
+An ADR or IDR that changes system structure or cross-cutting design links in its body to the affected `docs/architecture/README.md` or `docs/design/README.md`; the decision states why the choice constrains future work and does not repeat the overview. A PDR links there only when it governs the documentation methodology.
+
 A decision that changes a methodology contract inventories every live carrier that states the affected contract and updates that complete inventory in the same change. Live carriers include current corpus truth, canonical and generated skills, templates, public or contributor guidance, implementation explanations, CLI text, and distribution metadata. Historical analyses, completed plans, and changelog entries remain pinned history. Add focused guards for stable repaired claims, but do not present those anchors as proof that an arbitrary future carrier inventory is complete; that general obligation remains agent-enforced until a mechanism can derive it.

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

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

.agents/skills/clue-extract/mappings/openspec.md

@@ -14,7 +14,7 @@ Layout: `openspec/config.yaml`, synced truth in `openspec/specs/<capability>/spe
 | Pending change (`changes/<name>/`) | a milestone in the repo's plan **plus** a `status: draft` capability holding its criteria (draft = exempt from the test contract until implemented) and its design decisions in `design.md` **plus** a durable `imported-change` record (`docs/imported-changes/`) pinning the source change's origin, intent, design rationale, dependency links, and a task-to-criterion proof-links table; extraction does not delete an incomplete pending change's in-flight work until its `imported-change` record's status reaches `complete` — `clue-delta` still regenerates the target's own `tasks.md` once implementation starts, but the source task graph and proof links survive in the record instead of dying with the source |
 | `changes/archive/…` | git history only — no corpus artifact |
 | Nygard/MADR ADRs in `docs/decisions` | see [madr.md](madr.md) for the conversion — MADR is a source format on its own, not an OpenSpec detail |
-| Architecture docs | `docs/architecture/` artifacts (`status: draft` until reviewed) or capability `design.md` where they are capability-local |
+| Architecture or broad design docs | The concise canonical `docs/architecture/README.md` or `docs/design/README.md`, with capability-local detail in `design.md`; survey and propose the grouped move before relocating an existing source document |
 | AC registry / scenario templates (`test/…`) | deleted — the corpus is the registry; next free ID per prefix is max + 1 over declared ACs |
 | Project README purpose statements | `G-xxx` goal(s), `status: accepted` (the repo's existence is the acceptance) |
 | Coverage/quality gates in build config | `C-xxx` constraints (`enforcement: machine`) referencing the enforcing tool |

.agents/skills/clue-extract/references/decision-records.md

@@ -10,4 +10,6 @@ Agent-authored decisions start `status: inferred` and `author: agent`. Merging m
 
 Every new or modified decision record is timeless and compact: keep enduring context and the decision; add considered alternatives only when they materially explain the choice, and consequences only when they help a future reader act on it. Keep triggering incidents, chronology, conversations, carrier inventories, implementation walkthroughs, and review history in findings, the change workspace, the PR, and Git history.
 
+An ADR or IDR that changes system structure or cross-cutting design links in its body to the affected `docs/architecture/README.md` or `docs/design/README.md`; the decision states why the choice constrains future work and does not repeat the overview. A PDR links there only when it governs the documentation methodology.
+
 A decision that changes a methodology contract inventories every live carrier that states the affected contract and updates that complete inventory in the same change. Live carriers include current corpus truth, canonical and generated skills, templates, public or contributor guidance, implementation explanations, CLI text, and distribution metadata. Historical analyses, completed plans, and changelog entries remain pinned history. Add focused guards for stable repaired claims, but do not present those anchors as proof that an arbitrary future carrier inventory is complete; that general obligation remains agent-enforced until a mechanism can derive it.

.agents/skills/clue-extract/references/target-contract.md

@@ -2,7 +2,7 @@
 
 The extraction PR is complete only when all of these hold:
 
-1. **The full taxonomy exists:** `/docs` has goals, plans, capabilities, decisions, constraints, analysis, and architecture, with an indexed README in every folder and README, criteria, and design files in each capability folder. Extract meaning; do not invent it. A folder with nothing real to hold stays empty but indexed. An index row states its record and says what the artifact is about; index generation seeds that sentence from the artifact's own body, and you correct it rather than leaving a seed that reads as a summary but states a problem.
+1. **The full taxonomy and system overviews exist:** `/docs` has goals, plans, capabilities, decisions, constraints, analysis, architecture, and design, with an indexed README in every folder and README, criteria, and design files in each capability folder. `docs/architecture/README.md` is a concise evidence-based overview of actors, boundaries, components, and durable technology choices; `docs/design/README.md` is a concise overview of cross-cutting flows, interactions, and patterns. Extract the big picture, not every local detail: capability `design.md` remains the local home. Survey the source for suitable existing overview documents and visual assets. Before moving any found overview into the canonical path, present one grouped source-to-target mapping and link rewrites to the human; move only after explicit consent. If consent is declined, keep the source and write a concise canonical pointer rather than duplicate it. Where evidence cannot establish a material boundary or intent, ask the human; otherwise draft the overview as inferred repository truth. Use Mermaid when it materially clarifies a relationship or flow, retaining SVG when Mermaid is inadequate. A folder with nothing real to hold stays empty but indexed. An index row states its record and says what the artifact is about; index generation seeds that sentence from the artifact's own body, and you correct it rather than leaving a seed that reads as a summary but states a problem.
 2. **Everything extracted is born inferred and decisions route by subject:** Use `provenance: inferred` plus `reversal-cost: low|high` on every non-decision artifact, classifying whether its meaning is cheap and local or expensive to reverse. A future-shaping decision instead uses `status: inferred` and `author: agent`, routing to ADR for architecture, PDR for project/process, or IDR for implementation; routine facts and history do not become records. Human review may promote records to `verified`, file by file or in bulk. An active capability cannot depend by one `links:` edge on high-cost inferred meaning, while low-cost inferred findings may remain legitimately deferred. Extracted decisions also follow [Decision records](decision-records.md). A legacy decision log is inventoried row by row in the rehearsal and remains until a reviewed full change classifies every future-shaping choice and explicitly accounts for discarded narrative; extraction never guesses or silently drops a row.
 3. **Existing criterion IDs survive; a criterion with none is minted deterministically:** Declare each capability's namespace with `ac-prefix:` and keep source IDs verbatim — never renumber, since IDs are meaning-immutable and existing test tags must keep resolving. A namespace may contain one or more uppercase alphanumeric segments joined by single hyphens, and a canonical criterion ID may carry a lowercase letter suffix after its numeric portion; case and punctuation are exact in the corpus. When a source requirement carries no stable ID of its own, mint one in its capability's `ac-prefix:` namespace: take the requirements without IDs in the source's own stated or file order and assign the next numeric slot after the maximum numeric component already declared in that namespace, ignoring letter suffixes for the maximum; an empty namespace starts at one. The corpus is the registry, a minted ID never collides with one kept verbatim, and the same source state always mints the same IDs. Record the preserved and minted mapping in the extraction report below.
 4. **Every test keeps or gains exactly one purpose without losing source evidence:** Existing criterion tags remain. Untagged tests get `Unit`, `Sanity`, or `Arch` according to intent. On the JVM, normalize each supported Java or Kotlin executable so its canonical AC identity, proof type, and direction attach together through literal JUnit method tags or the stable `test<PREFIX><digits>[lowercase-suffix]_<Type><Direction>_<description>` name; remove hyphens from segmented prefixes only in the named form and use underscores for hyphens in literal JUnit tags. A multi-criterion executable or class-level criterion tag is a semantic conflict: the rehearsal inventories its location, identities, behavior or structural scope, and proposed resolution, while a normalizer reports it but never deletes, selects, or relocates a tag. After explicit human direction, split a multi-criterion test into one-criterion executables that retain the relevant assertions, or keep one reviewed primary identity and record every other one as needing dedicated proof or an explicit `@draft` criterion. Move a class-level identity only to the executable that actually proves it or to a scoped new test; if that work is explicitly out of scope, record its source location and named plan door with an explicit `@draft` criterion. Comments, dynamic or multi-line tag expressions, and metadata split across methods are unsupported evidence; record and resolve the gap instead of installing an external rule or letting `clue` guess.

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

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