control-plane-validation
Canonical workflow for validating changes to this repository's control plane — establishes Git baseline, classifies each changed path by owning plane, checks current official Codex docs for format drift, runs tools/control-plane/verify.mjs and syntax/unit tests for changed scripts, inspects git diff --check, and reports exact diff scope while distinguishing tested evidence from assumptions. Use whenever work touches AGENTS.md, .codex/**, .agents/**, .claude/**, control-plane tooling (tools/control-plane/**), source-control governance, CI governance (.github/workflows/**), or production-policy documentation (docs/control-plane/**, netlify.toml).
- License 许可
- MIT
- 最近更新
- 2026-10-02
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- control-plane-validation
- description
- Canonical workflow for validating changes to this repository's control plane — establishes Git baseline, classifies each changed path by owning plane, checks current official Codex docs for format drift, runs tools/control-plane/verify.mjs and syntax/unit tests for changed scripts, inspects git diff --check, and reports exact diff scope while distinguishing tested evidence from assumptions. Use whenever work touches AGENTS.md, .codex/**, .agents/**, .claude/**, control-plane tooling (tools/control-plane/**), source-control governance, CI governance (.github/workflows/**), or production-policy documentation (docs/control-plane/**, netlify.toml).
02 资源文件 3
- 参考文档references/evidence-schema.md5.0 KB
- 参考文档references/topology.md6.8 KB
- 脚本scripts/run-checks.mjs11.6 KB
03 SKILL.md 正文
Control Plane Validation
Contents
- Objective
- Authority statement (non-negotiable)
- Trigger scope
- Workflow
- Owning-plane classification
- Evidence and status vocabulary
- Failure handling
- Resources
1. Objective
Prove — with fresh, on-disk evidence — that a change touching this repository's control plane is structurally sound and correctly scoped, without ever implying that a passing check authorizes shipping it. This skill produces a validation report; it does not implement fixes, and it never pushes, merges, or deploys.
The default deliverable is:
- a Git baseline (branch, HEAD, dirty-state inventory);
- a per-path plane classification for every changed file;
- a Codex-docs drift check for any changed Codex-native file format;
- a
tools/control-plane/verify.mjsrun; - syntax/unit-test evidence for changed scripts;
- a
git diff --checkinspection; - an exact diff-scope report;
- an explicit evidence-vs-assumption breakdown;
- a release-readiness statement that is blocked, not guessed, when required checks are unavailable.
2. Authority statement (non-negotiable)
State these explicitly in every report this skill produces, not just once at skill-authoring time:
- Skills are workflow knowledge, not permission grants. This skill tells you how to validate a control-plane change once you are already permitted to look at and edit those files. It does not itself authorize any tool call, write, commit, or publication.
- Hooks are guardrails, not complete authorization. A hook firing (or not firing) is not proof that an action is safe or approved.
- Tests passing does not authorize push, merge, or deploy. A green
tools/control-plane/verify.mjsrun, a green Biome check, or a greennode --testrun is evidence (§1.11 of the migration contract), not approval (§1.5). Approval is a separate, human act. mainpublication triggers Netlify production. Merging tomainis an automatic, public production deploy with no separate gate (netlify.tomlhas no branch/context restriction). Treat it with release-action weight every time, regardless of what this skill reports.
Full rationale: references/topology.md, "Authority statement" section.
3. Trigger scope
Run this skill when a task touches any of:
AGENTS.md,.agents/**,.codex/**,.claude/**;tools/control-plane/**(the verifier itself);- CI governance:
.github/workflows/**; - production-policy documentation:
docs/control-plane/**,netlify.toml; security/constitution.md(machine-readable security invariants thatAGENTS.mdrestates in prose).
If the task touches none of these, this skill does not apply — do not run it defensively on unrelated product-code changes.
4. Workflow
Copy and maintain this checklist for the current change:
Control Plane Validation Progress
- [ ] 1. Establish Git baseline and dirty state
- [ ] 2. Identify owning plane for each changed path
- [ ] 3. Check current official Codex docs for format drift (if applicable)
- [ ] 4. Run tools/control-plane/verify.mjs
- [ ] 5. Run syntax/unit tests for changed scripts
- [ ] 6. Inspect git diff --check
- [ ] 7. Report exact diff scope
- [ ] 8. Distinguish tested evidence from assumptions
- [ ] 9. State release-readiness honestly (block the claim if unverifiable)
Step 1: Git baseline and dirty state
Do not trust a prior summary, .planning/** artifact, or this skill's own
reference files for current state — re-derive it:
git status --porcelain=v1
git rev-parse HEAD
git rev-parse --abbrev-ref HEAD
Or let the bundled script do it (see Step 4 — it captures the same baseline as part of one evidence object).
Step 2: Identify owning plane for each changed path
Classify every changed path against
references/topology.md's plane map. A path that
matches no row is out of this skill's scope — note it, do not force-fit a
plane onto it. Watch specifically for a single diff that touches two planes
in a way that collapses their separation (e.g. a rule file edit that also
adds executable logic, or a skill edit that also changes a permission
allowlist) — that is exactly the failure mode
docs/control-plane/MIGRATION_CONTRACT.md §3.3 calls out, and it is a
finding to surface, not silently pass through.
scripts/run-checks.mjs (Step 4) performs this classification
automatically and includes it in its JSON output under diffScope.
Step 3: Check current official Codex docs for format drift
Only required when the diff touches a Codex-native file format:
.codex/config.toml, .codex/hooks.json, .codex/rules/*.rules,
.codex/agents/*.toml, or .codex/workflows/**. tools/control-plane/verify.mjs
validates these files against this repository's current understanding of
their grammar (see its embedded TOML/execpolicy parsers) — it cannot detect
that Codex CLI's actual contract for one of these formats changed upstream.
When applicable, fetch the current official Codex CLI documentation for the
specific format(s) touched and compare against what
tools/control-plane/verify.mjs currently enforces. If network access is
unavailable, do not silently skip this — record it as UNVERIFIED (see
references/evidence-schema.md) and carry
that into Step 9's release-readiness statement.
When not applicable (the diff doesn't touch a Codex-native format), record that this step was correctly skipped and why — do not spend a network call proving a negative.
Step 4: Run tools/control-plane/verify.mjs
Run the bundled deterministic script, which wraps verify.mjs and adds
Steps 1, 2, 6, and 7 of this workflow in one evidence object:
node .agents/skills/control-plane-validation/scripts/run-checks.mjs
Or run the verifier directly if you only need its own checks:
node tools/control-plane/verify.mjs
Read every FAIL, including non-authoritative/informational ones (the
Claude-compatibility check is informational by design — see
tools/control-plane/verify.mjs's own comments — but still worth reporting
if it fails). Never treat a SKIPPED check as a PASS.
Step 5: Run syntax/unit tests for changed scripts
scripts/run-checks.mjs syntax-checks (node --check) every changed
.js/.mjs/.cjs file inside a recognized control-plane plane and reports
the results under syntaxCheck. This proves the file parses — it is not a
substitute for running its actual tests. Separately:
- if the change touches
tools/control-plane/verify.mjsor anything it imports, also run whatever test suite currently covers it (checktests/AGENTS.mdandtests/security/for a matching file — e.g.tests/security/codex-config.test.mjscovers.codex/config.tomlparseability); - if no test currently covers a changed control-plane script, say so explicitly rather than reporting untested code as verified.
Step 6: Inspect git diff --check
git diff --check
git diff --cached --check
scripts/run-checks.mjs runs both and classifies the result: real conflict
markers (<<<<<<<, =======, >>>>>>> at line start) are an authoritative
failure; trailing-whitespace-only findings are informational (this
repository has a known pre-existing trailing-whitespace finding in
.repository-hygiene/report.md — do not treat that class of finding as
blocking by default, but do report it).
Step 7: Report exact diff scope
State precisely which paths changed, their Git status code, and their
plane — not a paraphrase ("some control-plane files changed"). Use
diffScope.byPlane from the script output directly; it is already grouped
correctly. Call out outOfScopeCount if non-zero so the reader knows the
report is deliberately narrowed to control-plane paths, not silently
incomplete.
Step 8: Distinguish tested evidence from assumptions
Apply references/evidence-schema.md's
evidence-vs-assumption rule to every claim in the report: a claim is
evidence only if it is backed by this session's own script/tool output
or a freshly fetched doc; anything sourced from
docs/control-plane/CURRENT_STATE.md, MIGRATION_CONTRACT.md, a prior
summary, or this skill's own reference files is a hypothesis until
re-confirmed in this session.
Step 9: State release-readiness honestly
Follow references/evidence-schema.md's
"Blocking a release-ready claim" section. In particular: if Step 3 was
required and could not be performed, or tools/control-plane/verify.mjs
could not run at all, do not say the change is "ready" — say what is
unverified and why, plainly, in the same report.
5. Owning-plane classification
Full plane map, target topology, and authority statement: references/topology.md.
6. Evidence and status vocabulary
Full JSON shape for scripts/run-checks.mjs, the PASS/FAIL/SKIPPED/UNVERIFIED
vocabulary, and the evidence-vs-assumption rule:
references/evidence-schema.md.
7. Failure handling
tools/control-plane/verify.mjsfails to load or throws: report it as a tool failure (not a SKIPPED sub-check) and block any release-readiness claim — do not fall back to reasoning about control-plane correctness from memory.- Codex docs are unreachable for Step 3: mark that specific claim UNVERIFIED, do not treat the rest of the report as invalidated, and do not silently drop the step from the checklist.
- A changed path does not match any plane rule: report it explicitly as unclassified rather than guessing a plane or omitting it from the diff scope.
git diff --checkreports real conflict markers: stop and resolve them before any further validation — a diff with conflict markers is not in a reviewable state.- No test currently covers a changed control-plane script: report that gap by name; do not report the script as verified because it parses.
8. Resources
Load only what the current step requires:
- Plane ownership map, target topology, authority statement: references/topology.md
- Evidence JSON shape, status vocabulary, evidence-vs-assumption rule, release-readiness gating: references/evidence-schema.md
- Deterministic evidence collector (wraps
tools/control-plane/verify.mjs): scripts/run-checks.mjs - Underlying cross-runtime verifier (not owned by this skill — read, don't
fork it):
tools/control-plane/verify.mjs - Full migration contract this skill operationalizes:
docs/control-plane/MIGRATION_CONTRACT.md - Point-in-time baseline the contract was derived from:
docs/control-plane/CURRENT_STATE.md
Before treating this skill itself as validated after an edit, run:
node .agents/skills/control-plane-validation/scripts/run-checks.mjs
node tools/control-plane/verify.mjs
and confirm the agents-skills:control-plane-validation check reports
PASS (valid name/description frontmatter) and that neither run reports
this skill's own files as .gitignore-hidden. Only report Done &
Verified when that fresh run backs the claim — not this file's own
memory of a prior run.
04 同仓库更多 Skills
sample
Fixture skill.
sample
A minimal fixture skill used only to exercise the verifier.
sample
A minimal fixture skill used only to exercise the verifier.
sample
A minimal fixture skill used only to exercise the verifier.
sample
A minimal fixture skill used only to exercise the verifier.
sample
A minimal fixture skill used only to exercise the verifier.