@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/release/github-release.ts

@@ -1,6 +1,7 @@
 import { setTimeout } from 'node:timers/promises'
 import semver from 'semver'
 import { z } from 'zod'
+import { github_release_runs, type PollState, type RunSource } from './github-release-runs'
 
 const API_ROOT = 'https://api.github.com/repos'
 const LATEST_PATH = '/releases/latest'
@@ -8,42 +9,26 @@ const REPOSITORY_PATTERN = /^[\w.-]+\/[\w.-]+$/u
 const TAG_PATTERN = /^v\d+\.\d+\.\d+(?:[.-][0-9A-Za-z.-]+)?$/u
 const REQUEST_TIMEOUT_MS = 30_000
 const NOT_FOUND_STATUS = 404
-// A job skipped by its `if:` (or neutral) belongs to a run that succeeded; counting it would skip a
-// lower tag whose release is still on its way.
-const FAILED_CONCLUSIONS = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure'])
 const POLL_INTERVAL_MS = 30_000
 const MAX_WAIT_ATTEMPTS = 120
 const RELEASE_SCHEMA = z.object({ tag_name: z.string().min(1) })
 const NOTES_SCHEMA = z.object({ name: z.string().min(1), body: z.string().min(1) })
-const RUN_SCHEMA = z.object({
-	id: z.number(),
-	display_title: z.string(),
-	status: z.string().optional(),
-	conclusion: z.string().nullable().optional(),
-})
-const JOB_SCHEMA = z.object({
-	name: z.string(),
-	status: z.string(),
-	conclusion: z.string().nullable(),
-})
-const RUNS_SCHEMA = z.object({ workflow_runs: z.array(RUN_SCHEMA) })
-const JOBS_SCHEMA = z.object({ jobs: z.array(JOB_SCHEMA) })
-
 type ReleaseRequest = (url: string, init: RequestInit) => Promise<Response>
 type Wait = () => Promise<void>
-type PollState = 'ready' | 'failed' | 'pending'
 
 // What differs between repositories. `start_tag` is the last tag that predates automatic releases;
 // without it the latest existing release is the floor. `workflow` names the publish workflow whose
 // failed run lets a lower tag be skipped, and `jobs` the jobs in it that count (empty: every job).
 // `await_publish` holds the tag's own release until its run in that workflow has succeeded, for a
-// release started beside the publication rather than from inside it.
+// release started beside the publication rather than from inside it. `release_run_workflow` names
+// the workflow whose run creates a tag's release, so a lower tag left without one can be told lost.
 interface ReleaseSettings {
 	repository: string
 	start_tag?: string | undefined
 	workflow?: string | undefined
 	jobs?: ReadonlyArray<string> | undefined
 	await_publish?: boolean | undefined
+	release_run_workflow?: string | undefined
 }
 
 interface PublishOptions extends ReleaseSettings {
@@ -51,12 +36,10 @@ interface PublishOptions extends ReleaseSettings {
 	wait?: Wait
 }
 
-interface Client {
+interface Client extends Omit<RunSource, 'read'> {
 	request: ReleaseRequest
 	token: string
 	url: string
-	workflow: string | undefined
-	jobs: ReadonlyArray<string>
 }
 
 // `fallback` answers when no tag sits between the floor and the target; without one the floor itself
@@ -139,59 +122,21 @@ function predecessor(
 		.toSorted((left, right) => semver.compare(right, left))[0]
 }
 
-function is_failed_job(job: z.infer<typeof JOB_SCHEMA>, names: ReadonlyArray<string>): boolean {
-	if (job.status !== 'completed' || !FAILED_CONCLUSIONS.has(job.conclusion ?? '')) return false
-	if (names.length === 0) return true
-
-	return names.some((name) => job.name === name || job.name.startsWith(`${name} /`))
-}
-
-async function publish_run(
-	client: Client,
-	workflow_name: string,
-	tag: string,
-): Promise<z.infer<typeof RUN_SCHEMA> | undefined> {
-	const workflow = encodeURIComponent(workflow_name)
-	const runs_response = await api_get(client, `/actions/workflows/${workflow}/runs?per_page=100`)
-	const runs = RUNS_SCHEMA.parse(await read_response(runs_response)).workflow_runs
-
-	return runs.find((item) => item.display_title === `Publish ${tag}`)
-}
-
-async function failed_publication(client: Client, tag: string): Promise<boolean> {
-	if (client.workflow === undefined) return false
-
-	const run = await publish_run(client, client.workflow, tag)
-	if (!run) return false
-
-	const jobs_response = await api_get(client, `/actions/runs/${String(run.id)}/jobs?per_page=100`)
-	const { jobs } = JOBS_SCHEMA.parse(await read_response(jobs_response))
-
-	return jobs.some((job) => is_failed_job(job, client.jobs))
+function run_source(client: Client): RunSource {
+	return { ...client, read: async (path) => await read_response(await api_get(client, path)) }
 }
 
 async function default_wait(): Promise<void> {
 	await setTimeout(POLL_INTERVAL_MS)
 }
 
+// The lost state is read before the release: a run completes only after creating the release, so a
+// run that completes between the two reads still shows its release to the second one.
 async function release_state(client: Client, tag: string): Promise<PollState> {
+	const is_lost = await github_release_runs.is_release_lost(run_source(client), tag)
 	if (await existing_release(client, tag)) return 'ready'
-	if (await failed_publication(client, tag)) return 'failed'
-
-	return 'pending'
-}
-
-// A run not listed yet is pending too: the announcement that starts this release also starts the
-// publication, so the release can ask before GitHub has queued that run.
-async function publication_state(
-	client: Client,
-	workflow: string,
-	tag: string,
-): Promise<PollState> {
-	const run = await publish_run(client, workflow, tag)
-	if (run?.status !== 'completed') return 'pending'
 
-	return run.conclusion === 'success' ? 'ready' : 'failed'
+	return is_lost ? 'failed' : 'pending'
 }
 
 async function poll(
@@ -225,7 +170,7 @@ async function wait_for_publication(client: Client, tag: string, budget: Budget)
 	if (workflow === undefined) throw new Error('Waiting for the publication needs RELEASE_WORKFLOW')
 
 	return await poll(
-		async () => await publication_state(client, workflow, tag),
+		async () => await github_release_runs.publication_state(run_source(client), workflow, tag),
 		budget,
 		`Publish ${tag}`,
 	)
@@ -325,6 +270,7 @@ function create_client(request: ReleaseRequest, token: string, settings: Release
 		url: `${API_ROOT}/${settings.repository}`,
 		workflow: settings.workflow,
 		jobs: settings.jobs ?? [],
+		release_run_workflow: settings.release_run_workflow,
 	}
 }
 

package/scripts/repo/repository-labels.ts

@@ -52,9 +52,9 @@ function label_names(labels: ReadonlyArray<LabelDefinition>): ReadonlyArray<stri
 
 // An unreadable listing is not an empty one: nothing is created, and every label is reported as
 // unconfirmed rather than as missing. An unresolved repository (no GitHub remote) is the same case.
-function unreadable(repo: string | undefined): ReadonlyArray<string> {
+function unreadable(repo: string | undefined = 'this repository'): ReadonlyArray<string> {
 	const names = label_names(REPOSITORY_LABELS)
-	const target = repo ?? 'this repository'
+	const target = repo
 
 	console.warn(
 		`  ⚠ could not read the labels of ${target}; make sure these exist: ${names.join(', ')}`,

package/scripts/repo/required-checks-logic.ts

@@ -72,9 +72,7 @@ function workflow_job_names(content: string): Array<string> {
 	const parsed = workflow_schema.safeParse(parse_yaml_safe(content))
 	if (!parsed.success) return []
 
-	return Object.values(parsed.data.jobs).flatMap((job) =>
-		job.name === undefined ? [] : [job.name],
-	)
+	return Object.values(parsed.data.jobs).flatMap((job) => job.name ?? [])
 }
 
 // The checks this repository should require: only those a workflow it has actually reports. A file

package/scripts/review/live-evidence.ts

@@ -16,12 +16,10 @@ import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-l
 
 const EVIDENCE_HEADING = '## 実機証跡'
 
-function verdict_for(paths: ReadonlyArray<string>, body: string | undefined): Verdict {
+function verdict_for(paths: ReadonlyArray<string>, body: string | undefined = ''): Verdict {
 	if (test_declared_logic.runtime_files(paths).length === 0) return 'exempt'
 
-	return reproduction_measure.has_command_output(body ?? '', EVIDENCE_HEADING)
-		? 'satisfied'
-		: 'required'
+	return reproduction_measure.has_command_output(body, EVIDENCE_HEADING) ? 'satisfied' : 'required'
 }
 
 // The diff is this checkout's, so it answers for the named branch only when that is the one checked

package/scripts/review/review-brief-cli.ts

@@ -13,7 +13,7 @@ import { find_package_directory } from '#scripts/josh/josh-logic'
 import { path_decision } from '#scripts/josh/path-decision'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { openai_review_broker } from '#scripts/lane/openai-review-broker'
-import { run_ship_review } from '#scripts/run/run-ship-review'
+import { run_ship_review } from '#scripts/run/ship/run-ship-review'
 import { review_attest } from './review-attest'
 import { review_brief } from './review-brief'
 import { review_checkout, type ReviewCheckout } from './review-checkout'

package/scripts/review/review-finding-ledger.ts

@@ -1,7 +1,7 @@
 // The review-finding line's grammar, its category vocabulary and the aggregation over it — the single
 // place all three are defined (joshuafolkken/kit#2325). A `/code-review` round's findings evaporated
 // the moment they were fixed, so no one could say which category recurred. They now land in the same
-// append-only ledger the observation lines use (`docs/maintainers/observations/`), under a distinct `- rf:`
+// append-only ledger the observation lines use (`.josh/observations/`), under a distinct `- rf:`
 // prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger,
 // one commit path, a second line *type* rather than a second ledger.
 

package/scripts/review/review-findings-cli.ts

@@ -19,9 +19,7 @@ function zero_line(zero_rounds: number): string {
 }
 
 function format_report(counts: ReadonlyArray<CategoryCount>, zero_rounds: number): string {
-	if (counts.length === 0) {
-		return zero_rounds === 0 ? NO_FINDINGS : zero_line(zero_rounds)
-	}
+	if (counts.length === 0) return zero_rounds === 0 ? NO_FINDINGS : zero_line(zero_rounds)
 
 	const body = counts.map((entry) => count_line(entry)).join('\n')
 

package/scripts/rules/decision-oracle-batch.ts

@@ -0,0 +1,128 @@
+import type { DecisionOracle } from './decision-oracle'
+import { oracle_tokens } from './decision-oracle-tokens'
+
+// The batch oracles — the lane cut, the backlog budget and offer, the epic and post-merge steps, and
+// `run:step` — kept beside the enumeration rather than inside it because `decision-oracle.ts` reached
+// its file-size limit (joshuafolkken/kit#3264). They are one contiguous run of `DECISION_ORACLES`, so
+// spreading them back in at the same position keeps the printed listing's order unchanged.
+
+const {
+	BUSY,
+	EXCLUDE_ARG,
+	HUMAN_REVIEW,
+	ISSUE_N_ARG,
+	NONE,
+	NOT_A_LANE,
+	OVER,
+	RETRY,
+	STOP,
+	UNKNOWN,
+	WAIT,
+} = oracle_tokens
+
+const PRE_GATE_CUT_MD = '.claude/skills/workflow-commands/pre-gate-cut.md'
+const BACKLOGRUN_MD = '.claude/skills/workflow-commands/backlogrun.md'
+
+// The command reference in `docs/josh-commands.md` — one section per command, headed by the command
+// itself. joshuafolkken/kit#2190 cut `backlogrun.md` back to a manifest of pointers, so a decision it
+// used to carry inline (`run:merge`, `epic:next`, `backlog:budget`, `run:liveness`, `auto-ok:next`)
+// now has its verdict contract only in this reference. That makes it the single source and the section
+// a reader is routed to, in the same `file.md → \`josh <command>\`` form the `epic:reconcile` and
+// `lane:list` entries already use. joshuafolkken/kit#2254.
+const RUN_MERGE_REFERENCE = 'docs/josh-commands-run.md → `josh run:merge`'
+const EPIC_NEXT_REFERENCE = 'docs/josh-commands-backlog.md → `josh epic:next`'
+const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands-backlog.md → `josh backlog:budget`'
+const RUN_LIVENESS_REFERENCE = 'docs/josh-commands-run.md → `josh run:liveness`'
+const AUTO_OK_NEXT_REFERENCE = 'docs/josh-commands-backlog.md → `josh auto-ok:next`'
+
+// Command used by two separate oracle entries (run:cut:resume and run:cut:gate).
+const RUN_CUT_CMD = 'run:cut'
+
+const BATCH_ORACLES: ReadonlyArray<DecisionOracle> = [
+	{
+		name: 'run:cut:resume',
+		command: RUN_CUT_CMD,
+		decision: 'Whether a lane child is resuming prior work or starting fresh',
+		args: `--resume ${ISSUE_N_ARG}`,
+		vocabulary: ['fresh', 'resume', NOT_A_LANE],
+		single_source: PRE_GATE_CUT_MD,
+	},
+	{
+		name: 'run:cut:gate',
+		command: RUN_CUT_CMD,
+		decision: 'Whether a lane child should take its pre-gate cut now',
+		args: ISSUE_N_ARG,
+		vocabulary: ['cut', NOT_A_LANE],
+		single_source: PRE_GATE_CUT_MD,
+	},
+	{
+		name: 'backlog:budget',
+		decision: 'Whether a backlogrun may start more work, keep watching, or finish',
+		args: '',
+		vocabulary: ['run', 'watch', STOP],
+		single_source: BACKLOG_BUDGET_REFERENCE,
+	},
+	{
+		name: 'run:liveness',
+		decision: 'Whether a delegated unit is still working or has stopped without reporting',
+		args: `${ISSUE_N_ARG} --output <path>`,
+		vocabulary: ['alive', 'stopped', 'settled', 'undetermined'],
+		single_source: RUN_LIVENESS_REFERENCE,
+	},
+	{
+		name: 'stash:pop',
+		decision: 'Whether a named stash entry exists and can be applied',
+		args: '<message>',
+		vocabulary: ['popped', 'conflicted', 'no-match', 'ambiguous'],
+		single_source: '.claude/skills/workflow-commands/prerequisite.md',
+	},
+	{
+		name: 'backlog:next',
+		decision: 'Which issue the backlog offers next, or whether to wait or stop',
+		args: EXCLUDE_ARG,
+		vocabulary: [WAIT, STOP, RETRY, 'error', NONE],
+		single_source: BACKLOGRUN_MD,
+	},
+	{
+		name: 'auto-ok:next',
+		decision: 'The next opted-in issue outside any epic, or none',
+		args: EXCLUDE_ARG,
+		vocabulary: [NONE],
+		single_source: AUTO_OK_NEXT_REFERENCE,
+	},
+	{
+		name: 'epic:next',
+		decision: "The next runnable child of an epic, or the epic's status",
+		args: '<epic>',
+		vocabulary: [WAIT, STOP, 'complete'],
+		single_source: EPIC_NEXT_REFERENCE,
+	},
+	{
+		name: 'run:merge',
+		decision: 'The post-merge batch step: confirm child, advance, or report a stop condition',
+		args: ISSUE_N_ARG,
+		vocabulary: [OVER, HUMAN_REVIEW, STOP, RETRY, BUSY],
+		single_source: RUN_MERGE_REFERENCE,
+	},
+	{
+		name: 'run:step',
+		decision: 'The run’s next single action, computed from the event stream, carry and issue state',
+		args: ISSUE_N_ARG,
+		// The non-command answers: `run:step` prints a runnable command for a phase with one to run, and
+		// one of these verdicts otherwise. A command line is not a vocabulary token, exactly as an issue
+		// number is not one for `backlog:next`.
+		vocabulary: [
+			'implement',
+			HUMAN_REVIEW,
+			'update-deps',
+			'already-done',
+			'keep-work',
+			WAIT,
+			STOP,
+			UNKNOWN,
+		],
+		single_source: BACKLOGRUN_MD,
+	},
+]
+
+export { BATCH_ORACLES }

package/scripts/rules/decision-oracle-tokens.ts

@@ -0,0 +1,21 @@
+// Vocabulary tokens and arguments that appear in more than one oracle entry, shared by
+// `decision-oracle.ts` and `decision-oracle-batch.ts` so each string has one source
+// (joshuafolkken/kit#3264).
+
+const oracle_tokens = {
+	REQUIRED: 'required',
+	SKIP: 'skip',
+	STOP: 'stop',
+	WAIT: 'wait',
+	RETRY: 'retry',
+	OVER: 'over',
+	UNKNOWN: 'unknown',
+	NONE: 'none',
+	NOT_A_LANE: 'not-a-lane',
+	BUSY: 'busy',
+	HUMAN_REVIEW: 'human-review',
+	ISSUE_N_ARG: '<N>',
+	EXCLUDE_ARG: '[--exclude <n>...]',
+} as const
+
+export { oracle_tokens }

package/scripts/rules/decision-oracle.ts

@@ -6,7 +6,11 @@
 // not by prose. Single source: `prompts/collaboration-workflow/residency.md` → question 0.
 //
 // Anything not on this list is answered by prose or by a hook-delivered rule, never by a command.
+import { BATCH_ORACLES } from './decision-oracle-batch'
 import { RUN_ENTRY_ORACLE } from './decision-oracle-stage'
+import { oracle_tokens } from './decision-oracle-tokens'
+
+const { BUSY, ISSUE_N_ARG, NONE, OVER, REQUIRED, SKIP, UNKNOWN } = oracle_tokens
 
 // Paths that appear in more than one entry's `single_source` field.
 const CHAIN_RULE_MD = '.claude/skills/workflow-commands/chain-rule.md'
@@ -14,36 +18,7 @@ const BACKLOGRUN_PROGRESS_MD = '.claude/skills/workflow-commands/backlogrun-prog
 const SKILL_2E = '.claude/skills/workflow-commands/issue-scout.md'
 const SPLIT_ASSESSMENT_QUESTION =
 	'.claude/skills/workflow-commands/split-assessment.md → The question'
-const PRE_GATE_CUT_MD = '.claude/skills/workflow-commands/pre-gate-cut.md'
-const BACKLOGRUN_MD = '.claude/skills/workflow-commands/backlogrun.md'
-
-// The command reference in `docs/josh-commands.md` — one section per command, headed by the command
-// itself. joshuafolkken/kit#2190 cut `backlogrun.md` back to a manifest of pointers, so a decision it
-// used to carry inline (`run:merge`, `epic:next`, `backlog:budget`, `run:liveness`, `auto-ok:next`)
-// now has its verdict contract only in this reference. That makes it the single source and the section
-// a reader is routed to, in the same `file.md → \`josh <command>\`` form the `epic:reconcile` and
-// `lane:list` entries already use. joshuafolkken/kit#2254.
-const RUN_MERGE_REFERENCE = 'docs/josh-commands-automation.md → `josh run:merge`'
-const EPIC_NEXT_REFERENCE = 'docs/josh-commands-automation.md → `josh epic:next`'
-const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands-automation.md → `josh backlog:budget`'
-const RUN_LIVENESS_REFERENCE = 'docs/josh-commands-automation.md → `josh run:liveness`'
-const AUTO_OK_NEXT_REFERENCE = 'docs/josh-commands-automation.md → `josh auto-ok:next`'
 
-// Command used by two separate oracle entries (run:cut:resume and run:cut:gate).
-const RUN_CUT_CMD = 'run:cut'
-
-// Vocabulary tokens that appear in more than one oracle's vocabulary array.
-const REQUIRED = 'required'
-const SKIP = 'skip'
-const STOP = 'stop'
-const WAIT = 'wait'
-const RETRY = 'retry'
-const OVER = 'over'
-const UNKNOWN = 'unknown'
-const NONE = 'none'
-const NOT_A_LANE = 'not-a-lane'
-const BUSY = 'busy'
-const HUMAN_REVIEW = 'human-review'
 // Lane liveness verdicts shared by the lane:list oracle and asserted against `lane_occupancy` in its
 // test. `LIVE` is the silent norm; `STOPPED` and `UNKNOWN` lead the difference lines.
 const LIVE = 'live'
@@ -53,10 +28,6 @@ const STOPPED = 'stopped'
 const RECONCILED = 'reconciled'
 const NOTHING_TO_RECONCILE = 'nothing to reconcile'
 
-// Arguments shared by more than one oracle entry.
-const ISSUE_N_ARG = '<N>'
-const EXCLUDE_ARG = '[--exclude <n>...]'
-
 interface DecisionOracle {
 	// Short identifier used by the CLI and tests.
 	name: string
@@ -193,90 +164,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 		vocabulary: ['human_review: yes', 'human_review: no'],
 		single_source: '.claude/skills/workflow-commands/needs-human-review.md',
 	},
-	{
-		name: 'run:cut:resume',
-		command: RUN_CUT_CMD,
-		decision: 'Whether a lane child is resuming prior work or starting fresh',
-		args: `--resume ${ISSUE_N_ARG}`,
-		vocabulary: ['fresh', 'resume', NOT_A_LANE],
-		single_source: PRE_GATE_CUT_MD,
-	},
-	{
-		name: 'run:cut:gate',
-		command: RUN_CUT_CMD,
-		decision: 'Whether a lane child should take its pre-gate cut now',
-		args: ISSUE_N_ARG,
-		vocabulary: ['cut', NOT_A_LANE],
-		single_source: PRE_GATE_CUT_MD,
-	},
-	{
-		name: 'backlog:budget',
-		decision: 'Whether a backlogrun may start more work, keep watching, or finish',
-		args: '',
-		vocabulary: ['run', 'watch', STOP],
-		single_source: BACKLOG_BUDGET_REFERENCE,
-	},
-	{
-		name: 'run:liveness',
-		decision: 'Whether a delegated unit is still working or has stopped without reporting',
-		args: `${ISSUE_N_ARG} --output <path>`,
-		vocabulary: ['alive', 'stopped', 'settled', 'undetermined'],
-		single_source: RUN_LIVENESS_REFERENCE,
-	},
-	{
-		name: 'stash:pop',
-		decision: 'Whether a named stash entry exists and can be applied',
-		args: '<message>',
-		vocabulary: ['popped', 'conflicted', 'no-match', 'ambiguous'],
-		single_source: '.claude/skills/workflow-commands/prerequisite.md',
-	},
-	{
-		name: 'backlog:next',
-		decision: 'Which issue the backlog offers next, or whether to wait or stop',
-		args: EXCLUDE_ARG,
-		vocabulary: [WAIT, STOP, RETRY, 'error', NONE],
-		single_source: BACKLOGRUN_MD,
-	},
-	{
-		name: 'auto-ok:next',
-		decision: 'The next opted-in issue outside any epic, or none',
-		args: EXCLUDE_ARG,
-		vocabulary: [NONE],
-		single_source: AUTO_OK_NEXT_REFERENCE,
-	},
-	{
-		name: 'epic:next',
-		decision: "The next runnable child of an epic, or the epic's status",
-		args: '<epic>',
-		vocabulary: [WAIT, STOP, 'complete'],
-		single_source: EPIC_NEXT_REFERENCE,
-	},
-	{
-		name: 'run:merge',
-		decision: 'The post-merge batch step: confirm child, advance, or report a stop condition',
-		args: ISSUE_N_ARG,
-		vocabulary: [OVER, HUMAN_REVIEW, STOP, RETRY, BUSY],
-		single_source: RUN_MERGE_REFERENCE,
-	},
-	{
-		name: 'run:step',
-		decision: 'The run’s next single action, computed from the event stream, carry and issue state',
-		args: ISSUE_N_ARG,
-		// The non-command answers: `run:step` prints a runnable command for a phase with one to run, and
-		// one of these verdicts otherwise. A command line is not a vocabulary token, exactly as an issue
-		// number is not one for `backlog:next`.
-		vocabulary: [
-			'implement',
-			HUMAN_REVIEW,
-			'update-deps',
-			'already-done',
-			'keep-work',
-			WAIT,
-			STOP,
-			UNKNOWN,
-		],
-		single_source: BACKLOGRUN_MD,
-	},
+	...BATCH_ORACLES,
 	{
 		name: 'refactor:scan',
 		decision: 'Whether the refactoring scope still holds high- or medium-priority candidates',
@@ -303,7 +191,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 		decision: 'Whether cross-file or cross-repository code duplication exists',
 		args: '',
 		vocabulary: ['clean', 'clones:'],
-		single_source: 'prompts/collaboration-workflow/principles.md → クローン禁止',
+		single_source: 'prompts/collaboration-workflow/principles.md → no-clones',
 	},
 	{
 		name: 'epic:reconcile',
@@ -312,7 +200,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 			"Whether an epic's declaration matches its recorded relations, and the repair when it does not",
 		args: '--reconcile <E>',
 		vocabulary: [RECONCILED, NOTHING_TO_RECONCILE],
-		single_source: 'docs/josh-commands-automation.md → `josh epic --reconcile`',
+		single_source: 'docs/josh-commands-backlog.md → `josh epic --reconcile`',
 	},
 	{
 		name: 'lane:list',
@@ -320,7 +208,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 			'Whether each in-progress issue holds a live lane, and the two-directional difference',
 		args: '',
 		vocabulary: [LIVE, STOPPED, UNKNOWN],
-		single_source: 'docs/josh-commands-automation.md → The `in-progress` / lane difference',
+		single_source: 'docs/josh-commands-run.md → The `in-progress` / lane difference',
 	},
 	RUN_ENTRY_ORACLE,
 ]