A5-R3-R7-R2B adaptive semantic front matter + structural heading identity

core/generation_runner.py

@@ -1755,6 +1755,40 @@ class GenerationRunner:
         if not expected or expected != actual:
             raise RuntimeError(f"english_section_integrity_seal_mismatch:{section_title}")
 
+    @staticmethod
+    def _apply_quantitative_front_matter_contract(mode: str, topic: str, keywords: str, data_metadata: dict):
+        """Preserve original research seeds through retrieval and reasoning.
+
+        Reader-facing AMJ title/keywords are reconciled only after the empirical
+        scope and completed manuscript are frozen.
+        """
+        return str(topic or "").strip(), str(keywords or "").strip()
+
+    @staticmethod
+    def _canonical_quantitative_front_matter_keywords(mode: str, candidate_keywords, data_metadata: dict):
+        """Normalize model-generated keywords without replacing semantic context."""
+        values = []
+        seen = set()
+        for item in candidate_keywords or []:
+            value = re.sub(r"\s+", " ", str(item or "")).strip()
+            key = value.casefold()
+            if value and key not in seen:
+                values.append(value)
+                seen.add(key)
+        return values
+
+    @staticmethod
+    def _replace_title(manuscript: str, title: str) -> str:
+        value = str(manuscript or "")
+        rendered = re.sub(r"\s+", " ", str(title or "")).strip()
+        if not rendered:
+            return value
+        updated, count = re.subn(r"(?m)^#\s+.+$", f"# {rendered}", value, count=1)
+        if count == 1:
+            return updated
+        logging.warning("Manuscript title heading missing during final reconciliation; reconstructing canonical H1 instead of failing generation.")
+        return f"# {rendered}\n\n" + value.lstrip("\n")
+
     @staticmethod
     def _replace_keywords(manuscript: str, keywords) -> str:
         value = str(manuscript or '')
@@ -1764,10 +1798,19 @@ class GenerationRunner:
             rendered = str(keywords or '').strip()
         pattern = re.compile(r'(?ms)(^##\s+Keywords\s*$\n)(.*?)(?=^#\s+[^#].*?$|\Z)')
         matches = list(pattern.finditer(value))
-        if len(matches) != 1:
-            raise RuntimeError(f'keywords_heading_count_invalid:{len(matches)}')
-        match = matches[0]
-        return value[:match.start()] + match.group(1) + rendered + '\n\n' + value[match.end():].lstrip('\n')
+        if len(matches) == 1:
+            match = matches[0]
+            return value[:match.start()] + match.group(1) + rendered + '\n\n' + value[match.end():].lstrip('\n')
+        logging.warning("Keywords heading missing or ambiguous during final reconciliation; rebuilding front-matter keyword block without aborting generation | count=%s", len(matches))
+        abstract_pattern = re.compile(r'(?ms)(^##\s+Abstract\s*$\n.*?)(?=^#\s+[^#].*?$|\Z)')
+        abstract_match = abstract_pattern.search(value)
+        block = f"## Keywords\n{rendered}\n\n"
+        if abstract_match:
+            return value[:abstract_match.end()].rstrip() + "\n\n" + block + value[abstract_match.end():].lstrip("\n")
+        title_match = re.search(r'(?m)^#\s+.+$', value)
+        if title_match:
+            return value[:title_match.end()] + "\n\n" + block + value[title_match.end():].lstrip("\n")
+        return block + value.lstrip("\n")
 
     @staticmethod
     def _section_is_complete(tasks, completed_display_names, section_key: str) -> bool:
@@ -3157,8 +3200,37 @@ class GenerationRunner:
                         "Quantitative hypothesis ledger contract advanced; rebuilt locally version=%s",
                         expected_hypothesis_version,
                     )
+                front_contract = dict(data_metadata.get("front_matter_contract") or {})
+                expected_front_version = str(getattr(quant_engine, "FRONT_MATTER_CONTRACT_VERSION", ""))
+                if front_contract.get("version") != expected_front_version:
+                    constructs = dict(data_metadata.get("constructs") or {})
+                    rebuilt_front = quant_engine.build_front_matter_contract(
+                        topic, keywords, [
+                            constructs.get("predictor"), constructs.get("mediator"), constructs.get("outcome")
+                        ]
+                    )
+                    if rebuilt_front:
+                        data_metadata["front_matter_contract"] = rebuilt_front
+                    else:
+                        logging.warning("Quantitative front-matter semantic contract could not be rebuilt; continuing with existing research seeds and degraded final reconciliation.")
+                    prior_translation_sections = dict(state.get("translation_sections") or {})
+                    prior_translation_sections.pop("__front_matter__", None)
+                    state["translation_sections"] = prior_translation_sections
+                    state["translation_complete"] = False
+                    state["package_validated"] = False
+                    logging.warning(
+                        "Quantitative front-matter contract advanced; rebuilt locally version=%s",
+                        expected_front_version,
+                    )
                 state["data_metadata"] = data_metadata
 
+        source_topic, source_keywords = topic, keywords
+        topic, keywords = self._apply_quantitative_front_matter_contract(
+            mode, topic, keywords, data_metadata
+        )
+        state.pop("effective_topic", None)
+        state.pop("effective_keywords", None)
+
         hypothesis_ledger = dict(data_metadata.get("hypothesis_ledger") or {}) if mode == "amj" else {}
         hypothesis_contract = self._hypothesis_contract_directive(hypothesis_ledger)
         if hypothesis_ledger:
@@ -3275,7 +3347,9 @@ class GenerationRunner:
                 working_abstract = self._normalize_hypothesis_ordinal_aliases(
                     working_abstract, hypothesis_ledger
                 )
-            working_keywords = list(working_front.get("keywords") or [])
+            working_keywords = self._canonical_quantitative_front_matter_keywords(
+                mode, list(working_front.get("keywords") or []), data_metadata
+            )
             if not working_abstract or not working_keywords:
                 raise RuntimeError("working_front_matter_missing")
             _, front_fact_rows = self._repair_validate_study_fact_contract(
@@ -3302,7 +3376,9 @@ class GenerationRunner:
                     working_abstract = self._normalize_hypothesis_ordinal_aliases(
                         working_abstract, hypothesis_ledger
                     )
-                working_keywords = list(working_front.get("keywords") or [])
+                working_keywords = self._canonical_quantitative_front_matter_keywords(
+                    mode, list(working_front.get("keywords") or []), data_metadata
+                )
                 _, remaining_front_rows = self._repair_validate_study_fact_contract(
                     mode, agent, quant_engine, working_abstract, data_metadata, section_name="Working Abstract",
                 )
@@ -3523,6 +3599,16 @@ class GenerationRunner:
             self._checkpoint("outline_ready", state, 15)
         else:
             full_draft_en = str(state.get("full_draft_en") or "")
+            if str(data_metadata.get("source_type") or "") == "system_generated" and mode == "amj":
+                full_draft_en = self._replace_title(full_draft_en, topic)
+                canonical_resume_keywords = self._canonical_quantitative_front_matter_keywords(
+                    mode, [], data_metadata
+                )
+                full_draft_en = self._replace_keywords(full_draft_en, canonical_resume_keywords)
+                state["full_draft_en"] = full_draft_en
+                state["working_keywords"] = canonical_resume_keywords
+                if state.get("final_keywords") is not None:
+                    state["final_keywords"] = canonical_resume_keywords
             # JIT text itself is already represented in agent citation state;
             # refs + user literature rebuild a safe RAG baseline on resume.
 
@@ -3589,7 +3675,11 @@ class GenerationRunner:
             )
             state['canonical_concept_ledger'] = canonical_concept_ledger
         working_abstract = str(state.get("working_abstract") or "").strip()
-        working_keywords = list(state.get("working_keywords") or [])
+        working_keywords = self._canonical_quantitative_front_matter_keywords(
+            mode, list(state.get("working_keywords") or []), data_metadata
+        )
+        if working_keywords:
+            state["working_keywords"] = working_keywords
         if working_abstract and not state.get("english_finalized"):
             if hypothesis_ledger:
                 working_abstract = self._normalize_hypothesis_ordinal_aliases(
@@ -3614,7 +3704,9 @@ class GenerationRunner:
                     candidate_abstract = self._normalize_hypothesis_ordinal_aliases(
                         candidate_abstract, hypothesis_ledger
                     )
-                candidate_keywords = list(working_front.get("keywords") or [])
+                candidate_keywords = self._canonical_quantitative_front_matter_keywords(
+                    mode, list(working_front.get("keywords") or []), data_metadata
+                )
                 _, remaining = self._repair_validate_study_fact_contract(
                     mode, agent, quant_engine, candidate_abstract, data_metadata, section_name="Working Abstract",
                 )
@@ -3838,7 +3930,9 @@ class GenerationRunner:
                 working_abstract = self._normalize_hypothesis_ordinal_aliases(
                     working_abstract, hypothesis_ledger
                 )
-            working_keywords = list(working_front.get("keywords") or [])
+            working_keywords = self._canonical_quantitative_front_matter_keywords(
+                mode, list(working_front.get("keywords") or []), data_metadata
+            )
             if not working_abstract or not working_keywords:
                 raise RuntimeError("working_front_matter_missing")
             _, front_fact_rows = self._repair_validate_study_fact_contract(
@@ -3860,7 +3954,9 @@ class GenerationRunner:
                     working_abstract = self._normalize_hypothesis_ordinal_aliases(
                         working_abstract, hypothesis_ledger
                     )
-                working_keywords = list(working_front.get("keywords") or [])
+                working_keywords = self._canonical_quantitative_front_matter_keywords(
+                    mode, list(working_front.get("keywords") or []), data_metadata
+                )
                 _, remaining = self._repair_validate_study_fact_contract(
                     mode, agent, quant_engine, working_abstract, data_metadata, section_name="Working Abstract",
                 )
@@ -4999,7 +5095,9 @@ The previous attempt for this same manuscript unit was rejected by validation. R
                 final_abstract = self._normalize_hypothesis_ordinal_aliases(
                     final_abstract, hypothesis_ledger
                 )
-            final_keywords = list(final_front.get("keywords") or [])
+            final_keywords = self._canonical_quantitative_front_matter_keywords(
+                mode, list(final_front.get("keywords") or []), data_metadata
+            )
             if not final_abstract or not final_keywords:
                 raise RuntimeError("final_front_matter_missing")
             final_front_fact_rows = self._study_fact_violations(
@@ -5026,7 +5124,9 @@ The previous attempt for this same manuscript unit was rejected by validation. R
                     final_abstract = self._normalize_hypothesis_ordinal_aliases(
                         final_abstract, hypothesis_ledger
                     )
-                final_keywords = list(final_front.get("keywords") or [])
+                final_keywords = self._canonical_quantitative_front_matter_keywords(
+                    mode, list(final_front.get("keywords") or []), data_metadata
+                )
                 if not final_abstract or not final_keywords:
                     raise RuntimeError("final_front_matter_missing_after_retry")
                 remaining_final_fact_rows = self._study_fact_violations(
@@ -5052,7 +5152,28 @@ The previous attempt for this same manuscript unit was rejected by validation. R
                     "examples":final_front_fact_rows[:3],
                 })
             state.pop("final_abstract_retry_exhausted", None)
+            final_title = str(topic or "").strip()
+            if mode == "amj" and str(data_metadata.get("source_type") or "") == "system_generated":
+                semantic_contract = dict(data_metadata.get("front_matter_contract") or {})
+                reconciled_front = agent.reconcile_quantitative_reader_front_matter(
+                    topic=source_topic, keywords=source_keywords, contract=semantic_contract,
+                    manuscript=body_only,
+                )
+                candidate_title = re.sub(r"\s+", " ", str(reconciled_front.get("title") or "")).strip()
+                candidate_keywords = self._canonical_quantitative_front_matter_keywords(
+                    mode, list(reconciled_front.get("keywords") or []), data_metadata
+                )
+                if candidate_title:
+                    final_title = candidate_title
+                if 4 <= len(candidate_keywords) <= 6:
+                    final_keywords = candidate_keywords
+                else:
+                    logging.warning(
+                        "Adaptive final keyword reconciliation returned nonpreferred count=%s; preserving validated Final Front Matter keywords.",
+                        len(candidate_keywords),
+                    )
             full_draft_en = replace_abstract(full_draft_en, final_abstract)
+            full_draft_en = self._replace_title(full_draft_en, final_title)
             full_draft_en = self._replace_keywords(full_draft_en, final_keywords)
             if mode == "amj" and hypothesis_ledger:
                 post_front_hypothesis_rows = self._hypothesis_contract_violations(
@@ -5103,6 +5224,7 @@ The previous attempt for this same manuscript unit was rejected by validation. R
                     "translation_sections": translation_sections,
                     "translation_glossary": translation_glossary,
                     "final_abstract": final_abstract,
+                    "final_title": final_title,
                     "final_keywords": final_keywords,
                     "front_matter_phase": "final",
                     "final_reference_count": final_reference_count,

core/pipeline_agent.py

@@ -1761,6 +1761,179 @@ Return a concise PROVISIONAL RESEARCH LOGIC CONTRACT in plain English prose. It
                     )
         raise DeepSeekRequestError(f'{phase} front matter validation failed: {last_error}')
 
+    @staticmethod
+    def _quantitative_front_matter_fallback(contract):
+        """Last-resort degraded front matter derived only from frozen authority.
+
+        This fallback is intentionally plain.  It is used only after bounded
+        semantic reconciliation cannot produce a validated result; it never
+        replaces the normal LLM path.
+        """
+        constructs = dict((contract or {}).get("constructs") or {})
+        roles = list((contract or {}).get("construct_roles") or ("predictor", "mediator", "outcome"))
+        values = [re.sub(r"\s+", " ", str(constructs.get(role) or "")).strip() for role in roles]
+        values = [item for item in values if item]
+        if not values:
+            return {"title": "Quantitative Management Study", "keywords": ["quantitative research", "management research", "empirical study", "evidence"]}
+        title = ", ".join(values[:-1]) + ((", and " if len(values) > 2 else " and ") + values[-1] if len(values) > 1 else "")
+        keywords = list(values)
+        for item in ("quantitative research", "empirical study", "management research"):
+            if len(keywords) >= 4:
+                break
+            if item.casefold() not in {value.casefold() for value in keywords}:
+                keywords.append(item)
+        return {"title": title, "keywords": keywords[:6]}
+
+    @staticmethod
+    def _validate_quantitative_front_matter_candidate(candidate, contract):
+        """Validate structure and frozen-construct coverage, not prose style."""
+        if not isinstance(candidate, dict):
+            return ["candidate_not_object"]
+        title = re.sub(r"\s+", " ", str(candidate.get("title") or "")).strip()
+        raw_keywords = candidate.get("keywords")
+        if not title:
+            return ["title_missing"]
+        if not isinstance(raw_keywords, list):
+            return ["keywords_not_array"]
+        keywords = [re.sub(r"\s+", " ", str(item or "")).strip() for item in raw_keywords]
+        keywords = [item for item in keywords if item]
+        issues = []
+        if not 4 <= len(keywords) <= 6:
+            issues.append("keywords_count_must_be_4_to_6")
+        if len({item.casefold() for item in keywords}) != len(keywords):
+            issues.append("keywords_must_be_distinct")
+        constructs = dict((contract or {}).get("constructs") or {})
+        roles = list((contract or {}).get("construct_roles") or constructs.keys())
+        combined = (title + " ; " + " ; ".join(keywords)).casefold()
+        missing = [
+            str(constructs.get(role) or "").strip()
+            for role in roles
+            if str(constructs.get(role) or "").strip()
+            and str(constructs.get(role) or "").strip().casefold() not in combined
+        ]
+        if missing:
+            issues.append("missing_frozen_constructs:" + " | ".join(missing))
+        return issues
+
+    def reconcile_quantitative_reader_front_matter(self, *, topic, keywords, contract, manuscript=""):
+        """Adaptively reconcile final AMJ title/keywords to frozen evidence.
+
+        Original user topic/keyword seeds are retained as research context.  The
+        model may preserve domain/context terms, but it must not present an
+        unmeasured concept as a focal studied construct.  A reasoning critic
+        validates semantic fidelity.  After bounded retries, deterministic
+        degraded-mode fallback keeps packaging recoverable.
+        """
+        contract = dict(contract or {})
+        constructs = dict(contract.get("constructs") or {})
+        roles = list(contract.get("construct_roles") or constructs.keys())
+        frozen = [{"role": role, "name": constructs.get(role)} for role in roles if constructs.get(role)]
+        if not frozen:
+            logging.warning("Front-matter semantic contract missing frozen constructs; using degraded fallback.")
+            return self._quantitative_front_matter_fallback(contract)
+
+        source_topic = str(contract.get("source_topic") or topic or "").strip()
+        source_keywords = list(contract.get("source_keywords") or [])
+        if not source_keywords:
+            source_keywords = [item.strip() for item in re.split(r"[,;\n|]+", str(keywords or "")) if item.strip()]
+        body_context = self._abstract_manuscript_context(str(manuscript or ""), 8000) if manuscript else ""
+        feedback = ""
+        last_candidate = None
+
+        for attempt in range(2):
+            prompt = f"""Reconcile the reader-facing English TITLE and KEYWORDS for a completed management-journal quantitative manuscript.
+Return JSON only: {{"title":"...","keywords":["...", "..."]}}.
+
+SEMANTIC RULES:
+1. The frozen construct-role list below is authoritative for what the study actually measures/models.
+2. Preserve useful domain, industry, population, technology, or methodological context from the user's topic/keyword seeds when academically appropriate.
+3. Do NOT present any concept outside the frozen construct-role list as a focal measured, modeled, mediating, moderating, or outcome variable.
+4. Contextual terms may appear when they describe setting/domain rather than an unmeasured focal construct.
+5. Produce a natural journal-style title, not a mechanical template.
+6. Return 4-6 distinct academic keywords. Include the frozen constructs and add only genuinely useful context/method terms.
+7. Do not mention this reconciliation process.
+
+<ORIGINAL_USER_TOPIC>
+{source_topic}
+</ORIGINAL_USER_TOPIC>
+<ORIGINAL_USER_KEYWORD_SEEDS>
+{json.dumps(source_keywords, ensure_ascii=False)}
+</ORIGINAL_USER_KEYWORD_SEEDS>
+<FROZEN_CONSTRUCT_ROLES>
+{json.dumps(frozen, ensure_ascii=False)}
+</FROZEN_CONSTRUCT_ROLES>
+<COMPLETED_MANUSCRIPT_CONTEXT>
+{body_context}
+</COMPLETED_MANUSCRIPT_CONTEXT>
+<VALIDATION_FEEDBACK>
+{feedback}
+</VALIDATION_FEEDBACK>"""
+            try:
+                response = self.call_deepseek(
+                    "You are a senior management-journal editor. Reconcile title and keywords to the study's frozen empirical scope without erasing legitimate domain context.",
+                    prompt,
+                    max_tokens=900,
+                    temp=0.0,
+                    model_role="writing",
+                    thinking=False,
+                    allow_fallback=False,
+                    response_format={"type": "json_object"},
+                    logical_node="front_matter_reconciliation",
+                )
+                candidate = self._extract_json_from_text(response)
+                last_candidate = candidate if isinstance(candidate, dict) else None
+            except Exception as exc:
+                logging.warning("Adaptive front-matter generation unavailable; degraded fallback will preserve delivery | error=%s", self._safe_source_error(exc))
+                break
+
+            local_issues = self._validate_quantitative_front_matter_candidate(candidate, contract)
+            if local_issues:
+                feedback = "Local validation issues: " + "; ".join(local_issues)
+                logging.warning("Adaptive front-matter local retry | attempt=%s/2 | %s", attempt + 1, feedback)
+                continue
+
+            critic_prompt = f"""Audit the proposed title/keywords against the frozen empirical construct roles.
+Return JSON only: {{"valid":true,"unmeasured_focal_constructs":[],"missing_frozen_constructs":[],"reason":"..."}}.
+A contextual/domain term is allowed. Mark INVALID only when the proposal makes an unmeasured concept appear to be a focal measured/modeled variable, omits a frozen focal construct from the reader-facing scope, or materially misstates the empirical design.
+<FROZEN_CONSTRUCT_ROLES>{json.dumps(frozen, ensure_ascii=False)}</FROZEN_CONSTRUCT_ROLES>
+<ORIGINAL_USER_TOPIC>{source_topic}</ORIGINAL_USER_TOPIC>
+<CANDIDATE>{json.dumps(candidate, ensure_ascii=False)}</CANDIDATE>"""
+            try:
+                critic_raw = self.call_deepseek(
+                    "You are a rigorous empirical-methods editor checking title-to-evidence fidelity.",
+                    critic_prompt,
+                    max_tokens=500,
+                    temp=0.0,
+                    model_role="reasoning",
+                    thinking=True,
+                    allow_fallback=False,
+                    response_format={"type": "json_object"},
+                    logical_node="front_matter_fidelity_critic",
+                )
+                critic = self._extract_json_from_text(critic_raw)
+            except Exception as exc:
+                logging.warning("Front-matter semantic critic unavailable; accepting structurally valid candidate with frozen-construct coverage | error=%s", self._safe_source_error(exc))
+                critic = {"valid": True, "unmeasured_focal_constructs": [], "missing_frozen_constructs": []}
+
+            invalid = not bool((critic or {}).get("valid"))
+            extra = [str(item).strip() for item in ((critic or {}).get("unmeasured_focal_constructs") or []) if str(item).strip()]
+            missing = [str(item).strip() for item in ((critic or {}).get("missing_frozen_constructs") or []) if str(item).strip()]
+            if not invalid and not extra and not missing:
+                return {
+                    "title": re.sub(r"\s+", " ", str(candidate.get("title") or "")).strip(),
+                    "keywords": [re.sub(r"\s+", " ", str(item)).strip() for item in candidate.get("keywords") or [] if str(item).strip()],
+                }
+            feedback = "Semantic critic rejected candidate. " + str((critic or {}).get("reason") or "")
+            if extra:
+                feedback += " Unmeasured focal constructs: " + ", ".join(extra) + "."
+            if missing:
+                feedback += " Missing frozen constructs: " + ", ".join(missing) + "."
+            logging.warning("Adaptive front-matter semantic retry | attempt=%s/2 | %s", attempt + 1, feedback[:900])
+
+        fallback = self._quantitative_front_matter_fallback(contract)
+        logging.warning("Adaptive front-matter reconciliation exhausted; using deterministic degraded fallback instead of failing manuscript generation.")
+        return fallback
+
     def generate_working_front_matter(
         self, topic, keywords, research_logic_contract, synthesis_result, data_evidence='', mode='amj', validation_feedback='', hypothesis_contract=''
     ):

core/quantitative_engine.py

@@ -21,6 +21,7 @@ class QuantitativeEngine:
     QUANTITATIVE_EVIDENCE_LEDGER_VERSION = "quantitative-evidence-ledger-v2"
     QUANTITATIVE_TABLE_MANIFEST_VERSION = "quantitative-table-manifest-v1"
     HYPOTHESIS_LEDGER_VERSION = "quantitative-hypothesis-ledger-v1"
+    FRONT_MATTER_CONTRACT_VERSION = "quantitative-front-matter-contract-v2"
     TARGET_TABLE_BINDING_VERSION = "target-quantitative-table-binding-v1"
     SEMANTIC_CLAIM_FRAME_VERSION = "smartpaper-core-semantic-claim-frame-v1"
 
@@ -108,6 +109,43 @@ class QuantitativeEngine:
         },
     }
 
+    @classmethod
+    def build_front_matter_contract(cls, topic, keywords, constructs):
+        """Freeze semantic authority without hard-coding reader-facing prose.
+
+        The evidence engine owns construct identities/roles.  The user's topic
+        and keyword seeds remain available for retrieval, literature synthesis,
+        and domain reasoning.  Reader-facing title/keywords are reconciled later
+        by the model against this frozen contract and then deterministically
+        validated.
+        """
+        role_names = ("predictor", "mediator", "outcome")
+        if isinstance(constructs, dict):
+            role_map = {
+                role: re.sub(r"\s+", " ", str(constructs.get(role) or "")).strip()
+                for role in role_names
+            }
+        else:
+            values = [re.sub(r"\s+", " ", str(item or "")).strip() for item in (constructs or [])]
+            if len(values) != len(role_names):
+                return {}
+            role_map = dict(zip(role_names, values))
+        if any(not role_map.get(role) for role in role_names):
+            return {}
+        source_keywords = [
+            re.sub(r"\s+", " ", item).strip()
+            for item in re.split(r"[,;\n|]+", str(keywords or ""))
+            if re.sub(r"\s+", " ", item).strip()
+        ]
+        return {
+            "version": cls.FRONT_MATTER_CONTRACT_VERSION,
+            "policy": "system_generated_frozen_construct_semantic_authority",
+            "source_topic": re.sub(r"\s+", " ", str(topic or "")).strip(),
+            "source_keywords": source_keywords,
+            "construct_roles": list(role_names),
+            "constructs": role_map,
+        }
+
     @classmethod
     def build_hypothesis_ledger(cls, constructs):
         """Freeze one result-independent AMJ hypothesis identity contract.
@@ -2050,6 +2088,9 @@ Keywords: {keywords}"""
             ],
         }
         metadata["semantic_claim_frame_version"] = self.SEMANTIC_CLAIM_FRAME_VERSION
+        metadata["front_matter_contract"] = self.build_front_matter_contract(
+            topic, keywords, metadata.get("constructs") or construct_names
+        )
         metadata["hypothesis_ledger"] = self.build_hypothesis_ledger(construct_names)
         metadata["quantitative_table_manifest"] = self.build_table_manifest(
             validity_df, fl_matrix_df, path_table, spearman

smartpaper_restore_bridge/frontend/index.html

@@ -542,25 +542,20 @@
     target.textContent = value;
   }
 
-  const UNNUMBERED_HEADINGS = new Set([
-    "abstract","keyword","keywords","references","reference list",
-    "摘要","关键词","关键字","参考文献",
-    "аннотация","ключевое слово","ключевые слова","литература","список литературы",
-    "аңдатпа","түйіндеме","түйін сөздер","түйінді сөздер","кілт сөздер",
-    "әдебиеттер","пайдаланылған әдебиеттер"
-  ]);
-
-  const UNNUMBERED_HEADING_PREFIXES = ["appendix", "附录", "приложение", "қосымша"];
-
-  function isUnnumberedHeading(value) {
-    const key = String(value || "").trim().toLocaleLowerCase();
-    return UNNUMBERED_HEADINGS.has(key) || UNNUMBERED_HEADING_PREFIXES.some(prefix => key.startsWith(prefix));
-  }
-
   function cleanHeadingTitle(value) {
     return String(value || "").trim().replace(/^\d+(?:\.\d+){0,2}\s+/, "");
   }
 
+  function segmentHasSixColumnMarkdownTable(lines, startIndex, endIndex) {
+    for (let index = startIndex; index < endIndex; index += 1) {
+      const line = String(lines[index] || "").trim();
+      if (!line.includes("|")) continue;
+      const cells = line.replace(/^\|/, "").replace(/\|$/, "").split("|").map(cell => cell.trim());
+      if (cells.length === 6 && cells.every(Boolean)) return true;
+    }
+    return false;
+  }
+
   function numberMarkdownHeadings(value) {
     const text = String(value || "").replace(/\r/g, "");
     const lines = text.split("\n");
@@ -569,13 +564,25 @@
       const match = line.match(/^(#{1,3})\s+(.+?)\s*$/);
       return match ? { index, level:match[1].length, title:cleanHeadingTitle(match[2]) } : null;
     }).filter(Boolean);
-    const hasFrontMatter = headingRows.some(row => isUnnumberedHeading(row.title));
-    const firstH1 = headingRows.find(row => row.level === 1);
+    const h1Rows = headingRows.filter(row => row.level === 1);
+    const firstH1 = h1Rows[0] || null;
+    const secondH1 = h1Rows[1] || null;
+    const firstH1IsTitle = Boolean(firstH1);
+    const structuralUnnumberedH1 = new Set();
+    if (h1Rows.length >= 2) structuralUnnumberedH1.add(h1Rows[h1Rows.length - 1].index);
+    if (h1Rows.length >= 3) {
+      const penultimate = h1Rows[h1Rows.length - 2];
+      const last = h1Rows[h1Rows.length - 1];
+      if (segmentHasSixColumnMarkdownTable(lines, penultimate.index + 1, last.index)) {
+        structuralUnnumberedH1.add(penultimate.index);
+      }
+    }
+
     for (const row of headingRows) {
-      const key = row.title.toLocaleLowerCase();
-      const isKnownUnnumbered = isUnnumberedHeading(row.title);
-      const isTitle = hasFrontMatter && firstH1 && row.index === firstH1.index && !isKnownUnnumbered;
-      if (isKnownUnnumbered || isTitle) {
+      const isTitle = firstH1IsTitle && firstH1 && row.index === firstH1.index;
+      const isFrontMatterChild = firstH1IsTitle && firstH1 && row.level > 1 && row.index > firstH1.index && (!secondH1 || row.index < secondH1.index);
+      const isStructuralBackMatter = row.level === 1 && structuralUnnumberedH1.has(row.index);
+      if (isTitle || isFrontMatterChild || isStructuralBackMatter) {
         lines[row.index] = row.title;
         continue;
       }

utils/docx_builder.py

@@ -15,19 +15,34 @@ class DocxBuildError(RuntimeError):
     """Raised when markdown cannot be rendered into a valid DOCX document."""
 
 
-_UNNUMBERED_REFERENCE_HEADINGS = frozenset({
-    "references",
-    "参考文献",
-    "литература",
-    "список литературы",
-    "пайдаланылған әдебиеттер",
-})
+def _manuscript_heading_structure(markdown_content, *, qualitative_appendix=False):
+    """Derive unnumbered heading roles from Markdown structure, not language.
 
-
-def _normalize_heading_label(text):
-    """Normalize a heading for exact front/back-matter label matching."""
-    value = " ".join(str(text or "").replace("\u00a0", " ").split()).casefold()
-    return value.rstrip(" :：")
+    Production manuscripts have an optional title/front-matter H1 followed by
+    numbered body H1s and a final References H1. ASQ additionally has a
+    penultimate Appendix H1.  The roles are identified by position and the
+    existing semantic ASQ packaging flag, so translated wording is irrelevant.
+    """
+    tokens = mistune.create_markdown(renderer="ast", plugins=["table"])(str(markdown_content or ""))
+    headings = []
+    for token_index, token in enumerate(tokens):
+        if not isinstance(token, dict) or token.get("type") != "heading":
+            continue
+        level = int((token.get("attrs") or {}).get("level") or 0)
+        headings.append((token_index, level))
+    h1 = [(token_index, level) for token_index, level in headings if level == 1]
+    if not h1:
+        return {"first_h1_is_title": False, "unnumbered_h1_ordinals": set()}
+    first_h1_is_title = True
+    unnumbered = set()
+    if len(h1) >= 2:
+        unnumbered.add(len(h1))  # final References H1
+    if qualitative_appendix and len(h1) >= 3:
+        unnumbered.add(len(h1) - 1)  # ASQ Appendix H1
+    return {
+        "first_h1_is_title": first_h1_is_title,
+        "unnumbered_h1_ordinals": unnumbered,
+    }
 
 
 def _table_column_count(token):
@@ -72,11 +87,13 @@ def _qualitative_appendix_table_ordinal(markdown_content):
 
 
 class DocxRenderer(mistune.HTMLRenderer):
-    def __init__(self, *, qualitative_appendix_table_ordinal=None, semantic_qualitative_appendix=False):
+    def __init__(self, *, qualitative_appendix_table_ordinal=None, semantic_qualitative_appendix=False, first_h1_is_title=False, unnumbered_h1_ordinals=None):
         super().__init__()
         self.doc = Document()
         self.h_counters = [0] * 6
-        self.is_first_h1 = True
+        self.h1_ordinal = 0
+        self.first_h1_is_title = bool(first_h1_is_title)
+        self.unnumbered_h1_ordinals = set(unnumbered_h1_ordinals or set())
         self.table_ordinal = -1
         self.qualitative_appendix_table_ordinal = qualitative_appendix_table_ordinal
         self.semantic_qualitative_appendix = bool(semantic_qualitative_appendix)
@@ -108,19 +125,17 @@ class DocxRenderer(mistune.HTMLRenderer):
 
     def heading(self, text, level):
         clean_text = BeautifulSoup(text, 'html.parser').get_text().strip()
-        lower_text = clean_text.lower()
-        normalized_text = _normalize_heading_label(clean_text)
-        skip_keywords = APP_CONFIG["blacklists"]["meta_sections"]
-        exact_reference_heading = normalized_text in _UNNUMBERED_REFERENCE_HEADINGS
-        
-        if exact_reference_heading or any(kw in lower_text for kw in skip_keywords) or (level == 1 and self.is_first_h1):
-            if level == 1: 
-                self.is_first_h1 = False
-            self.doc.add_heading(clean_text, level=1)
+        level = int(level or 0)
+        if level == 1:
+            self.h1_ordinal += 1
+            if (self.first_h1_is_title and self.h1_ordinal == 1) or self.h1_ordinal in self.unnumbered_h1_ordinals:
+                self.doc.add_heading(clean_text, level=1)
+                return ''
+        elif self.first_h1_is_title and self.h1_ordinal == 1:
+            # Abstract/Keywords and any other front-matter child headings are
+            # structurally unnumbered regardless of language.
+            self.doc.add_heading(clean_text, level=level)
             return ''
-
-        if level == 1: 
-            self.is_first_h1 = False
             
         idx = level - 1
         if 0 <= idx < 6:
@@ -275,9 +290,14 @@ def text_to_docx(markdown_content, *, qualitative_appendix=False):
                 raise DocxBuildError(
                     "Qualitative Appendix semantic table identity is missing or ambiguous."
                 )
+        heading_structure = _manuscript_heading_structure(
+            markdown_content, qualitative_appendix=semantic_qualitative_appendix
+        )
         renderer = DocxRenderer(
             qualitative_appendix_table_ordinal=qualitative_table_ordinal,
             semantic_qualitative_appendix=semantic_qualitative_appendix,
+            first_h1_is_title=heading_structure["first_h1_is_title"],
+            unnumbered_h1_ordinals=heading_structure["unnumbered_h1_ordinals"],
         )
         mistune.create_markdown(renderer=renderer, plugins=['table'])(str(markdown_content or ''))
         doc = renderer.doc