Projection
update generates CLAUDE.md, AGENTS.md, GEMINI.md, or any target you name, deterministically, and stamps each with the policy hash and the hash of its own content; a hand edit is detected and never silently overwritten
update generates CLAUDE.md, AGENTS.md, GEMINI.md, or any target you name, deterministically, and stamps each with the policy hash and the hash of its own content; a hand edit is detected and never silently overwritten
Where it lives
State it owns
The command that acts on it
majordomus update
Regenerate every provider instruction file from the one policy, deterministically.
- generated-output-mutating
majordomus update [--dry-run] [--diff <target>] [--force]
See it refuse, and accept
One policy, several provider instruction files, generated deterministically. Running it twice leaves byte-identical files, which is what makes a stamp able to detect a hand edit.
Given this repository
# Installed, but the provider instruction files have not been generated yet. "$MJ" init >/dev/null mkdir -p lib && echo a > lib/a && git add . && git commit -qm base
Run
$ majordomus update
Output contains
- create CLAUDE.md
- carries its own stamp
exit
0
Each target named in the policy's projections is written, and a stamp of each is recorded together with the hash of the policy that produced it.
Given this repository
# A repository with Majordomus installed and projections generated, and one commit of work. "$MJ" init >/dev/null "$MJ" update >/dev/null mkdir -p lib docs echo a > lib/a echo d > docs/d git add . && git commit -qm base
Run
$ majordomus update
Output contains
- unchanged CLAUDE.md
exit
0
Deterministic output is not a nicety here. If regeneration produced a different file each time, a stamp could never distinguish a hand edit from the generator's own noise.
What enforces it
- majordomus.bootstrap-integrity blocking enforced by doctor, watch The path from a human reader to the AI layer is unbroken — README.md names AGENTS.md, every generated instruction file points at .ai/README.md, and none of them carries a rule of its own.
- majordomus.projection-integrity blocking enforced by doctor, watch Every generated instruction file exists, matches the stamp it carries, and is never silently overwritten after a hand edit.
- majordomus.context-budget blocking enforced by doctor, watch The always-loaded projection stays within its line budget, every reference in it resolves, it states no count that will go stale, and the assembled context fits the builder's own budget.
What is guaranteed
- guaranteed Every platform, artifact name and installation URL is derived from one model, and a projection that disagrees with it is refusedproved by test/cases/84_distribution_model.sh
- guaranteed The documented one-line install command is composed from the model's parts, and a document that states a different one fails the suiteproved by test/cases/84_distribution_model.sh
- guaranteed A release publishes an artifact for every supported target or it is not publishedproved by test/cases/87_release_pipeline.sh
- guaranteed The install command this project advertises is fetched and run from the published site on every push to the default branch, and the branch is red while it does not install a working toolproved by test/cases/97_install_gate.sh
- guaranteed A release archive carries every path once and carries nothing but files and directoriesproved by test/cases/87b_release_archive_shape.sh
- guaranteed Provider instruction files are generated from the one policy, deterministicallyproved by test/cases/03_update.sh
- guaranteed Every generated instruction file carries its own stamp, and a hand edit is detectedproved by test/cases/03_update.sh
- guaranteed A projection can own only the region between its markers, leaving the rest of the file untouchedproved by test/cases/13_region_projection.sh
- guaranteed A hand-edited instruction file is never silently overwrittenproved by test/cases/03_update.sh
- guaranteed The always-loaded instruction file has a line budget with a failing checkproved by test/cases/03_update.sh
- guaranteed Provider instruction files are thin bootstraps that point at the AI layer and carry no rule of their ownproved by test/cases/03_update.sh
- guaranteed The provider bootstraps the policy declares (AGENTS.md, CLAUDE.md, GEMINI.md, ...) are a target of majordomus generate, rendered from the policy and the provider templates byte for byte as the shell tool renders them, and generate --check refuses a hand-edited or stale one in CIproved by test/cases/93_rust_provider_projections.sh
The moments this answers
- opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository Each provider reads its own hand-edited file, nothing relates them, and which contract applies depends on which tool is open.
- watched the always-loaded instruction file grow past a thousand lines Everything important gets appended to the always-loaded file, so every session pays for every rule and reads none of them carefully.
- changed a policy in one place and found the old one still in force in three others A decision is updated at its source and the generated copies keep serving the previous version, with nothing reporting the difference.
- had a green pipeline over generated files that no longer matched their sources Tests exercise the code and say nothing about the committed outputs derived from it, so the build is green and the artifacts are wrong.
- found the same thing explained three times, slightly differently Every hand-maintained copy of a fact drifts on its own schedule, and a reader cannot tell which copy is the current one.
- spent the first hour in an unfamiliar repository working out what was normal here What is conventional in a codebase is knowledge held by its regulars, so every arrival — human or machine — pays for it again.
- was asked who made a change and under what policy, and had only a commit Attribution stops at the commit, so what authorised a change, what verified it and what governed it are unrecoverable.