jackherd 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.15.0
+
+- **Any plan, once it meets the contract.** `docs/plan-contract.md` writes down what Jack needs from a plan: phases with an id, checkbox tasks, a model per phase, and from two phases on a dependency table. `jh plan check <file>` says per part whether it is there, missing or malformed, and exits 0 when the plan meets it. Without a dependency table, phases run one after another, and `jh check --parallel` says so.
+- **Jack adopts a plan from another planner.** When a plan a lane starts from misses the contract, or lives only in an issue or a `.scratch/` folder, Jack mirrors it into a plan file and adds only what is missing: phase headings, tasks, model rows, the dependency table, short task names and a line saying the source planned no review. No word of the author's goes, which a word diff proves, and you see that diff before the plan is committed.
+- **A lane builds with any skill.** The lane prompt names what every lane does, whatever skill it builds with (`/jh-implement`, someone else's, or your own): report each task with `jh task`, write the report, send questions as text, leave git to Jack. A prompt to a lane that does not start working comes back as an error instead of passing as sent, and Jack's own prompts wait the same way.
+- **Other people's skills sit beside jackherd.** A skill installed with `npx skills add` (listed in `skills-lock.json`) only warns when it exceeds a word budget, it never turns `jh check` red. When one lands on the path of a jackherd skill, `jh sync` names it, also when it kept your file, with the way out: `"skillPrefix": "jh-"` moves jackherd's skills to `/jh-…` and leaves the other skill where it is.
+- **Leave out jackherd skills you don't use.** List them in `kit.exclude` in `.jackherd/config.json`, by name without the prefix (`"exclude": ["devops", "grill"]`); a name takes its skill and its agent. `jh sync` stops writing them, removes a copy you never changed, keeps one you changed, and names what it left out. Where another jackherd skill calls one you left out, it reads `/devops (not installed)`, so the agent knows instead of calling a skill that isn't there. A name jackherd doesn't ship stops the sync before it writes anything; `orchestrate` and `start` cannot be left out.
+- **The herd shows what a working lane does.** Under the line of a working lane, a dim `↳` line shows its agent's last action from the session log, a tool with its target or the start of its answer, and one more for each running subagent. The log is read again only when it grew, never per frame.
+- **Jack starts a ready phase at once.** When a lane reports `done` or `idle` and its plan has a phase whose dependencies are ticked and that nobody works on, the watcher prints `<lane> ready: P9 (after P7): start it now`, so a pull request waiting for your approval no longer holds the next phase back, only the commit.
+- **Word budgets follow the skill prefix.** With a `skillPrefix`, `jh check` measured every jackherd skill against the default 2000 words; it now measures each against its own budget.
+- **Tests by name find a private module's test.** `_result.py` counts as tested by `test_result.py`.
+- **A folded lane shows its checks.** Behind each pull request badge the folded lane line shows `✓ checks`, `checks running`, `✗ test +1` with the first red check, or `draft`, also while the lane rests, so a red check or a draft no longer hides until you open the lane. The open lane says `checks running` too, where it said `… checks`.
+- **Pull requests stay drafts until their merge.** With `"merge": { "openAsDraft": true }` a lane opens every pull request with `gh pr create --draft`, so its pushes start no workflow that skips drafts. Jack runs `gh pr ready` when he reports the pull request to you to merge, or as the first step of his own merge, and waits for the runs that start then. Off by default.
+- **The merge guard never merges a draft, and a required check needs a success.** A draft always asks. A check in `guard.requiredChecks` counts only with a run that succeeded: a skipped run, as a draft leaves it right after `gh pr ready`, no longer lets a merge pass. That holds for a self-merge too, which waited for no required check before; a `guard.requiredChecks` that does not read turns the self-merge answer off. Without required checks, at least one run must have succeeded: a pull request whose checks were all skipped asks.
+
+## 1.14.0
+
+- **Any language, once its commands are set.** PHP and Node are recognised on their own, as before. For any other language, set its test command once, or let `/jh-start` in Claude Code propose the commands from your CI: it writes only the ones you approve. From then on `jh check` runs your tests before a commit. In a language jackherd does not know, a changed file without a test of its name gets a warning, not a block, since some languages keep tests in the source file.
+- **The herd shows the plan a lane really works on.** When a lane's plan is not on the main branch yet, Jack hears about it once and gets it there, so the herd no longer shows an older plan for that lane.
+
 ## 1.13.0
 
 - **Repositories without Node.** `jh init` reads the stack from the lock file: next to the Node managers, `composer.lock` writes the tools `composer.json` names (Pest or PHPUnit, PHPStan or Psalm, Pint or PHP-CS-Fixer, each as `vendor/bin/…`) and `composer install`. Before the first install, `composer.json` alone decides Composer, with no `lanes.lockFile`; a `package.json` without a lock file names no package manager, so none is guessed. A repository without a known stack gets no Bun commands any more; `init` leaves them out and says so, and the config gets a `$schema` only where `node_modules` can sit beside `.jackherd/`.

package/README.md

@@ -1,9 +1,9 @@
 <p>
-<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.13.0/assets/branding/jackherd-logo-outline.svg" width="340">
+<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.15.0/assets/branding/jackherd-logo-outline.svg" width="340">
 <br>
 </p>
 
-[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.13.0/assets/icons/space.svg">
+[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.15.0/assets/icons/space.svg">
 
 # Jack herds your coding agents.
 
@@ -15,25 +15,27 @@ For developers who'd rather decide than supervise.
 curl -fsSL https://unpkg.com/jackherd/install.sh | sh
 ```
 
-Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.13.0/assets/icons/space.svg">
+Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.15.0/assets/icons/space.svg">
 
 <p>
-<img src="https://unpkg.com/jackherd@1.13.0/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
+<img src="https://unpkg.com/jackherd@1.15.0/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
 <br>
-<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.13.0/assets/icons/space.svg">
+<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.15.0/assets/icons/space.svg">
 </p>
 
-<p><img src="https://unpkg.com/jackherd@1.13.0/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
+<p><img src="https://unpkg.com/jackherd@1.15.0/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.13.0/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A blocked lane, a red check, a review comment: Jack wakes, and the herd view shows where every lane stands.</p>
+<p><img src="https://unpkg.com/jackherd@1.15.0/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Nothing is committed, pushed or merged without your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.13.0/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments go to the lane that fixes them, with a test. <code>/jh-follow</code> brings anything with a CLI or an API into the herd: tickets, error logs, status pages, deploys, and whatever else you point it at.</p>
+<p><img src="https://unpkg.com/jackherd@1.15.0/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A blocked lane, a red check, a review comment: Jack wakes, and the herd view shows where every lane stands.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.13.0/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>Picks up where you left off.</b><br>Plan and board hold the state, not the chat.</p>
+<p><img src="https://unpkg.com/jackherd@1.15.0/assets/icons/skills.svg" width="24" height="34" align="middle" alt=""> <b>Works with your skills.</b><br>Keep your own skills: a lane builds with whichever one you pick. Plans written elsewhere run too, once Jack fills in what they're missing.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.13.0/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.</p>
+<p><img src="https://unpkg.com/jackherd@1.15.0/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments go to the lane that fixes them, with a test. <code>/jh-follow</code> brings anything with a CLI or an API into the herd: tickets, error logs, status pages, deploys, and whatever else you point it at.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.13.0/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Nothing is committed, pushed or merged without your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.13.0/assets/icons/space.svg"></p>
+<p><img src="https://unpkg.com/jackherd@1.15.0/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>Picks up where you left off.</b><br>Plan and board hold the state, not the chat.</p>
+
+<p><img src="https://unpkg.com/jackherd@1.15.0/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.15.0/assets/icons/space.svg"></p>
 
 ## Quickstart
 
@@ -69,22 +71,22 @@ Then `/jh-start` in a repository, and Jack offers your first plan. → [Quicksta
    /jh-orchestrate docs/plans/board-<name>/board.md
    ```
 
-By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks. → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.13.0/assets/icons/space.svg">
+By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks. → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.15.0/assets/icons/space.svg">
 
 ## Follow anything outside GitHub
 
 Whatever you check by hand, Jack can watch: tickets, error logs, status pages, deploys. One `/jh-follow`, one yes, and every change comes to you like this:
 
-<img src="https://unpkg.com/jackherd@1.13.0/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
+<img src="https://unpkg.com/jackherd@1.15.0/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
 
-The herd sums up your sources in one `Sources` line: per source its new entries, or when it last ran, red while it fails; opened, a click on an entry opens it. A ticket shows on the lane that works it, and a row in Your turn that came from a source starts with that source's label.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.13.0/assets/icons/space.svg">
+The herd sums up your sources in one `Sources` line: per source its new entries, or when it last ran, red while it fails; opened, a click on an entry opens it. A ticket shows on the lane that works it, and a row in Your turn that came from a source starts with that source's label.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.15.0/assets/icons/space.svg">
 
 ## In detail
 
 <details>
 <summary><b>What Jack does on his own, and what waits for you</b></summary>
 
-<img src="https://unpkg.com/jackherd@1.13.0/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
+<img src="https://unpkg.com/jackherd@1.15.0/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
 
 | On his own | After your approval | Never |
 | --- | --- | --- |
@@ -108,16 +110,18 @@ A project install adds two hooks to Claude Code's [permission rules](https://cod
 
 A merge passes without a question on green checks after self-merge, or under a standing approval: one plan's lanes until a time you pick, at most 24 hours; workflows, migrations, env files and the guards' own files still ask. A pull request whose files all match `merge.withoutChecks`, such as docs only, skips question and checks, unless a file lies on a path that always asks.
 
+`"merge": { "openAsDraft": true }` has lanes open every pull request as a draft, so pushes while it is worked on start no workflow that skips drafts; Jack runs `gh pr ready` before the merge. The guard never merges a draft, and a check in `guard.requiredChecks` counts only with a run that succeeded, not with the skipped run a draft leaves behind; without that list, at least one run must have succeeded.
+
 The guards catch mistakes, not intent; for that, use branch protection. The hooks need Bun; a global install ships none.
 
 </details>
 
 <details>
-<summary><b>Plans, boards and the skills</b></summary>
+<summary><b>Plans, boards and the skills, yours included</b></summary>
 
 A **plan** is Markdown with phases, checkbox tasks, a model and a review gate per phase. A **board** lists the lanes of one or more plans: which phases each lane builds, on which model, after what. A **lane** is one agent session in its own git worktree (a second checkout of your repository), and **Jack** is the session in the main checkout that runs `/jh-orchestrate` on a board.
 
-<img src="https://unpkg.com/jackherd@1.13.0/docs/skills-dark.svg" alt="/jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
+<img src="https://unpkg.com/jackherd@1.15.0/docs/skills-dark.svg" alt="Your own plan or an issue is adopted (Jack adds what is missing, you see the diff) and goes to /jh-orchestrate; /jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement, which your own skill can replace; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
 
 | Skill | Does |
 | --- | --- |
@@ -130,7 +134,10 @@ A **plan** is Markdown with phases, checkbox tasks, a model and a review gate pe
 | `/jh-follow` | follows something outside GitHub: a ticket, error logs, a status page |
 | `/jh-diagnose` | turns a bug into a failing command, fixes it with a regression test |
 
-The global install names the skills with a `jh-` prefix; a project install uses none, unless the project already has skills of the same names.
+- **Your own skills stay.** `jh init` keeps them and gives jackherd's skills a `jh-` prefix where a name is taken, as a global install always does; `jh sync` never writes over a file you changed, it leaves `<file>.kit-new` beside it. If a skill from `npx skills add` later takes the path of one of jackherd's, `jh sync` names it and the way out: `"skillPrefix": "jh-"`. Such skills only warn in `jh check`'s word budgets, never red.
+- **Leave out what you don't use.** `"kit": { "exclude": ["devops", "grill"] }` in `.jackherd/config.json` keeps those skills and agents out on the next `jh sync`: a copy you never changed goes, one you changed stays, and the skills that call one show it as not installed. `/jh-orchestrate` and `/jh-start` always stay.
+- **A lane builds with any skill.** The lane's rules hold over it: report each task with `jh task`, send questions as text, leave git to Jack.
+- **A plan from another planner**, or one in an issue, runs once it meets the [plan contract](https://unpkg.com/jackherd/docs/plan-contract.md): Jack adds what is missing and shows you the diff before committing it.
 
 </details>
 
@@ -181,9 +188,10 @@ How the herd reads the board:
 - **Sources** shows, per source that is no ticket, its entries and how many are new, or when it last ran: amber with a new entry that is not in Your turn yet, red while it fails. Opened, its entries stand newest first by the time they show, and a click on an entry opens it; `↑ in your turn` marks one a row of Your turn asks about.
 - **Lanes** opens at the start. A lane that works or is blocked opens by itself only when it first appears; after that, opening and folding are yours. A lane symbol says the state (`●` working, `◆` blocked, `◉` the agent finished its answer, `○` idle, `(·) no agent` a worktree nobody works in); only blocked wears its word. A resting lane names what it waits on: `waits on you` with the open questions of its report, `waits on` a row of Your turn, `after` its board row's starts-after cell, or `idle · no reason`.
 - **Waiting** lists the lanes not started yet: no worktree yet, something left to do, and what each starts after; it starts folded. Finished lanes (cleaned up, or every phase they name ticked) are not shown.
-- **An open lane** shows, top down: its branch, the model and how long it idles; its link chips on one line, `+n` for the rest; its pull requests; the phases it works on, each with its bar and its first four open tasks, the running ones first, `▸ n more open · k done` to list them all; `▸ next` with the phases that wait, as ranges; `▸ done` with the finished ones. A lane shows only the phases its board rows name; a lane without a worktree reads its plan from the main checkout. A folded lane line names the phase moved last, `+n` more active ones and its count, and a reported task below it.
+- **An open lane** shows, top down: its branch, the model and how long it idles; its link chips on one line, `+n` for the rest; its pull requests; the phases it works on, each with its bar and its first four open tasks, the running ones first, `▸ n more open · k done` to list them all; `▸ next` with the phases that wait, as ranges; `▸ done` with the finished ones. A lane shows only the phases its board rows name; a lane without a worktree reads its plan from the main checkout. A folded lane line names the phase moved last, `+n` more active ones and its count, and a reported task below it; behind each pull request badge it shows the checks, also while the lane rests: `✓ checks`, `checks running`, `✗ test +1` with the first red check, `draft` for a draft.
 - **A phase runs** when an agent reports working on it, one of its boxes was ticked in the last 20 minutes, or some of its tasks are ticked. A phase whose run was merged and that the lane's newest board row no longer names waits behind the others in `▸ next`, its open boxes left open on purpose. `n min ago` counts since the last tick or report; `· gate` means only the review gate is open, `docs open` only the documentation box.
 - **A running task** carries `●` when an agent reported it, from its task list or `jh task`; its text stands in teal and a light band runs over it (`plans.shimmer: false`, `NO_COLOR` and `--once` keep it still). `◌` in dim is only guessed from the words of the lane's log. `now: …` is a reported task no plan task names, `Subagent: …` a running subagent on no phase; a running review sits on the gate box that names it, in the phase it names or else the lane's current one. With several agents in a lane, each task carries its agent's name, dim, at the right edge.
+- **What a working lane does right now:** under its lane line, open or folded, a dim `↳` line shows the last action from the agent's session log, a tool with its target (`↳ Read plans/layout.ts`) or the start of its answer, and each running subagent adds one, indented and led by its task (where `Subagent: …` says what it works on, `↳` says what it does); the lines go when the lane rests.
 - **Counts and colours:** the bar is the progress over the lane's plans; `n/m` counts checkboxes, `n/m ph` finished phases, green when all are ticked; `–` is a phase without checkboxes, `?` one not in the plan. `🥣` is the share of the context window used, on a folded lane only once it warns. `Sonnet ≠ Opus` in amber says a phase's subagent ran on another model than the plan's. `stale?` in Backlog marks a plan file unchanged on the base branch for 14 days.
 - **Chips:** `🔗` an Artifact, `⑂` a pull request or issue, `◈` Figma, `📡` a ticket with its status (`📡 n` in amber on a folded lane when tickets are new), `private` where the plan says so. After the lane: `↗` a pull request with its checks, `💬` new feedback, `✋` changes requested, `🌐` a preview. ctrl+click opens a chip's link.
 - **Mouse and keys:** `▸` `▾` marks a row that opens and folds, and only such a row has one; it turns teal under the mouse or the arrows. `❯` and a light background mark the row under the mouse or the arrows; the mark leaves with the mouse, while a row the arrows chose keeps it; the footer says what a click or a key does there. A click or enter on a task opens it and nothing else: what it asks, up to its first ` — `, one sentence per line behind a thin `│`, only whole sentences in at most five lines, code in teal and the origin dim at the end; `▸ n more lines` opens the rest. Buttons in square brackets do something, bold under the mouse. `s` opens every lane and plan as one HTML page.
@@ -222,7 +230,7 @@ Each phase in the plan names its model: the planning model (Opus by default) whe
 | `jh preview <file>` | renders a Markdown file through the GitHub API into a preview in GitHub and npm style |
 | `jh waiting` | the files and Artifacts sent to you that you have not answered yet (`close <id>…` or `close --all` once you have) |
 | `jh context` | how full an agent's context is, as JSON |
-| `jh config` | the commands and the base branch the repository uses; a missing value or one the lock files contradict goes to stderr with the line to set, and `jh config <key>` for an unset value exits 3 |
+| `jh config` | the commands and the base branch the repository uses; a missing value goes to stderr with the line to set, and `jh config <key>` for an unset value exits 3 |
 
 Without a global install, run them as `bunx jackherd <command>`. The config is `.jackherd/config.json` in a project and `~/.jackherd/config.json` globally, checked against [one schema](https://unpkg.com/jackherd/schemas/jackherd.schema.json), which your editor completes in the project config. What usually needs setting:
 
@@ -242,24 +250,6 @@ Without a global install, run them as `bunx jackherd <command>`. The config is `
 
 </details>
 
-<details>
-<summary><b>Other languages</b></summary>
-
-jackherd runs on Bun; your project does not need Node. `jh init` reads the lock file in the repository root and writes the commands of that stack:
-
-| Lock file | Commands |
-| --- | --- |
-| `bun.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` | the manager's own (`bun test`, `npm test`, …), TypeScript and Biome |
-| `composer.lock`, or `composer.json` before the first install | from `composer.json`: Pest or PHPUnit, PHPStan or Psalm, Pint or PHP-CS-Fixer, each as `vendor/bin/…`; `composer install` |
-
-A tool the manifest does not name gets no command, and a repository without a known lock file or a `composer.json` gets none at all: jackherd never guesses one, so a `package.json` without a lock file names no package manager. `jh config` names each missing value with the line to set, and `/jh-start` passes those lines on. Set a command yourself under `commands` in `.jackherd/config.json`; a value there always wins.
-
-`jh check` tests from the nearest directory with the stack's manifest (`package.json`, `composer.json`), type-checks where a type config is (`tsconfig.json`, `phpstan.neon`), and lints only the files the stack lints. It fails when a changed source file is reached by no test, and when `commands.test` belongs to another stack than the lock file (`bun test` beside `composer.lock`), since such a run finds no test. A suite that runs some other way is a `check.checks` entry with `"kind": "tests"`.
-
-The kit rules name no language, framework or test runner. Put your team's conventions (PSR-12, the PHPStan level, how Pest tests are written) into a rule of your own beside `.claude/rules/kit/`; `jh sync` never touches it.
-
-</details>
-
 <details>
 <summary><b>Troubleshooting</b></summary>
 

package/assets/icons/skills.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 26.18 37.09" width="24" height="34" fill="none" stroke-linecap="round" stroke-linejoin="round"><g transform="translate(-0.822 -0.552) scale(1.019)" stroke-width="1.718"><path stroke="#6F818A" d="M10.35 5.40L10.44 2.12L13.56 2.12L13.65 5.40L15.50 6.17L17.88 3.91L20.09 6.12L17.83 8.50L18.60 10.35L21.88 10.44L21.88 13.56L18.60 13.65L17.83 15.50L20.09 17.88L17.88 20.09L15.50 17.83L13.65 18.60L13.56 21.88L10.44 21.88L10.35 18.60L8.50 17.83L6.12 20.09L3.91 17.88L6.17 15.50L5.40 13.65L2.12 13.56L2.12 10.44L5.40 10.35L6.17 8.50L3.91 6.12L6.12 3.91L8.50 6.17Z"/><circle stroke="#04A5AD" cx="12" cy="12" r="3.3"/></g></svg>

package/dist/config.d.ts

@@ -21,6 +21,10 @@ declare const isTerminalAdapter: (value: string) => value is TerminalAdapter;
 declare 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. */
 declare const SKILL_PREFIX: RegExp;
+/** What a global install, and a project that already has skills of kit names, puts before every kit name. */
+declare const DEFAULT_SKILL_PREFIX = "jh-";
+/** The skills every lane and the coordinator run on; `kit.exclude` cannot take them away. */
+declare const KIT_CORE: readonly string[];
 /**
  * The project's own commands. Each is optional: detection fills what the repository's stack decides, and a command
  * nobody set stays out instead of a guessed one (a kit text then says where to set it).
@@ -101,6 +105,9 @@ declare const jackherdConfigSchema: z.ZodObject<{
         install: z.ZodOptional<z.ZodString>;
         dev: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    kit: z.ZodPrefault<z.ZodObject<{
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     lanes: z.ZodPrefault<z.ZodObject<{
         copy: z.ZodDefault<z.ZodArray<z.ZodString>>;
         lockFile: z.ZodOptional<z.ZodString>;
@@ -288,6 +295,7 @@ declare const jackherdConfigSchema: z.ZodObject<{
     }>>>;
     merge: z.ZodPrefault<z.ZodObject<{
         withoutChecks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        openAsDraft: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     hints: z.ZodPrefault<z.ZodObject<{
         askUserQuestion: z.ZodDefault<z.ZodBoolean>;
@@ -321,6 +329,9 @@ declare const jackherdConfigSchema: z.ZodObject<{
         }, z.core.$strict>>;
         skillBudgets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
         looseTests: z.ZodDefault<z.ZodBoolean>;
+        roots: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+        sourceFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        testFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 type JackherdConfig = z.infer<typeof jackherdConfigSchema>;
@@ -330,4 +341,4 @@ declare const parseConfigFile: (raw: unknown, label: string) => JackherdConfig;
 /** One `watch.sources` entry outside the config, such as a draft to try; invalid throws with `label` and the issues. */
 declare const parseSourceDraft: (raw: unknown, label: string) => z.infer<typeof sourceSchema>;
 
-export { COMMAND_KEYS, type CommandKey, DEFAULT_CONTEXT_WINDOW, DEFAULT_MODELS, type JackherdConfig, MODEL_ROLE, type ModelRole, SKILL_PREFIX, TERMINAL_ADAPTER, type TerminalAdapter, isModelRole, isTerminalAdapter, jackherdConfigSchema, parseConfigFile, parseJackherdConfig, parseSourceDraft, renderConfigJsonSchema };
+export { COMMAND_KEYS, type CommandKey, DEFAULT_CONTEXT_WINDOW, DEFAULT_MODELS, DEFAULT_SKILL_PREFIX, type JackherdConfig, KIT_CORE, MODEL_ROLE, type ModelRole, SKILL_PREFIX, TERMINAL_ADAPTER, type TerminalAdapter, isModelRole, isTerminalAdapter, jackherdConfigSchema, parseConfigFile, parseJackherdConfig, parseSourceDraft, renderConfigJsonSchema };

package/dist/config.js

@@ -36,6 +36,7 @@ var isTokenizable = (command3) => {
 var command = nonEmpty.refine(isTokenizable, "Unterminated quote in command");
 var glob = nonEmpty.refine((value) => !/[{}[\]]/.test(value), "Braces and brackets are not supported in globs");
 var globs = z.array(glob).min(1);
+var directory = nonEmpty.transform((value) => value.replace(/^(\.\/)+/, "").replace(/\/+$/, "") || ".");
 var DEFAULT_BUILD_ARTIFACT_GLOBS = [
   "**/tsup.config.bundled_*",
   "**/dist/**",
@@ -90,12 +91,25 @@ var checkConfigSchema = z.strictObject({
    */
   skillBudgets: skillBudgets.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
-  looseTests: z.boolean().default(false)
+  looseTests: z.boolean().default(false),
+  /**
+   * Package roots, as directories from the repository root, read only where no stack is detected: a changed file
+   * belongs to the nearest one above it, else to the repository root `.`.
+   */
+  roots: z.array(directory).min(1).optional(),
+  /** The files a test covers; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  sourceFiles: globs.optional(),
+  /** The test files; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  testFiles: globs.optional()
 });
 
 // src/claude/paths.ts
 var CLAUDE_DIRECTORY = ".claude";
+var SKILLS_DIRECTORY = "skills";
+var AGENTS_DIRECTORY = "agents";
 var WORKTREES_DIRECTORY = "worktrees";
+var SKILL_PATH = new RegExp(`^${SKILLS_DIRECTORY}/([^/]+)/(.+)$`);
+var AGENT_PATH = new RegExp(`^${AGENTS_DIRECTORY}/([^/]+)\\.md$`);
 var claudePath = (...segments) => [CLAUDE_DIRECTORY, ...segments].join("/");
 
 // src/watch/source-fields.ts
@@ -265,10 +279,16 @@ var DEFAULT_MODELS = {
 var isTerminalAdapter = (value) => Object.values(TERMINAL_ADAPTER).includes(value);
 var isModelRole = (value) => Object.values(MODEL_ROLE).includes(value);
 var SKILL_PREFIX = /^[a-z0-9]+-$/;
+var DEFAULT_SKILL_PREFIX = "jh-";
+var KIT_CORE = ["orchestrate", "start"];
+var KIT_ENTRY_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 var FULL_MODEL_ID = /^claude-[a-z0-9][a-z0-9.-]*$/;
 var language = z2.enum(Object.values(PLAN_LANGUAGE));
 var modelId = z2.string().regex(FULL_MODEL_ID, "Use a full model ID such as claude-opus-5-5, not an alias like opus or sonnet");
 var command2 = z2.string().min(1);
+var excludedKitEntry = z2.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`
+});
 var tokenCount = z2.number().int().positive();
 var commandsSchema = z2.strictObject({
   test: command2.optional(),
@@ -457,7 +477,13 @@ var mergeSchema = z2.strictObject({
    * of them, `/orchestrate` merges at once and the merge guard does not ask, for a merge bound to the head commit with
    * `--match-head-commit`. Empty means every merge waits for checks.
    */
-  withoutChecks: z2.array(checkFreePattern).default([])
+  withoutChecks: z2.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: z2.boolean().default(false)
 });
 var guardFields = z2.strictObject({
   /**
@@ -551,6 +577,11 @@ var jackherdConfigSchema = z2.strictObject({
    */
   skillPrefix: z2.union([z2.literal(""), z2.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: z2.strictObject({ exclude: z2.array(excludedKitEntry).default([]) }).prefault({}),
   /** How `/orchestrate` sets up a lane's worktree. */
   lanes: z2.strictObject({
     /** Untracked files copied into every new worktree; empty means the files `.worktreeinclude` lists. */
@@ -626,6 +657,8 @@ export {
   COMMAND_KEYS,
   DEFAULT_CONTEXT_WINDOW,
   DEFAULT_MODELS,
+  DEFAULT_SKILL_PREFIX,
+  KIT_CORE,
   MODEL_ROLE,
   SKILL_PREFIX,
   TERMINAL_ADAPTER,

package/dist/plan-format.d.ts

@@ -382,6 +382,12 @@ type OpenLaneRow = {
 };
 /** Sprint tables name a phase `P4`; the sidebar title prints it the same way. */
 declare const PHASE_ID_PREFIX = "P";
+/** The phase a table's first cell names (`1 — Title`, `P1`, `10c`), lower-cased; null when it names none. */
+declare const phaseIdOf: (cell: string) => string | null;
+/** What a report says when the plan has no dependency table. */
+declare const NO_DEPENDENCY_TABLE = "no dependency table: phases run one after another";
+/** `1 phase`, `3 phases`. */
+declare const phaseCount: (count: number) => string;
 /** A phase as plans and reports name it: `P4`. */
 declare const phaseLabel: (id: string) => string;
 /** Phases as plans and reports name them, joined by `separator`: `P3 P4`, `P19 ∥ P20`. */
@@ -418,6 +424,23 @@ declare const columnModels: (column: string) => ColumnModel[];
  */
 declare const differsFromColumn: (column: string, modelId: string) => boolean;
 
+/**
+ * A row of the model table: the phase it names, the models its model cell names (none for a dash), the model cell as
+ * written, and the row's 1-based line.
+ */
+type ModelRow = {
+    id: string;
+    models: ColumnModel[];
+    cell: string;
+    line: number;
+};
+/**
+ * The rows of the plan's model table (`### Model-Empfehlungen pro Phase`): the phase from the first cell (`1 — Title`,
+ * `P1`, `10c`), the models from the second, read like a board's model column. A row whose first cell names no phase is
+ * skipped; null when the plan has no such section or the section holds no table.
+ */
+declare const parseModelTable: (markdown: string, language: PlanLanguage) => ModelRow[] | null;
+
 /** Per heading that carries checkboxes or table status cells: how many are done and open. */
 type PhaseTally = {
     title: string;
@@ -591,4 +614,4 @@ declare const readSprintDocument: (markdown: string, language: PlanLanguage) =>
  */
 declare const readPhaseDependencies: (planMarkdown: string, language: PlanLanguage) => Record<string, string>;
 
-export { ADDRESS_FORM, APPOINTMENT_VOCABULARY, APPROVAL_TEXTS, type ChecklistItem, type ColumnModel, type DeferredItem, type DriftFinding, LANE_PROMPT_OPENING, LANGUAGE_NAME, type LaneProgress, type LongPhaseTitle, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, NEXT_VOCABULARY, PHASE_CELL_LIMIT, PHASE_ID_PREFIX, PHASE_TITLE_LIMIT, PHASE_WORK, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, PROSE_REASON, type PhaseDependency, type PhaseHeading, type PhaseProgress, type PhaseSchedule, type PhaseTally, type PhaseWithoutGate, type PhaseWithoutRow, type PhaseWork, type PhaseWorkFields, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type ProseReason, RESPONSE_ADDRESS, type ResponseAddress, type RowWithProse, type RowWithoutPhase, SELF_MERGE_LABEL, SHORT_NAME_LIMIT, SHORT_NAME_PROBLEM, STANDING_APPROVAL_TEXTS, type ShortNameFinding, type ShortNameProblem, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, WAITING_VOCABULARY, activeItem, boardRowsWithProse, boardRowsWithoutPhase, classifyStatus, columnModels, countDecisions, criticalPath, currentPhase, currentPhaseOf, deferralTarget, differsFromColumn, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isDocumentationGateItem, isOpenCheckboxLine, isPhaseFinished, isPhaseOpen, isPlanLanguage, isReviewGateLine, isTickedUnmerged, laneNameOf, laneProgress, longPhaseTitles, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, onlyDocumentationOpen, parallelGroups, parallelGroupsOfPlan, parseDependencyTable, parsePlanPhases, parseSprintLanes, phaseHeading, phaseHeadingPattern, phaseHeadings, phaseIdsOfCell, phaseIdsOfPlan, phaseLabel, phaseLabels, phaseProgress, phaseWaves, phaseWorkFields, phasesText, phasesWithoutDependencyRow, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortNameFindings, shortTitle, sprintTitleOf, sumPhases, tallyPhases, wavesOfPlan, withoutRepeats };
+export { ADDRESS_FORM, APPOINTMENT_VOCABULARY, APPROVAL_TEXTS, type ChecklistItem, type ColumnModel, type DeferredItem, type DriftFinding, LANE_PROMPT_OPENING, LANGUAGE_NAME, type LaneProgress, type LongPhaseTitle, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, type ModelRow, NEXT_VOCABULARY, NO_DEPENDENCY_TABLE, PHASE_CELL_LIMIT, PHASE_ID_PREFIX, PHASE_TITLE_LIMIT, PHASE_WORK, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, PROSE_REASON, type PhaseDependency, type PhaseHeading, type PhaseProgress, type PhaseSchedule, type PhaseTally, type PhaseWithoutGate, type PhaseWithoutRow, type PhaseWork, type PhaseWorkFields, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type ProseReason, RESPONSE_ADDRESS, type ResponseAddress, type RowWithProse, type RowWithoutPhase, SELF_MERGE_LABEL, SHORT_NAME_LIMIT, SHORT_NAME_PROBLEM, STANDING_APPROVAL_TEXTS, type ShortNameFinding, type ShortNameProblem, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, WAITING_VOCABULARY, activeItem, boardRowsWithProse, boardRowsWithoutPhase, classifyStatus, columnModels, countDecisions, criticalPath, currentPhase, currentPhaseOf, deferralTarget, differsFromColumn, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isDocumentationGateItem, isOpenCheckboxLine, isPhaseFinished, isPhaseOpen, isPlanLanguage, isReviewGateLine, isTickedUnmerged, laneNameOf, laneProgress, longPhaseTitles, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, onlyDocumentationOpen, parallelGroups, parallelGroupsOfPlan, parseDependencyTable, parseModelTable, parsePlanPhases, parseSprintLanes, phaseCount, phaseHeading, phaseHeadingPattern, phaseHeadings, phaseIdOf, phaseIdsOfCell, phaseIdsOfPlan, phaseLabel, phaseLabels, phaseProgress, phaseWaves, phaseWorkFields, phasesText, phasesWithoutDependencyRow, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortNameFindings, shortTitle, sprintTitleOf, sumPhases, tallyPhases, wavesOfPlan, withoutRepeats };

package/dist/plan-format.js

@@ -69,9 +69,10 @@ var headerField = (markdown, name) => {
 };
 var firstHeading = (markdown, fallback) => terminalSafe(markdown.match(/^#\s+(.+)$/m)?.[1] ?? fallback).trim();
 var HEADING = /^(#{2,4})\s+(.*?)\s*$/;
+var subsectionStart = (markdown, headingText) => markdown.split("\n").findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText));
 var subsectionLines = (markdown, headingText) => {
   const lines = markdown.split("\n");
-  const start = lines.findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText));
+  const start = subsectionStart(markdown, headingText);
   if (start === -1) return [];
   const level = HEADING.exec(lines[start])?.[1].length ?? 2;
   const rest = lines.slice(start + 1);
@@ -102,6 +103,10 @@ var LANE_NAME = /`([^`]+)`/;
 var CONTINUATION = "\u21B3";
 var PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/;
 var PHASE_ID_PREFIX = "P";
+var LEADING_PHASE_ID = new RegExp(`^\\s*${PHASE_ID_PREFIX}?(\\d+[a-z]?)\\b`, "i");
+var phaseIdOf = (cell) => LEADING_PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null;
+var NO_DEPENDENCY_TABLE = "no dependency table: phases run one after another";
+var phaseCount = (count) => `${count} ${count === 1 ? "phase" : "phases"}`;
 var phaseLabel = (id) => `${PHASE_ID_PREFIX}${id}`;
 var MAX_RANGE = 50;
 var spannedPhaseIds = (first, last) => first > last || last - first >= MAX_RANGE ? [] : Array.from({ length: last - first + 1 }, (_, offset) => String(first + offset));
@@ -467,7 +472,6 @@ var shortTitle = (progress) => {
 
 // src/plan-format/dependencies.ts
 var ID = "(\\d+[a-z]?)";
-var PHASE_ID = new RegExp(`^\\s*${PHASE_ID_PREFIX}?${ID}\\b`, "i");
 var PHASE_RANGE = new RegExp(`^${PHASE_ID_PREFIX}?(\\d+)\\s*[\u2013-]\\s*${PHASE_ID_PREFIX}?(\\d+)$`, "i");
 var BACKTICKED = /`([^`]+)`/g;
 var NO_VALUE = /^[—–-]?$/;
@@ -476,7 +480,6 @@ var GLOB_CHARACTER = /[*?{[]/;
 var VERSION = /^v?\d+(?:[.\-+][\w.-]*)?$/i;
 var PACKAGE_SCOPE = /^@[^/]+\//;
 var RELEASE_FILE = /(?:^|\/)(?:CHANGELOG\.md|package\.json)$/;
-var phaseIdOf = (cell) => PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null;
 var splitOutsideParentheses = (cell, separator) => {
   const entries = [];
   let depth = 0;
@@ -749,11 +752,24 @@ var differsFromColumn = (column, modelId) => {
   return models.length > 0 && !models.some((model) => fits(tokens, model));
 };
 
+// src/plan-format/model-table.ts
+var parseModelTable = (markdown, language) => {
+  const heading = PLAN_VOCABULARY[language].sections.modelRecommendations;
+  const rows = firstTableRows(subsectionLines(markdown, heading));
+  if (rows.length === 0) return null;
+  const firstBodyLine = subsectionStart(markdown, heading) + 2;
+  return rows.flatMap(({ index, cells }) => {
+    const id = phaseIdOf(cells[0] ?? "");
+    const cell = cells[1] ?? "";
+    return id === null ? [] : [{ id, models: columnModels(cell), cell, line: firstBodyLine + index }];
+  });
+};
+
 // src/plan-format/phase-tally.ts
 var DONE_MARK = /^\s*[-*]\s\[x\]|\|\s*✅\s*\|/gim;
 var OPEN_MARK = /^\s*[-*]\s\[ \]|\|\s*⬜\s*\|/gm;
 var TRAILING_SEPARATOR = /[:—–-]\s*$/;
-var PHASE_ID2 = /^(\d+[a-z]?)/;
+var PHASE_ID = /^(\d+[a-z]?)/;
 var modelFor = (markdown, phaseWord, phaseTitle) => {
   const prefix = new RegExp(`^${escapeRegExp(phaseWord)}\\s*`, "i");
   const number = /^(\d+)/.exec(phaseTitle.replace(prefix, ""))?.[1];
@@ -765,7 +781,7 @@ var sectionOf = (section, heading, markdown, phaseWord) => {
   const match = heading.exec(section);
   if (!match) return null;
   const title = match[1].replace(TRAILING_SEPARATOR, "").trim();
-  const phaseId = PHASE_ID2.exec(title)?.[1]?.toLowerCase() ?? "";
+  const phaseId = PHASE_ID.exec(title)?.[1]?.toLowerCase() ?? "";
   const targets = section.split("\n").flatMap((line) => deferralTarget(line, phaseId) ?? []);
   const done = (section.match(DONE_MARK) ?? []).length;
   const open = (section.match(OPEN_MARK) ?? []).length - targets.length;
@@ -911,6 +927,7 @@ export {
   LANE_PROMPT_OPENING,
   LANGUAGE_NAME,
   NEXT_VOCABULARY,
+  NO_DEPENDENCY_TABLE,
   PHASE_CELL_LIMIT,
   PHASE_ID_PREFIX,
   PHASE_TITLE_LIMIT,
@@ -957,11 +974,14 @@ export {
   parallelGroups,
   parallelGroupsOfPlan,
   parseDependencyTable,
+  parseModelTable,
   parsePlanPhases,
   parseSprintLanes,
+  phaseCount,
   phaseHeading,
   phaseHeadingPattern,
   phaseHeadings,
+  phaseIdOf,
   phaseIdsOfCell,
   phaseIdsOfPlan,
   phaseLabel,

package/docs/plan-contract.md

@@ -0,0 +1,84 @@
+# The plan contract
+
+jackherd reads a plan from its Markdown. This is what a plan has to hold for the readers to find it, and how to check that with one command.
+
+## The four parts
+
+| Part | Form | Required | Read by |
+| ---- | ---- | -------- | ------- |
+| Phases | a heading per phase: `### Phase 1: Title` (also `## 1 — Title` or `## P1 — Title`) | yes | herd, watcher, `jh check`, lane start |
+| Tasks | at least one checkbox (`- [ ]`, `- [x]`) or a ✅/⬜ table row in every phase; a phase that points at a section (``See `## Documentation` ``) counts that section's checkboxes | yes | herd (progress), watcher, `jh check` |
+| Model | a table under `### Model recommendations per phase`: the phase in the first cell (`1 — Title`, `P1`, `10c`), the model in the second (`claude-opus-5-5`, `Opus 5.5`); a dash marks a phase that needs no model | yes | lane start (the model a lane runs on), `/implement` |
+| Dependencies | a table under `### Dependencies and parallelization` with the columns `Depends on`, `Writes`, `Serial marker` and one row per phase | from two phases on, optional | `jh check --parallel`, `/implement` |
+
+Details that decide a verdict:
+
+- A sub-phase (`3b`) is covered by the row of its base phase (`3`) in the model and the dependency table, or by a row of its own.
+- A model cell that names no model and is no dash is a gap: the lane would start on a guess.
+- With fewer than two phases the dependency part is reported `present` ("not needed"), never missing.
+- With two or more phases and no dependency table the plan is still valid: the phases run one after another. A table that is there but lacks a row for a phase is a gap.
+- The headings come from the plan language in `.jackherd/config.json` (`planLanguage`, `de` or `en`); the English ones are shown here.
+
+## Minimal valid plan
+
+```markdown
+# Search filter
+
+**Date:** YYYY-MM-DD
+**Status:** Draft
+
+## Implementation
+
+### Model recommendations per phase
+
+| Phase | Model | Rationale |
+| ----- | ----- | --------- |
+| 1 — Query parser | claude-sonnet-5-5 | pure functions, cheap to review |
+| 2 — Filter bar | claude-opus-5-5 | touches the shared state |
+
+### Dependencies and parallelization
+
+| Phase | Depends on | Writes | Serial marker |
+| ----- | ---------- | ------ | ------------- |
+| 1 | — | `src/query/` | — |
+| 2 | 1 | `src/ui/filter-bar/` | — |
+
+### Phase 1: Query parser
+
+- [ ] **Parse filters**: `parseQuery(text)` returns the filter list
+- [ ] **Test it**: every operator, one malformed input
+
+### Phase 2: Filter bar
+
+- [ ] **Render the bar**: one chip per filter
+```
+
+## Checking a plan
+
+```
+jh plan check <plan.md>
+```
+
+Prints one line per part, `file:line` where the part is incomplete. For the plan above:
+
+```
+phases: present plan.md:22 2 phases
+tasks: present plan.md:22 every phase has tasks
+model: present plan.md:12 every phase has a model
+dependencies: present every phase has a row
+```
+
+If the model table lacked the row for phase 2, and the dependency table were left out, the lines would read:
+
+```
+phases: present plan.md:22 2 phases
+tasks: present plan.md:22 every phase has tasks
+model: malformed plan.md:22 no model for P2
+dependencies: missing no dependency table: phases run one after another
+```
+
+| Exit | Meaning |
+| ---- | ------- |
+| 0 | the contract is met (a missing dependency table is a note, not a gap) |
+| 1 | at least one part is missing or malformed |
+| 2 | wrong command line: no subcommand, unknown subcommand, no file, unreadable file, unreadable config |