@colin4k1024/tsp 2.4.0 → 2.4.2

package/docs/memory/decisions.md

@@ -0,0 +1,43 @@
+# Decisions Log
+
+> 追加策略：每次重大技术决策由主责角色追加，不覆盖历史行。格式：`## YYYY-MM-DD · {标题}`
+
+---
+
+## 2026-03-31 · Memory Persistence Hook 从被动等待改为主动采集
+
+**背景**：原 `session_end.py` 设计依赖 Claude 发送结构化 JSON 结束信号，实际上 Claude 从不发送该信号，导致 hook 永远处于等待状态，经验数据完全不落盘。
+
+**决策**：彻底重写 `session_end.py`，改为主动通过 `git log -15` + `docs/memory/` 文件读取的方式采集经验；`session_start.py` 改为双源加载（repo docs/memory/ + ~/.claude/memory/ 经验文件）。
+
+**影响**：hook 现在不依赖 Claude 输出行为，在任何 session end 场景下都能落盘。Smoke test 验证：15 commits、61 experience capsules。待确认：session_start payload 中 repo_memory_files_found 是否非空（依赖 docs/memory/ 存在）。
+
+---
+
+## 2026-03-31 · Observability Trace Skill 归入公共增强层
+
+**背景**：通用编码链路追踪能力不绑定特定业务系统，适合作为编码类 skill 的公共增强。
+
+**决策**：将这类能力保留在公开增强层，配置给 backend-engineer 和 qa-engineer，而不是作为私有企业扩展的默认依赖。
+
+**影响**：公共仓可以保留通用可观测性说明，而不会默认暴露私有企业发布或权限集成。
+
+---
+
+## 2026-04-01 · 文档架构能力并入 team 主链
+
+**背景**：需要将 eags 风格 discovery/modeling/audit 能力与当前 team-skills 体系整合，并避免并行文档目录。
+
+**决策**：新增 `skills/doc-architecture`，并将其装配到 tech-lead、architect、backend-engineer、frontend-engineer、qa-engineer、devops-engineer。同步增强 artifact 标准、输出契约与模板字段。
+
+**影响**：主链可直接产出并追溯 PRD、Plan、Arch、API、Execute、Test、Release、ADR、Session Summary，不需要新增 team 主命令。
+
+---
+
+## 2026-04-02 · Internal Workflow and Permission Case Studies Moved Out of Public Memory
+
+**背景**：部分记忆条目直接绑定私有流程系统、权限中心和组织专属案例，不适合作为公开仓的默认示例。
+
+**决策**：将组织专属案例从公开记忆层移出，只保留公共运行时、文档架构和平台演进相关的决策记录；私有案例转入 `enterprise` overlay 或私有仓。
+
+**影响**：公开仓的 `docs/memory/` 更适合外部用户阅读，也不会把私有领域案例误当成公共默认路径。

package/docs/memory/lessons-learned.md

@@ -0,0 +1,87 @@
+# Lessons Learned
+
+> 追加策略：由 qa-engineer 或 devops-engineer 在遇到可复用经验时追加。格式：`## YYYY-MM-DD · {标题}`
+
+---
+
+## 2026-03-31 · session_end hook 不能依赖 LLM 主动发送结构化数据
+
+**场景**：设计 memory persistence hook 时，原方案希望 Claude 在会话结束时输出结构化 JSON 摘要，由 hook 捕获存盘。
+
+**问题**：Claude 不会主动向 hook stdin 发送任何结束信号。`while True: line = sys.stdin.readline()` 会永久阻塞，数据永远不落盘。
+
+**建议**：session_end hook 应主动采集，而非被动等待。可读 git log、docs/memory/、changelog 等文件作为替代数据源；不依赖 LLM 在特定格式下产出数据。
+
+---
+
+## 2026-03-31 · _experience.json 文件格式与 SessionSummary dataclass 不兼容
+
+**场景**：session_end.py 在同一目录写入 `{id}.json`（SessionSummary）和 `{id}_experience.json`（experience capsules）两类文件。
+
+**问题**：`memory_store.py` 的 `load_latest_session_summary` 按日期排序读取所有 `.json` 文件，`_experience.json` 字段不同会导致 dataclass 反序列化失败。
+
+**建议**：在 `load_latest_session_summary` 中添加 `if "_experience" in session_file.name: continue` 跳过逻辑；或将两类文件放入不同子目录隔离。
+
+---
+
+## 2026-03-31 · docs/memory/ 目录必须提前初始化
+
+**场景**：session_start.py 重写后从 `docs/memory/project-context.md` 等文件读取上下文，但该目录在项目初始未被创建。
+
+**问题**：`repo_memory_files_found: []` — session_start 运行无报错但上下文为空，导致新会话缺少项目感知。
+
+**建议**：每个接入项目在首次配置 hooks 后，应立即创建 `docs/memory/project-context.md`、`decisions.md`、`lessons-learned.md` 三个基础文件，哪怕内容只是占位符。可在 `docs/runbooks/project-onboarding.md` 中补充这一步骤。
+
+---
+
+## 2026-03-31 · validate_library.py（当前等价 `node scripts/validate-library.js`）的 REQUIRED_ECC_SKILLS 必须与目录同步更新
+
+**场景**：新增 ecc skill（langfuse-coding-trace、harness-audit）后，历史脚本 `validate_library.py`（当前等价 `node scripts/validate-library.js`）仍只检查旧的 9 个 required skills。
+
+**问题**：新 skill 存在但不被验证，脚本 PASS 不代表实际完整性正确。
+
+**建议**：每次在 `skills/` 新增 skill 时，同步更新 `scripts/validate-library.js` 中的 `REQUIRED_ECC_SKILLS` 列表；可考虑改为动态读取 `skills/` 自动发现。
+
+---
+
+## 2026-04-01 · 文档能力整合优先走 artifacts 映射而非新目录
+
+**场景**：将外部文档能力并入 team-skills 主链。
+
+**问题**：若沿用外部目录习惯（architecture/domains/specs/plans/runbooks），会与现有 artifact 持久化规则冲突，导致事实源分裂。
+
+**建议**：统一把 discovery/modeling/audit 内容映射到现有 artifact 文件；新增能力优先通过 shared skill + 输出契约字段扩展落地，不新增并行主命令或并行主目录。
+
+---
+
+## 2026-04-09 · skills 子目录嵌套会阻止 Claude 自动发现
+
+**场景**：skills 按 shared/ecc/company 三层子目录组织（`skills/shared/api-contract`、`skills/ecc/eval-harness`），认为逻辑清晰。
+
+**问题**：Claude Code 只自动扫描 `skills/` 根目录下的 SKILL.md，嵌套一层子目录后 skill 不会出现在可用列表中，用户无法直接使用。
+
+**建议**：所有 skill 统一平铺到 `skills/` 根目录。分类信息通过 manifest module 和 role.yaml 的 recommended_*_skills 字段表达，不依赖目录层级。
+
+---
+
+## 2026-04-09 · JSON 文件中的 Unicode 弯引号导致解析歧义
+
+**场景**：`roles/architect/role.yaml` 中 outputs 字段包含中文弯引号 `"前端页面"`，Node.js `JSON.parse` 报错 position 422。
+
+**问题**：中文弯引号 U+201C/U+201D 在 JSON 字符串内部时，解析器会在遇到 ASCII `"` 时错误地判断字符串终止位置。
+
+**建议**：JSON 文件内的中文引号统一使用 `「」` 或反斜杠转义。CI 可加一条 pre-commit 检查，检测 .yaml/.json 中的 U+201C/U+201D。
+
+---
+
+## 2026-04-09 · 批量路径替换后验证脚本需单独修复
+
+**场景**：sed 全局替换了 `skills/shared/` → `skills/`，文档和配置文件正确，但验证脚本内部 `path.join(root, "skills", "shared", skill)` 硬编码路径未被替换。
+
+**问题**：验证脚本通过 string concat 拼路径，sed 替换 markdown/JSON 中的字符串引用时不会命中 JS/Python 代码中的路径拼接。
+
+**建议**：路径替换后，必须单独 grep 验证脚本中的硬编码子目录名（如 `"shared"`、`"ecc"`、`"company"`），并运行验证脚本确认。
+
+## 2026-04-17 - BMAD Source Adoption v2.2 closeout
+
+Closeout readiness for /team-closeout depends on complete artifacts (prd, delivery-plan, handoff, execute/review/release docs). When continuing from mid-stream work, run a gate completeness check early to avoid end-stage backfill.

package/docs/plans/2026-04-03-python-remnants-audit.md

@@ -0,0 +1,265 @@
+# Python Remnants Audit
+
+**Date:** 2026-04-03  
+**Scope:** `/scripts` remaining `.py` files after the JS-first migration waves  
+**Goal:** classify every remaining Python file into one of three buckets:
+
+- keep as compatibility shim
+- migrate next to JS
+- retire/delete
+
+> Historical snapshot: this audit captures Python remnants at that date.  
+> Current command equivalents for referenced core scripts:  
+> `scripts/build_platform_artifacts.py` -> `scripts/build-platform-artifacts.js`  
+> `scripts/validate_library.py` -> `scripts/validate-library.js`
+
+## Executive Summary
+
+The repository is **not yet Python-free**.
+
+The current state is:
+
+- the main operational path is already JS-first
+- several Python files remain intentionally as compatibility shims for tests and legacy entrypoints
+- a smaller set of Python files are still real implementations and should be considered the next migration targets
+- a final set are one-off maintenance/debug utilities and should be retired rather than migrated unless there is a live owner for them
+
+## Classification Rules
+
+### A. Keep as Compatibility Shim
+
+Use this bucket only when all of the following are true:
+
+1. there is already a JS primary implementation
+2. Python is still imported by tests, hooks, or legacy operators
+3. removing the Python file now would create unnecessary churn
+
+### B. Migrate Next to JS
+
+Use this bucket when:
+
+1. the Python file is still a real implementation
+2. it belongs to an actively used path
+3. the repository would be simpler if it moved into the Node toolchain
+
+### C. Retire/Delete
+
+Use this bucket when:
+
+1. the file is a one-off migration/debug utility
+2. it is not on the supported operational path
+3. it has no active owner or runbook dependency
+
+## Current Inventory
+
+Remaining Python files under `/scripts`:
+
+- `scripts/__init__.py`
+- `scripts/_inspect_project_session.py`
+- `scripts/_migrate_agent_governance.py`
+- `scripts/_register_audit_hooks.py`
+- `scripts/_ruoyi_audit_live.py`
+- `scripts/_ruoyi_detail.py`
+- `scripts/build_platform_artifacts.py`
+- `scripts/hooks/__init__.py`
+- `scripts/hooks/insaits-security-monitor.py`
+- `scripts/hooks/mcp_health_check.py`
+- `scripts/hooks/observe.py`
+- `scripts/hooks/session_end.py`
+- `scripts/hooks/session_start.py`
+- `scripts/install_platform.py`
+- `scripts/langfuse_trace.py`
+- `scripts/lib/audit_logger.py`
+- `scripts/lib/audit_query.py`
+- `scripts/lib/hook_contract.py`
+- `scripts/lib/memory_store.py`
+- `scripts/lib/utils.py`
+- `scripts/query_audit_logs.py`
+- `scripts/run_e2e_test.py`
+- `scripts/scan_leaked_keys.py`
+- `scripts/team_skills_platform.py`
+- `scripts/trigger_gitlab_pipeline.py`
+- `scripts/validate_library.py`
+- `scripts/validate_workflow_state.py`
+
+## Bucket 1: Keep as Compatibility Shim
+
+These files already have a JS-first runtime path and should remain temporarily as thin Python compatibility surfaces:
+
+- `scripts/build_platform_artifacts.py`
+- `scripts/install_platform.py`
+- `scripts/langfuse_trace.py`
+- `scripts/query_audit_logs.py`
+- `scripts/scan_leaked_keys.py`
+- `scripts/validate_library.py`
+- `scripts/validate_workflow_state.py`
+
+### Why
+
+- they preserve old commands such as `python3 scripts/<name>.py`
+- they protect existing imports in tests and legacy operator habits
+- the real implementation now lives in JS
+
+### Exit Criteria For Deletion
+
+These shims can be removed only after:
+
+1. docs no longer point to the Python entrypoints
+2. tests no longer import these Python modules directly
+3. shell and PowerShell wrappers are fully JS-native
+4. at least one cleanup cycle confirms no active operators still rely on Python invocation
+
+## Bucket 2: Keep as Python Compatibility Support For Now
+
+These files are not the canonical runtime anymore, but they still provide compatibility for current tests and hook behavior:
+
+- `scripts/hooks/mcp_health_check.py`
+- `scripts/hooks/observe.py`
+- `scripts/hooks/session_end.py`
+- `scripts/hooks/session_start.py`
+- `scripts/lib/audit_logger.py`
+- `scripts/lib/audit_query.py`
+- `scripts/lib/hook_contract.py`
+- `scripts/lib/memory_store.py`
+- `scripts/lib/utils.py`
+
+### Why
+
+- the current test suite imports these Python modules directly
+- they provide a stable bridge while the repository transitions from Python hook semantics to JS hook semantics
+- deleting them now would force a wider hook/test refactor than the main migration required
+
+### Recommendation
+
+Do **not** migrate these in the next wave by default.
+
+Instead choose one of two intentional end states:
+
+1. keep them as a supported Python compatibility layer for legacy hook/tests
+2. run a dedicated “hook/test runtime unification” project, then delete them together
+
+### Warning
+
+Migrating these one-by-one is the wrong shape of work. They are tightly coupled and should be handled as a single compatibility-surface decision.
+
+## Bucket 3: Migrate Next to JS
+
+These are the remaining Python files that still represent real implementation value and should be the next migration candidates.
+
+### High Priority
+
+- `scripts/team_skills_platform.py`
+- `scripts/trigger_gitlab_pipeline.py`
+
+### Medium Priority
+
+- `scripts/run_e2e_test.py` only if we decide to keep a standalone script surface
+
+### Why
+
+#### `scripts/team_skills_platform.py`
+
+- still contains the legacy Python source of truth for platform constants and generation logic
+- even though JS generation now exists, leaving this as a large Python implementation keeps conceptual duplication alive
+- this is the biggest remaining architectural inconsistency
+
+#### `scripts/trigger_gitlab_pipeline.py`
+
+- still performs real external automation work
+- belongs on the same Node operational surface as the rest of the script toolchain
+
+#### `scripts/run_e2e_test.py`
+
+- duplicates what the repository now handles through standard test entrypoints
+- is not part of the normal build / validate / install path
+- should be retired unless a real operator still depends on it
+
+## Bucket 4: Retire/Delete Instead of Migrating
+
+These look like one-off maintenance, audit, or local debugging tools and should not be migrated unless a current owner explicitly claims them.
+
+- `scripts/_inspect_project_session.py`
+- `scripts/_migrate_agent_governance.py`
+- `scripts/_register_audit_hooks.py`
+- `scripts/_ruoyi_audit_live.py`
+- `scripts/_ruoyi_detail.py`
+- `scripts/run_e2e_test.py`
+
+### Why
+
+- they are prefixed like internal maintenance tools
+- they are not part of the supported installation/build/validate path
+- migrating them to JS would create more surface area, not less
+
+### Default Action
+
+1. confirm no runbook depends on them
+2. move them to an archive or delete them
+3. if retained, label them clearly as internal legacy utilities
+
+## Bucket 5: Structural Python Files That Are Fine To Keep
+
+These are packaging markers, not meaningful migration targets:
+
+- `scripts/__init__.py`
+- `scripts/hooks/__init__.py`
+
+## Explicit Python Exception
+
+`scripts/hooks/insaits-security-monitor.py` is now treated as an **explicit supported Python exception**.
+
+### Why
+
+- it is a third-party SDK-facing hook, not core platform generation logic
+- the active integration surface is already JS-first through `scripts/hooks/insaits-security-wrapper.js`
+- forcing an immediate port would couple this migration to the external InsAIts Python SDK behavior
+
+### Required Guardrails
+
+1. keep the JS wrapper as the canonical entrypoint
+2. document clearly that the monitor is a Python implementation behind a JS wrapper
+3. do not expand Python usage from this hook into the rest of the platform
+
+### Recommendation
+
+Ignore them until the Python compatibility layer is fully retired. At that point they can disappear with the rest of the Python package surface.
+
+## Recommended Next Wave
+
+If the goal is to reduce Python without destabilizing the repository, the next wave should be:
+
+1. migrate `scripts/team_skills_platform.py`
+2. migrate `scripts/trigger_gitlab_pipeline.py`
+3. retire `scripts/run_e2e_test.py` unless an owner claims it
+4. keep `scripts/hooks/insaits-security-monitor.py` as a documented Python exception behind the JS wrapper
+5. explicitly defer the Python hook/lib compatibility layer until a dedicated cleanup pass
+
+## Non-Goals For The Next Wave
+
+The next wave should **not** try to:
+
+- delete all Python immediately
+- rewrite test imports and hook compatibility at the same time as generator migration
+- migrate one-off `_*.py` utilities without confirming they are still needed
+
+## Decision Table
+
+| File Group | Status | Recommended Action |
+|---|---|---|
+| JS-backed entrypoint shims | acceptable temporary state | keep until callers are cleaned up |
+| Python hook/lib compatibility layer | intentional technical debt | defer to dedicated hook/test cleanup |
+| `team_skills_platform.py` | unresolved core duplication | migrate next |
+| `trigger_gitlab_pipeline.py` | unresolved operational Python | migrate next |
+| `run_e2e_test.py` | no longer justified on main path | retire unless reclaimed |
+| `hooks/insaits-security-monitor.py` | explicit third-party exception | keep behind JS wrapper |
+| `_*.py` maintenance scripts | likely dead weight | retire/delete unless owned |
+
+## Suggested Acceptance Criteria For “Python Mostly Cleared”
+
+We should only claim the repository is effectively JS-first when:
+
+1. all active operational scripts use JS as the primary implementation
+2. the only remaining Python files are either:
+   - compatibility shims, or
+   - explicitly documented exceptions
+3. every remaining Python file has an owner and a stated reason to exist