Problem
scripts/devkit/check_doc_budget.py imports yaml (via scripts/devkit/lib/devmodel_config.py) to read config/dev-model.yaml. PyYAML is not in the standard library, so adopting the kit forces pyyaml into the adopting project's dev dependencies purely for a line-counting tripwire.
Worse, it fails hard rather than degrading:
Traceback (most recent call last):
File "scripts/devkit/check_doc_budget.py", line 46, in <module>
from devmodel_config import _repo_root, get, load_config
File "scripts/devkit/lib/devmodel_config.py", line 22, in <module>
import yaml
ModuleNotFoundError: No module named 'yaml'
Why it matters
The doc-budget check is a warn-only tripwire — the least important thing in the kit. It shouldn't be able to (a) dictate a project's dependency list or (b) abort a /session-start run.
Observed live: it crashed during a /session-start in a project where the dev extra wasn't synced into the active interpreter, which silently disabled the budget check for that session. A tripwire that fails closed and loudly is fine; one that fails with a stack trace and takes the surrounding skill step with it is not.
Proposed fix
Two independent improvements, either helps:
- Stdlib-only reader.
dev-model.yaml uses a small, flat subset of YAML — string/int scalars, nested maps, and simple lists. A ~40-line parser handles it without PyYAML. (Alternative: ship the config as TOML and use tomllib, which is stdlib on 3.11+ — arguably the cleaner answer, at the cost of changing the config format.)
- Degrade instead of crash. Wrap the import; if the config can't be read, print a warning and exit 0. The budget check is advisory — never let it break a session.
Doing (2) alone already removes the sharp edge; (1) removes the dependency.
Acceptance
Source: docs/friction-log.md 2026-07-10 (topij/brain), entry "Doc-budget script needs PyYAML" — reconfirmed live 2026-07-23.
Problem
scripts/devkit/check_doc_budget.pyimportsyaml(viascripts/devkit/lib/devmodel_config.py) to readconfig/dev-model.yaml. PyYAML is not in the standard library, so adopting the kit forcespyyamlinto the adopting project's dev dependencies purely for a line-counting tripwire.Worse, it fails hard rather than degrading:
Why it matters
The doc-budget check is a warn-only tripwire — the least important thing in the kit. It shouldn't be able to (a) dictate a project's dependency list or (b) abort a
/session-startrun.Observed live: it crashed during a
/session-startin a project where the dev extra wasn't synced into the active interpreter, which silently disabled the budget check for that session. A tripwire that fails closed and loudly is fine; one that fails with a stack trace and takes the surrounding skill step with it is not.Proposed fix
Two independent improvements, either helps:
dev-model.yamluses a small, flat subset of YAML — string/int scalars, nested maps, and simple lists. A ~40-line parser handles it without PyYAML. (Alternative: ship the config as TOML and usetomllib, which is stdlib on 3.11+ — arguably the cleaner answer, at the cost of changing the config format.)Doing (2) alone already removes the sharp edge; (1) removes the dependency.
Acceptance
check_doc_budget.pyruns with no third-party dependencies installedpyyamlto a project's dev deps for this reasonSource:
docs/friction-log.md2026-07-10 (topij/brain), entry "Doc-budget script needs PyYAML" — reconfirmed live 2026-07-23.