ops-wiki-agent-kit 0.1.0

package/.github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py

@@ -0,0 +1,527 @@
+#!/usr/bin/env python3
+import sys
+
+sys.dont_write_bytecode = True
+
+import argparse
+import csv
+import json
+import re
+from collections import OrderedDict, defaultdict
+from pathlib import Path
+
+for parent in Path(__file__).resolve().parents:
+    shared_scripts = parent / "source-code-to-spec-tools" / "scripts"
+    if (shared_scripts / "queue_contract.py").exists():
+        sys.path.insert(0, str(shared_scripts))
+        break
+else:
+    raise SystemExit("Cannot locate source-code-to-spec-tools/scripts/queue_contract.py")
+
+from queue_contract import (
+    DOC_STATUSES as VALID_DOC_STATUSES,
+    COVERAGE_COLUMNS,
+    DEFAULT_PATH_PATTERNS,
+    DEFAULT_PREFIXES,
+    MAIN_COLUMNS,
+    REVIEW_STATUSES as VALID_REVIEW_STATUSES,
+    SUMMARY_COLUMNS,
+    normalize_completed_flag,
+    normalize_doc_profile,
+    normalize_status,
+    normalize_text,
+)
+
+
+def normalize_path_segment(value):
+    value = normalize_text(value)
+    if not value:
+        return "Unclassified"
+    value = re.sub(r'[<>:"/\\|?*]', " ", value)
+    value = re.sub(r"\s+", " ", value).strip()
+    return value or "Unclassified"
+
+
+def markdown_escape(value):
+    return normalize_text(value).replace("|", "\\|")
+
+
+def detect_delimiter(path):
+    suffix = path.suffix.lower()
+    if suffix == ".tsv":
+        return "\t"
+    return ","
+
+
+def read_rows(path):
+    if path is None:
+        return []
+    path = Path(path)
+    if not path.exists():
+        raise SystemExit(f"Input file not found: {path}")
+    suffix = path.suffix.lower()
+    if suffix == ".jsonl":
+        rows = []
+        with path.open("r", encoding="utf-8-sig", newline="") as handle:
+            for line_no, line in enumerate(handle, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    value = json.loads(line)
+                except json.JSONDecodeError as exc:
+                    raise SystemExit(f"{path}:{line_no}: invalid JSONL: {exc}") from exc
+                if not isinstance(value, dict):
+                    raise SystemExit(f"{path}:{line_no}: JSONL row must be an object")
+                rows.append(value)
+        return rows
+    if suffix == ".json":
+        with path.open("r", encoding="utf-8-sig") as handle:
+            value = json.load(handle)
+        if isinstance(value, dict):
+            for key in ("rows", "targets", "items"):
+                if key in value:
+                    value = value[key]
+                    break
+        if not isinstance(value, list) or any(not isinstance(row, dict) for row in value):
+            raise SystemExit(f"{path}: JSON input must be an array of objects or an object with rows")
+        return value
+    delimiter = detect_delimiter(path)
+    with path.open("r", encoding="utf-8-sig", newline="") as handle:
+        return list(csv.DictReader(handle, delimiter=delimiter))
+
+
+def write_csv(path, rows, columns):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=columns)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow({column: row.get(column, "") for column in columns})
+
+
+def parse_prefix_args(values):
+    prefixes = dict(DEFAULT_PREFIXES)
+    for value in values or []:
+        if "=" not in value:
+            raise SystemExit(f"Invalid --prefix value: {value}. Expected source_type=PREFIX.")
+        source_type, prefix = value.split("=", 1)
+        source_type = normalize_text(source_type)
+        prefix = normalize_text(prefix).upper()
+        if not source_type or not re.fullmatch(r"[A-Z][A-Z0-9]*", prefix):
+            raise SystemExit(f"Invalid --prefix value: {value}.")
+        prefixes[source_type] = prefix
+    return prefixes
+
+
+def row_get(row, *names):
+    lowered = {str(key).lower(): key for key in row.keys()}
+    for name in names:
+        key = lowered.get(name.lower())
+        if key is not None:
+            return row.get(key)
+    return ""
+
+
+def normalize_targets(rows, prefixes):
+    normalized = []
+    for index, row in enumerate(rows, 1):
+        source_type = normalize_text(row_get(row, "source_type", "type"))
+        group = normalize_text(row_get(row, "group", "group_name", "module", "category")) or "Unclassified"
+        name = normalize_text(row_get(row, "name", "display_name", "label", "title"))
+        entrypoint = normalize_text(row_get(row, "entrypoint", "activation_target", "route", "path", "command"))
+        keyword = normalize_text(row_get(row, "keyword", "stable_key", "key", "code", "id"))
+        document_path = normalize_text(row_get(row, "document_path", "doc_path"))
+        foundation_doc_status = normalize_status(
+            row_get(row, "foundation_doc_status"),
+            VALID_DOC_STATUSES,
+            "pending",
+        )
+        architecture_doc_status = normalize_status(
+            row_get(row, "architecture_doc_status"),
+            VALID_DOC_STATUSES,
+            "pending",
+        )
+        ops_doc_status = normalize_status(
+            row_get(row, "ops_doc_status"),
+            VALID_DOC_STATUSES,
+            "pending",
+        )
+        review_status = normalize_status(
+            row_get(row, "review_status"), VALID_REVIEW_STATUSES, "not_started"
+        )
+        completed_flag = normalize_completed_flag(
+            row_get(row, "document_completed_flag(Y/N)")
+        )
+        if not source_type:
+            raise SystemExit(f"Target row {index}: missing source_type")
+        if source_type not in prefixes:
+            raise SystemExit(
+                f"Target row {index}: source_type '{source_type}' has no prefix. "
+                "Register the activation surface in Source Type Registry or pass "
+                "--prefix source_type=PREFIX for this converter run."
+            )
+        if not name:
+            raise SystemExit(f"Target row {index}: missing name")
+        if not keyword:
+            keyword = entrypoint or name
+        if not entrypoint:
+            entrypoint = keyword
+        if not document_path:
+            pattern = DEFAULT_PATH_PATTERNS.get(source_type, "docs/{source_type}/{name}")
+            document_path = pattern.format(
+                source_type=normalize_path_segment(source_type),
+                group=normalize_path_segment(group),
+                name=normalize_path_segment(name),
+            )
+        doc_profile = normalize_doc_profile(row_get(row, "doc_profile"), source_type)
+        normalized.append(
+            {
+                "id": normalize_text(row_get(row, "id")),
+                "source_type": source_type,
+                "original_id": normalize_text(row_get(row, "original_id")),
+                "group": group,
+                "name": name,
+                "entrypoint": entrypoint,
+                "document_path": document_path,
+                "keyword": keyword,
+                "doc_profile": doc_profile,
+                "foundation_doc_status": foundation_doc_status,
+                "architecture_doc_status": architecture_doc_status,
+                "ops_doc_status": ops_doc_status,
+                "review_status": review_status,
+                "document_completed_flag(Y/N)": completed_flag,
+                "last_handoff": normalize_text(row_get(row, "last_handoff")),
+                "notes": normalize_text(row_get(row, "notes")),
+            }
+        )
+    return dedupe_targets(normalized)
+
+
+def dedupe_targets(rows):
+    deduped = OrderedDict()
+    for row in rows:
+        key = (
+            row["source_type"].casefold(),
+            row["keyword"].casefold(),
+            row["entrypoint"].casefold(),
+        )
+        if key not in deduped:
+            deduped[key] = row
+            continue
+        current = deduped[key]
+        for column in MAIN_COLUMNS:
+            if not current.get(column) and row.get(column):
+                current[column] = row[column]
+    return list(deduped.values())
+
+
+def sort_targets_by_source_type(rows):
+    return sorted(rows, key=lambda row: normalize_text(row.get("source_type", "")).casefold())
+
+
+def parse_existing_ids(path):
+    if path is None or not Path(path).exists():
+        return {}, defaultdict(set)
+    rows = parse_markdown_main_table(Path(path))
+    mapping = {}
+    used = defaultdict(set)
+    for row in rows:
+        source_type = row.get("source_type", "")
+        original_id = row.get("original_id", "")
+        if source_type and original_id.isdigit():
+            used[source_type].add(int(original_id))
+        for key in target_keys(row):
+            mapping[key] = {
+                "id": row.get("id", ""),
+                "original_id": row.get("original_id", ""),
+            }
+    return mapping, used
+
+
+def parse_markdown_main_table(path):
+    rows = []
+    lines = path.read_text(encoding="utf-8-sig").splitlines()
+    for index, line in enumerate(lines):
+        cells = split_markdown_row(line)
+        if cells == MAIN_COLUMNS:
+            columns = cells
+            if index + 1 >= len(lines):
+                return rows
+            for data_line in lines[index + 2 :]:
+                if not data_line.strip().startswith("|"):
+                    break
+                values = split_markdown_row(data_line)
+                if len(values) != len(columns):
+                    break
+                row = dict(zip(columns, values))
+                rows.append(normalize_existing_row(row))
+            break
+    return rows
+
+
+def normalize_existing_row(row):
+    normalized = {column: row.get(column, "") for column in MAIN_COLUMNS}
+    normalized["doc_profile"] = normalize_doc_profile(
+        normalized.get("doc_profile", ""), normalized.get("source_type", "")
+    )
+    return normalized
+
+
+def split_markdown_row(line):
+    line = line.strip()
+    if not line.startswith("|") or not line.endswith("|"):
+        return []
+    cells = []
+    current = []
+    escaped = False
+    for char in line[1:-1]:
+        if escaped:
+            current.append(char)
+            escaped = False
+        elif char == "\\":
+            escaped = True
+        elif char == "|":
+            cells.append("".join(current).strip())
+            current = []
+        else:
+            current.append(char)
+    cells.append("".join(current).strip())
+    return cells
+
+
+def target_keys(row):
+    source_type = normalize_text(row.get("source_type", "")).casefold()
+    keyword = normalize_text(row.get("keyword", "")).casefold()
+    entrypoint = normalize_text(row.get("entrypoint", "")).casefold()
+    name = normalize_text(row.get("name", "")).casefold()
+    keys = []
+    if source_type and keyword:
+        keys.append((source_type, "keyword", keyword))
+    if source_type and entrypoint and name:
+        keys.append((source_type, "entrypoint-name", entrypoint, name))
+    return keys
+
+
+def assign_ids(rows, prefixes, existing_mapping, used_original_ids):
+    used_ids = set()
+    next_ids = {}
+    for source_type, values in used_original_ids.items():
+        next_ids[source_type] = max(values) + 1 if values else 1
+
+    for row in rows:
+        preserved = None
+        for key in target_keys(row):
+            preserved = existing_mapping.get(key)
+            if preserved:
+                break
+        source_type = row["source_type"]
+        prefix = prefixes[source_type]
+        if preserved and preserved.get("id") and preserved["id"] not in used_ids:
+            row["id"] = preserved["id"]
+            row["original_id"] = preserved.get("original_id", row.get("original_id", ""))
+        elif row.get("id") and row["id"] not in used_ids:
+            row["original_id"] = row.get("original_id") or strip_prefix(row["id"], prefix)
+        else:
+            next_value = next_ids.get(source_type, 1)
+            while next_value in used_original_ids[source_type]:
+                next_value += 1
+            row["original_id"] = str(next_value)
+            row["id"] = f"{prefix}{next_value}"
+            used_original_ids[source_type].add(next_value)
+            next_ids[source_type] = next_value + 1
+        if not row["original_id"].isdigit():
+            raise SystemExit(f"Row '{row['name']}' has non-numeric original_id: {row['original_id']}")
+        expected_prefix = prefixes[source_type]
+        expected_id = f"{expected_prefix}{row['original_id']}"
+        if row["id"] != expected_id:
+            raise SystemExit(
+                f"Row '{row['name']}' id does not match source_type prefix and original_id: "
+                f"{row['id']} != {expected_id}"
+            )
+        if row["id"] in used_ids:
+            raise SystemExit(f"Duplicate id after assignment: {row['id']}")
+        used_ids.add(row["id"])
+    return rows
+
+
+def strip_prefix(value, prefix):
+    value = normalize_text(value)
+    if value.startswith(prefix):
+        return value[len(prefix) :]
+    return ""
+
+
+def normalize_summary(rows):
+    normalized = []
+    for index, row in enumerate(rows, 1):
+        item = {column: normalize_text(row_get(row, column)) for column in SUMMARY_COLUMNS}
+        for column in ("raw_count", "eligible_count", "excluded_count", "gap_count"):
+            if item[column] == "":
+                raise SystemExit(f"Summary row {index}: missing {column}")
+            if not item[column].isdigit():
+                raise SystemExit(f"Summary row {index}: {column} must be a non-negative integer")
+        raw = int(item["raw_count"])
+        eligible = int(item["eligible_count"])
+        excluded = int(item["excluded_count"])
+        gap = int(item["gap_count"])
+        if raw != eligible + excluded + gap:
+            raise SystemExit(
+                f"Summary row {index}: raw_count must equal eligible_count + excluded_count + gap_count"
+            )
+        normalized.append(item)
+    return normalized
+
+
+def normalize_coverage(rows):
+    normalized = []
+    for row in rows:
+        item = {column: normalize_text(row_get(row, column)) for column in COVERAGE_COLUMNS}
+        if any(item.values()):
+            normalized.append(item)
+    return normalized
+
+
+def validate_main_counts(rows, summary_rows):
+    main_count = len(rows)
+    eligible_count = sum(int(row["eligible_count"]) for row in summary_rows)
+    if eligible_count != main_count:
+        raise SystemExit(
+            f"Eligible count mismatch: summary eligible_count total is {eligible_count}, "
+            f"but main target rows are {main_count}."
+        )
+
+
+def is_canonical_queue_output(output_path):
+    return (
+        output_path.name == "docs-target-queue.md"
+        and output_path.parent.name.casefold() == "docs"
+    )
+
+
+def is_target_staging_output(output_path):
+    return (
+        output_path.suffix.lower() == ".md"
+        and "target" in {part.casefold() for part in output_path.parts}
+    )
+
+
+def validate_output_path(output_path, partial_output):
+    if is_canonical_queue_output(output_path):
+        return
+    if partial_output and is_target_staging_output(output_path):
+        return
+    if partial_output:
+        raise SystemExit(
+            "--partial-output only permits staging Markdown output under target/**. "
+            "Final queue output must be docs/docs-target-queue.md."
+        )
+    raise SystemExit(
+        "Final queue output must be docs/docs-target-queue.md. "
+        "For partial candidates, pass --partial-output and write under "
+        "target/docs-target-queue-from-catalog/."
+    )
+
+
+def build_obsidian_links(output_path):
+    links = []
+    if output_path.name == "docs-target-queue.md":
+        catalog_path = output_path.with_name("docs-target-catalog.md")
+        if catalog_path.exists():
+            links.append("- [[docs-target-catalog]]")
+    return links
+
+
+def build_markdown(rows, summary_rows, coverage_rows, source_note, output_path):
+    lines = []
+    lines.extend(["# Documentation Target Queue", ""])
+    lines.append(f"Source note: {source_note}")
+    obsidian_links = build_obsidian_links(output_path)
+    if obsidian_links:
+        lines.extend(["", "## Obsidian Links", ""])
+        lines.extend(obsidian_links)
+    lines.extend(["", "## Source Acquisition Summary", ""])
+    append_table(lines, SUMMARY_COLUMNS, summary_rows)
+    lines.extend(["", "## Main Target Table", ""])
+    append_table(lines, MAIN_COLUMNS, rows)
+    lines.extend(["", "## Source-Type Counts", ""])
+    count_rows = []
+    counts = defaultdict(int)
+    for row in rows:
+        counts[row["source_type"]] += 1
+    for source_type in sorted(counts):
+        count_rows.append({"source_type": source_type, "count": str(counts[source_type])})
+    count_rows.append({"source_type": "Total", "count": str(len(rows))})
+    append_table(lines, ["source_type", "count"], count_rows)
+    lines.extend(["", "## Coverage Review", ""])
+    append_table(lines, COVERAGE_COLUMNS, coverage_rows)
+    lines.append("")
+    return "\n".join(lines)
+
+
+def append_table(lines, columns, rows):
+    lines.append("| " + " | ".join(columns) + " |")
+    lines.append("| " + " | ".join("---" for _ in columns) + " |")
+    for row in rows:
+        values = [markdown_escape(row.get(column, "")) for column in columns]
+        lines.append("| " + " | ".join(values) + " |")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate docs/docs-target-queue.md from normalized target, summary, and coverage inputs."
+    )
+    parser.add_argument("--targets", required=True, help="CSV/TSV/JSON/JSONL normalized target rows.")
+    parser.add_argument("--summary", required=True, help="CSV/TSV/JSON/JSONL source acquisition summary rows.")
+    parser.add_argument("--coverage", help="CSV/TSV/JSON/JSONL coverage review rows.")
+    parser.add_argument("--existing", help="Existing docs/docs-target-queue.md used to preserve IDs.")
+    parser.add_argument("--output", required=True, help="Output docs/docs-target-queue.md path.")
+    parser.add_argument("--source-note", required=True, help="Short source note for the generated Markdown.")
+    parser.add_argument(
+        "--partial-output",
+        action="store_true",
+        help=(
+            "Allow writing a partial/staging Markdown output under target/**. "
+            "Final output remains docs/docs-target-queue.md."
+        ),
+    )
+    parser.add_argument(
+        "--prefix",
+        action="append",
+        default=[],
+        help=(
+            "Registration extension for a source_type prefix in source_type=PREFIX form. "
+            "Use for activation surfaces not yet in the shared registry. May be repeated."
+        ),
+    )
+    parser.add_argument(
+        "--write-normalized-targets",
+        help="Optional CSV path for the post-validation target rows with assigned IDs.",
+    )
+    args = parser.parse_args()
+
+    output = Path(args.output)
+    validate_output_path(output, args.partial_output)
+
+    prefixes = parse_prefix_args(args.prefix)
+    targets = normalize_targets(read_rows(args.targets), prefixes)
+    summary = normalize_summary(read_rows(args.summary))
+    coverage = normalize_coverage(read_rows(args.coverage) if args.coverage else [])
+    existing_mapping, used_original_ids = parse_existing_ids(args.existing)
+    targets = assign_ids(targets, prefixes, existing_mapping, used_original_ids)
+    targets = sort_targets_by_source_type(targets)
+    validate_main_counts(targets, summary)
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(build_markdown(targets, summary, coverage, args.source_note, output), encoding="utf-8", newline="\n")
+    if args.write_normalized_targets:
+        write_csv(args.write_normalized_targets, targets, MAIN_COLUMNS)
+    print(f"Wrote {output} with {len(targets)} target rows.")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BrokenPipeError:
+        sys.exit(1)

package/.github/skills/source-code-to-ops-spec-guidelines/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: source-code-to-ops-spec-guidelines
+description: 在產生、維護、重構或審查 source-code-backed ops SPEC guideline contract 與 reference guideline 時使用。適用於調整 `SKILL.md`、`references/01-system-overview-and-business-scenarios-guideline.md`、`references/02-core-architecture-flow-data-logic-guideline.md`、`references/03-error-ops-scenario-coverage-guideline.md`、圖表可讀性、Metadata、Mermaid syntax、維運導向 SPEC 章節契約、source evidence discipline 與 mixed-language documentation rules。
+---
+
+# Source Code-backed Ops SPEC Guideline Maintainer
+
+## 核心用途
+
+使用這個 skill 來產生、維護、重構或審查 source-code-backed ops SPEC 的 guideline contract 與 reference guideline。它不是用來直接產出某一份最終系統文件；它負責維護「AI 如何根據 source code、SQL、config、DB object、runtime evidence 與既有文件產生維運導向 SPEC」的 guideline contract。
+
+輸出與說明使用繁體中文。Source code、class names、method names、variable names、API paths、SQL、database objects、YAML/JSON/XML keys、CLI commands、Git commands、protocol names、tool names、prompt placeholders、Markdown syntax 與 Mermaid syntax 必須保留英文或原始語法。
+
+## Reference Guidelines
+
+本 skill 的主要 reference guideline 是以下三份。Supporting reference 負責跨三份 target SPEC 共用的文件基礎與輸出格式，不是第四份輸出文件。
+
+| Reference | Responsibility |
+|---|---|
+| `references/01-system-overview-and-business-scenarios-guideline.md` | 系統單元概述、使用者問題與業務場景。 |
+| `references/02-core-architecture-flow-data-logic-guideline.md` | 系統責任邊界、進入點、處理流程、資料關聯、資料流向、SQL、狀態、詳細邏輯與資料對應。 |
+| `references/03-error-ops-scenario-coverage-guideline.md` | 錯誤處理、連動影響、log、監控、troubleshooting、維運操作資訊、情境專屬覆蓋與安全證據。 |
+| `references/supporting-output-format-diagram-and-example-reference.md` | Supporting reference；維護跨三份 SPEC 的文件定位、系統單元型態、章節適用判斷、Metadata、Obsidian Links、章節編號原則、圖表可讀性、Mermaid / ASCII Art 語法、圖表文字說明、系統功能規格書 Metadata variant，以及歷史範例整理出的格式規則；本檔不是第四份輸出文件。 |
+
+若未來新增 reference、prompt、agent 或 generated-output contract，必須先確認檔案存在與責任邊界，再把它們加入本 skill。
+
+## Reference Routing
+
+先判斷使用者正在修改哪一種 ops SPEC guideline contract，再只載入相關 reference。
+
+| Goal | Load first | Then load if needed |
+|---|---|---|
+| 調整跨三份 SPEC 的文件定位、Metadata、Obsidian Links、系統單元型態或章節適用判斷 | `references/supporting-output-format-diagram-and-example-reference.md` | The owner guideline for the chapter where the rule is applied |
+| 調整系統概述、使用者問題或業務場景 | `references/01-system-overview-and-business-scenarios-guideline.md` | `references/supporting-output-format-diagram-and-example-reference.md` if shared document foundation or Metadata is affected |
+| 調整架構、流程、資料、SQL、狀態或 step-by-step logic | `references/02-core-architecture-flow-data-logic-guideline.md` | `references/supporting-output-format-diagram-and-example-reference.md` if diagram syntax or examples are affected |
+| 調整錯誤、監控、troubleshooting、維運操作或情境覆蓋 | `references/03-error-ops-scenario-coverage-guideline.md` | `references/02-core-architecture-flow-data-logic-guideline.md` if flow-level error behavior must stay aligned |
+| 調整 Mermaid、ASCII Art、圖表文字說明或範例語法 | `references/supporting-output-format-diagram-and-example-reference.md` | The owner guideline for the chapter where the rule is applied |
+| Review guideline drift or stale references | `SKILL.md` plus the suspected owner guideline | Other guidelines only if cross-reference text must be aligned |
+
+不要因為 skill 觸發就全文載入所有 reference。先看任務目標與檔名，再做 progressive loading。
+
+## Generation Usage
+
+若 generation workflow 使用本 skill 產生 target-facing SPEC，必須先套用 `references/supporting-output-format-diagram-and-example-reference.md` 中跨三份 SPEC 的文件基礎規則，再依 `generation_scope` 載入對應 reference guideline；不要把 single-scope invocation 擴大成 all-scope generation。
+
+| `generation_scope` | Required reference guideline |
+|---|---|
+| `all` | 依序套用 `references/supporting-output-format-diagram-and-example-reference.md` 的共用文件基礎規則，再載入 `references/01-system-overview-and-business-scenarios-guideline.md`、`references/02-core-architecture-flow-data-logic-guideline.md`、`references/03-error-ops-scenario-coverage-guideline.md`。 |
+| `foundation` | 套用 `references/supporting-output-format-diagram-and-example-reference.md` 的共用文件基礎規則，並載入 `references/01-system-overview-and-business-scenarios-guideline.md`；架構、資料、錯誤與維運內容若影響 foundation 判斷，保留 source-backed cross-reference、handoff 與必要證據線索，但不把其他 scope 的正式章節複製到本文件。 |
+| `architecture` | 套用 `references/supporting-output-format-diagram-and-example-reference.md` 的共用文件基礎規則，並載入 `references/02-core-architecture-flow-data-logic-guideline.md`；foundation 與 ops 內容若影響 architecture 判斷，保留 source-backed cross-reference、handoff 與必要證據線索，但不把其他 scope 的正式章節複製到本文件。 |
+| `ops` | 套用 `references/supporting-output-format-diagram-and-example-reference.md` 的共用文件基礎規則，並載入 `references/03-error-ops-scenario-coverage-guideline.md`；foundation 與 architecture 內容若影響 ops 判斷，保留 source-backed cross-reference、handoff 與必要證據線索，但不把其他 scope 的正式章節複製到本文件。 |
+
+若任務只維護某一份主要 guideline 且不涉及共用文件基礎，可先載入該 owner guideline；涉及 target-facing SPEC generation、Metadata、Obsidian Links、章節適用或圖表格式時，必須載入 `references/supporting-output-format-diagram-and-example-reference.md`。
+
+`doc_file_plan` 用來記錄 generation scope、selected output files、章節 `N/A` / `Unresolved` 原因、coverage gaps 與 handoff impact；reference 檔案選擇以本 skill 的 Reference Routing 為準。
+
+Target-facing SPEC 的內容優先順序是完整、準確、source-backed，其次才是篇幅壓縮或版面簡潔。摘要、維運摘要卡、圖表文字說明、handoff summary 或 cross-reference 只能協助導覽，不可取代正式詳細章節；若來源可確認 handler、service、DAO / Repository / Mapper、SQL、table、status transition、config、job、file I/O 或 external integration 行為，應在對應 scope 的章節保留可審查細節。
+
+Target-facing SPEC 以業務行為、處理流程、資料規則、錯誤處理與維運判斷方式為主。Source path、line、symbol 與 `EvidenceRef[]` 由 `source-code-to-spec-documenter` 的 `handoff.json` 保存；文件本身只在內容需要時保留必要識別資料，例如 API path、SQL ID、table、status column、job name、config key、file name、log keyword 或 trace id，且應整合到對應章節的操作、資料、狀態或錯誤欄位中。
+
+`doc_profile=full` 代表 selected scope 內採完整深度，不是把 source-backed detail 壓成摘要。Full profile 至少應保留：
+
+- 可從 source 讀取的完整 SQL excerpt；若 SQL 是動態組合，保留 source-backed pseudo SQL、組合條件、參數來源與限制。
+- DAO / Repository / Mapper method 與 SQL、table、status column、DB object、stored routine 或 external resource 的 mapping。
+- Handler / controller / job / service 到 DAO method 的可追蹤流程，以及與維運判斷有關的 branch、transaction、rollback、retry、rerun、log、error message 與 status transition。
+- 欄位 mapping、狀態 mapping、request / response mapping、file column mapping 或 external payload mapping 的來源欄位、目標欄位、轉換規則與限制。
+
+不要因為流程、SQL、圖表或資料 mapping 較大就刪減 source-backed detail；必要時拆成多個表格、子章節或多張圖表，並讓每一段都可追溯到 source evidence。
+
+Target-facing SPEC 的每一個正式章節都應保留章節標題。若該章節沒有來源資料、已確認不適用，或目前來源不足以填寫，不要硬湊表格、圖表或推測內容；在章節下方輸出一行 `N/A: <簡短原因>`、`無法由目前來源確認: <缺少的 evidence>` 或 `Unresolved: <阻塞原因>` 即可，並將 completion-impacting gap 寫入 handoff。
+
+Target-facing SPEC 的 generation / update 執行流程、source tracing、idempotent update、handoff 欄位與 queue 狀態不由本 skill 維護；請使用 `source-code-to-spec-documenter/references/generation-workflow.md`、`source-code-to-spec-documenter/references/source-tracing-rules.md`、`source-code-to-spec-documenter/references/generation-handoff-contract.md` 與 `source-code-to-spec-documenter/references/target-queue-contract.md`。
+
+## Ownership Boundary
+
+維護 guideline contract 時，先找 owner，再改 owner。避免同一條規則散落在多份文件中。
+
+| Rule Type | Owner |
+|---|---|
+| Skill trigger、reference routing、共通維護流程、品質門檻 | `SKILL.md` |
+| Cross-SPEC document positioning、system unit type、section applicability、Metadata、Obsidian Links、chapter numbering | `references/supporting-output-format-diagram-and-example-reference.md` |
+| Overview、user problems、business scenarios | `references/01-system-overview-and-business-scenarios-guideline.md` |
+| Responsibility boundary、entry points、processing flow、data relationship、data flow、SQL、status、steps、mapping | `references/02-core-architecture-flow-data-logic-guideline.md` |
+| Error handling、side effects、logs、monitoring、troubleshooting、operations、scenario coverage、security evidence | `references/03-error-ops-scenario-coverage-guideline.md` |
+| Diagram accessibility、Mermaid syntax caveats、ASCII Art fallback、example tables、system-function-spec Metadata variant | `references/supporting-output-format-diagram-and-example-reference.md` |
+| Existing output reconciliation、idempotent update、handoff coverage status | `source-code-to-spec-documenter/references/source-tracing-rules.md` 與 `source-code-to-spec-documenter/references/generation-handoff-contract.md` |
+
+若一條規則會影響多份 guideline，應在 owner 中維護完整規則，其他文件只保留簡短 cross-reference。
+
+## Guideline Maintenance Workflow
+
+1. 先檢查目前 repo 實際存在的檔案，不要加入未經確認的 phantom references。
+2. 判斷變更屬於哪個 owner guideline；如果規則已存在，優先原地優化，不新增重複章節。
+3. 保持 `SKILL.md` 精簡，只放 trigger、routing、owner boundary、workflow 與 quality gate；詳細寫作規則放到 reference guideline。
+4. 修改 guideline 時，保留正式產出章節與 guideline-only 說明的分界。不要讓「欄位說明」、「撰寫要求」、「圖表規則」被誤產到最終文件。
+5. 保留 Markdown table、code fence、Mermaid fence、placeholder、technical identifier 與 machine-readable syntax。
+6. 若新增圖表、流程或範例規則，確認每張圖表後都有結構化文字說明要求。
+7. 若來源不足，guideline 應要求標示 `N/A`、`無法由目前來源確認`、`unknown` 或 `Unresolved`，不得鼓勵 AI 補完不存在的行為。
+8. 不要把歷史範例中的示意 table、狀態值、API、Job 或 DB object 當成真實 source evidence；只能作為格式與顆粒度範例。
+
+## Diagram and Metadata Rules
+
+圖表與 Metadata 的補充規則放在 `references/supporting-output-format-diagram-and-example-reference.md`。維護任一 guideline 時，至少要遵守以下共通規則：
+
+- 每張 Mermaid、ASCII Art、ERD、UML、flowchart、sequenceDiagram、classDiagram 或其他圖表後面，必須立即附上 `> 📝 **圖表文字說明**` blockquote。
+- 圖表文字說明必須可獨立閱讀；即使 diagram 無法 render，讀者仍能理解架構、流程、資料關聯、分支結果與維運線索。
+- 圖表負責視覺化，圖表文字說明負責補足完整脈絡；兩者共同構成必填內容。
+- Mermaid `sequenceDiagram` 失敗或例外訊息優先使用 `-x`，避免使用不穩定的 `A--xB` 寫法。
+- Mermaid `erDiagram` 的 PK/FK 標示必須使用雙引號，例如 `string PRODUCT_ID "PK"`。
+- Metadata 與 `## Obsidian Links` 規則以 `references/supporting-output-format-diagram-and-example-reference.md` 為主；若任務明確要求「系統功能規格書」格式，使用同一 supporting reference 的 Metadata variant。
+
+## Quality Gate
+
+完成變更前檢查：
+
+- `SKILL.md` frontmatter 只有有效的 `name` 與 `description`。
+- `SKILL.md` 沒有引用不存在的 reference、prompt、agent 或 generated output。
+- 每條規則落在正確 owner guideline，沒有在多處複製成 drift 來源。
+- 三份主要 guideline 的使用順序仍清楚：supporting document foundation → foundation/business → architecture/flow/data/logic → error/ops/scenario coverage。
+- 圖表規則仍要求 diagram 後方緊接結構化文字說明。
+- Detail policy 仍要求 source-backed full detail；摘要、圖表或 cross-reference 沒有取代正式詳細章節。
+- File I/O / Report evidence 的欄位主規格由 `02` 的 `6.5 檔案 I/O 規格` 擁有；`03` 只補維運覆蓋，不得取代 `02` 的欄位表。
+- Metadata 規則沒有混淆 guideline 文件格式與 final SPEC 文件格式。
+- Source evidence discipline 由 handoff 承接，target-facing guideline 只要求必要內容與維運判斷方式。
+- 繁體中文敘述與必要 English technical identifiers 都被保留。
+- Markdown tables、code fences、Mermaid syntax、links 與 placeholders 仍可讀且未被翻譯破壞。
+
+若 validator 可用，針對 skill 目錄執行 skill validation；若沒有 validator，至少用 `git diff --check` 檢查 Markdown 空白與格式問題。