yam-flow 2.8.0 → 2.8.2

package/references/study-note.md

@@ -48,6 +48,12 @@ Study Note:
 - Limits: this does not infer requirements from prose; the agent or user still has to provide them.
 ```
 
+## Security check in Yam note
+
+When documenting commit, push, or deployment security checks, include a separate `-- Security check --` block using `references/security-check.md` and `templates/security-check-note.md`. Every SEC ID must have a concrete Korean security explanation, its status, and supporting evidence or an explicit limitation. Keep this block outside the Study Note / Next step pair so their required adjacency is preserved.
+
+The security CLI appends this block to the configured note without adding a `yam note` command or changing `yam.study-note.v1`. Git hooks require explicit setup; remote CI/deployment enforcement requires project configuration.
+
 ## When Nothing Changed
 
 For pure Q&A, planning, scouting, or review with no changed artifact, do not force a Study Note. Say `No code or project artifact changed` when that prevents ambiguity.

package/skills/deep/SKILL.md

@@ -73,6 +73,10 @@ Stop condition:
 - Stop earlier when the same blocker repeats, a required tool/auth/runtime is unavailable, or a user decision is needed.
 - Do not keep retrying the same failure; classify the cause, give a recovery hint, and hand off.
 
+## Commit, push and deployment security gate
+
+Before performing a requested commit, push or deployment, follow `references/security-check.md`: validate stage-bound evidence with `yam security check`, require a successful persisted Security check note, and stop the operation when the gate blocks. If the project is not configured, report that blocker rather than claim security approval. Do not overwrite existing hooks or treat supplied evidence as an automatic vulnerability scan.
+
 ## Final Response
 
 Include:

package/skills/mission/SKILL.md

@@ -120,6 +120,10 @@ Good mission prompts include:
 
 If the user invokes `$mission` without an approved plan, ask for the plan or propose a compact plan first.
 
+## Commit, push and deployment security gate
+
+Before performing a requested commit, push or deployment, follow `references/security-check.md`: validate stage-bound evidence with `yam security check`, require a successful persisted Security check note, and stop the operation when the gate blocks. If the project is not configured, report that blocker rather than claim security approval. Do not overwrite existing hooks or treat supplied evidence as an automatic vulnerability scan.
+
 ## Final Response
 
 Report:

package/skills/quick/SKILL.md

@@ -74,6 +74,10 @@ Use `references/study-note.md` when any code, config, docs, or project artifact
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.
 
+## Commit, push and deployment security gate
+
+Before performing a requested commit, push or deployment, follow `references/security-check.md`: validate stage-bound evidence with `yam security check`, require a successful persisted Security check note, and stop the operation when the gate blocks. If the project is not configured, report that blocker rather than claim security approval. Do not overwrite existing hooks or treat supplied evidence as an automatic vulnerability scan.
+
 ## Final Response
 
 Keep it compact:

package/skills/ueye/SKILL.md

@@ -182,6 +182,10 @@ Always consider:
 - Interaction affordance.
 - Consistency with the project's visual language.
 
+## Commit, push and deployment security gate
+
+Before performing a requested commit, push or deployment, follow `references/security-check.md`: validate stage-bound evidence with `yam security check`, require a successful persisted Security check note, and stop the operation when the gate blocks. If the project is not configured, report that blocker rather than claim security approval. Do not overwrite existing hooks or treat supplied evidence as an automatic vulnerability scan.
+
 ## Final Response
 
 Report:

package/src/bin/yam.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+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';
 import fsp from 'node:fs/promises';
@@ -148,8 +151,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',
@@ -224,6 +227,7 @@ Usage:
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
   yam study-note check [dir] [--report file|--text text] [--json]
+  yam security <init|check|hooks|status> [--stage commit|push|ci|deploy] [--json]
   yam next-step <report|verify> [--spec file|--receipt file] [--json]
   yam loop report [--route route] [--intent text] [--stage id:status:note] [--evidence text] [--json]
   yam scout receipt <create|verify> [options]
@@ -249,7 +253,7 @@ Usage:
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
   yam hook <status|enable|disable|run> [lite|study-note] [--global|--project dir]
-  yam template <project|ueye|mission|proof|tuning>
+  yam template <project|ueye|mission|proof|tuning|security|security-ci>
   yam tune-log [dir]
   yam install [--dry-run] [--json] [--replace-user-skill name]
   yam uninstall
@@ -570,6 +574,7 @@ async function verify({ quiet = false } = {}) {
     'context-reuse.md',
     'markdown-management.md',
     'study-note.md',
+    'security-check.md',
     'final-report.md',
     'token-budget-reporter.md',
     'memory.md'
@@ -585,7 +590,7 @@ async function verify({ quiet = false } = {}) {
       if (!hasHeading(projectTemplate, section)) issues.push(`project template missing section: ${section}`);
     }
   }
-  for (const template of ['ueye-review.md', 'ueye-comparison.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md']) {
+  for (const template of ['ueye-review.md', 'ueye-comparison.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md', 'security-check-note.md', 'security-gate.yml']) {
     if (!await exists(path.join(ROOT, 'templates', template))) issues.push(`missing template: ${template}`);
   }
   for (const module of ['trust-kernel.js', 'ueye-artifacts.js']) {
@@ -2011,6 +2016,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));
@@ -2022,14 +2028,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.
 `);
 }
 
@@ -2054,7 +2063,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');
 }
 
@@ -2070,19 +2079,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;
 }
@@ -2100,7 +2132,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;
 }
@@ -2110,6 +2142,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}`);
@@ -2120,10 +2157,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;
 }
 
@@ -2132,7 +2187,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));
   }));
 }
@@ -2147,7 +2202,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;
@@ -2206,6 +2261,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') {
@@ -2246,6 +2302,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}`);
@@ -2272,6 +2329,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: '' };
@@ -2291,8 +2351,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;
@@ -2323,6 +2409,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.');
 }
@@ -2343,7 +2430,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);
@@ -2371,6 +2458,7 @@ 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;
@@ -6069,11 +6157,13 @@ async function printTemplate(name = '') {
     mission: 'mission-plan.md',
     proof: 'runtime-proof.md',
     runtime: 'runtime-proof.md',
-    tuning: 'tuning-log.md'
+    tuning: 'tuning-log.md',
+    security: 'security-check-note.md',
+    'security-ci': 'security-gate.yml'
   };
   const file = map[key];
   if (!file) {
-    console.error('usage: yam template <project|ueye|ueye-comparison|mission|proof|tuning>');
+    console.error('usage: yam template <project|ueye|ueye-comparison|mission|proof|tuning|security|security-ci>');
     process.exitCode = 1;
     return;
   }
@@ -6104,7 +6194,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}`);
@@ -6118,7 +6208,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:
@@ -6193,7 +6283,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;
@@ -6208,9 +6305,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');
@@ -6241,7 +6345,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 = []) {
@@ -6300,20 +6405,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() {
@@ -6349,6 +6441,7 @@ function showRequestedHelp(args: string[]) {
   }
 
   const commandUsage: Record<string, () => void> = {
+    security: () => console.log('yam security <init|check|hooks enable|status> [--stage commit|push|ci|deploy] [--policy file --policy-digest sha256 --evidence file --note file]\nSee references/security-check.md for exact bindings and CI/deploy trust configuration.'),
     context: contextUsage,
     cleanup: cleanupUsage,
     'study-note': studyNoteUsage,
@@ -6375,6 +6468,16 @@ async function main() {
   const command = args[0] || 'help';
   if (showRequestedHelp(args)) return;
   if (command === 'help') return usage();
+  if (command === 'security') {
+    if (args.length === 1 || ['help', '--help', '-h'].includes(args[1])) {
+      console.log('yam security <init|check|hooks enable|status> [--stage commit|push|ci|deploy] [--policy file --policy-digest sha256 --evidence file --note file]\nSee references/security-check.md for exact bindings and CI/deploy trust configuration.');
+      return;
+    }
+    const result = await runSecurityCommand(args.slice(1), { cwd: process.cwd(), cliPath: fileURLToPath(import.meta.url) });
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
   if (command === 'install') return install(args.slice(1));
   if (command === 'uninstall') return uninstall(args.slice(1));
   if (command === 'version') return console.log(VERSION);

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) {