@zigrivers/scaffold 3.16.0 → 3.18.0

package/content/methodology/backend-fintech.yml

@@ -0,0 +1,46 @@
+# methodology/backend-fintech.yml
+name: backend-fintech
+description: >
+  Fintech domain sub-overlay — adds compliance, ledger design,
+  broker integration, order lifecycle, risk management, and
+  observability knowledge to backend projects.
+project-type: backend
+domain: fintech
+
+knowledge-overrides:
+  create-prd:
+    append: [backend-fintech-compliance, backend-fintech-broker-integration]
+  user-stories:
+    append: [backend-fintech-order-lifecycle, backend-fintech-risk-management]
+  domain-modeling:
+    append: [backend-fintech-ledger, backend-fintech-order-lifecycle, backend-fintech-data-modeling]
+  system-architecture:
+    append: [backend-fintech-broker-integration, backend-fintech-risk-management]
+  database-schema:
+    append: [backend-fintech-ledger, backend-fintech-data-modeling]
+  api-contracts:
+    append: [backend-fintech-order-lifecycle]
+  security:
+    append: [backend-fintech-compliance]
+  operations:
+    append: [backend-fintech-observability, backend-fintech-risk-management]
+  tdd:
+    append: [backend-fintech-testing]
+  create-evals:
+    append: [backend-fintech-testing, backend-fintech-compliance]
+  story-tests:
+    append: [backend-fintech-testing]
+  review-architecture:
+    append: [backend-fintech-broker-integration, backend-fintech-risk-management, backend-fintech-ledger]
+  review-api:
+    append: [backend-fintech-order-lifecycle]
+  review-database:
+    append: [backend-fintech-ledger, backend-fintech-data-modeling]
+  review-security:
+    append: [backend-fintech-compliance]
+  review-operations:
+    append: [backend-fintech-observability, backend-fintech-risk-management]
+  review-testing:
+    append: [backend-fintech-testing]
+  implementation-plan:
+    append: [backend-fintech-ledger, backend-fintech-broker-integration, backend-fintech-order-lifecycle, backend-fintech-risk-management, backend-fintech-compliance]

package/content/methodology/custom-defaults.yml

@@ -106,3 +106,9 @@ steps:
   analytics-telemetry: { enabled: false }
   live-ops-plan: { enabled: false }
   platform-cert-prep: { enabled: false }
+  # Multi-service steps (enabled via multi-service overlay)
+  service-ownership-map: { enabled: false }
+  inter-service-contracts: { enabled: false }
+  cross-service-auth: { enabled: false }
+  cross-service-observability: { enabled: false }
+  integration-test-plan: { enabled: false }

package/content/methodology/deep.yml

@@ -105,3 +105,9 @@ steps:
   analytics-telemetry: { enabled: false }
   live-ops-plan: { enabled: false }
   platform-cert-prep: { enabled: false }
+  # Multi-service steps (enabled via multi-service overlay)
+  service-ownership-map: { enabled: false }
+  inter-service-contracts: { enabled: false }
+  cross-service-auth: { enabled: false }
+  cross-service-observability: { enabled: false }
+  integration-test-plan: { enabled: false }

package/content/methodology/multi-service-overlay.yml

@@ -0,0 +1,103 @@
+name: multi-service
+description: >
+  Cross-service pipeline steps and knowledge for multi-service monorepos.
+  Activated by presence of services[] in config.
+
+# ---------------------------------------------------------------------------
+# step-overrides
+# ---------------------------------------------------------------------------
+step-overrides:
+  # Cross-service steps (wave 2)
+  service-ownership-map: { enabled: true }
+  inter-service-contracts: { enabled: true }
+  cross-service-auth: { enabled: true }
+  cross-service-observability: { enabled: true }
+  integration-test-plan: { enabled: true }
+  # Pre-phase steps marked global (already enabled — no-op for enablement,
+  # but marks them as global for the step classifier in wave 3b)
+  create-vision: { enabled: true }
+  review-vision: { enabled: true }
+  create-prd: { enabled: true }
+  review-prd: { enabled: true }
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+knowledge-overrides:
+  # Architecture awareness
+  system-architecture:
+    append: [multi-service-architecture, multi-service-resilience]
+  # Domain/data awareness
+  domain-modeling:
+    append: [multi-service-data-ownership]
+  database-schema:
+    append: [multi-service-data-ownership]
+  # API awareness
+  api-contracts:
+    append: [multi-service-api-contracts]
+  review-api:
+    append: [multi-service-api-contracts]
+  # Operations awareness
+  operations:
+    append: [multi-service-observability, multi-service-resilience]
+  review-operations:
+    append: [multi-service-observability]
+  # Security awareness
+  security:
+    append: [multi-service-auth]
+  review-security:
+    append: [multi-service-auth]
+  # Testing awareness
+  review-testing:
+    append: [multi-service-testing]
+  story-tests:
+    append: [multi-service-testing]
+  create-evals:
+    append: [multi-service-testing]
+  # Planning awareness
+  implementation-plan:
+    append: [multi-service-task-decomposition]
+  implementation-plan-review:
+    append: [multi-service-task-decomposition]
+
+# ---------------------------------------------------------------------------
+# reads-overrides
+# ---------------------------------------------------------------------------
+reads-overrides:
+  # Planning reads cross-service artifacts
+  implementation-plan:
+    append: [service-ownership-map, inter-service-contracts]
+  # Security review reads cross-service auth (order 952 < 960 allows this)
+  review-security:
+    append: [cross-service-auth]
+  # Database schema reads ownership map for data partitioning
+  database-schema:
+    append: [service-ownership-map]
+  # Validation phase reads all 5 new outputs for holistic review
+  cross-phase-consistency:
+    append:
+      - service-ownership-map
+      - inter-service-contracts
+      - cross-service-auth
+      - cross-service-observability
+      - integration-test-plan
+
+# ---------------------------------------------------------------------------
+# dependency-overrides
+# ---------------------------------------------------------------------------
+# Reads alone don't gate execution — `next` only checks dependencies.
+# These overrides ensure downstream steps wait for cross-service artifacts.
+dependency-overrides:
+  review-security:
+    append: [cross-service-auth]
+  database-schema:
+    append: [service-ownership-map]
+  implementation-plan:
+    append: [service-ownership-map, inter-service-contracts]
+  cross-phase-consistency:
+    append:
+      - service-ownership-map
+      - inter-service-contracts
+      - cross-service-auth
+      - cross-service-observability
+      - integration-test-plan

package/content/methodology/mvp.yml

@@ -105,3 +105,9 @@ steps:
   analytics-telemetry: { enabled: false }
   live-ops-plan: { enabled: false }
   platform-cert-prep: { enabled: false }
+  # Multi-service steps (enabled via multi-service overlay)
+  service-ownership-map: { enabled: false }
+  inter-service-contracts: { enabled: false }
+  cross-service-auth: { enabled: false }
+  cross-service-observability: { enabled: false }
+  integration-test-plan: { enabled: false }

package/content/pipeline/architecture/service-ownership-map.md

@@ -0,0 +1,83 @@
+---
+name: service-ownership-map
+description: Define logical domain and data ownership boundaries across services
+summary: "Maps which service owns which business domain, data concepts, and event topics. Establishes boundaries that inform database schema design, API contracts, and cross-service communication patterns."
+phase: "architecture"
+order: 721
+dependencies: [review-architecture]
+outputs: [docs/service-ownership-map.md]
+reads: [system-architecture, domain-modeling]
+conditional: null
+knowledge-base: [multi-service-architecture, multi-service-data-ownership]
+---
+
+## Purpose
+Define logical ownership boundaries across services: which service owns which
+business domain, data concepts, and event topics. Produces a reference document
+that informs database schema design, API contracts, and cross-service
+communication patterns. Prevents ownership ambiguity and data-coupling
+anti-patterns before implementation begins.
+
+## Inputs
+- docs/system-architecture.md (required) — service topology and responsibilities
+- docs/domain-modeling.md (optional) — bounded contexts and aggregate roots
+- docs/adrs/ (optional) — architecture decisions affecting service boundaries
+
+## Expected Outputs
+- docs/service-ownership-map.md — service-to-domain ownership matrix, data
+  concept ownership table, event topic ownership list, and cross-cutting concern
+  assignments
+
+## Quality Criteria
+- (mvp) Each service maps to at least one primary business domain
+- (mvp) Every core data concept has exactly one owning service (no orphans, no
+  co-owners)
+- (mvp) Cross-service reads are listed as explicit access patterns (not implicit
+  data sharing)
+- (deep) Event topic ownership assigned per service with producer/consumer roles
+  listed
+- (deep) Data sync strategies documented for each cross-service read pattern
+  (sync call, async replication, CQRS projection)
+- (deep) Ownership matrix covers all entities from domain model with no gaps
+- (deep) Cross-cutting concerns (auth, audit logging, rate limiting, feature
+  flags) assigned to named services or shared infrastructure
+- (deep) Boundary violations from the current architecture are identified and
+  flagged for resolution
+- (deep) Ownership conflicts (candidate co-owners) are surfaced with a
+  resolution rationale
+
+## Methodology Scaling
+- **deep**: Full ownership matrix with every entity and aggregate. Event flow
+  diagrams showing producer/consumer relationships. Data sync strategies per
+  cross-service read. Cross-cutting concern assignments with rationale. Boundary
+  violation inventory.
+- **mvp**: Service-to-domain mapping table. Primary data concept ownership list.
+  Cross-service read patterns enumerated without sync detail.
+- **custom:depth(1-5)**:
+  - Depth 1: service-to-domain mapping table only.
+  - Depth 2: add primary data concept ownership and list cross-service reads.
+  - Depth 3: add event topic ownership with producer/consumer roles.
+  - Depth 4: add data sync strategies, cross-cutting concern assignments, and
+    boundary violation flags.
+  - Depth 5: full ownership matrix with conflict resolution rationale, event flow
+    diagrams, and multi-region or multi-tenant ownership considerations.
+
+## Mode Detection
+Check for docs/service-ownership-map.md. If it exists, operate in update mode:
+read the existing map and diff against the current system architecture and any
+updated domain model. Preserve existing ownership assignments unless the
+architecture has explicitly reassigned a domain. Surface new services or data
+concepts that lack ownership entries and prompt for assignments. Never silently
+change an ownership assignment without documenting the reason.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/service-ownership-map.md exists
+- **Preserve**: established service-to-domain assignments, confirmed event topic
+  ownership, cross-cutting concern assignments, documented sync strategies
+- **Triggers for update**: new service added to architecture, domain model
+  changed aggregate boundaries, ADR reassigned data ownership, review identified
+  ownership ambiguity
+- **Conflict resolution**: if architecture added a new service that overlaps an
+  existing domain, surface the conflict with both candidate owners and request a
+  resolution decision before updating the map; do not silently absorb the new
+  service into an existing owner

package/content/pipeline/quality/cross-service-auth.md

@@ -0,0 +1,96 @@
+---
+name: cross-service-auth
+description: Define inter-service trust model — mTLS, service tokens, audience scoping
+summary: "Designs the internal service identity and trust framework: mutual TLS configuration, service-to-service token issuance and validation, audience scoping, and zero-trust boundary definitions."
+phase: "quality"
+order: 952
+dependencies: [security, service-ownership-map]
+outputs: [docs/cross-service-auth.md]
+reads: [inter-service-contracts]
+conditional: null
+knowledge-base: [multi-service-auth]
+---
+
+## Purpose
+Define the inter-service trust model for multi-service systems: how services
+establish identity, authenticate to one another, and enforce authorization at
+service boundaries. Produces a document specifying the chosen trust mechanism
+(mTLS, service tokens, or both), certificate or token lifecycle management,
+audience scoping per service, and zero-trust boundary definitions. Complements
+docs/security-review.md (which covers user-facing auth) by focusing exclusively
+on machine-to-machine trust.
+
+## Inputs
+- docs/security-review.md (required) — user-facing auth controls and trust model
+- docs/service-ownership-map.md (required) — which services communicate and
+  who owns which trust boundary
+- docs/inter-service-contracts.md (required) — auth mechanism noted per contract
+- docs/system-architecture.md (optional) — service topology and transport choices
+- docs/operations-runbook.md (optional) — certificate and secret rotation context
+
+## Expected Outputs
+- docs/cross-service-auth.md — inter-service trust model: identity approach,
+  mTLS configuration, token issuance and validation, audience scoping, and
+  zero-trust boundary definitions
+
+## Quality Criteria
+- (mvp) Trust mechanism chosen (mTLS, short-lived service tokens, or hybrid)
+  with rationale tied to architecture constraints
+- (mvp) Every cross-service call from the ownership map has an assigned trust
+  mechanism (no gaps)
+- (mvp) Audience scoping defined: each service token specifies the intended
+  recipient service and is rejected outside that scope
+- (mvp) Token issuance authority identified (internal token service, mesh
+  control plane, or cloud IAM)
+- (mvp) Certificate or token lifetime documented with rotation policy
+- (deep) mTLS configuration specified: CA hierarchy, certificate SAN fields,
+  validation rules, and revocation strategy
+- (deep) Token claims schema documented (issuer, subject, audience, expiry,
+  scope) with validation rules per receiving service
+- (deep) Zero-trust boundary definitions: each service trusts no caller by
+  default; allowed callers enumerated per service
+- (deep) Service identity bootstrapping process documented (how a new service
+  instance proves identity before receiving credentials)
+- (deep) Token revocation or short-lived-token refresh strategy documented for
+  compromise scenarios
+- (deep) Lateral movement controls: a compromised service cannot escalate
+  privileges or reach services outside its allowed caller list
+- (deep) Auth enforcement point identified per contract (sidecar, library, or
+  service-level middleware) so no contract relies on network-only isolation
+
+## Methodology Scaling
+- **deep**: Full zero-trust model. mTLS CA hierarchy with revocation strategy.
+  Token claims schema with validation rules per service. Service identity
+  bootstrapping. Lateral movement controls. Enforcement point per contract.
+- **mvp**: Trust mechanism choice with rationale. Audience scoping. Token
+  lifetime and rotation policy. Allowed-caller list per service.
+- **custom:depth(1-5)**:
+  - Depth 1: trust mechanism choice and audience scoping only.
+  - Depth 2: add token lifetime, rotation policy, and allowed-caller list per service.
+  - Depth 3: add token claims schema and validation rules; or mTLS CA hierarchy
+    and SAN fields if mTLS is chosen.
+  - Depth 4: add zero-trust boundary definitions, service identity bootstrapping,
+    and enforcement point per contract.
+  - Depth 5: full zero-trust model with lateral movement controls, revocation
+    strategy, and compromise-scenario runbook.
+
+## Mode Detection
+Check for docs/cross-service-auth.md. If it exists, operate in update mode:
+read the existing trust model and diff against the current service ownership
+map, security review, and inter-service contracts. Preserve confirmed trust
+mechanism choices, audience scoping rules, and rotation policies. Surface new
+cross-service calls that lack an assigned trust mechanism. Flag contracts whose
+auth mechanism changed in the inter-service contracts document.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/cross-service-auth.md exists
+- **Preserve**: confirmed trust mechanism, mTLS configuration, token claims
+  schema, audience scoping rules, rotation policies, zero-trust boundary
+  definitions, enforcement points
+- **Triggers for update**: ownership map added a new cross-service call,
+  security review changed the trust model, inter-service contracts updated
+  an auth mechanism, architecture changed transport or added a new service
+- **Conflict resolution**: if a new cross-service call introduces a caller
+  that is not on the allowed-caller list of the target service, surface the
+  gap and request an explicit approval decision before expanding the trust
+  boundary; never silently widen a zero-trust boundary

package/content/pipeline/quality/cross-service-observability.md

@@ -0,0 +1,104 @@
+---
+name: cross-service-observability
+description: Design distributed tracing, correlation IDs, and cross-service SLOs
+summary: "Defines the observability strategy for multi-service systems: distributed tracing propagation, correlation ID standards, cross-service SLO definitions, and failure isolation alerting."
+phase: "quality"
+order: 941
+dependencies: [review-operations, service-ownership-map]
+outputs: [docs/cross-service-observability.md]
+reads: [operations]
+conditional: null
+knowledge-base: [multi-service-observability]
+---
+
+## Purpose
+Design the observability strategy specific to multi-service systems: how traces
+propagate across service boundaries, how correlation IDs are generated and
+forwarded, what cross-service SLOs are defined and measured, and how alerting
+isolates failures to a specific service rather than surfacing them only at the
+user-facing layer. Extends the single-service monitoring strategy in
+docs/operations-runbook.md without redefining it — focusing on the interactions
+and dependencies between services.
+
+## Inputs
+- docs/operations-runbook.md (required) — single-service monitoring baseline
+  to extend
+- docs/service-ownership-map.md (required) — which services exist and how they
+  communicate
+- docs/system-architecture.md (optional) — service topology and transport choices
+- docs/inter-service-contracts.md (optional) — per-contract SLA targets to
+  derive SLOs from
+
+## Expected Outputs
+- docs/cross-service-observability.md — distributed tracing setup, correlation
+  ID standard, cross-service SLO definitions, failure isolation alerting strategy
+
+## Quality Criteria
+- (mvp) Distributed tracing standard chosen (OpenTelemetry, Jaeger, Zipkin, or
+  vendor-specific) with propagation format specified (W3C TraceContext, B3)
+- (mvp) Correlation ID standard defined: field name, generation point (entry
+  service or API gateway), forwarding requirement (all outbound calls must
+  propagate the ID)
+- (mvp) Every service in the ownership map emits traces with at minimum: service
+  name, operation name, trace ID, span ID, and error status
+- (mvp) Cross-service SLOs defined for at least the critical user-facing request
+  paths (availability and latency targets per path)
+- (deep) Sampling strategy defined: head-based vs. tail-based, sampling rate,
+  and rules for forcing full traces on errors or slow requests
+- (deep) Each cross-service SLO includes: the measured boundary (caller or
+  provider), the metric (p99 latency, error rate), the threshold, and the
+  measurement window
+- (deep) Error budget alerting: alert fires before 100% of monthly error budget
+  is consumed (e.g., at 50% and 90%), not only on threshold breach
+- (deep) Failure isolation alerting: alerts identify the originating service,
+  not just the user-facing symptom (dependency latency vs. internal latency
+  tracked separately)
+- (deep) Span attributes standardized across services: required attribute set
+  documented (HTTP method, status code, db system, messaging system, etc.)
+- (deep) Log correlation: every log line emitted during a traced request includes
+  the trace ID and span ID so logs and traces can be joined
+- (deep) Observability data retention policy defined per signal type (traces,
+  metrics, logs) with storage tier and cost rationale
+- (deep) Cross-service dashboard spec: describes what panels are needed to
+  diagnose a latency spike from entry point to the offending downstream service
+
+## Methodology Scaling
+- **deep**: Full distributed tracing setup with sampling strategy. Standardized
+  span attributes. Log-trace correlation. Cross-service SLOs with error budgets
+  and multi-threshold alerting. Failure isolation alerting. Dashboard spec.
+  Retention policy.
+- **mvp**: Tracing standard and propagation format. Correlation ID standard.
+  Cross-service SLOs for critical paths. Basic failure isolation alerting.
+- **custom:depth(1-5)**:
+  - Depth 1: tracing standard choice and correlation ID standard only.
+  - Depth 2: add per-service trace emission requirements and cross-service SLOs
+    for critical paths.
+  - Depth 3: add sampling strategy, span attribute standards, and log-trace
+    correlation.
+  - Depth 4: add error budget alerting, failure isolation alerting per service,
+    and cross-service dashboard spec.
+  - Depth 5: full observability strategy with retention policy, cost rationale,
+    and multi-region or multi-tenant trace propagation considerations.
+
+## Mode Detection
+Check for docs/cross-service-observability.md. If it exists, operate in update
+mode: read the existing observability strategy and diff against the current
+service ownership map and operations runbook. Preserve confirmed SLOs, sampling
+strategies, and correlation ID standards. Surface new services from the
+ownership map that lack trace emission requirements. Flag SLOs whose source
+contracts changed in the inter-service contracts document.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/cross-service-observability.md exists
+- **Preserve**: confirmed SLO definitions, error budget thresholds, sampling
+  strategy, correlation ID standard, span attribute requirements, log-trace
+  correlation rules, retention policy
+- **Triggers for update**: ownership map added a new service or cross-service
+  call, operations runbook changed the monitoring baseline, inter-service
+  contracts updated SLA targets, architecture changed transport or observability
+  infrastructure
+- **Conflict resolution**: if a new service from the ownership map has
+  conflicting SLO requirements (e.g., its provider SLA is tighter than the
+  existing consumer SLO), surface both targets and request a resolution
+  decision; never silently relax an existing SLO without documenting the
+  rationale

package/content/pipeline/quality/integration-test-plan.md

@@ -0,0 +1,106 @@
+---
+name: integration-test-plan
+description: Design contract tests, cross-service E2E flows, and service mocking strategy
+summary: "Plans the cross-service testing strategy: consumer-driven contract tests, integration test flows covering critical multi-service journeys, and service dependency mocking approaches for isolated testing."
+phase: "quality"
+order: 942
+dependencies: [review-testing, inter-service-contracts]
+outputs: [docs/integration-test-plan.md]
+reads: [service-ownership-map, cross-service-auth]
+conditional: null
+knowledge-base: [multi-service-testing]
+---
+
+## Purpose
+Design and document the cross-service testing strategy: consumer-driven contract
+tests that verify inter-service API compatibility without full-stack deployment,
+integration test flows covering critical multi-service user journeys, and
+service dependency mocking approaches that allow individual services to be
+tested in isolation. Extends the single-service TDD standards in
+docs/tdd-standards.md — focusing on the boundaries and interactions between
+services rather than unit or component tests within a single service.
+
+## Inputs
+- docs/tdd-standards.md (required) — single-service test standards to extend
+- docs/inter-service-contracts.md (required) — contracts to derive consumer-
+  driven tests from
+- docs/service-ownership-map.md (required) — which services communicate and
+  own which data concepts
+- docs/cross-service-auth.md (optional) — auth mechanism to include in
+  integration test flows
+
+## Expected Outputs
+- docs/integration-test-plan.md — contract testing approach, integration test
+  flow inventory, and service mocking strategy
+
+## Quality Criteria
+- (mvp) Contract testing tool chosen (Pact, Spring Cloud Contract, or equivalent)
+  with rationale
+- (mvp) Every cross-service call from the ownership map has a corresponding
+  consumer-driven contract test
+- (mvp) Consumer-driven contract tests run in CI on both consumer and provider
+  pipelines; provider cannot merge a breaking change without a failing test
+- (mvp) Integration test flows defined for at least the critical user-facing
+  multi-service journeys (happy path per journey)
+- (mvp) Each integration test flow identifies: the services involved, the entry
+  point, the data dependencies, and the expected end state
+- (deep) Contract tests cover: success responses, error responses, and schema
+  evolution cases (optional field added, field deprecated)
+- (deep) Provider state setup documented for each contract test: how to
+  bootstrap the provider into the correct state before verification
+- (deep) Service mocking strategy defined per dependency type: in-process stub,
+  WireMock/API mock server, or contract-verified test double
+- (deep) Mocking boundary policy stated: mocks are only used at service
+  boundaries (never mock internal collaborators in integration tests)
+- (deep) Integration test environment strategy: dedicated environment, ephemeral
+  per-PR environment, or service virtualization — with trade-offs documented
+- (deep) Cross-service auth included in integration test flows: service tokens
+  or mTLS certificates provisioned in the test environment
+- (deep) Flaky test mitigation strategy: retry policy for integration tests,
+  isolation rules (no shared state between tests), and quarantine process for
+  known-flaky tests
+- (deep) Data seeding and teardown approach: how test data is created and
+  cleaned up across services without leaking state between test runs
+
+## Methodology Scaling
+- **deep**: Full contract test suite per service pair with provider state setup.
+  Integration test flow inventory covering all critical journeys (happy and
+  error paths). Service mocking strategy with boundary policy. Flaky test
+  mitigation. Data seeding and teardown. Cross-service auth in test flows.
+  Integration environment strategy with trade-offs.
+- **mvp**: Contract testing tool choice. Consumer-driven tests per cross-service
+  call. Integration test flows for critical journeys (happy path). Basic
+  mocking strategy.
+- **custom:depth(1-5)**:
+  - Depth 1: contract testing tool choice and consumer-driven test list only.
+  - Depth 2: add integration test flows for critical journeys and basic mocking
+    strategy.
+  - Depth 3: add provider state setup, schema evolution test cases, and mocking
+    boundary policy.
+  - Depth 4: add integration environment strategy, cross-service auth in test
+    flows, and data seeding/teardown approach.
+  - Depth 5: full plan with flaky test mitigation, quarantine process, and
+    multi-environment or multi-tenant testing considerations.
+
+## Mode Detection
+Check for docs/integration-test-plan.md. If it exists, operate in update mode:
+read the existing plan and diff against the current inter-service contracts and
+service ownership map. Preserve confirmed contract test tool choice, mocking
+strategy, and integration test flows. Surface new cross-service calls from the
+ownership map that lack contract tests. Flag flows whose participating services
+changed in the architecture.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/integration-test-plan.md exists
+- **Preserve**: confirmed contract testing tool, consumer-driven test inventory,
+  provider state setup, mocking strategy, integration environment choice,
+  flaky test mitigation rules, data seeding approach
+- **Triggers for update**: ownership map added a new cross-service call,
+  inter-service contracts changed a schema or auth mechanism, architecture
+  added or removed a service, security review identified new auth requirements
+  that affect test flows
+- **Conflict resolution**: if a new cross-service call from the ownership map
+  has no clear owner for writing the consumer-driven contract test, surface the
+  ambiguity and request an ownership assignment before adding the test entry;
+  never add a contract test without a designated consumer team responsible for
+  maintaining it

package/content/pipeline/specification/inter-service-contracts.md

@@ -0,0 +1,95 @@
+---
+name: inter-service-contracts
+description: Design API contracts between services with versioning, retries, and failure isolation
+summary: "Specifies internal service-to-service API contracts including versioning strategy, backward compatibility rules, retry policies, timeout budgets, idempotency requirements, and failure isolation patterns."
+phase: "specification"
+order: 841
+dependencies: [service-ownership-map, review-api]
+outputs: [docs/inter-service-contracts.md]
+reads: [api-contracts]
+conditional: null
+knowledge-base: [multi-service-api-contracts, multi-service-resilience]
+---
+
+## Purpose
+Design and document the internal API contracts between services: endpoint
+signatures, versioning strategy, backward compatibility rules, retry policies,
+timeout budgets, idempotency requirements, and failure isolation patterns.
+Produces a contract document that governs how services call one another and
+what guarantees callers can rely on, distinct from the public-facing API
+contracts in docs/api-contracts.md.
+
+## Inputs
+- docs/service-ownership-map.md (required) — which services communicate and
+  who owns which data concepts
+- docs/api-contracts.md (required) — public API patterns to align with
+- docs/system-architecture.md (optional) — service topology and transport choices
+- docs/adrs/ (optional) — decisions affecting inter-service transport or
+  resilience strategy
+
+## Expected Outputs
+- docs/inter-service-contracts.md — per-contract specifications covering
+  endpoint or event schema, versioning, retry policy, timeout budget,
+  idempotency, and failure isolation
+
+## Quality Criteria
+- (mvp) Every cross-service call from the ownership map has a corresponding
+  contract entry
+- (mvp) Each contract specifies the caller, the provider, the operation name,
+  and the transport (HTTP, gRPC, message queue, etc.)
+- (mvp) Versioning strategy defined (URI prefix, header, schema version field)
+  and applied consistently across all contracts
+- (mvp) Backward compatibility rules stated (additive-only, deprecation window,
+  breaking-change process)
+- (deep) Each contract has an explicit timeout budget with rationale tied to
+  the caller's own SLA
+- (deep) Retry policy specified per contract: max attempts, backoff strategy
+  (exponential + jitter), retryable vs. non-retryable error codes
+- (deep) Idempotency requirements stated per operation (idempotency key, safe
+  to retry, at-most-once)
+- (deep) Failure isolation pattern assigned per contract (circuit breaker,
+  bulkhead, fallback response, graceful degradation)
+- (deep) Each contract documents its SLA: expected p99 latency and error
+  budget
+- (deep) Schema evolution rules documented (required vs. optional fields,
+  unknown field handling, enum extension policy)
+- (deep) Authentication and authorization mechanism specified for each
+  contract (service-to-service token, mTLS, API key scope)
+
+## Methodology Scaling
+- **deep**: Full contract specification per service pair. Timeout budgets with
+  SLA rationale. Retry and backoff policies. Idempotency guarantees. Failure
+  isolation patterns (circuit breaker, bulkhead). Schema evolution rules.
+  Auth mechanism per contract.
+- **mvp**: Contract list with caller, provider, operation, and transport.
+  Versioning strategy. Backward compatibility rules.
+- **custom:depth(1-5)**:
+  - Depth 1: contract list with caller, provider, operation, and transport only.
+  - Depth 2: add versioning strategy and backward compatibility rules.
+  - Depth 3: add timeout budgets, retry policies, and idempotency requirements.
+  - Depth 4: add failure isolation patterns, SLA documentation, and schema
+    evolution rules.
+  - Depth 5: full specification with auth mechanism per contract, consumer-driven
+    contract testing strategy, and multi-version coexistence plan.
+
+## Mode Detection
+Check for docs/inter-service-contracts.md. If it exists, operate in update
+mode: read the existing contracts and diff against the current service
+ownership map and API review findings. Preserve all confirmed contracts.
+Surface new cross-service calls from the ownership map that lack contract
+entries. Flag contracts whose provider or transport changed in the architecture
+and require review. Never silently change a retry policy or timeout budget
+without documenting the reason.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/inter-service-contracts.md exists
+- **Preserve**: confirmed retry policies, timeout budgets, idempotency
+  guarantees, failure isolation patterns, versioning strategy, auth mechanisms
+- **Triggers for update**: ownership map added a new cross-service call,
+  API review identified a missing contract, architecture changed transport for
+  a service pair, ADR updated resilience strategy
+- **Conflict resolution**: if a new cross-service call from the ownership map
+  conflicts with an existing contract boundary (e.g., caller now bypasses the
+  designated provider), surface the conflict and request resolution before
+  adding the new contract entry; do not silently add a contract that undermines
+  an existing ownership assignment