Remove lower-priority figure placeholder rule

Author: 917Dhj

SKILL.md

@@ -160,12 +160,13 @@ Local-library-first rule (applies only when the Zotero check above succeeds):
 - The note must include figure/table placeholders for all major visuals rather than silently skipping them.
 - Every kept figure/table placeholder must appear directly under the most relevant analytical section named by its `建议位置`; do not collect unresolved placeholders in catch-all sections such as `剩余图表占位` or `Remaining figures`.
 - Every kept figure/table placeholder must use the standard `> [!figure]` callout format with `建议位置`, `放置原因`, and `当前状态`; do not use ordinary paragraph markers such as `[图表占位 | Fig. 1]`, `图表占位：Table 2`, or `Figure Placeholder | Fig. 3`.
-- Real images may replace some placeholders, but only if they clearly match the corresponding paper figure/table.
+- Real images replace placeholders when they clearly match the corresponding paper figure/table and pass the visual-usability gate.
 - When inserting a real image, use the `relative_markdown_embed` from `figure_table_decisions.json`; final save with `scripts/write_obsidian_note.py --figure-decisions ...` copies the image into the paper-local `images/` directory.
 - When a real image is inserted, render it as the Obsidian embed or Markdown image embed followed immediately by one italic caption line.
 - Do not keep a redundant `> [!figure]` placeholder callout for the same inserted real figure.
 - Figure captions in the note must preserve the original paper numbering such as `Fig. 1` or `Table 2`.
-- If a figure/table candidate is marked usable, resolve it explicitly: insert the real image, keep the placeholder because of a concrete visual defect, keep it as lower-priority because a more central related figure is already inserted, or keep it because materialization failed.
+- If a figure/table candidate is marked usable and has a real image path, insert the real image. Do not keep a placeholder merely because the figure/table is lower priority, supplemental, already summarized in text, or less central than another inserted figure.
+- A kept placeholder is valid only when the image cannot be safely inserted because of a concrete visual defect, missing candidate, unresolved visual review, identity mismatch, contamination, or materialization/copy/write failure.
 - For `usable_candidate` or `needs_visual_quality_check` / `review` candidates, make the visual decision only after inspecting the actual candidate image file exposed by the pipeline. Record the concrete visual observation behind the decision. Do not claim manual visual review, visual inspection, or "no reliable insertable candidate" unless the candidate image was actually opened and inspected.
 - `reject_visual_quality` and `asset_candidate_missing` are fail-closed script states. They do not require manual visual review before keeping a placeholder or skipping insertion; treat them as automatic extraction outcomes unless you explicitly inspect or re-extract the source asset.
 - Do not misreport missing candidates as materialization failures: `asset_candidate_missing`, empty `source_image_path`, or no independent crop means the placeholder status should say no high-confidence image candidate was extracted. Use materialization/copy/write failure language only after a real chosen image asset failed to copy or write.

references/figure-placement.md

@@ -47,13 +47,14 @@ Do not let scripts make the final semantic choice; scripts should only prepare c
 
 ## Usable Candidate Decision Contract
 
-`usable_candidate` means the candidate is eligible for final judgment; it is not an automatic insertion command.
+`usable_candidate` means the pipeline found a candidate that is visually eligible to insert.
 For every usable figure/table candidate, resolve the final note into one of these states:
 - `insert`: materialize the image and replace the placeholder with the real image plus one italic caption line
 - `kept_placeholder_visual_defect`: keep the placeholder because manual review found a concrete visual defect, such as contamination, truncation, missing table body, partial subfigure, or caption loss
-- `kept_placeholder_lower_priority`: keep the placeholder because a more central or more direct related figure/table is already inserted
 - `kept_placeholder_materialization_blocked`: keep the placeholder because `materialize_figure_asset.py` or file copy/write permission failed
 
+Do not keep a usable candidate as a placeholder merely because it is lower priority, supplemental, already summarized in text, or less central than another inserted figure/table. If a usable candidate is important enough to appear as a callout in the final note, insert the real image. If it is not important enough to appear, omit it or summarize it in prose rather than leaving a placeholder.
+
 For `usable_candidate` and `needs_visual_quality_check` / `review` candidates, final visual judgment requires opening and inspecting the actual candidate image file.
 Do not write that manual visual review found no reliable insertable candidate unless that inspection actually happened.
 If no manual inspection happened, name the state as an unresolved visual review requirement or an automatic script outcome, not as a reviewed visual defect.
@@ -63,7 +64,7 @@ Keep missing-candidate cases separate from materialization failures:
 - reserve `materialization blocked` only for a real chosen image asset that failed during `materialize_figure_asset.py`, final copy, permission, or `write_obsidian_note.py`
 - if a crop includes another Figure/Table caption or another figure body, treat it as a visual defect or missing independent candidate; do not call it usable just because it contains the target label
 
-`plan_figure_table_decisions.py` may preselect high-priority usable figure crops as `insert`.
+`plan_figure_table_decisions.py` preselects planned usable figure/table crops as `insert`.
 That does not mean `run_pipeline.py` writes into the vault; materialization happens at the final save step, where `write_obsidian_note.py --figure-decisions ...` copies the selected images and refuses a note that does not reference the selected image path.
 
 Do not use soft reasons such as keeping the note light, values already transcribed, future lookup, or convenient back-reference as the standalone reason for keeping a usable candidate as a placeholder.

references/final-writing.md

@@ -242,7 +242,9 @@ If the bundle contains candidate figure pages or candidate image files:
 - still make the final decision yourself rather than trusting the candidate ranking blindly
 - for `usable_candidate` or `needs_visual_quality_check` / `review`, make that final decision only after opening and inspecting the actual candidate image file; do not say manual visual review found no reliable candidate unless that inspection actually happened
 - treat `reject_visual_quality` and `asset_candidate_missing` as automatic fail-closed script outcomes that do not require manual visual review
-- if a candidate is usable, resolve it explicitly as inserted, kept for a concrete visual defect, kept as lower-priority because a more central related figure is already inserted, or kept because materialization/copy/write failed
+- if a candidate is usable and has a real image path, insert it
+- do not keep a usable candidate as a placeholder merely because it is lower priority, supplemental, already summarized in text, or less central than another inserted figure/table
+- keep a placeholder only when there is a concrete visual defect, missing candidate, unresolved visual review, identity mismatch, contamination, or materialization/copy/write failure
 - never describe a missing image asset, empty `source_image_path`, `asset_candidate_missing`, or absent independent crop as a materialization/copy failure
 - if the crop contains a different Figure/Table caption or another figure body, describe that as contamination/visual defect or lack of an independent crop, not as a usable clean candidate
 - do not keep a usable candidate as a placeholder only because the note should stay light, the values were transcribed, the figure can be checked later, or it is convenient as a back-reference

references/workflow.md

@@ -123,7 +123,7 @@ For a normal single-paper note request, the pipeline below is a required executi
 8. `plan_figure_table_decisions`
    Build a decision row for every detected figure/table caption.
    Each item should have one explicit state: `insert`, `placeholder`, `low_priority`, `visual_defect`, or `skip` with reason.
-   High-priority usable figure crops may be marked `insert`, but this is still a final-save obligation, not a pipeline-time vault write.
+   Planned usable figure/table crops with real image paths should be marked `insert`; this is still a final-save obligation, not a pipeline-time vault write.
    Completion condition:
    - every major detected figure/table has a recorded decision or skip reason
 
@@ -163,7 +163,7 @@ For a normal single-paper note request, the pipeline below is a required executi
    Completion condition:
    - every substantive planned section cites either a valid `section_id` or a valid page range
    - every substantive planned section has a paper-specific `focus`/reading goal, not only a valid anchor
-   - high-priority usable figure candidates are not left as vague placeholders
+   - usable figure/table candidates with real image paths are not left as vague placeholders or low-priority placeholders
    - old broad bundle references such as `synthesis_bundle.evidence.method_evidence` are rejected
    - truncated source text blocks full-read drafting unless partial reading was explicitly accepted
 
@@ -240,8 +240,8 @@ For a normal single-paper note request, the pipeline below is a required executi
     - create a new domain only when no existing domain fits well
     - do not save directly into the bare papers root
    Complete the figure decision before this step:
-    - replace high-confidence placeholders with real images
-    - keep lower-confidence items as placeholders
+    - replace usable matched placeholders with real images
+    - keep lower-confidence, missing, contaminated, or blocked items as placeholders
     - pass the figure decision table to `write_obsidian_note.py --figure-decisions ...` so `insert` rows are copied into the paper-local `images/` folder and must be referenced by the final Markdown
     - do not split text writing and figure handling into two separate user turns by default
     If the configured vault or its paper-local `images/` directory cannot currently be written:

scripts/build_synthesis_bundle.py

@@ -274,7 +274,7 @@ def compact_writing_contract() -> dict:
         depth_requirements["generic_focus_phrases"]
     )
     usable_insert_candidate = dict(WRITING_CONTRACT_RULES["usable_insert_candidate"])
-    usable_insert_candidate["plan_kinds"] = list(usable_insert_candidate["plan_kinds"])
+    usable_insert_candidate["kinds"] = list(usable_insert_candidate["kinds"])
     analysis_coverage = dict(WRITING_CONTRACT_RULES["analysis_coverage_contract"])
     analysis_coverage["central_claim_fields"] = list(
         analysis_coverage["central_claim_fields"]

scripts/contracts.py

@@ -278,14 +278,12 @@
     ),
     "figure_decision_values": ("insert", "placeholder", "low_priority", "visual_defect", "skip"),
     "usable_insert_candidate": {
-        "kind": "figure",
-        "max_priority": 2,
+        "kinds": ("figure", "table"),
         "visual_quality_status": "usable_candidate",
-        "plan_kinds": ("method_overview", "data_or_task_overview", "main_result"),
+        "requires_source_image_path": True,
     },
     "allowed_usable_placeholder_reasons": (
         "visual_defect",
-        "lower_priority_related_inserted",
         "materialization_blocked",
     ),
     "manual_visual_review_required_statuses": (

scripts/lint_grounding.py

@@ -340,11 +340,7 @@ def validate_figure_decisions(
         return [issue("figure_table_decisions_invalid")]
     valid_decisions = set(WRITING_CONTRACT_RULES["figure_decision_values"])
     usable_insert = WRITING_CONTRACT_RULES["usable_insert_candidate"]
-    max_insert_priority = int(usable_insert["max_priority"])
-    auto_insert_plan_kinds = set(usable_insert.get("plan_kinds", ()))
-    allowed_placeholder_reasons = set(
-        WRITING_CONTRACT_RULES["allowed_usable_placeholder_reasons"]
-    )
+    insertable_kinds = set(usable_insert.get("kinds", ()))
     decision_ids = {
         normalize_whitespace(
             str(item.get("source_id") or item.get("label") or item.get("item_id") or "")
@@ -397,29 +393,21 @@ def validate_figure_decisions(
                     source_id=item.get("source_id") or item.get("label") or "",
                 )
             )
-        try:
-            priority = int(item.get("priority", 99) or 99)
-        except (TypeError, ValueError):
-            priority = 99
         is_required_insert_candidate = (
-            normalize_whitespace(str(item.get("kind", ""))) == usable_insert["kind"]
+            normalize_whitespace(str(item.get("kind", ""))) in insertable_kinds
             and normalize_whitespace(str(item.get("visual_quality_status", "")))
             == usable_insert["visual_quality_status"]
-            and priority <= max_insert_priority
+            and normalize_whitespace(str(item.get("source_image_path", "")))
         )
-        plan_kind = normalize_whitespace(str(item.get("plan_kind", "")))
-        if plan_kind not in auto_insert_plan_kinds:
-            is_required_insert_candidate = False
-        if is_required_insert_candidate and decision == "placeholder":
+        if is_required_insert_candidate and decision != "insert":
             skip_reason = normalize_whitespace(str(item.get("skip_reason", "")))
-            if skip_reason not in allowed_placeholder_reasons:
-                issues.append(
-                    issue(
-                        "usable_insert_candidate_left_placeholder",
-                        source_id=item.get("source_id") or item.get("label") or "",
-                        skip_reason=skip_reason,
-                    )
+            issues.append(
+                issue(
+                    "usable_insert_candidate_left_placeholder",
+                    source_id=item.get("source_id") or item.get("label") or "",
+                    skip_reason=skip_reason,
                 )
+            )
     return issues
 
 

scripts/lint_note.py

@@ -117,6 +117,10 @@
         |
         (?:图像|图片|表格|图|表)?\s*裁剪[^。；，\n>]{0,12}(?<!不)(?:可用|可读|清晰)
         |
+        (?:图像|图片|表格|图|表)[^。；，\n>]{0,12}(?<!不)(?:可用|可读|清晰)
+        |
+        图号\s*匹配
+        |
         匹配度\s*高
         |
         高\s*置信(?:度)?[^。；，\n>]{0,12}候选
@@ -150,24 +154,6 @@
     flags=re.IGNORECASE | re.VERBOSE,
 )
 
-USABLE_CANDIDATE_LOWER_PRIORITY_RE = re.compile(
-    r"""
-    (?:
-        低优先级|优先级较低|次要|补充性
-        |
-        (?:已插入|已有|already\s+inserted)[^。；\n]{0,40}
-        (?:更核心|更直接|低优先级|同一(?:机制|概念|结论|任务|流程))
-        |
-        (?:Fig(?:ure)?|Table|图|表)\s*[\w.-]*[^。；\n]{0,40}(?:更核心|更直接)
-        |
-        lower[-\s]*priority
-        |
-        more\s+(?:central|direct|core)
-    )
-    """,
-    flags=re.IGNORECASE | re.VERBOSE,
-)
-
 USABLE_CANDIDATE_MATERIALIZATION_BLOCKED_RE = re.compile(
     r"""
     (?:
@@ -625,14 +611,9 @@ def figure_status_text(line: str) -> str:
     return stripped.removeprefix("> 当前状态：").strip()
 
 
-def has_lower_priority_placeholder_reason(status_text: str) -> bool:
-    return bool(USABLE_CANDIDATE_LOWER_PRIORITY_RE.search(status_text))
-
-
 def has_accepted_usable_placeholder_reason(status_text: str) -> bool:
     return bool(
         USABLE_CANDIDATE_VISUAL_DEFECT_RE.search(status_text)
-        or USABLE_CANDIDATE_LOWER_PRIORITY_RE.search(status_text)
         or USABLE_CANDIDATE_MATERIALIZATION_BLOCKED_RE.search(status_text)
     )
 
@@ -773,7 +754,7 @@ def figure_callout_real_image_status_issues(text: str) -> list[dict[str, object]
             if not nxt.startswith(">"):
                 break
             status_text = figure_status_text(nxt)
-            if status_text and REAL_IMAGE_STATUS_RE.search(nxt) and not has_lower_priority_placeholder_reason(status_text):
+            if status_text and REAL_IMAGE_STATUS_RE.search(nxt):
                 issues.append(
                     {
                         "line_number": j + 1,

scripts/plan_figure_table_decisions.py

@@ -16,9 +16,7 @@
 )
 
 DECISION_VALUES = {"insert", "placeholder", "low_priority", "visual_defect", "skip"}
-INSERTABLE_KIND = "figure"
-INSERTABLE_PRIORITY_MAX = 2
-AUTO_INSERT_PLAN_KINDS = {"method_overview", "data_or_task_overview", "main_result"}
+INSERTABLE_KINDS = {"figure", "table"}
 
 
 def parser() -> argparse.ArgumentParser:
@@ -137,16 +135,9 @@ def source_image_filename(plan_item: dict[str, Any]) -> str:
 def should_insert(caption: dict[str, Any], plan_item: dict[str, Any], status: str) -> bool:
     if status != "usable_candidate":
         return False
-    if caption.get("kind") != INSERTABLE_KIND:
+    if caption.get("kind") not in INSERTABLE_KINDS:
         return False
-    plan_kind = normalize_whitespace(str(plan_item.get("kind", "")))
-    if plan_kind not in AUTO_INSERT_PLAN_KINDS:
-        return False
-    try:
-        priority = int(plan_item.get("priority", 99) or 99)
-    except (TypeError, ValueError):
-        priority = 99
-    return priority <= INSERTABLE_PRIORITY_MAX and bool(source_image_path(plan_item))
+    return bool(source_image_path(plan_item))
 
 
 def decide(caption: dict[str, Any], plan_item: dict[str, Any] | None) -> dict[str, Any]:
@@ -193,7 +184,7 @@ def decide(caption: dict[str, Any], plan_item: dict[str, Any] | None) -> dict[st
     else:
         base["decision"] = "placeholder"
         if status == "usable_candidate":
-            base["skip_reason"] = "not_auto_insertable_by_kind_or_priority"
+            base["skip_reason"] = "asset_candidate_missing"
         elif status:
             base["skip_reason"] = "visual_quality_requires_review"
         else:

tests/test_build_synthesis_bundle_contract.py

@@ -48,12 +48,13 @@ def test_bundle_compact_writing_contract_keeps_depth_rules_without_old_bundle_fi
         ),
     }
     assert contract["figure_table_contract"]["usable_insert_candidate"] == {
-        "kind": WRITING_CONTRACT_RULES["usable_insert_candidate"]["kind"],
-        "max_priority": WRITING_CONTRACT_RULES["usable_insert_candidate"]["max_priority"],
+        "kinds": list(WRITING_CONTRACT_RULES["usable_insert_candidate"]["kinds"]),
         "visual_quality_status": WRITING_CONTRACT_RULES["usable_insert_candidate"][
             "visual_quality_status"
         ],
-        "plan_kinds": list(WRITING_CONTRACT_RULES["usable_insert_candidate"]["plan_kinds"]),
+        "requires_source_image_path": WRITING_CONTRACT_RULES["usable_insert_candidate"][
+            "requires_source_image_path"
+        ],
     }
     assert contract["figure_table_contract"]["manual_visual_review_required_statuses"] == list(
         WRITING_CONTRACT_RULES["manual_visual_review_required_statuses"]