@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.
Files changed (109) hide show
  1. package/CHANGELOG.md +1421 -0
  2. package/LICENSE +201 -0
  3. package/README.md +206 -2
  4. package/package.json +44 -4
  5. package/plugins/devos/agents/reader.md +27 -0
  6. package/plugins/devos/agents/verifier.md +155 -0
  7. package/plugins/devos/pi/extension/devos.ts +605 -0
  8. package/plugins/devos/scripts/check-evidence-router.sh +140 -0
  9. package/plugins/devos/scripts/evidence-router.py +254 -0
  10. package/plugins/devos/scripts/gates/check-dod-core.sh +285 -0
  11. package/plugins/devos/scripts/gates/check-dod.sh +38 -0
  12. package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
  13. package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
  14. package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
  15. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +104 -0
  16. package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
  17. package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
  18. package/plugins/devos/scripts/gates/plan-template-check.py +141 -0
  19. package/plugins/devos/scripts/gates/run-gate.sh +148 -0
  20. package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
  21. package/plugins/devos/scripts/gates/spec-template-check.py +152 -0
  22. package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
  23. package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
  24. package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
  25. package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
  26. package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
  27. package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
  28. package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
  29. package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
  30. package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
  31. package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
  32. package/plugins/devos/scripts/gates/test-gates.sh +76 -0
  33. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
  34. package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
  35. package/plugins/devos/skills/absorb/SKILL.md +75 -0
  36. package/plugins/devos/skills/absorb/references/distill.md +67 -0
  37. package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
  38. package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
  39. package/plugins/devos/skills/build/SKILL.md +71 -0
  40. package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
  41. package/plugins/devos/skills/build/references/defect.md +17 -0
  42. package/plugins/devos/skills/build/references/exposure.md +28 -0
  43. package/plugins/devos/skills/build/references/hard.md +39 -0
  44. package/plugins/devos/skills/build/references/refactor.md +66 -0
  45. package/plugins/devos/skills/build/references/routes.md +56 -0
  46. package/plugins/devos/skills/build/references/scale.md +84 -0
  47. package/plugins/devos/skills/build/references/spike.md +19 -0
  48. package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
  49. package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
  50. package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
  51. package/plugins/devos/skills/build/scripts/route.sh +5 -0
  52. package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
  53. package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
  54. package/plugins/devos/skills/frame/SKILL.md +54 -0
  55. package/plugins/devos/skills/frame/references/template.md +115 -0
  56. package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
  57. package/plugins/devos/skills/implement/SKILL.md +36 -0
  58. package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
  59. package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
  60. package/plugins/devos/skills/implement/references/dod.md +37 -0
  61. package/plugins/devos/skills/implement/references/implement.md +54 -0
  62. package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
  63. package/plugins/devos/skills/implement/references/plan.md +142 -0
  64. package/plugins/devos/skills/implement/references/resume.md +9 -0
  65. package/plugins/devos/skills/implement/references/scale.md +86 -0
  66. package/plugins/devos/skills/implement/references/verify-close.md +62 -0
  67. package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
  68. package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
  69. package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
  70. package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
  71. package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
  72. package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
  73. package/plugins/devos/skills/implement/scripts/validate-spec.sh +220 -0
  74. package/plugins/devos/skills/init/SKILL.md +100 -0
  75. package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
  76. package/plugins/devos/skills/init/references/context.md +42 -0
  77. package/plugins/devos/skills/init/references/conventions-template.md +153 -0
  78. package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
  79. package/plugins/devos/skills/init/references/rule-format.md +58 -0
  80. package/plugins/devos/skills/init/references/shape-model.md +29 -0
  81. package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
  82. package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
  83. package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
  84. package/plugins/devos/skills/learn/SKILL.md +29 -0
  85. package/plugins/devos/skills/learn/references/destinations.md +43 -0
  86. package/plugins/devos/skills/learn/references/scoring.md +26 -0
  87. package/plugins/devos/skills/review/SKILL.md +54 -0
  88. package/plugins/devos/skills/review/references/comments.md +13 -0
  89. package/plugins/devos/skills/review/references/gaps.md +26 -0
  90. package/plugins/devos/skills/review/references/reviewer.md +124 -0
  91. package/plugins/devos/skills/review/references/routing.md +35 -0
  92. package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
  93. package/plugins/devos/skills/review/scripts/prepare.py +763 -0
  94. package/plugins/devos/skills/spec/SKILL.md +57 -0
  95. package/plugins/devos/skills/spec/references/prototype.md +21 -0
  96. package/plugins/devos/skills/spec/references/question-craft.md +47 -0
  97. package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
  98. package/plugins/devos/skills/spec/references/write-spec.md +128 -0
  99. package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
  100. package/plugins/devos/skills/status/SKILL.md +67 -0
  101. package/plugins/devos/skills/status/references/cost.md +38 -0
  102. package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
  103. package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
  104. package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
  105. package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
  106. package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
  107. package/plugins/devos/skills/status/scripts/quality-correlation.sh +259 -0
  108. package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
  109. 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(/&/, "\\&amp;", s)
56
+ gsub(/</, "\\&lt;", s)
57
+ gsub(/>/, "\\&gt;", s)
58
+ gsub(/"/, "\\&quot;", s)
59
+ gsub(/'"'"'/, "\\&apos;", 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