@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/backlog/backlog-drive-restore.ts

@@ -5,12 +5,14 @@ const SETTLED_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.MERGE,
 	run_event_stream.EVENT_KIND.PARK,
 	run_event_stream.EVENT_KIND.SPLIT,
+	run_event_stream.EVENT_KIND.WITHDRAW,
 	run_event_stream.EVENT_KIND.OUTAGE,
 ])
 const DONE_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.MERGE,
 	run_event_stream.EVENT_KIND.PARK,
 	run_event_stream.EVENT_KIND.SPLIT,
+	run_event_stream.EVENT_KIND.WITHDRAW,
 ])
 
 function issue_of(event: RunEvent): string | undefined {
@@ -82,4 +84,10 @@ function restore(
 	)
 }
 
-export const backlog_drive_restore = { active_issues, restore, settled_issues, parked_issues }
+export const backlog_drive_restore = {
+	active_issues,
+	mentioned_issues,
+	restore,
+	settled_issues,
+	parked_issues,
+}

package/scripts/backlog/backlog-occupied.ts

@@ -0,0 +1,56 @@
+import type { LaneInfo } from '#scripts/lane/lane-registry'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_invocation } from '#scripts/run/run-invocation'
+import { backlog_drive_restore } from './backlog-drive-restore'
+
+// The open lanes that hold a place under the lane limit — the one count `lane:limit`, the drive and
+// `run:board` all subtract from it.
+//
+// **A lane nobody will come back to holds no place.** A `--only` run works its named list and never
+// touches another lane, so a lane an earlier run left with no child in it would fill the limit for the
+// whole run, and the run's own issues would wait on it for good (joshuafolkken/kit#3967). Under a `--only`
+// run such a lane is not counted; its tree and branch stay, for the next run that names its issue.
+//
+// **Everything else keeps its place, so the count errs toward fewer free lanes.** A run that drains
+// the pool may offer any open lane's issue again, a lane whose child still works is busy whoever owns
+// it, and with no run there is nobody to judge ownership for. The read stays local — no issue label is
+// read — because the count gates the network read behind it (`backlog-ready.ts`).
+
+interface OccupiedRead {
+	// The live run's invocation, `undefined` when no run is live here.
+	invocation: string | undefined
+	// The live run's own events, for the issues it launched or settled; `undefined` where its scope
+	// could not be told, which leaves every open lane counted.
+	events: ReadonlyArray<RunEvent> | undefined
+	// The issues whose lane has no child working in it; read only for a `--only` run.
+	idle: (lanes: ReadonlyArray<LaneInfo>) => ReadonlyArray<string>
+}
+
+// The issues a `--only` run owns — those it names and those it launched or settled — or `undefined`
+// where there is no such run, or its events could not be scoped to it.
+function owned_issues(read: OccupiedRead): ReadonlySet<string> | undefined {
+	const { invocation, events } = read
+	const is_only = invocation !== undefined && run_invocation.has_only(invocation)
+
+	if (!is_only || events === undefined) return undefined
+
+	const named = (run_invocation.issue_numbers(invocation) ?? []).map(String)
+
+	return new Set([...named, ...backlog_drive_restore.mentioned_issues(events)])
+}
+
+function occupied_lanes(lanes: ReadonlyArray<LaneInfo>, read: OccupiedRead): Array<LaneInfo> {
+	const live = lanes.filter((lane) => !lane.is_stranded)
+	const owned = owned_issues(read)
+
+	if (owned === undefined) return live
+
+	const idle = new Set(read.idle(live))
+
+	return live.filter((lane) => owned.has(lane.issue) || !idle.has(lane.issue))
+}
+
+const backlog_occupied = { occupied_lanes }
+
+export { backlog_occupied }
+export type { OccupiedRead }

package/scripts/backlog/backlog-ready.ts

@@ -3,9 +3,12 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_spent } from '#scripts/lane/lane-spent'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_invocation } from '#scripts/run/run-invocation'
+import { backlog_occupied, type OccupiedRead } from './backlog-occupied'
 import { backlog_stalled } from './backlog-stalled'
 
 // The ready line reports runnable work to the driving backlogrun parent on a watcher wake.
@@ -18,14 +21,46 @@ interface ReadyReading {
 	free_lanes: number
 }
 
+// How many open lanes hold a place under the limit, and how many hold a port seat.
+interface LaneUse {
+	occupied: number
+	seated: number
+}
+
 interface ReadyPorts {
 	free_lane_count: () => Promise<number>
 	ready_issues: () => Promise<ReadonlyArray<string>>
 }
 
-// The lanes in use: the open worktrees an interruption has not stranded. `josh lane:limit` prints it.
-async function live_lane_count(): Promise<number> {
-	return lane_registry.live_count(await lane_registry.list_lanes())
+// What decides which open lanes hold a place, read from this checkout's live run.
+async function occupied_read(): Promise<OccupiedRead> {
+	const carry = await run_headless.current_carry()
+
+	return {
+		invocation: carry?.invocation,
+		events: carry === undefined ? [] : await run_event_stream_emit.scoped_current_events(),
+		idle: lane_spent.idle_lanes,
+	}
+}
+
+// The lanes that hold a place under the limit (`backlog-occupied.ts`).
+async function occupied_lanes(lanes?: ReadonlyArray<LaneInfo>): Promise<Array<LaneInfo>> {
+	const open = lanes ?? (await lane_registry.list_lanes())
+
+	return backlog_occupied.occupied_lanes(open, await occupied_read())
+}
+
+// The open lanes as the free count reads them: those that hold a place under the limit, and every
+// open one, since an uncounted lane still holds its port seat.
+async function lane_use(lanes?: ReadonlyArray<LaneInfo>): Promise<LaneUse> {
+	const open = lanes ?? (await lane_registry.list_lanes())
+	const occupied = await occupied_lanes(open)
+
+	return { occupied: occupied.length, seated: open.filter((lane) => !lane.is_stranded).length }
+}
+
+function free_of(limit: number, use: LaneUse): number {
+	return lane_capacity.free_lanes(limit, use.occupied, use.seated)
 }
 
 // Free lanes beside `lanes`, `undefined` where the limit could not be read: the count `lane:limit`
@@ -35,11 +70,11 @@ async function free_lanes_beside(lanes: ReadonlyArray<LaneInfo>): Promise<number
 
 	if (limit.kind !== 'limit') return undefined
 
-	return lane_capacity.free_lanes(limit.limit, lane_registry.live_count(lanes))
+	return free_of(limit.limit, await lane_use(lanes))
 }
 
 async function free_under(limit: number): Promise<number> {
-	return lane_capacity.free_lanes(limit, await live_lane_count())
+	return free_of(limit, await lane_use())
 }
 
 // Free lanes right now: the limit less the live lanes. An unreadable limit reads as no free lane — the
@@ -48,9 +83,10 @@ async function free_under(limit: number): Promise<number> {
 //
 // **Occupancy is the local worktree count, not the dispatch budget's busy read.** `epic-lane-offer`
 // measures occupancy with `epic_busy.occupied_lanes`, a network read of in-progress issue labels; this
-// counts live worktrees instead, deliberately — it runs on the cheap-first path where the costly read
-// (`backlog:next`) is gated behind a free lane, so a network read here would defeat that design. The
-// two can diverge, but only toward over-counting live lanes → fewer free lanes, the safe direction.
+// counts the worktrees that hold a place instead (`backlog-occupied.ts`), deliberately — it runs on the
+// cheap-first path where the costly read (`backlog:next`) is gated behind a free lane, so a network
+// read here would defeat that design. The two can diverge, but only toward over-counting live lanes →
+// fewer free lanes, the safe direction.
 async function free_lane_count(): Promise<number> {
 	return (await free_lanes_beside(await lane_registry.list_lanes())) ?? NO_FREE
 }
@@ -172,7 +208,8 @@ const backlog_ready = {
 	print_offer_hint,
 	free_lane_count,
 	free_lanes_beside,
-	live_lane_count,
+	lane_use,
+	occupied_lanes,
 	drive_free_lane_count,
 	drains_pool,
 	print_ready_line,
@@ -182,4 +219,4 @@ const backlog_ready = {
 }
 
 export { backlog_ready }
-export type { ReadyPorts, ReadyReading }
+export type { LaneUse, ReadyPorts, ReadyReading }

package/scripts/delegation/duplicate-read-guard.ts

@@ -176,8 +176,8 @@ function is_candidate(call: GuardedCall): boolean {
 }
 
 // A refusable call is refused only where the mode is `refuse`. A lane child is `notice`, so it reaches
-// here and is withheld the refusal — the notice branch carries the guidance instead, because a refusal
-// ends a headless child's turn.
+// here and is withheld the refusal — the notice branch carries the guidance instead, for the reason its
+// `because` in `lane-guard-policy.ts` records.
 function should_block_here(tail: string, call: GuardedCall, refused_at_ms: number): boolean {
 	if (duplicate_mode() !== 'refuse') return false
 

package/scripts/delegation/investigation-guard.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env tsx
 import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
+import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
-import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
+import { lane_guard_policy } from '#scripts/lane/lane-guard-policy'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { investigation_reads } from './investigation-reads'
 
@@ -21,91 +22,42 @@ import { investigation_reads } from './investigation-reads'
 // file — debugging the guard itself, or a session whose reading really is all edit targets.
 const SWITCH_ENV_KEY = 'JOSH_INVESTIGATION_GUARD'
 
-// This guard's refusal record, and the notice's own record — distinct so a lane-child notice never
-// spends the refusal's stamp, the same split the batching guard keeps.
 const STAMP_PREFIX = 'josh-investigation-guard-'
-const NOTICE_STAMP_PREFIX = 'josh-investigation-guard-notice-'
 
-// **How the guard behaves for the session in hand, decided from the one-place enumeration**.
-// Outside a lane child the mode is `refuse` and the
-// guard refuses; in a dispatched lane child it is `notice`, because a lane child does read unedited
-// files and can dispatch sub-agents, so the reading is there to send out. The enumeration reads `JOSH_LANE_CHILD` against this checkout's own
-// issue only for a guard whose mode it would change, so a person working in a lane sees the guard
-// unchanged. It wraps `investigation_reads.should_block` here rather than inside it so the pure counting
-// rule stays free of process state and its own suite keeps testing it directly.
-function investigation_mode(): LaneGuardMode {
-	return lane_guard_policy.mode_here('investigation')
-}
-
-// A refusable call is refused only where the mode is `refuse` — the main line. A lane child is
-// `notice`, so it reaches the notice branch and is withheld the refusal that would end its headless
-// turn; an `off` some future enumeration sets stays silent here too.
+// **How the guard behaves for the session in hand, decided from the one-place enumeration**. It is
+// `refuse` in a dispatched lane child too (joshuafolkken/kit#3927): a hook denial returns to the model
+// as guidance, and the notice it replaced was measured not to move the reading. It wraps
+// `investigation_reads.should_block` here rather than inside it so the pure counting rule stays free of
+// process state and its own suite keeps testing it directly. A reviewer session stands down: reading
+// the diff's files is its whole task, and it carries the lane's marker, so it would otherwise be refused
+// like the child it reviews — the stand-down `implementation-cut.ts` takes for the same session.
 function should_block(
 	tail: string,
 	call: GuardedCall,
 	refused_at_ms: number,
 	run?: GuardRun,
 ): boolean {
-	if (investigation_mode() !== 'refuse') return false
+	if (
+		agent_session_role.is_reviewer() ||
+		lane_guard_policy.mode_here('investigation') !== 'refuse'
+	) {
+		return false
+	}
 
 	return investigation_reads.should_block(tail, call, refused_at_ms, run)
 }
 
-// The lane-child notice: the same threshold, delivered without a `permissionDecision`. It
-// reads the notify stamp's own record, so a notice never spends the refusal's stamp and re-arms on the
-// next accumulation exactly as the refusal does.
-function should_notify(
-	tail: string,
-	call: GuardedCall,
-	notified_at_ms: number,
-	run?: GuardRun,
-): boolean {
-	if (investigation_mode() !== 'notice') return false
-
-	return investigation_reads.should_block(tail, call, notified_at_ms, run)
-}
-
-// **The lane-child counterpart of REASON, delivered as a notice rather than a refusal**.
-// A dispatched lane child ends its turn on a denial, so
-// the same guidance is carried without a `permissionDecision`: the read proceeds and the child is nudged
-// to delegate rather than killed. It carries no ⛔, so a person watching reads it as advice.
-const NOTICE = `💡 investigation: files read and not edited, or search turns, since the last delegated unit reached the threshold; the read proceeds. Run \`pnpm josh delegate investigation\`, then dispatch the \`${investigation_reads.INVESTIGATOR_AGENT}\` agent (\`kit:${investigation_reads.INVESTIGATOR_AGENT}\` in a consumer); it returns \`file:line\` citations, never the file text. Keep main-line reads to files you will edit.`
-
-// The notice as it reaches the model: the base guidance with the concrete unedited reads named, so a
-// lane child is shown *which* reads to send to a unit rather than only told to delegate. An empty
-// set names nothing and the notice falls back to its guidance alone. The call is part of the notify
-// contract but this guard's wording depends on the tail alone.
-function notice_text(_call: GuardedCall, tail: string): string {
-	const pending = investigation_reads
-		.tally_of(tail)
-		.pending.map((absolute) => investigation_reads.repository_relative(absolute))
-
-	return pending.length === 0
-		? NOTICE
-		: `${NOTICE} Read and not edited so far: ${pending.join(' ')}.`
-}
-
 const GUARD = hook_decision.create_transcript_guard({
 	prefix: STAMP_PREFIX,
 	switch_key: SWITCH_ENV_KEY,
 	is_candidate: investigation_reads.is_refusable_call,
 	should_block,
 	reason: investigation_reads.REASON,
-	// The lane-child notice fires where the refusal is withheld, on a record of its own so it
-	// never spends the refusal's stamp.
-	notify: {
-		prefix: NOTICE_STAMP_PREFIX,
-		should_notify,
-		text: notice_text,
-	},
 })
 
 const investigation_refusal = GUARD.refusal
 const investigation_outcome = GUARD.outcome
 const { is_enabled, refusal_path } = GUARD
-// The notice's stamp path, exposed the way `refusal_path` is so a test can clean it apart from the
-// refusal's record.
-const investigation_notice_path = hook_decision.create_refusal_stamp(NOTICE_STAMP_PREFIX).path
 const { deny_envelope, load_environment_file, DISABLED_VALUES } = hook_decision
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -115,13 +67,11 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 export {
 	deny_envelope,
-	investigation_notice_path,
 	investigation_outcome,
 	investigation_refusal,
 	is_enabled,
 	load_environment_file,
 	refusal_path,
 	DISABLED_VALUES,
-	NOTICE,
 	SWITCH_ENV_KEY,
 }

package/scripts/delegation/investigation-reads.ts

@@ -362,7 +362,6 @@ const investigation_reads = {
 	is_session_artifact,
 	is_subject_file,
 	projected_count,
-	repository_relative,
 	resolved,
 	should_block,
 	tally_of,

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

@@ -73,18 +73,19 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/prerequisite.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	{ path: 'docs/josh-commands-automation.md', bytes: 45_056 },
-	{ path: 'docs/josh-commands-run.md', bytes: 61_440 },
-	{ path: 'docs/josh-commands-backlog.md', bytes: 49_152 },
-	{ path: 'docs/josh-commands.md', bytes: 45_056 },
+	{ path: 'docs/josh-commands-automation.md', bytes: 49_152 },
+	{ path: 'docs/josh-commands-run.md', bytes: 65_536 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 53_248 },
+	{ path: 'docs/josh-commands.md', bytes: 49_152 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/glossary.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/lane-instructions.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 4096 },

package/scripts/document/document-section-cli.ts

@@ -2,6 +2,7 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { find_package_directory } from '#scripts/josh/package-directory'
 import { capped_output } from './capped-print'
 import { document_section } from './document-section'
 import { entry_read_set } from './entry-read-set'
@@ -35,14 +36,25 @@ const USAGE = 'Usage: josh doc:section <file.md> "<heading>"'
 // directory, a bare name that happened to exist beside the caller would beat the document under
 // `root` and print a section of the wrong file — silently, which is the failure this command exists
 // to refuse.
-function resolve_document(name: string, root: string = process.cwd()): string {
-	const named = path.resolve(root, name)
+//
+// **The kit package is the fallback.** A consumer keeps no `prompts/` of its own — the package ships
+// it under `node_modules/@joshuafolkken/kit/` — so `prompts/review.md` resolves there when `root` has
+// no copy, exactly as `review:brief` resolves the rubric.
+const PACKAGE_DIRECTORY = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
 
-	if (existsSync(named)) return named
+function candidates_under(directory: string, name: string): Array<string> {
+	return [path.resolve(directory, name), entry_read_set.document_path(directory, name)]
+}
 
-	const in_skill = entry_read_set.document_path(root, name)
+function resolve_document(
+	name: string,
+	root: string = process.cwd(),
+	package_directory: string = PACKAGE_DIRECTORY,
+): string {
+	const named = path.resolve(root, name)
+	const candidates = [...candidates_under(root, name), ...candidates_under(package_directory, name)]
 
-	return existsSync(in_skill) ? in_skill : named
+	return candidates.find((candidate) => existsSync(candidate)) ?? named
 }
 
 function report_missing(markdown: string, heading: string): number {

package/scripts/document/entry-read-budget.ts

@@ -47,8 +47,8 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	{ entry: 'kickoff', bytes: 36_864 },
 	{ entry: 'fullrun', bytes: 53_248 },
 	{ entry: 'halfrun', bytes: 49_152 },
-	{ entry: 'prrun', bytes: 57_344 },
-	{ entry: 'backlogrun', bytes: 86_016 },
+	{ entry: 'prrun', bytes: 53_248 },
+	{ entry: 'backlogrun', bytes: 81_920 },
 	{ entry: LANE_CHILD, bytes: 45_056 },
 ]
 

package/scripts/document/read-set-cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { lane_instructions } from '#scripts/agent/lane-instructions'
 import { backlogrun_parent_read_set } from './backlogrun-parent-read-set'
 import { entry_read_set, type ReadSetCost, type SectionCost } from './entry-read-set'
 import { lane_child_read_set } from './lane-child-read-set'
@@ -192,7 +193,9 @@ function total_lines(report: ReadSetCost, width: number): Array<string> {
 }
 
 function note_lines(report: ReadSetCost): Array<string> {
-	if (report.entry === lane_child_read_set.LANE_CHILD) return [...LANE_CHILD_NOTE, '']
+	if (report.entry === lane_child_read_set.LANE_CHILD) {
+		return [...LANE_CHILD_NOTE, lane_instructions.resident_line(), '']
+	}
 
 	if (report.entry === BACKLOGRUN) return [...BACKLOGRUN_PARENT_NOTE, '']
 

package/scripts/epic/epic-audit-orphans.ts

@@ -14,7 +14,6 @@ import { epic_parse } from './epic-parse'
 // the children the epic already names, while this one searches for issues the epic does *not* name.
 
 const SEARCH_LIMIT = 50
-const PARENT_MARKERS: ReadonlyArray<string> = ['親:', 'Parent:', '親：']
 // Named apart from `epic_audit_checks.ORPHAN_CHILD`: that check reports an orphan it found, this one
 // reports that the search for orphans was incomplete, and a reader has to be able to tell them apart.
 const ORPHAN_SEARCH = 'orphan search'
@@ -25,18 +24,15 @@ const CAPPED_BY_MATCHES = `The open-issue scan filled its ${String(SEARCH_LIMIT)
 
 const searched_issue_schema = z.object({ number: z.number(), body: z.string().nullable() })
 
-function has_parent_marker(line: string): boolean {
-	return PARENT_MARKERS.some((marker) => line.includes(marker))
-}
-
 // Whether an issue's body names this epic as its parent, in the shape the issue template uses.
 //
 // Both halves must be on the *same line*. An issue parented to a different epic routinely backlinks
 // this one elsewhere in its body, and matching the marker and the number independently reported
 // every such issue as an orphan.
 //
-// The number is read through the same reference parse the checks use, so a parent line (a PARENT_MARKERS
-// prefix) such as `owner/other#858` names that repository's epic and not this one's.
+// The number is read through the same reference parse the checks use, so a parent line (one
+// `epic_audit_logic.has_parent_marker` accepts) such as `owner/other#858` names that repository's
+// epic and not this one's.
 // The known set is this repository alone — a parent line names this epic or it names nothing here —
 // and it is passed rather than omitted so a repository whose own name contains a dot still recognizes
 // `joshuafolkken/site.com#858`.
@@ -49,7 +45,8 @@ function names_this_epic(line: string, epic_number: number, repo: string): boole
 function claims_parent(body: string | null, epic_number: number, repo: string): boolean {
 	return (body ?? '')
 		.split('\n')
-		.some((line) => has_parent_marker(line) && names_this_epic(line, epic_number, repo))
+		.filter((line) => epic_audit_logic.has_parent_marker(line))
+		.some((line) => names_this_epic(line, epic_number, repo))
 }
 
 // Why the scan stopped before the end of the open backlog, or that it did not. Both cutoffs hide the

package/scripts/epic/epic-audit.ts

@@ -180,6 +180,55 @@ function acceptance_section(body: string | undefined): string {
 	return markdown_section.section_lines_matching(body, is_acceptance_heading).join('\n')
 }
 
+// Where a body reference that counts as a relation was written. Only these two places state what the
+// issue delivers or where it belongs; a number in the background, symptom or origin section is the
+// example that prompted the filing, and reading it as a relation bundled issues whose work never
+// overlaps.
+type SignalSection = 'acceptance criteria' | 'parent line'
+
+interface SignalReference {
+	number: number
+	section: SignalSection
+}
+
+// What marks a line as naming the issue's parent, in both spellings for the same reason as
+// `ACCEPTANCE_HEADINGS`. `epic:audit`'s orphan search matches it anywhere in the line, then asks
+// whether the same line names the epic.
+const PARENT_MARKERS: ReadonlyArray<string> = ['親:', '親：', 'Parent:', 'parent:']
+
+function has_parent_marker(line: string): boolean {
+	return PARENT_MARKERS.some((marker) => line.includes(marker))
+}
+
+// The reference written directly after a parent marker, bold markup allowed (`- **Parent:** #N`).
+// Only that reference is the parent: a background sentence that mentions `parent:` and names an
+// issue elsewhere on the line is not a parent line.
+const PARENT_REFERENCE = /(?:親|Parent|parent)\**[:：]\**\s*(?:[\w.-]+\/[\w.-]+)?#\d+/gu
+
+function parent_references(body: string): string {
+	return markdown_section
+		.unfenced_lines(body)
+		.flatMap((line) => [...line.matchAll(PARENT_REFERENCE)].map((match) => match[0]))
+		.join('\n')
+}
+
+function references_in(text: string, repo: string, section: SignalSection): Array<SignalReference> {
+	return parse_references(text, repo).map((number) => ({ number, section }))
+}
+
+// The same-repository references a body makes in the places that count as a relation, each with the
+// section it was read from. A number both places name is reported once, at the first.
+function signal_references(body: string, repo = ''): Array<SignalReference> {
+	const read = [
+		...references_in(acceptance_section(body), repo, 'acceptance criteria'),
+		...references_in(parent_references(body), repo, 'parent line'),
+	]
+
+	return read.filter((reference, index) => {
+		return read.findIndex((other) => other.number === reference.number) === index
+	})
+}
+
 // Everything `node` depends on, directly or through a chain. Walked iteratively so a graph that
 // still contains a cycle terminates — `epic:next` rejects one first, but an auditor must not hang on
 // the input it exists to examine.
@@ -223,8 +272,10 @@ const epic_audit_logic = {
 	parse_issue_references,
 	parse_references,
 	acceptance_section,
+	signal_references,
+	has_parent_marker,
 	depends_on,
 }
 
-export type { AuditFinding, FindingLevel, ReferenceState }
+export type { AuditFinding, FindingLevel, ReferenceState, SignalReference, SignalSection }
 export { epic_audit_logic }