@colin4k1024/tsp 2.4.5 → 2.4.6

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

@@ -1,265 +0,0 @@
-# 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

@@ -1,372 +0,0 @@
-# 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