Skip to content

Maintenance, checks and CI

Chapter 15 of the ResearchTools manual. Back to table of contents.

This chapter is for the person who keeps the toolkit healthy: proving a change, deploying it to ~/.claude, closing a branch, and publishing this site. Installing and updating a machine is in chapter 01.

The green stamp

scripts/test/run-offline-tests.ps1 finds every .claude/**/Test/test_*.py suite and runs it with no network, no API key and no model. Each suite is graded PASSED, FAILED or NOT RUN (a suite that cannot import a third-party package). A full pass writes .rt-green.json, a hash per code file, and any failure deletes it. The stamp is what lets install-junctions.ps1 -Sync copy a hook or a skill script into ~/.claude: only a file a green run has proven is copied, and the rest is held and named. The interpreter is .venv-skills of this clone, then of the main clone from a worktree, and the script refuses with the rebuild command (.\setup.ps1 -InstallPython) rather than falling back to whatever python is on the PATH.

Checks

Script Proves Runs
scripts/test/run-offline-tests.ps1 Every Python suite, and writes the green stamp about 15 minutes
scripts/test/run-all-checks.ps1 The suite, then every verify-*.ps1 of scripts/test, each in its own process. Exit 0 only if all pass about 15 minutes
scripts/audit/check-deployment.ps1 Read-only: does ~/.claude match the repository (agents by hash, skill links, hooks, contract block, settings entry, green stamp, interpreter) seconds
scripts/audit/check-claude-template.ps1 Read-only drift check of CLAUDE.template.md against the live global file, plus the write-path invariants seconds
scripts/audit/check-graph-health.ps1 What the code graph holds and whether it is stale. Reserved to the local-writer agent, since it reads the graph seconds

run-all-checks.ps1 takes -DryRun (list, run nothing), -SkipSuite, -Only a,b, -Exclude names, -ReportPath file.json and -Jobs N. It leaves out verify-graph-health.ps1 for the same reason as above.

Speed (-Jobs). Both scripts run their work side by side instead of one item at a time, because one sequential run left the machine at 20 to 25 percent CPU. -Jobs 0, the default, takes 90 percent of the logical processors, a share written with its provenance in scripts/lib/rt-runner.json. -Jobs 1 gives the old sequential run, -Jobs 8 caps it at eight. In run-offline-tests.ps1 the slowest suites start first. A suite that fails while others run beside it is run again alone: if it passes alone it is listed as flaky under parallel load and counted as passed, and if it fails again it is a real failure. The run then needs more memory, about one Python process per job. verify-parallel-runner.ps1 proves the pool.

The twelve verifiers in scripts/test/ each prove one installer or tool by running it for real against a throwaway home or repository, never your own:

Verifier Proves
verify-branch-tools.ps1 run-all-checks.ps1 and finish-branch.ps1
verify-daemon-install.ps1 setup.ps1 -InstallDaemon and the OBSIDIAN_VAULT offer
verify-graph-health.ps1 The graph health script (local-writer only)
verify-no-personal-data.ps1 No published file carries the account name of whoever runs it
verify-parallel-runner.ps1 The parallel pool of the two runners: job count, overlap, order of results, rerun of a failure alone
verify-python-env.ps1 setup.ps1 -InstallPython: the three environments, their order, one pin per library, every requirements file registered
verify-python-libs.ps1 Every third-party import is declared and the library tables of chapter 02 are current (scripts/docs/python_libs.py --check)
verify-rt-contract.ps1 The generated RT-CONTRACT block of the global CLAUDE.md
verify-setup-writes.ps1 The three writes setup.ps1 makes to the global configuration
verify-sync-writes.ps1 The two irreversible writes of -Sync and what it selects
verify-template-audit.ps1 The title gate in check-claude-template.ps1
verify-venv-resolution.ps1 How every launcher finds its interpreter

Five more live beside their skill and are not run by run-all-checks.ps1: scripts/local/Test/verify-claude-switch.ps1, the three verify-*.ps1 in .claude/skills/aider-setup/scripts/Test/, and verify-kit-install.ps1 for the student kit.

Improving ResearchTools from another folder

Code written to work around a weakness in ResearchTools goes inside ResearchTools, at the level of the skill, agent or command that carries the weakness, never in the paper, thesis or grant folder. The protocol, written in .claude/CLAUDE.md, has eight steps: find the owner and extend its code with a flag, read .rt-green.json, copy each file to .rt-undo/ before changing it, prove the fix with a test and a full suite, loop at most three times, roll back after the third failure, make the fix active with install-junctions.ps1 -Sync, and log one line in IMPROVEMENTS.md. Nothing is committed by that protocol.

From a change to a merged branch

  1. A change that opens a pull request has a GitHub Issue and a card on the project board (R30).
  2. Update the documentation of what the change touched in the same pull request (R31, R33), see chapter 08.
  3. Before the pull request opens, run the bounded security and code review of R35 and fix what it finds. The review bounds are declared first, see chapter 11.
  4. Regenerate the mirrors with install.ps1 -Profile <active> and commit them in the same pull request. Then run scripts/test/run-all-checks.ps1 once, after the last commit. Its verify-mirrors-fresh.ps1 fails when the mirrors were not regenerated.
  5. Open the pull request. The owner merges it, never a session.
  6. After the merge, from the main clone: .claude/skills/finish-branch/scripts/finish-branch.ps1 -Branch <branch> -Refresh. The finish-branch skill (command /finish-branch, or "clean the project") runs these steps in order and shows the dry run before any -Yes.

-Refresh runs setup.ps1 -Update -Profile <active> -RunSuite -NonInteractive -Force after the clean-up. It adds -Personal when the merged pull request changed an agent, a command or a rule, and passes -KeepHooks on. It prints a reminder to run mkdocs gh-deploy when docs/ changed. A failed refresh exits 1. finish-branch.ps1 removes the merged branch's worktree, deletes the branch locally and on origin, prunes, and moves a plans folder from docs/superpowers/todo to done. It is a dry run until -Yes, and it never uses --force. It refuses, listing every reason at once and changing nothing, when no merged pull request has that head, when the local or the origin branch is not on the merged commit, when the main clone is not on the main branch or holds modified tracked files, when the worktree is dirty, holds git-ignored files (unless -DiscardIgnored) or holds a junction or symbolic link, and when it is started from inside the worktree it removes. A second run finds nothing to clean and exits 0.

Continuous integration

Two GitHub workflows run on pull requests. privacy-scan.yml is free and static: it scans the added commits for secrets and personal-data shapes. review.yml is billed and optional: a headless review posts one consolidated comment. Both are described in chapter 15. There is no workflow that runs the test suites, they are run by hand as above.

This documentation site

The site is built by MkDocs Material (the libraries of .venv-docs are listed in chapter 02) from mkdocs.yml at the repository root and the pages under docs/. Chapter order is the nav list in that file, and the chapter table in README.md and in docs/index.md follows it. A chapter that is added, removed or renamed updates all three.

Task Command
Install the tools, once .\setup.ps1 -InstallPython, which builds .venv-docs from requirements-docs.txt with the other environments (chapter 01, Step 5)
Preview .venv-docs\Scripts\python.exe -m mkdocs serve, then open the printed local address
Check links and anchors .venv-docs\Scripts\python.exe -m mkdocs build --strict, which must print no warning
Publish .venv-docs\Scripts\python.exe -m mkdocs gh-deploy, run by hand from main after the merge

MkDocs serves only docs/. The build hook scripts/docs/mkdocs_hooks.py rewrites a link that reaches outside docs/ (to README.md or .claude/CLAUDE.md, for example) into its page on GitHub, on the branch named by extra.docs_source_ref in mkdocs.yml. Those links therefore work only once the change is on that branch, which is why publishing happens after the merge. A push to main never updates the published site by itself, and the deploy is the only way the live pages change.

Deployed services

deploy/ holds the container set for the form-service HTTP API: docker-compose.yml, a Caddyfile reverse proxy, initdb/ which enables pgvector on the PostgreSQL 17 container, and form-service/ for the service itself. Its boundary with ThesisTracker is in chapter 17.


← 15 Security audit and guards | Table of contents | 17 ThesisTracker integration →