Repository navigation
Description
importance is 1-10 on every entry. A write refuses a value outside that range only when the entry is an event. Every other type stores it, and pyrite qa validate then reports the value Pyrite just wrote.
Found by the 2026-11-16 code audit (kb/designs/code-audit-2026-11-16.md, finding H3). Both hallway tests on 2026-11-16 hit it (see #1393).
Steps
dev at bccf8f7 (0.26.3), with HOME, PYRITE_CONFIG_DIR and PYRITE_DATA_DIR pointed at empty directories.
$ pyrite init -t research -p kbs/res -n res --no-examples
$ pyrite create -k res -t person --title "Jane Roe" -b x -f importance=99 --format json
{
"created": true,
"entry_id": "jane-roe",
"entry_type": "person",
"outcome": "done"
}
$ grep -n '^importance' kbs/res/people/jane-roe.md
5:importance: 99
$ pyrite update jane-roe -k res -f importance=77 --format json
{
"updated": true,
"entry_id": "jane-roe",
"locked": false,
"outcome": "done"
}
$ pyrite qa validate res --format json | grep -B1 -A3 '"rule": "importance_range"'
"kb_name": "res",
"rule": "importance_range",
"severity": "warning",
"field": "importance",
"message": "Entry 'jane-roe' has importance 77 (must be 1-10)"The same value on an event, same KB:
$ pyrite create -k res -t event --title "Hearing" -b x -f date=2026-01-02 -f importance=99 --format json
{"outcome": "error", "errors": [{"field": "importance", "rule": "range", "message": "Importance must be 1-10, got: 99", "expected": "1-10"}], "error": "Importance must be 1-10, got: 99", "error_code": "VALIDATION_FAILED", "retryable": false, "suggestion": "use 1-10 for importance"}
$ echo $?
1Expected
The person create and update are refused exactly as the event is: exit 1, VALIDATION_FAILED, the errors row naming importance, nothing written. The same on MCP kb_create and kb_update.
Groom 2026-11-16
Automated groom (architect agent, working for the maintainer). Written so someone new to Pyrite can start from this issue alone. "Checked" means I ran the command or read the line on bccf8f7.
The user's model. "Importance is 1 to 10. If I send 99, Pyrite tells me, whatever kind of entry it is."
The implementation model. One range rule, on the base entry, reached by every write through the one write gate. Design principle 8 (kb/design.md): each rule lives in one place.
The difference today. The rule sits on one subclass. The gate that calls it already runs for every type.
Contracts that apply
kb/design.mdprinciple 8: a rule is enforced at the single point everything passes through.kb/design.mdprinciple 2: a hand-edited file is never refused or repaired for what it already holds. An update that leaves a bad value alone must still succeed.docs/json-contracts.md, "canonical error shape": the refusal isVALIDATION_FAILEDwith anerrorsrow (field,rule,message,expected).kb/maps/types-and-schema.md: its first invariant (write path andqa validateagree) covers enums only. No sibling for ranges is written anywhere; 0.26.4 theme T1: a type is one schema per KB #1528 slice T1-4 writes it. Not this issue's job.
What the code does today (checked)
pyrite/services/kb_service.py:759KBService._validate_writeis the write gate. Create (:1589) and every update path (:1724,:2321,:2350) call it, and it callsentry.validation_errors()for every type. So the enforcement point exists and every surface passes it.pyrite/models/core_types.py:198EventEntry.validation_errorsis the only place the range is checked on a write (:221-232, callingvalidate_importance,pyrite/schema/validators.py:103).pyrite/models/base.py:724Entry.validation_errorschecks id and title only.importanceis a base field (:287), carried by all of the about 40 entry classes (13 in core).- Surprise: a third copy.
extensions/journalism-investigation/src/pyrite_journalism_investigation/validators.py:142-150has its own range check, which runs only in a KB registered with that plugin's type.tests/test_plugin_contract.py:403-446uses it. pyrite/services/qa_service.py:915_check_importance_rangeand:1179report the same rule after the fact, as a warning.- REST bounds the top-level field in pydantic (
pyrite/server/schemas.py:467,:484,ge=1, le=10). MCP only describes it (pyrite/server/tool_schemas.py:784,:844,:874). The CLI has no bound on--importance(pyrite/cli/entry_commands.py:318,:565) or on-f importance=. - The on-disk case already works for events (checked). With
importance: 99hand-written into an event file,pyrite update vote -k res -f location=Hallsucceeds and returns a warning:"rule": "model_validation", "message": "Importance must be 1-10, got: 99", "note": "violation already on disk; kept". That is_validate_write'sprior_model_errors(:783-807). Moving the rule to the base class gives every type this behaviour with no new code.
Invariant and surfaces
A write never stores an importance outside 1-10, on any type, by any surface. A value already in the file is reported, not refused.
| Surface | Today | Evidence |
|---|---|---|
CLI create/update -f importance= |
fails for non-events | steps above |
CLI create/update --importance |
fails for non-events | #1393; PR #1428 adds a usage error in front |
MCP kb_create, kb_update |
fails for non-events | audit H3 probe (99, then 77); not re-run here |
REST create/update, top-level importance |
holds | pydantic bound (read) |
REST, importance inside metadata |
not checked | assumed to fail; the test below settles it |
pyrite add <file> |
an event file is refused today; other types are not | read (:1589), not run |
| Plugins | journalism KBs refuse through their own copy | read |
Hand edit + index sync |
not a write by Pyrite; qa validate reports it |
must stay so |
Shapes (parametrise the test over these):
| Shape | Count | How counted |
|---|---|---|
| Entry classes | about 40 (13 core) | grep -rnE "^class \w+\(" pyrite/models/*.py extensions/*/src/*/*.py | grep -c Entry |
Types defined by kb.yaml alone (GenericEntry) |
1 class, any name | read |
| Values | in range (1, 10); out (0, 11, -5, 99); "7"; "high"; absent |
the event rule's own cases |
| Operation | create; update setting it; update of another field over a bad value on disk; add |
_validate_write callers |
importance: in this repo's own files |
369 lines, 368 in range, 1 template placeholder (<1-10>) |
git grep -hE "^importance:" -- '*.md' | sort | uniq -c |
Options
- A. Move the range row from
EventEntry.validation_errorstoEntry.validation_errors(recommended). About ten lines moved. Every type and surface is covered by the gate that already runs; the on-disk exception comes with it.kb_service.pyis not edited. - B. Check in
_validate_write. Same effect, but it editskb_service.py, which is the busiest file in the tree this month (0.26.4 themes: order of work #1533, "Files that force a series"), and puts a model rule in the service. - C. Wait for 0.26.4 theme T1: a type is one schema per KB #1528 T1-4 (one value check behind
type_spec). Right end state, about three weeks out, andimportanceis a base field whose range does not depend on the type.
Open questions
- Should
qa validatereportimportance_rangeas an error, now that a write refuses it? Today it is a warning. Leave it unless the maintainer says otherwise; note what you find. - The journalism plugin's copy becomes unreachable for a write (the model check raises first). Remove it here, or leave it for 0.26.4 theme T2: a plugin passes the same single points as core #1529? If you remove it,
tests/test_plugin_contract.py::TestValidateWritePrefersMessageneeds another rule-less validator to exercise. pyrite addof a hand-written file withimportance: 99: refused, as an event file is today. Say so in the changelog fragment. If you find that this breaks an import path, report it instead of working around it.
Pointers
pyrite/models/core_types.py (EventEntry.validation_errors), pyrite/models/base.py (Entry.validation_errors, unrepresented_frontmatter), pyrite/services/kb_service.py (_validate_write, read only), tests/test_enum_enforcement.py (a write-gate test over surfaces), tests/conftest.py (cli_world), tests/_world.py.
Checked versus assumed
- Ran: every command above; the on-disk event case.
- Read, not run: MCP and REST paths,
pyrite add. - Assumed: no entry class overrides
validation_errorswithout callingsuper()(grep finds one override,EventEntry, which does call it). - This groom is wrong if some type or importer relies on storing 0 or a value above 10. I found none in
pyrite/,extensions/or the shipped templates. - Predicted footprint:
pyrite/models/base.py,pyrite/models/core_types.py, one new test file, onechangelog.d/*.changed.mdfragment. About 60 lines with tests. If it grows past four source files, stop and say why.
Acceptance: create and update of a non-event with importance 0, 11, -5 or 99 are refused on the CLI
(-f importance=) and on MCP kb_create/kb_update with VALIDATION_FAILED and an errors row
naming importance; no file is written or changed. 1 and 10 are accepted. An update of
another field on a file that already holds importance: 99 succeeds with the
"violation already on disk; kept" warning. The event behaviour is unchanged.
Fails today: the person create in "Steps" exits 0.
Regimes: value already out of range on disk (kept, warned); importance absent (default 5, accepted);
non-numeric value in a hand-written file ("high": kept, as for events today);
a kb.yaml-only type; a plugin type.
Shapes: the table above; one test parametrised over type x value x operation.
Touches: existing: pyrite/models/base.py, pyrite/models/core_types.py
new: tests/test_importance_range_on_every_type.py, changelog.d/<slug>.changed.md
Sequence: independent. PR #1428 (#1393) edits pyrite/cli/entry_commands.py only and stays in front
as a usage error (exit 2) for --importance; write this issue's tests with -f importance=
and MCP so the two do not collide. #1502 is the list-field half of the same audit finding
and is separate. #1528 T1-4 later moves this rule behind type_spec; if #1528 T1-0's
value matrix has landed, remove its expected-failure marker for the importance row here.
Model: sonnet
Size: S
heavy: no
Cold read: no (no new shape; an existing refusal now applies to more types)
Out of scope: list-typed fields (#1502). The CLI --importance usage error (#1393, PR #1428).
MCP schema minimum/maximum (the service refusal is the rule; a schema bound would
answer with a second error shape, see #1508). QA severity. Read-side --min-importance
filters (#1412, #1474).
🤖 Filed by the maintainer's conductor agent (pyrite-architect) (Claude Code)
Activity
markramm commentedon Nov 17, 2026
Claimed by the maintainer's loop, 2026-11-17T02:46Z: a cloud worker is building this on branch
fix/1537-importance-range-every-typefrom the groom above (option A: the range rule moves to the base entry;kb_service.pyis not edited). The groom's three open questions are taken at their defaults for this fix: QA severity stays a warning, the journalism plugin's own copy stays for #1529, andpyrite addof a file with an out-of-range importance is refused as an event file is today. The draft pull request will link here. If you were about to start on it, say so on this issue and the work can be shared or handed over.🤖 Generated with Claude Code
fix: a write refuses importance outside 1-10 on every type (#1537)
test: mark the in-range and event rows of #1537 as controls
refactor: an event's date row stays ahead of the importance row (#1537)
test: plugin-validator tests trigger on a plugin-only rule, not impor…
kb: #1537 done
fix: the importance check never raises, and a blank importance is abs…
fix: compare an importance as a number, not truncated to a whole numb…
docs: say which importance paths compare the number as given, and whi…
fix: a write refuses importance outside 1-10 on every type (pyrite-wi…