@elvis1513/auto-coding-skill 0.2.0 → 1.0.0

package/README.md

@@ -5,9 +5,7 @@ Engineering workflow skill for:
 - Claude Code
 - Codex CLI
 
-This branch is specialized for Go backend + frontend monorepo projects that build Docker images locally, validate with project `docker compose`, and rely on Jenkins to auto-build and update target environments after push.
-It supports both Claude and Codex. During development, it should prefer already available MCP servers, installed skills, plugins, and app connectors for design, research, documentation, verification, and external system updates.
-It should also prefer multi-agent execution whenever the work can be split into parallel subtasks safely.
+This skill targets Go backend + frontend monorepo projects that rely on Jenkins for build and deployment. The optimized default flow is lightweight locally, then Jenkins-first and target-environment-first for real verification.
 
 ## Install
 
@@ -21,6 +19,73 @@ Fallback:
 npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
 ```
 
+## Release Notes
+
+### v0.3.1
+
+- Added Jenkins crumb / CSRF retry support for API verification requests.
+- Added finer-grained Jenkins folder / multibranch pipeline resolution.
+- Added multibranch root job + branch child job support, with current Git branch inference when needed.
+- Kept existing `verify-jenkins-build --git-ref` and direct `--job-url` / `--build-number` flows compatible.
+
+### v0.3.0
+
+- Synced reusable workflow improvements from a production project back into this skill.
+- Moved repo-side helper entrypoint to `docs/tools/autopipeline`.
+- Tightened regression matrix rules: rows start as `TODO`, and `PASS` requires real execution evidence.
+- Added Jenkins API verification flow with credentials sourced from `docs/ENGINEERING.md` or environment variables.
+
+## Optimized Standard Flow
+
+默认闭环：
+
+`需求/任务记录 -> 最小设计 -> 开发 -> 本地轻量校验 -> commit/push -> Jenkins 构建部署 -> 目标环境验证 -> 闭环记录`
+
+具体执行顺序：
+
+1. 需求确认
+   - 明确任务范围、影响服务、是否涉及 API / 数据库 / 部署 / Jenkins / 前端页面。
+2. 最小设计记录
+   - 普通小改动只更新 `taskbook` 或相关设计文档的一小段。
+   - 跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD。
+3. 开发实现
+   - 只修改本次任务必要文件，不做无关重构。
+4. 本地轻量校验
+   - build
+   - 单元测试或关键快速测试
+   - lint / typecheck
+   - API 文档检查
+   - Jenkinsfile / 脚本语法检查
+   - `git diff --check`
+5. 立即提交推送
+   - 本地轻量校验通过后，commit + push，触发 Jenkins。
+6. Jenkins 验证
+   - 看 Jenkins 构建、镜像、部署结果；失败则基于 Jenkins 日志修复并再次提交。
+7. 目标环境验证
+   - 在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
+8. 回归与证据记录
+   - 只有真实执行过 Jenkins / 目标环境验证，或明确要求本地运行验证时，才把 regression matrix 写成 `PASS`。
+9. 闭环记录
+   - 每个任务默认必须留下轻量闭环记录。
+
+## Default vs On-demand
+
+默认不做：
+- 本地 Docker Compose 启动
+- 本地 Docker build
+- 本地完整 smoke / regression
+- 每个小改动强制 `check-matrix`
+- 每个小改动强制生成 summary
+- 未真实执行就要求 regression matrix 全 `PASS`
+- 未真实部署目标环境就生成 deployment record
+
+按需保留：
+- `runtime-up` / `runtime-down`
+- 本地 health / smoke / regression
+- `check-matrix`
+- `gen-summary`
+- deployment runbook / deployment record
+
 ## Standard Workflow
 
 1. Install skill into project:
@@ -42,35 +107,48 @@ python3 .claude/skills/auto-coding-skill/scripts/ap.py --repo . install
 
 - `docs/ENGINEERING.md` frontmatter
 
-This frontmatter is the only manual config source (commands + local Docker runtime + Jenkins + docs paths).
+This frontmatter is the only manual config source.
+
+重点字段：
+- `commands.*`
+- `target_env.*`
+- `jenkins.*`
+- `docs.*`
+
+默认必填：
+- `project.name`
+- `commands.build`
+- `commands.quick_test` 或 `commands.test`
+- `commands.lint` 或 `commands.typecheck`
+- `target_env.name`
+- `target_env.health_base_url`
+- `target_env.health_path`
+- `jenkins.trigger_branch`
+- `jenkins.image_repository`
+- `jenkins.image_tag_strategy`
+- `jenkins.deploy_env`
+- `jenkins.job_url` 或 `jenkins.base_url + jenkins.job_name` 或 `jenkins.base_url + jenkins.multibranch_root_job`
 
 4. Start AI development by constraints:
 
 - `docs/ENGINEERING.md`
 - `docs/tasks/taskbook.md`
-- `docs/design/**`
+- `docs/tasks/closure-log.md`
 - `docs/interfaces/**`
 - `docs/testing/regression-matrix.md`
 - `docs/bugs/bug-list.md`
-- `docs/tasks/summaries/**`
 
 5. Tool selection rule during execution:
 
-- Prefer current MCP/skills/plugins/apps first.
-- Fall back to shell/manual work only when those capabilities are unavailable or insufficient.
+- Prefer current MCP / skills / plugins / apps first.
+- Fall back to shell / manual work only when those capabilities are unavailable or insufficient.
 
 6. Collaboration rule during execution:
 
 - Prefer multi-agent mode.
-- Split research, design, implementation, validation, and documentation into parallel subtasks whenever the boundaries are clear.
+- Split research, design, implementation, verification, and documentation into parallel subtasks whenever the boundaries are clear.
 - Keep one main agent responsible for integration and final gates.
 
-7. Delivery rule during execution:
-
-- Local `docker compose` validation must pass before commit.
-- `git push` is expected to trigger Jenkins automatically.
-- Task is not complete until Jenkins succeeds and the target environment health check passes.
-
 ## AGENTS.md Constraint Example
 
 ```md
@@ -79,90 +157,171 @@ This frontmatter is the only manual config source (commands + local Docker runti
 - Before any code change, read and obey:
   1) docs/ENGINEERING.md
   2) docs/tasks/taskbook.md
-- Execute gates using `python3 scripts/autopipeline/ap.py`.
+- Execute workflow commands using `python3 docs/tools/autopipeline/ap.py`.
 - If required docs are missing, create/update docs first, then code.
+
+## Tooling Policy
+- Prefer currently available MCP servers, installed skills, plugins, and app connectors before shell/manual work.
+- When a connector or MCP can read or write the authoritative source directly, use it instead of retyping or duplicating state.
+
+## Multi-Agent Policy
+- Default to multi-agent execution.
+- Before substantial work, split into parallel subtasks whenever boundaries are clear:
+  1) design / research
+  2) backend implementation
+  3) frontend implementation
+  4) validation / documentation / review
+- Keep one main agent responsible for task framing, integration, quality gates, and final delivery.
+
+## Default Gate Policy
+- Default local gate is lightweight only.
+- Do not require local Docker Compose or full local regression unless the task explicitly needs local runtime diagnosis.
+- Push is not the finish line: Jenkins success, target environment verification, and closure record are mandatory.
 ```
 
 ## Docs Structure and Recording Rules
 
 ### 1) docs/ENGINEERING.md
-- Purpose: single source of project config + engineering gate rules.
-- How to record:
-  - Fill YAML frontmatter once (project/commands/runtime/jenkins/docs fields).
-  - Keep all local runtime and Jenkins info here only (compose file/service/container/image/health/job/env).
-  - Do not duplicate config in other docs.
-
-### 2) docs/deployment/
-- Files:
-  - `docs/deployment/deploy-runbook.md`: local Compose validation + Jenkins deployment procedure.
-  - `docs/deployment/deploy-records/<TASK_ID>-YYYYMMDD.md`: local validation + Jenkins deployment evidence.
+- Purpose: single source of project config + workflow rules.
 - How to record:
-  - Record both local Compose validation and Jenkins deployment evidence: compose file, service, container, image tag, Jenkins build, deploy env, health checks.
+  - Fill YAML frontmatter once.
+  - Keep target env accounts, Jenkins UI/API accounts, commands, docs paths here only.
+  - Do not duplicate config elsewhere.
 
-### 3) docs/design/
-- Files:
-  - `docs/design/<TASK_ID>-<slug>.md` (from DD template).
-- Purpose:
-  - Detailed design before coding (scope,方案、时序图、ER图、接口编排、测试策略、回滚).
+### 2) docs/tasks/taskbook.md
+- Purpose: master task ledger.
 - How to record:
-  - One task/subtask one DD file.
-  - Status changes: Draft -> Reviewed -> Approved.
+  - Every task writes scope, risk, impact area, minimal design note, acceptance, evidence links.
 
-### 4) docs/interfaces/
-- Files:
-  - `docs/interfaces/api.md`: authoritative API documentation (current contract).
-  - `docs/interfaces/api-change-log.md`: append-only API changes per task.
+### 3) docs/tasks/closure-log.md
+- Purpose: default lightweight closure record.
 - How to record:
-  - API changes must update both files in the same task.
-  - `api.md` records latest endpoint contract.
-  - `api-change-log.md` appends task-level delta (新增/修改/废弃/兼容策略/影响面).
+  - Append one record per task.
+  - Required fields: task, commit, Jenkins build, target env verification, result, follow-up.
+  - If Jenkins failed then was fixed, also record failure reason and fix commit.
 
-### 5) docs/reviews/
-- Files:
-  - `docs/reviews/<TASK_ID>-<timestamp>.md` (from review template).
-- Purpose:
-  - Gate review evidence: static checks, Go + frontend quality, local Compose validation, Jenkins readiness, risks.
+### 4) docs/design/
+- Purpose: DD for cross-module / API / DB / deployment / Jenkins / key-page-flow changes.
 - How to record:
-  - Record commands used (lint/typecheck from docs/ENGINEERING.md frontmatter) and conclusion (Pass/Blocked).
+  - Small changes do not need a standalone DD file.
+  - Higher-risk changes create `docs/design/<TASK_ID>-<slug>.md`.
 
-### 6) docs/tasks/
+### 5) docs/interfaces/
 - Files:
-  - `docs/tasks/taskbook.md`: master task ledger (all tasks appended here).
-  - `docs/tasks/summaries/<TASK_ID>.md`: end-of-task summary artifact.
-- How to record:
-  - `taskbook.md` stores task scope/acceptance/subtasks/evidence links.
-  - `summaries/<TASK_ID>.md` stores final objective result, change overview, gate evidence, risks, follow-ups.
-
-### 7) docs/testing/
-- Files:
-  - `docs/testing/regression-matrix.md`
-- Purpose:
-  - Full regression matrix against the local Compose environment; must be 0 FAIL.
-- How to record:
-  - Add/maintain rows by regression ID (R-xxx), area, steps/command, expected, status, evidence.
-  - If any FAIL exists, gate fails.
+  - `docs/interfaces/api.md`
+  - `docs/interfaces/api-change-log.md`
+- Rule:
+  - Any API change updates both files in the same task.
+
+### 6) docs/testing/regression-matrix.md
+- Purpose: on-demand regression evidence, not default gate for every small change.
+- Rule:
+  - Only real executed items can be marked `PASS`.
+  - `check-matrix` is used only when full regression is explicitly required.
+
+### 7) docs/tasks/summaries/
+- Purpose: optional long-form summary.
+- Rule:
+  - Only for high-risk changes, milestones, or tasks that need full retrospective.
+
+### 8) docs/deployment/
+- Purpose: optional heavy deployment audit docs.
+- Rule:
+  - Only for manual deploys, high-risk releases, or explicit audit requirements.
+
+## High-risk Changes
+
+These categories require stronger verification and usually a DD:
+- Database migration
+- Authentication / authorization
+- Payment / order
+- Deployment / Jenkins
+- Nginx / gateway
+- File upload / download
+- Production configuration
+
+For these tasks, target environment verification is mandatory.
 
 ## Commands
 
+Recommended default flow:
+
 ```bash
 pip install pyyaml requests
-python3 scripts/autopipeline/ap.py run build
-python3 scripts/autopipeline/ap.py run test
-python3 scripts/autopipeline/ap.py run lint
-python3 scripts/autopipeline/ap.py run docker_build
-python3 scripts/autopipeline/ap.py runtime-up
-python3 scripts/autopipeline/ap.py wait-health
-python3 scripts/autopipeline/ap.py run smoke
-python3 scripts/autopipeline/ap.py run regression
-python3 scripts/autopipeline/ap.py runtime-down
-python3 scripts/autopipeline/ap.py verify-jenkins
-python3 scripts/autopipeline/ap.py wait-health --scope prod
-python3 scripts/autopipeline/ap.py verify-api-docs
-python3 scripts/autopipeline/ap.py check-matrix
-python3 scripts/autopipeline/ap.py gen-summary T0001-1
-python3 scripts/autopipeline/ap.py commit-push T0001-1 --msg "T0001-1: <summary>" --require-runtime-health --require-jenkins --require-matrix
+python3 docs/tools/autopipeline/ap.py doctor
+python3 docs/tools/autopipeline/ap.py light-gate
+python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>" --require-light-gate --require-jenkins
+python3 docs/tools/autopipeline/ap.py verify-jenkins-build --git-ref HEAD
+python3 docs/tools/autopipeline/ap.py wait-health --scope target
+python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
+python3 docs/tools/autopipeline/ap.py record-closure <TASK_ID> --commit HEAD --jenkins <build-url> --result PASS --verification "health check" --verification "key api" --verification "key page"
 ```
 
+Or let `commit-push` append the closure record directly:
+
+```bash
+python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> \
+  --msg "<TASK_ID>: <summary>" \
+  --require-light-gate \
+  --require-jenkins \
+  --record-closure \
+  --jenkins-build <build-url> \
+  --result PASS \
+  --verification "health check" \
+  --verification "key api" \
+  --verification "key page"
+```
+
+Available on-demand commands:
+
+```bash
+python3 docs/tools/autopipeline/ap.py run build
+python3 docs/tools/autopipeline/ap.py run test
+python3 docs/tools/autopipeline/ap.py run quick_test
+python3 docs/tools/autopipeline/ap.py run lint
+python3 docs/tools/autopipeline/ap.py run typecheck
+python3 docs/tools/autopipeline/ap.py run script_syntax
+python3 docs/tools/autopipeline/ap.py doctor
+python3 docs/tools/autopipeline/ap.py verify-api-docs
+python3 docs/tools/autopipeline/ap.py verify-jenkins
+python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
+python3 docs/tools/autopipeline/ap.py verify-jenkins-build --job-name <job-name> --build-number <number>
+python3 docs/tools/autopipeline/ap.py verify-jenkins-build --job-url <job-url> --build-number <number>
+python3 docs/tools/autopipeline/ap.py verify-jenkins-build --multibranch-root-job <root-job> --branch-name <branch> --build-number <number>
+python3 docs/tools/autopipeline/ap.py runtime-up
+python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
+python3 docs/tools/autopipeline/ap.py run smoke
+python3 docs/tools/autopipeline/ap.py run regression
+python3 docs/tools/autopipeline/ap.py runtime-down
+python3 docs/tools/autopipeline/ap.py check-matrix
+python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
+```
+
+## Jenkins Build Tracking
+
+- `verify-jenkins-build --git-ref HEAD`
+  - Use when Jenkins build descriptions include commit SHA and you want to find the latest build automatically.
+- `verify-jenkins-build --job-name <folder/job> --build-number <N>`
+  - Use when you already know the Jenkins job and build number.
+- `verify-jenkins-build --job-url <full-job-url> --build-number <N>`
+  - Use when you want to bypass configured job resolution.
+- `verify-jenkins-build --multibranch-root-job <folder/repo> --branch-name <branch> --build-number <N>`
+  - Use for multibranch or organization-folder jobs where the branch is a child job.
+- `verify-jenkins-build --multibranch-root-job <folder/repo> --git-ref HEAD`
+  - Use when the current Git branch should be inferred automatically.
+- If Jenkins returns `403`, the script retries with crumb / CSRF handling automatically.
+
+## New Safeguards
+
+- `doctor`
+  - Checks whether the default lightweight workflow is actually configured instead of silently skipping gates.
+- `light-gate`
+  - Now fails if required commands are missing instead of returning `OK` after skipping everything.
+- `verify-target`
+  - Performs real target-environment verification beyond health checks when you provide key backend/frontend paths.
+- `commit-push --record-closure`
+  - Lets you append the closure record as part of the same close loop.
+
 ## Publish (NPM)
 
 1. Sync assets and basic check:
@@ -172,54 +331,35 @@ npm run sync-assets
 npm test
 ```
 
-2. Bump version (required before every publish):
+2. Bump version:
 
 ```bash
 npm version patch
-# or: npm version minor
-# or: npm version major
+# or: npm version minor / major
 ```
 
-`npm version` will update `package.json` and create a git tag.
-
-3. Login and run release check:
+3. Release check:
 
 ```bash
-npm login
 npm whoami
 npm run release:check
 ```
 
-4. Publish package:
+4. Publish:
 
 ```bash
 npm publish --access public
-# if your account requires 2FA OTP:
+# or
 npm publish --access public --otp <6-digit-otp>
 ```
 
-5. Verify and update clients:
+5. Verify and update:
 
 ```bash
 npm view @elvis1513/auto-coding-skill version
 npm install -g @elvis1513/auto-coding-skill@latest
 ```
 
-### Common Publish Errors
-
-- `403 You cannot publish over the previously published versions`
-  - Cause: same version already exists.
-  - Fix: run `npm version patch` (or `minor`/`major`) then publish again.
-- `403 Two-factor authentication ... is required to publish`
-  - Cause: publish requires 2FA.
-  - Fix: use `npm publish --access public --otp <6-digit-otp>`.
-- `404 Not Found` when install
-  - Cause: package not published successfully, or scope/name mismatch.
-  - Fix: verify with `npm view @elvis1513/auto-coding-skill version` first.
-- `Access token expired or revoked`
-  - Cause: npm auth token expired.
-  - Fix: run `npm login` again and retry publish/install.
-
 ## License
 
 MIT

package/cli/assets/skill/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: auto-coding-skill
-description: Use for strict Go fullstack monorepo engineering workflow in Claude/Codex. Initialize docs, fill docs/ENGINEERING.md frontmatter once, then execute design->implement->local-docker-gates->jenkins-trigger->verify.
+description: Use for a lightweight Jenkins-first engineering workflow in Claude/Codex. Initialize docs, fill docs/ENGINEERING.md once, then execute task->minimal-design->light-gate->push->jenkins->target-env->closure.
 ---
 
 # Auto Coding Skill (Claude + Codex)
 
-This branch specializes the skill for Go backend + frontend monorepo projects that build Docker images locally and use Jenkins pipelines to auto-deploy after push. It supports both Claude and Codex. During design, research, implementation, verification, and delivery, prefer already available MCP servers, installed skills, plugins, and app connectors over ad-hoc manual work whenever they can complete the task reliably.
+This skill is for Go backend + frontend monorepo projects that rely on Jenkins to build and deploy after push. It supports both Claude and Codex. The default workflow is lightweight locally, then uses Jenkins and the real target environment as the authoritative verification path.
+
+Prefer already available MCP servers, installed skills, plugins, and app connectors over ad-hoc manual work whenever they can complete the task reliably.
 
 Default to multi-agent execution when the client supports it. Break work into independent design, research, implementation, validation, and documentation subtasks so Claude/Codex can run them in parallel whenever that reduces cycle time without weakening control of the main task.
 
@@ -23,21 +25,15 @@ Use available platform capabilities first:
 3) Prefer supported plugins/apps/connectors when they provide authoritative project context or can write back records.
 4) Fall back to manual shell/code workflows only when the above are unavailable, insufficient, or slower than direct execution.
 
-Typical examples:
-- Design/UI work: prefer Figma MCP and related design skills.
-- Documentation/library lookup: prefer official docs and MCP-backed doc tools.
-- Project management or knowledge base updates: prefer Linear/Notion connectors if available.
-- Browser/runtime verification: prefer Playwright/browser tools if available.
-- Pipeline and deployment verification: prefer Jenkins-capable connectors, browser automation, or project-integrated tools if available.
-
 ## Collaboration policy
 
 Prefer multi-agent mode across the workflow:
 
 1) Split independent subtasks early when they can run in parallel.
-2) Keep the main agent on the critical path: task framing, design decisions, integration, and final quality gates.
-3) Use side agents for bounded work such as research, code slices, documentation updates, regression checks, or review passes.
+2) Keep the main agent on the critical path: task framing, design decisions, integration, Jenkins / target-env verification, and final closure.
+3) Use side agents for bounded work such as research, code slices, documentation updates, targeted regression checks, or review passes.
 4) Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
+5) A practical default split for Go fullstack work is: design/research, backend implementation, frontend implementation, validation/documentation.
 
 ## Entry
 
@@ -69,41 +65,80 @@ Fill only:
 
 This contains all manual fields:
 - `commands.*`
-- `runtime.*`
+- `runtime.*` (only for optional local diagnostics)
+- `target_env.*`
 - `jenkins.*`
 - `docs.*`
 
 Do not duplicate config in other md/yaml files.
 
+Minimum required config for the default flow:
+- `project.name`
+- `commands.build`
+- `commands.quick_test` or `commands.test`
+- `commands.lint` or `commands.typecheck`
+- `target_env.name`
+- `target_env.health_base_url`
+- `target_env.health_path`
+- `jenkins.trigger_branch`
+- `jenkins.image_repository`
+- `jenkins.image_tag_strategy`
+- `jenkins.deploy_env`
+- `jenkins.job_url` or `jenkins.base_url + jenkins.job_name` or `jenkins.base_url + jenkins.multibranch_root_job`
+
+## Branch policy
+
+- `dev` is the long-lived integration branch.
+- Use a temporary task branch only when parallel work would otherwise collide on `dev`.
+- Keep temporary branches task-scoped and merge/rebase back into `dev` after closure.
+
 ## Execution order
 
-1) `docs/ENGINEERING.md`
-2) `docs/tasks/taskbook.md`
-3) `docs/design/**`
-4) implementation
-5) local build/test/lint gates
-6) start and validate local Docker Compose runtime
-7) update API docs + regression matrix + bug list + summary
-8) verify Jenkins config / Jenkinsfile readiness
-9) commit/push to trigger Jenkins
-10) verify Jenkins pipeline + target environment health
+1) read `docs/ENGINEERING.md`
+2) read / update `docs/tasks/taskbook.md`
+3) write minimal design notes; create a DD only when the change is cross-module, API, DB, deployment, Jenkins, or key-page-flow related
+4) implement only the necessary changes
+5) run the default local lightweight gate
+6) commit + push
+7) verify Jenkins build / deployment result
+8) verify the real target environment
+9) append `docs/tasks/closure-log.md`
+10) use summary / deployment record / regression matrix only when the task actually requires them
 
 ## Commands
 
+Default commands:
+
 ```bash
-python3 scripts/autopipeline/ap.py run build
-python3 scripts/autopipeline/ap.py run test
-python3 scripts/autopipeline/ap.py run lint
-python3 scripts/autopipeline/ap.py run docker_build
-python3 scripts/autopipeline/ap.py runtime-up
-python3 scripts/autopipeline/ap.py wait-health
-python3 scripts/autopipeline/ap.py run smoke
-python3 scripts/autopipeline/ap.py run regression
-python3 scripts/autopipeline/ap.py runtime-down
-python3 scripts/autopipeline/ap.py verify-jenkins
-python3 scripts/autopipeline/ap.py wait-health --scope prod
-python3 scripts/autopipeline/ap.py verify-api-docs
-python3 scripts/autopipeline/ap.py check-matrix
-python3 scripts/autopipeline/ap.py gen-summary T0001-1
-python3 scripts/autopipeline/ap.py commit-push T0001-1 --msg "T0001-1: <summary>" --require-runtime-health --require-jenkins --require-matrix
+python3 docs/tools/autopipeline/ap.py doctor
+python3 docs/tools/autopipeline/ap.py light-gate
+python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>" --require-light-gate --require-jenkins
+python3 docs/tools/autopipeline/ap.py verify-jenkins-build --git-ref HEAD
+python3 docs/tools/autopipeline/ap.py wait-health --scope target
+python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
+python3 docs/tools/autopipeline/ap.py record-closure <TASK_ID> --commit HEAD --jenkins <build-url> --result PASS --verification "health check" --verification "key api"
 ```
+
+On-demand commands:
+
+```bash
+python3 docs/tools/autopipeline/ap.py runtime-up
+python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
+python3 docs/tools/autopipeline/ap.py run smoke
+python3 docs/tools/autopipeline/ap.py run regression
+python3 docs/tools/autopipeline/ap.py runtime-down
+python3 docs/tools/autopipeline/ap.py check-matrix
+python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
+```
+
+## Quality policy
+
+- Default local gate is lightweight only: build, unit/quick test, lint, typecheck, API docs, Jenkinsfile / script syntax, `git diff --check`.
+- `doctor` should be used early to catch missing config before the first implementation loop.
+- `light-gate` now fails if the required default commands are not configured.
+- Do not require local Docker Compose or full local regression for every small change.
+- Jenkins and target environment verification are more valuable than repeated local simulation of deploy-only problems.
+- `verify-target` should be used for real target-environment API/page checks when the task touches user-visible or deploy-sensitive behavior.
+- `commit-push --record-closure` can close the loop in one command when Jenkins build URL and verification results are already known.
+- `regression-matrix.md` can mark `PASS` only after real execution with evidence.
+- High-risk changes must include target environment verification and usually a DD.