keelcore-standards 0.1.0__tar.gz

keelcore_standards-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,31 @@
+# CODEOWNERS
+# Changes to these paths require review from the designated owners.
+# Owners are referenced by GitHub team or username.
+# The last matching rule takes precedence.
+
+# Default owner for everything
+*                                   @keelcore/platform-team
+
+# CI workflows — security/infra review required
+.github/workflows/                  @keelcore/platform-infra
+.github/CODEOWNERS                  @keelcore/platform-infra
+.github/dependabot.yml              @keelcore/platform-infra
+
+# Scripts — infra review required; author cannot self-approve
+scripts/                            @keelcore/platform-infra
+
+# Governance documents — ARB review required
+governance/                         @keelcore/arb
+docs/adr/                           @keelcore/arb
+docs/rfc/                           @keelcore/arb
+docs/break-glass.md                 @keelcore/arb @keelcore/platform-infra
+
+# Dependency manifests — infra review required
+go.mod                              @keelcore/platform-infra
+package.json                        @keelcore/platform-infra
+package-lock.json                   @keelcore/platform-infra
+pyproject.toml                      @keelcore/platform-infra
+
+# Version and changelog — ARB review required
+VERSION                             @keelcore/arb
+CHANGELOG.md                        @keelcore/arb

keelcore_standards-0.1.0/.github/dependabot.yml

@@ -0,0 +1,42 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore(ci)"
+    labels:
+      - "dependencies"
+      - "ci"
+
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - "dependencies"

keelcore_standards-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: ci
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    name: audit / makefile
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - run: make audit
+
+  pr-policy:
+    name: policy / pr
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    if: github.event_name == 'pull_request'
+    env:
+      GITHUB_HEAD_REF: ${{ github.head_ref }}
+      PR_TITLE: ${{ github.event.pull_request.title }}
+      PR_BODY: ${{ github.event.pull_request.body }}
+      PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 2
+      - run: make ci-pr-policy
+
+  check-governance:
+    name: check / governance metadata
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - run: make check-adr-metadata
+      - run: make check-governance-metadata
+      - run: make check-rfc-metadata
+
+  lint-markdown:
+    name: lint / markdown
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+          cache-dependency-path: "package-lock.json"
+
+      - run: make setup-markdownlint
+      - run: make lint-newlines
+      - run: make lint-md
+
+  lint-bash:
+    name: lint / bash
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - run: make setup-shellcheck
+      - run: make lint-bash
+
+  verify-go:
+    name: verify / go module
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417  # v6.3.0
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - run: make verify-go

keelcore_standards-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,110 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to publish (e.g. v1.2.0)"
+        required: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  sbom:
+    name: release / sbom
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - run: make setup-syft
+      - run: make release-sbom
+
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f  # v7.0.0
+        with:
+          name: sbom
+          path: sbom.spdx.json
+          retention-days: 90
+
+  publish-npm:
+    name: publish / npm
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: npm-publish
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+        with:
+          node-version-file: ".nvmrc"
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
+          cache-dependency-path: "package-lock.json"
+
+      - run: make release-npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Attest npm provenance
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32  # v4.1.0
+        with:
+          subject-path: "*.tgz"
+
+  publish-pypi:
+    name: publish / pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi-publish
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version-file: ".python-version"
+
+      - run: make release-pypi
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1.13.0
+
+      - name: Attest PyPI provenance
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32  # v4.1.0
+        with:
+          subject-path: "dist/*"
+
+  publish-go:
+    name: publish / go (pkg.go.dev)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: go-publish
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417  # v6.3.0
+        with:
+          go-version-file: go.mod
+
+      - run: make release-go
+        env:
+          GITHUB_REF_NAME: ${{ github.ref_name }}
+          INPUT_TAG: ${{ inputs.tag }}

keelcore_standards-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# IDE — JetBrains
+.idea/
+*.iml
+*.iws
+*.ipr
+
+# IDE — VS Code
+.vscode/
+
+# IDE — Cursor
+.cursor/
+
+# IDE — Vim / Neovim
+*.swp
+*.swo
+*~
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.Python
+
+# Go
+/vendor/
+
+# Script log files (written by scripts/lint.sh, scripts/release/*.sh, etc.)
+/tmp/*.log
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Materialize output (consumers gitignore this in their own repos)
+.standards/
+.claude

keelcore_standards-0.1.0/.markdownlint.json

@@ -0,0 +1,7 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD024": { "allow_different_nesting": true, "siblings_only": true },
+  "MD029": false,
+  "MD033": false
+}

keelcore_standards-0.1.0/.nvmrc

@@ -0,0 +1 @@
+20

keelcore_standards-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

keelcore_standards-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to keelcore/standards are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+Breaking changes (governance removals, renamed files): major bump.
+New governance or expanded rules: minor bump.
+Corrections, clarifications, metadata: patch bump.
+
+---
+
+## [Unreleased]
+
+### Added
+
+- Architecture Review Board governance (`governance/arb.md`) — membership, quorum, tie-breaking, escalation
+- RFC workflow (`docs/rfc/RFC-0000-template.md`) — full Draft → Implemented lifecycle
+- DACI metadata fields on ADR template and all existing ADRs (Driver, Approver, Contributors, Informed, Supersedes, Superseded By)
+- Maturity metadata on all governance standards (Draft | Recommended | Required | Deprecated)
+- Automated ADR metadata enforcement (`scripts/check/adr-metadata.sh`)
+- Automated governance metadata enforcement (`scripts/check/governance-metadata.sh`)
+- RFC metadata enforcement (`scripts/check/rfc-metadata.sh`)
+- PR policy gate (`scripts/ci/pr-policy.sh`) — commit format, branch naming, description completeness, secret scan
+- Break-glass procedure (`docs/break-glass.md`)
+- Supply chain: artifact signing (`scripts/release/sign.sh`), SBOM generation (`scripts/release/sbom.sh`)
+- CI: SLSA provenance attestation, artifact signing, SBOM, and SHA256SUMS in publish workflow
+- CI: concurrency control (cancel superseded PR runs), npm caching, environment protection on publish jobs
+- `.github/CODEOWNERS` — coverage for workflows, scripts, governance, and manifests
+- `.github/dependabot.yml` — automated action SHA pin updates
+- `VERSION` file as single source of truth for standards version
+
+## [0.1.0] - 2026-03-09
+
+### Added
+
+- Initial scaffold: `governance/coding.md`, `governance/ci.md`, `governance/bash.md`
+- Platform architecture standards (`governance/platform.md`)
+- Observability standards (`governance/observability.md`)
+- Security and IAM standards (`governance/security.md`)
+- Runtime and orchestration standards (`governance/runtime.md`)
+- API management standards (`governance/api-management.md`)
+- ADR template (`docs/adr/0000-template.md`)
+- ADR-0001: Standards distributed as submodule and language package
+- ADR-0002: Coverage baseline stored in repository
+- ADR-0003: Architecture governance via DACI, RFC, and ARB
+- ADR-0004: SPIFFE/SPIRE for workload identity
+- ADR-0005: OpenTelemetry as unified observability framework
+- ADR-0006: OPA as centralized authorization policy engine
+- ADR-0007: Zero-downtime deployment via blue/green and canary
+- ADR-0008: Rapid key rotation with 5-minute platform SLA
+- ADR-0009: GitOps as declarative change management mechanism
+- Multi-ecosystem publishing (Go, npm, PyPI) via GitHub Actions
+- Tool adapters for Claude Code, Cursor, and GitHub Copilot
+- Release scripts: `npm-publish.sh`, `pypi-publish.sh`, `go-publish.sh`
+- Lint scripts: `markdown.sh`, `shellcheck.sh`
+- Verify script: `go.sh`

keelcore_standards-0.1.0/Makefile

@@ -0,0 +1,210 @@
+# keelcore/standards — Master Orchestrator
+# All CI concerns are invoked through this file.
+# Workflow YAML calls `make <target>`; developers call the same targets locally.
+
+.PHONY: build lint lint-newlines lint-md lint-bash lint-markdown \
+        test unit-test integration-test clean audit \
+        ci-pr-policy ci-secret-scan ci-dco ci-coverage-delta \
+        coverage check-adr-metadata check-governance-metadata check-rfc-metadata \
+        check-legal-drift release-sbom release-sign release-go release-npm release-pypi \
+        setup-markdownlint setup-shellcheck setup-syft verify-canonical verify-go \
+        format lint-all pre-commit help
+
+## Universal canonical targets (language-independent; mandated by CI standards)
+
+build:
+	@echo "✅ Nothing to build (standards is a documentation repository)"
+
+lint: lint-newlines lint-md lint-bash
+
+test: unit-test integration-test
+
+unit-test:
+	@echo "✅ No unit tests (standards is a documentation repository)"
+
+integration-test:
+	@echo "✅ No integration tests (standards is a documentation repository)"
+
+clean:
+	@echo "🧹 Nothing to clean (standards is a documentation repository)"
+
+## Audit
+
+audit:
+	@echo "🔍 Running CI/Makefile audit..."
+	./scripts/ci/audit-make-targets.sh
+
+## Lint targets
+
+lint-newlines:
+	@echo "🔍 Checking trailing newlines..."
+	./scripts/lint/newlines.sh
+
+lint-md:
+	@echo "🔍 Running markdown lint (markdownlint-cli)..."
+	./scripts/lint/md.sh
+
+lint-bash:
+	@echo "🔍 Running shellcheck..."
+	./scripts/lint/shellcheck.sh
+
+lint-markdown:
+	@echo "🔍 Running markdown lint (markdownlint-cli2)..."
+	./scripts/lint/markdown.sh
+
+## Check targets
+
+check-adr-metadata:
+	@echo "🔍 Checking ADR metadata..."
+	./scripts/check/adr-metadata.sh
+
+check-governance-metadata:
+	@echo "🔍 Checking governance metadata..."
+	./scripts/check/governance-metadata.sh
+
+check-rfc-metadata:
+	@echo "🔍 Checking RFC metadata..."
+	./scripts/check/rfc-metadata.sh
+
+check-legal-drift:
+	@echo "⚖️  Checking legal file drift..."
+	./scripts/check-legal-drift.sh
+
+## CI gate targets
+
+ci-pr-policy:
+	@echo "🔍 Running PR policy check..."
+	./scripts/ci/pr-policy.sh
+
+ci-secret-scan:
+	@echo "🔍 Running secret scan..."
+	./scripts/ci/secret-scan.sh
+
+ci-dco:
+	@echo "🔍 Running DCO sign-off check..."
+	./scripts/ci/dco-check.sh
+
+ci-coverage-delta:
+	@echo "📊 Checking coverage delta..."
+	./scripts/test/coverage-delta.sh
+
+## Coverage
+
+coverage:
+	@echo "📊 Generating coverage report..."
+	./scripts/test/coverage.sh
+
+## Release targets
+
+release-sbom:
+	@echo "📋 Generating SBOM..."
+	./scripts/release/sbom.sh
+
+release-sign:
+	@echo "✍️  Signing artifacts..."
+	./scripts/release/sign.sh
+
+release-go:
+	@echo "🚀 Publishing Go module..."
+	./scripts/release/go-publish.sh
+
+release-npm:
+	@echo "🚀 Publishing npm package..."
+	./scripts/release/npm-publish.sh
+
+release-pypi:
+	@echo "🚀 Publishing PyPI package..."
+	./scripts/release/pypi-publish.sh
+
+## Setup targets
+
+setup-markdownlint:
+	@echo "🔧 Installing markdownlint-cli..."
+	./scripts/ci/setup-markdownlint.sh
+
+setup-shellcheck:
+	@echo "🔧 Installing shellcheck..."
+	./scripts/ci/setup-shellcheck.sh
+
+setup-syft:
+	@echo "🔧 Installing syft..."
+	./scripts/ci/setup-syft.sh
+
+## Canonical script verification
+
+verify-canonical:
+	@echo "🔍 Verifying canonical scripts in downstream repo (REPO=<path>)..."
+	./scripts/ci/verify-canonical-scripts.sh $(REPO)
+
+## Verify targets
+
+verify-go:
+	@echo "🔍 Verifying Go module..."
+	./scripts/verify/go.sh
+
+## Utility targets
+
+format:
+	@echo "🖊️  Formatting repository..."
+	./scripts/format.sh
+
+lint-all:
+	@echo "🔍 Running all linters (full suite)..."
+	./scripts/lint.sh
+
+pre-commit:
+	@echo "🪝 Running pre-commit checks..."
+	./scripts/git_precommit.sh
+
+## Help
+
+help:
+	@echo "keelcore/standards Build System"
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Universal targets (canonical; language-independent):"
+	@echo "  build              No-op (documentation repository)"
+	@echo "  lint               lint-newlines + lint-md + lint-bash"
+	@echo "  test               unit-test + integration-test"
+	@echo "  unit-test          No-op (documentation repository)"
+	@echo "  integration-test   No-op (documentation repository)"
+	@echo "  clean              No-op (documentation repository)"
+	@echo "  audit              CI/Makefile standards compliance audit"
+	@echo ""
+	@echo "Lint:"
+	@echo "  lint-newlines      Check trailing newlines (.md .sh .go .yml etc.)"
+	@echo "  lint-md            markdownlint-cli check (canonical; from keel)"
+	@echo "  lint-bash          shellcheck on all scripts"
+	@echo "  lint-markdown      markdownlint-cli2 check (standards native)"
+	@echo ""
+	@echo "Checks:"
+	@echo "  check-adr-metadata         Validate ADR metadata fields"
+	@echo "  check-governance-metadata  Validate governance file metadata"
+	@echo "  check-rfc-metadata         Validate RFC metadata fields"
+	@echo "  check-legal-drift          Verify legal files match source of truth"
+	@echo ""
+	@echo "CI Gates:"
+	@echo "  ci-pr-policy       PR policy gate"
+	@echo "  ci-secret-scan     Secret scan (gitleaks)"
+	@echo "  ci-dco             DCO Signed-off-by check"
+	@echo "  ci-coverage-delta  Coverage delta gate"
+	@echo "  coverage           Generate coverage report"
+	@echo ""
+	@echo "Release:"
+	@echo "  release-sbom       Generate SPDX SBOM"
+	@echo "  release-sign       Sign artifacts (cosign)"
+	@echo "  release-go         Publish Go module"
+	@echo "  release-npm        Publish npm package"
+	@echo "  release-pypi       Publish PyPI package"
+	@echo ""
+	@echo "Setup:"
+	@echo "  setup-markdownlint Install markdownlint-cli"
+	@echo ""
+	@echo "Verification:"
+	@echo "  verify-canonical REPO=<path>  Check downstream repo scripts match standards"
+	@echo "  verify-go                     Build and vet the Go module"
+	@echo ""
+	@echo "Utilities:"
+	@echo "  format             Run all formatters"
+	@echo "  lint-all           Run full linter suite (scripts/lint.sh)"
+	@echo "  pre-commit         Run pre-commit checks"

keelcore_standards-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: keelcore-standards
+Version: 0.1.0
+Summary: Engineering standards for keelcore projects — coding, CI, and bash.
+License: MIT
+Requires-Python: >=3.9