stack 3/5: add first-contributor trust lane

.github/scripts/pr-trust-lane.cjs

@@ -0,0 +1,100 @@
+"use strict";
+
+const FIRST_TIME_ASSOCIATIONS = new Set([
+  "FIRST_TIMER",
+  "FIRST_TIME_CONTRIBUTOR",
+  "NONE",
+]);
+const MAX_FIRST_TIME_CHANGED_LINES = 500;
+const RESTRICTED_PREFIXES = [
+  ".github/workflows/",
+  "src/auth/",
+  "src/oauth/",
+];
+const RESTRICTED_FILES = new Set([
+  "scripts/release.ts",
+  "package.json",
+  "bun.lock",
+]);
+const IMPLEMENTATION_PREFIXES = ["src/", "gui/", "scripts/", "tests/", "bin/", "packages/", ".github/workflows/"];
+const IMPLEMENTATION_FILES = new Set(["package.json", "bun.lock", "tsconfig.json"]);
+
+function isFirstTimeContributor(authorAssociation) {
+  return FIRST_TIME_ASSOCIATIONS.has(String(authorAssociation || "").toUpperCase());
+}
+
+function isImplementationPath(path) {
+  return IMPLEMENTATION_FILES.has(path) || IMPLEMENTATION_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+
+function isRestrictedPath(path) {
+  return RESTRICTED_FILES.has(path) || RESTRICTED_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+
+function changedLines(files) {
+  return (files || []).reduce(
+    (total, file) => total + Number(file.additions || 0) + Number(file.deletions || 0),
+    0,
+  );
+}
+
+function linkedIssueHasLabel(linkedIssues, labelName) {
+  return (linkedIssues || []).some((issue) =>
+    (issue.labels || []).some((label) =>
+      (typeof label === "string" ? label : label?.name) === labelName,
+    ),
+  );
+}
+
+function assessTrustLane({
+  authorAssociation,
+  authorHasPushPermission = false,
+  files = [],
+  linkedIssues = [],
+  otherOpenImplementationPrs = [],
+}) {
+  if (authorHasPushPermission || !isFirstTimeContributor(authorAssociation)) return [];
+  if (!files.some((file) => isImplementationPath(file.filename))) return [];
+
+  const failures = [];
+  if (otherOpenImplementationPrs.length > 0) {
+    failures.push({
+      code: "active_pr_limit",
+      pullRequests: otherOpenImplementationPrs,
+    });
+  }
+
+  const size = changedLines(files);
+  if (
+    size > MAX_FIRST_TIME_CHANGED_LINES &&
+    !linkedIssueHasLabel(linkedIssues, "large-change-approved")
+  ) {
+    failures.push({
+      code: "first_pr_too_large",
+      changedLines: size,
+      maximum: MAX_FIRST_TIME_CHANGED_LINES,
+    });
+  }
+
+  const restricted = files
+    .map((file) => file.filename)
+    .filter(isRestrictedPath);
+  if (
+    restricted.length > 0 &&
+    !linkedIssueHasLabel(linkedIssues, "maintainer-sponsored")
+  ) {
+    failures.push({ code: "restricted_surface", paths: restricted });
+  }
+
+  return failures;
+}
+
+module.exports = {
+  MAX_FIRST_TIME_CHANGED_LINES,
+  assessTrustLane,
+  changedLines,
+  isFirstTimeContributor,
+  isImplementationPath,
+  isRestrictedPath,
+  linkedIssueHasLabel,
+};

.github/scripts/pr-trust-lane.test.cjs

@@ -0,0 +1,79 @@
+"use strict";
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const {
+  MAX_FIRST_TIME_CHANGED_LINES,
+  assessTrustLane,
+  isFirstTimeContributor,
+  isRestrictedPath,
+} = require("./pr-trust-lane.cjs");
+
+describe("first-time classification", () => {
+  it("classifies GitHub first-time associations", () => {
+    assert.equal(isFirstTimeContributor("FIRST_TIMER"), true);
+    assert.equal(isFirstTimeContributor("FIRST_TIME_CONTRIBUTOR"), true);
+    assert.equal(isFirstTimeContributor("NONE"), true);
+    assert.equal(isFirstTimeContributor("CONTRIBUTOR"), false);
+  });
+
+  it("recognizes restricted security and dependency surfaces", () => {
+    assert.equal(isRestrictedPath(".github/workflows/ci.yml"), true);
+    assert.equal(isRestrictedPath("src/oauth/provider.ts"), true);
+    assert.equal(isRestrictedPath("package.json"), true);
+    assert.equal(isRestrictedPath("src/router.ts"), false);
+  });
+});
+
+describe("assessTrustLane", () => {
+  const smallRuntimeChange = [{ filename: "src/router.ts", additions: 40, deletions: 5 }];
+
+  it("limits first-time authors to one active implementation PR", () => {
+    const failures = assessTrustLane({
+      authorAssociation: "FIRST_TIME_CONTRIBUTOR",
+      files: smallRuntimeChange,
+      otherOpenImplementationPrs: [812],
+    });
+    assert.deepEqual(failures[0], { code: "active_pr_limit", pullRequests: [812] });
+  });
+
+  it("rejects oversized first implementation PRs without approval", () => {
+    const failures = assessTrustLane({
+      authorAssociation: "FIRST_TIMER",
+      files: [{ filename: "src/router.ts", additions: MAX_FIRST_TIME_CHANGED_LINES + 1, deletions: 0 }],
+    });
+    assert.equal(failures[0].code, "first_pr_too_large");
+  });
+
+  it("allows oversized work when the linked issue approves it", () => {
+    const failures = assessTrustLane({
+      authorAssociation: "FIRST_TIMER",
+      files: [{ filename: "src/router.ts", additions: 700, deletions: 0 }],
+      linkedIssues: [{ labels: [{ name: "large-change-approved" }] }],
+    });
+    assert.deepEqual(failures, []);
+  });
+
+  it("requires sponsorship for restricted surfaces", () => {
+    const failures = assessTrustLane({
+      authorAssociation: "NONE",
+      files: [{ filename: ".github/workflows/ci.yml", additions: 10, deletions: 2 }],
+    });
+    assert.equal(failures[0].code, "restricted_surface");
+  });
+
+  it("allows sponsored restricted work", () => {
+    const failures = assessTrustLane({
+      authorAssociation: "NONE",
+      files: [{ filename: "src/oauth/provider.ts", additions: 10, deletions: 2 }],
+      linkedIssues: [{ labels: ["maintainer-sponsored"] }],
+    });
+    assert.deepEqual(failures, []);
+  });
+
+  it("does not restrict established contributors, maintainers, or docs-only PRs", () => {
+    assert.deepEqual(assessTrustLane({ authorAssociation: "CONTRIBUTOR", files: smallRuntimeChange }), []);
+    assert.deepEqual(assessTrustLane({ authorAssociation: "NONE", authorHasPushPermission: true, files: smallRuntimeChange }), []);
+    assert.deepEqual(assessTrustLane({ authorAssociation: "NONE", files: [{ filename: "README.md", additions: 900 }] }), []);
+  });
+});

.github/workflows/pr-trust-lane.yml

@@ -0,0 +1,172 @@
+name: PR trust lane
+
+on:
+  pull_request_target:
+    types: [opened, reopened, edited, synchronize, ready_for_review]
+
+# Trusted default-branch script only; no PR-head checkout or execution.
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: pr-trust-lane-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  trust-lane:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout trusted trust-lane script
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+          sparse-checkout: .github/scripts
+
+      - name: Enforce first-contribution limits
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
+        with:
+          script: |
+            const path = require("node:path");
+            const { extractLinkedIssueNumbers } = require(
+              path.join(process.cwd(), ".github", "scripts", "pr-admission.cjs"),
+            );
+            const {
+              assessTrustLane,
+              isImplementationPath,
+            } = require(
+              path.join(process.cwd(), ".github", "scripts", "pr-trust-lane.cjs"),
+            );
+
+            const { owner, repo } = context.repo;
+            const pull_number = context.payload.pull_request.number;
+            const marker = "<!-- pr-trust-lane -->";
+            const blockedLabel = "intake: trust-lane-blocked";
+
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number });
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner, repo, pull_number, per_page: 100,
+            });
+
+            let permission = "read";
+            try {
+              const response = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner, repo, username: pr.user.login,
+              });
+              permission = response.data.permission;
+            } catch (error) {
+              core.warning(`Permission lookup failed: ${error.message}`);
+            }
+            const authorHasPushPermission = ["admin", "maintain", "write"].includes(permission);
+
+            const linkedIssues = [];
+            for (const issue_number of extractLinkedIssueNumbers(pr.body)) {
+              try {
+                const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number });
+                if (!issue.pull_request) linkedIssues.push({ number: issue.number, labels: issue.labels });
+              } catch (error) {
+                core.warning(`Could not load issue #${issue_number}: ${error.message}`);
+              }
+            }
+
+            const open = await github.paginate(github.rest.pulls.list, {
+              owner, repo, state: "open", per_page: 100,
+            });
+            const otherOpenImplementationPrs = [];
+            for (const candidate of open) {
+              if (candidate.number === pull_number || candidate.user?.login !== pr.user.login) continue;
+              const candidateFiles = await github.paginate(github.rest.pulls.listFiles, {
+                owner, repo, pull_number candidate.number, per_page: 100,
+              });
+              if (candidateFiles.some((file) => isImplementationPath(file.filename))) {
+                otherOpenImplementationPrs.push(candidate.number);
+              }
+            }
+
+            const failures = assessTrustLane({
+              authorAssociation: pr.author_association,
+              authorHasPushPermission,
+              files,
+              linkedIssues,
+              otherOpenImplementationPrs,
+            });
+
+            async function ensureLabel() {
+              try {
+                await github.rest.issues.getLabel({ owner, repo, name: blockedLabel });
+              } catch (error) {
+                if (error.status !== 404) throw error;
+                try {
+                  await github.rest.issues.createLabel({
+                    owner,
+                    repo,
+                    name: blockedLabel,
+                    color: "b60205",
+                    description: "First-contribution limits require maintainer approval",
+                  });
+                } catch (createError) {
+                  if (createError.status !== 422) throw createError;
+                }
+              }
+            }
+
+            async function setBlocked(blocked) {
+              const labels = new Set(pr.labels.map((label) => label.name));
+              if (blocked && !labels.has(blockedLabel)) {
+                await ensureLabel();
+                await github.rest.issues.addLabels({
+                  owner, repo, issue_number: pull_number, labels: [blockedLabel],
+                });
+              } else if (!blocked && labels.has(blockedLabel)) {
+                await github.rest.issues.removeLabel({
+                  owner, repo, issue_number pull_number, name: blockedLabel,
+                });
+              }
+            }
+
+            async function upsert(body) {
+              const comments = await github.paginate(github.rest.issues.listComments, {
+                owner, repo, issue_number: pull_number, per_page: 100,
+              });
+              const existing = comments.find(
+                (comment) => comment.user?.login === "github-actions[bot]" && comment.body?.includes(marker),
+              );
+              if (existing) {
+                await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+              } else {
+                await github.rest.issues.createComment({ owner, repo, issue_number: pull_number, body });
+              }
+            }
+
+            if (failures.length === 0) {
+              await setBlocked(false);
+              await upsert(`${marker}\n\n✅ **Contributor trust-lane requirements passed.**`);
+              return;
+            }
+
+            await setBlocked(true);
+            const lines = failures.flatMap((failure) => {
+              if (failure.code === "active_pr_limit") {
+                return [
+                  "### One active implementation PR",
+                  `Close or finish ${failure.pullRequests.map((n) => `#${n}`).join(", ")} before opening another implementation PR.`,
+                  "",
+                ];
+              }
+              if (failure.code === "first_pr_too_large") {
+                return [
+                  "### First contribution is too large",
+                  `This PR changes ${failure.changedLines} lines; the first-contribution ceiling is ${failure.maximum}. Split it, or obtain \`large-change-approved\` on the linked issue before implementation.`,
+                  "",
+                ];
+              }
+              return [
+                "### Maintainer sponsorship required",
+                `Restricted paths: ${failure.paths.map((p) => `\`${p}\``.),.join(", ")}. The linked issue needs \`maintainer-sponsored\` before a first-time contributor changes these surfaces.`,
+                "",
+              ];
+            });
+            await upsert([marker, "", "⚠️ **First-contribution limits blocked this PR.**", "", ...lines].join("\n"));
+            core.setFailed(`Trust lane failed: ${failures.map((f) => f.code).join(", ")}`);

docs/superpowers/specs/2026-08-02-pr-trust-lane-design.md

@@ -0,0 +1,12 @@
+# New-contributor trust lane — Design
+
+**Stack:** 3/5, based on `agent/pr-readiness-gate`
+
+First-time contributors get a deliberately narrow lane until the repository has evidence that they can scope, validate, and maintain their submissions.
+
+- One active implementation PR per first-time author.
+- Maximum 500 changed lines for a first implementation PR unless the linked issue has `large-change-approved`.
+- Workflow, OAuth/authentication, release, and dependency surfaces require `maintainer-sponsored` on the linked issue.
+- Documentation-only work, established contributors, and repository collaborators are exempt.
+
+The workflow uses PR metadata and GitHub APIs only. It does not inspect whether code was written by AI and does not execute untrusted code.