godpowers 1.6.15 → 1.6.17

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.15",
+  "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-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/schema/state.v1.json

@@ -131,6 +131,32 @@
         "additionalProperties": false
       }
     },
+    "godpowers-features": {
+      "type": "object",
+      "description": "Installed Godpowers feature awareness recorded for this project.",
+      "required": ["feature-set-version", "runtime-version", "known"],
+      "properties": {
+        "feature-set-version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "runtime-version": {
+          "type": "string",
+          "pattern": "^(unknown|\\d+\\.\\d+\\.\\d+)$"
+        },
+        "known": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "last-awareness-refresh-at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "additionalProperties": false
+    },
     "yolo-decisions": {
       "type": "array",
       "description": "Auto-decisions made under --yolo. Mirrored to YOLO-DECISIONS.md.",

package/skills/god-context.md

@@ -33,10 +33,12 @@ the Godpowers fences off, check status, or refresh on demand.
 
 1. Verify `.godpowers/` exists. If not, suggest `/god-init` first.
 2. Read `.godpowers/state.json`.
-3. Call `lib/pillars.detect(projectRoot)`.
-4. If Pillars is absent or partial, call `lib/pillars.init(projectRoot)`.
-5. Spawn `god-context-writer` agent with the requested mode.
-6. Report results.
+3. Call `lib/feature-awareness.run(projectRoot)` to record current runtime
+   features and refresh managed AI-tool awareness safely.
+4. Call `lib/pillars.detect(projectRoot)`.
+5. If Pillars is absent or partial, call `lib/pillars.init(projectRoot)`.
+6. Spawn `god-context-writer` agent with the requested mode.
+7. Report results.
 
 ## What gets written
 
@@ -136,6 +138,14 @@ When `/god-sync` runs (after a project run, or any sync), `god-updater` calls th
 with `refresh` to keep `AGENTS.md` content aligned with the latest project
 state (mode, scale, completed tiers, active artifacts).
 
+For existing projects after a Godpowers upgrade, `/god-context refresh`
+auto-invokes `lib/feature-awareness.run(projectRoot)`. Report it as:
+
+```
+Agent: none, local runtime only
+Why: this path records current runtime features and refreshes managed context fences
+```
+
 You can disable the Godpowers fences by running `/god-context off`. Pillars
 remains because it is the native context contract for Godpowers projects.
 
@@ -146,7 +156,7 @@ The fenced content contains:
 - Mode (greenfield/brownfield/audit) and scale
 - A short list of completed-tier artifact paths
 - Quarterback rule reminder
-- Top 4 useful slash commands
+- Short useful slash command list
 
 It does NOT contain:
 - Secrets, credentials, API keys

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

@@ -32,6 +32,8 @@ Run a system-state diagnostic. Build nothing. Touch nothing. Report only.
 5. Is the reflog (`.godpowers/log`) parseable?
 6. Are there entries in `.godpowers/.trash/`?
 7. Do declared linkage entries point at real code files?
+8. Does `state.json` know the current Godpowers feature set?
+9. Are managed AI-tool context fences present when tools are detected?
 
 ### External integration health
 1. Is impeccable present? `node_modules/impeccable` or `~/.claude/skills/impeccable`?
@@ -53,6 +55,7 @@ Install: claude (~/.claude/)
 
 Project: /Users/.../my-project/.godpowers/
   [OK] state.json valid
+  [WARN] feature awareness stale -> run /god-context refresh
   [WARN] PRD declared but .godpowers/prd/PRD.md missing -> run /god-prd
   [INFO] 2 entries in .trash/; run /god-restore to review
 
@@ -96,12 +99,42 @@ Skip install checks. Useful inside the project.
 ### `/god-doctor --fix`
 Attempt to repair detected issues automatically (only for safe categories: regenerate missing routing YAMLs, repair PROGRESS.md from state.json, etc.). Pauses before any destructive change.
 
+## Feature Awareness
+
+For initialized projects, `/god-doctor` calls `lib/feature-awareness.detect`
+as a read-only diagnostic. It reports:
+- runtime version recorded in `state.json`
+- missing current Godpowers feature IDs
+- missing managed AI-tool context fences
+- unimported GSD, BMAD, or Superpowers evidence that should route to
+  `/god-migrate`
+- `god-greenfieldifier` recommendation when migration evidence is low
+  confidence or conflicting
+
+`/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:
 - `<runtime>/GODPOWERS_VERSION` (compare to package.json)
 - `<runtime>/skills/` and `<runtime>/agents/` listings
 - `.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

@@ -304,7 +304,9 @@ Sync status:
   Trigger: /god-mode final sync
   Agent: god-updater spawned
   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>
@@ -318,6 +320,16 @@ to relevant pillar files through `lib/pillars.planArtifactSync`. Default mode
 proposes pillar updates for review. `--yolo` applies them immediately and logs
 the action to `.godpowers/YOLO-DECISIONS.md`.
 
+When `/god-mode` resumes an existing `.godpowers` project, it auto-invokes
+`lib/feature-awareness.run(projectRoot)` before the final sync report. This
+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.
@@ -337,7 +349,9 @@ Sync status:
   Trigger: /god-mode final sync
   Agent: god-updater spawned
   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