godpowers 1.6.16 → 1.6.17

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.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.17-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.17 adds autonomous repository documentation sync. `/god-sync`,
+`/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` can now detect stale
+README badges, public surface counts, release docs, contribution guidance,
+security policy, and Pillars context planning needs before a project run is
+declared complete.
 
 It fuses four disciplines into one unified workflow:
 
@@ -361,6 +360,7 @@ 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)
 - [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.17 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.17 adds autonomous repository documentation sync for release
+surfaces and project-run closeout. Godpowers can now detect stale README badges,
+public surface counts, release notes, changelog entries, contribution guidance,
+security policy, and Pillars context planning needs before a sync, docs, doctor,
+status, or god-mode closeout declares the repository current.
 
 ## What is stable
 
@@ -23,46 +24,52 @@ 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
 
 ## 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.
+- Added `lib/repo-doc-sync.js`.
+- Added `docs/repo-doc-sync.md`.
+- Added `scripts/test-repo-doc-sync.js`.
+- Added missing `/god-export-otel` routing metadata.
+- `/god-sync`, `/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` now
+  document repo documentation sync integration.
+- The dashboard proactive docs check now reads repo documentation sync status.
+- Package contents checks now require the repo documentation sync helper and
+  `/god-export-otel` routing metadata.
 
-## Awareness behavior
+## Sync behavior
 
-For an initialized `.godpowers` project, the helper:
+For a Godpowers repository, 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
+- reads package version and repository surface counts
+- detects stale mechanical claims in README, user docs, architecture docs,
+  roadmap docs, command reference docs, `/god-version`, and `/god-doctor`
+- applies safe mechanical badge, version, and count refreshes when requested
+- plans Pillars sync for changed repo documentation paths
+- recommends `god-docs-writer` for release notes, changelog, contribution,
+  support, or security policy prose
 
-Detection is read-only. Applying awareness does not rewrite product, planning,
-source-system, or code files outside Godpowers-owned fences.
+Detection is read-only by default. Applying sync does not invent narrative
+release notes, changelog entries, contribution policy, support policy, or
+security support policy.
 
 ## Auto-invoke and auto-spawn policy
 
-Feature awareness is local runtime work and must be reported as:
+Safe repo documentation 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 or spawns `god-docs-writer` only when narrative docs need
+claim verification or policy judgment after local mechanical sync has finished.
 
 ## Validation
 
 Release validation includes:
 
+- `node scripts/test-repo-doc-sync.js`
 - `node scripts/test-feature-awareness.js`
 - `node scripts/test-context-writer.js`
 - `node scripts/test-planning-systems.js`
@@ -70,5 +77,5 @@ Release validation includes:
 - `node scripts/validate-skills.js`
 - `git diff --check`
 
-The `v1.6.16` tag should point to the release commit that matches the npm
-`godpowers@1.6.16` package.
+The `v1.6.17` tag should point to the release commit that matches the npm
+`godpowers@1.6.17` package.

package/SKILL.md

@@ -154,7 +154,7 @@ 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>
   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 +214,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 | 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 +242,8 @@ 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`
 
 ### 13. Proactive Auto-Invoke Policy
 Godpowers should be proactive from disk evidence, not from guesswork. Before
@@ -278,6 +280,10 @@ 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.
 - 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 +297,9 @@ 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-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/lib/README.md

@@ -13,6 +13,7 @@ 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. |
 | `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,7 @@ 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 GOD_DIR = '.godpowers';
 const PRD_PATH = '.godpowers/prd/PRD.md';
@@ -158,12 +159,16 @@ 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`;
 
   return {
     checkpoint,
     reviews: reviews > 0 ? `${reviews} pending, suggest /god-review-changes` : 'none',
     sync,
-    docs: 'fresh',
+    docs: repoDocsStatus,
     runtime: 'not-applicable',
     automation: automationSummary(projectRoot),
     security: sensitiveChanged ? 'sensitive files changed, suggest /god-harden' : 'clear',

package/lib/feature-awareness.js

@@ -34,6 +34,12 @@ 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.'
   }
 ];
 

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'] },

package/lib/repo-doc-sync.js

@@ -0,0 +1,392 @@
+/**
+ * Repository documentation sync.
+ *
+ * Keeps mechanical public repository claims aligned with the actual runtime
+ * surface. Narrative docs remain human or specialist-agent owned.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const pillars = require('./pillars');
+
+const LOG_PATH = '.godpowers/docs/REPO-DOC-SYNC.md';
+
+function read(projectRoot, relPath) {
+  const file = path.join(projectRoot, relPath);
+  if (!fs.existsSync(file)) return '';
+  return fs.readFileSync(file, 'utf8');
+}
+
+function write(projectRoot, relPath, text) {
+  const file = path.join(projectRoot, relPath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+function exists(projectRoot, relPath) {
+  return fs.existsSync(path.join(projectRoot, relPath));
+}
+
+function countFiles(projectRoot, dir, pattern) {
+  const full = path.join(projectRoot, dir);
+  if (!fs.existsSync(full)) return 0;
+  return fs.readdirSync(full).filter((name) => pattern.test(name)).length;
+}
+
+function readPackage(projectRoot) {
+  const file = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return {};
+  }
+}
+
+function packageVersion(projectRoot) {
+  return readPackage(projectRoot).version || 'unknown';
+}
+
+function counts(projectRoot) {
+  return {
+    skills: countFiles(projectRoot, 'skills', /^god.*\.md$/),
+    agents: countFiles(projectRoot, 'agents', /^god.*\.md$/),
+    workflows: countFiles(projectRoot, 'workflows', /\.yaml$/),
+    recipes: countFiles(projectRoot, path.join('routing', 'recipes'), /\.yaml$/)
+  };
+}
+
+function expectedSurface(projectRoot) {
+  const version = packageVersion(projectRoot);
+  const surfaceCounts = counts(projectRoot);
+  return {
+    version,
+    counts: surfaceCounts,
+    surface: `${surfaceCounts.skills} skills, ${surfaceCounts.agents} agents`,
+    commandSurface: `${surfaceCounts.skills} slash commands`,
+    workflowSurface: `${surfaceCounts.workflows} workflows`,
+    recipeSurface: `${surfaceCounts.recipes} recipes`,
+    minorSeries: version.split('.').slice(0, 2).join('.')
+  };
+}
+
+function includes(projectRoot, relPath, expected) {
+  const text = read(projectRoot, relPath);
+  return text.includes(expected);
+}
+
+function makeCheck(id, relPath, expected, opts = {}) {
+  return {
+    id,
+    path: relPath,
+    expected,
+    safeFix: opts.safeFix === true,
+    owner: opts.owner || (opts.safeFix ? 'local runtime' : 'god-docs-writer'),
+    reason: opts.reason || ''
+  };
+}
+
+function checkDefinitions(projectRoot) {
+  const expected = expectedSurface(projectRoot);
+  return [
+    makeCheck('package-description-surface', 'package.json',
+      `${expected.counts.skills} slash commands and ${expected.counts.agents} specialist agents`,
+      { safeFix: true, reason: 'package metadata is a mechanical count claim' }),
+    makeCheck('readme-version-badge', 'README.md', `version-${expected.version}-blue`,
+      { safeFix: true, reason: 'README badge mirrors package version' }),
+    makeCheck('readme-reference-counts', 'README.md',
+      `all ${expected.counts.skills} skills + ${expected.counts.agents} agents`,
+      { safeFix: true, reason: 'README command reference count mirrors files on disk' }),
+    makeCheck('users-version', 'USERS.md', `Godpowers is at v${expected.version}. Stable release.`,
+      { safeFix: true, reason: 'user support version mirrors package version' }),
+    makeCheck('architecture-version', 'ARCHITECTURE.md', `STABLE v${expected.version}`,
+      { safeFix: true, reason: 'architecture release marker mirrors package version' }),
+    makeCheck('architecture-surface', 'ARCHITECTURE.md',
+      `Core: ${expected.surface}, ${expected.workflowSurface}`,
+      { safeFix: true, reason: 'architecture surface mirrors repository counts' }),
+    makeCheck('roadmap-version', 'docs/ROADMAP.md', `Current shipped: v${expected.version}`,
+      { safeFix: true, reason: 'roadmap current shipped marker mirrors package version' }),
+    makeCheck('roadmap-command-count', 'docs/ROADMAP.md', `**${expected.commandSurface}**`,
+      { safeFix: true, reason: 'roadmap command count mirrors skills directory' }),
+    makeCheck('roadmap-agent-count', 'docs/ROADMAP.md',
+      `**${expected.counts.agents} specialist agents**`,
+      { safeFix: true, reason: 'roadmap agent count mirrors agents directory' }),
+    makeCheck('reference-version', 'docs/reference.md', `reference for v${expected.version}`,
+      { safeFix: true, reason: 'reference docs version mirrors package version' }),
+    makeCheck('reference-command-count', 'docs/reference.md',
+      `Slash commands (${expected.counts.skills} total)`,
+      { safeFix: true, reason: 'reference command count mirrors skills directory' }),
+    makeCheck('reference-agent-count', 'docs/reference.md',
+      `Specialist agents (${expected.counts.agents} total)`,
+      { safeFix: true, reason: 'reference agent count mirrors agents directory' }),
+    makeCheck('god-version-surface', 'skills/god-version.md',
+      `Surface: ${expected.surface}, ${expected.workflowSurface}, ${expected.recipeSurface}`,
+      { safeFix: true, reason: '/god-version output mirrors repository counts' }),
+    makeCheck('god-doctor-skill-count', 'skills/god-doctor.md',
+      `[OK] ${expected.counts.skills} skills installed`,
+      { safeFix: true, reason: '/god-doctor sample output mirrors skills directory' }),
+    makeCheck('god-doctor-agent-count', 'skills/god-doctor.md',
+      `[OK] ${expected.counts.agents} agents installed`,
+      { safeFix: true, reason: '/god-doctor sample output mirrors agents directory' }),
+    makeCheck('release-notes-version', 'RELEASE.md', `Godpowers ${expected.version}`,
+      { reason: 'release notes are narrative and should be reviewed before publish' }),
+    makeCheck('changelog-version', 'CHANGELOG.md', `## [${expected.version}]`,
+      { reason: 'changelog entries are narrative and should be curated' }),
+    makeCheck('security-supported-series', 'SECURITY.md', `${expected.minorSeries}.x`,
+      { reason: 'supported versions are release policy and should be reviewed' }),
+    makeCheck('contributing-release-sync', 'CONTRIBUTING.md', 'repo documentation sync',
+      { reason: 'contributor release guidance is narrative policy' })
+  ];
+}
+
+function detect(projectRoot, opts = {}) {
+  const expected = expectedSurface(projectRoot);
+  const checks = checkDefinitions(projectRoot).map((check) => {
+    const present = exists(projectRoot, check.path);
+    const fresh = present && includes(projectRoot, check.path, check.expected);
+    return {
+      ...check,
+      status: !present ? 'missing' : (fresh ? 'fresh' : 'stale')
+    };
+  });
+  const stale = checks.filter((check) => check.status !== 'fresh');
+  const safeFixes = stale.filter((check) => check.safeFix);
+  const prose = stale.filter((check) => !check.safeFix);
+  const changedFiles = opts.changedFiles || [];
+  const touchedDocs = changedFiles.filter((file) => isRepoDocPath(file));
+  const pillarSyncPlan = touchedDocs.length > 0
+    ? pillars.planArtifactSync(projectRoot, touchedDocs, opts)
+    : [];
+
+  return {
+    version: expected.version,
+    counts: expected.counts,
+    status: stale.length === 0 ? 'fresh' : 'stale',
+    checks,
+    stale,
+    safeFixes,
+    prose,
+    touchedDocs,
+    pillarSyncPlan,
+    adjacentOpportunities: adjacentOpportunities(),
+    spawnRecommendation: prose.length > 0
+      ? {
+          agent: 'god-docs-writer',
+          reason: 'Repo documentation has narrative release, contribution, or security policy drift.',
+          paths: [...new Set(prose.map((check) => check.path))].sort()
+        }
+      : null
+  };
+}
+
+function replaceOnce(text, regex, replacement) {
+  if (!regex.test(text)) return text;
+  return text.replace(regex, replacement);
+}
+
+function safeFixContent(relPath, text, expected) {
+  switch (relPath) {
+    case 'package.json':
+      return fixPackageDescription(text, expected);
+    case 'README.md':
+      return replaceOnce(
+        replaceOnce(text, /version-[0-9]+\.[0-9]+\.[0-9]+-blue/g, `version-${expected.version}-blue`),
+        /all [0-9]+ skills \+ [0-9]+ agents/g,
+        `all ${expected.counts.skills} skills + ${expected.counts.agents} agents`
+      );
+    case 'USERS.md':
+      return replaceOnce(text, /Godpowers is at v[0-9]+\.[0-9]+\.[0-9]+\. Stable release\./g,
+        `Godpowers is at v${expected.version}. Stable release.`);
+    case 'ARCHITECTURE.md':
+      return replaceOnce(
+        replaceOnce(text, /STABLE v[0-9]+\.[0-9]+\.[0-9]+/g, `STABLE v${expected.version}`),
+        /Core: [0-9]+ skills, [0-9]+ agents, [0-9]+ workflows/g,
+        `Core: ${expected.surface}, ${expected.workflowSurface}`
+      );
+    case 'docs/ROADMAP.md':
+      return replaceOnce(
+        replaceOnce(
+          replaceOnce(text, /Current shipped: v[0-9]+\.[0-9]+\.[0-9]+/g,
+            `Current shipped: v${expected.version}`),
+          /\*\*[0-9]+ slash commands\*\*/g,
+          `**${expected.commandSurface}**`
+        ),
+        /\*\*[0-9]+ specialist agents\*\*/g,
+        `**${expected.counts.agents} specialist agents**`
+      );
+    case 'docs/reference.md':
+      return replaceOnce(
+        replaceOnce(
+          replaceOnce(text, /reference for v[0-9]+\.[0-9]+\.[0-9]+/g,
+            `reference for v${expected.version}`),
+          /Slash commands \([0-9]+ total\)/g,
+          `Slash commands (${expected.counts.skills} total)`
+        ),
+        /Specialist agents \([0-9]+ total\)/g,
+        `Specialist agents (${expected.counts.agents} total)`
+      );
+    case 'skills/god-version.md':
+      return replaceOnce(text,
+        /Surface: [0-9]+ skills, [0-9]+ agents, [0-9]+ workflows, [0-9]+ recipes/g,
+        `Surface: ${expected.surface}, ${expected.workflowSurface}, ${expected.recipeSurface}`);
+    case 'skills/god-doctor.md':
+      return replaceOnce(
+        replaceOnce(text, /\[OK\] [0-9]+ skills installed/g,
+          `[OK] ${expected.counts.skills} skills installed`),
+        /\[OK\] [0-9]+ agents installed/g,
+        `[OK] ${expected.counts.agents} agents installed`
+      );
+    default:
+      return text;
+  }
+}
+
+function fixPackageDescription(text, expected) {
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.description === 'string') {
+      parsed.description = parsed.description.replace(
+        /[0-9]+ slash commands and [0-9]+ specialist agents/g,
+        `${expected.counts.skills} slash commands and ${expected.counts.agents} specialist agents`
+      );
+    }
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+  } catch (err) {
+    return text;
+  }
+}
+
+function isRepoDocPath(file) {
+  return [
+    'README.md',
+    'CHANGELOG.md',
+    'RELEASE.md',
+    'CONTRIBUTING.md',
+    'SECURITY.md',
+    'SUPPORT.md',
+    'AGENTS.md'
+  ].includes(file) || file.startsWith('docs/');
+}
+
+function appendLog(projectRoot, before, after, applied) {
+  const now = new Date().toISOString();
+  const lines = [];
+  if (exists(projectRoot, LOG_PATH)) {
+    lines.push(read(projectRoot, LOG_PATH).replace(/\s*$/, ''));
+    lines.push('');
+  } else {
+    lines.push('# Repo Documentation Sync Log');
+    lines.push('');
+    lines.push('- [DECISION] This file records mechanical repository documentation syncs run by Godpowers.');
+    lines.push('- [DECISION] Narrative release, contribution, support, and security policy prose remains owned by humans or `god-docs-writer`.');
+    lines.push('');
+  }
+  lines.push(`## ${now}`);
+  lines.push('');
+  lines.push(`- [DECISION] Repo documentation sync status before apply was ${before.status}.`);
+  lines.push(`- [DECISION] Repo documentation sync status after apply is ${after.status}.`);
+  if (applied.length === 0) {
+    lines.push('- [DECISION] No mechanical repo documentation files were changed.');
+  } else {
+    for (const item of applied) {
+      lines.push(`- [DECISION] Refreshed ${item.path} for ${item.checks.join(', ')}.`);
+    }
+  }
+  if (after.spawnRecommendation) {
+    lines.push(`- [HYPOTHESIS] ${after.spawnRecommendation.agent} should review ${after.spawnRecommendation.paths.join(', ')}.`);
+  }
+  lines.push('');
+  write(projectRoot, LOG_PATH, lines.join('\n'));
+}
+
+function run(projectRoot, opts = {}) {
+  const before = detect(projectRoot, opts);
+  const expected = expectedSurface(projectRoot);
+  const byPath = new Map();
+  const applied = [];
+
+  for (const check of before.safeFixes) {
+    if (!byPath.has(check.path)) byPath.set(check.path, []);
+    byPath.get(check.path).push(check);
+  }
+
+  for (const [relPath, checks] of byPath.entries()) {
+    const original = read(projectRoot, relPath);
+    if (!original) continue;
+    const next = safeFixContent(relPath, original, expected);
+    if (next !== original) {
+      write(projectRoot, relPath, next);
+      applied.push({
+        path: relPath,
+        checks: checks.map((check) => check.id)
+      });
+    }
+  }
+
+  const touched = applied.map((item) => item.path);
+  const pillarResults = opts.applyPillars && touched.length > 0
+    ? pillars.applyArtifactSync(projectRoot, touched, opts)
+    : pillars.planArtifactSync(projectRoot, touched, opts);
+
+  const after = detect(projectRoot, { ...opts, changedFiles: touched });
+  if (opts.log !== false) appendLog(projectRoot, before, after, applied);
+
+  return {
+    before,
+    after,
+    applied,
+    pillarResults,
+    logPath: opts.log === false ? null : LOG_PATH,
+    hash: sha(JSON.stringify({ before: before.status, after: after.status, applied }))
+  };
+}
+
+function sha(input) {
+  return `sha256:${crypto.createHash('sha256').update(input).digest('hex')}`;
+}
+
+function adjacentOpportunities() {
+  return [
+    {
+      id: 'routing-surface-sync',
+      trigger: '/god-doctor, /god-help, /god-next, /god-sync',
+      behavior: 'detect missing routing YAML for installed slash-command skills',
+      escalation: 'suggest fix by default, auto-apply only under fix mode'
+    },
+    {
+      id: 'package-installer-sync',
+      trigger: '/god-doctor, /god-sync, release checks',
+      behavior: 'detect package file allowlist and installer smoke drift when runtime files are added',
+      escalation: 'suggest fix because package contents affect release'
+    },
+    {
+      id: 'agent-contract-sync',
+      trigger: '/god-agent-audit, /god-doctor, /god-sync',
+      behavior: 'compare route spawns, skill docs, agent files, and agent specs',
+      escalation: 'spawn god-auditor when ownership or handoff conflicts need judgment'
+    },
+    {
+      id: 'workflow-recipe-graph-sync',
+      trigger: '/god-next, /god-mode, /god-doctor',
+      behavior: 'compare workflow YAML, recipes, command flows, and orchestrator guidance',
+      escalation: 'spawn god-roadmap-reconciler when lifecycle intent is ambiguous'
+    },
+    {
+      id: 'extension-pack-sync',
+      trigger: '/god-extension-info, /god-extension-list, /god-doctor',
+      behavior: 'compare first-party extension manifests, READMEs, skills, agents, and workflows',
+      escalation: 'spawn god-coordinator for multi-pack release prep'
+    }
+  ];
+}
+
+module.exports = {
+  LOG_PATH,
+  counts,
+  expectedSurface,
+  detect,
+  run,
+  adjacentOpportunities
+};

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "godpowers",
-  "version": "1.6.16",
+  "version": "1.6.17",
   "description": "AI-powered development system: 109 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"
   },
   "scripts": {
-    "test": "node scripts/validate-skills.js && node scripts/test-doc-surface-counts.js && bash scripts/smoke.sh && node scripts/test-runtime.js && node scripts/test-router.js && node scripts/test-recipes.js && node scripts/test-context-writer.js && node scripts/test-pillars.js && node scripts/test-artifact-linter.js && node scripts/test-artifact-diff.js && node scripts/test-design-foundation.js && node scripts/test-linkage.js && node scripts/test-impact.js && node scripts/test-reverse-sync.js && node scripts/test-planning-systems.js && node scripts/test-feature-awareness.js && node scripts/test-integration.js && node scripts/test-cross-artifact.js && node scripts/test-awesome-design.js && node scripts/test-skillui-bridge.js && node scripts/test-runtime-verification.js && node scripts/test-agent-browser.js && node scripts/test-mode-d.js && node scripts/test-runtime-heuristics.js && node scripts/test-agent-validator.js && node scripts/test-story-validator.js && node scripts/test-state.js && node scripts/test-dashboard.js && node scripts/test-automation-providers.js && node scripts/test-intent.js && node scripts/test-events.js && node scripts/test-golden-artifacts.js && node scripts/test-install-smoke.js && node scripts/test-checkpoint.js && node scripts/test-extensions.js && node scripts/test-event-reader.js && node scripts/test-state-lock.js && node scripts/test-cost-saver.js && node scripts/test-budget-onoff.js && node scripts/test-workflow-runner.js && npm run test:e2e && node scripts/test-otel-exporter.js && node scripts/test-extensions-publish.js",
+    "test": "node scripts/validate-skills.js && node scripts/test-doc-surface-counts.js && bash scripts/smoke.sh && node scripts/test-runtime.js && node scripts/test-router.js && node scripts/test-recipes.js && node scripts/test-context-writer.js && node scripts/test-pillars.js && node scripts/test-artifact-linter.js && node scripts/test-artifact-diff.js && node scripts/test-design-foundation.js && node scripts/test-linkage.js && node scripts/test-impact.js && node scripts/test-reverse-sync.js && node scripts/test-planning-systems.js && node scripts/test-feature-awareness.js && node scripts/test-repo-doc-sync.js && node scripts/test-integration.js && node scripts/test-cross-artifact.js && node scripts/test-awesome-design.js && node scripts/test-skillui-bridge.js && node scripts/test-runtime-verification.js && node scripts/test-agent-browser.js && node scripts/test-mode-d.js && node scripts/test-runtime-heuristics.js && node scripts/test-agent-validator.js && node scripts/test-story-validator.js && node scripts/test-state.js && node scripts/test-dashboard.js && node scripts/test-automation-providers.js && node scripts/test-intent.js && node scripts/test-events.js && node scripts/test-golden-artifacts.js && node scripts/test-install-smoke.js && node scripts/test-checkpoint.js && node scripts/test-extensions.js && node scripts/test-event-reader.js && node scripts/test-state-lock.js && node scripts/test-cost-saver.js && node scripts/test-budget-onoff.js && node scripts/test-workflow-runner.js && npm run test:e2e && node scripts/test-otel-exporter.js && node scripts/test-extensions-publish.js",
     "prepublishOnly": "npm test",
     "validate-skills": "node scripts/validate-skills.js",
     "test:surface": "node scripts/test-doc-surface-counts.js",

package/routing/god-export-otel.yaml

@@ -0,0 +1,24 @@
+apiVersion: godpowers/v1
+kind: CommandRouting
+metadata:
+  command: /god-export-otel
+  description: Export Godpowers events to OpenTelemetry OTLP JSON traces
+  tier: 0
+
+prerequisites:
+  required: []
+
+execution:
+  spawns: [built-in]
+  context: fresh
+  writes: []
+
+success-path:
+  next-recommended: /god-status
+
+failure-path:
+  on-error: /god-doctor
+
+endoff:
+  state-update: none
+  events: [agent.start, agent.end]

package/skills/god-docs.md

@@ -23,6 +23,11 @@ Documentation work. Docs that don't lie.
 
 ## Orchestration
 
+First call `lib/repo-doc-sync.run(projectRoot)` for mechanical repository
+documentation claims such as README badges, version references, public surface
+counts, and `/god-doctor` sample counts. Report this as `Agent: none, local
+runtime only`.
+
 Spawn **god-docs-writer** in fresh context.
 
 The agent:
@@ -56,6 +61,7 @@ Godpowers may invoke docs work proactively in two ways:
 |---|---|---|
 | Docs changed after code changed | Spawn `god-docs-writer` in drift-check mode when current workflow owns docs | Do not invent new docs scope |
 | Code changed after docs that claim current behavior | Suggest `/god-docs` or spawn drift-check inside `/god-mode`, `/god-feature`, `/god-refactor`, or `/god-sync` closeout | Verify claims against code before editing |
+| Repo docs surface drift | Run `lib/repo-doc-sync.run` for safe mechanical fixes, then spawn `god-docs-writer` for prose | Do not auto-invent changelog or release notes |
 | `REVIEW-REQUIRED.md` contains docs drift items | Suggest `/god-review-changes` first | Do not auto-clear review items |
 
 When auto-invoked, show:
@@ -65,6 +71,7 @@ Auto-invoked:
   Trigger: docs and code changed in the same workflow
   Agent: god-docs-writer
   Local syncs:
+    + repo-doc-sync: <safe mechanical fixes, prose review needed, or no-op>
     + docs-drift-check: <N claims checked, N drift items>
   Artifacts: .godpowers/docs/UPDATE-LOG.md or no-op
   Log: .godpowers/docs/UPDATE-LOG.md

package/skills/god-doctor.md

@@ -114,6 +114,18 @@ as a read-only diagnostic. It reports:
 `/god-doctor --fix` may call `lib/feature-awareness.run(projectRoot)` because
 that helper writes only safe state metadata and managed context fences.
 
+## Repo Documentation Sync
+
+For initialized projects, `/god-doctor` calls `lib/repo-doc-sync.detect` as a
+read-only diagnostic. It reports stale README badges, public surface counts,
+release notes, changelog entries, contribution guidance, security policy, and
+Pillars sync planning for changed repo docs.
+
+`/god-doctor --fix` may call `lib/repo-doc-sync.run(projectRoot)` because that
+helper writes only safe mechanical version, badge, and count claims. It should
+recommend `god-docs-writer` when narrative release, contribution, support, or
+security prose needs judgment.
+
 ## Implementation
 
 Built-in, no spawned agent. Reads:
@@ -122,6 +134,7 @@ Built-in, no spawned agent. Reads:
 - `.godpowers/state.json`, `intent.yaml`, `log`, `linkage.json`
 - `lib/feature-awareness.detect(projectRoot)` for existing-project upgrade
   awareness
+- `lib/repo-doc-sync.detect(projectRoot)` for repo documentation freshness
 - `bin/install.js` VERSION constant
 
 ## Exit codes

package/skills/god-mode.md

@@ -306,6 +306,7 @@ Sync status:
   Local syncs:
     + feature-awareness: <recorded runtime features, refreshed context, or no-op>
     + reverse-sync: <counts and result>
+    + repo-doc-sync: <refreshed repo docs, recommended god-docs-writer, or no-op>
     + pillars-sync: <counts and result>
     + checkpoint-sync: <created, updated, no-op, or skipped>
     + context-refresh: <spawned, no-op, or skipped>
@@ -324,6 +325,11 @@ When `/god-mode` resumes an existing `.godpowers` project, it auto-invokes
 keeps upgraded projects aware of new runtime features, current context fences,
 and migration routes without rewriting user artifacts.
 
+The mandatory final sync also receives repo documentation sync through
+`/god-sync`. This keeps README badges, release surfaces, contribution guidance,
+security policy checks, and Pillars context planning arc-ready before the
+project run is declared complete.
+
 If `/god-mode` resumes an existing `.godpowers` project that lacks Pillars,
 it Pillar-izes the project before continuing. Existing `.godpowers` artifacts
 become managed source references in the relevant `agents/*.md` files.
@@ -345,6 +351,7 @@ Sync status:
   Local syncs:
     + feature-awareness: <recorded runtime features, refreshed context, or no-op>
     + reverse-sync: <counts and result>
+    + repo-doc-sync: <refreshed repo docs, recommended god-docs-writer, or no-op>
     + pillars-sync: <counts and result>
     + checkpoint-sync: <created, updated, no-op, or skipped>
     + context-refresh: <spawned, no-op, or skipped>

package/skills/god-status.md

@@ -171,8 +171,8 @@ Report:
 - Checkpoint: `fresh`, `missing`, `stale`, or `conflicts with state.json`
 - Reviews: `none` or `<N> pending, suggest /god-review-changes`
 - Sync: `fresh`, `missing`, `stale`, or `suggest /god-sync`
-- Docs: `fresh`, `possible drift, suggest /god-docs`, or
-  `docs drift-check already logged`
+- Docs: `fresh`, `<N> stale, suggest /god-docs`, `possible drift, suggest
+  /god-docs`, or `repo-doc-sync ran`
 - Runtime: `not-applicable`, `known URL, suggest /god-test-runtime`, or
   `no known URL, defer deployed verification`
 - Automation: `not configured`, `<N> active`, or

package/skills/god-sync.md

@@ -35,11 +35,18 @@ User runs `/god-sync` after manual changes. Useful for:
 3. Call `lib/pillars.pillarizeExisting(projectRoot)` if Pillars is absent or
    partial, because every Godpowers project must also carry native Pillars
    context.
-4. If `state.json` contains enabled `source-systems`, auto-invoke
+4. Call `lib/repo-doc-sync.run(projectRoot)` so README badges, public surface
+   counts, release references, contribution docs, and security policy are
+   checked before sync closes. Safe mechanical updates are local runtime work.
+   Narrative drift should recommend or spawn `god-docs-writer`.
+5. If repo documentation changed durable project truth, plan or apply Pillars
+   updates through `lib/pillars.planArtifactSync` or
+   `lib/pillars.applyArtifactSync` under the active Pillars policy.
+6. If `state.json` contains enabled `source-systems`, auto-invoke
    `lib/source-sync.run(projectRoot)` so current Godpowers progress is written
    back to imported GSD, BMAD, or Superpowers companion files. Report this as
    `Agent: none, local runtime only`.
-5. Spawn god-updater in fresh context with:
+7. Spawn god-updater in fresh context with:
    - The reconciliation verdict (if available from a prior /god-reconcile)
    - Or: re-run reconciliation against current state to detect what changed
    - Recent commits for context
@@ -51,7 +58,7 @@ Auto-invoked:
   Trigger: <manual /god-sync, recipe closeout, /god-mode final sync, or other source>
   Agent: god-updater
   Local syncs:
-    - pending: feature-awareness, reverse-sync, source-sync, pillars-sync, checkpoint-sync, context-refresh
+    - pending: feature-awareness, reverse-sync, source-sync, repo-doc-sync, pillars-sync, checkpoint-sync, context-refresh
   Artifacts: pending
   Log: .godpowers/SYNC-LOG.md
 ```
@@ -78,6 +85,7 @@ Sync status:
     + reverse-sync: <scanned N files, updated M footers, populated K review items>
     + feature-awareness: <recorded runtime features, refreshed context, or no-op>
     + source-sync: <written GSD/BMAD/Superpowers companion files, no-op, or skipped>
+    + repo-doc-sync: <refreshed README badges/counts, recommended god-docs-writer, or no-op>
     + pillars-sync: <updated N pillar files, no-op, or proposed>
     + checkpoint-sync: <CHECKPOINT.md updated or skipped>
     + context-refresh: <updated AGENTS.md/tool pointers, no-op, or skipped by setting>
@@ -122,6 +130,7 @@ Next:
 | Orphan todos | Closes superseded todos |
 | Lost threads | Active threads get progress notes |
 | Pillars drift | Keeps `agents/*.md` aligned with current `.godpowers` artifacts |
+| Repo docs drift | Keeps README badges, repo docs, and release surfaces aligned |
 
 The loop: