yam-flow 2.3.2 → 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,6 +51,13 @@ 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 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`;
@@ -116,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]
@@ -145,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
@@ -169,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,
@@ -177,6 +210,7 @@ async function install() {
         packageName: String(PACKAGE_JSON.name || 'yam-flow'),
         version: VERSION,
         skills: SKILLS,
+        replaceSkills,
         legacySkills: LEGACY_SKILLS,
         retiredSkills: RETIRED_SKILLS
     });
@@ -187,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 } = {}) {
@@ -397,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:');
@@ -413,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}`);
@@ -426,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 });
@@ -449,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'
@@ -468,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'));
     }
@@ -759,19 +808,24 @@ async function studyNoteCheck(args = []) {
         process.exitCode = 1;
 }
 async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'not_provided') {
-    const changedFiles = await gitChangedFiles(dir);
-    const needsStudyNote = changedFiles.length > 0;
+    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('execution_point', !needsStudyNote || /(execution|\bruns?\b|\bloads?\b|\brenders?\b|validates?|builds?|publishes?|read by|실행|로드|렌더|검사|검증|빌드|게시|배포|읽)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should explain where or when the touched code/artifact runs or is read'),
-        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('expected_behavior', !needsStudyNote || /(expected|should|will|result|behavior|예상|기대|결과|동작|되어야|하게 됨)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should describe the expected behavior or result'),
-        studyNoteGuardCheck('syntax_or_structure', !needsStudyNote || /(syntax|structure|schema|\bapi\b|function|array|field|type|condition|문법|구조|스키마|함수|배열|필드|타입|조건)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should include one useful syntax or structure insight'),
-        studyNoteGuardCheck('verification', !needsStudyNote || /(verification|verified|checked|tested|검증|확인|테스트)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should say what was checked'),
-        studyNoteGuardCheck('limits_or_uncertainty', !needsStudyNote || /(limits?|uncertain|unknown|not checked|remaining|한계|불확실|모르는|미확인|남은)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should say what remains uncertain or explicitly state that no meaningful uncertainty remains')
+        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));
@@ -781,13 +835,18 @@ async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'n
         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: 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'
     };
     return result;
 }
@@ -805,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)
@@ -902,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'
@@ -961,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}`);
@@ -1830,10 +2074,16 @@ 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.');
@@ -1852,6 +2102,12 @@ async function buildStudyNoteHookContext({ cwd }) {
 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('; ');
@@ -4341,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',
@@ -4352,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;
     }
@@ -4370,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}`);
@@ -4387,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}`);
@@ -4395,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);
@@ -4773,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')