@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,191 @@
+import type { DependencyLink } from '#scripts/git/git-epic-parse'
+import { epic_audit_logic, type AuditFinding } from './epic-audit'
+import type { AuditChild } from './epic-audit-checks'
+import { epic_graph, type IssueReference } from './epic-graph'
+
+// Check 6 — a declared order between two open children that nobody wrote a reason for
+// (joshuafolkken/kit#1712).
+//
+// **Every other check looks the other way.** They report a dependency the epic *omitted* — prose or
+// acceptance criteria naming a sibling with nothing ordering the two. Not one of them reads the
+// declaration itself, so a chain somebody typed by hand passed the audit exactly as a justified one
+// did: on 2026-09-10 the chain `#1690 -> #1694 -> #1703 -> #1679 -> #1675 -> #1676` serialized five
+// otherwise independent children through `epicrun`, and the audit reported **0 errors** both while
+// it stood and after it was deleted. It was found because a person asked why the backlog had gone
+// single-file, which is not a mechanism.
+//
+// **Where a reason lives is already settled**, so this check does not invent a place to look:
+// `josh epic --add --decision-file` writes the record to the epic's `## Decisions` **and** as a
+// comment on each child, and `--remove` does the same for a deletion. Those two are the whole search.
+
+const UNJUSTIFIED_ORDER = 'unjustified order'
+
+// Both ends of one declared order, resolved to the children they name.
+interface OrderPair {
+	blocker: AuditChild
+	blocked: AuditChild
+}
+
+interface RationaleInput {
+	pairs: ReadonlyArray<OrderPair>
+	// Every place the epic body records a reason: its `## Decisions` log and its `## Split rationale`,
+	// as one text.
+	decisions: string
+	// Each pair end's comments, keyed by `epic_graph.key_of`. **An absent key means the listing could
+	// not be read, and an empty array means it was read and holds nothing** — the two are different
+	// facts, and `is_reportable` below is what keeps them apart.
+	comments: ReadonlyMap<string, ReadonlyArray<string>>
+	current_repo: string
+}
+
+const { key_of } = epic_graph
+
+function find_child(
+	children: ReadonlyArray<AuditChild>,
+	reference: IssueReference,
+): AuditChild | undefined {
+	return children.find((candidate) => key_of(candidate) === key_of(reference))
+}
+
+// Whether this pair is one the check may speak about. Three conditions, and each excludes a case the
+// finding would be wrong about rather than merely noisy:
+//
+// **Both ends open.** A settled order can no longer stall anything, which is the same reason
+// `order_level` demotes a settled contradiction — and joshuafolkken/kit#1712 asks for it by name.
+// **Both ends in the repository the audit runs in.** The comment listing reads that repository and
+// takes no `--repo` (`git-gh-issue-read.ts`), so a cross-repository end's record cannot be read at
+// all and every such order would be reported as unjustified whatever its author wrote.
+function is_open_local(child: AuditChild, current_repo: string): boolean {
+	return child.state !== 'CLOSED' && child.repo === current_repo
+}
+
+// The declared orders this check can speak about, resolved to children. A link naming something the
+// epic does not track is left to `epic:next`'s own graph anomalies, which is where a declaration
+// that names a stranger is already reported.
+function order_pairs(
+	links: ReadonlyArray<DependencyLink>,
+	children: ReadonlyArray<AuditChild>,
+	epic_repo: string,
+	current_repo: string,
+): Array<OrderPair> {
+	return links.flatMap((link) => {
+		const blocker = find_child(children, { repo: epic_repo, number: link.blocker })
+		const blocked = find_child(children, { repo: epic_repo, number: link.blocked })
+		if (blocker === undefined || blocked === undefined) return []
+
+		return is_open_local(blocker, current_repo) && is_open_local(blocked, current_repo)
+			? [{ blocker, blocked }]
+			: []
+	})
+}
+
+// The children whose comments have to be read to answer for these pairs.
+function pair_ends(pairs: ReadonlyArray<OrderPair>): Array<AuditChild> {
+	const seen = new Set<string>()
+
+	return pairs
+		.flatMap((pair) => [pair.blocker, pair.blocked])
+		.filter((child) => {
+			const is_new = !seen.has(key_of(child))
+
+			seen.add(key_of(child))
+
+			return is_new
+		})
+}
+
+function named_keys(text: string, pair: OrderPair, current_repo: string): ReadonlySet<string> {
+	const known = epic_audit_logic.known_repos([pair.blocker, pair.blocked], current_repo)
+
+	return new Set(
+		epic_audit_logic
+			.parse_issue_references(text, current_repo, known)
+			.map((reference) => key_of(reference)),
+	)
+}
+
+// A comment on one end that names the **other** end. The issue it sits on is named by where it is,
+// so a record posted on `#102` reads "placed after #101" and never repeats its own number — asking
+// for both would refuse the exact wording `--decision-file` produces.
+function has_record_on(
+	input: RationaleInput,
+	on: AuditChild,
+	about: AuditChild,
+	pair: OrderPair,
+): boolean {
+	return (input.comments.get(key_of(on)) ?? []).some((comment) =>
+		named_keys(comment, pair, input.current_repo).has(key_of(about)),
+	)
+}
+
+// **A comment is matched one at a time; the `## Decisions` section is matched whole, once.** A
+// comment is one record by construction — `--decision-file` posts exactly one — so the question can
+// be asked of a single comment. The section holds many records with no delimiter a reader can rely
+// on, so it is asked the weaker question: does this section talk about both issues at all. That is
+// deliberately generous, and generous is the right side for a finding that stops a run — it errs
+// toward silence rather than toward accusing an author who did write the record.
+function is_justified(input: RationaleInput, pair: OrderPair): boolean {
+	const declared = named_keys(input.decisions, pair, input.current_repo)
+
+	if (declared.has(key_of(pair.blocker)) && declared.has(key_of(pair.blocked))) return true
+
+	return (
+		has_record_on(input, pair.blocker, pair.blocked, pair) ||
+		has_record_on(input, pair.blocked, pair.blocker, pair)
+	)
+}
+
+// **An error rather than a warning**, and the choice is the one joshuafolkken/kit#1712 asks to be
+// recorded.
+//
+// A warning would not be read: one real epic carries 447 of them, and the whole reason this check
+// exists is that a false order was invisible. The counter-argument is `order_level`'s doctrine —
+// where the machine cannot tell whether something is wrong, it warns — and it does not reach this
+// check, because what is asserted here is not "this order is wrong". It is "this order's reason is
+// not recorded", which is a fact about the repository's own rule that a placement decision is
+// written down, not a judgement about the order.
+//
+// What makes the level affordable is that both remedies are now one command: `josh epic --remove`
+// deletes the order, and `--decision-file` on either command records the reason. Before
+// joshuafolkken/kit#1712 the first of those did not exist, and an error would have sent the reader
+// to the hand edit `CLAUDE.md` forbids.
+function unjustified_message(pair: OrderPair, current_repo: string): string {
+	const blocker = epic_graph.format_reference(pair.blocker, current_repo)
+	const blocked = epic_graph.format_reference(pair.blocked, current_repo)
+
+	return (
+		`The declared order ${blocker} -> ${blocked} has no recorded reason — neither the epic's ` +
+		'`## Decisions` or `## Split rationale` section nor a comment on either issue mentions the ' +
+		`other. Remove it with \`josh epic --remove <E> ${String(pair.blocker.number)} ` +
+		`${String(pair.blocked.number)}\`, or record why with \`--decision-file\`, whose text has to ` +
+		'name both issues for this check to find it.'
+	)
+}
+
+// Whether both ends' comments were actually read. A listing that failed leaves its child out of the
+// map, and judging that as "nobody recorded anything" turns a rate limit into an `error` that stops
+// the epic over an order whose reason *was* written down. So a pair with an unread end is not
+// reported at all — the audit says nothing rather than something false.
+function is_reportable(input: RationaleInput, pair: OrderPair): boolean {
+	return input.comments.has(key_of(pair.blocker)) && input.comments.has(key_of(pair.blocked))
+}
+
+function find_unjustified_orders(input: RationaleInput): Array<AuditFinding> {
+	return input.pairs
+		.filter((pair) => is_reportable(input, pair) && !is_justified(input, pair))
+		.map((pair) => ({
+			level: 'error' as const,
+			check: UNJUSTIFIED_ORDER,
+			message: unjustified_message(pair, input.current_repo),
+		}))
+}
+
+const epic_audit_rationale = {
+	UNJUSTIFIED_ORDER,
+	order_pairs,
+	pair_ends,
+	find_unjustified_orders,
+}
+
+export { epic_audit_rationale }
+export type { OrderPair, RationaleInput }

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

@@ -0,0 +1,101 @@
+import type { AuditFinding } from './epic-audit'
+import { epic_graph, type GraphAnomaly, type IssueReference } from './epic-graph'
+
+// Turning the findings into a report and an exit code.
+//
+// Only errors decide the exit code. A warning is something a reader has to look at, not something a
+// gate may fail on: check 1 fires on a legitimate forward reference as readily as on a real missing
+// dependency, and a gate that failed on both would make design notes unwritable
+// (joshuafolkken/kit#870).
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const PASS_LINE = '✓ No cross-child contradictions found.'
+const UNREADABLE_CHECK = 'unreadable children'
+
+interface AuditResult {
+	findings: ReadonlyArray<AuditFinding>
+	exit_code: number
+}
+
+// The graph's own problems, as findings. A cycle or a body-versus-relations disagreement is an error
+// — `epic:next` already refuses to run on either, so an audit that only warned would disagree with
+// the command that acts on it.
+function anomaly_findings(anomalies: ReadonlyArray<GraphAnomaly>): Array<AuditFinding> {
+	return anomalies.map((anomaly) => ({
+		level: 'error' as const,
+		check: anomaly.kind.replaceAll('_', ' '),
+		message: anomaly.message,
+	}))
+}
+
+// A child that could not be read makes every check unreliable, and `epic:next` already refuses to
+// run on that state — an audit that reported a clean bill on the same input would contradict the
+// command that acts on it.
+//
+// Each one is written with the repository it lives in. `- [ ] sveltejs/kit#7`, refused by the owner
+// restriction, was reported as `Could not read #7` and sent the reader to this repository's issue 7
+// — the one message joshuafolkken/kit#1014 left resolving against the wrong repository
+// (joshuafolkken/kit#1016).
+function unreadable_findings(
+	missing: ReadonlyArray<IssueReference>,
+	current_repo: string,
+): Array<AuditFinding> {
+	if (missing.length === 0) return []
+	const list = epic_graph.format_references(missing, current_repo)
+
+	return [
+		{
+			level: 'error',
+			check: UNREADABLE_CHECK,
+			message: `Could not read ${list}; the audit would be reading an incomplete epic.`,
+		},
+	]
+}
+
+function has_error(findings: ReadonlyArray<AuditFinding>): boolean {
+	return findings.some((finding) => finding.level === 'error')
+}
+
+function build_result(findings: ReadonlyArray<AuditFinding>): AuditResult {
+	return { findings, exit_code: has_error(findings) ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE }
+}
+
+function format_finding(finding: AuditFinding): string {
+	return `${finding.level === 'error' ? '✖' : '⚠'} ${finding.check}: ${finding.message}`
+}
+
+// Errors first, so the things that must be fixed are not buried under the things to look at.
+function sort_findings(findings: ReadonlyArray<AuditFinding>): Array<AuditFinding> {
+	return findings.toSorted((left, right) => {
+		if (left.level === right.level) return 0
+
+		return left.level === 'error' ? -1 : 1
+	})
+}
+
+function format_report(result: AuditResult): string {
+	if (result.findings.length === 0) return PASS_LINE
+	const lines = sort_findings(result.findings).map((finding) => format_finding(finding))
+	const errors = result.findings.filter((finding) => finding.level === 'error').length
+	const warnings = result.findings.length - errors
+
+	return [
+		...lines,
+		'',
+		`${String(errors)} error(s), ${String(warnings)} warning(s). Only errors fail this check.`,
+	].join('\n')
+}
+
+const epic_audit_report = {
+	PASS_LINE,
+	anomaly_findings,
+	unreadable_findings,
+	has_error,
+	build_result,
+	sort_findings,
+	format_report,
+}
+
+export type { AuditResult }
+export { epic_audit_report }

package/scripts/epic/epic-audit.ts

@@ -0,0 +1,240 @@
+import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
+
+// Reading an epic's children against each other.
+//
+// `epic:check` verifies one epic's *format*; nothing verified that the children agree. A hand audit
+// of joshuafolkken/kit#858 found two contradictions that would have stalled the implementation, and
+// `epic:check` reported all four of its requirements as passing throughout (joshuafolkken/kit#870).
+//
+// The graph's own properties — a cycle, and a body that declares one order while the relations
+// record another — are already detected by `epic:next` for its own purposes. This module is a
+// consumer of that, not a second implementation. What is new here is reading *inside* the children.
+
+// An issue reference anywhere in prose. Deliberately broader than the task-list pattern the epic
+// format uses: the point is to notice a child talking about another child at all.
+//
+// The number is matched on its own and the `owner/repo` in front of it is read by walking backwards,
+// rather than by widening the pattern to cover both forms: two unbounded segments ahead of the `#`
+// backtrack, and this runs over every child's whole body.
+const REFERENCE_PATTERN = /#(\d+)\b/gu
+// What may appear in the `owner/repo` written in front of a `#`: exactly the set the previous
+// lookbehind refused a bare reference after, plus the `.` a repository name may legitimately contain.
+//
+// The dot is where this parse and the task-list parse used to disagree. `git_epic_parse`'s
+// `EXTERNAL_REFERENCE_SOURCE` allows one, so `- [ ] owner/site.com#40` is tracked as a genuine
+// cross-repository child; this one excluded it, so a sibling quoting `owner/site.com#40` was read
+// back as `com` — no repository — and every check skipped it in silence. A child that can be tracked
+// but never cited is the gap joshuafolkken/kit#1016 closes.
+//
+// Nothing in the syntax separates `owner/site.com` from a path written in prose: `prompts/review.md`
+// has the same shape, and reading it as a repository is the misread the exclusion was there to
+// prevent. So the dot is admitted and `reference_repo` decides — a dotted name is a repository only
+// when the epic actually tracks one by that name.
+const PREFIX_CHARACTER = /[\w./-]/u
+const REPO_SEPARATOR = '/'
+const REPO_PART_COUNT = 2
+const REPO_NAME_DOT = '.'
+// No epic in view, so no dotted name can be confirmed against one. Shared rather than allocated per
+// call: it is never written to.
+const NO_KNOWN_REPOS: ReadonlySet<string> = new Set()
+// Where a child states what it must deliver. Both spellings, because the bodies are written in
+// whichever language the session was in.
+const ACCEPTANCE_HEADINGS: ReadonlyArray<string> = ['## 受け入れ条件', '## Acceptance criteria']
+const HEADING_PREFIX = '## '
+
+type FindingLevel = 'error' | 'warning'
+
+// Whether an issue a body cites is open, closed, or could not be read at all. Declared beside the
+// parse rather than in either consumer, so the checks and the command that resolves the states name
+// one type instead of two identical ones.
+type ReferenceState = 'OPEN' | 'CLOSED' | 'UNRESOLVED'
+
+interface AuditFinding {
+	level: FindingLevel
+	check: string
+	message: string
+}
+
+// The text immediately in front of a `#`, up to the first character that cannot be part of an
+// `owner/repo`.
+function prefix_before(text: string, index: number): string {
+	let start = index
+
+	while (start > 0 && PREFIX_CHARACTER.test(text[start - 1] ?? '')) start -= 1
+
+	return text.slice(start, index)
+}
+
+// Two non-empty segments, which is all a repository name and a path have in common.
+function is_repo_shape(parts: ReadonlyArray<string>): boolean {
+	return parts.length === REPO_PART_COUNT && parts.every((part) => part !== '')
+}
+
+// Which repository a reference names: the body's own when nothing is written in front of the `#`,
+// the named one when an `owner/repo` is, and none at all when the prefix is something else — a bare
+// word (`kit#12` names nothing GitHub can resolve) or the tail of a URL.
+//
+// A dotted name is the one case the shape cannot settle, so it is settled by `known_repos` — the
+// repositories this epic actually spans. `owner/site.com#40` is read when the epic tracks a child
+// there, and `prompts/review.md#5` is not read at all, because no epic tracks a repository by that
+// name. That makes the set of children that can be *tracked* and the set that can be *cited* the same
+// set, which is what joshuafolkken/kit#1016 asked for, without admitting the path misread that
+// widening the pattern outright would have brought back.
+function reference_repo(
+	prefix: string,
+	repo: string,
+	known: ReadonlySet<string>,
+): string | undefined {
+	if (prefix === '') return repo
+	if (!is_repo_shape(prefix.split(REPO_SEPARATOR))) return undefined
+	if (!prefix.includes(REPO_NAME_DOT)) return prefix
+
+	return known.has(prefix) ? prefix : undefined
+}
+
+function to_reference(
+	text: string,
+	match: RegExpExecArray,
+	repo: string,
+	known: ReadonlySet<string>,
+): IssueReference | undefined {
+	const issue_number = Number(match[1])
+	if (!Number.isSafeInteger(issue_number)) return undefined
+	const named_repo = reference_repo(prefix_before(text, match.index), repo, known)
+
+	return named_repo === undefined ? undefined : { repo: named_repo, number: issue_number }
+}
+
+// The same issue named twice is one reference, however each mention was written. Kept in the order
+// the prose wrote them in, which is the order the findings then read in.
+function unique_references(references: ReadonlyArray<IssueReference>): Array<IssueReference> {
+	const seen = new Set<string>()
+
+	return references.filter((reference) => {
+		const key = epic_graph.key_of(reference)
+		const is_new = !seen.has(key)
+
+		seen.add(key)
+
+		return is_new
+	})
+}
+
+// The issues a piece of prose refers to, each with the repository it lives in. `repo` is the
+// `owner/name` whose body this is: an unqualified `#N` there names that repository's issue N.
+//
+// `known` names the repositories the epic in hand spans, and only a dotted name consults it —
+// see `reference_repo`. A caller with no epic in view passes nothing and gets the dotless reading,
+// which is what every caller got before joshuafolkken/kit#1016.
+function parse_issue_references(
+	text: string,
+	repo: string,
+	known: ReadonlySet<string> = NO_KNOWN_REPOS,
+): Array<IssueReference> {
+	const found: Array<IssueReference> = []
+
+	for (const match of text.matchAll(REFERENCE_PATTERN)) {
+		const reference = to_reference(text, match, repo, known)
+
+		if (reference !== undefined) found.push(reference)
+	}
+
+	return unique_references(found)
+}
+
+// The repositories an epic actually spans, which is what settles a dotted name written in prose:
+// `owner/site.com#40` is a reference when a child lives there and a path otherwise. Built from the
+// children rather than supplied, so a caller cannot hand the parse a set that disagrees with the
+// epic being read (joshuafolkken/kit#1016).
+function known_repos(
+	children: ReadonlyArray<IssueReference>,
+	current_repo: string,
+): ReadonlySet<string> {
+	return new Set([current_repo, ...children.map((child) => child.repo)])
+}
+
+// The issue numbers a piece of prose refers to *in its own repository*. Kept as the narrower reading
+// of the same parse rather than a second one: `epic:bundle` compares two issues' references by
+// number and has no cross-repository notion to compare with.
+function parse_references(text: string, repo = ''): Array<number> {
+	return parse_issue_references(text, repo)
+		.filter((reference) => reference.repo === repo)
+		.map((reference) => reference.number)
+}
+
+function is_acceptance_heading(line: string): boolean {
+	return ACCEPTANCE_HEADINGS.includes(line.trim())
+}
+
+function is_heading(line: string): boolean {
+	return line.trimStart().startsWith(HEADING_PREFIX)
+}
+
+// The lines under the acceptance-criteria heading, up to the next `##`. Shaped like the other
+// section readers in this repository, for the same reason: a regex spanning the block backtracks.
+function section_lines(lines: ReadonlyArray<string>): Array<string> {
+	const start = lines.findIndex((line) => is_acceptance_heading(line))
+	if (start === -1) return []
+	const rest = lines.slice(start + 1)
+	const end = rest.findIndex((line) => is_heading(line))
+
+	return end === -1 ? rest : rest.slice(0, end)
+}
+
+// The acceptance-criteria section of a child's body, or an empty string.
+function acceptance_section(body: string | undefined): string {
+	if (body === undefined) return ''
+
+	return section_lines(body.split('\n')).join('\n')
+}
+
+// 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.
+function collect_blockers(
+	index: ReadonlyMap<string, EpicChild>,
+	node: string,
+): ReadonlySet<string> {
+	const seen = new Set<string>()
+	const pending = [...epic_graph.blockers_of(index, node)]
+
+	while (pending.length > 0) {
+		const current = pending.pop() ?? node
+
+		if (seen.has(current)) {
+			continue
+		}
+
+		seen.add(current)
+		pending.push(...epic_graph.blockers_of(index, current))
+	}
+
+	return seen
+}
+
+// Both ends are named by identity — repository plus number — because an epic can track two children
+// whose numbers collide across repositories (joshuafolkken/kit#864).
+function depends_on(
+	index: ReadonlyMap<string, EpicChild>,
+	node: EpicChild,
+	target: EpicChild,
+): boolean {
+	return collect_blockers(index, epic_graph.key_of(node)).has(epic_graph.key_of(target))
+}
+
+// `REFERENCE_PATTERN` is deliberately not exported: the guard that decides what may sit in front of
+// a `#` lives in `prefix_before`, so the pattern on its own matches the tail of `owner/repo#12` —
+// the very reading this module exists to prevent.
+const epic_audit_logic = {
+	ACCEPTANCE_HEADINGS,
+	unique_references,
+	known_repos,
+	parse_issue_references,
+	parse_references,
+	acceptance_section,
+	collect_blockers,
+	depends_on,
+}
+
+export type { AuditFinding, FindingLevel, ReferenceState }
+export { epic_audit_logic }