godpowers 1.6.14 → 1.6.16

package/lib/source-sync.js

@@ -0,0 +1,220 @@
+/**
+ * Source System Sync-Back
+ *
+ * Writes Godpowers progress back to detected GSD, BMAD, and Superpowers
+ * projects through managed companion files and optional managed fences.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const state = require('./state');
+
+const FENCE_BEGIN = '<!-- godpowers:source-sync:begin -->';
+const FENCE_END = '<!-- godpowers:source-sync:end -->';
+
+const SYSTEM_TARGETS = {
+  gsd: {
+    companionCandidates: ['.planning/GODPOWERS-SYNC.md', '.gsd/GODPOWERS-SYNC.md'],
+    pointerCandidates: ['.planning/STATE.md']
+  },
+  bmad: {
+    companionCandidates: ['_bmad-output/GODPOWERS-SYNC.md', '.bmad/GODPOWERS-SYNC.md'],
+    pointerCandidates: ['_bmad-output/project-context.md']
+  },
+  superpowers: {
+    companionCandidates: ['docs/superpowers/GODPOWERS-SYNC.md', '.superpowers/GODPOWERS-SYNC.md'],
+    pointerCandidates: []
+  }
+};
+
+function rel(projectRoot, absPath) {
+  return path.relative(projectRoot, absPath).split(path.sep).join('/');
+}
+
+function sha(input) {
+  return `sha256:${crypto.createHash('sha256').update(input).digest('hex')}`;
+}
+
+function readFenced(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, before: '', fenced: '', after: '' };
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  const beginIdx = content.indexOf(FENCE_BEGIN);
+  const endIdx = content.indexOf(FENCE_END);
+  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
+    return { exists: true, before: content, fenced: '', after: '' };
+  }
+  return {
+    exists: true,
+    before: content.slice(0, beginIdx),
+    fenced: content.slice(beginIdx + FENCE_BEGIN.length, endIdx),
+    after: content.slice(endIdx + FENCE_END.length)
+  };
+}
+
+function writeFenced(filePath, sectionContent) {
+  const parsed = readFenced(filePath);
+  const block = `${FENCE_BEGIN}\n${sectionContent}\n${FENCE_END}`;
+  let next;
+  if (!parsed.exists) {
+    next = `${block}\n`;
+  } else if (parsed.fenced === '') {
+    const sep = parsed.before.endsWith('\n\n') ? '' : (parsed.before.endsWith('\n') ? '\n' : '\n\n');
+    next = `${parsed.before}${sep}${block}\n`;
+  } else {
+    next = `${parsed.before}${block}${parsed.after}`;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, next);
+  return {
+    written: true,
+    hadFenceBefore: parsed.exists && parsed.fenced !== ''
+  };
+}
+
+function firstExisting(projectRoot, candidates) {
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(projectRoot, candidate))) return candidate;
+  }
+  return candidates[0];
+}
+
+function readArtifact(projectRoot, relPath) {
+  const full = path.join(projectRoot, relPath);
+  if (!fs.existsSync(full)) return null;
+  return fs.readFileSync(full, 'utf8');
+}
+
+function summarizeArtifact(projectRoot, relPath, label) {
+  const content = readArtifact(projectRoot, relPath);
+  if (!content) return `- [HYPOTHESIS] ${label}: missing.`;
+  const headings = content
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => /^#{1,3}\s+/.test(line))
+    .map((line) => line.replace(/^#{1,3}\s+/, ''))
+    .slice(0, 6);
+  if (headings.length === 0) {
+    return `- [HYPOTHESIS] ${label}: present at ${relPath}.`;
+  }
+  return `- [HYPOTHESIS] ${label}: ${headings.join('; ')}. Source: ${relPath}.`;
+}
+
+function progressLines(projectRoot) {
+  const current = state.read(projectRoot);
+  const lines = [];
+  lines.push('# Godpowers Sync-Back');
+  lines.push('');
+  lines.push('- [DECISION] This file is managed by Godpowers source sync.');
+  lines.push('- [DECISION] It lets the prior planning system see current Godpowers progress without Godpowers rewriting source-system documents.');
+  lines.push('- [DECISION] Edit Godpowers artifacts, then run `/god-sync` or `/god-migrate --sync-back` to refresh this file.');
+  lines.push('');
+
+  if (current) {
+    const summary = state.progressSummary(current);
+    lines.push('## Progress');
+    lines.push('');
+    lines.push(`- [HYPOTHESIS] Godpowers progress is ${summary.percent}% with ${summary.completed} of ${summary.total} steps complete.`);
+    if (summary.current) {
+      lines.push(`- [HYPOTHESIS] Current Godpowers step is ${summary.current.tierLabel}: ${summary.current.subStepLabel} with status ${summary.current.status}.`);
+    }
+  }
+
+  lines.push('');
+  lines.push('## Current Godpowers Artifacts');
+  lines.push('');
+  lines.push(summarizeArtifact(projectRoot, '.godpowers/prd/PRD.md', 'PRD'));
+  lines.push(summarizeArtifact(projectRoot, '.godpowers/arch/ARCH.md', 'Architecture'));
+  lines.push(summarizeArtifact(projectRoot, '.godpowers/roadmap/ROADMAP.md', 'Roadmap'));
+  lines.push(summarizeArtifact(projectRoot, '.godpowers/stack/DECISION.md', 'Stack'));
+  lines.push(summarizeArtifact(projectRoot, '.godpowers/build/STATE.md', 'Build state'));
+  lines.push('');
+  lines.push('## Return Path');
+  lines.push('');
+  lines.push('- [DECISION] If the project returns to GSD, BMAD, or Superpowers, use this file as a migration note rather than treating it as a native source-system artifact.');
+  lines.push('- [OPEN QUESTION] Confirm which Godpowers decisions should be copied into native source-system documents before switching systems. Owner: user. Due: before switching systems.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function pointerContent(companionPath) {
+  return [
+    '## Godpowers Sync-Back Pointer',
+    '',
+    `- [DECISION] Current Godpowers progress is summarized in \`${companionPath}\`.`,
+    '- [DECISION] This fenced pointer is managed by Godpowers and may be refreshed by `/god-sync`.',
+    ''
+  ].join('\n');
+}
+
+function updateStateSync(projectRoot, results, contentHash) {
+  const current = state.read(projectRoot);
+  if (!current || !Array.isArray(current['source-systems'])) return null;
+  const now = new Date().toISOString();
+  const byId = new Set(results.map((result) => result.system));
+  current['source-systems'] = current['source-systems'].map((system) => {
+    if (!byId.has(system.id)) return system;
+    return {
+      ...system,
+      'last-sync-back-hash': contentHash,
+      'last-sync-back-at': now
+    };
+  });
+  state.write(projectRoot, current);
+  return current;
+}
+
+function run(projectRoot, opts = {}) {
+  const current = state.read(projectRoot);
+  const configured = current && Array.isArray(current['source-systems'])
+    ? current['source-systems']
+    : [];
+  const systems = configured.filter((system) => system['sync-back-enabled'] !== false);
+  const content = progressLines(projectRoot);
+  const contentHash = sha(content);
+  const results = [];
+
+  for (const system of systems) {
+    const targets = SYSTEM_TARGETS[system.id];
+    if (!targets) continue;
+    const companionRel = firstExisting(projectRoot, targets.companionCandidates);
+    const companionFull = path.join(projectRoot, companionRel);
+    const companionResult = writeFenced(companionFull, content);
+    const pointerResults = [];
+
+    for (const pointerRel of targets.pointerCandidates) {
+      const pointerFull = path.join(projectRoot, pointerRel);
+      if (!fs.existsSync(pointerFull)) continue;
+      const pointerResult = writeFenced(pointerFull, pointerContent(companionRel));
+      pointerResults.push({ path: pointerRel, ...pointerResult });
+    }
+
+    results.push({
+      system: system.id,
+      name: system.name,
+      companion: companionRel,
+      companionWritten: companionResult.written,
+      pointers: pointerResults
+    });
+  }
+
+  const nextState = updateStateSync(projectRoot, results, contentHash);
+  return {
+    hash: contentHash,
+    results,
+    state: nextState
+  };
+}
+
+module.exports = {
+  run,
+  progressLines,
+  readFenced,
+  writeFenced,
+  FENCE_BEGIN,
+  FENCE_END,
+  SYSTEM_TARGETS
+};

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "godpowers",
-  "version": "1.6.14",
-  "description": "AI-powered development system: 108 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.",
+  "version": "1.6.16",
+  "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-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-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-migrate.yaml

@@ -0,0 +1,61 @@
+apiVersion: godpowers/v1
+kind: CommandRouting
+metadata:
+  command: /god-migrate
+  description: Detect and migrate GSD, BMAD, and Superpowers planning context
+  tier: 0
+
+prerequisites:
+  required: []
+  recommended:
+    - command: /god-init
+      when: .godpowers-state-missing
+
+execution:
+  spawns: []
+  context: current
+  reads:
+    - .planning/**
+    - .gsd/**
+    - _bmad-output/**
+    - .bmad/**
+    - docs/superpowers/**
+  writes:
+    - .godpowers/prep/IMPORTED-CONTEXT.md
+    - .godpowers/prd/PRD.md
+    - .godpowers/arch/ARCH.md
+    - .godpowers/roadmap/ROADMAP.md
+    - .godpowers/stack/DECISION.md
+    - .godpowers/build/STATE.md
+    - .godpowers/state.json
+    - .planning/GODPOWERS-SYNC.md
+    - .gsd/GODPOWERS-SYNC.md
+    - _bmad-output/GODPOWERS-SYNC.md
+    - .bmad/GODPOWERS-SYNC.md
+    - docs/superpowers/GODPOWERS-SYNC.md
+  local-runtime:
+    - lib/planning-systems.importPlanningContext
+    - lib/source-sync.run
+  conditional-spawns:
+    - agent: god-greenfieldifier
+      when: low-confidence-or-conflicting-import
+
+standards:
+  gate-on-failure: pause-for-user
+
+success-path:
+  next-recommended: /god-audit
+  alternatives:
+    - command: /god-prd
+      when: imported-prd-seed-needs-hardening
+    - command: /god-roadmap
+      when: imported-roadmap-seed-needs-hardening
+    - command: /god-sync
+      when: user-only-wants-sync-back
+
+failure-path:
+  on-error: /god-doctor
+
+endoff:
+  state-update: source-systems imported and sync-back timestamps updated
+  events: [migration.detected, artifact.imported, source-sync.updated]

package/schema/state.v1.json

@@ -74,6 +74,89 @@
       "description": "Slot for linkage map summary. Authoritative file is .godpowers/linkage.json.",
       "additionalProperties": true
     },
+    "source-systems": {
+      "type": "array",
+      "description": "Detected external planning systems imported into Godpowers and eligible for managed sync-back.",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "confidence", "files", "import-hash"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "enum": ["gsd", "bmad", "superpowers", "other"]
+          },
+          "name": { "type": "string" },
+          "confidence": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          },
+          "markers": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "files": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "import-hash": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          },
+          "imported-at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "sync-back-enabled": {
+            "type": "boolean",
+            "default": true
+          },
+          "last-sync-back-hash": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^sha256:[a-f0-9]{64}$"
+              },
+              { "type": "null" }
+            ]
+          },
+          "last-sync-back-at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "conflict-count": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "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-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`?
@@ -46,13 +48,14 @@ Plain-text report grouped by severity:
 GODPOWERS DOCTOR
 
 Install: claude (~/.claude/)
-  [OK] 108 skills installed
+  [OK] 109 skills installed
   [OK] 40 agents installed
   [OK] VERSION matches (1.6.6)
   [WARN] routing/god-doctor.yaml exists but skill file did not until now
 
 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,29 @@ 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.
+
 ## 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
 - `bin/install.js` VERSION constant
 
 ## Exit codes

package/skills/god-init.md

@@ -44,6 +44,13 @@ needs to specify a mode.
    - If any are detected, summarize useful signals into
      `.godpowers/prep/IMPORTED-CONTEXT.md` as preparation context.
      Do not treat external planning-system files as source of truth.
+   - Auto-invoke `lib/planning-systems.importPlanningContext(projectRoot)`
+     when GSD, Superpowers, or BMAD context is detected. Report this as
+     `Agent: none, local runtime only`.
+   - If import confidence is low, more than one source system appears to
+     conflict, or canonical Godpowers seed artifacts cannot be created from
+     available evidence, spawn `god-greenfieldifier` to produce a controlled
+     migration plan before rewriting any canonical artifact.
    - Detect whether early design preparation is warranted:
      - UI frameworks or app models: React, Next, Vue, Nuxt, Svelte,
        SvelteKit, Astro, Remix, Angular, Solid, Flutter, Electron, Tauri
@@ -109,6 +116,9 @@ needs to specify a mode.
    - Write `.godpowers/prep/INITIAL-FINDINGS.md`
    - Run planning-system context detection for GSD, Superpowers, and BMAD
    - Write `.godpowers/prep/IMPORTED-CONTEXT.md` when useful context exists
+   - Run automatic planning-system import through
+     `lib/planning-systems.importPlanningContext(projectRoot)` and record
+     detected source systems under `state.json` `source-systems`
    - Initialize native Pillars context and record Pillars health in
      `INITIAL-FINDINGS.md`
    - For brownfield: schedule preflight before archaeology + reconstruction

package/skills/god-migrate.md

@@ -0,0 +1,146 @@
+---
+name: god-migrate
+description: |
+  Detect GSD, BMAD, and Superpowers planning systems, migrate useful context
+  into Godpowers prep and seed artifacts, and sync Godpowers progress back to
+  the prior system through managed companion files.
+
+  Triggers on: "god migrate", "/god-migrate", "migrate from gsd",
+  "migrate from bmad", "migrate from superpowers", "sync back to gsd",
+  "sync back to bmad", "sync back to superpowers"
+---
+
+# /god-migrate
+
+Detect and migrate adjacent planning systems into Godpowers.
+
+## When To Use
+
+- A project already has GSD `.planning/` or `.gsd/` context.
+- A project already has BMAD `_bmad/`, `_bmad-output/`, `.bmad-core/`, or
+  `.bmad/` context.
+- A project already has Superpowers specs, plans, or project-local skills.
+- The user wants a reversible migration path into Godpowers.
+- The user wants current Godpowers progress written back to the prior planning
+  system before returning to it.
+
+## Auto-Invoke Contract
+
+`/god-init` auto-invokes the import path when it detects GSD, BMAD, or
+Superpowers context. It must show this visible status card:
+
+```
+Auto-invoked:
+  Trigger: /god-init planning-system detection
+  Agent: none, local runtime only
+  Local syncs:
+    + planning-system-import: <detected systems, written seeds, or no-op>
+  Artifacts: .godpowers/prep/IMPORTED-CONTEXT.md and optional seed artifacts
+```
+
+`/god-sync` auto-invokes sync-back when `state.json` contains enabled
+`source-systems` entries. It must show this visible status card:
+
+```
+Auto-invoked:
+  Trigger: /god-sync source-system sync-back
+  Agent: none, local runtime only
+  Local syncs:
+    + source-sync: <written companion files, pointer fences, or no-op>
+  Artifacts: <.planning/GODPOWERS-SYNC.md, _bmad-output/GODPOWERS-SYNC.md, docs/superpowers/GODPOWERS-SYNC.md>
+```
+
+If the import has low confidence, multiple conflicting systems, or missing
+canonical Godpowers seeds after import, spawn `god-greenfieldifier` with a
+fresh context and this instruction:
+
+```
+This project has imported external planning-system context. Read
+.godpowers/prep/IMPORTED-CONTEXT.md and .godpowers/state.json. Produce a
+controlled migration plan that converts imported hypotheses into Godpowers
+artifacts without overwriting source-system files outside managed fences.
+```
+
+## Runtime Calls
+
+### Import
+
+Call:
+
+```
+lib/planning-systems.importPlanningContext(projectRoot, {
+  syncBackEnabled: true
+})
+```
+
+This:
+- detects GSD, BMAD, and Superpowers sources
+- writes `.godpowers/prep/IMPORTED-CONTEXT.md`
+- writes missing Godpowers seed artifacts when enough source evidence exists
+- marks those seed artifacts as `imported` in `state.json`
+- records detected systems under `state.json` `source-systems`
+
+### Sync-Back
+
+Call:
+
+```
+lib/source-sync.run(projectRoot)
+```
+
+This:
+- reads current Godpowers state and artifacts
+- writes a managed companion file in the prior planning system
+- writes pointer fences only when a safe native state file already exists
+- updates `last-sync-back-hash` and `last-sync-back-at` in `state.json`
+
+## Source Mapping
+
+| Source system | Import evidence | Godpowers destination | Sync-back destination |
+|---|---|---|---|
+| GSD | `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, phase files | prep context, PRD seed, roadmap seed, build-state seed | `.planning/GODPOWERS-SYNC.md` |
+| GSD 2 | `.gsd/` files | prep context and seeds when source files are readable | `.gsd/GODPOWERS-SYNC.md` |
+| BMAD | `_bmad-output/planning-artifacts/PRD.md`, `architecture.md`, epics, stories, sprint status | prep context, PRD seed, arch seed, roadmap seed | `_bmad-output/GODPOWERS-SYNC.md` |
+| Superpowers | `docs/superpowers/specs/*.md`, `docs/superpowers/plans/*.md`, project-local skills | prep context, PRD seed, roadmap seed, build-state seed | `docs/superpowers/GODPOWERS-SYNC.md` |
+
+## Guardrails
+
+- Do not delete, move, or rewrite GSD, BMAD, or Superpowers files.
+- Do not treat imported content as authoritative until a Godpowers artifact or
+  the user confirms it.
+- Do not write outside Godpowers-owned fences in source-system files.
+- Do not overwrite existing Godpowers artifacts unless the user passes
+  `--force` and the command shows a diff or clear file list first.
+- If conflicts appear, pause or spawn `god-greenfieldifier` for a controlled
+  migration plan.
+
+## Output
+
+```
+Migration complete.
+
+Detected:
+  + GSD: high confidence, 12 files
+  + BMAD: not detected
+  + Superpowers: medium confidence, 2 files
+
+Imported:
+  + .godpowers/prep/IMPORTED-CONTEXT.md
+  + .godpowers/prd/PRD.md (imported seed)
+  + .godpowers/roadmap/ROADMAP.md (imported seed)
+
+Sync-back:
+  + .planning/GODPOWERS-SYNC.md
+
+Auto-spawn:
+  + god-greenfieldifier: skipped, import confidence high and no conflicts
+
+Suggested next:
+  /god-audit to score imported seeds before treating them as authoritative.
+```
+
+## Locking
+
+Acquire the state lock with scope `migration.source-systems` before writing
+`.godpowers/prep/IMPORTED-CONTEXT.md`, seed artifacts, source-system companion
+files, or `state.json`.