Glossary

Glossary

The canonical vocabulary of this wiki and of the kit, in the six groups the documentation uses. Terms in bold are the canonical forms enforced by the run's terms.json; the right column names the rejected near-synonyms where they exist — one concept, one term, across every page. Definitions are traced to the source at 7e17a11 or to this run's tests.

Contents

• Doctrine
• Phases and process
• Tools and mechanisms
• Artefacts
• GitHub wiki mechanics
• Sandbox and operations
• See also

---

Doctrine

Term	Definition	Not this
the kit	this repository/toolchain as a whole: doctrine docs + 11 Python tools + 3 shell scripts + templates + examples	the tool, the framework, the product (ambiguous with individual tools)
the one rule	a claim enters the wiki only if traced to a source line, or reproduced by executing the software	golden rule, core principle
subject	the repository being documented	target repo; project (ambiguous — could mean the kit)
run	one end-to-end execution of the four phases	session, pass (for the phases)
reference run	the completed MD.Viewer run the kit was extracted from: 22 files, 73,013 words, 154 alerts, 27 mermaid diagrams, 1,687 table rows, 341 wiki-links, 0 QA errors	"original run"
field run (run 2)	the MD.Scribe 3.1.0 run behind the 1.1.0/1.2.0 hardening: 23 pages, 41,623 words, 249 empirical checks, 14 verified doc-vs-code discrepancies	—
verification channel	either half of the one rule: (a) source tracing or (b) execution	—
provenance	the source discipline on every fact: code:file:line | readme | git | test:name | web:url	—
doc-vs-code discrepancy	a documented claim the executed software contradicts; recorded, corrected in the wiki, and banned from returning	—
drift finding	a measured behaviour that no longer matches an expectation recorded from an earlier build (this run found two in the current MD.Viewer)	—

Phases and process

Term	Definition
Phase 1 — research (~40% of effort)	bootstrap → clone → repo_scan.py → run and probe the subject → the five research files
Phase 2 — wiki architecture (~3%)	page tree in PROGRESS.json; ban.json from sources §D; terms.json from the glossary
Phase 3 — writing (~45%)	new_page.py --init scaffold → fill pages (hardest first) → fix_toc.py per rewrite
Phase 4 — QA and delivery (~12%)	--self-test → --strict to zero errors → re-run documented commands → publish.sh → REPORT.md
phase boundary	the moment state files are updated and a snapshot taken — not "at the end"
recovery point	STATE.md / PROGRESS.json / REWORK-STATE.md / research/ — enough for a fresh agent to resume without re-deriving anything ("checkpoint" is acceptable in prose)
effort budget	the measured 40/3/45/12 split from the reference run
hand-over	the delivery package when pushing is impossible: prepared clone + verified bundle + PUBLISH.md

Tools and mechanisms

Term	Definition	Not this
battery	a declarative set of probe requests: traversal (20 payloads), injection (26), headers (10 security + 4 leak), flags, disk	test suite (reserve suite for the registered functions)
suite	a registered probe function (Probe, entry) -> dict: generic, php-mdviewer, or yours	—
staged instance	ServedApp's clean throwaway copy of the subject on a verified-free port, killed on exit	test server, sandbox app
verified-free port	a port bound by a probe socket before the server starts; a busy preferred port raises instead of drifting	free port (weaker)
body marker	a substring asserted in a response body, because a status code alone can be meaningless (front controllers answer 200 for everything)	content check
evidence	JSON/Markdown artefacts recording requests, statuses, headers, excerpts — the reproducible backing for [tested] claims	"proof", "output"
runtime floor	the subject's declared minimum runtime (composer.json → require.php, engines.node, go.mod); mismatch = exit 2, because probing an unbootable subject measures a corpse	—
capability report	bootstrap's inventory of installed tools, stdlib modules and network egress	env report
scrubbed view	page text with fenced/inline code, [[wiki-links]], anchor targets and filenames blanked (offsets preserved) before ban/avoid/filler matching	cleaned text
negation downgrade	a banned-phrase hit preceded in-sentence (~90 chars) by a negation/hedge becomes a WARNING — never a suppression	suppression (it is the opposite)
exemption	{phrase, file?, quote?, reason} entry making a legitimate hit report as INFO, visible forever, never silently dropped	whitelist
ban list (ban.json)	phrases that must never appear, built from sources.md §D; affirmative forms only	blocklist
terms file (terms.json)	canonical terms (counted, never failing) + avoided synonyms (errors) + _tuning_log	glossary file (the glossary is this page / the domain-notes section)
self-test	a tool's built-in proof that it can fail: qa 22 detections, fix_toc 8, evidence 3, session 8 (live PHP)	—
QA-clean by construction	scaffold output passes qa_wiki.py --strict unfilled (verified across three page lists, T8)	—
negative control	a deliberately broken input proving a CI step fails when the defect returns (five named in the 1.2.1 verification)	—

Artefacts

Term	Definition
the five research files	summary.md, architecture.md, domain-notes.md, facts.json, sources.md — Phase 1's output and Phase 3's input
sources.md §D	claims deliberately NOT made, with reasons; the most valuable section, because it becomes ban.json
facts.json	machine-readable fact base; every value carries its source
PROGRESS.json	page tree + groups + style contract + do_not_claim + QA numbers + delivery state
STATE.md / REWORK-STATE.md	orientation file / recovery artefact (resume recipe, environment rebuild, quirks, append-only log)
REPORT.md	the closing report: inventory, verification methods, doc-vs-code findings, sources, and the honest limits of the analysis
PUBLISH.md	the written push instructions: clone path, branch, SHA, remote, bundle, three options, never-force-push rule, post-publish checklist
bundle	git bundle of the wiki commit — verified with git bundle verify; cloning one directly needs -b master (no HEAD symref, else an empty tree and vacuous checks)

GitHub wiki mechanics

Term	Definition
the filename rule	files are named with spaces (Security Hardening Guide.md); GitHub maps them to hyphenated URLs and resolves [[Page Name]] against that; hyphenated filenames kill every such link
GitHub slug	heading → anchor: lowercase; strip everything except alphanumerics/spaces/hyphens/underscores; spaces→hyphens; do not collapse repeated hyphens; dedupe -1, -2. Computed by tooling, never hand-written
chrome files	_Sidebar.md and _Footer.md — underscore-prefixed, rendered on every page, not listed; the sidebar must link every page
alert	`> [!NOTE
fence nesting	an example containing a fence needs a longer outer fence (four backticks around three); the early-close bug renders the rest of the page as garbage
wiki repo	OWNER/REPO.wiki.git, default branch master, created by GitHub only after the first UI page save

Sandbox and operations

Term	Definition
PITFALLS	setup/PITFALLS.md — 31 traps in four classes (A wrong-answers, B sandbox, C wiki, D process), ordered by time wasted; A1–A3 produce silently wrong results
A1 / stale server	a port collision makes the new server die while tests hit the old one — the worst offender, and the reason serve.py exists
B4 / path mangling	absolute workspace paths inside heredocs and script files can be rewritten or left literal by the harness; resolve paths at runtime inside scripts (this run's field discovery)
B11 / visibility loss	a long probe losing sight of parts of the workspace filesystem mid-run; the reason evidence.py writes with fallbacks
snapshot	snapshot.sh's git commit of the whole workspace at a phase boundary, so a bad bulk edit costs minutes
D2 discipline	distrust your own checker once: verify one case by hand on mass failure; verify it can fail on mass success
terminal-less sandbox	no controlling terminal, closed stdin: no prompts anywhere, git push fails → bundles and hand-overs are the delivery model

---

See also

• Configuration Reference — the schemas behind ban.json, terms.json, PROGRESS.json
• Tool Reference — every term's owning tool
• Writing Pages Guide — the style contract the glossary enforces
• Sandbox Survival Guide — the PITFALLS classes in operational context
• Home — wiki entry point