superpowers-manager 0.10.2 → 0.11.0

package/README.md

@@ -42,7 +42,7 @@ See [version selection](https://github.com/j7an/superpowers-manager/blob/main/do
 
 ## Start with your agent
 
-The five harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
+The five harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex. Only the official `obra/superpowers` repository is supported; other sources are experimental on every harness and need `--allow-experimental` to install, or to update when the update would install or reinstall.
 
 ### Codex
 
@@ -56,7 +56,7 @@ Codex installs the Manager-owned marketplace plugin after preparation and
 validation. Review upstream hook definitions with Codex's `/hooks` flow before
 trusting or running them; updates can change a referenced script or surface a
 new definition. The manager neither creates hooks nor changes Codex trust state.
-See the [Codex reference](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md#durable-storage-migration-and-recovery) for durable storage, migration, and recovery.
+See the [Codex reference](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md#upstream-admission) for upstream admission, durable storage, migration, and recovery.
 
 ### Pi
 
@@ -68,8 +68,8 @@ npx superpowers-manager update --harness pi
 
 Pi installs a separately validated, Manager-owned frozen snapshot. Restart Pi
 after a successful install, activating update, or removal. See the
-[Pi reference](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md)
-for compatibility, experimental opt-in, and recovery behavior.
+[Pi reference](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md#upstream-admission)
+for upstream admission, compatibility, and recovery behavior.
 
 ### OpenCode
 
@@ -81,8 +81,8 @@ npx superpowers-manager update --harness opencode
 
 OpenCode installs a separately validated, Manager-owned frozen snapshot. Restart
 OpenCode after a successful install, activating update, or removal. See the
-[OpenCode reference](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md)
-for global configuration, conflicts, and recovery behavior.
+[OpenCode reference](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md#upstream-admission)
+for upstream admission, global configuration, conflicts, and recovery behavior.
 
 ### Claude Code
 
@@ -94,8 +94,8 @@ npx superpowers-manager update --harness claude-code
 
 Claude Code installs a validated, Manager-owned local marketplace snapshot.
 Restart Claude Code or run `/reload-plugins` after an install, activating update,
-or removal. See the [Claude Code reference](https://github.com/j7an/superpowers-manager/blob/main/docs/claude-code.md)
-for conflicts, hooks, and recovery.
+or removal. See the [Claude Code reference](https://github.com/j7an/superpowers-manager/blob/main/docs/claude-code.md#upstream-admission)
+for upstream admission, conflicts, hooks, and recovery.
 
 ### Hermes Agent
 
@@ -106,8 +106,8 @@ npx superpowers-manager update --harness hermes
 ```
 
 Restart Hermes sessions after an install, activating update, or removal. See
-the [Hermes Agent reference](https://github.com/j7an/superpowers-manager/blob/main/docs/hermes.md)
-for plugin layout, compatibility, route switching, and recovery.
+the [Hermes Agent reference](https://github.com/j7an/superpowers-manager/blob/main/docs/hermes.md#upstream-admission)
+for upstream admission, plugin layout, compatibility, route switching, and recovery.
 
 To remove a Manager-owned installation, choose one harness explicitly:
 
@@ -163,7 +163,7 @@ The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs
 
 ## Requirements and platforms
 
-The installed package requires Node >=24. Native source, tests, and packaging tooling target latest Node 24. Every other requirement is command-specific and is checked before dispatch. This table is derived from production by `tests/bin/readme-requirements.test.ts`.
+The installed package requires Node >=24. Native source, tests, and packaging tooling target latest Node 24; CI also runs the shared suite on latest Node 26. Every other requirement is command-specific and is checked before dispatch. This table is derived from production by `tests/bin/readme-requirements.test.ts`.
 
 <!-- requirements:begin -->
 
@@ -182,7 +182,7 @@ The installed package requires Node >=24. Native source, tests, and packaging to
 
 Generated Codex manifests preserve upstream JSON number tokens while rejecting non-finite decimal or exponent values.
 
-macOS and Linux are tested. WSL2 is supported for the established Codex path; Pi in WSL2 and native Windows remain untested. The manager runs in-process and does not require Git Bash. The [Pi reference](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md#runtime-compatibility) explains its runtime qualification and admission checks. OpenCode support currently covers 1.x; OpenCode 2.x is untested and not certified as compatible (see the [OpenCode reference](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md)).
+macOS and Linux are tested. WSL2 is supported for the established Codex path; Pi in WSL2 and native Windows remain untested. The manager runs in-process and does not require Git Bash. Each harness reference's Upstream admission section lists what is checked. OpenCode support covers the 1.x and 2.x lines (see the [OpenCode reference](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md)).
 
 Native test versions qualify integration mechanisms; they are not runtime allowlists, and an untested runtime is not automatically certified as compatible.
 

package/dist/cli.js

@@ -216,6 +216,7 @@ function usage() {
         "  update --harness opencode [--allow-experimental]",
         "  uninstall --harness opencode",
         "  --harness=codex, --harness=pi, --harness=opencode, --harness=claude-code, and --harness=hermes are also accepted after the command.",
+        "  --allow-experimental (install, update) admits a custom upstream source on any harness.",
         "",
         "Environment overrides (used by in-process commands): SUPERPOWERS_REF,",
         "SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,",

package/dist/harnesses/claude-code/install.js

@@ -163,7 +163,8 @@ export async function installClaudeCode(artifact, ctx, deps = DEFAULTS) {
         const assessment = await readClaudeCodePackageAssessment(artifact.root);
         if (assessment.receipt.digest !== artifact.identity ||
             assessment.receipt.commit !== artifact.commit ||
-            assessment.compatibility.kind !== "supported")
+            (assessment.compatibility.kind !== "supported" &&
+                assessment.compatibility.kind !== "experimental"))
             throw new ClaudeCodeStep("the Claude Code prepared artifact changed before activation");
         const leftovers = await leftoverPublicationMaterial(paths);
         if (leftovers.length > 0)

package/dist/harnesses/claude-code/prepare.js

@@ -7,7 +7,7 @@ import { SEMVER_RE } from "../../domain/refs.js";
 import { classifyPathNoFollow } from "../../safe-path.js";
 import { SafetyError } from "../../safety-error.js";
 import { validateSource } from "../../selection.js";
-import { createSnapshotReceipts, } from "../../snapshot-package.js";
+import { createSnapshotReceipts, isOfficialSnapshotSource, } from "../../snapshot-package.js";
 import { createSnapshotPreparation } from "../../snapshot-prepare.js";
 import { manifestVersionForRef } from "../../upstream-version.js";
 import { assertClaudeCodeStorageSafe, claudeCodePaths } from "./paths.js";
@@ -16,6 +16,7 @@ const GENERATION = "claude-code-native-plugin-v1";
 async function assessClaudeCodeCompatibility(root, selection) {
     try {
         validateSource(selection.effectiveSource);
+        const official = isOfficialSnapshotSource(selection.effectiveSource);
         const manifest = await readArtifactObject(root, join(root, CLAUDE_CODE_MANIFEST));
         if (manifest.name !== "superpowers" ||
             typeof manifest.version !== "string" ||
@@ -26,9 +27,11 @@ async function assessClaudeCodeCompatibility(root, selection) {
         if ((await classifyPathNoFollow(hooks)) !== "missing")
             await readArtifactObject(root, hooks);
         return {
-            kind: "supported",
+            kind: official ? "supported" : "experimental",
             generation: GENERATION,
-            reason: "native Claude Code plugin",
+            reason: official
+                ? "native Claude Code plugin"
+                : "native Claude Code plugin from a custom source",
         };
     }
     catch {

package/dist/harnesses/claude-code/state.js

@@ -200,7 +200,8 @@ export async function inspectClaudeCodeInstalled(selection, ctx, run = runClaude
         return mismatch(observed);
     try {
         const prepared = await readClaudeCodePackageAssessment(facts.paths.preparedRoot);
-        if (prepared.compatibility.kind !== "supported" ||
+        if ((prepared.compatibility.kind !== "supported" &&
+            prepared.compatibility.kind !== "experimental") ||
             prepared.receipt.commit !== selection.desiredCommit ||
             !sameSnapshotSource(prepared.receipt.source, selection.effectiveSource) ||
             facts.snapshot.receipt.commit !== prepared.receipt.commit ||

package/dist/harnesses/codex/compatibility.js

@@ -4,6 +4,7 @@ import { classifyPathNoFollow, assertExistingContained, } from "../../safe-path.
 import { classifyHooks, readManifest } from "./hooks.js";
 import { SEMVER_RE } from "../../domain/refs.js";
 import { validateSource } from "../../selection.js";
+import { isOfficialSnapshotSource } from "../../snapshot-package.js";
 import { writeFile } from "node:fs/promises";
 import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, digestArtifactTree, readArtifactObject, } from "../../artifact-tree.js";
 import { COMMIT_RE } from "../../domain/refs.js";
@@ -78,6 +79,7 @@ export async function readCodexAssessment(root) {
 export async function assessCodexCompatibility(root, selection) {
     try {
         validateSource(selection.effectiveSource);
+        const official = isOfficialSnapshotSource(selection.effectiveSource);
         await validateNativeSkill(root);
         for (const path of [
             ".codex/superpowers-codex",
@@ -97,9 +99,11 @@ export async function assessCodexCompatibility(root, selection) {
             await classifyHooks(manifest, "upstream", root);
         }
         return {
-            kind: "supported",
+            kind: official ? "supported" : "experimental",
             generation: "codex-native-skills-v1",
-            reason: "native Codex skill discovery",
+            reason: official
+                ? "native Codex skill discovery"
+                : "native Codex skill discovery from a custom source",
         };
     }
     catch {

package/dist/harnesses/codex/prepare.js

@@ -173,7 +173,8 @@ export async function prepareCodexCandidate(input, ctx) {
         return { status: built.status, outcome: built.outcome };
     }
     const compatibility = await assessCodexCompatibility(input.upstreamRoot, input.selection);
-    if (compatibility.kind === "supported") {
+    if (compatibility.kind === "supported" ||
+        compatibility.kind === "experimental") {
         try {
             await writeCodexAssessment(input.candidateRoot, input.selection, (await isFile(join(input.upstreamRoot, ".codex-plugin/plugin.json")))
                 ? "upstream"
@@ -205,7 +206,8 @@ export async function inspectCodexPrepared(selection, ctx) {
         const source = await readStrictProvenanceField(join(artifact.root, ".superpowers-upstream.json"), "source");
         if (artifact.commit === selection.desiredCommit &&
             source === selection.effectiveSource) {
-            if (artifact.compatibility.kind === "supported")
+            if (artifact.compatibility.kind === "supported" ||
+                artifact.compatibility.kind === "experimental")
                 return successResult("inspect-prepared", {
                     kind: "current",
                     artifact,
@@ -243,7 +245,8 @@ export async function readCodexPrepared(ctx) {
     }
     try {
         const artifact = await readCodexAssessment(codexPreparationLocation(ctx).destinationRoot);
-        if (artifact.compatibility.kind !== "supported")
+        if (artifact.compatibility.kind !== "supported" &&
+            artifact.compatibility.kind !== "experimental")
             throw new Error("unsupported profile");
         return successResult("read-prepared", artifact, []);
     }

package/dist/harnesses/codex/publication.js

@@ -213,7 +213,8 @@ async function verifyPrepared(artifact, expectedRoot) {
     const assessed = await readCodexAssessment(artifact.root);
     if (assessed.root !== artifact.root ||
         assessed.commit !== artifact.commit ||
-        assessed.compatibility.kind !== "supported") {
+        (assessed.compatibility.kind !== "supported" &&
+            assessed.compatibility.kind !== "experimental")) {
         throw new Error("Codex prepared artifact changed");
     }
     return await digestArtifactTree(artifact.root);
@@ -325,7 +326,8 @@ async function verifyActivated(pending, dependencies, ctx, messages) {
     }
     const active = await readCodexAssessment(native.activeRoot);
     if (active.commit !== published.artifact.commit ||
-        active.compatibility.kind !== "supported" ||
+        (active.compatibility.kind !== "supported" &&
+            active.compatibility.kind !== "experimental") ||
         (await digestArtifactTree(active.root)) !==
             (await digestArtifactTree(published.artifact.root))) {
         throw new Error("active Codex plugin differs from publication");

package/dist/harnesses/codex/state.js

@@ -138,7 +138,8 @@ export async function inspectCodexInstallation(selection, ctx, readNative = code
         return mismatch("durable Codex marketplace is missing", messages, observedIdentity);
     try {
         if (marketplace.artifact.commit !== selection.desiredCommit ||
-            marketplace.artifact.compatibility.kind !== "supported" ||
+            (marketplace.artifact.compatibility.kind !== "supported" &&
+                marketplace.artifact.compatibility.kind !== "experimental") ||
             !(await matchesSelection(marketplace.artifact.root, selection))) {
             return mismatch("durable Codex marketplace differs from selection", messages, observedIdentity);
         }
@@ -185,7 +186,8 @@ export async function inspectCodexInstallation(selection, ctx, readNative = code
     }
     try {
         if (active.commit !== selection.desiredCommit ||
-            active.compatibility.kind !== "supported" ||
+            (active.compatibility.kind !== "supported" &&
+                active.compatibility.kind !== "experimental") ||
             !(await matchesSelection(active.root, selection)) ||
             activeDigest !== durableDigest) {
             return mismatch("active Codex plugin payload differs from durable marketplace", messages, active.commit);

package/dist/harnesses/hermes/install.js

@@ -105,7 +105,8 @@ export async function installHermes(artifact, ctx, deps = DEFAULTS) {
         const assessment = await readHermesPackageAssessment(artifact.root);
         if (assessment.receipt.digest !== artifact.identity ||
             assessment.receipt.commit !== artifact.commit ||
-            assessment.compatibility.kind !== "supported")
+            (assessment.compatibility.kind !== "supported" &&
+                assessment.compatibility.kind !== "experimental"))
             throw new HermesStep("the Hermes prepared artifact changed before activation");
         previouslyEnabled =
             (await readHermesStatus(paths, ctx.env ?? {})) === "enabled";
@@ -130,7 +131,8 @@ export async function installHermes(artifact, ctx, deps = DEFAULTS) {
         const staged = await readHermesPackageAssessment(pending.stage);
         if (staged.receipt.digest !== artifact.identity ||
             staged.receipt.commit !== artifact.commit ||
-            staged.compatibility.kind !== "supported")
+            (staged.compatibility.kind !== "supported" &&
+                staged.compatibility.kind !== "experimental"))
             throw new HermesStep("the staged Hermes artifact changed");
         // Keep backups outside plugins so Hermes discovery sees only the live copy.
         if (ownership.kind === "owned") {

package/dist/harnesses/hermes/prepare.js

@@ -5,7 +5,7 @@ import { readArtifactFile, validateNativeSkill } from "../../artifact-tree.js";
 import { assertNoFollowType, classifyPathNoFollow } from "../../safe-path.js";
 import { SafetyError } from "../../safety-error.js";
 import { validateSource } from "../../selection.js";
-import { createSnapshotReceipts, } from "../../snapshot-package.js";
+import { createSnapshotReceipts, isOfficialSnapshotSource, } from "../../snapshot-package.js";
 import { createSnapshotPreparation } from "../../snapshot-prepare.js";
 import { assertHermesStorageSafe, hermesPaths } from "./paths.js";
 async function flattenHermesPlugin(root) {
@@ -26,6 +26,7 @@ async function flattenHermesPlugin(root) {
 async function assessHermesCompatibility(root, selection) {
     try {
         validateSource(selection.effectiveSource);
+        const official = isOfficialSnapshotSource(selection.effectiveSource);
         await readArtifactFile(root, join(root, "__pycache__"), 0);
         for (const relative of [
             "plugin.yaml",
@@ -35,9 +36,11 @@ async function assessHermesCompatibility(root, selection) {
             await assertNoFollowType(join(root, relative), ["regular-file"]);
         await validateNativeSkill(root);
         return {
-            kind: "supported",
+            kind: official ? "supported" : "experimental",
             generation: "hermes-flat-plugin-v1",
-            reason: "native Hermes plugin",
+            reason: official
+                ? "native Hermes plugin"
+                : "native Hermes plugin from a custom source",
         };
     }
     catch {

package/dist/harnesses/hermes/state.js

@@ -97,7 +97,8 @@ export async function inspectHermesInstalled(selection, ctx) {
         return mismatch();
     try {
         const prepared = await readHermesPackageAssessment(facts.paths.preparedRoot);
-        if (prepared.compatibility.kind !== "supported" ||
+        if ((prepared.compatibility.kind !== "supported" &&
+            prepared.compatibility.kind !== "experimental") ||
             prepared.receipt.commit !== selection.desiredCommit ||
             !sameSnapshotSource(prepared.receipt.source, selection.effectiveSource) ||
             facts.ownership.receipt.commit !== selection.desiredCommit ||

package/dist/harnesses/opencode/package.js

@@ -1,36 +1,11 @@
 import { join } from "node:path";
 import { readArtifactObject, validateNativeSkill, } from "../../artifact-tree.js";
 import { SEMVER_RE } from "../../domain/refs.js";
-import { assertNoFollowType } from "../../safe-path.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
 import { validateSource } from "../../selection.js";
 import { createSnapshotReceipts, isOfficialSnapshotSource, requireNoSnapshotDependencies, requireSnapshotBootstrap, } from "../../snapshot-package.js";
 const BOOTSTRAP = ".opencode/plugins/superpowers.js";
 const ENTRYPOINT = "index.js";
-// Exact-byte allowlist, matched as a unit: a bootstrap and the V2 entrypoint
-// that shipped with it were qualified together in the native container. Adding
-// either half alone would admit a combination no container ever ran. Every
-// upstream change needs re-qualification before its bytes are added here.
-const QUALIFIED_PROFILES = [
-    {
-        // obra/superpowers v6.0.0-v6.3.0 — no V2 entrypoint shipped
-        bootstrap: {
-            size: 5464,
-            sha256: "a5c5e1dbb0abfbd6ec3322b724b9a7b3318bbbb3d83f9a661c56ae0ed0a3adb8",
-        },
-        entrypoint: null,
-    },
-    {
-        // obra/superpowers v6.4.1
-        bootstrap: {
-            size: 17617,
-            sha256: "c979fe5a9fd6fddc9bc9730b34b25989f9d53939eed7d594c4564f6e47495f26",
-        },
-        entrypoint: {
-            size: 536,
-            sha256: "f0132fd5339befeb99ba903b1619fd9530969e5b4a1ea8cecf0b0a7f0213a099",
-        },
-    },
-];
 export async function assessOpenCodeCompatibility(root, selection) {
     try {
         validateSource(selection.effectiveSource);
@@ -43,15 +18,11 @@ export async function assessOpenCodeCompatibility(root, selection) {
             throw new Error("package metadata");
         requireNoSnapshotDependencies(pkg);
         await validateNativeSkill(root);
-        const matched = await Promise.any(QUALIFIED_PROFILES.map(async (profile) => {
-            await requireSnapshotBootstrap(root, BOOTSTRAP, profile.bootstrap.size, profile.bootstrap.sha256);
-            if (profile.entrypoint === null)
-                await assertNoFollowType(join(root, ENTRYPOINT), ["missing"]);
-            else
-                await requireSnapshotBootstrap(root, ENTRYPOINT, profile.entrypoint.size, profile.entrypoint.sha256);
-            return profile;
-        }));
-        const generation = matched.entrypoint === null
+        await requireSnapshotBootstrap(root, BOOTSTRAP);
+        const v1 = (await classifyPathNoFollow(join(root, ENTRYPOINT))) === "missing";
+        if (!v1)
+            await requireSnapshotBootstrap(root, ENTRYPOINT);
+        const generation = v1
             ? "opencode-native-bootstrap-v1"
             : "opencode-native-bootstrap-v2";
         const official = isOfficialSnapshotSource(selection.effectiveSource);
@@ -59,14 +30,14 @@ export async function assessOpenCodeCompatibility(root, selection) {
             kind: official ? "supported" : "experimental",
             generation,
             reason: official
-                ? "qualified upstream-native OpenCode bootstrap"
-                : "qualified OpenCode mechanics from a custom source",
+                ? "upstream-native OpenCode bootstrap"
+                : "upstream-native OpenCode bootstrap from a custom source",
         };
     }
     catch {
         return {
             kind: "unsupported",
-            reason: `OpenCode package does not match the qualified native bootstrap profile: ${root}`,
+            reason: `OpenCode package does not provide a native OpenCode bootstrap: ${root}`,
         };
     }
 }

package/dist/harnesses/pi/compatibility.js

@@ -23,19 +23,19 @@ export async function assessPiCompatibility(root, selection) {
             throw new Error("resource declaration");
         requireNoSnapshotDependencies(pkg);
         await validateNativeSkill(root);
-        await requireSnapshotBootstrap(root, ".pi/extensions/superpowers.ts", 4283, "39c27000c047f8a1399a76e032e4cd239d7bdb0be168a121f46a2ac719deaae0");
+        await requireSnapshotBootstrap(root, ".pi/extensions/superpowers.ts");
         return {
             kind: official ? "supported" : "experimental",
             generation: "pi-native-bootstrap-v1",
             reason: official
-                ? "qualified upstream-native Pi bootstrap"
-                : "qualified Pi mechanics from a custom source",
+                ? "upstream-native Pi bootstrap"
+                : "upstream-native Pi bootstrap from a custom source",
         };
     }
     catch {
         return {
             kind: "unsupported",
-            reason: `Pi package does not match the qualified native bootstrap profile: ${root}`,
+            reason: `Pi package does not provide a native Pi bootstrap: ${root}`,
         };
     }
 }

package/dist/snapshot-package.js

@@ -70,12 +70,13 @@ export function requireNoSnapshotDependencies(pkg) {
             throw new Error("runtime dependencies");
     }
 }
-export async function requireSnapshotBootstrap(root, relativePath, expectedSize, expectedDigest) {
+// Ceiling: structural admission cannot catch an upstream bootstrap whose
+// behavior breaks the integration; add a behavior-level check if that happens
+// in the field.
+export async function requireSnapshotBootstrap(root, relativePath) {
     const bootstrap = join(root, relativePath);
-    const bytes = await readArtifactFile(root, bootstrap, expectedSize);
-    if ((await lstat(bootstrap)).mode & 0o111 ||
-        bytes.length !== expectedSize ||
-        createHash("sha256").update(bytes).digest("hex") !== expectedDigest)
+    await readArtifactFile(root, bootstrap);
+    if ((await lstat(bootstrap)).mode & 0o111)
         throw new Error("bootstrap implementation");
 }
 // strictGeneration=false admits a generation on unknown/unsupported

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-manager",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Install obra/superpowers directly from upstream for Codex, Pi, OpenCode, Claude Code, and Hermes Agent. Stay on a known-good release or commit, try a branch, and upgrade when you choose.",
   "keywords": [
     "superpowers",
@@ -38,7 +38,7 @@
   ],
   "license": "MIT",
   "type": "module",
-  "packageManager": "pnpm@12.9.1",
+  "packageManager": "pnpm@12.17.0",
   "scripts": {
     "lint": "oxlint src/ tests/",
     "format": "prettier --write src/ tests/",