@ikon85/agent-workflow-kit 0.31.0 → 0.32.0

package/.agents/skills/audit-skills/SKILL.md

@@ -23,6 +23,35 @@ skills the other steps rely on drift, and nothing fixes them unless a recipe doe
 Not for: rewriting a domain skill's content on demand (that is the skill itself),
 or auditing application code (a code review or a diagnosis does that).
 
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before enumerating skills, launching research subagents, or editing any skill,
+run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill audit-skills --json
+```
+
+- `ready`: continue silently with the generic audit and the active
+  `projectChecks` block.
+- `degraded`: keep the generic audit active, omit only `projectChecks`, and emit
+  exactly one concise summary: `Readiness degraded — inactive block
+  projectChecks (auditSkillsLayer: <state>). Run /setup-workflow, configure
+  docs/agents/skills/audit-skills.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability
+  plus the exact `/setup-workflow` recovery path.
+- Invalid evidence is always visible in that one summary; never interpret it as
+  an opt-out or invent project checks.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectChecks -->
+When `projectChecks` is active, read
+`docs/agents/skills/audit-skills.md` and apply its concrete class assignments,
+project-specific guard commands, and drift checks in addition to the generic
+recipe below.
+<!-- readiness:end -->
+
 ## Standing guards (run without this audit)
 
 Two automatic nets catch the most common drift classes before an audit — this
@@ -31,7 +60,7 @@ recipe complements them, it does not replace them:
 1. **A skill-sync test** — for any un-guessable enumeration a skill documents (a
    status→bucket map, a design-token list), a test parses the value out of the
    SKILL.md and asserts equality with the code constant. Drift breaks the build.
-   Your project layer names the concrete tests.
+   Run the concrete tests available in the repository.
 2. **The drift-hint hook** (`.claude/hooks/skill-drift-hint.py`) + a per-skill
    `SOURCES.txt`: at SessionStart it flags any skill whose declared source file
    is newer in git than its SKILL.md.
@@ -79,8 +108,9 @@ plus the `SOURCES.txt` files. Sort every skill into one of three classes:
    scripts or hooks with no `SOURCES.txt` and no hook net. No hook warns, so
    re-check them manually each audit.
 
-Your project layer assigns each concrete skill to a class — a completeness gate
-catches the next new skill that would otherwise stay invisible.
+Derive each concrete skill's class from the manifest, its `SOURCES.txt`, and the
+repository surfaces — a completeness gate catches the next new skill that would
+otherwise stay invisible.
 
 ### 2. Audit in parallel — one subagent per skill
 
@@ -129,8 +159,7 @@ alongside the Claude source), sync the mirror in the **same** change — otherwi
 the second surface rots silently. Mirror the body, but preserve each surface's
 own frontmatter: a mirror's `description` may be deliberately condensed, so never
 blind-copy the whole file over it. A `SOURCES.txt` is a plain anchor list and can
-be mirrored verbatim. Your project layer names the surfaces and the exact
-transform.
+be mirrored verbatim. Use the repository's declared surfaces and exact transform.
 
 ## Done
 

package/.agents/skills/git-worktree-recover/SKILL.md

@@ -20,11 +20,36 @@ discipline and its guards) didn't stop it.
 
 ## Precondition
 
-If your project has a prevention layer — a SessionStart warning on active
-worktrees, a pre-edit guard that blocks edits on the wrong branch — this skill
-handles the case where that layer did NOT prevent a misplaced commit. Your project
-layer names those guards (`docs/agents/skills/git-worktree-recover.md`, seeded as
-an empty stub by `/setup-workflow`).
+This generic recovery remains usable whether or not the project has prevention
+guards or a custom worktree setup command.
+
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before assessing refs or moving a branch, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill git-worktree-recover --json
+```
+
+- `ready`: continue silently with generic recovery and the active
+  `projectRecovery` block.
+- `degraded`: keep generic reflog recovery active, omit only
+  `projectRecovery`, and emit exactly one concise summary: `Readiness degraded
+  — inactive block projectRecovery (worktreeRecoveryLayer: <state>). Run
+  /setup-workflow, configure docs/agents/skills/git-worktree-recover.md, then
+  rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability
+  plus the exact `/setup-workflow` recovery path.
+- Invalid evidence is always visible in that one summary; never interpret it as
+  an opt-out or invent a project command.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectRecovery -->
+When `projectRecovery` is active, read
+`docs/agents/skills/git-worktree-recover.md` and apply its named prevention
+guards and exact worktree setup command around the generic recovery below.
+<!-- readiness:end -->
 
 ---
 
@@ -124,16 +149,12 @@ it.
 
 ## Phase 5 — Set up a worktree
 
-Set the recovered branch up cleanly in its own worktree. If your project has a
-worktree-setup command, use it (it typically runs `git worktree add`, installs
-deps and copies env files); otherwise:
+Set the recovered branch up cleanly in its own worktree. The generic fallback is:
 
 ```bash
 git worktree add <path> <recovered-branch>
 ```
 
-Your project layer names the exact command and what it copies.
-
 **Verify after setup:**
 
 ```bash

package/.agents/skills/orchestrate-wave/SKILL.md

@@ -13,13 +13,46 @@ correctly, AFK. Subagents BUILD; **you** integrate + verify + land.
 The anchor, its sub-issues and the locked plan doc contain the verbatim contracts
 you must NOT paraphrase.
 
-> **Phase 0 probes a project layer.** Concrete tooling — exact test/verify
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before reading from the issue tracker, claiming a wave, creating worktrees, or
+making any local or remote mutation, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill orchestrate-wave --json
+```
+
+- `ready`: continue silently with the required tracker/board context and the
+  active `projectRecipe` block.
+- `degraded`: required tracker and managed-board evidence is ready, so keep the
+  complete generic orchestration fallback active, omit only `projectRecipe`,
+  and emit exactly one concise summary: `Readiness degraded — inactive block
+  projectRecipe (orchestrateWaveRecipe: <state>); using the generic
+  orchestration fallback. Run /setup-workflow, configure
+  docs/agents/skills/orchestrate-wave.md, then rerun this skill.`
+- `blocked`: `STOP` before tracker access, dispatch, claims, worktrees, or other
+  mutation. Report `issueTracker=<state>` and `managedBoard=<state>`, then give
+  exactly one recovery path: **Run `/setup-workflow`, then rerun
+  `/orchestrate-wave`.** Never fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/orchestrate-wave` is
+  inapplicable without a managed board. This is a terminal project decision,
+  not invalid evidence and not a partially active mode.
+- Invalid evidence is always visible and never treated as an opt-out.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectRecipe -->
+> **Phase 0 consumes the active project recipe.** Concrete tooling — exact test/verify
 > commands, a DB/tunnel setup, a headless login recipe, brand checks, deploy
 > lockstep — is project-specific and lives in a **project layer** this skill reads
 > at runtime, not in this skeleton. The skeleton names the layer's sections
 > (`§Setup`, `§Builder Commands`, `§Builder Hard Rules`, `§Integration Suites`,
 > `§Verify Recipe`, `§Headless Login`, `§Landing`) and falls back to generic
 > instructions when the layer is absent. See **Phase 0**.
+>
+> When `projectRecipe` is active, read the filled project layer before applying
+> any phase-specific command below.
+<!-- readiness:end -->
 
 ## Standing rules (all phases)
 
@@ -59,15 +92,11 @@ you must NOT paraphrase.
 1. **Read everything**: the anchor body, every sub-issue body (each has a Handoff
    block: scope, blast-radius, live-verify, PR line), and the locked plan /
    plan-review doc in the planning worktree (file-exact).
-2. **Probe the project layer.** Read the project layer doc for this skill (the
-   consumer's `docs/agents/skills/orchestrate-wave.md` or the path your project
-   uses). If its `§`-sections carry **filled** content, follow the project recipe
-   wherever a phase below points at a `§`-section. If the file is only a
-   `setup-workflow` sentinel stub (empty headings, no real content) or absent,
-   treat the layer as **ABSENT** → use the generic fallback in each phase and warn
-   **once** that `/setup-workflow` plus project maintenance fill the layer (the
-   commands/tunnel/login can't be guessed). Never treat an empty heading as a
-   verify recipe.
+2. **Select exact commands or the generic fallback.** If the readiness result
+   activated `projectRecipe`, use the loaded filled recipe wherever a phase below
+   points at a `§`-section. Otherwise use each phase's generic fallback; the
+   preflight's single degraded summary is the only warning. Never guess a project
+   command, tunnel, login, or verify recipe.
 3. **Preflight — refuse a wave already in flight, otherwise claim it.** Before
    dispatch, inspect all three same-machine collision signals: **(a)** an existing
    `wave-active/<anchor>` tag; **(b)** any slice branch ahead of the wave's current
@@ -88,10 +117,10 @@ you must NOT paraphrase.
    tunnel or service the live-verify depends on. Absent layer → start whatever your
    live-verify environment requires before Phase 4.
 
-**Done when:** anchor + every sub-issue + plan read · project layer probed
-(filled → project recipe; stub/absent → generic + one-time warning) · preflight
-clean + this run's local claim planted · wave branch ff'd to `origin/main` + deps
-installed · project setup steps running.
+**Done when:** anchor + every sub-issue + plan read · readiness result consumed
+(active `projectRecipe` → exact recipe; inactive → generic fallback) · collision
+preflight clean + this run's local claim planted · wave branch ff'd to
+`origin/main` + deps installed · project setup steps running.
 
 ## Phase 1 — Disjointness recon (the load-bearing step)
 

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

@@ -23,6 +23,35 @@ skills the other steps rely on drift, and nothing fixes them unless a recipe doe
 Not for: rewriting a domain skill's content on demand (that is the skill itself),
 or auditing application code (a code review or a diagnosis does that).
 
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before enumerating skills, launching research subagents, or editing any skill,
+run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill audit-skills --json
+```
+
+- `ready`: continue silently with the generic audit and the active
+  `projectChecks` block.
+- `degraded`: keep the generic audit active, omit only `projectChecks`, and emit
+  exactly one concise summary: `Readiness degraded — inactive block
+  projectChecks (auditSkillsLayer: <state>). Run /setup-workflow, configure
+  docs/agents/skills/audit-skills.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability
+  plus the exact `/setup-workflow` recovery path.
+- Invalid evidence is always visible in that one summary; never interpret it as
+  an opt-out or invent project checks.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectChecks -->
+When `projectChecks` is active, read
+`docs/agents/skills/audit-skills.md` and apply its concrete class assignments,
+project-specific guard commands, and drift checks in addition to the generic
+recipe below.
+<!-- readiness:end -->
+
 ## Standing guards (run without this audit)
 
 Two automatic nets catch the most common drift classes before an audit — this
@@ -31,7 +60,7 @@ recipe complements them, it does not replace them:
 1. **A skill-sync test** — for any un-guessable enumeration a skill documents (a
    status→bucket map, a design-token list), a test parses the value out of the
    SKILL.md and asserts equality with the code constant. Drift breaks the build.
-   Your project layer names the concrete tests.
+   Run the concrete tests available in the repository.
 2. **The drift-hint hook** (`.claude/hooks/skill-drift-hint.py`) + a per-skill
    `SOURCES.txt`: at SessionStart it flags any skill whose declared source file
    is newer in git than its SKILL.md.
@@ -79,8 +108,9 @@ plus the `SOURCES.txt` files. Sort every skill into one of three classes:
    scripts or hooks with no `SOURCES.txt` and no hook net. No hook warns, so
    re-check them manually each audit.
 
-Your project layer assigns each concrete skill to a class — a completeness gate
-catches the next new skill that would otherwise stay invisible.
+Derive each concrete skill's class from the manifest, its `SOURCES.txt`, and the
+repository surfaces — a completeness gate catches the next new skill that would
+otherwise stay invisible.
 
 ### 2. Audit in parallel — one subagent per skill
 
@@ -129,8 +159,7 @@ alongside the Claude source), sync the mirror in the **same** change — otherwi
 the second surface rots silently. Mirror the body, but preserve each surface's
 own frontmatter: a mirror's `description` may be deliberately condensed, so never
 blind-copy the whole file over it. A `SOURCES.txt` is a plain anchor list and can
-be mirrored verbatim. Your project layer names the surfaces and the exact
-transform.
+be mirrored verbatim. Use the repository's declared surfaces and exact transform.
 
 ## Done
 

package/.claude/skills/git-worktree-recover/SKILL.md

@@ -26,11 +26,36 @@ discipline and its guards) didn't stop it.
 
 ## Precondition
 
-If your project has a prevention layer — a SessionStart warning on active
-worktrees, a pre-edit guard that blocks edits on the wrong branch — this skill
-handles the case where that layer did NOT prevent a misplaced commit. Your project
-layer names those guards (`docs/agents/skills/git-worktree-recover.md`, seeded as
-an empty stub by `/setup-workflow`).
+This generic recovery remains usable whether or not the project has prevention
+guards or a custom worktree setup command.
+
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before assessing refs or moving a branch, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill git-worktree-recover --json
+```
+
+- `ready`: continue silently with generic recovery and the active
+  `projectRecovery` block.
+- `degraded`: keep generic reflog recovery active, omit only
+  `projectRecovery`, and emit exactly one concise summary: `Readiness degraded
+  — inactive block projectRecovery (worktreeRecoveryLayer: <state>). Run
+  /setup-workflow, configure docs/agents/skills/git-worktree-recover.md, then
+  rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability
+  plus the exact `/setup-workflow` recovery path.
+- Invalid evidence is always visible in that one summary; never interpret it as
+  an opt-out or invent a project command.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectRecovery -->
+When `projectRecovery` is active, read
+`docs/agents/skills/git-worktree-recover.md` and apply its named prevention
+guards and exact worktree setup command around the generic recovery below.
+<!-- readiness:end -->
 
 ---
 
@@ -130,16 +155,12 @@ it.
 
 ## Phase 5 — Set up a worktree
 
-Set the recovered branch up cleanly in its own worktree. If your project has a
-worktree-setup command, use it (it typically runs `git worktree add`, installs
-deps and copies env files); otherwise:
+Set the recovered branch up cleanly in its own worktree. The generic fallback is:
 
 ```bash
 git worktree add <path> <recovered-branch>
 ```
 
-Your project layer names the exact command and what it copies.
-
 **Verify after setup:**
 
 ```bash

package/.claude/skills/orchestrate-wave/SKILL.md

@@ -21,13 +21,46 @@ correctly, AFK. Subagents BUILD; **you** integrate + verify + land.
 The anchor, its sub-issues and the locked plan doc contain the verbatim contracts
 you must NOT paraphrase.
 
-> **Phase 0 probes a project layer.** Concrete tooling — exact test/verify
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before reading from the issue tracker, claiming a wave, creating worktrees, or
+making any local or remote mutation, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill orchestrate-wave --json
+```
+
+- `ready`: continue silently with the required tracker/board context and the
+  active `projectRecipe` block.
+- `degraded`: required tracker and managed-board evidence is ready, so keep the
+  complete generic orchestration fallback active, omit only `projectRecipe`,
+  and emit exactly one concise summary: `Readiness degraded — inactive block
+  projectRecipe (orchestrateWaveRecipe: <state>); using the generic
+  orchestration fallback. Run /setup-workflow, configure
+  docs/agents/skills/orchestrate-wave.md, then rerun this skill.`
+- `blocked`: `STOP` before tracker access, dispatch, claims, worktrees, or other
+  mutation. Report `issueTracker=<state>` and `managedBoard=<state>`, then give
+  exactly one recovery path: **Run `/setup-workflow`, then rerun
+  `/orchestrate-wave`.** Never fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/orchestrate-wave` is
+  inapplicable without a managed board. This is a terminal project decision,
+  not invalid evidence and not a partially active mode.
+- Invalid evidence is always visible and never treated as an opt-out.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectRecipe -->
+> **Phase 0 consumes the active project recipe.** Concrete tooling — exact test/verify
 > commands, a DB/tunnel setup, a headless login recipe, brand checks, deploy
 > lockstep — is project-specific and lives in a **project layer** this skill reads
 > at runtime, not in this skeleton. The skeleton names the layer's sections
 > (`§Setup`, `§Builder Commands`, `§Builder Hard Rules`, `§Integration Suites`,
 > `§Verify Recipe`, `§Headless Login`, `§Landing`) and falls back to generic
 > instructions when the layer is absent. See **Phase 0**.
+>
+> When `projectRecipe` is active, read the filled project layer before applying
+> any phase-specific command below.
+<!-- readiness:end -->
 
 ## Standing rules (all phases)
 
@@ -67,15 +100,11 @@ you must NOT paraphrase.
 1. **Read everything**: the anchor body, every sub-issue body (each has a Handoff
    block: scope, blast-radius, live-verify, PR line), and the locked plan /
    plan-review doc in the planning worktree (file-exact).
-2. **Probe the project layer.** Read the project layer doc for this skill (the
-   consumer's `docs/agents/skills/orchestrate-wave.md` or the path your project
-   uses). If its `§`-sections carry **filled** content, follow the project recipe
-   wherever a phase below points at a `§`-section. If the file is only a
-   `setup-workflow` sentinel stub (empty headings, no real content) or absent,
-   treat the layer as **ABSENT** → use the generic fallback in each phase and warn
-   **once** that `/setup-workflow` plus project maintenance fill the layer (the
-   commands/tunnel/login can't be guessed). Never treat an empty heading as a
-   verify recipe.
+2. **Select exact commands or the generic fallback.** If the readiness result
+   activated `projectRecipe`, use the loaded filled recipe wherever a phase below
+   points at a `§`-section. Otherwise use each phase's generic fallback; the
+   preflight's single degraded summary is the only warning. Never guess a project
+   command, tunnel, login, or verify recipe.
 3. **Preflight — refuse a wave already in flight, otherwise claim it.** Before
    dispatch, inspect all three same-machine collision signals: **(a)** an existing
    `wave-active/<anchor>` tag; **(b)** any slice branch ahead of the wave's current
@@ -96,10 +125,10 @@ you must NOT paraphrase.
    tunnel or service the live-verify depends on. Absent layer → start whatever your
    live-verify environment requires before Phase 4.
 
-**Done when:** anchor + every sub-issue + plan read · project layer probed
-(filled → project recipe; stub/absent → generic + one-time warning) · preflight
-clean + this run's local claim planted · wave branch ff'd to `origin/main` + deps
-installed · project setup steps running.
+**Done when:** anchor + every sub-issue + plan read · readiness result consumed
+(active `projectRecipe` → exact recipe; inactive → generic fallback) · collision
+preflight clean + this run's local claim planted · wave branch ff'd to
+`origin/main` + deps installed · project setup steps running.
 
 ## Phase 1 — Disjointness recon (the load-bearing step)
 

package/README.md

@@ -348,6 +348,15 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 
 ## Release notes
 
+### 0.32.0
+
+- changed: `.agents/skills/audit-skills/SKILL.md`
+- changed: `.agents/skills/git-worktree-recover/SKILL.md`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/audit-skills/SKILL.md`
+- changed: `.claude/skills/git-worktree-recover/SKILL.md`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+
 ### 0.31.0
 
 - changed: `.agents/skills/board-to-waves/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.31.0",
+  "kitVersion": "0.32.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -27,7 +27,7 @@
       "ownerSkill": "audit-skills",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "f99bfc88bf23ad8279583653bdd7b63dcdcff010227258e4adf9e8df69384f7f",
+      "sha256": "662c4dec0c03716c468f202f73f52140ceba84e092873e6619692dde6d7ed0f2",
       "mode": 420,
       "origin": "kit"
     },
@@ -197,7 +197,7 @@
       "ownerSkill": "git-worktree-recover",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "71e043456586a59ddb83fb3fb1f98c8c269cd7575ade8616238bdb7e07fba4ba",
+      "sha256": "1628f47a5b5f71b7596ec070c8f038a3ce98abe007fce1b7f5c21ea40858124d",
       "mode": 420,
       "origin": "kit"
     },
@@ -417,7 +417,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "39c0dd4d6f7663ab9a3602aab2869a881497604ca12f53f6ba0ca7debb0a4157",
+      "sha256": "7a94293b7db49f42497d34e6ae0fe9992ab1c770ae0766557618818d6d671c50",
       "mode": 420,
       "origin": "kit"
     },
@@ -1189,7 +1189,7 @@
       "ownerSkill": "audit-skills",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "80ab0f1910914f4bcb375bf63aa66a1297a0b873082d7cc4f386d0d931e6015f",
+      "sha256": "dce7c13e9b9c2eb6fe9028f69fe2fe2d48ad50546327c9d9c1232191425f1b7c",
       "mode": 420,
       "origin": "kit"
     },
@@ -1419,7 +1419,7 @@
       "ownerSkill": "git-worktree-recover",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "435c3a32a0c31dbefc774d8f6caa30cae9f23026930292ea0c364d2115ed3e52",
+      "sha256": "3251c8db671286330e48748719e05ee3fdc0555d93d61d7fee3fc0e0d2868e92",
       "mode": 420,
       "origin": "kit"
     },
@@ -1699,7 +1699,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "20a972d7c13f059b1fda4daaeb77da777c898620bf9ec6bf6dd19c31b7e41d90",
+      "sha256": "9690ec772a99131c225037dd4bca884e899c133a8e460c36b26a25d6c6c797e1",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/test_skill_readiness_contract.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import re
+import subprocess
 import unittest
 from pathlib import Path
 
@@ -12,7 +13,8 @@ MANIFEST_PATH = ROOT / ".claude/skills/skill-manifest.json"
 START = re.compile(r"^<!-- readiness:block ([a-z][A-Za-z0-9]*) -->$")
 END = "<!-- readiness:end -->"
 SURFACE = {"claude": ".claude/skills", "codex": ".agents/skills"}
-REQUIRED = {
+FIXTURES = ROOT / "test/fixtures/readiness"
+REQUIRED_V1 = {
     "to-prd": ["issueTracker", "managedBoard"],
     "to-issues": ["issueTracker", "managedBoard", "specCompleteness"],
     "to-waves": ["issueTracker", "managedBoard", "specCompleteness"],
@@ -23,7 +25,7 @@ REQUIRED = {
     "project-release": ["projectReleaseProfile"],
     "security-audit": ["securityAuditRunbook"],
 }
-OPTIONAL = {
+OPTIONAL_V1 = {
     "wrapup": {"deployReport": "prodTarget"},
     "orchestrate-wave": {"projectRecipe": "orchestrateWaveRecipe"},
     "spec-self-critique": {"projectEnrichment": "specCritiqueLayer"},
@@ -32,6 +34,74 @@ OPTIONAL = {
     "audit-skills": {"projectChecks": "auditSkillsLayer"},
     "git-worktree-recover": {"projectRecovery": "worktreeRecoveryLayer"},
 }
+COMPAT_UPDATE_SCRIPT = r"""
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const [repo, fixturePath] = process.argv.slice(-2);
+const load = async (path) => import(pathToFileURL(join(repo, path)));
+const { init } = await load('src/commands/init.mjs');
+const { update } = await load('src/commands/update.mjs');
+const { checkSkill } = await load('scripts/readiness.mjs');
+const { makeKit, makeEmptyDir, cleanup } = await load('test/helpers.mjs');
+const { PACKAGE_MANIFEST_NAME, readManifest, writeManifest } = await load('src/lib/manifest.mjs');
+const { sha256 } = await load('src/lib/hash.mjs');
+const readinessPath = '.claude/skills/skill-manifest.json';
+const fixture = JSON.parse(await readFile(fixturePath, 'utf8'));
+const current = JSON.parse(await readFile(join(repo, readinessPath), 'utf8'));
+const previous = structuredClone(current);
+for (const skill of Object.keys(fixture.readinessFixture.skills)) {
+  previous.skills[skill].readiness = {};
+}
+const kit = await makeKit({ '.claude/skills/to-prd/SKILL.md': 'fixture\n' });
+const consumer = await makeEmptyDir();
+async function setKitReadiness(manifest) {
+  const content = `${JSON.stringify(manifest, null, 2)}\n`;
+  const path = join(kit, readinessPath);
+  await mkdir(join(kit, '.claude/skills'), { recursive: true });
+  await writeFile(path, content);
+  const pkg = await readManifest(join(kit, PACKAGE_MANIFEST_NAME));
+  const entry = pkg.files.find(({ path: candidate }) => candidate === readinessPath);
+  if (entry) entry.sha256 = sha256(content);
+  else pkg.files.push({ path: readinessPath, kind: 'doc', sha256: sha256(content), mode: 0o644, origin: 'kit' });
+  await writeManifest(join(kit, PACKAGE_MANIFEST_NAME), pkg);
+}
+try {
+  await setKitReadiness(previous);
+  await init({ kitRoot: kit, consumerRoot: consumer });
+  for (const [relative, body] of Object.entries(fixture.readinessFixture.evidence)) {
+    const path = join(consumer, relative);
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, body);
+  }
+  const manifestPath = join(consumer, 'agent-workflow-kit.json');
+  const installed = await readManifest(manifestPath);
+  await writeManifest(manifestPath, {
+    ...installed,
+    readinessDecisions: fixture.readinessDecisions ?? {},
+    readinessFixture: fixture.readinessFixture,
+  });
+  const before = {};
+  for (const skill of Object.keys(fixture.readinessFixture.skills)) {
+    before[skill] = await checkSkill({ root: consumer, skill, manifest: previous });
+  }
+  await setKitReadiness(current);
+  const identity = { name: '@ikon85/agent-workflow-kit', version: '0.1.0', tarballIntegrity: 'sha512-fixture', manifestSha256: 'fixture-manifest' };
+  const result = await update({
+    kitRoot: kit, consumerRoot: consumer,
+    releaseIdentities: { installed: { name: identity.name, version: identity.version, manifestSha256: identity.manifestSha256 }, npm: identity, github: identity },
+    verify: async () => {},
+  });
+  const afterManifest = await readManifest(manifestPath);
+  const after = {};
+  for (const skill of Object.keys(fixture.readinessFixture.skills)) {
+    after[skill] = await checkSkill({ root: consumer, skill, manifest: current });
+  }
+  console.log(JSON.stringify({ before, result, afterManifest, after }));
+} finally {
+  await cleanup(kit, consumer);
+}
+"""
 
 
 def load_manifest() -> dict:
@@ -100,11 +170,32 @@ class ReadinessContractTests(unittest.TestCase):
             blocks = list(declaration.get("optionalBlocks", {}))
             self.assertEqual(len(blocks), len(set(blocks)), skill)
 
-    def test_initial_enforcement_mapping_is_exact(self) -> None:
-        for skill, required in REQUIRED.items():
-            self.assertEqual(self.published[skill]["readiness"]["required"], required)
-        for skill, blocks in OPTIONAL.items():
-            self.assertEqual(self.published[skill]["readiness"]["optionalBlocks"], blocks)
+    def test_locked_v1_policy_cannot_disappear_from_the_manifest(self) -> None:
+        actual_required = {
+            skill: entry["readiness"]["required"]
+            for skill, entry in self.published.items()
+            if entry.get("readiness", {}).get("required")
+        }
+        actual_optional = {
+            skill: entry["readiness"]["optionalBlocks"]
+            for skill, entry in self.published.items()
+            if entry.get("readiness", {}).get("optionalBlocks")
+        }
+        self.assertEqual(actual_required, REQUIRED_V1)
+        self.assertEqual(actual_optional, OPTIONAL_V1)
+
+    def test_every_declared_consumer_has_the_standard_preflight(self) -> None:
+        consumers = {
+            skill: entry for skill, entry in self.published.items()
+            if entry.get("readiness")
+        }
+        self.assertGreater(len(consumers), 0)
+        for skill, entry in consumers.items():
+            expected = f"node scripts/readiness.mjs check --skill {skill} --json"
+            for surface in entry["surfaces"]:
+                path = ROOT / SURFACE[surface] / skill / "SKILL.md"
+                body = path.read_text(encoding="utf-8")
+                self.assertEqual(body.count(expected), 1, f"{surface}:{skill}")
 
     def test_markers_are_balanced_declared_and_surface_equal_when_activated(self) -> None:
         for skill, entry in self.published.items():
@@ -114,6 +205,7 @@ class ReadinessContractTests(unittest.TestCase):
                 path = ROOT / SURFACE[surface] / skill / "SKILL.md"
                 self.assertTrue(path.is_file(), f"missing published surface: {path}")
                 sequence = marker_sequence(path.read_text(encoding="utf-8"), declared)
+                self.assertEqual(set(sequence), declared, f"undeclared marker coverage: {surface}:{skill}")
                 sequences.append((surface, sequence))
             if len(sequences) > 1:
                 validate_surface_sequences([sequence for _, sequence in sequences])
@@ -134,6 +226,34 @@ class ReadinessContractTests(unittest.TestCase):
         with self.assertRaises(AssertionError):
             validate_surface_sequences([["projectEnrichment"], []])
 
+    def test_legacy_and_current_consumers_keep_previously_ready_skill_cores(self) -> None:
+        fixtures = sorted(FIXTURES.glob("*/agent-workflow-kit.json"))
+        self.assertEqual([path.parent.name for path in fixtures], ["current", "legacy"])
+        for fixture_path in fixtures:
+            fixture = json.loads(fixture_path.read_text(encoding="utf-8"))
+            scenario = fixture["readinessFixture"]
+            with self.subTest(fixture=fixture_path.parent.name):
+                run = subprocess.run(
+                    ["node", "--input-type=module", "-e", COMPAT_UPDATE_SCRIPT,
+                     str(ROOT), str(fixture_path)],
+                    check=True, capture_output=True, text=True,
+                )
+                proof = json.loads(run.stdout)
+                self.assertEqual(proof["result"]["state"], "applied")
+                self.assertEqual(proof["result"]["availability"]["newlyBlocked"], [])
+                for skill, expected in scenario["skills"].items():
+                    self.assertEqual(proof["before"][skill]["verdict"], "ready", skill)
+                    verdict = proof["after"][skill]
+                    self.assertNotEqual(verdict["verdict"], "blocked", skill)
+                    self.assertEqual(verdict["verdict"], expected["verdict"], skill)
+                    self.assertEqual(verdict["inactiveBlocks"], expected["inactiveBlocks"], skill)
+                self.assertEqual(
+                    proof["afterManifest"].get("readinessDecisions", {}),
+                    scenario["expectedDecisions"],
+                    "unavailable behavior must not manufacture a decision",
+                )
+                self.assertEqual(proof["afterManifest"]["readinessFixture"], scenario)
+
 
 if __name__ == "__main__":
     unittest.main()