yam-flow 2.3.1 → 2.4.0

package/src/bin/yam.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import { createRequire } from 'node:module';
@@ -34,10 +35,9 @@ import {
   verifyUeyeRevisionHistory
 } from '../lib/ueye-artifacts.js';
 import {
-  INSTALL_LOCK_NAME,
-  INSTALL_RECEIPT_NAME,
   inspectSkillInstallation,
-  installSkillSetTransactional
+  installSkillSetTransactional,
+  uninstallSkillSetSafely
 } from '../lib/skill-installation.js';
 
 type AnyRecord = Record<string, any>;
@@ -84,8 +84,16 @@ const VERSION = String(PACKAGE_JSON.version || '0.0.0');
 const PROJECT_PACK = 'yam.project.md';
 const LEGACY_PROJECT_PACK = 'timeto.project.md';
 const PACK_STALE_DAYS = 30;
-const YAM_LITE_HOOK_COMMAND = `node ${path.join(ROOT, 'dist', 'bin', 'yam.js')} hook run lite`;
-const YAM_STUDY_NOTE_HOOK_COMMAND = `node ${path.join(ROOT, 'dist', 'bin', 'yam.js')} hook run study-note`;
+const INSTRUCTION_DUPLICATION_LIMITS = {
+  maxFiles: 24,
+  maxBytesPerFile: 128000,
+  maxGroups: 8,
+  maxDepth: 6,
+  minDirectiveChars: 40
+};
+const YAM_HOOK_ENTRYPOINT = path.join(ROOT, 'dist', 'bin', 'yam.js');
+const YAM_LITE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite`;
+const YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note`;
 const REQUIRED_PACK_SECTIONS = [
   'Product Direction',
   'UI Direction',
@@ -150,7 +158,7 @@ Usage:
   yam list
   yam status
   yam verify
-  yam detect [dir]
+  yam detect [dir] [--json]
   yam pack [dir]
   yam context pressure [dir] [--json]
   yam cleanup scan [dir] [--json]
@@ -179,7 +187,7 @@ Usage:
   yam hook <status|enable|disable|run> [lite|study-note] [--global|--project dir]
   yam template <project|ueye|mission|proof|tuning>
   yam tune-log [dir]
-  yam install
+  yam install [--replace-user-skill name]
   yam uninstall
   yam doctor [--json]
   yam examples
@@ -205,7 +213,32 @@ async function rmrf(target) {
   await fsp.rm(target, { recursive: true, force: true });
 }
 
-async function install() {
+function installReplacementSkills(args: string[] = []) {
+  const skills: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index] || '');
+    if (arg === '--replace-user-skill') {
+      const skill = String(args[index + 1] || '');
+      if (!skill || skill.startsWith('--')) {
+        throw new Error('missing skill name after --replace-user-skill');
+      }
+      skills.push(skill);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--replace-user-skill=')) {
+      const skill = arg.slice('--replace-user-skill='.length);
+      if (!skill) throw new Error('missing skill name after --replace-user-skill=');
+      skills.push(skill);
+      continue;
+    }
+    throw new Error(`unknown yam install argument: ${arg}`);
+  }
+  return [...new Set(skills)];
+}
+
+async function install(args: string[] = []) {
+  const replaceSkills = installReplacementSkills(args);
   const result = await installSkillSetTransactional({
     sourceRoot: ROOT,
     destination: DEST,
@@ -213,6 +246,7 @@ async function install() {
     packageName: String(PACKAGE_JSON.name || 'yam-flow'),
     version: VERSION,
     skills: SKILLS,
+    replaceSkills,
     legacySkills: LEGACY_SKILLS,
     retiredSkills: RETIRED_SKILLS
   });
@@ -223,20 +257,20 @@ async function install() {
   console.log('Restart Codex to reload skills.');
 }
 
-async function uninstall() {
-  const lockPath = path.join(DEST, INSTALL_LOCK_NAME);
-  if (await exists(lockPath)) {
-    throw new Error(`cannot uninstall while an install lock exists: ${lockPath}`);
-  }
-  for (const skill of [...SKILLS, ...LEGACY_SKILLS, ...RETIRED_SKILLS]) {
-    await rmrf(path.join(DEST, skill));
-    if (CODEX_MIRROR !== DEST) {
-      await rmrf(path.join(CODEX_MIRROR, skill));
-    }
-  }
-  await rmrf(path.join(DEST, INSTALL_RECEIPT_NAME));
+async function uninstall(args: string[] = []) {
+  if (args.length) throw new Error(`unknown yam uninstall argument: ${args[0]}`);
+  const result = await uninstallSkillSetSafely({
+    destination: DEST,
+    codexMirror: CODEX_MIRROR,
+    packageName: String(PACKAGE_JSON.name || 'yam-flow'),
+    skills: SKILLS
+  });
   console.log(`yam removed from ${DEST}`);
-  if (CODEX_MIRROR !== DEST) console.log(`yam mirror entries removed from ${CODEX_MIRROR}`);
+  console.log(`removed receipt: ${result.receiptPath}`);
+  for (const warning of result.cleanupWarnings) console.warn(`warning: ${warning}`);
+  if (CODEX_MIRROR !== DEST) {
+    console.log(`unowned legacy, retired, and Codex mirror entries were preserved`);
+  }
   console.log('Restart Codex to unload skills.');
 }
 
@@ -425,12 +459,20 @@ async function doctor(args = []) {
     console.log('yam doctor: ok');
     console.log('No hooks, automations, or global config are required.');
     console.log('Skill install state is reported by `yam status`.');
+    if (report.preservedUnprovenSkillEntries.length) {
+      console.log(`Preserved unproven legacy/retired/mirror entries: ${report.preservedUnprovenSkillEntries.length}`);
+    }
     console.log(`yam-lite hook: ${report.yamLiteHook} (optional)`);
     return;
   }
 
   console.log('yam doctor: issues');
   for (const issue of report.issues) console.log(`- ${issue}`);
+  if (report.preservedUnprovenSkillEntries.length) {
+    console.log('');
+    console.log('Preserved unproven skill entries:');
+    for (const entry of report.preservedUnprovenSkillEntries) console.log(`- ${entry}`);
+  }
   if (report.nextActions.length) {
     console.log('');
     console.log('Next actions:');
@@ -441,6 +483,7 @@ async function doctor(args = []) {
 
 async function buildDoctorReport() {
   const issues = [];
+  const preservedUnprovenSkillEntries = [];
   for (const skill of SKILLS) {
     if (!await exists(path.join(ROOT, 'skills', skill, 'SKILL.md'))) issues.push(`missing source skill: ${skill}`);
   }
@@ -449,15 +492,21 @@ async function buildDoctorReport() {
   if (await exists(path.join(os.homedir(), '.codex', 'automations', 'yam'))) issues.push('unexpected yam automation');
   if (await exists(path.join(os.homedir(), '.codex', 'automations', 'timeto'))) issues.push('unexpected legacy timeto automation');
   for (const legacySkill of LEGACY_SKILLS) {
-    if (await exists(path.join(DEST, legacySkill, 'SKILL.md'))) issues.push(`unexpected legacy installed skill: ${legacySkill}`);
-    if (CODEX_MIRROR !== DEST && await exists(path.join(CODEX_MIRROR, legacySkill, 'SKILL.md'))) {
-      issues.push(`unexpected legacy mirror skill: ${legacySkill}`);
+    if (await exists(path.join(DEST, legacySkill, 'SKILL.md'))) {
+      preservedUnprovenSkillEntries.push(`legacy-named destination entry: ${legacySkill}`);
     }
   }
   for (const retiredSkill of RETIRED_SKILLS) {
-    if (await exists(path.join(DEST, retiredSkill, 'SKILL.md'))) issues.push(`unexpected retired installed skill: ${retiredSkill}`);
-    if (CODEX_MIRROR !== DEST && await exists(path.join(CODEX_MIRROR, retiredSkill, 'SKILL.md'))) {
-      issues.push(`unexpected retired mirror skill: ${retiredSkill}`);
+    if (await exists(path.join(DEST, retiredSkill, 'SKILL.md'))) {
+      preservedUnprovenSkillEntries.push(`retired-name destination entry: ${retiredSkill}`);
+    }
+  }
+  if (CODEX_MIRROR !== DEST) {
+    const mirrorSkillNames = [...new Set([...SKILLS, ...LEGACY_SKILLS, ...RETIRED_SKILLS])];
+    for (const skill of mirrorSkillNames) {
+      if (!await exists(path.join(CODEX_MIRROR, skill, 'SKILL.md'))) continue;
+      const nameKind = SKILLS.includes(skill) ? 'active-name' : LEGACY_SKILLS.includes(skill) ? 'legacy-named' : 'retired-name';
+      preservedUnprovenSkillEntries.push(`${nameKind} Codex mirror entry: ${skill}`);
     }
   }
   const verifyIssues = await verify({ quiet: true });
@@ -469,6 +518,7 @@ async function buildDoctorReport() {
     generatedAt: new Date().toISOString(),
     ok: issues.length === 0,
     issues,
+    preservedUnprovenSkillEntries,
     nextActions: nextActionDetails.map((action) => action.next_action),
     nextActionDetails,
     yamLiteHook: hookConfigHasYamLite(globalHook) ? 'enabled' : 'disabled'
@@ -486,7 +536,6 @@ function doctorNextActionDetails(issues = []) {
     else if (/missing truth matrix/i.test(issue)) actions.push(nextActionDetail('restore-truth-matrix', 'warning', issue, 'restore references/truth-matrix.md before publishing', 'git checkout -- references/truth-matrix.md'));
     else if (/unexpected local hooks/i.test(issue)) actions.push(nextActionDetail('remove-project-hook', 'warning', issue, 'remove project hooks unless this repo is intentionally dogfooding them', 'inspect .codex/hooks.json and remove only intentional stale hooks'));
     else if (/unexpected .*automation/i.test(issue)) actions.push(nextActionDetail('remove-stale-automation', 'warning', issue, 'remove stale yam/timeto automations before claiming clean install state', 'inspect ~/.codex/automations and remove stale entries manually'));
-    else if (/legacy|retired/i.test(issue)) actions.push(nextActionDetail('replace-old-skills', 'warning', issue, 'run `yam install` to replace old skill entries', 'yam install'));
     else if (/verify reported/i.test(issue)) actions.push(nextActionDetail('run-verify', 'error', issue, 'run `npm run verify` and fix the reported package boundary or metadata issue', 'npm run verify'));
   }
   return uniqueNextActionDetails(actions);
@@ -756,16 +805,36 @@ Notes:
 async function studyNoteCheck(args = []) {
   const flags = parseSimpleFlags(args, new Set(['report', 'text', 'json']));
   const dir = path.resolve(firstPositional(args) || process.cwd());
-  const changedFiles = await gitChangedFiles(dir);
   const reportText = await readStudyNoteReportText(flags, dir);
-  const needsStudyNote = changedFiles.length > 0;
+  const reportSource = flags.report ? path.resolve(dir, String(flags.report)) : flags.text ? 'inline_text' : 'not_provided';
+  const result = await buildStudyNoteGuardResult(dir, reportText, reportSource);
+  printJsonOrHuman(result, Boolean(flags.json), 'Study Note guard');
+  if (result.blockers.length) process.exitCode = 1;
+}
+
+async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'not_provided') {
+  const changedFileDetection = gitChangedFileSnapshot(dir);
+  const changedFiles = changedFileDetection.files;
+  const changeScopeAvailable = changedFileDetection.available;
+  const needsStudyNote = changeScopeAvailable && changedFiles.length > 0;
+  const scopeAwareStatus = (passes) => changeScopeAvailable ? (!needsStudyNote || passes ? 'pass' : 'fail') : 'partial';
   const hygieneRequirements = studyNoteHygieneRequirements(changedFiles);
   const checks = [
-    studyNoteGuardCheck('changed_files', needsStudyNote ? 'pass' : 'skipped', needsStudyNote ? 'changed files detected; Study Note is required before final completion' : 'no changed files detected'),
-    studyNoteGuardCheck('study_note_present', !needsStudyNote || hasStudyNoteMarker(reportText) ? 'pass' : 'fail', 'final report should include a Study Note when project artifacts changed'),
-    studyNoteGuardCheck('role_or_responsibility', !needsStudyNote || /(\brole\b|\bresponsib|\bdoes\b|역할|기능)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should explain what the touched code/artifact does'),
-    studyNoteGuardCheck('before_after_or_change', !needsStudyNote || /(\bbefore\b|\bafter\b|before\/after|changed|change meaning|바뀌|변경|수정)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should explain what changed from before to after'),
-    studyNoteGuardCheck('verification_or_limits', !needsStudyNote || /(verification|verified|checked|limits|uncertain|검증|확인|한계|모르는)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should say what was checked and what remains uncertain')
+    studyNoteGuardCheck(
+      'changed_files',
+      changeScopeAvailable ? (needsStudyNote ? 'pass' : 'skipped') : 'partial',
+      changeScopeAvailable
+        ? (needsStudyNote ? 'changed files detected; Study Note is required before final completion' : 'no changed files detected')
+        : 'Git changed-file scope is unavailable; do not treat this project as clean and determine Study Note need manually'
+    ),
+    studyNoteGuardCheck('study_note_present', scopeAwareStatus(hasStudyNoteMarker(reportText)), 'final report should include a Study Note when project artifacts changed'),
+    studyNoteGuardCheck('role_or_responsibility', scopeAwareStatus(/(\brole\b|\bresponsib|\bdoes\b|역할|기능)/i.test(reportText)), 'Study Note should explain what the touched code/artifact does'),
+    studyNoteGuardCheck('execution_point', scopeAwareStatus(/(execution|\bruns?\b|\bloads?\b|\brenders?\b|validates?|builds?|publishes?|read by|실행|로드|렌더|검사|검증|빌드|게시|배포|읽)/i.test(reportText)), 'Study Note should explain where or when the touched code/artifact runs or is read'),
+    studyNoteGuardCheck('before_after_or_change', scopeAwareStatus(/(\bbefore\b|\bafter\b|before\/after|changed|change meaning|바뀌|변경|수정)/i.test(reportText)), 'Study Note should explain what changed from before to after'),
+    studyNoteGuardCheck('expected_behavior', scopeAwareStatus(/(expected|should|will|result|behavior|예상|기대|결과|동작|되어야|하게 됨)/i.test(reportText)), 'Study Note should describe the expected behavior or result'),
+    studyNoteGuardCheck('syntax_or_structure', scopeAwareStatus(/(syntax|structure|schema|\bapi\b|function|array|field|type|condition|문법|구조|스키마|함수|배열|필드|타입|조건)/i.test(reportText)), 'Study Note should include one useful syntax or structure insight'),
+    studyNoteGuardCheck('verification', scopeAwareStatus(/(verification|verified|checked|tested|검증|확인|테스트)/i.test(reportText)), 'Study Note should say what was checked'),
+    studyNoteGuardCheck('limits_or_uncertainty', scopeAwareStatus(/(limits?|uncertain|unknown|not checked|remaining|한계|불확실|모르는|미확인|남은)/i.test(reportText)), 'Study Note should say what remains uncertain or explicitly state that no meaningful uncertainty remains')
   ];
   for (const requirement of hygieneRequirements) {
     checks.push(studyNoteGuardCheck(requirement.id, requirementSatisfied(reportText, requirement), requirement.note));
@@ -775,16 +844,20 @@ async function studyNoteCheck(args = []) {
     schema: 'yam.study-note-guard.v1',
     generated_at: new Date().toISOString(),
     project: dir,
+    changed_file_detection: changedFileDetection,
     changed_files: changedFiles,
     changed_file_count: changedFiles.length,
-    report_source: flags.report ? path.resolve(dir, String(flags.report)) : flags.text ? 'inline_text' : 'not_provided',
+    report_source: reportSource,
     checks,
     blockers,
-    next_action: blockers[0] || (needsStudyNote ? 'Study Note guard passed for the supplied report text' : 'no Study Note required because no changed files were detected'),
-    truth_status: blockers.length ? 'blocked' : needsStudyNote ? 'verified' : 'skipped'
+    next_action: blockers[0] || (!changeScopeAvailable
+      ? 'Git change scope is unavailable; inspect changed artifacts manually and include a Study Note when anything changed'
+      : needsStudyNote
+        ? 'Study Note guard passed for the supplied report text'
+        : 'no Study Note required because no changed files were detected'),
+    truth_status: blockers.length ? 'blocked' : !changeScopeAvailable ? 'partial' : needsStudyNote ? 'verified' : 'skipped'
   };
-  printJsonOrHuman(result, Boolean(flags.json), 'Study Note guard');
-  if (blockers.length) process.exitCode = 1;
+  return result;
 }
 
 function firstPositional(args = []) {
@@ -800,14 +873,35 @@ function firstPositional(args = []) {
   return '';
 }
 
-async function gitChangedFiles(dir) {
-  const output = runReadOnlyCommandIn(dir, 'git', ['status', '--short']);
-  return output
-    .split(/\r?\n/)
-    .filter(Boolean)
-    .map((line) => line.replace(/^..\s+/, '').replace(/^.* -> /, ''))
-    .map((line) => line.trim())
-    .filter((file) => file && !file.startsWith('dist/') && !file.endsWith('.tgz'));
+function gitChangedFileSnapshot(dir) {
+  const result = spawnSync('git', ['status', '--short', '-z', '--untracked-files=all'], {
+    cwd: dir,
+    encoding: 'utf8',
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+    timeout: 30000
+  });
+  if (result.status !== 0) {
+    return {
+      available: false,
+      source: 'git status --short -z --untracked-files=all',
+      files: []
+    };
+  }
+  const records = String(result.stdout || '').split('\0');
+  const files = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    if (!record || record.length < 4) continue;
+    const status = record.slice(0, 2);
+    const file = record.slice(3);
+    if (/[RC]/.test(status)) index += 1;
+    if (file && !file.startsWith('dist/') && !file.endsWith('.tgz')) files.push(file);
+  }
+  return {
+    available: true,
+    source: 'git status --short -z --untracked-files=all',
+    files
+  };
 }
 
 async function readStudyNoteReportText(flags, dir) {
@@ -900,12 +994,22 @@ async function buildCleanupScanReport(targetDir = process.cwd()) {
   for (const artifact of await staleYamArtifacts(dir)) {
     findings.push(cleanupFinding('low', artifact.file, artifact.reason, 'archive or refresh only if it misleads the current work'));
   }
+  const instructionDuplicationBudget = await buildInstructionDuplicationBudget(dir);
+  if (instructionDuplicationBudget.duplicate_group_count > 0) {
+    findings.push(cleanupFinding(
+      'low',
+      'AGENTS.md/SKILL.md directive duplication budget',
+      `${instructionDuplicationBudget.duplicate_group_count} normalized directive group(s) repeat across separate instruction surfaces; exact normalized matches are advisory and may be intentional`,
+      'review the reported source files and consolidate only repetition that causes drift or conflicting maintenance'
+    ));
+  }
   return {
     schema: 'yam.cleanup-scan.v1',
     generated_at: new Date().toISOString(),
     project: dir,
     destructive: false,
     findings,
+    instruction_duplication_budget: instructionDuplicationBudget,
     risk_level: overallCleanupRisk(findings),
     safe_next_action: findings.length ? 'review findings and make explicit user-approved cleanup decisions' : 'no cleanup action needed',
     truth_status: 'partial'
@@ -959,6 +1063,163 @@ async function staleYamArtifacts(dir) {
   return artifacts;
 }
 
+async function buildInstructionDuplicationBudget(
+  rootDir = process.cwd(),
+  limits = INSTRUCTION_DUPLICATION_LIMITS
+) {
+  const root = path.resolve(rootDir || process.cwd());
+  const inventory = await collectInstructionFiles(root, limits);
+  const directives = new Map<string, AnyRecord[]>();
+  let candidateDirectiveCount = 0;
+  for (const relativeFile of inventory.files) {
+    const absolute = path.join(root, relativeFile);
+    const text = await readBoundedUtf8File(absolute, limits.maxBytesPerFile);
+    for (const directive of instructionDirectives(text, relativeFile, limits.minDirectiveChars)) {
+      candidateDirectiveCount += 1;
+      directives.set(directive.normalized, [...(directives.get(directive.normalized) || []), directive]);
+    }
+  }
+
+  const allGroups = [...directives.entries()]
+    .map(([normalized, occurrences]) => {
+      const surfaces = [...new Set(occurrences.map((item) => item.file))];
+      if (surfaces.length < 2) return null;
+      return {
+        directive_digest: createHash('sha256').update(normalized).digest('hex').slice(0, 16),
+        directive_preview: redactSensitiveText(String(occurrences[0]?.text || '')).slice(0, 180),
+        occurrence_count: occurrences.length,
+        surface_count: surfaces.length,
+        surfaces,
+        occurrences: occurrences.slice(0, 8).map((item) => ({
+          file: item.file,
+          line: item.line
+        }))
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => (
+      right.surface_count - left.surface_count
+      || right.occurrence_count - left.occurrence_count
+      || left.directive_digest.localeCompare(right.directive_digest)
+    ));
+  const duplicateGroups = allGroups.slice(0, limits.maxGroups);
+  return {
+    schema: 'yam.instruction-duplication-budget.v1',
+    scope: 'project AGENTS.md and SKILL.md files only',
+    advisory_only: true,
+    hard_gate: false,
+    destructive: false,
+    normalization: 'exact normalized markdown directive text; no semantic similarity inference',
+    limits: {
+      max_files: limits.maxFiles,
+      max_bytes_per_file: limits.maxBytesPerFile,
+      max_groups: limits.maxGroups,
+      max_depth: limits.maxDepth,
+      min_directive_chars: limits.minDirectiveChars
+    },
+    files_scanned: inventory.files.length,
+    scanned_files: inventory.files,
+    candidate_directive_count: candidateDirectiveCount,
+    duplicate_group_count: allGroups.length,
+    duplicate_groups: duplicateGroups,
+    file_limit_reached: inventory.fileLimitReached,
+    group_limit_reached: allGroups.length > duplicateGroups.length,
+    truth_status: 'partial',
+    note: allGroups.length
+      ? 'repetition may be intentional; review before consolidating'
+      : 'no cross-surface exact normalized directive repetition found within the bounded scan'
+  };
+}
+
+async function collectInstructionFiles(root, limits) {
+  const files: string[] = [];
+  let fileLimitReached = false;
+
+  async function walk(current, depth) {
+    if (depth > limits.maxDepth || fileLimitReached) return;
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const absolute = path.join(current, entry.name);
+      const relative = path.relative(root, absolute);
+      if (shouldSkipScanPath(relative, entry.name) || entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        await walk(absolute, depth + 1);
+        if (fileLimitReached) return;
+        continue;
+      }
+      if (!entry.isFile() || !['AGENTS.md', 'SKILL.md'].includes(entry.name)) continue;
+      if (files.length >= limits.maxFiles) {
+        fileLimitReached = true;
+        return;
+      }
+      files.push(relative);
+    }
+  }
+
+  await walk(root, 0);
+  return { files, fileLimitReached };
+}
+
+async function readBoundedUtf8File(file, maxBytes) {
+  const handle = await fsp.open(file, 'r');
+  try {
+    const buffer = Buffer.alloc(maxBytes);
+    const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+    return buffer.subarray(0, bytesRead).toString('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+function instructionDirectives(text = '', relativeFile = '', minChars = 40) {
+  const directives = [];
+  const lines = String(text || '').split(/\r?\n/);
+  let inFence = false;
+  let inFrontmatter = lines[0]?.trim() === '---';
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const trimmed = raw.trim();
+    if (index === 0 && inFrontmatter) continue;
+    if (inFrontmatter) {
+      if (trimmed === '---') inFrontmatter = false;
+      continue;
+    }
+    if (/^(```|~~~)/.test(trimmed)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence || !trimmed || /^#{1,6}\s/.test(trimmed)) continue;
+    const match = trimmed.match(/^(?:[-*+]|\d+[.)])\s+(.+)$/);
+    if (!match) continue;
+    const normalized = normalizeInstructionDirective(match[1]);
+    if (normalized.length < minChars) continue;
+    directives.push({
+      file: relativeFile,
+      line: index + 1,
+      text: match[1].trim().slice(0, 240),
+      normalized
+    });
+  }
+  return directives;
+}
+
+function normalizeInstructionDirective(value = '') {
+  return String(value || '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[`*_~]/g, '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .replace(/[.;:,!?。，、；：！？]+$/g, '')
+    .trim()
+    .toLowerCase();
+}
+
 function printCleanupScanReport(report) {
   console.log('yam cleanup scan');
   console.log(`Project: ${report.project}`);
@@ -1028,6 +1289,8 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
   const codexHome = path.join(os.homedir(), '.codex');
   const pluginCache = path.join(codexHome, 'plugins', 'cache');
   const globalHook = await readJsonOrDefault(path.join(codexHome, 'hooks.json'), {});
+  const globalLiteHookHealth = await inspectHookProfile(globalHook, 'lite');
+  const globalStudyNoteHookHealth = await inspectHookProfile(globalHook, 'study-note');
   const tmux = await findExecutable('tmux');
   const packageInfo = await projectPackageInfo(dir);
   const pack = await findProjectPack(dir);
@@ -1046,7 +1309,8 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
   const rows = [
     readinessRow('Codex home', await exists(codexHome) ? 'ready' : 'missing', codexHome),
     readinessRow('Yam skills', await status({ quiet: true }) === 0 ? 'ready' : 'missing', DEST),
-    readinessRow('yam-lite hook', hookConfigHasYamLite(globalHook) ? 'enabled' : 'disabled', 'optional UserPromptSubmit guide'),
+    readinessRow('yam-lite hook', globalLiteHookHealth.state, globalLiteHookHealth.issues[0] || 'optional UserPromptSubmit guide'),
+    readinessRow('yam-study-note hook', globalStudyNoteHookHealth.state, globalStudyNoteHookHealth.issues[0] || 'optional prompt reminder plus one-pass Stop completion gate'),
     readinessRow('tmux', tmux ? 'ready' : 'missing', tmux || 'not found on PATH or common Homebrew paths'),
     readinessRow('Browser plugin', await pluginCacheHas('openai-bundled/browser') ? 'ready' : 'unknown', 'Codex in-app browser cache'),
     readinessRow('Chrome plugin', await pluginCacheHas('openai-bundled/chrome') ? 'ready' : 'unknown', 'Chrome/profile-dependent browser cache'),
@@ -1420,7 +1684,8 @@ Usage:
   yam hook run <lite|study-note>
 
 Notes:
-  hooks are opt-in and advisory-only. They do not run tmux, subagents, or proof gates.
+  hooks are opt-in. lite is advisory-only; study-note adds a prompt reminder and a one-pass Stop completion gate.
+  Hooks do not generate reports, run tmux, start subagents, or execute verification automatically.
 `);
 }
 
@@ -1450,11 +1715,11 @@ function hookPathFor(parsed) {
 }
 
 function isYamLiteHook(handler: AnyRecord = {}) {
-  return handler?.type === 'command' && String(handler.command || '').includes('yam.js hook run lite');
+  return handler?.type === 'command' && /yam(?:\.js)?["']?\s+hook\s+run\s+lite(?:\s|$)/i.test(String(handler.command || ''));
 }
 
 function isYamStudyNoteHook(handler: AnyRecord = {}) {
-  return handler?.type === 'command' && String(handler.command || '').includes('yam.js hook run study-note');
+  return handler?.type === 'command' && /yam(?:\.js)?["']?\s+hook\s+run\s+study-note(?:\s|$)/i.test(String(handler.command || ''));
 }
 
 function isYamHookProfile(handler: AnyRecord = {}, profile = 'lite') {
@@ -1464,7 +1729,8 @@ function isYamHookProfile(handler: AnyRecord = {}, profile = 'lite') {
 function stripYamHooks(config: AnyRecord = {}, profile = 'lite') {
   const next = { ...config };
   for (const event of Object.keys(next)) {
-    const entries = Array.isArray(next[event]) ? next[event] : [];
+    if (!Array.isArray(next[event])) continue;
+    const entries = next[event];
     const keptEntries = [];
     for (const entry of entries) {
       const hooks = Array.isArray(entry?.hooks) ? entry.hooks.filter((handler) => !isYamHookProfile(handler, profile)) : [];
@@ -1479,28 +1745,42 @@ function stripYamHooks(config: AnyRecord = {}, profile = 'lite') {
 
 function withYamHook(config: AnyRecord = {}, profile = 'lite') {
   const next = stripYamHooks(config, profile);
-  const event = 'UserPromptSubmit';
-  const entry = {
-    hooks: [
-      {
-        type: 'command',
-        command: profile === 'study-note' ? YAM_STUDY_NOTE_HOOK_COMMAND : YAM_LITE_HOOK_COMMAND,
-        timeout: 5
-      }
-    ]
-  };
-  next[event] = [...(Array.isArray(next[event]) ? next[event] : []), entry];
+  const command = hookCommandForProfile(profile);
+  for (const event of hookEventsForProfile(profile)) {
+    const entry = {
+      hooks: [
+        {
+          type: 'command',
+          command,
+          timeout: 5
+        }
+      ]
+    };
+    next[event] = [...(Array.isArray(next[event]) ? next[event] : []), entry];
+  }
   return next;
 }
 
 async function hookStatus(args = []) {
   const parsed = parseHookArgs(args);
   const target = hookPathFor(parsed);
-  const config = await readJsonOrDefault(target, {});
-  console.log(`yam-lite hook: ${hookConfigHasProfile(config, 'lite') ? 'enabled' : 'disabled'}`);
-  console.log(`yam-study-note hook: ${hookConfigHasProfile(config, 'study-note') ? 'enabled' : 'disabled'}`);
+  const loaded = await readHookConfig(target);
+  if (loaded.error) {
+    console.log('yam-lite hook: broken');
+    console.log('yam-study-note hook: broken');
+    console.log(`  - hook config unreadable: ${loaded.error}`);
+    console.log(`scope: ${parsed.mode}`);
+    console.log(`file: ${target}`);
+    process.exitCode = 1;
+    return;
+  }
+  const lite = await inspectHookProfile(loaded.config, 'lite');
+  const studyNote = await inspectHookProfile(loaded.config, 'study-note');
+  printHookProfileStatus('lite', lite);
+  printHookProfileStatus('study-note', studyNote);
   console.log(`scope: ${parsed.mode}`);
   console.log(`file: ${target}`);
+  if (lite.state === 'broken' || studyNote.state === 'broken') process.exitCode = 1;
 }
 
 function hookConfigHasYamLite(config = {}) {
@@ -1513,6 +1793,160 @@ function hookConfigHasProfile(config = {}, profile = 'lite') {
   }));
 }
 
+function hookCommandForProfile(profile = 'lite') {
+  return profile === 'study-note' ? YAM_STUDY_NOTE_HOOK_COMMAND : YAM_LITE_HOOK_COMMAND;
+}
+
+function hookEventsForProfile(profile = 'lite') {
+  return profile === 'study-note' ? ['UserPromptSubmit', 'Stop'] : ['UserPromptSubmit'];
+}
+
+function hookProfileEntries(config: AnyRecord = {}, profile = 'lite') {
+  const matches = [];
+  for (const [event, entries] of Object.entries(config)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (!Array.isArray(entry?.hooks)) continue;
+      for (const handler of entry.hooks) {
+        if (isYamHookProfile(handler, profile)) matches.push({ event, handler });
+      }
+    }
+  }
+  return matches;
+}
+
+function splitHookCommand(command = '') {
+  const words = [];
+  let current = '';
+  let quote = '';
+  let escaped = false;
+  let started = false;
+  for (const char of String(command)) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      started = true;
+      continue;
+    }
+    if (char === '\\' && quote !== "'") {
+      escaped = true;
+      started = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = '';
+      else current += char;
+      started = true;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (started) {
+        words.push(current);
+        current = '';
+        started = false;
+      }
+      continue;
+    }
+    current += char;
+    started = true;
+  }
+  if (escaped || quote) return [];
+  if (started) words.push(current);
+  return words;
+}
+
+function parseYamHookCommand(command = '', profile = 'lite') {
+  const words = splitHookCommand(command);
+  if (words.length === 5 && words[2] === 'hook' && words[3] === 'run' && words[4] === profile) {
+    const nodeName = path.basename(words[0]).toLowerCase();
+    if (/^node(?:\.exe)?$/.test(nodeName) && path.basename(words[1]).toLowerCase() === 'yam.js') {
+      return { executable: words[0], script: words[1] };
+    }
+  }
+  if (words.length === 4 && words[1] === 'hook' && words[2] === 'run' && words[3] === profile) {
+    const yamName = path.basename(words[0]).toLowerCase();
+    if (/^yam(?:\.cmd|\.exe)?$/.test(yamName)) return { executable: words[0], script: '' };
+  }
+  return null;
+}
+
+async function hookTargetExists(target = '', executable = false) {
+  if (!target) return false;
+  if (!path.isAbsolute(target)) return executable ? Boolean(await findExecutable(target)) : false;
+  try {
+    await fsp.access(target, executable ? fs.constants.X_OK : fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function inspectHookHandler(handler: AnyRecord = {}, profile = 'lite') {
+  const parsed = parseYamHookCommand(String(handler.command || ''), profile);
+  if (!parsed) return { ok: false, issue: 'unsupported yam hook command shape; rerun hook enable to migrate it' };
+  if (!await hookTargetExists(parsed.executable, true)) {
+    return { ok: false, issue: `hook executable is missing or not executable: ${parsed.executable}` };
+  }
+  if (parsed.script && !await hookTargetExists(parsed.script)) {
+    return { ok: false, issue: `hook target is missing: ${parsed.script}` };
+  }
+  return { ok: true, issue: '' };
+}
+
+async function inspectHookProfile(config: AnyRecord = {}, profile = 'lite') {
+  const entries = hookProfileEntries(config, profile);
+  if (!entries.length) return { state: 'disabled', issues: [], entries };
+  const issues = [];
+  for (const event of hookEventsForProfile(profile)) {
+    const count = entries.filter((entry) => entry.event === event).length;
+    if (count === 0) issues.push(`${event} handler is missing; rerun yam hook enable ${profile}`);
+    if (count > 1) issues.push(`${event} has ${count} yam-${profile} handlers; rerun hook enable to remove duplicates`);
+  }
+  for (const entry of entries) {
+    if (!hookEventsForProfile(profile).includes(entry.event)) {
+      issues.push(`unexpected ${entry.event} handler; rerun hook enable to migrate event coverage`);
+    }
+    const health = await inspectHookHandler(entry.handler, profile);
+    if (!health.ok) issues.push(`${entry.event}: ${health.issue}`);
+  }
+  return { state: issues.length ? 'broken' : 'enabled', issues: [...new Set(issues)], entries };
+}
+
+function printHookProfileStatus(profile, health) {
+  console.log(`yam-${profile} hook: ${health.state}`);
+  for (const issue of health.issues) console.log(`  - ${issue}`);
+}
+
+async function readHookConfig(target) {
+  try {
+    const value = JSON.parse(await fsp.readFile(target, 'utf8'));
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+      return { config: {}, exists: true, error: 'top-level value must be a JSON object' };
+    }
+    return { config: value, exists: true, error: '' };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { config: {}, exists: false, error: '' };
+    return { config: {}, exists: true, error: errorMessage(error) };
+  }
+}
+
+async function writeHookConfig(target, config) {
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.yam-write-${process.pid}-${timestampId()}`;
+  try {
+    await fsp.writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    await fsp.rename(temporary, target);
+  } catch (error) {
+    await rmrf(temporary).catch(() => {});
+    throw error;
+  }
+}
+
 async function hookEnable(args = []) {
   const parsed = parseHookArgs(args);
   if (!['lite', 'study-note'].includes(parsed.profile)) {
@@ -1521,23 +1955,45 @@ async function hookEnable(args = []) {
     return;
   }
   const target = hookPathFor(parsed);
-  const current = await readJsonOrDefault(target, {});
+  const loaded = await readHookConfig(target);
+  if (loaded.error) {
+    console.error(`Cannot update unreadable hook config: ${target}`);
+    console.error(loaded.error);
+    process.exitCode = 1;
+    return;
+  }
+  const current = loaded.config;
+  const existing = hookProfileEntries(current, parsed.profile);
+  const expectedEvents = hookEventsForProfile(parsed.profile);
+  const expectedCommand = hookCommandForProfile(parsed.profile);
+  const needsMigration = existing.length > 0 && (
+    existing.length !== expectedEvents.length
+    || existing.some((entry) => !expectedEvents.includes(entry.event) || String(entry.handler?.command || '') !== expectedCommand)
+  );
   const next = withYamHook(current, parsed.profile);
   await fsp.mkdir(path.dirname(target), { recursive: true });
-  if (await exists(target)) {
+  if (loaded.exists) {
     const backup = `${target}.yam-backup-${timestampId()}`;
     await fsp.copyFile(target, backup);
     console.log(`backup: ${backup}`);
   }
-  await fsp.writeFile(target, `${JSON.stringify(next, null, 2)}\n`);
+  await writeHookConfig(target, next);
   console.log(`yam-${parsed.profile} hook enabled (${parsed.mode}): ${target}`);
+  if (needsMigration) console.log(`migrated: ${existing.length} existing yam-${parsed.profile} handler(s) to the current command and event coverage`);
   console.log('Restart Codex or start a new thread if the app does not pick up hook changes immediately.');
 }
 
 async function hookDisable(args = []) {
   const parsed = parseHookArgs(args);
   const target = hookPathFor(parsed);
-  const current = await readJsonOrDefault(target, {});
+  const loaded = await readHookConfig(target);
+  if (loaded.error) {
+    console.error(`Cannot update unreadable hook config: ${target}`);
+    console.error(loaded.error);
+    process.exitCode = 1;
+    return;
+  }
+  const current = loaded.config;
   if (!hookConfigHasProfile(current, parsed.profile)) {
     console.log(`yam-${parsed.profile} hook already disabled (${parsed.mode}): ${target}`);
     return;
@@ -1546,7 +2002,7 @@ async function hookDisable(args = []) {
   if (Object.keys(next).length === 0) {
     await rmrf(target);
   } else {
-    await fsp.writeFile(target, `${JSON.stringify(next, null, 2)}\n`);
+    await writeHookConfig(target, next);
   }
   console.log(`yam-${parsed.profile} hook disabled (${parsed.mode}): ${target}`);
 }
@@ -1560,6 +2016,10 @@ async function hookRun(args = []) {
   const input = await readStdinJson();
   const event = input?.hook_event_name || input?.hookEventName || input?.event || 'UserPromptSubmit';
   const cwd = String(input?.cwd || process.cwd());
+  if (profile === 'study-note' && event === 'Stop') {
+    console.log(JSON.stringify(await buildStudyNoteStopOutput(input, cwd)));
+    return;
+  }
   const prompt = extractPrompt(input);
   const additionalContext = profile === 'study-note'
     ? await buildStudyNoteHookContext({ cwd })
@@ -1619,12 +2079,19 @@ async function buildYamLiteContext({ cwd, prompt }) {
 
 async function buildStudyNoteHookContext({ cwd }) {
   const dir = path.resolve(cwd || process.cwd());
-  const changedFiles = await gitChangedFiles(dir);
+  const changedFileDetection = gitChangedFileSnapshot(dir);
+  const changedFiles = changedFileDetection.files;
   const lines = [
     'yam Study Note guard active: if this turn changes code, config, release metadata, docs, or project artifacts, include a Study Note in the final response.'
   ];
+  if (!changedFileDetection.available) {
+    lines.push('Git changed-file scope is unavailable at prompt time; do not treat this as a clean project.');
+    lines.push('Determine manually whether artifacts changed and include the Study Note when they did; the Stop hook will keep this uncertainty visible.');
+    return lines.join('\n');
+  }
   if (!changedFiles.length) {
     lines.push('No changed files were detected at prompt time; if you change artifacts during this turn, add the Study Note before final.');
+    lines.push('The Study Note Stop hook will check the final response if artifacts are changed later in the turn.');
     return lines.join('\n');
   }
   lines.push(`Changed files detected (${Math.min(changedFiles.length, 8)} shown): ${changedFiles.slice(0, 8).join(', ')}`);
@@ -1634,10 +2101,37 @@ async function buildStudyNoteHookContext({ cwd }) {
     lines.push(`Architecture hygiene required: ${hygiene.map((item) => item.id).join(', ')}.`);
     lines.push('Report whether the change avoided dumping unrelated logic into page.tsx, one-off CSS into global.css, or structured product data into broad DB jsonb.');
   }
-  lines.push('This hook is advisory; it does not generate or edit the Study Note.');
+  lines.push('This prompt reminder does not generate or edit the Study Note; the paired Stop hook requests one correction pass if the final response is incomplete.');
   return lines.join('\n');
 }
 
+async function buildStudyNoteStopOutput(input: AnyRecord = {}, cwd = process.cwd()) {
+  const lastAssistantMessage = String(input?.last_assistant_message || input?.lastAssistantMessage || '');
+  const result = await buildStudyNoteGuardResult(path.resolve(cwd), lastAssistantMessage, 'stop_hook_last_assistant_message');
+  if (result.truth_status === 'partial' && !result.changed_file_detection.available) {
+    return {
+      continue: true,
+      systemMessage: 'yam Study Note guard could not read Git changed-file scope; do not treat this project as clean. Confirm manually whether artifacts changed and include a complete Study Note when they did.'
+    };
+  }
+  if (!result.blockers.length) return { continue: true };
+  const summary = result.blockers.slice(0, 4).join('; ');
+  if (Boolean(input?.stop_hook_active || input?.stopHookActive)) {
+    return {
+      continue: true,
+      systemMessage: `yam Study Note completion gate remains blocked after one correction pass: ${summary}`
+    };
+  }
+  return {
+    decision: 'block',
+    reason: [
+      'yam Study Note completion gate blocked this response because changed project artifacts require a complete Study Note.',
+      summary,
+      'Revise the final response to include: touched artifact, role, execution point, before/after change, expected behavior, one syntax/structure insight, verification, limits, and any relevant architecture hygiene.'
+    ].join(' ')
+  };
+}
+
 function yamLiteRouteHint(prompt = '') {
   const text = String(prompt || '').toLowerCase();
   if (!text) return '';
@@ -4092,7 +4586,10 @@ function pickScript(scripts = {}, groups = []) {
 async function detectProject(targetDir = process.cwd(), { quiet = false } = {}) {
   const dir = path.resolve(targetDir || process.cwd());
   const packageJson = path.join(dir, 'package.json');
+  const changedFileDetection = gitChangedFileSnapshot(dir);
+  const changedFiles = changedFileDetection.files;
   const result = {
+    schema: 'yam.project-detection.v1',
     dir,
     packageJson: await exists(packageJson),
     packageManager: 'npm',
@@ -4103,12 +4600,26 @@ async function detectProject(targetDir = process.cwd(), { quiet = false } = {})
       test: null,
       build: null
     },
-    frameworkChecklist: null
+    frameworkChecklist: null,
+    changedFileDetection,
+    changedFiles,
+    verificationRecommendations: [],
+    verificationCommandPlan: []
   };
   if (!result.packageJson) {
+    result.verificationRecommendations = buildChangedFileVerificationRecommendations({
+      packageManager: result.packageManager,
+      scripts: {},
+      commands: result.commands,
+      changedFiles,
+      changedFilesAvailable: changedFileDetection.available,
+      packageJson: false
+    });
+    result.verificationCommandPlan = buildVerificationCommandPlan(result.verificationRecommendations);
     if (!quiet) {
       console.log(`No package.json found in ${dir}`);
       console.log('Suggested verification: use project pack or local framework conventions.');
+      printChangedFileVerificationRecommendations(result.verificationRecommendations, result.verificationCommandPlan);
     }
     return result;
   }
@@ -4122,11 +4633,255 @@ async function detectProject(targetDir = process.cwd(), { quiet = false } = {})
   result.commands.test = runCommand(result.packageManager, pickScript(scripts, ['test', 'spec']));
   result.commands.build = runCommand(result.packageManager, pickScript(scripts, ['build']));
   result.frameworkChecklist = await detectFrameworkChecklist(dir, pkg);
+  result.verificationRecommendations = buildChangedFileVerificationRecommendations({
+    packageManager: result.packageManager,
+    scripts,
+    commands: result.commands,
+    changedFiles,
+    changedFilesAvailable: changedFileDetection.available,
+    packageJson: true
+  });
+  result.verificationCommandPlan = buildVerificationCommandPlan(result.verificationRecommendations);
 
   if (!quiet) printDetection(result);
   return result;
 }
 
+async function detectCommand(args = []) {
+  const flags = parseSimpleFlags(args, new Set(['json']));
+  const dir = path.resolve(firstPositional(args) || process.cwd());
+  const result = await detectProject(dir, { quiet: true });
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  printDetection(result);
+}
+
+function buildChangedFileVerificationRecommendations({
+  packageManager = 'npm',
+  scripts = {},
+  commands = {},
+  changedFiles = [],
+  changedFilesAvailable = true,
+  packageJson = false
+}: AnyRecord) {
+  const safeFallbackCommands = uniqueStrings([
+    commands.typecheck,
+    commands.lint,
+    commands.test,
+    commands.build
+  ]);
+  if (!changedFilesAvailable) {
+    return [{
+      matched_rule: 'git-status-unavailable',
+      confidence: 'low',
+      reason: 'Git change status was unavailable, so yam cannot prove that the project has no changed files',
+      fallback: packageJson
+        ? 'run all available non-publish typecheck, lint, test, and build checks or use project-pack conventions'
+        : 'use yam.project.md or local framework conventions; no Git change scope or executable package scripts were detected',
+      files: [],
+      suggested_commands: safeFallbackCommands
+    }];
+  }
+  if (!changedFiles.length) {
+    return [{
+      matched_rule: 'no-changes',
+      confidence: 'high',
+      reason: 'git reports no dirty, staged, or untracked project files',
+      fallback: 'rerun `yam detect --json` after files change; use project-pack conventions if Git is unavailable',
+      files: [],
+      suggested_commands: []
+    }];
+  }
+
+  const rules = [
+    {
+      id: 'package-release-metadata',
+      confidence: 'high',
+      matches: (file) => /^(?:package(?:-lock)?\.json|npm-shrinkwrap\.json|yam\.manifest\.json|CHANGELOG\.md|scripts\/check-(?:package-boundary|registry-version|dist-freshness)\.mjs)$/i.test(file),
+      reason: 'package or release metadata changed, so package contents and release readiness can drift',
+      commandNames: ['package-boundary:check', 'release:check'],
+      fallback: 'run the available typecheck/build/package checks and perform the public release workflow separately'
+    },
+    {
+      id: 'src-lib',
+      confidence: 'high',
+      matches: (file) => /^src\/lib\//i.test(file),
+      reason: 'shared library code changed, so compile safety and a focused behavior smoke are the narrowest honest checks',
+      commandNames: ['typecheck'],
+      fallback: 'run typecheck plus the closest available test/smoke; use the full safe fallback when the library crosses package boundaries'
+    },
+    {
+      id: 'scripts',
+      confidence: 'medium',
+      matches: (file) => /^scripts\//i.test(file),
+      reason: 'an executable verification or maintenance script changed, so its direct npm wrapper or closest smoke should run',
+      commandNames: [],
+      fallback: 'run the changed script in an isolated fixture, then use the full safe fallback if no direct wrapper exists'
+    },
+    {
+      id: 'unknown-safe-fallback',
+      confidence: packageJson ? 'medium' : 'low',
+      matches: () => true,
+      reason: 'no focused changed-file rule matched, so skipping verification would be weaker than the available project-wide safe checks',
+      commandNames: [],
+      fallback: packageJson
+        ? 'run all available non-publish typecheck, lint, test, and build checks'
+        : 'use yam.project.md or local framework conventions; no executable package scripts were detected'
+    }
+  ];
+
+  const grouped = new Map<string, string[]>();
+  for (const rawFile of changedFiles) {
+    const file = String(rawFile || '').replaceAll('\\', '/');
+    const rule = rules.find((candidate) => candidate.matches(file)) || rules[rules.length - 1];
+    grouped.set(rule.id, [...(grouped.get(rule.id) || []), file]);
+  }
+
+  const recommendations = [];
+  for (const rule of rules) {
+    const files = grouped.get(rule.id) || [];
+    if (!files.length) continue;
+    let commandEvidence: AnyRecord[] = rule.commandNames.map((name) => ({
+      name,
+      files,
+      basis: 'rule-wide'
+    }));
+    if (rule.id === 'src-lib') {
+      commandEvidence = [
+        { name: 'typecheck', files, basis: 'rule-wide' },
+        ...focusedSmokeScriptEvidenceForFiles(scripts, files)
+      ];
+    } else if (rule.id === 'scripts') {
+      const directEvidence = files.flatMap((file) => (
+        directScriptNamesForFile(scripts, file).map((name) => ({
+          name,
+          files: [file],
+          basis: 'direct-script-wrapper'
+        }))
+      ));
+      commandEvidence = directEvidence.length
+        ? directEvidence
+        : focusedSmokeScriptNames(scripts).slice(0, 1).map((name) => ({
+          name,
+          files,
+          basis: 'group-fallback'
+        }));
+    } else if (rule.id === 'unknown-safe-fallback') {
+      commandEvidence = safeFallbackCommands.map((command) => ({
+        command,
+        files,
+        basis: 'safe-fallback'
+      }));
+    }
+    const commandSources = commandEvidence
+      .map((evidence) => ({
+        command: evidence.command || scriptCommandIfPresent(packageManager, scripts, evidence.name),
+        files: [...new Set(evidence.files || [])].sort(),
+        basis: evidence.basis
+      }))
+      .filter((evidence) => evidence.command);
+    const suggestedCommands = uniqueStrings(commandSources.map((evidence) => evidence.command));
+    recommendations.push({
+      matched_rule: rule.id,
+      confidence: rule.confidence,
+      reason: rule.reason,
+      fallback: rule.fallback,
+      files: [...new Set(files)].sort(),
+      suggested_commands: suggestedCommands,
+      command_sources: commandSources
+    });
+  }
+  return recommendations;
+}
+
+function focusedSmokeScriptNames(scripts = {}) {
+  return Object.keys(scripts)
+    .filter((name) => /(?:^|[-:])(?:smoke|test)(?:$|[-:])/i.test(name) || /smoke/i.test(String(scripts[name] || '')))
+    .sort();
+}
+
+function focusedSmokeScriptEvidenceForFiles(scripts = {}, files = []) {
+  const candidates = focusedSmokeScriptNames(scripts);
+  const selected = [];
+  for (const file of files) {
+    const stem = path.posix.basename(String(file || '').replaceAll('\\', '/')).replace(/\.[^.]+$/, '');
+    const direct = candidates.find((name) => {
+      const command = String(scripts[name] || '');
+      return name.includes(stem)
+        || command.includes(stem)
+        || (stem === 'skill-installation' && /install.*smoke|smoke.*install/i.test(`${name} ${command}`))
+        || (['trust-kernel', 'ueye-artifacts'].includes(stem) && /cli.*smoke|smoke.*cli/i.test(`${name} ${command}`));
+    });
+    if (direct) selected.push({
+      name: direct,
+      files: [file],
+      basis: 'focused-file-match'
+    });
+  }
+  if (!selected.length && candidates.length) {
+    selected.push({
+      name: candidates[0],
+      files,
+      basis: 'group-fallback'
+    });
+  }
+  return selected;
+}
+
+function directScriptNamesForFile(scripts = {}, changedFile = '') {
+  const normalized = String(changedFile || '').replaceAll('\\', '/');
+  const basename = path.posix.basename(normalized);
+  return Object.entries(scripts)
+    .filter(([, command]) => {
+      const text = String(command || '').replaceAll('\\', '/');
+      return text.includes(normalized) || text.includes(`/${basename}`) || text.includes(` ${basename}`);
+    })
+    .map(([name]) => name)
+    .sort();
+}
+
+function scriptCommandIfPresent(packageManager, scripts = {}, name = '') {
+  return name && Object.prototype.hasOwnProperty.call(scripts, name)
+    ? runCommand(packageManager, name)
+    : null;
+}
+
+function uniqueStrings(values = []) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.trim()))];
+}
+
+function buildVerificationCommandPlan(recommendations = []) {
+  const commands = new Map<string, AnyRecord>();
+  for (const recommendation of recommendations) {
+    const sources = recommendation.command_sources?.length
+      ? recommendation.command_sources
+      : (recommendation.suggested_commands || []).map((command) => ({
+        command,
+        files: recommendation.files || [],
+        basis: 'recommendation-fallback'
+      }));
+    for (const source of sources) {
+      const current = commands.get(source.command) || {
+        command: source.command,
+        matched_rules: [],
+        files: [],
+        provenance: []
+      };
+      current.matched_rules = uniqueStrings([...current.matched_rules, recommendation.matched_rule]);
+      current.files = uniqueStrings([...current.files, ...(source.files || [])]).sort();
+      current.provenance.push({
+        matched_rule: recommendation.matched_rule,
+        files: [...new Set(source.files || [])].sort(),
+        basis: source.basis
+      });
+      commands.set(source.command, current);
+    }
+  }
+  return [...commands.values()];
+}
+
 function printDetection(result) {
   console.log(`Project: ${result.dir}`);
   console.log(`Package manager: ${result.packageManager}`);
@@ -4140,6 +4895,7 @@ function printDetection(result) {
   console.log(`- $quick: ${result.commands.typecheck || result.commands.lint || result.commands.test || result.commands.build || 'L1 inspected; no command detected'}`);
   console.log(`- $ueye: ${result.commands.typecheck || result.commands.build || 'Browser/screenshot check; no command detected'}`);
   console.log(`- $deep: ${[result.commands.typecheck, result.commands.lint, result.commands.test, result.commands.build].filter(Boolean).join(' && ') || `No command detected; define in ${PROJECT_PACK}`}`);
+  printChangedFileVerificationRecommendations(result.verificationRecommendations, result.verificationCommandPlan);
   if (result.frameworkChecklist?.detected) {
     console.log('');
     console.log(`Framework checklist: ${result.frameworkChecklist.framework}`);
@@ -4149,6 +4905,29 @@ function printDetection(result) {
   }
 }
 
+function printChangedFileVerificationRecommendations(recommendations = [], commandPlan = []) {
+  console.log('');
+  console.log('Changed-file verification recommendations (advisory; commands were not run):');
+  for (const recommendation of recommendations) {
+    console.log(`- ${recommendation.matched_rule} [confidence: ${recommendation.confidence}]`);
+    console.log(`  files: ${recommendation.files.length ? recommendation.files.join(', ') : '(none)'}`);
+    console.log(`  reason: ${recommendation.reason}`);
+    console.log(`  commands: ${recommendation.suggested_commands.length ? recommendation.suggested_commands.join(' && ') : '(none detected)'}`);
+    console.log(`  fallback: ${recommendation.fallback}`);
+  }
+  console.log('');
+  console.log('Verification command plan (deduplicated; advisory; commands were not run):');
+  if (!commandPlan.length) {
+    console.log('- (none detected)');
+    return;
+  }
+  for (const item of commandPlan) {
+    console.log(`- ${item.command}`);
+    console.log(`  rules: ${item.matched_rules.join(', ')}`);
+    console.log(`  files: ${item.files.join(', ') || '(none)'}`);
+  }
+}
+
 function budget(routeArg = '') {
   const normalized = normalizeRoute(routeArg);
   const entries = normalized ? [[normalized, ROUTE_BUDGETS[normalized]]] : Object.entries(ROUTE_BUDGETS);
@@ -4536,16 +5315,39 @@ function findSensitivePattern(text = '') {
 function showPath() {
   console.log(`root: ${ROOT}`);
   console.log(`skills: ${DEST}`);
-  console.log(`codex mirror cleanup: ${CODEX_MIRROR}`);
+  console.log(`codex mirror (preserved without an ownership receipt): ${CODEX_MIRROR}`);
+}
+
+function showRequestedHelp(args: string[]) {
+  if (!args.some((arg) => arg === '--help' || arg === '-h')) return false;
+
+  const commandUsage: Record<string, () => void> = {
+    context: contextUsage,
+    cleanup: cleanupUsage,
+    'study-note': studyNoteUsage,
+    tools: toolsUsage,
+    hook: hookUsage,
+    loop: loopUsage,
+    ueye: ueyeUsage,
+    media: mediaUsage,
+    runtime: runtimeUsage,
+    mission: missionUsage,
+    benchmark: benchmarkUsage,
+    memory: memoryUsage
+  };
+  (commandUsage[args[0]] || usage)();
+  return true;
 }
 
 async function main() {
-  const command = process.argv[2] || 'help';
-  if (command === 'help' || command === '--help' || command === '-h') return usage();
-  if (command === 'install') return install();
-  if (command === 'uninstall') return uninstall();
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+  if (showRequestedHelp(args)) return;
+  if (command === 'help') return usage();
+  if (command === 'install') return install(args.slice(1));
+  if (command === 'uninstall') return uninstall(args.slice(1));
   if (command === 'version') return console.log(VERSION);
-  if (command === 'detect') return detectProject(process.argv[3]);
+  if (command === 'detect') return detectCommand(args.slice(1));
   if (command === 'pack') return inspectProjectPack(process.argv[3]);
   if (command === 'context') return context(process.argv.slice(3));
   if (command === 'cleanup') return cleanup(process.argv.slice(3));