codex-workflows 0.4.2 → 0.4.3

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
@@ -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

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/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
@@ -349,10 +351,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 +361,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.3",
   "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"
   ],