yam-flow 2.8.1 → 2.8.3

package/src/bin/yam.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import { studyNoteTurnScope } from '../lib/study-note-scope.js';
+import { selectHookNode, probeHookDiscovery, inspectHookObservation, recordHookObservation } from '../lib/hook-readiness.js';
+import { readMemoryDirectory } from '../lib/memory-records.js';
 import { runSecurityCommand } from '../lib/security-integration.js';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
@@ -149,8 +152,8 @@ const INSTRUCTION_DUPLICATION_LIMITS = {
   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`;
+let YAM_LITE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite`;
+let 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',
@@ -986,8 +989,8 @@ async function studyNoteCheck(args = []) {
   if (result.blockers.length) process.exitCode = 1;
 }
 
-async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'not_provided') {
-  const changedFileDetection = gitChangedFileSnapshot(dir);
+async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'not_provided', scope: any = null) {
+  const changedFileDetection = scope || gitChangedFileSnapshot(dir);
   const changedFiles = changedFileDetection.files;
   const changeScopeAvailable = changedFileDetection.available;
   const needsStudyNote = changeScopeAvailable && changedFiles.length > 0;
@@ -1022,6 +1025,13 @@ async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'n
   for (const requirement of hygieneRequirements) {
     checks.push(studyNoteGuardCheck(requirement.id, requirementSatisfied(studyNoteText, requirement), requirement.note));
   }
+  if (scope?.mode === 'advisory') {
+    const ordinary = new Set(['changed_files', 'study_note_present', 'role_or_responsibility', 'verification', 'limits_or_uncertainty', 'next_step_present', 'single_study_note_next_step_pair', 'study_note_then_next_step']);
+    for (const check of checks) if (!ordinary.has(check.id)) {
+      check.status = 'skipped';
+      check.truth_status = 'skipped';
+    }
+  }
   const blockers = checks.filter((check) => check.status === 'fail').map((check) => `${check.id}: ${check.next_action}`);
   const result = {
     schema: 'yam.study-note-guard.v1',
@@ -1108,7 +1118,7 @@ function hasNextStepMarker(text = '') {
 
 function reportSectionMarkers(text = '') {
   return String(text || '').split(/\r?\n/).map((line, index) => {
-    const trimmed = line.trim();
+    const trimmed = line.trim().replace(/^\*\*(.*?)\*\*\s*:?[ \t]*$/, '$1');
     const heading = trimmed.match(/^#{1,6}\s+(.+?)\s*#*\s*$/);
     const named = trimmed.match(/^(study note|study-note|학습\s*노트|스터디\s*노트|next step|next-step|다음\s*(?:단계|할\s*일|작업))\s*:?[ \t]*$/i);
     const rawLabel = heading?.[1] || named?.[1] || '';
@@ -1234,7 +1244,7 @@ function studyNoteHygieneRequirements(files = []) {
   if (files.some((file) => /(^|\/)global\.css$/i.test(file))) {
     requirements.push({ id: 'global_css_hygiene', terms: ['global.css', 'token', 'component', 'scoped', 'module', 'utility'], note: 'Study Note should say whether CSS belongs globally or should move to tokens/scoped/component styles' });
   }
-  if (files.some((file) => /(migration|schema|db|database|sql|prisma|drizzle|supabase)/i.test(file))) {
+  if (files.some((file) => /\.(sql|prisma)$/i.test(file) || /(^|\/)(migrations?|schema|database|drizzle|supabase)\//i.test(file) && /\.(ts|js)$/i.test(file))) {
     requirements.push({ id: 'jsonb_hygiene', terms: ['jsonb', 'column', 'table', 'constraint', 'index', 'schema', 'relation'], note: 'Study Note should say whether structured product data belongs in typed columns/tables/constraints/indexes instead of broad DB jsonb' });
   }
   return requirements;
@@ -2014,6 +2024,7 @@ async function hook(args = []) {
   const subcommand = args[0] || 'status';
   if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') return hookUsage();
   if (subcommand === 'status') return hookStatus(args.slice(1));
+  if (subcommand === 'migrate') return hookMigrate(args.slice(1));
   if (subcommand === 'enable') return hookEnable(args.slice(1));
   if (subcommand === 'disable') return hookDisable(args.slice(1));
   if (subcommand === 'run') return hookRun(args.slice(1));
@@ -2025,14 +2036,17 @@ function hookUsage() {
   console.log(`yam hook
 
 Usage:
-  yam hook status [--global|--project dir]
-  yam hook enable <lite|study-note> [--global|--project dir]
+  yam hook status [--global|--project dir] [--probe] [--json]
+  yam hook migrate [--global|--project dir]
+  yam hook enable <lite|study-note> [--global|--project dir] [--observe]
   yam hook disable [lite|study-note] [--global|--project dir]
   yam hook run <lite|study-note>
 
 Notes:
   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.
+  --probe queries hooks/list in a separate bounded Codex app-server; active session loading stays unknown.
+  --observe opts into private local entrypoint observations without storing prompt content; not host attestation.
 `);
 }
 
@@ -2057,7 +2071,7 @@ function parseHookArgs(args = []) {
 }
 
 function hookPathFor(parsed) {
-  if (parsed.mode === 'global') return path.join(os.homedir(), '.codex', 'hooks.json');
+  if (parsed.mode === 'global') return path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'hooks.json');
   return path.join(path.resolve(parsed.projectDir || process.cwd()), '.codex', 'hooks.json');
 }
 
@@ -2073,19 +2087,42 @@ function isYamHookProfile(handler: AnyRecord = {}, profile = 'lite') {
   return profile === 'study-note' ? isYamStudyNoteHook(handler) : isYamLiteHook(handler);
 }
 
+const CODEX_HOOK_EVENTS = new Set(['SessionStart', 'SessionEnd', 'PreToolUse', 'PermissionRequest', 'PostToolUse', 'PreCompact', 'PostCompact', 'UserPromptSubmit', 'SubagentStart', 'SubagentStop', 'Stop', 'Interrupt']);
+
+function hookEventMap(config: AnyRecord = {}) {
+  const nested = config.hooks && typeof config.hooks === 'object' && !Array.isArray(config.hooks) ? config.hooks : {};
+  const events = { ...nested };
+  for (const [event, entries] of Object.entries(config)) {
+    if (CODEX_HOOK_EVENTS.has(event) && Array.isArray(entries)) {
+      events[event] = [...(Array.isArray(events[event]) ? events[event] : []), ...entries];
+    }
+  }
+  return events;
+}
+
+function canonicalHookConfig(config: AnyRecord = {}) {
+  if (config.hooks != null && (typeof config.hooks !== 'object' || Array.isArray(config.hooks))) throw new Error('hooks must be an event object; existing file preserved');
+  const next = { ...config, hooks: hookEventMap(config) };
+  for (const event of CODEX_HOOK_EVENTS) {
+    if (event in config && !Array.isArray(config[event])) throw new Error('legacy hook event must be an array; existing file preserved');
+    delete next[event];
+  }
+  return next;
+}
+
 function stripYamHooks(config: AnyRecord = {}, profile = 'lite') {
-  const next = { ...config };
-  for (const event of Object.keys(next)) {
-    if (!Array.isArray(next[event])) continue;
-    const entries = next[event];
+  const next = canonicalHookConfig(config);
+  for (const event of Object.keys(next.hooks)) {
+    if (!Array.isArray(next.hooks[event])) continue;
+    const entries = next.hooks[event];
     const keptEntries = [];
     for (const entry of entries) {
       const hooks = Array.isArray(entry?.hooks) ? entry.hooks.filter((handler) => !isYamHookProfile(handler, profile)) : [];
       const rest = { ...entry, hooks };
       if (hooks.length > 0) keptEntries.push(rest);
     }
-    if (keptEntries.length > 0) next[event] = keptEntries;
-    else delete next[event];
+    if (keptEntries.length > 0) next.hooks[event] = keptEntries;
+    else delete next.hooks[event];
   }
   return next;
 }
@@ -2103,7 +2140,7 @@ function withYamHook(config: AnyRecord = {}, profile = 'lite') {
         }
       ]
     };
-    next[event] = [...(Array.isArray(next[event]) ? next[event] : []), entry];
+    next.hooks[event] = [...(Array.isArray(next.hooks[event]) ? next.hooks[event] : []), entry];
   }
   return next;
 }
@@ -2113,6 +2150,11 @@ async function hookStatus(args = []) {
   const target = hookPathFor(parsed);
   const loaded = await readHookConfig(target);
   if (loaded.error) {
+    if (args.includes('--json')) {
+      console.log(JSON.stringify({ schema: 'yam.hook-readiness.v1', scope: parsed.mode, configuration: 'unreadable', loaded: 'unknown', execution_observed: false, truth_status: 'partial' }, null, 2));
+      process.exitCode = 1;
+      return;
+    }
     console.log('yam-lite hook: broken');
     console.log('yam-study-note hook: broken');
     console.log(`  - hook config unreadable: ${loaded.error}`);
@@ -2123,10 +2165,28 @@ async function hookStatus(args = []) {
   }
   const lite = await inspectHookProfile(loaded.config, 'lite');
   const studyNote = await inspectHookProfile(loaded.config, 'study-note');
+  const cwd = path.resolve(parsed.projectDir || process.cwd());
+  const commands = { lite: lite.entries.map((entry) => String(entry.handler.command)), 'study-note': studyNote.entries.map((entry) => String(entry.handler.command)) };
+  const host = args.includes('--probe')
+    ? await probeHookDiscovery({ executable: await findExecutable('codex') || 'codex', cwd, commands, configPath: target })
+    : { state: 'not_measured', active_session_loaded: 'not_measured', execution_observed: false, truth_status: 'partial' };
+  const profiles = {};
+  for (const [profile, health] of [['lite', lite], ['study-note', studyNote]] as const) {
+    profiles[profile] = { configured: health.state, issues: health.issues, loaded: 'unknown',
+      execution: await inspectHookObservation(cwd, profile, YAM_HOOK_ENTRYPOINT) };
+  }
+  if (args.includes('--json')) {
+    console.log(JSON.stringify({ schema: 'yam.hook-readiness.v1', scope: parsed.mode, profiles, host, truth_status: 'partial' }, null, 2));
+    if (lite.state === 'broken' || studyNote.state === 'broken') process.exitCode = 1;
+    return;
+  }
   printHookProfileStatus('lite', lite);
   printHookProfileStatus('study-note', studyNote);
   console.log(`scope: ${parsed.mode}`);
   console.log(`file: ${target}`);
+  console.log('active Codex session loaded: unknown (configuration is not runtime evidence)');
+  console.log(`host discovery: ${host.state}`);
+  for (const profile of ['lite', 'study-note']) console.log(`yam-${profile} execution: ${profiles[profile].execution.state} (local entrypoint evidence, not host attestation)`);
   if (lite.state === 'broken' || studyNote.state === 'broken') process.exitCode = 1;
 }
 
@@ -2135,7 +2195,7 @@ function hookConfigHasYamLite(config = {}) {
 }
 
 function hookConfigHasProfile(config = {}, profile = 'lite') {
-  return Object.values(config).some((entries) => Array.isArray(entries) && entries.some((entry) => {
+  return Object.values(hookEventMap(config)).some((entries) => Array.isArray(entries) && entries.some((entry) => {
     return Array.isArray(entry?.hooks) && entry.hooks.some((handler) => isYamHookProfile(handler, profile));
   }));
 }
@@ -2150,7 +2210,7 @@ function hookEventsForProfile(profile = 'lite') {
 
 function hookProfileEntries(config: AnyRecord = {}, profile = 'lite') {
   const matches = [];
-  for (const [event, entries] of Object.entries(config)) {
+  for (const [event, entries] of Object.entries(hookEventMap(config))) {
     if (!Array.isArray(entries)) continue;
     for (const entry of entries) {
       if (!Array.isArray(entry?.hooks)) continue;
@@ -2209,6 +2269,7 @@ function splitHookCommand(command = '') {
 
 function parseYamHookCommand(command = '', profile = 'lite') {
   const words = splitHookCommand(command);
+  if (words.at(-1) === '--observe') words.pop();
   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') {
@@ -2249,6 +2310,7 @@ async function inspectHookProfile(config: AnyRecord = {}, profile = 'lite') {
   const entries = hookProfileEntries(config, profile);
   if (!entries.length) return { state: 'disabled', issues: [], entries };
   const issues = [];
+  if (Object.keys(config).some((event) => CODEX_HOOK_EVENTS.has(event))) issues.push('legacy hook config requires the top-level hooks wrapper; rerun yam hook enable to migrate with backup');
   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}`);
@@ -2275,6 +2337,9 @@ async function readHookConfig(target) {
     if (!value || Array.isArray(value) || typeof value !== 'object') {
       return { config: {}, exists: true, error: 'top-level value must be a JSON object' };
     }
+    if (value.hooks != null && (typeof value.hooks !== 'object' || Array.isArray(value.hooks))) {
+      return { config: {}, exists: true, error: 'hooks must be an event object' };
+    }
     return { config: value, exists: true, error: '' };
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { config: {}, exists: false, error: '' };
@@ -2294,8 +2359,34 @@ async function writeHookConfig(target, config) {
   }
 }
 
+async function hookMigrate(args = []) {
+  const parsed = parseHookArgs(args);
+  const target = hookPathFor(parsed);
+  const loaded = await readHookConfig(target);
+  if (loaded.error) { console.error('hook migration blocked: unreadable configuration'); process.exitCode = 1; return; }
+  if (!loaded.exists || !Object.keys(loaded.config).some((key) => CODEX_HOOK_EVENTS.has(key))) {
+    console.log('hook migration: no legacy event layout found'); return;
+  }
+  const before = await fsp.lstat(target);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) throw new Error('hook migration blocked: unsafe config file');
+  const original = await fsp.readFile(target, 'utf8');
+  if (JSON.stringify(JSON.parse(original)) !== JSON.stringify(loaded.config)) throw new Error('hook configuration changed; retry migration');
+  const next = canonicalHookConfig(loaded.config);
+  const backup = `${target}.yam-backup-${timestampId()}`;
+  await fsp.copyFile(target, backup, fs.constants.COPYFILE_EXCL);
+  const after = await fsp.lstat(target);
+  if (after.dev !== before.dev || after.ino !== before.ino || after.mtimeMs !== before.mtimeMs
+    || await fsp.readFile(target, 'utf8') !== original) throw new Error('hook configuration changed; backup preserved, retry migration');
+  await writeHookConfig(target, next);
+  console.log(`hook migration: wrapped event groups; handlers and metadata preserved\nbackup: ${backup}\nReview changed definitions in Codex /hooks before enabling execution.`);
+}
+
 async function hookEnable(args = []) {
   const parsed = parseHookArgs(args);
+  const node = await selectHookNode();
+  const observe = args.includes('--observe') ? ' --observe' : '';
+  YAM_LITE_HOOK_COMMAND = `${JSON.stringify(node.executable)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite${observe}`;
+  YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(node.executable)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note${observe}`;
   if (!['lite', 'study-note'].includes(parsed.profile)) {
     console.error('Only lite and study-note hooks are supported: yam hook enable <lite|study-note>');
     process.exitCode = 1;
@@ -2326,6 +2417,7 @@ async function hookEnable(args = []) {
   }
   await writeHookConfig(target, next);
   console.log(`yam-${parsed.profile} hook enabled (${parsed.mode}): ${target}`);
+  console.log(`node launcher: ${node.selection}; alias identity matched the current runtime (no PATH candidate executed)`);
   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.');
 }
@@ -2346,7 +2438,7 @@ async function hookDisable(args = []) {
     return;
   }
   const next = stripYamHooks(current, parsed.profile);
-  if (Object.keys(next).length === 0) {
+  if (Object.keys(next).length === 1 && Object.keys(next.hooks).length === 0) {
     await rmrf(target);
   } else {
     await writeHookConfig(target, next);
@@ -2374,13 +2466,14 @@ async function hookRun(args = []) {
   }
   const event = input?.hook_event_name || input?.hookEventName || input?.event || 'UserPromptSubmit';
   const cwd = String(input?.cwd || process.cwd());
+  if (args.includes('--observe')) await recordHookObservation(cwd, profile, String(event), YAM_HOOK_ENTRYPOINT).catch(() => {});
   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 })
+    ? await buildStudyNoteTurnContext(input, cwd)
     : await buildYamLiteContext({ cwd, prompt });
   const output = {
     continue: true,
@@ -2412,6 +2505,7 @@ function extractPrompt(input: AnyRecord = {}) {
 async function buildYamLiteContext({ cwd, prompt }) {
   const lines = [
     'yam-lite guide active: keep project direction visible, preserve momentum, and deepen when scope, risk, or user intent calls for it.',
+    'Git workflow: keep the current branch; create/switch branches, worktrees or PRs only on explicit user request or applicable project rule. Commit/push, release bumps, branch-name prefixes and protection alone do not authorize them. If blocked, report and ask; do not silently change workflow or protections.',
     'Default: do a basic direction-fit and honest-verification check; avoid broad reading for small work and never claim proof without evidence.'
   ];
   const pack = await findProjectPack(cwd).catch(() => null);
@@ -2427,38 +2521,10 @@ async function buildYamLiteContext({ cwd, prompt }) {
   return lines.join('\n');
 }
 
-async function buildStudyNoteHookContext({ cwd }) {
-  const dir = path.resolve(cwd || process.cwd());
-  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 followed immediately by Next step 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 Study Note followed by Next step 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 Study Note followed immediately by Next step 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(', ')}`);
-  lines.push('Study Note minimum: touched code/artifact, role, execution point, before/after change, expected behavior, one syntax/structure insight, verification, and limits.');
-  lines.push('Next step minimum: quick whole-process scan, current situation, forward outlook, critical opinion, improvement recommendation, ordered fix-first then planned actions, evidence, ownership, blocker status, safe retry, side effects, and truth status.');
-  const hygiene = studyNoteHygieneRequirements(changedFiles);
-  if (hygiene.length) {
-    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 prompt reminder does not generate or edit either section; the paired Stop hook requests one correction pass if the final response is incomplete or ordered incorrectly.');
-  return lines.join('\n');
-}
-
 async function buildStudyNoteStopOutput(input: AnyRecord = {}, cwd = process.cwd()) {
   const lastAssistantMessage = String(input?.last_assistant_message || input?.lastAssistantMessage || '');
-  const result = await buildStudyNoteGuardResult(path.resolve(cwd), lastAssistantMessage, 'stop_hook_last_assistant_message');
+  const scope = studyNoteTurnScope(input, cwd);
+  const result = await buildStudyNoteGuardResult(path.resolve(cwd), lastAssistantMessage, 'stop_hook_last_assistant_message', scope);
   if (result.truth_status === 'partial' && !result.changed_file_detection.available) {
     return {
       continue: true,
@@ -2466,7 +2532,11 @@ async function buildStudyNoteStopOutput(input: AnyRecord = {}, cwd = process.cwd
     };
   }
   if (!result.blockers.length) return { continue: true };
-  const summary = result.blockers.slice(0, 4).join('; ');
+  const failed = result.checks.filter(check => check.status === 'fail').map(check => check.id);
+  const summary = failed.includes('study_note_present') ? 'study_note_present' : failed.join(', ');
+  if (scope.mode !== 'strict') {
+    return { continue: true, systemMessage: `yam Study Note advisory — missing fields: ${summary}. Keep ordinary work concise; no correction gate applied.` };
+  }
   if (Boolean(input?.stop_hook_active || input?.stopHookActive)) {
     return {
       continue: true,
@@ -2476,13 +2546,18 @@ async function buildStudyNoteStopOutput(input: AnyRecord = {}, cwd = process.cwd
   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.'
+      `yam Study Note strict — missing fields: ${summary}.`,
+      'Revise only the missing fields in Study Note / Next step; this is report validation, not a security scan.'
     ].join(' ')
   };
 }
 
+async function buildStudyNoteTurnContext(input: AnyRecord, cwd: string) {
+  const scope = studyNoteTurnScope(input, cwd, true);
+  if (!scope.available) return 'yam Study Note: turn scope is unavailable; do not treat this as a clean project. Inspect changed artifacts manually; no strict block will be applied without a baseline.';
+  return `yam Study Note turn baseline saved (hash-only). Mode: ${scope.mode}. Only changes since this prompt count; known generated logs, mission/security receipts and screenshots are excluded unless explicitly included. Include a concise Study Note followed by Next step when product artifacts change. ${scope.mode === 'strict' ? 'Risk work uses the detailed report contract and one correction pass.' : 'Ordinary work is advisory: a short explanation, verification/limits and remaining work (or none) suffice.'}`;
+}
+
 function yamLiteRouteHint(prompt = '') {
   const text = String(prompt || '').toLowerCase();
   if (!text) return '';
@@ -6109,7 +6184,7 @@ async function memory(args = []) {
   }
   if (subcommand === 'summary' || subcommand === 'summarize') {
     const parsed = parseMemoryArgs(args.slice(1));
-    return memorySummary(parsed.dir);
+    return memorySummary(parsed.dir, { json: args.includes('--json') });
   }
   if (subcommand === 'resolve') return memoryResolve(args.slice(1));
   console.error(`unknown memory command: ${subcommand}`);
@@ -6123,7 +6198,7 @@ Usage:
   yam memory init [dir]
   yam memory add [dir] --kind <kind> --summary <text> [--evidence <text>] [--action <text>] [--source <text>]
   yam memory list [dir] [--json]
-  yam memory summary [dir]
+  yam memory summary [dir] [--json]
   yam memory resolve [dir] <id> [--note <text>]
 
 Kinds:
@@ -6198,7 +6273,14 @@ async function memoryAdd(args = []) {
 }
 
 async function memoryList(targetDir = process.cwd(), { json = false } = {}) {
-  const records = await readMemoryRecords(targetDir);
+  const report = await readMemoryRecords(targetDir);
+  const records = report.records;
+  if (!report.complete) {
+    if (report.state !== 'missing') process.exitCode = 1;
+    if (json) console.log(JSON.stringify(report, null, 2));
+    else console.error(`memory read ${report.state}: ${JSON.stringify(report.diagnostics)}${report.diagnostics_truncated ? ' (diagnostics truncated)' : ''}`);
+    return;
+  }
   if (json) {
     console.log(JSON.stringify(records, null, 2));
     return;
@@ -6213,9 +6295,16 @@ async function memoryList(targetDir = process.cwd(), { json = false } = {}) {
   }
 }
 
-async function memorySummary(targetDir = process.cwd()) {
+async function memorySummary(targetDir = process.cwd(), { json = false } = {}) {
   const dir = memoryDir(targetDir);
-  const records = await readMemoryRecords(targetDir);
+  const report = await readMemoryRecords(targetDir);
+  if (!report.complete) {
+    process.exitCode = 1;
+    if (json) console.log(JSON.stringify({ ...report, summary_written: false }, null, 2));
+    else console.error(`memory summary blocked (${report.state}); existing summary preserved: ${JSON.stringify(report.diagnostics)}${report.diagnostics_truncated ? ' (diagnostics truncated)' : ''}`);
+    return;
+  }
+  const records = report.records;
   await fsp.mkdir(dir, { recursive: true });
   const active = records.filter((record) => record.status !== 'resolved');
   const resolved = records.filter((record) => record.status === 'resolved');
@@ -6246,7 +6335,8 @@ async function memorySummary(targetDir = process.cwd()) {
 
   const target = path.join(dir, 'summary.md');
   await fsp.writeFile(target, `${lines.join('\n').trim()}\n`);
-  console.log(`memory summary written: ${target}`);
+  if (json) console.log(JSON.stringify({ ...report, summary_written: true, path: target }, null, 2));
+  else console.log(`memory summary written: ${target}`);
 }
 
 async function memoryResolve(args = []) {
@@ -6305,20 +6395,7 @@ function memoryDir(targetDir = process.cwd()) {
 
 async function readMemoryRecords(targetDir = process.cwd()) {
   const recordsDir = path.join(memoryDir(targetDir), 'records');
-  if (!await exists(recordsDir)) return [];
-  const entries = await fsp.readdir(recordsDir, { withFileTypes: true });
-  const records = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
-    const file = path.join(recordsDir, entry.name);
-    try {
-      const record = await readJson(file);
-      records.push(record);
-    } catch (error) {
-      records.push({ id: entry.name.replace(/\.json$/, ''), kind: 'invalid', status: 'invalid', summary: `invalid JSON: ${errorMessage(error)}` });
-    }
-  }
-  return records.sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+  return readMemoryDirectory(recordsDir);
 }
 
 function timestampId() {

package/src/lib/external-updates.ts

@@ -34,6 +34,7 @@ export interface ExternalUpdatePaths {
 export interface ExternalUpdateDependencies {
   run?: (command: string, args: string[], options?: ExternalCommandOptions) => Promise<ExternalCommandResult> | ExternalCommandResult;
   fetchJson?: (url: string) => Promise<any>;
+  probeArtifact?: (url: string) => Promise<number>;
   now?: () => Date;
   homeDir?: string;
   env?: NodeJS.ProcessEnv;
@@ -46,7 +47,7 @@ export interface ExternalComponentCheck {
   installed_version: string;
   latest_version: string;
   update_available: boolean;
-  status: 'up_to_date' | 'update_available' | 'not_installed' | 'check_failed';
+  status: 'up_to_date' | 'update_available' | 'not_installed' | 'pending_distribution' | 'check_failed';
   source: string;
   source_revision?: {
     local: string;
@@ -113,6 +114,7 @@ export interface YamInstallIdentity {
 interface ResolvedDependencies {
   run: NonNullable<ExternalUpdateDependencies['run']>;
   fetchJson: NonNullable<ExternalUpdateDependencies['fetchJson']>;
+  probeArtifact: NonNullable<ExternalUpdateDependencies['probeArtifact']>;
   now: NonNullable<ExternalUpdateDependencies['now']>;
   homeDir: string;
   env: NodeJS.ProcessEnv;
@@ -158,7 +160,7 @@ export async function checkExternalUpdates(
     checkScrapling(deps),
     checkInsaneSearch(deps)
   ]);
-  const failed = checks.filter((item) => item.status === 'check_failed');
+  const failed = checks.filter((item) => item.status === 'check_failed' || item.status === 'pending_distribution');
   return {
     schema: 'yam.external-update-check.v1',
     generated_at: deps.now().toISOString(),
@@ -351,6 +353,7 @@ async function resolveDependencies(input: ExternalUpdateDependencies): Promise<R
   return {
     run,
     fetchJson: input.fetchJson || defaultFetchJson,
+    probeArtifact: input.probeArtifact || defaultProbeArtifact,
     now: input.now || (() => new Date()),
     homeDir,
     env,
@@ -409,18 +412,52 @@ async function acquireApplyLock(deps: ResolvedDependencies) {
 }
 
 async function checkYam(currentYamVersion: string, deps: ResolvedDependencies): Promise<ExternalComponentCheck> {
+  let pending: ExternalComponentCheck | undefined;
   try {
     const data = await deps.fetchJson(YAM_REGISTRY_URL);
     const latest = requireStableVersion(data?.version, 'yam registry version');
     const installed = requireStableVersion(currentYamVersion, 'installed yam version');
     const integrity = requireIntegrityValue(data?.dist?.integrity, 'yam registry integrity');
     const revision = requireGitRevision(data?.gitHead, 'yam registry gitHead');
+    if (data?.name !== 'yam-flow') throw new Error('yam registry package name mismatch');
+    const tarball = requireYamTarball(data?.dist?.tarball, latest);
+    const exactUrl = `${NPM_REGISTRY}yam-flow/${latest}`;
+    pending = {
+      ...componentCheck('yam', installed, latest, 'npm:yam-flow'),
+      status: 'pending_distribution',
+      error: 'pending_distribution: exact-version metadata or tarball returned HTTP 404; retry the explicit update later',
+      source_receipt: {
+        canonical_url: YAM_REGISTRY_URL,
+        retrieved_at: deps.now().toISOString(),
+        access_path: 'npm latest observed; exact-version distribution readiness incomplete',
+        version: latest,
+        revision,
+        integrity: [integrity]
+      }
+    };
+    let exact: any;
+    try {
+      exact = await deps.fetchJson(exactUrl);
+    } catch (error) {
+      if (error instanceof RegistryHttpError && error.status === 404) return pending;
+      throw error;
+    }
+    if (exact?.name !== 'yam-flow' || data?.name !== 'yam-flow'
+      || requireStableVersion(exact?.version, 'yam exact registry version') !== latest
+      || requireIntegrityValue(exact?.dist?.integrity, 'yam exact registry integrity') !== integrity
+      || requireGitRevision(exact?.gitHead, 'yam exact registry gitHead') !== revision
+      || requireYamTarball(exact?.dist?.tarball, latest) !== tarball) {
+      throw new Error('yam latest and exact-version registry metadata disagree');
+    }
+    const artifactStatus = await deps.probeArtifact(tarball);
+    if (artifactStatus === 404) return pending;
+    if (artifactStatus !== 200) throw new Error(`yam tarball availability check failed: HTTP ${artifactStatus}`);
     return {
       ...componentCheck('yam', installed, latest, 'npm:yam-flow'),
       source_receipt: {
         canonical_url: YAM_REGISTRY_URL,
         retrieved_at: deps.now().toISOString(),
-        access_path: 'npm registry latest endpoint',
+        access_path: 'npm latest + exact-version metadata + bounded no-redirect tarball HEAD (availability only)',
         version: latest,
         revision,
         integrity: [integrity]
@@ -601,7 +638,7 @@ function failedCheck(
 
 async function applyYam(currentYamVersion: string, deps: ResolvedDependencies) {
   const check = await checkYam(currentYamVersion, deps);
-  if (check.status === 'check_failed') return persistFailureFromCheck(check, deps);
+  if (check.status === 'check_failed' || check.status === 'pending_distribution') return persistFailureFromCheck(check, deps);
   if (!check.update_available) {
     return persistReceipt(baseReceipt(check, 'up_to_date', [], {
       automatic: true,
@@ -1609,14 +1646,58 @@ async function defaultRun(command: string, args: string[], options: ExternalComm
 
 async function defaultFetchJson(url: string) {
   const response = await fetch(url, {
+    redirect: 'error',
+    credentials: 'omit',
     headers: {
       accept: 'application/json',
       'user-agent': 'yam-flow external-update-check'
     },
     signal: AbortSignal.timeout(30000)
   });
-  if (!response.ok) throw new Error(`HTTP ${response.status} for ${url}`);
-  return response.json();
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new RegistryHttpError(response.status, url);
+  }
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error(`empty registry response for ${url}`);
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 1024 * 1024) throw new Error('registry metadata exceeds 1 MiB limit');
+      chunks.push(chunk.value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+export class RegistryHttpError extends Error {
+  constructor(readonly status: number, url: string) {
+    super(`HTTP ${status} for ${url}`);
+  }
+}
+
+function requireYamTarball(value: unknown, version: string) {
+  const expected = `${NPM_REGISTRY}yam-flow/-/yam-flow-${version}.tgz`;
+  if (value !== expected) throw new Error('yam tarball must be the exact-version artifact on the official npm registry');
+  return expected;
+}
+
+async function defaultProbeArtifact(url: string) {
+  const response = await fetch(url, {
+    method: 'HEAD',
+    redirect: 'error',
+    credentials: 'omit',
+    headers: { 'user-agent': 'yam-flow external-update-check' },
+    signal: AbortSignal.timeout(10000)
+  });
+  await response.body?.cancel();
+  return response.status;
 }
 
 function requireStableVersion(value: unknown, label: string) {