create-pathfinder 1.7.0 → 2.0.0

package/src/install.mjs

@@ -16,7 +16,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 
-import { COPY_LIST, isExcluded } from "./kit.mjs";
+import { COPY_LIST, isExcluded, neverShips } from "./kit.mjs";
 import {
   ADAPTER_STATE,
   adapterPath,
@@ -43,6 +43,10 @@ export function planInstall(kitRoot, targetRoot, { force = false } = {}) {
   for (const entry of COPY_LIST) {
     for (const source of walkFiles(join(kitRoot, entry))) {
       const relativePath = relative(kitRoot, source).split(sep).join("/");
+      // Filtered here rather than in walkFiles, which sees basenames only and
+      // would have to guess whether a `tracker.md` is *the* one.
+      if (neverShips(relativePath)) continue;
+
       const destination = join(targetRoot, relativePath);
       const exists = existsSync(destination);
 

package/src/kickstart-prompt.mjs

@@ -4,7 +4,7 @@
  * This used to be one hardcoded string naming a file path, and that was right
  * for exactly as long as Pathfinder configured nothing. Once a run can generate
  * native adapters, the path form is no longer the best answer for someone who
- * just watched twenty skills be installed into their harness — it is the answer
+ * just watched the whole kit be installed into their harness — it is the answer
  * for someone whose tool cannot discover them.
  *
  * A pure function of the selection, deliberately: no filesystem, no detection,

package/src/kit.mjs

@@ -8,7 +8,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -49,6 +49,75 @@ export function isExcluded(basename) {
   return EXCLUDED.has(basename) || basename.startsWith("._");
 }
 
+/**
+ * Kit files that are deliberately not part of the kit, by kit-relative path.
+ *
+ * A different idea from EXCLUDED above, and kept separate for that reason.
+ * Those are OS and editor droppings that were never anybody's file. These are
+ * 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.
+ *
+ * `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/current-feature.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 `load-feature`
+ * 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
+ * maintainer had loaded on the day of the release.
+ *
+ * `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
+ * `git add -f` defeats it, and `stage-kit.mjs` copies from the working tree
+ * without consulting it at all.
+ *
+ * Matched on the kit-relative path, never the basename — a project's own
+ * `tracker.md` somewhere else is not this file and must not be caught by it.
+ */
+const NEVER_SHIPS = new Set([
+  "context/tracker.md",
+  "context/current-feature.md",
+  "context/handoff.md",
+]);
+
+/**
+ * Is this kit-relative path one the kit must never hand over?
+ *
+ * @param {string} relativePath forward-slashed, relative to the kit root
+ */
+export function neverShips(relativePath) {
+  return NEVER_SHIPS.has(relativePath);
+}
+
+/**
+ * A `cpSync` filter that drops never-ships files from a recursive copy.
+ *
+ * Lives here rather than inline in `stage-kit.mjs` so the staging path and its
+ * test run the same code. A test that rebuilds the predicate proves only that
+ * `cpSync` honours `filter`; it cannot catch the path arithmetic below going
+ * wrong, which is the part with anything to get wrong in it.
+ *
+ * `cpSync` hands the filter absolute paths and calls it for the copy root
+ * itself, so the root resolves to `""` and is kept — filtering a directory out
+ * would take its whole subtree with it.
+ *
+ * @param {string} rootDir absolute path the kit-relative paths are relative to
+ * @returns {(source: string) => boolean} true to copy, false to skip
+ */
+export function neverShipsFilter(rootDir) {
+  return (source) => !neverShips(relative(rootDir, source).split(sep).join("/"));
+}
+
 const PACKAGE_ROOT = resolve(HERE, "..");
 
 /**

package/templates/CHANGELOG.template.md

@@ -1,6 +1,7 @@
 # Changelog
 
-Use this file only when the destination project adopts a changelog.
+Use only when the project adopts a changelog.
+Record user-facing changes, not implementation history.
 
 ## [Unreleased]
 

package/templates/feature-spec.template.md

@@ -2,98 +2,42 @@
 
 ## Status
 
-Not Started
-
-## Overview
-
-Describe the smallest coherent outcome, where it fits, and why it matters.
-
-## Problem
-
-- What is missing, risky, confusing, inaccessible, unreliable, or inefficient?
-- Who or what is affected?
-- Why does this matter now?
+Proposed
 
 ## Goal
 
-State one user-visible or system-verifiable outcome.
+[One clear user-visible or system-verifiable outcome.]
+
+## Context
 
-## Dependencies
+Include only what materially helps someone implement this Feature.
 
-- Earlier feature, system, decision, prototype, or `None`.
+- Read: `[specific files, sections, or systems]`
+- Relevant area: `[path or component]`
+- Avoid: `[unrelated area, if useful]`
 
 ## Requirements
 
-- Requirement 1
-- Requirement 2
-- Requirement 3
-- Include relevant failure, permission, loading, empty, retry, responsive, accessibility, operational, or compatibility states only when applicable.
+- `[required behavior]`
+- `[important constraint]`
+- `[relevant edge or failure behavior, when applicable]`
 
 ## Out of Scope
 
-- Explicit exclusion
-- Later feature, if known
-- Unrelated refactors, dependencies, or polish
-
-## Experience or Operational Notes — When Applicable
-
-- User interaction, system behavior, responsive behavior, accessibility, observability, performance, security, or operational expectations.
-
-## Technical Notes
-
-Likely areas:
-
-- `[specific path or bounded area]`
-
-Implementation constraints:
-
-- Follow project context and approved prototype direction.
-- Do not silently resolve open architecture decisions.
-- Keep prototype and production code boundaries explicit.
-
-## Context Boundary
-
-Read:
-
-- `[specific context and code]`
-
-Avoid loading:
-
-- `[unrelated systems, old specs, generated output]`
-
-Split this feature further if its required context is not focused enough for reliable implementation and verification.
+- `[explicit exclusion]`
 
 ## Delivery Chunks
 
-1. `[stable, verifiable increment]`
-2. `[stable, verifiable increment]`
-3. `[optional stable increment]`
+1. `[small, stable, verifiable increment]`
+2. `[next increment, if needed]`
 
-Each chunk should leave the project stable.
+Use one chunk when the Feature is already small.
 
 ## Acceptance Criteria
 
-- The defined outcome works end to end within scope.
-- Relevant failure and edge behavior is handled.
-- Applicable quality requirements are met.
-- Required automated/manual checks pass.
-- The work can be reviewed independently.
-
-## Verification
-
-- Manual or operational checks:
-- Automated checks:
-- Edge cases:
-- Quality checks:
-
-## Learning Targets
-
-- Concepts worth explaining after completion:
-- Diagram or demonstration opportunity:
-- Quiz ideas:
+- `[observable result proving the Feature works]`
+- `[important verification result]`
 
-## Suggested Delivery Metadata
+## Notes / Decisions
 
-- Git action: `[follow project workflow]`
-- Suggested branch, when applicable: `[project naming convention]`
-- Suggested commit, when applicable: `[project convention]`
+- `[Feature-specific dependency, approved decision, constraint, or None]`

package/templates/history.template.md

@@ -0,0 +1,12 @@
+# Project History
+
+Compact record of completed work.
+
+## Completed
+
+### [YYYY-MM-DD] — [Feature or milestone]
+
+- Outcome: `[what changed for the project/user]`
+- Verification: `[brief result or evidence pointer]`
+- Commit/PR: `[sha, PR, or release reference]`
+- Follow-up: `[only if something remains, otherwise none]`

package/templates/lesson.template.md

@@ -1,71 +1,42 @@
 # Lesson — [Feature Name]
 
 - Date:
-- Branch:
-- Feature spec:
-- Commit or diff range:
-- Difficulty:
-- Estimated review time:
+- Feature:
+- Commit/diff:
 
-## 1. Feature in One Minute
+## What Changed
 
-What changed, why it exists, and the user or system value it creates.
+Explain what was implemented and why it matters.
 
-## 2. Mental Model
+## Mental Model
 
-Explain the feature through one clear model. Include a small Mermaid diagram when useful.
+Explain the simplest useful way to understand the Feature.
 
-## 3. Execution and Data Flow
+Include a small diagram only when it helps.
 
-Trace one representative interaction from input to visible result.
+## How It Works
 
-## 4. Important Files
+Trace one representative flow through the implementation.
 
-| File | Responsibility | Why it matters |
-| --- | --- | --- |
+## Important Files
 
-## 5. Key Decisions and Tradeoffs
+| File | Responsibility |
+| --- | --- |
 
-For each meaningful decision:
+Include only files that materially help understanding.
 
-- Decision
-- Evidence in the repository
-- Benefit
-- Cost
-- Credible alternative
-- When the alternative would be better
+## Key Decisions
 
-## 6. Concepts Worth Retaining
+- `[important decision and why it was made]`
 
-Limit this to the most transferable concepts.
+Include only decisions worth remembering.
 
-## 7. Quality Lens
+## Concepts to Retain
 
-### Testing
+- `[transferable concept]`
 
-### Accessibility
+## Check Your Understanding
 
-### Performance
-
-### Maintainability
-
-### Error and edge states
-
-## 8. Production-Scale Gap
-
-What would need to change for higher traffic, larger datasets, multiple teams, stricter security, or real-time collaboration?
-
-## 9. Interview Preparation
-
-- Likely question:
-- Strong answer outline:
-- Follow-up question:
-- Vocabulary to use carefully:
-
-## 10. Check Your Understanding
-
-Three short retrieval questions. Do not include answers here.
-
-## 11. Suggested Next Action
-
-Choose one: quiz, challenge, architecture lesson, spaced review, or no further work.
+1. `[question]`
+2. `[question]`
+3. `[question]`

package/templates/project-overview.template.md

@@ -1,129 +1,108 @@
 # Project Overview
 
-> Describe the product, audience, intended feeling, and reason it should exist.
+Durable, project-wide context.
 
-## Status
+Keep this concise. Feature scope, active work, history, and temporary
+planning belong elsewhere.
 
-- Project: `[Project Name]`
-- Stage: `[idea / prototype / MVP / production / maintenance]`
-- Repo type: `[new / existing / application / library / service / monorepo / other]`
-- Primary goal: `[success definition]`
-- Prototype status: `[not required / recommended / in progress / approved / rejected / TBD]`
+Two words keep an unmade decision visible:
 
-## Decision States
+- `TBD` — a human decision is still required
+- `None` — considered and intentionally excluded
 
-These four words describe a decision:
+Leave nothing blank. A blank field is indistinguishable from an abandoned one.
 
-- `TBD` — human decision required
-- `None` — intentionally excluded
-- `N/A` — not applicable
-- `Deferred` — intentionally postponed
+## Project
 
-## Record Status
+- Name: `[Project Name]`
+- Stage: `[idea / prototype / MVP / production / maintenance]`
+- Repo type: `[application / library / service / monorepo / other]`
+- Primary goal: `[what success means]`
 
-A `Status` column describes the record, not the decision:
+## Product
 
-- `proposed` — written down, not yet approved by the human
-- `accepted` — approved by the human
-- `superseded` — replaced by a later decision, kept for history
+- Problem: `[problem being solved]`
+- Primary user: `[who it is for]`
+- First useful outcome: `[smallest meaningful result]`
+- Distinctive quality: `[what should make it good or different]`
+- Avoid becoming: `[important anti-goal]`
 
-The two answer different questions. `TBD` says nobody has decided yet. `proposed` says something was recorded for the human to approve. A recorded proposal is not an approved decision.
+## Scope
 
-## Product Vision
+### In
 
-- Problem:
-- Primary user:
-- First useful outcome:
-- Distinctive quality:
-- What this must avoid becoming:
+- `[core outcome]`
 
-## MVP Boundary
+### Out
 
-### In scope
+- `[explicit non-goal]`
 
-- `[essential outcome]`
+## Requirements and Open Decisions
 
-### Out of scope
+Record only what constrains the work. An open decision stays `TBD` until a
+human resolves it.
 
-- `[deferred outcome]`
+| Type | Item | Notes |
+| --- | --- | --- |
+| Requirement | `[must be true]` | |
+| Preference | `[desired but negotiable]` | |
+| Constraint | `[limit or external obligation]` | |
+| Open decision | `TBD` | |
+
+## System
 
-### Success signals
+Record only important project-wide architecture and constraints.
 
-- `[observable user, business, system, or learning signal]`
+- Architecture: `[short description or TBD]`
+- Main components: `[components or TBD]`
+- Constraints: `[important constraint or None]`
 
-## Core Experience or System Flow
+Optional flow:
 
 ```text
-starting state -> action/process -> useful result -> reason to return or continue
+[input] -> [component] -> [result]
 ```
 
-## Requirements, Preferences, Constraints, and Open Decisions
+## Technology
 
-| Type | Item | Notes |
+The stack an agent must follow rather than choose. Keep the rows this project
+actually has.
+
+| Layer | Choice | Reason |
 | --- | --- | --- |
-| Requirement | `[must be true]` | |
-| Preference | `[desired but negotiable]` | |
-| Constraint | `[limit or external obligation]` | |
-| Open decision | `[TBD]` | |
-
-## Recommended and Approved Technology
-
-Recommended and approved choices both live here. `debate-me` and `kickstart-pathfinder` may record a choice before the human approves it; that row is marked `proposed` in `Status` and stays that way until it is `accepted`. Leave `Status` empty while the choice is still `TBD`.
-
-| Layer | Choice | Reason | Status |
-| --- | --- | --- | --- |
-| Platform/runtime | `TBD` | | |
-| Language(s) | `TBD` | | |
-| UI/presentation | `TBD / N/A` | | |
-| Backend/application layer | `TBD / None` | | |
-| Data storage | `TBD / None` | | |
-| Data access/ORM | `TBD / None` | | |
-| Authentication | `TBD / None` | | |
-| Authorization | `TBD / None` | | |
-| API/integration style | `TBD / None` | | |
-| State management | `TBD / N/A` | | |
-| Testing | `TBD` | | |
-| Build/package tooling | `TBD` | | |
-| Deployment/runtime environment | `TBD` | | |
-| Observability | `TBD / Deferred` | | |
-| AI providers/models | `TBD / None` | | |
-
-## Architecture
-
-- Architecture style: `TBD`
-- Repository shape: `TBD`
-- Main boundaries/modules:
-- Data/control flow:
-- Important tradeoffs:
+| Platform/runtime | `TBD` | |
+| Language(s) | `TBD` | |
+| UI/presentation | `TBD / None` | |
+| Backend/application | `TBD / None` | |
+| Data storage and access | `TBD / None` | |
+| Auth | `TBD / None` | |
+| Testing | `TBD` | |
+| Build and package tooling | `TBD` | |
 
-```text
-[path or module]    # purpose
-[path or module]    # purpose
-```
+## Commands
 
-## Prototype Direction
+The commands an agent runs to verify its own work.
 
-- Prototype needed: `[yes / no / TBD]`
-- Type: `[experience / technical / diagram / mixed / N/A]`
-- Assumption being validated:
-- Output location:
-- Review criteria:
-- Approved direction:
-- Elements explicitly not adopted into production:
+```text
+install: TBD
+run/dev: TBD
+test: TBD
+lint/static analysis: TBD
+build/package: TBD
+```
 
 ## Delivery Workflow
 
 | Area | Choice |
 | --- | --- |
 | Git workflow | `TBD` |
-| Default/stable branch | `TBD` |
-| Branch naming | `TBD / N/A` |
+| Default branch | `TBD` |
+| Branch naming | `TBD / None` |
 | Commit convention | `TBD / None` |
-| Pull request policy | `TBD` |
+| Review policy | `TBD` |
 | Merge strategy | `TBD` |
 | CI/CD | `TBD / None` |
-| Versioning | `TBD / None` |
-| Changelog | `TBD / None` |
+| Versioning and changelog | `TBD / None` |
 | Release process | `TBD / None` |
 
 ## Environments and Integrations
@@ -133,14 +112,12 @@ Recommended and approved choices both live here. `debate-me` and `kickstart-path
 | Local development | `TBD` | |
 | Preview/staging | `TBD / None` | |
 | Production | `TBD / None` | |
-| Environment configuration | `TBD` | |
-| Secrets management | `TBD / N/A` | |
-| External APIs/services | `TBD / None` | |
-| Rate/cost limits | `TBD / N/A` | |
+| Configuration and secrets | `TBD` | |
+| External services/APIs | `TBD / None` | |
 
 ## Quality Priorities
 
-Rank only what matters for this project.
+Rank only what matters for this project, highest first.
 
 1. `[priority]`
 2. `[priority]`
@@ -149,63 +126,21 @@ Rank only what matters for this project.
 | Concern | Target or decision |
 | --- | --- |
 | Correctness/reliability | `TBD` |
-| Security/privacy | `TBD / N/A` |
-| Accessibility | `TBD / N/A` |
-| Performance | `TBD / N/A` |
-| Browser/platform support | `TBD / N/A` |
-| Localization | `TBD / None` |
-| Offline behavior | `TBD / N/A` |
-
-## Core Domain Concepts
-
-Describe durable concepts without assuming a language:
-
-```text
-Entity/Concept: Example
-Required fields: id, name
-Important states: draft, active, archived
-Relationships: belongs to / contains / references
-```
-
-## Build, Test, and Run Commands
+| Security/privacy | `TBD / None` |
+| Accessibility | `TBD / None` |
+| Performance | `TBD / None` |
+| Supported platforms | `TBD / None` |
 
-```text
-install: TBD
-run/dev: TBD
-test: TBD
-lint/static analysis: TBD
-build/package: TBD
-other verification: TBD
-```
+## Durable Decisions
 
-## Build Phases
+Decisions that outlive a Feature, including approved prototype direction and
+anything a prototype proved must not reach production.
 
-| Phase | Goal | Visible or verifiable win |
+| Date | Decision | Reason |
 | --- | --- | --- |
-| 1 | Foundation | `[result]` |
-| 2 | Core experience/system | `[result]` |
-| 3 | Real data/integration | `[result]` |
-| 4 | Quality and release readiness | `[result]` |
+| `[YYYY-MM-DD]` | `[decision]` | `[reason]` |
 
-## Learning Goals
+## Learning
 
-- What the human wants to understand:
+- What the human wants to understand: `[topics or None]`
 - Preferred lesson format: `[HTML / MDX / Markdown / existing docs system / TBD]`
-- Quiz preferences:
-- Topics to emphasize:
-- Topics to avoid over-explaining:
-
-## Durable Decisions
-
-| Date | Decision | Reason | Status |
-| --- | --- | --- | --- |
-| `[YYYY-MM-DD]` | `[decision]` | `[reason]` | `[proposed / accepted / superseded]` |
-
-## Things To Avoid
-
-- Building before critical decisions are understood.
-- Treating recommendations as approval.
-- Silently resolving `TBD` items.
-- Turning prototype shortcuts into production defaults.
-- Over-documenting temporary implementation detail.
-- Creating feature specs too large for a focused LLM context window.