ai-agents-change-control

Change control for this repo. Classify a change (docs-only, investigation-only, code, plugin content, hook, workflow, ADR governance), map each class to the gates it triggers, and hold the non-negotiables with the incident behind each rule. Use when you say `classify this change`, `what gates does this change trigger`, `which rules are non-negotiable`. Do NOT use for producing test evidence (use `ai-agents-validation-and-qa`) or incident history (use `ai-agents-failure-archaeology`).

Aller à l'installation

Dépôt: rjmurillo/ai-agents
Dernière activité de la source: 4 août 2026 à 05:21
Langue détectée de SKILL.md: anglais
Étoiles: 41
Forks: 13

Options d'installation

Le prompt qui vérifie d'abord la source est sélectionné par défaut. Vous pouvez passer à une commande directe ou télécharger une copie locale.

Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.

Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.

npx skills add https://github.com/rjmurillo/ai-agents --skill ai-agents-change-control

La commande reste sur une seule ligne. Faites défiler horizontalement pour la vérifier avant de la copier.

Vous préférez une copie locale ? Téléchargez les fichiers actuellement disponibles dans SkillsMP.

Vérifiez les fichiers source

Lisez SKILL.md et les fichiers associés affichés par SkillsMP avant de décider de l'installer.

Explorateur de fichiers

5 fichiers

SKILL.md

Instructions source · Aperçu en lecture seule

Retour à la recherche Retour à l’installation

name	ai-agents-change-control
description	Change control for this repo. Classify a change (docs-only, investigation-only, code, plugin content, hook, workflow, ADR governance), map each class to the gates it triggers, and hold the non-negotiables with the incident behind each rule. Use when you say `classify this change`, `what gates does this change trigger`, `which rules are non-negotiable`. Do NOT use for producing test evidence (use `ai-agents-validation-and-qa`) or incident history (use `ai-agents-failure-archaeology`).
version	1.0.0
license	MIT

AI Agents Change Control

How a change moves through this repository, and the rules that never bend. This repo runs verification-based enforcement, not trust-based. The protocol states it directly: "Labels like 'MANDATORY' or 'NON-NEGOTIABLE' are insufficient. Each requirement MUST have a verification mechanism" (.agents/SESSION-PROTOCOL.md:36). Every rule below therefore names two things: the gate that enforces it, and the incident that created it. If you are tempted to argue with a rule, read its incident first.

Jargon used once: a "gate" is an automated check that blocks progress (commit, push, or merge) until satisfied. A "drift gate" compares generated output trees against their canonical sources. A "canonical source" is the single tree you are allowed to edit; everything generated from it is read-only output.

Triggers

classify this change
what gates does this change trigger
which rules are non-negotiable

Rule

Enforcement mechanism

Incident / rationale

No new bash scripts; Python for all new scripts

Review + .claude/rules/universal.md SHOULD 3 ("MUST NOT create new bash scripts")

ADR-042 (Accepted)

No logic in YAML workflows

ADR-006 + .claude/rules/universal.md MUST NOT 4

Workflow YAML cannot be tested locally. Amendment 2026-04-28 allows pure config-data YAML under 7 conditions in templates/platforms/ and build/ only; run: block logic stays banned

No em or en dashes in authored text

validate_dash_prohibition (scripts/validation/checks_dash.py via pre_pr.py) + dash-guard hook; tests/hooks/fixtures/ exempt

.claude/rules/universal.md MUST NOT 5: bot reviewers open one or more threads per dash, every PR (Issue #1923)

SHA-pin all GitHub Actions

Pre-commit hook + workflow validation (.agents/governance/PROJECT-CONSTRAINTS.md:162)

Tags are mutable, so pinning blocks supply-chain tag-moving. Operative rule: pin everything unless a human explicitly approves the GP-006 first-party actions/* tag allowance, and disclose the tension in your PR description when you hit it. Fuller writeup in references/incident-history.md

Generated and released hook artifacts fail closed and loud (ADR-066 D1, ADR-071). Scoped, not blanket: push guards fail open on infrastructure errors by design (.claude/hooks/PreToolUse/push_guard_base.py docstring); repo-wide audit tracked in #2271. Per-family table: ai-agents-architecture-contract Phase 3

validate_hook_anchoring.py, runtime-contract tests, named Lefthook jobs, and CI enforcement

#2205 customer wedge; policy reversal in the incident history

No version field in any plugin manifest or marketplace entry

pre_pr.py + validate-plugin-version-bump.yml

ADR-092: the field pins freshness to a hand-bumped string and conflicts across every concurrent PR (issue #4080 measured 14 of 22)

Block-style YAML arrays only in frontmatter

.agents/governance/PROJECT-CONSTRAINTS.md:224 ("Exceptions: None")

Copilot CLI frontmatter parser fails on CRLF and related formatting: github/copilot-cli#694, cited at PROJECT-CONSTRAINTS.md:220; ADR-044

.agents/HANDOFF.md is read-only

.claude/rules/universal.md MUST NOT 3

ADR-014 (Accepted): the monolithic handoff file bloated and became a chronic merge-conflict magnet; distributed handoffs replaced it

Memory-first: retrieval precedes reasoning

AGENTS.md Retrieval section; session-start gates

ADR-007: Serena memories are canonical, Forgetful supplementary. Search before building; do not re-derive settled decisions

"Matches/mirrors" claims must quote the canonical source verbatim

.claude/rules/canonical-source-mirror.md; heuristic citation check in pre_pr.py

FM-9 confident-incorrectness; PR #1887 in the incident history

No silent defaults

FM-10 detection table (.agents/governance/FAILURE-MODES.md:315-399); taste-lints and pre-push scans

PR #1965 verdict-parser; incident history

Session-file merge immutability

Retro rule; session-protocol validation

Session 1187 (incident history): take --theirs for main's session file, rename yours to the next number

No secrets, no force-push, no --no-verify, no direct commits to main

.claude/rules/universal.md MUST 1, MUST 5, MUST NOT 1, MUST NOT 2

Hooks are the enforcement surface; skipping them is self-disarming

Class	You touched	Marker or obligation
Docs-only	Markdown prose only; no code, no generated trees	QA evidence row `SKIPPED: docs-only` (case-insensitive; ADR-034 cites it as the pre-existing pattern)
Investigation-only	Nothing outside the ADR-034 allowlist (below)	QA evidence row `SKIPPED: investigation-only`
Code	Python, scripts, tests, libs	Full QA evidence per `.agents/governance/TESTING-RIGOR.md`; see `ai-agents-validation-and-qa`
Plugin content	Anything under `.claude/`, `src/claude/`, or `src/copilot-cli/`	No manifest edit. The `.claude-plugin/plugin.json` files carry no `version`; Claude Code resolves freshness from the commit SHA (ADR-092)
Git hook configuration	`lefthook.yml`	Named-job validation and relevant validator tests
Claude lifecycle hook	`.claude/hooks/**`, hook generators	Dual-registration sync; runtime-contract tests; `scripts/validation/validate_hook_anchoring.py`
Workflow	`.github/workflows/*.yml`	No logic in YAML (ADR-006); SHA-pinned actions; run changed workflows before push (AGENTS.md Always list)
ADR / governance	Any `ADR-*.md` or `SESSION-PROTOCOL.md` create or edit	Fires the `adr-review` multi-agent debate gate (AGENTS.md "ADR Review"); governance changes need human approval plus an ADR

Class	Extra gates it triggers
Docs-only	Scoped markdownlint on changed files; dash prohibition; session log still required
Investigation-only	Staged-file allowlist check in the pre-commit QA validator (ADR-034)
Code	Full test rigor: positive, negative, edge, branch coverage, mocked I/O; coverage floors 100 security / 80 business / 60 docs (AGENTS.md Standards)
Plugin content	Version-field gate at two layers: `pre_pr.py` wrapping `build/scripts/validate_plugin_version_bump.py` at pre-push, CI `.github/workflows/validate-plugin-version-bump.yml`
Hook	Anchoring validator; runtime-contract tests (`tests/build_scripts/test_generate_hooks_runtime_contract.py`); keep `.claude/settings.json` and `.claude/hooks/hooks.json` in sync by hand
Workflow	SHA-pin validation; yamllint style; local workflow run gate in pre-push (`SKIP_WORKFLOW_LOCAL_TEST` escape exists for unrunnable workflows; semantics in `ai-agents-config-catalog`)
ADR / governance	`adr-review` debate to consensus; blocking `git_hook_policy.py adr-review` Lefthook job
Any canonical-source edit	Drift gates: `uv run python build/generate_agents.py --validate` and `uv run python build/scripts/build_all.py --check`; CI mirrors in `agent-drift-detection.yml` and `drift-detection.yml`

Anti-pattern	Why it fails here
Editing a generated tree to silence a drift gate	Inverts the source of truth (2025-12-15 incident, reverted). Ask which side is canonical first
Using `[skip-drift-check]` or `commit-limit-bypass` without a stated reason and human approval	Bypass markers are audited; unexplained use reads as the session 1187 pattern
Adding a `version` back to a plugin.json or marketplace entry	The gate fails on the field's presence (ADR-092). Freshness already tracks the commit SHA, so the field only re-creates the merge conflict it was deleted for
Adding a fail-open wrapper so a broken hook "does not block anyone"	Rejected pattern (#2230, recorded in ADR-071): silent exit 0 disables the hook while looking like success, exactly the #2205 failure
Classifying a mixed session as investigation-only	One staged file outside the ADR-034 allowlist voids the exemption; split the work
Fixing a bot-flagged dash or style claim without byte-level verification	Bots false-positive; count the actual bytes before editing (PR #1873 observation: an em-dash flag on a line with zero em-dashes)
Citing ADR-008/033/035/062 fail-open language for a new hook	Stale; the operative policy is fail-closed and loud (the #2205 reversal, told in `references/incident-history.md`)
Re-arguing a settled non-negotiable in a PR thread	The incident column is the answer; new evidence goes in an ADR, which fires `adr-review`

ai-agents-change-control

Options d'installation

Vérifiez les fichiers source

AI Agents Change Control

Triggers

AI Agents Change Control

Triggers

Process

Phase 1: Classify the change

Phase 2: Map the class to its triggered gates

Phase 3: Run the gates, local to CI

Phase 4: Hold the non-negotiables

Anti-Patterns

Verification

Provenance and Maintenance

ai-agents-change-control

Informations de source

Options d'installation

Vérifiez les fichiers source

Plus depuis ce dépôt

AI Agents Change Control

Triggers

Plus depuis ce dépôt

AI Agents Change Control

Triggers

Process

Phase 1: Classify the change

Phase 2: Map the class to its triggered gates

Phase 3: Run the gates, local to CI

Phase 4: Hold the non-negotiables

Anti-Patterns

Verification

Provenance and Maintenance