@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,140 @@
1
+ #!/bin/bash
2
+ # equivalence-check.sh: the judge for a behavior-preserving change.
3
+ #
4
+ # A behavior-preserving change is proven by running the same judgment against
5
+ # the before tree and the after tree and comparing what came back. This script
6
+ # is that comparison, so the proof is a command with an exit status rather than
7
+ # a claim in prose.
8
+ #
9
+ # Two rules make the verdict worth something:
10
+ #
11
+ # - A judge that errored proves nothing. A command that fails on the before
12
+ # tree makes the whole comparison unproven, not equivalent, and a red
13
+ # baseline is a finding of its own.
14
+ # - A judge that has never seen a break does not know what a break looks
15
+ # like. `--self-test` runs the judge against a tree that is deliberately
16
+ # broken and fails when the judge calls it equivalent.
17
+ #
18
+ # Usage:
19
+ # equivalence-check.sh --before DIR --after DIR [--cmd CMD]
20
+ # [--before-cmd CMD --after-cmd CMD] [--label NAME]
21
+ # equivalence-check.sh --self-test
22
+ #
23
+ # Diagnostic envelope (shared by DevOS check scripts):
24
+ # FAIL <check>: <message>
25
+ # fix: <one actionable line>
26
+ # Exit 0 = equivalent, 1 = not equivalent, 2 = usage or unproven.
27
+ set -u
28
+
29
+ die() { echo "FAIL equivalence-check: $1" >&2; echo " fix: $2" >&2; exit 2; }
30
+
31
+ before=""
32
+ after=""
33
+ before_cmd=""
34
+ after_cmd=""
35
+ label="comparison"
36
+ self_test=0
37
+
38
+ while [[ $# -gt 0 ]]; do
39
+ case "$1" in
40
+ --before) before="${2:-}"; shift 2 ;;
41
+ --after) after="${2:-}"; shift 2 ;;
42
+ --cmd) before_cmd="${2:-}"; after_cmd="${2:-}"; shift 2 ;;
43
+ --before-cmd) before_cmd="${2:-}"; shift 2 ;;
44
+ --after-cmd) after_cmd="${2:-}"; shift 2 ;;
45
+ --label) label="${2:-}"; shift 2 ;;
46
+ --self-test) self_test=1; shift ;;
47
+ -h|--help) sed -n '2,28p' "$0"; exit 0 ;;
48
+ *) die "unknown argument: $1" "use --before, --after, --cmd and --self-test as listed in the header" ;;
49
+ esac
50
+ done
51
+
52
+ SELF="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
53
+
54
+ # Run one command in one tree, capturing combined output and the exit status.
55
+ # The output file is left behind when the caller asked to see a diff.
56
+ run_side() {
57
+ local dir="$1" cmd="$2" out="$3"
58
+ ( cd "$dir" && eval "$cmd" ) > "$out" 2>&1
59
+ echo $?
60
+ }
61
+
62
+ # $1 before dir, $2 after dir, $3 before cmd, $4 after cmd, $5 label.
63
+ # Prints the verdict, returns 0 equivalent, 1 not equivalent, 2 unproven.
64
+ judge() {
65
+ local bdir="$1" adir="$2" bcmd="$3" acmd="$4" lbl="$5"
66
+ local tmp bo ao brc arc
67
+ tmp="$(mktemp -d)"
68
+ bo="$tmp/before.out"; ao="$tmp/after.out"
69
+ brc="$(run_side "$bdir" "$bcmd" "$bo")"
70
+ arc="$(run_side "$adir" "$acmd" "$ao")"
71
+ local elapsed=$SECONDS
72
+
73
+ if [[ "$brc" != "0" ]]; then
74
+ echo "UNPROVEN equivalence-check: $lbl failed on the before tree (exit $brc), so the comparison proves nothing"
75
+ echo " fix: the before tree must be green before an equivalence claim is about anything"
76
+ tail -n 5 "$bo" | sed 's/^/ | /'
77
+ rm -rf "$tmp"
78
+ return 2
79
+ fi
80
+ if [[ "$arc" != "0" ]]; then
81
+ echo "FAIL equivalence-check: $lbl fails on the after tree (exit $arc) and passed on the before tree"
82
+ echo " fix: the change broke the judgment; fix the code, or the change is not behavior-preserving"
83
+ tail -n 5 "$ao" | sed 's/^/ | /'
84
+ rm -rf "$tmp"
85
+ return 1
86
+ fi
87
+ if ! cmp -s "$bo" "$ao"; then
88
+ echo "FAIL equivalence-check: $lbl output differs between the trees"
89
+ echo " fix: the difference below is the behavior that moved; restore it or declare the change"
90
+ diff -u "$bo" "$ao" 2>/dev/null | head -n 30 | sed 's/^/ | /'
91
+ rm -rf "$tmp"
92
+ return 1
93
+ fi
94
+ echo "PASS equivalence-check: $lbl is identical in both trees (judged in ${elapsed}s)"
95
+ rm -rf "$tmp"
96
+ return 0
97
+ }
98
+
99
+ if [[ "$self_test" -eq 1 ]]; then
100
+ tmp="$(mktemp -d)"
101
+ trap 'rm -rf "$tmp"' EXIT
102
+ mkdir -p "$tmp/good" "$tmp/broken" "$tmp/red"
103
+ printf '#!/bin/sh\necho "case: ok"\n' > "$tmp/good/judge.sh"
104
+ printf '#!/bin/sh\necho "case: broken"\n' > "$tmp/broken/judge.sh"
105
+ printf '#!/bin/sh\necho "case: boom"\nexit 1\n' > "$tmp/red/judge.sh"
106
+ chmod +x "$tmp"/*/judge.sh
107
+ bad=0
108
+ check() { # $1 expected rc, $2 label, rest: args
109
+ local want="$1" name="$2"; shift 2
110
+ local got=0
111
+ "$SELF" "$@" > "$tmp/out" 2>&1 || got=$?
112
+ if [[ "$got" != "$want" ]]; then
113
+ echo "FAIL equivalence-check: the judge called '$name' exit $got, expected $want"
114
+ echo " fix: a judge that misses a break cannot certify anything; fix the judge before trusting a verdict"
115
+ sed 's/^/ | /' "$tmp/out"
116
+ bad=1
117
+ else
118
+ echo "ok self-test: $name is judged exit $got"
119
+ fi
120
+ }
121
+ check 0 "two identical trees" --before "$tmp/good" --after "$tmp/good" --cmd "./judge.sh"
122
+ check 1 "a broken tree against a good one" --before "$tmp/good" --after "$tmp/broken" --cmd "./judge.sh"
123
+ check 1 "a tree that fails where the other passed" --before "$tmp/good" --after "$tmp/red" --cmd "./judge.sh"
124
+ check 2 "a red baseline on both sides" --before "$tmp/red" --after "$tmp/red" --cmd "./judge.sh"
125
+ if [[ "$bad" -ne 0 ]]; then
126
+ exit 1
127
+ fi
128
+ echo "PASS equivalence-check: the judge catches every break it was shown"
129
+ exit 0
130
+ fi
131
+
132
+ [[ -n "$before" && -n "$after" ]] \
133
+ || die "--before and --after are required" "point them at the two trees the judgment runs in"
134
+ [[ -d "$before" ]] || die "before tree not found: $before" "give the directory holding the code before the change"
135
+ [[ -d "$after" ]] || die "after tree not found: $after" "give the directory holding the code after the change"
136
+ [[ -n "$before_cmd" && -n "$after_cmd" ]] \
137
+ || die "no command to run" "pass --cmd for one command in both trees, or --before-cmd and --after-cmd when the two stacks differ"
138
+
139
+ judge "$before" "$after" "$before_cmd" "$after_cmd" "$label"
140
+ exit $?
@@ -0,0 +1,185 @@
1
+ #!/bin/bash
2
+ # manifest-queue.sh: the unit queue for a behavior-preserving change at scale.
3
+ #
4
+ # The manifest is the unit list, one row per unit: `source<TAB>target`. A unit
5
+ # is done when its target exists and carries content, so the filesystem holds
6
+ # the state and a run resumes for free after a crash, a halt, or a session
7
+ # ending. Nothing else tracks progress, so nothing else can disagree with it.
8
+ #
9
+ # Usage:
10
+ # manifest-queue.sh init --from-root DIR --to DIR --list FILE --out FILE
11
+ # manifest-queue.sh status --manifest FILE
12
+ # manifest-queue.sh next --manifest FILE [--batch N]
13
+ # manifest-queue.sh verify --manifest FILE
14
+ #
15
+ # Diagnostic envelope (shared by DevOS check scripts):
16
+ # FAIL <check>: <message>
17
+ # fix: <one actionable line>
18
+ # Exit 0 = ok, 1 = findings, 2 = usage.
19
+ set -u
20
+ fail=0
21
+ finding() { echo "FAIL manifest-queue: $1"; echo " fix: $2"; fail=1; }
22
+
23
+ die() { echo "FAIL manifest-queue: $1" >&2; echo " fix: $2" >&2; exit 2; }
24
+
25
+ cmd=""
26
+ manifest=""
27
+ from_root=""
28
+ to_root=""
29
+ list=""
30
+ out=""
31
+ batch=10
32
+ count=""
33
+ units=0
34
+
35
+ while [[ $# -gt 0 ]]; do
36
+ case "$1" in
37
+ init|status|next|verify|slice) cmd="$1"; shift ;;
38
+ --manifest) manifest="${2:-}"; shift 2 ;;
39
+ --from-root) from_root="${2:-}"; shift 2 ;;
40
+ --to) to_root="${2:-}"; shift 2 ;;
41
+ --list) list="${2:-}"; shift 2 ;;
42
+ --out) out="${2:-}"; shift 2 ;;
43
+ --batch) batch="${2:-}"; shift 2 ;;
44
+ --count) count="${2:-}"; shift 2 ;;
45
+ -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
46
+ *) die "unknown argument: $1" "use init, status, next, verify or slice with the flags listed in the header" ;;
47
+ esac
48
+ done
49
+ [[ -n "$cmd" ]] || die "no command given" "pass one of: init, status, next, verify"
50
+
51
+ # A unit carries content when it is a non-empty file, or a directory with
52
+ # something in it. An empty target is the failure this queue exists to catch:
53
+ # a worker that touched the file and moved on.
54
+ carries_content() {
55
+ local p="$1"
56
+ [[ -e "$p" ]] || return 1
57
+ if [[ -d "$p" ]]; then
58
+ [[ -n "$(find "$p" -mindepth 1 -print -quit 2>/dev/null)" ]]
59
+ else
60
+ [[ -s "$p" ]]
61
+ fi
62
+ }
63
+
64
+ read_manifest() {
65
+ local f="$1"
66
+ [[ -f "$f" ]] || die "manifest not found: $f" "write it with: manifest-queue.sh init --from-root DIR --to DIR --list FILE --out $f"
67
+ local header
68
+ header="$(head -1 "$f" | tr -d '\r')"
69
+ [[ "$header" == "$(printf 'source\ttarget')" ]] \
70
+ || die "manifest header must be 'source<TAB>target', got: $header" "the header is the contract: one source path and one target path per row"
71
+ }
72
+
73
+ case "$cmd" in
74
+ init)
75
+ [[ -n "$from_root" && -n "$to_root" && -n "$list" && -n "$out" ]] \
76
+ || die "init needs --from-root, --to, --list and --out" "example: manifest-queue.sh init --from-root legacy --to modernized --list units.txt --out devos/specs/x/manifest.tsv"
77
+ [[ -f "$list" ]] || die "list not found: $list" "write one source path per line, relative to --from-root"
78
+ mkdir -p "$(dirname "$out")" || die "cannot create $(dirname "$out")" "create the spec folder first"
79
+ {
80
+ printf 'source\ttarget\n'
81
+ while IFS= read -r rel || [[ -n "$rel" ]]; do
82
+ rel="${rel%%$'\r'}"
83
+ [[ -n "$rel" ]] || continue
84
+ case "$rel" in \#*) continue ;; esac
85
+ printf '%s/%s\t%s/%s\n' "$from_root" "$rel" "$to_root" "$rel"
86
+ done < "$list"
87
+ } > "$out"
88
+ units=$(($(wc -l < "$out") - 1))
89
+ echo "wrote $out ($units units)"
90
+ ;;
91
+
92
+ status)
93
+ [[ -n "$manifest" ]] || die "status needs --manifest" "pass the manifest path"
94
+ read_manifest "$manifest"
95
+ total=0; done=0
96
+ dirs="$(mktemp)"
97
+ while IFS=$'\t' read -r src tgt; do
98
+ [[ "$src" == "source" ]] && continue
99
+ [[ -n "$src" ]] || continue
100
+ total=$((total + 1))
101
+ if carries_content "$tgt"; then
102
+ done=$((done + 1))
103
+ else
104
+ d="$(dirname "$src")"
105
+ printf '%s\n' "$d" >> "$dirs"
106
+ fi
107
+ done < "$manifest"
108
+ pct=0
109
+ [[ "$total" -gt 0 ]] && pct=$((done * 100 / total))
110
+ echo "$done/$total done (${pct}%)"
111
+ if [[ -s "$dirs" ]]; then
112
+ sort "$dirs" | uniq -c | sort -rn | while read -r n d; do
113
+ echo " $d: $n pending"
114
+ done
115
+ fi
116
+ rm -f "$dirs"
117
+ ;;
118
+
119
+ next)
120
+ [[ -n "$manifest" ]] || die "next needs --manifest" "pass the manifest path"
121
+ read_manifest "$manifest"
122
+ n=0
123
+ while IFS=$'\t' read -r src tgt; do
124
+ [[ "$src" == "source" ]] && continue
125
+ [[ -n "$src" ]] || continue
126
+ carries_content "$tgt" && continue
127
+ printf '%s\t%s\n' "$src" "$tgt"
128
+ n=$((n + 1))
129
+ [[ "$n" -ge "$batch" ]] && break
130
+ done < "$manifest"
131
+ ;;
132
+
133
+ slice)
134
+ # A phase of a port takes the first units of the manifest, and the manifest
135
+ # is in dependency order, so a slice is closed under the dependencies: every
136
+ # unit a unit needs is in the slice or in an earlier phase.
137
+ [[ -n "$manifest" && -n "$out" && -n "$count" ]] \
138
+ || die "slice needs --manifest, --count and --out" "example: manifest-queue.sh slice --manifest SPEC/manifest.tsv --count 40 --out SPEC/phase-1.tsv"
139
+ read_manifest "$manifest"
140
+ [[ "$count" =~ ^[0-9]+$ ]] || die "count must be a number, got: $count" "pass how many units the phase holds"
141
+ {
142
+ printf 'source\ttarget\n'
143
+ taken=0
144
+ while IFS=$'\t' read -r src tgt; do
145
+ [[ "$src" == "source" ]] && continue
146
+ [[ -n "$src" ]] || continue
147
+ if [[ "$taken" -ge "$count" ]]; then
148
+ break
149
+ fi
150
+ printf '%s\t%s\n' "$src" "$tgt"
151
+ taken=$((taken + 1))
152
+ done < "$manifest"
153
+ } > "$out"
154
+ units=$(($(wc -l < "$out") - 1))
155
+ echo "wrote $out ($units units of the first $count)"
156
+ ;;
157
+
158
+ verify)
159
+ [[ -n "$manifest" ]] || die "verify needs --manifest" "pass the manifest path"
160
+ read_manifest "$manifest"
161
+ empty=0; missing=0
162
+ while IFS=$'\t' read -r src tgt; do
163
+ [[ "$src" == "source" ]] && continue
164
+ [[ -n "$src" ]] || continue
165
+ if [[ -z "$tgt" ]]; then
166
+ finding "a row names no target: $src" "every row names a source and a target"
167
+ missing=$((missing + 1))
168
+ continue
169
+ fi
170
+ if [[ -e "$tgt" ]] && ! carries_content "$tgt"; then
171
+ finding "target exists but carries nothing: $tgt" "write the unit, or drop the row from the manifest"
172
+ empty=$((empty + 1))
173
+ fi
174
+ if [[ ! -e "$src" ]]; then
175
+ finding "source is missing: $src" "the unit points at nothing; fix the row or drop it"
176
+ missing=$((missing + 1))
177
+ fi
178
+ done < "$manifest"
179
+ if [[ "$empty" -eq 0 && "$missing" -eq 0 ]]; then
180
+ echo "PASS manifest-queue: every unit has a source and a target that carries content"
181
+ fi
182
+ ;;
183
+ esac
184
+
185
+ exit $fail
@@ -0,0 +1,58 @@
1
+ #!/bin/bash
2
+ # ops-log.sh SPEC_DIR event [detail]: append one line to SPEC_DIR/ops.jsonl.
3
+ #
4
+ # The pipeline's own timeline. Filesystem-derived state says which artifacts
5
+ # exist; it cannot say when each phase happened or in what order a resumed run
6
+ # actually went. ops.jsonl is that record, and /devos:explain plus implement's
7
+ # resume detection read it instead of reconstructing.
8
+ #
9
+ # Fixed event vocabulary so readers match on names:
10
+ # started | plan-approved | implemented | verified | closed | note
11
+ #
12
+ # Appends are serialized with a mkdir lock (portable: darwin ships no flock(1)).
13
+ # Each line is one small write under that lock, so two sessions logging at the
14
+ # same moment cannot interleave into torn JSON.
15
+ set -u
16
+
17
+ usage="Usage: $0 SPEC_DIR <started|plan-approved|implemented|verified|closed|note> [detail]"
18
+
19
+ [[ $# -ge 2 ]] || { echo "$usage" >&2; exit 2; }
20
+ dir="$1"; event="$2"; detail="${3:-}"
21
+
22
+ case "$event" in
23
+ started|plan-approved|implemented|verified|closed|note) ;;
24
+ *) echo "$usage" >&2; exit 2 ;;
25
+ esac
26
+ case "$detail" in
27
+ *$'\n'*|*$'\r'*) echo "detail must be a single line" >&2; exit 2 ;;
28
+ esac
29
+
30
+ # JSON strings cannot contain raw control characters. Newline and carriage
31
+ # return are rejected above because they would also break the one-record-per-line
32
+ # format. Escape the other C0 controls before writing the JSON value.
33
+ detail=${detail//\\/\\\\}
34
+ detail=${detail//\"/\\\"}
35
+ printf -v backspace_escape '\\b'
36
+ printf -v formfeed_escape '\\f'
37
+ printf -v tab_escape '\\t'
38
+ detail=${detail//$'\b'/"$backspace_escape"}
39
+ detail=${detail//$'\f'/"$formfeed_escape"}
40
+ detail=${detail//$'\t'/"$tab_escape"}
41
+ for control_code in {1..31}; do
42
+ case "$control_code" in
43
+ 8|9|10|12|13) continue ;;
44
+ esac
45
+ printf -v control_char '\\%03o' "$control_code"
46
+ printf -v json_escape '\\u%04x' "$control_code"
47
+ detail=${detail//"$control_char"/"$json_escape"}
48
+ done
49
+
50
+ mkdir -p "$dir" || exit 1
51
+ file="$dir/ops.jsonl"
52
+ lock="$dir/.ops.lock"
53
+
54
+ while ! mkdir "$lock" 2>/dev/null; do sleep 0.05; done
55
+ trap 'rmdir "$lock" 2>/dev/null' EXIT
56
+
57
+ at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
58
+ printf '{"at":"%s","event":"%s","detail":"%s"}\n' "$at" "$event" "$detail" >> "$file"
@@ -0,0 +1,173 @@
1
+ #!/usr/bin/env python3
2
+ """pilot-consistency: did the same rulebook produce the same port three times?
3
+
4
+ A port's rulebook decides every unit after the first three, so the first three
5
+ are the pilot. Two of them coming out the same way is not evidence that the
6
+ rulebook is right, it is evidence that one rule was applied the same way twice.
7
+ The question the pilot has to answer is the other one: where the units
8
+ disagree, the rulebook is missing a rule or has a vague one, and the fan-out
9
+ to the remaining units would spread that defect.
10
+
11
+ The disagreement is found without a second translator. Every unit's source and
12
+ target are reduced to the same handful of structural roles, and the roles are
13
+ compared across the units. Only the units whose source holds the role are
14
+ compared, because a unit with no exception site decides nothing about
15
+ exceptions, and comparing it against a unit that has one says nothing.
16
+
17
+ One disagreement is a finding: a site the source had is gone in one unit and
18
+ there in another. The same kind of site came out two ways, so the rule that
19
+ decides it is not written down, or is written down badly. A softer difference,
20
+ the same kind of site kept in both units but in different numbers, is printed
21
+ as a note, because a language can legitimately need a different number of
22
+ branches for the same source branch.
23
+
24
+ The comparison is over structure, not over names, so it works across
25
+ languages: a port from Python to Rust keeps its branches and drops its
26
+ exceptions, and the tool says so instead of guessing which is right.
27
+
28
+ Deterministic, no model calls, no dependency beyond the standard library.
29
+
30
+ Usage:
31
+ pilot-consistency.py --manifest FILE [--units N] [--root DIR]
32
+
33
+ --manifest the manifest whose source and target columns name the units
34
+ --units how many units to compare, in manifest order (0 = all, default 3)
35
+ --root the directory the manifest's paths are relative to (default .)
36
+
37
+ Diagnostic envelope (shared by DevOS check scripts):
38
+ FAIL <check>: <message>
39
+ fix: <one actionable line>
40
+
41
+ Exit 0 = the pilot agrees, 1 = the pilot disagrees somewhere, 2 = usage.
42
+ """
43
+ from __future__ import annotations
44
+
45
+ import argparse
46
+ import re
47
+ import sys
48
+ from pathlib import Path
49
+
50
+ # The roles a port has to preserve. Each is a shape a site can have, and the
51
+ # count of a role is what a rule decides: a branch becomes a branch, an
52
+ # exception site becomes an error path or a returned error.
53
+ ROLES = {
54
+ "branch": r"\b(?:if|elif|else|switch|case|match|when)\b",
55
+ "loop": r"\b(?:for|while|foreach|do|loop)\b",
56
+ "error": r"\b(?:try|catch|except|finally|rescue|throw|raise|panic)\b",
57
+ "definition": r"\b(?:def|function|fn|func|class|struct|enum|interface|trait|impl)\b",
58
+ "return": r"\breturn\b",
59
+ }
60
+
61
+ BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.S)
62
+ LINE_COMMENT = re.compile(r"//[^\n]*|#[^\n]*")
63
+ STRING = re.compile(
64
+ r"\"\"\".*?\"\"\"|'''.*?'''|\"(?:\\.|[^\"\\])*\"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`", re.S
65
+ )
66
+
67
+ PATTERNS = {name: re.compile(pattern) for name, pattern in ROLES.items()}
68
+
69
+ KEPT, DROPPED = "kept", "dropped"
70
+
71
+
72
+ def strip_noise(text: str) -> str:
73
+ """Comments and string literals are not structure, and their words read as structure."""
74
+ text = BLOCK_COMMENT.sub(" ", text)
75
+ text = STRING.sub(" ", text)
76
+ text = LINE_COMMENT.sub(" ", text)
77
+ return text
78
+
79
+
80
+ def roles_of(path: Path) -> dict[str, int]:
81
+ try:
82
+ text = path.read_text(encoding="utf-8", errors="replace")
83
+ except OSError:
84
+ return {}
85
+ text = strip_noise(text)
86
+ return {name: len(pattern.findall(text)) for name, pattern in PATTERNS.items()}
87
+
88
+
89
+ def read_manifest(path: Path) -> list[tuple[str, str]]:
90
+ rows = []
91
+ for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
92
+ if not line.strip():
93
+ continue
94
+ parts = line.split("\t")
95
+ if len(parts) < 2 or parts[0] == "source":
96
+ continue
97
+ rows.append((parts[0].strip(), parts[1].strip()))
98
+ return rows
99
+
100
+
101
+ def main() -> int:
102
+ ap = argparse.ArgumentParser(description="did the same rulebook produce the same port three times")
103
+ ap.add_argument("--manifest", required=True, help="the manifest of the pilot units")
104
+ ap.add_argument("--units", type=int, default=3, help="how many units to compare (0 = all)")
105
+ ap.add_argument("--root", default=".", help="the directory the manifest's paths are relative to")
106
+ args = ap.parse_args()
107
+
108
+ manifest = Path(args.manifest)
109
+ if not manifest.is_file():
110
+ print(f"FAIL pilot-consistency: no manifest at {args.manifest}", file=sys.stderr)
111
+ print(" fix: point --manifest at the manifest of the phase you are piloting", file=sys.stderr)
112
+ return 2
113
+ root = Path(args.root).resolve()
114
+
115
+ units = []
116
+ for source, target in read_manifest(manifest):
117
+ src = root / source
118
+ tgt = root / target
119
+ if not src.is_file() or not tgt.is_file():
120
+ continue
121
+ units.append((source, target, roles_of(src), roles_of(tgt)))
122
+ if args.units and len(units) >= args.units:
123
+ break
124
+
125
+ if len(units) < 2:
126
+ print("pilot-consistency: fewer than two ported units to compare, so there is nothing to disagree about")
127
+ return 0
128
+
129
+ print("| Unit | Role | Source | Target | |")
130
+ print("|---|---|---|---|---|")
131
+ findings = []
132
+ notes = []
133
+ for role in ROLES:
134
+ answers = {}
135
+ for source, target, src_roles, tgt_roles in units:
136
+ source_count = src_roles.get(role, 0)
137
+ if source_count == 0:
138
+ continue
139
+ target_count = tgt_roles.get(role, 0)
140
+ outcome = KEPT if target_count else DROPPED
141
+ answers.setdefault(outcome, []).append((source, target, source_count, target_count))
142
+ print(f"| {target} | {role} | {source_count} | {target_count} | {outcome} |")
143
+ if len(answers) < 2:
144
+ continue
145
+ kept = answers[KEPT]
146
+ dropped = answers[DROPPED]
147
+ first = (kept or dropped)[0]
148
+ second = (dropped or kept)[0]
149
+ if kept and dropped:
150
+ findings.append((role, first, second, "kept in one unit, gone in another"))
151
+ else:
152
+ counts = {count for _, _, _, count in kept}
153
+ if len(counts) > 1:
154
+ notes.append((role, first, second, "kept in both units, in different numbers"))
155
+
156
+ for role, first, second, what in notes:
157
+ print(f"note {role}: {what}; read {first[1]} and {second[1]} side by side")
158
+
159
+ if not findings:
160
+ print()
161
+ print("pilot-consistency: the pilot units agree on every role, so the rulebook covers them")
162
+ return 0
163
+
164
+ print()
165
+ print("FAIL pilot-consistency: the pilot units translated the same kind of site two ways")
166
+ for role, first, second, what in findings:
167
+ print(f" fix: read {first[1]} and {second[1]} side by side and write the rule for {role}: {what}")
168
+ print(" a role the units disagree on is a rule that is missing or vague, and the fan-out spreads it")
169
+ return 1
170
+
171
+
172
+ if __name__ == "__main__":
173
+ sys.exit(main())