codex-workflows 0.4.2 → 0.4.4

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

@@ -241,6 +241,15 @@ Self-evident: internal-only refactoring with identical observable inputs and out
 - **Success criteria**: [Observable outcome that proves correctness]
 - **Failure response**: [What to do if early verification fails]
 
+### Output Comparison (When Changing Existing Observable Behavior, an External Contract, or a Persisted Data Shape)
+
+- **Comparison input**: [Identical input used for both the current and new implementation]
+- **Expected output fields**: [Specific fields, columns, or output format to compare]
+- **Diff method**: [How the outputs are compared, such as field-by-field diff, file diff, or snapshot comparison]
+- **Transformation pipeline coverage**: [Map each listed step from codebase analysis `dataTransformationPipelines` to the comparison that verifies its output. If a step passes data through unchanged, mark it excluded with rationale]
+
+Mark as `N/A` with a brief rationale only when the change does not alter existing observable behavior, an external contract, or a persisted data shape.
+
 ### State Transitions and Invariants (When Applicable)
 
 ```yaml

package/.agents/skills/recipe-build/SKILL.md

@@ -98,14 +98,24 @@ ENFORCEMENT: Sub-agent prompts missing the constraint suffix MUST be re-issued w
 
 VERIFY approval status before proceeding. Once confirmed, INITIATE autonomous execution mode.
 
-## Security Review (After All Tasks Complete)
-
-After all task cycles finish, collect all `filesModified` from every task-executor response (deduplicated), then invoke security-reviewer before the completion report:
-1. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance."
-2. Check response:
-   - `approved` or `approved_with_notes` -> Proceed to completion report (include notes if present)
-   - `needs_revision` -> Spawn task-executor with `requiredFixes`, then quality-fixer, then re-invoke security-reviewer
-   - `blocked` -> Escalate to user
+## Post-Implementation Verification (After All Tasks Complete)
+
+After all task cycles finish, collect all `filesModified` from every task-executor response (deduplicated), then run both verification agents before the completion report:
+1. Spawn code-verifier agent: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [path]. `code_paths`: [collected filesModified list]."
+2. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance."
+3. Consolidate results:
+   - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent`
+   - code-verifier fails when `summary.status` is `needs_review` or `inconsistent`
+   - security-reviewer passes when `status` is `approved` or `approved_with_notes`
+   - security-reviewer fails when `status` is `needs_revision`
+   - security-reviewer `blocked` -> Escalate to user
+4. If either verifier fails:
+   - Create a single fix task covering verifier discrepancies and security requiredFixes
+   - Spawn task-executor with that consolidated task
+   - Spawn quality-fixer
+   - Re-run only the verifier(s) that failed
+   - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user
+5. If both verifiers pass -> Proceed to completion report
 
 **[STOP — BLOCKING]** Upon detecting ANY requirement changes, halt execution immediately.
 **CANNOT proceed until user explicitly confirms the change scope.**

package/.agents/skills/recipe-front-build/SKILL.md

@@ -106,14 +106,24 @@ ENFORCEMENT: Sub-agent prompts missing the constraint suffix MUST be re-issued w
 
 VERIFY approval status before proceeding. Once confirmed, INITIATE autonomous execution mode.
 
-## Security Review (After All Tasks Complete)
-
-After all task cycles finish, collect all `filesModified` from every task-executor-frontend response (deduplicated), then invoke security-reviewer before the completion report:
-1. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance."
-2. Check response:
-   - `approved` or `approved_with_notes` -> Proceed to completion report (include notes if present)
-   - `needs_revision` -> Spawn task-executor-frontend with `requiredFixes`, then quality-fixer-frontend, then re-invoke security-reviewer
-   - `blocked` -> Escalate to user
+## Post-Implementation Verification (After All Tasks Complete)
+
+After all task cycles finish, collect all `filesModified` from every task-executor-frontend response (deduplicated), then run both verification agents before the completion report:
+1. Spawn code-verifier agent: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [path]. `code_paths`: [collected filesModified list]."
+2. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance."
+3. Consolidate results:
+   - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent`
+   - code-verifier fails when `summary.status` is `needs_review` or `inconsistent`
+   - security-reviewer passes when `status` is `approved` or `approved_with_notes`
+   - security-reviewer fails when `status` is `needs_revision`
+   - security-reviewer `blocked` -> Escalate to user
+4. If either verifier fails:
+   - Create a single fix task covering verifier discrepancies and security requiredFixes
+   - Spawn task-executor-frontend with that consolidated task
+   - Spawn quality-fixer-frontend
+   - Re-run only the verifier(s) that failed
+   - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user
+5. If both verifiers pass -> Proceed to completion report
 
 **[STOP -- BLOCKING]** Upon detecting ANY requirement changes, halt execution immediately.
 **CANNOT proceed until user explicitly confirms the change scope.**

package/.agents/skills/recipe-front-review/SKILL.md

@@ -33,7 +33,7 @@ Identify the Design Doc in docs/design/ and check implementation files changed f
 **CANNOT proceed without both a Design Doc and implementation files.**
 
 ### 2. Execute code-reviewer
-Spawn code-reviewer agent: "Validate Design Doc compliance for [design-doc-path]. Implementation files: [git diff file list]. Review mode: full. Return structured JSON report with complianceRate, verdict, acceptanceCriteria, and qualityIssues."
+Spawn code-reviewer agent: "Validate Design Doc compliance for [design-doc-path]. Implementation files: [git diff file list]. Review mode: full. Return structured JSON report per your Output Format specification."
 
 **Store output as**: `$STEP_2_OUTPUT`
 
@@ -59,10 +59,16 @@ Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [file
 ```
 Code Compliance: [complianceRate from code-reviewer]
   Verdict: [verdict from code-reviewer]
+  Identifier Match Rate: [identifierMatchRate from code-reviewer]
   Acceptance Criteria:
-  - [fulfilled] [item]
+  - [fulfilled] [item] (confidence: [high/medium/low])
   - [partially_fulfilled] [item]: [gap] — [suggestion]
   - [unfulfilled] [item]: [gap] — [suggestion]
+  Identifier Mismatches (show only mismatches; write `None` if all identifiers match):
+  - None
+  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location] (confidence: [high/medium/low])
+  Quality Findings:
+  - [category] [location]: [description] — [rationale]
 
 Security Review: [status from security-reviewer]
   Findings by category:

package/.agents/skills/recipe-fullstack-build/SKILL.md

@@ -116,14 +116,24 @@ ENFORCEMENT: Sub-agent prompts missing the constraint suffix MUST be re-issued w
 
 VERIFY approval status before proceeding. Once confirmed, INITIATE autonomous execution mode.
 
-## Security Review (After All Tasks Complete)
-
-After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated), then invoke security-reviewer before the completion report:
-1. Spawn security-reviewer agent: "Design Doc: [path(s)]. Implementation files: [collected filesModified list]. Review security compliance."
-2. Check response:
-   - `approved` or `approved_with_notes` -> Proceed to completion report (include notes if present)
-   - `needs_revision` -> Spawn layer-appropriate task-executor with `requiredFixes`, then quality-fixer, then re-invoke security-reviewer
-   - `blocked` -> Escalate to user
+## Post-Implementation Verification (After All Tasks Complete)
+
+After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated), then run both verification agents before the completion report:
+1. Spawn code-verifier once per Design Doc: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [single design doc path]. `code_paths`: [collected filesModified list]."
+2. Spawn security-reviewer agent: "Design Doc: [path(s)]. Implementation files: [collected filesModified list]. Review security compliance."
+3. Consolidate results:
+   - each code-verifier run passes when `summary.status` is `consistent` or `mostly_consistent`
+   - a code-verifier run fails when `summary.status` is `needs_review` or `inconsistent`
+   - security-reviewer passes when `status` is `approved` or `approved_with_notes`
+   - security-reviewer fails when `status` is `needs_revision`
+   - security-reviewer `blocked` -> Escalate to user
+4. If any verifier fails:
+   - Create a single fix task covering verifier discrepancies and security requiredFixes
+   - Spawn the layer-appropriate task-executor
+   - Spawn the layer-appropriate quality-fixer
+   - Re-run only the verifier(s) that failed
+   - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user
+5. If all verifiers pass -> Proceed to completion report
 
 **[STOP -- BLOCKING]** Upon detecting ANY requirement changes, halt execution immediately.
 **CANNOT proceed until user explicitly confirms the change scope.**

package/.agents/skills/recipe-fullstack-implement/SKILL.md

@@ -127,14 +127,24 @@ ENFORCEMENT: Sub-agent prompts missing the constraint suffix MUST be re-issued w
 3. Quality-fixer MUST run after each executor (no skipping)
 4. Commit MUST execute when quality-fixer returns `status: "approved"` (do not defer to end)
 
-### Security Review (After All Tasks Complete)
-
-After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated), then invoke security-reviewer before the completion report:
-1. Spawn security-reviewer agent: "Design Doc: [path(s)]. Implementation files: [collected filesModified list]. Review security compliance."
-2. Check response:
-   - `approved` or `approved_with_notes` -> Proceed to completion report (include notes if present)
-   - `needs_revision` -> Spawn layer-appropriate task-executor with `requiredFixes`, then quality-fixer, then re-invoke security-reviewer
-   - `blocked` -> Escalate to user
+### Post-Implementation Verification (After All Tasks Complete)
+
+After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated), then run both verification agents before the completion report:
+1. Spawn code-verifier once per Design Doc: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [single design doc path]. `code_paths`: [collected filesModified list]."
+2. Spawn security-reviewer agent: "Design Doc: [path(s)]. Implementation files: [collected filesModified list]. Review security compliance."
+3. Consolidate results:
+   - each code-verifier run passes when `summary.status` is `consistent` or `mostly_consistent`
+   - a code-verifier run fails when `summary.status` is `needs_review` or `inconsistent`
+   - security-reviewer passes when `status` is `approved` or `approved_with_notes`
+   - security-reviewer fails when `status` is `needs_revision`
+   - security-reviewer `blocked` -> Escalate to user
+4. If any verifier fails:
+   - Create a single fix task covering verifier discrepancies and security requiredFixes
+   - Spawn the layer-appropriate task-executor
+   - Spawn the layer-appropriate quality-fixer
+   - Re-run only the verifier(s) that failed
+   - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user
+5. If all verifiers pass -> Proceed to completion report
 
 ### Test Information Communication
 After acceptance-test-generator execution, when calling work-planner, communicate:

package/.agents/skills/recipe-implement/SKILL.md

@@ -108,14 +108,24 @@ After user grants "batch approval for entire implementation phase", enter autono
 3. Spawn quality-fixer (or quality-fixer-frontend) agent: "Quality check and fixes"
 4. git commit -> Execute on `status: "approved"`
 
-### Security Review (After All Tasks Complete)
-
-After all task cycles finish, collect all `filesModified` from every executor response (task-executor and task-executor-frontend, deduplicated), then invoke security-reviewer before the completion report:
-1. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance."
-2. Check response:
-   - `approved` or `approved_with_notes` -> Proceed to completion report (include notes if present)
-   - `needs_revision` -> Spawn layer-appropriate executor (task-executor or task-executor-frontend per task filename routing) with `requiredFixes`, then layer-appropriate quality-fixer, then re-invoke security-reviewer
-   - `blocked` -> Escalate to user
+### Post-Implementation Verification (After All Tasks Complete)
+
+After all task cycles finish, collect all `filesModified` from every executor response (task-executor and task-executor-frontend, deduplicated), then run both verification agents before the completion report:
+1. Spawn code-verifier agent: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [path]. `code_paths`: [collected filesModified list]."
+2. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance."
+3. Consolidate results:
+   - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent`
+   - code-verifier fails when `summary.status` is `needs_review` or `inconsistent`
+   - security-reviewer passes when `status` is `approved` or `approved_with_notes`
+   - security-reviewer fails when `status` is `needs_revision`
+   - security-reviewer `blocked` -> Escalate to user
+4. If either verifier fails:
+   - Create a single fix task covering verifier discrepancies and security requiredFixes
+   - Spawn the layer-appropriate executor
+   - Spawn the layer-appropriate quality-fixer
+   - Re-run only the verifier(s) that failed
+   - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user
+5. If both verifiers pass -> Proceed to completion report
 
 ### Test Information Communication
 After acceptance-test-generator execution, when spawning work-planner, communicate:

package/.agents/skills/recipe-review/SKILL.md

@@ -35,7 +35,7 @@ Design Doc (uses most recent if omitted): $ARGUMENTS
 Identify Design Doc in docs/design/ and check implementation files via git diff.
 
 ### Step 2: Execute code-reviewer
-Spawn code-reviewer agent: "Validate Design Doc compliance for the implementation. Design Doc path: [path]. Implementation files: [git diff file list]. Review mode: full. Return structured JSON report with complianceRate, verdict, acceptanceCriteria, and qualityIssues."
+Spawn code-reviewer agent: "Validate Design Doc compliance for the implementation. Design Doc path: [path]. Implementation files: [git diff file list]. Review mode: full. Return structured JSON report per your Output Format specification."
 
 **Store output as**: `$STEP_2_OUTPUT`
 
@@ -61,10 +61,16 @@ Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [file
 ```
 Code Compliance: [complianceRate from code-reviewer]
   Verdict: [verdict from code-reviewer]
+  Identifier Match Rate: [identifierMatchRate from code-reviewer]
   Acceptance Criteria:
-  - [fulfilled] [item]
+  - [fulfilled] [item] (confidence: [high/medium/low])
   - [partially_fulfilled] [item]: [gap] — [suggestion]
   - [unfulfilled] [item]: [gap] — [suggestion]
+  Identifier Mismatches (show only mismatches; write `None` if all identifiers match):
+  - None
+  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location] (confidence: [high/medium/low])
+  Quality Findings:
+  - [category] [location]: [description] — [rationale]
 
 Security Review: [status from security-reviewer]
   Findings by category:

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

@@ -69,7 +69,7 @@ The following subagents are available:
 10. **technical-designer**: ADR/Design Doc creation
 11. **work-planner**: Work plan creation from Design Doc and test skeletons
 12. **document-reviewer**: Single document quality and rule compliance check
-13. **code-verifier**: Document-code consistency verification for review inputs
+13. **code-verifier**: Document-code consistency verification for review inputs and post-implementation verification
 14. **design-sync**: Design Doc consistency verification across multiple documents
 15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs
 
@@ -182,7 +182,7 @@ Subagents respond in JSON format. The final response from each JSON-returning su
 - **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/similar_component_found/investigation_target_not_found/out_of_scope_file/test_environment_not_ready), testsAdded, requiresTestReview
 - **quality-fixer**: status (approved/blocked). For blocked responses, discriminate by `reason`: specification conflicts use `blockingIssues[]`; execution prerequisites use `missingPrerequisites[]`, and each item provides its own `resolutionSteps`
 - **document-reviewer**: verdict.decision (approved/approved_with_conditions/needs_revision/rejected)
-- **code-verifier**: summary, discrepancies, reverseCoverage
+- **code-verifier**: summary.status, summary.consistencyScore, discrepancies, reverseCoverage
 - **design-sync**: sync_status (CONFLICTS_FOUND/NO_CONFLICTS) — text format with [SUMMARY] block
 - **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
 - **security-reviewer**: status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes
@@ -252,7 +252,7 @@ When receiving new features or change requests, start with requirement-analyzer.
 ### Design Flow Data Passing
 
 - Pass requirement-analyzer output and original requirements to codebase-analyzer
-- Pass codebase-analyzer JSON to technical-designer or technical-designer-frontend as `Codebase Analysis`
+- Pass codebase-analyzer JSON to technical-designer or technical-designer-frontend as `Codebase Analysis`, including `dataTransformationPipelines` when present
 - Pass Design Doc path to code-verifier
 - Pass code-verifier JSON to document-reviewer as `code_verification`
 
@@ -300,9 +300,9 @@ Batch approval -> Start autonomous execution mode
       -> Orchestrator: Execute git commit
       -> Check remaining tasks:
           - Yes -> next task
-          - No -> security-reviewer: Security review
-              - approved/approved_with_notes -> Completion report
-              - needs_revision -> layer-appropriate task-executor: Security fixes -> quality-fixer -> security-reviewer
+          - No -> code-verifier + security-reviewer: Post-implementation verification
+              - all pass -> Completion report
+              - any fail -> layer-appropriate task-executor: Verification fixes -> quality-fixer -> re-run failed verifiers
               - blocked -> Escalate to user
 ```
 
@@ -321,6 +321,16 @@ Use the task loop defined in the autonomous execution diagram above. The canonic
 3. quality-fixer quality gate
 4. git commit on approval
 
+### Post-Implementation Verification Pass/Fail Criteria
+
+| Verifier | Pass | Fail | Blocked |
+|----------|------|------|---------|
+| code-verifier | `summary.status` is `consistent` or `mostly_consistent` | `summary.status` is `needs_review` or `inconsistent` | — |
+| security-reviewer | `status` is `approved` or `approved_with_notes` | `status` is `needs_revision` | `status` is `blocked` |
+
+Re-run only verifiers that failed on the previous verification cycle.
+Maximum retry count is 1 verification fix cycle. If any failed verifier still fails after the re-run, escalate to the user.
+
 ## Main Orchestrator Roles
 
 1. **State Management**: Track current phase, each subagent's state, and next action
@@ -363,6 +373,7 @@ When a Design Doc contains a Verification Strategy section, the orchestrator mus
   - Early verification point (first target, success criteria, failure response)
 
 The resulting work plan must include this summary in its header so the plan remains self-sufficient for downstream task generation and execution planning.
+When the Design Doc includes an `Output Comparison` section, carry forward the comparison input, expected output fields or format, diff method, and transformation pipeline coverage as part of that summary.
 
 ## Important Constraints [MANDATORY]
 

package/.codex/agents/code-reviewer.toml

@@ -59,27 +59,79 @@ Skill Status:
 ## Workflow
 
 ### 1. Load Baseline
-Read the Design Doc and extract:
+Read the Design Doc in full and extract:
 - Functional requirements and acceptance criteria (list each AC individually)
 - Architecture design and data flow
+- Interface contracts (function signatures, API endpoints, data structures)
+- Identifier specifications explicitly written in the Design Doc as exact values, literals, labels, or named fields (resource names, endpoint paths, configuration keys, error codes, schema/model names)
 - Error handling policy
 - Non-functional requirements
 
-### 2. Map Implementation to Acceptance Criteria
+### 2. Map Implementation to Design Doc
+
+#### 2-1. Acceptance Criteria Verification
 For each acceptance criterion extracted in Step 1:
 - Search implementation files for the corresponding code
 - Determine status: fulfilled / partially fulfilled / unfulfilled
 - Record the file path and relevant code location
 - Note any deviations from the Design Doc specification
 
+#### 2-2. Identifier Verification
+For each identifier specification extracted in Step 1:
+1. Search implementation files for the exact string
+2. Compare code values against the Design Doc specification
+3. Flag discrepancies such as missing references, misspellings, or inconsistent naming
+4. Evaluate every identifier and update overall totals for matched and mismatched results
+5. Emit only mismatches in `identifierVerification`, with `{ identifier, designDocValue, codeValue, location, match, confidence, evidence }`
+
+Identifier extraction constraints:
+- Only verify identifiers that are explicitly written in the Design Doc as exact values, literals, labeled fields, or code-facing names
+- Do not infer identifiers from descriptive prose, conceptual summaries, or implied naming conventions
+- If the Design Doc names a concept without an exact code-facing value, treat it as a normal Design Doc claim, not an identifier check
+
+#### 2-3. Evidence Collection
+For each acceptance criterion and identifier check:
+1. Primary evidence: direct implementation in source files
+2. Secondary evidence: corresponding tests
+3. Tertiary evidence: config, schemas, or type definitions
+
+`agreeing sources` means multiple sources independently support the same determination about the same acceptance criterion or identifier. Naming overlap alone is NOT agreement; the evidence must support the same behavior, contract, or exact value match.
+
+Assign confidence based on evidence count:
+- high: 3+ agreeing sources
+- medium: 2 agreeing sources
+- low: 1 source only
+
 ### 3. Assess Code Quality
-Read each implementation file and check:
-- Function length (ideal: <50 lines, max: 200 lines)
-- Nesting depth (ideal: <=3 levels, max: 4 levels)
-- Single responsibility adherence
-- Error handling implementation
-- Appropriate logging
-- Test coverage for acceptance criteria
+Read each implementation file and evaluate:
+
+#### 3-1. Structural Quality
+For each implementation file, read the concrete functions, handlers, or components in scope and evaluate them against the active coding-rules skill:
+- Function organization: flag `maintainability` when a single function mixes multiple distinct concerns such as validation, orchestration, persistence, and presentation formatting
+- Control-flow clarity: flag `maintainability` when branches, nested conditions, or early-exit patterns make the execution path materially difficult to follow
+- Single responsibility adherence: flag `maintainability` when a function or file has more than one primary responsibility
+- Naming clarity: flag `maintainability` when ambiguous names materially obscure intent, domain meaning, or responsibility
+
+#### 3-2. Error Handling and Reliability
+Read error paths and boundary handling directly in the code:
+- Error handling implementation: verify failures are either propagated explicitly or handled with context
+- Explicit failure paths over silent suppression: flag `reliability` when errors are swallowed, converted to defaults without justification, or otherwise hidden from callers and operators
+- Boundary validation: flag `reliability` when external input, deserialized data, or cross-system responses enter important logic without the validation implied by the Design Doc, type contracts, or code boundary shape
+
+#### 3-3. Test Coverage for Acceptance Criteria
+- For each fulfilled AC, check whether tests exercise the expected behavior
+
+Classify each quality finding into one of:
+- `dd_violation`: implementation deviates from the Design Doc
+- `maintainability`: code structure impedes change or comprehension
+- `reliability`: missing safeguards could cause runtime failure
+- `coverage_gap`: acceptance criteria lack meaningful test verification
+
+Each finding MUST include a rationale:
+- `dd_violation`: what the Design Doc says vs what code does
+- `maintainability`: the concrete maintenance or comprehension risk
+- `reliability`: the failure scenario and triggering conditions
+- `coverage_gap`: the untested AC and why coverage matters
 
 ### 4. Check Architecture Compliance
 Verify against the Design Doc architecture:
@@ -89,9 +141,10 @@ Verify against the Design Doc architecture:
 - No unnecessary duplicate implementations (Pattern 5 from ai-development-guide skill)
 - Existing codebase analysis section includes similar functionality investigation results
 
-### 5. Calculate Compliance
+### 5. Calculate Compliance and Consolidate
 - Compliance rate = (fulfilled items + 0.5 x partially fulfilled items) / total AC items x 100
-- Compile all AC statuses, quality issues with specific locations
+- Identifier match rate = matched identifiers / total identifiers x 100
+- Compile all AC statuses, identifier results, and quality findings with specific locations
 - Determine verdict based on compliance rate
 
 ### 6. Return JSON Result
@@ -102,50 +155,100 @@ Return the JSON result as the final response. See Output Format for the schema.
 ```json
 {
   "complianceRate": "[X]%",
+  "identifierMatchRate": "[X]%",
   "verdict": "[pass/needs-improvement/needs-redesign]",
 
   "acceptanceCriteria": [
     {
       "item": "[acceptance criteria name]",
       "status": "fulfilled|partially_fulfilled|unfulfilled",
+      "confidence": "high|medium|low",
       "location": "[file:line, if implemented]",
+      "evidence": ["[source1: file:line]", "[source2: test file:line]"],
       "gap": "[what is missing or deviating, if not fully fulfilled]",
       "suggestion": "[specific fix, if not fully fulfilled]"
     }
   ],
 
-  "qualityIssues": [
+  "identifierVerification": [
+    {
+      "identifier": "[identifier name]",
+      "designDocValue": "[value specified in Design Doc]",
+      "codeValue": "[value found in code, or 'not found']",
+      "location": "[file:line]",
+      "confidence": "high|medium|low",
+      "evidence": ["[source1: file:line]", "[source2: config file:line]"],
+      "match": false
+    }
+  ],
+
+  "qualityFindings": [
     {
-      "type": "[long-function/deep-nesting/multiple-responsibilities]",
-      "location": "[filename:function]",
+      "category": "dd_violation|maintainability|reliability|coverage_gap",
+      "location": "[filename:function or file:line]",
+      "description": "[specific issue]",
+      "rationale": "[why this matters]",
       "suggestion": "[specific improvement]"
     }
   ],
 
+  "summary": {
+    "acsTotal": 0,
+    "acsFulfilled": 0,
+    "acsPartial": 0,
+    "acsUnfulfilled": 0,
+    "identifiersTotal": 0,
+    "identifiersMatched": 0,
+    "lowConfidenceItems": 0,
+    "findingsByCategory": {
+      "dd_violation": 0,
+      "maintainability": 0,
+      "reliability": 0,
+      "coverage_gap": 0
+    }
+  },
+
   "nextAction": "[highest priority action needed]"
 }
 ```
 
+`identifierVerification` MUST include mismatches only. Use `summary.identifiersTotal` and `summary.identifiersMatched` for overall counts.
+
 ## Verdict Criteria
 
 - **90%+**: pass — Minor adjustments only
 - **70-89%**: needs-improvement — Critical gaps exist
 - **<70%**: needs-redesign — Major revision required
 
+Lower the verdict by one level only when at least one identifier mismatch has confidence `medium` or `high`.
+
 ## Important Notes
 
 ### Review Principles
 - Use Design Doc as single source of truth; evaluate independent of implementation context
+- Every finding must include file:line evidence
+- Low-confidence determinations must be explicit
+- Convert abstract skill rules into concrete, code-backed review findings rather than restating the rule alone
 - Provide solutions, not just problems; quantify wherever possible
-- Acknowledge good implementations; present improvements as actionable items
 
 ## Completion Criteria
 
-- [ ] All acceptance criteria individually evaluated
-- [ ] Compliance rate calculated
+- [ ] All acceptance criteria individually evaluated with confidence
+- [ ] Identifier specifications verified against implementation
+- [ ] Compliance rate and identifier match rate calculated
+- [ ] Quality findings classified with rationale
 - [ ] Verdict determined
 - [ ] Final response is the JSON output
 
+## Output Self-Check
+
+- [ ] Every AC determination cites evidence
+- [ ] Identifier comparisons use exact strings from the Design Doc and code
+- [ ] Low-confidence items are explicit
+- [ ] Every quality finding includes category, rationale, and file:line
+- [ ] Every maintainability or reliability finding is backed by code that was actually read, not inferred from naming alone
+- [ ] identifierVerification contains mismatches only, and each mismatch includes confidence and evidence
+
 ### Escalation Criteria
 Recommend higher-level review when: Design Doc itself has deficiencies, security concerns discovered, or critical performance issues found.
 

package/.codex/agents/codebase-analyzer.toml

@@ -70,14 +70,29 @@ Identify what exists, what appears missing, and what deserves close attention in
 ### Step 2: Existing Code Element Discovery
 
 For each affected file or inferred target file in the selected scope:
-1. Read the file and record public interfaces, key functions, classes, types, constants, and configuration use
-2. Trace one level of direct dependencies through imports or equivalent declarations
-3. Search for patterns related to:
+1. Read the file in full and record:
+   - public and private/internal interfaces, key functions, methods, classes, types, constants, and configuration use
+   - exact names, visibility, and signatures where directly observable
+2. Trace call chains with these scope rules:
+   - same module or file: follow internal function and method calls recursively until the chain terminates, delegates externally, or reaches a leaf
+   - external dependencies through imports or equivalent declarations: record them as integration points with public interface or contract details only
+3. Enumerate all entry points discovered in the traced scope that receive input from outside the module or file
+4. Mark each entry point as `change-relevant` or `non-relevant` based on requirement scope, affected files, and user-visible behavior
+5. For each `change-relevant` entry point, trace the data transformation pipeline step by step:
+   - record how the input changes at each step
+   - record intermediate representations or formats when they differ from the final output
+   - record external lookups that modify values, including configuration, constants, mapping tables, and reference data
+6. For each `non-relevant` entry point, record at minimum:
+   - entry point name and file:line
+   - input shape
+   - output shape
+7. If additional entry points share the same output path or transformation logic as a `change-relevant` entry point, reclassify them as `change-relevant` and trace them step by step
+8. Search for patterns related to:
    - data access: repository usage, ORM calls, query builders, raw SQL, migration references
    - external service calls: HTTP clients, SDK clients, queue producers or consumers, webhook handlers
    - validation logic: validator functions, schema parsers, assertions, guard clauses, constraint checks
    - user-visible state handling: state stores, reducers, hooks, loading or error states, view-model shaping
-4. Record each discovered element with exact file path and line number
+9. Record each discovered element with exact file path and line number
 
 ### Step 3: Data Model Discovery
 
@@ -149,6 +164,31 @@ Return the JSON result as the final response.
     ],
     "migrationFiles": ["path/to/migration"]
   },
+  "dataTransformationPipelines": [
+    {
+      "entryPoint": "functionOrMethodName (path/to/file:line)",
+      "steps": [
+        {
+          "order": 1,
+          "method": "functionOrMethodName (path/to/file:line)",
+          "input": "Input data or format at this step",
+          "output": "Output data or format at this step",
+          "externalLookups": ["Config.KEY lookup", "Reference table mapping"],
+          "transformation": "What changed and why it matters"
+        }
+      ],
+      "intermediateFormats": ["Intermediate representation if applicable"],
+      "finalOutput": "Final output shape or observable value"
+    }
+  ],
+  "entryPointInventory": [
+    {
+      "entryPoint": "functionOrMethodName (path/to/file:line)",
+      "classification": "change-relevant|non-relevant",
+      "inputShape": "Input type or shape",
+      "outputShape": "Output type or shape"
+    }
+  ],
   "constraints": [
     {
       "type": "validation|business_rule|configuration|assumption",
@@ -176,11 +216,18 @@ Return the JSON result as the final response.
 ## Completion Criteria
 
 - [ ] Parsed requirement context and identified analysis categories
-- [ ] Read affected files and traced direct dependencies
-- [ ] Recorded key interfaces and implementation elements with file:line evidence
+- [ ] Read affected files in full and recorded public and private implementation elements with file:line evidence, or documented scope limits in `limitations`
+- [ ] Traced call chains according to the scope rules, or documented incomplete traces in `limitations`
+- [ ] Enumerated all entry points in the traced scope and marked each as `change-relevant` or `non-relevant`
+- [ ] Traced data transformation pipelines step by step for all `change-relevant` entry points that transform incoming data
+- [ ] Recorded at minimum entry point name, input shape, and output shape for all `non-relevant` entry points
+- [ ] Reclassified and traced entry points that share the same output path or transformation logic as a `change-relevant` entry point
+- [ ] Recorded external lookups that modify output values, including configuration, constants, and mapping data
 - [ ] Performed data model discovery when data access patterns were present
 - [ ] Extracted constraints and focus areas with concrete risks
 - [ ] Checked existing tests for coverage signals
+- [ ] Populated `dataTransformationPipelines` for all traced pipelines
+- [ ] Populated `entryPointInventory` for all discovered entry points in the traced scope
 - [ ] Returned valid JSON
 """
 

package/.codex/agents/document-reviewer.toml

@@ -98,6 +98,7 @@ For DesignDoc, additionally verify:
 - [ ] Field propagation map present (when fields cross boundaries)
 - [ ] Data-oriented designs contain concrete data design or Test Boundaries content, or an explicit N/A rationale
 - [ ] Verification Strategy section present with correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
+- [ ] Output Comparison section present when the design changes existing observable behavior, an external contract, or a persisted data shape
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -116,6 +117,7 @@ For DesignDoc, additionally verify:
 - **Data design completeness check**: When the document references persistence, storage, database, repository, query, ORM, migration, table, schema, or column concepts, verify that the Design Doc includes concrete data design content or an explicit N/A rationale. Useful evidence includes schema references, data model notes, or Test Boundaries with data layer strategy
 - **Code-verifier evidence integration**: When `code_verification` is provided, reconcile major or critical discrepancies and undocumented data operations as part of Gate 1 completeness and consistency review
 - **Verification Strategy quality check**: When the Verification Strategy section exists, verify that: (1) correctness definition is specific and measurable, (2) target comparison and observable success indicator are concrete when the change modifies observable behavior, external contracts, integrations, or data flow, (3) internal-only refactoring with identical observable inputs and outputs may use the minimal form, (4) verification method can detect the change's primary risk, (5) verification timing uses the normalized vocabulary or an explicit `N/A` rationale for minimal form, and (6) vertical-slice designs do not defer all verification to the final phase
+- **Output comparison check**: When the Design Doc changes existing observable behavior, an external contract, or a persisted data shape, verify that a concrete output comparison method is defined with identical input, expected output fields or format, and diff method. When upstream analysis includes `dataTransformationPipelines`, each listed step must be mapped to the comparison that verifies it; steps excluded because data passes through unchanged must include rationale. Missing mappings or rationale → `important` issue (category: `completeness`)
 - **Undetermined items review** [MANDATORY]: Every TBD, unknown, or open item MUST include: (1) **owner** — who resolves it, (2) **due** — when it gets resolved (which phase or milestone), (3) **next-phase handling** — how the next phase treats this gap. Missing any of these three → `important` issue
 
 **Perspective-specific Mode**:
@@ -258,6 +260,7 @@ Include in output when `prior_context_count > 0`:
 - [ ] Match of requirements, terminology, numbers between documents
 - [ ] Completeness of required elements in each document
 - [ ] Verification Strategy present with a concrete correctness definition and early verification point
+- [ ] Output Comparison defined when the design changes existing observable behavior, an external contract, or a persisted data shape
 - [ ] Verification Strategy aligns with design type and implementation approach
 - [ ] Compliance with project rules
 - [ ] Technical feasibility and reasonableness of estimates

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

@@ -90,7 +90,7 @@ Must be performed before Design Doc creation:
    - Record and distinguish between existing implementation locations and planned new locations
 
 2. **Existing Interface Investigation** (Only when changing existing features)
-   - List major public methods of target service (about 5 important ones if over 10)
+   - List every public method of the target service with full signatures
    - Identify call sites using content search with appropriate search patterns
 
 3. **Similar Functionality Search and Decision** (Pattern 5 prevention from ai-development-guide skill)
@@ -189,7 +189,9 @@ Must be performed when creating Design Doc:
    - For new features, specify acceptance-criteria verification beyond unit tests
    - For extensions, specify regression verification that proves existing behavior is preserved
    - For refactors or rewrites, specify behavioral equivalence verification against the current implementation when applicable
-   - Define an early verification point: the first target to validate before scaling the approach
+   - When the design changes existing observable behavior, an external contract, or a persisted data shape, define a concrete `Output Comparison` method: identical input, expected output fields or format, diff method, and a mapping from each listed pipeline step to the comparison that verifies it
+   - When `Codebase Analysis` provides `dataTransformationPipelines`, use them to populate the `Output Comparison` section. Steps that pass data through unchanged may be excluded only with explicit rationale
+   - Define an early verification point: the first target to validate before scaling the approach. For changes to existing observable behavior, external contracts, or persisted data shapes, this must be an output comparison of at least one representative case
 
 ### Change Impact Map【Required】
 Must be included when creating Design Doc:
@@ -252,6 +254,7 @@ Confirm and document conflicts with existing systems at each integration point t
   - `dataModel` informs schema references, data contracts, and persistence design
   - `focusAreas` indicate areas requiring deeper design attention
   - `constraints` inform design constraints, assumptions, and risk handling
+  - `dataTransformationPipelines` informs the `Output Comparison` section in Verification Strategy
   - Additional investigation should focus on gaps or limitations that the analysis calls out
 - **PRD**: PRD document (if exists)
 - **Documents to Create**: ADR, Design Doc, or both
@@ -352,6 +355,7 @@ Implementation sample creation checklist:
 - [ ] **Data representation decision documented** (when new structures introduced)
 - [ ] **Field propagation map included** (when fields cross boundaries)
 - [ ] **Verification Strategy defined** (correctness definition, target comparison, verification method, observable success indicator, timing, early verification point)
+- [ ] **Output Comparison defined** when changing existing observable behavior, an external contract, or a persisted data shape (comparison input, expected output fields, diff method, and transformation pipeline coverage)
 
 **Reverse-engineer mode only**:
 - [ ] Every architectural claim cites file:line evidence

package/README.md

@@ -4,9 +4,9 @@
 [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Spec%20Compliant-blue)](https://developers.openai.com/codex/skills/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**End-to-end AI coding workflows for [Codex CLI](https://developers.openai.com/codex/cli)** — specialized subagents handle requirements, design, implementation, and quality checks so you get code with explicit design docs, test coverage, and commit-level traceability — not just raw generations.
+**Structured agentic coding workflows for [OpenAI Codex CLI](https://developers.openai.com/codex/cli)** — specialized AI coding agents plan, implement, test, and review changes with traceable docs, task-level commits, and quality gates.
 
-Built on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents). Works with the latest GPT models.
+Built on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents). Designed for long-running tasks, large refactors, and reviewable changes.
 
 ---
 
@@ -25,36 +25,45 @@ $recipe-implement Add user authentication with JWT
 
 `$` is Codex CLI's syntax for invoking a skill explicitly. Type `$recipe-` to see all available recipes via tab completion.
 
-The framework runs a structured workflow — requirements → design → task decomposition → TDD implementation → quality gates — all through specialized subagents.
+Small changes stay lightweight. Larger tasks get structure: requirements → design → task decomposition → TDD implementation → quality gates.
+
+codex-workflows is the Codex-native counterpart of [Claude Code Workflows](https://github.com/shinpr/claude-code-workflows): same document-driven development style, adapted for Codex CLI, subagents, and GPT models.
 
 ---
 
 ## Why codex-workflows?
 
-**Without codex-workflows:**
-- Code generation is inconsistent across large tasks
-- Requirements and design decisions are implicit — lost after the session
-- Refactoring and debugging become harder as context grows
+Codex is already strong at one-shot implementation. The problem starts when a change spans multiple files, needs design decisions to stay visible, or has to survive review, testing, and follow-up edits.
+
+For larger tasks, explicit planning changes the job from raw generation into verification against a design, a task breakdown, and acceptance criteria. That matters because review loops are more reliable than first-shot generation once scope and ambiguity grow.
+
+codex-workflows adds the missing structure around those jobs:
+- Traceable artifacts: PRD → Design Doc → Task → Commit
+- Built-in TDD and quality gates before code is ready to commit
+- Agent context separation for large refactors, migrations, and PR-sized changes
+- Diagnosis and reverse-engineering flows for bugs and legacy code
+
+## Not Designed For
 
-**With codex-workflows:**
-- Every change is traceable: PRD → Design Doc → Task → Commit
-- Built-in TDD and quality gates catch regressions before commit
-- Large tasks stay structured and reviewable through agent context separation
+- One-shot toy scripts or vibe-coding sessions where speed matters more than traceability
+- Repositories that do not use tests, lint, builds, or reviewable commits
+- Teams that do not want design docs, task breakdowns, or explicit quality gates
 
 ---
 
 ## What It Does
 
-A single request becomes a structured development process:
+A single request becomes a structured development process. The framework chooses the level of ceremony based on scope:
+
+| Scale | File Count | What Happens |
+|-------|------------|-------------|
+| Small | 1-2 | Simplified plan → direct implementation |
+| Medium | 3-5 | Design Doc → work plan → task execution |
+| Large | 6+ | PRD → ADR → Design Doc → test skeletons → work plan → autonomous execution |
 
-1. **Understand** the problem (scale, constraints, affected files)
-2. **Analyze the existing codebase** (dependencies, data layer, risk areas)
-3. **Design** the solution (ADR, Design Doc with acceptance criteria)
-4. **Break it into tasks** (atomic, 1 commit each)
-5. **Implement with tests** (TDD per task)
-6. **Run quality checks** (lint, test, build — no failing checks)
+For larger work, the path usually looks like this: understand the problem, analyze the codebase, design the change, break it into atomic tasks, implement with tests, and run quality checks before commit.
 
-Each step is handled by a specialized subagent in its own context, preventing context pollution and reducing error accumulation in long-running tasks:
+Each step is handled by a specialized subagent in its own context, using context engineering to prevent context pollution and reduce error accumulation in long-running tasks:
 
 ```
 User Request
@@ -96,6 +105,8 @@ Problem → investigator → verifier (ACH + Devil's Advocate) → solver → Ac
 Existing code → scope-discoverer (discoveredUnits + prdUnits) → prd-creator → code-verifier → document-reviewer → Design Docs
 ```
 
+This works best when repository knowledge is explicit and local. Short `AGENTS.md` files can act as entry points, while design docs, plans, and task files hold the deeper instructions that agents need to execute reliably.
+
 ---
 
 ## Installation
@@ -103,7 +114,7 @@ Existing code → scope-discoverer (discoveredUnits + prdUnits) → prd-creator
 ### Requirements
 
 - [Codex CLI](https://developers.openai.com/codex/cli) (latest)
-- Node.js >= 20
+- Node.js >= 22
 
 ### Install
 
@@ -266,16 +277,6 @@ Codex spawns these as needed during recipe execution. Each agent runs in its own
 
 ## How It Works
 
-### Scale-Based Workflow Selection
-
-The framework automatically determines the right level of ceremony:
-
-| Scale | File Count | What Happens |
-|-------|------------|-------------|
-| Small | 1-2 | Simplified plan → direct implementation |
-| Medium | 3-5 | Design Doc → work plan → task execution |
-| Large | 6+ | PRD → ADR → Design Doc → test skeletons → work plan → autonomous execution |
-
 ### Autonomous Execution Mode
 
 After work plan approval, the framework enters guided autonomous execution with escalation points:
@@ -287,7 +288,8 @@ After work plan approval, the framework enters guided autonomous execution with
 
 ### Context Separation
 
-Each subagent runs in a fresh context. This matters because:
+Each subagent runs in a fresh context. This context-engineering pattern keeps long-running agentic coding tasks legible and reviewable:
+- generation and verification happen in separate contexts, reducing author bias and carry-over assumptions
 - **document-reviewer** reviews without the author's bias
 - **investigator** collects evidence without confirmation bias
 - **code-reviewer** validates compliance without implementation context
@@ -335,6 +337,14 @@ your-project/
 
 ---
 
+## Works With
+
+If your requirements already live in Linear or an existing PRD, [linear-prism](https://github.com/shinpr/linear-prism) can decompose them into implementation-ready tasks by reading the codebase, making dependencies explicit, and preserving Design Doc boundaries.
+
+Those tasks can then be passed into `$recipe-design` to enter the design phase with clearer scope and better task visibility.
+
+---
+
 ## FAQ
 
 **Q: What models does this work with?**
@@ -349,10 +359,6 @@ A: Yes. Edit the TOML files in `.codex/agents/` — change model, sandbox_mode,
 
 A: `$recipe-implement` is the universal entry point. It runs requirement-analyzer first, detects affected layers from the codebase, and automatically routes to backend, frontend, or fullstack flow. `$recipe-fullstack-implement` skips the detection and goes straight into the fullstack flow (separate Design Docs per layer, design-sync, layer-aware task execution). Use `$recipe-implement` when you're not sure; use `$recipe-fullstack-implement` when you know upfront that the feature spans both layers.
 
-**Q: How does this relate to Claude Code Workflows?**
-
-A: codex-workflows is the Codex-native counterpart of [Claude Code Workflows](https://github.com/shinpr/claude-code-workflows). Same development philosophy, adapted for Codex CLI's subagent architecture and GPT model family.
-
 **Q: Does this work with MCP servers?**
 
 A: Yes. Codex skills and subagents work alongside [MCP](https://developers.openai.com/codex/mcp) — skills operate at the instruction layer while MCP operates at the tool transport layer. You can add MCP servers to any agent's TOML configuration.
@@ -363,6 +369,19 @@ A: Subagents escalate to the user when they encounter design deviations, ambiguo
 
 ---
 
+## Design Rationale
+
+<details>
+<summary>Background reading behind the workflow design</summary>
+
+- [Planning Is the Real Superpower of Agentic Coding](https://www.norsica.jp/blog/planning-superpower-agentic-coding) — why explicit planning turns large-task execution from raw generation into verification against a design and task breakdown
+- [Why LLMs Are Bad at 'First Try' and Great at Verification](https://www.norsica.jp/blog/llm-verification-over-generation) — why review loops and session separation are more reliable than first-shot generation on complex work
+- [Stop Putting Everything in AGENTS.md](https://www.norsica.jp/blog/stop-putting-everything-in-agents-md) — why `AGENTS.md` should stay lean while rules, docs, and task instructions live near the point of use
+
+</details>
+
+---
+
 ## License
 
 MIT License — free to use, modify, and distribute.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",
@@ -22,9 +22,12 @@
     "agent-skills",
     "agentic-coding",
     "ai-coding",
+    "ai-coding-agent",
     "subagents",
     "multi-agent",
+    "harness-engineering",
     "context-engineering",
+    "ai-development-workflow",
     "tdd",
     "code-generation"
   ],