diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index dd62e67d68cec..5ff16bf9e7d32 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -72,6 +72,7 @@ .github/scripts/fork-vitest-gc-check.test.cjs .github/scripts/fork-workflow-triggers.test.cjs fork-ci/actions/ci-demand/ci_demand.test.py ~17s +fork-ci/actions/doc-check/doc_check.test.py fork-ci/actions/docs-scope/docs-scope.test.py ~12s fork-ci/actions/fleet-route/fleet_route.test.py fork-ci/actions/fleet-watch/fleet_watch.test.py diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index 425d897509166..30dd6dbd90200 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -62,7 +62,7 @@ These change only how this repository is built, tested and released, not the app | Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) | | A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) | | Secret scan on every push and pull request. Known false alarm: a new pre-release version of a package with "key" in its name, in `pnpm-lock.yaml`, is a finding until its exact value is allowed in `.gitleaks.toml`. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212), [#299](https://github.com/scuttletoby/t3code/pull/299) | -| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned, test-select), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141), [#256](https://github.com/scuttletoby/t3code/pull/256) | +| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned, test-select, doc-check), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141), [#256](https://github.com/scuttletoby/t3code/pull/256) | | fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) | | fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) | | Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far), `desk` (a desktop's side of a fleet desk pool). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183) | diff --git a/docs/fork/agent-rules.md b/docs/fork/agent-rules.md new file mode 100644 index 0000000000000..77800cc25444a --- /dev/null +++ b/docs/fork/agent-rules.md @@ -0,0 +1,85 @@ +# Agent rules (general) + +Fork only. The rules for coding agents that hold in every project and on every machine, each written once. A +project's `AGENTS.md` and a machine's instruction file link here and add only their facts; they never copy a rule. +Where a tool enforces a rule, the tool is the authority. + +## Facts each place supplies + +- The machine's instruction file: its capacity check and sizes, agent limits, how the owner runs a command there. +- The project's `AGENTS.md`: build slot, test servers, where owner questions go, the state file. +- The [model-guard](../../fork-kit/model-guard/README.md) policy file: allowed models and efforts. +- The project's [review](../../fork-kit/review/SKILL.md) and [doc-check](../../fork-ci/actions/doc-check/README.md) + configs: review weights and rounds; instruction file budgets. + +## Instruction files + +- Only what every reader needs every time; the rest is a skill or doc, named in one line with when to read it. + _Why: they are re-read on every call._ +- Current rules only: update in place, delete what you replace. _Why: git keeps history; old text misleads._ +- Decisions go in issue comments; history in git, issues and releases; live state in a state file; lessons in + memory until a tool enforces them; what code or git can tell, nowhere. _Why: one place each._ +- A change that adds a guard (check, hook, test) deletes the rule text it replaces; a line outside the repository + is named in the pull request. _Why: no stale copies._ +- A rule that looks wrong goes to the owner with the reason. _Why: working around it hides the flaw._ + +## General first + +- CI, review, agent and ops tooling is general by default: project facts in a project config file, project-only + parts in a thin adapter, a "General vs project" section in each pull request. _Why: the next project gets it._ +- A check that refuses beats a rule in a doc; call a guard a security boundary only when it is one. + _Why: agents forget; checks do not._ +- No guessed waits, no time gates: wait on real progress, advance when the check passes. _Why: guesses fail._ + +## Machine safety + +- Before a build, a test server or several agents, run the capacity check with the job's size. On no: do not start, + do lighter work, check again on the next wake. Gate with `check && cmd`, never pipe it. + _Why: overload kills agents; a pipe hides the no._ +- Builds and test servers only through the project's build slot and the capped slice (`heavy`). _Why: one cap._ +- Stop every server, watcher, daemon and browser tab you started; list what is left to prove it. + _Why: leftovers starve the next job._ +- Deletes: guarded variables (`rm -rf "${DIR:?}/${NAME:?}"`) or literal paths; look at the target first. + _Why: an empty variable deletes the wrong tree._ +- Never print, commit or paste a key, token or credential file; use it only through its command, and ask for one + only through the secret request tool. _Why: chat and logs are kept._ + +## Work and pull requests + +- Re-check the live state before acting on a brief, a summary or an old status. _Why: facts go stale._ +- CI decides: fix the cause of red CI, never bypass it. No CI-skip marker in a commit message, even quoted. + _Why: it silently skips the real CI._ +- Small, focused pull requests; one push per fix round. _Why: each push restarts CI._ +- A test that fails the same way twice is known-failing: its fix goes first, no reruns. _Why: reruns waste CI._ +- "Fixes #N" only when the fix is proven; else "Part of #N". _Why: merging closes the issue._ +- Never update pull request branches by hand when a merge queue does it. _Why: it restarts every CI at once._ +- Reports, handoffs and review notes go in the pull request or an issue. _Why: the repository holds current text._ +- Reviews follow the [review skill](../../fork-kit/review/SKILL.md) (weights, the state question, round limit); + never restate it. _Why: one source._ +- No `git stash`; edit tracked files in place. _Why: worktrees share the stash; a move drops `+x`._ +- In a fork: build on upstream's mechanisms, check upstream first, never push, comment or open anything upstream. + _Why: thin forks rebase cleanly; upstream is the owner's._ +- Public repositories hold nothing personal (names, hosts, addresses, home paths, tokens). _Why: anyone reads it._ + +## Agents and orchestrators + +- Each task gets a chosen model and effort from the policy file, never the launch default. _Why: cost is a choice._ +- One job per agent. New work is a new agent with a short brief naming the old thread; a running agent gets only + what changes its job. _Why: a long context costs on every call._ +- Never end a turn on your own background run, or on remote work with nothing to wake you; wait in the turn or + register a wake-up and say what will wake you. _Why: nothing else wakes you._ +- Ask tools for small outputs: list limits, JSON fields, `git diff --stat`, test output through `tail`. + _Why: output stays in context._ +- An orchestrator stays responsive: longer work goes to a sub-agent, no sleep or poll loops; it keeps a terse + state file outside `/tmp`. _Why: owner messages wait otherwise._ +- Post first, read the link back from the output, then pass it on. _Why: guessed links are wrong._ +- Write briefs with the Write tool or a quoted heredoc (`<<'EOF'`). _Why: backticks in `< + with: { fetch-depth: 0, persist-credentials: false } + - uses: scuttletoby/t3code/fork-ci/actions/doc-check@ # ci/vN +``` + +A daily or manual run over every file: `with: { mode: all }` (no base needed). Locally, from the repository root: + +```sh +python3 -I fork-ci/actions/doc-check/doc_check.py --base origin/main # the files this branch changes +python3 -I fork-ci/actions/doc-check/doc_check.py --all # every tracked file +python3 -I fork-ci/actions/doc-check/doc_check.py --files AGENTS.md # these files +``` + +| Input | Default | What it is | +| -------- | ----------------------------------- | -------------------------------------------------------------------------------- | +| `config` | `.github/doc-check.json` | the project's config, read at the base commit; optional file | +| `base` | the event's `pull_request.base.sha` | the files changed since `merge-base(base, HEAD)` are checked | +| `mode` | `changed` | `all`: every tracked file the config selects (the config read from the checkout) | +| `path` | `.` | where the repository is checked out | + +Exit 0: no problem (warnings allowed). Exit 1: a rule is broken; each problem is a `DOC` line and an error +annotation. Exit 2: the config, the base or git could not be read; that is never a pass. Read-only and stateless: +a re-run gives the same output. + +## Config + +Every key is optional. A missing file, an empty file and `{}` all mean the defaults below. A key that is present +replaces its default whole (a project that lists `budgets` lists every budget it wants). Keys starting with `_` are +comments. An unknown key, a value of the wrong type or a pattern that is not a regular expression is an error. + +```json +{ + "files": ["**/*.md"], + "exclude": [], + "budgets": [ + { "glob": "AGENTS.md", "lines": 150, "bytes": 12000 }, + { "glob": "**/AGENTS.md", "lines": 100, "bytes": 8000 }, + { "glob": "**/CLAUDE.md", "lines": 40, "bytes": 3000 }, + { "glob": "**/SKILL.md", "lines": 250, "bytes": 8000 } + ], + "warn_at": 0.9, + "history": [{ "pattern": "", "flags": "im", "why": "what it is" }], + "report_name": "", + "report_name_flags": "i", + "links": true +} +``` + +- `files`, `exclude`: globs from the repository root (`**/` any folders, `*` within one name) of the files checked. +- `budgets`: the first matching glob gives a file its budget; a file with a budget is an instruction file (the + history rules apply to it). A project file such as `ENGINEERING.md` gets a line here. +- `history`: the default three patterns are in [doc_check.py](doc_check.py) (`DEFAULTS`); `[]` turns them off. +- `report_name`: `null` turns the dated-report rule off. +- `links`: `false` turns link checks off. + +The config is read at the base commit, never from the checkout, so a pull request cannot loosen the rules that judge +it: a change to the config applies from the next pull request. `mode: all` and `--files` read it from the checkout. + +## Not covered + +- A deleted or renamed file breaks the links that point to it from files the change did not touch; `mode: all` + finds those. +- Anchors (`#section`) are not checked, and neither are backticked paths in the text. +- A symlinked Markdown file is listed as a warning and not checked. diff --git a/fork-ci/actions/doc-check/action.yml b/fork-ci/actions/doc-check/action.yml new file mode 100644 index 0000000000000..aeb08fa74a42f --- /dev/null +++ b/fork-ci/actions/doc-check/action.yml @@ -0,0 +1,48 @@ +name: doc-check +description: >- + Doc rules for the Markdown files agents read: size budgets for instruction files, no history in them, every + relative link resolves, no dated reports added to the repository. Rules from the project's optional config, read at + the base commit. Fails on a broken rule; warns near a budget. Usage: README.md next to this file. +inputs: + config: + description: The project's JSON config (optional file; README "Config"), a plain path, read at the base commit. + required: false + default: .github/doc-check.json + base: + description: >- + The base commit: the files changed since merge-base(base, HEAD) are checked. Needs both commits fetched + (fetch-depth 0). Empty on a pull request: the event's base. Empty elsewhere: an error, unless mode is all. + required: false + default: "" + mode: + description: "changed (the default): the files the change adds or modifies; all: every tracked file the config selects." + required: false + default: changed + path: + description: Where the repository is checked out (actions/checkout's path). + required: false + default: "." +runs: + using: composite + steps: + # Only code from this action's folder (the caller's pinned SHA) runs; nothing from the checkout. Before any git + # call, the checkout's .git config must be one actions/checkout writes (fork-ci git-clean). + - name: Refuse a git config actions/checkout does not write (fork-ci git-clean) + shell: bash + env: + CHECKOUT_PATH: ${{ inputs.path }} + run: exec python3 -I "$GITHUB_ACTION_PATH/../git-clean/git_clean.py" check --path "$CHECKOUT_PATH" --require + - name: Doc rules + shell: bash + env: + CONFIG: ${{ inputs.config }} + BASE: ${{ inputs.base || github.event.pull_request.base.sha }} + MODE: ${{ inputs.mode }} + CHECKOUT_PATH: ${{ inputs.path }} + run: | + cd "$CHECKOUT_PATH" + case "$MODE" in + all) exec python3 -I "$GITHUB_ACTION_PATH/doc_check.py" --config "$CONFIG" --all ;; + changed) exec python3 -I "$GITHUB_ACTION_PATH/doc_check.py" --config "$CONFIG" --base "$BASE" ;; + *) echo "::error::doc-check: mode must be changed or all, not '$MODE'"; exit 2 ;; + esac diff --git a/fork-ci/actions/doc-check/doc_check.py b/fork-ci/actions/doc-check/doc_check.py new file mode 100644 index 0000000000000..d3ba2ddf387de --- /dev/null +++ b/fork-ci/actions/doc-check/doc_check.py @@ -0,0 +1,323 @@ +#!/usr/bin/env python3 +"""doc-check: rules for the Markdown files agents read, on the files a change adds or modifies (or on every file). + + * size budgets (lines and bytes) for instruction files, matched by glob, first match wins; above `warn_at` of a + budget a WARN line that never fails; + * no history in instruction files (changelog blocks, "is live on" claims, dated "Updated" banners); + * every relative link resolves to a file or folder in the repository (code fences are skipped; `/x` is from the + repository root, as GitHub reads it; a link that leaves the repository is broken); + * a newly added file whose name looks like a dated report, handoff or review belongs in the pull request or an + issue, not in the repository. + +The rules come from the project's JSON config (README "Config"); every key is optional and a missing, empty or `{}` +config means the defaults. With --base the config is read at the base commit, never from the checkout, so a change +cannot loosen the rules that judge it (a change to the config applies from the next change); with --all (or --files) it is read from the checkout. A config that is not +valid JSON, has an unknown key or a value of the wrong type is an error (exit 2), never a pass. + + python3 -I doc_check.py --base origin/main [--config .github/doc-check.json] # changed files (CI) + python3 -I doc_check.py --all # every tracked .md file + python3 -I doc_check.py --files a.md b.md # these files +Run from the repository root. Exit 0: no problem (warnings allowed); 1: a rule is broken; 2: the config, git or the +base could not be read. Read-only and stateless: a re-run gives the same output. +""" +import argparse, json, os, re, subprocess, sys +from urllib.parse import unquote + +DEFAULT_CONFIG = '.github/doc-check.json' +DEFAULTS = { + 'files': ['**/*.md'], + 'exclude': [], + 'budgets': [ + {'glob': 'AGENTS.md', 'lines': 150, 'bytes': 12000}, + {'glob': '**/AGENTS.md', 'lines': 100, 'bytes': 8000}, + {'glob': '**/CLAUDE.md', 'lines': 40, 'bytes': 3000}, + {'glob': '**/SKILL.md', 'lines': 250, 'bytes': 8000}, + ], + 'warn_at': 0.9, + 'history': [ + {'pattern': r'\n'}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 1, out) + self.assertIn('CLAUDE.md:1: "live/deployed on" claim', out) + self.assertIn('CLAUDE.md:2: changelog block', out) + + def test_dated_report_only_when_added(self): + self.commit({'docs/REVIEW-2026-01-01.md': 'old\n'}) + base = self.branch({'docs/REVIEW-2026-01-01.md': 'edited\n', 'docs/HANDOFF-2026-02-03.md': 'new\n'}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 1, out) + self.assertIn('DOC docs/HANDOFF-2026-02-03.md: dated report', out) + self.assertNotIn('REVIEW-2026-01-01', out) + + +class Links(Repo): + def test_broken_link_fails_with_its_line(self): + base = self.branch({'docs/a.md': 'See [b](b.md) and [gone](missing.md#top).\n\n[x]()\n', + 'docs/b.md': 'b\n'}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 1, out) + self.assertIn('DOC docs/a.md:1: broken link missing.md: no such file', out) + self.assertIn('DOC docs/a.md:3: broken link sub dir/nope.md: no such file', out) + self.assertNotIn('broken link b.md', out) + + def test_links_that_are_fine(self): + text = ('[web](https://example.com/x) [mail](mailto:a@b) [anchor](#top) [root](/README.md)\n' + '[folder](../docs/) [space]() [enc](sub%20dir/c.md) [img](sub%20dir/c.md "title")\n' + '```\n[in a fence](nowhere.md)\n```\n') + base = self.branch({'docs/a.md': text, 'docs/sub dir/c.md': 'c\n'}) + code, out = self.run_check('--base', base) + self.assertEqual(code, 0, out) + + def test_link_out_of_the_repository_is_broken(self): + base = self.branch({'a.md': '[up](../outside.md)\n'}) + open(os.path.join(self.tmp.name, 'outside.md'), 'w').close() + code, out = self.run_check('--base', base) + self.assertEqual(code, 1, out) + self.assertIn('points outside the repository', out) + + def test_links_off_in_config(self): + self.commit({'.github/doc-check.json': '{"links": false}'}) + base = self.branch({'a.md': '[gone](missing.md)\n'}) + self.assertEqual(self.run_check('--base', base)[0], 0) + + def test_all_mode_reads_every_tracked_file_and_the_checkout_config(self): + self.commit({'docs/a.md': '[gone](missing.md)\n', 'vendor/x.md': '[gone](missing.md)\n', + '.github/doc-check.json': '{"exclude": ["vendor/**"]}'}) + code, out = self.run_check('--all') + self.assertEqual(code, 1, out) + self.assertIn('docs/a.md:1: broken link', out) + self.assertNotIn('vendor/x.md', out) + self.assertIn('rules from .github/doc-check.json', out) + + def test_not_utf8_warns_and_rerun_is_identical(self): + base = self.branch({'a.md': 'ok\n'}) + with open(os.path.join(self.root, 'a.md'), 'wb') as f: + f.write(b'\xff\xfe bad\n') + first = self.run_check('--base', base) + self.assertEqual(first[0], 0, first[1]) + self.assertIn('WARN a.md: cannot read it', first[1]) + self.assertEqual(first, self.run_check('--base', base)) + + +class AgentRulesPage(unittest.TestCase): + """docs/fork/agent-rules.md: the general rules every project links to. Small, every link resolves, and it names + nothing personal (the fork is public): no home paths, machine ids, addresses or account names.""" + PAGE = 'docs/fork/agent-rules.md' + + def test_page_passes_doc_check_and_stays_small(self): + old = os.getcwd() + self.addCleanup(os.chdir, old) + os.chdir(REPO) + out = io.StringIO() + with contextlib.redirect_stdout(out): + code = DC.main(['--config', '/nonexistent/doc-check.json', '--files', self.PAGE]) + self.assertEqual(code, 0, out.getvalue()) + self.assertIn('0 problem(s)', out.getvalue()) + self.assertLessEqual(os.path.getsize(os.path.join(REPO, self.PAGE)), 6500) + + def test_page_names_nothing_personal(self): + with open(os.path.join(REPO, self.PAGE), encoding='utf-8') as f: + text = f.read() + for rx in [r'/home/', r'~/\.', r'\bVM ?\d{2,}', r'\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b', r'@[a-z0-9-]+\.[a-z]', + r'scuttletoby', r'skyrpg', r'\bOpus\b', r'\bFable\b', r'\bSonnet\b']: + self.assertIsNone(re.search(rx, text, re.I), rx) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-ci/actions/git-clean/git_clean.test.py b/fork-ci/actions/git-clean/git_clean.test.py index fbf359ec1ac4f..41c253450a278 100644 --- a/fork-ci/actions/git-clean/git_clean.test.py +++ b/fork-ci/actions/git-clean/git_clean.test.py @@ -1081,8 +1081,8 @@ def test_actions_that_run_git_check_first(self): first = ('\n' + steps).split('\n - ')[1] self.assertIn('git-clean/git_clean.py" check --path', first, f'{path}: the first step must be the check') self.assertIn('--require', first, path) - self.assertEqual(sorted(seen), ['docs-scope', 'handoff-get', 'handoff-put', 'head-check', 'job-changed', - 'pr-queue/tested-base', 'test-select', 'weakened-tests']) + self.assertEqual(sorted(seen), ['doc-check', 'docs-scope', 'handoff-get', 'handoff-put', 'head-check', + 'job-changed', 'pr-queue/tested-base', 'test-select', 'weakened-tests']) def test_git_clean_action_runs_prepare(self): with open(os.path.join(HERE, 'action.yml'), encoding='utf-8') as fh: