feat(governance): block agent edits to goals/priorities/directives (Layer 1)

[kokevidaurre]

Summary

Layer 1 of the founder governance epic (#764) — the highest-leverage piece.

Agents can no longer Edit/Write governance files (goals.md, priorities.md, directives.md, SQUAD.md). The authority rule existed as convention but was unenforced; agents have been observed resetting goals to fit their own logic and contradicting directives. Drift accumulates over runs.

Changes

• templates/guardrail.json — extended PreToolUse with an Edit|Write|MultiEdit matcher that blocks governance-file paths. Exit code 2 with a clear redirect message.
• templates/proposed/README.md — documents the suggestion channel pattern. Agents write proposals to .squads/proposed/<file>-<date>-<slug>.md instead of editing canonical files.
• docs/governance.md — authority-by-file table, enforcement mechanism, founder override.

How it works

agent: Edit /path/.agents/memory/engineering/goals.md
hook:  exit 2 — "BLOCKED: ... is a governance file. Propose changes by writing to .squads/proposed/..."
agent: Write /path/.squads/proposed/goals-engineering-20260425-add-mobile.md
hook:  exit 0 (allowed)

Founder's own Claude Code sessions don't pass through the agent guardrail, so direct edits work normally.

Tested

• ✅ Hook blocks */goals.md (exit 2)
• ✅ Hook allows */state.md, */learnings/* (exit 0)
• ✅ JSON validates

Out of scope (separate PRs in #764)

• Layer 2: actual .squads/proposed/ scaffold in squads init (this PR adds the README template only)
• Layer 3: squads coherence command
• Layer 4: goal-linked GitHub issue template

Test plan

• CI green
• Manual: run an agent, ask it to edit goals.md, confirm it's blocked with the redirect message
• Manual: ask the same agent to edit state.md, confirm it succeeds

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[gemini-code-assist]

Code Review

This pull request introduces a squad governance model that restricts autonomous agents from directly editing core governance files, such as goals and priorities, by implementing a guardrail hook. The changes include new documentation for the governance model and a proposal workflow for agents. However, the guardrail implementation in templates/guardrail.json has several technical issues, including a bypass for files in the root directory, incorrect JSON key extraction for tool inputs, and inconsistencies in the suggested naming convention for proposals.

[gemini-code-assist]

The guardrail implementation has several technical issues that could lead to bypasses or poor user experience:

1. Root Path Bypass: The glob patterns (e.g., */goals.md) only match files in subdirectories. Governance files located in the root directory (e.g., goals.md, SQUAD.md) will not be blocked, which contradicts the documentation in docs/governance.md implying **/ coverage.
2. Key Mismatch: The script extracts file_path, but many agent tools (including standard Claude Code tools) use the key path. This would cause the guardrail to miss the target file entirely.
3. MultiEdit Support: The MultiEdit tool typically operates on a list of files. This one-liner only checks a single top-level field, allowing governance files to be modified if they are part of a batch edit.
4. Naming Inconsistency: The suggested filename format in the error message results in goals.md-YYYYMMDD.md, whereas the convention in templates/proposed/README.md uses a slug and avoids double extensions (e.g., goals-YYYYMMDD-slug.md).

Suggested change

"command": "bash -c 'path=$(echo \"$CLAUDE_TOOL_INPUT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get(\\\"file_path\\\",\\\"\\\"))\" 2>/dev/null || true); case \"$path\" in */goals.md|*/priorities.md|*/directives.md|*/SQUAD.md) echo \"BLOCKED: $path is a governance file. Only the founder can edit goals/priorities/directives/SQUAD identity. Propose changes by writing to .squads/proposed/<filename>-$(date +%Y%m%d).md instead — the founder reviews and merges.\" >&2; exit 2;; esac'",

"command": "bash -c 'path=$(echo \"$CLAUDE_TOOL_INPUT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get(\\\"path\\\", d.get(\\\"file_path\\\", \\\"\\\")))\" 2>/dev/null || true); case \"$path\" in goals.md|*/goals.md|priorities.md|*/priorities.md|directives.md|*/directives.md|SQUAD.md|*/SQUAD.md) echo \"BLOCKED: $path is a governance file. Only the founder can edit goals/priorities/directives/SQUAD identity. Propose changes by writing to .squads/proposed/$(basename \\\"$path\\\" .md)-$(date +%Y%m%d)-slug.md instead — the founder reviews and merges.\" >&2; exit 2;; esac'",