godpowers 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.2] - 2026-06-09
+
+### Added
+- Added strict YAML diagnostics for the dependency-free parser, covering
+  skipped malformed lines, unsafe prototype-pollution keys, and legacy empty
+  array shorthand.
+- Added shared markdown frontmatter parsing through `lib/frontmatter.js` and a
+  static check that blocks new inline parser drift.
+- Added dev-only coverage tooling through `c8` and `npm run coverage`.
+
+### Changed
+- Routing, recipe, and workflow loaders now surface strict YAML warnings with
+  file and line context.
+- Installer metadata, Pillars, skill validation, agent validation, checkpoint
+  reads, context budgets, skill surface metadata, and DESIGN.md parsing now use
+  the shared frontmatter helper.
+
+### Fixed
+- Extension manifests now fail closed on malformed YAML lines and unsafe keys
+  instead of accepting partially parsed manifests.
+- Removed stale root tarballs and `.DS_Store` package clutter before release.
+
+## [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.2-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.2 keeps the 2.4 command-family UX and hardens the release-facing
+runtime: strict YAML diagnostics for routing, recipes, workflows, and extension
+manifests; shared markdown frontmatter parsing; dev-only coverage tooling; and
+clean package hygiene before publish.
 
 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,12 @@
-# Godpowers 2.4.0 Release
+# Godpowers 2.4.2 Release
 
 > Status: Ready for package verification
-> Date: 2026-06-08
+> Date: 2026-06-09
 
-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.2 is a release-hardening patch for the 2.4 line. It keeps the
+2.4 command-family UX intact while making parser failures, frontmatter
+metadata, coverage visibility, and package hygiene more accountable before
+publish.
 
 ## What's in this release
 
@@ -17,43 +17,42 @@ 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.
+- YAML parsing now exposes strict diagnostics for malformed skipped lines and
+  unsafe prototype-pollution keys while preserving default legacy reads.
+- Routing, recipe, and workflow YAML loaders now surface warnings with file and
+  line context.
+- Extension manifests now fail closed on malformed YAML lines and unsafe keys.
+- Markdown frontmatter parsing is centralized in `lib/frontmatter.js` and
+  enforced by `scripts/static-check.js`.
+- Installer metadata, Pillars, skill validation, agent validation,
+  checkpoints, context budgets, skill surface metadata, and DESIGN.md parsing
+  now share the same frontmatter path.
+- `npm run coverage` is available through dev-only `c8` tooling.
+- Stale root package tarballs and `.DS_Store` clutter were removed before
+  release.
 
 ## 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
+- `node scripts/test-yaml-parser.js` green
+- `node scripts/test-frontmatter.js` green
+- `node scripts/test-extensions.js` green
+- `node scripts/test-router.js` green
+- `node scripts/test-recipes.js` green
+- `node scripts/test-install-smoke.js` green
+- `npm run release:check` required before publish
+- `npm pack` creates a local `godpowers-2.4.2.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.2` or `npx godpowers@2.4.2`
 - 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`.
+- No breaking changes for valid `.godpowers/` state. Invalid extension
+  manifests that were previously partially accepted now fail with parse errors.
 
 ## Notes
 
-- GitHub release creation for `v2.4.0`
+- GitHub release creation for `v2.4.2`
 - 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.2` tag should point to the release commit that matches the npm
+  `godpowers@2.4.2` package.

package/lib/README.md

@@ -11,6 +11,7 @@ package-level integrations.
 | `state.js` | Read, initialize, validate, and write `.godpowers/state.json`. |
 | `state-lock.js` | Coordinate state writes with a lock file. |
 | `intent.js` | Read and validate `intent.yaml` from project roots or `.godpowers/`. |
+| `frontmatter.js` | Parse shared markdown YAML frontmatter for skills, agents, Pillars, checkpoints, and design specs. |
 | `checkpoint.js` | Create and inspect resumable checkpoint artifacts. |
 | `feature-awareness.js` | Detect and refresh existing-project awareness after runtime upgrades. |
 | `code-intelligence.js` | Detect optional `ast-grep`, `sg`, and LSP tooling for structural search, rewrite, and diagnostics guidance. |

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/agent-validator.js

@@ -18,6 +18,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const frontmatter = require('./frontmatter');
 
 const REQUIRED_FRONTMATTER = ['name', 'description'];
 const RECOMMENDED_FRONTMATTER = ['tools'];
@@ -37,33 +38,7 @@ function parseAgentFile(filePath) {
     raw
   };
 
-  // Frontmatter block: --- ... ---
-  if (raw.startsWith('---')) {
-    const end = raw.indexOf('\n---', 3);
-    if (end > 0) {
-      const fmBlock = raw.slice(3, end).trim();
-      // Parse simple YAML (key: value, key: |, etc.)
-      let currentMultiline = null;
-      for (const line of fmBlock.split('\n')) {
-        if (currentMultiline) {
-          if (line.startsWith(' ') || line.startsWith('\t')) {
-            result.frontmatter[currentMultiline] += '\n' + line.trim();
-            continue;
-          }
-          currentMultiline = null;
-        }
-        const m = line.match(/^([\w-]+):\s*(.*)$/);
-        if (m) {
-          if (m[2] === '|' || m[2] === '>') {
-            currentMultiline = m[1];
-            result.frontmatter[m[1]] = '';
-          } else {
-            result.frontmatter[m[1]] = m[2].trim();
-          }
-        }
-      }
-    }
-  }
+  result.frontmatter = frontmatter.parse(raw, { strict: true, source: filePath });
 
   // Sections: lines starting with # / ## / ###
   const lines = raw.split('\n');

package/lib/checkpoint.js

@@ -50,6 +50,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const atomic = require('./atomic-write');
+const frontmatterLib = require('./frontmatter');
 
 const MAX_ACTIONS = 20;
 const MAX_FACTS = 10;
@@ -74,25 +75,9 @@ function read(projectRoot) {
   if (!fs.existsSync(file)) return null;
   const raw = fs.readFileSync(file, 'utf8');
 
-  // Frontmatter parse
-  let frontmatter = {};
-  let body = raw;
-  if (raw.startsWith('---')) {
-    const end = raw.indexOf('\n---', 3);
-    if (end > 0) {
-      const fmText = raw.slice(3, end).trim();
-      body = raw.slice(end + 4).trim();
-      for (const line of fmText.split('\n')) {
-        const m = line.match(/^([\w-]+):\s*(.*)$/);
-        if (m) {
-          let v = m[2].trim();
-          if (v === 'true') v = true;
-          else if (v === 'false') v = false;
-          frontmatter[m[1]] = v;
-        }
-      }
-    }
-  }
+  const parsed = frontmatterLib.split(raw, { strict: true, source: file });
+  const frontmatter = parsed.frontmatter || {};
+  const body = parsed.body.trim();
 
   // Section parse for actions and facts
   const actions = parseList(body, 'Last actions');

package/lib/context-budget.js

@@ -25,6 +25,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const frontmatter = require('./frontmatter');
 
 const BYTES_PER_TOKEN = 4;            // rough English text heuristic
 const DEFAULT_MAX_TOKENS = 80_000;    // per-agent default; ~half of a 200K window
@@ -52,44 +53,14 @@ function parseAgentBudget(agentPath) {
     return { required: [], optional: [], maxTokens: null };
   }
   const raw = fs.readFileSync(agentPath, 'utf8');
-  let fmText = '';
-  if (raw.startsWith('---')) {
-    const end = raw.indexOf('\n---', 3);
-    if (end > 0) fmText = raw.slice(3, end);
-  }
-
+  const metadata = frontmatter.parse(raw, { strict: true, source: agentPath });
   const out = { required: [], optional: [], maxTokens: null };
-  // very loose YAML-ish parse, just for our subset
-  const lines = fmText.split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
-    if (line.startsWith('required-context:')) {
-      out.required = parseListInline(line.slice('required-context:'.length), lines, i);
-    } else if (line.startsWith('optional-context:')) {
-      out.optional = parseListInline(line.slice('optional-context:'.length), lines, i);
-    } else if (line.startsWith('max-tokens:')) {
-      const n = parseInt(line.slice('max-tokens:'.length).trim(), 10);
-      if (Number.isFinite(n)) out.maxTokens = n;
-    }
-  }
+  if (Array.isArray(metadata['required-context'])) out.required = metadata['required-context'];
+  if (Array.isArray(metadata['optional-context'])) out.optional = metadata['optional-context'];
+  if (Number.isFinite(metadata['max-tokens'])) out.maxTokens = metadata['max-tokens'];
   return out;
 }
 
-function parseListInline(rest, lines, idx) {
-  const r = rest.trim();
-  if (r.startsWith('[') && r.endsWith(']')) {
-    return r.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
-  }
-  // Block list: subsequent lines starting with '- '
-  const items = [];
-  for (let j = idx + 1; j < lines.length; j++) {
-    const l = lines[j];
-    if (!l.startsWith('  - ')) break;
-    items.push(l.slice(4).trim().replace(/^["']|["']$/g, ''));
-  }
-  return items;
-}
-
 /**
  * Compute total bytes + estimated tokens for a list of file paths.
  * Missing files contribute 0; not an error.

package/lib/design-spec.js

@@ -15,7 +15,7 @@
  *   lint(content) -> { findings, valid }   // run all checks
  */
 
-const intent = require('./intent');
+const frontmatter = require('./frontmatter');
 
 const VALID_SECTIONS = [
   'Overview', 'Brand & Style',
@@ -48,23 +48,21 @@ const COMPONENT_PROPS = [
  * Parse a DESIGN.md file: separate YAML frontmatter from markdown body.
  */
 function parse(content) {
-  const errors = [];
   if (!content.startsWith('---')) {
     return { frontmatter: null, body: content, errors: ['Missing YAML frontmatter (file must start with `---`).'] };
   }
-  const end = content.indexOf('\n---', 3);
-  if (end === -1) {
+  const parsed = frontmatter.split(content, { strict: true, source: 'DESIGN.md' });
+  if (!parsed.frontmatter) {
     return { frontmatter: null, body: content, errors: ['Frontmatter not closed (missing closing `---`).'] };
   }
-  const yamlBlock = content.slice(3, end).trim();
-  const body = content.slice(end + 4).trim();
-  let frontmatter = null;
-  try {
-    frontmatter = intent.parseSimpleYaml(yamlBlock);
-  } catch (e) {
-    errors.push(`Frontmatter YAML parse error: ${e.message}`);
-  }
-  return { frontmatter, body, errors };
+  const errors = parsed.diagnostics.map((diagnostic) =>
+    `Frontmatter YAML warning: ${diagnostic.message} on line ${diagnostic.line}`
+  );
+  return {
+    frontmatter: errors.length > 0 ? null : parsed.frontmatter,
+    body: parsed.body.trim(),
+    errors
+  };
 }
 
 /**

package/lib/extensions.js

@@ -41,8 +41,18 @@ function parseManifest(yamlText) {
     return { manifest: null, errors: ['empty manifest'] };
   }
   try {
-    const manifest = intentLib.parseSimpleYaml(yamlText);
-    return { manifest, errors: [] };
+    const parsed = intentLib.parseSimpleYamlWithDiagnostics(yamlText, {
+      strict: true,
+      source: 'manifest.yaml',
+      unsafeKeySeverity: 'error'
+    });
+    if (parsed.diagnostics.length > 0) {
+      return {
+        manifest: null,
+        errors: parsed.diagnostics.map(intentLib.formatDiagnostic)
+      };
+    }
+    return { manifest: parsed.data, errors: [] };
   } catch (e) {
     return { manifest: null, errors: ['parse error: ' + e.message] };
   }

package/lib/frontmatter.js

@@ -0,0 +1,74 @@
+/**
+ * Shared YAML frontmatter helpers for markdown-backed Godpowers contracts.
+ *
+ * Frontmatter uses the same dependency-free YAML subset as intent, routing,
+ * recipes, workflows, and extension manifests.
+ */
+
+const { parseSimpleYamlWithDiagnostics } = require('./intent');
+
+function hasOpeningFence(text) {
+  return typeof text === 'string' && text.startsWith('---');
+}
+
+function split(text, opts = {}) {
+  const source = opts.source || null;
+  if (!hasOpeningFence(text)) {
+    return {
+      frontmatter: null,
+      body: text,
+      rawFrontmatter: '',
+      diagnostics: opts.require ? [{
+        severity: 'warning',
+        line: 1,
+        source,
+        message: 'Missing YAML frontmatter fence'
+      }] : []
+    };
+  }
+
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) {
+    return {
+      frontmatter: null,
+      body: text,
+      rawFrontmatter: '',
+      diagnostics: [{
+        severity: 'warning',
+        line: 1,
+        source,
+        message: 'YAML frontmatter fence is not closed'
+      }]
+    };
+  }
+
+  const rawFrontmatter = text.slice(3, end).trim();
+  const parsed = parseSimpleYamlWithDiagnostics(rawFrontmatter, {
+    strict: opts.strict === true,
+    source,
+    unsafeKeySeverity: opts.unsafeKeySeverity || 'warning',
+    onDiagnostic: opts.onDiagnostic
+  });
+
+  return {
+    frontmatter: parsed.data,
+    body: text.slice(end + 4).trimStart(),
+    rawFrontmatter,
+    diagnostics: parsed.diagnostics
+  };
+}
+
+function parse(text, opts = {}) {
+  const result = split(text, opts);
+  return result.frontmatter || {};
+}
+
+function strip(text) {
+  return split(text).body.trim();
+}
+
+module.exports = {
+  split,
+  parse,
+  strip
+};

package/lib/installer-core.js

@@ -5,6 +5,7 @@ const { ensureDir, copyRecursive, copyRuntimeBundle } = require('./installer-fil
 const { resolveRuntime } = require('./installer-runtimes');
 const { selectedSkillNames, normalizeProfiles } = require('./install-profiles');
 const identity = require('./package-identity');
+const frontmatter = require('./frontmatter');
 
 const VERSION = identity.PACKAGE_VERSION;
 
@@ -46,52 +47,6 @@ function installSkillFile(srcFile, skillsDest, runtimeKey, targetName = null) {
   fs.copyFileSync(srcFile, path.join(skillsDest, `${baseName}.md`));
 }
 
-function parseAgentFrontmatter(content) {
-  const fallback = { name: null, description: null };
-  if (!content.startsWith('---\n')) return fallback;
-
-  const end = content.indexOf('\n---', 4);
-  if (end === -1) return fallback;
-
-  const lines = content.slice(4, end).split('\n');
-  const parsed = { ...fallback };
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const nameMatch = line.match(/^name:\s*(.+)\s*$/);
-    if (nameMatch) {
-      parsed.name = nameMatch[1].replace(/^["']|["']$/g, '');
-      continue;
-    }
-
-    if (line === 'description: |') {
-      const desc = [];
-      i++;
-      while (i < lines.length && /^ {2}/.test(lines[i])) {
-        desc.push(lines[i].slice(2));
-        i++;
-      }
-      i--;
-      parsed.description = desc.join('\n').trim();
-      continue;
-    }
-
-    const descMatch = line.match(/^description:\s*(.+)\s*$/);
-    if (descMatch) {
-      parsed.description = descMatch[1].replace(/^["']|["']$/g, '');
-    }
-  }
-
-  return parsed;
-}
-
-function stripFrontmatter(content) {
-  if (!content.startsWith('---\n')) return content.trim();
-  const end = content.indexOf('\n---', 4);
-  if (end === -1) return content.trim();
-  return content.slice(end + 4).trim();
-}
-
 function tomlString(value) {
   return JSON.stringify(value || '');
 }
@@ -102,10 +57,10 @@ function tomlLiteral(value) {
 
 function writeCodexAgentToml(srcFile, agentsDest) {
   const content = fs.readFileSync(srcFile, 'utf8');
-  const frontmatter = parseAgentFrontmatter(content);
-  const name = frontmatter.name || path.basename(srcFile, '.md');
-  const description = frontmatter.description || `Godpowers specialist agent: ${name}.`;
-  const instructions = stripFrontmatter(content);
+  const metadata = frontmatter.parse(content, { strict: true, source: srcFile });
+  const name = metadata.name || path.basename(srcFile, '.md');
+  const description = metadata.description || `Godpowers specialist agent: ${name}.`;
+  const instructions = frontmatter.strip(content);
   const toml = [
     `name = ${tomlString(name)}`,
     `description = ${tomlString(description)}`,
@@ -371,8 +326,8 @@ module.exports = {
   uninstallForRuntime,
   countInstalledSurface: countProfileSurface,
   installSkillFile,
-  parseAgentFrontmatter,
-  stripFrontmatter,
+  parseAgentFrontmatter: frontmatter.parse,
+  stripFrontmatter: frontmatter.strip,
   writeCodexAgentToml,
   removeSkillEntry,
   pruneGodpowersSkills,

package/lib/intent.js

@@ -5,6 +5,7 @@
  *
  * Note: this is a minimal YAML reader, intentionally avoiding a YAML
  * dependency. Handles the subset of YAML our intent files use.
+ * Strict callers can collect diagnostics for skipped lines and unsafe keys.
  * For complex YAML, agents read the file directly.
  */
 
@@ -66,15 +67,59 @@ function isUnsafeKey(key) {
  * Parse a simple YAML subset. Just enough for intent.yaml structure.
  * Real-world: replace with `yaml` npm package when we add deps.
  */
-function parseSimpleYaml(content) {
+function createDiagnostic(severity, line, message, source) {
+  return {
+    severity,
+    line,
+    source: source || null,
+    message
+  };
+}
+
+function formatDiagnostic(diagnostic) {
+  const source = diagnostic.source ? `${diagnostic.source}:` : '';
+  return `${source}${diagnostic.line}: ${diagnostic.message}`;
+}
+
+function diagnosticsError(diagnostics, label = 'YAML diagnostics') {
+  const error = new Error(`${label}:\n  - ${diagnostics.map(formatDiagnostic).join('\n  - ')}`);
+  error.diagnostics = diagnostics;
+  return error;
+}
+
+function parseSimpleYaml(content, opts = {}) {
+  const result = parseSimpleYamlWithDiagnostics(content, opts);
+  if (opts.throwOnDiagnostics && result.diagnostics.length > 0) {
+    throw diagnosticsError(result.diagnostics, opts.errorLabel);
+  }
+  return result.data;
+}
+
+function parseSimpleYamlWithDiagnostics(content, opts = {}) {
   const lines = content.split('\n');
   const result = {};
   const stack = [{ obj: result, indent: -1, key: null, isArray: false, parent: null }];
+  const diagnostics = [];
+  const strict = opts.strict === true;
+  const source = opts.source || null;
+  const unsafeKeySeverity = opts.unsafeKeySeverity || 'warning';
+
+  function record(severity, lineNumber, message) {
+    const diagnostic = createDiagnostic(severity, lineNumber, message, source);
+    diagnostics.push(diagnostic);
+    if (typeof opts.onDiagnostic === 'function') opts.onDiagnostic(diagnostic);
+  }
+
+  function recordSkipped(lineNumber, rawLine, reason) {
+    if (!strict) return;
+    record('warning', lineNumber, `${reason}: ${rawLine.trim()}`);
+  }
 
   for (let i = 0; i < lines.length; i++) {
     let line = lines[i];
     if (!line.trim() || line.trim().startsWith('#')) continue;
     line = stripInlineComment(line);
+    if (!line.trim()) continue;
 
     const indent = line.length - line.trimStart().length;
     const trimmed = line.trim();
@@ -84,6 +129,16 @@ function parseSimpleYaml(content) {
       stack.pop();
     }
     const parent = stack[stack.length - 1].obj;
+
+    if (trimmed === '[]') {
+      const current = stack[stack.length - 1];
+      if (current.parent && current.key && Object.keys(current.obj).length === 0) {
+        current.parent[current.key] = [];
+        stack.pop();
+        continue;
+      }
+    }
+
     // List item: "- key: value" or "- value"
     if (trimmed.startsWith('- ')) {
       const rest = trimmed.slice(2);
@@ -102,7 +157,14 @@ function parseSimpleYaml(content) {
       } else {
         // List of objects: "- key: value"
         const itemKey = rest.slice(0, restColonIdx).trim();
-        if (isUnsafeKey(itemKey)) continue;
+        if (!itemKey) {
+          recordSkipped(i + 1, lines[i], 'Missing list item key');
+          continue;
+        }
+        if (isUnsafeKey(itemKey)) {
+          record(unsafeKeySeverity, i + 1, `Unsafe YAML key rejected: ${itemKey}`);
+          continue;
+        }
         const itemVal = rest.slice(restColonIdx + 1).trim();
         const newObj = {};
         if (itemVal) {
@@ -122,9 +184,19 @@ function parseSimpleYaml(content) {
     }
 
     const colonIdx = findUnquotedColon(trimmed);
-    if (colonIdx === -1) continue;
+    if (colonIdx === -1) {
+      recordSkipped(i + 1, lines[i], 'Unparseable YAML line skipped');
+      continue;
+    }
     const key = trimmed.slice(0, colonIdx).trim();
-    if (isUnsafeKey(key)) continue;
+    if (!key) {
+      recordSkipped(i + 1, lines[i], 'Missing YAML key');
+      continue;
+    }
+    if (isUnsafeKey(key)) {
+      record(unsafeKeySeverity, i + 1, `Unsafe YAML key rejected: ${key}`);
+      continue;
+    }
     const valueStr = trimmed.slice(colonIdx + 1).trim();
 
     if (!valueStr) {
@@ -140,7 +212,7 @@ function parseSimpleYaml(content) {
     }
   }
 
-  return cleanArrays(result);
+  return { data: cleanArrays(result), diagnostics };
 }
 
 function readBlockScalar(lines, startIndex, parentIndent, folded) {
@@ -301,4 +373,14 @@ function validate(intent) {
   return errors;
 }
 
-module.exports = { read, readAsync, get, validate, intentPath, parseSimpleYaml };
+module.exports = {
+  read,
+  readAsync,
+  get,
+  validate,
+  intentPath,
+  parseSimpleYaml,
+  parseSimpleYamlWithDiagnostics,
+  diagnosticsError,
+  formatDiagnostic
+};

package/lib/pillars.js

@@ -8,6 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const frontmatterLib = require('./frontmatter');
 
 const PILLARS_FENCE_BEGIN = '<!-- pillars:begin -->';
 const PILLARS_FENCE_END = '<!-- pillars:end -->';
@@ -119,47 +120,7 @@ function stripQuotes(value) {
   return String(value).trim().replace(/^['"]|['"]$/g, '');
 }
 
-function parseInlineList(value) {
-  const trimmed = value.trim();
-  if (trimmed === '[]') return [];
-  if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return null;
-  const body = trimmed.slice(1, -1).trim();
-  if (!body) return [];
-  return body.split(',').map(part => stripQuotes(part)).filter(Boolean);
-}
-
-function parseScalar(value) {
-  const trimmed = value.trim();
-  if (trimmed === 'true') return true;
-  if (trimmed === 'false') return false;
-  const list = parseInlineList(trimmed);
-  if (list) return list;
-  return stripQuotes(trimmed);
-}
-
-function parseFrontmatter(raw) {
-  if (!raw.startsWith('---\n')) return null;
-  const end = raw.indexOf('\n---', 4);
-  if (end === -1) return null;
-
-  const frontmatter = {};
-  const lines = raw.slice(4, end).split('\n');
-  let currentKey = null;
-  for (const line of lines) {
-    const match = line.match(/^([\w-]+):\s*(.*)$/);
-    if (match) {
-      currentKey = match[1];
-      frontmatter[currentKey] = parseScalar(match[2]);
-      continue;
-    }
-    const itemMatch = line.match(/^\s*-\s*(.+)$/);
-    if (currentKey && itemMatch) {
-      if (!Array.isArray(frontmatter[currentKey])) frontmatter[currentKey] = [];
-      frontmatter[currentKey].push(stripQuotes(itemMatch[1]));
-    }
-  }
-  return frontmatter;
-}
+const parseFrontmatter = (raw) => frontmatterLib.parse(raw, { strict: true });
 
 function walkMarkdown(dir) {
   if (!fs.existsSync(dir)) return [];

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/lib/recipes.js

@@ -8,13 +8,17 @@
 
 const fs = require('fs');
 const path = require('path');
-const { parseSimpleYaml } = require('./intent');
+const { parseSimpleYaml, formatDiagnostic } = require('./intent');
 const state = require('./state');
 
 const RECIPES_DIR = path.join(__dirname, '..', 'routing', 'recipes');
 
 let _cache = null;
 
+function warnYamlDiagnostic(diagnostic) {
+  console.warn(`[godpowers] YAML warning ${formatDiagnostic(diagnostic)}`);
+}
+
 /**
  * Load all recipe definitions.
  */
@@ -26,7 +30,11 @@ function loadAll() {
   for (const file of fs.readdirSync(RECIPES_DIR)) {
     if (!file.endsWith('.yaml') && !file.endsWith('.yml')) continue;
     const content = fs.readFileSync(path.join(RECIPES_DIR, file), 'utf8');
-    const parsed = parseSimpleYaml(content);
+    const parsed = parseSimpleYaml(content, {
+      strict: true,
+      source: path.join('routing', 'recipes', file),
+      onDiagnostic: warnYamlDiagnostic
+    });
     if (parsed.metadata && parsed.metadata.name) {
       result.push(parsed);
     }

package/lib/router.js

@@ -10,7 +10,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { parseSimpleYaml } = require('./intent');
+const { parseSimpleYaml, formatDiagnostic } = require('./intent');
 const state = require('./state');
 const commandFamilies = require('./command-families');
 
@@ -24,6 +24,10 @@ const HARDEN_FINDINGS = '.godpowers/harden/FINDINGS.md';
 
 let _cache = null;
 
+function warnYamlDiagnostic(diagnostic) {
+  console.warn(`[godpowers] YAML warning ${formatDiagnostic(diagnostic)}`);
+}
+
 /**
  * Load all routing files into a map keyed by command.
  */
@@ -35,7 +39,11 @@ function loadAll() {
   for (const file of fs.readdirSync(ROUTING_DIR)) {
     if (!file.endsWith('.yaml')) continue;
     const content = fs.readFileSync(path.join(ROUTING_DIR, file), 'utf8');
-    const parsed = parseSimpleYaml(content);
+    const parsed = parseSimpleYaml(content, {
+      strict: true,
+      source: path.join('routing', file),
+      onDiagnostic: warnYamlDiagnostic
+    });
     if (parsed.metadata && parsed.metadata.command) {
       result[parsed.metadata.command] = parsed;
     }

package/lib/skill-surface.js

@@ -1,17 +1,8 @@
 const fs = require('fs');
 const path = require('path');
+const frontmatter = require('./frontmatter');
 
-function parseFrontmatter(text) {
-  if (!text.startsWith('---\n')) return {};
-  const end = text.indexOf('\n---', 4);
-  if (end === -1) return {};
-  const out = {};
-  for (const line of text.slice(4, end).split('\n')) {
-    const match = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
-    if (match) out[match[1]] = match[2].replace(/^["']|["']$/g, '');
-  }
-  return out;
-}
+const parseFrontmatter = (text) => frontmatter.parse(text, { strict: true });
 
 function listSkills(rootDir = path.join(__dirname, '..', 'skills')) {
   return fs.readdirSync(rootDir)

package/lib/workflow-parser.js

@@ -7,7 +7,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const { parseSimpleYaml } = require('./intent');
+const { parseSimpleYaml, formatDiagnostic } = require('./intent');
+
+function warnYamlDiagnostic(diagnostic) {
+  console.warn(`[godpowers] YAML warning ${formatDiagnostic(diagnostic)}`);
+}
 
 /**
  * Parse a workflow YAML file into a structured object.
@@ -17,14 +21,18 @@ function parseFile(filePath) {
     throw new Error(`Workflow not found: ${filePath}`);
   }
   const content = fs.readFileSync(filePath, 'utf8');
-  return parse(content);
+  return parse(content, filePath);
 }
 
 /**
  * Parse YAML content into a workflow object.
  */
-function parse(yamlContent) {
-  const parsed = parseSimpleYaml(yamlContent);
+function parse(yamlContent, source = 'workflow.yaml') {
+  const parsed = parseSimpleYaml(yamlContent, {
+    strict: true,
+    source,
+    onDiagnostic: warnYamlDiagnostic
+  });
   validate(parsed);
   return parsed;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "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"
@@ -22,6 +22,7 @@
     "test:linter": "node scripts/test-artifact-linter.js",
     "test:diff": "node scripts/test-artifact-diff.js",
     "test:e2e": "node tests/integration/full-arc.test.js",
+    "coverage": "c8 --reporter=text --reporter=lcov node scripts/run-tests.js",
     "test:audit": "npm audit --omit=dev && git diff --check && npm run test:surface",
     "pack:check": "node scripts/check-package-contents.js",
     "release:check": "npm test && npm run test:audit && npm run pack:check",
@@ -86,5 +87,8 @@
     "AGENTS.md",
     "CHANGELOG.md",
     "LICENSE"
-  ]
+  ],
+  "devDependencies": {
+    "c8": "^11.0.0"
+  }
 }