create-pathfinder 4.0.0 → 4.2.0

package/CLAUDE.md

@@ -103,4 +103,5 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `role` — explicitly override the role the lifecycle would assume
 - `whereami` — report a compact read-only snapshot of the current session
 - `skillsmith` — teach and create small local skills
+- `hooksmith` — turn a described guarantee into one verified hook for the active harness
 - `setup-tracker` — choose the canonical ticket store when it is not local Markdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Install Pathfinder's ticket-first, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",

package/skills/hooksmith/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: hooksmith
+description: Turn a plain-English automation or deterministic guarantee into the smallest working, correctly scoped, verified hook for the active AI coding harness.
+argument-hint: [what the hook must guarantee or do]
+---
+
+# Hooksmith
+
+A skill is reusable reasoning. A hook is deterministic lifecycle automation.
+
+> A skill asks. A hook guarantees.
+
+Start from the behavior the human describes. Do not start from a harness, an
+event name, a settings file, or a script.
+
+A hook is trusted executable configuration: it runs automatically, with the
+human's credentials, every time its trigger matches, and nothing asks first.
+Build one the way you would accept a change to CI.
+
+## 1. Decide whether this should be a hook
+
+Answer before anything else, out loud:
+
+- deterministic lifecycle behavior — a guarantee, or an automatic reaction to
+  something the session did → hook candidate
+- judgment or reasoning workflow → a skill; use `skillsmith`
+- something a human runs when they want it → a script, a command, or a Make
+  target
+
+Example: "never allow edits to approved Feature specs." Whether the rule holds
+cannot depend on an agent remembering it, and the answer is a path comparison.
+That is a hook.
+
+Anti-example: "review whether this implementation actually satisfies the
+Feature." That is a reading of intent against evidence. No trigger expresses it,
+and a hook that approximates it will block correct work and pass incorrect work.
+It belongs in a reviewer skill.
+
+Say which of the three the request is. Concluding "this is not a hook" is a
+successful outcome of this skill — stop there and name what to use instead.
+
+## 2. Describe the hook without naming a harness
+
+Write the behavior down in these terms, and only these, before looking at any
+harness:
+
+- **lifecycle moment** — what point in the session's life this attaches to
+- **trigger** — what narrows it to the cases the human means
+- **action** — what actually happens when it fires
+- **blocking or non-blocking** — must it *stop* something, or only react to it
+- **ownership and scope** — whose sessions this fires in
+- **failure behavior** — what happens when the hook itself errors
+- **verification** — what would prove it works, and what would prove it does not
+
+The worked example becomes:
+
+> pre-action, blocking file-mutation guard on the approved Feature spec paths,
+> owned by the project or the kit, failing closed only if the check is trivially
+> correct, verified by one edit that must pass and one that must be refused.
+
+That paragraph is the portable contract: what the hook must guarantee, stated in
+terms no harness owns. What follows it is four different things, and keeping
+them apart is the point of the rest of this skill — translation onto one
+harness's primitives (step 4), implementation of the action (step 5–6),
+configuration that installs it (step 7), and verification that it actually
+behaves that way (step 8). Only the first is translation.
+
+Keep this description in the report. It is what survives a change of harness.
+
+## 3. Identify the active harness and read what it can actually do
+
+Name the harness this session is running in. Then inspect its current hook or
+lifecycle capabilities and conventions — its documentation, its configuration
+files, what it already has configured — rather than assuming they match another
+harness or match what you remember.
+
+Confirm four things before translating anything:
+
+- which lifecycle moments it exposes, and their real names
+- how a trigger is expressed, and how precisely it can narrow
+- whether the moment you need can **block**, or only observe
+- where the configuration lives, and what scopes it offers
+
+If the harness exposes no equivalent lifecycle primitive, or exposes one that
+cannot block when the guarantee requires blocking, say so plainly and stop. A
+guarantee the harness cannot enforce is not a hook — it is a rule, a skill, or a
+check the human runs. Do not build something that looks like enforcement and is
+not.
+
+### Claude Code
+
+The first harness this skill supports concretely, and a reference for what a
+translation looks like — not the definition of a hook.
+
+Under Claude Code, read the current documentation before relying on any detail:
+
+- https://code.claude.com/docs/en/hooks.md — reference
+- https://code.claude.com/docs/en/hooks-guide.md — examples
+
+That contract changes faster than any skill describing it, which is why nothing
+here restates its event list. Once confirmed against the fetched page, use its
+own vocabulary directly — the lifecycle event names, the matcher and condition
+syntax, the handler types, the settings and plugin locations, the way a handler
+receives input and returns a decision. Naming them is correct here and wrong
+anywhere else.
+
+Under any other harness, use that harness's native equivalent on the same terms:
+read its documentation first, then speak its vocabulary.
+
+#### The worked example, realized here
+
+The step 2 description — *pre-action, blocking file-mutation guard on the
+approved Feature spec paths, owned by the project or the kit* — becomes, under
+this harness and no other:
+
+| Portable term | Claude Code realization |
+| --- | --- |
+| lifecycle moment, pre-action | a `PreToolUse` event, which fires before the tool call and can block it |
+| trigger | a matcher on the file-writing tools, narrowed further by an `if` condition on the spec paths |
+| blocking | a denying permission decision, or exit code 2, returned by the handler |
+| ownership, project or kit | `.claude/settings.json` in the repository, or the plugin's `hooks/hooks.json` |
+
+Every cell on the right is this harness's dialect. Another harness answers the
+same four questions with different names, or cannot answer one of them at all —
+which is what step 3 is for. Treat the table as an illustration of the shape of
+a translation, and confirm each cell against the documentation you just fetched
+before relying on it; the names and the decision format change.
+
+## 4. Translate, narrowest first
+
+Map the description from step 2 onto what step 3 found:
+
+- the lifecycle moment → the harness's nearest real moment, blocking-capable if
+  the guarantee needs it
+- the trigger → the narrowest expression the harness supports; a trigger that
+  fires on everything is a noise problem that hides the cases the hook exists for
+- ownership → the smallest scope that delivers the guarantee. Scope is a blast
+  radius: a guarantee one person wants does not belong in everyone's
+  configuration, and a project guarantee does not belong in something that ships
+  to other people's projects.
+
+State every place the translation is imperfect. The guarantee is only as strong
+as the trigger, so say plainly what it does not catch.
+
+For a hook that ships with Pathfinder, prefer what the installation environment
+already guarantees. A hook needing a runtime, a package manager, or a dependency
+the kit does not already assume is a hook Pathfinder cannot ship.
+
+### Two approval gates
+
+They are independent, and either one can apply:
+
+- **Location.** Writing outside the repository — user settings, machine
+  configuration — needs approval.
+- **Blast radius.** Installing or changing a hook whose behavior reaches beyond
+  the human's own private, local configuration needs approval, wherever the file
+  sits. That covers a project hook committed to the repository and a hook
+  shipped by Pathfinder or a plugin: both make other people's sessions behave
+  differently, and neither is yours to decide.
+
+Building and testing a candidate hook in a scratch or local-only place is not
+gated. Ask at the moment of installing or modifying shared automatic behavior,
+not before experimenting.
+
+## 5. Choose the smallest reliable action
+
+Prefer, in order: what the harness's own handler types give you for free; a
+short shell command; a small script in a runtime the environment already has.
+Choose a language because it is present and appropriate, not out of habit.
+
+The action runs in the harness's environment, not the human's shell. Do not
+assume a project's virtual environment, `PATH`, or dependencies are active. If
+the hook must run a project command, run it as the human would type it, in the
+project directory, and confirm it resolves there — a hook that always fails
+looks exactly like a hook that always works.
+
+## 6. Decide failure and recursion behavior
+
+State the choice explicitly:
+
+- **fail open** — an unexpected error allows the action. The default. A broken
+  hook must not brick a session.
+- **fail closed** — an unexpected error blocks. Only for a real safety boundary,
+  and only when the check is simple enough to be obviously correct.
+
+A hook attached to the end of a turn must not block the very ending it caused.
+Find the harness's re-entry signal and exit early when it is set. A hook that
+loops is worse than no hook.
+
+Keep the action fast. It runs on every match.
+
+## 7. Merge, never overwrite
+
+Read the existing configuration before writing. Add this hook to what is already
+there; leave every other moment and every other hook intact. Losing someone's
+unrelated hook is a silent, hard-to-notice failure.
+
+## 8. Prove it, both ways
+
+Run the hook, the way this harness runs hooks. Verification is where the
+abstraction ends: use the harness's real invocation, real input shape, and real
+signals.
+
+Verify both sides of the boundary:
+
+- a case that must be **allowed** — it passes
+- a case that must **trigger, block, or react** — it fires, with a reason a
+  reader would understand
+
+A hook that responds identically to both is broken, whichever way it responds.
+Fix it and re-run before reporting anything.
+
+Never report success from reading the code. A hook that always blocks and a hook
+that always allows are indistinguishable on the page.
+
+## 9. Report
+
+State:
+
+- the harness-independent description from step 2
+- the harness, and what its capabilities were confirmed to be
+- what was created, and where it lives
+- what triggers it, what it guarantees, and what it does not catch
+- what was actually executed, and what each run proved
+- the one line the human would edit to adjust it
+- how the human can trigger it themselves
+- that the hook runs automatically with their credentials, and should be
+  reviewed like any other executable configuration
+
+Say plainly what could not be verified, and name anything the harness could not
+enforce.
+
+## Rules
+
+- One hook per invocation. Finish it, verify it, report it, stop.
+- Do not treat one harness's event names, configuration files, handler types, or
+  input and output contracts as universal. They are that harness's dialect.
+- Do not build a cross-harness abstraction layer, runtime, adapter framework,
+  registry, or orchestration system. The abstraction is the reasoning in steps
+  1–2; everything written to disk is native to one harness.
+- Do not write outside the repository — user settings, machine configuration —
+  without approval.
+- Do not install or change a hook that affects anyone but the human running this
+  session — a project hook in the repository, a hook shipped by Pathfinder or a
+  plugin — without approval. Experimenting locally is free; making shared
+  automatic behavior is not.
+- Do not add a dependency to make a hook possible. Choose a smaller hook.
+- Do not weaken an existing hook to make a new one fit.
+- Do not report a hook as working without having run it.
+
+## Stop conditions
+
+Stop and hand the decision back when:
+
+- the behavior turns out to need judgment, and belongs in a skill
+- the active harness has no equivalent primitive, or none that can block when
+  blocking is the point
+- its documentation contradicts what the hook would rely on
+- the guarantee cannot be expressed by any available trigger
+- the correct scope is one the human has not approved, or is shared and the
+  human has not approved installing it
+- verification cannot distinguish the allowed case from the blocked one
+
+Keep version one small and easy to delete. A hook nobody can explain is a hook
+nobody can trust.

package/src/activation.mjs

@@ -0,0 +1,199 @@
+/**
+ * What a human does to turn a generated handler on, and how they turn it off.
+ *
+ * Pathfinder generates the handler and stops. Activation is native harness
+ * configuration in a file Pathfinder does not own, does not read, and never
+ * writes — so the only thing this package can offer is the exact text to paste
+ * and an honest account of what happens if nobody pastes it.
+ *
+ * That is why this module is prose and nothing else. It imports no `node:fs`,
+ * holds no path to a settings file it might one day open, and returns strings.
+ * `test/hooks.test.mjs` asserts both halves of that: this is the one module
+ * under `src/` allowed to name a settings file, and it is allowed to precisely
+ * because it cannot act on one.
+ *
+ * The fragment is built from the registry's stable handler path rather than
+ * written out, so a fragment that no longer matches what the installer
+ * generates is not a thing this package can print.
+ *
+ * The handler ships mode 0644 and is not executable, whatever its shebang
+ * says, so the command runs it through Node. `$CLAUDE_PROJECT_DIR` is what
+ * keeps the activation correct from a subdirectory and inside a worktree.
+ */
+
+import { HARNESSES } from "./harnesses/index.mjs";
+import { hookPath, hooksFor } from "./harnesses/hook.mjs";
+
+/** Where a human puts the fragment. The first is the documented default. */
+export const DEFAULT_SURFACE = ".claude/settings.local.json";
+export const SHARED_SURFACE = ".claude/settings.json";
+
+/**
+ * Does this harness declare that it can run a handler at all?
+ *
+ * Read from the registry — `hooksDir` is the field that says "this tool has a
+ * place handlers go" — rather than from the length of `hooks`, which is the
+ * thing being checked. Codex answers no, and that is a correct answer, not a
+ * gap: it gets no handler and no activation prose.
+ */
+export function supportsActivation(harness) {
+  return typeof harness?.hooksDir === "string" && harness.hooksDir !== "";
+}
+
+/**
+ * The one handler a capable harness activates, or null for a harness that has
+ * no place to put one.
+ *
+ * v1 ships exactly one orientation handler per capable harness, and this is
+ * where that assumption is stated instead of assumed. `hooksFor(harness)[0]`
+ * reads identically whether the registry holds one handler, none, or three —
+ * which is precisely the property that makes it unsafe: a registry that lost
+ * its hook would print no fragment and a registry that grew a second one would
+ * silently document the first. Both are wrong, and both are silent.
+ *
+ * So a capable harness that does not resolve to exactly one handler throws.
+ * Callers that legitimately have nothing to say — a Codex run — are served by
+ * the null, not by the throw.
+ *
+ * @throws {Error} when the registry and this assumption disagree.
+ */
+export function activationHandler(harness) {
+  const hooks = hooksFor(harness);
+
+  if (!supportsActivation(harness)) {
+    if (hooks.length > 0) {
+      throw new Error(
+        `activation: ${harness?.id ?? "harness"} declares ${hooks.length} handler(s) ` +
+          "but no hooksDir to put them in",
+      );
+    }
+    return null;
+  }
+
+  if (hooks.length !== 1) {
+    throw new Error(
+      `activation: ${harness.id} supports session orientation, so exactly one handler ` +
+        `must resolve; the registry gives ${hooks.length}`,
+    );
+  }
+
+  return hooks[0];
+}
+
+/**
+ * Every harness this build can print activation for, with its handler.
+ *
+ * Exported for `validate-kit.py`, which needs the set rather than one harness:
+ * checking the guide against `claude-code` alone would pass unchanged on the
+ * day a second capable harness is added and left undocumented.
+ *
+ * Throws for the same reasons `activationHandler` does, which is the point —
+ * a validator that enumerates this cannot pass vacuously.
+ */
+export function activationTargets() {
+  return HARNESSES.map((harness) => ({ harness, hook: activationHandler(harness) })).filter(
+    ({ hook }) => hook !== null,
+  );
+}
+
+/**
+ * The command that runs one handler, quoted for a shell.
+ *
+ * Exported for the documentation build and the tests, which check the site and
+ * the installer against one spelling rather than two.
+ */
+export function activationCommand(harness, hook) {
+  return `node "$CLAUDE_PROJECT_DIR/${hookPath(harness, hook)}"`;
+}
+
+/**
+ * The native fragment, as the lines a person pastes.
+ *
+ * The matcher is deliberately omitted, so one entry covers the lifecycle
+ * sources without naming any of them.
+ *
+ * `startup`, `resume`, `clear`, and `compact` were each observed live per
+ * source against a real install, not inferred from `startup`. `fork` was not:
+ * the reachable surface, `claude --resume --fork-session`, emits
+ * `source: "resume"`, so it was covered by driving the handler with a `fork`
+ * payload instead. The handler branches on the source for nothing, which is
+ * what bounds what that weaker evidence can cost.
+ */
+export function activationFragmentLines(harness, hook) {
+  return [
+    "{",
+    '  "hooks": {',
+    '    "SessionStart": [',
+    "      {",
+    '        "hooks": [',
+    "          {",
+    '            "type": "command",',
+    `            "command": ${JSON.stringify(activationCommand(harness, hook))}`,
+    "          }",
+    "        ]",
+    "      }",
+    "    ]",
+    "  }",
+    "}",
+  ];
+}
+
+/**
+ * The whole activation note for one harness, as undecorated lines.
+ *
+ * Returned as text rather than printed, so the two renderings in `cli.mjs`
+ * decorate one set of sentences instead of each keeping their own copy — the
+ * same reason `outcome.mjs` exists. Empty for a harness with no handler, which
+ * is how a Codex run says nothing at all about activation.
+ *
+ * `dryRun` changes tense and nothing else. A dry run has written no handler, so
+ * a note that says "the handler is inert" is describing a file that is not
+ * there — the one sentence on that screen a reader could act on and be wrong
+ * about. The fragment itself is identical in both modes, because the path it
+ * points at is the path the real run will write.
+ *
+ * The unactivated answer is stated in the same breath as the fragment, because
+ * a reader who decides not to paste it is owed the consequence on the same
+ * screen: no automatic orientation, and `/whereami` on demand.
+ */
+export function activationLines(harness, { dryRun = false } = {}) {
+  const hook = activationHandler(harness);
+  if (!hook) return [];
+
+  const opening = dryRun
+    ? [
+        "The handler would be inert. Once installed it would run only if you add",
+        `this to ${DEFAULT_SURFACE}:`,
+      ]
+    : [
+        "The handler is inert. It runs only if you add this to",
+        `${DEFAULT_SURFACE}:`,
+      ];
+
+  const closing = dryRun
+    ? [
+        "Without the fragment there would be no automatic orientation. Nothing else",
+        "would change: run /whereami whenever you want the same picture.",
+        "To remove it later, delete the handler and drop the fragment. Either order",
+        "is fine, and so is doing only one: an unreferenced handler never runs.",
+        "A fragment for a missing handler is a no-op that cannot block a session.",
+      ]
+    : [
+        "Without the fragment there is no automatic orientation. Nothing else",
+        "changes: run /whereami whenever you want the same picture.",
+        "To remove it later, delete the handler and drop the fragment. Either order",
+        "is fine, and so is doing only one: an unreferenced handler never runs.",
+        "A fragment for a missing handler is a no-op that cannot block a session.",
+      ];
+
+  return [
+    ...opening,
+    "",
+    ...activationFragmentLines(harness, hook),
+    "",
+    `${DEFAULT_SURFACE} keeps the choice yours and`,
+    `per-machine. Use ${SHARED_SURFACE} only to turn it on for everyone`,
+    "who clones the repository.",
+    ...closing,
+  ];
+}