@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/discovery/repo-discovery.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
+import { stamped_memo } from '#scripts/lib/stamped-memo'
 import { repo_map_logic, type DiscoveredRepo, type RepoMap } from './repo-map-logic'
 import { repo_origin } from './repo-origin'
 
@@ -59,18 +60,35 @@ function resolve_git_directory(repository_path: string): string | undefined {
 	}
 }
 
-// The work tree's git config text, or nothing when it is unreadable or not a work tree.
-function read_config(repository_path: string): string | undefined {
-	const git_directory = resolve_git_directory(repository_path)
-	if (git_directory === undefined) return undefined
-
+function read_text(file: string): string | undefined {
 	try {
-		return readFileSync(path.join(git_directory, GIT_CONFIG), 'utf8')
+		return readFileSync(file, 'utf8')
 	} catch {
 		return undefined
 	}
 }
 
+// Each work tree's git directory and each config's text, read again only once the `.git` entry or the
+// config itself has changed: `run:board` cites issues through the origin on every redraw
+// (joshuafolkken/kit#4263).
+const git_directories = stamped_memo.create<string | undefined>()
+const configs = stamped_memo.create<string | undefined>()
+
+// The work tree's git config text, or nothing when it is unreadable or not a work tree.
+function read_config(repository_path: string): string | undefined {
+	const git_entry = path.join(repository_path, GIT_DIRECTORY)
+	const git_directory = git_directories.of(
+		repository_path,
+		stamped_memo.file_stamp(git_entry),
+		() => resolve_git_directory(repository_path),
+	)
+	if (git_directory === undefined) return undefined
+
+	const config = path.join(git_directory, GIT_CONFIG)
+
+	return configs.of(config, stamped_memo.file_stamp(config), () => read_text(config))
+}
+
 // The `origin` URL a work tree declares, or nothing when it has no `origin`, no readable config, or
 // is not a work tree at all. Every failure reads as "no remote" so one unreadable sibling cannot
 // fail a command whose contract is to report what it could find.

package/scripts/doctor/doctor-consumer.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { file_reader } from '#scripts/lib/read-file'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
@@ -37,11 +38,7 @@ const STATE_MISSING = 'missing'
 type ClaudeMdState = typeof STATE_OK | typeof STATE_TARGET_MISSING | typeof STATE_MISSING
 
 function parse_manifest(root: string): ManifestShape | undefined {
-	const content = file_reader.read_if_readable(path.join(root, 'package.json'))
-	if (content === undefined) return undefined
-	const parsed = manifest_schema.safeParse(json_value.parse_or_undefined(content))
-
-	return parsed.success ? parsed.data : undefined
+	return package_manifest.read_manifest_if_valid(root, manifest_schema)
 }
 
 function lists_kit_dependency(manifest: ManifestShape | undefined): boolean {

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

@@ -58,7 +58,7 @@ function block_ceiling(size: number): number {
 // unreached file, so the definition cannot rot as documents move on or off the execution path.
 const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/dependency-update/SKILL.md', bytes: 4096 },
-	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 12_288 },
+	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 8192 },
 	{ path: '.claude/skills/epic-commands/epic-bundle.md', bytes: 4096 },
 	{ path: '.claude/skills/epic-commands/execution-waves.md', bytes: 4096 },
 	{ path: '.claude/skills/verify-ui/SKILL.md', bytes: 4096 },
@@ -74,17 +74,20 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ 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-run.md', bytes: 69_632 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands.md', bytes: 53_248 },
 	{ 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 },
+	// The priority declaration and its criteria (joshuafolkken/kit#4383) crossed the 8192 block.
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 12_288 },
+	{ path: 'prompts/collaboration-workflow/lane-instructions.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/measurement.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-scan.ts

@@ -57,7 +57,7 @@ function command_references(text: string): Array<string> {
 		.filter((name) => !name.endsWith(':'))
 }
 
-// A `<placeholder>` inside a command, and `depth:<n>` after the char class stops at `<`, both leave a
+// A `<placeholder>` inside a command, and `label:<n>` after the char class stops at `<`, both leave a
 // token that is not a real label. Real labels never end in a colon and never carry angle brackets.
 function is_real_label(token: string): boolean {
 	return token.length > 0 && !token.endsWith(':') && !token.includes('<')

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

@@ -1,7 +1,7 @@
-#!/usr/bin/env tsx
 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'
@@ -21,7 +21,6 @@ import { entry_read_set } from './entry-read-set'
 // renamed would otherwise print nothing and read as a section with nothing in it — the one outcome
 // that is worse than reading the whole file.
 
-const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const FILE_ARGUMENT = 0
 const HEADING_ARGUMENT = 1
@@ -35,14 +34,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 {
@@ -89,12 +99,6 @@ function run(argv: ReadonlyArray<string>, root: string = process.cwd()): number
 	return markdown === undefined ? FAILURE_EXIT_CODE : print_section(markdown, heading, root)
 }
 
-function main(argv: ReadonlyArray<string>): void {
-	process.exitCode = run(argv)
-}
-
 const document_section_cli = { FAILURE_EXIT_CODE, USAGE, resolve_document, run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
-
 export { document_section_cli }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { document_section_cli } from './document-section-cli'
+
+// The `josh doc:section` entry, kept apart from `document-section-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = document_section_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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-cli.ts

@@ -222,22 +222,27 @@ function fetch_anomalies(
 //
 // A listing that could not be read is left out of the map rather than entered as `[]`, so a
 // transport failure reads as "not asked" instead of "nobody recorded anything" — the finding it
-// would otherwise manufacture is an `error`, which stops the epic.
+// would otherwise manufacture is an `error`, which stops the epic. Only a comment from an author with
+// write access records a rationale.
 async function read_order_comments(
 	pairs: ReadonlyArray<OrderPair>,
 ): Promise<Map<string, ReadonlyArray<string>>> {
 	const ends = epic_audit_rationale.pair_ends(pairs)
-	const listings = await Promise.all(
-		ends.map(async (child) => await git_gh_command.issue_list_comments(String(child.number))),
+	const parsed = await Promise.all(
+		ends.map(async (child) => {
+			const listing = await git_gh_command.issue_list_comments(String(child.number))
+
+			return await issue_read.parse_comments(listing)
+		}),
 	)
 
 	return new Map(
 		ends.flatMap((child, index) => {
-			const comments = issue_read.parse_comments(listings[index])
+			const comments = parsed[index]
 
 			return comments === undefined
 				? []
-				: [[epic_graph.key_of(child), comments.map((comment) => comment.body)] as const]
+				: [[epic_graph.key_of(child), issue_read.trusted_bodies(comments)] as const]
 		}),
 	)
 }
@@ -349,7 +354,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 // `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
 // a pipe is asynchronous on macOS, so exiting can tear the process down before it drains. This
 // command's answer is what a workflow reads and acts on, which is exactly that pipe. The same shape
-// is in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first.
+// is in `scripts/cost-runtime/cost-main.ts`, which met the truncation first.
 async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
@@ -360,6 +365,7 @@ const epic_audit_cli = {
 	attach_bodies,
 	resolve_reference_states,
 	outside_references,
+	read_order_comments,
 	audit,
 	run,
 }

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 }

package/scripts/epic/epic-bundle-apply.ts

@@ -0,0 +1,137 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { epic_add } from './epic-add'
+import {
+	epic_bundle,
+	type BacklogIssue,
+	type BundleAction,
+	type BundleDecision,
+} from './epic-bundle'
+import { epic_reconcile } from './epic-reconcile'
+import { epic_run } from './epic-run'
+
+// `josh epic:bundle <N> --apply` — write the answer whose placement is settled: `add_to_epic` through
+// `epic --add`'s writer, `create_epic` through `epic`'s. Nothing here edits an epic itself, so the
+// task list and the `blocked-by` relations stay as those writers keep them.
+//
+// **An order the candidates already record is carried into the epic body** by `epic --reconcile`,
+// which declares exactly the recorded relations — an order nobody recorded is never invented.
+//
+// `ask` stays the caller's: which epic to choose is a judgement, recorded with its reasoning.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface ApplyInput {
+	decision: BundleDecision
+	subject: BacklogIssue
+	// The backlog rows of `decision.candidates`, as `format_order` reads them.
+	members: ReadonlyArray<BacklogIssue>
+	is_membership_established: boolean
+}
+
+const UNAPPLIED_LINES: Readonly<Partial<Record<BundleAction, string>>> = {
+	ask: '↷ `--apply` wrote nothing: the related issues sit in more than one epic. Choose one and place it with `pnpm josh epic --add <E> <N> --decision-file <path>`.',
+	none: '↷ `--apply` wrote nothing: there is nothing to place.',
+}
+const WITHHELD_LINE =
+	'↷ `--apply` wrote nothing: the epic listing was cut short, so no placement was confirmed.'
+const UNREAD_EPIC_LINE =
+	"✖ The new epic's number could not be read, so the recorded order was not written; run `pnpm josh epic --reconcile <E>` on it."
+
+function has_order(input: ApplyInput): boolean {
+	return epic_bundle.bundle_dependency_links(input.subject, input.members).length > 0
+}
+
+function children_of(input: ApplyInput): Array<number> {
+	return epic_bundle.bundle_children(input.subject, input.members)
+}
+
+// An epic whose number could not be read cannot be given the order, so that is a failure rather than
+// an order silently left out.
+async function reconcile_order(
+	epic_number: number | undefined,
+	input: ApplyInput,
+): Promise<number> {
+	if (!has_order(input)) return SUCCESS_EXIT_CODE
+
+	if (epic_number === undefined) {
+		console.error(UNREAD_EPIC_LINE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await epic_reconcile.reconcile_epic(epic_number)
+}
+
+// A member another epic tracks stays there: `add_to_epic` can name an inner epic while a candidate sits
+// in its parent, and adding that candidate here would put one issue in two task lists.
+function placeable(epic_number: number, input: ApplyInput): ApplyInput {
+	const members = input.members.filter(
+		(member) => member.epic === undefined || member.epic === epic_number,
+	)
+
+	return { ...input, members }
+}
+
+async function add_to_epic(epic_number: number, input: ApplyInput): Promise<number> {
+	const placed = placeable(epic_number, input)
+	const added = await epic_add.add_children({ epic_number, children: children_of(placed) })
+	if (added !== SUCCESS_EXIT_CODE) return added
+
+	return await reconcile_order(epic_number, placed)
+}
+
+// The title is the subject's, since the subject is what the bundle was asked about; the rationale is
+// the verdict's own reason, which already names the signal that grouped them.
+function title_of(subject: BacklogIssue): string {
+	const title = subject.title ?? `bundle with ${issue_cite.plain(subject.number)}`
+
+	return `Epic: ${title}`
+}
+
+async function create_epic(input: ApplyInput): Promise<number> {
+	const epic_number = await epic_run.create_epic_number({
+		title: title_of(input.subject),
+		children: children_of(input),
+		rationale: input.decision.reason,
+		is_ordered: false,
+	})
+
+	return await reconcile_order(epic_number, input)
+}
+
+function report_unapplied(action: BundleAction): number {
+	const line = UNAPPLIED_LINES[action]
+	if (line !== undefined) console.info(line)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function apply_decision(input: ApplyInput): Promise<number> {
+	const { decision } = input
+
+	if (!input.is_membership_established) {
+		console.info(WITHHELD_LINE)
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	if (decision.action === 'add_to_epic' && decision.epic !== undefined) {
+		return await add_to_epic(decision.epic, input)
+	}
+
+	if (decision.action === 'create_epic') return await create_epic(input)
+
+	return report_unapplied(decision.action)
+}
+
+const epic_bundle_apply = {
+	UNAPPLIED_LINES,
+	WITHHELD_LINE,
+	UNREAD_EPIC_LINE,
+	title_of,
+	apply_decision,
+}
+
+export { epic_bundle_apply }
+export type { ApplyInput }