TechSpokes · sergeliatko · Sep 3, 2026 · Sep 3, 2026
@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [v0.4.1] - 2026-09-03
+
+### Changed
+
+- `page-refresh-brief@2.0.1` now performs the blocking target-page technical precheck before result inspection and acquires target and comparison content only after the precheck passes.
+- Public guidance now distinguishes readiness failures, execution-time required-evidence failures, and successful completed-empty evidence, with a constrained `seo-diagnostic/v1` recovery shape for incomplete execution.
+- Automated content and quality scores now require observation-level review and conflict reconciliation before they can support a conclusion.
+- Catalog, package, plugin, and current-version identities advance to `0.4.1` without changing result-contract versions.
+
+### Added
+
+- Focused behavior scenarios for precheck order, structurally unavailable required evidence, and score-versus-observation conflicts.
+- A contract-valid incomplete diagnostic fixture that records remaining valid evidence, prohibited claims, a recovery route, and a resume condition.
+
 ## [v0.4.0] - 2026-09-03
 
 ### Added

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

@@ -1,7 +1,7 @@
 {
   "schema_version": 2,
   "id": "page-refresh-brief",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "title": "Page Refresh Brief",
   "summary": "Diagnose whether one page should be refreshed, consolidated, preserved, or routed to another intervention, then prepare a verification-ready brief.",
   "primary_domain": "page",
@@ -31,13 +31,13 @@
       "scope": {
         "unit": "query",
         "maximum": 3,
-        "guidance": "Inspect no more than three representative queries needed to distinguish intent and page role."
+        "guidance": "After the blocking target-page precheck passes, inspect no more than three representative queries needed to distinguish intent and page role."
       },
       "completion_without": {
         "allowed": false,
         "limitation": "The method cannot support a search-intent or result-pattern diagnosis without current result evidence."
       },
-      "fallback": "Return an incomplete diagnostic and do not prescribe a content intervention."
+      "fallback": "If execution passed readiness but cannot produce result evidence for the relevant input, return a constrained incomplete diagnostic with the failure class, unresolved question, valid remaining observations, prohibited claims, recovery route, and resume condition; defer disposition and emit no implementation handoff."
     },
     {
       "capability": "page-metadata",
@@ -50,7 +50,7 @@
       "scope": {
         "unit": "page",
         "maximum": 1,
-        "guidance": "Inspect metadata for the one target page."
+        "guidance": "Inspect identification, canonicalization, and observable indexability directives for the one target page during the blocking precheck."
       },
       "completion_without": {
         "allowed": false,
@@ -69,7 +69,7 @@
       "scope": {
         "unit": "page",
         "maximum": 1,
-        "guidance": "Inspect blocking technical signals for the one target page before content comparison."
+        "guidance": "Inspect observable access, crawl, rendering, redirect, status, and indexability signals for the one target page before result inspection or content comparison."
       },
       "completion_without": {
         "allowed": false,
@@ -89,7 +89,7 @@
       "scope": {
         "unit": "page",
         "maximum": 4,
-        "guidance": "Read the target and no more than three representative comparison pages."
+        "guidance": "Only after the blocking target-page precheck passes, read the target and no more than three representative comparison pages."
       },
       "completion_without": {
         "allowed": false,
@@ -128,20 +128,20 @@
       "instruction": "Inspect current runtime cost and authorization for page retrieval, result inspection, and comparison."
     },
     {
-      "id": "inspect-serp",
-      "instruction": "Inspect a bounded current result set to identify observed intent, result types, and viable page patterns."
+      "id": "inspect-target",
+      "instruction": "First inspect observable access, crawl, rendering, redirect, status, canonicalization, and indexability directives or signals for the target. If a blocking signal makes result comparison misleading, stop before inspect-serp and return the supported technical conclusion as a completed bounded diagnostic without claiming first-party index state. Only after the precheck passes may the method acquire the target content and continue comparison."
     },
     {
-      "id": "inspect-target",
-      "instruction": "Collect observable page content, metadata, and blocking technical signals while recording preservation candidates."
+      "id": "inspect-serp",
+      "instruction": "After the target precheck passes, inspect a bounded current result set for no more than three representative queries to identify observed intent, result types, and viable page patterns."
     },
     {
       "id": "compare-pages",
       "instruction": "Compare the target with representative results and relevant site pages without treating competitor phrasing as a drafting template."
     },
     {
       "id": "classify-gaps",
-      "instruction": "Classify supported causes across technical access, site role, intent, planning, content, authority, and operational evidence."
+      "instruction": "Classify supported causes across technical access, site role, intent, planning, content, authority, and operational evidence. Treat every automated content or quality score as an evidence input rather than an editorial verdict: inspect its underlying observations, reconcile material conflicts with independently observed page evidence, and state unresolved discrepancies before reporting a score-derived conclusion."
     },
     {
       "id": "produce-brief",
@@ -152,16 +152,20 @@
     "The diagnosis records current page evidence and result-page conditions.",
     "Every proposed change or preservation constraint links to an observation or explicit user requirement.",
     "Competing technical, strategic, authority, and operational explanations are considered before prescribing content.",
-    "First-party performance claims appear only when supplied or returned by an authorized source."
+    "First-party performance claims appear only when supplied or returned by an authorized source.",
+    "Automated scores support conclusions only when their underlying observations were inspected and material conflicts were reconciled or recorded as unresolved."
   ],
   "stop_conditions": [
-    "Stop content diagnosis when a blocking access or indexing signal makes page comparison misleading.",
-    "Stop before paid result inspection when authorization is insufficient.",
+    "Stop before inspect-serp when an observed blocking access, crawl, or indexability signal makes page comparison misleading; sufficient blocker evidence supports a completed bounded technical diagnostic even though comparison did not begin.",
+    "Treat unmet authorization, availability, input, parameter, or budget requirements as readiness failures: stop before starting the affected paid or protected evidence step and report the precise prerequisite.",
+    "Treat a capability that passed readiness but could not produce required evidence for the relevant input as an execution-time evidence failure: return a constrained incomplete diagnostic with defer disposition and no implementation handoff.",
+    "Treat a successfully completed capability with no observations as completed empty evidence rather than as an execution failure.",
     "Return an incomplete diagnostic when the page or required market context cannot be resolved."
   ],
   "completion_criteria": [
     "The supported intervention and disposition are explicit.",
     "The diagnostic distinguishes observations, interpretations, competing explanations, and unknowns.",
+    "An execution-time required-evidence failure identifies the exact gap and failure class, supported and unknown layers, valid remaining evidence, prohibited conclusions or interventions, recovery route, resume condition, defer disposition, and omitted implementation handoff.",
     "Any implementation handoff is self-contained and contains no finished copy.",
     "Verification criteria protect useful current material and test required changes."
   ],

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

@@ -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.4.0
-npm run release:verify-assets -- v0.4.0
+npm run package -- v0.4.1
+npm run release:verify-assets -- v0.4.1
 ```
 
 Use the intended version tag rather than retaining an older release example after the package version changes.
@@ -45,7 +45,7 @@ Report a successful `npm run validate` result as structural or evaluation-regist
 
 `tests/evals/cases.json` is the machine-discoverable registry. Every scenario heading must be registered, and every required segment must have at least one case.
 
-`tests/fixtures/contracts/cases.json` registers valid and intentionally invalid JSON instances assessed by catalog validation. The result cases cover a non-empty opportunity set, completed empty opportunity and diagnostic results, a diagnostic with issues, an incomplete diagnostic with a precise stop reason, a self-contained implementation handoff, and a content-question review with ordered supplied questions, separate supplemental questions, readable source variants, human escalations, and completion behavior. Negative cases preserve legacy unresolved-evidence checks and reject unsupported dispositions, missing handoff context, mismatched source payloads, missing source material, missing revision recommendations, blocking escalations in complete reviews, and incomplete reviews without stop reasons. Catalog and recipe cases prove rejection of unknown fields, unsupported schema versions, uncontrolled capability and scope values, unknown steps and result contracts, invalid evidence source and use classes, missing conditional predicates, invalid bounds, and ambiguous output composition. The registry and its source instances remain under `tests/` and are excluded from release archives and the server projection.
+`tests/fixtures/contracts/cases.json` registers valid and intentionally invalid JSON instances assessed by catalog validation. The result cases cover a non-empty opportunity set, completed empty opportunity and diagnostic results, a diagnostic with issues, an incomplete diagnostic with a precise stop reason, a constrained incomplete diagnostic for structurally unavailable required evidence, a self-contained implementation handoff, and a content-question review with ordered supplied questions, separate supplemental questions, readable source variants, human escalations, and completion behavior. Negative cases preserve legacy unresolved-evidence checks and reject unsupported dispositions, missing handoff context, mismatched source payloads, missing source material, missing revision recommendations, blocking escalations in complete reviews, and incomplete reviews without stop reasons. Catalog and recipe cases prove rejection of unknown fields, unsupported schema versions, uncontrolled capability and scope values, unknown steps and result contracts, invalid evidence source and use classes, missing conditional predicates, invalid bounds, and ambiguous output composition. The registry and its source instances remain under `tests/` and are excluded from release archives and the server projection.
 
 After a substantial instruction change, run fresh-context agent evaluations against representative fixtures. Give each evaluator only the installed runtime tree plus the prompt and test facts needed for its case. Record whether the output satisfied the invariants; do not count an evaluator's agreement with the prose as execution evidence.
 

@@ -1,5 +1,5 @@
 # Version
 
-Current version: `0.4.0`.
+Current version: `0.4.1`.
 
 This version applies to the portable skill and plugin packages. Catalog and recipe definitions have independent versions described in [Releasing](RELEASING.md).
@@ -0,0 +1,27 @@
+# SEO Agent Tools v0.4.1
+
+## [v0.4.1]
+
+This focused defect-correction release updates the portable page-refresh method without adding capabilities, provider behavior, persistent execution, finished content writing, or a new result-contract version.
+
+The public contract versions are:
+
+- portable skill and plugin packages: `0.4.1`;
+- catalog: `0.4.1`;
+- recipe schema: `2`;
+- page-refresh recipe: `page-refresh-brief@2.0.1`;
+- content-production recipe: `content-production-workflow@1.1.0`;
+- four other seed recipes: `2.0.0` each;
+- result contracts: `content-question-review/v1`, `seo-opportunity-set/v1`, `seo-diagnostic/v1`, and `seo-implementation-handoff/v1`.
+
+`page-refresh-brief@2.0.1` preserves its stable step identifiers and now orders `inspect-target` before `inspect-serp`. It performs observable access, crawl, rendering, redirect, status, canonicalization, and indexability-directive checks first. A supported blocking signal stops result inspection and can complete a bounded technical diagnostic without claiming first-party index state. The method still inspects no more than three representative result queries after the precheck passes.
+
+The guidance distinguishes a readiness failure before evidence execution, an execution-time failure after readiness passed, and a successful completed-empty result. An execution-time required-evidence failure uses the existing `seo-diagnostic/v1` fields to preserve valid observations, supported findings, unknown layers, prohibited conclusions, a recovery route, a resume condition, `defer` disposition, and an omitted implementation handoff.
+
+Automated content and quality scores remain evidence inputs rather than editorial verdicts. Agents must inspect underlying observations, reconcile material conflicts with independent page evidence, and disclose unresolved discrepancies. A score alone cannot support ranking, traffic, accuracy, intent-match, or content-intervention claims.
+
+The release publishes three runtime archives plus `seo-agent-tools-catalog-v0.4.1.json` and `seo-agent-tools-catalog-manifest-v0.4.1.json`. `SHA256SUMS` covers all five assets.
+
+## Validation
+
+The exact release candidate passed structural and evaluation-registry validation. Separate fresh-context evaluators passed every named invariant for blocking target precheck order, the constrained incomplete diagnostic after execution-time evidence failure, and automated-score conflict handling. A regression evaluator also confirmed the query bound, readiness, completed-empty, evidence-source, claim, and conditional-handoff boundaries at the public source level; runtime settlement remains a connected-server verification concern. Deterministic package replay, release-asset disclosure and provenance checks, and the release preflight for `v0.4.1` also passed before publication.
@@ -1,6 +1,6 @@
 {
   "name": "seo-agent-tools",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": true,
   "type": "module",
   "scripts": {

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

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

@@ -36,8 +36,8 @@ A result contract makes the decision reusable by defining the exact subject, sup
 3. Choose the shortest route that can answer the question with sufficient evidence: direct analysis, recipe execution, content-quality diagnosis, implementation handoff, or verification.
 4. Before any paid or approval-gated call, obtain current price and balance information when the server exposes it, state the expected call scope, and follow the user's authorization boundary.
 5. Confirm that the selected recipe's evidence plan, primary result contract, and any conditional result contracts are interpretable before collecting evidence. Use contracts embedded in the full server-resolved recipe or obtained through a discovered server schema surface. Never coerce an unfamiliar contract into a locally documented family; stop for unsupported result-contract skew when the exact shape is unavailable or incompatible.
-6. Execute only the selected path. Resolve each evidence entry by its `server`, `client`, or `user` source, apply its required, conditional, or fallback use, respect the provider-neutral evidence bound, and follow its declared completion-without behavior. Load full recipe definitions only after selecting a candidate, and stop when required evidence is unavailable.
-7. Separate observed facts from interpretations. Preserve source, subject, observation time, locale, device, query, and other conditions needed to understand what each item of evidence means.
+6. Execute only the selected path. Resolve each evidence entry by its `server`, `client`, or `user` source, apply its required, conditional, or fallback use, respect the provider-neutral evidence bound, and follow its declared completion-without behavior. Load full recipe definitions only after selecting a candidate. Distinguish a readiness failure before evidence execution, an execution-time failure after readiness passed, and a successful completed-empty result; report each through the selected recipe and result contract without inventing evidence.
+7. Separate observed facts from interpretations. Preserve source, subject, observation time, locale, device, query, and other conditions needed to understand what each item of evidence means. Treat an automated content or quality score as one evidence input, inspect its underlying observations, and reconcile or disclose material conflicts before using it in a conclusion.
 8. Return the applicable result contract. If another agent must implement the decision, add a handoff that specifies outcomes, constraints, acceptance criteria, and verification without drafting the finished content.
 9. Verify the result against the original decision and completion criteria. Report unavailable checks and unresolved uncertainty instead of implying completion.