@cbartens/bkit 5.5.1 → 6.0.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 (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -1,10 +1,11 @@
1
- // bkit issues text|labels|comment — tracker payloads, prepared but never sent.
1
+ // bkit issues text|labels|comment — tracker payloads, and with --post / --write the call itself.
2
2
  //
3
- // The tracker calls stay in the workflows, through MCP: a workflow touches only
4
- // its own issue, and only through the tracker's MCP server. These verbs do the
5
- // arithmetic the workflows stated as prose — which comments count as human input,
6
- // which labels a transition adds and drops, the board update, and the exact text
7
- // of every `###### bkit:generated` comment — so no step re-derives it by hand.
3
+ // These verbs do the arithmetic the workflows stated as prose — which comments count
4
+ // as human input, which labels a transition adds and drops, the board update, and the
5
+ // exact text of every `###### bkit:generated` comment — so no step re-derives it by
6
+ // hand. A workflow touches only its own issue. The tracker I/O goes through
7
+ // `tracker.ts`; when it fails the verb prints `tracker.done: false` and the workflow
8
+ // sends the same payload through the tracker's MCP server.
8
9
 
9
10
  import * as fs from "node:fs";
10
11
  import * as path from "node:path";
@@ -19,6 +20,28 @@ import {
19
20
  } from "../lib.js";
20
21
  import { readBkitConfig, type BkitConfig } from "../../shared/settings.js";
21
22
  import { str } from "./status.js";
23
+ import { isCloudOrCi } from "../../checks/before/env.js";
24
+ import {
25
+ COMMENT_FILE_OUTPUT,
26
+ GENERATED_MARKER,
27
+ POST_FLAG,
28
+ TRACKER_OUTPUT,
29
+ attempt,
30
+ classifyFailure,
31
+ commentFileOf,
32
+ fetchIssue,
33
+ moveOnBoard,
34
+ postForVerb,
35
+ readBlockers,
36
+ readLabels,
37
+ redact,
38
+ runActionKey,
39
+ skipOf,
40
+ stampMarker,
41
+ trackerTarget,
42
+ writeLabels,
43
+ type TrackerOutcome,
44
+ } from "./tracker.js";
22
45
 
23
46
  /** Exit code: an input file is missing or not in the expected shape. */
24
47
  export const EXIT_BAD_INPUT = 3;
@@ -34,12 +57,17 @@ function readInput(cwd: string, file: string, flag: string): string {
34
57
  // text
35
58
  // ---------------------------------------------------------------------------
36
59
 
37
- /** First line of every comment bkit posts; such comments are never workflow input. */
38
- export const GENERATED_MARKER = "###### bkit:generated";
60
+ export { GENERATED_MARKER };
39
61
  /** A human writes this as a whole line to discard everything above it. */
40
62
  export const CUT_MARKER = "###### bkit:ignore-earlier";
41
63
  // Whole line only: naming the token inline is prose, not a live marker.
42
64
  const CUT_LINE = /^[ \t]*###### bkit:ignore-earlier[ \t]*\r?$/;
65
+ // The same cut as Jira's HTML comment page renders it: its own `<h6>` element.
66
+ const CUT_ANY =
67
+ /^[ \t]*###### bkit:ignore-earlier[ \t]*\r?$|<h6\b[^>]*>\s*bkit:ignore-earlier\s*<\/h6>/gm;
68
+ // The marker as a whole first line (bare or stamped with its hash), or as Jira's HTML `<h6>`.
69
+ const GENERATED_FIRST =
70
+ /^(?:######[ \t]+bkit:generated(?:[ \t]+[0-9a-f]{12})?[ \t]*$|<h6\b[^>]*>\s*bkit:generated(?:\s+[0-9a-f]{12})?\s*<\/h6>)/;
43
71
 
44
72
  export interface IssueComment {
45
73
  body: string;
@@ -47,23 +75,13 @@ export interface IssueComment {
47
75
  }
48
76
 
49
77
  export const isGenerated = (body: string): boolean =>
50
- (body.replace(/^\s+/, "").split(/\r?\n/, 1)[0] ?? "").trim() === GENERATED_MARKER;
78
+ GENERATED_FIRST.test(body.replace(/^\s+/, "").split(/\r?\n/, 1)[0] ?? "");
51
79
 
52
- /** Keep only what follows the LAST whole-line cut marker; the marker itself goes too. */
80
+ /** Keep only what follows the LAST cut marker (whole line, or Jira's HTML `<h6>`); the marker itself goes too. */
53
81
  export function cutEarlier(text: string): { text: string; cut: boolean } {
54
- const lines = text.split("\n");
55
- let last = -1;
56
- lines.forEach((line, i) => {
57
- if (CUT_LINE.test(line)) last = i;
58
- });
59
- if (last === -1) return { text, cut: false };
60
- return {
61
- text: lines
62
- .slice(last + 1)
63
- .join("\n")
64
- .replace(/^\s*\n/, ""),
65
- cut: true,
66
- };
82
+ const last = [...text.matchAll(CUT_ANY)].at(-1);
83
+ if (last === undefined) return { text, cut: false };
84
+ return { text: text.slice(last.index + last[0].length).replace(/^\s*\n/, ""), cut: true };
67
85
  }
68
86
 
69
87
  /**
@@ -128,6 +146,32 @@ export function issueText(description: string, comments: IssueComment[]) {
128
146
  return { text, kept: human.length, dropped: comments.length - human.length, cut };
129
147
  }
130
148
 
149
+ export interface IssuePart {
150
+ kind: "description" | "comment";
151
+ text: string;
152
+ createdAt?: string;
153
+ }
154
+
155
+ /**
156
+ * The issue as separate parts, oldest first: the description, then each human comment.
157
+ * The last cut marker drops every part above it and the text above it in its own part;
158
+ * nothing else is dropped.
159
+ */
160
+ export function issueParts(description: string, comments: IssueComment[]): IssuePart[] {
161
+ const parts: IssuePart[] = [
162
+ { kind: "description", text: description },
163
+ ...comments
164
+ .filter((c) => !isGenerated(c.body))
165
+ .map((c): IssuePart => ({ kind: "comment", text: c.body, createdAt: c.createdAt })),
166
+ ];
167
+ const last = parts.map((p) => cutEarlier(p.text).cut).lastIndexOf(true);
168
+ const kept =
169
+ last === -1
170
+ ? parts
171
+ : [{ ...parts[last]!, text: cutEarlier(parts[last]!.text).text }, ...parts.slice(last + 1)];
172
+ return kept.map((p) => ({ ...p, text: p.text.trim() })).filter((p) => p.text !== "");
173
+ }
174
+
131
175
  function textVerb(ctx: RunContext): number {
132
176
  const descFile = str(ctx.flags.descriptionFile);
133
177
  const commentsFile = str(ctx.flags.commentsFile);
@@ -209,7 +253,7 @@ export function transitionLabels(current: string[], t: LabelTransition) {
209
253
 
210
254
  /**
211
255
  * The issue state the workflows set for the same transition, on a tracker whose
212
- * board status is the issue state: `bkit.linear` or `bkit.jira`. A shipped
256
+ * board status is the issue state: `bkit.tracker.linear` or `bkit.tracker.jira`. A shipped
213
257
  * or failed issue waits on a human (`review`); a phase starting is `progress`.
214
258
  * The workflows write it alone, so a name the team or project lacks leaves the
215
259
  * labels landed. Null under github (the Projects v2 board moves instead) and
@@ -243,12 +287,13 @@ const BOARD_STATES = new Set(["progress", "review"]);
243
287
 
244
288
  /**
245
289
  * The two `projects_write` payloads that move an issue on the Projects v2 board,
246
- * from `bkit.github`. Payload keys are the MCP tool's own argument names: the
290
+ * from `bkit.tracker.github`. Payload keys are the MCP tool's own argument names: the
247
291
  * board item is found by its issue, and Status is set by option name.
248
292
  */
249
293
  function boardPayload(
250
294
  ctx: RunContext,
251
295
  status: "progress" | "review",
296
+ target?: { issue: string; ownerRepo: string },
252
297
  ): { board: Record<string, unknown> | null; boardSkipped: string | null } {
253
298
  const { issueTracker: tracker, github } = readBkitConfig(repoRoot(ctx.cwd));
254
299
  if (tracker !== "github") {
@@ -262,11 +307,13 @@ function boardPayload(
262
307
  ctx.log("GitHub project not configured in package.json");
263
308
  return { board: null, boardSkipped: "not-configured" };
264
309
  }
265
- ctx.log(`bkit.github.project "${github.projectUrl}" is not a GitHub Projects board URL`);
310
+ ctx.log(
311
+ `bkit.tracker.github.project "${github.projectUrl}" is not a GitHub Projects board URL`,
312
+ );
266
313
  return { board: null, boardSkipped: "project-url-invalid" };
267
314
  }
268
- const issue = String(ctx.flags.issue ?? "").replace(/^#/, "");
269
- const ownerRepo = String(ctx.flags.ownerRepo ?? "");
315
+ const issue = (target?.issue ?? String(ctx.flags.issue ?? "")).replace(/^#/, "");
316
+ const ownerRepo = target?.ownerRepo ?? String(ctx.flags.ownerRepo ?? "");
270
317
  const [itemOwner, itemRepo, extra] = ownerRepo.split("/");
271
318
  if (!/^[0-9]+$/.test(issue) || !itemOwner || !itemRepo || extra !== undefined) {
272
319
  throw new CommandError(
@@ -291,7 +338,8 @@ function boardPayload(
291
338
  };
292
339
  }
293
340
 
294
- function labelsVerb(ctx: RunContext): number {
341
+ /** The flags of a label transition, checked. */
342
+ function labelTransition(ctx: RunContext): { t: LabelTransition; board: BoardState | undefined } {
295
343
  const phase = str(ctx.flags.phase);
296
344
  if (phase !== undefined && !PHASE_LABELS.includes(`bkit:${phase}`)) {
297
345
  throw new CommandError(
@@ -306,25 +354,92 @@ function labelsVerb(ctx: RunContext): number {
306
354
  if (board !== undefined && !BOARD_STATES.has(board)) {
307
355
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
308
356
  }
309
- const t: LabelTransition = { phase, failed };
310
- const { add, remove, labels } = transitionLabels(
311
- (ctx.flags.label as string[] | undefined) ?? [],
312
- t,
313
- );
314
- const { board: payload, boardSkipped } =
315
- board === undefined
316
- ? { board: null, boardSkipped: null }
317
- : boardPayload(ctx, board as "progress" | "review");
318
- ctx.emit({
357
+ return { t: { phase, failed }, board: board as BoardState | undefined };
358
+ }
359
+
360
+ type BoardState = "progress" | "review";
361
+
362
+ /** The printed transition for `current` labels. */
363
+ function transitionOut(ctx: RunContext, current: string[], t: LabelTransition, board?: string) {
364
+ const { add, remove, labels } = transitionLabels(current, t);
365
+ return {
319
366
  add,
320
367
  remove,
321
368
  labels,
322
369
  changed: add.length + remove.length > 0,
323
370
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
324
371
  trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
325
- board: payload,
326
- boardSkipped,
372
+ };
373
+ }
374
+
375
+ function labelsVerb(ctx: RunContext): number | Promise<number> {
376
+ if (ctx.flags.write === true) return labelsWrite(ctx);
377
+ const { t, board } = labelTransition(ctx);
378
+ const out = transitionOut(ctx, (ctx.flags.label as string[] | undefined) ?? [], t, board);
379
+ const { board: payload, boardSkipped } =
380
+ board === undefined ? { board: null, boardSkipped: null } : boardPayload(ctx, board);
381
+ ctx.emit({ ...out, board: payload, boardSkipped });
382
+ return EXIT.OK;
383
+ }
384
+
385
+ /**
386
+ * `--write`: read the issue's labels, write the transition (and the Linear / Jira
387
+ * state), then move the board item. Each write that fails prints `done: false`
388
+ * with its reason; the workflow sends the printed payload through the MCP instead.
389
+ */
390
+ async function labelsWrite(ctx: RunContext): Promise<number> {
391
+ const { t, board } = labelTransition(ctx);
392
+ const target = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
393
+ const skip = skipOf(target);
394
+ const given = (ctx.flags.label as string[] | undefined) ?? [];
395
+ if (skip) {
396
+ ctx.emit({
397
+ ...transitionOut(ctx, given, t, board),
398
+ board: null,
399
+ boardSkipped: null,
400
+ tracker: skip,
401
+ });
402
+ return EXIT.OK;
403
+ }
404
+ // A malformed board target is a usage error: refused before any label is written.
405
+ let { board: payload, boardSkipped } =
406
+ board === undefined
407
+ ? { board: null, boardSkipped: null as string | null }
408
+ : boardPayload(ctx, board, {
409
+ issue: target.issue ?? "",
410
+ ownerRepo: target.ownerRepo || String(ctx.flags.ownerRepo ?? ""),
411
+ });
412
+ let current = given;
413
+ const read = await attempt("labels", ctx.log, async () => {
414
+ current = await readLabels(target);
327
415
  });
416
+ const out = transitionOut(ctx, current, t, board);
417
+ const tracker =
418
+ "done" in read && !read.done
419
+ ? read
420
+ : await attempt("labels", ctx.log, () =>
421
+ writeLabels(target, {
422
+ add: out.add,
423
+ remove: out.remove,
424
+ labels: out.labels,
425
+ state: out.trackerState,
426
+ }),
427
+ );
428
+ let boardWrite: TrackerOutcome | null = null;
429
+ const project = readBkitConfig(repoRoot(ctx.cwd)).github;
430
+ if (payload !== null && board !== undefined && project.project) {
431
+ if (isCloudOrCi()) {
432
+ // A cloud run's token can comment and label but never reach a Projects v2 board.
433
+ payload = null;
434
+ boardSkipped = "cloud";
435
+ } else {
436
+ const { owner, number } = project.project;
437
+ boardWrite = await attempt("board", ctx.log, () =>
438
+ moveOnBoard(target, { owner, number, status: project[board] }),
439
+ );
440
+ }
441
+ }
442
+ ctx.emit({ ...out, board: payload, boardSkipped, tracker, boardWrite });
328
443
  return EXIT.OK;
329
444
  }
330
445
 
@@ -346,7 +461,7 @@ const FIELD_LABELS: Record<string, string> = {
346
461
  verdict: "Verdict",
347
462
  failures: "Failures",
348
463
  scope: "Scope",
349
- subPlan: "Sub-plan",
464
+ group: "Group",
350
465
  attempt: "Attempt",
351
466
  strategy: "Strategy",
352
467
  };
@@ -365,12 +480,9 @@ function headerFields(ctx: RunContext): Array<[string, string]> {
365
480
  if (eq <= 0) throw new CommandError(EXIT.USAGE, `--field "${f}" must be Name=value`);
366
481
  out.push([f.slice(0, eq), f.slice(eq + 1)]);
367
482
  }
368
- } else if (key === "subPlan") {
369
- const count = str(ctx.flags.subPlanCount);
370
- out.push([
371
- "Sub-plan",
372
- `${String(ctx.flags.subPlan)}${count === undefined ? "" : `/${count}`}`,
373
- ]);
483
+ } else if (key === "group") {
484
+ const count = str(ctx.flags.groupCount);
485
+ out.push(["Group", `${String(ctx.flags.group)}${count === undefined ? "" : `/${count}`}`]);
374
486
  } else if (FIELD_LABELS[key] !== undefined) {
375
487
  out.push([FIELD_LABELS[key], String(ctx.flags[key])]);
376
488
  }
@@ -546,19 +658,22 @@ export function buildComment(cwd: string, o: CommentInput): string {
546
658
  }
547
659
 
548
660
  // A whole-line cut marker copied in from an artifact would fire on the next
549
- // run's issue text; inline, it is only a mention.
550
- return lines
551
- .join("\n")
552
- .split("\n")
553
- .map((l) => (CUT_LINE.test(l) ? `\`${CUT_MARKER}\`` : l))
554
- .join("\n");
661
+ // run's issue text; inline, it is only a mention. The marker carries the body's
662
+ // hash, which is how a re-run finds the comment already posted.
663
+ return stampMarker(
664
+ lines
665
+ .join("\n")
666
+ .split("\n")
667
+ .map((l) => (CUT_LINE.test(l) ? `\`${CUT_MARKER}\`` : l))
668
+ .join("\n"),
669
+ );
555
670
  }
556
671
 
557
672
  /** `bkit issues comment`'s flags as a `CommentInput`. */
558
673
  export function commentBody(ctx: RunContext): string {
559
674
  const kind = str(ctx.flags.kind) ?? "step";
560
- if (ctx.flags.subPlanCount !== undefined && ctx.flags.subPlan === undefined) {
561
- throw new CommandError(EXIT.USAGE, "--sub-plan-count needs --sub-plan");
675
+ if (ctx.flags.groupCount !== undefined && ctx.flags.group === undefined) {
676
+ throw new CommandError(EXIT.USAGE, "--group-count needs --group");
562
677
  }
563
678
  return buildComment(ctx.cwd, {
564
679
  kind: kind as CommentInput["kind"],
@@ -585,13 +700,121 @@ export function commentBody(ctx: RunContext): string {
585
700
  });
586
701
  }
587
702
 
703
+ // ---------------------------------------------------------------------------
704
+ // fetch / related — issue text straight to files, never through the orchestrator
705
+ // ---------------------------------------------------------------------------
706
+
707
+ /** Exit code 80 with the failure's reason, for the verbs that only talk to the tracker. */
708
+ function useMcp(ctx: RunContext, err: unknown): number {
709
+ const reason = classifyFailure(err);
710
+ ctx.log(redact(`tracker read failed (${reason}): ${(err as Error).message ?? String(err)}`));
711
+ ctx.emit({ reason });
712
+ return EXIT.USE_MCP;
713
+ }
714
+
715
+ async function fetchVerb(ctx: RunContext): Promise<number> {
716
+ const out = str(ctx.flags.sessionDir) || str(ctx.flags.outbox);
717
+ if (!out) throw new CommandError(EXIT.USAGE, "give --session-dir or --outbox");
718
+ const t = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
719
+ const skip = skipOf(t);
720
+ if (skip) {
721
+ ctx.emit(skip);
722
+ return EXIT.OK;
723
+ }
724
+ let issue;
725
+ try {
726
+ issue = await fetchIssue(t);
727
+ } catch (err) {
728
+ return useMcp(ctx, err);
729
+ }
730
+ const dir = path.resolve(ctx.cwd, out);
731
+ const files = {
732
+ description: path.join(dir, "issue-description.md"),
733
+ comments: path.join(dir, "issue-comments.json"),
734
+ facts: path.join(dir, "issue-facts.json"),
735
+ };
736
+ const facts = { title: issue.title, url: issue.url, state: issue.state, labels: issue.labels };
737
+ fs.mkdirSync(dir, { recursive: true });
738
+ fs.writeFileSync(files.description, issue.body);
739
+ const comments = sortOldestFirst(issue.comments).comments;
740
+ fs.writeFileSync(files.comments, `${JSON.stringify(comments, null, 2)}\n`);
741
+ fs.writeFileSync(files.facts, `${JSON.stringify(facts, null, 2)}\n`);
742
+ ctx.emit({ ...facts, files });
743
+ return EXIT.OK;
744
+ }
745
+
746
+ /** Hit ids from a search the orchestrator ran: ids, or objects carrying `number` / `identifier` / `key` / `id`. */
747
+ function readHits(cwd: string, file: string): string[] {
748
+ const parsed = parseJson(readInput(cwd, file, "hits-file"));
749
+ const bad = () =>
750
+ new CommandError(EXIT_BAD_INPUT, `--hits-file ${file} is not a JSON list of issue ids`);
751
+ if (!parsed.ok || !Array.isArray(parsed.value)) throw bad();
752
+ return parsed.value.map((h: unknown) => {
753
+ const o = (h ?? {}) as Record<string, unknown>;
754
+ const id = typeof h === "object" ? (o.number ?? o.identifier ?? o.key ?? o.id) : h;
755
+ if (typeof id !== "string" && typeof id !== "number") throw bad();
756
+ return String(id).trim().replace(/^#/, "").toUpperCase();
757
+ });
758
+ }
759
+
760
+ async function relatedVerb(ctx: RunContext): Promise<number> {
761
+ const hitsFile = String(ctx.flags.hitsFile);
762
+ const outFile = String(ctx.flags.out);
763
+ const top = ctx.flags.top === undefined ? 10 : Number(ctx.flags.top);
764
+ if (!Number.isInteger(top) || top < 1)
765
+ throw new CommandError(EXIT.USAGE, "--top must be a positive integer");
766
+ const own = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
767
+ const hits = [...new Set(readHits(ctx.cwd, hitsFile))]
768
+ .filter((id) => id !== own.issue)
769
+ .slice(0, top);
770
+ const sections: string[] = [];
771
+ for (const id of hits) {
772
+ let issue;
773
+ try {
774
+ issue = await fetchIssue({ ...own, issue: id });
775
+ } catch (err) {
776
+ return useMcp(ctx, err);
777
+ }
778
+ const ref = own.tracker === "github" ? `#${id}` : id;
779
+ const { text } = issueText(issue.body, sortOldestFirst(issue.comments).comments);
780
+ sections.push(`## ${ref} — ${issue.title} (${issue.state})${text ? `\n\n${text}` : ""}\n`);
781
+ }
782
+ const body = sections.length === 0 ? "None.\n" : sections.join("\n");
783
+ const abs = path.resolve(ctx.cwd, outFile);
784
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
785
+ fs.writeFileSync(abs, body);
786
+ ctx.emit({ path: outFile, bytes: Buffer.byteLength(body), hits: hits.length });
787
+ return EXIT.OK;
788
+ }
789
+
790
+ async function blockedByVerb(ctx: RunContext): Promise<number> {
791
+ const t = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
792
+ const skip = skipOf(t);
793
+ if (skip) {
794
+ ctx.emit(skip);
795
+ return EXIT.OK;
796
+ }
797
+ let blockers;
798
+ try {
799
+ blockers = await readBlockers(t);
800
+ } catch (err) {
801
+ return useMcp(ctx, err);
802
+ }
803
+ ctx.emit({
804
+ blockers: blockers.map(({ id, state }) => ({ id, state })),
805
+ open: blockers.filter((b) => b.open).length,
806
+ });
807
+ return EXIT.OK;
808
+ }
809
+
588
810
  // ---------------------------------------------------------------------------
589
811
  // Command
590
812
  // ---------------------------------------------------------------------------
591
813
 
592
814
  export const issuesCommand: CommandSpec = {
593
815
  noun: "issues",
594
- summary: "Prepare tracker payloads (issue text, label transitions, comments); MCP sends them.",
816
+ summary:
817
+ "Tracker payloads (issue text, label transitions, comments); --post / --write send them.",
595
818
  verbs: {
596
819
  text: {
597
820
  summary: "ISSUE_TEXT: description + human comments, after the bkit:ignore-earlier cut.",
@@ -612,6 +835,78 @@ export const issuesCommand: CommandSpec = {
612
835
  exitCodes: { [EXIT_BAD_INPUT]: "an input file is missing or not a list of comments" },
613
836
  run: textVerb,
614
837
  },
838
+ fetch: {
839
+ summary:
840
+ "Read the run's issue into issue-description.md, issue-comments.json and issue-facts.json; prints the facts, never the body.",
841
+ flags: [
842
+ { name: "fid", type: "string", help: "the run's FID (names the issue)" },
843
+ { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
844
+ { name: "session-dir", type: "string", help: "write the three files here" },
845
+ {
846
+ name: "outbox",
847
+ type: "string",
848
+ help: "write the three files here (instead of --session-dir)",
849
+ },
850
+ ],
851
+ output: {
852
+ title: "issue title",
853
+ url: "issue URL",
854
+ state: "tracker state name (GitHub: open | closed)",
855
+ labels: "label names",
856
+ files:
857
+ "{description, comments, facts}: raw description, comments oldest first as JSON, {title, url, state, labels} as JSON",
858
+ skipped: "no-issue | tracker-none: nothing read, nothing written",
859
+ reason:
860
+ "exit 80: network | auth | scope | rate-limit | not-found | http-<n>; read the issue via the tracker MCP",
861
+ },
862
+ exitCodes: {},
863
+ run: fetchVerb,
864
+ },
865
+ related: {
866
+ summary:
867
+ "Fetch each hit of the orchestrator's related-issue search and write the related-issues file.",
868
+ flags: [
869
+ {
870
+ name: "hits-file",
871
+ type: "string",
872
+ required: true,
873
+ help: "JSON list of hit ids (or objects with number / identifier / key) in rank order",
874
+ },
875
+ { name: "out", type: "string", required: true, help: "the related-issues file to write" },
876
+ { name: "top", type: "string", help: "keep the first N hits (default 10)" },
877
+ {
878
+ name: "fid",
879
+ type: "string",
880
+ help: "the run's FID: its own issue is dropped from the hits",
881
+ },
882
+ { name: "issue", type: "string", help: "the run's issue id (instead of --fid)" },
883
+ ],
884
+ output: {
885
+ path: "the file written: one `## {ref} — {title} ({state})` section per hit, else `None.`",
886
+ bytes: "its size in bytes",
887
+ hits: "hits fetched",
888
+ reason: "exit 80: why a hit could not be read; nothing was written",
889
+ },
890
+ exitCodes: { [EXIT_BAD_INPUT]: "--hits-file is missing or not a JSON list of issue ids" },
891
+ run: relatedVerb,
892
+ },
893
+ "blocked-by": {
894
+ summary: "The issues blocking the run's issue, with their states and the ones still open.",
895
+ flags: [
896
+ { name: "fid", type: "string", help: "the run's FID (names the issue)" },
897
+ { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
898
+ ],
899
+ output: {
900
+ blockers:
901
+ "[{id, state}]: GitHub from the body's bkit:blocked-by block, Linear from blocks relations, Jira from is-blocked-by links",
902
+ open: "how many blockers are not closed / done / canceled (0 = unblocked)",
903
+ skipped: "no-issue | tracker-none: nothing read",
904
+ reason:
905
+ "exit 80: network | auth | scope | rate-limit | not-found | http-<n>; read the blockers via the tracker MCP",
906
+ },
907
+ exitCodes: {},
908
+ run: blockedByVerb,
909
+ },
615
910
  labels: {
616
911
  summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
617
912
  flags: [
@@ -627,8 +922,18 @@ export const issuesCommand: CommandSpec = {
627
922
  type: "string",
628
923
  help: "also move the Projects v2 item: progress | review",
629
924
  },
630
- { name: "issue", type: "string", help: "issue number (with --board)" },
925
+ {
926
+ name: "issue",
927
+ type: "string",
928
+ help: "issue number (with --board); with --write, the issue to write (instead of --fid)",
929
+ },
631
930
  { name: "owner-repo", type: "string", help: "<owner>/<repo> of the issue (with --board)" },
931
+ {
932
+ name: "write",
933
+ type: "boolean",
934
+ help: "read the issue's labels, write the transition and state, move the board; prints `tracker` and `boardWrite`",
935
+ },
936
+ { name: "fid", type: "string", help: "with --write: the run's FID (names the issue)" },
632
937
  ],
633
938
  output: {
634
939
  add: "labels to add",
@@ -640,7 +945,11 @@ export const issuesCommand: CommandSpec = {
640
945
  "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
641
946
  board: "projects_write payloads {addItem, updateItem}, or null",
642
947
  boardSkipped:
643
- "why board is null with --board: opted-out | not-configured | project-url-invalid | tracker-<name>",
948
+ "why board is null with --board: opted-out | not-configured | project-url-invalid | tracker-<name> | cloud (--write on a cloud or CI runtime: the next local run moves it)",
949
+ tracker:
950
+ "with --write: the label (and state) write: {done: true, action: labels} | {done: false, action, reason} (write `labels` / `trackerState` via the tracker MCP) | {skipped}",
951
+ boardWrite:
952
+ "with --write and a board payload: {done: true, action: board} | {done: false, action, reason} (send `board` via the MCP); null when nothing to move",
644
953
  },
645
954
  run: labelsVerb,
646
955
  },
@@ -661,8 +970,8 @@ export const issuesCommand: CommandSpec = {
661
970
  { name: "verdict", type: "string", help: "header field Verdict" },
662
971
  { name: "failures", type: "string", help: "header field Failures" },
663
972
  { name: "scope", type: "string", help: "header field Scope" },
664
- { name: "sub-plan", type: "string", help: "header field Sub-plan (x of x/y)" },
665
- { name: "sub-plan-count", type: "string", help: "y of Sub-plan x/y" },
973
+ { name: "group", type: "string", help: "header field Group (x of x/y)" },
974
+ { name: "group-count", type: "string", help: "y of Group x/y" },
666
975
  { name: "attempt", type: "string", help: "header field Attempt" },
667
976
  { name: "strategy", type: "string", help: "header field Strategy" },
668
977
  {
@@ -703,14 +1012,48 @@ export const issuesCommand: CommandSpec = {
703
1012
  type: "string",
704
1013
  help: "failure: captured stderr (last 20 lines kept)",
705
1014
  },
1015
+ POST_FLAG,
1016
+ { name: "fid", type: "string", help: "with --post: the run's FID (names the issue)" },
1017
+ { name: "issue", type: "string", help: "with --post: the issue id (instead of --fid)" },
1018
+ {
1019
+ name: "file",
1020
+ type: "string",
1021
+ help: "with --post: the run's status.jsonl; the post is recorded there and a re-run of the same comment is deduped by that row",
1022
+ },
706
1023
  ],
707
- output: { comment: "the comment body" },
1024
+ output: {
1025
+ comment: "the comment body",
1026
+ commentFile: COMMENT_FILE_OUTPUT,
1027
+ tracker: TRACKER_OUTPUT,
1028
+ },
708
1029
  exitCodes: {
709
1030
  [EXIT_BAD_INPUT]:
710
1031
  "a --body-file / --section / --stderr-file / --error-file file is missing",
711
1032
  },
712
- run: (ctx) => {
713
- ctx.emit({ comment: commentBody(ctx) });
1033
+ run: async (ctx) => {
1034
+ const comment = commentBody(ctx);
1035
+ const commentFile = commentFileOf(ctx.cwd, comment);
1036
+ if (ctx.flags.post !== true) {
1037
+ ctx.emit({ comment, commentFile });
1038
+ return EXIT.OK;
1039
+ }
1040
+ const file = str(ctx.flags.file)
1041
+ ? path.resolve(ctx.cwd, String(ctx.flags.file))
1042
+ : undefined;
1043
+ const key = runActionKey(
1044
+ file,
1045
+ str(ctx.flags.workflow),
1046
+ str(ctx.flags.kind) ?? "step",
1047
+ str(ctx.flags.stepNumber),
1048
+ str(ctx.flags.subStep),
1049
+ str(ctx.flags.attempt),
1050
+ );
1051
+ const tracker = await postForVerb(ctx, comment, {
1052
+ fid: str(ctx.flags.fid),
1053
+ issue: str(ctx.flags.issue),
1054
+ ...(key === undefined ? {} : { file, key }),
1055
+ });
1056
+ ctx.emit({ comment, commentFile, tracker });
714
1057
  return EXIT.OK;
715
1058
  },
716
1059
  },