@ikon85/agent-workflow-kit 0.34.3 → 0.34.5

package/.agents/skills/kit-release/SKILL.md

@@ -110,3 +110,15 @@ manifest and compares it with both the base and the checked-in manifest. It
 blocks an unbumped shipped delta, a stale manifest, a too-small Semver bump, or
 a dead manifest entry and prints the concrete paths. CI runs the same command;
 there is no separately remembered shipped-file list.
+
+It also blocks a **version bump stacked on an untagged previous release**: if
+the base version carries no matching annotated tag, that release is still
+`awaiting-tag` and never became its own artifact. Tag and publish it first —
+never bury it under the next bump. A repository with no matching tag at all is
+bootstrapping its first release and is not blocked.
+
+A red release run does not prove nothing was published. Reconstruct the real
+state from the registry and the release before reacting; a stale local
+packument cache can answer "not published" for a package that is live, and the
+recovery route is the idempotent reconciler on the existing tag, never a new
+version.

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

@@ -30,9 +30,12 @@ release contain the same artifact.
    ```
 
    The command checks npm/GitHub release parity before staging. It prepares a
-   complete candidate outside the consumer, runs the consumer's existing
-   `npm test` command there, and activates only a verified candidate. A staging
-   or verification failure leaves the installed tree byte-identical.
+   complete manifest-bounded candidate outside the Consumer, verifies the
+   Kit-owned manifest, artifact, protocol, schema/reference, syntax, and
+   transaction invariants, and activates only that verified candidate. It
+   never runs a Consumer package script, configurable verification command, or
+   legacy fallback. A staging or verification failure leaves the installed
+   tree byte-identical.
 
    The staged candidate also adopts the current readiness schema without
    invoking `setup-workflow`: it preserves explicit readiness decisions and

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

@@ -81,11 +81,19 @@ Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [
 
 ### 2a. Automatic Kit update pull requests (GitHub tracker only)
 
-> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
-
-Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
-
-Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+> A short scheduled check can keep the installed Kit current by opening one
+> normal pull request after the candidate passes the built-in Kit invariant
+> validator. It runs no Consumer package script and never merges the pull
+> request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language:
+*"Should GitHub check weekly for a verified Agent Workflow Kit update and keep
+one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, explain that the update command uses the same
+built-in Kit invariant validator as manual and agent-driven updates. There is
+no Consumer package script, lockfile, configurable verification profile, or
+legacy test fallback prerequisite.
 
 Also read the repository Actions policy before enabling:
 

package/.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -23,9 +23,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22.14
-      - name: Install locked consumer dependencies
-        run: npm ci --ignore-scripts
-      - name: Verify, test, and upsert the Kit update pull request
+      - name: Verify and upsert the Kit update pull request
         env:
           GH_TOKEN: ${{ github.token }}
         run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

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

@@ -110,3 +110,15 @@ manifest and compares it with both the base and the checked-in manifest. It
 blocks an unbumped shipped delta, a stale manifest, a too-small Semver bump, or
 a dead manifest entry and prints the concrete paths. CI runs the same command;
 there is no separately remembered shipped-file list.
+
+It also blocks a **version bump stacked on an untagged previous release**: if
+the base version carries no matching annotated tag, that release is still
+`awaiting-tag` and never became its own artifact. Tag and publish it first —
+never bury it under the next bump. A repository with no matching tag at all is
+bootstrapping its first release and is not blocked.
+
+A red release run does not prove nothing was published. Reconstruct the real
+state from the registry and the release before reacting; a stale local
+packument cache can answer "not published" for a package that is live, and the
+recovery route is the idempotent reconciler on the existing tag, never a new
+version.

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

@@ -30,9 +30,12 @@ release contain the same artifact.
    ```
 
    The command checks npm/GitHub release parity before staging. It prepares a
-   complete candidate outside the consumer, runs the consumer's existing
-   `npm test` command there, and activates only a verified candidate. A staging
-   or verification failure leaves the installed tree byte-identical.
+   complete manifest-bounded candidate outside the Consumer, verifies the
+   Kit-owned manifest, artifact, protocol, schema/reference, syntax, and
+   transaction invariants, and activates only that verified candidate. It
+   never runs a Consumer package script, configurable verification command, or
+   legacy fallback. A staging or verification failure leaves the installed
+   tree byte-identical.
 
    The staged candidate also adopts the current readiness schema without
    invoking `setup-workflow`: it preserves explicit readiness decisions and

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

@@ -81,11 +81,19 @@ Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [
 
 ### 2a. Automatic Kit update pull requests (GitHub tracker only)
 
-> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
-
-Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
-
-Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+> A short scheduled check can keep the installed Kit current by opening one
+> normal pull request after the candidate passes the built-in Kit invariant
+> validator. It runs no Consumer package script and never merges the pull
+> request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language:
+*"Should GitHub check weekly for a verified Agent Workflow Kit update and keep
+one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, explain that the update command uses the same
+built-in Kit invariant validator as manual and agent-driven updates. There is
+no Consumer package script, lockfile, configurable verification profile, or
+legacy test fallback prerequisite.
 
 Also read the repository Actions policy before enabling:
 

package/.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -23,9 +23,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22.14
-      - name: Install locked consumer dependencies
-        run: npm ci --ignore-scripts
-      - name: Verify, test, and upsert the Kit update pull request
+      - name: Verify and upsert the Kit update pull request
         env:
           GH_TOKEN: ${{ github.token }}
         run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

package/README.md

@@ -387,6 +387,23 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.34.5
+
+- changed: `.agents/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
+- changed: `.claude/skills/kit-update/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
+- changed: `scripts/kit-update-pr.mjs`
+
+### 0.34.4
+
+- changed: `.agents/skills/kit-release/SKILL.md`
+- changed: `.claude/skills/kit-release/SKILL.md`
+- changed: `scripts/release-delta-guard.mjs`
+- changed: `scripts/release-state.mjs`
+
 ### 0.34.3
 
 - changed: `.agents/skills/diagnose/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.34.3",
+  "kitVersion": "0.34.5",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -367,7 +367,7 @@
       "ownerSkill": "kit-release",
       "surface": "codex",
       "installRole": "maintainer",
-      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
+      "sha256": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
       "mode": 420,
       "origin": "kit"
     },
@@ -377,7 +377,7 @@
       "ownerSkill": "kit-update",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "c3487295864d1d8d765e1c453c80daf77d3f08a2b0017f614e44e85170913624",
+      "sha256": "9129e14b12b573546e253e14be3b7793afe2ca2b46102bb7b5f2ec1a8276a1ec",
       "mode": 420,
       "origin": "kit"
     },
@@ -577,7 +577,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "sha256": "dcabda3d93b7c79f35065a9f3130807ff29737e15187a68fdbc37533015d461d",
       "mode": 420,
       "origin": "kit"
     },
@@ -677,7 +677,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "7281bb67588328aa4a788cbefe69f396c4617569335ce47cfb45bb5607d3205e",
+      "sha256": "0f098f6efeda6682726d918135f0a66ffbf9c90616293fd3833d5fe47fc5c927",
       "mode": 420,
       "origin": "kit"
     },
@@ -1679,7 +1679,7 @@
       "ownerSkill": "kit-release",
       "surface": "claude",
       "installRole": "maintainer",
-      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
+      "sha256": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
       "mode": 420,
       "origin": "kit"
     },
@@ -1689,7 +1689,7 @@
       "ownerSkill": "kit-update",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "c3487295864d1d8d765e1c453c80daf77d3f08a2b0017f614e44e85170913624",
+      "sha256": "9129e14b12b573546e253e14be3b7793afe2ca2b46102bb7b5f2ec1a8276a1ec",
       "mode": 420,
       "origin": "kit"
     },
@@ -1909,7 +1909,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "sha256": "dcabda3d93b7c79f35065a9f3130807ff29737e15187a68fdbc37533015d461d",
       "mode": 420,
       "origin": "kit"
     },
@@ -2009,7 +2009,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "7281bb67588328aa4a788cbefe69f396c4617569335ce47cfb45bb5607d3205e",
+      "sha256": "0f098f6efeda6682726d918135f0a66ffbf9c90616293fd3833d5fe47fc5c927",
       "mode": 420,
       "origin": "kit"
     },
@@ -2535,7 +2535,7 @@
       "path": "scripts/kit-update-pr.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "83f30a4ca938171cfa2f4153917813fae40bf2a906940e047c7066d18284209b",
+      "sha256": "c28bbd5a45583a92eca12758c1d626e04bce820300178b54933340759d1690fd",
       "mode": 493,
       "origin": "kit"
     },
@@ -2655,7 +2655,7 @@
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
       "installRole": "maintainer",
-      "sha256": "a51f30e7261e4efb0b5c5002f39353ef8e8be18a2bd39ad7139f1ce7a2e7e18d",
+      "sha256": "1d2aab5f15bca25167b166b37232139916cf814e94de873fa74a653ecf9a4619",
       "mode": 420,
       "origin": "kit"
     },
@@ -2671,7 +2671,7 @@
       "path": "scripts/release-state.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "23b4ffc77e9b499587fa563d067b1df9ae81b87a654d636281c7d139e5842687",
+      "sha256": "fd9f7f86e26ab3faba819e0c46e5e87c2dd3a84dc9a6111b4eceb4ebe6a3a344",
       "mode": 420,
       "origin": "kit"
     },

package/docs/adr/0001-consumer-divergence-policy.md

@@ -2,6 +2,10 @@
 
 Status: accepted (2026-07-18, issue #130)
 
+Partially superseded by ADR-0003: consumer ownership remains valid for genuine
+project files, but no longer applies to Kit Core or to mixed core/extension
+registries.
+
 Since the consumer-source cutover the kit is SSOT for shipped files, but
 consumers keep learning: edits made directly on a shipped file in a consumer
 silently fork it, and every subsequent `kit-update` reports a permanent

package/docs/adr/0003-kit-core-and-project-extension-lifecycle.md

@@ -0,0 +1,63 @@
+# Kit Core and project extensions have separate identities
+
+Status: accepted (2026-07-22, issues #190, #194, #196, #197)
+
+The original divergence policy allowed any shipped path to become
+consumer-owned. That is safe for a genuinely project-specific file, but not for
+a protocol authority such as the skill/readiness registry: once a consumer
+owns that mixed file, new Kit declarations stop arriving while local additions
+and stale Kit declarations remain indistinguishable. A real consumer exhibited
+exactly this state: the installed readiness harness was current while its owned
+registry had no readiness capabilities or declarations.
+
+We decided to model four explicit lifecycle states instead of treating every
+local difference as file ownership:
+
+1. **Kit Core** remains upstream-owned under the Kit's canonical identity. A
+   consumer cannot permanently own it under that same identity.
+2. **Project extensions** live on separate consumer-owned surfaces. Every
+   shipped skill may load its optional `docs/agents/skills/<skill>.md`; local
+   skill identities live in a separate local registry. Neither surface changes
+   the corresponding Kit Core.
+3. A **Contribution bridge** may temporarily retain a registered local Core
+   experiment. It must resolve into a project extension, a generalized upstream
+   contribution that returns in a release, or an explicit fork.
+4. An **Explicit fork** has its own identity, version, and update line. Semantic
+   divergence cannot masquerade indefinitely as the canonical Kit skill.
+
+An update composes and validates the complete protocol group in an isolated,
+manifest-derived staged candidate. It never infers an ownership decision from
+`--yes`: an unclassified collision blocks unchanged until a user classifies it.
+Existing mixed states migrate semantically, preserving local identities and
+project metadata on their new surfaces; an ambiguous semantic change blocks
+instead of being overwritten or frozen silently.
+
+The upstream route is capability-based, not maintainer-specific. At the moment
+of contribution, repository permissions and an optional machine-local upstream
+checkout determine whether the approved route can use a direct pull request, a
+fork, or an issue. No consumer asks who the user is, and no telemetry reports
+local edits automatically.
+
+## Considered options
+
+- **Keep arbitrary consumer-owned shipped paths:** rejected because a protocol
+  authority then stops receiving schema and behavior evolution under the same
+  identity.
+- **Add more merge rules to the mixed registry:** rejected because local skills,
+  project annotations, readiness declarations, and upstream skill definitions
+  have different ownership and lifecycle semantics.
+- **Overwrite Core and discard local changes:** rejected because it loses valid
+  project behavior and can destroy unregistered work.
+- **Special-case the maintainer:** rejected because identity is irrelevant; the
+  portable distinction is whether the user has an approved route and the
+  required repository capabilities.
+
+## Consequences
+
+- ADR-0001 remains valid for genuine consumer-owned files but is narrowed for
+  Kit Core and mixed registries.
+- Core updates can advance without erasing project-specific behavior.
+- Consumers gain explicit extension, contribution, and fork lifecycles instead
+  of permanent accidental divergence.
+- Migration requires a one-time semantic classification of existing mixed
+  states and must fail closed when that classification is ambiguous.

package/docs/agents/board-sync.md

@@ -65,7 +65,7 @@ The workflow board is [Agent Workflow Kit](https://github.com/users/iKon85/proje
     "wavePrefix": "Welle"
   },
   "wrapup": {
-    "remoteBranchSweep": false
+    "remoteBranchSweep": true
   }
 }
 ```

package/docs/agents/workflow-capabilities.json

@@ -0,0 +1,17 @@
+{
+  "worktreeLifecycle": {
+    "enabled": true,
+    "worktreeRoot": ".worktrees",
+    "branchTemplate": "{type}/{issue}-{slug}",
+    "pathTemplate": "{issue}-{slug}",
+    "branchRegex": "^(?:feat|fix|chore|docs)/(?P<issue>\\d+)-",
+    "mainBranches": ["main"],
+    "protectedBranches": ["main"],
+    "setupEntry": "python3 scripts/worktree-lifecycle/setup.py",
+    "setupSteps": [],
+    "riskyCommandPatterns": [
+      "\\b(?:npm|pnpm|yarn)\\s+(?:run\\s+)?(?:test|typecheck|build)\\b",
+      "\\bgit\\s+(?:commit|push)\\b"
+    ]
+  }
+}

package/docs/research/benchlm-routing-source.md

@@ -0,0 +1,198 @@
+# BenchLM as a routing-evidence source
+
+**Researched:** 2026-07-22  
+**Question:** What role, if any, should BenchLM play in the Kit's evidence-backed
+model and effort routing, and what does that imply for setup and kit-update?
+
+## Decision
+
+Use BenchLM as a **catalog, discovery, and corroboration source**, not as an
+authoritative routing source.
+
+BenchLM is unusually useful for finding new model families, benchmarks,
+pricing changes, supersession relationships, and gaps in current evidence. It
+must not directly choose a dispatch route, especially an effort level. A route
+observation still has to come from the benchmark owner and retain the complete
+configuration identity: model, effort, agent/harness, benchmark version,
+quality metric, uncertainty, and task cost.
+
+This gives the source hierarchy:
+
+1. **Benchmark owner artifacts** (DeepSWE, Artificial Analysis, OpenHands,
+   Code/Design Arena) provide decision evidence.
+2. **BenchLM** discovers and cross-checks those sources and model releases.
+3. **Local user evidence and preferences** calibrate the resulting policy.
+4. The approval-gated policy reconciler proposes, but never silently applies,
+   routing changes.
+
+## What BenchLM contributes
+
+BenchLM currently tracks 290 models and 323 benchmarks. Its useful coverage
+includes agentic work, coding, multimodal work, model pricing, context windows,
+runtime signals, release metadata, and supersession chains. Its methodology
+currently gives ranking weight to three agentic and five coding benchmarks;
+many more sources, including DeepSWE and most frontend sources, are display-only
+context ([methodology](https://benchlm.ai/methodology)).
+
+Frontend coverage is useful primarily as a source map. The current focused page
+combines sourced React Native Evals, Design2Code, Vision2Web, and related
+browser-task evidence, but calls itself a reporting family rather than a
+weighted category, contains only seven eligible models, and warns that models
+may have as few as two source rows
+([frontend/app-dev view](https://benchlm.ai/best/frontend-app-dev)). The owners
+remain more authoritative: [React Native Evals](https://rn-evals.vercel.app/)
+publishes agent success, token, and cost results, while
+[Vision2Web](https://vision2web-bench.github.io/) explicitly evaluates
+model-plus-framework submissions across visual, interactive, and full-stack
+tasks.
+
+BenchLM also exposes confidence separately from score, 90% score intervals,
+`Supported` versus `Estimated` states, source-coverage counts, and a dated
+BenchAlign method/frozen-input identifier. That is valuable for shortlisting
+and for detecting insufficient evidence, but it is confidence in BenchLM's
+composite inference rather than a pass-rate interval for our exact workload
+([confidence method](https://benchlm.ai/benchmark-confidence)).
+
+## Why it cannot drive routing directly
+
+### Effort and harness can disappear
+
+BenchLM's exported Sol model row records DeepSWE as `72.7`, but not the effort,
+harness, confidence interval, or cost
+([models export](https://benchlm.ai/data/models.json)). The owner artifact shows
+that this number is specifically `gpt-5-6-sol + mini-swe-agent + max`: 72.7%
+Pass@1 over four whole-benchmark runs, with a 95% run-to-run interval and about
+$8.39 mean cost per scored attempt
+([DeepSWE v1.1 artifact](https://deepswe.datacurve.ai/artifacts/v1.1/leaderboard-live.json)).
+
+This collapsing is fatal for model-plus-effort selection. Some older model
+families have explicit `high` or `max` variants in the BenchLM catalog, while
+current Sol, Terra, Luna, and Fable evidence can be folded into one base-model
+row. The overall/category scores therefore describe mixed published
+configurations, not a consistent effort curve.
+
+### Composite rankings are editorial inference
+
+BenchAlign normalizes unlike protocols, combines source families, and imputes
+missing evidence with wider uncertainty. BenchLM publishes the method version,
+frozen-input identifier, weighted benchmark list, and dated output, but its
+public downloads reference internal source files rather than a published,
+locally reproducible BenchAlign implementation. The composite is reproducible
+as a cached dated output, not independently rebuildable by the Kit from public
+code ([methodology](https://benchlm.ai/methodology)).
+
+Raw source rows are more useful than the composite, but the current
+machine-readable model export is a numeric benchmark map without per-row source
+URLs or complete execution settings. The Kit must follow the benchmark catalog
+to the owner rather than treating `models.json` as normalized routing evidence.
+
+### Current semantic inconsistencies require defensive ingestion
+
+The same-day exports currently contain examples that a production adapter must
+reject or downgrade:
+
+- BenchLM's DeepSWE Markdown page says that source metadata is preserved but
+  reports zero leaderboard models, while `models.json` contains six DeepSWE
+  scores.
+- `benchmarks.json` currently contains duplicate `sweMultimodal` definitions.
+- Its Design2Code and Vision2Web catalog entries currently point to a provider
+  documentation page rather than the benchmark owners. The official
+  [Design2Code repository](https://github.com/NoviScl/Design2Code) and
+  [Vision2Web site](https://vision2web-bench.github.io/) show the correct
+  provenance.
+
+These may be transient publishing defects, but they make last-known-good,
+semantic validation, and owner verification mandatory.
+
+## Machine-readable access, cadence, and legal posture
+
+BenchLM documents MIT-licensed JSON downloads for leaderboard, models,
+benchmarks, pricing, speed, and comparisons. Each export currently has
+`schemaVersion`, `generatedAt`, and `sourceLastUpdated`; `updates.json` provides
+a cheap change feed. BenchLM says it refreshes several times per week and often
+within hours of major launches ([dataset documentation](https://benchlm.ai/data)).
+
+The adapter should use the documented `/data/*.json` downloads and
+`updates.json`, not scrape rendered pages. Fetch at low cadence, send ordinary
+conditional requests where supported, retain attribution, and persist the raw
+snapshot hash and generation timestamp.
+
+There is one governance warning: the current Terms page still visibly contains
+launch placeholders for operator identity, jurisdiction, effective date, and
+contact details. It permits published downloads under their stated licenses
+and non-degrading automated access, but this unfinished legal surface reduces
+operational confidence. The MIT dataset declaration is clear; nonetheless the
+adapter should not depend on high-frequency or undocumented endpoints
+([dataset license](https://benchlm.ai/data),
+[terms](https://benchlm.ai/terms)). Underlying benchmark data remains subject
+to its original publisher's license.
+
+## Concrete adapter contract
+
+`BenchLmCatalogSource` should ingest only:
+
+- model/provider/family and release/supersession metadata;
+- current pricing and runtime hints;
+- benchmark definitions and owner links;
+- coverage, freshness, `Supported`/`Estimated`, and confidence metadata;
+- the update feed as an invalidation and discovery trigger.
+
+It should emit `candidate-discovered`, `source-changed`, `pricing-changed`, and
+`evidence-gap` events. It must not emit an authoritative
+`RouteObservation(model, effort, harness)` unless an owner adapter has verified
+the complete row.
+
+Every refresh must:
+
+1. validate the export schema and cross-file referential integrity;
+2. reject duplicate benchmark identities and implausible source changes;
+3. retain the last-known-good snapshot on failure;
+4. classify aggregate scores as `corroborating`, never `decisive`;
+5. resolve relevant rows through the original source adapter;
+6. show a human-readable diff before a personal policy changes.
+
+## Setup and kit-update implication
+
+BenchLM improves discovery, but it does not change ownership: setup asks which
+**surfaces/providers the user can and wants to use**, not which model currently
+tops a leaderboard. Availability, policy, and benchmark ability are separate.
+
+For a first setup or an existing installation without a routing profile:
+
+1. Detect installed/supported surfaces where possible and ask the user to
+   confirm the common choices (for example Claude Code, Codex, and explicitly
+   offered additional providers such as Google or Moonshot/Kimi).
+2. Record availability and dispatch capability separately: subscription/API,
+   allowed cross-provider execution, per-spawn model control, and per-spawn
+   effort control.
+3. Ask for the optimization preference and local overrides, or allow the safe
+   `inherit` mode.
+4. Use BenchLM to discover current candidate families, then owner sources to
+   construct the proposed model-plus-effort policy.
+5. Preview the policy and require approval before activation.
+
+The list of “common AIs” must be data-driven and versioned, not hard-coded in a
+skill prompt. BenchLM can nominate newly common candidates, while surface
+capability checks determine whether they are actually selectable.
+
+`kit-update` should install updated schemas, adapters, and provider-catalog
+logic. It should run a short routing preflight when the profile is absent,
+invalid, stale, references a removed model, or when a newly detected surface
+changes available choices. It should otherwise report `still valid` without
+re-running the whole interview. An update may refresh and cache evidence, but
+must never rewrite the user's provider choices, model routes, effort routes, or
+global configuration without a separately approved reconcile transaction.
+
+## Final classification
+
+| Use | Classification |
+|---|---|
+| Discover new models, providers, benchmarks, and releases | Recommended |
+| Detect evidence/pricing/freshness changes | Recommended with validation |
+| Corroborate owner-source observations | Useful |
+| Select a candidate shortlist | Advisory only |
+| Select model plus effort for dispatch | Rejected |
+| Treat BenchAlign overall/category score as capability truth | Rejected |
+
+BenchLM therefore adds real value to the planned routing wave, but as the
+system's **radar**, not its **autopilot**.