Add content question review contract

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [v0.4.0] - 2026-09-03
+
+### Added
+
+- The standalone `content-question-review/v1` result contract for ordered approved-question assessments, separate supplemental questions, structured human escalations, and explicit completion state without a legacy evidence-ID graph.
+- Additive reusable `source` and `humanEscalation` definitions supporting readable web, tool, file, and conversation material without changing released envelope requirements.
+- Deterministic positive and negative fixtures covering source variants, typed content payloads, review statuses, revision recommendations, escalation behavior, and incomplete-result stops.
+
+### Changed
+
+- `content-production-workflow@1.1.0` conditionally emits the question review when approved buyer or people-also-ask questions are present, reviews their exact wording and order before publication approval, and keeps generated coverage supplemental.
+- Public guidance now requires bounded autonomous resolution before a self-contained human escalation and preserves final angle, sourcing, quotations, and editorial approval as human or client responsibilities.
+- Catalog `0.4.0` registers the new contract while retaining the legacy diagnostic, opportunity, and implementation-handoff schemas and evidence-ID semantics unchanged.
+
 ## [v0.3.2] - 2026-09-03
 
 ### Changed

README.md

@@ -60,8 +60,8 @@ Node.js 22 is used in CI. The repository has no runtime package dependency.
 ```bash
 npm ci
 npm run validate
-npm run package -- v0.3.1
-npm run release:verify-assets -- v0.3.1
+npm run package -- v0.4.0
+npm run release:verify-assets -- v0.4.0
 ```
 
 `npm run validate` checks catalog structure, runtime skill structure, documentation links, behavioral fixtures, and maintenance contracts. Packaging creates deterministic standalone, Codex plugin, and Claude plugin archives plus versioned catalog and manifest assets under `dist/assets/`. Release verification checks all five assets and rebuilds them to prove byte identity.

catalog/catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "catalog_version": "0.3.1",
+  "catalog_version": "0.4.0",
   "catalog_schema": "catalog/schemas/catalog.schema.json",
   "recipe_schema": "catalog/schemas/recipe.schema.json",
   "supported_recipe_schema_versions": [
@@ -67,6 +67,7 @@
     "serp-results"
   ],
   "result_contracts": {
+    "content-question-review/v1": "catalog/schemas/content-question-review.v1.schema.json",
     "seo-diagnostic/v1": "catalog/schemas/seo-diagnostic.v1.schema.json",
     "seo-implementation-handoff/v1": "catalog/schemas/seo-implementation-handoff.v1.schema.json",
     "seo-opportunity-set/v1": "catalog/schemas/seo-opportunity-set.v1.schema.json"

catalog/recipes/content-production-workflow.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 2,
   "id": "content-production-workflow",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "title": "Content Production Workflow",
   "summary": "Plan, evaluate, publish, and verify one bounded existing-site content artifact while preserving business context, factual limits, approval, freshness, and lifecycle ownership.",
   "primary_domain": "content",
@@ -25,6 +25,7 @@
       "use": "required",
       "steps": [
         "acquire-context",
+        "analyze-document",
         "approve-outline",
         "prepare-publication-handoff",
         "record-lifecycle-decision"
@@ -285,19 +286,19 @@
     },
     {
       "id": "research-before-outline",
-      "instruction": "Use supplied site evidence and one bounded research burst before outlining only when candidate subtopics, intent, page type, or priority can materially change."
+      "instruction": "Use supplied site evidence and one bounded research burst before outlining only when candidate subtopics, intent, page type, priority, or keyword and people-also-ask evidence can materially challenge the proposed page scope, required questions, or site routing before the brief is approved."
     },
     {
       "id": "approve-outline",
-      "instruction": "Have the client prepare an outline that links material sections, proof needs, and internal-link needs to supported context or evidence, then obtain the required approval."
+      "instruction": "Have the client prepare an outline that links material sections, proof needs, internal-link needs, and proposed buyer or people-also-ask questions to supported context or evidence. Resolve material research challenges, then obtain approval and preserve the exact wording and order of the approved questions."
     },
     {
       "id": "prepare-canonical-document",
       "instruction": "Have a separate client content capability create and edit one canonical document. Preserve the intended SEO title and meta description with it: pass separately held values as explicit document metadata, or retain recognized opening Markdown YAML front matter or a complete HTML document head. Do not reduce a complete draft to body-only content when the required metadata is already known, and keep publishing-only instructions outside analyzed body content."
     },
     {
       "id": "analyze-document",
-      "instruction": "Run the required content SEO analysis only with a canonical document that resolves the intended SEO title and meta description alongside its format and body for the supported focus. Treat missing required metadata as incomplete input rather than omitting it, inferring it from the H1, or inventing replacement values. Run only the conditional quality checks whose result can change revision or approval; do not maximize scores blindly."
+      "instruction": "Run the required content SEO analysis only with a canonical document that resolves the intended SEO title and meta description alongside its format and body for the supported focus. Treat missing required metadata as incomplete input rather than omitting it, inferring it from the H1, or inventing replacement values. When the approved context contains buyer or people-also-ask questions, review every exact supplied question in its original order against the draft, cite the governing brief and relevant draft passage or absence directly in each assessment, and keep independently discovered questions in the separate supplemental collection. Use generated query coverage only as a supplemental signal. Resolve retrievable uncertainty through bounded evidence before creating a structured human escalation for a material issue that still requires intent, authority, private knowledge, approval, ownership, or a business or editorial tradeoff. Run only the conditional quality checks whose result can change revision or approval; do not maximize scores blindly."
     },
     {
       "id": "verify-factual-claims",
@@ -309,7 +310,7 @@
     },
     {
       "id": "confirm-approval",
-      "instruction": "Obtain the required human or client approval for the exact canonical artifact and publication target."
+      "instruction": "Obtain the required human or client approval for the exact canonical artifact and publication target only after any blocking supplied-question review or human escalation is resolved. Final angle, sourcing, quotations, and editorial approval remain human or client responsibilities."
     },
     {
       "id": "publish-content",
@@ -325,7 +326,7 @@
     },
     {
       "id": "produce-handoff",
-      "instruction": "Return the evidence-linked implementation handoff with publication verification, limitations, completion state, and remaining lifecycle ownership."
+      "instruction": "Return the evidence-linked implementation handoff with publication verification, limitations, completion state, and remaining lifecycle ownership. When approved buyer or people-also-ask questions were supplied, also return the standalone question review with supplied and supplemental questions kept separate and with any unresolved material escalation packaged as a self-contained request."
     }
   ],
   "evidence_requirements": [
@@ -334,17 +335,20 @@
     "Material factual claims have separate verification evidence or an explicit blocking record; content-analysis scores never satisfy factual verification.",
     "Publication and live verification are client and server evidence respectively; a staged snapshot cannot establish production equivalence.",
     "The canonical page body remains a client-owned artifact and is not embedded in the validated handoff.",
-    "The canonical document evidence resolves the document format, body content, intended SEO title, and intended meta description for the required content SEO analysis. The title and description come from explicit document metadata, recognized opening Markdown YAML front matter, or a complete HTML document head; a body-only document is incomplete when either value is unresolved."
+    "The canonical document evidence resolves the document format, body content, intended SEO title, and intended meta description for the required content SEO analysis. The title and description come from explicit document metadata, recognized opening Markdown YAML front matter, or a complete HTML document head; a body-only document is incomplete when either value is unresolved.",
+    "Each approved buyer or people-also-ask question retains its exact wording and original order, cites the governing brief source and relevant draft passage or absence directly, and remains separate from supplemental generated questions."
   ],
   "stop_conditions": [
     "Stop or narrow before paid research when the audience, market, page role, factual constraints, or approval ownership is materially ambiguous.",
     "Stop before a paid step when current authorization or budget is insufficient for the selected bounded evidence path.",
     "Stop before content SEO analysis when the focus keyword, document format, document body, intended SEO title, or intended meta description is unresolved, and stop publication when the canonical document, factual verification, or required approval is incomplete.",
+    "Return the question review as incomplete when a material supplied-question assessment or blocking human escalation remains unresolved after bounded autonomous resolution.",
     "Return an incomplete handoff when the published page or required live verification evidence cannot be obtained."
   ],
   "completion_criteria": [
     "The business and editorial context, research bounds, approved outline, canonical artifact identity, document format, and provenance of its resolvable intended SEO title and meta description are recorded.",
     "The required content SEO analysis uses the canonical body and intended metadata for the supported focus; selected conditional analyses are evidence-linked, and score conflicts or input limitations are explicit.",
+    "When approved questions are present, every exact supplied question is assessed in its original order with direct human-readable sources and any scoped revision recommendation, supplemental questions remain separate, and no blocking review or escalation remains unresolved.",
     "Material factual claims are separately verified or the result stops incomplete.",
     "Approval, client-owned publication, live page reading, metadata, and technical verification are recorded.",
     "The handoff is self-contained, contains no finished page body, and identifies lifecycle ownership and any remaining checks."
@@ -353,6 +357,11 @@
     {
       "id": "seo-implementation-handoff/v1",
       "role": "primary"
+    },
+    {
+      "id": "content-question-review/v1",
+      "role": "conditional",
+      "condition": "Emit when the approved content context contains buyer or people-also-ask questions."
     }
   ],
   "bounds": {

catalog/schemas/content-question-review.v1.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/TechSpokes/seo-agent-tools/catalog/schemas/content-question-review.v1.schema.json",
+  "title": "Content Question Review v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contract_id",
+    "subject",
+    "reviewed_at",
+    "questions",
+    "supplemental_questions",
+    "human_escalations",
+    "completion"
+  ],
+  "properties": {
+    "contract_id": {
+      "const": "content-question-review/v1"
+    },
+    "subject": {
+      "type": "object",
+      "minProperties": 1
+    },
+    "reviewed_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/questionReview"
+      }
+    },
+    "supplemental_questions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/questionReview"
+      }
+    },
+    "human_escalations": {
+      "type": "array",
+      "items": {
+        "$ref": "shared-evidence.schema.json#/$defs/humanEscalation"
+      }
+    },
+    "completion": {
+      "$ref": "#/$defs/completion"
+    }
+  },
+  "$defs": {
+    "questionReview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "question",
+        "status",
+        "reason",
+        "sources"
+      ],
+      "properties": {
+        "question": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "enum": [
+            "answered",
+            "partially_answered",
+            "not_answered",
+            "unable_to_determine"
+          ]
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sources": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "shared-evidence.schema.json#/$defs/source"
+          }
+        },
+        "recommendation": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "enum": [
+                  "partially_answered",
+                  "not_answered"
+                ]
+              }
+            },
+            "required": [
+              "status"
+            ]
+          },
+          "then": {
+            "properties": {
+              "recommendation": true
+            },
+            "required": [
+              "recommendation"
+            ]
+          }
+        }
+      ]
+    },
+    "completion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "complete",
+            "incomplete"
+          ]
+        },
+        "stop_reason": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "incomplete"
+              }
+            },
+            "required": [
+              "status"
+            ]
+          },
+          "then": {
+            "properties": {
+              "stop_reason": true
+            },
+            "required": [
+              "stop_reason"
+            ]
+          },
+          "else": {
+            "not": {
+              "required": [
+                "stop_reason"
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+}