From a61d944a00182fee0223c79906320cda092acdcb Mon Sep 17 00:00:00 2001 From: Vivswan Shah <58091053+Vivswan@users.noreply.github.com> Date: Mon, 26 Oct 2026 15:57:54 -0400 Subject: [PATCH] docs(comments): restore four facts the lint-floor sweep cut An audit of the comment lines the sweep removed found four whose fact went with the wording: how the dry-run push judges the token (origin's receive-pack advertisement over the real push's channel), an example of an execution-phase read (the Codespaces sealing key), GitHub's 422 on both deployment-branch flags true and on both false, and the instruction that a fifth secret family breaking the _secrets naming must say so at the type that spells it. Each returns beside the thing it explains, one line where the member-shape rule wants one. --- .github/scripts/post-green-steps.ts | 4 ++-- src/sections/contract/endpoints.ts | 3 ++- src/sections/environments/schema.ts | 3 +++ src/sections/shared/secrets-and-variables/repo-secrets.ts | 3 ++- 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/scripts/post-green-steps.ts b/.github/scripts/post-green-steps.ts index 0a2d612dd..9523d30fa 100644 --- a/.github/scripts/post-green-steps.ts +++ b/.github/scripts/post-green-steps.ts @@ -14,14 +14,14 @@ import { attempt, requireEnv, setOutput } from "./lib/workflow-step.js"; /** What each subcommand writes to GITHUB_OUTPUT; test/workflows/post-green-workflow.test.ts judges the job's wiring from it, as from the shell steps' echo lines. */ export const STEP_OUTPUTS = { probe: ["proceed"] } as const; -/** Refused for a token without write access and creates nothing, against a ref that never exists, so git cannot refuse a non-fast-forward locally whatever the token. */ +/** A dry-run push asks origin for its receive-pack advertisement over the real push's channel, so a token without write access is refused and nothing is created. */ const DRY_RUN_PUSH = [ "git", "push", "--dry-run", "--quiet", "origin", - "HEAD:refs/dry-run/token-probe", + "HEAD:refs/dry-run/token-probe", // a ref that never exists, so git cannot refuse a non-fast-forward locally whatever the token ]; /** The text's lines as awk would read them: no trailing record for a final newline, none at all for empty text. */ diff --git a/src/sections/contract/endpoints.ts b/src/sections/contract/endpoints.ts index e88446dcb..d8fcbac72 100644 --- a/src/sections/contract/endpoints.ts +++ b/src/sections/contract/endpoints.ts @@ -41,7 +41,8 @@ type PermissionOverride = SectionPermission | "none"; /** * A read's phase. Omitted, the read is available to plan(), so check mode and preflight may meet it. "execution" - * gates it behind the ExecTools token only a thunk receives (ReadPort in ./plan.ts), so check mode never issues it. + * gates it behind the ExecTools token only a thunk receives (ReadPort in ./plan.ts), so check mode never issues it + * (the Codespaces sealing key, for one). * * e2e mock -> treats an execution read in check mode as a violation * denialPosture() -> rejects a primaryRead on it: no denied first read can be classified from it diff --git a/src/sections/environments/schema.ts b/src/sections/environments/schema.ts index 3a95e717e..8c0e0e6a2 100644 --- a/src/sections/environments/schema.ts +++ b/src/sections/environments/schema.ts @@ -73,6 +73,9 @@ export type EnvironmentSecretConfig = z.infer; const DeploymentBranchPolicy = open(DeploymentBranchPolicyFlags.unwrap().shape) .check( rule((flags, refineCtx) => { + // GitHub accepts exactly one flag on: both true is a 422, and both false is a 422 too, since "any branch may + // deploy" is spelled `deployment_branch_policy: null`. + // A raw flag beside its own shape issue is neither setting: two equal raw values (0 and 0, a YAML alias // to one mapping) are not both false, nor both true. if ( diff --git a/src/sections/shared/secrets-and-variables/repo-secrets.ts b/src/sections/shared/secrets-and-variables/repo-secrets.ts index 6468a353b..b07a3510b 100644 --- a/src/sections/shared/secrets-and-variables/repo-secrets.ts +++ b/src/sections/shared/secrets-and-variables/repo-secrets.ts @@ -51,7 +51,7 @@ export type RepoSecretsKey = | "codespaces_secrets" | "agents_secrets"; -/** The routes derive from THIS map, so a key paired with another family's segment (which the mock would faithfully serve) is unrepresentable; the `satisfies` pins each value to the segment its key spells. */ +/** Routes derive from THIS map, so a key under another family's segment is unrepresentable (the mock would serve the swap and hide it). */ const SECRETS_SEGMENTS = { actions_secrets: "actions", dependabot_secrets: "dependabot", @@ -67,6 +67,7 @@ const SECRETS_ENTRIES = { agents_secrets: AgentsSecretConfig, } as const satisfies Record>; +/** The path segment a family's key spells; a fifth family breaking the `_secrets` naming must say so here. */ type SegmentOfSecretsKey = K extends `${infer S}_secrets` ? S : never; type SecretsSegment = (typeof SECRETS_SEGMENTS)[K];