yam-flow 2.3.1 → 2.4.0

package/dist/bin/yam.js

@@ -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';
@@ -9,7 +10,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { TRUTH_STATUSES, buildLoopReport, buildMediaGenerationProof, buildMissionCompletionGate, buildMissionPatchEnvelope, buildMissionSubagentReceipt, buildRollbackHint, buildRuntimeBackendEvidence, buildStudyNote, buildUeyeDesignCompletionGate, buildUeyeVisualProvenance, buildUeyeRunReport, buildUeyeSurfaceContext, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
 import { archiveUeyeRevision, inspectImageFile, upsertUeyeAsset, verifyUeyeAssetManifest, verifyUeyeRevisionHistory } from '../lib/ueye-artifacts.js';
-import { INSTALL_LOCK_NAME, INSTALL_RECEIPT_NAME, inspectSkillInstallation, installSkillSetTransactional } from '../lib/skill-installation.js';
+import { inspectSkillInstallation, installSkillSetTransactional, uninstallSkillSetSafely } from '../lib/skill-installation.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -50,8 +51,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',
@@ -115,7 +124,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]
@@ -144,7 +153,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
@@ -168,7 +177,32 @@ async function exists(file) {
 async function rmrf(target) {
     await fsp.rm(target, { recursive: true, force: true });
 }
-async function install() {
+function installReplacementSkills(args = []) {
+    const skills = [];
+    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 = []) {
+    const replaceSkills = installReplacementSkills(args);
     const result = await installSkillSetTransactional({
         sourceRoot: ROOT,
         destination: DEST,
@@ -176,6 +210,7 @@ async function install() {
         packageName: String(PACKAGE_JSON.name || 'yam-flow'),
         version: VERSION,
         skills: SKILLS,
+        replaceSkills,
         legacySkills: LEGACY_SKILLS,
         retiredSkills: RETIRED_SKILLS
     });
@@ -186,21 +221,22 @@ async function install() {
         console.warn(`warning: ${warning}`);
     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 = []) {
+    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.');
 }
 async function status({ quiet = false } = {}) {
@@ -396,12 +432,21 @@ 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:');
@@ -412,6 +457,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}`);
@@ -425,17 +471,22 @@ async function buildDoctorReport() {
     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 });
@@ -448,6 +499,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'
@@ -467,8 +519,6 @@ function doctorNextActionDetails(issues = []) {
             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'));
     }
@@ -750,16 +800,32 @@ 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));
@@ -769,17 +835,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 = []) {
     for (let index = 0; index < args.length; index += 1) {
@@ -795,14 +864,38 @@ 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) {
     if (flags.text)
@@ -892,12 +985,17 @@ 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'
@@ -951,6 +1049,162 @@ 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();
+    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 = [];
+    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}`);
@@ -1017,6 +1271,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);
@@ -1035,7 +1291,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'),
@@ -1413,7 +1670,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.
 `);
 }
 function parseHookArgs(args = []) {
@@ -1444,10 +1702,10 @@ function hookPathFor(parsed) {
     return path.join(path.resolve(parsed.projectDir || process.cwd()), '.codex', 'hooks.json');
 }
 function isYamLiteHook(handler = {}) {
-    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 = {}) {
-    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 = {}, profile = 'lite') {
     return profile === 'study-note' ? isYamStudyNoteHook(handler) : isYamLiteHook(handler);
@@ -1455,7 +1713,9 @@ function isYamHookProfile(handler = {}, profile = 'lite') {
 function stripYamHooks(config = {}, 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)) : [];
@@ -1472,27 +1732,42 @@ function stripYamHooks(config = {}, profile = 'lite') {
 }
 function withYamHook(config = {}, 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 = {}) {
     return hookConfigHasProfile(config, 'lite');
@@ -1502,6 +1777,169 @@ function hookConfigHasProfile(config = {}, profile = 'lite') {
         return Array.isArray(entry?.hooks) && entry.hooks.some((handler) => isYamHookProfile(handler, profile));
     }));
 }
+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 = {}, 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 = {}, 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 = {}, 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.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)) {
@@ -1510,22 +1948,43 @@ 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;
@@ -1535,7 +1994,7 @@ async function hookDisable(args = []) {
         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}`);
 }
@@ -1548,6 +2007,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 })
@@ -1611,12 +2074,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(', ')}`);
@@ -1626,9 +2096,36 @@ 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 = {}, 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)
@@ -4100,7 +4597,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',
@@ -4111,12 +4611,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;
     }
@@ -4129,10 +4643,238 @@ 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 }) {
+    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();
+    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 = 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();
+    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}`);
@@ -4146,6 +4888,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}`);
@@ -4154,6 +4897,28 @@ 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);
@@ -4532,20 +5297,43 @@ 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) {
+    if (!args.some((arg) => arg === '--help' || arg === '-h'))
+        return false;
+    const commandUsage = {
+        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')
+    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();
+        return install(args.slice(1));
     if (command === 'uninstall')
-        return uninstall();
+        return uninstall(args.slice(1));
     if (command === 'version')
         return console.log(VERSION);
     if (command === 'detect')
-        return detectProject(process.argv[3]);
+        return detectCommand(args.slice(1));
     if (command === 'pack')
         return inspectProjectPack(process.argv[3]);
     if (command === 'context')