Skip to content

Process capabilities: raise from 4/5 to 5/5 (enterprise quality audit) #126

Description

@Kravalg

Description

This issue was produced by the automated enterprise quality & NFR audit (2026-07-02), which audited the repository against the quality attributes from Wikipedia's "List of system quality attributes" plus AI-native development readiness. Attribute: process capabilities (cluster: Governance, Process & Compliance), current score 4/5. Audit justification: Process maturity is high and largely institutionalized: 16 focused workflows with least-privilege permissions, a documented 1:1 mapping from every CI check to a local make target (docs/sre-operations.md, docs/ci-architecture.md), a labeled override process for destructive infra changes ('allow-destructive-infra-change'), PR/issue templates, CodeRabbit with request_changes_workflow (.coderabbit.yaml), and agent-specific process rules in AGENTS.md. The gaps are enforcement, not definition: required checks exist only as prose ('should be required in branch protection' in docs/ci-quality-gates.md) rather than as codified rulesets, and the conventional-commit convention that autorelease.yml depends on is not machine-enforced — git history already contains non-conforming commits ('Update README.md', 'Fix autorelease version source'). Identified gaps: Branch protection / required checks are documented but not codified — docs/ci-quality-gates.md says its PR-blocking table 'should be required in branch protection', but nothing in the repo enforces or verifies that (no GitHub ruleset export, no settings-as-code, no structural test asserting required-check names). Downstream repos created from the template inherit the workflows but not the protection, so the entire gate system can be silently bypassed by merging with failing or skipped checks. Conventional commits are relied on by autorelease but never enforced — autorelease.yml derives versions and changelogs from conventional-commit messages (TriPSs/conventional-changelog-action), yet no commitlint or PR-title check exists, and CONTRIBUTING.md never mentions the convention. Non-conforming commits already in history ('Update README.md', 'Fix autorelease version source') show the process leaks, which corrupts semver inference for release automation.

Tasks

  • Commit a repository ruleset definition (e.g. .github/rulesets/main.json applied via gh api, or a Probot/settings.yml approach) listing the required status checks from docs/ci-quality-gates.md
  • Add a scheduled or structural check (tests/pulumi or nightly-guardrails.yml) that queries the branch-protection/ruleset API and fails when required checks drift from the documented table
  • Document the bootstrap step for downstream repos in docs/README.md Quick Start
  • Add a PR-title or commit-message lint job (e.g. amannn/action-semantic-pull-request pinned by SHA) to an existing PR workflow such as security-scans.yml or a new lightweight workflow
  • Document the required commit format and allowed types/scopes in CONTRIBUTING.md
  • Enable squash-merge-with-PR-title guidance so a single lint point controls the released history

Acceptance Criteria

  • The set of required checks is version-controlled in the repo and matches docs/ci-quality-gates.md
  • An automated job fails when the live branch protection diverges from the committed definition
  • Template consumers have a documented one-command way to apply the same protection
  • A PR with a non-conventional title/commit fails a required check with an actionable message
  • CONTRIBUTING.md documents the commit convention that autorelease consumes
  • New commits on main all parse as conventional commits
  • Attribute re-scores 5/5 in a follow-up enterprise quality audit

Metadata

Metadata

Assignees

No one assigned

    Labels

    devopsdocumentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions