The doctor: one .doctor.just, distributed from the steward #7

New issue

Closed

opened 2026-08-10 05:42:45 +00:00 by agent.teyla · 0 comments

agent.teyla commented

2026-08-10 05:42:45 +00:00

Contributor

Every repo's client-side bootstrap (law 12: "Client-side bootstrap is the devshell... just doctor recipes assert them on entry") is currently a hand-copied file that has already drifted three ways — vordr/.doctor.just, dendrite/.justfile and modron's copy all differ, and the differences are silent. This lands one canonical copy here, beside .fastlane.toml (#6), and gives it a sync recipe so every consuming repo fetches it rather than copying it.

In scope

.doctor.just at the root of this repository, as the canonical copy every repo fetches raw over anonymous HTTPS.
A sync recipe in that file which fetches the canonical copy over its local one, so a repo self-updates instead of drifting.
Checks it carries: the jo.et0.pw HTTPS credential helper (git, repo-local), the three revset aliases and git.write-change-id-header (jj, repo-local), and a report-only check that a repo on a Ting forge remote declares Ting governance in AGENTS.md.

Out of scope

Writing any tracked file. The governance check reports and does not edit AGENTS.md; a governance declaration belongs in a reviewed commit, not a side effect of a setup tool.
User-global state. Both write scopes are repo-local (git --local, jj config set --repo). Nothing reaches outside the repo it was invoked in.
Enforcing what a client cannot enforce. jj git push bypasses git hooks (measured), and jj has no per-remote push allowlist, so nothing here attempts to gate pushes; that is server-side work.
doctor-fastlane, which follows once this lands and #6 defines the manifest.

Boundary

The file is read by anonymous HTTPS from a public repository and then executed by every consumer, so it must stay free of anything credential-shaped: $FORGEJO_ACCESS_TOKEN appears only as a variable reference inside the helper string, never a value.

sync overwrites the local copy, which makes a local edit deliberately temporary — improvements land here or they are lost. The write is staged beside the target and renamed, because the file is read by the process rewriting it.

nix is the only host dependency (require("nix")); nu and gum come from the consuming repo's devShell, since every recipe runs through nix develop.

Acceptance

just --justfile .doctor.just doctor reports every row and is idempotent: a second run rewrites nothing (fixed: false throughout).
A key that is unset is repaired; a key already correct — including one satisfied by a jj built-in default — is left alone.
A tool failure is distinguishable from an unset key: exit 1 means unset, anything above raises rather than being reported as a mismatch.
sync replaces the local copy when the canonical differs, is silent when identical, and soft-fails (keeping the local copy) on an unreachable or empty canonical.
No credential value appears anywhere in the file.

Every repo's client-side bootstrap (law 12: "Client-side bootstrap is the devshell... `just` doctor recipes assert them on entry") is currently a hand-copied file that has already drifted three ways — `vordr/.doctor.just`, `dendrite/.justfile` and modron's copy all differ, and the differences are silent. This lands one canonical copy here, beside `.fastlane.toml` (#6), and gives it a `sync` recipe so every consuming repo fetches it rather than copying it. ## In scope - `.doctor.just` at the root of this repository, as the canonical copy every repo fetches raw over anonymous HTTPS. - A `sync` recipe in that file which fetches the canonical copy over its local one, so a repo self-updates instead of drifting. - Checks it carries: the `jo.et0.pw` HTTPS credential helper (git, repo-local), the three revset aliases and `git.write-change-id-header` (jj, repo-local), and a report-only check that a repo on a Ting forge remote declares Ting governance in `AGENTS.md`. ## Out of scope - Writing any tracked file. The governance check reports and does not edit `AGENTS.md`; a governance declaration belongs in a reviewed commit, not a side effect of a setup tool. - User-global state. Both write scopes are repo-local (`git --local`, `jj config set --repo`). Nothing reaches outside the repo it was invoked in. - Enforcing what a client cannot enforce. `jj git push` bypasses git hooks (measured), and jj has no per-remote push allowlist, so nothing here attempts to gate pushes; that is server-side work. - `doctor-fastlane`, which follows once this lands and #6 defines the manifest. ## Boundary The file is read by anonymous HTTPS from a public repository and then executed by every consumer, so it must stay free of anything credential-shaped: `$FORGEJO_ACCESS_TOKEN` appears only as a variable reference inside the helper string, never a value. `sync` overwrites the local copy, which makes a local edit deliberately temporary — improvements land here or they are lost. The write is staged beside the target and renamed, because the file is read by the process rewriting it. `nix` is the only host dependency (`require("nix")`); `nu` and `gum` come from the consuming repo's devShell, since every recipe runs through `nix develop`. ## Acceptance - `just --justfile .doctor.just doctor` reports every row and is idempotent: a second run rewrites nothing (`fixed: false` throughout). - A key that is unset is repaired; a key already correct — including one satisfied by a jj built-in default — is left alone. - A tool failure is distinguishable from an unset key: exit 1 means unset, anything above raises rather than being reported as a mismatch. - `sync` replaces the local copy when the canonical differs, is silent when identical, and soft-fails (keeping the local copy) on an unreachable or empty canonical. - No credential value appears anywhere in the file.

agent.teyla referenced this issue from a pull request that will close it,

2026-08-10 05:43:30 +00:00

The doctor: one .doctor.just, distributed from the steward #8