omakit 0.6.6 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Tested plumbing, the marketplace's own checks, and a disposable Omarchy to test in.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/tools/blocks/commit.json

@@ -1,5 +1,5 @@
 {
-  "commit": "94cb1762be1d74aadbc884d9f86d2a8a0429b019",
-  "recordedAt": "2026-09-21T19:08:27.689Z",
+  "commit": "5dd9db1969775b87b10f21445570557cf82e8073",
+  "recordedAt": "2026-09-21T20:24:57.368Z",
   "how": "Written by `node tools/blocks/record-commit.mjs` in the release workflow before `npm pack`, so a packaged omakit, which has no Git checkout, still names the commit its block files come from. In a checkout this file is null and `git rev-parse HEAD` is the source; a package with null here was packed without the release step, and `omakit add` refuses to stamp a header it cannot name."
 }

package/tools/marketplace/README.md

@@ -7,14 +7,14 @@ local commit through the transport seam the marketplace tests itself
 
 | File | Purpose |
 | --- | --- |
-| `pin.mjs` | The pin identity (one home) and the reproducible setup: `omakit pin` fetches exactly that commit into `$XDG_CACHE_HOME/omakit/marketplace` and refuses a modified checkout. |
+| `pin.mjs` | The pin identity (one home) and the reproducible setup: `omakit pin` fetches exactly that commit into `$XDG_CACHE_HOME/omakit/marketplace` and refuses a modified checkout. `PIN_PATHS` is what is fetched; `PIN_READS` is what omakit opens under `scripts/` and how (imported or read as text), and `pinnedReadSet(pinDir)` adds what the imported files import, by regex over the pinned text and never by loading a module: 16 of 34 files at `b7b29654`, pinned by `tests/unit/pin.test.mjs`. `policyConstants(text)` reads the two policy constants out of the module's text, for the pin's identity and for doctor's comparison at HEAD. |
 | `local-transport.mjs` | Answers the four request shapes the official resolver makes, from a local clone at the exact commit. No network, no credentials, no writes. With `subdir`, serves a directory below the root as the whole tree, which is how `inspect` keeps the baseline to the plugin's own tree. |
 | `run-baseline.mjs` | Runs the pinned official baseline over either transport and reports the pin identity beside the result. |
 | `verify.mjs` | Builds the `marketplaceBaseline` section: pin, transport, assumptions, the official result verbatim, the statement. `omakit verify` renders it for a person (`renderVerify` in `report.mjs`) and prints the document itself behind `--json` and `--out`. |
 | `preflight.mjs` | Translates that result into what it will cause on submission, using the pinned policy, and renders the marketplace's own report text with its attestation marker stripped and asserted absent. |
 | `yaml.mjs` | A deliberately small YAML reader for the pinned issue form. Accepts that subset and throws on anything else. |
 | `form.mjs` | The submission contract, read from the form and cross-checked against the marketplace's own constants. Also the route for a plugin that is already listed: the marketplace's verification form and its "newer commit" choice, read from `verify-plugin.yml` at the pin and cross-checked against `plugin-verification-request.mjs`. |
-| `registry.mjs` | The plugin-id and repository universe: the reserved namespace from the pinned catalog builder, the listed and retired ids and listed repositories from `registry.json` and `site/catalog.json` at the marketplace's current HEAD when the network is there (cached under `$XDG_CACHE_HOME/omakit/registry/<commit>/`, never in the pin) and at the pin with `--offline`; `liveFileUrl()` is the only way to the raw file host, at a 40-character commit, for those two files. `sameRepository()` is the one rule for "the subject's own repository" (owner and name, case-insensitively, a trailing `.git` ignored), and `listingOf()` is what the catalog records about a listing: since when, which commit, verified or not, checked when. |
+| `registry.mjs` | The plugin-id and repository universe: the reserved namespace from the pinned catalog builder, the listed and retired ids and listed repositories from `registry.json` and `site/catalog.json` at the marketplace's current HEAD when the network is there (cached under `$XDG_CACHE_HOME/omakit/registry/<commit>/`, never in the pin) and at the pin with `--offline`; `liveFileUrl()` is the way to the raw file host for those two files, and `headTextUrl()` for the one text `doctor` compares and drops (the policy module at HEAD, `HEAD_TEXT_PATHS`), both at a 40-character commit. `sameRepository()` is the one rule for "the subject's own repository" (owner and name, case-insensitively, a trailing `.git` ignored), and `listingOf()` is what the catalog records about a listing: since when, which commit, verified or not, checked when. |
 | `tree.mjs` | The installable tree of a subject at one exact commit, from the Git object database. |
 | `plugin.mjs` | The root files the submission contract needs, and the declared plugin identity. |
 | `agent-control.mjs` | The recursive agent-control warning, and its remedy. |
@@ -23,7 +23,7 @@ local commit through the transport seam the marketplace tests itself
 | `issue.mjs` | Renders the issue the way the form would, then has the marketplace's own parser judge it. |
 | `submit.mjs` | Assembles every check with its measured reason, and withholds the body when a blocking check fails. Three outcomes: `ready` (the body), `refused` (a blocking check failed) and `listed` (the plugin is already listed by its own repository: `identity.available` passes with the listing's record, the five body checks are omitted rather than drawn as waiting, no body exists on purpose, and `listing` carries the listed commit against the local one and the form to use for a newer commit). Decides the category and tags after the registry: a listed plugin, own or taken, is asked for neither; an unlisted one without them is asked through `ask.mjs` at a terminal, and is a usage error otherwise. Ends with `reproduce`, the command line that repeats the run without asking. Under `--offline` the validation-commit check is `skipped`, not passed: verdict `skipped`, listed under `skipped` and not `unknown`, never blocking, and the READY line says "1 check skipped (--offline)". |
 | `ask.mjs` | The two questions `submit` asks a person at a terminal, and only there: category and tags, numbered from the pinned form, with the marketplace's own presentation for the manifest's kinds (read from the pinned catalog builder) as the default where it is on the list. Prompts on stderr, nothing persisted. |
-| `doctor.mjs` | What is installed, what is pinned, and what has moved. `omakit.version` is one check for one question, is this the current omakit: `ok` with "0.1.8, the newest published version", a `note` with "0.1.8; 0.1.9 is published" and the upgrade command, `unknown` with the registry's failure code, `info` offline; its evidence carries `{ installed, latest, source }`. `pin.freshness` compares each path in `PIN_PATHS` between the pin and the marketplace's HEAD by tree or blob id and splits what moved by the list `registry.mjs` reads live from: `registry.json` and `site/catalog.json` moving is `ok`, because those are read from HEAD anyway; anything else moving (`scripts/`, the two forms) is a `note` naming the paths, with an action a user can take, `omakit upgrade` and then an issue at the repository named in package.json. The maintainer's pin procedure stays in `docs/UPSTREAM_CONTRACT.md` and is never printed. HEAD unreadable is `unknown`. `--json` carries `changedPaths`, `readLive` and `pinned` under the check's evidence. |
+| `doctor.mjs` | What is installed, what is pinned, and what has moved. `omakit.version` is one check for one question, is this the current omakit: `ok` with "0.1.8, the newest published version", a `note` with "0.1.8; 0.1.9 is published" and the upgrade command, `unknown` with the registry's failure code, `info` offline; its evidence carries `{ installed, latest, source }`. `pin.freshness` compares what omakit reads between the pin and the marketplace's HEAD (`comparePin`): the 16 files in `pinnedReadSet()` by blob id, the two data files by blob id, the form directory by tree id, and the two policy constants by the module's text at HEAD when its blob moved; three tree reads, a fourth for `scripts/` only when its id moved, a fifth GET for the policy text only when that blob moved. Graded: `ok` when nothing in the read set moved (the data files are read live; `scripts/` moving elsewhere is said as "in none of the 16 files omakit reads"), `info` when a read file moved and both constants read the same (the files named, verdicts unchanged, nothing to do), `advice` when a constant differs, a read file is gone, or the form moved, with `omakit upgrade` as the action when a newer omakit is published and otherwise that the maintainer is notified; it never asks for an issue, the weekly workflow opens the one there is. Measured (M7): 5e401552, which changed only `repository-identity.mjs`, graded `advice` by tree id and grades `ok` here. The maintainer's pin procedure stays in `docs/UPSTREAM_CONTRACT.md` and is never printed. HEAD unreadable is `unknown`. `--json` carries `changedPaths`, `readLive` and `pinned` under the check's evidence as before, plus `reads`, `moved`, `missing` and `policy.{pin,head}`. |
 | `watch.mjs` | The validation watch: validated commit versus current default-branch HEAD, and the one action that refreshes it. |
 | `github.mjs` | Read-only GitHub access. GET only. The credential is your `gh` login, read through one frozen `gh auth token` call, and is never written anywhere. |
 | `style.mjs` | The visual system, defined once: the palette, the status vocabulary, the block ramp, the columns, the motion budgets, and the composition helpers every command draws with. Six states: `▁ ok`, `█ FAIL`, `▓ note`, `░ info`, `▒ ?` for a check that could not be made, and `▔ skip` for a check a flag said not to make, the floor's ink at the ceiling so it is never read as a pass. `docs/TUI.md` explains it. |

package/tools/marketplace/doctor.mjs

@@ -13,12 +13,13 @@
 // contract is read from, and the procedure in docs/UPSTREAM_CONTRACT.md requires
 // re-proving transport parity and committing the evidence afterwards. An
 // `upgrade` that quietly advanced the pin would break the one guarantee this
-// tool sells. So doctor reports that the pin is behind, and that is all it
-// does: the procedure is the maintainer's, it lives in that document and in
-// this comment, and it is never printed, because the person running doctor
-// is a user of a package that does not even ship docs/. What a user can do
-// is run `omakit upgrade`, since a newer omakit may already carry the new
-// pin, and otherwise open an issue naming the paths that moved.
+// tool sells. So doctor reports what moved, graded, and that is all it does:
+// the procedure is the maintainer's, it lives in that document and in this
+// comment, and it is never printed, because the person running doctor is a
+// user of a package that does not even ship docs/. What a user can do is run
+// `omakit upgrade` when a newer omakit is published, since it may carry the
+// new pin; otherwise the weekly pin-freshness workflow in this repository
+// has already told the maintainer, and there is nothing to open.
 //
 // That the pin goes stale unnoticed is, of course, exactly the defect class
 // `omakit watch` exists to report. It would be poor form not to apply it here.
@@ -35,13 +36,31 @@
 // only registry.json and site/catalog.json moved, doctor said `note` and
 // pointed a user at docs/UPSTREAM_CONTRACT.md, though the pin was behind in
 // nothing the tool uses.
+//
+// Nor is "scripts/ moved" the same as "a file omakit reads moved". Measured
+// on 2026-09-21 (M7): of the three marketplace commits that touched
+// scripts/ since the first pin 38060f89, one (5e401552) changed only
+// repository-identity.mjs, a file none of omakit's reads reach, and doctor
+// graded the tree id's change as advice, a user read "run omakit upgrade",
+// and the maintainer moved the pin for a verdict that could not change.
+// So under scripts/ the comparison is by blob, over the 16 files
+// pinnedReadSet() names, and the verdict is graded: `ok` when none of them
+// moved, `info` when the only moved files are ones omakit takes wording or
+// a label out of (WORDING_READS), `advice` when a file omakit executes or
+// reads a rule from moved, a read file is gone at HEAD, or the form
+// directory moved, which is the contract itself. The two policy constants
+// are read at HEAD as text and printed beside the grade, so a person sees
+// whether the baseline itself changed; they never soften the grade, since
+// a rule can change without its version. The other two commits (7dd6e56,
+// 40315f2) touched submission.mjs and the policy module, both executed,
+// and the forms, so they grade advice either way.
 
 import { execFileSync } from "node:child_process"
 import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
-import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinShape, requirePin } from "./pin.mjs"
-import { LIVE_PATHS } from "./registry.mjs"
-import { credential, defaultBranchHead, getJson, GitHubError } from "./github.mjs"
+import { MARKETPLACE_PIN, PIN_PATHS, POLICY_MODULE, WORDING_READS, marketplacePinDir, pinDiskUsage, pinShape, pinnedReadSet, policyConstants, requirePin } from "./pin.mjs"
+import { LIVE_PATHS, headTextUrl } from "./registry.mjs"
+import { credential, defaultBranchHead, getJson, getText, GitHubError } from "./github.mjs"
 import { compareVersions, NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
 import { sourceCommit } from "../blocks/add.mjs"
 import { recordedCommit } from "../blocks/record-commit.mjs"
@@ -50,19 +69,12 @@ import { completionStatus } from "./completion-check.mjs"
 import { inspectLab } from "../lab/inspect.mjs"
 import { labDoctorChecks } from "../lab/report.mjs"
 
-/** "git+https://github.com/owner/name.git" in package.json -> "https://github.com/owner/name", or null. */
-function repositoryPage(repository) {
-  const url = typeof repository === "string" ? repository : repository?.url
-  const match = String(url || "").match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/)
-  return match ? `https://github.com/${match[1]}/${match[2]}` : null
-}
-
 export function tool(repoRoot) {
   try {
     const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
-    return { name: pkg.name, version: pkg.version, engines: pkg.engines?.node || null, repository: repositoryPage(pkg.repository) }
+    return { name: pkg.name, version: pkg.version, engines: pkg.engines?.node || null }
   } catch {
-    return { name: "omakit", version: "unknown", engines: null, repository: null }
+    return { name: "omakit", version: "unknown", engines: null }
   }
 }
 
@@ -80,17 +92,36 @@ function pinObjectId(pinDir, commit, path) {
   return execFileSync("git", ["-C", pinDir, "rev-parse", `${commit}:${path}`], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
 }
 
+/** A PIN_PATHS pattern as a path: "/site/catalog.json" -> "site/catalog.json". */
+const asPath = (pattern) => pattern.replace(/^\/|\/$/g, "")
+
+/** The form directory: the whole contract, compared by tree id and graded advice when it moved. */
+const FORMS = "/.github/ISSUE_TEMPLATE/"
+
 /**
- * Which of PIN_PATHS differ between the pin and `headCommit`. The pin side is
- * read from the local checkout; the HEAD side walks the git-trees API from the
- * exact commit, one read per tree on the way (three for PIN_PATHS as it
- * stands), so a directory compares by its tree id and a file by its blob id,
- * which is what "the blob at HEAD versus the blob at the pin" means for a
- * directory that omakit reads whole. A path missing at HEAD counts as changed.
+ * The pin against `headCommit`, path by path and, under scripts/, file by
+ * file. The pin side is read from the local checkout; the HEAD side walks
+ * the git-trees API from the exact commit, one read per tree on the way:
+ * three for PIN_PATHS as it stands, a fourth for the scripts/ tree only
+ * when its id moved, since an identical tree has identical blobs. Each
+ * PIN_PATHS entry compares by its own object id (a directory by tree id, a
+ * file by blob id) into `changedPaths`; each file in `reads`
+ * (pinnedReadSet by default) compares by blob id into `moved`, or
+ * `missing` when HEAD no longer has it. A PIN_PATHS entry missing at HEAD
+ * counts as changed.
  *
- * `fetchJson` is injectable for tests; the default is the one GET call site.
+ * When the policy module is among `moved`, its text at HEAD is read once
+ * through `fetchText` (the raw file host at the exact commit, the one GET
+ * call site; a fifth request) and its two constants are returned as
+ * `policyAtHead`; otherwise `policyAtHead` is null, because an identical
+ * blob has identical constants. The text is never imported.
+ *
+ * `fetchJson` and `fetchText` are injectable for tests.
+ *
+ * @returns {Promise<{ changedPaths: string[], reads: number, moved: string[], missing: string[],
+ *                     policyAtHead: { baselineVersion: string, enforcementMode: string }|null }>}
  */
-export async function changedPinPaths({ pinDir, headCommit, pinCommit = MARKETPLACE_PIN.commit, fetchJson = getJson }) {
+export async function comparePin({ pinDir, headCommit, pinCommit = MARKETPLACE_PIN.commit, fetchJson = getJson, fetchText = getText, reads = pinnedReadSet(pinDir) }) {
   const match = MARKETPLACE_PIN.repository.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)$/)
   const trees = new Map()
   const tree = async (sha) => {
@@ -118,73 +149,140 @@ export async function changedPinPaths({ pinDir, headCommit, pinCommit = MARKETPL
     }
     return id
   }
-  const changed = []
+  const changedPaths = []
   for (const pattern of PIN_PATHS) {
-    const path = pattern.replace(/^\/|\/$/g, "")
-    if (pinObjectId(pinDir, pinCommit, path) !== await headObjectId(path)) changed.push(pattern)
+    if (pinObjectId(pinDir, pinCommit, asPath(pattern)) !== await headObjectId(asPath(pattern))) changedPaths.push(pattern)
+  }
+  const moved = []
+  const missing = []
+  if (changedPaths.includes("/scripts/")) {
+    for (const { path } of reads) {
+      const atHead = await headObjectId(path)
+      if (atHead === null) missing.push(path)
+      else if (atHead !== pinObjectId(pinDir, pinCommit, path)) moved.push(path)
+    }
   }
-  return changed
+  const policyAtHead = moved.includes(POLICY_MODULE) ? policyConstants(await fetchText(headTextUrl(headCommit, POLICY_MODULE))) : null
+  return { changedPaths, reads: reads.length, moved, missing, policyAtHead }
 }
 
-/** A PIN_PATHS pattern as a path: "/site/catalog.json" -> "site/catalog.json". */
-const asPath = (pattern) => pattern.replace(/^\/|\/$/g, "")
-
 /** "a", "a and b", "a, b and c". */
 function list(items) {
   return items.length < 3 ? items.join(" and ") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`
 }
 
+/** "baseline 3 (selective)". */
+const policyText = (policy) => `baseline ${policy.baselineVersion} (${policy.enforcementMode})`
+
+/** The moved files a verdict can depend on: everything omakit executes or reads a rule from, which is every read outside WORDING_READS. */
+const verdictBearing = (paths) => paths.filter((path) => !WORDING_READS.includes(path))
+
 /**
- * The pin against the marketplace's HEAD, for a user. `changedPaths` is the
- * answer from changedPinPaths(), split by LIVE_PATHS into `readLive`, the
+ * The pin against the marketplace's HEAD, for a user, graded by what the
+ * difference can do to a verdict. `comparison` is the answer from
+ * comparePin(): its `changedPaths` split by LIVE_PATHS into `readLive`, the
  * data files a moved HEAD cannot make stale because registry.mjs reads them
- * from HEAD, and `pinned`, everything only a new pin can carry. Only the
- * second set is worth a note; the action for it is a user's, not the
- * maintainer's. Null when the comparison was not made, and then the detail
- * says only that HEAD moved. Full commits in the evidence; short ones in
- * the detail. `issues` is where a user reports a pinned path that moved,
- * read from package.json by the caller.
+ * from HEAD, and `pinned`, everything only a new pin can carry; its `moved`
+ * and `missing` name the files omakit reads under scripts/ whose blob
+ * differs at HEAD; its `policyAtHead` carries the two policy constants
+ * there when the policy module moved.
+ *
+ *   ok      nothing omakit reads moved: HEAD moved elsewhere, or only in
+ *           the live-read data files, or scripts/ moved in none of the
+ *           files omakit reads.
+ *   info    the only read files that moved are ones omakit takes wording
+ *           or a label out of (WORDING_READS): what it prints may differ
+ *           at HEAD, what it passes or refuses cannot. A newer omakit will
+ *           carry the pin. Nothing for a user to do.
+ *   advice  a file omakit executes or reads a rule from moved (a verdict
+ *           may differ at HEAD, whether or not the two policy constants
+ *           still read the same, since a rule can change without its
+ *           version), a read file is gone at HEAD, or the form directory
+ *           moved (the contract itself). The action is `upgrade` (the
+ *           command, when the caller found a newer omakit published), else
+ *           that the maintainer is notified; never an issue to open, since
+ *           the weekly pin-freshness workflow opens the one there is. The
+ *           two constants are printed beside the grade in both cases.
+ *
+ * Null for `comparison` means the comparison was not made, which stays
+ * advice: HEAD moved and nothing here can say the pin is fine. Full commits
+ * in the evidence; short ones in the detail.
  */
-export function pinFreshness(identity, head, changedPaths = null, { issues = null } = {}) {
+export function pinFreshness(identity, head, comparison = null, { upgrade = null } = {}) {
   const current = head.commit === identity.commit
   const branch = head.branch || "default"
-  const changed = current ? [] : changedPaths || []
+  const compared = !current && comparison !== null
+  const changed = compared ? comparison.changedPaths : []
   const readLive = changed.filter((pattern) => LIVE_PATHS.includes(asPath(pattern)))
   const pinned = changed.filter((pattern) => !LIVE_PATHS.includes(asPath(pattern)))
+  const moved = compared ? comparison.moved : []
+  const missing = compared ? comparison.missing : []
+  const pinPolicy = { baselineVersion: identity.baselineVersion, enforcementMode: identity.enforcementMode }
+  const headPolicy = (compared && comparison.policyAtHead) || pinPolicy
+  const policyDiffers = headPolicy.baselineVersion !== pinPolicy.baselineVersion || headPolicy.enforcementMode !== pinPolicy.enforcementMode
+  const formMoved = pinned.includes(FORMS)
+  const verdictMoved = verdictBearing(moved)
+  const graded = moved.length > 0 || missing.length > 0 || formMoved
+  const state = current ? "ok"
+    : comparison === null || policyDiffers || formMoved || missing.length || verdictMoved.length ? "advice"
+      : moved.length ? "info"
+        : "ok"
+
   const where = `pin ${identity.commit.slice(0, 7)}; marketplace ${branch} at ${head.commit.slice(0, 7)}`
-  const moved = changedPaths === null
-    ? "; the paths omakit reads were not compared"
-    : pinned.length
-      ? `; changed since the pin: ${pinned.join(", ")}${readLive.length ? ` (${list(readLive.map(asPath))} moved too, and ${readLive.length === 1 ? "that is" : "those are"} read live)` : ""}`
-      : readLive.length
-        ? `; only ${list(readLive.map(asPath))} moved, and ${readLive.length === 1 ? "that is" : "those are"} read live`
-        : "; nothing omakit reads moved"
-  const stale = !current && (changedPaths === null || pinned.length > 0)
+  const clauses = []
+  if (comparison === null) clauses.push("the paths omakit reads were not compared")
+  else if (!changed.length) clauses.push("nothing omakit reads moved")
+  else {
+    if (moved.length) clauses.push(`moved since the pin: ${list(moved)}${verdictMoved.length ? "" : " (wording and labels only)"}`)
+    if (missing.length) clauses.push(`gone at HEAD: ${list(missing)}`)
+    if (formMoved) clauses.push(`the form moved (${asPath(FORMS)}/)`)
+    if (pinned.includes("/scripts/") && !moved.length && !missing.length) clauses.push(`scripts/ moved in none of the ${comparison.reads} files omakit reads`)
+    if (graded) clauses.push(policyDiffers ? `${policyText(pinPolicy)} at the pin, ${policyText(headPolicy)} at HEAD` : `${policyText(pinPolicy)} at both`)
+  }
+  const live = readLive.length ? `${list(readLive.map(asPath))} moved${clauses.length ? " too" : ""}, and ${readLive.length === 1 ? "that is" : "those are"} read live` : ""
+  const tail = !live ? "" : clauses.length ? ` (${live})` : `only ${live}`
+  const detail = current ? `the pin is the marketplace's current ${branch}-branch HEAD` : `${where}; ${clauses.join("; ")}${tail}`
+
+  const action = state === "info"
+    ? `${moved.length === 1 ? "That file is" : "Those files are"} read for wording and labels, not for a pass or a refusal; what omakit prints may differ at HEAD, what it decides cannot. A newer omakit will carry the pin; nothing to do.`
+    : state === "advice"
+      ? upgrade
+        ? `A newer omakit is published and may carry the pin: run \`${upgrade}\`. Until then every verdict here is the pin's, and the marketplace's own run on your issue is the one that counts.`
+        : "The maintainer is notified by the weekly pin-freshness run; a newer omakit will carry the pin. Until then every verdict here is the pin's, and the marketplace's own run on your issue is the one that counts."
+      : null
+
   return {
     id: "pin.freshness",
-    state: stale ? "advice" : "ok",
-    detail: current ? `the pin is the marketplace's current ${branch}-branch HEAD` : `${where}${moved}`,
-    action: stale
-      ? `A newer omakit may already carry the new pin: run \`omakit upgrade\`. If it does not, open an issue${issues ? ` at ${issues}/issues` : ""} naming the paths above.`
-      : null,
+    state,
+    detail,
+    action,
     evidence: {
       pinCommit: identity.commit,
       marketplaceHead: head.commit,
       branch,
-      ...(changedPaths === null ? {} : { changedPaths: changed, readLive, pinned }),
+      ...(comparison === null ? {} : {
+        changedPaths: changed,
+        readLive,
+        pinned,
+        reads: comparison.reads,
+        moved,
+        verdictMoved,
+        missing,
+        policy: { pin: pinPolicy, head: headPolicy },
+      }),
     },
   }
 }
 
 /**
  * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null,
- *           resolveHead?: typeof defaultBranchHead, latest?: typeof registryLatest }} options
+ *           resolveHead?: typeof defaultBranchHead, latest?: typeof registryLatest, compare?: typeof comparePin }} options
  *   `env` and `npmPrefix` are injectable for tests of the PATH check;
- *   `resolveHead` and `latest` for tests of the two checks that read the
- *   network, whose defaults are the tool's one HEAD resolver and its one
- *   registry read.
+ *   `resolveHead`, `latest` and `compare` for tests of the two checks that
+ *   read the network, whose defaults are the tool's one HEAD resolver, its
+ *   one registry read and the pin comparison above.
  */
-export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = registryLatest }) {
+export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = registryLatest, compare = comparePin }) {
   // Optional: told what is being read while the network answers. Never
   // affects the result.
   const phase = onPhase || (() => {})
@@ -201,7 +299,9 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
   // What is installed and what is published, one check: the two facts are
   // one question, "is this the current omakit", and were two lines before.
   // Offline, the first fact alone, as information. The evidence carries both
-  // and where the second came from.
+  // and where the second came from. `upgrade` is the command when a newer
+  // omakit is published, for pin.freshness to name below.
+  let upgrade = null
   const versionCheck = (state, detail, action = null, latest = null, source = null) =>
     add("omakit.version", state, detail, action, { installed: self.version, latest, source })
   if (offline) {
@@ -214,11 +314,12 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
       if (comparison === null) {
         versionCheck("unknown", `${self.version}; the installed or published version is invalid`)
       } else {
+        if (comparison > 0) upgrade = upgradeCommand(repoRoot, self.name)
         versionCheck(comparison > 0 ? "advice" : "ok",
           comparison === 0 ? `${self.version}, the newest published version`
             : comparison < 0 ? `${self.version}; ahead of the newest published version ${published.version}`
               : `${self.version}; ${published.version} is published`,
-          comparison > 0 ? `run \`${upgradeCommand(repoRoot, self.name)}\`` : null,
+          comparison > 0 ? `run \`${upgrade}\`` : null,
           published.version, NPM_REGISTRY)
       }
     } else {
@@ -293,12 +394,12 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
     phase("reading the marketplace's current default-branch HEAD")
     try {
       const head = await resolveHead(MARKETPLACE_PIN.repository)
-      let changedPaths = []
+      let comparison = { changedPaths: [], reads: pinnedReadSet(dir).length, moved: [], missing: [], policyAtHead: null }
       if (head.commit !== identity.commit) {
-        phase("comparing each path omakit reads between the pin and HEAD")
-        changedPaths = await changedPinPaths({ pinDir: dir, headCommit: head.commit, pinCommit: identity.commit })
+        phase("comparing each file omakit reads between the pin and HEAD")
+        comparison = await compare({ pinDir: dir, headCommit: head.commit, pinCommit: identity.commit })
       }
-      checks.push(pinFreshness(identity, head, changedPaths, { issues: self.repository }))
+      checks.push(pinFreshness(identity, head, comparison, { upgrade }))
     } catch (error) {
       add("pin.freshness", "unknown", `could not read the marketplace's HEAD (${error.code || "error"})`,
         error.code === "network-unavailable" ? "Connect to the network, or pass --offline to skip the two checks that need it." : null,

package/tools/marketplace/pin.mjs

@@ -4,14 +4,15 @@
 //
 // It fetches only what omakit reads. The marketplace at this commit is 325 MB,
 // of which 168 MB is preview imagery and 151 MB is history, and omakit reads
-// seven files out of it. A blob-filtered, sparsely checked out fetch of just
-// those paths is 15 MB and takes 2 seconds instead of 17. PIN_PATHS below is the
-// whole list, and tests/unit/pin.test.mjs fails if any module starts reading a
-// path outside it, because on a partial clone such a read would quietly reach
-// for the network instead of failing.
+// twenty files out of it, sixteen of them under scripts/ (PIN_READS). A
+// blob-filtered, sparsely checked out fetch of just those paths is 15 MB and
+// takes 2 seconds instead of 17. PIN_PATHS below is the whole list, and
+// tests/unit/pin.test.mjs fails if any module starts reading a path outside
+// it, because on a partial clone such a read would quietly reach for the
+// network instead of failing.
 import { execFileSync, spawnSync } from "node:child_process"
 import { existsSync, readdirSync, readFileSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs"
-import { dirname, join, resolve } from "node:path"
+import { dirname, join, posix, resolve } from "node:path"
 import { omakitCacheDir } from "./paths.mjs"
 
 /** Raised for every way the pin can be missing or wrong; the code is what the CLI keys its remedy on. */
@@ -52,6 +53,147 @@ export const PIN_PATHS = Object.freeze([
   "/.github/ISSUE_TEMPLATE/",
 ])
 
+/** The policy module, read at the pin for its two constants (readPinIdentity) and at HEAD as text by doctor for the same two. */
+export const POLICY_MODULE = "scripts/security-baseline-policy.mjs"
+
+/**
+ * The files omakit opens under /scripts/, and how. PIN_PATHS fetches the
+ * directory whole because these import each other; this is what is opened
+ * out of it, so `omakit doctor` can tell a change to one of the 34 files
+ * there at the pin that omakit reads from a change to one it does not.
+ * Measured on 2026-09-21 (docs/MEASUREMENTS.md M7): of the three commits
+ * that touched scripts/ since the first pin 38060f89, one touched only
+ * `repository-identity.mjs`, a file omakit neither opens nor imports
+ * through anything it opens, and doctor called the pin behind for it.
+ *
+ * An `imported` file is executed, and what it imports is read with it:
+ * pinnedReadSet() follows the static imports. A file read as text is read
+ * alone, since a constant taken out of its text does not change when its
+ * imports do.
+ *
+ *   submission.mjs                   form.mjs, watch.mjs
+ *   plugin-verification-request.mjs  form.mjs, watch.mjs
+ *   security-baseline-scanner.mjs    run-baseline.mjs
+ *   security-baseline-policy.mjs     preflight.mjs, watch.mjs, review-cost.mjs;
+ *                                    as text here, for readPinIdentity
+ *   security-baseline-report.mjs     preflight.mjs
+ *   security-baseline-record.mjs     watch.mjs
+ *   submission-feedback.mjs          watch.mjs, and as text for its codes
+ *   build-catalog.mjs                registry.mjs, text: it imports sharp
+ *   approve-submission.mjs           watch.mjs, text: one label
+ *   approve-plugin-update.mjs        review-cost.mjs, text: one label
+ *
+ * tests/unit/pin.test.mjs derives this list from the sources and fails on
+ * a read that is not here, or one listed the wrong way round.
+ */
+export const PIN_READS = Object.freeze([
+  Object.freeze({ path: "scripts/submission.mjs", imported: true }),
+  Object.freeze({ path: "scripts/plugin-verification-request.mjs", imported: true }),
+  Object.freeze({ path: "scripts/security-baseline-scanner.mjs", imported: true }),
+  Object.freeze({ path: POLICY_MODULE, imported: true }),
+  Object.freeze({ path: "scripts/security-baseline-report.mjs", imported: true }),
+  Object.freeze({ path: "scripts/security-baseline-record.mjs", imported: true }),
+  Object.freeze({ path: "scripts/submission-feedback.mjs", imported: true }),
+  Object.freeze({ path: "scripts/build-catalog.mjs", imported: false }),
+  Object.freeze({ path: "scripts/approve-submission.mjs", imported: false }),
+  Object.freeze({ path: "scripts/approve-plugin-update.mjs", imported: false }),
+])
+
+/**
+ * The read files omakit takes only wording or a label out of, and decides
+ * nothing by: the baseline's rendered details, the failure table a refusal's
+ * reason is mapped through for display, and one label name each from the
+ * two approval scripts. A change to one of these changes what omakit
+ * prints, never whether it passes or refuses. Every other file in
+ * pinnedReadSet() is executed or read for a rule, a limit, a constant or a
+ * parser, so a change there can change a verdict, and `omakit doctor`
+ * grades it advice. The list is a whitelist on purpose: a file that is not
+ * here is treated as verdict-bearing until someone proves otherwise here.
+ */
+export const WORDING_READS = Object.freeze([
+  "scripts/security-baseline-report.mjs",
+  "scripts/submission-feedback.mjs",
+  "scripts/approve-submission.mjs",
+  "scripts/approve-plugin-update.mjs",
+])
+
+/** A static import or re-export of a relative module: `import x from "./y.mjs"`, `export * from "./y.mjs"`, across lines. */
+export const RELATIVE_IMPORT = /\bfrom\s+["'](\.\.?\/[^"']+)["']/g
+
+/**
+ * The import forms RELATIVE_IMPORT does not follow. (A relative `from`
+ * specifier of any kind is followed, a JSON import included, so that needs
+ * no guard; Node's ESM loader requires an extension.) If one of these ever
+ * appears in an executed file of the pinned read set, pinnedReadSet() could
+ * miss a file, and tests/unit/pin.test.mjs fails on the file and line
+ * instead of doctor staying quiet. Measured at pin b7b29654: none of
+ * the 13 executed files uses any of them (the three read as text are not
+ * scanned, since nothing they import is loaded).
+ */
+export const UNFOLLOWED_IMPORTS = Object.freeze([
+  Object.freeze({ form: "dynamic import()", pattern: /\bimport\s*\(/ }),
+  Object.freeze({ form: "side-effect import", pattern: /^\s*import\s+["']/ }),
+  Object.freeze({ form: "require()", pattern: /\brequire\s*\(/ }),
+  Object.freeze({ form: "import.meta.resolve()", pattern: /\bimport\.meta\.resolve\s*\(/ }),
+])
+
+/**
+ * Every line in the read set's executed files that carries an import form
+ * the closure does not follow: `{ path, line, form, text }`, empty when the
+ * closure is complete. Files read as text are not scanned: nothing they
+ * import is loaded. Read as text, like the closure itself.
+ */
+export function unfollowedImports(pinDir, reads = pinnedReadSet(pinDir)) {
+  const found = []
+  for (const { path } of reads.filter((read) => read.imported)) {
+    const lines = readFileSync(join(pinDir, path), "utf8").split("\n")
+    lines.forEach((text, index) => {
+      for (const { form, pattern } of UNFOLLOWED_IMPORTS) {
+        if (pattern.test(text)) found.push({ path, line: index + 1, form, text: text.trim() })
+      }
+    })
+  }
+  return found
+}
+
+/**
+ * Every file omakit reads under /scripts/ at the checkout in `pinDir`:
+ * PIN_READS, plus, for each imported one, what it imports in turn, found
+ * by regex over `from "./x.mjs"` in the file's text and never by loading
+ * it. Paths relative to the checkout, sorted, each once, with `via` naming
+ * the file that imports it or null for one omakit opens itself. A
+ * specifier that leaves scripts/ (the marketplace's site/ assets) or names
+ * a package (`sharp`) is not followed: PIN_PATHS does not fetch it, so
+ * omakit could not read it. Measured at pin b7b29654: 16 of the 34 files
+ * under scripts/, 10 opened by omakit and 6 imported by those.
+ *
+ * @returns {{ path: string, imported: boolean, via: string|null }[]}
+ */
+export function pinnedReadSet(pinDir, reads = PIN_READS) {
+  const set = new Map()
+  const queue = []
+  for (const read of reads) {
+    set.set(read.path, { path: read.path, imported: read.imported, via: null })
+    if (read.imported) queue.push(read.path)
+  }
+  while (queue.length) {
+    const from = queue.shift()
+    let text
+    try {
+      text = readFileSync(join(pinDir, from), "utf8")
+    } catch (error) {
+      throw new PinError(`cannot read ${from} from the pinned checkout at ${pinDir}: ${error.message}`)
+    }
+    for (const match of text.matchAll(RELATIVE_IMPORT)) {
+      const path = posix.normalize(posix.join(posix.dirname(from), match[1]))
+      if (!path.startsWith("scripts/") || set.has(path)) continue
+      set.set(path, { path, imported: true, via: from })
+      queue.push(path)
+    }
+  }
+  return [...set.values()].sort((a, b) => a.path.localeCompare(b.path))
+}
+
 /**
  * The user-writable pin location: `$XDG_CACHE_HOME/omakit/marketplace`, or
  * `~/.cache/omakit/marketplace`. omakit reads no variable of its own; a test or
@@ -86,14 +228,27 @@ function git(dir, args, options = {}) {
   return execFileSync("git", ["-C", dir, ...args], { timeout: 300_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...options })
 }
 
+/**
+ * The two policy constants out of the policy module's text, the way the
+ * pin's identity has always read them: `securityBaselineVersion` and
+ * `securityBaselineEnforcementMode`, or "unknown" where the text has no
+ * such line. Text in, two strings out; the module is not loaded, so the
+ * same read serves doctor for the module at HEAD.
+ */
+export function policyConstants(text) {
+  const source = String(text || "")
+  return {
+    baselineVersion: source.match(/securityBaselineVersion\s*=\s*"?([^";\s]+)"?/)?.[1] || "unknown",
+    enforcementMode: source.match(/securityBaselineEnforcementMode\s*=\s*"([^"]+)"/)?.[1] || "unknown",
+  }
+}
+
 /** Identity of the checkout at `dir`: commit plus the policy constants read from the pinned source. */
 function readPinIdentity(dir) {
   const commit = git(dir, ["rev-parse", "HEAD"]).trim()
-  const policy = git(dir, ["show", `${commit}:scripts/security-baseline-policy.mjs`])
-  const version = policy.match(/securityBaselineVersion\s*=\s*"?([^";\s]+)"?/)?.[1] || "unknown"
-  const mode = policy.match(/securityBaselineEnforcementMode\s*=\s*"([^"]+)"/)?.[1] || "unknown"
+  const { baselineVersion, enforcementMode } = policyConstants(git(dir, ["show", `${commit}:${POLICY_MODULE}`]))
   const dirty = git(dir, ["status", "--porcelain"]).trim().length > 0
-  return { commit, baselineVersion: version, enforcementMode: mode, dirty }
+  return { commit, baselineVersion, enforcementMode, dirty }
 }
 
 /**

package/tools/marketplace/registry.mjs

@@ -26,7 +26,7 @@
 
 import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
-import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
+import { MARKETPLACE_PIN, POLICY_MODULE, requirePin } from "./pin.mjs"
 import { defaultBranchHead, getJson } from "./github.mjs"
 import { omakitCacheDir } from "./paths.mjs"
 
@@ -34,9 +34,17 @@ export const CATALOG_PATH = "site/catalog.json"
 export const REGISTRY_PATH = "registry.json"
 export const CATALOG_BUILDER_PATH = "scripts/build-catalog.mjs"
 
-/** The only two marketplace files ever read from HEAD. Everything else comes from the pin. */
+/** The only two marketplace files whose content omakit uses from HEAD. Everything else comes from the pin. */
 export const LIVE_PATHS = Object.freeze([REGISTRY_PATH, CATALOG_PATH])
 
+/**
+ * The one file read from HEAD as text and used for nothing: `omakit doctor`
+ * reads the policy module at HEAD to compare its two constants with the
+ * pin's (pin.mjs policyConstants) and drops the text. It is never imported,
+ * never cached and never a source of a rule; the rules stay the pin's.
+ */
+export const HEAD_TEXT_PATHS = Object.freeze([POLICY_MODULE])
+
 export class RegistryError extends Error {
   constructor(code, message) {
     super(message)
@@ -140,7 +148,9 @@ export function sameRepository(a, b) {
  * one explicit 40-character commit on the marketplace's raw file host. Never
  * a branch name, so the two files always come from the same commit and the
  * commit named in the output is the one they came from; never a path outside
- * LIVE_PATHS, so nothing executable can arrive this way.
+ * LIVE_PATHS, so nothing executable can arrive this way. (headTextUrl below
+ * reaches the same host for one module's text, which is compared and never
+ * run.)
  */
 export function liveFileUrl(commit, path) {
   if (!/^[0-9a-f]{40}$/.test(String(commit))) {
@@ -149,6 +159,27 @@ export function liveFileUrl(commit, path) {
   if (!LIVE_PATHS.includes(path)) {
     throw new RegistryError("usage", `${path} is never read from HEAD; only ${LIVE_PATHS.join(" and ")} are`)
   }
+  return rawFileUrl(commit, path)
+}
+
+/**
+ * The same URL shape for the one file doctor reads from HEAD as text:
+ * HEAD_TEXT_PATHS, at a 40-character commit, through the same host and the
+ * same GET call site. Its text is compared and dropped; `liveFileUrl` still
+ * refuses it, so nothing reads it as data.
+ */
+export function headTextUrl(commit, path) {
+  if (!/^[0-9a-f]{40}$/.test(String(commit))) {
+    throw new RegistryError("usage", `a marketplace file is read at a 40-character commit, not "${commit}"`)
+  }
+  if (!HEAD_TEXT_PATHS.includes(path)) {
+    throw new RegistryError("usage", `${path} is never read from HEAD as text; only ${HEAD_TEXT_PATHS.join(" and ")} ${HEAD_TEXT_PATHS.length === 1 ? "is" : "are"}`)
+  }
+  return rawFileUrl(commit, path)
+}
+
+/** The raw file host at one commit; the two builders above are its only callers, and each holds its own path list. */
+function rawFileUrl(commit, path) {
   const raw = MARKETPLACE_PIN.repository.replace(/^https:\/\/github\.com\//, "https://raw.githubusercontent.com/")
   return `${raw}/${commit}/${path}`
 }