@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/rules/reply-prose.ts

@@ -0,0 +1,34 @@
+// The prose of a session-facing reply — the text a person reads as sentences, with code, links and
+// bare paths taken out. Two Stop rules read it: the reply's language (`reply-language.ts`) and its
+// length (`concise-reply.ts`).
+
+const CODE_PATTERNS: ReadonlyArray<RegExp> = [
+	/```[\s\S]*?(?:```|$)/gu,
+	/`[^`\n]*`/gu,
+	/\]\([^)\s]*\)/gu,
+	/https?:\/\/\S+/gu,
+]
+// A run of printable ASCII; one holding a slash is a bare path the reply printed outside backticks.
+const ASCII_RUN_PATTERN = /[!-~]+/gu
+// A table row or a list item — the structure a reply's points are carried in, not its narrative.
+const STRUCTURE_LINE_PATTERN = /^\s*(?:\||[-*+] |[・•] ?|\d+\. )/u
+
+function prose_of(message: string): string {
+	let text = message
+
+	for (const pattern of CODE_PATTERNS) text = text.replaceAll(pattern, ' ')
+
+	return text.replaceAll(ASCII_RUN_PATTERN, (run) => (run.includes('/') ? ' ' : run))
+}
+
+// The prose outside tables and lists: what a reply narrates around its one table or list.
+function narrative_of(message: string): string {
+	return prose_of(message)
+		.split('\n')
+		.filter((line) => !STRUCTURE_LINE_PATTERN.test(line))
+		.join('\n')
+}
+
+const reply_prose = { narrative_of, prose_of }
+
+export { reply_prose }

package/scripts/rules/repo-admin.ts

@@ -0,0 +1,132 @@
+import { bash_triggers } from './bash-triggers'
+import { direct_pr_create } from './direct-pr-create'
+import { gh_api } from './gh-api'
+import { git_argv } from './git-argv'
+import { pr_merge } from './pr-merge'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `repo-admin` row of `delivered-rules.ts`: a write to
+// the repository's own administration — the rulesets and branch protection, the collaborators and
+// their invitations, the secrets and variables, the webhooks and deploy keys, and the repository's
+// settings. The server-side ruleset is one of the two real boundaries of an unattended run, and the
+// trust gate reads write permission, so one injected call that adds a collaborator or disables the
+// ruleset hands the backlog to an attacker (joshuafolkken/kit#4650).
+//
+// **A `DELETE` is `destructive-command`'s**, which refuses every `DELETE repos/…` already; this row
+// takes the other write methods, so one row claims each call. `gh ruleset` has no write subcommand.
+//
+// **It fires on every occurrence**, for the reason `git-force.ts` does.
+
+const GH_COMMAND = 'gh'
+const DELETE_METHOD = 'DELETE'
+const PATCH_METHOD = 'PATCH'
+
+// `repos/<o>/<r>` as a path or a full URL (`https://api.github.com/repos/…`), anchored on the whole
+// argument so a path smuggled into a field value (`-f x=repos/…/hooks`) is not read as the endpoint.
+const REPOSITORY_PREFIX = String.raw`^['"]?(?:https?:\/\/[^/\s'"]+)?\/?repos\/[^/\s'"]+\/[^/\s'"]+`
+// The administration endpoints under it — the environments whole, since their protection rules move
+// the deployment boundary as their secrets do.
+const ADMIN_PATH = new RegExp(
+	REPOSITORY_PREFIX +
+		String.raw`\/(?:rulesets|branches\/[^\s'"]+\/protection|collaborators|invitations|hooks|keys|` +
+		String.raw`transfer|actions\/permissions|environments|` +
+		String.raw`(?:actions|dependabot|codespaces)\/(?:secrets|variables))(?:[/?'"]|$)`,
+	'u',
+)
+// The repository itself — a `PATCH` here edits its settings (visibility, default branch, merge rules).
+const REPOSITORY_BODY = new RegExp(String.raw`${REPOSITORY_PREFIX}\/?['"]?$`, 'u')
+// The GraphQL mutations that do what the endpoints above do. Looked for in the whole line, as
+// `pr-merge.ts` does, since the segment cut ignores quotes; a body read from a file is `pr-merge`'s.
+const ADMIN_MUTATIONS =
+	/\b(?:updateRepository|archiveRepository|(?:create|update|delete)(?:BranchProtectionRule|RepositoryRuleset|Environment))\b/u
+
+function is_admin_target(argument: string, method: string | undefined): boolean {
+	return ADMIN_PATH.test(argument) || (method === PATCH_METHOD && REPOSITORY_BODY.test(argument))
+}
+
+function is_admin_graphql_call(command: string, args: ReadonlyArray<string>): boolean {
+	return pr_merge.is_graphql_call(GH_COMMAND, args) && ADMIN_MUTATIONS.test(command)
+}
+
+// Judged on the call with its wrapper cut off, as `destructive-command.ts` does.
+function is_admin_api_call(command: string, args: ReadonlyArray<string>): boolean {
+	const call = [GH_COMMAND, ...args].join(' ')
+
+	if (!gh_api.is_gh_api(call) || !gh_api.is_write(call)) return false
+	if (is_admin_graphql_call(command, args)) return true
+
+	const method = gh_api.method_of(call)
+
+	if (method === DELETE_METHOD) return false
+
+	return args.some((argument) => is_admin_target(argument, method))
+}
+
+// The read subcommands of the groups whose every other subcommand writes.
+const READ_ACTIONS: ReadonlySet<string> = new Set(['list', 'ls', 'get', 'view'])
+const ACTION_POSITION = 1
+const SUB_ACTION_POSITION = 2
+// Where the word that decides read vs write sits, keyed by the group (`gh secret <verb>`) or by the
+// group and action (`gh repo deploy-key <verb>`); `gh repo edit` is its own verb and only writes.
+const VERB_POSITIONS: ReadonlyMap<string, number> = new Map([
+	['secret', ACTION_POSITION],
+	['variable', ACTION_POSITION],
+	['repo edit', ACTION_POSITION],
+	['repo deploy-key', SUB_ACTION_POSITION],
+])
+
+// The verb of an administration subcommand, or `undefined` for every other call. Read off the
+// positional words, so a repository selector before the group (`gh -R o/r secret set`) is skipped.
+function admin_verb(args: ReadonlyArray<string>): string | undefined {
+	const words = direct_pr_create.positional_words(args, direct_pr_create.API_VALUE_TAKING_FLAGS)
+	const position =
+		VERB_POSITIONS.get(words[0] ?? '') ??
+		VERB_POSITIONS.get(words.slice(0, SUB_ACTION_POSITION).join(' '))
+
+	if (position === undefined) return undefined
+
+	return words[position] ?? ''
+}
+
+function is_admin_cli_call(args: ReadonlyArray<string>): boolean {
+	const verb = admin_verb(args)
+
+	return verb !== undefined && !READ_ACTIONS.has(verb)
+}
+
+function is_admin_segment(command: string, segment: string): boolean {
+	const args = git_argv.arguments_of(segment, GH_COMMAND)
+
+	if (args === undefined) return false
+
+	return is_admin_cli_call(args) || is_admin_api_call(command, args)
+}
+
+function is_repo_admin_write(command: string): boolean {
+	return shell_segments.commands_of(command).some((segment) => is_admin_segment(command, segment))
+}
+
+const REPO_ADMIN_REASON =
+	'⛔ repository administration: a write to the rulesets, branch protection, collaborators, ' +
+	'invitations, secrets, variables, webhooks, deploy keys or repository settings moves the ' +
+	'boundary an unattended run relies on, which is Tier C. Ask the user to run it. It fires on every occurrence ' +
+	'(`prompts/collaboration-workflow/operating-rules.md`).'
+
+const ROW = {
+	id: 'repo-admin',
+	is_trigger: bash_triggers.on_bash_command(is_repo_admin_write),
+	reason: REPO_ADMIN_REASON,
+	decide: (): boolean => true,
+	about: {
+		title: 'Repository administration',
+		topic: '`operating-rules.md`',
+		fires:
+			'a `gh api` POST / PUT / PATCH (path or URL) to the rulesets, branch protection, collaborators, invitations, secrets, variables, hooks, keys, environments, actions permissions or transfer, a `PATCH` of the repository, the matching GraphQL mutations, `gh secret` / `gh variable` writes, `gh repo edit` / `deploy-key` writes. Every occurrence',
+		quiet:
+			'`gh secret list`, `gh variable get`, a `gh api` read — a `DELETE` is `destructive-command`',
+	},
+}
+
+const repo_admin = { REPO_ADMIN_REASON, ROW, is_repo_admin_write }
+
+export { repo_admin }

package/scripts/rules/reviewer-foreground.ts

@@ -0,0 +1,88 @@
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { agent_model } from './agent-model'
+
+// A lane child's `reviewer` dispatched without `run_in_background: false` is run in the foreground
+// instead (joshuafolkken/kit#5154).
+//
+// **A headless child's turn end kills a background reviewer**, so `chain-rule.md` → "A lane child" says
+// not to background it. The subagent tool launches in the background by default, and 23 of 178 lanes
+// did: #5129 polled the output file in a `sleep` loop, then waited again on `run:review --join`.
+//
+// **The fix is the same call with one field, so the hook makes it** (`guard-remedy.ts`): no round trip,
+// and a build whose tool declares no `run_in_background` drops the added field as it drops the typed
+// one. Lane children only — an interactive turn is re-invoked by the background result.
+
+// `kit:reviewer` is the consumer's spelling of the same definitions.
+const REVIEWER_AGENTS: ReadonlySet<string> = new Set(['reviewer', 'reviewer-verification'])
+
+const BACKGROUND_FIELD = 'run_in_background'
+
+const CHAIN_RULE_STEP = '`.claude/skills/workflow-commands/chain-rule.md` → "A lane child"'
+
+const KILLED = 'reviewer foreground: a lane child’s turn end kills a background `reviewer`'
+const FOREGROUND = `\`${BACKGROUND_FIELD}: false\``
+
+const REVIEWER_FOREGROUND_NOTE = `↻ ${KILLED}, so the call ran with ${FOREGROUND} (${CHAIN_RULE_STEP}).`
+
+// Delivered only where the rewrite cannot reach the call.
+const REVIEWER_FOREGROUND_REASON = `⛔ ${KILLED}. Reissue the call with ${FOREGROUND} (${CHAIN_RULE_STEP}). It fires on every occurrence.`
+
+function is_reviewer(call: GuardedCall): boolean {
+	if (!agent_model.SUBAGENT_TOOLS.has(call.name) || !json_value.is_record(call.input)) return false
+
+	const type = call.input['subagent_type']
+
+	return typeof type === 'string' && REVIEWER_AGENTS.has(type.split(':').at(-1) ?? '')
+}
+
+function is_foreground(call: GuardedCall): boolean {
+	return json_value.is_record(call.input) && call.input[BACKGROUND_FIELD] === false
+}
+
+function is_background_reviewer(
+	call: GuardedCall,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+): boolean {
+	return is_lane_child && is_reviewer(call) && !is_foreground(call)
+}
+
+function foreground_input(
+	call: GuardedCall,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+): Record<string, unknown> | undefined {
+	if (!is_background_reviewer(call, is_lane_child) || !json_value.is_record(call.input)) {
+		return undefined
+	}
+
+	return { ...call.input, [BACKGROUND_FIELD]: false }
+}
+
+const ROW = {
+	id: 'reviewer-foreground',
+	is_trigger: (call: GuardedCall): boolean => is_background_reviewer(call),
+	reason: REVIEWER_FOREGROUND_REASON,
+	decide: (): boolean => true,
+	keeps: (call: GuardedCall): boolean => is_reviewer(call) && is_foreground(call),
+	reaches: is_reviewer,
+	rewrite: (call: GuardedCall): Record<string, unknown> | undefined => foreground_input(call),
+	rewrite_note: REVIEWER_FOREGROUND_NOTE,
+	about: {
+		title: 'Lane child reviewer dispatched in the foreground',
+		topic: CHAIN_RULE_STEP,
+		fires:
+			'a dispatched lane child’s `Agent` / `Task` call of the `reviewer` or `reviewer-verification` type without `run_in_background: false` — rewritten with it, every occurrence',
+		quiet: 'not a lane child, another agent type, or `run_in_background: false` set',
+	},
+}
+
+const reviewer_foreground = {
+	REVIEWER_FOREGROUND_NOTE,
+	REVIEWER_FOREGROUND_REASON,
+	ROW,
+	foreground_input,
+	is_background_reviewer,
+}
+
+export { reviewer_foreground }

package/scripts/rules/round-one-check-related.ts

@@ -0,0 +1,120 @@
+import type { GuardRun } from '#scripts/josh/hook-decision'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_markers } from '#scripts/time-runtime/time-markers'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_transcript_line, type Block } from '#scripts/time-runtime/time-transcript-line'
+import { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
+import { tail_commands } from './tail-commands'
+
+// A lane child is stopped from running `check:related` on round 1's fixes before it joins the review.
+//
+// **Ship reruns the scoped pair on the fixed tree.** `chain-rule.md` → "A lane child" says the round's
+// fixes take no `check:related` unless a brief follows: `josh ship`'s pre-detach checks the tree the
+// fixes left. The #5168 lane fixed two findings between its brief and `run:review --join` and ran
+// `check:related` after each, 12 of its 70 minutes, because the sentence was prose with no delivery.
+//
+// **The material is the run's own calls, read in order off the transcript tail.** The brief is a
+// `run:review` in its writing mode, the fix an `Edit` / `Write` after it, and the round closes at
+// `run:review --join` or `ship --detach`. Neither the brief file nor the join leaves a record on disk
+// that tells "briefed, not yet joined" apart, so the tail is the one source that can answer.
+
+// Named canonically — `shell_segments.is_josh_command` expands an alias (`josh cr`) before the match.
+const CHECK_COMMANDS: ReadonlySet<string> = new Set(['check:related'])
+const REVIEW_COMMANDS: ReadonlySet<string> = new Set(['run:review'])
+const SHIP_COMMANDS: ReadonlySet<string> = new Set(['ship'])
+const JOIN_FLAG = /(?:^|\s)--join(?:[=\s]|$)/u
+// The `run:review` modes that read a running check rather than write a brief.
+const READING_MODE_FLAG = /(?:^|\s)--(?:pinned|push)(?:[=\s]|$)/u
+const DETACH_FLAG = /(?:^|\s)--detach(?:[=\s]|$)/u
+
+type RoundEvent = 'brief' | 'close' | 'edit' | 'none'
+
+function review_event(segment: string): RoundEvent {
+	if (JOIN_FLAG.test(segment)) return 'close'
+
+	return READING_MODE_FLAG.test(segment) ? 'none' : 'brief'
+}
+
+function segment_event(segment: string): RoundEvent {
+	if (shell_segments.is_josh_command(segment, REVIEW_COMMANDS)) return review_event(segment)
+
+	const is_detach =
+		shell_segments.is_josh_command(segment, SHIP_COMMANDS) && DETACH_FLAG.test(segment)
+
+	return is_detach ? 'close' : 'none'
+}
+
+function block_events(block: Block): ReadonlyArray<RoundEvent> {
+	if (tail_commands.is_bash_use(block)) {
+		const segments = shell_segments.segments_of(time_shell.bash_command(block.input))
+
+		return segments.map((segment) => segment_event(segment))
+	}
+
+	const is_edit = time_markers.tool_marker(block.name, block.input) === time_markers.EDIT_MARKER
+
+	return is_edit ? ['edit'] : []
+}
+
+// Whether the tail's last brief was followed by a fix and by neither a join nor a detach.
+function fixes_an_open_round(tail: string): boolean {
+	const blocks = time_transcript_line.parse_text(tail).flatMap((line) => line.blocks)
+	const events = blocks.flatMap((block) => block_events(block))
+	const brief_at = events.lastIndexOf('brief')
+
+	if (brief_at === -1) return false
+
+	const since_brief = new Set(events.slice(brief_at))
+
+	return since_brief.has('edit') && !since_brief.has('close')
+}
+
+function runs_check_related(command: string): boolean {
+	return shell_segments
+		.segments_of(command)
+		.some((segment) => shell_segments.is_josh_command(segment, CHECK_COMMANDS))
+}
+
+// **The command test comes first and the world is consulted second**: a person working in a lane
+// carries no mark and sees no refusal.
+function is_candidate(command: string): boolean {
+	if (!runs_check_related(command)) return false
+
+	return lane_child_marker.is_child_of(process.cwd())
+}
+
+// Refused on every occurrence while the round stays open: the way on is the join, never a reissue.
+function decide(_call: unknown, run: GuardRun): boolean {
+	return fixes_an_open_round(time_density_hook.read_tail(run.transcript))
+}
+
+const ROUND_ONE_CHECK_RELATED_REASON =
+	"⛔ round-one check:related: round 1's fixes need no `check:related` — ship's pre-detach reruns the " +
+	'scoped pair on the fixed tree; refused on every occurrence. Go on to `pnpm josh run:review --join`; ' +
+	'`--join --fixing` while round 1 has fixes to make (`.claude/skills/workflow-commands/chain-rule.md` → "A lane child").'
+
+// It declares no `keeps`: skipping the check is the absence of a call, so the row is reported
+// unmeasured rather than scored on an act that does not exist (`lane-split-park.ts`).
+const ROW = {
+	id: 'round-one-check-related',
+	is_trigger: bash_triggers.on_bash_command(is_candidate),
+	reason: ROUND_ONE_CHECK_RELATED_REASON,
+	decide,
+	about: {
+		title: "No check:related on round 1's fixes",
+		topic: '`.claude/skills/workflow-commands/chain-rule.md` → "A lane child"',
+		fires:
+			"`pnpm josh check:related` (`josh cr`) in a lane child after an `Edit` / `Write` that follows `run:review`'s brief, before `run:review --join` or `ship --detach`. Every occurrence",
+		quiet: 'no fix since the brief, already joined or detached, or not a lane child',
+	},
+}
+
+const round_one_check_related = {
+	ROUND_ONE_CHECK_RELATED_REASON,
+	ROW,
+	fixes_an_open_round,
+}
+
+export { round_one_check_related }

package/scripts/rules/rule-body-guard.ts

@@ -2,6 +2,7 @@ import { json_value } from '#scripts/lib/json-value'
 import { file_reader } from '#scripts/lib/read-file'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
+import { edit_tool } from './edit-tool'
 import { shell_segments } from './shell-segments'
 import { tail_commands } from './tail-commands'
 
@@ -29,10 +30,9 @@ import { tail_commands } from './tail-commands'
 // refuses until it is met. It passes on answering the questions, not on reading the
 // reminder. Keeping the rule is therefore running those two commands, which `keeps` names.
 
-// The two edit tools the `PreToolUse` matcher routes here. A `Write` carries the whole new file; an
-// `Edit` carries the region as `old_string` / `new_string`.
-const EDIT_TOOL = 'Edit'
-const WRITE_TOOL = 'Write'
+// The two edit tools the `PreToolUse` matcher routes here (`edit-tool.ts`). A `Write` carries the whole
+// new file; an `Edit` carries the region as `old_string` / `new_string`.
+const { WRITE, is_edit_tool, string_field } = edit_tool
 
 // The three rule-document families question 0 must be pushed at: the resident source, the
 // collaboration-workflow prompts, and the skill bodies. Anchored at a path separator or the string
@@ -69,12 +69,6 @@ function adds_rule_prose(old_text: string, new_text: string): boolean {
 	return prose_of(new_text).length - prose_of(old_text).length >= MIN_APPENDED_PROSE
 }
 
-function string_field(input: Record<string, unknown>, key: string): string {
-	const value = input[key]
-
-	return typeof value === 'string' ? value : ''
-}
-
 // The file's current text, read synchronously before the write lands so a `Write` has an `old` to
 // measure against. Injected so the suite controls it without touching the real filesystem, the way
 // `file-body.ts` injects its existence check. A new file reads as empty, so its whole body is added.
@@ -87,7 +81,7 @@ function texts_of(
 	input: Record<string, unknown>,
 	read: (file_path: string) => string,
 ): { old_text: string; new_text: string } {
-	if (name === WRITE_TOOL) {
+	if (name === WRITE) {
 		return {
 			old_text: read(string_field(input, 'file_path')),
 			new_text: string_field(input, 'content'),
@@ -100,10 +94,6 @@ function texts_of(
 	}
 }
 
-function is_edit_tool(name: string): boolean {
-	return name === EDIT_TOOL || name === WRITE_TOOL
-}
-
 // The call's input when it is an edit of a rule document, and `undefined` otherwise. The tool-name and
 // path tests run before the text read, so an ordinary edit pays nothing and a `Write`'s file read
 // happens only for a rule document.

package/scripts/rules/rule-value-cache.ts

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process'
 import { statSync } from 'node:fs'
 import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
 import { atomic_write } from '#scripts/lib/atomic-write'
 import { file_reader } from '#scripts/lib/read-file'
 import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
@@ -14,7 +15,12 @@ import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 // **It reports and never fails**, as `rule:value` itself does: a missing cache, an unwritable directory
 // or a refresh that could not start prints at most nothing, and never changes the offer's answer.
 
-const CACHE_DIRECTORY = ['node_modules', '.cache', 'josh']
+// Outside a repository only: inside one the cache lives in the common git directory, so a lane's work
+// tree reads the reading its parent's loop head stored rather than measuring again
+// (joshuafolkken/kit#5186). The reading is the main checkout's — its transcripts and every lane's —
+// because only the main checkout writes it (`is_linked_work_tree`); a lane's own measurement reaches
+// only its own transcripts (`cost_transcript.transcript_directories`).
+const FALLBACK_DIRECTORY = ['node_modules', '.cache', 'josh']
 const CACHE_FILE = 'rule-value.txt'
 // Touched when a refresh starts, so the loop head starts at most one per interval however often it runs.
 const STAMP_FILE = 'rule-value.stamp'
@@ -28,14 +34,48 @@ interface CachePorts {
 	start_refresh: (cwd: string) => void
 }
 
+interface FreshReading {
+	text: string
+	taken_at: Date
+}
+
 function cache_path(cwd: string, file: string): string {
-	return path.join(cwd, ...CACHE_DIRECTORY, file)
+	const common = git_common_directory.repository(cwd)
+
+	if (common === undefined) return path.join(cwd, ...FALLBACK_DIRECTORY, file)
+
+	return path.join(common, git_common_directory.STATE_DIRECTORY, file)
 }
 
 function read_cached(cwd: string): string | undefined {
 	return file_reader.read_if_readable(cache_path(cwd, CACHE_FILE))
 }
 
+function taken_at_if_fresh(cwd: string, now_ms: number): Date | undefined {
+	try {
+		const { mtime } = statSync(cache_path(cwd, CACHE_FILE))
+
+		return now_ms - mtime.getTime() < REFRESH_MS ? mtime : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// The stored reading when it was taken inside the refresh interval — what `josh rule:value` prints
+// instead of measuring. `undefined` is a miss: no reading, or one older than the interval.
+function read_fresh(
+	cwd: string = process.cwd(),
+	now_ms: number = Date.now(),
+): FreshReading | undefined {
+	const taken_at = taken_at_if_fresh(cwd, now_ms)
+
+	if (taken_at === undefined) return undefined
+
+	const text = read_cached(cwd)
+
+	return text === undefined ? undefined : { text, taken_at }
+}
+
 function is_refresh_due(cwd: string, now_ms: number): boolean {
 	try {
 		return now_ms - statSync(cache_path(cwd, STAMP_FILE)).mtimeMs >= REFRESH_MS
@@ -63,8 +103,14 @@ function start_refresh_default(cwd: string): void {
 
 const DEFAULT_PORTS: CachePorts = { now: Date.now, start_refresh: start_refresh_default }
 
+// A linked work tree — a lane — measures its own transcripts alone, so it never writes the main
+// checkout's reading or its stamp: either would stand in for the whole repository's for an interval.
+function is_linked_work_tree(cwd: string): boolean {
+	return git_common_directory.resolve(cwd) !== undefined
+}
+
 function refresh_if_due(cwd: string, ports: CachePorts): void {
-	if (!is_refresh_due(cwd, ports.now())) return
+	if (is_linked_work_tree(cwd) || !is_refresh_due(cwd, ports.now())) return
 
 	write_cache_file(cwd, STAMP_FILE, new Date(ports.now()).toISOString())
 	ports.start_refresh(cwd)
@@ -85,10 +131,12 @@ function emit(cwd: string = process.cwd(), ports: CachePorts = DEFAULT_PORTS): v
 
 // The detached refresh's body: the reading written whole, so a reader never sees half of one.
 function store(text: string, cwd: string = process.cwd()): void {
+	if (is_linked_work_tree(cwd)) return
+
 	write_cache_file(cwd, CACHE_FILE, `${text}\n`)
 }
 
-const rule_value_cache = { CACHE_FILE, REFRESH_MS, STAMP_FILE, cache_path, emit, store }
+const rule_value_cache = { CACHE_FILE, REFRESH_MS, STAMP_FILE, cache_path, emit, read_fresh, store }
 
-export type { CachePorts }
+export type { CachePorts, FreshReading }
 export { rule_value_cache }

package/scripts/rules/rule-value-candidates.ts

@@ -0,0 +1,84 @@
+import { delivered_rules, type MeasuredRule } from './delivered-rules'
+import type { RuleReading } from './rule-value'
+
+// The rules `rule:value`'s reading says can go or shrink — the evidence
+// `prompts/collaboration-workflow/residency.md` lets a retirement or a condensation rest on. **It lists, never removes**: each candidate is retired or condensed in an
+// Issue of its own, or kept with a recorded reason.
+//
+// - **Retire**: no run reached the rule, over a window large enough for "never" to mean something.
+//   Below it nothing is judged, since a fresh checkout reaches no rule at all. **Measurable rows
+//   only**: an unmeasured row's trigger is the violation itself, so its `reached 0` says the rule was
+//   never broken — the guard working — not that its situation never arose. A measurable row's trigger
+//   is a neutral act or it declares `reaches` (`rule-value.ts`, `RuleReading.sessions`).
+// - **Condense**: the hook refuses the rule on every occurrence (`decide`) and has refused it at least
+//   once, so the prose need only point at the row — the hook, not the text, keeps it.
+
+// The one threshold: the runs a reading must cover before a rule no run reached is a retirement
+// candidate.
+const MIN_RUNS_FOR_RETIREMENT = 20
+const SEPARATOR = ', '
+const NONE = 'none'
+
+interface RuleCandidates {
+	retire: ReadonlyArray<string>
+	condense: ReadonlyArray<string>
+}
+
+function retire_candidates(readings: ReadonlyArray<RuleReading>, runs: number): Array<string> {
+	if (runs < MIN_RUNS_FOR_RETIREMENT) return []
+
+	return readings
+		.filter((reading) => reading.is_measurable && reading.sessions === 0)
+		.map((reading) => reading.id)
+}
+
+function is_enforced_on_every_occurrence(id: string, rules: ReadonlyArray<MeasuredRule>): boolean {
+	return rules.some((rule) => rule.id === id && rule.decide !== undefined)
+}
+
+function condense_candidates(
+	readings: ReadonlyArray<RuleReading>,
+	rules: ReadonlyArray<MeasuredRule> = delivered_rules.MEASURED_RULES,
+): Array<string> {
+	return readings
+		.filter((reading) => reading.refusals > 0)
+		.filter((reading) => is_enforced_on_every_occurrence(reading.id, rules))
+		.map((reading) => reading.id)
+}
+
+function judge(
+	readings: ReadonlyArray<RuleReading>,
+	runs: number,
+	rules: ReadonlyArray<MeasuredRule> = delivered_rules.MEASURED_RULES,
+): RuleCandidates {
+	return {
+		retire: retire_candidates(readings, runs),
+		condense: condense_candidates(readings, rules),
+	}
+}
+
+function listed(ids: ReadonlyArray<string>): string {
+	return ids.length === 0 ? NONE : ids.join(SEPARATOR)
+}
+
+function render(candidates: RuleCandidates, runs: number): string {
+	const window = `${runs.toString()} runs, threshold ${MIN_RUNS_FOR_RETIREMENT.toString()}`
+
+	return [
+		'candidates:',
+		`  retire (reached 0; ${window}): ${listed(candidates.retire)}`,
+		`  condense (refused on every occurrence by its hook): ${listed(candidates.condense)}`,
+	].join('\n')
+}
+
+const rule_value_candidates = {
+	condense_candidates,
+	judge,
+	render,
+	retire_candidates,
+	MIN_RUNS_FOR_RETIREMENT,
+	NONE,
+}
+
+export type { RuleCandidates }
+export { rule_value_candidates }