codex-workflows 0.6.8 → 0.7.0

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

@@ -126,163 +126,7 @@ Produce `candidateWriteSet[]` with likely modified files:
 Return a single JSON object as the final response:
 
 ```json
-{
-  "analysisScope": {
-    "filesAnalyzed": ["path/to/component.tsx"],
-    "stylesAnalyzed": ["path/to/styles.module.css"],
-    "uiConventions": {
-      "componentExtension": ".tsx",
-      "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes|unknown",
-      "storybook": true,
-      "testRunner": "vitest|jest|other|unknown"
-    }
-  },
-  "externalResources": {
-    "status": "resolved|partial|not_recorded",
-    "designOrigin": {
-      "resource_status": "present|existing-implementation|not_applicable",
-      "resolution_status": "fetched|inspected_local|recorded_for_manual_confirmation|unavailable|not_applicable",
-      "accessMethod": "MCP name | URL | file path | existing implementation",
-      "summary": "brief description of resolved content"
-    },
-    "designSystem": {
-      "resource_status": "present|existing-package|not_applicable",
-      "resolution_status": "fetched|inspected_local|unavailable|not_applicable",
-      "accessMethod": "MCP name | URL | file path | package imports | local docs",
-      "summary": "components, tokens, and variants captured"
-    },
-    "guidelines": {
-      "resource_status": "present|project-conventions|not_applicable",
-      "resolution_status": "fetched|inspected_local|unavailable|not_applicable",
-      "accessMethod": "URL | file path | local docs | project conventions",
-      "summary": "rule categories captured"
-    },
-    "visualVerification": {
-      "resource_status": "present|manual-confirmation|not_applicable",
-      "resolution_status": "available|recorded_for_manual_confirmation|unavailable|not_applicable",
-      "accessMethod": "MCP name | URL | command | manual confirmation",
-      "notes": "rendering verification path"
-    },
-    "generatedUiArtifacts": {
-      "resource_status": "present|not_applicable",
-      "resolution_status": "inspected_local|available|unavailable|not_applicable",
-      "accessMethod": "command | config path | file path | package script",
-      "summary": "generated UI artifact source, trigger, and verification path"
-    },
-    "additionalResources": [
-      {
-        "label": "resource-label",
-        "description": "resource description",
-        "accessMethod": "URL | MCP name | file path | command | notes",
-        "resource_status": "present|existing-implementation|existing-package|project-conventions|manual-confirmation",
-        "resolution_status": "fetched|inspected_local|recorded_for_manual_confirmation|unavailable",
-        "summary": "facts relevant to the requested UI scope"
-      }
-    ]
-  },
-  "componentStructure": [
-    {
-      "name": "ComponentName",
-      "filePath": "path/to/file:line",
-      "propsInterface": "name and brief shape",
-      "topLevelElement": "tag or component name",
-      "domOrder": ["child1", "child2"],
-      "conditionalBranches": [
-        {"predicate": "condition", "renderedSubtree": "brief description"}
-      ],
-      "callSites": ["path/to/consumer:line"]
-    }
-  ],
-  "propsPatterns": [
-    {
-      "component": "ComponentName",
-      "callSite": "path/to/file:line",
-      "props": {"variant": "primary"},
-      "computedProps": ["onClick"],
-      "groupKey": "primary"
-    }
-  ],
-  "cssLayout": [
-    {
-      "filePath": "path/to/styles.module.css",
-      "classNamingConvention": "camelCase|kebab-case|BEM|unknown",
-      "baseClass": "root",
-      "layouts": [
-        {
-          "selector": ".root",
-          "display": "flex|grid|block|unknown",
-          "direction": "row|column|grid-template|unknown",
-          "gap": "8px|none|unknown",
-          "wrap": "wrap|nowrap|absent|unknown",
-          "logicalProperties": true,
-          "stateSelectors": ["[data-state=active]"]
-        }
-      ],
-      "responsiveBreakpoints": ["768px"]
-    }
-  ],
-  "stateDisplay": [
-    {
-      "component": "ComponentName",
-      "states": [
-        {"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}
-      ],
-      "unsupportedStates": ["state absent from current component"]
-    }
-  ],
-  "displayConditions": [
-    {
-      "component": "ComponentName",
-      "condition": "feature_flag|role|route|region|tenant|page_context",
-      "predicateLocation": "path/to/file:line",
-      "predicate": "expression",
-      "gatedSubtree": "brief description"
-    }
-  ],
-  "i18n": {
-    "format": "csv|json|code-catalog|other|none",
-    "structuralConventions": {},
-    "keyNamingConvention": "",
-    "locales": [],
-    "localeGaps": [],
-    "generatedTypings": {"command": "", "outputPath": ""}
-  },
-  "accessibility": [
-    {
-      "component": "ComponentName",
-      "ariaAttributes": ["role=button", "aria-label from prop"],
-      "keyboardHandling": "Enter and Space trigger action",
-      "focusStyling": "focus-visible outline",
-      "testCoverage": "axe checks present|absent|unknown"
-    }
-  ],
-  "generatedArtifacts": [
-    {
-      "kind": "css-module-typings|message-catalog-typings|route-typings|other",
-      "command": "generator command",
-      "trigger": "on source change|manual|unknown",
-      "consumers": ["typecheck", "test", "build", "runtime"],
-      "resourceRef": "externalResources.generatedUiArtifacts"
-    }
-  ],
-  "focusAreas": [
-    {
-      "fact_id": "path:identifier",
-      "area": "Brief UI area name",
-      "evidence": "componentStructure[name=...]",
-      "factsToAddress": "Concrete UI facts to respect",
-      "risk": "What inconsistency results if omitted"
-    }
-  ],
-  "candidateWriteSet": [
-    {
-      "path": "src/components/Card.tsx",
-      "reasonRef": "focusAreas[fact_id=...]",
-      "confidence": "high|medium|low"
-    }
-  ],
-  "limitations": []
-}
+{"analysisScope":{"filesAnalyzed":["path/to/component.tsx"],"stylesAnalyzed":["path/to/styles.module.css"],"uiConventions":{"componentExtension":".tsx","styleStrategy":"css-modules|vanilla-css|css-in-js|utility-classes|unknown","storybook":true,"testRunner":"vitest|jest|other|unknown"}},"externalResources":{"status":"resolved|partial|not_recorded","designOrigin":{"resource_status":"present|existing-implementation|not_applicable","resolution_status":"fetched|inspected_local|recorded_for_manual_confirmation|unavailable|not_applicable","accessMethod":"MCP name | URL | file path | existing implementation","summary":"brief description of resolved content"},"designSystem":{"resource_status":"present|existing-package|not_applicable","resolution_status":"fetched|inspected_local|unavailable|not_applicable","accessMethod":"MCP name | URL | file path | package imports | local docs","summary":"components, tokens, and variants captured"},"guidelines":{"resource_status":"present|project-conventions|not_applicable","resolution_status":"fetched|inspected_local|unavailable|not_applicable","accessMethod":"URL | file path | local docs | project conventions","summary":"rule categories captured"},"visualVerification":{"resource_status":"present|manual-confirmation|not_applicable","resolution_status":"available|recorded_for_manual_confirmation|unavailable|not_applicable","accessMethod":"MCP name | URL | command | manual confirmation","notes":"rendering verification path"},"generatedUiArtifacts":{"resource_status":"present|not_applicable","resolution_status":"inspected_local|available|unavailable|not_applicable","accessMethod":"command | config path | file path | package script","summary":"generated UI artifact source, trigger, and verification path"},"additionalResources":[{"label":"resource-label","description":"resource description","accessMethod":"URL | MCP name | file path | command | notes","resource_status":"present|existing-implementation|existing-package|project-conventions|manual-confirmation","resolution_status":"fetched|inspected_local|recorded_for_manual_confirmation|unavailable","summary":"facts relevant to the requested UI scope"}]},"componentStructure":[{"name":"ComponentName","filePath":"path/to/file:line","propsInterface":"name and brief shape","topLevelElement":"tag or component name","domOrder":["child1","child2"],"conditionalBranches":[{"predicate":"condition","renderedSubtree":"brief description"}],"callSites":["path/to/consumer:line"]}],"propsPatterns":[{"component":"ComponentName","callSite":"path/to/file:line","props":{"variant":"primary"},"computedProps":["onClick"],"groupKey":"primary"}],"cssLayout":[{"filePath":"path/to/styles.module.css","classNamingConvention":"camelCase|kebab-case|BEM|unknown","baseClass":"root","layouts":[{"selector":".root","display":"flex|grid|block|unknown","direction":"row|column|grid-template|unknown","gap":"8px|none|unknown","wrap":"wrap|nowrap|absent|unknown","logicalProperties":true,"stateSelectors":["[data-state=active]"]}],"responsiveBreakpoints":["768px"]}],"stateDisplay":[{"component":"ComponentName","states":[{"name":"loading|empty|partial|error|ready|disabled","trigger":"what causes this state","renders":"brief description"}],"unsupportedStates":["state absent from current component"]}],"displayConditions":[{"component":"ComponentName","condition":"feature_flag|role|route|region|tenant|page_context","predicateLocation":"path/to/file:line","predicate":"expression","gatedSubtree":"brief description"}],"i18n":{"format":"csv|json|code-catalog|other|none","structuralConventions":{},"keyNamingConvention":"","locales":[],"localeGaps":[],"generatedTypings":{"command":"","outputPath":""}},"accessibility":[{"component":"ComponentName","ariaAttributes":["role=button","aria-label from prop"],"keyboardHandling":"Enter and Space trigger action","focusStyling":"focus-visible outline","testCoverage":"axe checks present|absent|unknown"}],"generatedArtifacts":[{"kind":"css-module-typings|message-catalog-typings|route-typings|other","command":"generator command","trigger":"on source change|manual|unknown","consumers":["typecheck","test","build","runtime"],"resourceRef":"externalResources.generatedUiArtifacts"}],"focusAreas":[{"fact_id":"path:identifier","area":"Brief UI area name","evidence":"componentStructure[name=...]","factsToAddress":"Concrete UI facts to respect","risk":"What inconsistency results if omitted"}],"candidateWriteSet":[{"path":"src/components/Card.tsx","reasonRef":"focusAreas[fact_id=...]","confidence":"high|medium|low"}],"limitations":[]}
 ```
 
 ## Quality Checklist

package/.codex/agents/verifier.toml

@@ -80,6 +80,7 @@ Record each supplementary finding and its impact on the existing failure points
 - Check whether the mapped execution path adequately covers the observed symptom from entry to failure
 - Identify uncovered boundaries or unverified nodes that could hide additional failure points
 - Evaluate at least 2 additional path segments or boundaries beyond the investigator's original failure-point list
+- When the investigated incident is a bug or regression, or when a failure point affects a state transition, persisted state, or external boundary, trace adjacent cases sharing the same path, contract, persisted state, or external boundary and evaluate whether they carry the same class of defect
 - Evaluate each failure point independently:
   - Is the supporting evidence sufficient?
   - Is there direct counter-evidence?
@@ -125,71 +126,7 @@ Return the JSON result as the final response. See Output Format for the schema.
 **JSON format is mandatory.**
 
 ```json
-{
-  "investigationReview": {
-    "originalFailurePointCount": 3,
-    "coverageAssessment": "sufficient|partial|insufficient",
-    "identifiedGaps": ["Perspectives overlooked in investigation"]
-  },
-  "triangulationSupplements": [
-    {
-      "source": "Additional information source investigated",
-      "findings": "Content discovered",
-      "impactOnFailurePoints": "Impact on existing failure points"
-    }
-  ],
-  "scopeValidation": {
-    "verified": true,
-    "concerns": ["Concerns"]
-  },
-  "externalResearch": [
-    {
-      "query": "Search query used",
-      "source": "Information source",
-      "findings": "Related information discovered",
-      "impactOnFailurePoints": "Impact on failure points"
-    }
-  ],
-  "additionalFailurePoints": [
-    {
-      "id": "AFP1",
-      "description": "Additional failure point description",
-      "rationale": "Why this failure point was considered",
-      "evidence": {"supporting": [], "contradicting": []},
-      "plausibility": "high|medium|low"
-    }
-  ],
-  "pathCoverageFindings": [
-    {
-      "nodeId": "N1",
-      "status": "covered|partially_covered|uncovered",
-      "findings": "Coverage finding",
-      "followUpNeeded": ["Needed follow-up"]
-    }
-  ],
-  "failurePointsEvaluation": [
-    {
-      "failurePointId": "FP1 or AFP1",
-      "description": "Failure point description",
-      "verificationLevel": "speculation|indirect|direct|verified",
-      "refutationStatus": "unrefuted|partially_refuted|refuted",
-      "remainingUncertainty": ["Remaining uncertainty"]
-    }
-  ],
-  "conclusion": {
-    "confirmedFailurePoints": [
-      {"failurePointId": "FP1", "status": "confirmed|probable|possible", "originalCheckStatus": "retained|added_by_verifier|null"}
-    ],
-    "failurePointRelationships": [
-      {"from": "FP1", "to": "FP2", "relationship": "independent|upstream_of|downstream_of|amplifies|same_boundary"}
-    ],
-    "finalStatus": "ready_for_solution|needs_more_investigation",
-    "coverageAssessment": "sufficient|partial|insufficient",
-    "statusRationale": "Rationale for status and coverage level",
-    "recommendedVerification": ["Additional verification needed to confirm conclusion"]
-  },
-  "verificationLimitations": ["Limitations of this verification process"]
-}
+{"investigationReview":{"originalFailurePointCount":3,"coverageAssessment":"sufficient|partial|insufficient","identifiedGaps":["Perspectives overlooked in investigation"]},"triangulationSupplements":[{"source":"Additional information source investigated","findings":"Content discovered","impactOnFailurePoints":"Impact on existing failure points"}],"scopeValidation":{"verified":true,"concerns":["Concerns"]},"externalResearch":[{"query":"Search query used","source":"Information source","findings":"Related information discovered","impactOnFailurePoints":"Impact on failure points"}],"additionalFailurePoints":[{"id":"AFP1","description":"Additional failure point description","rationale":"Why this failure point was considered","evidence":{"supporting":[],"contradicting":[]},"plausibility":"high|medium|low"}],"pathCoverageFindings":[{"nodeId":"N1","status":"covered|partially_covered|uncovered","findings":"Coverage finding","followUpNeeded":["Needed follow-up"]}],"failurePointsEvaluation":[{"failurePointId":"FP1 or AFP1","description":"Failure point description","verificationLevel":"speculation|indirect|direct|verified","refutationStatus":"unrefuted|partially_refuted|refuted","remainingUncertainty":["Remaining uncertainty"]}],"conclusion":{"confirmedFailurePoints":[{"failurePointId":"FP1","status":"confirmed|probable|possible","originalCheckStatus":"retained|added_by_verifier|null"}],"failurePointRelationships":[{"from":"FP1","to":"FP2","relationship":"independent|upstream_of|downstream_of|amplifies|same_boundary"}],"finalStatus":"ready_for_solution|needs_more_investigation","coverageAssessment":"sufficient|partial|insufficient","statusRationale":"Rationale for status and coverage level","recommendedVerification":["Additional verification needed to confirm conclusion"]},"verificationLimitations":["Limitations of this verification process"]}
 ```
 
 ## Completion Criteria

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

@@ -141,20 +141,38 @@ Rules:
 - Record the mapping in the `UI Spec Component -> Task Mapping` table from the plan template.
 - Mark components with no covering task as `gap` with justification and user confirmation before approval.
 
-### 5b. Map Runtime Boundaries to Tasks
+### 5b. Map Reference Contract Values to Tasks
 
-When implementation crosses runtime, process, deployment, or service boundaries, create a `Connection Map`.
+After Design-to-Plan Traceability is complete, create a `Reference Contract Values` table when any traced Design Doc item contains a binding observable value the implementation must reproduce exactly. When the Design Doc has an `Observable Contract Values` table, use that table as the primary source and copy each applicable row into the work plan.
+
+Qualifying observable values:
+- `structure-order`: column sets, field sets, label sets, or display order
+- `derived-display`: display value derived from another field, lookup, state, or configuration
+- `state-lifecycle-negative`: condition where persisted, restored, cached, or derived state must stay unused
+
+For each qualifying value:
+1. Record the Design Doc path and section.
+2. Classify the Contract Type using exactly one value above.
+3. Copy the Required Observable Value verbatim from the Design Doc. Preserve field names, labels, order, and conditions.
+4. Map it to the task IDs that implement or verify the value.
+5. Mark `covered` when concrete task IDs cover the value. Mark `gap` only when no concrete task covers it, set Covered By Task(s) to `-`, add justification in Notes, and flag it for user confirmation before plan approval.
+
+Serialized boundaries belong in the Connection Map. ADR-derived structural decisions belong in ADR Bindings. When a value qualifies both as an observable value and as a serialized boundary, record it in the Connection Map and omit a duplicate Reference Contract Values row.
+
+### 5c. Map Runtime Boundaries to Tasks
+
+When implementation crosses runtime, process, deployment, or service boundaries, or when a value is serialized and parsed within one runtime, create a `Connection Map`.
 
 A boundary qualifies only when all of the following hold:
-- The two sides run in separate processes, services, runtimes, or deployed artifacts.
-- A serialized contract crosses the boundary, such as HTTP, RPC, event payload, queue message, or webhook payload.
-- A failure on one side creates an observable signal on the other side, such as a status code, timeout, missing field, dropped message, or persisted row.
+- Two sides exchange a value through a boundary. This includes separate processes, services, runtimes, or deployed artifacts, and same-runtime serialized media such as query strings, route parameters, form posts, CLI arguments, environment variables, config entries, message payloads, storage keys, or files.
+- Producer and consumer depend on a shared representation or parse rule.
+- A mismatch creates an observable signal, such as a status code, timeout, missing field, dropped message, invalid route state, parse failure, or persisted row difference.
 
-Map only boundaries satisfying all three qualifications above: separate runtime, serialized contract, and observable cross-side signal.
+Map only boundaries satisfying all three qualifications above.
 
-For each boundary, record the caller/producer, callee/consumer, expected signal, and covering tasks in the `Connection Map` table.
+For each boundary, record the caller/producer, callee/consumer, serialized format, consumer parse rule, expected signal, and covering tasks in the `Connection Map` table. Serialized boundaries must have concrete Serialized Format and Consumer Parse Rule values. Use `-` only for non-serialized external signals where the Expected Signal fully captures the contract.
 
-### 5c. Map ADR Decisions to Tasks
+### 5d. Map ADR Decisions to Tasks
 
 When ADRs are provided as input or listed in a Design Doc's "Prerequisite ADRs" section, create an `ADR Bindings` table before finalizing tasks.
 
@@ -177,7 +195,7 @@ Mapping rules:
 - Acceptance criteria and required user-visible behaviors belong in `Design-to-Plan Traceability`; `ADR Bindings` covers structural implementation constraints.
 - If an ADR decision constrains the design but no task covers it, add a justified gap and flag it for user confirmation before plan approval.
 
-### 5d. Build Failure Mode Checklist
+### 5e. Build Failure Mode Checklist
 
 Populate the plan template's `Failure Mode Checklist` before finalizing tasks. Enumerate all eight domain-independent categories, mark whether each applies, and list the task IDs that cover applicable categories. Keep category names generic and put project-specific details in task descriptions or notes.
 
@@ -390,6 +408,9 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
   - [ ] Scope-boundary items mapped explicitly when the Design Doc defines protected no-change areas
   - [ ] Covered By Task(s) uses only normalized task IDs
   - [ ] No unjustified `gap` entries remain
+- [ ] Reference Contract Values table completed when binding observable values appear in traced Design Doc items
+  - [ ] Each row mapped to covering task(s) or justified `gap`
+  - [ ] No unjustified `gap` entries remain
 - [ ] ADR Bindings table completed when ADRs are provided or listed in Design Doc prerequisites
   - [ ] ADR references resolved with exact path or single `docs/adr/ADR-XXXX-*.md` match
   - [ ] Each binding row has one valid Axis value

package/package.json

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