godpowers 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -7,6 +7,28 @@ 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

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.4.0-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,18 +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.4.0 keeps every leaf command available while making the command
-surface easier to navigate. `/god`, `/god-help`, `/god-next`, and route
-metadata now share command families, decision ladders, typed route outcomes,
-and workflow helper groups so users see clearer paths without losing power.
+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
@@ -47,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:
@@ -80,7 +95,7 @@ should prove:
 ## Install
 
 ```bash
-npx godpowers --claude --global
+npx godpowers --claude --global --profile=core
 ```
 
 Other targets: `--codex`, `--cursor`, `--windsurf`, `--opencode`, `--gemini`,
@@ -94,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
@@ -207,6 +223,21 @@ commands remain direct shortcuts.
 | 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:
@@ -509,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.4.0 Release
+# Godpowers 2.4.1 Release
 
 > Status: Ready for package verification
 > Date: 2026-06-08
 
-Godpowers 2.4.0 is a UX flow consolidation release for the 2.x line. It keeps
-the complete 112-command surface intact while making the primary paths easier
-to understand through command families, decision ladders, typed route outcomes,
-and auditable workflow helper groups.
+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,43 +16,38 @@ and auditable workflow helper groups.
 
 ## Highlights
 
-- `/god-help` now presents command families first, then ladders and the full
-  catalog.
-- `/god` and `/god-next` now share command-family helpers for capture, work
-  sizing, verification, and overlapping trigger phrases.
-- `/god-status` is documented as the continue-family hub, with `/god-progress`,
-  `/god-lifecycle`, `/god-locate`, and `/god-next` as direct views.
-- Every shipped route now carries command family metadata.
-- Flexible route exits now carry typed `success-path.outcome` metadata so
-  contextual, verdict-based, steady-state, session-end, and selection outcomes
-  can be explained to users.
-- Workflow YAML can now use named helper groups, while generated plans still
-  expand the exact local helper list for visibility.
-- Recipes now split simple existing-repo onboarding from deeper inheritance
-  flows, and clarify workstream versus suite collaboration paths.
-- Extension journey docs now describe current extension-pack-required flows
-  instead of old release annotations.
-- Release guardrails now require the command-family runtime files, helper group
-  runtime files, and command-family regression test.
+- 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 test:audit` green
 - `npm run pack:check` green
-- `npm pack` creates a local `godpowers-2.4.0.tgz` tarball for package
+- `npm pack` creates a local `godpowers-2.4.1.tgz` tarball for package
   inspection
 
 ## Upgrade
 
-- `npm install -g godpowers@2.4.0` or `npx godpowers@2.4.0`
+- `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.4.0`
+- GitHub release creation for `v2.4.1`
 - The tag should match the npm package version
-- The `v2.4.0` tag should point to the release commit that matches the npm
-  `godpowers@2.4.0` package.
+- The `v2.4.1` tag should point to the release commit that matches the npm
+  `godpowers@2.4.1` package.

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
+};

package/lib/quick-proof.js

@@ -10,6 +10,7 @@ const path = require('path');
 
 const dashboard = require('./dashboard');
 const hostCapabilities = require('./host-capabilities');
+const adoptionMetrics = require('./adoption-metrics');
 
 const FIXTURE_ROOT = path.join(__dirname, '..', 'fixtures', 'quick-proof', 'project');
 const MANIFEST_PATH = path.join(__dirname, '..', 'fixtures', 'quick-proof', 'manifest.json');
@@ -85,6 +86,8 @@ function compute(projectRoot = process.cwd(), opts = {}) {
     ]
   };
 
+  proof.metrics = adoptionMetrics.fromQuickProof(proof);
+
   return proof;
 }
 
@@ -111,7 +114,10 @@ function render(proof, opts = {}) {
       `  State on disk: ${proof.statePath}`,
       `  Fixture: ${proof.fixturePath}`,
       `  PRD: ${planning.prd ? planning.prd.status : 'unknown'}`,
-      `  Roadmap: ${planning.roadmap ? planning.roadmap.status : 'unknown'}`
+      `  Roadmap: ${planning.roadmap ? planning.roadmap.status : 'unknown'}`,
+      '',
+      'Outcome metrics:',
+      adoptionMetrics.render(proof.metrics)
     ].join('\n');
   }
 
@@ -138,6 +144,9 @@ function render(proof, opts = {}) {
     'Evidence:',
     ...proof.evidence.map((item, index) => `  ${index + 1}. ${item.label}: ${item.value}`),
     '',
+    'Outcome metrics:',
+    adoptionMetrics.render(proof.metrics),
+    '',
     'Try it on the fixture:',
     `  npx godpowers status --project=${proof.fixtureRoot} --brief`,
     `  npx godpowers next --project=${proof.fixtureRoot} --brief`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "AI-powered development system: 112 slash commands and 40 specialist agents that take a project from raw idea to hardened production. Runs inside Claude Code, Codex, Cursor, Windsurf, Gemini, and 10+ other AI coding tools.",
   "bin": {
     "godpowers": "./bin/install.js"