jackherd 1.15.2 → 1.17.0

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

@@ -0,0 +1,73 @@
+import { questionsOf, recordsOf } from './run'
+
+/**
+ * The words the check needs, per response language: the mark a recommended option's label ends with, and the option
+ * labels a guard reads word for word (approvals of a lane call, the self-merge and the standing approval). An empty
+ * mark, from an install that does not pass one, checks nothing.
+ */
+export type RecommendationWords = { mark: string; guardedLabels: readonly string[] }
+
+const QUESTION_LENGTH = 80
+
+const shorten = (text: string): string =>
+  text.length > QUESTION_LENGTH ? `${text.slice(0, QUESTION_LENGTH - 1)}…` : text
+
+const labelsOf = (options: unknown): string[] =>
+  recordsOf(options).flatMap((option) => (typeof option.label === 'string' ? [option.label] : []))
+
+const isMarked = (label: string, mark: string): boolean => label.trimEnd().toLowerCase().endsWith(mark.toLowerCase())
+
+const withoutMark = (label: string, mark: string): string =>
+  isMarked(label, mark) ? label.trimEnd().slice(0, -mark.length).trimEnd() : label
+
+/** A guarded label that carries the mark: the guard would not know the answer, so the dialog goes back. */
+const markedGuardReason = (labels: readonly string[], { mark, guardedLabels }: RecommendationWords): string | null => {
+  const label = labels.find(
+    (candidate) => isMarked(candidate, mark) && guardedLabels.includes(withoutMark(candidate, mark)),
+  )
+  return label === undefined
+    ? null
+    : `Option "${label}": a guard reads "${withoutMark(label, mark)}" word for word; drop "${mark}" from it.`
+}
+
+/** The first option carries the mark; else the reason names a later marked option to move up, or asks for one. */
+const firstMarkReason = (question: string, labels: readonly string[], mark: string): string | null => {
+  const [first, ...rest] = labels
+  if (first !== undefined && isMarked(first, mark)) return null
+  const later = rest.find((label) => isMarked(label, mark))
+  return later === undefined
+    ? `Question "${shorten(question)}": put your recommendation first and end its label with "${mark}".`
+    : `Question "${shorten(question)}": the recommendation goes first; move "${later}" to the top.`
+}
+
+/** A single choice has one recommendation: the first option carries the mark and no other does. */
+const singleChoiceReason = (question: string, labels: readonly string[], mark: string): string | null => {
+  const firstReason = firstMarkReason(question, labels, mark)
+  const second = labels.slice(1).find((label) => isMarked(label, mark))
+  return firstReason ?? (second === undefined
+    ? null
+    : `Question "${shorten(question)}": one recommendation only; drop "${mark}" from "${second}".`)
+}
+
+const questionReason = (question: Record<string, unknown>, words: RecommendationWords): string | null => {
+  const labels = labelsOf(question.options)
+  if (labels.length === 0) return null
+  const guarded = markedGuardReason(labels, words)
+  if (guarded !== null) return guarded
+  if (labels.some((label) => words.guardedLabels.includes(label))) return null
+  const text = typeof question.question === 'string' ? question.question : ''
+  // A multiSelect question may recommend several options, the first among them.
+  const reasonOf = question.multiSelect === true ? firstMarkReason : singleChoiceReason
+  return reasonOf(text, labels, words.mark)
+}
+
+/**
+ * The reason to send a dialog back because a question does not carry its recommendation as the first option, marked
+ * at the end of its label; null when every question does. A question that offers a label a guard reads word for word
+ * needs no mark, and such a label must not carry one.
+ */
+export const recommendationReasonOf = (toolInput: unknown, words: RecommendationWords): string | null => {
+  if (words.mark === '') return null
+  const [reason] = questionsOf(toolInput).flatMap((question) => questionReason(question, words) ?? [])
+  return reason ?? null
+}

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

@@ -1,49 +1,56 @@
 ---
 name: follow
-description: 'Have the watcher report changes of something outside GitHub (a ticket, an issue, an error, a status page): pick a recipe, check the tool and its login read only, dry-run the source, write it to `watch.sources` after approval. Use when the user asks to follow or be told about such an item, e.g. "/follow PROJ-123".'
+description: 'Have the watcher report changes of something outside GitHub (a ticket, an issue, an error, a status page): pick a recipe, check the tool and its login read only, dry-run the source, write it to the watcher''s sources (personal or repository) after approval. Use when the user asks to follow or be told about such an item, e.g. "/follow PROJ-123".'
 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 `watch.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 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
 
 `AskUserQuestion` in {{kit.responseLanguage}}, only for what the argument and the conversation leave open, each with the recommended option first; at most four questions per call, so more open points go into a second call:
 
+- **Where it lives:** a personal source (`~/.jackherd/sources.json`: runs in every repository of the user, the keychain can hold its secrets; recommended when a personal secret is attached, otherwise second) or a repository source (`watch.sources` of the project: runs for everyone who starts the watcher there, and its `secrets` read only the watcher's environment, never the keychain, so it needs a token from the environment or none).
 - **Service:** the services the recipe index lists, and "another command that prints JSON".
 - **What to follow:** the item the argument names (its comments, recommended) or a query over several items.
 - **Lane:** the lane the reports name, from the board's lanes table, or none.
 - **Ticket:** whether the entries are tickets (`ticket: true`, recommended for an issue tracker or a project board), which the herd shows as a badge beside the plan of their lane: the lane above, or the lane whose name, board row or plan names the ticket's id. A source of comments or messages is no ticket; it shows in the herd's `Sources` block instead (a click opens the entry at `map.url`). The path of the status you find yourself in step 3.
-- **Tone:** for a non-ticket source, the colour of its `Sources` mark while its report is new (`tone`: amber, teal, grey, red, green, blue, magenta); recommended: no `tone`.- **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
+- **Tone:** for a non-ticket source, the colour of its `Sources` mark while its report is new (`tone`: amber, teal, grey, red, green, blue, magenta); recommended: no `tone`.
+- **Show:** for a non-ticket source whose entries are the day's content (a calendar), `show: "entries"` opens them in a block of their own under "Your turn"; otherwise none.
+- **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
 - **Own changes:** ignore the user's own account on that service (`ignoreAuthors`, needs an author in the map), or report everything.
 
 ## 2. Check, read only
 
 - The tool: `command -v <tool>` for the recipe's program (`curl`, the service's CLI, and `bun` for a recipe with a script).
-- The login: the tool's own status command where it has one. For a token in an environment variable only whether it is set: `test -n "$<VARIABLE>" && echo set || echo missing`. Never print, echo or pass on a token's value, and never read a file that holds one.
+- The login: the tool's own status command where it has one. For a token in an environment variable only whether it is set: `test -n "$<VARIABLE>" && echo set || echo missing`. Never print, echo or pass on a token's value, never ask for it, and never read a file that holds one.
 
-Anything missing goes to the user as the command to run themselves (`! <command>`); wait until they did, then check again.
+Anything missing goes to the user as the command to run themselves (`! <command>`; a keychain secret: below, not with `!`); wait until they did, then check again.
+
+**A secret** (a token the script needs) is named in the entry's `secrets` (`["NAME"]`) and never passes through you (the rule above). A repository source does not read the keychain: check its environment variable as above. A personal source's secret goes into the keychain in step 4, after the entry is written: `jh secret list` knows only names an entry already lists.
 
 ## 3. Fill and dry-run
 
 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"]`. 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
 jh watch source <draft.json> --dry-run
 ```
 
-It runs the command once and shows the entries and the report the watcher would print, without touching the watcher's state. Exit code 1 means the run failed or a `map` field is empty in every entry (`map.<field>: in … entries empty (<path>)`): never write such an entry, correct the path or drop the field. When the run fails or the entries look wrong, run it again with `--raw` to see the command's output, correct `items` or a path of `map`, and try again; after two failed corrections, show the user the reason and the output's first lines and ask how to go on. Show the user the dry run's list and report, not the raw output.
+It runs the command once and shows the entries and the report the watcher would print, without touching the watcher's state. A draft runs as a repository source: in the main checkout, without the keychain. A personal entry with `secrets` or a script under `sources/` cannot pass there; skip its draft run, show the entry and the recipe's sample output, and dry-run it by name in step 4. Exit code 1 means the run failed or a `map` field is empty in every entry (`map.<field>: in … entries empty (<path>)`): never write such an entry, correct the path or drop the field. When the run fails or the entries look wrong, run it again with `--raw` to see the command's output, correct `items` or a path of `map`, and try again; after two failed corrections, show the user the reason and the output's first lines and ask how to go on. Show the user the dry run's list and report, not the raw output.
 
 ## 4. Write after approval
 
-Ask through `AskUserQuestion`: write the entry (recommended), change it, or drop it. Say in the question that the source runs for everyone who starts the watcher in this repository, and that the watcher cannot keep a command from writing, so the command only reads.
+Ask through `AskUserQuestion`: write the entry (recommended), change it, or drop it. Say in the question which file it goes to and that the watcher cannot keep a command from writing, so the command only reads; for a repository source add that it runs for everyone who starts the watcher in this repository.
+
+On approval write exactly one of these files, and a script from step 3 under the path the entry names:
 
-On approval add the entry to `watch.sources` in `.jackherd/config.json` of the main checkout (create the array if missing), and a script from step 3 under the path the entry names. Then run `jh config`, which fails on an invalid config, and `jh watch source <name> --dry-run` once more against the written entry.
+- **Personal:** add the entry to `sources` in `~/.jackherd/sources.json`; create the file as `{ "$schema": "<installed package>/schemas/sources.schema.json", "sources": [] }` if missing (the package directory is the one the recipe path above resolves to, minus `/recipes/README.md`). The script goes to `~/.jackherd/sources/<name>.ts`. A repository source of the same `name` wins over it, so pick a name the project does not use. For each name in `secrets`, ask the user to run `jh secret set <NAME>` in a terminal of their own (a separate pane; it asks hidden and refuses without a terminal), wait, then check only `jh secret list`: `set` is fine, `missing` means they still have to, `set (environment)` means the watcher's environment must carry it too, `secret store unavailable` means it can come only from that environment. Then run `jh watch source <name> --dry-run`; it prints `origin: personal`. A failure here is corrected in the written entry as in step 3.
+- **Repository:** add the entry to `watch.sources` in `.jackherd/config.json` of the main checkout (create the array if missing). Then run `jh config`, which fails on an invalid config, and `jh watch source <name> --dry-run` once more.
 
-End with one line: the watcher takes the source over at its next start, so a running watcher (the coordinator's stream) has to be started again. The new file and the changed config are part of the repository and follow its commit rules.
+End with one line: a running watcher and the herd take the source over at their next cycle (about a minute); a file that is invalid then keeps the previous sources and prints `sources not reloaded`. A repository entry and its script are part of the repository and follow its commit rules; the personal file is not.

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