From 0d348f1f1c2a6b2c7ef76257fa4894a09ae74c3d Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah Date: Tue, 30 Jun 2026 03:31:30 -0700 Subject: [PATCH] Refresh diagnostics documentation --- docs/check-parallelism.md | 11 +++++++++++ docs/doctor-findings.md | 1 + docs/observability.md | 8 +++++--- 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/check-parallelism.md b/docs/check-parallelism.md index 709a818..695a717 100644 --- a/docs/check-parallelism.md +++ b/docs/check-parallelism.md @@ -63,6 +63,17 @@ After all probe PIDs exit, the parent shell parses the files, validates required fields, adds any parent-owned results, and only then renders text or calls the Python JSON renderer. +Python-backed project artifact and IDE diagnostics use bounded subprocess +probes instead of the shell background result-file collector. The shared +diagnostic timeout is `process.DIAGNOSTIC_TIMEOUT_SECONDS` (10 seconds), and it +is passed to Homebrew artifact checks, Brewfile and mise delegate probes, IDE +extension and app-install probes, Python artifact package probes, and Git remote +diagnostics. When one of these subprocess probes times out, the Python layer +returns the normal finding ID for that probe with timeout-specific text, usually +as a warning when the diagnostic is informational. The parent `check`/`doctor` +rendering still preserves the same deterministic text and JSON order; the +timeout changes the finding content, not the ordering contract. + ## Constraints - Preserve `basectl check --format json` schema and ordering. diff --git a/docs/doctor-findings.md b/docs/doctor-findings.md index 131c6b9..2db23bd 100644 --- a/docs/doctor-findings.md +++ b/docs/doctor-findings.md @@ -145,6 +145,7 @@ Doctor commands use the same diagnostic item fields. The top-level | `BASE-P161` | Manifest command project script path readiness | | `BASE-P170` | Project Python version requirement support window | | `BASE-P171` | Selected project Python interpreter availability | +| `BASE-P172` | Actual inspectable project Python runtime: environment manager, virtualenv path, interpreter path, and Python minor version | `BASE-P050` is the stable project virtual-environment readiness finding. The Bash setup/check path reports detailed venv health messages when a project venv diff --git a/docs/observability.md b/docs/observability.md index 95b3e02..0df97c4 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -2,9 +2,9 @@ > **STATUS** — `basectl history` and the local history index are implemented as > the first slice. `basectl explain last-error`, `basectl report`, and history -> cleanup integration remain future work. +> cleanup integration are tracked but not scheduled longer-term future work. -Issue: #396 +Tracker: [#396](https://github.com/basefoundry/base/issues/396) Base currently exposes raw runtime logs through `basectl logs` and structured local command metadata through `basectl history`. This document defines the @@ -144,7 +144,7 @@ The retention contract should be: log path safely, but `basectl history` should mark missing logs clearly. - Durable user state under `~/.base.d` is never cleaned by history retention. -## Future Commands +## Shipped Commands ### `basectl history` @@ -168,6 +168,8 @@ Expected options: `basectl logs` should remain the command for opening or tailing raw log files. `basectl history` should point to logs, not replace them. +## Planned Commands + ### `basectl explain last-error` `basectl explain last-error` should find the latest failed history record,