mandrel-platform 1.8.1 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/env-doctor.mjs

@@ -121,6 +121,8 @@ export const SHAPE_NAMES = Object.freeze(Object.keys(SHAPE_VOCABULARY));
  */
 export const MANIFEST_SCHEMA = Object.freeze({
   environments: "string[] — environment slugs, e.g. ['staging','production']",
+  environmentSlugs:
+    "object? — surface name -> {environment: slug}. Only 'infisical' is honored; an unmapped environment resolves to itself.",
   workers:
     "object? — worker id -> {config, scriptName}. `scriptName` may contain '{env}', substituted per environment.",
   keys: "object[] — one entry per env var / secret (see KEY_SCHEMA)",
@@ -131,13 +133,98 @@ export const KEY_SCHEMA = Object.freeze({
   kind: "'var' | 'secret'",
   sensitivity: "'public' | 'secret'",
   residency:
-    "object — {local: 'var'|'secret'|'file'|null, github: {scope,kind}|null, cloudflare: {workers,kind}|null}",
-  infisical: "{folder, environments} | 'unmanaged'",
+    "object — {local: 'var'|'secret'|'file'|null, github: G|G[]|null where G = {scope,kind,environments?}, cloudflare: {workers,kind}|null}",
+  infisical:
+    "{folder, environments} | {folders: (string | {folder, environments})[]} | 'unmanaged'",
   shape: `string? — one of ${SHAPE_NAMES.join(", ")}`,
   placeholderPattern: "string? — literal, case-insensitive substring marking an unset placeholder value",
   note: "string? — free text",
 });
 
+/**
+ * The surfaces whose environment namespace can be remapped.
+ *
+ * `manifest.environments` names DEPLOY environments, and until Story #464 that
+ * one list was substituted verbatim into three namespaces that are not the
+ * same namespace — the Worker script name, the GitHub Environment API path,
+ * and the Infisical environment slug. A project whose Infisical slugs differ
+ * from its deploy names (`prod` against a `production` environment) could not
+ * be probed at all: the surface went to `error`, which is deliberately
+ * unsuppressable, so the lane was permanently red with no downstream fix.
+ *
+ * Only `infisical` is remappable, and deliberately so. Cloudflare already has
+ * its own escape hatch — `resolveScriptName` substitutes `{env}` into
+ * `workers[].scriptName`, so `acme-site-{env}` resolves whatever the deploy
+ * name is — and giving it a slug map too would be two mechanisms for one job.
+ * The GitHub Environment API is read at `manifest.environments` verbatim and
+ * no divergence has been observed there. The CONTAINER is nonetheless keyed by
+ * surface rather than being an Infisical-only field, so a surface that ever
+ * does diverge adopts it without inventing a second idiom.
+ */
+export const SLUG_MAPPED_SURFACES = Object.freeze(["infisical"]);
+
+/**
+ * Normalize `manifest.environmentSlugs` to a total map over the slug-mapped
+ * surfaces, so a caller never has to distinguish "absent" from "empty".
+ *
+ * Validation fails closed, matching this module's posture on an unknown
+ * `shape`: silently ignoring a misspelled surface or environment is how a
+ * manifest author comes to believe they have remapped something they have not,
+ * and the symptom — a 404 from the store — looks nothing like the cause.
+ *
+ * @param {unknown} raw
+ * @param {string[]} environments
+ * @returns {Record<string, Record<string, string>>}
+ */
+function normalizeEnvironmentSlugs(raw, environments) {
+  const out = {};
+  for (const surface of SLUG_MAPPED_SURFACES) out[surface] = {};
+  if (raw === undefined || raw === null) return out;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("manifest.environmentSlugs must be an object mapping a surface name -> {environment: slug}");
+  }
+
+  for (const [surface, map] of Object.entries(raw)) {
+    if (!SLUG_MAPPED_SURFACES.includes(surface)) {
+      throw new Error(
+        `manifest.environmentSlugs."${surface}" is not a slug-mapped surface — supported: ` +
+          `${SLUG_MAPPED_SURFACES.join(", ")}. Cloudflare resolves each environment through the ` +
+          `"{env}" substitution in workers[].scriptName, and the GitHub Environment API is read at ` +
+          `manifest.environments verbatim, so neither takes a slug map.`
+      );
+    }
+    if (!map || typeof map !== "object" || Array.isArray(map)) {
+      throw new Error(`manifest.environmentSlugs.${surface} must be an object mapping environment -> slug`);
+    }
+    for (const [environment, slug] of Object.entries(map)) {
+      if (!environments.includes(environment)) {
+        throw new Error(
+          `manifest.environmentSlugs.${surface} maps "${environment}", absent from manifest.environments`
+        );
+      }
+      if (typeof slug !== "string" || !slug) {
+        throw new Error(`manifest.environmentSlugs.${surface}["${environment}"] must be a non-empty slug string`);
+      }
+      out[surface][environment] = slug;
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve the slug one surface uses for a manifest environment. Identity for
+ * any environment the manifest does not remap, which is what keeps an absent
+ * `environmentSlugs` a no-op for every manifest written before Story #464.
+ *
+ * @param {object} manifest  A parsed manifest.
+ * @param {string} surface
+ * @param {string} environment
+ * @returns {string}
+ */
+export function resolveSurfaceEnvironment(manifest, surface, environment) {
+  return manifest?.environmentSlugs?.[surface]?.[environment] ?? environment;
+}
+
 /**
  * Parse and validate a raw manifest object. Throws with an actionable message
  * on any violation — a manifest is authored by hand, so a vague error costs a
@@ -175,10 +262,198 @@ export function parseManifest(raw) {
     throw new Error("manifest.keys must be a non-empty array");
   }
 
+  const environmentSlugs = normalizeEnvironmentSlugs(raw.environmentSlugs, environments);
+
   const seen = new Set();
   const keys = raw.keys.map((entry, i) => validateKeyEntry(entry, i, workers, environments, seen));
 
-  return { environments: [...environments], workers, keys };
+  return { environments: [...environments], environmentSlugs, workers, keys };
+}
+
+/**
+ * Normalize `residency.github` to its canonical array form.
+ *
+ * The field accepts EITHER a single `{scope, kind}` object — the shape every
+ * manifest written before Story #459 uses — or an array of them, because two
+ * residencies that occur in practice cannot be said with one object:
+ *
+ *   1. **Dual scope.** A key can legitimately live at repository level AND at
+ *      environment level, for different consumers: a deploy job declares
+ *      `environment:` and reads the per-environment value while a CI job
+ *      declares none and reads a repo-level credential of the same name.
+ *      Under a single object, whichever scope the manifest declared, the other
+ *      reported as an orphan — permanently, on a healthy repo.
+ *   2. **Per-environment presence.** A key can be deliberately present in one
+ *      environment and absent from another (a production-only analytics token
+ *      whose staging counterpart is meant to resolve empty). With no
+ *      per-entry `environments`, the absence read as a `missing` failure.
+ *
+ * Both authored shapes normalize to one array of `{scope, kind, environments}`
+ * with `environments` defaulted and materialized to `manifest.environments`,
+ * so `probeGitHub` has exactly one shape to read — the same normalize-at-parse
+ * treatment `infisical.environments` already receives.
+ *
+ * Validation fails closed, matching this module's posture on an unknown
+ * `shape`: silently ignoring a misplaced or misspelled `environments` is how a
+ * manifest author comes to believe they have scoped something they have not.
+ *
+ * @param {unknown} raw
+ * @param {{at: string, name: string, environments: string[]}} ctx
+ * @returns {Array<{scope: string, kind: string, environments: string[]}> | null}
+ */
+function normalizeGitHubResidency(raw, { at, name, environments }) {
+  if (raw === undefined || raw === null) return null;
+
+  const authoredAsArray = Array.isArray(raw);
+  const entries = authoredAsArray ? raw : [raw];
+  if (entries.length === 0) {
+    throw new Error(
+      `${at}.residency.github must not be an empty array — use null when the key does not belong in GitHub (key ${name})`
+    );
+  }
+
+  const seenPairs = new Set();
+  return entries.map((entry, j) => {
+    const where = authoredAsArray ? `${at}.residency.github[${j}]` : `${at}.residency.github`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${where} must be an object with {scope, kind} (key ${name})`);
+    }
+    if (entry.scope !== "environment" && entry.scope !== "repository") {
+      throw new Error(`${where}.scope must be "environment" or "repository" (key ${name})`);
+    }
+    if (entry.kind !== "secret" && entry.kind !== "var") {
+      throw new Error(`${where}.kind must be "secret" or "var" (key ${name})`);
+    }
+
+    const pair = `${entry.scope}/${entry.kind}`;
+    if (seenPairs.has(pair)) {
+      throw new Error(
+        `${where} repeats the (scope, kind) pair "${pair}" — declare one entry per pair (key ${name})`
+      );
+    }
+    seenPairs.add(pair);
+
+    if (entry.environments !== undefined) {
+      if (entry.scope === "repository") {
+        throw new Error(
+          `${where}.environments is meaningful only under scope "environment" — a repository-scope ` +
+            `secret or variable belongs to no environment (key ${name})`
+        );
+      }
+      if (!Array.isArray(entry.environments) || !entry.environments.every((e) => typeof e === "string")) {
+        throw new Error(`${where}.environments must be an array of environment slugs (key ${name})`);
+      }
+      for (const e of entry.environments) {
+        if (!environments.includes(e)) {
+          throw new Error(
+            `${where}.environments names "${e}", absent from manifest.environments (key ${name})`
+          );
+        }
+      }
+    }
+
+    return {
+      scope: entry.scope,
+      kind: entry.kind,
+      environments: entry.environments ? [...entry.environments] : [...environments],
+    };
+  });
+}
+
+/**
+ * Normalize `infisical` residency to its canonical `{folders: [...]}` form.
+ *
+ * The field accepts EITHER a single `{folder, environments}` object — the shape
+ * every manifest written before Story #464 uses — or `{folders: [...]}` whose
+ * entries are a bare folder path or a `{folder, environments}` object, because
+ * two residencies that occur in practice cannot be said with one folder:
+ *
+ *   1. **Multi-folder residency.** A key can legitimately be resident in more
+ *      than one folder, and folder IMPORTS are what make that normal rather
+ *      than sloppy: when `/cloudflare` imports `/shared`, a value entering at
+ *      `/shared` is genuinely read through `/cloudflare` as well. Both
+ *      statements are true and one field could hold only one, so the same
+ *      misplacement was counted TWICE — `missing` from the declared folder and
+ *      `orphan` in the folder that actually held it.
+ *   2. **Per-environment residency.** A key can live in a different folder per
+ *      environment (an operator-held credential that arrives via `/github` in
+ *      staging only). With no per-entry `environments`, one of the two folders
+ *      was always wrong.
+ *
+ * Both authored shapes normalize to one array of `{folder, environments}` with
+ * `environments` defaulted and materialized to `manifest.environments`, so
+ * `probeInfisical` has exactly one shape to read — the same normalize-at-parse
+ * treatment `residency.github` received in Story #459, so there is one
+ * precedent for expressive residency rather than two idioms.
+ *
+ * @param {unknown} raw
+ * @param {{at: string, name: string, environments: string[]}} ctx
+ * @returns {"unmanaged" | {folders: Array<{folder: string, environments: string[]}>}}
+ */
+function normalizeInfisicalResidency(raw, { at, name, environments }) {
+  if (raw === undefined || raw === null || raw === "unmanaged") return "unmanaged";
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${at}.infisical must be "unmanaged", {folder, environments} or {folders: [...]} (key ${name})`);
+  }
+
+  const hasFolder = raw.folder !== undefined;
+  const hasFolders = raw.folders !== undefined;
+  if (hasFolder && hasFolders) {
+    throw new Error(`${at}.infisical declares both "folder" and "folders" — use one or the other (key ${name})`);
+  }
+  if (!hasFolder && !hasFolders) {
+    throw new Error(`${at}.infisical must declare "folder" or "folders", or be "unmanaged" (key ${name})`);
+  }
+
+  let authored;
+  if (hasFolder) {
+    authored = [{ folder: raw.folder, environments: raw.environments, where: `${at}.infisical` }];
+  } else {
+    if (!Array.isArray(raw.folders) || raw.folders.length === 0) {
+      throw new Error(
+        `${at}.infisical.folders must be a non-empty array — use "unmanaged" when the key does not ` +
+          `belong in Infisical (key ${name})`
+      );
+    }
+    if (raw.environments !== undefined) {
+      throw new Error(
+        `${at}.infisical.environments is meaningful only beside a single "folder" — under "folders" ` +
+          `each entry carries its own environments (key ${name})`
+      );
+    }
+    authored = raw.folders.map((folderEntry, j) => {
+      const where = `${at}.infisical.folders[${j}]`;
+      if (typeof folderEntry === "string") return { folder: folderEntry, environments: undefined, where };
+      if (!folderEntry || typeof folderEntry !== "object" || Array.isArray(folderEntry)) {
+        throw new Error(`${where} must be a folder path string or {folder, environments} (key ${name})`);
+      }
+      return { folder: folderEntry.folder, environments: folderEntry.environments, where };
+    });
+  }
+
+  const seenFolders = new Set();
+  const folders = authored.map(({ folder, environments: authoredEnvs, where }) => {
+    if (typeof folder !== "string" || !folder) {
+      throw new Error(`${where}.folder must be a non-empty folder path string (key ${name})`);
+    }
+    if (seenFolders.has(folder)) {
+      throw new Error(`${at}.infisical repeats the folder "${folder}" — declare one entry per folder (key ${name})`);
+    }
+    seenFolders.add(folder);
+
+    const envs = authoredEnvs ?? environments;
+    if (!Array.isArray(envs) || !envs.every((e) => typeof e === "string")) {
+      throw new Error(`${at}.infisical.environments must be an array of environment slugs (key ${name})`);
+    }
+    for (const e of envs) {
+      if (!environments.includes(e)) {
+        throw new Error(`${at}.infisical.environments names "${e}", absent from manifest.environments (key ${name})`);
+      }
+    }
+    return { folder, environments: [...envs] };
+  });
+
+  return { folders };
 }
 
 /**
@@ -217,15 +492,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
     throw new Error(`${at}.residency.local must be "var", "secret", "file" or null (key ${name})`);
   }
 
-  const github = residency.github ?? null;
-  if (github !== null) {
-    if (github.scope !== "environment" && github.scope !== "repository") {
-      throw new Error(`${at}.residency.github.scope must be "environment" or "repository" (key ${name})`);
-    }
-    if (github.kind !== "secret" && github.kind !== "var") {
-      throw new Error(`${at}.residency.github.kind must be "secret" or "var" (key ${name})`);
-    }
-  }
+  const github = normalizeGitHubResidency(residency.github, { at, name, environments });
 
   const cloudflare = residency.cloudflare ?? null;
   if (cloudflare !== null) {
@@ -242,21 +509,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
     }
   }
 
-  const infisical = entry.infisical ?? "unmanaged";
-  if (infisical !== "unmanaged") {
-    if (!infisical || typeof infisical !== "object" || typeof infisical.folder !== "string") {
-      throw new Error(`${at}.infisical must be "unmanaged" or {folder, environments} (key ${name})`);
-    }
-    const envs = infisical.environments ?? environments;
-    if (!Array.isArray(envs) || !envs.every((e) => typeof e === "string")) {
-      throw new Error(`${at}.infisical.environments must be an array of environment slugs (key ${name})`);
-    }
-    for (const e of envs) {
-      if (!environments.includes(e)) {
-        throw new Error(`${at}.infisical.environments names "${e}", absent from manifest.environments (key ${name})`);
-      }
-    }
-  }
+  const infisical = normalizeInfisicalResidency(entry.infisical, { at, name, environments });
 
   if (entry.shape !== undefined) {
     if (typeof entry.shape !== "string" || !Object.hasOwn(SHAPE_VOCABULARY, entry.shape)) {
@@ -279,10 +532,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
       github,
       cloudflare: cloudflare ? { workers: [...cloudflare.workers], kind: cloudflare.kind } : null,
     },
-    infisical:
-      infisical === "unmanaged"
-        ? "unmanaged"
-        : { folder: infisical.folder, environments: [...(infisical.environments ?? environments)] },
+    infisical,
     shape: entry.shape ?? null,
     placeholderPattern: entry.placeholderPattern ?? null,
     note: typeof entry.note === "string" ? entry.note : null,
@@ -774,12 +1024,22 @@ export function runOfflineChecks({ manifest, repoRoot }) {
  * @param {string} opts.surface
  * @param {string | null} opts.environment
  * @param {string} [opts.scope]     Free-text scope for the detail line.
+ * @param {Iterable<string> | null} [opts.declaredElsewhere]
+ *   Names the caller has already accounted for in a SIBLING partition of the
+ *   same surface. A name in this set is never reported as an orphan here; it
+ *   has no effect on `missing`. The option exists because a surface can be
+ *   probed in more than one partition — GitHub is read at repository scope and
+ *   again per environment — and a key legitimately resident in two of them is
+ *   not drift. Only the caller knows which partitions are siblings, so the set
+ *   is supplied rather than inferred: the default is `null`, which keeps this
+ *   function's behaviour identical for every caller that omits it.
  * @returns {object[]} findings
  */
-export function reconcileNames({ expected, present, surface, environment, scope = "" }) {
+export function reconcileNames({ expected, present, surface, environment, scope = "", declaredElsewhere = null }) {
   const findings = [];
   const presentSet = new Set(present);
   const expectedSet = new Set(expected);
+  const elsewhere = declaredElsewhere ? new Set(declaredElsewhere) : null;
   const where = scope ? ` (${scope})` : "";
   for (const name of expected) {
     if (!presentSet.has(name)) {
@@ -795,6 +1055,7 @@ export function reconcileNames({ expected, present, surface, environment, scope
   }
   for (const name of present) {
     if (!expectedSet.has(name)) {
+      if (elsewhere?.has(name)) continue;
       findings.push({
         severity: "orphan",
         kind: "orphan",
@@ -1065,6 +1326,45 @@ function unavailableNotice(unavailability, surface) {
 }
 
 /**
+ * Names declared at one GitHub `(scope, kind)`, optionally narrowed to the
+ * entries that name a given environment.
+ *
+ * @param {object[]} keys           Parsed manifest keys.
+ * @param {string} scope            "repository" | "environment"
+ * @param {string} kind             "secret" | "var"
+ * @param {string | null} environment  Non-null narrows to entries naming it.
+ * @returns {string[]}
+ */
+function githubNamesAt(keys, scope, kind, environment) {
+  return keys
+    .filter((k) =>
+      (k.residency.github ?? []).some(
+        (g) =>
+          g.scope === scope && g.kind === kind && (environment === null || g.environments.includes(environment))
+      )
+    )
+    .map((k) => k.name);
+}
+
+/**
+ * Reconcile the GitHub surface per `(scope, kind, environment)` triple.
+ *
+ * Two partitions are read — repository scope once, environment scope once per
+ * environment — and a key may legitimately be resident in both. So each
+ * partition suppresses orphans for names declared at the OTHER scope with the
+ * SAME kind, and nothing wider:
+ *
+ * - **Cross-scope, same kind** is suppressed: that is the dual-scope residency
+ *   the array form exists to describe, and reporting it was the false orphan.
+ * - **Cross-kind is NOT suppressed.** A name declared as a secret but present
+ *   as a variable is a real mismatch, and the orphan is how it surfaces.
+ * - **Cross-environment is NOT suppressed.** A production-only key turning up
+ *   in staging is undeclared presence in that environment — arguably the most
+ *   interesting thing this surface can find — so it still orphans.
+ *
+ * A name declared in no GitHub scope at all orphans exactly as before, which
+ * is what keeps `--strict-orphans` worth enabling once a manifest is correct.
+ *
  * @param {object} ctx
  */
 async function probeGitHub({ manifest, environments, github, surfaces, findings, unavailability = {} }) {
@@ -1076,18 +1376,18 @@ async function probeGitHub({ manifest, environments, github, surfaces, findings,
     });
     return;
   }
-  const repoKeys = manifest.keys.filter((k) => k.residency.github?.scope === "repository");
-  const envKeys = manifest.keys.filter((k) => k.residency.github?.scope === "environment");
+  const keys = manifest.keys;
   try {
     const present = await github.repositoryNames();
     for (const kind of ["secret", "var"]) {
       findings.push(
         ...reconcileNames({
-          expected: repoKeys.filter((k) => k.residency.github.kind === kind).map((k) => k.name),
+          expected: githubNamesAt(keys, "repository", kind, null),
           present: present[kind] ?? [],
           surface: "github",
           environment: null,
           scope: `repository ${kind}s`,
+          declaredElsewhere: githubNamesAt(keys, "environment", kind, null),
         })
       );
     }
@@ -1096,11 +1396,12 @@ async function probeGitHub({ manifest, environments, github, surfaces, findings,
       for (const kind of ["secret", "var"]) {
         findings.push(
           ...reconcileNames({
-            expected: envKeys.filter((k) => k.residency.github.kind === kind).map((k) => k.name),
+            expected: githubNamesAt(keys, "environment", kind, environment),
             present: envPresent[kind] ?? [],
             surface: "github",
             environment,
             scope: `environment ${kind}s`,
+            declaredElsewhere: githubNamesAt(keys, "repository", kind, null),
           })
         );
       }
@@ -1172,6 +1473,48 @@ async function probeCloudflare({ manifest, environments, cloudflare, surfaces, f
   }
 }
 
+/**
+ * Does a key declare residency at this folder in this environment?
+ *
+ * @param {object} key   A parsed manifest key with normalized infisical residency.
+ * @param {string} folder
+ * @param {string} environment
+ * @returns {boolean}
+ */
+function residentAt(key, folder, environment) {
+  return key.infisical.folders.some((f) => f.folder === folder && f.environments.includes(environment));
+}
+
+/**
+ * Names declared in a SIBLING declared folder of the same environment.
+ *
+ * Infisical is probed once per (environment, folder) pair, so a key resident
+ * in two folders is read in two partitions — and reporting it as an orphan in
+ * the one the manifest happens not to be reconciling is the false positive the
+ * `folders` array exists to remove. Suppression is deliberately no wider:
+ *
+ * - **Cross-folder, same environment** is suppressed: that is multi-folder
+ *   residency, including the folder-import case.
+ * - **Cross-environment is NOT suppressed.** A key declared for staging only
+ *   but present in production is undeclared presence in that environment —
+ *   the most interesting thing this surface can find — so it still orphans.
+ *
+ * A name declared in no folder at all orphans exactly as before, which is what
+ * keeps `--strict-orphans` worth enabling once a manifest is correct. This is
+ * the `declaredElsewhere` treatment `probeGitHub` has had since Story #459;
+ * its absence here is why a single misplacement was reported twice.
+ *
+ * @param {object[]} managed
+ * @param {string} folder
+ * @param {string} environment
+ * @returns {string[]}
+ */
+function infisicalNamesElsewhere(managed, folder, environment) {
+  return managed
+    .filter((k) => k.infisical.folders.some((f) => f.folder !== folder && f.environments.includes(environment)))
+    .map((k) => k.name);
+}
+
 /**
  * The Infisical probe, plus the shape stage — the only place a value is read.
  *
@@ -1188,27 +1531,39 @@ async function probeInfisical({ manifest, environments, infisical, surfaces, fin
     return;
   }
   try {
-    const folders = new Set(managed.map((k) => k.infisical.folder));
+    const folders = new Set(managed.flatMap((k) => k.infisical.folders.map((f) => f.folder)));
     const shapeChecked = [];
+    // A key resident in several folders is READ in each of them, but its value
+    // is one value — so it earns at most one shape verdict per environment.
+    // Scoring it once per folder would re-introduce, in the shape stage, the
+    // very double-reporting this Story removes from the residency stage.
+    const shapeSeen = new Set();
     for (const environment of environments) {
+      // The store's own environment slug, which need not be the deploy name.
+      const slug = resolveSurfaceEnvironment(manifest, "infisical", environment);
       for (const folder of folders) {
-        const expected = managed
-          .filter((k) => k.infisical.folder === folder && k.infisical.environments.includes(environment))
-          .map((k) => k.name);
-        const present = await infisical.listNames({ environment, folder });
+        const expected = managed.filter((k) => residentAt(k, folder, environment)).map((k) => k.name);
+        const present = await infisical.listNames({ environment: slug, folder });
         findings.push(
-          ...reconcileNames({ expected, present, surface: "infisical", environment, scope: `folder ${folder}` })
+          ...reconcileNames({
+            expected,
+            present,
+            surface: "infisical",
+            environment,
+            scope: `folder ${folder}`,
+            declaredElsewhere: infisicalNamesElsewhere(managed, folder, environment),
+          })
         );
 
         // Shape stage. Values enter this scope and leave it as verdicts.
         const needShape = managed.filter(
           (k) =>
-            k.infisical.folder === folder &&
-            k.infisical.environments.includes(environment) &&
-            (k.shape || k.placeholderPattern)
+            residentAt(k, folder, environment) &&
+            (k.shape || k.placeholderPattern) &&
+            !shapeSeen.has(`${environment}\u241f${k.name}`)
         );
         if (needShape.length === 0) continue;
-        const values = await infisical.listValues({ environment, folder });
+        const values = await infisical.listValues({ environment: slug, folder });
         for (const key of needShape) {
           if (!values.has(key.name)) continue;
           const verdict = checkShape({
@@ -1217,6 +1572,7 @@ async function probeInfisical({ manifest, environments, infisical, surfaces, fin
             placeholderPattern: key.placeholderPattern,
           });
           shapeChecked.push(key.name);
+          shapeSeen.add(`${environment}\u241f${key.name}`);
           if (!verdict.ok) {
             findings.push({
               severity: "fail",

package/scripts/env-doctor.test.mjs

@@ -31,7 +31,9 @@ import { promisify } from "node:util";
 import { test } from "node:test";
 
 import {
+  KEY_SCHEMA,
   MANIFEST_SCHEMA,
+  SLUG_MAPPED_SURFACES,
   SHAPE_NAMES,
   SHAPE_VOCABULARY,
   applyExceptions,
@@ -49,6 +51,7 @@ import {
   redactUrl,
   renderReport,
   resolveScriptName,
+  resolveSurfaceEnvironment,
   runDoctor,
   runOfflineChecks,
 } from "./env-doctor.mjs";
@@ -186,6 +189,78 @@ test("parseManifest rejects a duplicate key name and an infisical env outside th
   assert.throws(() => parseManifest(badEnv), /absent from manifest.environments/);
 });
 
+test("parseManifest normalizes the single-object residency.github to a one-entry array", () => {
+  const m = parseManifest(singleWorkerManifest());
+  // The authored shape is an object; the parsed shape is always an array, so
+  // probeGitHub reads exactly one shape. `environments` defaults to all of
+  // manifest.environments, the same treatment infisical.environments gets.
+  assert.deepEqual(m.keys[0].residency.github, [
+    { scope: "environment", kind: "var", environments: ["staging", "production"] },
+  ]);
+});
+
+test("parseManifest accepts the array form and defaults environments per entry", () => {
+  const raw = singleWorkerManifest();
+  raw.keys[0].residency.github = [
+    { scope: "repository", kind: "var" },
+    { scope: "environment", kind: "var", environments: ["production"] },
+  ];
+  const m = parseManifest(raw);
+  assert.deepEqual(m.keys[0].residency.github, [
+    { scope: "repository", kind: "var", environments: ["staging", "production"] },
+    { scope: "environment", kind: "var", environments: ["production"] },
+  ]);
+});
+
+test("parseManifest rejects an residency.github environments slug outside manifest.environments", () => {
+  const raw = singleWorkerManifest();
+  raw.keys[0].residency.github = [{ scope: "environment", kind: "var", environments: ["preview"] }];
+  assert.throws(() => parseManifest(raw), (err) => {
+    assert.match(err.message, /absent from manifest.environments/);
+    assert.match(err.message, /PUBLIC_SITE_URL/);
+    return true;
+  });
+});
+
+test("parseManifest rejects environments on a repository-scope entry rather than ignoring it", () => {
+  // Silently ignoring it is how an author comes to believe they scoped
+  // something they did not — the same fail-closed posture as an unknown shape.
+  const raw = singleWorkerManifest();
+  raw.keys[0].residency.github = [{ scope: "repository", kind: "var", environments: ["production"] }];
+  assert.throws(() => parseManifest(raw), (err) => {
+    assert.match(err.message, /meaningful only under scope "environment"/);
+    assert.match(err.message, /PUBLIC_SITE_URL/);
+    return true;
+  });
+});
+
+test("parseManifest rejects a duplicate (scope, kind) pair and an empty residency.github array", () => {
+  const dup = singleWorkerManifest();
+  dup.keys[0].residency.github = [
+    { scope: "environment", kind: "var" },
+    { scope: "environment", kind: "var", environments: ["production"] },
+  ];
+  assert.throws(() => parseManifest(dup), (err) => {
+    assert.match(err.message, /repeats the \(scope, kind\) pair "environment\/var"/);
+    assert.match(err.message, /PUBLIC_SITE_URL/);
+    return true;
+  });
+
+  const empty = singleWorkerManifest();
+  empty.keys[0].residency.github = [];
+  assert.throws(() => parseManifest(empty), /must not be an empty array/);
+});
+
+test("parseManifest still rejects a malformed scope and kind under both authored shapes", () => {
+  const objForm = singleWorkerManifest();
+  objForm.keys[0].residency.github = { scope: "org", kind: "var" };
+  assert.throws(() => parseManifest(objForm), /\.scope must be "environment" or "repository"/);
+
+  const arrForm = singleWorkerManifest();
+  arrForm.keys[0].residency.github = [{ scope: "repository", kind: "file" }];
+  assert.throws(() => parseManifest(arrForm), /residency\.github\[0\]\.kind must be "secret" or "var"/);
+});
+
 test("resolveScriptName substitutes {env} per environment", () => {
   assert.equal(resolveScriptName("acme-site-{env}", "staging"), "acme-site-staging");
   assert.equal(resolveScriptName("acme-site-{env}", "production"), "acme-site-production");
@@ -458,6 +533,214 @@ test("a non-404 probe failure becomes an error surface and exits 1 — never 'no
   }
 });
 
+// ---------------------------------------------------------------------------
+// GitHub residency — dual scope and per-environment presence (Story #459)
+// ---------------------------------------------------------------------------
+
+/**
+ * A manifest with no workers and no local residency, so the offline arm over an
+ * empty repo root contributes no findings and every finding under test comes
+ * from the GitHub probe.
+ */
+function githubOnlyManifest(github) {
+  return parseManifest({
+    environments: ["staging", "production"],
+    keys: [{ name: "SHARED_TOKEN", kind: "secret", sensitivity: "secret", residency: { local: null, github } }],
+  });
+}
+
+/** Mock the two GitHub probe calls from a `{repository, staging, production}` map. */
+function githubProbe(present) {
+  const at = (slot) => ({ secret: [], var: [], ...(present[slot] ?? {}) });
+  return {
+    repositoryNames: async () => at("repository"),
+    environmentNames: async (environment) => at(environment),
+  };
+}
+
+async function githubFindings({ manifest, present, environments = ["staging", "production"] }) {
+  const root = makeRepo({});
+  try {
+    const report = await runDoctor({ manifest, repoRoot: root, environments, github: githubProbe(present) });
+    return report.findings.filter((f) => f.surface === "github");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const DUAL_SCOPE = [
+  { scope: "repository", kind: "secret" },
+  { scope: "environment", kind: "secret" },
+];
+
+test("a dual-scope key present at both scopes reports no finding", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest(DUAL_SCOPE),
+    present: {
+      repository: { secret: ["SHARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("a dual-scope key absent from one scope reports a missing naming that scope only", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest(DUAL_SCOPE),
+    present: {
+      repository: { secret: [] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "missing");
+  assert.equal(findings[0].key, "SHARED_TOKEN");
+  assert.equal(findings[0].environment, null);
+  assert.match(findings[0].detail, /repository secrets/);
+});
+
+test("a dual-scope key absent from one environment reports a missing naming that environment only", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest(DUAL_SCOPE),
+    present: {
+      repository: { secret: ["SHARED_TOKEN"] },
+      staging: { secret: [] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "missing");
+  assert.equal(findings[0].environment, "staging");
+});
+
+test("an environments-scoped entry reports no missing for an environment it never names", async () => {
+  // The motivating case: a production-only analytics token whose staging
+  // counterpart is meant to resolve empty. That is design, not drift.
+  const manifest = githubOnlyManifest([{ scope: "environment", kind: "secret", environments: ["production"] }]);
+  assert.deepEqual(
+    await githubFindings({ manifest, present: { production: { secret: ["SHARED_TOKEN"] } } }),
+    []
+  );
+
+  const missing = await githubFindings({ manifest, present: {} });
+  assert.equal(missing.length, 1, "production still fails when it lacks the key");
+  assert.equal(missing[0].kind, "missing");
+  assert.equal(missing[0].environment, "production");
+});
+
+test("a key declared only at environment scope is not a repository-level orphan", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret" }]),
+    present: {
+      repository: { secret: ["SHARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("suppression is cross-scope only — an undeclared name still orphans", async () => {
+  // The half that keeps --strict-orphans worth enabling: nothing about the
+  // suppression hides a name the manifest never declared anywhere.
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret" }]),
+    present: {
+      repository: { secret: ["SHARED_TOKEN", "UNDECLARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.equal(findings[0].key, "UNDECLARED_TOKEN");
+  assert.equal(findings[0].environment, null);
+});
+
+test("suppression does not cross kind — a secret declared, a variable present, still orphans", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret" }]),
+    present: {
+      repository: { var: ["SHARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.match(findings[0].detail, /repository vars/);
+});
+
+test("suppression does not cross environment — a production-only key found in staging orphans", async () => {
+  // Undeclared presence in the wrong environment is the most interesting thing
+  // this surface can find, so the cross-scope rule must not reach it.
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret", environments: ["production"] }]),
+    present: {
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.equal(findings[0].environment, "staging");
+});
+
+test("the single-object residency.github form yields exactly the findings it did before", async () => {
+  // The regression case, over the unchanged existing fixture: both keys are
+  // authored as single objects at environment scope, so a repo-level probe
+  // holding neither must produce two per-environment missings and nothing else.
+  const root = makeRepo(CONSISTENT_REPO);
+  try {
+    const report = await runDoctor({
+      manifest: parseManifest(singleWorkerManifest()),
+      repoRoot: root,
+      environments: ["staging", "production"],
+      github: githubProbe({
+        staging: { var: ["PUBLIC_SITE_URL"], secret: ["TURSO_AUTH_TOKEN"] },
+        production: { var: ["PUBLIC_SITE_URL"] },
+      }),
+    });
+    const gh = report.findings.filter((f) => f.surface === "github");
+    assert.equal(gh.length, 1);
+    assert.deepEqual(
+      { kind: gh[0].kind, key: gh[0].key, environment: gh[0].environment },
+      { kind: "missing", key: "TURSO_AUTH_TOKEN", environment: "production" }
+    );
+    assert.equal(report.surfaces.find((s) => s.surface === "github").status, "checked");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("declaredElsewhere suppresses only orphans, never a missing", async () => {
+  // The new argument is opt-in and orphan-only, so the cloudflare and infisical
+  // call sites that omit it cannot change behaviour.
+  const suppressed = reconcileNames({
+    expected: ["A"],
+    present: ["B"],
+    surface: "github",
+    environment: null,
+    declaredElsewhere: ["A", "B"],
+  });
+  assert.deepEqual(
+    suppressed.map((f) => [f.kind, f.key]),
+    [["missing", "A"]]
+  );
+  assert.deepEqual(reconcileNames({ expected: [], present: ["B"], surface: "github", environment: null }), [
+    {
+      severity: "orphan",
+      kind: "orphan",
+      key: "B",
+      surface: "github",
+      environment: null,
+      detail: "present in github but declared by no manifest key",
+    },
+  ]);
+});
+
 test("the Cloudflare probe resolves {env} in scriptName once per environment", async () => {
   const root = makeRepo(CONSISTENT_REPO);
   const asked = [];
@@ -763,6 +1046,388 @@ test("no secret VALUE reaches stdout or stderr on a real run against a mock Infi
   }
 });
 
+// ---------------------------------------------------------------------------
+// Infisical environment slugs and folder residency (Story #464)
+// ---------------------------------------------------------------------------
+
+/**
+ * A manifest with no local residency and no GitHub residency, so every finding
+ * under test comes from the Infisical probe. One Worker is kept so the
+ * Cloudflare surface can be asserted to keep the DEPLOY name while Infisical
+ * is asked for the mapped slug.
+ */
+function infisicalOnlyManifest(infisical, { environmentSlugs, keys } = {}) {
+  return parseManifest({
+    environments: ["staging", "production"],
+    ...(environmentSlugs ? { environmentSlugs } : {}),
+    workers: { site: { scriptName: "acme-site-{env}" } },
+    keys:
+      keys ??
+      [
+        {
+          name: "SHARED_TOKEN",
+          kind: "secret",
+          sensitivity: "secret",
+          residency: { local: null, github: null, cloudflare: null },
+          infisical,
+        },
+      ],
+  });
+}
+
+/**
+ * Run the Infisical probe against a `{ "<environment-slug><folder>": [names] }`
+ * map, recording every (environment, folder) pair the client was asked for.
+ * The map is keyed by the slug the CLIENT sees, which is the whole point: a
+ * remapped environment must be looked up under its store slug.
+ */
+async function infisicalRun({ manifest, present, environments = ["staging", "production"], cloudflare = null }) {
+  const root = makeRepo({});
+  const asked = [];
+  try {
+    const report = await runDoctor({
+      manifest,
+      repoRoot: root,
+      environments,
+      cloudflare,
+      infisical: {
+        listNames: async ({ environment, folder }) => {
+          asked.push(`${environment}${folder}`);
+          return present[`${environment}${folder}`] ?? [];
+        },
+        listValues: async () => new Map(),
+      },
+    });
+    return { asked, findings: report.findings.filter((f) => f.surface === "infisical"), report };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test("a remapped Infisical slug is probed at the slug while Cloudflare keeps the deploy name", async () => {
+  // The motivating case: deploy environments are staging/production, but the
+  // Infisical project's slugs are staging/prod. Before this, `production`
+  // reached Infisical verbatim and 404'd the whole surface into `error`.
+  const scripts = [];
+  const { asked } = await infisicalRun({
+    manifest: infisicalOnlyManifest(
+      { folder: "/shared" },
+      { environmentSlugs: { infisical: { production: "prod" } } }
+    ),
+    present: { "staging/shared": ["SHARED_TOKEN"], "prod/shared": ["SHARED_TOKEN"] },
+    cloudflare: {
+      secretNames: async (scriptName) => {
+        scripts.push(scriptName);
+        return [];
+      },
+    },
+  });
+
+  assert.deepEqual(asked, ["staging/shared", "prod/shared"]);
+  assert.ok(!asked.some((a) => a.startsWith("production")), "the deploy name must not reach Infisical");
+  // The Cloudflare surface resolves {env} from the DEPLOY name, unmapped —
+  // which is why it needs no slug map of its own.
+  assert.deepEqual(scripts, []);
+});
+
+test("a manifest declaring a Cloudflare secret still resolves {env} from the unmapped deploy name", async () => {
+  const scripts = [];
+  await infisicalRun({
+    manifest: infisicalOnlyManifest(undefined, {
+      environmentSlugs: { infisical: { production: "prod" } },
+      keys: [
+        {
+          name: "SHARED_TOKEN",
+          kind: "secret",
+          sensitivity: "secret",
+          residency: { local: null, github: null, cloudflare: { workers: ["site"], kind: "secret" } },
+          infisical: { folder: "/shared" },
+        },
+      ],
+    }),
+    present: {},
+    cloudflare: {
+      secretNames: async (scriptName) => {
+        scripts.push(scriptName);
+        return ["SHARED_TOKEN"];
+      },
+    },
+  });
+  assert.deepEqual(scripts, ["acme-site-staging", "acme-site-production"]);
+});
+
+test("environmentSlugs rejects a surface that is not slug-mapped, and names it", () => {
+  assert.throws(
+    () =>
+      infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { cloudflare: { production: "prod" } } }),
+    (err) => {
+      assert.match(err.message, /"cloudflare" is not a slug-mapped surface/);
+      assert.match(err.message, /infisical/);
+      // The message must say WHY, or the author re-files the same request.
+      assert.match(err.message, /scriptName/);
+      return true;
+    }
+  );
+});
+
+test("environmentSlugs rejects an unmapped environment and a slug that is not a non-empty string", () => {
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: { preview: "prev" } } }),
+    /maps "preview", absent from manifest.environments/
+  );
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: { production: "" } } }),
+    /must be a non-empty slug string/
+  );
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: { production: 7 } } }),
+    /must be a non-empty slug string/
+  );
+  assert.throws(
+    () => infisicalOnlyManifest({ folder: "/" }, { environmentSlugs: { infisical: ["prod"] } }),
+    /must be an object mapping environment -> slug/
+  );
+});
+
+test("with no environmentSlugs every environment resolves to itself", async () => {
+  const manifest = infisicalOnlyManifest({ folder: "/shared" });
+  // The container is normalized to a total-but-empty map, so no caller has to
+  // distinguish "absent" from "empty".
+  assert.deepEqual(manifest.environmentSlugs, { infisical: {} });
+  assert.equal(resolveSurfaceEnvironment(manifest, "infisical", "production"), "production");
+  const { asked } = await infisicalRun({ manifest, present: { "staging/shared": ["SHARED_TOKEN"] } });
+  assert.deepEqual(asked, ["staging/shared", "production/shared"]);
+});
+
+test("parseManifest normalizes the single-object infisical form to a one-entry folders array", () => {
+  // The pre-#464 authored shape, parsed: one shape reaches probeInfisical, the
+  // same treatment residency.github received in #459.
+  const m = infisicalOnlyManifest({ folder: "/shared", environments: ["production"] });
+  assert.deepEqual(m.keys[0].infisical, { folders: [{ folder: "/shared", environments: ["production"] }] });
+
+  const defaulted = infisicalOnlyManifest({ folder: "/shared" });
+  assert.deepEqual(defaulted.keys[0].infisical, {
+    folders: [{ folder: "/shared", environments: ["staging", "production"] }],
+  });
+});
+
+test("the folders array accepts bare paths and per-entry environments", () => {
+  const m = infisicalOnlyManifest({
+    folders: ["/shared", { folder: "/github", environments: ["staging"] }],
+  });
+  assert.deepEqual(m.keys[0].infisical, {
+    folders: [
+      { folder: "/shared", environments: ["staging", "production"] },
+      { folder: "/github", environments: ["staging"] },
+    ],
+  });
+});
+
+test("a key resident in two folders and present in both reports no finding", async () => {
+  // The folder-import case: /cloudflare imports /shared, so the value is
+  // genuinely readable through both. Both statements are true.
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({ folders: ["/shared", "/cloudflare"] }),
+    present: {
+      "staging/shared": ["SHARED_TOKEN"],
+      "staging/cloudflare": ["SHARED_TOKEN"],
+      "production/shared": ["SHARED_TOKEN"],
+      "production/cloudflare": ["SHARED_TOKEN"],
+    },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("a misplacement across two declared folders is reported ONCE, as the missing", async () => {
+  // Declared in /shared, actually resident in /cloudflare. Before #464 this
+  // was two findings for one fact — a missing AND an orphan — and the orphan
+  // was unsuppressable by an exception, so --strict-orphans could never go
+  // green on a manifest that was merely imprecise about placement.
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({ folders: ["/shared", "/cloudflare"] }),
+    present: {
+      "staging/cloudflare": ["SHARED_TOKEN"],
+      "production/cloudflare": ["SHARED_TOKEN"],
+    },
+    environments: ["staging"],
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "missing");
+  assert.equal(findings[0].key, "SHARED_TOKEN");
+  assert.match(findings[0].detail, /folder \/shared/);
+  assert.equal(
+    findings.filter((f) => f.kind === "orphan").length,
+    0,
+    "the sibling declared folder must not also orphan the same key"
+  );
+});
+
+test("suppression does not cross environment — a staging-only key found in production orphans", async () => {
+  // SHARED_TOKEN is declared in /github for staging only. Finding it in
+  // /shared in production is undeclared presence in that environment, which
+  // is the most interesting thing this surface can report.
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({
+      folders: [{ folder: "/github", environments: ["staging"] }, { folder: "/shared", environments: ["staging"] }],
+    }),
+    present: {
+      "staging/github": ["SHARED_TOKEN"],
+      "staging/shared": ["SHARED_TOKEN"],
+      "production/shared": ["SHARED_TOKEN"],
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.equal(findings[0].environment, "production");
+});
+
+test("a per-environment folder entry reports no missing for an environment it never names", async () => {
+  const { findings } = await infisicalRun({
+    manifest: infisicalOnlyManifest({ folders: [{ folder: "/operator", environments: ["production"] }] }),
+    present: { "production/operator": ["SHARED_TOKEN"] },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("infisical folder residency fails closed on every malformed shape", () => {
+  const bad = (infisical) => () => infisicalOnlyManifest(infisical);
+  assert.throws(bad({ folders: [] }), /folders must be a non-empty array/);
+  assert.throws(bad({ folders: ["/shared", "/shared"] }), /repeats the folder "\/shared"/);
+  assert.throws(bad({ folders: [{ folder: "/s", environments: ["preview"] }] }), /absent from manifest.environments/);
+  assert.throws(bad({ folder: "/s", folders: ["/t"] }), /declares both "folder" and "folders"/);
+  assert.throws(bad({ folders: ["/s"], environments: ["staging"] }), /meaningful only beside a single "folder"/);
+  assert.throws(bad({}), /must declare "folder" or "folders"/);
+  assert.throws(bad({ folders: [""] }), /must be a non-empty folder path string/);
+  assert.throws(bad({ folders: [42] }), /must be a folder path string or \{folder, environments\}/);
+  assert.throws(bad("nope"), /must be "unmanaged", \{folder, environments\} or \{folders: \[\.\.\.\]\}/);
+  // Unchanged from before #464: the single-object form's own env validation.
+  assert.throws(bad({ folder: "/s", environments: ["preview"] }), /absent from manifest.environments/);
+});
+
+test("a multi-folder key with a shape earns ONE verdict per environment, not one per folder", async () => {
+  // A key resident in two folders is READ twice, but it is one value — so
+  // scoring it per folder would re-introduce double-reporting in the shape
+  // stage, the very defect #464 removes from the residency stage.
+  const root = makeRepo({});
+  try {
+    const manifest = infisicalOnlyManifest(undefined, {
+      keys: [
+        {
+          name: "SHARED_TOKEN",
+          kind: "var",
+          sensitivity: "public",
+          residency: { local: null, github: null, cloudflare: null },
+          infisical: { folders: ["/shared", "/cloudflare"] },
+          shape: "url",
+        },
+      ],
+    });
+    const report = await runDoctor({
+      manifest,
+      repoRoot: root,
+      environments: ["staging"],
+      infisical: {
+        listNames: async () => ["SHARED_TOKEN"],
+        listValues: async () => new Map([["SHARED_TOKEN", "example.test"]]),
+      },
+    });
+    const shapeFails = report.findings.filter((f) => f.kind === "shape-fail");
+    assert.equal(shapeFails.length, 1, "one value, one verdict");
+    assert.equal(shapeFails[0].key, "SHARED_TOKEN");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("MANIFEST_SCHEMA and KEY_SCHEMA describe the slug container and the folders array", () => {
+  assert.ok(Object.hasOwn(MANIFEST_SCHEMA, "environmentSlugs"));
+  assert.match(MANIFEST_SCHEMA.environmentSlugs, /infisical/);
+  assert.match(KEY_SCHEMA.infisical, /folders/);
+  assert.deepEqual(SLUG_MAPPED_SURFACES, ["infisical"]);
+});
+
+test("the documented manifest schema block names the new shapes", () => {
+  // The script exports the schema so the doc and the code describe one shape;
+  // this asserts the DOC kept its half of that bargain.
+  const doc = readFileSync(join(HERE, "..", "docs", "reusable-workflows.md"), "utf8");
+  assert.match(doc, /"environmentSlugs"/);
+  assert.match(doc, /"folders"/);
+});
+
+test("no secret VALUE reaches stdout or stderr through the remapped-slug, multi-folder path", async () => {
+  // The values-safety guarantee, re-asserted over the shapes #464 adds: a
+  // remapped environment slug and a key resident in two folders. Same
+  // low-entropy dictionary canaries as the sibling leak test, for the same
+  // reason (a key-shaped fixture is a true positive for gitleaks).
+  const INJECTED = {
+    PUBLIC_SITE_URL: "example.test/no-scheme-here",
+    TURSO_AUTH_TOKEN: "second-canary-that-must-never-be-printed",
+  };
+  const requested = [];
+
+  const server = createServer((req, res) => {
+    if (req.method === "POST" && req.url.startsWith("/api/v1/auth/universal-auth/login")) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ accessToken: "mock-token", expiresIn: 3600, tokenType: "Bearer" }));
+      return;
+    }
+    if (req.url.startsWith("/api/v4/secrets")) {
+      const params = new URL(req.url, "http://localhost").searchParams;
+      requested.push(`${params.get("environment")}${params.get("secretPath")}`);
+      const withValues = params.get("viewSecretValue") === "true";
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          secrets: Object.entries(INJECTED).map(([secretKey, secretValue]) => ({
+            secretKey,
+            ...(withValues ? { secretValue } : {}),
+          })),
+        })
+      );
+      return;
+    }
+    res.writeHead(404).end("{}");
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  const site = `http://127.0.0.1:${server.address().port}`;
+
+  const raw = singleWorkerManifest();
+  raw.environmentSlugs = { infisical: { production: "prod" } };
+  for (const key of raw.keys) key.infisical = { folders: ["/", "/shared"] };
+
+  const root = makeRepo(CONSISTENT_REPO);
+  const manifestPath = join(root, "env.manifest.json");
+  writeFileSync(manifestPath, JSON.stringify(raw));
+
+  try {
+    const run = await runCli(
+      [
+        "--manifest", manifestPath,
+        "--repo-root", root,
+        "--environments", "production",
+        "--infisical-project", "proj-1",
+        "--infisical-site", site,
+        "--json",
+      ],
+      { env: { INFISICAL_CLIENT_ID: "id", INFISICAL_CLIENT_SECRET: "sec", ENV_DRIFT_GITHUB_TOKEN: "", CLOUDFLARE_API_TOKEN: "" } }
+    );
+
+    // End-to-end proof that the slug reaches the wire through the real CLI:
+    // every request names `prod`, never the `production` deploy name.
+    assert.ok(requested.length > 0, "the mock store should have been asked for something");
+    assert.deepEqual([...new Set(requested.map((r) => r.split("/")[0]))], ["prod"]);
+
+    const captured = run.stdout + run.stderr;
+    assert.ok(captured.includes("PUBLIC_SITE_URL"), "the failing key's NAME should be reported");
+    for (const [name, value] of Object.entries(INJECTED)) {
+      assert.ok(!captured.includes(value), `the VALUE of ${name} leaked into the doctor's output`);
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+    await new Promise((r) => server.close(r));
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Shipped workflow shape
 // ---------------------------------------------------------------------------