godpowers 1.6.16 → 1.6.19

package/lib/repo-surface-sync.js

@@ -0,0 +1,512 @@
+/**
+ * Repository surface sync.
+ *
+ * Detects structural drift between commands, routing, package metadata,
+ * agent contracts, workflows, recipes, extensions, and release policy docs.
+ * The helper is read-only by default. The apply path writes only safe local
+ * logs and optional missing routing stubs when explicitly requested.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseSimpleYaml } = require('./intent');
+const extensions = require('./extensions');
+const repoDocSync = require('./repo-doc-sync');
+
+const LOG_PATH = '.godpowers/surface/REPO-SURFACE-SYNC.md';
+
+const REQUIRED_PACKAGE_FILE_ENTRIES = [
+  'bin/',
+  'skills/',
+  'agents/god-*.md',
+  'templates/',
+  'references/',
+  'routing/',
+  'workflows/',
+  'schema/',
+  'lib/',
+  'extensions/',
+  'RELEASE.md',
+  'SKILL.md',
+  'AGENTS.md',
+  'CHANGELOG.md',
+  'LICENSE'
+];
+
+const REQUIRED_PACKAGE_CHECKS = [
+  'lib/feature-awareness.js',
+  'lib/repo-doc-sync.js',
+  'lib/repo-surface-sync.js',
+  'routing/god-export-otel.yaml'
+];
+
+function rel(projectRoot, absPath) {
+  return path.relative(projectRoot, absPath).split(path.sep).join('/');
+}
+
+function exists(projectRoot, relPath) {
+  return fs.existsSync(path.join(projectRoot, relPath));
+}
+
+function read(projectRoot, relPath) {
+  const file = path.join(projectRoot, relPath);
+  if (!fs.existsSync(file)) return '';
+  return fs.readFileSync(file, 'utf8');
+}
+
+function write(projectRoot, relPath, content) {
+  const file = path.join(projectRoot, relPath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function listFiles(projectRoot, relDir, pattern) {
+  const dir = path.join(projectRoot, relDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => pattern.test(name))
+    .sort()
+    .map((name) => `${relDir}/${name}`.replace(/\\/g, '/'));
+}
+
+function readJson(projectRoot, relPath) {
+  try {
+    return JSON.parse(read(projectRoot, relPath));
+  } catch (err) {
+    return null;
+  }
+}
+
+function routeForSkill(skillPath) {
+  const base = path.basename(skillPath, '.md');
+  return `routing/${base}.yaml`;
+}
+
+function commandForSkill(skillPath) {
+  return `/${path.basename(skillPath, '.md')}`;
+}
+
+function addCheck(checks, area, id, status, relPath, message, opts = {}) {
+  checks.push({
+    area,
+    id,
+    status,
+    path: relPath,
+    message,
+    severity: opts.severity || (status === 'fresh' ? 'info' : 'warning'),
+    safeFix: opts.safeFix === true,
+    spawn: opts.spawn || null
+  });
+}
+
+function routingChecks(projectRoot) {
+  const checks = [];
+  const skills = listFiles(projectRoot, 'skills', /^god.*\.md$/);
+  const routes = listFiles(projectRoot, 'routing', /^god.*\.yaml$/);
+  const skillRoutes = new Set(skills.map(routeForSkill));
+  const routeSet = new Set(routes);
+
+  for (const skill of skills) {
+    const route = routeForSkill(skill);
+    addCheck(
+      checks,
+      'routing',
+      `route-for-${path.basename(skill, '.md')}`,
+      routeSet.has(route) ? 'fresh' : 'stale',
+      route,
+      routeSet.has(route)
+        ? `${commandForSkill(skill)} has routing metadata.`
+        : `${commandForSkill(skill)} is missing routing metadata.`,
+      { safeFix: !routeSet.has(route) }
+    );
+  }
+
+  for (const route of routes) {
+    if (!skillRoutes.has(route)) {
+      addCheck(
+        checks,
+        'routing',
+        `skill-for-${path.basename(route, '.yaml')}`,
+        'stale',
+        route,
+        `${route} has no matching skill file.`,
+        { severity: 'warning' }
+      );
+    }
+  }
+  return checks;
+}
+
+function packageChecks(projectRoot) {
+  const checks = [];
+  const pkg = readJson(projectRoot, 'package.json') || {};
+  const lock = readJson(projectRoot, 'package-lock.json');
+  const fileEntries = Array.isArray(pkg.files) ? pkg.files : [];
+
+  for (const entry of REQUIRED_PACKAGE_FILE_ENTRIES) {
+    addCheck(
+      checks,
+      'package',
+      `package-files-${entry.replace(/[^a-z0-9]+/gi, '-')}`,
+      fileEntries.includes(entry) ? 'fresh' : 'stale',
+      'package.json',
+      fileEntries.includes(entry)
+        ? `package.json includes ${entry}.`
+        : `package.json files is missing ${entry}.`
+    );
+  }
+
+  const packageCheckText = read(projectRoot, 'scripts/check-package-contents.js');
+  for (const required of REQUIRED_PACKAGE_CHECKS) {
+    addCheck(
+      checks,
+      'package',
+      `package-check-${required.replace(/[^a-z0-9]+/gi, '-')}`,
+      packageCheckText.includes(required) ? 'fresh' : 'stale',
+      'scripts/check-package-contents.js',
+      packageCheckText.includes(required)
+        ? `package contents check requires ${required}.`
+        : `package contents check does not require ${required}.`
+    );
+  }
+
+  if (lock && lock.version) {
+    addCheck(
+      checks,
+      'package',
+      'package-lock-version',
+      lock.version === pkg.version ? 'fresh' : 'stale',
+      'package-lock.json',
+      lock.version === pkg.version
+        ? 'package-lock.json version matches package.json.'
+        : `package-lock.json version ${lock.version} does not match package.json ${pkg.version}.`
+    );
+  }
+
+  return checks;
+}
+
+function parseRoute(projectRoot, routePath) {
+  try {
+    return parseSimpleYaml(read(projectRoot, routePath));
+  } catch (err) {
+    return null;
+  }
+}
+
+function agentChecks(projectRoot) {
+  const checks = [];
+  const agents = new Set(listFiles(projectRoot, 'agents', /^god.*\.md$/)
+    .map((file) => path.basename(file, '.md')));
+  const routes = listFiles(projectRoot, 'routing', /^god.*\.yaml$/);
+  const missing = new Set();
+
+  for (const route of routes) {
+    const parsed = parseRoute(projectRoot, route);
+    const spawns = parsed && parsed.execution && Array.isArray(parsed.execution.spawns)
+      ? parsed.execution.spawns
+      : [];
+    for (const spawn of spawns) {
+      if (!String(spawn).startsWith('god-')) continue;
+      if (!/^god-[a-z0-9-]+$/.test(String(spawn))) continue;
+      if (!agents.has(spawn)) {
+        missing.add(`${route}:${spawn}`);
+        addCheck(
+          checks,
+          'agents',
+          `missing-agent-${spawn}`,
+          'stale',
+          route,
+          `${route} references missing agent ${spawn}.`,
+          { spawn: 'god-auditor' }
+        );
+      }
+    }
+  }
+
+  if (missing.size === 0) {
+    addCheck(checks, 'agents', 'route-spawn-targets', 'fresh',
+      'routing/', 'All routed specialist spawns resolve to agent files.');
+  }
+
+  return checks;
+}
+
+function workflowRecipeChecks(projectRoot) {
+  const checks = [];
+  const workflows = listFiles(projectRoot, 'workflows', /\.yaml$/);
+  const recipes = listFiles(projectRoot, path.join('routing', 'recipes'), /\.yaml$/);
+  const commandFlows = read(projectRoot, 'docs/command-flows.md');
+
+  for (const workflow of workflows) {
+    const text = read(projectRoot, workflow);
+    const parsed = parseSimpleYaml(text);
+    const hasMetadata = Boolean(parsed.apiVersion || parsed.name || parsed.metadata);
+    addCheck(
+      checks,
+      'workflow',
+      `workflow-metadata-${path.basename(workflow, '.yaml')}`,
+      hasMetadata ? 'fresh' : 'stale',
+      workflow,
+      hasMetadata ? `${workflow} has metadata.` : `${workflow} is missing parseable metadata.`,
+      { spawn: hasMetadata ? null : 'god-roadmap-reconciler' }
+    );
+  }
+
+  for (const recipe of recipes) {
+    const text = read(projectRoot, recipe);
+    const hasCommand = /\/god-[a-z0-9-]+/.test(text);
+    const recipeName = path.basename(recipe, '.yaml');
+    addCheck(
+      checks,
+      'workflow',
+      `recipe-command-${recipeName}`,
+      hasCommand ? 'fresh' : 'stale',
+      recipe,
+      hasCommand ? `${recipe} includes a slash-command route.` : `${recipe} has no slash-command route.`,
+      { spawn: hasCommand ? null : 'god-roadmap-reconciler' }
+    );
+  }
+
+  if (workflows.length > 0) {
+    addCheck(
+      checks,
+      'workflow',
+      'command-flows-workflows',
+      commandFlows.includes('/god-docs') && commandFlows.includes('/god-sync') ? 'fresh' : 'stale',
+      'docs/command-flows.md',
+      'docs/command-flows.md includes core docs and sync flows.',
+      { spawn: 'god-roadmap-reconciler' }
+    );
+  }
+  return checks;
+}
+
+function extensionChecks(projectRoot) {
+  const checks = [];
+  const extRoot = path.join(projectRoot, 'extensions');
+  const pkg = readJson(projectRoot, 'package.json') || {};
+  if (!fs.existsSync(extRoot)) return checks;
+  for (const entry of fs.readdirSync(extRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const packRel = `extensions/${entry.name}`;
+    const manifestRel = `${packRel}/manifest.yaml`;
+    const packageRel = `${packRel}/package.json`;
+    const manifestText = read(projectRoot, manifestRel);
+    const packPkg = readJson(projectRoot, packageRel);
+    const parsed = manifestText ? extensions.parseManifest(manifestText).manifest : null;
+    const validation = parsed ? extensions.validateManifest(parsed, pkg.version || '0.0.0') : ['missing manifest'];
+
+    addCheck(
+      checks,
+      'extensions',
+      `extension-manifest-${entry.name}`,
+      validation.length === 0 ? 'fresh' : 'stale',
+      manifestRel,
+      validation.length === 0
+        ? `${entry.name} manifest validates against current Godpowers.`
+        : `${entry.name} manifest validation failed: ${validation.join('; ')}.`,
+      { spawn: validation.length === 0 ? null : 'god-coordinator' }
+    );
+
+    if (parsed && packPkg) {
+      const sameName = parsed.metadata && parsed.metadata.name === packPkg.name;
+      const sameVersion = parsed.metadata && parsed.metadata.version === packPkg.version;
+      const sameEngine = packPkg.peerDependencies
+        && packPkg.peerDependencies.godpowers === parsed.engines.godpowers;
+      addCheck(checks, 'extensions', `extension-name-${entry.name}`,
+        sameName ? 'fresh' : 'stale', packageRel,
+        sameName ? `${entry.name} package name matches manifest.` : `${entry.name} package name does not match manifest.`,
+        { spawn: sameName ? null : 'god-coordinator' });
+      addCheck(checks, 'extensions', `extension-version-${entry.name}`,
+        sameVersion ? 'fresh' : 'stale', packageRel,
+        sameVersion ? `${entry.name} package version matches manifest.` : `${entry.name} package version does not match manifest.`,
+        { spawn: sameVersion ? null : 'god-coordinator' });
+      addCheck(checks, 'extensions', `extension-engine-${entry.name}`,
+        sameEngine ? 'fresh' : 'stale', packageRel,
+        sameEngine ? `${entry.name} peer dependency matches manifest engine.` : `${entry.name} peer dependency does not match manifest engine.`,
+        { spawn: sameEngine ? null : 'god-coordinator' });
+      for (const kind of ['skills', 'agents', 'workflows']) {
+        const provided = parsed.provides && Array.isArray(parsed.provides[kind])
+          ? parsed.provides[kind]
+          : [];
+        for (const item of provided) {
+          const ext = kind === 'workflows' ? 'yaml' : 'md';
+          const providedRel = `${packRel}/${kind}/${item}.${ext}`;
+          addCheck(checks, 'extensions', `extension-${kind}-${entry.name}-${item}`,
+            exists(projectRoot, providedRel) ? 'fresh' : 'stale',
+            providedRel,
+            exists(projectRoot, providedRel)
+              ? `${providedRel} exists.`
+              : `${providedRel} is missing.`,
+            { spawn: exists(projectRoot, providedRel) ? null : 'god-coordinator' });
+        }
+      }
+    }
+  }
+  return checks;
+}
+
+function releasePolicyChecks(projectRoot) {
+  const checks = [];
+  const docs = repoDocSync.detect(projectRoot);
+  addCheck(
+    checks,
+    'release',
+    'repo-doc-sync-fresh',
+    docs.status === 'fresh' ? 'fresh' : 'stale',
+    'docs/repo-doc-sync.md',
+    docs.status === 'fresh'
+      ? 'Repository documentation sync reports fresh.'
+      : `Repository documentation sync reports ${docs.stale.length} stale checks.`,
+    { spawn: docs.status === 'fresh' ? null : 'god-docs-writer' }
+  );
+  addCheck(
+    checks,
+    'release',
+    'release-checklist-surface-sync',
+    read(projectRoot, 'docs/RELEASE-CHECKLIST.md').includes('repo-surface-sync'),
+    'docs/RELEASE-CHECKLIST.md',
+    'Release checklist references repo-surface-sync readiness.',
+    { spawn: 'god-docs-writer' }
+  );
+  return checks.map((check) => ({
+    ...check,
+    status: check.status === true ? 'fresh' : (check.status === false ? 'stale' : check.status)
+  }));
+}
+
+function detect(projectRoot) {
+  const checks = [
+    ...routingChecks(projectRoot),
+    ...packageChecks(projectRoot),
+    ...agentChecks(projectRoot),
+    ...workflowRecipeChecks(projectRoot),
+    ...extensionChecks(projectRoot),
+    ...releasePolicyChecks(projectRoot)
+  ];
+  const stale = checks.filter((check) => check.status !== 'fresh');
+  const byArea = {};
+  for (const check of checks) {
+    if (!byArea[check.area]) byArea[check.area] = { total: 0, stale: 0 };
+    byArea[check.area].total++;
+    if (check.status !== 'fresh') byArea[check.area].stale++;
+  }
+  const spawnRecommendations = [...new Set(stale.map((check) => check.spawn).filter(Boolean))]
+    .map((agent) => ({
+      agent,
+      reason: `Repo surface drift requires ${agent} judgment.`,
+      paths: [...new Set(stale.filter((check) => check.spawn === agent).map((check) => check.path))].sort()
+    }));
+  return {
+    status: stale.length === 0 ? 'fresh' : 'stale',
+    checks,
+    stale,
+    byArea,
+    spawnRecommendations
+  };
+}
+
+function routeTemplate(command) {
+  const name = command.replace(/^\//, '');
+  return [
+    'apiVersion: godpowers/v1',
+    'kind: CommandRouting',
+    'metadata:',
+    `  command: ${command}`,
+    '  description: ',
+    '  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]',
+    ''
+  ].join('\n').replace('description: ', `description: Route metadata for /${name}`);
+}
+
+function applySafeFixes(projectRoot, report, opts = {}) {
+  const applied = [];
+  if (!opts.fixRouting) return applied;
+  for (const check of report.stale) {
+    if (check.area !== 'routing' || !check.safeFix || !check.path.startsWith('routing/')) continue;
+    if (exists(projectRoot, check.path)) continue;
+    const command = `/${path.basename(check.path, '.yaml')}`;
+    write(projectRoot, check.path, routeTemplate(command));
+    applied.push({ path: check.path, check: check.id });
+  }
+  return applied;
+}
+
+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 Surface Sync Log');
+    lines.push('');
+    lines.push('- [DECISION] This file records structural repository surface sync checks run by Godpowers.');
+    lines.push('- [DECISION] Detection is read-only by default and safe fixes require explicit fix options.');
+    lines.push('');
+  }
+  lines.push(`## ${now}`);
+  lines.push('');
+  lines.push(`- [DECISION] Repo surface sync status before apply was ${before.status}.`);
+  lines.push(`- [DECISION] Repo surface sync status after apply is ${after.status}.`);
+  if (applied.length === 0) {
+    lines.push('- [DECISION] No structural repository surface files were changed.');
+  } else {
+    for (const item of applied) {
+      lines.push(`- [DECISION] Created or refreshed ${item.path} for ${item.check}.`);
+    }
+  }
+  for (const rec of after.spawnRecommendations) {
+    lines.push(`- [HYPOTHESIS] ${rec.agent} should review ${rec.paths.join(', ')}.`);
+  }
+  lines.push('');
+  write(projectRoot, LOG_PATH, lines.join('\n'));
+}
+
+function run(projectRoot, opts = {}) {
+  const before = detect(projectRoot);
+  const applied = applySafeFixes(projectRoot, before, opts);
+  const after = detect(projectRoot);
+  if (opts.log !== false) appendLog(projectRoot, before, after, applied);
+  return {
+    before,
+    after,
+    applied,
+    logPath: opts.log === false ? null : LOG_PATH
+  };
+}
+
+function summary(report) {
+  if (report.status === 'fresh') return 'fresh';
+  return `${report.stale.length} stale across ${Object.keys(report.byArea).length} areas`;
+}
+
+module.exports = {
+  LOG_PATH,
+  REQUIRED_PACKAGE_CHECKS,
+  REQUIRED_PACKAGE_FILE_ENTRIES,
+  detect,
+  run,
+  summary,
+  routeTemplate
+};

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "godpowers",
-  "version": "1.6.16",
+  "version": "1.6.19",
   "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-repo-surface-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,15 @@ 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`.
+
+Then call `lib/repo-surface-sync.run(projectRoot)` so documentation work sees
+whether route, package, agent, workflow, recipe, extension, or release policy
+surfaces disagree before prose claims are rewritten.
+
 Spawn **god-docs-writer** in fresh context.
 
 The agent:
@@ -56,6 +65,8 @@ 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 |
+| Repo structural surface drift | Run `lib/repo-surface-sync.run` and include findings in docs scope | Do not invent routing or agent ownership prose without evidence |
 | `REVIEW-REQUIRED.md` contains docs drift items | Suggest `/god-review-changes` first | Do not auto-clear review items |
 
 When auto-invoked, show:
@@ -65,6 +76,8 @@ 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>
+    + repo-surface-sync: <structural surface fresh, scoped findings, 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,30 @@ 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.
+
+## Repo Surface Sync
+
+For initialized projects, `/god-doctor` calls `lib/repo-surface-sync.detect`
+as a read-only diagnostic. It reports structural drift across command routing,
+package payload rules, agent spawn targets, workflow metadata, recipe command
+routes, extension packs, and release policy checks.
+
+`/god-doctor --fix` may call
+`lib/repo-surface-sync.run(projectRoot, { fixRouting: true })` to create
+missing routing metadata for shipped slash-command skills. Other structural
+findings should recommend the scoped specialist named by the helper.
+
 ## Implementation
 
 Built-in, no spawned agent. Reads:
@@ -122,6 +146,9 @@ 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
+- `lib/repo-surface-sync.detect(projectRoot)` for structural repo surface
+  freshness
 - `bin/install.js` VERSION constant
 
 ## Exit codes

package/skills/god-mode.md

@@ -306,6 +306,8 @@ 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>
+    + repo-surface-sync: <checked structural surfaces, recommended scoped agents, 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 +326,16 @@ 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.
+
+The mandatory final sync also receives repo surface sync through `/god-sync`.
+This keeps routes, packages, agent handoffs, workflow metadata, recipe routes,
+extension packs, and release policy checks aligned 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 +357,8 @@ 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>
+    + repo-surface-sync: <checked structural surfaces, recommended scoped agents, or no-op>
     + pillars-sync: <counts and result>
     + checkpoint-sync: <created, updated, no-op, or skipped>
     + context-refresh: <spawned, no-op, or skipped>