# Process Template Schema — Layer 3 Vocabulary Schema
# KNO Schema Version: 0.2.0
#
# Layer 3 schema for declarative agent process templates. A process
# template defines a phase-by-phase loop that agents execute when
# fulfilling a task: which phases exist, in what order, with what
# guards between them, what output each phase must produce, and how
# multi-pass iteration / quality gating / governance work.
#
# The CANONICAL instance (`content/process-templates/agent-loop.kno`)
# defines the 6-phase Agent Loop (DISCOVER → ANALYZE → STRUCTURE →
# SHARE → ENACT → COMPLY) that all M22 personas instantiate. Future
# specialized templates (e.g. continuous-monitoring-loop) MAY also
# conform to this schema.
#
# DOMAIN: Agent process specification
# PURPOSE: Make the agent loop declarative, not coded. Adding a new
#          template = adding a .kno file. State machine, phases,
#          AECS routing, governance hooks all live in the .kno;
#          the runtime interpreter (post-F4) reads them.
#
# DESIGN DECISIONS:
#   - DD-PT-01: Templates are .kno entities, not config in code. The
#     runtime interpreter is generic; per-template behaviour comes from
#     the .kno. New templates can be added without code change.
#   - DD-PT-02: `lifecycle: bounded | continuous` distinction per
#     blindspot B-005 + #2018 carry-forward A-6. Bounded templates
#     reach terminal COMPLETED under normal operation; continuous
#     templates loop COMPLY → DISCOVER indefinitely. The state
#     machine respects the lifecycle: continuous templates have no
#     "normal" path to COMPLETED.
#   - DD-PT-03: Multi-pass iteration support per Framework F-2. Each
#     phase declares `max_passes` and `quality_threshold`. Per #2018
#     A-6: explicit `max_passes` exhaustion semantics — after N
#     passes without meeting threshold, transition to BLOCKED with
#     reason `max_passes_exhausted`. Not silent completion; not
#     infinite loop.
#   - DD-PT-04: AECS routing thresholds (ADOPT ≥85%, EVOLVE 40-84%,
#     CREATE <40%) are TEMPLATE-LEVEL DEFAULTS that an instantiating
#     agent MAY override via its agent-card. Per #2018 A-6 +
#     pre-mortem failure C: thresholds may be wrong for specific
#     personas; per-agent override avoids forcing a template-level
#     change to accommodate one outlier.
#   - DD-PT-05: Output contracts per phase (Framework F-5). Each
#     phase declares required + optional output fields. The runtime
#     enforces required fields before the phase transition fires.
#   - DD-PT-06: State-machine illegal transitions are FIRST-CLASS in
#     the schema. The four core illegal transitions are required;
#     templates MAY add more. Drift-guard asserts the four cores
#     are present.
#   - DD-PT-07: Bedrock principle citations per finding (Framework
#     F-6). Findings emitted by phases SHOULD reference the
#     applicable bedrock principle; the schema doesn't enforce, but
#     the runtime MAY warn.
#   - DD-PT-08: Phase-boundary retros (Framework F-7) are emitted as
#     mini-retro entities (separate schema, post-F4 follow-up). F4
#     declares the EMISSION POINT (transition guards) but doesn't
#     define the retro schema — that schema lives in `mini-retro` skill
#     references and may eventually graduate to its own
#     `agent-retro-schema.kno`.
#
# Created for: M22-P2 F4 (#852).

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KQ58GH1FW9K3CES54QJRDGQJ
slug: process-template-schema
type: spec
version: 0.1.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Process Template Schema"
purpose: |
  Define the schema for agent process templates — the declarative
  description of how an agent's work loop is structured.

  **What is a process template?**

  A `.kno` document that specifies:
    - The phases an agent passes through (e.g. DISCOVER → ANALYZE → ...)
    - The transitions between phases (with guards)
    - Illegal transitions that MUST be prevented
    - Output contracts per phase (what must be produced before transition fires)
    - Multi-pass iteration parameters (max passes, quality threshold)
    - AECS routing defaults (ADOPT/EVOLVE/CREATE/SKIP thresholds)
    - Governance + Knowledge Courier hooks (which phases handle
      compliance + sharing logic)
    - Lifecycle: bounded vs continuous (B-005 mitigation)

  Each M22 agent persona instantiates a template. The canonical
  template (`agent-loop`) defines the 6-phase loop. A6 Entity
  Lifecycle Guardian (#858) and A13 Drift Detective (#2013) use the
  same template but with `lifecycle: continuous` so the loop never
  reaches a terminal COMPLETED state.

  **Layer 3 position:** Layer 3 vocabulary. Pairs with
  `agent-card-schema` (F1; agent cards reference a process template
  via `process_template_xri`).

# =============================================================================
# RICH TIER — Provenance & Taxonomy
# =============================================================================
provenance:
  origin:
    id: 01KQ58GH1FW9K3CES54QJRDGQJ
    timestamp: "2026-04-25T23:55:00Z"
    tool: manual
    issue: "https://github.com/PossibilityTruthy/possibility-space/issues/852"

taxonomy:
  topics:
    - process-template
    - agent-loop
    - state-machine
    - governance
    - m22
  keywords:
    - process-template
    - agent-loop
    - state-machine
    - aecs-routing
    - lifecycle
    - bounded
    - continuous

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
relationships:
  related_to:
    - xri: "kno://specs/agent-card-schema"
      reason: "Agents reference a process template via process_template_xri; the
        schema also depends on perception domains for phase-routing decisions"
    - xri: "kno://specs/decision-schema"
      reason: "STRUCTURE / ENACT phases call recordDecision() to capture choices made
        in-loop"
    - xri: "kno://specs/observation-schema"
      reason: "DISCOVER phase consumes observations from F3 tap; intermediate-pass
        findings are persisted as observations"
    - xri: "kno://specs/perception-domain-schema"
      reason: "Phase routing logic uses perception domains (P10 derivable structure)
        to decide which agents process which observations"

quality:
  completeness: 0.9
  last_reviewed: "2026-04-25"
  review_status: draft

# =============================================================================
# HISTORY
# =============================================================================
_history:
  version: 1
  created: "2026-04-25T23:55:00Z"
  created_by: "claude"
  modified: "2026-04-25T23:55:00Z"
  modified_by: "claude"

# =============================================================================
# SPECIFICATION
# =============================================================================
spec:
  status: Draft

  changelog:
    - version: "0.2.0"
      date: "2026-04-29"
      changes:
        - "Add OPTIONAL top-level `budget_policy` block (M22-P3 PR-2). Captures
          token budget cap, warn threshold, optional cost ceiling, and on_breach
          action (default `blocked`). Strict-additive bump per spike Q5 (#2080)
          and the F4 spike resolution carried in #2078: budget exhaustion is a
          recoverable signal that routes the agent to BLOCKED (not FAILED),
          letting callers raise the cap and re-trigger."
        - "Allow `process-template@0.2.0` in `$schema` const; existing v0.1.0
          instances remain valid."
    - version: "0.1.0"
      date: "2026-04-25"
      changes:
        - "Initial creation for M22-P2 F4 (#852)"
        - "lifecycle: bounded | continuous distinction per #2018 A-6 (B-005
          mitigation)"
        - "Explicit max_passes exhaustion semantics (DD-PT-03)"
        - "Per-agent AECS threshold override mechanism (DD-PT-04)"
        - "Required core illegal-transition guards (DD-PT-06)"

  schema:
    type: object
    required:
      - id
      - slug
      - type
      - version
      - lifecycle
      - phases
      - transitions
      - illegal_transitions
      - aecs_defaults
      - governance
    properties:
      $schema:
        type: string
        enum:
          - "process-template@0.1.0"
          - "process-template@0.2.0"
        description: |
          Schema declaration. Either v0.1.0 or v0.2.0 is valid; v0.2.0
          adds the optional `budget_policy` block. Strict-additive
          bump — existing v0.1.0 instances remain valid as v0.2.0
          consumers (the new field is optional).

      id:
        type: string
      slug:
        type: string
        description: "Kebab-case. MUST match filename."
      type:
        type: string
        const: "process-template"
      version:
        type: string

      name:
        type: string
      description:
        type: string

      # -----------------------------------------------------------------------
      # LIFECYCLE (DD-PT-02, B-005)
      # -----------------------------------------------------------------------

      lifecycle:
        type: string
        enum:
          - bounded
          - continuous
        description: |
          Distinguishes templates whose loop terminates (bounded) from
          those that loop indefinitely (continuous):

          - **bounded**: The state machine reaches COMPLETED under
            normal operation. Used by personas A1-A5, A7-A9, A12.
            Examples: schema analysis, hindsight review, RFC research.

          - **continuous**: The state machine NEVER legitimately reaches
            COMPLETED — after the COMPLY phase, the agent transitions
            back to DISCOVER. COMPLETED is reachable ONLY via explicit
            shutdown signal. FAILED-terminal is replaced by
            BLOCKED-with-retry. Used by A6 Entity Lifecycle Guardian,
            A13 Drift Detective.

          The runtime interpreter respects this field: under
          continuous lifecycle, the COMPLY → DISCOVER transition is
          included in the active state machine; under bounded, it's
          not.

      # -----------------------------------------------------------------------
      # PHASES (DD-PT-03, DD-PT-05, F-2, F-5)
      # -----------------------------------------------------------------------

      phases:
        type: array
        description: "Ordered list of phases the agent passes through"
        items:
          type: object
          required:
            - id
            - description
            - output_contract
          properties:
            id:
              type: string
              description: "Stable phase ID (e.g. discover, analyze, structure, share, enact,
                comply)"
            name:
              type: string
            description:
              type: string

            output_contract:
              type: object
              required:
                - required
              description: |
                Specification of what the phase MUST produce before its
                outbound transitions fire. The runtime interpreter
                enforces required fields by inspecting the phase's
                emitted entities (observations, decisions, retros).
              properties:
                required:
                  type: array
                  items:
                    type: string
                  description: "Field names that must be present"
                optional:
                  type: array
                  items:
                    type: string

            max_passes:
              type: integer
              minimum: 1
              default: 1
              description: |
                Maximum number of internal iterations within this phase
                (Framework F-2). Default 1 = single pass. Higher values
                let agents narrow focus across passes (e.g. broad scan
                → focused investigation → final synthesis).

            quality_threshold:
              type: number
              minimum: 0
              maximum: 1
              default: 0.7
              description: |
                Minimum confidence required before the phase's
                outbound transitions can fire. Below threshold and
                max_passes is exhausted → BLOCKED with reason
                `max_passes_exhausted` (per DD-PT-03).

            entry_actions:
              type: array
              items:
                type: string
              description: "Optional actions to run on phase entry (e.g. emit retro entity)"

            exit_actions:
              type: array
              items:
                type: string
              description: "Optional actions to run on phase exit"

      # -----------------------------------------------------------------------
      # TRANSITIONS
      # -----------------------------------------------------------------------

      transitions:
        type: array
        description: |
          Allowed transitions between states. Each transition has a
          named guard; the runtime evaluates the guard against the
          phase's output and only fires the transition if the guard
          passes.
        items:
          type: object
          required:
            - from
            - to
            - guard
          properties:
            from:
              type: string
              description: "Source state ID"
            to:
              type: string
              description: "Target state ID"
            guard:
              type: string
              description: |
                Named guard expression. Examples:
                  - "trigger_received"
                  - "perception_data_collected"
                  - "analysis_complete AND confidence >= quality_threshold"
                  - "proposal_acknowledged"
                  - "max_passes_exhausted"
            description:
              type: string

      # -----------------------------------------------------------------------
      # ILLEGAL TRANSITIONS (DD-PT-06)
      # -----------------------------------------------------------------------

      illegal_transitions:
        type: array
        description: |
          Transitions the runtime MUST NOT permit, even if
          accidentally requested. Templates MUST declare the four
          core illegal transitions (drift-guard enforces).
        items:
          type: object
          required:
            - from
            - to
            - reason
          properties:
            from:
              type: string
              description: "Source state ID (* = any state)"
            to:
              type: string
              description: "Target state ID"
            reason:
              type: string
              description: "Why this transition is forbidden"

      # -----------------------------------------------------------------------
      # AECS ROUTING (DD-PT-04, §7.2)
      # -----------------------------------------------------------------------

      aecs_defaults:
        type: object
        required:
          - adopt_threshold
          - evolve_range
          - create_threshold
        description: |
          Default AECS routing thresholds. Agents MAY override per-
          persona via their agent-card (post-F4 follow-up). The
          numbers are suggestions for first-pass calibration; expect
          to refine after P3 personas hit real data.
        properties:
          adopt_threshold:
            type: number
            minimum: 0
            maximum: 1
            description: "Schema-coverage % at/above which → ADOPT (fast path)"
          evolve_range:
            type: array
            minItems: 2
            maxItems: 2
            items:
              type: number
            description: "[low, high] range for EVOLVE (e.g. [0.40, 0.85])"
          create_threshold:
            type: number
            minimum: 0
            maximum: 1
            description: "Schema-coverage % below which → CREATE (with structural signals)"
          skip_conditions:
            type: array
            items:
              type: string
            description: "Conditions that route to SKIP (no action)"

      # -----------------------------------------------------------------------
      # GOVERNANCE
      # -----------------------------------------------------------------------

      governance:
        type: object
        required:
          - sentinel_phase
          - courier_phase
        description: |
          Embeds Governance Sentinel + Knowledge Courier as named
          phase responsibilities (per architecture §7.3).
        properties:
          sentinel_phase:
            type: string
            description: |
              ID of the phase responsible for bedrock conformance
              checking. Conformance violation → route back to
              STRUCTURING (or equivalent).

          courier_phase:
            type: string
            description: |
              ID of the phase responsible for routing
              observations/proposals to consumers. Acknowledgment
              tracked here; SHARING → BLOCKED if courier target
              unavailable.

          conformance_violation_action:
            type: string
            enum:
              - revise
              - block
              - escalate
            default: revise
            description: |
              What to do on bedrock conformance violation:
                - revise: route back to STRUCTURING (default; loop)
                - block: transition to BLOCKED (manual intervention)
                - escalate: emit attention-severity observation +
                  block

      # -----------------------------------------------------------------------
      # BUDGET POLICY (M22-P3 PR-2 \u2014 #2080 spike Q5)
      # -----------------------------------------------------------------------

      budget_policy:
        type: object
        description: |
          OPTIONAL token-budget policy applied per invocation. When
          absent, the runtime uses its built-in default cap
          (DEFAULT_TOKEN_CAP = 50_000) and routes exhaustion to
          BLOCKED with no policy customization.

          When present, the runtime:
            1. Caps total tokens at `max_invocation_tokens`.
            2. Logs a warn-level event when usage crosses
               `warn_threshold_pct`.
            3. On breach, transitions per `on_breach`:
                 - `blocked` (default): runtime emits BudgetExhaustion
                   error \u2192 state transitions to BLOCKED. Caller may
                   re-trigger with a raised cap. T0 counter + T1 log
                   emitted per failure-is-knowledge.
                 - `failed`: terminal failure (FAILED state). Use only
                   for templates where exhaustion is not recoverable.

          Per-agent overrides live in agent-card `budget_override`
          (agent-card-schema v0.2.1). Agent overrides take precedence
          over the template policy when both are present.
        properties:
          max_invocation_tokens:
            type: integer
            minimum: 1
            description: "Hard cap on total tokens consumed per invocation"
          max_phase_tokens:
            type: integer
            minimum: 1
            description: "OPTIONAL per-phase sub-cap. Not enforced in v0.1.0 runtime."
          warn_threshold_pct:
            type: number
            minimum: 0
            maximum: 1
            default: 0.8
            description: "Fraction of cap at which a warn-level log is emitted"
          cost_ceiling_usd:
            type: number
            minimum: 0
            description: "OPTIONAL dollar ceiling. Informational in v0.1.0 (no provider
              price table wired)."
          on_breach:
            type: string
            enum:
              - blocked
              - failed
            default: blocked
            description: |
              Routing on cap breach. Default `blocked` is the
              recoverable path \u2014 caller may re-trigger with a raised
              cap. Use `failed` only for templates where exhaustion
              cannot be remediated (rare).

      # -----------------------------------------------------------------------
      # METRICS HOOKS
      # -----------------------------------------------------------------------

      metrics:
        type: object
        description: |
          Runtime metrics the interpreter SHOULD emit. Names are
          stable identifiers usable as OTel metric names.
        properties:
          phase_duration:
            type: boolean
            default: true
          confidence_delta:
            type: boolean
            default: true
          pass_count:
            type: boolean
            default: true
          verdict_distribution:
            type: boolean
            default: true

      # -----------------------------------------------------------------------
      # FRAMEWORK ENRICHMENTS (informational; runtime references)
      # -----------------------------------------------------------------------

      frameworks:
        type: object
        description: |
          Documents which §6b frameworks the template embeds. Used by
          the interpreter to wire up framework-specific behavior
          (e.g. F-7 retro emission) without per-template code.
        properties:
          multi_pass_iteration:
            type: boolean
            description: "F-2 — phase max_passes is honored"
          document_as_you_go:
            type: boolean
            description: "F-3 — intermediate observations persisted"
          evidence_based_verdicts:
            type: boolean
            description: "F-5 — per-criterion verdicts with evidence"
          principle_citation:
            type: boolean
            description: "F-6 — findings cite bedrock principles"
          mandatory_retro:
            type: boolean
            description: "F-7 — retro entity emitted at phase boundaries"
          phase_lookahead:
            type: boolean
            description: "F-8 — plan-reality comparison at boundaries"
          slow_deliberate_cadence:
            type: boolean
            description: "F-10 — quality-over-speed enforcement"

# =============================================================================
# EXAMPLES
# =============================================================================
examples:
  - title: "Minimal bounded template"
    description: "Smallest valid template — single phase, terminal COMPLETED"
    content: |
      $schema: process-template@0.1.0
      id: 01EXAMPLEMINIMALTEMPLATE0001
      slug: example-minimal
      type: process-template
      version: 0.1.0
      name: "Example Minimal"
      lifecycle: bounded

      phases:
        - id: do-thing
          description: "The one and only phase"
          output_contract:
            required: [result]

      transitions:
        - from: IDLE
          to: do-thing
          guard: trigger_received
        - from: do-thing
          to: COMPLETED
          guard: result_present

      illegal_transitions:
        - from: IDLE
          to: COMPLETED
          reason: "Completion requires passing through the phase"
        - from: "*"
          to: do-thing
          reason: "Re-entry forbidden after completion"
        - from: do-thing
          to: do-thing
          reason: "No self-loop"
        - from: COMPLETED
          to: "*"
          reason: "Terminal state"

      aecs_defaults:
        adopt_threshold: 0.85
        evolve_range: [0.40, 0.85]
        create_threshold: 0.40

      governance:
        sentinel_phase: do-thing
        courier_phase: do-thing