jhste-skills 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## Unreleased
+
+## 0.4.1 - 2026-07-01
+
+### Changed (breaking: personal-use topology reform)
+- Reformed the jhste skill topology so most workflow policy lives in installed skills and `_shared` docs, while `AGENTS.md` and the bridge templates stay minimal and route through `ask-jhste`.
+- Renamed skills: `jhste-engineering-groundwork` → `jhste-preflight`, `jhste-red-team-review` → `jhste-redteam`, `jhste-long-running-work-loop` → `jhste-workstate`.
+- Merged `jhste-code-quality` and `jhste-architecture-review` into `jhste-change-review`, which selects domain review cards; kept `jhste-db-api-boundary` and `jhste-crawler-automation` as thin trigger skills so their safety checks keep firing reliably.
+- Dropped back-compat skill aliases while keeping a migration-only replacement map for `sync`/`update`, so existing managed installs select the new replacement skills before retired directories are pruned.
+- Minimized `AGENTS.md` and both bridge templates to a router pointer, a one-line trigger anchor, and an approval headline; moved the full loop, approval boundaries, and cross-cutting doctrine into `skills/_shared/`.
+
+### Added
+- Added `skills/_shared/core-loop.md` (single source for the common coding loop) and `skills/_shared/side-effect-policy.md` (approval boundaries), plus `skills/_shared/review-cards/` (`code-quality`, `architecture`, `api-db`, `automation`).
+- Added `docs-check` anti-bloat protections: a model-facing description length cap, required shared-doctrine references, a core-loop delegation/no-restate guard, a review-card restate guard, and a retired-skill-name check across skills, `AGENTS.md`, and bridge templates.
+
+### Validation
+- `npm test` passed (12 stages). `jhste-skills guard --scope changed --format text --fail-on warning` passed with 0 warnings/errors.
+
 ## 0.4.0 - 2026-07-01
 
 ### Added

package/README.ja.md

@@ -2,6 +2,8 @@
 
 Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.zh.md) · [日本語](README.ja.md)
 
+> このドキュメントは翻訳版です。正本は [README.md](README.md) であり、個人向けトポロジー改編後は翻訳が遅れる場合があります。
+
 AI コーディングエージェントが、あなたの定義したエンジニアリング基準を一貫して守るための、インストール可能な作業ルールキットです。
 
 `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 です。
@@ -18,7 +20,7 @@ AI コーディングエージェントが、あなたの定義したエンジ
 
 このツールはプロジェクトを乗っ取りません。リポジトリ内の `AGENTS.md`、`CLAUDE.md`、docs が常に権威です。デフォルト設定は advisory モードで、marker-managed 方式で管理され、低リスクで試せるように設計されています。
 
-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`。
+Skills は、必要な状況でエージェントが自動的に使うことを想定しています。たとえば API コードを変更する場合は API/database boundary skill を、完了直前には red-team review skill を使うよう促します。ユーザーが明示的に skill を呼び出すこともできます。例: `use jhste-preflight to review this change premise`、`run jhste-redteam on this diff`。
 
 ## なぜインストールするのか？
 
@@ -176,13 +178,13 @@ Custom   - 効果ベースの質問でセットアップ範囲を選択
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>install/connect/update が既存プロジェクト指示を上書きしないようにする安全セットアップ skill | kit をインストール、またはリポジトリに接続するとき | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
 | [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>適切な jhste skill や workflow を選ぶ user-invoked router | 次にどの jhste skill/workflow を使うべきか迷うとき | Wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
-| [`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-preflight`](skills/jhste-preflight/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-change-review`](skills/jhste-change-review/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-change-review`](skills/jhste-change-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 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 |
-| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>session、待ち状態、durable decision をまたいで作業状態を保つための狭い orchestration skill | 状態喪失が誤り、重複、不安全、または再開困難な作業につながるとき: 複数セッションの作業、繰り返し review、当日または複数日の外部待ち状態、複数 repo への影響、PRD→issue→implementation→review の流れ、durable decision | Lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
+| [`jhste-redteam`](skills/jhste-redteam/SKILL.md)<br>完了前に変更コードを攻撃的に再確認する read-only red-team code review skill | non-trivial code work の完了宣言前 | Premature “done”, missed null/auth/env/write/API/performance risk |
+| [`jhste-workstate`](skills/jhste-workstate/SKILL.md)<br>session、待ち状態、durable decision をまたいで作業状態を保つための狭い orchestration skill | 状態喪失が誤り、重複、不安全、または再開困難な作業につながるとき: 複数セッションの作業、繰り返し review、当日または複数日の外部待ち状態、複数 repo への影響、PRD→issue→implementation→review の流れ、durable decision | Lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
 
 ## Bundled workflow skills
 
@@ -243,8 +245,8 @@ 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-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 の変更はスキップします。
+5. non-trivial code change の前に、`jhste-preflight` で scope、boundary、failure path、data contract、assumption、changed class/module/function の SOLID-informed review lens を確認します。
+6. non-trivial code work の完了宣言前に `jhste-redteam` を使います。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 を防ぐために使います。
 

package/README.ko.md

@@ -2,6 +2,8 @@
 
 Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.zh.md) · [日本語](README.ja.md)
 
+> 이 문서는 번역본입니다. 최신 정본은 [README.md](README.md)이며, 개인용 토폴로지 개편 이후 번역이 늦어질 수 있습니다.
+
 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이며, 완료 보고는 current proof, 실행하지 않은 check, residual risk를 분리해야 합니다.
@@ -18,7 +20,7 @@ AI 코딩 에이전트가 설정한 코딩 기준을 일관되게 따르도록
 
 이 도구는 프로젝트를 장악하지 않습니다. 레포 안의 `AGENTS.md`, `CLAUDE.md`, docs가 항상 우선입니다. 기본 설정은 advisory 모드이며, marker-managed 방식으로 동작하고, 부담 없이 시도할 수 있도록 설계되어 있습니다.
 
-스킬은 필요한 상황에서 에이전트가 자동으로 사용하도록 설계되어 있습니다. 예를 들어 API 코드를 수정하면 API/database boundary 스킬을, 완료 직전에는 red-team review 스킬을 사용하도록 안내합니다. 사용자가 직접 특정 스킬을 호출할 수도 있습니다. 예: `jhste-engineering-groundwork를 사용해서 이 변경 전제를 검토해줘`, `jhste-red-team-review로 이 diff를 리뷰해줘`.
+스킬은 필요한 상황에서 에이전트가 자동으로 사용하도록 설계되어 있습니다. 예를 들어 API 코드를 수정하면 API/database boundary 스킬을, 완료 직전에는 red-team review 스킬을 사용하도록 안내합니다. 사용자가 직접 특정 스킬을 호출할 수도 있습니다. 예: `jhste-preflight를 사용해서 이 변경 전제를 검토해줘`, `jhste-redteam로 이 diff를 리뷰해줘`.
 
 ## 왜 설치해야 하나요?
 
@@ -179,13 +181,13 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>설치, 연결, 업데이트가 기존 프로젝트 지침을 덮어쓰지 않도록 하는 안전 설치 스킬 | kit를 설치하거나 레포에 연결할 때 | unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
 | [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>적절한 jhste skill이나 workflow를 고르는 user-invoked router | 다음에 어떤 jhste skill/workflow를 써야 할지 확실하지 않을 때 | wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
-| [`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-preflight`](skills/jhste-preflight/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-change-review`](skills/jhste-change-review/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-change-review`](skills/jhste-change-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 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 |
-| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>세션, 대기 상태, durable decision 사이의 작업 상태를 보존하는 좁은 orchestration 스킬 | 상태 손실이 잘못된 작업, 중복 작업, unsafe resume, 재개 어려움으로 이어질 수 있을 때: 여러 세션 작업, 반복 리뷰, 당일 또는 다일 외부 대기 상태, 여러 repo 영향, PRD→issue→구현→리뷰 흐름, durable decision | lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
+| [`jhste-redteam`](skills/jhste-redteam/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 |
+| [`jhste-workstate`](skills/jhste-workstate/SKILL.md)<br>세션, 대기 상태, durable decision 사이의 작업 상태를 보존하는 좁은 orchestration 스킬 | 상태 손실이 잘못된 작업, 중복 작업, unsafe resume, 재개 어려움으로 이어질 수 있을 때: 여러 세션 작업, 반복 리뷰, 당일 또는 다일 외부 대기 상태, 여러 repo 영향, PRD→issue→구현→리뷰 흐름, durable decision | lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
 
 ## Bundled workflow skills
 
@@ -246,8 +248,8 @@ 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-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 변경은 건너뜁니다.
+5. non-trivial code change 전에는 `jhste-preflight`로 scope, boundary, failure path, data contract, assumption, changed class/module/function의 SOLID-informed review lens를 확인합니다.
+6. non-trivial code work 완료 선언 전에는 `jhste-redteam`를 사용합니다. 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 용도로 사용합니다.
 

package/README.md

@@ -18,7 +18,7 @@ SOLID is used here as a design review lens for concrete maintenance and failure
 
 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-groundwork 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 `jhste-db-api-boundary`; before completion, it is guided to use `jhste-redteam`. When unsure which skill fits, route through `ask-jhste`. You can also call a skill directly, for example: `use jhste-preflight to review this change premise`, or `run jhste-redteam on this diff`.
 
 ## Why install this?
 
@@ -179,13 +179,12 @@ 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 |
 | [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>A user-invoked router for choosing the right jhste skill or workflow | You are not sure which jhste skill or workflow to use next | Wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
-| [`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-preflight`](skills/jhste-preflight/SKILL.md)<br>Pre-edit groundwork 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-change-review`](skills/jhste-change-review/SKILL.md)<br>Changed-path quality and design review that selects code-quality and architecture review cards from the touched files | After editing non-trivial code, alongside guard | Unvalidated input, silent failure, secret logging, pass-through abstraction, mixed responsibility |
 | [`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 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 |
-| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>A narrow orchestration skill for preserving work state across sessions, wait states, and durable decisions | Losing state could make work wrong, duplicated, unsafe, or hard to resume: multi-session work, recurring reviews, same-day or multi-day external wait states, multiple repos, PRD→issue→implementation→review flows, or durable decisions | Lost context, stale scratchpads, unclear approval boundaries, unsafe resume points |
+| [`jhste-redteam`](skills/jhste-redteam/SKILL.md)<br>A read-only red-team code review skill that 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 |
+| [`jhste-workstate`](skills/jhste-workstate/SKILL.md)<br>A narrow orchestration skill for preserving work state across sessions, wait states, and durable decisions | Losing state could make multi-session, wait-state, or multi-repo work wrong, duplicated, or unsafe | Lost context, stale scratchpads, unclear approval boundaries, unsafe resume points |
 
 ## Bundled workflow skills
 
@@ -246,8 +245,8 @@ 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-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.
+5. Before non-trivial code changes, use `jhste-preflight` to check scope, boundary, failure path, data contract, assumptions, and the SOLID-informed review lens for changed classes/modules/functions.
+6. During and after the change, use `jhste-change-review` on the changed path, and `jhste-redteam` before declaring non-trivial code work complete. 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.
 
@@ -288,6 +287,6 @@ See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptanc
 
 Fast agents need guardrails. `jhste-skills` gives them a repo-respecting engineering workflow.
 
-Skills share cross-cutting doctrine (SOLID lens, evidence discipline, issue-candidate protocol, scope discipline) from `skills/_shared/`. Directories under `skills/` whose name starts with `_` are shared companion resources, not skills: they are excluded from skill listing, selection, and missing-skill checks, but are copied alongside the skills whenever any skill is installed so cross-skill `../_shared/...` references never dangle in the installed artifact.
+Skills share cross-cutting doctrine — the core loop, SOLID lens, evidence discipline, scope discipline, side-effect/approval policy, and issue-candidate protocol — from `skills/_shared/`, plus domain review cards under `skills/_shared/review-cards/`. Each skill references this doctrine instead of restating it, so `ask-jhste` and a minimal bridge can stay small. Directories under `skills/` whose name starts with `_` are shared companion resources, not skills: they are excluded from skill listing, selection, and missing-skill checks, but are copied alongside the skills whenever any skill is installed so cross-skill `../_shared/...` references never dangle in the installed artifact.
 
-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`. Managed copies of retired `write-a-skill` are removed rather than kept as a compatibility fallback.
+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. Retired and renamed skills are pruned rather than exposed as installable aliases during `sync` and `update`: when an old managed name is detected, the matching replacement skill is selected for refresh, then the retired directory is removed. This covers the pre-reform `jhste-engineering-groundwork`, `jhste-code-quality`, `jhste-architecture-review`, `jhste-red-team-review`, and `jhste-long-running-work-loop`, plus the older `diagnose`, `jhste-engineering-judgment`, and `write-a-skill` names.

package/README.zh.md

@@ -2,6 +2,8 @@
 
 Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.zh.md) · [日本語](README.ja.md)
 
+> 本文档为翻译版本。权威来源以 [README.md](README.md) 为准；个人化拓扑改版后，翻译可能滞后。
+
 一套可安装的工作规则工具包，帮助 AI 编程代理稳定遵循你设定的工程标准。
 
 `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 证明。
@@ -18,7 +20,7 @@ Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.
 
 这个工具不会接管你的项目。仓库内的 `AGENTS.md`、`CLAUDE.md` 和 docs 始终是权威来源。默认设置是 advisory 模式，使用 marker-managed 方式管理变更，设计目标是低风险、容易试用。
 
-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`。
+Skills 设计为在需要时由代理自动使用。例如，代理修改 API 代码时会被引导使用 API/database boundary skill；在完成前会被引导使用 red-team review skill。你也可以直接调用某个 skill，例如：`use jhste-preflight to review this change premise`，或 `run jhste-redteam on this diff`。
 
 ## 为什么要安装？
 
@@ -176,13 +178,13 @@ Custom   - 通过面向效果的问题自定义安装范围
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>安全安装 skill，避免 install/connect/update 覆盖现有项目说明 | 安装 kit 或连接仓库时 | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
 | [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>用于选择正确 jhste skill 或 workflow 的 user-invoked router | 不确定下一步该用哪个 jhste skill/workflow 时 | Wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
-| [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>pre-change groundwork skill，在改代码前验证目标、前提、scope、boundary 和 failure path | 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 的架构 review skill | 修改 module boundary、app structure、side-effect placement 或 responsibility split 时 | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-preflight`](skills/jhste-preflight/SKILL.md)<br>pre-change groundwork skill，在改代码前验证目标、前提、scope、boundary 和 failure path | non-trivial code change 前 | Blind agreement, scope creep, unverified assumption, unclear boundary |
+| [`jhste-change-review`](skills/jhste-change-review/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-change-review`](skills/jhste-change-review/SKILL.md)<br>检查 module boundary、side-effect placement 和 SOLID-informed design risk 的架构 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 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 |
-| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>用于在 session、等待状态和 durable decision 间保留工作状态的窄 orchestration skill | 状态丢失可能导致错误、重复、不安全或难以恢复的工作时：多会话工作、重复 review、当天或多天外部等待状态、多 repo 影响、PRD→issue→implementation→review 流程或 durable decision | Lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
+| [`jhste-redteam`](skills/jhste-redteam/SKILL.md)<br>read-only red-team code review skill，在完成前主动攻击性复查变更代码 | non-trivial code work 完成声明前 | Premature “done”, missed null/auth/env/write/API/performance risk |
+| [`jhste-workstate`](skills/jhste-workstate/SKILL.md)<br>用于在 session、等待状态和 durable decision 间保留工作状态的窄 orchestration skill | 状态丢失可能导致错误、重复、不安全或难以恢复的工作时：多会话工作、重复 review、当天或多天外部等待状态、多 repo 影响、PRD→issue→implementation→review 流程或 durable decision | Lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
 
 ## Bundled workflow skills
 
@@ -243,8 +245,8 @@ 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-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 变更。
+5. non-trivial code change 前，用 `jhste-preflight` 检查 scope、boundary、failure path、data contract、assumption，以及 changed class/module/function 的 SOLID-informed review lens。
+6. non-trivial code work 完成声明前，使用 `jhste-redteam`。跳过 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。
 

package/adapters/codex/README.md

@@ -6,22 +6,12 @@ Bridge block:
 
 ```md
 ## Agent skills
-This repo uses jhste skills as shared guidance.
+This repo uses jhste skills as installed workflow guidance.
 Repo-local instructions in this file remain authoritative.
-File, repo, command, issue, PR, or other external side effects are allowed when the user directly requested that workflow or repo-local standing approval covers it.
-Ask for destructive, irreversible, ambiguous, production, secret, cost-bearing, broad existing-item, or out-of-scope changes.
-For reversible in-scope choices, make a reasonable assumption, proceed, and report it in the final summary.
+Use `ask-jhste` as the router for jhste coding, review, setup, and workstate workflows; detailed policy lives in the installed skills and their `_shared` docs, not this block.
+For non-trivial code changes: run `jhste-preflight` before editing, `jhste-skills guard --scope changed` and `jhste-change-review` on the changed path, then `jhste-redteam` before completion.
+Before destructive, irreversible, production, secret-bearing, cost-bearing, commit, push, release, publish, or broad out-of-scope actions, follow repo-local instructions and the side-effect policy in the installed skills directory's `_shared/side-effect-policy.md`.
 See `.jhste/profile.yaml` for local skill preferences.
-Before non-trivial code changes, use the `jhste-engineering-groundwork` skill to check scope, boundaries, failure paths, final behavior predicates, 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 clean-code review lens for concrete failure modes, not a compliance claim or automatic abstraction trigger; 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; completion review should separate current proof, skipped/not-run checks, consumer-path proof when feasible, and residual risk.
-If guard or red-team review reports new warnings on changed files, attempt a bounded fix before declaring completion, then rerun guard. Do not commit automatically.
-Before declaring non-trivial code work complete, use the `jhste-red-team-review` skill.
-Skip red-team review for docs-only, comment-only, formatting-only, or trivial rename-only changes.
-Do not enter an unbounded fix/review loop; stop after at most two fix + re-review cycles and report remaining risks.
 ```
 
 Default install copies skills to a kit-managed skill directory and does not delete or rewrite existing Codex skills.

package/cli/install-actions/skill-migrations.mjs

@@ -0,0 +1,22 @@
+// Personal-use topology reform keeps no back-compat aliases for direct skill
+// selection: retired names are not installable aliases. `sync`/`update` still use
+// this migration-only replacement map so existing managed installs select the new
+// workflow skills before pruning old directories.
+export const LEGACY_SKILL_RENAMES = Object.freeze({});
+
+export const RETIRED_SKILL_REPLACEMENTS = Object.freeze({
+  'write-a-skill': ['writing-great-skills'],
+  diagnose: ['diagnosing-bugs'],
+  'jhste-engineering-judgment': ['jhste-preflight'],
+  'jhste-engineering-groundwork': ['jhste-preflight'],
+  'jhste-code-quality': ['jhste-change-review'],
+  'jhste-architecture-review': ['jhste-change-review'],
+  'jhste-red-team-review': ['jhste-redteam'],
+  'jhste-long-running-work-loop': ['jhste-workstate'],
+});
+
+export const DELETED_MANAGED_SKILLS = Object.freeze(Object.keys(RETIRED_SKILL_REPLACEMENTS));
+
+export function canonicalSkillName(name) {
+  return LEGACY_SKILL_RENAMES[name] || name;
+}

package/cli/install-actions/skills.mjs

@@ -2,19 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { directoryDigest, ensureDir, KIT_ROOT, listSharedResourceNames, listSkillDirectories, nowIso } from '../shared.mjs';
 import { readJsonFile, validateJsonObject, validateStringArray } from '../json-file.mjs';
+import { DELETED_MANAGED_SKILLS, LEGACY_SKILL_RENAMES, canonicalSkillName } from './skill-migrations.mjs';
 
 export const SKILLS_MANIFEST_NAME = '.jhste-skills-manifest.json';
 export const MANIFEST_MANAGED_BY = 'jhste-skills';
-export const LEGACY_SKILL_RENAMES = Object.freeze({
-  diagnose: 'diagnosing-bugs',
-  'jhste-engineering-judgment': 'jhste-engineering-groundwork',
-});
-
-export const DELETED_MANAGED_SKILLS = Object.freeze(['write-a-skill']);
-
-export function canonicalSkillName(name) {
-  return LEGACY_SKILL_RENAMES[name] || name;
-}
 
 function vendoredSkillNames() {
   const allowlistPath = path.join(KIT_ROOT, 'vendor', 'matt-pocock', 'allowlist.json');

package/cli/shared/templates.mjs

@@ -7,22 +7,12 @@ export const BRIDGE_START = '<!-- jhste-skills:start -->';
 export const BRIDGE_END = '<!-- jhste-skills:end -->';
 
 export const BRIDGE_BLOCK = `## Agent skills
-This repo uses jhste skills as shared guidance.
+This repo uses jhste skills as installed workflow guidance.
 Repo-local instructions in this file remain authoritative.
-File, repo, command, issue, PR, or other external side effects are allowed when the user directly requested that workflow or repo-local standing approval covers it.
-Ask for destructive, irreversible, ambiguous, production, secret, cost-bearing, broad existing-item, or out-of-scope changes.
-For reversible in-scope choices, make a reasonable assumption, proceed, and report it in the final summary.
-See \`.jhste/profile.yaml\` for local skill preferences.
-Before non-trivial code changes, use the \`jhste-engineering-groundwork\` skill to check scope, boundaries, failure paths, final behavior predicates, 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 clean-code review lens for concrete failure modes, not a compliance claim or automatic abstraction trigger; 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; completion review should separate current proof, skipped/not-run checks, consumer-path proof when feasible, and residual risk.
-If guard or red-team review reports new warnings on changed files, attempt a bounded fix before declaring completion, then rerun guard. Do not commit automatically.
-Before declaring non-trivial code work complete, use the \`jhste-red-team-review\` skill.
-Skip red-team review for docs-only, comment-only, formatting-only, or trivial rename-only changes.
-Do not enter an unbounded fix/review loop; stop after at most two fix + re-review cycles and report remaining risks.`;
+Use \`ask-jhste\` as the router for jhste coding, review, setup, and workstate workflows; detailed policy lives in the installed skills and their \`_shared\` docs, not this block.
+For non-trivial code changes: run \`jhste-preflight\` before editing, \`jhste-skills guard --scope changed\` and \`jhste-change-review\` on the changed path, then \`jhste-redteam\` before completion.
+Before destructive, irreversible, production, secret-bearing, cost-bearing, commit, push, release, publish, or broad out-of-scope actions, follow repo-local instructions and the side-effect policy in the installed skills directory's \`_shared/side-effect-policy.md\`.
+See \`.jhste/profile.yaml\` for local skill preferences.`;
 
 export const MANAGED_BRIDGE_BLOCK = `${BRIDGE_START}\n${BRIDGE_BLOCK}\n${BRIDGE_END}`;
 
@@ -34,16 +24,9 @@ export const MANAGED_BRIDGE_BLOCK = `${BRIDGE_START}\n${BRIDGE_BLOCK}\n${BRIDGE_
 export const GLOBAL_BRIDGE_BLOCK = `## Agent skills (jhste, global)
 jhste skills are installed globally as shared engineering guidance for this agent.
 Repo-local AGENTS.md, CLAUDE.md, and docs remain authoritative when present.
-File, repo, command, issue, PR, or other external side effects are allowed when the user directly requested that workflow or repo-local standing approval covers it.
-Ask for destructive, irreversible, ambiguous, production, secret, cost-bearing, broad existing-item, or out-of-scope changes.
-For reversible in-scope choices, make a reasonable assumption, proceed, and report it in the final summary.
-Before non-trivial code changes, use the \`jhste-engineering-groundwork\` skill to check scope, boundaries, failure paths, final behavior predicates, 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 clean-code review lens for concrete failure modes, not a compliance claim or automatic abstraction trigger; guard findings are review candidates, not proof.
-After code changes, run \`jhste-skills guard --scope changed --format text --fail-on warning\` when available; treat guard output as advisory review evidence, not proof.
-Before declaring non-trivial code work complete, use the \`jhste-red-team-review\` skill.
-Skip red-team review for docs-only, comment-only, formatting-only, or trivial rename-only changes.
-Do not enter an unbounded fix/review loop; stop after at most two fix + re-review cycles and report remaining risks.`;
+Use \`ask-jhste\` as the router for jhste coding, review, setup, and workstate workflows; detailed policy lives in the installed skills and their \`_shared\` docs.
+For non-trivial code changes: run \`jhste-preflight\` before editing, \`jhste-skills guard --scope changed\` (advisory) and \`jhste-change-review\` on the changed path, then \`jhste-redteam\` before completion.
+Before destructive, irreversible, production, secret-bearing, cost-bearing, commit, push, release, publish, or broad out-of-scope actions, follow repo-local instructions and the side-effect policy in the installed skills directory's \`_shared/side-effect-policy.md\`.`;
 
 export const MANAGED_GLOBAL_BRIDGE_BLOCK = `${BRIDGE_START}\n${GLOBAL_BRIDGE_BLOCK}\n${BRIDGE_END}`;
 

package/cli/sync-core.mjs

@@ -14,7 +14,7 @@ import {
   readIfExists,
 } from './shared.mjs';
 import { applyPlan, preflightPlan, printApplyResult } from './install-actions.mjs';
-import { LEGACY_SKILL_RENAMES, canonicalSkillName } from './install-actions/skills.mjs';
+import { LEGACY_SKILL_RENAMES, RETIRED_SKILL_REPLACEMENTS, canonicalSkillName } from './install-actions/skill-migrations.mjs';
 import { gitHooksDir, HOOKS, isManagedHook } from './hook-utils.mjs';
 import { printConfigErrors, printPlanSummary } from './install-flow/output.mjs';
 import { readJsonFile, validateStringArray } from './json-file.mjs';
@@ -113,11 +113,14 @@ function sourceSkillNames() {
 function detectInstalledSkillNames(skillsDir) {
   const known = new Set(sourceSkillNames());
   const detected = new Set();
+  function addKnown(name) {
+    if (known.has(name)) detected.add(name);
+  }
   for (const name of listDirectories(skillsDir)) {
     const canonicalName = canonicalSkillName(name);
-    if (known.has(canonicalName) || Object.prototype.hasOwnProperty.call(LEGACY_SKILL_RENAMES, name)) {
-      detected.add(canonicalName);
-    }
+    addKnown(canonicalName);
+    if (Object.prototype.hasOwnProperty.call(LEGACY_SKILL_RENAMES, name)) addKnown(canonicalName);
+    for (const replacementName of RETIRED_SKILL_REPLACEMENTS[name] || []) addKnown(replacementName);
   }
   return [...detected];
 }

package/docs/ACCEPTANCE_CHECK.md

@@ -9,16 +9,17 @@ Implemented directories: `skills/`, `rules/`, `packs/`, `adapters/`, `cli/`, `ve
 Core skills implemented:
 
 - `skills/setup/SKILL.md`
-- `skills/jhste-engineering-groundwork/SKILL.md`
-- `skills/jhste-code-quality/SKILL.md`
-- `skills/jhste-architecture-review/SKILL.md`
+- `skills/ask-jhste/SKILL.md`
+- `skills/jhste-preflight/SKILL.md`
+- `skills/jhste-change-review/SKILL.md`
 - `skills/jhste-db-api-boundary/SKILL.md`
 - `skills/jhste-crawler-automation/SKILL.md`
-- `skills/jhste-red-team-review/SKILL.md`
+- `skills/jhste-redteam/SKILL.md`
+- `skills/jhste-workstate/SKILL.md`
 
 ## Fast setup
 
-`cli/install.mjs` implements mode-based setup (`Minimal`, `Normal`, `Full`, `Custom`), creates `.jhste/profile.yaml` when project connection is enabled, keeps mode advisory by default, asks for a source-file line limit in interactive repo setup, defaults non-interactive setup to a 300-line advisory policy, uses marker-managed bridge blocks idempotently, and does not touch target CI, `package.json`, lockfiles, or source code. Skill installs write a managed manifest with digests and refuse unmanaged differing overwrites unless a separate explicit override is supplied. Hook automation installs a managed advisory pre-commit hook in Normal and advisory pre-commit/pre-push hooks in Full, with `--skip-hooks` as opt-out and blocking mode as explicit opt-in. `cli/connect.mjs` connects additional git repositories to an existing install without silently mutating global skills unless `--install-missing` is explicit. Installed bridge/profile guidance points agents at `jhste-engineering-groundwork` before non-trivial code changes and `jhste-red-team-review` before non-trivial code work is declared complete.
+`cli/install.mjs` implements mode-based setup (`Minimal`, `Normal`, `Full`, `Custom`), creates `.jhste/profile.yaml` when project connection is enabled, keeps mode advisory by default, asks for a source-file line limit in interactive repo setup, defaults non-interactive setup to a 300-line advisory policy, uses marker-managed bridge blocks idempotently, and does not touch target CI, `package.json`, lockfiles, or source code. Skill installs write a managed manifest with digests and refuse unmanaged differing overwrites unless a separate explicit override is supplied. Hook automation installs a managed advisory pre-commit hook in Normal and advisory pre-commit/pre-push hooks in Full, with `--skip-hooks` as opt-out and blocking mode as explicit opt-in. `cli/connect.mjs` connects additional git repositories to an existing install without silently mutating global skills unless `--install-missing` is explicit. Installed bridge/profile guidance routes agents through `ask-jhste` and points at `jhste-preflight` before non-trivial code changes and `jhste-redteam` before non-trivial code work is declared complete.
 
 ## Deep scan
 
@@ -41,7 +42,7 @@ Rule modes are documented in `docs/RULES.md`, example profile defaults to adviso
 Skill guidance now requires these completion and safety properties:
 
 - Red-team review requires current proof and separates checks run, consumer-path proof when feasible, checks not run, checks intentionally skipped, and residual risk.
-- Engineering groundwork records final behavior predicates for non-trivial code changes.
+- Preflight (`jhste-preflight`) records final behavior predicates for non-trivial code changes.
 - Cleanup/search-replace guidance requires editable `EDIT_PATHS` vs protected `PROTECTED_PATHS` classification before writes.
 - Grilling remains read-only by default; docs or tracker writes route to explicit writing workflows such as `grill-with-docs`, `domain-modeling`, `to-issues`, or `triage`.
 - Architecture improvement defaults to Markdown reporting, with HTML visual reports only when requested or materially useful.
@@ -64,7 +65,7 @@ Record actual command output in release notes before publishing a release.
 
 Release gates include dependency-free syntax checking, a first-run `install -> deep-scan -> tune --yes -> guard` smoke flow, `npm pack --dry-run` contents checks, and packed-tarball bin execution in a fresh temp consumer. These gates are not part of commit-time hooks.
 
-- Verify `sync`/`update` migrates older managed renames without leaving duplicate directories, including `diagnose` → `diagnosing-bugs`, `jhste-engineering-judgment` → `jhste-engineering-groundwork`, and managed removal of retired `write-a-skill`.
+- Verify `sync`/`update` prunes managed copies of retired or renamed skills without leaving duplicate directories, including the pre-reform jhste skills and the older `diagnose`, `jhste-engineering-judgment`, and `write-a-skill` names.
 
 ## npm trusted publishing
 

package/docs/CLI.md

@@ -44,7 +44,7 @@ Safety and compatibility:
 - existing profile is created when missing; generated/managed profiles can be refreshed with `--force`; modified profiles are preserved unless `--force --allow-profile-overwrite` is explicit; user source, CI, package files, lockfiles, non-managed hooks, and unmanaged differing skill directories are not overwritten; unmanaged skill overwrite requires `--allow-unmanaged-skill-overwrite` after review;
 - `AGENTS.md` and `CLAUDE.md` bridge blocks use `<!-- jhste-skills:start -->` / `<!-- jhste-skills:end -->` markers; only that managed block is updated on later runs;
 - CI, target `package.json`, and lockfiles are not changed. A local advisory pre-commit hook is installed by default in Normal, unless `--skip-hooks` is passed or an existing non-managed hook prevents safe install;
-- installed bridge/profile guidance tells agents to record final behavior predicates during groundwork and run `jhste-red-team-review` before declaring non-trivial code work complete, while skipping docs-only, comment-only, formatting-only, and trivial rename-only changes.
+- installed bridge/profile guidance tells agents to record final behavior predicates during `jhste-preflight` and run `jhste-redteam` before declaring non-trivial code work complete, while skipping docs-only, comment-only, formatting-only, and trivial rename-only changes.
 - guard text output includes short `Meaning` and `Next` guidance for warning/info findings so users can understand and address candidates from hook output. Guard output remains review evidence, not completion proof; completion reports should separate current proof, consumer-path proof when feasible, skipped or not-run checks, and residual risk.
 
 Repo detection:

package/docs/CONFLICT_RESOLUTION.md

@@ -36,22 +36,12 @@ Managed block content:
 ```md
 <!-- jhste-skills:start -->
 ## Agent skills
-This repo uses jhste skills as shared guidance.
+This repo uses jhste skills as installed workflow guidance.
 Repo-local instructions in this file remain authoritative.
-File, repo, command, issue, PR, or other external side effects are allowed when the user directly requested that workflow or repo-local standing approval covers it.
-Ask for destructive, irreversible, ambiguous, production, secret, cost-bearing, broad existing-item, or out-of-scope changes.
-For reversible in-scope choices, make a reasonable assumption, proceed, and report it in the final summary.
+Use `ask-jhste` as the router for jhste coding, review, setup, and workstate workflows; detailed policy lives in the installed skills and their `_shared` docs, not this block.
+For non-trivial code changes: run `jhste-preflight` before editing, `jhste-skills guard --scope changed` and `jhste-change-review` on the changed path, then `jhste-redteam` before completion.
+Before destructive, irreversible, production, secret-bearing, cost-bearing, commit, push, release, publish, or broad out-of-scope actions, follow repo-local instructions and the side-effect policy in the installed skills directory's `_shared/side-effect-policy.md`.
 See `.jhste/profile.yaml` for local skill preferences.
-Before non-trivial code changes, use the `jhste-engineering-groundwork` skill to check scope, boundaries, failure paths, final behavior predicates, 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 clean-code review lens for concrete failure modes, not a compliance claim or automatic abstraction trigger; 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; completion review should separate current proof, skipped/not-run checks, consumer-path proof when feasible, and residual risk.
-If guard or red-team review reports new warnings on changed files, attempt a bounded fix before declaring completion, then rerun guard. Do not commit automatically.
-Before declaring non-trivial code work complete, use the `jhste-red-team-review` skill.
-Skip red-team review for docs-only, comment-only, formatting-only, or trivial rename-only changes.
-Do not enter an unbounded fix/review loop; stop after at most two fix + re-review cycles and report remaining risks.
 <!-- jhste-skills:end -->
 ```
 
@@ -61,4 +51,4 @@ If a similar section exists, the installer prints the snippet instead of editing
 
 Managed hooks are identified by the jhste-skills hook markers. Existing non-managed hooks are never overwritten, including in `Full` mode and with `--force`. Full may install multiple hook targets, but each target is reported separately as installed, refreshed, skipped because non-managed, or failed.
 
-Legacy managed renames are treated differently from unmanaged conflicts. During `sync` and `update`, older managed `diagnose` and `jhste-engineering-judgment` installs are migrated to `diagnosing-bugs` and `jhste-engineering-groundwork` automatically, and managed copies of retired `write-a-skill` are removed, so the skills directory does not keep duplicate or removed names.
+Retired and renamed skills are pruned, not aliased. During `sync` and `update`, managed copies of skills the kit no longer ships — including the pre-reform `jhste-engineering-groundwork`, `jhste-code-quality`, `jhste-architecture-review`, `jhste-red-team-review`, and `jhste-long-running-work-loop`, plus the older `diagnose`, `jhste-engineering-judgment`, and `write-a-skill` names — are removed, and the current skills install fresh, so the skills directory does not keep duplicate or removed names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jhste-skills",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Installable engineering guardrails and workflow skills for AI coding agents.",
   "type": "module",
   "license": "MIT",

package/scripts/docs-check/bridge-and-retired.mjs

@@ -0,0 +1,35 @@
+import path from 'node:path';
+
+export function assertBridgeAndRetiredNames({ root, read, walk, relPath, fail, retiredSkillNames, fullLoopSentinels }) {
+  const bridgeText = 'Repo-local instructions in this file remain authoritative.';
+  for (const rel of ['adapters/codex/README.md', 'docs/CONFLICT_RESOLUTION.md', 'cli/shared/templates.mjs']) {
+    const text = read(rel);
+    if (!text.includes(bridgeText)) fail(`${rel} must include authoritative repo-local bridge wording`);
+    for (const requiredText of ['ask-jhste', 'jhste-preflight', 'jhste-redteam']) {
+      if (!text.includes(requiredText)) fail(`${rel} must mention ${requiredText} in shared workflow guidance`);
+    }
+    if (/approval boundary in \\?`_shared\/side-effect-policy\.md\\?`/.test(text)) fail(`${rel} must not point bridge readers at a bare _shared side-effect policy path`);
+    if (!text.includes("installed skills directory's") || !text.includes('_shared/side-effect-policy.md')) fail(`${rel} must point bridge readers at the installed skills directory side-effect policy`);
+    for (const sentinel of fullLoopSentinels) {
+      if (text.includes(sentinel)) fail(`${rel} bridge must delegate the core loop to skills/_shared/core-loop.md, not restate it ("${sentinel}")`);
+    }
+  }
+
+  const rootAgents = read('AGENTS.md');
+  for (const requiredText of ['ask-jhste', 'jhste-preflight', 'jhste-redteam', 'side-effect-policy.md']) {
+    if (!rootAgents.includes(requiredText)) fail(`AGENTS.md must mention ${requiredText}`);
+  }
+  if (/approval boundary in `_shared\/side-effect-policy\.md`/.test(rootAgents)) fail('AGENTS.md must not point bridge readers at a bare _shared side-effect policy path');
+  for (const sentinel of fullLoopSentinels) {
+    if (rootAgents.includes(sentinel)) fail(`AGENTS.md must delegate the core loop to the installed skills, not restate it ("${sentinel}")`);
+  }
+
+  const retiredNameSurfaces = walk(path.join(root, 'skills'), (file) => file.endsWith('.md')).map(relPath);
+  retiredNameSurfaces.push('AGENTS.md', 'cli/shared/templates.mjs');
+  for (const rel of retiredNameSurfaces) {
+    const text = read(rel);
+    for (const oldName of retiredSkillNames) {
+      if (text.includes(oldName)) fail(`${rel} references retired skill name ${oldName}; update it to the current topology`);
+    }
+  }
+}