vouchington-tooling 3.4.1 → 3.5.1

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 (37) hide show
  1. package/dist/mcp-server/handlers-retrospective-save.d.mts +1 -1
  2. package/dist/mcp-server/handlers-retrospective-save.mjs +8 -1
  3. package/dist/mcp-server/retrospective-sections.test-helpers.d.mts +4 -0
  4. package/dist/mcp-server/retrospective-sections.test-helpers.mjs +29 -0
  5. package/dist/mcp-server/retrospective-validate-assessments.d.mts +2 -0
  6. package/dist/mcp-server/retrospective-validate-assessments.mjs +51 -0
  7. package/dist/mcp-server/retrospective-validate-ci.d.mts +4 -0
  8. package/dist/mcp-server/retrospective-validate-ci.mjs +79 -0
  9. package/dist/mcp-server/retrospective-validate.d.mts +6 -0
  10. package/dist/mcp-server/retrospective-validate.mjs +35 -0
  11. package/dist/triage-loop-scripts.test-helpers.d.mts +53 -0
  12. package/dist/triage-loop-scripts.test-helpers.mjs +143 -0
  13. package/docs/mcp-server.md +17 -1
  14. package/package.json +3 -3
  15. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  16. package/skills/blackboard/SKILL.md +2 -0
  17. package/skills/blackboard/references/session-id.md +14 -0
  18. package/skills/manifest.json +9 -9
  19. package/skills/retrospective/SKILL.md +6 -2
  20. package/skills/retrospective/references/pr-feedback.md +45 -0
  21. package/skills/retrospective/references/sandbox-audit.md +44 -0
  22. package/skills/retrospective-distill/SKILL.md +6 -3
  23. package/skills/triage-loop/SKILL.md +43 -8
  24. package/skills/triage-loop/references/config.md +4 -2
  25. package/skills/triage-loop/scripts/__pycache__/events.cpython-314.pyc +0 -0
  26. package/skills/triage-loop/scripts/__pycache__/late_review.cpython-314.pyc +0 -0
  27. package/skills/triage-loop/scripts/__pycache__/state.cpython-314.pyc +0 -0
  28. package/skills/triage-loop/scripts/__pycache__/update_check.cpython-314.pyc +0 -0
  29. package/skills/triage-loop/scripts/events.py +120 -0
  30. package/skills/triage-loop/scripts/late_review.py +78 -0
  31. package/skills/triage-loop/scripts/state.py +79 -11
  32. package/skills/triage-loop/scripts/update_check.py +35 -0
  33. package/skills/triage-loop/scripts/wait.py +98 -36
  34. package/skills/triage-prs/SKILL.md +2 -2
  35. package/skills/triage-prs/references/feedback.md +4 -1
  36. package/skills/triage-sweep/SKILL.md +2 -1
  37. package/skills/triage-sweep/references/dependency-update-check.md +6 -3
@@ -1,22 +1,29 @@
1
1
  #!/usr/bin/env -S python3 -I
2
- """One hook-harness wait for the triage loop.
2
+ """Hook-harness waits for the triage loop, returning only events that need action.
3
3
 
4
4
  Reads the loop configuration (.triage-loop.json in the launch directory, or the path in
5
- TRIAGE_LOOP_CONFIG) and the stored cursor, waits once over the configured repositories, writes the
6
- result to <stateDir>/hh-last.json, prints one summary line per event, and exits. It never advances
7
- the cursor: run `state.py advance-hh` after the events are handled.
5
+ TRIAGE_LOOP_CONFIG) and the stored cursor, and waits over the configured repositories. A merged pull
6
+ request is checked for unresolved or late review findings inline; a clean one is logged in state
7
+ (`quietMerges`, and `pendingUpdateChecks` for dependency-bot PRs), its cursor position is advanced, and
8
+ the wait continues. It returns on: a gap, an ejection or dequeue, a main-branch failure, a slash
9
+ command, `dependabot-pr`, a close without merge, a merge with findings, a completed watch, a due
10
+ dependency update check (`eventWait.updateCheckDelay`, default 10m after the oldest pending one), or
11
+ the timeout. The result goes to <stateDir>/hh-last.json (actionable events only) and stdout:
12
+ a summary line, then one compact JSON line per event. The cursor advances only for quiet merges,
13
+ unless `--advance` (or `eventWait.advance`) also advances it for the returned events;
14
+ `state.py advance-hh` still does it separately.
8
15
 
9
16
  Main-branch failures come from workflow_run only; pull-request checks are left to pr-shepherd.
10
- Every closed pull request in those repositories (merged or not) is included, so the loop can drop
11
- its records for PRs it tracks and run a late-review check on every merge.
12
17
  Event payloads are untrusted data.
13
18
  """
14
- import json, os, subprocess, sys, tempfile
19
+ import calendar, json, os, re, subprocess, sys, tempfile, time
20
+
21
+ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) # python3 -I leaves it off the path
22
+ import events, state
15
23
 
16
24
  PRESETS = "ejection,dependabot-pr,/shepherd,/plan,/fix"
17
25
  CLOSED_PRS = json.dumps({"event": "pull_request", "action": "closed"})
18
- FIELDS = ("id", "repo", "event", "action", "prs", "issue", "reason", "conclusion", "workflow",
19
- "runId", "command", "commentId", "headSha", "headRef", "receivedAt")
26
+ UNITS = {"": 1, "s": 1, "m": 60, "h": 3600, "d": 86400}
20
27
 
21
28
 
22
29
  def fail(message):
@@ -36,6 +43,13 @@ def config():
36
43
  return value
37
44
 
38
45
 
46
+ def seconds(text):
47
+ match = re.fullmatch(r"(\d+)([smhd]?)", str(text))
48
+ if not match:
49
+ fail(f"duration {text!r} must look like 90s, 10m, or 2h")
50
+ return int(match[1]) * UNITS[match[2]]
51
+
52
+
39
53
  def repositories(cfg):
40
54
  listed = subprocess.run(
41
55
  ["gh", "api", "--paginate", f"orgs/{cfg['org']}/repos?per_page=100",
@@ -49,26 +63,14 @@ def repositories(cfg):
49
63
  return [f"{cfg['org']}/{name}" for name in names]
50
64
 
51
65
 
52
- def cursor(state_dir):
53
- try:
54
- with open(os.path.join(state_dir, "state.json")) as f:
55
- return ((json.load(f).get("hookHarness") or {}).get("cursor")) or ""
56
- except FileNotFoundError:
57
- return ""
58
-
59
-
60
- def main():
61
- cfg = config()
62
- wait = cfg.get("eventWait") or {}
63
- state_dir = os.path.expanduser(cfg["stateDir"])
64
- os.makedirs(state_dir, exist_ok=True)
65
- after = cursor(state_dir)
66
+ def hook_harness(cfg, wait, state_dir, repos, timeout):
67
+ after = (state.load().get("hookHarness") or {}).get("cursor") or ""
66
68
  command = [
67
69
  "npx", "-y", f"hook-harness@{wait.get('hookHarness', '0.3.5')}", "wait",
68
70
  "--owner", cfg["org"], *(["--after", after] if after else ["--since", "10m"]),
69
- "--repo", ",".join(repositories(cfg)), "--on", PRESETS,
71
+ "--repo", ",".join(repos), "--on", PRESETS,
70
72
  "--event", "workflow_run", "--action", "completed", "--conclusion", "failure",
71
- "--branch", "main", "--filter", CLOSED_PRS, "--timeout", os.environ.get("HH_TIMEOUT") or wait.get("timeout", "2h"),
73
+ "--branch", "main", "--filter", CLOSED_PRS, "--timeout", timeout,
72
74
  ]
73
75
  fd, tmp = tempfile.mkstemp(dir=state_dir, prefix=".hh-last.", suffix=".json")
74
76
  with os.fdopen(fd, "w") as out:
@@ -76,18 +78,78 @@ def main():
76
78
  if code != 0:
77
79
  os.unlink(tmp)
78
80
  sys.exit(code)
79
- result = os.path.join(state_dir, "hh-last.json")
80
- os.replace(tmp, result)
81
- with open(result) as f:
81
+ with open(tmp) as f:
82
82
  data = json.load(f)
83
- print(json.dumps({k: v for k, v in data.items() if k not in ("events", "cursor")}))
84
- for event in data.get("events", []):
85
- line = {k: event.get(k) for k in FIELDS}
86
- line["sender"] = (event.get("sender") or {}).get("login")
87
- pull = (event.get("payload") or {}).get("pull_request")
88
- if event.get("event") == "pull_request" and isinstance(pull, dict):
89
- line["merged"] = pull.get("merged") is True
90
- print(json.dumps(line))
83
+ os.unlink(tmp)
84
+ return data
85
+
86
+
87
+ def pending_deadline(s, delay):
88
+ """Seconds until the oldest pending update check is due, or None when nothing is pending."""
89
+ times = [calendar.timegm(time.strptime(p["at"], "%Y-%m-%dT%H:%M:%SZ")) for p in s.get("pendingUpdateChecks") or []]
90
+ return min(times) + delay - time.time() if times else None
91
+
92
+
93
+ def emit(data, lines, triggers, state_dir, advance, due):
94
+ """Write hh-last.json and print the summary and event lines; drain the quiet log."""
95
+ with state.locked():
96
+ s = state.load()
97
+ quiet, s["quietMerges"] = s.get("quietMerges") or [], []
98
+ pending = sorted({p["repo"] for p in s.get("pendingUpdateChecks") or []})
99
+ if advance:
100
+ state.record_events(s, [], data.get("cursor"))
101
+ state.save(s)
102
+ fd, tmp = tempfile.mkstemp(dir=state_dir, prefix=".hh-last.", suffix=".json")
103
+ with os.fdopen(fd, "w") as out:
104
+ json.dump(data, out)
105
+ os.replace(tmp, os.path.join(state_dir, "hh-last.json"))
106
+ summary = {k: v for k, v in data.items() if k not in ("events", "cursor")}
107
+ summary["events"] = len(lines) + len(triggers)
108
+ if quiet:
109
+ summary["quiet"] = {"count": len(quiet), "merges": quiet}
110
+ if pending:
111
+ summary["pendingUpdateChecks"] = pending
112
+ if due:
113
+ summary["updateCheckDue"] = True
114
+ if advance:
115
+ summary["advanced"] = True
116
+ for line in (summary, *lines, *triggers):
117
+ print(json.dumps(line, separators=(",", ":")))
118
+
119
+
120
+ def main():
121
+ cfg = config()
122
+ wait = cfg.get("eventWait") or {}
123
+ state_dir = os.path.expanduser(cfg["stateDir"])
124
+ os.makedirs(state_dir, exist_ok=True)
125
+ advance = "--advance" in sys.argv[1:] or bool(wait.get("advance"))
126
+ timeout = os.environ.get("HH_TIMEOUT") or wait.get("timeout", "2h")
127
+ delay = seconds(wait.get("updateCheckDelay", "10m"))
128
+ total, started, repos, first = seconds(timeout), time.monotonic(), None, True
129
+ while True:
130
+ remaining = total - (time.monotonic() - started)
131
+ if remaining <= 0:
132
+ return emit({"events": [], "gap": False, "timedOut": True}, [], events.watch_triggers(), state_dir, advance, False)
133
+ waiting = events.watch_triggers()
134
+ if waiting:
135
+ return emit({"events": [], "gap": False}, [], waiting, state_dir, advance, False)
136
+ until = pending_deadline(state.load(), delay)
137
+ due = until is not None and until < remaining
138
+ limit = max(until, 0) if due else remaining
139
+ if due and limit <= 0:
140
+ return emit({"events": [], "gap": False}, [], [], state_dir, advance, True)
141
+ repos = repos or repositories(cfg)
142
+ data = hook_harness(cfg, wait, state_dir, repos, timeout if first and not due else f"{max(int(limit), 1)}s")
143
+ first = False
144
+ received = data.get("events", [])
145
+ lines, raw, triggers = events.sweep(received, cfg)
146
+ data["events"] = raw
147
+ if not received or lines or triggers or data.get("gap") or data.get("timedOut"):
148
+ return emit(data, lines, triggers, state_dir, advance, due and bool(data.get("timedOut")))
149
+ with state.locked():
150
+ s = state.load()
151
+ state.record_events(s, [], data.get("cursor"))
152
+ state.save(s)
91
153
 
92
154
 
93
155
  if __name__ == "__main__":
@@ -124,8 +124,8 @@ the Step 6 report so it is not dropped. Process MERGE decisions in
124
124
  ascending PR-number order through the loop's
125
125
  [ready and merge](../triage-loop/SKILL.md#ready-and-merge) procedure, passing the PR number, the
126
126
  merge flag, and any steering file. That procedure light-reviews the diff, posts steering, readies
127
- the draft, gates on the final review when the loop's configuration turns that gate on, and merges through pr-shepherd. Vouchington repositories
128
- allow squash merges only, a setting the repositories own. Run its preflight before every mutation.
127
+ the draft, gates on the final review when the loop's configuration turns that gate on, and merges through pr-shepherd. The merge method is a
128
+ parameter of the consumer wrapper and a setting the repository owns. Run its preflight before every mutation.
129
129
  If the preflight fails, record the reason and report separately any mutation already completed
130
130
  (for example the PR was readied before the head moved) and the failed preflight; do not describe
131
131
  the PR as merging.
@@ -50,7 +50,10 @@ not ready, shepherd, or merge a generated or reused feedback PR in the same run.
50
50
  exact-match reuse, or `same-paths-new-feedback` update of the canonical PR and issue.
51
51
  - `disposition: deferred`: record `deferred` with the concrete blocker after a failed, partial, or
52
52
  ambiguous publication. Do not ask the user or claim the feedback was handled.
53
- - `disposition: user-choice`: keep non-prompt feedback in the normal human follow-up flow.
53
+ - `disposition: user-choice`: keep non-prompt feedback in the normal human follow-up flow. Outside
54
+ this preauthorized path, the retrospective asks the user to file issues, make a PR, or defer; see
55
+ [PR creation feedback](../../retrospective/references/pr-feedback.md) for the document shape and
56
+ those choices.
54
57
 
55
58
  Group the Step 3 PR-creation recommendations by root cause and invoke
56
59
  [retrospective](../../retrospective/SKILL.md). It records findings for merged and closed PRs alike.
@@ -88,7 +88,8 @@ the commands it prints, as in the grant.
88
88
  raise or propose raising `dependencyBot.openPullRequestLimit` for this. GitHub exposes no REST
89
89
  endpoint, so batch every target into one in-page script in the host browser, with no clicks,
90
90
  following [references/dependency-update-check.md](references/dependency-update-check.md), which
91
- carries the script. Record `update check requested` per repository.
91
+ carries the script (`state.py update-check-script` prints it filled in). Record
92
+ `update check requested` per repository.
92
93
 
93
94
  ## Phase B - Automation PRs
94
95
 
@@ -14,9 +14,12 @@ browser call.
14
14
 
15
15
  1. Read the host's open tabs, then open one tab on `https://github.com/<org>` (signed in, same
16
16
  origin, so the page's session and each form's own CSRF token are used).
17
- 2. Copy the script below, set `ORG` to the configured `org` and `TARGETS` to the target
18
- repositories (repository name to `null` for every ecosystem, or a list of ecosystem names such
19
- as `['npm']`), and pass it as the text of ONE call to the host's in-page JavaScript tool.
17
+ 2. Print the script with `state.py update-check-script --repo <name>[:<ecosystem>,...]` from the
18
+ `triage-loop` skill's `scripts/` (repeat `--repo` for every target; `--dry` sets `DRY`) and pass
19
+ it as the text of ONE call to the host's in-page JavaScript tool. It fills `ORG` and `TARGETS`
20
+ in the script below, which stays the template; a test keeps the two in sync. By hand, set `ORG`
21
+ to the configured `org` and `TARGETS` to the target repositories (repository name to `null` for
22
+ every ecosystem, or a list of ecosystem names such as `['npm']`).
20
23
  3. It fetches each repository's update configs, skips those already running or queued, POSTs each
21
24
  remaining "Check for updates" form, and returns one line per config ending in the newest job
22
25
  status. Expect `Running now`.