yam-flow 2.8.1 → 2.8.3

package/src/lib/hook-readiness.ts

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const MAX_BYTES = 256 * 1024;
+const sha = (text: string) => createHash('sha256').update(text).digest('hex');
+
+/** Select an upgrade-stable alias only when it resolves to the running Node binary. */
+export async function selectHookNode(executable = process.execPath, searchPath = process.env.PATH || '') {
+  const real = await fsp.realpath(executable);
+  const running = await fsp.stat(real);
+  const candidates = searchPath.split(path.delimiter).filter((dir) => path.isAbsolute(dir))
+    .map((dir) => path.join(dir, process.platform === 'win32' ? 'node.exe' : 'node'));
+  for (const candidate of candidates) {
+    try {
+      const canonical = await fsp.realpath(candidate);
+      const stat = await fsp.stat(canonical);
+      await fsp.access(candidate, fs.constants.X_OK);
+      if (stat.isFile() && stat.dev === running.dev && stat.ino === running.ino && canonical === real) {
+        return { executable: candidate, canonical, selection: 'verified_runtime_alias', dev: stat.dev, ino: stat.ino };
+      }
+    } catch { /* An unverified PATH candidate is never executed. */ }
+  }
+  return { executable: real, canonical: real, selection: 'current_runtime_fallback', dev: running.dev, ino: running.ino };
+}
+
+export function summarizeHookDiscovery(value: unknown, cwd: string, commands: Record<string, string[]>, configPath?: string) {
+  const input = value as { data?: Array<{ cwd?: string; hooks?: Array<Record<string, unknown>>; errors?: unknown[]; warnings?: unknown[] }> };
+  if (!Array.isArray(input?.data)) return { state: 'unknown', reason: 'unsupported_response_schema', profiles: {} };
+  const entry = input.data.find((row) => row.cwd === cwd);
+  if (!entry || !Array.isArray(entry.hooks) || !Array.isArray(entry.errors) || !Array.isArray(entry.warnings)) {
+    return { state: 'unknown', reason: 'missing_cwd_or_unsupported_response', profiles: {} };
+  }
+  const profiles = Object.fromEntries(Object.entries(commands).map(([profile, expected]) => {
+    const matches = entry.hooks.filter((hook) => hook.handlerType === 'command' && expected.includes(String(hook.command))
+      && (!configPath || hook.sourcePath === configPath));
+    const approved = matches.filter((hook) => hook.enabled === true && ['trusted', 'managed'].includes(String(hook.trustStatus)));
+    const expectedEvents = profile === 'study-note' ? ['userPromptSubmit', 'stop'] : ['userPromptSubmit'];
+    return [profile, { state: matches.length ? 'discovered' : 'not_discovered', enabled_trusted: approved.length,
+      eligible_event_coverage: expectedEvents.every((event) => approved.filter((hook) => hook.eventName === event).length === 1),
+      discovered_count: matches.length, trust_statuses: [...new Set(matches.map((hook) => String(hook.trustStatus)))],
+      execution_observed: false }];
+  }));
+  return { state: entry.errors.length ? 'partial' : 'queried', reason: entry.errors.length ? 'host_discovery_errors' : '',
+    profiles, warning_count: entry.warnings.length, error_count: entry.errors.length };
+}
+
+/** Opt-in discovery in a new app-server process, not the active desktop session. */
+export async function probeHookDiscovery(options: { executable: string; cwd: string; commands: Record<string, string[]>; configPath?: string; timeoutMs?: number }) {
+  const timeoutMs = Math.min(Math.max(options.timeoutMs || 5000, 100), 10000);
+  return new Promise<Record<string, unknown>>((resolve) => {
+    let finished = false;
+    let stopping = false;
+    let failure = '';
+    let result: Record<string, unknown>;
+    let buffer = '';
+    let total = 0;
+    let timer: NodeJS.Timeout;
+    let killTimer: NodeJS.Timeout;
+    const child = spawn(options.executable, ['app-server'], { cwd: options.cwd, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    const stop = (reason = '') => {
+      if (stopping) return;
+      stopping = true;
+      failure = reason;
+      child.stdin.end();
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 500);
+    };
+    const send = (value: unknown) => { if (!stopping) child.stdin.write(`${JSON.stringify(value)}\n`); };
+    child.stdin.on('error', () => stop('protocol_stdin_failed'));
+    child.on('error', () => { failure = 'host_unavailable'; });
+    child.stderr.on('data', (chunk) => { total += chunk.length; if (total > MAX_BYTES) stop('output_limit'); });
+    child.stdout.on('data', (chunk) => {
+      total += chunk.length;
+      if (total > MAX_BYTES) return stop('output_limit');
+      buffer += chunk.toString('utf8');
+      let index: number;
+      while (!stopping && (index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+        let message;
+        try { message = JSON.parse(line); } catch { stop('invalid_protocol_json'); break; }
+        if (message.id === 0) {
+          if (message.error) { stop('initialization_rejected'); break; }
+          send({ method: 'initialized', params: {} });
+          send({ method: 'hooks/list', id: 1, params: { cwds: [options.cwd] } });
+        } else if (message.id === 1) {
+          if (message.error) { stop('hooks_list_unsupported_or_rejected'); break; }
+          result = summarizeHookDiscovery(message.result, options.cwd, options.commands, options.configPath);
+          stop();
+        } else if (message.id != null && message.method) {
+          stop('unexpected_server_request');
+        }
+      }
+    });
+    child.on('close', (_code, signal) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer); clearTimeout(killTimer);
+      resolve({ ...(result || { state: 'unknown', profiles: {} }), ...(failure ? { state: 'unknown', reason: failure } : {}),
+        host_context: 'separate_app_server_probe', active_session_loaded: 'not_measured',
+        execution_observed: false, process_exit_observed: true, termination_signal: signal || null,
+        truth_status: 'partial', reason: failure || (result ? result.reason : 'host_exited_before_response') });
+    });
+    timer = setTimeout(() => stop('probe_timeout'), timeoutMs);
+    send({ method: 'initialize', id: 0, params: { clientInfo: { name: 'yam_hook_probe', version: '1' }, capabilities: { experimentalApi: true } } });
+  });
+}
+
+async function safeObservationDirectory(cwd: string, create: boolean) {
+  const root = await fsp.realpath(cwd);
+  let current = root;
+  const identities: Array<{ target: string; dev: number; ino: number }> = [];
+  for (const part of ['', '.yam', 'hooks']) {
+    if (part) current = path.join(current, part);
+    if (create && part) await fsp.mkdir(current, { mode: 0o700 }).catch((error) => { if (error.code !== 'EEXIST') throw error; });
+    const stat = await fsp.lstat(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('unsafe_observation_directory');
+    identities.push({ target: current, dev: stat.dev, ino: stat.ino });
+  }
+  return { directory: current, identities };
+}
+
+async function checkParents(identities: Array<{ target: string; dev: number; ino: number }>) {
+  for (const identity of identities) {
+    const stat = await fsp.lstat(identity.target);
+    if (stat.isSymbolicLink() || !stat.isDirectory() || stat.dev !== identity.dev || stat.ino !== identity.ino) throw new Error('observation_parent_changed');
+  }
+}
+
+async function configurationDigest(cwd: string) {
+  const paths = [path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'hooks.json'), path.join(await fsp.realpath(cwd), '.codex', 'hooks.json')];
+  const values = [];
+  for (const target of paths) {
+    try {
+      const before = await fsp.lstat(target);
+      if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_BYTES) throw new Error('unsafe_hook_configuration');
+      const handle = await fsp.open(target, fs.constants.O_RDONLY | (process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0));
+      try {
+        const stat = await handle.stat();
+        if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > MAX_BYTES) throw new Error('hook_configuration_changed');
+        const buffer = Buffer.alloc(MAX_BYTES + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > MAX_BYTES) throw new Error('hook_configuration_limit');
+        values.push(sha(buffer.subarray(0, bytesRead).toString('utf8')));
+      } finally { await handle.close(); }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      values.push('absent');
+    }
+  }
+  return sha(JSON.stringify(values));
+}
+
+export async function recordHookObservation(cwd: string, profile: string, event: string, entrypoint: string) {
+  if (!['lite', 'study-note'].includes(profile) || !['UserPromptSubmit', 'Stop'].includes(event)) throw new Error('unsupported_observation');
+  const { directory, identities } = await safeObservationDirectory(cwd, true);
+  const value = { schema: 'yam.hook-observation.v1', profile, event, observed_at: new Date().toISOString(),
+    cwd_digest: sha(await fsp.realpath(cwd)), entrypoint_digest: sha(await fsp.readFile(entrypoint, 'utf8')),
+    configuration_digest: await configurationDigest(cwd),
+    host_authenticated: false, evidence_kind: 'local_entrypoint_invocation' };
+  const target = path.join(directory, `${profile}.json`);
+  const noFollow = process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0;
+  const before = await fsp.lstat(target).catch((error) => { if (error.code === 'ENOENT') return null; throw error; });
+  if (before && (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)) throw new Error('unsafe_observation_file');
+  const handle = await fsp.open(target, fs.constants.O_WRONLY | noFollow | (before ? 0 : fs.constants.O_CREAT | fs.constants.O_EXCL), 0o600);
+  try {
+    const stat = await handle.stat();
+    const pathname = await fsp.lstat(target);
+    if (!stat.isFile() || stat.nlink !== 1 || pathname.isSymbolicLink() || pathname.dev !== stat.dev || pathname.ino !== stat.ino
+      || (before && (before.dev !== stat.dev || before.ino !== stat.ino))) throw new Error('unsafe_observation_file');
+    await checkParents(identities);
+    await handle.chmod(0o600);
+    await handle.truncate(0);
+    await handle.writeFile(`${JSON.stringify(value)}\n`);
+    await checkParents(identities);
+    const after = await fsp.lstat(target);
+    if (after.isSymbolicLink() || after.dev !== stat.dev || after.ino !== stat.ino) throw new Error('observation_identity_changed');
+  } finally { await handle.close(); }
+}
+
+export async function inspectHookObservation(cwd: string, profile: string, entrypoint: string) {
+  try {
+    if (!['lite', 'study-note'].includes(profile)) throw new Error('unsupported_profile');
+    const { directory, identities } = await safeObservationDirectory(cwd, false);
+    const target = path.join(directory, `${profile}.json`);
+    const before = await fsp.lstat(target);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 4096 || before.nlink !== 1) throw new Error('unsafe_observation_file');
+    const handle = await fsp.open(target, fs.constants.O_RDONLY | (process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0));
+    let value;
+    try {
+      const stat = await handle.stat();
+      if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > 4096) throw new Error('observation_identity_changed');
+      const data = Buffer.alloc(4097); const { bytesRead } = await handle.read(data, 0, data.length, 0);
+      if (bytesRead > 4096) throw new Error('observation_limit');
+      value = JSON.parse(data.subarray(0, bytesRead).toString('utf8'));
+      await checkParents(identities);
+    } finally { await handle.close(); }
+    const age = Date.now() - Date.parse(value.observed_at);
+    if (value.schema !== 'yam.hook-observation.v1' || value.profile !== profile || !['UserPromptSubmit', 'Stop'].includes(value.event)
+      || value.host_authenticated !== false || value.evidence_kind !== 'local_entrypoint_invocation'
+      || !Number.isFinite(age) || age < 0 || age > 24 * 60 * 60 * 1000
+      || value.cwd_digest !== sha(await fsp.realpath(cwd)) || value.configuration_digest !== await configurationDigest(cwd)
+      || value.entrypoint_digest !== sha(await fsp.readFile(entrypoint, 'utf8'))) {
+      return { state: 'unknown', reason: 'stale_or_mismatched_observation', truth_status: 'partial', host_authenticated: false };
+    }
+    return { state: 'entrypoint_observed', observed_at: value.observed_at, event: value.event,
+      host_authenticated: false, truth_status: 'partial', reason: 'local_same_user_evidence_not_host_attestation' };
+  } catch (error) {
+    return { state: 'not_observed', reason: (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'no_observation' : 'observation_unreadable_or_unsafe',
+      host_authenticated: false, truth_status: 'partial' };
+  }
+}

package/src/lib/memory-records.ts

@@ -0,0 +1,109 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+export type MemoryReadState = 'missing' | 'empty' | 'complete' | 'unreadable' | 'invalid' | 'incomplete';
+export interface MemoryRecord {
+  schemaVersion: number;
+  id: string;
+  kind: string;
+  status: string;
+  summary: string;
+  evidence?: string;
+  action?: string;
+  source?: string;
+  createdAt?: string;
+  [key: string]: unknown;
+}
+export interface MemoryReadReport {
+  schema: 'yam.memory-read.v1';
+  state: MemoryReadState;
+  complete: boolean;
+  records: MemoryRecord[];
+  diagnostics: Array<{ operation: string; code: string; record_index?: number }>;
+  diagnostics_truncated: boolean;
+}
+export type MemoryReadIo = Pick<typeof fsp, 'access' | 'readdir' | 'readFile'>;
+const kinds = new Set(['wrong_decision', 'repeat_mistake', 'direction_change', 'lesson', 'risk', 'command']);
+const safeCodes = new Set(['ENOENT', 'EACCES', 'EPERM', 'EIO', 'ENOTDIR', 'EISDIR', 'EMFILE', 'ENFILE', 'ELOOP']);
+
+function errorCode(error: unknown): string {
+  const code = (error as { code?: unknown })?.code;
+  return typeof code === 'string' && safeCodes.has(code) ? code : 'READ_FAILED';
+}
+
+function isMemoryRecord(value: unknown): value is MemoryRecord {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const r = value as Record<string, unknown>;
+  return r.schemaVersion === 1 && typeof r.id === 'string' && r.id.length > 0
+    && typeof r.kind === 'string' && kinds.has(r.kind)
+    && (r.status === 'active' || r.status === 'resolved')
+    && typeof r.summary === 'string' && r.summary.trim().length > 0
+    && ['evidence', 'action', 'source', 'createdAt', 'resolvedAt', 'resolution'].every((key) => r[key] === undefined || typeof r[key] === 'string');
+}
+
+/** Diagnostics intentionally contain no filesystem paths, record text, or exception messages. */
+export async function readMemoryDirectory(recordsDir: string, io: MemoryReadIo = fsp): Promise<MemoryReadReport> {
+  const report: MemoryReadReport = {
+    schema: 'yam.memory-read.v1', state: 'complete', complete: true,
+    records: [], diagnostics: [], diagnostics_truncated: false
+  };
+  const diagnose = (operation: string, code: string, record_index?: number) => {
+    if (report.diagnostics.length < 20) report.diagnostics.push({ operation, code, ...(record_index === undefined ? {} : { record_index }) });
+    else report.diagnostics_truncated = true;
+  };
+  try {
+    await io.access(recordsDir);
+  } catch (error) {
+    const code = errorCode(error);
+    report.state = code === 'ENOENT' ? 'missing' : 'unreadable';
+    report.complete = false;
+    diagnose('access', code);
+    return report;
+  }
+  let entries;
+  try {
+    entries = await io.readdir(recordsDir, { withFileTypes: true });
+  } catch (error) {
+    // An existing directory disappearing mid-read is incomplete, not an empty memory.
+    report.state = errorCode(error) === 'ENOENT' ? 'incomplete' : 'unreadable';
+    report.complete = false;
+    diagnose('readdir', errorCode(error));
+    return report;
+  }
+  let invalid = 0;
+  let unreadable = 0;
+  const candidates = entries.filter((entry) => entry.name.endsWith('.json')).sort((a, b) => a.name.localeCompare(b.name));
+  for (const [index, entry] of candidates.entries()) {
+    if (!entry.isFile()) {
+      unreadable += 1;
+      diagnose('record_type', 'NOT_REGULAR_FILE', index);
+      continue;
+    }
+    let text: string;
+    try {
+      text = await io.readFile(path.join(recordsDir, entry.name), 'utf8');
+    } catch (error) {
+      unreadable += 1;
+      diagnose('read', errorCode(error), index);
+      continue;
+    }
+    let record: unknown;
+    try { record = JSON.parse(text); } catch {
+      invalid += 1;
+      diagnose('parse', 'INVALID_JSON', index);
+      continue;
+    }
+    if (!isMemoryRecord(record)) {
+      invalid += 1;
+      diagnose('validate', 'INVALID_RECORD', index);
+      continue;
+    }
+    report.records.push(record);
+  }
+  report.records.sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+  report.complete = invalid + unreadable === 0;
+  report.state = report.complete ? (report.records.length ? 'complete' : 'empty')
+    : report.records.length || (invalid && unreadable) ? 'incomplete'
+      : unreadable ? 'unreadable' : 'invalid';
+  return report;
+}

package/src/lib/study-note-scope.ts

@@ -0,0 +1,134 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const hash = (value: string | Buffer) => createHash('sha256').update(value).digest('hex');
+const MAX_FILES = 4000;
+const MAX_BYTES = 2 * 1024 * 1024;
+type Snapshot = { root: string; files: Record<string, string> };
+type Policy = { include: string[]; exclude: string[]; strict: boolean };
+
+function git(dir: string, args: string[]) {
+  const result = spawnSync('git', args, { cwd: dir, encoding: 'utf8', timeout: 750, maxBuffer: MAX_BYTES,
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
+  if (result.status !== 0) throw new Error('git_scope_unavailable');
+  return result.stdout;
+}
+
+function snapshot(dir: string): Snapshot {
+  const root = fs.realpathSync(git(dir, ['rev-parse', '--show-toplevel']).trim());
+  const config = policy(root);
+  const files: Record<string, string> = Object.create(null);
+  let bytesRead = 0;
+  const tracked = git(root, ['ls-files', '--stage', '-z']).split('\0').filter(Boolean);
+  for (const row of tracked) {
+    const tab = row.indexOf('\t');
+    if (selected(row.slice(tab + 1), config)) files[row.slice(tab + 1)] = hash(row.slice(0, tab));
+  }
+  const rows = git(root, ['status', '--short', '-z', '--untracked-files=all']).split('\0');
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    if (!row) continue;
+    const name = row.slice(3);
+    if (/[RC]/.test(row.slice(0, 2))) i++;
+    if (!selected(name, config)) continue;
+    const target = path.resolve(root, name);
+    if (!target.startsWith(root + path.sep)) throw new Error('unsafe_path');
+    // Do not follow symlinks, including symlinked parent directories.
+    let parent = path.dirname(target);
+    while (parent !== root) {
+      try { if (fs.lstatSync(parent).isSymbolicLink()) throw new Error('unsafe_path'); }
+      catch (error: any) { if (error.code !== 'ENOENT') throw error; }
+      parent = path.dirname(parent);
+    }
+    let content = 'missing';
+    try {
+      const stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) content = 'link:' + hash(fs.readlinkSync(target));
+      else if (stat.isFile() && (bytesRead += stat.size) <= MAX_BYTES) content = hash(fs.readFileSync(target));
+      else throw new Error('scope_limit');
+    } catch (error: any) { if (error.code !== 'ENOENT') throw error; }
+    files[name] = hash(JSON.stringify([row.slice(0, 2), files[name] || '', content]));
+  }
+  if (Object.keys(files).length > MAX_FILES) throw new Error('scope_limit');
+  return { root, files };
+}
+
+function policy(root: string): Policy {
+  const target = path.join(root, '.yam', 'study-note.json');
+  let value: any = {};
+  if (fs.existsSync(target)) {
+    if (fs.lstatSync(path.dirname(target)).isSymbolicLink() || fs.lstatSync(target).isSymbolicLink()
+      || fs.statSync(target).size > 16384) throw new Error('invalid_policy');
+    value = JSON.parse(fs.readFileSync(target, 'utf8'));
+    if (!value || !['advisory', 'strict', undefined].includes(value.mode)) throw new Error('invalid_policy');
+  }
+  const list = (key: string) => {
+    const result = value[key] || [];
+    if (!Array.isArray(result) || result.length > 100 || result.some((x: any) => typeof x !== 'string'
+      || !x || x.startsWith('/') || x.includes('..') || /[\\\0]/.test(x) || x.replace(/\/\*\*$/, '').includes('*'))) throw new Error('invalid_policy');
+    return result;
+  };
+  return { include: list('include'), exclude: list('exclude'), strict: value.mode === 'strict' };
+}
+
+const matches = (name: string, pattern: string) => pattern.endsWith('/**')
+  ? name.startsWith(pattern.slice(0, -2)) : name === pattern;
+function selected(name: string, config: Policy) {
+  if (config.include.some(p => matches(name, p))) return true;
+  if (config.exclude.some(p => matches(name, p))) return false;
+  return !/^(dist\/|\.yam\/(mission|security|logs|screenshots)\/)/.test(name)
+    && !/\.tgz$/.test(name);
+}
+
+function statePath(root: string, session: string) {
+  const dir = path.join(os.tmpdir(), `yam-study-note-${process.getuid?.() ?? 'user'}`);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(dir);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid())
+    || (process.platform !== 'win32' && (stat.mode & 0o077))) throw new Error('unsafe_state');
+  return path.join(dir, hash(root + '\0' + session) + '.json');
+}
+
+/** Hash-only, bounded scope evidence; not a security attestation. */
+export function studyNoteTurnScope(input: any, cwd: string, begin = false) {
+  try {
+    const session = String(input.session_id || input.sessionId || input.thread_id || '');
+    const turn = String(input.turn_id || input.turnId || '');
+    if (!session || session.length > 512 || turn.length > 512) throw new Error('session_unavailable');
+    const current = snapshot(cwd);
+    const config = policy(current.root);
+    const target = statePath(current.root, session);
+    if (begin) {
+      const prompt = String(input.prompt || input.user_prompt || '');
+      // Deep/Mission alone do not make a read-only task strict. Risk intent or explicit strict does.
+      const strict = config.strict || /(?:study-note\s+strict|strict\s+study.note|commit|push|deploy|publish|security|migration|database|\bDB\b|커밋|푸시|배포|보안|마이그레이션|데이터베이스)/i.test(prompt);
+      const state = { schema: 'yam.study-note-baseline.v1', created: Date.now(), turn, strict, ...current };
+      try {
+        const previous = fs.lstatSync(target);
+        if (!previous.isFile() || previous.isSymbolicLink() || previous.nlink !== 1
+          || (process.getuid && previous.uid !== process.getuid())) throw new Error('unsafe_state');
+      } catch (error: any) { if (error.code !== 'ENOENT') throw error; }
+      const fd = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | (fs.constants.O_NOFOLLOW || 0), 0o600);
+      try { fs.writeFileSync(fd, JSON.stringify(state)); } finally { fs.closeSync(fd); }
+      return { available: true, files: [], source: 'turn_baseline', mode: strict ? 'strict' : 'advisory', reason: '' };
+    }
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_BYTES) throw new Error('invalid_baseline');
+    const before = JSON.parse(fs.readFileSync(target, 'utf8'));
+    if (before.schema !== 'yam.study-note-baseline.v1' || before.root !== current.root
+      || !before.files || typeof before.files !== 'object' || Array.isArray(before.files)
+      || !Number.isFinite(before.created) || typeof before.strict !== 'boolean'
+      || Object.keys(before.files).length > MAX_FILES
+      || Object.values(before.files).some(value => typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value))
+      || Date.now() - before.created > 24 * 60 * 60 * 1000 || before.created > Date.now()
+      || (turn && before.turn !== turn)) throw new Error('stale_baseline');
+    const files = [...new Set([...Object.keys(before.files), ...Object.keys(current.files)])]
+      .filter(name => before.files[name] !== current.files[name] && selected(name, config));
+    return { available: true, files, source: 'turn_baseline', mode: config.strict || before.strict ? 'strict' : 'advisory', reason: '' };
+  } catch {
+    return { available: false, files: [], source: 'turn_baseline', mode: 'advisory', reason: 'baseline_unavailable; inspect changed artifacts manually' };
+  }
+}

package/yam.manifest.json

@@ -1,8 +1,9 @@
 {
   "name": "yam",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "principles": [
     "Direction before execution.",
+    "Keep the current branch; new/switched branches, worktrees and PRs require explicit user direction or applicable project rules. Protection blockers require reporting, not silent workflow changes or bypass.",
     "Start fast.",
     "Deepen deliberately.",
     "Basic direction fit and honest verification always.",
@@ -13,12 +14,12 @@
     "Context-reuse first.",
     "End with remaining tasks and fix-first items.",
     "When code, config, release metadata, documentation, or project artifacts changed, include a Study Note even if no yam skill was explicitly invoked.",
-    "When the opt-in Study Note hook is enabled, check the final response at Codex Stop and request one bounded correction pass instead of relying only on prompt-time advice.",
+    "When the opt-in Study Note hook is enabled, compare against a hash-only turn baseline; ordinary work is advisory and selected risky changes request at most one strict correction pass.",
     "Explain what changed, what role it has, where it runs or is read, what was wrong or missing when relevant, before/after behavior, expected behavior, and one useful syntax or structure insight in short non-specialist language.",
     "When relevant, include architecture hygiene: avoid dumping unrelated logic into page.tsx, one-off component CSS into global.css, or structured product data into broad DB jsonb blobs when better project boundaries exist.",
     "Use handoff notes for fix-first items, remaining tasks, recommended next direction, requirement coverage, blocker kind, failure cause, recovery hint, safe retry, evidence level, and owner scope when useful.",
     "Use bounded heavy verification for serious claims, with explicit stop conditions instead of endless proof loops.",
-    "After changed artifacts, put an evidence-bound Next step immediately after Study Note with a whole-process scan, critical opinion, recommendations, and fix-first-before-planned ordering."
+    "After changed artifacts, put Next step immediately after Study Note; ordinary work stays brief, while strict reports use evidence-bound whole-process scanning and fix-first-before-planned ordering."
   ],
   "defaultHooks": false,
   "routes": [