@colin4k1024/tsp 2.4.1 → 2.4.2

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

package/docs/plans/2026-04-03-scripts-python-to-js-migration.md

@@ -0,0 +1,372 @@
+# Scripts Python-to-JS Migration Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Migrate the Team Skills Platform's core `scripts/` execution path from Python to JavaScript so that build, generation, and validation workflows run natively in the repository's existing Node.js toolchain.
+
+**Architecture:** Replace the current Python-centered platform pipeline with a JS-first pipeline in layers. First migrate shared runtime utilities, then the artifact generator, then the validation chain, while keeping generated output and workflow-gate behavior equivalent to the current implementation.
+
+**Tech Stack:** Node.js 18+, existing `package.json` scripts, repository markdown/templates/roles/commands, filesystem-based code generation, audit logging, validation fixtures.
+
+---
+
+## 1. Background
+
+The repository already uses Node.js as its primary package/tooling surface, but the platform core still depends on Python for:
+
+- artifact generation
+- library validation
+- workflow-gate validation
+- local audit logging
+
+This creates three problems:
+
+1. The build and validation path is split across two runtimes.
+2. The platform's most critical governance logic now lives in Python, while the surrounding repo tooling is JS-first.
+3. Every future platform change risks duplicating utility logic across Python and JS.
+
+This migration formalizes a JS-first platform core.
+
+## 2. Migration Scope
+
+### 2.1 In Scope
+
+This migration covers the core platform path only:
+
+- [scripts/lib/team-skills-platform.js](../../scripts/lib/team-skills-platform.js)
+- [scripts/build-platform-artifacts.js](../../scripts/build-platform-artifacts.js)
+- [scripts/validate-library.js](../../scripts/validate-library.js)
+- [scripts/validate-workflow-state.js](../../scripts/validate-workflow-state.js)
+- [scripts/lib/audit-logger.js](../../scripts/lib/audit-logger.js)
+
+### 2.2 Out of Scope
+
+These Python scripts are not part of the first migration wave:
+
+- [scripts/install-platform.js](../../scripts/install-platform.js)
+- [scripts/query-audit-logs.js](../../scripts/query-audit-logs.js)
+- [scripts/scan-leaked-keys.js](../../scripts/scan-leaked-keys.js)
+- [scripts/langfuse-trace.js](../../scripts/langfuse-trace.js)
+- [scripts/trigger-gitlab-pipeline.js](../../scripts/trigger-gitlab-pipeline.js)
+- `scripts/run-e2e-test.js` (已废弃，无 JS 等价物)
+
+These can be migrated later after the platform core is stable.
+
+## 3. Target End State
+
+After this migration:
+
+- `npm run build` uses JS only
+- `npm run validate` uses JS only
+- core platform generation no longer depends on Python
+- workflow-gate validation no longer depends on Python
+- generated artifacts remain equivalent to the current implementation
+- Python entrypoints for the migrated path can be removed or retained only as thin compatibility shims during transition
+
+## 4. Success Criteria
+
+The migration is complete only when all of the following are true:
+
+1. A JS artifact generator can compute and write all expected generated files.
+2. A JS validation entrypoint can replace the current Python validation path.
+3. Workflow-state validation behaves the same as the current fixture-based Python validator.
+4. `package.json` no longer routes core build/validate through Python.
+5. Repository docs no longer instruct users to run Python for the migrated scripts.
+6. Generated output diff is either identical or intentionally reviewed and accepted.
+
+## 5. Proposed File Layout
+
+Recommended JS replacements:
+
+- `scripts/lib/audit-logger.js`
+- `scripts/lib/team-skills-platform.js`
+- `scripts/build-platform-artifacts.js`
+- `scripts/validate-library.js`
+- `scripts/validate-workflow-state.js`
+
+Optional compatibility wrappers during transition:
+
+- keep Python files temporarily, but reduce them to delegating wrappers
+- or update shell/PowerShell wrappers directly to JS and retire Python immediately
+
+## 6. Execution Strategy
+
+Use an incremental migration instead of a big-bang rewrite.
+
+### Phase 1: Shared Utility Layer
+
+Build the common JS foundation first.
+
+Deliverables:
+
+- JS audit logger with writable-root fallback behavior
+- reusable file IO helpers
+- reusable frontmatter parsing helpers
+- reusable markdown/link/path validation helpers
+
+Primary outputs:
+
+- `scripts/lib/audit-logger.js`
+- utility helpers colocated under `scripts/lib/`
+
+Acceptance:
+
+- audit events can be emitted from JS scripts
+- local fallback behavior matches the current Python behavior
+
+### Phase 2: Core Generator Migration
+
+Migrate the platform generator logic from Python into JS.
+
+Deliverables:
+
+- JS implementation of role loading
+- JS rendering of generated role prompts
+- JS rendering of generated commands
+- JS expected-artifacts computation
+- JS write/check mode equivalent to the current generator
+
+Primary outputs:
+
+- `scripts/lib/team-skills-platform.js`
+- `scripts/build-platform-artifacts.js`
+
+Acceptance:
+
+- generated artifact check passes
+- regenerated output matches current expected output
+
+### Phase 3: Workflow Validator Migration
+
+Migrate workflow-state validation into JS without changing behavior.
+
+Deliverables:
+
+- JS validation for:
+  - required artifact presence
+  - delivery-plan gate markers
+  - arch-design presence when applicable
+  - handoff readiness fields
+  - legal phase transition rules
+
+Primary outputs:
+
+- `scripts/validate-workflow-state.js`
+
+Acceptance:
+
+- current valid fixture passes
+- current invalid fixtures fail with clear errors
+
+### Phase 4: Library Validator Migration
+
+Migrate the repo-wide library validator to JS and wire in the workflow validator.
+
+Deliverables:
+
+- required file checks
+- generated artifact consistency checks
+- skill catalog checks
+- markdown link checks
+- workflow fixture checks
+
+Primary outputs:
+
+- `scripts/validate-library.js`
+
+Acceptance:
+
+- the JS validator covers the same effective validation surface as the Python path for migrated components
+
+### Phase 5: Entry Point and Documentation Cutover
+
+Switch repository entrypoints and docs to JS.
+
+Deliverables:
+
+- update [package.json](../../package.json)
+- update:
+  - [scripts/build-platform-artifacts.sh](../../scripts/build-platform-artifacts.sh)
+  - [scripts/build-platform-artifacts.ps1](../../scripts/build-platform-artifacts.ps1)
+  - [scripts/validate-library.sh](../../scripts/validate-library.sh)
+  - [scripts/validate-library.ps1](../../scripts/validate-library.ps1)
+- update all operational docs that still instruct Python use for the migrated scripts
+
+Acceptance:
+
+- build and validate commands shown to users are JS-native
+
+### Phase 6: Python Retirement
+
+Once the JS path is stable:
+
+- remove migrated Python implementations
+- or keep only temporary compatibility stubs with a clear removal deadline
+
+Acceptance:
+
+- there is a single authoritative implementation for core platform generation/validation
+
+## 7. Recommended Task Breakdown
+
+### Workstream A: Generator Path
+
+Files:
+
+- `scripts/lib/team-skills-platform.js`
+- `scripts/build-platform-artifacts.js`
+- `scripts/lib/audit-logger.js`
+
+JS targets:
+
+- `scripts/lib/team-skills-platform.js`
+- `scripts/build-platform-artifacts.js`
+- `scripts/lib/audit-logger.js`
+
+Why first:
+
+- highest leverage
+- unblocks JS-native generation
+- reduces future platform change cost the most
+
+### Workstream B: Validation Path
+
+Files:
+
+- `scripts/validate-workflow-state.js`
+- `scripts/validate-library.js`
+
+JS targets:
+
+- `scripts/validate-workflow-state.js`
+- `scripts/validate-library.js`
+
+Why second:
+
+- depends on generator outputs
+- easier to validate after generation parity exists
+
+### Workstream C: Entry Point Cutover
+
+Files:
+
+- `package.json`
+- shell wrappers
+- PowerShell wrappers
+- docs references
+
+Why third:
+
+- should happen only after JS scripts are already stable
+
+## 8. Risks and Controls
+
+### Risk 1: Output drift during generator migration
+
+Problem:
+- generated markdown/manifests may change subtly
+
+Mitigation:
+- keep snapshot/equivalence checks
+- compare expected outputs before cutover
+- treat any output delta as reviewable, not accidental
+
+### Risk 2: Validation parity gaps
+
+Problem:
+- JS validator may miss checks the Python version had
+
+Mitigation:
+- port by category, not file-by-file intuition
+- keep fixture-based tests
+- verify each validation concern explicitly
+
+### Risk 3: Mixed-runtime confusion during transition
+
+Problem:
+- contributors may keep using Python commands while JS becomes canonical
+
+Mitigation:
+- switch `package.json` early once stable
+- update AGENTS/README/runbooks in the same cutover
+- optionally leave deprecation shims with explicit warnings
+
+### Risk 4: Regressions in workflow-gate enforcement
+
+Problem:
+- new gate logic was just introduced and must not be weakened
+
+Mitigation:
+- treat workflow fixtures as blocking regression tests
+- do not rewrite gate semantics during migration
+- migrate behavior first, refactor second
+
+## 9. Testing and Verification Plan
+
+The migration must include these checks:
+
+1. Generator parity check
+2. Workflow fixture validation
+3. Library validation check
+4. Targeted unit tests for parser/renderer helpers
+5. Manual spot-check of generated:
+- role prompts
+- team commands
+- plugin manifests
+
+Suggested verification commands after JS cutover:
+
+```bash
+npm run build
+npm run validate
+npm test
+```
+
+## 10. Rollout Recommendation
+
+Do this as two PRs or two tightly scoped implementation waves.
+
+### Recommended Wave 1
+
+Migrate:
+
+- audit logger
+- team skills generator core
+- build entrypoint
+
+Reason:
+- smallest high-value slice
+- immediately removes Python from the generation path
+
+### Recommended Wave 2
+
+Migrate:
+
+- workflow validator
+- library validator
+- package/documentation cutover
+
+Reason:
+- depends on wave 1 parity
+- lets validation migration build on the stable JS generator
+
+## 11. Final Recommendation
+
+The best first implementation slice is:
+
+1. migrate [team-skills-platform.js](../../scripts/lib/team-skills-platform.js)
+2. migrate [build-platform-artifacts.js](../../scripts/build-platform-artifacts.js)
+3. migrate [audit-logger.js](../../scripts/lib/audit-logger.js)
+
+This gives the repository a JS-native generation core with the least coordination risk. After that, migrate the validators and switch the user-facing commands.
+
+## 12. Deliverable Checklist
+
+- [ ] JS audit logger exists and is wired into JS entrypoints
+- [ ] JS generator exists and produces equivalent outputs
+- [ ] JS build entrypoint replaces Python build entrypoint
+- [ ] JS workflow validator exists and passes current fixtures
+- [ ] JS library validator exists and replaces Python validate entrypoint
+- [ ] `package.json` scripts are JS-native for build/validate
+- [ ] Docs no longer direct users to Python for migrated scripts
+- [ ] Deprecated Python entrypoints are removed or explicitly marked temporary