Start here
Scenario Pack Guide
Defines the minimum pack, named roles, authority boundary, entry and exit criteria, failure routing, deeper-record triggers, and reopening rules.
Preview
# Tool-Using Workflow or Agent Scenario Pack Toolkit schema: `PAISEH-TK-1.0` Scenario pack: `PAISEH-SC-TWA-1.0` Use this pack when an AI-assisted workflow can call a tool, wait for approval, resume later, or create an external effect. It turns each proposed action into an inspectable contract, permission decision, approval, durable state transition, and effect receipt. The pack does not grant tool access, authorize an action, make a retry safe, or prove an outcome by itself. Identity, authorization, approval, dispatch, reconciliation, and terminal ownership must be enforced by authoritative systems outside the model. ## Smallest Credible Starting Set For one bounded, reversible action with a named owner, complete: 1. `tool-action-contract.md` 2. `permission-matrix.md` 3. `approval-record.md` when the contract requires approval 4. `workflow-state-model.md` 5. `effect-receipt.md` Attach every runbook whose entry condition is plausible. Advisory and proposal-only workflows may omit dispatch fields, but they still record the explicit no-effect boundary. Add deeper toolkit modules when the workflow handles sensitive data, crosses a trust boundary, delegates authority, creates durable state, produces an irreversible effect, or raises consequence. ## Users, Owners, and Authority | Role | Responsibility | Authority boundary | | --- | --- | --- | | Requester | States the intended outcome and supplies permitted input | May request work; cannot grant tool authority | | Workflow owner | Owns purpose, state model, stop conditions, and terminal service outcome | May narrow or stop workflow admission under policy | | Action owner | Owns one semantic action, its consequence, and its contract | Defines the action boundary; cannot authorize a principal | | Tool owner | Owns the adapter, schema, dependency behavior, and compatibility | May suspend the tool path; cannot broaden business authority | | Policy authority | Defines which principals may perform which actions and under what conditions | Issues or denies authoritative permission decisions | | Approver | Reviews one canonical action and evidence snapshot | May choose only the recorded decisions within current delegated authority | | Executor | Dispatches an authorized action through the controlled boundary | Cannot change material parameters, target, or effect identity | | Reconciliation owner | Determines effect state from authoritative evidence | May classify the outcome; cannot invent a missing receipt | | Compensation authority | Authorizes any corrective or offsetting effect | Compensation is a new action with its own contract and receipt | | Output verifier | Validates returned data and the claimed postcondition | Accepts or rejects evidence; does not approve the original action | | Terminal owner | Owns unresolved, failed, cancelled, partial, or completed work | Decides the permitted terminal disposition and follow-up | One person may hold several roles when policy permits. Record each assignment, authority source, expiry, handoff, and separation-of-duties requirement. ## Required Inputs and Entry Criteria - A bounded workflow purpose, initiating principal, represented principal if any, accountable owner, environment, and consequence class. - A versioned semantic action with exact target, typed parameters, provenance, protected fields, preconditions, postcondition, explicit denies, and output contract. - An authoritative permission decision that is no broader than the action and current at dispatch. - A canonical action digest and an approval rule that names the reviewer authority, allowed decisions, binding fields, evidence snapshot, expiry, and invalidation conditions. - A stable workflow, action, attempt, effect, and receipt identity scheme. - Defined commit, acknowledgement, completion, partial-success, unknown-outcome, cancellation, retry, compensation, and reconciliation semantics. - A durable state store with legal transitions, single-writer or lease behavior, checkpoints, safe resume rules, and terminal ownership. - An audit path that can relate proposal, canonicalization, permission, approval, dispatch, dependency response, observed effect, reconciliation, compensation, and terminal disposition. Do not dispatch when identity, target, parameter provenance, authority, approval binding, idempotency, commit semantics, reconciliation path, output validation, or terminal ownership is missing or indeterminate. ## Working Sequence | Stage | Required record | Result | | --- | --- | --- | | Contract | Tool and Action Contract | Versioned semantic action, tool boundary, inputs, effect semantics, outputs, and failure behavior | | Permit | Permission Matrix | Least-authority decision surface with explicit denies and current decision sources | | Approve | Approval Record | One review decision bound to the exact action, evidence, authority, and expiry | | Execute | Workflow State Model | Enforceable transitions, durable facts, retry and cancellation rules, and terminal owners | | Prove | Effect Receipt | Attributable dispatch, acknowledgement, effect, reconciliation, output validation, and disposition | ## Completed Walkthrough Use `examples/approved-ticket-creation-and-failed-job-restart.md` to inspect the five records completed for two separately approved effects. It demonstrates approval binding, idempotency, a lost response, reconciliation before retry, and terminal effect receipts. ## Enforcement Boundary The model may propose an action and explain its reasoning. Controls outside the model canonicalize inputs, authenticate the principal, resolve protected fields, authorize the exact action, validate approval, derive or verify effect identity, dispatch, record durable state, constrain retries, validate outputs, and issue receipts. A transport acknowledgement is not completion. A timeout is not failure. Cancellation after dispatch does not prove that no effect occurred. Compensation is a separately authorized effect, not deletion of history. When evidence cannot establish the outcome, the action remains `outcome-unknown`, receives a reconciliation owner, and blocks any repeat that could duplicate consequence. ## Runbook Selector | Condition | Runbook | | --- | --- | | Input, target, principal, permission, or action scope fails validation or exceeds the contract | `runbooks/action-rejected-or-scope-escape.md` | | The action changed after review, the approval expired, or reviewer authority cannot be proved | `runbooks/approval-invalidated-or-expired.md` | | Dispatch may have produced an effect but the outcome is unknown, late, or duplicated | `runbooks/unknown-outcome-or-duplicate-effect.md` | | Cancellation races with dispatch, work completes late, or a superseded task returns | `runbooks/cancellation-or-late-result.md` | | The tool returns malformed, untrusted, incomplete, or postcondition-inconsistent output | `runbooks/output-validation-failure.md` | | A completed or partial effect requires correction, compensation, or cross-system reconciliation | `runbooks/compensation-and-reconciliation.md` | ## Exit and Acceptance Criteria Close one action only when: - the executed action matches the accepted contract, canonical digest, permission decision, and any required approval; - the effective principal, target, environment, material parameters, provenance, tool version, and policy version are recorded; - effect identity, commit point, attempts, acknowledgement, dependency receipt, and observed postcondition are distinguishable; - every output used downstream has passed its schema, provenance, trust, completeness, and postcondition checks; - cancellation, late results, partial completion, and retries follow the state model; - each effect is confirmed, compensated, rejected before dispatch, cancelled before dispatch, terminally failed with no effect, or explicitly owned as unresolved; - reconciliation and compensation create their own evidence and never overwrite the original attempt; - the Effect Receipt and audit record are retrievable under the appropriate access controls; and - the terminal owner records the final disposition, residual risk, follow-up, and reopening conditions. ## Deeper Record Triggers Attach applicable core toolkit modules when the workflow: - uses protected, personal, confidential, regulated, or cross-tenant data; - accepts untrusted context or tool-returned instructions; - delegates work or can choose among several consequential actions; - creates durable state, notifications, financial effects, access changes, jobs, or external commitments; - requires long-running execution, takeover, concurrent workers, or human approval; - lacks a stable effect receipt or authoritative status lookup; - relies on a broad execution credential or crosses trust boundaries; - cannot fully reverse an effect or has a high consequence ceiling; or - changes action contracts, tool versions, policy, population, autonomy, or release compatibility. Typical additions are the AI Fit and Risk Assessment Worksheet, Harness Control-Loop Diagram, Tool Permission Matrix, AI Threat Model, Evaluation Plan, AI Release Manifest, AI Operations Runbook, and Principal Design Review Checklist and Record. ## Material Change and Reopening Triggers Reopen affected records when workflow purpose, principal, target, environment, parameter schema, provenance, protected fields, action or tool contract, permission rule, approval rule, evidence snapshot, effect identity, idempotency window, commit semantics, retry policy, cancellation behavior, compensation path, output contract, terminal owner, autonomy, or consequence changes. Also reopen when a late receipt, duplicate effect, unauthorized target, invalid output, failed compensation, unreconciled state, or audit gap contradicts the recorded disposition.