@erclx/aitk 0.10.0 → 0.11.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.10.0",
+  "version": "0.11.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents.md

@@ -136,6 +136,16 @@ headlessly, so a call that names its stack or category is unchanged.
 `aitk snippets install`. Both resolve the target before anything else, so a path
 that does not exist fails rather than being scaffolded.
 
+`aitk gov regen` is the one governance verb that runs against the toolkit root,
+because the `.claude/rules/` it writes there is produced output rather than an
+operator's working copy. It reads the stack recorded in `internal/governance.toml`,
+installs it alongside anything under `internal/rules/`, and clears the
+destination first so a rule the record stopped naming disappears. It takes
+`--root <path>` and defaults to the toolkit root, prints nothing on success, and
+reports the reason on stderr with exit 1 when the record names a stack or rule
+that does not resolve. `scripts/core/regen-claude-copies.sh` calls it, and the
+Consumed copies stage of `bun run check` asserts the result is committed.
+
 `aitk sync` runs every installed domain sync, then offers to commit the result
 and open a pull request. Under `AITK_NON_INTERACTIVE=1` it applies the domain
 syncs and then refuses the git workflow, reporting the branch and commit it

package/package.json

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

package/scripts/core/regen-claude-copies.sh

@@ -23,4 +23,13 @@ mirror_dir "$PROJECT_ROOT/snippets" "$PROJECT_ROOT/.claude/snippets" -name "*.md
 
 # `internal/` is the surface the plugin does not symlink. Mirrored on its own so
 # toolkit sessions read it at a `.claude/` path like every other consumed copy.
-mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md"
+# `internal/rules/` is excluded because it lands in `.claude/rules/` below, and
+# mirroring it here too would publish each rule at a second inert path. The
+# exclusion is anchored to that one folder, since an unanchored `*/rules/*` would
+# also drop a later `internal/standards/rules/` and report nothing for it.
+mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md" -not -path "$PROJECT_ROOT/internal/rules/*"
+
+# `.claude/rules/` is a subset rather than a mirror, so it resolves through the
+# stack machinery instead of a fourth `mirror_dir` call. The record naming the
+# subset is `internal/governance.toml`.
+bun "$PROJECT_ROOT/src/cli.ts" gov regen --root "$PROJECT_ROOT"

package/scripts/core/verify.sh

@@ -132,7 +132,7 @@ main() {
 
   log_step "Consumed copies"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-claude-copies.sh" "Consumed-copy regen failed"
-  assert_no_drift ".claude/standards .claude/snippets .claude/internal" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, and .claude/internal."
+  assert_no_drift ".claude/standards .claude/snippets .claude/internal .claude/rules" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, .claude/internal, and .claude/rules."
   log_info "Consumed copies clean"
 
   log_step "Skill references"

package/src/commands/gov.ts

@@ -5,6 +5,7 @@ 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 { buildRulesPayload, listRuleFiles } from '@/gov/payload'
 import {
@@ -39,6 +40,10 @@ interface InstallOptions {
   readonly add?: string
 }
 
+interface RegenOptions {
+  readonly root?: string
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -95,9 +100,44 @@ export function register(program: Command): void {
       process.exitCode = await runBuild(target)
     })
 
+  gov
+    .command('regen')
+    .description("Rebuild a repository's own .claude/rules/ from its record")
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository root to regenerate', PROJECT_ROOT)
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads internal/governance.toml and installs the stack it names, plus',
+        'any rules under internal/rules/. Unlike install and sync, this runs',
+        'against the toolkit root, whose .claude/rules/ is produced output.',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RegenOptions) => {
+      process.exitCode = await runRegen(opts)
+    })
+
   registerPassThroughVerbs(gov, 'gov', PASS_THROUGH_VERBS)
 }
 
+/**
+ * Silent on success so the consumed-copy stage that calls it stays as quiet as
+ * the three `mirror_dir` lines it sits beside. The installed set is readable on
+ * disk, so printing it would only add noise to every `bun run check`.
+ */
+async function runRegen(opts: RegenOptions): Promise<number> {
+  const result = await regenConsumedRules(resolve(opts.root ?? PROJECT_ROOT))
+
+  if (!result.ok) {
+    process.stderr.write(`Consumed-rules regen failed: ${result.reason}\n`)
+    return 1
+  }
+
+  return 0
+}
+
 /**
  * Renders the target-relative path the prompt quotes, keeping the argument the
  * caller typed rather than the absolute path it resolves to.

package/src/gov/consumed.ts

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import {
+  installRules,
+  installedRulesDir,
+  lookupRules,
+  type RuleSource,
+  ruleSubdir,
+} from '@/gov/install'
+import { mergeExtraRules, resolveRules } from '@/gov/stacks'
+
+export const RECORD_REL = join('internal', 'governance.toml')
+
+const INTERNAL_RULES_REL = join('internal', 'rules')
+
+/** The stack a repository installs into its own `.claude/rules/`. */
+export interface ConsumedRecord {
+  readonly stack: string
+  readonly add: readonly string[]
+}
+
+export type ConsumedResult =
+  | { readonly ok: true; readonly installed: readonly string[] }
+  | { readonly ok: false; readonly reason: string }
+
+export function consumedRecordPath(root: string): string {
+  return join(root, RECORD_REL)
+}
+
+export function internalRulesDir(root: string): string {
+  return join(root, INTERNAL_RULES_REL)
+}
+
+/**
+ * Reads the record naming the consumed stack. A file with no `stack` reads the
+ * same as no file at all, since neither tells the producer what to install and
+ * the caller's message covers both.
+ */
+export function readConsumedRecord(root: string): ConsumedRecord | undefined {
+  const path = consumedRecordPath(root)
+  if (!existsSync(path)) return undefined
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const stack = typeof parsed.stack === 'string' ? parsed.stack : ''
+  if (stack === '') return undefined
+
+  return {
+    stack,
+    add: Array.isArray(parsed.add)
+      ? parsed.add.filter(
+          (rule): rule is string => typeof rule === 'string' && rule !== '',
+        )
+      : [],
+  }
+}
+
+/**
+ * Lists rules authored under `internal/rules/`. These govern toolkit authoring
+ * against paths only this repository has, so they install into the consumed
+ * copy without ever entering `governance/rules/`, which ships to targets.
+ */
+export function listInternalRules(root: string): RuleSource[] {
+  const dir = internalRulesDir(root)
+  if (!existsSync(dir)) return []
+
+  return [...new Bun.Glob('**/*.md').scanSync({ cwd: dir, onlyFiles: true })]
+    .sort()
+    .map((rel) => {
+      const src = join(dir, rel)
+      return { rule: basename(rel, '.md'), src, subdir: ruleSubdir(src, dir) }
+    })
+}
+
+/**
+ * Rebuilds a repository's own `.claude/rules/` from its record. Unlike
+ * `gov install` and `gov sync`, this runs against the toolkit root on purpose:
+ * those two refuse it because a target's rules are the operator's to edit,
+ * while this destination is produced output that happens to live beside its
+ * source.
+ */
+export async function regenConsumedRules(
+  root: string,
+): Promise<ConsumedResult> {
+  const record = readConsumedRecord(root)
+  if (record === undefined) {
+    return { ok: false, reason: `No stack recorded at ${RECORD_REL}` }
+  }
+
+  const resolution = resolveRules(root, record.stack)
+  if (!resolution.ok) {
+    return { ok: false, reason: `Stack not found: ${resolution.missingStack}` }
+  }
+
+  const { found, missing } = lookupRules(
+    root,
+    mergeExtraRules(resolution.rules, record.add.join(',')),
+  )
+  if (missing.length > 0) {
+    return { ok: false, reason: `No source for: ${missing.join(', ')}` }
+  }
+
+  const internal = listInternalRules(root)
+  const stackRules = new Set(found.map((entry) => entry.rule))
+  const shadowed = internal
+    .filter((entry) => stackRules.has(entry.rule))
+    .map((entry) => entry.rule)
+  if (shadowed.length > 0) {
+    return {
+      ok: false,
+      reason: `Internal rules shadow stack rules: ${shadowed.join(', ')}`,
+    }
+  }
+
+  // Clearing first is what makes a rule the record stopped naming disappear.
+  // Copying over the destination would leave it behind as an unsourced file,
+  // which is the state this producer exists to end.
+  await rm(installedRulesDir(root), { recursive: true, force: true })
+
+  const installed = [
+    ...(await installRules(found, root)),
+    ...(await installRules(internal, root)),
+  ]
+
+  return { ok: true, installed: installed.sort() }
+}