@joshuafolkken/kit 1.1435.0 → 1.1453.0

package/dist/hooks/pretool-guard.js

@@ -1,22 +1,22 @@
 #!/usr/bin/env tsx
 import {
   pretool_guard
-} from "./chunk-JXQBK323.js";
-import "./chunk-MSYSUSY6.js";
-import "./chunk-YZXYOAZ3.js";
+} from "./chunk-5C7L6FRC.js";
+import "./chunk-SHYUQOIS.js";
+import "./chunk-Y3GKIKGW.js";
 import "./chunk-IX6TTTI6.js";
-import "./chunk-YW452ZAX.js";
+import "./chunk-Z4XI7CZS.js";
 import "./chunk-CDY4NFQG.js";
-import "./chunk-7KMN5QB5.js";
-import "./chunk-2G5F2YCD.js";
-import "./chunk-QL6QTPWN.js";
-import "./chunk-5SJSSCJG.js";
+import "./chunk-EF5GQ6WS.js";
+import "./chunk-LBFYEOXJ.js";
+import "./chunk-NO4AALP5.js";
+import "./chunk-UT7YC3N2.js";
 import {
   hook_decision
-} from "./chunk-MU4LJFIV.js";
-import "./chunk-XER6SSIB.js";
-import "./chunk-4BHUPFKF.js";
-import "./chunk-3LE6VLSR.js";
+} from "./chunk-W5ZKGTSY.js";
+import "./chunk-MBJYQPEK.js";
+import "./chunk-OLMO72ON.js";
+import "./chunk-3C4XRYG6.js";
 import "./chunk-DGT54IH5.js";
 
 // scripts/hooks/pretool-guard-cli.ts

package/dist/hooks/session-lang.js

@@ -8,19 +8,19 @@ import {
   run_event_stream_emit,
   run_headless,
   session_language
-} from "./chunk-YW452ZAX.js";
+} from "./chunk-Z4XI7CZS.js";
 import {
   error_text
 } from "./chunk-CDY4NFQG.js";
 import {
   josh_environment_file
-} from "./chunk-4BHUPFKF.js";
+} from "./chunk-OLMO72ON.js";
 import {
   agent_session_environment,
   json_value,
   process_identity,
   run_carry
-} from "./chunk-3LE6VLSR.js";
+} from "./chunk-3C4XRYG6.js";
 import {
   stamp_file
 } from "./chunk-DGT54IH5.js";

package/dist/hooks/stop-guard.js

@@ -13,7 +13,7 @@ import {
   repo_party,
   run_cut,
   run_hold
-} from "./chunk-YZXYOAZ3.js";
+} from "./chunk-Y3GKIKGW.js";
 import {
   agent_headless,
   agent_role_profile,
@@ -23,22 +23,22 @@ import {
   run_event_stream_emit,
   run_headless,
   session_language
-} from "./chunk-YW452ZAX.js";
+} from "./chunk-Z4XI7CZS.js";
 import {
   timed_fetch
 } from "./chunk-723HKZO5.js";
 import "./chunk-CDY4NFQG.js";
 import {
   hook_decision
-} from "./chunk-MU4LJFIV.js";
+} from "./chunk-W5ZKGTSY.js";
 import {
   time_density_hook,
   time_hook_transcript,
   time_reported_failure
-} from "./chunk-XER6SSIB.js";
+} from "./chunk-MBJYQPEK.js";
 import {
   lane_child_marker
-} from "./chunk-4BHUPFKF.js";
+} from "./chunk-OLMO72ON.js";
 import {
   backlog_budget,
   issue_number_shape,
@@ -47,7 +47,7 @@ import {
   process_owner_schema,
   run_carry,
   run_invocation
-} from "./chunk-3LE6VLSR.js";
+} from "./chunk-3C4XRYG6.js";
 import {
   stamp_file
 } from "./chunk-DGT54IH5.js";

package/dist/josh.js

@@ -395,6 +395,7 @@ var START_TIME_FORMAT = "lstart=";
 var PID_FLAG = "-p";
 var PROBE_ENVIRONMENT = { TZ: "UTC", LC_ALL: "C" };
 var LIVENESS_SIGNAL = 0;
+var NO_SUCH_PROCESS = "ESRCH";
 var LOWEST_REAL_PID = 1;
 var PROC_START_FIELD_INDEX = 19;
 var BEACON_SCHEME = "socket:";
@@ -409,15 +410,20 @@ var BEACON_GONE_STATUS = 2;
 var SOCKET_PROBE_SOURCE = `const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(${String(BEACON_LIVE_STATUS)}));socket.once('error',(error)=>process.exit(['ECONNREFUSED','ENOENT'].includes(error.code)?${String(BEACON_GONE_STATUS)}:${String(BEACON_UNKNOWN_STATUS)}));socket.setTimeout(1000,()=>process.exit(${String(BEACON_UNKNOWN_STATUS)}));`;
 var beacons = /* @__PURE__ */ new Map();
 var exit_cleanup = { is_registered: false };
-function is_live_pid(pid) {
-  if (pid < LOWEST_REAL_PID) return false;
+function signal_refusal(pid) {
   try {
     process.kill(pid, LIVENESS_SIGNAL);
-    return true;
-  } catch {
-    return false;
+    return void 0;
+  } catch (error) {
+    return error.code ?? NO_SUCH_PROCESS;
   }
 }
+function is_live_pid(pid) {
+  return pid >= LOWEST_REAL_PID && signal_refusal(pid) === void 0;
+}
+function is_present_pid(pid) {
+  return pid >= LOWEST_REAL_PID && signal_refusal(pid) !== NO_SUCH_PROCESS;
+}
 function read_proc_start(pid) {
   try {
     const stat = readFileSync3(`/proc/${String(pid)}/stat`, "utf8");
@@ -543,6 +549,11 @@ function is_same_process(pid, recorded_start, read2 = read_start) {
   if (recorded_start === void 0) return void 0;
   return matches_recorded_start(pid, recorded_start, read2);
 }
+function is_present_process(pid, recorded_start, read2 = read_start) {
+  if (!is_present_pid(pid)) return false;
+  if (recorded_start === void 0) return void 0;
+  return matches_recorded_start(pid, recorded_start, read2);
+}
 function is_own_process(pid, recorded_start) {
   return pid === process.pid && recorded_start === own_start();
 }
@@ -551,6 +562,8 @@ var process_identity = {
   is_live_beacon,
   is_live_pid,
   is_own_process,
+  is_present_pid,
+  is_present_process,
   is_same_process,
   open_beacon,
   own_fields,
@@ -1447,16 +1460,16 @@ var ISSUE_COMMANDS = {
     description: "File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle",
     category: "AI tools",
     reference: [
-      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>] [--over-cap] [--no-auto-ok] [--requested] [--release]",
+      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>] [--over-cap] [--no-auto-ok] [--release]",
       "automation",
       ["network"]
     ]
   },
   "issue:release": {
     script: "scripts/issue/issue-release-cli.ts",
-    description: "Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+    description: "Link an Issue to the repository's open release Issue as its blocker (or, with --wait, as waiting on it), filing one when none is open",
     category: "AI tools",
-    reference: ["<issue>", "automation", ["network"]]
+    reference: ["<issue> [--wait]", "automation", ["network"]]
   }
 };
 
@@ -1741,6 +1754,16 @@ var AI_COMMANDS = {
     category: "AI tools",
     reference: ["[--exclude <n>[,<n>...]] [--label <name>]", "automation", ["network"]]
   },
+  "auto-ok:judge": {
+    script: "scripts/auto-ok/auto-ok-judge-cli.ts",
+    description: "List the open issues backlogrun owes an auto-ok judgement, or record one (--apply / --decline)",
+    category: "AI tools",
+    reference: [
+      "[--apply <n> (--lane | --solo) | --decline <n> --reason <text>]",
+      "automation",
+      ["network"]
+    ]
+  },
   ...BACKLOG_COMMANDS,
   cost: {
     script: "scripts/cost-runtime/cost-cli.ts",
@@ -2528,7 +2551,7 @@ var PROJECT_COMMANDS = {
     description: "Set a project up for the GitHub Issue workflow, from git init to the setup PR",
     category: "Project",
     reference: [
-      `${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]`,
+      `${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--dry-run] [--init-command <command>] [--push-preflight-command <command>]`,
       "developer",
       ["files", "git", "network", "processes"]
     ]
@@ -2561,7 +2584,7 @@ var PROJECT_COMMANDS = {
     description: "Initialize config in a new project",
     category: "Project",
     reference: [
-      `${PROFILE_ARGUMENTS} [--no-install]`,
+      `${PROFILE_ARGUMENTS} [--no-install] [--dry-run]`,
       "developer",
       ["files", "network", "processes"]
     ]

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1435.0",
+  "version": "1.1453.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [

package/prompts/collaboration-workflow/issue-template.md

@@ -6,6 +6,7 @@
 ## 背景
 
 <不具合なら `- 種別: 不具合`、そうでなければ `- 種別: 非不具合` を宣言する>
+<人の判断が要らなければ `- 人の判断: 不要`、要るなら `- 人の判断: 要（<方針の判断 / 外部アカウント / 目視確認>）` を宣言する>
 
 <なぜ必要か>
 
@@ -49,15 +50,16 @@
 
 ### `## 背景` 直下の宣言と分類ラベル
 
-起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行う。本文の検査（`pnpm josh issue:lint <path>` と同じ）と、下表の宣言から決まる分類ラベルの付与は、このコマンドが 1 回の作成リクエストで行う。**宣言を選ぶのは起票者の判断であり、コマンドは単語から推測しない。** 人が依頼した起票（会話での依頼も含む）には `--requested` を付ける（`kickoff.md` → "Words typed after `new`"）。
+起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行う。本文の検査（`pnpm josh issue:lint <path>` と同じ）と、下表の宣言から決まる分類ラベルの付与は、このコマンドが 1 回の作成リクエストで行う。**宣言を選ぶのは起票者の判断であり、コマンドは単語から推測しない。** `- 人の判断:` の行は必須で、`issue:file` だけが検査し（`issue:lint` は見ない）、`auto-ok` の判定に使う。判定は人が依頼した起票も含めてすべて同じ（`scripts/issue/issue-auto-ok.ts`、`docs/how-to/run-backlog.md`）。**`不要` を宣言する起票には `--label run:lane`（kit 自身の検証の不具合なら `run:solo`）も付ける** — 付いていなければ `issue:file` が拒否する。
 
-| 宣言                   | 付くラベル        | 選ぶ基準                                                                                   |
-| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
-| `- 種別: 不具合`       | `bug`             | 報告された症状を直す。`- 種別: 非不具合` とどちらか一方を必ず置く                          |
-| `- 目的: 機能追加`     | `enhancement`     | 新しい機能。不具合修正・文書のみ・依存更新・保守作業には書かない                           |
-| `- 目的: 機能改善`     | `enhancement`     | 既存機能の改善。目的が曖昧なら期待結果と受け入れ条件を具体化してから選ぶ                   |
-| `- 互換性: 破壊的変更` | `breaking-change` | 既存の利用者・API・設定の契約を変える。移行措置があっても書き、廃止対象と影響を説明する    |
-| `- 種別: 振る舞い変更` | なし              | AI の振る舞いを変える。`## 発火点` / `## ベースライン` / `## 再現` の 3 見出しが必須になる |
+| 宣言                   | 付くラベル                        | 選ぶ基準                                                                                                        |
+| ---------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `- 種別: 不具合`       | `bug`                             | 報告された症状を直す。`- 種別: 非不具合` とどちらか一方を必ず置く                                               |
+| `- 目的: 機能追加`     | `enhancement`                     | 新しい機能。不具合修正・文書のみ・依存更新・保守作業には書かない                                                |
+| `- 目的: 機能改善`     | `enhancement`                     | 既存機能の改善。目的が曖昧なら期待結果と受け入れ条件を具体化してから選ぶ                                        |
+| `- 互換性: 破壊的変更` | `breaking-change`                 | 既存の利用者・API・設定の契約を変える。移行措置があっても書き、廃止対象と影響を説明する                         |
+| `- 種別: 振る舞い変更` | なし                              | AI の振る舞いを変える。`## 発火点` / `## ベースライン` / `## 再現` の 3 見出しが必須になる                      |
+| `- 人の判断: 不要`     | `auto-ok`（除外ラベルがなければ） | 方針の判断・外部アカウント・人の目視確認のどれも要らない。`- 人の判断: 要（<どれか>）` とどちらか一方を必ず置く |
 
 - **持ち主の意図と違う動きは、コード・コメント・テストに書かれた設計どおりでも `- 種別: 不具合` とする。** コードは意図を写したもので、意図そのものではない。変更の形（コードか文書か）でも決めない。例: コメントとテストに固定されたまま意図より広く働く自動付与、文書だけでも意図と違う分類を生む基準
 - **`- 種別: 不具合` の Issue の回帰テストは、利用者が症状を見たのと同じ粒度で書く。** 修正前のツリーでも緑になるテストは `pnpm josh git -y` がコミットを拒否する（joshuafolkken/kit#2448）

package/prompts/review.md

@@ -100,10 +100,14 @@ round-1 High/Medium finding actually closed — by a fix in this working tree, o
 positive — and none was filed or deferred. **Without the flag the answer is `required`**, which is also
 what the command answers to every uncertainty it meets, a missing round-1 snapshot included.
 
-**`skip` has exactly two arms** — **A** (no fix code: the fix delta is empty) and **B** (inert fix
-code: every path in the fix delta is inert by the review-level classification above); the reason line
-names which fired. Why neither weakens the standard: `docs/maintainers/review-history.md` → "The two
-skip arms".
+**`skip` has exactly two arms** — **A** (no fix code: the fix delta is empty) and **B** (a fix that
+leaves what executes unchanged: every path in the fix delta is inert by the review-level classification
+above, `docs/**/*.md`, the root `README.md`, under `prompts/`, or a `.ts` / `.js` / `.svelte` file
+outside `.claude/` whose only change is in comments, a directive comment — lint, type-check, coverage
+or bundler — counting as code); the reason line names which fired. **One path
+outside that set makes the round `required`** — `.claude/**`, `CLAUDE.md`, a test, configuration, a
+code line, or a source file whose comment-free text cannot be read. Why neither arm weakens the
+standard: `docs/maintainers/review-history.md` → "The two skip arms".
 
 **A skipped round is recorded on the Issue**, so the condition stays auditable and can be withdrawn if
 a defect is later traced to a skipped delta:

package/scripts/auto-ok/auto-ok-judge-cli.ts

@@ -0,0 +1,125 @@
+import { fileURLToPath } from 'node:url'
+import { RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { auto_ok_judge_read } from './auto-ok-judge-read'
+import { auto_ok_judge_write } from './auto-ok-judge-write'
+
+// `josh auto-ok:judge` — the open issues `backlogrun` judges for `auto-ok` when a lane is free and
+// nothing is opted in (joshuafolkken/kit#3854), and the record of each judgement.
+//
+// Bare, it lists the issues that still owe a judgement: one number per line on stdout, or `none`, with
+// each title on stderr. The agent reads each one's body and comments (`josh issue:read`) and answers
+// with `--apply <N> --lane|--solo` or `--decline <N> --reason <text>`; which of the two is a reading of
+// the issue, never this command's.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const NONE_TOKEN = 'none'
+const USAGE =
+	'Usage: josh auto-ok:judge [--apply <N> (--lane | --solo) | --decline <N> --reason <text>]'
+
+const OPTIONS = {
+	apply: { type: 'string' },
+	decline: { type: 'string' },
+	lane: { type: 'boolean' },
+	solo: { type: 'boolean' },
+	reason: { type: 'string' },
+} as const
+
+type Values = NonNullable<ReturnType<typeof cli_flags.values_of<typeof OPTIONS>>>
+
+type JudgeRequest =
+	| { kind: 'list' }
+	| { kind: 'apply'; issue: string; run_label: string }
+	| { kind: 'decline'; issue: string; reason: string }
+
+function run_label_of(values: Values): string | undefined {
+	if (values.lane === values.solo) return undefined
+
+	return values.lane === true ? RUN_LANE_LABEL : RUN_SOLO_LABEL
+}
+
+function apply_request(issue: string, values: Values): JudgeRequest | undefined {
+	const run_label = run_label_of(values)
+
+	return run_label === undefined ? undefined : { kind: 'apply', issue, run_label }
+}
+
+function decline_request(issue: string, values: Values): JudgeRequest | undefined {
+	const reason = values.reason?.trim() ?? ''
+
+	return reason === '' ? undefined : { kind: 'decline', issue, reason }
+}
+
+function request_of(values: Values): JudgeRequest | undefined {
+	const issue = values.apply ?? values.decline
+
+	if (issue === undefined) return { kind: 'list' }
+	if (!issue_number_shape.is_issue_number(issue)) return undefined
+
+	return values.apply === undefined ? decline_request(issue, values) : apply_request(issue, values)
+}
+
+function parse_request(argv: ReadonlyArray<string>): JudgeRequest | undefined {
+	const values = cli_flags.values_of(argv, OPTIONS)
+
+	if (values === undefined || (values.apply !== undefined && values.decline !== undefined)) {
+		return undefined
+	}
+
+	return request_of(values)
+}
+
+async function list(): Promise<number> {
+	const owed = await auto_ok_judge_read.owed()
+
+	if (owed === undefined) {
+		console.error('the open issues could not be read')
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (owed.length === 0) console.info(NONE_TOKEN)
+
+	for (const row of owed) {
+		console.error(session_cite.issue(row.number, row.title))
+		console.info(String(row.number))
+	}
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function dispatch(request: JudgeRequest): Promise<number> {
+	const { apply, decline } = auto_ok_judge_write
+
+	if (request.kind === 'list') return await list()
+	if (request.kind === 'decline') return await decline(request.issue, request.reason)
+
+	return await apply(request.issue, request.run_label)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await dispatch(request)
+}
+
+// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const auto_ok_judge_cli = { NONE_TOKEN, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { auto_ok_judge_cli }

package/scripts/auto-ok/auto-ok-judge-read.ts

@@ -0,0 +1,95 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { issue_watch_diff } from '#scripts/issue/issue-watch-diff'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { z } from 'zod'
+import { auto_ok_judge, type JudgeIssue } from './auto-ok-judge'
+
+// The reading half of `josh auto-ok:judge`: the open issues that still owe a judgement, shared by the
+// command's listing and the backlog driver's check for a free lane with nothing opted in.
+//
+// **The driver asks once a minute while it watches**, so it hands in a cache it keeps for its process:
+// an issue seen judged is remembered with its `updatedAt`, and its comments are read again only once
+// that moves — a body edit, a comment or a label change. Without it every watch minute would read the
+// comments of every candidate in the repository.
+
+// The listing cap `auto-ok:next` reads the opted-in pool under; the open backlog is read under the same.
+const LISTING_LIMIT = 200
+// How many comment listings run at once — a handful of `gh` processes, never one per candidate.
+const COMMENT_READ_WIDTH = 4
+
+const row_schema = z.looseObject({
+	number: z.number(),
+	title: z.string(),
+	body: z.string().nullish(),
+	labels: z.array(issue_label_schema),
+	updatedAt: z.string(),
+})
+
+interface JudgeRow extends JudgeIssue {
+	title: string
+	updated_at: string
+}
+
+// An issue's number to the `updatedAt` it was last seen judged at.
+type JudgedCache = Map<number, string>
+
+function to_row(raw: z.infer<typeof row_schema>): JudgeRow {
+	return {
+		number: raw.number,
+		title: raw.title,
+		body: raw.body ?? '',
+		labels: raw.labels.map((label) => label.name),
+		updated_at: raw.updatedAt,
+	}
+}
+
+// `undefined` when the listing could not be read, which is never "nothing to judge".
+async function read_candidates(): Promise<ReadonlyArray<JudgeRow> | undefined> {
+	const { json } = await git_gh_command.issue_list_open_for_judgement(LISTING_LIMIT)
+
+	if (json === undefined) return undefined
+
+	const listing = read_json_listing(json, row_schema)
+
+	if (listing.kind !== 'read') return undefined
+
+	return listing.rows.map((raw) => to_row(raw)).filter((row) => auto_ok_judge.is_candidate(row))
+}
+
+// `true` only for an issue known to owe a judgement: a failed comment read learns nothing, so it is
+// neither counted nor remembered.
+async function owes_judgement(row: JudgeRow, cache: JudgedCache): Promise<boolean> {
+	if (cache.get(row.number) === row.updated_at) return false
+
+	const comments = issue_watch_diff.parse_comments(
+		await git_gh_command.issue_list_comments(String(row.number)),
+	)
+
+	if (comments === undefined) return false
+	if (!auto_ok_judge.is_judged(row.body, comments)) return true
+
+	cache.set(row.number, row.updated_at)
+
+	return false
+}
+
+async function owed(cache: JudgedCache = new Map()): Promise<ReadonlyArray<JudgeRow> | undefined> {
+	const candidates = await read_candidates()
+
+	if (candidates === undefined) return undefined
+
+	const owing = await bounded_pool.bounded_map(
+		candidates,
+		COMMENT_READ_WIDTH,
+		async (row) => await owes_judgement(row, cache),
+	)
+
+	return candidates.filter((_row, index) => owing[index] === true)
+}
+
+const auto_ok_judge_read = { owed }
+
+export type { JudgedCache, JudgeRow }
+export { auto_ok_judge_read }

package/scripts/auto-ok/auto-ok-judge-write.ts

@@ -0,0 +1,109 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_auto_ok, type AutoOkDecision } from '#scripts/issue/issue-auto-ok'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { AUTO_OK_LABEL } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { z } from 'zod'
+import { auto_ok_judge } from './auto-ok-judge'
+
+// The writing half of `josh auto-ok:judge`: the agent's judgement of one open issue, recorded on it.
+//
+// **An applied judgement still passes the mechanical exclusions** — `issue_auto_ok.exclusion_of` is
+// re-read against the labels as they stand, so a label added since the listing refuses the write
+// rather than racing it. **The run label lands before `auto-ok`**, so the pool never holds an opted-in
+// issue that `backlog:next` would withhold as untriaged. Both answers leave the judgement comment the
+// next listing reads as the record, and an applied one is a `note` on the board's 📌.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const UNREADABLE = 'the issue could not be read'
+
+const issue_schema = z.object({ labels: z.array(issue_label_schema), body: z.string().nullish() })
+
+interface IssueRead {
+	labels: ReadonlyArray<string>
+	body: string
+}
+
+async function read_issue(issue: string): Promise<IssueRead | undefined> {
+	const raw = await git_gh_command.issue_get_labels_and_body(issue)
+	const parsed = raw === undefined ? undefined : parse_json_object_or_undefined(raw, issue_schema)
+
+	if (parsed === undefined) return undefined
+
+	return { labels: parsed.labels.map((label) => label.name), body: parsed.body ?? '' }
+}
+
+async function apply_labels(issue: string, run_label: string): Promise<string | undefined> {
+	for (const label of [run_label, AUTO_OK_LABEL]) {
+		// eslint-disable-next-line no-await-in-loop -- the run label must land before `auto-ok`
+		const write = await git_gh_command.issue_apply_label(issue, label)
+
+		if (!write.is_applied) return `could not apply \`${label}\`: ${write.reason}`
+	}
+
+	return undefined
+}
+
+async function record(issue: string, decision: AutoOkDecision, body: string): Promise<number> {
+	try {
+		await git_gh_command.issue_comment(issue, auto_ok_judge.comment_of(decision, body))
+	} catch {
+		console.error(`could not comment the judgement on ${session_cite.issue(issue)}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(issue_auto_ok.line_of(decision))
+
+	return SUCCESS_EXIT_CODE
+}
+
+function refused(issue: string, problem: string): number {
+	console.error(`${session_cite.issue(issue)}: ${problem}`)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function apply_to(issue: string, run_label: string, read: IssueRead): Promise<number> {
+	const exclusion = issue_auto_ok.exclusion_of(read.labels)
+
+	if (exclusion !== undefined) return refused(issue, issue_auto_ok.line_of(exclusion))
+
+	const problem = await apply_labels(issue, run_label)
+
+	if (problem !== undefined) return refused(issue, problem)
+
+	const reason = `judged by backlogrun: no exclusion holds and no person's judgement is needed (${run_label})`
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.NOTE,
+		`${issue_cite.plain(issue)} auto-ok applied (${run_label})`,
+	)
+
+	return await record(issue, { is_applied: true, reason }, read.body)
+}
+
+async function apply(issue: string, run_label: string): Promise<number> {
+	const read = await read_issue(issue)
+
+	if (read === undefined) return refused(issue, UNREADABLE)
+
+	return await apply_to(issue, run_label, read)
+}
+
+async function decline(issue: string, reason: string): Promise<number> {
+	const read = await read_issue(issue)
+
+	if (read === undefined) return refused(issue, UNREADABLE)
+
+	return await record(issue, { is_applied: false, reason }, read.body)
+}
+
+const auto_ok_judge_write = { apply, decline }
+
+export { auto_ok_judge_write }