@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,140 @@
1
+ #!/bin/bash
2
+ # Deterministic tests for evidence-router.py, plain asserts, no framework,
3
+ # no model calls. Run via `just verify`.
4
+ set -u
5
+ cd "$(dirname "${BASH_SOURCE[0]}")"
6
+ ROUTER="$PWD/evidence-router.py"
7
+ REPO="$(cd ../../.. && pwd)"
8
+
9
+ pass=0 fail=0
10
+
11
+ check() { # check <name> <expected-exit> <actual-exit>
12
+ if [[ "$2" == "$3" ]]; then
13
+ pass=$((pass + 1))
14
+ else
15
+ echo "FAIL $1: expected exit $2, got $3" >&2
16
+ fail=$((fail + 1))
17
+ fi
18
+ }
19
+
20
+ has() { # has <name> <needle> <haystack>
21
+ if [[ "$3" == *"$2"* ]]; then
22
+ pass=$((pass + 1))
23
+ else
24
+ echo "FAIL $1: expected output to contain '$2'" >&2
25
+ fail=$((fail + 1))
26
+ fi
27
+ }
28
+
29
+ hasnt() { # hasnt <name> <needle> <haystack>
30
+ if [[ "$3" != *"$2"* ]]; then
31
+ pass=$((pass + 1))
32
+ else
33
+ echo "FAIL $1: expected output NOT to contain '$2'" >&2
34
+ fail=$((fail + 1))
35
+ fi
36
+ }
37
+
38
+ tmp=$(mktemp -d)
39
+ trap '[[ $BASH_SUBSHELL -eq 0 ]] && rm -rf "$tmp"' EXIT
40
+
41
+ # --- fixture project ------------------------------------------------------
42
+ proj="$tmp/proj"
43
+ mkdir -p "$proj/devos/standards/rules/01-api" "$proj/devos/product/behaviors"
44
+ cat > "$proj/devos/standards/conventions.md" <<'MD'
45
+ ---
46
+ devos-contract: 1
47
+ ---
48
+ # Project Conventions
49
+
50
+ Choices this project has made.
51
+
52
+ ## Testing
53
+
54
+ Write tests for every gate script before it is wired anywhere. A test that
55
+ cannot fail is not a test.
56
+
57
+ ## Commits
58
+
59
+ Conventional commits. One logical change per commit.
60
+ MD
61
+ cat > "$proj/devos/standards/rules/01-api/auth.md" <<'MD'
62
+ ---
63
+ globs: src/api/**
64
+ ---
65
+ # Auth
66
+
67
+ Every src/api route authenticates the request before it touches the store.
68
+ MD
69
+ cat > "$proj/devos/product/domain-model.md" <<'MD'
70
+ # Domain Model
71
+
72
+ ## Invoice
73
+
74
+ An Invoice is a list of InvoiceLine amounts, summed to a total.
75
+ MD
76
+ cat > "$proj/devos/product/behaviors/invoice.md" <<'MD'
77
+ # Invoice behavior
78
+
79
+ Creating an invoice emits one `invoice.created` event.
80
+ MD
81
+
82
+ # --- 1. lexical selection keeps the relevant block, drops the rest --------
83
+ out=$(python3 "$ROUTER" --root "$proj" --task 'how should tests be named' --files src/x.ts)
84
+ check "lexical: exits 0" 0 $?
85
+ has "lexical: keeps the Testing block" "· Testing" "$out"
86
+ hasnt "lexical: drops the Commits block" "## Commits" "$out"
87
+ has "lexical: counts the candidates" "> kept 2 of 7 candidates" "$out"
88
+ has "lexical: quotes the block" "> Write tests for every gate script" "$out"
89
+
90
+ # --- 2. a rules file matching a touched file is mandatory -----------------
91
+ out=$(python3 "$ROUTER" --root "$proj" --task 'update the logging format' --files src/api/routes.ts)
92
+ has "rules: matched glob is mandatory" "mandatory rule" "$out"
93
+ has "rules: names the rule file" "01-api/auth.md" "$out"
94
+
95
+ out=$(python3 "$ROUTER" --root "$proj" --task 'update the logging format' --files src/cli/main.ts)
96
+ hasnt "rules: unmatched glob is not mandatory" "mandatory rule" "$out"
97
+
98
+ # --- 3. --keep caps the kept set and json parses --------------------------
99
+ n=$(python3 "$ROUTER" --root "$proj" --task 'conventions about tests and invoices and api auth' \
100
+ --files src/api/routes.ts --keep 3 --format json \
101
+ | python3 -c "import json,sys; d=json.load(sys.stdin); assert len(d['kept']) <= 3; assert 'dropped' in d; print('ok')")
102
+ check "keep: --keep 3 holds the cap" 0 $?
103
+ has "keep: json parses" "ok" "$n"
104
+
105
+ # --- 4. the selection has no model, server or setting in it ---------------
106
+ out=$(python3 "$ROUTER" --root "$proj" --task 'how should tests be named' --files src/x.ts)
107
+ hasnt "deterministic: no model vocabulary in the header" "systemone" "$out"
108
+ hasnt "deterministic: no transport note" "unavailable" "$out"
109
+
110
+ # The flags that reached a model are gone rather than ignored, so a stale script
111
+ # fails loudly instead of selecting quietly without the pass it asked for.
112
+ for flag in --systemone --no-systemone --shadow-log --export-eval --dataset-from-shadow --_systemone-resolve; do
113
+ python3 "$ROUTER" --root "$proj" --task 'anything' "$flag" x >/dev/null 2>&1
114
+ check "removed: $flag is a usage error" 2 $?
115
+ done
116
+
117
+ # --- 5. the real repository is indexable ----------------------------------
118
+ out=$(python3 "$ROUTER" --root "$REPO" --task 'gate script tests run against real repo content before wiring' \
119
+ --files plugins/devos/scripts/gates/test-gates.sh --format json)
120
+ check "real repo: exits 0" 0 $?
121
+ has "real repo: selects a conventions block" "devos/standards/conventions.md" "$out"
122
+
123
+ # --- 6. a project with no devos/ folder yields nothing, quietly -----------
124
+ mkdir -p "$tmp/empty"
125
+ out=$(python3 "$ROUTER" --root "$tmp/empty" --task 'anything at all' --files src/x.ts)
126
+ check "empty: exits 0" 0 $?
127
+ has "empty: reports zero candidates" "kept 0 of 0 candidates" "$out"
128
+
129
+ # --- 7. --terms adds vocabulary the task does not carry -------------------
130
+ out=$(python3 "$ROUTER" --root "$proj" --task 'how should tests be named' --files src/x.ts)
131
+ hasnt "terms: without terms the Commits block is dropped" "## Commits" "$out"
132
+ out=$(python3 "$ROUTER" --root "$proj" --task 'how should tests be named' --terms 'conventional commit' --files src/x.ts)
133
+ has "terms: the extra terms bring the Commits block back" "## Commits" "$out"
134
+
135
+ # --- 8. a missing task is a usage error ----------------------------------
136
+ python3 "$ROUTER" --root "$proj" --files src/x.ts >/dev/null 2>&1
137
+ check "usage: --task is required" 2 $?
138
+
139
+ echo "evidence-router: $pass passed, $fail failed"
140
+ [[ $fail -eq 0 ]]
@@ -0,0 +1,254 @@
1
+ #!/usr/bin/env python3
2
+ """evidence-router: pick the evidence blocks a DevOS stage should read.
3
+
4
+ Given a task and the files it touches, index the project's declared evidence
5
+ (devos/standards/conventions.md sections, devos/standards/rules/*.md,
6
+ devos/product/behaviors/*.md, devos/product/domain-model.md sections, and a spec
7
+ folder's spec.md sections), select the smallest set worth
8
+ loading, and print it quoted with file:line ranges.
9
+
10
+ Selection is deterministic: a rules file whose `globs:` matches a touched file is
11
+ mandatory, everything else ranks by lexical overlap between the task and the
12
+ block. There is no model call, no server and no setting: the same task and files
13
+ give the same list on every machine.
14
+
15
+ A block is ranked by heading hits at 3x plus body hits damped by the block's own
16
+ length, so a long file does not out-rank a short section on size alone. The
17
+ budget is `--keep`, clamped to 3-8, and the list never grows past it.
18
+
19
+ This chooses references. It never summarises or rewrites them and it is not a
20
+ gate: the reader decides what to read, and a block the router dropped still
21
+ becomes a finding when someone reads it. The plan capsule stays the source of
22
+ truth, so implementation reads spec.md as before.
23
+
24
+ Usage:
25
+ evidence-router.py --task "add PDF export" [--files a,b] [--spec devos/specs/name]
26
+ [--root DIR] [--keep N] [--format md|json]
27
+ """
28
+ from __future__ import annotations
29
+
30
+ import argparse
31
+ import json
32
+ import re
33
+ import sys
34
+ from pathlib import Path
35
+
36
+ STOPWORDS = frozenset(
37
+ "a an the and or of to in for on with is are be this that it its as at by "
38
+ "from not no when what how you your any all each every add make use change "
39
+ "file files should must before after into over under".split()
40
+ )
41
+ MAX_BLOCK_LINES = 40
42
+ MAX_BLOCK_CHARS = 2000
43
+
44
+
45
+ class Candidate:
46
+ def __init__(self, path: Path, rel: str, heading: str, start: int, end: int, text: str):
47
+ self.path = path
48
+ self.rel = rel
49
+ self.heading = heading
50
+ self.start = start
51
+ self.end = end
52
+ self.text = text
53
+ self.glob_patterns: list[str] = []
54
+ self.score = 0
55
+ self.why = ""
56
+
57
+ @property
58
+ def id(self) -> str:
59
+ if self.heading and self.heading != self.rel:
60
+ return f"{self.rel}#{self.heading}"
61
+ return self.rel
62
+
63
+
64
+ def tokens(text: str) -> set[str]:
65
+ return {t for t in re.findall(r"[a-z0-9]+", text.lower()) if t not in STOPWORDS}
66
+
67
+
68
+ def block_score(cand: Candidate, qtokens: set[str]) -> float:
69
+ """Rank a block by how much of the query it carries, damped by its own size.
70
+
71
+ The body term is divided by sqrt(block tokens) rather than counted raw. A raw
72
+ count rewards a block for being long, and the artifacts are split unevenly:
73
+ a behavior file is one 100-token block while conventions.md is ten blocks of
74
+ 15 to 80, so a long file out-scored every short relevant section on the
75
+ strength of its size alone. The sqrt term is the standard damping in
76
+ retrieval scoring: one more hit still counts, but a hit in a long block
77
+ counts for progressively less than the same hit in a short one. It has no
78
+ tuned constant, which matters because the only label available is a file
79
+ and a constant fitted to it would be the label wearing a score.
80
+
81
+ The heading stays at 3x undamped. A heading is a few tokens either way, so
82
+ it carries no size bias to correct.
83
+ """
84
+ heading_hits = len(qtokens & tokens(cand.heading))
85
+ body_hits = len(qtokens & tokens(cand.text))
86
+ body_len = max(1, len(tokens(cand.text)))
87
+ return 3 * heading_hits + body_hits / body_len**0.5
88
+
89
+
90
+ def sectionize(path: Path, rel: str) -> list[Candidate]:
91
+ """Split a markdown file into blocks at '## ' headings (preamble included)."""
92
+ lines = path.read_text(errors="replace").splitlines()
93
+ starts = [i for i, l in enumerate(lines) if l.startswith("## ")]
94
+ bounds = starts + [len(lines)]
95
+ out: list[Candidate] = []
96
+ if not starts:
97
+ out.append(Candidate(path, rel, rel, 1, len(lines), "\n".join(lines)))
98
+ return out
99
+ if starts[0] > 0:
100
+ title = next((l.lstrip("# ").strip() for l in lines[: starts[0]] if l.startswith("# ")), rel)
101
+ out.append(Candidate(path, rel, title, 1, starts[0], "\n".join(lines[: starts[0]])))
102
+ for i in range(len(bounds) - 1):
103
+ s, e = bounds[i], bounds[i + 1]
104
+ heading = lines[s][3:].strip()
105
+ out.append(Candidate(path, rel, heading, s + 1, e, "\n".join(lines[s:e])))
106
+ return out
107
+
108
+
109
+ def whole_file(path: Path, rel: str, root: Path) -> Candidate:
110
+ lines = path.read_text(errors="replace").splitlines()
111
+ return Candidate(path, rel, path.stem, 1, len(lines), "\n".join(lines))
112
+
113
+
114
+ def parse_globs(path: Path) -> list[str]:
115
+ m = re.search(r"^globs:[ \t]*(.*)$", path.read_text(errors="replace"), re.M)
116
+ if not m:
117
+ return []
118
+ return [p.strip() for p in m.group(1).split(",") if p.strip()]
119
+
120
+
121
+ def glob_match(pattern: str, rel: str) -> bool:
122
+ rx = ""
123
+ i = 0
124
+ while i < len(pattern):
125
+ c = pattern[i]
126
+ if pattern.startswith("**/", i):
127
+ rx += "(?:.*/)?"
128
+ i += 3
129
+ elif pattern.startswith("**", i):
130
+ rx += ".*"
131
+ i += 2
132
+ elif c == "*":
133
+ rx += "[^/]*"
134
+ i += 1
135
+ elif c == "?":
136
+ rx += "[^/]"
137
+ i += 1
138
+ else:
139
+ rx += re.escape(c)
140
+ i += 1
141
+ return re.fullmatch(rx, rel) is not None
142
+
143
+
144
+ def collect(root: Path, spec: Path | None) -> list[Candidate]:
145
+ cands: list[Candidate] = []
146
+ for rel in ("devos/standards/conventions.md", "devos/product/domain-model.md"):
147
+ p = root / rel
148
+ if p.is_file():
149
+ cands += sectionize(p, rel)
150
+ rules = root / "devos/standards/rules"
151
+ if rules.is_dir():
152
+ for p in sorted(rules.rglob("*.md")):
153
+ rel = p.relative_to(root).as_posix()
154
+ c = whole_file(p, rel, root)
155
+ c.glob_patterns = parse_globs(p)
156
+ cands.append(c)
157
+ behaviors = root / "devos/product/behaviors"
158
+ if behaviors.is_dir():
159
+ for p in sorted(behaviors.glob("*.md")):
160
+ cands.append(whole_file(p, p.relative_to(root).as_posix(), root))
161
+ if spec:
162
+ for name in ("spec.md",):
163
+ p = spec / name
164
+ if p.is_file():
165
+ cands += sectionize(p, p.relative_to(root).as_posix() if p.is_relative_to(root) else str(p))
166
+ return cands
167
+
168
+
169
+ def select_lexical(cands: list[Candidate], qtokens: set[str], files: list[str], keep: int) -> list[Candidate]:
170
+ mandatory = []
171
+ for c in cands:
172
+ if c.glob_patterns and any(glob_match(g, f) for g in c.glob_patterns for f in files):
173
+ c.why = "mandatory rule"
174
+ mandatory.append(c)
175
+ ranked = [c for c in cands if c not in mandatory]
176
+ for c in ranked:
177
+ c.score = block_score(c, qtokens)
178
+ ranked = [c for c in ranked if c.score > 0]
179
+ ranked.sort(key=lambda c: (-c.score, c.rel, c.start))
180
+ for c in ranked:
181
+ c.why = f"lexical score {c.score:.2f}"
182
+ return mandatory + ranked[: max(0, keep - len(mandatory))]
183
+
184
+
185
+ def quote_block(cand: Candidate) -> str:
186
+ lines = cand.text.splitlines()
187
+ out, chars = [], 0
188
+ for line in lines:
189
+ if len(out) >= MAX_BLOCK_LINES or chars + len(line) > MAX_BLOCK_CHARS:
190
+ out.append("…")
191
+ break
192
+ out.append("> " + line)
193
+ chars += len(line)
194
+ return "\n".join(out)
195
+
196
+
197
+ def emit_md(kept: list[Candidate], total: int, task: str) -> None:
198
+ print(f"> kept {len(kept)} of {total} candidates | task: {task[:80]}")
199
+ for c in kept:
200
+ print(f"\n## {c.rel}:{c.start}-{c.end} · {c.heading} [{c.why}]")
201
+ print(quote_block(c))
202
+
203
+
204
+ def main() -> int:
205
+ ap = argparse.ArgumentParser(prog="evidence-router", description="select the evidence blocks a DevOS stage should read")
206
+ ap.add_argument("--task")
207
+ ap.add_argument("--task-file")
208
+ ap.add_argument("--files", default="")
209
+ ap.add_argument("--terms", default="", help="extra query terms, e.g. the identifiers a diff adds")
210
+ ap.add_argument("--spec")
211
+ ap.add_argument("--root", default=".")
212
+ ap.add_argument("--keep", type=int, default=6, help="blocks to keep, clamped to 3-8")
213
+ ap.add_argument("--format", choices=("md", "json"), default="md")
214
+ args = ap.parse_args()
215
+
216
+ if args.task:
217
+ task = args.task
218
+ elif args.task_file:
219
+ task = sys.stdin.read() if args.task_file == "-" else Path(args.task_file).read_text()
220
+ else:
221
+ ap.error("one of --task or --task-file is required")
222
+ root = Path(args.root).resolve()
223
+ files = [f.strip() for f in args.files.split(",") if f.strip()]
224
+ spec = None
225
+ if args.spec:
226
+ spec = Path(args.spec)
227
+ spec = spec if spec.is_absolute() else (spec if "/" in args.spec else root / "devos/specs" / args.spec)
228
+ spec = spec.resolve()
229
+ keep = max(3, min(8, args.keep))
230
+
231
+ cands = collect(root, spec)
232
+ qtokens = tokens(task) | tokens(args.terms) | {t for f in files for t in tokens(f.replace("/", " ").replace(".", " ").replace("-", " ").replace("_", " "))}
233
+ kept = select_lexical(cands, qtokens, files, keep)
234
+
235
+ if args.format == "json":
236
+ print(json.dumps({
237
+ "task": task.strip()[:200],
238
+ "files": files,
239
+ "terms": args.terms.strip()[:400],
240
+ "keep": keep,
241
+ "candidates": len(cands),
242
+ "kept": [{
243
+ "id": c.id, "path": c.rel, "start": c.start, "end": c.end,
244
+ "heading": c.heading, "why": c.why, "score": c.score,
245
+ } for c in kept],
246
+ "dropped": [c.id for c in cands if c not in kept],
247
+ }, indent=2))
248
+ else:
249
+ emit_md(kept, len(cands), task.strip())
250
+ return 0
251
+
252
+
253
+ if __name__ == "__main__":
254
+ sys.exit(main())
@@ -0,0 +1,285 @@
1
+ #!/bin/bash
2
+ # DoD check core: given a transcript file, decide allow/block.
3
+ # Deterministic: no LLM judgment. Shared by every harness adapter that
4
+ # has transcript access at its stop/end-of-turn event (Claude, Copilot CLI,
5
+ # Codex).
6
+ #
7
+ # Usage: check-dod-core.sh <transcript-file>
8
+ # <transcript-file> must already be a plain-text or JSONL dump containing
9
+ # the assistant's messages; callers extract it from their own transcript
10
+ # format before calling this.
11
+ #
12
+ # Exit 0 = allow (no DONE claim, or DONE claim with a report that concludes
13
+ # Completeness CLEAN and Quality PASS).
14
+ # Exit 2 = block. Reason on stderr. A report that exists but concludes FAIL,
15
+ # HAS ISSUES, or states no verdict at all blocks exactly like a
16
+ # missing report.
17
+ set -u
18
+
19
+ GATES="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
20
+ transcript="${1:-}"
21
+ [[ -f "$transcript" ]] || exit 0
22
+
23
+ last=$(cat "$transcript")
24
+
25
+ # More than one line can start `Verdict: DONE`, and the last is not always the
26
+ # verdict: this gate's own message names the format as `Verdict: DONE:
27
+ # devos/specs/[name]`, so a model that echoes the reminder after emitting the
28
+ # real verdict used to have the reminder read instead and get blocked for
29
+ # repeating the gate's words. Scan every matching line and keep the last that
30
+ # yields a valid spec; block only when none does.
31
+ spec=""
32
+ found=0
33
+ while IFS= read -r verdict_line; do
34
+ found=1
35
+ # A valid spec name is exactly one path segment after devos/specs[/archive].
36
+ # A bare directory (no name), a literal `...` placeholder, or a report path
37
+ # pasted as the spec (last segment `verifications`, which would make the gate
38
+ # append verifications/verification.md twice) name no spec, so a later valid
39
+ # line can still supply one.
40
+ s=$(printf '%s' "$verdict_line" | grep -Eo 'devos/specs/(archive/)?[A-Za-z0-9._-]+' | head -1)
41
+ case "$s" in
42
+ devos/specs|devos/specs/archive|*'...'*|*/verifications) s="" ;;
43
+ esac
44
+ [[ -n "$s" ]] && spec="$s"
45
+ done < <(printf '%s' "$last" | grep -E 'Verdict: *DONE')
46
+ [[ $found -eq 0 ]] && exit 0
47
+
48
+ # The checkout already knows which spec this turn belongs to: the pipeline
49
+ # creates a `[spec-name]` branch before the first edit, so the branch is
50
+ # a deterministic resolver and the model should not have to transcribe a path.
51
+ # When no line names a spec, or the one it names has no report (a placeholder
52
+ # like `devos/specs/x`), the branch's spec stands in. Off a spec branch nothing
53
+ # changes: naming is still the only signal, and its absence still blocks.
54
+ if [[ -z "$spec" || ! -f "$spec/verifications/verification.md" ]]; then
55
+ branch=$(git symbolic-ref --short HEAD 2>/dev/null || true)
56
+ bspec="devos/specs/${branch:-}"
57
+ [[ -n "$branch" && -f "$bspec/verifications/verification.md" ]] && spec="$bspec"
58
+ fi
59
+
60
+ if [[ -z "$spec" ]]; then
61
+ echo "'Verdict: DONE' must name the spec on the same line (format: 'Verdict: DONE: devos/specs/[name]') so the gate can check its verification report." >&2
62
+ exit 2
63
+ fi
64
+
65
+ report="$spec/verifications/verification.md"
66
+ if [[ ! -f "$report" ]]; then
67
+ echo "'Verdict: DONE' claimed but $report does not exist. Run the verifier before declaring DONE." >&2
68
+ exit 2
69
+ fi
70
+
71
+ # The plan is the artifact of record for what this spec delivered: its
72
+ # `**Files:**` lines are the file list the checks below read.
73
+ plan="$spec/spec.md"
74
+ planned=""
75
+ if [[ -f "$plan" ]]; then
76
+ planned=$(grep -oE '^\*\*Files:\*\*.*' "$plan" | grep -oE '`[^`]+`' | tr -d '`' || true)
77
+ fi
78
+
79
+ if ! grep -qE 'Completeness:[[:space:]]*(\*\*)?CLEAN(\*\*)?([[:space:]]*(\||$))' "$report" \
80
+ || ! grep -qE 'Quality:[[:space:]]*(\*\*)?PASS(\*\*)?([[:space:]]*(\||$))' "$report"; then
81
+ echo "'Verdict: DONE' claimed but $report does not conclude Completeness CLEAN + Quality PASS. Fix the findings and re-run the verifier before declaring DONE." >&2
82
+ exit 2
83
+ fi
84
+
85
+ # A verdict is about code, and code moves. The report records the commit it read
86
+ # (`> <date> | commit: <sha> | Completeness: ...`), because nothing re-runs the
87
+ # verifier when a later edit lands: without it, a report that concluded CLEAN
88
+ # outlives the code it was true of, and every green report reads the same whether
89
+ # it still holds. That is the one thing a green report cannot tell its reader.
90
+ #
91
+ # Scoped to the files the plan names, not the whole tree: the close protocol
92
+ # writes the behavior files, the archive, the changelog and the roadmap after the
93
+ # verifier has run, and a verification gate that fires on its own pipeline's
94
+ # paperwork is a bottleneck with no failure behind it. A delivered file whose
95
+ # content changed after the verdict is the unarguable case this catches. A report
96
+ # with no marker predates the field and passes, and git's absence fails open like
97
+ # every other environment-dependent check here.
98
+ if git rev-parse --git-dir >/dev/null 2>&1; then
99
+ judged=$(grep -oE '^>.*commit: *[0-9a-f]{7,40}' "$report" 2>/dev/null | head -1 | sed 's/.*commit: *//')
100
+ if [[ -n "$judged" ]] && ! git cat-file -e "${judged}^{commit}" 2>/dev/null; then
101
+ echo "$report names commit '$judged', which does not exist in this repository, so its verdict is about no tree here. Re-run the verifier and record the commit it read." >&2
102
+ exit 2
103
+ fi
104
+ top=$(git rev-parse --show-toplevel 2>/dev/null || true)
105
+ planned_files=()
106
+ while IFS= read -r f; do [[ -n "$f" ]] && planned_files+=("$f"); done <<<"$planned"
107
+ if [[ -n "$judged" && -n "$top" && ${#planned_files[@]} -gt 0 ]]; then
108
+ # Only a real difference blocks: a pathspec or shallow-clone error is the
109
+ # gate's own limitation, never the implementer's problem.
110
+ git -C "$top" diff --quiet "$judged" -- "${planned_files[@]}" 2>/dev/null
111
+ drift=$?
112
+ if [[ $drift -eq 1 ]]; then
113
+ echo "$report concluded CLEAN + PASS on $judged, and a file the plan delivered has changed since. A verdict holds for the commit it judged: re-run the verifier on the current code before declaring DONE." >&2
114
+ exit 2
115
+ fi
116
+ fi
117
+ fi
118
+
119
+ # A failure called pre-existing has to be shown, not asserted. The DoD's own
120
+ # rationalization table already answers "the 2 failures are unrelated" with
121
+ # "then prove it: show they fail on the base branch too", and until Phase B
122
+ # started recording that run there was nothing to point at. baseline.md is that
123
+ # record; a report leaning on the claim without it is blocked here.
124
+ #
125
+ # The claim is what triggers the requirement, so a report that never makes it
126
+ # needs no baseline: this cannot block a project whose commands do not run.
127
+ preexisting_claim=$(awk '
128
+ {
129
+ line = $0
130
+ gsub(/[.!?;,]|[[:space:]]+(but|however|although)[[:space:]]+/, "\n", line)
131
+ n = split(line, clauses, "\n")
132
+ for (i = 1; i <= n; i++) {
133
+ text = tolower(clauses[i])
134
+ if (text ~ /pre-?existing|already failing|unrelated failure|fails on the base|failed before/ \
135
+ && text !~ /(^|[^[:alnum:]])(no|not|never|without|zero)[[:space:]]/) {
136
+ print clauses[i]
137
+ }
138
+ }
139
+ }' "$report")
140
+ if [[ -n "$preexisting_claim" ]] && [[ ! -f "$spec/verifications/baseline.md" ]]; then
141
+ echo "$report calls a failure pre-existing, but $spec/verifications/baseline.md does not exist, so nothing shows it failing before this implementation. Capture the baseline (Phase B step 3) and re-run the verifier, or drop the claim." >&2
142
+ exit 2
143
+ fi
144
+
145
+ # An implementation that delivered nothing verifies CLEAN: the verifier scopes
146
+ # to the diff, and an empty diff has no placeholders in it. The plan's own
147
+ # `**Files:**` lines say what was meant to exist, so requiring one of them to be
148
+ # real is the crude version of the check nothing enforced.
149
+ #
150
+ # One file, not all of them: a plan whose file list was amended mid-flight is
151
+ # normal, and a gate that blocks legitimate work is worse than one that catches
152
+ # only the unarguable case. Paths under devos/ count like any other, because a
153
+ # spec whose whole job is to write a standards file delivered what it planned.
154
+ # Silent when the plan names no files (an M-route inline spec may not), same
155
+ # "validated only if present" posture as below.
156
+ if [[ -n "$planned" ]]; then
157
+ delivered=0
158
+ while IFS= read -r f; do
159
+ [[ -e "$f" ]] && { delivered=1; break; }
160
+ done <<<"$planned"
161
+ if [[ "$delivered" == 0 ]]; then
162
+ echo "'Verdict: DONE' claimed but not one file named in $plan's Implementation Plan exists. Nothing was delivered, which the verifier reads as a clean diff rather than as missing work." >&2
163
+ exit 2
164
+ fi
165
+ fi
166
+
167
+ # The edit hooks cover normal writes. This final pass catches files produced by
168
+ # a shell command or written before a hook loaded. The plan is the authoritative
169
+ # file list, and the boundary helper applies the same project-owned-code rule.
170
+ if [[ -f "$plan" && -x "$GATES/check-implementation-boundary.sh" ]]; then
171
+ # This repository's eval corpus is framework input, not target project output.
172
+ framework_repo=0
173
+ [[ -d "$PWD/plugins/devos/skills" && -d "$PWD/evals" ]] && framework_repo=1
174
+ while IFS= read -r f; do
175
+ [[ -e "$f" ]] || continue
176
+ if (( framework_repo )); then
177
+ case "$f" in
178
+ evals/*) continue ;;
179
+ esac
180
+ fi
181
+ boundary_reason=$("$GATES/check-implementation-boundary.sh" --scan --file "$f" 2>&1 >/dev/null)
182
+ boundary_status=$?
183
+ if [[ "$boundary_status" -eq 2 ]]; then
184
+ echo "'Verdict: DONE' claimed but $f contains internal process metadata. Keep trace IDs and framework rules in devos artifacts." >&2
185
+ [[ -n "$boundary_reason" ]] && echo "$boundary_reason" >&2
186
+ exit 2
187
+ fi
188
+ done <<<"$planned"
189
+ fi
190
+
191
+ # Temporary instrumentation, tagged per the B route's convention
192
+ # (`[DEBUG-xxxx]`, 4 hex digits), must be gone before DONE. Tracked files only:
193
+ # an untracked scratch script was never shipped. Scoped to the tag shape on
194
+ # purpose, so prose that documents the convention with the literal `xxxx`
195
+ # placeholder does not match itself. Fails open outside a git repo.
196
+ if git rev-parse --git-dir >/dev/null 2>&1; then
197
+ debug_hits=$(git grep -nE '\[DEBUG-[0-9a-f]{4}\]' 2>/dev/null | head -5)
198
+ if [[ -n "$debug_hits" ]]; then
199
+ echo "'Verdict: DONE' claimed but tagged debug instrumentation is still in tracked files. Remove it before declaring DONE:" >&2
200
+ echo "$debug_hits" >&2
201
+ exit 2
202
+ fi
203
+ fi
204
+
205
+ # The Behavior delta names capabilities this spec changes; Completion step 1
206
+ # (references/verify-close.md) merges each into
207
+ # devos/product/behaviors/<capability>.md before the verdict is declared.
208
+ # Silent when no Behavior delta section exists at all: pre-v0.4.0 specs,
209
+ # M-route inline specs, and a delta with nothing changed are all legitimate
210
+ #.
211
+ sf=$(mktemp)
212
+ bash "$(dirname "${BASH_SOURCE[0]}")/spec-contract.sh" "$spec" >"$sf" 2>/dev/null
213
+ if grep -qiE '^#+ .*behavior delta' "$sf"; then
214
+ spec_name="$(basename "$spec")"
215
+ while IFS= read -r line; do
216
+ marker=$(printf '%s' "$line" | grep -oE '\*\*(Added|Modified|Removed)\*\*')
217
+ cap=$(printf '%s' "$line" | grep -oE 'capability: *`[A-Za-z0-9-]+`' | tr -d '`' | sed 's/^capability: *//')
218
+ [[ -z "$cap" ]] && continue
219
+ bf="devos/product/behaviors/$cap.md"
220
+ if [[ "$marker" == "**Removed**" ]]; then
221
+ # A removal leaves a ## History tombstone, not necessarily a fresh
222
+ # last-spec header (nothing else about the file may have changed).
223
+ if [[ ! -f "$bf" ]] || ! grep -qE '^## History' "$bf" || ! grep -qF "$spec_name" "$bf"; then
224
+ echo "'Verdict: DONE' claimed but the Behavior delta's Removed entry for capability '$cap' has no History tombstone naming this spec in $bf. Merge the Behavior delta (Completion step 1) before declaring DONE." >&2
225
+ exit 2
226
+ fi
227
+ else
228
+ if [[ ! -f "$bf" ]] || ! grep -qF "last spec: $spec_name" "$bf"; then
229
+ echo "'Verdict: DONE' claimed but the Behavior delta names capability '$cap' ($marker), and $bf does not exist or its 'last spec:' header does not name this spec. Merge the Behavior delta (Completion step 1) before declaring DONE." >&2
230
+ exit 2
231
+ fi
232
+ fi
233
+ done < <(grep -E '\*\*(Added|Modified|Removed)\*\*.*capability:' "$sf")
234
+ fi
235
+ rm -f "$sf"
236
+
237
+ # Every `path:line` the report cites is re-derived from the tree. A finding's
238
+ # position is the part of it a candidate can get right in prose and wrong in
239
+ # fact, and until this pass nothing read it back: a citation past the end of its
240
+ # file blocked nothing and looked like every other line. The reflection lives in
241
+ # a sibling script so it is testable alone and any caller holding a report can
242
+ # run it; a missing or broken script fails open (a hook's own error is never
243
+ # policy), a reported finding blocks.
244
+ loc_out=$(bash "$(dirname "${BASH_SOURCE[0]}")/check-report-locations.sh" "$report" 2>&1)
245
+ loc_rc=$?
246
+ if [[ $loc_rc -eq 1 ]]; then
247
+ echo "'Verdict: DONE' claimed but $report cites positions that do not resolve:" >&2
248
+ echo "$loc_out" >&2
249
+ exit 2
250
+ fi
251
+
252
+ # The other half of the same reflection: the citation pass catches a row that
253
+ # points nowhere, this catches the row that was never written. The verifier is
254
+ # told to record every SC-n from the spec's Scenarios, and an omitted scenario is
255
+ # invisible exactly where the report reads cleanest. A missing or broken script
256
+ # fails open, a missing ID blocks, the same contract as the pass above.
257
+ cov_out=$(bash "$(dirname "${BASH_SOURCE[0]}")/check-scenario-coverage.sh" "$spec" 2>&1)
258
+ cov_rc=$?
259
+ if [[ $cov_rc -eq 1 ]]; then
260
+ echo "'Verdict: DONE' claimed but $report does not account for every scenario the functional spec declares:" >&2
261
+ echo "$cov_out" >&2
262
+ exit 2
263
+ fi
264
+
265
+ # A port reads one tree and writes another, and the tree it reads may be
266
+ # running in production. The manifest names the sources, so the sources are
267
+ # checked against the branch: an edit to one is a deploy of code nobody
268
+ # reviewed. The check lives in a sibling script so it is testable alone; a
269
+ # missing or broken script fails open, a reported finding blocks.
270
+ if [[ -f "$spec/manifest.tsv" ]]; then
271
+ src_out=$(bash "$(dirname "${BASH_SOURCE[0]}")/check-port-source.sh" --spec-dir "$spec" 2>&1)
272
+ src_rc=$?
273
+ if [[ $src_rc -eq 1 ]]; then
274
+ echo "'Verdict: DONE' claimed but the port touched the tree it reads:" >&2
275
+ echo "$src_out" >&2
276
+ exit 2
277
+ fi
278
+ fi
279
+
280
+ # Per-task acceptance gates (SPEC_DIR/gates.md) stay OUT of this gate on
281
+ # purpose: gate-check.mjs is the single parser of that format, and
282
+ # no spec has used one yet. Wire enforcement in only after a real spec has
283
+ # run with gates and the format has survived contact.
284
+
285
+ exit 0