kandev/.github/AGENTS.md

GitHub Actions security

Apply this guidance whenever editing .github/**.

• issue_comment and pull_request_target jobs execute the workflow from the trusted default/base branch. Syncing a PR does not change an existing comment-triggered run.
• Never check out or execute an untrusted PR head in a secret-bearing or comment-triggered job before a privileged agent or action. Keep the default branch checkout, use persist-credentials: false, and treat PR metadata, diffs, and files as untrusted data.
• Constrain capabilities in the tool policy, not prompt text alone. For PR-file reads, prefer a small GET-only helper bound to the event PR/head; validate normalized repository-relative paths, regular-file type, response path, size, encoding, and content. Do not grant generic gh api, arbitrary interpreters, or broad Bash merely to read PR files.
• PR label/metadata cleanup jobs that operate on pull requests must declare pull-requests: write, not issues: write; mirror the permission shape used by preview-env.yml.
• Workflow and checkout identity: A workflow_dispatch uses the workflow definition at the selected dispatch ref. An explicit checkout of main selects the files that subsequent steps consume. It does not replace the running workflow definition. Record github.workflow_ref, github.workflow_sha, and the checkout SHA separately. Attribute failures to the definition or consumed files before deciding which branch needs a fix.
• Release workflow changes must trace prepare/summary outputs and conditions through every build and publication job: skip decisions must propagate without accidental publishing, while backfill must reuse and validate the existing tag and still run its required build/publication path. Verify each actual publication job and artifact, not only the aggregate workflow result.
• When validating a public artifact through redirects, inspect the final HTTP status, content type, effective URL, and non-empty body. Intermediate redirect headers do not prove that the delivered artifact is valid.
• For workflow security changes, run the relevant raw workflow-contract tests, python3 .github/scripts/lint-action-pinning_test.py, zizmor .github/workflows, and git diff --check.
• The pr-docs.yml workflow is a base-controlled, metadata-only check. It reads pull-request files through the bounded .github/scripts/pr-docs.cjs adapter; it must never check out or execute a pull-request head.
• Its PR documentation coverage status is revision-specific. The exact no-docs-allow label is the only policy override, and merge-group evaluation must resolve and validate every member independently against the group's entry boundaries. All event types share a non-cancelling target-branch lock with queue: max so queued label reevaluations cannot race with merge-group status writes or replace the single pending run.