docs: apply jargon standards — add a glossary, gloss on first use, fix drift - #10
Merged
Merged
Conversation
…x drift A repo-wide documentation pass (markdown + code comments) applying the project's documentation standards: define load-bearing jargon on first use, keep invented terms sparse, and keep every claim consistent with what the code actually does. - **New `docs/glossary.md`** — the recurring vocabulary (host, reviewer, operator, backend, CLAR, anchored evidence, reconciliation, disposition, deadlock, escalation, independence tier, self-review, consent gate, run record, hermetic, supervisor, raw mode, Fast mode, effort) as mechanism + role. Docs now link here on first use instead of re-defining inline; CLAUDE.md and CONTRIBUTING.md point to it. - **First-use glosses / links** for anchored evidence (protocol.md, README), operator (README), host (codex.md), undetermined (environments.md), and panel-mode's "Workflow layer"/"Guardrails". - **Accuracy fixes (doc vs code):** regenerate the README example-output block and lifetime-recap to match the real renderer (Decisions header, ✅/❌ emoji, "awaiting you"); CONTRIBUTING build gates now match the canonical three (adds the missing ruff gate, uses the repo .venv); security-model's transient-file list (`*.txt` isn't gitignored; scratch is auto-cleaned only on normal exit) and delegate mode (not implemented — present-conditional); reconcile schema-versioning guidance across CONTRIBUTING/CLAUDE; drop the unverifiable "~1.5×" figure; restore codex.md's exact tested CLI version. - **Code comments:** the "F0NN" audit labels now carry a decodable phrase each (they collide across audits); impasse_lib's module docstring and supervise()'s now lead with purpose; the "fast mode" name no longer collides between --raw and --speed. Comments-only — no logic changed. Reviewed cross-provider with Impasse at high effort + fast speed. It caught two containment OVERCLAIMS this pass had introduced — "reliable whole-process-tree teardown" (the code documents setpgid/setsid escapes) and unconditional scratch cleanup (a finally that a SIGKILL bypasses) — plus glossary precision (backend→ endpoint isn't categorical; deadlock isn't the only disposition reaching the operator); all fixed here. Three gates green; voice lint clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X8XaW2bqgYnp7oRVgfHXid
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A repo-wide documentation pass (markdown and code comments) applying the project's documentation standards: define load-bearing jargon on first use, invent sparingly (CLAR earns it), and keep every claim consistent with what the code actually does.
What changed
docs/glossary.md— the recurring vocabulary as mechanism + role (host, reviewer, operator, backend, CLAR, anchored evidence, reconciliation, disposition, deadlock, escalation, independence tier, self-review, consent gate, run record, hermetic, supervisor, raw mode, Fast mode, effort). Docs link here on first use; CLAUDE.md + CONTRIBUTING.md point to it.Decisions:header,✅ resolved/❌ rejected,awaiting you) — they'd drifted and predated the issue-report: show renders "Nothing needed you" for runs the operator actually decided #5 change.CONTRIBUTING.mdbuild gates now match the canonical three (adds the missing ruff gate, uses the repo.venv) — a contributor was shipping un-linted.security-model.md:*.txtisn't gitignored; scratch is auto-cleaned only on normal exit; delegate mode is not implemented (present-conditional).impasse_lib's module docstring andsupervise()'s now lead with purpose; the "fast mode" name collision between--rawand--speedis gone.How it was done
Four read-only review agents (README+SKILL, docs-core, backends+root, code comments) produced term inventories + first-use gaps + code-verified inconsistencies; four writer agents applied disjoint fixes; then the whole diff was dogfooded through Impasse at high effort + fast speed.
That review earned its keep: it caught two containment overclaims this pass had introduced — "reliable whole-process-tree teardown" (the code documents
setpgid/setsidescapes) and unconditional scratch cleanup (afinallyaSIGKILLbypasses) — plus glossary precision (backend→endpoint isn't categorical; deadlock isn't the only disposition reaching the operator). All nine findings fixed here.Three gates green; voice lint clean. Docs + comments only.
🤖 Generated with Claude Code