docs: strengthen collaboration governance and AGENTS engineering protocol (#263 )

* docs: harden collaboration policy and review automation

* ci(docs): remove unsupported lychee --exclude-mail flag

* docs(governance): reduce automation side-effects and tighten risk controls

* docs(governance): add backlog pruning and supersede protocol

* docs(agents): codify engineering principles and risk-tier workflow

* docs(readme): add centered star history section at bottom

* docs(agents): enforce privacy-safe and neutral test wording

* docs(governance): enforce privacy-safe and neutral collaboration checks

* fix(ci): satisfy rustfmt and discord schema test fields

* docs(governance): require ZeroClaw-native identity wording

* docs(agents): add ZeroClaw identity-safe naming palette

* docs(governance): codify code naming and architecture contracts

* docs(contributing): add naming and architecture good/bad examples

* docs(pr): reduce checkbox TODOs and shift to label-first metadata

* docs(pr): remove duplicate collaboration track field

* ci(labeler): auto-derive module labels and expand provider hints

* ci(labeler): auto-apply trusted contributor on PRs and issues

* fix(ci): apply rustfmt updates from latest main

* ci(labels): flatten namespaces and add contributor tiers

* chore: drop stale rustfmt-only drift

* ci: scope Rust and docs checks by change set

* ci: exclude non-markdown docs from docs-quality targets

* ci: satisfy actionlint shellcheck output style

* ci(labels): auto-correct manual contributor tier edits

* ci(labeler): auto-correct risk label edits

* ci(labeler): auto-correct size label edits

---------

Co-authored-by: Chummy <183474434+chumyin@users.noreply.github.com>

2026-02-16 05:59:04 -05:00

4.9 KiB

Raw Blame History

CI Workflow Map

This document explains what each GitHub workflow does, when it runs, and whether it should block merges.

Merge-Blocking vs Optional

Merge-blocking checks should stay small and deterministic. Optional checks are useful for automation and maintenance, but should not block normal development.

Merge-Blocking

.github/workflows/ci.yml (CI)
- Purpose: Rust validation (fmt, clippy, test, release build smoke) + docs quality checks when docs change
- Merge gate: CI Required Gate
.github/workflows/workflow-sanity.yml (Workflow Sanity)
- Purpose: lint GitHub workflow files (actionlint, tab checks)
- Recommended for workflow-changing PRs

Non-Blocking but Important

.github/workflows/docker.yml (Docker)
- Purpose: PR docker smoke check and publish images on main/tag pushes
.github/workflows/security.yml (Security Audit)
- Purpose: dependency advisories (cargo audit) and policy/license checks (cargo deny)
.github/workflows/release.yml (Release)
- Purpose: build tagged release artifacts and publish GitHub releases

Optional Repository Automation

.github/workflows/labeler.yml (PR Labeler)
- Purpose: scope/path labels + size/risk labels + fine-grained module labels (<module>:<component>)
- Additional behavior: provider-related keywords in provider/config/onboard/integration changes are promoted to provider:* labels (for example provider:kimi, provider:deepseek)
- Additional behavior: applies contributor tiers on PRs by merged PR count (experienced >=10, principal >=20, distinguished >=50)
- Additional behavior: risk + size labels are auto-corrected on manual PR label edits (labeled/unlabeled events); apply risk: manual when maintainers intentionally override automated risk selection
- High-risk heuristic paths: src/security/**, src/runtime/**, src/gateway/**, src/tools/**, .github/workflows/**
- Guardrail: maintainers can apply risk: manual to freeze automated risk recalculation
.github/workflows/auto-response.yml (Auto Response)
- Purpose: first-time contributor onboarding + label-driven response routing (r:support, r:needs-repro, etc.)
- Additional behavior: applies contributor tiers on issues by merged PR count (experienced >=10, principal >=20, distinguished >=50)
- Additional behavior: contributor-tier labels are treated as automation-managed (manual add/remove on PR/issue is auto-corrected)
- Guardrail: label-based close routes are issue-only; PRs are never auto-closed by route labels
.github/workflows/stale.yml (Stale)
- Purpose: stale issue/PR lifecycle automation
.github/dependabot.yml (Dependabot)
- Purpose: grouped, rate-limited dependency update PRs (Cargo + GitHub Actions)
.github/workflows/pr-hygiene.yml (PR Hygiene)
- Purpose: nudge stale-but-active PRs to rebase/re-run required checks before queue starvation

Trigger Map

CI: push to main, PRs to main
Docker: push to main, tag push (v*), PRs touching docker/workflow files, manual dispatch
Release: tag push (v*)
Security Audit: push to main, PRs to main, weekly schedule
Workflow Sanity: PR/push when .github/workflows/**, .github/*.yml, or .github/*.yaml change
PR Labeler: pull_request_target lifecycle events
Auto Response: issue opened/labeled, pull_request_target opened/labeled
Stale: daily schedule, manual dispatch
Dependabot: weekly dependency maintenance windows
PR Hygiene: every 12 hours schedule, manual dispatch

Fast Triage Guide

CI Required Gate failing: start with .github/workflows/ci.yml.
Docker failures on PRs: inspect .github/workflows/docker.yml pr-smoke job.
Release failures on tags: inspect .github/workflows/release.yml.
Security failures: inspect .github/workflows/security.yml and deny.toml.
Workflow syntax/lint failures: inspect .github/workflows/workflow-sanity.yml.
Docs failures in CI: inspect docs-quality job logs in .github/workflows/ci.yml.

Maintenance Rules

Keep merge-blocking checks deterministic and reproducible (--locked where applicable).
Prefer explicit workflow permissions (least privilege).
Use path filters for expensive workflows when practical.
Keep docs quality checks low-noise (markdownlint + offline link checks).
Keep dependency update volume controlled (grouping + PR limits).
Avoid mixing onboarding/community automation with merge-gating logic.

Automation Side-Effect Controls

Prefer deterministic automation that can be manually overridden (risk: manual) when context is nuanced.
Keep auto-response comments deduplicated to prevent triage noise.
Keep auto-close behavior scoped to issues; maintainers own PR close/merge decisions.
If automation is wrong, correct labels first, then continue review with explicit rationale.
Use superseded / stale-candidate labels to prune duplicate or dormant PRs before deep review.

4.9 KiB Raw Blame History