jumpstart-mode 1.1.13 → 1.1.14

package/.jumpstart/skills/agent-tool-catalog-designer/evals/evals.json

@@ -0,0 +1,32 @@
+{
+  "skill_name": "agent-tool-catalog-designer",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design the tool catalog for a sales-ops agent that lives in Salesforce. It should let AEs ask for account context, log a meeting summary to the opportunity, draft a follow-up email for the AE to send, and flag stalled deals to the manager. Acts on behalf of the AE. Give us the catalog plus the spec for the riskiest tool.",
+      "expected_output": "A tool catalog with side-effect classes, auth, approval gates, rate limits, and a full per-tool spec for the riskiest write/send tool.",
+      "expectations": [
+        "Lists each tool with a verb-led name, one-line purpose, and side-effect class (read/write/send/escalate).",
+        "Distinguishes drafting an email (read-only artifact for AE to send) from sending it (send class with explicit approval) and does not let the agent send on the AE's behalf without approval.",
+        "Uses on-behalf-of AE identity by default and names the Salesforce scopes required.",
+        "Specifies typed inputs (record IDs, enums) rather than free-text fields.",
+        "Includes rate limits, idempotency keys for write tools, and a typed error contract.",
+        "Provides a full per-tool spec for the riskiest tool with failure modes and observability.",
+        "Names out-of-scope tools (e.g., closing a deal, changing forecast) with rationale."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We have an existing copilot calling 14 tools. It is hallucinating tool calls and occasionally double-creating tickets in ServiceNow. Review the tool surface design issues likely at play and tell us what to redesign first.",
+      "expected_output": "A tightening plan focused on tool surface discipline, with prioritized fixes.",
+      "expectations": [
+        "Diagnoses likely causes of hallucinated calls (stringly-typed inputs, overlapping tool intents, vague descriptions, no enums).",
+        "Diagnoses double-create as missing idempotency keys and recommends a key strategy.",
+        "Recommends consolidating overlapping tools and removing or splitting tools that mix side-effect classes.",
+        "Recommends an explicit error contract and approval gate for write tools.",
+        "Sequences fixes by impact: schema discipline first, idempotency second, approval and audit third.",
+        "Calls out observability gaps (tracing per call, redaction, metrics)."
+      ]
+    }
+  ]
+}

package/.jumpstart/skills/agent-tool-catalog-designer/examples/example-it-helpdesk-agent.md

@@ -0,0 +1,57 @@
+# Example: IT Helpdesk Triage Agent — Tool Catalog
+
+## Agent purpose
+Triage employee IT requests in Teams: classify, gather context, attempt safe self-service, and either resolve or open a ServiceNow ticket with a complete summary.
+
+## User and identity context
+- Caller: employee in Teams.
+- Acts on behalf of: the calling employee (Entra OBO) for read; system identity (helpdesk service principal) for ticket creation, with employee captured as `caller_id`.
+- Execution surface: Copilot Studio agent + Azure Functions tool host.
+
+## Catalog summary
+
+| # | Tool | Side effect | Auth | Approval | Rate limit | Owner |
+|---|---|---|---|---|---|---|
+| 1 | `search_kb` | read | OBO user | none | 60/min/user | KB team |
+| 2 | `lookup_device` | read | OBO user | none | 30/min/user | Endpoint |
+| 3 | `check_account_status` | read | OBO user | none | 30/min/user | IAM |
+| 4 | `reset_password_self_service` | write | OBO user + MFA step-up | implicit (MFA gate) | 3/day/user | IAM |
+| 5 | `create_ticket` | write | system + caller_id | implicit | 10/min/user | ServiceNow |
+| 6 | `notify_oncall` | escalate | system | explicit (severity ≥ P2) | 5/hour | Ops |
+
+## Per-tool spec — `reset_password_self_service`
+
+- Side effect: `write` (irreversible without admin reset).
+- Identity: OBO user with MFA step-up; will not run on cached token.
+- Input schema: `{ "confirm": "I_UNDERSTAND" }` — no other fields; agent must not pass new password text.
+- Output: `{ "status": "RESET_LINK_SENT" | "BLOCKED", "channel": "email|sms" }`.
+- Approval: implicit via MFA challenge; agent never bypasses.
+- Idempotency: per-user 5-minute key to prevent loop.
+- Failure modes: `FORBIDDEN` (account locked, escalate to human), `RATE_LIMITED` (wait), `UPSTREAM_FAILURE` (retry once then escalate).
+- Observability: log invocation, MFA outcome, channel; redact email/sms target after first 3 chars.
+
+## Per-tool spec — `create_ticket`
+
+- Side effect: `write`.
+- Identity: system principal scoped to ServiceNow `incident.create`; `caller_id` field carries employee for audit.
+- Input schema: typed enum for `category`, `urgency`, `impact`; `summary` and `description` strings with length limits and PII redaction prior to send.
+- Output: `{ "ticket_id": "...", "url": "..." }`.
+- Idempotency key: hash of `(caller_id, category, summary, last_5min)` to prevent duplicate tickets from retry loops.
+- Failure modes: `CONFLICT` (existing ticket linked, surface link), `UPSTREAM_FAILURE` (retry up to 3, then escalate to `notify_oncall`).
+- Observability: trace span with category, urgency; full content logged to compliance store.
+
+## Cross-cutting
+
+- Default identity: OBO user. System identity used only for ServiceNow and on-call paging, with rationale recorded.
+- Rate-limit posture: token bucket per user and per tenant, enforced in tool wrapper before upstream call.
+- Error taxonomy: typed error envelope defined in `references/tool-design-patterns.md`.
+- Observability: Application Insights traces; metrics dashboard for call counts, error rates, approval-gate denials, MFA challenge outcomes.
+
+## Out of scope
+- `delete_user`, `unlock_account`, `change_group_membership` — too high-risk for the agent's autonomy level; routed to human admin via `create_ticket` with category `iam_admin_action`.
+- Direct AD writes — disallowed; only IAM API path is sanctioned.
+
+## Risks, assumptions, next validation
+- Risk: ServiceNow rate limits in incident storms; mitigate with caller-facing fallback message and ticket bundling.
+- Assumption: MFA step-up is enabled tenant-wide for password reset.
+- Next validation: 2-week shadow mode where the agent proposes tool calls but a human approves every `write`/`escalate` invocation; collect false-positive rate before enabling autonomy.

package/.jumpstart/skills/agent-tool-catalog-designer/references/tool-design-patterns.md

@@ -0,0 +1,60 @@
+# Tool Design Patterns
+
+## Side-effect classes
+
+| Class | Examples | Default approval | Audit |
+|---|---|---|---|
+| `read` | search, fetch, list, summarize | none | sampled |
+| `write` | create/update record, file upload | implicit if low-risk; explicit if regulated | full |
+| `send` | email, Teams/Slack post, SMS | explicit human until trust established | full + content |
+| `schedule` | create job, set reminder, queue task | implicit + reversible | full |
+| `escalate` | open ticket, page on-call, notify exec | explicit human or policy-gated | full |
+
+## Auth patterns
+
+- **On-behalf-of (OBO) user** — preferred. Agent acts within the user's scopes. Audit clearly attributes to user.
+- **Application identity (system)** — only when the agent acts on system behalf (batch jobs, cross-tenant). Document why and which scopes.
+- **Delegated with consent** — for OAuth APIs (Graph, Salesforce); design the consent surface explicitly.
+- **Workload identity federation** — agent runs in cloud workload; federate to identity provider; no static secrets.
+
+## Rate-limit posture
+
+- Specify per-call timeout, per-user QPS, per-tenant QPS, per-day quota.
+- Add token-bucket or leaky-bucket inside the tool wrapper, not just at the upstream API.
+- Define backoff and jitter; specify retryable error codes.
+- Surface `RateLimitedError` as a typed error so the agent can wait or degrade gracefully.
+
+## Idempotency and rollback
+
+- Use idempotency keys for any `write` or `send` tool (`Idempotency-Key` header or equivalent).
+- For `write`, design a compensating action or document why rollback is impossible.
+- For `send`, design a recall path if the channel supports it; otherwise label as irreversible and require explicit approval.
+
+## Error contract
+
+Define a typed error envelope:
+
+```json
+{
+  "error_code": "INPUT_INVALID|NOT_FOUND|FORBIDDEN|RATE_LIMITED|UPSTREAM_FAILURE|CONFLICT|TIMEOUT",
+  "retryable": true,
+  "user_facing_message": "...",
+  "developer_message": "...",
+  "trace_id": "..."
+}
+```
+
+Agents should retry only `RATE_LIMITED`, `TIMEOUT`, and transient `UPSTREAM_FAILURE`. Everything else surfaces or escalates.
+
+## Schema discipline
+
+- Prefer enums over strings for any controlled vocabulary.
+- Use IDs (record_id, user_id, tenant_id) over names; resolve names inside the tool.
+- Reject free-text where a structured field will do.
+- Validate at the tool boundary; do not trust model output.
+
+## Observability per tool
+
+- Trace span per call: tool name, args (redacted), latency, outcome, error code, identity used.
+- Log content for `send` and high-risk `write`; redact PII per policy.
+- Emit metrics: call count, error rate, p95 latency, rate-limit hits, approval-gate denials.

package/.jumpstart/skills/agent-tool-catalog-designer/templates/tool-catalog.md

@@ -0,0 +1,43 @@
+# Tool Catalog — `<agent name>`
+
+## Agent purpose
+One sentence.
+
+## User and identity context
+- Caller:
+- Acts on behalf of:
+- Execution surface:
+
+## Catalog summary
+
+| # | Tool | Side effect | Auth | Approval | Rate limit | Owner |
+|---|---|---|---|---|---|---|
+| 1 | | | | | | |
+
+## Per-tool specs
+Link to one `tool-spec.md` per tool.
+
+## Cross-cutting
+
+### Auth model
+- Default identity:
+- Consent flows:
+- Secret management:
+
+### Rate-limit posture
+- Global ceilings:
+- Per-tenant:
+- Backoff strategy:
+
+### Error taxonomy
+Common error envelope (see references/tool-design-patterns.md).
+
+### Observability
+- Tracing platform:
+- Metrics dashboard:
+- Alerting rules:
+
+## Out of scope
+Tools we explicitly chose not to build, with reason.
+
+## Risks, assumptions, next validation

package/.jumpstart/skills/agent-tool-catalog-designer/templates/tool-spec.md

@@ -0,0 +1,68 @@
+# Tool Spec — `<tool_name>`
+
+## Purpose
+One-line, verb-led, scoped to one job.
+
+## Side-effect class
+`read | write | send | schedule | escalate`
+
+## Auth and identity
+- Identity: on-behalf-of user | system | delegated
+- Required scopes:
+- Consent surface (if any):
+
+## Input schema
+```json
+{
+  "type": "object",
+  "required": [],
+  "properties": {}
+}
+```
+
+Examples:
+- Happy path:
+- Edge case:
+
+## Output schema
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+Error envelope: see common error contract.
+
+## Rate limits
+- Per call timeout:
+- Per user QPS:
+- Per tenant QPS:
+- Per day quota:
+- Retry policy:
+
+## Idempotency and rollback
+- Idempotency key:
+- Rollback / compensation:
+- Reversible? Yes/No
+
+## Failure modes
+| Code | Meaning | Retryable | Agent action |
+|---|---|---|---|
+| INPUT_INVALID | | No | Surface to user |
+| NOT_FOUND | | No | Surface |
+| FORBIDDEN | | No | Escalate |
+| RATE_LIMITED | | Yes | Backoff |
+| UPSTREAM_FAILURE | | Maybe | Retry with cap |
+| CONFLICT | | No | Surface |
+| TIMEOUT | | Yes | Retry with cap |
+
+## Approval gate
+`none | implicit | explicit human | dual control`
+- Trigger conditions:
+- Approver role:
+
+## Observability
+- Trace fields:
+- Logged content (redactions):
+- Metrics:

package/.jumpstart/skills/agent-workflow-state-machine/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: agent-workflow-state-machine
+description: Convert an agentic process into a production-ready state machine with explicit states, transitions, guardrails, retry and compensation behavior, and human approval checkpoints. Use this whenever the user asks for workflow states, finite-state modeling, lifecycle design, orchestration logic, approval gates, retry policies, failure handling, escalation paths, or runbook-ready control logic for AI agents, agentic workflows, or automation systems, even if they do not explicitly say "state machine".
+---
+
+# Agent Workflow State Machine
+
+Use this skill to turn a rough agentic workflow idea into an implementation-ready operating model that delivery teams can build and govern.
+
+## What this skill produces
+
+For substantial requests, produce a state-machine package that includes:
+1. State catalog with entry and exit criteria
+2. Transition rules with triggers, guards, and side effects
+3. Guardrails and policy controls per state and transition
+4. Retry, timeout, compensation, and dead-letter behavior
+5. Human approval checkpoints with clear authority boundaries
+6. Observability hooks, audit events, and failure signals
+7. Machine-readable artifacts (Mermaid, YAML, CSV)
+
+## When to use
+
+Apply this skill when the user asks for any of the following:
+- convert a process flow into an agent state model
+- map an agent lifecycle, orchestration workflow, or run-state model
+- define retries, fallback paths, escalation behavior, or failure states
+- add approval gates, human-in-the-loop checkpoints, or policy constraints
+- produce implementation artifacts for workflow engines or agent runners
+
+Do not produce vague conceptual diagrams only. Always anchor outputs in executable workflow semantics: state, trigger, guard, action, next state.
+
+## Bundled resources
+
+Read these references when needed:
+- `references/state-machine-design-guide.md` for the canonical modeling method
+- `references/guardrails-retries-approvals.md` for control and reliability patterns
+
+Use these templates when the user wants scaffolded artifacts:
+- `templates/agent-workflow-state-machine.mmd`
+- `templates/agent-workflow-state-machine.yaml`
+- `templates/state-transition-table.csv`
+- `templates/human-approval-matrix.md`
+
+Use this example for expected depth and structure:
+- `examples/jumpstart-client-recap-example.md`
+
+Use these eval prompts to regression-test the skill behavior:
+- `evals/evals.json`
+
+## Required modeling order
+
+Follow this order every time:
+1. Define objective, outcome quality bar, and blast-radius limits.
+2. Partition workflow into stable states, not transient implementation details.
+3. Define transitions: trigger, guard, action, and target state.
+4. Add retries, timeout, compensation, and terminal failure behavior.
+5. Insert human approvals where risk, cost, legal, or trust requires it.
+6. Attach policy controls and tool restrictions to each state.
+7. Define telemetry and audit events for each transition.
+8. Validate determinism and safety with completion checks.
+
+## State model rules
+
+Use these default state categories unless the user gives a better domain-specific taxonomy:
+- Intake
+- Context preparation
+- Planning
+- Tool execution
+- Validation
+- Human approval
+- Commit or publish
+- Recovery
+- Completed
+- Failed
+- Canceled
+
+Every state should include:
+- Purpose and allowed actions
+- Entry criteria and exit criteria
+- Max dwell time (timeout)
+- Retry policy and escalation condition
+- Required evidence or artifacts
+
+## Transition design rules
+
+For each transition, always capture:
+- `from_state`
+- `event_trigger`
+- `guard_condition`
+- `action`
+- `to_state`
+- `idempotency_rule`
+- `audit_event`
+
+Use explicit guard checks for:
+- confidence threshold and evidence completeness
+- policy or compliance checks
+- authorization and tool permission checks
+- budget or token/cost limits
+- output validation and schema conformance
+
+## Human approval checkpoints
+
+Require human approval transitions when any of the following applies:
+- external communication is sent to clients, partners, or regulators
+- state-changing write actions affect production systems or records
+- legal, compliance, or contractual interpretation is involved
+- confidence is below threshold but action impact is high
+- rollback cost or blast radius is above agreed threshold
+
+Define for each checkpoint:
+- approver role
+- decision SLA
+- approve/reject/rework outcomes
+- fallback if SLA expires
+
+## Retry and failure behavior
+
+Default reliability behavior:
+- transient error -> bounded retries with exponential backoff
+- persistent validation failure -> route to rework or human review
+- nonrecoverable policy violation -> hard fail with audit trail
+- repeated tool failure -> circuit-break to safe state and escalate
+
+Always define:
+- max attempts
+- backoff strategy
+- jitter behavior
+- dead-letter criteria
+- compensation action
+
+## Required output package
+
+When the request is substantial, create these sibling files:
+- `response.md` narrative summary and recommendation
+- `workflow-state-machine.mmd` state diagram
+- `workflow-state-machine.yaml` machine-readable state and transition spec
+- `state-transition-table.csv` transition inventory
+- `human-approval-matrix.md` checkpoint matrix
+
+If the request is narrow, provide only the relevant subset, but prefer file-shaped outputs over fenced blocks.
+
+## Completion checks
+
+Before finalizing, verify all checks pass:
+1. Every non-terminal state has at least one valid outbound transition.
+2. All transitions have guard conditions and explicit failure paths.
+3. Approval states define approver role, timeout, and reject path.
+4. Retries are bounded and cannot loop forever.
+5. Terminal states (`Completed`, `Failed`, `Canceled`) are reachable.
+6. High-risk actions are never reachable without required approvals.
+7. Observability and audit events are defined for critical transitions.
+8. Assumptions and out-of-scope boundaries are explicitly listed.
+
+## Output style
+
+- Prefer tables and structured fields over prose.
+- Make controls and responsibilities explicit.
+- Separate confirmed logic from assumptions.
+- Use practical language that can be copied into PRDs, runbooks, or implementation tickets.
+
+## Example prompts
+
+- "Convert this claims-triage agent flow into states, transitions, retries, and approval gates."
+- "Design a state machine for our onboarding copilot including guardrails and human escalation."
+- "Map this Jump Start delivery workflow into a state model with acceptance checks and rollback paths."
+
+## Escalation and companion skills
+
+- For deeper governance controls, use `agent-governance`.
+- For implementation-ready requirements language, use `agent-prd-writer`.
+- For phased execution planning, use `phased-roadmap`.

package/.jumpstart/skills/agent-workflow-state-machine/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "agent-workflow-state-machine",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Convert this rough agentic process into an implementation-ready state machine: intake customer request, gather context from CRM and policy docs, draft recommendation, require human approval before external send, then publish to CRM. Include retries, timeout handling, and failure states.",
+      "expected_output": "A structured state-machine package with explicit states, guarded transitions, retry behavior, and human approval gates.",
+      "files": [],
+      "expectations": [
+        "The output defines clear non-terminal and terminal states including Completed and Failed or Canceled.",
+        "Each transition includes trigger, guard, action, and target state rather than narrative prose only.",
+        "The output includes at least one explicit human approval checkpoint with approver role and decision outcomes.",
+        "The output defines bounded retry behavior and avoids infinite retry loops.",
+        "The output explains timeout or escalation behavior for stalled approval or execution states."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Design a state machine for a Jump Start workshop copilot that drafts recap notes, asks for facilitator review, and only sends client-ready recap after approval. It must handle low-confidence outputs and policy violations safely.",
+      "expected_output": "A governance-aware workflow with confidence and policy guards, rework path, and approval checkpoints.",
+      "files": [],
+      "expectations": [
+        "The output includes guard conditions for low confidence and policy checks.",
+        "The output routes low-confidence or policy-failed outputs to rework, human review, or failure states.",
+        "The output prevents external send actions without an explicit approval transition.",
+        "The output includes an approval matrix or equivalent mapping of checkpoint, approver, and SLA.",
+        "The output includes audit or observability events for critical transitions."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Take this existing workflow and normalize it into state-machine artifacts: Plan -> Execute Tools -> Validate -> Deliver. Add missing control points for retries, rollback, and human escalation when risk is high.",
+      "expected_output": "A normalized artifact set that preserves the original flow but adds missing operational controls.",
+      "files": [],
+      "expectations": [
+        "The output preserves the original high-level flow while introducing additional control states where required.",
+        "The output includes explicit recovery or compensation behavior for partial failures.",
+        "The output defines high-risk escalation logic and routes to human checkpoints.",
+        "The output produces machine-readable artifacts such as Mermaid, YAML, or CSV structures.",
+        "The output includes completion checks verifying reachability, bounded retries, and approval safety."
+      ]
+    }
+  ]
+}

package/.jumpstart/skills/agent-workflow-state-machine/examples/jumpstart-client-recap-example.md

@@ -0,0 +1,55 @@
+# Example: Jump Start Client Recap Workflow State Machine
+
+This example shows how to transform a recap workflow into explicit states and controls.
+
+## Scenario
+
+Workflow goal:
+
+- summarize workshop outputs
+- perform quality and policy validation
+- require facilitator approval
+- deliver final recap to client
+
+Risk notes:
+
+- external communication to client
+- possible leakage of internal or sensitive details
+
+## State catalog
+
+| state | purpose | entry criteria | exit criteria |
+| --- | --- | --- | --- |
+| Intake | Accept workshop notes and transcript | notes uploaded | minimum required artifacts present |
+| ContextPreparation | Normalize notes and classify sensitivity | intake validated | context packet complete |
+| DraftRecap | Generate draft recap | context packet complete | draft generated |
+| Validation | Check policy, quality, and confidence | draft generated | validation decision produced |
+| AwaitingHumanApproval | Facilitator or account owner review | validation passed and external send required | approval decision recorded |
+| CommitOrPublish | Publish to approved destination | approval granted | publish result captured |
+| Rework | Fix quality or policy issues | validation failed or changes requested | updated draft validated |
+| Completed | End state for successful publish | publish success | n/a |
+| Failed | End state for unrecoverable error | hard-failure condition | n/a |
+| Canceled | End state for rejected publish | approval rejected | n/a |
+
+## Critical transitions
+
+| from | trigger | guard | action | to |
+| --- | --- | --- | --- | --- |
+| Validation | validation_passed | confidence >= 0.8 and policy_status == pass | open_approval_checkpoint | AwaitingHumanApproval |
+| Validation | validation_failed_retryable | confidence < 0.8 or missing_citations == true | request_rework | Rework |
+| AwaitingHumanApproval | approved | approver_role in [Facilitator Lead, Account Owner] | unlock_publish | CommitOrPublish |
+| AwaitingHumanApproval | rejected | true | record_rejection | Canceled |
+| CommitOrPublish | publish_failed_transient | retry_count < 3 | retry_publish | CommitOrPublish |
+| CommitOrPublish | publish_failed_nonrecoverable | true | emit_failure_event | Failed |
+
+## Approval checkpoint
+
+| checkpoint_id | approver_role | evidence_required | approve_target_state | reject_target_state | sla_minutes |
+| --- | --- | --- | --- | --- | --- |
+| recap-send-approval | Facilitator Lead | draft recap, policy scan, confidence score | CommitOrPublish | Canceled | 30 |
+
+## Retry policy
+
+- Draft generation retry: max 2 attempts, fixed 10s delay.
+- Publish retry: max 3 attempts, exponential backoff with jitter.
+- If retries exhausted, route to `Failed` and notify owner.

package/.jumpstart/skills/agent-workflow-state-machine/references/guardrails-retries-approvals.md

@@ -0,0 +1,75 @@
+# Guardrails, Retries, and Approvals
+
+Use this reference to standardize control behavior in agent workflow state machines.
+
+## Guardrail policy layers
+
+Use layered controls instead of a single gate:
+
+1. Input guardrails: classify sensitivity, validate allowed intent.
+2. Planning guardrails: verify allowed tools and action scope.
+3. Execution guardrails: sandbox, least privilege, egress restrictions.
+4. Output guardrails: redact sensitive data, enforce policy and quality.
+5. Commit guardrails: approval gate before irreversible or external actions.
+
+## Retry policy defaults
+
+Use these defaults unless the user specifies alternatives:
+
+| Error Type | Retry? | Max Attempts | Backoff | Next Step if Exhausted |
+| --- | --- | --- | --- | --- |
+| Network timeout | Yes | 3 | Exponential + jitter | Recovery |
+| Rate limit | Yes | 4 | Exponential + jitter | AwaitingHumanApproval |
+| Schema validation fail | Limited | 2 | Fixed short delay | Rework |
+| Authorization failure | No | 0 | None | Failed |
+| Policy violation | No | 0 | None | Failed |
+
+## Compensation patterns
+
+When an action partially succeeds:
+
+- emit compensating event
+- run idempotent rollback where possible
+- route to `Recovery`
+- require human confirmation if rollback cannot be guaranteed
+
+## Human checkpoint triggers
+
+Insert human checkpoints for:
+
+- write operations in production systems
+- customer-facing communication
+- regulated data handling
+- low confidence with high impact
+- actions above financial or compliance threshold
+
+## Approval matrix fields
+
+Capture at minimum:
+
+- `checkpoint_id`
+- `risk_class`
+- `approver_role`
+- `evidence_required`
+- `decision_sla_minutes`
+- `approve_target_state`
+- `reject_target_state`
+- `timeout_target_state`
+
+## Audit and observability
+
+For each critical transition, emit:
+
+- transition event name
+- actor identity (human or system)
+- policy decision summary
+- correlation ID / run ID
+- timestamp and duration
+
+Track these metrics:
+
+- time in state
+- approval wait time
+- retry count by tool
+- recovery rate
+- hard-failure rate