jackherd 1.9.0 → 1.10.0

package/kit/hooks/hooks/task-hint/run.ts

@@ -0,0 +1,62 @@
+import { isHintOn } from '../shared/config'
+import { isWithinDirectory } from '../shared/files'
+import { firstPromptOf, isLanePrompt } from '../shared/transcript'
+import { decideTaskHint, hasTaskInProgress, TASK_HINT_SUBAGENT_TEXT, TASK_HINT_TEXT } from './decision'
+
+/** An Edit, Write or Agent call as the hook receives it: the session, its directory, its transcript and the tool. */
+export type TaskHintCall = { session: string; cwd: string; transcriptPath: string; tool: string }
+
+/** The tool that starts a subagent. */
+const SUBAGENT_TOOL = 'Agent'
+
+/** Everything with a side effect, passed in so a test reaches the flow without git, files or a home directory. */
+export type TaskHintDependencies = {
+  mainCheckoutOf: (cwd: string) => string
+  repositoryRootOf: (cwd: string) => string
+  /** The parsed configs, the main checkout's first, then the home directory's. */
+  configs: (root: string) => Record<string, unknown>[]
+  /** The first lines of the transcript, which hold the session's first prompt. */
+  readHead: (path: string) => string[]
+  /** The last lines of the transcript, which hold the task list's latest state. */
+  readTail: (path: string) => string[]
+  /** The directories of the open `jh task` records in the main checkout. */
+  openTaskDirectories: (main: string) => string[]
+  /** Whether this session was hinted for its current task already. */
+  readMark: (main: string, session: string) => boolean
+  writeMark: (main: string, session: string, hinted: boolean) => void
+}
+
+const isSignalled = (call: TaskHintCall, main: string, worktree: string, dependencies: TaskHintDependencies): boolean =>
+  dependencies.openTaskDirectories(main).some((directory) => isWithinDirectory(directory, worktree)) ||
+  hasTaskInProgress(dependencies.readTail(call.transcriptPath))
+
+const hintFor = (call: TaskHintCall, dependencies: TaskHintDependencies): string | null => {
+  const main = dependencies.mainCheckoutOf(call.cwd)
+  const worktree = dependencies.repositoryRootOf(call.cwd)
+  const hinted = dependencies.readMark(main, call.session)
+  const subagent = call.tool === SUBAGENT_TOOL
+  const decision = decideTaskHint({
+    enabled: isHintOn(dependencies.configs(main), 'taskSignal'),
+    lane: isLanePrompt(firstPromptOf(dependencies.readHead(call.transcriptPath).join('\n'))),
+    signalled: isSignalled(call, main, worktree, dependencies),
+    hinted,
+    subagent,
+  })
+  if (decision.hinted !== hinted) dependencies.writeMark(main, call.session, decision.hinted)
+  if (!decision.hint) return null
+  return subagent ? TASK_HINT_SUBAGENT_TEXT : TASK_HINT_TEXT
+}
+
+/**
+ * The hint after an Edit, Write or Agent call in a lane without an open task signal (D112): a `jh task` record whose
+ * directory lies in the session's worktree, or a task of the session's own list in progress. Once per task for an edit:
+ * the mark set by the hint is cleared by the next signal; at every subagent started without one. Only a session whose first prompt opens a lane is hinted; any failure answers
+ * nothing, so the edit is never held up.
+ */
+export const runTaskHint = (call: TaskHintCall, dependencies: TaskHintDependencies): string | null => {
+  try {
+    return hintFor(call, dependencies)
+  } catch {
+    return null
+  }
+}

package/kit/hooks/hooks/task-hint/store.ts

@@ -0,0 +1,51 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isRecord } from '../shared/json'
+import { writePrivateRecord } from '../shared/private-directory'
+
+const TASK_RECORD_FILE = /^[0-9a-f]{12}\.json$/
+const SESSION_ID = /^[A-Za-z0-9-]{1,64}$/
+const MAX_RECORD_BYTES = 16 * 1024
+
+/** Where `jh task start` keeps its records, in the main checkout. */
+const tasksDirectory = (main: string): string => join(main, '.jackherd', 'tasks')
+
+/** Where the hook marks the sessions it hinted, beside the task records. Ignored by git. */
+const hintsDirectory = (main: string): string => join(main, '.jackherd', 'task-hints')
+
+const parsedFile = (path: string): unknown => {
+  try {
+    const entry = lstatSync(path)
+    return entry.isFile() && entry.size <= MAX_RECORD_BYTES ? JSON.parse(readFileSync(path, 'utf8')) : null
+  } catch {
+    return null
+  }
+}
+
+/** The directories of the open `jh task` records; a link, a file over 16 KiB and a malformed record are skipped. */
+export const openTaskDirectories = (main: string): string[] => {
+  const directory = tasksDirectory(main)
+  try {
+    return readdirSync(directory)
+      .filter((name) => TASK_RECORD_FILE.test(name))
+      .flatMap((name) => {
+        const record = parsedFile(join(directory, name))
+        return isRecord(record) && record.closedAt === null && typeof record.cwd === 'string' ? [record.cwd] : []
+      })
+  } catch {
+    return []
+  }
+}
+
+/** Whether the session was hinted for its current task; false without a mark or for an id that is no plain name. */
+export const readHintMark = (main: string, session: string): boolean => {
+  if (!SESSION_ID.test(session)) return false
+  const mark = parsedFile(join(hintsDirectory(main), `${session}.json`))
+  return isRecord(mark) && mark.hinted === true
+}
+
+/** Writes the session's mark; throws for an id that is no plain name, so nothing is written outside the directory. */
+export const writeHintMark = (main: string, session: string, hinted: boolean): void => {
+  if (!SESSION_ID.test(session)) throw new Error('session id is no plain name')
+  writePrivateRecord(hintsDirectory(main), { id: session, hinted })
+}

package/kit/hooks/hooks.json

@@ -39,7 +39,7 @@
     "matcher": "Bash",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/index.ts '{{kit.guard.selfMergeLabel}}' '{{kit.guard.planApproval.approve}}' || exit 2",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/index.ts '{{kit.guard.selfMergeLabel}}' '{{kit.guard.standingApproval.approve}}' '{{kit.guard.standingApproval.until}}' || exit 2",
       "timeout": 10,
       "onFailure": "block"
     }
@@ -61,12 +61,11 @@
       "timeout": 10
     }
   },
-  "plan-approval": {
-    "event": "PostToolUse",
-    "matcher": "AskUserQuestion",
+  "open-question": {
+    "event": "Stop",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/plan-approval-record.ts '{{kit.guard.planApproval.approve}}' '{{kit.guard.planApproval.revoke}}'",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/open-question/index.ts",
       "timeout": 10
     }
   },
@@ -79,6 +78,15 @@
       "timeout": 10
     }
   },
+  "task-hint": {
+    "event": "PostToolUse",
+    "matcher": "Edit|Write|Agent",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/task-hint/index.ts",
+      "timeout": 10
+    }
+  },
   "watch-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",

package/kit/review/agents/skill-review.md

@@ -0,0 +1,34 @@
+---
+name: skill-review
+description: 'Agent Text Review: does a change to a skill, agent, rule, project supplement or CLAUDE.md still steer the agent that reads it? Use when /pre-commit routes a change to agent texts.'
+model: {{kit.model.review}}
+tools: Read, Grep, Glob
+user-invocable: false
+---
+
+Read `.claude/rules/kit/writing-for-agents.md` first, then the project's `.claude/rules/writing-for-agents.md` if it exists, then `.claude/project/skill-review.md` if it exists. They carry the levers this review applies; the project files win where they disagree with the kit.
+
+You receive the `git diff` of agent texts: skills, agents, rules, project supplements, `CLAUDE.md`, `AGENTS.md`. Judge only the lines the diff adds, changes or removes, a moved passage where its trigger or rung changed; the rest of a file is context. A budget, a broken link, a required rule and a trigger in the first lines are measured by `jh check`, so leave them to it.
+
+## What is a finding
+
+Check every changed passage against each lens; a passage that passes all six needs no row.
+
+1. **No-op:** the sentence changes nothing against what the model does by default. Delete the sentence, never trim it.
+2. **Same meaning twice:** the passage restates, in other words, what the skill, its project supplement, a rule, `CLAUDE.md` or a memory file the caller names already carries. Grep for the key terms before you call it new; name the other place. A passage removed in favour of a pointer is lost when the target lacks part of it.
+3. **Wrong rung:** a step every run takes sits in a disclosed reference, or reference only some branches reach sits in the core, or a lasting reason that explains the code belongs in `ARCHITECTURE.md` rather than in a text loaded on every run.
+4. **Late trigger:** a pointer to a reference or another document names its condition after the content, or fires at a moment the agent has already passed.
+5. **Negation:** the passage steers by prohibition where a target could be stated; a hard guardrail stays, paired with its target.
+6. **Open step:** a step ends without a condition the agent can check, so done and not done look alike.
+
+## Output
+
+```markdown
+## Agent Text Review — PASS | PASS WITH NOTES | FIX FIRST
+
+| File:line | Lens | Passage | Proposal |
+|---|---|---|---|
+| skills/x/SKILL.md:14 | same meaning twice (rules/y.md:8) | "…" | delete; the rule carries it |
+```
+
+`FIX FIRST` for a duplicate that already disagrees with its other copy, or a step that lost its completion criterion; `PASS WITH NOTES` for the other findings; `PASS` with no row. Quote the passage so the author finds it. Your output is the report; applying a proposal is the caller's decision.

package/kit/review/skills/pre-commit/SKILL.md

@@ -25,7 +25,7 @@ Run `/review` for what the command cannot decide: dead exports, naming, function
 
 ## Step 3: Specialized Reviewers
 
-**Step 1 printed the reviewer list** (`Reviewers: …`, from `check.reviewerRoutes`) — dispatch exactly those, each as a subagent via the `Agent` tool with its `subagent_type`:
+**Step 1 printed the reviewer list** (`Reviewers: …`, from `check.reviewerRoutes`, plus `check.publicContent` and `skill-review` for changed agent texts) — dispatch exactly those, each as a subagent via the `Agent` tool with its `subagent_type`:
 
 - Pass in the `prompt`: the `git diff` of the relevant files and the file paths.
 - Start all of them **in parallel**, in a single message, and wait for every result before step 4.

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

@@ -30,14 +30,7 @@ Anything missing goes to the user as the command to run themselves (`! <command>
 
 Before filling, read the help of the installed CLI version for every command the recipe calls (`acli jira workitem search --help` and `workitem view --help`, `gh issue list --help`) and confirm that the fields and options the entry needs exist there. Read the provider's web documentation only when the help leaves it open or no recipe fits. A recipe is a starting point; the installed version decides.
 
-Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors` and `ticket` where chosen. For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it, from the recipe's script under `recipes/sources/`, to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. The script:
-
-- bounds every request and every call of a tool with `AbortSignal.timeout(20_000)`, where a shell recipe would use `--max-time`;
-- reads a token only from `process.env`, and never prints it, passes it as an argument or writes it into an output;
-- ends with `process.exit(1)` when the token is missing, the answer is not 2xx (or carries an `errors` list, as GraphQL does with a 200) or a tool it calls fails, without printing the answer's body, so a failure is an exit code and never an empty list the watcher would take for a source with nothing new;
-- prints one JSON value on stdout and nothing else.
-
-A recipe that needs no script (`gh …`, `curl` on a public page, `curl --netrc`) stays a direct command. Write `bun` as the program, never an absolute path to it: the watcher starts a source without a shell and resolves `bun` to the Bun that runs the watcher, and a path in the config would differ from machine to machine.
+Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors` and `ticket` where chosen. For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it, from the recipe's script under `recipes/sources/`, to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. Script and direct command follow the index's **Rules every recipe follows**.
 
 Write the entry as one JSON object to a draft file in the scratchpad and run, from the main checkout:
 

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

@@ -19,16 +19,15 @@ You are the **Implementer**. Your job is to carry tasks through completely: expl
 1. Read the model recommended for the phase from the table.
 2. Compare it with the model your current run is on:
    - **Same model** → continue with step 1.
-   - **Any other model, stronger or weaker** → delegate the phase to a subagent with the recommended model: `Agent(subagent_type: 'implement', model: <recommended>, prompt: …)`. Hand it what you already know (files located, decisions made, the phase's review gate) so it does not repeat the exploration. The prompt names the phase as `Phase P<n>` and the plan by its path from the repository root, the one form the kit's hooks read: `model-gate` stops a start on a weaker model than the table's, `model-log` records the model the subagent ran on for the herd. It ticks its phase's tasks itself as it finishes them (see Plan Hygiene). You stay the orchestrator: the review gate, gate verification, the arc42 and architecture checks and `/pre-commit` stay with you.
-3. **The recommendation is a choice, not a floor.** The table records the tier the plan's author judged right for the error cost; a model cannot switch itself, so spawning the subagent is the way to apply it.
+   - **Any other model, stronger or weaker** (the recommendation is a choice, not a floor) → delegate the phase to a subagent with the recommended model: `Agent(subagent_type: 'implement', model: <recommended>, description: …, prompt: …)`, the `description` as in Step 0b item 3. Hand it what you already know (files located, decisions made, the phase's review gate) so it does not repeat the exploration. The prompt names the phase as `Phase P<n>` and the plan by its path from the repository root: then `model-gate` stops a start on a weaker model and `model-log` records the model for the herd. It ticks its phase's tasks itself as it finishes them (see Plan Hygiene). You stay the orchestrator: the review gate, gate verification, the arc42 and architecture checks and `/pre-commit` stay with you.
 
 ## Step 0b: Parallel Gate (plans with a `{{kit.heading.dependencies}}` table)
 
 When the user asks for more than one phase:
 
-1. **Read the computed waves:** run `jh check --parallel <plan>`. It reads the plan's `{{kit.heading.dependencies}}` table and the plan's ticks and prints one line per wave of phases that can run side by side, in order (`wave 1: P19 ∥ P20`), then `critical path: …` and `in no wave: …`; wave 1 can start now, each later wave once the waves before it are done. A phase is ready when every `{{kit.heading.dependsOn}}` entry is done (ticked off with its review gate); a phase with an external gate (`User: …`) is never ready, since the plan cannot say the gate holds. Two phases share a wave only with no shared path under `{{kit.heading.writes}}`, no shared `{{kit.heading.serialMarker}}` (compared without case), and no release of the same package: a marker `Release <package> <version>`, or the package's `CHANGELOG.md` or `package.json` under `{{kit.heading.writes}}`. Only backticked paths count, written from the repository root; a directory overlaps every file below it, a glob counts as the directory before its first wildcard, and a wildcard at the root (`*.md`) overlaps everything. A `like N` entry (`wie N`, the plan's own word) in the cell, with several phases (`like 15 and 16`) as their union, adds the sets of those phases. `no dependency table` means the plan has none: the phases run one after the other. `no phase is ready` means every open phase waits, is done, or is in no wave.
+1. **Read the computed waves:** run `jh check --parallel <plan>`. It prints one line per wave of phases that can run side by side, in order (`wave 1: P19 ∥ P20`), then `critical path: …` and `in no wave: …`; wave 1 can start now, each later wave once the waves before it are done. A phase is ready once every `{{kit.heading.dependsOn}}` entry is ticked off with its review gate; one with an external gate (`User: …`) never is. Two phases share a wave only with no overlapping backticked path under `{{kit.heading.writes}}` (a `like N` entry adds that phase's set), no shared `{{kit.heading.serialMarker}}`, and no release of the same package: a marker `Release <package> <version>`, or the package's `CHANGELOG.md` or `package.json` under `{{kit.heading.writes}}`. `no dependency table`: the phases run one after the other. `no phase is ready`: every open phase waits, is done, or is in no wave.
 2. **Batch:** the requested phases in wave 1. A requested phase in a later wave waits, naming the phase it collides with. One in no wave is not ready for one of these reasons: it has an external gate (ask whether the gate holds), its `like N` entry names an unknown phase or runs in a cycle, its `{{kit.heading.writes}}` cell has no backticked path, or it depends on such a phase; say which. The command checks paths, markers and releases only: two phases that collide in content stay your judgement, so serialise them yourself.
-3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. They may run in the background; a hand-over (Step 7) waits until all are back. Each prompt names its phase (`Phase P<n>` and the plan's path, as in Step 0) and its `{{kit.heading.writes}}` set as the **only** paths it may edit, besides ticking its own phase's task lines in the plan, and states that it ticks the task checkboxes of its own phase as it finishes each one (Plan Hygiene), and leaves the review gate, commits and `/pre-commit` to you — it reports changed files, test results and the gate items it ran.
+3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, description: …, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. The `description` starts with the short name of the task the subagent works on, the first open one of its phase, then the phase: `<Name> · P<n>`; the herd puts its `▶` on that task. Without a short name, the phase alone. They may run in the background; a hand-over (Step 7) waits until all are back. Each prompt names its phase (`Phase P<n>` and the plan's path, as in Step 0) and its `{{kit.heading.writes}}` set as the **only** paths it may edit, besides ticking its own phase's task lines in the plan, and states that it ticks the task checkboxes of its own phase as it finishes each one (Plan Hygiene), and leaves the review gate, commits and `/pre-commit` to you — it reports changed files, test results and the gate items it ran.
 4. **When the batch returns:** check each report against its set (`git diff --stat`; an edit outside the set is a finding; a ticked line outside its own phase is one too), tick what it left open, walk each review gate. Gate items that write outside a phase's set (documentation, a changelog entry, plan synchronisation) are yours, at the wave's end. Then recompute the ready set and dispatch the next batch.
 5. **Commits stay serial and with you:** one `/pre-commit` per finished phase, in phase order; in a lane under `/orchestrate`, one per pull request (orchestrate skill § 5).
 
@@ -36,6 +35,7 @@ When the user asks for more than one phase:
 
 - **Tick off tasks as you go.** As soon as a task is done, set `- [ ]` → `- [x]` in the plan document, right then, so the plan reflects real progress and the herd shows it while the phase runs.
 - **A subagent ticks only its own phase,** and only with `Edit` on the exact task line (enough of it to be unique in the file). Never `Write` the plan or rewrite it with a script: parallel subagents share the file, and `Edit` applies its replacement to the file as it is on disk, so ticks in other phases survive, while a whole-file write from an older read erases them. A line that is not unique, and every review-gate item, stays with the caller.
+- **A task you add starts with its short name:** `- [ ] **Name**: …`, the name 40 characters at most, naming the subject and the result; how, conditions, origin and evidence follow the colon (`/plan`, step 2). A task the user adds later ends with `(User <DD.MM.> <HH:MM>)`.
 - **The review gate is binding.** A phase is finished once its review gate has been walked through completely and ticked off; only then comes the next phase or `/pre-commit`. Gate items that name a skill (`/uncle-bob`, `/security-audit`, …) are ticked after the skill has actually run.
 
 ## Step 1: Explore
@@ -54,6 +54,8 @@ Before you write a single line:
 
 Follow `.claude/rules/kit/code-style.md`: types → pure functions → higher-order functions, names that reveal intent, no section-label comments.
 
+Write code and tests with Write and Edit, never through a here-document or a script in Bash: such a call shows the reviewer no diff, and an unquoted or unreadable one can stop at a guard.
+
 ## Step 3: Verify
 
 After each changed file:
@@ -91,7 +93,7 @@ The report at the end is short: one line of diff stat, one line per check with i
 
 `git add`, `git commit`, `git fetch`, `git rebase` and `git push` each run as a Bash command of their own, with no check or other step joined to them by `&&`, `||`, `;`, a pipe or a line break. The checks run as separate commands before and after. The order is: checks, commit, fetch, rebase, checks again, push. Push only once the checks after the rebase are green. The checks again run only where the rebase brought in changes to your package roots or plans, all of them when in doubt (orchestrate skill § 6).
 
-Why: Claude Code checks permissions per subcommand and splits a command at `&&`, `||`, `;`, `|`, `|&`, `&` and newlines (Claude Code docs, page "Configure permissions", section "Compound commands"). A chained command cannot be approved as one: the dialog cannot vouch for what follows the first part, and whoever confirms for you cannot confirm it either.
+Why: a chained command cannot be approved as one (Claude Code docs, "Configure permissions", section "Compound commands").
 
 ## Step 7: Phase Boundary
 
@@ -103,6 +105,6 @@ Runs once the phase's review gate is ticked off, committed or not (a lane under
    bunx jackherd context
    ```
 
-   It prints one line of JSON with `tokens`, `share` and `level` (`ok`, `warn` or `alert`, from the token thresholds `plans.context.warnTokens` and `alertTokens`), or `null` when there is no value (no terminal adapter, no log). `null` or `ok` → continue with the next phase in this chat, and say nothing about it. A line on stderr that the auto-compact window is not above `alertTokens` means Claude Code compacts before this hand-over: name it in one line of your report.
+   `null` or `level` `ok` → continue with the next phase in this chat, and say nothing about it. A line on stderr that the auto-compact window is not above `plans.context.alertTokens` means Claude Code compacts before this hand-over: name it in one line of your report.
 2. `warn` or `alert`, and a next phase exists → the next phase runs in a new chat, without a question: go on with step 3, once every subagent you started is back, no dialog of yours is open and no question of yours waits for an answer. The same holds when Jack, the coordinator, asked this lane for its hand-over.
 3. Write the hand-over to `.claude/handover/<lane>.md` (`<lane>` is the name of the worktree directory; the directory is ignored by git and stays out of every commit) and end your turn with its path. The file holds, in this order: the line `{{kit.word.openSubagents}}: 0`, which the coordinator requires, the state (branch, commits or uncommitted changes, what is merged), the open points, the next step (after a wave, the state of each of its phases), the traps you ran into, and links to the plan and the files that matter. Jack ends this agent and starts a fresh one in the same worktree with the hand-over as its first task; without a coordinator, the last line names the fill and tells the user to start a new chat with that file.