Skip to content

feat(guardrail): add git freshness, merge gate, test falsifiability, doc reminder hooks #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
terisuke merged 1 commit into from
Apr 6, 2026
Merged

feat(guardrail): add git freshness, merge gate, test falsifiability, doc reminder hooks #90

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 73 additions & 2 deletions packages/guardrails/profile/plugins/guardrail.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,19 @@ function str(data: unknown) {
return typeof data === "string" ? data : ""
}

async function git(dir: string, args: string[]) {
const proc = Bun.spawn(["git", "-C", dir, ...args], {
stdout: "pipe",
stderr: "pipe",
})
const [stdout, stderr] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
])
return { stdout, stderr }
Comment on lines +158 to +163
Copy link

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new git() helper drops the process exit code, so callers can’t distinguish a successful command from a failure (Bun.spawn won’t throw on non‑zero exit). Consider returning code (like the existing helper in team.ts) and using it in the freshness check to avoid warning on failed fetches.

Suggested change
const [stdout, stderr] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
])
return { stdout, stderr }
const [stdout, stderr, code] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
])
return { stdout, stderr, code }

Copilot uses AI. Check for mistakes.
}

function free(data: {
id?: unknown
providerID?: unknown
Expand Down Expand Up @@ -399,6 +412,8 @@ export default async function guardrail(input: {
edits_since_review: 0,
last_block: "",
last_reason: "",
git_freshness_checked: false,
review_state: "",
})
}
if (event.type === "permission.asked") {
Expand All @@ -415,6 +430,44 @@ export default async function guardrail(input: {
})
}
},
"chat.message": async (
item: {
sessionID: string
},
out: {
message: {
id: string
sessionID: string
role: string
}
parts: {
id: string
sessionID: string
messageID?: string
type: string
text: string
}[]
},
) => {
if (out.message.role !== "user") return
const data = await stash(state)
if (flag(data.git_freshness_checked)) return
await mark({ git_freshness_checked: true })
try {
const fetchCheck = await git(input.worktree, ["fetch", "--dry-run"])
if (fetchCheck.stdout.trim() || fetchCheck.stderr.includes("From")) {
out.parts.push({
id: crypto.randomUUID(),
sessionID: out.message.sessionID,
messageID: out.message.id,
type: "text",
text: "⚠️ Your branch may be behind origin. Consider running `git pull` before making changes.",
})
}
} catch {
// git fetch may fail in offline or no-remote scenarios; skip silently
}
Comment on lines +456 to +469
Copy link

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

chat.message awaits git fetch --dry-run inline. If the remote is slow/hung (DNS, credentials prompt, etc.), this hook can delay handling the user message. Consider adding a short timeout (and/or running the fetch in a detached task) so the guardrail doesn’t block the chat pipeline.

Copilot uses AI. Check for mistakes.
},
"tool.execute.before": async (
item: { tool: string; args?: unknown },
out: { args: Record<string, unknown> },
Expand Down Expand Up @@ -450,6 +503,13 @@ export default async function guardrail(input: {
await mark({ last_block: "bash", last_command: cmd, last_reason: "shell access to protected files" })
throw new Error(text("shell access to protected files"))
}
if (/\b(git\s+merge|gh\s+pr\s+merge)\b/i.test(cmd)) {
const data = await stash(state)
if (str(data.review_state) !== "done") {
await mark({ last_block: "bash", last_command: cmd, last_reason: "merge blocked: review not done" })
throw new Error(text("merge blocked: run /review before merging"))
}
Comment on lines +506 to +511
Copy link

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The merge gate regex will also match non-merge commands like git merge-base (because merge is a prefix and the trailing \b still matches before -). Tighten the pattern to require merge as a whole subcommand (e.g., git\s+merge(\s|$) / gh\s+pr\s+merge(\s|$)) to avoid blocking read-only git queries.

Copilot uses AI. Check for mistakes.
}
if (!bash(cmd)) return
if (!cfg.some((rule) => rule.test(file)) && !file.includes(".opencode/guardrails/")) return
await mark({ last_block: "bash", last_command: cmd, last_reason: "protected runtime or config mutation" })
Expand All @@ -458,7 +518,7 @@ export default async function guardrail(input: {
},
"tool.execute.after": async (
item: { tool: string; args?: Record<string, unknown> },
_out: { title: string; output: string; metadata: Record<string, unknown> },
out: { title: string; output: string; metadata: Record<string, unknown> },
) => {
const now = new Date().toISOString()
const file = pick(item.args)
Expand Down Expand Up @@ -508,13 +568,23 @@ export default async function guardrail(input: {
if ((item.tool === "edit" || item.tool === "write") && file) {
const seen = list(data.edited_files)
const next = seen.includes(rel(input.worktree, file)) ? seen : [...seen, rel(input.worktree, file)]
const nextEditCount = num(data.edit_count) + 1
await mark({
edited_files: next,
edit_count: num(data.edit_count) + 1,
edit_count: nextEditCount,
edit_count_since_check: num(data.edit_count_since_check) + 1,
edits_since_review: num(data.edits_since_review) + 1,
last_edit: rel(input.worktree, file),
review_state: "",
})
Comment on lines 568 to 579
Copy link

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

review_state is reset only for edit/write, but other mutating tools (apply_patch, multiedit, and mutating bash like sed -i/redirects) can change the worktree without clearing review_state. That can let a stale /review incorrectly satisfy the merge gate. Consider resetting review_state (and incrementing edits_since_review) for all mutation paths, not just edit/write.

Copilot uses AI. Check for mistakes.

if (/\.(test|spec)\.(ts|tsx|js|jsx)$|^test_.*\.py$|_test\.go$/.test(rel(input.worktree, file))) {
Copy link

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Python test-file detector only matches files at the repo root (^test_.*\.py$). It won’t trigger for common layouts like tests/test_foo.py. Adjust the regex to match test_*.py in any directory (e.g., (^|/)test_.*\.py$) so the reminder fires as intended.

Suggested change
if (/\.(test|spec)\.(ts|tsx|js|jsx)$|^test_.*\.py$|_test\.go$/.test(rel(input.worktree, file))) {
if (/\.(test|spec)\.(ts|tsx|js|jsx)$|(^|\/)test_.*\.py$|_test\.go$/.test(rel(input.worktree, file))) {

Copilot uses AI. Check for mistakes.
out.output += "\n\n🧪 Test file modified. Verify this test actually FAILS without the fix (test falsifiability)."
}

if (code(file) && nextEditCount > 0 && nextEditCount % 3 === 0) {
out.output += "\n\n📝 Source code edited (3+ operations). Check if related documentation (README, AGENTS.md, ADRs) needs updating."
}
}

if (item.tool === "task") {
Expand All @@ -525,6 +595,7 @@ export default async function guardrail(input: {
reviewed: true,
review_at: now,
review_agent: agent,
review_state: "done",
edits_since_review: 0,
})
}
Expand Down
Loading