jhste-skills 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+
+## 0.3.1 - 2026-06-26
+
+### Changed
+- Strengthened completion review around current proof, consumer-path and fresh-client verification, skipped checks, checks not run, and residual risk.
+- Added final behavior predicates to pre-change engineering groundwork.
+- Clarified cleanup/search-replace safety by separating editable product paths from protected evidence/history-like surfaces.
+- Kept SOLID-informed coding discipline while emphasizing concrete failure modes over automatic abstraction.
+- Clarified that `grilling` and `grill-me` are read-only by default.
+- Made architecture improvement Markdown-first, with HTML visual reports optional when requested or materially useful.
+
+## 0.3.0 - 2026-06-24
+
+### Added
+- Added repo-local agent autonomy and standing approval guidance for routine reversible work, tracker/doc workflows, prototypes, handoffs, and bounded review follow-up.
+- Added shared generated-profile detection with legacy generated profile support, including legacy profiles that still contain `guard.exit_codes`.
+- Added `--allow-profile-overwrite` for explicit modified profile replacement when used with `--force`.
+- Added smoke and fixture coverage for profile overwrite safety, legacy generated profiles, deep-scan validation, baseline path handling, legacy guard exit-code no-op handling, and managed skill rename migration.
+
+### Changed
+- Renamed `jhste-engineering-judgment` to `jhste-engineering-groundwork`; managed `sync`/`update` migrate the old managed skill name automatically.
+- Replaced general user-facing “seam” language with “boundary” while preserving stable rule/profile ids such as `extension_seam_advisory` for compatibility.
+- Updated skill descriptions and bodies for grilling, PRD/issues, prototype, handoff, triage, domain modeling, codebase design, architecture review, code quality, groundwork, and red-team review triggers/side-effect policy.
+- Refactored install/connect preset planning to table-driven plan factories so the previous OCP advisory warning is no longer emitted.
+
+### Fixed
+- `install --force` no longer overwrites modified/custom `.jhste/profile.yaml` unless `--allow-profile-overwrite` is also supplied.
+- `connect`, `sync`, and `update` now share the same profile overwrite safety policy.
+- New generated/example profiles no longer advertise unsupported `guard.exit_codes`; existing profile `guard.exit_codes` blocks are accepted as legacy no-op configuration.
+- `deep-scan` now validates `.jhste/profile.yaml` and exits with config failure before writing reports when the profile is invalid.
+- `baseline` now validates profile configuration and shows/uses the effective baseline path from CLI args, profile, or the default consistently.
+
+### Validation
+- `npm test` passed.
+- `jhste-skills guard --scope changed --format text --fail-on error` passed with 0 warnings/errors.
+- `git diff --check` passed.

package/README.ja.md

@@ -11,14 +11,14 @@ AI コーディングエージェントが、あなたの定義したエンジ
 ここでの SOLID は、自動 compliance チェックリストではなく、設計レビューのレンズです。
 
 - **S — Single Responsibility:** 変更された function、module、class は、1 つの主な役割と 1 つの主な変更理由を持つべきです。
-- **O — Open/Closed:** 新しい variant、provider、policy を追加するたびに core branching を何度も編集するなら、実際の extension seam が必要かを確認します。
+- **O — Open/Closed:** 新しい variant、provider、policy を追加するたびに core branching を何度も編集するなら、実際の extension boundary が必要かを確認します。
 - **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 にします。
+- **D — Dependency Inversion:** high-level policy が DB、API、browser、filesystem、email、payment、queue などの concrete side effect に強く結びつかないようにし、必要な場合は意図的で見える boundary にします。
 
 このツールはプロジェクトを乗っ取りません。リポジトリ内の `AGENTS.md`、`CLAUDE.md`、docs が常に権威です。デフォルト設定は advisory モードで、marker-managed 方式で管理され、低リスクで試せるように設計されています。
 
-Skills は、必要な状況でエージェントが自動的に使うことを想定しています。たとえば API コードを変更する場合は API/database boundary skill を、完了直前には red-team review skill を使うよう促します。ユーザーが明示的に skill を呼び出すこともできます。例: `use jhste-engineering-judgment to review this change premise`、`run jhste-red-team-review on this diff`。
+Skills は、必要な状況でエージェントが自動的に使うことを想定しています。たとえば API コードを変更する場合は API/database boundary skill を、完了直前には red-team review skill を使うよう促します。ユーザーが明示的に skill を呼び出すこともできます。例: `use jhste-engineering-groundwork to review this change premise`、`run jhste-red-team-review on this diff`。
 
 ## なぜインストールするのか？
 
@@ -26,7 +26,7 @@ AI コーディングエージェントは高速ですが、失敗パターン
 
 - 不明確な要求や誤った前提を黙って受け入れます。
 - 役に立とうとして作業範囲を広げすぎます。
-- UI、route/controller、service、database、side effect の責任を 1 か所に混ぜ込んだり、実際の seam がない抽象化を SOLID 名目で追加したりします。
+- UI、route/controller、service、database、side effect の責任を 1 か所に混ぜ込んだり、実際の boundary がない抽象化を SOLID 名目で追加したりします。
 - 失敗を隠したり、安全でないログを出したりします。
 - 変更コードを十分確認する前に「完了」と言います。
 - マシンやリポジトリを切り替えるたびに、リポジトリ固有のルールを忘れます。
@@ -35,7 +35,7 @@ AI コーディングエージェントは高速ですが、失敗パターン
 
 ```text
 non-trivial code change の前:
-  goal、premise、ownership seam、data contract、failure path、SOLID-informed review lens を確認
+  goal、premise、ownership boundary、data contract、failure path、SOLID-informed review lens を確認
 
 編集中:
   repo-local instructions を権威として扱う
@@ -50,7 +50,7 @@ warning が出た場合:
   bounded fix を試し、再確認し、無限ループせず停止する
 ```
 
-期待される結果は、より小さな diff、より明確な SOLID-informed seam、より安全な API/database コード、より少ない silent assumption、より誠実な完了報告です。
+期待される結果は、より小さな diff、より明確な SOLID-informed boundary、より安全な API/database コード、より少ない silent assumption、より誠実な完了報告です。
 
 ## 誰がインストールすべきか？
 
@@ -83,7 +83,7 @@ jhste-skills install
 デフォルトインストールは Normal mode を使います。
 
 - bundled skills 全体をインストールします: jhste core skills + vendored workflow skills。
-- `.jhste/profile.yaml` がなければ作成します。
+- `.jhste/profile.yaml` がなければ作成します。`--force` は generated/managed profile だけを refresh し、modified profile の overwrite には `--force --allow-profile-overwrite` が必要です。
 - project guidance が有効な場合、`AGENTS.md` または `CLAUDE.md` に marker-managed bridge block を追加または更新します。
 - 安全な場合、advisory pre-commit hook をインストールします。
 - CI、対象 `package.json`、lockfile、source code は変更しません。
@@ -119,7 +119,7 @@ managed outputs を削除するには:
 jhste-skills uninstall --yes --repo /path/to/repo
 ```
 
-`uninstall` は managed hook、marker-managed bridge block、manifest-managed skill directory を削除します。non-managed file には触れません。`.jhste/profile.yaml` は generated shape のままの場合のみ削除されます。変更済み profile を削除する場合は、内容を確認してから `--force-profile` を明示してください。
+`uninstall` は managed hook、marker-managed bridge block、manifest-managed skill directory を削除します。non-managed file には触れません。`.jhste/profile.yaml` は current または legacy generated shape の場合のみ削除されます。変更済み profile を削除する場合は、内容を確認してから `--force-profile` を明示してください。
 
 ## インストールモード
 
@@ -155,36 +155,36 @@ Custom   - 効果ベースの質問でセットアップ範囲を選択
 | Skill | いつ使うか | 何を減らすか |
 |---|---|---|
 | [`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、SOLID-informed design risk を確認する architecture review skill | module boundary や app structure を変更するとき | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>コード変更前に goal、premise、scope、boundary、failure path を検証する pre-change groundwork skill | non-trivial code change の前 | Blind agreement, scope creep, unverified assumption, unclear boundary |
+| [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>input validation、observable failure handling、secret-safe logging、oversized-file review の skill | external input、failure handling、logging、env/config、code-quality review path を触るとき | Unvalidated input, silent failure, secret logging, oversized file |
+| [`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、side-effect placement、responsibility split を変更するとき | 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-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>crawler/scraper/worker/scheduler の producer-consumer boundary と 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 |
 
 ## Bundled workflow skills
 
-Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring した 14 個の workflow skills もインストールします。これらは debugging、planning、architecture、issue workflow、prototyping、handoff に役立ちます。インストールしたくない場合は `--skill-set core` を使ってください。
+Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring した 13 個の workflow skills もインストールします。これらは debugging、planning、architecture、issue workflow、prototyping、handoff に役立ちます。インストールしたくない場合は `--skill-set core` を使ってください。
 
 | Skill | いつ使うか |
 |---|---|
 | [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>高速な pass/fail feedback loop を中心に root cause を絞り込む debugging skill | reproduce → minimise → hypothesise → instrument → fix ループが必要なとき |
-| [`grill-me`](skills/grill-me/SKILL.md)<br>計画や設計の穴がなくなるまで粘り強く質問する skill | agent に計画や設計を明確になるまで質問させたいとき |
-| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>質問しながら domain terms と decisions を文書化する design validation skill | 質問プロセスで project vocabulary や docs/ADR も更新したいとき |
-| [`grilling`](skills/grilling/SKILL.md)<br>実装前に圧迫質問で計画と設計を検証する汎用 grilling skill | 一般的な plan/design stress-test 質問ループが必要なとき |
+| [`grill-me`](skills/grill-me/SKILL.md)<br>ユーザー自身の計画や推論を直接厳しく質問する grilling skill | grilled、challenged、pressure-tested、aggressive questioning を求めるとき |
+| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>grilling の結果を CONTEXT.md や ADR に記録する skill | stress-test に加えて documentation、ADR、glossary、CONTEXT update も必要なとき |
+| [`grilling`](skills/grilling/SKILL.md)<br>docs を書かずに plan/design を pressure-test する read-only grilling skill | challenge、pressure-test、red-team、grill、find gaps が必要なとき |
 | [`domain-modeling`](skills/domain-modeling/SKILL.md)<br>プロジェクト用語、domain model、architectural decision を明確にする skill | domain term、ubiquitous language、architectural decision を整えるとき |
-| [`codebase-design`](skills/codebase-design/SKILL.md)<br>deep module、小さな interface、明確な seam のための codebase design skill | より良い module interface、seam、testability vocabulary が必要なとき |
+| [`codebase-design`](skills/codebase-design/SKILL.md)<br>deep module、小さな interface、明確な boundary のための codebase design skill | より良い module interface、boundary、testability vocabulary が必要なとき |
 | [`improve-codebase-architecture`](skills/improve-codebase-architecture/SKILL.md)<br>shallow module と coupling を見つけ、deepening opportunity を探す architecture skill | deepening opportunity を見つけ、architectural friction を減らしたいとき |
-| [`prototype`](skills/prototype/SKILL.md)<br>本実装前に throwaway code で logic や UI 方向を検証する prototyping skill | approach を確定する前に throwaway logic/UI prototype を作りたいとき |
-| [`to-prd`](skills/to-prd/SKILL.md)<br>会話 context を product requirements に構造化する PRD 作成 skill | 会話 context を PRD に変換したいとき |
-| [`to-issues`](skills/to-issues/SKILL.md)<br>計画を独立して作業可能な vertical-slice issues に分解する skill | plan を独立して進められる implementation issues に分けたいとき |
-| [`triage`](skills/triage/SKILL.md)<br>structured workflow で issue を分類し、次の action を決める triage skill | issue を structured triage workflow で処理したいとき |
-| [`handoff`](skills/handoff/SKILL.md)<br>次の agent や session が続けられるよう context を圧縮する handoff skill | 別の agent や session に context を渡したいとき |
+| [`prototype`](skills/prototype/SKILL.md)<br>throwaway local code で logic/state model や UI direction を検証する skill | prototype、mock up、try designs、sanity-check、“let me play with it” の依頼時 |
+| [`to-prd`](skills/to-prd/SKILL.md)<br>PRD draft を作成し通常の PRD workflow に載せられる形にする skill | PRD が必要なとき; tracker publish は直接依頼または repo approval がある場合のみ |
+| [`to-issues`](skills/to-issues/SKILL.md)<br>計画を issue-ready vertical slices に分解する skill | implementation tickets/work breakdown が必要なとき; tracker creation は直接依頼または repo approval がある場合 |
+| [`triage`](skills/triage/SKILL.md)<br>issue を分類し次の action を計画する triage skill | issue classification、next-action planning、repo-approved triage writes が必要なとき |
+| [`handoff`](skills/handoff/SKILL.md)<br>次の agent や session が続けられるよう context を圧縮する handoff skill | handoff、session summary、continuation brief、next-agent context の依頼時 |
 | [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>正しい構造と progressive disclosure で agent skill を作成する skill-writing skill | agent skill を作成または改善したいとき |
 
 ## Attribution: Matt Pocock skills
 
-このリポジトリは、上記 14 個の skills を Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring しています。
+このリポジトリは、上記 13 個の skills を Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring しています。
 
 これらの skills は upstream MIT License に基づいて vendoring されています。このリポジトリは必要な copyright/license notice を保持し、インポート元を記録しています。
 
@@ -220,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 の SOLID-informed review lens を確認します。
+5. non-trivial code change の前に、`jhste-engineering-groundwork` で scope、boundary、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 を防ぐために使います。
@@ -255,7 +255,7 @@ Release acceptance notes は [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.
 - 盲目的に同意しない。
 - local project authority を上書きしない。
 - 変更範囲を小さく保つ。
-- SOLID-informed coding discipline を使い、responsibility、extension seam、caller contract、interface size、concrete dependency direction を確認する。
+- SOLID-informed coding discipline を使い、responsibility、extension boundary、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,21 +4,21 @@ Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.
 
 AI 코딩 에이전트가 설정한 코딩 기준을 일관되게 따르도록 만드는 설치형 작업 규칙 세트입니다.
 
-`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입니다.
+`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이며, 완료 보고는 current proof, 실행하지 않은 check, residual risk를 분리해야 합니다.
 
 ## 여기서 SOLID가 의미하는 것
 
-여기서 SOLID는 자동 준수 체크리스트가 아니라 설계 리뷰 렌즈입니다.
+여기서 SOLID는 concrete maintenance/failure risk를 찾는 설계 리뷰 렌즈이며, 자동 준수 체크리스트나 추상화 트리거가 아닙니다.
 
 - **S — Single Responsibility:** 변경된 함수, 모듈, 클래스는 하나의 주 역할과 하나의 주 변경 이유를 가져야 합니다.
-- **O — Open/Closed:** 새 variant, provider, policy를 추가할 때 핵심 분기문을 계속 고쳐야 한다면 실제 extension seam이 필요한지 검토합니다.
+- **O — Open/Closed:** 새 variant, provider, policy를 추가할 때 핵심 분기문을 계속 고쳐야 한다면 실제 extension boundary가 필요한지 검토합니다.
 - **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으로 둡니다.
+- **D — Dependency Inversion:** high-level policy가 DB, API, browser, filesystem, email, payment, queue 같은 구체 side effect에 강하게 묶이지 않도록 하고, 필요한 경우 의도적이고 보이는 boundary로 둡니다.
 
 이 도구는 프로젝트를 장악하지 않습니다. 레포 안의 `AGENTS.md`, `CLAUDE.md`, docs가 항상 우선입니다. 기본 설정은 advisory 모드이며, marker-managed 방식으로 동작하고, 부담 없이 시도할 수 있도록 설계되어 있습니다.
 
-스킬은 필요한 상황에서 에이전트가 자동으로 사용하도록 설계되어 있습니다. 예를 들어 API 코드를 수정하면 API/database boundary 스킬을, 완료 직전에는 red-team review 스킬을 사용하도록 안내합니다. 사용자가 직접 특정 스킬을 호출할 수도 있습니다. 예: `jhste-engineering-judgment를 사용해서 이 변경 전제를 검토해줘`, `jhste-red-team-review로 이 diff를 리뷰해줘`.
+스킬은 필요한 상황에서 에이전트가 자동으로 사용하도록 설계되어 있습니다. 예를 들어 API 코드를 수정하면 API/database boundary 스킬을, 완료 직전에는 red-team review 스킬을 사용하도록 안내합니다. 사용자가 직접 특정 스킬을 호출할 수도 있습니다. 예: `jhste-engineering-groundwork를 사용해서 이 변경 전제를 검토해줘`, `jhste-red-team-review로 이 diff를 리뷰해줘`.
 
 ## 왜 설치해야 하나요?
 
@@ -26,7 +26,8 @@ AI 코딩 에이전트는 빠르지만, 반복적으로 비슷한 방식으로
 
 - 불명확한 요구사항이나 틀린 전제를 조용히 받아들입니다.
 - 도와주려다가 작업 범위를 과하게 넓힙니다.
-- UI, route/controller, service, database, side effect 책임을 한곳에 섞거나, 실제 seam 없는 추상화를 SOLID 명목으로 추가합니다.
+- UI, route/controller, service, database, side effect 책임을 한곳에 섞거나, 실제 boundary 없는 추상화를 SOLID 명목으로 추가합니다.
+- raw search result를 그대로 edit set으로 보고 broad cleanup/search-replace를 수행합니다.
 - 실패를 숨기거나 위험한 로그를 남깁니다.
 - 변경된 코드를 충분히 확인하기 전에 “완료”라고 말합니다.
 - 머신이나 레포를 바꿀 때마다 레포별 규칙을 잊어버립니다.
@@ -35,7 +36,7 @@ AI 코딩 에이전트는 빠르지만, 반복적으로 비슷한 방식으로
 
 ```text
 non-trivial code change 전:
-  목표, 전제, ownership seam, data contract, failure path, SOLID-informed review lens 확인
+  목표, 전제, ownership boundary, data contract, failure path, final behavior predicate, SOLID-informed review lens 확인
 
 수정 중:
   repo-local instructions를 권위로 취급
@@ -44,13 +45,13 @@ non-trivial code change 전:
   가능한 경우 빠른 changed-file guard 실행
 
 “완료”라고 말하기 전:
-  read-only red-team code review 실행
+  read-only red-team code review를 실행하고 가능한 경우 actual consumer-path proof 확인
 
 warning이 나오면:
   bounded fix를 시도하고, 다시 확인한 뒤, 무한 루프에 빠지지 않고 멈춤
 ```
 
-기대하는 결과는 더 작은 diff, 더 명확한 SOLID-informed seam, 더 안전한 API/database 코드, 더 적은 silent assumption, 더 솔직한 완료 보고입니다.
+기대하는 결과는 더 작은 diff, 더 명확한 SOLID-informed boundary, 더 안전한 API/database 코드, 더 적은 silent assumption, 더 안전한 cleanup/search-replace 동작, 그리고 변경된 public behavior의 현재 증거에 기반한 더 솔직한 완료 보고입니다.
 
 ## 누가 설치하면 좋나요?
 
@@ -60,7 +61,7 @@ warning이 나오면:
 - non-trivial code change 전에 에이전트가 전제를 확인하길 원합니다.
 - 기존 repo docs가 계속 권위로 남길 원합니다.
 - 커밋 전 또는 완료 선언 전에 가벼운 advisory check를 두고 싶습니다.
-- SOLID-informed coding discipline, API/database boundary, safe logging, input validation, side effect, automation reliability를 중요하게 봅니다.
+- SOLID-informed coding discipline, API/database boundary, safe logging, input validation, cleanup safety, side effect, automation reliability를 중요하게 봅니다.
 - 머신과 레포를 옮겨도 같은 AI 작업 습관을 빠르게 복원하고 싶습니다.
 
 반대로, prompt 파일 하나만 원하거나, 설치 즉시 strict CI enforcement를 원하거나, `.jhste/` 파일과 bridge block 생성을 원하지 않거나, 이 도구가 자동으로 코드를 refactor하길 기대한다면 맞지 않을 수 있습니다.
@@ -83,7 +84,7 @@ jhste-skills install
 기본 설치는 Normal mode를 사용합니다.
 
 - bundled skills 전체를 설치합니다: jhste core skills + vendored workflow skills.
-- `.jhste/profile.yaml`이 없으면 생성합니다.
+- `.jhste/profile.yaml`이 없으면 생성합니다. `--force`는 generated/managed profile만 refresh하며, modified profile overwrite는 `--force --allow-profile-overwrite`가 필요합니다.
 - project guidance가 켜져 있으면 `AGENTS.md` 또는 `CLAUDE.md`에 marker-managed bridge block을 추가하거나 갱신합니다.
 - 안전할 때 advisory pre-commit hook을 설치합니다.
 - CI, target `package.json`, lockfile, source code는 수정하지 않습니다.
@@ -119,7 +120,7 @@ managed output을 제거하려면:
 jhste-skills uninstall --yes --repo /path/to/repo
 ```
 
-`uninstall`은 managed hook, marker-managed bridge block, manifest-managed skill directory를 제거합니다. non-managed file은 건드리지 않습니다. `.jhste/profile.yaml`은 generated shape 그대로일 때만 제거하며, 수정된 profile을 제거하려면 내용을 검토한 뒤 `--force-profile`을 명시해야 합니다.
+`uninstall`은 managed hook, marker-managed bridge block, manifest-managed skill directory를 제거합니다. non-managed file은 건드리지 않습니다. `.jhste/profile.yaml`은 current 또는 legacy generated shape일 때만 제거하며, 수정된 profile을 제거하려면 내용을 검토한 뒤 `--force-profile`을 명시해야 합니다.
 
 ## 설치 모드
 
@@ -145,6 +146,8 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 - strict mode는 명시적 opt-in이 필요합니다.
 - bridge block은 `<!-- jhste-skills:start -->` / `<!-- jhste-skills:end -->` marker를 사용합니다.
 - guard output은 review evidence이지 그 자체로 proof가 아닙니다.
+- 완료 전 리뷰는 가능한 경우 actual consumer-path proof를 선호하고 current proof, skipped check, not-run check, residual risk를 분리해야 합니다.
+- cleanup/search-replace 작업은 쓰기 전에 editable path와 protected evidence/history-like path를 분리해야 합니다.
 - guard runtime/config failure는 rule violation과 별도로 보고해야 합니다.
 - install/update/uninstall flow는 non-managed hook, bridge text, skill directory를 건드리지 않습니다.
 
@@ -155,31 +158,31 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 | Skill | 언제 쓰나 | 무엇을 줄여주나 |
 |---|---|---|
 | [`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 위치, SOLID-informed design risk를 검토하는 아키텍처 리뷰 스킬 | module boundary나 app structure 변경 시 | pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>코드 변경 전 목표, 전제, scope, boundary, failure path, final behavior predicate를 검증하는 pre-change groundwork 스킬 | non-trivial code change 전 | blind agreement, scope creep, unverified assumption, unclear boundary |
+| [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>입력 검증, 관측 가능한 실패 처리, secret-safe logging, oversized-file review 스킬 | external input, failure handling, logging, env/config, cleanup/search-replace, code-quality review path를 만질 때 | unvalidated input, silent failure, secret logging, unsafe broad cleanup, oversized file |
+| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>모듈 경계, side effect 위치, SOLID-informed design risk를 검토하는 아키텍처 리뷰 스킬 | module boundary, app structure, side-effect placement, responsibility split 변경 시 | 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 |
+| [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>crawler, scraper, worker, scheduler의 producer/consumer boundary와 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”, missing consumer-path proof, 놓치기 쉬운 null/auth/env/write/API/performance risk |
 
 ## Bundled workflow skills
 
-Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpocock/skills)에서 vendoring한 workflow skills 14개도 함께 설치합니다. 이 스킬들은 debugging, planning, architecture, issue workflow, prototyping, handoff 작업에 유용합니다. 설치하고 싶지 않다면 `--skill-set core`를 사용하세요.
+Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpocock/skills)에서 vendoring한 workflow skills 13개도 함께 설치합니다. 이 스킬들은 debugging, planning, architecture, issue workflow, prototyping, handoff 작업에 유용합니다. 설치하고 싶지 않다면 `--skill-set core`를 사용하세요.
 
 | Skill | 언제 쓰나 |
 |---|---|
 | [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>빠른 pass/fail feedback loop를 중심으로 원인을 좁혀가는 debugging 스킬 | reproduce → minimise → hypothesise → instrument → fix 루프가 필요할 때 |
-| [`grill-me`](skills/grill-me/SKILL.md)<br>계획이나 설계의 빈틈이 사라질 때까지 집요하게 질문하는 스킬 | agent가 계획이나 설계를 명확해질 때까지 질문하게 하고 싶을 때 |
-| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>질문 과정에서 도메인 용어와 의사결정을 문서화하는 설계 검증 스킬 | 질문 과정에서 project vocabulary와 docs/ADR까지 함께 정리하고 싶을 때 |
-| [`grilling`](skills/grilling/SKILL.md)<br>구현 전에 계획과 설계를 압박 질문으로 검증하는 일반 grilling 스킬 | 일반적인 plan/design stress-test 질문 루프가 필요할 때 |
+| [`grill-me`](skills/grill-me/SKILL.md)<br>사용자 자신의 계획/추론을 공격적으로 질문하는 direct grilling 스킬 | grilled, challenged, pressure-tested, aggressive questioning을 원할 때 |
+| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>grilling 결과를 CONTEXT.md나 ADR에 기록하는 스킬 | stress-test와 documentation, ADR, glossary, CONTEXT update를 함께 원할 때 |
+| [`grilling`](skills/grilling/SKILL.md)<br>docs write 없이 계획/설계를 pressure-test하는 read-only grilling 스킬 | challenge, pressure-test, red-team, grill, gap finding을 원할 때 |
 | [`domain-modeling`](skills/domain-modeling/SKILL.md)<br>프로젝트의 용어, 도메인 모델, architectural decision을 선명하게 만드는 스킬 | domain term, ubiquitous language, architectural decision을 다듬을 때 |
-| [`codebase-design`](skills/codebase-design/SKILL.md)<br>deep module, 작은 interface, 명확한 seam을 설계하기 위한 코드베이스 설계 스킬 | 더 나은 module interface, seam, testability vocabulary가 필요할 때 |
+| [`codebase-design`](skills/codebase-design/SKILL.md)<br>deep module, 작은 interface, 명확한 boundary를 설계하기 위한 코드베이스 설계 스킬 | 더 나은 module interface, boundary, testability vocabulary가 필요할 때 |
 | [`improve-codebase-architecture`](skills/improve-codebase-architecture/SKILL.md)<br>얕은 모듈과 결합도를 찾아 더 깊은 모듈로 개선할 기회를 찾는 아키텍처 스킬 | deepening opportunity를 찾고 architectural friction을 줄이고 싶을 때 |
-| [`prototype`](skills/prototype/SKILL.md)<br>본 구현 전에 throwaway prototype으로 로직이나 UI 방향을 검증하는 스킬 | approach를 확정하기 전에 throwaway logic/UI prototype을 만들고 싶을 때 |
-| [`to-prd`](skills/to-prd/SKILL.md)<br>대화 내용을 제품 요구사항 문서로 구조화하는 PRD 작성 스킬 | 대화 context를 PRD로 정리하고 싶을 때 |
-| [`to-issues`](skills/to-issues/SKILL.md)<br>계획을 독립적으로 작업 가능한 vertical-slice issue로 나누는 스킬 | plan을 독립적으로 처리 가능한 implementation issue로 나누고 싶을 때 |
-| [`triage`](skills/triage/SKILL.md)<br>issue를 역할과 상태 기반 workflow로 분류하고 다음 행동을 정하는 triage 스킬 | issue를 structured triage workflow로 처리하고 싶을 때 |
-| [`handoff`](skills/handoff/SKILL.md)<br>다음 agent나 다음 세션이 이어받을 수 있도록 맥락을 압축하는 handoff 스킬 | 다른 agent나 session이 이어받을 수 있도록 context를 압축할 때 |
+| [`prototype`](skills/prototype/SKILL.md)<br>logic/state model이나 UI direction을 throwaway local code로 검증하는 스킬 | prototype, mock up, try designs, sanity-check, “let me play with it” 요청 시 |
+| [`to-prd`](skills/to-prd/SKILL.md)<br>PRD draft를 작성하고 프로젝트 PRD workflow에 맞게 준비하는 스킬 | PRD가 필요할 때; tracker publish는 직접 요청이나 repo approval이 있을 때 |
+| [`to-issues`](skills/to-issues/SKILL.md)<br>계획을 issue-ready vertical slice로 나누는 스킬 | implementation ticket/work breakdown이 필요할 때; tracker creation은 직접 요청이나 repo approval이 있을 때 |
+| [`triage`](skills/triage/SKILL.md)<br>issue를 분류하고 다음 행동을 계획하는 triage 스킬 | issue classification, next-action planning, repo-approved triage write가 필요할 때 |
+| [`handoff`](skills/handoff/SKILL.md)<br>다음 agent나 session이 이어받을 수 있도록 context를 압축하는 handoff 스킬 | handoff, session summary, continuation brief, next-agent context 요청 시 |
 | [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>새로운 agent skill을 올바른 구조와 progressive disclosure 방식으로 작성하는 스킬 | agent skill을 새로 만들거나 다듬고 싶을 때 |
 
 ## Attribution: Matt Pocock skills
@@ -220,7 +223,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의 SOLID-informed review lens를 확인합니다.
+5. non-trivial code change 전에는 `jhste-engineering-groundwork`로 scope, boundary, 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 용도로 사용합니다.
@@ -255,7 +258,7 @@ Release acceptance notes는 [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.m
 - 무조건 동의하지 않습니다.
 - local project authority를 덮어쓰지 않습니다.
 - 변경 범위를 작게 유지합니다.
-- SOLID-informed coding discipline을 사용해 responsibility를 이름 붙이고, extension seam, caller contract, interface 크기, concrete dependency 방향을 검토합니다.
+- SOLID-informed coding discipline을 clean-code review lens로 사용해 responsibility를 이름 붙이고, maintenance/failure risk가 있는 extension boundary, caller contract, interface 크기, concrete dependency 방향을 검토합니다.
 - failure를 observable하게 만듭니다.
 - automated guard output을 proof가 아니라 evidence로 취급합니다.
 - non-trivial work를 완료라고 말하기 전에 red-team code review를 수행합니다.

package/README.md

@@ -4,21 +4,21 @@ 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, 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.
+`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, and completion reports should separate current proof, checks not run, and residual risk.
 
 ## What SOLID means here
 
-SOLID is used here as a design review lens, not as an automatic compliance checklist.
+SOLID is used here as a design review lens for concrete maintenance and failure risks, not as an automatic compliance checklist or abstraction trigger.
 
 - **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.
+- **O — Open/Closed:** adding a new variant, provider, or policy should not force repeated edits to core branching when a real extension boundary 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.
+- **D — Dependency Inversion:** high-level policy should not be tightly coupled to concrete DB, API, browser, filesystem, email, payment, or queue effects unless that boundary 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.
 
-Skills are designed to be used automatically when the situation calls for them. For example, when an agent edits API code, it is guided to use the API/database boundary skill; before completion, it is guided to use the red-team review skill. You can also call a skill directly, for example: `use jhste-engineering-judgment to review this change premise`, or `run jhste-red-team-review on this diff`.
+Skills are designed to be used automatically when the situation calls for them. For example, when an agent edits API code, it is guided to use the API/database boundary skill; before completion, it is guided to use the red-team review skill. You can also call a skill directly, for example: `use jhste-engineering-groundwork to review this change premise`, or `run jhste-red-team-review on this diff`.
 
 ## Why install this?
 
@@ -26,7 +26,8 @@ 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, or add abstractions without a real SOLID-informed seam.
+- They mix UI, route/controller, service, database, and side-effect responsibilities in one place, or add abstractions without a real SOLID-informed boundary.
+- They apply broad cleanup or search/replace edits directly from raw search results.
 - 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.
@@ -35,7 +36,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 SOLID-informed review lens
+  check the goal, premise, ownership boundary, data contract, failure path, final behavior predicates, and SOLID-informed review lens
 
 While editing:
   treat repo-local instructions as the authority
@@ -44,13 +45,13 @@ After changing code:
   run a fast changed-file guard when available
 
 Before saying “done”:
-  run a read-only red-team code review
+  run a read-only red-team code review and prefer actual consumer-path proof when feasible
 
 If warnings appear:
   attempt a bounded fix, re-check, and stop instead of looping forever
 ```
 
-The expected result is smaller diffs, clearer SOLID-informed seams, safer API/database code, fewer silent assumptions, and more honest completion reports.
+The expected result is smaller diffs, clearer SOLID-informed boundaries, safer API/database code, fewer silent assumptions, safer cleanup/search-replace behavior, and more honest completion reports grounded in current proof of the changed public behavior.
 
 ## Who should install this?
 
@@ -60,7 +61,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 SOLID-informed coding discipline, 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, cleanup safety, 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.
@@ -83,7 +84,7 @@ Use `npx` when you want a one-off run without a global install. Use `npm install
 The default install uses Normal mode.
 
 - Installs all bundled skills: jhste core skills + vendored workflow skills.
-- Creates `.jhste/profile.yaml` when missing.
+- Creates `.jhste/profile.yaml` when missing; `--force` refreshes generated/managed profiles, while modified profiles require `--force --allow-profile-overwrite`.
 - Adds or refreshes a marker-managed bridge block in `AGENTS.md` or `CLAUDE.md` when project guidance is enabled.
 - Installs an advisory pre-commit hook when safe.
 - Does not modify CI, target `package.json`, lockfiles, or source code.
@@ -119,7 +120,7 @@ To remove managed outputs:
 jhste-skills uninstall --yes --repo /path/to/repo
 ```
 
-`uninstall` removes managed hooks, marker-managed bridge blocks, and manifest-managed skill directories. It does not touch non-managed files. `.jhste/profile.yaml` is removed only when it still matches the generated shape; use `--force-profile` only after reviewing a modified profile.
+`uninstall` removes managed hooks, marker-managed bridge blocks, and manifest-managed skill directories. It does not touch non-managed files. `.jhste/profile.yaml` is removed only when it still matches the current or legacy generated shape; use `--force-profile` only after reviewing a modified profile.
 
 ## Install modes
 
@@ -145,6 +146,8 @@ Custom   - asks effect-oriented questions so you can choose the setup
 - strict mode requires explicit opt-in;
 - bridge blocks use `<!-- jhste-skills:start -->` / `<!-- jhste-skills:end -->` markers;
 - guard output is review evidence, not proof by itself;
+- completion review should prefer actual consumer-path proof when feasible and separate current proof, skipped checks, checks not run, and residual risk;
+- cleanup/search-replace work should classify editable paths separately from protected evidence/history-like paths before writing;
 - guard runtime/config failures must be reported separately from rule violations;
 - install/update/uninstall flows leave non-managed hooks, bridge text, and skill directories untouched.
 
@@ -155,12 +158,12 @@ These are the jhste-authored guardrail skills. They are installed by default as
 | Skill | Use it when | What it helps reduce |
 |---|---|---|
 | [`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 SOLID-informed design risks | Changing module boundaries or app structure | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>A pre-change groundwork skill that verifies goal, premise, scope, boundary, failure path, and final behavior predicates before code edits | Before non-trivial code changes | Blind agreement, scope creep, unverified assumptions, unclear boundaries |
+| [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>A code-quality skill for input validation, observable failure handling, secret-safe logging, and oversized-file review | Touching external input, failure handling, logging, env/config, cleanup/search-replace, or code-quality review paths | Unvalidated input, silent failure, secret logging, unsafe broad cleanup, oversized files |
+| [`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, app structure, side-effect placement, or responsibility splits | 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 |
+| [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>An automation skill for crawler/scraper/worker/scheduler producer-consumer boundaries 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”, missing consumer-path proof, missed null/auth/env/write/API/performance risks |
 
 ## Bundled workflow skills
 
@@ -169,17 +172,17 @@ Normal install also includes 13 workflow skills vendored from Matt Pocock's [`ma
 | Skill | Use it when |
 |---|---|
 | [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>A debugging skill that narrows root cause around a fast pass/fail feedback loop | You need a reproduce → minimise → hypothesise → instrument → fix loop |
-| [`grill-me`](skills/grill-me/SKILL.md)<br>A skill that asks persistent questions until a plan or design has no obvious gaps | You want the agent to question your plan or design until it becomes clear |
-| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>A design-challenge skill that documents domain terms and decisions while questioning the plan | You want project vocabulary and docs/ADRs updated during the questioning process |
-| [`grilling`](skills/grilling/SKILL.md)<br>A general grilling skill for pressure-testing plans and designs before implementation | You need a general plan/design stress-test questioning loop |
+| [`grill-me`](skills/grill-me/SKILL.md)<br>A direct personal grilling skill for aggressively questioning your own plan or reasoning | You ask to be grilled, challenged, pressure-tested, or questioned aggressively |
+| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>A grilling skill that records resulting domain terms and decisions in CONTEXT.md or ADRs | You want stress-testing plus documentation, ADR, glossary, or CONTEXT updates |
+| [`grilling`](skills/grilling/SKILL.md)<br>A general read-only grilling skill for pressure-testing plans and designs before implementation | You ask to challenge, pressure-test, red-team, grill, or find gaps without docs updates |
 | [`domain-modeling`](skills/domain-modeling/SKILL.md)<br>A skill for sharpening project terminology, domain models, and architectural decisions | Refining domain terms, ubiquitous language, or architectural decisions |
-| [`codebase-design`](skills/codebase-design/SKILL.md)<br>A codebase design skill for deep modules, small interfaces, and clear seams | You need better module interface, seam, and testability vocabulary |
+| [`codebase-design`](skills/codebase-design/SKILL.md)<br>A codebase design skill for deep modules, small interfaces, and clear boundaries | You need better module interface, boundary, and testability vocabulary |
 | [`improve-codebase-architecture`](skills/improve-codebase-architecture/SKILL.md)<br>An architecture skill that finds shallow modules and coupling that can be improved into deeper modules | You want to find deepening opportunities and reduce architectural friction |
-| [`prototype`](skills/prototype/SKILL.md)<br>A prototyping skill for validating logic or UI direction with throwaway code before implementation | You want a throwaway logic/UI prototype before committing to an approach |
-| [`to-prd`](skills/to-prd/SKILL.md)<br>A PRD-writing skill that structures conversation context into product requirements | You want to turn conversation context into a PRD |
-| [`to-issues`](skills/to-issues/SKILL.md)<br>A skill that breaks a plan into independently workable vertical-slice issues | You want to split a plan into implementation issues that can be worked independently |
-| [`triage`](skills/triage/SKILL.md)<br>An issue triage skill that classifies issues and decides next actions through a structured workflow | You want issues handled through a structured triage workflow |
-| [`handoff`](skills/handoff/SKILL.md)<br>A handoff skill that compresses context so the next agent or session can continue | You want to hand context to another agent or session |
+| [`prototype`](skills/prototype/SKILL.md)<br>A prototyping skill for validating logic/state models or UI directions with throwaway local code | You ask to prototype, mock up, try designs, sanity-check behavior, or “let me play with it” |
+| [`to-prd`](skills/to-prd/SKILL.md)<br>A PRD-writing skill that drafts requirements and makes them ready for the normal project workflow | You want a PRD; tracker publication happens only when directly requested or repo-approved |
+| [`to-issues`](skills/to-issues/SKILL.md)<br>A skill that breaks a plan into issue-ready vertical slices | You want implementation tickets or work breakdown; tracker creation follows direct request or repo approval |
+| [`triage`](skills/triage/SKILL.md)<br>An issue triage skill that classifies issues and plans next actions through a structured workflow | You want issue classification, next-action planning, or repo-approved triage writes |
+| [`handoff`](skills/handoff/SKILL.md)<br>A handoff skill that compresses context so the next agent or session can continue | You ask for a handoff, session summary, continuation brief, or next-agent context |
 | [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>A skill-writing skill for creating agent skills with the right structure and progressive disclosure | You want to create or refine an agent skill |
 
 ## Attribution: Matt Pocock skills
@@ -220,7 +223,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 the SOLID-informed review lens for changed classes/modules/functions.
+5. Before non-trivial code changes, use `jhste-engineering-groundwork` to check scope, boundary, 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.
@@ -255,11 +258,11 @@ 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.
-- Use SOLID-informed coding discipline: name responsibilities, review extension seams, preserve caller contracts, keep interfaces right-sized, and make concrete dependencies visible.
+- Use SOLID-informed coding discipline as a clean-code review lens: name responsibilities, review extension boundaries, preserve caller contracts, keep interfaces right-sized, and make concrete dependencies visible when they create maintenance or failure risk.
 - Make failures observable.
 - Treat automated guard output as evidence, not proof.
 - Run a red-team code review before calling non-trivial work complete.
 
 Fast agents need guardrails. `jhste-skills` gives them a repo-respecting engineering workflow.
 
-Installed skill directories are tracked with `.jhste-skills-manifest.json`. `--force` refreshes manifest-managed skill copies; overwriting unmanaged differing skill directories still requires the separate `--allow-unmanaged-skill-overwrite` flag after review. `sync` and `update` can also adopt additional known jhste skills into an already managed skills directory so older mixed installs can be reconciled without a manual overwrite flag. Legacy vendored renames are also reconciled during `sync` and `update`, so older managed installs that still have `diagnose` are migrated to `diagnosing-bugs` without leaving duplicate skill directories.
+Installed skill directories are tracked with `.jhste-skills-manifest.json`. `--force` refreshes manifest-managed skill copies and generated/managed profiles; modified profiles need `--force --allow-profile-overwrite`; overwriting unmanaged differing skill directories still requires the separate `--allow-unmanaged-skill-overwrite` flag after review. `sync` and `update` can also adopt additional known jhste skills into an already managed skills directory so older mixed installs can be reconciled without a manual overwrite flag. Legacy managed renames are also reconciled during `sync` and `update`, so older managed installs that still have `diagnose` or `jhste-engineering-judgment` are migrated to `diagnosing-bugs` or `jhste-engineering-groundwork` without leaving duplicate skill directories.