codex-workflows 0.6.2 → 0.6.3

package/.agents/skills/documentation-criteria/SKILL.md

@@ -81,7 +81,7 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 
 ### Work Plan
 **Purpose**: Implementation task management and progress tracking
-**Scope**: Task breakdown, dependencies, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, Design-to-Plan Traceability mapping for implementation-relevant technical requirements, final Quality Assurance phase, and progress tracking only. Technical rationale belongs in ADR and design details belong in Design Doc.
+**Scope**: Task breakdown, dependencies, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, Design-to-Plan Traceability mapping for implementation-relevant technical requirements, ADR Bindings for implementation-binding ADR decisions, final Quality Assurance phase, and progress tracking only. Technical rationale belongs in ADR and design details belong in Design Doc.
 
 **Phase Division Criteria**:
 

package/.agents/skills/documentation-criteria/references/design-template.md

@@ -30,8 +30,9 @@ unknowns:
 
 ### Prerequisite ADRs
 
-- [ADR File Name]: [Related decision items]
+- docs/adr/ADR-XXXX-title.md: [Related decision items]
 - Reference common technical ADRs when applicable
+- ADR placeholders use the repository ADR filename convention: replace `XXXX` with the four-digit ADR number and `title` with the file slug.
 
 ### External Resources Used
 

package/.agents/skills/documentation-criteria/references/plan-template.md

@@ -11,9 +11,11 @@ Implementation Readiness: pending
 - Design Doc(s):
   - [docs/design/XXX.md]
   - [docs/design/YYY.md] (if multiple, e.g. backend + frontend)
-- ADR: [docs/adr/ADR-XXXX.md] (if any)
+- ADR: docs/adr/ADR-XXXX-title.md (if any)
 - PRD: [docs/prd/XXX.md] (if any)
 
+ADR placeholders use the repository ADR filename convention: replace `XXXX` with the four-digit ADR number and `title` with the file slug.
+
 ## Verification Strategies (from Design Docs)
 
 Repeat this block for each Design Doc when multiple Design Docs exist. Preserve each strategy's identity and source document path. Merge strategies only when the Design Docs explicitly define a shared one.
@@ -77,6 +79,23 @@ Include this section when a UI Spec is among the inputs. Map each UI component s
 
 **Reference key rule**: The component identifier is the UI Spec section heading verbatim. Component headings must be unique within a UI Spec.
 
+## ADR Bindings
+
+Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Map each implementation-binding ADR decision to the task(s) it constrains. Omit this section when no ADR applies.
+
+A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behavior remain in the Design Doc; this table covers structural implementation constraints from ADRs.
+
+| ADR | Source Section | Axis (exactly one value) | Binding Decision | Covered By Task(s) | Gap Status | Notes |
+|-----|----------------|--------------------------|------------------|--------------------|------------|-------|
+| docs/adr/ADR-XXXX-title.md | Decision | dependency_direction | [One implementation-binding decision sentence, copied or condensed from the named section] | P1-T1, P2-T1 | covered | |
+| docs/adr/ADR-YYYY-title.md | Implementation Guidance | persistence | [Binding decision with no covering task yet] | - | gap | [Justification and user-confirmation note] |
+
+**Axis values**: `placement` (where code belongs), `dependency_direction` (allowed import or call direction), `contract_schema` (interface, payload, or schema shape), `data_flow` (how data moves across components), `persistence` (where and how state is stored)
+
+One row represents one independently checkable binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows.
+
+**Gap Status values**: `covered` (mapped to one or more tasks), `gap` (no task exists yet; set Covered By Task(s) to `-`, include justification in Notes, and require user confirmation before plan approval)
+
 ## Connection Map
 
 Include this section when implementation crosses runtime, process, deployment, or service boundaries. Omit it when the change stays inside one runtime or only uses in-process package imports.

package/.agents/skills/documentation-criteria/references/task-template.md

@@ -17,9 +17,19 @@ Metadata:
 Files to read before starting implementation. Use concrete file paths, optionally with a section/function hint:
 - [e.g., src/orders/checkout.ts (processOrder function)]
 
+## Binding Decisions
+(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.)
+
+Each row is an ADR decision the implementation in this task must comply with.
+
+| Source | Axis | Decision | Compliance Check |
+|--------|------|----------|------------------|
+| docs/adr/ADR-XXXX-title.md (§ <Source Section>) | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned and final implementation satisfy the decision] |
+
 ## Investigation Notes
 Brief observations recorded after reading Investigation Targets:
 - [path] - [interfaces, control/data flow, state transitions, side effects relevant to this task]
+- When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.
 
 ## Implementation Steps (TDD: Red-Green-Refactor)
 ### 1. Red Phase
@@ -52,6 +62,7 @@ Brief observations recorded after reading Investigation Targets:
 - [ ] All added tests pass
 - [ ] Operation verified per Operation Verification Methods above
 - [ ] Deliverables created (for research/design tasks)
+- [ ] When Binding Decisions exist, every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes
 
 ## Notes
 - Impact scope: [Areas where changes may propagate]

package/.agents/skills/recipe-prepare-implementation/SKILL.md

@@ -31,7 +31,7 @@ Each criterion produces `pass`, `fail`, or `not_applicable`, with file:line evid
 
 | ID | Criterion | Pass Evidence |
 |----|-----------|---------------|
-| R1 | Verification Strategy references resolve | Every command, file path, function, endpoint, fixture, seed, and test reference in the work plan's Verification Strategies either exists now or is the deliverable of a task in the plan |
+| R1 | Verification Strategy and ADR Binding references resolve | Every command, file path, function, endpoint, fixture, seed, and test reference in the work plan's Verification Strategies either exists now or is the deliverable of a task in the plan; every ADR Bindings source path resolves; every ADR Bindings `covered` row references existing task IDs |
 | R2 | E2E prerequisites are addressed | For each fixture-e2e or service-integration-e2e skeleton, every noted precondition is present in the codebase or covered by a Phase 0 task |
 | R3 | Phase 1 observability exists | The first implementation phase includes at least one operation verification method executable at task completion using existing files, prior Phase 0 deliverables, or the task's own output |
 | R4 | UI rendering surface exists | When the plan implements UI components, a fixture entry, dev route, Storybook story, preview harness, or equivalent render surface exists or is covered by a Phase 0 task |
@@ -47,11 +47,12 @@ Read the work plan passed in `$ARGUMENTS`; if absent, select the most recent non
 - Verification Strategies
 - Quality Assurance Mechanisms
 - Design-to-Plan Traceability
+- ADR Bindings
 - UI Spec Component -> Task Mapping
 - Connection Map
 - test skeleton references and E2E absence reasons
 - phase structure and task IDs
-- referenced Design Docs and UI Specs
+- referenced Design Docs, ADRs, and UI Specs
 
 If no work plan exists, stop and report the missing prerequisite.
 

package/.agents/skills/subagents-orchestration-guide/SKILL.md

@@ -185,7 +185,7 @@ Subagents respond in JSON format. The final response from each JSON-returning su
 | `requirement-analyzer` | `scale`, `confidence`, `affectedLayers`, `adrRequired`, `scopeDependencies`, `questions` |
 | `codebase-analyzer` | `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` |
 | `ui-analyzer` | `externalResources`, `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, `focusAreas`, `candidateWriteSet`, `limitations` |
-| `task-executor*` | `status`, `escalation_type`, `filesModified`, `requiresTestReview` |
+| `task-executor*` | `status`, `escalation_type` (`design_compliance_violation`, `similar_function_found`, `similar_component_found`, `investigation_target_not_found`, `out_of_scope_file`, `dependency_version_uncertain`, `binding_decision_violation`), `filesModified`, `requiresTestReview` |
 | `quality-fixer*` | `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` |
 | `document-reviewer` | `verdict.decision`, `verdict.conditions` |
 | `code-verifier` | `summary.status`, `discrepancies`, `reverseCoverage` |
@@ -209,9 +209,9 @@ Work plans use the header line `Implementation Readiness: <status>`.
 
 Use this procedure after work-plan approval and before autonomous task execution when the flow needs to verify implementation readiness.
 
-1. Load the approved work plan exact path and extract Verification Strategies, Quality Assurance Mechanisms, Design-to-Plan Traceability, UI Spec Component -> Task Mapping, Connection Map, test skeleton references, E2E absence reasons, phase structure, referenced Design Docs, and UI Specs.
+1. Load the approved work plan exact path and extract Verification Strategies, Quality Assurance Mechanisms, Design-to-Plan Traceability, ADR Bindings, UI Spec Component -> Task Mapping, Connection Map, test skeleton references, E2E absence reasons, phase structure, referenced Design Docs, ADRs, and UI Specs.
 2. Evaluate these criteria with evidence:
-   - R1 Verification Strategy references resolve
+   - R1 Verification Strategy and ADR Binding references resolve
    - R2 E2E prerequisites are addressed
    - R3 Phase 1 observability exists
    - R4 UI rendering surface exists when UI work is present

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

@@ -66,6 +66,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Create individual task files in `docs/plans/tasks/`
    - Document concrete executable procedures
    - Include task-level Quality Assurance Mechanisms when the work plan defines them
+   - Include task-level Binding Decisions when ADR Bindings cover the task
    - **Always include operation verification methods**
    - Define clear completion criteria (within executor's scope of responsibility)
 
@@ -92,6 +93,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Extract task list
    - Identify dependencies
    - Read Design-to-Plan Traceability rows and verify every `covered` item has a corresponding generated task or phase completion task
+   - Read ADR Bindings rows and verify every `covered` item has a corresponding generated task
    - **Overall Optimization Considerations**
      - Identify common processing (prevent redundant implementation)
      - Pre-map impact scope
@@ -136,6 +138,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    | fixture-e2e environment/setup work | Existing fixture data, API mock layer, browser harness configuration |
    | service-integration-e2e environment/setup work | Current environment config, startup scripts, seed scripts, auth flow references, external service stubs |
    | Cross-boundary implementation | Connection Map rows touching the task target files, caller/producer module, callee/consumer module, expected signal, contract definition |
+   | Task constrained by an ADR | ADR file with section hint matching the ADR Bindings row's Source Section value |
    | Bug fix/refactor | Affected code paths, failing tests, reproduction-related files |
    | Behavior replacement/rewrite | Existing implementation being replaced, observable outputs, Verification Strategy section in the Design Doc |
 
@@ -146,6 +149,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - When test skeletons exist, include them explicitly
    - When the work plan contains a UI Spec Component -> Task Mapping table, propagate matching component sections to every task listed in the row
    - When the work plan contains a Connection Map, propagate boundary rows touching the task's target files to every task on either side of the boundary
+   - When the work plan contains an ADR Bindings table, propagate matching binding rows to every covered task
    - When a task matches multiple natures, include Investigation Targets from all matching rows and deduplicate overlaps
 
 7. **Implementation Pattern Consistency**
@@ -191,6 +195,26 @@ When the work plan includes a `Design-to-Plan Traceability` section:
 5. **Verification integrity**: For `verification` rows, ensure the corresponding task file includes the required comparison or verification method in Operation Verification Methods.
 6. **Prerequisite integrity**: For `prerequisite` rows, place setup, migration, seed, auth, or environment work before dependent implementation tasks.
 
+## ADR Binding Propagation
+
+When the work plan includes an `ADR Bindings` section:
+
+1. **Coverage preservation**: For each row marked `covered`, locate every task ID listed in `Covered By Task(s)`.
+2. **Gap handling**: Preserve each `gap` row as a planning issue and surface it to the caller when task generation would otherwise assume the ADR decision is implemented.
+3. **Investigation Targets**: Add the ADR file path with the row's Source Section as a section hint to each matched task, formatted as `docs/adr/ADR-XXXX-title.md (§ [Source Section])`.
+4. **Binding Decisions table**: Add one row to each matched task's `Binding Decisions` section:
+   - `Source`: ADR path with section hint
+   - `Axis`: value copied verbatim from the plan row
+   - `Decision`: binding decision copied from the plan row
+   - `Compliance Check`: a Y/N-answerable positive predicate that evaluates whether the planned and final implementation satisfy the decision
+5. **Predicate shape**: Write each Compliance Check as a concrete positive statement. Examples by Axis:
+   - `placement`: `Auth entrypoint is in src/middleware/**`
+   - `dependency_direction`: `Domain code imports only from src/domain/** and src/shared/**`
+   - `contract_schema`: `API responses match the ResponseEnvelope<T> schema`
+   - `data_flow`: `Session tokens are written through the Redis client`
+   - `persistence`: `User records are persisted through the UsersRepository interface`
+6. **Validation**: Treat missing Axis, unknown Axis value, or non-checkable Compliance Check as an incomplete task file. Non-checkable means the implementation cannot be observed and answered as `Y` or `N`, or the predicate is written as a negative or compound condition.
+
 ## UI Spec Propagation
 
 When the work plan includes a `UI Spec Component -> Task Mapping` section:
@@ -310,6 +334,10 @@ Please execute decomposed tasks according to the order.
 - [ ] Appropriate granularity (1-5 files/task)
 - [ ] Investigation Targets specified for every task
 - [ ] Quality Assurance Mechanisms propagated to relevant tasks when present in the plan header
+- [ ] ADR Bindings rows propagated to relevant tasks when present in the work plan
+  - [ ] ADR source includes section hint
+  - [ ] Axis copied verbatim from the work plan row
+  - [ ] Compliance Check is a Y/N-answerable positive predicate
 - [ ] Operation Verification Methods specified for every task
 - [ ] Clear completion criteria setting
 - [ ] Overall design document creation

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

@@ -176,6 +176,22 @@ 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
 
+#### 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.
+
+1. Confirm each Source in the Binding Decisions table has been read. Sources should also appear in Investigation Targets.
+2. Use the Investigation Notes format below while recording the planned approach and evaluation results.
+   - `### Binding Decisions Evaluation`
+   - `[axis] planned: [one sentence planned approach]`
+   - `[source] [Compliance Check] -> Y|N|Unknown — [one-line rationale]`
+3. Record the planned implementation approach in Investigation Notes, one sentence per distinct `Axis` value present in the Binding Decisions table. Group rows that share an Axis value when one sentence covers the group.
+4. Evaluate each row's Compliance Check against the planned approach. Record the result as `Y`, `N`, or `Unknown` with a one-line rationale.
+5. Branch per row:
+   - `Y`: proceed
+   - `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 Representativeness (Applied During Implementation)
 
 When adopting a pattern, UI composition, or dependency from existing code, apply repository-wide representativeness checks at the point of adoption:
@@ -218,7 +234,7 @@ For research tasks, includes creating deliverable files specified in metadata "P
 ### 5. Return JSON Result
 Return one of the following as the final response (see Structured Response Specification for schemas):
 - `status: "completed"` — task fully implemented
-- `status: "escalation_needed"` — design deviation or similar component discovered
+- `status: "escalation_needed"` — a structured escalation case from the schemas below applies
 
 ## Structured Response Specification
 
@@ -260,6 +276,8 @@ 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.
+
 ```json
 {
   "status": "escalation_needed",
@@ -366,6 +384,36 @@ When repository-wide verification is insufficient to determine the appropriate d
 }
 ```
 
+#### 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"
+  ]
+}
+```
+
 ## Scope Boundary (delegate to orchestrator)
 - Overall quality checks → handled by quality-fixer-frontend
 - Commit creation → handled by orchestrator after quality checks
@@ -378,11 +426,12 @@ When repository-wide verification is insufficient to determine the appropriate d
 ☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section
 ☐ Investigation Notes were updated before implementation when Investigation Targets exist
 ☐ Implementation is consistent with the observations recorded in Investigation Notes
+☐ 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)
 ☐ 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.
+**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 other completion gate failures.
 
 """
 

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

@@ -176,6 +176,22 @@ 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
 
+#### 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.
+
+1. Confirm each Source in the Binding Decisions table has been read. Sources should also appear in Investigation Targets.
+2. Use the Investigation Notes format below while recording the planned approach and evaluation results.
+   - `### Binding Decisions Evaluation`
+   - `[axis] planned: [one sentence planned approach]`
+   - `[source] [Compliance Check] -> Y|N|Unknown — [one-line rationale]`
+3. Record the planned implementation approach in Investigation Notes, one sentence per distinct `Axis` value present in the Binding Decisions table. Group rows that share an Axis value when one sentence covers the group.
+4. Evaluate each row's Compliance Check against the planned approach. Record the result as `Y`, `N`, or `Unknown` with a one-line rationale.
+5. Branch per row:
+   - `Y`: proceed
+   - `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 Representativeness (Applied During Implementation)
 
 When adopting a pattern, API usage, or dependency from existing code, apply repository-wide representativeness checks at the point of adoption:
@@ -221,7 +237,7 @@ For research tasks, includes creating deliverable files specified in metadata "P
 ### 5. Return JSON Result
 Return one of the following as the final response (see Structured Response Specification for schemas):
 - `status: "completed"` — task fully implemented
-- `status: "escalation_needed"` — design deviation or similar function discovered
+- `status: "escalation_needed"` — a structured escalation case from the schemas below applies
 
 ## Structured Response Specification
 
@@ -263,6 +279,8 @@ 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.
+
 ```json
 {
   "status": "escalation_needed",
@@ -369,6 +387,36 @@ When repository-wide verification is insufficient to determine the appropriate d
 }
 ```
 
+#### 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"
+  ]
+}
+```
+
 ## Execution Principles
 - Follow RED-GREEN-REFACTOR (see the principles in testing skill)
 - Update progress checkboxes per step
@@ -381,11 +429,12 @@ When repository-wide verification is insufficient to determine the appropriate d
 ☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section
 ☐ Investigation Notes were updated before implementation when Investigation Targets exist
 ☐ Implementation is consistent with the observations recorded in Investigation Notes
+☐ 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)
 ☐ 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.
+**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 other completion gate failures.
 
 """
 

package/.codex/agents/work-planner.toml

@@ -44,7 +44,8 @@ Skill Status:
 6. Concretize risks and countermeasures
 7. Create explicit Design-to-Plan Traceability so Design Doc technical requirements are covered without silent omission
 8. Propagate UI Spec component and runtime boundary context into the plan so task decomposition can pass it to executors
-9. Document in progress-trackable format
+9. Map implementation-binding ADR decisions to constrained tasks
+10. Document in progress-trackable format
 
 ## Input Parameters
 
@@ -68,10 +69,16 @@ Read the Design Doc(s), UI Spec, PRD, and ADR (if provided). Extract:
 - Verification Strategy from each Design Doc: correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
 - Quality Assurance Mechanisms from each Design Doc: all items marked `adopted`, including mechanism name, enforced quality aspect, configuration path, and covered files or project-wide scope
 - Implementation-relevant technical requirements from each Design Doc section using the category values defined in the plan template's `Design-to-Plan Traceability` section
+- Prerequisite ADR references from each Design Doc and implementation-binding decisions from each resolved ADR
 
 Focus on implementation-relevant items only: items that directly inform task creation, dependency ordering, verification design, or protected no-change boundaries.
 Extract `scope-boundary` rows from explicit non-target statements such as `No Ripple Effect`, compatibility constraints, or protected boundaries that must remain unchanged.
 
+For ADR references, resolve paths using these rules:
+- Explicit `docs/adr/ADR-XXXX-title.md` path: read that file directly
+- Short `docs/adr/ADR-XXXX.md` or `ADR-XXXX` reference: match `docs/adr/ADR-XXXX-*.md`
+- Zero matches or two or more matches: flag a planning gap requiring user confirmation before plan approval
+
 ### 2. Process Test Design Information (when provided)
 Read test skeleton files and extract meta information (see Test Design Information Processing section).
 
@@ -141,6 +148,29 @@ Map only boundaries satisfying all three qualifications above: separate runtime,
 
 For each boundary, record the caller/producer, callee/consumer, expected signal, and covering tasks in the `Connection Map` table.
 
+### 5c. Map ADR Decisions to Tasks
+
+When ADRs are provided as input or listed in a Design Doc's "Prerequisite ADRs" section, create an `ADR Bindings` table before finalizing tasks.
+
+For each resolved ADR:
+1. Extract decisions from sections such as `Decision`, `Implementation Guidance`, `Consequences`, or clearly labeled decision bullets.
+2. Select only implementation-binding decisions: constraints on code placement, dependency direction, contract/schema shape, data flow, or persistence.
+3. Classify each selected decision with exactly one Axis value:
+   - `placement`: constrains where code, modules, components, or responsibilities belong
+   - `dependency_direction`: constrains allowed import, call, ownership, or layering direction
+   - `contract_schema`: constrains interface, payload, schema, props, DTO, event, or persisted record shape
+   - `data_flow`: constrains how data moves, transforms, is passed, emitted, or observed
+   - `persistence`: constrains storage location, repository boundary, migration, cache, or durable state behavior
+   - When multiple Axis values apply, prefer the ADR's explicit subject. If the subject remains ambiguous, use this priority order: `persistence` > `contract_schema` > `dependency_direction` > `data_flow` > `placement`.
+4. Map each binding decision to the task IDs that implement or verify the constrained area.
+5. Record one row per binding decision in the plan template's `ADR Bindings` table.
+
+Mapping rules:
+- A binding decision can map to multiple tasks when the constrained implementation spans boundaries.
+- A task can be covered by multiple binding decisions.
+- Acceptance criteria and required user-visible behaviors belong in `Design-to-Plan Traceability`; `ADR Bindings` covers structural implementation constraints.
+- If an ADR decision constrains the design but no task covers it, add a justified gap and flag it for user confirmation before plan approval.
+
 ### 6. Define Tasks with Completion Criteria
 For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete).
 
@@ -333,6 +363,10 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
   - [ ] Scope-boundary items mapped explicitly when the Design Doc defines protected no-change areas
   - [ ] Covered By Task(s) uses only normalized task IDs
   - [ ] No unjustified `gap` entries remain
+- [ ] ADR Bindings table completed when ADRs are provided or listed in Design Doc prerequisites
+  - [ ] ADR references resolved with exact path or single `docs/adr/ADR-XXXX-*.md` match
+  - [ ] Each binding row has one valid Axis value
+  - [ ] Each binding row maps to covering task(s) or a justified gap
 - [ ] Phase structure matches the implementation approach
 - [ ] Early verification point placed in the earliest applicable phase
 - [ ] Normalized verification timing mapped consistently to phases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",