Document the repository settings that back the human gates
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 71
- Forks
- 64
- Avg merge
- 15h 38m
- Merged PRs (30d)
- 66
Description
Facility's core claim is that agents cannot approve their own work, cannot merge, and cannot push to protected branches. Some of that is enforced by Facility; some of it depends on how the GitHub repository is configured, and the documentation does not currently say which is which.
That gap is easy to hit: a repository can run the whole loop, look correct, and still allow an automated actor to satisfy a human gate — for example when Allow GitHub Actions to create and approve pull requests is left enabled, or when the default branch has no protection at all.
Scope
- A short section — likely in the security reference, linked from the kickstart and existing-repo guides — listing the repository settings a Facility-governed repository should have, and stating for each whether Facility enforces it or the setting does.
- Cover at least: Actions approving pull requests, default
GITHUB_TOKENpermissions, default-branch protection and required checks, and who may merge. facility doctor --githubalready checks parts of the GitHub side. Where a setting is checkable through the API, say so, and note the ones worth adding todoctoras a follow-up.
Acceptance
- A reader can tell, per setting, whether skipping it weakens a gate the product advertises.
- The guides point at it before the first agent run, not after.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the security reference, kickstart guide, existing-repo guide, and the facility doctor --github checks. Document the required GitHub settings, identify which protections Facility enforces versus repository configuration, and link the reference before the first agent run. Note API-checkable gaps as follow-up work for doctor.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github, github-actions
- Domain
- devops, documentation, security
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 70/100