chore(core/docs): changelog automation, ref alignment, constants unification, safety sweeps

.coderabbit.yml

@@ -0,0 +1,36 @@
+version: 1
+
+review:
+  summary_preferred: true
+  max_total_comments: 50
+  max_comments_per_file: 5
+  prefer_patch_suggestions: true
+  tone: "concise, constructive, and action-oriented"
+  style:
+    - "Group similar issues together; avoid duplicates"
+    - "Reference rules/patterns (e.g., markdownlint MD041) over fragile line numbers"
+    - "Propose concrete fix-it snippets where possible"
+    - "Avoid inline comments on docs unless correctness is at stake; use summary"
+
+filters:
+  paths:
+    docs/**: summary_only
+    assets/**: ignore
+    build/**: ignore
+    .github/**: summary_only
+
+labels:
+  summary_only:
+    - docs-only
+    - chore
+  skip:
+    - vendored
+
+rules:
+  - name: "Front matter required"
+    paths: ["docs/**/*.md"]
+    summary: true
+  - name: "Single H1 per document"
+    paths: ["docs/**/*.md"]
+    summary: true
+

.githooks/pre-push

@@ -1,3 +1,56 @@
-#!/bin/sh
-command -v git-lfs >/dev/null 2>&1 || { printf >&2 "\n%s\n\n" "This repository is configured for Git LFS but 'git-lfs' was not found on your path. If you no longer wish to use Git LFS, remove this hook by deleting the 'pre-push' file in the hooks directory (set by 'core.hookspath'; usually '.git/hooks')."; exit 2; }
-git lfs pre-push "$@"
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Guard: allow bypass
+if [[ "${HOOKS_BYPASS:-}" == "1" ]]; then
+  exit 0
+fi
+
+remote_name=$1
+remote_url=$2
+
+status=0
+while read -r local_ref local_sha remote_ref remote_sha; do
+  # Only enforce for pushes to main
+  if [[ "$remote_ref" == "refs/heads/main" ]]; then
+    # Determine the range to inspect
+    range=""
+    if [[ "$remote_sha" == "0000000000000000000000000000000000000000" ]]; then
+      # New branch/update; check last commit only
+      range="$local_sha^..$local_sha"
+    else
+      range="$remote_sha..$local_sha"
+    fi
+
+    # Check if a changelog file is updated in this push
+    # Match common variants: CHANGELOG, CHANGES, with optional .md, case-insensitive, with or without paths
+    if ! git diff --name-only "$range" | grep -iqE '(^|.*/)(CHANGELOG|CHANGES)(\.md)?$'; then
+      echo "[pre-push] No changelog file updated for push to main ($range)." >&2
+      echo "           Expected one of: CHANGELOG.md, CHANGES.md, or variants (case-insensitive)." >&2
+      echo "           Run: make changelog-add m=\"<one-liner>\"" >&2
+      echo "           Or bypass once: HOOKS_BYPASS=1 git push" >&2
+      status=1
+    fi
+  fi
+
+  # Worksheet gate: block pushes when review worksheets contain unfilled templates
+  # Determine the range to inspect for all branches
+  range=""
+  if [[ "$remote_sha" == "0000000000000000000000000000000000000000" ]]; then
+    range="$local_sha^..$local_sha"
+  else
+    range="$remote_sha..$local_sha"
+  fi
+  changed_files=$(git diff --name-only "$range" | grep '^docs/code-reviews/PR' || true)
+  if [[ -n "$changed_files" ]]; then
+    # Run worksheet checker
+    if ! python3 tools/review/check_worksheets.py $changed_files; then
+      echo "[pre-push] Unfilled review worksheet templates detected in changed files." >&2
+      echo "           Please complete Accepted/Rejected sections before pushing." >&2
+      echo "           Bypass once with HOOKS_BYPASS=1 if necessary." >&2
+      status=1
+    fi
+  fi
+done
+
+exit $status

.github/labeler.yml

@@ -0,0 +1,4 @@
+docs-only:
+  - changed-files:
+      - any-glob-to-any-file: ['docs/**', 'README.md', 'AGENTS.md', 'CONTRIBUTING.md']
+

.github/pull_request_template.md

@@ -1,28 +1,24 @@
-## Description
+## Summary
 
-Brief description of what this PR does.
+Describe the change and why it’s needed. Link issues/PRDs if relevant.
 
-## Related Issue
+## Change Areas
 
-Fixes #(issue number)
+- [ ] Core (C)
+- [ ] CLI / Hooks
+- [ ] Docs
+- [ ] CI / Tooling
 
-## Type of Change
+## Risk
 
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation update
+- [ ] Behavior change
+- [ ] Public API change
+- [ ] Docs-only
 
-## Testing
+## Code Review Guidance (for humans and CodeRabbit)
 
-- [ ] I have added tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] I have added/updated documentation as needed
+- Summarize top risks and propose concrete fix-it blocks where needed.
+- Prefer rule/pattern references (e.g., markdownlint MD041) over fragile line numbers.
+- Group nits into a brief summary; avoid inline comments on docs unless correctness is impacted.
+- Provide patch suggestions for repeated issues.
 
-## Checklist
-
-- [ ] My code follows the style guidelines of this project
-- [ ] I have run `make test` in Docker
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
-- [ ] I have added tests that prove my fix is effective or that my feature works

.github/workflows/apply-feedback.yml

@@ -0,0 +1,36 @@
+name: Apply PR Feedback Replies
+
+on:
+  push:
+    branches-ignore: [ main ]
+    paths:
+      - 'docs/code-reviews/**.md'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  apply:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Detect changed review worksheets
+        id: files
+        run: |
+          set -e
+          BEFORE=${{ github.event.before }}
+          AFTER=${{ github.sha }}
+          git fetch --no-tags origin "$BEFORE" || true
+          CHANGED=$(git diff --name-only "$BEFORE" "$AFTER" | grep '^docs/code-reviews/PR' || true)
+          echo "changed=$CHANGED" >> $GITHUB_OUTPUT
+      - name: Apply feedback replies
+        if: steps.files.outputs.changed != ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          OWNER=${GITHUB_REPOSITORY%%/*}
+          REPO=${GITHUB_REPOSITORY##*/}
+          python3 -m pip install --upgrade pip >/dev/null 2>&1 || true
+          python3 tools/review/apply_feedback_to_github.py --owner "$OWNER" --repo "$REPO" ${{ steps.files.outputs.changed }}

.github/workflows/auto-seed-review.yml

@@ -0,0 +1,123 @@
+name: Auto Seed Review Doc
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  seed-same-repo:
+    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch (same-repo)
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Seed feedback doc into repo
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PR=${{ github.event.number }}
+          echo "Seeding review for PR#$PR (same-repo)"
+          python3 tools/review/seed_feedback_from_github.py \
+            --owner "${GITHUB_REPOSITORY%%/*}" --repo "${GITHUB_REPOSITORY##*/}" \
+            --pr "$PR" --out docs/code-reviews
+      - name: Commit and push
+        run: |
+          git config user.name  "git-mind-bot"
+          git config user.email "gitmind-bot@example.com"
+          git add docs/code-reviews
+          if git diff --cached --quiet; then
+            echo "No changes to commit"; exit 0; fi
+          PR=${{ github.event.number }}
+          SHA=${{ github.event.pull_request.head.sha }}
+          git commit -m "chore(review): seed feedback for PR #$PR ($SHA)"
+          git push
+
+  seed-fork:
+    if: ${{ github.event.pull_request.head.repo.full_name != github.repository }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout fork branch (read-only)
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Try to seed and push to fork (if maintainers can modify)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITMIND_PR_WORKSHEET_BOT: ${{ secrets.GITMIND_PR_WORKSHEET_BOT }}
+        run: |
+          set -e
+          PR=${{ github.event.number }}
+          echo "Seeding review for PR#$PR (fork)"
+          # Ensure our tools exist (checked out fork branch may not have them in older forks)
+          if [ ! -f tools/review/seed_feedback_from_github.py ]; then
+            echo "Tools missing in fork, checking out base repo tools..."
+            mkdir -p _tools
+            git clone --depth=1 https://github.com/${GITHUB_REPOSITORY}.git _tools/base
+            cp -r _tools/base/tools/review . || true
+          fi
+          python3 tools/review/seed_feedback_from_github.py \
+            --owner "${GITHUB_REPOSITORY%%/*}" --repo "${GITHUB_REPOSITORY##*/}" \
+            --pr "$PR" --out docs/code-reviews
+          git config user.name  "git-mind-bot"
+          git config user.email "gitmind-bot@example.com"
+          git add docs/code-reviews
+          if git diff --cached --quiet; then
+            echo "No seeded changes to commit"; exit 0; fi
+          git commit -m "chore(review): seed feedback for PR #$PR"
+          # Attempt to push using GITMIND_PR_WORKSHEET_BOT if provided and contributor allows edits
+          if [ -n "$GITMIND_PR_WORKSHEET_BOT" ]; then
+            repo_full="${{ github.event.pull_request.head.repo.full_name }}"
+            branch="${{ github.event.pull_request.head.ref }}"
+            echo "Attempting push to fork $repo_full branch $branch"
+            git remote set-url origin https://x-access-token:$GITMIND_PR_WORKSHEET_BOT@github.com/$repo_full.git
+            if git push origin "HEAD:$branch"; then
+              echo "Pushed seeded doc to fork branch"
+              exit 0
+            else
+              echo "Push to fork failed (likely edits not allowed); will upload artifact instead"
+            fi
+          else
+            echo "GITMIND_PR_WORKSHEET_BOT not set; cannot push to fork. Uploading artifact instead."
+          fi
+          # Fall through to artifact path
+          mkdir -p review-seed && cp -r docs/code-reviews/* review-seed/ || true
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: review-seed-PR${{ github.event.number }}
+          path: review-seed/**
+      - name: Comment with instructions
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request.number;
+            const msg = `I've generated a seeded review worksheet as an artifact for this PR (forked branch).
+
+            Steps:
+            1. Download the 'review-seed-PR${pr}' artifact from this workflow run.
+            2. Copy the file under 'docs/code-reviews/PR${pr}/<sha>.md' into your branch.
+            3. Fill in {response} sections with Accepted/Rejected templates and push.
+
+            Maintainers: merging PR branches into the main repo will allow auto-commit of future seeds.`;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr,
+              body: msg
+            });

.github/workflows/label-docs-only.yml

@@ -0,0 +1,18 @@
+name: Label docs-only PRs
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          configuration-path: .github/labeler.yml

.github/workflows/seed-review.yml

@@ -0,0 +1,32 @@
+name: Seed Review Doc (manual)
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: PR number to seed
+        required: true
+        type: number
+
+jobs:
+  seed:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Run seeding script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python3 tools/review/seed_feedback_from_github.py \
+            --owner ${GITHUB_REPOSITORY%%/*} --repo ${GITHUB_REPOSITORY##*/} --pr ${{ inputs.pr }} --out review-seed
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: review-seed
+          path: review-seed/**

.github/workflows/update-features-ledger.yml

@@ -0,0 +1,32 @@
+name: Update Features Ledger
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/features/Features_Ledger.md'
+      - 'README.md'
+      - 'scripts/update_progress.py'
+
+permissions:
+  contents: write
+
+jobs:
+  update-ledger:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Update progress
+        run: |
+          python3 scripts/update_progress.py
+      - name: Commit changes if any
+        run: |
+          git config user.name  "git-mind-bot"
+          git config user.email "gitmind-bot@example.com"
+          git add README.md docs/features/Features_Ledger.md
+          if git diff --cached --quiet; then
+            echo "No progress changes"; exit 0; fi
+          git commit -m "chore(ledger): auto-update features progress"
+          git push