Skip to content

Verification Gate

Jump to bottom
Chris Sweet edited this page Jun 12, 2026 · 3 revisions

type: concept up: "Three-Operations" extends: "Three-Operations" tags: [policy, safety]

Verification Gate

A four-criteria pre-commit checklist the agent runs before committing any wiki change, with concrete "fix if failed" actions for each. Introduced by PR #1.

The four criteria

Criterion Fix if failed
Index updated? Update index_<repo>.md before committing
Log entry appended? Append per Log-Entry-Attribution
Cross-references bidirectional? Add the inverse links on the affected pages
Frontmatter present and non-untyped? Add frontmatter; assign a proper type

The criteria are paired with their fix actions, so the gate is actionable, not aspirational. Priscila's review feedback specifically called out this property: "each verification criterion having a concrete fix-if-failed makes the gate actionable rather than aspirational."

Why it exists

Without an explicit gate, ingest commits silently drift away from the conventions: index updates get missed, log entries get skipped, back-references go unlinked. The gate forces a single conscious checkpoint before commit, with an unambiguous remedy for each criterion.

Where it lives

The gate is defined once in wiki/agents/verification-gate.md (agent-agnostic) and referenced from the per-overlay procedures rather than duplicated:

  • Claude Code: .claude/skills/wiki-experiment.md, .claude/skills/wiki-source.md, plus the slash-command copies in .claude/commands/
  • Cursor: .cursor/rules/wiki-experiment.mdc, .cursor/rules/wiki-source.mdc

This referencing pattern is the DRY mechanism that keeps the Agent-Overlays consistent.

Relationship to the PostToolUse hook

The optional PostToolUse-Hook is an advisory reminder that fires on every Write or Edit and tells the agent to run the gate. The gate is the policy; the hook is one possible nudge to invoke it. They are complementary, and the hook is opt-in.

/wiki-lint and the gate

The current template does not invoke the verification gate from /wiki-lint; the rationale is that lint is the corrective pass, so gating it on the criteria it produces is somewhat circular. A lighter lint-specific gate is a possible future addition. Priscila raised this in PR #1 review as point 5 and it was left open by mutual agreement.

See also

Clone this wiki locally