Skip to content

docs/fork/agent-rules.md + fork-ci doc-check: general agent rules, once - #874

Merged
scuttletoby merged 3 commits into
mainfrom
fork/agent-rules-doc
Nov 22, 2026
Merged

scuttletoby merged 3 commits into
mainfrom
fork/agent-rules-doc

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

Part of #834 (fork audit, G5).

What

  • docs/fork/agent-rules.md (about 6 KB): the general rules for coding agents, each written once with a one-line
    "why". Machine facts (capacity check, agent limits) and project facts (build slot, test servers, where owner
    questions go) stay in the machine's or project's own instruction file and config. Review rules link to
    fork-kit/review (see fork-kit/review: one general review skill; tiers, failure table, nit-only check and a drift test #845) and are not copied.
  • fork-ci/actions/doc-check: a general port of a project's doc check, as a pinnable composite action.
    • Instruction files (AGENTS.md, CLAUDE.md, SKILL.md, plus any the project adds) stay under a size budget;
      it warns above 90% and says when this change crossed the line.
    • No history in instruction files (changelog blocks, "is live on" claims, dated "Updated" banners).
    • Every relative link in a changed Markdown file resolves inside the repository (code fences, URLs and anchors
      skipped).
    • No dated report, handoff or review file is added.
    • Rules come from an optional .github/doc-check.json, read at the base commit so a pull request cannot loosen
      its own rules. Missing, empty or {} means the defaults; a broken config exits 2, never a pass.
    • Tests cover missing/empty/broken config, a file over budget, broken links (including <path with spaces>),
      history patterns, the base-commit rule, --all, and that agent-rules.md itself passes and holds nothing
      personal.
  • The fork-ci README table, FORK_CHANGES.md and .github/fork-ci-tests.txt list the new action.

Rule summary

Section Rules (one line each in the doc)
Instruction files every-time text only; current rules only; where each kind of text goes; a guard deletes its rule text; a wrong-looking rule goes to the owner
General first tooling general by default with a "General vs project" section; checks beat doc rules; no guessed waits or time gates
Machine safety capacity check before heavy work (check && cmd, never piped); build slot + capped slice; stop what you started; guarded deletes; secrets only through their command
Work and pull requests re-check live state; CI decides, no CI-skip marker; small PRs, one push per fix round; known-failing test first; "Fixes #N" only when proven; no manual branch updates; reports in PRs or issues; reviews per the review skill; no git stash; fork stays off upstream; public repos hold nothing personal
Agents and orchestrators model and effort from the policy file; one job per agent; never end a turn on unwatched work; small outputs; responsive orchestrator with a state file outside /tmp; post then read the link back; briefs via Write or <<'EOF'
The owner automate; plain English, recommendation first; read the issue first, one issue per question; sub-agents ask their orchestrator; paste-ready commands at the top; reply last; legal decisions are the owner's

General vs project

  • General (this PR): the rules doc, the doc-check action and its defaults. No project, host, path or model name
    is in the code or the doc.
  • Project (not in this PR): each project's .github/doc-check.json (extra instruction files such as an
    ENGINEERING.md, its own budgets), its AGENTS.md facts (build slot, test servers, owner-question repository,
    state file), the model-guard policy file and the review config. A project adopts doc-check by pinning the action
    at a ci/vN release; a follow-up trims each instruction file to its facts plus a link here.

Not in this PR

  • No instruction file outside this repository is edited; the trim is planned separately.
  • No release tag for the action yet (normal fork-ci release flow after merge).

🤖 Generated with Claude Code

scuttletoby and others added 2 commits November 21, 2026 23:54
docs/fork/agent-rules.md holds the agent rules that hold in every project
and on every machine, each once with a one-line why. Machine and project
facts stay in their own instruction files and config; review rules link
to the review skill instead of being copied.

fork-ci/actions/doc-check is a general port of a project's doc check:
size budgets and a no-history rule for instruction files, broken relative
links in changed Markdown, and no dated report files added. Budgets and
patterns come from an optional project config read at the base commit,
with defaults; a missing or empty config means the defaults, a broken one
exits 2.

Part of #834

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: merge-path · reviewer: lens agent (A: public text, agent rules, doc-check fail-safe) · read at: 910dc3c
verdict: safe to merge
covered: docs/fork/agent-rules.md; fork-ci/actions/doc-check (action.yml, doc_check.py, doc_check.test.py, README.md); the fork-ci README row, FORK_CHANGES.md row, .github/fork-ci-tests.txt line and the git-clean test list change; the commit metadata.
checks: ran doc_check.test.py (24 OK) and git_clean.test.py (60 OK); ran doc_check.py against small throwaway git repos: a deleted doc, a renamed doc, AGENTS.md turned into a symlink, a non-UTF-8 AGENTS.md over budget, a CRLF file, a link in an inline code span, a link in a fenced block inside a list item, a ?query link, the config path being a folder at the base, an unrelated (orphan) history, and a re-run; searched the diff for anything personal.
state: config missing, empty or {} at the base: defaults (tested). Invalid JSON, a non-object, an unknown key or a bad type: exit 2 (tested); the config path being a folder at the base: exit 2 (tried). A config added in the PR itself: ignored, and the base's rules (or the defaults) judge it (tested). A renamed or deleted doc: the links that point at it from untouched files are not checked and the run passes (tried; listed under "Not covered", see minor 3). No base commit: an empty base, a sha that is not there, or no merge base all exit 2 (tested/tried); mode: all needs no base. Re-run: read-only and stateless, the same output (tried). Stopped half-way: it writes nothing, so there is nothing to clean up.
blocker: none
major: none
minor: 1. A budgeted instruction file that a change turns into a symlink is not checked at all (fork-ci/actions/doc-check/doc_check.py:249, :296). Scenario: a 400-line docs/big.md, and AGENTS.md replaced by a symlink to it. git reports a type change (T), --diff-filter=AM drops it, and the run says 1 file(s), 0 problem(s), exit 0. A newly added symlink only warns. Fix: add T to the diff filter. For a symlink that resolves inside the repository, check the target's text against the link path's budget; for any other symlink, report a problem, not a warning.
minor: 2. A non-UTF-8 instruction file is a warning, so its budget, history and links are skipped (doc_check.py:299-304; the test at doc_check.test.py:244 pins this). Scenario: AGENTS.md with 400 lines and one Latin-1 byte gives WARN ... not checked, exit 0. This passes toward green where the brief wants red. Fix: read the bytes; size the file from the bytes and decode with errors='replace' for history and links (or make it a problem).
minor: 3. A deleted or renamed doc leaves broken links in files the change did not touch, and changed mode passes (doc_check.py:249). The README says so, but renames are the main way links break. Scenario: git mv docs/a.md docs/b.md while AGENTS.md links docs/a.md gives exit 0. Fix: when the diff has a D (or a rename's old side), run the link check over every tracked selected file, or over the files whose links name a removed path. It is cheap, and the run stays stateless.
minor: 4. Byte budgets are counted after newline translation (doc_check.py:300, open() with the default newline=None). A CRLF file counts 1 byte short per line. Scenario: a 11,992-byte CRLF AGENTS.md is reported as 11,872 B. A 12,100-byte CRLF file would pass a 12,000-byte budget. Fix: open(path, encoding='utf-8', newline=''), or measure os.path.getsize.
nit: 5. False red from links in code: an inline code span (`[x](missing.md)`) and a fenced block indented four or more spaces inside a list item are both checked (doc_check.py:181-194; FENCE allows only 0-3 spaces). A ?plain=1 query is also reported as "no such file". All three fail red, which is safe, but they are noise; strip inline code spans and the query before the check.
nit: 6. The README's "a pull request cannot loosen the rules that judge it" covers only the config's contents. On pull_request the workflow file comes from the PR, so the PR can change the config:, mode: or base: input, or drop the step. Say so in one line ("protect the workflow file, e.g. CODEOWNERS or a default-branch gate").
nit: 7. docs/fork/agent-rules.md:59, "a move drops +x", is not accurate: mv keeps the mode. What drops it is writing a new file (or a temp file) and moving it over the old one. Suggest: "writing a new file over it drops +x".
nit: 8. docs/fork/agent-rules.md:22-23, "a line outside the repository is named in the pull request", is unclear. It means: rule text outside the repository that the guard replaces is listed in the PR for removal. Say that.
nit: 9. docs/fork/agent-rules.md:24 sends a wrong-looking rule "to the owner", but :82 says a sub-agent asks its orchestrator, never the owner. Add "(a sub-agent: its orchestrator)" to :24.
nit: 10. docs/fork/agent-rules.md:39 names heavy, a fork-kit tool, inside a rule that says the machine supplies these facts. It is public and general, so this is fine, but "the machine's capped wrapper (fork-kit heavy)" would keep the rule free of a tool name.
public text: nothing personal in any changed file or commit. Author and committer are the noreply address, no home paths, IPs, VM ids or account names; the only repository name is the action's uses: line. The doc's own test (doc_check.test.py:270) guards this.
agent rules: each rule is stated once. Machine and project facts are kept out (capacity sizes, build slot, test servers and owner-question repo are all "supplied by" the machine or project file). Review rules link to fork-kit/review/SKILL.md, which exists at this head. Apart from nits 7-9, no rule would mislead an agent.
doc-check shell safety: every input goes through env:; no ${{ }} in a run:; the git-clean check runs first; python3 -I; git runs with hooks, fsmonitor, replace objects and global/system config off; annotation text passes through shown() and escapes %. An unknown mode exits 2.

@scuttletoby
scuttletoby merged commit 27014ac into main Nov 22, 2026
40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant