@davidvornholt/standards 0.23.0 → 0.24.1

package/README.md

@@ -35,11 +35,11 @@ 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.
 
-`creds` is the credential broker: it mints scoped Cloudflare tokens, rotates and revokes those tokens, and places GitHub App credentials into SOPS-encrypted targets — secret values never touch stdout, argv, or an agent's context; commands print only metadata (token name, scopes, expiry, destination). Cloudflare reconciliation has exactly two sources of truth: the plaintext key structure of the SOPS files and the provider token list under the deterministic naming scheme `standards/<owner>/<repo>/<sops-target>/<dotted.key>`; there is no separate credential manifest. `plan` and `apply` reconcile Cloudflare only: each run uses the stored bootstrap credential to verify its current provider token ID, excludes that ID from reconciliation regardless of its current name, and aborts if the identity cannot be correlated with the complete account token list; a brokered token whose SOPS key was deleted is revoked, while one nearing expiry (30 days) is renewed by creating a fresh-expiry replacement with the live token's policies, durably writing and verifying the new value, and only then revoking the old token; secrets the broker did not mint are never touched. Both also report what reconciliation will never touch, in two separately labelled and separately counted blocks that never block: unmanaged tokens, meaning every unexpired token in the account whose name falls outside the reserved `standards/` namespace — with one exception, this machine's own bootstrap credential, which every run removes by verified ID before anything is classified — and tokens brokered to another repository, each printed with the repository whose `apply` owns it. An expired token is omitted from the unmanaged listing because it grants nothing. Neither block is idle information: nothing here renews or revokes those tokens, and a forgotten one — the original half of a hand-made credential that was replaced rather than retired, or a brokered token whose repository was renamed away — stays valid indefinitely, so a listed token is normally printed with the exact command that retires it, carrying `--account` and, for a token brokered elsewhere, `--force` and the one condition that justifies it. Two rows are exceptions. A token named `standards-broker` holds the reserved name for a machine's bootstrap credential, so it is either another machine's or a superseded one on this machine; `revoke` refuses it by name, so the row names the Cloudflare dashboard rather than a command that would always fail. The other exception looks like an ordinary brokered-elsewhere row, and its command fails. `plan` classifies by exact token name, so a token whose brokered repository differs from this checkout's origin only in capitalisation lands in the brokered-elsewhere block with a `--force` command; `revoke` compares repository names case-insensitively, reads the same token as this checkout's own, and refuses. Row and block header both read that token as foreign — the header labels the block tokens brokered to another repository, and the row explains the `--force` by the owning repository having been renamed, transferred, or deleted. Neither holds there: GitHub names are case-insensitive, so the owning repository is this one and it is still alive. Re-point the origin remote at the capitalisation the token carries, or retire the token in the Cloudflare dashboard. A name that claims this repository's brokered namespace without being one the broker mints is a finding instead, and findings abort reconciliation before any mutation, because reconciliation cannot own that token; plain `revoke --token-id` takes it once you decide it should go. `revoke --token-id <id>` deletes exactly one Cloudflare token, named by its 32-character hexadecimal ID, with `--account <id>` required whenever more than one account is configured; it records no ownership, so the power is momentary rather than standing and a human names the target every time. It refuses an ID the account does not hold, the bootstrap credential this machine has stored (matched by verified ID, so a rename cannot disguise it), and any other token named `standards-broker`, the reserved name for a machine's bootstrap (matched by name, because that one is another machine's bootstrap or a superseded one, retired in the Cloudflare dashboard where you can confirm whose it is — the broker cannot re-mint its own root credential). A token brokered to this repository is refused with the remedy that works here: delete its SOPS key in this repository and run `apply`, which revokes the token and keeps the secret in step. A token whose brokered name differs from this checkout's origin only in capitalisation is refused too, and without the `apply` remedy: reconciliation matches the name exactly, so from here it would neither renew nor revoke the token. Its remedies are re-pointing the origin remote at the capitalisation the token carries, which brings it back under reconciliation, or retiring it in the Cloudflare dashboard. A token brokered to a repository that is genuinely a different one is refused with that repository named, because the same `apply` remedy runs there. `--force` widens exactly that last refusal, and nothing else: it lets `revoke` delete a token whose brokered repository is not this checkout's. It verifies nothing about the state of that repository, so it is justified only when nothing reconciles the token any more — the owning repository was renamed, transferred, or deleted, and no checkout resolves to its name. `revoke` decides ownership from the origin remote and compares it case-insensitively, as GitHub names are; `plan` classifies by exact name instead, which is why the two disagree about a case-only difference. When the origin remote resolves to no GitHub repository, every brokered token is refused, `--force` included, because the check it widens is the one that could not be run. `--force` never bypasses either bootstrap guard, the case-only refusal, or that unresolvable-origin refusal. Without a manifest there is no desired-policy record, so live policy drift is not detected, and a repository rename or transfer changes the deterministic namespace and requires the visible old token to be re-minted under the new name and revoked. `add cloudflare` mints an account-owned API token (default TTL 90 days) scoped to the named permission groups (`permissions` lists the valid names) and writes it to `--dest <target>:<dotted.key>`, where `<target>` resolves like the canonical `just secrets` targets (`ci` → `secrets/ci.yaml`, `prod-1` → `infra/hosts/prod-1/secrets.yaml`). `--zone <zone-id>[,<zone-id>...]` adds a zone resource so zone-scoped groups such as DNS Write can be minted. Zones are named by their 32-character hexadecimal ID, shown on the zone's dashboard overview and not a secret; resolving a domain name instead would need Zone Read on the bootstrap token, which holds Account API Tokens / Edit and nothing else. With zones named, the selection is split by what each group can target: every group Cloudflare reports as zone-scoped forms one policy holding all named zones, and groups that can only target an account keep their own account policy on the same token, so one credential can hold DNS access next to account-wide access. A group Cloudflare reports as both takes the zone policy, which is the narrower reading of `--zone`. A group matching neither resource is named and rejected, `--zone` requires at least one zone-scoped group, and `--zone` cannot be combined with `--bucket`, which is a separate credential. The mint summary prints the resources the token reaches, so an account policy alongside the zones is visible rather than implied. `--bucket <name>` switches the policy resource to a single R2 bucket; `--jurisdiction default|eu` selects the provider jurisdiction and defaults to `default`, producing `com.cloudflare.edge.r2.bucket.<account_id>_default_<bucket>` or `com.cloudflare.edge.r2.bucket.<account_id>_eu_<bucket>`. FedRAMP jurisdictions are not supported. Bucket destinations accept only bucket-scoped groups such as Workers R2 Storage Bucket Item Read/Write, and account-scoped groups are rejected. `--s3` requires `--bucket` and stores the S3-compatible credential pair Cloudflare derives from an API token — access key ID is the token ID, secret access key is the SHA-256 hex digest of the token value — as `<dotted.key>.access_key_id` and `<dotted.key>.secret_access_key` under the destination instead of the raw token value; the default endpoint is `https://<account_id>.r2.cloudflarestorage.com`, while EU uses `https://<account_id>.eu.r2.cloudflarestorage.com`. Reconciliation infers each destination's concrete write footprint from the plaintext SOPS key structure — a bearer owns the leaf at its key, while an S3 token owns both pair leaves — and aborts before mutation when managed footprints intersect. `plan` and `apply` renew and revoke S3 destinations like any other brokered token, but renewal first proves the stored access key ID matches the current provider token; an incomplete pair, unreadable value, or identity mismatch is surfaced as a finding and never mutated automatically. `add github` selects the private broker App whose owner matches the destination repository's origin owner, checks both local SOPS leaves before authenticating, proves that the exact selected App is installed on that repository, and writes only while that full App identity still holds the synchronized broker-store entry; missing, duplicate, replaced, or mismatched owners fail before SOPS changes. Durable GitHub tokens cannot be created via API (PAT and OAuth-app creation are UI-only), so workflows mint short-lived installation tokens from the App at runtime (`actions/create-github-app-token`), scoped per repository and permission. The canonical weekly sync expects `bun standards creds add github --dest ci:ci.broker_app`, then mints a current-repository token with Contents read and Pull requests write; missing credentials or minting failures stop it without a fallback. Bootstrap is once per machine and per GitHub owner: `login github` creates a private personal App, while `login github --org <org>` creates or replaces only that organization's entry; each manifest conversion records GitHub's authoritative owner, and the command opens the installation page, where the App must be bound to selected repositories rather than all repositories. GitHub App names are globally unique and limited to 34 characters, so organization defaults include owners up to 17 characters; a longer owner or a colliding replacement name requires an explicit shorter unused `--name`. The first GitHub-specific command against an existing singleton broker store authenticates as that App, resolves its registration owner, and atomically migrates the old mapping to that one owner; a failed lookup leaves the persisted bytes untouched. If the singleton was a public App installed on repositories owned by other users or organizations, those repositories stop matching after migration because owner selection no longer treats that App as shared. For each affected owner, run `login github` while signed in as that personal owner or `login github --org <owner>`, install the new private App only on the selected repositories, run `bun standards creds add github --dest <target>:<key>` in every consumer, and verify its workflows can mint tokens. Retire the old public App only after every repository owner has its own entry, every intended SOPS destination has been reprovisioned, and token minting has been verified; until then, keep its key and installation available for any destinations not yet migrated. `login cloudflare` guides the one dashboard paste Cloudflare requires for the first account token (named `standards-broker` to match the App, created from the "Create additional tokens" token template because its "Account API Tokens: Edit" permission is unavailable in the custom token builder, and holding that permission only), verifies that it is active, correlates its verified ID with the complete account token list and an active list record, and stores it; a bootstrap token named inside the minted `standards/` namespace is rejected before storage to keep its role unambiguous, while any other divergence from the recommended name only warns. `plan` and `apply` do not rotate GitHub App keys; create a replacement key on the App's settings page, atomically replace that owner's `private_key` in the protected machine-global broker store while preserving its `0600` mode, then update every intended SOPS destination, verify workflows can mint installation tokens, and revoke the old key manually. Root credentials live in the machine-global broker store (see Configuration); SOPS writes go through `sops edit` with a non-interactive editor, preserving comments and reusing the file's data key.
+`creds` is the credential broker: it mints scoped Cloudflare tokens, rotates and revokes those tokens, and places GitHub App credentials into SOPS-encrypted targets — secret values never touch stdout, argv, or an agent's context; commands print only metadata (token name, scopes, expiry, destination). Cloudflare reconciliation has exactly two sources of truth: the plaintext key structure of the SOPS files and the provider token list under the deterministic naming scheme `standards/<owner>/<repo>/<sops-target>/<dotted.key>`; there is no separate credential manifest. `plan` and `apply` reconcile Cloudflare only: each run uses the stored bootstrap credential to verify its current provider token ID, excludes that ID from reconciliation regardless of its current name, and aborts if the identity cannot be correlated with the complete account token list; a brokered token whose SOPS key was deleted is revoked, while one nearing expiry (30 days) is renewed by creating a fresh-expiry replacement with the live token's policies, durably writing and verifying the new value, and only then revoking the old token; secrets the broker did not mint are never touched. Both also report what reconciliation will never touch, in two separately labelled and separately counted blocks that never block: unmanaged tokens, meaning every unexpired token in the account whose name falls outside the reserved `standards/` namespace — with one exception, this machine's own bootstrap credential, which every run removes by verified ID before anything is classified — and tokens brokered to another repository, each printed with the repository whose `apply` owns it. An expired token is omitted from the unmanaged listing because it grants nothing. Neither block is idle information: nothing here renews or revokes those tokens, and a forgotten one — the original half of a hand-made credential that was replaced rather than retired, or a brokered token whose repository was renamed away — stays valid indefinitely, so a listed token is normally printed with the exact command that retires it, carrying `--account` and, for a token brokered elsewhere, `--force` and the one condition that justifies it. Two rows are exceptions. A token named `standards-broker` holds the reserved name for a machine's bootstrap credential, so it is either another machine's or a superseded one on this machine; `revoke` refuses it by name, so the row names the Cloudflare dashboard rather than a command that would always fail. The other exception looks like an ordinary brokered-elsewhere row, and its command fails. `plan` classifies by exact token name, so a token whose brokered repository differs from this checkout's origin only in capitalisation lands in the brokered-elsewhere block with a `--force` command; `revoke` compares repository names case-insensitively, reads the same token as this checkout's own, and refuses. Row and block header both read that token as foreign — the header labels the block tokens brokered to another repository, and the row explains the `--force` by the owning repository having been renamed, transferred, or deleted. Neither holds there: GitHub names are case-insensitive, so the owning repository is this one and it is still alive. Re-point the origin remote at the capitalisation the token carries, or retire the token in the Cloudflare dashboard. A name that claims this repository's brokered namespace without being one the broker mints is a finding instead, and findings abort reconciliation before any mutation, because reconciliation cannot own that token; plain `revoke --token-id` takes it once you decide it should go. `revoke --token-id <id>` deletes exactly one Cloudflare token, named by its 32-character hexadecimal ID, with `--account <id>` required whenever more than one account is configured; it records no ownership, so the power is momentary rather than standing and a human names the target every time. It refuses an ID the account does not hold, the bootstrap credential this machine has stored (matched by verified ID, so a rename cannot disguise it), and any other token named `standards-broker`, the reserved name for a machine's bootstrap (matched by name, because that one is another machine's bootstrap or a superseded one, retired in the Cloudflare dashboard where you can confirm whose it is — the broker cannot re-mint its own root credential). A token brokered to this repository is refused with the remedy that works here: delete its SOPS key in this repository and run `apply`, which revokes the token and keeps the secret in step. A token whose brokered name differs from this checkout's origin only in capitalisation is refused too, and without the `apply` remedy: reconciliation matches the name exactly, so from here it would neither renew nor revoke the token. Its remedies are re-pointing the origin remote at the capitalisation the token carries, which brings it back under reconciliation, or retiring it in the Cloudflare dashboard. A token brokered to a repository that is genuinely a different one is refused with that repository named, because the same `apply` remedy runs there. `--force` widens exactly that last refusal, and nothing else: it lets `revoke` delete a token whose brokered repository is not this checkout's. It verifies nothing about the state of that repository, so it is justified only when nothing reconciles the token any more — the owning repository was renamed, transferred, or deleted, and no checkout resolves to its name. `revoke` decides ownership from the origin remote and compares it case-insensitively, as GitHub names are; `plan` classifies by exact name instead, which is why the two disagree about a case-only difference. When the origin remote resolves to no GitHub repository, every brokered token is refused, `--force` included, because the check it widens is the one that could not be run. `--force` never bypasses either bootstrap guard, the case-only refusal, or that unresolvable-origin refusal. Without a manifest there is no desired-policy record, so live policy drift is not detected, and a repository rename or transfer changes the deterministic namespace and requires the visible old token to be re-minted under the new name and revoked. `add cloudflare` mints an account-owned API token (default TTL 90 days) scoped to the named permission groups (`permissions` lists the valid names) and writes it to `--dest <target>:<dotted.key>`, where `<target>` resolves like the canonical `just secrets` targets (`ci` → `secrets/ci.yaml`, `prod-1` → `infra/hosts/prod-1/secrets.yaml`). `--zone <zone-id>[,<zone-id>...]` adds a zone resource so zone-scoped groups such as DNS Write can be minted. Zones are named by their 32-character hexadecimal ID, shown on the zone's dashboard overview and not a secret; resolving a domain name instead would need Zone Read on the bootstrap token, which holds Account API Tokens / Edit and nothing else. With zones named, the selection is split by what each group can target: every group Cloudflare reports as zone-scoped forms one policy holding all named zones, and groups that can only target an account keep their own account policy on the same token, so one credential can hold DNS access next to account-wide access. A group Cloudflare reports as both takes the zone policy, which is the narrower reading of `--zone`. A group matching neither resource is named and rejected, `--zone` requires at least one zone-scoped group, and `--zone` cannot be combined with `--bucket`, which is a separate credential. The mint summary prints the resources the token reaches, so an account policy alongside the zones is visible rather than implied. `--bucket <name>` switches the policy resource to a single R2 bucket; `--jurisdiction default|eu` selects the provider jurisdiction and defaults to `default`, producing `com.cloudflare.edge.r2.bucket.<account_id>_default_<bucket>` or `com.cloudflare.edge.r2.bucket.<account_id>_eu_<bucket>`. FedRAMP jurisdictions are not supported. Bucket destinations accept only bucket-scoped groups such as Workers R2 Storage Bucket Item Read/Write, and account-scoped groups are rejected. `--s3` requires `--bucket` and stores the S3-compatible credential pair Cloudflare derives from an API token — access key ID is the token ID, secret access key is the SHA-256 hex digest of the token value — as `<dotted.key>.access_key_id` and `<dotted.key>.secret_access_key` under the destination instead of the raw token value; the default endpoint is `https://<account_id>.r2.cloudflarestorage.com`, while EU uses `https://<account_id>.eu.r2.cloudflarestorage.com`. Reconciliation infers each destination's concrete write footprint from the plaintext SOPS key structure — a bearer owns the leaf at its key, while an S3 token owns both pair leaves — and aborts before mutation when managed footprints intersect. `plan` and `apply` renew and revoke S3 destinations like any other brokered token, but renewal first proves the stored access key ID matches the current provider token; an incomplete pair, unreadable value, or identity mismatch is surfaced as a finding and never mutated automatically. `add github` selects the private broker App whose owner matches the destination repository's origin owner, checks both local SOPS leaves before authenticating, proves that the exact selected App is installed on that repository, and writes only while that full App identity still holds the synchronized broker-store entry; missing, duplicate, replaced, or mismatched owners fail before SOPS changes. Durable GitHub tokens cannot be created via API (PAT and OAuth-app creation are UI-only), so workflows mint short-lived installation tokens from the App at runtime (`actions/create-github-app-token`), scoped per repository and permission. The canonical weekly sync expects `bun standards creds add github --dest ci:ci.broker_app`, then mints a current-repository branch writer with Contents write and Workflows write plus a separate PR opener with Contents read and Pull requests write; both mint before sync but enter only their post-sync operations, and missing credentials, unapproved App permissions, or minting failures stop the workflow without a fallback. Existing broker Apps must add Workflows write on the App settings page and have every installation owner approve that permission before consumers adopt the workflow. Bootstrap is once per machine and per GitHub owner: `login github` creates a private personal App, while `login github --org <org>` creates or replaces only that organization's entry; each manifest conversion records GitHub's authoritative owner, and the command opens the installation page, where the App must be bound to selected repositories rather than all repositories. GitHub App names are globally unique and limited to 34 characters, so organization defaults include owners up to 17 characters; a longer owner or a colliding replacement name requires an explicit shorter unused `--name`. The first GitHub-specific command against an existing singleton broker store authenticates as that App, resolves its registration owner, and atomically migrates the old mapping to that one owner; a failed lookup leaves the persisted bytes untouched. If the singleton was a public App installed on repositories owned by other users or organizations, those repositories stop matching after migration because owner selection no longer treats that App as shared. For each affected owner, run `login github` while signed in as that personal owner or `login github --org <owner>`, install the new private App only on the selected repositories, run `bun standards creds add github --dest <target>:<key>` in every consumer, and verify its workflows can mint tokens. Retire the old public App only after every repository owner has its own entry, every intended SOPS destination has been reprovisioned, and token minting has been verified; until then, keep its key and installation available for any destinations not yet migrated. `login cloudflare` guides the one dashboard paste Cloudflare requires for the first account token (named `standards-broker` to match the App, created from the "Create additional tokens" token template because its "Account API Tokens: Edit" permission is unavailable in the custom token builder, and holding that permission only), verifies that it is active, correlates its verified ID with the complete account token list and an active list record, and stores it; a bootstrap token named inside the minted `standards/` namespace is rejected before storage to keep its role unambiguous, while any other divergence from the recommended name only warns. `plan` and `apply` do not rotate GitHub App keys; create a replacement key on the App's settings page, atomically replace that owner's `private_key` in the protected machine-global broker store while preserving its `0600` mode, then update every intended SOPS destination, verify workflows can mint installation tokens, and revoke the old key manually. Root credentials live in the machine-global broker store (see Configuration); SOPS writes go through `sops edit` with a non-interactive editor, preserving comments and reusing the file's data key.
 
 `structure --profile source` validates the standards source repository itself, which is deliberately not a consumer. The profile pins its intentional exceptions so they cannot drift silently: exact, ordered root gate scripts that run this CLI from the local checkout (`structure --profile source`, `dependabot --check` or `dependabot --write`, `github --check`, and the Turbo gate) instead of a recursive `standards check`, and a non-private published bin-only CLI workspace that carries a stable release SemVer and exactly maps the `standards` bin to `src/cli.ts` without `exports`. Every other consumer rule still applies.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "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-login-github-manifest.ts

@@ -47,6 +47,7 @@ const DEFAULT_PERMISSIONS = {
   issues: 'write',
   metadata: 'read',
   pull_requests: 'write',
+  workflows: 'write',
 } as const;
 
 export const buildAppManifest = (

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 { 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,
@@ -158,9 +147,15 @@ 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(
@@ -178,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,
@@ -189,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-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 a branch token with Contents write and Workflows write plus a pull request token with Contents read and Pull requests write 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);