jackherd 1.16.0 → 1.17.0

package/kit/hooks/hooks/plain-question/run.ts

@@ -9,16 +9,23 @@ const LANE_DIRECTORY = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/
 
 const strings = (values: unknown[]): string[] => values.filter((value): value is string => typeof value === 'string')
 
+/** The objects of a list, or none when it is no list: the questions of a dialog, the options of a question. */
+export const recordsOf = (values: unknown): Record<string, unknown>[] =>
+  Array.isArray(values) ? values.filter(isRecord) : []
+
+/** The questions of an `AskUserQuestion` input; none when it is no object or has no list of them. */
+export const questionsOf = (toolInput: unknown): Record<string, unknown>[] =>
+  isRecord(toolInput) ? recordsOf(toolInput.questions) : []
+
 const optionTexts = (options: unknown): string[] =>
-  Array.isArray(options) ? options.filter(isRecord).flatMap((option) => strings([option.label, option.description])) : []
+  recordsOf(options).flatMap((option) => strings([option.label, option.description]))
 
 /** The texts a dialog shows the user: each question, its header chip, and every option's label and description. */
-export const dialogTextsOf = (toolInput: unknown): string[] => {
-  if (!isRecord(toolInput) || !Array.isArray(toolInput.questions)) return []
-  return toolInput.questions
-    .filter(isRecord)
-    .flatMap((question) => [...strings([question.question, question.header]), ...optionTexts(question.options)])
-}
+export const dialogTextsOf = (toolInput: unknown): string[] =>
+  questionsOf(toolInput).flatMap((question) => [
+    ...strings([question.question, question.header]),
+    ...optionTexts(question.options),
+  ])
 
 /** Every plan the boards link, relative to the repository, once; a path that leaves the repository is dropped. */
 export const planPathsOfBoards = (boards: readonly Board[], language: BoardLanguage): string[] => [

package/kit/hooks/hooks/shared/standing-mark.ts

@@ -0,0 +1,104 @@
+/**
+ * A standing approval: the user's answer to a dialog whose question carries ``<Key> `<subject>` <until> <YYYY-MM-DD HH:MM>``
+ * lifts a question about that subject until that moment, at most 24 hours after the answer. The key names what is
+ * approved (`Plan` for the merges of a plan's lanes, `Environment` for the calls against an environment), so two kinds
+ * never read each other's questions. The newest answer to a question naming the subject decides; any other label ends
+ * the approval, also on a question without an end: in doubt it ends.
+ */
+import type { DialogAnswer } from './dialog-answer'
+import { MS_PER_MINUTE } from './fresh'
+import { newestVerdict } from './newest-verdict'
+
+/** The exact option label that approves, and the word before the end in the question, both per response language. */
+export type StandingLabels = { approve: string; until: string }
+
+/** What a kind of standing approval is about: the word before the subject, and which subjects it accepts. */
+export type StandingKind = { key: string; isSubject: (subject: string) => boolean }
+
+/** A subject approved until `until`, in milliseconds. */
+export type StandingMark = { subject: string; until: number }
+
+export const MAX_STANDING_MINUTES = 24 * 60
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** A local moment from its parts; undefined for one the calendar or the clock does not have (Feb 30, 24:00, a DST gap). */
+const localMoment = ([year, month, day, hour, minute]: number[]): number | undefined => {
+  const date = new Date(year, month - 1, day, hour, minute)
+  const exact =
+    date.getFullYear() === year &&
+    date.getMonth() === month - 1 &&
+    date.getDate() === day &&
+    date.getHours() === hour &&
+    date.getMinutes() === minute
+  return exact ? date.getTime() : undefined
+}
+
+/** The subject and the end a question names as ``<Key> `<subject>` <until> YYYY-MM-DD HH:MM``; none for none or several. */
+export const standingMarkOf = (question: string, kind: StandingKind, until: string): StandingMark | undefined => {
+  if (until === '') return undefined
+  const pattern = `\\b${escapeRegExp(kind.key)} \`([^\`]*)\` ${escapeRegExp(until)} (\\d{4})-(\\d{2})-(\\d{2}) (\\d{2}):(\\d{2})(?!\\d)`
+  const marks = [...question.matchAll(new RegExp(pattern, 'g'))]
+  if (marks.length !== 1) return undefined
+  const [, subject, ...parts] = marks[0]
+  const end = localMoment(parts.map(Number))
+  return end !== undefined && kind.isSubject(subject) ? { subject, until: end } : undefined
+}
+
+/** The one subject a question names as ``<Key> `<subject>` ``, with or without an end; none for none or several. */
+const namedSubjectOf = (question: string, kind: StandingKind): string | undefined => {
+  const mention = new RegExp(`\\b${escapeRegExp(kind.key)} \`([^\`]*)\``, 'g')
+  const subjects = new Set([...question.matchAll(mention)].map(([, subject]) => subject))
+  const [only] = subjects
+  return subjects.size === 1 && kind.isSubject(only) ? only : undefined
+}
+
+/**
+ * The subject an answer speaks about, and the end its question names; `NaN` for a question that names the subject
+ * without an end, which never approves but, answered with anything else, ends the approval: in doubt it ends.
+ */
+const markOf = (question: string, kind: StandingKind, until: string): StandingMark | undefined => {
+  const mark = standingMarkOf(question, kind, until)
+  if (mark !== undefined) return mark
+  const subject = namedSubjectOf(question, kind)
+  return subject === undefined ? undefined : { subject, until: Number.NaN }
+}
+
+type MarkedAnswer = DialogAnswer & { mark: StandingMark }
+
+const approves = ({ answer, offered, answeredAt, mark }: MarkedAnswer, label: string): boolean =>
+  label !== '' &&
+  answer === label &&
+  offered.includes(label) &&
+  mark.until > answeredAt &&
+  mark.until - answeredAt <= MAX_STANDING_MINUTES * MS_PER_MINUTE
+
+/** The approval the newest answers about one subject give: all of them approve, and the earliest end is still ahead. */
+const grantOf = (subject: string, answers: readonly MarkedAnswer[], label: string, now: number): StandingMark[] => {
+  const verdict = newestVerdict(answers, now)
+  if (verdict.length === 0 || !verdict.every((answer) => approves(answer, label))) return []
+  const until = Math.min(...verdict.map(({ mark }) => mark.until))
+  return until > now ? [{ subject, until }] : []
+}
+
+/** The subjects of this kind the user approved standing in these dialog answers, and until when; only those holding at `now`. */
+export const standingGrants = (
+  answers: readonly DialogAnswer[],
+  kind: StandingKind,
+  labels: StandingLabels,
+  now: number,
+): StandingMark[] => {
+  const marked = answers.flatMap((answer): MarkedAnswer[] => {
+    const mark = markOf(answer.question, kind, labels.until)
+    return mark === undefined ? [] : [{ ...answer, mark }]
+  })
+  const subjects = [...new Set(marked.map(({ mark }) => mark.subject))]
+  return subjects.flatMap((subject) =>
+    grantOf(
+      subject,
+      marked.filter(({ mark }) => mark.subject === subject),
+      labels.approve,
+      now,
+    ),
+  )
+}

package/kit/hooks/hooks.json

@@ -3,7 +3,7 @@
     "event": "PermissionRequest",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/approval-gate/index.ts '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.approval.pending}}' '{{kit.approval.denied}}'",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/approval-gate/index.ts '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.approval.pending}}' '{{kit.approval.denied}}' '{{kit.guard.standingApproval.approve}}' '{{kit.guard.standingApproval.until}}'",
       "timeout": 600
     }
   },
@@ -34,6 +34,15 @@
       "onFailure": "block"
     }
   },
+  "lane-start-guard": {
+    "event": "PreToolUse",
+    "matcher": "Bash",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && { input=$(cat); case \"$input\" in *herdr*) printf '%s' \"$input\" | bun .claude/hooks/lane-start-guard/index.ts;; esac; }",
+      "timeout": 10
+    }
+  },
   "merge-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",
@@ -74,7 +83,7 @@
     "matcher": "AskUserQuestion",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/plain-question/index.ts",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/plain-question/index.ts '{{kit.question.recommended}}' '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.guard.selfMergeLabel}}' '{{kit.guard.standingApproval.approve}}'",
       "timeout": 10
     }
   },

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

@@ -8,11 +8,11 @@ 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.
+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. Length: a finding when the diff takes a file over its target or grows one already over, per the `hint:` lines of the `Skill budgets` result /pre-commit passes; that result missing is a finding. `jh check` measures `Lint pointers`; lens 7 judges what its patterns miss.
 
 ## What is a finding
 
-Check every changed passage against each lens; a passage that passes all six needs no row.
+Check every changed passage against each lens; a passage that passes all seven 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.
@@ -20,6 +20,7 @@ Check every changed passage against each lens; a passage that passes all six nee
 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.
+7. **Lint-shaped prose:** a rule the project's linter can check, without a `lint:` pointer. Propose the lint rule plus the pointer.
 
 ## Output
 

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

@@ -27,7 +27,7 @@ Run `/review` for what the command cannot decide: dead exports, naming, function
 
 **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.
+- Pass in the `prompt`: the `git diff` of the relevant files and the file paths; to `skill-review`, also the `Skill budgets` and `Lint pointers` results of the latest `jh check` run.
 - Start all of them **in parallel**, in a single message, and wait for every result before step 4.
 
 `security-audit` has a judgement half: add it when the diff *does* something security-relevant in a path no route lists — auth middleware, API key handling, a schema at an HTTP endpoint, a raw database query, an access policy.

package/kit/rules/rules/kit/code-style.md

@@ -1,13 +1,13 @@
 # Code Style
 
-The kit's core. Project-specific conventions (UI framework, shared component library, class utilities) live in the project's own rules beside `.claude/rules/kit/`; where they are stricter, they win.
+The kit's core. Project-specific conventions (UI framework, shared component library, class utilities) live in the project's own rules beside `.claude/rules/kit/`; where they are stricter, they win. Where the project's own rule names a `lint:<rule id>` for a rule below, the linter's message is the authority.
 
 ## Formatting
 
 The formatter and linter config is the authority; where it is silent, match the surrounding code.
 
 - No unused imports.
-- Blank lines separate logical sections; decorative separator comments (`// ─────────`) stay out.
+- Blank lines separate sections; no decorative separator comments.
 
 ## Language
 
@@ -24,7 +24,7 @@ The formatter and linter config is the authority; where it is silent, match the
 ## Comments & Documentation
 
 - Self-documenting code over comments: clear naming, pure functions, obvious control flow.
-- **No section-label comments** (`// Types`, `// Pure functions`, `// Imports`). The code order speaks for itself.
+- **No section-label comments** (`// Types`, `// Imports`): the code order speaks for itself.
 
 ### When to add a doc comment
 
@@ -112,10 +112,10 @@ Before editing a file that might be generated:
 
 Roles, modes, statuses, channels: every closed set of values has **one** constant next to its type (an `as const` object, an enum, a class constant), and every comparison, option id and schema literal reads from it.
 
-A type checker already checks a literal against the closed set inside the core. The constant earns its place at the **seams where a `string` arrives**: a query parameter, a form option id, a row read from the database. There a literal comparison is unchecked, and its usual companion — `mode === 'per_km' ? 'per_km' : 'tiers'` — maps every unknown value to a default in silence.
+The constant earns its place at the **seams where a `string` arrives** (a query parameter, a form option id, a database row): there a literal comparison is unchecked, and `mode === 'per_km' ? 'per_km' : 'tiers'` maps every unknown value to a default in silence.
 
 ```ts
-// ✅ (TypeScript shown) the constant is the vocabulary; a guard narrows the string, an unknown value is refused
+// ✅ the constant is the vocabulary; a guard narrows the string, an unknown value is refused
 export const FEE_MODE = { tiers: 'tiers', perKm: 'per_km' } as const
 export type FeeMode = (typeof FEE_MODE)[keyof typeof FEE_MODE]
 export const isFeeMode = (value: string): value is FeeMode =>
@@ -127,7 +127,7 @@ if (isFeeMode(id)) handleChange(switchMode(form, id))
 mode: id === 'per_km' ? 'per_km' : 'tiers'
 ```
 
-Derive the schema from the constant (a literal built from `FEE_MODE.perKm`), never the other way round, so the constant, the type and the parser cannot disagree. Test fixtures may spell the literal.
+Derive the schema from the constant, never the other way round, so constant, type and parser cannot disagree. Test fixtures may spell the literal.
 
 ## Database Writes
 

package/kit/rules/rules/kit/writing-for-agents.md

@@ -57,6 +57,9 @@ A **context pointer** names material that is out of context and encodes the cond
 - **One trigger per branch.** Synonyms renaming one branch are that branch written twice.
 - **Cut what the body already carries.** A pointer says when to come, not what is inside.
 - **Every trigger names something its loader can honour.** A skill with `disable-model-invocation: true` describes what it is for, since the user picks it; a `paths:` list names globs the repository actually has. Check both against reality — a trigger nothing can fire is a line paid for on every load and never earned back.
+- **A mandatory rule behind a pointer needs a trigger that fires without the reader's judgement.** Code raises it (an event line that names the file, a hook's denial, a command's output) or it is a step every run reaches; "read when needed" is no pointer, since a rule reached only when the reader thinks of it is a weakened rule. Test the link: the rule's sentence stands in the target, the target is linked, and the trigger names it.
+- **A rule a hook enforces is one sentence in the text: how a call gets through.** The full rule lives in the hook's denial, which the reader sees at the moment it matters; written out in both places, it is one meaning in two places that drift apart.
+- **A rule the project's linter can check is a lint rule, and the text keeps one sentence naming it as `lint:<rule id>`**, plus the why where it is not obvious. The full rule lives in the linter's message, for the same reason as above.
 
 ## The two loads
 

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

@@ -6,7 +6,7 @@ argument-hint: 'What to follow, e.g. a ticket key, an issue or a query'
 
 If `.claude/project/follow.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
 
-You add one entry to the watcher's sources, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the entry's file (step 4: the user's `~/.jackherd/sources.json` or the project's `.jackherd/config.json` in the main checkout), and only after the user approved the entry. Read the recipe index `recipes/README.md` of the installed package first (`"$(dirname "$(readlink -f "$(command -v jh)")")/../recipes/README.md"`), then only the recipe file it names for the chosen service; do not copy a recipe from memory. Where the recipe leaves a field open, the index's section **Rules every recipe follows** decides, and `recipes/sources.md` beside it describes every field and limit of a source.
+You add one entry to the watcher's sources, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the entry's file (step 4: the user's `~/.jackherd/sources.json` or the project's `.jackherd/config.json` in the main checkout), and only after the user approved the entry. Read the recipe index `recipes/README.md` of the installed package first (`"$(dirname "$(readlink -f "$(command -v jh)")")/../recipes/README.md"`), then only the recipe file it names for the chosen service; do not copy a recipe from memory. The index's section **Rules every recipe follows** binds every script and direct command, and decides any field the recipe leaves open, and `recipes/sources.md` beside it describes every field and limit of a source.
 
 ## 1. Ask
 
@@ -35,8 +35,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`, `ticket` and `tone` where chosen, and a short `label` (e.g. `Error log · Checkout`; it prefixes the source's `Waiting for you` rows). 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"]` (a personal source runs in `~/.jackherd/`: `["bun", "sources/<name>.ts"]`). Script and direct command follow the index's **Rules every recipe follows**.
-
+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`, `ticket` and `tone` where chosen, and a short `label` (e.g. `Error log · Checkout`; it prefixes the source's `Waiting for you` rows). 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"]` (a personal source runs in `~/.jackherd/`: `["bun", "sources/<name>.ts"]`).
 Write the entry as one JSON object to a draft file in the scratchpad and run, from the main checkout:
 
 ```bash

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

@@ -35,7 +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>)`.
+- **A task you add, or one the user adds later,** takes the form of `/plan` step 2: `- [ ] **Name**: …`.
 - **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