godpowers 1.6.17 → 1.6.20

package/lib/route-quality-sync.js

@@ -0,0 +1,286 @@
+/**
+ * Route quality sync.
+ *
+ * Detects disconnected route automation surfaces: symbolic spawn tokens,
+ * unresolved agent targets, contextual exits without an approved reason, and
+ * composite flows that should be represented as primary plus secondary or
+ * parallel spawns.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseSimpleYaml } = require('./intent');
+
+const LOG_PATH = '.godpowers/surface/ROUTE-QUALITY-SYNC.md';
+
+const CONTEXTUAL_NEXT_ALLOWED = new Set([
+  '/god',
+  '/god-agent-audit',
+  '/god-budget',
+  '/god-cache-clear',
+  '/god-check-todos',
+  '/god-context-scan',
+  '/god-cost',
+  '/god-discuss',
+  '/god-doctor',
+  '/god-extension-add',
+  '/god-extension-info',
+  '/god-extension-list',
+  '/god-extension-remove',
+  '/god-graph',
+  '/god-help',
+  '/god-lifecycle',
+  '/god-list-assumptions',
+  '/god-locate',
+  '/god-logs',
+  '/god-metrics',
+  '/god-next',
+  '/god-redo',
+  '/god-resume-work',
+  '/god-test-extension',
+  '/god-thread',
+  '/god-trace',
+  '/god-workstream'
+]);
+
+const STANDARDS_EXEMPT_COMMANDS = new Set([
+  '/god-archaeology',
+  '/god-audit',
+  '/god-automation-setup',
+  '/god-debug',
+  '/god-discuss',
+  '/god-explore',
+  '/god-feature',
+  '/god-hotfix',
+  '/god-hygiene',
+  '/god-init',
+  '/god-org-context',
+  '/god-party',
+  '/god-pause-work',
+  '/god-preflight',
+  '/god-reconstruct',
+  '/god-roadmap-check',
+  '/god-smite',
+  '/god-tech-debt'
+]);
+
+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 arr(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function parseRoute(projectRoot, routePath) {
+  try {
+    return parseSimpleYaml(read(projectRoot, routePath)) || {};
+  } catch (err) {
+    return {};
+  }
+}
+
+function addCheck(checks, id, status, relPath, message, opts = {}) {
+  checks.push({
+    area: 'route-quality',
+    id,
+    status,
+    path: relPath,
+    message,
+    severity: opts.severity || (status === 'fresh' ? 'info' : 'warning'),
+    spawn: opts.spawn || null
+  });
+}
+
+function spawnTokens(route) {
+  const execution = route.execution || {};
+  return normalizeSpawnList([
+    ...arr(execution.spawns),
+    ...arr(execution['secondary-spawns']),
+    ...arr(execution['parallel-spawns'])
+  ]);
+}
+
+function normalizeSpawnList(tokens) {
+  return tokens
+    .map((token) => {
+      if (token && typeof token === 'object' && token.agent) return token.agent;
+      return token;
+    })
+    .filter((token) => token !== null && token !== undefined);
+}
+
+function isAtomicSpawn(token) {
+  return token === 'built-in' || /^god-[a-z0-9-]+$/.test(token);
+}
+
+function detect(projectRoot) {
+  const checks = [];
+  const routes = listFiles(projectRoot, 'routing', /^god.*\.yaml$/);
+  const agents = new Set(listFiles(projectRoot, 'agents', /^god.*\.md$/)
+    .map((file) => path.basename(file, '.md')));
+  let symbolicCount = 0;
+  let unresolvedCount = 0;
+  let contextualExitCount = 0;
+  let standardsExemptCount = 0;
+
+  for (const routePath of routes) {
+    const route = parseRoute(projectRoot, routePath);
+    const command = route.metadata && route.metadata.command
+      ? route.metadata.command
+      : `/${path.basename(routePath, '.yaml')}`;
+
+    for (const token of spawnTokens(route)) {
+      if (!isAtomicSpawn(String(token))) {
+        symbolicCount++;
+        addCheck(
+          checks,
+          `symbolic-spawn-${command.replace(/[^a-z0-9]+/gi, '-')}`,
+          'stale',
+          routePath,
+          `${command} uses symbolic spawn token ${token}.`,
+          { spawn: 'god-auditor' }
+        );
+        continue;
+      }
+      if (String(token).startsWith('god-') && !agents.has(String(token))) {
+        unresolvedCount++;
+        addCheck(
+          checks,
+          `unresolved-spawn-${command.replace(/[^a-z0-9]+/gi, '-')}-${token}`,
+          'stale',
+          routePath,
+          `${command} references missing agent ${token}.`,
+          { spawn: 'god-auditor' }
+        );
+      }
+    }
+
+    const next = route['success-path'] && route['success-path']['next-recommended'];
+    const conditionalNext = route['success-path'] && arr(route['success-path']['conditional-next']);
+    if (next === 'varies' && conditionalNext.length === 0) {
+      if (CONTEXTUAL_NEXT_ALLOWED.has(command)) {
+        contextualExitCount++;
+      } else {
+        addCheck(
+          checks,
+          `unapproved-varies-${command.replace(/[^a-z0-9]+/gi, '-')}`,
+          'stale',
+          routePath,
+          `${command} uses next-recommended: varies without an approved contextual-exit classification.`,
+          { spawn: 'god-roadmap-reconciler' }
+        );
+      }
+    }
+
+    const writes = arr(route.execution && route.execution.writes);
+    const writesDurableSurface = writes.length > 0;
+    if (writesDurableSurface && !route.standards) {
+      if (STANDARDS_EXEMPT_COMMANDS.has(command)) {
+        standardsExemptCount++;
+      } else {
+        addCheck(
+          checks,
+          `missing-standards-${command.replace(/[^a-z0-9]+/gi, '-')}`,
+          'stale',
+          routePath,
+          `${command} writes durable surfaces but has no standards block or approved exemption.`,
+          { spawn: 'god-auditor' }
+        );
+      }
+    }
+  }
+
+  if (symbolicCount === 0) {
+    addCheck(checks, 'atomic-spawn-tokens', 'fresh', 'routing/', 'All route spawn tokens are atomic.');
+  }
+  if (unresolvedCount === 0) {
+    addCheck(checks, 'resolved-spawn-targets', 'fresh', 'routing/', 'All route spawn targets resolve to shipped agents or built-in runtime work.');
+  }
+  addCheck(
+    checks,
+    'contextual-exit-policy',
+    checks.some((check) => check.id.startsWith('unapproved-varies-')) ? 'stale' : 'fresh',
+    'routing/',
+    `${contextualExitCount} contextual route exits are approved and all other next routes are explicit.`,
+    { spawn: checks.some((check) => check.id.startsWith('unapproved-varies-')) ? 'god-roadmap-reconciler' : null }
+  );
+  addCheck(
+    checks,
+    'standards-policy',
+    checks.some((check) => check.id.startsWith('missing-standards-')) ? 'stale' : 'fresh',
+    'routing/',
+    `${standardsExemptCount} durable-writing routes have approved standards exemptions and all other writing routes declare standards.`,
+    { spawn: checks.some((check) => check.id.startsWith('missing-standards-')) ? 'god-auditor' : null }
+  );
+
+  const stale = checks.filter((check) => check.status !== 'fresh');
+  return {
+    status: stale.length === 0 ? 'fresh' : 'stale',
+    checks,
+    stale
+  };
+}
+
+function appendLog(projectRoot, before, after) {
+  const now = new Date().toISOString();
+  const lines = [];
+  if (fs.existsSync(path.join(projectRoot, LOG_PATH))) {
+    lines.push(read(projectRoot, LOG_PATH).replace(/\s*$/, ''));
+    lines.push('');
+  } else {
+    lines.push('# Route Quality Sync Log');
+    lines.push('');
+    lines.push('- [DECISION] This file records route-quality sync checks run by Godpowers.');
+    lines.push('');
+  }
+  lines.push(`## ${now}`);
+  lines.push('');
+  lines.push(`- [DECISION] Route quality status before apply was ${before.status}.`);
+  lines.push(`- [DECISION] Route quality status after apply is ${after.status}.`);
+  lines.push('');
+  write(projectRoot, LOG_PATH, lines.join('\n'));
+}
+
+function run(projectRoot, opts = {}) {
+  const before = detect(projectRoot);
+  const after = detect(projectRoot);
+  if (opts.log !== false) appendLog(projectRoot, before, after);
+  return {
+    before,
+    after,
+    applied: [],
+    logPath: opts.log === false ? null : LOG_PATH
+  };
+}
+
+function summary(report) {
+  return report.status === 'fresh' ? 'fresh' : `${report.stale.length} stale`;
+}
+
+module.exports = {
+  LOG_PATH,
+  CONTEXTUAL_NEXT_ALLOWED,
+  STANDARDS_EXEMPT_COMMANDS,
+  detect,
+  run,
+  summary
+};

package/lib/router.js

@@ -221,7 +221,10 @@ function getSpawnedAgents(command) {
   if (!routing || !routing.execution) return [];
   const primary = routing.execution.spawns || [];
   const secondary = routing.execution['secondary-spawns'] || [];
-  return [...primary, ...secondary];
+  const parallel = routing.execution['parallel-spawns'] || [];
+  return [...primary, ...secondary, ...parallel]
+    .map(spawn => (spawn && typeof spawn === 'object' && spawn.agent) ? spawn.agent : spawn)
+    .filter(spawn => spawn !== null && spawn !== undefined);
 }
 
 /**

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "godpowers",
-  "version": "1.6.17",
+  "version": "1.6.20",
   "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-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",
+    "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-automation-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-party.yaml

@@ -9,9 +9,11 @@ prerequisites:
   required: []
 
 execution:
-  spawns: [multi]
+  spawns: [built-in]
   context: fresh
-  writes: []
+  parallel-spawns: [god-pm, god-architect, god-executor, god-quality-reviewer, god-harden-auditor, god-launch-strategist]
+  writes:
+    - .godpowers/party/*.md
 
 success-path:
   next-recommended: /god-next

package/routing/god-story-build.yaml

@@ -10,9 +10,18 @@ prerequisites:
     - .godpowers/stories/STORY-*.md
 
 execution:
-  spawns: [god-planner+god-executor+reviewers]
+  spawns: [god-planner]
   context: fresh
-  writes: []
+  secondary-spawns: [god-executor, god-spec-reviewer, god-quality-reviewer]
+  writes:
+    - .godpowers/stories/STORY-*.md
+    - source code
+
+standards:
+  substitution-test: true
+  three-label-test: true
+  have-nots: [B-01, B-02, B-03, B-04, B-05, B-06, B-07, B-08, B-09, B-10, B-11, B-12]
+  gate-on-failure: pause-for-user
 
 success-path:
   next-recommended: /god-story-verify

package/routing/recipes/automation-setup.yaml

@@ -0,0 +1,25 @@
+apiVersion: godpowers/v1
+kind: Recipe
+metadata:
+  name: automation-setup
+  category: maintaining
+  description: "Set up and verify native Godpowers automations"
+
+triggers:
+  intent-keywords:
+    - "create automation"
+    - "set up automation"
+    - "recurring godpowers"
+    - "weekly automation"
+    - "automation status"
+
+sequences:
+  default:
+    description: "Set up and verify native Godpowers automations"
+    steps:
+      - command: "/god-automation-setup"
+        why: "Create approved host-native automation"
+      - command: "/god-automation-status"
+        why: "Confirm configured providers and active templates"
+
+default-sequence: default

package/routing/recipes/context-refresh.yaml

@@ -0,0 +1,26 @@
+apiVersion: godpowers/v1
+kind: Recipe
+metadata:
+  name: context-refresh
+  category: knowledge
+  description: "Refresh agent context after repo, docs, or workflow changes"
+
+triggers:
+  intent-keywords:
+    - "context refresh"
+    - "update agent context"
+    - "make agents aware"
+    - "new godpowers features"
+
+sequences:
+  default:
+    description: "Refresh agent context after repo, docs, or workflow changes"
+    steps:
+      - command: "/god-context"
+        why: "Refresh portable agent context files"
+      - command: "/god-sync"
+        why: "Apply feature-awareness and Pillars sync checks"
+      - command: "/god-status"
+        why: "Confirm proactive checks are fresh"
+
+default-sequence: default

package/routing/recipes/release-maintenance.yaml

@@ -0,0 +1,27 @@
+apiVersion: godpowers/v1
+kind: Recipe
+metadata:
+  name: release-maintenance
+  category: maintaining
+  description: "Release closeout, package, docs, and published-surface maintenance"
+
+triggers:
+  intent-keywords:
+    - "create release"
+    - "publish npm"
+    - "update readme badge"
+    - "release notes"
+    - "package release"
+
+sequences:
+  default:
+    description: "Release closeout, package, docs, and published-surface maintenance"
+    steps:
+      - command: "/god-sync"
+        why: "Refresh project artifacts and repo surface checks before release work"
+      - command: "/god-docs"
+        why: "Verify README, release notes, badges, and public docs against code"
+      - command: "/god-version"
+        why: "Confirm installed runtime and package version visibility"
+
+default-sequence: default

package/routing/recipes/story-work.yaml

@@ -0,0 +1,29 @@
+apiVersion: godpowers/v1
+kind: Recipe
+metadata:
+  name: story-work
+  category: feature-addition
+  description: "Create, build, verify, and close a scoped story"
+
+triggers:
+  intent-keywords:
+    - "create story"
+    - "build story"
+    - "implement story"
+    - "verify story"
+    - "close story"
+
+sequences:
+  default:
+    description: "Create, build, verify, and close a scoped story"
+    steps:
+      - command: "/god-story"
+        why: "Create or select a runtime-testable story"
+      - command: "/god-story-build"
+        why: "Plan and implement the selected story with reviewers"
+      - command: "/god-story-verify"
+        why: "Runtime-test the story acceptance criteria"
+      - command: "/god-story-close"
+        why: "Close the story only after verification passes"
+
+default-sequence: default

package/skills/god-docs.md

@@ -28,6 +28,10 @@ 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:
@@ -62,6 +66,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 |
+| 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:
@@ -72,6 +77,7 @@ Auto-invoked:
   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

@@ -126,6 +126,19 @@ 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, route quality, recipe coverage, release surfaces, 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:
@@ -135,6 +148,14 @@ Built-in, no spawned agent. Reads:
 - `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
+- `lib/route-quality-sync.detect(projectRoot)` through repo surface sync for
+  atomic spawn and contextual route exit freshness
+- `lib/recipe-coverage-sync.detect(projectRoot)` through repo surface sync for
+  high-frequency intent recipe coverage freshness
+- `lib/release-surface-sync.detect(projectRoot)` through repo surface sync for
+  release-facing surface freshness
 - `bin/install.js` VERSION constant
 
 ## Exit codes

package/skills/god-mode.md

@@ -307,6 +307,7 @@ Sync status:
     + 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>
@@ -330,6 +331,11 @@ The mandatory final sync also receives repo documentation sync through
 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.
@@ -352,6 +358,7 @@ Sync status:
     + 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>

package/skills/god-next.md

@@ -25,6 +25,9 @@ Before reading routing data or calling runtime modules, resolve the Godpowers ru
 4. For status output, load `<runtimeRoot>/lib/dashboard.js` and call
    `dashboard.compute(projectRoot)`. Use `dashboard.render(result)` for the
    shared dashboard section before adding route-specific detail.
+5. If the checkout runtime and installed runtime differ, say which runtime root
+   was used. Only call the output a manual disk scan when `lib/dashboard.js`
+   cannot be loaded at all.
 
 ## Three modes of invocation
 
@@ -347,11 +350,13 @@ Godpowers Next
 
 Godpowers Dashboard
 
+Source: runtime dashboard (lib/dashboard.js)
+
 Current status:
   State: proposal
   Phase: [plain-language phase] (tier [human ordinal] of [human total])
   Step: [current step label] (step [n] of [total steps])
-  Progress: [pct]% ([done] of [total] steps complete)
+  Progress: [pct]% workflow progress ([done] of [total] tracked steps complete)
   Worktree: [clean | modified files unstaged | staged changes | mixed]
   Index: [untouched | staged files listed]
 
@@ -359,7 +364,7 @@ Planning visibility:
   PRD: [done | pending | missing | deferred] [path when present]
   Roadmap: [done | pending | missing | deferred] [path when present]
   Current milestone: [roadmap milestone, phase, tier, or next planning gate]
-  Completion: [pct]% [basis from state.json, PROGRESS.md, or artifacts]
+  Completion basis: [state.json, PROGRESS.md, artifacts, or audit score source]
 
 Suggested next: [/god-X]
 

package/skills/god-status.md

@@ -38,9 +38,10 @@ Re-derive state from disk. Your memory is not authoritative. The file system is.
    - If PROGRESS.md says "done" but artifact is missing: FLAG as phantom resume
    - If artifact exists but PROGRESS.md says "pending": FLAG as untracked work
 8. Report the Godpowers Dashboard from `dashboard.render(result)`:
+   - Dashboard source: runtime dashboard or unavailable manual scan
    - Current mode and scale
    - Current phase, tier number, step label, and step number
-   - Progress summary: percentage, completed step count, current step number
+   - Workflow progress summary: percentage, completed step count, current step number
    - Planning visibility: PRD status, roadmap status, active milestone, and
      completion basis
    - What happened recently, using CHECKPOINT.md actions when available
@@ -55,11 +56,16 @@ Re-derive state from disk. Your memory is not authoritative. The file system is.
 If the runtime module is unavailable, fall back to the manual scan below and
 say `Dashboard engine: unavailable, manual scan used`.
 
+Never mix workflow progress with audit, hygiene, or remediation scores. If an
+audit score is relevant, label it separately as `Audit score`.
+
 ## Output Format
 
 ```text
 Godpowers Dashboard
 
+Source: runtime dashboard (lib/dashboard.js)
+
 Mode: A (greenfield)    Scale: medium
 Started: 2026-05-09
 
@@ -67,7 +73,7 @@ Current status:
   State: in progress
   Phase: Planning (tier 2 of 4, internal tier-1)
   Step: Architecture (step 3 of 13)
-  Progress: 15% (2 of 13 steps complete)
+  Progress: 15% workflow progress (2 of 13 tracked steps complete)
   Worktree: clean
   Index: untouched
 
@@ -75,7 +81,7 @@ Planning visibility:
   PRD: done .godpowers/prd/PRD.md
   Roadmap: pending
   Current milestone: Planning / Architecture
-  Completion: 15% based on PROGRESS.md tracked steps
+  Completion basis: .godpowers/state.json workflow steps
 
 What happened recently:
   1. PRD artifact verified on disk
@@ -173,6 +179,8 @@ Report:
 - Sync: `fresh`, `missing`, `stale`, or `suggest /god-sync`
 - Docs: `fresh`, `<N> stale, suggest /god-docs`, `possible drift, suggest
   /god-docs`, or `repo-doc-sync ran`
+- Repo surface: `fresh`, `<N> stale, suggest /god-doctor`, or
+  `repo-surface-sync ran`
 - Runtime: `not-applicable`, `known URL, suggest /god-test-runtime`, or
   `no known URL, defer deployed verification`
 - Automation: `not configured`, `<N> active`, or