@elvis1513/auto-coding-skill 0.3.0 → 1.0.1

package/cli/assets/skill/scripts/ap.py

@@ -8,9 +8,9 @@ import argparse
 import base64
 import datetime as _dt
 import json
-import os
 import time
 import urllib.parse
+import urllib.error
 import urllib.request
 from pathlib import Path
 from typing import Optional, List
@@ -18,6 +18,10 @@ from typing import Optional, List
 from core import APError, ensure_git_repo, copy_tree, run, load_yaml, find_config, run_shell, http_get_status
 
 
+_JENKINS_CRUMB_CACHE: dict[str, dict[str, str]] = {}
+_INVALID_PLACEHOLDERS = {"N/A", "TODO", "TBD", "CHANGEME", "CHANGE_ME", "FILL_ME", "FILL-ME", "PLACEHOLDER", "XXX"}
+
+
 def _skill_root() -> Path:
     return Path(__file__).resolve().parent.parent
 
@@ -56,29 +60,150 @@ def _run_configured_command(repo: Path, cfg: dict, name: str) -> bool:
 
 def _jenkins_basic_auth_headers(cfg: dict) -> dict:
     jenkins_cfg = (cfg.get("jenkins") or {})
-    direct_user = str(jenkins_cfg.get("api_user") or "").strip()
-    direct_token = str(jenkins_cfg.get("api_token") or "").strip()
-    user_env = str(jenkins_cfg.get("api_user_env") or "JENKINS_USER").strip() or "JENKINS_USER"
-    token_env = str(jenkins_cfg.get("api_token_env") or "JENKINS_TOKEN").strip() or "JENKINS_TOKEN"
-    user = direct_user or os.getenv(user_env) or os.getenv("JENKINS_USER")
-    token = direct_token or os.getenv(token_env) or os.getenv("JENKINS_TOKEN") or os.getenv("JENKINS_PASSWORD")
-    if not user or not token:
+    user_candidates = [
+        jenkins_cfg.get("api_user"),
+        jenkins_cfg.get("ui_username"),
+    ]
+    secret_candidates = [
+        jenkins_cfg.get("api_password"),
+        jenkins_cfg.get("ui_password"),
+    ]
+    user = next((_text(v) for v in user_candidates if _is_explicit_fill(v)), "")
+    secret = next((_text(v) for v in secret_candidates if _is_explicit_fill(v)), "")
+    if not user or not secret:
         raise APError(
-            f"Missing Jenkins API credentials. Fill jenkins.api_user / jenkins.api_token in docs/ENGINEERING.md, "
-            f"or set env vars {user_env} and {token_env}."
+            "Missing Jenkins API credentials. Fill jenkins.api_user and jenkins.api_password in docs/ENGINEERING.md."
         )
-    raw = f"{user}:{token}".encode("utf-8")
+    raw = f"{user}:{secret}".encode("utf-8")
+    auth = base64.b64encode(raw).decode("ascii")
+    return {"Authorization": f"Basic {auth}"}
+
+
+def _http_error_body(exc: urllib.error.HTTPError) -> str:
+    try:
+        return exc.read().decode("utf-8", errors="replace").strip()
+    except Exception:
+        return ""
+
+
+def _http_get(url: str, headers: Optional[dict[str, str]] = None, timeout_s: int = 10) -> tuple[int, str]:
+    req = urllib.request.Request(url, headers=headers or {}, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as response:
+            return response.status, response.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read().decode("utf-8", errors="replace")
+
+
+def _basic_auth_header(username: str, password: str) -> dict[str, str]:
+    raw = f"{username}:{password}".encode("utf-8")
     auth = base64.b64encode(raw).decode("ascii")
     return {"Authorization": f"Basic {auth}"}
 
 
-def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15) -> dict:
+def _jenkins_root_url(cfg: dict, job_url: str = "") -> str:
+    jenkins_cfg = (cfg.get("jenkins") or {})
+    base_url = str(jenkins_cfg.get("base_url") or "").strip().rstrip("/")
+    if base_url:
+        return base_url
+
+    source = str(job_url or jenkins_cfg.get("job_url") or "").strip().rstrip("/")
+    if not source:
+        return ""
+    if "/job/" in source:
+        return source.split("/job/", 1)[0].rstrip("/")
+    return source
+
+
+def _jenkins_crumb_api_url(cfg: dict, job_url: str = "") -> str:
+    root = _jenkins_root_url(cfg, job_url=job_url)
+    if not root:
+        return ""
+    return root.rstrip("/") + "/crumbIssuer/api/json"
+
+
+def _jenkins_crumb_headers(cfg: dict, job_url: str = "", timeout_s: int = 15) -> dict:
+    crumb_url = _jenkins_crumb_api_url(cfg, job_url=job_url)
+    if not crumb_url:
+        return {}
+    cached = _JENKINS_CRUMB_CACHE.get(crumb_url)
+    if cached:
+        return dict(cached)
+
+    headers = {"Accept": "application/json"}
+    headers.update(_jenkins_basic_auth_headers(cfg))
+    req = urllib.request.Request(crumb_url, headers=headers, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            data = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return {}
+        body = _http_error_body(exc)
+        raise APError(
+            f"Jenkins crumb request failed: {crumb_url}\n"
+            f"HTTP {exc.code}\n{body or '(empty response body)'}"
+        ) from exc
+    except Exception as exc:
+        raise APError(f"Jenkins crumb request failed: {crumb_url}\n{exc}") from exc
+
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise APError(f"Jenkins crumb endpoint returned non-JSON response: {crumb_url}\n{exc}") from exc
+
+    field = str(payload.get("crumbRequestField") or "").strip()
+    crumb = str(payload.get("crumb") or "").strip()
+    if not field or not crumb:
+        return {}
+
+    crumb_headers = {field: crumb}
+    _JENKINS_CRUMB_CACHE[crumb_url] = crumb_headers
+    return dict(crumb_headers)
+
+
+def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15, allow_404: bool = False) -> Optional[dict]:
     headers = {"Accept": "application/json"}
     headers.update(_jenkins_basic_auth_headers(cfg))
     req = urllib.request.Request(url, headers=headers, method="GET")
     try:
         with urllib.request.urlopen(req, timeout=timeout_s) as resp:
             data = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = _http_error_body(exc)
+        if exc.code == 404 and allow_404:
+            return None
+        if exc.code == 403:
+            crumb_headers = _jenkins_crumb_headers(cfg, job_url=url, timeout_s=timeout_s)
+            if crumb_headers:
+                retry_headers = dict(headers)
+                retry_headers.update(crumb_headers)
+                retry_req = urllib.request.Request(url, headers=retry_headers, method="GET")
+                try:
+                    with urllib.request.urlopen(retry_req, timeout=timeout_s) as resp:
+                        data = resp.read().decode("utf-8")
+                except urllib.error.HTTPError as retry_exc:
+                    if retry_exc.code == 404 and allow_404:
+                        return None
+                    retry_body = _http_error_body(retry_exc)
+                    raise APError(
+                        f"Jenkins API request failed after crumb retry: {url}\n"
+                        f"HTTP {retry_exc.code}\n{retry_body or '(empty response body)'}"
+                    ) from retry_exc
+                except Exception as retry_exc:
+                    raise APError(f"Jenkins API request failed after crumb retry: {url}\n{retry_exc}") from retry_exc
+            else:
+                    raise APError(
+                        f"Jenkins API request failed: {url}\n"
+                        f"HTTP 403\n{body or '(empty response body)'}\n"
+                        "Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
+                    "Fill jenkins.base_url in docs/ENGINEERING.md if needed."
+                    ) from exc
+        else:
+            raise APError(
+                f"Jenkins API request failed: {url}\n"
+                f"HTTP {exc.code}\n{body or '(empty response body)'}"
+            ) from exc
     except Exception as exc:
         raise APError(f"Jenkins API request failed: {url}\n{exc}") from exc
     try:
@@ -95,6 +220,14 @@ def _resolve_git_short_sha(repo: Path, ref: str) -> str:
     return ref.strip()
 
 
+def _resolve_git_branch_name(repo: Path, ref: str) -> str:
+    result = run(["git", "rev-parse", "--abbrev-ref", ref], cwd=repo, check=False)
+    value = result.stdout.strip()
+    if value and value != "HEAD":
+        return value
+    return ""
+
+
 def _jenkins_builds_api_url(job_url: str, max_builds: int) -> str:
     base = str(job_url or "").strip().rstrip("/")
     if not base:
@@ -103,6 +236,139 @@ def _jenkins_builds_api_url(job_url: str, max_builds: int) -> str:
     return f"{base}/api/json?tree={urllib.parse.quote(tree, safe='=,')}"
 
 
+def _jenkins_job_path(job_name: str) -> str:
+    parts = [p.strip() for p in str(job_name or "").split("/") if p.strip()]
+    if not parts:
+        raise APError("Jenkins job name is empty. Pass --job-name or fill jenkins.job_name.")
+    return "/".join(f"job/{urllib.parse.quote(part, safe='')}" for part in parts)
+
+
+def _jenkins_job_url_from_name(base_url: str, job_name: str) -> str:
+    base = str(base_url or "").strip().rstrip("/")
+    if not base:
+        raise APError("Missing Jenkins base URL. Fill jenkins.base_url or pass --job-url.")
+    return f"{base}/{_jenkins_job_path(job_name)}"
+
+
+def _jenkins_branch_job_candidates(branch_name: str) -> List[str]:
+    raw = str(branch_name or "").strip()
+    if not raw:
+        return []
+
+    candidates: List[str] = []
+
+    def add(value: str) -> None:
+        if value and value not in candidates:
+            candidates.append(value)
+
+    if "/" not in raw:
+        add(urllib.parse.quote(raw, safe=""))
+    single = urllib.parse.quote(raw, safe="")
+    double = urllib.parse.quote(single, safe="")
+    add(single)
+    add(double)
+    return candidates
+
+
+def _jenkins_branch_job_urls(root_job_url: str, branch_name: str) -> List[str]:
+    base = str(root_job_url or "").strip().rstrip("/")
+    if not base:
+        raise APError("Missing Jenkins multibranch root job URL.")
+    urls: List[str] = []
+    for candidate in _jenkins_branch_job_candidates(branch_name):
+        url = f"{base}/job/{candidate}"
+        if url not in urls:
+            urls.append(url)
+    return urls
+
+
+def _resolve_jenkins_job_url(cfg: dict, job_name: str = "", job_url: str = "") -> str:
+    jenkins_cfg = (cfg.get("jenkins") or {})
+    explicit_url = str(job_url or "").strip()
+    requested_name = str(job_name or "").strip()
+    configured_url = str(jenkins_cfg.get("job_url") or "").strip()
+    base_url = str(jenkins_cfg.get("base_url") or "").strip()
+
+    if explicit_url:
+        return explicit_url.rstrip("/")
+    if requested_name:
+        if base_url:
+            return _jenkins_job_url_from_name(base_url, requested_name)
+        raise APError(
+            f"Cannot resolve Jenkins job URL for job '{requested_name}'. "
+            "Pass --job-url, or fill jenkins.base_url in docs/ENGINEERING.md."
+        )
+    if configured_url:
+        return configured_url.rstrip("/")
+    raise APError(
+        "Missing Jenkins job location. Fill jenkins.job_url in docs/ENGINEERING.md, "
+        "or pass --job-url / --job-name explicitly."
+    )
+
+
+def _resolve_jenkins_job_candidates(
+    cfg: dict,
+    repo: Path,
+    git_ref: str = "",
+    job_name: str = "",
+    job_url: str = "",
+    multibranch_root_job: str = "",
+    branch_name: str = "",
+) -> List[str]:
+    jenkins_cfg = (cfg.get("jenkins") or {})
+    effective_branch = str(branch_name or "").strip()
+    if not effective_branch:
+        inferred_branch = _resolve_git_branch_name(repo, git_ref or "HEAD")
+        if inferred_branch:
+            effective_branch = inferred_branch
+
+    effective_root = str(multibranch_root_job or "").strip()
+    explicit_url = str(job_url or "").strip()
+    explicit_name = str(job_name or "").strip()
+    configured_url = str(jenkins_cfg.get("job_url") or "").strip()
+
+    if effective_branch:
+        if explicit_url:
+            return _jenkins_branch_job_urls(explicit_url, effective_branch)
+        if effective_root:
+            base_url = str(jenkins_cfg.get("base_url") or "").strip()
+            return _jenkins_branch_job_urls(_jenkins_job_url_from_name(base_url, effective_root), effective_branch)
+        if explicit_name:
+            base_url = str(jenkins_cfg.get("base_url") or "").strip()
+            return _jenkins_branch_job_urls(_jenkins_job_url_from_name(base_url, explicit_name), effective_branch)
+        if configured_url:
+            return _jenkins_branch_job_urls(configured_url, effective_branch)
+        raise APError(
+            "Missing Jenkins multibranch root job location. Pass --job-url / --job-name together with "
+            "--branch-name, or pass --multibranch-root-job with jenkins.base_url."
+        )
+
+    return [_resolve_jenkins_job_url(cfg, job_name=job_name, job_url=job_url)]
+
+
+def _jenkins_build_api_url(job_url: str, build_number: int) -> str:
+    base = str(job_url or "").strip().rstrip("/")
+    if not base:
+        raise APError("Missing Jenkins job URL.")
+    if build_number <= 0:
+        raise APError("Build number must be a positive integer.")
+    tree = "number,result,building,description,url"
+    return f"{base}/{build_number}/api/json?tree={urllib.parse.quote(tree, safe='=,')}"
+
+
+def _assert_jenkins_build_success(build: dict, identifier: str, allow_no_deploy: bool) -> tuple[str, str]:
+    if build.get("building"):
+        raise APError(f"Jenkins build is still running: {identifier}")
+
+    result = str(build.get("result") or "").strip().upper()
+    description = str(build.get("description") or "").strip()
+    if result != "SUCCESS":
+        raise APError(f"Jenkins build did not succeed: {identifier} result={result or '(empty)'}")
+    if not allow_no_deploy and description.startswith("no-deploy:"):
+        raise APError(f"Jenkins build succeeded but did not deploy: {identifier} {description}")
+    return result, description
+
+
 def cmd_install(args: argparse.Namespace) -> None:
     repo = Path(args.repo).resolve()
     templates = _skill_root() / "data" / "templates"
@@ -119,17 +385,8 @@ def cmd_install(args: argparse.Namespace) -> None:
     copy_tree(Path(__file__).resolve().parent / "core.py", tools_dir / "core.py")
     copy_tree(Path(__file__).resolve().parent / "http_checks.py", tools_dir / "http_checks.py")
 
-    gi = repo / ".gitignore"
-    secret_line = "docs/ENGINEERING.md"
-    if gi.exists():
-        txt = gi.read_text(encoding="utf-8")
-        if secret_line not in txt:
-            gi.write_text(txt.rstrip() + "\n" + secret_line + "\n", encoding="utf-8")
-    else:
-        gi.write_text(secret_line + "\n", encoding="utf-8")
-
     print(f"[install] OK: scaffold installed into {repo}")
-    print("[install] Next: edit docs/ENGINEERING.md frontmatter and fill project/runtime/jenkins fields")
+    print("[install] Next: edit docs/ENGINEERING.md frontmatter, fill all platform credentials, and commit that file into Git.")
 
 
 def _infer_title(taskbook: Path, task_id: str) -> str:
@@ -160,7 +417,7 @@ def cmd_gen_summary(args: argparse.Namespace) -> None:
     if out_file.exists() and not args.force:
         raise APError(f"Summary already exists: {out_file} (use --force to overwrite)")
 
-    title = _infer_title(taskbook, task_id)
+    title = str(args.title or "").strip() or _infer_title(taskbook, task_id)
     date = _dt.date.today().isoformat()
 
     staged = run(["git", "diff", "--cached", "--name-only"], cwd=repo, check=False).stdout.strip()
@@ -169,6 +426,8 @@ def cmd_gen_summary(args: argparse.Namespace) -> None:
 
     content = f"""# Task Summary — {task_id} — {title}
 
+> 仅用于高风险、跨模块、阶段性里程碑、需要完整复盘的任务。
+
 - Task ID：{task_id}
 - Date：{date}
 - Scope（本次范围）：TODO
@@ -180,7 +439,7 @@ def cmd_gen_summary(args: argparse.Namespace) -> None:
 - 目标：TODO
 - 验收结论：PASS / FAIL — TODO
 
-## 2. 变更概览（代码/配置/本地运行/Jenkins）
+## 2. 变更概览
 ### Git change snapshot
 - Staged files:
 {('- ' + staged.replace('\n','\n- ')) if staged else '- (none)'}
@@ -194,19 +453,19 @@ def cmd_gen_summary(args: argparse.Namespace) -> None:
 ## 3. 接口变更（以 API Markdown 为准）
 - 变更记录位置：`{api_change_log}`
 
-## 5. 质量门禁证据（必须可追溯）
-- 后端测试：`commands.test` — TODO
-- 前端构建：`commands.build` — TODO
-- 静态分析：`commands.lint` — TODO
-- 前端类型检查：`commands.typecheck` — TODO
-- Review 文档：TODO
-- DD 文档：TODO
-- Jenkins 准备：TODO
-- 回归矩阵：`{regression_matrix}`（全量 PASS，0 fail，且每项必须有真实证据）
-
-## 6. 本地运行与 Jenkins 部署记录
-- Local compose：TODO
-- Jenkins build / deploy：TODO
+## 4. 质量证据
+- 本地轻量校验：build / test or quick_test / lint / typecheck / api docs / jenkinsfile / diff-check — TODO
+- Jenkins Build：TODO
+- 目标环境验证：TODO
+- 闭环记录：TODO
+- 回归矩阵（如有）：`{regression_matrix}`
+
+## 5. 风险与回滚
+- 风险：TODO
+- 回滚：TODO
+
+## 6. 后续行动
+- TODO：TODO
 """
 
     out_file.write_text(content, encoding="utf-8")
@@ -281,6 +540,49 @@ def _load_cfg(repo: Path) -> dict:
     return load_yaml(cfg_path)
 
 
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _is_placeholder(value: object) -> bool:
+    return _text(value).upper() in _INVALID_PLACEHOLDERS
+
+
+def _is_explicit_fill(value: object) -> bool:
+    return bool(_text(value)) and not _is_placeholder(value)
+
+
+def _validate_url_field(errors: List[str], field: str, value: object) -> None:
+    raw = _text(value)
+    parsed = urllib.parse.urlparse(raw)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        errors.append(f"{field} must be a valid http/https URL")
+
+
+def _validate_path_field(errors: List[str], field: str, value: object) -> None:
+    raw = _text(value)
+    if not raw.startswith("/"):
+        errors.append(f"{field} must start with '/'")
+
+
+def _require_explicit_field(missing: List[str], field: str, value: object) -> None:
+    raw = _text(value)
+    if not _is_explicit_fill(raw):
+        missing.append(f"{field} (must be explicitly filled, not blank/TODO)")
+
+
+def _run_git_diff_check(repo: Path, cfg: dict) -> None:
+    commands = (cfg.get("commands") or {})
+    configured = str(commands.get("diff_check") or "").strip()
+    if configured:
+        print(f"[diff-check] {configured}")
+        run_shell(configured, cwd=repo)
+    else:
+        print("[diff-check] git diff --check")
+        run(["git", "diff", "--check"], cwd=repo)
+    print("[diff-check] OK")
+
+
 def cmd_run(args: argparse.Namespace) -> None:
     """
     Run any configured gate command by name.
@@ -302,6 +604,62 @@ def cmd_run(args: argparse.Namespace) -> None:
     print(f"[run] OK: {name}")
 
 
+def cmd_light_gate(args: argparse.Namespace) -> None:
+    repo = Path(args.repo).resolve()
+    cmd_doctor(argparse.Namespace(repo=str(repo)))
+    cfg = _load_cfg(repo)
+    commands = (cfg.get("commands") or {})
+
+    executed: List[str] = []
+    missing: List[str] = []
+
+    if not str(commands.get("build") or "").strip():
+        missing.append("commands.build")
+    else:
+        _run_configured_command(repo, cfg, "build")
+        executed.append("build")
+
+    if str(commands.get("quick_test") or "").strip():
+        _run_configured_command(repo, cfg, "quick_test")
+        executed.append("quick_test")
+    elif str(commands.get("test") or "").strip():
+        _run_configured_command(repo, cfg, "test")
+        executed.append("test")
+    else:
+        missing.append("commands.quick_test or commands.test")
+
+    static_executed = False
+    if str(commands.get("lint") or "").strip():
+        _run_configured_command(repo, cfg, "lint")
+        executed.append("lint")
+        static_executed = True
+
+    if str(commands.get("typecheck") or "").strip():
+        _run_configured_command(repo, cfg, "typecheck")
+        executed.append("typecheck")
+        static_executed = True
+
+    if not static_executed:
+        missing.append("commands.lint or commands.typecheck")
+
+    if str(commands.get("script_syntax") or "").strip():
+        _run_configured_command(repo, cfg, "script_syntax")
+        executed.append("script_syntax")
+
+    if missing:
+        raise APError(
+            "Light gate is under-configured. Missing required commands: "
+            + ", ".join(missing)
+            + ". Edit docs/ENGINEERING.md frontmatter."
+        )
+
+    _run_git_diff_check(repo, cfg)
+    cmd_verify_api_docs(argparse.Namespace(repo=str(repo)))
+    cmd_verify_jenkins(argparse.Namespace(repo=str(repo)))
+    executed.extend(["diff_check", "verify_api_docs", "verify_jenkins"])
+    print("[light-gate] OK: " + ", ".join(executed))
+
+
 def cmd_runtime_up(args: argparse.Namespace) -> None:
     repo = Path(args.repo).resolve()
     cfg = _load_cfg(repo)
@@ -338,10 +696,13 @@ def cmd_wait_health(args: argparse.Namespace) -> None:
         url = _join_url(str(runtime_cfg.get("health_base_url") or ""), str(runtime_cfg.get("health_path") or ""))
         timeout_s = int(runtime_cfg.get("startup_timeout_sec") or 120)
     else:
+        target_cfg = (cfg.get("target_env") or {})
         jenkins_cfg = (cfg.get("jenkins") or {})
+        base_url = str(target_cfg.get("health_base_url") or "")
+        path = str(target_cfg.get("health_path") or "")
         url = _join_url(
-            str(jenkins_cfg.get("prod_health_base_url") or ""),
-            str(jenkins_cfg.get("prod_health_path") or "")
+            base_url,
+            path,
         )
         timeout_s = int(jenkins_cfg.get("deploy_timeout_sec") or 1800)
 
@@ -360,24 +721,74 @@ def cmd_wait_health(args: argparse.Namespace) -> None:
     raise APError(f"Health check timeout for {scope}: {url}\nLast result: {last_error}")
 
 
+def cmd_verify_target(args: argparse.Namespace) -> None:
+    repo = Path(args.repo).resolve()
+    cfg = _load_cfg(repo)
+    target_cfg = (cfg.get("target_env") or {})
+
+    cmd_wait_health(argparse.Namespace(repo=str(repo), scope="target"))
+
+    checks: List[str] = []
+
+    backend_base = str(target_cfg.get("backend_base_url") or "").strip().rstrip("/")
+    frontend_base = str(target_cfg.get("frontend_base_url") or "").strip().rstrip("/")
+
+    backend_headers: dict[str, str] = {}
+    frontend_headers: dict[str, str] = {}
+    if args.backend_basic_auth:
+        user = str(target_cfg.get("backend_username") or "").strip()
+        password = str(target_cfg.get("backend_password") or "").strip()
+        if not user or not password:
+            raise APError("Missing target_env.backend_username / target_env.backend_password for backend basic auth.")
+        backend_headers = _basic_auth_header(user, password)
+    if args.frontend_basic_auth:
+        user = str(target_cfg.get("frontend_username") or "").strip()
+        password = str(target_cfg.get("frontend_password") or "").strip()
+        if not user or not password:
+            raise APError("Missing target_env.frontend_username / target_env.frontend_password for frontend basic auth.")
+        frontend_headers = _basic_auth_header(user, password)
+
+    for path in args.backend_path or []:
+        if not backend_base:
+            raise APError("Missing target_env.backend_base_url for backend path verification.")
+        url = _join_url(backend_base, path)
+        status, body = _http_get(url, headers=backend_headers, timeout_s=10)
+        if not (200 <= status < 400):
+            raise APError(f"Backend target verification failed: {url} -> {status}\n{body[:400]}")
+        checks.append(f"backend:{url}->{status}")
+
+    for path in args.frontend_path or []:
+        if not frontend_base:
+            raise APError("Missing target_env.frontend_base_url for frontend path verification.")
+        url = _join_url(frontend_base, path)
+        status, body = _http_get(url, headers=frontend_headers, timeout_s=10)
+        if not (200 <= status < 400):
+            raise APError(f"Frontend target verification failed: {url} -> {status}\n{body[:400]}")
+        checks.append(f"frontend:{url}->{status}")
+
+    summary = ", ".join(checks) if checks else "health-only"
+    print(f"[verify-target] OK: {summary}")
+
+
 def cmd_verify_jenkins(args: argparse.Namespace) -> None:
     repo = Path(args.repo).resolve()
     cfg = _load_cfg(repo)
     project_cfg = (cfg.get("project") or {})
     jenkins_cfg = (cfg.get("jenkins") or {})
+    target_cfg = (cfg.get("target_env") or {})
     jenkinsfile = Path(repo, str(project_cfg.get("jenkinsfile") or "Jenkinsfile"))
     if not jenkinsfile.exists():
         raise APError(f"Jenkinsfile not found: {jenkinsfile}")
 
     required = [
-        ("jenkins.job_name", jenkins_cfg.get("job_name")),
+        ("jenkins.base_url", jenkins_cfg.get("base_url")),
         ("jenkins.job_url", jenkins_cfg.get("job_url")),
         ("jenkins.trigger_branch", jenkins_cfg.get("trigger_branch")),
         ("jenkins.image_repository", jenkins_cfg.get("image_repository")),
         ("jenkins.image_tag_strategy", jenkins_cfg.get("image_tag_strategy")),
         ("jenkins.deploy_env", jenkins_cfg.get("deploy_env")),
-        ("jenkins.prod_health_base_url", jenkins_cfg.get("prod_health_base_url")),
-        ("jenkins.prod_health_path", jenkins_cfg.get("prod_health_path")),
+        ("target_env.health_base_url", target_cfg.get("health_base_url")),
+        ("target_env.health_path", target_cfg.get("health_path")),
     ]
     missing = [name for name, value in required if not str(value or "").strip()]
     if missing:
@@ -385,60 +796,188 @@ def cmd_verify_jenkins(args: argparse.Namespace) -> None:
     print(f"[verify-jenkins] OK: {jenkinsfile}")
 
 
-def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
+def cmd_doctor(args: argparse.Namespace) -> None:
     repo = Path(args.repo).resolve()
     cfg = _load_cfg(repo)
+    project_cfg = (cfg.get("project") or {})
+    commands = (cfg.get("commands") or {})
+    target_cfg = (cfg.get("target_env") or {})
     jenkins_cfg = (cfg.get("jenkins") or {})
-    job_url = str(jenkins_cfg.get("job_url") or "").strip()
-    if not job_url:
-        raise APError("Missing jenkins.job_url in docs/ENGINEERING.md")
+    docs_cfg = (cfg.get("docs") or {})
+    runtime_cfg = (cfg.get("runtime") or {})
+
+    missing: List[str] = []
+    warnings: List[str] = []
+
+    if not str(project_cfg.get("name") or "").strip():
+        missing.append("project.name")
+    if not str(commands.get("build") or "").strip():
+        missing.append("commands.build")
+    if not (str(commands.get("quick_test") or "").strip() or str(commands.get("test") or "").strip()):
+        missing.append("commands.quick_test or commands.test")
+    if not (str(commands.get("lint") or "").strip() or str(commands.get("typecheck") or "").strip()):
+        missing.append("commands.lint or commands.typecheck")
+    _require_explicit_field(missing, "target_env.name", target_cfg.get("name"))
+    _require_explicit_field(missing, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
+    _require_explicit_field(missing, "target_env.frontend_username", target_cfg.get("frontend_username"))
+    _require_explicit_field(missing, "target_env.frontend_password", target_cfg.get("frontend_password"))
+    _require_explicit_field(missing, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
+    _require_explicit_field(missing, "target_env.backend_username", target_cfg.get("backend_username"))
+    _require_explicit_field(missing, "target_env.backend_password", target_cfg.get("backend_password"))
+    _require_explicit_field(missing, "target_env.health_base_url", target_cfg.get("health_base_url"))
+    _require_explicit_field(missing, "target_env.health_path", target_cfg.get("health_path"))
+
+    _require_explicit_field(missing, "jenkins.base_url", jenkins_cfg.get("base_url"))
+    _require_explicit_field(missing, "jenkins.ui_username", jenkins_cfg.get("ui_username"))
+    _require_explicit_field(missing, "jenkins.ui_password", jenkins_cfg.get("ui_password"))
+    _require_explicit_field(missing, "jenkins.job_url", jenkins_cfg.get("job_url"))
+    _require_explicit_field(missing, "jenkins.trigger_branch", jenkins_cfg.get("trigger_branch"))
+    _require_explicit_field(missing, "jenkins.image_repository", jenkins_cfg.get("image_repository"))
+    _require_explicit_field(missing, "jenkins.image_tag_strategy", jenkins_cfg.get("image_tag_strategy"))
+    _require_explicit_field(missing, "jenkins.deploy_env", jenkins_cfg.get("deploy_env"))
+    _require_explicit_field(missing, "jenkins.api_user", jenkins_cfg.get("api_user"))
+    _require_explicit_field(missing, "jenkins.api_password", jenkins_cfg.get("api_password"))
+
+    repo_docs = {
+        "docs.taskbook": Path(repo, str(docs_cfg.get("taskbook", "docs/tasks/taskbook.md"))),
+        "docs.closure_log": Path(repo, str(docs_cfg.get("closure_log", "docs/tasks/closure-log.md"))),
+        "docs.api_doc": Path(repo, str(docs_cfg.get("api_doc", "docs/interfaces/api.md"))),
+        "docs.api_change_log": Path(repo, str(docs_cfg.get("api_change_log", "docs/interfaces/api-change-log.md"))),
+    }
+    for key, path in repo_docs.items():
+        if not path.exists():
+            warnings.append(f"{key} missing on disk: {path}")
+
+    _validate_url_field(warnings, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
+    _validate_url_field(warnings, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
+    _validate_url_field(warnings, "target_env.health_base_url", target_cfg.get("health_base_url"))
+    _validate_path_field(warnings, "target_env.health_path", target_cfg.get("health_path"))
+    _validate_url_field(warnings, "jenkins.base_url", jenkins_cfg.get("base_url"))
+    _validate_url_field(warnings, "jenkins.job_url", jenkins_cfg.get("job_url"))
+
+    runtime_enabled = any(str(runtime_cfg.get(key) or "").strip() for key in ["docker_compose_file", "docker_service", "health_base_url", "health_path"])
+    if runtime_enabled and not (str(commands.get("compose_up") or "").strip() or str(runtime_cfg.get("docker_compose_file") or "").strip()):
+        warnings.append("runtime config is partially enabled but compose_up or docker_compose_file is missing")
+
+    try:
+        timeout_s = int(jenkins_cfg.get("deploy_timeout_sec") or 0)
+        if timeout_s <= 0:
+            warnings.append("jenkins.deploy_timeout_sec must be a positive integer")
+    except Exception:
+        warnings.append("jenkins.deploy_timeout_sec must be a positive integer")
+
+    if warnings:
+        missing.extend([f"invalid {item}" for item in warnings])
+
+    if missing:
+        raise APError("Doctor found blocking config issues:\n- " + "\n- ".join(missing))
+
+    print("[doctor] OK")
+
 
+def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
+    repo = Path(args.repo).resolve()
+    cfg = _load_cfg(repo)
+    jenkins_cfg = (cfg.get("jenkins") or {})
     git_ref = str(args.git_ref or "HEAD").strip()
-    git_short_sha = _resolve_git_short_sha(repo, git_ref)
+    candidate_job_urls = _resolve_jenkins_job_candidates(
+        cfg,
+        repo,
+        git_ref=git_ref,
+        job_name=args.job_name,
+        job_url=args.job_url,
+        multibranch_root_job=args.multibranch_root_job,
+        branch_name=args.branch_name,
+    )
+    build_number = args.build_number
     max_builds = int(args.max_builds or 20)
     timeout_s = int(args.timeout_sec or 300)
     poll_s = int(args.poll_sec or 5)
+    inferred_branch = _resolve_git_branch_name(repo, git_ref)
+    branch_hint = str(args.branch_name or inferred_branch or "").strip()
+    root_hint = str(
+        args.multibranch_root_job
+        or args.job_name
+        or args.job_url
+        or jenkins_cfg.get("job_url")
+        or ""
+    ).strip()
+    if branch_hint and root_hint:
+        job_label = f"{root_hint}/{branch_hint}"
+    else:
+        job_label = branch_hint or root_hint or "(configured)"
 
     deadline = time.time() + timeout_s
+    if build_number is not None:
+        payload = None
+        while time.time() < deadline:
+            payload = None
+            for candidate_job_url in candidate_job_urls:
+                api_url = _jenkins_build_api_url(candidate_job_url, int(build_number))
+                payload = _jenkins_api_get_json(api_url, cfg, allow_404=True)
+                if payload is not None:
+                    break
+            if payload is not None and not payload.get("building"):
+                break
+            time.sleep(poll_s)
+        if not payload:
+            raise APError(
+                f"No Jenkins build payload found for build #{build_number} under any candidate job URL. "
+                f"Checked for up to {timeout_s}s."
+            )
+        if payload.get("building"):
+            raise APError(
+                f"Jenkins build is still running: "
+                f"#{payload.get('number')} {payload.get('url')}"
+            )
+        result, description = _assert_jenkins_build_success(
+            payload,
+            f"#{payload.get('number')} {payload.get('url')}",
+            args.allow_no_deploy,
+        )
+        print(
+            "[verify-jenkins-build] OK: "
+            f"job={job_label} "
+            f"build=#{payload.get('number')} "
+            f"result={result} "
+            f"description={description} "
+            f"url={payload.get('url')}"
+        )
+        return
+
+    git_short_sha = _resolve_git_short_sha(repo, git_ref)
     matched = None
-    api_url = _jenkins_builds_api_url(job_url, max_builds)
 
     while time.time() < deadline:
-        payload = _jenkins_api_get_json(api_url, cfg)
-        builds = payload.get("builds") or []
-        matched = next((b for b in builds if git_short_sha in str(b.get("description") or "")), None)
+        matched = None
+        for candidate_job_url in candidate_job_urls:
+            api_url = _jenkins_builds_api_url(candidate_job_url, max_builds)
+            payload = _jenkins_api_get_json(api_url, cfg, allow_404=True)
+            if payload is None:
+                continue
+            builds = payload.get("builds") or []
+            matched = next((b for b in builds if git_short_sha in str(b.get("description") or "")), None)
+            if matched:
+                break
         if matched and not matched.get("building"):
             break
         time.sleep(poll_s)
 
     if not matched:
         raise APError(
-            f"No Jenkins build found for commit {git_short_sha} under {job_url}. "
+            f"No Jenkins build found for commit {git_short_sha} under any candidate job URL. "
             f"Checked latest {max_builds} builds for up to {timeout_s}s."
         )
 
-    if matched.get("building"):
-        raise APError(
-            f"Jenkins build for commit {git_short_sha} is still running: "
-            f"#{matched.get('number')} {matched.get('url')}"
-        )
-
-    result = str(matched.get("result") or "").strip().upper()
-    description = str(matched.get("description") or "").strip()
-    if result != "SUCCESS":
-        raise APError(
-            f"Jenkins build for commit {git_short_sha} did not succeed: "
-            f"#{matched.get('number')} result={result or '(empty)'} {matched.get('url')}"
-        )
-    if not args.allow_no_deploy and description.startswith("no-deploy:"):
-        raise APError(
-            f"Jenkins build for commit {git_short_sha} succeeded but did not deploy: "
-            f"#{matched.get('number')} {description}"
-        )
-
+    result, description = _assert_jenkins_build_success(
+        matched,
+        f"#{matched.get('number')} {matched.get('url')}",
+        args.allow_no_deploy,
+    )
     print(
         "[verify-jenkins-build] OK: "
         f"commit={git_short_sha} "
+        f"job={job_label} "
         f"build=#{matched.get('number')} "
         f"result={result} "
         f"description={description} "
@@ -459,26 +998,69 @@ def cmd_verify_api_docs(args: argparse.Namespace) -> None:
     print(f"[verify-api-docs] OK: {api_doc} + {change_log}")
 
 
-def cmd_commit_push(args: argparse.Namespace) -> None:
+def cmd_record_closure(args: argparse.Namespace) -> None:
     repo = Path(args.repo).resolve()
     ensure_git_repo(repo)
     cfg = _load_cfg(repo)
     docs_cfg = (cfg.get("docs") or {})
-    summary_dir = Path(repo, str(docs_cfg.get("summary_dir", "docs/tasks/summaries")))
+    target_cfg = (cfg.get("target_env") or {})
+    taskbook = Path(repo, str(docs_cfg.get("taskbook", "docs/tasks/taskbook.md")))
+    closure_log = Path(repo, str(docs_cfg.get("closure_log", "docs/tasks/closure-log.md")))
+    closure_log.parent.mkdir(parents=True, exist_ok=True)
+    if not closure_log.exists():
+        closure_log.write_text("# Closure Log\n\n", encoding="utf-8")
 
     task_id = args.task_id
+    title = str(args.title or "").strip() or _infer_title(taskbook, task_id)
+    timestamp = _dt.datetime.now().strftime("%Y-%m-%d %H:%M")
+    commit_value = _resolve_git_short_sha(repo, args.commit)
+    target_env = str(args.target_env or target_cfg.get("name") or "").strip() or "(not set)"
+    verification_items = args.verification or []
+    verification_text = "; ".join(verification_items) if verification_items else "TODO"
+    follow_up = str(args.follow_up or "").strip() or "none"
+    jenkins_build = str(args.jenkins or "").strip() or "TODO"
+
+    lines = [
+        f"## {task_id} — {title} — {timestamp}",
+        f"- Task: {task_id}",
+        f"- Commit: {commit_value}",
+        f"- Jenkins Build: {jenkins_build}",
+        f"- Target Env: {target_env}",
+        f"- Verification: {verification_text}",
+        f"- Result: {args.result}",
+        f"- Follow-up: {follow_up}",
+    ]
+    if str(args.initial_commit or "").strip():
+        lines.append(f"- Initial Commit: {args.initial_commit.strip()}")
+    if str(args.jenkins_failure or "").strip():
+        lines.append(f"- Jenkins Failure: {args.jenkins_failure.strip()}")
+    if str(args.fix_commit or "").strip():
+        lines.append(f"- Fix Commit: {args.fix_commit.strip()}")
+
+    with closure_log.open("a", encoding="utf-8") as f:
+        if closure_log.stat().st_size > 0:
+            f.write("\n")
+        f.write("\n".join(lines))
+        f.write("\n")
+    print(f"[record-closure] OK: {closure_log}")
+
+
+def cmd_commit_push(args: argparse.Namespace) -> None:
+    repo = Path(args.repo).resolve()
+    ensure_git_repo(repo)
+    cmd_doctor(argparse.Namespace(repo=str(repo)))
+
     msg = args.msg
 
-    summary = summary_dir / f"{task_id}.md"
-    if not summary.exists():
-        raise APError(
-            f"Task summary missing: {summary}\n"
-            f"Generate: python3 docs/tools/autopipeline/ap.py gen-summary {task_id}"
-        )
+    if args.record_closure and not args.result:
+        raise APError("When using --record-closure, --result is required.")
 
     if args.require_runtime_health:
         cmd_wait_health(argparse.Namespace(repo=str(repo), scope="runtime"))
 
+    if args.require_light_gate:
+        cmd_light_gate(argparse.Namespace(repo=str(repo)))
+
     if args.require_jenkins:
         cmd_verify_jenkins(argparse.Namespace(repo=str(repo)))
 
@@ -492,6 +1074,23 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
 
     run(["git", "commit", "-m", msg], cwd=repo)
     run(["git", "push"], cwd=repo)
+    if args.record_closure:
+        cmd_record_closure(
+            argparse.Namespace(
+                repo=str(repo),
+                task_id=args.task_id,
+                title=args.title,
+                commit="HEAD",
+                jenkins=args.jenkins_build,
+                target_env=args.target_env,
+                verification=args.verification,
+                result=args.result,
+                follow_up=args.follow_up,
+                initial_commit=args.initial_commit,
+                jenkins_failure=args.jenkins_failure,
+                fix_commit=args.fix_commit,
+            )
+        )
     print("[commit-push] OK - push completed, Jenkins should auto-trigger")
 
 
@@ -506,6 +1105,7 @@ def main(argv: Optional[List[str]] = None) -> int:
 
     s = sp.add_parser("gen-summary")
     s.add_argument("task_id")
+    s.add_argument("--title")
     s.add_argument("--force", action="store_true")
     s.set_defaults(func=cmd_gen_summary)
 
@@ -516,6 +1116,12 @@ def main(argv: Optional[List[str]] = None) -> int:
     s.add_argument("name")
     s.set_defaults(func=cmd_run)
 
+    s = sp.add_parser("light-gate")
+    s.set_defaults(func=cmd_light_gate)
+
+    s = sp.add_parser("doctor")
+    s.set_defaults(func=cmd_doctor)
+
     s = sp.add_parser("runtime-up")
     s.set_defaults(func=cmd_runtime_up)
 
@@ -523,14 +1129,19 @@ def main(argv: Optional[List[str]] = None) -> int:
     s.set_defaults(func=cmd_runtime_down)
 
     s = sp.add_parser("wait-health")
-    s.add_argument("--scope", choices=["runtime", "prod"], default="runtime")
+    s.add_argument("--scope", choices=["runtime", "target", "prod"], default="runtime")
     s.set_defaults(func=cmd_wait_health)
 
     s = sp.add_parser("verify-jenkins")
     s.set_defaults(func=cmd_verify_jenkins)
 
     s = sp.add_parser("verify-jenkins-build")
-    s.add_argument("--git-ref", default="HEAD")
+    s.add_argument("--git-ref")
+    s.add_argument("--job-name")
+    s.add_argument("--job-url")
+    s.add_argument("--multibranch-root-job")
+    s.add_argument("--branch-name")
+    s.add_argument("--build-number", type=int)
     s.add_argument("--max-builds", type=int, default=20)
     s.add_argument("--timeout-sec", type=int, default=300)
     s.add_argument("--poll-sec", type=int, default=5)
@@ -540,12 +1151,44 @@ def main(argv: Optional[List[str]] = None) -> int:
     s = sp.add_parser("verify-api-docs")
     s.set_defaults(func=cmd_verify_api_docs)
 
+    s = sp.add_parser("verify-target")
+    s.add_argument("--backend-path", action="append")
+    s.add_argument("--frontend-path", action="append")
+    s.add_argument("--backend-basic-auth", action="store_true")
+    s.add_argument("--frontend-basic-auth", action="store_true")
+    s.set_defaults(func=cmd_verify_target)
+
+    s = sp.add_parser("record-closure")
+    s.add_argument("task_id")
+    s.add_argument("--title")
+    s.add_argument("--commit", default="HEAD")
+    s.add_argument("--jenkins")
+    s.add_argument("--target-env")
+    s.add_argument("--verification", action="append")
+    s.add_argument("--result", choices=["PASS", "FAIL", "PARTIAL"], required=True)
+    s.add_argument("--follow-up")
+    s.add_argument("--initial-commit")
+    s.add_argument("--jenkins-failure")
+    s.add_argument("--fix-commit")
+    s.set_defaults(func=cmd_record_closure)
+
     s = sp.add_parser("commit-push")
     s.add_argument("task_id")
+    s.add_argument("--title")
     s.add_argument("--msg", required=True)
+    s.add_argument("--require-light-gate", action="store_true")
     s.add_argument("--require-runtime-health", action="store_true")
     s.add_argument("--require-jenkins", action="store_true")
     s.add_argument("--require-matrix", action="store_true")
+    s.add_argument("--record-closure", action="store_true")
+    s.add_argument("--jenkins-build")
+    s.add_argument("--target-env")
+    s.add_argument("--verification", action="append")
+    s.add_argument("--result", choices=["PASS", "FAIL", "PARTIAL"])
+    s.add_argument("--follow-up")
+    s.add_argument("--initial-commit")
+    s.add_argument("--jenkins-failure")
+    s.add_argument("--fix-commit")
     s.set_defaults(func=cmd_commit_push)
 
     try: