godpowers 2.1.0 → 2.2.0

package/agents/god-roadmapper.md

@@ -70,13 +70,20 @@ Rules:
 ## Process
 
 1. Read PRD (priorities) and ARCH (technical dependencies)
-2. List all features from PRD with their priority (MUST/SHOULD/COULD)
+2. List all requirements from PRD by their stable id
+   (P-MUST-NN / P-SHOULD-NN / P-COULD-NN) and priority
 3. Build dependency graph from ARCH (component A depends on component B)
 4. Topologically sort
-5. Group features into delivery increments:
-   - Each increment has a clear, substitution-tested goal
-   - Each increment has an observable completion gate
-   - Each increment is sized: S/M/L (no day-level precision without capacity input)
+5. Group requirements into delivery increments. Each increment gets:
+   - A stable id `M-<slug>` derived from the increment name
+   - An initial `Status: pending`. Status is later derived from the linkage map
+     (code linked to the increment's requirements); set `done` explicitly only
+     when the completion gate has been verified
+   - A clear, substitution-tested goal
+   - An observable completion gate
+   - A size: S/M/L (no day-level precision without capacity input)
+   - A Features list of the exact PRD requirement ids it delivers
+     (P-MUST-01, P-MUST-02, ...), so each requirement maps to one increment
 6. Assign Now/Next/Later horizons:
    - **Now**: building right now, committed
    - **Next**: planned next, flexible
@@ -92,11 +99,13 @@ as the structural starting point. Write `.godpowers/roadmap/ROADMAP.md`:
 
 ## Now
 ### Delivery Increment 1: [substitution-tested name]
+- ID: M-[slug]
+- Status: pending
 - Goal: [what users can do when this ships]
 - Gate: [observable completion criteria]
 - Size: S/M/L
-- Depends on: [list]
-- Features: [from PRD]
+- Depends on: [M-slug list]
+- Features (from PRD): [P-MUST-01, P-MUST-02, ...]
 
 ## Next
 [delivery increments]
@@ -111,6 +120,8 @@ Roadmap FAILS if:
 - Delivery increment goal passes substitution test
 - Completion gate is not observable
 - Feature appears that is not in the PRD
+- Any increment has no stable M-slug id
+- A committed (Now or Next) increment lists no PRD requirement ids
 - All increments the same size (no prioritization)
 - No dependency edges between increments
 - Day-level precision without capacity input

package/agents/god-spec-reviewer.md

@@ -50,6 +50,13 @@ Answer each with EVIDENCE from the code:
    - Did the executor add future options, broad configurability, or generic
      interfaces that the current slice does not need?
 
+6. **Is each planned requirement id annotated in the code?**
+   - For each PRD requirement id listed in the slice plan (its `Requirements:`
+     field): does the code carry the corresponding `// Implements: P-...`
+     annotation that god-executor follows?
+   - A planned requirement id with no annotation is a finding, because the
+     deliverable ledger derives requirement status from those annotations.
+
 ## Output
 
 Return verdict to orchestrator:
@@ -75,6 +82,7 @@ Return verdict to orchestrator:
 - No scope creep without justification
 - Every touched file has request-trace evidence
 - No speculative flexibility or unrelated cleanup entered the diff
+- Every planned requirement id carries its `// Implements: P-...` annotation
 
 If FAIL: orchestrator returns the slice to god-executor with the failures.
 If PASS: orchestrator spawns god-quality-reviewer next.

package/agents/god-storyteller.md

@@ -33,6 +33,7 @@ title: "Short noun phrase"
 status: pending
 owner: <name>
 deps: []
+requirement: P-MUST-01   # optional; the PRD requirement id this story decomposes
 created: <ISO date>
 ---
 
@@ -61,6 +62,10 @@ As a [persona], I want [capability] so that [outcome].
 1. Read PRD.md and ARCH.md for context.
 2. If `--with-stories` from /god-feature: decompose the feature spec
    into 3-7 stories (don't exceed 10).
+   - When a story decomposes a specific PRD functional requirement, reference
+     that requirement id (set `requirement: P-MUST-01` in the frontmatter, or
+     mention it in the acceptance criteria) so the story traces back to the PRD
+     requirement and the deliverable ledger.
 3. Determine next ID number:
    - List `.godpowers/stories/<feature-slug>/STORY-*.md`
    - Use max + 1, zero-padded to 3 digits

package/agents/god-updater.md

@@ -113,6 +113,11 @@ After feature work, every artifact that was impacted needs to reflect reality.
   - Surfaces drift + impeccable findings to `REVIEW-REQUIRED.md`
 - Update `state.json.linkage` with current `coverage-pct`, `orphan-count`,
   `drift-count`, `review-required-items`
+- Refresh deliverable tracking from the updated linkage map:
+  - Call `lib/requirements.writeLedger(projectRoot)` to regenerate
+    `.godpowers/REQUIREMENTS.md`
+  - Cache the summary into `state.json.deliverables` via
+    `lib/requirements.summarizeForState`
 - Emit events: `linkage.snapshot`, `drift.detected` (per finding),
   `review-required.populated`
 - Report counts in the final sync status:
@@ -121,6 +126,7 @@ After feature work, every artifact that was impacted needs to reflect reality.
   - fenced footers updated
   - drift findings
   - REVIEW-REQUIRED.md items created
+  - requirement coverage: `<done>/<total> done` and any gaps
 
 ### Repository documentation sync
 - Call `lib/repo-doc-sync.run(projectRoot, { changedFiles })` when the runtime

package/bin/install.js

@@ -248,7 +248,7 @@ function runInstall(opts, srcDir) {
   log(`\x1b[32mDone!\x1b[0m Installed Godpowers v${VERSION} for ${installed} runtime(s).`);
   log('');
   log(`\x1b[36mInstalled:\x1b[0m`);
-  log(`  ${surface.skills} slash commands (try: /god-mode, /god-next, /god-status)`);
+  log(`  ${surface.skills} slash commands (try: /god-mode, /god-next, /god-status, /god-progress)`);
   log(`  ${surface.agents} specialist agents`);
   log('  Templates and references for artifact discipline');
   log('');

package/hooks/session-start.sh

@@ -80,6 +80,7 @@ Next step: run /god-next  (it inspects disk state and proposes the next command)
 Or:       /god-mode for the full autonomous project run
 Or:       /god-help to see the catalog
 Or:       /god-status for the full project snapshot
+Or:       /god-progress for deliverable progress (requirements done / left)
 Or:       /god-context refresh after installing a newer Godpowers runtime
 
 Disk state is authoritative. Conversation memory is not.

package/lib/README.md

@@ -22,6 +22,7 @@ package-level integrations.
 | `dogfood-runner.js` | Run deterministic messy-repo scenarios against migration, host, extension, and suite release behavior. |
 | `budget.js` | Read and enforce configured budget controls. |
 | `cost-tracker.js` | Track token and cost estimates from event streams. |
+| `fs-async.js` | Promise-based file read/write helpers for non-blocking runtime paths. |
 
 ## Events and observability
 
@@ -43,6 +44,8 @@ package-level integrations.
 | `workflow-runner.js` | Execute workflow steps with validation hooks. |
 | `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. |
+| `skill-surface.js` | Derive slash-command metadata from the individual `skills/` files. |
 
 ## Artifact quality
 
@@ -71,6 +74,7 @@ package-level integrations.
 | `impeccable-bridge.js` | Bridge runtime checks into impeccable quality workflows. |
 | `extensions.js` | Load and validate extension packs. |
 | `extension-authoring.js` | Scaffold publishable extension packs with manifest, package, README, skill, agent, and workflow files. |
+| `pillars.js` | Manage the Pillars project-context layer (`AGENTS.md` plus routed `agents/*.md`). |
 
 ## Repository and graph helpers
 
@@ -87,5 +91,17 @@ package-level integrations.
 | `review-required.js` | Decide when review gates should block progress. |
 | `suite-state.js` | Manage state across registered project suites. |
 
+## Installer, dashboard, and CLI helpers
+
+| Module | Purpose |
+|--------|---------|
+| `installer-core.js` | Install and uninstall the Godpowers surface for each runtime. |
+| `installer-files.js` | File-copy helpers shared by the installer and its tests. |
+| `installer-args.js` | Parse `bin/install.js` arguments and subcommands. |
+| `installer-runtimes.js` | Map supported runtimes to their config directories. |
+| `automation-providers.js` | Detect and configure host-native automation providers. |
+| `dashboard.js` | Compute the next-step action brief and host guarantee line. |
+| `quick-proof.js` | Render the shipped proof fixture for `godpowers quick-proof`. |
+
 See `../ARCHITECTURE.md` for system design and `../docs/ROADMAP.md` for planned
 runtime work.

package/lib/context-writer.js

@@ -216,15 +216,21 @@ function writeFenced(filePath, sectionContent) {
 }
 
 /**
- * Remove the Godpowers fence from a file. Leaves the rest untouched. If the
- * file becomes empty (whitespace only), removes it.
+ * Remove the Godpowers fence from a file. Leaves the rest untouched. If only
+ * the fence remained, an auto-generated pointer file is deleted; with
+ * { preserveFile: true } the file is emptied instead of deleted (used for the
+ * canonical AGENTS.md so the off-switch never removes the user's primary file).
  */
-function removeFenced(filePath) {
+function removeFenced(filePath, opts = {}) {
   if (!fs.existsSync(filePath)) return { removed: false, reason: 'missing' };
   const parsed = readFenced(filePath);
   if (parsed.fenced === '') return { removed: false, reason: 'no-fence' };
   let remaining = `${parsed.before}${parsed.after}`.replace(/\n{3,}/g, '\n\n').trim();
   if (remaining === '') {
+    if (opts.preserveFile) {
+      fs.writeFileSync(filePath, '');
+      return { removed: true, fileDeleted: false, emptied: true };
+    }
     fs.unlinkSync(filePath);
     return { removed: true, fileDeleted: true };
   }
@@ -284,8 +290,11 @@ function apply(projectRoot, state, opts = {}) {
  * Remove all Godpowers fences from canonical + pointers (off-switch).
  */
 function clearAll(projectRoot) {
-  const targets = [
-    path.join(projectRoot, 'AGENTS.md'),
+  // The canonical AGENTS.md is the user's primary context file: empty it rather
+  // than delete it. The remaining targets are auto-generated pointer files that
+  // Godpowers owns outright, so they are deleted when only the fence remains.
+  const canonical = path.join(projectRoot, 'AGENTS.md');
+  const pointers = [
     path.join(projectRoot, 'CLAUDE.md'),
     path.join(projectRoot, 'GEMINI.md'),
     path.join(projectRoot, '.cursorrules'),
@@ -300,7 +309,9 @@ function clearAll(projectRoot) {
     path.join(projectRoot, '.agents', 'skills', 'godpowers.md')
   ];
   const results = [];
-  for (const t of targets) {
+  const rc = removeFenced(canonical, { preserveFile: true });
+  if (rc.removed) results.push({ path: canonical, ...rc });
+  for (const t of pointers) {
     const r = removeFenced(t);
     if (r.removed) results.push({ path: t, ...r });
   }

package/lib/dashboard.js

@@ -10,6 +10,7 @@ const path = require('path');
 const cp = require('child_process');
 
 const state = require('./state');
+const requirements = require('./requirements');
 const router = require('./router');
 const automationProviders = require('./automation-providers');
 const repoDocSync = require('./repo-doc-sync');
@@ -239,6 +240,7 @@ function compute(projectRoot, opts = {}) {
       proactive: proactiveChecks(projectRoot, git.entries.map(statusPath)),
       host: hostCapabilities.detect(projectRoot, opts.host || {}),
       next,
+      deliverables: { hasRequirements: false },
       openItems: ['No .godpowers/state.json found']
     };
     result.actionBrief = actionBrief(result);
@@ -251,6 +253,14 @@ function compute(projectRoot, opts = {}) {
   const openItems = [];
   const drift = state.detectDrift(projectRoot);
 
+  const buildSub = s.tiers && s.tiers['tier-2'] && s.tiers['tier-2'].build;
+  const deliverables = requirements.derive(projectRoot, {
+    buildComplete: Boolean(buildSub && state.isCompleteStatus(buildSub.status))
+  });
+  if (deliverables.gaps.length > 0) {
+    openItems.push(`${deliverables.gaps.length} requirement(s) in a done increment with no linked code, see ${requirements.LEDGER_PATH}`);
+  }
+
   if (drift.length > 0) openItems.push(`${drift.length} artifact drift item(s), suggest /god-repair`);
   if (next && next.blocker) openItems.push(`${next.blocker} blocks next route`);
   if (reviewCount(projectRoot) > 0) openItems.push('pending review items');
@@ -269,6 +279,7 @@ function compute(projectRoot, opts = {}) {
     proactive: proactiveChecks(projectRoot, git.entries.map(statusPath)),
     host: hostCapabilities.detect(projectRoot, opts.host || {}),
     next,
+    deliverables,
     openItems
   };
   result.actionBrief = actionBrief(result);
@@ -314,6 +325,11 @@ function render(dashboard, opts = {}) {
   const progress = dashboard.progress || {};
   const prd = planning.prd || {};
   const roadmap = planning.roadmap || {};
+  const deliverables = dashboard.deliverables || { hasRequirements: false };
+  const deliverableLines = requirements.renderProgressLines(deliverables);
+  const deliverableBrief = deliverables.hasRequirements
+    ? `  Requirements: ${requirements.progressBar(deliverables.summary.done, deliverables.summary.total)} done (${deliverables.summary.percent}%)`
+    : null;
   const openItems = dashboard.openItems && dashboard.openItems.length > 0
     ? dashboard.openItems
     : ['none'];
@@ -332,6 +348,7 @@ function render(dashboard, opts = {}) {
       'Current status:',
       `  State: ${dashboard.state}`,
       `  Progress: ${progress.percent || 0}% workflow progress (${progress.completed || 0} of ${progress.total || 0} tracked steps complete)`,
+      ...(deliverableBrief ? [deliverableBrief] : []),
       '',
       'Next:',
       `  Recommended: ${next.command || 'describe the next intent'}`,
@@ -365,6 +382,9 @@ function render(dashboard, opts = {}) {
     `  Current milestone: ${planning.currentMilestone || 'unknown'}`,
     `  Completion basis: ${planning.completionBasis || planning.completion || 'unknown'}`,
     '',
+    'Deliverable progress:',
+    ...deliverableLines,
+    '',
     'Proactive checks:',
     `  Checkpoint: ${proactive.checkpoint || 'unknown'}`,
     `  Reviews: ${proactive.reviews || 'unknown'}`,

package/lib/feature-awareness.js

@@ -118,6 +118,12 @@ const FEATURES = [
     since: '1.6.22',
     commands: ['/god-suite-release'],
     description: 'Plan Mode D suite releases with impacted dependents and planned writes before mutation.'
+  },
+  {
+    id: 'deliverable-progress-tracking',
+    since: '2.2.0',
+    commands: ['/god-progress', '/god-status', '/god-sync'],
+    description: 'Track which PRD requirements and roadmap increments are done, in progress, or not started, derived from the linkage map and surfaced in the .godpowers/REQUIREMENTS.md ledger.'
   }
 ];