@ikon85/agent-workflow-kit 0.29.1 → 0.31.0

package/.agents/skills/triage/SKILL.md

@@ -14,6 +14,30 @@ Every comment or issue posted to the issue tracker during triage **must** start
 > *This was generated by AI during triage.*
 ```
 
+## Required readiness preflight
+
+Before reading from or writing to the issue tracker, labels, or board, run:
+
+```sh
+node scripts/readiness.mjs check --skill triage --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent: continue with
+the existing triage flow and all of its confirmation gates. For a `blocked`
+verdict, stop without querying or mutating the issue tracker and report
+`Triage unavailable`, the exact state (`missing`, `pending`, `not-applicable`,
+or `invalid`), and the matching recovery path:
+
+- `issueTracker` → run `/setup-workflow`, then fill
+  `docs/agents/issue-tracker.md`.
+- `managedBoard` → run `/setup-workflow`, then configure
+  `docs/agents/board-sync.md`; `not-applicable` means this board-driven skill is
+  unavailable, not partially usable.
+- `triageLabels` → run `/setup-workflow`, then fill
+  `docs/agents/triage-labels.md`.
+
+Never guess a tracker, label, board, field, status, or fallback workflow.
+
 ## Reference docs
 
 - [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs

package/.agents/skills/verify-spike/SKILL.md

@@ -21,10 +21,29 @@ This is the "Verify First" rule with a runnable harness behind it: when you cann
 
 If the question is really "what should this be", it is not a verify-spike — those are open, not yes/no.
 
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before framing or running the spike, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill verify-spike --json
+```
+
+- `ready`: continue without a readiness message. Ready is silent.
+- `degraded`: keep the generic empirical spike active, omit only the inactive block `projectPlacement`, and emit exactly one concise summary: `Readiness degraded — inactive block projectPlacement (verifySpikeLayer: <state>). Run /setup-workflow, configure docs/agents/skills/verify-spike.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability plus the exact `/setup-workflow` recovery path.
+- Invalid is always visible: include the `invalid` capability state in the single summary and never treat it as an opt-out. Do not emit separate warnings later in the workflow.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectPlacement -->
+When `projectPlacement` is active, read `docs/agents/skills/verify-spike.md` and follow its project-specific harness-placement and import rules.
+<!-- readiness:end -->
+
 ## Steps
 
 1. **Frame one falsifiable question.** Write it down as a single sentence with a yes/no answer and the exact version/context it is scoped to — e.g. "Does `customType.mapFromDriverValue` run on `drizzle-orm@1.0.0-rc.3` + node-postgres?". Name what a YES vs a NO looks like in the output *before* you run anything.
-2. **Build the smallest harness that forces the answer.** Borrow the feedback-loop toolkit from `diagnose` Phase 1 — a one-call throwaway script, a fixture replay, a tiny HTTP/curl probe, a headless-browser assertion. Pick the cheapest one that touches the real thing (real lib version, real runtime, the actual DB read). One command to run; locate it in a clearly-throwaway path (`scratch/`, `*.spike.ts`). If a project layer exists at `docs/agents/skills/verify-spike.md`, follow its harness-placement/import rules — some repos need spikes inside a package dir so real imports resolve.
+2. **Build the smallest harness that forces the answer.** Borrow the feedback-loop toolkit from `diagnose` Phase 1 — a one-call throwaway script, a fixture replay, a tiny HTTP/curl probe, a headless-browser assertion. Pick the cheapest one that touches the real thing (real lib version, real runtime, the actual DB read). One command to run; locate it in a clearly-throwaway path (`scratch/`, `*.spike.ts`).
 3. **Run it and capture the proof.** Keep the raw output — the value, the error, the stack, the HTTP status. The verdict is only as good as the evidence pasted under it.
 4. **Record the verdict durably, with its evidence inline.** Yes/No + the proof (output snippet / `file:line` / version) + the date + the scope it was checked at. Sink it where the decision lives: an ADR, the issue body, the plan, or a PR comment. A verdict without inline evidence is just an unverified claim — keep the proof attached so a later reader does not have to re-run the spike to trust it.
 5. **Delete the harness.** The *answer* is the only keeper. Remove the spike code (or fold the proven fact into real code) so nothing throwaway rots in the repo.

package/.agents/skills/wrapup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wrapup
 disable-model-invocation: true
-"description": "Use ONLY when the user types /wrapup. Session-end \"land & clean\" for a finished feature/fix worktree — merges the open PR (= triggers prod deploy), kills the worktree dev server, removes the worktree + local branch, and fast-forwards the main checkout so main is current again, then sweeps merged-branch leftovers (local + stale remote whose PR is merged). If the slice isn't landed yet, it first makes it landable (Step 0): commits a dirty tree (after an .env/secret check), pushes, and opens the PR — reusing one if it already exists. User-triggered only (never auto-invoke, never hook). Aborts hard only on: not in a feature worktree, a detected .env/secret, a rejected push, a conflicting PR, or red (FAILURE) checks."
+"description": "Use ONLY when the user types /wrapup. Session-end \"land & clean\" for a finished feature/fix worktree — merges the open PR, kills the worktree dev server, removes the worktree + local branch, and fast-forwards the main checkout so main is current again, then sweeps merged-branch leftovers (local + stale remote whose PR is merged). If the slice isn't landed yet, it first makes it landable (Step 0): commits a dirty tree (after an .env/secret check), pushes, and opens the PR — reusing one if it already exists. User-triggered only (never auto-invoke, never hook). Aborts hard only on: not in a feature worktree, a detected .env/secret, a rejected push, a conflicting PR, or red (FAILURE) checks."
 ---
 
 # wrapup — land PR & tear down worktree
@@ -10,7 +10,11 @@ Trigger: user types `/wrapup` (optionally with a PR number). **Manual only** —
 
 ## ⚠ Spec context
 
-**Merging to `main` = prod deploy.** The agent never deploys on its own — the user's `/wrapup` input IS the explicit merge+deploy authorization for that run. Never call this skill from a hook, another skill, or autonomously. Deploy banner before the merge, no y/n confirmation (deliberate); the pre-flight hard stops are non-negotiable.
+The user's `/wrapup` input IS the explicit landing authorization for that run.
+It authorizes the normal merge flow whether Prod readiness is ready or degraded;
+it never authorizes the agent to invent or configure a deploy target. Never call
+this skill from a hook, another skill, or autonomously. There is no second merge
+confirmation; the pre-flight hard stops are non-negotiable.
 
 ## Execution model — script does mechanics, the agent does judgment
 
@@ -27,6 +31,17 @@ python3 scripts/wrapup-land.py preflight
 ```
 Hard stop (the only pure precondition): not in a feature worktree / on `main` — the script exits 1. The report carries everything the later steps need: dirty files, `.env` hits, secret-grep hits, issue + parent (leaf vs. anchor slice), existing PR + whether its body has a `**Retro:**` line, parsed `ANNAHMEN.md` drift lines, profile values (`retro_values`, `vor_bau`, remote-sweep switch).
 
+Then run:
+
+```bash
+node scripts/readiness.mjs check --skill wrapup --json
+```
+
+`prodTarget: ready` activates only `deployReport` below. `pending` or `missing`
+omits that block, emits exactly one concise note — `Prod readiness is pending or missing; deploy reporting omitted.` — and landing continues normally.
+`invalid` means malformed or divergent Prod evidence: STOP and report the
+conflicting instruction surfaces; never choose a target on the user's behalf.
+
 ### 2 · Retro gate (blocking, optional retro-exit — before anything is committed)
 One reminder, not a merge confirmation:
 > "Already ran a retro? **(a)** yes / continue → landing now. **(b)** you want one first → the retro starts now; afterwards, invoke `/wrapup` again — repo-file patches then travel in this PR."
@@ -72,10 +87,17 @@ One call covers: push → PR create/reuse (+ drift markers merged into the body)
 STOP → diagnose in the main conversation, fix, re-run `land` (an already-merged PR resumes at teardown).
 
 ### 6 · Post-merge (agent)
-- **Deploy banner**, one line: `⚠ PR #<pr> merged → main deploys (~7 min live).`
 - **Sibling propagation:** for each `drift_markers` entry in the land report, append the note to the target issue's `vor_bau` section + re-stamp its `plan_revision`. Log-based markers → **write directly, then show what was written where** (mandatory report — visibility moved from a pre-gate into the report, decision 2026-07-06); fallback candidates the user hasn't confirmed yet → confirm first. Program context widens the target set to unbuilt wave-stubs/leaves and the Program-PRD itself — same append-only mechanism. **Exception:** appends to the Program-PRD or unbuilt wave-stubs do **not** re-stamp `plan_revision` — that stays reserved for structural wave-plan edits via the `to-waves` escalation path; a mere drift note must not stale-block published stubs.
 - **Anchor close:** report says `anchor_complete: true` → `gh issue close <anchor> -c "Wave complete — all slices merged via PR #<pr>."` and verify board status Done. The guard keeps anchors away from every auto-close — this verified close is the only close path; without it the anchor stays silently open after the last slice. **Then re-run the upward propagation**: the land-time `program-sync` ran BEFORE this close, so on a wave-completing slice the Wellenplan still shows 🔄 and the Phasen-Gate stays unchecked — after the board shows Done, run `python3 scripts/board-sync.py program-sync <program-prd#>` once more (the report's `program_sync.program` names it; skip when the report says the parent is not a program). Board auto-rules can lag the close (Close→Done race) — verify Done first, that's what the token reads.
-- **Report**, concise, from the land JSON: PR merged · issue close (auto/manual) · worktree removed · branch deleted · sweep counts local/remote · anchor synced + complete/pending · program propagation (`program_sync`: Wellenplan refreshed / gates checked / skipped) · propagation writes (what → where) · `main` at `<sha>` · deploy running.
+- **Report**, concise, from the land JSON: PR merged · issue close (auto/manual) · worktree removed · branch deleted · sweep counts local/remote · anchor synced + complete/pending · program propagation (`program_sync`: Wellenplan refreshed / gates checked / skipped) · propagation writes (what → where) · `main` at `<sha>`.
+
+<!-- readiness:block deployReport -->
+- **Deploy-aware report:** read the coherent `## Prod` block; before merging,
+  state the configured deploy trigger and expected outcome. After merge, report
+  the configured target and its actual known state. Do not claim a deployment
+  is running or live unless the configured trigger and observed evidence prove
+  it; keep unknown timing explicit.
+<!-- readiness:end -->
 
 ## Out of scope
 - Live-verify / DoD: must happen **before** `/wrapup` — this skill lands, it does not verify.

package/.claude/skills/board-to-waves/SKILL.md

@@ -21,6 +21,20 @@ description: >-
 
 **Survey the board → cluster open issues by theme → anchor stub issues.** Systematizes how Welle F came about: first look at what's open and what fits together, then form thematic waves. Result lands durably as an anchor issue on the board (GitHub = SSOT), not as a chat list.
 
+<!-- readiness:required-preflight:start -->
+## 0. Required readiness preflight
+
+This is the first executable workflow step. From the project root, before any remote write or other `gh`/`board-sync.py` command, run this read-only check:
+
+```bash
+node scripts/readiness.mjs check --skill board-to-waves --json
+```
+
+- `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
+- `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `missing`, `pending`, and `invalid` remain distinct, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/board-to-waves`.** Do not fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/board-to-waves` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
+<!-- readiness:required-preflight:end -->
+
 ## Pipeline Position
 
 ```

package/.claude/skills/code-review/SKILL.md

@@ -16,7 +16,26 @@ A code-review compares one diff against **two independent axes** — Standards a
 | "Why is this broken / slow?" (root-cause of a known defect) | `diagnose` |
 | "Clean this up — reuse, simplify, cut waste." (no bug-hunting) | a dedicated simplification pass |
 
-## Preflight (fail-fast, before either axis starts)
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before the diff preflight or either review axis, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill code-review --json
+```
+
+- `ready`: continue without a readiness message. Ready is silent.
+- `degraded`: keep the generic two-axis review active, omit only the inactive block `projectEnrichment`, and emit exactly one concise summary: `Readiness degraded — inactive block projectEnrichment (codeReviewLayer: <state>). Run /setup-workflow, configure docs/agents/code-review.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability plus the exact `/setup-workflow` recovery path.
+- Invalid is always visible: include the `invalid` capability state in the single summary and never treat it as an opt-out. Do not emit separate warnings later in the workflow.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectEnrichment -->
+When `projectEnrichment` is active, read `docs/agents/code-review.md` first. Apply its project-specific guidance about which sources count and how this method relates to adjacent tools already running in the environment.
+<!-- readiness:end -->
+
+## Diff preflight (fail-fast, before either axis starts)
 
 1. **Fixed point** — whatever the requester names: a SHA, branch, tag, `main`, `HEAD~N`. Missing → ask; do not guess.
 2. **Three-dot diff against the merge-base** — `git diff <fixed-point>...HEAD` (three dots, not two — two dots diffs tip-to-tip and pulls in unrelated upstream changes), plus the commit list: `git log <fixed-point>..HEAD --oneline`.
@@ -24,7 +43,7 @@ A code-review compares one diff against **two independent axes** — Standards a
 
 ## Axis 1 — Standards
 
-**Sources.** This repo's own documented conventions: a root convention file (`CLAUDE.md`/`AGENTS.md`/`CONTRIBUTING.md` — whichever this repo uses), any per-package convention files in a monorepo, a `docs/conventions/` folder. If `docs/agents/code-review.md` exists (this skill's project layer, seeded by `/setup-workflow`), read it first — it names exactly which sources count here and how this method relates to any other review tooling already running in this environment. Absent that file, gather the sources yourself from the repo root before reviewing.
+**Sources.** This repo's own documented conventions: a root convention file (`CLAUDE.md`/`AGENTS.md`/`CONTRIBUTING.md` — whichever this repo uses), any per-package convention files in a monorepo, and a `docs/conventions/` folder. Gather these generic sources from the repo root before reviewing.
 
 **Plus a Fowler-smell baseline** (*Refactoring*, ch. 3) — applies even when the repo documents nothing. Each smell is a **judgment call** (flag as "possible X"), never a hard violation:
 
@@ -61,4 +80,4 @@ A code-review compares one diff against **two independent axes** — Standards a
 
 ## Relationship to adjacent review tooling
 
-This skill governs one thing: a diff/branch/PR review split into Standards vs. Spec. It is not the only review-shaped tool an environment may have — a pre-code plan-review loop, a security-specific audit, a pure reuse/simplification pass, or a dedicated reviewer subagent can all coexist with it; each stays its own axis, not a replacement for this one. If this repo has seeded `docs/agents/code-review.md`, it names the concrete adjacent tools and how they relate; absent that, treat any other review tool you find as complementary unless it explicitly says otherwise.
+This skill governs one thing: a diff/branch/PR review split into Standards vs. Spec. It is not the only review-shaped tool an environment may have — a pre-code plan-review loop, a security-specific audit, a pure reuse/simplification pass, or a dedicated reviewer subagent can all coexist with it; each stays its own axis, not a replacement for this one. Without active project enrichment, treat any other review tool you find as complementary unless it explicitly says otherwise.

package/.claude/skills/kit-update/SKILL.md

@@ -34,12 +34,30 @@ release contain the same artifact.
    `npm test` command there, and activates only a verified candidate. A staging
    or verification failure leaves the installed tree byte-identical.
 
+   The staged candidate also adopts the current readiness schema without
+   invoking `setup-workflow`: it preserves explicit readiness decisions and
+   legacy project evidence, and seeds only newly introduced safe project-layer
+   stubs whose destinations are absent. Those generated consumer-owned paths
+   are destination-race checked and activate or roll back in the same
+   transaction as kit files and the consumer manifest. Never create project
+   data, infer an external fact, or manufacture `pending`/`not-applicable` to
+   make a capability appear ready.
+
 3. Read the terminal report. `aktuell` proves a second run found no upstream
    delta. A conflict report names and counts every category and leaves every
    consumer file untouched. Follow its recommendation and resolve each named
    conflict manually; never auto-merge, delete a local edit, or silently choose
    the incoming copy.
 
+   Read all four availability categories alongside the file delta: newly
+   available skill core, newly degraded optional blocks, newly blocked skill
+   core, and still unresolved capability states. Missing readiness for genuinely
+   new behavior does not block a compatible kit update; only that behavior stays
+   unavailable. A compatible update must stop if it would make previously
+   available skill core unavailable. `--yes` answers only package reconciliation
+   questions and never supplies a readiness decision. Automated update pull
+   requests carry the same availability summary and remain manual-merge only.
+
    For each conflicted kit-shipped file, always ask the user whether the local
    edit is a generic improvement or project-specific; never decide or act
    automatically. For a generic improvement, offer to file an issue in the
@@ -74,4 +92,6 @@ release contain the same artifact.
 The update API reports `checking -> preview/awaiting_decision -> staging ->
 verifying -> applied | conflicted | failed | aborted`. `conflicted`, `failed`,
 and `aborted` never authorize partial activation. The existing manifest,
-three-way diff, and atomic-write seams remain the source of truth.
+three-way diff, and atomic-write seams remain the source of truth. A failure
+also names its transaction phase and whether consumer state stayed unchanged or
+was rolled back.

package/.claude/skills/local-ci/SKILL.md

@@ -20,6 +20,22 @@ live in the **project layer** for this skill (its `docs/agents/skills/local-ci.m
 seeded as an empty stub by `/setup-workflow` and filled per project). This
 skeleton names the two profiles generically; run the two your project layer names.
 
+## Required readiness preflight
+
+Before running a guard, hook, test, or any other project command, run:
+
+```sh
+node scripts/readiness.mjs check --skill local-ci --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent: continue with
+the existing gate and its safety rules. For a `blocked` verdict, stop without
+running any guessed command and report `Local CI unavailable`, the
+`localCiRecipe` state (`missing`, `pending`, `not-applicable`, or `invalid`),
+and one recovery path: run `/setup-workflow`, then fill
+`docs/agents/skills/local-ci.md` with the project's exact commands. Never infer
+commands from package scripts, hooks, CI configuration, or another repository.
+
 ## When
 
 - **Before opening ANY PR** → run the full local gate. Red → fix it, or defer a

package/.claude/skills/project-release/SKILL.md

@@ -9,6 +9,24 @@ Prepare a consumer-owned multi-package release through the kit's shared
 SemVer, preview, and transactional apply engine. This skill changes only the
 profiled version files. It does not commit, tag, push, publish, or merge.
 
+## Required readiness preflight
+
+Before previewing a release or changing any version file, run:
+
+```sh
+node scripts/readiness.mjs check --skill project-release --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent and hands
+execution to `scripts/project-release.mjs`; the helper remains the authority
+for preview, confirmation, validation, and transactional apply. For a
+`blocked` verdict, stop without invoking that helper or changing files and
+report `Project Release unavailable`, the `projectReleaseProfile` state
+(`missing`, `pending`, `not-applicable`, or `invalid`), and one recovery path:
+run `/setup-workflow`, then fill the `projectRelease` section in
+`docs/agents/workflow-capabilities.json`. Never infer packages, version files,
+tag prefixes, or versions.
+
 ## Profile contract
 
 Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and

package/.claude/skills/security-audit/SKILL.md

@@ -13,6 +13,24 @@ generic runbook structure ships as a template you copy and fill:
 your actual stack, and keep it as the checklist single source of truth. Read your
 filled runbook first.
 
+## Required readiness preflight
+
+Before reading application code, creating a tracking issue, launching either
+model, or writing audit scratch files, run:
+
+```sh
+node scripts/readiness.mjs check --skill security-audit --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent: continue with
+the existing two-model procedure and all human approval gates. For a `blocked`
+verdict, stop without starting an audit or mutating repository or remote state
+and report `Security Audit unavailable`, the `securityAuditRunbook` state
+(`missing`, `pending`, `not-applicable`, or `invalid`), and one recovery path:
+run `/setup-workflow`, then fill `docs/agents/skills/security-audit.md` and the
+project runbook it references. Never guess the stack, security scope, commands,
+tracking anchor, or board wiring.
+
 **Scope guard:** code + config only. Infrastructure (firewall, exposed ports,
 TLS, SSH, backups) is audited **separately** — an exposed database port beats any
 code fix. Keep the two audits apart.

package/.claude/skills/setup-workflow/SKILL.md

@@ -331,7 +331,36 @@ Seed `## Workflow` from [workflow-overview.md](./workflow-overview.md) when the
 
 > `wrapup` and live-verify reference where this project deploys (host, command, URL). It lives in the `## Prod` block of CLAUDE.md/AGENTS.md, not a separate file.
 
-Ask for the deploy target in plain terms (where does this ship, how is it deployed, what's the live URL?). Record it for the `## Prod` block (Write step). If the user has no deploy target, skip — do not invent one.
+First run `node scripts/readiness.mjs check --skill wrapup --json`. If
+`prodTarget` is `ready`, adopt the evidence, clear any superseded pending
+decision with `node scripts/readiness.mjs decision clear prodTarget`, and do
+not ask again. Malformed or divergent `## Prod` evidence is `invalid`: leave
+all instruction files untouched, show the conflict, and stop this section
+until the user resolves it.
+
+For a missing or pending target, ask where this ships, how it is deployed, and
+what the live URL is. Offer only the bounded choices permitted by the readiness
+catalog:
+
+- **Configure now** — collect a non-empty host/platform, deploy command or
+  trigger, and live URL. Preview the exact local `## Prod` replacement for
+  every applicable existing Claude/Codex instruction surface and obtain
+  approval before writing it. Any external mutation retains its own separate
+  preview and approval; approving the local block never approves repository,
+  hosting, DNS, or deployment changes.
+- **Configure later** — run
+  `node scripts/readiness.mjs decision set prodTarget pending`; create or alter
+  no `## Prod` block, and report exactly:
+  `wrapup.deployReport omitted (prodTarget pending)`.
+- **Not applicable** — offer only when the manifest catalog entry has
+  `allowNotApplicable: true`; record it with `readiness.mjs decision set` and
+  deactivate the dependent block (or the whole skill when the declaration
+  requires the capability). `prodTarget` does not permit this choice, so never
+  offer it for Prod.
+
+Ready and terminal `not-applicable` choices are not re-asked. A pending choice
+remains deliberately retryable so a later `setup-workflow` run can take the
+Configure-now path. Never invent a deploy target.
 
 ### 8b. Section H — Size-Profil (optional LoC-offender gate, non-interactive)
 
@@ -391,6 +420,14 @@ For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reco
 - If **neither** exists → ask the user which surface(s) to create (**default `CLAUDE.md`**), then write there.
 - If a `## Workflow` block already exists → skip it; this block is often repo-specific.
 - If an `## Agent skills` / `## Prod` block already exists → update its contents in-place; never duplicate or clobber surrounding user content.
+- For Configure now, apply the approved `## Prod` preview to every applicable
+  existing surface as one coherent local change. Preserve each file's
+  `## Workflow` and `## Agent skills` blocks byte-for-byte, including spacing,
+  and leave all unrelated setup blocks untouched. Re-read every written Prod
+  body and run `node scripts/readiness.mjs check --skill wrapup --json`; all
+  surfaces must agree and `activeBlocks` must be exactly `["deployReport"]`.
+  Only then clear a prior `prodTarget` decision. A partial write is not ready:
+  restore the previewed surface set before reporting the section complete.
 
 `## Workflow` block:
 
@@ -411,7 +448,7 @@ Use [workflow-overview.md](./workflow-overview.md) verbatim as the generic seed.
 [one-line summary — single- or multi-context]. See `docs/agents/domain.md`.
 ```
 
-`## Prod` block (only if Section F produced a deploy target):
+`## Prod` block (only if Section G's Configure-now path produced a deploy target):
 
 ```markdown
 ## Prod

package/.claude/skills/skill-manifest.json

@@ -1,8 +1,37 @@
 {
   "schema_version": 1,
   "description": "Public skill classification and publishing SSOT.",
+  "readiness": {
+    "contractVersion": 1,
+    "capabilities": {
+      "issueTracker": { "evidence": { "type": "sentinel", "paths": ["docs/agents/issue-tracker.md"], "allowLegacy": true } },
+      "triageLabels": { "evidence": { "type": "sentinel", "paths": ["docs/agents/triage-labels.md"], "allowLegacy": true } },
+      "managedBoard": { "allowNotApplicable": true, "evidence": { "type": "board-profile", "paths": ["docs/agents/board-sync.md"] } },
+      "specCompleteness": { "evidence": { "type": "sentinel", "paths": ["docs/conventions/spec-completeness.md"], "allowLegacy": true } },
+      "localCiRecipe": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/local-ci.md"], "allowLegacy": true } },
+      "projectReleaseProfile": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "validator": "project-release" } },
+      "securityAuditRunbook": { "evidence": { "type": "runbook-reference", "paths": ["docs/agents/skills/security-audit.md"], "allowLegacy": true } },
+      "prodTarget": { "evidence": { "type": "prod-section", "paths": ["CLAUDE.md", "AGENTS.md"] } },
+      "orchestrateWaveRecipe": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/orchestrate-wave.md"], "allowLegacy": true } },
+      "specCritiqueLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/spec-self-critique.md"], "allowLegacy": true } },
+      "codeReviewLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/code-review.md"], "allowLegacy": true } },
+      "verifySpikeLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/verify-spike.md"], "allowLegacy": true } },
+      "auditSkillsLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/audit-skills.md"], "allowLegacy": true } },
+      "worktreeRecoveryLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/git-worktree-recover.md"], "allowLegacy": true } },
+      "domainDocs": { "evidence": { "type": "sentinel", "paths": ["docs/agents/domain.md"], "allowLegacy": true } },
+      "censusChoice": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["census"] } },
+      "memoryLifecycle": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["memoryLifecycle"] } },
+      "worktreeLifecycle": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["worktreeLifecycle"] } },
+      "workflowAdvisories": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["workflowAdvisories"] } },
+      "safetyGuardrails": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["safetyGuardrails"] } },
+      "workflowSummary": { "evidence": { "type": "nonempty", "paths": ["CLAUDE.md", "AGENTS.md"] } },
+      "locProfile": { "evidence": { "type": "json", "paths": ["docs/agents/max-lines-allowlist.json"] } },
+      "kitOriginHint": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["kitOriginHint"] } }
+    }
+  },
   "skills": {
     "to-prd": {
+      "readiness": { "required": ["issueTracker", "managedBoard"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -13,6 +42,7 @@
       "provenance": "matt-pocock"
     },
     "to-issues": {
+      "readiness": { "required": ["issueTracker", "managedBoard", "specCompleteness"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -51,6 +81,7 @@
       "provenance": "own"
     },
     "wrapup": {
+      "readiness": { "optionalBlocks": { "deployReport": "prodTarget" } },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -61,6 +92,7 @@
       "provenance": "own"
     },
     "verify-spike": {
+      "readiness": { "optionalBlocks": { "projectPlacement": "verifySpikeLayer" } },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -81,6 +113,7 @@
       "provenance": "own"
     },
     "spec-self-critique": {
+      "readiness": { "optionalBlocks": { "projectEnrichment": "specCritiqueLayer" } },
       "class": "generic",
       "publish": true,
       "surfaces": [
@@ -90,6 +123,7 @@
       "provenance": "own"
     },
     "code-review": {
+      "readiness": { "optionalBlocks": { "projectEnrichment": "codeReviewLayer" } },
       "class": "generic",
       "publish": true,
       "surfaces": [
@@ -118,6 +152,7 @@
       "provenance": "own"
     },
     "board-to-waves": {
+      "readiness": { "required": ["issueTracker", "managedBoard"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -138,6 +173,7 @@
       "provenance": "own"
     },
     "to-waves": {
+      "readiness": { "required": ["issueTracker", "managedBoard", "specCompleteness"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -187,6 +223,7 @@
       "provenance": "matt-pocock"
     },
     "triage": {
+      "readiness": { "required": ["issueTracker", "managedBoard", "triageLabels"] },
       "class": "vendored",
       "publish": true,
       "entryPoint": true,
@@ -327,6 +364,7 @@
       "provenance": "own"
     },
     "audit-skills": {
+      "readiness": { "optionalBlocks": { "projectChecks": "auditSkillsLayer" } },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -337,6 +375,7 @@
       "provenance": "own"
     },
     "local-ci": {
+      "readiness": { "required": ["localCiRecipe"] },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -347,6 +386,10 @@
       "provenance": "own"
     },
     "orchestrate-wave": {
+      "readiness": {
+        "required": ["issueTracker", "managedBoard"],
+        "optionalBlocks": { "projectRecipe": "orchestrateWaveRecipe" }
+      },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -357,6 +400,7 @@
       "provenance": "own"
     },
     "git-worktree-recover": {
+      "readiness": { "optionalBlocks": { "projectRecovery": "worktreeRecoveryLayer" } },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -367,6 +411,7 @@
       "provenance": "own"
     },
     "security-audit": {
+      "readiness": { "required": ["securityAuditRunbook"] },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -388,6 +433,7 @@
       "provenance": "own"
     },
     "project-release": {
+      "readiness": { "required": ["projectReleaseProfile"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,

package/.claude/skills/spec-self-critique/SKILL.md

@@ -11,15 +11,24 @@ A portable, structural self-review pass over a freshly written spec/plan. The **
 
 - After a spec was written/edited (a `SPEC.md` / `PLAN.md`, or a spec/design doc), BEFORE the user-review gate.
 
-## Step 0 — Project-layer probe
+## Readiness preflight — first
 
-First, check whether a project layer exists: from the project root, look for `docs/agents/skills/spec-self-critique.md`.
+<!-- readiness:optional-preflight:start -->
+Before any other step, run this once from the project root:
 
-- **Present** → **full pass**: run the 12 generic checks AND apply the per-point enrichment that file defines (incidents, grep patterns, extra sub-checks).
-- **Absent** → **base pass**: run the 12 generic checks only, then add this one-line warning to the summary:
-  > ⚠ No project layer found (`docs/agents/skills/spec-self-critique.md`) — only the generic base checks ran. `/setup-workflow` creates the layer; it fills in project-specific content via `/retro`.
+```bash
+node scripts/readiness.mjs check --skill spec-self-critique --json
+```
+
+- `ready`: continue without a readiness message. Ready is silent.
+- `degraded`: keep the generic 12-point critique active, omit only the inactive block `projectEnrichment`, and emit exactly one concise summary: `Readiness degraded — inactive block projectEnrichment (specCritiqueLayer: <state>). Run /setup-workflow, configure docs/agents/skills/spec-self-critique.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability plus the exact `/setup-workflow` recovery path.
+- Invalid is always visible: include the `invalid` capability state in the single summary and never treat it as an opt-out. Do not emit separate warnings later in the workflow.
+<!-- readiness:optional-preflight:end -->
 
-> **Routing — keep this skeleton clean.** Project-specific checks, incidents, and grep patterns belong in the project layer (`docs/agents/skills/spec-self-critique.md`), **NOT here**. `/retro` appends new project-specific lore to the project layer, never into this generic skeleton.
+<!-- readiness:block projectEnrichment -->
+When `projectEnrichment` is active, read `docs/agents/skills/spec-self-critique.md` and apply its per-point enrichment, including project-specific incidents, grep patterns, conventions, and extra sub-checks. Project-specific checks belong in that layer, **not here**; `/retro` appends new project-specific lore there rather than into this generic skeleton.
+<!-- readiness:end -->
 
 ## Altitude — a portable kit concept
 
@@ -63,7 +72,7 @@ Self-Critique complete — <N> corrections:
 - ...
 ```
 
-or, if none were needed: `Self-Critique complete — no corrections needed.` (append the Step-0 layer-absent warning if it applied). THEN ask the user-review question.
+or, if none were needed: `Self-Critique complete — no corrections needed.` THEN ask the user-review question.
 
 ## The 12-point checklist
 

package/.claude/skills/to-issues/SKILL.md

@@ -9,7 +9,19 @@ description: Break a plan, spec, or PRD into independently-grabbable issues on t
 
 Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-workflow` if not.
+<!-- readiness:required-preflight:start -->
+## 0. Required readiness preflight
+
+This is the first executable workflow step. From the project root, before any remote write or other `gh`/`board-sync.py` command, run this read-only check:
+
+```bash
+node scripts/readiness.mjs check --skill to-issues --json
+```
+
+- `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
+- `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `issueTracker`, `managedBoard`, and `specCompleteness` failures — including distinct `missing`, `pending`, and `invalid` states — stay visible, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-issues`.** Do not fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/to-issues` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
+<!-- readiness:required-preflight:end -->
 
 ## Process
 

package/.claude/skills/to-prd/SKILL.md

@@ -10,6 +10,20 @@ description: "Turn a locked plan (PLAN.md in the worktree, conversation context,
 
 Takes an **already-locked plan** and publishes it as a **Draft-PRD issue**. **Never invents requirements** — only synthesizes what's already decided. Pipeline: `board-to-waves → grill(-with-docs) → to-prd → to-issues`. The **grill sits upstream**; to-prd writes the PRD after the grill. **Slicing + promotion to an anchor (cluster/Wave, child link) = `to-issues`** (future), not here.
 
+<!-- readiness:required-preflight:start -->
+## 0. Required readiness preflight
+
+This is the first executable workflow step. From the project root, before any remote write or other `gh`/`board-sync.py` command, run this read-only check:
+
+```bash
+node scripts/readiness.mjs check --skill to-prd --json
+```
+
+- `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
+- `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `missing`, `pending`, and `invalid` remain distinct, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-prd`.** Do not fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/to-prd` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
+<!-- readiness:required-preflight:end -->
+
 Board constants (project node, field/status IDs) + helpers live **consumer-side**: read `docs/agents/board-sync.md` from the project root + use the helper `scripts/board-sync.py` (missing → `/setup-workflow` scaffolds the project layer). Issue body **always** via `--body-file` (inline `--body` with backticks/parens crashes bash).
 
 ## 1. Input — source-agnostic