@keelcore/standards 0.9.7

package/README.md

@@ -0,0 +1,99 @@
+# keelcore/standards
+
+Engineering standards for keelcore projects. Single source of truth for coding, CI, and bash.
+Consumed by AI coding tools (Claude, Cursor, Copilot) and human contributors alike.
+
+## Governance
+
+| File | Scope |
+| --- | --- |
+| [governance/coding.md](governance/coding.md) | All code edits — scope control, reviewability, safety |
+| [governance/ci.md](governance/ci.md) | CI workflows and scripts — supply chain, coverage, permissions |
+| [governance/bash.md](governance/bash.md) | Bash scripts — portability, structure, logging |
+| [governance/platform.md](governance/platform.md) | Platform architecture — governance process, DNS, TLS, WAF, networking |
+| [governance/observability.md](governance/observability.md) | Metrics, logging, tracing, alerting |
+| [governance/security.md](governance/security.md) | IAM, encryption, key management, data classification |
+| [governance/runtime.md](governance/runtime.md) | Containers, orchestration, deployment, compliance |
+| [governance/api-management.md](governance/api-management.md) | API design, versioning, rate limiting, quotas, gateway |
+
+## Consumption
+
+### Submodule (default, language-agnostic)
+
+```bash
+git submodule add git@github.com:keelcore/standards .standards
+git submodule update --init --recursive
+```
+
+Reference governance from your tool adapters via relative paths (`.standards/governance/coding.md`).
+
+Update to latest:
+
+```bash
+git submodule update --remote .standards
+git add .standards && git commit -m "chore: update standards"
+```
+
+### Go
+
+```bash
+go get github.com/keelcore/standards/go
+```
+
+Add to your repo:
+
+```go
+//go:generate go run github.com/keelcore/standards/go/cmd/materialize .standards
+```
+
+Then run `go generate ./...` to extract governance files to `.standards/` (gitignore this directory).
+
+### Node
+
+```bash
+npm install @keelcore/standards
+```
+
+Governance files are available under `node_modules/@keelcore/standards/governance/`.
+
+### Python
+
+```bash
+pip install keelcore-standards
+```
+
+## Tool Adapters
+
+Copy the relevant adapter to your repo and adjust paths if needed.
+
+| Tool | Adapter |
+| --- | --- |
+| Claude Code | [adapters/claude/CLAUDE.md](adapters/claude/CLAUDE.md) |
+| Cursor | [adapters/cursor/](adapters/cursor/) |
+| GitHub Copilot | [adapters/copilot/copilot-instructions.md](adapters/copilot/copilot-instructions.md) |
+
+## Architecture Decision Records
+
+ADRs documenting standards design decisions live in [docs/adr/](docs/adr/).
+
+New ADRs use the template at [docs/adr/0000-template.md](docs/adr/0000-template.md).
+
+| ADR | Decision |
+| --- | --- |
+| [0001](docs/adr/0001-standards-as-submodule-and-package.md) | Standards distributed as both submodule and language package |
+| [0002](docs/adr/0002-coverage-baseline-in-repo.md) | Code coverage baseline stored in repository |
+| [0003](docs/adr/0003-architecture-governance-process.md) | Architecture governance via DACI, RFC, and ARB |
+| [0004](docs/adr/0004-workload-identity-spiffe-spire.md) | SPIFFE/SPIRE for workload identity |
+| [0005](docs/adr/0005-observability-opentelemetry.md) | OpenTelemetry as the unified observability framework |
+| [0006](docs/adr/0006-opa-centralized-policy-engine.md) | OPA as the centralized authorization policy engine |
+| [0007](docs/adr/0007-zero-downtime-deployment.md) | Zero-downtime deployment via blue/green and canary |
+| [0008](docs/adr/0008-rapid-key-rotation.md) | Rapid key rotation with a 5-minute platform SLA |
+| [0009](docs/adr/0009-gitops-change-management.md) | GitOps as the declarative change management mechanism |
+
+## Versioning
+
+Semantic versioning. Tags trigger publication to all package ecosystems simultaneously.
+
+- Breaking changes (governance removals, renamed files): major version bump.
+- New governance or expanded rules: minor version bump.
+- Corrections, clarifications: patch version bump.

package/governance/ai/conduct.md

@@ -0,0 +1,66 @@
+# AI Model Conduct Standards
+
+These rules govern the behavior of AI coding assistants (Claude, Copilot, Cursor, or equivalent)
+when working in projects under this governance. They are non-negotiable and take precedence over
+any model-default behavior.
+
+**Maturity:** Required
+**Version:** 1.0.0
+**Last Reviewed:** 2026-03-14
+
+## Commit Attribution
+
+- Do NOT add `Co-Authored-By`, `Generated-by`, or any AI attribution trailer to commit messages.
+- Commit messages contain only the subject, optional body, and the required DCO `Signed-off-by`
+  trailer. No AI branding.
+
+## Test File Protection
+
+- Do NOT modify test files without explicit prior authorization from the developer.
+- When a test fails, find and fix the root cause in production code. Do not adjust the test to
+  make it pass.
+- Exceptions (adding a new test, fixing a test bug, tracking an intentional contract change)
+  require explicit approval in the conversation before any edit is made.
+
+## Test Suite Execution
+
+- Run `make test` (or `make unit-test` at minimum) before declaring any code change complete.
+- Do not hand off code without verifying the test suite passes.
+- If tests cannot be run (environment constraint), state this explicitly and enumerate what was
+  not validated.
+
+## Entry Point Files Are Pinned
+
+- `main.go` (and any program entry point file) is pinned — do not edit it without explicit
+  developer consent in the current conversation.
+- Entry points are considered high-blast-radius: a silent change to `main` can alter startup
+  behavior, flag defaults, or initialization order in ways that are hard to review.
+
+## Bash Script Delivery
+
+- When writing or editing a bash script, always deliver the complete script.
+- Never deliver a diff, patch, or partial snippet of a bash script.
+- Rationale: partial bash edits are error-prone; the complete script is reviewable as a unit.
+
+## Governance Supremacy
+
+- Project governance documents (this repo's `governance/` tree) override any model default or
+  prior training behavior.
+- When a governance rule conflicts with a model default (e.g., adding attribution, adding
+  speculative features, cleaning up untouched code), governance wins without exception.
+- If a governance rule is ambiguous, ask for clarification rather than applying a default.
+
+## Scope Discipline
+
+- Do not perform unrequested cleanup, refactoring, or improvements in files adjacent to the
+  current change.
+- Do not add docstrings, comments, or type annotations to code not directly modified.
+- Do not add error handling, fallbacks, or validation for scenarios that cannot occur.
+- Surgical edits only: the smallest correct change that satisfies the request.
+
+## Memory and Governance Relationship
+
+- Model memory (session-local or persisted) is subordinate to governance.
+- If a memory contradicts governance, flag the conflict to the developer; do not silently pick
+  one over the other.
+- Governance is the source of truth; memory captures working context and in-flight decisions.

package/governance/api-management.md

@@ -0,0 +1,185 @@
+# API Management Standards
+
+These rules govern API design, versioning, rate limiting, quotas, lifecycle management, and
+developer experience. They are non-negotiable unless explicitly superseded by a signed ADR.
+
+**Maturity:** Required
+**Version:** 1.0.0
+**Last Reviewed:** 2026-03-09
+
+## API Design
+
+### Interface Contracts
+
+1. Every API exposes a machine-readable interface definition. REST APIs use OpenAPI 3.1+.
+   gRPC services use Protocol Buffers with buf schema registry publication. GraphQL schemas
+   are registered in the central schema registry.
+2. Interface definitions are version-controlled in the owning service's repository and published
+   to the central API catalog on every release.
+3. APIs follow a consistent resource-oriented design: nouns for resources, standard HTTP verbs
+   (GET, POST, PUT, PATCH, DELETE) for operations, and standard status codes.
+
+### Versioning
+
+4. All APIs are versioned. The version is embedded in the URL path for REST (`/v1/`, `/v2/`).
+   gRPC APIs encode the version in the package name (`keelcore.auth.v1`).
+5. A version is considered stable once it is deployed to production. Stable versions must not
+   receive breaking changes. Add a new version instead.
+6. Breaking changes are defined as: removing or renaming a field, changing a field's type,
+   removing an endpoint, changing required/optional status of a field, or changing error semantics.
+7. Non-breaking additions (new optional fields, new endpoints, new enum values that do not affect
+   existing behavior) may be made to a stable version.
+8. Deprecated versions remain available for a minimum of 6 months after the successor version
+   is available. Deprecation is communicated via the `Deprecation` and `Sunset` response headers
+   and in the API catalog.
+
+### Error Responses
+
+9. All error responses use a consistent envelope:
+
+   ```json
+   {
+     "error": {
+       "code": "RESOURCE_NOT_FOUND",
+       "message": "The requested resource was not found.",
+       "request_id": "<trace_id>",
+       "details": []
+     }
+   }
+   ```
+
+10. `code` is a machine-readable uppercase string constant. `message` is human-readable.
+    HTTP status codes and `code` values are documented in the API catalog.
+11. Error messages must not include internal implementation details (stack traces, SQL queries,
+    internal service names) in production responses.
+
+### Pagination
+
+12. All list endpoints that may return more than 100 items support cursor-based pagination.
+    Offset pagination is acceptable only for internal tooling APIs.
+13. Page size has a maximum (default 100, configurable per endpoint, maximum 1000). Requests
+    for unlimited results are rejected.
+14. Pagination response includes: `next_cursor`, `prev_cursor` (where supported), `total_count`
+    (where computationally feasible), and `has_more`.
+
+## Rate Limiting
+
+### Global Limits
+
+15. All API traffic passes through the centralized rate limiting layer before reaching service pods.
+16. Global rate limits protect the platform from aggregate overload. These are set by the platform
+    team and documented in the API catalog.
+17. Rate limit enforcement uses a token bucket algorithm. Burst capacity may be up to 2× the
+    sustained rate for a window of up to 5 seconds.
+
+### Per-Service and Per-Client Limits
+
+18. Every API defines explicit rate limits per endpoint. Rate limits are documented in the API
+    catalog alongside the endpoint specification.
+19. Rate limits are enforced per API key, per client identity (OAuth client ID), or per
+    authenticated user, in that priority order. Unauthenticated traffic shares a shared
+    anonymous pool with a lower limit.
+20. Services configure rate limits independently of the global limit; the effective limit is
+    the minimum of the global and per-service limits.
+21. Rate limit state is stored in a shared, distributed backend (e.g., Redis). Per-replica
+    in-memory rate limiting that can be bypassed by round-robin routing is prohibited.
+
+### Rate Limit Responses
+
+22. Rate-limited requests receive HTTP 429 with:
+    - `Retry-After` header (seconds until the client may retry)
+    - `X-RateLimit-Limit` (requests allowed per window)
+    - `X-RateLimit-Remaining` (requests remaining in the current window)
+    - `X-RateLimit-Reset` (Unix timestamp of window reset)
+    - A JSON body following the standard error envelope (rule 9 above)
+23. Rate limit headers (`X-RateLimit-*`) are included on every API response, not only on 429s.
+
+### Quotas
+
+24. Usage quotas (distinct from rate limits) enforce longer-window consumption caps (daily,
+    monthly) per API key or tenant. Quotas are configured in the API management platform.
+25. Quota exhaustion returns HTTP 429 with `code: QUOTA_EXCEEDED` and a `Retry-After` pointing
+    to the quota reset time.
+26. Quota alerts fire at 80% and 95% consumption to allow clients and operators to take action
+    before hard limits are hit.
+
+## Authentication and Authorization
+
+### API Key Management
+
+27. API keys are issued by the central API management platform. Hand-crafted keys are prohibited.
+28. API keys are associated with: an owner (human or service), a set of allowed scopes, an
+    expiry date, and an environment (keys do not cross environment boundaries).
+29. API keys are rotated on a maximum 12-month cycle. Keys that have not been rotated are
+    automatically expired and flagged for the owner.
+30. API key usage is logged per request with: key ID (never the key value), endpoint, response
+    code, and latency.
+31. Compromised API keys are revoked within 5 minutes of detection. The platform supports
+    emergency bulk revocation for a compromised credential class.
+
+### Scopes and Permissions
+
+32. API scopes are defined at the resource level and follow the pattern `{resource}:{action}`
+    (e.g., `orders:read`, `orders:write`). Wildcard scopes are prohibited for non-admin APIs.
+33. Clients are issued only the scopes they need. Over-provisioned scopes are flagged in the
+    quarterly access review.
+34. Admin scopes require MFA-protected issuance and a shorter expiry (maximum 8 hours).
+
+## API Gateway
+
+### Gateway Responsibilities
+
+35. The API gateway handles: routing, authentication verification, rate limiting, WAF enforcement,
+    request/response logging, and protocol translation (where needed).
+36. Business logic must not reside in gateway configuration. Transformation rules that implement
+    business semantics belong in the upstream service.
+37. Gateway configuration is version-controlled and deployed via the same GitOps pipeline as
+    application code. Manual console edits are prohibited in staging and production.
+
+### Backend Health and Circuit Breaking
+
+38. The gateway enforces circuit breakers for each upstream service. A service that exceeds the
+    error threshold (5xx rate > 50% for 10 seconds) is circuit-broken; traffic is rejected at
+    the gateway with HTTP 503 until the upstream recovers.
+39. Upstream health checks are configured per route. The gateway does not route to unhealthy
+    upstreams.
+
+### Observability at the Gateway
+
+40. The gateway emits per-endpoint metrics: request rate, error rate, latency (p50/p95/p99),
+    and upstream latency. These are automatically included in each API's RED dashboard.
+41. Every request is tagged with a `request_id` injected or verified by the gateway. The
+    `request_id` matches the `trace_id` in distributed traces.
+
+## API Lifecycle
+
+### Catalog and Discovery
+
+42. Every API is registered in the central API catalog before its first production deployment.
+    Unregistered APIs are blocked by admission control.
+43. The catalog entry includes: service owner, SLO, rate limits, authentication requirements,
+    versioning status, deprecation dates (if applicable), and a link to the OpenAPI/Protobuf spec.
+44. The catalog is queryable by all engineers and is the single source of truth for API
+    discoverability.
+
+### Deprecation and Retirement
+
+45. API retirement follows a defined process: announce deprecation (Sunset header + catalog
+    update), monitor usage, notify active consumers, enforce sunset date.
+46. An API version with active traffic cannot be retired without consumer migration or an
+    explicitly accepted exception.
+47. The `Sunset` date is set in UTC and announced at least 6 months in advance for externally
+    consumed APIs, 30 days for internal-only APIs.
+
+## Do Not
+
+- Publish an API without an OpenAPI/Protobuf spec in the central catalog.
+- Make breaking changes to a stable API version.
+- Issue API keys outside the central API management platform.
+- Cross environment boundaries with API keys.
+- Return internal stack traces or SQL errors in production API responses.
+- Implement rate limiting as per-replica in-memory state.
+- Configure the gateway with business logic or inline transformations.
+- Retire an API version with active consumers without an approved migration plan.
+- Return list endpoints without pagination for collections that may grow beyond 100 items.
+- Omit rate limit headers from API responses.

package/governance/arb.md

@@ -0,0 +1,110 @@
+# Architecture Review Board (ARB)
+
+**Maturity:** Required
+**Version:** 1.0.0
+**Last Reviewed:** 2026-03-09
+
+The ARB is the governing body for platform architecture decisions. It is the default Approver
+for all architecture ADRs and the final escalation point for cross-domain technical disputes.
+
+## Membership
+
+### Composition
+
+1. The ARB has a minimum of 5 members and a maximum of 9 members.
+2. Members are nominated by the CTO and serve a minimum term of 12 months.
+3. Required seats (one each): Infrastructure, Security, Observability, Data, Application Platform.
+4. The CTO or a designated VP of Engineering holds the Chair seat. The Chair is a non-voting
+   member except to break ties (see Tie-Breaking below).
+5. Membership is documented in the internal people directory and in this file's companion
+   `docs/arb-members.md` (maintained separately from this governance doc to avoid churn).
+
+### Eligibility
+
+6. Members must be active engineers or engineering managers with direct responsibility in their
+   domain. Advisory or external members are not permitted.
+7. A member who misses three consecutive meetings without proxy is automatically suspended
+   pending review by the Chair.
+
+## Meeting Cadence
+
+8. The ARB meets on a defined monthly cadence. The meeting schedule is published at the start
+   of each quarter.
+9. Emergency sessions may be called by the Chair or by any two members with a minimum 24-hour
+   notice. Emergency sessions are limited to the agenda item that triggered them.
+10. Meeting notes and decisions are published to the engineering wiki within five business days.
+11. Decisions made asynchronously (via PR approval or written vote) are recorded with the same
+    formality as decisions made in session.
+
+## Decision-Making
+
+### Quorum
+
+12. Quorum is a simple majority of seated, non-suspended members (excluding the Chair):
+    - 5 members: quorum = 3
+    - 7 members: quorum = 4
+    - 9 members: quorum = 5
+13. Decisions made without quorum are provisional. They must be ratified at the next session
+    where quorum is present, or they are void.
+14. A member who has a conflict of interest in a decision must declare it and recuse. Recused
+    members do not count toward quorum for that item.
+
+### Voting
+
+15. Decisions are made by simple majority of present, non-recused members.
+16. Votes are recorded (member, vote, rationale for dissent) in the meeting notes.
+17. Abstentions are permitted but discourage without stated reason.
+
+### Tie-Breaking
+
+18. When a vote is tied, the Chair casts the deciding vote.
+19. The Chair must state their rationale when casting a tie-breaking vote.
+20. Tie-breaking decisions are flagged in meeting notes for CTO awareness.
+
+## Scope of Authority
+
+21. The ARB has authority over: platform architecture standards, vendor selection for
+    platform-level tooling, cross-domain API contracts, security architecture, and
+    data architecture patterns.
+22. The ARB does not have authority over: team-internal implementation choices, product
+    roadmap prioritization, staffing decisions, or budget approval.
+23. Any team may bring a decision to the ARB for guidance even if ARB approval is not strictly
+    required. The ARB may accept or decline to review.
+
+## ADR and RFC Approval
+
+24. The ARB is the default Approver for all ADRs tagged as architecture decisions.
+25. The ARB reviews RFCs at the Under Discussion stage. Approval converts an RFC to Accepted
+    and triggers ADR creation.
+26. The ARB may delegate Approver authority for a specific decision to a named individual or
+    sub-committee. Delegation is recorded in the relevant ADR/RFC.
+27. The ARB chair may approve urgent security-related ADRs unilaterally with 24-hour notice
+    to the full board, subject to ratification at the next session.
+
+## Escalation
+
+28. Escalation path: Team → Domain Lead → ARB → CTO.
+29. Any engineer may escalate a decision to the ARB by opening a GitHub issue in the
+    `keelcore/standards` repository labeled `arb-escalation`.
+30. The ARB must acknowledge escalations within three business days and schedule review
+    within ten business days.
+31. ARB decisions may be escalated to the CTO only on the grounds of: process violation,
+    conflict of interest, or organizational policy conflict. The CTO's decision is final.
+32. Escalation outcomes are published (with appropriate confidentiality) in the engineering wiki.
+
+## Standards Cadence
+
+33. The ARB publishes a versioned Architecture Standards snapshot at least once per quarter.
+    The snapshot is tagged in this repository as `arb-standards-YYYY-QN`.
+34. Each quarterly snapshot includes: new ADRs accepted since the last snapshot, standards
+    that changed maturity level, deprecated standards, and open RFCs in progress.
+35. The ARB reviews all standards marked `Deprecated` at least once per year to confirm
+    retirement or rescind deprecation.
+
+## Do Not
+
+- Allow a decision with quorum impact to proceed if quorum is not met.
+- Allow a member to vote on a decision where they have a declared conflict of interest.
+- Publish meeting notes without removing information subject to legal hold or HR confidentiality.
+- Allow the Chair to cast a non-tie-breaking vote.
+- Make ARB decisions without recording them in the engineering wiki within five business days.

package/governance/bash.md

@@ -0,0 +1,147 @@
+# Bash Script Standards
+
+These rules govern all bash scripts in this project. They are non-negotiable.
+
+**Maturity:** Required
+**Version:** 1.0.0
+**Last Reviewed:** 2026-03-09
+
+## Portability and Shell Baseline
+
+1. Google Bash style unless overridden by rules below.
+2. Darwin-compatible; Bash 3.x compatible — no `mapfile`, no `declare -A`.
+3. Shebang: `#!/usr/bin/env bash` always.
+4. Use the explicit shell options block (not `set -euo pipefail` shorthand).
+
+## Required Shell Options Block
+
+Every script begins with:
+
+```bash
+#!/usr/bin/env bash
+# <script name>
+# <functional description, with arguments if needed>
+
+# bash configuration:
+# 1) Exit script if you try to use an uninitialized variable.
+set -o nounset
+
+# 2) Exit script if a statement returns a non-true return value.
+set -o errexit
+
+# 3) Use the error status of the first failure, rather than that of the last item in a pipeline.
+set -o pipefail
+```
+
+## Script Structure
+
+5. `main` is the FIRST function defined in the file.
+6. `main "${@:-}"` is the LAST line of the file.
+7. Always provide the complete script, never a patch or diff.
+8. Never omit any referenced function.
+
+## Functions
+
+9. All function declarations preceded by keyword `function`.
+10. No `function_` prefix on function names.
+11. Function names: lowercase, simple, reflect intent.
+12. One statement per line.
+13. No function body > 10 lines unless reduction is genuinely impossible.
+14. Prefer decomposition into small, reusable helpers.
+15. Load-bearing functions: log intent first, then log result.
+
+## Arguments and Validation
+
+16. Validate argument count.
+17. Validate required arguments are non-null.
+18. Support empty argument lists under `set -u` using `"${@:-}"`.
+19. `validate_args` must allow an empty first argument when zero arguments are valid:
+
+```bash
+function validate_args() {
+  if [ "${#}" -gt 0 ] && [ -z "${1:-}" ]; then
+    log '❌ Error: Unexpected empty argument'
+    exit 1
+  fi
+}
+```
+
+## Variables
+
+20. Always `"${var}"` style for variable expansion.
+21. Quote expansions unless unquoted behavior is explicitly required.
+22. `local -r` for immutable locals NOT assigned from subshell.
+23. Mutable locals or subshell-assigned: declare on one line, assign on next:
+
+```bash
+local result
+result="$(some_command)"
+```
+
+24. Single quotes for literal strings with no expansion needed.
+
+## Logging and Output
+
+25. Route all messaging through a `log` function.
+26. `log` must tee to a well-known log file.
+27. Capture original stdout in `main` with `exec 5>&1`; `log` writes to FD 5.
+28. Use emoji for key accomplishments.
+29. Load-bearing functions log both intent and result.
+
+## Printing
+
+30. Prefer `printf` over `echo`.
+31. `printf` format string must be single-quoted with explicit format specifiers.
+32. Use `echo` only with no parameters and no formatting concerns.
+
+## Standard `log` Function Pattern
+
+```bash
+function log() {
+  local msg
+  msg="${1:-}"
+  printf '%s\n' "${msg}" | tee -a '/tmp/SCRIPTNAME.log' >&5
+}
+```
+
+## Standard `main` Pattern
+
+```bash
+function main() {
+  exec 5>&1
+  validate_args "${@:-}"
+  # ... work ...
+}
+# ... helper functions ...
+main "${@:-}"
+```
+
+## GitHub Actions `validate_args` Quirk
+
+In GitHub Actions, `shell: bash` expands an empty `$@` to a single empty-string argument when
+using `"${@:-}"`. Unadjusted, this triggers the argument check spuriously. Apply the following
+fixups based on script type:
+
+**Zero-argument scripts** — tolerate the single-empty-string artifact; reject any real arg:
+
+```bash
+function validate_args() {
+  if [ "${#}" -gt 1 ] || [ -n "${1:-}" ]; then
+    log '❌ Error: Unexpected argument'
+    exit 1
+  fi
+}
+```
+
+**Argument-taking scripts** — tolerate the artifact; still catch multiple or non-empty extra args:
+
+```bash
+function validate_args() {
+  if [ "${#}" -gt 1 ] && [ -n "${1:-}" ]; then
+    log '❌ Error: Too many arguments'
+    exit 1
+  fi
+}
+```
+
+Do NOT change the call site from `"${@:-}"` to `"$@"` — fix the body only.