superpowers-manager 0.4.0 → 0.5.1

package/dist/harnesses/codex/compatibility.js

@@ -0,0 +1,126 @@
+import { join } from "node:path";
+import { validateNativeSkill } from "../../artifact-tree.js";
+import { classifyPathNoFollow, assertExistingContained, } from "../../safe-path.js";
+import { classifyHooks, readManifest } from "./hooks.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 { validateGeneratedPlugin } from "./generated-plugin.js";
+import { SafetyError } from "../../safety-error.js";
+export async function writeCodexAssessment(root, selection, manifestSource) {
+    const receipt = {
+        schema: 1,
+        manager: "superpowers-manager",
+        harness: "codex",
+        source: selection.effectiveSource,
+        commit: selection.desiredCommit,
+        generation: "codex-native-skills-v1",
+        manifestSource,
+        digest: await digestArtifactTree(root),
+    };
+    await writeFile(join(root, ARTIFACT_RECEIPT), JSON.stringify(receipt) + "\n", { flag: "wx" });
+}
+export async function readCodexAssessment(root) {
+    try {
+        const receipt = await readArtifactObject(root, join(root, ARTIFACT_RECEIPT));
+        const provenance = await readArtifactObject(root, join(root, ".superpowers-upstream.json"));
+        if (receipt.schema !== 1 ||
+            receipt.manager !== "superpowers-manager" ||
+            receipt.harness !== "codex" ||
+            receipt.generation !== "codex-native-skills-v1" ||
+            typeof receipt.source !== "string" ||
+            typeof receipt.commit !== "string" ||
+            !COMMIT_RE.test(receipt.commit) ||
+            typeof receipt.digest !== "string" ||
+            !ARTIFACT_DIGEST_RE.test(receipt.digest) ||
+            (receipt.manifestSource !== "upstream" &&
+                receipt.manifestSource !== "fallback") ||
+            receipt.source !== provenance.source ||
+            receipt.commit !== provenance.commit)
+            throw new Error("assessment fields");
+        validateSource(receipt.source);
+        if ((await digestArtifactTree(root)) !== receipt.digest)
+            throw new Error("assessment digest");
+        const manifest = await readManifest(join(root, ".codex-plugin/plugin.json"));
+        if (typeof manifest.version !== "string" ||
+            typeof provenance.requested_ref !== "string" ||
+            typeof provenance.resolved_ref !== "string" ||
+            typeof provenance.upstream_manifest_version !== "string")
+            throw new Error("provenance fields");
+        const errors = await validateGeneratedPlugin({
+            pluginRoot: root,
+            source: receipt.source,
+            commit: receipt.commit,
+            requestedRef: provenance.requested_ref,
+            resolvedRef: provenance.resolved_ref,
+            upstreamManifestVersion: provenance.upstream_manifest_version,
+            manifestVersion: manifest.version,
+            manifestSource: receipt.manifestSource,
+        });
+        if (errors.length)
+            throw new Error("generated resources");
+        const selection = {
+            effectiveSource: receipt.source,
+            desiredCommit: receipt.commit,
+            requestedRef: provenance.requested_ref,
+            resolvedRef: provenance.resolved_ref,
+            resolutionKind: "raw-commit",
+            selectionOrigin: "package-default",
+            selectionMode: "default",
+            upstreamSourceOrigin: "package-default",
+            saved: {
+                saved_mode: "none",
+                saved_source: "",
+                saved_requested_ref: "",
+                saved_resolved_ref: "",
+                saved_commit: "",
+            },
+        };
+        const compatibility = await assessCodexCompatibility(root, selection);
+        return {
+            root,
+            commit: receipt.commit,
+            identity: receipt.commit,
+            compatibility,
+        };
+    }
+    catch (cause) {
+        throw new SafetyError("codex-compatibility", `invalid Codex prepared assessment: ${root}`, { cause });
+    }
+}
+export async function assessCodexCompatibility(root, selection) {
+    try {
+        validateSource(selection.effectiveSource);
+        await validateNativeSkill(root);
+        for (const path of [
+            ".codex/superpowers-codex",
+            ".codex/superpowers-bootstrap.md",
+        ]) {
+            if ((await classifyPathNoFollow(join(root, path))) !== "missing")
+                throw new Error("legacy bootstrap");
+        }
+        const path = join(root, ".codex-plugin/plugin.json");
+        if ((await classifyPathNoFollow(path)) !== "missing") {
+            await assertExistingContained(root, path);
+            const manifest = await readManifest(path);
+            if (manifest.name !== "superpowers" ||
+                typeof manifest.version !== "string" ||
+                !SEMVER_RE.test(manifest.version))
+                throw new Error("manifest");
+            await classifyHooks(manifest, "upstream", root);
+        }
+        return {
+            kind: "supported",
+            generation: "codex-native-skills-v1",
+            reason: "native Codex skill discovery",
+        };
+    }
+    catch {
+        return {
+            kind: "unsupported",
+            reason: `Codex package does not provide compatible native skill discovery: ${root}`,
+        };
+    }
+}

package/dist/harnesses/codex/conflicts.js

@@ -0,0 +1,99 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+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@";
+const DISPLAYABLE_PLUGIN_ID = /^superpowers@[A-Za-z0-9][A-Za-z0-9._-]*/;
+const NATIVE_ROUTE = ".agents/skills/superpowers";
+const NATIVE_ROUTE_CONFLICT = `native Codex skills route ~/${NATIVE_ROUTE} has indeterminate activity`;
+function isMissingPath(cause) {
+    if (cause === null || typeof cause !== "object" || !("code" in cause)) {
+        return false;
+    }
+    return cause.code === "ENOENT" || cause.code === "ENOTDIR";
+}
+function isUnmanagedPluginId(pluginId) {
+    if (pluginId === CODEX_MANAGER_PLUGIN_ID ||
+        pluginId === CODEX_LEGACY_PLUGIN_ID) {
+        return false;
+    }
+    return (pluginId.startsWith(SUPERPOWERS_PLUGIN_PREFIX) &&
+        pluginId.length > SUPERPOWERS_PLUGIN_PREFIX.length);
+}
+function displayablePluginId(pluginId) {
+    return pluginId.length <= 256 &&
+        DISPLAYABLE_PLUGIN_ID.exec(pluginId)?.[0] === pluginId
+        ? pluginId
+        : "";
+}
+function unmanagedPluginConflict(plugin) {
+    if (!isUnmanagedPluginId(plugin.pluginId))
+        return "";
+    const displayId = displayablePluginId(plugin.pluginId);
+    const subject = displayId.length > 0
+        ? `Codex plugin ${displayId}`
+        : "Codex plugin with a non-displayable Superpowers identity";
+    if (plugin.installed === true && plugin.enabled === true) {
+        return `active ${subject}`;
+    }
+    if ((plugin.installed === true && plugin.enabled === false) ||
+        (plugin.installed === false && plugin.enabled === false)) {
+        return "";
+    }
+    return `${subject} has indeterminate activity`;
+}
+async function nativeRouteConflict(ctx) {
+    const home = ctx.env?.HOME;
+    if (home === undefined || home.length === 0)
+        return NATIVE_ROUTE_CONFLICT;
+    const route = join(home, ".agents", "skills", "superpowers");
+    const asset = join(route, "using-superpowers", "SKILL.md");
+    let routeIsSymlink;
+    try {
+        routeIsSymlink = (await lstat(route)).isSymbolicLink();
+    }
+    catch (cause) {
+        return isMissingPath(cause) ? "" : NATIVE_ROUTE_CONFLICT;
+    }
+    if (!routeIsSymlink) {
+        try {
+            await lstat(asset);
+        }
+        catch (cause) {
+            return isMissingPath(cause) ? "" : NATIVE_ROUTE_CONFLICT;
+        }
+    }
+    try {
+        const resolvedAsset = await realpath(asset);
+        if (!(await stat(resolvedAsset)).isFile())
+            return NATIVE_ROUTE_CONFLICT;
+        const contents = await readFile(resolvedAsset, "utf8");
+        const lines = contents.split(/\r?\n/u);
+        if (lines[0] !== "---")
+            return "";
+        const end = lines.indexOf("---", 1);
+        if (end < 0 ||
+            !lines
+                .slice(1, end)
+                .some((line) => /^name:[ \t]+using-superpowers[ \t]*$/u.test(line))) {
+            return "";
+        }
+    }
+    catch {
+        return NATIVE_ROUTE_CONFLICT;
+    }
+    return NATIVE_ROUTE_CONFLICT;
+}
+export async function inspectCodexConflicts(ctx, installedListing) {
+    const conflicts = new Set();
+    for (const plugin of codexInstalledPluginsFromJson(installedListing)) {
+        const conflict = unmanagedPluginConflict(plugin);
+        if (conflict.length > 0)
+            conflicts.add(conflict);
+    }
+    const nativeConflict = await nativeRouteConflict(ctx);
+    if (nativeConflict.length > 0)
+        conflicts.add(nativeConflict);
+    return [...conflicts];
+}

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.
-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. */
-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;
-}
-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,9 +1,11 @@
-import { failureResult, hasTerminalControl, successResult, } from "./adapter-result.js";
+import { join, resolve } from "node:path";
+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 { 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");
@@ -40,6 +42,23 @@ function resourceFlag(result, key) {
     const value = bag[key];
     return typeof value === "boolean" ? value : null;
 }
+function conflictDescriptions(result) {
+    const raw = result.conflicts;
+    if (raw === null || raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return null;
+    const descriptions = [];
+    for (const item of raw) {
+        if (typeof item !== "string" ||
+            item.length === 0 ||
+            hasTerminalControl(item)) {
+            return null;
+        }
+        descriptions.push(item);
+    }
+    return descriptions;
+}
 function installDecision(legacy) {
     switch (legacy.kind) {
         case "ok":
@@ -87,7 +106,11 @@ export function normalizeCodexOwnership(result) {
         return malformed(result, "adapter returned a non-string identity_state for inspect --view ownership");
     }
     const identityState = identity.value;
-    const installEligibility = identityState.length === 0
+    const conflicts = conflictDescriptions(record);
+    if (conflicts === null) {
+        return malformed(result, "expected an array of strings at conflicts");
+    }
+    const legacyEligibility = identityState.length === 0
         ? {
             kind: "blocked",
             output: {
@@ -96,6 +119,19 @@ export function normalizeCodexOwnership(result) {
             },
         }
         : installDecision(requireNoLegacyState(identityState));
+    const installEligibility = legacyEligibility.kind === "blocked" || conflicts.length === 0
+        ? legacyEligibility
+        : {
+            kind: "blocked",
+            output: {
+                stdout: [],
+                stderr: [
+                    "Conflicting unmanaged Superpowers Codex resources require manual resolution:",
+                    ...conflicts.map((conflict) => `- ${conflict}`),
+                    "Remove or disable each resource manually, then retry.",
+                ],
+            },
+        };
     const verification = verifyUninstalledResources(result);
     const legacyReport = reportLegacyState(identityState);
     let removalVerification;
@@ -132,6 +168,7 @@ export function normalizeCodexOwnership(result) {
         removalVerification,
         postRemovalOutput,
         presentationValue: identityState,
+        presentationConflicts: conflicts,
     }, result.outcome.messages);
 }
 export function normalizeCodexControl(result) {
@@ -243,8 +280,21 @@ function requirements(command, env) {
         },
     ];
 }
+async function mutationRoots(ctx) {
+    const env = ctx.env ?? {};
+    const configured = env.CODEX_HOME;
+    if (configured !== undefined && configured.length > 0) {
+        return [resolve(configured)];
+    }
+    const home = env.HOME;
+    if (home === undefined || home.length === 0) {
+        throw new SafetyError("codex-harness", "cannot determine Codex state root without HOME");
+    }
+    return [join(resolve(home), ".codex")];
+}
 export const codexHarness = {
     preparationLocation: codexPreparationLocation,
+    mutationRoots,
     validatePreparationBeforeFetch: validateCodexPreparationBeforeFetch,
     prepareCandidate: prepareCodexCandidate,
     inspectPrepared: inspectCodexPrepared,

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",
@@ -59,6 +59,13 @@ function hasTerminalControl(value) {
 export function installedListingHas(raw, arrayKey, field, value) {
     return checkedItems(raw, ACCEPT_CONSTANTS, arrayKey, field).some((item) => item[field] === value);
 }
+export function codexInstalledPluginsFromJson(raw) {
+    return checkedItems(raw, ACCEPT_CONSTANTS, "installed", "pluginId").map((item) => ({
+        pluginId: item.pluginId,
+        installed: typeof item.installed === "boolean" ? item.installed : null,
+        enabled: typeof item.enabled === "boolean" ? item.enabled : null,
+    }));
+}
 export function marketplaceRootFromJson(raw, marketplaceName) {
     const items = checkedItems(raw, ACCEPT_CONSTANTS, "marketplaces", "name");
     const match = items.find((item) => item.name === marketplaceName);

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
@@ -69,7 +69,7 @@ function setMember(entries, key, value) {
 }
 /**
  * Map strict-json's diagnostics onto the CPython wording the callers assert.
- * Repository policy at `AGENTS.md:91::most diagnostics are asserted as`
+ * Repository policy at `AGENTS.md:92::most diagnostics are asserted as`
  * freezes most of these diagnostics as complete-string contracts.
  */
 function translate(cause, source, path) {

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

@@ -1,12 +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 { commitMatches } from "./domain/fingerprint.js";
+import { ARTIFACT_RECEIPT } from "../../artifact-tree.js";
+import { assessCodexCompatibility, readCodexAssessment, writeCodexAssessment, } from "./compatibility.js";
 import { readManifest } from "./hooks.js";
-import { generatedCommitOrEmpty, generatedMetadataPath, readStrictProvenanceField, writeProvenance, } from "./provenance.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/" },
@@ -27,6 +29,12 @@ const RESOLUTION_KINDS = [
     "ref",
     "raw-commit",
 ];
+function unassessedCompatibility() {
+    return {
+        kind: "unknown",
+        reason: "Codex compatibility assessment is not available",
+    };
+}
 function prepareError(message, cause) {
     return new SafetyError("prepare", message, { cause });
 }
@@ -166,26 +174,66 @@ export async function prepareCodexCandidate(input, ctx) {
     if (built.status !== 0) {
         return failureResult("build", "invalid-status", "adapter reported failure without an error outcome", [], built.outcome.messages);
     }
-    return successResult(built.outcome.operation, { root: input.candidateRoot, commit: input.selection.desiredCommit }, built.outcome.messages);
+    const compatibility = await assessCodexCompatibility(input.upstreamRoot, input.selection);
+    if (compatibility.kind === "supported") {
+        try {
+            await writeCodexAssessment(input.candidateRoot, input.selection, (await regularFileExists(join(input.upstreamRoot, ".codex-plugin/plugin.json")))
+                ? "upstream"
+                : "fallback");
+        }
+        catch {
+            return failureResult("prepare", "assessment-failed", `cannot record Codex compatibility assessment: ${input.candidateRoot}`, [], built.outcome.messages);
+        }
+    }
+    return successResult(built.outcome.operation, {
+        root: input.candidateRoot,
+        commit: input.selection.desiredCommit,
+        compatibility,
+        identity: input.selection.desiredCommit,
+    }, built.outcome.messages);
 }
 export async function inspectCodexPrepared(selection, ctx) {
-    const observedIdentity = await generatedCommitOrEmpty(ctx.root);
-    if (!commitMatches(selection.desiredCommit, observedIdentity)) {
-        return successResult("inspect-prepared", { kind: "needs-prepare", observedIdentity }, []);
+    const root = codexPreparationLocation(ctx).destinationRoot;
+    const observedIdentity = await readGeneratedCommitLenient(join(root, ".superpowers-upstream.json"));
+    const compatibility = unassessedCompatibility();
+    try {
+        if ((await classifyPathNoFollow(join(root, ARTIFACT_RECEIPT))) === "missing")
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity,
+                compatibility,
+            }, []);
+        const artifact = await readCodexAssessment(root);
+        const source = await readStrictProvenanceField(join(artifact.root, ".superpowers-upstream.json"), "source");
+        if (artifact.commit === selection.desiredCommit &&
+            source === selection.effectiveSource) {
+            if (artifact.compatibility.kind === "supported")
+                return successResult("inspect-prepared", {
+                    kind: "current",
+                    artifact,
+                    observedIdentity,
+                    compatibility: artifact.compatibility,
+                }, []);
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity,
+                compatibility: artifact.compatibility,
+            }, []);
+        }
+    }
+    catch {
+        return failureResult("inspect-prepared", "invalid-assessment", `cannot inspect Codex prepared artifact: ${root}`, [], []);
     }
     return successResult("inspect-prepared", {
-        kind: "current",
-        artifact: {
-            root: join(ctx.root, "plugins", "superpowers"),
-            commit: observedIdentity,
-        },
+        kind: "needs-prepare",
         observedIdentity,
+        compatibility,
     }, []);
 }
 export async function readCodexPrepared(ctx) {
     let commit = "";
     try {
-        const value = await readStrictProvenanceField(generatedMetadataPath(ctx.root), "commit");
+        const value = await readStrictProvenanceField(join(codexPreparationLocation(ctx).destinationRoot, ".superpowers-upstream.json"), "commit");
         if (typeof value === "string")
             commit = value;
     }
@@ -195,5 +243,13 @@ export async function readCodexPrepared(ctx) {
     if (commit.length === 0) {
         return failureResult("read-prepared", "missing-commit", "generated metadata missing desired commit after prepare", [], []);
     }
-    return successResult("read-prepared", { root: join(ctx.root, "plugins", "superpowers"), commit }, []);
+    try {
+        const artifact = await readCodexAssessment(codexPreparationLocation(ctx).destinationRoot);
+        if (artifact.compatibility.kind !== "supported")
+            throw new Error("unsupported profile");
+        return successResult("read-prepared", artifact, []);
+    }
+    catch {
+        return failureResult("read-prepared", "invalid-assessment", "generated Codex compatibility assessment is missing or invalid", [], []);
+    }
 }