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/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