Merge pull request #105 from OneFineStarstuff/codex/develop-agi-and-asi-governance-roadmap

Add governance docs linting CI, scripts, tests, and governance blueprint artifacts

Author: OneFineStarstuff

.github/workflows/governance-docs-lint.yml

@@ -0,0 +1,59 @@
+name: Governance Docs Lint
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**/*.md'
+      - '.markdownlint.json'
+      - '.markdownlintignore'
+      - 'scripts/lint_governance_docs.sh'
+      - 'tests/test_lint_governance_docs.sh'
+      - 'Makefile'
+      - 'tests/test_lint_governance_docs.sh'
+      - 'Makefile'
+      - '.github/workflows/governance-docs-lint.yml'
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**/*.md'
+      - '.markdownlint.json'
+      - '.markdownlintignore'
+      - 'scripts/lint_governance_docs.sh'
+      - 'tests/test_lint_governance_docs.sh'
+      - 'Makefile'
+      - '.github/workflows/governance-docs-lint.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: governance-docs-lint-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-governance-docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Validate lint script syntax
+        run: bash -n scripts/lint_governance_docs.sh
+
+      - name: Validate test script syntax
+        run: bash -n tests/test_lint_governance_docs.sh
+
+      - name: Shellcheck lint scripts
+        uses: ludeeus/action-shellcheck@2.0.0
+        with:
+          scandir: "scripts tests"
+          severity: warning
+
+      - name: Run governance docs check target
+        run: make governance-docs-check

.markdownlint.json

@@ -0,0 +1,3 @@
+{
+  "default": true
+}

.markdownlintignore

@@ -0,0 +1,2 @@
+docs/governance/AGI_ASI_GSIFI_Blueprint_2026_2030.md
+docs/governance/LINTING_NOTES.md

Makefile

@@ -164,6 +164,16 @@ gov-suite-ci:
 gov-clean:
 	$(PYTHON) -c "from pathlib import Path; import shutil; report=Path('governance-artifact-validation-report.json'); suite=Path('governance-validation-suite-report.json'); report.exists() and report.unlink(); suite.exists() and suite.unlink(); [shutil.rmtree(p) for p in Path('governance_blueprint/validation').rglob('__pycache__') if p.is_dir()]"
 
+.PHONY: governance-docs-lint governance-docs-test governance-docs-check
+
+governance-docs-lint:
+	bash scripts/lint_governance_docs.sh
+	bash scripts/lint_governance_docs.sh all
+
+governance-docs-test:
+	bash tests/test_lint_governance_docs.sh
+
+governance-docs-check: governance-docs-lint governance-docs-test
 .PHONY: gstack-setup gstack-validate gstack-validate-strict gstack-validate-json gstack-validate-json-check gstack-test gstack-check gstack-ci gstack-clean
 
 gstack-setup:

docs/README.md

@@ -0,0 +1,19 @@
+# Documentation Index
+
+## Governance
+
+- See `docs/governance/README.md` for the AGI/ASI governance blueprint,
+  supporting templates, and linting notes used for G‑SIFI policy artifacts.
+
+## Linting
+
+- Markdown linting is enabled by default (`.markdownlint.json`).
+- Long-form governance policy files are explicitly listed in
+  `.markdownlintignore` to preserve dense regulatory tables/checklists.
+
+## Validation Commands
+
+- `scripts/lint_governance_docs.sh` verifies required ignore entries and lints
+  governance index docs (`strict`, default).
+- `scripts/lint_governance_docs.sh all` lints all governance markdown files
+  while honoring `.markdownlintignore`.