godpowers 1.6.16 → 1.6.19

package/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to Godpowers will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.19] - 2026-05-16
+
+Repository surface sync and status truth closeout.
+
+### Added
+- Added `lib/repo-surface-sync.js` to detect structural drift across command
+  routing, package payload rules, agent handoffs, workflow metadata, recipe
+  routes, extension packs, and release policy checks.
+- Added `docs/repo-surface-sync.md` with auto-invoke, auto-spawn, and guardrail
+  behavior.
+- Added behavioral tests for missing route detection, explicit route stub
+  creation, sync logging, package checks, agent handoff checks, and current
+  repo freshness.
+
+### Changed
+- `/god-sync`, `/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` now
+  document repo surface sync behavior.
+- Dashboard proactive checks now include a repo surface status line.
+- Feature awareness now records `repo-surface-sync` as a known runtime feature.
+- Package contents checks now require `lib/repo-surface-sync.js`.
+- README, release notes, command flows, release checklist, command reference,
+  and runtime docs now describe repo surface sync.
+
+### Guardrails
+- Detection is read-only by default.
+- Safe apply can create missing routing stubs only when `fixRouting` is
+  explicitly enabled.
+- Agent, workflow, recipe, extension, and release-policy ambiguity routes to
+  scoped specialists instead of being rewritten blindly.
+
+## [1.6.17] - 2026-05-16
+
+Autonomous repository documentation sync.
+
+### Added
+- Added `lib/repo-doc-sync.js` to detect and refresh mechanical repository
+  documentation claims.
+- Added `docs/repo-doc-sync.md` with auto-invoke, auto-spawn, Pillars, and
+  arc-ready closeout behavior.
+- Added behavioral tests for stale repo docs detection, safe mechanical sync,
+  sync logging, Pillars planning, and adjacent autonomous sync recommendations.
+- Added missing `/god-export-otel` routing metadata.
+
+### Changed
+- `/god-sync`, `/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` now
+  document repo documentation sync behavior.
+- The dashboard proactive docs check now uses `lib/repo-doc-sync.detect`.
+- Package contents checks now require `lib/repo-doc-sync.js` and
+  `routing/god-export-otel.yaml`.
+- Release and contribution docs now describe repo documentation sync as part of
+  release readiness.
+
+### Guardrails
+- Detection is read-only by default.
+- Safe apply is limited to mechanical version, badge, and count claims.
+- Narrative changelog, release, contribution, support, and security policy
+  changes route to `god-docs-writer` or the maintainer.
+
 ## [1.6.16] - 2026-05-16
 
 Feature awareness for existing Godpowers projects.

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-1.6.16-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.6.19-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.**
@@ -12,12 +12,11 @@ idea to hardened production. It runs as **slash commands inside your AI coding
 tool** (Claude Code, Codex, Cursor, etc.) that orchestrate **specialist agents**
 in fresh contexts to do the work.
 
-Version 1.6.16 adds feature awareness for existing Godpowers projects. When a
-new runtime adds capabilities, `/god-doctor`, `/god-context`, `/god-sync`, and
-`/god-mode` can detect stale project awareness, record the current feature set
-in `state.json`, refresh AI-tool context fences, and point source-system
-migration cases to `/god-migrate` or `god-greenfieldifier` when judgment is
-needed.
+Version 1.6.19 sharpens Godpowers status truth and adds repository surface
+sync. Dashboards now name whether they came from `lib/dashboard.js` or a manual
+fallback, and Godpowers checks routing gaps, package payload drift, agent
+handoff drift, workflow metadata drift, recipe route drift, extension pack
+drift, and release-policy drift before closeout.
 
 It fuses four disciplines into one unified workflow:
 
@@ -195,12 +194,13 @@ durable `.godpowers` artifacts change project truth. The decision is logged to
 `.godpowers/YOLO-DECISIONS.md`.
 
 Every completing command now ends with a **Godpowers Dashboard**. It shows the
-current phase, tier, step count, percent complete, PRD and roadmap visibility,
+current phase, tier, step count, workflow progress, PRD and roadmap visibility,
 recent work, proactive checks, open items, and the single recommended next
 action. `/god-status` and `/god-next` use the same shape so the project never
 ends in a vague "done" state. The dashboard is backed by
-`lib/dashboard.js`, so status and next-step commands share one executable
-source of disk truth instead of parallel Markdown-only contracts.
+`lib/dashboard.js`, and the rendered output names that source when the runtime
+engine is available. Audit, hygiene, and remediation scores are reported as
+separate scores rather than being reused as workflow progress.
 
 Godpowers can also inspect automation support:
 
@@ -361,6 +361,8 @@ Pi. T3 Code inherits from the underlying agent (Codex / Claude / OpenCode).
 - [Concepts](docs/concepts.md)
 - [Command reference (all 109 skills + 40 agents)](docs/reference.md)
 - [Feature awareness](docs/feature-awareness.md)
+- [Repository documentation sync](docs/repo-doc-sync.md)
+- [Repository surface sync](docs/repo-surface-sync.md)
 - [Roadmap](docs/ROADMAP.md)
 - [Release Notes](RELEASE.md)
 - [Changelog](CHANGELOG.md)

package/RELEASE.md

@@ -1,11 +1,12 @@
-# Godpowers 1.6.16 Release
+# Godpowers 1.6.19 Release
 
 Date: 2026-05-16
 
-Godpowers 1.6.16 adds feature awareness for existing Godpowers projects. After
-the installed runtime gains new capabilities, Godpowers can detect stale project
-awareness, record the current feature set in `state.json`, refresh AI-tool
-context fences, and route migration judgment to the right command or agent.
+Godpowers 1.6.19 adds repository surface sync and clarifies status truth across
+`/god-status`, `/god-next`, God Mode closeouts, and installer CLI status
+helpers. Godpowers can now detect structural drift across routes, package
+payload rules, agent handoffs, workflow metadata, recipe routes, extension
+packs, and release policy before declaring a project run current.
 
 ## What is stable
 
@@ -23,52 +24,68 @@ context fences, and route migration judgment to the right command or agent.
 - Critical harden finding gate before launch
 - Planning-system migration for GSD, BMAD, and Superpowers
 - Managed sync-back companion files for imported source systems
+- Feature awareness for existing Godpowers projects
+- Repository documentation sync checks
+- Repository surface sync checks
 
 ## What is new
 
-- Added `lib/feature-awareness.js`.
-- Added `godpowers-features` to `state.v1.json`.
-- Added `scripts/test-feature-awareness.js`.
-- `/god-doctor`, `/god-context`, `/god-sync`, and `/god-mode` now document the
-  feature-awareness auto-invoke path.
-- `AGENTS.md` refreshes now include `/god-sync`, `/god-migrate`, and
-  `/god-context refresh` in the useful command list.
-
-## Awareness behavior
-
-For an initialized `.godpowers` project, the helper:
-
-- reads the installed runtime version
-- compares the project `godpowers-features` record to the current feature set
-- detects missing managed AI-tool context fences
-- detects unimported GSD, BMAD, or Superpowers planning artifacts
-- writes only safe state metadata and managed context fences when applied
-
-Detection is read-only. Applying awareness does not rewrite product, planning,
-source-system, or code files outside Godpowers-owned fences.
+- Added `lib/repo-surface-sync.js`.
+- Added `docs/repo-surface-sync.md`.
+- Added `scripts/test-repo-surface-sync.js`.
+- `/god-sync`, `/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` now
+  document repo surface sync integration.
+- Dashboard proactive checks now include a repo surface status line.
+- Package contents checks now require `lib/repo-surface-sync.js`.
+- Feature awareness now records `repo-surface-sync` as a known runtime feature.
+- Dashboard output keeps workflow progress distinct from audit, hygiene,
+  remediation, and launch-readiness scores.
+
+## Surface sync behavior
+
+For a Godpowers repository, the helper checks:
+
+- every `skills/god-*.md` command has matching `routing/god-*.yaml` metadata
+- required package payload entries exist in `package.json`
+- package content checks require load-bearing runtime helper files
+- routed specialist spawns resolve to real agent files
+- workflows have parseable metadata
+- recipes contain slash-command routes
+- extension manifests, package metadata, peer dependencies, and provided files agree
+- release docs and release policy checks name repo documentation and repo surface sync
+
+Detection is read-only by default. Applying sync only writes a log and may
+create missing routing stubs when `fixRouting` is explicitly enabled.
 
 ## Auto-invoke and auto-spawn policy
 
-Feature awareness is local runtime work and must be reported as:
+Safe repo surface sync is local runtime work and must be reported as:
 
-```
+```text
 Agent: none, local runtime only
 ```
 
-Godpowers recommends or spawns `god-greenfieldifier` only when imported or
-detected planning-system context has low confidence or conflicts that need
-migration judgment.
+Godpowers recommends scoped specialists only when judgment is needed:
+
+- `god-auditor` for agent contract or handoff drift
+- `god-roadmap-reconciler` for workflow or recipe lifecycle drift
+- `god-coordinator` for extension pack drift
+- `god-docs-writer` for release prose drift
 
 ## Validation
 
 Release validation includes:
 
+- `node scripts/test-repo-surface-sync.js`
+- `node scripts/test-repo-doc-sync.js`
 - `node scripts/test-feature-awareness.js`
+- `node scripts/test-dashboard.js`
 - `node scripts/test-context-writer.js`
 - `node scripts/test-planning-systems.js`
 - `node scripts/test-doc-surface-counts.js`
 - `node scripts/validate-skills.js`
 - `git diff --check`
+- `npm run release:check`
 
-The `v1.6.16` tag should point to the release commit that matches the npm
-`godpowers@1.6.16` package.
+The `v1.6.19` tag should point to the release commit that matches the npm
+`godpowers@1.6.19` package.

package/SKILL.md

@@ -154,7 +154,8 @@ Proactive checks:
   Checkpoint: <fresh | refreshed | missing | stale | conflicts with state.json>
   Reviews: <none | N pending, suggest /god-review-changes>
   Sync: <fresh | missing | stale | local helper ran | suggest /god-sync>
-  Docs: <fresh | possible drift, suggest /god-docs>
+  Docs: <fresh | N stale, suggest /god-docs | repo-doc-sync ran>
+  Repo surface: <fresh | N stale, suggest /god-doctor | repo-surface-sync ran>
   Runtime: <not-applicable | known URL, suggest /god-test-runtime | no known URL, defer deployed verification>
   Automation: <not configured | N active | available via provider, suggest /god-automation-setup>
   Security: <clear | sensitive files changed, suggest /god-harden>
@@ -214,7 +215,7 @@ Auto-invoked:
   Trigger: <what caused this automatic step>
   Agent: <god-updater | god-context-writer | none, local runtime only>
   Local syncs:
-    + <feature-awareness | planning-system-import | reverse-sync | source-sync | pillars-sync | checkpoint-sync | context-refresh>: <result or skipped reason>
+    + <feature-awareness | planning-system-import | reverse-sync | source-sync | repo-doc-sync | repo-surface-sync | pillars-sync | checkpoint-sync | context-refresh>: <result or skipped reason>
   Artifacts: <changed files, no-op, or deferred>
   Log: <SYNC-LOG.md, CHECKPOINT.md, REVIEW-REQUIRED.md, or none>
 ```
@@ -242,6 +243,10 @@ Automatic steps that especially need visible reporting:
 - source-system sync-back during `/god-sync`, `/god-scan`, or `/god-migrate`
 - feature-awareness refresh during `/god-doctor`, `/god-context`,
   `/god-sync`, or `/god-mode`
+- repo documentation sync during `/god-sync`, `/god-docs`, `/god-doctor`,
+  `/god-status`, or `/god-mode`
+- repo surface sync during `/god-sync`, `/god-docs`, `/god-doctor`,
+  `/god-status`, or `/god-mode`
 
 ### 13. Proactive Auto-Invoke Policy
 Godpowers should be proactive from disk evidence, not from guesswork. Before
@@ -278,6 +283,14 @@ Run these local runtime helpers automatically when their trigger is present:
   `lib/feature-awareness.run` during `/god-context`, `/god-sync`, or
   `/god-mode` when an initialized `.godpowers` project lacks current runtime
   feature metadata or managed AI-tool context fences.
+- `lib/repo-doc-sync.detect` during `/god-status` and `/god-doctor`, and
+  `lib/repo-doc-sync.run` during `/god-sync`, `/god-docs`, or `/god-mode`
+  when README badges, public surface counts, release docs, contribution docs,
+  or security policy may have drifted.
+- `lib/repo-surface-sync.detect` during `/god-status` and `/god-doctor`, and
+  `lib/repo-surface-sync.run` during `/god-sync`, `/god-docs`, or
+  `/god-mode` when command routing, package payload, agent handoffs, workflow
+  metadata, recipe routes, extension packs, or release policy may have drifted.
 - Context refresh dry-run after `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`,
   `.cursor/rules/`, `.windsurfrules`, `.github/copilot-instructions.md`,
   `.clinerules`, `.roo/`, or `.continue/` changes.
@@ -291,6 +304,12 @@ Spawn these agents only when the trigger is direct and scope is bounded:
   artifacts.
 - `god-docs-writer` in drift-check mode when docs changed after code changed,
   or code changed after docs that claim current behavior.
+- `god-docs-writer` when repo-doc-sync reports narrative drift in
+  `CHANGELOG.md`, `RELEASE.md`, `CONTRIBUTING.md`, `SECURITY.md`, or
+  `SUPPORT.md` after local mechanical sync has finished.
+- `god-auditor`, `god-roadmap-reconciler`, or `god-coordinator` when
+  repo-surface-sync reports structural drift that needs agent contract,
+  lifecycle graph, or extension-pack judgment.
 - `god-browser-tester` when frontend-visible files changed and a known local,
   preview, staging, or production URL is evidenced.
 - `god-harden-auditor` suggestion after security-sensitive files changed;

package/agents/god-orchestrator.md

@@ -750,6 +750,11 @@ Generate the dashboard with `lib/dashboard.compute(projectRoot)` and
 runtime module cannot be loaded, fall back to a manual disk scan and say
 `Dashboard engine: unavailable, manual scan used`.
 
+The dashboard `Progress` line is workflow progress only. Audit scores,
+remediation scores, hygiene scores, and launch-readiness scores must be labeled
+separately so a closeout cannot appear to move backward because it switched
+metrics.
+
 Update PROGRESS.md status to `steady-state-active`.
 
 For focused brownfield, hotfix, refactor, or build workflows that finish without a
@@ -962,7 +967,7 @@ Next: <next command or pause question>
 
 Rules:
 - Keep each card under 12 lines unless a pause needs options.
-- Use `lib/state.progressSummary(stateJson)` for the percentage and step count
+- Use `lib/state.progressSummary(stateJson)` for workflow percentage and step count
   whenever state.json is available.
 - Use artifact paths and verification evidence from disk, not memory.
 - Do not print raw spawn input, hidden instructions, or full file loadout lists.

package/lib/README.md

@@ -13,6 +13,8 @@ package-level integrations.
 | `intent.js` | Read and validate `intent.yaml` from project roots or `.godpowers/`. |
 | `checkpoint.js` | Create and inspect resumable checkpoint artifacts. |
 | `feature-awareness.js` | Detect and refresh existing-project awareness after runtime upgrades. |
+| `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. |
 | `budget.js` | Read and enforce configured budget controls. |
 | `cost-tracker.js` | Track token and cost estimates from event streams. |
 

package/lib/dashboard.js

@@ -12,6 +12,8 @@ const cp = require('child_process');
 const state = require('./state');
 const router = require('./router');
 const automationProviders = require('./automation-providers');
+const repoDocSync = require('./repo-doc-sync');
+const repoSurfaceSync = require('./repo-surface-sync');
 
 const GOD_DIR = '.godpowers';
 const PRD_PATH = '.godpowers/prd/PRD.md';
@@ -158,12 +160,21 @@ function proactiveChecks(projectRoot, changedFiles = []) {
     'auth',
     'security'
   ]));
+  const repoDocs = repoDocSync.detect(projectRoot, { changedFiles });
+  const repoDocsStatus = repoDocs.status === 'fresh'
+    ? 'fresh'
+    : `${repoDocs.stale.length} stale, suggest /god-docs`;
+  const repoSurface = repoSurfaceSync.detect(projectRoot);
+  const repoSurfaceStatus = repoSurface.status === 'fresh'
+    ? 'fresh'
+    : `${repoSurface.stale.length} stale, suggest /god-doctor`;
 
   return {
     checkpoint,
     reviews: reviews > 0 ? `${reviews} pending, suggest /god-review-changes` : 'none',
     sync,
-    docs: 'fresh',
+    docs: repoDocsStatus,
+    repoSurface: repoSurfaceStatus,
     runtime: 'not-applicable',
     automation: automationSummary(projectRoot),
     security: sensitiveChanged ? 'sensitive files changed, suggest /god-harden' : 'clear',
@@ -195,7 +206,8 @@ function planningVisibility(projectRoot, progress) {
     prd: { status: prd, path: prd === 'done' ? PRD_PATH : null },
     roadmap: { status: roadmap, path: roadmap === 'done' ? ROADMAP_PATH : null },
     currentMilestone: phase.stepLabel ? `${phase.phase} / ${phase.stepLabel}` : phase.phase,
-    completion: `${progress.percent}% based on state.json tracked steps`
+    completion: `${progress.percent}% workflow progress from .godpowers/state.json tracked steps`,
+    completionBasis: '.godpowers/state.json workflow steps'
   };
 }
 
@@ -206,6 +218,7 @@ function compute(projectRoot, opts = {}) {
   if (!s) {
     const next = { command: '/god-init', reason: 'No Godpowers project initialized' };
     return {
+      source: 'runtime dashboard (lib/dashboard.js)',
       state: 'not initialized',
       mode: null,
       lifecycle: 'pre-init',
@@ -217,7 +230,8 @@ function compute(projectRoot, opts = {}) {
         prd: { status: 'missing', path: null },
         roadmap: { status: 'missing', path: null },
         currentMilestone: 'Project initialization',
-        completion: '0% based on missing state.json'
+        completion: '0% workflow progress because .godpowers/state.json is missing',
+        completionBasis: 'missing .godpowers/state.json'
       },
       proactive: proactiveChecks(projectRoot, git.entries.map(statusPath)),
       next,
@@ -237,6 +251,7 @@ function compute(projectRoot, opts = {}) {
   if (openItems.length === 0) openItems.push('none');
 
   return {
+    source: 'runtime dashboard (lib/dashboard.js)',
     state: progress.remaining === 0 ? 'complete' : 'in progress',
     mode: s.mode || s['mode-announced-as'] || null,
     lifecycle: s['lifecycle-phase'] || 'in-arc',
@@ -266,11 +281,13 @@ function render(dashboard) {
   return [
     'Godpowers Dashboard',
     '',
+    `Source: ${dashboard.source || 'manual disk scan'}`,
+    '',
     'Current status:',
     `  State: ${dashboard.state}`,
     `  Phase: ${current.phase || 'unknown'}${current.tierNumber !== null && current.tierNumber !== undefined ? ` (tier ${current.tierOrdinal} of ${current.tierCount}, internal ${current.tierKey || `tier-${current.tierNumber}`})` : ''}`,
     `  Step: ${current.stepLabel || 'unknown'}${current.stepNumber ? ` (step ${current.stepNumber} of ${current.totalSteps})` : ''}`,
-    `  Progress: ${progress.percent || 0}% (${progress.completed || 0} of ${progress.total || 0} steps complete)`,
+    `  Progress: ${progress.percent || 0}% workflow progress (${progress.completed || 0} of ${progress.total || 0} tracked steps complete)`,
     `  Worktree: ${dashboard.worktree}`,
     `  Index: ${dashboard.index}`,
     '',
@@ -278,13 +295,14 @@ function render(dashboard) {
     `  PRD: ${prd.status || 'missing'}${prd.path ? ` ${prd.path}` : ''}`,
     `  Roadmap: ${roadmap.status || 'missing'}${roadmap.path ? ` ${roadmap.path}` : ''}`,
     `  Current milestone: ${planning.currentMilestone || 'unknown'}`,
-    `  Completion: ${planning.completion || 'unknown'}`,
+    `  Completion basis: ${planning.completionBasis || planning.completion || 'unknown'}`,
     '',
     'Proactive checks:',
     `  Checkpoint: ${proactive.checkpoint || 'unknown'}`,
     `  Reviews: ${proactive.reviews || 'unknown'}`,
     `  Sync: ${proactive.sync || 'unknown'}`,
     `  Docs: ${proactive.docs || 'unknown'}`,
+    `  Repo surface: ${proactive.repoSurface || 'unknown'}`,
     `  Runtime: ${proactive.runtime || 'unknown'}`,
     `  Automation: ${proactive.automation || 'unknown'}`,
     `  Security: ${proactive.security || 'unknown'}`,

package/lib/feature-awareness.js

@@ -34,6 +34,18 @@ const FEATURES = [
     since: '1.6.16',
     commands: ['/god-doctor', '/god-context', '/god-sync', '/god-mode'],
     description: 'Refresh existing Godpowers projects when the installed runtime gains new capabilities.'
+  },
+  {
+    id: 'repo-documentation-sync',
+    since: '1.6.17',
+    commands: ['/god-sync', '/god-docs', '/god-doctor', '/god-status', '/god-mode'],
+    description: 'Detect and refresh repository documentation surfaces, release docs, and Pillars planning signals.'
+  },
+  {
+    id: 'repo-surface-sync',
+    since: '1.6.19',
+    commands: ['/god-sync', '/god-docs', '/god-doctor', '/god-status', '/god-mode'],
+    description: 'Detect structural drift across routing, packages, agents, workflows, recipes, extensions, and release policy.'
   }
 ];
 

package/lib/pillars.js

@@ -80,6 +80,15 @@ const KNOWN_PILLARS = {
 };
 
 const ARTIFACT_PILLAR_MAP = [
+  { pattern: /^README\.md$/i, pillars: ['context', 'repo'] },
+  { pattern: /^CHANGELOG\.md$/i, pillars: ['context', 'deploy'] },
+  { pattern: /^RELEASE\.md$/i, pillars: ['context', 'deploy'] },
+  { pattern: /^CONTRIBUTING\.md$/i, pillars: ['repo', 'quality'] },
+  { pattern: /^SECURITY\.md$/i, pillars: ['security'] },
+  { pattern: /^SUPPORT\.md$/i, pillars: ['context'] },
+  { pattern: /^docs\/ROADMAP\.md$/i, pillars: ['context', 'quality'] },
+  { pattern: /^docs\/reference\.md$/i, pillars: ['repo'] },
+  { pattern: /^docs\/repo-doc-sync\.md$/i, pillars: ['repo', 'quality'] },
   { pattern: /(^|\/)prd\/PRD\.md$/i, pillars: ['context'] },
   { pattern: /(^|\/)arch\/ARCH\.md$/i, pillars: ['arch'] },
   { pattern: /(^|\/)arch\/adr\//i, pillars: ['arch'] },