jackherd 1.13.0 → 1.15.0

package/src/check/plan.ts

@@ -3,9 +3,10 @@ import { STACKS, type Stack, type StackProfile } from '../config/detect'
 import { agentTextReviewers } from './agent-text-reviewers'
 import { type ChangedFile, generatorOwnedFiles, stagedBuildArtifacts } from './changes'
 import { tokenize } from './command-line'
+import { hasNamedTest, isSourceFile, isTestFile, testStemsOf } from './file-kinds'
 import { matchesAnyGlob } from './glob'
 import { CHECK_KIND, type CheckKind } from './result'
-import { isUnder, looseDirectories, packageRootsFor } from './roots'
+import { isUnder, looseDirectories, nearestRootOf, packageRootOf, packageRootsFor } from './roots'
 import { projectChecksFor, publicContentReviewers, reviewersFor } from './routing'
 import type { CheckConfig, ProjectCheck } from './schema'
 
@@ -21,7 +22,7 @@ export type PlannedCheck = {
   kind: CheckKind
 }
 
-export type PackageCommands = Pick<JackherdConfig['commands'], 'test' | 'typecheck'>
+export type PackageCommands = Pick<JackherdConfig['commands'], 'test' | 'typecheck' | 'lint'>
 
 /** What the plan asks of the disk, by the markers of the stack (`checkStackOf`). */
 export type Filesystem = {
@@ -32,9 +33,11 @@ export type Filesystem = {
   /** Whether the directory holds a type marker of the stack (`tsconfig.json`, `phpstan.neon`). */
   hasTypeConfig: (dir: string) => boolean
   hasTests: (dir: string) => boolean
+  /** Every file of the repository that git tracks or does not ignore; read only for the name rule. */
+  repositoryFiles: () => readonly string[]
 }
 
-/** The stack as the check reads it; without a detected stack, every stack's markers and patterns together. */
+/** The stack as the check reads it; with none or several detected, every stack's markers and patterns together. */
 export type CheckStack = {
   rootMarkers: string[]
   typeMarkers: string[]
@@ -44,6 +47,14 @@ export type CheckStack = {
   lintGlobs: string[]
 }
 
+/** What the check reads only where no stack is detected at all (not where several are). */
+export type NoStackFallback = {
+  /** `check.roots` and the repository root `.`: a file no root marker holds belongs to the nearest one above it. */
+  roots: readonly string[]
+  /** `commands.lint`, run once from `.` where no `check.lintFilesCommand` is set. */
+  lintCommand?: string
+}
+
 /** What the plan reads from the settings: the test and type commands, the `check` block and the stack's patterns. */
 export type PlanInputs = {
   commands: PackageCommands
@@ -51,6 +62,8 @@ export type PlanInputs = {
   stack: Pick<CheckStack, 'lintGlobs' | 'sourceFile'>
   /** Repository paths of the kit's copies (`.jackherd/lock.json`); their tests run where the kit keeps the source. */
   kitCopies: readonly string[]
+  /** Null where a stack is detected, or several. */
+  noStackFallback: NoStackFallback | null
 }
 
 export type CheckPlan = {
@@ -63,8 +76,22 @@ export type CheckPlan = {
   checks: PlannedCheck[]
   /** The changed source files of the stack no planned test reaches, kit copies aside; a check without a test is no green. */
   untestedSources: string[]
+  /**
+   * Without a detected stack, the changed source files under a root found by `NoStackFallback.roots` that no test file
+   * of their name covers: a run from such a root reaches every file, so the name decides, and only as a warning.
+   */
+  sourcesWithoutNamedTest: string[]
 }
 
+/** The roots of a change: by root marker, and without a detected stack by `NoStackFallback.roots` for the rest. */
+type ChangeRoots = { roots: string[]; fallbackRoots: string[]; fallbackPaths: string[] }
+
+/** What reaches a changed file: a test run from a directory above it, or a fired project check of kind tests whose globs (or no globs) match it. */
+type TestReach = { dirs: readonly string[]; checks: readonly ProjectCheck[] }
+
+/** Which changed source files no test covers: the paths under marker roots by reach, the fallback paths by name. */
+type Coverage = Pick<CheckPlan, 'untestedSources' | 'sourcesWithoutNamedTest'>
+
 export const isSlow = (check: PlannedCheck): boolean =>
   check.kind === CHECK_KIND.types || check.kind === CHECK_KIND.tests
 
@@ -92,6 +119,36 @@ export const checkStackOf = (stack: Stack | null): CheckStack => {
 const lintedPaths = (paths: readonly string[], lintGlobs: readonly string[]): string[] =>
   lintGlobs.length === 0 ? [...paths] : paths.filter((path) => matchesAnyGlob(path, lintGlobs))
 
+/** A predicate from the configured globs, or the given one where none are configured. */
+const globsOr =
+  (globs: readonly string[] | undefined, fallback: (path: string) => boolean) =>
+  (path: string): boolean =>
+    globs === undefined ? fallback(path) : matchesAnyGlob(path, globs)
+
+/** Each path no root marker holds, with the nearest fallback root above it; paths without one are left out. */
+const fallbackRootsOf = (
+  paths: readonly string[],
+  fallback: readonly string[],
+  isProjectRoot: Filesystem['isProjectRoot'],
+): { path: string; root: string }[] =>
+  paths.flatMap((path) => {
+    const root = packageRootOf(path, isProjectRoot) === null ? nearestRootOf(path, fallback) : null
+    return root === null ? [] : [{ path, root }]
+  })
+
+const changeRootsOf = (
+  paths: readonly string[],
+  fallback: readonly string[],
+  { isProjectRoot, isWorkspaceRoot }: Pick<Filesystem, 'isProjectRoot' | 'isWorkspaceRoot'>,
+): ChangeRoots => {
+  const isTestable = (root: string) => !isWorkspaceRoot(root)
+  const fallbackPairs = fallbackRootsOf(paths, fallback, isProjectRoot)
+  const fallbackPaths = fallbackPairs.map(({ path }) => path)
+  const fallbackRoots = unique(fallbackPairs.map(({ root }) => root)).filter(isTestable)
+  const markerRoots = packageRootsFor(paths, isProjectRoot).filter(isTestable)
+  return { roots: unique([...markerRoots, ...fallbackRoots]), fallbackRoots, fallbackPaths }
+}
+
 /** No lint without a `lintFilesCommand`, none is guessed; none either when no changed file is the stack's to lint. */
 const lintChecks = (command: string | undefined, paths: readonly string[]): PlannedCheck[] =>
   command === undefined || paths.length === 0
@@ -106,6 +163,17 @@ const lintChecks = (command: string | undefined, paths: readonly string[]): Plan
         },
       ]
 
+/** Without a detected stack and a `lintFilesCommand`, the project's lint once from the repository root. */
+const projectLint = (command: string | undefined): PlannedCheck[] =>
+  command === undefined ? [] : [{ name: 'Lint', command, argv: tokenize(command), cwd: '.', kind: CHECK_KIND.lint }]
+
+const lintOf = (
+  lintFilesCommand: string | undefined,
+  noStackFallback: NoStackFallback | null,
+  paths: readonly string[],
+): PlannedCheck[] =>
+  lintFilesCommand === undefined ? projectLint(noStackFallback?.lintCommand) : lintChecks(lintFilesCommand, paths)
+
 const projectChecks = (fired: readonly ProjectCheck[]): PlannedCheck[] =>
   fired.map(({ name, command, kind }) => ({
     name,
@@ -127,18 +195,15 @@ const inDirectory = (kind: CheckKind, label: string, command: string, dir: strin
 const typeChecks = (
   roots: readonly string[],
   command: string | undefined,
-  hasTypeConfig: Filesystem['hasTypeConfig'],
+  isTypeRoot: (root: string) => boolean,
 ): PlannedCheck[] =>
   command === undefined
     ? []
-    : roots.filter(hasTypeConfig).map((root) => inDirectory(CHECK_KIND.types, 'Types', command, root))
+    : roots.filter(isTypeRoot).map((root) => inDirectory(CHECK_KIND.types, 'Types', command, root))
 
 const testChecks = (dirs: readonly string[], command: string | undefined): PlannedCheck[] =>
   command === undefined ? [] : dirs.map((dir) => inDirectory(CHECK_KIND.tests, 'Tests', command, dir))
 
-/** What reaches a changed file: a test run from a directory above it, or a fired project check of kind tests whose globs (or no globs) match it. */
-type TestReach = { dirs: readonly string[]; checks: readonly ProjectCheck[] }
-
 const isReached = (path: string, { dirs, checks }: TestReach): boolean =>
   dirs.some((dir) => isUnder(path, dir)) ||
   checks.some(({ globs }) => globs === undefined || matchesAnyGlob(path, globs))
@@ -147,8 +212,43 @@ const isReached = (path: string, { dirs, checks }: TestReach): boolean =>
 const untestedSourcesOf = (
   paths: readonly string[],
   reach: TestReach,
-  { sourceFile, kitCopies }: Pick<PlanInputs['stack'], 'sourceFile'> & Pick<PlanInputs, 'kitCopies'>,
-): string[] => paths.filter((path) => sourceFile.test(path) && !kitCopies.includes(path) && !isReached(path, reach))
+  { isSource, kitCopies }: { isSource: (path: string) => boolean; kitCopies: readonly string[] },
+): string[] => paths.filter((path) => isSource(path) && !kitCopies.includes(path) && !isReached(path, reach))
+
+/** The source files among `paths` with no test file of their name in the repository, read only when there are any. */
+const sourcesWithoutNamedTestOf = (
+  paths: readonly string[],
+  testChecks: readonly ProjectCheck[],
+  { check, kitCopies }: Pick<PlanInputs, 'check' | 'kitCopies'>,
+  repositoryFiles: Filesystem['repositoryFiles'],
+): string[] => {
+  const isTest = globsOr(check.testFiles, isTestFile)
+  const isNamedSource = globsOr(check.sourceFiles, isSourceFile)
+  const isSource = (path: string) => !isTest(path) && isNamedSource(path)
+  const candidates = untestedSourcesOf(paths, { dirs: [], checks: testChecks }, { isSource, kitCopies })
+  if (candidates.length === 0) return []
+  const testStems = testStemsOf(repositoryFiles(), isTest)
+  return candidates.filter((path) => !hasNamedTest(path, testStems))
+}
+
+const coverageOf = (
+  { paths, fallbackPaths }: { paths: readonly string[]; fallbackPaths: readonly string[] },
+  reach: TestReach,
+  { check, stack, kitCopies }: Pick<PlanInputs, 'check' | 'stack' | 'kitCopies'>,
+  repositoryFiles: Filesystem['repositoryFiles'],
+): Coverage => {
+  const markerPaths = paths.filter((path) => !fallbackPaths.includes(path))
+  const isSource = globsOr(check.sourceFiles, (path) => stack.sourceFile.test(path))
+  return {
+    untestedSources: untestedSourcesOf(markerPaths, reach, { isSource, kitCopies }),
+    sourcesWithoutNamedTest: sourcesWithoutNamedTestOf(
+      fallbackPaths,
+      reach.checks,
+      { check, kitCopies },
+      repositoryFiles,
+    ),
+  }
+}
 
 /** The reviewers a set of changed paths calls for, each named once: routed, public content and agent texts. */
 export const reviewersOf = (paths: readonly string[], config: CheckConfig): string[] => [
@@ -162,15 +262,17 @@ export const reviewersOf = (paths: readonly string[], config: CheckConfig): stri
 /**
  * Decides, without touching the disk or running anything, what a set of changed files calls for:
  * which package roots to type-check and test, which project checks fire, which reviewers to start,
- * and which changed source files no test covers. A root that gathers workspaces is never tested.
+ * and which changed source files no test covers. A root that gathers workspaces is never tested. Without a
+ * detected stack, a file no root marker holds is tested from its `NoStackFallback.roots` entry and judged by its name.
  */
 export const planChecks = (
   files: readonly ChangedFile[],
-  { commands, check: config, stack, kitCopies }: PlanInputs,
+  { commands, check: config, stack, kitCopies, noStackFallback }: PlanInputs,
   filesystem: Filesystem,
 ): CheckPlan => {
   const paths = files.map((file) => file.path)
-  const roots = packageRootsFor(paths, filesystem.isProjectRoot).filter((root) => !filesystem.isWorkspaceRoot(root))
+  const { roots, fallbackRoots, fallbackPaths } = changeRootsOf(paths, noStackFallback?.roots ?? [], filesystem)
+  const isTypeRoot = (root: string) => fallbackRoots.includes(root) || filesystem.hasTypeConfig(root)
   const loose = config.looseTests ? looseDirectories(paths, roots, filesystem.hasTests) : []
   const fired = projectChecksFor(paths, config.checks)
   const testDirs = commands.test === undefined ? [] : [...roots, ...loose]
@@ -178,9 +280,9 @@ export const planChecks = (
     paths.length === 0
       ? []
       : [
-          ...lintChecks(config.lintFilesCommand, lintedPaths(paths, stack.lintGlobs)),
+          ...lintOf(config.lintFilesCommand, noStackFallback, lintedPaths(paths, stack.lintGlobs)),
           ...projectChecks(fired),
-          ...typeChecks(roots, commands.typecheck, filesystem.hasTypeConfig),
+          ...typeChecks(roots, commands.typecheck, isTypeRoot),
           ...testChecks(testDirs, commands.test),
         ]
   const reach: TestReach = { dirs: testDirs, checks: fired.filter((check) => check.kind === CHECK_KIND.tests) }
@@ -191,6 +293,6 @@ export const planChecks = (
     generated: generatorOwnedFiles(paths, config.generatorOwned),
     artifacts: stagedBuildArtifacts(files, config.buildArtifacts),
     checks,
-    untestedSources: untestedSourcesOf(paths, reach, { sourceFile: stack.sourceFile, kitCopies }),
+    ...coverageOf({ paths, fallbackPaths }, reach, { check: config, stack, kitCopies }, filesystem.repositoryFiles),
   }
 }

package/src/check/report.ts

@@ -1,7 +1,8 @@
 import { STACKS, type StackDetection, stackOfCommand } from '../config/detect'
+import { PROJECT_CONFIG_PATH } from '../config/location'
 import { CLI_NAME } from '../version/release'
 import { type ChangedFile, STATUS_COMMAND } from './changes'
-import type { CheckPlan } from './plan'
+import type { CheckPlan, PackageCommands } from './plan'
 import { CHECK_STATUS, type CheckResult, type CheckStatus, RUN_MODE, type RunMode, SKIP_SLOW_FLAG } from './result'
 
 const STATUS_ICON = { pass: '✅', fail: '❌', warn: '⚠️ ', skipped: '⏭️ ' } as const
@@ -45,6 +46,48 @@ export const untestedResult = (sources: readonly string[], mode: RunMode): Check
         durationMs: 0,
       }
 
+/** Without a detected stack, the changed source files no test file of their name covers: a warning in every run mode. */
+export const namedTestResult = (sources: readonly string[]): CheckResult | null =>
+  sources.length === 0
+    ? null
+    : {
+        name: 'Tests by name',
+        command: 'check.testFiles',
+        status: CHECK_STATUS.warn,
+        detail: [
+          `no test file named like ${plural(sources.length, 'changed source file')}; add one, or name the test files in \`check.testFiles\``,
+          ...sources,
+        ].join('\n'),
+        durationMs: 0,
+      }
+
+/** Without a detected stack nothing derives `commands.test`, and a check without it tests nothing, so it fails. */
+export const missingTestCommandResult = (command: string | undefined, detection: StackDetection): CheckResult | null =>
+  command !== undefined || detection.kind !== 'none'
+    ? null
+    : {
+        name: 'Test command',
+        command: 'commands.test',
+        status: CHECK_STATUS.fail,
+        detail: `no stack detected and no \`commands.test\` set; set it in ${PROJECT_CONFIG_PATH} (\`${CLI_NAME} config test\` names the line, \`/jh-start\` proposes it from the CI)`,
+        durationMs: 0,
+      }
+
+/** Without a detected stack a missing type or lint command is a note, not a result: not every language has the step. */
+export const missingCommandNotes = (
+  commands: PackageCommands,
+  lintFilesCommand: string | undefined,
+  detection: StackDetection,
+): string[] => {
+  if (detection.kind !== 'none') return []
+  return [
+    ...(commands.typecheck === undefined ? [`${CLI_NAME}: no \`commands.typecheck\` set; no type check runs.`] : []),
+    ...(commands.lint === undefined && lintFilesCommand === undefined
+      ? [`${CLI_NAME}: neither \`check.lintFilesCommand\` nor \`commands.lint\` set; no lint runs.`]
+      : []),
+  ]
+}
+
 /** The lock files of known stacks the repository holds; none means it has not installed yet. */
 const presentLockFiles = (detection: StackDetection): readonly string[] => {
   if (detection.kind === 'found') return [detection.lockFile]

package/src/check/roots.ts

@@ -46,6 +46,15 @@ export const kitCopyPaths = (manifest: unknown): string[] => {
 /** Whether a test run from `root` reaches `path`; from `.` it reaches every path. */
 export const isUnder = (path: string, root: string): boolean => root === '.' || path.startsWith(`${root}/`)
 
+/**
+ * The deepest of `roots` above `path`; null when none is. Without a detected stack, a file no root marker holds
+ * belongs to the nearest `check.roots` entry, with the repository root `.` among them.
+ */
+export const nearestRootOf = (path: string, roots: readonly string[]): string | null =>
+  roots
+    .filter((root) => isUnder(path, root))
+    .reduce<string | null>((nearest, root) => (nearest === null || root.length > nearest.length ? root : nearest), null)
+
 /**
  * Directories with test files that belong to no package root, which would otherwise be tested by
  * nobody. The repository root `.` is excluded: a test run from there walks the whole repository.

package/src/check/schema.ts

@@ -20,6 +20,9 @@ const glob = nonEmpty.refine((value) => !/[{}[\]]/.test(value), 'Braces and brac
 
 const globs = z.array(glob).min(1)
 
+/** A directory from the repository root as the check compares it: `./crates/core/` reads as `crates/core`. */
+const directory = nonEmpty.transform((value) => value.replace(/^(\.\/)+/, '').replace(/\/+$/, '') || '.')
+
 /** Staged output that belongs to a build, never to a commit. */
 export const DEFAULT_BUILD_ARTIFACT_GLOBS = [
   '**/tsup.config.bundled_*',
@@ -88,6 +91,15 @@ export const checkConfigSchema = z.strictObject({
   skillBudgets: skillBudgets.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
   looseTests: z.boolean().default(false),
+  /**
+   * Package roots, as directories from the repository root, read only where no stack is detected: a changed file
+   * belongs to the nearest one above it, else to the repository root `.`.
+   */
+  roots: z.array(directory).min(1).optional(),
+  /** The files a test covers; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  sourceFiles: globs.optional(),
+  /** The test files; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  testFiles: globs.optional(),
 })
 
 export type CheckConfig = z.infer<typeof checkConfigSchema>

package/src/check/settings.ts

@@ -10,7 +10,7 @@ import {
 } from '../config/detect'
 import { PROJECT_CONFIG_PATH } from '../config/location'
 import type { PlanLanguage } from '../vocabulary'
-import type { PackageCommands } from './plan'
+import type { NoStackFallback, PackageCommands } from './plan'
 import { type CheckConfig, checkConfigSchema } from './schema'
 
 export const CONFIG_PATH = PROJECT_CONFIG_PATH
@@ -25,6 +25,8 @@ export type CheckSettings = {
   baseBranch: string
   /** Where the lane worktrees live, below the main checkout: a board's plans are read there too. */
   worktreeDirectory: string
+  /** Put before the kit's skill and agent names in this project; empty without one. */
+  skillPrefix: string
   /** What the lock files (without one, the manifests) decide: one stack, none, or several (ambiguous); `stackOf` reads the stack from it. */
   stack: StackDetection
   notes: string[]
@@ -33,11 +35,16 @@ export type CheckSettings = {
 /** The stack a detection decided, by lock file or manifest; null for none or several, where the check reads every stack's markers. */
 export const stackOf = (detection: StackDetection): Stack | null => (isDecided(detection) ? detection.stack : null)
 
+/** Without any detected stack: `check.roots` and the repository root `.` as fallback roots, `commands.lint` from the root. */
+export const noStackFallbackOf = ({ stack, check, commands }: CheckSettings): NoStackFallback | null =>
+  stack.kind === 'none' ? { roots: [...(check.roots ?? []), '.'], lintCommand: commands.lint } : null
+
 const commandsSchema = jackherdConfigSchema.shape.commands
 const planDirectorySchema = jackherdConfigSchema.shape.planDirectory
 const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
 const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
 const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
+const skillPrefixSchema = jackherdConfigSchema.shape.skillPrefix
 
 /**
  * The check runner's view of `.jackherd/config.json`: the shared `commands` block, `planDirectory`, `planLanguage` and `baseBranch` plus its own
@@ -47,14 +54,15 @@ const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
 export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckSettings => {
   const detected = withDetected(z.record(z.string(), z.unknown()).parse(raw), facts)
   const object = z.record(z.string(), z.unknown()).parse(detected.raw)
-  const { test, typecheck } = commandsSchema.parse(object.commands)
+  const { test, typecheck, lint } = commandsSchema.parse(object.commands)
   return {
-    commands: { test, typecheck },
+    commands: { test, typecheck, lint },
     check: checkConfigSchema.parse(object.check ?? {}),
     planDirectory: planDirectorySchema.parse(object.planDirectory),
     planLanguage: planLanguageSchema.parse(object.planLanguage),
     baseBranch: baseBranchSchema.parse(object.baseBranch),
     worktreeDirectory: worktreeDirectorySchema.parse(object.worktreeDirectory),
+    skillPrefix: skillPrefixSchema.parse(object.skillPrefix),
     stack: detectStack(facts.lockFiles, facts.manifests),
     notes: detected.notes,
   }

package/src/check/skill-budget-defaults.ts

@@ -21,18 +21,30 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/implement/SKILL.md': 2190,
   // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
   // Plain words: no plan code without its words in a short question.
-  '.claude/skills/orchestrate/SKILL.md': 7920,
+  // Any language: a pointer in § 0 and a section in events.md for `plan missing`.
+  // Open up: a pointer in § 0 to adopt-plan.md, and § 2 step 8 waits until the lane works on its prompt (+113);
+  // step 0 lets the adoption diff stand for its question, step 2 bases on origin only for an unchanged plan.
+  // Cross-check: measured in a repository whose stack nothing detects, every unset command renders as a note (+7).
+  // Ready phase: the `done` / `idle` row names the watcher's mandatory `ready:` line (+20).
+  // Drafts until the merge: § 5 step 5 opens a draft and readies it, Self-merge step 3 waits for the runs after it (+100).
+  '.claude/skills/orchestrate/SKILL.md': 8230,
+  // skill-review: the copy is taken after a mirror, and rejecting together with a remark is a remark (+36).
+  // Cross-check: an adopted plan also gets short names and a no-review-gate line, which `jh check` asks of a new
+  // plan; the proof became a word diff, since a short name goes into an existing line (+74); skill-review: the
+  // done check names `jh check`, the gate and short-name rules as the code reads them (+24).
+  '.claude/skills/orchestrate/references/adopt-plan.md': 680,
   '.claude/skills/orchestrate/references/acceptance.md': 200,
   '.claude/skills/orchestrate/references/close-lane.md': 250,
   '.claude/skills/orchestrate/references/coordinator-handover.md': 551,
   '.claude/skills/orchestrate/references/draft-review.md': 300,
   // P33: a source entry the user must read or decide becomes a row of what waits on them, and when it closes.
-  '.claude/skills/orchestrate/references/events.md': 1110,
+  '.claude/skills/orchestrate/references/events.md': 1166,
   '.claude/skills/orchestrate/references/herd.md': 299,
   '.claude/skills/orchestrate/references/lane-handover.md': 280,
   '.claude/skills/orchestrate/references/lane-session.md': 280,
   '.claude/skills/orchestrate/references/lane-setup.md': 380,
-  '.claude/skills/orchestrate/references/plan-commit.md': 330,
+  // Open up: an adopted plan is committed like a missing one, and a tracked copy is restored after the merge.
+  '.claude/skills/orchestrate/references/plan-commit.md': 350,
   '.claude/skills/orchestrate/references/sensitive-input.md': 269,
   '.claude/skills/plan/SKILL.md': 1920,
   '.claude/skills/plan/references/template-English.md': 536,
@@ -40,10 +52,11 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/pre-commit/SKILL.md': 1003,
   '.claude/skills/review/SKILL.md': 319,
   '.claude/skills/security-audit/SKILL.md': 519,
-  '.claude/skills/start/SKILL.md': 607,
+  // Any language: step 3 points to proposing the missing commands from the CI; the proposal itself is a reference.
+  '.claude/skills/start/SKILL.md': 630,
   '.claude/skills/uncle-bob/SKILL.md': 466,
-  // P33: grows with the skill above.
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8720,
+  // P33 and open up: grows with the skill above.
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8880,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,
@@ -54,6 +67,7 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/agents/spec-review.md': 1137,
   '.claude/agents/uncle-bob.md': 111,
   '.claude/rules/kit/code-style.md': 1664,
-  '.claude/rules/kit/pull-requests.md': 601,
+  // Drafts until the merge: a precondition opens a draft when `merge.openAsDraft` says so (+39).
+  '.claude/rules/kit/pull-requests.md': 640,
   '.claude/rules/kit/testing.md': 741,
 }

package/src/check/skill-budgets.ts

@@ -1,7 +1,9 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { CLAUDE_DIRECTORY, claudePath, SKILLS_DIRECTORY } from '../claude/paths'
+import { CLAUDE_DIRECTORY, claudePath, prefixedKitPath, SKILLS_DIRECTORY } from '../claude/paths'
 import { projectLockCandidates } from '../config/legacy-names'
+import { parseJsonOrNull } from '../shared/parse-json'
+import { readForeignSkills, SKILLS_LOCK_FILE, skillEntryPath, skillNameOfEntry } from '../sync/foreign-skills'
 import { parseManifest } from '../sync/manifest'
 import { matchesGlob } from './glob'
 import { CHECK_STATUS, type CheckResult, type CheckStatus } from './result'
@@ -17,9 +19,10 @@ import {
 export type BudgetTable = Readonly<SkillBudgets>
 
 /** A file with the budget it falls back on when neither the project nor the kit names one. */
-export type FileWords = { path: string; words: number; fallback: number }
+export type FileWords = { path: string; words: number; fallback: number; foreign?: boolean }
 
-export type Measurement = { label: string; words: number; budget: number }
+/** A `foreign` measurement belongs to a skill `skills-lock.json` lists: it warns, it never fails. */
+export type Measurement = { label: string; words: number; budget: number; foreign?: boolean }
 
 type Overrun = typeof CHECK_STATUS.warn | typeof CHECK_STATUS.fail
 
@@ -31,6 +34,7 @@ const KIT_RULE = /^rules\//
 const PATHS_IN_FRONTMATTER = /^---\r?\n(?:(?!---)[^\n]*\n)*?paths:/
 const SUM_SEPARATOR = ' + '
 const FAIL_FACTOR = 1.1
+const FOREIGN_LABEL = `(foreign, ${SKILLS_LOCK_FILE})`
 
 const OVERRUN_LABEL: Record<Overrun, string> = { warn: 'warning', fail: 'error' }
 
@@ -65,6 +69,23 @@ export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTab
   return project[path] ?? (glob === undefined ? undefined : project[glob]) ?? defaults[path] ?? fallback
 }
 
+/** Every budget path starts with `.claude/` (the kit-content test holds them to shipped files). */
+const prefixedPath = (path: string, prefix: string): string =>
+  claudePath(prefixedKitPath(path.slice(CLAUDE_DIRECTORY.length + 1), prefix))
+
+/** The kit's budgets under the paths a project with `skillPrefix` installs its skills and agents at; supplements keep theirs. */
+export const prefixedBudgets = (budgets: BudgetTable, prefix: string): BudgetTable =>
+  prefix === ''
+    ? budgets
+    : Object.fromEntries(
+        Object.entries(budgets).map(([key, words]) => [
+          budgetKeyPaths(key)
+            .map((path) => prefixedPath(path, prefix))
+            .join(SUM_SEPARATOR),
+          words,
+        ]),
+      )
+
 const sumEntry = (key: string, files: readonly FileWords[]): number | null => {
   const parts = budgetKeyPaths(key).map((part) => files.find((file) => file.path === part))
   return parts.every((part) => part !== undefined) ? parts.reduce((total, part) => total + part.words, 0) : null
@@ -76,10 +97,11 @@ export const measureFiles = (
   project: BudgetTable,
   defaults: BudgetTable,
 ): Measurement[] => {
-  const single = files.map(({ path, words, fallback }) => ({
-    label: path,
+  const single = files.map(({ path, words, fallback, foreign }) => ({
+    label: foreign ? `${path} ${FOREIGN_LABEL}` : path,
     words,
     budget: budgetOf(path, project, defaults, fallback),
+    foreign,
   }))
   const sums = [...new Set([...Object.keys(project), ...Object.keys(defaults)])]
     .filter((key) => key.includes(SUM_SEPARATOR))
@@ -90,6 +112,11 @@ export const measureFiles = (
   return [...single, ...sums]
 }
 
+const overrunOfMeasurement = ({ words, budget, foreign }: Measurement): Overrun | null => {
+  const overrun = overrunOf(words, budget)
+  return foreign && overrun === CHECK_STATUS.fail ? CHECK_STATUS.warn : overrun
+}
+
 const overrunLine = ({ entry: { label, words, budget }, overrun }: MeasuredOverrun): string =>
   `${OVERRUN_LABEL[overrun]}: ${label} has ${words} words, budget ${budget}`
 
@@ -104,7 +131,7 @@ const statusOf = (overruns: readonly MeasuredOverrun[]): CheckStatus => {
 /** One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %. */
 export const budgetResult = (measured: readonly Measurement[], durationMs: number): CheckResult => {
   const overruns = measured.flatMap((entry) => {
-    const overrun = overrunOf(entry.words, entry.budget)
+    const overrun = overrunOfMeasurement(entry)
     return overrun === null ? [] : [{ entry, overrun }]
   })
   return {
@@ -124,19 +151,11 @@ const readText = (path: string): string | null => {
   }
 }
 
-const parseJson = (text: string): unknown => {
-  try {
-    return JSON.parse(text)
-  } catch {
-    return null
-  }
-}
-
 /** The kit documents the first valid lock file lists, the lock under its old name counting while sync has not moved it. */
 const kitPathsOf = (root: string): string[] => {
   for (const candidate of projectLockCandidates(root)) {
     const text = readText(candidate)
-    const parsed = text === null ? null : parseManifest(parseJson(text))
+    const parsed = text === null ? null : parseManifest(parseJsonOrNull(text))
     if (parsed?.ok) return Object.keys(parsed.manifest.files).filter((key) => KIT_DOCUMENT.test(key))
   }
   return []
@@ -159,9 +178,17 @@ const kitFileWordsOf = (root: string, kitPath: string): FileWords[] => {
 
 const ownSkillPaths = (root: string, kit: ReadonlySet<string>): string[] =>
   listDirectory(join(root, CLAUDE_DIRECTORY, SKILLS_DIRECTORY))
-    .map((name) => claudePath(SKILLS_DIRECTORY, name, 'SKILL.md'))
+    .map((name) => claudePath(skillEntryPath(name)))
     .filter((path) => !kit.has(path))
 
+/** Marks the entry file of a skill `skills-lock.json` lists; any other file is left as it is. */
+const markForeign =
+  (foreign: ReadonlySet<string>) =>
+  (file: FileWords): FileWords => {
+    const name = skillNameOfEntry(file.path)
+    return name !== undefined && foreign.has(name) ? { ...file, foreign: true } : file
+  }
+
 const supplementPaths = (root: string): string[] =>
   listDirectory(join(root, CLAUDE_DIRECTORY, SUPPLEMENTS_DIRECTORY))
     .filter((name) => name.endsWith('.md'))
@@ -170,16 +197,19 @@ const supplementPaths = (root: string): string[] =>
 /**
  * The installed kit skills with their references, kit agents and kit rules that load every session (the lock file
  * says which files the kit installed), the project's supplements and its own skills, measured against the budgets.
+ * `skillPrefix` is the project's: the kit's budgets follow its skills and agents to their prefixed paths.
  * Null when there is nothing to measure.
  */
-export const skillBudgetCheck = (root: string, project: BudgetTable = {}): CheckResult | null => {
+export const skillBudgetCheck = (root: string, project: BudgetTable = {}, skillPrefix = ''): CheckResult | null => {
   const started = Date.now()
   const kitPaths = kitPathsOf(root)
   const kit = new Set(kitPaths.map((key) => claudePath(key)))
+  const foreign = readForeignSkills(root)
   const files = [
     ...kitPaths.flatMap((key) => kitFileWordsOf(root, key)),
     ...supplementPaths(root).flatMap((path) => fileWordsOf(root, path, SUPPLEMENT_BUDGET)),
     ...ownSkillPaths(root, kit).flatMap((path) => fileWordsOf(root, path, OWN_SKILL_BUDGET)),
-  ]
-  return files.length === 0 ? null : budgetResult(measureFiles(files, project, KIT_SKILL_BUDGETS), Date.now() - started)
+  ].map(markForeign(foreign))
+  const defaults = prefixedBudgets(KIT_SKILL_BUDGETS, skillPrefix)
+  return files.length === 0 ? null : budgetResult(measureFiles(files, project, defaults), Date.now() - started)
 }

package/src/claude/paths.ts

@@ -10,5 +10,17 @@ export const HANDOVER_DIRECTORY = 'handover'
 export const WORKTREES_DIRECTORY = 'worktrees'
 export const SESSION_LOGS_DIRECTORY = 'projects'
 
+/** A skill's file and an agent below `.claude/`, by name: `skills/<name>/<file>`, `agents/<name>.md`. */
+export const SKILL_PATH = new RegExp(`^${SKILLS_DIRECTORY}/([^/]+)/(.+)$`)
+export const AGENT_PATH = new RegExp(`^${AGENTS_DIRECTORY}/([^/]+)\\.md$`)
+
 /** `.claude/<directory>` as a path in a project and in a text that names it. */
 export const claudePath = (...segments: string[]): string => [CLAUDE_DIRECTORY, ...segments].join('/')
+
+/** A kit path below `.claude/` as a project with `skillPrefix` installs it: skills and agents prefixed, the rest as it is. */
+export const prefixedKitPath = (path: string, prefix: string): string => {
+  const skill = SKILL_PATH.exec(path)
+  if (skill) return `${SKILLS_DIRECTORY}/${prefix}${skill[1]}/${skill[2]}`
+  const agent = AGENT_PATH.exec(path)
+  return agent ? `${AGENTS_DIRECTORY}/${prefix}${agent[1]}.md` : path
+}

package/src/cli.ts

@@ -26,6 +26,7 @@ export const COMMANDS: CommandTable = {
   [HERD_COMMAND.alias]: () => import('./plans/command'),
   lane: () => import('./lane/command'),
   mermaid: () => import('./mermaid/command'),
+  plan: () => import('./plan-contract/command'),
   preview: () => import('./preview/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),