@joshuafolkken/kit 1.978.0 → 1.983.0

package/prompts/collaboration-workflow/upstream-interrupt.md

@@ -16,7 +16,7 @@
 
 1. **現在の作業を退避する**: `git stash push -u -m "upstream-interrupt: paused #<N>"`（WIP コミットでも可）。退避したことを忘れないよう、この時点で stash を作る。メッセージ付きで積むのは、復元をメッセージで特定するため（下記ステップ 5）
 2. **進行中の Issue に状況を明記する**: `pnpm josh issue:comment <N> --body-file <path>` で、(a) 作業を stash したこと、(b) 中断理由（どの別パッケージの・どんな問題で中断したか）、(c) 対象パッケージに作成した新 Issue へのリンクを `## Upstream issues` 見出しの下に `owner/repo#N` 形式で、を記載する。これにより「なぜこの Issue が一時停止しているか」と「何を待っているのか」が後から監査できる（→「起票元へのバックリンク」）
-3. **対象パッケージのリポジトリに新しい Issue を作成する（確認なし）**: `gh api repos/<owner>/<repo>/issues -f title="<root-cause title>" -f 'labels[]=route:tier-a' -f 'labels[]=depth:<n>' -F body=@<body-file>`（`route:tier-a` は実装中の Tier A 起票を経路として集計するためのラベル — joshuafolkken/kit#1083。付与するのは first-party の場合だけで、third-party はそもそもこの手順に到達せず起票しない）。起票前に `pnpm josh issue:lint <body-file>` を実行し、`labels:` に列挙された分類ラベルをすべて同じ作成呼び出しに付ける。分類の単一ソースは `prompts/collaboration-workflow/issue-template.md`。根本原因・再現・期待結果を Step 1 のテンプレに沿って記載し、**本文に `## Origin` 節を置いて起票元 Issue を `owner/repo#N` 形式で書く**（→「起票元へのバックリンク」）。上流 Issue は欠陥を、起票元 Issue は証拠を持つため、リンクがないと上流 Issue は後から解釈できなくなる。ここで「起票してよいか」を尋ねて停止してはならない。**ただし確認なしで起票してよいのは対象が first-party のときだけ**で、third-party（owner が自リポジトリと一致しないリポジトリ）なら起票せずに停止する（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
+3. **対象パッケージのリポジトリに新しい Issue を作成する（確認なし）**: `pnpm josh issue:file "<root-cause title>" --body-file <body-file> --depth <n> --route tier-a --repo <owner>/<repo>`（`route:tier-a` は実装中の Tier A 起票を経路として集計するためのラベル — joshuafolkken/kit#1083。付与するのは first-party の場合だけで、third-party はコマンド自身が拒否し起票しない）。本文の検査、本文が宣言する分類ラベルの付与、`## Origin` 節の確認、起票先での重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands.md` → `josh issue:file`）。分類の単一ソースは `prompts/collaboration-workflow/issue-template.md`。根本原因・再現・期待結果を Step 1 のテンプレに沿って記載し、**本文に `## Origin` 節を置いて起票元 Issue を `owner/repo#N` 形式で書く**（→「起票元へのバックリンク」）。上流 Issue は欠陥を、起票元 Issue は証拠を持つため、リンクがないと上流 Issue は後から解釈できなくなる。ここで「起票してよいか」を尋ねて停止してはならない。**ただし確認なしで起票してよいのは対象が first-party のときだけ**で、third-party（owner が自リポジトリと一致しないリポジトリ）なら起票せずに停止する（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
 4. **`confirmation` Telegram を送って停止する**: 上流 Issue の URL と、何が止まっているかを本文に書く（→「確認待ちで停止するときの Telegram 通知（`confirmation`）」）。無人実行でも画面外でユーザーが気付ける。停止は Issue が既に存在する状態で行うので、ユーザーは「待つ / 先送りする」を Issue を見ながら 1 語で答えられる
 5. **元の作業を再開する**: 上流の修正がマージされた、または**ユーザーが先送りを明示判断した**後に `pnpm josh stash:pop "upstream-interrupt: paused #<N>"`（位置指定や引数なしの `git stash pop` は使わない — stash は全 work tree が共有する 1 本のスタックで、別のレーンの stash を取り込む恐れがある）して、退避していた元タスクを続行する。上流 Issue を割り込みで実装するかどうかもユーザーの判断（上流パッケージの実装・PR・マージはそれぞれのワークフロー規則に従う）
 

package/prompts/collaboration-workflow/wip-cap.md

@@ -2,7 +2,7 @@
 
 **単一ソースはこのファイルである。**
 
-**この規則は常駐していない — 引き金つき配送に移った**（joshuafolkken/kit#1524）。`pnpm josh rule:guard` が Issue を作成する `Bash` 呼び出し（`gh issue create`、または `…/issues` への `title` 付き POST）を拒否し、そこで数え方・拒否・2 つの免除・免除を決める 3 条件を突きつける。起票が無いターンでは何も起きず、それは上限に触れる行為が無いということである。配送は**ラン 1 回につき 1 度**なので、数えたうえで同じ呼び出しをもう一度出せばよい。機構と列挙表は `rule-delivery.md`、配送文の実体は `scripts/rules/delivered-rules.ts` の `WIP_CAP_REASON` にあり、`scripts/backlog/backlog-manufacturing-rule.test.ts` がその中身を固定している。
+**この規則は常駐していない — 引き金つき配送に移った**（joshuafolkken/kit#1524）。`pnpm josh rule:guard` が Issue を作成する `Bash` 呼び出し（`pnpm josh issue:file`。`gh issue create` や `…/issues` への `title` 付き POST による直接起票は `direct-filing` が毎回拒否する）を拒否し、そこで数え方・拒否・2 つの免除・免除を決める 3 条件を突きつける。起票が無いターンでは何も起きず、それは上限に触れる行為が無いということである。配送は**ラン 1 回につき 1 度**なので、数えたうえで同じ呼び出しをもう一度出せばよい。機構と列挙表は `rule-delivery.md`、配送文の実体は `scripts/rules/delivered-rules.ts` の `WIP_CAP_REASON` にあり、`scripts/backlog/backlog-manufacturing-rule.test.ts` がその中身を固定している。
 
 ## 規則
 
@@ -69,10 +69,10 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 
 #### 該当したときの手順
 
-1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。起票前に `pnpm josh issue:lint <body-file>` を実行し、その `labels:` に列挙された分類ラベルをすべて同じ作成呼び出しに付ける。`prompts/collaboration-workflow/issue-template.md` の手順に従う。
+1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。起票は `pnpm josh issue:file` で行う。本文の検査、本文が宣言する分類ラベルの付与、重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands.md` → `josh issue:file`）。
 
    ```bash
-   gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=route:interrupt' -f 'labels[]=depth:<n>' -F body=@<body-file>
+   pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route interrupt
    ```
 
 2. **超過している事実と、当たった条件の番号を本文に 1 行書く**（例:「オープン 37 件で起票。3 条件のうち 2（文書化された手順が完了できない）に該当」）。**どちらか一方では足りない** — 件数だけでは判定が再現できず、条件だけでは上限の可視化が効かない。

package/prompts/review.md

@@ -183,7 +183,7 @@ Only branch 2 files an Issue. What follows applies to that branch.
   than being deferred — see below.)
 - **Filing does not end at the Issue.** `epic:next` only ever offers a child the task list of an epic
   names, so an Issue in no epic is never handed to a running `backlogrun` — the deferred finding is parked
-  forever, which reads the same from the backlog. **The three steps run inside the CI wait, not before
+  forever, which reads the same from the backlog. **The steps run inside the CI wait, not before
   the commit.** Where the run opens a pull request — `fullrun`, `backlogrun` — they go after
   `pnpm josh git -y` and before `pnpm josh followup`; where it does not — `halfrun`, or a standalone
   pre-commit self-review — they run as soon as the disposition is decided. **The chain may run in a
@@ -191,14 +191,16 @@ Only branch 2 files an Issue. What follows applies to that branch.
 - **When the round files a second follow-up, run `pnpm josh issue:fold` first.** Several findings from
   one review fold into one Issue by default — the filing-time counterpart to the split assessment,
   reading the same two questions (`.claude/skills/workflow-commands/split-assessment.md` → "The same
-  two questions decide the filing-time fold"). `pnpm josh rule:guard` refuses the second `gh api …
-issues` call until it is folded; the first filing asks nothing.
-
-  1. File the follow-up Issue referencing the current one, tagged `route:review-cap`. Run `pnpm josh issue:lint <body-file>` first and apply every label in its `labels:` answer at creation, following `prompts/collaboration-workflow/issue-template.md`:
-     `gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=route:review-cap' -f 'labels[]=depth:<n>' -F body=@<body-file>`.
-  2. Run `pnpm josh epic:bundle <new>` — **before the current Issue closes.** The candidate search reads
-     open issues only, so once the parent has closed the command answers `none` permanently.
-  3. Act on its answer. **`epic:bundle` recommends and writes nothing**, so acting means running the
+  two questions decide the filing-time fold"). `pnpm josh rule:guard` refuses the second
+  `pnpm josh issue:file` call until it is folded; the first filing asks nothing.
+
+  1. File the follow-up Issue referencing the current one, tagged `route:review-cap` — **before the current Issue closes.**
+     `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route review-cap`.
+     The command lints the body, applies the classification labels it declares, runs the duplicate scan
+     and then `epic:bundle` on the new Issue (`docs/josh-commands.md` → `josh issue:file`). The
+     `epic:bundle` candidate search reads open issues only, so once the parent has closed it answers
+     `none` permanently.
+  2. Act on the `epic:bundle` answer it prints. **`epic:bundle` recommends and writes nothing**, so acting means running the
      write command yourself — never a hand edit of the epic body, which leaves the task list and the
      `blocked-by` relations disagreeing and `epic:next` returning `error`.
 

package/scripts/delegation/delegation-policy.ts

@@ -53,16 +53,16 @@ const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
 	},
 	{
 		name: 'followup-filing',
-		// The late-run follow-up filing chain — issue:scout → file the Issue → epic:bundle → epic --add
-		// — is a dependency chain `batch:guard` correctly keeps one call per step, and what makes it
-		// expensive is the ~340k context it runs in at the tail of a run, not the step count
-		// (joshuafolkken/kit#1892). A fresh unit runs the same chain at a small context, and the review
-		// round cap already composed the finding text, so what the unit is handed is mechanical: run the
-		// four commands and act on their deterministic answers. This is not `batch:guard`'s business —
-		// the chain stays one call per step; delegation only moves it to a cheaper context.
-		does: 'run the late-run follow-up filing chain in an isolated unit — issue:scout, file the Issue, epic:bundle, epic --add — given the finding text the parent already composed, and return the new Issue number and the epic:bundle answer',
+		// The late-run follow-up filing chain — `issue:file` (which scouts, lints, labels and runs
+		// epic:bundle itself, joshuafolkken/kit#2808) → epic --add — is a dependency chain `batch:guard`
+		// correctly keeps one call per step, and what makes it expensive is the ~340k context it runs in
+		// at the tail of a run, not the step count (joshuafolkken/kit#1892). A fresh unit runs the same
+		// chain at a small context, and the review round cap already composed the finding text, so what
+		// the unit is handed is mechanical: run the commands and act on their deterministic answers. This
+		// is not `batch:guard`'s business — delegation only moves the chain to a cheaper context.
+		does: 'run the late-run follow-up filing chain in an isolated unit — issue:file (scout, lint, labels, epic:bundle), then epic --add — given the finding text the parent already composed, and return the new Issue number and the epic:bundle answer',
 		verifier:
-			"the parent reads the filed Issue from GitHub with `pnpm josh issue:state <new>`, not the unit's summary; a follow-up reported filed but not created is still absent, the way `epic-child`'s reported-done-but-not-merged child is still open. The finding text came from the parent and `issue:scout` / `epic:bundle` are deterministic, so the unit's work is the mechanical execution `issue:state` confirms",
+			"the parent reads the filed Issue from GitHub with `pnpm josh issue:state <new>`, not the unit's summary; a follow-up reported filed but not created is still absent, the way `epic-child`'s reported-done-but-not-merged child is still open. The finding text came from the parent and `issue:file`'s steps are deterministic, so the unit's work is the mechanical execution `issue:state` confirms",
 	},
 	{
 		name: 'implementation-unit',

package/scripts/document/document-byte-budget.ts

@@ -82,7 +82,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/rule-residency.md', bytes: 24_576 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	{ path: 'docs/josh-commands.md', bytes: 172_032 },
+	{ path: 'docs/josh-commands.md', bytes: 176_128 },
 	{ path: 'prompts/agent-rules.md', bytes: 4096 },
 	{ path: 'prompts/coding-standards.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },

package/scripts/issue/issue-file-cli.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { repo_party } from '#scripts/discovery/repo-party'
+import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
+import { github_issue_url } from '#scripts/git/github-issue-url'
+import { issue_file, type FileArguments } from './issue-file'
+import { issue_lint_cli } from './issue-lint-cli'
+import { issue_scout_cli } from './issue-scout-cli'
+
+// `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
+// [--repo <owner/repo>] [--distinct <N,…>]` — file an Issue with every filing step run in order
+// (joshuafolkken/kit#2808): the third-party refusal, the body lint, the `## Origin` check for another
+// repository, the duplicate scout, the create call carrying every label, and `epic:bundle` after it.
+// A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE =
+	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>]'
+const UNKNOWN_REPO_MESSAGE =
+	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
+const THIRD_PARTY_MESSAGE =
+	'✖ third-party target: a tracker we do not own is Tier C — draft the Issue for a person to post instead (`CLAUDE.md` → "Third-party repositories are Tier C").'
+// `GH_REPO` is the variable `gh` reads `{owner}/{repo}` from, so setting it points every listing the
+// scout and `epic:bundle` make at the target repository rather than at this checkout.
+const GH_REPO_VARIABLE = 'GH_REPO'
+
+interface Filing {
+	args: FileArguments
+	body: string
+	target: string
+	current: string
+}
+
+async function read_body(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function is_third_party(target: string): boolean {
+	const party = repo_party.classify(repo_party.current_owner(), repo_party.target_owner(target))
+
+	return party === repo_party.THIRD_PARTY
+}
+
+// Every refusal the filing can meet before a request is sent, in the order the steps run — `[]` when
+// the filing may go on to the scout.
+function refusals_of(filing: Filing): ReadonlyArray<string> {
+	if (is_third_party(filing.target)) return [THIRD_PARTY_MESSAGE]
+	const problems = issue_lint_cli.problems(filing.body).map((problem) => `✖ ${problem}`)
+	const origin = issue_file.origin_problem(filing.body, filing.target, filing.current)
+
+	return origin === undefined ? problems : [...problems, `✖ ${origin}`]
+}
+
+function unacknowledged_message(numbers: ReadonlyArray<number>): string {
+	const listed = numbers.map(String).join(',')
+
+	return `✖ duplicate candidate(s) ${listed} not declared separate — read each (\`issue-fold-existing.md\`); fold into a duplicate, or reissue with \`--distinct ${listed}\` when each is a separate deliverable.`
+}
+
+// Set before the scout and left set for `epic:bundle`, so both read the target's backlog.
+function point_listings_at(filing: Filing): void {
+	if (issue_file.is_same_repository(filing.target, filing.current)) return
+
+	process.env[GH_REPO_VARIABLE] = filing.target
+}
+
+// The scout's report is printed whatever it finds, and the filing is held until every candidate it
+// names is declared separate.
+async function is_scout_clear(filing: Filing): Promise<boolean> {
+	point_listings_at(filing)
+	const outcome = await issue_scout_cli.scout(
+		{ title: filing.args.title, body: filing.body },
+		filing.target,
+	)
+
+	if (outcome === undefined) return false
+	console.info(outcome.report)
+	const open = issue_file.unacknowledged(outcome.candidates, filing.args.distinct)
+
+	if (open.length > 0) console.error(unacknowledged_message(open))
+
+	return open.length === 0
+}
+
+// `undefined` when the create call failed. `gh`'s standard error is captured into the thrown error
+// rather than printed, so it is printed here — otherwise the filing fails with no reason given.
+async function create(filing: Filing): Promise<string | undefined> {
+	const request = git_gh_issue_write.issue_create_request({
+		title: filing.args.title,
+		body: filing.body,
+		labels: issue_file.labels_of(filing.args, filing.body),
+		repo: filing.target,
+	})
+
+	try {
+		return await git_gh_exec.exec_gh_api(request)
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error)
+
+		console.error(`✖ the create call failed: ${reason}`)
+
+		return undefined
+	}
+}
+
+// The Issue exists once `create` returns, so a failed placement is reported rather than failed: a
+// non-zero exit would read as "not filed" and invite the second filing the scout exists to stop.
+async function place(url: string, target: string): Promise<void> {
+	const issue_number = Number(github_issue_url.parse(url)?.issue_number)
+	const exit_code = Number.isSafeInteger(issue_number)
+		? await epic_bundle_cli.report_for(issue_number, target)
+		: FAILURE_EXIT_CODE
+
+	if (exit_code !== SUCCESS_EXIT_CODE) {
+		console.error(`⚠ epic:bundle did not answer for ${url} — run \`pnpm josh epic:bundle <N>\`.`)
+	}
+}
+
+async function file(filing: Filing): Promise<number> {
+	const refusals = refusals_of(filing)
+
+	if (refusals.length > 0) {
+		console.error(refusals.join('\n'))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (!(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
+	const url = await create(filing)
+
+	if (url === undefined) return FAILURE_EXIT_CODE
+	console.info(url)
+	await place(url, filing.target)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function filing_of(args: FileArguments): Promise<Filing | string> {
+	const body = await read_body(args.body_file)
+
+	if (body === undefined) return `Could not read the body file ${args.body_file}.`
+	const current = await git_gh_command.repo_get_name_with_owner()
+
+	if (current === undefined) return UNKNOWN_REPO_MESSAGE
+
+	return { args, body, target: args.repo ?? current, current }
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const args = issue_file.parse(argv)
+
+	if (args === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const filing = await filing_of(args)
+
+	if (typeof filing === 'string') {
+		console.error(filing)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await file(filing)
+}
+
+// `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 issue_file_cli = { USAGE, THIRD_PARTY_MESSAGE, UNKNOWN_REPO_MESSAGE, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_file_cli }

package/scripts/issue/issue-file.ts

@@ -0,0 +1,192 @@
+import { parseArgs } from 'node:util'
+import { epic_issue } from '#scripts/epic/epic-issue'
+import { github_issue_url } from '#scripts/git/github-issue-url'
+import { DEPTH_LABEL_ORDER, FILING_ROUTE_LABELS, has_label_name } from '#scripts/git/issue-labels'
+import { issue_backlinks } from './issue-backlinks'
+import { issue_classification } from './issue-classification'
+import { markdown_section } from './markdown-section'
+
+// The decisions behind `josh issue:file` (joshuafolkken/kit#2808), kept apart from the command that
+// reads the network so each one is a pure answer a test can pin. Every filing used to be a hand-built
+// `gh api …/issues` call beside five steps spread over as many documents, and joshuafolkken/kit#2805
+// ran two of them and skipped the lint and the labels. Here the steps are the command's arguments:
+// a label the filing owes is a required option rather than a line to remember.
+
+const DEPTH_PREFIX = 'depth:'
+const ROUTE_PREFIX = 'route:'
+const LIST_SEPARATOR = ','
+const WORD_SEPARATOR = /\s+/u
+const CODE_SPAN = /`/gu
+// Prose written against a reference with no space — `(owner/repo#N)`, `owner/repo#N。`, Japanese text
+// after the number — is trimmed off, so the anchored parsers below still see the reference itself.
+const LEADING_NON_WORD = /^[^\w]+/u
+const DIGIT = /\d/u
+
+interface FileArguments {
+	title: string
+	body_file: string
+	depth: string
+	route: string | undefined
+	labels: ReadonlyArray<string>
+	repo: string | undefined
+	distinct: ReadonlyArray<number>
+}
+
+const OPTIONS = {
+	'body-file': { type: 'string' },
+	depth: { type: 'string' },
+	route: { type: 'string' },
+	label: { type: 'string', multiple: true },
+	repo: { type: 'string' },
+	distinct: { type: 'string', multiple: true },
+} as const
+
+// The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
+// label sets `issue-labels.ts` defines, so the command cannot apply a depth or route nobody provisions.
+function label_of(
+	prefix: string,
+	value: string | undefined,
+	known: ReadonlyArray<string>,
+): string | undefined {
+	if (value === undefined) return undefined
+	const label = value.startsWith(prefix) ? value : `${prefix}${value}`
+
+	return known.includes(label) ? label : undefined
+}
+
+const ROUTE_NAMES: ReadonlyArray<string> = FILING_ROUTE_LABELS.map((label) => label.name)
+
+// `--distinct 12,34 --distinct 56` → `[12, 34, 56]`; `undefined` when any entry is not an issue number,
+// so a typo is refused rather than read as an acknowledgement of nothing.
+function distinct_numbers(values: ReadonlyArray<string>): ReadonlyArray<number> | undefined {
+	const numbers = values
+		.flatMap((value) => value.split(LIST_SEPARATOR))
+		.map((raw) => {
+			return Number(raw.trim().replace('#', ''))
+		})
+
+	return numbers.every((number) => Number.isSafeInteger(number) && number > 0) ? numbers : undefined
+}
+
+type ParsedValues = ReturnType<typeof parseArgs<{ options: typeof OPTIONS }>>['values']
+
+function route_of(values: ParsedValues): string | undefined | false {
+	if (values.route === undefined) return undefined
+
+	return label_of(ROUTE_PREFIX, values.route, ROUTE_NAMES) ?? false
+}
+
+function has_text(value: string | undefined): value is string {
+	return value !== undefined && value.trim() !== ''
+}
+
+// The labelled half of the arguments, or `undefined` when a depth, route or `--distinct` entry is not
+// one the command knows.
+function labelled_of(
+	values: ParsedValues,
+): Pick<FileArguments, 'depth' | 'route' | 'distinct'> | undefined {
+	const depth = label_of(DEPTH_PREFIX, values.depth, DEPTH_LABEL_ORDER)
+	const route = route_of(values)
+	const distinct = distinct_numbers(values.distinct ?? [])
+
+	if (route === false || depth === undefined || distinct === undefined) return undefined
+
+	return { depth, route, distinct }
+}
+
+function arguments_of(values: ParsedValues, title: string | undefined): FileArguments | undefined {
+	const labelled = labelled_of(values)
+	const body_file = values['body-file']
+
+	if (labelled === undefined || !has_text(title) || !has_text(body_file)) return undefined
+
+	return { title, body_file, ...labelled, labels: values.label ?? [], repo: values.repo }
+}
+
+// An unknown flag makes `parseArgs` throw; caught so the answer is the usage line, not a stack trace.
+function parse(argv: ReadonlyArray<string>): FileArguments | undefined {
+	try {
+		const { values, positionals } = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			allowPositionals: true,
+		})
+
+		return arguments_of(values, positionals[0])
+	} catch {
+		return undefined
+	}
+}
+
+// A classification label is the body's to declare, so an extra `--label` naming one the body does not
+// declare is dropped rather than applied — the label then always matches what `issue:lint` reads.
+function is_undeclared_classification(label: string, body: string): boolean {
+	const is_classification = has_label_name(issue_classification.CLASSIFICATION_LABELS, label)
+
+	return is_classification && !has_label_name(issue_classification.required_labels(body), label)
+}
+
+// Every label the filing carries: the depth, the route when there is one, the classification labels
+// the body declares (`issue_classification.labels_for`, which merges case-insensitively), then any
+// extra `--label`. One request applies them all, so no label is a separate step to forget.
+function labels_of(args: FileArguments, body: string): ReadonlyArray<string> {
+	const extra = args.labels.filter((label) => !is_undeclared_classification(label, body))
+	const declared = [args.depth, ...(args.route === undefined ? [] : [args.route]), ...extra]
+
+	return issue_classification.labels_for(body, declared)
+}
+
+function is_same_repository(target: string, current: string): boolean {
+	return target.toLowerCase() === current.toLowerCase()
+}
+
+// `owner/repo#N` or a github.com issue URL — the qualified forms the issue template's backlink section
+// requires, never a bare `#N`, which resolves to whichever repository renders it. Read through the
+// parsers that already know both forms rather than a third pattern.
+function without_trailing_prose(text: string): string {
+	let end = text.length
+
+	while (end > 0 && !DIGIT.test(text.charAt(end - 1))) end -= 1
+
+	return text.slice(0, end)
+}
+
+function is_qualified_reference(word: string): boolean {
+	const bare = without_trailing_prose(word.replaceAll(CODE_SPAN, '').replace(LEADING_NON_WORD, ''))
+
+	return (
+		epic_issue.parse_epic_reference(bare)?.repo !== undefined ||
+		github_issue_url.parse(bare) !== undefined
+	)
+}
+
+function cites_origin(line: string): boolean {
+	return line.split(WORD_SEPARATOR).some((word) => is_qualified_reference(word))
+}
+
+// Why a cross-repository filing is refused, or `undefined` when it is not refused. A filing into the
+// session's own repository owes no `## Origin`; one into another repository owes the section with a
+// qualified reference back to the Issue that found it (`issue-template.md`, the backlink section).
+function origin_problem(body: string, target: string, current: string): string | undefined {
+	if (is_same_repository(target, current)) return undefined
+	const lines = markdown_section.section_lines(body, issue_backlinks.ORIGIN_HEADING)
+
+	if (lines.some((line) => cites_origin(line))) return undefined
+
+	return `filing into ${target} from ${current} needs a \`${issue_backlinks.ORIGIN_HEADING}\` section citing the originating Issue as \`owner/repo#N\` or its URL`
+}
+
+// The duplicate candidates the caller has not declared separate. The scan cannot tell a duplicate from
+// a neighbor — that is a reading of each candidate (`issue-fold-existing.md`) — so the command holds
+// the filing until every candidate it printed is named back with `--distinct`.
+function unacknowledged(
+	candidates: ReadonlyArray<number>,
+	distinct: ReadonlyArray<number>,
+): ReadonlyArray<number> {
+	return candidates.filter((candidate) => !distinct.includes(candidate))
+}
+
+const issue_file = { parse, labels_of, origin_problem, unacknowledged, is_same_repository }
+
+export type { FileArguments }
+export { issue_file }

package/scripts/issue/issue-lint-cli.ts

@@ -58,7 +58,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv[0])
 }
 
-const issue_lint_cli = { run, OK_MESSAGE, USAGE }
+const issue_lint_cli = { problems, run, OK_MESSAGE, USAGE }
 
 const ARGV_OFFSET = 2