guard-authoring

name	guard-authoring
description	Author, approve, and maintain project guard profiles (.wipnote/guard-profile.yaml). Use for custom quality/completion/yolo gates, polyglot monorepo per-directory guards, re-approving after drift, and understanding the trust boundary and autodetection fallback.

Guard Authoring Skill

Trigger keywords: guard profile, guard init, quality gate, completion gate, yolo gate, applies_when, guard authoring, re-approve guard, guard drift

---

What a guard profile is

.wipnote/guard-profile.yaml is a hand-maintained YAML file committed to the repository. It replaces wipnote's manifest autodetection with an explicit, version-controlled list of commands. Treat it like any other config file — diff it, review it in PRs, edit it when your toolchain changes. See docs/guard-profiles.md for the full reference.

---

Schema

guards:
  quality:          # run by `wipnote check --gate`
    - name: go-build               # short identifier (required)
      cmd: go build ./...          # shell command (required, non-empty)
      cwd: backend                 # repo-root-relative working dir (optional)
      applies_when:                # narrow when guard is active (optional)
        paths: ["backend/**/*.go"] # ** matches zero or more path segments
  completion:       # work-item completion gate
    - name: go-test
      cmd: go test ./...
  yolo:             # per-commit gate in yolo sessions
    - name: go-vet
      cmd: go vet ./...
approved:
  signature: "sha256:..."   # content hash; written by wipnote, never by hand
  by: "Alice"
  at: "2026-01-15T10:30:00Z"

Fields: name (required), cmd (required, non-empty), cwd (optional, repo-root-relative), applies_when.paths (optional forward-slash globs — ** crosses /, * does not). Do not hand-edit approved.signature.

---

Polyglot / monorepo example

guards:
  quality:
    - name: go-test
      cmd: go test ./...
      cwd: backend
      applies_when:
        paths: ["backend/**/*.go"]
    - name: npm-test
      cmd: npm test
      cwd: frontend
      applies_when:
        paths: ["frontend/**"]
    - name: py-test
      cmd: uv run pytest
      cwd: dataservice
      applies_when:
        paths: ["dataservice/**/*.py"]
  completion:
    - name: go-test
      cmd: go test ./...
      cwd: backend
      applies_when:
        paths: ["backend/**/*.go"]
  yolo:
    - name: go-vet
      cmd: go vet ./...
      cwd: backend
      applies_when:
        paths: ["backend/**/*.go"]
approved:
  signature: "sha256:..."
  by: "Alice"
  at: "2026-01-15T10:30:00Z"

cwd routes each toolchain to its subdirectory. applies_when.paths gates a guard on whether matching files EXIST in the repository — not on which files a commit changed (wipnote does not inspect the changed-file set). A guard whose globs match no repo file is skipped; one that matches any repo file runs on every gate. Use it to scope guards to a project layout, not to skip guards per-commit.

---

Approval model and trust boundary

wipnote only honors a profile when approved.signature matches the sha256 of the guard content. Falls back to autodetection (no error) when: profile absent, signature empty, signature mismatch (edited after approval), or validation failure (unknown phase key or empty cmd). The signature is order-independent — reformatting YAML does not break it, but changing any guard field does.

---

Launch-time setup and wipnote guard init

Every interactive launch (wipnote claude/yolo/dev/codex/gemini) auto-runs setup: if no approved profile exists and the launch is interactive, it proposes guards from manifests, prompts [y/N], and on y signs + commits the profile. Non-interactive launches skip silently.

wipnote guard init    # explicit: propose, review, approve, commit (re-runnable)

Run wipnote guard init after any edit to re-approve and record a fresh signature.

---

Safe default

No approved profile → autodetection from go.mod, package.json, Makefile, etc., with a hint to run wipnote guard init. Use a committed profile for custom commands, subdirectory routing, or applies_when filtering.