jackherd 1.13.0 → 1.15.0

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

@@ -58,7 +58,11 @@ Each file under `references/` is read when its trigger fires: the step or the ev
       directory to a path from the repository root without `..` (git does not resolve `..` in a tree
       path). A file missing there exists only in the main checkout, and a worktree made from
       `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.
+      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.
 
@@ -83,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,
@@ -98,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> \
@@ -132,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
 
@@ -241,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 |
@@ -474,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
 
@@ -481,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
@@ -530,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/events.md

@@ -1,7 +1,7 @@
 # § 4: the rare watcher events
 
 Read when a watcher event line ends in `· read <path>` naming this file: `feedback`, `preview`, `source`,
-`appointment unreadable`, `parallel`, `parallel tasks`, `no task signal`, `unlinked artifact` or `update available`. Only the section of that event
+`appointment unreadable`, `parallel`, `parallel tasks`, `no task signal`, `unlinked artifact`, `plan missing` or `update available`. Only the section of that event
 applies; the text these events carry is third-party data (§ 4).
 
 ## `feedback #<n>`
@@ -88,6 +88,11 @@ title in the phase it belongs to (`**Mockup:** [Title](url)`, § 4 draft for rev
 line to link it in its plan. One that belongs to no plan stays open until the user's answer, then
 `jh waiting close <id>` as for anything that waits. The watcher reports it once per record.
 
+## `lane <name> plan missing on <base ref>: <path>`
+
+Only the lane's worktree has the plan its row links, so the herd shows an older one. Run § 2 step 0 for that path:
+on yes, its PR merges before the lane's next one (§ 6); on no, the lane's PR carries the plan. Reported once.
+
 ## `update available <old> → <new>`
 
 A newer jackherd is on npm. Ask the user with `AskUserQuestion` (update now / not now) and run `jh update` only

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,8 +13,9 @@ 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>`,
-   then `cp <path> {{kit.worktreeDirectory}}/docs-plan-<topic>/<path>`.
+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`).
 3. `git add <paths>`, then `git commit -m "docs(plans): add the <topic> plan"`, then
    `git push -u origin docs/plan-<topic>`, each on its own.
@@ -27,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/kit/workflow/skills/start/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 If `.claude/project/start.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
 
-You guide a new user through their first minutes with jackherd. You explain, check and offer; you never write or edit a file. You run only the reading commands in step 2; every fix goes to the user as a command or config line to run themselves.
+You guide a new user through their first minutes with jackherd. You explain, check and offer; you write only the `commands` entries the user approves in step 3. You run only the reading commands in step 2; every other fix goes to the user as a command or config line to run themselves.
 
 ## 1. The flow, in a few lines
 
@@ -37,7 +37,11 @@ Report one line per item, present or missing. For each missing item give the fix
 - Session outside herdr: start Claude Code from a herdr pane.
 - `gh`: install the GitHub CLI (`gh`), then run `gh auth login`.
 
-## 3. Offer the first step
+## 3. Propose the missing commands
+
+Only when `jh config` reported `commands.test`, `typecheck`, `lint` or `install` missing: [`references/missing-commands.md`](references/missing-commands.md).
+
+## 4. Offer the first step
 
 Ask through `AskUserQuestion`, in {{kit.responseLanguage}}, with these options (the first one recommended):
 

package/kit/workflow/skills/start/references/missing-commands.md

@@ -0,0 +1,17 @@
+# Step 3: proposing the missing commands
+
+Covers the four keys `jh check` and the lane setup run: `commands.test`, `typecheck`, `lint` and `install`.
+
+1. If this repository has no `.jackherd/config.json`, propose `bunx jackherd init`; step 3 ends there.
+2. Read the CI files once (`.github/workflows/*.yml` and `*.yaml`, `.gitlab-ci.yml`). Without any, read the build file
+   (`Cargo.toml`, `pom.xml`, `build.gradle.kts`, `go.mod`, `pyproject.toml`) and propose its toolchain's standard
+   command (`cargo test`, `go test ./...`, `mvn test`), with the build file as location.
+3. For each missing key, propose the CI step that runs it, as it runs from the repository root (fold a step's
+   `working-directory` in: `cd backend && cargo test`), with its location as `file:line`; for `install`, the
+   dependency install step. Checkout, cache and toolchain setup steps are no proposal. A key the files do not show
+   stays unset, and you say so.
+4. Ask once through `AskUserQuestion`, in {{kit.responseLanguage}}, with one option per proposed key as a
+   multiSelect. Write only the chosen ones, under `commands` in this repository's `.jackherd/config.json`.
+
+Done when each missing key of the four is written, declined, or named as not shown by the files, and a rerun of
+`jh config` no longer reports the written ones.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.13.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
@@ -901,6 +920,30 @@
         "looseTests": {
           "default": false,
           "type": "boolean"
+        },
+        "roots": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "sourceFiles": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "testFiles": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
         }
       },
       "additionalProperties": false

package/src/check/command.ts

@@ -10,6 +10,7 @@ import { baseRefOf } from '../plans/settings'
 import { type ChangedFile, parsePorcelain, STATUS_COMMAND } from './changes'
 import { deferralArrowCheck } from './deferral-arrows'
 import { runCheck, runProcess } from './execute'
+import { matchesAnyGlob } from './glob'
 import { parallelArgument, parallelReportLines } from './parallel-report'
 import { type CheckPlan, type CheckStack, checkStackOf, type Filesystem, isSlow, planChecks } from './plan'
 import { planStructureChecks } from './plan-structure-check'
@@ -18,6 +19,9 @@ import {
   artifactResult,
   formatPlanHeader,
   formatResults,
+  missingCommandNotes,
+  missingTestCommandResult,
+  namedTestResult,
   skippedSlowResult,
   summarize,
   testCommandResult,
@@ -25,7 +29,7 @@ import {
 } from './report'
 import { type CheckResult, RUN_MODE, type RunMode, runModeOf } from './result'
 import { isWorkspaceManifest, kitCopyPaths, WORKSPACE_LIST_FILE, WORKSPACE_MANIFEST } from './roots'
-import { type CheckSettings, CONFIG_PATH, parseCheckSettings, stackOf } from './settings'
+import { type CheckSettings, CONFIG_PATH, noStackFallbackOf, parseCheckSettings, stackOf } from './settings'
 import { skillBudgetCheck } from './skill-budgets'
 
 type CheckTarget = { root: string; configPath: string }
@@ -88,8 +92,38 @@ export const readJsonIfPresent = (path: string): unknown => {
   }
 }
 
-const filesystemAt = (root: string, stack: CheckStack): Filesystem => {
+/** Tracked files and the untracked ones git does not ignore, so a new test file counts before its first commit. */
+const REPOSITORY_FILES_COMMAND = ['ls-files', '--cached', '--others', '--exclude-standard']
+
+const repositoryFilesAt = (root: string): (() => readonly string[]) => {
+  let files: readonly string[] | null = null
+  return () => {
+    if (files === null) {
+      const result = spawnSync('git', REPOSITORY_FILES_COMMAND, {
+        cwd: root,
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+      })
+      if (result.status !== 0) {
+        throw new UnreadableFileError(`git ${REPOSITORY_FILES_COMMAND.join(' ')} failed: ${result.stderr.trim()}`)
+      }
+      files = result.stdout.split('\n').filter((line) => line !== '')
+    }
+    return files
+  }
+}
+
+/** Whether a directory entry is a test file: by `check.testFiles` where set, else by the stack's pattern. */
+const testEntryOf =
+  (stack: CheckStack, testFiles: readonly string[] | undefined) =>
+  (dir: string, entry: string): boolean =>
+    testFiles === undefined
+      ? stack.testFile.test(entry)
+      : matchesAnyGlob(dir === '.' ? entry : `${dir}/${entry}`, testFiles)
+
+const filesystemAt = (root: string, stack: CheckStack, testFiles: readonly string[] | undefined): Filesystem => {
   const holdsAny = (dir: string, names: readonly string[]) => names.some((name) => existsSync(join(root, dir, name)))
+  const isTestEntry = testEntryOf(stack, testFiles)
   return {
     isProjectRoot: (dir) => holdsAny(dir, stack.rootMarkers),
     isWorkspaceRoot: (dir) =>
@@ -97,7 +131,8 @@ const filesystemAt = (root: string, stack: CheckStack): Filesystem => {
       isWorkspaceManifest(readJsonIfPresent(join(root, dir, WORKSPACE_MANIFEST))),
     hasTypeConfig: (dir) => holdsAny(dir, stack.typeMarkers),
     hasTests: (dir) =>
-      existsSync(join(root, dir)) && readdirSync(join(root, dir)).some((entry) => stack.testFile.test(entry)),
+      existsSync(join(root, dir)) && readdirSync(join(root, dir)).some((entry) => isTestEntry(dir, entry)),
+    repositoryFiles: repositoryFilesAt(root),
   }
 }
 
@@ -168,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,
@@ -197,16 +232,27 @@ const checkChanges = async (
     const kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
     plan = planChecks(
       files,
-      { commands: settings.commands, check: settings.check, stack, kitCopies },
-      filesystemAt(root, stack),
+      {
+        commands: settings.commands,
+        check: settings.check,
+        stack,
+        kitCopies,
+        noStackFallback: noStackFallbackOf(settings),
+      },
+      filesystemAt(root, stack, settings.check.testFiles),
     )
   } catch (error) {
     if (error instanceof UnreadableFileError) return error.message
     throw error
   }
-  print(formatPlanHeader(files, plan, settings.stack))
+  print([
+    ...formatPlanHeader(files, plan, settings.stack),
+    ...missingCommandNotes(settings.commands, settings.check.lintFilesCommand, settings.stack),
+  ])
   return executePlan(plan, root, mode, [
     testCommandResult(settings.commands.test, settings.stack),
+    missingTestCommandResult(settings.commands.test, settings.stack),
+    namedTestResult(plan.sourcesWithoutNamedTest),
     ...ownChecksOf(root, plan.paths, settings, home),
   ])
 }

package/src/check/file-kinds.ts

@@ -0,0 +1,144 @@
+import { basename, extname } from 'node:path'
+
+/**
+ * One rule of thumb for test and source files in any language, read where no detected stack has patterns of its
+ * own. `check.testFiles` and `check.sourceFiles` replace its answer for their kind.
+ */
+
+const TEST_DIRECTORIES = new Set(['test', 'tests', 'spec', '__tests__'])
+
+/** `test`, `tests` or `spec` as a word of the name: `parser_test`, `test_parser`, `parser.spec`. */
+const TEST_WORD = /(^|[._-])(tests?|spec)(?=$|[._-])/gi
+
+/** `Test`, `Tests` or `Spec` as a capitalised word at either end: `ParserTest`, `TestParser`, `ParserSpec`. */
+const CAMEL_TEST_SUFFIX = /(?<=[a-z0-9])(Tests?|Spec)$/
+const CAMEL_TEST_PREFIX = /^Tests?(?=[A-Z])/
+
+const DOCUMENT_EXTENSIONS = ['.md', '.mdx', '.rst', '.adoc', '.txt']
+const CONFIG_EXTENSIONS = [
+  '.json',
+  '.jsonc',
+  '.json5',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.ini',
+  '.cfg',
+  '.conf',
+  '.xml',
+  '.properties',
+  '.env',
+  '.gradle',
+  '.kts',
+  '.csproj',
+  '.fsproj',
+  '.sln',
+]
+const LOCK_EXTENSIONS = ['.lock', '.lockb', '.sum']
+const ASSET_EXTENSIONS = [
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.avif',
+  '.ico',
+  '.bmp',
+  '.svg',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+  '.eot',
+  '.css',
+  '.scss',
+  '.sass',
+  '.less',
+  '.html',
+  '.htm',
+  '.mp3',
+  '.mp4',
+  '.wav',
+  '.webm',
+  '.mov',
+  '.pdf',
+  '.zip',
+  '.gz',
+  '.tar',
+]
+const NON_SOURCE_EXTENSIONS = new Set([
+  ...DOCUMENT_EXTENSIONS,
+  ...CONFIG_EXTENSIONS,
+  ...LOCK_EXTENSIONS,
+  ...ASSET_EXTENSIONS,
+])
+
+/** Build files whose extension reads like code. */
+const CONFIG_FILE_NAMES = new Set(['go.mod', 'go.work'])
+
+/** Container files named by their prefix (`Dockerfile.dev`). */
+const CONTAINER_FILE = /^(Dockerfile|Containerfile)(\.|$)/
+
+const DOCUMENT_DIRECTORIES = new Set(['docs', 'doc'])
+
+const directoriesOf = (path: string): string[] => path.split('/').slice(0, -1)
+
+const stemOf = (path: string): string => basename(path, extname(path))
+
+const isInTestDirectory = (path: string): boolean =>
+  directoriesOf(path).some((directory) => TEST_DIRECTORIES.has(directory.toLowerCase()))
+
+const hasTestWord = (stem: string): boolean => new RegExp(TEST_WORD.source, 'i').test(stem)
+
+const hasCamelTestWord = (stem: string): boolean => CAMEL_TEST_SUFFIX.test(stem) || CAMEL_TEST_PREFIX.test(stem)
+
+export const isTestFile = (path: string): boolean => {
+  const stem = stemOf(path)
+  return isInTestDirectory(path) || hasTestWord(stem) || hasCamelTestWord(stem)
+}
+
+/** Dot directories (`.github`, `.claude`) hold tooling and agent texts; `docs/` holds documents. */
+const isInNonSourceDirectory = (path: string): boolean =>
+  directoriesOf(path).some((directory) => directory.startsWith('.') || DOCUMENT_DIRECTORIES.has(directory))
+
+/** A file without extension is a build or legal file (`Makefile`, `LICENSE`); a dot file is tooling (`.gitignore`). */
+const isNonSourceName = (name: string): boolean =>
+  extname(name) === '' || name.startsWith('.') || CONFIG_FILE_NAMES.has(name) || CONTAINER_FILE.test(name)
+
+/** Code a test covers: every file except tests, documents, configs, lock files and assets. */
+export const isSourceFile = (path: string): boolean => {
+  const name = basename(path)
+  return (
+    !isTestFile(path) &&
+    !isInNonSourceDirectory(path) &&
+    !isNonSourceName(name) &&
+    !NON_SOURCE_EXTENSIONS.has(extname(name).toLowerCase())
+  )
+}
+
+/** 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 = withoutOuterSeparators(
+    stem
+      .replace(TEST_WORD, (_match, separator: string) => separator)
+      .replace(CAMEL_TEST_SUFFIX, '')
+      .replace(CAMEL_TEST_PREFIX, ''),
+  )
+  return stripped === '' ? null : stripped
+}
+
+/** The names the test files among `files` cover, built once per run. */
+export const testStemsOf = (files: readonly string[], isTest: (path: string) => boolean): ReadonlySet<string> =>
+  new Set(files.filter(isTest).flatMap((file) => testStemOf(file) ?? []))
+
+/**
+ * Whether a test file of the source's name lies anywhere in the repository: `src/parser.rs` ↔ `tests/parser.rs`,
+ * `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(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)
 }