fix: /dotbot never ran — invalid permissions scope rejects dotbot-act.yml

[wezell]

What

/dotbot has never worked in this repo, and the cause is one line:

    permissions:
      contents: write
      workflows: write      # ← no such GITHUB_TOKEN scope
      pull-requests: write
      issues: write

workflows: write is not a valid permission scope, so GitHub rejects the whole workflow file. Every push records a failed run named after the file path with no jobs:

X This run likely failed because of a workflow file issue.

All 28 recorded runs of this workflow are that failure. No /dotbot comment has ever triggered one, so Act mode has been a no-op since the scope was introduced — and the DOTBOT_ACT_MODEL wiring from #7 could never be exercised.

Caught by uvx --from actionlint-py==1.7.12.25 actionlint:

.github/workflows/dotbot-act.yml:31:7: unknown permission scope "workflows".
all available permission scopes are "actions", … "statuses" [permissions]

Fix

• Drop the invalid scope. The intent (let /dotbot edit .github/workflows/*) is a token concern: the GITHUB_TOKEN used to push cannot update workflow files, and the escape hatch is a PAT with the workflow scope — not a workflow-level permission.
• Checkout token falls back: ${{ secrets.REPO_ACCESS_TOKEN || github.token }}, so Act runs where no PAT exists (this repo has none). Documented trade-offs: pushes made with the workflow token don't trigger further workflow runs, and can't touch workflow files.
• README corrected — its Act example carried the same invalid workflows: write, so anyone copying it got a dead workflow; the "workflows: write is required" note now explains the PAT scope instead.
• Guards: test_workflow_permissions_use_known_scopes asserts every permissions: scope is one GitHub knows (verified: it fails on the old file, passes now), and CI runs actionlint so invalid workflows are reported before they are pushed.

Verification

• uvx --from actionlint-py==1.7.12.25 actionlint → clean, exit 0
• uv run pytest -q → 808 passed; pre-commit run --all-files (ruff, mypy) → Passed
• After merging: a /dotbot probe on a scratch PR to confirm Act starts and resolves the act model from DOTBOT_ACT_MODEL (the org value is ~deepseek/deepseek-flash-latest)

[github-actions]

dotbot code review:

• Reviewer: meta/muse-spark-1.3 (medium)
• Overall: patch is correct
• New findings this run: 0
• Prior unresolved dotbot findings still relevant: 0
• Active findings total: 0

Incremental change only extends permission-scope guard to top-level permissions with no logic errors.

Tip: comment with "/dotbot address comments" to attempt automated fixes for unresolved review threads.

_{reviewed by dotbot · meta/muse-spark-1.3 · medium}

[github-actions]

dotbot code review:

• Reviewer: ~z-ai/glm-latest (medium)
• Overall: patch is correct
• New findings this run: 0
• Prior unresolved dotbot findings still relevant: 0
• Active findings total: 0

The incremental change addresses the prior top-level permissions gap cleanly via a shared _check helper, correctly handling string shorthands, dicts, and missing/None blocks. No new issues are introduced.

Tip: comment with "/dotbot address comments" to attempt automated fixes for unresolved review threads.

_{reviewed by dotbot · ~z-ai/glm-latest · medium}

[github-actions]

✅ dotbot review: all reviewer models (meta/muse-spark-1.3, ~z-ai/glm-latest) agree — patch is correct.

_{approved automatically by dotbot}