create-pathfinder 3.1.0 → 4.1.0

package/skills/whereami/SKILL.md

@@ -12,16 +12,18 @@ action. It reports state. It never changes it.
 
 ## Process
 
-1. Role: report the role activated in this session via `/role`.
-   Roles are session state and are never written to disk, so if no role was
-   activated in this conversation, report `none`. Do not search `roles/`.
-2. Read `context/current-feature.md` if it exists.
-   Take Feature, Active chunk, and Next from it verbatim. The Feature number is
-   the `NN` recorded there, from its spec filename.
+1. Role: report an explicit `/role` override when one is active; otherwise
+   report `none`. Lifecycle role assumptions apply only to their own invocation,
+   so a previous `ticket` or planning action does not persist a role for
+   `whereami`. Roles are never written to disk. Do not infer one from the
+   current ticket or search `roles/`.
+2. Read `context/current-ticket.md` if it exists.
+   Take Ticket, Feature, and Next from it verbatim. The ticket key and the
+   Feature number are the ones recorded there, from their filenames.
    If the file is missing or still holds template placeholders, report `none`.
 3. Run `git status --short --branch` once.
    Report the branch/ref, and `clean` or the count of changed paths.
-4. Compare the Git section of `context/current-feature.md` with step 3.
+4. Compare the Git section of `context/current-ticket.md` with step 3.
    Report a drift line only if the recorded branch differs from the real one.
 5. Context telemetry: report it only if this harness exposes it.
    Otherwise `unavailable`. Do not estimate.
@@ -33,7 +35,7 @@ Exactly this shape, one line each:
 ```
 Role:    <role | none>
 Feature: <## — name | none>
-Chunk:   <number and name | none>
+Ticket:  <key and name | none>
 Git:     <branch/ref> — <clean | N changed>
 Context: <telemetry | unavailable>
 Next:    <single next action | none>
@@ -42,7 +44,7 @@ Next:    <single next action | none>
 Add at most one line after it, and only when step 4 found drift:
 
 ```
-Drift:   current-feature.md records <branch>, working tree is on <branch>
+Drift:   current-ticket.md records <branch>, working tree is on <branch>
 ```
 
 Then stop.
@@ -50,8 +52,8 @@ Then stop.
 ## Rules
 
 - Read only. No writes, no commits, no `git` command that mutates anything.
-- Read at most one file: `context/current-feature.md`.
-- Do not open the feature spec, history, roadmap, `.features/`, or source.
+- Read at most one file: `context/current-ticket.md`.
+- Do not open the ticket, the feature spec, history, roadmap, or source.
 - Report `none` or `unavailable` instead of inferring a missing value.
 - Do not offer to fix drift, update state, or start the next action.
   The human decides what happens after the snapshot.
@@ -63,7 +65,7 @@ Then stop.
 ```
 Role:    developer
 Feature: 12 — export saved searches
-Chunk:   2 — CSV writer
+Ticket:  12.2 — CSV writer
 Git:     feature/12-export-saved-searches — 3 changed
 Context: unavailable
 Next:    Verify the CSV writer against the acceptance criteria
@@ -76,12 +78,12 @@ Do not do this:
 ```
 Role:    developer (inferred from recent commits)
 Feature: 12 — export saved searches
-Chunk:   3 — probably the download endpoint
+Ticket:  12.3 — probably the download endpoint
 Git:     feature/12-export-saved-searches — 3 changed
 Context: ~60% used
-Next:    I can update current-feature.md and start chunk 3 — want me to?
+Next:    I can update current-ticket.md and start ticket 12.3 — want me to?
 ```
 
-It guesses the role from history, invents a chunk the spec never named,
+It guesses the role from history, invents a ticket that was never written,
 estimates telemetry it cannot see, and turns a status report into a proposal
 to write state.

package/src/kit.mjs

@@ -57,24 +57,38 @@ export function isExcluded(basename) {
  * real, hand-written files that live inside a copy-list directory and must
  * still never reach a destination project.
  *
- * All three are this repository's own working state, and every one of them
- * would be actively wrong in somebody else's project.
+ * Every one of them would be actively wrong in somebody else's project,
+ * though not all for the same reason — see `context/history.md` below.
  *
- * `context/tracker.md` is the original case. Work Tracking's off switch is the
- * *absence* of that file in a destination project, so shipping this
- * repository's own copy would hand every new project a configuration naming a
- * tracker it does not own, pointing at a spec directory it does not have, with
- * the off switch already defeated on first install.
+ * `context/tracker.md` is the original case. Its absence selects the default
+ * local-Markdown ticket store, so shipping this repository's own copy would
+ * hand every new project a configuration naming a store it does not own.
  *
- * `context/current-feature.md` and `context/handoff.md` are transient session
+ * `context/current-ticket.md` and `context/handoff.md` are transient session
  * state, and they are here for the same reason one step further on: the kit
- * stopped shipping a blank `current-feature.md` stencil, because `/feature load`
+ * stopped shipping a blank `current-ticket.md` stencil, because `/ticket load`
  * writes the real one on first use and a placeholder is just a file a reader
  * has to recognise as empty. Having stopped shipping the blank one, the thing
  * to guard against is shipping a *filled-in* one — a destination project
- * opening its first session to a note about whichever feature a Pathfinder
+ * opening its first session to a note about whichever ticket a Pathfinder
  * maintainer had loaded on the day of the release.
  *
+ * `context/current-feature.md` is the same file under its former name. The
+ * delivery loop stopped writing it when tickets became the executable unit, and
+ * it stays on this list because a project installed before that change still
+ * has one sitting in `context/`, and an upgrade must not ship a maintainer's
+ * copy over it.
+ *
+ * `context/history.md` is the odd one out, and the reason this set now has two
+ * kinds in it. The others are transient or local session state, ignored by
+ * Git as well as excluded here. This one is durable project truth, tracked in
+ * version control exactly as `README.md` says a project should track it — it is
+ * simply *another project's* truth. A destination project gets its own, written
+ * by `/ticket complete` from `templates/history.template.md` on the day it
+ * first completes something, and that template must keep shipping. So the
+ * promise made about this path is the publication half only: never shipped, but
+ * emphatically tracked.
+ *
  * `context` is a *directory* entry in the copy list, so anything placed beneath
  * it ships by default. Making the invariant enforced rather than intended is
  * the same move `check_no_junk_tracked` made: an ignore rule is advisory, one
@@ -86,8 +100,10 @@ export function isExcluded(basename) {
  */
 const NEVER_SHIPS = new Set([
   "context/tracker.md",
+  "context/current-ticket.md",
   "context/current-feature.md",
   "context/handoff.md",
+  "context/history.md",
 ]);
 
 /**

package/templates/feature-spec.template.md

@@ -26,13 +26,6 @@ Include only what materially helps someone implement this Feature.
 
 - `[explicit exclusion]`
 
-## Delivery Chunks
-
-1. `[small, stable, verifiable increment]`
-2. `[next increment, if needed]`
-
-Use one chunk when the Feature is already small.
-
 ## Acceptance Criteria
 
 - `[observable result proving the Feature works]`

package/templates/ticket.template.md

@@ -0,0 +1,42 @@
+# [Ticket Title]
+
+## Status
+
+Proposed
+
+## Parent Feature
+
+`[NN-feature-name.md]`
+
+## Blocked by
+
+- `[NN.TT]` — `[what this ticket needs from it, in a few words]`
+
+Write `None` when nothing blocks this ticket.
+
+## Goal
+
+[One vertical slice: a change that leaves the project working and is worth
+reviewing on its own.]
+
+## Context
+
+- Read: `[specific files or sections this ticket needs]`
+- Relevant area: `[path or component]`
+
+## Changes
+
+- `[required change]`
+- `[important constraint]`
+
+## Verification
+
+- `[command to run, or behavior to observe, and what proves it worked]`
+
+## Out of Scope
+
+- `[explicit exclusion, or None]`
+
+## Notes / Decisions
+
+- `[ticket-specific decision or constraint, or None]`

package/skills/feature/SKILL.md

@@ -1,56 +0,0 @@
----
-name: feature
-description: Run one action of the Feature delivery loop — load, start, review, or complete.
-argument-hint: load|start|review|complete
----
-
-# Feature
-
-The Feature delivery loop, as one skill. The human names the action:
-
-`/feature load`
-`/feature start`
-`/feature review`
-`/feature complete`
-
-## Process
-
-1. Take the action from the invocation.
-   If none was given, list the four actions below and stop.
-   If it is not one of the four, say so, list them, and stop.
-2. Read only `skills/feature/actions/<action>.md` and follow it exactly.
-
-## Actions
-
-- `load` — prepare one Feature for execution. Reads its spec and the minimum
-  context around it, checks for blockers, records the approval in the spec, and
-  writes the session's workspace state.
-- `start` — implement the active delivery chunk in small, stable increments,
-  restating the pre-implementation summary before editing anything.
-- `review` — verify implemented work against its Feature and report findings.
-  It changes no implementation and accepts nothing.
-- `complete` — complete work the human has accepted, through the project's
-  delivery workflow and its durable records.
-
-## Lifecycle
-
-The Feature spec's `## Status` holds the durable lifecycle state named in
-`context/ai-interaction.md`:
-
-`Proposed` → `Ready` → `In Progress` → `Complete`
-
-`Cancelled` and `Superseded` are terminal alternatives.
-
-- `load` writes `Proposed` → `Ready`.
-- `start` writes `Ready` → `In Progress`.
-- `complete` writes `Complete`.
-- `review` writes no status. Review is workflow activity, not lifecycle state.
-
-`context/current-feature.md` is transient workspace state and records no status.
-
-## Rules
-
-- Run the one action the human named. Do not continue into the next one.
-- Read only that action's file. The other three are not context for this work.
-- Human authority is unchanged: approval, acceptance, merge, and release are
-  the human's, whichever action is running.

package/skills/feature/actions/complete.md

@@ -1,22 +0,0 @@
-# Feature: Complete
-
-Invoking this action is the human's acceptance of the Feature. Do not ask for
-acceptance again.
-
-Acceptance of the Feature is not approval of the delivery steps below. Each one
-that the project's documented workflow gates is still asked for.
-
-1. Run the project's required final checks.
-2. Follow the documented Git, merge, version, release, and deployment workflow.
-   Ask for approval where it requires it. If that workflow is undocumented or
-   `TBD`, stop and ask rather than choosing one.
-3. Mark the Feature `Complete` in its spec's `## Status`.
-4. Add a compact entry to `context/history.md`.
-   Create it from `templates/history.template.md` if it does not exist.
-5. Clear or update `context/current-feature.md`. Do nothing if it does not exist.
-6. If work tracking is configured, sync the completed state.
-7. Report the completed outcome and any remaining follow-up.
-
-Do not re-review accepted work unless final verification exposes a new problem.
-
-Do not claim completion if required checks or delivery steps failed.

package/skills/feature/actions/load.md

@@ -1,45 +0,0 @@
-# Feature: Load
-
-Prepare one Feature for execution.
-
-1. Select the Feature the human named. Being invoked on it is the approval to
-   prepare it for execution, so its spec does not already have to say `Ready`.
-   Its spec is `NN-feature-name.md` in the spec source, and `NN` is its Feature
-   number.
-2. Read the Feature spec.
-3. Read only the files or context needed for the current work.
-4. Inspect the current Git state.
-5. Stop if a required human decision or explicit dependency blocks the work.
-6. Record the approval in the Feature spec's `## Status`, which holds the
-   durable lifecycle state:
-   - `Proposed` becomes `Ready`. That is the only value this action writes.
-   - `Ready` or `In Progress` is left exactly as it is. Reloading a Feature
-     mid-work is normal and must not rewrite its state.
-   - `Complete`, `Cancelled`, or `Superseded` blocks the load. Report it and
-     stop. Reopening terminal work is the human's decision.
-
-   Do this only once steps 1-5 found no blocker, and before the next step, so a
-   blocked load never leaves a promoted spec behind.
-7. Create or update `context/current-feature.md` — it does not ship, so the
-   first load writes it — with:
-   - Feature number, name, and spec path
-   - active delivery chunk
-   - Git state
-   - blocker, if any
-   - next action
-
-   Do not record the lifecycle status here. This file is transient workspace
-   state belonging to one session on one machine; the spec carries the durable
-   status.
-8. If `context/tracker.md` exists, name the tracked item for this Feature —
-   its key is that Feature number. Do nothing here if it does not.
-9. Present a short readiness summary.
-
-Do not implement the Feature. That is `/feature start`.
-
-Do not scan unrelated repository areas, load history or roadmap by default, or
-silently resolve `TBD` decisions.
-
-Do not rewrite the Feature's substance — its Goal, Context, Requirements, Out of
-Scope, Delivery Chunks, or Acceptance Criteria. `## Status` is the one field this
-action maintains.

package/skills/feature/actions/review.md

@@ -1,32 +0,0 @@
-# Feature: Review
-
-Review the actual diff and behavior, not only the developer's summary.
-
-## Check
-
-- acceptance criteria
-- regressions and important edge cases
-- security/privacy when relevant
-- accessibility, performance, compatibility, and operations when relevant
-- tests and verification
-- scope creep
-- documentation accuracy
-
-Use the project's quality priorities and existing standards where relevant.
-
-## Output
-
-Report:
-
-- `PASS`, or findings by severity
-- file/location and impact for each finding
-- what was actually verified
-- anything important that remains unverified
-
-Do not modify the implementation unless the human explicitly asks.
-
-Do not invent findings or treat passing tests as automatic acceptance.
-
-Do not write the Feature's `## Status`. Review is workflow activity, not
-lifecycle state, and a reviewed Feature stays `In Progress` until it is
-completed.

package/skills/feature/actions/start.md

@@ -1,33 +0,0 @@
-# Feature: Start
-
-Implement the active delivery chunk.
-
-1. Read only the context needed for the current work.
-2. Restate the pre-implementation summary the project's agent guide requires,
-   and wait for it to be answered where it names a human decision. Do not edit
-   any file before this step is done.
-3. Record the Feature spec's `## Status` as `In Progress`, before the first file
-   edit of the first chunk:
-   - `Ready` becomes `In Progress`. That is the only value this action writes.
-   - `In Progress` is left exactly as it is. Continuing a Feature across
-     sessions and chunks is normal and must not rewrite its state.
-   - Any other status stops the session. Report it. A Feature that was never
-     loaded is not approved for execution, and terminal work is the human's to
-     reopen.
-4. Follow the Feature and existing project conventions.
-5. Make the smallest complete change.
-6. Verify the behavior you changed.
-7. Keep the repository stable.
-8. Create or update `context/current-feature.md` with the current state and next
-   action. Do not record the lifecycle status there; the spec carries it.
-
-## Rules
-
-- Stay inside the approved scope.
-- Stop if implementation requires a human decision or material scope change.
-- Do not silently add dependencies or adopt prototype code.
-- Follow the project's approval and Git rules.
-- Do not decide that your own work is accepted.
-
-When the chunk is done, report what changed, what was verified, and anything
-unresolved.

package/skills/sync-tracker/SKILL.md

@@ -1,81 +0,0 @@
----
-name: sync-tracker
-description: Project Feature specs onto the configured work tracker.
----
-
-# Sync Tracker
-
-Sync project Features to the tracker configured in `context/tracker.md`.
-
-The repository is canonical.
-Tracker state never changes Pathfinder state.
-
-## Process
-
-1. If `context/tracker.md` does not exist, report that tracking is not
-   configured and stop. Do not propose configuring one.
-2. Read the tracker configuration. It names the tracker, how to reach it, the
-   spec source, and how a published item records its Pathfinder key. Stop if it
-   does not say how the key is recorded — without it a re-run cannot recognise
-   what it published last time, and would duplicate every item.
-3. Read the approved Feature specs from the spec source. A config that names
-   none means `context/features/`. If the named source does not exist, report
-   it and stop rather than falling back.
-4. Build one item per Feature: key, title, and body, composed only from the
-   spec.
-5. Show the proposed writes.
-6. Ask before the first write that leaves this repository. One approval covers
-   the run. A projection onto files inside the repository is an ordinary file
-   write and is not gated.
-7. Create or update only the items that changed.
-8. Report created, updated, and unchanged as counts of writes, not as final
-   tracker state.
-
-## Identity
-
-Each Feature has one stable key derived from the number in its spec filename.
-`to-specs` names every spec `NN-feature-name.md`, so
-`27-export-saved-searches.md` is `pathfinder:feature/27` in whichever directory
-it sits — moving specs orphans nothing.
-
-Read the number from the basename only. Never from the directory above it, the
-title inside it, or the order the specs happen to be read in.
-
-Match published items on that key alone. Titles are edited by humans.
-
-Skip a spec whose filename carries no number and report it by name. Do not
-assign one — numbering is `to-specs`' job, and inventing one here would publish
-an item that the next run cannot recognise.
-
-## Idempotency
-
-A second run over unchanged Features must issue **zero writes** — not writes
-that happen to be no-ops.
-
-- Compose the body as a pure function of the spec: fixed section order, no
-  timestamps, no counters, nothing derived from the run.
-- Compare normalized, never raw bytes. Strip trailing whitespace per line and
-  collapse trailing blank lines, on both sides. A tracker is not obliged to
-  return a body byte-for-byte, and a naive comparison then rewrites every item
-  forever while looking like working sync.
-- Where the config defines tags, compare them as sets, not ordered lists.
-- Edit in place. Never close, reopen, delete, or recreate an item.
-- Leave any item whose key is absent from this run completely alone.
-
-`3 items, 0 changes` is the expected second run and the most important line of
-output.
-
-## Rules
-
-- Do not decompose Features into tickets.
-- Do not derive dependency edges, ordering, or a graph from a spec. A Feature
-  may mention a dependency under `## Notes / Decisions` for a human to read;
-  it is prose, not structure, and this skill does not parse or orchestrate it.
-- Do not infer labels, tags, status, or other metadata.
-- Do not modify Feature specs from tracker state.
-- Do not read tracker state back into anything.
-- Do not delete tracker items automatically.
-- Do not rewrite unchanged items.
-- Local Markdown tracking is an ordinary repository/file write.
-- External trackers require human approval before writing.
-- Stop and report when the config, the specs, and the tracker disagree.