@davidvornholt/standards 0.22.2 → 0.24.0

package/README.md

@@ -35,7 +35,7 @@ standards poller --print-units --config <path>
 
 `github --check` compares the live GitHub repository (including the canonical squash-only repository settings, rulesets, and declared labels) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges that declared state. The canonical declaration enables squash while disabling merge commits and rebases, and its default-branch ruleset independently allows only squash. Undeclared live labels remain untouched, while undeclared repository-owned rulesets are removed. `check` runs the same comparison whenever `.github/settings.json` is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. The canonical workflow sets `STANDARDS_SKIP_GITHUB_CHECK=true` only in its unprivileged quality step because its `check` aggregator job runs the live comparison with its own workflow token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either `check`'s live phase or `github --check`; `github --apply` is never skipped. `--apply` re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.
 
-`structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. `check` includes `structure`, so these rules gate every consumer PR.
+`structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. Every repo-owned workspace must carry a non-empty `README.md` as the prerequisite for documenting its configuration and secrets; the gate checks presence, not content completeness. Canonical workspaces synced from the standards template (the `apps/*` or `packages/*` entries in `sync-standards.json`) are exempt under the consumer profile because a consumer cannot fix them locally, and an unreadable or symlinked `sync-standards.json` fails the gate rather than guessing which workspaces are repo-owned. `structure` also validates the CI secrets contract without decrypting anything, using the plaintext key structure SOPS leaves in place: `secrets/ci.yaml` must be a contained regular file with complete SOPS metadata, every business leaf value must have a complete `ENC[AES256_GCM,...]` envelope (a rejected leaf is reported by key path only, never by value), and the repo-owned `secrets/ci.example.yaml` must mirror the structural business-key paths in both directions with plaintext placeholders. `ci.ntfy_topic_url` is always required for `Notify pause`. `ci.broker_app.app_id` and `ci.broker_app.private_key` are required for the weekly `Standards sync` workflow unless the validated `sync-standards.local.json` policy sets `"autoSync": false`. Required workflow values must each be one encrypted scalar because the resolver requires a string. The secrets files, workspace READMEs, and sync manifest cannot be supplied through symlinks. `check` includes `structure`, so these rules gate every consumer PR.
 
 `poller` runs one tick of the fix poller: host-level automation that turns maintainer-approved GitHub issues into verified draft PRs and maintainer-approved draft PRs into completed review-fix cycles, using headless Codex runs. All workflow state lives in GitHub labels, comments, and draft PRs (the labels are canonical declared settings — see `github --apply`), so ticks are stateless, re-runnable, and safe to schedule from any host. A tick claims work by label (`fix-in-progress` / `review-in-progress`), releases claims stale for longer than `staleClaimHours`, and fails loudly — a red tick means jobs stalled, never silence. A separate acknowledgement tick validates pending approvals and posts one deduplicated queued message per approval generation; it never claims or starts work, so it can keep giving maintainers prompt feedback while the worker is occupied. When a worker claims a request, it posts a concise start message. The exact approval and distributed claim records remain in hidden comment metadata, and losing claim contenders remove their duplicate comments. Trust is verified per event, not per configuration: the approval labels (`approved-for-fix`, `approved-for-review`) only count when the applying user holds the `admin` or `maintain` role, bind to the exact approved issue revision or PR head, and are revalidated before publication; only admin/maintain comments are treated as answers to agent questions. Approved Codex runs inherit the poller's GitHub token and use authenticated `gh` for relevant reads and comments; review runs also maintain the PR review ledger, apply authorized title or body edits, post fix threads, and file deferred findings directly. The run works in a throwaway git worktree, grants Codex write access to that worktree and its exact Git common directory so commits can update the linked repository metadata, and hands results back through a structured outcome file. The poller then verifies the approved head, commits, and protected paths before pushing or publishing; it replies to and resolves agent-posted fix threads only after the reviewed head is pushed, and it alone changes protocol labels, posts the final report, and flips a reviewed draft ready, while required CI remains the quality gate. If publishing a sealed fix or review result fails, the poller releases only its owned in-progress claim and keeps the approval and sealed output, so the next worker tick retries publication without another Codex run. Sealed review plans from the earlier protocol are rejected and their output branches are ignored, so the review reruns on a fresh protocol-versioned branch rather than silently dropping legacy deferred work. Host mutation is declarative-only: `--print-units` emits four correctly escaped systemd units for the polling host's infrastructure repository to adapt and deploy: the worker service and timer plus an independent lightweight acknowledgement service and timer. That repository owns the service identity, writable HOME, PATH, authenticated `gh`, lingering, and deployment. The worker service's tick budget (`TimeoutStartSec`) is derived from `maxJobsPerTick` × `runTimeoutMinutes` plus overhead, so re-render and redeploy the units after changing either value.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.22.2",
+  "version": "0.24.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,7 @@
     "LICENSE",
     "README.md",
     "src/cli.ts",
+    "src/contained-path.ts",
     "src/creds-add.ts",
     "src/creds-add-collision.ts",
     "src/creds-add-cloudflare-commit.ts",
@@ -109,6 +110,7 @@
     "src/github-settings-merge.ts",
     "src/github-settings-parse.ts",
     "src/github-settings.ts",
+    "src/json-file.ts",
     "src/managed-files.ts",
     "src/managed-path-ownership.ts",
     "src/poller-approval.ts",
@@ -158,8 +160,13 @@
     "src/sops-exec.ts",
     "src/structure-check.ts",
     "src/structure-profile.ts",
+    "src/structure-readme.ts",
+    "src/structure-secret-document.ts",
     "src/structure-script.ts",
+    "src/structure-secrets.ts",
+    "src/structure-sops-envelope.ts",
     "src/structure-workspace.ts",
+    "src/sync-policy.ts",
     "src/yaml-emit.ts",
     "src/yaml-parse.ts"
   ],

package/src/cli.ts

@@ -29,7 +29,7 @@ import { runDevEnv } from './dev-env';
 import { CANONICAL_SETTINGS_FILE, LOCAL_SETTINGS_FILE } from './github-api';
 import { runGithubApply, runGithubCheck } from './github-commands';
 import { loadGithubSettings } from './github-settings';
-import { isNonEmptyString, isRecord } from './github-settings-parse';
+import { isRecord } from './github-settings-parse';
 import {
   findManagedFilesContainingBiomeDirectiveToken,
   inspectManagedPath,
@@ -46,6 +46,11 @@ import { runPollerCommand } from './poller-commands';
 import { collectStructureProblems } from './structure-check';
 import type { StructureProfile } from './structure-profile';
 import { hasSafeCommand } from './structure-script';
+import {
+  inspectSyncPolicy,
+  readSyncPolicy,
+  selectedSyncRef,
+} from './sync-policy';
 
 const DEFAULT_UPSTREAM = 'github:davidvornholt/standards';
 
@@ -943,7 +948,7 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
     );
   }
 
-  problems.push(...(await inspectPolicy(consumer)));
+  problems.push(...(await inspectSyncPolicy(consumer)));
 
   if (problems.length > 0) {
     console.error(
@@ -1181,7 +1186,9 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
 };
 
 // Canonical monorepo structure gate: workspace and root script shapes,
-// internal versioning, `exports`, tsconfig inheritance, and a11y wiring.
+// internal versioning, `exports`, tsconfig inheritance, a11y wiring,
+// repo-owned workspace READMEs, and the undecrypted CI secrets contract
+// (SOPS shape mirroring plus the keys the synced workflows require).
 // The `source` profile instead pins the standards template repository's own
 // deliberate exceptions to the consumer contract.
 const runStructure = async (
@@ -1229,82 +1236,6 @@ const runGithubCheckGate = (consumer: string): Promise<boolean> => {
   return runGithubCheck(consumer);
 };
 
-// Consumer-owned sync policy, checked in next to the canonical (read-only)
-// standards-sync workflow it configures — versioned and reviewable, unlike
-// repository Actions variables. All fields are optional; a missing file means
-// the defaults (track main, weekly auto-sync on).
-//   autoSync  false skips the scheduled workflow run; local CLI runs remain
-//             the deliberate sync path.
-//   ref       tag, branch, or full commit sha to sync from instead of main.
-const POLICY_FILE = 'sync-standards.local.json';
-const LINE_BREAK = /[\r\n]/u;
-
-type Policy = {
-  readonly autoSync?: boolean;
-  readonly ref?: string;
-};
-
-const parsePolicy = (parsed: unknown): Policy => {
-  if (!isRecord(parsed)) {
-    throw new Error(`${POLICY_FILE} must be a JSON object`);
-  }
-  const unsupportedFields = Object.keys(parsed).filter(
-    (field) => field !== 'autoSync' && field !== 'ref',
-  );
-  if (unsupportedFields.length > 0) {
-    throw new Error(
-      `${POLICY_FILE} contains unsupported field(s): ${unsupportedFields.join(', ')}`,
-    );
-  }
-  if (parsed.autoSync !== undefined && typeof parsed.autoSync !== 'boolean') {
-    throw new Error(`${POLICY_FILE} "autoSync" must be a boolean`);
-  }
-  if (
-    parsed.ref !== undefined &&
-    (!isNonEmptyString(parsed.ref) || LINE_BREAK.test(parsed.ref))
-  ) {
-    throw new Error(
-      `${POLICY_FILE} "ref" must be a non-empty single-line string`,
-    );
-  }
-  return { autoSync: parsed.autoSync, ref: parsed.ref };
-};
-
-const readPolicy = async (consumer: string): Promise<Policy> => {
-  const raw = await readTextIfPresent(join(consumer, POLICY_FILE));
-  if (raw === null) {
-    return {};
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`${POLICY_FILE} must contain valid JSON`, { cause: error });
-  }
-  return parsePolicy(parsed);
-};
-
-const inspectPolicy = async (
-  consumer: string,
-): Promise<ReadonlyArray<string>> => {
-  try {
-    await readPolicy(consumer);
-    return [];
-  } catch (error) {
-    return [error instanceof Error ? error.message : String(error)];
-  }
-};
-
-// Policy validation is unconditional once the file exists. Selection happens
-// afterward: explicit refs win for remote sources, while local paths are used
-// as-is and ignore only the already-validated policy ref.
-const selectedRef = (
-  src: string,
-  explicitRef: string | undefined,
-  policy: Policy,
-): string | undefined =>
-  existsSync(src) ? explicitRef : (explicitRef ?? policy.ref);
-
 const runInitCommand = async (
   consumer: string,
   from: string | undefined,
@@ -1321,8 +1252,8 @@ const runInitCommand = async (
     return;
   }
   const src = from ?? DEFAULT_UPSTREAM;
-  const policy = await readPolicy(consumer);
-  const source = resolveSource(src, selectedRef(src, ref, policy));
+  const policy = await readSyncPolicy(consumer);
+  const source = resolveSource(src, selectedSyncRef(src, ref, policy));
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),
@@ -1343,8 +1274,8 @@ const runSyncCommand = async (
     join(consumer, 'sync-standards.json'),
   );
   const src = from ?? consumerManifest.upstream;
-  const policy = await readPolicy(consumer);
-  const source = resolveSource(src, selectedRef(src, ref, policy));
+  const policy = await readSyncPolicy(consumer);
+  const source = resolveSource(src, selectedSyncRef(src, ref, policy));
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),

package/src/contained-path.ts

@@ -0,0 +1,59 @@
+import { lstatSync, realpathSync, type Stats } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+
+const isContained = (root: string, candidate: string): boolean => {
+  const fromRoot = relative(root, candidate);
+  return (
+    fromRoot !== '' &&
+    !isAbsolute(fromRoot) &&
+    fromRoot !== '..' &&
+    !fromRoot.startsWith(`..${sep}`)
+  );
+};
+
+const matchesKind = (stat: Stats, kind: 'directory' | 'file'): boolean =>
+  kind === 'file' ? stat.isFile() : stat.isDirectory();
+
+// Validate the path component by component without following symlinks. Callers
+// may read it only after this succeeds; the remaining check/read race is inside
+// the package's non-hostile maintainer threat model.
+export const isContainedPath = (
+  consumer: string,
+  rel: string,
+  kind: 'directory' | 'file',
+): boolean => {
+  try {
+    if (
+      isAbsolute(rel) ||
+      rel.includes('\\') ||
+      lstatSync(consumer).isSymbolicLink()
+    ) {
+      return false;
+    }
+    const parts = rel.split('/');
+    if (
+      parts.length === 0 ||
+      parts.some((part) => ['', '.', '..'].includes(part))
+    ) {
+      return false;
+    }
+    const root = realpathSync(consumer);
+    let candidate = consumer;
+    for (const [index, part] of parts.entries()) {
+      candidate = join(candidate, part);
+      const stat = lstatSync(candidate);
+      const final = index === parts.length - 1;
+      const expectedKind = final ? kind : 'directory';
+      if (
+        stat.isSymbolicLink() ||
+        !isContained(root, realpathSync(candidate)) ||
+        !matchesKind(stat, expectedKind)
+      ) {
+        return false;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+};

package/src/creds-dest.ts

@@ -4,7 +4,8 @@
 
 import { lstatSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { isContainedSopsPath, parseSopsKeyPath } from './creds-sops-structure';
+import { isContainedPath } from './contained-path';
+import { parseSopsKeyPath } from './creds-sops-structure';
 import {
   type BrokerStore,
   type CloudflareBrokerAccount,
@@ -71,7 +72,7 @@ export const assertWritableSopsPath = (
 const isYamlSecrets = (name: string): boolean =>
   name.endsWith('.yaml') && !name.endsWith('.example.yaml');
 const listDir = (consumer: string, rel: string): ReadonlyArray<string> => {
-  if (!isContainedSopsPath(consumer, rel, 'directory')) {
+  if (!isContainedPath(consumer, rel, 'directory')) {
     return [];
   }
   try {
@@ -82,7 +83,7 @@ const listDir = (consumer: string, rel: string): ReadonlyArray<string> => {
 };
 const isHostTargetCandidate = (consumer: string, name: string): boolean => {
   const rel = `infra/hosts/${name}`;
-  if (isContainedSopsPath(consumer, rel, 'directory')) {
+  if (isContainedPath(consumer, rel, 'directory')) {
     return listDir(consumer, rel).includes('secrets.yaml');
   }
   try {

package/src/creds-sops-structure.ts

@@ -1,5 +1,3 @@
-import { lstatSync, realpathSync, type Stats } from 'node:fs';
-import { isAbsolute, join, relative, sep } from 'node:path';
 import {
   isAlias,
   isMap,
@@ -42,57 +40,6 @@ export const parseSopsKeyPath = (
     ? segments
     : null;
 };
-const isContained = (root: string, candidate: string): boolean => {
-  const fromRoot = relative(root, candidate);
-  return (
-    fromRoot !== '' &&
-    !isAbsolute(fromRoot) &&
-    fromRoot !== '..' &&
-    !fromRoot.startsWith(`..${sep}`)
-  );
-};
-const matchesKind = (stat: Stats, kind: 'directory' | 'file'): boolean =>
-  kind === 'file' ? stat.isFile() : stat.isDirectory();
-export const isContainedSopsPath = (
-  consumer: string,
-  rel: string,
-  kind: 'directory' | 'file',
-): boolean => {
-  try {
-    if (
-      isAbsolute(rel) ||
-      rel.includes('\\') ||
-      lstatSync(consumer).isSymbolicLink()
-    ) {
-      return false;
-    }
-    const parts = rel.split('/');
-    if (
-      parts.length === 0 ||
-      parts.some((part) => ['', '.', '..'].includes(part))
-    ) {
-      return false;
-    }
-    const root = realpathSync(consumer);
-    let candidate = consumer;
-    for (const [index, part] of parts.entries()) {
-      candidate = join(candidate, part);
-      const stat = lstatSync(candidate);
-      const final = index === parts.length - 1;
-      const expectedKind = final ? kind : 'directory';
-      if (
-        stat.isSymbolicLink() ||
-        !isContained(root, realpathSync(candidate)) ||
-        !matchesKind(stat, expectedKind)
-      ) {
-        return false;
-      }
-    }
-    return true;
-  } catch {
-    return false;
-  }
-};
 const keyName = (node: unknown): string | null =>
   isScalar(node) && typeof node.value === 'string' && node.tag === undefined
     ? node.value

package/src/creds-sops-value.ts

@@ -4,7 +4,8 @@
 // unverifiable read, so the two negative answers must stay distinct: anything
 // that is not a leaf we can read as a scalar string is unverifiable.
 
-import { isContainedSopsPath, parseSopsKeyPath } from './creds-sops-structure';
+import { isContainedPath } from './contained-path';
+import { parseSopsKeyPath } from './creds-sops-structure';
 import { runSops } from './sops-exec';
 
 export type SopsStoredValueVerification =
@@ -51,7 +52,7 @@ export const verifySopsStoredValueWith = (
   const { consumer, rel, dottedPath, expectedValue } = input;
   const path = parseSopsKeyPath(dottedPath);
   const problem = `could not verify stored SOPS value at ${dottedPath} in ${rel}`;
-  if (path === null || !isContainedSopsPath(consumer, rel, 'file')) {
+  if (path === null || !isContainedPath(consumer, rel, 'file')) {
     return { ok: false, problem };
   }
   const extract = path

package/src/creds-sops.ts

@@ -6,6 +6,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { isContainedPath } from './contained-path';
 import {
   type SopsValueChange as EditorValueChange,
   inspectSopsScalarStructure,
@@ -14,7 +15,6 @@ import {
 } from './creds-sops-editor';
 import {
   inspectSopsStructure,
-  isContainedSopsPath,
   type SopsShapeFailure,
 } from './creds-sops-structure';
 import { runSops } from './sops-exec';
@@ -45,7 +45,7 @@ export const readEncryptedKeys = async (
   consumer: string,
   rel: string,
 ): Promise<EncryptedKeysReadResult> => {
-  if (!isContainedSopsPath(consumer, rel, 'file')) {
+  if (!isContainedPath(consumer, rel, 'file')) {
     return {
       ok: false,
       kind: 'read-error',
@@ -68,7 +68,7 @@ export const inspectSopsScalarDestination = async (
   rel: string,
   dottedPath: string,
 ): Promise<SopsScalarDestinationResult> => {
-  if (!isContainedSopsPath(consumer, rel, 'file')) {
+  if (!isContainedPath(consumer, rel, 'file')) {
     return {
       ok: false,
       kind: 'read-error',
@@ -118,7 +118,7 @@ export const setSopsValues = (
   rel: string,
   changes: ReadonlyArray<EditorValueChange>,
 ): SopsWriteResult => {
-  if (!isContainedSopsPath(consumer, rel, 'file')) {
+  if (!isContainedPath(consumer, rel, 'file')) {
     return { ok: false, problem: `unsafe encrypted secrets target ${rel}` };
   }
   const result = runSops(['edit', rel], consumer, {

package/src/creds-target.ts

@@ -1,4 +1,4 @@
-import { isContainedSopsPath } from './creds-sops-structure';
+import { isContainedPath } from './contained-path';
 
 const SAFE_TARGET = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9_-])?$/u;
 
@@ -26,8 +26,8 @@ export const resolveTargetRelResult = (
   }
   const host = `infra/hosts/${target}/secrets.yaml`;
   const flat = `secrets/${target}.yaml`;
-  const hostExists = isContainedSopsPath(consumer, host, 'file');
-  const flatExists = isContainedSopsPath(consumer, flat, 'file');
+  const hostExists = isContainedPath(consumer, host, 'file');
+  const flatExists = isContainedPath(consumer, flat, 'file');
   if (hostExists && flatExists) {
     return {
       ok: false,

package/src/json-file.ts

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import { isRecord } from './github-settings-parse';
+
+export const readJsonFile = async (
+  path: string,
+): Promise<Record<string, unknown> | null> => {
+  const raw = await readFile(path, 'utf8').catch(() => null);
+  if (raw === null) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};

package/src/structure-check.ts

@@ -1,13 +1,16 @@
 import { existsSync } from 'node:fs';
-import { readdir, readFile } from 'node:fs/promises';
+import { readdir } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
 import { isRecord } from './github-settings-parse';
+import { readJsonFile } from './json-file';
 import {
   missingPublishedCliProblems,
   rootScriptExpectations,
   type StructureProfile,
 } from './structure-profile';
-import { hasSafeCommands, isSafeFilteredTurboAlias } from './structure-script';
+import { collectWorkspaceReadmeProblems } from './structure-readme';
+import { filteredTurboAliasProblem, hasSafeCommands } from './structure-script';
+import { collectCiSecretsProblems } from './structure-secrets';
 import { inspectWorkspace, type Workspace } from './structure-workspace';
 
 const ROOT_FIXED_SCRIPTS = new Set(
@@ -17,20 +20,6 @@ const GLOB_SUFFIX = '/*';
 const WORKSPACES_REQUIREMENT =
   'package.json: "workspaces" must be a non-empty array of literal paths or one-level "<dir>/*" patterns';
 
-const readJson = async (
-  path: string,
-): Promise<Record<string, unknown> | null> => {
-  const raw = await readFile(path, 'utf8').catch(() => null);
-  if (raw === null) {
-    return null;
-  }
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    return isRecord(parsed) ? parsed : null;
-  } catch {
-    return null;
-  }
-};
 type ResolvedPattern = {
   readonly dirs: ReadonlyArray<string>;
   readonly problem: string | null;
@@ -116,7 +105,7 @@ const loadWorkspace = async (
   if (!existsSync(path)) {
     return { workspace: null, problem: null };
   }
-  const manifest = await readJson(path);
+  const manifest = await readJsonFile(path);
   if (manifest === null) {
     return {
       workspace: null,
@@ -145,24 +134,28 @@ const inspectRootScripts = (
           `package.json: root script "${name}" must run ${exact ? 'exactly ' : ''}${requirement}`,
         ];
   });
-  const aliasProblems = Object.entries(scripts).flatMap(([name, script]) =>
-    ROOT_FIXED_SCRIPTS.has(name) ||
-    typeof script !== 'string' ||
-    isSafeFilteredTurboAlias(script)
-      ? []
-      : [
-          `package.json: root script "${name}" must delegate through Turbo with an explicit --filter`,
-        ],
-  );
+  const aliasProblems = Object.entries(scripts).flatMap(([name, script]) => {
+    if (ROOT_FIXED_SCRIPTS.has(name) || typeof script !== 'string') {
+      return [];
+    }
+    const problem = filteredTurboAliasProblem(name, script);
+    return problem === null ? [] : [problem];
+  });
   return [...gateProblems, ...aliasProblems];
 };
 export const collectStructureProblems = async (
   consumer: string,
   profile: StructureProfile,
 ): Promise<ReadonlyArray<string>> => {
-  const root = await readJson(join(consumer, 'package.json'));
+  const [root, secretsProblems] = await Promise.all([
+    readJsonFile(join(consumer, 'package.json')),
+    collectCiSecretsProblems(consumer),
+  ]);
   if (root === null) {
-    return ['package.json must exist and contain a JSON object'];
+    return [
+      'package.json must exist and contain a JSON object',
+      ...secretsProblems,
+    ];
   }
   const declaration = workspacePatternsOf(root);
   const resolved = await Promise.all(
@@ -180,9 +173,16 @@ export const collectStructureProblems = async (
       .map((ws) => ws.manifest.name)
       .filter((name): name is string => typeof name === 'string'),
   );
-  const inspections = await Promise.all(
-    workspaces.map((ws) => inspectWorkspace(ws, workspaceNames, profile)),
-  );
+  const [inspections, readmeProblems] = await Promise.all([
+    Promise.all(
+      workspaces.map((ws) => inspectWorkspace(ws, workspaceNames, profile)),
+    ),
+    collectWorkspaceReadmeProblems(
+      consumer,
+      profile,
+      workspaces.map((ws) => ws.rel),
+    ),
+  ]);
   const requireA11y = inspections.some((i) => i.hasA11ySuite);
   return [
     ...declaration.problems,
@@ -191,5 +191,7 @@ export const collectStructureProblems = async (
     ...missingPublishedCliProblems(profile, workspaces),
     ...inspectRootScripts(root, profile, requireA11y),
     ...inspections.flatMap((i) => [...i.problems]),
+    ...readmeProblems,
+    ...secretsProblems,
   ];
 };

package/src/structure-readme.ts

@@ -0,0 +1,85 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isContainedPath } from './contained-path';
+import { readJsonFile } from './json-file';
+import type { StructureProfile } from './structure-profile';
+
+const SYNC_MANIFEST = 'sync-standards.json';
+const TRAILING_SLASHES = /\/+$/u;
+const MANIFEST_REQUIREMENT = `${SYNC_MANIFEST}: must contain a JSON object with a "paths" array of strings; the structure gate reads it to tell canonical workspaces from repo-owned ones`;
+const MANIFEST_CONTAINMENT = `${SYNC_MANIFEST}: must be a contained regular file; symlinked paths are not allowed`;
+
+type CanonicalRels = {
+  readonly rels: ReadonlySet<string>;
+  readonly problem: string | null;
+};
+
+// Canonical workspaces are synced from the standards template and cannot be
+// fixed in a consumer checkout, so the consumer profile exempts them from
+// repo-owned documentation rules. The source repository owns those workspaces,
+// so the source profile exempts nothing.
+const canonicalWorkspaceRels = async (
+  consumer: string,
+  profile: StructureProfile,
+): Promise<CanonicalRels> => {
+  if (profile === 'source') {
+    return { rels: new Set(), problem: null };
+  }
+  const manifestPath = join(consumer, SYNC_MANIFEST);
+  const manifestInfo = await lstat(manifestPath).catch(() => null);
+  if (
+    manifestInfo !== null &&
+    !isContainedPath(consumer, SYNC_MANIFEST, 'file')
+  ) {
+    return { rels: new Set(), problem: MANIFEST_CONTAINMENT };
+  }
+  const manifest = await readJsonFile(manifestPath);
+  const paths = manifest?.paths;
+  if (
+    !(
+      Array.isArray(paths) &&
+      paths.every((path): path is string => typeof path === 'string')
+    )
+  ) {
+    return { rels: new Set(), problem: MANIFEST_REQUIREMENT };
+  }
+  return {
+    rels: new Set(paths.map((path) => path.replace(TRAILING_SLASHES, ''))),
+    problem: null,
+  };
+};
+
+const readmeProblem = async (
+  consumer: string,
+  rel: string,
+): Promise<string | null> => {
+  const readmeRel = `${rel}/README.md`;
+  const readmePath = join(consumer, readmeRel);
+  const info = await lstat(readmePath).catch(() => null);
+  if (info !== null && !isContainedPath(consumer, readmeRel, 'file')) {
+    return `${rel}: README.md must be a contained regular file; symlinked paths are not allowed`;
+  }
+  const raw = await readFile(readmePath, 'utf8').catch(() => null);
+  return raw !== null && raw.trim() !== ''
+    ? null
+    : `${rel}: repo-owned workspace must have a non-empty README.md`;
+};
+
+export const collectWorkspaceReadmeProblems = async (
+  consumer: string,
+  profile: StructureProfile,
+  rels: ReadonlyArray<string>,
+): Promise<ReadonlyArray<string>> => {
+  const canonical = await canonicalWorkspaceRels(consumer, profile);
+  if (canonical.problem !== null) {
+    // Without the manifest the gate cannot tell canonical workspaces from
+    // repo-owned ones, so it fails on the manifest instead of guessing.
+    return [canonical.problem];
+  }
+  const problems = await Promise.all(
+    rels
+      .filter((rel) => !canonical.rels.has(rel))
+      .map((rel) => readmeProblem(consumer, rel)),
+  );
+  return problems.filter((problem): problem is string => problem !== null);
+};

package/src/structure-script.ts

@@ -2,6 +2,18 @@ const UNSAFE_SCRIPT_SYNTAX = /[|;#"'`\r\n]/u;
 const SCRIPT_WHITESPACE = /\s+/u;
 const NON_EXECUTING_TURBO_OPTION = /^(?:-h|-v|--(?:dry|help|version))(?:=|$)/u;
 
+type FilteredTurboAliasViolation =
+  | 'empty'
+  | 'filter-empty'
+  | 'filter-missing'
+  | 'filter-option'
+  | 'multiple-commands'
+  | 'non-executing-option'
+  | 'not-run'
+  | 'not-turbo'
+  | 'syntax'
+  | 'task';
+
 export const parseSafeCommands = (
   script: string | null,
 ): ReadonlyArray<ReadonlyArray<string>> | null => {
@@ -39,12 +51,32 @@ export const hasSafeCommand = (
   expected: string,
 ): boolean => hasSafeCommands(script, [expected], false);
 
-export const isSafeFilteredTurboAlias = (script: string): boolean => {
+const filteredTurboAliasViolation = (
+  script: string,
+): FilteredTurboAliasViolation | null => {
+  if (script.trim() === '') {
+    return 'empty';
+  }
   const commands = parseSafeCommands(script);
-  if (commands?.length !== 1) {
-    return false;
+  if (commands === null) {
+    return 'syntax';
+  }
+  if (commands.length !== 1) {
+    return 'multiple-commands';
   }
   const [tokens] = commands;
+  if (tokens[0] !== 'turbo') {
+    return 'not-turbo';
+  }
+  if (tokens[1] !== 'run') {
+    return 'not-run';
+  }
+  if (tokens.some((token) => NON_EXECUTING_TURBO_OPTION.test(token))) {
+    return 'non-executing-option';
+  }
+  if (tokens[2]?.startsWith('-') !== false) {
+    return 'task';
+  }
   const filterAt = tokens.findIndex(
     (token) => token === '--filter' || token.startsWith('--filter='),
   );
@@ -53,11 +85,40 @@ export const isSafeFilteredTurboAlias = (script: string): boolean => {
     filter === '--filter'
       ? tokens[filterAt + 1]
       : filter?.slice('--filter='.length);
-  return tokens[0] !== 'turbo' || tokens[1] !== 'run'
-    ? false
-    : tokens[2]?.startsWith('-') === false &&
-        !tokens.some((token) => NON_EXECUTING_TURBO_OPTION.test(token)) &&
-        filterValue !== undefined &&
-        filterValue !== '' &&
-        !filterValue.startsWith('-');
+  if (filter === undefined) {
+    return 'filter-missing';
+  }
+  if (filterValue === undefined || filterValue === '') {
+    return 'filter-empty';
+  }
+  return filterValue.startsWith('-') ? 'filter-option' : null;
 };
+
+export const filteredTurboAliasProblem = (
+  name: string,
+  script: string,
+): string | null => {
+  const violation = filteredTurboAliasViolation(script);
+  if (violation === null) {
+    return null;
+  }
+  const details: Record<FilteredTurboAliasViolation, string> = {
+    empty: 'must be a non-empty single filtered Turbo command',
+    'filter-empty': 'must pass a non-empty value to --filter',
+    'filter-missing': 'must pass an explicit --filter',
+    'filter-option': 'must pass a --filter value that is not another option',
+    'multiple-commands':
+      'must contain exactly one command; && command chains are not supported',
+    'non-executing-option':
+      'must execute a task; Turbo help, version, and dry-run options are not allowed',
+    'not-run': 'must invoke Turbo through "turbo run"',
+    'not-turbo': 'must invoke Turbo directly with "turbo"',
+    syntax:
+      'contains shell syntax the structure gate does not parse (quotes, |, ;, #, backticks, $(, CR/LF line breaks, or malformed ampersand separators); write one command with plain arguments, using --filter=./apps/* for a glob',
+    task: 'must put a task name immediately after "turbo run"',
+  };
+  return `package.json: root script "${name}" ${details[violation]}`;
+};
+
+export const isSafeFilteredTurboAlias = (script: string): boolean =>
+  filteredTurboAliasViolation(script) === null;

package/src/structure-secret-document.ts

@@ -0,0 +1,170 @@
+import { isRecord } from './github-settings-parse';
+import {
+  hasCompleteSopsMetadata,
+  isEncryptedLeafValue,
+  isSopsEncryptedString,
+  looksEncrypted,
+} from './structure-sops-envelope';
+
+export type SecretLeaf = {
+  readonly id: string;
+  readonly path: string;
+  readonly segments: ReadonlyArray<string>;
+  readonly value: unknown;
+};
+
+export type SecretDocumentInspection = {
+  readonly leaves: ReadonlyMap<string, SecretLeaf>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export type RequiredSecretLeaf = {
+  readonly path: ReadonlyArray<string>;
+  readonly reason: string;
+};
+
+export const secretPathId = (segments: ReadonlyArray<string>): string =>
+  JSON.stringify(segments);
+
+const collectLeaves = (
+  value: unknown,
+  segments: ReadonlyArray<string>,
+  into: Map<string, SecretLeaf>,
+): void => {
+  if (
+    isRecord(value) &&
+    (segments.length === 0 || Object.keys(value).length > 0)
+  ) {
+    for (const [key, child] of Object.entries(value)) {
+      collectLeaves(child, [...segments, key], into);
+    }
+    return;
+  }
+  const leaf = {
+    id: secretPathId(segments),
+    path: segments.join('.'),
+    segments,
+    value,
+  };
+  into.set(leaf.id, leaf);
+};
+
+const businessLeaves = (
+  mapping: Record<string, unknown>,
+): ReadonlyMap<string, SecretLeaf> => {
+  const { sops: _sops, ...business } = mapping;
+  const leaves = new Map<string, SecretLeaf>();
+  collectLeaves(business, [], leaves);
+  return leaves;
+};
+
+const ambiguityProblems = (
+  rel: string,
+  leaves: ReadonlyMap<string, SecretLeaf>,
+): ReadonlyArray<string> => {
+  const idsByDottedPath = new Map<string, Array<string>>();
+  for (const leaf of leaves.values()) {
+    const ids = idsByDottedPath.get(leaf.path) ?? [];
+    ids.push(leaf.id);
+    idsByDottedPath.set(leaf.path, ids);
+  }
+  return [...idsByDottedPath]
+    .filter(([, ids]) => ids.length > 1)
+    .map(
+      ([path]) =>
+        `${rel}: key path "${path}" is ambiguous because direct dotted keys and nested mappings collide`,
+    );
+};
+
+export const inspectSecretDocument = (
+  rel: string,
+  mapping: Record<string, unknown>,
+  required: ReadonlyArray<RequiredSecretLeaf>,
+): SecretDocumentInspection => {
+  const leaves = businessLeaves(mapping);
+  return {
+    leaves,
+    problems: [
+      ...(hasCompleteSopsMetadata(mapping.sops)
+        ? []
+        : [
+            `${rel}: incomplete top-level "sops" metadata; encrypt the file with SOPS before committing it`,
+          ]),
+      ...ambiguityProblems(rel, leaves),
+      ...[...leaves.values()]
+        .filter((leaf) => !isEncryptedLeafValue(leaf.value))
+        .map(
+          (leaf) =>
+            `${rel}: value at "${leaf.path}" is not a complete SOPS-encrypted value; plaintext secret values must never be committed`,
+        ),
+      ...required.flatMap((requirement) => {
+        const leaf = leaves.get(secretPathId(requirement.path));
+        if (leaf === undefined) {
+          return [
+            `${rel}: missing required key "${requirement.path.join('.')}" — ${requirement.reason}`,
+          ];
+        }
+        return isEncryptedLeafValue(leaf.value) &&
+          !isSopsEncryptedString(leaf.value)
+          ? [
+              `${rel}: required key "${requirement.path.join('.')}" must be one SOPS-encrypted string scalar because its workflow resolves it as a string`,
+            ]
+          : [];
+      }),
+    ],
+  };
+};
+
+export const inspectExampleDocument = (
+  rel: string,
+  mapping: Record<string, unknown>,
+): SecretDocumentInspection => {
+  const leaves = businessLeaves(mapping);
+  return {
+    leaves,
+    problems: [
+      ...(mapping.sops === undefined
+        ? []
+        : [`${rel}: must hold plaintext placeholders, not SOPS metadata`]),
+      ...ambiguityProblems(rel, leaves),
+      ...[...leaves.values()]
+        .filter((leaf) => looksEncrypted(leaf.value))
+        .map(
+          (leaf) =>
+            `${rel}: value at "${leaf.path}" looks SOPS-encrypted; replace it with a plaintext placeholder`,
+        ),
+    ],
+  };
+};
+
+type SecretShapeContext = {
+  readonly secretsRel: string;
+  readonly exampleRel: string;
+  readonly secrets: ReadonlyMap<string, SecretLeaf>;
+  readonly example: ReadonlyMap<string, SecretLeaf>;
+  readonly required: ReadonlyArray<RequiredSecretLeaf>;
+};
+
+export const secretShapeProblems = ({
+  secretsRel,
+  exampleRel,
+  secrets,
+  example,
+  required,
+}: SecretShapeContext): ReadonlyArray<string> => {
+  const requiredIds = new Set(required.map(({ path }) => secretPathId(path)));
+  return [
+    ...[...secrets.values()]
+      .filter((leaf) => !example.has(leaf.id))
+      .map(
+        (leaf) =>
+          `${exampleRel}: missing key "${leaf.path}" with the same mapping shape; mirror every ${secretsRel} key with a placeholder`,
+      ),
+    ...[...example.values()]
+      .filter((leaf) => !(secrets.has(leaf.id) || requiredIds.has(leaf.id)))
+      .map(
+        (leaf) =>
+          `${secretsRel}: missing key "${leaf.path}" with the same mapping shape; add the secret or delete the stale key from ${exampleRel}`,
+      ),
+  ];
+};

package/src/structure-secrets.ts

@@ -0,0 +1,131 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isContainedPath } from './contained-path';
+import { isRecord } from './github-settings-parse';
+import {
+  inspectExampleDocument,
+  inspectSecretDocument,
+  type RequiredSecretLeaf,
+  secretShapeProblems,
+} from './structure-secret-document';
+import { readSyncPolicy } from './sync-policy';
+import { parseYaml } from './yaml-parse';
+
+const CI_SECRETS = 'secrets/ci.yaml';
+const CI_EXAMPLE = 'secrets/ci.example.yaml';
+const BROKER_REASON =
+  'the synced Standards sync workflow mints its pull request token from ci.broker_app; provision it with "bun standards creds add github --dest ci:ci.broker_app"';
+const NTFY_REQUIREMENT: RequiredSecretLeaf = {
+  path: ['ci', 'ntfy_topic_url'],
+  reason: 'the synced Notify pause workflow pushes to it',
+};
+const BROKER_REQUIREMENTS: ReadonlyArray<RequiredSecretLeaf> = [
+  { path: ['ci', 'broker_app', 'app_id'], reason: BROKER_REASON },
+  { path: ['ci', 'broker_app', 'private_key'], reason: BROKER_REASON },
+];
+
+type ParsedMapping = {
+  readonly mapping: Record<string, unknown> | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const parseMapping = async (
+  consumer: string,
+  rel: string,
+  missingRequirement: string,
+): Promise<ParsedMapping> => {
+  const path = join(consumer, rel);
+  const info = await lstat(path).catch(() => null);
+  if (info === null) {
+    return { mapping: null, problems: [missingRequirement] };
+  }
+  if (!isContainedPath(consumer, rel, 'file')) {
+    return {
+      mapping: null,
+      problems: [
+        `${rel}: must be a contained regular file; symlinked paths are not allowed`,
+      ],
+    };
+  }
+  const raw = await readFile(path, 'utf8').catch(() => null);
+  if (raw === null) {
+    return { mapping: null, problems: [`${rel}: could not be read`] };
+  }
+  const parsed = parseYaml(raw, rel);
+  if (parsed.problem !== null) {
+    return { mapping: null, problems: [parsed.problem] };
+  }
+  if (!isRecord(parsed.value)) {
+    return { mapping: null, problems: [`${rel}: must be a YAML mapping`] };
+  }
+  return { mapping: parsed.value, problems: [] };
+};
+
+const requiredLeaves = async (
+  consumer: string,
+): Promise<{
+  readonly required: ReadonlyArray<RequiredSecretLeaf>;
+  readonly problems: ReadonlyArray<string>;
+}> => {
+  try {
+    const policy = await readSyncPolicy(consumer);
+    return {
+      required:
+        policy.autoSync === false
+          ? [NTFY_REQUIREMENT]
+          : [NTFY_REQUIREMENT, ...BROKER_REQUIREMENTS],
+      problems: [],
+    };
+  } catch (error) {
+    return {
+      required: [NTFY_REQUIREMENT, ...BROKER_REQUIREMENTS],
+      problems: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+};
+
+export const collectCiSecretsProblems = async (
+  consumer: string,
+): Promise<ReadonlyArray<string>> => {
+  const [requirement, secretsFile, exampleFile] = await Promise.all([
+    requiredLeaves(consumer),
+    parseMapping(
+      consumer,
+      CI_SECRETS,
+      `${CI_SECRETS}: must exist as a SOPS-encrypted file; the synced CI workflows read ci.ntfy_topic_url and, when automatic sync is enabled, ci.broker_app from it`,
+    ),
+    parseMapping(
+      consumer,
+      CI_EXAMPLE,
+      `${CI_EXAMPLE}: must exist and mirror the key shape of ${CI_SECRETS} with plaintext placeholders`,
+    ),
+  ]);
+  const secrets =
+    secretsFile.mapping === null
+      ? null
+      : inspectSecretDocument(
+          CI_SECRETS,
+          secretsFile.mapping,
+          requirement.required,
+        );
+  const example =
+    exampleFile.mapping === null
+      ? null
+      : inspectExampleDocument(CI_EXAMPLE, exampleFile.mapping);
+  return [
+    ...requirement.problems,
+    ...secretsFile.problems,
+    ...exampleFile.problems,
+    ...(secrets === null ? [] : secrets.problems),
+    ...(example === null ? [] : example.problems),
+    ...(secrets !== null && example !== null
+      ? secretShapeProblems({
+          secretsRel: CI_SECRETS,
+          exampleRel: CI_EXAMPLE,
+          secrets: secrets.leaves,
+          example: example.leaves,
+          required: requirement.required,
+        })
+      : []),
+  ];
+};

package/src/structure-sops-envelope.ts

@@ -0,0 +1,123 @@
+import { isRecord } from './github-settings-parse';
+
+const SOPS_ENVELOPE =
+  /^ENC\[AES256_GCM,data:(?<data>[A-Za-z0-9+/]+={0,2}),iv:(?<iv>[A-Za-z0-9+/]+={0,2}),tag:(?<tag>[A-Za-z0-9+/]+={0,2}),type:(?<type>bool|bytes|comment|float|int|str)\]$/u;
+const SOPS_VERSION = /^\d+\.\d+\.\d+$/u;
+const SOPS_SOURCE_CONTRACTS = [
+  ['age', ['recipient', 'enc']],
+  ['azure_kv', ['vault_url', 'name', 'version', 'created_at', 'enc']],
+  ['gcp_kms', ['resource_id', 'created_at', 'enc']],
+  [
+    'hc_vault',
+    ['vault_address', 'engine_path', 'key_name', 'created_at', 'enc'],
+  ],
+  ['kms', ['arn', 'created_at', 'enc']],
+  ['pgp', ['created_at', 'enc', 'fp']],
+] as const;
+type SopsSource = (typeof SOPS_SOURCE_CONTRACTS)[number][0];
+const SOPS_SOURCES = SOPS_SOURCE_CONTRACTS.map(([source]) => source);
+const SOPS_SOURCE_FIELDS = new Map<SopsSource, ReadonlyArray<string>>(
+  SOPS_SOURCE_CONTRACTS,
+);
+
+const isCanonicalBase64 = (value: string): boolean => {
+  try {
+    return Buffer.from(value, 'base64').toString('base64') === value;
+  } catch {
+    return false;
+  }
+};
+
+const sopsEnvelopeType = (value: unknown): string | null => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const match = SOPS_ENVELOPE.exec(value);
+  const groups = match?.groups;
+  return groups !== undefined &&
+    groups.data !== undefined &&
+    groups.iv !== undefined &&
+    groups.tag !== undefined &&
+    groups.type !== undefined &&
+    [groups.data, groups.iv, groups.tag].every(isCanonicalBase64)
+    ? groups.type
+    : null;
+};
+
+export const isSopsEncryptedScalar = (value: unknown): boolean =>
+  sopsEnvelopeType(value) !== null;
+
+export const isSopsEncryptedString = (value: unknown): boolean =>
+  sopsEnvelopeType(value) === 'str';
+
+export const isEncryptedLeafValue = (value: unknown): boolean =>
+  isSopsEncryptedScalar(value) ||
+  (Array.isArray(value) &&
+    value.length > 0 &&
+    value.every(isSopsEncryptedScalar));
+
+export const looksEncrypted = (value: unknown): boolean =>
+  (typeof value === 'string' && value.startsWith('ENC[')) ||
+  (Array.isArray(value) &&
+    value.some((item) => typeof item === 'string' && item.startsWith('ENC[')));
+
+const hasRequiredStringFields = (
+  value: unknown,
+  fields: ReadonlyArray<string>,
+): boolean =>
+  isRecord(value) &&
+  fields.every(
+    (field) => typeof value[field] === 'string' && value[field].length > 0,
+  );
+
+const hasCompleteSource = (value: unknown, source: SopsSource): boolean => {
+  const fields = SOPS_SOURCE_FIELDS.get(source);
+  return (
+    fields !== undefined &&
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((entry) => hasRequiredStringFields(entry, fields))
+  );
+};
+
+const hasCompleteSources = (
+  value: Record<string, unknown>,
+  allowEmptyPlaceholders: boolean,
+): boolean => {
+  const present = SOPS_SOURCES.filter((source) => value[source] !== undefined);
+  return (
+    present.length > 0 &&
+    present.some((source) => hasCompleteSource(value[source], source)) &&
+    present.every(
+      (source) =>
+        hasCompleteSource(value[source], source) ||
+        (allowEmptyPlaceholders &&
+          Array.isArray(value[source]) &&
+          value[source].length === 0),
+    )
+  );
+};
+
+const hasCompleteKeyGroups = (value: unknown): boolean =>
+  Array.isArray(value) &&
+  value.length > 0 &&
+  value.every((group) => isRecord(group) && hasCompleteSources(group, true));
+
+const hasCompleteRecipients = (value: Record<string, unknown>): boolean => {
+  const hasDirectSource = SOPS_SOURCES.some(
+    (source) => value[source] !== undefined,
+  );
+  const hasKeyGroups = value.key_groups !== undefined;
+  return (
+    (hasDirectSource || hasKeyGroups) &&
+    (!hasDirectSource || hasCompleteSources(value, false)) &&
+    (!hasKeyGroups || hasCompleteKeyGroups(value.key_groups))
+  );
+};
+
+export const hasCompleteSopsMetadata = (value: unknown): boolean =>
+  isRecord(value) &&
+  typeof value.version === 'string' &&
+  SOPS_VERSION.test(value.version) &&
+  isSopsEncryptedScalar(value.mac) &&
+  hasCompleteRecipients(value);

package/src/sync-policy.ts

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isContainedPath } from './contained-path';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+
+export const SYNC_POLICY_FILE = 'sync-standards.local.json';
+const LINE_BREAK = /[\r\n]/u;
+
+export type SyncPolicy = {
+  readonly autoSync?: boolean;
+  readonly ref?: string;
+};
+
+const parseSyncPolicy = (parsed: unknown): SyncPolicy => {
+  if (!isRecord(parsed)) {
+    throw new Error(`${SYNC_POLICY_FILE} must be a JSON object`);
+  }
+  const unsupportedFields = Object.keys(parsed).filter(
+    (field) => field !== 'autoSync' && field !== 'ref',
+  );
+  if (unsupportedFields.length > 0) {
+    throw new Error(
+      `${SYNC_POLICY_FILE} contains unsupported field(s): ${unsupportedFields.join(', ')}`,
+    );
+  }
+  if (parsed.autoSync !== undefined && typeof parsed.autoSync !== 'boolean') {
+    throw new Error(`${SYNC_POLICY_FILE} "autoSync" must be a boolean`);
+  }
+  if (
+    parsed.ref !== undefined &&
+    (!isNonEmptyString(parsed.ref) || LINE_BREAK.test(parsed.ref))
+  ) {
+    throw new Error(
+      `${SYNC_POLICY_FILE} "ref" must be a non-empty single-line string`,
+    );
+  }
+  return { autoSync: parsed.autoSync, ref: parsed.ref };
+};
+
+export const readSyncPolicy = async (consumer: string): Promise<SyncPolicy> => {
+  const path = join(consumer, SYNC_POLICY_FILE);
+  const info = await lstat(path).catch((error: unknown) => {
+    if (isRecord(error) && error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  });
+  if (info === null) {
+    return {};
+  }
+  if (!isContainedPath(consumer, SYNC_POLICY_FILE, 'file')) {
+    throw new Error(
+      `${SYNC_POLICY_FILE} must be a contained regular file; symlinked paths are not allowed`,
+    );
+  }
+  const raw = await readFile(path, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${SYNC_POLICY_FILE} must contain valid JSON`, {
+      cause: error,
+    });
+  }
+  return parseSyncPolicy(parsed);
+};
+
+export const inspectSyncPolicy = async (
+  consumer: string,
+): Promise<ReadonlyArray<string>> => {
+  try {
+    await readSyncPolicy(consumer);
+    return [];
+  } catch (error) {
+    return [error instanceof Error ? error.message : String(error)];
+  }
+};
+
+// Policy validation is unconditional once the file exists. Selection happens
+// afterward: explicit refs win for remote sources, while local paths are used
+// as-is and ignore only the already-validated policy ref.
+export const selectedSyncRef = (
+  src: string,
+  explicitRef: string | undefined,
+  policy: SyncPolicy,
+): string | undefined =>
+  existsSync(src) ? explicitRef : (explicitRef ?? policy.ref);