fix: feat: define vault action TOML schema for PR-based approval (#74)

- Add vault/SCHEMA.md documenting the TOML schema for vault actions
- Add validate_vault_action() function to vault/vault-env.sh that:
  - Validates required fields (id, formula, context, secrets)
  - Validates secret names against allowlist
  - Rejects unknown fields
  - Validates formula exists in formulas/
- Create vault/validate.sh script for CLI validation
- Add example TOML files in vault/examples/:
  - webhook-call.toml: Example calling external webhook
  - promote.toml: Example promoting build/artifact
  - publish.toml: Example publishing to ClawHub

vault/SCHEMA.md

@@ -0,0 +1,81 @@
+# Vault Action TOML Schema
+
+This document defines the schema for vault action TOML files used in the PR-based approval workflow (issue #74).
+
+## File Location
+
+Vault actions are stored in `vault/actions/<action-id>.toml` on the ops repo.
+
+## Schema Definition
+
+```toml
+# Required
+id = "publish-skill-20260331"
+formula = "clawhub-publish"
+context = "SKILL.md bumped to 0.3.0"
+
+# Required secrets to inject
+secrets = ["CLAWHUB_TOKEN"]
+
+# Optional
+model = "sonnet"
+tools = ["clawhub"]
+timeout_minutes = 30
+```
+
+## Field Specifications
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier for the vault action. Format: `<action-type>-<date>` (e.g., `publish-skill-20260331`) |
+| `formula` | string | Formula name from `formulas/` directory that defines the operational task to execute |
+| `context` | string | Human-readable explanation of why this action is needed. Used in PR description |
+| `secrets` | array of strings | List of secret names to inject into the execution environment. Only these secrets are passed to the container |
+
+### Optional Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | `sonnet` | Override the default Claude model for this action |
+| `tools` | array of strings | `[]` | MCP tools to enable during execution |
+| `timeout_minutes` | integer | `60` | Maximum execution time in minutes |
+
+## Secret Names
+
+Secret names must be defined in `.env.vault.enc` on the ops repo. The vault validates that requested secrets exist in the allowlist before execution.
+
+Common secret names:
+- `CLAWHUB_TOKEN` - Token for ClawHub skill publishing
+- `GITHUB_TOKEN` - GitHub API token for repository operations
+- `DEPLOY_KEY` - Infrastructure deployment key
+
+## Validation Rules
+
+1. **Required fields**: `id`, `formula`, `context`, and `secrets` must be present
+2. **Formula validation**: The formula must exist in the `formulas/` directory
+3. **Secret validation**: All secrets in the `secrets` array must be in the allowlist
+4. **No unknown fields**: The TOML must not contain fields outside the schema
+5. **ID uniqueness**: The `id` must be unique across all vault actions
+
+## Example Files
+
+See `vault/examples/` for complete examples:
+- `webhook-call.toml` - Example of calling an external webhook
+- `promote.toml` - Example of promoting a build/artifact
+- `publish.toml` - Example of publishing a skill to ClawHub
+
+## Usage
+
+Validate a vault action file:
+
+```bash
+./vault/validate.sh vault/actions/<action-id>.toml
+```
+
+The validator will check:
+- All required fields are present
+- Secret names are in the allowlist
+- No unknown fields are present
+- Formula exists in the formulas directory