@erclx/aitk 0.56.0 → 0.58.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-groundwork/SKILL.md

@@ -7,7 +7,7 @@ description: Opens and runs a numbered groundwork folder under `.claude/groundwo
 
 Groundwork gathers and weighs. A plan commits. A groundwork folder costs nothing to throw away, which is what makes it the right container for a question nobody has answered yet.
 
-Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file in the folder. It holds the reserved numbers, what each required file carries, the conventions, and the anti-patterns.
+Read `.claude/standards/groundwork.md` from the project root before writing any file in the folder, or `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` when the project does not have it. It holds the reserved numbers, the frontmatter and dating rules, what each required file carries, the conventions, and the anti-patterns. Do not work them from memory.
 
 ## Guards
 
@@ -65,19 +65,9 @@ Then read only what a live question needs. Do not read entire directories specul
 
 Do not dispatch subagents. A groundwork track is a conversation, and fanning out loses the reasoning that makes the folder worth keeping. A search too large to run inline is a finding that the question is too broad.
 
-## Open question format
+## Open questions in chat
 
-Every open question carries a lean, wherever it appears: inside a topic file, in `00-scope.md`, and in the chat output. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
-
-```markdown
-1. <question>
-   - Leaning: <where the evidence currently points>
-   - Overturned by: <the finding that would change it>
-```
-
-- `Leaning:` is weaker than a plan's `- Suggested:`. It records the current read on a question still open by definition, not a decision to accept by default at execution time.
-- Pair every lean with what would overturn it. A lean with no falsifier is an opinion.
-- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse than an admission.
+The standard sets the open question format and requires it inside a topic file and in `00-scope.md`. Carry the same shape into the chat output, which sits outside the folder the standard governs. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
 
 ## Open mode
 
@@ -85,7 +75,7 @@ Every open question carries a lean, wherever it appears: inside a topic file, in
 2. Write `README.md` first. Writing it first forces the question of what the track is for.
 3. Write `01-current-state.md` by measuring now. Never carry a figure from a previous session or from recall without re-measuring it. Measure only what an open question in the folder needs. A number with no question attached is how groundwork turns into the work.
 4. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.
-5. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the format above.
+5. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the standard's format.
 6. Keep going. Revise, reframe, and take correction as the questions move. The folder is meant to be rewritten.
 
 ## Resume mode

package/claude/skills/claude-intake/SKILL.md

@@ -7,7 +7,7 @@ description: Files a raw brain dump into a numbered intake folder under `.claude
 
 Intake dispositions many findings in breadth. A dump goes in, an inventory comes out, and every item carries a problem measured against the tree, one proposed fix, and a verdict. The item that turns out to be already settled is the highest-value output, and it is the one thing neither a plan nor a groundwork track has anywhere to put.
 
-Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file in the folder. It holds the numbering, the file map, the frontmatter, and the item template.
+Read `.claude/standards/intake.md` from the project root before writing any file in the folder, or `${CLAUDE_SKILL_DIR}/../../standards/intake.md` when the project does not have it. It holds the numbering, the file map, the frontmatter and dating rules, the item format, and the answer contract. Do not work them from memory.
 
 ## Routing
 
@@ -34,7 +34,7 @@ Using the wrong one fails in two shapes. Intake on a question that needs measuri
 - Reading is unrestricted inside the project. Measuring is the work.
 - Treat the folder as gitignored and unbacked. No check reaches its contents, so every rule stated here holds only while a session reads it.
 
-Nothing outside this body carries the floor, and no path-scoped rule can. The item format and the answer contract are heading for a standard covering this folder and a groundwork track together, which is queued rather than written.
+Nothing outside this body carries the write-scope floor, and no path-scoped rule can. A misrouted write lands on a path the folder's glob never matches, so the rule that ships beside the intake standard carries the item format and the answer contract instead, for a session editing the folder with this skill unloaded.
 
 ## Step 1: detect open or resume
 
@@ -71,7 +71,9 @@ Two heading levels is the right depth. A third means the cluster should have bee
 
 ## Step 5: disposition each item
 
-Write every item in the format below, in the cluster file its fix belongs to. Close each item with a verdict and an empty operator slot.
+Write every item in the standard's item format, in the cluster file its fix belongs to. Close each item with a verdict and an empty operator slot, and never fill that slot or read an empty one as agreement.
+
+Where an item's call is the operator's, pair it with a suggestion rather than a bare question. The toolkit's `decision-help` snippet writes the same shape for chat use, and the standard's item format is the whole spec.
 
 ## Step 6: write the index
 
@@ -81,40 +83,6 @@ Each open question in the index is a labeled markdown link to its owning item's
 
 Add `99-next-session.md` only where the pass ends holding context no cluster file carries, such as a dump half filed or a measurement that has to be redone. Write it self-contained, since the folder is unbacked and the conversation behind it compacts away.
 
-## Item format
-
-```markdown
-### N. Short title stating the defect
-
-- **Problem:** what is wrong today, stated against the tree and carrying a number or a file path
-- **Fix:** the one change proposed
-- **Worth it:** yes, later, or no, with the reason
-- **Open:** only where the call is the operator's
-- **Suggested:** the pick in one sentence, then the reason and the main tradeoff in one or two
-- **Overlaps:** the live board task that already owns this item
-- **You:**
-```
-
-- `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
-- `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default. The toolkit's `decision-help` snippet writes the same four-line shape for chat use, and the four lines above are the whole spec.
-- `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
-
-## The answer contract
-
-`You:` belongs to the operator and ships empty on every item.
-
-Empty means unread. It never means agreement. Accepting a verdict is typed as one token, `- **You:** ok`.
-
-That inverts the plan file's contract, where a blank `- Answer:` means accept the suggestion, and the inversion is deliberate. A plan is read in one sitting with every question already surfaced in chat. An intake folder is read over weeks, so an empty slot is ambiguous between accepting the verdict and never having reached the item, and the second reading is far more likely. Acting on silence as consent ships a change nobody approved.
-
-Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
-
-## Numbering
-
-Numbers are read order and nothing else. Reserve `00` for the index and carry the domain in every other filename, so `07-tooling.md` says what it holds before anyone opens it.
-
-Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. `claude-groundwork` reserves its numbers because its shape is fixed, and that half of the convention does not transfer.
-
 ## Output
 
 Emit the full relative path from the project root for every file written, and name the heading and the act beside it. A path alone cannot distinguish three new items from one reworded sentence in a file that holds a dozen items and lives for weeks, so a bare path sends the reader to diff it against memory. This overrides the paths-only reporting the project states generally, which stays right wherever the reader is about to see a diff.

package/docs/agents/scripting.md

@@ -11,15 +11,15 @@ What a skill or script reads to discover names at runtime, and how each domain i
 
 Use these to discover what's available instead of hardcoding names.
 
-| Command                          | Returns                                       |
-| -------------------------------- | --------------------------------------------- |
-| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts  |
-| `aitk snippets list --json`      | Presets and categories with their slugs       |
-| `aitk standards list --json`     | Standards docs and the paths each governs     |
-| `aitk gov list --json`           | Governance stacks and rule sets               |
-| `aitk claude seeds list --json`  | Seed doc sources with content                 |
-| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag |
-| `aitk docs list --json`          | Consumer docs plus per-domain context         |
+| Command                          | Returns                                              |
+| -------------------------------- | ---------------------------------------------------- |
+| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts         |
+| `aitk snippets list --json`      | Presets and categories with their slugs              |
+| `aitk standards list --json`     | Standards docs and the paths each governs            |
+| `aitk gov list --json`           | Governance stacks, rule sets, and unreferenced rules |
+| `aitk claude seeds list --json`  | Seed doc sources with content                        |
+| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag        |
+| `aitk docs list --json`          | Consumer docs plus per-domain context                |
 
 ### Catalog fields
 
@@ -40,6 +40,18 @@ listing and the install cannot disagree. It now reports
 `.claude/context/index.md`, which `init` has always installed and the listing
 never named, and it emits the project-level `CLAUDE.md` last rather than first.
 
+`aitk gov list` reports each stack's rules already expanded. A stack entry names
+either a rule or a whole rule folder under `governance/rules/`, and the folder
+form reaches this listing as the rules it stands for rather than as the folder
+name. A consumer deduping `--add` extras against a stack therefore reads the same
+set the install writes, whichever form the stack file uses.
+
+It also carries `unreferenced`, the rules no stack reaches, on every invocation
+rather than behind a flag. These install only through `--add`, so the key answers
+what a stack leaves out without a caller resolving every stack itself. The key is
+present alongside `stacks` and `rules` and survives `--stacks` or `--rules`
+narrowing the other two.
+
 ### The skills catalog
 
 `aitk claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder

package/governance/rules/claude/556-groundwork.md

@@ -0,0 +1,16 @@
+---
+description: Route .claude/groundwork/ edits to the groundwork standard for numbering, frontmatter, and required file contents
+paths:
+  - '.claude/groundwork/**'
+---
+
+# Groundwork standards
+
+## Measuring and closing
+
+- Never carry a figure from an earlier session without re-measuring it. Mark an inference as an inference.
+- Never close a track while an open question quietly fails an outcome. Resolve it, or record it as knowingly accepted.
+
+## Authority
+
+- Follow `.claude/standards/groundwork.md` for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source.

package/governance/rules/claude/557-intake.md

@@ -0,0 +1,16 @@
+---
+description: Route .claude/intake/ edits to the intake standard for the item format, the answer contract, and numbering
+paths:
+  - '.claude/intake/**'
+---
+
+# Intake standards
+
+## The answer contract
+
+- Never fill a `You:` slot and never infer a disposition from an empty one. Empty means unread, never agreement.
+- Report unread items by count on a resume pass. Do not decide one.
+
+## Authority
+
+- Follow `.claude/standards/intake.md` for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source.

package/governance/stacks/base.toml

@@ -1,2 +1,4 @@
 extends = ""
-rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "090-code-comments", "500-prose", "501-markdown", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]
+# Both folders whole. Every rule authored under them ships to a base consumer,
+# so adding one is a single edit rather than a file and a name here.
+rules = ["core", "claude"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -45,14 +45,34 @@ for payload in "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$T
   fi
 done
 
-export SKILLS_JSON GOV_JSON STANDARDS_JSON SNIPPETS_JSON TOOLING_JSON
+# The catalogs reach the eval as files rather than as environment entries. Linux
+# caps a single env string at 128KB, and the standards payload crossed it, which
+# fails the exec with E2BIG before any stage can report a stale count. A file
+# path is bounded whatever the catalogs grow to.
+PAYLOAD_DIR="$(mktemp -d)"
+trap 'rm -rf "$PAYLOAD_DIR"' EXIT
+
+printf '%s' "$SKILLS_JSON" >"$PAYLOAD_DIR/skills.json"
+printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
+printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
+printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
+printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
+
+export PAYLOAD_DIR
 export TEMPLATE OUTPUT LISTED PROJECT_ROOT
 
 bun --eval '
-const {
-  SKILLS_JSON, GOV_JSON, STANDARDS_JSON, SNIPPETS_JSON, TOOLING_JSON,
-  TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT,
-} = process.env
+const { readFileSync } = require("node:fs")
+
+const { PAYLOAD_DIR, TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT } = process.env
+
+const payload = (name) => readFileSync(PAYLOAD_DIR + "/" + name + ".json", "utf8")
+
+const SKILLS_JSON = payload("skills")
+const GOV_JSON = payload("gov")
+const STANDARDS_JSON = payload("standards")
+const SNIPPETS_JSON = payload("snippets")
+const TOOLING_JSON = payload("tooling")
 
 const listed = Number(LISTED)
 const skills = JSON.parse(SKILLS_JSON).skills.map((entry) => entry.name)

package/scripts/core/verify.sh

@@ -18,6 +18,12 @@ CHANGED_FILES=""
 # unarmed and why.
 SANDBOX_UNDECLARED_CEILING=47
 
+# Rules no stack reaches, space separated and sorted the way `aitk gov list`
+# emits them. Both are opt-in libraries a project may not want, so they are
+# recorded here rather than in a config file: the list is what a reader compares
+# a new arrival against, and a config file would absorb the arrival silently.
+GOV_EXPECTED_UNREFERENCED="260-shadcn 320-tanstack-query"
+
 check_dependencies() {
   command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
 }
@@ -208,6 +214,55 @@ main() {
   run_check "bash $PROJECT_ROOT/scripts/core/check-plugin-boundary.sh" "Plugin ships toolkit-internal content."
   log_info "Plugin boundary clean"
 
+  # A stack entry naming a rule folder takes every rule in it, which is what
+  # stops a new rule from needing a second edit to reach a target. The failure
+  # it leaves open is a rule authored into a folder no stack names, which
+  # installs for nobody and reports nothing on its own.
+  #
+  # This reports and never fails. Both standing findings are opt-in libraries
+  # this repository ships on purpose, so gating would fail every push over the
+  # deliberate case and teach a reader to route around the stage. Revisit when a
+  # third appears and the pattern is either a library set or an accident.
+  log_step "Unreferenced rules"
+  local gov_json gov_status=0 unreferenced
+  gov_json=$(cd "$PROJECT_ROOT" && bun src/cli.ts gov list --json 2>/dev/null) || gov_status=$?
+  if [ "$gov_status" -ne 0 ] || [ -z "$gov_json" ]; then
+    log_warn "Skipped, the governance catalog did not report"
+  else
+    # `bun --eval` rather than a grep, because the key holds an array of names
+    # and the numeric matches the stages above use reach a scalar alone.
+    #
+    # The `ok:` sentinel carries success rather than the exit code, because
+    # `bun --eval` reading piped stdin exits 0 even when the script throws.
+    # Measured on Bun 1.3.14: the same throw exits 1 with no pipe attached. A
+    # payload that parses as text but not as JSON would therefore print nothing
+    # and exit clean, and empty already means every rule is reached, so reading
+    # the exit code would report a broken catalog as a clean sweep. A missing
+    # or non-array key takes the same branch, since a stage that cannot measure
+    # should say so rather than claim the sweep found nothing.
+    local reported
+    reported=$(printf '%s' "$gov_json" | bun --eval '
+      try {
+        const data = JSON.parse(require("node:fs").readFileSync(0, "utf8"))
+        if (!Array.isArray(data.unreferenced)) throw new Error("no field")
+        console.log("ok:" + data.unreferenced.join(" "))
+      } catch {
+        console.log("unreadable:")
+      }
+    ')
+    unreferenced="${reported#ok:}"
+    if [ "${reported%%:*}" != "ok" ]; then
+      log_warn "Skipped, the governance catalog carried no readable unreferenced list"
+    elif [ -z "$unreferenced" ]; then
+      log_info "Every rule is reached by a stack"
+    elif [ "$unreferenced" = "$GOV_EXPECTED_UNREFERENCED" ]; then
+      log_info "Reached by no stack: $unreferenced (opt-in, install with --add)"
+    else
+      log_warn "Reached by no stack: $unreferenced"
+      log_warn "Expected: $GOV_EXPECTED_UNREFERENCED. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in this script and say why it ships opt-in."
+    fi
+  fi
+
   # Only the citation half of the audit gates. Length, depth, table, and index
   # findings are judgment thresholds, and failing a push on one would make the
   # stage something to route around. `bun src/cli.ts` rather than `aitk`, since a

package/src/commands/gov.ts

@@ -2,11 +2,11 @@ import { existsSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, resolve } from 'node:path'
 import type { Command } from 'commander'
-import { registerPassThroughVerbs } from '@/commands/pass-through'
 import { PROJECT_ROOT } from '@/exec'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
 import { hasStandards, installRules, lookupRules } from '@/gov/install'
+import { buildGovCatalog, describeRule, describeStack } from '@/gov/list'
 import { buildRulesPayload, listRuleFiles } from '@/gov/payload'
 import {
   govStackExists,
@@ -34,8 +34,6 @@ const NC = '\x1b[0m'
 const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
 const RULES_REL = join('.claude', 'rules')
 
-const PASS_THROUGH_VERBS = ['list'] as const
-
 interface InstallOptions {
   readonly add?: string
 }
@@ -44,6 +42,12 @@ interface RegenOptions {
   readonly root?: string
 }
 
+interface ListOptions {
+  readonly stacks?: boolean
+  readonly rules?: boolean
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -119,7 +123,78 @@ export function register(program: Command): void {
       process.exitCode = await runRegen(opts)
     })
 
-  registerPassThroughVerbs(gov, 'gov', PASS_THROUGH_VERBS)
+  gov
+    .command('list')
+    .description('Emit the catalog of stacks and rules')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--stacks', 'Only list stacks')
+    .option('--rules', 'Only list rules')
+    .option('--json', 'Emit machine-readable JSON')
+    .action((opts: ListOptions) => {
+      process.exitCode = runList(opts)
+    })
+}
+
+/**
+ * Both selectors absent means both sections, which is the bash default. Naming
+ * both is the same as naming neither rather than an error, since the two flags
+ * read as filters and a caller passing both is asking for everything.
+ */
+function selectedSections(opts: ListOptions): {
+  stacks: boolean
+  rules: boolean
+} {
+  const stacks = opts.stacks === true
+  const rules = opts.rules === true
+  if (stacks === rules) return { stacks: true, rules: true }
+  return { stacks, rules }
+}
+
+/**
+ * `JSON.stringify` replaces a `printf` that interpolated a description into a
+ * JSON string literal through a hand-rolled escaper, so a rule carrying a
+ * character that escaper missed emitted output a consuming skill could not
+ * parse.
+ *
+ * `unreferenced` rides the same payload rather than taking a flag of its own.
+ * The verify stage and a skill asking what a stack leaves out read one call,
+ * and the key is additive, so a consumer reading `stacks` or `rules` is
+ * untouched by it.
+ */
+function runList(opts: ListOptions): number {
+  const catalog = buildGovCatalog(PROJECT_ROOT)
+  const sections = selectedSections(opts)
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ...(sections.stacks ? { stacks: catalog.stacks } : {}),
+        ...(sections.rules ? { rules: catalog.rules } : {}),
+        unreferenced: catalog.unreferenced,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk gov list')
+
+  if (sections.stacks) {
+    logStep('Stacks')
+    for (const entry of catalog.stacks) logInfo(describeStack(entry))
+  }
+
+  if (sections.rules) {
+    logStep('Rules')
+    for (const entry of catalog.rules) logInfo(describeRule(entry))
+  }
+
+  if (catalog.unreferenced.length > 0) {
+    logStep('Reached by no stack')
+    for (const rule of catalog.unreferenced) logInfo(rule)
+  }
+
+  outro()
+  return 0
 }
 
 /**

package/src/gov/install.ts

@@ -31,6 +31,37 @@ export function ruleSubdir(src: string, rulesRoot: string): string {
   return subdir === '.' ? '' : subdir
 }
 
+/**
+ * Lists every rule source path under `governance/rules/`, relative to it and
+ * sorted, so a caller walking the tree and a caller resolving one name read the
+ * same order.
+ */
+export function listRuleSourcePaths(root: string): string[] {
+  const rulesRoot = rulesSourceDir(root)
+  if (!existsSync(rulesRoot)) return []
+
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: rulesRoot, onlyFiles: true }),
+  ].sort()
+}
+
+/**
+ * Maps each rule name to its source file. First path wins, so a name appearing
+ * in two subdirectories resolves deterministically rather than by whichever
+ * entry the filesystem yielded first.
+ */
+function indexRuleSources(root: string): Map<string, string> {
+  const rulesRoot = rulesSourceDir(root)
+  const byName = new Map<string, string>()
+
+  for (const rel of listRuleSourcePaths(root)) {
+    const name = rel.slice(rel.lastIndexOf('/') + 1, -'.md'.length)
+    if (!byName.has(name)) byName.set(name, join(rulesRoot, rel))
+  }
+
+  return byName
+}
+
 /**
  * Finds each rule's source file by name across the `governance/rules/`
  * subfolders. A rule with no source is reported rather than dropped, matching
@@ -41,21 +72,7 @@ export function lookupRules(
   rules: readonly string[],
 ): RuleLookup {
   const rulesRoot = rulesSourceDir(root)
-  const byName = new Map<string, string>()
-
-  const relPaths = existsSync(rulesRoot)
-    ? [
-        ...new Bun.Glob('**/*.md').scanSync({
-          cwd: rulesRoot,
-          onlyFiles: true,
-        }),
-      ].sort()
-    : []
-
-  for (const rel of relPaths) {
-    const name = rel.slice(rel.lastIndexOf('/') + 1, -'.md'.length)
-    if (!byName.has(name)) byName.set(name, join(rulesRoot, rel))
-  }
+  const byName = indexRuleSources(root)
 
   const found: RuleSource[] = []
   const missing: string[] = []

package/src/gov/list.ts

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
+import {
+  expandStackEntry,
+  listGovStacks,
+  loadGovStack,
+  unreferencedRules,
+} from '@/gov/stacks'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+
+export interface StackEntry {
+  readonly name: string
+  readonly extends: string | null
+  readonly rules: string[]
+}
+
+export interface RuleEntry {
+  readonly name: string
+  readonly domain: string
+  readonly description: string
+  readonly paths: string[] | null
+}
+
+export interface GovCatalog {
+  readonly stacks: StackEntry[]
+  readonly rules: RuleEntry[]
+  readonly unreferenced: string[]
+}
+
+/**
+ * Reports each stack's own entries expanded, so a folder entry reaches a
+ * consumer as the rules it stands for. `setup-gov` dedupes `--add` extras
+ * against this list, and a stack answering `core` there would re-add every
+ * rule that folder already carries.
+ *
+ * The `extends` chain is deliberately not resolved, which is what the bash
+ * did. The list shows what each stack contributes beside the parent it
+ * inherits from, rather than repeating the ancestors under every descendant.
+ */
+export function buildStackEntries(root: string): StackEntry[] {
+  const entries: StackEntry[] = []
+
+  for (const name of listGovStacks(root)) {
+    const stack = loadGovStack(root, name)
+    if (!stack) continue
+
+    const seen = new Set<string>()
+    const rules: string[] = []
+
+    for (const entry of stack.rules) {
+      for (const rule of expandStackEntry(root, entry)) {
+        if (seen.has(rule)) continue
+        seen.add(rule)
+        rules.push(rule)
+      }
+    }
+
+    entries.push({ name, extends: stack.parent ?? null, rules })
+  }
+
+  return entries
+}
+
+/**
+ * Reads the catalog straight off the source tree. A rule's domain is the
+ * subdirectory it sits in, which is the band grouping install preserves.
+ */
+export function buildRuleEntries(root: string): RuleEntry[] {
+  const rulesRoot = rulesSourceDir(root)
+
+  return listRuleSourcePaths(root).map((rel) => {
+    const frontmatter = parseFrontmatter(
+      readFileSync(join(rulesRoot, rel), 'utf8'),
+    )
+    const paths = frontmatter?.fields.paths
+
+    return {
+      name: basename(rel, '.md'),
+      domain: rel.includes('/') ? rel.slice(0, rel.indexOf('/')) : '',
+      description: readField(frontmatter, 'description') ?? '',
+      paths: Array.isArray(paths)
+        ? paths.filter((entry): entry is string => typeof entry === 'string')
+        : null,
+    }
+  })
+}
+
+export function buildGovCatalog(root: string): GovCatalog {
+  return {
+    stacks: buildStackEntries(root),
+    rules: buildRuleEntries(root),
+    unreferenced: unreferencedRules(root),
+  }
+}
+
+export function describeStack(entry: StackEntry): string {
+  const count = `${entry.rules.length} rules`
+  return entry.extends === null
+    ? `${entry.name} (${count})`
+    : `${entry.name} (extends: ${entry.extends}, ${count})`
+}
+
+export function describeRule(entry: RuleEntry): string {
+  return `${entry.name} [${entry.domain}] ${entry.description}`
+}