jackherd 1.14.0 → 1.15.0

package/kit/workflow/skills/orchestrate/handover/index.ts

@@ -25,6 +25,9 @@ const EXIT = { done: 0, aborted: 1, usage: 2 } as const
 
 const ABORT_TITLE = 'Hand-over aborted'
 
+/** As SKILL.md § 2 step 8: herdr reports a line left as a paste (`agent_prompt_stalled`) instead of taking it. */
+const CONFIRM_WORKING = ['--wait', '--until', 'working', '--timeout', '30000']
+
 const herdr = async (args: string[]): Promise<HerdrResult> => {
   try {
     const child = Bun.spawn(['herdr', ...args], { stdout: 'pipe', stderr: 'pipe' })
@@ -58,7 +61,10 @@ const sleep = (milliseconds: number): Promise<void> => new Promise((resolve) =>
 
 type Log = (line: string) => Promise<void>
 
-/** Returns the reason of a failed herdr call, or null once `/clear` went out. */
+/**
+ * Returns the reason of a failed herdr call, or null once `/clear` went out. No `--wait`: `/clear` never turns
+ * the agent `working`, and the wait for a new session confirms it.
+ */
 const sendClear = async (options: HandoverOptions, log: Log): Promise<string | null> => {
   const cleared = await herdr(['agent', 'prompt', options.pane, '/clear'])
   if (!cleared.ok) return `herdr agent prompt /clear failed: ${cleared.error}`
@@ -98,7 +104,7 @@ const sendCommand = async (rename: string | null, options: HandoverOptions, log:
     const renamed = await herdr(['agent', 'rename', options.pane, rename])
     await log(renamed.ok ? `renamed the agent to ${rename}` : `rename to ${rename} failed: ${renamed.error}`)
   }
-  const sent = await herdr(['agent', 'prompt', options.pane, line.line])
+  const sent = await herdr(['agent', 'prompt', options.pane, line.line, ...CONFIRM_WORKING])
   if (!sent.ok) return `herdr agent prompt failed: ${sent.error}`
   await log(`sent: ${line.line}`)
   return null

package/kit/workflow/skills/orchestrate/references/adopt-plan.md

@@ -0,0 +1,51 @@
+# § 0: adopt a plan that misses the contract
+
+Read when `jh plan check <plan>` exits 1 for a plan a starting lane links, or when the lane's row links an issue
+or a `.scratch/<feature>/` folder instead of a plan file. The contract is `docs/plan-contract.md` in the jackherd
+package; the check's lines name each gap with `file:line`.
+
+**You add, the author's text stays.** Every word the plan holds stays, in its place: you insert lines, and into
+an open task line only its short name. Done when `jh plan check <plan>` exits 0, `jh check` names no line of
+`<plan>`, and `git diff --no-index --word-diff=porcelain <copy> <plan>` shows no line opening with `-` apart from
+its `--- a/…` header (its exit 1 only means a difference).
+
+## A plan in an issue tracker
+
+A plan that lives only in issues (a spec with its tickets in GitHub or GitLab, or Markdown under
+`.scratch/<feature>/`) is mirrored first, to `{{kit.planDirectory}}/<YYYY-MM-DD>-<topic>.md` with the date from
+`date`. Read it with `gh issue view <n> --comments`, `glab issue view <n> --comments` or `Read`, and copy the
+spec and each ticket's text as it stands, under a heading per ticket. The origin line under the title links the
+issue or the folder; done when each ticket's text reads in the file as in the issue. From then on the file is the one source: the board row links it, and nothing is written back
+to the issue. Then adopt the file like any other plan.
+
+## The additions
+
+Before the first addition (a mirrored plan: right after the mirror, so the diff shows only additions), run `mktemp`, keep the path it prints as `<copy>`, then `cp <plan> <copy>`. Then add only
+what the check's lines name as missing or malformed, in the plan language's headings, and the short names and the
+no-gate line, which `jh check` asks of a plan the commit adds:
+
+- **Phases**: a heading `### {{kit.heading.phase}} <id>: <title>` above each section or ticket that is one
+  piece of work, ids counting from 1 in the plan's order. A heading in a form the check does not read keeps its
+  line; the readable heading goes on the line below it.
+- **Tasks**: in a phase without checkboxes, a list at its end built from the lists and steps it already has, one
+  `- [ ] **Name**: …` per item, the name 40 characters at most and naming the result.
+- **Model**: one row per phase without one, appended to `### {{kit.heading.modelRecommendations}}`, or that
+  table placed before the first phase, each row judged as `/plan` judges it (its model recommendations); the
+  rationale cell names the error cost.
+- **Dependencies**, from two phases on: `### {{kit.heading.dependencies}}` with `{{kit.heading.dependsOn}}`
+  (the previous phase unless the plan says otherwise), `{{kit.heading.writes}}` estimated from the code the phase
+  names (search for its modules and files) and `{{kit.heading.serialMarker}}`.
+- **Short names**: an open task `- [ ] <text>` of a phase, before its review gate, without one gets `**<name>**: `
+  after its box, the name taken from its text, 40 characters at most.
+- **No review gate**: a phase with checkboxes and no line opening `**Review gate` (`de`: `**Review-Gate`) gets a
+  line after its tasks, in the plan's language:
+  `**No review gate:** adopted plan, the source planned no review` (`en`), `**Kein Review-Gate:** übernommener
+  Plan, die Quelle plante kein Review` (`de`).
+
+## The user sees the diff
+
+Write the output of `git diff --no-index <copy> <plan>` into `.claude/handover/adopt-<topic>.md` as a `diff` code block, its fence longer than any run of backticks in it, and show it as
+[`draft-review.md`](draft-review.md) says. The round's question is the one of § 2 step 0: its first option
+approves the additions together with the commit, the push and the documentation PR; each remark is an option of
+its own and leads to another round; one option rejects the additions, and it stops this plan's lanes as in
+step 0. Rejecting chosen together with another option counts as a remark.

package/kit/workflow/skills/orchestrate/references/plan-commit.md

@@ -1,7 +1,7 @@
 # § 2 step 0 and § 6: the plan commit as the base
 
-Read when § 0 finds the board or a plan missing on `origin/{{kit.baseBranch}}` and the user said yes to the
-plan commit, and again when its documentation PR has merged (§ 6).
+Read when § 0 finds the board or a plan missing on `origin/{{kit.baseBranch}}`, or adopted one, and the user
+said yes to the plan commit, and again when its documentation PR has merged (§ 6).
 
 ## The commit
 
@@ -13,7 +13,7 @@ Bash call of its own:
 git worktree add {{kit.worktreeDirectory}}/docs-plan-<topic> -b docs/plan-<topic> origin/{{kit.baseBranch}}
 ```
 
-1. From the main checkout, per missing file: `mkdir -p {{kit.worktreeDirectory}}/docs-plan-<topic>/<directory>`,
+1. From the main checkout, per missing or adopted file: `mkdir -p {{kit.worktreeDirectory}}/docs-plan-<topic>/<directory>`,
    then `cp <path> {{kit.worktreeDirectory}}/docs-plan-<topic>/<path>`. For `plan missing` while a lane
    works, copy from the lane's worktree instead (`<lane worktree>/<path>`): the main checkout lacks it.
 2. `cd` into the temporary worktree, as a command of its own (the kit's git guard refuses `git -C`).
@@ -28,8 +28,8 @@ The copies in the main checkout stay until the PR is merged.
 
 The lanes rebase on `origin/{{kit.baseBranch}}` as after every merge. Then, after `git fetch origin {{kit.baseBranch}}`,
 compare each copy in the main checkout with the merged file
-(`git show origin/{{kit.baseBranch}}:<path> | cmp -s - <path>`, one per file; read-only) and remove the copies
-that are equal, so the next update of the main checkout does not stop on them. A board that only gained lane
+(`git show origin/{{kit.baseBranch}}:<path> | cmp -s - <path>`, one per file; read-only). Of the copies that are
+equal, a tracked file is restored with `git checkout -- <path>`, an untracked one removed, so the next update of the main checkout does not stop on them. A board that only gained lane
 rows since stays and is no question; any other difference goes to the user. Once every lane of the plan has
 rebased, delete the local branch (`git branch -D docs/plan-<topic>`; a squash merge leaves it unmerged), so a
 later step 0 can use the name again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -113,6 +113,21 @@
       },
       "additionalProperties": false
     },
+    "kit": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "exclude": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "lanes": {
       "default": {},
       "type": "object",
@@ -726,6 +741,10 @@
             "type": "string",
             "pattern": "^[A-Za-z0-9_.*/-]+$"
           }
+        },
+        "openAsDraft": {
+          "default": false,
+          "type": "boolean"
         }
       },
       "additionalProperties": false

package/src/check/command.ts

@@ -203,7 +203,7 @@ const planRootsOf = (root: string, worktreeDirectory: string): string[] => {
 const ownChecksOf = (root: string, paths: readonly string[], settings: CheckSettings, home: string) => [
   publicContentCheck(root, paths, settings.check.publicContent, home),
   deferralArrowCheck(root, paths, settings.planDirectory),
-  skillBudgetCheck(root, settings.check.skillBudgets),
+  skillBudgetCheck(root, settings.check.skillBudgets, settings.skillPrefix),
   ...planStructureChecks({
     root,
     paths,

package/src/check/file-kinds.ts

@@ -116,17 +116,18 @@ export const isSourceFile = (path: string): boolean => {
   )
 }
 
-const LEADING_SEPARATORS = /^[._-]+/
+/** Separators at either end: `_result` (a private Python module) and `test_result` both name `result`. */
+const withoutOuterSeparators = (name: string): string => name.replace(/^[._-]+/, '').replace(/[._-]+$/, '')
 
 /** The name a test file covers: its stem without the test word (`test_parser.py` → `parser`); null when nothing is left. */
 export const testStemOf = (path: string): string | null => {
   const stem = stemOf(path)
-  const stripped = stem
-    .replace(TEST_WORD, (_match, separator: string) => separator)
-    .replace(CAMEL_TEST_SUFFIX, '')
-    .replace(CAMEL_TEST_PREFIX, '')
-    .replace(LEADING_SEPARATORS, '')
-    .replace(/[._-]+$/, '')
+  const stripped = withoutOuterSeparators(
+    stem
+      .replace(TEST_WORD, (_match, separator: string) => separator)
+      .replace(CAMEL_TEST_SUFFIX, '')
+      .replace(CAMEL_TEST_PREFIX, ''),
+  )
   return stripped === '' ? null : stripped
 }
 
@@ -139,4 +140,5 @@ export const testStemsOf = (files: readonly string[], isTest: (path: string) =>
  * `parser_test.go`, `test_parser.py`, `ParserTest.java`. Only the last extension of the source is dropped, so
  * `foo.module.ts` needs `foo.module.test.ts`.
  */
-export const hasNamedTest = (source: string, testStems: ReadonlySet<string>): boolean => testStems.has(stemOf(source))
+export const hasNamedTest = (source: string, testStems: ReadonlySet<string>): boolean =>
+  testStems.has(withoutOuterSeparators(stemOf(source)))

package/src/check/parallel-report.ts

@@ -1,4 +1,11 @@
-import { type PhaseSchedule, phaseLabels, phasesText, wavesOfPlan } from '../plan-format'
+import {
+  NO_DEPENDENCY_TABLE,
+  type PhaseSchedule,
+  phaseCount,
+  phaseLabels,
+  phasesText,
+  wavesOfPlan,
+} from '../plan-format'
 import type { PlanLanguage } from '../vocabulary'
 
 /** The flag by which `jh check` prints the waves of one plan instead of running the checks. */
@@ -12,7 +19,7 @@ export const parallelArgument = (args: readonly string[]): string | null => {
 
 /** `critical path: P1 → P3 → P6 (3 phases)` */
 const criticalPathLine = (path: readonly string[]): string =>
-  `critical path: ${phaseLabels(path, ' → ')} (${path.length} ${path.length === 1 ? 'phase' : 'phases'})`
+  `critical path: ${phaseLabels(path, ' → ')} (${phaseCount(path.length)})`
 
 const scheduleLines = ({ waves, criticalPath, unplaced }: PhaseSchedule): string[] => [
   ...(waves.length === 0
@@ -29,5 +36,5 @@ const scheduleLines = ({ waves, criticalPath, unplaced }: PhaseSchedule): string
  */
 export const parallelReportLines = (markdown: string, language: PlanLanguage): string[] => {
   const schedule = wavesOfPlan(markdown, language)
-  return schedule === null ? ['no dependency table'] : scheduleLines(schedule)
+  return schedule === null ? [NO_DEPENDENCY_TABLE] : scheduleLines(schedule)
 }

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
+  /** 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[]
@@ -42,6 +44,7 @@ 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
@@ -59,6 +62,7 @@ export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckS
     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

@@ -22,7 +22,17 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   // 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`.
-  '.claude/skills/orchestrate/SKILL.md': 7929,
+  // 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,
@@ -33,7 +43,8 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.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,
@@ -44,8 +55,8 @@ 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: grows with the skill above.
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8729,
+  // 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,
@@ -56,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'),

package/src/config/schema.ts

@@ -46,6 +46,15 @@ export const isModelRole = (value: string): value is ModelRole =>
 /** Lower-case letters and digits ending in a dash, so a prefixed name stays one plain path segment. */
 export const SKILL_PREFIX = /^[a-z0-9]+-$/
 
+/** What a global install, and a project that already has skills of kit names, puts before every kit name. */
+export const DEFAULT_SKILL_PREFIX = 'jh-'
+
+/** The skills every lane and the coordinator run on; `kit.exclude` cannot take them away. */
+export const KIT_CORE: readonly string[] = ['orchestrate', 'start']
+
+/** A kit skill or agent as the kit names it, before `skillPrefix`. */
+const KIT_ENTRY_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
 const FULL_MODEL_ID = /^claude-[a-z0-9][a-z0-9.-]*$/
 
 const language = z.enum(Object.values(PLAN_LANGUAGE))
@@ -56,6 +65,13 @@ const modelId = z
 
 const command = z.string().min(1)
 
+const excludedKitEntry = z
+  .string()
+  .regex(KIT_ENTRY_NAME, 'a kit skill or agent name as the kit names it, e.g. devops')
+  .refine((name) => !KIT_CORE.includes(name), {
+    error: (issue) => `${issue.input} is the kit's core and cannot be excluded`,
+  })
+
 const tokenCount = z.number().int().positive()
 
 /**
@@ -360,6 +376,12 @@ const mergeSchema = z.strictObject({
    * `--match-head-commit`. Empty means every merge waits for checks.
    */
   withoutChecks: z.array(checkFreePattern).default([]),
+  /**
+   * Whether a lane opens every pull request as a draft (`gh pr create --draft`), so pushes while it is worked on start
+   * no workflow that skips drafts. `/orchestrate` runs `gh pr ready` before the merge and waits for the checks that
+   * start then; the merge guard never lets a draft through. Off opens pull requests ready, as before.
+   */
+  openAsDraft: z.boolean().default(false),
 })
 
 const guardFields = z.strictObject({
@@ -480,6 +502,11 @@ export const jackherdConfigSchema = z.strictObject({
     .union([z.literal(''), z.string().regex(SKILL_PREFIX, 'lower-case letters and digits ending in a dash, e.g. kit-')])
     .default(''),
   commands: commandsSchema.prefault({}),
+  /**
+   * Kit skills and agents `jh sync` leaves out, by the kit's name without `skillPrefix`; a name takes its skill and
+   * its agent alike. An unchanged copy already installed is removed, a changed one stays untracked.
+   */
+  kit: z.strictObject({ exclude: z.array(excludedKitEntry).default([]) }).prefault({}),
   /** How `/orchestrate` sets up a lane's worktree. */
   lanes: z
     .strictObject({

package/src/context/fill.ts

@@ -1,3 +1,4 @@
+import { LOG_ENTRY_TYPE } from './log-vocabulary'
 import { keptLogEntry } from './session-log'
 
 /** How the context window of a model is assumed: by model ID, with a default for the models not listed. */
@@ -26,7 +27,7 @@ const count = (value: unknown): number => (typeof value === 'number' && Number.i
 /** The answer of a main-chain `assistant` line; null for every other line, a sub-agent's answer and a synthetic one. */
 const answerOf = (line: string): Answer | null => {
   const entry = keptLogEntry(line)
-  if (!entry || entry.type !== 'assistant' || entry.isSidechain === true) return null
+  if (!entry || entry.type !== LOG_ENTRY_TYPE.assistant || entry.isSidechain === true) return null
   const { message } = entry
   if (!isRecord(message) || typeof message.model !== 'string' || message.model === SYNTHETIC_MODEL) return null
   const { usage } = message

package/src/context/log-vocabulary.ts

@@ -0,0 +1,22 @@
+/** The entry types of a Claude Code session log line that a reader tells apart; the log delivers them as strings. */
+export const LOG_ENTRY_TYPE = { assistant: 'assistant' } as const
+
+/** The block types inside an entry's `message.content`. */
+export const CONTENT_BLOCK_TYPE = { text: 'text', toolUse: 'tool_use', toolResult: 'tool_result' } as const
+
+/** The names of Claude Code's tools a reader looks for in a `tool_use` block. */
+export const CLAUDE_TOOL = {
+  taskCreate: 'TaskCreate',
+  taskUpdate: 'TaskUpdate',
+  todoWrite: 'TodoWrite',
+  edit: 'Edit',
+  write: 'Write',
+  multiEdit: 'MultiEdit',
+  notebookEdit: 'NotebookEdit',
+} as const
+
+/**
+ * What every assistant entry's raw line holds, as the log writes it without spaces: a text search for it finds the
+ * answers of a log without parsing every line.
+ */
+export const ASSISTANT_ENTRY_MARK = `"type":"${LOG_ENTRY_TYPE.assistant}"`

package/src/context/session-log.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { CLAUDE_DIRECTORY, SESSION_LOGS_DIRECTORY } from '../claude/paths'
 import { boundedMemo } from '../shared/bounded-memo'
 import { isRecord } from '../shared/is-record'
+import { ASSISTANT_ENTRY_MARK } from './log-vocabulary'
 
 /** A tail read before: the file as it was (inode, size, modification time), its lines and the byte offset each starts at. */
 type FollowedTail = { inode: number; size: number; modifiedAt: number; lines: string[]; starts: number[] }
@@ -159,7 +160,7 @@ export const sessionLog = (
 
 export type AgentSession = { session: string | null; cwd: string | null }
 
-const hasAnswer = (lines: readonly string[]): boolean => lines.some((line) => line.includes('"type":"assistant"'))
+const hasAnswer = (lines: readonly string[]): boolean => lines.some((line) => line.includes(ASSISTANT_ENTRY_MARK))
 
 /** Claude Code names a project directory after the working directory, `/` and `.` turned into `-`. */
 export const projectDirectoryOf = (cwd: string): string => cwd.replace(/[/.]/g, '-')

package/src/lane-prompt/build.ts

@@ -19,6 +19,8 @@ export type LanePromptInput = {
   plans: LanePlan[]
   port: number | null
   handover: string | null
+  /** The project's `skillPrefix` (`''` for none), put before the name of the kit's skill the start names. */
+  skillPrefix: string
 }
 
 const writesText = (language: PlanLanguage, texts: LanePromptTexts, writes: string[] | null): string => {
@@ -35,11 +37,12 @@ const planLines = (language: PlanLanguage, texts: LanePromptTexts, plan: LanePla
   ...plan.phases.map((phase) => `  - ${phaseText(language, texts, phase)}`),
 ]
 
-const ruleLines = (input: LanePromptInput, texts: LanePromptTexts): string[] => [
-  input.port === null ? texts.noPort : texts.port(input.port),
+const ruleLines = (input: LanePromptInput, texts: LanePromptTexts, implementSkill: string): string[] => [
+  input.port === null ? texts.noPort : texts.port(input.port, implementSkill),
   texts.blocking,
   texts.mustNot,
   texts.commit,
+  texts.taskSignals,
   texts.report(laneReportFile(input.lane)),
   texts.textBlock,
   texts.secret,
@@ -51,11 +54,13 @@ const ruleLines = (input: LanePromptInput, texts: LanePromptTexts): string[] =>
 /**
  * The prompt that starts a lane, in the plan language: a first line that names the lane (the words the ask hint hook
  * and the project's lane exception recognise), the plans with their phases as `Phase P<n>` and each phase's write
- * set, the rules of `/orchestrate` § 1 that `/implement` does not carry already, and the start: `/implement`, or the
+ * set, the rules of `/orchestrate` § 1 and the lane contract (report each task, the report file, questions as text blocks,
+ * git through the coordinator), and the start: the phases built with `/implement` or another skill, or the
  * hand-over file after a restart.
  */
 export const buildLanePrompt = (input: LanePromptInput): string => {
   const texts = LANE_PROMPT_TEXTS[input.language]
+  const implementSkill = `/${input.skillPrefix}implement`
   return [
     `${LANE_PROMPT_OPENING[input.language]} ${input.lane}. ${texts.answersTo}`,
     '',
@@ -66,9 +71,9 @@ export const buildLanePrompt = (input: LanePromptInput): string => {
     texts.editInside,
     texts.writeTools,
     '',
-    ...ruleLines(input, texts).map((line) => `- ${line}`),
+    ...ruleLines(input, texts, implementSkill).map((line) => `- ${line}`),
     '',
-    input.handover === null ? texts.start : texts.restart(input.handover),
+    input.handover === null ? texts.start(implementSkill) : texts.restart(input.handover),
     '',
   ].join('\n')
 }