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

docs/governance.md

@@ -0,0 +1,49 @@
+# Squad governance model
+
+Squads are autonomous within bounds. Governance files set those bounds — and the founder owns them.
+
+## Authority by file
+
+| File | Owner | Updated by | Frequency |
+|------|-------|-----------|-----------|
+| `directives.md` | Founder + Cofounder | Founder | When strategy shifts |
+| `goals.md` (per squad) | Founder + Cofounder | Founder | Per release / quarter |
+| `priorities.md` (per squad) | Founder + Cofounder | Founder | Weekly review |
+| `SQUAD.md` | Founder | Founder | Rarely (atemporal identity) |
+| `state.md` | Squad agents | Workers + lead | Every run |
+| `learnings/` | Squad agents | Workers | Every run |
+| GitHub issues (tasks) | COO + agents | Anyone | Continuously |
+
+## Why the split
+
+Governance files set the **target**. Memory files capture the **trajectory**. If agents could rewrite both, they'd drift away from the founder's intent run by run — and fast. Letting agents write memory but not governance is the minimum viable separation.
+
+## How it's enforced
+
+The bundled `templates/guardrail.json` includes a PreToolUse hook that blocks `Edit`, `Write`, and `MultiEdit` to:
+- `**/goals.md`
+- `**/priorities.md`
+- `**/directives.md`
+- `**/SQUAD.md`
+
+When an agent tries to write one of these, the hook exits with code 2 and a message redirecting to `.squads/proposed/`.
+
+The founder's own Claude Code sessions don't pass through the agent guardrail, so direct edits work normally for governance owners.
+
+## How agents propose changes
+
+Instead of editing the canonical file, agents write to `.squads/proposed/<source-file>-<date>-<slug>.md`. See `.squads/proposed/README.md` for the format.
+
+The founder reviews proposals on a cadence (weekly, or per release) and merges accepted ones into the canonical files.
+
+## Coherence checks
+
+Run `squads coherence` (coming in the next release) to surface drift:
+- Are squad goals aligned with `directives.md`?
+- Are priorities grounded in goals?
+- Are governance files stale (>14 days)?
+- Are there pending proposals awaiting founder review?
+
+## Override
+
+In emergencies (security incident, broken release) the founder can edit governance files without going through proposals. There's no audit trail beyond git history — keep that as the source of truth.

templates/guardrail.json

@@ -10,6 +10,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "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'",
+            "timeout": 5
+          }
+        ]
       }
     ]
   }

templates/proposed/README.md

@@ -0,0 +1,51 @@
+# Proposed governance changes
+
+Agents cannot edit governance files directly (`goals.md`, `priorities.md`, `directives.md`, `SQUAD.md`). The PreToolUse guardrail blocks those writes.
+
+When an agent believes a governance file should change, it writes a proposal here instead.
+
+## Naming convention
+
+```
+.squads/proposed/<source-file>-<YYYYMMDD>-<short-slug>.md
+```
+
+Examples:
+- `goals-engineering-20260425-add-cross-platform.md`
+- `priorities-marketing-20260425-deprioritize-outbound.md`
+- `directives-20260425-shift-to-inbound-only.md`
+
+## Proposal format
+
+```markdown
+# Proposal: <one-line summary>
+
+**Target file:** `.agents/memory/<squad>/goals.md`
+**Source agent:** `<squad>/<agent>`
+**Reason:** <why this change is needed — link to data, executions, learnings>
+
+## Proposed change
+<exact diff or new content>
+
+## Impact
+<what this changes about the squad's behaviour>
+
+## Founder decision
+- [ ] Accepted — merged to canonical file on YYYY-MM-DD
+- [ ] Rejected — reason: ...
+- [ ] Deferred — revisit on YYYY-MM-DD
+```
+
+## Founder workflow
+
+Weekly (or per-release), the founder reviews proposals:
+
+```bash
+ls .squads/proposed/                          # see what's queued
+squads coherence                              # check for drift before deciding
+# review each proposal, decide
+# accepted: merge into canonical file, then move proposal to .squads/proposed/accepted/
+# rejected: move to .squads/proposed/rejected/ with reason in the file
+```
+
+The proposal channel is a **defer**, not a **block** — agents keep contributing ideas, the founder keeps governance authority.