omniconductor 0.5.0 → 1.0.1

package/docs/MANUAL-INSTALL.md

@@ -2,12 +2,12 @@
 
 > Companion to `README.md`. Step-by-step manual install for every supported tool, on Mac and Windows.
 
-This document is the fallback when the per-tool `transform.sh` adapter is not yet available, when you want to understand exactly what the adapter does, or when you are in a constrained environment (no bash, locked-down corporate machine, etc.) and need to copy files by hand.
+This document is the fallback for when you want to understand exactly what the adapter does, or when you are in a constrained environment (no bash, locked-down corporate machine, etc.) and need to copy files by hand.
 
 For each tool there are two paths:
 
-- **Adapter (recommended)** — a single `bash transform.sh <target>` invocation. Available now for Claude Code, Cursor, GitHub Copilot.
-- **Manual file copy (fallback)** — explicit `cp` / `cat` commands and frontmatter cheat sheet. Available for every tool, including the ones whose adapters have not shipped.
+- **Adapter (recommended)** — `npx omniconductor init --target=<tool> <dir>` or a single `bash transform.sh <target>` invocation. Available for **all six tools** (Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Windsurf).
+- **Manual file copy (fallback)** — explicit `cp` / `cat` commands and frontmatter cheat sheet.
 
 > **Read first**: [`README.md`](../README.md) Quick Start. The Claude adapter has a guided wizard that handles 90% of installs. Manual install is for the remaining 10%.
 
@@ -30,14 +30,14 @@ For each tool there are two paths:
 
 | Tool | Adapter ready | Recommended install |
 |---|---|---|
-| Claude Code | ✅ | `bash adapters/claude/transform.sh <target>` (see README) |
-| Cursor | ✅ (P2 in flight) | `bash adapters/cursor/transform.sh <target>` |
-| GitHub Copilot | ✅ (P2 in flight) | `bash adapters/copilot/transform.sh <target>` |
-| Gemini CLI | ❌ | manual copy (this doc) |
-| Codex (OpenAI) | ❌ | manual copy (this doc) |
-| Windsurf | ❌ | manual copy (this doc) |
+| Claude Code | ✅ | `npx omniconductor init --target=claude <target>` (see README) |
+| Cursor | ✅ | `npx omniconductor init --target=cursor <target>` |
+| GitHub Copilot | ✅ | `npx omniconductor init --target=copilot <target>` |
+| Gemini CLI | ✅ | `npx omniconductor init --target=gemini <target>` |
+| Codex (OpenAI) | ✅ | `npx omniconductor init --target=codex <target>` |
+| Windsurf | ✅ | `npx omniconductor init --target=windsurf <target>` |
 
-> Adapter ship status as of 2026-05-10. Cursor and Copilot adapters are in active development under separate dispatches. If `adapters/<tool>/transform.sh` exists and is executable, prefer it; otherwise follow the manual section for that tool.
+> All six adapters ship `transform.sh` and the npm CLI has existed since v0.2. Prefer the adapter — it handles backups, the install manifest, and `--uninstall`. Use the manual sections below only for constrained environments.
 
 ---
 
@@ -66,7 +66,7 @@ Each tool consumes a different syntax. When you copy a rule file into a tool-nat
 
 ---
 
-## Tool 1 — Cursor (manual, until P2 adapter ships)
+## Tool 1 — Cursor (fallback manual install)
 
 ### Prerequisites
 
@@ -164,7 +164,7 @@ rm -f .cursorrules
 
 ---
 
-## Tool 2 — GitHub Copilot (manual, until P2 adapter ships)
+## Tool 2 — GitHub Copilot (fallback manual install)
 
 GitHub Copilot supports custom instructions via `.github/instructions/*.instructions.md` files, which are picked up by the Copilot extension across **VSCode, Cursor, Windsurf, JetBrains, Neovim** simultaneously (one install covers all five IDEs that have the Copilot extension).
 
@@ -281,7 +281,7 @@ Get-ChildItem C:\conductor\core\universal-rules\*.md |
 ### Limitations
 
 - No lazy load — every rule is loaded every turn (token cost higher than Claude/Cursor/Copilot).
-- No hooks, no sub-agents (per ADR-004 honesty principle).
+- Manual install ships rule text only — no hook configs or agents (the tool supports hooks/sub-agents natively, ADR-031; the bash adapter emits the opt-in Reflector hook, broader emission is Phase 2 — ADR-034).
 
 ### Uninstall
 
@@ -330,7 +330,7 @@ None — Codex ignores YAML frontmatter. Optional cleanup: strip `---...---` blo
 ### Limitations
 
 - Single bundled file, no per-pattern routing.
-- No hooks, no sub-agents.
+- Manual install ships rule text only — no hook configs or agents (the tool supports hooks/sub-agents natively, ADR-031; the bash adapter emits the opt-in Reflector hook, broader emission is Phase 2 — ADR-034).
 
 ### Uninstall
 
@@ -385,7 +385,7 @@ Windsurf rule format is **NOT VERIFIED for v0.2** — check the Windsurf docs fo
 ### Limitations
 
 - Per-pattern routing support is version-dependent — likely degrades to "all loaded all the time".
-- No hooks, no sub-agents.
+- Manual install ships rule text only — no hook configs or agents (the tool supports hooks/sub-agents natively, ADR-031; the bash adapter emits the opt-in Reflector hook, broader emission is Phase 2 — ADR-034).
 
 ### Uninstall
 

package/docs/PUBLICATION-POLICY.md

@@ -0,0 +1,46 @@
+# Publication Policy — private source, public distribution
+
+## Decision
+
+CONDUCTOR uses a **dual-repository model**:
+
+| Surface | Visibility | Purpose |
+|---|---|---|
+| Working source repository | Private | Development, operational history, internal audits/plans, release safety controls, and the private-token deny list. |
+| `omniconductor` mirror | Public | User-visible source, GitHub Releases, issue/discussion entry point, and the exact tree used for npm publication. |
+
+The working source repository **must never be made public**. Changing its
+visibility would expose all historical commits, including artifacts that a
+current file filter cannot remove. A clean public repository is produced only
+by the filtered-mirror process below.
+
+## Enforced publication boundary
+
+`scripts/sync-public.sh` creates a snapshot from committed private `main` and
+fails closed before any push when either control fails:
+
+1. A structural DENY list removes private-only paths, including operational
+   session files, maintainer scripts, internal audit/plan/spec/data directories,
+   and the private-token list itself.
+2. Every private token is scanned across the entire filtered snapshot. One hit
+   aborts the operation even if the affected file was not anticipated by the
+   DENY list.
+3. The framework-purity gate must pass.
+
+The private CI workflow runs `bash scripts/sync-public.sh HEAD --check`. This
+is an offline, no-push verification of those three controls for every mergeable
+commit. The actual sync remains human-triggered and requires `--push`.
+
+## Required v1.0.1 release order
+
+1. Commit and test the change in the private source repository.
+2. Let private CI pass, including the public-snapshot safety job.
+3. Run `bash scripts/sync-public.sh main --push --release v1.0.1` from the
+   private source repository.
+4. Clone or otherwise check out the resulting public `v1.0.1` release.
+5. From that public checkout, run `npm pack --dry-run`, then the interactive
+   `npm publish` command.
+6. Verify `npm view omniconductor version` reports `1.0.1`.
+
+Feature branches and uncommitted working trees are never synchronized. A new
+internal document must be added to the sync script's DENY list before release.

package/docs/PUBLISH-GUIDE.md

@@ -0,0 +1,141 @@
+# Conductor — Marketplace Publish Guide
+
+How to package and publish the Phase 2 VSCode extension to the **VSCode Marketplace** (Microsoft) and the **Open VSX Registry** (Eclipse Foundation, used by Cursor + open-source forks).
+
+This is a **manual procedure** — the extension code lives in `phase-2/vscode-extension/`, but registry credentials are personal/organizational secrets and never live in the repo.
+
+---
+
+## 0. Prerequisites (one-time)
+
+```bash
+cd phase-2/vscode-extension
+npm install
+npm install -g @vscode/vsce ovsx   # or use npx
+```
+
+Verify the icon exists at `images/icon.png` (replace the placeholder before first publish — see CHANGELOG).
+
+## 1. Local build + package
+
+```bash
+cd phase-2/vscode-extension
+npm run compile
+npx vsce package
+```
+
+Output: `conductor-0.3.0.vsix` in the extension dir. Expected size: < 200 KB (no bundled rules — the extension only ships compiled JS).
+
+Smoke-test the .vsix locally before publishing:
+
+```bash
+code --install-extension conductor-0.3.0.vsix
+# In VSCode: Cmd/Ctrl+Shift+P → "Conductor: Install" should appear.
+code --uninstall-extension lfamily-labs.conductor
+```
+
+---
+
+## 2. VSCode Marketplace publish (Microsoft)
+
+### 2.1 Publisher account (one-time)
+
+1. Sign in at https://dev.azure.com with a Microsoft account.
+2. Create an organization (any name, used internally only).
+3. Open https://marketplace.visualstudio.com/manage and create a publisher with **Publisher ID `lfamily-labs`** (matches `package.json` `"publisher"`).
+4. Sign the Microsoft Marketplace Publisher Agreement.
+
+### 2.2 Personal Access Token (PAT)
+
+1. Azure DevOps → User settings → Personal access tokens → New token.
+2. **Organization**: All accessible organizations.
+3. **Scopes**: custom-defined → **Marketplace → Manage** (everything else off).
+4. **Expiration**: 1 year.
+5. Copy the token — it is shown once.
+
+Store the PAT in 1Password (or your secrets vault of choice) under `Conductor / VSCode Marketplace PAT` — same convention you use for other long-lived publisher credentials.
+
+### 2.3 Login + publish
+
+```bash
+cd phase-2/vscode-extension
+npx vsce login lfamily-labs
+# Paste the PAT when prompted.
+
+npx vsce publish
+# Or publish a specific .vsix:
+# npx vsce publish --packagePath conductor-0.3.0.vsix
+```
+
+Verify: https://marketplace.visualstudio.com/items?itemName=lfamily-labs.conductor (5-10 min indexing delay).
+
+---
+
+## 3. Open VSX Registry publish (Cursor / forks)
+
+### 3.1 Publisher account (one-time)
+
+1. Sign in at https://open-vsx.org with GitHub.
+2. Create a namespace `lfamily-labs` (must match `package.json` `"publisher"`).
+3. Sign the [Eclipse Foundation Publisher Agreement](https://open-vsx.org/user-settings/profile) — required before first publish.
+
+### 3.2 Personal Access Token
+
+1. https://open-vsx.org/user-settings/tokens → Generate new token.
+2. Description: `Conductor publish`.
+3. Copy the token.
+
+Store in 1Password under `Conductor / Open VSX PAT`.
+
+### 3.3 Publish
+
+```bash
+cd phase-2/vscode-extension
+npx ovsx create-namespace lfamily-labs -p <OPEN_VSX_PAT>   # one-time
+npx ovsx publish conductor-0.3.0.vsix -p <OPEN_VSX_PAT>
+```
+
+Verify: https://open-vsx.org/extension/lfamily-labs/conductor
+
+---
+
+## 4. Updating to a new version
+
+Per release:
+
+1. Bump `package.json` `version` (semver).
+2. Add a `## [x.y.z] — YYYY-MM-DD` block in `CHANGELOG.md`.
+3. Build + package:
+   ```bash
+   npm run compile && npx vsce package
+   ```
+4. Cross-publish:
+   ```bash
+   npx vsce publish
+   npx ovsx publish conductor-<version>.vsix -p <OPEN_VSX_PAT>
+   ```
+5. Tag in git: `git tag vscode-ext-v<version> && git push --tags`.
+
+Both marketplaces accept the same `.vsix` artifact — no separate build per registry.
+
+---
+
+## 5. Common publish failures
+
+| Symptom | Fix |
+|---|---|
+| `vsce` rejects with "missing repository" | Ensure `package.json` `repository.url` is set + reachable. |
+| `ovsx` rejects with "namespace not found" | Run `ovsx create-namespace` once. |
+| Marketplace shows extension but icon is blank | Replace `images/icon.png` placeholder with a 128x128 square PNG. |
+| PAT expired mid-publish | Regenerate (Section 2.2 / 3.2), re-login. |
+| `Cannot publish — manifest contains 'name' that doesn't match publisher` | `package.json` `publisher` must equal the registered publisher ID exactly. |
+
+---
+
+## 6. Roadmap (post-marketplace)
+
+- **Auto-update telemetry** — opt-in install count via `vsce` analytics dashboard.
+- **CI publishing** — GitHub Action that publishes on tag push (deferred until Phase 3, gated on the adopter project's CI-quota recovery).
+- **JetBrains plugin** — separate registry, separate dispatch (ADR-025 "out of scope").
+
+References: ADR-023 (marketplace strategy), ADR-025 (extension architecture).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omniconductor",
-  "version": "0.5.0",
+  "version": "1.0.1",
   "description": "Multi-coding-agent workflow framework. Write your project's rules, workflow, and discipline ONCE — install into Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, or Windsurf. Encodes the discipline developers most often skip — spec-before-code, review gates, session continuity — so your AI agents catch what's easy to miss.",
   "license": "Apache-2.0",
   "author": "LFamily Labs LLC",
@@ -26,6 +26,12 @@
     "docs/MANUAL-INSTALL.md",
     "docs/PROMPT-CACHING-GUIDE.md",
     "docs/CONTEXT-EDITING-GUIDE.md",
+    "docs/COMPATIBILITY-MATRIX.md",
+    "docs/ADAPTER-LIVE-VERIFICATION.md",
+    "docs/PUBLISH-GUIDE.md",
+    "docs/PUBLICATION-POLICY.md",
+    "docs/DESIGN-DECISIONS.md",
+    "docs/COMPARISON.md",
     "README.md",
     "VISION.md",
     "LICENSE",

package/tools/check-adapter-metadata.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# CONDUCTOR adapter-metadata consistency check (ADR-040).
+# Exit 0 = consistent, 1 = drift/inconsistency found, 2 = checker error.
+#
+# adapters/<tool>/metadata.json is the SINGLE SOURCE for enumerable adapter facts
+# (output paths, legacy paths, tier, capabilities, live-verification, headless CLI).
+# This checker asserts the places that state those facts agree with it:
+#
+#   M1: metadata.json exists for all 6 adapters, is valid JSON, has required keys —
+#       including NON-EMPTY nested fields (tier, live_verification.status,
+#       headless_cli.command, at least one output with a path)
+#   M2: every outputs[].path literal appears in adapters/<tool>/transform.sh
+#   M3: every outputs[].path with "validated": true appears in tools/validate-adapter-output.sh
+#   M4: every reflector_outputs[].path literal appears in adapters/<tool>/transform.sh
+#   M5: every legacy_paths[] literal is at least MENTIONED in transform.sh or the
+#       validator (legacy awareness in code/comments — a substring check, not proof of
+#       functional migration handling)
+#   M6: live_verification.status == "verified" requires a date, and that date must
+#       appear on a line of docs/ADAPTER-LIVE-VERIFICATION.md that names the tool
+#       (fixed-string matching; single-sourced verification claims)
+#   M7: headless_cli.command is in the `for c in ...` auto-detect list of
+#       core/reflector/run-weekly.sh (word match on that line — comments don't count)
+#   M8: tier — the COMPATIBILITY-MATRIX tier-assignment TABLE ROW (a line starting
+#       with '| **<tier> — ') must name the adapter's display_name
+#   M9: install.ala_carte strategy matches the code — "block" iff transform.sh
+#       contains the conductor:block marker machinery (ADR-044)
+#
+# Dependency: node (already required by the CLI + CI). No jq.
+
+set -u
+
+cd "$(dirname "$0")/.." || exit 2
+
+command -v node >/dev/null 2>&1 || { echo "ERROR: node is required" >&2; exit 2; }
+
+TOOLS="claude cursor copilot gemini codex windsurf"
+VALIDATOR="tools/validate-adapter-output.sh"
+LIVE_DOC="docs/ADAPTER-LIVE-VERIFICATION.md"
+MATRIX_DOC="docs/COMPATIBILITY-MATRIX.md"
+RUNNER="core/reflector/run-weekly.sh"
+
+FAIL=0
+fail() { echo "FAIL[$1] $2"; FAIL=1; }
+ok()   { echo "OK  [$1] $2"; }
+
+# Flatten metadata.json to TSV lines via node (validates nested completeness):
+#   OUTPUT<TAB>path<TAB>validated
+#   REFLECTOR<TAB>path
+#   LEGACY<TAB>path
+#   FIELD<TAB>key<TAB>value
+flatten_metadata() {
+  node -e '
+    const fs = require("fs");
+    const m = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    const die = (msg) => { console.error("INCOMPLETE: " + msg); process.exit(3); };
+    const req = ["tool","display_name","tier","outputs","reflector_outputs","legacy_paths","capabilities","live_verification","headless_cli"];
+    for (const k of req) if (!(k in m)) die("missing key " + k);
+    const nonEmpty = (v, name) => { if (typeof v !== "string" || !v.trim()) die(name + " must be a non-empty string"); };
+    nonEmpty(m.tool, "tool"); nonEmpty(m.display_name, "display_name"); nonEmpty(m.tier, "tier");
+    if (!Array.isArray(m.outputs) || m.outputs.length === 0) die("outputs must be a non-empty array");
+    for (const o of m.outputs) nonEmpty(o.path, "outputs[].path");
+    if (!Array.isArray(m.reflector_outputs)) die("reflector_outputs must be an array");
+    for (const r of m.reflector_outputs) nonEmpty(r.path, "reflector_outputs[].path");
+    if (!Array.isArray(m.legacy_paths)) die("legacy_paths must be an array");
+    for (const l of m.legacy_paths) nonEmpty(l, "legacy_paths[]");
+    if (!m.capabilities || !m.capabilities.tool_native || !m.capabilities.conductor_emitted) die("capabilities needs tool_native + conductor_emitted");
+    if (!m.live_verification) die("live_verification missing");
+    nonEmpty(m.live_verification.status, "live_verification.status");
+    if (m.live_verification.status === "verified") nonEmpty(m.live_verification.date, "live_verification.date (required when verified)");
+    if (!m.headless_cli) die("headless_cli missing");
+    nonEmpty(m.headless_cli.command, "headless_cli.command");
+    if (!m.install || (m.install.ala_carte !== "block" && m.install.ala_carte !== "per-file")) die("install.ala_carte must be block|per-file");
+    for (const o of m.outputs) console.log(["OUTPUT", o.path, o.validated ? "true" : "false"].join("\t"));
+    for (const r of m.reflector_outputs) console.log(["REFLECTOR", r.path].join("\t"));
+    for (const l of m.legacy_paths) console.log(["LEGACY", l].join("\t"));
+    console.log(["FIELD","tool",m.tool].join("\t"));
+    console.log(["FIELD","display_name",m.display_name].join("\t"));
+    console.log(["FIELD","tier",m.tier].join("\t"));
+    console.log(["FIELD","live_status",m.live_verification.status].join("\t"));
+    console.log(["FIELD","live_date",m.live_verification.date || ""].join("\t"));
+    console.log(["FIELD","headless_command",m.headless_cli.command].join("\t"));
+    console.log(["FIELD","ala_carte",m.install.ala_carte].join("\t"));
+  ' "$1"
+}
+
+for tool in $TOOLS; do
+  meta="adapters/$tool/metadata.json"
+  transform="adapters/$tool/transform.sh"
+
+  # M1 — exists + valid JSON + required keys + non-empty nested fields
+  if [ ! -f "$meta" ]; then
+    fail "M1" "$meta missing"
+    continue
+  fi
+  if ! flat="$(flatten_metadata "$meta" 2>&1)"; then
+    fail "M1" "$meta invalid or incomplete: $(printf '%s' "$flat" | head -1)"
+    continue
+  fi
+  ok "M1" "$meta valid + complete"
+
+  tier="";     display=""
+  live_status=""; live_date=""; headless=""; ala_carte=""
+  while IFS=$'\t' read -r kind a b; do
+    case "$kind" in
+      OUTPUT)
+        # M2 — path literal present in transform.sh
+        if grep -qF -- "$a" "$transform"; then
+          ok "M2" "$tool: transform.sh mentions '$a'"
+        else
+          fail "M2" "$tool: outputs path '$a' NOT found in $transform (metadata drift?)"
+        fi
+        # M3 — validated paths must be known to the validator
+        if [ "$b" = "true" ]; then
+          if grep -qF -- "$a" "$VALIDATOR"; then
+            ok "M3" "$tool: validator covers '$a'"
+          else
+            fail "M3" "$tool: validated path '$a' NOT found in $VALIDATOR"
+          fi
+        fi
+        ;;
+      REFLECTOR)
+        # M4 — reflector path literal present in transform.sh
+        if grep -qF -- "$a" "$transform"; then
+          ok "M4" "$tool: transform.sh mentions reflector path '$a'"
+        else
+          fail "M4" "$tool: reflector path '$a' NOT found in $transform"
+        fi
+        ;;
+      LEGACY)
+        # M5 — legacy path at least mentioned in code (awareness, not proof of handling)
+        if grep -qF -- "$a" "$transform" || grep -qF -- "$a" "$VALIDATOR"; then
+          ok "M5" "$tool: legacy path '$a' mentioned in code"
+        else
+          fail "M5" "$tool: legacy path '$a' not mentioned in $transform or $VALIDATOR"
+        fi
+        ;;
+      FIELD)
+        case "$a" in
+          tier) tier="$b" ;;
+          display_name) display="$b" ;;
+          live_status) live_status="$b" ;;
+          live_date) live_date="$b" ;;
+          headless_command) headless="$b" ;;
+          ala_carte) ala_carte="$b" ;;
+          tool)
+            [ "$b" = "$tool" ] || fail "M1" "$meta: tool field '$b' != directory '$tool'"
+            ;;
+        esac
+        ;;
+    esac
+  done <<< "$flat"
+
+  # M6 — verified => dated + the date co-appears with the tool name in the live doc
+  # (fixed-string greps; no user data interpolated into a regex)
+  if [ "$live_status" = "verified" ]; then
+    if [ -z "$live_date" ]; then
+      fail "M6" "$tool: live_verification.status=verified but date is empty"
+    elif { grep -iF -- "$display" "$LIVE_DOC"; grep -iF -- "$tool" "$LIVE_DOC"; } | grep -qF -- "$live_date"; then
+      ok "M6" "$tool: live verification date $live_date matches $LIVE_DOC"
+    else
+      fail "M6" "$tool: verified date '$live_date' not found next to '$display' in $LIVE_DOC"
+    fi
+  else
+    ok "M6" "$tool: live status '$live_status' (no date assertion)"
+  fi
+
+  # M7 — headless CLI must be a word in the runner's `for c in ...` auto-detect list
+  # (strict: comments/usage text do NOT count; strip the trailing `; do`)
+  detect_line="$(grep -E 'for c in ' "$RUNNER" | head -1 | sed 's/;.*$//')"
+  if [ -z "$detect_line" ]; then
+    fail "M7" "no 'for c in' auto-detect line found in $RUNNER"
+  elif printf '%s\n' "$detect_line" | grep -qE "(^| )${headless}( |\$)"; then
+    ok "M7" "$tool: headless CLI '$headless' in $RUNNER auto-detect list"
+  else
+    fail "M7" "$tool: headless CLI '$headless' NOT in $RUNNER auto-detect list: $detect_line"
+  fi
+
+  # M9 — à-la-carte strategy matches the code (block ⇔ marker machinery present)
+  if [ "$ala_carte" = "block" ]; then
+    if grep -qF 'conductor:block' "$transform"; then
+      ok "M9" "$tool: ala_carte=block matches conductor:block machinery in transform.sh"
+    else
+      fail "M9" "$tool: metadata says ala_carte=block but $transform has no conductor:block machinery"
+    fi
+  else
+    if grep -qF 'conductor:block' "$transform"; then
+      fail "M9" "$tool: metadata says ala_carte=per-file but $transform contains conductor:block machinery"
+    else
+      ok "M9" "$tool: ala_carte=per-file (no block machinery, as declared)"
+    fi
+  fi
+
+  # M8 — the tier-assignment TABLE ROW must name this adapter
+  tier_row="$(grep -E "^\| \*\*${tier} — " "$MATRIX_DOC" | head -1)"
+  if [ -z "$tier_row" ]; then
+    fail "M8" "$tool: no tier table row '| **${tier} — ' in $MATRIX_DOC"
+  elif printf '%s' "$tier_row" | grep -qF -- "$display"; then
+    ok "M8" "$tool: matrix tier row ${tier} names ${display}"
+  else
+    fail "M8" "$tool: matrix tier row ${tier} does not name '${display}': $tier_row"
+  fi
+done
+
+echo
+if [ "$FAIL" -eq 0 ]; then
+  echo "OK — adapter metadata is consistent with transform.sh / validator / live-verification doc / matrix."
+  exit 0
+fi
+echo "FAIL — adapter metadata inconsistency. metadata.json is the single source (ADR-040):"
+echo "fix the code/doc to match it, or update metadata.json if reality changed."
+exit 1

package/tools/check-stale-tokens.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# CONDUCTOR stale-token + version-stamp check (ADR-039).
+# Exit 0 = clean, 1 = stale claim or stamp drift found, 2 = checker error.
+#
+# Two check classes:
+#   A. Version stamps — mechanizes the R7 release checklist items that drifted twice:
+#      A1: README.md has EXACTLY ONE status line, and it stamps the CURRENT
+#          package.json version (policy: re-stamped on EVERY release, patches
+#          included — ADR-039).
+#      A2: CHANGELOG.md has a section for the current version.
+#   B. Stale-claim tokens — known-false claims (data-driven from tools/stale-tokens.txt).
+#      A line matching a token fails UNLESS its CONTENT (not its file path) matches the
+#      token's allow_regex (legacy/historical qualifiers) or carries an inline waiver
+#      `stale-ok: <why>`.
+#
+# Scanned paths (living public surface — what an adopter reads as CURRENT truth):
+#   README.md / VISION.md / ROADMAP.md
+#   docs/*.md            (top level only)
+#   core/                (all rule/template text)
+#   adapters/            (READMEs, specs, transform.sh emitted text, templates)
+#
+# Excluded (frozen history / private / machine data / self):
+#   CHANGELOG.md, docs/DESIGN-DECISIONS.md (ADRs), docs/audits|plans|specs|data/,
+#   docs/KPI.md, docs/GO-TO-MARKET.md, docs/LAUNCH-*.md, docs/CONDUCTOR-V0.2-DESIGN.md,
+#   CLAUDE.md / CURRENT_WORK.md / SESSION_HANDOFF.md (private session docs),
+#   adapters/*/metadata.json (machine data — its legacy_paths MUST name legacy tokens;
+#   checked by tools/check-adapter-metadata.sh instead), archive/, tools/ (this checker
+#   + its data file), scripts/, phase-2/ (frozen scaffold).
+#
+# See docs/DESIGN-DECISIONS.md ADR-026 (frozen-history carve-outs) + ADR-039 (this policy).
+
+set -u
+
+cd "$(dirname "$0")/.." || exit 2
+
+TOKENS_FILE="tools/stale-tokens.txt"
+[ -f "$TOKENS_FILE" ] || { echo "ERROR: $TOKENS_FILE not found" >&2; exit 2; }
+
+FAIL=0
+
+# --------------------------------------------------------------------------
+# Class A — version stamps
+# --------------------------------------------------------------------------
+PKG_VERSION="$(sed -n -E 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' package.json 2>/dev/null | head -n 1)"
+if [ -z "$PKG_VERSION" ]; then
+  echo "ERROR: cannot read version from package.json" >&2
+  exit 2
+fi
+
+STATUS_LINES="$(grep -cE '^> \*\*Status' README.md || true)"
+if [ "$STATUS_LINES" -ne 1 ]; then
+  echo "FAIL[A1] README.md must have exactly ONE '> **Status' line (found ${STATUS_LINES}) — a leftover stamp from a previous release is itself drift (ADR-039)"
+  grep -nE '^> \*\*Status' README.md | head -4
+  FAIL=1
+elif grep -E '^> \*\*Status' README.md | grep -qF "v${PKG_VERSION}"; then
+  echo "OK  [A1] README.md status line stamps v${PKG_VERSION}"
+else
+  echo "FAIL[A1] README.md status line does not stamp v${PKG_VERSION} (package.json is the single source; re-stamp on EVERY release, patches included — ADR-039)"
+  grep -nE '^> \*\*Status' README.md | head -2
+  FAIL=1
+fi
+
+if grep -qF "## [${PKG_VERSION}]" CHANGELOG.md; then
+  echo "OK  [A2] CHANGELOG.md has a [${PKG_VERSION}] section"
+else
+  echo "FAIL[A2] CHANGELOG.md has no section for [${PKG_VERSION}] (R7 checklist: [Unreleased] -> [${PKG_VERSION}] — <date>)"
+  FAIL=1
+fi
+
+# A3 (advisory, never fails the check): npm registry lag. The docs say "published to
+# npm"; if the registry is behind package.json, `npm publish` is the missing R7 step.
+# Skipped silently when npm/network is unavailable (CI-safe).
+if command -v npm >/dev/null 2>&1; then
+  REG_VERSION="$(npm view omniconductor version 2>/dev/null || true)"
+  if [ -n "$REG_VERSION" ] && [ "$REG_VERSION" != "$PKG_VERSION" ]; then
+    echo "WARN[A3] npm registry serves omniconductor@${REG_VERSION} but package.json is ${PKG_VERSION} — run \`npm publish\` (advisory only)"
+  fi
+fi
+
+# --------------------------------------------------------------------------
+# Class B — stale-claim tokens
+# --------------------------------------------------------------------------
+# Build the scan file list.
+SCAN_FILES=()
+for f in README.md VISION.md ROADMAP.md; do
+  [ -f "$f" ] && SCAN_FILES+=("$f")
+done
+while IFS= read -r f; do
+  case "$(basename "$f")" in
+    DESIGN-DECISIONS.md|KPI.md|GO-TO-MARKET.md|CONDUCTOR-V0.2-DESIGN.md|LAUNCH-*.md) continue ;;
+  esac
+  SCAN_FILES+=("$f")
+done < <(find docs -maxdepth 1 -type f -name '*.md' | sort)
+while IFS= read -r f; do
+  SCAN_FILES+=("$f")
+done < <(find core adapters -type f \( -name '*.md' -o -name '*.sh' -o -name '*.template' -o -name '*.json' \) ! -name 'metadata.json' | sort)
+
+TOTAL_HITS=0
+while IFS=$'\t' read -r pattern reason hint allow_regex || [ -n "${pattern:-}" ]; do
+  # Strip CR from every field (CRLF-saved data file must not corrupt the last column).
+  pattern="${pattern%$'\r'}"; reason="${reason-}"; hint="${hint-}"; allow_regex="${allow_regex-}"
+  reason="${reason%$'\r'}"; hint="${hint%$'\r'}"; allow_regex="${allow_regex%$'\r'}"
+  case "$pattern" in ''|'#'*) continue ;; esac
+  matches="$(grep -FIn -- "$pattern" "${SCAN_FILES[@]}" 2>/dev/null | grep -v 'stale-ok:' || true)"
+  if [ -n "$matches" ] && [ -n "$allow_regex" ]; then
+    # Apply allow_regex to the line CONTENT only — never to the "file:line:" prefix,
+    # so a file path containing e.g. "legacy" cannot waive hits inside it.
+    matches="$(printf '%s\n' "$matches" | grep -Ev -- "^[^:]*:[0-9]+:.*(${allow_regex})" || true)"
+  fi
+  if [ -n "$matches" ]; then
+    count="$(printf '%s\n' "$matches" | wc -l | tr -d ' ')"
+    echo "FAIL[B]  stale claim '$pattern' — $count line(s)"
+    echo "         why stale : $reason"
+    echo "         fix       : $hint"
+    printf '%s\n' "$matches" | head -8 | sed 's/^/         /'
+    echo
+    FAIL=1
+    TOTAL_HITS=$((TOTAL_HITS + count))
+  fi
+done < "$TOKENS_FILE"
+
+if [ "$FAIL" -eq 0 ]; then
+  echo "OK — no stale claims on living surfaces; version stamps consistent (v${PKG_VERSION})."
+  exit 0
+fi
+
+echo "FAIL — stale-token check found problems (stale lines: ${TOTAL_HITS})."
+echo "Fix the claim, add a legacy qualifier matching the token's allow_regex,"
+echo "or (rarely) add an inline 'stale-ok: <why>' waiver. Policy: ADR-039."
+exit 1