@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/package/package-scout-cli.ts

@@ -6,14 +6,17 @@ import { z } from 'zod'
 import {
 	package_scout,
 	type PackageMetrics,
+	type RankedTable,
 	type RegistryFacts,
 	type SearchCandidate,
 } from './package-scout'
 import { package_scout_format } from './package-scout-format'
+import { package_scout_reuse, type ReuseOutcome } from './package-scout-reuse'
 
-// `josh pkg:scout <keywords> [--size <n>]` — before the Package-First tier decision, rank the
-// candidate packages by measured metrics so "clearly best (Tier A)" and "genuine toss-up (Tier B)"
-// are read off the output rather than judged.
+// `josh pkg:scout <keywords> [--size <n>] [--issue <n>]` — before the Package-First tier decision,
+// rank the candidate packages by measured metrics so "clearly best (Tier A)" and "genuine toss-up
+// (Tier B)" are read off the output rather than judged. A toss-up the target Issue already settled by
+// reusing existing code is recorded there and read as Tier A (`package-scout-reuse.ts`).
 //
 // The registry answers in three reads: one search for the candidates, then per candidate a downloads
 // point and the latest version metadata (bundled types, license, unpacked size). A per-candidate read
@@ -26,7 +29,7 @@ const ARGV_OFFSET = 2
 const DEFAULT_SIZE = 10
 const REGISTRY = 'https://registry.npmjs.org'
 const DOWNLOADS_API = 'https://api.npmjs.org/downloads/point/last-week'
-const USAGE = 'Usage: josh pkg:scout <keywords> [--size <n>]'
+const USAGE = 'Usage: josh pkg:scout <keywords> [--size <n>] [--issue <n>]'
 const SEARCH_FAILED_MESSAGE =
 	'Could not read the npm registry search, so no candidates can be ranked — check the network and try again.'
 
@@ -112,6 +115,7 @@ async function search(keywords: string, size: number): Promise<Array<SearchCandi
 interface ScoutArguments {
 	keywords: string
 	size: number
+	issue: string | undefined
 }
 
 function parse_size(raw: string | undefined): number {
@@ -125,17 +129,32 @@ function parse_size(raw: string | undefined): number {
 function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
 	const parsed = cli_flags.parse_or_undefined({
 		args: [...argv],
-		options: { size: { type: 'string' } },
+		options: { size: { type: 'string' }, issue: { type: 'string' } },
 		allowPositionals: true,
 	})
 	const keywords = parsed?.positionals.join(' ').trim() ?? ''
 
 	if (parsed === undefined || keywords === '') return undefined
 
-	return { keywords, size: parse_size(parsed.values.size) }
+	return { keywords, size: parse_size(parsed.values.size), issue: parsed.values.issue }
 }
 
-async function report(args: ScoutArguments): Promise<number> {
+// Only a close pair asks a question the Issue may already have answered; a clear pick, a lone
+// candidate or no candidate never reads the Issue.
+async function reuse_of(
+	args: ScoutArguments,
+	table: RankedTable,
+	directory: string,
+): Promise<ReuseOutcome | undefined> {
+	const [first] = table.ranked
+	if (first === undefined || table.verdict !== 'close') return undefined
+
+	const request = { issue: args.issue, keywords: args.keywords, rejected: first.name, directory }
+
+	return await package_scout_reuse.check(request)
+}
+
+async function report(args: ScoutArguments, directory: string): Promise<number> {
 	const candidates = await search(args.keywords, args.size)
 
 	if (candidates === undefined) {
@@ -145,14 +164,21 @@ async function report(args: ScoutArguments): Promise<number> {
 	}
 
 	const metrics = await Promise.all(candidates.map(async (candidate) => await gather(candidate)))
+	const table = package_scout.build_table(metrics)
+	const reuse = await reuse_of(args, table, directory)
 
 	console.info(`Candidates for "${args.keywords}" (ranked by npm score):`)
-	console.info(package_scout_format.format_table(package_scout.build_table(metrics)))
+	console.info(package_scout_format.format_table(table, reuse))
 
-	return SUCCESS_EXIT_CODE
+	return reuse !== undefined && package_scout_reuse.is_failure(reuse)
+		? FAILURE_EXIT_CODE
+		: SUCCESS_EXIT_CODE
 }
 
-async function run(argv: ReadonlyArray<string>): Promise<number> {
+async function run(
+	argv: ReadonlyArray<string>,
+	directory: string = process.cwd(),
+): Promise<number> {
 	const args = read_arguments(argv)
 
 	if (args === undefined) {
@@ -161,7 +187,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await report(args)
+	return await report(args, directory)
 }
 
 // `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to

package/scripts/package/package-scout-format.ts

@@ -4,6 +4,7 @@ import {
 	type RankedTable,
 	type TierVerdict,
 } from './package-scout'
+import type { ReuseOutcome } from './package-scout-reuse'
 
 // The printed shape of `josh pkg:scout` — one line per candidate with each metric labelled, then a
 // verdict line that names whether the choice is a Tier A pick or a Tier B question.
@@ -111,30 +112,43 @@ function lead_line(table: RankedTable): string {
 	return `${names} by ${format_percent(table.gap ?? 0)}`
 }
 
-function format_pair(table: RankedTable, verdict: TierVerdict): string {
+// joshuafolkken/kit#6510: a close pair is Tier A only once the Issue's reuse decision is recorded;
+// every other outcome keeps the question and prints its note, so a stopped check never reads as made.
+function format_close(lead: string, reuse: ReuseOutcome | undefined): string {
+	if (reuse?.kind === 'recorded') {
+		return `Tier: close — ${lead}; ${reuse.note} — no dependency added (Tier A). Auto-decided: ${reuse.url}`
+	}
+
+	const line = `Tier: close — ${lead}; ask the user (Tier B).`
+
+	return reuse === undefined ? line : `${line}\n${reuse.note}`
+}
+
+function format_pair(table: RankedTable, verdict: TierVerdict, reuse?: ReuseOutcome): string {
 	const threshold = format_percent(package_scout.NEAR_TIE_THRESHOLD)
 	const lead = lead_line(table)
 
 	if (verdict === 'clear') return `Tier: clear — ${lead} (≥ ${threshold}); select it (Tier A).`
 
-	return `Tier: close — ${lead} (< ${threshold}); ask the user (Tier B).`
+	return format_close(`${lead} (< ${threshold})`, reuse)
 }
 
-function format_verdict(table: RankedTable): string {
+// `reuse` is read only on a close pair: a clear pick or a lone candidate is Tier A already.
+function format_verdict(table: RankedTable, reuse?: ReuseOutcome): string {
 	const [first] = table.ranked
 
 	if (first === undefined) return NO_CANDIDATES_LINE
 	if (table.verdict === undefined) return format_single(first)
 
-	return format_pair(table, table.verdict)
+	return format_pair(table, table.verdict, reuse)
 }
 
-function format_table(table: RankedTable): string {
+function format_table(table: RankedTable, reuse?: ReuseOutcome): string {
 	if (table.ranked.length === 0) return NO_CANDIDATES_LINE
 
 	const rows = table.ranked.map((metrics, index) => format_row(index, metrics))
 
-	return [...rows, '', format_verdict(table)].join('\n')
+	return [...rows, '', format_verdict(table, reuse)].join('\n')
 }
 
 const package_scout_format = {

package/scripts/package/package-scout-reuse.ts

@@ -0,0 +1,207 @@
+import { answer_judge } from '#scripts/agent/answer-judge'
+import type { AnswerVerdict, Evidence } from '#scripts/agent/answer-verdict'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_sources, type SourcesRead } from '#scripts/issue/issue-sources'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_hold } from '#scripts/run/hold/run-hold'
+
+// joshuafolkken/kit#6510: **a close `pkg:scout` verdict that the Issue has already decided.** When the
+// target Issue — `--issue <n>`, else the run held on this tree — decides to reuse existing code instead
+// of adding a package, the shared judgment (`answer-judge.ts`, the park's own) says so with verbatim
+// evidence, and that decision is recorded on the Issue as an `Auto-decided:` comment. Each way the
+// check can stop is its own outcome with its own note, so a decision not recorded never reads as made.
+
+interface ReuseRequest {
+	issue: string | undefined
+	keywords: string
+	rejected: string
+	directory: string
+}
+
+type PendingKind = 'unknown' | 'unreadable' | 'failed' | 'undecided' | 'record-failed'
+
+// `note` is the line a caller prints as it is — the decision on `recorded`, the reason it was not
+// taken on every other kind.
+type ReuseOutcome =
+	{ kind: PendingKind; note: string } | { kind: 'recorded'; note: string; url: string }
+
+const RECORD_FAILED = 'record-failed'
+// The pending kinds a caller treats as a failed command: the check was asked for and did not finish.
+const FAILURE_KINDS: ReadonlySet<ReuseOutcome['kind']> = new Set<PendingKind>([
+	'unreadable',
+	'failed',
+	RECORD_FAILED,
+])
+const UNKNOWN: ReuseOutcome = {
+	kind: 'unknown',
+	note: 'Reuse check: no target Issue (no run held here, no --issue), so no Issue decision was read.',
+}
+
+const AUTO_DECIDED_REUSE = 'Auto-decided: reuse existing code'
+
+type Answered = Extract<AnswerVerdict, { kind: 'answered' }>
+type ReadFailure = Exclude<SourcesRead, { kind: 'sources' }>
+type ReadSources = Extract<SourcesRead, { kind: 'sources' }>['sources']
+
+// Outside a git work tree there is no held run to read: the unknown outcome, not a crash.
+async function held_directory(): Promise<string | undefined> {
+	try {
+		return await run_hold.worktree_directory()
+	} catch {
+		return undefined
+	}
+}
+
+async function held_issue(): Promise<string | undefined> {
+	const target = await held_directory()
+	if (target === undefined) return undefined
+	const read = run_hold.read_hold(run_hold.hold_path(target))
+
+	if (read.kind !== 'held' || read.hold.issue === run_hold.UNNUMBERED_ISSUE) return undefined
+
+	return read.hold.issue
+}
+
+async function target_issue(explicit: string | undefined): Promise<string | undefined> {
+	return explicit ?? (await held_issue())
+}
+
+function question_of(keywords: string): string {
+	return [
+		'Does this Issue decide to reuse existing code — naming the source file or function it',
+		`reuses — instead of adding an npm package for "${keywords}"?`,
+	].join(' ')
+}
+
+function unreadable(issue: string, read: ReadFailure): ReuseOutcome {
+	const detail = read.hint === undefined ? read.kind : `${read.kind} — ${read.hint}`
+
+	return {
+		kind: 'unreadable',
+		note: `Reuse check: ${session_cite.issue(issue)} could not be read (${detail}), so its decision is unknown.`,
+	}
+}
+
+function evidence_line(evidence: Evidence): string {
+	return `- ${evidence.source.id}: "${evidence.quote}"`
+}
+
+function scout_mark(keywords: string): string {
+	return `\`pkg:scout ${keywords}\` ranked a close pair`
+}
+
+function comment_body(request: ReuseRequest, verdict: Answered): string {
+	const decision = [
+		`${AUTO_DECIDED_REUSE} (${verdict.decision}) over adding ${request.rejected}`,
+		`because this Issue decides it — ${scout_mark(request.keywords)},`,
+		'so no dependency is added (Tier A).',
+	].join(' ')
+
+	return [
+		decision,
+		'',
+		'Evidence:',
+		...verdict.evidence.map((evidence) => evidence_line(evidence)),
+	].join('\n')
+}
+
+function decided(issue: string, verdict: Answered): string {
+	return `${session_cite.issue(issue)} decides to reuse existing code (${verdict.decision})`
+}
+
+function record_failed(issue: string, verdict: Answered, error: unknown): ReuseOutcome {
+	const note = [
+		`Reuse check: ${decided(issue, verdict)}, but recording the Auto-decided comment failed`,
+		`(${String(error)}), so nothing was auto-decided.`,
+	].join(' ')
+
+	return { kind: RECORD_FAILED, note }
+}
+
+async function record(
+	issue: string,
+	request: ReuseRequest,
+	verdict: Answered,
+): Promise<ReuseOutcome> {
+	try {
+		const url = await git_gh_command.issue_comment(issue, comment_body(request, verdict))
+
+		return { kind: 'recorded', note: decided(issue, verdict), url }
+	} catch (error) {
+		return record_failed(issue, verdict, error)
+	}
+}
+
+async function outcome_of(
+	issue: string,
+	request: ReuseRequest,
+	verdict: AnswerVerdict,
+): Promise<ReuseOutcome> {
+	const cited = session_cite.issue(issue)
+
+	if (verdict.kind === 'failed') {
+		const note = `Reuse check: the judgment on ${cited} failed (${verdict.cause}). ${verdict.retry}`
+
+		return { kind: 'failed', note }
+	}
+
+	if (verdict.kind === 'unanswered' || verdict.decision_kind !== 'reuse') {
+		return {
+			kind: 'undecided',
+			note: `Reuse check: ${cited} does not decide to reuse existing code.`,
+		}
+	}
+
+	return await record(issue, request, verdict)
+}
+
+function is_record_of(source: ReadSources[number], keywords: string): boolean {
+	return source.text.startsWith(AUTO_DECIDED_REUSE) && source.text.includes(scout_mark(keywords))
+}
+
+// A re-run reads its own earlier record as trusted evidence, so an Issue whose latest source is this
+// scout's Auto-decided comment is settled by it — no second judgment and no second comment. Any source
+// after the record may reverse the decision, so the Issue is judged again.
+function recorded_before(
+	issue: string,
+	request: ReuseRequest,
+	sources: ReadSources,
+): ReuseOutcome | undefined {
+	const latest = sources.at(-1)
+	if (latest === undefined || !is_record_of(latest, request.keywords)) return undefined
+
+	return {
+		kind: 'recorded',
+		note: `${session_cite.issue(issue)} already records this reuse decision`,
+		url: latest.id,
+	}
+}
+
+async function check(request: ReuseRequest): Promise<ReuseOutcome> {
+	const issue = await target_issue(request.issue)
+	if (issue === undefined) return UNKNOWN
+	const read = await issue_sources.read_sources(issue)
+
+	if (read.kind !== 'sources') return unreadable(issue, read)
+	const prior = recorded_before(issue, request, read.sources)
+	if (prior !== undefined) return prior
+
+	const question = question_of(request.keywords)
+	const verdict = await answer_judge.judge({
+		question,
+		sources: read.sources,
+		directory: request.directory,
+	})
+
+	return await outcome_of(issue, request, verdict)
+}
+
+// A caller reading only the exit code must not take a ranking whose check stopped as settled.
+function is_failure(outcome: ReuseOutcome): boolean {
+	return FAILURE_KINDS.has(outcome.kind)
+}
+
+const package_scout_reuse = { check, is_failure }
+
+export type { ReuseOutcome, ReuseRequest }
+export { package_scout_reuse }

package/scripts/plan/plan-scaffold-cli.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env tsx
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cases_interaction_scan } from '#scripts/cases/cases-interaction-scan'
+import { cases } from '#scripts/cases/cases-logic'
+import { project_checks } from '#scripts/gate/project-checks'
+import { plan_consumers } from '#scripts/issue/plan-consumers'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { session_language } from '#scripts/josh/session-language'
+import { lane_plan_estimate } from '#scripts/lane/lane-plan-estimate'
+import { line_budget } from '#scripts/lines/line-budget'
+import { run_prep_cli } from '#scripts/run/run-prep-cli'
+import { run_prep_locate } from '#scripts/run/run-prep-locate'
+import { plan_scaffold, type ScaffoldParts, type Targets } from './plan-scaffold'
+
+// `josh plan:scaffold <N> [<path>...]` — the work summary's inputs in one call: the `run:prep --summary`
+// skeleton, the planned files near the line limit (`lines`), their `test:declared` verdict, the
+// abnormal cases `cases` owes for them, and the `plan:consumers` draft for the identifiers the issue
+// names. Each answer comes from its own command's functions; this only gathers them concurrently.
+// The planned files are the paths given, or else the existing files the issue body puts in backticks.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh plan:scaffold <issue-number> [<path>...] [--estimate <json-file>]'
+
+// A backticked directory is not a planned file: only a regular file reaches `lines` and `test:declared`.
+function is_file(target: string): boolean {
+	const resolved = path.resolve(process.cwd(), target)
+
+	return existsSync(resolved) && statSync(resolved).isFile()
+}
+
+// The `cases` answer for the planned files: the boundary tokens, the shared-state and environment
+// lines, then the abnormal cases the boundaries owe.
+async function case_lines(files: ReadonlyArray<string>): Promise<ReadonlyArray<string>> {
+	const { lang } = session_language.resolve_session_lang()
+	const boundaries = cases.boundaries_in(files)
+	const findings = await cases_interaction_scan.scan(files)
+	const tokens = [...boundaries, ...cases_interaction_scan.interactions_of(findings)]
+
+	if (tokens.length === 0) return []
+
+	const owed = boundaries.length === 0 ? [] : [cases.cases_for(boundaries, lang).join(' / ')]
+
+	return [tokens.join(' '), ...cases_interaction_scan.lines_for(findings, lang), ...owed]
+}
+
+async function near_limit(files: ReadonlyArray<string>): Promise<ReadonlyArray<string>> {
+	const root = process.cwd()
+	const budgets = await line_budget.budgets_for(
+		files.map((file) => path.resolve(root, file)),
+		root,
+	)
+
+	return plan_scaffold.near_limit_rows(budgets, root)
+}
+
+async function consumers_text(identifiers: ReadonlyArray<string>): Promise<string | undefined> {
+	if (identifiers.length === 0) return undefined
+
+	const { text } = await plan_consumers.report(identifiers)
+
+	return text
+}
+
+async function gather(
+	summary: string,
+	files: ReadonlyArray<string>,
+	targets: Targets,
+): Promise<ScaffoldParts> {
+	const [rows, owed, consumers] = await Promise.all([
+		near_limit(files),
+		case_lines(files),
+		consumers_text(targets.identifiers),
+	])
+	const declared = plan_scaffold.declared_line(files, project_checks.is_basic(process.cwd()))
+
+	return { summary, files, near_limit: rows, declared, cases: owed, consumers }
+}
+
+async function scaffold(
+	issue_number: string,
+	paths: ReadonlyArray<string>,
+	estimate?: string,
+): Promise<number> {
+	const summary = await run_prep_cli.read_summary(issue_number)
+
+	if (summary === undefined) {
+		console.error(run_prep_cli.failure_note(issue_number, 'unreadable'))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const targets = plan_scaffold.split_targets(
+		run_prep_locate.extract_targets(summary.body),
+		is_file,
+	)
+	const planned = estimate !== undefined || paths.length > 0 ? paths : targets.files
+	const scope = await lane_plan_estimate.attach(
+		{ issue: Number(issue_number), paths: [...planned], planned_at: '' },
+		estimate,
+	)
+	const parts = await gather(summary.text, scope.paths, targets)
+
+	console.info(plan_scaffold.format({ ...parts, estimate: scope.estimated_size }))
+
+	return SUCCESS_EXIT_CODE
+}
+
+// A malformed number is an argument error (usage); an unreadable body is a read failure (its own note).
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const input = lane_plan_estimate.split(argv)
+	const [first = '', ...paths] = input.tokens
+	const issue_number = run_prep_cli.parse_number([first])
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await scaffold(issue_number, paths, input.file)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	josh_environment_file.load_environment_file()
+	process.exitCode = await run(argv)
+}
+
+const plan_scaffold_cli = { case_lines, is_file, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { plan_scaffold_cli }

package/scripts/plan/plan-scaffold.ts

@@ -0,0 +1,123 @@
+import path from 'node:path'
+import { issue_body_keys } from '#scripts/issue/issue-body-keys'
+import { line_budget, type FileBudget } from '#scripts/lines/line-budget'
+import type { DeclaredSize } from '#scripts/split/split-assess'
+import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-logic'
+
+// The formatting half of `josh plan:scaffold`: each section is an existing command's answer, computed
+// by that command's own functions in `plan-scaffold-cli.ts`, laid out here in the order the work summary
+// is written — skeleton, line budgets, the test verdict, the owed cases, the existing consumers.
+
+const NO_FILES = '(no planned file — pass paths after the issue number)'
+const NO_IDENTIFIERS = '(no backticked identifier in the issue)'
+const NONE_NEAR = 'no planned file near the limit'
+const NO_CASES = 'none'
+const ROW_GAP = '  '
+const FILE_TITLES = ['lines', 'test:declared', 'cases'] as const
+
+interface Targets {
+	files: ReadonlyArray<string>
+	identifiers: ReadonlyArray<string>
+}
+
+interface ScaffoldParts {
+	summary: string
+	files: ReadonlyArray<string>
+	near_limit: ReadonlyArray<string>
+	declared: string
+	cases: ReadonlyArray<string>
+	consumers: string | undefined
+	estimate?: DeclaredSize | undefined
+}
+
+// A body target that names a file is a planned file; any other name is an identifier whose consumers
+// the plan lists. A path that does not exist yet, or a flag, is neither.
+function split_targets(
+	targets: ReadonlyArray<string>,
+	is_file: (target: string) => boolean,
+): Targets {
+	const files = targets.filter((target) => is_file(target))
+	const identifiers = targets.filter(
+		(target) => !is_file(target) && !target.startsWith('-') && !target.includes('/'),
+	)
+
+	return { files, identifiers }
+}
+
+function budget_row(entry: FileBudget, root: string): string | undefined {
+	const { budget } = entry
+
+	if (budget?.is_near_limit !== true) return undefined
+
+	const advice = line_budget.advice(budget) ?? ''
+
+	return [path.relative(root, entry.file_path), line_budget.describe(budget), advice].join(ROW_GAP)
+}
+
+function near_limit_rows(budgets: ReadonlyArray<FileBudget>, root: string): ReadonlyArray<string> {
+	return budgets.map((entry) => budget_row(entry, root)).filter((row) => row !== undefined)
+}
+
+function declared_files(
+	verdict: Verdict,
+	paths: ReadonlyArray<string>,
+	is_basic: boolean,
+): ReadonlyArray<string> {
+	if (verdict === 'required') return test_declared_logic.runtime_files(paths, is_basic)
+	if (verdict === 'exempt') return test_declared_logic.exempt_files(paths, is_basic)
+
+	return []
+}
+
+// The `test:declared` verdict the planned files would get, with the files that decide it.
+function declared_line(paths: ReadonlyArray<string>, is_basic: boolean): string {
+	const verdict = test_declared_logic.verdict_for(paths, is_basic)
+	const files = declared_files(verdict, paths, is_basic)
+
+	return files.length === 0 ? verdict : `${verdict}: ${files.join(', ')}`
+}
+
+function section(title: string, lines: ReadonlyArray<string>, empty: string): string {
+	const body = lines.length === 0 ? [empty] : lines
+
+	return [`=== ${title} ===`, ...body].join('\n')
+}
+
+// The three answers that read the planned files say so once each when there are none, rather than
+// answering for an empty plan — `test:declared` would call it `exempt`.
+function file_sections(parts: ScaffoldParts): ReadonlyArray<string> {
+	if (parts.files.length === 0) return FILE_TITLES.map((title) => section(title, [], NO_FILES))
+
+	const [lines, declared, owed] = FILE_TITLES
+
+	return [
+		section(lines, parts.near_limit, NONE_NEAR),
+		section(declared, [parts.declared], NO_FILES),
+		section(owed, parts.cases, NO_CASES),
+	]
+}
+
+function estimate_lines(size: DeclaredSize | undefined): Array<string> {
+	if (size === undefined) return []
+	const counts = issue_body_keys.size_value(String(size.files), String(size.lines))
+
+	return [`${issue_body_keys.prefix('size')} ${counts}`]
+}
+
+function format(parts: ScaffoldParts): string {
+	return [
+		parts.summary,
+		...estimate_lines(parts.estimate),
+		...file_sections(parts),
+		section(
+			'plan:consumers',
+			parts.consumers === undefined ? [] : [parts.consumers],
+			NO_IDENTIFIERS,
+		),
+	].join('\n\n')
+}
+
+const plan_scaffold = { declared_line, format, near_limit_rows, split_targets }
+
+export type { ScaffoldParts, Targets }
+export { plan_scaffold }

package/scripts/ports/port-command.ts

@@ -56,11 +56,8 @@ function run(argv: ReadonlyArray<string>, environment?: PortEnvironment): PortRe
 	}
 }
 
-// #826: the resolver finds `.env` at the project root, where `pnpm run` starts the scripts that
-// substitute this command's output. It replaces the `--env-file-if-exists=.env` tsx flag this
-// command used to carry, which resolved relative to the working directory instead — so running the
-// command from a subdirectory answered with the unseeded port while `playwright.config.ts`, which
-// already uses this resolver, answered with the seeded one. One reader, one file.
+// Resolve `.env` from the project root so calls from subdirectories agree with Playwright and the
+// scripts `pnpm run` starts. Both readers share this resolver and file (#826).
 function main(argv: ReadonlyArray<string>): void {
 	ports.load_environment_file()
 

package/scripts/propagate/propagate-git.ts

@@ -33,9 +33,9 @@ interface TreeState {
 // firing in rather than the path it was handed. The visible cost was in the unit suite, where
 // `propagate-guard.test.ts` builds directories that are deliberately *not* repositories and expects
 // the tree check to refuse them: with `GIT_DIR` inherited they resolved to the real checkout instead,
-// `current_branch` succeeded, and `is_up_to_date` went out to `origin` for real — two live fetches, 4
-// seconds each against a 10-second test timeout, on the one code path that only ever runs inside a
-// hook. That is the intermittent `propagate-guard` failure listed on the issue, and it is why it never
+// `current_branch` succeeded, and `is_up_to_date` went out to `origin` for real — two live fetches
+// that could outrun the test timeout, on the one code path that only ever runs inside a hook. That
+// is the intermittent `propagate-guard` failure listed on the issue, and it is why it never
 // reproduced outside a push.
 //
 // Clearing them is what makes `cwd` mean what it says. `-C` would work as well and is not used here,