build(sdk): automate README sync to prevent npm/repo drift (0.11.2)

Adds infrastructure to keep packages/governance/README.md (the file npm
publishes) in sync with the repo-root README:

- scripts/sync-readme.mjs — generates the package README from the root,
  normalizing repo-relative links to absolute GitHub URLs so they resolve
  on npmjs.com. Idempotent.
- prepublishOnly hook runs sync-readme before tsc, guaranteeing every
  npm release ships an in-sync README.
- npm run sync-readme at the monorepo root for manual runs.
- CI guard added to .github/workflows/ci.yml — fails the build if anyone
  commits a manual edit to the package README without running the sync.

No code changes. SDK behavior identical to 0.11.1.

Author: scotty595

.github/workflows/ci.yml

@@ -21,3 +21,11 @@ jobs:
       - run: npm run build
       - run: npm run lint
       - run: npm test
+      - name: Verify packages/governance/README.md is in sync with root README
+        run: |
+          node scripts/sync-readme.mjs
+          git diff --exit-code packages/governance/README.md || (
+            echo "::error::packages/governance/README.md is out of sync with root README.md.";
+            echo "::error::Run 'npm run sync-readme' locally and commit the result.";
+            exit 1
+          )

package.json

@@ -15,7 +15,8 @@
   "scripts": {
     "build": "npm run build -w packages/governance && npm run build -w packages/governance-platform",
     "test": "npm test -w packages/governance && npm test -w packages/governance-platform",
-    "lint": "npm run lint -w packages/governance && npm run lint -w packages/governance-platform"
+    "lint": "npm run lint -w packages/governance && npm run lint -w packages/governance-platform",
+    "sync-readme": "node scripts/sync-readme.mjs"
   },
   "engines": {
     "node": ">=20"

packages/governance/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.11.2] - 2026-04-16 — Automate README sync
+
+Adds infrastructure to prevent the npm README from drifting out of sync
+with the repo-root README again:
+
+- New `scripts/sync-readme.mjs` — generates `packages/governance/README.md`
+  from the root `README.md`, normalizing repo-relative links to absolute
+  GitHub URLs so they resolve on npmjs.com. Idempotent.
+- Wired into `prepublishOnly` so every npm release ships an in-sync README
+  automatically.
+- New `npm run sync-readme` at the monorepo root for manual runs.
+- CI guard added to `.github/workflows/ci.yml` — fails the build if anyone
+  commits a manual edit to the package README without running the sync.
+
+No code changes. SDK behavior identical to 0.11.1.
+
 ## [0.11.1] - 2026-04-16 — Sync npm README with repo
 
 The `packages/governance/README.md` (the file npm publishes) had drifted ~3

packages/governance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "governance-sdk",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "AI Agent Governance for TypeScript — policy enforcement, scoring, compliance, and audit for AI agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -201,7 +201,7 @@
     "dev": "tsc --watch",
     "test": "tsx --test src/*.test.ts src/**/*.test.ts",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "node ../../scripts/sync-readme.mjs && tsc"
   },
   "keywords": [
     "ai-governance",

scripts/sync-readme.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * sync-readme.mjs — Sync packages/governance/README.md from the repo-root README.
+ *
+ * Why: npm publishes the package-local README (the one inside packages/governance/),
+ * not the repo-root one. Without sync, npm users see a stale doc. This script
+ * runs in `prepublishOnly` so every release ships an in-sync README, and is
+ * also enforced in CI to catch drift on PRs.
+ *
+ * Transforms repo-relative links into absolute GitHub URLs so they resolve
+ * correctly when read on npmjs.com (where there's no monorepo context).
+ *
+ * Idempotent — running twice is a no-op.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const REPO = "lua-ai-global/governance";
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const SRC = join(ROOT, "README.md");
+const DST = join(ROOT, "packages", "governance", "README.md");
+
+const root = readFileSync(SRC, "utf8");
+
+// Map repo-relative links → absolute GitHub URLs. Order matters: more
+// specific patterns first so they don't get clobbered by broader ones.
+const transforms = [
+  // Directory references (use /tree/main/)
+  [/\]\(\.\/packages\/governance\)/g, `](https://github.com/${REPO}/tree/main/packages/governance)`],
+  [/\]\(\.\/packages\/governance-platform\)/g, `](https://github.com/${REPO}/tree/main/packages/governance-platform)`],
+  // File references inside packages (use /blob/main/)
+  [/\]\(\.\/packages\/([^)]+)\)/g, `](https://github.com/${REPO}/blob/main/packages/$1)`],
+  // Top-level files
+  [/\]\(\.\/LICENSE\)/g, `](https://github.com/${REPO}/blob/main/LICENSE)`],
+  [/\]\(\.\/CONTRIBUTING\.md\)/g, `](https://github.com/${REPO}/blob/main/CONTRIBUTING.md)`],
+  [/\]\(\.\/SECURITY\.md\)/g, `](https://github.com/${REPO}/blob/main/SECURITY.md)`],
+  [/\]\(\.\/CODE_OF_CONDUCT\.md\)/g, `](https://github.com/${REPO}/blob/main/CODE_OF_CONDUCT.md)`],
+];
+
+let synced = root;
+for (const [pattern, replacement] of transforms) {
+  synced = synced.replace(pattern, replacement);
+}
+
+// Sanity check: any remaining `](./` link is suspicious — flag but don't fail.
+const stragglers = synced.match(/\]\(\.\/[^)]+\)/g);
+if (stragglers) {
+  console.warn(`[sync-readme] WARNING: ${stragglers.length} relative link(s) remain unconverted:`);
+  for (const s of stragglers) console.warn(`  ${s}`);
+  console.warn("[sync-readme] Add a transform rule in scripts/sync-readme.mjs if these should be absolute.");
+}
+
+writeFileSync(DST, synced);
+console.log(`[sync-readme] Wrote ${synced.length} bytes to packages/governance/README.md`);