godpowers 2.3.1 → 2.4.1

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.1] - 2026-06-08
+
+### Added
+- Added adoption-proof outcome metrics for Quick Proof and Adoption Canary
+  reports, covering commands to first signal, disk-state source, missing
+  artifacts, next command, host level, and host gaps.
+- Added the First 10 Minute Proof case study as a repo-verifiable public proof
+  artifact before the first external repository canary.
+
+### Changed
+- Updated README and Getting Started to lead with `--profile=core` and the
+  brief Quick Proof path before full autonomy.
+- Updated Quick Proof, Adoption Canary, Reference, Roadmap, and Proof
+  Transcript docs to separate observable adoption evidence from broader product
+  claims.
+- Added surface-discipline guidance so new public commands require adoption
+  evidence before expanding the command surface.
+
+### Fixed
+- Package guardrails now require the adoption metrics runtime helper so the
+  published package keeps Quick Proof and canary metrics available.
+
+## [2.4.0] - 2026-06-08
+
+### Added
+- Added command-family UX metadata for start, continue, build, verify,
+  operate, maintain, capture, recover, extend, collaborate, and configure
+  while keeping every shipped leaf command available.
+- Added capture, work-size, verification, status-view, and trigger-precedence
+  helpers in `lib/command-families.js`.
+- Added typed route outcome metadata for contextual, verdict-based,
+  steady-state, session-end, and selection-based route exits.
+- Added workflow helper groups with serialized plan expansion so closeout
+  helpers can be consolidated without hiding local runtime work.
+
+### Changed
+- Updated `/god`, `/god-help`, `/god-next`, `/god-status`, README,
+  reference docs, recipes, architecture docs, command-flow docs, and
+  auto-invoke visibility docs to present the consolidated UX paths.
+- Updated all shipped command routes with command family metadata.
+- Updated repeated workflow closeout helper lists to named helper groups while
+  preserving explicit expanded helpers in generated plans.
+- Updated extension recipe copy to describe current extension-pack-required
+  flows instead of old release annotations.
+
+### Fixed
+- Route-quality sync now requires typed outcomes for flexible route exits
+  instead of accepting unexplained placeholder next routes.
+- The full-arc e2e smoke test now verifies both helper groups and expanded
+  local helper visibility.
+
 ## [2.3.1] - 2026-06-08
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-2.3.1-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.4.1-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -13,20 +13,19 @@ tool** (Claude Code, Codex, Cursor, etc.) that orchestrate **specialist agents**
 in fresh contexts to do the work.
 
 Want the short proof first? Start with [Quick Proof](docs/quick-proof.md) to
-run `npx godpowers quick-proof --project=.`, see transcript excerpts, pick a
-starter command set, and understand runtime expectations before reading the
-full reference.
+run `npx godpowers quick-proof --project=. --brief`, see outcome metrics, pick
+a starter command set, and understand runtime expectations before reading the
+full reference. The [First 10 Minute Proof Case Study](docs/case-studies/first-10-minute-proof.md)
+shows the same evidence as a before-and-after adoption story.
 
 Godpowers makes AI coding accountable: every serious run should leave disk
 state, artifacts, validation gates, host guarantees, and a next action. Code is
 only one output. The project memory and proof trail matter too.
 
-Version 2.3.1 keeps the proof loop executable and adds release-surface
-hardening. Extension authors get `/god-extension-scaffold`, public starter
-paths are regression-tested against the actual router, host capability reports
-include optional code-intelligence tooling, clean user dashboards avoid
-maintainer-repo drift, and symlink handling is hardened across extension,
-planning-system, and cache paths.
+Version 2.4.1 keeps the 2.4 command-family UX and adds a clearer first trust
+step: Quick Proof outcome metrics, a First 10 Minute Proof case study,
+profile-first onboarding, and surface-discipline guidance for future command
+growth.
 
 Maintainer hardening continues on the 2.x line with small, audited public
 surface updates when they close real workflow gaps. The 2.1.0 patch closes a command-injection vector in the
@@ -49,6 +48,20 @@ next command, why it is recommended, whether the project is ready, the first
 blockers that need attention, and whether the current host can provide full,
 degraded, or unknown runtime guarantees.
 
+### Ten Minute Proof Path
+
+Run this before deciding whether Godpowers is worth a full project arc:
+
+```bash
+npx godpowers quick-proof --project=. --brief
+npx godpowers status --project=. --brief
+npx godpowers next --project=. --brief
+```
+
+The first command should produce disk-state evidence, missing-artifact
+visibility, a next command, host guarantees, and outcome metrics. The next two
+commands show what Godpowers can infer from your current project.
+
 It fuses four disciplines into one unified workflow:
 
 - **Native project context** - every Godpowers project is a Pillars project:
@@ -82,7 +95,7 @@ should prove:
 ## Install
 
 ```bash
-npx godpowers --claude --global
+npx godpowers --claude --global --profile=core
 ```
 
 Other targets: `--codex`, `--cursor`, `--windsurf`, `--opencode`, `--gemini`,
@@ -96,7 +109,8 @@ The installer copies:
 - Codex agent metadata to `<runtime>/agents/*.toml`
 - SessionStart hook (Claude Code only) to `<runtime>/hooks/`
 
-Installer profiles keep the visible command surface calm:
+Installer profiles keep the visible command surface calm. Start with `core` or
+`builder` unless you already know you need the full maintainer surface:
 
 ```bash
 npx godpowers --claude --global --profile=core
@@ -109,6 +123,16 @@ preserves the complete command surface, while the smaller profiles install the
 commands most relevant to the role. `--minimal` is an alias for
 `--profile=core`.
 
+Use profiles as journeys:
+
+| Journey | Profile |
+|---|---|
+| I want the basics | `core` |
+| I build products | `builder` |
+| I maintain Godpowers or mature repos | `maintainer` |
+| I coordinate suites | `suite` |
+| I want everything | `full` |
+
 Agent spawning is host-native. Claude uses its native agent/task interface,
 Codex uses installed `agents/*.toml` metadata backed by the same Markdown agent
 contracts, and the other runtimes use their supported agent or subagent
@@ -185,6 +209,10 @@ hook does the same thing when you open a new session in a Godpowers project.
 If the full command surface feels large, begin with one of these paths and only
 learn the next command when Godpowers recommends it.
 
+`/god-help` presents command families first: start, continue, build, verify,
+operate, maintain, capture, recover, extend, collaborate, and configure. Leaf
+commands remain direct shortcuts.
+
 | Goal | Starter path |
 |---|---|
 | Start a product | `/god-init`, `/god-prd`, `/god-design`, `/god-arch`, `/god-roadmap`, `/god-stack`, `/god-repo`, `/god-build` |
@@ -195,6 +223,21 @@ learn the next command when Godpowers recommends it.
 | Maintain project health | `/god-hygiene`, `/god-update-deps`, `/god-docs`, `/god-check-todos` |
 | Extend Godpowers | `/god-extension-scaffold --name=@godpowers/my-pack --output=.`, `/god-test-extension`, `/god-extension-add`, `/god-extension-list` |
 
+### Outcome Metrics
+
+Godpowers reports adoption and run signals separately from narrative claims:
+
+| Metric | Where it appears |
+|---|---|
+| Commands to first signal | `quick-proof` outcome metrics |
+| Next command and reason | `quick-proof`, `status`, `next`, `/god-next` |
+| Missing artifacts | dashboard planning visibility |
+| Host gaps | host guarantee line |
+| Run duration, pauses, retries, cost | `/god-metrics`, `/god-trace`, `/god-cost` |
+
+New public command surface should be added only when existing families,
+ladders, profiles, recipes, and docs cannot express a proven user need.
+
 The same status engine is available from the installer CLI for humans, CI,
 Codex, Claude, Cursor, Gemini, OpenCode, Windsurf, Antigravity, and any host
 runtime that can execute Node:
@@ -497,6 +540,7 @@ Pi. T3 Code inherits from the underlying agent (Codex / Claude / OpenCode).
 
 - [Getting Started](docs/getting-started.md)
 - [Quick Proof](docs/quick-proof.md)
+- [First 10 Minute Proof Case Study](docs/case-studies/first-10-minute-proof.md)
 - [Concepts](docs/concepts.md)
 - [Command reference (all 112 skills + 40 agents)](docs/reference.md)
 - [Feature awareness](docs/feature-awareness.md)

package/RELEASE.md

@@ -1,12 +1,11 @@
-# Godpowers 2.3.1 Release
+# Godpowers 2.4.1 Release
 
 > Status: Ready for package verification
 > Date: 2026-06-08
 
-Godpowers 2.3.1 is an accountability and release-surface hardening release for
-the 2.x line. It strengthens planning grounding, package legitimacy, install
-profiles, atomic persistence, executor recovery, extension authoring,
-front-door route coverage, host capability reporting, and dashboard behavior.
+Godpowers 2.4.1 is an adoption-proof patch for the 2.4 line. It keeps the
+2.4.0 command-family UX intact while making the first trust step smaller,
+measurable, and easier to inspect before a user commits to a full project arc.
 
 ## What's in this release
 
@@ -17,52 +16,38 @@ front-door route coverage, host capability reporting, and dashboard behavior.
 
 ## Highlights
 
-- `/god-extension-scaffold` gives extension authors a first-class
-  slash-command path before `/god-test-extension` and `/god-extension-add`.
-- Public `/god` intent matching now covers the starter phrases users are most
-  likely to type: start a product, add a feature, fix production, audit an
-  existing repo, ship a release, maintain health, and extend Godpowers.
-- Quick Proof and README starter paths are now regression-tested against the
-  actual router and recipe engine.
-- User project dashboards no longer show maintainer-repository documentation
-  drift when a clean non-Godpowers project is inspected.
-- Host capability reporting now includes optional code-intelligence tooling
-  without treating missing optional tools as a host degradation.
-- Extension install, planning-system detection, and agent-cache cleanup are
-  hardened around symlinked paths that point outside trusted source trees.
-- Source-grounded planning records existing files, existing symbols, planned new
-  artifacts, and unchecked references before build execution.
-- Package legitimacy checks give stack and dependency decisions a concrete npm
-  evidence gate before recommending package-backed choices.
-- Installer profiles let users install a smaller role-based command surface
-  with `--profile=<name>` or `--minimal`.
-- Atomic write helpers now protect core state and ledger writes from partial
-  file updates.
-- Executor repair classification names whether a failed attempt should retry,
-  decompose, prune, or escalate.
-- Public migration language now uses neutral legacy-planning terminology so
-  Godpowers is not confused with external workflow products.
-- Architecture docs now include an executable audit map for disconnected
-  commands, actions, workflows, recipes, and package surfaces.
+- Quick Proof now reports outcome metrics: commands to first signal,
+  disk-state source, tracked steps, missing planning artifacts, next command,
+  host level, and host gaps.
+- Adoption Canary reports now include CLI-verifiable outcome metrics for
+  quick-proof, status, and next signals.
+- README and Getting Started now lead with `--profile=core` and the brief Quick
+  Proof path before full autonomy.
+- The First 10 Minute Proof case study documents the local before-and-after
+  proof while clearly naming what still requires an external repository canary.
+- Reference and Roadmap docs now include surface-discipline guidance: try
+  families, ladders, profiles, recipes, typed route outcomes, and docs before
+  adding new public commands.
+- Package guardrails now require `lib/adoption-metrics.js`.
 
 ## Validation
 
 - `npm test` green across the full suite
-- `npm run lint` clean
-- `npm run release:check` green (tests, audit, package contents)
-- `npm pack` creates a local `godpowers-2.3.1.tgz` tarball for package
+- `npm run test:audit` green
+- `npm run pack:check` green
+- `npm pack` creates a local `godpowers-2.4.1.tgz` tarball for package
   inspection
 
 ## Upgrade
 
-- `npm install -g godpowers@2.3.1` or `npx godpowers@2.3.1`
+- `npm install -g godpowers@2.4.1` or `npx godpowers@2.4.1`
 - Re-run `/god-context` in each project to refresh installed runtime metadata
 - No breaking changes; existing `.godpowers/` state is compatible. Users who
   want a compact install can run `npx godpowers --profile=core`.
 
 ## Notes
 
-- GitHub release creation for `v2.3.1`
+- GitHub release creation for `v2.4.1`
 - The tag should match the npm package version
-- The `v2.3.1` tag should point to the release commit that matches the npm
-  `godpowers@2.3.1` package.
+- The `v2.4.1` tag should point to the release commit that matches the npm
+  `godpowers@2.4.1` package.

package/SKILL.md

@@ -198,7 +198,30 @@ When the command only recommends work, keep the same dashboard but set
 command pauses, set `State: blocked` or `State: paused` and make `Next` the
 one exact user decision needed to continue.
 
-### 11. User-Facing Vocabulary
+### 11. Command Family UX
+Godpowers has many leaf commands, but user-facing routing should start from
+families. Keep the full command surface available while presenting these
+families first:
+
+- Start: start or import a project.
+- Continue: understand state and choose the next move.
+- Build: plan, implement, test, and ship product work.
+- Verify: check artifacts, code, runtime behavior, and release readiness.
+- Operate: deploy, observe, harden, launch, and respond in production.
+- Maintain: keep artifacts, docs, dependencies, context, and repo surfaces current.
+- Capture: save thoughts, tasks, backlog items, seeds, and learnings.
+- Recover: undo, repair, restore, skip, or diagnose broken state.
+- Extend: install, inspect, test, remove, or author extension packs.
+- Collaborate: coordinate people, workstreams, suites, sprints, and pull requests.
+- Configure: tune settings, budgets, cache, profiles, help, and version info.
+
+When choosing between similar commands, use the ladders from
+`lib/command-families.js`: capture ladder, work size ladder, verification
+ladder, status views, and trigger precedence. `/god-help` should render
+families before leaf commands, and `/god` should use the family helpers before
+asking the user to choose from a long list.
+
+### 12. User-Facing Vocabulary
 Godpowers may use internal words such as "arc" in routing, recipes, and agent
 implementation notes. Do not require the user to decode that word in visible
 output.
@@ -218,7 +241,7 @@ and roadmap visibility when those files exist or are expected. Show whether
 the PRD is done, whether the roadmap exists, which milestone or tier is active,
 how close the tracked workflow is to completion, and the next concrete move.
 
-### 12. Auto-Invoke Visibility
+### 13. Auto-Invoke Visibility
 When Godpowers automatically runs another command, agent, or local runtime
 helper, show the user what happened. Do not describe these as "background"
 unless they are truly detached from the current run. Most Godpowers sync work
@@ -271,7 +294,7 @@ Automatic steps that especially need visible reporting:
 - dogfood runner execution during `/god-dogfood`, release checks, or explicit
   dogfood requests
 
-### 13. Proactive Auto-Invoke Policy
+### 14. Proactive Auto-Invoke Policy
 Godpowers should be proactive from disk evidence, not from guesswork. Before
 auto-invoking anything, classify the action by risk and apply the safest
 allowed behavior.

package/bin/install.js

@@ -18,6 +18,7 @@ const {
   countInstalledSurface
 } = require('../lib/installer-core');
 const { describeProfiles } = require('../lib/install-profiles');
+const commandFamilies = require('../lib/command-families');
 const identity = require('../lib/package-identity');
 
 const VERSION = identity.PACKAGE_VERSION;
@@ -55,6 +56,11 @@ function showHelp() {
   log('  dogfood              Run built-in messy-repo dogfood scenarios');
   log('  extension-scaffold   Create a publishable extension pack skeleton');
   log('');
+  log('Command families:');
+  for (const family of commandFamilies.COMMAND_FAMILIES) {
+    log(`  ${family.id.padEnd(12)} ${family.purpose}`);
+  }
+  log('');
   log('Options:');
   log('  --project=<path>     Project root for status, next, proof, or automation commands');
   log('  --json               Emit JSON for status, next, proof, or automation commands');

package/lib/README.md

@@ -17,7 +17,7 @@ package-level integrations.
 | `host-capabilities.js` | Detect host guarantees for shell, git, npm, agent spawning, optional code intelligence, extension authoring, and suite dry-runs. |
 | `repo-doc-sync.js` | Detect and refresh mechanical repository documentation surfaces. |
 | `repo-surface-sync.js` | Detect structural drift across commands, routes, packages, agents, workflows, recipes, extensions, and release policy. |
-| `route-quality-sync.js` | Detect symbolic route spawns, unresolved agent targets, and unapproved contextual route exits. |
+| `route-quality-sync.js` | Detect symbolic route spawns, unresolved agent targets, and untyped contextual route exits. |
 | `recipe-coverage-sync.js` | Detect missing high-frequency intent recipe coverage. |
 | `release-surface-sync.js` | Detect release-facing drift across badges, release notes, changelog, package checks, and release checklist policy. |
 | `dogfood-runner.js` | Run deterministic messy-repo scenarios against migration, host, extension, and suite release behavior. |
@@ -41,9 +41,11 @@ package-level integrations.
 | Module | Purpose |
 |--------|---------|
 | `router.js` | Resolve user intent to skills, agents, recipes, and workflows. |
+| `command-families.js` | Define UX command families, status views, decision ladders, and trigger precedence helpers. |
 | `recipes.js` | Load and validate routing recipes. |
 | `workflow-parser.js` | Parse workflow YAML into executable steps. |
 | `workflow-runner.js` | Execute workflow steps with validation hooks. |
+| `workflow-helper-groups.js` | Expand named workflow helper groups into explicit local helper names for plan visibility. |
 | `agent-cache.js` | Cache agent metadata for faster routing. |
 | `agent-validator.js` | Validate agent frontmatter and contracts. |
 | `agent-refs.js` | Validate workflow agent references and scan skill/agent prose for phantom references. |

package/lib/adoption-metrics.js

@@ -0,0 +1,87 @@
+/**
+ * Adoption proof metrics.
+ *
+ * These metrics keep first-user trust claims tied to observable CLI signals
+ * instead of narrative confidence.
+ */
+
+function countMissingPlanning(planning = {}) {
+  return Object.values(planning)
+    .filter(item => item && item.status === 'missing')
+    .length;
+}
+
+function fromQuickProof(proof) {
+  const dashboard = proof.dashboard || {};
+  const progress = dashboard.progress || {};
+  const planning = dashboard.planning || {};
+  const next = dashboard.next || {};
+  const host = proof.host || {};
+  const hostGaps = Array.isArray(host.gaps) ? host.gaps : [];
+  const completed = Number.isFinite(progress.completed) ? progress.completed : 0;
+  const total = Number.isFinite(progress.total) ? progress.total : 0;
+
+  return {
+    commandsToFirstSignal: 1,
+    stateSource: proof.statePath || 'unknown',
+    trackedStepsComplete: completed,
+    trackedStepsTotal: total,
+    missingPlanningArtifacts: countMissingPlanning(planning),
+    nextCommand: next.command || 'describe the next intent',
+    nextReason: next.reason || 'No route was computed.',
+    hostLevel: host.level || 'unknown',
+    hostGapCount: hostGaps.length,
+    proofSignals: [
+      'disk state',
+      'missing artifact',
+      'next command',
+      'host guarantee'
+    ]
+  };
+}
+
+function render(metrics) {
+  return [
+    `  Commands to first signal: ${metrics.commandsToFirstSignal}`,
+    `  State source: ${metrics.stateSource}`,
+    `  Tracked steps: ${metrics.trackedStepsComplete} of ${metrics.trackedStepsTotal}`,
+    `  Missing planning artifacts: ${metrics.missingPlanningArtifacts}`,
+    `  Next command: ${metrics.nextCommand}`,
+    `  Host level: ${metrics.hostLevel}`,
+    `  Host gaps: ${metrics.hostGapCount}`
+  ].join('\n');
+}
+
+function canaryMetrics(outputs = {}) {
+  const quickProof = outputs.quickProof || '';
+  const status = outputs.status || '';
+  const next = outputs.next || '';
+  return {
+    cliSignalsCaptured: ['quick-proof', 'status', 'next']
+      .filter((name) => outputs[camelSignal(name)] && outputs[camelSignal(name)].trim()).length,
+    quickProofHasNext: /\bNext:\s+\S+/.test(quickProof),
+    statusHasDashboard: /Godpowers Dashboard|Current status:/.test(status),
+    nextHasRecommendation: /Suggested next command:|Recommended:|Next:/.test(next)
+  };
+}
+
+function camelSignal(name) {
+  if (name === 'quick-proof') return 'quickProof';
+  return name;
+}
+
+function renderCanary(metrics) {
+  return [
+    `- [DECISION] CLI signals captured: ${metrics.cliSignalsCaptured} of 3.`,
+    `- [DECISION] Quick Proof reported a next action: ${metrics.quickProofHasNext ? 'yes' : 'no'}.`,
+    `- [DECISION] Status rendered a dashboard signal: ${metrics.statusHasDashboard ? 'yes' : 'no'}.`,
+    `- [DECISION] Next rendered a recommendation signal: ${metrics.nextHasRecommendation ? 'yes' : 'no'}.`
+  ].join('\n');
+}
+
+module.exports = {
+  fromQuickProof,
+  render,
+  canaryMetrics,
+  renderCanary
+};