create-pathfinder 3.1.0 → 4.1.0

package/AGENTS.md

@@ -2,11 +2,11 @@
 
 Read `CLAUDE.md` first.
 
-Project truth lives in `context/`. Follow the technology and delivery choices documented in `context/project-overview.md`; do not assume a framework, package manager, branch model, or release process. That file, like `context/features/`, `context/history.md`, `context/current-feature.md`, and `context/handoff.md`, is created by the workflow that first needs it — its absence is normal, not an error. Track the durable ones in Git; `context/current-feature.md` and `context/handoff.md` are transient session state and belong in `.gitignore`. Never ignore `context/` as a whole.
+Project truth lives in `context/`. Follow the technology and delivery choices documented in `context/project-overview.md`; do not assume a framework, package manager, branch model, or release process. That file, like `context/features/`, `context/history.md`, `context/current-ticket.md`, and `context/handoff.md`, is created by the workflow that first needs it — its absence is normal, not an error. `context/tickets/` exists only when local Markdown is the project's ticket store; a project whose tickets are in GitHub Issues or another tracker has none, and that is not a gap. Track the durable ones in Git; `context/current-ticket.md` and `context/handoff.md` are transient session state and belong in `.gitignore`. Never ignore `context/` as a whole.
 
-Use the smallest relevant context for the active task. Keep each delivery chunk stable, reviewable, and verifiable.
+Use the smallest relevant context for the active task. Keep each ticket stable, reviewable, and verifiable.
 
-The roles are `planner`, `developer`, and `tester`. When the human names one, read `roles/<name>.md` before anything else and follow it for that session. A role is a declarative contract stating what a worker is responsible for and what it must not do, where a skill states how to perform a task. Naming one is the only thing that activates it, so a session where none is named behaves exactly as if `roles/` were not there.
+The roles are `planner`, `developer`, and `tester`. Lifecycle skills assume the responsible role for each invocation and read its contract themselves. When the human explicitly names a role, read `roles/<name>.md` before anything else and use it instead for that session. A role is a declarative contract stating what a worker is responsible for and what it must not do, where a skill states how to perform a task. Assumed or explicit, a role narrows responsibility and never grants human authority.
 
 Canonical skills live under `skills/` and are the only behavior contract; anything under `.claude/skills/` or `.agents/skills/` is a generated pointer to one, so edit the canonical file and regenerate the adapter.
 

package/CLAUDE.md

@@ -4,34 +4,41 @@ This repository uses an AI-assisted, human-in-the-loop workflow. Project truth l
 
 ## Read only what is needed
 
-For feature work, usually read:
+For delivery work, usually read:
 
-1. `context/current-feature.md`
-2. its referenced feature spec
+1. `context/current-ticket.md`
+2. the ticket it names, and that ticket's parent feature spec
 3. relevant sections of `context/project-overview.md`
 4. relevant rules from `context/coding-standards.md`
 5. `context/ai-interaction.md`
-6. only the source files needed for the current delivery chunk
+6. only the source files needed for the current ticket
 
 Do not load the whole repo by default.
 
 Pathfinder ships two context files: `ai-interaction.md` and
 `coding-standards.md`. Everything else in `context/` — `project-overview.md`,
-`features/`, `history.md`, `current-feature.md`, `handoff.md` — is written by
-the workflow that first needs it. A missing file here is normal; skip it rather
-than treating it as an error.
+`features/`, `tickets/`, `history.md`, `current-ticket.md`, `handoff.md` — is
+written by the workflow that first needs it. A missing file here is normal; skip
+it rather than treating it as an error. `tickets/` in particular exists only
+when local Markdown is the project's ticket store.
 
 Track the durable ones in Git and ignore the two transient ones,
-`current-feature.md` and `handoff.md`. `context/coding-standards.md` carries the
+`current-ticket.md` and `handoff.md`. `context/coding-standards.md` carries the
 rule; do not ignore `context/` wholesale.
 
 ## Roles
 
-When the human names a role, read `roles/<name>.md` before anything else and follow it for the session. A role says what a worker is responsible for, what it reads, and what it must not do, where a skill says how to perform a task.
+Lifecycle skills assume their responsible role for each invocation and read its
+contract themselves: planning uses `planner`, ticket implementation and
+completion use `developer`, and ticket review uses `tester`.
 
-The roles are `planner`, `developer`, and `tester`. Activate one with `/role <name>`.
+The human can explicitly override that default with `/role <name>`. Read the
+named `roles/<name>.md` before anything else and follow it for the session. A
+role says what a worker is responsible for, what it reads, and what it must not
+do, where a skill says how to perform a task.
 
-Naming a role is the only thing that activates one. If the human names none, ignore `roles/` and work as this guide otherwise describes. A role narrows what a session may do and never widens it. Human authority sits outside the role system: approval, acceptance, merge, and release are always the human's.
+A role narrows responsibility and never widens authority. Approval, acceptance,
+merge, and release remain the human's whether a role was assumed or explicit.
 
 ## Project-selected policies
 
@@ -44,7 +51,7 @@ If a policy is `TBD`, do not invent it. Ask the human or clearly mark it unresol
 Restate:
 
 1. Goal
-2. Active delivery chunk
+2. Active ticket
 3. Expected files or areas
 4. Required context
 5. Risks
@@ -60,8 +67,8 @@ Ask before actions identified in `context/ai-interaction.md`, especially depende
 
 ## Scope and quality
 
-- Implement only the active feature and current delivery chunk.
-- Keep the project stable after each chunk.
+- Implement only the active feature and current ticket.
+- Keep the project stable after each ticket.
 - Do not convert prototype code into production code without an explicit feature decision.
 - Prefer concrete verification over confident narration.
 - Report conflicts between specs, repository reality, and durable context.
@@ -81,7 +88,8 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `reverse-engineer` — analyze an external reference and produce an evidence-based reconstruction blueprint
 - `prototype` — create and iterate the cheapest useful validation artifact
 - `to-specs` — generate context-sized feature specs
-- `feature` — run one action of the Feature delivery loop: `load`, `start`, `review`, `complete`
+- `to-tickets` — decompose one approved Feature into blocker-linked tickets
+- `ticket` — run one action of the ticket delivery loop: `load`, `start`, `review`, `complete`
 - `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it
 - `learn-feature` — create an interactive lesson for a completed feature
 - `learn-codebase` — create a modular learning portal for the repository
@@ -92,8 +100,8 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `learning-review` — review accumulated lessons, identify gaps, and create a reinforcement plan
 - `reflect` — review completed work, and the reflection itself, and propose reusable workflow improvements for human approval
 - `handoff` — preserve useful state between sessions or tools
-- `role` — activate one named role for the current session
+- `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
-- `setup-tracker` — configure an optional external work tracker
-- `sync-tracker` — publish approved feature specs to the configured tracker, one-way and idempotently
+- `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/README.md

@@ -80,11 +80,11 @@ The installer copies six kit entries into your repository:
 | --- | --- |
 | `AGENTS.md`, `CLAUDE.md` | Entry files that tell supported agents how to work in the project |
 | `context/` | Project standards and interaction rules; other context is created only when needed |
-| `roles/` | Three optional responsibility contracts: planner, developer, tester |
-| `skills/` | Reusable procedures for discovery, specs, delivery, debugging, review, learning, and optional work tracking |
+| `roles/` | Planner, developer, and tester contracts assumed by lifecycle skills |
+| `skills/` | Reusable procedures for discovery, specs, delivery, debugging, review, learning, and ticket-store selection |
 | `templates/` | Minimal starting shapes; records are created from them later, when a workflow needs one |
 
-A fresh Pathfinder 2.0 project begins with only:
+A fresh Pathfinder project begins with only:
 
 ```text
 context/

package/context/ai-interaction.md

@@ -20,7 +20,7 @@ Ask before:
 - Git history rewriting
 - commits, merges, releases, or deployments
 - adopting prototype code into production
-- writes outside the repository, such as shared tracker changes
+- writes outside the repository, such as tickets in a shared store
 
 The human owns judgment, acceptance, merge, and release decisions.
 
@@ -34,21 +34,24 @@ or deployment workflow.
 Inspect current Git state before acting. If the workflow is unclear or
 `TBD`, ask.
 
-## Feature Workflow
+## Delivery Workflow
 
 Use the workflow skills instead of recreating their procedures in chat:
 
-1. `/feature load` — load the active work and relevant context.
-2. `/feature start` — implement the current delivery chunk.
-3. `/feature review` — verify the work and report findings.
-4. `/feature complete` — complete accepted work and durable records.
-5. `learn-feature` — optionally teach what was implemented.
+1. `to-tickets` — slice one approved Feature into executable tickets.
+2. `/ticket load` — load one ticket, its Feature, and relevant context.
+3. `/ticket start` — implement that ticket.
+4. `/ticket review` — verify the work and report findings.
+5. `/ticket complete` — complete accepted work and durable records, and name
+   the tickets that are now ready.
+6. `learn-feature` — optionally teach what was implemented.
 
-Roles are optional. The workflow must work without activating one.
+Lifecycle skills assume their responsible role automatically. Explicit
+activation with `/role` is optional and overrides that default for the session.
 
 ### Status
 
-Feature status records durable lifecycle state only:
+Ticket status records durable lifecycle state only:
 
 `Proposed` → `Ready` → `In Progress` → `Complete`
 
@@ -56,17 +59,20 @@ Feature status records durable lifecycle state only:
 
 - `Ready` means the human approved execution.
 - Review and testing are optional workflow activity, not a status.
-  A Feature stays `In Progress` until it is complete.
-- `Blocked` is not a status; record the blocker in current workspace state.
+  A ticket stays `In Progress` until it is complete.
+- `Blocked` is not a status. A ticket's blockers are the edges under its
+  `## Blocked by`, and anything else that stops work is recorded in current
+  workspace state.
+- A Feature's status is derived from its tickets, never maintained by hand.
 - The human decides approval, acceptance, cancellation, and supersession.
 
 ## Context Discipline
 
 - Read only what the current work requires.
 - Prefer exact files or sections over broad repository scans.
-- Do not load history, roadmap, tracker data, or unrelated context by
+- Do not load history, roadmap, other tickets, or unrelated context by
   default.
-- Work one delivery chunk at a time.
+- Work one ticket at a time.
 - If the work can no longer be understood safely in a focused session,
   stop and split or hand off.
 - Extra scaffolding must earn its cost by reducing downstream context.

package/context/coding-standards.md

@@ -92,10 +92,12 @@ Keep durable truth in its appropriate project artifact.
   `context/project-overview.md`
 - Feature contracts:
   `context/features/`
+- executable tickets, when local Markdown is the configured store:
+  `context/tickets/`
 - completed outcomes:
   `context/history.md`
 - active workspace state:
-  `context/current-feature.md`
+  `context/current-ticket.md`
 - state handed to the next session:
   `context/handoff.md`
 
@@ -115,6 +117,7 @@ project", it outlives any session, and a reviewer should see it change:
 ```text
 context/project-overview.md
 context/features/
+context/tickets/ # only when local Markdown is the ticket store
 context/history.md
 context/tracker.md
 ```
@@ -124,14 +127,14 @@ it belongs to one session on one machine, and committing it puts one person's
 in-flight work in everybody's diff:
 
 ```text
-context/current-feature.md
+context/current-ticket.md
 context/handoff.md
 ```
 
 Two lines in `.gitignore` are the whole mechanism:
 
 ```text
-context/current-feature.md
+context/current-ticket.md
 context/handoff.md
 ```
 
@@ -144,7 +147,8 @@ A team that would rather share workspace state — a single-machine project, or
 handoff meant to be read by a colleague — can track them instead. Nothing in the
 kit reads Git state to decide how to behave.
 
-`context/tracker.md` is durable and tracked, with one exception that does not
-apply to your project: Pathfinder's own repository ignores it, because `context`
-is a directory in the installer's copy list and a committed copy would ship
-Pathfinder's tracker config to every new install.
+`context/tracker.md` is durable and tracked when the project selects a store
+other than local Markdown. With local Markdown, `context/tickets/` is durable
+and tracked instead. Pathfinder's own repository ignores its tracker config,
+because `context` is a directory in the installer's copy list and a committed
+copy would ship Pathfinder's store selection to every new install.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-pathfinder",
-  "version": "3.1.0",
-  "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
+  "version": "4.1.0",
+  "description": "Install Pathfinder's ticket-first, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",
     "ai",

package/roles/developer.md

@@ -17,7 +17,8 @@ Do not load unrelated history, roadmap, Features, or repository areas by default
 
 ## Use
 
-- `feature` — its load action to load the work, its start action to implement it.
+- `ticket` — its load action to load work, start action to implement it, and
+  complete action to record work the human accepted.
 - Use the project's existing build, test, and verification commands as needed.
 
 ## Rules

package/roles/planner.md

@@ -1,14 +1,14 @@
 ---
 name: planner
-description: Turns approved direction into small, implementable Feature specs.
+description: Discovers project direction and turns it into implementable Features and tickets.
 ---
 
 # Planner
 
 ## Responsibility
 
-Turn approved direction into clear Feature specs for another session to
-implement.
+Discover project direction, turn approved direction into clear Feature specs,
+and slice those Features into tickets another session can implement.
 
 ## Context
 
@@ -18,8 +18,10 @@ Inspect implementation code only when necessary to understand the work.
 
 ## Use
 
+- `kickstart-pathfinder` to discover and initialize project context.
 - `debate-me` when direction still needs pressure-testing.
 - `to-specs` to create Feature specs.
+- `to-tickets` to slice one approved Feature into executable tickets.
 
 ## Rules
 
@@ -33,6 +35,6 @@ Inspect implementation code only when necessary to understand the work.
 
 ## Finish
 
-Produce the Feature specs and clearly identify any unresolved human decisions.
-
-Stop before implementation.
+Finish at the invoked skill's stop condition: approved project context, Feature
+specs, or a ticket graph. Identify unresolved human decisions and stop before
+implementation.

package/roles/tester.md

@@ -20,7 +20,7 @@ Do not rely on the developer's summary as proof.
 
 ## Use
 
-- `feature` — its review action, to verify implemented work.
+- `ticket` — its review action, to verify implemented work.
 - Use the project's existing test commands and relevant testing tools.
 
 ## Rules

package/skills/debug-issue/SKILL.md

@@ -29,9 +29,9 @@ Use Debug Issue when there is a concrete unexpected behavior such as:
 
 Do not use it merely because implementation work is difficult.
 
-If the task is planned feature construction, use `/feature start`.
+If the task is planned construction, use `/ticket start`.
 
-If the goal is reviewing completed implementation for possible defects, use `/feature review`.
+If the goal is reviewing completed implementation for possible defects, use `/ticket review`.
 
 If the real question is broad understanding of the repository, use `learn-codebase`.
 
@@ -202,8 +202,8 @@ It does not:
 
 * implement unrelated feature scope
 * perform a general repository review
-* replace `/feature review`
-* replace `/feature complete`
+* replace `/ticket review`
+* replace `/ticket complete`
 * silently change architecture or dependencies
 * turn debugging into opportunistic refactoring
 * hide uncertainty behind a successful-looking workaround

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/skills/kickstart-pathfinder/SKILL.md

@@ -7,6 +7,12 @@ description: Discover and initialize a new or existing project without writing p
 
 Use this skill to turn an idea or existing repository into durable, human-approved project context.
 
+## Assumed role
+
+Unless the human explicitly activated a role, assume `planner` for this
+invocation: read `roles/planner.md` and follow it. An explicit role overrides
+this default. A role narrows responsibility and never grants human authority.
+
 ## Rules
 
 - Do not install packages or write product code.

package/skills/quiz-me/SKILL.md

@@ -13,7 +13,7 @@ The goal is retrieval and diagnosis, not entertainment and not a long exam.
 ## Read First
 
 1. The relevant lesson in `context/learning/lessons/`
-2. `context/current-feature.md`
+2. `context/current-ticket.md`
 3. Only the implementation or tests needed to verify answers
 4. `context/learning/progress.md`
 

package/skills/reverse-engineer/SKILL.md

@@ -173,7 +173,7 @@ Use one of these:
 * `debate-me` — when major product or technical decisions remain
 * `prototype` — when the experience or technical assumption needs validation
 * `to-specs` — when the direction is approved and ready to become feature files
-* `/feature load` — when the analysis applies to one already-planned feature
+* `/ticket load` — when the analysis applies to one already-planned ticket
 * `learn-codebase` — when the user wants to understand their own repository instead
 * no handoff — when the user only requested analysis