@colin4k1024/tsp 2.4.5 → 2.4.7

package/docs/runbooks/kubeconform-schema-gates.md

@@ -1,100 +0,0 @@
-# Kubeconform Schema 门禁手册
-
-本手册承接 `yannh/kubeconform` 的工程实践，用于把 Kubernetes manifest 的 schema 级校验接入 PR、评审和发布前预检。它补的是“这个 YAML / JSON 是否符合对应 Kubernetes OpenAPI / JSON Schema 结构”的验证层，不替代策略引擎、漏洞扫描、镜像治理或集群 admission 强制。
-
-## 用途/定位
-
-Kubeconform 是一个面向 Kubernetes manifests 的快速结构校验器，重点验证资源对象是否满足官方 OpenAPI 所表达的字段、类型和结构约束。它适合放在最前面的门禁层，用来尽早拦截明显的字段拼写错误、类型错误、资源结构不合法，以及 CRD 相关的 schema 不匹配问题。
-
-它的定位不是“安全审计器”，也不是“策略判定器”，而是“先把 manifest 形状校正好”的基础质量门禁。更具体地说，它适合回答的是：
-
-- 这个资源对象能不能被 Kubernetes schema 识别
-- 这个字段类型和层级结构对不对
-- 这个 CRD / 自定义资源的 schema 是否能被当前校验链路覆盖
-
-## 适用场景
-
-- 仓库中存在 Kubernetes YAML、Helm 渲染产物、kustomize 输出或其他最终会落到集群的 manifest。
-- 团队希望在提交和评审阶段尽早发现字段拼写、类型、层级、必填项和对象结构错误。
-- 团队需要对多版本 Kubernetes 兼容性做基础校验，并希望显式指定目标版本或 schema 源。
-- 团队使用 CRD 或自定义资源，希望把可获得的 schema 纳入统一校验，而不是等到集群里才发现对象不可用。
-- 团队需要一个高吞吐、低噪音的前置校验层，作为后续策略和安全门禁的输入净化步骤。
-
-## 不适用场景
-
-- 期望 Kubeconform 替代 `conftest-policy-gates` 的 Rego 策略判断。
-- 期望 Kubeconform 替代 `trivy-security-gates` 的漏洞、secret、misconfiguration 和镜像层扫描。
-- 期望 Kubeconform 替代 `policy-controller-gates` 在 Kubernetes admission 层的强制执行。
-- 期望它判断资源是否符合团队的权限模型、网络策略、镜像来源、SBOM、签名或 provenance 要求。
-- 期望它覆盖 Kubernetes 控制器的所有 server-side 校验，因为 OpenAPI schema 本身覆盖不到全部运行时语义。
-- 仓库里根本没有 Kubernetes manifests，却为了“流程完整”硬塞一个 schema validator。
-
-## 推荐落地方式
-
-1. 把 Kubeconform 放在 manifest 生成链路的最前面，先做结构校验，再交给后续策略和安全检查。
-2. 先固定校验范围：
-   - 原始 Kubernetes YAML
-   - Helm 渲染后的最终清单
-   - kustomize 输出
-   - 明确纳入的 CRD 和自定义资源
-3. 先把目标 Kubernetes 版本、schema 来源和 CRD 覆盖范围定下来，再决定是否启用更严格的模式。
-4. 将门禁分层，避免职责重叠：
-   - `helm-unittest-playbook` 负责 Helm chart 模板、values 组合和 snapshot 层的本地渲染断言
-   - `kubeconform-schema-gates` 负责 manifest 的 OpenAPI / JSON Schema 结构校验
-   - `kubectl-server-dry-run-gates` 负责把 manifests 送到 API server 做不落盘预检，确认 server-side 接受性
-   - `conftest-policy-gates` 负责结构化配置上的 policy-as-code 规则
-   - `trivy-security-gates` 负责镜像、文件系统和 IaC 的漏洞与安全风险扫描
-   - `policy-controller-gates` 负责在集群 admission 层强制执行已确认的策略
-5. 对 CRD 场景，优先保证 schema 来源可追溯、版本明确、覆盖稳定，再考虑扩大到更多自定义类型。
-6. 如果团队需要更接近集群实际行为的确认，应把 Kubeconform 视为前置静态校验，而不是最终可运行性证明。
-
-## 最小门禁模型
-
-- `input layer`：Kubernetes manifests、Helm 渲染结果、kustomize 输出或 CRD 相关清单
-- `schema layer`：Kubernetes OpenAPI / JSON Schema、指定版本 schema、CRD 衍生 schema
-- `validation layer`：Kubeconform 对对象字段、类型、结构和资源定义做静态验证
-- `decision layer`：`qa-engineer`、`devops-engineer`、`tech-lead` 根据结果判断是否阻塞合并或发布
-
-这个门禁的关键不是“跑了一个校验器”，而是团队能否稳定回答“这个 manifest 为什么不合法、是 schema 不足还是文件本身有问题、是否需要升级到后续门禁继续判断”。
-
-## 重点检查项
-
-- manifest 是否与目标 Kubernetes 版本匹配，而不是拿过旧或过新的 schema 盲测
-- 对象字段名、类型、数组 / map 结构是否和 schema 一致
-- 必填字段、枚举约束和资源层级是否正确
-- CRD 或自定义资源是否有明确可追溯的 schema 来源，避免“默认 schema 不认识就算通过或算失败”这种不稳定行为
-- 是否需要更严格的模式来捕获额外字段、重复键或隐式拼写错误
-- 是否存在大量被忽略的 kind / GVK，导致门禁看似通过，实际没有覆盖关键资源
-- 是否已经把 OpenAPI 能验证的结构问题和需要后续策略校验的问题分开，避免职责混杂
-
-## 反模式
-
-- 把 Kubeconform 当成 Kubernetes 安全基线工具，拿它去管权限、漏洞、签名或镜像来源。
-- 只接默认 schema，却没有明确 CRD 覆盖策略，导致自定义资源要么被误判、要么根本没被覆盖。
-- 把所有 schema 不匹配都当成“集群会自动处理”，不回到 manifest 生成阶段修正。
-- 同时启用 `conftest-policy-gates`、`trivy-security-gates`、`policy-controller-gates`，却没有说明各自检查层，最后同一类问题在多个工具里重复或遗漏。
-- 只看通过率，不看哪些资源被跳过、哪些版本不匹配、哪些 schema 来源不可信。
-
-## 输出回落
-
-- PR 阶段：把 schema 不匹配、字段类型错误、CRD 覆盖缺口和修复建议写入 review 摘要。
-- 评审阶段：在 `/team-review` 中明确哪些问题是 manifest 结构错误，哪些需要交给后续 policy 或安全门禁继续判断。
-- 发布阶段：若关键 manifests 仍存在 schema 级错误，必须回写到 `/team-release` 的风险项、阻塞项或修复待办中。
-- 治理阶段：把目标 Kubernetes 版本、schema 源、CRD 覆盖策略和例外规则沉淀到团队 runbook 或发布规范中。
-
-## 许可证与使用边界
-
-- `yannh/kubeconform` 采用 Apache-2.0。
-- Kubeconform 只验证 Kubernetes 官方 OpenAPI / JSON Schema 能表达的结构约束，不覆盖所有 server-side 语义校验。
-- 官方文档明确指出，Kubernetes controllers 还会做额外的 server-side validation，这部分需要其他工具或 `kubectl --dry-run=server` 之类的机制补足。
-- 对自定义资源而言，校验质量取决于 schema 源和 CRD 转换质量，不能把“schema 可用”误当成“运行时一定可用”。
-
-## 参考来源
-
-- [yannh/kubeconform](https://github.com/yannh/kubeconform)
-- [yannh/kubernetes-json-schema](https://github.com/yannh/kubernetes-json-schema)
-- [helm-unittest-playbook.md](helm-unittest-playbook.md)
-- [kubectl-server-dry-run-gates.md](kubectl-server-dry-run-gates.md)
-- [conftest-policy-gates.md](conftest-policy-gates.md)
-- [trivy-security-gates.md](trivy-security-gates.md)
-- [policy-controller-gates.md](policy-controller-gates.md)

package/docs/runbooks/kubectl-server-dry-run-gates.md

@@ -1,103 +0,0 @@
-# Kubectl Server Dry-Run 门禁手册
-
-本手册承接 Kubernetes 官方关于 `kubectl apply --server-side [--dry-run=server]`、server-side apply、字段管理和 server-side validation 的工程实践，用于把“先把变更送到 API server 做一次不落盘预检”纳入 PR、评审和发布前检查。它是 reference-only 的静态说明，不替代集群内真实发布，也不替代 schema、policy 或 admission 强制门禁。
-
-## 用途/定位
-
-`kubectl --dry-run=server` 的核心价值，是让变更在不真正持久化的前提下，走一遍 API server 能理解的接收流程。对 `kubectl apply` 而言，这意味着它不仅看本地文件，还会把请求交给 server 侧做处理；配合 `--server-side` 使用时，还会进入 server-side apply 的字段管理、冲突检测和 validation 路径。
-
-这个门禁适合回答的是：
-
-- 这个变更在目标集群的 API server 上能不能被接受
-- server-side apply 视角下会不会发生字段所有权冲突
-- 目标集群对该对象的 server-side validation 是否能通过
-- 这次变更在不落盘的情况下，会暴露出哪些默认值、字段管理或权限问题
-
-它不负责判断“这是不是团队允许的配置”，也不负责判断“这是不是最优的安全姿态”。它关注的是 server 端能否接住这次 declarative intent。
-
-## 适用场景
-
-- 变更会通过 `kubectl apply`、`kubectl apply --server-side`、GitOps 预处理或类似流程进入集群。
-- 团队希望在合并前尽早发现对象在目标集群上不可接受的问题，例如字段冲突、校验失败、权限不足或资源定义不兼容。
-- 团队已经有稳定的 API server 连接、明确的 kubeconfig、可控的 RBAC，以及清晰的目标集群版本。
-- 团队需要把“本地渲染通过”与“server 端真的能接受”分开验证，避免只在文件级通过、上线后才失败。
-- 团队希望补足离线 schema 校验无法覆盖的 server-side 行为，例如字段管理冲突和 server-side validation 的实际结果。
-
-## 不适用场景
-
-- 期望它替代 `kubeconform-schema-gates` 的 OpenAPI / JSON Schema 结构校验。
-- 期望它替代 `conftest-policy-gates` 的 Rego policy 规则判断。
-- 期望它替代 `policy-controller-gates` 在集群 admission 层的强制执行。
-- 没有可访问的目标 API server，却想把它当成纯本地 lint 工具。
-- 团队还没有统一的 field manager、目标集群版本和 RBAC 约定，导致 dry-run 结果不稳定。
-- 需要判断镜像漏洞、SBOM、签名、provenance、网络安全或运行时策略时。
-
-## 推荐落地方式
-
-1. 把 `kubectl apply --server-side --dry-run=server` 放在“渲染后、落盘前”的预检层，优先检查目标集群是否愿意接受这次声明式变更。
-2. 统一使用稳定的 field manager，并将其和流水线、环境或控制器身份对齐，避免不同执行主体混用同一名字。
-3. 只把它当成“server 接受性预检”，不要把它当成唯一门禁。
-4. 将门禁分层：
-   - `kubeconform-schema-gates` 负责 manifest 的 schema 结构校验
-   - `kubectl-server-dry-run-gates` 负责把变更送到 API server 做不落盘预检，观察 server-side apply、validation 和冲突结果
-   - `conftest-policy-gates` 负责配置策略、团队规则和 policy-as-code
-   - `policy-controller-gates` 负责在集群 admission 层强制执行已确认策略
-5. 对于可能存在字段冲突的资源，先用 dry-run 暴露冲突，再决定是调整 manifest、切换 field manager，还是回到上游 owner 协调字段所有权。
-6. 把结果回写到评审或发布结论，而不是把 dry-run 当成一次“只是看看”的临时命令。
-
-## 最小门禁模型
-
-- `input layer`：渲染后的 Kubernetes manifests、Helm 输出、kustomize 输出或直接的 YAML / JSON 资源定义
-- `server preflight layer`：`kubectl apply --server-side --dry-run=server`，必要时配合 `--validate=strict`
-- `server behavior layer`：API server 的对象接收、server-side validation、defaulting、field management 和冲突检测
-- `decision layer`：`qa-engineer`、`devops-engineer`、`tech-lead` 根据结果判断是否阻塞合并或发布
-
-最小模型的关键，不是“命令有没有跑完”，而是团队是否能稳定回答：
-
-- 这个对象是因为 schema 问题失败，还是因为 server-side 语义问题失败
-- 失败来自字段冲突、校验失败，还是 RBAC / 访问路径问题
-- 这次 dry-run 的结果能否代表目标集群当前真实行为
-
-## 重点检查项
-
-- 是否明确使用了 `--server-side`，避免把 client-side 习惯误以为是 server-side 预检
-- 是否把 `--dry-run=server` 和 `--validate=strict` 的意义区分清楚，避免只做“看起来像校验”的假门禁
-- 是否固定了目标集群、kubeconfig、命名空间和 field manager，避免结果受隐式上下文影响
-- 是否检查字段冲突，尤其是被其他管理者或控制器接管过的字段
-- 是否关注 server-side validation 的真实结果，而不是只看本地文件是否能被解析
-- 是否把 warning、conflict 和 validation failure 分别记录，避免把所有失败都混成“kubectl 不好使”
-- 是否识别出这类门禁依赖 API server 在线可达，不能拿它替代离线的 schema / policy 检查
-- 是否在目标集群版本升级后重新验证 dry-run 行为，因为 server-side 行为会随集群能力变化
-
-## 反模式
-
-- 把 `kubectl --dry-run=server` 当成离线 YAML linter，用来替代 schema 校验或策略审查。
-- 只在开发机本地跑一次，就把结果当成所有环境都成立的结论。
-- field manager 命名随人、随流水线、随仓库变化，导致字段所有权判断失去稳定性。
-- 把 dry-run 的成功理解成“资源一定能稳定运行”，忽略 admission、控制器回调和运行时依赖。
-- 看到冲突就直接加 `--force-conflicts`，却没有先确认字段所有权和变更边界。
-- 不区分 `dry-run=client` 和 `dry-run=server`，把“本地预览”误当成“server 接受性验证”。
-
-## 输出回落
-
-- PR 阶段：把 server-side validation failure、field conflict、权限不足和建议修正写入 review 摘要。
-- 评审阶段：在 `/team-review` 中明确这是 API server 侧预检结果，和 schema / policy / admission 结果分开记录。
-- 发布阶段：若 dry-run 暴露出关键对象不可接受，必须回写到 `/team-release` 的阻塞项、风险项或修复待办中。
-- 治理阶段：把目标集群版本、field manager 约定、RBAC 前提和例外流程沉淀到团队 runbook 中。
-
-## 许可证与使用边界
-
-- Kubernetes 官方文档按 CC BY 4.0 许可分发；本手册仅做工程归纳，不复制大段原文。
-- `kubectl --dry-run=server` 依赖目标 API server 在线可达，也依赖目标集群当前的 validation、defaulting 和 field management 行为。
-- 官方文档说明，server-side apply 以 patch 语义工作，且需要合适的权限；对既有资源需要 `patch` 权限，对新建资源还需要 `create` 权限。
-- 官方文档也说明，`kubectl apply --server-side` 可以与 `--dry-run=server` 一起使用，并支持 `--field-manager`；当 `--validate=strict` 可用时，它会尝试使用 server-side validation，若集群不支持则可能回退到较弱的客户端校验。
-- 这意味着它是“目标集群接受性预检”，不是“最终放行证明”，更不是 admission 强制。
-
-## 参考来源
-
-- [kubectl apply | Kubernetes](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_apply/)
-- [Server-Side Apply | Kubernetes](https://kubernetes.io/docs/reference/using-api/server-side-apply/)
-- [kubectl Usage Conventions | Kubernetes](https://kubernetes.io/docs/reference/kubectl/conventions/)
-- [kubeconform-schema-gates.md](kubeconform-schema-gates.md)
-- [conftest-policy-gates.md](conftest-policy-gates.md)
-- [policy-controller-gates.md](policy-controller-gates.md)

package/docs/runbooks/kyverno-policy-gates.md

@@ -1,90 +0,0 @@
-# Kyverno Policy 门禁手册
-
-本手册基于 `kyverno/kyverno` 的官方文档与仓库信息整理，用于说明 Kyverno 在 Kubernetes admission、background scan、policy report 和 image verification 场景里的落地边界。它补的是“把 Kubernetes 策略在集群内执行，并把结果回流到治理链”这一层，不替代通用配置策略扫描、漏洞扫描或独立的供应链强制组件。
-
-## 用途 / 定位
-
-Kyverno 是 Kubernetes 原生的 policy engine。官方文档说明它以 dynamic admission controller 方式工作，同时配套 background scans 和 policy reports；它既能做 `validate` / `mutate` / `generate`，也能做镜像签名与 attestation 校验。对于当前仓库来说，Kyverno 更适合被定位为“集群内的策略执行层 + 策略回报层”，而不是通用扫描器。
-
-## 适用场景
-
-- 需要对 Kubernetes 资源做 admission 级拦截或审计，例如标签、镜像引用、工作负载约束、命名约束、namespace 约束。
-- 需要先用 `Audit` 观察策略影响，再逐步切到 `Enforce`。
-- 需要对现有资源做 background scan，评估新策略对存量 workload 的影响。
-- 需要在集群里对镜像签名、attestation 或 digest 约束做原生校验。
-- 需要把策略执行结果沉淀为 Policy Report，便于治理、排障和回溯。
-
-## 不适用场景
-
-- 只想扫漏洞、secret、IaC misconfiguration，且没有明确的 Kubernetes 策略执行需求。
-- 只想对任意结构化配置做离线 policy-as-code 预检，不打算进入 Kubernetes admission 或 background 体系。
-- 团队已经明确选择 `sigstore/policy-controller` 作为镜像签名与 attestation 的 admission 强制层，不希望重复维护一套 Kyverno 镜像策略。
-- 期望 Kyverno 替代人工发布判断、依赖审查或制品安全扫描。
-
-## 推荐落地方式
-
-1. 先把 Kyverno 的职责收窄到 Kubernetes 资源治理，不要一开始就把所有平台规则都塞进同一组 policy。
-2. 先从 `validate` 策略开始，配合 `Audit` 和 background scan 观察影响，再决定哪些规则升到 `Enforce`。
-3. 对镜像治理，优先使用 Kyverno 官方支持的 `verifyImages` 或 `ImageValidatingPolicy` 能力来做签名、attestation、digest 约束，而不是把镜像安全问题拆成多个互相重复的规则源。
-4. 在 CI / 预检阶段，可以用 Kyverno CLI 对资源清单做离线应用和 policy report 生成；在集群内则由 admission controller 和 reports controller 负责持续执行与回报。
-5. 在当前仓库的分工里，建议这样分层：
-   - `conftest-policy-gates` 负责 Kubernetes 之外的结构化配置 policy-as-code 预检
-   - `kyverno-policy-gates` 负责 Kubernetes admission、background scan、policy report 和 image verification
-   - `policy-controller-gates` 负责以 policy-controller 方式做 admission 层的镜像签名 / attestation 强制
-   - `trivy-security-gates` 负责漏洞、secret 和 IaC 安全扫描
-6. 如果同一类规则已经在 `conftest` 或 `policy-controller` 中被明确拥有，就不要再用 Kyverno 重复实现一套相同语义的门禁，避免三套策略漂移。
-
-## 最小门禁模型
-
-- `policy layer`：Kyverno `Policy` / `ClusterPolicy`，或新一代 `ValidatingPolicy` / `ImageValidatingPolicy`
-- `evaluation layer`：admission control、background scan、Kyverno CLI policy apply / policy report
-- `report layer`：PolicyReport / ClusterPolicyReport，外加 Kubernetes events
-- `decision layer`：`qa-engineer`、`devops-engineer`、`tech-lead` 决定是否进入 `Audit`、是否升级到 `Enforce`、是否接受例外
-
-最小可用模型不是“装了 Kyverno”，而是至少要同时具备策略定义、评估路径、报告回流和例外治理四件事。
-
-## 重点检查项
-
-- 策略类型是否选对：资源校验优先 `validate`，资源变更才考虑 `mutate` / `generate`，镜像校验才考虑 `verifyImages` 或 `ImageValidatingPolicy`
-- `failureAction` 是否明确，`Audit` 与 `Enforce` 是否按阶段推进
-- `background` 是否和策略用途一致；需要存量扫描时保持开启，不需要时显式关闭
-- `match` / `exclude` 范围是否过宽，是否会误伤系统 namespace 或平台组件
-- 镜像约束是否以 digest、签名或 attestation 为依据，而不是只靠 tag 字符串
-- Policy Report 是否被用于当前状态观察，而不是误当成历史审计账本
-- 例外机制是否通过 Kyverno 官方支持的 policy exception 能力或明确的治理流程管理，而不是临时改 policy 绕过去
-
-## 反模式
-
-- 把 Kyverno 当成通用漏洞扫描器，结果只看到了策略结果，没有建立真正的安全证据链。
-- 先上全局 `Enforce`，再回头补例外和可视化，导致大量正常工作负载被拦。
-- 在 `conftest`、`policy-controller`、Kyverno 三套体系里重复表达同一条规则，却没有统一 owner。
-- 只看 admission 结果，不看 background scan 和 policy report，导致存量违规一直被忽略。
-- 用 Kyverno 做轻量的结构化配置 lint，却不打算把它接入 Kubernetes 策略生命周期。
-
-## 输出回落
-
-- 评审阶段：把 Kyverno 命中的策略、影响范围、例外判断写回 `/team-review`。
-- 发布阶段：若策略将阻塞部署或已触发 `Enforce` 拒绝，必须写回 `/team-release` 的风险、放行结论或后续观察项。
-- 平台治理：将长期稳定的 policy、命中样例和例外流程沉淀到平台治理文档或策略仓库，而不是只留在集群事件里。
-
-## 许可证与使用边界
-
-- `kyverno/kyverno` 采用 Apache-2.0。
-- Kyverno 适合用来做 Kubernetes 原生策略治理、background scan 和 image verification，但不应被当作通用漏洞扫描器或任意配置的唯一门禁。
-- 如果团队已经选择 `sigstore/policy-controller` 作为镜像签名与 attestation 的最终 admission 强制层，Kyverno 的同类能力应避免重复建设，除非已经明确分层并有独立 owner。
-- 若团队需要对 Kubernetes 之外的 JSON / YAML / 结构化配置做 policy-as-code 预检，应优先走 `conftest-policy-gates` 的边界，而不是把非 Kubernetes 规则硬塞进 Kyverno。
-
-## 参考来源
-
-- [kyverno/kyverno](https://github.com/kyverno/kyverno)
-- [How Kyverno Works](https://kyverno.io/docs/introduction/how-kyverno-works/)
-- [Applying Policies](https://kyverno.io/docs/applying-policies/)
-- [Kyverno CLI](https://kyverno.io/docs/subprojects/kyverno-cli/)
-- [Policy Types](https://kyverno.io/docs/policy-types/)
-- [ValidatingPolicy](https://kyverno.io/docs/policy-types/validating-policy/)
-- [ImageValidatingPolicy](https://kyverno.io/docs/policy-types/image-validating-policy/)
-- [Verify Images Rules](https://kyverno.io/docs/policy-types/cluster-policy/verify-images/)
-- [Policy Reports](https://kyverno.io/docs/policy-reports/)
-- [conftest-policy-gates.md](conftest-policy-gates.md)
-- [policy-controller-gates.md](policy-controller-gates.md)
-- [trivy-security-gates.md](trivy-security-gates.md)

package/docs/runbooks/langfuse-and-observability-integration-guide.md

@@ -1,43 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# Langfuse 追踪与可观测性集成指南
-
-本文说明 Langfuse 在 Team Skills Platform 中应该怎样作为可观测性补充能力使用。重点是何时启用、记录什么、如何回写主链，而不是单独讨论脚本调用。
-
-## 1. 什么时候值得启用
-
-- 任务跨多个阶段，需要追踪关键决策或验证链路
-- 发布或事故处理需要保留更可追溯的执行证据
-- 团队需要把 AI 辅助执行与后续排障连接起来
-
-## 2. 不应该指望它做什么
-
-- 不替代 `/team-execute` 的实现说明
-- 不替代 `/team-review` 的质量结论
-- 不替代 `/team-release` 的放行、回滚和观察窗口
-
-## 3. 推荐记录粒度
-
-- trace：一次任务、一次发布、一次事故处理
-- span：某个阶段，如 intake、execute、verify、release
-- 关键标签：任务名、角色、风险级别、是否命中 custom overlay
-
-## 4. 回写位置
-
-- execute 阶段：记录是否开启 trace、关键 span 与异常点
-- review 阶段：只在可观测性证据影响结论时引用
-- release 阶段：记录观察窗口、异常事件和后续动作
-
-## 5. 常见错误
-
-- 没有决定记录粒度，就把所有步骤都打点
-- 追踪信息很多，但主链输出没有任何回写
-- 把 Langfuse 追踪误当成审计结论本身
-
-与这些文档配合阅读：[langfuse-coding-trace.md](langfuse-coding-trace.md)、[production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)

package/docs/runbooks/langfuse-coding-trace.md

@@ -1,44 +0,0 @@
-# Langfuse 编码追踪手册
-
-本手册承接原 `langfuse-coding-trace` custom overlay。它现在是编码、QA、发布流程的可观测性补充 runbook，不再作为正式 `skills/` 安装入口。
-
-如果你想先判断什么时候该启用 Langfuse、记录哪些 trace 和 span，以及如何回写主链，继续看 [langfuse-and-observability-integration-guide.md](langfuse-and-observability-integration-guide.md)。
-
-## 适用场景
-
-- 当前任务已经存在编码、QA 或发布执行链，需要补充 Langfuse Trace / Span 记录。
-- 追踪失败不能阻塞主流程。
-
-## 前置条件
-
-需要在执行环境中提供以下变量；缺失时直接声明“未开启 Langfuse 追踪”，主流程继续：
-
-- `LANGFUSE_PUBLIC_KEY`
-- `LANGFUSE_SECRET_KEY`
-- `LANGFUSE_HOST`
-
-## 执行入口
-
-脚本位置：
-
-```bash
-node scripts/langfuse-trace.js
-```
-
-主链阶段可按需调用：
-
-- `trace-start`
-- `span-start`
-- `span-end`
-- `trace-end`
-
-## 输出回落
-
-- 在 `/team-execute` 中记录是否开启追踪、trace 名称、关键 span 结果。
-- 若发布链使用，也同步回落到 `/team-release` 的 `可选领域扩展执行记录`。
-
-## 使用约定
-
-1. Trace / Span 名称尽量和 `/team-*` 阶段或实际 skill 名保持一致。
-2. 追踪只是附加证据，不能替代实现说明、自测结论、QA 结果或放行结论。
-3. 若任务需要对外审计，在输出中显式说明“已开启 / 未开启 Langfuse 追踪”。

package/docs/runbooks/mobile-miniapp-delivery-walkthrough.md

@@ -1,112 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# 移动端与小程序交付演练
-
-本文演示一个移动端 / 小程序需求如何从终端边界澄清、交互约束、适配拆解、实现、自测到 QA 收口完整跑通。重点是多终端和弱网边界，而不是只看桌面端页面开发。
-
-## 1. 场景
-
-- 任务：新增移动端报销申请页与提交流程
-- 项目主要运行在手机和企业移动容器中
-- 风险集中在弱网、终端权限、交互反馈和多尺寸适配
-
-## 2. 推荐链路
-
-1. `/team-intake`
-2. `/team-plan`
-3. `/tdd`
-4. `/multi-frontend`
-5. `/team-execute`
-6. `/handoff`
-7. `/team-review`
-
-## 3. 第一步：/team-intake
-
-### 输入示例
-
-```text
-/team-intake
-目标：新增移动端报销申请页与提交流程
-范围：页面布局、表单交互、终端权限、测试计划
-不做：后端流程改造
-约束：必须说明多尺寸适配、弱网、授权路径、拒绝态和加载反馈
-```
-
-### 期望输出重点
-
-- 明确终端范围、机型范围和容器范围
-- 锁定权限路径、拒绝态、网络异常态和加载态
-- 判断是否需要额外引入 `backend-engineer` 或 `architect`
-
-## 4. 第二步：/team-plan
-
-### 应拆解的内容
-
-- 页面和表单结构
-- 授权路径和拒绝态
-- 多尺寸与横竖屏适配
-- QA 真机 / 模拟器 / 弱网验证范围
-- handoff 中需要保留的终端风险说明
-
-### 计划中最容易漏的内容
-
-- 容器差异
-- 弱网下的加载和重试
-- 权限拒绝后的兜底方案
-
-## 5. 第三步：/tdd
-
-在移动端项目里，`/tdd` 建议优先锁定：
-
-- 机型与尺寸范围
-- 弱网场景
-- 权限拒绝态
-- 空态、异常态、加载态
-- 成功提交与失败回退行为
-
-## 6. 第四步：/multi-frontend
-
-Multi-fronted 阶段建议并行拆成：
-
-- 交互体验
-- 终端适配
-- QA 风险
-
-输出最终要回到 handoff，至少包含：
-
-- 已确认终端行为
-- 剩余适配风险
-- QA 重点回归链路
-
-## 7. 第五步：/team-execute 与 /handoff
-
-执行阶段要沉淀：
-
-- 代码改动摘要
-- 多终端自测范围
-- 权限授权 / 拒绝行为
-- 弱网和加载反馈结果
-
-handoff 中则要把这些内容整理成 QA 能直接接住的结构化结论。
-
-## 8. 第六步：/team-review
-
-Review 阶段要回答：
-
-- 哪些终端和场景已验证
-- 是否还存在阻塞上线的终端风险
-- 哪些问题可以留到下一轮优化
-
-## 9. 常见错误
-
-- 只验证 happy path，不验证弱网和拒绝态
-- 只看浏览器模拟，不说明真机范围
-- handoff 不写终端差异，导致 QA 只能重新摸索验证范围
-
-建议配合阅读：[frontend-engineer-daily-operations.md](frontend-engineer-daily-operations.md)、[qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)、[specialist-commands-playbook.md](specialist-commands-playbook.md)

package/docs/runbooks/mobile-miniapp-demo-execution-log.md

@@ -1,139 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# 移动端与小程序交付演示执行记录
-
-本文记录一条移动端 / 小程序需求演示路径，重点展示团队如何把终端边界、弱网、权限、交互反馈、多尺寸适配和 QA 验证组织成可交接的交付链路。
-
-## 1. 场景定义
-
-### 背景
-
-- 项目主要运行在手机与企业移动容器中
-- 需求是新增报销申请页与提交流程
-- 团队既要交付页面，也要保证弱网、权限拒绝和终端差异不在上线前失控
-
-### 演示目标
-
-- 让观众理解移动端项目的风险不只在 UI，而在终端边界和异常态
-- 让观众理解 `/multi-frontend` 如何帮助前置发现适配与体验风险
-- 让观众理解 handoff 为什么必须写清终端验证范围
-
-## 2. 阶段 1：/team-intake
-
-### 输入
-
-```text
-/team-intake
-目标：新增移动端报销申请页与提交流程
-范围：页面结构、表单交互、授权路径、多尺寸适配、测试计划
-不做：后端流程引擎改造
-约束：必须覆盖弱网、拒绝态、加载态、真机范围和容器差异
-```
-
-### 产出
-
-| 字段 | 内容 |
-|------|------|
-| 任务类型 | 移动端交付 / 多终端体验治理 |
-| 主体对象 | 页面、权限、终端适配、handoff、QA 验证 |
-| 主要风险 | 弱网失败、权限拒绝、容器差异、适配遗漏 |
-| 收口要求 | QA 必须能基于 handoff 直接接住验证范围 |
-
-## 3. 阶段 2：/team-plan
-
-### 拆解结果
-
-| 模块 | 动作 | 收口位置 |
-|------|------|----------|
-| 页面结构 | 布局、表单、反馈态 | frontend |
-| 终端适配 | 多尺寸、容器差异、横竖屏 | frontend / QA |
-| 权限路径 | 授权、拒绝、兜底逻辑 | frontend / handoff |
-| 异常场景 | 弱网、加载失败、重试 | test plan |
-| 最终验证 | 真机 / 模拟器 / 关键链路 | `/team-review` |
-
-### 关键判断
-
-- 移动端项目不能只写 happy path
-- QA 需要在 handoff 中直接拿到机型范围、权限路径和异常态说明
-
-## 4. 阶段 3：/tdd
-
-### 定义的完成标准
-
-```text
-1. 机型与容器范围明确
-2. 权限授权与拒绝态已定义
-3. 弱网、加载态、异常态有验证口径
-4. handoff 包含终端差异与已测范围
-5. review 能判断是否还有阻塞上线的终端风险
-```
-
-### 价值说明
-
-- 把移动端风险前置成显式测试标准
-- 避免只在开发自测末尾才发现真机问题
-
-## 5. 阶段 4：/multi-frontend 与 /team-execute
-
-### 执行批次
-
-#### 批次 A：交互与页面
-
-- 建立表单流程与成功 / 失败反馈
-- 统一加载态、空态和异常态
-
-#### 批次 B：终端适配
-
-- 检查多尺寸布局
-- 补容器差异处理
-- 验证授权路径
-
-#### 批次 C：handoff 准备
-
-- 汇总真机范围
-- 汇总弱网验证结果
-- 汇总剩余风险与待观察项
-
-## 6. 阶段 5：/handoff 与 /team-review
-
-### Handoff 结论
-
-- QA 已拿到终端范围、授权路径、弱网结果和剩余风险
-- 交接内容足以支撑直接回归，而不是重新摸索场景
-
-### Review 结论
-
-- 当前交付已覆盖核心终端与主要异常态
-- 若仍有非阻塞适配问题，应清晰标记为下一轮优化项
-
-## 7. 校验结果
-
-### 文档静态检查
-
-- 本轮新增 walkthrough 与 execution log 无错误
-
-### 仓库校验
-
-```text
-Validation passed.
-- Roles: 8
-- Shared skills: 3
-- ECC skills: 9
-- Private overlay skills: not shipped in public repo
-- Specialist agents: 27
-- Generated artifacts: 70
-```
-
-## 8. 推荐搭配材料
-
-- [mobile-miniapp-delivery-walkthrough.md](mobile-miniapp-delivery-walkthrough.md)
-- [../../examples/mobile-miniapp-CLAUDE.md](../../examples/mobile-miniapp-CLAUDE.md)
-- [../../examples/vertical-project-conversation-scripts.md](../../examples/vertical-project-conversation-scripts.md)
-- [frontend-engineer-daily-operations.md](frontend-engineer-daily-operations.md)
-- [qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)