roadkeep 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/guarding.py
ADDED
|
@@ -0,0 +1,1028 @@
|
|
|
1
|
+
"""The barrier at the agent boundary: a governed write refused before it happens (RK22).
|
|
2
|
+
|
|
3
|
+
L1 puts the schema where the text is created, and every command in this package honours it
|
|
4
|
+
— but only for text that arrives *through* a command. With Markdown as the store (L2), an
|
|
5
|
+
agent can bypass the entire format with one `Edit`, and will, because `Edit` is cheaper than
|
|
6
|
+
reading a `--help`. `lint` catches it at the commit, which is a whole turn of prose too late:
|
|
7
|
+
by then the tokens are spent and what the report asks for is a deletion. So this is the one
|
|
8
|
+
enforcement point an agent cannot route around — a `PreToolUse` hook, run by the harness
|
|
9
|
+
*before* the tool call, answering one question: **is this path a file that some project's
|
|
10
|
+
`roadkeep.toml` says is governed?** For a `Bash` payload, which names no path, it is the same
|
|
11
|
+
question asked of the command's characters, and the answer is `ask` rather than `deny` (RK128).
|
|
12
|
+
|
|
13
|
+
If it is, the write is denied and the reason *is the command to call instead*, with its
|
|
14
|
+
flags. That second half is the whole value: a refusal that names no alternative is a refusal
|
|
15
|
+
an agent works around, and one that names the command makes the denial the cheapest path
|
|
16
|
+
forward rather than an obstacle.
|
|
17
|
+
|
|
18
|
+
Five decisions, each because the opposite breaks a session rather than a rule:
|
|
19
|
+
|
|
20
|
+
* **The config is discovered from the file, not from the working directory.** A harness
|
|
21
|
+
edits across repositories, and a hook installed in `~/.claude/settings.json` sees all of
|
|
22
|
+
them. Walking up from the path being written is the one rule that answers correctly for a
|
|
23
|
+
monorepo, a worktree and a global install, with a single implementation.
|
|
24
|
+
* **Silence is the allow.** Nothing is ever returned for a file this does not govern.
|
|
25
|
+
``allow`` in this protocol *is* an approval, and emitting it would bypass the permission
|
|
26
|
+
rules the user set for every unrelated file in the repository — a guard that widens what
|
|
27
|
+
an agent may write is worse than no guard.
|
|
28
|
+
* **Every failure allows.** A malformed payload, an unreadable `roadkeep.toml`, a tool
|
|
29
|
+
input carrying no path: all allow. A guard that denies on its own errors turns one typo
|
|
30
|
+
in a config file into a repository nobody can edit, and RK14 still refuses the file at
|
|
31
|
+
the commit — the gate is the backstop for the barrier, not the other way round.
|
|
32
|
+
* **`Bash` is matched, and answered with `ask` rather than `deny`** (RK128). It used not to be
|
|
33
|
+
matched at all, on the argument that parsing shell to catch one `sed -i` is a tax on every
|
|
34
|
+
command — but the refusal above says *roadkeep owns its writes*, and an agent told that will
|
|
35
|
+
believe it, so silence there was the barrier claiming a side it did not hold. Nothing parses
|
|
36
|
+
shell: the one decidable question is whether a path this project declares appears in the
|
|
37
|
+
command at all, and where it does, what the command *does* to it is the harness's user to
|
|
38
|
+
answer. `deny` would refuse `git add docs/ROADMAP.md` and every `git log --` of a governed
|
|
39
|
+
file; `allow` is not this hook's to give. So the third answer is the honest one, and the
|
|
40
|
+
`Stop` hook still runs `lint` behind it — and, since RK175, :func:`attested`, because a
|
|
41
|
+
`sed` the user approves leaves a *conforming* line `lint` has no quarrel with.
|
|
42
|
+
* **The decision travels in the payload, never in the exit code.** The harness reads a
|
|
43
|
+
non-zero exit as *the hook itself failed*, so this is the one command in the package that
|
|
44
|
+
always exits 0 (see :func:`roadkeep.cli._guard`) and says everything in its output.
|
|
45
|
+
|
|
46
|
+
The same process answers `SessionStart` (RK82), because the barrier only ever spoke to a
|
|
47
|
+
session that had already decided to write: :class:`Notice` states which files are governed
|
|
48
|
+
here, once, before the first read. The other candidate — a `PreToolUse` matcher on the
|
|
49
|
+
reading tools — is not taken, on the argument `Bash` gets above: paying on every read to
|
|
50
|
+
catch what one resident line already said is a tax, and reading is never refused anyway.
|
|
51
|
+
|
|
52
|
+
That start is also where a **drifted vendored copy** is named (RK234). `install --check` was
|
|
53
|
+
the gate holding the copy in step and no adopting project ran it, so a session read a skill
|
|
54
|
+
78 lines behind the file it came from with the trust of the original. Asked here because this
|
|
55
|
+
process *is* the wired checkout and the copy is what the session is about to load, and cheap
|
|
56
|
+
enough to ask unconditionally: :func:`~roadkeep.installing.stale` costs one `is_file` where
|
|
57
|
+
there is no copy at all.
|
|
58
|
+
|
|
59
|
+
**One module, three events, and each event's imports are its own** (RK260). What the three need
|
|
60
|
+
is disjoint: `PreToolUse` wants the config, the tool names and the invocation; `SessionStart`
|
|
61
|
+
wants :func:`~roadkeep.installing.stale`; `Stop` wants `linting`, `attesting` and `history`.
|
|
62
|
+
Imported at module level, that made the hook the harness waits for on *every* Edit, Write and
|
|
63
|
+
Bash pay for the linter it will not run — measured at **84.5 ms and 25 modules**, against 50.1
|
|
64
|
+
and 7 once each import moved into the branch that uses it, and 44.6 and 5 once `Document` and
|
|
65
|
+
`LockBusy` followed (RK261). Interleaved, warm, minimum of nine rounds per tree: the first pass
|
|
66
|
+
at this reported 141 against 66 from one sample each, and single-shot import timings on this
|
|
67
|
+
machine drift far enough that a tree with *five* modules measured slower than one with seven.
|
|
68
|
+
The module count is the exact half of the claim and the milliseconds are one machine's.
|
|
69
|
+
|
|
70
|
+
This is the opposite trade from RK202,
|
|
71
|
+
and for the opposite reason: the MCP server is one process answering many messages, so a lookup
|
|
72
|
+
it repeats is worth hoisting, while the guard is a **fresh process per hook call**, so every
|
|
73
|
+
import it holds is paid again. RK176 bought the floor below this with
|
|
74
|
+
:mod:`roadkeep.screening`, which answers "there is certainly nothing here" out of the standard
|
|
75
|
+
library; this is the same argument for the payloads that get past it.
|
|
76
|
+
|
|
77
|
+
What is deliberately absent: any judgement about the *content* of the write. This module
|
|
78
|
+
never reads what the agent was about to insert, only where it was going. Deciding whether a
|
|
79
|
+
sentence fits is :meth:`Schema.validate`'s job, and it gets to make it when the author calls
|
|
80
|
+
`add` — which is the entire point of refusing here.
|
|
81
|
+
"""
|
|
82
|
+
|
|
83
|
+
from __future__ import annotations
|
|
84
|
+
|
|
85
|
+
import os
|
|
86
|
+
import tomllib
|
|
87
|
+
from collections.abc import Mapping
|
|
88
|
+
from dataclasses import dataclass, replace
|
|
89
|
+
from pathlib import Path
|
|
90
|
+
from typing import TYPE_CHECKING
|
|
91
|
+
|
|
92
|
+
from roadkeep.config import Config, ConfigError, find_config
|
|
93
|
+
from roadkeep.provenance import WIRED, invocation, served_by
|
|
94
|
+
from roadkeep.remedying import Door, alongside, offered
|
|
95
|
+
|
|
96
|
+
if TYPE_CHECKING: # annotations only, and already strings — see the docstring's sixth decision
|
|
97
|
+
from roadkeep.attesting import Unattested
|
|
98
|
+
from roadkeep.linting import Finding, Report
|
|
99
|
+
|
|
100
|
+
#: The tools that put bytes in a file. Listed by what reaches the disk and not by what the
|
|
101
|
+
#: harness happens to call it this month: a writing tool that is missing here is the hole
|
|
102
|
+
#: the whole hook exists to close, so the set is wider than the two RK22 names.
|
|
103
|
+
WRITE_TOOLS = ("Edit", "MultiEdit", "NotebookEdit", "Write")
|
|
104
|
+
|
|
105
|
+
#: The tools that put bytes in a file the payload does not name (RK128). One, and it is the
|
|
106
|
+
#: hole every other measure in this module was arranged around: a `command` is a string the
|
|
107
|
+
#: harness never resolves into a path, so the only thing knowable without parsing shell is
|
|
108
|
+
#: whether a governed path is *mentioned* — which is why these are asked about, not denied.
|
|
109
|
+
ASK_TOOLS = ("Bash",)
|
|
110
|
+
|
|
111
|
+
#: Both, in the order the plugin's `PreToolUse` matcher lists them. Kept as one name because
|
|
112
|
+
#: the matcher and this module have to agree or the hook never sees the payload it decides.
|
|
113
|
+
GUARDED_TOOLS = (*WRITE_TOOLS, *ASK_TOOLS)
|
|
114
|
+
|
|
115
|
+
#: The events that mean the turn is trying to end, and `lint` is the last thing to say.
|
|
116
|
+
STOP_EVENTS = ("Stop", "SubagentStop")
|
|
117
|
+
|
|
118
|
+
#: The event that arrives before the session's first tool call — the one moment an
|
|
119
|
+
#: announcement is cheaper than the mistake it prevents (RK82).
|
|
120
|
+
START_EVENTS = ("SessionStart",)
|
|
121
|
+
|
|
122
|
+
#: What the notice may cost, in characters. A budget and not a style rule: this is resident
|
|
123
|
+
#: for the whole session in every governed project, so the thing that keeps it one line is
|
|
124
|
+
#: a number a test holds, exactly as `[budgets]` holds `agents.md` (RK30). It prices the line
|
|
125
|
+
#: every session gets; the drift sentence (RK234) is over it deliberately and is not resident
|
|
126
|
+
#: — it appears only while a copy has drifted and goes away with one `install`.
|
|
127
|
+
#:
|
|
128
|
+
#: Raised from 260 by RK1242, which is the deliberate act a counted limit exists to make
|
|
129
|
+
#: visible. What it bought is the fallback clause on a project that declares the server: a
|
|
130
|
+
#: line naming an interface that never arrives sends a session to re-derive by hand
|
|
131
|
+
#: everything this line exists to stop it re-deriving, which is worth more than the sixty
|
|
132
|
+
#: characters. Sized for the longest invocation a wired project has — the committed launcher,
|
|
133
|
+
#: `python .roadkeep/scripts/roadkeep.py` — rather than for the console script.
|
|
134
|
+
#:
|
|
135
|
+
#: Counted in **UTF-16 code units** since RK1243, which is how every other length in this
|
|
136
|
+
#: package is counted (RK430) and how `cost --session` now reports this one: a read and a
|
|
137
|
+
#: gate that measured the same line two ways would disagree on exactly the line carrying a
|
|
138
|
+
#: character outside the BMP, which is the marker this tool writes.
|
|
139
|
+
_NOTICE_BUDGET = 320
|
|
140
|
+
|
|
141
|
+
#: Where a tool's input spells the file. Every key any writer uses, rather than the key
|
|
142
|
+
#: each one uses: reading all three costs three dict lookups and survives a renamed field.
|
|
143
|
+
_PATH_KEYS = ("file_path", "notebook_path", "path")
|
|
144
|
+
|
|
145
|
+
#: A `Stop` reason is context the next turn pays for, so the report is truncated — and the
|
|
146
|
+
#: truncation is *stated*, because a capped list that does not say so reads as a complete one.
|
|
147
|
+
_MOST_FINDINGS = 12
|
|
148
|
+
|
|
149
|
+
#: What to call instead, per role: the command, and what it is for. A denial is only as
|
|
150
|
+
#: useful as this table — the flags are the part that otherwise gets guessed (RK24), and
|
|
151
|
+
#: `<x>`/`<id>`/`…` are placeholders on purpose, since the tool never writes the prose (L4).
|
|
152
|
+
_INSTEAD: Mapping[str, tuple[tuple[str, str], ...]] = {
|
|
153
|
+
"roadmap": (
|
|
154
|
+
('add --block <x> --symptom "…" --why "…"', "a new task line, fields refused at input"),
|
|
155
|
+
# First, because it is the one the agent meets first (RK141): every write above
|
|
156
|
+
# refuses an undeclared block, and until this verb existed the only key to that
|
|
157
|
+
# door was the edit this refusal denies.
|
|
158
|
+
('block add <x> --title "…"', "declare a block, in every file organised by them"),
|
|
159
|
+
# And the inverse (RK144), because the key that only opens is the same asymmetry: a
|
|
160
|
+
# label typed wrongly was a heading in three files that only this denial's edit removed.
|
|
161
|
+
("block drop <x>", "withdraw a label: refused by name over any line under it"),
|
|
162
|
+
# And the words on it (RK1204): the drop above is refused the moment a line is filed
|
|
163
|
+
# under the label, so a heading's title was correctable only while nobody read it.
|
|
164
|
+
('block amend <x> --title "…"', "correct a heading's words; the label and work stay"),
|
|
165
|
+
("status <id> <marker>", "a marker, and only in this file"),
|
|
166
|
+
('amend <id> --why "…"', "correct the why, the deps or the pointer of a line"),
|
|
167
|
+
# The field that one excludes, which is the whole reason it is a second row (RK178): a
|
|
168
|
+
# denial naming only `amend` sends a reader to the verb that refuses this field.
|
|
169
|
+
('restate <id> --symptom "…"', "a symptom whose premise turned out to be false"),
|
|
170
|
+
("ship <id>", "shipped: ledger entry, line gone, section dropped"),
|
|
171
|
+
('retire <id> --reason "…"', "gone without shipping"),
|
|
172
|
+
# The one bullet in this file that is not a task line, and the reason the five above
|
|
173
|
+
# were not enough: a denial that named only them left `sed` as the route (RK70).
|
|
174
|
+
('non-goal add --lead "…" --why "…"', "a constraint on what may be proposed at all"),
|
|
175
|
+
("non-goal drop <lead>", "a constraint that is gone, or whose lead is being corrected"),
|
|
176
|
+
# The one read in a table of writes (RK69), and here rather than in the closing
|
|
177
|
+
# sentence because this is the file whose first bullet decides whether `add` may be
|
|
178
|
+
# called at all: a denial that teaches the write and not the check teaches half.
|
|
179
|
+
("non-goal list", "what may not be proposed at all — before `add`, not after"),
|
|
180
|
+
# The second read before a proposal (RK385), and beside the first for the same
|
|
181
|
+
# reason: a duplicate is not refusable, and the measurement that says so is the
|
|
182
|
+
# *score* and not the rank (RK441). BM25 over the 426 shipped symptoms this ledger
|
|
183
|
+
# held when it was taken ranks the true partner of all four `superseded by` pairs at
|
|
184
|
+
# #1 to #3 across the file — the ranking is fine. Two of those four score below the
|
|
185
|
+
# 13th percentile of the top-1 score a proposal with **no** duplicate produces, so a
|
|
186
|
+
# threshold catching all four flags 419 of the 426. Relative order inside one query
|
|
187
|
+
# carries signal and the absolute score carries none, which makes a gate impossible
|
|
188
|
+
# rather than merely unreliable — and it holds however good the ranking gets, where
|
|
189
|
+
# the rank this replaced argued the same right decision from a figure the ledger
|
|
190
|
+
# contradicts. Two people describing one problem use disjoint words. So the block
|
|
191
|
+
# states what it delivered and the author reads it, which costs one call against a
|
|
192
|
+
# claim and a retirement.
|
|
193
|
+
("delivered <x>", "what this block already shipped, as claims — also before `add`"),
|
|
194
|
+
# The other list this file holds that is not task lines (RK325), and the reason it
|
|
195
|
+
# arrived: the queue used to live in the config, which nothing governs — right for
|
|
196
|
+
# the prefix and the limits, wrong for a list whose every token names work that leaves.
|
|
197
|
+
("priority add <token>", "an id or 'Block X' jumps the id order; --first, --after"),
|
|
198
|
+
("priority drop <token>", "an entry that has shipped, or stopped being urgent"),
|
|
199
|
+
# The repair for damage smaller than a line (RK126). Listed on both line files,
|
|
200
|
+
# because a control character is the one defect no verb above reaches.
|
|
201
|
+
("lint --fix", "a derived field or a character that is not text, repaired"),
|
|
202
|
+
),
|
|
203
|
+
"changelog": (
|
|
204
|
+
("ship <id>", "the entry a planned task earns, in one transaction"),
|
|
205
|
+
('record add --block <x> --symptom "…" --why "…"', "work that was never planned"),
|
|
206
|
+
('block add <x> --title "…"', "declare a block: `ship` refuses one this file lacks"),
|
|
207
|
+
# Its inverse reaches this file too, but only for a label with nothing under it: an
|
|
208
|
+
# entry is history, and history keeps the heading it was filed under (RK144).
|
|
209
|
+
("block drop <x>", "withdraw a label opened by mistake; entries keep theirs"),
|
|
210
|
+
# Which is why the retitle reaches it at all (RK1204): a heading standing over history
|
|
211
|
+
# is one that can never be dropped, so its words were correctable by nothing.
|
|
212
|
+
('block amend <x> --title "…"', "correct a heading's words over entries it keeps"),
|
|
213
|
+
# The ledger's update (RK124), without which the honest answer to "a word is wrong
|
|
214
|
+
# here" was drop-and-re-add, which moves the entry to the end of its block.
|
|
215
|
+
('record amend <id> --why "…"', "correct an entry's sentence where it already is"),
|
|
216
|
+
# The field that update deliberately withheld (RK143): filing an entry elsewhere is a
|
|
217
|
+
# move, so it is a verb that says so rather than a flag inside a correction.
|
|
218
|
+
("record move <id> --to-block <x>", "an entry filed under the wrong block heading"),
|
|
219
|
+
("record drop <id>", "one of two entries for one id, when they say the same thing"),
|
|
220
|
+
# And when they do not (RK127): two deliveries under one id, which the drop above
|
|
221
|
+
# refuses rather than resolving by picking the entry that earned the id. Offered
|
|
222
|
+
# without its `--line`, because the refusal names the two real line numbers and a
|
|
223
|
+
# placeholder here would be the guess this whole table exists to remove.
|
|
224
|
+
("record renumber <id>", "two deliveries sharing an id; it names both, you pick --line"),
|
|
225
|
+
('retire <id> --reason "…"', "a line that left without shipping"),
|
|
226
|
+
("lint --fix", "a character that is not text, removed wherever it is"),
|
|
227
|
+
),
|
|
228
|
+
"improvements": (
|
|
229
|
+
('section add <id> --title "…"', "the prose on stdin, within the word budget"),
|
|
230
|
+
# The correction an open task's design needs (RK123): `drop` is refused while a live
|
|
231
|
+
# pointer names the anchor, so without this the table named nothing that applied.
|
|
232
|
+
("section amend <id> --body -", "correct a live section's prose, or its --title"),
|
|
233
|
+
("section drop <id>", "delete one section whole, subsections included"),
|
|
234
|
+
),
|
|
235
|
+
"strategy": (
|
|
236
|
+
('section add <id> --title "…" --role strategy', "the prose on stdin, filled"),
|
|
237
|
+
("section amend <id> --body - --role strategy", "correct a live section's prose"),
|
|
238
|
+
("section drop <id> --role strategy", "delete one section whole"),
|
|
239
|
+
),
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
def _doors(rows: tuple[tuple[str, str], ...]) -> tuple[Door, ...]:
|
|
243
|
+
"""One table's rows as doors, which is what a spelling is decided from (RK488).
|
|
244
|
+
|
|
245
|
+
The tables above stay strings — they are read by people as much as rendered — and the
|
|
246
|
+
split is `Door`'s own: an argv joined by single spaces renders back to the line it was
|
|
247
|
+
written as, which is the round-trip L3 asks of a task line, one file over.
|
|
248
|
+
|
|
249
|
+
This module composed both spellings itself until RK488, and `_tool_for` was the half that
|
|
250
|
+
made it look cheap: it matched the subcommand path and never asked whether the tool takes
|
|
251
|
+
the flags beside it, so `lint --fix` was offered as `mcp__roadkeep__lint` — RK16 keeps
|
|
252
|
+
`--fix` where a human is standing, so the row named a call the session cannot make. That
|
|
253
|
+
question is `serving.serves`' now, asked once for every surface.
|
|
254
|
+
"""
|
|
255
|
+
return tuple(Door(tuple(command.split()), purpose) for command, purpose in rows)
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
#: What a file that is governed but absent needs, which is not an edit.
|
|
259
|
+
_SCAFFOLD = (("init", "create the governed files and the config this project declares"),)
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
@dataclass(frozen=True, slots=True)
|
|
263
|
+
class Refusal:
|
|
264
|
+
"""One write denied, and the commands that do it properly."""
|
|
265
|
+
|
|
266
|
+
#: The tool the harness was about to run, named back so the reason reads as an answer.
|
|
267
|
+
tool: str
|
|
268
|
+
#: As the project spells it — a reason quoting an absolute path is a reason that is
|
|
269
|
+
#: about one machine.
|
|
270
|
+
path: str
|
|
271
|
+
role: str
|
|
272
|
+
#: On disk already. A governed file that is *not* there yet is `init`'s, not `add`'s.
|
|
273
|
+
exists: bool = True
|
|
274
|
+
#: The prefix this session's tools arrive under (RK333) — the bare `mcp__roadkeep__`
|
|
275
|
+
#: where a project declares the server, and `mcp__plugin_<plugin>_roadkeep__` where a
|
|
276
|
+
#: plugin provides it. A field and not a call, because it is a fact about the *project*
|
|
277
|
+
#: being refused and one hook process serves every repository the session touches.
|
|
278
|
+
#:
|
|
279
|
+
#: `""` is the third state and not a missing value (RK447): this session has no server
|
|
280
|
+
#: for them, so there is no tool table to print.
|
|
281
|
+
#:
|
|
282
|
+
#: And it is the **default** since RK1247, where it used to be the bare prefix on the
|
|
283
|
+
#: argument that this is what every wired project has. That argument is RK333's, from
|
|
284
|
+
#: when the choice was *between two prefixes*; RK447 ended it. A project that
|
|
285
|
+
#: pip-installed roadkeep and never ran `install` has neither scope and no tools at all,
|
|
286
|
+
#: and naming a route it cannot call spends a turn being told the tool does not exist
|
|
287
|
+
#: before it reaches the command that works — worse than naming none. Unreachable through
|
|
288
|
+
#: the hook, where both doors pass `served_by` and `tests/carrying.py` holds them to it;
|
|
289
|
+
#: what the default reaches is every caller building one without the field, and each of
|
|
290
|
+
#: those was getting the answer RK447 argued against. The four carriers now say one thing.
|
|
291
|
+
served: str = ""
|
|
292
|
+
|
|
293
|
+
@property
|
|
294
|
+
def decision(self) -> str:
|
|
295
|
+
"""What the harness is told: `deny`, or `ask` where the target was only mentioned.
|
|
296
|
+
|
|
297
|
+
Derived from the tool and not stated, so the two cannot disagree (RK128). A tool that
|
|
298
|
+
*names* the file it writes is certain, and the command table below is then the cheaper
|
|
299
|
+
path forward. A shell command only mentions the path — `sed -i` and `git log --` are
|
|
300
|
+
one payload shape — so the answer belongs to whoever owns the repository, which is the
|
|
301
|
+
one response that is neither a lie about the boundary nor a hole in it.
|
|
302
|
+
"""
|
|
303
|
+
return "ask" if self.tool in ASK_TOOLS else "deny"
|
|
304
|
+
|
|
305
|
+
@property
|
|
306
|
+
def commands(self) -> tuple[Door, ...]:
|
|
307
|
+
return _doors(_INSTEAD.get(self.role, ()) if self.exists else _SCAFFOLD)
|
|
308
|
+
|
|
309
|
+
@property
|
|
310
|
+
def tools(self) -> tuple[Door, ...]:
|
|
311
|
+
"""The commands above that the same plugin also serves as MCP tools (RK58).
|
|
312
|
+
|
|
313
|
+
Named first, because since RK57 the plugin installs with no `pip install` and no
|
|
314
|
+
PATH entry: on that machine the tool is the route that is certainly there and
|
|
315
|
+
`roadkeep add` is a `command not found` waiting to teach that the advice is wrong.
|
|
316
|
+
|
|
317
|
+
**Empty where this session has no server for them** (RK447), which is the same
|
|
318
|
+
argument read backwards. A project that pip-installed roadkeep and never ran
|
|
319
|
+
`install` has neither scope, and led with a prefix it cannot call the agent spends a
|
|
320
|
+
turn being told the tool does not exist before it reaches the command that works —
|
|
321
|
+
naming an edit that cannot be made, which is worse than naming none (RK16). The
|
|
322
|
+
`else` branch below is then the whole answer, and it was already there: this is a
|
|
323
|
+
denial, and the one thing it owes is the command that closes it. That `install`
|
|
324
|
+
would give this project the tools is true and is the notice's to say (RK444); a
|
|
325
|
+
refusal is a bad place to advertise.
|
|
326
|
+
"""
|
|
327
|
+
if not self.served:
|
|
328
|
+
return ()
|
|
329
|
+
# A door whose served spelling is its shell one is a command this session does not
|
|
330
|
+
# serve, which is the renderer's answer rather than a second lookup here (RK488).
|
|
331
|
+
return tuple(
|
|
332
|
+
door for door in self.commands if door.named(self.served) != door.command
|
|
333
|
+
)
|
|
334
|
+
|
|
335
|
+
@property
|
|
336
|
+
def _opening(self) -> str:
|
|
337
|
+
"""The one sentence the two decisions do not share (RK128).
|
|
338
|
+
|
|
339
|
+
Everything under it is the same text, because the value of a denial is the command
|
|
340
|
+
table and a project that printed two of those would have two that could drift. What
|
|
341
|
+
differs is only the claim being made: one states that the write was refused, the other
|
|
342
|
+
that this hook cannot tell a read from a write and is not going to pretend.
|
|
343
|
+
"""
|
|
344
|
+
if self.decision == "ask":
|
|
345
|
+
return (
|
|
346
|
+
f"{self.tool} names {self.path}, this project's {self.role}, and roadkeep "
|
|
347
|
+
f"owns its writes. A shell command is not read to see which it does, so the "
|
|
348
|
+
f"decision is yours: reading it is fine, and writing it wants a verb below."
|
|
349
|
+
)
|
|
350
|
+
return (
|
|
351
|
+
f"{self.tool} refused: {self.path} is this project's {self.role}, and "
|
|
352
|
+
f"roadkeep owns its writes."
|
|
353
|
+
)
|
|
354
|
+
|
|
355
|
+
@property
|
|
356
|
+
def _repairing(self) -> list[str]:
|
|
357
|
+
"""The shorter route, for the write that is a repair (RK424).
|
|
358
|
+
|
|
359
|
+
This table is keyed by **role**, deliberately: the hook never reads what the agent
|
|
360
|
+
was about to write — the module's last paragraph is about exactly that — so it
|
|
361
|
+
cannot narrow fourteen commands to one, and a table keyed by intent would be a table
|
|
362
|
+
keyed by a guess.
|
|
363
|
+
|
|
364
|
+
But since RK420 the guard is no longer the only thing that speaks. A finding carries
|
|
365
|
+
the command that closes it, so an agent repairing a *reported* line has a route that
|
|
366
|
+
is one call rather than a read of this list — and this refusal is the one place it
|
|
367
|
+
will certainly look, because it is what stopped the `Edit`. So the route is named
|
|
368
|
+
first and the fourteen stay beneath it, for the write that is not a repair.
|
|
369
|
+
|
|
370
|
+
What this deliberately does **not** do is run `lint` here. `PreToolUse` is a fresh
|
|
371
|
+
process the harness waits on before every `Edit`, `Write` and `Bash`, held at 44.6 ms
|
|
372
|
+
and five modules by RK261, and loading the linter would spend that budget on every
|
|
373
|
+
write in the repository to answer a question about a few of them. Naming the command
|
|
374
|
+
costs three lines of a string already being composed, and the caller who needs the
|
|
375
|
+
answer is one call away from it.
|
|
376
|
+
"""
|
|
377
|
+
# RK448: this paragraph is read *first* — RK424 put it above the tool table — and it
|
|
378
|
+
# spelled all three with the invocation whatever the session had. So on a wired
|
|
379
|
+
# project the line an agent acts on recommended the shell for exactly the verbs the
|
|
380
|
+
# table under it would have served, which is RK58's own argument arriving one
|
|
381
|
+
# paragraph too late. Where the tools are here, this is where they are named.
|
|
382
|
+
#
|
|
383
|
+
# A flag is not a word over that transport: `repair --dry-run` is the `repair` tool
|
|
384
|
+
# carrying `dry_run`. Which spelling, and where a dropped flag is named, is
|
|
385
|
+
# `remedying.offered`'s since RK488 — this states the three doors and nothing else.
|
|
386
|
+
doors = (
|
|
387
|
+
Door(("repair",), "every finding whose remedy is one command, applied in one call"),
|
|
388
|
+
Door(("repair", "--dry-run"), "the same list, printed and not run"),
|
|
389
|
+
Door(("explain", "<code>"), "what one code means, and which doors close it"),
|
|
390
|
+
)
|
|
391
|
+
return [
|
|
392
|
+
"If this edit was repairing something `lint` reported, it already named the "
|
|
393
|
+
"command that closes each finding — so none of them has to be inferred:",
|
|
394
|
+
*offered(doors, self.served),
|
|
395
|
+
"",
|
|
396
|
+
]
|
|
397
|
+
|
|
398
|
+
def __str__(self) -> str:
|
|
399
|
+
"""The reason, as the agent reads it: what was refused, why, and what to run."""
|
|
400
|
+
lines = [
|
|
401
|
+
self._opening,
|
|
402
|
+
"",
|
|
403
|
+
"The id, the pointer and every (deps: …) annotation are derived on render, "
|
|
404
|
+
"so a hand-edit is the one path that can leave a line the format rejects — "
|
|
405
|
+
"and a limit discovered after the sentence exists is a limit that costs a "
|
|
406
|
+
"deletion instead of a refusal.",
|
|
407
|
+
"",
|
|
408
|
+
]
|
|
409
|
+
lines += self._repairing
|
|
410
|
+
if self.tools:
|
|
411
|
+
lines.append("Call instead — this session's tools, where the fields are a schema:")
|
|
412
|
+
lines += offered(self.tools, self.served)
|
|
413
|
+
lines += ["", "Or the same engine in a shell, from the project root:"]
|
|
414
|
+
else:
|
|
415
|
+
lines.append("Call instead, from the project root:")
|
|
416
|
+
# The shell table, rendered by the same function and therefore with the invocation
|
|
417
|
+
# this machine actually has (RK254): since RK57 the plugin installs with no `pip
|
|
418
|
+
# install` and no PATH entry, so `roadkeep add` was advice that answers `command not
|
|
419
|
+
# found` on the machine most likely to read it. `--help` closes the table rather than
|
|
420
|
+
# sitting in it — it is not a role's command, it is what makes the rest readable.
|
|
421
|
+
helped = Door(("<command>", "--help"), "every flag, so none is guessed")
|
|
422
|
+
lines += offered((*self.commands, helped))
|
|
423
|
+
lines += ["", self._reading]
|
|
424
|
+
return "\n".join(lines)
|
|
425
|
+
|
|
426
|
+
@property
|
|
427
|
+
def _reading(self) -> str:
|
|
428
|
+
"""The three reads, in the spelling the session that will make them has (RK477).
|
|
429
|
+
|
|
430
|
+
RK254 gave this sentence `invocation()` for the console script RK57 removed, which is
|
|
431
|
+
right for a shell and was all it got: RK24 split the *writes* into a tools table and a
|
|
432
|
+
shell table, and the closing line stayed below both, composed once. So the message
|
|
433
|
+
offered fifteen writes as tools and then said reading is never refused in a shell the
|
|
434
|
+
reader may not have — measured on a scaffolded project as 15 rendered twice, 3 once.
|
|
435
|
+
|
|
436
|
+
Per table, like `_repairing` above it, and a sentence rather than a fourth table: what
|
|
437
|
+
makes these three read as *not* the refused act is that they are not in one. And the
|
|
438
|
+
served form names fields, because `<id>` is an argv and a caller here passes arguments.
|
|
439
|
+
|
|
440
|
+
The **spelling** is `remedying.alongside`'s since RK488, and the two sentences stay:
|
|
441
|
+
a served name drops the arguments a shell line shows, so what each verb takes has to
|
|
442
|
+
be said in words there and is already visible here. That difference is prose, which
|
|
443
|
+
is the one thing a renderer may not decide.
|
|
444
|
+
"""
|
|
445
|
+
brief, show, listing = alongside(
|
|
446
|
+
(
|
|
447
|
+
Door(("brief", "<id>"), ""),
|
|
448
|
+
Door(("show", "<id>"), ""),
|
|
449
|
+
Door(("list", "--block", "<x>"), ""),
|
|
450
|
+
),
|
|
451
|
+
self.served,
|
|
452
|
+
)
|
|
453
|
+
if self.served:
|
|
454
|
+
return (
|
|
455
|
+
f"Reading is never refused: `{brief}` starts a task in one call and "
|
|
456
|
+
f"`{show}` joins the line to its rationale, both taking the id; "
|
|
457
|
+
f"`{listing}` prints them verbatim, and takes a block."
|
|
458
|
+
)
|
|
459
|
+
return (
|
|
460
|
+
f"Reading is never refused: `{brief}` starts a task in one call, "
|
|
461
|
+
f"`{show}` joins the line to its rationale, `{listing}` prints them "
|
|
462
|
+
f"verbatim."
|
|
463
|
+
)
|
|
464
|
+
|
|
465
|
+
|
|
466
|
+
@dataclass(frozen=True, slots=True)
|
|
467
|
+
class Review:
|
|
468
|
+
"""What `lint` found when the turn tried to end (RK14 as the backstop for RK22).
|
|
469
|
+
|
|
470
|
+
Only the failing tier: a :class:`~roadkeep.linting.Note` is something the gate says at
|
|
471
|
+
exit 0, and a turn is not worth blocking over a sentence.
|
|
472
|
+
"""
|
|
473
|
+
|
|
474
|
+
report: Report
|
|
475
|
+
#: The prefix this session's tools arrive under, or `""` where it has none (RK448). The
|
|
476
|
+
#: same field :class:`Refusal` carries and for the same reason: this message is what an
|
|
477
|
+
#: agent acts on to unblock itself, and it named the shell on projects whose `lint` is
|
|
478
|
+
#: pre-approved. A field rather than a call, because one hook process serves every
|
|
479
|
+
#: repository the session touches and the answer is a fact about this one.
|
|
480
|
+
served: str = ""
|
|
481
|
+
#: This project, for the doors below (RK478). Optional because `Review` is constructed
|
|
482
|
+
#: in tests from a report alone, and a rule the table does not vary by needs none — but
|
|
483
|
+
#: `remedy` reads `ref_scheme`, `role` and the queue for the five that do, so the gate
|
|
484
|
+
#: gets it wherever a caller has one.
|
|
485
|
+
config: Config | None = None
|
|
486
|
+
|
|
487
|
+
def __str__(self) -> str:
|
|
488
|
+
findings = self.report.findings
|
|
489
|
+
# Both spellings from one renderer (RK488). The engine is the one this machine has,
|
|
490
|
+
# for `Denial`'s reason (RK254) — a gate naming a repair the reader cannot run blocks
|
|
491
|
+
# the turn and withholds the way out of it — and where the session has the tool, that
|
|
492
|
+
# is the route (RK448). `lint --fix` answers the shell on every project without being
|
|
493
|
+
# asked to: `--fix` writes, RK16 keeps it where a human is standing, so the served
|
|
494
|
+
# `lint` does not expose it and `Door.named` declines the prefix by derivation.
|
|
495
|
+
lint_ = Door(("lint",), "").named(self.served)
|
|
496
|
+
fixing = Door(("lint", "--fix"), "").named(self.served)
|
|
497
|
+
lines = [
|
|
498
|
+
f"{lint_} refuses {len(findings)} line(s) this turn changed in "
|
|
499
|
+
f"{', '.join(self.report.checked)}: a governed file was changed by something "
|
|
500
|
+
f"other than roadkeep, and the format is what the next reader trusts.",
|
|
501
|
+
"",
|
|
502
|
+
]
|
|
503
|
+
lines += self._findings(findings, lint_)
|
|
504
|
+
lines += [
|
|
505
|
+
"",
|
|
506
|
+
# Six repairs, held against `fixing.REPAIRS` by a test and not imported (RK355):
|
|
507
|
+
# this module stays out of that import path, which is what RK260 bought.
|
|
508
|
+
#
|
|
509
|
+
# The one route here that keeps the invocation on every project (RK448), and it
|
|
510
|
+
# says so: `--fix` writes, and RK16 puts it where a human is standing — so the
|
|
511
|
+
# served surface withholds it deliberately (`lint` is exposed there without it),
|
|
512
|
+
# and a prefix glued to this line would name a tool that does not exist.
|
|
513
|
+
f"`{fixing}` repairs what is derived (annotation, pointer, dep "
|
|
514
|
+
f"order, marker codepoint, whitespace, dead queue entry, orphaned criteria "
|
|
515
|
+
f"heading); everything left is "
|
|
516
|
+
f"editorial and wants a command, not an edit."
|
|
517
|
+
+ (
|
|
518
|
+
" That one is the shell whatever this session serves: `--fix` writes, so "
|
|
519
|
+
"the tool surface withholds it."
|
|
520
|
+
if self.served
|
|
521
|
+
else ""
|
|
522
|
+
),
|
|
523
|
+
]
|
|
524
|
+
return "\n".join(lines)
|
|
525
|
+
|
|
526
|
+
def _findings(self, findings: tuple[Finding, ...], lint_: str) -> list[str]:
|
|
527
|
+
"""Each finding, and under it the door RK420 gave it (RK478).
|
|
528
|
+
|
|
529
|
+
The gate was the one surface that withheld it: it printed the address and the
|
|
530
|
+
sentence and closed on *everything left is editorial and wants a command*, which
|
|
531
|
+
says one exists and not which — so a turn stopped here called `lint` again to read a
|
|
532
|
+
report already composed. Measured on a copy of Shio, three `path.missing` with three
|
|
533
|
+
doors and none of them shown.
|
|
534
|
+
|
|
535
|
+
Grouped exactly as `cli._print_findings` groups (RK469), by `(code, file, shared)`
|
|
536
|
+
and printed at the first member, and the **cap counts groups** — it exists for
|
|
537
|
+
length, and a group is what costs lines. That is what makes the doors affordable:
|
|
538
|
+
on Turing, 35 findings reach 11 groups and all of them are shown, where the same cap
|
|
539
|
+
ungrouped prints 12 and hides 23. Shio's three fold to nothing because they declare
|
|
540
|
+
no shared fact, which is the emitter's answer and the right one.
|
|
541
|
+
|
|
542
|
+
The mechanical class stays counted and not printed: the `lint --fix` sentence below
|
|
543
|
+
is already that remedy, said once for all of them, which is RK420's own rule.
|
|
544
|
+
"""
|
|
545
|
+
# RK260: this module's imports are per event, and a door is only ever printed here.
|
|
546
|
+
from roadkeep.remedying import remedy # noqa: PLC0415
|
|
547
|
+
|
|
548
|
+
runs: dict[tuple[str, str, str], list[Finding]] = {}
|
|
549
|
+
for finding in findings:
|
|
550
|
+
if finding.shared:
|
|
551
|
+
runs.setdefault((finding.code, finding.file, finding.shared), []).append(finding)
|
|
552
|
+
lines: list[str] = []
|
|
553
|
+
seen: set[tuple[str, str, str]] = set()
|
|
554
|
+
shown = covered = 0
|
|
555
|
+
for finding in findings:
|
|
556
|
+
key = (finding.code, finding.file, finding.shared)
|
|
557
|
+
run = runs.get(key, []) if finding.shared else []
|
|
558
|
+
if len(run) > 1 and key in seen:
|
|
559
|
+
continue
|
|
560
|
+
if shown == _MOST_FINDINGS:
|
|
561
|
+
break
|
|
562
|
+
seen.add(key)
|
|
563
|
+
shown += 1
|
|
564
|
+
covered += max(len(run), 1)
|
|
565
|
+
lines += self._group(finding, run)
|
|
566
|
+
found = remedy(finding, self.config)
|
|
567
|
+
if found is not None and found.kind != "fix":
|
|
568
|
+
lines += [f" {one.lstrip()}" for one in found.spoken(self.served).splitlines()]
|
|
569
|
+
if covered < len(findings):
|
|
570
|
+
left = len(findings) - covered
|
|
571
|
+
lines.append(f" … and {left} more — `{lint_}` prints all of them")
|
|
572
|
+
return lines
|
|
573
|
+
|
|
574
|
+
@staticmethod
|
|
575
|
+
def _group(finding: Finding, run: list[Finding]) -> list[str]:
|
|
576
|
+
"""One row, or the pair a run of two or more folds to — `cli._print_findings`' shape."""
|
|
577
|
+
if len(run) < 2:
|
|
578
|
+
return [f" {finding}"]
|
|
579
|
+
return [
|
|
580
|
+
f" {finding.file} {finding.code} {len(run)} addresses {finding.shared}",
|
|
581
|
+
f" {' '.join(f'{one.token}:{one.lineno}' for one in run)}",
|
|
582
|
+
]
|
|
583
|
+
|
|
584
|
+
|
|
585
|
+
@dataclass(frozen=True, slots=True)
|
|
586
|
+
class Notice:
|
|
587
|
+
"""The one line a session is given before it reads anything (RK82).
|
|
588
|
+
|
|
589
|
+
The write side had an instrument and the read side had prose: a hook refuses a
|
|
590
|
+
hand-edit, and the rule that these files are *queried* rather than read lives in a
|
|
591
|
+
skill that loads once a governed file is already in play. Measured, that is too late —
|
|
592
|
+
a session opened with a `grep` of the roadmap and the skill in the same batch, so the
|
|
593
|
+
instruction not to read the file arrived with the file's contents.
|
|
594
|
+
|
|
595
|
+
So this states the two facts nothing resident carried: **which** files are governed
|
|
596
|
+
here, and that reading them is a command too. It never repeats the write path — that
|
|
597
|
+
is the skill's, and a rule in two places is two places that can disagree.
|
|
598
|
+
"""
|
|
599
|
+
|
|
600
|
+
#: As this project spells them, in the order `[files]` declares: the whole point is
|
|
601
|
+
#: that a session learns these paths before it greps for one (L6).
|
|
602
|
+
files: tuple[str, ...]
|
|
603
|
+
#: The vendored surfaces that have drifted from the checkout answering (RK234). Said in
|
|
604
|
+
#: this line and nowhere else because this is the one moment it is both cheap to ask and
|
|
605
|
+
#: early enough to act on — the copy the session is about to trust is the skill.
|
|
606
|
+
stale: tuple[str, ...] = ()
|
|
607
|
+
#: The prefix this session's roadkeep tools arrive under, or `""` where there are none
|
|
608
|
+
#: (RK444). The route this line names, and the reason it is a field rather than a call
|
|
609
|
+
#: inside `__str__`: which engine answers is a fact about the project, decided where the
|
|
610
|
+
#: project is read, and a `Notice` built by a test says which case it is testing.
|
|
611
|
+
served: str = ""
|
|
612
|
+
|
|
613
|
+
def __str__(self) -> str:
|
|
614
|
+
# And the first message of the session is the first place the invocation has to be one
|
|
615
|
+
# this machine has (RK254) — it is the line teaching that reading is a command.
|
|
616
|
+
#
|
|
617
|
+
# Where the tools are served, that is the route (RK444). This is the only message
|
|
618
|
+
# every adopting session gets, and it named the shell on exactly the projects whose
|
|
619
|
+
# tools are pre-approved: the deny lists them correctly and fires only on a hand-edit,
|
|
620
|
+
# which the agent that behaves never makes, and the skill's copy waits on a trigger,
|
|
621
|
+
# one sentence among two hundred and fifty. What is stated is which engine answers —
|
|
622
|
+
# the same kind of fact as which files are governed — and never the write path, which
|
|
623
|
+
# stays the skill's, a rule in two places being two places that can disagree.
|
|
624
|
+
#
|
|
625
|
+
# One renderer for the three spellings since RK488, and `alongside` is the half this
|
|
626
|
+
# line paid for: a served name is self-contained, and three shell lines each carrying
|
|
627
|
+
# the invocation is 46 characters of repetition inside a 260-character budget.
|
|
628
|
+
brief, show, listing = alongside(
|
|
629
|
+
(
|
|
630
|
+
Door(("brief",), ""),
|
|
631
|
+
Door(("show", "<id>"), ""),
|
|
632
|
+
Door(("list", "--block", "<x>"), ""),
|
|
633
|
+
),
|
|
634
|
+
self.served,
|
|
635
|
+
)
|
|
636
|
+
asks = f"`{brief}` starts a task, `{show}` and `{listing}` answer the rest"
|
|
637
|
+
said = (
|
|
638
|
+
f"roadkeep governs {', '.join(self.files)} — ask, never read them whole: "
|
|
639
|
+
f"{asks}, and a hand-edit is refused."
|
|
640
|
+
)
|
|
641
|
+
# And what to do when they do not arrive (RK1242). Measured over one long session on a
|
|
642
|
+
# project that vendors roadkeep: this line named the tools, the harness reported the
|
|
643
|
+
# server as still connecting, and they never appeared — two searches minutes apart
|
|
644
|
+
# found none, and every call for the rest of the session went through the launcher.
|
|
645
|
+
# Nothing was lost, which is why it is worth saying: the CLI answered everything, so
|
|
646
|
+
# the only cost was a paragraph about an interface that was not there, and an agent
|
|
647
|
+
# that trusted it would have waited or reported the capability as unavailable.
|
|
648
|
+
#
|
|
649
|
+
# Where the project **declares** the server and not where a plugin provides it: the
|
|
650
|
+
# connection that can fail this way is the launcher this repository wrote, spawned by
|
|
651
|
+
# the harness, and a plugin's server is the harness's own machinery. So this appears on
|
|
652
|
+
# the projects the failure was measured on and stays off the rest.
|
|
653
|
+
#
|
|
654
|
+
# Read off `served` and never carried beside it (RK1244). RK1242 added a second field
|
|
655
|
+
# for this, which was a three-way answer stored as two — and the pair `mcp__plugin_…`
|
|
656
|
+
# with `declared = True` is a project whose server is both, which `serving` cannot
|
|
657
|
+
# produce and a caller could construct without noticing. `WIRED` **is** the declared
|
|
658
|
+
# case, by that function's own first branch, so there was never a second fact to hold.
|
|
659
|
+
if self.served == WIRED:
|
|
660
|
+
said += f" `{invocation()}` is the same engine if they never arrive."
|
|
661
|
+
# The invocation stays here whatever the clause above chose (RK444): `install` runs
|
|
662
|
+
# once per project and is deliberately not on the served surface — so it is one more
|
|
663
|
+
# door through the same renderer, and the shell form is what comes back because
|
|
664
|
+
# nothing serves the verb, rather than because this line remembered not to ask.
|
|
665
|
+
if self.stale:
|
|
666
|
+
installing = Door(("install",), "").named(self.served)
|
|
667
|
+
said += (
|
|
668
|
+
f" This project's copy of {', '.join(self.stale)} has drifted from the "
|
|
669
|
+
f"checkout answering here: `{installing}` refreshes it, and until then "
|
|
670
|
+
f"the copy is not what this session is running."
|
|
671
|
+
)
|
|
672
|
+
return said
|
|
673
|
+
|
|
674
|
+
|
|
675
|
+
def announce(payload: Mapping[str, object], root: str | Path = ".") -> Notice | None:
|
|
676
|
+
"""Compose what a starting session is told, or ``None`` where there is nothing to say.
|
|
677
|
+
|
|
678
|
+
Silence outside a roadkeep project, on the same argument the barrier makes about
|
|
679
|
+
`allow`: a hook that speaks in every repository is a hook every repository pays for.
|
|
680
|
+
Failure is silence too — a session that cannot start because a `roadkeep.toml` has a
|
|
681
|
+
typo in it is a worse outcome than one told nothing, and `lint` still refuses the file.
|
|
682
|
+
"""
|
|
683
|
+
try:
|
|
684
|
+
config = Config.discover(_cwd(payload, root))
|
|
685
|
+
except (ConfigError, OSError, tomllib.TOMLDecodeError):
|
|
686
|
+
return None
|
|
687
|
+
if config.source is None:
|
|
688
|
+
return None
|
|
689
|
+
files = tuple(config.relative(path) for path in config.paths.values())
|
|
690
|
+
if not files:
|
|
691
|
+
return None
|
|
692
|
+
# Asked here and not on a `PreToolUse`, for the reason the notice itself is: the copy a
|
|
693
|
+
# session trusts is the skill it loads, and by the first write it has been read (RK234).
|
|
694
|
+
from roadkeep.installing import stale # noqa: PLC0415 - RK260 the SessionStart path only
|
|
695
|
+
|
|
696
|
+
# `serving` and not `served_as` (RK444): a refusal has to recommend something and the
|
|
697
|
+
# bare prefix is the right guess wherever nothing says otherwise, but this line is read
|
|
698
|
+
# by every adopting session including the ones with no tools at all, and there naming a
|
|
699
|
+
# prefix nobody can call is worse than naming the shell.
|
|
700
|
+
return Notice(files=files, stale=stale(config.root), served=served_by(config.root))
|
|
701
|
+
|
|
702
|
+
|
|
703
|
+
@dataclass(frozen=True, slots=True)
|
|
704
|
+
class Advice:
|
|
705
|
+
"""A hand edit that is allowed, and the door four of its tables now have (RK1280).
|
|
706
|
+
|
|
707
|
+
The guard does not govern `roadkeep.toml` — "which a human edits by hand on purpose" —
|
|
708
|
+
and half of that stopped being true: `[limits]`, `[budgets]`, `[tools]` and `[claims]`
|
|
709
|
+
have a verb that takes the reading first and refuses a number this corpus already breaks.
|
|
710
|
+
So the two writers disagree about what is checkable, and the unchecked one is the default.
|
|
711
|
+
|
|
712
|
+
**Denying it is the wrong answer**, and the reason is the shape of the file: a hook sees a
|
|
713
|
+
path and not a table. `[files]`, `[markers]`, `[refs]` and `[grammar]` have no verb and
|
|
714
|
+
are not going to get one, so a denial would make the config unwritable in the sessions
|
|
715
|
+
that need it most — including the one where `install` has not run yet.
|
|
716
|
+
|
|
717
|
+
What this is instead is the register the barrier deliberately has no other use for: it
|
|
718
|
+
**decides nothing**. `permissionDecision: "allow"` would grant the write and wave through
|
|
719
|
+
the permission rules the user set for every other file (RK1202), so this carries no
|
|
720
|
+
decision at all — only the sentence, on the one path a session touches twice a year.
|
|
721
|
+
"""
|
|
722
|
+
|
|
723
|
+
#: As the project spells it, for :class:`Refusal`'s reason: a message quoting an absolute
|
|
724
|
+
#: path is a message about one machine.
|
|
725
|
+
path: str
|
|
726
|
+
#: The prefix this session's tools arrive under, or `""` — :class:`Refusal`'s field and
|
|
727
|
+
#: its argument exactly, so the door named is one this session can actually call.
|
|
728
|
+
served: str = ""
|
|
729
|
+
|
|
730
|
+
def __str__(self) -> str:
|
|
731
|
+
from roadkeep.governing import GOVERNED # noqa: PLC0415 - RK260
|
|
732
|
+
|
|
733
|
+
tables = ", ".join(f"[{one.split('.')[0]}]" for one in GOVERNED)
|
|
734
|
+
governing = Door(("govern", "<key>", "<n>"), "").named(self.served)
|
|
735
|
+
listing = Door(("config",), "").named(self.served)
|
|
736
|
+
return (
|
|
737
|
+
f"{self.path} is yours to edit and this is not a refusal — but {tables} are "
|
|
738
|
+
f"numbers a reading decides, and `{governing}` takes that reading and refuses "
|
|
739
|
+
f"one this project already breaks, where a hand edit lands it and the gate "
|
|
740
|
+
f"reports it on the next run. `{listing}` says what may be declared here."
|
|
741
|
+
)
|
|
742
|
+
|
|
743
|
+
|
|
744
|
+
@dataclass(frozen=True, slots=True)
|
|
745
|
+
class Barrier:
|
|
746
|
+
"""What one `PreToolUse` call answers: a refusal, a sentence, or neither (RK1283).
|
|
747
|
+
|
|
748
|
+
One record because it is **one walk**. `guard` resolved the config per target and threw it
|
|
749
|
+
away on the way to `None`, and `advise` then discovered the same file again — one
|
|
750
|
+
`find_config` walk and one `tomllib` parse per *allowed* write, on the path every `Edit` a
|
|
751
|
+
session makes goes down. What the barrier has always been careful about is what an allowed
|
|
752
|
+
call costs; this is that care, kept while the sentence was added.
|
|
753
|
+
|
|
754
|
+
The order is a rule and not an ordering (RK1280): the advice is held rather than returned
|
|
755
|
+
while any target may still be governed, because a call producing both would be two
|
|
756
|
+
messages about one write.
|
|
757
|
+
"""
|
|
758
|
+
|
|
759
|
+
refusal: Refusal | None = None
|
|
760
|
+
advice: Advice | None = None
|
|
761
|
+
|
|
762
|
+
|
|
763
|
+
def decide(payload: Mapping[str, object], root: str | Path = ".") -> Barrier:
|
|
764
|
+
"""Both answers, from one reading of the project (RK22, RK1280, RK1283).
|
|
765
|
+
|
|
766
|
+
``root`` is only the fallback for a payload with no ``cwd`` — the paths in the tool input
|
|
767
|
+
decide which project's configuration applies, because one hook process serves every
|
|
768
|
+
repository the session touches.
|
|
769
|
+
"""
|
|
770
|
+
tool = payload.get("tool_name")
|
|
771
|
+
if not isinstance(tool, str) or tool not in GUARDED_TOOLS:
|
|
772
|
+
return Barrier()
|
|
773
|
+
base = _cwd(payload, root)
|
|
774
|
+
if tool in ASK_TOOLS:
|
|
775
|
+
# A command only *mentions* a path, so there is nothing here to advise about either:
|
|
776
|
+
# a sentence about four tables attached to a call that may be reading the file is
|
|
777
|
+
# prose about a write nobody made.
|
|
778
|
+
return Barrier(refusal=_mentioned(payload.get("tool_input"), base, tool))
|
|
779
|
+
advice: Advice | None = None
|
|
780
|
+
for path in _targets(payload.get("tool_input"), base):
|
|
781
|
+
config = owning(path)
|
|
782
|
+
if config is None:
|
|
783
|
+
continue
|
|
784
|
+
role = role_at(config, path)
|
|
785
|
+
if role is not None:
|
|
786
|
+
return Barrier(
|
|
787
|
+
refusal=Refusal(
|
|
788
|
+
tool=tool,
|
|
789
|
+
path=config.relative(path),
|
|
790
|
+
role=role,
|
|
791
|
+
exists=path.is_file(),
|
|
792
|
+
served=served_by(config.root),
|
|
793
|
+
)
|
|
794
|
+
)
|
|
795
|
+
if config.source is not None and _comparable(path) == _comparable(config.source):
|
|
796
|
+
advice = Advice(
|
|
797
|
+
path=config.relative(config.source), served=served_by(config.root)
|
|
798
|
+
)
|
|
799
|
+
return Barrier(advice=advice)
|
|
800
|
+
|
|
801
|
+
|
|
802
|
+
def advise(payload: Mapping[str, object], root: str | Path = ".") -> Advice | None:
|
|
803
|
+
"""The one thing to say about a write this gate allows, or ``None`` (RK1280).
|
|
804
|
+
|
|
805
|
+
Narrow twice over. Only the project's **own declaration** — the config this path resolves
|
|
806
|
+
to, so a `pyproject.toml` that configures nothing here says nothing — and only where
|
|
807
|
+
nothing was refused, which :func:`decide` establishes in one pass.
|
|
808
|
+
|
|
809
|
+
Kept as its own name for :func:`guard`'s reason: it is the question a reader outside this
|
|
810
|
+
module asks, and the tests that hold this boundary are written against it.
|
|
811
|
+
"""
|
|
812
|
+
return decide(payload, root).advice
|
|
813
|
+
|
|
814
|
+
|
|
815
|
+
def guard(payload: Mapping[str, object], root: str | Path = ".") -> Refusal | None:
|
|
816
|
+
"""Decide one `PreToolUse` call: ``None`` allows, a :class:`Refusal` denies.
|
|
817
|
+
|
|
818
|
+
:func:`decide`'s refusal half, kept as its own name because that is the question every
|
|
819
|
+
caller outside this module asks and the one the tests are written against.
|
|
820
|
+
"""
|
|
821
|
+
return decide(payload, root).refusal
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
def _mentioned(raw: object, base: Path, tool: str) -> Refusal | None:
|
|
825
|
+
"""The governed path a shell command spells, or ``None`` (RK128).
|
|
826
|
+
|
|
827
|
+
Not a parse and not a heuristic about what the command *is*: the question is only whether
|
|
828
|
+
one of the handful of paths this project declares occurs in the string at all, which is the
|
|
829
|
+
single thing decidable without knowing what `sed`, a heredoc or a `python -c` would do with
|
|
830
|
+
it. A command naming none of them is the overwhelming majority and costs one config read.
|
|
831
|
+
|
|
832
|
+
Nothing is allowlisted, because nothing needs to be: roadkeep's own commands address a
|
|
833
|
+
task by **id and role**, never by path, so the verbs this refusal recommends do not
|
|
834
|
+
trip it — which is a fact `tests/test_guarding.py` holds rather than a hope.
|
|
835
|
+
"""
|
|
836
|
+
if not isinstance(raw, Mapping):
|
|
837
|
+
return None
|
|
838
|
+
command = raw.get("command")
|
|
839
|
+
if not isinstance(command, str) or not command:
|
|
840
|
+
return None
|
|
841
|
+
try:
|
|
842
|
+
config = Config.discover(base)
|
|
843
|
+
except (ConfigError, OSError, tomllib.TOMLDecodeError):
|
|
844
|
+
return None
|
|
845
|
+
if config.source is None:
|
|
846
|
+
return None
|
|
847
|
+
spelled = _comparable_text(command)
|
|
848
|
+
for role, declared in config.paths.items():
|
|
849
|
+
relative = config.relative(declared)
|
|
850
|
+
# Both spellings, because a command may name the file either way and the substring is
|
|
851
|
+
# the whole test: `./docs/ROADMAP.md` and a quoted absolute path both contain one.
|
|
852
|
+
if any(_comparable_text(form) in spelled for form in (relative, str(declared))):
|
|
853
|
+
return Refusal(
|
|
854
|
+
tool=tool,
|
|
855
|
+
path=relative,
|
|
856
|
+
role=role,
|
|
857
|
+
exists=declared.is_file(),
|
|
858
|
+
served=served_by(config.root),
|
|
859
|
+
)
|
|
860
|
+
return None
|
|
861
|
+
|
|
862
|
+
|
|
863
|
+
def review(payload: Mapping[str, object], root: str | Path = ".") -> Review | None:
|
|
864
|
+
"""Judge the files as the turn ends: ``None`` lets it end, a :class:`Review` blocks.
|
|
865
|
+
|
|
866
|
+
The one check `Bash` cannot dodge, and the reason `PreToolUse` does not need to match
|
|
867
|
+
every shell command. ``stop_hook_active`` is honoured before anything is read: blocking
|
|
868
|
+
a second time on a file the agent has already failed to repair is a loop, and a loop
|
|
869
|
+
costs more than the drift it was trying to stop.
|
|
870
|
+
"""
|
|
871
|
+
if payload.get("stop_hook_active") is True:
|
|
872
|
+
return None
|
|
873
|
+
if not isinstance(payload.get("hook_event_name", "Stop"), str):
|
|
874
|
+
return None
|
|
875
|
+
try:
|
|
876
|
+
config = Config.discover(_cwd(payload, root))
|
|
877
|
+
except ConfigError:
|
|
878
|
+
# The same failure rule as the barrier: a broken config must not pin a session
|
|
879
|
+
# open. `lint` refuses to run and says why, where somebody can act on it.
|
|
880
|
+
return None
|
|
881
|
+
if config.source is None:
|
|
882
|
+
return None # not a roadkeep project: there is nothing here this may judge
|
|
883
|
+
try:
|
|
884
|
+
from roadkeep.linting import lint # noqa: PLC0415 - RK260 the Stop path only
|
|
885
|
+
|
|
886
|
+
report = lint(config)
|
|
887
|
+
except (KeyError, OSError):
|
|
888
|
+
return None
|
|
889
|
+
if report.clean:
|
|
890
|
+
return None
|
|
891
|
+
narrowed = _this_turn(config, report)
|
|
892
|
+
if not narrowed.findings:
|
|
893
|
+
return None
|
|
894
|
+
return Review(report=narrowed, served=served_by(config.root), config=config)
|
|
895
|
+
|
|
896
|
+
|
|
897
|
+
def attested(payload: Mapping[str, object], root: str | Path = ".") -> Unattested | None:
|
|
898
|
+
"""The other half of the same `Stop`: bytes no verb wrote, stated once (RK175).
|
|
899
|
+
|
|
900
|
+
Beside :func:`review` rather than inside it, because the two answer different questions
|
|
901
|
+
and only one of them is about the format: `lint` asks whether the file is correct, and
|
|
902
|
+
this asks whether roadkeep put it there. A conforming hand-edit passes the first and is
|
|
903
|
+
the entire subject of the second, so folding them would hide it behind a clean report.
|
|
904
|
+
|
|
905
|
+
Silence on every failure and on `stop_hook_active`, on the rules the rest of this module
|
|
906
|
+
keeps: a broken config must not pin a session open, and blocking twice on one fact is a
|
|
907
|
+
loop. :mod:`roadkeep.attesting` re-baselines as it reports, so the second pass is silent
|
|
908
|
+
even where the harness never sets the flag.
|
|
909
|
+
"""
|
|
910
|
+
if payload.get("stop_hook_active") is True:
|
|
911
|
+
return None
|
|
912
|
+
try:
|
|
913
|
+
config = Config.discover(_cwd(payload, root))
|
|
914
|
+
except (ConfigError, OSError, tomllib.TOMLDecodeError):
|
|
915
|
+
return None
|
|
916
|
+
if config.source is None:
|
|
917
|
+
return None
|
|
918
|
+
from roadkeep.attesting import unattested # noqa: PLC0415 - RK260
|
|
919
|
+
|
|
920
|
+
return unattested(config)
|
|
921
|
+
|
|
922
|
+
|
|
923
|
+
def _this_turn(config: Config, report: Report) -> Report:
|
|
924
|
+
"""The same report, keeping only findings on lines the working tree changed (RK60).
|
|
925
|
+
|
|
926
|
+
The hook answers "did this turn leave the file in a state the format rejects", and a
|
|
927
|
+
project that adopted the tool with drift already in it would otherwise have every turn
|
|
928
|
+
blocked by history — 278 findings in Shio, none of them the session's. `roadkeep lint`,
|
|
929
|
+
the pre-commit hook and the Action are unchanged: they answer "is this file correct".
|
|
930
|
+
"""
|
|
931
|
+
from roadkeep.history import changed_lines # noqa: PLC0415 - RK260 the Stop path only
|
|
932
|
+
|
|
933
|
+
per_file: dict[str, frozenset[int] | None] = {}
|
|
934
|
+
kept = []
|
|
935
|
+
for finding in report.findings:
|
|
936
|
+
if finding.file not in per_file:
|
|
937
|
+
per_file[finding.file] = changed_lines(config, "HEAD", config.root / finding.file)
|
|
938
|
+
changed = per_file[finding.file]
|
|
939
|
+
# `None` is git declining to say, and a finding about the file itself (a budget) has
|
|
940
|
+
# no line to compare — both are judged, because neither can be excused.
|
|
941
|
+
if changed is None or finding.lineno is None or finding.lineno in changed:
|
|
942
|
+
kept.append(finding)
|
|
943
|
+
return replace(report, findings=tuple(kept))
|
|
944
|
+
|
|
945
|
+
|
|
946
|
+
def owning(path: str | Path) -> Config | None:
|
|
947
|
+
"""The project whose declaration covers ``path``, or ``None`` (RK1283).
|
|
948
|
+
|
|
949
|
+
The half :func:`governed` and :func:`advise` share, split out because both of them wanted
|
|
950
|
+
it on the same call: the barrier resolved the config per target, threw it away on the way
|
|
951
|
+
to `None`, and the advice then discovered the same file again — one `find_config` walk and
|
|
952
|
+
one `tomllib` parse per **allowed** write, which is the path every `Edit` a session makes
|
|
953
|
+
goes down.
|
|
954
|
+
|
|
955
|
+
Discovery walks up from the file itself, so the answer does not depend on where the hook
|
|
956
|
+
process happened to be started.
|
|
957
|
+
"""
|
|
958
|
+
found = find_config(Path(path).parent)
|
|
959
|
+
if found is None:
|
|
960
|
+
return None
|
|
961
|
+
try:
|
|
962
|
+
return Config.load(found)
|
|
963
|
+
except (ConfigError, OSError, tomllib.TOMLDecodeError):
|
|
964
|
+
return None
|
|
965
|
+
|
|
966
|
+
|
|
967
|
+
def role_at(config: Config, path: str | Path) -> str | None:
|
|
968
|
+
"""Which governed role this path holds in that project, or ``None``.
|
|
969
|
+
|
|
970
|
+
`roadkeep.toml` is *not* governed: it is the per-project declaration (L6), which a human
|
|
971
|
+
edits by hand on purpose — and since RK1280 is told what four of its tables now have.
|
|
972
|
+
"""
|
|
973
|
+
wanted = _comparable(Path(path))
|
|
974
|
+
for role, declared in config.paths.items():
|
|
975
|
+
if _comparable(declared) == wanted:
|
|
976
|
+
return role
|
|
977
|
+
return None
|
|
978
|
+
|
|
979
|
+
|
|
980
|
+
def governed(path: str | Path) -> tuple[Config, str] | None:
|
|
981
|
+
"""The project that owns ``path`` and the role it holds there, or ``None``.
|
|
982
|
+
|
|
983
|
+
The pair the two readers above compose, kept because it is the question every caller
|
|
984
|
+
outside this module asks — one path, one answer — and because the tests that hold this
|
|
985
|
+
boundary are written against it.
|
|
986
|
+
"""
|
|
987
|
+
config = owning(path)
|
|
988
|
+
if config is None:
|
|
989
|
+
return None
|
|
990
|
+
role = role_at(config, path)
|
|
991
|
+
return None if role is None else (config, role)
|
|
992
|
+
|
|
993
|
+
|
|
994
|
+
def _comparable(path: Path) -> str:
|
|
995
|
+
"""A path as this filesystem compares them.
|
|
996
|
+
|
|
997
|
+
`normcase` and not `str`: on Windows `docs/ROADMAP.md` and `docs/roadmap.md` are one
|
|
998
|
+
file, and a comparison that misses that allows the write it exists to refuse.
|
|
999
|
+
"""
|
|
1000
|
+
return os.path.normcase(str(path.resolve()))
|
|
1001
|
+
|
|
1002
|
+
|
|
1003
|
+
def _comparable_text(text: str) -> str:
|
|
1004
|
+
"""A path *inside* a longer string, as this filesystem compares them (RK128).
|
|
1005
|
+
|
|
1006
|
+
The same `normcase` rule as above and for the same reason — on Windows it also settles the
|
|
1007
|
+
separator, so a command written with `/` and a declaration held as `\\` are one string. Not
|
|
1008
|
+
`resolve`: there is no path here to resolve, only characters that may contain one.
|
|
1009
|
+
"""
|
|
1010
|
+
return os.path.normcase(text)
|
|
1011
|
+
|
|
1012
|
+
|
|
1013
|
+
def _targets(raw: object, base: Path) -> tuple[Path, ...]:
|
|
1014
|
+
"""Every path the tool input names, resolved against the session's directory."""
|
|
1015
|
+
if not isinstance(raw, Mapping):
|
|
1016
|
+
return ()
|
|
1017
|
+
out: list[Path] = []
|
|
1018
|
+
for key in _PATH_KEYS:
|
|
1019
|
+
value = raw.get(key)
|
|
1020
|
+
if isinstance(value, str) and value:
|
|
1021
|
+
candidate = Path(value)
|
|
1022
|
+
out.append(candidate if candidate.is_absolute() else base / candidate)
|
|
1023
|
+
return tuple(out)
|
|
1024
|
+
|
|
1025
|
+
|
|
1026
|
+
def _cwd(payload: Mapping[str, object], root: str | Path) -> Path:
|
|
1027
|
+
value = payload.get("cwd")
|
|
1028
|
+
return Path(value if isinstance(value, str) and value else root)
|