merge: v2.6.2 — stop committing machine-local capability into compound-v.json

Author: copeus

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-v",
       "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert + Context7 library validator), disjoint partitioning, manifest-driven multi-backend dispatch (Claude + Codex + Antigravity + Cursor), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall→action bridge), and batched parallel dispatch (Opus default, narrow Sonnet exception)",
-      "version": "2.6.1",
+      "version": "2.6.2",
       "source": "./",
       "author": {
         "name": "Oleg",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-v",
   "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert advisor + library/doc validator via Context7), disjoint file partitioning, manifest-driven multi-backend dispatch (Claude + headless Codex + Antigravity + Cursor workers), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode for multi-feature builds, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall\u2192action bridge), and batched parallel dispatch (Opus default, Sonnet for narrow junior-task carve-out), plus /v:onboard — a project-onboarding command that builds a citation-verified knowledge base + AGENTS.md/CLAUDE.md bridge behind a human gate. Auto-intercepts brainstorming \u2192 writing-plans \u2192 execution transitions.",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "author": {
     "name": "Oleg",
     "email": "copeus@gmail.com"

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to **superpowers-v (Compound V)** are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning.
 
+## [2.6.2] — 2026-07-06
+
+### Fixed — `.claude/compound-v.json` no longer commits machine-local capability
+
+- **Closed a real downstream-repo review comment:** a teammate flagged the committed `.claude/compound-v.json` as looking like it should be gitignored. The diagnosis: the file mixed genuine team **policy** (`stance`, `models`, `memory`, `epic`, `review`, `workflows_accelerator` — correct to commit) with a **machine-local capability snapshot** (`backends`, `checked_at` — "which CLI/MCP tools were detected on the machine that last ran `/v:init`") — a fact about one developer's machine, wrong the moment a teammate with a different local setup opens the file.
+- **The fix removes `backends`/`checked_at` from the committed file — no new file needed.** A correct, already-uncommitted home for exactly this data already existed: `~/.claude/compound-v-capabilities.json` (`/v:init` Step 4b, user-home-scoped, already documented as "reused across repos"). `backends` was pure redundancy with it.
+- **Audited before touching anything:** `compound-v-resolve-model.py`'s `load_config_models()` reads only the `models` key; a full-repo grep found **zero** programmatic readers of `backends`/`checked_at` — actual backend availability is already re-probed live at dispatch time (the env-aware codex→claude fallback). So this is a hygiene/trust fix, not a routing-behavior change — nothing about dispatch logic changed. **Backward-compatible**: an existing committed file with the old fields is simply ignored, no migration needed.
+- `commands/v-init.md` Step 4a and `commands/v-models.md` Step 3 updated (write path + example JSON + an explicit "why" note at the canonical source). **Codex cross-model verification: ACCURATE** — independently confirmed `load_config_models()` reads only `models`, zero remaining `backends` references anywhere in the repo, the sole remaining `checked_at` is correctly inside the Step 4b capability-cache shape, and the Step 4b cache fully covers the old capability role.
+
 ## [2.6.1] — 2026-07-06
 
 ### Fixed — worktree git-base fixes are the caller's job, never the worker's

commands/v-init.md

@@ -261,11 +261,17 @@ Write **both**. Create parent dirs as needed.
 
 ### 4a. Project stance → `.claude/compound-v.json` (project-local; committed in YOUR project, never in the plugin repo)
 
+**Committed team POLICY only — never machine-local capability.** This file is shared across every
+developer's checkout, so it must never claim something that's only true of the machine that ran
+`/v:init` (e.g. "Codex is available" when a teammate's machine doesn't have it installed) — that
+data already has a correct, uncommitted home: the Step 4b user-level capability cache below. Do not
+add a `backends` or `checked_at` field here; they were removed in v2.6.2 for exactly this reason
+(a real downstream repo review flagged the committed file as looking like machine-local state — it
+was, in those two fields).
+
 ```json
 {
   "stance": "balanced",
-  "backends": ["claude", "codex"],
-  "checked_at": "<YYYY-MM-DD>",
   "memory": { "embeddings": false, "auto_recall": true, "auto_tighten": false },
   "epic":   { "max_features": 1 },
   "review": { "cross_model": false },
@@ -291,13 +297,6 @@ identically to `balanced`. Only `cost-aware.claude.standard` differs: `sonnet`,
 `opus`; `cost-aware.claude.deep` stays `opus`.)
 
 - `stance` = the stance chosen in Step 3.
-- `backends` = the usable set: always includes `"claude"`; add `"codex"` if Codex is
-  usable, add `"antigravity"` if `agy` is installed (Step 1a-bis), add `"cursor"` if
-  `cursor-agent` is installed **and authenticated** (Step 1a-ter). E.g. `["claude","codex"]`
-  or `["claude","codex","antigravity","cursor"]`. Antigravity and Cursor are the lower-trust
-  opt-in backends (no kernel sandbox); list each only when its CLI is present (Cursor also
-  requires auth).
-- `checked_at` = today's date.
 - If the user opted into the Workflows accelerator, also include
   `"workflows_accelerator": true` (omit otherwise — default OFF).
 - **`memory.embeddings`** = the Step 3b lane choice (default `false` = FTS5-only). When `true`,

commands/v-models.md

@@ -179,10 +179,13 @@ Guardrails on every assignment:
 ## Step 3 — Write the map into `.claude/compound-v.json`
 
 Merge the confirmed assignments into the config's `models` block. **Preserve every
-other key** in the file (`stance`, `backends`, `checked_at`, `workflows_accelerator`,
+other key** in the file (`stance`, `memory`, `epic`, `review`, `workflows_accelerator`,
 …) and any backend block you did not refresh this run. Create the file (and parent
 dir) if absent, seeding the non-`models` keys from `/v:init` conventions if they
-aren't there yet.
+aren't there yet. **Never write `backends` or `checked_at`** — machine-local
+capability lives in `~/.claude/compound-v-capabilities.json`, not in this committed
+file (v2.6.2). If an older file already has those two keys (pre-2.6.2), leave them
+untouched — they're inert, no migration needed.
 
 Resulting shape (only `models` is this command's responsibility) — write the
 **per-stance** shape, refreshing each backend's row inside every stance block (only
@@ -191,8 +194,6 @@ Resulting shape (only `models` is this command's responsibility) — write the
 ```jsonc
 {
   "stance": "…",            // preserved
-  "backends": ["…"],         // preserved
-  "checked_at": "…",         // preserved
   "models": {
     "balanced": {
       "claude":      { "deep": "opus",    "standard": "opus",    "light": "sonnet" },

docs/superpowers/specs/2026-07-06-v2.6.2-split-local-config-design.md

@@ -0,0 +1,92 @@
+# Stop committing machine-local capability into `.claude/compound-v.json` (design, v2.6.2)
+
+**Status:** approved for build (2026-07-06). Triggered by a real downstream-repo PR review comment
+(a teammate flagged `.claude/compound-v.json` — 109 new lines — as "should be in exclusions").
+
+## 1. What it is
+`.claude/compound-v.json` (written by `/v:init` Step 4a, refreshed by `/v:models` Step 3) currently
+mixes two unrelated kinds of data in one **committed** file: genuine team/project **policy**
+(`stance`, `models`, `memory`, `epic`, `review`, `workflows_accelerator`) and a **machine-local
+capability snapshot** (`backends`, `checked_at` — "which CLI/MCP tools were detected on the machine
+that last ran `/v:init`"). The fix: **stop writing `backends`/`checked_at` into the committed
+file.** No new file is needed — a correct, already-uncommitted home for exactly this data already
+exists: `~/.claude/compound-v-capabilities.json` (`/v:init` Step 4b, user-home-scoped, "reused
+across repos"). `backends` was pure redundancy with it.
+
+## 2. Why
+`backends` is written as *"add `codex` if Codex is usable... add `cursor` if `cursor-agent` is
+installed **and authenticated**"* — a fact about **the machine that ran `/v:init`**, not a team
+decision. Committing it means every other developer's checkout claims their teammate's local tool
+availability as if it were their own — wrong the moment a second developer (with a different local
+setup) opens the file. This is precisely what the reviewer flagged.
+
+**It is also not load-bearing today** — audited via full-repo grep before writing this spec:
+`compound-v-resolve-model.py`'s `load_config_models()` reads only the `models` key; no script or
+skill prose reads `backends`/`checked_at` back out of `.claude/compound-v.json` programmatically.
+Actual backend availability is already re-probed live at dispatch/orchestrate time (the "env-aware"
+codex→claude fallback in `routing-policy.md`, invoked "at runtime, not only at `/v:init`") and by
+the Step 4b capability cache. So this is a hygiene/trust fix (stop the file lying to teammates), not
+a routing-behavior fix — nothing about actual dispatch logic changes.
+
+## 3. The split (final — after the audit, simpler than a new file)
+
+| Field | Home | Committed? |
+|---|---|---|
+| `stance`, `models`, `memory`, `epic`, `review`, `workflows_accelerator` | `.claude/compound-v.json` (unchanged) | ✅ yes — team policy |
+| Backend/tool availability (`codex`, `antigravity`, `cursor`, `context7`, `workflows`) | `~/.claude/compound-v-capabilities.json` (**already exists**, Step 4b, user-home) | ❌ no — already outside any repo |
+| ~~`backends`~~, ~~`checked_at`~~ | **removed** from `.claude/compound-v.json` | — |
+
+No new file, no new read path, no resolver/dispatcher/memory code changes — the two fields being
+removed have zero programmatic readers today (confirmed by audit). This is a **documentation +
+write-path** change only.
+
+## 4. Components
+
+### 4.1 `commands/v-init.md` Step 4a
+Drop `backends` and `checked_at` from the written JSON example and the field-by-field write
+instructions. Add one clarifying sentence: this file is committed team **policy** only; machine
+capability already lives in the Step 4b user-level cache and must never be duplicated here.
+
+### 4.2 `commands/v-models.md` Step 3
+Drop `backends`/`checked_at` from the "preserve every other key" list (nothing seeds or reads them
+going forward). **Backward-compat:** if an existing project's file already has these keys (written
+by a pre-2.6.2 `/v:init`), `/v:models` does not need to actively strip them — they're inert. No
+migration tooling; a user who wants a clean file re-runs `/v:init`, or edits the two keys out by
+hand. (No over-engineering: don't build a migration script for two dead JSON keys.)
+
+### 4.3 Every other doc showing the full example JSON
+`skills/compound-v/routing-policy.md`, `skills/compound-v/execution-manifest.md`, and any other
+doc that reproduces the `.claude/compound-v.json` example shape gets the same trim, so there is
+exactly one place a reader learns the shape and it's consistent everywhere.
+
+### 4.4 Explicit "why" note, once, at the canonical source
+`v-init.md` Step 4a (the canonical place the file is first written) states the committed/uncommitted
+split explicitly and *why* — this is the paragraph a future contributor (or a `git blame`-curious
+teammate) reads to understand the reasoning, so it doesn't need re-litigating per downstream repo.
+
+## 5. Invariants
+1. **`.claude/compound-v.json` (committed) never records what's true only of one machine.**
+2. **No duplication** — machine capability has exactly one home (`~/.claude/compound-v-capabilities.json`).
+3. **No functional/runtime behavior changes** — `models` resolution, `memory`/`epic`/`review` reads,
+   and the live env-aware backend fallback are all unaffected (none of them read `backends`/`checked_at`).
+4. **Backward-compatible** — an existing committed file with the old fields still works (they're
+   simply ignored by everything, as they are today); no migration required to upgrade.
+
+## 6. Verification
+- Grep-based check: after the doc edits, no doc's *written* example (the JSON blocks presented as
+  "what `/v:init`/`/v:models` writes") contains `backends`/`checked_at` inside `.claude/compound-v.json`'s
+  shape.
+- Re-confirm the audit finding holds after edits: `load_config_models()` and every other reader are
+  unaffected (they were never touched).
+- Codex cross-model verification: does the doc consistently point machine-capability data at the
+  Step 4b cache everywhere, with no leftover reference implying `backends` is still needed/read?
+- Full existing regression (`compound-v-resolve-model.py --selftest`, `compound-v-memory.py --selftest`,
+  frontmatter lint, CI version lockstep) stays green — expected, since no code changed.
+
+## 7. Out of scope
+- An automated migration/cleanup tool for existing committed files with the old fields.
+- Any change to the Step 4b capability-cache format (it's already correct).
+- Any change to live routing/fallback behavior (unaffected by this fix).
+
+## 8. Version
+**v2.6.2** (patch — docs/write-path only; `plugin.json` + `marketplace.json` in lockstep).