@ibotor/smart-trellis 0.5.22 → 0.5.24

package/dist/templates/common/bundled-skills/trellis-quality-review/references/safe-refactor-boundaries.md

@@ -0,0 +1,158 @@
+# Safe Refactor Boundaries
+
+Use this reference before splitting components, extracting composables/hooks, moving helpers, or changing ownership. The goal is to reduce responsibility pile-up without creating abstraction churn or expanding beyond the current diff.
+
+## Core Rule
+
+Refactor only when it improves the current requirement's clarity, correctness, or maintainability inside the review boundary. File size alone is not enough.
+
+A safe refactor has all of these properties:
+
+- The problematic responsibility is touched by the current diff.
+- The target boundary is obvious and nameable.
+- The extracted interface is smaller than the code it hides.
+- The move does not require unrelated callers, routes, stores, styles, or tests to change.
+- Behavior, copy, layout, and public contracts remain unchanged unless required.
+- Verification can cover the moved logic or affected render path.
+
+## Strong Signals to Split or Extract
+
+Consider a targeted split when at least one is true:
+
+- A page/container now owns orchestration plus multiple changed UI sections.
+- A component now mixes rendering with request orchestration, validation, mapping, and modal/table/form state touched by this requirement.
+- The current diff duplicates non-trivial logic in two or more places.
+- Newly added side effects make the render component hard to follow.
+- Newly added pure mapping/formatting/validation logic obscures the UI path.
+- A modal/drawer/wizard section has its own state, validation, and actions that can be named independently.
+- A hook/composable would isolate stateful behavior used by the current feature without becoming a generic utility.
+
+## Strong Signals Not to Refactor
+
+Avoid structural refactor when any is true:
+
+- The file is merely large, but the current change touches a small localized area.
+- The split would require moving unrelated markup, styles, tests, or callers.
+- The extracted function/component would have many props or return values just to keep behavior working.
+- The new abstraction would be used once and does not hide meaningful complexity.
+- Naming the boundary requires vague words like `Common`, `Base`, `Manager`, `Handler`, or `Utils`.
+- The refactor would change user-visible copy, layout, option order, focus behavior, or event timing.
+- The user requested a micro-change or explicitly asked to avoid broad cleanup.
+
+## Boundary Heuristics
+
+### Page / Route / Container
+
+Should own:
+
+- route params and navigation glue
+- top-level data loading orchestration
+- composition of feature sections
+- passing typed props and event handlers to children
+
+Should not accumulate:
+
+- multiple independent UI sections with detailed markup
+- modal internals
+- table cell formatting details
+- form field validation internals
+- low-level API payload mapping when it obscures orchestration
+
+### Component
+
+Should own:
+
+- one nameable UI section
+- local UI state for that section
+- typed props/events or callbacks
+- minimal formatting needed for display
+
+Extract when the component contains multiple independently nameable regions touched by this requirement, such as search form + table + edit modal + upload drawer.
+
+Do not extract when the child would only wrap a few lines and add prop plumbing without hiding complexity.
+
+### Composable / Hook
+
+Should own:
+
+- stateful logic and side effects
+- async request lifecycle
+- derived state tied to the feature
+- event handlers whose behavior is not just presentational
+
+Good candidates:
+
+- `useUserTableData`
+- `useDomainForm`
+- `useUploadDialog`
+
+Weak candidates:
+
+- `useHelpers`
+- `useCommon`
+- `usePageLogic`
+- a hook returning 15 unrelated values
+
+### Helper
+
+Should own pure logic:
+
+- formatters
+- mappers
+- validators
+- sort/filter predicates
+- small calculations
+
+Keep helpers local when used only by one component/composable. Move to a separate file only when the helper is non-trivial, reused by current-work code, or makes the owning file materially clearer.
+
+### Types
+
+Keep feature-local types near the owning component/composable when they are not reused.
+
+Move types to shared files only when:
+
+- multiple current-work files consume them
+- they represent API or route/store boundaries
+- colocating them would create import cycles or unclear ownership
+
+## Vue-Specific Guidance
+
+- Prefer `<script setup>` and typed props/emits when the project uses that style.
+- Keep section-local refs in the section component unless parent orchestration needs them.
+- Extract a composable when state transitions, async effects, watchers, or derived state dominate the component.
+- Avoid Pinia for one-off UI state; use Pinia when state is shared across routes/features or must outlive the component.
+- Avoid composables that return large bags of unrelated refs; split by feature behavior instead.
+
+## React / Next-Specific Guidance
+
+- Keep route/page components focused on orchestration and server/client boundary correctness.
+- Do not add `use client` broadly just to support a small interactive child; prefer isolating the client component when feasible and in scope.
+- Extract a hook when stateful behavior or side effects obscure the component body.
+- Extract a component when a nameable UI section has its own props and events.
+- Do not add `useMemo`/`useCallback` as a refactor unless identity stability or render cost is a real current-diff concern.
+
+## Safe Refactor Procedure
+
+1. Name the responsibility that is piled up.
+2. Confirm it is touched by the current requirement.
+3. Choose the smallest boundary that hides complexity without leaking many props/returns.
+4. Preserve public behavior, copy, layout, and event timing.
+5. Move only the directly related code.
+6. Re-run the smallest relevant verification from `verification-selection.md`.
+7. If any step requires broad unrelated edits, stop and record the idea as Note Only.
+
+## Reporting
+
+When you refactor, report why the boundary was safe:
+
+```text
+Changed:
+- Extracted EditDomainModal because the current diff added independent modal state, validation, and submit handling; parent now only orchestrates open/close and refresh.
+```
+
+When you do not refactor, report why not when relevant:
+
+```text
+Severity:
+- Should Fix: did not split SettingsPage because the large table section was pre-existing and untouched by this request.
+```

package/dist/templates/common/bundled-skills/trellis-quality-review/references/scope-control.md

@@ -0,0 +1,49 @@
+# Scope Control
+
+Use this gate before any cleanup or refactor. The purpose is to protect the user's requested change from scope creep.
+
+## Default Rule
+
+Change only what the requirement asks for, plus the smallest necessary adjacent code to keep it correct, typed, lint-clean, or buildable.
+
+Do not opportunistically optimize, polish, reorder, refactor, rename, reformat, or clean up code the requirement does not touch.
+
+Preserve existing user-visible text, helper descriptions, option order, placeholders, tooltips, validation messages, comments, and layout unless the requirement explicitly asks to change them or the feature cannot work without the change.
+
+If the user says “do not change anything not mentioned”, treat all non-required UI/text changes as high-risk and list them explicitly in the review.
+
+## Gate Steps
+
+1. Restate the current requirement in one sentence.
+2. Inspect `git status` and `git diff HEAD` before editing.
+3. Classify each changed block:
+   - **In requirement:** directly implements or verifies the requested change.
+   - **Necessary adjacent:** required to keep the requested change correct, typed, lint-clean, or buildable.
+   - **Out of scope:** opportunistic old-code optimization, unrelated formatting, broad refactor, unrelated dead-code cleanup, renamed abstractions, style changes, user-visible copy changes, helper-description changes, or option-order changes not needed by the requirement.
+4. Only edit **In requirement** and **Necessary adjacent** blocks.
+5. For **Out of scope** blocks, do not extend the change.
+6. Revert your own out-of-scope edits when safe.
+7. If an out-of-scope edit predates the session or ownership is unclear, leave it untouched and mention it in Notes.
+8. If classification is unclear and would change more code, ask the user instead of deciding silently.
+
+## Responsibility Map
+
+Use this map to decide whether structure changes are justified:
+
+- **route/page/container:** orchestration, data loading, high-level composition
+- **component:** one UI section with typed props/emits or typed component props/callbacks
+- **composable/hook:** stateful logic, side effects, derived state, lifecycle coordination
+- **helper:** pure feature-local logic
+- **api/types:** external boundary and shared contracts
+
+Split only when the current requirement created unclear ownership or repeated logic. Keep feature-local types/helpers near the owning unit unless reused broadly.
+
+## Common Scope Mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Optimizing old code during requirement review | Record it in Notes unless it blocks the current requirement |
+| Splitting every type/helper into standalone files | Keep local helpers local unless reused |
+| Moving UI state into parent unnecessarily | Keep section-local state near the section |
+| Letting old violations expand scope | Fix only newly introduced violations unless adjacent legacy code blocks correctness |
+| Trusting visual refactor | Preserve behavior and verify with commands |

package/dist/templates/common/bundled-skills/trellis-quality-review/references/severity.md

@@ -0,0 +1,105 @@
+# Severity
+
+Classify findings before fixing them. Severity applies to the current review boundary: default to `git diff HEAD` unless the user requested staged-only or a specific base ref. Historical or untouched issues are usually Note Only unless they block the current requirement.
+
+## Levels
+
+### Blocker
+
+Must be fixed before handoff. The current diff introduces or exposes a problem that can break build, typecheck, runtime behavior, critical user flow, permissions, data integrity, or security.
+
+Frontend examples:
+
+- current diff causes build, typecheck, or required test failure
+- key page crashes or fails to render
+- form cannot submit, primary action cannot be clicked, or required user flow is broken
+- API payload or response mapping is wrong for the changed feature
+- permission/auth guard is loosened or bypassed
+- Next.js server/client boundary error prevents render or build
+- changed props/types break touched consumers
+- unsanitized user-controlled `dangerouslySetInnerHTML` or equivalent XSS risk
+- production-executed `debugger`
+
+Action: fix in the current review if possible, rerun relevant verification, and report as blocking if not resolved.
+
+### Must Fix Before Handoff
+
+Should be fixed before delivery when introduced by the current diff, even if it does not immediately fail build.
+
+Frontend examples:
+
+- added `console.log`, `debugger`, unexplained `@ts-ignore`, `@ts-expect-error`, or broad `eslint-disable`
+- current-work dead code: unused props, emits, refs, state, imports, branches, mock fields
+- out-of-scope user-visible copy, helper text, placeholder, validation message, or option-order changes
+- out-of-scope formatting churn mixed into the diff
+- current diff introduces obvious duplicated logic that can be removed locally
+- local UI state was lifted or globalized without requirement support
+- newly added loading/error state is never rendered or consumed
+- temporary mock/demo data is scattered in production components
+
+Action: fix when ownership is clear and the fix stays inside the requirement boundary. If ownership is unclear, record in Notes instead of expanding scope.
+
+### Should Fix If In Scope
+
+Real issue, but fix only when it is clearly within the current requirement and the change is small.
+
+Frontend examples:
+
+- unclear name in newly added function, prop, event, or variable
+- newly added condition is hard to read but safe
+- new component is somewhat large but not yet clearly multi-responsibility
+- duplicated new snippet appears twice and a local helper would clarify it
+- type could be narrower, but current type is safe
+- composable/hook return shape is slightly broad but still understandable
+- helper extraction would improve clarity but requires moving files or touching callers
+- tests are not ideal, but selected verification covers the main changed path
+
+Action: fix only if the edit is small and does not expand scope. Otherwise mention as a follow-up Note.
+
+### Note Only
+
+Do not fix during this review. The issue is historical, untouched, unclear ownership, or not needed for the current requirement.
+
+Frontend examples:
+
+- old component is large but this task touched only a tiny unrelated line
+- historical lint/typecheck/test failures
+- old copy inconsistency
+- legacy form validation pattern
+- old API layer or directory structure concerns
+- untouched hook/composable design issue
+- existing `any`, formatter churn, or test gap not introduced by the current diff
+
+Action: record briefly in Notes when useful. Do not mark the current task failed unless it blocks the current requirement.
+
+## Classification Flow
+
+1. **Was it introduced or exposed by the current review diff?**
+   - No: Note Only, unless it blocks the current requirement.
+   - Yes: continue.
+
+2. **Can it break build, typecheck, runtime behavior, critical flow, permissions, data integrity, or security?**
+   - Yes: Blocker.
+   - No: continue.
+
+3. **Is it current-work debug code, unexplained suppression, dead code, out-of-scope copy, or out-of-scope formatting?**
+   - Yes: Must Fix Before Handoff.
+   - No: continue.
+
+4. **Is the fix small, local, and inside the current requirement boundary?**
+   - Yes: Should Fix If In Scope.
+   - No: Note Only.
+
+## Reporting
+
+Keep severity concise. Prefer counts and high-signal examples over long lists.
+
+Example:
+
+```text
+Severity:
+- Blocker: none
+- Must Fix: removed added console.log; restored out-of-scope placeholder change
+- Should Fix: did not split SettingsPanel because it would touch unrelated sections
+- Note Only: pre-existing vue-tsc errors in src/legacy/* are unrelated to touched files
+```

package/dist/templates/common/bundled-skills/trellis-quality-review/references/small-change-fast-path.md

@@ -0,0 +1,51 @@
+# Small-Change Fast Path
+
+Use this path for tiny, low-risk frontend changes where full quality review would create more churn than value.
+
+## Qualifying Changes
+
+A change qualifies only when all are true:
+
+- The user's request is narrow and explicit.
+- The diff is limited to one file or a very small localized area.
+- The change does not affect API shape, routing, permissions, state flow, data transformation, validation behavior, dependency configuration, or shared types.
+- The change is easy to verify by reading the diff.
+- No suspicious added lines appear, such as `console.log`, `debugger`, `@ts-ignore`, `eslint-disable`, `TODO`, or `FIXME`.
+
+Common qualifying examples:
+
+- UI spacing, width, color, or alignment constants
+- single label/copy change explicitly requested by the user
+- table column width/order requested by the user
+- small style/class adjustment
+- single local config flag with no behavior cascade
+
+## Disqualifiers
+
+Do not use the fast path if any are true:
+
+- The change affects component boundaries, composables/hooks, stores, route logic, API calls, form validation, permissions, upload/download behavior, or data mapping.
+- The diff spans multiple modules or shared abstractions.
+- The change introduces or edits TypeScript types used outside the local file.
+- The diff includes unrelated formatting or copy churn.
+- The user asks for a full review, cleanup, refactor, verification, or confidence before handoff.
+- The project currently has failing diagnostics that may be related to the touched code.
+
+## Fast Path Procedure
+
+1. Restate the small requirement in one sentence.
+2. Inspect the relevant diff only.
+3. Confirm the diff contains only the requested localized change.
+4. Do not run broad lint, typecheck, unit tests, or build by default.
+5. If a minimal targeted command is obvious and cheap, run it only when it directly validates the change.
+6. Report that the fast path was used and whether verification was limited to diff inspection.
+
+## Required Final Note
+
+When using this path, include a short note like:
+
+```text
+Used small-change fast path: skipped lint/typecheck/test/build because the diff is a localized UI/copy/config change and diff inspection confirmed scope.
+```
+
+If the diff inspection finds scope expansion, leave the fast path and return to the normal decision tree.

package/dist/templates/common/bundled-skills/trellis-quality-review/references/verification-selection.md

@@ -0,0 +1,81 @@
+# Verification Selection
+
+Use this reference before reporting completion or correctness. The goal is to choose the smallest verification set that gives confidence for the current frontend diff without expanding into unrelated legacy cleanup.
+
+## Core Rule
+
+Verification should match the risk introduced by the current diff:
+
+- Tiny localized UI/copy/style/config changes can use the small-change fast path and diff inspection only.
+- Type, data, state, validation, routing, API, component-boundary, or framework-boundary changes need targeted commands.
+- Full build is reserved for changes that affect bundling, routes/pages, framework config, server/client boundaries, or when lighter checks cannot cover the risk.
+
+Always inspect project scripts and nearby docs/config before inventing commands.
+
+## Command Discovery Order
+
+Prefer project-defined scripts over raw tool invocations:
+
+1. Read `package.json` scripts.
+2. Check project docs or local agent instructions if already relevant to the task.
+3. Check framework config only when needed: `vite.config.*`, `next.config.*`, `tsconfig*.json`, `eslint.config.*`, `.eslintrc*`, `vitest.config.*`, `jest.config.*`, `playwright.config.*`.
+4. Prefer the package manager already used by the project: lockfiles and scripts reveal `pnpm`, `npm`, `yarn`, or `bun`.
+
+Do not add dependencies or modify configs just to run verification.
+
+## Selection Matrix
+
+| Diff signal | Verification default |
+| --- | --- |
+| Small-change fast path | Diff inspection only; no broad lint/typecheck/test/build by default |
+| `.vue` template/script/style changes | Project lint plus Vue/typecheck script when available, such as `vue-tsc` or `typecheck` |
+| Vue props/emits/composable/store changes | Typecheck plus targeted tests if present |
+| React/TSX component changes | Project lint plus TypeScript check when available |
+| Next.js route/page/server-client boundary changes | Lint/typecheck plus build when boundary or route behavior risk is meaningful |
+| Type definitions or shared contracts changed | Typecheck; targeted tests for consumers when present |
+| Form validation, data mapping, formatter, parser, permission logic | Targeted unit tests; typecheck if TypeScript is involved |
+| API call shape or request/response mapping changed | Typecheck plus targeted integration/unit tests if available |
+| Styling-only but not fast-path | Scoped lint/style check if project has one; otherwise diff inspection plus optional visual/manual note |
+| Suspicious added debug/type-suppression lines fixed | Re-run the scan or scoped lint that would catch the issue |
+| Formatter conflict | Prefer scoped lint with formatting rules disabled when preserving scope; report the conflict |
+
+## Running Strategy
+
+1. Start with the narrowest command that covers the changed files or feature.
+2. Prefer targeted tests over full test suites when a clear target exists.
+3. Run full lint/typecheck/build only when the diff risk justifies it or project scripts are fast and standard.
+4. If a command is unavailable, do not invent a replacement blindly; report that no matching script was found.
+5. If the user explicitly asked to skip verification, skip it and report that instruction.
+
+## Failure Handling
+
+When a command fails:
+
+1. Read the output and identify the failing file or test.
+2. Decide whether the failure is related to the current diff.
+3. If related, fix within scope and rerun the relevant command.
+4. If unrelated or historical, do not expand scope; report it under Notes with evidence.
+5. Do not claim verification passed if any required command failed.
+6. If partial verification passed, say exactly which commands passed and which failed.
+
+## Final Report Evidence
+
+In the `Verified` section, include:
+
+- exact command
+- exit status
+- short result summary
+- if skipped, the explicit reason
+
+Examples:
+
+```text
+Verified:
+- `pnpm lint -- src/pages/Settings.vue` exited 0.
+- `pnpm vue-tsc --noEmit` exited 1 due to pre-existing errors in src/legacy/*; no errors referenced the touched files.
+```
+
+```text
+Verified:
+- Used small-change fast path: skipped lint/typecheck/test/build because only one table column width changed and diff inspection confirmed scope.
+```

package/dist/templates/common/bundled-skills/trellis-quality-review/scripts/diff_scans.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mode="base"
+base_ref="HEAD"
+json=0
+files_only=0
+
+usage() {
+  cat <<'EOF'
+Usage: diff_scans.sh [--base REF] [--cached] [--files] [--json]
+
+Modes:
+  --base REF   Scan git diff against REF. Defaults to HEAD.
+  --cached     Scan staged changes.
+  --files      Only print changed frontend files.
+  --json       Print a JSON summary instead of sectioned text.
+  -h, --help   Show this help.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base)
+      mode="base"
+      base_ref="${2:?--base requires a ref}"
+      shift 2
+      ;;
+    --cached|--staged)
+      mode="cached"
+      shift
+      ;;
+    --files)
+      files_only=1
+      shift
+      ;;
+    --json)
+      json=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      mode="base"
+      base_ref="$1"
+      shift
+      ;;
+  esac
+done
+
+frontend_globs=(-- '*.vue' '*.ts' '*.tsx' '*.jsx' '*.js' '*.css' '*.scss')
+code_globs=(-- '*.vue' '*.ts' '*.tsx' '*.jsx' '*.js')
+
+git_diff() {
+  if [[ "$mode" == "cached" ]]; then
+    git diff --cached "$@"
+  else
+    git diff "$base_ref" "$@"
+  fi
+}
+
+diff_label() {
+  if [[ "$mode" == "cached" ]]; then
+    echo "--cached"
+  else
+    echo "$base_ref"
+  fi
+}
+
+json_array() {
+  python3 -c 'import json,sys; print(json.dumps(sys.stdin.read().splitlines()))'
+}
+
+json_string() {
+  python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'
+}
+
+changed_files() {
+  git_diff --name-only --diff-filter=ACMRTUXB "${frontend_globs[@]}" || true
+}
+
+scan() {
+  local title="$1"
+  local pattern="$2"
+  shift 2
+  echo
+  echo "== $title =="
+  git_diff -U0 "$@" | rg "$pattern" || true
+}
+
+if [[ "$files_only" -eq 1 && "$json" -eq 0 ]]; then
+  changed_files
+  exit 0
+fi
+
+if [[ "$json" -eq 1 ]]; then
+  files="$(changed_files)"
+  suspicious="$(git_diff -U0 "${code_globs[@]}" | rg '^\+[^+].*(eslint-disable|@ts-ignore|@ts-expect-error|console\.log|debugger|TODO|FIXME)' || true)"
+  ts_risks="$(git_diff -U0 "${code_globs[@]}" | rg '^\+[^+].*(:\s*any\b|as\s+any\b|as\s+unknown\s+as|!\.|\w!\b)' || true)"
+  vue_risks="$(git_diff -U0 -- '*.vue' | rg '^\+[^+].*(v-model:|watch\s*\([^\n]*deep\s*:\s*true|defineProps\([^\n]*\)\.[A-Za-z_$][\w$]*\s*=)' || true)"
+  react_next_risks="$(git_diff -U0 "${code_globs[@]}" | rg '^\+[^+].*(use client|dangerouslySetInnerHTML|window\.|document\.|localStorage\.|sessionStorage\.)' || true)"
+  copy_changes="$(git_diff -U0 "${code_globs[@]}" | rg '^[+-][^+-].*(label|title|placeholder|help|message|Radio|Checkbox|Button|Tooltip|content|confirmText|cancelText|text-|aria-label|alt=|请选择|请输入|验证|账户|服务商|域名|说明|提示)' || true)"
+
+  printf '{\n'
+  printf '  "mode": %s,\n' "$(printf '%s' "$(diff_label)" | json_string)"
+  printf '  "changed_files": %s,\n' "$(printf '%s' "$files" | json_array)"
+  printf '  "suspicious_patterns": %s,\n' "$(printf '%s' "$suspicious" | json_array)"
+  printf '  "typescript_risks": %s,\n' "$(printf '%s' "$ts_risks" | json_array)"
+  printf '  "vue_risks": %s,\n' "$(printf '%s' "$vue_risks" | json_array)"
+  printf '  "react_next_risks": %s,\n' "$(printf '%s' "$react_next_risks" | json_array)"
+  printf '  "potential_copy_changes": %s\n' "$(printf '%s' "$copy_changes" | json_array)"
+  printf '}\n'
+  exit 0
+fi
+
+label="$(diff_label)"
+
+echo "== Diff scan mode =="
+echo "$label"
+
+echo
+echo "== Changed frontend files =="
+changed_files
+
+scan "Added-line suspicious patterns" '^\+[^+].*(eslint-disable|@ts-ignore|@ts-expect-error|console\.log|debugger|TODO|FIXME)' "${code_globs[@]}"
+
+scan "TypeScript risk patterns on added lines" '^\+[^+].*(:\s*any\b|as\s+any\b|as\s+unknown\s+as|!\.|\w!\b)' "${code_globs[@]}"
+
+scan "Vue risk patterns on added lines" '^\+[^+].*(v-model:|watch\s*\([^\n]*deep\s*:\s*true|defineProps\([^\n]*\)\.[A-Za-z_$][\w$]*\s*=)' -- '*.vue'
+
+scan "React/Next/browser-boundary risk patterns on added lines" '^\+[^+].*(use client|dangerouslySetInnerHTML|window\.|document\.|localStorage\.|sessionStorage\.)' "${code_globs[@]}"
+
+scan "Potential copy/accessibility text changes" '^[+-][^+-].*(label|title|placeholder|help|message|Radio|Checkbox|Button|Tooltip|content|confirmText|cancelText|text-|aria-label|alt=|请选择|请输入|验证|账户|服务商|域名|说明|提示)' "${code_globs[@]}"
+
+echo
+echo "== Formatting check hint =="
+echo "For each modified existing file, compare:"
+echo "  git diff $label -- path/to/file"
+if [[ "$mode" == "cached" ]]; then
+  echo "  git diff --cached -w -- path/to/file"
+else
+  echo "  git diff -w $base_ref -- path/to/file"
+fi