@elvis1513/auto-coding-skill 0.3.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 prefers already available MCP servers, installed skills, plugins, and app connectors for design, research, documentation, verification, and external system updates.
-It also prefers 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,42 +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.
-
-8. Branch rule during execution:
-
-- `dev` is the long-lived integration branch.
-- If there is no parallel work conflict, prefer `dev`-first.
-- If the repo is in detached HEAD, worktree mode, or another task is already mutating `dev`, create a temporary task branch first.
-- Temporary branches should stay task-scoped and rebase back to latest `dev` before final integration.
-
 ## AGENTS.md Constraint Example
 
 ```md
@@ -86,115 +157,170 @@ 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 docs/tools/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.
+- Purpose: single source of project config + workflow 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.
+  - Fill YAML frontmatter once.
+  - Keep target env accounts, Jenkins UI/API accounts, commands, docs paths here only.
+  - Do not duplicate config elsewhere.
 
-### 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.
+### 2) docs/tasks/taskbook.md
+- Purpose: master task ledger.
 - How to record:
-  - Record both local Compose validation and Jenkins deployment evidence: compose file, service, container, image tag, Jenkins build, deploy env, health checks.
+  - Every task writes scope, risk, impact area, minimal design note, acceptance, evidence links.
 
-### 3) docs/design/
-- Files:
-  - `docs/design/<TASK_ID>-<slug>.md` (from DD template).
-- Purpose:
-  - Detailed design before coding (scope,方案、时序图、ER图、接口编排、测试策略、回滚).
+### 3) docs/tasks/closure-log.md
+- Purpose: default lightweight closure record.
 - How to record:
-  - One task/subtask one DD file.
-  - Status changes: Draft -> Reviewed -> Approved.
+  - 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.
 
-### 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.
+### 4) docs/design/
+- Purpose: DD for cross-module / API / DB / deployment / Jenkins / key-page-flow changes.
 - 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 (新增/修改/废弃/兼容策略/影响面).
+  - Small changes do not need a standalone DD file.
+  - Higher-risk changes create `docs/design/<TASK_ID>-<slug>.md`.
 
-### 5) docs/reviews/
+### 5) docs/interfaces/
 - 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.
-- How to record:
-  - Record commands used (lint/typecheck from docs/ENGINEERING.md frontmatter) and conclusion (Pass/Blocked).
-
-### 6) docs/tasks/
-- 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.
+  - `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.
 
-### 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 rows by regression ID (R-xxx), area, steps/command, expected, status, evidence.
-  - New or unexecuted rows must stay `TODO`.
-  - `PASS` is valid only after real execution with non-placeholder evidence.
-  - If any row is not `PASS`, or evidence is placeholder text, gate fails.
+## Commands
 
-## Branch Policy
+Recommended default flow:
 
-- `dev` is the only long-lived integration branch.
-- Temporary branches are preferred when parallel worktrees or concurrent tasks would otherwise collide on `dev`.
-- Temporary branches should be small, task-scoped, and rebased frequently against latest `dev`.
-- Final integration target remains `dev`; temporary branches are not release branches.
+```bash
+pip install pyyaml requests
+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"
+```
 
-## CI Trigger Strategy
+Or let `commit-push` append the closure record directly:
 
-- Prefer split Jenkins behavior:
-- Branch or MR validation job for build/test/lint/typecheck and optional non-deploy runtime checks.
-- `dev` integration/deploy job for actual deployment-triggering pushes.
-- Avoid duplicate deploy triggers from both merge acceptance events and `dev` push events.
+```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"
+```
 
-## Commands
+Available on-demand commands:
 
 ```bash
-pip install pyyaml requests
 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 docker_build
+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
+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 verify-jenkins
-python3 docs/tools/autopipeline/ap.py verify-jenkins-build --git-ref HEAD
-python3 docs/tools/autopipeline/ap.py wait-health --scope prod
-python3 docs/tools/autopipeline/ap.py verify-api-docs
 python3 docs/tools/autopipeline/ap.py check-matrix
-python3 docs/tools/autopipeline/ap.py gen-summary T0001-1
-python3 docs/tools/autopipeline/ap.py commit-push T0001-1 --msg "T0001-1: <summary>" --require-runtime-health --require-jenkins --require-matrix
+python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
 ```
 
-## Quality Gate Expectations
-
-- Backend quality gate: `commands.test` must pass.
-- Frontend quality gate: at minimum `commands.build`, `commands.lint`, and `commands.typecheck` must pass.
-- Regression matrix rows must start as `TODO` until actually executed.
-- `PASS` requires real evidence, not placeholders.
-- Before final commit/push, clean temporary logs, screenshots, generated artifacts, and cache by-products. `.local/` may remain when it is the intended local runtime data directory.
+## 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)
 
@@ -205,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,72 +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.
 
-## Branch policy
-
-- `dev` remains the only long-lived integration branch.
-- Default behavior stays `dev`-first when there is no parallel work conflict.
-- If Claude or Codex is operating in a derived worktree, detached HEAD, or any parallel task context where another thread is already changing `dev`, prefer creating a temporary branch from the latest `dev` before editing.
-- Name temporary branches after the task, preferably `codex/<task-id>-<slug>` such as `codex/t0005-domestic-payment-site`.
-- Keep the temporary branch scoped to one task, complete design/implementation/verification there, then merge or rebase it back onto `dev` only after local gates pass.
-- Do not treat temporary branches as release branches; the final integration target is still `dev`.
-- In temporary-branch mode, work in small, closed-loop slices. Each slice should have a clear scope, synchronized docs, the relevant local validation, and a commit that can stand on its own.
-- Rebase temporary branches frequently against the latest `dev` to keep merge surfaces small.
+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`
 
-## CI trigger strategy
+## Branch policy
 
-- Prefer a split Jenkins model when parallel worktrees are active:
-- MR or branch validation job: build/test/lint/typecheck and optional non-deploy runtime checks on temporary branches or merge requests.
-- `dev` integration/deploy job: trigger only from pushes that land on `dev`.
-- Do not rely on merge-request acceptance events to drive production deployment when a `dev` push event already exists; that commonly creates duplicate builds around merge time.
+- `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) choose branch mode (`dev` directly, or temporary branch if parallel worktree rules apply)
-2) `docs/ENGINEERING.md`
-3) `docs/tasks/taskbook.md`
-4) `docs/design/**`
-5) implementation
-6) local build/test/lint gates
-7) start and validate local Docker Compose runtime
-8) update API docs + regression matrix + bug list + summary
-9) verify Jenkins config / Jenkinsfile readiness
-10) if temporary-branch mode is used, close one small slice at a time with reviewable commits and rebase regularly onto `dev`
-11) merge/rebase temporary branch back to latest `dev` when temporary-branch mode was used
-12) commit/push to trigger Jenkins
-13) verify Jenkins pipeline + target environment health, preferably with `verify-jenkins-build --git-ref HEAD` (strict deploy check by default; use `--allow-no-deploy` only for docs-only sync verification)
+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 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 run build
-python3 docs/tools/autopipeline/ap.py run test
-python3 docs/tools/autopipeline/ap.py run lint
-python3 docs/tools/autopipeline/ap.py run typecheck
-python3 docs/tools/autopipeline/ap.py run docker_build
 python3 docs/tools/autopipeline/ap.py runtime-up
-python3 docs/tools/autopipeline/ap.py wait-health
+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 verify-jenkins
-python3 docs/tools/autopipeline/ap.py verify-jenkins-build --git-ref HEAD
-python3 docs/tools/autopipeline/ap.py wait-health --scope prod
-python3 docs/tools/autopipeline/ap.py verify-api-docs
 python3 docs/tools/autopipeline/ap.py check-matrix
-python3 docs/tools/autopipeline/ap.py gen-summary T0001-1
-python3 docs/tools/autopipeline/ap.py commit-push T0001-1 --msg "T0001-1: <summary>" --require-runtime-health --require-jenkins --require-matrix
+python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
 ```
 
-## Quality gate expectations
-
-- Gate-4: backend must pass `commands.test`; frontend must at least pass `commands.build`, `commands.lint`, and `commands.typecheck`. Frontend automated tests are added incrementally when the repo gains them.
-- Gate-9: `docs/testing/regression-matrix.md` rows must start as `TODO` until they are actually executed.
-- A matrix row can be marked `PASS` only after real execution, and `Evidence` must contain non-placeholder logs, screenshots, or report paths.
-- `python3 docs/tools/autopipeline/ap.py check-matrix` should be treated as a hard gate; placeholder evidence is equivalent to incomplete regression.
-- Before the final commit/push, clean temporary files, logs, screenshots, generated verification artifacts, cache directories, and similar by-products created during the task. The only persistent local runtime data that may remain is `.local/`.
+## 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.