feat(systems): read-side teeth — the vocabulary at session start, a search filter, and the state/chronicle instructions
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 9s
CI & Build / TypeScript typecheck (push) Successful in 10s
CI & Build / integration (push) Successful in 18s
CI & Build / Python tests (push) Successful in 46s
CI & Build / Build & push image (push) Successful in 25s
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 9s
CI & Build / TypeScript typecheck (push) Successful in 10s
CI & Build / integration (push) Successful in 18s
CI & Build / Python tests (push) Successful in 46s
CI & Build / Build & push image (push) Successful in 25s
Step 4 of #278, product half. The audit that motivated it: one System in project 2, thirty records tagged, nothing since July 28 — three days after the feature landed. Not a discipline failure; retrieval was completely blind to the association (zero references in embeddings, knowledge, search, auto-inject, or enter_project), so tagging was a write-side label with no read-side payoff, and labels nobody reads don't get maintained. Three changes, ordered by what makes the others workable: 1. enter_project returns the project's Systems (id, name, first line of the charter). Load-bearing for the tagging instruction: you cannot ask an agent to check a record against a vocabulary it never sees. Trimmed because it rides on every session start; the full charter stays get_system's job. Present-and-empty rather than absent when a project has none — "no named areas yet" is information the create-the-System instruction acts on. 2. search accepts system_id, MCP and REST (#33). Implemented once in semantic_search_notes as an EXISTS against record_systems — an association filter deciding candidate-set membership before scoring, like project_id, not a ranking signal. The REST route's missing project filter stays #2463's: it carries a default-scope UI decision this change must not preempt. 3. The instructions (#119, _INSTRUCTIONS + using-scribe skill; plugin 0.1.25 for the cache): - Tag as you write, with an executable test — "would someone investigating that subsystem want this in the pile list_system_records returns?" — rather than "tag appropriately", which is what died. - Create the System when the area has no record: the two-or-more test snippets use, plus "don't wait to be asked to name an area that plainly exists", because the agent's default was leaving un-modelled areas un-modelled forever. - State vs chronicle: dev-logs are written once and never rewritten; durable findings live in the System's reference note, updated in place — safe because note versions are the changelog, which has existed since the feature shipped and was never named as one. list_system_records' docstring now sells it as the way to READ a subsystem, reference note first. No auto-inject boost by System — vocabulary and filter first, measure before adding ranking behaviour (the #2486 lesson). Refs #278, #2546
This commit is contained in:
@@ -54,10 +54,29 @@ What each part is for, and when to reach for it:
|
||||
system as a rulebook — rules are for behaviour, and tokens kept as prose
|
||||
cannot be resolved, inherited, rendered to a stylesheet, or checked against
|
||||
code.
|
||||
- System: a per-project, reusable, self-describing subsystem/area. Associate any
|
||||
record (note, task, issue) with it via system_ids so research, build-work, and
|
||||
fixes for the same area line up, and recurring problem-spots surface. Manage
|
||||
with create_system / list_systems / get_system.
|
||||
- System: a per-project, reusable, self-describing subsystem/area — the
|
||||
project's vocabulary for WHERE work happens. enter_project returns the list.
|
||||
TAG AS YOU WRITE: when you create or meaningfully update a note, task, or
|
||||
snippet, ask which of those areas it is about and pass system_ids. The test:
|
||||
would someone investigating that subsystem want this record in the pile
|
||||
list_system_records returns? Cross-cutting records take several; a record
|
||||
about no particular area takes none — don't force it. If the area a record
|
||||
describes has no System yet, CREATE it (create_system: name + a one-paragraph
|
||||
charter) and tag the record — a subsystem that exists in the code deserves a
|
||||
System the moment two records would share it, the same two-or-more test
|
||||
snippets use; don't wait to be asked to name an area that plainly exists.
|
||||
Read a subsystem back with list_system_records, or search(system_id=...) for
|
||||
a ranked cut.
|
||||
- Reference note vs dev-log — STATE vs CHRONICLE. A dev-log records what
|
||||
HAPPENED: write it once, never rewrite it. A durable finding — how a
|
||||
subsystem works, a measured number, an architecture fact — belongs in that
|
||||
System's REFERENCE NOTE ("«System name» — reference", tagged to the System),
|
||||
which is UPDATED IN PLACE as the facts change. Updating loses nothing: every
|
||||
meaningful edit is snapshotted (note versions are the changelog). Create the
|
||||
reference note if the System lacks one; update it if it exists; have the
|
||||
dev-log [[link]] it rather than restating state. State smeared across dated
|
||||
logs is unreachable by search — sixteen near-identical dev-logs tie, and no
|
||||
ranking can pick the right one, because no right one exists.
|
||||
|
||||
Mechanics:
|
||||
- Notes and Tasks share a model; tasks are notes with is_task=True.
|
||||
|
||||
Reference in New Issue
Block a user