git-learn/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-interface-impact/spec.md

ADDED Requirements

Requirement: Interface changes have impact records

SM Flow SHALL require every interface-related change to record interface impact before Phase 3.

Scenario: Internal interface field changes

• WHEN a change adds, removes, renames, or changes the semantics of a field, DTO, service method, event, API, callback, database contract, or command contract
• THEN the flow records the affected interface, affected consumers, compatibility expectation, and validation method in OpenSpec design/specs/tasks or devflow evidence/decisions

Scenario: Interface uncertainty

• WHEN the agent cannot determine whether a change affects an interface contract
• THEN the flow treats it as an interface-impact question and asks for confirmation before Phase 3

Scenario: Internal decision logic changes observable behavior

• WHEN a change modifies internal decision logic inside an interface and the result can change returned data, status, error code, permission result, validation result, ordering, filtering, idempotency, timing, or side effects
• THEN the flow treats the change as interface impact even if the interface shape and field names are unchanged

Requirement: Interface documentation is level-gated

SM Flow SHALL create an independent interface document only when the interface impact level requires it.

Scenario: Low-risk internal interface change

• WHEN an interface change is limited to internal implementation or an internal module boundary and has no external consumers
• THEN the flow records the interface impact inline without requiring a standalone interface document

Scenario: External or breaking interface change

• WHEN an interface change affects external APIs, SDKs, callbacks, events, database contracts, cross-team consumers, or breaks backward compatibility
• THEN the flow requires a standalone interface document or equivalent explicit section covering consumers, compatibility, migration, rollback, and validation

Requirement: Interface impact levels use risk-based classification

SM Flow SHALL classify interface impact by consumer boundary, contract semantics, and compatibility risk.

Scenario: L1 internal implementation

• WHEN a change does not alter any consumer-visible interface shape, field, status, error, data range, ordering, permission result, state transition, side effect, or documented behavior
• THEN the flow classifies it as L1 and records validation in tasks or acceptance without requiring interface impact documentation

Scenario: L2 internal interface

• WHEN a change affects internal DTOs, service methods, internal events, internal RPC, or internal decision logic and all consumers are inside the same implementation scope
• THEN the flow classifies it as L2 and records interface impact inline

Scenario: L3 collaboration interface

• WHEN a change affects other modules, services, frontend callers, external systems, cross-team consumers, database contracts, events, callbacks, or SDK users
• THEN the flow classifies it as L3 and requires a standalone interface document or equivalent explicit section

Scenario: L4 breaking interface

• WHEN old consumers can fail, receive less data, receive more data, observe different statuses or errors, require migration, require rollback, or lose backward compatibility
• THEN the flow classifies it as L4 and requires standalone interface documentation plus migration and rollback notes