@ikon85/agent-workflow-kit 0.29.1 → 0.30.0

package/.agents/skills/codex-adapter-sync/SKILL.md

@@ -9,50 +9,128 @@ Use this skill when the user asks for a Codex adapter sync, Codex drift check,
 Claude-to-Codex migration check, or when changes to Claude-facing project
 knowledge may need to be reflected in Codex-facing files.
 
+## Audit mode (default)
+
+Audit is a read-only diagnosis from the current checkout. Inventory and compare
+the source and adapter surfaces, then report the exact proposed changes. Do not
+create or switch branches or worktrees, edit files, or change external state.
+
+## Apply mode
+
+Apply only when the user asked to update or fix the adapter. Create or reuse the
+correct issue or slice worktree before the first edit. Never apply adapter
+changes on `main`; move any accidental main-checkout diff into the worktree and
+leave the main checkout clean.
+
+## Model routing
+
+Default to inherited parent model configuration. Do not pin a model merely
+because the source workflow delegates, and do not invent model or role fields
+on a spawn call. The supported built-in agent names are `default`, `worker`, and
+`explorer`; custom agents declare overrides in their TOML files.
+
+When an explicit custom-agent model is genuinely justified, route by task
+shape:
+
+- `gpt-5.6-sol` for complex, open-ended judgment work.
+- `gpt-5.6-terra` for everyday tool-using development.
+- `gpt-5.6-luna` for clear, repeatable, high-volume work.
+
+Use `model_reasoning_effort` for a supported reasoning override. The family
+name `gpt-5.6` describes the family and is not a fourth concrete variant in
+this routing table. Keep user gates, security judgment, and approval decisions
+in the main thread.
+
 ## Scope
 
 Source side:
-- `CLAUDE.md`
-- `frontend/CLAUDE.md`
-- `backend/CLAUDE.md`
+- every repository instruction file matched by `**/CLAUDE.md`
 - `~/.claude/CLAUDE.md` when the user explicitly mentions global Claude
   instruction drift or global Claude changes
 - `.claude/skills/`
 - `.claude/agents/`
+- Claude hook declarations and implementations
 - `.gitignore`
 
 Codex adapter side:
-- `AGENTS.md`
+- every repository instruction file matched by `**/AGENTS.md` or
+  `**/AGENTS.override.md`
 - `.agents/skills/`
-- `.codex/config.toml`
+- every trusted project config layer matched by `**/.codex/config.toml`
 - `.codex/agents/`
+- Codex hook declarations
 - `.gitignore`
 
+## Inventory
+
+Derive a fresh, counted inventory from the repository root; do not assume only
+known package names or root-level files. Include:
+
+- arbitrary nested `**/CLAUDE.md`, `**/AGENTS.md`, and
+  `**/AGENTS.override.md` instruction layers;
+- every `**/.codex/config.toml`, noting that Codex loads project config and
+  hooks only from trusted project layers;
+- `.claude/skills/**`, `.agents/skills/**`, `.claude/agents/**`, and
+  `.codex/agents/**`;
+- Claude hook definitions in `.claude/settings*.json` and implementations in
+  `.claude/hooks/**` as adaptation candidates;
+- Codex targets in `.codex/hooks.json` and inline `[hooks]` tables in each
+  active config layer; and
+- ignore rules and every skill reference, asset, script, template, and other
+  distributed support file, regardless of extension.
+
+For every relevant Claude hook behavior, record one explicit classification:
+**Codex-adapted** with its target, or **intentionally Claude-only** with the
+reason. Never port hooks blindly.
+
+## Custom-agent validation
+
+Codex custom-agent files are standalone TOML config layers. Parse every
+`.codex/agents/*.toml` file and require non-empty string values for the required
+`name`, `description`, and `developer_instructions` fields. Validate supported
+optional `model` and `model_reasoning_effort` fields as strings when present,
+then let strict Codex config validation reject unsupported keys or values.
+Reject a file that is malformed, misses a required field, or uses the legacy
+schema. A README or no-op note is not a custom-agent TOML file.
+
+## Validation
+
+Run validation from the repository root and keep the evidence in the report:
+
+1. Run `codex --strict-config --version` from the root and from a representative
+   nested directory for every discovered project config layer. Any unknown
+   active key is a failure, not a warning to ignore.
+2. Validate skill metadata and loading with the repository's strict
+   skill-frontmatter guard when one is available, then start a fresh Codex
+   session and check that every enabled skill is discoverable without load
+   warnings.
+3. Parse and validate every custom-agent TOML file against the
+   Custom-agent validation section above; strict config validation must also
+   accept its supported optional fields.
+4. Use `git check-ignore --no-index` on `.codex/config.toml`, every
+   `.codex/agents/*.toml`, `.agents/skills/**`, `.codex/hooks.json`, and any
+   adapted hook implementation. A checked-in adapter target being ignored is a
+   failure; local state and override files should remain ignored.
+5. Resolve every path named by skill prose and verify that all references,
+   assets, scripts, templates, and other distributed support files exist. Run
+   the repository's all-file mirror-parity guard when available so non-Markdown
+   presence parity and Markdown body/`mirror-xform` parity are both checked.
+6. Recompute the dual-surface skill denominator from the manifest, compare all
+   distributed files in both trees, and report the fresh result as **X of Y**
+   mirrored skills. Do not reuse a remembered count.
+7. Enforce this repository's 1024-character description cap as a named
+   repository safeguard. It is not a Codex product limit; the local guard owns
+   the policy and must fail when a description exceeds it.
+
 ## Workflow
 
-1. Establish a worktree before making adapter changes — pick the mode by how
-   the sync was triggered:
-   - **In-current-worktree (default for a per-slice gate).** If you are already
-     in a non-main slice/feature worktree — e.g. invoked as the mandatory
-     `codex-adapter-sync` gate at the end of a skill-touching slice — sync the
-     adapter **here**, in that same worktree. Commit the adapter changes
-     alongside the slice and ship them in the slice's own PR. Do **not** spin up
-     a separate adapter branch or PR: a per-slice gate that demanded its own
-     worktree/PR would collide with the slice it is gating.
-   - **Dedicated adapter worktree.** Only when invoked standalone from the main
-     checkout (no active slice worktree): create or reuse a dedicated adapter
-     worktree before inventory or edits — your project's worktree helper (or
-     `git worktree add`) on an issue-anchored branch when an anchor exists, or a
-     `chore/codex-adapter-sync-<slug>` worktree for a deliberate no-issue chore
-     — and ship it through its own PR.
-   - Either way: never land adapter changes directly on `main`. Move any
-     accidental main-checkout adapter diff into the chosen worktree first, then
-     leave the main checkout clean.
-2. Inventory the source side and adapter side from inside that worktree. If
-   global Claude instructions are in scope, read them from the main thread but
-   keep personal overrides, secrets, and machine-local state out of the repo
-   diff.
-3. Compare project knowledge:
+1. Select the mode from the user's request. Audit in the current checkout. For
+   Apply, reuse the active non-main slice worktree when the sync gates that
+   slice; otherwise create or reuse a dedicated issue-anchored adapter worktree.
+2. Build the Inventory before proposing or making changes. If global Claude
+   instructions are in scope, inspect them without exposing personal overrides,
+   secrets, credentials, or machine-local state.
+3. Compare project knowledge and instruction precedence:
    - New or changed durable conventions in `CLAUDE.md` should be reflected in
      `AGENTS.md` only as concise adapter guidance or references.
    - Do not duplicate long `CLAUDE.md` sections into `AGENTS.md`.
@@ -62,26 +140,16 @@ Codex adapter side:
      Codex-facing adapter rule in `AGENTS.md` or a minimal safe Codex config
      change; do not copy personal style, identities, credentials, or long
      global sections.
-4. Compare skills:
+4. Compare every skill and distributed support file:
    - Important repo/domain/workflow skills from `.claude/skills/` belong in
      `.agents/skills/`.
    - Keep each `SKILL.md` and its support files together.
    - Do not copy skills into `.codex/skills/`.
    - Leave clearly Claude-only setup, hook, or personal/meta skills out unless
      the user explicitly wants them ported.
-   - Translate Claude-specific model delegation instead of copying it
-     literally (tier mapping per your routing doctrine; if the repo carries a
-     Codex mirror table in `AGENTS.md`, keep it in sync). In particular, Claude `Agent` dispatches with
-     `model: sonnet` should become Codex `spawn_agent` dispatches with the
-     appropriate `agent_type`; for mechanical coding/git work use a `worker`
-     subagent with `model: gpt-5.4-mini` and `reasoning_effort: low` unless the
-     source skill gives a stronger task-specific reason. Claude `opus` /
-     judgment-tier dispatches (subtle logic, review/verify verdicts) map to
-     `model: gpt-5.5` with `reasoning_effort: high` (verdicts never below
-     high). Translate Claude `effort:` params to the nearest
-     `reasoning_effort` value (`minimal|low|medium|high|xhigh`; Claude `max`
-     → `xhigh`). Keep user gates, security judgment, and approval decisions
-     in the main thread.
+   - Translate Claude-specific delegation rather than copying it literally.
+     Apply the Model routing section above only when an explicit custom-agent
+     override is justified; otherwise preserve inherited parent configuration.
    - Keep dual-surface generic/vendored skill bodies content-synced. When a
      Codex mirror must intentionally differ from the Claude source, bracket the
      source region and the Codex replacement with a matching transform marker
@@ -111,36 +179,30 @@ Codex adapter side:
      `chaseai-yt/grill-me-codex`, `docs/agents/skills/grill-with-docs-codex.md`)
      is not an escalation target and must NOT be rewritten — rewriting it would
      break attribution/a real link.
-5. Validate Codex skill frontmatter:
-   - `name` and `description` are required.
-   - Quote `description` when it contains colons, arrows, commas, or other
-     YAML-sensitive punctuation.
-   - Keep `description` under 1024 characters.
-   - Keep trigger detail in the body if the original Claude description is too
-     long.
-6. Compare agents:
-   - Claude agents are `.md` files under `.claude/agents/`.
-   - Codex agents are `.toml` files under `.codex/agents/`.
-   - Convert agent instruction bodies into `developer_instructions`.
-   - If no Claude agents exist, keep only a short README or no-op note.
-7. Compare config and ignore rules:
-   - Keep `.codex/config.toml` minimal and safe.
-   - Never add secrets, provider credentials, auth tokens, or local personal
-     overrides.
-   - Ensure `.gitignore` excludes local Codex state and override files while
-     allowing checked-in project config, agents, and skills.
-8. Before edits, show the exact files that will be created or changed.
-9. After edits, validate:
-   - `.codex/config.toml` parses as TOML.
-   - All `.agents/skills/*/SKILL.md` files load without Codex warnings.
-   - No skill description exceeds 1024 characters.
-   - `.codex/config.toml`, `.codex/agents/*.toml`, and `.agents/skills/**`
-     are not accidentally ignored.
-10. Prepare the branch for review:
-   - Commit the adapter changes on the worktree branch after checking for
-     secrets and ignored files.
-   - Push the branch and create or update a PR.
-   - Report the PR URL, changed files, skipped items, and verification results.
+5. Compare agents, hooks, config, and ignore rules:
+   - Claude agents are `.md`; Codex custom agents are `.toml` and must satisfy
+     Custom-agent validation.
+   - Classify each Claude hook behavior using the Inventory contract and check
+     Codex hook targets at every active trusted config layer.
+   - Keep `.codex/config.toml` minimal and safe. Never add secrets, provider
+     credentials, auth tokens, or local personal overrides.
+   - Ensure ignore rules exclude local Codex state and override files while
+     allowing checked-in config, agents, hooks, skills, and support files.
+6. In Audit mode, run every read-only Validation step that the checkout
+   supports and report the proposed file changes without mutating anything.
+7. In Apply mode, show the exact files to create or change before editing, make
+   only those changes, then run the complete Validation section. Prepare the
+   existing worktree branch for review: check for secrets and ignored files,
+   commit the adapter changes, push, and create or update its PR.
+
+Codex skill frontmatter must also satisfy these repository rules:
+
+- `name` and `description` are required.
+- Quote `description` when it contains colons, arrows, commas, or other
+  YAML-sensitive punctuation.
+- Enforce the Validation section's named description safeguard.
+- Keep trigger detail in the body if the original Claude description is too
+  long.
 
 ## Output
 

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/README.md

@@ -348,6 +348,15 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 
 ## Release notes
 
+### 0.30.0
+
+- added: `.claude/skills/skill-manifest.json`
+- added: `scripts/readiness.mjs`
+- added: `src/lib/atomicWrite.mjs`
+- added: `src/lib/manifest.mjs`
+- added: `src/lib/sentinel.mjs`
+- changed: `.agents/skills/codex-adapter-sync/SKILL.md`
+
 ### 0.29.1
 
 - Metadata-only release.

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.29.1",
+  "kitVersion": "0.30.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -107,7 +107,7 @@
       "ownerSkill": "codex-adapter-sync",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "3a8ad73c4bfce8c01e561d2dc0c7f0e24d9ac85c1bb2c8c0194a2de278cd6a2d",
+      "sha256": "ae398e40308e6ad8d6091c418435e2dca8a4f67e526ab85efa88e8e57c0354c2",
       "mode": 420,
       "origin": "kit"
     },
@@ -2023,6 +2023,14 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/skill-manifest.json",
+      "kind": "doc",
+      "installRole": "consumer",
+      "sha256": "290cc3e847a10cb10b4ecb17cf0d45be0f60f95e96b7a70417b3e8da0a32e23c",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/spec-self-critique/scenarios.md",
       "kind": "skill",
@@ -2575,6 +2583,14 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "scripts/readiness.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "f5e8bc2e724f72d1aa9f94c4f8d87b8f4d3f9843797cd6ae59f48e563dc7c7fb",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
@@ -2727,6 +2743,22 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "src/lib/atomicWrite.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "dbb971617ae641127857341a02cc029f30633ab5ef0c6efff2bab27b95794a9f",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "src/lib/manifest.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "171eba2662054379c40c1c629110fa8e34353de72e136004b861b2ac6a4edc13",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "src/lib/release-apply.mjs",
       "kind": "script",
@@ -2750,6 +2782,14 @@
       "sha256": "7d0a8da3740ed1eb79edb80f0eedb3cd1de47692d4886c6b119b39073a6468d1",
       "mode": 420,
       "origin": "kit"
+    },
+    {
+      "path": "src/lib/sentinel.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "f99d28d2053d55222650d2ca426509d3f56eec5ef70709bbf8c4a278bf80024e",
+      "mode": 420,
+      "origin": "kit"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.29.1",
+  "version": "0.30.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/readiness.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { firstLineState } from '../src/lib/sentinel.mjs';
+import { CONSUMER_MANIFEST_NAME, readManifest, writeManifest } from '../src/lib/manifest.mjs';
+
+const SOURCE_MANIFEST = '.claude/skills/skill-manifest.json';
+const DECISIONS = new Set(['pending', 'not-applicable']);
+
+async function readText(root, path) {
+  try { return await readFile(join(root, path), 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function sentinelVerdict(text, allowLegacy) {
+  if (text === null) return 'absent';
+  const state = firstLineState(text);
+  const content = text.split('\n').slice(1).join('\n').trim();
+  if (state === 'filled') return content ? 'valid' : 'invalid';
+  if (state === null && allowLegacy && text.trim()) return 'valid';
+  return 'invalid';
+}
+
+function nonemptyVerdict(text) {
+  return text === null ? 'absent' : (text.trim() ? 'valid' : 'invalid');
+}
+
+function jsonValue(text, required) {
+  if (text === null) return 'absent';
+  try {
+    let value = JSON.parse(text);
+    for (const key of required ?? []) value = value?.[key];
+    return value === undefined || value === null ? 'invalid' : value;
+  } catch { return 'invalid'; }
+}
+
+function jsonVerdict(text, evidence) {
+  if (evidence.validator === 'project-release') {
+    if (text === null) return 'absent';
+    let profile;
+    try { profile = JSON.parse(text); } catch { return 'invalid'; }
+    const value = profile.schemaVersion === 1 ? profile.projectRelease : null;
+    const files = value?.versionFiles;
+    const tag = value?.tagPrefix;
+    return Array.isArray(files) && files.length > 0
+      && files.every((path) => typeof path === 'string' && path.trim())
+      && (tag === undefined || typeof tag === 'string') ? 'valid' : 'invalid';
+  }
+  const value = jsonValue(text, evidence.required);
+  if (['absent', 'invalid'].includes(value)) return value;
+  if (!(evidence.required?.length) && typeof value === 'object'
+      && !Array.isArray(value) && Object.keys(value).length === 0) return 'invalid';
+  return 'valid';
+}
+
+function fencedJsonAfter(text, marker) {
+  const start = text.indexOf(marker);
+  if (start < 0) return null;
+  const match = /```json\s*([\s\S]*?)```/.exec(text.slice(start + marker.length));
+  if (!match) return 'invalid';
+  try { return JSON.parse(match[1]); } catch { return 'invalid'; }
+}
+
+function boardVerdict(text) {
+  if (text === null) return 'absent';
+  const profile = fencedJsonAfter(text, '<!-- board-sync:profile -->');
+  if (!profile || profile === 'invalid') return 'invalid';
+  const status = profile.fields?.status;
+  const required = [profile.repo, profile.project?.owner, profile.project?.number,
+    profile.project?.nodeId, status?.id, status?.options, status?.roles,
+    profile.fields?.wave, profile.fields?.cluster, profile.labels];
+  return required.every(Boolean) ? 'valid' : 'invalid';
+}
+
+async function runbookVerdict(root, evidence) {
+  const layer = await readText(root, evidence.paths[0]);
+  const layerState = sentinelVerdict(layer, evidence.allowLegacy);
+  if (layerState !== 'valid') return layerState;
+  const paths = [...layer.matchAll(/`([^`\n]+\.md)`/g)].map((match) => match[1]);
+  for (const path of paths) {
+    if (path.includes('template')) continue;
+    const runbook = await readText(root, path);
+    if (runbook?.trim() && !runbook.includes('<placeholder>')) return 'valid';
+  }
+  return 'invalid';
+}
+
+function section(text, heading) {
+  if (text === null) return null;
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start < 0) return null;
+  const body = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^##\s+/.test(line)) break;
+    body.push(line);
+  }
+  return body.join('\n').trim();
+}
+
+async function prodVerdict(root, paths) {
+  const bodies = [];
+  for (const path of paths) {
+    const text = await readText(root, path);
+    if (text === null) continue;
+    const body = section(text, '## Prod');
+    bodies.push(body);
+  }
+  if (!bodies.length) return 'absent';
+  if (bodies.every((body) => body === null)) return 'absent';
+  if (bodies.some((body) => !body)) return 'invalid';
+  return bodies.every((body) => body === bodies[0]) ? 'valid' : 'invalid';
+}
+
+async function evidenceVerdict(root, evidence) {
+  if (evidence.type === 'prod-section') return prodVerdict(root, evidence.paths);
+  if (evidence.type === 'runbook-reference') return runbookVerdict(root, evidence);
+  const verdicts = await Promise.all((evidence.paths ?? []).map(async (path) => {
+    const text = await readText(root, path);
+    if (evidence.type === 'sentinel') return sentinelVerdict(text, evidence.allowLegacy);
+    if (evidence.type === 'json') return jsonVerdict(text, evidence);
+    if (evidence.type === 'board-profile') return boardVerdict(text);
+    return nonemptyVerdict(text);
+  }));
+  if (verdicts.some((value) => value === 'invalid')) return 'invalid';
+  if (verdicts.some((value) => value === 'valid')) return 'valid';
+  return 'absent';
+}
+
+export async function evaluateCapability({ root, capability, decision }) {
+  const evidence = await evidenceVerdict(root, capability.evidence);
+  if (evidence === 'invalid') return { state: 'invalid', clearDecision: false };
+  if (evidence === 'valid') return { state: 'ready', clearDecision: Boolean(decision) };
+  if (decision === 'pending') return { state: 'pending', clearDecision: false };
+  if (decision === 'not-applicable' && capability.allowNotApplicable) {
+    return { state: 'not-applicable', clearDecision: false };
+  }
+  return { state: 'missing', clearDecision: false };
+}
+
+async function loadManifest(root) {
+  const body = await readText(root, SOURCE_MANIFEST);
+  if (body === null) throw new Error(`readiness manifest not found: ${SOURCE_MANIFEST}`);
+  return JSON.parse(body);
+}
+
+export async function checkSkill({ root, skill, manifest }) {
+  manifest ??= await loadManifest(root);
+  const declaration = manifest.skills?.[skill]?.readiness;
+  if (!declaration) throw new Error(`skill has no readiness declaration: ${skill}`);
+  const consumer = await readManifest(join(root, CONSUMER_MANIFEST_NAME));
+  const decisions = consumer?.readinessDecisions ?? {};
+  const names = new Set([
+    ...(declaration.required ?? []), ...Object.values(declaration.optionalBlocks ?? {}),
+  ]);
+  const capabilities = {};
+  for (const name of names) {
+    const catalogEntry = manifest.readiness?.capabilities?.[name];
+    if (!catalogEntry) throw new Error(`unknown readiness capability: ${name}`);
+    capabilities[name] = await evaluateCapability({
+      root, capability: catalogEntry, decision: decisions[name],
+    });
+  }
+  const requiredBlocked = (declaration.required ?? []).some(
+    (name) => capabilities[name].state !== 'ready',
+  );
+  const activeBlocks = [];
+  const inactiveBlocks = [];
+  for (const [block, name] of Object.entries(declaration.optionalBlocks ?? {})) {
+    (capabilities[name].state === 'ready' ? activeBlocks : inactiveBlocks).push(block);
+  }
+  const invalid = Object.values(capabilities).some(({ state }) => state === 'invalid');
+  const verdict = requiredBlocked ? 'blocked' : (inactiveBlocks.length || invalid ? 'degraded' : 'ready');
+  return { contractVersion: manifest.readiness.contractVersion, verdict, capabilities, activeBlocks, inactiveBlocks };
+}
+
+async function changeDecision(root, capability, value) {
+  const path = join(root, CONSUMER_MANIFEST_NAME);
+  const manifest = await readManifest(path);
+  if (!manifest) throw new Error('not initialised — run `init` first');
+  const readiness = (await loadManifest(root)).readiness;
+  const catalog = readiness.capabilities;
+  if (!catalog[capability]) throw new Error(`unknown readiness capability: ${capability}`);
+  if (value && !DECISIONS.has(value)) throw new Error(`invalid readiness decision: ${value}`);
+  if (value === 'not-applicable' && !catalog[capability].allowNotApplicable) {
+    throw new Error(`${capability} does not allow not-applicable`);
+  }
+  const decisions = { ...(manifest.readinessDecisions ?? {}) };
+  if (value) decisions[capability] = value; else delete decisions[capability];
+  await writeManifest(path, {
+    ...manifest, readinessContractVersion: readiness.contractVersion, readinessDecisions: decisions,
+  });
+}
+
+function option(args, name, fallback) {
+  const index = args.indexOf(name);
+  return index < 0 ? fallback : args[index + 1];
+}
+
+async function main(args = process.argv.slice(2)) {
+  const root = resolve(option(args, '--root', process.cwd()));
+  if (args[0] === 'check') {
+    const result = await checkSkill({ root, skill: option(args, '--skill') });
+    console.log(JSON.stringify(result, null, args.includes('--json') ? 2 : 0));
+    return;
+  }
+  if (args[0] === 'decision' && args[1] === 'set') return changeDecision(root, args[2], args[3]);
+  if (args[0] === 'decision' && args[1] === 'clear') return changeDecision(root, args[2], null);
+  throw new Error('usage: readiness check --skill <name> [--json] [--root <path>] | decision <set|clear> <capability> [value]');
+}
+
+if (resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(`readiness: ${error.message}`); process.exitCode = 1; });
+}

package/scripts/test_codex_adapter_sync_contract.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Regression contract for the Codex-only adapter audit skill."""
+
+import importlib.util
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+ADAPTER = REPO_ROOT / ".agents/skills/codex-adapter-sync/SKILL.md"
+_FRONTMATTER_SPEC = importlib.util.spec_from_file_location(
+    "skill_frontmatter_lint", REPO_ROOT / "scripts/test_skill_frontmatter_lint.py")
+frontmatter = importlib.util.module_from_spec(_FRONTMATTER_SPEC)
+_FRONTMATTER_SPEC.loader.exec_module(frontmatter)
+
+
+def section(body: str, heading: str) -> str:
+    """Return one second-level Markdown section, excluding the next one."""
+    marker = f"## {heading}\n"
+    start = body.index(marker) + len(marker)
+    end = body.find("\n## ", start)
+    return body[start:] if end == -1 else body[start:end]
+
+
+class AdapterModesContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_audit_is_read_only_and_apply_is_worktree_gated(self):
+        audit = " ".join(section(self.body, "Audit mode (default)").split())
+        apply = " ".join(section(self.body, "Apply mode").split())
+
+        self.assertIn("current checkout", audit)
+        self.assertIn("read-only", audit)
+        self.assertIn("Do not create or switch branches or worktrees", audit)
+        self.assertIn("before the first edit", apply)
+        self.assertIn("Never apply adapter changes on `main`", apply)
+        self.assertNotIn("before inventory or edits", self.body)
+
+
+class AdapterModelContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_current_models_inherit_by_default_and_route_by_task_shape(self):
+        routing = " ".join(section(self.body, "Model routing").split())
+
+        self.assertIn("inherited parent model configuration", routing)
+        self.assertIn("`gpt-5.6-sol`", routing)
+        self.assertIn("complex, open-ended judgment work", routing)
+        self.assertIn("`gpt-5.6-terra`", routing)
+        self.assertIn("everyday tool-using development", routing)
+        self.assertIn("`gpt-5.6-luna`", routing)
+        self.assertIn("clear, repeatable, high-volume work", routing)
+        self.assertIn("`model_reasoning_effort`", routing)
+        self.assertIn("`default`, `worker`, and `explorer`", routing)
+        self.assertIn("not a fourth concrete variant", routing)
+
+        for stale in ("gpt-5.4-mini", "gpt-5.5"):
+            self.assertNotIn(stale, self.body)
+        self.assertNotRegex(self.body, r"(?<!model_)\breasoning_effort\b")
+        self.assertNotRegex(self.body, r"\bagent_type\b")
+
+
+class AdapterInventoryContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_nested_instructions_configs_and_hooks_are_inventoried(self):
+        inventory = section(self.body, "Inventory")
+
+        for surface in (
+            "`**/CLAUDE.md`",
+            "`**/AGENTS.md`",
+            "`**/AGENTS.override.md`",
+            "`**/.codex/config.toml`",
+            "`.claude/settings*.json`",
+            "`.claude/hooks/**`",
+            "`.codex/hooks.json`",
+            "inline `[hooks]`",
+        ):
+            self.assertIn(surface, inventory)
+        self.assertIn("trusted project layers", inventory)
+        self.assertIn("Codex-adapted", inventory)
+        self.assertIn("intentionally Claude-only", inventory)
+        self.assertNotIn("`frontend/CLAUDE.md`", self.body)
+        self.assertNotIn("`backend/CLAUDE.md`", self.body)
+
+
+class AdapterAgentContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_custom_agent_toml_uses_the_current_schema(self):
+        agents = " ".join(section(self.body, "Custom-agent validation").split())
+
+        self.assertIn(
+            "required `name`, `description`, and `developer_instructions`", agents)
+        self.assertIn("optional `model` and `model_reasoning_effort`", agents)
+        self.assertIn("Parse every `.codex/agents/*.toml`", agents)
+        self.assertIn("Reject a file", agents)
+
+
+class AdapterValidationContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_validation_covers_every_current_adapter_surface(self):
+        validation = " ".join(section(self.body, "Validation").split())
+
+        for proof in (
+            "`codex --strict-config --version`",
+            "skill-frontmatter guard",
+            "skill metadata and loading",
+            "custom-agent TOML",
+            "`git check-ignore",
+            "references, assets, scripts",
+            "mirror-parity guard",
+            "X of Y",
+        ):
+            self.assertIn(proof, validation)
+        for maintainer_only_path in (
+            "scripts/test_skill_frontmatter_lint.py",
+            "scripts/test_skill_portability_lint.py",
+        ):
+            self.assertNotIn(maintainer_only_path, self.body)
+
+    def test_description_cap_is_an_enforced_repository_safeguard(self):
+        validation = " ".join(section(self.body, "Validation").split())
+        self.assertIn("1024-character description cap", validation)
+        self.assertIn("repository safeguard", validation)
+        self.assertIn("not a Codex product limit", validation)
+
+        problems = []
+        for skill in (REPO_ROOT / ".agents/skills").glob("*/SKILL.md"):
+            data = frontmatter.parse_frontmatter(
+                frontmatter.extract_frontmatter(skill.read_text(encoding="utf-8")))
+            description = data.get("description")
+            if isinstance(description, str) and len(description) > 1024:
+                problems.append(f"{skill.relative_to(REPO_ROOT)}: {len(description)}")
+        self.assertEqual(
+            problems,
+            [],
+            "skill descriptions over 1024 characters:\n" + "\n".join(problems),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_skill_portability_lint.py

@@ -23,8 +23,8 @@ A line carrying `portability-lint: ok` is exempt — line-scoped, for deliberate
 doc counterexamples.
 
 This file also asserts mirror parity:
-- every dual-surface skill has the same set of distributed `*.md` files in both
-  trees (catches a forgotten mirror file);
+- every dual-surface skill has the same set of distributed files in both trees
+  (catches a forgotten mirror support file of any type);
 - generic/vendored dual-surface skill bodies match after stripping paired
   `mirror-xform` regions. The paired marker convention lets codex-adapter-sync
   keep legitimate Codex body translations local instead of maintaining a central
@@ -220,12 +220,36 @@ def enforced_skills() -> set[str]:
             if e["class"] in ENFORCED_CLASSES}
 
 
-def skill_md_set(tree: str, name: str) -> set[str]:
-    """Relative posix paths of every distributed *.md under one tree's skill dir."""
-    d = REPO_ROOT / tree / name
-    if not d.is_dir():
+def distributed_file_set(skill_dir: Path) -> set[str]:
+    """Relative paths of every distributed file under one skill directory."""
+    if not skill_dir.is_dir():
         return set()
-    return {p.relative_to(d).as_posix() for p in d.rglob("*.md")}
+    return {
+        p.relative_to(skill_dir).as_posix()
+        for p in skill_dir.rglob("*")
+        if p.is_file()
+    }
+
+
+def skill_file_set(tree: str, name: str) -> set[str]:
+    return distributed_file_set(REPO_ROOT / tree / name)
+
+
+def skill_md_set(tree: str, name: str) -> set[str]:
+    """Markdown subset used by the body and structure parity checks."""
+    return {p for p in skill_file_set(tree, name) if p.endswith(".md")}
+
+
+def mirror_presence_drift(name: str, claude: set[str], codex: set[str]) -> list[str]:
+    problems = [
+        f"{name}: .claude/skills/{name}/{rel} has no codex mirror"
+        for rel in sorted(claude - codex)
+    ]
+    problems.extend(
+        f"{name}: .agents/skills/{name}/{rel} has no claude source"
+        for rel in sorted(codex - claude)
+    )
+    return problems
 
 
 def dual_surface_skills() -> list[str]:
@@ -486,21 +510,16 @@ class ProfileValueLiteralNegativeFixture(unittest.TestCase):
 
 class MirrorPresenceParity(unittest.TestCase):
     """LEAN mirror parity: a dual-surface skill has the SAME set of distributed
-    *.md files in both trees. Presence/file-set only — not content (codex-adapter-sync
-    legitimately translates body model-dispatch; full content parity is a follow-up).
+    files in both trees. Presence/file-set only; Markdown content parity is handled
+    separately because codex-adapter-sync legitimately translates body model-dispatch.
     Catches a forgotten / orphaned mirror file (Codex R1#11 first half)."""
 
-    def test_dual_surface_md_filesets_match(self):
+    def test_dual_surface_distributed_filesets_match(self):
         problems = []
         for name in sorted(dual_surface_skills()):
-            claude = skill_md_set(".claude/skills", name)
-            codex = skill_md_set(".agents/skills", name)
-            only_claude = claude - codex
-            only_codex = codex - claude
-            for f in sorted(only_claude):
-                problems.append(f"{name}: .claude/skills/{name}/{f} has no codex mirror")
-            for f in sorted(only_codex):
-                problems.append(f"{name}: .agents/skills/{name}/{f} has no claude source")
+            claude = skill_file_set(".claude/skills", name)
+            codex = skill_file_set(".agents/skills", name)
+            problems.extend(mirror_presence_drift(name, claude, codex))
         self.assertEqual(
             problems, [],
             "mirror file-set drift — run codex-adapter-sync to add/remove the mirror "
@@ -540,6 +559,26 @@ class MirrorContentParity(unittest.TestCase):
 class MirrorParityFixture(unittest.TestCase):
     """The file-set comparison catches an orphaned mirror file (regression guard)."""
 
+    def test_non_markdown_support_file_is_detected(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            claude = Path(d) / "claude"
+            codex = Path(d) / "codex"
+            (claude / "assets").mkdir(parents=True)
+            codex.mkdir()
+            (claude / "SKILL.md").write_text("# Example\n", encoding="utf-8")
+            (codex / "SKILL.md").write_text("# Example\n", encoding="utf-8")
+            (claude / "assets/example.yml").write_text("enabled: true\n", encoding="utf-8")
+
+            self.assertEqual(
+                mirror_presence_drift(
+                    "example",
+                    distributed_file_set(claude),
+                    distributed_file_set(codex),
+                ),
+                ["example: .claude/skills/example/assets/example.yml has no codex mirror"],
+            )
+
     def test_extra_mirror_file_is_detected(self):
         claude = {"SKILL.md", "tests.md"}
         codex = {"SKILL.md"}

package/scripts/test_skill_readiness_contract.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Manifest-derived readiness declaration and marker grammar guard."""
+from __future__ import annotations
+
+import json
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+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 = {
+    "to-prd": ["issueTracker", "managedBoard"],
+    "to-issues": ["issueTracker", "managedBoard", "specCompleteness"],
+    "to-waves": ["issueTracker", "managedBoard", "specCompleteness"],
+    "board-to-waves": ["issueTracker", "managedBoard"],
+    "triage": ["issueTracker", "managedBoard", "triageLabels"],
+    "orchestrate-wave": ["issueTracker", "managedBoard"],
+    "local-ci": ["localCiRecipe"],
+    "project-release": ["projectReleaseProfile"],
+    "security-audit": ["securityAuditRunbook"],
+}
+OPTIONAL = {
+    "wrapup": {"deployReport": "prodTarget"},
+    "orchestrate-wave": {"projectRecipe": "orchestrateWaveRecipe"},
+    "spec-self-critique": {"projectEnrichment": "specCritiqueLayer"},
+    "code-review": {"projectEnrichment": "codeReviewLayer"},
+    "verify-spike": {"projectPlacement": "verifySpikeLayer"},
+    "audit-skills": {"projectChecks": "auditSkillsLayer"},
+    "git-worktree-recover": {"projectRecovery": "worktreeRecoveryLayer"},
+}
+
+
+def load_manifest() -> dict:
+    return json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+
+
+def marker_sequence(body: str, declared: set[str]) -> list[str]:
+    sequence: list[str] = []
+    active: str | None = None
+    seen: set[str] = set()
+    for number, line in enumerate(body.splitlines(), 1):
+        match = START.fullmatch(line)
+        if match:
+            block = match.group(1)
+            if active:
+                raise AssertionError(f"nested readiness block at line {number}")
+            if block in seen:
+                raise AssertionError(f"duplicate readiness block {block}")
+            if block not in declared:
+                raise AssertionError(f"unknown readiness block {block}")
+            active = block
+            seen.add(block)
+            sequence.append(block)
+        elif line == END:
+            if not active:
+                raise AssertionError(f"unbalanced readiness end at line {number}")
+            active = None
+        elif "readiness:block" in line or "readiness:end" in line:
+            raise AssertionError(f"invalid readiness marker grammar at line {number}")
+    if active:
+        raise AssertionError(f"unbalanced readiness block {active}")
+    return sequence
+
+
+def validate_surface_sequences(sequences: list[list[str]]) -> None:
+    if any(sequence != sequences[0] for sequence in sequences[1:]):
+        raise AssertionError("cross-surface readiness marker drift")
+
+
+class ReadinessContractTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.manifest = load_manifest()
+        self.catalog = self.manifest["readiness"]["capabilities"]
+        self.published = {
+            name: entry for name, entry in self.manifest["skills"].items()
+            if entry.get("publish")
+        }
+
+    def test_contract_and_skill_denominator_come_from_publish_manifest(self) -> None:
+        self.assertEqual(self.manifest["readiness"]["contractVersion"], 1)
+        manifest_source = (ROOT / "src/lib/manifest.mjs").read_text(encoding="utf-8")
+        version = re.search(r"READINESS_CONTRACT_VERSION = (\d+);", manifest_source)
+        self.assertIsNotNone(version)
+        self.assertEqual(int(version.group(1)), self.manifest["readiness"]["contractVersion"])
+        self.assertGreater(len(self.published), 0)
+        for name, entry in self.published.items():
+            self.assertTrue(entry.get("surfaces"), name)
+
+    def test_every_declaration_references_the_single_capability_catalog(self) -> None:
+        for skill, entry in self.published.items():
+            declaration = entry.get("readiness", {})
+            references = list(declaration.get("required", []))
+            references += list(declaration.get("optionalBlocks", {}).values())
+            for capability in references:
+                self.assertIn(capability, self.catalog, f"{skill}: {capability}")
+            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_markers_are_balanced_declared_and_surface_equal_when_activated(self) -> None:
+        for skill, entry in self.published.items():
+            declared = set(entry.get("readiness", {}).get("optionalBlocks", {}))
+            sequences: list[tuple[str, list[str]]] = []
+            for surface in entry["surfaces"]:
+                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)
+                sequences.append((surface, sequence))
+            if len(sequences) > 1:
+                validate_surface_sequences([sequence for _, sequence in sequences])
+
+    def test_marker_parser_rejects_each_structural_failure(self) -> None:
+        declared = {"projectEnrichment"}
+        bad = [
+            "<!-- readiness:block projectEnrichment -->\n<!-- readiness:block projectEnrichment -->",
+            "<!-- readiness:block projectEnrichment -->\n<!-- readiness:end -->\n<!-- readiness:block projectEnrichment -->",
+            "<!-- readiness:end -->",
+            "<!-- readiness:block projectEnrichment -->",
+            "<!-- readiness:block unknownBlock -->\n<!-- readiness:end -->",
+            " <!-- readiness:block projectEnrichment -->",
+        ]
+        for body in bad:
+            with self.subTest(body=body), self.assertRaises(AssertionError):
+                marker_sequence(body, declared)
+        with self.assertRaises(AssertionError):
+            validate_surface_sequences([["projectEnrichment"], []])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/commands/init.mjs

@@ -8,6 +8,7 @@ import {
   readManifest, writeManifest, emptyConsumerManifest,
   filesForInstallRole, CONSUMER_INSTALL_ROLE,
   indexByPath,
+  readReadinessContract,
   CONSUMER_ORIGIN,
   PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME,
 } from '../lib/manifest.mjs';
@@ -27,6 +28,7 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
   const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
   if (!pkg) throw new Error('kit package manifest not found');
   const prior = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const readiness = await readReadinessContract(kitRoot);
   const tracked = new Set((prior?.installed ?? []).map((e) => e.path));
   const consumerOwned = new Set(
     (prior?.installed ?? []).filter((e) => e.origin === CONSUMER_ORIGIN).map((e) => e.path),
@@ -68,7 +70,7 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
 
   await writeManifest(
     join(consumerRoot, CONSUMER_MANIFEST_NAME),
-    { ...emptyConsumerManifest(pkg.kitVersion), installed }
+    { ...emptyConsumerManifest(pkg.kitVersion, prior, readiness), installed }
   );
 
   for (const stub of STUB_TARGETS) {

package/src/commands/uninstall.mjs

@@ -5,6 +5,7 @@ import { hookReferenced } from '../lib/settings.mjs';
 import {
   writeManifest, readManifest, emptyConsumerManifest,
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN,
+  readReadinessContract,
 } from '../lib/manifest.mjs';
 
 const exists = (p) => access(p).then(() => true, () => false);
@@ -18,6 +19,7 @@ const exists = (p) => access(p).then(() => true, () => false);
 export async function uninstall({ consumerRoot }) {
   const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!consumer) throw new Error('not initialised — nothing to uninstall');
+  const readiness = await readReadinessContract(consumerRoot);
 
   const res = { removed: [], retained: [] };
   const retainedEntries = [];
@@ -42,7 +44,9 @@ export async function uninstall({ consumerRoot }) {
 
   const manifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
   if (retainedEntries.length) {
-    await writeManifest(manifestPath, { ...emptyConsumerManifest(consumer.kitVersion), installed: retainedEntries });
+    await writeManifest(manifestPath, {
+      ...emptyConsumerManifest(consumer.kitVersion, consumer, readiness), installed: retainedEntries,
+    });
   } else {
     await rm(manifestPath, { force: true });
   }

package/src/lib/bundle.mjs

@@ -4,6 +4,13 @@ import { join, relative } from 'node:path';
 // The planning skills are not usable without their helper ecosystem (Codex R2#1).
 // These ship alongside the skills. Paths are relative to the bundle/consumer root.
 export const HELPER_FILES = [
+  // Readiness declarations and their deterministic consumer-side command ship
+  // together; the manifest remains the only capability/dependency registry.
+  { path: '.claude/skills/skill-manifest.json', kind: 'doc', mode: 0o644 },
+  { path: 'scripts/readiness.mjs', kind: 'script', mode: 0o755 },
+  { path: 'src/lib/sentinel.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/manifest.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/atomicWrite.mjs', kind: 'script', mode: 0o644 },
   // Shared profile loader imported by the three planning scripts — they read
   // every board-specific value from docs/agents/board-sync.md through it, so it
   // MUST ship or they are broken-on-arrival. Library (imported, not run) → 0o644.

package/src/lib/manifest.mjs

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { writeAtomic } from './atomicWrite.mjs';
 
 // Two manifests (Codex R1#9 / R3#1):
@@ -15,6 +16,8 @@ export const PACKAGE_MANIFEST_NAME = 'agent-workflow-kit.package.json';
 export const CONSUMER_INSTALL_ROLE = 'consumer';
 export const KIT_ORIGIN = 'kit';
 export const CONSUMER_ORIGIN = 'consumer';
+export const READINESS_CONTRACT_VERSION = 1;
+export const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
 
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
@@ -51,8 +54,29 @@ export async function writeManifest(path, obj) {
   await writeAtomic(path, JSON.stringify(obj, null, 2) + '\n');
 }
 
-export function emptyConsumerManifest(kitVersion) {
-  return { kitVersion, installRole: CONSUMER_INSTALL_ROLE, installed: [] };
+export async function readReadinessContract(root) {
+  const manifest = await readManifest(join(root, READINESS_MANIFEST_PATH));
+  return manifest?.readiness ?? null;
+}
+
+function retainedDecisions(prior, readiness) {
+  const allowed = readiness?.capabilities ? new Set(Object.keys(readiness.capabilities)) : null;
+  return Object.fromEntries(Object.entries(prior.readinessDecisions ?? {}).filter(
+    ([name, value]) => (!allowed || allowed.has(name)) && (value === 'pending'
+      || (value === 'not-applicable' && readiness?.capabilities?.[name]?.allowNotApplicable)),
+  ));
+}
+
+export function emptyConsumerManifest(kitVersion, prior = {}, readiness = null) {
+  prior ??= {};
+  return {
+    ...prior,
+    kitVersion,
+    installRole: CONSUMER_INSTALL_ROLE,
+    readinessContractVersion: readiness?.contractVersion ?? READINESS_CONTRACT_VERSION,
+    readinessDecisions: retainedDecisions(prior, readiness),
+    installed: [],
+  };
 }
 
 /** Package entries without a role predate role-aware installs and remain consumer-owned. */

package/src/lib/updateReconcile.mjs

@@ -8,6 +8,7 @@ import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, emptyConsumerManifest,
   CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, KIT_ORIGIN, filesForInstallRole,
   indexByPath, readManifest, writeManifest,
+  readReadinessContract,
 } from './manifest.mjs';
 
 const exists = (path) => access(path).then(() => true, () => false);
@@ -18,6 +19,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
   if (!pkg) throw new Error('kit package manifest not found');
   const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!consumer) throw new Error('not initialised — run `init` first');
+  const readiness = await readReadinessContract(kitRoot);
 
   const installedIdx = indexByPath(consumer, 'installed');
   const packageIdx = indexByPath(pkg, 'files');
@@ -117,7 +119,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 
   if (!dryRun) {
     await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), {
-      ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled,
+      ...emptyConsumerManifest(pkg.kitVersion, consumer, readiness), installed: nextInstalled,
     });
   }
   return result;