Artifact 產物契約

這份規則是需求級 HTML、截圖與議題附件的唯一正本。

資料流

/sdlc-analyze 完成排程後重新取得需求與工作包抽取 JSON。
流程組成一個 schemaVersion: 1 的需求根物件，暫存於 .tmp/。
scripts/overview-render.js --input <json> --output <html> --manifest <manifest> 驗證並產生自包含 HTML。
預覽平台優先；沒有預覽能力時，使用可用 ephemeral port 短暫啟動 Node 靜態伺服器。
瀏覽器產生 full-page 與圖表局部 PNG，寫入 manifest。
scripts/issue-assets.js --repo ... --index ... --manifest ... 上傳附件並就地更新需求議題附件索引。

JSON、HTML、SVG 與 PNG 全部寫入 .tmp/，不寫入目標專案。

必要欄位：schemaVersion、source、requirement、workPackages、overview。

schemaVersion 不是目前 renderer 支援的版本時必須停止；未知欄位保留。

圖表以抽象資料保存：kind、direction、nodes、edges。議題輸出由 renderer 產生 Mermaid；HTML 重新產生 SVG 或 HTML／CSS，不得直接搬用 Mermaid。

流程、依賴、架構與網路圖使用 SVG；卡片與清單使用 HTML／CSS。布局必須固定且可重跑。

公式是可選欄位，保存 LaTeX 原文、標題、說明與用途。議題使用 formula fenced block；HTML 使用自包含 SVG。單一公式解析失敗時保留原文並標記未渲染，不得靜默遺失；公式欄位結構錯誤仍使整體 schema 驗證失敗。

manifest 的每個 screenshot 必須包含 role、path、fileName、sha256。PNG 使用固定語意檔名，內容 hash 用 SHA-256。

full-page 與局部圖全部上傳為需求議題附件，不直接嵌入圖片。正文只保留一行附件索引；重跑時內容相同就重用，無法確認 hash 就新增附件。附件上傳或議題索引更新失敗是硬錯誤。

若平台提供真正可用的 preview URL，才使用既有 --overview-url 回寫；不可把 .tmp/ 或 0.0.0.0 寫回議題。

平台 preview 是首選。沒有平台 preview 時，可執行：

node scripts/overview-capture.js --backend auto --url <preview-url> --output <png>

若沒有瀏覽器但有 SVG rasterizer：

node scripts/overview-capture.js --backend svg --svg <overview.svg> --output <png>

auto 優先使用 Firefox，再使用 rsvg-convert 或 resvg。找不到任何 backend 必須失敗並保留 .tmp/ 的 HTML／SVG，不得假裝已完成截圖。