msdevflow 0.8.4 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {

package/skill/msd/README.md

@@ -420,5 +420,7 @@ typed CLI command
 - [references/ci-and-review.md](references/ci-and-review.md)：CI 和作者 discussion 深层规则。
 - [scripts/openlibing_ci.py](scripts/openlibing_ci.py)：openLiBing 只读诊断与交互 OAuth 客户端。
 - [scripts/gitcode_review.py](scripts/gitcode_review.py)：`code-review` 固定 snapshot/context/finding/lgtm/cleanup 适配器。
-- [scripts/test_openlibing_ci.py](scripts/test_openlibing_ci.py)：openLiBing 无凭证控制流测试。
-- [scripts/test_gitcode_review.py](scripts/test_gitcode_review.py)：GitCode review 适配器的无网络回归测试。
+- [scripts/gitcode_verify.py](scripts/gitcode_verify.py)：`pr`/`ci` 的 PR 回读、评论回读、CI 轮询和监控 helper。
+- [scripts/gitcode_issue.py](scripts/gitcode_issue.py)：`create-issue` 的 schema/标签/里程碑/模板批量只读探测和 Issue 回读 helper。
+
+测试文件（`scripts/test_openlibing_ci.py`、`scripts/test_gitcode_review.py`）只存在于 [源仓库](https://gitcode.com/msbuilder/msdevflow)，不随 npm 包或 skill 安装产物分发；安装目录中没有这两个文件是预期行为。

package/skill/msd/SKILL.md

@@ -127,6 +127,7 @@ discovered -> claimed -> verified -> analyzed -> designed
 - 创建 Issue/PR、评论、触发 CI、resolve 和 merge 前检查幂等状态；`create-issue` 在最终预览确认前禁止远端写入，每个 run 最多执行一次已确认的真实创建，禁止测试 Issue、POST 探测、失败重试或替代 Issue，只在写结果不确定时有界只读恢复；其他写结果不确定时也先回读。
 - `code-review` 的 GitCode 网络访问只能由 `scripts/gitcode_review.py` 执行；helper 输出不完整或能力不足即阻断，不回退现场命令、文本解析或 endpoint 探测。受管 snapshot 必须结束时清理，受管 write receipt 只用于固定 head 上评论写入的幂等恢复。
 - `pr`/`ci` 的 PR 回读、评论回读和 CI 轮询固定使用 `scripts/gitcode_verify.py`，不每轮现场生成 python/PowerShell 内联 JSON 解析；脚本报告 FAIL 或退出码非 0 时按验证失败阻断，先原地修复再回读。
+- `create-issue` 的 schema 探测、标签/里程碑分页和创建后回读固定使用 `scripts/gitcode_issue.py prepare` / `inspect`，不逐条现场调用只读 CLI 命令；批量只读探测走单次 `python` 调用，避免每条命令单独触发权限确认。
 - Agent 写入 GitCode 的 PR 正文、Issue/PR 评论、discussion 回复和其他人类可读正文必须按 [references/state-and-safety.md](references/state-and-safety.md) 在末尾恰好附加一次 `——msdevflow`。
 - 所有人类可读远端文本必须通过 UTF-8 安全通道写入并逐字回读；发现乱码、`?`、截断或尾签损坏时阻断依赖动作，先原地修复。
 - 严格机器协议 payload 保持原样，不把尾签拼进 `compile`、`/lgtm`、`/merge` 等命令。除 `code-review` 检视通过时只发送精确 `/lgtm` 外，其他协议按 [references/state-and-safety.md](references/state-and-safety.md) 发布并验证带尾签的独立人类可读说明。

package/skill/msd/references/command-capabilities.md

@@ -35,7 +35,7 @@ GitCode CLI 版本和命令集合可能不同。工作流必须探测能力，
 <gitcode-command> schema "pr merge"
 ```
 
-若无 schema，对应使用 `<command> --help`。只探测当前 action 所需命令；`create-issue` 至少需要 `milestone list` 的显式 repo、JSON 和分页，`label list` 的显式 repo、JSON 和完整分页，`issue create` 的显式 repo、title、body-file、issue-type、JSON 和 dry-run，`issue view` 的 JSON 回读能力，以及 `issue edit` 的显式 repo、label、title、body-file、milestone number、yes 和 JSON。平台 `issue_type` 不在 typed view 输出时须用已验证的同 CLI 单 Issue GET JSON 回读；类型枚举和名称/ID 映射只采用当前官方文档、CLI 实现或仓库类型配置支持的只读路径，不猜 endpoint。`--issue-type` 的 enterprise 标注不是目标仓库支持证据；类型无法明确设置或回读时在创建前阻断，不能省略参数创建默认 Bug。标签完整分页证明必需标签缺失时也必须阻断，不降级为 `none`。官方 npm GitCode CLI 的 typed `issue create --title` 是 `create-issue` 唯一支持的非 ASCII 标题创建通道；不得调用 `api .../issues --method POST` 测试或创建 Issue。`pr` 至少需要读取关联 Issue 和 PR milestone 的 JSON 能力，以及 `pr edit` 的显式 repo、milestone number 和 JSON；typed `pr create` 不支持 milestone 时，必须在同一次已确认的 PR action 中以 `pr edit --milestone` 关联并回读。`openlibing-auth` 至少需要可有界列举 canonical PR、读取 PR head/labels/comments 的 JSON 能力。完整作者 E2E 记录仓库参数（`-R`/`--repo`）、JSON、body-file/comment-file/stdin、dry-run、fork、assignee、discussion/resolve、正文 edit 和标题 edit 能力。涉及人类可读远端文本时，必须确认 [state-and-safety.md](state-and-safety.md) 要求的 UTF-8 文件、stdin 或 `api --input <utf8-json-file>` 安全通道；Windows PowerShell 5.1 下只有 `--body`/`--comment`/`--title` 等字符串参数而入口为 `.cmd` wrapper 时，不把非 ASCII 文本直接放进命令行参数。
+若无 schema，对应使用 `<command> --help`。只探测当前 action 所需命令；`create-issue` 至少需要 `milestone list` 的显式 repo、JSON 和分页，`label list` 的显式 repo、JSON 和完整分页，`issue create` 的显式 repo、title、body-file、issue-type、JSON 和 dry-run，`issue view` 的 JSON 回读能力，以及 `issue edit` 的显式 repo、label、title、body-file、milestone number、yes 和 JSON。这些只读探测和回读固定通过 `scripts/gitcode_issue.py prepare` / `inspect` 一次完成，不逐条现场调用 schema 和分页命令，避免每条命令单独触发权限确认。平台 `issue_type` 不在 typed view 输出时须用已验证的同 CLI 单 Issue GET JSON 回读；类型枚举和名称/ID 映射只采用当前官方文档、CLI 实现或仓库类型配置支持的只读路径，不猜 endpoint。`--issue-type` 的 enterprise 标注不是目标仓库支持证据；类型无法明确设置或回读时在创建前阻断，不能省略参数创建默认 Bug。标签完整分页证明必需标签缺失时也必须阻断，不降级为 `none`。官方 npm GitCode CLI 的 typed `issue create --title` 是 `create-issue` 唯一支持的非 ASCII 标题创建通道；不得调用 `api .../issues --method POST` 测试或创建 Issue。`pr` 至少需要读取关联 Issue 和 PR milestone 的 JSON 能力，以及 `pr edit` 的显式 repo、milestone number 和 JSON；typed `pr create` 不支持 milestone 时，必须在同一次已确认的 PR action 中以 `pr edit --milestone` 关联并回读。`openlibing-auth` 至少需要可有界列举 canonical PR、读取 PR head/labels/comments 的 JSON 能力。完整作者 E2E 记录仓库参数（`-R`/`--repo`）、JSON、body-file/comment-file/stdin、dry-run、fork、assignee、discussion/resolve、正文 edit 和标题 edit 能力。涉及人类可读远端文本时，必须确认 [state-and-safety.md](state-and-safety.md) 要求的 UTF-8 文件、stdin 或 `api --input <utf8-json-file>` 安全通道；Windows PowerShell 5.1 下只有 `--body`/`--comment`/`--title` 等字符串参数而入口为 `.cmd` wrapper 时，不把非 ASCII 文本直接放进命令行参数。
 
 `code-review` 是能力降级顺序的专用例外：Agent 不直接探测或组合 GitCode 命令，只调用 Skill 随附的 `scripts/gitcode_review.py`。setup 必须验收 `issue view`、`pr view`、`pr comments`、`pr comment` 和 `api`；helper 内部只使用 [code-review.md](code-review.md) 固定的数据路径，以 `pulls/<number>/files` 而不是 typed `pr diff --json` 读取完整 changed-files。helper 的 `snapshot`/`context`/`finding`/`lgtm` 返回能力不足、未知 schema 或不完整响应时，停止为 `blocked: review-capability-required` 或 `review-incomplete`；不得退回 raw CLI、网页 raw URL、`curl`、现场 `python -c`/PowerShell JSON、展示文本 grep 或其他 endpoint 试探。
 

package/skill/msd/references/create-issue.md

@@ -135,17 +135,22 @@ Duplicate search: not performed by design
 
 本 Skill 固定使用 setup 已验收的官方 npm GitCode CLI typed command，不通过 Issue collection API 创建。能力验证只能使用 `schema`、`--help` 和 typed command 自带的 `--dry-run`；`api .../issues --method POST` 没有 dry-run 语义，禁止用于创建、试错或验证。
 
-使用前只读探测：
+使用前只读探测固定使用 Skill 随附脚本一次完成，不逐条现场调用 schema 和分页命令：
 
 ```bash
-<gitcode-command> schema "label list"
-<gitcode-command> schema "milestone list"
-<gitcode-command> schema "issue create"
-<gitcode-command> schema "issue view"
-<gitcode-command> schema "issue edit"
+MSDEVFLOW_GITCODE_COMMAND=<gitcode-command> python <skill-scripts-dir>/gitcode_issue.py prepare <canonical> --template-ref <canonical-remote>/<default-branch>
 ```
 
-必须具备 `issue create --issue-type`、完整的标签分页、同 Issue 标签/里程碑编辑和平台类型 JSON 回读能力；具体类型的适用性仍按“平台类型”核验，不能只看 flag 是否存在。
+该命令一次返回：`issue create`/`issue view`/`issue edit`/`label list`/`milestone list` 的 schema flags、全部分页标签（含精确数量，避免把第一页截断误判为“标签不存在”）、开放里程碑列表，以及 `.gitcode` 模板树。缺少 `issue create --issue-type`、完整标签分页或同 Issue 编辑能力时在创建前阻断；具体类型的适用性仍按“平台类型”核验，不能只看 flag 是否存在。
+
+创建后的权威回读同样固定使用脚本一次完成：
+
+```bash
+MSDEVFLOW_GITCODE_COMMAND=<gitcode-command> python <skill-scripts-dir>/gitcode_issue.py inspect <canonical> <issue-number> \
+  --expect-type <platform-issue-type> --expect-label <required-label> --expect-milestone <milestone-number> --expect-title "<exact-title>"
+```
+
+脚本用 typed `issue view` 加单 Issue GET API 读取平台类型、标签、里程碑和正文，逐项输出 PASS/FAIL，退出码非 0 即回读失败。命令本身不创建、编辑或删除任何远端对象；只有脚本报告全部 PASS 才能继续。
 
 将最终正文写入唯一的系统临时文件，编码固定为 UTF-8 无 BOM。官方 npm GitCode CLI 的 `issue create --title` 是本 Skill 已验收的中文标题通道；Windows `.cmd` wrapper 也直接使用 typed command，不得为中文标题切换到 API POST。最终预览前必须用固定仓库、带前缀标题、正文文件和已验证的平台类型执行本地 dry-run：
 
@@ -175,7 +180,7 @@ dry-run 不得产生新 Issue number/URL；否则视为能力异常并停止。
 
 ## 回读、恢复与完成
 
-创建返回 Issue number/URL 后立即回读目标与类型；仅在该门禁通过后应用已确认元数据，随后再次用权威 JSON 完整验证：
+创建返回 Issue number/URL 后，先用 `gitcode_issue.py inspect` 回读目标与类型；仅在该门禁通过后应用已确认元数据，随后再次运行带 `--expect-*` 的 `inspect` 完整验证：
 
 - repository 和 Issue number/URL；
 - state 为 open；

package/skill/msd/references/pr-and-ci.md

@@ -8,7 +8,7 @@
 
 只读确认：
 
-- Issue 已核验，canonical 默认分支没有闭环实现或重复 PR；
+- Issue 已核验，canonical 默认分支没有闭环实现或重复 PR；用户明确说明本次是不关联 Issue 的独立文档/维护修复时，按下方“独立 PR”执行，不要求 Issue 核验；
 - 当前分支不是默认分支，且基于已确认的 canonical 基线；
 - 任务实现与已确认范围一致；
 - 适用本地门禁有实际通过证据；
@@ -17,6 +17,16 @@
 
 前置条件缺失时返回 `blocked` 和建议的上游 `action=issue` 或 `action=develop`，不得自动补跑。为防止过期证据，提交前复验受影响的最小本地门禁属于 `pr` action。
 
+### 独立 PR（无 Issue）
+
+用户明确说明本次是不关联 Issue 的独立修复（文档文件名/typo/注释、模板或 CI 配置微调等）时，跳过 Issue 接取和核验，不返回 `blocked: issue-required`。要求：
+
+- change_type 记录为 `standalone-docs` 或 `standalone-maintenance`，issue/milestone 均为 `none`；
+- 用户没有明确说明独立修复、改动又明显超出文档/维护范围时，不得自行归类，返回 `blocked` 并建议 `action=issue`；
+- PR 正文关联 Issue 写 `N/A`，不虚构 Issue 编号；仓库模板要求 Issue 关联字段时按模板结构保留 `N/A`；
+- PR milestone 必须为 `none`，不继承、不选择其他里程碑；
+- 仍执行完整 commit 规范、本地门禁、push、PR 创建、回读验证和后续 CI 触发监控；禁止把独立 PR 当理由跳过任何门禁。
+
 ### Commit
 
 只暂存本任务文件，检查凭证和大文件。遵循仓库 commit 规范；无规范时使用 Conventional Commits。贡献规范要求时 sign-off：
@@ -38,6 +48,15 @@ git push -u <source-remote> HEAD:<branch>
 
 默认不 force push。
 
+push 被服务器以 `Git LFS upload failed: missing objects`、`missing or corrupt local objects` 等 LFS 错误拒绝时：
+
+1. 先确认本次待推送 diff 是否包含 LFS tracked 文件（`git lfs ls-files` 对照 `git diff --name-only <remote>/<default>..HEAD`）；
+2. 本次 diff 不含 LFS 文件、缺失对象属于历史数据时，在 guided 模式展示原因并取得用户确认后，使用一次性配置完成本次 push，不写入全局或仓库永久配置：
+   ```bash
+   git -c lfs.allowincompletepush=true push -u <source-remote> HEAD:<branch>
+   ```
+3. 本次 diff 包含 LFS tracked 文件时，不得使用该 bypass；先执行 `git lfs fetch --all` 和 `git lfs fsck` 补齐对象，无法补齐时返回 `blocked` 并报告缺失对象清单。
+
 ### 普通 PR
 
 使用仓库画像从 canonical repository 最新默认分支确认的 PR 模板，保留其标题、章节、检查项和说明，不从 Fork、工作分支或本地未提交文件重新取模板。正文按模板填写背景与 Issue、变更、验证、风险/回滚和未覆盖项；模板缺少必要信息时补入最合适的现有章节，不随意删除模板要求。若仓库没有模板，使用：

package/skill/msd/references/setup-and-issue.md

@@ -72,6 +72,12 @@ pr_number（如已有）
 
 从 URL、Git remotes、remote HEAD 和 PR base 交叉验证。canonical 身份不等于写授权。
 
+source repository 按以下优先级确定：
+1. 用户本轮显式提供的 `source` 优先，不得被本地 remote 自动识别结果覆盖。
+2. 本地 remote 精确匹配该 source 且指向同一仓库时直接复用。
+3. 本地没有匹配 remote 时，允许创建 `fork` remote；若已有同名 remote 但指向不同仓库，生成唯一 remote 名或请求用户确认。
+4. 后续 push 和 PR create 必须使用用户指定的 source，不得因后续 remote 探测结果而静默更换。
+
 ### 仓库画像
 
 读取适用范围的 `AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING*`、README、Issue/PR 模板、OWNERS/CODEOWNERS、CI、pre-commit 和测试配置。PR 模板必须来自 canonical repository 最新默认分支，不得从个人 Fork、当前工作分支或本地未提交文件读取。先检查贡献指南或仓库配置明确指定的路径，再依次检查：

package/skill/msd/references/state-and-safety.md

@@ -97,6 +97,19 @@ Agent 创建或修改的 Issue/PR 正文，以及发布的 Issue 评论、PR 普
 - `code-review` 完整检视通过时只发送正文恰好为 `/lgtm` 的评论，不发布检视摘要、前置说明或其他伴随评论；发送前后都回读并确认 `review_head_sha` 未变化，再逐字回读 `/lgtm`。
 - 尾签只标识文本由 msdevflow 发布，不代表 reviewer/approver 身份，也不替代独立审批或仓库门禁。
 
+### 机器人命令分级
+
+所有必须精确匹配的机器人/机器协议命令按风险分级执行，行为不再依赖临场判断：
+
+| 命令 | 风险级别 | 行为 |
+|---|---|---|
+| `/check-cla`、`/check-sign` 等只读状态重检 | 低风险 | 用户明确要求该命令后，可直接发送精确 payload 并回读，无需前置说明评论 |
+| `compile`、`retry`、`stop` 等 CI 触发命令 | 中风险 | 必须先发布带唯一尾签的独立说明评论并逐字回读，再单独发送精确 payload |
+| `/lgtm` | reviewer 门禁 | 仅 `code-review` 完整检视通过且用户针对当前 PR/head 明确确认后发送精确 payload |
+| `/merge`、`/approve` | 最终合入/审批入口 | 仅 `merge` 阶段、门禁满足且用户确认后发送；作者不得发送 `/approve` |
+
+低风险命令的判定标准：命令只触发只读重检或状态刷新，不启动构建、不改变 PR/Issue 状态、不产生审批语义。不确定分类时按中风险处理（前置说明评论 + 精确 payload），不猜测。仓库机器人协议与该分级冲突时以仓库文档为准并记录适配器证据。
+
 ## 授权范围
 
 `autonomous` 授权至少包含 canonical、Issue、source、branch 和目标。授权只适用于该运行，不能扩展到其他 Issue、PR 或仓库。

package/skill/msd/scripts/gitcode_issue.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Fixed read-only helpers for msd create-issue.
+
+Batches the read-only probes that create-issue otherwise issues as dozens of
+separate CLI calls (schema, full label/milestone pagination, Issue readback),
+so the workflow can invoke one `python` script instead of many gitcode
+commands. Read-only: never creates, edits or deletes anything.
+
+Subcommands:
+  prepare  schema flags + all label pages + all milestone pages + template tree
+  inspect  read back one Issue via typed view and authoritative GET API
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+if os.name == "nt":
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+DEFAULT_PAGE_SIZE = 100
+GITCODE_COMMAND = os.environ.get("MSDEVFLOW_GITCODE_COMMAND", "gitcode")
+
+
+def resolve_command() -> str:
+    selected = shutil.which(GITCODE_COMMAND)
+    if not selected:
+        print(f"gitcode command not found: {GITCODE_COMMAND}", file=sys.stderr)
+        raise SystemExit(3)
+    return selected
+
+
+def invocation(arguments: list[str]) -> list[str]:
+    exe = resolve_command()
+    if os.name == "nt" and Path(exe).suffix.lower() in {".cmd", ".bat"}:
+        # .cmd wrappers cannot be exec'd directly by subprocess.
+        return [
+            "powershell.exe", "-NoProfile", "-Command",
+            "& { $exe = $args[0]; $rest = @($args | Select-Object -Skip 1); & $exe @rest; exit $LASTEXITCODE }",
+            exe, *arguments,
+        ]
+    return [exe, *arguments]
+
+
+def run(args: list[str], allow_failure: bool = False) -> str:
+    result = subprocess.run(
+        invocation(args),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        timeout=180,
+    )
+    if result.returncode != 0:
+        if allow_failure:
+            return ""
+        print(f"{GITCODE_COMMAND} {' '.join(args)} failed: exit {result.returncode}", file=sys.stderr)
+        print(result.stderr[-2000:], file=sys.stderr)
+        raise SystemExit(3)
+    return result.stdout
+
+
+def run_json(args: list[str], allow_failure: bool = False):
+    text = run(args, allow_failure=allow_failure)
+    if not text.strip():
+        return None
+    return json.loads(text)
+
+
+def json_list(value) -> list:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, dict):
+        for key in ("items", "data", "labels", "milestones", "comments"):
+            if isinstance(value.get(key), list):
+                return value[key]
+    return []
+
+
+def page_all(kind: str, repo: str, page_size: int, max_pages: int) -> list:
+    """Read every page of a list command. Stops on empty page, short page
+    (< page_size), repeated page, or max_pages."""
+    seen_page_signatures: set[str] = set()
+    items: list = []
+    for page in range(1, max_pages + 1):
+        payload = run_json(
+            [
+                kind, "list", "-R", repo,
+                "--limit", str(page_size),
+                "--per-page", str(page_size),
+                "--page", str(page),
+                "--json",
+            ]
+        )
+        batch = json_list(payload)
+        signature = json.dumps(sorted(str(item.get("id") or item.get("number")) for item in batch))
+        if not batch:
+            break
+        if signature in seen_page_signatures:
+            print(f"warning: {kind} list page {page} repeats page {page - 1}; stopping", file=sys.stderr)
+            break
+        seen_page_signatures.add(signature)
+        items.extend(batch)
+        if len(batch) < page_size:
+            break
+    return items
+
+
+def cmd_prepare(args: argparse.Namespace) -> int:
+    report: dict = {"repository": args.repo}
+
+    # schema flags for the commands create-issue needs
+    schemas: dict[str, list[str]] = {}
+    for name in ("issue create", "issue view", "issue edit", "label list", "milestone list"):
+        payload = run_json(["schema", name], allow_failure=True)
+        flags = []
+        if isinstance(payload, dict) and isinstance(payload.get("flags"), list):
+            flags = [flag.get("name") for flag in payload["flags"] if isinstance(flag, dict)]
+        schemas[name] = flags
+    report["schemas"] = schemas
+
+    labels = page_all("label", args.repo, args.page_size, args.max_pages)
+    report["labels"] = [item.get("name") for item in labels]
+    report["label_count"] = len(labels)
+
+    milestones = page_all("milestone", args.repo, args.page_size, args.max_pages)
+    report["open_milestones"] = [
+        {
+            "number": item.get("number") or item.get("id"),
+            "title": item.get("title"),
+            "state": item.get("state"),
+            "due_on": item.get("due_on") or item.get("due_date") or "",
+        }
+        for item in milestones
+        if str(item.get("state", "")).lower() in ("active", "open", "")
+    ]
+    report["milestone_count"] = len(milestones)
+
+    if args.template_ref:
+        result = subprocess.run(
+            ["git", "ls-tree", "-r", "--name-only", args.template_ref, "--", ".gitcode"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=120,
+        )
+        report["gitcode_tree"] = (
+            [line for line in result.stdout.splitlines() if line.strip()]
+            if result.returncode == 0
+            else None
+        )
+    else:
+        report["gitcode_tree"] = None
+
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_inspect(args: argparse.Namespace) -> int:
+    view = run_json(["issue", "view", str(args.number), "-R", args.repo, "--json"]) or {}
+    api = run_json(["api", f"repos/{args.repo}/issues/{args.number}"]) or {}
+
+    labels = [l.get("name") if isinstance(l, dict) else l for l in (api.get("labels") or view.get("labels") or [])]
+    type_detail = api.get("issue_type_detail") or {}
+    platform_type = api.get("issue_type") or type_detail.get("title") or ""
+    milestone = api.get("milestone") or view.get("milestone") or {}
+    body = view.get("body") or api.get("body") or ""
+    title = view.get("title") or api.get("title") or ""
+
+    report = {
+        "number": view.get("number") or api.get("number"),
+        "state": view.get("state") or api.get("state"),
+        "title": title,
+        "platform_issue_type": platform_type,
+        "labels": labels,
+        "milestone_number": milestone.get("number"),
+        "milestone_title": milestone.get("title"),
+        "signature_count": body.count("——msdevflow"),
+        "body": body,
+    }
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+
+    ok = True
+
+    def check(condition: bool, label: str) -> None:
+        nonlocal ok
+        ok = ok and condition
+        print(f"{'PASS' if condition else 'FAIL'} {label}")
+
+    check(bool(platform_type), f"platform type present ({platform_type or 'empty'})")
+    check(len(labels) == len(set(labels)), "labels unique")
+    check(report["signature_count"] == 1, f"signature exactly once ({report['signature_count']})")
+    if args.expect_type:
+        check(platform_type == args.expect_type, f"platform type == {args.expect_type}")
+    if args.expect_label:
+        for name in args.expect_label:
+            check(name in labels, f"label present: {name}")
+    if args.expect_milestone is not None:
+        check(milestone.get("number") == args.expect_milestone, f"milestone number == {args.expect_milestone}")
+    if args.expect_title:
+        check(title == args.expect_title, "title verbatim")
+    return 0 if ok else 3
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("prepare", help="batch schema + labels + milestones + template tree")
+    p.add_argument("repo")
+    p.add_argument("--page-size", type=int, default=DEFAULT_PAGE_SIZE)
+    p.add_argument("--max-pages", type=int, default=50)
+    p.add_argument("--template-ref", help="git ref to list .gitcode template tree from, e.g. upstream/HEAD")
+
+    p = sub.add_parser("inspect", help="read back one Issue via view + GET API")
+    p.add_argument("repo")
+    p.add_argument("number", type=int)
+    p.add_argument("--expect-type", help="expected platform issue_type")
+    p.add_argument("--expect-label", action="append", default=[], help="expected label (repeatable)")
+    p.add_argument("--expect-milestone", type=int, help="expected milestone number")
+    p.add_argument("--expect-title", help="expected exact title")
+
+    args = parser.parse_args()
+    if args.command == "prepare":
+        return cmd_prepare(args)
+    return cmd_inspect(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())