From 732d5a23cff327fef0b3c78b698e78d65a7c6756 Mon Sep 17 00:00:00 2001
From: root <root@localhost.localdomain>
Date: Tue, 7 Apr 2026 21:08:06 +0800
Subject: [PATCH] docs: harden digest SOP for hugo and IMA upload

---
 reader-digest-flow/SKILL.md           | 23 +++++++++++++++++++----
 reader-digest-flow/references/flow.md | 20 ++++++++++++++++++++
 2 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/reader-digest-flow/SKILL.md b/reader-digest-flow/SKILL.md
index 92639dc..11eca53 100644
--- a/reader-digest-flow/SKILL.md
+++ b/reader-digest-flow/SKILL.md
@@ -128,11 +128,21 @@ Internal review digest writing rules:
 
 ### Phase 3: Publish to Hugo
 
-Publish only the public digest to Hugo and verify:
+Publish only the public digest to Hugo.
 
-- list page works
-- detail page works
-- latest digest is visible
+Required execution steps:
+
+1. write the public digest markdown to:
+   - `/home/ubuntu/zhu/apps/hugo-site/content/daily/YYYY-MM-DD/index.md`
+2. immediately redeploy Hugo:
+   - `cd /home/ubuntu/zhu/apps/hugo-site && ./redeploy.sh`
+3. verify before moving on:
+   - homepage works
+   - list page works
+   - detail page works
+   - latest digest is visible
+
+Do not treat “markdown file written” as equivalent to publish success. Hugo publish for this SOP is complete only after redeploy and page verification pass.
 
 Do not block on style polish unless the user explicitly asks.
 
@@ -169,6 +179,8 @@ Upload only the generated single-article markdown summaries to IMA.
 
 **Hard gate before upload:** even if the markdown file was generated by `reader`, do **not** upload it to IMA as-is. You must first reformat/check it against the IMA-facing Markdown rules in this skill, then upload the formatted version. Treat `reader` output as article-summary source material, not automatically as final IMA-ready Markdown.
 
+**Hard naming rule before upload:** the final uploaded Markdown filename must use the article's user-facing natural title (normally the original Chinese article title) plus `.md`. Do **not** use internal workflow names, slugs, prefixes, or temp filenames such as `ima-*`, `item-*`, `summary-*`, or English-only shorthand as the final IMA object name.
+
 Default target knowledge base for this phase:
 
 - `daily`
@@ -180,6 +192,7 @@ Completion criteria for this phase:
 
 - a selected article has been summarized from extracted content
 - a single-article Markdown summary file has been generated
+- the final upload filename has been normalized to a user-facing article title (not an internal slug / temp name)
 - the Markdown file is uploaded directly into the target knowledge base as a Markdown knowledge item (`media_type=7`)
 - the uploaded object preserves source link context and uses IMA-friendly layout for readability
 - the upload target is the `daily` knowledge base unless the user explicitly requests otherwise
@@ -204,6 +217,8 @@ IMA Markdown layout guidance for selected article deposition:
 - Remove stiff metadata headers such as `Source:` / `Category:` when preparing the IMA-facing Markdown.
 - Keep source traceability by placing `原文链接：` near the top, followed by the original URL on the next line.
 - Break long prose under `核心结论` and `主要论点` into short paragraphs for IMA readability instead of relying on platform auto-formatting.
+- The final upload filename should normally be `<文章标题>.md`; only when a same-name file already exists should you append a timestamp suffix before `.md`.
+- If local working files use internal slugs or prefixes for convenience, create or rename a final upload copy before calling IMA upload APIs.
 - Use `references/ima-markdown-example.md` as the formatting example whenever preparing the final upload file.
 - Completion for IMA upload requires both: (1) upload API success, and (2) the uploaded markdown having passed the above format checks.
 
diff --git a/reader-digest-flow/references/flow.md b/reader-digest-flow/references/flow.md
index 9928b89..50eca06 100644
--- a/reader-digest-flow/references/flow.md
+++ b/reader-digest-flow/references/flow.md
@@ -147,6 +147,17 @@ Internal review digest constraints:
 
 Publish only the public digest to Hugo.
 
+Hard execution steps:
+
+1. write the public digest markdown to:
+   - `/home/ubuntu/zhu/apps/hugo-site/content/daily/YYYY-MM-DD/index.md`
+2. redeploy Hugo immediately after writing:
+   - `cd /home/ubuntu/zhu/apps/hugo-site && ./redeploy.sh`
+3. verify all three URLs before continuing:
+   - `http://127.0.0.1:14322/`
+   - `http://127.0.0.1:14322/daily/`
+   - `http://127.0.0.1:14322/daily/YYYY-MM-DD/`
+
 Expected verification targets:
 
 - homepage works
@@ -189,6 +200,14 @@ python scripts/run_article_summaries.py \
 
 Upload only the generated markdown files for the selected articles.
 
+Hard execution rules before upload:
+
+1. reformat/check the generated markdown into IMA-facing final content
+2. normalize the final upload filename to `<文章标题>.md`
+3. do not use internal temp names such as `ima-*`, `item-*`, `summary-*`, or English slug filenames as the final uploaded object name
+4. if the knowledge base already contains the same filename, append a timestamp suffix before `.md`
+5. if local work needs internal temp names, create a final upload copy with the user-facing title before calling IMA APIs
+
 Default target knowledge base:
 
 - `daily`
@@ -204,3 +223,4 @@ Default target knowledge base:
 - Only explicitly user-selected articles go to IMA.
 - Selected article summaries use extracted text, not live refetch.
 - Prefer `ARTICLE_SUMMARY_*` for selected article summarization.
+- Final IMA upload filenames must use user-facing article titles, not internal slugs or workflow temp names.