Skip to content

docs: apply jargon standards — add a glossary, gloss on first use, fix drift - #10

Merged
windaddict merged 1 commit into
mainfrom
docs/jargon-standards-glossary
Aug 9, 2026
Merged

docs: apply jargon standards — add a glossary, gloss on first use, fix drift#10
windaddict merged 1 commit into
mainfrom
docs/jargon-standards-glossary

Conversation

@windaddict

Copy link
Copy Markdown
Owner

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

  • New 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.
  • First-use glosses/links for the terms readers hit cold: anchored evidence, operator, host, undetermined, and panel-mode's "Workflow layer"/"Guardrails".
  • Accuracy (doc vs code):
    • README example-output block + lifetime-recap regenerated from the real renderer (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.md build gates now match the canonical three (adds the missing ruff gate, uses the repo .venv) — a contributor was shipping un-linted.
    • security-model.md: *.txt isn't gitignored; scratch is auto-cleaned only on normal exit; delegate mode is not implemented (present-conditional).
    • Reconcile schema-versioning guidance across CONTRIBUTING/CLAUDE; drop the unverifiable "~1.5×"; restore codex.md's exact tested CLI version.
  • Code comments (comments-only, no logic): the private "F0NN" audit labels now each carry a decodable phrase (they collide across audits); impasse_lib's module docstring and supervise()'s now lead with purpose; the "fast mode" name collision between --raw and --speed is 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/setsid escapes) and unconditional scratch cleanup (a finally a SIGKILL bypasses) — 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

…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
@windaddict
windaddict merged commit 83bc295 into main Aug 9, 2026
2 checks passed
@windaddict
windaddict deleted the docs/jargon-standards-glossary branch August 9, 2026 20:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant