jackherd 1.15.2 → 1.17.0

package/src/check/schema.ts

@@ -68,6 +68,30 @@ const publicContent = z.strictObject({
 /** A budget in words per path or glob from the project root; a key joining two paths with ` + ` budgets them together. */
 const skillBudgets = z.record(glob, z.number().int().positive())
 
+/** What `jh check` does with open boxes in the phase a lane builds: fail, warn or leave the check out. */
+export const OPEN_BOXES_LEVEL = { fail: 'fail', warn: 'warn', off: 'off' } as const
+
+export type OpenBoxesLevel = (typeof OPEN_BOXES_LEVEL)[keyof typeof OPEN_BOXES_LEVEL]
+
+/** What `jh check` does with a lint-shaped rule block that names no lint rule: warn (the default), fail or leave the check out. */
+export const LINT_POINTERS_LEVEL = { warn: 'warn', fail: 'fail', off: 'off' } as const
+
+export type LintPointersLevel = (typeof LINT_POINTERS_LEVEL)[keyof typeof LINT_POINTERS_LEVEL]
+
+const lintPointers = z.strictObject({
+  /** `warn` reports a block and lets the commit through; `fail` stops it; `off` skips the check. */
+  level: z
+    .enum([LINT_POINTERS_LEVEL.warn, LINT_POINTERS_LEVEL.fail, LINT_POINTERS_LEVEL.off])
+    .default(LINT_POINTERS_LEVEL.warn),
+  /** Rule files left unread, as globs from the project root; the kit copies in the lock file are always left out. */
+  exclude: z.array(glob).default([]),
+})
+
+export type LintPointersConfig = z.infer<typeof lintPointers>
+
+/** The check without a `lintPointers` block: warn, nothing excluded. */
+export const DEFAULT_LINT_POINTERS: LintPointersConfig = { level: LINT_POINTERS_LEVEL.warn, exclude: [] }
+
 /**
  * The `check` block of `.jackherd/config.json`. Test and type commands come from the top-level
  * `commands` block; this block holds what only the check runner reads.
@@ -89,6 +113,19 @@ export const checkConfigSchema = z.strictObject({
    * path and sets one for the project's own skills; a file with none is measured against the kit's default.
    */
   skillBudgets: skillBudgets.optional(),
+  /**
+   * What a lane's check does when the phase its board row names still has open boxes without `→ P<n>`: `fail` (the
+   * default) stops the commit, `warn` reports, `off` skips. A row carrying the `partialPhase` word (`(Teil)` in German) builds part of the phase and is
+   * left alone; a branch whose directory is no lane's is not checked.
+   */
+  openBoxes: z
+    .enum([OPEN_BOXES_LEVEL.fail, OPEN_BOXES_LEVEL.warn, OPEN_BOXES_LEVEL.off])
+    .default(OPEN_BOXES_LEVEL.fail),
+  /**
+   * Whether a new or changed block of a rule file (or `CLAUDE.md`, `AGENTS.md`) that a linter could check, such
+   * as a forbidden import path or call, must name its lint rule with `` `lint:<rule id>` `` (or `` `lint:none` `` and a reason).
+   */
+  lintPointers: lintPointers.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
   looseTests: z.boolean().default(false),
   /**

package/src/check/settings.ts

@@ -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
+  /** Where the boards live: the directories under `planDirectory` and the file in each. */
+  board: { pattern: string; file: 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. */
@@ -45,6 +47,7 @@ const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
 const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
 const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
 const skillPrefixSchema = jackherdConfigSchema.shape.skillPrefix
+const boardSchema = jackherdConfigSchema.shape.board
 
 /**
  * The check runner's view of `.jackherd/config.json`: the shared `commands` block, `planDirectory`, `planLanguage` and `baseBranch` plus its own
@@ -62,6 +65,7 @@ export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckS
     planLanguage: planLanguageSchema.parse(object.planLanguage),
     baseBranch: baseBranchSchema.parse(object.baseBranch),
     worktreeDirectory: worktreeDirectorySchema.parse(object.worktreeDirectory),
+    board: boardSchema.parse(object.board),
     skillPrefix: skillPrefixSchema.parse(object.skillPrefix),
     stack: detectStack(facts.lockFiles, facts.manifests),
     notes: detected.notes,

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

@@ -8,44 +8,61 @@ export const KIT_FILE_FALLBACK_BUDGET = 2000
 export const SUPPLEMENT_BUDGET = 800
 
 /**
- * The kit's word budgets, by path from the project root. A key joining two paths with ` + ` budgets what is
- * loaded together. A budget is the measured size plus at most 10 %, so a file has room for a sentence, not for a
- * section; a file that needs more justifies the growth where it raises the number.
+ * The kit's word targets, by path from the project root: the size a file should have, not the size it has. A key
+ * joining two paths with ` + ` targets what is loaded together. A file above its target carries a ceiling in
+ * `KIT_SKILL_CEILINGS`; growth never moves a target.
  */
-export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
+export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   '.claude/skills/devops/SKILL.md': 321,
   '.claude/skills/diagnose/SKILL.md': 1521,
   '.claude/skills/diagnose/references/feedback-loops.md': 636,
-  '.claude/skills/follow/SKILL.md': 1100,
+  // Personal sources: where the source lives, the secret step that keeps the value out of the agent, the personal
+  // file and its script path, what a reload prints (+295); skill-review: a personal source stores its secret and is
+  // dry-run by name after the entry is written, since a draft runs without the keychain (+103).
+  '.claude/skills/follow/SKILL.md': 1498,
   '.claude/skills/grill/SKILL.md': 685,
   '.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.
-  // 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,
+  '.claude/skills/orchestrate/SKILL.md': 4500,
   // 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,
+  // Core cut: the `due` row of the wake-up table moved here (+33).
+  '.claude/skills/orchestrate/references/appointments.md': 290,
+  // Resume: `--branch` finishes a lane whose worktree is gone, a detached worktree on the base closes, a closed lane
+  // is reported (+41). The ask rule is the one question: the coordinator asks no dialog before it (+15).
+  '.claude/skills/orchestrate/references/close-lane.md': 309,
+  '.claude/skills/orchestrate/references/coordinator-handover.md': 567,
   '.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': 1166,
+  // Core cut: the `deploy`, `stalled` and lane `warn` rows of the wake-up table moved here (+101), and the checks
+  // after `Nothing changed.` from `jh check` (+70 as rendered), and the board patch when `main checkout behind`
+  // cannot fast-forward (+60). skill-review: `lane removed`, `no longer listed`, `did not stop` and
+  // `herd --ensure failed`, whose lines the watcher already points here (+86).
+  '.claude/skills/orchestrate/references/events.md': 1491,
   '.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/herd-ask.md': 152,
+  // Core cut: the request on `lane alert` moved here (+56); ending a lane names `herdr agent prompt <lane> /exit`,
+  // the form the merge guard passes (+23).
+  '.claude/skills/orchestrate/references/lane-handover.md': 360,
+  // Ending the agent names `herdr agent prompt <lane> /exit`, the form the merge guard passes (+25).
+  '.claude/skills/orchestrate/references/lane-session.md': 285,
   '.claude/skills/orchestrate/references/lane-setup.md': 380,
   // 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,
+  // Core cut: the question of § 2 step 0 (the adoption's diff round, the approval it is, `<topic>`, a no) (+60).
+  '.claude/skills/orchestrate/references/plan-commit.md': 412,
+  // Core cut: § 5 self-merge steps 1 to 6, moved out of the core.
+  '.claude/skills/orchestrate/references/self-merge.md': 379,
   '.claude/skills/orchestrate/references/sensitive-input.md': 269,
+  '.claude/skills/orchestrate/references/stage-approval.md': 634,
+  '.claude/skills/orchestrate/references/standing-approval.md': 458,
+  // Core cut: § 2 steps 0 to 8 and § 3 dev server, moved out of the core.
+  '.claude/skills/orchestrate/references/start-lane.md': 712,
+  // Core cut: § 4 waiting rows beyond the basic one, moved out of the core.
+  '.claude/skills/orchestrate/references/waiting.md': 216,
+  '.claude/skills/orchestrate/references/watch-without-monitor.md': 154,
   '.claude/skills/plan/SKILL.md': 1920,
   '.claude/skills/plan/references/template-English.md': 536,
   '.claude/skills/plan/references/template-German.md': 501,
@@ -55,8 +72,7 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   // 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 and open up: grows with the skill above.
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8880,
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 5100,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,
@@ -66,8 +82,50 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/agents/skill-review.md': 468,
   '.claude/agents/spec-review.md': 1137,
   '.claude/agents/uncle-bob.md': 111,
-  '.claude/rules/kit/code-style.md': 1664,
+  // Lint before prose: the vocabulary section and two one-liners cut, a sentence on `lint:` pointers added (-79).
+  '.claude/rules/kit/code-style.md': 1585,
   // 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,
 }
+
+/**
+ * The most a file above its target may have, today's size. A ceiling only falls: the plan that cuts the file lowers
+ * or deletes it, and a rise needs a reason in the comment above the entry (a test holds every entry to one).
+ */
+export const KIT_SKILL_CEILINGS: Readonly<Record<string, number>> = {
+  // Orchestrate core plan P1: the reviewer also judges the whole length of a file against its target (+12).
+  // Lint before prose: lens 7 for lint-shaped prose and the sentence on the `Lint pointers` result (+33).
+  '.claude/agents/skill-review.md': 513,
+  // Lint before prose: the quality check that asks of every written rule whether the linter can check it (+44).
+  '.claude/skills/plan/SKILL.md': 1964,
+  // 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.
+  // 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).
+  // Ready round: a PR of the lane waiting for approval or merge holds only the commit; the self-merge command runs
+  // alone, so the guard can check it (+132, the longest rendering of the kit's renderings); skill-review: the commit
+  // of a PR awaiting approval stages only its files, a branch over a squash-merged PR moves with `--onto` (+51).
+  // Change id: the PR question names the staged change's patch id, which the merge guard compares; skill-review:
+  // staging first and the worktree named (+55, to cut again).
+  // Bundled board lines: written into the main checkout at once, carried to the base bundled, and the fast-forward
+  // that keeps them (+115).
+  // Audit P6: commands and hooks carry rules the prose repeated; monitorless watching, appointments, the standing
+  // approval and the herd's ask line moved to references. Cut to the measured size plus 5 %.
+  // Orchestrate core plan P1: the target is 4500. P5 cut the core to its longest rendering; the rest of the cut is
+  // a follow-up, decided by the user after the P6 runs.
+  '.claude/skills/orchestrate/SKILL.md': 5938,
+  // P33 and open up: grows with the skill above (+132 for the ready round and the lone merge call); measured with
+  // this repository's supplement after the skill-review fixes (+153); click merge grows with the skill (+30); change
+  // id grows with the skill, staging first and the worktree named after skill-review (+55). Audit P6: cut with the
+  // skill, the supplement down to its deviations; measured size plus 5 %.
+  // Orchestrate core plan P1: the target is 5100; P5 lowered the ceiling with the skill's to the rendered sum.
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 6635,
+}
+
+/** What `jh check` measures against: a file's ceiling where it has one, else its target. */
+export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = { ...KIT_SKILL_TARGETS, ...KIT_SKILL_CEILINGS }

package/src/check/skill-budgets.ts

@@ -11,6 +11,7 @@ import type { SkillBudgets } from './schema'
 import {
   KIT_FILE_FALLBACK_BUDGET,
   KIT_SKILL_BUDGETS,
+  KIT_SKILL_TARGETS,
   OWN_SKILL_BUDGET,
   SUPPLEMENT_BUDGET,
 } from './skill-budget-defaults'
@@ -21,8 +22,18 @@ 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; foreign?: boolean }
 
-/** 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 }
+/**
+ * A `foreign` measurement belongs to a skill `skills-lock.json` lists: it warns, it never fails. `target` is the
+ * kit's target for the path, `projectBudget` is the project's own entry for the path.
+ */
+export type Measurement = {
+  label: string
+  words: number
+  budget: number
+  foreign?: boolean
+  target?: number
+  projectBudget?: number
+}
 
 type Overrun = typeof CHECK_STATUS.warn | typeof CHECK_STATUS.fail
 
@@ -63,12 +74,16 @@ export const overrunOf = (words: number, budget: number): Overrun | null => {
   return words > budget ? CHECK_STATUS.warn : null
 }
 
-/** The project's entry for the exact path, else its first glob that matches, else the kit's default, else `fallback`. */
-export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTable, fallback: number): number => {
+/** The project's entry for the exact path, else its first glob that matches; undefined when it names neither. */
+const projectBudgetOf = (path: string, project: BudgetTable): number | undefined => {
   const glob = Object.keys(project).find((key) => isGlob(key) && matchesGlob(path, key))
-  return project[path] ?? (glob === undefined ? undefined : project[glob]) ?? defaults[path] ?? fallback
+  return project[path] ?? (glob === undefined ? undefined : project[glob])
 }
 
+/** The project's entry for the exact path, else its first glob that matches, else the kit's default, else `fallback`. */
+export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTable, fallback: number): number =>
+  projectBudgetOf(path, project) ?? 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))
@@ -91,23 +106,39 @@ const sumEntry = (key: string, files: readonly FileWords[]): number | null => {
   return parts.every((part) => part !== undefined) ? parts.reduce((total, part) => total + part.words, 0) : null
 }
 
-/** Every file against its budget, then every sum entry of the project and the kit whose files all exist. */
+/**
+ * Every file against its budget, then every sum entry of the project and the kit whose files all exist. `targets`
+ * are the kit's targets by path; a measurement carries its own when the kit names one.
+ */
 export const measureFiles = (
   files: readonly FileWords[],
   project: BudgetTable,
   defaults: BudgetTable,
+  targets: BudgetTable = {},
 ): Measurement[] => {
   const single = files.map(({ path, words, fallback, foreign }) => ({
     label: foreign ? `${path} ${FOREIGN_LABEL}` : path,
     words,
     budget: budgetOf(path, project, defaults, fallback),
     foreign,
+    target: targets[path],
+    projectBudget: projectBudgetOf(path, project),
   }))
   const sums = [...new Set([...Object.keys(project), ...Object.keys(defaults)])]
     .filter((key) => key.includes(SUM_SEPARATOR))
     .flatMap((key) => {
       const words = sumEntry(key, files)
-      return words === null ? [] : [{ label: key, words, budget: budgetOf(key, project, defaults, 0) }]
+      return words === null
+        ? []
+        : [
+            {
+              label: key,
+              words,
+              budget: budgetOf(key, project, defaults, 0),
+              target: targets[key],
+              projectBudget: projectBudgetOf(key, project),
+            },
+          ]
     })
   return [...single, ...sums]
 }
@@ -128,17 +159,33 @@ const statusOf = (overruns: readonly MeasuredOverrun[]): CheckStatus => {
   return overruns.length > 0 ? CHECK_STATUS.warn : CHECK_STATUS.pass
 }
 
-/** One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %. */
+/** A file within the kit's ceiling but above the kit's target for it: a hint, never a failure. A project budget has its note instead. */
+const targetHint = ({ label, words, budget, target, projectBudget }: Measurement): string[] =>
+  target !== undefined && projectBudget === undefined && words > target && budget > target
+    ? [`hint: ${label} is over target by ${words - target} words (target ${target}, ceiling ${budget})`]
+    : []
+
+/** A budget the project set above the kit's target for the path: shown, so the deviation stays visible. */
+const overrideNote = ({ label, target, projectBudget }: Measurement): string[] =>
+  target !== undefined && projectBudget !== undefined && projectBudget > target
+    ? [`note: ${label} budget ${projectBudget} comes from the project, above the kit target ${target}`]
+    : []
+
+/**
+ * One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %.
+ * Lines for a file over its target and for a project budget above the kit target follow, and change no status.
+ */
 export const budgetResult = (measured: readonly Measurement[], durationMs: number): CheckResult => {
   const overruns = measured.flatMap((entry) => {
     const overrun = overrunOfMeasurement(entry)
     return overrun === null ? [] : [{ entry, overrun }]
   })
+  const lines = overruns.length > 0 ? overruns.map(overrunLine) : [withinLine(measured.length)]
   return {
     name: 'Skill budgets',
     command: `${measured.length} measured, words per budget`,
     status: statusOf(overruns),
-    detail: overruns.map(overrunLine).join('\n') || withinLine(measured.length),
+    detail: [...lines, ...measured.flatMap(targetHint), ...measured.flatMap(overrideNote)].join('\n'),
     durationMs,
   }
 }
@@ -211,5 +258,6 @@ export const skillBudgetCheck = (root: string, project: BudgetTable = {}, skillP
     ...ownSkillPaths(root, kit).flatMap((path) => fileWordsOf(root, path, OWN_SKILL_BUDGET)),
   ].map(markForeign(foreign))
   const defaults = prefixedBudgets(KIT_SKILL_BUDGETS, skillPrefix)
-  return files.length === 0 ? null : budgetResult(measureFiles(files, project, defaults), Date.now() - started)
+  const targets = prefixedBudgets(KIT_SKILL_TARGETS, skillPrefix)
+  return files.length === 0 ? null : budgetResult(measureFiles(files, project, defaults, targets), Date.now() - started)
 }

package/src/cli.ts

@@ -18,6 +18,7 @@ const ALIASES = new Set<string>([HERD_COMMAND.alias])
 
 /** One line per command; each entry lazily imports the module that exports its `run`. */
 export const COMMANDS: CommandTable = {
+  approval: () => import('./approval/command'),
   check: () => import('./check/command'),
   config: () => import('./config/command'),
   context: () => import('./context/command'),
@@ -28,6 +29,7 @@ export const COMMANDS: CommandTable = {
   mermaid: () => import('./mermaid/command'),
   plan: () => import('./plan-contract/command'),
   preview: () => import('./preview/command'),
+  resume: () => import('./resume/command'),
   secret: () => import('./secrets/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),

package/src/config/personal-sources.ts

@@ -4,40 +4,68 @@ import { errorMessage } from '../sync/error-message'
 import { SOURCE_ORIGIN, type SourceOrigin, type SourceSettings } from '../watch/sources'
 import { personalSourcesPath } from './location'
 import { readResolvedConfig } from './read-config'
+import { isRepositoryIn } from './repository-identity'
 import { parsePersonalSourcesFile } from './schema'
 
-export type MergedSources = { sources: SourceSettings[]; notes: string[] }
+/** Why a personal source with `repos` does not run in this repository. */
+export const EXCLUDED_REASON = { otherRepository: 'not for this repo', noOrigin: 'no origin' } as const
+
+export type ExcludedReason = (typeof EXCLUDED_REASON)[keyof typeof EXCLUDED_REASON]
+
+/** A personal source left out because of its `repos`, kept so `jh secret list` and the dry run can still name it. */
+export type ExcludedSource = { source: SourceSettings; reason: ExcludedReason }
+
+export type MergedSources = { sources: SourceSettings[]; notes: string[]; excluded: ExcludedSource[] }
 
 /** What a note starts with when an invalid personal file was left out. */
 export const PERSONAL_IGNORED = 'personal sources ignored:'
 
 const skippedPrefix = (name: string): string => `personal source ${name} in `
 
+const excludedPrefix = (name: string): string => `${name}: `
+
 const skippedNote = (name: string, path: string): string =>
   `${skippedPrefix(name)}${path} skipped: the repository has a source of that name`
 
-/** Whether a merge note concerns the source `name`: the personal source of that name was skipped, or the file was ignored. */
+/** The note for a source left out for its `repos`: `<name>: not for this repo` or `<name>: no origin`. */
+export const excludedNote = ({ source, reason }: ExcludedSource): string => `${excludedPrefix(source.name)}${reason}`
+
+/** Whether a merge note concerns the source `name`: the personal source of that name was skipped or left out for its `repos`, or the file was ignored. */
 export const isNoteAbout = (note: string, name: string): boolean =>
-  note.startsWith(skippedPrefix(name)) || note.startsWith(PERSONAL_IGNORED)
+  note.startsWith(skippedPrefix(name)) || note.startsWith(excludedPrefix(name)) || note.startsWith(PERSONAL_IGNORED)
 
 const withOrigin = (sources: readonly SourceSettings[], origin: SourceOrigin): SourceSettings[] =>
   sources.map((source) => ({ ...source, origin }))
 
+const exclusionOf = (source: SourceSettings, repository: string | null): ExcludedReason | null => {
+  if (source.repos === undefined || isRepositoryIn(repository, source.repos)) return null
+  return repository === null ? EXCLUDED_REASON.noOrigin : EXCLUDED_REASON.otherRepository
+}
+
 /**
  * The repository's sources, then the personal ones, each marked with its origin. A personal source whose name a
- * repository source has is left out and named in a note; `path` is how the notes spell the personal file.
+ * repository source has is left out and named in a note, and so is one whose `repos` do not list `repository`
+ * (`owner/name` of this checkout's origin, null without one); `path` is how the notes spell the personal file.
  */
 export const mergedSources = (
   repo: readonly SourceSettings[],
   personal: readonly SourceSettings[],
   path: string,
+  repository: string | null,
 ): MergedSources => {
   const repoNames = new Set(repo.map(({ name }) => name))
-  const kept = personal.filter(({ name }) => !repoNames.has(name))
+  const unclashed = personal.filter(({ name }) => !repoNames.has(name))
   const skipped = personal.filter(({ name }) => repoNames.has(name))
+  const excluded = withOrigin(unclashed, SOURCE_ORIGIN.personal).flatMap((source): ExcludedSource[] => {
+    const reason = exclusionOf(source, repository)
+    return reason === null ? [] : [{ source, reason }]
+  })
+  const left = new Set(excluded.map(({ source }) => source.name))
+  const kept = unclashed.filter(({ name }) => !left.has(name))
   return {
     sources: [...withOrigin(repo, SOURCE_ORIGIN.repo), ...withOrigin(kept, SOURCE_ORIGIN.personal)],
-    notes: skipped.map(({ name }) => skippedNote(name, path)),
+    notes: [...skipped.map(({ name }) => skippedNote(name, path)), ...excluded.map(excludedNote)],
+    excluded,
   }
 }
 
@@ -64,14 +92,19 @@ export const readPersonalSources = (
  */
 export const sourcesWithPersonal = (
   repo: readonly SourceSettings[],
+  repository: string | null,
   home: string = homedir(),
   exists: (path: string) => boolean = existsSync,
   readText?: (path: string) => string,
 ): MergedSources => {
   try {
-    return mergedSources(repo, readPersonalSources(home, exists, readText), personalSourcesPath(home))
+    return mergedSources(repo, readPersonalSources(home, exists, readText), personalSourcesPath(home), repository)
   } catch (error) {
-    return { sources: withOrigin(repo, SOURCE_ORIGIN.repo), notes: [`${PERSONAL_IGNORED} ${errorMessage(error)}`] }
+    return {
+      sources: withOrigin(repo, SOURCE_ORIGIN.repo),
+      notes: [`${PERSONAL_IGNORED} ${errorMessage(error)}`],
+      excluded: [],
+    }
   }
 }
 
@@ -79,5 +112,8 @@ export const sourcesWithPersonal = (
  * The sources of the project config of the first of `roots` that has one (`readResolvedConfig`), with the personal
  * ones of `home` merged in; throws like `readResolvedConfig` when the project config is missing or invalid.
  */
-export const configuredSources = (roots: string[], home: string = homedir()): MergedSources =>
-  sourcesWithPersonal(readResolvedConfig(roots, home).config.watch.sources, home)
+export const configuredSources = (
+  roots: string[],
+  repository: string | null,
+  home: string = homedir(),
+): MergedSources => sourcesWithPersonal(readResolvedConfig(roots, home).config.watch.sources, repository, home)

package/src/config/repository-identity.ts

@@ -0,0 +1,40 @@
+/** `owner/name` as `repos` spells a repository. */
+export const REPOSITORY_NAME = /^[\w.-]+\/[\w.-]+$/
+
+const SCP_REMOTE = /^[\w.-]+@[\w.-]+:([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/
+
+/** `owner/name` of a URL path with exactly those two segments; a deeper or shorter path names no repository of ours. */
+const ownerAndName = (path: string): string | null => {
+  const segments = path
+    .replace(/\.git\/?$/, '')
+    .split('/')
+    .filter((segment) => segment !== '')
+  return segments.length === 2 ? segments.join('/') : null
+}
+
+/**
+ * `owner/name` of a git remote URL: `git@host:owner/name(.git)`, `https://host/owner/name(.git)` (credentials
+ * allowed) and `ssh://git@host(:port)/owner/name(.git)`. Null for anything else: a local path, a `file://` URL, a
+ * path with more or fewer than two segments.
+ */
+export const repositoryOf = (remoteUrl: string): string | null => {
+  const remote = remoteUrl.trim()
+  const scp = SCP_REMOTE.exec(remote)
+  if (scp) return `${scp[1]}/${scp[2]}`
+  try {
+    const url = new URL(remote)
+    return ['https:', 'http:', 'ssh:'].includes(url.protocol) ? ownerAndName(url.pathname) : null
+  } catch {
+    return null
+  }
+}
+
+/** Whether `repository` is one of `repos`; GitHub names compare without regard to case. A repository nobody could name is in none. */
+export const isRepositoryIn = (repository: string | null, repos: readonly string[]): boolean =>
+  repository !== null && repos.some((repo) => repo.toLowerCase() === repository.toLowerCase())
+
+/** The repository the checkout at `root` pushes to (`origin`), null without a git repository, an origin or a URL `repositoryOf` knows. */
+export const readRepositoryIdentity = (root: string): string | null => {
+  const result = Bun.spawnSync(['git', '-C', root, 'remote', 'get-url', 'origin'], { stdout: 'pipe', stderr: 'ignore' })
+  return result.exitCode === 0 ? repositoryOf(result.stdout.toString()) : null
+}

package/src/config/schema.ts

@@ -12,12 +12,16 @@ import { DEFAULT_BASE_BRANCH } from './base-branch'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
 import { isRepositoryDirectory } from './repository-directory'
+import { REPOSITORY_NAME } from './repository-identity'
 import { DEFAULT_TONES, TONE_NAMES } from './tones'
 
 export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
 
 export type TerminalAdapter = (typeof TERMINAL_ADAPTER)[keyof typeof TERMINAL_ADAPTER]
 
+/** The environments a standing approval may cover; production is never one. */
+export const STANDING_ENVIRONMENT = { stage: 'stage' } as const
+
 // TODO: draft role list taken from the agents the kit ships; confirm it before more kit files render model
 // IDs per role.
 export const MODEL_ROLE = {
@@ -302,6 +306,16 @@ const sourceSchema = z
       .optional(),
     /** `entries` shows the source's entries open, in a herd block of its own; not for a ticket source, whose entries are badges. */
     show: z.literal(SOURCE_SHOW.entries).optional(),
+    /**
+     * `owner/name` of the repositories a personal source runs in (matched without regard to case); without it every
+     * repository. Only in the personal sources file: the repository's own config is for that repository already.
+     */
+    repos: z
+      .array(z.string().regex(REPOSITORY_NAME, 'owner/name, such as acme/tool'))
+      .min(1)
+      .max(20)
+      .refine((repos) => new Set(repos.map((repo) => repo.toLowerCase())).size === repos.length, 'repos must be unique')
+      .optional(),
   })
   .refine(canChange, {
     message: 'map needs updatedAt, a content field (title, author, body, url) or reportOn',
@@ -327,6 +341,22 @@ const sourceSchema = z
 const hasUniqueNames = (sources: readonly { name: string }[]): boolean =>
   new Set(sources.map(({ name }) => name)).size === sources.length
 
+/** The sources of the repository's own config: none may name `repos`, which only a personal source has. */
+const repositorySources = z
+  .array(sourceSchema)
+  .refine(hasUniqueNames, 'source names must be unique')
+  .superRefine((sources, context) => {
+    sources.forEach((source, index) => {
+      if (source.repos === undefined) return
+      context.addIssue({
+        code: 'custom',
+        path: [index, 'repos'],
+        message:
+          'repos belongs in the personal sources file (~/.jackherd/sources.json): this config is for one repository',
+      })
+    })
+  })
+
 const coordinatorSchema = z
   .strictObject({
     /** Tokens in the coordinator's context from which the watcher reports `coordinator warn`. */
@@ -336,6 +366,18 @@ const coordinatorSchema = z
   })
   .refine(warnBelowAlert, WARN_BELOW_ALERT)
 
+/**
+ * An SQL tool of an MCP server by its full name (`mcp__<server>__execute_sql`), never one whose name says `prod`. The
+ * approval gate hook applies the same rule (`kit/hooks/hooks/approval-gate/settings.ts`), which cannot import this.
+ */
+const standingTool = z
+  .string()
+  .regex(
+    /^mcp__[A-Za-z0-9_-]+__execute_sql$/,
+    'a full MCP tool name ending in execute_sql, such as mcp__<server>__execute_sql',
+  )
+  .refine((name) => !/prod/i.test(name), 'a tool whose name says prod never runs under a standing approval')
+
 /** A guarded command as words: a program and one to three plain words after it, never an option, a quote or a shell character. */
 const guardedCommand = z
   .string()
@@ -420,6 +462,14 @@ const guardFields = z.strictObject({
     .strictObject({
       /** How long the approval gate hook holds a lane's call for the coordinator's dialog before it denies it; below the hook's 10 minutes. */
       waitMinutes: z.number().int().min(1).max(9).default(8),
+      /**
+       * The calls a standing approval of the user may let through once the coordinator marked them checked: each tool
+       * by its full name and the environment it writes to, only `stage`. A tool whose name says `prod` is refused, as the
+       * hook refuses it under a broken config; which project a server reaches is the project's start script's to say.
+       */
+      standing: z
+        .strictObject({ tools: z.record(standingTool, z.enum(Object.values(STANDING_ENVIRONMENT))) })
+        .optional(),
     })
     .prefault({}),
   /**
@@ -531,6 +581,8 @@ export const jackherdConfigSchema = z.strictObject({
       copy: z.array(laneCopyPath).default([]),
       /** The dependency lock file a rebase takes from the base branch and regenerates, never merges by hand; detected from the repository when left out. */
       lockFile: lockFilePath.optional(),
+      /** Free gigabytes the disk must hold before `jh lane space` lets a new lane install its dependencies; 5 when left out. */
+      minFreeGb: z.number().positive().optional(),
     })
     .prefault({}),
   models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),
@@ -582,7 +634,7 @@ export const jackherdConfigSchema = z.strictObject({
       parallelTasks: parallelTasksSchema.prefault({}),
       taskSignalMinutes: z.number().int().positive().default(DEFAULT_TASK_SIGNAL_MINUTES),
       previews: previewsSchema.optional(),
-      sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
+      sources: repositorySources.default([]),
     })
     .prefault({}),
   /** Read by the merge guard hook, which asks before the listed commands run, and by `/orchestrate`. */