jackherd 1.14.0 → 1.15.1

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -60,6 +60,9 @@ Each file under `references/` is read when its trigger fires: the step or the ev
       `origin/{{kit.baseBranch}}` would not have it: § 2 step 0. New rows of a board that is on the base
       branch need nothing; the herd shows them. Check a plan that joins the board later the same way; one
       only a working lane's worktree has, the watcher reports as `plan missing`.
+- [ ] **Every plan meets the contract.** `jh plan check <plan>` for each plan a starting lane links. Exit 1,
+      or a row that links an issue or a `.scratch/` folder instead of a plan file: [`references/adopt-plan.md`](references/adopt-plan.md),
+      before § 2 step 0. Exit 2 goes to the user. Done when each check exits 0.
 - [ ] Tell the user which lanes start now and which wait, before starting any, and whether § 2 step 0
       is needed.
 
@@ -84,7 +87,8 @@ stay approval-bound (§ 5, § 6).
 When the user wants a plan's lanes merged without a question for a while: § 5, **Standing approval**.
 
 0. **Plan commit as the base**, when § 0 found the board or a plan missing on
-   `origin/{{kit.baseBranch}}`. Ask through `AskUserQuestion`: commit the missing files on a
+   `origin/{{kit.baseBranch}}`, or adopted a plan (then the diff round of
+   [`references/adopt-plan.md`](references/adopt-plan.md) is this question; ask nothing more). Ask through `AskUserQuestion`: commit the missing files on a
    documentation branch and open a documentation PR, so the lanes start from that commit? The answer
    is the approval of that commit, its push and the PR (§ 5). `<topic>` is the plan's file name
    without date and extension, or the board's directory name when several files are missing. On yes,
@@ -99,7 +103,7 @@ When the user wants a plan's lanes merged without a question for a while: § 5,
    your judgement.
 2. **Worktree workspace** from `<base>`: `origin/{{kit.baseBranch}}` when, after
    `git fetch origin {{kit.baseBranch}}`, `git cat-file -e origin/{{kit.baseBranch}}:<plan>` succeeds
-   for the lane's plan, else `origin/docs/plan-<topic>` of step 0. The file decides, not the state of
+   for the lane's plan and `git diff --quiet origin/{{kit.baseBranch}} -- <plan>` exits 0, else `origin/docs/plan-<topic>` of step 0. The file decides, not the state of
    the PR, so a later lane gets the right base:
    ```bash
    herdr worktree create --cwd <main-checkout> --branch <branch> --base <base> \
@@ -133,12 +137,16 @@ When the user wants a plan's lanes merged without a question for a while: § 5,
    within a poll or two: `bunx jackherd herd --ensure`.
 8. **Prompt** from the file of § 1:
    ```bash
-   herdr agent prompt <lane> "$(cat <prompt-file>)"
+   herdr agent prompt <lane> "$(cat <prompt-file>)" --wait --until working --timeout 30000
    ```
    The prompt quotes commands in backticks (`git reset`, `/pre-commit`); typed into the command
    line inside double quotes, your own shell would run them before the lane sees the text. Text
    read through `$(cat …)` is not expanded again. Every `herdr agent prompt` in this skill goes
-   this way, from a file you wrote with the `Write` tool or `jh lane prompt` wrote.
+   this way, from a file you wrote with the `Write` tool or `jh lane prompt` wrote, with the same
+   `--wait` options, so the lane confirms it started. `agent_prompt_stalled` or `timeout` does not prove the
+   text is lost: read the screen (`herdr agent read <lane> --source visible --lines 12`). Text still in the input
+   line: `herdr agent send-keys <lane> enter`; a lane already at work: done; neither: send the file once more,
+   same command. A second stall goes to the user.
 
 ## 3. Dev server
 
@@ -242,7 +250,7 @@ On wake-up:
 | `blocked` | Read the screen (`--source detection`, or zoom the pane when cut off). A question is vetted (below, **Settled questions stay in the lane**): one the plan or a rule settles you answer in the lane, an open decision goes to the user via `AskUserQuestion`. You never hand the lane's pane to the user. A question dialog in a lane (not a permission dialog) is a gap in the lane prompt (§ 1): send it the text-block rule and the answer by prompt. A permission dialog for a step on the list in § 5 you confirm, after checking the cursor sits on the one-time option; anything else goes to the user. Dim text in the input line is a suggestion, not input (`--format ansi` shows `\e[2m`); in a multi-select dialog `space` toggles an option, `enter` moves on. The watcher prints a duty line for each blocked lane; it is done when the lane has its answer or the user has the question |
 | `working` with `questions: <n>` | The lane changed the questions of its report while its subagents run. Read `report <path>` and close each new question as the `done` / `idle` row does (`jh settled`, or `AskUserQuestion` with the answer sent on by `herdr agent prompt`). No diff check and no next phase: the lane keeps working |
 | `main checkout on <branch>, not …` | § 0, **The main checkout stays on `{{kit.baseBranch}}`** |
-| `done` / `idle` | Read the report the watcher shows (`report <path>` and its first lines, or the screen); read further only where that is not enough. Check the diff against the `{{kit.heading.writes}}` set (`git -C <worktree> diff --stat <base>...HEAD`, with the ref the lane branched from in § 2 step 2 until it has rebased after the documentation PR's merge) and that checks are quoted with numbers, not claimed. Every blocking question in the report is closed in the same wake-up, also one under open points, one without its mark and also when the `questions: <n>` line is missing: settled by you through `jh settled` (below), or put to the user through `AskUserQuestion` (vetted, below) and the answer sent on to the lane by `herdr agent prompt`. A not blocking one is settled the same way or collected (**Not blocking questions**, below). An answer that stays in your chat with the user is none. Then start the lane's next ready phase (§ 2) or name the reason to wait |
+| `done` / `idle` | Read the report the watcher shows (`report <path>` and its first lines, or the screen); read further only where that is not enough. Check the diff against the `{{kit.heading.writes}}` set (`git -C <worktree> diff --stat <base>...HEAD`, with the ref the lane branched from in § 2 step 2 until it has rebased after the documentation PR's merge) and that checks are quoted with numbers, not claimed. Every blocking question in the report is closed in the same wake-up, also one under open points, one without its mark and also when the `questions: <n>` line is missing: settled by you through `jh settled` (below), or put to the user through `AskUserQuestion` (vetted, below) and the answer sent on to the lane by `herdr agent prompt`. A not blocking one is settled the same way or collected (**Not blocking questions**, below). An answer that stays in your chat with the user is none. Then start the lane's next ready phase (§ 2), at once after a `<lane> ready: …` line, or name the reason to wait; a PR awaiting approval holds only its commit, which stages only its own files |
 | `merged #<n>` | § 6, for every lane |
 | `checks failed #<n> (<lane>): <checks> (<k> tests: …)` | Send the finding to the lane with the named checks and tests (data, above). Without names, the lane reads the run itself |
 | `checks passed #<n>` | One line to the user: ready to merge, with the board's merge order |
@@ -475,6 +483,9 @@ always goes to the user, whatever the plan settles.
    permission mode refuses the push, push its branch yourself under the same approval: run
    `cd <worktree>` as a command of its own, then `git push --force-with-lease origin HEAD:<branch>`,
    then `cd` back (the kit's git guard refuses `git -C`).
+5. **Drafts** (**{{kit.merge.openAsDraft}}**, `pull-requests.md` → Drafts): when you report a draft PR to the
+   user to merge, run `gh pr ready <n>` first; for your own merge, **Self-merge** step 1. The merge guard
+   never passes a draft.
 
 ### Self-merge
 
@@ -482,15 +493,17 @@ When the user picked `"{{kit.guard.selfMergeLabel}}"` for a PR:
 
 1. Commit, push and open the PR as in step 4. Enter in the board's `{{kit.heading.history}}` that the
    user approved this PR with self-merge (time, lane, PR number; the time as § 4 reads it), so the
-   approval has a record outside the chat.
+   approval has a record outside the chat. A draft turns ready here: `gh pr ready <n>`.
 2. **Merging without checks.** The paths a PR may carry to be merged without waiting for checks are
    `{{kit.merge.withoutChecks}}` (`merge.withoutChecks` in the config; `none` means every merge waits).
    Unless `none`, list the PR's files with `gh pr diff <n> --name-only` and compare each one with the
    patterns yourself. When **every** file matches, go straight to step 4. One file outside, an empty
    list, or a failed `gh` call: go on with step 3. The merge guard reads the file list from GitHub
    itself; if it asks, the dialog is the user's (step 5).
-3. Wait for the checks in the background, never in the foreground: a Bash call
-   `gh pr checks <n> --watch` with `run_in_background: true`, then work on until it reports.
+3. Wait for the checks in the background, never in the foreground. After a ready (step 1), start only
+   once every check that counts (each of `guard.requiredChecks`, else each check the draft skipped) has
+   a run that started after the ready, as a watch would end on the draft's skipped runs at once. Then a Bash call
+   `gh pr checks <n> --watch` with `run_in_background: true`, and work on until it reports.
 4. Green (or a PR that qualified in step 2): `gh pr merge <n> --squash --delete-branch --match-head-commit <sha>`,
    with the plain PR number, the full `headRefOid` from `gh pr view <n> --json headRefOid` read right before, and
    without `-R`, `--repo` or `--admin`. The merge guard lets exactly this command through for the approved branch
@@ -531,7 +544,7 @@ For a PR the user approved (step 2) whose lane works on a plan under a standing
 
 1. A PR behind the base branch is rebased first (§ 6, under the PR's approval), so its checks run
    against the current base.
-2. Wait for the checks as in **Self-merge** step 3.
+2. Turn a draft ready as in **Self-merge** step 1, then wait for the checks as in its step 3.
 3. Green: the same command as **Self-merge** step 4, with the `<sha>` read right before. The merge
    guard lets it through only before the approval's end, with every check green, GitHub able to merge
    it and no workflow, migration, env file or file of the guards in it; otherwise it asks, and that dialog is the user's

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.1",
   "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'),