jhste-skills 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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

package/README.ko.md

@@ -4,11 +4,11 @@ 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 boundary가 필요한지 검토합니다.
@@ -27,6 +27,7 @@ AI 코딩 에이전트는 빠르지만, 반복적으로 비슷한 방식으로
 - 불명확한 요구사항이나 틀린 전제를 조용히 받아들입니다.
 - 도와주려다가 작업 범위를 과하게 넓힙니다.
 - 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 boundary, 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 boundary, 더 안전한 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하길 기대한다면 맞지 않을 수 있습니다.
@@ -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,12 +158,12 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 | Skill | 언제 쓰나 | 무엇을 줄여주나 |
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>설치, 연결, 업데이트가 기존 프로젝트 지침을 덮어쓰지 않도록 하는 안전 설치 스킬 | kit를 설치하거나 레포에 연결할 때 | unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
-| [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>코드 변경 전 목표, 전제, scope, boundary, failure path를 검증하는 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, code-quality review path를 만질 때 | unvalidated input, silent failure, secret logging, oversized file |
+| [`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 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”, 놓치기 쉬운 null/auth/env/write/API/performance risk |
+| [`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
 
@@ -255,7 +258,7 @@ Release acceptance notes는 [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.m
 - 무조건 동의하지 않습니다.
 - local project authority를 덮어쓰지 않습니다.
 - 변경 범위를 작게 유지합니다.
-- SOLID-informed coding discipline을 사용해 responsibility를 이름 붙이고, extension boundary, 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,11 +4,11 @@ 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 boundary would be safer.
@@ -27,6 +27,7 @@ AI coding agents are fast, but they fail in predictable ways:
 - They silently accept unclear requirements or incorrect premises.
 - They expand the scope while trying to be helpful.
 - They mix UI, route/controller, service, database, and side-effect responsibilities in one place, 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 boundary, 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 boundaries, 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.
@@ -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-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>A pre-change groundwork skill that verifies goal, premise, scope, boundary, and failure path 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, or code-quality review paths | Unvalidated input, silent failure, secret logging, oversized files |
+| [`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 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”, missed null/auth/env/write/API/performance risks |
+| [`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
 
@@ -255,7 +258,7 @@ See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptanc
 - Do not agree blindly.
 - Do not overwrite local project authority.
 - Keep changes scoped.
-- Use SOLID-informed coding discipline: name responsibilities, review extension boundaries, 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.

package/adapters/codex/README.md

@@ -12,12 +12,12 @@ File, repo, command, issue, PR, or other external side effects are allowed when
 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, and assumptions.
+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 review lens, not a compliance claim; guard findings are review candidates, not proof.
+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.
+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.

package/cli/shared/templates.mjs

@@ -13,12 +13,12 @@ File, repo, command, issue, PR, or other external side effects are allowed when
 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, and assumptions.
+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 review lens, not a compliance claim; guard findings are review candidates, not proof.
+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.
+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.

package/docs/ACCEPTANCE_CHECK.md

@@ -36,6 +36,17 @@ Rule modes are documented in `docs/RULES.md`, example profile defaults to adviso
 
 `docs/CONFLICT_RESOLUTION.md` and installer behavior preserve existing repo instructions, skip existing differing profiles/skills by default, make bridge insertion marker-managed and idempotent, refuse to overwrite non-managed hooks even in Full mode or with `--force`, refuse unmanaged skill-directory overwrites without `--allow-unmanaged-skill-overwrite`, and let `sync`/`update` adopt additional known jhste skills into an already managed skills directory.
 
+## Guardrail behavior updates
+
+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.
+- 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.
+- SOLID-informed coding discipline remains a clean-code review lens for concrete failure modes, not automatic abstraction pressure.
+
 ## Verification commands
 
 ```bash

package/docs/CLI.md

@@ -44,8 +44,8 @@ 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 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.
-- guard text output includes short `Meaning` and `Next` guidance for warning/info findings so users can understand and address candidates from hook output.
+- 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.
+- 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

@@ -42,12 +42,12 @@ File, repo, command, issue, PR, or other external side effects are allowed when
 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, and assumptions.
+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 review lens, not a compliance claim; guard findings are review candidates, not proof.
+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.
+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.

package/docs/PUBLIC_SAFETY.md

@@ -12,7 +12,9 @@ Before release, confirm:
 - deep scan is optional and does not modify source code;
 - recommended profile is not applied without user approval;
 - strict mode requires explicit opt-in;
-- Matt skills have allowlist, source lock, and license attribution.
+- Matt skills have allowlist, source lock, and license attribution;
+- cleanup/search-replace guidance does not encourage broad writes from raw search results;
+- protected docs/examples/tests/fixtures/snapshots/generated outputs/reports/diffs/patches/history-like surfaces remain report-only unless explicitly targeted.
 
 Optional local private patterns can be placed in `.jhste/private-safety-patterns.txt` (one literal fragment per line, `#` comments allowed). The file is ignored and skipped by the checker; matches are reported without echoing the private fragment. If the file is absent, generic secret-like filename, token, credential, and local-path checks still run.
 

package/docs/RULES.md

@@ -59,9 +59,9 @@ Repo-specific policy should stay in repo-local guards or `.jhste/profile.yaml` d
 Shared guidance now distinguishes two review stages:
 
 - commit-time guard: fast, read-only, and safe for hooks;
-- completion-time red-team review: a read-only red-team pass before declaring non-trivial code work complete.
+- completion-time red-team review: a read-only red-team pass before declaring non-trivial code work complete, with current proof, actual consumer-path proof when feasible, skipped/not-run checks, and residual risk separated.
 
-Red-team review should run for non-trivial code changes and may be skipped for docs-only, comment-only, formatting-only, and trivial rename-only changes. Agents should stop after at most two fix + re-review cycles and report residual risks instead of looping indefinitely.
+Red-team review should run for non-trivial code changes and may be skipped for docs-only, comment-only, formatting-only, and trivial rename-only changes. Agents should prefer the actual public entrypoint, CLI, UI route, worker path, service entrypoint, fresh-client flow, or documented acceptance path when feasible. They should stop after at most two fix + re-review cycles and report residual risks instead of looping indefinitely.
 
 The first shared finding families behind red-team review are:
 
@@ -93,7 +93,7 @@ SRP is not a "one function per file" or "smallest possible file" rule. A split i
 
 ## SOLID-informed design advisory
 
-SOLID is a coding discipline and review lens in this kit, not an automated compliance standard. `single_responsibility_advisory` remains the existing built-in SRP rule and is the S in the SOLID review model; do not rename it to a broader rule id just for branding.
+SOLID is a coding discipline and clean-code review lens for concrete maintenance and failure risks in this kit, not an automated compliance standard or abstraction trigger. `single_responsibility_advisory` remains the existing built-in SRP rule and is the S in the SOLID review model; do not rename it to a broader rule id just for branding.
 
 The added SOLID advisory families are intentionally split by principle so messages stay actionable:
 
@@ -102,7 +102,7 @@ The added SOLID advisory families are intentionally split by principle so messag
 - `interface_segregation_advisory` (ISP-informed) is metadata-only and human-review required. Review broad config/interface/props bags, but keep cohesive public contracts together when they are read and changed together.
 - `dependency_boundary_advisory` (DIP-informed) has a low-confidence guard candidate, `solid.dip.concrete_side_effect_dependency`, for concrete DB/API/filesystem/payment/notification/queue/browser dependencies in policy-like paths. Treat it as a prompt to inspect the boundary; an intentionally local dependency can be acceptable when visible and tested.
 
-Do not describe these rules as `SOLID compliance`, `SOLID rule enforcement`, or a `SOLID violation` detector. Guard findings are review candidates, not proof, and metadata-only SOLID rules provide no automated guard coverage.
+Do not describe these rules as `SOLID compliance`, `SOLID rule enforcement`, or a `SOLID violation` detector. Guard findings are review candidates, not proof, metadata-only SOLID rules provide no automated guard coverage, and abstractions should require a concrete caller, variant, side-effect boundary, testability problem, or maintenance failure mode.
 
 ## Restricted profile format
 

package/package.json

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

package/scripts/docs-check-data.mjs

@@ -67,11 +67,14 @@ export const required = [
 ];
 
 export const recipeRequirements = {
-  'skills/jhste-code-quality/references/code-quality.md': ['React client loader/hook/adapter/view', 'Mutation write safety', 'Import/ops script'],
+  'skills/jhste-code-quality/references/code-quality.md': ['React client loader/hook/adapter/view', 'Mutation write safety', 'Import/ops script', 'EDIT_PATHS', 'PROTECTED_PATHS'],
   'skills/jhste-architecture-review/references/architecture-review.md': ['Next.js or API route split', 'React client path split', 'Generic module or function split', 'Function responsibility split', 'Adjacent-code scope limit'],
   'skills/jhste-db-api-boundary/references/db-api-boundary.md': ['DB row to domain/public DTO', 'Scoped mutation'],
   'skills/jhste-crawler-automation/references/crawler-automation.md': ['Producer / consumer recipe'],
-  'skills/jhste-engineering-groundwork/SKILL.md': ['Senior-quality pre-edit gate', 'partial-failure or rollback path', 'Adjacent-code scope creep', 'Changed responsibility', 'bounded fix'],
-  'skills/jhste-red-team-review/SKILL.md': ['Severity rubric and path tracing', 'changed execution path', 'changes required'],
-  'skills/jhste-red-team-review/references/red-team-review.md': ['Severity rubric', 'Trace at least one changed execution path', 'one main reason to change'],
+  'skills/grilling/SKILL.md': ['read-only by default'],
+  'skills/grill-me/SKILL.md': ['read-only by default'],
+  'skills/improve-codebase-architecture/SKILL.md': ['Default to a concise Markdown architecture review', 'HTML/Tailwind/Mermaid report only when requested'],
+  'skills/jhste-engineering-groundwork/SKILL.md': ['Senior-quality pre-edit gate', 'partial-failure or rollback path', 'Adjacent-code scope creep', 'Changed responsibility', 'bounded fix', 'Final behavior predicates'],
+  'skills/jhste-red-team-review/SKILL.md': ['Severity rubric and path tracing', 'changed execution path', 'changes required', 'actual consumer', 'residual risk'],
+  'skills/jhste-red-team-review/references/red-team-review.md': ['Severity rubric', 'Trace at least one changed execution path', 'one main reason to change', 'Current proof'],
 };

package/skills/grill-me/SKILL.md

@@ -8,7 +8,8 @@ description: Direct personal grilling mode for stress-testing the user's own pla
 - Repo-local instructions remain authoritative.
 - Use `jhste-engineering-groundwork` for scope, boundaries, assumptions, and failure paths when it applies.
 - Vocabulary in this vendored skill is advisory unless adopted by repo-local docs; do not rename established repo concepts only to match this skill.
-- 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.
+- This skill is read-only by default. Do not create or modify files, issues, PRs, commands, or repo state during grilling.
+- If the user wants documentation updates, ADRs, glossary changes, issue creation, or other side effects, switch to the appropriate writing workflow such as `grill-with-docs`, `domain-modeling`, `to-issues`, or `triage`.
 
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

package/skills/grilling/SKILL.md

@@ -8,7 +8,8 @@ description: General plan/design stress-test interview. Use when the user asks t
 - Repo-local instructions remain authoritative.
 - Use `jhste-engineering-groundwork` for scope, boundaries, assumptions, and failure paths when it applies.
 - Vocabulary in this vendored skill is advisory unless adopted by repo-local docs; do not rename established repo concepts only to match this skill.
-- 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.
+- This skill is read-only by default. Do not create or modify files, issues, PRs, commands, or repo state during grilling.
+- If the user wants documentation updates, ADRs, glossary changes, issue creation, or other side effects, switch to the appropriate writing workflow such as `grill-with-docs`, `domain-modeling`, `to-issues`, or `triage`.
 
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

package/skills/improve-codebase-architecture/SKILL.md

@@ -60,30 +60,29 @@ Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't
 
 Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
 
-### 2. Present candidates as an HTML report
+### 2. Present candidates
 
-Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+Default to a concise Markdown architecture review unless the user asks for a visual report or the candidate set is complex enough that diagrams would materially improve decision quality. Do not make an HTML file merely because this skill is running.
 
-The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+For the Markdown report, include for each candidate:
 
-For each candidate, the same template as before, but rendered as a card:
-
-- **Files** — which files/modules are involved
+- **Files/modules involved** — which files, modules, or boundaries are involved
 - **Problem** — why the current architecture is causing friction
-- **Solution** — plain English description of what would change
-- **Benefits** — explained in terms of locality and leverage, and how tests would improve
-- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
-- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+- **Concrete failure or maintenance risk** — what can break, mislead, slow review, or force repeated edits
+- **Proposed direction** — plain English description of what would change
+- **SOLID-informed lens involved** — responsibility, extension boundary, substitutability, interface size, or dependency direction when relevant
+- **Benefits** — explained in terms of locality, leverage, testability, or caller clarity
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, or `Speculative`
 
 End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
 
-**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+Use the HTML/Tailwind/Mermaid report only when requested or when visual comparison would materially improve decision quality. If using HTML, write a self-contained file outside the repo unless the user asks otherwise. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user when the environment supports that, and tell them the absolute path. See [HTML-REPORT.md](HTML-REPORT.md) for the optional HTML scaffold, diagram patterns, and styling guidance.
 
-**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
 
-See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
 
-Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+Do NOT propose interfaces yet. After the report, ask the user: "Which of these would you like to explore?"
 
 ### 3. Grilling loop
 

package/skills/jhste-architecture-review/SKILL.md

@@ -12,6 +12,7 @@ Repo-local architecture docs remain authoritative. Use this skill to keep common
 - For non-trivial changes, apply `jhste-engineering-groundwork` before proposing or editing architecture.
 - Keep routing, UI composition, service logic, persistence, and side effects in clear boundaries.
 - Avoid pass-through abstraction that adds names without protecting an invariant or simplifying a caller.
+- Do not introduce an abstraction only to satisfy a SOLID label. Require a concrete caller, variant, side-effect boundary, testability problem, or maintenance failure mode.
 - Make side effects visible in names, directories, or injected dependencies.
 - For changed classes, modules, and functions, name one main responsibility and one main reason to change before adding behavior.
 - For large or mixed modules, identify the responsibility that can move behind a tested boundary without creating shallow pass-through wrappers.

package/skills/jhste-code-quality/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jhste-code-quality
-description: Public-safe code-quality guidance for input validation, observable failures, secret-safe logging, and oversized-file review. Use when touching external input, failure handling, logging, env/config, or code-quality review paths.
+description: Public-safe code-quality guidance for input validation, observable failures, secret-safe logging, cleanup/search-replace safety, and oversized-file review. Use when touching external input, failure handling, logging, env/config, cleanup or secret-removal work, broad search/replace, or code-quality review paths.
 ---
 
 # jhste-code-quality
@@ -18,11 +18,23 @@ Use repo-local instructions first. Treat this skill as shared advisory guidance
 - Do not stop at happy-path-only coverage for changed behavior; include the most relevant edge, failure, side-effect, idempotency, or regression case.
 - Mock external boundaries, not internal collaborators you control.
 - Before adding a new helper, type, or shape, check for the existing source of truth.
-- Use SOLID-informed coding discipline as advisory guidance: one responsibility, extension boundaries only when variants force repeated edits, stable caller contracts, right-sized interfaces, and visible side-effect dependencies.
+- Use SOLID-informed coding discipline as advisory guidance for concrete maintenance and failure risks: one responsibility, extension boundaries only when variants force repeated edits, stable caller contracts, right-sized interfaces, and visible side-effect dependencies. Do not add abstraction only to satisfy a SOLID label.
 - If a hand-written source file grows beyond the profile threshold, consider splitting responsibilities before adding more code.
 - If a page, client module, route/controller, import script, or Python orchestrator crosses a responsibility budget, treat it as a review signal to find the next clean boundary.
 - After code changes, prefer `jhste-skills guard --scope changed --format text --fail-on error` when the CLI is available; report warnings and guard runtime/config failures separately.
 
+## Cleanup and secret-removal safety
+
+For secret cleanup, value removal, broad repository cleanup, or search/replace work:
+
+- Do not treat search results as an edit set.
+- First classify `EDIT_PATHS` and `PROTECTED_PATHS`.
+- `EDIT_PATHS` may include only current product files on the changed execution path or paths explicitly named by the user.
+- Treat docs, examples, tests, fixtures, snapshots, generated outputs, reports, diffs, patches, archives, and history-like surfaces as `PROTECTED_PATHS` unless the user explicitly names that exact path as the edit target.
+- Search the broader repo for reporting evidence, but write only inside `EDIT_PATHS`.
+- Report protected residual hits instead of silently editing them.
+- Do not edit history, object stores, reflogs, external copies, or run garbage collection unless the user explicitly scopes destructive purge work and approves the plan.
+
 ## References
 
 - `references/code-quality.md`

package/skills/jhste-code-quality/references/code-quality.md

@@ -15,7 +15,15 @@ Risky fallback patterns include `catch` blocks that return `[]`, `null`, `undefi
 
 ## SOLID-informed coding discipline
 
-Use SOLID as a design review lens, not as automatic compliance. Keep each changed function, module, or class focused on one responsibility and one reason to change. Review extension boundaries when new variants repeatedly edit core branching, but avoid premature strategies or registries. Preserve caller-visible return shapes, nullability, error behavior, and side-effect expectations. Prefer right-sized contracts over broad config/interface/props bags, while keeping cohesive public contracts together. Keep concrete DB, API, browser, filesystem, email, payment, and queue effects visible through adapters, repositories, injected dependencies, or intentionally local boundaries.
+Use SOLID as a design review lens for concrete maintenance and failure risks, not as automatic compliance. Keep each changed function, module, or class focused on one responsibility and one reason to change. Review extension boundaries when new variants repeatedly edit core branching, but avoid premature strategies or registries. Preserve caller-visible return shapes, nullability, error behavior, and side-effect expectations. Prefer right-sized contracts over broad config/interface/props bags, while keeping cohesive public contracts together. Keep concrete DB, API, browser, filesystem, email, payment, and queue effects visible through adapters, repositories, injected dependencies, or intentionally local boundaries. Do not introduce abstraction only to satisfy a SOLID label.
+
+## Cleanup and secret-removal safety
+
+Broad search results are evidence, not an edit plan. Before removing secrets, values, generated noise, or repeated patterns, classify `EDIT_PATHS` and `PROTECTED_PATHS`.
+
+`EDIT_PATHS` should be limited to current product files on the changed execution path or exact paths the user named as editable. Treat docs, examples, tests, fixtures, snapshots, generated outputs, reports, diffs, patches, archives, and history-like surfaces as `PROTECTED_PATHS` unless the user explicitly targets that exact path. Search protected paths for reporting evidence, but report residual hits instead of silently rewriting them.
+
+Never edit history, object stores, reflogs, external copies, or run garbage collection as part of ordinary cleanup. Those are destructive purge operations and need explicit user scope and approval.
 
 ## Test quality
 

package/skills/jhste-crawler-automation/SKILL.md

@@ -14,6 +14,7 @@ Use this skill when adding or reviewing crawler, scraper, worker, scheduler, or
 - Do not depend on a live scheduled crawler run as the only routine validation path.
 - Browser, network, filesystem, clock, sleep, and notification effects should be visible and testable behind boundaries.
 - Store raw sensitive payloads only when the repo has an explicit policy for doing so.
+- Verify artifact handoff through the consumer-facing path when feasible: produced artifact shape, documented handoff location, idempotent retry behavior, and the consumer-side mutation boundary.
 
 ## References
 

package/skills/jhste-db-api-boundary/SKILL.md

@@ -17,6 +17,7 @@ Use this skill for API and persistence boundary changes. Repo-local API contract
 - Validate database rows or third-party records before treating them as domain objects when shape matters.
 - Make write safety visible for repeated execution, batch mutation, or idempotent retry paths.
 - Return public-safe errors; do not leak raw database, stack, or secret-like details.
+- For API or persistence changes, verification should prefer the actual contract surface when feasible: route handler behavior, request/response shape, auth or tenant scoping, SQL binding behavior, migration/application path, or service boundary used by callers.
 
 ## References
 

package/skills/jhste-engineering-groundwork/SKILL.md

@@ -5,7 +5,7 @@ description: "Pre-change engineering groundwork for non-trivial code work: verif
 
 # jhste-engineering-groundwork
 
-Use before non-trivial code changes. Repo-local instructions and architecture docs remain authoritative.
+Use before non-trivial code changes. Repo-local instructions and architecture docs remain authoritative. For docs-only, comment-only, formatting-only, and trivial rename-only work, skip the full groundwork block unless the change affects user-visible behavior, public API shape, data ownership, safety, or repo architecture. Still keep a short scope and verification note.
 
 ## Contract
 
@@ -15,7 +15,7 @@ Use before non-trivial code changes. Repo-local instructions and architecture do
 - Use this as a pre-edit groundwork check, not as a reason to interrupt the user. Make reasonable assumptions for reversible in-scope work and report them later. Ask only when the assumption changes scope, safety, data ownership, API contract, or user-visible behavior.
 - Identify the ownership boundary: UI, route/controller, usecase/service, repository/query, adapter, job, script, or test fixture.
 - Name the one main responsibility and one main reason to change for each changed class, module, and function.
-- Apply SOLID-informed coding discipline as review guidance, not compliance proof: responsibility, extension boundary, substitutability, interface size, and dependency direction.
+- Use SOLID-informed coding discipline as a clean-code review lens for concrete failure modes, not as compliance proof or a reason to add abstraction by default: responsibility, extension boundary, substitutability, interface size, and dependency direction.
 - Reject adjacent responsibilities unless they are on the changed execution path and leaving them out creates a concrete failure mode.
 - List the important failure paths before writing code.
 - State the data contract entering and leaving the changed boundary.
@@ -41,13 +41,15 @@ For non-trivial code changes, check these before editing:
 8. **Rejected scope** — adjacent refactors or old problems intentionally not touched.
 9. **Smallest safe change** — why the planned change is minimal.
 10. **Verification plan** — tests, guards, builds, or manual checks to run, plus any checks likely to be skipped.
+11. **Final behavior predicates** — concrete public behavior that must change, public/API/DB/UI shape that must not change, expected error behavior, persistence or side-effect expectations, and backward-compatibility constraints.
 
 Keep these items available as internal review evidence, but do not make the user read the full evidence block every time. User-facing output should usually be one or two plain sentences covering:
 
 - scope checked;
 - main risks;
 - smallest-change plan;
-- anything important that was **not checked**.
+- anything important that was **not checked**;
+- the key final behavior predicate when it is useful for the user to review.
 
 
 If a premise was not checked, say **not checked**. Do not write "not found" unless you actually inspected the relevant path.

package/skills/jhste-red-team-review/SKILL.md

@@ -22,8 +22,11 @@ Perform the changed-code review, inspect guard/test output, and run bounded fix/
 - New warnings on changed files should be reported as changes required when they can be fixed within the changed execution path; the follow-up fix happens after the review, not inside it.
 - Inspect the actual changed files or diff before assigning `pass`.
 - Check that each changed class, module, and function has one clear main job, and call out mixed responsibilities that create concrete review or failure risk.
-- Apply SOLID-informed review as a coding-discipline lens: extension boundaries, substitutability, right-sized interfaces, and dependency direction are prompts for concrete failure modes, not automatic violations.
+- Apply SOLID-informed review as a coding-discipline lens: extension boundaries, substitutability, right-sized interfaces, and dependency direction are prompts for concrete failure modes, not automatic violations or automatic abstractions.
 - Do not assign `pass` from guard/test output alone; guard output is evidence, not a substitute for review.
+- Treat old passes, intent, skipped checks, partial artifacts, internal reasoning, and guard output alone as current proof gaps, not proof of completion.
+- Prefer proof through the actual consumer path when feasible: public API route, CLI command, UI route, worker/scheduler path, service entrypoint, fresh-client flow, or documented acceptance path.
+- Keep current proof, checks not run, checks intentionally skipped, and residual risks separate in the final report.
 - Report `guard` runtime/config failures separately from rule violations.
 - Distinguish **not found** from **not checked**. Use **not found** only after inspecting the relevant path.
 - Avoid recommending unrelated refactors unless they are on the changed execution path and required for safety.
@@ -34,7 +37,7 @@ Perform the changed-code review, inspect guard/test output, and run bounded fix/
 
 ## Severity rubric and path tracing
 
-For non-trivial code changes, name the main responsibility of changed classes/modules/functions, apply the SOLID-informed review lens where relevant, trace at least one changed execution path from entrypoint through validation/auth/state to the side effect or result, and state any changed paths not checked. Use `changes required` for new guard or review warnings on changed files that can be fixed within the changed execution path, and for P0/P1 issues that can cause data loss, security/privacy exposure, misleading success, broken runtime behavior, or failed documented acceptance. Use `residual risk` when the bounded review completed but lower-severity, heuristic, environmental, or out-of-scope risks remain. Use `pass` only after inspecting the relevant diff and finding no material follow-up.
+For non-trivial code changes, name the main responsibility of changed classes/modules/functions, apply the SOLID-informed review lens where relevant, trace at least one changed execution path from entrypoint through validation/auth/state to the side effect or result, and state any changed paths not checked. Use `changes required` for new guard or review warnings on changed files that can be fixed within the changed execution path, and for P0/P1 issues that can cause data loss, security/privacy exposure, misleading success, broken runtime behavior, or failed documented acceptance. Use `residual risk` when the bounded review completed but lower-severity, heuristic, environmental, or out-of-scope risks remain. Use `pass` only after inspecting the relevant diff and finding no material follow-up, with current proof for the changed public behavior or a clear explanation of why consumer-path proof was not feasible.
 
 ## Issue candidate protocol
 
@@ -72,8 +75,11 @@ Findings must include:
 Verification must state:
 
 - tests/builds/guards actually run;
+- actual consumer, entrypoint, fresh-client, or documented acceptance path checked when feasible;
 - checks not run;
-- whether any guard failures were runtime/config failures or rule violations.
+- checks intentionally skipped and why;
+- whether any guard failures were runtime/config failures or rule violations;
+- residual risk that remains after bounded review.
 
 When reporting warnings or residual risks to the user, keep the write-up to 2-3 short sentences in a natural developer tone:
 

package/skills/jhste-red-team-review/references/red-team-review.md

@@ -4,16 +4,18 @@ Use an objective red-team checklist. Prefer concrete findings over broad praise.
 
 ## Checklist
 
-- Inspect the changed files or diff directly. Do not pass from summaries, test output, or guard output alone.
+- Inspect the changed files or diff directly. Do not pass from summaries, old passes, intent, test output, partial artifacts, internal reasoning, or guard output alone.
 - Responsibility is separated cleanly enough that changed classes, modules, functions, and UI components each have a clear main job and one main reason to change.
 - SOLID-informed risks are checked as review prompts, not proof: extension boundaries for repeated variants, substitutability contracts, broad interfaces, and concrete dependency direction.
 - Data flow is predictable and easy to trace through the changed code.
+- Current proof is identified explicitly: tests, builds, guards, direct inspection, actual consumer path, fresh-client flow, or documented acceptance path checked now.
 - Null, undefined, empty, loading, and error states are handled safely for the affected paths.
 - Failure handling is observable and does not silently pretend success.
 - Type expectations, API contracts, and caller assumptions still line up after the change.
 - Auth, permission, and user-data isolation risks are called out when relevant.
 - Create/update/delete paths do not appear vulnerable to data loss, duplicate writes, or misleading success states.
 - Build, import, env, route, and runtime assumptions that could break deployment are called out when relevant.
+- Actual consumer-path proof is preferred when feasible: public API route, CLI command, UI route, worker/scheduler path, service entrypoint, fresh-client flow, or documented acceptance path.
 - Performance risks such as duplicate requests, avoidable rerenders, or obviously heavy work on hot paths are called out when relevant.
 - Tests for changed behavior assert observable outcomes through the relevant interface, not implementation details or incidental strings.
 - Changed behavior is not covered only by a happy path when a meaningful edge, failure, side-effect, idempotency, or regression case is relevant.
@@ -35,7 +37,7 @@ Use **not found** only for risks whose relevant paths were inspected. Use **not
 - **P2 -> changes required or residual risk**: contract drift, missing edge-case tests, poor failure observability, or maintainability debt on the changed path; require changes when the failure mode is concrete and immediate.
 - **P3 -> residual risk**: low-confidence heuristic, polish, docs clarity, or follow-up work outside the changed execution path.
 
-Trace at least one changed execution path from entrypoint to side effect/result for non-trivial code changes. Report paths not checked rather than implying broad coverage.
+Trace at least one changed execution path from entrypoint to side effect/result for non-trivial code changes. Report paths not checked rather than implying broad coverage. Keep current proof, skipped checks, not checked areas, and residual risks separate.
 
 ## Issue candidate shape
 
@@ -64,8 +66,9 @@ Summarize the result with:
 1. `pass`, `changes required`, or `residual risk`
 2. Short finding bullets with the concrete problem and impact
 3. Issue candidates only when separate tracked follow-up is warranted
-4. Tests, guard output, builds, or other checks that support the conclusion, plus checks not run
-5. What still might be wrong, if anything
+4. Current proof: tests, guard output, builds, consumer-path/fresh-client checks, or other checks that support the conclusion
+5. Checks intentionally skipped, checks not run, and why
+6. Residual risk: what still might be wrong, if anything
 
 Every finding should name: