fix: [nomad-step-2] S2.6 — CI: vault policy fmt + validate + roles.yaml check (#884)

vault/policies/AGENTS.md

@@ -48,12 +48,43 @@ validation.
 1. Drop a file matching one of the four naming patterns above. Use an
    existing file in the same family as the template — comment header,
    capability list, and KV path layout should match the family.
-2. Run `tools/vault-apply-policies.sh --dry-run` to confirm the new
+2. Run `vault policy fmt -write <file>` to ensure consistent formatting.
+3. Run `vault policy validate <file>` locally to check syntax + semantics.
+4. Run `tools/vault-apply-policies.sh --dry-run` to confirm the new
    basename appears in the planned-work list with the expected SHA.
-3. Run `tools/vault-apply-policies.sh` against a Vault instance to
+5. Run `tools/vault-apply-policies.sh` against a Vault instance to
    create it; re-run to confirm it reports `unchanged`.
-4. The CI fmt + validate step lands in S2.6 (#884). Until then
-   `vault policy fmt <file>` locally is the fastest sanity check.
+
+## Policy lifecycle
+
+Adding a new policy is a three-step process:
+
+1. **Add policy HCL** — Drop a file in `vault/policies/` matching one of the
+   naming patterns. Run `vault policy fmt <file>` locally to ensure consistent
+   formatting.
+2. **Update roles.yaml** — Add a JWT auth role in `vault/roles.yaml` that
+   references the new policy name (basename without `.hcl`).
+3. **Attach to Nomad job** — In S2.4, add the policy to a jobspec's
+   `template { vault { policies = ["<policy-name>"] } }` stanza.
+
+CI enforces:
+
+- `vault policy fmt -check` — all `.hcl` files must be formatted
+- `vault policy validate` — syntax + semantic check (no unknown stanzas,
+  valid capabilities)
+- `roles.yaml` validator — each role must reference a policy that exists
+  in `vault/policies/`
+- secret-scan gate — no literal secrets in policy files (rare but
+  dangerous copy-paste mistake)
+
+## Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `vault policy fmt -check` fails | HCL not formatted (wrong indentation, trailing spaces) | Run `vault policy fmt -write <file>` |
+| `vault policy validate` fails | Unknown stanza, invalid capability, missing required field | Check Vault docs; valid capabilities: `read`, `list`, `create`, `update`, `delete`, `sudo` |
+| `roles.yaml` validator fails | Policy name in role doesn't match any `.hcl` basename | Ensure policy name = filename without `.hcl` |
+| secret-scan fails | Literal secret value embedded (e.g., `token = "abc123..."`) | Use env var reference (`$TOKEN`) or sops/age-encrypted secret |
 
 ## What this directory does NOT own
 
@@ -63,4 +94,3 @@ validation.
   (#881).
 - **Writing the secret values themselves.** That's S2.2 (#880) via
   `tools/vault-import.sh`.
-- **CI policy fmt + validate + roles.yaml check.** That's S2.6 (#884).