@tduyng/pi-devos 0.0.0-stage → 0.13.6

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 (138) hide show
  1. package/CHANGELOG.md +1398 -0
  2. package/LICENSE +201 -0
  3. package/README.md +213 -2
  4. package/package.json +45 -4
  5. package/plugins/devos/agents/reader.md +27 -0
  6. package/plugins/devos/agents/verifier.md +181 -0
  7. package/plugins/devos/pi/extension/devos.ts +615 -0
  8. package/plugins/devos/scripts/check-evidence-router.sh +134 -0
  9. package/plugins/devos/scripts/evidence-router.py +252 -0
  10. package/plugins/devos/scripts/gates/check-dod-core.sh +283 -0
  11. package/plugins/devos/scripts/gates/check-dod.sh +38 -0
  12. package/plugins/devos/scripts/gates/check-handoff.sh +215 -0
  13. package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
  14. package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
  15. package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
  16. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +102 -0
  17. package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
  18. package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
  19. package/plugins/devos/scripts/gates/plan-template-check.py +147 -0
  20. package/plugins/devos/scripts/gates/run-gate.sh +148 -0
  21. package/plugins/devos/scripts/gates/spec-template-check.py +165 -0
  22. package/plugins/devos/scripts/gates/test-gates.sh +4306 -0
  23. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
  24. package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
  25. package/plugins/devos/skills/absorb/SKILL.md +75 -0
  26. package/plugins/devos/skills/absorb/references/distill.md +67 -0
  27. package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
  28. package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
  29. package/plugins/devos/skills/build/SKILL.md +71 -0
  30. package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
  31. package/plugins/devos/skills/build/references/defect.md +17 -0
  32. package/plugins/devos/skills/build/references/exposure.md +28 -0
  33. package/plugins/devos/skills/build/references/hard.md +39 -0
  34. package/plugins/devos/skills/build/references/refactor.md +66 -0
  35. package/plugins/devos/skills/build/references/routes.md +56 -0
  36. package/plugins/devos/skills/build/references/scale.md +84 -0
  37. package/plugins/devos/skills/build/references/spike.md +19 -0
  38. package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
  39. package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
  40. package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
  41. package/plugins/devos/skills/build/scripts/route.sh +5 -0
  42. package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
  43. package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
  44. package/plugins/devos/skills/design-taste/SKILL.md +55 -0
  45. package/plugins/devos/skills/design-taste/references/tells.md +85 -0
  46. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +305 -0
  47. package/plugins/devos/skills/docs/SKILL.md +22 -0
  48. package/plugins/devos/skills/docs/references/backfill.md +54 -0
  49. package/plugins/devos/skills/docs/references/init.md +43 -0
  50. package/plugins/devos/skills/docs/references/status.md +71 -0
  51. package/plugins/devos/skills/docs/references/update.md +80 -0
  52. package/plugins/devos/skills/explain/SKILL.md +45 -0
  53. package/plugins/devos/skills/explain/references/quiz.md +21 -0
  54. package/plugins/devos/skills/frame/SKILL.md +71 -0
  55. package/plugins/devos/skills/frame/references/boundaries.md +53 -0
  56. package/plugins/devos/skills/frame/references/decompose.md +96 -0
  57. package/plugins/devos/skills/frame/references/impact.md +43 -0
  58. package/plugins/devos/skills/frame/references/interrogate.md +68 -0
  59. package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
  60. package/plugins/devos/skills/implement/SKILL.md +36 -0
  61. package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
  62. package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
  63. package/plugins/devos/skills/implement/references/dod.md +32 -0
  64. package/plugins/devos/skills/implement/references/implement.md +52 -0
  65. package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
  66. package/plugins/devos/skills/implement/references/plan.md +160 -0
  67. package/plugins/devos/skills/implement/references/resume.md +9 -0
  68. package/plugins/devos/skills/implement/references/scale.md +86 -0
  69. package/plugins/devos/skills/implement/references/verify-close.md +61 -0
  70. package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
  71. package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
  72. package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
  73. package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
  74. package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
  75. package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
  76. package/plugins/devos/skills/implement/scripts/validate-spec.sh +268 -0
  77. package/plugins/devos/skills/init/SKILL.md +100 -0
  78. package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
  79. package/plugins/devos/skills/init/references/context.md +42 -0
  80. package/plugins/devos/skills/init/references/conventions-template.md +153 -0
  81. package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
  82. package/plugins/devos/skills/init/references/rule-format.md +58 -0
  83. package/plugins/devos/skills/init/references/shape-model.md +29 -0
  84. package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
  85. package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
  86. package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
  87. package/plugins/devos/skills/learn/SKILL.md +29 -0
  88. package/plugins/devos/skills/learn/references/destinations.md +43 -0
  89. package/plugins/devos/skills/learn/references/scoring.md +26 -0
  90. package/plugins/devos/skills/product/SKILL.md +40 -0
  91. package/plugins/devos/skills/product/references/planner.md +54 -0
  92. package/plugins/devos/skills/review/SKILL.md +77 -0
  93. package/plugins/devos/skills/review/references/gaps.md +26 -0
  94. package/plugins/devos/skills/spec/SKILL.md +58 -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 +143 -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 +282 -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
  110. package/plugins/devos/skills/surgical-diff/SKILL.md +23 -0
  111. package/plugins/devos/skills/test-integrity/SKILL.md +26 -0
  112. package/plugins/devos/skills/verification-evidence/SKILL.md +17 -0
  113. package/plugins/devos/workflows/common/backlog-file-structure.md +44 -0
  114. package/plugins/devos/workflows/common/category-file-structure.md +41 -0
  115. package/plugins/devos/workflows/common/feature-line-format.md +10 -0
  116. package/plugins/devos/workflows/common/roadmap-file-structure.md +51 -0
  117. package/plugins/devos/workflows/common/suggest-categories.md +76 -0
  118. package/plugins/devos/workflows/common/suggest-milestones.md +92 -0
  119. package/plugins/devos/workflows/doc/doc-health.md +137 -0
  120. package/plugins/devos/workflows/doc/doc-writer.md +44 -0
  121. package/plugins/devos/workflows/doc/init-documentation.md +196 -0
  122. package/plugins/devos/workflows/doc/retro-documentation.md +304 -0
  123. package/plugins/devos/workflows/doc/templates/library.md +58 -0
  124. package/plugins/devos/workflows/doc/templates/service.md +61 -0
  125. package/plugins/devos/workflows/doc/update-documentation.md +194 -0
  126. package/plugins/devos/workflows/doc/write-documentation.md +137 -0
  127. package/plugins/devos/workflows/product/create-product-mission.md +45 -0
  128. package/plugins/devos/workflows/product/create-product-roadmap.md +106 -0
  129. package/plugins/devos/workflows/product/create-product-tech-stack.md +19 -0
  130. package/plugins/devos/workflows/product/gather-product-info.md +25 -0
  131. package/plugins/devos/workflows/product/resume-detection.md +70 -0
  132. package/plugins/devos/workflows/product/reverse-backlog.md +118 -0
  133. package/plugins/devos/workflows/product/reverse-domain-model.md +86 -0
  134. package/plugins/devos/workflows/product/reverse-product-plan.md +81 -0
  135. package/plugins/devos/workflows/product/reverse-tech-stack.md +73 -0
  136. package/plugins/devos/workflows/product/scan-deep.md +113 -0
  137. package/plugins/devos/workflows/product/scan-git.md +122 -0
  138. package/plugins/devos/workflows/product/scan-light.md +154 -0
@@ -0,0 +1,184 @@
1
+ #!/bin/bash
2
+ # convention-usage.sh: which conventions.md entries archived capsules actually
3
+ # exercised. Zero model calls, grep and sed only.
4
+ #
5
+ # Why this exists: DevOS can add to conventions.md forever and has no signal
6
+ # for removing anything, so the file only grows and every plan-time read pays
7
+ # for the dead entries. A convention that mattered got embedded into a spec.md
8
+ # capsule at plan time. That embedding is the usage record, already on disk.
9
+ #
10
+ # What it can and cannot see. Capsules paraphrase conventions, they do not quote
11
+ # them, so matching bullet text is hopeless. What survives paraphrase is the
12
+ # identifiers: a convention about test-gates.sh says "test-gates.sh" and so does
13
+ # the capsule that obeyed it. So each entry is keyed on its backticked
14
+ # file/path-shaped spans, and an entry with none of those cannot be measured
15
+ # this way at all. Those are reported as UNMEASURABLE, never as unused: a
16
+ # prose-only convention ("one logical change per commit") is invisible here and
17
+ # saying nothing about it is the honest output.
18
+ #
19
+ # CITED an identifier of this entry appears in >=1 archived capsule
20
+ # UNCITED it has identifiers and none appear in any capsule
21
+ # UNMEASURABLE no file/path-shaped identifier to key on
22
+ #
23
+ # UNCITED is a prompt to re-read the entry, never an instruction to delete it.
24
+ # A convention can be load-bearing precisely because it is always obeyed and
25
+ # therefore never discussed. Exit is always 0: this reports, it does not gate.
26
+ #
27
+ # Below MIN_CAPSULES archived capsules the ratio means nothing and the script
28
+ # says INSUFFICIENT DATA instead of guessing (same floor and same wording as
29
+ # quality-correlation.sh).
30
+ set -u
31
+
32
+ MIN_CAPSULES=5
33
+
34
+ REPO_DIR="${1:-.}"
35
+ cd "$REPO_DIR" || { echo "FAIL convention-usage: no such directory: $REPO_DIR" >&2; exit 1; }
36
+
37
+ CONVENTIONS="devos/standards/conventions.md"
38
+ ARCHIVE_DIR="devos/specs/archive"
39
+
40
+ if [[ ! -f "$CONVENTIONS" ]]; then
41
+ echo "No $CONVENTIONS yet (nothing onboarded)."
42
+ exit 0
43
+ fi
44
+
45
+ capsules=$(find "$ARCHIVE_DIR" -mindepth 2 -maxdepth 2 -name 'spec.md' 2>/dev/null | sort)
46
+ capsule_count=$(printf '%s' "$capsules" | grep -c . || true)
47
+
48
+ echo "# Convention Usage"
49
+ echo ""
50
+
51
+ if [[ "$capsule_count" -lt "$MIN_CAPSULES" ]]; then
52
+ echo "INSUFFICIENT DATA: only $capsule_count archived capsule(s) found (need at least $MIN_CAPSULES)"
53
+ exit 0
54
+ fi
55
+
56
+ echo "Source: $capsule_count archived capsule(s) in $ARCHIVE_DIR"
57
+ echo ""
58
+
59
+ # One haystack for every capsule; each entry is tested against all of them.
60
+ # Read the paths one line at a time rather than handing them to cat as one
61
+ # word-split argument list. A spec name is a free-form slug, so a directory may
62
+ # contain a space, and the unquoted form then split the path into two arguments
63
+ # that both failed to open, with stderr discarded: the capsule was dropped from
64
+ # the search and every entry only it mentioned came out UNCITED.
65
+ haystack=$(while IFS= read -r capsule; do
66
+ [[ -n "$capsule" ]] && cat -- "$capsule"
67
+ done <<<"$capsules" 2>/dev/null)
68
+
69
+ cited=0 uncited=0 unmeasurable=0
70
+ loose_rows="" uncited_rows=""
71
+ section=""
72
+
73
+ while IFS= read -r line || [[ -n "$line" ]]; do
74
+ # Track the nearest heading so a row can say where the entry lives.
75
+ if [[ "$line" =~ ^##[[:space:]]+(.*) ]]; then
76
+ section="${BASH_REMATCH[1]}"
77
+ continue
78
+ fi
79
+ # Only top-level bullets are entries; continuation lines belong to the one
80
+ # above. Both markdown bullet markers count: a convention written `* foo`
81
+ # is the same entry as one written `- foo`, and matching only the dash
82
+ # dropped it from every class and from the total, so a file with two
83
+ # entries reported one.
84
+ if [[ "$line" =~ ^-[[:space:]]+ ]]; then
85
+ entry="${line#- }"
86
+ elif [[ "$line" =~ ^\*[[:space:]]+ ]]; then
87
+ entry="${line#\* }"
88
+ else
89
+ continue
90
+ fi
91
+ # Backticked spans that look like a file or a path: foo.sh, a/b, dir/f.md.
92
+ ids=$(grep -o '`[^`]*`' <<<"$entry" 2>/dev/null \
93
+ | tr -d '`' \
94
+ | grep -oE '[A-Za-z0-9_.-]+/[A-Za-z0-9_./-]+|[A-Za-z0-9_-]+\.[A-Za-z]{1,4}' \
95
+ | sort -u)
96
+
97
+ # Label: the entry's first 60 chars, backticks and pipes stripped so the
98
+ # markdown table cannot be broken by the content it quotes.
99
+ label=$(printf '%s' "$entry" | tr -d '`|' | cut -c1-60)
100
+
101
+ if [[ -z "$ids" ]]; then
102
+ unmeasurable=$((unmeasurable + 1))
103
+ continue
104
+ fi
105
+
106
+ # Two passes, strongest first. A convention naming a full path is satisfied
107
+ # by a capsule that mentions only the file, so the basename is a legitimate
108
+ # fallback — but a generic basename would match every capsule and report a
109
+ # dead convention as live, so those are skipped and the match kind is shown.
110
+ hit="" hit_kind=""
111
+ while IFS= read -r id; do
112
+ [[ -n "$id" ]] || continue
113
+ if grep -qF -- "$id" <<<"$haystack"; then
114
+ hit="$id" hit_kind="path"
115
+ break
116
+ fi
117
+ done <<<"$ids"
118
+
119
+ if [[ -z "$hit" ]]; then
120
+ while IFS= read -r id; do
121
+ [[ "$id" == */* ]] || continue
122
+ base="${id##*/}"
123
+ [[ "${#base}" -ge 6 ]] || continue
124
+ case "$base" in
125
+ spec.md | notes.md | index.* | README.md | AGENTS.md | \
126
+ decisions.md | conventions.md | domain-model.md | package.json | \
127
+ verification.md | spec-functional.md) continue ;;
128
+ esac
129
+ if grep -qF -- "$base" <<<"$haystack"; then
130
+ hit="$base" hit_kind="name"
131
+ break
132
+ fi
133
+ done <<<"$ids"
134
+ fi
135
+
136
+ if [[ -n "$hit" ]]; then
137
+ cited=$((cited + 1))
138
+ # Only the basename matches are listed: a full-path hit is unambiguous,
139
+ # a basename hit is the one a reader may want to sanity-check.
140
+ [[ "$hit_kind" == "name" ]] &&
141
+ loose_rows="${loose_rows}| ${section} | ${label} | ${hit} |"$'\n'
142
+ else
143
+ uncited=$((uncited + 1))
144
+ first_id=$(head -1 <<<"$ids")
145
+ uncited_rows="${uncited_rows}| ${section} | ${label} | ${first_id} |"$'\n'
146
+ fi
147
+ done <"$CONVENTIONS"
148
+
149
+ total=$((cited + uncited + unmeasurable))
150
+ echo "| Class | Entries |"
151
+ echo "|---|---|"
152
+ echo "| CITED | $cited |"
153
+ echo "| UNCITED | $uncited |"
154
+ echo "| UNMEASURABLE | $unmeasurable |"
155
+ echo "| Total entries | $total |"
156
+ echo ""
157
+
158
+ if [[ "$uncited" -gt 0 ]]; then
159
+ echo "## UNCITED"
160
+ echo ""
161
+ echo "No capsule mentions these entries' identifiers. Re-read each one: still true and"
162
+ echo "load-bearing, or a leftover the map or a scoped rule now covers?"
163
+ echo ""
164
+ echo "| Section | Entry | Looked for |"
165
+ echo "|---|---|---|"
166
+ printf '%s' "$uncited_rows"
167
+ echo ""
168
+ fi
169
+
170
+ if [[ -n "$loose_rows" ]]; then
171
+ echo "## CITED by filename only"
172
+ echo ""
173
+ echo "Matched on the basename, not the full path the entry names. Worth a glance:"
174
+ echo "a common filename can match a capsule that had nothing to do with this entry."
175
+ echo ""
176
+ echo "| Section | Entry | Matched |"
177
+ echo "|---|---|---|"
178
+ printf '%s' "$loose_rows"
179
+ echo ""
180
+ fi
181
+
182
+ if [[ "$unmeasurable" -gt 0 ]]; then
183
+ echo "$unmeasurable entry(s) carry no file-shaped identifier and were not assessed."
184
+ fi
@@ -0,0 +1,112 @@
1
+ #!/bin/bash
2
+ # Findings summary: reads devos/deferred.md and reports statistics.
3
+ # Deterministic, zero model calls.
4
+ #
5
+ # Reports: total specs completed, total findings, findings by severity,
6
+ # findings by resolution type, trend over time (finding count per month),
7
+ # and how often the zero-findings rule triggered.
8
+ #
9
+ # Usage: findings-summary.sh [project-root]
10
+ # project-root defaults to pwd (the user's project directory).
11
+ set -u
12
+ PROJECT_ROOT="${1:-$(pwd)}"
13
+ DEFERRED="$PROJECT_ROOT/devos/deferred.md"
14
+
15
+ if [[ ! -f "$DEFERRED" ]] || [[ ! -s "$DEFERRED" ]]; then
16
+ echo "No findings data yet — no specs have completed this session."
17
+ exit 0
18
+ fi
19
+
20
+ # A ledger is append-only, but it may also contain a heading, blank lines, or
21
+ # explanatory prose. Count records only. The documented record shape is a
22
+ # bracketed spec/date, a bracketed severity, and one of the four resolutions,
23
+ # with or without brackets around the resolution.
24
+ FINDING_RE='^[[:space:]]*(-[[:space:]]*|\*[[:space:]]*)?\[[^]]+\][[:space:]]+\[[[:space:]]*(critical|warning|suggestion)\][[:space:]]+\[?(patch|spec-amendment|defer|reject)\]?[[:space:]]*:'
25
+ records=$(grep -E "$FINDING_RE" "$DEFERRED" 2>/dev/null || true)
26
+
27
+ severity_count() {
28
+ printf '%s\n' "$records" | grep -Ec "\\][[:space:]]+\\[$1\\]" 2>/dev/null || true
29
+ }
30
+
31
+ resolution_count() {
32
+ printf '%s\n' "$records" | grep -Ec "\\[[[:space:]]*(critical|warning|suggestion)\\][[:space:]]+\\[?$1\\]?[[:space:]]*:" 2>/dev/null || true
33
+ }
34
+
35
+ total=$(printf '%s\n' "$records" | awk 'NF { n++ } END { print n + 0 }')
36
+ critical=$(severity_count critical)
37
+ warning=$(severity_count warning)
38
+ suggestion=$(severity_count suggestion)
39
+ patch=$(resolution_count patch)
40
+ spec_amend=$(resolution_count spec-amendment)
41
+ defer=$(resolution_count defer)
42
+ reject=$(resolution_count reject)
43
+
44
+ echo "Findings summary from devos/deferred.md:"
45
+ echo "| Metric | Count |"
46
+ echo "|---|---|"
47
+ echo "| Total findings | $total |"
48
+ echo "| By severity: critical | $critical |"
49
+ echo "| By severity: warning | $warning |"
50
+ echo "| By severity: suggestion | $suggestion |"
51
+ echo "| By resolution: patch | $patch |"
52
+ echo "| By resolution: spec-amendment | $spec_amend |"
53
+ echo "| By resolution: defer | $defer |"
54
+ echo "| By resolution: reject | $reject |"
55
+
56
+ # Trend: finding count per month (from filename dates in the log entries if present, otherwise from file mtime)
57
+ echo ""
58
+ echo "Trend (findings per month):"
59
+ # The month comes from the record's leading bracketed field only. Scanning the
60
+ # whole record also matched months named in the message, so one January finding
61
+ # that mentions an earlier month was reported under both.
62
+ monthly=$(printf '%s\n' "$records" | sed -nE 's/^[[:space:]]*(-[[:space:]]*|\*[[:space:]]*)?\[([^]]+)\].*/\2/p' \
63
+ | grep -oE '^[0-9]{4}-[0-9]{2}' 2>/dev/null | sort | uniq -c | sort -r)
64
+ if [[ -n "$monthly" ]]; then
65
+ while IFS=' ' read -r count month; do
66
+ echo " $month: $count findings"
67
+ done <<<"$monthly"
68
+ else
69
+ # Fall back to file modification time grouping
70
+ echo " No date stamps in deferred.md entries; trend data unavailable."
71
+ fi
72
+
73
+ # Zero findings rule measurement: count L-route specs whose deferred entry says
74
+ # "zero findings on first run".
75
+ #
76
+ # Count specs, not ledger lines. Two findings for one spec are still one spec,
77
+ # and the denominator is completed specs, so counting records here produced
78
+ # "3 of 2 completed specs": a ratio no set of specs can have. The route filter
79
+ # the sentence already claims is applied here too, read from the spec's own
80
+ # archived .quality.md row, so an M-route spec cannot inflate an L-only rule.
81
+ archive_dir="$(dirname "$DEFERRED")/specs/archive"
82
+ zero_findings=0
83
+ zero_seen=""
84
+ while IFS= read -r rec; do
85
+ [[ -n "$rec" ]] || continue
86
+ rec_spec=$(printf '%s' "$rec" | sed -nE 's/^[[:space:]]*[-*][[:space:]]*\[([^]]+)\].*/\1/p')
87
+ [[ -n "$rec_spec" ]] || continue
88
+ # The rule measures a clean first pass, so the record has to say so. A
89
+ # message that merely mentions an absence ("no findings were observed") is
90
+ # prose about the run, not a claim that the first pass came back clean, and
91
+ # counting it turned an absence into a measurement.
92
+ printf '%s' "$rec" | grep -qiE 'first[[:space:]]+(run|pass|attempt|try)' || continue
93
+ case " $zero_seen " in *" $rec_spec "*) continue ;; esac
94
+ qrow="$archive_dir/$rec_spec.quality.md"
95
+ [[ -f "$qrow" ]] || continue
96
+ rec_route=$(awk -F'\t' 'NF >= 2 { print toupper($2); exit }' "$qrow" 2>/dev/null)
97
+ [[ "$rec_route" == "L" ]] || continue
98
+ zero_seen="$zero_seen $rec_spec"
99
+ zero_findings=$((zero_findings + 1))
100
+ done < <(printf '%s\n' "$records" | grep -iE 'zero.*findings|no findings' 2>/dev/null || true)
101
+ # Denominator is archived specs, not findings. $total counts parsed records, so
102
+ # reporting "N of $total completed specs" cannot mistake ledger lines for specs.
103
+ specs=0
104
+ [[ -d "$archive_dir" ]] && specs=$(find "$archive_dir" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
105
+ echo ""
106
+ if ((specs > 0)); then
107
+ echo "Zero-findings rule: $zero_findings of $specs completed specs triggered a re-run (zero findings on first pass)."
108
+ else
109
+ echo "Zero-findings rule: no completed specs to measure."
110
+ fi
111
+
112
+ exit 0
@@ -0,0 +1,282 @@
1
+ #!/bin/bash
2
+ # quality-correlation.sh: reads tab-separated .quality.md files from devos/specs/archive/,
3
+ # prints findings-per-route averages and an S/M/L routing confusion matrix.
4
+ # Pure awk, zero model calls.
5
+ #
6
+ # .quality.md format (tab-separated):
7
+ # spec-name route validate-pass finding-count severity dod-pass [triage-loops] [audit-hits] [understanding]
8
+ # route: S|M|L|C
9
+ # validate-pass: yes|no
10
+ # finding-count: integer
11
+ # severity: none|suggestion|warning|critical
12
+ # dod-pass: yes|no
13
+ # triage-loops: integer, or ? when the row predates the column
14
+ # audit-hits: hits/findings (e.g. 2/5), -/0 when the audit was clean,
15
+ # ?/N when the row predates the column and only N is known
16
+ # understanding: debt (the run hid work from the engineer: a worktree, or a
17
+ # summary standing in for the code), explained (/devos:explain was run on it since), or
18
+ # - (neither applied). Absent on rows predating the column.
19
+ #
20
+ # Columns 7, 8 and 9 are optional: rows written before they existed are shorter
21
+ # and are counted for everything the first six answer. An unknown value is
22
+ # excluded from its average rather than read as zero, which is the difference
23
+ # between "we did not measure this" and "this measured zero".
24
+ set -u
25
+
26
+ REPO_DIR="${1:-.}"
27
+ cd "$REPO_DIR" || { echo "FAIL quality-correlation: no such directory: $REPO_DIR" >&2; exit 1; }
28
+
29
+ QUALITY_DIR="devos/specs/archive"
30
+ if [[ ! -d "$QUALITY_DIR" ]]; then
31
+ echo "INSUFFICIENT DATA: $QUALITY_DIR does not exist"
32
+ exit 0
33
+ fi
34
+
35
+ # Count files, non-empty rows, and rows the parser can actually use. The
36
+ # report denominator must match the parser, not the number of files on disk.
37
+ file_count=$(find "$QUALITY_DIR" -name '*.quality.md' 2>/dev/null | wc -l | tr -d ' ')
38
+ row_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk 'NF { n++ } END { print n + 0 }' {} +)
39
+ valid_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk -F '\t' 'NF >= 6 && $3 ~ /^(yes|no)$/ && $4 ~ /^[0-9]+$/ && $5 ~ /^(none|suggestion|warning|critical)$/ && $6 ~ /^(yes|no)$/ && (NF < 9 || $9 ~ /^(debt|explained|-)$/) { n++ } END { print n + 0 }' {} +)
40
+ invalid_finding_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk -F '\t' 'NF >= 6 && $4 !~ /^[0-9]+$/ { n++ } END { print n + 0 }' {} +)
41
+ invalid_validate_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk -F '\t' 'NF >= 6 && $3 !~ /^(yes|no)$/ { n++ } END { print n + 0 }' {} +)
42
+ invalid_severity_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk -F '\t' 'NF >= 6 && $5 !~ /^(none|suggestion|warning|critical)$/ { n++ } END { print n + 0 }' {} +)
43
+ invalid_dod_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk -F '\t' 'NF >= 6 && $6 !~ /^(yes|no)$/ { n++ } END { print n + 0 }' {} +)
44
+ invalid_understanding_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk -F '\t' 'NF >= 9 && $9 !~ /^(debt|explained|-)$/ { n++ } END { print n + 0 }' {} +)
45
+ invalid_triage_count=$(find "$QUALITY_DIR" -name '*.quality.md' -exec awk -F '\t' 'NF >= 7 && $7 !~ /^([0-9]+|\?)$/ { n++ } END { print n + 0 }' {} +)
46
+ row_count=${row_count:-0}
47
+ valid_count=${valid_count:-0}
48
+ invalid_finding_count=${invalid_finding_count:-0}
49
+ invalid_validate_count=${invalid_validate_count:-0}
50
+ invalid_severity_count=${invalid_severity_count:-0}
51
+ invalid_dod_count=${invalid_dod_count:-0}
52
+ invalid_understanding_count=${invalid_understanding_count:-0}
53
+ invalid_triage_count=${invalid_triage_count:-0}
54
+ skipped_count=$(find "$QUALITY_DIR" -name '*.quality.md' 2>/dev/null -exec awk -F '\t' 'NF && NF < 6 { n++ } END { print n + 0 }' {} +)
55
+ skipped_count=${skipped_count:-0}
56
+
57
+ if [[ "$valid_count" -lt 5 ]]; then
58
+ echo "INSUFFICIENT DATA: only $valid_count valid quality rows found (need at least 5)"
59
+ exit 0
60
+ fi
61
+
62
+ echo "# Quality Correlation Report"
63
+ echo ""
64
+ echo "Source: $QUALITY_DIR"
65
+ echo "Quality files: $file_count"
66
+ echo "Specs analyzed: $valid_count"
67
+ if [[ "$skipped_count" -gt 0 ]]; then
68
+ echo "Skipped quality rows: $skipped_count (fewer than 6 tab-separated fields)"
69
+ fi
70
+ echo ""
71
+
72
+ # Parse tab-separated quality files.
73
+ find "$QUALITY_DIR" -name '*.quality.md' 2>/dev/null -exec awk -v invalid_finding_count="$invalid_finding_count" -v invalid_validate_count="$invalid_validate_count" -v invalid_severity_count="$invalid_severity_count" -v invalid_dod_count="$invalid_dod_count" -v invalid_understanding_count="$invalid_understanding_count" -v invalid_triage_count="$invalid_triage_count" -F'\t' '
74
+ BEGIN {
75
+ route_n = split("S M L C ?", rr, " ")
76
+ for (i = 1; i <= route_n; i++) {
77
+ route_total[rr[i]] = 0; route_count[rr[i]] = 0
78
+ high_sev_by_route[rr[i]] = 0; zero_by_route[rr[i]] = 0
79
+ loop_total[rr[i]] = 0; loop_count[rr[i]] = 0
80
+ }
81
+ total_findings = 0
82
+ total_specs = 0
83
+ audit_hits = 0; audit_found = 0; audit_rows = 0; audit_unknown = 0; audit_invalid = 0
84
+ debt_rows = 0; debt_explained = 0
85
+ }
86
+ {
87
+ if (NF < 6) next
88
+ if ($3 !~ /^(yes|no)$/ || $4 !~ /^[0-9]+$/ || $5 !~ /^(none|suggestion|warning|critical)$/ || $6 !~ /^(yes|no)$/ || (NF >= 9 && $9 !~ /^(debt|explained|-)$/)) next
89
+ route = toupper($2)
90
+ # An unrecognized route is reported as "?", never folded into M: silently
91
+ # defaulting is what hid the producer bug that recorded M for every spec
92
+ #, because the wrong value read as a legitimate one.
93
+ if (route != "S" && route != "M" && route != "L" && route != "C") route = "?"
94
+ findings = $4 + 0
95
+ severity = $5
96
+
97
+ route_total[route] += findings
98
+ route_count[route]++
99
+ total_findings += findings
100
+ total_specs++
101
+
102
+ # Track high-severity findings per route (confusion matrix signals).
103
+ if (severity == "critical" || severity == "warning") {
104
+ high_sev_by_route[route]++
105
+ }
106
+ if (findings == 0) {
107
+ zero_by_route[route]++
108
+ }
109
+
110
+ # Triage loops (column 7). A "?" row predates the column: excluded from the
111
+ # average rather than counted as 0, which would read as a first-pass clean.
112
+ if (NF >= 7 && $7 ~ /^[0-9]+$/) {
113
+ loop_total[route] += $7 + 0
114
+ loop_count[route]++
115
+ }
116
+
117
+ # Audit hit rate (column 8), written hits/findings. "-" means the audit was
118
+ # clean, so there was nothing to hit; "?" means nobody recorded the hits.
119
+ if (NF >= 8 && $8 ~ /\//) {
120
+ audit_parts = split($8, a, "/")
121
+ if (audit_parts != 2) {
122
+ audit_invalid++
123
+ } else if (a[1] == "?" && a[2] ~ /^[0-9]+$/) {
124
+ found = a[2] + 0
125
+ if (found > 0) audit_unknown++
126
+ } else if (a[1] == "-" && a[2] == "0") {
127
+ audit_rows++
128
+ } else if (a[1] ~ /^[0-9]+$/ && a[2] ~ /^[0-9]+$/) {
129
+ if ((a[2] + 0) > 0 && (a[1] + 0) <= (a[2] + 0)) {
130
+ audit_hits += a[1] + 0
131
+ audit_found += a[2] + 0
132
+ audit_rows++
133
+ } else {
134
+ audit_invalid++
135
+ }
136
+ } else {
137
+ audit_invalid++
138
+ }
139
+ } else if (NF >= 8) {
140
+ # A present empty audit field is malformed metadata, not an absent
141
+ # optional column. Keep the row for general metrics, but surface the
142
+ # invalid audit value instead of silently treating it as unrecorded.
143
+ audit_invalid++
144
+ }
145
+
146
+ # Understanding (column 9). Only rows where the run actually hid work from
147
+ # the engineer are counted: a "-" row had no debt to pay back, so folding it
148
+ # in would inflate the rate with specs the question never applied to.
149
+ if (NF >= 9 && ($9 == "debt" || $9 == "explained")) {
150
+ debt_rows++
151
+ if ($9 == "explained") debt_explained++
152
+ }
153
+ }
154
+ END {
155
+ if (total_specs == 0) {
156
+ print "No findings data found in quality files."
157
+ exit 0
158
+ }
159
+ print "## Findings per Route"
160
+ print ""
161
+ printf "%-6s %5s %8s %s\n", "Route", "Specs", "Findings", "Avg"
162
+ printf "%-6s %5s %8s %s\n", "------", "-----", "--------", "---"
163
+ # Walk the declared route list, not the route map. A bare for-in over an
164
+ # associative array has unspecified order, so the tables came out in hash
165
+ # order (C, L, M, S on this awk) and the same report could order its rows
166
+ # differently on another awk. The reader compares routes by size, so the
167
+ # order has to be the one the route list declares.
168
+ for (ri = 1; ri <= route_n; ri++) {
169
+ r = rr[ri]
170
+ if (route_count[r] > 0) {
171
+ avg = route_total[r] / route_count[r]
172
+ printf "%-6s %5d %8d %.1f\n", r, route_count[r], route_total[r], avg
173
+ }
174
+ }
175
+ printf "%-6s %5d %8d %.1f\n", "TOTAL", total_specs, total_findings, total_findings/total_specs
176
+
177
+ print ""
178
+ print "## Routing Confusion Matrix"
179
+ print ""
180
+ printf "%-6s %5s %8s %s\n", "Route", "Specs", "High-Sev", "Zero-Findings"
181
+ printf "%-6s %5s %8s %s\n", "------", "-----", "--------", "------------"
182
+ for (ri = 1; ri <= route_n; ri++) {
183
+ r = rr[ri]
184
+ if (route_count[r] > 0) {
185
+ printf "%-6s %5d %8d %d\n", r, route_count[r], high_sev_by_route[r], zero_by_route[r]
186
+ }
187
+ }
188
+
189
+ print ""
190
+ print "## Triage Loops per Route"
191
+ print ""
192
+ print "How many verify-fix rounds each spec took. 1 is a first-pass clean."
193
+ print "Separates a spec that was hard from a spec that was planned badly."
194
+ print ""
195
+ printf "%-6s %5s %s\n", "Route", "Rows", "Avg loops"
196
+ printf "%-6s %5s %s\n", "------", "-----", "---------"
197
+ any_loops = 0
198
+ for (ri = 1; ri <= route_n; ri++) {
199
+ r = rr[ri]
200
+ if (loop_count[r] > 0) {
201
+ printf "%-6s %5d %.1f\n", r, loop_count[r], loop_total[r] / loop_count[r]
202
+ any_loops = 1
203
+ }
204
+ }
205
+ if (!any_loops) print "(no rows carry a triage-loop count yet)"
206
+
207
+ print ""
208
+ print "## Spec Audit Hit Rate"
209
+ print ""
210
+ print "Audit findings later confirmed by a verifier finding or a decisions.md"
211
+ print "entry naming the same gap. A rate near zero means the audit is being"
212
+ print "paid for and not used."
213
+ print ""
214
+ if (audit_found > 0) {
215
+ printf "%d of %d audit findings confirmed downstream (%.0f%%), across %d spec(s)\n", \
216
+ audit_hits, audit_found, 100 * audit_hits / audit_found, audit_rows
217
+ } else if (audit_rows > 0) {
218
+ printf "no audit findings to confirm across %d spec(s) (every audit was clean)\n", audit_rows
219
+ } else {
220
+ print "(no rows carry an audit hit rate yet)"
221
+ }
222
+ if (audit_unknown > 0) {
223
+ printf "%d spec(s) excluded: audit findings recorded, hits never were\n", audit_unknown
224
+ }
225
+ if (audit_invalid > 0) {
226
+ printf "Invalid audit-hits values: %d (expected -/0, ?/N, or hits/findings)\n", audit_invalid
227
+ }
228
+ if (invalid_finding_count > 0) {
229
+ print "Invalid finding-count values: " invalid_finding_count " (excluded from analysis)"
230
+ }
231
+ if (invalid_validate_count > 0) {
232
+ print "Invalid validate-pass values: " invalid_validate_count " (excluded from analysis)"
233
+ }
234
+ if (invalid_severity_count > 0) {
235
+ print "Invalid severity values: " invalid_severity_count " (excluded from analysis)"
236
+ }
237
+ if (invalid_dod_count > 0) {
238
+ print "Invalid dod-pass values: " invalid_dod_count " (excluded from analysis)"
239
+ }
240
+ if (invalid_understanding_count > 0) {
241
+ print "Invalid understanding values: " invalid_understanding_count " (excluded from analysis)"
242
+ }
243
+ if (invalid_triage_count > 0) {
244
+ print "Invalid triage-loop values: " invalid_triage_count " (excluded from triage averages)"
245
+ }
246
+
247
+ print ""
248
+ print "## Understanding Debt"
249
+ print ""
250
+ print "Specs whose work ran where the engineer could not watch it (a"
251
+ print "worktree, a summary instead of the code), and how many they came back"
252
+ print "to explain. A rate near zero means /devos:explain is not being used."
253
+ print ""
254
+ if (debt_rows > 0) {
255
+ printf "%d of %d spec(s) with hidden work were explained (%.0f%%)\n", \
256
+ debt_explained, debt_rows, 100 * debt_explained / debt_rows
257
+ } else {
258
+ print "(no rows carry an understanding column yet)"
259
+ }
260
+
261
+ print ""
262
+ print "## Signals"
263
+ print ""
264
+ under_routed = 0
265
+ over_routed = 0
266
+ for (ri = 1; ri <= route_n; ri++) {
267
+ r = rr[ri]
268
+ if (route_count[r] > 0 && high_sev_by_route[r] > 0) {
269
+ printf "%d %s spec(s) with high-severity findings (potential under-routes)\n", high_sev_by_route[r], r
270
+ under_routed += high_sev_by_route[r]
271
+ }
272
+ if (route_count[r] > 0 && zero_by_route[r] > 0) {
273
+ printf "%d %s spec(s) with zero findings (potential over-routes)\n", zero_by_route[r], r
274
+ over_routed += zero_by_route[r]
275
+ }
276
+ }
277
+ if (under_routed == 0 && over_routed == 0) {
278
+ print "(no routing signals detected)"
279
+ }
280
+ print ""
281
+ print "(Manual review required: this report surfaces signals, not verdicts.)"
282
+ }' {} +
@@ -0,0 +1,71 @@
1
+ #!/bin/bash
2
+ # Sizing calibration: compares the router's size call against what the plan
3
+ # capsule actually contained, across active and archived specs.
4
+ # Deterministic, zero model calls.
5
+ #
6
+ # The router states a size (S/M/L) before routing; implement logs it as the
7
+ # `started` event's detail. The capsule records reality as task groups. A
8
+ # repeated mismatch in one direction is a prompt-fix candidate for the build
9
+ # skill's sizing table, which is the whole point of this report: it turns
10
+ # "the router keeps getting X wrong" from an impression into a count.
11
+ #
12
+ # Advisory only: always exits 0. Specs whose `started` detail carries no
13
+ # standalone S/M/L token are skipped silently (resume details, older runs).
14
+ #
15
+ # Usage: sizing-calibration.sh [project-root]
16
+ set -u
17
+ PROJECT_ROOT="${1:-$(pwd)}"
18
+ SPECS="$PROJECT_ROOT/devos/specs"
19
+
20
+ [[ -d "$SPECS" ]] || { echo "No devos/specs yet - nothing to calibrate."; exit 0; }
21
+
22
+ ok=0 undersized=0 oversized=0
23
+
24
+ for ops in "$SPECS"/*/ops.jsonl "$SPECS"/archive/*/ops.jsonl; do
25
+ [[ -f "$ops" ]] || continue
26
+ dir="$(dirname "$ops")"
27
+ name="${dir##*/}"
28
+ capsule="$dir/spec.md"
29
+ [[ -f "$capsule" ]] || continue
30
+ detail=$(sed -n 's/.*"event":"started","detail":"\([^"]*\)".*/\1/p' "$ops" | head -1)
31
+ # The size call is a letter standing on its own. A capital inside a path
32
+ # or a file name (src/L.ts, L.md) reads the same way in the raw detail but
33
+ # is not a sizing decision, so the letter must not be glued to a path
34
+ # segment or a file extension. The first letter that stands alone is the
35
+ # call; a detail that only names files carries no size and is skipped.
36
+ size=$(printf '%s' "$detail" |
37
+ grep -oE '(^|[^A-Za-z0-9_./-])[SML]([^A-Za-z0-9_.]|$)' | head -1 |
38
+ grep -oE '[SML]')
39
+ [[ -n "$size" ]] || continue
40
+ groups=$(grep -cE '^###[[:space:]]+Task[[:space:]]+Group' "$capsule")
41
+ case "$size" in
42
+ M)
43
+ if [[ "$groups" -ge 5 ]]; then
44
+ echo "UNDERSIZED $name: sized M, capsule has $groups task groups (L candidate)"
45
+ undersized=$((undersized + 1))
46
+ else
47
+ ok=$((ok + 1))
48
+ fi
49
+ ;;
50
+ L)
51
+ if [[ "$groups" -le 1 ]]; then
52
+ echo "OVERSIZED $name: sized L, capsule has $groups task group(s) (M candidate)"
53
+ oversized=$((oversized + 1))
54
+ else
55
+ ok=$((ok + 1))
56
+ fi
57
+ ;;
58
+ *)
59
+ ok=$((ok + 1))
60
+ ;;
61
+ esac
62
+ done
63
+
64
+ if ((ok + undersized + oversized == 0)); then
65
+ echo "No sizing data yet - specs with a size letter in their started event: none."
66
+ exit 0
67
+ fi
68
+ echo "---"
69
+ echo "calibrated: $ok ok, $undersized under-sized M, $oversized over-sized L"
70
+ echo "repeated mismatches in one direction are a build-skill sizing-table fix candidate"
71
+ exit 0