docs(comments): restore four facts the lint-floor sweep cut

.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. */

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

src/sections/environments/schema.ts

@@ -73,6 +73,9 @@ export type EnvironmentSecretConfig = z.infer<typeof EnvironmentSecretConfig>;
 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 (

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<RepoSecretsKey, ReturnType<typeof sealedSecretConfig>>;
 
+/** The path segment a family's key spells; a fifth family breaking the `<segment>_secrets` naming must say so here. */
 type SegmentOfSecretsKey<K extends RepoSecretsKey> = K extends `${infer S}_secrets` ? S : never;
 
 type SecretsSegment<K extends RepoSecretsKey = RepoSecretsKey> = (typeof SECRETS_SEGMENTS)[K];