create-pathfinder 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -79,11 +79,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
-- `load-feature` — prepare one feature for implementation
-- `start-feature` — implement scoped delivery chunks
+- `feature` — run one action of the Feature delivery loop: `load`, `start`, `review`, `complete`
 - `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it
-- `review-feature` — review against requirements, regressions, and standards
-- `complete-feature` — verify and close a feature cleanly
 - `learn-feature` — create an interactive lesson for a completed feature
 - `learn-codebase` — create a modular learning portal for the repository
 - `teach-feature` — teach the verified current feature from its spec, diff, tests, and implementation

package/context/ai-interaction.md

@@ -38,10 +38,10 @@ Inspect current Git state before acting. If the workflow is unclear or
 
 Use the workflow skills instead of recreating their procedures in chat:
 
-1. `load-feature` — load the active work and relevant context.
-2. `start-feature` — implement the current delivery chunk.
-3. `review-feature` — verify the work and report findings.
-4. `complete-feature` — complete accepted work and durable records.
+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.
 
 Roles are optional. The workflow must work without activating one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",

package/roles/developer.md

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

package/roles/tester.md

@@ -20,7 +20,7 @@ Do not rely on the developer's summary as proof.
 
 ## Use
 
-- `review-feature` to verify implemented work.
+- `feature` — 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 `start-feature`.
+If the task is planned feature construction, use `/feature start`.
 
-If the goal is reviewing completed implementation for possible defects, use `review-feature`.
+If the goal is reviewing completed implementation for possible defects, use `/feature 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 `review-feature`
-* replace `complete-feature`
+* replace `/feature review`
+* replace `/feature complete`
 * silently change architecture or dependencies
 * turn debugging into opportunistic refactoring
 * hide uncertainty behind a successful-looking workaround

package/skills/feature/SKILL.md

@@ -0,0 +1,56 @@
+---
+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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,45 @@
+# 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/{review-feature/SKILL.md → feature/actions/review.md}

@@ -1,9 +1,4 @@
----
-name: review-feature
-description: Verify implemented work against its Feature and report findings.
----
-
-# Review Feature
+# Feature: Review
 
 Review the actual diff and behavior, not only the developer's summary.
 
@@ -31,3 +26,7 @@ Report:
 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

@@ -0,0 +1,33 @@
+# 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/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
-* `load-feature` — when the analysis applies to one already-planned feature
+* `/feature load` — when the analysis applies to one already-planned feature
 * `learn-codebase` — when the user wants to understand their own repository instead
 * no handoff — when the user only requested analysis
 

package/skills/role/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: role
 description: Activate one named Pathfinder role for the current session.
+argument-hint: planner|developer|tester
 ---
 
 # Role

package/src/cli.mjs

@@ -16,6 +16,7 @@ import { detectEditors, openInEditor } from "./editor.mjs";
 import { kickstartPrompt, kickstartPromptLines } from "./kickstart-prompt.mjs";
 import { createTheme } from "./theme.mjs";
 import { createProgress } from "./progress.mjs";
+import { summarize } from "./outcome.mjs";
 import {
   HARNESSES,
   HARNESS_IDS,
@@ -48,6 +49,8 @@ Options:
                   It does not authorize \`git init\` or configure any tool;
                   pass --git-init and --agents for those.
   -h, --help      Show this message.
+  -v, --version   Print the version and exit, whatever else you passed.
+                  Nothing else is printed.
 
 Adapters are generated files Pathfinder owns and regenerates without --force.
 A file it did not generate is never replaced, at any path, without --force.
@@ -82,6 +85,22 @@ export async function run(
 ) {
   const options = parseArguments(argv);
 
+  // Answered before the error branch, and before every other flag: `--version`
+  // is a question about this package, not about this run. It holds outside a Git
+  // repository, alongside a misspelled flag, and when stdout is redirected to a
+  // file or a pipe, because the one thing a caller asking for a version number
+  // can never use is a paragraph explaining why the version could not be
+  // printed. A reader that closes the pipe before this write lands still raises
+  // EPIPE, as it does for every other write here; that is not something this
+  // early return changes.
+  //
+  // One line, `VERSION` alone. No `v` prefix, no identity block, no findings:
+  // this output is read by scripts, and the plain form is the whole contract.
+  if (options.version) {
+    out(`${VERSION}\n`);
+    return 0;
+  }
+
   if (options.error) {
     err(`create-pathfinder: ${options.error}\n\n${USAGE}`);
     return 2;
@@ -270,7 +289,13 @@ export async function run(
   progress.finish();
   if (!options.dryRun && theme.tier !== "contract") out("\n");
 
-  report({ result, plan, adapters, harnesses, customTools, cwd, gitRoot, options, out, err, theme });
+  // Derived here, once, and handed down. Below this line nothing re-reads a
+  // plan or a result: the two renderings disagree about everything except the
+  // facts, and this is what makes "except the facts" true rather than a hope
+  // about two functions being edited together.
+  const outcome = summarize({ plan, result, adapters, harnesses, options });
+
+  report({ outcome, harnesses, customTools, cwd, gitRoot, options, out, err, theme });
 
   // After the report, because the first offer is about the prompt the report
   // just printed — and because a question above the summary would make the user
@@ -286,7 +311,7 @@ export async function run(
   //
   // Not printed when anything failed. A sign-off over an error is a tool that
   // did not read its own output.
-  const failed = result.errors.length > 0 || adapters.result.errors.length > 0;
+  const failed = outcome.failures.length > 0;
   if (theme.tier !== "contract" && !failed) {
     out(`\n  ${theme.dim(SIGN_OFF)}\n`);
   }
@@ -497,9 +522,9 @@ function generateAdapters({ plan, harnesses, options, result, onProgress, onHarn
  * person reading has just watched a bar fill. A re-run that wrote nothing says
  * so plainly instead of inventing an achievement.
  */
-function endingHeadline({ theme, written, adapters, attention, options }) {
+function endingHeadline({ theme, outcome, options }) {
   const mark = theme.glyph;
-  const built = adapters.result.generated + adapters.result.replaced;
+  const { written, built, attention } = outcome;
 
   // Something wants a human. Still ready — it is — but this is not the moment
   // for confetti over somebody's conflicted file.
@@ -523,9 +548,9 @@ function endingHeadline({ theme, written, adapters, attention, options }) {
  * so plainly instead of inventing an achievement out of the harnesses it did
  * not have to configure.
  */
-function endingDetail({ written, adapters, harnesses, attention, options }) {
+function endingDetail({ outcome, harnesses, options }) {
   const parts = [];
-  const built = adapters.result.generated + adapters.result.replaced;
+  const { written, built, attention } = outcome;
 
   if (written > 0) parts.push(`${written} file${plural(written)}`);
   if (built > 0) parts.push(`${built} adapter${plural(built)}`);
@@ -563,21 +588,43 @@ function countWritten(result, plan, options) {
   return result.written + result.overwritten;
 }
 
+/**
+ * Every option at its unasked-for default. `parseArguments` starts from a copy
+ * of this and `--version` returns one, so the two agree by construction.
+ */
+const NO_OPTIONS = {
+  dryRun: false,
+  force: false,
+  help: false,
+  version: false,
+  gitInit: false,
+  noGitInit: false,
+  noClipboard: false,
+  noOpen: false,
+  yes: false,
+  // null means "not said", which is not the same as "none". Only the first
+  // suppresses the question.
+  agents: null,
+  error: null,
+};
+
+/**
+ * Which options this run asks for.
+ *
+ * `-v` and `--version` are recognized here, before any other token in `argv`
+ * is interpreted, because they ask what this package is rather than what this
+ * run should do. A misspelled flag or an invalid `--agents` value must not
+ * swallow the answer, and the answer must not depend on position: a wrapper
+ * that appends `--version` to arguments it was handed still gets a version
+ * number. That is why this is a scan and not another `case` below — the
+ * refusals in the loop return early, and one of them would otherwise win.
+ */
 function parseArguments(argv) {
-  const options = {
-    dryRun: false,
-    force: false,
-    help: false,
-    gitInit: false,
-    noGitInit: false,
-    noClipboard: false,
-    noOpen: false,
-    yes: false,
-    // null means "not said", which is not the same as "none". Only the first
-    // suppresses the question.
-    agents: null,
-    error: null,
-  };
+  if (argv.some((argument) => argument === "-v" || argument === "--version")) {
+    return { ...NO_OPTIONS, version: true };
+  }
+
+  const options = { ...NO_OPTIONS };
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
@@ -988,15 +1035,16 @@ export function formatFindings(findings, { theme = createTheme() } = {}) {
 function report(args) {
   // Two renderings, kept adjacent on purpose.
   //
-  // The duplication below is a known, accepted cost rather than an oversight.
-  // `contractReport` owes byte-for-byte what 1.4.1 printed, to scripts that
-  // parse it; `expressiveReport` owes a person a legible hierarchy. Merging
-  // them would mean one function whose every line carries a conditional, and
-  // the first wording improvement would silently break somebody's grep.
+  // What is reported is decided once, in `summarize`: both functions below read
+  // the same outcome and neither recounts anything. What remains separate is how
+  // it looks. `contractReport` owes byte-for-byte what 1.4.1 printed, to scripts
+  // that parse it; `expressiveReport` owes a person a legible hierarchy. Merging
+  // them would mean one function whose every line carries a conditional, and the
+  // first wording improvement would silently break somebody's grep.
   //
-  // They are written next to each other so that editing one is an obvious
-  // prompt to consider the other. Anything that changes what is *reported* —
-  // as opposed to how it looks — has to be made twice, and that is the point.
+  // So a new reported fact belongs in the outcome, and reaches both renderings
+  // from there; only its wording has to be chosen twice. They are written next
+  // to each other so that editing one is an obvious prompt to consider the other.
   if (args.theme.tier === "contract") return contractReport(args);
   return expressiveReport(args);
 }
@@ -1008,7 +1056,7 @@ function report(args) {
  * `test/non-interactive.test.mjs` and by a capture-and-compare against the
  * published package, because a script somewhere is reading it.
  */
-function contractReport({ result, plan, adapters, harnesses, customTools, cwd, gitRoot, options, out, err, theme }) {
+function contractReport({ outcome, harnesses, customTools, cwd, gitRoot, options, out, err, theme }) {
   const lines = [];
   const verb = options.dryRun ? "Would install" : "Installed";
 
@@ -1018,25 +1066,24 @@ function contractReport({ result, plan, adapters, harnesses, customTools, cwd, g
   }
   lines.push("");
 
-  const written = options.dryRun ? plan.filter((i) => i.status === "write").length : result.written;
+  const { written, overwritten, skipped } = outcome;
   lines.push(`  ${written} file${plural(written)} ${options.dryRun ? "to write" : "written"}`);
 
-  if (result.overwritten > 0) {
-    lines.push(`  ${result.overwritten} file${plural(result.overwritten)} overwritten (--force)`);
+  if (overwritten > 0) {
+    lines.push(`  ${overwritten} file${plural(overwritten)} overwritten (--force)`);
   }
 
-  lines.push(...contractAdapterLines({ adapters, harnesses, options, theme }));
+  lines.push(...contractAdapterLines({ outcome, options, theme }));
   lines.push(...customToolLines(customTools));
 
-  const skipped = plan.filter((item) => item.status === "skip");
   if (skipped.length > 0) {
     lines.push(`  ${skipped.length} file${plural(skipped.length)} left untouched because they already exist:`);
-    for (const item of skipped) lines.push(`      ${item.relativePath}`);
+    for (const path of skipped) lines.push(`      ${path}`);
     lines.push("");
     lines.push("  Nothing above was modified. Re-run with --force to replace them.");
   }
 
-  if (written === 0 && skipped.length === plan.length) {
+  if (outcome.alreadyInstalled) {
     lines.push("");
     lines.push("The kit is already installed here.");
   }
@@ -1054,7 +1101,7 @@ function contractReport({ result, plan, adapters, harnesses, customTools, cwd, g
 
   out(lines.join("\n") + "\n");
 
-  const failures = [...result.errors, ...adapters.result.errors];
+  const { failures } = outcome;
   if (failures.length > 0) {
     const detail = failures.map((error) => `  ${error.relativePath}: ${error.message}`).join("\n");
     err(`\ncreate-pathfinder: ${failures.length} file${plural(failures.length)} could not be written:\n${detail}\n`);
@@ -1198,10 +1245,12 @@ async function offerEditor({ editors, cwd, prompter, out, env, platform, theme }
  * Empty when no harness was chosen, which is the default and must stay
  * invisible: a scripted 1.4.1-era run prints exactly what it always did.
  */
-function contractAdapterLines({ adapters, harnesses, options, theme }) {
-  if (harnesses.length === 0) return [];
-
-  if (adapters.blocked) {
+function contractAdapterLines({ outcome, options, theme }) {
+  // No explicit "no harness chosen" guard: that case is no rows and
+  // `blocked: false`, so it falls straight through to an empty list. The
+  // blocked case is checked first because it is *also* no rows, and the two
+  // must not print the same nothing.
+  if (outcome.blocked) {
     return [
       "",
       "  No adapters were generated, because the kit copy did not finish.",
@@ -1210,21 +1259,9 @@ function contractAdapterLines({ adapters, harnesses, options, theme }) {
     ];
   }
 
-  const failed = new Set(adapters.result.errors.map((error) => error.relativePath));
   const lines = [];
 
-  for (const harness of harnesses) {
-    const mine = adapters.plan.filter(
-      (item) => item.harness === harness && !failed.has(item.relativePath),
-    );
-    const count = (action) => mine.filter((item) => item.action === action).length;
-
-    const generated = count("write");
-    const replaced = count("replace");
-    const unchanged = count("up-to-date");
-    const conflicts = mine.filter((item) => item.action === "conflict");
-    const orphans = mine.filter((item) => item.action === "orphan");
-
+  for (const { harness, generated, replaced, unchanged, conflicts, orphans } of outcome.harnessRows) {
     lines.push(
       `  ${generated} ${harness.label} skill adapter${plural(generated)} ` +
         (options.dryRun ? "to generate" : "generated"),
@@ -1242,7 +1279,7 @@ function contractAdapterLines({ adapters, harnesses, options, theme }) {
       lines.push(
         `  ${conflicts.length} file${plural(conflicts.length)} left untouched because Pathfinder did not write ${conflicts.length === 1 ? "it" : "them"}:`,
       );
-      for (const item of conflicts) lines.push(`      ${item.relativePath}`);
+      for (const path of conflicts) lines.push(`      ${path}`);
       lines.push("");
       lines.push(
         conflicts.length === 1
@@ -1253,8 +1290,8 @@ function contractAdapterLines({ adapters, harnesses, options, theme }) {
       );
     }
 
-    for (const item of orphans) {
-      lines.push(`  ${item.relativePath} delegates to a skill this version no longer`);
+    for (const path of orphans) {
+      lines.push(`  ${path} delegates to a skill this version no longer`);
       lines.push("  ships. It was left in place; delete it yourself if you want it gone.");
     }
   }
@@ -1311,7 +1348,7 @@ function customToolLines(customTools = []) {
  *   and get colour. The paths underneath get neither, for the reason below.
  * - **Diagnostics stay pasteable.** See `pathList`.
  */
-function expressiveReport({ result, plan, adapters, harnesses, customTools, cwd, gitRoot, options, out, err, theme }) {
+function expressiveReport({ outcome, harnesses, customTools, cwd, gitRoot, options, out, err, theme }) {
   const mark = theme.glyph;
   const lines = [];
   const verb = options.dryRun ? "Would install" : "Installed";
@@ -1325,7 +1362,7 @@ function expressiveReport({ result, plan, adapters, harnesses, customTools, cwd,
     );
   }
 
-  const written = options.dryRun ? plan.filter((i) => i.status === "write").length : result.written;
+  const { written, overwritten, skipped } = outcome;
   // A zero is reported, never celebrated. `✓ 0 files written` is a tick over
   // nothing happening, which is the kind of detail that makes a whole summary
   // feel automated rather than read.
@@ -1342,18 +1379,17 @@ function expressiveReport({ result, plan, adapters, harnesses, customTools, cwd,
   // was asked to do, and marking a requested action as a warning is how a tool
   // teaches people to ignore its warnings. The files it replaced are still
   // worth stating plainly, which is what `info` is for.
-  if (result.overwritten > 0) {
+  if (overwritten > 0) {
     lines.push(
       railed(
         theme,
-        theme.info(`${mark.info} ${result.overwritten} file${plural(result.overwritten)} overwritten (--force)`),
+        theme.info(`${mark.info} ${overwritten} file${plural(overwritten)} overwritten (--force)`),
       ),
     );
   }
 
-  lines.push(...expressiveAdapterLines({ adapters, harnesses, options, theme }));
+  lines.push(...expressiveAdapterLines({ outcome, options, theme }));
 
-  const skipped = plan.filter((item) => item.status === "skip");
   if (skipped.length > 0) {
     lines.push(
       railed(
@@ -1379,33 +1415,26 @@ function expressiveReport({ result, plan, adapters, harnesses, customTools, cwd,
         theme,
         word: "Skipped",
         summary: `${skipped.length} file${plural(skipped.length)} already exist${skipped.length === 1 ? "s" : ""} and ${skipped.length === 1 ? "was" : "were"} left untouched`,
-        paths: skipped.map((item) => item.relativePath),
+        paths: skipped,
         advice: ["Nothing above was modified. Re-run with --force to replace them."],
       }),
     );
   }
 
-  lines.push(...expressiveAdapterBlocks({ adapters, harnesses, theme }));
+  lines.push(...expressiveAdapterBlocks({ outcome, theme }));
 
   if (customTools.length > 0) lines.push(...customToolLines(customTools));
 
-  const failureCount = result.errors.length + adapters.result.errors.length;
-  // What actually wants a human: a contested path, or an adapter pointing at a
-  // skill that is gone. Skipped files are deliberately *not* counted here.
-  // A re-run over an existing install skips every file by design, and calling
-  // thirty-six routine skips "things to look at" would turn the one number that
-  // should mean something into noise nobody reads twice.
-  const attention = adapters.blocked
-    ? 0
-    : adapters.plan.filter((item) => item.action === "conflict" || item.action === "orphan").length;
-
-  if (failureCount === 0) {
+  // `attention` is what actually wants a human: a contested path, or an adapter
+  // pointing at a skill that is gone. Skipped files are deliberately not among
+  // them — see `summarize`, which is where that decision now lives.
+  if (outcome.failures.length === 0) {
     lines.push("");
     lines.push(
       ...readyBlock({
         theme,
-        headline: endingHeadline({ theme, written, adapters, attention, options }),
-        detail: endingDetail({ written, adapters, harnesses, attention, options }),
+        headline: endingHeadline({ theme, outcome, options }),
+        detail: endingDetail({ outcome, harnesses, options }),
       }),
     );
   }
@@ -1431,7 +1460,7 @@ function expressiveReport({ result, plan, adapters, harnesses, customTools, cwd,
 
   out(lines.join("\n") + "\n");
 
-  const failures = [...result.errors, ...adapters.result.errors];
+  const { failures } = outcome;
   if (failures.length > 0) {
     // `bad`, not `warn`, and the distinction is the whole point of having both:
     // everything above is an outcome somebody may want to know about, and this
@@ -1481,29 +1510,21 @@ function pathList(paths) {
 }
 
 /** The per-harness summary counts, on the gutter, each at its own severity. */
-function expressiveAdapterLines({ adapters, harnesses, options, theme }) {
+function expressiveAdapterLines({ outcome, options, theme }) {
   const mark = theme.glyph;
-  if (harnesses.length === 0) return [];
 
-  if (adapters.blocked) {
+  // No "no harness chosen" guard: that case is no rows and `blocked: false`,
+  // so it falls through to an empty list. Blocked is checked first because it
+  // is also no rows, and the two must not print the same nothing.
+  if (outcome.blocked) {
     return [
       railed(theme, theme.bad(`${mark.bad} No adapters were generated`) + theme.dim(" (the kit copy did not finish)")),
     ];
   }
 
-  const failed = new Set(adapters.result.errors.map((error) => error.relativePath));
   const lines = [];
 
-  for (const harness of harnesses) {
-    const mine = adapters.plan.filter(
-      (item) => item.harness === harness && !failed.has(item.relativePath),
-    );
-    const count = (action) => mine.filter((item) => item.action === action).length;
-
-    const generated = count("write");
-    const replaced = count("replace");
-    const unchanged = count("up-to-date");
-
+  for (const { harness, generated, replaced, unchanged, conflicts, orphans } of outcome.harnessRows) {
     lines.push(
       railed(
         theme,
@@ -1526,9 +1547,6 @@ function expressiveAdapterLines({ adapters, harnesses, options, theme }) {
       );
     }
 
-    const conflicts = mine.filter((item) => item.action === "conflict");
-    const orphans = mine.filter((item) => item.action === "orphan");
-
     if (conflicts.length > 0) {
       lines.push(
         railed(
@@ -1554,20 +1572,12 @@ function expressiveAdapterLines({ adapters, harnesses, options, theme }) {
 }
 
 /** The conflict and orphan detail blocks, with their paths kept pasteable. */
-function expressiveAdapterBlocks({ adapters, harnesses, theme }) {
-  if (harnesses.length === 0 || adapters.blocked) return [];
+function expressiveAdapterBlocks({ outcome, theme }) {
+  if (outcome.blocked) return [];
 
-  const failed = new Set(adapters.result.errors.map((error) => error.relativePath));
   const blocks = [];
 
-  for (const harness of harnesses) {
-    const mine = adapters.plan.filter(
-      (item) => item.harness === harness && !failed.has(item.relativePath),
-    );
-
-    const conflicts = mine.filter((item) => item.action === "conflict");
-    const orphans = mine.filter((item) => item.action === "orphan");
-
+  for (const { harness, conflicts, orphans } of outcome.harnessRows) {
     if (conflicts.length > 0) {
       const one = conflicts.length === 1;
       blocks.push(
@@ -1575,7 +1585,7 @@ function expressiveAdapterBlocks({ adapters, harnesses, theme }) {
           theme,
           word: "Conflict",
           summary: `${conflicts.length} ${harness.label} file${plural(conflicts.length)} at ${one ? "a path an adapter wants" : "paths adapters want"}, which Pathfinder did not write`,
-          paths: conflicts.map((item) => item.relativePath),
+          paths: conflicts,
           advice: [
             `Re-run with --force to replace ${one ? "it" : "them"} ${theme.glyph.dash} note that --force also`,
             "overwrites Pathfinder kit files you have edited.",
@@ -1591,7 +1601,7 @@ function expressiveAdapterBlocks({ adapters, harnesses, theme }) {
           theme,
           word: "Orphan",
           summary: `${orphans.length} ${harness.label} adapter${plural(orphans.length)} delegat${one ? "es" : "e"} to a skill this version no longer ships`,
-          paths: orphans.map((item) => item.relativePath),
+          paths: orphans,
           advice: [
             `Left in place. Delete ${one ? "it" : "them"} yourself if you want ${one ? "it" : "them"} gone.`,
           ],

package/src/kit.mjs

@@ -68,7 +68,7 @@ export function isExcluded(basename) {
  *
  * `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`
+ * stopped shipping a blank `current-feature.md` stencil, because `/feature 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

package/src/outcome.mjs

@@ -0,0 +1,147 @@
+/**
+ * What a run did, derived once.
+ *
+ * Two renderings print this install — `contractReport` owes byte-for-byte what
+ * 1.4.1 printed, `expressiveReport` owes a person a legible hierarchy — and
+ * they had each grown their own copy of the same four derivations: the
+ * mode-dependent written count, the skipped filter, the failure merge, and a
+ * per-harness adapter tally that appeared three times character-for-character.
+ * Four facts, ten spellings, and no mechanism keeping them in agreement. This
+ * module is the one spelling. The renderings stay two renderings; they just
+ * stop each deciding what the numbers are.
+ *
+ * Pure by construction: no filesystem, no `process`, no writing. Everything
+ * here is a function of the plans and results it is handed, which is what lets
+ * a summary be tested without building a temporary repository or a fake
+ * terminal.
+ *
+ * Two counters elsewhere are deliberately *not* folded in, and a later change
+ * that "finishes the job" will break them:
+ *
+ * - `countWritten` in `cli.mjs` runs mid-run, before adapters are applied, and
+ *   reports a different number — `written + overwritten`, labelled "copied" —
+ *   than the summary's `written`. It cannot read a result that does not exist
+ *   yet.
+ * - The streaming per-harness counts in `generateAdapters` accumulate as units
+ *   resolve, so milestones can print while the work is happening, and they
+ *   count conflicts, orphans, and up-to-date adapters differently from the
+ *   rows below. A summary computed at the end cannot drive a progress bar.
+ */
+
+/**
+ * Every derived fact both renderings need, and nothing either of them can
+ * compute for itself.
+ *
+ * @param {object} args
+ * @param {{relativePath: string, status: "write"|"skip"|"overwrite"}[]} args.plan
+ *   the kit copy plan, in `planInstall`'s sort
+ * @param {{written: number, skipped: number, overwritten: number,
+ *          errors: {relativePath: string, message: string}[]}} args.result
+ * @param {{plan: object[], result: object, blocked: boolean}} args.adapters
+ * @param {{label: string}[]} args.harnesses the selected harnesses, registry order
+ * @param {{dryRun?: boolean}} args.options
+ * @returns {Readonly<object>} frozen; rows and lists frozen with it
+ */
+export function summarize({ plan, result, adapters, harnesses, options }) {
+  // A dry run has no `result.written` to report, because nothing was written.
+  // The plan is counted instead, which is the same number the run would have
+  // produced had it been allowed to write.
+  const written = options.dryRun
+    ? plan.filter((item) => item.status === "write").length
+    : result.written;
+
+  const skipped = plan
+    .filter((item) => item.status === "skip")
+    .map((item) => item.relativePath);
+
+  // Copy errors before adapter errors, because that is the order they happened
+  // in and the order the failure list has always printed.
+  const failures = Object.freeze([...result.errors, ...adapters.result.errors]);
+
+  return Object.freeze({
+    written,
+    overwritten: result.overwritten,
+    skipped: Object.freeze(skipped),
+    // Nothing to write and every file already there. Not the same as `written
+    // === 0`, which a partly failed copy also satisfies.
+    alreadyInstalled: written === 0 && skipped.length === plan.length,
+    failures,
+    blocked: adapters.blocked,
+    // Summed from the result, never from `harnessRows`. The rows exclude paths
+    // that errored and this does not, so the two disagree exactly when a write
+    // fails — and this is the number the closing headline speaks for.
+    built: adapters.result.generated + adapters.result.replaced,
+    attention: attentionCount(adapters),
+    harnessRows: harnessRows({ adapters, harnesses }),
+  });
+}
+
+/**
+ * What actually wants a human: a contested path, or an adapter pointing at a
+ * skill that is gone.
+ *
+ * Skipped files are deliberately not counted. A re-run over an existing install
+ * skips every file by design, and calling thirty-six routine skips "things to
+ * look at" would turn the one number that should mean something into noise
+ * nobody reads twice.
+ *
+ * Counted across the whole adapter plan rather than across `harnessRows`,
+ * errored paths included, because a path that could not be written is still a
+ * path somebody has to go and look at.
+ */
+function attentionCount(adapters) {
+  if (adapters.blocked) return 0;
+  return adapters.plan.filter(
+    (item) => item.action === "conflict" || item.action === "orphan",
+  ).length;
+}
+
+/**
+ * One row per selected harness, in the order the harnesses were given.
+ *
+ * The three-way distinction the report depends on is carried by the rows
+ * themselves, and all three collapse to a zero if it is lost:
+ *
+ * - no harness chosen — no rows, `blocked: false`
+ * - the kit copy failed — no rows, `blocked: true`
+ * - a harness that produced nothing — a row of zeroes
+ *
+ * The blocked case returns no rows explicitly rather than falling out of an
+ * empty plan, so that a harness which was chosen and never reached is never
+ * described as having generated zero adapters.
+ *
+ * Paths that failed to write are excluded from every count and list here: an
+ * adapter that could not be written was not generated, is not up to date, and
+ * is not a conflict the user can resolve by re-running with `--force`. They are
+ * reported once, as failures.
+ */
+function harnessRows({ adapters, harnesses }) {
+  if (harnesses.length === 0 || adapters.blocked) return Object.freeze([]);
+
+  const failed = new Set(adapters.result.errors.map((error) => error.relativePath));
+
+  return Object.freeze(
+    harnesses.map((harness) => {
+      // Identity, not label: the harness object on a plan item is the registry
+      // entry itself, and two entries could plausibly share a label one day.
+      const mine = adapters.plan.filter(
+        (item) => item.harness === harness && !failed.has(item.relativePath),
+      );
+      const count = (action) => mine.filter((item) => item.action === action).length;
+      const paths = (action) =>
+        Object.freeze(
+          mine.filter((item) => item.action === action).map((item) => item.relativePath),
+        );
+
+      return Object.freeze({
+        harness,
+        generated: count("write"),
+        replaced: count("replace"),
+        unchanged: count("up-to-date"),
+        // `planAdapters` order, which is the order they will be printed in.
+        conflicts: paths("conflict"),
+        orphans: paths("orphan"),
+      });
+    }),
+  );
+}

package/skills/complete-feature/SKILL.md

@@ -1,23 +0,0 @@
----
-name: complete-feature
-description: Complete accepted work through the project's delivery workflow and durable records.
----
-
-# Complete Feature
-
-Complete only work the human has accepted.
-
-1. Confirm the Feature is accepted.
-2. Run the project's required final checks.
-3. Follow the documented Git, merge, version, release, and deployment workflow.
-   Ask for approval where required.
-4. Mark the Feature complete.
-5. Add a compact entry to `context/history.md`.
-   Create it from `templates/history.template.md` if it does not exist.
-6. Clear or update `context/current-feature.md`. Do nothing if it does not exist.
-7. If work tracking is configured, sync the completed state.
-8. 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/load-feature/SKILL.md

@@ -1,28 +0,0 @@
----
-name: load-feature
-description: Load one approved Feature and the minimum context needed to work on it.
----
-
-# Load Feature
-
-1. Select the requested approved Feature. 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. 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
-7. 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.
-8. Present a short readiness summary.
-
-Do not implement the Feature.
-
-Do not scan unrelated repository areas, load history or roadmap by default,
-rewrite the Feature, or silently resolve `TBD` decisions.

package/skills/start-feature/SKILL.md

@@ -1,29 +0,0 @@
----
-name: start-feature
-description: Implement the active Feature in small, stable increments.
----
-
-# Start Feature
-
-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. Follow the Feature and existing project conventions.
-4. Make the smallest complete change.
-5. Verify the behavior you changed.
-6. Keep the repository stable.
-7. Create or update `context/current-feature.md` with the current state and next action.
-
-## 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.