@chenguangyao/devflow-kit 0.1.43

package/docs/internal-gitlab-setup.md

@@ -0,0 +1,426 @@
+# 在内部 GitLab + Jenkins 环境落地 devflow-kit
+
+> 本文面向企业内网 —— 代码托管在自建 GitLab,CI 可能是 **GitLab Runner + Jenkins** 混合。
+> 公网版指引见 [README](../README.md),两者可共存:同一份源码、两套分发渠道。
+
+## 1. 分发方式(三选一,推荐 A)
+
+### A) GitLab Package Registry(npm 私有,推荐)
+
+最接近公网 `npm i -g devflow-kit` 的体验,团队成员无痛。
+
+**一次性:给 devflow-kit 自己的仓库配发布**
+
+```yaml
+# .gitlab-ci.yml 片段(只给 devflow-kit 仓库本身)
+publish:
+  stage: publish
+  image: node:20
+  only: [tags]
+  script:
+    - echo "@<your-group>:registry=https://<your-gitlab>/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > ~/.npmrc
+    - echo "//<your-gitlab>/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> ~/.npmrc
+    - npm test
+    - npm publish
+```
+
+`package.json` 里改 `name` 为带 scope 的(否则 npm publish 默认走公网):
+
+```json
+{
+  "name": "@<your-group>/devflow-kit",
+  ...
+  "publishConfig": {
+    "registry": "https://<your-gitlab>/api/v4/projects/<project-id>/packages/npm/"
+  }
+}
+```
+
+**团队成员使用**:
+
+```bash
+# 配一次
+echo "@<your-group>:registry=https://<your-gitlab>/api/v4/packages/npm/" >> ~/.npmrc
+# 若 GitLab 要求鉴权,加上 Personal Access Token(read_api):
+echo "//<your-gitlab>/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}" >> ~/.npmrc
+
+# 装
+npm i -g @<your-group>/devflow-kit
+df --version
+```
+
+> 双分发:公网 package 名 `devflow-kit`,内网 `@<your-group>/devflow-kit`,源码同一份,靠 CI 里写不同 `name` 或维护两个 `package.json.<env>` 切换。
+
+### B) git+ssh 直装(零基建,适合早期)
+
+```bash
+npm i -g git+ssh://git@<your-gitlab>:<group>/devflow-kit.git#v0.1.0
+df --version
+```
+
+优点:不用建 registry;缺点:每个 dev 机器要有 gitlab ssh key。
+
+升级就是 `npm i -g .......git#v0.2.0`,用 tag 锁版本。
+
+### C) tarball + 内网对象存储(最朴素)
+
+CI 在 release 时跑 `npm pack` 生成 `devflow-kit-0.1.0.tgz`,丢到内网 MinIO / OSS / GitLab Generic Packages:
+
+```bash
+npm i -g https://<internal-artifacts>/devflow-kit/0.1.0/devflow-kit-0.1.0.tgz
+```
+
+适合完全没有 npm registry 的环境。
+
+---
+
+## 2. Provider 配置(GitLab + Jenkins 混栈)
+
+公司现状假设:**GitLab 托代码 + JIRA/Wiki 在另一套(或 GitLab 自带 Wiki) + Jenkins 跑构建发布 + 可能有内部 KB(WeKnora / Confluence)**。
+
+推荐把内网适配全部集中到 `devflow/providers.json`(项目级,不含明文 token):
+
+```json
+{
+  "intake.wiki": {
+    "type": "intake",
+    "driver": "qs-bridge",
+    "config": {
+      "binPath": "/usr/local/bin/qs-bridge",
+      "tool": "wiki",
+      "timeoutMs": 30000
+    }
+  },
+  "issue.jira": {
+    "type": "issue",
+    "driver": "qs-bridge",
+    "config": { "tool": "jira", "project": "YOUR-PROJ" }
+  },
+  "ci.jenkins": {
+    "type": "ci",
+    "driver": "qs-bridge",
+    "config": {
+      "tool": "jenkins",
+      "jenkinsBase": "https://<your-jenkins-host>",
+      "defaultJob": "deploy/<your-service>"
+    }
+  },
+  "vcs.gitlab": {
+    "type": "vcs",
+    "driver": "gitlab",
+    "config": {
+      "baseUrl": "https://<your-gitlab>",
+      "projectId": "<group>/<project>",
+      "tokenEnv": "GITLAB_TOKEN"
+    }
+  },
+  "kb.weknora": {
+    "type": "kb",
+    "driver": "weknora",
+    "config": {
+      "endpoint": "https://<your-kb-host>",
+      "kb_id": "${env:KB_ID}",
+      "tag_id": "${env:KB_TAG_ID}",
+      "token": "${env:WEKNORA_API_KEY}",
+      "_comment": "Bare config above runs the built-in generic contract. For arb-shape endpoints, fill auth/paths/body/responsePath via `devflow provider add kb.weknora --from <your-local-weknora-arb.json>` — see §2.3."
+    }
+  },
+
+  "notify.smtp": {
+    "type": "notify",
+    "driver": "smtp",
+    "config": {
+      "host": "smtp.exmail.qq.com",
+      "port": 465,
+      "user": "${env:SMTP_USER}",
+      "pass": "${env:SMTP_PASS}",
+      "from": "DevBot <${env:SMTP_USER}>",
+      "defaults": {
+        "to":  "qa-team@<your-corp>.com",
+        "cc":  "pm@<your-corp>.com"
+      }
+    }
+  }
+}
+```
+
+**真正的凭证全部落到** `~/.devflow/providers.json`(chmod 600,`devflow init` 自动设)或直接读环境变量。仓库里绝不落明文 token —— `devflow doctor --scope=cred` 会检查并拒绝通过。
+
+### 2.1 qs-bridge 首装
+
+```bash
+# qs-bridge 本身是另一份内网工具,先按内部指引装
+npm i -g @<your-group>/qs-bridge   # 或 git+ssh
+
+# 首次走浏览器登录(会弹窗,所有 wiki/jira/jenkins 共用同一套 cookie)
+qs-bridge auth login
+qs-bridge auth status    # 验证
+```
+
+然后在项目里:
+
+```bash
+devflow provider add intake.wiki --type=intake --driver=qs-bridge \
+  --config-binPath=/usr/local/bin/qs-bridge --config-tool=wiki
+devflow provider status intake.wiki     # 应显示 ok
+devflow ingest https://<your-wiki-host>/pages/12345   # 立马能跑
+```
+
+### 2.2 GitLab 作为 VCS provider
+
+`devflow deliver --mode=pr` 需要 VCS provider;GitLab 走 REST API:
+
+```bash
+# 生成一个 personal access token,scopes: api, write_repository
+export GITLAB_TOKEN=glpat-xxxxx
+
+devflow provider add vcs.gitlab --type=vcs --driver=gitlab \
+  --config-baseUrl=https://<your-gitlab> \
+  --config-projectId=<group>/<project> \
+  --config-tokenEnv=GITLAB_TOKEN
+
+devflow deliver --mode=pr --base=main --head=feat/coupon-grant
+# → 内部调 GitLab API,创建 MR
+```
+
+### 2.3 WeKnora 知识库(引导配置 + 本地参考片段)
+
+`kb-weknora` driver 只内置**一套通用最小契约**(Bearer + `/api/v1/kb/{kb_id}/*` 形状),所有字段都可以通过 `providers.json` 覆盖。我们不把内网特定的 endpoint / auth 形状打进包里——**内网具体配置以"本地参考片段"形式在 `.internal/` 维护,不进仓、不进包、不推 npm**。
+
+首次接入步骤:
+
+**方式 1:引导式(推荐,新手零成本)**
+
+```bash
+devflow provider add kb.weknora
+# 交互输入:
+#   type     = kb
+#   driver   = weknora
+#   endpoint = https://<your-kb-host>
+#   kb_id    = <uuid>
+#   token    = env:WEKNORA_API_KEY        ← 会自动转成 ${env:WEKNORA_API_KEY}
+#   tag_id   = (可选)
+#   idempotent = false|true  ← 若目标后端按 title 去重,填 true
+```
+
+走完只得到一份"默认契约"配置,适配标准 Bearer `/api/v1/kb/{kb_id}/*` 形态的 WeKnora。
+
+**方式 2:从本地参考片段导入(对接 arb-knowledge 用)**
+
+在你本机准备一份 `<anywhere>/weknora-arb.local.json`(**不要提交到任何仓库**),把你们内网 arb-knowledge 的 endpoint / auth header / paths / body / responsePath 写齐,然后:
+
+```bash
+devflow provider add kb.weknora --from=./weknora-arb.local.json
+```
+
+`--from` 支持的结构有两种:
+- 顶层就是一个 `config{}` 片段 → 直接当 `kb.weknora.config` 用
+- 顶层含 `kb.weknora: { type, driver, config }` → 整段原样搬入
+
+参考模板(**由了解内网的同事线下告知具体 endpoint 后填充**,不要提交):
+
+```jsonc
+// ~/devflow-templates/weknora-arb.local.json(本地)
+{
+  "kb.weknora": {
+    "type": "kb",
+    "driver": "weknora",
+    "config": {
+      "endpoint": "https://<your-internal-kb-host>",
+      "kb_id": "<your-kb-uuid>",
+      "token": "${env:WEKNORA_API_KEY}",
+      "tag_id": "",
+      "idempotent": true,
+      "auth": { "header": "X-API-Key", "scheme": "" },
+      "paths": {
+        "findByTitle": "/api/v1/knowledge-bases/{kb_id}/knowledge?keyword={title}&page=1&page_size=20",
+        "create":      { "method": "POST",   "path": "/api/v1/knowledge-bases/{kb_id}/knowledge/manual" },
+        "update":      { "method": "PUT",    "path": "/api/v1/knowledge/manual/{id}" },
+        "delete":      { "method": "DELETE", "path": "/api/v1/knowledge-bases/{kb_id}/knowledge/{id}" },
+        "search":      { "method": "POST",   "path": "/api/v1/knowledge-search" }
+      },
+      "body": {
+        "create": { "title": "{title}", "content": "{content}", "status": "publish", "tag_id": "{tag_id?}" },
+        "update": { "title": "{title}", "content": "{content}", "status": "publish" },
+        "search": { "query": "{query}", "knowledge_base_id": "{kb_id}", "tag_id": "{tag_id?}", "knowledge_ids": "{ids?}" }
+      },
+      "responsePath": {
+        "createId":    "data.id",
+        "searchItems": "data",
+        "listItems":   "data",
+        "itemId":      "id",
+        "itemTitle":   "title",
+        "itemUrl":     "url",
+        "itemScore":   "score",
+        "itemSnippet": "content"
+      }
+    }
+  }
+}
+```
+
+> **安全**:上面的文件只是脚手架,不含任何 token;但因为可能带有内网域名/KB ID,**请一定放到 gitignore 区**(devflow-kit 的仓库根已内置 `.internal/`、`*.local.json`、`*.local.md` 作为 gitignore 白名单,可以放心用这些命名)。
+
+dry-run 方式验证(不实际调用):
+
+```bash
+DEVFLOW_KB_DRY_RUN=1 devflow knowledge sync --driver=weknora
+```
+
+### 2.4 提测邮件(notify-smtp)
+
+原 arb `deploy-submit/send-email.py` 的 Node 零依赖移植,完全对齐:
+
+- SMTPS(465)/ STARTTLS(587)/ plain(25)三种连接模式
+- `AUTH PLAIN` / `AUTH LOGIN` 自动协商(Exchange / 企业邮默认 LOGIN)
+- Markdown → HTML(表格 / 列表 / 标题 / 粗体 / 行内代码)
+- 多附件 + RFC 2047 中文 Subject 编码
+
+`devflow deliver --notify` 会在 MR 建完之后自动发邮件;`--notify-dry-run` 只组装 MIME 不连接 SMTP。
+
+```bash
+export SMTP_USER=devbot@<your-corp>.com
+export SMTP_PASS=***                    # 企业邮 SMTP 授权码
+
+devflow deliver --mode=pr --notify \
+  --notify-to="qa1@corp.com,qa2@corp.com" \
+  --notify-cc="pm@corp.com"
+```
+
+发送成功会在 `state.json.auditLog` 留一条 `deliver.notify` 事件。
+
+### 2.5 Jenkins 触发(via qs-bridge)
+
+```bash
+devflow test smoke --env=staging
+# 背后等价:qs-bridge jenkins trigger '{"job":"deploy/your-service","params":{"env":"staging"}}'
+```
+
+---
+
+## 3. 在 **用户项目** 里接 GitLab CI(不是给 devflow-kit 自己)
+
+`devflow init --with-ci=gitlab` 生成一份 `.gitlab-ci.devflow.yml` 模板。它负责:
+
+1. **PR validation**:MR 开起来就跑 `devflow doctor --scope=config,change,knowledge` + `devflow status` 评论回 MR
+2. **Knowledge sync**:主干合入后,若 `devflow/knowledge/**` 有变更,跑 `devflow knowledge sync --since=before --to=sha --driver=weknora` 同步到知识库
+3. **Archive hook**(可选):打 tag 时触发 `devflow archive` 合并 delta 到 specs(一般本地做完再推,少用)
+
+模板位置:[`src/templates/files/ci/gitlab.yml`](../src/templates/files/ci/gitlab.yml)。
+
+### 3.1 公司惯例适配
+
+不同 BU 的 Runner 标签、基础镜像、before_script 往往不同。建议 `devflow init --with-ci=gitlab` 生成后,保留 3 个可改点:
+
+```yaml
+.devflow-base: &devflow-base
+  image: <your-internal-registry>/node:20-devflow        # ← BU 内部镜像
+  tags: [<your-runner-tag>]                              # ← BU runner tag
+  before_script:
+    - npm i -g @<your-group>/devflow-kit                 # ← 私有 registry
+    - df --version
+
+devflow:validate:
+  <<: *devflow-base
+  stage: test
+  script:
+    - devflow doctor --scope=config,change,knowledge --json > doctor.json
+  artifacts:
+    reports: { junit: doctor.json }
+
+devflow:knowledge-sync:
+  <<: *devflow-base
+  stage: deploy
+  only:
+    refs: [main]
+    changes: [devflow/knowledge/**/*.md]
+  script:
+    - devflow knowledge sync --since="${CI_COMMIT_BEFORE_SHA}" --to="${CI_COMMIT_SHA}" --driver=weknora
+  variables:
+    WEKNORA_API_KEY: $WEKNORA_API_KEY    # ← GitLab CI/CD Variable(masked)
+```
+
+### 3.2 与 Jenkins 共存
+
+GitLab CI 负责 **静态校验 + 知识库同步**,Jenkins 负责 **真实构建 / 测试 / 发布**。
+`devflow test smoke` 可从任一侧触发,但一般放在 `devflow deliver` 之后(Deploy → Smoke)。
+
+一条完整双 CI 走向:
+
+```
+开发本地:
+  devflow apply --task=N  →  devflow review --round × ≤3  →  devflow verify finalize  →  devflow deliver --mode=pr
+
+GitLab CI(MR 自动跑):
+  devflow:validate        ← devflow doctor
+  test:unit               ← npm test 等
+
+人工 merge →  GitLab CI 再跑一次:
+  devflow:knowledge-sync  ← 只当 knowledge/ 有变
+
+人工在 Jenkins 点 deploy:
+  deploy-job              ← 常规发布流水
+
+发布后:
+  devflow test smoke --env=prod   ← 通过 qs-bridge 调 Jenkins smoke-job
+  devflow archive                 ← 本地跑,提最后一个 MR 合入
+```
+
+---
+
+## 4. 从 arb-workflow-kit 迁移(补充内网视角)
+
+详见 [migration-from-arb.md](./migration-from-arb.md)。内网迁移多一条 **WeKnora / arb-knowledge UUID 继承**:
+
+```bash
+# 在旧 arb 仓库根目录
+devflow knowledge migrate --from=arb-7 --to=improved-9
+# → 只动目录名,.meta.json 里 external.weknora.uuid 保留
+# → 后续 devflow knowledge sync --driver=weknora 走 update(不重复创建 tag)
+```
+
+团队老 `arb-knowledge` 仓库可以**原地**升级到 devflow 结构,然后各业务仓库把本地 `devflow/knowledge/` 的同步目标指向它,实现"一个团队知识库 + 多项目汇聚"。
+
+---
+
+## 5. 团队推行 checklist
+
+**第 1 周:基建**
+- [ ] 决定分发渠道(上面 A/B/C),建一个 `@<your-group>/devflow-kit` 包
+- [ ] `qs-bridge` 装在开发机(若还没)
+- [ ] `~/.devflow/providers.json` 模板下发(不含 token,靠 env 注入)
+- [ ] GitLab CI/CD Variables 里配 `WEKNORA_API_KEY` / `GITLAB_TOKEN`(masked)
+
+**第 2 周:1-2 个先锋项目**
+- [ ] 选 1 个 L2 需求做完整走查:`devflow ingest → df plan → devflow apply --task=N 并行 → devflow review --round × 2 → devflow verify → devflow deliver --mode=pr`
+- [ ] 填 `devflow doctor` 出现的所有 warning(项目概览 mode / provider 状态 / git 健康)
+- [ ] 整理踩坑点反馈到 devflow-kit issue
+
+**第 3-4 周:面向团队**
+- [ ] 分享会:演示 worktree-swarm 并行 + 3 轮审查 + 知识库自动沉淀
+- [ ] 旧 `~/.config/dev-workflow/` 的迁移(如果有在用 arb)
+- [ ] 统一 `.gitlab-ci.devflow.yml` 模板推到各项目,由各项目酌情合入
+
+**日常维护**
+- [ ] `devflow doctor` 进 pre-commit(用 `--scope=change,git` 轻量版)
+- [ ] 每月 `devflow provider audit` 做凭证体检(file permissions / plaintext token 扫描)
+- [ ] 季度 `devflow provider rotate <name>` 轮换 token
+
+---
+
+## 6. FAQ
+
+**Q: 我们公司内网 Jenkins 有两套(国内/海外),怎么办?**
+A: 在 `providers.json` 里配两个 ci provider:`ci.jenkins-cn` 与 `ci.jenkins-global`,用不同 `jenkinsBase`。`devflow test smoke --provider=ci.jenkins-global` 显式指定。
+
+**Q: GitLab 要求 MR 必须过 approve,我的 `devflow deliver --mode=pr` 怎么判断?**
+A: `devflow deliver` 只创建 MR 不要求合并;approve / merge 保留给 GitLab 原生 UI。合入后本地再跑 `devflow archive`,把 `delta/` 合并进 `devflow/specs/` 再提一个小 MR。
+
+**Q: 我们的 wiki 不在 qs-bridge 覆盖范围(比如 GitLab Wiki / 飞书 / 语雀)。**
+A: `intake` provider 可替换成 `github-wiki` / `feishu-doc` / `yuque`(接口位已留,驱动实现可本地按抽象补);或者最简单:**`devflow ingest --file=./my-prd.md`** 直接喂本地 markdown,不要 provider。
+
+**Q: 凭证文件 chmod 600 在 Windows 开发机怎么处理?**
+A: Windows 下 `devflow` 会跳过 chmod 检查,但会 warn。建议 Windows 开发机走 WSL2,或把 `providers.json` 彻底走 `${env:VAR}` 引用,不落明文。
+
+**Q: devflow-kit 自己的仓库要不要接 GitLab CI?**
+A: 要,最少两段(`test` + `publish-on-tag`);示例见本文 §1.A。

package/docs/marketplace-skills.md

@@ -0,0 +1,231 @@
+# 可选扩展 Skills 说明
+
+devflow-kit 的核心流程由阶段 skill 负责:requirement、tech-spec、plan、apply、code-review、verify、deliver、archive 等。本文说明新增的 5 个可选扩展 skill。它们不是新的强制阶段,而是在特定风险出现时增强现有 phase。
+
+## 总览
+
+| Skill | 解决什么问题 | 主要接入 phase | 是否默认必用 |
+| --- | --- | --- | --- |
+| `devflow-frontend-quality` | 前端 UI、交互、可访问性、性能和截图证据 | code-review / verify | 前端改动时必用 |
+| `devflow-ci-fix` | CI 失败和 PR/MR comment 修复闭环 | review / apply / verify / deliver | CI 或评论失败时必用 |
+| `devflow-dependency-upgrade` | 依赖升级、漏洞修复、lockfile 变更 | apply / verify | 依赖任务时必用 |
+| `devflow-handoff-resume` | 长任务交接、上下文恢复、多 agent 接力 | 任意 phase | 长任务或恢复时必用 |
+| `devflow-security-hardening` | 安全、隐私、支付、鉴权、回调、敏感信息 | tech-spec / code-review / verify | L3 或安全相关必用 |
+
+这些 skill 吸收的是“能力模型”，不是把外部 SaaS 或某个 marketplace 包直接内置进核心流程:
+
+| 吸收来源类型 | 吸收的能力 | 落到 devflow 的位置 | 优点 |
+| --- | --- | --- | --- |
+| 前端质量类 guideline | UI checklist、可访问性、响应式、截图证据 | `frontend-quality`、`reports/test-report.md#joint/#e2e` | 前端改动不再只看编译通过，能留下可复查证据 |
+| CI / PR feedback workflow | 读日志、定位失败、修复、重跑、关闭反馈 | `ci-fix`、review/apply/verify 闭环 | CI 失败不会被当成“再试一次”，会先归因 |
+| dependency updater | 版本风险分级、lockfile、breaking change、回滚 | `dependency-upgrade` | 依赖升级从“改版本号”变成可审计任务 |
+| session handoff | 上下文摘要、下一步命令、风险和验证记录 | `handoff-resume`、`handoff.md` | 长任务或换 agent 时不容易从头来过 |
+| security checklist | OWASP / MITRE 风格的威胁面检查 | `security-hardening`、review/verify security section | 支付、鉴权、隐私类改动有固定安全视角 |
+
+CLI 兜底:
+
+```bash
+devflow status risk add frontend_change --reason="UI diff touched"
+devflow status risk add dependency_change --reason="lockfile changed"
+devflow status risk add security_sensitive --reason="auth/callback changed"
+devflow status risk add ci_failure --reason="required check failed"
+```
+
+这些信号写入 `state.json.riskSignals[]`。`verify finalize` 会按信号追加证据要求,`deliver` 会阻止 open risk signal 直接交付。skill 负责发现和解释风险,CLI 负责把风险变成可审计硬闸。
+
+## 1. frontend-quality
+
+目录:
+
+```text
+skills/frontend-quality/
+```
+
+触发:
+
+- React / Vue / Next / Vite / CSS / 页面组件改动。
+- 表单、弹窗、列表、分页、筛选、上传、支付、签约、登录页面改动。
+- 前端消费者、轮询页、redirect/query/returnUrl/callback 变化。
+
+要实现的功能:
+
+- code-review 增加 UI 一致性、响应式、可访问性、性能 checklist。
+- verify 要求浏览器证据:Playwright/Cypress 或人工操作步骤 + 截图。
+- 把证据写到 `reports/test-report.md#joint` 或 `#e2e`。
+- 没有浏览器验证时,必须在 `verify.md` 写明跳过原因。
+
+建议命令和产物:
+
+```bash
+devflow test joint --cmd="npm run test:e2e" --backend-url=<url> --frontend-url=<url>
+devflow test e2e --cmd="npm run test:e2e"
+devflow verify finalize
+```
+
+产物落点:
+
+- `reports/test-report.md#joint`:前后端联调、浏览器步骤、截图、失败详情。
+- `reports/test-report.md#e2e`:端到端入口、用户路径、断言结果。
+- `review.md`:UI / a11y / responsive / performance finding。
+
+## 2. ci-fix / pr-feedback
+
+目录:
+
+```text
+skills/ci-fix/
+```
+
+触发:
+
+- PR/MR 检查失败。
+- Jenkins / GitHub Actions / GitLab CI 失败。
+- reviewer comment 未解决。
+- deliver 前发现 required checks 未通过。
+
+要实现的功能:
+
+- 先读 CI 日志和 review comment,再修复。
+- 归因为 `code_error`、`env_error`、`flake`、`baseline`。
+- 把 comment 分类为 MUST / SHOULD / NIT。
+- 修完后重跑最小相关测试或远端 CI。
+- 在 `review -> apply -> verify -> deliver` 之间形成闭环。
+
+建议命令和产物:
+
+```bash
+devflow review --round
+devflow apply
+devflow test unit --cmd="<focused test>"
+devflow verify finalize
+```
+
+产物落点:
+
+- `review.md`:把 reviewer comment 或 CI finding 分成 MUST / SHOULD / NIT。
+- `reports/test-report.md#unit/#integration/#smoke`:修复后的最小验证证据。
+- `state.json`:review 轮次、checkpoint、是否允许进入 verify。
+
+## 3. dependency-upgrade
+
+目录:
+
+```text
+skills/dependency-upgrade/
+```
+
+触发:
+
+- npm / Maven / Go module / Python 依赖升级。
+- lockfile 更新。
+- 安全漏洞修复。
+- 框架版本、构建工具版本变更。
+
+要实现的功能:
+
+- 识别 patch / minor / major。
+- 检查 changelog、breaking changes、peer dependency。
+- 同步更新 manifest 和 lockfile。
+- 跑最小必要测试。
+- 输出升级列表、风险和回滚说明。
+
+建议命令和产物:
+
+```bash
+devflow apply
+devflow test unit --cmd="<package focused test>"
+devflow test integration --cmd="<compatibility test>"
+devflow verify finalize
+```
+
+产物落点:
+
+- `design.md`:升级原因、影响面、兼容策略。
+- `plan.md`:manifest / lockfile / 适配代码 / 验证任务拆分。
+- `reports/test-report.md`:升级后的兼容性证据。
+- `deliver` 描述:升级列表、风险、回滚方式。
+
+## 4. handoff / resume
+
+目录:
+
+```text
+skills/handoff-resume/
+```
+
+触发:
+
+- 任务很长。
+- 上下文快满或发生压缩。
+- 用户说"接着上次继续"。
+- 多人或多 agent 接力。
+
+要实现的功能:
+
+- 生成或读取 `handoff.md`。
+- 记录当前 phase、checkpoint、已完成、未完成、风险、验证、下一步命令。
+- resume 时优先读 `state.json`、checkpoint、`reports/test-report.md`。
+- 避免下一个 agent 从头扫描或重复做已完成事项。
+
+建议命令和产物:
+
+```bash
+devflow status --slug=<slug>
+devflow checkpoint list --slug=<slug>
+devflow verify finalize
+```
+
+产物落点:
+
+- `handoff.md`:当前 phase、checkpoint、已完成、未完成、风险、验证、下一步命令。
+- `state.json`:事实状态优先于对话记忆。
+- `reports/test-report.md`:恢复时判断哪些验证已经完成。
+
+## 5. security-hardening
+
+目录:
+
+```text
+skills/security-hardening/
+```
+
+触发:
+
+- L3。
+- 支付、隐私、权限、鉴权、回调、文件上传、OSS/SLS、token/cookie/password。
+- 依赖漏洞修复。
+
+要实现的功能:
+
+- code-review 增加 security section。
+- verify 增加安全验证说明或 security subsection。
+- 检查敏感信息、权限绕过、注入、SSRF、XSS、回调验签、日志脱敏、依赖漏洞。
+- 风险接受必须有 owner 和 reason。
+
+建议命令和产物:
+
+```bash
+devflow design --with-tests
+devflow review --round
+devflow test integration --cmd="<security related test>"
+devflow verify finalize
+```
+
+产物落点:
+
+- `design.md`:鉴权、权限边界、回调验签、日志脱敏、降级和回滚。
+- `review.md`:security section。
+- `reports/test-report.md#integration/#contract/#self-test`:安全相关验证和人工检查结果。
+
+## 不建议做成默认强制阶段的原因
+
+- 这些 skill 是风险增强器,不是每个 change 都需要。
+- 强行默认触发会让 L0/L1 变重,违背懒生成和分级原则。
+- 它们应由 diff、level、用户意图、phase 风险触发。
+
+推荐策略:
+
+- L0:默认不用,除非用户明确要求。
+- L1:按 diff 类型触发 frontend/dependency/ci。
+- L2:有前端、调用链、依赖、安全信号时触发。
+- L3:默认考虑 security;跨服务/前端链路考虑 frontend + contract;CI 失败触发 ci-fix。