jhste-skills 0.1.3 → 0.2.0

package/README.ja.md

@@ -4,7 +4,17 @@ Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.
 
 AI コーディングエージェントが、あなたの定義したエンジニアリング基準を一貫して守るための、インストール可能な作業ルールキットです。
 
-`jhste-skills` は Codex、Claude Code などの AI コーディングエージェントに、共通のエンジニアリング作業フローを提供します。コードを変更する前に前提を検証し、リポジトリ内の既存指示を優先し、API/database/automation の境界を明確に保ち、各モジュールが SRP（Single Responsibility Principle、単一責任原則）に沿って 1 つの明確な責任を持つかを確認し、changed-file guard を実行し、完了を宣言する前に red-team code review を行うよう支援します。
+`jhste-skills` は Codex、Claude Code などの AI コーディングエージェントに、共通のエンジニアリング作業フローを提供します。コードを変更する前に前提を検証し、リポジトリ内の既存指示を優先し、API/database/automation の境界を明確に保ち、SOLID-informed coding discipline と design review lens を適用し、changed-file guard を実行し、完了を宣言する前に red-team code review を行うよう支援します。guard finding は自動的な SOLID 証明ではなく review candidate です。
+
+## ここでの SOLID の意味
+
+ここでの SOLID は、自動 compliance チェックリストではなく、設計レビューのレンズです。
+
+- **S — Single Responsibility:** 変更された function、module、class は、1 つの主な役割と 1 つの主な変更理由を持つべきです。
+- **O — Open/Closed:** 新しい variant、provider、policy を追加するたびに core branching を何度も編集するなら、実際の extension seam が必要かを確認します。
+- **L — Liskov Substitution:** 実装は return shape、nullability、error、side effect、文書化された behavior に関する caller の期待を弱めてはいけません。
+- **I — Interface Segregation:** caller が小さく安定した一部だけを必要とするのに、大きな config、interface、props object に依存しないようにします。
+- **D — Dependency Inversion:** high-level policy が DB、API、browser、filesystem、email、payment、queue などの concrete side effect に強く結びつかないようにし、必要な場合は意図的で見える seam にします。
 
 このツールはプロジェクトを乗っ取りません。リポジトリ内の `AGENTS.md`、`CLAUDE.md`、docs が常に権威です。デフォルト設定は advisory モードで、marker-managed 方式で管理され、低リスクで試せるように設計されています。
 
@@ -16,7 +26,7 @@ AI コーディングエージェントは高速ですが、失敗パターン
 
 - 不明確な要求や誤った前提を黙って受け入れます。
 - 役に立とうとして作業範囲を広げすぎます。
-- UI、route/controller、service、database、side effect の責任を 1 か所に混ぜ込み、「1 モジュール、1 責任」の原則（SRP）を壊します。
+- UI、route/controller、service、database、side effect の責任を 1 か所に混ぜ込んだり、実際の seam がない抽象化を SOLID 名目で追加したりします。
 - 失敗を隠したり、安全でないログを出したりします。
 - 変更コードを十分確認する前に「完了」と言います。
 - マシンやリポジトリを切り替えるたびに、リポジトリ固有のルールを忘れます。
@@ -25,7 +35,7 @@ AI コーディングエージェントは高速ですが、失敗パターン
 
 ```text
 non-trivial code change の前:
-  goal、premise、ownership seam、data contract、failure path、SRP responsibility を確認
+  goal、premise、ownership seam、data contract、failure path、SOLID-informed review lens を確認
 
 編集中:
   repo-local instructions を権威として扱う
@@ -40,7 +50,7 @@ warning が出た場合:
   bounded fix を試し、再確認し、無限ループせず停止する
 ```
 
-期待される結果は、より小さな diff、より明確な SRP 境界、より安全な API/database コード、より少ない silent assumption、より誠実な完了報告です。
+期待される結果は、より小さな diff、より明確な SOLID-informed seam、より安全な API/database コード、より少ない silent assumption、より誠実な完了報告です。
 
 ## 誰がインストールすべきか？
 
@@ -50,7 +60,7 @@ warning が出た場合:
 - non-trivial code change の前に、エージェントに前提を検証してほしい。
 - 既存の repo docs を引き続き権威として扱いたい。
 - commit 前、または完了宣言前に軽量な advisory check を置きたい。
-- SRP、API/database boundary、safe logging、input validation、side effect、automation reliability を重視している。
+- SOLID-informed coding discipline、API/database boundary、safe logging、input validation、side effect、automation reliability を重視している。
 - マシンやリポジトリを移っても、同じ AI 作業習慣を素早く復元したい。
 
 逆に、単一の prompt ファイルだけが欲しい場合、インストール直後から strict CI enforcement を期待する場合、`.jhste/` ファイルや bridge block を生成したくない場合、このツールに自動リファクタリングを期待している場合は、適さないかもしれません。
@@ -147,7 +157,7 @@ Custom   - 効果ベースの質問でセットアップ範囲を選択
 | [`setup`](skills/setup/SKILL.md)<br>install/connect/update が既存プロジェクト指示を上書きしないようにする安全セットアップ skill | kit をインストール、またはリポジトリに接続するとき | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
 | [`jhste-engineering-judgment`](skills/jhste-engineering-judgment/SKILL.md)<br>コード変更前に goal、premise、scope、seam、failure path を検証する pre-change 判断 skill | non-trivial code change の前 | Blind agreement, scope creep, unverified assumption, unclear seam |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>input validation、observable failure handling、secret-safe logging を確認するコード品質 skill | application code の作成またはレビュー時 | Unvalidated input, silent failure, secret logging, oversized file |
-| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>module boundary、side-effect placement、SRP 違反の可能性を確認する architecture review skill | module boundary や app structure を変更するとき | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>module boundary、side-effect placement、SOLID-informed design risk を確認する architecture review skill | module boundary や app structure を変更するとき | Pass-through abstraction, mixed responsibility, side-effect leakage |
 | [`jhste-db-api-boundary`](skills/jhste-db-api-boundary/SKILL.md)<br>API route、service、repository、SQL 間の責任と data contract を確認する boundary skill | API、controller、service、repository、SQL、persistence code を触るとき | Fat route, unsafe SQL, missing auth/data scoping, leaky DTO |
 | [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>crawler/scraper/worker/scheduler の producer-consumer seam と side effect を確認する automation skill | crawler、scraper、worker、scheduler、browser automation を触るとき | Fragile automation, unclear producer/consumer boundary, hidden side effect |
 | [`jhste-red-team-review`](skills/jhste-red-team-review/SKILL.md)<br>完了前に変更コードを攻撃的に再確認する read-only red-team code review skill | non-trivial code work の完了宣言前 | Premature “done”, missed null/auth/env/write/API/performance risk |
@@ -210,7 +220,7 @@ jhste-skills uninstall
 2. 最初は advisory hook を維持します。commit-time check が不要なら `--skip-hooks` を使い、blocking mode は noise と false positive を十分確認してから有効にします。
 3. まずデフォルトの 300-line advisory limit を使います。チームが warning-level hook enforcement を受け入れられるようになってから `--line-limit-mode blocking` を使います。
 4. コード変更中は `guard --scope changed --format text --fail-on error` を手動で実行します。
-5. non-trivial code change の前に、`jhste-engineering-judgment` で scope、seam、failure path、data contract、assumption、各 changed class/module/function の main responsibility を確認します。
+5. non-trivial code change の前に、`jhste-engineering-judgment` で scope、seam、failure path、data contract、assumption、changed class/module/function の SOLID-informed review lens を確認します。
 6. non-trivial code work の完了宣言前に `jhste-red-team-review` を使います。docs-only、comment-only、formatting-only、trivial rename-only の変更はスキップします。
 7. fix + re-review は最大 2 サイクルまでにし、無限ループせず残りの risk を報告します。
 8. baseline は existing debt をレビューした後にだけ作成します。Baseline は known-issues ledger として扱い、scanner failure を隠すのではなく、ratchet で new debt を防ぐために使います。
@@ -245,7 +255,7 @@ Release acceptance notes は [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.
 - 盲目的に同意しない。
 - local project authority を上書きしない。
 - 変更範囲を小さく保つ。
-- SRP の観点で responsibility boundary に名前を付ける。
+- SOLID-informed coding discipline を使い、responsibility、extension seam、caller contract、interface size、concrete dependency direction を確認する。
 - failure を observable にする。
 - automated guard output を proof ではなく evidence として扱う。
 - non-trivial work を完了と呼ぶ前に red-team code review を行う。

package/README.ko.md

@@ -4,7 +4,17 @@ Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.
 
 AI 코딩 에이전트가 설정한 코딩 기준을 일관되게 따르도록 만드는 설치형 작업 규칙 세트입니다.
 
-`jhste-skills`는 Codex, Claude Code 같은 AI 코딩 에이전트에게 공통된 엔지니어링 작업 루프를 제공합니다. 코드를 바꾸기 전에 전제를 확인하고, 레포의 기존 지침을 우선시하고, API/database/automation 경계를 지키고, 한 모듈이 하나의 명확한 책임을 갖는지 확인하는 SRP(Single Responsibility Principle) 관점으로 변경 책임을 점검하고, 변경 파일 guard를 실행하고, 완료를 선언하기 전에 red-team code review를 거치도록 돕습니다.
+`jhste-skills`는 Codex, Claude Code 같은 AI 코딩 에이전트에게 공통된 엔지니어링 작업 루프를 제공합니다. 코드를 바꾸기 전에 전제를 확인하고, 레포의 기존 지침을 우선시하고, API/database/automation 경계를 지키고, SOLID-informed coding discipline과 design review lens를 적용하고, 변경 파일 guard를 실행하고, 완료를 선언하기 전에 red-team code review를 거치도록 돕습니다. guard finding은 자동 SOLID 증명이 아니라 review candidate입니다.
+
+## 여기서 SOLID가 의미하는 것
+
+여기서 SOLID는 자동 준수 체크리스트가 아니라 설계 리뷰 렌즈입니다.
+
+- **S — Single Responsibility:** 변경된 함수, 모듈, 클래스는 하나의 주 역할과 하나의 주 변경 이유를 가져야 합니다.
+- **O — Open/Closed:** 새 variant, provider, policy를 추가할 때 핵심 분기문을 계속 고쳐야 한다면 실제 extension seam이 필요한지 검토합니다.
+- **L — Liskov Substitution:** 구현체는 반환 형태, null 가능성, 에러, side effect, 문서화된 동작에 대한 caller 기대를 약화시키면 안 됩니다.
+- **I — Interface Segregation:** caller가 작은 안정적 일부만 필요한데 거대한 config, interface, props 객체에 의존하지 않게 합니다.
+- **D — Dependency Inversion:** high-level policy가 DB, API, browser, filesystem, email, payment, queue 같은 구체 side effect에 강하게 묶이지 않도록 하고, 필요한 경우 의도적이고 보이는 seam으로 둡니다.
 
 이 도구는 프로젝트를 장악하지 않습니다. 레포 안의 `AGENTS.md`, `CLAUDE.md`, docs가 항상 우선입니다. 기본 설정은 advisory 모드이며, marker-managed 방식으로 동작하고, 부담 없이 시도할 수 있도록 설계되어 있습니다.
 
@@ -16,7 +26,7 @@ AI 코딩 에이전트는 빠르지만, 반복적으로 비슷한 방식으로
 
 - 불명확한 요구사항이나 틀린 전제를 조용히 받아들입니다.
 - 도와주려다가 작업 범위를 과하게 넓힙니다.
-- UI, route/controller, service, database, side effect 책임을 한곳에 섞어 “한 모듈, 한 책임” 원칙(SRP)을 깨뜨립니다.
+- UI, route/controller, service, database, side effect 책임을 한곳에 섞거나, 실제 seam 없는 추상화를 SOLID 명목으로 추가합니다.
 - 실패를 숨기거나 위험한 로그를 남깁니다.
 - 변경된 코드를 충분히 확인하기 전에 “완료”라고 말합니다.
 - 머신이나 레포를 바꿀 때마다 레포별 규칙을 잊어버립니다.
@@ -25,7 +35,7 @@ AI 코딩 에이전트는 빠르지만, 반복적으로 비슷한 방식으로
 
 ```text
 non-trivial code change 전:
-  목표, 전제, ownership seam, data contract, failure path, SRP 책임 확인
+  목표, 전제, ownership seam, data contract, failure path, SOLID-informed review lens 확인
 
 수정 중:
   repo-local instructions를 권위로 취급
@@ -40,7 +50,7 @@ warning이 나오면:
   bounded fix를 시도하고, 다시 확인한 뒤, 무한 루프에 빠지지 않고 멈춤
 ```
 
-기대하는 결과는 더 작은 diff, 더 명확한 SRP 경계, 더 안전한 API/database 코드, 더 적은 silent assumption, 더 솔직한 완료 보고입니다.
+기대하는 결과는 더 작은 diff, 더 명확한 SOLID-informed seam, 더 안전한 API/database 코드, 더 적은 silent assumption, 더 솔직한 완료 보고입니다.
 
 ## 누가 설치하면 좋나요?
 
@@ -50,7 +60,7 @@ warning이 나오면:
 - non-trivial code change 전에 에이전트가 전제를 확인하길 원합니다.
 - 기존 repo docs가 계속 권위로 남길 원합니다.
 - 커밋 전 또는 완료 선언 전에 가벼운 advisory check를 두고 싶습니다.
-- SRP, API/database boundary, safe logging, input validation, side effect, automation reliability를 중요하게 봅니다.
+- SOLID-informed coding discipline, API/database boundary, safe logging, input validation, side effect, automation reliability를 중요하게 봅니다.
 - 머신과 레포를 옮겨도 같은 AI 작업 습관을 빠르게 복원하고 싶습니다.
 
 반대로, prompt 파일 하나만 원하거나, 설치 즉시 strict CI enforcement를 원하거나, `.jhste/` 파일과 bridge block 생성을 원하지 않거나, 이 도구가 자동으로 코드를 refactor하길 기대한다면 맞지 않을 수 있습니다.
@@ -147,7 +157,7 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 | [`setup`](skills/setup/SKILL.md)<br>설치, 연결, 업데이트가 기존 프로젝트 지침을 덮어쓰지 않도록 하는 안전 설치 스킬 | kit를 설치하거나 레포에 연결할 때 | unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
 | [`jhste-engineering-judgment`](skills/jhste-engineering-judgment/SKILL.md)<br>코드 변경 전 목표, 전제, scope, seam, failure path를 검증하는 pre-change 판단 스킬 | non-trivial code change 전 | blind agreement, scope creep, unverified assumption, unclear seam |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>입력 검증, 관측 가능한 실패 처리, secret-safe logging을 점검하는 코드 품질 스킬 | application code 작성/리뷰 시 | unvalidated input, silent failure, secret logging, oversized file |
-| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>모듈 경계, side effect 위치, SRP 위반 가능성을 검토하는 아키텍처 리뷰 스킬 | module boundary나 app structure 변경 시 | pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>모듈 경계, side effect 위치, SOLID-informed design risk를 검토하는 아키텍처 리뷰 스킬 | module boundary나 app structure 변경 시 | pass-through abstraction, mixed responsibility, side-effect leakage |
 | [`jhste-db-api-boundary`](skills/jhste-db-api-boundary/SKILL.md)<br>API route, service, repository, SQL 사이의 책임 경계와 데이터 계약을 점검하는 boundary 스킬 | API, controller, service, repository, SQL, persistence code를 만질 때 | fat route, unsafe SQL, missing auth/data scoping, leaky DTO |
 | [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>crawler, scraper, worker, scheduler의 producer/consumer seam과 side effect를 점검하는 자동화 스킬 | crawler, scraper, worker, scheduler, browser automation을 만질 때 | fragile automation, unclear producer/consumer boundary, hidden side effect |
 | [`jhste-red-team-review`](skills/jhste-red-team-review/SKILL.md)<br>완료 선언 전 변경 코드를 공격적으로 재검토하는 read-only red-team code review 스킬 | non-trivial code work 완료 선언 전 | premature “done”, 놓치기 쉬운 null/auth/env/write/API/performance risk |
@@ -210,7 +220,7 @@ jhste-skills uninstall
 2. 처음에는 advisory hook을 유지합니다. commit-time check를 원하지 않으면 `--skip-hooks`를 사용하고, blocking mode는 noise와 false positive를 충분히 확인한 뒤 켭니다.
 3. 기본 300-line advisory limit을 먼저 사용합니다. warning-level hook enforcement를 팀이 받아들일 준비가 되었을 때만 `--line-limit-mode blocking`을 사용합니다.
 4. 코드 변경 중에는 `guard --scope changed --format text --fail-on error`를 수동으로 실행합니다.
-5. non-trivial code change 전에는 `jhste-engineering-judgment`로 scope, seam, failure path, data contract, assumption, 각 changed class/module/function의 main responsibility를 확인합니다.
+5. non-trivial code change 전에는 `jhste-engineering-judgment`로 scope, seam, failure path, data contract, assumption, changed class/module/function의 SOLID-informed review lens를 확인합니다.
 6. non-trivial code work 완료 선언 전에는 `jhste-red-team-review`를 사용합니다. docs-only, comment-only, formatting-only, trivial rename-only 변경은 건너뜁니다.
 7. fix + re-review는 최대 두 번까지만 반복하고, 무한 review loop 대신 남은 risk를 보고합니다.
 8. 기존 debt를 검토한 뒤에만 baseline을 생성합니다. Baseline은 known-issues ledger로 취급하고, scanner failure를 숨기는 용도가 아니라 new debt를 막는 ratchet 용도로 사용합니다.
@@ -245,7 +255,7 @@ Release acceptance notes는 [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.m
 - 무조건 동의하지 않습니다.
 - local project authority를 덮어쓰지 않습니다.
 - 변경 범위를 작게 유지합니다.
-- SRP 관점에서 responsibility boundary를 이름 붙입니다.
+- SOLID-informed coding discipline을 사용해 responsibility를 이름 붙이고, extension seam, caller contract, interface 크기, concrete dependency 방향을 검토합니다.
 - failure를 observable하게 만듭니다.
 - automated guard output을 proof가 아니라 evidence로 취급합니다.
 - non-trivial work를 완료라고 말하기 전에 red-team code review를 수행합니다.

package/README.md

@@ -4,7 +4,17 @@ Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.
 
 An installable working-rules kit that helps AI coding agents consistently follow your engineering standards.
 
-`jhste-skills` gives Codex, Claude Code, and other AI coding agents a shared engineering workflow. It helps agents verify assumptions before editing, respect repo-local instructions, keep API/database/automation boundaries clear, check whether each module has one clear responsibility under SRP (Single Responsibility Principle), run changed-file guards, and perform a red-team code review before claiming work is complete.
+`jhste-skills` gives Codex, Claude Code, and other AI coding agents a shared engineering workflow. It helps agents verify assumptions before editing, respect repo-local instructions, keep API/database/automation boundaries clear, apply SOLID-informed coding discipline and design review, run changed-file guards, and perform a red-team code review before claiming work is complete. Guard findings are review candidates, not automatic SOLID proof.
+
+## What SOLID means here
+
+SOLID is used here as a design review lens, not as an automatic compliance checklist.
+
+- **S — Single Responsibility:** each changed function, module, or class should have one main job and one main reason to change.
+- **O — Open/Closed:** adding a new variant, provider, or policy should not force repeated edits to core branching when a real extension seam would be safer.
+- **L — Liskov Substitution:** implementations should not weaken caller expectations for return shape, nullability, errors, side effects, or documented behavior.
+- **I — Interface Segregation:** callers should not depend on broad config, interface, or props objects when they only need a small, stable slice.
+- **D — Dependency Inversion:** high-level policy should not be tightly coupled to concrete DB, API, browser, filesystem, email, payment, or queue effects unless that seam is intentional and visible.
 
 This tool does **not** take over your project. Repo-local `AGENTS.md`, `CLAUDE.md`, and docs remain authoritative. The default setup is advisory, marker-managed, and designed to be low-risk to try.
 
@@ -16,7 +26,7 @@ AI coding agents are fast, but they fail in predictable ways:
 
 - They silently accept unclear requirements or incorrect premises.
 - They expand the scope while trying to be helpful.
-- They mix UI, route/controller, service, database, and side-effect responsibilities in one place, breaking the “one module, one responsibility” principle (SRP).
+- They mix UI, route/controller, service, database, and side-effect responsibilities in one place, or add abstractions without a real SOLID-informed seam.
 - They hide failures or produce unsafe logs.
 - They say “done” before the changed code has been checked.
 - They forget repo-specific rules when you switch machines or repositories.
@@ -25,7 +35,7 @@ AI coding agents are fast, but they fail in predictable ways:
 
 ```text
 Before a non-trivial code change:
-  check the goal, premise, ownership seam, data contract, failure path, and SRP responsibility
+  check the goal, premise, ownership seam, data contract, failure path, and SOLID-informed review lens
 
 While editing:
   treat repo-local instructions as the authority
@@ -40,7 +50,7 @@ If warnings appear:
   attempt a bounded fix, re-check, and stop instead of looping forever
 ```
 
-The expected result is smaller diffs, clearer SRP boundaries, safer API/database code, fewer silent assumptions, and more honest completion reports.
+The expected result is smaller diffs, clearer SOLID-informed seams, safer API/database code, fewer silent assumptions, and more honest completion reports.
 
 ## Who should install this?
 
@@ -50,7 +60,7 @@ Install `jhste-skills` if you:
 - want agents to verify assumptions before non-trivial code changes;
 - want existing repo docs to remain the source of authority;
 - want lightweight advisory checks before commit or before declaring work complete;
-- care about SRP, API/database boundaries, safe logging, input validation, side effects, and automation reliability;
+- care about SOLID-informed coding discipline, API/database boundaries, safe logging, input validation, side effects, and automation reliability;
 - want to restore the same AI coding workflow across machines and repositories.
 
 You may not need this if you only want a single prompt file, want strict CI enforcement immediately after installation, do not want generated `.jhste/` files or bridge blocks, or expect this tool to automatically refactor code.
@@ -147,7 +157,7 @@ These are the jhste-authored guardrail skills. They are installed by default as
 | [`setup`](skills/setup/SKILL.md)<br>A safe setup skill that prevents install/connect/update flows from overwriting existing project instructions | Installing or connecting the kit to a repository | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
 | [`jhste-engineering-judgment`](skills/jhste-engineering-judgment/SKILL.md)<br>A pre-change judgment skill that verifies goal, premise, scope, seam, and failure path before code edits | Before non-trivial code changes | Blind agreement, scope creep, unverified assumptions, unclear seams |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>A code-quality skill for input validation, observable failure handling, and secret-safe logging | Writing or reviewing application code | Unvalidated input, silent failure, secret logging, oversized files |
-| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>An architecture review skill for module boundaries, side-effect placement, and possible SRP violations | Changing module boundaries or app structure | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>An architecture review skill for module boundaries, side-effect placement, and SOLID-informed design risks | Changing module boundaries or app structure | Pass-through abstraction, mixed responsibility, side-effect leakage |
 | [`jhste-db-api-boundary`](skills/jhste-db-api-boundary/SKILL.md)<br>A boundary skill that checks responsibility and data contracts across API routes, services, repositories, and SQL | Touching API, controller, service, repository, SQL, or persistence code | Fat routes, unsafe SQL, missing auth/data scoping, leaky DTOs |
 | [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>An automation skill for crawler/scraper/worker/scheduler producer-consumer seams and side effects | Touching crawlers, scrapers, workers, schedulers, or browser automation | Fragile automation, unclear producer/consumer boundaries, hidden side effects |
 | [`jhste-red-team-review`](skills/jhste-red-team-review/SKILL.md)<br>A read-only red-team code review skill that aggressively re-checks changed code before completion | Before declaring non-trivial code work complete | Premature “done”, missed null/auth/env/write/API/performance risks |
@@ -210,7 +220,7 @@ See [`docs/CLI.md`](docs/CLI.md) for detailed command behavior.
 2. Keep advisory hooks at first. Use `--skip-hooks` if you do not want commit-time checks, and enable blocking mode only after reviewing noise and false positives.
 3. Start with the default 300-line advisory limit. Use `--line-limit-mode blocking` only when the team is ready for warning-level hook enforcement.
 4. During code changes, run `guard --scope changed --format text --fail-on error` manually.
-5. Before non-trivial code changes, use `jhste-engineering-judgment` to check scope, seam, failure path, data contract, assumptions, and each changed class/module/function's main responsibility.
+5. Before non-trivial code changes, use `jhste-engineering-judgment` to check scope, seam, failure path, data contract, assumptions, and the SOLID-informed review lens for changed classes/modules/functions.
 6. Before declaring non-trivial code work complete, use `jhste-red-team-review`. Skip docs-only, comment-only, formatting-only, and trivial rename-only changes.
 7. Limit fix + re-review loops to two cycles, then report remaining risks instead of looping indefinitely.
 8. Create a baseline only after reviewing existing debt. Treat the baseline as a known-issues ledger and use ratchet behavior to stop new debt, not to hide scanner failures.
@@ -245,7 +255,7 @@ See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptanc
 - Do not agree blindly.
 - Do not overwrite local project authority.
 - Keep changes scoped.
-- Name responsibility boundaries from an SRP perspective.
+- Use SOLID-informed coding discipline: name responsibilities, review extension seams, preserve caller contracts, keep interfaces right-sized, and make concrete dependencies visible.
 - Make failures observable.
 - Treat automated guard output as evidence, not proof.
 - Run a red-team code review before calling non-trivial work complete.

package/README.zh.md

@@ -4,7 +4,17 @@ Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.
 
 一套可安装的工作规则工具包，帮助 AI 编程代理稳定遵循你设定的工程标准。
 
-`jhste-skills` 为 Codex、Claude Code 等 AI 编程代理提供一套共享的工程工作流。它帮助代理在修改代码前验证前提，优先遵循仓库本地说明，保持 API/database/automation 边界清晰，从 SRP（Single Responsibility Principle，单一职责原则）的角度检查每个模块是否只有一个明确职责，运行 changed-file guard，并在声明完成前执行 red-team code review。
+`jhste-skills` 为 Codex、Claude Code 等 AI 编程代理提供一套共享的工程工作流。它帮助代理在修改代码前验证前提，优先遵循仓库本地说明，保持 API/database/automation 边界清晰，应用 SOLID-informed coding discipline 和 design review lens，运行 changed-file guard，并在声明完成前执行 red-team code review。guard finding 是 review candidate，不是自动 SOLID 证明。
+
+## 这里的 SOLID 是什么意思
+
+这里的 SOLID 是设计 review lens，不是自动合规检查表。
+
+- **S — Single Responsibility:** 被修改的 function、module、class 应该有一个主要职责和一个主要变更理由。
+- **O — Open/Closed:** 如果每次新增 variant、provider、policy 都要反复修改 core branching，就要检查是否需要真实的 extension seam。
+- **L — Liskov Substitution:** implementation 不应削弱 caller 对 return shape、nullability、error、side effect 或已文档化行为的期待。
+- **I — Interface Segregation:** caller 只需要小而稳定的一部分时，不应依赖过大的 config、interface 或 props object。
+- **D — Dependency Inversion:** high-level policy 不应强绑定到 DB、API、browser、filesystem、email、payment、queue 等 concrete side effect；必要时应通过有意图且可见的 seam 暴露。
 
 这个工具不会接管你的项目。仓库内的 `AGENTS.md`、`CLAUDE.md` 和 docs 始终是权威来源。默认设置是 advisory 模式，使用 marker-managed 方式管理变更，设计目标是低风险、容易试用。
 
@@ -16,7 +26,7 @@ AI 编程代理很快，但经常以可预测的方式失败：
 
 - 默默接受不清晰的需求或错误前提。
 - 为了“帮忙”而扩大修改范围。
-- 把 UI、route/controller、service、database、side effect 职责混在一个地方，破坏“一个模块，一个职责”原则（SRP）。
+- 把 UI、route/controller、service、database、side effect 职责混在一个地方，或以 SOLID 为名加入没有真实 seam 的抽象。
 - 隐藏失败，或产生不安全的日志。
 - 在变更代码尚未检查前就说“完成”。
 - 当你切换机器或仓库时，忘记仓库特定规则。
@@ -25,7 +35,7 @@ AI 编程代理很快，但经常以可预测的方式失败：
 
 ```text
 在 non-trivial code change 前：
-  检查目标、前提、ownership seam、data contract、failure path、SRP 职责
+  检查目标、前提、ownership seam、data contract、failure path、SOLID-informed review lens
 
 修改过程中：
   将 repo-local instructions 视为权威
@@ -40,7 +50,7 @@ AI 编程代理很快，但经常以可预测的方式失败：
   尝试 bounded fix，重新检查，然后停止，避免无限循环
 ```
 
-预期结果是更小的 diff、更清晰的 SRP 边界、更安全的 API/database 代码、更少的 silent assumption，以及更诚实的完成报告。
+预期结果是更小的 diff、更清晰的 SOLID-informed seam、更安全的 API/database 代码、更少的 silent assumption，以及更诚实的完成报告。
 
 ## 谁适合安装？
 
@@ -50,7 +60,7 @@ AI 编程代理很快，但经常以可预测的方式失败：
 - 希望代理在 non-trivial code change 前验证前提；
 - 希望现有 repo docs 继续作为权威来源；
 - 希望在提交前或声明完成前加入轻量 advisory check；
-- 重视 SRP、API/database boundary、safe logging、input validation、side effect、automation reliability；
+- 重视 SOLID-informed coding discipline、API/database boundary、safe logging、input validation、side effect、automation reliability；
 - 希望在不同机器和仓库之间快速恢复相同的 AI 编程工作习惯。
 
 如果你只想要一个 prompt 文件，或希望安装后立即启用 strict CI enforcement，或不想生成 `.jhste/` 文件和 bridge block，或期待这个工具自动重构代码，那它可能不适合你。
@@ -147,7 +157,7 @@ Custom   - 通过面向效果的问题自定义安装范围
 | [`setup`](skills/setup/SKILL.md)<br>安全安装 skill，避免 install/connect/update 覆盖现有项目说明 | 安装 kit 或连接仓库时 | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
 | [`jhste-engineering-judgment`](skills/jhste-engineering-judgment/SKILL.md)<br>pre-change 判断 skill，在改代码前验证目标、前提、scope、seam 和 failure path | non-trivial code change 前 | Blind agreement, scope creep, unverified assumption, unclear seam |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>检查 input validation、observable failure handling、secret-safe logging 的代码质量 skill | 编写或 review application code 时 | Unvalidated input, silent failure, secret logging, oversized file |
-| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>检查 module boundary、side-effect placement 和 SRP 风险的架构 review skill | 修改 module boundary 或 app structure 时 | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>检查 module boundary、side-effect placement 和 SOLID-informed design risk 的架构 review skill | 修改 module boundary 或 app structure 时 | Pass-through abstraction, mixed responsibility, side-effect leakage |
 | [`jhste-db-api-boundary`](skills/jhste-db-api-boundary/SKILL.md)<br>检查 API route、service、repository、SQL 之间职责和 data contract 的 boundary skill | 修改 API、controller、service、repository、SQL、persistence code 时 | Fat route, unsafe SQL, missing auth/data scoping, leaky DTO |
 | [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>检查 crawler/scraper/worker/scheduler 的 producer-consumer seam 和 side effect 的 automation skill | 修改 crawler、scraper、worker、scheduler、browser automation 时 | Fragile automation, unclear producer/consumer boundary, hidden side effect |
 | [`jhste-red-team-review`](skills/jhste-red-team-review/SKILL.md)<br>read-only red-team code review skill，在完成前主动攻击性复查变更代码 | non-trivial code work 完成声明前 | Premature “done”, missed null/auth/env/write/API/performance risk |
@@ -210,7 +220,7 @@ jhste-skills uninstall
 2. 一开始保留 advisory hook。如果不想要 commit-time check，使用 `--skip-hooks`；只有在充分检查 noise 和 false positive 后才启用 blocking mode。
 3. 先使用默认 300-line advisory limit。只有团队准备接受 warning-level hook enforcement 时，才使用 `--line-limit-mode blocking`。
 4. 修改代码时，手动运行 `guard --scope changed --format text --fail-on error`。
-5. non-trivial code change 前，用 `jhste-engineering-judgment` 检查 scope、seam、failure path、data contract、assumption，以及每个 changed class/module/function 的 main responsibility。
+5. non-trivial code change 前，用 `jhste-engineering-judgment` 检查 scope、seam、failure path、data contract、assumption，以及 changed class/module/function 的 SOLID-informed review lens。
 6. non-trivial code work 完成声明前，使用 `jhste-red-team-review`。跳过 docs-only、comment-only、formatting-only、trivial rename-only 变更。
 7. fix + re-review 最多重复两轮，然后报告剩余 risk，避免无限循环。
 8. 只有在审查 existing debt 后才创建 baseline。将 baseline 视为 known-issues ledger，用 ratchet 阻止 new debt，而不是隐藏 scanner failure。
@@ -245,7 +255,7 @@ Release acceptance notes 请参考 [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_
 - 不盲目同意。
 - 不覆盖 local project authority。
 - 保持变更范围受控。
-- 从 SRP 角度命名 responsibility boundary。
+- 使用 SOLID-informed coding discipline 来命名 responsibility，并检查 extension seam、caller contract、interface 大小和 concrete dependency 方向。
 - 让 failure observable。
 - 将 automated guard output 视为 evidence，而不是 proof。
 - 在称 non-trivial work 完成前执行 red-team code review。

package/adapters/codex/README.md

@@ -11,6 +11,7 @@ Repo-local instructions in this file remain authoritative.
 See `.jhste/profile.yaml` for local skill preferences.
 Before non-trivial code changes, use the `jhste-engineering-judgment` skill to check scope, seams, failure paths, and assumptions.
 For changed code, name the one main responsibility of each changed class, module, and function, and reject adjacent responsibilities unless they are on the changed execution path and prevent a concrete failure.
+Use SOLID-informed coding discipline as a review lens, not a compliance claim; guard findings are review candidates, not proof.
 After code changes, run `jhste-skills guard --scope changed --format text --fail-on error` when available.
 Report guard warnings/errors; do not treat guard runtime/config failures as validation success.
 Treat guard output as review evidence, not proof by itself.

package/cli/deep-scan/analyze.mjs

@@ -12,6 +12,8 @@ const SHARED_SCANNER_BUCKETS = new Map([
   ['file_size_advisory', 'largeFiles'],
   ['responsibility_budget', 'responsibilityBudget'],
   ['single_responsibility_advisory', 'singleResponsibility'],
+  ['extension_seam_advisory', 'extensionSeams'],
+  ['dependency_boundary_advisory', 'dependencyBoundaries'],
   ['component_responsibility', 'clientServerSeam'],
   ['external_input_validation', 'externalInput'],
   ['null_state_safety', 'stateSafety'],
@@ -80,6 +82,8 @@ function newFindingsBag() {
     routeResponsibility: [],
     responsibilityBudget: [],
     singleResponsibility: [],
+    extensionSeams: [],
+    dependencyBoundaries: [],
     clientServerSeam: [],
     hiddenSideEffects: [],
     secretLogging: [],

package/cli/deep-scan/report.mjs

@@ -70,6 +70,10 @@ ${tableRows([...findings.dbInRoutes, ...findings.routeResponsibility])}
 ${tableRows(findings.responsibilityBudget)}
 ### Existing single-responsibility candidates
 ${tableRows(findings.singleResponsibility)}
+### Existing extension seam candidates
+${tableRows(findings.extensionSeams)}
+### Existing dependency boundary candidates
+${tableRows(findings.dependencyBoundaries)}
 ### Existing client/server seam candidates
 ${tableRows(findings.clientServerSeam)}
 ### Existing hidden side-effect candidates
@@ -157,6 +161,10 @@ rules:
     module_export_family_hints: ${thresholds.singleResponsibility.module_export_family_hints}
   external_input_validation:
     mode: advisory
+  extension_seam_advisory:
+    mode: advisory
+  dependency_boundary_advisory:
+    mode: advisory
   null_state_safety:
     mode: advisory
   authz_data_isolation:

package/cli/guard/registry.mjs

@@ -24,6 +24,8 @@ export const FINDING_METADATA = {
   'srp.function.length': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
   'srp.function.mixed_responsibility': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
   'srp.module.mixed_exports': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
+  'solid.ocp.variant_branching_hotspot': { family: 'extension_seam_advisory', pack: 'core', scanner: 'scanExtensionSeamAdvisory' },
+  'solid.dip.concrete_side_effect_dependency': { family: 'dependency_boundary_advisory', pack: 'core', scanner: 'scanDependencyBoundaryAdvisory' },
   'state.non_null_assertion': { family: 'null_state_safety', pack: 'core', scanner: 'scanStateSafety' },
   'state.async_ui_missing_fallback': { family: 'null_state_safety', pack: 'core', scanner: 'scanStateSafety' },
   'authz.scope_not_visible': { family: 'authz_data_isolation', pack: 'core', scanner: 'scanAuthzDataIsolation' },

package/cli/guard/reporting.mjs

@@ -48,69 +48,60 @@ export function exitCodeFor(result, failOn, baselineMode) {
   return 0;
 }
 
+const FAMILY_GUIDANCE = {
+  file_size_advisory: {
+    means: 'This file exceeds the configured line limit. It is not proof of a bug, but it increases the chance that review, conflict resolution, and test boundaries become harder to manage.',
+    next: 'Split the file along natural boundaries so each helper, adapter, scanner family, or test fixture carries one main responsibility at a time.',
+  },
+  responsibility_budget: {
+    means: 'This file may be combining multiple responsibilities such as UI, state, IO, validation, persistence, and response shaping.',
+    next: 'Check whether the code can move into smaller modules with explicit names such as loader, service, repository, or view.',
+  },
+  single_responsibility_advisory: {
+    means: 'This class, module, or function may have more than one reason to change. The finding is heuristic and should be reviewed, not treated as proof.',
+    next: 'Name the one main responsibility, then move only independently changing work behind a real seam; keep always-cochanging contract pieces together and avoid shallow pass-through wrappers.',
+  },
+  extension_seam_advisory: {
+    means: 'This is a low-confidence SOLID-informed OCP candidate where variant, provider, or policy branching may keep forcing core edits.',
+    next: 'Review whether a registry, strategy, adapter, or explicit policy table would reduce repeated edits without adding premature pass-through abstraction.',
+  },
+  dependency_boundary_advisory: {
+    means: 'This is a low-confidence SOLID-informed DIP candidate where high-level policy or service code may directly own a concrete side effect.',
+    next: 'Check whether the dependency should be visible behind an adapter, repository, injected dependency, or intentionally local seam.',
+  },
+  external_input_validation: {
+    means: 'This is a candidate path where external input such as files, request bodies, third-party API data, or env values may be trusted without shape validation.',
+    next: 'Add an explicit validation boundary such as schema.safeParse, a validator, or assert/parseEnv, or make an existing validation step clearly visible in code.',
+  },
+  no_secret_logging: {
+    means: 'This is a candidate path where logs may include sensitive fields such as tokens, passwords, or session values.',
+    next: 'Confirm that real secrets are not emitted, and redact values before logging when needed.',
+  },
+  build_runtime_env_safety: {
+    means: 'Direct env reads can fail differently across build and runtime environments, producing undefined values or invalid configuration.',
+    next: 'Use startup-time env schema validation, defaults, or a requiredEnv helper so failure points are explicit.',
+  },
+  write_safety_idempotency: {
+    means: 'This is a candidate path where repeated or retried writes could create duplicate records or partial success states.',
+    next: 'Check whether transactions, upserts, idempotency keys, dedupe logic, or batch semantics are the right safety mechanism here.',
+  },
+  api_contract_compatibility: {
+    means: 'The request or response shape may be unclear at the API boundary, or storage-layer shapes may be leaking directly to callers.',
+    next: 'Add an input schema and public DTO mapping so the caller-facing contract stays explicit and stable.',
+  },
+  authz_data_isolation: {
+    means: 'Authn/authz checks or tenant-owner scoping may be unclear in code, creating a candidate risk of cross-user data access.',
+    next: 'Make requireUser/permission checks and owner filters such as userId, orgId, or tenantId visible in the same flow.',
+  },
+  performance_duplicate_fetch: {
+    means: 'Duplicate fetches or missing cache use in the same path may cause slow rendering or unnecessary network calls.',
+    next: 'Check whether these calls can be consolidated behind a shared loader, query hook, or cache key.',
+  },
+};
+
 function guidanceForFinding(item) {
   const family = item.rule_family || FINDING_METADATA[item.rule_id]?.family || item.rule_id;
-  if (family === 'file_size_advisory') {
-    return {
-      means: 'This file exceeds the configured line limit. It is not proof of a bug, but it increases the chance that review, conflict resolution, and test boundaries become harder to manage.',
-      next: 'Split the file along natural boundaries so each helper, adapter, scanner family, or test fixture carries one main responsibility at a time.',
-    };
-  }
-  if (family === 'responsibility_budget') {
-    return {
-      means: 'This file may be combining multiple responsibilities such as UI, state, IO, validation, persistence, and response shaping.',
-      next: 'Check whether the code can move into smaller modules with explicit names such as loader, service, repository, or view.',
-    };
-  }
-
-  if (family === 'single_responsibility_advisory') {
-    return {
-      means: 'This class, module, or function may have more than one reason to change. The finding is heuristic and should be reviewed, not treated as proof.',
-      next: 'Name the one main responsibility, then move only independently changing work behind a real seam; keep always-cochanging contract pieces together and avoid shallow pass-through wrappers.',
-    };
-  }
-  if (family === 'external_input_validation') {
-    return {
-      means: 'This is a candidate path where external input such as files, request bodies, third-party API data, or env values may be trusted without shape validation.',
-      next: 'Add an explicit validation boundary such as schema.safeParse, a validator, or assert/parseEnv, or make an existing validation step clearly visible in code.',
-    };
-  }
-  if (family === 'no_secret_logging') {
-    return {
-      means: 'This is a candidate path where logs may include sensitive fields such as tokens, passwords, or session values.',
-      next: 'Confirm that real secrets are not emitted, and redact values before logging when needed.',
-    };
-  }
-  if (family === 'build_runtime_env_safety') {
-    return {
-      means: 'Direct env reads can fail differently across build and runtime environments, producing undefined values or invalid configuration.',
-      next: 'Use startup-time env schema validation, defaults, or a requiredEnv helper so failure points are explicit.',
-    };
-  }
-  if (family === 'write_safety_idempotency') {
-    return {
-      means: 'This is a candidate path where repeated or retried writes could create duplicate records or partial success states.',
-      next: 'Check whether transactions, upserts, idempotency keys, dedupe logic, or batch semantics are the right safety mechanism here.',
-    };
-  }
-  if (family === 'api_contract_compatibility') {
-    return {
-      means: 'The request or response shape may be unclear at the API boundary, or storage-layer shapes may be leaking directly to callers.',
-      next: 'Add an input schema and public DTO mapping so the caller-facing contract stays explicit and stable.',
-    };
-  }
-  if (family === 'authz_data_isolation') {
-    return {
-      means: 'Authn/authz checks or tenant-owner scoping may be unclear in code, creating a candidate risk of cross-user data access.',
-      next: 'Make requireUser/permission checks and owner filters such as userId, orgId, or tenantId visible in the same flow.',
-    };
-  }
-  if (family === 'performance_duplicate_fetch') {
-    return {
-      means: 'Duplicate fetches or missing cache use in the same path may cause slow rendering or unnecessary network calls.',
-      next: 'Check whether these calls can be consolidated behind a shared loader, query hook, or cache key.',
-    };
-  }
+  if (FAMILY_GUIDANCE[family]) return FAMILY_GUIDANCE[family];
   if (item.confidence === 'low') {
     return {
       means: 'This is a low-confidence static heuristic candidate. It does not mean the code is definitely buggy.',

package/cli/guard/scanners/index.mjs

@@ -30,6 +30,7 @@ import {
   scanStateSafety,
 } from './ui-runtime.mjs';
 import { scanSingleResponsibility } from './single-responsibility.mjs';
+import { scanDependencyBoundaryAdvisory, scanExtensionSeamAdvisory } from './solid-design.mjs';
 import { isSourceCodePath, violation } from './utils.mjs';
 
 const ACTIVE_PROFILE_MODES = new Set(['advisory', 'changed-files', 'baseline-new-only', 'strict']);
@@ -50,6 +51,8 @@ export const SCANNER_REGISTRY = [
   { id: 'scanFileSizeAdvisory', families: ['file_size_advisory'], scan: ({ relPath, text, settings }) => scanFileSizeAdvisory(relPath, text, settings.fileSize) },
   { id: 'scanResponsibilityBudget', families: ['responsibility_budget'], scan: ({ relPath, text, settings }) => scanResponsibilityBudget(relPath, text, settings.responsibilityBudget) },
   { id: 'scanSingleResponsibility', families: ['single_responsibility_advisory'], scan: ({ relPath, text, settings }) => scanSingleResponsibility(relPath, text, settings.singleResponsibility) },
+  { id: 'scanExtensionSeamAdvisory', families: ['extension_seam_advisory'], scan: ({ relPath, text }) => scanExtensionSeamAdvisory(relPath, text) },
+  { id: 'scanDependencyBoundaryAdvisory', families: ['dependency_boundary_advisory'], scan: ({ relPath, text }) => scanDependencyBoundaryAdvisory(relPath, text) },
   { id: 'scanStateSafety', families: ['null_state_safety'], scan: ({ relPath, text }) => scanStateSafety(relPath, text) },
   { id: 'scanAuthzDataIsolation', families: ['authz_data_isolation'], scan: ({ relPath, text }) => scanAuthzDataIsolation(relPath, text) },
   { id: 'scanRuntimeEnvSafety', families: ['build_runtime_env_safety'], scan: ({ relPath, text }) => scanRuntimeEnvSafety(relPath, text) },