synaptiai/trigger-policy

Trigger Policy

You own FlowTrigger safety. Triggers fire without direct user supervision in many cases (CI events, scheduled runs); the policy in this skill is the last line of defense against unintended-action triggers.

Iron Law

merge and release MUST appear in every trigger's policy.forbidden_actions. Triggers cannot grant Tier 3 autonomy regardless of any other configuration. This is non-negotiable.

Inputs

The invoking command MUST pass:

1. Trigger YAML path — either a template under plugins/flow/triggers/templates/ or a project-local trigger at .flow/triggers/<id>.trigger.yaml.
2. Mode — validate | enforce. Validate is read-only (used by /flow:trigger validate); enforce is the gate before /flow:trigger run actually dispatches the target command.

Outputs

Structured JSON report:

{
  "trigger_id": "pr-123-watch",
  "schema_valid": true,
  "tier3_violations": [],
  "recursion_violations": [],
  "missing_required_forbidden": [],
  "cross_reference_violations": [],
  "concurrency_violations": [],
  "overall": "pass"
}

Exit code: 0 on pass; 1 on policy violation; 2 on schema invalid.

Workflow

Step 1: Schema validation

python3 -m jsonschema -i "${TRIGGER_YAML}" "plugins/flow/schemas/v1/trigger.schema.json"

Failure → overall: schema_invalid (exit 2).

Step 2: Tier 3 absolute deny

Verify policy.forbidden_actions contains both merge AND release. Missing either → tier3_violations.append({"action": "merge_or_release", "reason": "must be forbidden"}). Hard fail.

Step 3: Recursion policy check

Verify recursion_policy.triggered_runs_may_create_triggers is false (or unset; default is false). Same for triggered_runs_may_modify_triggers and triggered_runs_may_enable_triggers. Any set to true requires explicit Tier 3 authorization — surface as recursion_violations and require AskUserQuestion at /flow:trigger create time.

Step 4: Allowed-types check

Verify trigger.type is in flow.triggers.allowedTypes (cascade-resolved; default [manual, hook, loop_prompt]). Trigger types github_actions | local_cron | local_daemon are valid schema but disabled in v3.0 — surface as tier3_violations if the project's setting doesn't permit them.

Step 5: Active-trigger count

Count .flow/triggers/*.trigger.yaml files with metadata.enabled: true AND lifecycle != disabled. If count >= flow.triggers.maxActiveTriggers (cascade-resolved; default 5), refuse to enable a new trigger. The user must /flow:trigger disable an existing one first.

Step 6: Concurrency sanity check

If concurrency.policy: cancel_previous is set on a trigger whose target invokes a Tier 2 action (e.g., push, commit), surface a warning — cancel_previous + Tier 2 can produce partial commits.

Step 7: Target workflow cross-reference

If target.workflow is set, verify the referenced workflow exists. Check both locations:

WF="${target_workflow}"
PLUGIN_PATH="plugins/flow/workflows/${WF}.workflow.yaml"
LOCAL_PATH=".flow/workflows/${WF}.workflow.yaml"
[ -f "$PLUGIN_PATH" ] || [ -f "$LOCAL_PATH" ]

Missing → cross_reference_violations.append({"type": "missing_target_workflow", "name": target_workflow, "checked_paths": [PLUGIN_PATH, LOCAL_PATH]}). Hard fail (exit 1) — a trigger that points at a non-existent workflow can never do meaningful work and is broken by construction. This catches typos (e.g., address instead of address-pr) at trigger creation time rather than at runtime when /flow:run trigger <id> tries to dispatch.

If target.workflow is absent (the trigger uses target.command directly without naming a workflow), this step is a no-op.

Step 8: Compose overall verdict

| Condition | overall | |---|---| | schema fails | schema_invalid (exit 2) | | tier3_violations non-empty | tier3_violation (exit 1; HARD FAIL) | | recursion_violations non-empty | recursion_violation (exit 1) | | cross_reference_violations non-empty | cross_reference_failed (exit 1; HARD FAIL — missing target workflow) | | concurrency_violations non-empty | concurrency_warning (exit 0 — soft warning) | | else | pass (exit 0) |

Anti-patterns

• ❌ Allowing a trigger that grants merge/release autonomy. Non-negotiable.
• ❌ Allowing recursive trigger creation without explicit user approval. Loop-bomb shape.
• ❌ Treating soft-warning concurrency violations as hard fails (over-blocks).
• ❌ Skipping the active-trigger count check — unbounded trigger growth defeats the maxActiveTriggers budget.

Reuse map

• plugins/flow/schemas/v1/trigger.schema.json — schema this skill validates against.
• plugins/flow/triggers/templates/ — plugin-shipped templates.
• plugins/flow/commands/trigger.md — /flow:trigger command that invokes this skill.
• plugins/flow/commands/watch.md — /flow:watch command that creates triggers from templates.
• plugins/flow/references/flow-triggers.md — user-facing trigger documentation.