Preserve required content SEO metadata in workflow

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [v0.3.2] - 2026-09-03
+
+### Changed
+
+- `content-production-workflow@1.0.1` now requires a canonical document with a resolvable intended SEO title and meta description before its required content SEO analysis.
+- Recipe guidance now preserves separately held values through explicit document metadata while continuing to accept recognized opening Markdown YAML front matter or a complete HTML document head without duplicate metadata.
+- Missing required metadata is now an explicit incomplete-input condition; agents must not submit body-only content, infer a title from the H1, or invent a meta description.
+- Catalog `0.3.1` and registered behavior evidence cover the corrected metadata-preservation contract without changing workflow steps, capabilities, bounds, result contracts, or runtime-provider behavior.
+
 ## [v0.3.1] - 2026-08-15
 
 ### Changed

catalog/catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "catalog_version": "0.3.0",
+  "catalog_version": "0.3.1",
   "catalog_schema": "catalog/schemas/catalog.schema.json",
   "recipe_schema": "catalog/schemas/recipe.schema.json",
   "supported_recipe_schema_versions": [

catalog/recipes/content-production-workflow.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 2,
   "id": "content-production-workflow",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",
@@ -129,13 +129,13 @@
       "scope": {
         "unit": "document",
         "maximum": 1,
-        "guidance": "Maintain one canonical Markdown, HTML, or text document with explicit metadata provenance and a stable client-owned identity."
+        "guidance": "Maintain one canonical Markdown, HTML, or text document with a stable client-owned identity, body content, and a resolvable intended SEO title and meta description for the required content SEO analysis. Preserve separately held values as explicit document metadata, or retain recognized opening Markdown YAML front matter or a complete HTML document head."
       },
       "completion_without": {
         "allowed": false,
-        "limitation": "The method cannot analyze, approve, publish, or verify content without one canonical client-owned document."
+        "limitation": "The method cannot analyze, approve, publish, or verify content without one canonical client-owned document whose format, body, intended SEO title, and intended meta description are resolvable."
       },
-      "fallback": "Return an incomplete handoff and request a canonical document from the responsible content capability."
+      "fallback": "Return an incomplete handoff and request a canonical document from the responsible content capability, identifying any unresolved required body or metadata input."
     },
     {
       "capability": "content-seo-analysis",
@@ -148,11 +148,11 @@
       "scope": {
         "unit": "document",
         "maximum": 1,
-        "guidance": "Evaluate the canonical document once against the supported focus and preserve structural reliability and input limitations."
+        "guidance": "Evaluate the canonical document once against the supported focus only after its format, body, intended SEO title, and intended meta description resolve from explicit document metadata or recognized embedded declarations; preserve structural reliability and input limitations."
       },
       "completion_without": {
         "allowed": false,
-        "limitation": "The method cannot claim that the supplied document received its required focus-specific content review."
+        "limitation": "The method cannot claim that the supplied document received its required focus-specific content review when the focus keyword, document format, document body, intended SEO title, or intended meta description is unresolved."
       },
       "fallback": "Return an incomplete handoff without presenting the document as publication-ready."
     },
@@ -293,11 +293,11 @@
     },
     {
       "id": "prepare-canonical-document",
-      "instruction": "Have a separate client content capability create and edit one canonical document; prefer explicit title and meta-description provenance and keep publishing-only instructions outside analyzed body content."
+      "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 focus-specific review and 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. Run only the conditional quality checks whose result can change revision or approval; do not maximize scores blindly."
     },
     {
       "id": "verify-factual-claims",
@@ -333,17 +333,18 @@
     "Generated variants, third-party estimates, content-analysis scores, and client-supplied snapshots retain their distinct provenance and limitations.",
     "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 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."
   ],
   "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 publication when the canonical document, factual verification, or required approval is incomplete.",
+    "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 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, and canonical artifact identity are recorded.",
-    "Required and selected conditional analyses are evidence-linked, and score conflicts or input limitations are explicit.",
+    "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.",
     "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."

docs/RELEASING.md

@@ -23,14 +23,14 @@ Result contracts use explicit identifiers such as `seo-diagnostic/v1`. Add `v2`
 
 ```bash
 npm run validate
-npm run package -- v0.3.1
-npm run release:verify-assets -- v0.3.1
+npm run package -- v0.3.2
+npm run release:verify-assets -- v0.3.2
 ```
 
 4. Run the repository preflight when the branch and remote state are ready for release.
 
 ```bash
-npm run release:preflight -- v0.3.1
+npm run release:preflight -- v0.3.2
 ```
 
 5. Review `dist/assets/SHA256SUMS`, the three ZIP inventories, and both versioned catalog files under `dist/catalog/`.

docs/TESTING.md

@@ -17,8 +17,8 @@ npm run validate
 When runtime or release behavior changes, also build and verify the intended release candidate:
 
 ```bash
-npm run package -- v0.3.1
-npm run release:verify-assets -- v0.3.1
+npm run package -- v0.3.2
+npm run release:verify-assets -- v0.3.2
 ```
 
 Use the intended version tag rather than retaining an older release example after the package version changes.

docs/VERSION.md

@@ -1,5 +1,5 @@
 # Version
 
-Current version: `0.3.1`.
+Current version: `0.3.2`.
 
 This version applies to the portable skill and plugin packages. Catalog and recipe definitions have independent versions described in [Releasing](RELEASING.md).

docs/releases/v0.3.2.md

@@ -0,0 +1,24 @@
+# SEO Agent Tools v0.3.2
+
+## [v0.3.2]
+
+This patch release tightens the maintained content-production methodology so an orchestrating agent preserves the intended SEO title and meta description with the canonical document before required content SEO analysis.
+
+The public contract versions are:
+
+- portable skill and plugin packages: `0.3.2`;
+- catalog: `0.3.1`;
+- recipe schema: `2`;
+- content-production recipe: `content-production-workflow@1.0.1`;
+- five existing recipes: `2.0.0` each;
+- result contracts: `seo-opportunity-set/v1`, `seo-diagnostic/v1`, and `seo-implementation-handoff/v1`.
+
+The canonical document must now resolve its format, body, intended SEO title, and intended meta description for the required focus-specific content SEO analysis. Separately held title and description values travel as explicit document metadata. Recognized opening Markdown YAML front matter and a complete HTML document head remain accepted embedded sources, so an agent does not duplicate metadata already present in the canonical artifact.
+
+A body-only document is incomplete input when either required metadata value is unresolved. The recipe tells agents to preserve known values, not infer a title from the H1 or generate a replacement meta description. This correction does not add a top-level recipe input, capability, workflow step, evidence source, output field, result contract, provider behavior, or call budget.
+
+The registered behavior case uses generic facts and covers separately held metadata, accepted embedded alternatives, incomplete body-only input, and the prohibition on invented replacements. The release publishes the same three runtime archives plus `seo-agent-tools-catalog-v0.3.2.json` and `seo-agent-tools-catalog-manifest-v0.3.2.json`; the manifest records the exact immutable source commit and source checksums, and `SHA256SUMS` covers all five assets.
+
+## Validation
+
+The exact release candidate passed structural and evaluation-registry validation, deterministic package replay, release-asset disclosure and provenance checks, and the release preflight for `v0.3.2`. The focused content-metadata behavior invariants were also reviewed against the generated full recipe.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-agent-tools",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": true,
   "type": "module",
   "scripts": {

packaging/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "seo-agent-tools",
   "displayName": "SEO Agent Tools",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Evidence-backed SEO analysis, content-production coordination, implementation handoffs, and verification through an SEO MCP server.",
   "author": {
     "name": "TechSpokes"

packaging/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-agent-tools",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Evidence-backed SEO analysis, content-production coordination, implementation handoffs, and verification through an SEO MCP server.",
   "author": {
     "name": "TechSpokes"

tests/evals/cases.json

@@ -175,6 +175,17 @@
         "client and server responsibility confusion"
       ]
     },
+    {
+      "id": "content-seo-canonical-metadata",
+      "kind": "scenario",
+      "fixture": "behavior-scenarios.md",
+      "segment": "content-boundary",
+      "heading": "Content SEO Analysis Preserves Canonical Metadata",
+      "baseline_risks": [
+        "known SEO metadata discarded during orchestration",
+        "body-only document submitted for required analysis"
+      ]
+    },
     {
       "id": "live-publication-verification",
       "kind": "scenario",

tests/fixtures/behavior-scenarios.md

@@ -80,6 +80,16 @@ Expected invariants:
 - User evidence supplies business and editorial context, client capabilities own finished drafting, claim verification, approval, publication, and page reading, and server capabilities supply only their mapped research and analysis evidence.
 - The validated handoff identifies the canonical artifact and evidence records without embedding finished page copy or implying that the SEO server mutated the CMS.
 
+## Content SEO Analysis Preserves Canonical Metadata
+
+Input: The approved draft has a focus keyword, Markdown format and body, an intended SEO title, and an intended meta description. The title and description are held separately from the Markdown body.
+
+Expected invariants:
+
+- The agent treats the focus keyword, document format, document body, resolvable intended SEO title, and resolvable intended meta description as required information for the content SEO analysis.
+- The agent preserves separately held values through explicit document metadata and recognizes opening Markdown YAML front matter or a complete HTML document head as accepted alternatives without requiring duplicate metadata.
+- The agent treats body-only content with unresolved required metadata as incomplete input and neither infers a title from the H1 nor invents a meta description.
+
 ## Post-Publication Verification Requires Live Evidence
 
 Input: The client has a staged snapshot and says the approved article is now public. The last cached page evidence predates publication, and the selected live operations expose a current full-price refresh path.

tests/fixtures/contracts/handoff-content-production-valid.json

@@ -3,7 +3,7 @@
   "contract_id": "seo-implementation-handoff/v1",
   "recipe": {
     "id": "content-production-workflow",
-    "version": "1.0.0"
+    "version": "1.0.1"
   },
   "subject": {
     "content_objective": "Publish one evidence-backed guide for an existing site.",
@@ -24,7 +24,7 @@
       "source": "client-owned canonical document",
       "subject": "canonical document content-guide-1",
       "observed_at": "2026-08-15T10:30:00Z",
-      "observation": "The approved document identity and metadata provenance are recorded without embedding the page body.",
+      "observation": "The approved document identity and the accepted provenance of its resolvable intended SEO title and meta description are recorded without embedding the page body.",
       "limitations": [
         "The validated handoff does not contain the finished content."
       ]
@@ -34,7 +34,7 @@
       "source": "authorized content analysis",
       "subject": "canonical document content-guide-1",
       "observed_at": "2026-08-15T10:45:00Z",
-      "observation": "The required focus-specific review completed and its input limitations are recorded.",
+      "observation": "The required focus-specific review used the canonical body, intended SEO title, and intended meta description, and its input limitations are recorded.",
       "limitations": [
         "The analysis does not prove factual accuracy, ranking impact, or search-engine classifier behavior."
       ]