@tduyng/pi-devos 0.0.0-stage → 0.14.0
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.
- package/CHANGELOG.md +1421 -0
- package/LICENSE +201 -0
- package/README.md +206 -2
- package/package.json +44 -4
- package/plugins/devos/agents/reader.md +27 -0
- package/plugins/devos/agents/verifier.md +155 -0
- package/plugins/devos/pi/extension/devos.ts +605 -0
- package/plugins/devos/scripts/check-evidence-router.sh +140 -0
- package/plugins/devos/scripts/evidence-router.py +254 -0
- package/plugins/devos/scripts/gates/check-dod-core.sh +285 -0
- package/plugins/devos/scripts/gates/check-dod.sh +38 -0
- package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
- package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
- package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
- package/plugins/devos/scripts/gates/check-scenario-coverage.sh +104 -0
- package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
- package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
- package/plugins/devos/scripts/gates/plan-template-check.py +141 -0
- package/plugins/devos/scripts/gates/run-gate.sh +148 -0
- package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
- package/plugins/devos/scripts/gates/spec-template-check.py +152 -0
- package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
- package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
- package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
- package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
- package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
- package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
- package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
- package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
- package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
- package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
- package/plugins/devos/scripts/gates/test-gates.sh +76 -0
- package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
- package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
- package/plugins/devos/skills/absorb/SKILL.md +75 -0
- package/plugins/devos/skills/absorb/references/distill.md +67 -0
- package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
- package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
- package/plugins/devos/skills/build/SKILL.md +71 -0
- package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
- package/plugins/devos/skills/build/references/defect.md +17 -0
- package/plugins/devos/skills/build/references/exposure.md +28 -0
- package/plugins/devos/skills/build/references/hard.md +39 -0
- package/plugins/devos/skills/build/references/refactor.md +66 -0
- package/plugins/devos/skills/build/references/routes.md +56 -0
- package/plugins/devos/skills/build/references/scale.md +84 -0
- package/plugins/devos/skills/build/references/spike.md +19 -0
- package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
- package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
- package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
- package/plugins/devos/skills/build/scripts/route.sh +5 -0
- package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
- package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
- package/plugins/devos/skills/frame/SKILL.md +54 -0
- package/plugins/devos/skills/frame/references/template.md +115 -0
- package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
- package/plugins/devos/skills/implement/SKILL.md +36 -0
- package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
- package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
- package/plugins/devos/skills/implement/references/dod.md +37 -0
- package/plugins/devos/skills/implement/references/implement.md +54 -0
- package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
- package/plugins/devos/skills/implement/references/plan.md +142 -0
- package/plugins/devos/skills/implement/references/resume.md +9 -0
- package/plugins/devos/skills/implement/references/scale.md +86 -0
- package/plugins/devos/skills/implement/references/verify-close.md +62 -0
- package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
- package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
- package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
- package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
- package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
- package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
- package/plugins/devos/skills/implement/scripts/validate-spec.sh +220 -0
- package/plugins/devos/skills/init/SKILL.md +100 -0
- package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
- package/plugins/devos/skills/init/references/context.md +42 -0
- package/plugins/devos/skills/init/references/conventions-template.md +153 -0
- package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
- package/plugins/devos/skills/init/references/rule-format.md +58 -0
- package/plugins/devos/skills/init/references/shape-model.md +29 -0
- package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
- package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
- package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
- package/plugins/devos/skills/learn/SKILL.md +29 -0
- package/plugins/devos/skills/learn/references/destinations.md +43 -0
- package/plugins/devos/skills/learn/references/scoring.md +26 -0
- package/plugins/devos/skills/review/SKILL.md +54 -0
- package/plugins/devos/skills/review/references/comments.md +13 -0
- package/plugins/devos/skills/review/references/gaps.md +26 -0
- package/plugins/devos/skills/review/references/reviewer.md +124 -0
- package/plugins/devos/skills/review/references/routing.md +35 -0
- package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
- package/plugins/devos/skills/review/scripts/prepare.py +763 -0
- package/plugins/devos/skills/spec/SKILL.md +57 -0
- package/plugins/devos/skills/spec/references/prototype.md +21 -0
- package/plugins/devos/skills/spec/references/question-craft.md +47 -0
- package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
- package/plugins/devos/skills/spec/references/write-spec.md +128 -0
- package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
- package/plugins/devos/skills/status/SKILL.md +67 -0
- package/plugins/devos/skills/status/references/cost.md +38 -0
- package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
- package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
- package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
- package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
- package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
- package/plugins/devos/skills/status/scripts/quality-correlation.sh +259 -0
- package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
- package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
|
@@ -0,0 +1,556 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""check-requires: filesystem-derived spec dependency edges.
|
|
3
|
+
|
|
4
|
+
A port of check-requires.sh. Deterministic, zero model calls.
|
|
5
|
+
|
|
6
|
+
Usage:
|
|
7
|
+
check-requires.py [project-root] # blocked-by / blocks / CYCLE / BROKEN / SELF
|
|
8
|
+
check-requires.py --spec NAME [project-root]
|
|
9
|
+
check-requires.py --transitive [root] # BFS over all deps, full chain
|
|
10
|
+
check-requires.py --doctor [root] # BROKEN / CYCLE / SELF only (+ fix lines)
|
|
11
|
+
check-requires.py --verify SPEC_DIR [root] # INFO lines for unmet deps
|
|
12
|
+
check-requires.py --timeline CAPABILITY [root]
|
|
13
|
+
check-requires.py --concurrent [root] # which open specs can run together
|
|
14
|
+
|
|
15
|
+
--concurrent is the disjointness argument one level up, and is advisory only:
|
|
16
|
+
it names the groups, the human opens the worktrees. Nothing here dispatches,
|
|
17
|
+
schedules, or picks the next spec. Two specs are safe together when no
|
|
18
|
+
dependency path runs between them in either direction AND their planned file
|
|
19
|
+
sets are disjoint. A spec with no spec.md yet has no known file set, so it is
|
|
20
|
+
reported UNPLANNED and never grouped: "we cannot tell" and "it is safe" are
|
|
21
|
+
different answers, and only one of them is true.
|
|
22
|
+
|
|
23
|
+
Requires: line (optional):
|
|
24
|
+
Requires: [2026-01-01-auth, billing]
|
|
25
|
+
Name resolution: exact folder match, else unique suffix match (*-<name>).
|
|
26
|
+
Shipped = present under devos/specs/archive/. Absent line = no deps.
|
|
27
|
+
|
|
28
|
+
Why Python: the shell version held its graph in a newline-joined string,
|
|
29
|
+
popped the BFS frontier with `printf | head -1` and `sed 1d` (a fork per
|
|
30
|
+
node), and tracked the visited set with glob matching, because darwin ships
|
|
31
|
+
bash 3.2 and has no associative arrays. The cycle walk needed a `guard < 32`
|
|
32
|
+
backstop where a real visited set is just a set. Same output, same exit codes;
|
|
33
|
+
the graph is now indexed instead of rescanned.
|
|
34
|
+
"""
|
|
35
|
+
from __future__ import annotations
|
|
36
|
+
|
|
37
|
+
import re
|
|
38
|
+
import subprocess
|
|
39
|
+
import sys
|
|
40
|
+
from collections import deque
|
|
41
|
+
from pathlib import Path
|
|
42
|
+
|
|
43
|
+
# from|to|kind|token. kind is resolved | broken | ambiguous | self.
|
|
44
|
+
Edge = tuple[str, str, str, str]
|
|
45
|
+
|
|
46
|
+
REQUIRES_INLINE = re.compile(r"^Requires:", re.IGNORECASE)
|
|
47
|
+
HEADING = re.compile(r"^#{1,6}\s")
|
|
48
|
+
HEADING_REQUIRES = re.compile(r"^#{1,6}\s*Requires:", re.IGNORECASE)
|
|
49
|
+
BULLET = re.compile(r"^\s*-\s+")
|
|
50
|
+
LABEL = re.compile(r"^Requires:\s*", re.IGNORECASE)
|
|
51
|
+
FILES_LINE = re.compile(r"^\*\*Files:\*\*")
|
|
52
|
+
BACKTICK = re.compile(r"`([^`]*)`")
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
class Graph:
|
|
56
|
+
def __init__(self, root: Path) -> None:
|
|
57
|
+
self.root = root
|
|
58
|
+
self.specs = root / "devos" / "specs"
|
|
59
|
+
self.archive = self.specs / "archive"
|
|
60
|
+
self.edges: list[Edge] = []
|
|
61
|
+
self.known_names: list[str] = []
|
|
62
|
+
self._out: dict[str, list[Edge]] = {}
|
|
63
|
+
self._in: dict[str, list[Edge]] = {}
|
|
64
|
+
self._load_names()
|
|
65
|
+
|
|
66
|
+
# ---- name resolution -------------------------------------------------
|
|
67
|
+
|
|
68
|
+
def _load_names(self) -> None:
|
|
69
|
+
if not self.specs.is_dir():
|
|
70
|
+
return
|
|
71
|
+
names: list[str] = []
|
|
72
|
+
for base in (self.specs, self.archive):
|
|
73
|
+
if base.is_dir():
|
|
74
|
+
names += sorted(d.name for d in base.iterdir() if d.is_dir())
|
|
75
|
+
# The shell globbed specs/*/ then archive/*/, and skipped the "archive"
|
|
76
|
+
# entry that specs/*/ itself contributes. Mirror that order exactly:
|
|
77
|
+
# active specs first, then archived, archive's own name removed.
|
|
78
|
+
seen: set[str] = set()
|
|
79
|
+
ordered: list[str] = []
|
|
80
|
+
for group in (
|
|
81
|
+
sorted(d.name for d in self.specs.iterdir() if d.is_dir()) if self.specs.is_dir() else [],
|
|
82
|
+
sorted(d.name for d in self.archive.iterdir() if d.is_dir()) if self.archive.is_dir() else [],
|
|
83
|
+
):
|
|
84
|
+
for n in group:
|
|
85
|
+
if n != "archive" and n not in seen:
|
|
86
|
+
seen.add(n)
|
|
87
|
+
ordered.append(n)
|
|
88
|
+
self.known_names = ordered
|
|
89
|
+
|
|
90
|
+
def is_archived(self, name: str) -> bool:
|
|
91
|
+
return (self.archive / name).is_dir() and not (self.specs / name).is_dir()
|
|
92
|
+
|
|
93
|
+
def exists_anywhere(self, name: str) -> bool:
|
|
94
|
+
return (self.specs / name).is_dir() or (self.archive / name).is_dir()
|
|
95
|
+
|
|
96
|
+
def resolve_dep(self, token: str) -> tuple[str, list[str]]:
|
|
97
|
+
"""Return (resolved_or_empty, candidates). Ambiguity is not an error."""
|
|
98
|
+
t = re.sub(r"^[\s]+", "", token)
|
|
99
|
+
t = re.sub(r"[\s]+$", "", t)
|
|
100
|
+
t = re.sub(r"^\[", "", t)
|
|
101
|
+
t = re.sub(r"\]$", "", t)
|
|
102
|
+
t = re.sub(r",$", "", t)
|
|
103
|
+
if not t:
|
|
104
|
+
return "", []
|
|
105
|
+
if self.exists_anywhere(t):
|
|
106
|
+
return t, []
|
|
107
|
+
matches = [n for n in self.known_names if n.endswith("-" + t) or n == t]
|
|
108
|
+
if len(matches) == 1:
|
|
109
|
+
return matches[0], matches
|
|
110
|
+
return "", matches
|
|
111
|
+
|
|
112
|
+
# ---- edge collection -------------------------------------------------
|
|
113
|
+
|
|
114
|
+
def parse_requires(self, spec_file: Path) -> list[str]:
|
|
115
|
+
"""One Requires: token per line from a spec.md."""
|
|
116
|
+
if not spec_file.is_file():
|
|
117
|
+
return []
|
|
118
|
+
text = spec_file.read_text(errors="replace")
|
|
119
|
+
line = ""
|
|
120
|
+
for ln in text.splitlines():
|
|
121
|
+
if REQUIRES_INLINE.match(ln):
|
|
122
|
+
line = ln
|
|
123
|
+
break
|
|
124
|
+
if not line:
|
|
125
|
+
# `### Requires:` heading then `- name` bullets, which is what specs
|
|
126
|
+
# write in practice. Any heading ends the section; requiring a
|
|
127
|
+
# letter after the hashes matched only unnumbered subheadings, so
|
|
128
|
+
# the canonical skeleton's `## 5. Out of Scope` never closed the
|
|
129
|
+
# list and `- none` was read as a dependency named "none".
|
|
130
|
+
on = False
|
|
131
|
+
parts: list[str] = []
|
|
132
|
+
for ln in text.splitlines():
|
|
133
|
+
if HEADING_REQUIRES.match(ln):
|
|
134
|
+
on = True
|
|
135
|
+
continue
|
|
136
|
+
if HEADING.match(ln):
|
|
137
|
+
on = False
|
|
138
|
+
continue
|
|
139
|
+
if on and BULLET.match(ln):
|
|
140
|
+
parts.append(BULLET.sub("", ln, count=1))
|
|
141
|
+
line = ",".join(parts)
|
|
142
|
+
if not line:
|
|
143
|
+
return []
|
|
144
|
+
line = LABEL.sub("", line, count=1)
|
|
145
|
+
if line.startswith("["):
|
|
146
|
+
line = line[1:]
|
|
147
|
+
line = re.sub(r"\]\s*$", "", line)
|
|
148
|
+
out = []
|
|
149
|
+
for tok in line.split(","):
|
|
150
|
+
tok = tok.strip()
|
|
151
|
+
if tok:
|
|
152
|
+
out.append(tok)
|
|
153
|
+
return out
|
|
154
|
+
|
|
155
|
+
def add_edge(self, e: Edge) -> None:
|
|
156
|
+
self.edges.append(e)
|
|
157
|
+
self._out.setdefault(e[0], []).append(e)
|
|
158
|
+
self._in.setdefault(e[1], []).append(e)
|
|
159
|
+
|
|
160
|
+
def collect_edges_for(self, folder: Path) -> None:
|
|
161
|
+
name = folder.name
|
|
162
|
+
sf = folder / "spec.md"
|
|
163
|
+
if not sf.is_file():
|
|
164
|
+
return
|
|
165
|
+
for tok in self.parse_requires(sf):
|
|
166
|
+
resolved, matches = self.resolve_dep(tok)
|
|
167
|
+
if resolved:
|
|
168
|
+
kind = "self" if resolved == name else "resolved"
|
|
169
|
+
self.add_edge((name, resolved, kind, tok))
|
|
170
|
+
elif matches:
|
|
171
|
+
self.add_edge((name, " ".join(matches), "ambiguous", tok))
|
|
172
|
+
else:
|
|
173
|
+
self.add_edge((name, "", "broken", tok))
|
|
174
|
+
|
|
175
|
+
def collect_all(self, spec_filter: str, mode: str) -> None:
|
|
176
|
+
if not self.specs.is_dir():
|
|
177
|
+
return
|
|
178
|
+
for d in sorted(p for p in self.specs.iterdir() if p.is_dir()):
|
|
179
|
+
base = d.name
|
|
180
|
+
if base == "archive":
|
|
181
|
+
continue
|
|
182
|
+
# Cycle detection needs the complete graph. Keep collection
|
|
183
|
+
# unfiltered for status, including --spec, and apply the filter to
|
|
184
|
+
# status rows and emitted cycles below.
|
|
185
|
+
if spec_filter and mode != "status" and base != spec_filter:
|
|
186
|
+
continue
|
|
187
|
+
self.collect_edges_for(d)
|
|
188
|
+
|
|
189
|
+
# ---- graph queries ----------------------------------------------------
|
|
190
|
+
|
|
191
|
+
def has_path(self, start: str, goal: str) -> bool:
|
|
192
|
+
"""True if a directed path runs start -> goal over resolved edges."""
|
|
193
|
+
if start == goal:
|
|
194
|
+
return False
|
|
195
|
+
seen = {start}
|
|
196
|
+
queue = deque([start])
|
|
197
|
+
while queue:
|
|
198
|
+
node = queue.popleft()
|
|
199
|
+
for _frm, to, kind, _tok in self._out.get(node, ()):
|
|
200
|
+
if kind != "resolved" or to in seen:
|
|
201
|
+
continue
|
|
202
|
+
if to == goal:
|
|
203
|
+
return True
|
|
204
|
+
seen.add(to)
|
|
205
|
+
queue.append(to)
|
|
206
|
+
return False
|
|
207
|
+
|
|
208
|
+
def blocked_by_of(self, name: str) -> str:
|
|
209
|
+
return ",".join(
|
|
210
|
+
to for _f, to, kind, _t in self._out.get(name, ())
|
|
211
|
+
if kind == "resolved" and not self.is_archived(to)
|
|
212
|
+
)
|
|
213
|
+
|
|
214
|
+
def blocks_of(self, name: str) -> str:
|
|
215
|
+
return ",".join(
|
|
216
|
+
frm for frm, _to, kind, _t in self._in.get(name, ())
|
|
217
|
+
if kind == "resolved" and not self.is_archived(_to)
|
|
218
|
+
)
|
|
219
|
+
|
|
220
|
+
def status_names(self) -> list[str]:
|
|
221
|
+
names: list[str] = []
|
|
222
|
+
seen: set[str] = set()
|
|
223
|
+
for frm, to, kind, _tok in self.edges:
|
|
224
|
+
if frm not in seen:
|
|
225
|
+
seen.add(frm)
|
|
226
|
+
names.append(frm)
|
|
227
|
+
if kind == "resolved" and to not in seen:
|
|
228
|
+
seen.add(to)
|
|
229
|
+
names.append(to)
|
|
230
|
+
return names
|
|
231
|
+
|
|
232
|
+
def emit_cycles(self, cycle_filter: str = "") -> "list[str]":
|
|
233
|
+
out: list[str] = []
|
|
234
|
+
emitted: set[str] = set()
|
|
235
|
+
for frm, to, kind, _tok in self.edges:
|
|
236
|
+
if kind != "resolved":
|
|
237
|
+
continue
|
|
238
|
+
if not self.has_path(to, frm):
|
|
239
|
+
continue
|
|
240
|
+
# Walk from `to` back to `from`, recording the path. The shell took
|
|
241
|
+
# the first neighbour that still reaches `from`; a `visited` set is
|
|
242
|
+
# what makes that terminate, so no guard counter is needed.
|
|
243
|
+
path = [frm, to]
|
|
244
|
+
cur = to
|
|
245
|
+
seen = {frm, to}
|
|
246
|
+
while cur != frm:
|
|
247
|
+
nxt = None
|
|
248
|
+
for _f, t, k, _tk in self._out.get(cur, ()):
|
|
249
|
+
if k != "resolved" or t in seen:
|
|
250
|
+
continue
|
|
251
|
+
if t == frm or self.has_path(t, frm):
|
|
252
|
+
nxt = t
|
|
253
|
+
break
|
|
254
|
+
if nxt is None:
|
|
255
|
+
break
|
|
256
|
+
path.append(nxt)
|
|
257
|
+
seen.add(nxt)
|
|
258
|
+
cur = nxt
|
|
259
|
+
if cur != frm:
|
|
260
|
+
path.append(frm)
|
|
261
|
+
display = " -> ".join(path)
|
|
262
|
+
if cycle_filter and cycle_filter not in path:
|
|
263
|
+
continue
|
|
264
|
+
key = ",".join(sorted(set(path)))
|
|
265
|
+
if key in emitted:
|
|
266
|
+
continue
|
|
267
|
+
emitted.add(key)
|
|
268
|
+
out.append(f"CYCLE {display}")
|
|
269
|
+
return out
|
|
270
|
+
|
|
271
|
+
# ---- emitters ---------------------------------------------------------
|
|
272
|
+
|
|
273
|
+
def emit_status_for(self, name: str) -> list[str]:
|
|
274
|
+
out: list[str] = []
|
|
275
|
+
bb = self.blocked_by_of(name)
|
|
276
|
+
bl = self.blocks_of(name)
|
|
277
|
+
parts: list[str] = []
|
|
278
|
+
if bb:
|
|
279
|
+
parts.append(f"blocked-by: {bb}")
|
|
280
|
+
if bl:
|
|
281
|
+
parts.append(f"blocks: {bl}")
|
|
282
|
+
if parts:
|
|
283
|
+
out.append(f"{name} {' '.join(parts)}")
|
|
284
|
+
for frm, to, kind, token in self._out.get(name, ()):
|
|
285
|
+
if kind == "self":
|
|
286
|
+
out.append(f"SELF {name} Requires itself")
|
|
287
|
+
elif kind == "broken":
|
|
288
|
+
out.append(f"BROKEN {name} Requires: {token} (no folder under specs/ or archive/)")
|
|
289
|
+
elif kind == "ambiguous":
|
|
290
|
+
out.append(
|
|
291
|
+
f"AMBIGUOUS {name} Requires: {token} matches {to.replace(' ', ', ')} "
|
|
292
|
+
f"(short suffix is not unique)"
|
|
293
|
+
)
|
|
294
|
+
return out
|
|
295
|
+
|
|
296
|
+
def files_of(self, name: str) -> list[str] | None:
|
|
297
|
+
plan = self.specs / name / "spec.md"
|
|
298
|
+
if not plan.is_file():
|
|
299
|
+
return None
|
|
300
|
+
found: set[str] = set()
|
|
301
|
+
for ln in plan.read_text(errors="replace").splitlines():
|
|
302
|
+
if FILES_LINE.match(ln.strip()):
|
|
303
|
+
found.update(m for m in BACKTICK.findall(ln) if m)
|
|
304
|
+
return sorted(found)
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
def path_lists_overlap(fa: list[str], fb: list[str]) -> str | None:
|
|
308
|
+
for left in fa:
|
|
309
|
+
left = left.removeprefix("./").rstrip("/")
|
|
310
|
+
if not left:
|
|
311
|
+
continue
|
|
312
|
+
for right in fb:
|
|
313
|
+
right = right.removeprefix("./").rstrip("/")
|
|
314
|
+
if not right:
|
|
315
|
+
continue
|
|
316
|
+
if right == left or right.startswith(left + "/") or left.startswith(right + "/"):
|
|
317
|
+
return left
|
|
318
|
+
return None
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
def pair_verdict(g: Graph, a: str, b: str) -> str:
|
|
322
|
+
if g.has_path(a, b) or g.has_path(b, a):
|
|
323
|
+
return "depends"
|
|
324
|
+
fa = g.files_of(a)
|
|
325
|
+
if fa is None:
|
|
326
|
+
return f"unplanned:{a}"
|
|
327
|
+
fb = g.files_of(b)
|
|
328
|
+
if fb is None:
|
|
329
|
+
return f"unplanned:{b}"
|
|
330
|
+
if not fa or not fb:
|
|
331
|
+
return f"unplanned:{a if not fa else b}"
|
|
332
|
+
ov = path_lists_overlap(fa, fb)
|
|
333
|
+
return f"overlap:{ov}" if ov else "safe"
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def emit_concurrent(g: Graph) -> list[str]:
|
|
337
|
+
out: list[str] = []
|
|
338
|
+
# Open = has a functional spec, not yet verified, not archived. A spec that
|
|
339
|
+
# reached verification is finishing, not starting, so grouping it would
|
|
340
|
+
# advertise capacity that does not exist.
|
|
341
|
+
open_specs: list[str] = []
|
|
342
|
+
if g.specs.is_dir():
|
|
343
|
+
for d in sorted(p for p in g.specs.iterdir() if p.is_dir()):
|
|
344
|
+
if d.name == "archive" or not (d / "spec.md").is_file():
|
|
345
|
+
continue
|
|
346
|
+
if (d / "verifications" / "verification.md").is_file():
|
|
347
|
+
continue
|
|
348
|
+
open_specs.append(d.name)
|
|
349
|
+
if len(open_specs) < 2:
|
|
350
|
+
return [f"CONCURRENT {len(open_specs)} open spec(s): nothing to run in parallel"]
|
|
351
|
+
|
|
352
|
+
# Greedy grouping: first group where the spec is pairwise-safe with every
|
|
353
|
+
# member. Deterministic on sorted names. Not a maximum clique, and it does
|
|
354
|
+
# not need to be: an advisory grouping that is correct and slightly
|
|
355
|
+
# conservative beats an optimal one nobody can check by hand.
|
|
356
|
+
groups: list[list[str]] = []
|
|
357
|
+
unplanned: list[str] = []
|
|
358
|
+
for s in open_specs:
|
|
359
|
+
fs = g.files_of(s)
|
|
360
|
+
if not fs:
|
|
361
|
+
unplanned.append(s)
|
|
362
|
+
continue
|
|
363
|
+
placed = False
|
|
364
|
+
for grp in groups:
|
|
365
|
+
if all(pair_verdict(g, s, m) == "safe" for m in grp):
|
|
366
|
+
grp.append(s)
|
|
367
|
+
placed = True
|
|
368
|
+
break
|
|
369
|
+
if not placed:
|
|
370
|
+
groups.append([s])
|
|
371
|
+
|
|
372
|
+
for i, grp in enumerate(groups, 1):
|
|
373
|
+
label = "CONCURRENT" if len(grp) > 1 else "SEQUENTIAL"
|
|
374
|
+
out.append(f"{label} group {i}: {' '.join(grp)}")
|
|
375
|
+
for u in unplanned:
|
|
376
|
+
out.append(
|
|
377
|
+
f"UNPLANNED {u} has no spec.md file list yet, not grouped "
|
|
378
|
+
f"(run /devos:implement to plan it)"
|
|
379
|
+
)
|
|
380
|
+
# Why each cross-pair is separated. This is the part a human acts on.
|
|
381
|
+
for a in open_specs:
|
|
382
|
+
for b in open_specs:
|
|
383
|
+
if a >= b:
|
|
384
|
+
continue
|
|
385
|
+
v = pair_verdict(g, a, b)
|
|
386
|
+
if v == "depends":
|
|
387
|
+
out.append(f"BLOCKED {a} + {b}: a dependency path runs between them")
|
|
388
|
+
elif v.startswith("overlap:"):
|
|
389
|
+
out.append(f"OVERLAP {a} + {b}: both plan to touch {v[len('overlap:'):]}")
|
|
390
|
+
out += [
|
|
391
|
+
"",
|
|
392
|
+
"Advisory. Each group is a set you may run at the same time, one spec",
|
|
393
|
+
"per branch and worktree. Opening them, and merging them back, is yours.",
|
|
394
|
+
]
|
|
395
|
+
return out
|
|
396
|
+
|
|
397
|
+
|
|
398
|
+
def emit_transitive(g: Graph) -> list[str]:
|
|
399
|
+
out = ["# Transitive Dependencies", ""]
|
|
400
|
+
for frm, to, kind, _tok in g.edges:
|
|
401
|
+
if kind != "resolved":
|
|
402
|
+
continue
|
|
403
|
+
chain = [to]
|
|
404
|
+
watched = {frm, to}
|
|
405
|
+
queue = deque([to])
|
|
406
|
+
while queue:
|
|
407
|
+
nxt = queue.popleft()
|
|
408
|
+
for _f, t, k, _tk in g._out.get(nxt, ()):
|
|
409
|
+
if k != "resolved" or t in watched:
|
|
410
|
+
continue
|
|
411
|
+
chain.append(t)
|
|
412
|
+
watched.add(t)
|
|
413
|
+
queue.append(t)
|
|
414
|
+
out.append(f"{frm} -> {' -> '.join(chain)}")
|
|
415
|
+
return out
|
|
416
|
+
|
|
417
|
+
|
|
418
|
+
def emit_timeline(g: Graph, capability: str) -> tuple[list[str] | None, int]:
|
|
419
|
+
# Reject separators before lookup so traversal cannot read outside the
|
|
420
|
+
# behavior set. This one goes to stderr: it is a bad argument, not a
|
|
421
|
+
# finding, and the shell version said so on stderr too.
|
|
422
|
+
if "/" in capability or "\\" in capability:
|
|
423
|
+
return None, 2
|
|
424
|
+
cap_file = g.root / "devos" / "product" / "behaviors" / f"{capability}.md"
|
|
425
|
+
if not cap_file.is_file():
|
|
426
|
+
return [f"No behavior file found for capability: {capability}"], 1
|
|
427
|
+
out = [f"# Timeline: {capability}", "", f"Source: {cap_file}", ""]
|
|
428
|
+
# --diff-filter=M excluded the commit that CREATED the file, which is an A.
|
|
429
|
+
# Behavior files are created on first touch and most have only that one
|
|
430
|
+
# commit, so the old filter returned nothing for nearly every capability.
|
|
431
|
+
# Test the output, not the exit code: git log exits 0 when it prints
|
|
432
|
+
# nothing, so the `|| echo` fallback it used to carry never fired.
|
|
433
|
+
r = subprocess.run(
|
|
434
|
+
["git", "-C", str(g.root), "log", "-p", "--follow", "--date=short",
|
|
435
|
+
"--format=%n=== %ad %h %s", "--", str(cap_file)],
|
|
436
|
+
capture_output=True, text=True,
|
|
437
|
+
)
|
|
438
|
+
history = r.stdout
|
|
439
|
+
out.append("(no git history for this file yet)" if not history else history.rstrip("\n"))
|
|
440
|
+
return out, 0
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
def main(argv: list[str]) -> int:
|
|
444
|
+
mode = "status"
|
|
445
|
+
spec_filter = ""
|
|
446
|
+
verify_dir = ""
|
|
447
|
+
capability = ""
|
|
448
|
+
project_root = ""
|
|
449
|
+
|
|
450
|
+
i = 0
|
|
451
|
+
while i < len(argv):
|
|
452
|
+
a = argv[i]
|
|
453
|
+
if a == "--doctor":
|
|
454
|
+
mode = "doctor"
|
|
455
|
+
elif a == "--concurrent":
|
|
456
|
+
mode = "concurrent"
|
|
457
|
+
elif a == "--transitive":
|
|
458
|
+
mode = "transitive"
|
|
459
|
+
elif a == "--timeline":
|
|
460
|
+
mode = "timeline"
|
|
461
|
+
capability = argv[i + 1] if i + 1 < len(argv) else ""
|
|
462
|
+
if not capability:
|
|
463
|
+
print(f"Usage: {sys.argv[0]} --timeline CAPABILITY [project-root]", file=sys.stderr)
|
|
464
|
+
return 2
|
|
465
|
+
i += 1
|
|
466
|
+
elif a == "--verify":
|
|
467
|
+
mode = "verify"
|
|
468
|
+
verify_dir = argv[i + 1] if i + 1 < len(argv) else ""
|
|
469
|
+
if not verify_dir:
|
|
470
|
+
print(f"Usage: {sys.argv[0]} --verify SPEC_DIR [project-root]", file=sys.stderr)
|
|
471
|
+
return 2
|
|
472
|
+
i += 1
|
|
473
|
+
elif a == "--spec":
|
|
474
|
+
spec_filter = argv[i + 1] if i + 1 < len(argv) else ""
|
|
475
|
+
if not spec_filter:
|
|
476
|
+
print(f"Usage: {sys.argv[0]} --spec NAME [project-root]", file=sys.stderr)
|
|
477
|
+
return 2
|
|
478
|
+
i += 1
|
|
479
|
+
elif a.startswith("-"):
|
|
480
|
+
print(f"Unknown option: {a}", file=sys.stderr)
|
|
481
|
+
return 2
|
|
482
|
+
else:
|
|
483
|
+
project_root = a
|
|
484
|
+
i += 1
|
|
485
|
+
|
|
486
|
+
root = Path(project_root or ".").resolve()
|
|
487
|
+
g = Graph(root)
|
|
488
|
+
|
|
489
|
+
if mode == "verify":
|
|
490
|
+
vdir = Path(verify_dir)
|
|
491
|
+
if not vdir.is_absolute():
|
|
492
|
+
vdir = root / verify_dir
|
|
493
|
+
if not vdir.is_dir():
|
|
494
|
+
print(f"FAIL check-requires: spec directory not found: {verify_dir}", file=sys.stderr)
|
|
495
|
+
return 2
|
|
496
|
+
g.collect_edges_for(vdir)
|
|
497
|
+
else:
|
|
498
|
+
g.collect_all(spec_filter, mode)
|
|
499
|
+
|
|
500
|
+
out: list[str] = []
|
|
501
|
+
if mode == "status":
|
|
502
|
+
for n in g.status_names():
|
|
503
|
+
if spec_filter and n != spec_filter:
|
|
504
|
+
continue
|
|
505
|
+
out += g.emit_status_for(n)
|
|
506
|
+
out += g.emit_cycles(spec_filter)
|
|
507
|
+
elif mode == "doctor":
|
|
508
|
+
for frm, to, kind, token in g.edges:
|
|
509
|
+
if kind == "broken":
|
|
510
|
+
out.append(f"BROKEN Requires: {token} in {frm} (no folder under specs/ or archive/)")
|
|
511
|
+
out.append(" fix: correct the name, or create/archive the required spec folder")
|
|
512
|
+
elif kind == "ambiguous":
|
|
513
|
+
out.append(
|
|
514
|
+
f"AMBIGUOUS Requires: {token} in {frm} matches {to.replace(' ', ', ')} "
|
|
515
|
+
f"(short suffix is not unique)"
|
|
516
|
+
)
|
|
517
|
+
out.append(" fix: use the full YYYY-MM-DD-name of one of them in the Requires: line")
|
|
518
|
+
elif kind == "self":
|
|
519
|
+
out.append(f"BROKEN Requires: {frm} Requires itself")
|
|
520
|
+
out.append(" fix: remove the self-edge from spec.md")
|
|
521
|
+
for cline in g.emit_cycles():
|
|
522
|
+
out.append(cline)
|
|
523
|
+
out.append(" fix: break the cycle in one of the Requires: lines")
|
|
524
|
+
elif mode == "verify":
|
|
525
|
+
for _frm, to, kind, token in g.edges:
|
|
526
|
+
if kind == "broken":
|
|
527
|
+
out.append(f"INFO depends on '{token}', unknown target (broken edge)")
|
|
528
|
+
elif kind == "ambiguous":
|
|
529
|
+
out.append(f"INFO depends on '{token}', AMBIGUOUS short suffix matching {to.replace(' ', ', ')}")
|
|
530
|
+
elif kind == "self":
|
|
531
|
+
out.append("INFO depends on itself (self-edge)")
|
|
532
|
+
elif kind == "resolved" and not g.is_archived(to):
|
|
533
|
+
out.append(f"INFO depends on {to}, not yet shipped")
|
|
534
|
+
elif mode == "transitive":
|
|
535
|
+
out = emit_transitive(g)
|
|
536
|
+
elif mode == "concurrent":
|
|
537
|
+
out = emit_concurrent(g)
|
|
538
|
+
elif mode == "timeline":
|
|
539
|
+
out, code = emit_timeline(g, capability)
|
|
540
|
+
if out is None:
|
|
541
|
+
print("capability must be a single name without path separators", file=sys.stderr)
|
|
542
|
+
return code
|
|
543
|
+
if out:
|
|
544
|
+
print("\n".join(out))
|
|
545
|
+
return code
|
|
546
|
+
|
|
547
|
+
# An empty result is zero output, not one blank line: the shell version
|
|
548
|
+
# printed nothing when a filter matched no spec, and a caller parsing this
|
|
549
|
+
# output must not see a phantom line.
|
|
550
|
+
if out:
|
|
551
|
+
print("\n".join(out))
|
|
552
|
+
return 0
|
|
553
|
+
|
|
554
|
+
|
|
555
|
+
if __name__ == "__main__":
|
|
556
|
+
sys.exit(main(sys.argv[1:]))
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# context-cost.sh: what the plugin costs in context, measured rather than
|
|
3
|
+
# estimated.
|
|
4
|
+
#
|
|
5
|
+
# Three numbers, because one number hides what it counts:
|
|
6
|
+
# - the descriptions of the always-on rules, the part every harness loads
|
|
7
|
+
# - the catalog a harness renders at startup: names, descriptions, paths, wrapper
|
|
8
|
+
# - the tool the pi extension registers, whose description and schema load too
|
|
9
|
+
#
|
|
10
|
+
# The catalog is rendered the way pi renders it, as name, description, location
|
|
11
|
+
# and XML wrapper plus the harness's own intro paragraph, against pi 1.5.0's
|
|
12
|
+
# formatSkillsForPrompt. Another harness renders the same skills its own way,
|
|
13
|
+
# so its number moves and this one does not.
|
|
14
|
+
#
|
|
15
|
+
# Token estimate = bytes / 4, the same method evals/skill-cost-baseline.tsv
|
|
16
|
+
# uses, so the numbers here and the ratchet in evals/lint-skills.sh agree by
|
|
17
|
+
# construction.
|
|
18
|
+
#
|
|
19
|
+
# One awk pass over every SKILL.md, not a shell loop spawning wc/grep/awk per
|
|
20
|
+
# skill: check-claims.py calls this on every `just verify`, and test-gates.sh
|
|
21
|
+
# calls it seven more times through the fixture path. LC_ALL=C so length()
|
|
22
|
+
# counts bytes like `wc -c` did, not characters (these files contain →, ✅).
|
|
23
|
+
set -u
|
|
24
|
+
PLUGIN_ROOT="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)}"
|
|
25
|
+
# Resolved to an absolute path: the harness prints the skill's absolute
|
|
26
|
+
# location, and a relative path here would understate the catalog.
|
|
27
|
+
PLUGIN_ROOT="$(cd "$PLUGIN_ROOT" && pwd)"
|
|
28
|
+
echo "| Skill | Invocation | SKILL.md tokens (on invoke) | Description tokens (every session) |"
|
|
29
|
+
echo "|---|---|---|---|"
|
|
30
|
+
|
|
31
|
+
LC_ALL=C awk '
|
|
32
|
+
FNR == 1 {
|
|
33
|
+
if (name != "") emit()
|
|
34
|
+
path = FILENAME
|
|
35
|
+
sub(/\/SKILL\.md$/, "", path)
|
|
36
|
+
sub(/^.*\//, "", path)
|
|
37
|
+
name = path
|
|
38
|
+
loc = FILENAME
|
|
39
|
+
bytes = 0; user_invoked = 0; desc = ""; fm_name = ""; in_fm = 0
|
|
40
|
+
}
|
|
41
|
+
{ bytes += length($0) + 1 }
|
|
42
|
+
/^---$/ { in_fm = !in_fm; next }
|
|
43
|
+
in_fm && /^name:/ && fm_name == "" {
|
|
44
|
+
line = $0; sub(/^name:[[:space:]]*/, "", line); gsub(/^"|"$/, "", line); fm_name = line
|
|
45
|
+
}
|
|
46
|
+
in_fm && /^description:/ && desc == "" {
|
|
47
|
+
line = $0; sub(/^description:[[:space:]]*/, "", line); gsub(/^"|"$/, "", line)
|
|
48
|
+
desc = line
|
|
49
|
+
}
|
|
50
|
+
in_fm && /^disable-model-invocation:[[:space:]]*true/ { user_invoked = 1 }
|
|
51
|
+
|
|
52
|
+
# The harness escapes the XML it prints, so the escaped form is what lands in
|
|
53
|
+
# the context window.
|
|
54
|
+
function xesc(s) {
|
|
55
|
+
gsub(/&/, "\\&", s)
|
|
56
|
+
gsub(/</, "\\<", s)
|
|
57
|
+
gsub(/>/, "\\>", s)
|
|
58
|
+
gsub(/"/, "\\"", s)
|
|
59
|
+
gsub(/'"'"'/, "\\'", s)
|
|
60
|
+
return s
|
|
61
|
+
}
|
|
62
|
+
function emit( body, d) {
|
|
63
|
+
body = int(bytes / 4)
|
|
64
|
+
if (user_invoked) {
|
|
65
|
+
printf "| %s | user-invoked | %d | 0 |\n", name, body
|
|
66
|
+
} else {
|
|
67
|
+
# The description of a model-invoked skill sits in context every
|
|
68
|
+
# session, in every harness. The name, the path and the wrapper are
|
|
69
|
+
# the harness rendering of the same skill, counted separately below.
|
|
70
|
+
d = int(length(desc) / 4)
|
|
71
|
+
desc_total += d
|
|
72
|
+
cat = cat "\n <skill>\n <name>" xesc(fm_name == "" ? name : fm_name) "</name>\n <description>" xesc(desc) "</description>\n <location>" xesc(loc) "</location>\n </skill>"
|
|
73
|
+
cat_skills++
|
|
74
|
+
printf "| %s | model-invoked | %d | ~%d |\n", name, body, d
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
END {
|
|
78
|
+
if (name != "") emit()
|
|
79
|
+
# pi 1.3.0, formatSkillsForPrompt: the intro paragraph, the catalog, and
|
|
80
|
+
# the closing tag, joined with newlines exactly as that function does.
|
|
81
|
+
intro = "\n\nThe following skills provide specialized instructions for specific tasks.\nUse the read tool to load a skill'"'"'s file when the task matches its description.\nResolve relative paths against the skill'"'"'s directory (parent of SKILL.md). Use absolute paths in tool calls.\n\n<available_skills>"
|
|
82
|
+
catalog = intro cat "\n</available_skills>"
|
|
83
|
+
catalog_bytes = length(catalog)
|
|
84
|
+
printf "\nAlways-loaded total (pi session block: the skill catalog the harness renders at startup): ~%d tokens per session.\n", int(catalog_bytes / 4)
|
|
85
|
+
printf " skill catalog: ~%d tokens (%d advertised skills, with their names, descriptions, paths, the wrapper and the harness intro)\n", int(catalog_bytes / 4), cat_skills
|
|
86
|
+
printf " of which the descriptions: ~%d tokens, the part every harness loads\n", desc_total
|
|
87
|
+
print "Everything else loads only when its command is typed."
|
|
88
|
+
}
|
|
89
|
+
' "$PLUGIN_ROOT"/skills/*/SKILL.md
|