Modernisation proposal for review; durations are indicative.

execution-contract.md

Status and purpose

This execution contract is an unapproved planning proposal for the CardDemo modernisation. It defines bounded, independently reviewable work; it does not approve access, staffing, architecture, expenditure, provisioning, release, cutover, deployment, retirement, or production use.

The estate is only partially reconstructed. Source and inventory coverage do not prove semantic completeness, deployment, interoperability, production relevance, security, recoverability, or ownership. Contradictions must remain visible until runtime evidence or accountable human decisions resolve them.

The objectives are to preserve material business capabilities while enabling safer change, improved reliability, recovery, security, supportability, observability, and supported technology lifecycles. No benefit may be claimed until its indicator has an accepted baseline, proposed target, accountable owner, source, method, sampling period, exclusions, and review cadence. Targets, service levels, availability, performance, retention, recovery objectives, capacity, staffing, costs, and outage allowances remain undecided.

Contract-wide controls

Each task must have a human-approved scope statement, named evidence set, permitted non-production environment, allowed tools, data-handling rules, expected artifacts, reviewers, dependencies, and stop conditions. Agent output is review material until accepted by the relevant human owner. Agents must not choose business authority, resolve contradictions by majority, approve semantic differences, expose unrestricted sensitive data, copy legacy passwords, initiate destructive maintenance, or authorize releases.

Every result must be labelled as observation, inference, contradiction, missing evidence, or unresolved decision. Test outcomes must be classified as passed, failed, blocked by missing evidence, not executable, or not applicable. “Processed,” “compiled,” matching counts, or tool completion do not establish equivalence.

A small delivery group and an independent reviewer should be assigned to each bounded task. The reviewer must not have produced the result under review. Combining human roles requires a prior segregation-of-duties and capacity review. Human business, data, security, operations, financial, interface, release, and recovery owners retain their respective decisions.

No production write access is assumed. Credentials, customer information, financial records, passwords, card-security values, messages, logs, dumps, and extracts require approved minimisation, masking, and handling. Telemetry must not contain sensitive payloads.

Preservation and decision discipline

Confirmed business behaviour, data meaning, calculations, error distinctions, interfaces, reports, messages, paging, sorting, correlation, rejection handling, audit history, data integrity, and customer continuity are to be preserved unless an accountable owner explicitly accepts a change supported by evidence and tests.

Contradictory rules—including card keys, omitted account-key components, page sizes, attention keys, maps, transfers, layouts, record lengths, transaction-file roles, batch ordering, authorization representations, and FTP direction—are assigned resolve status. They must not be normalized in implementation.

Possible but unconfirmed behaviour, optional capabilities, unknown consumers, and unavailable components are assigned defer or blocked status with their consequences recorded. Absence of source is not evidence that behaviour is absent.

A change decision must identify the affected behaviour or obligation, reason, accountable decision owner, compatibility effect, migration treatment, tests, recovery treatment, and customer or external effect. Unresolved decisions cannot silently become target architecture.

Progress, checkpoints, retries, and stopping

Progress is measured by accepted evidence and artifacts, not by files scanned, agent tasks completed, or code produced. Reporting must separate agent runtime, human analysis and review effort, waiting time, and elapsed working days. Waiting causes include access, extracts, shared environments, scarce reviewers, suppliers, licensing, business calendars, change freezes, report cycles, and governance.

Each slice has four checkpoints: bounded scope accepted for investigation; evidence and tests ready for independent review; acceptance and recovery evidence reviewed; and a separate human decision on whether any later release proposal may proceed. Passing a checkpoint grants no deployment authority.

A failed test returns the affected item to analysis with the observed state retained. A retry is permitted only after the cause, changed precondition, data-reset or compensation method, and expected external effects are documented. Unsafe replay, uncertain financial effects, unresolved destructive operations, exposed sensitive data, unknown consumers, or inability to restore a trustworthy starting state are stop conditions. Repeated retries must not overwrite prior evidence.

After the first accepted end-to-end slice, and after any material contradiction, failed rehearsal, new consumer, unsafe replay, recovery defect, or sensitive-data issue, the modernisation lead should re-estimate scenarios and capacity assumptions. Parallel agent activity does not remove serial human decisions or shared-environment constraints.

Slice: Establish the Deployed and Measurable Baseline

The allowlisted scope is read-only collection and comparison of approved programs, maps, copybooks, transactions, jobs, procedures, datasets, indexes, database and IMS structures, queues, configurations, generated artifacts, load modules, scheduler definitions, logs, and external-interface descriptions. It includes characterization-test design and measurement-definition drafting. It excludes production changes, target architecture selection, declaring artifacts obsolete without owner evidence, and invented performance baselines.

Required artifacts are an accountable deployed-baseline view, an evidence register retaining contradictions, dependency views, characterization cases, observation records, and candidate indicators with owner, source, method, sampling period, exclusions, and review cadence proposed. Targets remain unset.

The baseline analyst and measurement-design agent personas should be selected. Human binding should include the evidence and configuration custodian, relevant business-behaviour owners, mainframe specialists, data stewards, security representatives, operations staff, and interface owners. Independent characterization and measurement reviewers are required.

The gate requires material contradictions in the selected scope to be resolved, excluded with supporting evidence, or classified as blocked. Selected observations must be reproducible. Indicators lacking the required measurement definition are rejected.

Elapsed scenarios are 20, 45, and 90 working days. They are not staffing commitments or agent runtimes.

Slice: Resolve Data Authority and Rehearse Migration

The allowlisted scope is non-production comparison and rehearsal for approved customer, account, card, transaction, reference, authorization, fraud, user, and related representations. It may cover extraction, transfer, framing, decoding, transformation, rejection, loading, cleanup, restart, rerun, restoration, and reconciliation. It excludes deciding authority automatically, destructive production actions, and treating equal counts as semantic equivalence.

Required artifacts are representation classifications, layout and mapping decisions, unresolved discrepancy records, controlled test data, repeatable rehearsal descriptions, rejection results, restart and restoration evidence, and reconciliation covering applicable counts, referential integrity, uniqueness, sequence, status distributions, balances, and financial values.

The layout-comparison, migration-rehearsal, and data-reconciliation agent personas should be selected. Human binding requires the data authority and migration lead, domain and application owners, data stewards, security, privacy, records, and operations reviewers. An independent migration verifier is required.

The gate blocks unexplained differences affecting authoritative keys, financial values, security, customer continuity, or external effects. The IMS child-layout and unload-allocation discrepancy remains blocked for affected records until resolved.

Elapsed scenarios are 20, 50, and 110 working days, with possible indefinite waiting for inaccessible representations or unresolved framing.

Slice: Deliver the Read-Only Servicing Path

The allowlisted scope is one owner-selected account or card inquiry path, coexistence adapters, presentation or API behaviour, protected telemetry, comparison, and reversible routing. Updates, payments, credential migration, and broad domain decomposition are excluded.

Required artifacts are the accepted inquiry contract, field and storage mappings, key decisions, masking rules, contract tests, comparison results, operational signals, support notes, and witnessed routing-recovery evidence.

The servicing-path and contract-test agent personas should be selected. Human binding requires business and data owners plus security, accessibility, platform, operations, and release reviewers. An independent servicing reviewer and separate rollback witness are required.

The gate requires testing—not normalization—of card keys, account-key components, page sizes, attention keys, maps, transfer targets, snapshots, formatting, and presentation-to-storage mappings. Acceptance requires no unexplained authoritative-key or material-meaning difference, preserved not-found and error distinctions, telemetry without sensitive payloads, and rehearsed return to the legacy path.

Elapsed scenarios are 25, 55, and 105 working days.

Slice: Modernize Workforce Identity and User Administration

The allowlisted scope is approved workforce identity correlation, authentication integration, application authorization, ordinary and administrative routing, audit continuity, and confirmed user-administration outcomes. Copying legacy passwords or substituting Azure platform roles for business authorization is excluded.

Required artifacts are an identity-correlation disposition, approved role matrix, unmatched-identity treatment, session and failure decisions, privileged and break-glass rules, audit evidence, provider-failure tests, and fallback evidence.

The identity-correlation and authorization-test agent personas should be selected. Human binding requires business and security authorities and operations reviewers. Independent access-control and rollback reviewers are required.

The gate requires least privilege, segregation of duties, controlled unmatched identities, audit continuity, and fallback that cannot lock authorized users out of both paths. Lockout, retry, session duration, access review, deletion, federation, reset, and privileged-access thresholds remain owner decisions.

Elapsed scenarios are 20, 45, and 90 working days.

Slice: Establish Reference Data and Servicing Updates

The allowlisted scope is owner-approved transaction-type and category distribution plus bounded customer, account, or card updates. It includes concurrency, stale-read, propagation, rollback, and reconciliation testing. Ungoverned dual writes and assumptions about a possible card-security defect are excluded.

Required artifacts are authority and synchronization decisions, versioned distribution contracts, consumer inventory, update-state models, compound-key and uniqueness decisions, concurrency results, propagation reconciliation, sensitive-data handling decisions, and transaction or compensation evidence.

The reference-distribution and concurrency-test agent personas should be selected. Human binding requires domain owners, the data authority lead, business-behaviour owners, security reviewers, and operations. Independent transaction and data-control reviewers are required.

The gate requires exact agreed state transitions; tests for unchanged values, stale reads, simultaneous updates, deadlocks, retries, expiry, statuses, dependent deletion, and propagation failure; and either one demonstrated local transaction or an explicitly accepted compensation model. Unknown consumers or unresolved authority stop progression.

Elapsed scenarios are 30, 65, and 130 working days.

Slice: Cut Over Payments and Transaction Outcomes

The allowlisted scope is controlled characterization and non-production or otherwise specifically approved verification of payment and accepted-versus-rejected transaction outcomes. It includes duplicate, boundary, concurrency, restart, rerun, shadow comparison, failure injection, reconciliation, and recovery design. Agents may not approve calculations, tolerances, corrective entries, replay safety, or cutover.

Required artifacts are approved financial rules, identifier and duplicate semantics, state and rejection models, atomicity evidence, external-effect ledger, failure-injection results, reconciliation, and witnessed stop, rollback, or forward-recovery evidence.

The financial-characterization and reconciliation agent personas should be selected. Human binding requires business and finance-rule owners plus data, security, risk, and operations reviewers. An independent financial-effects reviewer and recovery witness are required.

The gate requires no duplicate real financial effect, no rejected work counted as successful, and no unaccounted external effect. Automatic rollback is ineligible where a target effect may remain unaccounted for. Any unexplained authoritative financial difference blocks progression.

Elapsed scenarios are 35, 80, and 170 working days.

Slice: Migrate Authorization, Fraud, Batch, Reporting, and Recovery

The allowlisted scope is separately governed characterization of authorization messaging, fraud processing, dependency-based batch workflows, reports, statements, backup, restore, and external-effect recovery. Fraud and authorization must remain distinct unless evidence establishes a shared lifecycle. Retirement is excluded from the slice’s execution authority.

Required artifacts are message and persistence timelines, correlation and retry contracts, fraud lifecycle evidence, batch dependency and restart models, report and statement reconciliations, retention decisions, destructive-operation recovery tests, restoration results, external-effect reconciliation, and unresolved-consumer records.

The messaging-analysis, fraud-analysis, batch-dependency, report-analysis, and recovery-analysis agent personas should be selected. Human binding requires messaging, fraud, business, data, records, security, operations, recovery, reporting, and external-interface owners. Independent reviews are required for each concern, including retirement readiness.

The gate covers failure before and after receipt, evaluation, persistence, publication, acknowledgement, timeout, retry, expiry, posting, destructive file work, and index rebuilding. Acceptance requires controlled in-flight work, no lost or duplicate processing, restartable batch, reconciled outputs, and restoration reconciled with queues, files, payments, reports, and observed responses. Unknown consumers, recovery gaps, retention duties, discrepancies, or fallback dependence block retirement consideration.

Elapsed scenarios are 45, 110, and 240 working days.

Azure selection boundaries

Azure services must be selected only after runtime, language, state, consistency, latency, throughput, residency, identity, recovery, support, and integration requirements are evidenced.

For application hosting, credible options include Azure App Service for supported web or API workloads, Azure Container Apps for containerized event-driven components, Azure Kubernetes Service where orchestration complexity is justified, and Azure Functions for bounded event-triggered work. No option is selected until execution duration, networking, scaling, operational skill, and transaction requirements are known.

For data, Azure SQL is a candidate for relational semantics; Azure Database for PostgreSQL is credible where compatibility and support fit; Cosmos DB is credible only where its partitioning and consistency model fit; and Azure Storage may suit files, immutable extracts, or staging. Legacy product names alone do not determine the target.

For integration, Service Bus may fit durable queues and topics, Event Grid event notification, Event Hubs high-volume streams, and managed file-transfer patterns bounded file exchange. MQ correlation, ordering, acknowledgement, retry, and response timing must be characterized before selection.

Microsoft Entra ID is the candidate workforce identity plane, but application authorization remains explicit. Key Vault is a candidate for secrets and keys. Azure Monitor, Application Insights, and Log Analytics are observability candidates subject to masking, retention, residency, and correlation decisions. Azure-native deployment services or approved enterprise tooling may support repeatable delivery, but tool choice grants no promotion authority.

Managed services are preferred only when they satisfy evidenced semantics and support obligations. Availability, RTO, RPO, performance, retention, encryption, private connectivity, backup, restore, patching, and monitoring remain design decisions requiring human acceptance.

Sequence and re-estimation

The likely critical path is the deployed baseline, data authority, servicing updates, payment outcomes, and authorization, fraud, batch, reporting, and recovery. The read-only and workforce-identity slices are prerequisites for servicing updates. Tighter coupling discovered through evidence may change this sequence.

Every slice requires its prerequisites and independent gate evidence. Coexistence must have a declared authority, reconciliation, and a credible rollback or forward-recovery treatment. Any deployment, traffic progression, cutover, retirement, or decommissioning proposal remains subject to separate accountable human review and authorization outside this contract.