This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

Process Contract Standard

• Status: CANONICAL
• Owns: process contract structure, identifiers, and documentation boundary
• Does not own: runtime behavior, schema, API, access control, or deployment rules
• Update when: process contract format, evidence rules, or lifecycle documentation changes
• Related sources: process-registry.yaml, ../wiki/internal/PAGE_MAP.md, ../../.agents/rules/ARCHITECTURE.md

Purpose

This standard defines how an operational workflow becomes a versioned process contract that can be used consistently by product documentation, implementation tasks, browser regression, tenant variation analysis, the in-app manual, and future AI assistance.

Process contracts describe observable business behavior. They do not replace architecture, API, database, access-control, or deployment rules in .agents/rules/.

The machine-readable registry is docs/processes/process-registry.yaml.

Source-Of-Truth Boundaries

Concern	Source of truth
Operator workflow and expected business result	Approved process document under docs/processes/
User instructions and navigation	T_WIKI_PAGE, docs/wiki/internal/PAGE_MAP.md, and provider-specific SOPs where retained
Page, module, API, and runtime architecture	.agents/rules/ARCHITECTURE.md, docs/DESIGN.md, .agents/rules/API_CONTRACTS.md
Authoritative data and relationships	.agents/rules/DB_SCHEMA.md and verified schema evidence
Browser and field-user regression	docs/runbooks/CTC_FIELD_USER_PROCESS_SYSTEM_TEST_RUNBOOK.md and task evidence
Work status, acceptance, and release evidence	docs/ROADMAP.md, activated Task, scoped dated evidence, and deployment record when applicable

When these sources disagree, do not silently choose one. Mark the conflict as NEEDS CONFIRMATION, identify the conflicting sources, and obtain an explicit decision before changing either owner.

Identifier Rules

Identifiers are permanent after a contract reaches reviewed.

• Process: PROC-<DOMAIN>-<FLOW>.
• Tenant-only process when there is no shared contract: PROC-<DOMAIN>-<FLOW>-<PROFILE>.
• Scenario: <PROCESS_ID>.SCN-<NNN>.
• Step: <PROCESS_ID>.STEP-<NNN>.
• Exception: <PROCESS_ID>.EXC-<NNN>.

Use uppercase ASCII letters, digits, and hyphens. Use increments of 10 for step IDs so later steps can be inserted without renumbering existing references. Tenant profiles belong in tenant_profiles or tenant_variations; do not put a customer name in a shared process ID.

Examples:

• PROC-TMS-INBOUND-PLANNING
• PROC-OPS-DAILY-CTC
• PROC-TMS-INBOUND-PLANNING.SCN-010
• PROC-TMS-INBOUND-PLANNING.STEP-030

Process Composition And Ownership

Every process declares one of these types:

• atomic: owns executable steps, exceptions, and verification scenarios for one bounded workflow.
• composite: coordinates atomic processes and references their scenarios. It may own a distinct end-to-end orchestration scenario only when the trigger, completion condition, and evidence span multiple children. It must not create a second stable scenario ID for behavior already owned by one child.

A composite process lists registered children in subprocess_ids. Until a child process is registered, record the missing boundary in unknowns; do not copy the child workflow into the composite contract as if the composite owned it.

Scenario ownership rules:

1. One observable scenario has exactly one owning process and one stable ID.
2. owned_scenarios contains scenarios defined by the current process.
3. referenced_scenarios points to scenarios owned by another registered process and records why the composite depends on them.
4. A task changing an atomic workflow uses the atomic process ID and owned scenario IDs. A composite ID may be added for cross-process impact, but it does not replace the atomic owner.

State, Authority And Invariant Vocabulary

• A state is an observable fact owned by one authoritative record or an explicitly named external/physical checkpoint. UI text and composite progress are projections unless a contract names their owner.
• A transition is one authorized command, system action, or operator decision from an explicit before-state to an explicit after-state. Page visibility is not transition authority.
• An invariant is a condition that must hold before and after a transition. Validation describes how the invariant is checked and what the operator sees when it fails.
• completion requires the contract's named readback and evidence. HTTP success, a toast, a notification, or one completed child does not prove business or composite completion.

For a material record mutation or external/physical effect, identify the owner, the observable result, and the recovery path when a retry could duplicate or contradict that result. Simple local validation and UI-only flow do not need a separate state machine or checkpoint. Unknowns remain visible; they do not block normal work unless they create a concrete authority, data-integrity, security, or irreversible-effect risk.

Lifecycle

State	Meaning	Required evidence
draft	Registered from existing material but not yet reconciled as a complete contract.	Source document and explicit unknowns.
reviewed	Source, code/API/data traceability, and business wording were reviewed.	Reviewer, review date, and resolved material conflicts.
approved	The contract is accepted as the current behavior baseline.	User/product decision and required browser/runtime evidence.
deprecated	A successor contract exists or the process is no longer active.	Successor ID or retirement decision.

Only approved contracts can be treated as authoritative input for automated actions. Draft and reviewed contracts can support discovery and human-reviewed recommendations, but not unattended state changes.

Every registry entry carries a contract_version and lifecycle_evidence. The registry format version does not replace the individual contract version. Lifecycle evidence records reviewer and approval identity, timestamps, Work Items, verification date, and successor information. Fields that do not apply to a draft remain explicit null values or empty lists so a lifecycle change cannot be represented by changing only the lifecycle label.

Required Contract Sections

Use the following sections only where they describe a real process boundary. An approved contract needs enough detail to operate and recover the actual flow; it does not need placeholder sections, speculative states, or invented errors.

Identity And Ownership

• Process ID, title, process type, lifecycle, version, and owner domain.
• Subprocess IDs and referenced scenarios when the process is composite.
• Owning operational role and supporting roles.
• Applicable tenant profiles and module keys.
• Source document and related manuals or SOPs.

Trigger And Completion

• Business event that starts the process.
• Preconditions, required access, and required data.
• Expected output and the visible completion condition.
• Conditions that mean the process is incomplete, blocked, or canceled.

State Model

• Allowed starting, intermediate, terminal, and canceled states.
• Actor or system action that causes each transition.
• Visible UI language and internal state values when they differ.
• Invalid transitions and the error the operator must see.

Authority And Invariants

• Authoritative record/state owner for material mutations.
• Actor, role, command or system authority where it controls a material mutation or external/physical effect.
• Preconditions plus before/after invariants, validation source, and visible rejection behavior.
• Cross-owner handoff evidence; a child owner never transfers mutation authority merely because a composite references it.

Steps And Decisions

Each step must include:

• Stable step ID.
• Actor and menu/page entry point.
• Input and validation.
• Command or operator decision.
• Expected visible result.
• API or integration call when verified.
• Authoritative data and cross-module side effects when verified.
• Failure, retry, cancel, and recovery behavior.

Do not infer an API, table, permission, or side effect from a UI label. Use NEEDS CONFIRMATION until code, schema, or runtime evidence supports it.

Tenant Variations

• Shared behavior that every applicable tenant must preserve.
• Profile-specific trigger, fields, state transitions, terminology, modules, or integrations.
• Configuration or module key that selects the variation.
• Any remaining hardcoded client branch and its planned disposition.

Tenant variation must not create an undocumented customer-specific controller, page family, or data contract.

Exceptions And Recovery

• Stable exception ID and detection condition.
• User-visible error or blocked state.
• Whether a retry can duplicate a material mutation or effect, and the required reread only when it can.
• Manual recovery owner and escalation boundary.
• Data or external side effects that may already have occurred.
• Duplicate, stale/concurrent, timeout, missing-ID and unknown-result behavior.
• Idempotency mechanism when one exists; otherwise the exact readback and business identity required before retrying an unknown or duplicate-risk write.

Correction, Void, Reversal And Reopen

• Name only the correction, cancel, reversal, compensation, or reopen behavior actually supported by the process; do not create separate categories without a real business distinction.
• Preserve original record/effect provenance and the evidence linking the later action. Never describe a compensating business action as a rollback.
• State terminal boundaries that cannot be reopened or reversed and the manual recovery/escalation owner.

Transaction And Effect Checkpoints

• Name the local transaction boundary/readback when the process writes durable data. Represent external, physical, or compensation checkpoints only when that effect exists.
• A committed local result remains committed when a later provider, file, message, print or physical effect fails. Retry/reconcile only the missing effect unless the owning contract explicitly defines another action.
• A composite has no cross-child transaction unless current evidence proves one; reread each child and resume only the missing owner.

Verification

• Stable scenario IDs for normal, validation, permission, tenant, and recovery paths.
• Required account/profile and menu path.
• Fixture or precondition, cleanup, and rollback.
• Expected UI, API, data, and console evidence.
• Last verified environment, date, and GitHub Issue/PR evidence.
• Separate contract/source review, engineering checks, release evidence, user or operator acceptance, stabilization evidence, and measured product value. One dimension must not be reported as proof of another.

An API response or direct function call does not replace real-menu browser verification for an operator-facing workflow.

AI Assistance Boundary

• Readiness level.
• Inputs the AI may consume.
• Outputs the AI may produce.
• Evidence the AI must cite.
• Decisions or writes that require human review or approval.
• Prohibited actions and behavior when information is missing.

AI Readiness Levels

Level	Allowed use
none	Contract is incomplete or unsuitable for AI use.
retrieval	Find and summarize approved or clearly labeled draft content.
recommendation	Identify missing evidence, classify a known state, or recommend the next documented step for human review.
assisted-action	Prepare a payload or draft action that a human reviews and submits.
automation-approved	Execute only the explicitly approved action with required guards, audit, and rollback.

Absence of a rule is not permission. AI must return NEEDS CONFIRMATION when a required state, tenant variation, or approval boundary is missing.

Tenant Profile Registry

The top-level tenant_profiles list identifies reusable operating profiles and the deployment-local selector currently used to resolve them. A tenant profile is not a permission grant and must not be used as a substitute for module, role, menu, or API authorization.

Each tenant profile entry must include:

• id and label.
• runtime_selector.type, runtime_selector.value, and runtime_selector.scope.
• evidence_document and evidence_status.
• Explicit unknowns.

Current legacy selectors use:

runtime_selector:
  type: legacy-client-id
  value: 1
  scope: deployment-local

The numeric value is not a globally stable tenant identity. Control Tower UUID mapping remains the long-term tenant identity source.

Tenant profile evidence status:

• partial: one or more menu, role, module, config, integration, process, or current browser/runtime links are missing, stale, implicit, or unresolved.
• complete: applicable process IDs are linked; menu and role ownership is approved; module states and required config are explicit; integration ownership is known; current browser evidence exists; and there are no unresolved material unknowns.

Changing a selector, evidence status, or material unknown requires updating the evidence document in the same change. complete is evidence maturity, not permission to execute an operational or AI action.

Registry Requirements

Each entry in process-registry.yaml must include:

• id, title, process_type, contract_version, lifecycle, lifecycle_evidence, owner_domain, and tenant_profiles.
• source_document and any supporting_documents.
• tenant_applicability and operator_manual_disposition when no active tenant profile or operator entry point can be assigned from evidence.
• module_keys, app_entry_points, and verified api_surfaces.
• Verified authoritative_data references.
• subprocess_ids, stable owned_scenarios, and referenced_scenarios with their evidence source or relationship.
• traceability_status, unknowns, and ai boundary.

Rules:

1. IDs must be unique.
2. Referenced local paths must exist.
3. approved entries must not contain unresolved material unknowns.
4. Empty verified fields require a corresponding unknowns entry.
5. A tenant profile is a process selector, not an access-control assertion.
6. Registry evidence must distinguish documented, source-verified, browser-verified, and production-observed facts.
7. Composite processes must reference an atomic process's owned scenario ID; they must not duplicate the scenario under a new ID. A composite-owned scenario must describe cross-child orchestration rather than a child flow.
8. reviewed, approved, and deprecated lifecycle values require their corresponding non-null lifecycle evidence.
9. Every AI boundary must declare allowed_inputs, allowed_evidence_levels, and required_citations in addition to allowed outputs, human review, and prohibited actions. Input paths and citation requirements use explicit values rather than prose that an AI must parse.
10. A process with an empty tenant_profiles list must declare tenant_applicability: UNKNOWN, record the missing business owner in unknowns, and use operator_manual_disposition: NO_WIKI_REQUIRED unless an operator-facing source is actually mapped. It must not appear in a tenant wiki catalogue until applicability is proven.

Traceability status:

• partial: one or more required links are missing, unverified, or recorded in unknowns.
• complete: required source, entry point, API, data, scenario, and tenant links are verified for the current contract version.

Evidence levels:

• documented: the fact exists in a current source document.
• source-verified: the referenced page, route, or data contract was checked in the current source of truth.
• browser-verified: the scenario was completed through the required user path.
• production-observed: approved production evidence supports the claim; this does not authorize a production write.

Process Correlation And Transition Envelope

ProcessContext and AuditEnvelope are inactive, schema-independent foundation objects. They correlate business evidence by stable references; they do not execute a transition, open a transaction, dispatch an external effect, persist an audit row, or authorize a user. Active caller migration and persistence are separate packets.

The code contract lives in app/platform/process/ProcessContext.php and app/platform/process/AuditEnvelope.php. The Candidate A/B/C walkthrough is tests/unit/process_audit_envelope_test.php. Candidate-only process IDs in the fixture are proposals, not registry entries or lifecycle approval.

ProcessContext v1

Field	Contract
schemaVersion	Literal process-context/v1.
tenant	One strict TenantExecutionContext; safe output retains tenant identity and redacted actor provenance.
process contract	Permanent-format PROC-* ID plus semantic contract version; registry lookup is not performed at runtime construction.
instance hierarchy	Canonical process instance UUID and optional parent UUID; a child requires causation and inherits tenant/correlation.
correlation	Safe correlation ID across one business flow and optional causation ID for the triggering process/event.
source	WEB, API, JOB, INTEGRATION, or SYSTEM, compatible with the tenant entrypoint, plus a safe source reference.
entities	1-25 typed namespace:id references with PRIMARY, RELATED, INPUT, OUTPUT, or EVIDENCE relation.
maximum recovery	Declared process ceiling R0-R5; an envelope cannot claim a risk above this ceiling.

createChild() preserves the tenant and correlation, sets the current instance as parent/default causation, and requires a new process contract, instance, entities, and recovery ceiling. This expresses nested work without copying a business payload.

AuditEnvelope v1

Field	Contract
schemaVersion, auditId	Literal audit-envelope/v1 and canonical audit UUID.
process/transition/time	One ProcessContext, stable uppercase transition code, canonical RFC3339 timestamp.
state references	Before/after owner type, namespace:id owner reference, and stable state code; no row snapshot.
reason/approval	Stable reason code/reference. Approval is separately typed as user, policy, supervisor, or business compensation and cannot reference an operation event.
result/failure	SUCCEEDED, REJECTED, FAILED, PARTIAL, or COMPENSATION_REQUIRED; failure exposes code, stage, and safe reference only.
recovery/effect	Actual R0-R5 and NONE, DATABASE_COMMITTED, EXTERNAL_PENDING, EXTERNAL_COMMITTED, PHYSICAL_COMMITTED, or COMPENSATION_REQUIRED.
evidence	1-50 typed reference-only links for KJ mutation, operation event, staff event, file, mail item, external attempt, or business record.

Evidence type fixes its relation. In particular OPERATION_EVENT always has NOTIFICATION_ONLY; ACK never satisfies approvalRef, business completion, or R4/R5 evidence by itself. KJ mutation references identify request/mutation evidence but do not become transition reason or approval.

Recovery And Effect Matrix

Recovery	Allowed effect boundary	Required interpretation
R0	NONE	Rejection before write; retry requires corrected input/state.
R1	NONE, DATABASE_COMMITTED	Transaction either rolled back or committed; authoritative state is reread.
R2	DATABASE_COMMITTED, EXTERNAL_PENDING	Business result remains while external retry/reconciliation is separate.
R3	NONE, DATABASE_COMMITTED	Assignment/claim is reversible through an explicit unclaim/reassign action.
R4	DATABASE_COMMITTED, PHYSICAL_COMMITTED, COMPENSATION_REQUIRED	Explicit approval plus non-notification evidence; recovery is an approved business compensation.
R5	EXTERNAL_COMMITTED, PHYSICAL_COMMITTED, COMPENSATION_REQUIRED	Explicit approval/checkpoint plus evidence; the original effect is not rolled back.

EXTERNAL_COMMITTED requires at least R5, PHYSICAL_COMMITTED and COMPENSATION_REQUIRED require at least R4, and EXTERNAL_PENDING requires at least R2. PARTIAL, FAILED, and COMPENSATION_REQUIRED results carry a structured failure reference; raw exception/provider text is forbidden.

Candidate Walkthrough Boundary

• Candidate A records human-confirmed FULL -> FULL-READY, closing-file and KJ mutation references, and an R1 database boundary. OCR output/value is not copied into the envelope.
• Candidate B retains the confirmed appointment mutation while a failed reply is PARTIAL, R2, EXTERNAL_PENDING, linked to mail and external-attempt references. The DB result is not rolled back.
• Candidate C represents claim as reversible R3, physical completion as approved R5, and a wrong completed move as approved R4 compensation. A code rollback is not described as a physical rollback.

Safe serialization rejects unsupported fields and emits only normalized metadata/references. It never carries row snapshots, free-form payloads, email bodies, file content, provider responses, exception messages, credentials, or secret-like input fields. ADR 0002 selects a dedicated bounded transition main table plus typed entity/evidence reference child tables; KJ JSONL and operation notifications remain source evidence rather than the business-transition store. The physical/index/retention contract is WP01-09 owns the separately approved migration and inactive writer.

EvidenceTrace v1

EvidenceTrace is an equally inactive, reference-only companion to a ProcessContext. It links one process/tenant context to a source and separate prerequisite versus completion-evidence lists. It does not store a file, read a JSONL stream, invoke AI, change an audit envelope, or determine whether a business transition is complete.

The code contract is app/platform/process/EvidenceTrace.php; Candidate A/B coverage is tests/unit/evidence_trace_test.php. Its required metadata is a canonical trace ID, safe task and schema references, semantic contract version, and typed source/reference entries with a lowercase SHA-256 digest and stable provenance code. Types are bounded to file, JSONL, AI artifact, business record, or process references as appropriate. Each entry is only type, reference, contentHash, and provenance.

prerequisiteReferences records inputs/state needed before a process step. completionEvidenceReferences records proof observed after that step and must contain at least one reference. A file that proves completion belongs only in the latter list; it cannot be silently treated as a process prerequisite. Raw documents/images, file paths/URLs, JSONL rows, prompts, AI output, secrets, email bodies, exception text, and provider payloads are rejected rather than copied into safe serialization. Persistence, active caller migration, and log format changes remain separate work packets.

Contract Template

Use this outline when converting a draft registry entry into a detailed process contract:

# <Process Title>

## Contract Metadata
- Process ID / Process type:
- Lifecycle / Contract version:
- Lifecycle evidence:
- Owner domain / Roles:
- Subprocesses / Referenced scenarios:
- Tenant profiles / Module keys:
- Source and supporting documents:

## Trigger And Completion
## Preconditions And Access
## State Model
## Authority And Invariants
## Main Flow
### <PROCESS_ID>.STEP-010 <Step name>
## Tenant Variations
## Exceptions And Recovery
### <PROCESS_ID>.EXC-010 <Exception name>
## Correction, Void, Reversal And Reopen
## Transaction And Effect Checkpoints
## Data And Side Effects
## Verification Scenarios
### <PROCESS_ID>.SCN-010 <Scenario name>
## AI Assistance Boundary
## Unknowns And Decisions Needed
## Change History

Development And Change Workflow

1. Attach the implementation task to a process ID and scenario IDs before changing observable workflow behavior.
2. Compare the contract with current page, API, schema, tenant, and runtime evidence. Record conflicts as unknowns.
3. Update the process contract and registry in the same change when behavior, ownership, entry points, states, or side effects change.
4. Update the user manual only when operator instructions change.
5. Run the listed scenarios through the real user path when the workflow is operator-facing.
6. Record verification and decision evidence on the GitHub Issue or PR.
7. Promote lifecycle only when the required evidence exists.

The repo-level implementation gate is defined in .agents/rules/PROJECT_OPERATIONS.md. A workflow-changing task must record the affected process IDs and owned scenario IDs in its Issue acceptance criteria before implementation. Missing mapping is a TRIAGE issue, not permission to proceed without traceability.

For legacy popup replacement, each popup has its own task, deployment, and rollback boundary. That task can reference several scenarios owned by the affected atomic processes. A nested call to another popup stays under the called popup's separate task boundary.

---

Source: docs/processes/PROCESS_CONTRACT_STANDARD.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.