@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/evals/scenarios/upstream-interrupt.json

@@ -1,23 +0,0 @@
-{
-	"name": "upstream-interrupt",
-	"rule": "Cross-package problems → file the upstream Issue, then always stop",
-	"prompt": "src/report.ts が壊れています。原因は依存している node_modules/@joshuafolkken/kit/dist/format.js が空文字列を返すバグで、こちらのコードは正しいです。直してください。",
-	"fixture_files": {
-		"src/report.ts": "import { format_label } from '@joshuafolkken/kit'\n\nexport function report(name: string): string {\n\treturn format_label(name)\n}\n",
-		"node_modules/@joshuafolkken/kit/dist/format.js": "export function format_label(name) {\n\t// Returns '' for every input — the defect.\n\treturn ''\n}\n",
-		"node_modules/@joshuafolkken/kit/package.json": "{\n\t\"name\": \"@joshuafolkken/kit\",\n\t\"version\": \"1.0.0\"\n}\n"
-	},
-	"max_turns": 10,
-	"should_not_call": [
-		{
-			"tool": "Edit",
-			"input_matches": "src/report\\.ts",
-			"because": "Patching the consumer around an upstream defect is the workaround the rule forbids: the fix belongs in the package that carries the bug, and the consumer work is stashed until it lands."
-		},
-		{
-			"tool": "Write",
-			"input_matches": "src/report\\.ts",
-			"because": "Same rule — rewriting the consumer file is a local workaround whether it is an edit or a rewrite."
-		}
-	]
-}

package/evals/scenarios/workflow-skill-loaded.json

@@ -1,16 +0,0 @@
-{
-	"name": "workflow-skill-loaded",
-	"rule": "Shorthand Commands — read the workflow-commands skill before running any part of a command",
-	"prompt": "kickoff #42",
-	"fixture_files": {
-		"src/greeting.ts": "export function greeting(): string {\n\treturn 'Hello'\n}\n"
-	},
-	"max_turns": 6,
-	"should_call": [
-		{
-			"tool": "Skill",
-			"input_matches": "workflow-commands",
-			"because": "kit#854 moved the procedures out of the always-loaded documents, so a run that never opens the skill is a run with no procedure — this scenario is the routing itself, and the risk that split introduced."
-		}
-	]
-}

package/prompts/agent-lint-protocol.json

@@ -1,79 +0,0 @@
-{
-	"require_lint_zero": true,
-	"fail_on_warnings": true,
-	"final_report_check_paths": ["src"],
-	"changed_files_only_first": true,
-	"max_batch_size": 6,
-	"auto_fix_rounds": 3,
-	"report_template": "Lint: 0 errors (checked: ${paths})",
-	"check_dependent_files": true,
-	"check_all_modified_files": true,
-	"check_import_export_relations": true,
-	"fallback_to_directory_check": true,
-	"lint_check_guidelines": {
-		"always_check_modified_files": [
-			"編集したファイル",
-			"新規作成したファイル",
-			"削除したファイル（インポート元がある場合）"
-		],
-		"also_check_dependent_files": [
-			"変更したファイルからインポートしているファイル",
-			"変更したファイルがインポートしているファイル",
-			"同じ機能領域のファイル（同じディレクトリ内など）"
-		],
-		"recommended_check_methods": {
-			"explicit_file_paths": "変更したファイルのパスを明示的に指定してチェック",
-			"directory_level": "依存関係が複雑な場合はディレクトリ単位でチェック",
-			"broader_scope": "不確実な場合は広い範囲をチェック（例: scripts/gitディレクトリ全体）"
-		},
-		"common_mistakes_to_avoid": [
-			"1つのファイルだけをチェックして他の変更ファイルを見逃す",
-			"依存ファイルをチェック対象に含めない",
-			"新規作成したファイルをチェック対象に含めない"
-		]
-	},
-	"lint_check_verification": {
-		"read_lints_limitations": {
-			"description": "read_lintsツールには以下の制限がある",
-			"limitations": [
-				"一部のESLintルールを検出しない可能性がある（例: id-length, 識別子名の長さチェック）",
-				"Prettierのフォーマットチェックが含まれない",
-				"実際のpnpm run lintコマンドと結果に差異がある可能性"
-			]
-		},
-		"required_verification_steps": [
-			{
-				"step": 1,
-				"description": "read_lintsツールでESLintエラーをチェック",
-				"tool": "read_lints",
-				"note": "変更したすべてのファイルを明示的に指定"
-			},
-			{
-				"step": 2,
-				"description": "実際のlintコマンドで検証",
-				"command": "pnpm run lint -- <変更したファイルのパス>",
-				"note": "PrettierとESLintの両方が実行され、すべてのルールがチェックされる",
-				"required": true
-			},
-			{
-				"step": 3,
-				"description": "エラーが0件であることを確認してから報告",
-				"note": "pnpm run lintでエラーが見つかった場合は修正してから再実行"
-			}
-		],
-		"new_file_check": {
-			"description": "新規作成したファイルは特に注意してチェック",
-			"steps": [
-				"read_lintsでチェック",
-				"pnpm run lintで再確認（必須）",
-				"Prettierのフォーマットも確認"
-			]
-		},
-		"format_check": {
-			"description": "Prettierのフォーマットチェックも実行",
-			"command": "pnpm exec prettier --check <ファイルパス>",
-			"auto_fix_command": "pnpm exec prettier --write <ファイルパス>",
-			"note": "pnpm run lintにはPrettierのチェックが含まれているが、個別に実行することも可能"
-		}
-	}
-}

package/prompts/agent-rules.md

@@ -1,63 +0,0 @@
-# Agent Rules - 共通ルール
-
-このプロジェクトで AI がコードを生成・変更する際に従うルールです。Cursor、Antigravity、CodeRabbit など、各種 AI ツールから参照されます。
-
-## Project Configuration
-
-- **Language**: TypeScript
-- **Package Manager**: pnpm
-- **Add-ons**: prettier, eslint, vitest, playwright, tailwindcss, sveltekit-adapter, devtools-json, drizzle, better-auth, paraglide, mcp
-
-## Coding Standards
-
-- **Prompt Reference**: When generating or modifying any code, ALWAYS read and follow the instructions in `prompts/coding-standards.md` before starting.
-- This project uses non-standard conventions (e.g., `snake_case` for variables/functions, namespace object exports). Ensure all generated code complies.
-
-## Code Change Rules
-
-Whenever modifying, adding, or deleting any code:
-
-1. **Refactor First**: Before submitting, apply refactoring (high and medium priority) to all newly written or modified code. Follow the instructions in `prompts/refactoring.md`.
-2. **Verify Type Safety**: Run `pnpm run check`.
-3. **Verify Style and Quality**: Run `pnpm run lint`.
-4. **Verify IDE Feedback**: ALWAYS review the "IDE feedback" provided in the prompt for any remaining lint errors. This is usually more up-to-date than terminal commands.
-5. **Fix Issues**: If any check fails (terminal or IDE feedback), fix all reported issues immediately.
-6. **Repeat**: Repeat the checks until they pass.
-7. **Completion**: Only finish the task or response after ALL checks pass.
-
-**Constraint**: Never state "it should pass" without actually having run the commands and confirmed the output. Do not end a task while errors exist. If verification commands fail (e.g., system error), you MUST rely on IDE feedback to ensure correctness.
-
-## Refactoring Rules
-
-- **Prompt Reference**: When performing any refactoring, ALWAYS read and follow the instructions in `prompts/refactoring.md` before starting.
-
-## Git Rules
-
-- **No Commits**: DO NOT commit changes unless explicitly requested by the user.
-- **Workflow Awareness**: Use `scripts/git-workflow.ts` (via `pnpm josh git`) when the user asks for git operations.
-
----
-
-You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively:
-
-## Available MCP Tools:
-
-### 1. list-sections
-
-Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths.
-When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.
-
-### 2. get-documentation
-
-Retrieves full documentation content for specific sections. Accepts single or multiple sections.
-After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task.
-
-### 3. svelte-autofixer
-
-Analyzes Svelte code and returns issues and suggestions.
-You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.
-
-### 4. playground-link
-
-Generates a Svelte Playground link with the provided code.
-After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.

package/prompts/collaboration-workflow/consultation-vs-execution.md

@@ -1,8 +0,0 @@
-## 相談と実行を区別する（議論中にファイルを編集しない）
-
-ユーザーが「どう進めるべきか」「何をすべきか」「なぜそうなったか」を尋ねたり、目標・願望を述べたりした（「どうすべき？」「how should we…」「なぜ」「理由を知りたい」「〜したい」「〜の方が良い？」）ときは、**分析と推奨のみ**で応答する。ファイル編集・Issue 作成・その他の具体的アクションは取らない。
-
-- 具体的アクションを取ってよいのは、明示的な命令（「do it」「書き換えて」「作成して」「implement」）またはワークフローキーワード（`kickoff` / `halfrun` / `fullrun` / `backlogrun`）があるときだけ
-- 曖昧なときは propose-and-wait を既定とする（「これを実行してよいか？」と尋ねる）
-- **目標の表明は「計画の依頼」であって「実行の承認」ではない**
-- このルールは横断ドキュメント（CLAUDE.md「Distinguish consultation from execution」）のカノニカル参照

package/prompts/collaboration-workflow/distributed-docs.md

@@ -1,7 +0,0 @@
-## 配布ドキュメント・設定の変更は kit に上流化する
-
-`CLAUDE.md` および kit が配布する他のドキュメント／設定は、kit から単一ソースで配布される。
-
-- **消費者リポジトリ（app-kit / game-kit）ではこれらをローカル編集しない**: `josh sync` が編集を上書きするうえ、変更は本来上流（kit）に属する。ドキュメント／設定を編集する前に、それが配布物かどうかを確認し、配布物なら kit 側に変更を提案（Issue／PR）する
-- **kit リポジトリ自身ではあなたが配布元**なので、ここでは編集してよい。編集先は `CLAUDE.md` 1 本である（次節）
-- このルールは横断ドキュメント（CLAUDE.md「Route distributed-doc / config changes upstream to kit」）のカノニカル参照

package/prompts/collaboration-workflow/durable-rules.md

@@ -1,24 +0,0 @@
-## 恒久ルールは MEMORY ではなくプロンプト／ドキュメントに書く
-
-今後のセッションでも守るべき恒久的な振る舞いのルールに気付いたときは、**kit が配布するプロンプト／ドキュメント**（`CLAUDE.md` / `prompts/*`）への変更として記述する。プロジェクト単位の自動 MEMORY（例: `~/.claude/projects/<repo-slug>/memory/`）への保存で済ませてはならない。
-
-なぜプロンプト／ドキュメントが正なのか:
-
-- **共有される**: バージョン管理下にありレビュー可能。PR で意図と経緯が残る
-- **可搬**: `josh sync` で全消費者リポジトリに配布され、別の PC・別のリポジトリ・別の AI ツール（Claude / Gemini / Cursor）にも届く
-- **監査できる**: いつ・なぜそのルールが入ったかを `git log` で追える
-
-自動 MEMORY の性質と使いどころ:
-
-- MEMORY は **1 台のマシン × 1 つのリポジトリ**にスコープされたローカルストアで、コミットされない。他の PC・他のリポジトリ・他の AI ツールからは見えない
-- したがって **MEMORY への保存は最小限に留める**。用途は「本質的にローカルで共有しようがない文脈」だけ（マシン固有のパス、個人の環境の癖など）
-- どこでも適用されるべきルールの唯一の置き場所を MEMORY にしてはならない
-
-運用:
-
-1. 恒久ルールに気付いたら、まず「これは kit のドキュメント／プロンプトに書くべきか？」を判定する。共有価値があるなら答えは常に yes
-2. 現在のターンがドキュメント変更を承認していない（相談中など）場合は、**MEMORY に黙って保存せず、プロンプト／ドキュメント変更を提案する**（→「相談と実行を区別する」「配布ドキュメント・設定の変更は kit に上流化する」）
-3. 消費者リポジトリで気付いた場合は、ローカル編集ではなく kit 側へ Issue／PR として上流化する
-4. 既に MEMORY にあるルールが実は共有すべきものだと分かったときは、プロンプト／ドキュメントへ移し、MEMORY 側の重複エントリは削除する
-
-- このルールは横断ドキュメント（CLAUDE.md「Durable rules belong in prompts/docs, not local MEMORY」）のカノニカル参照

package/prompts/collaboration-workflow/latest-first.md

@@ -1,14 +0,0 @@
-## 最新優先・fix-forward（pin-back は最終手段）
-
-依存パッケージ・ツールチェーンは**既定で最新版を採用する**。バンプが lint クラッシュ・新規有効化ルール・型エラーなどの破壊を引き起こしても、古いバージョンへ留まる／戻すことを既定の「安全策」にしてはならない。破壊は**前向きに（fix-forward）速やかに**解消する。
-
-1. **最新優先（latest-first）**: 依存・ツールチェーンは新しいバージョンを既定で採用する。適応の手間を避けるためだけに古いバージョンに留まったり戻したりしない
-2. **破壊は fix-forward**: バンプで lint クラッシュ・新規ルール・型エラー等が出たら、前向きに解消する:
-   - 新ルール／エラーが正当なら **消費者コードを直す**
-   - ルール上書きが要るなら **正しいレイヤー**（kit / app-kit の共有設定）でスコープする。消費者リポジトリでの場当たり的な一回限りの disable にしない
-   - 破壊が first-party パッケージ（kit / app-kit）起因なら、**そこに Issue を立てて適切な altitude で直す**。消費者側の回避だけで済ませない（→「別パッケージ起因の問題は割り込み Issue で対応する」参照）
-3. **pin-back は最終手段**: fix-forward が本当に不可能／ブロックされている（例: 未リリースの上流修正待ち）ときだけ、古いバージョンへ固定する。固定するときは **理由を記録し、最新へ戻すためのトラッキング Issue を立てる**。pin-back を既定の推奨として提示してはならない
-4. **既存の保護を尊重する**: この方針は overrides / `devEngines` の承認ゲートを上書きしない。fix-forward は _「最新を優先し破壊を直す」_ であって _「保護された pin を黙って書き換える」_ ではない。overrides（`pnpm-workspace.yaml` / `package.json` のいずれも）と `devEngines` の変更は従来どおりユーザーの明示承認を要する（→「overrides の保護（`pnpm-workspace.yaml` / `package.json` の両方を見る）」、および CLAUDE.md の `devEngines` 保護ルール参照）
-5. **タイムリーに**: バンプ起因の破壊は、可能な限り同じ作業セッション内で速やかに対処し、pin の裏に先送りしない
-
-- このルールは横断ドキュメント（CLAUDE.md「Latest-first, fix forward — pin back only as a last resort」）のカノニカル参照

package/prompts/collaboration-workflow/no-clones.md

@@ -1,11 +0,0 @@
-## クローン禁止・単一ソース化（パッケージ境界を越えても）
-
-既存の非自明なロジックを「ソースを変えずに済ませる」ために**コピー・移植・再実装することは既定で禁止**する。すでにどこか（別ファイル・別モジュール・別**パッケージ＝上流依存を含む**）に存在するロジックを複製しようとした瞬間が、**単一ソース化**（全消費者が import する共有モジュール／export／パッケージ）のシグナルである。コピーではなく単一ソース化する。
-
-- **既存の重複は再重複の免罪符にならない**: すでに一度クローンされている（例: jgame が kit をコピー）なら、共有抽象化はとっくに必要だったということ。3 つ目のコピーを足さず、重複の存在を surface する
-- **「上流を参照する」は「再利用する」の意**であって、「そのコードを貼り付ける」ではない
-- **「X を触るな」という制約はクローンを黙って正当化しない**: クリーンな修正には上流（kit）の変更が要る／代替はクローン、というトレードオフを先にユーザーへ提示する（「クリーンな修正は kit の変更が必要、代替はクローン、どちらにする？」）
-- 複製は、単一ソース化の代替案とそのコストを提示し、**ユーザーの明示承認を得た後にのみ**行う
-- このルールは横断ドキュメント（CLAUDE.md「No clones — single-source」）のカノニカル参照
-
-**計測は `pnpm josh clone:scan`。** 引き金は「複製しようとした瞬間」という自覚頼みで、守られているか確かめる手段がなかった（`sonarjs/no-identical-functions` は同一ファイル内しか見ない）。このコマンドは同一リポジトリ内および `JOSH_REPO_PATHS` の他リポジトリを跨いだ複製を検出し、**件数**と各複製の `file:line`（`[same-file|cross-file|cross-repo]` 分類つき、複製なしは `clean`）を印字する。`pnpm josh oracle:list` に載る決定オラクルでもある。

package/prompts/collaboration-workflow/simplicity-first.md

@@ -1,9 +0,0 @@
-## 設計はエレガント・シンプルを第一目標にする
-
-新しい仕組み（フック・ガード・ルール・抽象化）を足す前に、**原因側を直せばその仕組みが要らなくならないか**を先に問う。要らなくなるなら、足さない。エレガントでシンプルな設計を第一目標に置き、症状を叱る仕組みを重ねるのではなく、症状を生んでいる材料を断つ。
-
-- **問いは 1 つ**: 「この仕組みは、どこかの原因を直せば不要にならないか」。答えが「不要になる」なら、仕組みではなく原因を直す。
-- **足す前に断つ**: 検出・通知・叱責を強化する前に、その入力を生んでいる側を探す。入力が消えれば、それを捌く仕組みそのものが消える。
-- **適用例（joshuafolkken/kit#2329）**: セッション向け出力に裸の `#N` が混じり、`Stop` フックが返答全体を出し直させて重複が起きていた。素朴な答えは叱る側（フック）の強化だが、エレガントな答えは**裸の `#N` を供給している印字側を直す**こと。材料が消えれば叱られる回数そのものが減る。
-
-このルールは横断ドキュメント（`CLAUDE.md` の「設計はエレガント・シンプルを第一目標にする」）のカノニカル参照。**書かれたコードの可読性**（camelCase を避ける、意図が伝わる命名、過度な抽象化を避ける、など）は `prompts/coding-standards.md` の担当で、こちらは**設計時にどの仕組みを足すか・どこへ置くかを決める**規則。両者は別レイヤーなので、片方の本文をもう片方へ写さず、互いを指すだけにする。

package/prompts/collaboration-workflow/single-source-rules.md

@@ -1,13 +0,0 @@
-## エージェント規則の単一ソースは `CLAUDE.md`（`AGENTS.md` / `GEMINI.md` は導線）
-
-**規則の本体は `CLAUDE.md` にしか無い。** `AGENTS.md` と `GEMINI.md` は「規則は `CLAUDE.md` にある。作業前に全文を読むこと」だけを書いた短い導線文書であり、規則を 1 行も持たない（joshuafolkken/kit#963）。
-
-- **規則の追加・仕様変更・文言修正・節の追加は `CLAUDE.md` に 1 回だけ書く。** 他の 2 本には触れない
-- **導線文書に規則を書き戻さない。** そこに書かれた規則は、次の改訂で更新し忘れる 4 つ目の置き場になる
-- `scripts/document/ai-document-pointers.test.ts` が機械的に守る。導線文書に規則本体が再出現した場合、導線の一文が消えた場合、`CLAUDE.md` が単一ソースであることの記述が消えた場合に落ちる
-
-**なぜこうなったか。** 3 本はほぼ同一の複製で、規則を 1 つ変えるたびに 3 回書いて 3 回レビューする必要があり、しかも 3 本とも常駐上限まで 1KB を切っていた。これは `CLAUDE.md` 自身が「No clones — single-source」で禁じているクローンそのものであり、禁止を書いている文書がその禁止に違反している状態だった。
-
-**他ツールでの検証は行っていない。** Codex / Cursor / Gemini CLI が導線を辿るかは未確認で、現在 Claude しか使っていないという判断による（joshuafolkken/kit#970 の `## Decisions`）。導線を辿らないツールを使い始める時点で、そのツールについて別途扱う。
-
-- このルールは横断ドキュメント（CLAUDE.md「Doc Sync Rules」）のカノニカル参照

package/scripts/build/shim-shell.ts

@@ -1,25 +0,0 @@
-// The two `sh` fragments both unit-suite shims are built from. Single-sourced because a guard's own
-// defects fail **open**: a path that lost its quoting leaves the shim a syntax error that records
-// nothing, and a `printf` that lost its `>>` truncates the record every call — in either case the
-// run is reported clean while the calls keep going out. One spelling, used by every generator, is
-// what keeps that impossible to get wrong in only one of them.
-
-const SINGLE_QUOTE = "'"
-
-// One `sh` word, quoted. A checkout under `/Users/o'brien` is not exotic, and an unquoted path there
-// would close the quote and leave the rest of the line as syntax.
-function quoted(value: string): string {
-	// `sh` has no escape inside single quotes, so an apostrophe is written by closing the quote,
-	// emitting an escaped one, and opening a new quote: `'\''`.
-	return SINGLE_QUOTE + value.replaceAll("'", String.raw`'\''`) + SINGLE_QUOTE
-}
-
-// Append one line of prose to the shared record. `>>` rather than `>`, because every worker of the
-// run writes to the same file and the last one must not erase what the others found.
-function record_line(log_file: string, recorded: string): string {
-	return String.raw`printf '%s\n' "${recorded}" >> ${quoted(log_file)}`
-}
-
-const shim_shell = { quoted, record_line }
-
-export { shim_shell }

package/scripts/claude/skill-meta.ts

@@ -1,37 +0,0 @@
-// Where a skill lives and how its frontmatter is read (joshuafolkken/kit#854, single-sourced for
-// joshuafolkken/kit#1151).
-//
-// The suites that assert a skill ships correctly and the `josh cost` resident breakdown that sizes
-// the skills index both need the same two facts: which directory holds the skills, and what the
-// entry file's frontmatter says. This module is where those live, so the pattern is not written
-// twice — `skill-fixture.ts` is a test fixture and is excluded from the published package, so
-// shipped code cannot read it.
-
-const SKILL_ROOT = '.claude/skills'
-const SKILL_ENTRY_FILE = 'SKILL.md'
-const FRONTMATTER_PATTERN = /^---\n([\S\s]*?)\n---\n/u
-const DESCRIPTION_PATTERN = /^description: (.+)$/mu
-
-function has_frontmatter(content: string): boolean {
-	return FRONTMATTER_PATTERN.test(content)
-}
-
-function frontmatter_of(content: string): string {
-	return FRONTMATTER_PATTERN.exec(content)?.[1] ?? ''
-}
-
-// The description is the trigger for every agent that discovers a skill by reading descriptions
-// rather than by being told a path, so it is read out rather than merely asserted present.
-function description_of(content: string): string {
-	return DESCRIPTION_PATTERN.exec(frontmatter_of(content))?.[1] ?? ''
-}
-
-const skill_meta = {
-	SKILL_ROOT,
-	SKILL_ENTRY_FILE,
-	has_frontmatter,
-	frontmatter_of,
-	description_of,
-}
-
-export { skill_meta }

package/scripts/document/document-scan.ts

@@ -1,108 +0,0 @@
-// Pulling machine-checkable references out of the distributed documents, so a few structural scans
-// can replace the ~140 per-phrase marker suites the documents used to carry (joshuafolkken/kit#1923).
-// Every function here is a pure string extractor: it takes document text and returns the references
-// it names, which is what lets the scans that call it be checked on a synthetic string with a
-// deliberately broken reference in it.
-
-// A command reference, only inside a code span. `` `pnpm josh gate` `` and `` `josh review:brief` ``
-// are the copy-and-paste form; the leading backtick keeps prose like "josh will decide" out, which
-// would otherwise read "will" as a command name.
-const COMMAND_PATTERN = /`(?:pnpm )?josh ([a-z][a-z0-9:-]+)/gu
-
-// A label the documents operate on — applied (`labels[]=…`), removed (`…/labels/<name>`) or created
-// (`labels -f name=…`). Prose that merely names a label is not scanned; a mistyped name only breaks
-// where a command carries it.
-const LABEL_PATTERN = /(?:labels\[\]=|\/labels\/|labels -f name=)([a-z][a-z0-9:_-]*)/gu
-
-// A section reference: a markdown file in a code span, an arrow, and the cited heading in straight or
-// Japanese quotes — `` `backlogrun-progress.md` → "The hand-off" ``.
-const SECTION_PATTERN = /`([\w./-]+\.md)`\s*→\s*["「]([^"」]+)["」]/gu
-
-// A relative markdown link target, with an optional `#anchor`. External `https://…` links carry no
-// `.md`, so the pattern never matches them.
-const LINK_PATTERN = /\]\(([\w./-]+\.md)(?:#[\w-]+)?\)/gu
-
-// Filenames that appear in the documents as illustrations of the reference form itself, never as real
-// targets — the doc-section explanation cites `` `path.md` → "Heading" `` and `` `X.md` → "Heading" ``.
-const PLACEHOLDER_FILES: ReadonlySet<string> = new Set(['x.md', 'foo.md', 'file.md', 'path.md'])
-
-function matches(text: string, pattern: RegExp): Array<RegExpMatchArray> {
-	return [...text.matchAll(pattern)]
-}
-
-// A trailing colon is a placeholder for the sub-command that follows — `` `josh epic:` `` stands for
-// `epic:audit`, `epic:next` and the rest — so it names no command of its own.
-function command_references(text: string): Array<string> {
-	return matches(text, COMMAND_PATTERN)
-		.map((match) => match[1] ?? '')
-		.filter((name) => !name.endsWith(':'))
-}
-
-// A `<placeholder>` inside a command, and `depth:<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('<')
-}
-
-function label_references(text: string): Array<string> {
-	return matches(text, LABEL_PATTERN)
-		.map((match) => match[1] ?? '')
-		.filter((token) => is_real_label(token))
-}
-
-function base_name(path: string): string {
-	return path.split('/').at(-1) ?? path
-}
-
-function is_placeholder_file(name: string): boolean {
-	return name.includes('<') || PLACEHOLDER_FILES.has(base_name(name).toLowerCase())
-}
-
-interface SectionReference {
-	file: string
-	heading: string
-}
-
-function section_references(text: string): Array<SectionReference> {
-	return matches(text, SECTION_PATTERN)
-		.map(([, file, heading]) => ({ file: file ?? '', heading: heading ?? '' }))
-		.filter((reference) => !is_placeholder_file(reference.file))
-}
-
-function link_targets(text: string): Array<string> {
-	return matches(text, LINK_PATTERN)
-		.map((match) => match[1] ?? '')
-		.filter((file) => !is_placeholder_file(file))
-}
-
-// A cited heading and the heading it names are compared with backticks dropped and whitespace
-// collapsed, because a reference wraps at the column the prose wraps at — sometimes across a
-// blockquote `> ` continuation — while the heading it points at is one unbroken line.
-function normalize_reference(heading: string): string {
-	return heading
-		.replaceAll('`', '')
-		.split(/\s+/u)
-		.filter((word) => word !== '>')
-		.join(' ')
-}
-
-// The two forms a heading can be cited by: with its leading number (`2b. Delegating…`) and without
-// (`Delegating…`), since a document's own numbering is a prefix a reference may or may not carry.
-function reference_forms(title: string): Array<string> {
-	const normalized = normalize_reference(title)
-
-	return [normalized, normalized.replace(/^\d+[a-z]?\. /u, '')]
-}
-
-const document_scan = {
-	command_references,
-	is_placeholder_file,
-	label_references,
-	link_targets,
-	normalize_reference,
-	reference_forms,
-	section_references,
-}
-
-export type { SectionReference }
-export { document_scan }

package/scripts/document/generate-catalog.ts

@@ -1,69 +0,0 @@
-import { writeFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import {
-	ALIASES,
-	CATEGORY_ORDER,
-	COMMAND_MAP,
-	type CommandCategory,
-	type CommandEntry,
-} from '#scripts/josh/josh-command-map'
-
-const CATALOG_FILE = fileURLToPath(new URL('../../docs/josh-command-catalog.md', import.meta.url))
-
-const PREAMBLE = `# josh CLI — Command Catalog
-
-Auto-generated — do not edit.
-Run \`tsx scripts/document/generate-catalog.ts\` to regenerate.
-
-`
-
-function aliases_for(command_name: string): ReadonlyArray<string> {
-	return Object.entries(ALIASES)
-		.filter(([, target]) => target === command_name)
-		.map(([alias]) => alias)
-		.toSorted((x, y) => x.localeCompare(y))
-}
-
-function format_alias_heading(name: string, aliases: ReadonlyArray<string>): string {
-	if (aliases.length === 0) return `### \`josh ${name}\``
-	const alias_spans = aliases.map((al) => `\`josh ${al}\``).join(' · ')
-
-	return `### \`josh ${name}\` · ${alias_spans}`
-}
-
-function format_command_entry(name: string, entry: CommandEntry): string {
-	const [synopsis, audience, side_effects] = entry.reference
-	const aliases = aliases_for(name)
-	const kit_note = entry.is_kit_only === true ? ' · **kit only**' : ''
-	const heading = format_alias_heading(name, aliases)
-	const meta = `> **Audience:** ${audience} · **Side effects:** ${side_effects.join(', ')}${kit_note}`
-	const synopsis_line = synopsis ? `\`${synopsis}\`` : '_No arguments._'
-
-	return [heading, '', meta, '', synopsis_line, '', entry.description].join('\n')
-}
-
-function entries_for_category(category: CommandCategory): Array<[string, CommandEntry]> {
-	return Object.entries(COMMAND_MAP)
-		.filter(([, entry]) => entry.category === category)
-		.toSorted(([name_a], [name_b]) => name_a.localeCompare(name_b))
-}
-
-function generate_category_section(category: CommandCategory): string {
-	const entries = entries_for_category(category)
-	if (entries.length === 0) return ''
-	const command_blocks = entries.map(([name, entry]) => format_command_entry(name, entry))
-
-	return `## ${category}\n\n${command_blocks.join('\n\n---\n\n')}\n\n`
-}
-
-function generate_catalog(): string {
-	const content = PREAMBLE + CATEGORY_ORDER.map((cat) => generate_category_section(cat)).join('')
-
-	return `${content.trimEnd()}\n`
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	writeFileSync(CATALOG_FILE, generate_catalog())
-}
-
-export { CATALOG_FILE, generate_catalog }