Wave-protocol hardening, profile-invariance principle, and skill dedup

skills/adr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:adr
 description: This skill should be used when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database, communication protocol, or infrastructure pattern.
-version: 0.3.0
+version: 0.3.1
 ---
 
 # ADR
@@ -26,7 +26,7 @@ Read `references/adr-conventions.md` for placement and lifecycle rules and `refe
 1. Read the existing ADR in full.
 2. **Upstream check:** If a relevant design doc exists under `docs/design/`, check whether the revised decision conflicts with current architecture. Warn the user if so.
 3. A decision that *evolves without changing direction* updates in place: refine consequences, note what shifted and why. Move `Proposed` → `Accepted` when the team agrees.
-4. A decision that *changes direction* is a new ADR: write the replacement under its own number, mark the old record `Superseded by NNNN`, and link forward. Never delete or rewrite a superseded ADR — the history stays readable. Partial supersession is stated on the old record ("the X portion superseded by NNNN") rather than pretending the whole decision flipped.
+4. A decision that *changes direction* is a new ADR under its own number; the supersession mechanics — forward links, partial supersession, never deleting or rewriting the old record — follow `references/adr-conventions.md` § Lifecycle.
 5. Refresh the index one-liners for every record the change touched.
 
 ## Output

skills/codebase-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:codebase-docs
 description: Generate or update hierarchical, AI-navigable documentation for a codebase under `docs/ai/`. Use whenever the user asks to "document the codebase for AI", "bootstrap AI docs", "generate codebase map", "set up AI navigation docs", "update AI docs", "refresh docs after change", or mentions building progressive-disclosure docs so an AI can find the right source files quickly. Produces a tree of concise docs that *point to* code rather than duplicate it. Use even when the user only says "document this repo" without specifying the structure.
-version: 0.1.0
+version: 0.1.1
 ---
 
 # Codebase Docs for AI Navigation
@@ -71,7 +71,7 @@ Use a named symbol when one exists — function, class, struct, type, const, rou
 
 **Coherence over splitting.** If a topic is naturally one story, keep it in one doc even if it runs a bit long. Only split when there's a genuinely bounded sub-concept *and* the parent is getting unwieldy — see the split heuristic below.
 
-**Match the code's vocabulary.** Use the same names the code uses. If the source folder is `rcp/` (or the package is `@org/rcp`, or the module is `rcp`), the doc folder is `rcp/` — not a more "descriptive" alias like `remote-control-protocol/`. The doc's job is to be findable from the code's own terms.
+**Match the code's vocabulary.** Use the same names the code uses (the folder-naming rule under "Output location and shape") — the doc's job is to be findable from the code's own terms, never through a more "descriptive" alias.
 
 ## Split heuristic
 
@@ -122,27 +122,7 @@ Rule of thumb: a good branch doc is ~30–80 lines. A good leaf doc is ~20–120
 
 ## Working example (sketch)
 
-The shape is the same regardless of stack — the folder names just mirror whatever the codebase calls its parts. A typical tree for a multi-area repo:
-
-```
-docs/ai/
-├── README.md                         # one paragraph: what the repo is + a menu of areas
-├── <area-1>/
-│   ├── README.md                     # menu of sub-topics in this area
-│   ├── <topic-a>.md                  # leaf: what / (why) / where
-│   ├── <topic-b>.md
-│   └── <sub-area>/
-│       ├── README.md
-│       └── <topic-c>.md
-├── <area-2>/
-│   ├── README.md
-│   ├── <topic-d>.md
-│   └── <topic-e>.md
-└── <area-3>/
-    └── README.md                     # small enough to stay single-doc
-```
-
-Concrete shape examples for different stacks:
+The shape is the same regardless of stack — the tree under "Output location and shape" above, with folder names mirroring whatever the codebase calls its parts. Concrete shape examples for different stacks:
 
 - **TS monorepo (`apps/`, `packages/`)** — top-level menu mirrors workspace members: `docs/ai/apps/<app>/`, `docs/ai/packages/<pkg>/`.
 - **Rust workspace (`crates/`)** — top-level menu mirrors crate names: `docs/ai/<crate>/`.
@@ -179,8 +159,7 @@ That's the whole doc — ~15 lines, three clear hooks into the code, no copied s
 - **Paraphrased code.** If the doc is explaining control flow line-by-line, delete that and just point to the function.
 - **Essay-style prose.** Bullets and short paragraphs beat flowing prose for skim-reading.
 - **Phantom references.** Never invent a function or file name. If you're unsure, open the file and check.
-- **Over-splitting.** Eight three-line leaves are harder to navigate than one thirty-line doc. Err toward keeping related things together.
-- **Under-splitting.** A single 500-line `README.md` with everything is exactly what this skill is trying to replace.
+- **Over- or under-splitting.** Apply the split heuristic; both directions are covered there.
 - **Documenting aspirations.** Only describe what's in the code now.
 
 ## Final check before finishing

skills/delivery-handoff/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:delivery-handoff
 description: This skill should be used when the user asks for "a handoff prompt", "a prompt for codex/grok/claude", "something I can paste into another agent", or wants to continue tracked work in a different tool — and at any phase boundary of the cmk:delivery-pipeline skill when the operator prefers a different agent for the next phase.
-version: 0.2.0
+version: 0.2.1
 ---
 
 # Delivery Handoff
@@ -71,10 +71,11 @@ freely; completeness matters, sections don't):
    rule. For clusters: the issue → worktree/branch/base table plus where
    the orchestration plan lives and which wave is active. For a handoff
    mid-way through a phase-3 wave, additionally enumerate every live task
-   worktree — path, task branch, wave-base SHA, and join state (pending /
-   integrated / escalated), from the wave manifest in the ledger — and
-   state that task worktrees follow the wave protocol's retention rules,
-   never ad-hoc cleanup.
+   worktree — path, task branch, and wave-base SHA from the ledger's wave
+   manifest, plus each task's join status (pending / integrated /
+   escalated) reconstructed from the ledger's join and escalation records —
+   and state that task worktrees follow the wave protocol's retention
+   rules, never ad-hoc cleanup.
 3. **Read first** — ordered absolute paths: the phase skill(s) to follow,
    the tracking contract (`cmk:delivery-workflow`), the context-efficiency
    reference, the receiver's runtime binding

skills/delivery-pipeline/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:delivery-pipeline
 description: This skill should be used when the user asks to "work on", "deliver", "tackle", "pick up", or "implement" a tracker issue (TICKET-123), a list of issues, or a body of tracked work expected to finish without supervision — even if they never say "pipeline". Also use when handed a cluster of related issues, or a single issue whose surrounding cluster should be derived from tracker dependencies, expecting dependency-aware sequencing across worktrees.
-version: 0.2.0
+version: 0.3.0
 ---
 
 # Delivery Pipeline

skills/delivery-pipeline/references/engineering-principles.md

@@ -114,6 +114,31 @@ bookkeeping follows the human-decision-boundary rules above. In an
 unattended run, consultation applies only when it was requested up front —
 otherwise decide and record.
 
+## One code path across infra profiles
+
+Product, protocol, and core/shared logic are profile-invariant: identical
+across the local development stack and every deployed environment, with
+environment differences living only at named composition or
+materialization surfaces. In this pipeline that means:
+
+- **Spec/plan:** every environment difference is placed at a named
+  composition or materialization surface (launcher, IaC, config and
+  secret delivery, credential source). A spec that puts an environment
+  conditional inside product/protocol/core code is reworked before
+  implementation.
+- **Implementation:** prefer extending the local materialization of a
+  missing production element over branching the shared path around it.
+- **Review:** audit for profile leakage into shared code the same way
+  other architectural boundaries are audited.
+- **Evidence:** local-stack proof is the default execution evidence for
+  profile-invariant logic; environment-specific evidence is reserved for
+  the composition/materialization surfaces that own it. A shared-logic
+  defect first seen on a deployed environment is a parity failure to
+  root-cause, not a normal find.
+
+Where the repository declares its own infra-profile standard, that
+standard refines this rule and takes precedence.
+
 ## Production readiness
 
 Every change is designed, built, reviewed, and shipped as something that
@@ -174,12 +199,10 @@ what you don't otherwise hand them does not exist for them.
 
 The role definition carries model, effort, and preloaded skills —
 superpowers skills are named inline by whichever phase needs them, not
-chosen through a separate lookup. That leaves a delegation prompt only
-five things to state: task and file scope disjoint from every concurrently
-running subagent, skills to invoke by name, source identity or an
-instruction to refresh it, stop/escalation conditions, and the evidence
-artifact the subagent must write to scratch (what it read, ran, changed,
-or found, with file:line traces).
+chosen through a separate lookup. The delegation-prompt and return
+contracts are owned by `references/context-efficiency.md` § Delegation
+and returns; the required evidence artifact goes to scratch with what the
+subagent read, ran, changed, or found, with file:line traces.
 
 A subagent result without its evidence artifact is rejected and re-run.
 Evidence, not elapsed time, is how a hollow run is detected. Verify

skills/delivery-pipeline/references/worktree-wave-execution.md

@@ -51,7 +51,11 @@ Tasks may share a wave only when all three hold:
    member task IDs, the wave-base SHA, and each task's worktree path and
    branch name. This manifest is what a crashed run resumes from — without
    it, a resuming controller cannot tell an already-integrated task from one
-   that was never dispatched.
+   that was never dispatched. A resuming controller MUST check the ledger for
+   an incomplete wave manifest before any dispatch step and continue that
+   wave from its recorded wave-base SHA — never re-snapshot or pin a new
+   base while a manifest's wave is unfinished — and MUST verify each
+   leftover task branch forks from that recorded base before resuming it.
 3. **Create one worktree per task.**
    `git worktree add <path> -b <ticket-branch>--task-<N> <wave-base-sha>`,
    under the runtime's native worktree area — never an ad-hoc path — with the
@@ -82,8 +86,8 @@ Tasks may share a wave only when all three hold:
    so it starts warm: prefer a copy-on-write clone (`cp -c -R` on macOS/APFS,
    `cp --reflink=auto -R` on Linux — `auto` degrades to a plain copy on
    filesystems without reflink), fall back to a plain copy, and accept a cold
-   build only when copying is unattractive. Seed only into a destination that
-   does not exist yet: `cp -R` into an existing directory nests
+   build only when copying is unattractive. Seeding MUST target a destination
+   that does not exist yet: `cp -R` into an existing directory nests
    (`target/target/…`) instead of merging, silently leaving stale artifacts
    in charge — so a resumed worktree keeps the build state it already has and
    is never re-seeded. Seeding MUST happen while no build runs in the parent
@@ -108,10 +112,15 @@ task number):
    this task's work out of a shared branch; its remaining job is the overflow
    check. Build the package with the repo's review-package script where one
    exists (per `phase-3-execution.md`), giving each task an explicit per-task
-   output path and the task's declared scope and commits, so edits outside
-   the declared scope are appended to the package for review and surfaced as
-   a distinct non-zero exit, which the controller MUST handle as a scope
-   violation — never as a generic failure to retry blindly.
+   output path and the task's declared scope and its own commits. Commits a
+   controller-recorded peer pull cherry-picked from another task stay out of
+   that commit list: they are the source task's work, reviewed in its own
+   package, and listing them under this task's disjoint scope would surface
+   as a false scope violation (the scope filter already keeps their content
+   out of the package body). Edits outside the declared scope are appended
+   to the package for review and surfaced as a distinct non-zero exit, which
+   the controller MUST handle as a scope violation — never as a generic
+   failure to retry blindly.
 2. **Integrate — two moves, each from the worktree that owns the branch.**
    First, *inside the task worktree*, rebase the task branch onto the current
    ticket branch tip. Then, *from the ticket worktree*, advance the ticket
@@ -137,8 +146,8 @@ task number):
    branch (its commits are reachable from the ticket branch, so the delete
    loses nothing — never delete the branch before the merge). If removal
    refuses because the worktree is dirty, that is unreported, uncommitted
-   work — escalate to the worker's fix round instead of forcing; `--force`
-   is reserved for explicit abandonment. A failed or escalated task MUST
+   work — the controller MUST escalate to the worker's fix round instead of
+   forcing; `--force` is reserved for explicit abandonment. A failed or escalated task MUST
    retain its worktree and branch for the fix round. `git worktree prune`
    runs at phase close.
 
@@ -160,7 +169,11 @@ repeats if the controller has new WIP.
   and verify during A's rebase that the cherry-picked commits drop as
   patch-identical duplicates — if they survive (the patch drifted after the
   pick), treat it as a conflict and escalate rather than landing B's work
-  twice. Unmediated peer merging is prohibited — it recreates the
+  twice. If B fails, is escalated, or its work materially changes before its
+  own join, A's pick is stale: the controller MUST either rewrite A's task
+  branch to drop the picked commits (recorded in the ledger) or hold A's
+  join until B lands — never integrate A carrying commits whose source never
+  shipped. Unmediated peer merging is prohibited — it recreates the
   cross-contamination this protocol removes.
 
 ## Shared state has one writer

skills/delivery-spec-plan/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:delivery-spec-plan
 description: This skill should be used when the user asks for a "spec", "design", "implementation plan", or "how should we build this" for a tracker issue, after context intake for any non-trivial change, and as phase 2 of the cmk:delivery-pipeline skill.
-version: 0.2.0
+version: 0.2.1
 ---
 
 # Delivery Spec & Plan
@@ -26,10 +26,9 @@ the record; durable conclusions reach `docs/design/`, `docs/decisions/`, the
 tracker, and the PR description.
 
 Read `cmk:delivery-workflow` and `cmk:delivery-pipeline`'s context-efficiency
-reference before relying on the intake brief. Refresh mutable tracker,
-code-host, repository HEAD, and ancestry inputs before planning when their
-recorded source identity is no longer proven current — an intake brief
-cannot authorize planning after continuity, scope, or provenance is lost.
+reference before relying on the intake brief — the brief is a capsule, and
+the context-efficiency continuity rules decide when mutable inputs must be
+refreshed before planning on them.
 
 Apply `cmk:delivery-pipeline`'s engineering-principles reference throughout:
 decide everything yourself, staff-level bar without overengineering, existing
@@ -127,9 +126,7 @@ them — an AC with no task is a hole in the plan, and so is a
 surface-inventory item with no covering task. Planning is the cheapest
 moment to find out a criterion will not land: if no task can honestly
 satisfy one, take its disposition now, on the issue, per `cmk:delivery-workflow`'s
-`references/acceptance-criteria.md`. A criterion carried into implementation
-on the hope it works out becomes a ship-time surprise, which is the same
-decision made later with worse options.
+`references/acceptance-criteria.md`.
 
 A plan whose tasks all serialize on one file is worth re-partitioning before
 it executes; sequential-by-accident is different from sequential-by-necessity,

skills/delivery-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:delivery-workflow
 description: This skill should be used when the user asks to "start tracked work", "reconcile the tracker", "check if this is ready to ship", "keep the issue useful", or "check acceptance criteria" — or needs the tracking contract every other delivery skill operates inside.
-version: 0.2.0
+version: 0.2.1
 ---
 
 # Delivery Workflow
@@ -121,10 +121,7 @@ Using Linear as your tracker? Read `references/linear.md`.
 | Splitting PR review across the issue and the PR | Keep it on one surface — the PR or the tracker's synced review thread |
 | Copying a deferred finding into several places | Link the review thread and the new follow-up issue |
 | Treating merge as delivery | Verify acceptance before the done state |
-| Leaving the AC checklist untouched all run | Tick each criterion as its proof lands, evidence reachable |
-| Checking a criterion because it feels done | Check it only against reachable proof; intent is not evidence |
-| Shrinking the AC to match what got built | Rescope explicitly, move removed criteria to a tracked successor, say why |
-| Delivering a narrow slice under a broad AC | Rewrite the AC to the honest outcome and track the remainder |
+| Shrinking the AC to match what got built | Rescope explicitly: successor tracked, description rewritten, reason recorded (`references/acceptance-criteria.md`) |
 | Trusting only auto-linking | Keep the issue ID in the branch and the PR body |
 | Treating the template as a form | Use any clear structure that serves the same review goals |
 | Claiming tests passed without proof | Include reproducible automation and its passing result |

skills/design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:design
 description: This skill should be used when the user asks "how should we build this", "design the backend", "update the architecture", "draft a system design", "create a feature spec", "spec out this feature", or discusses architecture, tech stack changes, component design, or infrastructure layout. Covers drafting, refining, or updating distilled design documents under docs/design/ — system-wide or per-feature — checking for conflicts with upstream requirements and recorded decisions.
-version: 0.4.0
+version: 0.5.0
 ---
 
 # Design

skills/design/references/design-conventions.md

@@ -13,7 +13,9 @@
 
 - **System-wide** — the whole platform: layers, dependency direction,
   component map, sub-system composition.
-- **Sub-system / track** — one product line or major component.
+- **Sub-system / track** — one product line or major component: its
+  responsibilities, protocols, and how it composes the shared core without
+  leaking into it.
 - **Feature-level** — one feature, scoped by a `Scope:` header.
 - Lower levels reference upward and never silently contradict the level
   above; conflicts are surfaced and resolved at the higher level.