feat(repo): Automate repo hygiene and release sync

Unify main-branch maintenance around repo-state and release-state commands so generated docs, contributor acknowledgements, tracked web assets, and canonical artifacts stay aligned across CI and scheduled hygiene runs.

Harden release publication by reusing deterministic sync commands, adding package dry-run verification, and covering the new workflow contract with regression tests.

.github/MAINTENANCE.md

@@ -84,7 +84,8 @@ Before ANY commit that adds/modifies skills, run the chain:
     ```bash
     npm run sync:repo-state
     ```
-    This wraps `chain + catalog + sync:contributors + audit:consistency` for a full local repo-state refresh.
+    This wraps `chain + catalog + sync:web-assets + sync:contributors + audit:consistency` for a full local repo-state refresh.
+    The scheduled GitHub Actions workflow `Repo Hygiene` runs this same sweep weekly to catch slow drift on `main`.
 
     When you need the live GitHub repo metadata updated too, run:
 
@@ -305,6 +306,7 @@ Preflight verification → Changelog → `npm run release:prepare -- X.Y.Z` →
     ```bash
     npm run release:preflight
     ```
+    This now runs the deterministic `sync:release-state` path, refreshes tracked web assets, executes the local test suite, runs the web-app build, and performs `npm pack --dry-run --json` before a release is considered healthy.
     Optional diagnostic pass:
     ```bash
     npm run validate:strict
@@ -326,6 +328,7 @@ Preflight verification → Changelog → `npm run release:prepare -- X.Y.Z` →
     ```
 
     **Important:** The release tag must match `package.json`'s version. The [Publish to npm](workflows/publish-npm.yml) workflow runs on **Release published** and will run `npm publish`; npm rejects republishing the same version.
+    Before publishing, that workflow re-runs `sync:release-state`, checks for canonical drift with `git diff --exit-code`, runs tests/docs security/web build, and performs `npm pack --dry-run --json`.
 
     _Or create the release manually via GitHub UI > Releases > Draft a new release, then publish._
 

.github/workflows/ci.yml

@@ -174,6 +174,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+    env:
+      GH_TOKEN: ${{ github.token }}
     steps:
       - uses: actions/checkout@v4
 
@@ -202,17 +204,11 @@ jobs:
           test -f README.md
           test -f CONTRIBUTING.md
 
-      - name: Validate skills
-        run: npm run validate
-
       - name: Validate references
         run: npm run validate:references
 
-      - name: Generate index
-        run: npm run index
-
-      - name: Update README
-        run: npm run readme
+      - name: Run repo-state sync
+        run: npm run sync:repo-state
 
       - name: Audit npm dependencies
         run: npm audit --audit-level=high
@@ -226,9 +222,6 @@ jobs:
       - name: Run docs security checks
         run: npm run security:docs
 
-      - name: Build catalog
-        run: npm run catalog
-
       - name: Set up GitHub credentials
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: |
@@ -243,12 +236,12 @@ jobs:
 
           git diff --quiet && exit 0
 
-          git pull origin main --rebase || true
           git add $managed_files || true
 
           git diff --cached --quiet && exit 0
 
-          git commit -m "chore: sync generated registry files [ci skip]"
+          git commit -m "chore: sync repo state [ci skip]"
+          git pull origin main --rebase
           git push origin HEAD
 
       - name: Check for uncommitted drift
@@ -260,8 +253,7 @@ jobs:
             echo "Main must be self-healing after the auto-sync step."
             echo "To fix locally, run the canonical maintainer flow:"
             echo "  npm run release:preflight"
-            echo "  npm run chain"
-            echo "  npm run catalog"
+            echo "  npm run sync:repo-state"
             echo "  git status"
             exit 1
           fi

.github/workflows/publish-npm.yml

@@ -19,12 +19,44 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Python dependencies
+        run: pip install pyyaml
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
           node-version: "20"
           registry-url: "https://registry.npmjs.org"
 
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate references
+        run: npm run validate:references
+
+      - name: Sync release state
+        run: npm run sync:release-state
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Run docs security checks
+        run: npm run security:docs
+
+      - name: Build web app
+        run: npm run app:build
+
+      - name: Verify canonical release state
+        run: git diff --exit-code
+
+      - name: Dry-run npm package
+        run: npm pack --dry-run --json
+
       - name: Publish
         run: npm publish
         env:

.github/workflows/repo-hygiene.yml

@@ -0,0 +1,62 @@
+name: Repo Hygiene
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 7 * * 1"
+
+permissions:
+  contents: write
+
+jobs:
+  sync-repo-state:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Python dependencies
+        run: pip install pyyaml
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          cache: "npm"
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Run repo-state sync
+        run: npm run sync:repo-state
+
+      - name: Commit and push if changed
+        run: |
+          set -euo pipefail
+
+          managed_files=$(node tools/scripts/generated_files.js --shell --include-mixed)
+
+          if git diff --quiet; then
+            echo "No repo-state drift detected."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add $managed_files || true
+
+          if git diff --cached --quiet; then
+            echo "Repo hygiene produced unmanaged drift."
+            git status --short
+            exit 1
+          fi
+
+          git commit -m "chore: scheduled repo hygiene sync [ci skip]"
+          git pull origin main --rebase
+          git push origin HEAD