troupe instructions check reads the instruction files through the loader and reports contradictions between scopes, missing paths, missing programs and repeated rules, preferring a missed finding to a false one¶
Decision 810 · accepted · 2026-10-07 · issue #123
A repository's instruction files reach every prompt (Decisions 706, 798, 806), and nothing
told a team when two of them disagreed, when a rule named a file that had moved, or a
command whose program the machine does not have. troupe instructions check [--workspace
DIR] [--json] does, one line per finding with its file and line, and exits 0 for none, 1
for any and 2 when the workspace cannot be read, so a repository can run it in CI on its
own files.
- The loader's files, and only the loader's. The check is
Troupe.Instructions.Checkin core, beside the loader, and it asksTroupe.Instructions.load/3which files a session reads, as a session that had worked on every file under the workspace would: the focus is each file a walk of the workspace finds, leaving out.git, what.gitignorehides and a directory with a.gitof its own (a submodule, a worktree, another repository). So a nestedAGENTS.mdis checked wherever it is, an alias the loader skipped or a file it would not read (outside) is not, imports come in their importer's scope, and whatever the loader learns to read later (.cursor/rules) comes with it without a change here. Each file the loader read is read again, whole, for its lines, since the loader trims what it puts in the prompt. The brief is Troupe's own and not checked. Not chosen: walking the directories for the four names itself, which forks the discovery and checks files no session reads. - Contradictions are between scopes, within an ecosystem. A command's subject (test,
build, lint, format, run) and its ecosystem are read from a short list (
npm test,pnpm test,yarn test,bun test,mix test,cargo test,go test,pytest,ruff check,black, ...), after its wrappers (mise exec --,uv run, an assignment, a package manager's-C dir) are taken off. A scope is the loader's (user,root, one per nested directory; a file and what it imports are one), and it is held to the nearest scope read before it whose work contains its own and that names the same subject in the same ecosystem: the root holds every nested scope, the person's own file holds everything, siblings hold nothing. The two disagree when they name no command in common. So the root'snpm testandfrontend/AGENTS.md'spnpm testare a finding on the nearer file's line, naming the other; a root'smix testandfrontend/'spnpm testare two parts of a repository; a root that names bothnpm testandpnpm testagrees with afrontend/that names one. Not chosen: any two scopes naming different commands for a subject, which flags every polyglot monorepo; #114's decision model, which would need a model call for a check that must run offline and in CI. - A path is checked only when it reads as one here. In a code span: one starting
./or../, or with a slash that ends in one, names a file with a known extension, or starts with a directory that exists. In a link: any relative target (a leading/is the root's). Resolved from the file's directory and from the root; one that leads out of the repository is not judged. A path that is not there is still no finding when the repository has it under another directory (client/link.exwritten afterlib/troupe/) or.gitignorehides it (_build/). A bare file name (an AGENTS.md) is a kind of file as often as a file here, and a word with a slash is a branch (origin/main), a package or a media type as often as a path, so neither is checked. An@import the loader foundmissingis a finding on its importer's line. The person's own file names paths for every repository, so its paths are not judged here. - A command is checked only where it is plainly one. A code span that starts with a
program from a short list of build tools (
npm,pnpm,mix,cargo,go,mise,make, ...) and has an argument (pytestandmakealone count); every line of a fenced block marked as a shell, after its prompt, comment and assignments, split at&&,||,;and|; a block with no language held to the spans' list; a console block's lines after a prompt; no other language. The program is looked for on thePATHa session's commands get (Troupe.Reaper.child_env/0: in a release, without the release's own runtime), once per file. Not looked for: the shell's own words and builtins, the tools every shell has (ls,grep,curl), PowerShell's cmdlets, and the platform's package managers (apt-get,brew,winget), which say how to set a machine up rather than what the repository runs. Not done yet: running the command, or asking the program whether the subcommand exists (mix check); a program found is taken as the command working. - A rule said twice is a paragraph or a list item of at least five words, compared
without its marks, case and closing full stop, outside fenced blocks, headings and
tables. Its first appearance in the order the files are read stands, and each later
file that says it again is a finding pointing back. Twice in one file is not, and a
skipped alias (a
CLAUDE.mdthat copiesAGENTS.md) is not read, so it repeats nothing. - Prefer missing a finding to a false one. Each detector's narrowness above is that choice: a check that cries wolf on a repository's own files is switched off, and one that is quiet where it is unsure can be widened later, case by case, from the files it missed.
- The TUI reaches it as a door.
troupe instructions checkruns in the TUI's VM, reading the files astroupe config --explainandtroupe doctordo, with no daemon;Troupe.Instructions.Checkjoins the harness modulesmix troupe.xreflets the TUI call, asTroupe.Doctordid.--jsonis the same as one object:workspace,root,files(each withfile,pathandscope) andfindings(each withfile,path,line,kindandmessage).
Governs: apps/troupe_core/lib/troupe/instructions/check.ex, apps/troupe_core/lib/troupe/instructions/check/text.ex, clients/tui/lib/mix/tasks/troupe.xref.ex