feat(B-0156): Phase 6 .py policy CI gate — no-python-files lint

.github/workflows/gate.yml

@@ -874,6 +874,29 @@ jobs:
       - name: Run no-empty-dirs
         run: bun tools/lint/no-empty-dirs.ts
 
+  lint-no-python-files:
+    # Fail if a committed .py file exists outside the allowlist /
+    # vendored-toolchain hard-excludes. Per B-0156 Phase 6
+    # (Aaron 2026-05-01: "any .py" should be ported to TS or
+    # excluded). Script under tools/lint/ respects .gitignore and
+    # the explicit allowlist at tools/lint/no-python-files.allowlist;
+    # references/upstreams, .venv, __pycache__, site-packages, .lake
+    # are hard-excluded by the script itself.
+    # No untrusted input used in run: — only a fixed repo path.
+    name: lint (no python files)
+    timeout-minutes: 3
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install toolchain
+        run: ./tools/setup/install.sh
+
+      - name: Run no-python-files
+        run: bun tools/lint/no-python-files.ts
+
   lint-markdown:
     # markdownlint-cli2 on every .md file outside the ignore list in
     # .markdownlint-cli2.jsonc. Round 33 static-analysis expansion

docs/backlog/P1/B-0156-typescript-standardization-non-install-scripts-aaron-2026-05-01.md

@@ -4,7 +4,7 @@ priority: P1
 status: open
 title: TypeScript standardization — port every .sh outside install graph + every .py to TS (Aaron 2026-05-01)
 created: 2026-05-01
-last_updated: 2026-05-08
+last_updated: 2026-05-16
 decomposition: decomposed
 children: [B-0140]
 depends_on:
@@ -155,11 +155,19 @@ delete the `.sh` siblings to complete the migration. Each
 deletion is reversible via `git revert` if regressions
 surface.
 
-### Phase 6 — `.py` policy enforcement
-
-Add a CI lint that fails on any new `.py` file outside
-`references/upstreams/`. Mechanizable as a pre-commit hook
-or simple `find`-based check in `gate.yml`.
+### Phase 6 — `.py` policy enforcement -- DONE (2026-05-16)
+
+Landed as `tools/lint/no-python-files.ts` (TS+Bun, per Rule 0)
+with an explicit allowlist at
+`tools/lint/no-python-files.allowlist` (starts empty) and a
+unit-test suite at `tools/lint/no-python-files.test.ts`
+(9 tests). Wired into `.github/workflows/gate.yml` as the
+`lint-no-python-files` job, adjacent to `lint-no-empty-dirs`.
+Hard-excludes `references/upstreams`, `.venv`, `__pycache__`,
+`site-packages`, `tools/lean4/.lake`, `node_modules`, `bin`,
+`obj`. Current repo state: 0 flagged, 0 allowlisted (the
+audit baseline this row stated for "Python files in our
+codebase (0)" is mechanically enforced going forward).
 
 ## Acceptance criteria
 

docs/hygiene-history/ticks/2026/05/16/2157Z.md

@@ -0,0 +1,39 @@
+---
+tick: "2026-05-16T21:57Z"
+agent: otto
+mode: autonomous
+operative-authorization: "aaron 2026-05-14: \"- **Devil-pole** (edge-runner drive): keep pushing, discover, go hard, never-be-idle\""
+---
+
+# Tick 2026-05-16T21:57Z — B-0156 Phase 6 lands
+
+- Cron `3b10475a` armed at session start (sentinel re-armed per
+  catch 43 — CronList returned empty).
+- Claim acquired: `B-0156` on branch
+  `otto-cli/b0156-phase6-no-python-lint-2026-05-16` (envelope
+  `1afe3322-422d-40cc-9c1e-d7713b7b384c`).
+- Substrate-drift discriminator on B-0156: all six named `.sh`
+  files in the row (Phases 1-4) are already deleted; their `.ts`
+  ports exist. Phases 1-5 = DONE. Phase 6 (`.py` policy CI gate)
+  was the only outstanding acceptance bullet.
+- Phase 6 implementation (smallest safe slice):
+  - `tools/lint/no-python-files.ts` — TS+Bun port of the
+    `find`-based mechanization candidate the row drafted in YAML,
+    rebuilt against the `no-empty-dirs.ts` template (Rule 0:
+    no `.sh` outside install graph).
+  - `tools/lint/no-python-files.allowlist` — explicit allowlist
+    (starts empty; legitimate exceptions land here with reason
+    comments).
+  - `tools/lint/no-python-files.test.ts` — 9-test `bun test`
+    suite exercising: missing-allowlist → exit 2; clean tree
+    → exit 0; flagged `.py` → exit 1; allowlisted `.py` → exit 0;
+    `references/upstreams` hard-exclude; `.venv` hard-exclude;
+    `__pycache__` hard-exclude; `--list` mode always exits 0;
+    comment/blank lines in allowlist ignored.
+  - `.github/workflows/gate.yml` — new `lint-no-python-files`
+    job adjacent to `lint-no-empty-dirs`, same pattern.
+- Focused checks: 9/9 tests pass; real-repo run reports
+  `0 allowlisted, 0 flagged`; `no-empty-dirs` regression =
+  green; gate.yml parses cleanly (17 jobs, new job present).
+- Backlog row updated: Phase 6 marked DONE; `last_updated`
+  bumped to 2026-05-16.

tools/lint/no-python-files.allowlist

@@ -0,0 +1,21 @@
+# tools/lint/no-python-files.allowlist
+#
+# Repo-relative paths to .py files that are legitimately allowed
+# in this repository despite the B-0156 (Aaron 2026-05-01) policy
+# of "any .py" should be ported to TS or excluded.
+#
+# Format: one repo-relative path per line. Lines starting with `#`
+# and blank lines are ignored. Trailing whitespace (incl. CR for
+# Windows checkouts) is trimmed.
+#
+# Per B-0156 Phase 6: this file starts empty. references/upstreams,
+# .venv, node_modules, __pycache__, site-packages, .lake are hard-
+# excluded by the script itself (HARD_EXCLUDE_PREFIXES /
+# HARD_EXCLUDE_SEGMENTS) and do NOT need to be listed here.
+#
+# Add an entry only when a .py file is genuinely required AND has a
+# documented reason. Example:
+#
+#   # tools/setup/common/foo.py — vendored upstream installer; cannot
+#   # be ported without forking upstream. Tracked in B-XXXX.
+#   tools/setup/common/foo.py

tools/lint/no-python-files.test.ts

@@ -0,0 +1,142 @@
+// no-python-files.test.ts — unit tests for the Phase 6 (B-0156)
+// .py policy lint. We exercise main() against synthetic trees in a
+// temporary directory so the test is independent of repo state.
+
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { main } from "./no-python-files";
+
+function makeRepo(): string {
+  const root = mkdtempSync(join(tmpdir(), "no-python-files-"));
+  spawnSync("git", ["init", "-q", root], { encoding: "utf8" });
+  return root;
+}
+
+function writeAllowlist(root: string, body: string): void {
+  mkdirSync(join(root, "tools", "lint"), { recursive: true });
+  writeFileSync(join(root, "tools", "lint", "no-python-files.allowlist"), body);
+}
+
+function captureStdout<T>(fn: () => T): { result: T; stdout: string; stderr: string } {
+  const realOut = process.stdout.write.bind(process.stdout);
+  const realErr = process.stderr.write.bind(process.stderr);
+  let stdout = "";
+  let stderr = "";
+  process.stdout.write = ((s: string | Uint8Array) => {
+    stdout += typeof s === "string" ? s : new TextDecoder().decode(s);
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((s: string | Uint8Array) => {
+    stderr += typeof s === "string" ? s : new TextDecoder().decode(s);
+    return true;
+  }) as typeof process.stderr.write;
+  try {
+    const result = fn();
+    return { result, stdout, stderr };
+  } finally {
+    process.stdout.write = realOut;
+    process.stderr.write = realErr;
+  }
+}
+
+describe("no-python-files", () => {
+  let originalCwd: string;
+  let repoRoot: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    repoRoot = makeRepo();
+    process.chdir(repoRoot);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test("returns 2 when allowlist is missing", () => {
+    const { result } = captureStdout(() => main([]));
+    expect(result).toBe(2);
+  });
+
+  test("returns 0 when no .py files exist", () => {
+    writeAllowlist(repoRoot, "");
+    writeFileSync(join(repoRoot, "hello.ts"), "// ts\n");
+    const { result, stdout } = captureStdout(() => main([]));
+    expect(result).toBe(0);
+    expect(stdout).toContain("OK");
+  });
+
+  test("returns 1 when a flagged .py file exists", () => {
+    writeAllowlist(repoRoot, "");
+    writeFileSync(join(repoRoot, "rogue.py"), "print('hi')\n");
+    const { result, stderr } = captureStdout(() => main([]));
+    expect(result).toBe(1);
+    expect(stderr).toContain("rogue.py");
+    expect(stderr).toContain("FAIL");
+  });
+
+  test("returns 0 when the only .py file is allowlisted", () => {
+    writeAllowlist(repoRoot, "tools/setup/common/legacy.py\n");
+    mkdirSync(join(repoRoot, "tools", "setup", "common"), { recursive: true });
+    writeFileSync(
+      join(repoRoot, "tools", "setup", "common", "legacy.py"),
+      "print('hi')\n",
+    );
+    const { result, stdout } = captureStdout(() => main([]));
+    expect(result).toBe(0);
+    expect(stdout).toContain("1 allowlisted");
+  });
+
+  test("ignores .py files under references/upstreams (hard-excluded prefix)", () => {
+    writeAllowlist(repoRoot, "");
+    mkdirSync(join(repoRoot, "references", "upstreams", "project"), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(repoRoot, "references", "upstreams", "project", "main.py"),
+      "x = 1\n",
+    );
+    const { result } = captureStdout(() => main([]));
+    expect(result).toBe(0);
+  });
+
+  test("ignores .py files under .venv (hard-excluded segment)", () => {
+    writeAllowlist(repoRoot, "");
+    mkdirSync(join(repoRoot, ".venv", "lib"), { recursive: true });
+    writeFileSync(join(repoRoot, ".venv", "lib", "thing.py"), "x = 1\n");
+    const { result } = captureStdout(() => main([]));
+    expect(result).toBe(0);
+  });
+
+  test("ignores .py files under __pycache__ (hard-excluded segment)", () => {
+    writeAllowlist(repoRoot, "");
+    mkdirSync(join(repoRoot, "src", "__pycache__"), { recursive: true });
+    writeFileSync(join(repoRoot, "src", "__pycache__", "x.py"), "x = 1\n");
+    const { result } = captureStdout(() => main([]));
+    expect(result).toBe(0);
+  });
+
+  test("--list mode returns 0 even when files are flagged", () => {
+    writeAllowlist(repoRoot, "");
+    writeFileSync(join(repoRoot, "rogue.py"), "print('hi')\n");
+    const { result, stdout } = captureStdout(() => main(["--list"]));
+    expect(result).toBe(0);
+    expect(stdout).toContain("Python files (flagged)");
+    expect(stdout).toContain("rogue.py");
+  });
+
+  test("comment and blank lines in the allowlist are ignored", () => {
+    writeAllowlist(
+      repoRoot,
+      "# leading comment\n\n  # indented comment\nrogue.py\n",
+    );
+    writeFileSync(join(repoRoot, "rogue.py"), "print('hi')\n");
+    const { result } = captureStdout(() => main([]));
+    expect(result).toBe(0);
+  });
+});