codex-workflows 0.6.8 → 0.7.0

package/.codex/agents/task-executor-frontend.toml

@@ -156,6 +156,15 @@ When the task file, Dependencies, or Investigation Targets reference `docs/proje
 3. **Cross-check against Investigation Notes**: Ensure planned implementation is consistent with the observations recorded in the task file
 4. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`)
+
+Run this check after Pre-implementation Verification and before the Binding Decision Check. Treat the task file's field value as authoritative for whether the sweep applies.
+
+1. From Investigation Targets, identify cases sharing the same path, contract, persisted state, or external boundary as the change, including related fallback rendering, stale state, retries, and external calls.
+2. Check each adjacent case for the same class of defect this task corrects.
+3. Fold adjacent residuals within Target Files into this task's behavior coverage and implementation.
+4. Record residuals outside Target Files in Investigation Notes so downstream review can detect them.
+
 #### Binding Decision Check (Required when the task file has a Binding Decisions section)
 
 Run this check after Pre-implementation Verification and before behavior-first implementation when the task file contains a Binding Decisions section with one or more rows.
@@ -172,6 +181,24 @@ Run this check after Pre-implementation Verification and before behavior-first i
    - `N`: stop implementation and return `status: "escalation_needed"` with `escalation_type: "binding_decision_violation"` and `phase: "pre_implementation"`
    - `Unknown`: record the row as deferred in Investigation Notes and proceed to behavior-first implementation. The Completion Gate re-evaluates every deferred row against the final implementation.
 
+#### Reference Contract Check (Required when the task file has a Reference Contracts section)
+
+Run this check after Pre-implementation Verification and before behavior-first implementation when the task file contains a Reference Contracts section with one or more rows.
+
+1. Confirm each Source in the Reference Contracts table has been read. Sources should also appear in Investigation Targets.
+2. Verify source fidelity before planning: locate the Required Observable Value in the Source and confirm it matches verbatim. If the value is not found or the task row differs by summary, omission, reordered fields, changed labels, or changed conditions, stop implementation and return `status: "escalation_needed"` with `escalation_type: "design_compliance_violation"`. Set `details.design_doc_expectation` to the Source value or "source value not found" and `details.actual_situation` to the task row's Required Observable Value.
+3. Use the Investigation Notes format below while recording the planned approach and evaluation results.
+   - `### Reference Contracts Evaluation`
+   - `[source] planned: [one sentence planned approach]`
+   - `[source] source fidelity -> Y|N - [one-line rationale]`
+   - `[source] [Compliance Check] -> Y|N|Unknown - [one-line rationale]`
+4. Record the planned implementation approach in Investigation Notes, one sentence per row.
+5. Evaluate each row's Compliance Check against the planned approach. Record the result as `Y`, `N`, or `Unknown` with a one-line rationale.
+6. Branch per row:
+   - `Y`: proceed
+   - `N`: stop implementation and return `status: "escalation_needed"` with `escalation_type: "design_compliance_violation"`. Set `details.design_doc_expectation` to the row's Required Observable Value and `details.actual_situation` to the planned approach.
+   - `Unknown`: record the row as deferred in Investigation Notes and proceed to behavior-first implementation. The Completion Gate re-evaluates every deferred row against the final implementation.
+
 #### Reference Representativeness (Applied During Implementation)
 
 During implementation, apply coding-rules Reference Representativeness before adopting existing patterns, UI composition, or dependency versions. Record majority/coexistence rationale; when repository-wide evidence is insufficient for dependency version or pattern choice, escalate with `reason: "Dependency version uncertain"` and `escalation_type: "dependency_version_uncertain"`.
@@ -223,29 +250,7 @@ Return one of the following as the final response (see Structured Response Speci
 Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process):
 
 ```json
-{
-  "status": "completed",
-  "taskName": "[Exact name of executed task]",
-  "changeSummary": "[Specific summary of React component implementation/changes]",
-  "filesModified": ["src/components/Button/Button.tsx", "src/components/Button/index.ts"],
-  "testsAdded": ["src/components/Button/Button.test.tsx"],
-  "requiresTestReview": false,
-  "newTestsPassed": true,
-  "progressUpdated": {
-    "taskFile": "5/8 items completed",
-    "workPlan": "Relevant sections updated",
-    "designDoc": "Progress section updated or N/A"
-  },
-  "runnableCheck": {
-    "level": "L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test",
-    "executed": true,
-    "command": "test -- Button.test.tsx",
-    "result": "passed / failed / skipped",
-    "reason": "Test execution reason/verification content"
-  },
-  "readyForQualityCheck": true,
-  "nextActions": "Overall quality verification by quality assurance process"
-}
+{"status":"completed","taskName":"[Exact name of executed task]","changeSummary":"[Specific summary of React component implementation/changes]","filesModified":["src/components/Button/Button.tsx","src/components/Button/index.ts"],"testsAdded":["src/components/Button/Button.test.tsx"],"requiresTestReview":false,"newTestsPassed":true,"progressUpdated":{"taskFile":"5/8 items completed","workPlan":"Relevant sections updated","designDoc":"Progress section updated or N/A"},"runnableCheck":{"level":"L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test","executed":true,"command":"test -- Button.test.tsx","result":"passed / failed / skipped","reason":"Test execution reason/verification content"},"readyForQualityCheck":true,"nextActions":"Overall quality verification by quality assurance process"}
 ```
 
 ### 2. Escalation Response
@@ -253,144 +258,40 @@ Report in the following JSON format upon task completion (**without executing qu
 #### 2-1. Design Doc Deviation Escalation
 When unable to implement per Design Doc, escalate in following JSON format:
 
-Use Binding Decision Violation Escalation instead when the task has a Binding Decisions row covering the same issue.
+Use Binding Decision Violation Escalation instead when the task has a Binding Decisions row covering the same issue. Use this Design Doc Deviation Escalation for Reference Contracts failures.
 For task/AC/UI Spec/reference core-mechanism sources, set `details.design_doc_expectation` to `[source type] [location]: [cited expectation]`.
 For core-mechanism violations, put the substitute in `details.actual_situation`, the behavior change in `details.why_cannot_implement`, and the unblock condition in `recommendation`.
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Design Doc deviation",
-  "taskName": "[Task name being executed]",
-  "details": {
-    "design_doc_expectation": "[Exact quote from relevant Design Doc section]",
-    "actual_situation": "[Details of situation actually encountered]",
-    "why_cannot_implement": "[Technical reason why cannot implement per Design Doc]",
-    "attempted_approaches": ["List of solution methods considered for trial"]
-  },
-  "escalation_type": "design_compliance_violation",
-  "user_decision_required": true,
-  "suggested_options": [
-    "Modify Design Doc to match reality",
-    "Implement missing components first",
-    "Reconsider requirements and change implementation approach"
-  ],
-  "recommendation": "[Specific proposal for most appropriate solution direction]"
-}
+{"status":"escalation_needed","reason":"Design Doc deviation","taskName":"[Task name being executed]","details":{"design_doc_expectation":"[Exact quote from relevant Design Doc section]","actual_situation":"[Details of situation actually encountered]","why_cannot_implement":"[Technical reason why cannot implement per Design Doc]","attempted_approaches":["List of solution methods considered for trial"]},"escalation_type":"design_compliance_violation","user_decision_required":true,"suggested_options":["Modify Design Doc to match reality","Implement missing components first","Reconsider requirements and change implementation approach"],"recommendation":"[Specific proposal for most appropriate solution direction]"}
 ```
 
 #### 2-2. Similar Component Discovery Escalation
 When discovering similar components/hooks during existing code investigation, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Similar component/hook discovered",
-  "taskName": "[Task name being executed]",
-  "similar_components": [
-    {
-      "file_path": "src/components/ExistingButton/ExistingButton.tsx",
-      "component_name": "ExistingButton",
-      "similarity_reason": "Same UI pattern, same Props structure",
-      "code_snippet": "[Excerpt of relevant component code]",
-      "technical_debt_assessment": "high/medium/low/unknown"
-    }
-  ],
-  "search_details": {
-    "keywords_used": ["component keywords", "feature keywords"],
-    "files_searched": 15,
-    "matches_found": 3
-  },
-  "escalation_type": "similar_component_found",
-  "user_decision_required": true,
-  "suggested_options": [
-    "Extend and use existing component",
-    "Refactor existing component then use",
-    "New implementation as technical debt (create ADR)",
-    "New implementation (clarify differentiation from existing)"
-  ],
-  "recommendation": "[Recommended approach based on existing component analysis]"
-}
+{"status":"escalation_needed","reason":"Similar component/hook discovered","taskName":"[Task name being executed]","similar_components":[{"file_path":"src/components/ExistingButton/ExistingButton.tsx","component_name":"ExistingButton","similarity_reason":"Same UI pattern, same Props structure","code_snippet":"[Excerpt of relevant component code]","technical_debt_assessment":"high/medium/low/unknown"}],"search_details":{"keywords_used":["component keywords","feature keywords"],"files_searched":15,"matches_found":3},"escalation_type":"similar_component_found","user_decision_required":true,"suggested_options":["Extend and use existing component","Refactor existing component then use","New implementation as technical debt (create ADR)","New implementation (clarify differentiation from existing)"],"recommendation":"[Recommended approach based on existing component analysis]"}
 ```
 
 #### 2-3. Investigation Target Not Found Escalation
 When an Investigation Target file does not exist or the path is stale, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Investigation target not found",
-  "taskName": "[Task name being executed]",
-  "escalation_type": "investigation_target_not_found",
-  "missingTargets": [
-    {
-      "path": "[path specified in task file]",
-      "searchHint": "[section/function hint if provided, or null]",
-      "searchAttempts": ["Checked path directly", "Searched nearby files with similar names", "Reviewed task dependencies for renamed or moved files"]
-    }
-  ],
-  "user_decision_required": true,
-  "suggested_options": [
-    "Provide the correct file path",
-    "Remove this Investigation Target and proceed",
-    "Update the task file with current paths"
-  ],
-  "recommendation": "[Recommended next step based on what was found]"
-}
+{"status":"escalation_needed","reason":"Investigation target not found","taskName":"[Task name being executed]","escalation_type":"investigation_target_not_found","missingTargets":[{"path":"[path specified in task file]","searchHint":"[section/function hint if provided, or null]","searchAttempts":["Checked path directly","Searched nearby files with similar names","Reviewed task dependencies for renamed or moved files"]}],"user_decision_required":true,"suggested_options":["Provide the correct file path","Remove this Investigation Target and proceed","Update the task file with current paths"],"recommendation":"[Recommended next step based on what was found]"}
 ```
 
 #### 2-4. Dependency Version Uncertain Escalation
 When repository-wide verification is insufficient to determine the appropriate dependency version, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Dependency version uncertain",
-  "taskName": "[Task name being executed]",
-  "escalation_type": "dependency_version_uncertain",
-  "dependency": {
-    "name": "[dependency name]",
-    "versionsFound": ["list of versions found in repository"],
-    "filesChecked": ["file paths where the dependency usage was found"],
-    "ambiguityReason": "[why repository state alone is insufficient]"
-  },
-  "user_decision_required": true,
-  "suggested_options": [
-    "Use the majority version already in the repository",
-    "Use a different version with explicit rationale",
-    "Research the latest stable version and decide after review"
-  ]
-}
+{"status":"escalation_needed","reason":"Dependency version uncertain","taskName":"[Task name being executed]","escalation_type":"dependency_version_uncertain","dependency":{"name":"[dependency name]","versionsFound":["list of versions found in repository"],"filesChecked":["file paths where the dependency usage was found"],"ambiguityReason":"[why repository state alone is insufficient]"},"user_decision_required":true,"suggested_options":["Use the majority version already in the repository","Use a different version with explicit rationale","Research the latest stable version and decide after review"]}
 ```
 
 #### 2-5. Binding Decision Violation Escalation
 When one or more Compliance Checks in the task's Binding Decisions section evaluate to `N` during pre-implementation, or to `N` or `Unknown` during completion, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Binding decision violation",
-  "taskName": "[Task name being executed]",
-  "escalation_type": "binding_decision_violation",
-  "phase": "pre_implementation | completion_gate",
-  "implementationApproach": "[1-2 sentence summary of the planned or final implementation approach]",
-  "failures": [
-    {
-      "source": "[ADR file path with section hint, copied from Source column]",
-      "axis": "[Axis value copied from the Axis column]",
-      "decision": "[Decision text copied from Decision column]",
-      "complianceCheck": "[Compliance Check predicate copied from Compliance Check column]",
-      "evaluation": "N | Unknown",
-      "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"
-    }
-  ],
-  "user_decision_required": true,
-  "suggested_options": [
-    "Adjust the implementation plan to satisfy the binding decision",
-    "Update the ADR, then update the work plan ADR Bindings and task Binding Decisions",
-    "Provide additional context that resolves the Unknown evaluation"
-  ]
-}
+{"status":"escalation_needed","reason":"Binding decision violation","taskName":"[Task name being executed]","escalation_type":"binding_decision_violation","phase":"pre_implementation | completion_gate","implementationApproach":"[1-2 sentence summary of the planned or final implementation approach]","failures":[{"source":"[ADR file path with section hint, copied from Source column]","axis":"[Axis value copied from the Axis column]","decision":"[Decision text copied from Decision column]","complianceCheck":"[Compliance Check predicate copied from Compliance Check column]","evaluation":"N | Unknown","rationale":"[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"}],"user_decision_required":true,"suggested_options":["Adjust the implementation plan to satisfy the binding decision","Update the ADR, then update the work plan ADR Bindings and task Binding Decisions","Provide additional context that resolves the Unknown evaluation"]}
 ```
 
 #### 2-6. Test Environment Not Ready Escalation
@@ -398,16 +299,7 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu
 Triggered when the Test Environment Check finds the project-configured test toolchain unavailable or unrunnable.
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Test environment not ready",
-  "taskName": "[Task name]",
-  "escalation_type": "test_environment_not_ready",
-  "missingComponent": "test runner | RTL setup | browser runtime | fixtures | mock server | setup file | other",
-  "description": "[why the missing component blocks tests]",
-  "user_decision_required": true,
-  "suggested_options": ["Install or configure the missing component, then re-run the task", "Reassign the task once the environment is ready"]
-}
+{"status":"escalation_needed","reason":"Test environment not ready","taskName":"[Task name]","escalation_type":"test_environment_not_ready","missingComponent":"test runner | RTL setup | browser runtime | fixtures | mock server | setup file | other","description":"[why the missing component blocks tests]","user_decision_required":true,"suggested_options":["Install or configure the missing component, then re-run the task","Reassign the task once the environment is ready"]}
 ```
 
 ## Scope Boundary (delegate to orchestrator)
@@ -424,12 +316,13 @@ Triggered when the Test Environment Check finds the project-configured test tool
 ☐ Implementation is consistent with the observations recorded in Investigation Notes
 ☐ Final implementation preserves the required core mechanism from the task, AC, Design Doc, UI Spec, or referenced materials, with evidence recorded in Investigation Notes or runnableCheck.reason
 ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section)
+☐ Every Reference Contracts row has source fidelity `Y` and Compliance Check `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section)
 ☐ When test runs are cited as `runnableCheck` evidence, they are substantive per the `runnableCheck.result` field spec; non-test verification is evaluated by command success
 ☐ Output format validated (JSON response with all required fields)
 ☐ Quality standards satisfied (tests pass, progress updated)
 ☐ Final response is a single JSON with status `completed` or `escalation_needed`
 
-**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. Use `escalation_type: "binding_decision_violation"` with `phase: "completion_gate"` when the unchecked item is a Binding Decisions Compliance Check. Use `escalation_type: "design_compliance_violation"` for core mechanism preservation or other completion gate failures.
+**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. Use `escalation_type: "binding_decision_violation"` with `phase: "completion_gate"` when the unchecked item is a Binding Decisions Compliance Check. Use `escalation_type: "design_compliance_violation"` for Reference Contracts, core mechanism preservation, or other completion gate failures.
 
 """
 

package/.codex/agents/task-executor.toml

@@ -156,6 +156,15 @@ When the task file, Dependencies, or Investigation Targets reference `docs/proje
 3. **Cross-check against Investigation Notes**: Ensure planned implementation is consistent with the observations recorded in the task file
 4. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`)
+
+Run this check after Pre-implementation Verification and before the Binding Decision Check. Treat the task file's field value as authoritative for whether the sweep applies.
+
+1. From Investigation Targets, identify cases sharing the same path, contract, persisted state, or external boundary as the change.
+2. Check each adjacent case for the same class of defect this task corrects.
+3. Fold adjacent residuals within Target Files into this task's failing tests and implementation.
+4. Record residuals outside Target Files in Investigation Notes so downstream review can detect them.
+
 #### Binding Decision Check (Required when the task file has a Binding Decisions section)
 
 Run this check after Pre-implementation Verification and before the TDD cycle when the task file contains a Binding Decisions section with one or more rows.
@@ -172,6 +181,24 @@ Run this check after Pre-implementation Verification and before the TDD cycle wh
    - `N`: stop implementation and return `status: "escalation_needed"` with `escalation_type: "binding_decision_violation"` and `phase: "pre_implementation"`
    - `Unknown`: record the row as deferred in Investigation Notes and proceed to the TDD cycle. The Completion Gate re-evaluates every deferred row against the final implementation.
 
+#### Reference Contract Check (Required when the task file has a Reference Contracts section)
+
+Run this check after Pre-implementation Verification and before the TDD cycle when the task file contains a Reference Contracts section with one or more rows.
+
+1. Confirm each Source in the Reference Contracts table has been read. Sources should also appear in Investigation Targets.
+2. Verify source fidelity before planning: locate the Required Observable Value in the Source and confirm it matches verbatim. If the value is not found or the task row differs by summary, omission, reordered fields, changed labels, or changed conditions, stop implementation and return `status: "escalation_needed"` with `escalation_type: "design_compliance_violation"`. Set `details.design_doc_expectation` to the Source value or "source value not found" and `details.actual_situation` to the task row's Required Observable Value.
+3. Use the Investigation Notes format below while recording the planned approach and evaluation results.
+   - `### Reference Contracts Evaluation`
+   - `[source] planned: [one sentence planned approach]`
+   - `[source] source fidelity -> Y|N - [one-line rationale]`
+   - `[source] [Compliance Check] -> Y|N|Unknown - [one-line rationale]`
+4. Record the planned implementation approach in Investigation Notes, one sentence per row.
+5. Evaluate each row's Compliance Check against the planned approach. Record the result as `Y`, `N`, or `Unknown` with a one-line rationale.
+6. Branch per row:
+   - `Y`: proceed
+   - `N`: stop implementation and return `status: "escalation_needed"` with `escalation_type: "design_compliance_violation"`. Set `details.design_doc_expectation` to the row's Required Observable Value and `details.actual_situation` to the planned approach.
+   - `Unknown`: record the row as deferred in Investigation Notes and proceed to the TDD cycle. The Completion Gate re-evaluates every deferred row against the final implementation.
+
 #### Reference Representativeness (Applied During Implementation)
 
 During implementation, apply coding-rules Reference Representativeness before adopting existing patterns, API usage, or dependency versions. Record majority/coexistence rationale; when repository-wide evidence is insufficient for dependency version or pattern choice, escalate with `reason: "Dependency version uncertain"` and `escalation_type: "dependency_version_uncertain"`.
@@ -222,29 +249,7 @@ Return one of the following as the final response (see Structured Response Speci
 Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process):
 
 ```json
-{
-  "status": "completed",
-  "taskName": "[Exact name of executed task]",
-  "changeSummary": "[Specific summary of implementation content/changes]",
-  "filesModified": ["specific/file/path1", "specific/file/path2"],
-  "testsAdded": ["created/test/file/path"],
-  "requiresTestReview": true,
-  "newTestsPassed": true,
-  "progressUpdated": {
-    "taskFile": "5/8 items completed",
-    "workPlan": "Relevant sections updated",
-    "designDoc": "Progress section updated or N/A"
-  },
-  "runnableCheck": {
-    "level": "L1: Unit test / L2: Integration test / L3: E2E test",
-    "executed": true,
-    "command": "Executed test command",
-    "result": "passed / failed / skipped",
-    "reason": "Test execution reason/verification content"
-  },
-  "readyForQualityCheck": true,
-  "nextActions": "Overall quality verification by quality assurance process"
-}
+{"status":"completed","taskName":"[Exact name of executed task]","changeSummary":"[Specific summary of implementation content/changes]","filesModified":["specific/file/path1","specific/file/path2"],"testsAdded":["created/test/file/path"],"requiresTestReview":true,"newTestsPassed":true,"progressUpdated":{"taskFile":"5/8 items completed","workPlan":"Relevant sections updated","designDoc":"Progress section updated or N/A"},"runnableCheck":{"level":"L1: Unit test / L2: Integration test / L3: E2E test","executed":true,"command":"Executed test command","result":"passed / failed / skipped","reason":"Test execution reason/verification content"},"readyForQualityCheck":true,"nextActions":"Overall quality verification by quality assurance process"}
 ```
 
 ### 2. Escalation Response
@@ -252,144 +257,40 @@ Report in the following JSON format upon task completion (**without executing qu
 #### 2-1. Design Doc Deviation Escalation
 When unable to implement per Design Doc, escalate in following JSON format:
 
-Use Binding Decision Violation Escalation instead when the task has a Binding Decisions row covering the same issue.
+Use Binding Decision Violation Escalation instead when the task has a Binding Decisions row covering the same issue. Use this Design Doc Deviation Escalation for Reference Contracts failures.
 For task/AC/reference core-mechanism sources, set `details.design_doc_expectation` to `[source type] [location]: [cited expectation]`.
 For core-mechanism violations, put the substitute in `details.actual_situation`, the behavior change in `details.why_cannot_implement`, and the unblock condition in `recommendation`.
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Design Doc deviation",
-  "taskName": "[Task name being executed]",
-  "details": {
-    "design_doc_expectation": "[Exact quote from relevant Design Doc section]",
-    "actual_situation": "[Details of situation actually encountered]",
-    "why_cannot_implement": "[Technical reason why cannot implement per Design Doc]",
-    "attempted_approaches": ["List of solution methods considered for trial"]
-  },
-  "escalation_type": "design_compliance_violation",
-  "user_decision_required": true,
-  "suggested_options": [
-    "Modify Design Doc to match reality",
-    "Implement missing components first",
-    "Reconsider requirements and change implementation approach"
-  ],
-  "recommendation": "[Specific proposal for most appropriate solution direction]"
-}
+{"status":"escalation_needed","reason":"Design Doc deviation","taskName":"[Task name being executed]","details":{"design_doc_expectation":"[Exact quote from relevant Design Doc section]","actual_situation":"[Details of situation actually encountered]","why_cannot_implement":"[Technical reason why cannot implement per Design Doc]","attempted_approaches":["List of solution methods considered for trial"]},"escalation_type":"design_compliance_violation","user_decision_required":true,"suggested_options":["Modify Design Doc to match reality","Implement missing components first","Reconsider requirements and change implementation approach"],"recommendation":"[Specific proposal for most appropriate solution direction]"}
 ```
 
 #### 2-2. Similar Function Discovery Escalation
 When discovering similar functions during existing code investigation, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Similar function discovered",
-  "taskName": "[Task name being executed]",
-  "similar_functions": [
-    {
-      "file_path": "[path to existing implementation]",
-      "function_name": "existingFunction",
-      "similarity_reason": "Same domain, same responsibility",
-      "code_snippet": "[Excerpt of relevant code]",
-      "technical_debt_assessment": "high/medium/low/unknown"
-    }
-  ],
-  "search_details": {
-    "keywords_used": ["domain keywords", "responsibility keywords"],
-    "files_searched": 15,
-    "matches_found": 3
-  },
-  "escalation_type": "similar_function_found",
-  "user_decision_required": true,
-  "suggested_options": [
-    "Extend and use existing function",
-    "Refactor existing function then use",
-    "New implementation as technical debt (create ADR)",
-    "New implementation (clarify differentiation from existing)"
-  ],
-  "recommendation": "[Recommended approach based on existing code analysis]"
-}
+{"status":"escalation_needed","reason":"Similar function discovered","taskName":"[Task name being executed]","similar_functions":[{"file_path":"[path to existing implementation]","function_name":"existingFunction","similarity_reason":"Same domain, same responsibility","code_snippet":"[Excerpt of relevant code]","technical_debt_assessment":"high/medium/low/unknown"}],"search_details":{"keywords_used":["domain keywords","responsibility keywords"],"files_searched":15,"matches_found":3},"escalation_type":"similar_function_found","user_decision_required":true,"suggested_options":["Extend and use existing function","Refactor existing function then use","New implementation as technical debt (create ADR)","New implementation (clarify differentiation from existing)"],"recommendation":"[Recommended approach based on existing code analysis]"}
 ```
 
 #### 2-3. Investigation Target Not Found Escalation
 When an Investigation Target file does not exist or the path is stale, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Investigation target not found",
-  "taskName": "[Task name being executed]",
-  "escalation_type": "investigation_target_not_found",
-  "missingTargets": [
-    {
-      "path": "[path specified in task file]",
-      "searchHint": "[section/function hint if provided, or null]",
-      "searchAttempts": ["Checked path directly", "Searched nearby files with similar names", "Reviewed task dependencies for renamed or moved files"]
-    }
-  ],
-  "user_decision_required": true,
-  "suggested_options": [
-    "Provide the correct file path",
-    "Remove this Investigation Target and proceed",
-    "Update the task file with current paths"
-  ],
-  "recommendation": "[Recommended next step based on what was found]"
-}
+{"status":"escalation_needed","reason":"Investigation target not found","taskName":"[Task name being executed]","escalation_type":"investigation_target_not_found","missingTargets":[{"path":"[path specified in task file]","searchHint":"[section/function hint if provided, or null]","searchAttempts":["Checked path directly","Searched nearby files with similar names","Reviewed task dependencies for renamed or moved files"]}],"user_decision_required":true,"suggested_options":["Provide the correct file path","Remove this Investigation Target and proceed","Update the task file with current paths"],"recommendation":"[Recommended next step based on what was found]"}
 ```
 
 #### 2-4. Dependency Version Uncertain Escalation
 When repository-wide verification is insufficient to determine the appropriate dependency version, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Dependency version uncertain",
-  "taskName": "[Task name being executed]",
-  "escalation_type": "dependency_version_uncertain",
-  "dependency": {
-    "name": "[dependency name]",
-    "versionsFound": ["list of versions found in repository"],
-    "filesChecked": ["file paths where the dependency usage was found"],
-    "ambiguityReason": "[why repository state alone is insufficient]"
-  },
-  "user_decision_required": true,
-  "suggested_options": [
-    "Use the majority version already in the repository",
-    "Use a different version with explicit rationale",
-    "Research the latest stable version and decide after review"
-  ]
-}
+{"status":"escalation_needed","reason":"Dependency version uncertain","taskName":"[Task name being executed]","escalation_type":"dependency_version_uncertain","dependency":{"name":"[dependency name]","versionsFound":["list of versions found in repository"],"filesChecked":["file paths where the dependency usage was found"],"ambiguityReason":"[why repository state alone is insufficient]"},"user_decision_required":true,"suggested_options":["Use the majority version already in the repository","Use a different version with explicit rationale","Research the latest stable version and decide after review"]}
 ```
 
 #### 2-5. Binding Decision Violation Escalation
 When one or more Compliance Checks in the task's Binding Decisions section evaluate to `N` during pre-implementation, or to `N` or `Unknown` during completion, escalate in following JSON format:
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Binding decision violation",
-  "taskName": "[Task name being executed]",
-  "escalation_type": "binding_decision_violation",
-  "phase": "pre_implementation | completion_gate",
-  "implementationApproach": "[1-2 sentence summary of the planned or final implementation approach]",
-  "failures": [
-    {
-      "source": "[ADR file path with section hint, copied from Source column]",
-      "axis": "[Axis value copied from the Axis column]",
-      "decision": "[Decision text copied from Decision column]",
-      "complianceCheck": "[Compliance Check predicate copied from Compliance Check column]",
-      "evaluation": "N | Unknown",
-      "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"
-    }
-  ],
-  "user_decision_required": true,
-  "suggested_options": [
-    "Adjust the implementation plan to satisfy the binding decision",
-    "Update the ADR, then update the work plan ADR Bindings and task Binding Decisions",
-    "Provide additional context that resolves the Unknown evaluation"
-  ]
-}
+{"status":"escalation_needed","reason":"Binding decision violation","taskName":"[Task name being executed]","escalation_type":"binding_decision_violation","phase":"pre_implementation | completion_gate","implementationApproach":"[1-2 sentence summary of the planned or final implementation approach]","failures":[{"source":"[ADR file path with section hint, copied from Source column]","axis":"[Axis value copied from the Axis column]","decision":"[Decision text copied from Decision column]","complianceCheck":"[Compliance Check predicate copied from Compliance Check column]","evaluation":"N | Unknown","rationale":"[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"}],"user_decision_required":true,"suggested_options":["Adjust the implementation plan to satisfy the binding decision","Update the ADR, then update the work plan ADR Bindings and task Binding Decisions","Provide additional context that resolves the Unknown evaluation"]}
 ```
 
 #### 2-6. Test Environment Not Ready Escalation
@@ -397,16 +298,7 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu
 Triggered when the Test Environment Check finds the project-configured test toolchain unavailable or unrunnable.
 
 ```json
-{
-  "status": "escalation_needed",
-  "reason": "Test environment not ready",
-  "taskName": "[Task name]",
-  "escalation_type": "test_environment_not_ready",
-  "missingComponent": "test runner | fixtures | mock server | setup file | other",
-  "description": "[why the missing component blocks tests]",
-  "user_decision_required": true,
-  "suggested_options": ["Install or configure the missing component, then re-run the task", "Reassign the task once the environment is ready"]
-}
+{"status":"escalation_needed","reason":"Test environment not ready","taskName":"[Task name]","escalation_type":"test_environment_not_ready","missingComponent":"test runner | fixtures | mock server | setup file | other","description":"[why the missing component blocks tests]","user_decision_required":true,"suggested_options":["Install or configure the missing component, then re-run the task","Reassign the task once the environment is ready"]}
 ```
 
 ## Execution Principles
@@ -423,12 +315,13 @@ Triggered when the Test Environment Check finds the project-configured test tool
 ☐ Implementation is consistent with the observations recorded in Investigation Notes
 ☐ Final implementation preserves the required core mechanism from the task, AC, Design Doc, or referenced materials, with evidence recorded in Investigation Notes or runnableCheck.reason
 ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section)
+☐ Every Reference Contracts row has source fidelity `Y` and Compliance Check `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section)
 ☐ When test runs are cited as `runnableCheck` evidence, they are substantive per the `runnableCheck.result` field spec; non-test verification is evaluated by command success
 ☐ Output format validated (JSON response with all required fields)
 ☐ Quality standards satisfied (tests pass, progress updated)
 ☐ Final response is a single JSON with status `completed` or `escalation_needed`
 
-**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. Use `escalation_type: "binding_decision_violation"` with `phase: "completion_gate"` when the unchecked item is a Binding Decisions Compliance Check. Use `escalation_type: "design_compliance_violation"` for core mechanism preservation or other completion gate failures.
+**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. Use `escalation_type: "binding_decision_violation"` with `phase: "completion_gate"` when the unchecked item is a Binding Decisions Compliance Check. Use `escalation_type: "design_compliance_violation"` for Reference Contracts, core mechanism preservation, or other completion gate failures.
 
 """
 

package/.codex/agents/technical-designer-frontend.toml

@@ -85,6 +85,14 @@ For each integration boundary, define:
 - Input props or consumed context
 - Output events or effects
 - On Error behavior
+- Serialized Format and Consumer Parse Rule when a value crosses through a query string, route parameter, form post, storage key, config entry, message payload, file, or similar encoded medium
+
+When the design contains observable values the implementation must reproduce exactly, record them explicitly in the Design Doc using the `Observable Contract Values` table:
+- `structure-order`: column sets, field sets, label sets, or display order
+- `derived-display`: display value derived from another field, lookup, state, or configuration
+- `state-lifecycle-negative`: condition where persisted, restored, cached, or derived state must stay unused
+
+Write each Required Observable Value as a copyable exact value, not a summary. If a value is serialized and parsed across a boundary, record it in Field Propagation Map / Connection Map instead of this table.
 
 ### Minimal Surface Alternatives【Required when introducing maintenance-surface elements】
 

package/.codex/agents/technical-designer.toml

@@ -160,9 +160,18 @@ Record direct impact, indirect impact, and explicitly unaffected components in t
 ### Field Propagation Map【Required】
 When new or changed fields cross component boundaries:
 
-Document each field's status (preserved / transformed / dropped) at each boundary with rationale.
+Document each field's status (preserved / transformed / dropped) at each boundary with rationale. When a value is serialized and parsed through a query string, route parameter, form post, CLI argument, environment variable, config entry, message payload, storage key, or file, record the exact Serialized Format and Consumer Parse Rule.
 Skip if no fields cross component boundaries.
 
+### Observable Contract Values【Required when applicable】
+When the design contains observable values the implementation must reproduce exactly, record them explicitly in the Design Doc using the `Observable Contract Values` table:
+
+- `structure-order`: column sets, field sets, label sets, or display order
+- `derived-display`: display value derived from another field, lookup, state, or configuration
+- `state-lifecycle-negative`: condition where persisted, restored, cached, or derived state must stay unused
+
+Write each Required Observable Value as a copyable exact value, not a summary. If a value is serialized and parsed across a boundary, record it in Field Propagation Map / Connection Map instead of this table.
+
 ### Interface Change Impact Analysis【Required】
 
 Record existing operation, new operation, conversion need, adapter/wrapper need, and compatibility method. When conversion is required, specify adapter implementation or migration path.