jhste-skills 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.3.5 - 2026-06-28
+
+### Added
+- Added `jhste-long-running-work-loop`, a narrow orchestration skill for multi-session and long-running work that preserves goals, phases, approval boundaries, resume points, and durable-state routing without replacing code-quality, PRD, issue, triage, or handoff workflows.
+
+### Changed
+- Updated smoke-test expected skill counts now that the bundled/core skill set includes the new long-running work loop skill.
+
+### Validation
+- `npm test` passed.
+- `jhste-skills guard --scope changed --format text --fail-on error` passed with 0 warnings/errors.
+
+## 0.3.4 - 2026-06-26
+
+### Changed
+- Shifted groundwork and red-team review guidance away from fixed checklist axes and toward context-based failure-mode review of the changed execution path.
+- Tightened DB/API and code-quality skill guidance around caller-appropriate response shapes, storage-backed invariants, authorization/data-isolation paths, and understandable failure behavior without turning those examples into a mandatory checklist.
+- Clarified red-team review versus red-team questioning/interrogation triggers while preserving the red-team wording and intent.
+- Clarified architecture, PRD, issue-slicing, and triage skill trigger boundaries to reduce accidental over-triggering.
+
+### Added
+- Added `sync`/`update --skills-only` to refresh installed skill files without touching repository profiles, bridge blocks, hooks, or deep-scan outputs.
+
 ## 0.3.3 - 2026-06-26
 
 ### Removed

package/README.ja.md

@@ -36,6 +36,7 @@ AI コーディングエージェントは高速ですが、失敗パターン
 ```text
 non-trivial code change の前:
   goal、premise、ownership boundary、data contract、failure path、SOLID-informed review lens を確認
+  固定 checklist を埋めるのではなく、changed execution path で本当に重要な failure mode を文脈に合わせて確認
 
 編集中:
   repo-local instructions を権威として扱う
@@ -107,6 +108,12 @@ changed-file guard を手動で実行するには:
 jhste-skills guard --scope changed --format text --fail-on error
 ```
 
+このリポジトリを最新化した後、プロジェクトの bridge、profile、hook、scan output には触れず、インストール済み skill ファイルだけを更新するには:
+
+```bash
+jhste-skills update --yes --skills-only
+```
+
 任意で repo-wide advisory scan を実行するには:
 
 ```bash

package/README.ko.md

@@ -37,6 +37,7 @@ AI 코딩 에이전트는 빠르지만, 반복적으로 비슷한 방식으로
 ```text
 non-trivial code change 전:
   목표, 전제, ownership boundary, data contract, failure path, final behavior predicate, SOLID-informed review lens 확인
+  고정 체크리스트를 채우기보다 변경된 실행 경로에서 실제로 중요한 실패 모드를 맥락에 맞게 확인
 
 수정 중:
   repo-local instructions를 권위로 취급
@@ -108,6 +109,12 @@ npx jhste-skills install --skill-set core
 jhste-skills guard --scope changed --format text --fail-on error
 ```
 
+이 저장소를 최신으로 당긴 뒤 프로젝트 bridge, profile, hook, scan output은 건드리지 않고 설치된 skill 파일만 새로고침하려면:
+
+```bash
+jhste-skills update --yes --skills-only
+```
+
 선택적으로 repo-wide advisory scan을 실행하려면:
 
 ```bash

package/README.md

@@ -37,6 +37,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, final behavior predicates, and SOLID-informed review lens
+  identify the failure modes that matter for the changed execution path instead of filling out a fixed checklist
 
 While editing:
   treat repo-local instructions as the authority
@@ -108,6 +109,12 @@ To run the changed-file guard manually:
 jhste-skills guard --scope changed --format text --fail-on error
 ```
 
+To refresh only the installed skill files after pulling this repository, without touching a project bridge, profile, hook, or scan output:
+
+```bash
+jhste-skills update --yes --skills-only
+```
+
 To run an optional repo-wide advisory scan:
 
 ```bash

package/README.zh.md

@@ -36,6 +36,7 @@ AI 编程代理很快，但经常以可预测的方式失败：
 ```text
 在 non-trivial code change 前：
   检查目标、前提、ownership boundary、data contract、failure path、SOLID-informed review lens
+  不填写固定 checklist，而是根据 changed execution path 找出真正重要的 failure mode
 
 修改过程中：
   将 repo-local instructions 视为权威
@@ -107,6 +108,12 @@ npx jhste-skills install --skill-set core
 jhste-skills guard --scope changed --format text --fail-on error
 ```
 
+拉取本仓库最新内容后，如果只想刷新已安装的 skill 文件，不触碰项目 bridge、profile、hook 或 scan output：
+
+```bash
+jhste-skills update --yes --skills-only
+```
+
 选择性运行 repo-wide advisory scan：
 
 ```bash

package/cli/sync-core.mjs

@@ -22,11 +22,13 @@ function usage(command = 'sync') {
   console.log(`jhste-skills ${command}
 Usage:
   jhste-skills ${command} [--repo <path>] [--skills-dir <path>] [--yes] [--force]
+  jhste-skills ${command} [--skills-only] [--skills-dir <path>] [--yes]
   jhste-skills ${command} [--skill-set core|vendor|all] [--skip-hooks] [--no-bridge] [--allow-profile-overwrite]
 Notes:
   ${command} reconciles installed skills and already-managed repo outputs using the current local jhste-skills source.
   It does not self-update the jhste-skills source or run git pull automatically.
   Installed skill directories are refreshed by default when they differ from the current source.
+  --skills-only refreshes installed skills without touching repo profile, bridge files, hooks, or deep-scan outputs.
   --force refreshes generated/managed profiles; modified profiles need --force --allow-profile-overwrite.
   Unmanaged skill directories require --allow-unmanaged-skill-overwrite.
 `);
@@ -52,7 +54,7 @@ function normalizeSyncOptions(argv, cwd) {
   const args = parseArgs(argv);
   if (args.help || args.h) return { help: true, errors: [] };
   const errors = [];
-  const supported = new Set(['repo', 'skills-dir', 'yes', 'y', 'force', 'skill-set', 'skip-hooks', 'no-bridge', 'allow-unmanaged-skill-overwrite', 'allow-profile-overwrite', 'help', 'h', '_']);
+  const supported = new Set(['repo', 'skills-dir', 'yes', 'y', 'force', 'skill-set', 'skills-only', 'skip-hooks', 'no-bridge', 'allow-unmanaged-skill-overwrite', 'allow-profile-overwrite', 'help', 'h', '_']);
   for (const key of Object.keys(args)) {
     if (!supported.has(key)) errors.push(`unknown option --${key}.`);
   }
@@ -60,6 +62,7 @@ function normalizeSyncOptions(argv, cwd) {
 
   const force = readBooleanOption(args, 'force', errors);
   const yes = readBooleanOption(args, 'yes', errors) || readBooleanOption(args, 'y', errors);
+  const skillsOnly = readBooleanOption(args, 'skills-only', errors);
   const skipHooks = readBooleanOption(args, 'skip-hooks', errors);
   const noBridge = readBooleanOption(args, 'no-bridge', errors);
   const allowUnmanagedSkillOverwrite = readBooleanOption(args, 'allow-unmanaged-skill-overwrite', errors);
@@ -95,6 +98,7 @@ function normalizeSyncOptions(argv, cwd) {
     repoInfo: findGitRootInfo(repoStart),
     repoStart,
     skipHooks,
+    skillsOnly,
     skillSet,
     skillsDir,
     yes,
@@ -177,8 +181,8 @@ function buildSyncPlan(options, command) {
     ? skillNamesForSet(options.skillSet)
     : (installedSkills.length > 0 ? installedSkills : skillNamesForSet('all'));
   const repoRoot = options.repoInfo.isGitRepo ? options.repoInfo.repoRoot : null;
-  const managedRepo = repoLooksManaged(repoRoot);
-  const hooks = detectSyncHooks(repoRoot, options.skipHooks);
+  const managedRepo = !options.skillsOnly && repoLooksManaged(repoRoot);
+  const hooks = options.skillsOnly ? [] : detectSyncHooks(repoRoot, options.skipHooks);
 
   const plan = {
     command,
@@ -190,7 +194,7 @@ function buildSyncPlan(options, command) {
     allowProfileOverwrite: options.allowProfileOverwrite,
     forceSkills: true,
     installMissing: false,
-    overrides: [],
+    overrides: options.skillsOnly ? ['--skills-only'] : [],
     skillSet: options.skillSet || (installedSkills.length > 0 ? 'detected' : 'all'),
     skillNames,
     installSkills: true,
@@ -200,7 +204,7 @@ function buildSyncPlan(options, command) {
     repoInfo: options.repoInfo,
     repoRoot,
     connectRepo: managedRepo,
-    repoSkippedReason: managedRepo ? null : 'not managed by jhste-skills yet',
+    repoSkippedReason: options.skillsOnly ? 'skills-only requested; not touching repo outputs' : (managedRepo ? null : 'not managed by jhste-skills yet'),
     writeProfile: managedRepo,
     writeBridge: managedRepo && !options.noBridge,
     hooks,

package/docs/CLI.md

@@ -88,6 +88,7 @@ Safety contract:
 ```bash
 jhste-skills sync --yes --repo /path/to/repo
 jhste-skills sync --yes --repo /path/to/repo --skills-dir /path/to/skills
+jhste-skills sync --yes --skills-only
 jhste-skills sync --yes --skill-set all
 jhste-skills sync --yes --force --allow-profile-overwrite
 ```
@@ -98,6 +99,7 @@ Stable contract:
 - only refreshes repo outputs that already look managed by jhste-skills (generated/legacy-generated `.jhste/profile.yaml`, managed bridge markers, or managed hooks);
 - does not bootstrap unmanaged repositories; use `install` or `connect` for first-time setup;
 - preserves non-managed hooks and does not touch source files, CI, `package.json`, or lockfiles;
+- `--skills-only` refreshes installed skills only and never writes repo profile, bridge blocks, hooks, or deep-scan outputs, even when `--repo` points at a managed repo;
 - `--force` refreshes generated/managed profiles but does not overwrite modified profiles unless `--allow-profile-overwrite` is also passed; unmanaged differing skill directories require `--allow-unmanaged-skill-overwrite`;
 - `sync`/`update` may adopt additional known jhste skills into an already managed skills directory and refresh them without the extra overwrite flag.
 
@@ -107,9 +109,11 @@ Stable contract:
 
 ```bash
 jhste-skills update --yes --repo /path/to/repo
+jhste-skills update --yes --skills-only
 ```
 
 It is meant for the common workflow of pulling the latest `jhste-skills` source first, then reconciling local installed copies and managed repo outputs. It does not self-update the package or run `git pull` for you.
+Use `--skills-only` when you want the latest skill files in the local skills directory but do not want to touch the current repository's managed profile, bridge block, hooks, or deep-scan outputs.
 
 ## `deep-scan`
 

package/package.json

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

package/scripts/docs-check-data.mjs

@@ -74,7 +74,7 @@ export const recipeRequirements = {
   '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-engineering-groundwork/SKILL.md': ['Senior-quality pre-edit gate', 'recovery or rollback expectation', '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/scripts/smoke/connect-scenarios.mjs

@@ -13,7 +13,7 @@ export function runConnectScenarios({ root, tmp, skillsDir }) {
   fs.mkdirSync(nonGitCwd, { recursive: true });
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--skills-dir', nonGitCwdSkills, '--skip-deep-scan'], { cwd: nonGitCwd });
   if (fs.existsSync(path.join(nonGitCwd, '.jhste'))) fail('install outside git repo created .jhste');
-  if (skillDirs(nonGitCwdSkills).length !== 20) fail('install outside git repo did not install 20 bundled skills');
+  if (skillDirs(nonGitCwdSkills).length !== 21) fail('install outside git repo did not install 21 bundled skills');
 
   const explicitNonGitRepo = path.join(tmp, 'explicit-non-git-repo');
   const explicitNonGitSkills = path.join(tmp, 'explicit-non-git-skills');
@@ -42,6 +42,6 @@ export function runConnectScenarios({ root, tmp, skillsDir }) {
   if (connectMissing.status !== 3) fail(`connect missing skills should exit 3, got ${connectMissing.status}`);
   if (fs.existsSync(path.join(connectMissingRepo, '.jhste'))) fail('connect missing skills created .jhste');
   run(process.execPath, [path.join(root, 'cli/connect.mjs'), '--mode', 'normal', '--yes', '--repo', connectMissingRepo, '--skills-dir', connectMissingSkills, '--skip-deep-scan', '--install-missing'], { cwd: connectMissingRepo });
-  if (skillDirs(connectMissingSkills).length !== 20) fail('connect --install-missing did not install 20 bundled skills');
+  if (skillDirs(connectMissingSkills).length !== 21) fail('connect --install-missing did not install 21 bundled skills');
   if (!fs.existsSync(path.join(connectMissingRepo, '.jhste', 'profile.yaml'))) fail('connect --install-missing did not create profile');
 }

package/scripts/smoke/install-scenarios.mjs

@@ -112,7 +112,7 @@ function runDefaultInstall(ctx) {
   const manifest = readManagedSkillsManifest(skillsDir);
   if (manifest.managed_by !== 'jhste-skills' || !manifest.skills?.['jhste-red-team-review']?.digest) fail('skills manifest missing managed skill digest');
   const defaultSkillDirs = skillDirs(skillsDir);
-  if (defaultSkillDirs.length !== 20) fail(`default install should copy 20 bundled skills, got ${defaultSkillDirs.length}`);
+  if (defaultSkillDirs.length !== 21) fail(`default install should copy 21 bundled skills, got ${defaultSkillDirs.length}`);
   if (!defaultSkillDirs.includes('improve-codebase-architecture')) fail('default install should copy vendored workflow skills');
 }
 
@@ -171,7 +171,33 @@ run_jhste_skills guard --scope staged --format text --fail-on warning
 
   const managedManifest = readManagedSkillsManifest(skillsDir);
   if (!managedManifest.skills?.[adoptedSkillName]?.digest) fail('update did not record adopted known skill in manifest');
-
+  const profilePath = path.join(repo, '.jhste', 'profile.yaml');
+  const profileBeforeSkillsOnly = fs.readFileSync(profilePath, 'utf8');
+  fs.writeFileSync(skillPath, '# stale local copy for skills-only\n');
+  fs.writeFileSync(agentsPath, updatedAgents.replace(
+    'Repo-local instructions in this file remain authoritative.',
+    'Bridge text that skills-only must not replace.',
+  ));
+  fs.writeFileSync(preCommitPath, `#!/usr/bin/env sh
+# jhste-skills managed hook start
+# mode=blocking hook=pre-commit scope=staged
+echo "skills-only must not replace hook"
+run_jhste_skills guard --scope staged --format text --fail-on warning
+# jhste-skills managed hook end
+`, { mode: 0o755 });
+  run(process.execPath, [path.join(root, 'cli/update.mjs'), '--yes', '--repo', repo, '--skills-dir', skillsDir, '--skills-only'], { cwd: repo });
+  if (fs.readFileSync(skillPath, 'utf8') !== fs.readFileSync(sourceSkillPath, 'utf8')) {
+    fail('update --skills-only did not refresh an installed skill');
+  }
+  if (!fs.readFileSync(agentsPath, 'utf8').includes('Bridge text that skills-only must not replace.')) {
+    fail('update --skills-only rewrote a managed bridge block');
+  }
+  if (!fs.readFileSync(preCommitPath, 'utf8').includes('skills-only must not replace hook')) {
+    fail('update --skills-only rewrote a managed hook');
+  }
+  if (fs.readFileSync(profilePath, 'utf8') !== profileBeforeSkillsOnly) {
+    fail('update --skills-only rewrote a managed profile');
+  }
   let migratedManifest = assertLegacySkillRenameMigration({
     root, repo, skillsDir, manifest: managedManifest, legacyName: 'diagnose', canonicalName: 'diagnosing-bugs', digest: 'legacy-digest',
   });
@@ -242,7 +268,7 @@ function runSkillSetScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(allRepo, 'AGENTS.md'), '# All skill repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--repo', allRepo, '--skills-dir', allSkillsDir, '--skip-deep-scan', '--skip-hooks', '--skill-set', 'all'], { cwd: allRepo });
   const allSkillDirs = skillDirs(allSkillsDir);
-  if (allSkillDirs.length !== 20) fail(`--skill-set all should copy 20 skills, got ${allSkillDirs.length}`);
+  if (allSkillDirs.length !== 21) fail(`--skill-set all should copy 21 skills, got ${allSkillDirs.length}`);
   if (!allSkillDirs.includes('jhste-red-team-review') || !allSkillDirs.includes('improve-codebase-architecture')) fail('--skill-set all missing core or vendored skill');
 }
 

package/scripts/smoke/mode-scenarios.mjs

@@ -27,7 +27,7 @@ function runCustomAndMinimalScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(minimalRepo, 'AGENTS.md'), '# Minimal repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--mode', 'minimal', '--yes', '--repo', minimalRepo, '--skills-dir', minimalSkillsDir, '--skip-deep-scan'], { cwd: minimalRepo });
   const minimalSkillDirs = skillDirs(minimalSkillsDir);
-  if (minimalSkillDirs.length !== 7) fail(`--mode minimal should copy 7 core skills, got ${minimalSkillDirs.length}`);
+  if (minimalSkillDirs.length !== 8) fail(`--mode minimal should copy 8 core skills, got ${minimalSkillDirs.length}`);
   if (fs.existsSync(path.join(minimalRepo, '.jhste'))) fail('--mode minimal created .jhste');
   if (fs.existsSync(path.join(minimalRepo, '.git', 'hooks', 'pre-commit'))) fail('--mode minimal created pre-commit hook');
   if (fs.readFileSync(path.join(minimalRepo, 'AGENTS.md'), 'utf8') !== '# Minimal repo\n') fail('--mode minimal modified AGENTS.md');
@@ -47,7 +47,7 @@ function runFullModeScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(fullModeRepo, 'AGENTS.md'), '# Full mode repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--mode', 'full', '--yes', '--repo', fullModeRepo, '--skills-dir', fullModeSkillsDir, '--skip-deep-scan'], { cwd: fullModeRepo });
   const fullModeSkillDirs = skillDirs(fullModeSkillsDir);
-  if (fullModeSkillDirs.length !== 20) fail(`--mode full should copy 20 skills, got ${fullModeSkillDirs.length}`);
+  if (fullModeSkillDirs.length !== 21) fail(`--mode full should copy 21 skills, got ${fullModeSkillDirs.length}`);
   const fullPreCommit = path.join(fullModeRepo, '.git', 'hooks', 'pre-commit');
   const fullPrePush = path.join(fullModeRepo, '.git', 'hooks', 'pre-push');
   if (!fs.existsSync(fullPreCommit) || !fs.existsSync(fullPrePush)) fail('--mode full did not install pre-commit and pre-push');

package/skills/codebase-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-design
-description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a boundary goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+description: Shared vocabulary for designing deep modules and module interfaces. Use when designing or improving a module interface, deciding where a boundary goes, making code more testable or AI-navigable, or when another skill needs deep-module vocabulary. For repo-wide refactor candidate discovery, use improve-codebase-architecture.
 ---
 
 ## jhste compatibility

package/skills/grill-me/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-me
-description: Direct personal grilling mode for stress-testing the user's own plan or reasoning. Use when the user asks to be grilled, challenged, pressure-tested, or questioned aggressively about their plan.
+description: Direct red-team interrogation of the user's own plan or reasoning. Use when the user asks to be grilled, challenged, pressure-tested, red-teamed, or questioned aggressively about their plan. Not for reviewing an already-changed code diff; use jhste-red-team-review for that.
 ---
 
 ## jhste compatibility

package/skills/grill-with-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-with-docs
-description: Stress-test a plan against project domain language and record resulting decisions in CONTEXT.md or ADRs. Use when the user wants grilling plus documentation, ADR, glossary, or CONTEXT updates.
+description: Red-team questioning of a plan against project domain language, then recording resulting decisions in CONTEXT.md or ADRs. Use when the user wants grilling plus documentation, ADR, glossary, or CONTEXT updates. Not for reviewing an already-changed code diff; use jhste-red-team-review for that.
 ---
 
 ## jhste compatibility

package/skills/grilling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grilling
-description: General plan/design stress-test interview. Use when the user asks to challenge, pressure-test, red-team, grill, or find gaps in a plan before building, without requesting documentation updates.
+description: Red-team questioning for plans and designs before implementation. Use when the user asks to challenge, pressure-test, red-team, grill, interrogate, or find gaps in a plan, without requesting documentation updates. Not for reviewing an already-changed code diff; use jhste-red-team-review for that.
 ---
 
 ## jhste compatibility

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

@@ -1,6 +1,6 @@
 ---
 name: improve-codebase-architecture
-description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+description: Repo-wide or area-wide architecture review to find deepening/refactoring opportunities, informed by CONTEXT.md and docs/adr/. Use when the user wants broad architecture improvement, refactoring opportunities, consolidation of tightly-coupled modules, or better testability and AI-navigability. Not for every local code change; use jhste-architecture-review for the current diff.
 ---
 
 ## jhste compatibility

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

@@ -1,6 +1,6 @@
 ---
 name: jhste-architecture-review
-description: Advisory architecture review guidance for module boundaries, SOLID-informed design review, side effects, and pass-through abstraction. Use when changing module boundaries, app structure, side-effect placement, or responsibility splits.
+description: Advisory architecture review for current code changes touching module boundaries, app structure, side-effect placement, responsibility splits, or pass-through abstraction. Use during or after local code changes; for repo-wide architecture improvement use improve-codebase-architecture, and for module interface vocabulary use codebase-design.
 ---
 
 # jhste-architecture-review

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

@@ -23,7 +23,7 @@ When reviewing a proposed change, ask:
 
 - Bad: `route.ts` performs auth, schema parsing, business rules, database queries, error mapping, and response DTO shaping inline.
 - Better: route/controller does request parsing and response mapping; a usecase owns business invariants; a repository/query owns persistence; errors are mapped through a small public-error boundary.
-- Why: caller contracts, authorization, partial-failure handling, and test boundaries are easier to inspect from entrypoint to side effect.
+- Why: caller contracts, authorization, failure behavior, and test boundaries are easier to inspect from entrypoint to side effect.
 
 ### React client path split
 
@@ -82,4 +82,3 @@ Change adjacent code only when it sits on the changed execution path and leaving
 - Bad: a caller accepts a broad config, interface, or props bag while using only a small slice, creating unrelated coupling.
 - Better: depend on the smallest useful contract, while keeping cohesive public contracts together when they are read and changed together.
 - Why: ISP should reduce coupling, not fragment a contract that always moves as one unit.
-

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

@@ -16,6 +16,7 @@ Use repo-local instructions first. Treat this skill as shared advisory guidance
 - Do not log secrets, tokens, passwords, cookies, authorization headers, sessions, or raw sensitive payloads.
 - Tests should verify observable behavior through the module interface, not implementation details, function-name existence, or incidental strings.
 - Do not stop at happy-path-only coverage for changed behavior; include the most relevant edge, failure, side-effect, idempotency, or regression case.
+- For code with side effects or multi-step work, make the failure behavior understandable to callers and users; do not let the code silently imply success when the changed path did not complete safely.
 - 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 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.

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

@@ -48,8 +48,8 @@ When code crosses async UI, env, or persistence paths, be skeptical of fragile a
 ### Mutation write safety
 
 - Bad: a route loops over writes and returns success after the first non-throwing path.
-- Better: define the idempotency key or dedupe rule, use a transaction/batch/upsert where needed, check affected rows, and report partial failure explicitly.
-- Why: duplicate execution, retry, and rollback behavior are observable instead of assumed.
+- Better: define the write rule at the layer that can enforce it, check the outcome that matters to callers, and report unsafe or incomplete results instead of implying success.
+- Why: duplicate execution, retry, and recovery behavior are observable instead of assumed.
 
 ### Import/ops script
 

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

@@ -7,5 +7,5 @@ Routine validation should use fixtures, dry runs, or focused smoke checks. Live
 ## Producer / consumer recipe
 
 - Bad: a crawler fetches pages, normalizes fields, deduplicates, writes the database, and sends notifications in one loop.
-- Better: the producer emits a versioned artifact; the consumer validates, deduplicates, persists, and reports partial failures with a resumable cursor.
+- Better: the producer emits a versioned artifact; the consumer validates, deduplicates, persists, and reports write outcomes with a resumable cursor.
 - Why: flaky network behavior is separated from write safety, fixtures can replay artifacts, and duplicate writes are easier to prevent.

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

@@ -15,7 +15,9 @@ Use this skill for API and persistence boundary changes. Repo-local API contract
 - Use parameter binding or a safe query abstraction for SQL.
 - Keep request and response contracts explicit enough that caller drift is visible before runtime.
 - 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.
+- Map storage rows to response shapes that match the caller's permission and purpose; do not let internal or higher-privilege data leak through convenient reuse.
+- Make write safety visible at the layer that actually preserves the rule; do not rely on app-side checks alone when storage behavior can contradict them.
+- For authorization or data-isolation changes, inspect the actual policy and execution path instead of trusting a single route, role, or helper as proof.
 - 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.
 

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

@@ -43,7 +43,9 @@ For non-trivial code changes, check these before editing:
 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:
+For changes touching user data, API/DB, permissions, files, external calls, batch writes, async UI actions, exports, or lifecycle state, do not reduce review to a fixed checklist. Follow the changed execution path and use repo-local rules, domain invariants, caller expectations, persistence behavior, side effects, user-visible states, operational impact, and verification evidence to identify the failure modes that matter for this change. Prefer concrete risk statements over named frameworks or exhaustive lists.
+
+Keep the full evidence available internally, but do not make the user read it every time. User-facing output should usually be one or two plain sentences covering:
 
 - scope checked;
 - main risks;
@@ -82,7 +84,7 @@ Avoid: "Should I create an issue?" without supporting reasoning.
 
 ## Senior-quality pre-edit gate
 
-For non-trivial code changes, compare at least two plausible shapes before editing: the smallest local patch and one cleaner boundary-preserving alternative. State the invariant that must remain true, the changed class/module/function responsibility, the caller contract entering and leaving the boundary, the test boundary that will prove behavior, the rejected alternative, and the partial-failure or rollback path. Keep this quiet for docs-only, comment-only, formatting-only, and trivial rename-only work.
+For non-trivial code changes, compare at least two plausible shapes before editing: the smallest local patch and one cleaner boundary-preserving alternative. State the invariant that must remain true, the changed class/module/function responsibility, the caller contract entering and leaving the boundary, the test boundary that will prove behavior, the rejected alternative, and the recovery or rollback expectation for failure after a side effect. Keep this quiet for docs-only, comment-only, formatting-only, and trivial rename-only work.
 
 Adjacent-code scope creep is allowed only when the adjacent code is on the changed execution path and leaving it untouched creates a concrete failure mode. Otherwise emit an Issue candidate rather than widening the change.
 

package/skills/jhste-long-running-work-loop/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: jhste-long-running-work-loop
+description: "Coordinate multi-session or long-running work while preserving state, approval boundaries, and resume points. Use when work spans sessions, wait states, recurring reviews, multiple repos, or durable decisions; does not replace code-quality, PRD, issue, triage, or handoff skills."
+---
+
+# jhste-long-running-work-loop
+
+Use this skill to decide whether a task needs a durable work loop, then keep the loop small, reviewable, and safe. Repo-local instructions remain authoritative.
+
+This is an orchestration skill. Do not reimplement code quality review, PRD writing, issue breakdown, triage, or handoff workflows. Route to the narrower skill when that is the actual task.
+
+## Scope
+
+Use for work that is likely to lose important state across time, tools, repositories, or sessions:
+
+- multi-session implementation or review work;
+- recurring review/check-in loops;
+- external waiting states such as CI, preview deploys, reviewer replies, approvals, vendor/API responses, or customer input;
+- workflows spanning PRD, issues, implementation, review, and release notes;
+- work that touches multiple repositories or external systems;
+- hard-to-reverse design decisions that need a durable decision record;
+- tasks where the next session or next agent must resume safely.
+
+Skip for:
+
+- simple Q&A;
+- typo fixes;
+- formatting-only work;
+- small README edits;
+- small single-file fixes that can finish in one session;
+- direct requests that are only PRD drafting, issue breakdown, triage, or handoff;
+- work where the changed code path can be handled by `jhste-engineering-groundwork`, guard, and `jhste-red-team-review` alone.
+
+When skipping, use the narrower workflow. If useful, briefly note that a long-running loop is unnecessary.
+
+## Contract
+
+1. **Decide if this is actually long-running.**  
+   If not, route to the smallest applicable skill or workflow.
+
+2. **Define the work loop before expanding scope.**  
+   Capture only:
+   - current goal;
+   - current phase;
+   - definition of done;
+   - explicit out-of-scope items;
+   - open decisions;
+   - external blockers or wait states;
+   - approval boundaries;
+   - next checkpoint;
+   - required review gates.
+
+3. **Preserve context only when it will reduce future failure.**  
+   Do not turn project docs into scratchpads. Do not persist raw thought, private reasoning, secrets, or noisy progress logs.
+
+4. **Choose the right durable surface.**
+   - Domain vocabulary or stable domain context -> `CONTEXT.md`.
+   - Hard-to-reverse design decision with real trade-offs -> ADR.
+   - Active work state, blockers, acceptance, and next action -> issue or PR notes.
+   - Next-session or next-agent continuation only -> `handoff`.
+   - Ephemeral, obvious, or soon-stale state -> do not persist.
+
+5. **Resume by verifying, not trusting.**  
+   On resume, re-check the current repo, branch, issue/PR, CI, deployment, or external state before relying on old notes. Mark stale assumptions as not checked.
+
+6. **Respect approval boundaries.**  
+   Proceed without asking for reading, searching, summarizing, planning, drafting, review notes, and issue candidates when repo-local instructions allow it.  
+   Ask before send, push, merge, deploy, delete, publish, production data changes, secret exposure, cost-bearing actions, broad tracker edits, or destructive/irreversible changes.
+
+7. **Delegate to existing skills.**
+   - Before non-trivial code changes, use `jhste-engineering-groundwork`.
+   - After non-trivial code changes, run the configured guard when available and use `jhste-red-team-review`.
+   - For PRDs, use `to-prd`.
+   - For issue breakdown, use `to-issues`.
+   - For tracker triage, use `triage`.
+   - For next-agent/session summaries, use `handoff`.
+   - For domain glossary or ADR work, use `grill-with-docs` or the repo's domain-documentation workflow.
+
+## Minimal loop note
+
+When a durable loop is warranted, keep the note compact:
+
+```md
+## Long-running work loop
+
+Goal:
+- ...
+
+Current phase:
+- ...
+
+Definition of done:
+- ...
+
+Out of scope:
+- ...
+
+Open decisions:
+- ...
+
+External blockers / wait states:
+- ...
+
+Approval required before:
+- ...
+
+Durable state location:
+- ...
+
+Next checkpoint:
+- ...
+
+Review gates:
+- ...
+```
+
+Prefer referencing existing artifacts by path or URL over duplicating their contents.
+
+## Context storage rules
+
+Unless repo-local docs define another role, treat `CONTEXT.md` as stable domain context, not a work log. Use it only for glossary or domain context that future agents need to understand the project correctly.
+
+Create or update an ADR only when all are true:
+
+1. the decision is hard to reverse;
+2. future readers would wonder why it was chosen;
+3. there were real alternatives and trade-offs.
+
+Use issue or PR notes for active work state because that state naturally expires when the work closes.
+
+Use handoff for continuation context that helps the next session but does not deserve permanent repo documentation.
+
+Record nothing when the information is trivial, already obvious from code/tests/diff, likely to go stale quickly, or not useful to future work.
+
+## Output style
+
+Be brief. Report:
+
+- whether the long-running loop is warranted;
+- the chosen durable surface, if any;
+- the next checkpoint;
+- any action that requires approval;
+- which narrower skill should handle the next concrete step.

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

@@ -1,11 +1,11 @@
 ---
 name: jhste-red-team-review
-description: Read-only completion-time red-team review and issue-candidate handoff for non-trivial code changes. Use before declaring code work complete.
+description: Read-only red-team code review for actual diffs or changed files after implementation, with issue-candidate handoff for residual risks. Use before declaring non-trivial code work complete. For pre-implementation red-team questioning or interrogation of a plan, use grilling, grill-me, or grill-with-docs.
 ---
 
 # jhste-red-team-review
 
-Use this skill after non-trivial code changes and before reporting completion. Repo-local instructions remain authoritative.
+Use this skill after non-trivial code changes and before reporting completion. This is red-team code review for changed code, not plan interrogation. Repo-local instructions remain authoritative.
 
 ## Automation and side effects
 
@@ -37,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, with current proof for the changed public behavior or a clear explanation of why consumer-path proof was not feasible.
+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. Do not stop at a fixed checklist; attack the changed path in the way most likely to reveal real failures for this repo, domain, caller, and runtime. 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
 

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

@@ -13,7 +13,10 @@ Use an objective red-team checklist. Prefer concrete findings over broad praise.
 - 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.
+- API and persistence contracts are checked through the public shape and caller expectations that matter for the changed path.
 - Create/update/delete paths do not appear vulnerable to data loss, duplicate writes, or misleading success states.
+- Mutation and side-effect safety are reviewed through the real write path, including what callers and users see if the path is repeated, interrupted, or only partly succeeds.
+- State transitions are reviewed where stale or inconsistent state would mislead users, leak access, or break the domain rule.
 - 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.

package/skills/to-issues/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: to-issues
-description: Break a plan, spec, or PRD into issue-ready vertical slices. Use when the user wants implementation tickets or work breakdown; create tracker issues when directly requested or when repo-local workflow gives standing approval for ticket creation.
+description: Break an existing plan, spec, or PRD into issue-ready vertical implementation slices. Use when the user wants implementation tickets, issue breakdown, or work breakdown from known requirements. For drafting product requirements from conversation context, use to-prd; create tracker issues only when directly requested or when repo-local workflow gives standing approval.
 ---
 
 ## jhste compatibility

package/skills/to-prd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: to-prd
-description: Draft a PRD from the current conversation context and make it ready for the project's normal PRD workflow. Use when the user wants a PRD; publish/create tracker items when directly requested or when repo-local workflow gives standing approval for PRD tracker writes.
+description: Draft a PRD from the current conversation context and make it ready for the project's normal PRD workflow. Use when the user asks for a PRD or product requirements document. For issue-ready implementation slices from an existing plan or PRD, use to-issues; publish/create tracker items only when directly requested or when repo-local workflow gives standing approval.
 ---
 
 ## jhste compatibility

package/skills/triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: triage
-description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
+description: Triage existing or newly requested issues through a state machine driven by triage roles. Use when the user wants to create a specific issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. For PRDs use to-prd; for bulk implementation slice generation from a plan use to-issues.
 ---
 
 ## jhste compatibility