superpowers-manager 0.5.0 → 0.5.1

package/README.md

@@ -1,9 +1,45 @@
 # Superpowers Manager
 
-Install and explicitly refresh the latest stable [`obra/superpowers`](https://github.com/obra/superpowers) release. Superpowers Manager supports Codex and the Pi coding agent without waiting for a marketplace copy to catch up.
+Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from upstream for Codex and the Pi coding agent. Stay on a known-good release or commit, try a branch, and upgrade when you choose—without waiting for a marketplace copy to catch up.
 
 > Unofficial community integration. Not affiliated with the `obra/superpowers` maintainers.
 
+## Choose what you run
+
+Start with the latest stable release by default, or choose the upstream version that works for you. There is no background updater.
+
+| What you want | How to choose it |
+|---|---|
+| Stay on a known-good version | `pin` a release tag or full 40-character commit SHA |
+| Try an upstream fix before its release | Set `SUPERPOWERS_REF` to a branch or other resolvable ref for that invocation |
+| Return to the latest stable release | Save `track-latest`, then explicitly install or update |
+
+For example, save a release pin and install it for your agent:
+
+```sh
+npx superpowers-manager pin v6.1.1
+npx superpowers-manager install --harness codex
+```
+
+Use `--harness pi` for Pi. The pin is shared by both agents, but each installation changes only when you run its `install` or `update` command. A saved pin keeps subsequent installs and updates on that version unless you change or override the selection.
+
+To try a branch, replace `feature/foo` with an existing upstream branch:
+
+```sh
+SUPERPOWERS_REF=feature/foo npx superpowers-manager install --harness codex
+```
+
+This override applies only to that command and leaves your saved selection unchanged; the installed version remains until you explicitly change it. Branches can move. Persistent `pin` accepts exact version tags (including prereleases) and full commit SHAs.
+
+When you are ready to return to the latest stable release:
+
+```sh
+npx superpowers-manager track-latest
+npx superpowers-manager update --harness codex
+```
+
+See [version selection](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#choosing-a-source) for source overrides, precedence, and `unpin`.
+
 ## Start with your agent
 
 The two harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
@@ -53,7 +89,7 @@ The manager never removes another Superpowers provider. See the [ownership guida
 
 ## Shared selection and lifecycle
 
-Use `pin`, `track-latest`, or `unpin` to save shared upstream intent. They do not activate Codex or Pi; run the selected harness's `install` or `update` to apply that choice. There is no background updater.
+The [selection commands above](#choose-what-you-run) save shared upstream intent. They do not activate Codex or Pi; run the selected harness's `install` or `update` to apply that choice. `unpin` restores the packaged fallback policy.
 
 | Command | Purpose |
 |---|---|
@@ -65,12 +101,6 @@ Use `pin`, `track-latest`, or `unpin` to save shared upstream intent. They do no
 
 Use `--harness codex` or `--harness pi` with each targeted lifecycle command.
 
-```sh
-npx superpowers-manager pin v6.1.1
-npx superpowers-manager track-latest
-npx superpowers-manager unpin
-```
-
 ```text
 shared selection -> prepare / inspect / activate Codex
                  -> prepare / inspect / activate Pi

package/dist/artifact-tree.js

@@ -4,7 +4,8 @@ import { join } from "node:path";
 import { assertExistingContained, assertNoFollowType, assertSymlinkTargetContained, } from "./safe-path.js";
 import { SafetyError } from "./safety-error.js";
 import { parseStrictJson } from "./strict-json.js";
-import { compareByCodePoint, DEFAULT_FS_DEPS, validateSkillFrontmatter, } from "./generated-plugin.js";
+import { compareByCodePoint } from "./python-text.js";
+import { DEFAULT_FS_DEPS, validateSkillFrontmatter, } from "./skill-validation.js";
 export const ARTIFACT_RECEIPT = ".superpowers-manager.json";
 export const ARTIFACT_DIGEST_RE = /^[a-f0-9]{64}$/;
 const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });

package/dist/cli.js

@@ -2,8 +2,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { extractHarnessOptions, oneLine, UsageError } from "./cli-arguments.js";
-import { codexHarness } from "./codex-harness.js";
-import { piHarness } from "./pi-harness.js";
+import { codexHarness } from "./harnesses/codex/harness.js";
+import { piHarness } from "./harnesses/pi/harness.js";
 import { createResourceCoordinator } from "./resource-lock.js";
 import { runInstall } from "./commands/install.js";
 import { runPin } from "./commands/pin.js";

package/dist/commands/install.js

@@ -1,6 +1,6 @@
 // Ports scripts/install. The shell sourced common.sh, provenance.sh,
 // status.sh, lifecycle.sh and adapter.sh; the predicates now live in
-// src/lifecycle.ts, the generated-metadata read lives in src/provenance.ts,
+// src/harnesses/codex/lifecycle.ts, the generated-metadata read lives in src/provenance.ts,
 // and the adapter arrives through ctx.adapter.
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
@@ -163,7 +163,7 @@ async function gatherInstallStages(ctx, selection, artifact) {
             // is what turns a failed inspection into "error: installed manager
             // fingerprint inspection failed after install."
             // renderInstallVerification's failed-inspection arm
-            // (`src/codex-presentation.ts:332::if (inspection.status !== 0 || !inspection.outcome.ok) {`)
+            // (`src/harnesses/codex/presentation.ts:329::if (inspection.status !== 0 || !inspection.outcome.ok) {`)
             // exists for this result-bearing path; the lifecycle compatibility
             // export delegates through the same arm. Returning
             // failed() instead reported the adapter's own generic diagnostic and

package/dist/commands/prepare.js

@@ -14,7 +14,7 @@ import { runWithMutation } from "./mutation.js";
 // Every message this module writes is hand-written here. The cause is attached
 // for debuggability and never reaches a stream: oneLine (src/cli-arguments.ts)
 // reads .message only. Same arrangement as hookError
-// (`src/hooks.ts:44::function hookError`).
+// (`src/harnesses/codex/hooks.ts:44::function hookError`).
 function prepareError(message, cause) {
     return new SafetyError("prepare", message, { cause });
 }
@@ -341,8 +341,8 @@ async function performPrepare(argv, ctx) {
         // failure (its cause is the shared runner's (src/validator.ts) captured
         // spawn error, which oneLine never reads -- it takes .message only);
         // readManifest's three hookError messages
-        // (`src/hooks.ts:113-138::readManifest`), pinned by
-        // `tests/unit/hooks.test.ts:95::void test("readManifest diagnostics` as carrying no reader vocabulary or
+        // (`src/harnesses/codex/hooks.ts:113-138::readManifest`), pinned by
+        // `tests/unit/harnesses/codex/hooks.test.ts:95::void test("readManifest diagnostics` as carrying no reader vocabulary or
         // errno; and SafetyErrors from gitSafeSource, writeProvenance, and
         // withWorkspace.
         //
@@ -382,7 +382,7 @@ async function performPrepare(argv, ctx) {
         // only, so it bounds how much of that text lands, not what it may
         // contain.
         //
-        // runAdapter's closing `throw cause` (src/adapter.ts) does NOT arrive
+        // runAdapter's closing `throw cause` (src/harnesses/codex/adapter.ts) does NOT arrive
         // here -- the call site catches it and converts it to a hand-written
         // message per AGENTS.md's reader-diagnostics rule.
         //

package/dist/commands/probe.js

@@ -11,7 +11,7 @@ export const PROBE_USAGE = "error: usage: superpowers-manager probe [--porcelain
 // silent diagnostics regression, not a simplification.
 //
 // Interpolating error.message and each hint is the sanctioned form (AGENTS.md):
-// src/adapter.ts has 52 `fail()` sites and none interpolates a caught error's
+// src/harnesses/codex/adapter.ts has 52 `fail()` sites and none interpolates a caught error's
 // message, so the callee owns every failure reachable on this path. Those two
 // writes now live in writeAdapterFailure (src/adapter-result.ts), which
 // validates all three strings before the first of them reaches the stream.
@@ -121,7 +121,7 @@ function validControl(value) {
 // evidence and report it as success.
 //
 // It does still THROW for a non-AdapterFailure cause (runAdapter's closing
-// `throw cause`, src/adapter.ts). That is caught here rather than in runProbe's
+// `throw cause`, src/harnesses/codex/adapter.ts). That is caught here rather than in runProbe's
 // outer catch, because the two need different diagnostics -- see spec §3.3a.
 //
 // Reached through ctx.adapter, not a direct module-level dependency on the
@@ -377,9 +377,9 @@ export async function runProbe(argv, ctx) {
         // which catches every failure and returns "".
         //
         // A non-AdapterFailure re-thrown by runAdapter's closing `throw cause`
-        // (src/adapter.ts) does NOT reach here: inspect() catches it and converts
+        // (src/harnesses/codex/adapter.ts) does NOT reach here: inspect() catches it and converts
         // it to a hand-written message per AGENTS.md's reader-diagnostics rule -- a
-        // rethrown cause is exactly the failure src/adapter.ts declined to own, so
+        // rethrown cause is exactly the failure src/harnesses/codex/adapter.ts declined to own, so
         // its text must never reach this stream. See §3.3a.
         //
         // gatherProbe performs no writes of its own, so this catch cannot also be

package/dist/commands/uninstall.js

@@ -1,5 +1,5 @@
 // Ports scripts/uninstall. The shell sourced common.sh, provenance.sh,
-// lifecycle.sh and adapter.sh; the predicates now live in src/lifecycle.ts
+// lifecycle.sh and adapter.sh; the predicates now live in src/harnesses/codex/lifecycle.ts
 // and the adapter arrives through ctx.adapter.
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
@@ -126,7 +126,7 @@ async function gatherUninstall(ctx) {
         // Reachable only for mkdtemp failure, with nothing collected yet: this
         // callback never throws -- every ctx.adapter throw is already caught
         // inside invoke(), and presenceFlag/verifyUninstalledResources/
-        // reportLegacyState are pure (src/lifecycle.ts's header comment) -- so a
+        // reportLegacyState are pure (src/harnesses/codex/lifecycle.ts's header comment) -- so a
         // post-success cleanup failure is handled by onCleanupFailure above and
         // cannot reach here. Wrapping with `outcomes` anyway keeps the class
         // total over its declared contract rather than assuming the callback's
@@ -163,7 +163,7 @@ async function performUninstall(argv, ctx) {
         // blindly.
         //
         // A cause outside ctx.adapter's AdapterFailure guard
-        // (`src/adapter.ts:973-999::async function runCodexOperation(`) does NOT
+        // (`src/harnesses/codex/adapter.ts:973-999::async function runCodexOperation(`) does NOT
         // reach here: invoke() catches it inside gatherUninstall and converts it
         // to a hand-written message carried as UninstallOutcome data, exactly as
         // src/commands/probe.ts's inspect() does for the same cause.

package/dist/commands/update.js

@@ -1,5 +1,5 @@
 // Ports scripts/update. The shell sourced common.sh and lifecycle.sh; the
-// predicates now live in src/lifecycle.ts. Unlike install and uninstall,
+// predicates now live in src/harnesses/codex/lifecycle.ts. Unlike install and uninstall,
 // update issues no ctx.adapter call of its own: every adapter interaction
 // this module needs already happens inside gatherProbe, runPrepare or
 // runInstall, each of which owns its own §4.2a-conformant invoke() gate. That

package/dist/domain/refs.js

@@ -3,6 +3,10 @@ const SEMVER_BASE_SOURCE = "(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0
     "(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?";
 export const SEMVER_BASE_RE = new RegExp(`^${SEMVER_BASE_SOURCE}$`);
 export const TAG_RE = new RegExp(`^v${SEMVER_BASE_SOURCE}$`);
+// The Python's own SEMVER_RE (:15-22). Deliberately not SEMVER_BASE_SOURCE
+// from this module, which omits the `+build` component; widening the shared
+// constant would change TAG_RE and is out of scope.
+export const SEMVER_RE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 export const COMMIT_RE = /^[0-9a-f]{40}$/;
 export const COMMIT_INPUT_RE = /^[0-9A-Fa-f]{40}$/;
 export function isTagRef(value) {

package/dist/{adapter.js → harnesses/codex/adapter.js}

@@ -4,17 +4,17 @@ import { constants } from "node:fs";
 import { access, copyFile, mkdir, readFile, realpath, stat, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { delimiter, isAbsolute, join } from "node:path";
-import { AdapterMessageLog, failureResult, successResult, } from "./adapter-result.js";
-import { activePluginVersionFromJson, installedListingHas, marketplaceRootFromJson, } from "./codex-json.js";
-import { CODEX_LEGACY_PLUGIN_ID, CODEX_MANAGER_PLUGIN_ID, inspectCodexConflicts, } from "./codex-conflicts.js";
-import { oneLine } from "./cli-arguments.js";
-import { installedCommitFromRoot, installedRootForVersion, pathsEqual, } from "./codex-state.js";
+import { AdapterMessageLog, failureResult, successResult, } from "../../adapter-result.js";
+import { activePluginVersionFromJson, installedListingHas, marketplaceRootFromJson, } from "./json.js";
+import { CODEX_LEGACY_PLUGIN_ID, CODEX_MANAGER_PLUGIN_ID, inspectCodexConflicts, } from "./conflicts.js";
+import { oneLine } from "../../cli-arguments.js";
+import { installedCommitFromRoot, installedRootForVersion, pathsEqual, } from "./state.js";
 import { validateGeneratedPlugin } from "./generated-plugin.js";
 import { classifyHooks, materializeHooks, readManifest, } from "./hooks.js";
 import { applyManifestOverlay } from "./manifest-overlay.js";
-import { readCodexBuildSource } from "./provenance.js";
-import { isAcceptedSplitValue } from "./validate-generated-plugin-cli.js";
-import { withWorkspace, workspaceRemovalFailure } from "./workspace.js";
+import { readCodexBuildSource } from "../../provenance.js";
+import { isAcceptedSplitValue } from "../../validate-generated-plugin-cli.js";
+import { withWorkspace, workspaceRemovalFailure } from "../../workspace.js";
 const PLUGIN_ID = CODEX_MANAGER_PLUGIN_ID;
 const MARKETPLACE_NAME = "superpowers-manager";
 const LEGACY_PLUGIN_ID = CODEX_LEGACY_PLUGIN_ID;
@@ -89,7 +89,7 @@ function runCommand(file, args, env) {
         });
     });
 }
-// Exported only so tests/unit/adapter.test.js can assert the env scrub
+// Exported only so tests/unit/harnesses/codex/adapter.test.ts can assert the env scrub
 // directly. No production caller uses this name.
 export { runCommand as runCommandForTest };
 function commandFailed(result) {
@@ -281,7 +281,7 @@ async function runBuild(input, env, log) {
                 // path — three are the frozen CPython wording, and the fourth (the
                 // numeric-overflow diagnostic, which has no CPython oracle wording
                 // to match) now carries the path via its own rewrap in
-                // src/manifest-overlay.ts. Emit as-is, with no added prefix — a
+                // src/harnesses/codex/manifest-overlay.ts. Emit as-is, with no added prefix — a
                 // prefix here would double up the path these messages already
                 // name.
                 log.appendText("stderr", oneLine(cause));

package/dist/{codex-compatibility.js → harnesses/codex/compatibility.js}

@@ -1,14 +1,14 @@
 import { join } from "node:path";
-import { validateNativeSkill } from "./artifact-tree.js";
-import { classifyPathNoFollow, assertExistingContained } from "./safe-path.js";
+import { validateNativeSkill } from "../../artifact-tree.js";
+import { classifyPathNoFollow, assertExistingContained, } from "../../safe-path.js";
 import { classifyHooks, readManifest } from "./hooks.js";
-import { SEMVER_RE } from "./generated-plugin.js";
-import { validateSource } from "./selection.js";
+import { SEMVER_RE } from "../../domain/refs.js";
+import { validateSource } from "../../selection.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";
+import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, digestArtifactTree, readArtifactObject, } from "../../artifact-tree.js";
+import { COMMIT_RE } from "../../domain/refs.js";
 import { validateGeneratedPlugin } from "./generated-plugin.js";
-import { SafetyError } from "./safety-error.js";
+import { SafetyError } from "../../safety-error.js";
 export async function writeCodexAssessment(root, selection, manifestSource) {
     const receipt = {
         schema: 1,

package/dist/{codex-conflicts.js → harnesses/codex/conflicts.js}

@@ -1,6 +1,6 @@
 import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { codexInstalledPluginsFromJson, } from "./codex-json.js";
+import { codexInstalledPluginsFromJson, } from "./json.js";
 export const CODEX_MANAGER_PLUGIN_ID = "superpowers@superpowers-manager";
 export const CODEX_LEGACY_PLUGIN_ID = "superpowers@superpowers-wrapper";
 const SUPERPOWERS_PLUGIN_PREFIX = "superpowers@";

package/dist/{generated-plugin.js → harnesses/codex/generated-plugin.js}

@@ -1,20 +1,9 @@
-import { lstat, readdir, readFile, readlink, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { posix } from "node:path";
-import { COMMIT_RE } from "./domain/refs.js";
-import { pythonSplitlines, pythonStrip } from "./python-text.js";
-import { parseStrictJson } from "./strict-json.js";
-export const DEFAULT_FS_DEPS = {
-    lstat,
-    stat,
-    readdir,
-    readlink,
-    readFile,
-};
-// The Python's own SEMVER_RE (:15-22). Deliberately not SEMVER_BASE_SOURCE
-// from src/domain/refs.ts, which omits the `+build` component; widening the
-// shared constant would change TAG_RE and is out of scope.
-export const SEMVER_RE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+import { COMMIT_RE, SEMVER_RE } from "../../domain/refs.js";
+import { compareByCodePoint, pythonStrip } from "../../python-text.js";
+import { DEFAULT_FS_DEPS, validateSkillFrontmatter, } from "../../skill-validation.js";
+import { parseStrictJson } from "../../strict-json.js";
 const MANIFEST_JSON_PROFILE = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "reject",
@@ -443,61 +432,6 @@ const REQUIRED_FILES = [
     "README.md",
     "CODE_OF_CONDUCT.md",
 ];
-/** Python `sorted()` orders by code point; JavaScript's default sort does not. */
-export function compareByCodePoint(left, right) {
-    // `Array.from` splits by code point, exactly as spreading would; oxlint's
-    // `no-misused-spread` rejects the spread form, and grapheme segmentation is
-    // the wrong unit here — Python compares code points.
-    const leftPoints = Array.from(left);
-    const rightPoints = Array.from(right);
-    const shared = Math.min(leftPoints.length, rightPoints.length);
-    for (let index = 0; index < shared; index += 1) {
-        const a = leftPoints[index].codePointAt(0);
-        const b = rightPoints[index].codePointAt(0);
-        if (a !== b)
-            return a - b;
-    }
-    return leftPoints.length - rightPoints.length;
-}
-export async function validateSkillFrontmatter(skillMd, skillName, errors, deps) {
-    let contents;
-    try {
-        contents = STRICT_DECODER.decode(await deps.readFile(skillMd));
-    }
-    catch {
-        errors.push(`skill \`${skillName}\` has unreadable UTF-8 \`SKILL.md\``);
-        return;
-    }
-    if (contents === "") {
-        errors.push(`skill \`${skillName}\` has empty \`SKILL.md\``);
-        return;
-    }
-    const lines = pythonSplitlines(contents);
-    if (lines.length === 0 || lines[0] !== "---") {
-        errors.push(`skill \`${skillName}\` must start with \`---\``);
-        return;
-    }
-    const closingIndex = lines.indexOf("---", 1);
-    if (closingIndex === -1) {
-        errors.push(`skill \`${skillName}\` frontmatter is not closed`);
-        return;
-    }
-    const frontmatter = lines.slice(1, closingIndex);
-    for (const key of ["name", "description"]) {
-        const matches = frontmatter.filter((line) => line.startsWith(`${key}:`));
-        if (matches.length !== 1) {
-            errors.push(`skill \`${skillName}\` frontmatter must contain exactly one top-level \`${key}:\``);
-            continue;
-        }
-        const value = pythonStrip(matches[0].slice(matches[0].indexOf(":") + 1));
-        if (value === "" ||
-            value === "''" ||
-            value === '""' ||
-            value.startsWith("#")) {
-            errors.push(`skill \`${skillName}\` frontmatter field \`${key}\` must be non-empty`);
-        }
-    }
-}
 async function validateHookSubtree(pluginRoot, hooksRoot, errors, deps) {
     let resolvedRoot;
     try {
@@ -513,9 +447,9 @@ async function validateHookSubtree(pluginRoot, hooksRoot, errors, deps) {
             isLink = (await inspectLink(path, deps)) === "symlink";
         }
         catch {
-            // The `src/generated-plugin.ts:667::isLink =` probe reaches the first catch bounded by `src/generated-plugin.ts:672-676::let rawTarget`; the `src/generated-plugin.ts:678::rawTarget = decodePathBytes` readlink reaches the same site text.
-            // The three probes sharing the *subtree* string are `src/generated-plugin.ts:711::resolvedDirectory =`, `src/generated-plugin.ts:721::children =`, and
-            // `src/generated-plugin.ts:730::deps, true)) === "directory"`, not this one.
+            // The `src/harnesses/codex/generated-plugin.ts:583::isLink =` probe reaches the first catch bounded by `src/harnesses/codex/generated-plugin.ts:592::let rawTarget`; the `src/harnesses/codex/generated-plugin.ts:594::rawTarget = decodePathBytes` readlink reaches the same site text.
+            // The three probes sharing the *subtree* string are `src/harnesses/codex/generated-plugin.ts:627::resolvedDirectory =`, `src/harnesses/codex/generated-plugin.ts:637::children =`, and
+            // `src/harnesses/codex/generated-plugin.ts:646::deps, true)) === "directory"`, not this one.
             errors.push(`generated hook symlink could not be inspected: ${path}`);
             return false;
         }

package/dist/{codex-harness.js → harnesses/codex/harness.js}

@@ -1,11 +1,11 @@
 import { join, resolve } from "node:path";
-import { failureResult, hasTerminalControl, successResult, } from "./adapter-result.js";
+import { failureResult, hasTerminalControl, successResult, } from "../../adapter-result.js";
 import { codexInspect, codexInstall, codexRemove, } from "./adapter.js";
-import { codexPreparationLocation, inspectCodexPrepared, prepareCodexCandidate, readCodexPrepared, validateCodexPreparationBeforeFetch, } from "./codex-prepare.js";
-import { codexInstallReceipt, codexPresentation, } from "./codex-presentation.js";
+import { codexPreparationLocation, inspectCodexPrepared, prepareCodexCandidate, readCodexPrepared, validateCodexPreparationBeforeFetch, } from "./prepare.js";
+import { codexInstallReceipt, codexPresentation } from "./presentation.js";
 import { reportLegacyState, requireManagedUpdateControl, requireNoLegacyState, verifyUninstalledResources, } from "./lifecycle.js";
-import { SafetyError } from "./safety-error.js";
-import { commitMatches } from "./status.js";
+import { SafetyError } from "../../safety-error.js";
+import { commitMatches } from "../../status.js";
 function preserveFailure(result) {
     if (result.outcome.ok) {
         throw new Error("cannot preserve a successful adapter result as failure");

package/dist/{hooks.js → harnesses/codex/hooks.js}

@@ -1,8 +1,8 @@
 import { copyFile, cp, mkdir, readdir, readFile, readlink, stat, symlink, } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { assertExistingContained, assertProspectiveContained, classifyPathNoFollow, } from "./safe-path.js";
-import { SafetyError } from "./safety-error.js";
-import { parseStrictJson } from "./strict-json.js";
+import { assertExistingContained, assertProspectiveContained, classifyPathNoFollow, } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { parseStrictJson } from "../../strict-json.js";
 // Annotated, not `as const`, matching
 // `src/provenance.ts:20::export const PROVENANCE_STRICT_PROFILE` and
 // `src/selection-store.ts:19::const SELECTION_JSON_PROFILE`. The annotation
@@ -77,11 +77,11 @@ export async function readManifest(path) {
     catch {
         // Deliberately drops the cause on both branches. `detail(cause)` on the
         // read branch surfaced a raw errno (`ENOENT: … open '<path>'`), which the
-        // `hook classification failed:` site in src/adapter.ts re-emits onto the
+        // `hook classification failed:` site in src/harnesses/codex/adapter.ts re-emits onto the
         // terminal these commands write to; the parse branch surfaced
-        // strict-json's own wording under a prefix src/manifest-overlay.ts also
+        // strict-json's own wording under a prefix src/harnesses/codex/manifest-overlay.ts also
         // uses with CPython wording.
-        // Same text as the `cannot read manifest JSON in` site in src/adapter.ts.
+        // Same text as the `cannot read manifest JSON in` site in src/harnesses/codex/adapter.ts.
         throw hookError(`cannot read manifest JSON in ${path}`);
     }
     let parsed;

package/dist/{codex-json.js → harnesses/codex/json.js}

@@ -1,5 +1,5 @@
-import { SafetyError } from "./safety-error.js";
-import { parseStrictJson, } from "./strict-json.js";
+import { SafetyError } from "../../safety-error.js";
+import { parseStrictJson, } from "../../strict-json.js";
 const ACCEPT_CONSTANTS = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "accept",

package/dist/{lifecycle.js → harnesses/codex/lifecycle.js}

@@ -52,7 +52,7 @@ export function reportLegacyState(identityState) {
     }
     return unknownState(identityState);
 }
-export { verifyInstalledFingerprint, } from "./codex-presentation.js";
+export { verifyInstalledFingerprint, } from "./presentation.js";
 // Ported from
 // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:62-70::spw_require_managed_update_control`.
 // Both refusals reached spw_die in the shell, so both carry the `error: ` prefix
@@ -101,7 +101,7 @@ export function verifyUninstalledResources(inspectResult) {
     // rather than getting its own message.
     // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:70::expected`
     // emits "expected Boolean adapter result at resources.plugin" for input {} —
-    // the input tests/unit/lifecycle.test.js's "a non-object resources falls
+    // the input tests/unit/harnesses/codex/lifecycle.test.ts's "a non-object resources falls
     // through to the Boolean message" exercises — so a distinct "not an object"
     // message here would be a port-only divergence. Parity, not divergence. Spec
     // §6.2.3 item 3.

package/dist/{manifest-overlay.js → harnesses/codex/manifest-overlay.js}

@@ -1,6 +1,6 @@
-import { escapeNonAscii, formatPythonNumber } from "./python-json-format.js";
-import { SafetyError } from "./safety-error.js";
-import { isRawNumber, isRawObject, parseStrictJsonPreservingNumbers, } from "./strict-json.js";
+import { escapeNonAscii, formatPythonNumber, } from "../../python-json-format.js";
+import { SafetyError } from "../../safety-error.js";
+import { isRawNumber, isRawObject, parseStrictJsonPreservingNumbers, } from "../../strict-json.js";
 const OVERLAY_PROFILE = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "reject",
@@ -12,7 +12,7 @@ const OVERLAY_PROFILE = {
  * Byte-for-byte equivalent to the CPython implementation this replaces:
  * `json.dump(data, f, indent=2, allow_nan=False)` plus a trailing newline.
  * The byte-parity evidence lives in
- * `tests/baseline/manifest-overlay-parity.test.js` (tracked as
+ * `tests/baseline/harnesses/codex/manifest-overlay-parity.test.ts` (tracked as
  * `MANIFEST-READER-OVERLAY-01` in `docs/baseline/traceability.md`) against
  * the fixtures under `tests/fixtures/baseline/overlay-parity/`. Known,
  * deliberate divergences from strict byte parity are recorded in

package/dist/{codex-prepare.js → harnesses/codex/prepare.js}

@@ -1,14 +1,14 @@
 import { cp, mkdir, rm, stat } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
-import { failureResult, successResult, } from "./adapter-result.js";
+import { failureResult, successResult, } from "../../adapter-result.js";
 import { codexBuild } from "./adapter.js";
-import { ARTIFACT_RECEIPT } from "./artifact-tree.js";
-import { assessCodexCompatibility, readCodexAssessment, writeCodexAssessment, } from "./codex-compatibility.js";
+import { ARTIFACT_RECEIPT } from "../../artifact-tree.js";
+import { assessCodexCompatibility, readCodexAssessment, writeCodexAssessment, } from "./compatibility.js";
 import { readManifest } from "./hooks.js";
-import { readGeneratedCommitLenient, readStrictProvenanceField, writeProvenance, } from "./provenance.js";
-import { classifyPathNoFollow } from "./safe-path.js";
-import { SafetyError } from "./safety-error.js";
-import { manifestVersionForRef } from "./upstream-version.js";
+import { readGeneratedCommitLenient, readStrictProvenanceField, writeProvenance, } from "../../provenance.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { manifestVersionForRef } from "../../upstream-version.js";
 // Order is inherited from the original prepare command; the first miss wins.
 const REQUIRED_UPSTREAM = [
     { path: "skills", label: "skills/" },

package/dist/{codex-presentation.js → harnesses/codex/presentation.js}

@@ -1,5 +1,5 @@
-import { normalizeCodexInstall, normalizeCodexInstalled, } from "./codex-harness.js";
-import { displaySource } from "./selection.js";
+import { normalizeCodexInstall, normalizeCodexInstalled } from "./harness.js";
+import { displaySource } from "../../selection.js";
 // One ordered table drives both formats, preserving the public human and
 // porcelain field order exposed through the harness presentation.
 export function fields(f) {
@@ -116,7 +116,7 @@ export function codexInstallReceipt(missingHint, mismatchHint) {
         mismatchVerificationOutput: verificationOutput("mismatch", mismatchHint),
     };
 }
-// Compatibility export target for src/lifecycle.ts. Delegate to the production
+// Compatibility export target for src/harnesses/codex/lifecycle.ts. Delegate to the production
 // normalizers and renderer so the retained verdict cannot drift from commands.
 export function verifyInstalledFingerprint(desiredCommit, installResult, inspectResult) {
     const receipt = normalizeCodexInstall(installResult);

package/dist/{codex-state.js → harnesses/codex/state.js}

@@ -1,8 +1,8 @@
 import { readFile, realpath } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { COMMIT_INPUT_RE } from "./domain/refs.js";
-import { SafetyError } from "./safety-error.js";
-import { parseStrictJson, } from "./strict-json.js";
+import { COMMIT_INPUT_RE } from "../../domain/refs.js";
+import { SafetyError } from "../../safety-error.js";
+import { parseStrictJson, } from "../../strict-json.js";
 const INSTALLED_PROFILE = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "reject",

package/dist/{pi-compatibility.js → harnesses/pi/compatibility.js}

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { lstat } from "node:fs/promises";
 import { join } from "node:path";
-import { readArtifactFile, readArtifactObject, validateNativeSkill, } from "./artifact-tree.js";
-import { SEMVER_RE } from "./generated-plugin.js";
-import { validateSource } from "./selection.js";
+import { readArtifactFile, readArtifactObject, validateNativeSkill, } from "../../artifact-tree.js";
+import { SEMVER_RE } from "../../domain/refs.js";
+import { validateSource } from "../../selection.js";
 const OFFICIAL_SOURCES = new Set([
     "https://github.com/obra/superpowers",
     "https://github.com/obra/superpowers.git",

package/dist/{pi-harness.js → harnesses/pi/harness.js}

@@ -1,10 +1,10 @@
-import { failureResult, successResult } from "./adapter-result.js";
-import { classifyPathNoFollow } from "./safe-path.js";
-import { installPi, removePi } from "./pi-install.js";
-import { piPaths } from "./pi-paths.js";
-import { inspectPiPrepared, piPreparationLocation, preparePiCandidate, readPiPrepared, } from "./pi-prepare.js";
-import { piPresentation } from "./pi-presentation.js";
-import { inspectPiControl, inspectPiInstalled, inspectPiOwnership, } from "./pi-state.js";
+import { failureResult, successResult } from "../../adapter-result.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
+import { installPi, removePi } from "./install.js";
+import { piPaths } from "./paths.js";
+import { inspectPiPrepared, piPreparationLocation, preparePiCandidate, readPiPrepared, } from "./prepare.js";
+import { piPresentation } from "./presentation.js";
+import { inspectPiControl, inspectPiInstalled, inspectPiOwnership, } from "./state.js";
 export const piHarness = {
     preparationLocation: piPreparationLocation,
     mutationRoots: async (ctx) => [

package/dist/{pi-install.js → harnesses/pi/install.js}

@@ -1,14 +1,14 @@
 import { randomBytes } from "node:crypto";
 import { cp, lstat, mkdir, open, readFile, readdir, rm, rmdir, unlink, } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { failureResult, successResult, } from "./adapter-result.js";
-import { atomicWriteFile, beginDirectoryPublication, } from "./atomic.js";
-import { normalizePiRuntimeVersion, runPi } from "./pi-native.js";
-import { digestPiTree, readPiPackageAssessment, readPiReceipt, } from "./pi-package.js";
-import { piPaths } from "./pi-paths.js";
-import { readPiSettings, resolveCanonicalPiLocalSource, } from "./pi-settings.js";
-import { inspectPiControl, inspectPiOwnership, } from "./pi-state.js";
-import { assertNoFollowType, canonicalizeProspectivePath, classifyPathNoFollow, } from "./safe-path.js";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { atomicWriteFile, beginDirectoryPublication, } from "../../atomic.js";
+import { normalizePiRuntimeVersion, runPi } from "./native.js";
+import { digestPiTree, readPiPackageAssessment, readPiReceipt, } from "./package.js";
+import { piPaths } from "./paths.js";
+import { readPiSettings, resolveCanonicalPiLocalSource, } from "./settings.js";
+import { inspectPiControl, inspectPiOwnership, } from "./state.js";
+import { assertNoFollowType, canonicalizeProspectivePath, classifyPathNoFollow, } from "../../safe-path.js";
 const DEFAULTS = {
     run: runPi,
     beginPublication: beginDirectoryPublication,

package/dist/{pi-native.js → harnesses/pi/native.js}

@@ -1,9 +1,9 @@
 import { tmpdir } from "node:os";
 import { isAbsolute, resolve, sep } from "node:path";
-import { AdapterMessageLog, failureResult, successResult, } from "./adapter-result.js";
-import { SEMVER_RE } from "./generated-plugin.js";
-import { BOUNDED_EXECUTABLE, runValidator as runBoundedCommand, } from "./validator.js";
-import { withWorkspace } from "./workspace.js";
+import { AdapterMessageLog, failureResult, successResult, } from "../../adapter-result.js";
+import { SEMVER_RE } from "../../domain/refs.js";
+import { BOUNDED_EXECUTABLE, runValidator as runBoundedCommand, } from "../../validator.js";
+import { withWorkspace } from "../../workspace.js";
 function selectedExecutable(env, invocationCwd) {
     const configured = env.SUPERPOWERS_PI || "pi";
     return configured.includes(sep) && !isAbsolute(configured)

package/dist/{pi-package.js → harnesses/pi/package.js}

@@ -3,12 +3,12 @@ import { createHash } from "node:crypto";
 import { chmod, mkdir, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
-import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, addArtifactHashField, digestArtifactTree, readArtifactObject, } from "./artifact-tree.js";
-import { COMMIT_RE } from "./domain/refs.js";
-import { assertNoFollowType, assertSymlinkTargetContained, } from "./safe-path.js";
-import { SafetyError } from "./safety-error.js";
-import { validateSource } from "./selection.js";
-import { assessPiCompatibility } from "./pi-compatibility.js";
+import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, addArtifactHashField, digestArtifactTree, readArtifactObject, } from "../../artifact-tree.js";
+import { COMMIT_RE } from "../../domain/refs.js";
+import { assertNoFollowType, assertSymlinkTargetContained, } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { validateSource } from "../../selection.js";
+import { assessPiCompatibility } from "./compatibility.js";
 const exec = promisify(execFile);
 const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
 // A consistency checksum, not authentication. A coherent manual rewrite of

package/dist/{pi-prepare.js → harnesses/pi/prepare.js}

@@ -1,11 +1,11 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { failureResult, successResult, } from "./adapter-result.js";
-import { ARTIFACT_RECEIPT } from "./artifact-tree.js";
-import { piPaths } from "./pi-paths.js";
-import { assessPiCompatibility, samePiSource } from "./pi-compatibility.js";
-import { digestPiTree, materializePiTree, readPiPackageAssessment, piReceiptBinding, } from "./pi-package.js";
-import { classifyPathNoFollow } from "./safe-path.js";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { ARTIFACT_RECEIPT } from "../../artifact-tree.js";
+import { piPaths } from "./paths.js";
+import { assessPiCompatibility, samePiSource } from "./compatibility.js";
+import { digestPiTree, materializePiTree, readPiPackageAssessment, piReceiptBinding, } from "./package.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
 export function piPreparationLocation(ctx) {
     return {
         destinationRoot: piPaths(ctx.env ?? {}, process.cwd()).preparedRoot,

package/dist/{pi-settings.js → harnesses/pi/settings.js}

@@ -1,9 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { canonicalizeProspectivePath } from "./safe-path.js";
-import { SafetyError } from "./safety-error.js";
-import { parseStrictJson, } from "./strict-json.js";
+import { canonicalizeProspectivePath } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { parseStrictJson, } from "../../strict-json.js";
 const SETTINGS_PROFILE = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "reject",

package/dist/{pi-shared-skills.js → harnesses/pi/shared-skills.js}

@@ -1,7 +1,7 @@
 import { readdir, readFile, readlink, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
 import { fileURLToPath } from "node:url";
-import { classifyPathNoFollow } from "./safe-path.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
 const PI_IGNORE_FILES = [".gitignore", ".ignore", ".fdignore"];
 function toPosixPath(path) {
     return path.split(sep).join("/");

package/dist/{pi-state.js → harnesses/pi/state.js}

@@ -1,12 +1,12 @@
 import { join } from "node:path";
-import { sharedPiSkillsActivity } from "./pi-shared-skills.js";
-import { failureResult, successResult, } from "./adapter-result.js";
-import { readArtifactObject } from "./artifact-tree.js";
-import { samePiSource } from "./pi-compatibility.js";
-import { digestPiTree, readPiPackageAssessment, readPiReceipt, } from "./pi-package.js";
-import { piPaths } from "./pi-paths.js";
-import { readPiSettings, resolveCanonicalPiLocalSource, resolvePiLocalSource, } from "./pi-settings.js";
-import { classifyPathNoFollow } from "./safe-path.js";
+import { sharedPiSkillsActivity } from "./shared-skills.js";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { readArtifactObject } from "../../artifact-tree.js";
+import { samePiSource } from "./compatibility.js";
+import { digestPiTree, readPiPackageAssessment, readPiReceipt, } from "./package.js";
+import { piPaths } from "./paths.js";
+import { readPiSettings, resolveCanonicalPiLocalSource, resolvePiLocalSource, } from "./settings.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
 // Verified remote spellings only: Pi 0.85.1 accepts http:// as Git. Unprefixed
 // github: and git+ forms stay local; git:-wrapped aliases and explicit transports
 // normalize only an exact GitHub authority and repository path (native source

package/dist/python-text.js

@@ -72,3 +72,19 @@ export function pythonSplitlines(value) {
         lines.push(value.slice(start));
     return lines;
 }
+/** Python `sorted()` orders by code point; JavaScript's default sort does not. */
+export function compareByCodePoint(left, right) {
+    // `Array.from` splits by code point, exactly as spreading would; oxlint's
+    // `no-misused-spread` rejects the spread form, and grapheme segmentation is
+    // the wrong unit here — Python compares code points.
+    const leftPoints = Array.from(left);
+    const rightPoints = Array.from(right);
+    const shared = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < shared; index += 1) {
+        const a = leftPoints[index].codePointAt(0);
+        const b = rightPoints[index].codePointAt(0);
+        if (a !== b)
+            return a - b;
+    }
+    return leftPoints.length - rightPoints.length;
+}

package/dist/skill-validation.js

@@ -0,0 +1,52 @@
+import { lstat, readdir, readFile, readlink, stat } from "node:fs/promises";
+import { pythonSplitlines, pythonStrip } from "./python-text.js";
+export const DEFAULT_FS_DEPS = {
+    lstat,
+    stat,
+    readdir,
+    readlink,
+    readFile,
+};
+const STRICT_DECODER = new TextDecoder("utf-8", {
+    fatal: true,
+    ignoreBOM: true,
+});
+export async function validateSkillFrontmatter(skillMd, skillName, errors, deps) {
+    let contents;
+    try {
+        contents = STRICT_DECODER.decode(await deps.readFile(skillMd));
+    }
+    catch {
+        errors.push(`skill \`${skillName}\` has unreadable UTF-8 \`SKILL.md\``);
+        return;
+    }
+    if (contents === "") {
+        errors.push(`skill \`${skillName}\` has empty \`SKILL.md\``);
+        return;
+    }
+    const lines = pythonSplitlines(contents);
+    if (lines.length === 0 || lines[0] !== "---") {
+        errors.push(`skill \`${skillName}\` must start with \`---\``);
+        return;
+    }
+    const closingIndex = lines.indexOf("---", 1);
+    if (closingIndex === -1) {
+        errors.push(`skill \`${skillName}\` frontmatter is not closed`);
+        return;
+    }
+    const frontmatter = lines.slice(1, closingIndex);
+    for (const key of ["name", "description"]) {
+        const matches = frontmatter.filter((line) => line.startsWith(`${key}:`));
+        if (matches.length !== 1) {
+            errors.push(`skill \`${skillName}\` frontmatter must contain exactly one top-level \`${key}:\``);
+            continue;
+        }
+        const value = pythonStrip(matches[0].slice(matches[0].indexOf(":") + 1));
+        if (value === "" ||
+            value === "''" ||
+            value === '""' ||
+            value.startsWith("#")) {
+            errors.push(`skill \`${skillName}\` frontmatter field \`${key}\` must be non-empty`);
+        }
+    }
+}

package/dist/validate-generated-plugin-cli.js

@@ -1,6 +1,6 @@
 import { realpathSync } from "node:fs";
 import { oneLine, parseFlags, UsageError } from "./cli-arguments.js";
-import { validateGeneratedPlugin, } from "./generated-plugin.js";
+import { validateGeneratedPlugin, } from "./harnesses/codex/generated-plugin.js";
 const FLAGS = [
     "plugin-root",
     "source",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-manager",
-  "version": "0.5.0",
-  "description": "Install and update the latest stable obra/superpowers release directly from upstream for Codex and Pi (pi-coding-agent), without waiting for agent marketplaces to catch up.",
+  "version": "0.5.1",
+  "description": "Install obra/superpowers directly from upstream for Codex and Pi. Stay on a known-good release or commit, try a branch, and upgrade when you choose.",
   "keywords": [
     "superpowers",
     "obra-superpowers",
@@ -16,7 +16,8 @@
     "installer",
     "updater",
     "pi",
-    "pi-coding-agent"
+    "pi-coding-agent",
+    "version-pinning"
   ],
   "license": "MIT",
   "type": "module",