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`).
rjmurillo · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rjmurillo/ai-agents --skill ai-agents-change-control技能说明
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
metadata:
routing:
role: conditional-adjunct
invoker: ai-agents-validation-and-qa
trigger: ai-agents-validation-and-qa points here to learn which gates a change class triggers
user-facing: false
AI Agents Change Control
How a change moves through this repository, and the rules that never bend. This repo runs verification-based enforcement. Evidence may live in the transcript, pull request, per-issue handoff, Serena memory, or an optional session log.
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 changewhat gates does this change triggerwhich rules are non-negotiablewhy does this gate exist
Process
Phase 1: Classify the change
Every change belongs to at least one class. A mixed change inherits the union of all its classes' obligations. Classify against the working tree, not against your intent: one staged file in a stricter class pulls the whole change up.
| 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 create or edit | Fires the adr-review debate gate (AGENTS.md "ADR Review": full panel only for executable enforcement or a rule other gates read, else a reduced panel; the debate log is required either way); governance changes need human approval plus an ADR |
The OPERATIVE investigation-only allowlist is the enforcement module scripts/modules/investigation_allowlist.py (docstring: "Single source of truth for investigation artifact path patterns"; consumed by validate_session_json.py, the session skill, and validate_investigation_claims.py). It allows 8 patterns as of 2026-07-30 (display form from get_investigation_allowlist_display()):
.project-toolkit/sessions/(session logs).project-toolkit/analysis/(investigation outputs).project-toolkit/retrospective/(learnings).serena/memories/(cross-session context).project-toolkit/security/(security assessments).project-toolkit/memory/(memory artifacts).project-toolkit/architecture/REVIEW-*(review artifacts).project-toolkit/critique/(critique outputs)
Former divergence, now closed: the ADR-034 text (.project-toolkit/architecture/ADR-034-investigation-session-qa-exemption.md:78-87) once listed only the first 5 paths, and #2958 reconciled it to the same 8 the module enforces. The code list is still what the gate enforces, so re-check the module rather than the ADR when they disagree.
One staged file outside the enforced list voids the exemption. The session then needs real QA evidence, or you split the work into two sessions.
Special case, generated trees. src/vs-code-agents/ and src/copilot-cli/agents/ are generated from templates/agents/*.shared.md. The .github/instructions/ tree and most of src/copilot-cli/ are generated from .claude/ sources. Never hand-edit a generated tree; edit the canonical source and regenerate (the operating procedure lives in ai-agents-generation-and-release, the seam rationale in ai-agents-architecture-contract). The generator enforces one direction itself: assert_no_claude_writes (build/scripts/build_all.py:888) diffs the .claude/ tree before and after the run, and any generator write there prints REQ-003-010 VIOLATION and exits 2 (lines 2229 to 2230 of the same file). ADR-108 carves out exactly one class, the template-owned skill files under .claude/skills/, which reach the guard as an allowlist. History note: on 2025-12-15 an agent "fixed" a drift failure by editing the canonical source to match the generated output; the commit was reverted. Drift output shows difference, not direction. Always ask which side is canonical before touching either.
Phase 2: Map the class to its triggered gates
| Class | Extra gates it triggers |
|---|