godpowers 1.6.15 → 1.6.17

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to Godpowers will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.17] - 2026-05-16
+
+Autonomous repository documentation sync.
+
+### Added
+- Added `lib/repo-doc-sync.js` to detect and refresh mechanical repository
+  documentation claims.
+- Added `docs/repo-doc-sync.md` with auto-invoke, auto-spawn, Pillars, and
+  arc-ready closeout behavior.
+- Added behavioral tests for stale repo docs detection, safe mechanical sync,
+  sync logging, Pillars planning, and adjacent autonomous sync recommendations.
+- Added missing `/god-export-otel` routing metadata.
+
+### Changed
+- `/god-sync`, `/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` now
+  document repo documentation sync behavior.
+- The dashboard proactive docs check now uses `lib/repo-doc-sync.detect`.
+- Package contents checks now require `lib/repo-doc-sync.js` and
+  `routing/god-export-otel.yaml`.
+- Release and contribution docs now describe repo documentation sync as part of
+  release readiness.
+
+### Guardrails
+- Detection is read-only by default.
+- Safe apply is limited to mechanical version, badge, and count claims.
+- Narrative changelog, release, contribution, support, and security policy
+  changes route to `god-docs-writer` or the maintainer.
+
+## [1.6.16] - 2026-05-16
+
+Feature awareness for existing Godpowers projects.
+
+### Added
+- Added `lib/feature-awareness.js` to detect stale project awareness after a
+  Godpowers runtime upgrade.
+- Added state recording for the current Godpowers feature set so existing
+  projects can tell whether their context has learned about new capabilities.
+- Added behavioral tests for feature-awareness detection, safe state refresh,
+  AI-tool context refresh, migration suggestions, and `god-greenfieldifier`
+  escalation.
+
+### Changed
+- `AGENTS.md` context refresh now advertises `/god-sync`, `/god-migrate`, and
+  `/god-context refresh` so AI tools opening an existing project see the new
+  migration and awareness commands.
+- `/god-doctor`, `/god-context`, `/god-sync`, and `/god-mode` now document the
+  feature-awareness auto-invoke path for existing `.godpowers` projects.
+- `state.v1.json` now accepts the `godpowers-features` awareness record.
+
+### Guardrails
+- Detection is read-only by default.
+- The apply path writes only safe state metadata and managed context fences.
+- Ambiguous planning-system evidence is reported as a scoped
+  `god-greenfieldifier` recommendation instead of being converted blindly.
+
 ## [1.6.15] - 2026-05-16
 
 Planning-system migration and sync-back.

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-1.6.15-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.6.17-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -12,13 +12,11 @@ idea to hardened production. It runs as **slash commands inside your AI coding
 tool** (Claude Code, Codex, Cursor, etc.) that orchestrate **specialist agents**
 in fresh contexts to do the work.
 
-Version 1.6.15 adds planning-system migration for teams arriving from GSD,
-BMAD, or Superpowers. `/god-init` now auto-detects those systems, imports
-useful context into Godpowers prep and seed artifacts, and records source
-systems in `state.json`. `/god-sync` now syncs current Godpowers progress back
-to managed companion files so teams can return to the prior system with a clear
-handoff trail. Ambiguous imports can auto-spawn `god-greenfieldifier` for a
-controlled migration plan.
+Version 1.6.17 adds autonomous repository documentation sync. `/god-sync`,
+`/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` can now detect stale
+README badges, public surface counts, release docs, contribution guidance,
+security policy, and Pillars context planning needs before a project run is
+declared complete.
 
 It fuses four disciplines into one unified workflow:
 
@@ -228,6 +226,16 @@ managed sync-back files such as `.planning/GODPOWERS-SYNC.md`,
 `_bmad-output/GODPOWERS-SYNC.md`, or
 `docs/superpowers/GODPOWERS-SYNC.md`.
 
+Existing Godpowers projects can refresh their awareness after an upgrade:
+
+```bash
+/god-context refresh
+```
+
+This records the current Godpowers feature set in `.godpowers/state.json`,
+refreshes managed AI-tool context fences, and suggests `/god-migrate` or
+`god-greenfieldifier` when source-system evidence needs migration judgment.
+
 For existing codebases and org-constrained new projects, God Mode now runs a
 greenfield simulation audit and then actions it through a greenfieldification
 plan. It pauses before risky artifact rewrites because that process can change
@@ -351,8 +359,10 @@ Pi. T3 Code inherits from the underlying agent (Codex / Claude / OpenCode).
 - [Getting Started](docs/getting-started.md)
 - [Concepts](docs/concepts.md)
 - [Command reference (all 109 skills + 40 agents)](docs/reference.md)
+- [Feature awareness](docs/feature-awareness.md)
+- [Repository documentation sync](docs/repo-doc-sync.md)
 - [Roadmap](docs/ROADMAP.md)
-- [1.5 Release Notes](RELEASE.md)
+- [Release Notes](RELEASE.md)
 - [Changelog](CHANGELOG.md)
 - [Inspiration](INSPIRATION.md)
 

package/RELEASE.md

@@ -1,10 +1,12 @@
-# Godpowers 1.6.15 Release
+# Godpowers 1.6.17 Release
 
 Date: 2026-05-16
 
-Godpowers 1.6.15 adds automatic migration from GSD, BMAD, and Superpowers
-projects into Godpowers. The release also adds managed sync-back so a team can
-return to its prior planning system with current Godpowers progress visible.
+Godpowers 1.6.17 adds autonomous repository documentation sync for release
+surfaces and project-run closeout. Godpowers can now detect stale README badges,
+public surface counts, release notes, changelog entries, contribution guidance,
+security policy, and Pillars context planning needs before a sync, docs, doctor,
+status, or god-mode closeout declares the repository current.
 
 ## What is stable
 
@@ -20,74 +22,60 @@ return to its prior planning system with current Godpowers progress visible.
 - `.godpowers/` workflow state and artifact layout
 - Safe-sync routing before deploy, observe, harden, launch, or god-mode work
 - Critical harden finding gate before launch
-- GSD-style proposition closeouts for exploratory, diagnostic, audit,
-  lifecycle, status, reconciliation, and decision-support outputs
-- Plain-language project-run wording in user-facing reports
+- Planning-system migration for GSD, BMAD, and Superpowers
+- Managed sync-back companion files for imported source systems
+- Feature awareness for existing Godpowers projects
 
 ## What is new
 
-- Added `lib/planning-systems.js` for GSD, BMAD, and Superpowers detection.
-- Added `lib/source-sync.js` for managed sync-back companion files.
-- Added `/god-migrate` as the explicit migration command.
-- `/god-init` now auto-invokes planning-system import when source systems are
-  detected.
-- `/god-sync` now auto-invokes source-system sync-back when enabled source
-  systems are recorded in `state.json`.
-- `reverse-sync` now returns source-system sync-back results.
-- `state.v1.json` now records source-system import and sync-back state.
-- Added `docs/planning-system-migration.md`.
+- Added `lib/repo-doc-sync.js`.
+- Added `docs/repo-doc-sync.md`.
+- Added `scripts/test-repo-doc-sync.js`.
+- Added missing `/god-export-otel` routing metadata.
+- `/god-sync`, `/god-docs`, `/god-doctor`, `/god-status`, and `/god-mode` now
+  document repo documentation sync integration.
+- The dashboard proactive docs check now reads repo documentation sync status.
+- Package contents checks now require the repo documentation sync helper and
+  `/god-export-otel` routing metadata.
 
-## Migration behavior
+## Sync behavior
 
-Godpowers detects:
+For a Godpowers repository, the helper:
 
-- GSD: `.planning/`, `.gsd/`, `GSD.md`, and `gsd*.md`
-- BMAD: `_bmad/`, `_bmad-output/`, `.bmad-core/`, `.bmad/`, and `BMAD.md`
-- Superpowers: `docs/superpowers/`, `.superpowers/`, `SUPERPOWERS.md`, and
-  project-local skills
+- reads package version and repository surface counts
+- detects stale mechanical claims in README, user docs, architecture docs,
+  roadmap docs, command reference docs, `/god-version`, and `/god-doctor`
+- applies safe mechanical badge, version, and count refreshes when requested
+- plans Pillars sync for changed repo documentation paths
+- recommends `god-docs-writer` for release notes, changelog, contribution,
+  support, or security policy prose
 
-Imported context is written to `.godpowers/prep/IMPORTED-CONTEXT.md`.
-Missing Godpowers seed artifacts are created only when source evidence exists.
-Existing Godpowers artifacts are preserved unless the user explicitly forces an
-overwrite.
-
-## Sync-back behavior
-
-Godpowers writes managed companion files:
-
-- GSD: `.planning/GODPOWERS-SYNC.md` or `.gsd/GODPOWERS-SYNC.md`
-- BMAD: `_bmad-output/GODPOWERS-SYNC.md` or `.bmad/GODPOWERS-SYNC.md`
-- Superpowers: `docs/superpowers/GODPOWERS-SYNC.md` or
-  `.superpowers/GODPOWERS-SYNC.md`
-
-Pointer fences are written only when a safe native state file already exists.
-Godpowers never rewrites source-system prose outside managed fences.
+Detection is read-only by default. Applying sync does not invent narrative
+release notes, changelog entries, contribution policy, support policy, or
+security support policy.
 
 ## Auto-invoke and auto-spawn policy
 
-The import path is local runtime work and must be reported as:
+Safe repo documentation sync is local runtime work and must be reported as:
 
-```
+```text
 Agent: none, local runtime only
 ```
 
-The sync-back path is also local runtime work and must be reported the same
-way.
-
-Godpowers spawns `god-greenfieldifier` only when import confidence is low,
-multiple source systems conflict, or canonical seed artifacts cannot be safely
-created from available evidence.
+Godpowers recommends or spawns `god-docs-writer` only when narrative docs need
+claim verification or policy judgment after local mechanical sync has finished.
 
 ## Validation
 
 Release validation includes:
 
+- `node scripts/test-repo-doc-sync.js`
+- `node scripts/test-feature-awareness.js`
+- `node scripts/test-context-writer.js`
 - `node scripts/test-planning-systems.js`
-- `node scripts/test-reverse-sync.js`
-- `npm test`
-- `npm run test:audit`
-- `node scripts/check-package-contents.js`
+- `node scripts/test-doc-surface-counts.js`
+- `node scripts/validate-skills.js`
 - `git diff --check`
 
-The `v1.6.15` git tag points to the release commit that matches the npm
-`godpowers@1.6.15` package.
+The `v1.6.17` tag should point to the release commit that matches the npm
+`godpowers@1.6.17` package.

package/SKILL.md

@@ -154,7 +154,7 @@ Proactive checks:
   Checkpoint: <fresh | refreshed | missing | stale | conflicts with state.json>
   Reviews: <none | N pending, suggest /god-review-changes>
   Sync: <fresh | missing | stale | local helper ran | suggest /god-sync>
-  Docs: <fresh | possible drift, suggest /god-docs>
+  Docs: <fresh | N stale, suggest /god-docs | repo-doc-sync ran>
   Runtime: <not-applicable | known URL, suggest /god-test-runtime | no known URL, defer deployed verification>
   Automation: <not configured | N active | available via provider, suggest /god-automation-setup>
   Security: <clear | sensitive files changed, suggest /god-harden>
@@ -214,7 +214,7 @@ Auto-invoked:
   Trigger: <what caused this automatic step>
   Agent: <god-updater | god-context-writer | none, local runtime only>
   Local syncs:
-    + <planning-system-import | reverse-sync | source-sync | pillars-sync | checkpoint-sync | context-refresh>: <result or skipped reason>
+    + <feature-awareness | planning-system-import | reverse-sync | source-sync | repo-doc-sync | pillars-sync | checkpoint-sync | context-refresh>: <result or skipped reason>
   Artifacts: <changed files, no-op, or deferred>
   Log: <SYNC-LOG.md, CHECKPOINT.md, REVIEW-REQUIRED.md, or none>
 ```
@@ -240,6 +240,10 @@ Automatic steps that especially need visible reporting:
   `/god-automation-status`, and `/god-automation-setup`
 - planning-system import during `/god-init` or `/god-migrate`
 - source-system sync-back during `/god-sync`, `/god-scan`, or `/god-migrate`
+- feature-awareness refresh during `/god-doctor`, `/god-context`,
+  `/god-sync`, or `/god-mode`
+- repo documentation sync during `/god-sync`, `/god-docs`, `/god-doctor`,
+  `/god-status`, or `/god-mode`
 
 ### 13. Proactive Auto-Invoke Policy
 Godpowers should be proactive from disk evidence, not from guesswork. Before
@@ -272,6 +276,14 @@ Run these local runtime helpers automatically when their trigger is present:
   `/god-migrate`.
 - `lib/source-sync.run` when `state.json` records enabled `source-systems`
   entries and `/god-sync`, `/god-scan`, or `/god-migrate` closes a workflow.
+- `lib/feature-awareness.detect` during `/god-doctor` and
+  `lib/feature-awareness.run` during `/god-context`, `/god-sync`, or
+  `/god-mode` when an initialized `.godpowers` project lacks current runtime
+  feature metadata or managed AI-tool context fences.
+- `lib/repo-doc-sync.detect` during `/god-status` and `/god-doctor`, and
+  `lib/repo-doc-sync.run` during `/god-sync`, `/god-docs`, or `/god-mode`
+  when README badges, public surface counts, release docs, contribution docs,
+  or security policy may have drifted.
 - Context refresh dry-run after `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`,
   `.cursor/rules/`, `.windsurfrules`, `.github/copilot-instructions.md`,
   `.clinerules`, `.roo/`, or `.continue/` changes.
@@ -285,6 +297,9 @@ Spawn these agents only when the trigger is direct and scope is bounded:
   artifacts.
 - `god-docs-writer` in drift-check mode when docs changed after code changed,
   or code changed after docs that claim current behavior.
+- `god-docs-writer` when repo-doc-sync reports narrative drift in
+  `CHANGELOG.md`, `RELEASE.md`, `CONTRIBUTING.md`, `SECURITY.md`, or
+  `SUPPORT.md` after local mechanical sync has finished.
 - `god-browser-tester` when frontend-visible files changed and a known local,
   preview, staging, or production URL is evidenced.
 - `god-harden-auditor` suggestion after security-sensitive files changed;
@@ -299,6 +314,8 @@ Spawn these agents only when the trigger is direct and scope is bounded:
 - `god-greenfieldifier` when imported GSD, BMAD, or Superpowers context has
   low confidence, conflicting systems, or missing canonical Godpowers seed
   artifacts after local import.
+- `god-greenfieldifier` when feature-awareness detects unimported or imported
+  source-system context that is low confidence or conflicting.
 
 #### Level 4: Explicit approval required
 Never auto-run these from inference alone:

package/lib/README.md

@@ -12,6 +12,8 @@ package-level integrations.
 | `state-lock.js` | Coordinate state writes with a lock file. |
 | `intent.js` | Read and validate `intent.yaml` from project roots or `.godpowers/`. |
 | `checkpoint.js` | Create and inspect resumable checkpoint artifacts. |
+| `feature-awareness.js` | Detect and refresh existing-project awareness after runtime upgrades. |
+| `repo-doc-sync.js` | Detect and refresh mechanical repository documentation surfaces. |
 | `budget.js` | Read and enforce configured budget controls. |
 | `cost-tracker.js` | Track token and cost estimates from event streams. |
 
@@ -52,6 +54,8 @@ package-level integrations.
 |--------|---------|
 | `context-writer.js` | Produce tool-specific context files. |
 | `context-budget.js` | Keep generated context within budget. |
+| `planning-systems.js` | Detect and import GSD, BMAD, and Superpowers planning context. |
+| `source-sync.js` | Write managed Godpowers progress back to source-system companion files. |
 | `design-detector.js` | Detect design-system conventions. |
 | `design-spec.js` | Normalize design specifications. |
 | `awesome-design.js` | Validate design guidance against awesome-design rules. |

package/lib/context-writer.js

@@ -97,11 +97,10 @@ function buildCanonicalContent(state, opts = {}) {
   lines.push('');
   lines.push('- `/god-status` - re-derive state from disk');
   lines.push('- `/god-next` - what to run next, with reason');
-  lines.push('- `/god <free text>` - match intent to a recipe');
   lines.push('- `/god-mode` - run the full autonomous project run');
-  lines.push('- `/god-lint` - validate artifacts against have-nots');
-  lines.push('- `/god-scan` - rebuild linkage map from code');
-  lines.push('- `/god-review-changes` - walk REVIEW-REQUIRED.md');
+  lines.push('- `/god-sync` - refresh artifacts, context, and source-system sync-back');
+  lines.push('- `/god-migrate` - import or sync GSD, BMAD, or Superpowers context');
+  lines.push('- `/god-context refresh` - refresh AI-tool awareness for this project');
   lines.push('');
 
   // Pointers to design and product files when present

package/lib/dashboard.js

@@ -12,6 +12,7 @@ const cp = require('child_process');
 const state = require('./state');
 const router = require('./router');
 const automationProviders = require('./automation-providers');
+const repoDocSync = require('./repo-doc-sync');
 
 const GOD_DIR = '.godpowers';
 const PRD_PATH = '.godpowers/prd/PRD.md';
@@ -158,12 +159,16 @@ function proactiveChecks(projectRoot, changedFiles = []) {
     'auth',
     'security'
   ]));
+  const repoDocs = repoDocSync.detect(projectRoot, { changedFiles });
+  const repoDocsStatus = repoDocs.status === 'fresh'
+    ? 'fresh'
+    : `${repoDocs.stale.length} stale, suggest /god-docs`;
 
   return {
     checkpoint,
     reviews: reviews > 0 ? `${reviews} pending, suggest /god-review-changes` : 'none',
     sync,
-    docs: 'fresh',
+    docs: repoDocsStatus,
     runtime: 'not-applicable',
     automation: automationSummary(projectRoot),
     security: sensitiveChanged ? 'sensitive files changed, suggest /god-harden' : 'clear',

package/lib/feature-awareness.js

@@ -0,0 +1,226 @@
+/**
+ * Godpowers Feature Awareness
+ *
+ * Keeps existing Godpowers projects aware of capabilities added by newer
+ * installed runtimes. This module is deliberately conservative: detect is
+ * read-only, run applies only safe state and context refreshes, and ambiguous
+ * migration cases are returned as spawn recommendations.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const state = require('./state');
+const contextWriter = require('./context-writer');
+const planningSystems = require('./planning-systems');
+
+const FEATURE_SET_VERSION = 1;
+
+const FEATURES = [
+  {
+    id: 'planning-system-migration',
+    since: '1.6.15',
+    commands: ['/god-migrate', '/god-init'],
+    description: 'Detect and import GSD, BMAD, and Superpowers planning artifacts.'
+  },
+  {
+    id: 'source-system-sync-back',
+    since: '1.6.15',
+    commands: ['/god-sync', '/god-migrate'],
+    description: 'Write managed Godpowers progress summaries back to detected source systems.'
+  },
+  {
+    id: 'feature-awareness',
+    since: '1.6.16',
+    commands: ['/god-doctor', '/god-context', '/god-sync', '/god-mode'],
+    description: 'Refresh existing Godpowers projects when the installed runtime gains new capabilities.'
+  },
+  {
+    id: 'repo-documentation-sync',
+    since: '1.6.17',
+    commands: ['/god-sync', '/god-docs', '/god-doctor', '/god-status', '/god-mode'],
+    description: 'Detect and refresh repository documentation surfaces, release docs, and Pillars planning signals.'
+  }
+];
+
+function packageVersion(projectRoot) {
+  const candidates = [
+    path.join(__dirname, '..', 'package.json'),
+    path.join(projectRoot || process.cwd(), 'package.json')
+  ];
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      if (parsed && parsed.name === 'godpowers' && parsed.version) return parsed.version;
+    } catch (err) {
+      // Ignore malformed package metadata. Awareness can still run with unknown.
+    }
+  }
+  return 'unknown';
+}
+
+function expectedFeatureIds() {
+  return FEATURES.map((feature) => feature.id);
+}
+
+function existingFeatureIds(current) {
+  const record = current && current['godpowers-features'];
+  return Array.isArray(record && record.known) ? record.known : [];
+}
+
+function missingFeatureIds(current) {
+  const known = new Set(existingFeatureIds(current));
+  return expectedFeatureIds().filter((id) => !known.has(id));
+}
+
+function sourceSystemsNeedJudgment(current) {
+  const systems = Array.isArray(current && current['source-systems'])
+    ? current['source-systems']
+    : [];
+  return systems.filter((system) => {
+    return system.confidence === 'low' || Number(system['conflict-count'] || 0) > 0;
+  });
+}
+
+function missingContextTargets(projectRoot) {
+  const status = contextWriter.status(projectRoot);
+  const missing = [];
+  if (!status.canonical.hasFence) missing.push('AGENTS.md');
+  for (const pointer of status.pointers) {
+    if (!pointer.hasFence) {
+      missing.push(path.relative(projectRoot, pointer.path).split(path.sep).join('/'));
+    }
+  }
+  return missing;
+}
+
+function detect(projectRoot, opts = {}) {
+  const current = state.read(projectRoot);
+  const runtimeVersion = opts.runtimeVersion || packageVersion(projectRoot);
+  if (!current) {
+    return {
+      initialized: false,
+      runtimeVersion,
+      actions: [],
+      missingFeatures: expectedFeatureIds(),
+      missingContext: [],
+      migrationCandidates: [],
+      spawnRecommendation: null
+    };
+  }
+
+  const record = current['godpowers-features'] || {};
+  const missingFeatures = missingFeatureIds(current);
+  const missingContext = missingContextTargets(projectRoot);
+  const migrationCandidates = planningSystems.detect(projectRoot).systems
+    .filter((system) => {
+      const configured = Array.isArray(current['source-systems'])
+        ? current['source-systems']
+        : [];
+      return !configured.some((entry) => entry.id === system.id);
+    })
+    .map((system) => ({
+      id: system.id,
+      name: system.name,
+      confidence: system.confidence,
+      files: system.files.length
+    }));
+
+  const actions = [];
+  if (record['runtime-version'] !== runtimeVersion) actions.push('record-runtime-version');
+  if (missingFeatures.length > 0) actions.push('record-feature-set');
+  if (missingContext.length > 0) actions.push('refresh-context');
+  if (migrationCandidates.length > 0) actions.push('suggest-god-migrate');
+
+  const needsJudgment = sourceSystemsNeedJudgment(current);
+  const lowConfidenceCandidates = migrationCandidates.filter((system) => system.confidence === 'low');
+  const spawnRecommendation = needsJudgment.length > 0 || lowConfidenceCandidates.length > 0
+    ? {
+        agent: 'god-greenfieldifier',
+        reason: 'Imported or detected planning-system context needs migration judgment.',
+        systems: [...needsJudgment.map((system) => system.id), ...lowConfidenceCandidates.map((system) => system.id)]
+      }
+    : null;
+
+  return {
+    initialized: true,
+    runtimeVersion,
+    featureSetVersion: FEATURE_SET_VERSION,
+    actions,
+    currentFeatures: existingFeatureIds(current),
+    expectedFeatures: FEATURES,
+    missingFeatures,
+    missingContext,
+    migrationCandidates,
+    spawnRecommendation
+  };
+}
+
+function buildFeatureRecord(runtimeVersion, now) {
+  return {
+    'feature-set-version': FEATURE_SET_VERSION,
+    'runtime-version': runtimeVersion,
+    known: expectedFeatureIds(),
+    'last-awareness-refresh-at': now
+  };
+}
+
+function sameFeatureRecord(existing, next) {
+  if (!existing) return false;
+  return existing['feature-set-version'] === next['feature-set-version']
+    && existing['runtime-version'] === next['runtime-version']
+    && JSON.stringify(existing.known || []) === JSON.stringify(next.known || []);
+}
+
+function applyStateAwareness(projectRoot, current, runtimeVersion, now) {
+  const nextRecord = buildFeatureRecord(runtimeVersion, now);
+  if (sameFeatureRecord(current['godpowers-features'], nextRecord)) {
+    return { written: false, record: current['godpowers-features'] };
+  }
+  const nextState = {
+    ...current,
+    'godpowers-features': nextRecord
+  };
+  state.write(projectRoot, nextState);
+  return { written: true, record: nextRecord };
+}
+
+function run(projectRoot, opts = {}) {
+  const before = detect(projectRoot, opts);
+  if (!before.initialized) {
+    return {
+      ...before,
+      applied: false,
+      stateWritten: false,
+      contextResults: [],
+      reason: '.godpowers/state.json not found'
+    };
+  }
+
+  const current = state.read(projectRoot);
+  const now = opts.now || new Date().toISOString();
+  const stateResult = applyStateAwareness(projectRoot, current, before.runtimeVersion, now);
+  const refreshedState = state.read(projectRoot);
+  const shouldRefreshContext = opts.refreshContext !== false;
+  const contextResults = shouldRefreshContext
+    ? contextWriter.apply(projectRoot, refreshedState, { projectRoot })
+    : [];
+  const after = detect(projectRoot, opts);
+
+  return {
+    ...after,
+    applied: true,
+    stateWritten: stateResult.written,
+    contextResults,
+    stateRecord: stateResult.record
+  };
+}
+
+module.exports = {
+  FEATURE_SET_VERSION,
+  FEATURES,
+  packageVersion,
+  detect,
+  run
+};

package/lib/pillars.js

@@ -80,6 +80,15 @@ const KNOWN_PILLARS = {
 };
 
 const ARTIFACT_PILLAR_MAP = [
+  { pattern: /^README\.md$/i, pillars: ['context', 'repo'] },
+  { pattern: /^CHANGELOG\.md$/i, pillars: ['context', 'deploy'] },
+  { pattern: /^RELEASE\.md$/i, pillars: ['context', 'deploy'] },
+  { pattern: /^CONTRIBUTING\.md$/i, pillars: ['repo', 'quality'] },
+  { pattern: /^SECURITY\.md$/i, pillars: ['security'] },
+  { pattern: /^SUPPORT\.md$/i, pillars: ['context'] },
+  { pattern: /^docs\/ROADMAP\.md$/i, pillars: ['context', 'quality'] },
+  { pattern: /^docs\/reference\.md$/i, pillars: ['repo'] },
+  { pattern: /^docs\/repo-doc-sync\.md$/i, pillars: ['repo', 'quality'] },
   { pattern: /(^|\/)prd\/PRD\.md$/i, pillars: ['context'] },
   { pattern: /(^|\/)arch\/ARCH\.md$/i, pillars: ['arch'] },
   { pattern: /(^|\/)arch\/adr\//i, pillars: ['arch'] },