Merge pull request #245 from robocode-dev/ch-029-cliewen-upgrade

chore: upgrade clue carriers and normalize ADR identifiers

Author: flemming-n-larsen

.agents/instructions/cross-platform.md

@@ -10,7 +10,7 @@ All official Bot APIs MUST be 1:1 semantically equivalent to the Java Bot API. S
 - `snake_case` (Python) vs `camelCase` (Java/TypeScript)
 - Properties (C#/Python) vs getters/setters (Java)
 - `@dataclass` (Python) vs immutable classes (Java)
-- `async/await` (TypeScript) for blocking methods like `forward()` — see ADR-0028
+- `async/await` (TypeScript) for blocking methods like `forward()` — see ADR-028
 
 **Unacceptable differences:**
 - Different default values, event order, null/None handling, or validation rules

.agents/instructions/documentation.md

@@ -110,9 +110,9 @@ Canonical home for all sequence diagrams: `docs/architecture/models/flows/`
 | `game-ended-event-*` | `battle-lifecycle.md` — Phase 4 (GAME_ENDED) |
 | `game-aborted-event`, `stop-game` | `battle-lifecycle.md` — Aborting a Game |
 | `pause-game`, `resume-game`, `game-paused-event-*`, `game-resumed-event-*` | `battle-lifecycle.md` — Manual Pause |
-| `next-turn` | `battle-lifecycle.md` — Debug Mode (ADR-0033) |
-| `enable-debug-mode`, `disable-debug-mode` | `battle-lifecycle.md` — Debug Mode (ADR-0033) |
-| `bot-policy-update` | `battle-lifecycle.md` — Breakpoint Mode (ADR-0034) and Debug Graphics Policy |
+| `next-turn` | `battle-lifecycle.md` — Debug Mode (ADR-033) |
+| `enable-debug-mode`, `disable-debug-mode` | `battle-lifecycle.md` — Debug Mode (ADR-033) |
+| `bot-policy-update` | `battle-lifecycle.md` — Breakpoint Mode (ADR-034) and Debug Graphics Policy |
 | `change-tps`, `tps-changed-event` | `battle-lifecycle.md` — Changing TPS |
 | All bot gameplay events (`scanned-bot-event`, `hit-by-bullet-event`, etc.) | `event-handling.md` — Key event list |
 | `team-message`, `team-message-event` | `event-handling.md` — Team Events section |

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

@@ -1,13 +1,13 @@
 ## Decision records
 
-Route every decision by reversal cost. A cheap-and-local-to-reverse decision is a dated row in `docs/decisions/log.md` (columns `Date | Decision | Why | Change/PR`); otherwise write an ADR for software or corpus architecture, or a PDR for how the project works. A decision adopting a well-established practice cites it by name and records only the local why.
+Only a future-shaping choice earns a decision record. Route it by subject to exactly one type: an ADR for software or corpus architecture, a PDR for how the project or its methodology works, or an IDR for implementation. Reversal cost does not route a record; routine facts, chronology, and implementation history are not decisions. A decision adopting a well-established practice cites it by name and records only the local why.
 
-A rejected alternative that is itself a decision gets a rejected decision record, not only a paragraph in a findings document — a route not taken, an interface declined, a mechanism ruled out — whenever re-proposing it later would be expensive; it routes by the same reversal-cost test as any other decision. A rejection that is cheap to revisit stays a paragraph.
+A rejected future-shaping choice gets a rejected decision record rather than only a paragraph in findings, routed by the same subject test. A rejected option that does not constrain future work stays a paragraph.
 
 Agent-authored decisions start `status: inferred` and `author: agent`. Merging makes them binding without changing that status. Only explicit human approval promotes a decision to `verified`; record every approver in `accepted-by:`, use the first approval date, and cite the venue. An explicit objection keeps the decision `inferred` and becomes an open question.
 
 `accepted-by:` records only approval given under Cliewen's merge boundary, never acceptance a source record already carried. A record converted from a format with its own acceptance history — names, roles, dates predating the corpus — preserves that history as body prose and keeps `accepted-by: []`, the same empty list any unsigned record carries.
 
-Every decision record is timeless: state what is decided and only the enduring context and rationale needed to understand it. Keep triggering incidents, chronology, conversations, implementation details, and review history in findings, the change workspace, the PR, and Git history.
+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.
 
 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.16.0
+version: 0.20.0
 ---
 
 <!-- Generated from Cliewen's canonical skill sources; edit those sources, not this file. -->

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

@@ -9,5 +9,5 @@ Use when the user chooses the full Cliewen loop recommended for accepted-contrac
    - `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.
-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 on `docs/decisions/log.md` when a demoted decision has none; 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.
+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

@@ -1,13 +1,13 @@
 ## Decision records
 
-Route every decision by reversal cost. A cheap-and-local-to-reverse decision is a dated row in `docs/decisions/log.md` (columns `Date | Decision | Why | Change/PR`); otherwise write an ADR for software or corpus architecture, or a PDR for how the project works. A decision adopting a well-established practice cites it by name and records only the local why.
+Only a future-shaping choice earns a decision record. Route it by subject to exactly one type: an ADR for software or corpus architecture, a PDR for how the project or its methodology works, or an IDR for implementation. Reversal cost does not route a record; routine facts, chronology, and implementation history are not decisions. A decision adopting a well-established practice cites it by name and records only the local why.
 
-A rejected alternative that is itself a decision gets a rejected decision record, not only a paragraph in a findings document — a route not taken, an interface declined, a mechanism ruled out — whenever re-proposing it later would be expensive; it routes by the same reversal-cost test as any other decision. A rejection that is cheap to revisit stays a paragraph.
+A rejected future-shaping choice gets a rejected decision record rather than only a paragraph in findings, routed by the same subject test. A rejected option that does not constrain future work stays a paragraph.
 
 Agent-authored decisions start `status: inferred` and `author: agent`. Merging makes them binding without changing that status. Only explicit human approval promotes a decision to `verified`; record every approver in `accepted-by:`, use the first approval date, and cite the venue. An explicit objection keeps the decision `inferred` and becomes an open question.
 
 `accepted-by:` records only approval given under Cliewen's merge boundary, never acceptance a source record already carried. A record converted from a format with its own acceptance history — names, roles, dates predating the corpus — preserves that history as body prose and keeps `accepted-by: []`, the same empty list any unsigned record carries.
 
-Every decision record is timeless: state what is decided and only the enduring context and rationale needed to understand it. Keep triggering incidents, chronology, conversations, implementation details, and review history in findings, the change workspace, the PR, and Git history.
+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.
 
 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.16.0
+version: 0.20.0
 ---
 
 <!-- Generated from Cliewen's canonical skill sources; edit those sources, not this file. -->