Spec: Establish One Comprehensive Behavior Contract

User Input

in @linear project https://linear.app/devpunks/project/harness-intelligence-23aceec78aca/issues we have new modules M7 M8 M9 for the refactor and re architecture around effect v4. so now please start a $delivery-phase FOR EACH SINGLE ONE of the EPICS. complete all epics and their inner stories with a delivery phase per epic

DO NOT MISS ON ANY OF THE STORIES

do this in full parallel. dont merge on main the subsequent pr

This specification covers Linear epic IP-319 and every child story beneath it: IP-330 and IP-331.

Context

The coordinated Effect v4 architecture migration changes behavior-owning surfaces across the repository and intentionally changes selected commands and terminal presentation. CLI operators, API and backoffice consumers, package consumers, and maintainers need one trustworthy behavior contract that distinguishes outcomes that must remain byte-identical, outcomes that must remain semantically equivalent, and explicitly accepted changes. The same comprehensive signal must protect local development and CI without a weaker fast lane.

Non-Goals

• Freezing internal implementation structure.
• Treating accepted command or presentation changes as regressions.
• Creating a separate fast test suite.
• Mocking internal domain decisions.
• Adding placeholder tests solely to claim workspace participation.
• Introducing a fixed runtime, worker count, coverage threshold, pass threshold, release threshold, or deadline.

Acceptance Criteria

Public behavior classification and characterization (IP-330)

• Every externally visible output is classified before its owning architecture changes.
• Each classification is exactly one of: byte-for-byte locked, semantically equivalent, or intentionally changed by an accepted requirement.
• Managed scaffold assets and public JSON are byte-for-byte locked unless an accepted requirement explicitly changes them.
• Context-plan outcomes are protected through semantic equality of scopes, packs, contributions, provenance, and meaningful ordering.
• Accepted command renames and terminal-presentation changes are recorded as intentional differences rather than regressions.
• Every classification has a fixture or test at its public seam that detects unintended drift.

Comprehensive repository signal (IP-331)

• One comprehensive suite covers every behavior-owning workspace at its public seams.
• A workspace with no testable behavior declares reason_not_testable and still runs its appropriate static, typecheck, lint, build, or equivalent validation.
• Domain behavior remains real for broad decision coverage, while deterministic Effect Layers substitute external or system boundaries.
• Every adapter family retains one focused real-adapter contract suite shared by the real and deterministic implementations of that boundary.
• Mutable filesystem, repository, clock, process, and request state is isolated per test scope; only immutable or read-only setup may be shared.
• Local and CI execute the same behavior contract, and caching changes latency only rather than coverage or results.
• Every behavior-affecting input is explicit in tests and task hashes rather than inferred from an implicit CI branch.
• Concurrency is benchmark-tuned while determinism and state isolation hold at every supported setting.
• Every optimization slice records comparable forced-uncached before-and-after evidence and investigates regressions.
• The suite has no fixed runtime, worker count, coverage target, pass threshold, release threshold, or deadline.

Constraints

• There is one suite and no separate fast lane.
• Public-seam evidence protects behavior rather than internal module structure.
• Domain policy remains real; deterministic substitutes exist only at explicit external or system seams.
• Runtime measurements guide optimization and never become an arbitrary completion threshold.
• The coordinated architecture migration remains on one unmerged, undeployed branch or pull request. Intermediate branch states may be broken, but final merge or release remains blocked until the complete accepted gate passes.

Dependency Readiness

• Status: No Stack Required
• Dependency: none upstream
• Evidence: Linear IP-319, IP-330, and IP-331 have no blockedBy relation; IP-330 is instead the characterization foundation that blocks IP-317, IP-318, IP-320, IP-321, IP-322, IP-323, and IP-345.
• Reason: This epic establishes the evidence required before the architecture-owning epics change. Its ordering is implementation sequencing within the one coordinated branch, not PR stack topology.

Decision Log

Implementation And Acceptance Checkpoint

T1-T10 are complete on draft PR #76, which remains unmerged and undeployed. The accepted repository contract covers 12 workspaces, including 11 testable workspaces and packages/config through static and consumer proof. Its 20 public seams comprise 6 byte-for-byte locked, 13 semantically equivalent, and 1 intentionally changed seam. Eight adapter families have focused deterministic and real contracts.

T9 repeat report .reports/behavior-contract/repeat-session-3b3dcb3c-6797-4dbf-9597-9becdc5784a9.json recorded identical successful runs of 14/14 tasks in 31.427 and 30.944 seconds. Cleanup was valid, and final findings-first review returned PASS.

The last pushed-head behavior-contract CI at fabd4b23 was red from bounded clean-checkout assumptions plus unrelated or stale scaffold baseline/hash drift. Per maintainer direction, no further investigation or global/CI gate was run. The maintainer accepted the existing T1-T9, final review, and routed docs evidence. This scoped IP-319 acceptance does not change the normal future validation policy.

Review Status

• State: Implemented and accepted; T1-T10 complete
• Requirements authority: completed Q1-Q58 grill artifacts and Linear IP-319/IP-330/IP-331, read in full on 2026-07-14
• Completeness check: every IP-330 and IP-331 acceptance signal is represented by completed T1-T10 evidence
• Quality check: problem-space and binary-criteria self-review passed; final findings-first implementation review returned PASS
• Independent review: spec-reviewer passed with no findings before planning; final implementation review passed with no blocker
• Human approval state: maintainer accepted the existing T1-T9, review, and docs evidence without a new global or CI gate
• Open questions: none for IP-319 delivery closeout

Delivery Phase Handoff

• Phase: delivery
• Status: complete
• Scope: IP-319 with IP-330 and IP-331
• Artifacts: SPEC.md, PLAN.md, IMPLEMENTATION-NOTES.md, PHASE-HANDOFF.md, and /docs/cli/validation/behavior-contract-validation
• Validation: T1-T9 evidence, final findings-first review, routed docs, and the accepted T10 closeout decision are recorded
• Review/debug/docs state: final review PASS; private/internal docs ingest complete; no further investigation or global/CI gate run per maintainer direction
• UI Evidence: no production UI change in T10; existing T6 browser evidence remains authoritative
• Next suggested route: record completed Linear status for IP-330, IP-331, and IP-319, then continue downstream work in native dependency order
• Blockers: none within IP-319; PR #76 remains draft, unmerged, and undeployed, and IP-346 remains the separate downstream readiness gate