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/briefing.py
ADDED
|
@@ -0,0 +1,970 @@
|
|
|
1
|
+
"""Everything it costs to start one task, in one call (RK29).
|
|
2
|
+
|
|
3
|
+
Starting RK1 in this repository cost reading `ROADMAP.md` and `IMPROVEMENTS.md` end to end
|
|
4
|
+
— some 5k tokens to learn one task, of which one line and one paragraph mattered. `pick`
|
|
5
|
+
(RK11) and `show` (RK12) each answer half; this composes them with the resolved deps
|
|
6
|
+
(RK28), the blocker chain (RK13) and the non-goals, so the answer to "start work" is a
|
|
7
|
+
single tool result.
|
|
8
|
+
|
|
9
|
+
**Bounded output is the point**, not a side effect: an answer that fits in a tool result
|
|
10
|
+
is an answer that costs nothing to consult twice, and one that does not fit gets replaced
|
|
11
|
+
by re-reading the file — which is the cost this removes. So the section is capped by its
|
|
12
|
+
own word budget (RK9), the chains by the graph's own limit, and the non-goals are carried
|
|
13
|
+
as *leads only*: enough to keep a proposal inside scope, not the paragraph that argues it.
|
|
14
|
+
|
|
15
|
+
Nothing here is stored and nothing is composed of new prose (L4): every field is another
|
|
16
|
+
module's answer, gathered in one place. Call it with no id and it briefs whatever `pick`
|
|
17
|
+
would choose, which makes the first call of a session the only one.
|
|
18
|
+
|
|
19
|
+
What it carries of the pick is the pick's own :class:`~roadkeep.picking.Choice` and not a
|
|
20
|
+
sentence copied out of it (RK154): a held line has to be *named* here for the reason it is
|
|
21
|
+
named there — a claim carries no owner, so an id is the only thing a caller recognises its own
|
|
22
|
+
by — and a field lifted out one at a time is a second place to keep in step.
|
|
23
|
+
|
|
24
|
+
**Which is why the claim has to be reachable from here** (RK149). RK119 made answering "what
|
|
25
|
+
next" a write so two agents get two lines, and put the flag on `pick` — the command a session
|
|
26
|
+
following the skill does not call, this one being the door that starts a task in one call. So
|
|
27
|
+
``claim`` takes the line as well as describing it, and the module's promise narrows from
|
|
28
|
+
*writes none* to *writes one marker, and only when asked*. The two callers it serves are not
|
|
29
|
+
the same act: with no id the claim is `pick`'s, which steps around what somebody else holds,
|
|
30
|
+
and with an id it is the caller's own assertion, which is refused where a live claim already
|
|
31
|
+
answers for that line (:func:`roadkeep.picking.hold`).
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
from __future__ import annotations
|
|
35
|
+
|
|
36
|
+
import textwrap
|
|
37
|
+
from collections.abc import Sequence
|
|
38
|
+
from dataclasses import dataclass, field
|
|
39
|
+
|
|
40
|
+
from roadkeep.backlog import Backlog, DepStatus, Readiness, Resolution, Standing
|
|
41
|
+
from roadkeep.budgeting import Budget, budget_of
|
|
42
|
+
from roadkeep.config import Config, Scope
|
|
43
|
+
from roadkeep.kernel.document import Document
|
|
44
|
+
from roadkeep.graph import Chain, Graph, Leverage
|
|
45
|
+
from roadkeep.history import Commit
|
|
46
|
+
from roadkeep import criteria, scoping
|
|
47
|
+
from roadkeep.claiming import Held
|
|
48
|
+
from roadkeep.locking import exclusive
|
|
49
|
+
from roadkeep.picking import Choice, Claim, Lacking, Waiting, hold, pick, take
|
|
50
|
+
from roadkeep.kernel.schema import Task
|
|
51
|
+
from roadkeep.remaining import Clause
|
|
52
|
+
from roadkeep.shipping import as_recorded, recording_cost, supersession_cost
|
|
53
|
+
from roadkeep.showing import View, show
|
|
54
|
+
|
|
55
|
+
#: How many blocker chains a brief carries. Lower than the graph's own limit on purpose:
|
|
56
|
+
#: a brief is read to start work, and the second chain is already context, not an answer.
|
|
57
|
+
CHAINS = 2
|
|
58
|
+
|
|
59
|
+
#: How many non-goals a brief carries, for the same reason (RK68): the list binds what may be
|
|
60
|
+
#: proposed, and a section long enough to need scrolling is the file back. Two live corpora
|
|
61
|
+
#: write seven and eight, so this is headroom over both rather than a cut anyone will meet.
|
|
62
|
+
NON_GOALS = 12
|
|
63
|
+
|
|
64
|
+
#: How many of the ids a task unblocks a brief carries (RK1301). The **count** is the answer —
|
|
65
|
+
#: it ranks this line against every other one and a caller reads it once — and the roster is
|
|
66
|
+
#: the file back: measured on quickshell, a fresh eighty-one-line backlog, where the first task
|
|
67
|
+
#: answered with seventy-nine ids spelled out, in a read RK29 bounded to a tool result and
|
|
68
|
+
#: RK1286 gave a ceiling. The case where the list is longest is exactly the case where it says
|
|
69
|
+
#: least, a task early in the graph unblocking essentially everything.
|
|
70
|
+
#:
|
|
71
|
+
#: `deps <id>` answers the roster whole and is where a caller who wants it goes. This number
|
|
72
|
+
#: bounds the printed row too, so the two registers cannot come to disagree about how much of
|
|
73
|
+
#: it a brief shows — it was the printer's own constant before it was a bound on the payload.
|
|
74
|
+
UNBLOCKS = 4
|
|
75
|
+
|
|
76
|
+
#: What a cut lead ends with. A space before it, so the mark reads as the tool's and not as
|
|
77
|
+
#: an author's ellipsis — the cut has to be visible where it happens, never silent.
|
|
78
|
+
ELLIPSIS = " …"
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class NothingToBrief(KeyError):
|
|
82
|
+
"""`pick` found no ready task, so there is nothing to start. Not a failure.
|
|
83
|
+
|
|
84
|
+
Carries the held ids where a claim is what emptied the answer (RK154): "every ready task
|
|
85
|
+
is claimed by a worker who has not finished it" is the one absence in this design a
|
|
86
|
+
caller cannot act on without them, a claim naming no owner and its own being the one it
|
|
87
|
+
would otherwise ask about again next turn.
|
|
88
|
+
"""
|
|
89
|
+
|
|
90
|
+
def __init__(
|
|
91
|
+
self,
|
|
92
|
+
reason: str,
|
|
93
|
+
held: tuple[Held, ...] = (),
|
|
94
|
+
standing: Standing | None = None,
|
|
95
|
+
lacking: tuple[Lacking, ...] = (),
|
|
96
|
+
) -> None:
|
|
97
|
+
self.held = held
|
|
98
|
+
#: The ready lines this caller has no way to finish, and what each would take
|
|
99
|
+
#: (RK1297). Carried for `held`'s reason and one further: a claim ends by itself,
|
|
100
|
+
#: and this absence ends only when the ids reach somebody who has the thing — so a
|
|
101
|
+
#: caller that cannot name them cannot even hand the work over.
|
|
102
|
+
self.lacking = lacking
|
|
103
|
+
#: What became of the block this was scoped to (RK429), where one was named. The
|
|
104
|
+
#: sentence above already states it; this is the same fact as a word, so a loop
|
|
105
|
+
#: driving a block to completion branches on `finished` rather than on English.
|
|
106
|
+
self.standing = standing
|
|
107
|
+
#: The bare sentence, before this class wraps it (RK409). Kept as a field because
|
|
108
|
+
#: `brief --json` answers this branch too now, and recovering it from `str(self)`
|
|
109
|
+
#: means stripping a prefix and `KeyError`'s own quoting — two spellings of the
|
|
110
|
+
#: reason, one of which goes wrong the first time either half is reworded.
|
|
111
|
+
self.reason = reason
|
|
112
|
+
named = ", ".join(f"{one.id} ({one.since} ago)" for one in held)
|
|
113
|
+
# Beside the held ids and on the same line, because this register is one string
|
|
114
|
+
# (RK1297): the sentence already says a requirement is missing, and these are the
|
|
115
|
+
# lines it is missing *for* — the half a caller needs to hand the work to somebody.
|
|
116
|
+
short = ", ".join(f"{one.id} ({', '.join(one.missing)})" for one in lacking)
|
|
117
|
+
super().__init__(
|
|
118
|
+
f"nothing to brief: {reason}"
|
|
119
|
+
+ (f" — held: {named}" if named else "")
|
|
120
|
+
+ (f" — absent: {short}" if short else "")
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@dataclass(frozen=True, slots=True)
|
|
125
|
+
class DoneWhen:
|
|
126
|
+
"""What would finish this task and what would finish its block (RK1265, RK1268).
|
|
127
|
+
|
|
128
|
+
:class:`NonGoals`' two fields for its reason, and a third thing this one has to state
|
|
129
|
+
without a field — **an empty list is not an empty answer here**. A block nobody wrote a
|
|
130
|
+
criterion for and a block whose criteria were all dropped are different facts, and `brief`
|
|
131
|
+
prints neither row rather than inventing a sentence about which: the difference is
|
|
132
|
+
`criterion list`'s to report, where a caller went to ask.
|
|
133
|
+
|
|
134
|
+
Two lists and not one, because they are two altitudes and the answer would otherwise
|
|
135
|
+
conflate them: the block's says when the body of work is finished and the task's own says
|
|
136
|
+
when this line is, and an agent starting the line is asking the second.
|
|
137
|
+
"""
|
|
138
|
+
|
|
139
|
+
leads: tuple[str, ...] = ()
|
|
140
|
+
#: How many the block's list held beyond the ones carried. 0 means these are all.
|
|
141
|
+
elided: int = 0
|
|
142
|
+
#: The task's own list, addressed by its id (RK1268), bounded the same way.
|
|
143
|
+
own: tuple[str, ...] = ()
|
|
144
|
+
#: How many the task's own list held beyond the ones carried. 0 means these are all.
|
|
145
|
+
own_elided: int = 0
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
@dataclass(frozen=True, slots=True)
|
|
149
|
+
class NonGoals:
|
|
150
|
+
"""The scope a proposal has to stay inside: the leads carried, and what was left.
|
|
151
|
+
|
|
152
|
+
Two fields because a bounded list that does not say it is bounded reads as the whole
|
|
153
|
+
list — the failure this is the fix for, one level up (RK68).
|
|
154
|
+
"""
|
|
155
|
+
|
|
156
|
+
leads: tuple[str, ...] = ()
|
|
157
|
+
#: How many bullets the section held beyond the ones carried. 0 means these are all.
|
|
158
|
+
elided: int = 0
|
|
159
|
+
|
|
160
|
+
def stated(self, config: Config) -> str:
|
|
161
|
+
"""The list at the moment a task is proposed (RK69), as a reader is told it.
|
|
162
|
+
|
|
163
|
+
Beside :meth:`payload` since RK1170. The rows take the shape `brief` prints, so the
|
|
164
|
+
list is recognisable as the same list and not as a second one that happens to agree
|
|
165
|
+
today — which is what a second projection of a scope would be.
|
|
166
|
+
"""
|
|
167
|
+
where = config.relative(config.path("roadmap"))
|
|
168
|
+
if not self.leads:
|
|
169
|
+
return f"{where}: no non-goals — nothing here says what may not be proposed"
|
|
170
|
+
# A project that has not opted in can still be read (RK70), and the report says which
|
|
171
|
+
# it is: `add` is what `[non_goals]` gates, and a listing that hid the difference would
|
|
172
|
+
# let a reader take an ungoverned list for an enforced one.
|
|
173
|
+
ungoverned = "" if config.non_goals is not None else " read-only: no [non_goals]"
|
|
174
|
+
rows = [f"{where} {len(self.leads)} non-goal(s){ungoverned}"]
|
|
175
|
+
rows += [f" not {lead}" for lead in self.leads]
|
|
176
|
+
if self.elided:
|
|
177
|
+
rows.append(f" not … and {self.elided} more under Non-goals")
|
|
178
|
+
return "\n".join(rows)
|
|
179
|
+
|
|
180
|
+
def payload(self, config: Config) -> dict[str, object]:
|
|
181
|
+
return {
|
|
182
|
+
"file": config.relative(config.path("roadmap")),
|
|
183
|
+
# A project that has not opted in can still be read — `add` is what `[non_goals]`
|
|
184
|
+
# gates (RK70), and refusing the read too would leave the scope of two live corpora
|
|
185
|
+
# unaskable.
|
|
186
|
+
"governed": config.non_goals is not None,
|
|
187
|
+
"non_goals": list(self.leads),
|
|
188
|
+
"non_goals_elided": self.elided,
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
@dataclass(frozen=True, slots=True)
|
|
193
|
+
class Settled:
|
|
194
|
+
"""A dep that shipped **after** this design was last revised (RK1163).
|
|
195
|
+
|
|
196
|
+
Measured on a real run. A task asked whether a check should widen, and its rationale argued
|
|
197
|
+
both sides — widening risks a report full of findings about work somebody is still writing,
|
|
198
|
+
which is the noise that gets a check switched off. Its dep then shipped a unique index, and
|
|
199
|
+
that deleted one side of the trade-off: what was left to report could no longer be anybody's
|
|
200
|
+
unfinished draft. The section still read as an open question, and `brief` handed it over
|
|
201
|
+
verbatim beside `deps_resolved: shipped`. Both facts were on screen and nothing joined them.
|
|
202
|
+
|
|
203
|
+
**A date and not a judgement.** What changed is in the dep's own commit, and saying which
|
|
204
|
+
part of a design it settles would be this tool writing prose about a trade-off (L4). So the
|
|
205
|
+
fact is the ordering — the section predates the ship — and the reader decides.
|
|
206
|
+
|
|
207
|
+
Empty wherever git cannot answer, which is a checkout with no history and a project whose
|
|
208
|
+
prose file is untracked: a note that cannot be dated is a guess, and this is a query.
|
|
209
|
+
"""
|
|
210
|
+
|
|
211
|
+
dep: str
|
|
212
|
+
#: The commit that shipped it, so the reader can go straight to what changed.
|
|
213
|
+
shipped: Commit
|
|
214
|
+
#: The last commit that touched this design, which is what "predates" is measured against.
|
|
215
|
+
revised: Commit
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
@dataclass(frozen=True, slots=True)
|
|
219
|
+
class Brief:
|
|
220
|
+
"""One task, and every derived fact needed to start it."""
|
|
221
|
+
|
|
222
|
+
view: View
|
|
223
|
+
readiness: Readiness
|
|
224
|
+
deps: tuple[Resolution, ...]
|
|
225
|
+
chains: tuple[Chain, ...]
|
|
226
|
+
leverage: Leverage
|
|
227
|
+
non_goals: NonGoals
|
|
228
|
+
#: What would finish **this task's block** (RK1265), as leads in file order and bounded
|
|
229
|
+
#: the way the non-goals are. Beside them because they are the same kind of statement
|
|
230
|
+
#: pointed opposite ways — one binds what may be proposed, the other says when the body
|
|
231
|
+
#: of work is done — and a task starts against both or against neither.
|
|
232
|
+
done_when: DoneWhen = field(default_factory=lambda: DoneWhen())
|
|
233
|
+
#: The pick that chose this id, absent where the caller named one (RK154). The whole
|
|
234
|
+
#: answer and not the sentence it used to be: `held` is the ids a live claim was stepped
|
|
235
|
+
#: around, and with no owner field a caller recognises its own only by reading them. One
|
|
236
|
+
#: field rather than five, so the next question `pick` already answers is a field here and
|
|
237
|
+
#: not a change — while what this *prints* stays bounded, which is why the counts are left
|
|
238
|
+
#: to the command that is about them.
|
|
239
|
+
choice: Choice | None = None
|
|
240
|
+
#: The line taken, where the caller asked for it (RK149). Absent otherwise, so a brief
|
|
241
|
+
#: that claimed nothing cannot be read as one that did.
|
|
242
|
+
claim: Claim | None = None
|
|
243
|
+
#: Deps that shipped after this design was last revised (RK1163) — the question a
|
|
244
|
+
#: dependency may have answered, said as an ordering and never as a claim about the prose.
|
|
245
|
+
settled: tuple[Settled, ...] = ()
|
|
246
|
+
#: What the **ship** this brief is starting will have for prose (RK1174). The same field of
|
|
247
|
+
#: the same task, measured under the ledger's grammar: `[limits.changelog]` and a line with
|
|
248
|
+
#: no deps and no pointer in it. Two numbers for what an author thinks of as one thing, and
|
|
249
|
+
#: only the one that does not apply was shown before the write — measured across four ships
|
|
250
|
+
#: in one session, three of them refused for `why.too-long` on the first attempt.
|
|
251
|
+
#:
|
|
252
|
+
#: None where the project declares no changelog, and on a shipped line, which has no ship
|
|
253
|
+
#: left to compose for.
|
|
254
|
+
shipping: Budget | None = None
|
|
255
|
+
#: What the **decision** that same ship may file will have for prose (RK1275). Its own
|
|
256
|
+
#: field and not a clause of the row above, because it is not that sentence at all: a
|
|
257
|
+
#: `--decides` writes a line in the decisions role, under that role's own limits, and the
|
|
258
|
+
#: one sentence this format asked an author to compose blind was the one recording what
|
|
259
|
+
#: outlives the code. None where the project declares no such role.
|
|
260
|
+
deciding: Budget | None = None
|
|
261
|
+
#: What this line has left for prose (RK190). Here because a brief is the call that
|
|
262
|
+
#: starts a task, and the next write on the line it handed over is an `amend` — so the
|
|
263
|
+
#: number that would otherwise arrive as a refusal is already on the desk. None for a
|
|
264
|
+
#: shipped task: the ledger is a different grammar and holds no line to amend.
|
|
265
|
+
budget: Budget | None = None
|
|
266
|
+
#: What this task's design says would prove it done, and how many sites each clause
|
|
267
|
+
#: matches **now** (RK1184, RK1185). A count and a quotation, never the files behind
|
|
268
|
+
#: them: this answer is bounded to a tool result, and the addresses are what `evidence`
|
|
269
|
+
#: is for once the work is under way.
|
|
270
|
+
#:
|
|
271
|
+
#: Empty where the design declares no criterion, and that is answered with silence: most
|
|
272
|
+
#: tasks state one in prose and always have, so printing an absence every turn is a nag
|
|
273
|
+
#: this tool has no standing to make.
|
|
274
|
+
criterion: tuple[tuple[Clause, int], ...] = ()
|
|
275
|
+
#: What has already **landed** of this task, as the ledger records it (RK1226). One string
|
|
276
|
+
#: per `ship --part`, in the order the ledger holds them, and empty for the ordinary line
|
|
277
|
+
#: that has shipped nothing.
|
|
278
|
+
#:
|
|
279
|
+
#: `ship --part` records the half that landed and leaves the line open, which is the right
|
|
280
|
+
#: shape: the ledger gains an entry qualified by what shipped and the roadmap keeps a task
|
|
281
|
+
#: whose sentence is still partly true. What nothing held was the **other** half. Reading
|
|
282
|
+
#: the ⏳ line said the problem was not solved and reading the ledger said what was done, so
|
|
283
|
+
#: the remainder was reconstructed by subtracting one from the other — across two files,
|
|
284
|
+
#: from prose written for different purposes, by whoever picked the line up. That
|
|
285
|
+
#: reconstruction happened here several sessions later and needed the whole design read to
|
|
286
|
+
#: recover a remainder the person shipping had known precisely.
|
|
287
|
+
#:
|
|
288
|
+
#: The subtraction is still the reader's; what changes is that both sides of it are on one
|
|
289
|
+
#: answer. Naming the remainder as *data* is the stronger version and a change to the
|
|
290
|
+
#: model — a second field on the entry — which RK1226 leaves open rather than guessing at.
|
|
291
|
+
landed: tuple[str, ...] = ()
|
|
292
|
+
|
|
293
|
+
@property
|
|
294
|
+
def task(self) -> Task:
|
|
295
|
+
return self.view.task
|
|
296
|
+
|
|
297
|
+
@property
|
|
298
|
+
def picked(self) -> str:
|
|
299
|
+
"""Why this id was chosen, or empty where the caller named it."""
|
|
300
|
+
return "" if self.choice is None else self.choice.reason
|
|
301
|
+
|
|
302
|
+
@property
|
|
303
|
+
def held(self) -> tuple[Held, ...]:
|
|
304
|
+
"""The ready lines a live claim kept out of the pick this brief came from."""
|
|
305
|
+
return () if self.choice is None else self.choice.held
|
|
306
|
+
|
|
307
|
+
def _clauses(self) -> list[dict[str, object]]:
|
|
308
|
+
"""What `ship`'s two optional flags spend out of the ledger sentence (RK1306).
|
|
309
|
+
|
|
310
|
+
Derived from the anchor and nothing else, which is the whole reason a number exists to
|
|
311
|
+
publish: `--superseded-design` parenthesises a note beside the pointer the line already
|
|
312
|
+
carries and `--recorded-in` wraps a path beside it, so the brackets and the address are
|
|
313
|
+
knowable before either is written and only the caller's own prose is not.
|
|
314
|
+
|
|
315
|
+
`[]` where there is no ship to compose for, or where the line points at nothing — both
|
|
316
|
+
figures are measured off an anchor, and inventing one would price a clause the write
|
|
317
|
+
cannot append. A record per flag rather than two keys, so `yours` can say **what the
|
|
318
|
+
number leaves out**: a consumer that added neither its note nor its path would
|
|
319
|
+
under-count by exactly the prose it is holding while it reads this.
|
|
320
|
+
"""
|
|
321
|
+
if self.shipping is None or self.task.ref is None:
|
|
322
|
+
return []
|
|
323
|
+
return [
|
|
324
|
+
{
|
|
325
|
+
"flag": "--superseded-design",
|
|
326
|
+
"wrapper": supersession_cost(self.task.ref, self.task.id),
|
|
327
|
+
"yours": "the note",
|
|
328
|
+
},
|
|
329
|
+
{
|
|
330
|
+
"flag": "--recorded-in",
|
|
331
|
+
"wrapper": recording_cost(self.task.ref, self.task.id),
|
|
332
|
+
"yours": "the path",
|
|
333
|
+
},
|
|
334
|
+
]
|
|
335
|
+
|
|
336
|
+
@property
|
|
337
|
+
def waiting(self) -> tuple[Waiting, ...]:
|
|
338
|
+
"""What the declared priority is waiting on, where nothing ready answered it (RK1304).
|
|
339
|
+
|
|
340
|
+
Off the choice for :attr:`held`'s reason: it is a fact about the pick this brief came
|
|
341
|
+
from, so a brief called with an id has none — nothing was ranked and no queue was
|
|
342
|
+
consulted, and inventing the reading here would answer a question nobody asked.
|
|
343
|
+
"""
|
|
344
|
+
return () if self.choice is None else self.choice.waiting
|
|
345
|
+
|
|
346
|
+
def stated(self, config: Config) -> str:
|
|
347
|
+
"""Everything needed to start this task, as a reader is told it (RK29).
|
|
348
|
+
|
|
349
|
+
Beside :meth:`payload` since RK1170, and the last of the verbs that task measured: 20
|
|
350
|
+
prints in the handler against a builder in `rendering.py`, one answer in two files with
|
|
351
|
+
neither of them where the brief is composed. The five sentences shared with `pick` compose
|
|
352
|
+
here because those produce rows, which is what the two prerequisite slices bought.
|
|
353
|
+
|
|
354
|
+
**Bounded, and that is the claim this file exists to keep.** An answer that fits in a tool
|
|
355
|
+
result costs nothing to consult twice; one that does not gets replaced by re-reading the
|
|
356
|
+
file, which is the 5k tokens this verb exists to stop spending — so the non-goals are
|
|
357
|
+
elided with a count and the budget is one line rather than the whole table.
|
|
358
|
+
"""
|
|
359
|
+
from roadkeep.rendering import ( # noqa: PLC0415 - RK260, the cycle's one direction
|
|
360
|
+
_claim_event,
|
|
361
|
+
_claim_rows,
|
|
362
|
+
_event_rows,
|
|
363
|
+
_held_rows,
|
|
364
|
+
_leverage_rows,
|
|
365
|
+
_waiting_rows,
|
|
366
|
+
)
|
|
367
|
+
from roadkeep.sections import heading_of # noqa: PLC0415 - RK260
|
|
368
|
+
|
|
369
|
+
view, task = self.view, self.task
|
|
370
|
+
rows = [
|
|
371
|
+
f"{task.id} Block {task.block} {task.status} {self.readiness} "
|
|
372
|
+
f"{view.file}:{view.entry.lineno}"
|
|
373
|
+
]
|
|
374
|
+
if self.picked:
|
|
375
|
+
rows.append(f" picked {self.picked}")
|
|
376
|
+
if self.choice is not None:
|
|
377
|
+
# What the declared priority is waiting on, where nothing ready answered it
|
|
378
|
+
# (RK1304). Beside `picked` because that is the sentence it completes: *the queue
|
|
379
|
+
# names nothing ready* is true and does not say which task would change it.
|
|
380
|
+
rows += _waiting_rows(self.choice)
|
|
381
|
+
# The ids a live claim was stepped around (RK154), on the door a session starts a task
|
|
382
|
+
# with: without them the caller cannot tell one of them is its own.
|
|
383
|
+
rows += _held_rows(self.choice)
|
|
384
|
+
taken = _claim_rows(self.claim, config)
|
|
385
|
+
rows += taken
|
|
386
|
+
event = _claim_event(self.claim, config)
|
|
387
|
+
if taken and event is not None:
|
|
388
|
+
# Beside the claim and not at the end: the rationale section closes this output, and
|
|
389
|
+
# an event line after a paragraph of prose is one a hook reader has to hunt for.
|
|
390
|
+
rows += _event_rows(event, " ")
|
|
391
|
+
rows.append(f" symptom {task.symptom}")
|
|
392
|
+
rows.append(f" why {task.why}")
|
|
393
|
+
if self.budget is not None:
|
|
394
|
+
# One line, and only the field an amend rewrites (RK190): the whole table is
|
|
395
|
+
# `budget`'s answer, and a brief that grew one would stop being a bounded one.
|
|
396
|
+
why = self.budget.share("why")
|
|
397
|
+
# The same figure `budget` states, off the same `Share` (RK245): a brief that named
|
|
398
|
+
# the whole field's aim beside this line's remainder would be the second answer.
|
|
399
|
+
#
|
|
400
|
+
# `allowed`, and `on <the line>` in the words the two rows under it use (RK1375).
|
|
401
|
+
# These three exist to be **compared** — RK1174 prints the second only where it
|
|
402
|
+
# differs, because two numbers for one field is the fact worth seeing — and a
|
|
403
|
+
# reader made to translate `left` into `for the ledger line` before subtracting
|
|
404
|
+
# pays that cost through the phrasing instead of through the repetition. Since
|
|
405
|
+
# RK1366 neither figure is what is left beside anything, so `left` was the word
|
|
406
|
+
# that had stopped describing either, and the branch spelling it for a draft was
|
|
407
|
+
# unreachable from here: this budget is always the line as it stands.
|
|
408
|
+
rows.append(
|
|
409
|
+
f" budget why {why.allowed} on this line, {why.aimed}, "
|
|
410
|
+
f"{self.budget.prose} for prose"
|
|
411
|
+
)
|
|
412
|
+
if self.shipping is not None:
|
|
413
|
+
# The allowance for the write this brief is starting, which is not the one above
|
|
414
|
+
# (RK1174): a `ship` writes a ledger line, whose limit is `[limits.changelog]` and
|
|
415
|
+
# whose structure carries no deps and no pointer. Measured across four ships in one
|
|
416
|
+
# session, three refused for `why.too-long` on the first attempt — a refusal that
|
|
417
|
+
# names the arithmetic and cannot arrive early, which is what this line is for.
|
|
418
|
+
#
|
|
419
|
+
# Printed only where it **differs**: two numbers for one field is the fact worth
|
|
420
|
+
# seeing, and repeating the same one under another name teaches nobody anything.
|
|
421
|
+
ship = self.shipping.share("why")
|
|
422
|
+
if self.budget is None or ship.allowed != self.budget.share("why").allowed:
|
|
423
|
+
# And what a supersession takes out of the same sentence (RK1261). The other
|
|
424
|
+
# hedge stays a hedge because a qualifier is prose this cannot know; this one
|
|
425
|
+
# is *derived*, the anchor being the pointer the line already carries — and a
|
|
426
|
+
# task about to lose its design is exactly when this allowance is read, so an
|
|
427
|
+
# answer that omitted it was wrong precisely when it was asked for.
|
|
428
|
+
rows.append(
|
|
429
|
+
f" shipping why {ship.allowed} on the ledger line a `ship` writes, which "
|
|
430
|
+
f"is the limit that refuses it — the whole of it, that sentence replacing "
|
|
431
|
+
f"this line's rather than extending it (RK1365) — less a `--part` "
|
|
432
|
+
f"qualifier, which is structure this cannot know you will pass"
|
|
433
|
+
)
|
|
434
|
+
# Both clauses and no longer one (RK1275): two flags landed in that sentence
|
|
435
|
+
# after this row learned to name the first, so the figure was wrong by an
|
|
436
|
+
# amount this tool knows. A row of their own rather than a third subordinate
|
|
437
|
+
# clause — the line above is already the longest a brief prints.
|
|
438
|
+
if task.ref is not None:
|
|
439
|
+
rows.append(
|
|
440
|
+
f" shipping less {supersession_cost(task.ref, task.id)} for a "
|
|
441
|
+
f"`--superseded-design` clause and {recording_cost(task.ref, task.id)} for a "
|
|
442
|
+
f"`--recorded-in` wrapper, both into that same sentence — the note "
|
|
443
|
+
f"and the path are yours and are not in either number"
|
|
444
|
+
)
|
|
445
|
+
if self.deciding is not None:
|
|
446
|
+
# The third write, and the one that is not that sentence at all (RK1275): a
|
|
447
|
+
# `--decides` files a line in the decisions role under that role's own limits, so
|
|
448
|
+
# a reader given only the ledger's number was composing the durable half blind.
|
|
449
|
+
decided = self.deciding.share("why")
|
|
450
|
+
rows.append(
|
|
451
|
+
f" deciding why {decided.allowed} on the line `--decides` files, which is "
|
|
452
|
+
f"the decisions role's own limit and not the ledger's — the constraint that "
|
|
453
|
+
f"outlives the code, refused by that number"
|
|
454
|
+
)
|
|
455
|
+
# The **claim** that line inherits, where the decisions file is narrower than the
|
|
456
|
+
# roadmap (RK1281): `--decides` writes no symptom, so a ship refused over one is
|
|
457
|
+
# refused for a field no flag on the call reaches — and the read that could have
|
|
458
|
+
# said so beforehand priced the `why` and stopped. Printed only where it binds,
|
|
459
|
+
# which is two numbers for one field being the fact worth seeing (RK1174).
|
|
460
|
+
claim = self.deciding.share("symptom")
|
|
461
|
+
if self.budget is not None and claim.allowed < self.budget.share("symptom").allowed:
|
|
462
|
+
rows.append(
|
|
463
|
+
f" deciding symptom {claim.taken} of {claim.allowed} there, inherited "
|
|
464
|
+
f"from this line's own claim — `--decides` does not write one, so "
|
|
465
|
+
f"`restate` or a wider limit are the two doors if it does not fit"
|
|
466
|
+
)
|
|
467
|
+
settled = {one.dep: one for one in self.settled}
|
|
468
|
+
for resolution in self.deps:
|
|
469
|
+
rows.append(
|
|
470
|
+
f" dep {resolution.dep.id} {resolution.status} {resolution.detail}"
|
|
471
|
+
)
|
|
472
|
+
landed = settled.get(resolution.dep.id)
|
|
473
|
+
if landed is not None:
|
|
474
|
+
# The ordering and never a claim about the prose (RK1163): the design below was
|
|
475
|
+
# last written before this dep shipped, so a trade-off it argues may already be
|
|
476
|
+
# decided — and what decided it is in that commit, which is what this names.
|
|
477
|
+
rows.append(
|
|
478
|
+
f" shipped {landed.shipped.date[:10]} in "
|
|
479
|
+
f"{landed.shipped.short}, after this design was last written "
|
|
480
|
+
f"({landed.revised.date[:10]})"
|
|
481
|
+
)
|
|
482
|
+
rows += [f" chain {chain.render(task.id)} — {chain.detail}" for chain in self.chains]
|
|
483
|
+
if not view.shipped:
|
|
484
|
+
# What shipping this would unblock, which a shipped line has already done (RK324):
|
|
485
|
+
# `unblocks 0 of 14 open` beside a checkmark is a cost quoted for work that happened,
|
|
486
|
+
# and the readiness word above is the whole answer a caller needs about it.
|
|
487
|
+
rows += _leverage_rows(self.leverage)
|
|
488
|
+
rows += [
|
|
489
|
+
f" path {one.path}{'' if one.exists else ' (missing)'}" for one in view.paths
|
|
490
|
+
]
|
|
491
|
+
# Before the criterion and after the deps, which is where a fact about *this* line's
|
|
492
|
+
# own history belongs (RK1226): what already landed is the other side of the
|
|
493
|
+
# subtraction whoever picks a partial up has to make, and the design is what they
|
|
494
|
+
# would otherwise read in full to make it.
|
|
495
|
+
rows += [f" landed {one}" for one in self.landed]
|
|
496
|
+
for clause, found in self.criterion:
|
|
497
|
+
# Before the design and after the deps, which is where the claim belongs: the
|
|
498
|
+
# order is the whole point (RK1185) — what the work will be measured against
|
|
499
|
+
# arrives before the first edit rather than at the `ship`. Never a verdict: `0`
|
|
500
|
+
# is the ordinary state of a task about to start.
|
|
501
|
+
rows.append(f" proves {clause} ({found} site(s) now)")
|
|
502
|
+
# The task's own first and the block's under it, each carrying its address (RK1268):
|
|
503
|
+
# two altitudes printed as one list is a reader taking the block's finish line for
|
|
504
|
+
# this line's, which is the conflation the second address exists to end.
|
|
505
|
+
rows += [f" done {self.view.task.id}: {lead}" for lead in self.done_when.own]
|
|
506
|
+
if self.done_when.own_elided:
|
|
507
|
+
rows.append(
|
|
508
|
+
f" done {self.view.task.id}: ... and {self.done_when.own_elided} more "
|
|
509
|
+
f"under Done when"
|
|
510
|
+
)
|
|
511
|
+
named = config.schema.block_named(self.view.task.block)
|
|
512
|
+
rows += [f" done {named}: {lead}" for lead in self.done_when.leads]
|
|
513
|
+
if self.done_when.elided:
|
|
514
|
+
rows.append(
|
|
515
|
+
f" done {named}: ... and {self.done_when.elided} more under Done when"
|
|
516
|
+
)
|
|
517
|
+
rows += [f" not {lead}" for lead in self.non_goals.leads]
|
|
518
|
+
if self.non_goals.elided:
|
|
519
|
+
# Where the list was cut, and not silently: a bounded list that reads as the whole
|
|
520
|
+
# one is a proposal made against a scope it never saw (RK68).
|
|
521
|
+
rows.append(f" not … and {self.non_goals.elided} more under Non-goals")
|
|
522
|
+
if view.section is not None:
|
|
523
|
+
rows += ["", heading_of(config.schema, view.section), "", view.section.body]
|
|
524
|
+
else:
|
|
525
|
+
rows.append(f" section none — {view.section_absence}")
|
|
526
|
+
return "\n".join(rows)
|
|
527
|
+
|
|
528
|
+
def payload(self, config: Config) -> dict[str, object]:
|
|
529
|
+
"""The same answer as data, with the whole budget table and every count (RK29).
|
|
530
|
+
|
|
531
|
+
Beside :meth:`stated` and deliberately wider: a tool result is read by something that
|
|
532
|
+
can hold it, so what the printed register elides with a count this carries in full —
|
|
533
|
+
the non-goals, both allowances, and the commits behind a settled dep.
|
|
534
|
+
"""
|
|
535
|
+
from roadkeep.rendering import ( # noqa: PLC0415 - RK260
|
|
536
|
+
_claim_event,
|
|
537
|
+
_dated_json,
|
|
538
|
+
)
|
|
539
|
+
|
|
540
|
+
return {
|
|
541
|
+
**self.view.payload(),
|
|
542
|
+
"readiness": str(self.readiness),
|
|
543
|
+
"picked": self.picked or None,
|
|
544
|
+
"deps_resolved": [
|
|
545
|
+
{
|
|
546
|
+
"dep": r.dep.id,
|
|
547
|
+
"kind": str(r.kind),
|
|
548
|
+
"status": str(r.status),
|
|
549
|
+
"detail": r.detail,
|
|
550
|
+
# Where this dep shipped after the design was last written (RK1163), the two
|
|
551
|
+
# commits that say so — beside the resolution rather than in a list of their
|
|
552
|
+
# own, because it is a fact *about* this dep and a consumer reading the row
|
|
553
|
+
# would otherwise join two arrays to find it.
|
|
554
|
+
**{
|
|
555
|
+
"settled_since": {
|
|
556
|
+
"shipped": _dated_json(one.shipped),
|
|
557
|
+
"revised": _dated_json(one.revised),
|
|
558
|
+
}
|
|
559
|
+
for one in self.settled
|
|
560
|
+
if one.dep == r.dep.id
|
|
561
|
+
},
|
|
562
|
+
}
|
|
563
|
+
for r in self.deps
|
|
564
|
+
],
|
|
565
|
+
"chains": [
|
|
566
|
+
{
|
|
567
|
+
"path": [self.task.id, *(hop.target for hop in c.hops)],
|
|
568
|
+
"end": str(c.end),
|
|
569
|
+
"detail": c.detail,
|
|
570
|
+
}
|
|
571
|
+
for c in self.chains
|
|
572
|
+
],
|
|
573
|
+
# The count whole and the roster bounded (RK1301), which is what the non-goals list
|
|
574
|
+
# in this same payload already does: a handful of ids, and how many were left, so a
|
|
575
|
+
# caller can tell a short list from a cut one without a second call. `deps <id>` is
|
|
576
|
+
# where the whole roster lives, and it is the read that answers that question.
|
|
577
|
+
"unblocks": {
|
|
578
|
+
"count": self.leverage.count,
|
|
579
|
+
"of": self.leverage.of,
|
|
580
|
+
"transitive": list(self.leverage.transitive[:UNBLOCKS]),
|
|
581
|
+
"transitive_elided": max(0, self.leverage.count - UNBLOCKS),
|
|
582
|
+
},
|
|
583
|
+
"non_goals": list(self.non_goals.leads),
|
|
584
|
+
"non_goals_elided": self.non_goals.elided,
|
|
585
|
+
"done_when": list(self.done_when.leads),
|
|
586
|
+
"done_when_elided": self.done_when.elided,
|
|
587
|
+
# The task's own, as its own key (RK1268): a caller merging the two would be
|
|
588
|
+
# asserting the block's finish line about this line.
|
|
589
|
+
"done_when_own": list(self.done_when.own),
|
|
590
|
+
"done_when_own_elided": self.done_when.own_elided,
|
|
591
|
+
# What the design says would prove this done, with what each clause matches now
|
|
592
|
+
# (RK1185). The clauses and the counts and never the sites: this answer is bounded
|
|
593
|
+
# to a tool result, and the addresses are `evidence`'s once the work is under way.
|
|
594
|
+
# `[]` where the design declares none, which is an answer and not an absence.
|
|
595
|
+
# What the ledger already records as landed, per `ship --part` (RK1226). `[]` on
|
|
596
|
+
# the ordinary line, which is an answer rather than an absence.
|
|
597
|
+
"landed": list(self.landed),
|
|
598
|
+
"criterion": [
|
|
599
|
+
{"pathspec": one.pathspec, "pattern": one.pattern, "sites": found}
|
|
600
|
+
for one, found in self.criterion
|
|
601
|
+
],
|
|
602
|
+
# The whole table here and one line on stdout (RK190): a tool result is read by
|
|
603
|
+
# something that can hold it, and this is the number the next write is measured on.
|
|
604
|
+
"budget": None if self.budget is None else self.budget.payload(),
|
|
605
|
+
# The write about to be made (RK1174), as its **difference** from the table above
|
|
606
|
+
# rather than as a second copy of it (RK1298). Always published where it exists —
|
|
607
|
+
# unlike the printed line, which is silent when the two agree: a consumer comparing
|
|
608
|
+
# them wants the numbers present, and what it never wanted is five rows repeated to
|
|
609
|
+
# say nothing. `against` names the base, so the overlay needs no convention.
|
|
610
|
+
"shipping": None
|
|
611
|
+
if self.shipping is None
|
|
612
|
+
else self.shipping.delta(self.budget, "budget" if self.budget else None),
|
|
613
|
+
# The third write (RK1275), diffed against the second where there is one: a project
|
|
614
|
+
# declaring both roles usually declares them the same limits, so `changed: {}` is the
|
|
615
|
+
# answer — and it is a fact, where a third identical table was the same fact spelled
|
|
616
|
+
# in every row it has.
|
|
617
|
+
"deciding": None
|
|
618
|
+
if self.deciding is None
|
|
619
|
+
else self.deciding.delta(
|
|
620
|
+
self.shipping or self.budget,
|
|
621
|
+
"shipping" if self.shipping else ("budget" if self.budget else None),
|
|
622
|
+
),
|
|
623
|
+
# And what the two optional clauses spend **out of** that allowance (RK1306). The
|
|
624
|
+
# row above stdout has carried them since RK1261 and RK1275 and the payload never
|
|
625
|
+
# did, so the caller this project is built for — the one on the other end of the
|
|
626
|
+
# served tool — composed a `why` against the published number and was refused by
|
|
627
|
+
# arithmetic it had no way to do. Measured on quickshell at five ships out of five:
|
|
628
|
+
# QS8, QS9, QS10, QS87 and QS88 each took a `why.too-long` first, and every one
|
|
629
|
+
# passed `--recorded-in` or `--superseded-design` or both.
|
|
630
|
+
#
|
|
631
|
+
# The **wrappers** and never the whole clause, which is what makes them knowable:
|
|
632
|
+
# the anchor is the pointer the line already carries, so only the note and the path
|
|
633
|
+
# are the caller's — and those the caller is holding while it reads this. `[]`
|
|
634
|
+
# where the line points at nothing, both figures being derived from the anchor.
|
|
635
|
+
#
|
|
636
|
+
# **Not `doors`, and the name now says so** (RK1324). These are *costs* and not
|
|
637
|
+
# calls: RK1324's falsification asked whether the four names were four facts,
|
|
638
|
+
# and this is the one that was — so it keeps its own key and stops reading as
|
|
639
|
+
# the class a consumer looks for a runnable command in.
|
|
640
|
+
"clause_costs": self._clauses(),
|
|
641
|
+
# Same key and same shape as `pick`'s (RK154): one fact spelled two ways is two facts.
|
|
642
|
+
"held": [{"id": h.id, "age": round(h.age), "since": h.since} for h in self.held],
|
|
643
|
+
# And the same for what the priority is waiting on (RK1304), by the same rule: this
|
|
644
|
+
# verb answers the pick's question too, so it answers it in the pick's words.
|
|
645
|
+
"waiting": [
|
|
646
|
+
{
|
|
647
|
+
"token": one.token,
|
|
648
|
+
"lines": one.lines,
|
|
649
|
+
"releases": list(one.releases),
|
|
650
|
+
"of": one.of,
|
|
651
|
+
}
|
|
652
|
+
for one in self.waiting
|
|
653
|
+
],
|
|
654
|
+
"claimed": None
|
|
655
|
+
if self.claim is None or self.claim.change is None
|
|
656
|
+
else {
|
|
657
|
+
"taken": True,
|
|
658
|
+
"from": self.claim.change.before,
|
|
659
|
+
"to": self.claim.change.after,
|
|
660
|
+
},
|
|
661
|
+
"event": _claim_event(self.claim, config),
|
|
662
|
+
}
|
|
663
|
+
|
|
664
|
+
|
|
665
|
+
def brief(
|
|
666
|
+
config: Config,
|
|
667
|
+
task_id: str | None = None,
|
|
668
|
+
block: str | None = None,
|
|
669
|
+
designed: bool = False,
|
|
670
|
+
claim: bool = False,
|
|
671
|
+
available: Sequence[str] = (),
|
|
672
|
+
) -> Brief:
|
|
673
|
+
"""Join every answer about one task, and take it where the caller asked to.
|
|
674
|
+
|
|
675
|
+
``block`` scopes the pick when no id is given (RK40), so "start the next thing in
|
|
676
|
+
Block C" is one call whose absence of an answer is about Block C. ``designed`` narrows
|
|
677
|
+
it to work whose design is written (RK83) — the two flags together are what "execute
|
|
678
|
+
Block C" means, and neither reaches a brief the caller addressed by id.
|
|
679
|
+
|
|
680
|
+
``available`` is what this caller has (RK1297), and it reaches the pick for the reason
|
|
681
|
+
the two above do: a brief is the call that *starts* work, so the one filter whose answer
|
|
682
|
+
is "not by you" belongs where the line is chosen and not where it is described.
|
|
683
|
+
|
|
684
|
+
``claim`` moves the marker to in-progress (RK149). One lock covers the write **and** the
|
|
685
|
+
reading that follows it, so the brief describes the line as it was taken rather than as
|
|
686
|
+
some later state found it — the four reads being milliseconds, which is what makes
|
|
687
|
+
holding the write lock across them free.
|
|
688
|
+
"""
|
|
689
|
+
if claim:
|
|
690
|
+
with exclusive(config.root):
|
|
691
|
+
return _gather(config, *_claimed(config, task_id, block, designed, available))
|
|
692
|
+
if task_id is None:
|
|
693
|
+
chosen = pick(config, block, designed, available=available)
|
|
694
|
+
if chosen.entry is None:
|
|
695
|
+
raise NothingToBrief(
|
|
696
|
+
chosen.reason, chosen.held, chosen.standing, chosen.lacking
|
|
697
|
+
)
|
|
698
|
+
return _gather(config, chosen.entry.task.id, chosen, None)
|
|
699
|
+
return _gather(config, task_id, None, None)
|
|
700
|
+
|
|
701
|
+
|
|
702
|
+
def _claimed(
|
|
703
|
+
config: Config,
|
|
704
|
+
task_id: str | None,
|
|
705
|
+
block: str | None,
|
|
706
|
+
designed: bool,
|
|
707
|
+
available: Sequence[str] = (),
|
|
708
|
+
) -> tuple[str, Choice | None, Claim]:
|
|
709
|
+
"""Take a line, by the tiers or by the id the caller gave, and say which happened."""
|
|
710
|
+
if task_id is not None:
|
|
711
|
+
return task_id, None, hold(config, task_id)
|
|
712
|
+
taken = take(config, block, designed, available=available)
|
|
713
|
+
if taken.choice is None or taken.choice.entry is None:
|
|
714
|
+
# The same absence `pick` reports and not a refusal: a caller asking for work and
|
|
715
|
+
# being told there is none got the fact it asked for, and nothing was written.
|
|
716
|
+
held = () if taken.choice is None else taken.choice.held
|
|
717
|
+
raise NothingToBrief(
|
|
718
|
+
"" if taken.choice is None else taken.choice.reason,
|
|
719
|
+
held,
|
|
720
|
+
None if taken.choice is None else taken.choice.standing,
|
|
721
|
+
() if taken.choice is None else taken.choice.lacking,
|
|
722
|
+
)
|
|
723
|
+
return taken.choice.entry.task.id, taken.choice, taken
|
|
724
|
+
|
|
725
|
+
|
|
726
|
+
def _gather(
|
|
727
|
+
config: Config, task_id: str, chosen: Choice | None, claim: Claim | None
|
|
728
|
+
) -> Brief:
|
|
729
|
+
"""Every derived fact about one task, joined. This half reads and never writes."""
|
|
730
|
+
view = show(config, task_id)
|
|
731
|
+
backlog = Backlog.load(config)
|
|
732
|
+
graph = Graph.of(backlog)
|
|
733
|
+
entry = backlog.entry(task_id)
|
|
734
|
+
# A shipped task has no deps left to resolve: the ledger carries none, which is the
|
|
735
|
+
# schema saying a shipped line has no dependency to state. Its readiness is the ledger's
|
|
736
|
+
# own answer and not `ready` (RK324) — this is the command a session starts work with, so
|
|
737
|
+
# the one word it leads with is the one a caller acts on, and `show` already says shipped.
|
|
738
|
+
task = entry.task if entry is not None else view.task
|
|
739
|
+
readiness = backlog.readiness(task) if entry is not None else Readiness.SHIPPED
|
|
740
|
+
return Brief(
|
|
741
|
+
view=view,
|
|
742
|
+
readiness=readiness,
|
|
743
|
+
deps=backlog.resolve(task) if entry is not None else (),
|
|
744
|
+
chains=graph.chains(task_id)[:CHAINS] if entry is not None else (),
|
|
745
|
+
leverage=graph.leverage(task_id),
|
|
746
|
+
non_goals=non_goals(config, backlog.roadmap),
|
|
747
|
+
done_when=done_when(config, backlog.roadmap, task.block, task.id),
|
|
748
|
+
choice=chosen,
|
|
749
|
+
claim=claim,
|
|
750
|
+
settled=_settled(config, view, backlog.resolve(task) if entry is not None else ()),
|
|
751
|
+
budget=None if view.shipped else budget_of(config, task, open_line=True),
|
|
752
|
+
criterion=_criterion(config, view),
|
|
753
|
+
# A lookup this verb already performs (RK1226): the ledger is open because `shipping`
|
|
754
|
+
# is measured against it, so surfacing what has already landed costs nothing.
|
|
755
|
+
landed=_landed(backlog, task.id) if not view.shipped else (),
|
|
756
|
+
shipping=None
|
|
757
|
+
if view.shipped or not config.has("changelog")
|
|
758
|
+
else budget_of(
|
|
759
|
+
config,
|
|
760
|
+
# The task **as the ledger will hold it** and not as the roadmap holds it
|
|
761
|
+
# (RK1199): `ship` drops the deps and the pointer before it renders, so pricing
|
|
762
|
+
# the roadmap's task under the ledger's schema measured a structure ten
|
|
763
|
+
# characters wider than the line — an allowance with ten it could not spend, and
|
|
764
|
+
# a reader who trusted it and then watched `ship` accept more was told two things.
|
|
765
|
+
# Through `ship`'s own function, so the figure and the write cannot come apart.
|
|
766
|
+
#
|
|
767
|
+
# With the `why` **emptied** and not inherited (RK1365). `Share.left` subtracts what
|
|
768
|
+
# a field already holds, which is an `amend`'s question — and `ship --why` is
|
|
769
|
+
# required and *replaces* the roadmap's sentence, so the room for it is the whole
|
|
770
|
+
# allowance. Priced with that sentence still in the field, this read reported `37 of
|
|
771
|
+
# 200` against a ship that then accepted 145: a number four times under the real one
|
|
772
|
+
# fails in the direction that looks safe, and an advisory limit nobody believes still
|
|
773
|
+
# costs a line of every brief.
|
|
774
|
+
as_recorded(task, config.schema.shipped_marker, ""),
|
|
775
|
+
open_line=False,
|
|
776
|
+
schema=config.schema_for("changelog"),
|
|
777
|
+
),
|
|
778
|
+
# The third write the same ship may make (RK1275), priced the same way and under the
|
|
779
|
+
# role's own schema: `--decides` renders a decision the way `ship` renders an entry,
|
|
780
|
+
# so the figure comes through `as_recorded` for the reason the one above does — and with
|
|
781
|
+
# the `why` emptied for the reason that one is (RK1365), a `--decides` sentence being
|
|
782
|
+
# written from nothing exactly as the entry's is.
|
|
783
|
+
deciding=None
|
|
784
|
+
if view.shipped or not config.has("decisions")
|
|
785
|
+
else budget_of(
|
|
786
|
+
config,
|
|
787
|
+
as_recorded(task, config.schema_for("decisions").shipped_marker, ""),
|
|
788
|
+
open_line=False,
|
|
789
|
+
schema=config.schema_for("decisions"),
|
|
790
|
+
),
|
|
791
|
+
)
|
|
792
|
+
|
|
793
|
+
|
|
794
|
+
def non_goals(config: Config, document: Document) -> NonGoals:
|
|
795
|
+
"""The lead of each bullet under the non-goals heading, in file order and bounded.
|
|
796
|
+
|
|
797
|
+
The lead and not the bullet: what keeps a proposal inside scope is *that* the line
|
|
798
|
+
exists, and the sentence arguing it is already in the file the caller can open. *Which*
|
|
799
|
+
characters are the lead is `scoping`'s answer and not one guessed here (RK68) — the
|
|
800
|
+
module that writes a non-goal is the one that says what its address is.
|
|
801
|
+
|
|
802
|
+
Bounded twice, for the reason the chains stop at two and a section has a word budget:
|
|
803
|
+
each lead is cut to the project's own `[non_goals]` limit (L6) with the cut *shown*, and
|
|
804
|
+
a list past :data:`NON_GOALS` reports how many it left. A field with no limit at all is
|
|
805
|
+
a forty-bullet section arriving in place of the file this call exists to replace.
|
|
806
|
+
"""
|
|
807
|
+
limit = (config.non_goals or Scope()).lead
|
|
808
|
+
every = scoping.leads(document)
|
|
809
|
+
return NonGoals(
|
|
810
|
+
leads=tuple(
|
|
811
|
+
textwrap.shorten(lead, width=limit, placeholder=ELLIPSIS)
|
|
812
|
+
for lead in every[:NON_GOALS]
|
|
813
|
+
),
|
|
814
|
+
elided=max(0, len(every) - NON_GOALS),
|
|
815
|
+
)
|
|
816
|
+
|
|
817
|
+
|
|
818
|
+
|
|
819
|
+
def done_when(
|
|
820
|
+
config: Config, document: Document, block: str, task_id: str = ""
|
|
821
|
+
) -> DoneWhen:
|
|
822
|
+
"""What finishes this task and what finishes its block, in file order and bounded (RK1265).
|
|
823
|
+
|
|
824
|
+
:func:`non_goals`' shape one list over, and bounded for its reasons: each lead is cut to
|
|
825
|
+
the project's own `[criteria]` limit with the cut shown, and a list past :data:`NON_GOALS`
|
|
826
|
+
reports how many it left. *Which* characters are the lead is `criteria`'s answer and not
|
|
827
|
+
one guessed here — the module that writes a criterion says what its address is.
|
|
828
|
+
|
|
829
|
+
Scoped to the task's own block and never to the backlog: a criterion is about a body of
|
|
830
|
+
work, so printing another block's would be answering a question the caller did not ask
|
|
831
|
+
with a claim about somebody else's finish line. And to the task's own list beside it
|
|
832
|
+
(RK1268), which is the narrower version of exactly that argument: the line is the unit
|
|
833
|
+
being executed, so what would finish *it* is the answer a brief was opened for.
|
|
834
|
+
"""
|
|
835
|
+
limit = (config.criteria or Scope()).lead
|
|
836
|
+
|
|
837
|
+
def bounded(every: tuple[str, ...]) -> tuple[tuple[str, ...], int]:
|
|
838
|
+
return (
|
|
839
|
+
tuple(
|
|
840
|
+
textwrap.shorten(lead, width=limit, placeholder=ELLIPSIS)
|
|
841
|
+
for lead in every[:NON_GOALS]
|
|
842
|
+
),
|
|
843
|
+
max(0, len(every) - NON_GOALS),
|
|
844
|
+
)
|
|
845
|
+
|
|
846
|
+
leads, elided = bounded(criteria.leads(document, block))
|
|
847
|
+
own, own_elided = bounded(criteria.leads(document, task_id) if task_id else ())
|
|
848
|
+
return DoneWhen(leads=leads, elided=elided, own=own, own_elided=own_elided)
|
|
849
|
+
|
|
850
|
+
|
|
851
|
+
def _criterion(config: Config, view: View) -> tuple[tuple[Clause, int], ...]:
|
|
852
|
+
"""What this design says would prove the task done, counted now (RK1184, RK1185).
|
|
853
|
+
|
|
854
|
+
The clause and its count, never the sites: a brief is bounded to a tool result, and the
|
|
855
|
+
addresses are what `evidence` answers once the work is under way. **A criterion is read
|
|
856
|
+
at the start and not at the ship** — the order is the whole point, since a claim the work
|
|
857
|
+
will be measured against has to arrive before the first edit.
|
|
858
|
+
|
|
859
|
+
Silent on three shapes, all of which are answers rather than failures: a task with no
|
|
860
|
+
design, a design declaring no criterion, and a block this grammar cannot read. The last is
|
|
861
|
+
`lint`'s to report (RK1184) and refusing a brief over it would take away the call that
|
|
862
|
+
starts the work, on a fence the work has not touched yet.
|
|
863
|
+
"""
|
|
864
|
+
from roadkeep.remaining import EVIDENCE, QueryError, count, declared # noqa: PLC0415 - RK260
|
|
865
|
+
|
|
866
|
+
if view.section is None:
|
|
867
|
+
return ()
|
|
868
|
+
try:
|
|
869
|
+
clauses = declared(view.section.body, EVIDENCE)
|
|
870
|
+
except QueryError:
|
|
871
|
+
return ()
|
|
872
|
+
if not clauses:
|
|
873
|
+
return ()
|
|
874
|
+
# Per clause and not one total: two clauses at 3 and 0 are a criterion half met, and a
|
|
875
|
+
# single `3` says the same thing as both met — which is the shape RK10 is about, one
|
|
876
|
+
# module over. One `count` each rather than attributing a joined answer afterwards: a
|
|
877
|
+
# `Site` carries no clause, and giving it one to serve this reader would be a field on
|
|
878
|
+
# the record that only a caller's arithmetic wanted.
|
|
879
|
+
return tuple(
|
|
880
|
+
(clause, count(config.root, view.task.id, (clause,), EVIDENCE).total)
|
|
881
|
+
for clause in clauses
|
|
882
|
+
)
|
|
883
|
+
|
|
884
|
+
|
|
885
|
+
def _landed(backlog: Backlog, task_id: str) -> tuple[str, ...]:
|
|
886
|
+
"""Every qualifier the ledger records for this open id, in file order (RK1226).
|
|
887
|
+
|
|
888
|
+
**All of them and not the first.** Through this tool's own door there is at most one:
|
|
889
|
+
`SecondPartial` refuses a second `ship --part` on one id, because one id carries one
|
|
890
|
+
partial and then the completion. An **adopted** ledger is the other case, and it is the
|
|
891
|
+
one that decides the reader — Turing's holds 755 entries written before the tool existed,
|
|
892
|
+
and a history spelling two deliveries of one id is exactly what `adopt` takes in. `by_id`
|
|
893
|
+
answers the first entry per id by design (a duplicate is a lint error, not a merge), which
|
|
894
|
+
would name one of them and hide the other.
|
|
895
|
+
|
|
896
|
+
Silent where nothing landed, which is every ordinary line: a row saying *nothing has
|
|
897
|
+
shipped* on every brief is a nag this tool has no standing to make.
|
|
898
|
+
"""
|
|
899
|
+
if backlog.ledger is None:
|
|
900
|
+
return ()
|
|
901
|
+
return tuple(
|
|
902
|
+
entry.task.part
|
|
903
|
+
for entry in backlog.ledger.entries
|
|
904
|
+
if entry.task.id == task_id and entry.task.part
|
|
905
|
+
)
|
|
906
|
+
|
|
907
|
+
|
|
908
|
+
def _settled(config: Config, view: View, deps: tuple[Resolution, ...]) -> tuple[Settled, ...]:
|
|
909
|
+
"""Which shipped deps landed after this design was last written (RK1163).
|
|
910
|
+
|
|
911
|
+
Only the **shipped** ones, because an open dep has settled nothing and its date would be a
|
|
912
|
+
question about work in progress. Only where the task has a section: there is no design to
|
|
913
|
+
predate otherwise, and `brief` on a line whose prose is unwritten already says so.
|
|
914
|
+
|
|
915
|
+
Two git reads per shipped dep at most, on a command a session runs once to start a task —
|
|
916
|
+
and none at all for the common case of a task whose deps are open or absent. A failure to
|
|
917
|
+
read history is silence, never an error: `git_available` is the guard the rest of this
|
|
918
|
+
package uses and a note nobody can date is the guess L4 keeps out.
|
|
919
|
+
"""
|
|
920
|
+
if view.section is None or not deps:
|
|
921
|
+
return ()
|
|
922
|
+
# Deferred for RK260's reason: `history` runs git, and no successful write path reaches it.
|
|
923
|
+
from roadkeep.history import ( # noqa: PLC0415
|
|
924
|
+
HistoryUnavailable,
|
|
925
|
+
git_available,
|
|
926
|
+
origin_of,
|
|
927
|
+
precedes,
|
|
928
|
+
revisions_of,
|
|
929
|
+
)
|
|
930
|
+
|
|
931
|
+
if not git_available():
|
|
932
|
+
return ()
|
|
933
|
+
if view.section_role is None or not config.has(view.section_role):
|
|
934
|
+
return ()
|
|
935
|
+
prose = config.path(view.section_role)
|
|
936
|
+
if not prose.is_file():
|
|
937
|
+
return ()
|
|
938
|
+
# The section's **span** and never a needle for its heading: a heading appears in the diff of
|
|
939
|
+
# the commit that wrote it and of nothing else, so a body-only `section amend` — the ordinary
|
|
940
|
+
# way a design is revised — would be invisible and every design would read as unrevised since
|
|
941
|
+
# the day it was filed. RK1126 measured that asymmetry one verb over.
|
|
942
|
+
try:
|
|
943
|
+
written = revisions_of(config, prose, view.section.first, view.section.last)
|
|
944
|
+
except (HistoryUnavailable, OSError):
|
|
945
|
+
# A project git cannot answer for — no repository, a checkout too shallow — says
|
|
946
|
+
# nothing rather than raising: this is a note on a query, and `brief` is the command a
|
|
947
|
+
# session starts a task with.
|
|
948
|
+
return ()
|
|
949
|
+
if not written:
|
|
950
|
+
return ()
|
|
951
|
+
revised = written[-1]
|
|
952
|
+
out: list[Settled] = []
|
|
953
|
+
for one in deps:
|
|
954
|
+
if one.status is not DepStatus.SHIPPED:
|
|
955
|
+
continue
|
|
956
|
+
try:
|
|
957
|
+
shipped = origin_of(config, one.dep.id).shipped_in
|
|
958
|
+
except (HistoryUnavailable, OSError):
|
|
959
|
+
continue
|
|
960
|
+
# Ancestry and not dates (RK1163): two commits in one second carry the same timestamp,
|
|
961
|
+
# and a rebase can order dates against the history. `precedes` answers the question the
|
|
962
|
+
# note is about — was this design written before that ship landed — and a design revised
|
|
963
|
+
# *in* the shipping commit is excluded, having read what changed.
|
|
964
|
+
if (
|
|
965
|
+
shipped is not None
|
|
966
|
+
and revised.sha != shipped.sha
|
|
967
|
+
and precedes(config, revised.sha, shipped.sha)
|
|
968
|
+
):
|
|
969
|
+
out.append(Settled(dep=one.dep.id, shipped=shipped, revised=revised))
|
|
970
|
+
return tuple(out)
|