@ikon85/agent-workflow-kit 0.34.4 → 0.34.6

package/docs/research/provider-neutral-agent-routing.md

@@ -0,0 +1,207 @@
+# Provider-neutral agent routing for shared work items
+
+**Researched:** 2026-07-22  
+**Question:** How should shared agent-workflow issues express model-routing intent across Claude Code and OpenAI Codex without embedding short-lived provider model names?
+
+## Recommendation
+
+Persist **task intent, not a model selection**, in shared issues. Use two small,
+provider-neutral fields:
+
+```yaml
+routing-intent: judgment | development | mechanical
+reasoning-intent: deep | balanced | light
+```
+
+The exact vocabulary is a Kit domain decision; the important constraint is that
+the values describe the work and desired trade-off, not Anthropic or OpenAI
+products. A surface-local resolver maps those values at dispatch time:
+
+```text
+shared issue intent
+        |
+        +-- Claude resolver -> current Claude alias/model + session effort
+        |
+        `-- Codex resolver  -> current Codex model + model_reasoning_effort
+```
+
+The default resolution must be `inherit` when no local policy exists or when a
+configured target cannot be proven usable. The orchestrator should report the
+effective resolution at session start, but it should not write that volatile
+result back into the issue.
+
+This separates three ownership layers:
+
+1. **Kit-owned schema and validation:** allowed intent values, inheritance,
+   diagnostics, and dispatch contract.
+2. **User/organization-owned surface policy:** how intent maps to models and
+   effort for that account, budget, provider, and current catalog.
+3. **Project-owned constraints, only when genuinely shared:** for example, a
+   prohibition on a model or a minimum capability required by every
+   collaborator. A project should not carry one maintainer's preferred model
+   mapping.
+
+## Verified platform facts
+
+### Claude Code
+
+Claude Code has Managed, User, Project, and Local scopes. For ordinary scalar
+settings, precedence is Managed, command-line, Local, Project, then User. A
+committed `.claude/settings.json` therefore affects all collaborators and
+overrides their user settings, while `.claude/settings.local.json` is personal
+and repository-specific ([Claude Code settings: scopes and precedence](https://code.claude.com/docs/en/settings#configuration-scopes)).
+
+Claude accepts provider aliases as well as full model IDs. Aliases such as
+`fable` and `sonnet` resolve to current models, while `default` returns to the
+runtime default for the account or organization. Aliases reduce version churn,
+but remain Claude-specific and do not encode a cross-provider task class
+([Claude Code model aliases](https://code.claude.com/docs/en/model-config#model-aliases)).
+
+The main-session model can be changed for a session with `/model` or at launch
+with `--model`; `ANTHROPIC_MODEL` and the persistent `model` setting are also
+supported. Organization restrictions and managed settings can replace or
+reject a requested selection, so a repository cannot assume that a named model
+is usable for every collaborator ([Claude Code model selection](https://code.claude.com/docs/en/model-config#setting-your-model),
+[Claude Code model restrictions](https://code.claude.com/docs/en/model-config#restrict-model-selection)).
+
+Claude subagent definitions support an alias, a full ID, or `inherit`; omission
+means `inherit`. Resolution currently considers
+`CLAUDE_CODE_SUBAGENT_MODEL`, a per-invocation value, subagent frontmatter, and
+finally the main conversation model. Excluded selections fall back to the
+inherited model. Extended-thinking configuration is inherited from the main
+conversation and has no per-subagent setting
+([Claude Code subagent model resolution](https://code.claude.com/docs/en/sub-agents#choose-a-model)).
+
+Claude effort levels are model-dependent. Unsupported levels are reduced to a
+supported level, organization policy can cap them, and some effort choices are
+session-only. Skill and subagent frontmatter can override the inherited session
+effort, subject to higher-precedence environment and organization constraints.
+Therefore a provider-neutral reasoning intent can be resolved on Claude, but a
+shared issue must not claim that one literal effort value has identical
+enforcement everywhere
+([Claude Code effort levels](https://code.claude.com/docs/en/model-config#adjust-effort-level),
+[Claude Code subagent effort](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields)).
+
+Anthropic exposes `GET /v1/models`, whose result describes models available to
+that API credential ([Anthropic Models API](https://platform.claude.com/docs/en/api/models/list)).
+That is not a universal Claude Code discovery contract: Claude Code may run
+through a Claude subscription, Bedrock, Vertex, Foundry, or a gateway. Gateway
+discovery is optional, limited to compatible `/v1/models` gateways, cached,
+and falls back to built-in entries if discovery fails
+([Claude Code gateway model discovery](https://code.claude.com/docs/en/llm-gateway#model-selection)).
+
+### OpenAI Codex
+
+Codex reads personal defaults from `~/.codex/config.toml` and project overrides
+from trusted `.codex/config.toml` files. Its documented precedence is CLI,
+project config, selected user profile, user config, system config, then built-in
+defaults. Consequently, a committed project routing table can override a
+collaborator's personal defaults; untrusted projects skip project-local layers
+entirely ([Codex configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)).
+
+Codex exposes `model` and `model_reasoning_effort` as separate configuration
+values ([Codex common configuration options](https://learn.chatgpt.com/docs/config-file/config-basic#common-configuration-options)).
+For custom subagents, a custom-agent file may override both. Otherwise each is
+resolved independently from an explicit spawn value, the `[agents]` default,
+and the parent session. Omitting a setting inherits it; changing the model
+without an explicit effort uses the selected model's default effort
+([Codex custom-agent resolution](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agents)).
+
+Official Codex guidance explicitly allows leaving both values unpinned so the
+runtime can balance capability, speed, and price. It also documents that
+available reasoning levels depend on the selected model
+([Codex choosing models and reasoning](https://learn.chatgpt.com/docs/agent-configuration/subagents#choosing-models-and-reasoning)).
+
+OpenAI exposes `GET /v1/models` for models available to an API key
+([OpenAI Models API](https://platform.openai.com/docs/api-reference/models/list)).
+The Codex documentation does not provide a stable, public model-discovery API
+for the effective catalog of every Codex/ChatGPT account and local client.
+An API-key catalog therefore cannot safely populate routing for users whose
+Codex authentication, plan, organization policy, or client surface differs.
+
+## Options compared
+
+| Option | Survives catalog changes | Works across Claude and Codex | Multi-user behavior | Offline/update behavior | Verdict |
+|---|---:|---:|---|---|---|
+| Concrete model names in issues | No. Every rename, replacement, or access change makes existing issues stale. | No. Names and effort controls are provider-specific. | Assumes every collaborator has the same entitlement and budget. | Old issues remain wrong until rewritten. | Reject. Suitable only for an explicit reproducibility pin in a provider-specific experiment. |
+| Stable task intent resolved by user/org surface policy | Yes. Existing issues survive mapping changes. | Yes. Each surface resolves independently or inherits. | Preserves personal and organization choices. | Cached/local policy continues to work; unknown targets can inherit and warn. | **Adopt.** |
+| Project-local concrete routing table | Partly. One table can be updated, but every checkout still receives volatile provider data. | Only by maintaining multiple provider sections. | Project config outranks user config on both surfaces, so the maintainer's preferences can override collaborators. | Fresh clones can start stale; offline discovery cannot repair it. | Reject as the default. Permit only explicit team policy/constraints. |
+
+## Setup and update implications
+
+### `setup-workflow`
+
+`setup-workflow` should install or reconcile only the Kit-owned intent schema,
+templates, validation, and a documented inheritance fallback. It may **offer**
+to create a user-local routing policy for the detected surface, but only with
+explicit consent and never as a committed project default.
+
+Setup must not attempt to infer a complete routing table from `/v1/models`:
+
+- API discovery requires credentials and network access.
+- API availability is not equivalent to Claude Code or Codex subscription
+  availability across all supported providers and account types.
+- A discovered model ID says nothing about the user's desired cost/capability
+  trade-off.
+
+An interactive setup may validate explicitly selected targets using the active
+surface and show a preview. Failure or absence of discovery should leave the
+policy at `inherit`, not install guessed names.
+
+### `kit-update`
+
+`kit-update` should update the Kit-owned schema, resolver implementation, and
+provider adapter capabilities transactionally. It must preserve user-owned
+mappings and project-owned constraints. If the schema changes, migration must
+be semantic (for example, rename an intent key), previewed, and reversible;
+ordinary updates must not rewrite historical issues or replace personal model
+choices.
+
+At dispatch, the resolver should:
+
+1. read the issue's stable intent;
+2. apply organization/user policy and explicit session overrides according to
+   the active surface;
+3. resolve or inherit without network-dependent mutation;
+4. reject a malformed intent, but fall back to `inherit` with a visible warning
+   when a volatile target is unavailable;
+5. record the effective model and effort in run evidence, not in the durable
+   issue contract.
+
+This lets a later Kit release improve mappings for users who accept Kit
+defaults while allowing a maintainer's user-local policy to evolve independently.
+
+## Implication for #213
+
+#213 should not hardcode `sol`, `terra`, `luna`, Claude aliases, or full model
+IDs into the issue template or validator. It should instead establish the
+provider-neutral intent schema and make `to-issues` emit that schema. The
+execute-ready check should reject concrete provider model recommendations in
+shared handoffs, while orchestration resolves the intent on the active surface.
+
+The existing free-text `Recommended model: <Model [Effort]>` field conflates a
+durable work classification with a volatile local decision. Replace it with
+machine-readable intent and render the effective local recommendation only
+when a session is actually dispatched.
+
+## Open risks and decisions
+
+1. **Vocabulary quality:** `judgment/development/mechanical` and
+   `deep/balanced/light` need task-based definitions and contract tests so they
+   do not become disguised provider tiers.
+2. **Enforcement asymmetry:** Both surfaces can override model and effort for
+   subagents, but their precedence, supported values, organization controls,
+   and fallback behavior differ. The Kit must promise intent resolution, not
+   identical low-level enforcement.
+3. **Unavailable targets:** silent substitution hides policy drift. Inheritance
+   should be visible in run evidence, and strict team policies may choose to
+   fail instead.
+4. **Organization policy:** managed restrictions outrank personal/project
+   wishes. The resolver must treat the surface's effective selection as
+   authoritative.
+5. **Reproducibility exception:** a benchmark or regression reproduction may
+   legitimately pin a provider/model snapshot. That is a distinct,
+   provider-specific execution constraint, not the normal issue-routing field.
+6. **No universal discovery source:** model catalogs are useful validation
+   inputs where available, but cannot be the SSOT for setup or updates across
+   all supported account types and providers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.34.4",
+  "version": "0.34.6",
   "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/kit-release.test.mjs

@@ -184,15 +184,21 @@ test('both release skill surfaces name only the owned scoped npm package', async
   }
 });
 
-test('an explicit AFK scope can authorize reversible preparation but never publication', async () => {
+// Amended by #257: one gate, at the Semver. The previous contract required a
+// second confirmation before the tag; that gate left prepared versions stranded
+// in `awaiting-tag` and is gone. What must survive is the narrowing rule — a
+// build-only request never becomes release authority.
+test('one confirmed Semver authorizes the release through tag and publish', async () => {
   const claude = await readFile(join(REPO, '.claude/skills/kit-release/SKILL.md'), 'utf8');
   const codex = await readFile(join(REPO, '.agents/skills/kit-release/SKILL.md'), 'utf8');
-  assert.equal(codex, claude);
+  assert.equal(codex.split('\n---\n')[1], claude.split('\n---\n')[1]);
   for (const body of [claude, codex]) {
     assert.match(body, /explicit AFK end-to-end mandate/i);
     assert.match(body, /deterministic recommendation/i);
-    assert.match(body, /reversible metadata preparation/i);
-    assert.match(body, /annotated `v<version>` tag[\s\S]*separate explicit confirmation/i);
+    assert.match(body, /annotated\s+`v<version>` tag/i);
+    assert.match(body, /confirmed Semver authorizes[\s\S]*without asking again/i);
+    assert.match(body, /narrower build-only or single-action request/i);
+    assert.doesNotMatch(body, /separate explicit confirmation/i);
   }
 });
 

package/scripts/kit-update-pr.mjs

@@ -11,7 +11,7 @@ export const UPDATE_TITLE = 'chore: update agent workflow kit';
 const UPDATE_BODY = [
   'Automated, parity-verified update of `@ikon85/agent-workflow-kit`.',
   '',
-  'The transactional update candidate passed the consumer test suite before this branch was published.',
+  'The transactional update candidate passed the built-in Kit invariants before this branch was published.',
   '',
   'This pull request is never merged automatically.',
 ].join('\n');

package/scripts/kit-update-pr.test.mjs

@@ -46,6 +46,8 @@ test('automated update pull requests carry the behavior availability summary', a
   assert.match(created.body, /## Availability/);
   assert.match(created.body, /newly degraded: orchestrate-wave\.projectRecipe/);
   assert.match(created.body, /still unresolved: orchestrateWaveRecipe:invalid/);
+  assert.match(created.body, /built-in Kit invariants/);
+  assert.doesNotMatch(created.body, /consumer test/i);
   assert.match(created.body, /never merged automatically/);
 });
 

package/scripts/test_release_authorization_contract.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Release-authorization contract (#257).
+
+The confirmed Semver authorizes the whole release, through tag and publish.
+One human gate at version choice, not two — the second gate stalled every
+release at `awaiting-tag` until someone returned, which is how 0.34.2 was
+skipped and buried under 0.34.3 (#243).
+
+What this pins:
+
+- Both `kit-release` surfaces carry the carried-through authorization, and
+  neither demands a separate confirmation before tagging.
+- The safety framing survives the change: irreversibility and the pre-tag
+  gates stay named, so autonomy never reads as "tag whatever".
+- `CLAUDE.md`, `AGENTS.md` and ADR-0004 agree with the skill.
+
+Run: python3 scripts/test_release_authorization_contract.py
+"""
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (".claude/skills/kit-release/SKILL.md", ".agents/skills/kit-release/SKILL.md")
+ADR = "docs/adr/0004-release-intent-is-a-version-tag.md"
+DOCTRINE_FILES = ("CLAUDE.md", "AGENTS.md")
+# Wording that would reinstate the second gate anywhere in the release surface.
+SECOND_GATE = (
+    "separate explicit confirmation",
+    "separately confirmed publication intent",
+    "obtain a separate",
+    "After that confirmation",
+)
+
+
+def read(relative: str) -> str:
+    return (ROOT / relative).read_text(encoding="utf-8")
+
+
+def normalized(relative: str) -> str:
+    return " ".join(read(relative).split())
+
+
+class SkillSurfaceContract(unittest.TestCase):
+    def test_both_surfaces_carry_the_authorization_through_to_the_tag(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("confirmed Semver authorizes", prose)
+                self.assertIn("tag and publish", prose)
+                self.assertIn("without asking again", prose)
+
+    def test_no_surface_reinstates_a_second_confirmation_gate(self):
+        for surface in SURFACES:
+            for phrase in SECOND_GATE:
+                with self.subTest(surface=surface, phrase=phrase):
+                    self.assertNotIn(phrase, normalized(surface))
+
+    def test_autonomy_never_drops_the_safety_framing(self):
+        """Tagging stays irreversible and gated — the gates just move earlier."""
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("irreversible", prose)
+                self.assertIn("cannot be reused", prose)
+                for gate in ("release:guard", "kit:staleness", "npm pack"):
+                    self.assertIn(gate, prose)
+
+    def test_the_tag_remains_the_sole_publication_intent(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("Merging integrates", prose)
+                self.assertIn("annotated", prose)
+
+    def test_both_surfaces_stay_mirrored_below_the_frontmatter(self):
+        bodies = [read(surface).split("\n---\n", 1)[1] for surface in SURFACES]
+        self.assertEqual(bodies[0], bodies[1])
+
+
+class ProjectDoctrineContract(unittest.TestCase):
+    def test_root_convention_files_agree_with_the_skill(self):
+        for name in DOCTRINE_FILES:
+            with self.subTest(document=name):
+                prose = normalized(name)
+                self.assertIn("confirmed Semver authorizes", prose)
+                for phrase in SECOND_GATE:
+                    self.assertNotIn(phrase, prose)
+
+    def test_the_adr_records_an_amendment_instead_of_a_silent_rewrite(self):
+        prose = normalized(ADR)
+        self.assertIn("Amended", prose)
+        self.assertIn("2026-07-25", prose)
+        self.assertIn("confirmed Semver authorizes", prose)
+        # The original decision must remain readable, not be overwritten.
+        self.assertIn("version tag", prose)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_skill_readiness_contract.py

@@ -56,7 +56,12 @@ for (const skill of Object.keys(fixture.readinessFixture.skills)) {
 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 candidateManifest = structuredClone(manifest);
+  for (const [name, declaration] of Object.entries(candidateManifest.skills)) {
+    declaration.publish = name === 'to-prd';
+    if (name === 'to-prd') declaration.surfaces = ['claude'];
+  }
+  const content = `${JSON.stringify(candidateManifest, null, 2)}\n`;
   const path = join(kit, readinessPath);
   await mkdir(join(kit, '.claude/skills'), { recursive: true });
   await writeFile(path, content);

package/scripts/test_skill_setup_workflow_seeds.py

@@ -49,13 +49,12 @@ def classify(first_line, is_empty):
 
 
 def update_workflow_action(
-    provider, choice, destination_exists, prerequisites=True,
-    pull_requests_allowed=True,
+    provider, choice, destination_exists, pull_requests_allowed=True,
 ):
     """Reference decision table for the prompt-driven setup contract."""
     if provider != "github" or destination_exists or choice != "enable":
         return "skip"
-    return "create" if prerequisites and pull_requests_allowed else "skip"
+    return "create" if pull_requests_allowed else "skip"
 
 
 def load_census_setup_effects():
@@ -421,19 +420,18 @@ class SeedTemplatesValid(unittest.TestCase):
 
     def test_update_workflow_provider_and_choice_fixtures(self):
         fixtures = [
-            ("github", "enable", False, True, True, "create"),
-            ("github", "opt-out", False, True, True, "skip"),
-            ("github", "later", False, True, True, "skip"),
-            ("github", "enable", True, True, True, "skip"),
-            ("github", "enable", False, False, True, "skip"),
-            ("github", "enable", False, True, False, "skip"),
-            ("gitlab", "enable", False, True, True, "skip"),
-            ("local", "enable", False, True, True, "skip"),
+            ("github", "enable", False, True, "create"),
+            ("github", "opt-out", False, True, "skip"),
+            ("github", "later", False, True, "skip"),
+            ("github", "enable", True, True, "skip"),
+            ("github", "enable", False, False, "skip"),
+            ("gitlab", "enable", False, True, "skip"),
+            ("local", "enable", False, True, "skip"),
         ]
-        for provider, choice, exists, prerequisites, allowed, expected in fixtures:
+        for provider, choice, exists, allowed, expected in fixtures:
             self.assertEqual(
                 update_workflow_action(
-                    provider, choice, exists, prerequisites, allowed,
+                    provider, choice, exists, allowed,
                 ), expected,
             )
 
@@ -446,8 +444,8 @@ class SeedTemplatesValid(unittest.TestCase):
             "Ask later",
             "GitHub tracker",
             "skipped (already present)",
-            "package-lock.json",
-            "npm test",
+            "built-in Kit invariant validator",
+            "no Consumer package script",
             "can_approve_pull_request_reviews",
             "Allow GitHub Actions to create and approve pull requests",
             "explicit confirmation",
@@ -461,10 +459,13 @@ class SeedTemplatesValid(unittest.TestCase):
             "schedule:", "workflow_dispatch:", "contents: write",
             "pull-requests: write", "agent-workflow-kit-update-pr",
             "@ikon85/agent-workflow-kit@latest", "fetch-depth: 0",
-            "node-version: 22.14", "npm ci --ignore-scripts",
+            "node-version: 22.14", "Verify and upsert the Kit update pull request",
         ):
             self.assertIn(token, workflow)
-        for forbidden in ("npm_token", "NPM_TOKEN", "auto-merge", "gh pr merge"):
+        for forbidden in (
+            "npm_token", "NPM_TOKEN", "auto-merge", "gh pr merge",
+            "npm ci", "npm test", "package-lock.json",
+        ):
             self.assertNotIn(forbidden, workflow)
 
         mirror = (REPO / ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml")

package/src/commands/update.mjs

@@ -2,8 +2,11 @@ import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { assertConsumerReleaseParity } from '../../scripts/release-parity.mjs';
 import {
-  activateCandidate, adoptReadinessCandidate, readReadinessManifest, stageConsumer, verifyCandidate,
+  activateCandidate, adoptReadinessCandidate, materializeUpdateCandidate, readReadinessManifest,
 } from '../lib/updateCandidate.mjs';
+import {
+  verifyCandidateSchema, verifyUpdateCandidate,
+} from '../lib/verifyUpdateCandidate.mjs';
 import { reconcile } from '../lib/updateReconcile.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
@@ -46,7 +49,7 @@ export async function update(options) {
 async function updatePackage(options) {
   const {
     kitRoot, consumerRoot, decide = () => false, dryRun = false,
-    releaseIdentities, verify = verifyCandidate, activate = activateCandidate,
+    releaseIdentities, verify = verifyUpdateCandidate, activate = activateCandidate,
     signal, onState = () => {}, resumeFrom,
   } = options;
   const history = [];
@@ -57,7 +60,8 @@ async function updatePackage(options) {
   if (!pkg) throw new Error('kit package manifest not found');
   if (!dryRun) verifyRelease(releaseIdentities, pkg.kitVersion);
   const consumerManifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
-  if (!await readManifest(consumerManifestPath)) {
+  const priorConsumerManifest = await readManifest(consumerManifestPath);
+  if (!priorConsumerManifest) {
     throw new Error('not initialised — run `init` first');
   }
   const consumerManifestBefore = await readFile(consumerManifestPath);
@@ -75,7 +79,7 @@ async function updatePackage(options) {
   let previewFailure;
   try {
     Object.assign(preview, await previewReadinessAdoption({
-      kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest,
+      kitRoot, consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
     }));
     preview.conflicts.push(...(preview.migrationConflicts ?? []).map((path) => ({
       path,
@@ -108,18 +112,26 @@ async function updatePackage(options) {
   }
   return applyTransaction({
     kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, activate, signal, resumeFrom,
-    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
+    consumerManifestBefore, priorConsumerManifest,
+    priorReadinessManifest, nextReadinessManifest, history, transition,
   });
 }
 
 async function previewReadinessAdoption(context) {
-  const { kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest } = context;
-  const candidateRoot = await stageConsumer(consumerRoot);
+  const {
+    kitRoot, consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+  } = context;
+  const candidateRoot = await materializeUpdateCandidate({
+    consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+  });
   try {
-    await reconcile({
+    const candidatePreview = await reconcile({
       kitRoot, consumerRoot: candidateRoot,
       decide: (action) => action === 'collision' ? 'keep-as-owned' : false,
     });
+    await verifyCandidateSchema(candidateRoot, {
+      pkg, preview: candidatePreview, priorReadinessManifest, nextReadinessManifest,
+    });
     return await adoptReadinessCandidate({
       candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
       nextManifest: nextReadinessManifest,
@@ -146,7 +158,8 @@ async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decid
 async function applyTransaction(context) {
   const {
     kitRoot, consumerRoot, pkg, preview, decisions, verify, activate, signal, resumeFrom,
-    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
+    consumerManifestBefore, priorConsumerManifest,
+    priorReadinessManifest, nextReadinessManifest, history, transition,
   } = context;
   let candidateRoot = resumeFrom;
   let keepCandidate = false;
@@ -157,12 +170,29 @@ async function applyTransaction(context) {
       throw new Error('collision-bearing candidate cannot be resumed safely');
     }
     if (!candidateRoot) {
-      candidateRoot = await stageConsumer(consumerRoot);
+      candidateRoot = await materializeUpdateCandidate({
+        consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+      });
       await reconcile({
         kitRoot, consumerRoot: candidateRoot,
         decide: (action, path) => decisions.get(decisionKey(action, path)),
       });
     }
+    phase = 'verification';
+    await transition('verifying');
+    const abort = async () => {
+      keepCandidate = true;
+      return { ...await terminal(preview, 'aborted', history, transition), candidateRoot };
+    };
+    if (signal?.aborted) return abort();
+    const canonicalContext = {
+      pkg: structuredClone(pkg),
+      preview: structuredClone(preview),
+      priorConsumerManifest: structuredClone(priorConsumerManifest),
+      priorReadinessManifest: structuredClone(priorReadinessManifest),
+      nextReadinessManifest: structuredClone(nextReadinessManifest),
+    };
+    await verifyCandidateSchema(candidateRoot, canonicalContext);
     const readiness = await adoptReadinessCandidate({
       candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
       nextManifest: nextReadinessManifest,
@@ -178,18 +208,20 @@ async function applyTransaction(context) {
     if (readiness.incompatible.length) {
       throw new Error(`monotonic compatibility would block existing skill core: ${readiness.incompatible.join(', ')}`);
     }
-    phase = 'verification';
-    await transition('verifying');
-    const abort = async () => {
-      keepCandidate = true;
-      return { ...await terminal(preview, 'aborted', history, transition), candidateRoot };
-    };
-    if (signal?.aborted) return abort();
-    await verify(candidateRoot);
+    canonicalContext.preview = structuredClone(preview);
+    await verifyUpdateCandidate(candidateRoot, canonicalContext);
+    if (verify !== verifyUpdateCandidate) {
+      const extensionContext = structuredClone(canonicalContext);
+      await verify(candidateRoot, extensionContext);
+      await verifyUpdateCandidate(candidateRoot, canonicalContext);
+    }
     if (signal?.aborted) return abort();
     phase = 'activation';
     await activate({
-      candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+      candidateRoot, consumerRoot,
+      pkg: canonicalContext.pkg,
+      preview: canonicalContext.preview,
+      consumerManifestBefore,
     });
     return { ...await terminal(preview, 'applied', history, transition), status: 'updated' };
   } catch (error) {
@@ -252,4 +284,4 @@ async function terminal(result, state, history, transition) {
   };
 }
 
-export { verifyCandidate } from '../lib/updateCandidate.mjs';
+export { verifyUpdateCandidate, verifyUpdateCandidate as verifyCandidate } from '../lib/verifyUpdateCandidate.mjs';

package/src/lib/bundle.mjs

@@ -107,7 +107,7 @@ export const HELPER_FILES = [
   // wave. Library (imported by the Phase-0 claim protocol) → 0o644.
   { path: 'src/lib/waveClaim.mjs', kind: 'script', mode: 0o644 },
   // GitHub-consumer automation: invokes the existing update command, then owns
-  // only the stable tested branch/pull-request upsert.
+  // only the stable Kit-verified branch/pull-request upsert.
   { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },
   // Stdlib-only project census foundation. index.mjs is the stable consumer
   // entrypoint; its five local modules must ship with it as one helper unit.