@dzhechkov/harness-core 0.8.5 → 0.8.6

package/src/feature-adr-routing.ts

@@ -14,8 +14,8 @@
  *
  * The load-bearing property: a model that WRITES code must not also SELF-QE.
  * When `args.models.qe` is unset, the QE stage is auto-routed to the OTHER
- * family than the resolved coder (codex-coder → Claude `opus`; Claude-coder →
- * `codex:<top>:high`, or `opus` if codex is unavailable — never a block).
+ * family than the resolved coder (codex-coder → Claude `sonnet`; Claude-coder →
+ * the Codex-budget cell, or `opus` if codex is unavailable — never a block).
  *
  * DESIGN CONSTRAINT — the Workflow parser is STRICTER than `node --check`
  * (no nested template literals, no inline `cond ? agent() : null` in arrays).
@@ -74,11 +74,15 @@ export interface RoutingEnv {
    */
   readonly usageOverride?: boolean;
   /**
-   * Per-stage reasoning for the usage-override spec (merged OVER {@link OVERRIDE_REASONING}).
-   * `args.usageReasoning` — stage → `'high'|'xhigh'|…`; a single stage may be overridden without
+   * Per-stage reasoning for the usage-override spec (merged OVER {@link STAGE_EFFORT}).
+   * `args.usageReasoning` — stage → a supported reasoning level; a single stage may be overridden without
    * touching the others.
    */
   readonly usageReasoning?: Record<string, string>;
+  /** Raw `args.budget`: a named preset or a per-family object. */
+  readonly budget?: unknown;
+  /** The productive family for design + code; absent defaults to Claude. */
+  readonly primary?: 'claude' | 'codex';
 }
 
 // ── USAGE-ADAPTIVE ROUTING (pre-emptive codex switch at >= usageThreshold) ────
@@ -109,39 +113,33 @@ export interface UsageDecision {
 }
 
 /**
- * Per-stage reasoning applied under the usage override (LOCKED L-4, arch §4.1 verbatim):
- * design/code/plan stages ⇒ `xhigh`; router/qe/fleet ⇒ `high`. A pure DATA table (not control
- * flow); user-overridable via `env.usageReasoning`. An unknown stage falls back to `'high'`.
+ * GPT-5.6 reasoning ladder used by the routing tables. The model default is `medium`; `xhigh`
+ * and `max` stay valid explicit values but are absent from shipped defaults until evals justify them.
  */
-export const OVERRIDE_REASONING: Record<string, 'high' | 'xhigh'> = {
-  router: 'high',
-  requirements: 'xhigh',
-  research: 'xhigh',
-  adr: 'xhigh',
-  ideation: 'xhigh',
-  ddd: 'xhigh',
-  architecture: 'xhigh',
-  plan: 'xhigh',
-  code: 'xhigh',
+export type ReasoningLevel = 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export const STAGE_EFFORT: { override: Record<string, ReasoningLevel> } = { override: {
+  router: 'medium',
+  requirements: 'medium',
+  research: 'medium',
+  adr: 'high',
+  ideation: 'medium',
+  ddd: 'high',
+  architecture: 'high',
+  plan: 'high',
+  code: 'medium',
   qe: 'high',
-  fleet: 'high',
-};
+  fleet: 'medium',
+} };
 
-/**
- * The gpt-5.6-ready TOP codex-id pick — SHARED by the cross-model QE default and the usage
- * override so adding an id to {@link KNOWN_CODEX} (e.g. `gpt-5.7`) retargets BOTH with zero
- * control-flow diff (AC-3). Pinned `CODEX_MODEL` when ≠ `'auto'`; else the last non-`auto` key of
- * `KNOWN_CODEX`.
- */
+/** One-release compatibility alias for existing public imports. */
+// Frozen (QE round-1 F10): the alias exports the SAME object as the live effort table, so a
+// consumer mutating the compatibility alias would silently mutate shipped routing. Freezing keeps
+// the read-compatibility promise while making any such write throw loudly in strict mode.
+export const OVERRIDE_REASONING = Object.freeze(STAGE_EFFORT.override);
+
+/** The flagship Codex id, independent of the spellability allowlist's insertion order. */
 export function topCodexId(env: RoutingEnv): string {
-  let top = env.CODEX_MODEL;
-  if (top === 'auto') {
-    const ids = Object.keys(KNOWN_CODEX);
-    for (let i = 0; i < ids.length; i++) {
-      if (ids[i] !== 'auto') top = ids[i] || top;
-    }
-  }
-  return top;
+  return env.CODEX_MODEL !== 'auto' ? env.CODEX_MODEL : CODEX_TIERS.flagship;
 }
 
 /**
@@ -190,11 +188,80 @@ export function decideUsageAction(
 /** Known codex ids. Adding a new id (e.g. `'gpt-5.7'`) is a DATA-ONLY change. */
 export const KNOWN_CODEX: Record<string, number> = { auto: 1, 'gpt-5.5': 1, 'gpt-5.6': 1, 'gpt-5.6-luna': 1, 'gpt-5.6-terra': 1, 'gpt-5.6-sol': 1 };
 
+export type CodexTier = 'flagship' | 'workhorse' | 'high-volume';
+
+/**
+ * Capability tiers are routing data, separate from {@link KNOWN_CODEX}'s spellability role.
+ * The allowlist is not an availability check — probe every id before every run
+ * (`codex exec -m <id> "Reply with exactly: OK"`); ids drift in both directions on a
+ * timescale of days (probed 2026-08-18: 3 ids HTTP 400; probed 2026-08-29: all 3 exit 0).
+ */
+export const CODEX_TIERS: Record<CodexTier, string> = {
+  flagship: 'gpt-5.6-sol',
+  workhorse: 'gpt-5.6-terra',
+  'high-volume': 'gpt-5.6-luna',
+};
+
+export function codexIdForTier(tier: CodexTier, env: RoutingEnv): string {
+  return env.CODEX_MODEL !== 'auto' ? env.CODEX_MODEL : CODEX_TIERS[tier];
+}
+
+export type BudgetLevel = 'normal' | 'eco';
+export interface BudgetAxis {
+  readonly claude: BudgetLevel;
+  readonly codex: BudgetLevel;
+}
+
+export const BUDGET_PRESETS: Record<'normal' | 'eco' | 'hybrid', BudgetAxis> = {
+  normal: { claude: 'normal', codex: 'normal' },
+  eco: { claude: 'eco', codex: 'eco' },
+  hybrid: { claude: 'eco', codex: 'normal' },
+};
+
+export function resolveBudgetMode(raw: unknown): BudgetAxis {
+  if (raw === undefined) return BUDGET_PRESETS.normal;
+  if (typeof raw === 'string') {
+    const preset = BUDGET_PRESETS[raw as keyof typeof BUDGET_PRESETS];
+    if (!preset) throw new RangeError('budget: unknown preset "' + raw + '" — valid: normal|eco|hybrid');
+    return preset;
+  }
+  if (raw && typeof raw === 'object') {
+    const value = raw as Record<string, unknown>;
+    for (const key of Object.keys(value)) {
+      if (key !== 'claude' && key !== 'codex') {
+        throw new RangeError('budget: unknown family key "' + key + '" — valid: claude|codex');
+      }
+    }
+    for (const key of ['claude', 'codex'] as const) {
+      const level = value[key];
+      if (level !== undefined && level !== 'normal' && level !== 'eco') {
+        throw new RangeError('budget.' + key + ': unknown level "' + level + '" — valid: normal|eco');
+      }
+    }
+    return {
+      claude: (value.claude as BudgetLevel | undefined) || 'normal',
+      codex: (value.codex as BudgetLevel | undefined) || 'normal',
+    };
+  }
+  throw new RangeError('budget: expected a preset name or {claude,codex} object, got ' + typeof raw);
+}
+
+export function budgetPresetName(axis: BudgetAxis): 'normal' | 'eco' | 'hybrid' | null {
+  for (const name of ['normal', 'eco', 'hybrid'] as const) {
+    const preset = BUDGET_PRESETS[name];
+    if (preset.claude === axis.claude && preset.codex === axis.codex) return name;
+  }
+  return null;
+}
+
 /** The Claude model names the Workflow runtime accepts as `agent()` `model`. */
 export const CLAUDE_NAMES: Record<string, number> = { fable: 1, opus: 1, sonnet: 1, haiku: 1 };
 
-/** The codex-companion `--effort` vocabulary; a spec's `<reasoning>` is clamped to this (unknown ⇒ 'high'). */
-export const VALID_REASONING: Record<string, number> = { none: 1, minimal: 1, low: 1, medium: 1, high: 1, xhigh: 1 };
+/**
+ * The codex-companion `--effort` vocabulary. `minimal` remains temporarily for compatibility
+ * until a live companion probe establishes whether it can be retired; `max` is part of GPT-5.6's ladder.
+ */
+export const VALID_REASONING: Record<string, number> = { none: 1, minimal: 1, low: 1, medium: 1, high: 1, xhigh: 1, max: 1 };
 
 /**
  * The proven DEFAULT TABLE, applied only when the user opts into routing.
@@ -215,6 +282,80 @@ export const DEFAULT_MODELS: Record<string, string | null> = {
   fleet: 'sonnet',
 };
 
+type FamilyRoutingTables = Record<'claude' | 'codex', Record<BudgetLevel, Partial<Record<string, string | null>>>>;
+
+/** Four family half-tables; presets compose the Claude and Codex halves independently. */
+export const ROUTING_TABLES: Record<'claude' | 'codex', FamilyRoutingTables> = {
+  claude: {
+    claude: {
+      normal: { router: 'sonnet', requirements: 'sonnet', research: 'sonnet', adr: 'fable', ideation: 'sonnet', ddd: 'fable', architecture: 'fable', plan: 'opus', code: 'sonnet', fleet: 'sonnet' },
+      eco: { router: 'sonnet', requirements: 'sonnet', research: 'sonnet', adr: 'opus', ideation: 'sonnet', ddd: 'opus', architecture: 'opus', plan: 'sonnet', code: 'sonnet', fleet: 'sonnet' },
+    },
+    codex: { normal: {}, eco: {} },
+  },
+  codex: {
+    claude: {
+      normal: { router: 'sonnet', qe: 'sonnet', fleet: 'sonnet' },
+      eco: { router: 'sonnet', qe: 'sonnet', fleet: 'sonnet' },
+    },
+    codex: { normal: {}, eco: {} },
+  },
+};
+
+function codexCell(tier: CodexTier, effort: ReasoningLevel, env: RoutingEnv): string {
+  return 'codex:' + codexIdForTier(tier, env) + ':' + effort;
+}
+
+export function budgetTable(
+  primary: 'claude' | 'codex',
+  mode: BudgetAxis,
+  env: RoutingEnv,
+): Partial<Record<string, string | null>> {
+  const claudeHalf = ROUTING_TABLES[primary].claude[mode.claude];
+  let codexHalf: Partial<Record<string, string | null>>;
+  if (primary === 'claude') {
+    const qeSpec = mode.codex === 'normal'
+      ? codexCell('flagship', 'high', env)
+      : codexCell('workhorse', 'medium', env);
+    codexHalf = { ...ROUTING_TABLES.claude.codex[mode.codex], qe: env.codexAvailable === false ? 'opus' : qeSpec };
+  } else {
+    const normal = mode.codex === 'normal';
+    const design = codexCell(normal ? 'flagship' : 'workhorse', normal ? 'high' : 'medium', env);
+    codexHalf = {
+      requirements: design,
+      research: design,
+      adr: design,
+      ideation: design,
+      ddd: design,
+      architecture: design,
+      plan: codexCell(normal ? 'flagship' : 'workhorse', normal ? 'high' : 'low', env),
+      code: codexCell(normal ? 'flagship' : 'workhorse', 'medium', env),
+    };
+  }
+  return { ...claudeHalf, ...codexHalf };
+}
+
+/** Optional Claude precision review after A-normal's recall-oriented Sonnet QE. */
+export function qePrecisionPassSpec(
+  primary: 'claude' | 'codex',
+  budget: BudgetAxis,
+  tier: 'S' | 'M' | 'L' | 'XL',
+  _env: RoutingEnv,
+): string | null {
+  if (primary !== 'codex') return null;
+  if (budget.claude !== 'normal') return null;
+  if (tier !== 'L' && tier !== 'XL') return null;
+  return 'opus';
+}
+
+/** Build/test-time guard for the matrix's load-bearing cross-family property. */
+export function assertCrossFamilyQe(codeSpec: string | null, qeSpec: string | null): void {
+  const fam = (s: string | null) => (s && String(s).split(':')[0] === 'codex') ? 'codex' : 'claude';
+  if (fam(codeSpec) === fam(qeSpec)) {
+    throw new Error('cross-family QE violated: code=' + codeSpec + ' qe=' + qeSpec);
+  }
+}
+
 // ── Pure resolvers (byte-equivalent to the workflow's inline block) ──────────
 
 /**
@@ -247,11 +388,8 @@ export function specToOpts(spec: string | null | undefined, env: RoutingEnv): St
       id = env.CODEX_MODEL;
     }
     let reasoning = parts[2] || 'high';
-    // Clamp to the codex-companion --effort vocabulary so a bad token (e.g. `codex:gpt-5.6:banana`)
-    // can't silently reach the runtime as `--effort banana` (QE LOW). Unknown ⇒ 'high'.
     if (!VALID_REASONING[reasoning]) {
-      log('models: unknown reasoning ' + reasoning + ' — using high');
-      reasoning = 'high';
+      throw new RangeError('models: invalid reasoning "' + reasoning + '" — valid: ' + Object.keys(VALID_REASONING).join('|'));
     }
     return { agentType: 'codex:codex-rescue', codexModel: id, _reasoning: reasoning };
   }
@@ -278,33 +416,43 @@ export function resolveCoderSpec(env: RoutingEnv): string {
  * `MODELS.code='codex'` still routes QE to Claude (never codex-self-QE).
  */
 export function coderIsCodex(env: RoutingEnv): boolean {
-  if (env.CODER === 'codex' || env.CODER === 'codex-fallback') return true;
   const codeSpec = env.MODELS.code;
-  if (codeSpec && String(codeSpec).split(':')[0] === 'codex') return true;
-  return false;
+  if (codeSpec !== undefined && codeSpec !== null) return String(codeSpec).split(':')[0] === 'codex';
+  if (env.CODER === 'codex' || env.CODER === 'codex-fallback') return true;
+  return env.primary === 'codex';
 }
 
 /**
  * The CROSS-MODEL QE default (load-bearing). Called only when `MODELS.qe` is
  * unset. Resolves to the OTHER family than the coder:
- *   - coder is codex  → `'opus'`                       (Claude reviews codex's code)
- *   - coder is Claude → codex-available ? `'codex:<top>:high'` : `'opus'` (never block)
- * `<top>` = `CODEX_MODEL` when pinned (≠'auto'), else the top `KNOWN_CODEX` id.
+ *   - coder is codex  → `'sonnet'` (the recall-oriented Claude reviewer)
+ *   - coder is Claude → the Codex-budget cell (`sol:high` or `terra:medium`),
+ *     or `'opus'` when Codex is unavailable (never block)
+ * A pinned `CODEX_MODEL` still outranks the tier selected by the budget table.
  */
-export function resolveQeSpec(env: RoutingEnv): string {
-  if (coderIsCodex(env)) return 'opus';
+export function resolveQeSpecForCoder(coderCodex: boolean, env: RoutingEnv): string {
+  if (coderCodex) return 'sonnet';
   const CODEX_AVAILABLE = env.codexAvailable !== false;
   if (!CODEX_AVAILABLE) return 'opus';
-  return 'codex:' + topCodexId(env) + ':high';
+  const budget = resolveBudgetMode(env.budget);
+  return budget.codex === 'eco'
+    ? 'codex:' + codexIdForTier('workhorse', env) + ':medium'
+    : 'codex:' + codexIdForTier('flagship', env) + ':high';
+}
+
+export function resolveQeSpec(env: RoutingEnv): string {
+  return resolveQeSpecForCoder(coderIsCodex(env), env);
 }
 
 /**
- * Whether the caller opted into routing at all. When FALSE (no `args.models`,
- * no codex knobs), every Claude stage resolves to `{}` → byte-identical to today.
+ * Whether the caller opted into routing at all. When FALSE (no axes, `args.models`,
+ * or Codex knobs), every Claude stage resolves to `{}` → byte-identical to today.
  */
 export function routingRequested(env: RoutingEnv): boolean {
   return (
     Object.keys(env.MODELS).length > 0 ||
+    env.primary !== undefined ||
+    env.budget !== undefined ||
     env.PLANNER === 'codex' ||
     env.CODER === 'codex' ||
     env.CODER === 'codex-fallback' ||
@@ -338,12 +486,12 @@ export function qeShouldUseCodex(env: RoutingEnv): boolean {
  * Resolve a stage to its `agent()` opts fragment.
  *   1. explicit `MODELS[stage]` wins
  *   2. else if the user did NOT opt into routing → `{}` (byte-identical BC path)
- *   3. else the DEFAULT TABLE fills the gap
+ *   3. else the primary × per-family-budget table fills the gap
  *   4. `code`/`qe` `null` sentinels resolve via the coder / cross-model rules
  */
 export function resolveStageModel(stage: string, env: RoutingEnv): StageOpts {
   if (env.usageOverride) {
-    const r = (env.usageReasoning && env.usageReasoning[stage]) || OVERRIDE_REASONING[stage] || 'high';
+    const r = (env.usageReasoning && env.usageReasoning[stage]) || STAGE_EFFORT.override[stage] || 'medium';
     const o = specToOpts('codex:' + topCodexId(env) + ':' + r, env);
     o._usageSwitched = true;
     return o;
@@ -351,7 +499,18 @@ export function resolveStageModel(stage: string, env: RoutingEnv): StageOpts {
   let spec = env.MODELS[stage];
   if (spec === undefined) {
     if (!routingRequested(env)) return {};
-    spec = DEFAULT_MODELS[stage];
+    if (stage === 'code' && (env.CODER === 'codex' || env.CODER === 'codex-fallback')) {
+      return specToOpts(resolveCoderSpec(env), env);
+    }
+    if (stage === 'plan' && env.PLANNER === 'codex') {
+      return specToOpts('codex:' + env.CODEX_MODEL + ':high', env);
+    }
+    if (stage === 'qe') {
+      return specToOpts(resolveQeSpec(env), env);
+    }
+    const resolvedPrimary = env.primary || 'claude';
+    const cell = budgetTable(resolvedPrimary, resolveBudgetMode(env.budget), env)[stage];
+    spec = cell !== undefined ? cell : DEFAULT_MODELS[stage];
   }
   if (stage === 'code' && (spec === null || spec === undefined)) return specToOpts(resolveCoderSpec(env), env);
   if (stage === 'qe' && (spec === null || spec === undefined)) return specToOpts(resolveQeSpec(env), env);
@@ -1545,6 +1704,7 @@ function codexCd(repo: string): string {
  */
 export function codexExecCommand(input: {
   readonly modelId?: string | null;
+  readonly reasoning?: string | null;
   readonly prompt?: string | null;
   readonly timeoutBin?: string | null;
   readonly timeoutSeconds?: number | null;
@@ -1553,12 +1713,15 @@ export function codexExecCommand(input: {
   const o = input || {};
   const modelId = String(o.modelId === undefined || o.modelId === null ? '' : o.modelId);
   if (!isSafeCodexId(modelId)) return null;
+  const reasoning = o.reasoning === undefined || o.reasoning === null || o.reasoning === '' ? 'high' : String(o.reasoning);
+  if (!VALID_REASONING[reasoning]) return null;
   const raw = Number(o.timeoutSeconds);
   const seconds = raw === raw && raw !== Infinity && raw > 0 ? Math.floor(raw) : CODEX_EXEC_TIMEOUT_SECONDS;
   const repo = String(o.repo === undefined || o.repo === null ? '' : o.repo);
   const cd = repo === '' ? '' : ' -C ' + codexSq(repo);
   return timeoutBinOrDefault(o.timeoutBin) + ' ' + seconds + ' codex exec' + cd
-    + ' -m ' + codexSq(modelId) + ' ' + codexSq(String(o.prompt === undefined || o.prompt === null ? '' : o.prompt)) + ' < /dev/null';
+    + ' -m ' + codexSq(modelId) + ' -c model_reasoning_effort=' + codexSq(reasoning)
+    + ' ' + codexSq(String(o.prompt === undefined || o.prompt === null ? '' : o.prompt)) + ' < /dev/null';
 }
 
 export function codexReviewCommand(input: CodexReviewCommandInput): CodexReviewCommandResult {

package/src/guard.ts

@@ -69,6 +69,29 @@ export interface GuardFacts {
   readonly counts?: readonly { readonly label: string; readonly a: number; readonly b: number }[];
   /** for store-bloat-cap: current learned-store size vs its cap. */
   readonly store?: { readonly count: number; readonly cap: number };
+  /** Advisory freshness evidence for the auto-cost outcome store. Missing evidence fails open. */
+  readonly routingFreshness?: { readonly unfedRunIds: readonly string[] };
+  /**
+   * for marketplace-parity: the CLI's read-only regeneration result. The whole field being absent
+   * means evidence could not be gathered, so this advisory rule reports nothing.
+   */
+  readonly marketplaceParity?: {
+    /** false ⇒ this repository has no .claude-plugin/ showcase and is out of scope. */
+    readonly applicable: boolean;
+    /** true ⇒ exactly one of plugin.json / marketplace.json is present. */
+    readonly onlyOnePresent?: boolean;
+    /** true ⇒ registry-derived composition differs from a fresh regeneration. */
+    readonly diverged?: boolean;
+    /** Operator-owned published version, carried only to render the exact repair command. */
+    readonly publishedVersion?: string;
+    /** Existing published manifests that could not be read or parsed. */
+    readonly manifestFailures?: readonly {
+      readonly file: 'plugin.json' | 'marketplace.json';
+      readonly error: string;
+    }[];
+    /** true ⇒ regeneration was attempted but could not complete. */
+    readonly regenerateFailed?: boolean;
+  };
   /** for skills-registrable: per skill pack, dirs that would ship un-registrable (no depth-1 SKILL.md). */
   readonly skillPacks?: readonly { readonly name: string; readonly nonRegistrable: readonly string[] }[];
   /** for readme-first: per publishable package, is a version bump staged without a README change? */
@@ -262,6 +285,8 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'readme-consistency', severity: 'soft', ops: ['publish'], description: 'README counts agree (CJM header vs All Commands, etc.)' },
   { id: 'skills-registrable', severity: 'soft', ops: ['publish'], description: 'every skill directory in a skill pack has a depth-1 SKILL.md (a buried or missing one ships un-registrable — the health-advisor 1.2.0 class)' },
   { id: 'readme-first', severity: 'soft', ops: ['publish'], description: 'a package with a staged version bump must update its own README.md in the same change (README-first)' },
+  { id: 'routing-store-stale', severity: 'soft', ops: ['publish'], description: 'harvested routing telemetry has been applied to the auto-cost outcome store' },
+  { id: 'marketplace-parity', severity: 'soft', ops: ['publish'], description: 'the published .claude-plugin/ showcase composition matches a fresh regeneration from the live registry (version excluded — an operator field)' },
   { id: 'agents-md-policy-sync', severity: 'soft', ops: ['publish'], description: 'proves the AGENTS.md copy is in SYNC with its source — not that the runtime read or obeyed it; heal drift with dz agents-sync' },
   { id: 'lockfile-in-sync', severity: 'soft', ops: ['publish'], description: 'every workspace @dzhechkov/* dependency spec matches the specifier pnpm-lock.yaml records for that importer (a dep bump without a lockfile refresh breaks CI with ERR_PNPM_OUTDATED_LOCKFILE). SOFT-ONLY — a config cannot promote it to HARD' },
   { id: 'store-bloat-cap', severity: 'soft', ops: ['teach', 'consolidate'], description: 'the learned store is within its size cap' },
@@ -360,6 +385,59 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
     }
     return out;
   },
+  'routing-store-stale': (f, _sev) => {
+    const ids = f.routingFreshness?.unfedRunIds;
+    if (!Array.isArray(ids) || ids.length === 0) return [];
+    const valid = [...new Set(ids.filter((id): id is string => typeof id === 'string' && id !== ''))].sort();
+    if (valid.length === 0) return [];
+    return [{
+      rule: 'routing-store-stale',
+      severity: 'soft',
+      detail: `${valid.length} harvested run(s) are not reflected in the auto-cost store: ${valid.slice(0, 5).join(', ')}${valid.length > 5 ? '…' : ''} — run dz routing recommend --apply`,
+    }];
+  },
+  'marketplace-parity': (f, _sev) => {
+    const fact = f.marketplaceParity;
+    if (fact === undefined || fact.applicable !== true) return [];
+    const hasPublishedVersion = typeof fact.publishedVersion === 'string' && fact.publishedVersion !== '';
+    const fix = `dz plugin --version ${hasPublishedVersion ? fact.publishedVersion : 'X.Y.Z'}`;
+    const fixHint = hasPublishedVersion ? '' : ' (substitute the published version for X.Y.Z)';
+    const manifestFailures = Array.isArray(fact.manifestFailures)
+      ? fact.manifestFailures.filter((failure) => failure
+        && (failure.file === 'plugin.json' || failure.file === 'marketplace.json')
+        && typeof failure.error === 'string'
+        && failure.error !== '')
+      : [];
+    if (manifestFailures.length > 0) {
+      return manifestFailures.map((failure) => ({
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: `.claude-plugin/${failure.file} exists but could not be read or parsed: ${failure.error} — run \`${fix}\`${fixHint} and commit the result`,
+      }));
+    }
+    if (fact.onlyOnePresent === true) {
+      return [{
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: `.claude-plugin/ has only one of plugin.json / marketplace.json — a broken half-showcase; run \`${fix}\`${fixHint} and commit the result`,
+      }];
+    }
+    if (fact.regenerateFailed === true) {
+      return [{
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: 'could not verify .claude-plugin/ composition because fresh regeneration failed',
+      }];
+    }
+    if (fact.diverged === true) {
+      return [{
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: `.claude-plugin/ composition does not match a fresh regeneration from the live registry — run \`${fix}\`${fixHint} and commit the result`,
+      }];
+    }
+    return [];
+  },
   'review-round': (f, sev) => {
     // The publish gate had eleven rules and not one asked whether anyone but the author had read the
     // code. MEASURED cost (health-advisor slice H): five rounds graded F, thirteen packages published
@@ -508,7 +586,7 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
  * may not understand a file, and "I might be wrong" plus "block the publish" is the wrong pair. Disabling
  * such a rule stays allowed — only the promotion is refused.
  */
-export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync', 'agents-md-policy-sync'];
+export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync', 'agents-md-policy-sync', 'routing-store-stale', 'marketplace-parity'];
 
 /**
  * A well-formed PROMOTED rule: an id the engine does not know, made enforceable by a template +

package/src/index.ts

@@ -283,7 +283,7 @@ export {
   codeCheckpointPersistAllowed,
   codeStageResultShapeValid,
 } from './feature-adr-checkpoints.js';
-export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead, TrainingPairFamily, TrainingPair, TrainingPairEvaluation, TrainingPairProvenance, TrainingPairTruncation,
+export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead, TrainingPairFamily, TrainingPair, TrainingPairEvaluation, TrainingPairProvenance, TrainingPairBudget, TrainingPairTruncation,
   CheckpointWriteVerdict,
 } from './feature-adr-checkpoints.js';
 
@@ -627,6 +627,7 @@ export {
   resolveCoderSpec,
   coderIsCodex,
   resolveQeSpec,
+  resolveQeSpecForCoder,
   crossFamilyQe,
   decideModeBScope,
   partitionReviewFindings,