From 5bfbb49d7441fa31d09fd4247893b2b1a7d7828b Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Sat, 26 Sep 2026 09:31:26 +0200 Subject: [PATCH] tools: command records, Instance health group - one bullet per check, examples (#142) Files changed: - CHANGES.md - VERSION - tools/CONTRACT.md - tools/chemenu/commands/doctor.py --- CHANGES.md | 11 +++++- VERSION | 2 +- tools/CONTRACT.md | 25 +++++++++++- tools/chemenu/commands/doctor.py | 67 +++++++++++++++++++------------- 4 files changed, 75 insertions(+), 30 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 32235d6..4b7b83e 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse. --- -## 7.1.0-beta.19 - 2026-09-26 - Command records, Private instances group: one line per cause, examples, prohibitions +## 7.1.0-beta.20 - 2026-09-26 - Command records, Instance health group: one bullet per check, examples **Author:** Torben Nehmer @@ -88,6 +88,7 @@ concern - readable here, never shipped as something to parse. - Command records, Telemetry group: examples, the missing --fail-on-error exit line - Command records, Content migrations group: one line per cause, examples, prohibitions - Command records, Private instances group: one line per cause, examples, prohibitions +- Command records, Instance health group: one bullet per check, examples ### CalDAV task-tracker provider (Nextcloud Tasks, iOS Reminders); review reports unknown-value findings instead of skipping them @@ -324,6 +325,14 @@ single paragraph is now one bullet per step of the merge, and its exit-1 causes fetch failure, a failing git step inside the open merge, and the post-commit leak, which its old record mentioned only in passing - each carry their own reaction. +### Command records, Instance health group: one bullet per check, examples + +`doctor` rewritten the same way; text only. Its one-sentence inventory of every check is now one +bullet per area, each stating which outcome is `OK`, `WARN` or `FAIL`. One stale reason was +dropped rather than moved: the record justified the conventions `FAIL` by `xref`/`cite` writing +out of the section headings, while the check's own docstring calls those headings cosmetic and +grounds the `FAIL` in the file binding every page. + --- ## 7.0.0 - 2026-09-22 - Task-Tracker-Anbindung: Vorhaben als Seitenart, Verpflichtungsschicht, Weekly Review als Read-Time-Join diff --git a/VERSION b/VERSION index 4f97afe..77167cc 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -7.1.0-beta.19 +7.1.0-beta.20 diff --git a/tools/CONTRACT.md b/tools/CONTRACT.md index 99fab0e..68ea468 100644 --- a/tools/CONTRACT.md +++ b/tools/CONTRACT.md @@ -3151,6 +3151,11 @@ Check that this instance is correctly configured. - budget: exempt - network: yes +**EXAMPLES** + +- `tools/wikitool doctor` +- `tools/wikitool doctor --json` + **EXIT STATUS** - 0 success @@ -3162,7 +3167,25 @@ Check that this instance is correctly configured. **NOTES** -Dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, kb/raw/reports/work/instructions structure, personalization (`USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`, since a renamed template is not a filled one), the KB conventions (`kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three, because `xref`/`cite` write out of it), the environment note (`ENVIRONMENT.md` - optional, so absent is `OK`; a still-templated one is a `WARN`), generated files, whether the MCP `submit` tool is armed (`.wikitool-upload.json` present/absent/malformed, its limits, and how many submissions are waiting in `mcp-upload/` - absent is `OK` and means the write path does not exist at all, malformed is the one `FAIL` here, since a broken opt-in must not silently disable the limits it exists to enforce), the task-tracker provider (`.wikitool-tasks.json` present/absent/malformed - absent is `OK` and means no tracker is configured, malformed is `FAIL` for the same reason the upload opt-in is; for a configured `superproductivity` provider, also its configured `access` path's own state - `access: "api"` reports whether its local REST API answers `GET /health` right now, `access: "snapshot"` reports whether a backup file is ready; the *other* access path is never attempted and is not a finding - and neither ever `FAIL`s, an app that is simply not running is not a fault; for a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - also never a `FAIL`, only a broken config block is), the session id source (`OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback - see `chemenu.session`), and telemetry state (on/off, why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session count/byte total against both caps; never `FAIL`, see `EVALS.md`). Read-only, exit 1 only on a `FAIL` (a missing remote, session id, or `VERSION` is a `WARN`, not a fault). Exempt from the Iteration Budget Gate +- Checks dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, the kb/raw/reports/work/instructions structure, and generated files. +- Personalization: `USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`. +- KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three. +- Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated one is a `WARN`. +- MCP `submit` tool: whether `.wikitool-upload.json` is present, absent or malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means the write path does not exist at all; malformed is a `FAIL`. +- Task tracker: `.wikitool-tasks.json` present, absent or malformed - absent is `OK` (no tracker configured), malformed is a `FAIL`. +- For a configured `superproductivity` provider, the configured `access` path's own state: `access: "api"` reports whether its local REST API answers `GET /health` right now, `access: "snapshot"` whether a backup file is ready. The other access path is never attempted, and neither state is ever a `FAIL`. +- For a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - never a `FAIL`; only a broken config block is. +- Session id source: `OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback. +- Telemetry: on or off and why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session's count and byte total against both caps; never a `FAIL`. +- Exits 1 only on a `FAIL`; a missing remote, session id or `VERSION` is a `WARN`, not a fault. +- Read-only and exempt from the Iteration Budget Gate. + +**SEE ALSO** + +- `instructions/setup-instance.md` - the setup steps most findings point back to +- `INSTALL.md` § "Konfiguration" - the per-checkout configuration files +- `EVALS.md` - telemetry state and caps +- `instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID` ## Design notes diff --git a/tools/chemenu/commands/doctor.py b/tools/chemenu/commands/doctor.py index d4e8e8f..6be52fc 100644 --- a/tools/chemenu/commands/doctor.py +++ b/tools/chemenu/commands/doctor.py @@ -628,38 +628,51 @@ def run_doctor() -> list[Check]: budget=cli_contract.Budget.EXEMPT, network=cli_contract.Network.YES, ), - notes="Dependencies (Python, ripgrep), author resolution, stack version, git " - "identity/branch/remote, published skills, kb/raw/reports/work/instructions structure, " - "personalization (`USER.md`/`SOUL.md` present **and** filled - a file still carrying the " - "template's sentinel is a `FAIL`, since a renamed template is not a filled one), the KB " - "conventions (`kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned " - "section headings - a `FAIL` on any of the three, because `xref`/`cite` write out of it), " - "the environment note (`ENVIRONMENT.md` - optional, so absent is `OK`; a still-templated " - "one is a `WARN`), generated files, whether the MCP `submit` tool is armed " - "(`.wikitool-upload.json` present/absent/malformed, its limits, and how many submissions " - "are waiting in `mcp-upload/` - absent is `OK` and means the write path does not exist at " - "all, malformed is the one `FAIL` here, since a broken opt-in must not silently disable the " - "limits it exists to enforce), the task-tracker provider (`.wikitool-tasks.json` " - "present/absent/malformed - absent is `OK` and means no tracker is configured, malformed is " - "`FAIL` for the same reason the upload opt-in is; for a configured `superproductivity` " - "provider, also its configured `access` path's own state - `access: \"api\"` reports " - "whether its local REST API answers `GET /health` right now, `access: \"snapshot\"` reports " - "whether a backup file is ready; the *other* access path is never attempted and is not a " - "finding - and neither ever `FAIL`s, an app that is simply not running is not a fault; for " - "a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - " - "also never a `FAIL`, only a broken config block is), the session id source (`OK` for " - "`WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare " - "parent-pid fallback - see `chemenu.session`), and telemetry state (on/off, why - " - "installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current " - "session count/byte total against both caps; never `FAIL`, see `EVALS.md`). Read-only, exit " - "1 only on a `FAIL` (a missing remote, session id, or `VERSION` is a `WARN`, not a fault). " - "Exempt from the Iteration Budget Gate", + notes=( + "Checks dependencies (Python, ripgrep), author resolution, stack version, git " + "identity/branch/remote, published skills, the kb/raw/reports/work/instructions " + "structure, and generated files.", + "Personalization: `USER.md`/`SOUL.md` present **and** filled - a file still carrying " + "the template's sentinel is a `FAIL`.", + "KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three " + "tool-owned section headings - a `FAIL` on any of the three.", + "Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated " + "one is a `WARN`.", + "MCP `submit` tool: whether `.wikitool-upload.json` is present, absent or malformed, " + "its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means " + "the write path does not exist at all; malformed is a `FAIL`.", + "Task tracker: `.wikitool-tasks.json` present, absent or malformed - absent is `OK` " + "(no tracker configured), malformed is a `FAIL`.", + "For a configured `superproductivity` provider, the configured `access` path's own " + "state: `access: \"api\"` reports whether its local REST API answers `GET /health` " + "right now, `access: \"snapshot\"` whether a backup file is ready. The other access " + "path is never attempted, and neither state is ever a `FAIL`.", + "For a configured `caldav` provider, whether the server is reachable and Basic auth " + "succeeds - never a `FAIL`; only a broken config block is.", + "Session id source: `OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, " + "`WARN` only for the bare parent-pid fallback.", + "Telemetry: on or off and why - installation-form default, `.wikitool-telemetry.json`, " + "or `WIKI_TRACE` - and the current session's count and byte total against both caps; " + "never a `FAIL`.", + "Exits 1 only on a `FAIL`; a missing remote, session id or `VERSION` is a `WARN`, not a " + "fault.", + "Read-only and exempt from the Iteration Budget Gate.", + ), failures=(cli_contract.Failure( - label="", cause="At least one check reported `FAIL` (a `WARN`, e.g. no remote or no " "`WIKITOOL_SESSION_ID`, does not exit 1)", reaction="Each finding names its own fix command; re-run after applying it", ),), + examples=( + "tools/wikitool doctor", + "tools/wikitool doctor --json", + ), + see_also=( + "`instructions/setup-instance.md` - the setup steps most findings point back to", + "`INSTALL.md` § \"Konfiguration\" - the per-checkout configuration files", + "`EVALS.md` - telemetry state and caps", + "`instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID`", + ), )) def doctor_command( json_out: bool = typer.Option(False, "--json", help="Print the checks as JSON"),