yam-flow 2.8.2 → 2.8.3

package/AGENTS.md

@@ -21,7 +21,8 @@
 19. Treat security as the first project lens: identify sensitive surfaces early and guide safer defaults before convenience.
 20. Keep final reports short and concrete, but always include remaining tasks or state that none are meaningful.
 21. When relevant, include architecture hygiene in the Study Note: avoid dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs when existing project boundaries, scoped styles, typed tables, constraints, or indexes fit better.
-22. When an artifact changed, put `Next step` immediately after Study Note. Build it from a quick whole-process scan with current situation, forward outlook, a concrete critical opinion, improvement recommendations, and ordered fix-first then planned actions with evidence and ownership; do not merely rename remaining tasks.
+22. When an artifact changed, put `Next step` immediately after Study Note. Ordinary advisory work may use a short concrete action or state that none remains. For risky changes, explicit strict reports and structured receipts, build it from a quick whole-process scan with current situation, forward outlook, a concrete critical opinion, improvement recommendations, and ordered fix-first then planned actions with evidence and ownership. Keep report validation separate from actual security verification.
+23. Work on the current branch by default. Create or switch branches, create worktrees, or create pull requests only when the user explicitly requests that action or an applicable project rule explicitly requires it. A commit/push request, release version bump, route selection, branch-name prefix, or branch protection alone is not authorization. If protection blocks the requested operation, report the blocker and ask for direction; do not silently choose a PR workflow, bypass checks, or change protection settings.
 
 ## Security check gate
 

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.8.3 - 2026-10-06
+
+### Improved
+
+- Study Note hooks compare bounded hash-only turn baselines instead of repeatedly treating pre-existing dirty files as new work; already-dirty edits, staging, commits, renames and deletions remain visible.
+- Ordinary work uses advisory completion with concise notes; risky intent or explicit strict policy uses one bounded correction pass only when selected artifacts changed. Missing session or stale scope stays partial and requests manual inspection.
+- Known generated outputs are excluded before content reads, with project include rules taking precedence over excludes; independent commit/push/deploy security gates remain unchanged.
+- Standalone bold report headings are accepted, correction messages list missing fields, and migration documentation no longer triggers database hygiene based only on its name.
+- Report guidance and Quick route now distinguish ordinary advisory handoffs from detailed strict reports.
+- All routes and lite hook guidance keep the current branch by default; new/switched branches, worktrees and PRs require explicit user direction or applicable project rules. Protection blockers are reported without silently changing workflow or settings.
+
+### Verification
+
+- Turn-scope, generated/include precedence, advisory/strict, stale/corrupt baseline and symlink safety fixtures; hook latency and packaged CLI regressions.
+
 ## v2.8.2 - 2026-10-02
 
 ### Improved

package/README.md

@@ -39,13 +39,14 @@ See `ROADMAP.md` for remaining implementation stages.
 - No automatic Team routing.
 - No automatic proof loops.
 - No automatic tmux.
+- Keep the current branch by default. New/switched branches, worktrees and PRs require explicit user direction or an applicable project rule; commit/push, release bumps and protection rules alone do not authorize them. Report protection blockers before changing workflow or settings.
 - No false completion claims: verification, cleanup, and visual checks must match actual evidence.
 - `yam` is not lightweight-only; it is progressive: fast direction, broader judgment when useful, stronger proof as scope/risk grows.
 - Every route should check project direction and use the L0-L5 Verification Ladder honestly.
 - Small work stays small, but serious work is allowed to become serious.
 - Security-sensitive work is never treated as ordinary polish.
 - When code, config, release metadata, documentation, or project artifacts changed, final reports include a Study Note even if no yam skill was invoked.
-- A changed-artifact report puts `Next step` immediately after Study Note. It rescans the whole process, states the situation and outlook, adds a critical opinion and improvement recommendations, then orders fix-first work before planned work.
+- A changed-artifact report puts `Next step` immediately after Study Note. Ordinary advisory work may state the next concrete action or no remaining work. Strict reports rescan the whole process, state situation/outlook, add critical opinion and recommendations, then order fix-first work before planned work.
 - Useful Study Notes explain what the changed code or artifact does, what role it has, what was wrong or missing, what changed, what behavior is expected, one small syntax/structure insight, what was verified, and what remains uncertain.
 - Research and reference scans should keep source boundaries clear, then rework good ideas into yam style.
 - Token economy is part of quality.
@@ -102,7 +103,11 @@ yam hook enable study-note --global
 yam hook status --global
 ```
 
-The profile installs `UserPromptSubmit` and `Stop` handlers. At `Stop`, yam checks the latest assistant message with the same read-only Study Note Guard used by `yam study-note check`. If changed artifacts lack the required role, execution point, before/after, expected behavior, syntax/structure, verification, limits, or relevant architecture hygiene, Codex receives one correction prompt. A second failed check warns but does not loop forever. If Git change scope is unavailable, the guard reports partial truth and keeps a manual-inspection warning visible instead of claiming the project is clean. The hook never writes the Study Note or runs verification for the agent.
+The profile installs `UserPromptSubmit` and `Stop` handlers. The prompt saves a bounded, hash-only baseline of index and dirty-file content in a private OS temporary directory, keyed by canonical repository and session (and checked against a turn ID when supplied). Stop inspects only subsequent changes, including edits to already-dirty files, staging, commits, renames and deletions. Missing/stale scope stays partial with manual-inspection guidance; it never means a clean project.
+
+Ordinary hook work is advisory: a short Study Note (role, verification and limits) followed by Next step, including “no remaining work”, is sufficient. An explicit `study-note strict` request, project strict policy, or commit/push/deploy/DB/security intent enables the detailed contract **only when selected artifacts changed**. Deep/Mission names alone do not enable strict. Strict requests at most one correction; messages list missing fields. `yam study-note check` remains an explicit strict whole-tree check for compatibility. Neither mode performs security verification; commit/push/deploy security gates remain separate and unchanged.
+
+Known generated `.yam/mission/`, `.yam/security/`, `.yam/logs/`, `.yam/screenshots/`, `dist/` and `.tgz` outputs are excluded from automatic turn reporting. This is not a blanket `.yam` exclusion. Optional `.yam/study-note.json` accepts `mode: "advisory" | "strict"`, `include` and `exclude` arrays of repository-relative exact paths or `directory/**` prefixes; include wins. Example: `{"include":[".yam/security/review.json"],"exclude":["fixtures/generated/**"]}`. Baselines expire after 24 hours and contain paths/digests, not source text or prompts. Without a turn ID the latest baseline for the session is used; overlapping turns cannot be independently attributed. Bounded snapshots (4,000 files, 2 MiB dirty content) fall back to manual inspection. The hook never writes the report, changes global configuration or bypasses a security gate.
 
 Hook stdin is limited to 1 MiB. Malformed JSON or an oversized payload produces a valid fail-open response without echoing the rejected content, deriving hook context from it, or mutating the workspace. Other CLI commands that read piped text use a 4 MiB limit and fail closed when it is exceeded.
 

package/dist/bin/yam.js

@@ -1,5 +1,6 @@
 #!/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';
@@ -934,8 +935,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 = null) {
+    const changedFileDetection = scope || gitChangedFileSnapshot(dir);
     const changedFiles = changedFileDetection.files;
     const changeScopeAvailable = changedFileDetection.available;
     const needsStudyNote = changeScopeAvailable && changedFiles.length > 0;
@@ -966,6 +967,14 @@ 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',
@@ -1054,7 +1063,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] || '';
@@ -1178,7 +1187,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;
@@ -2416,7 +2425,7 @@ async function hookRun(args = []) {
     }
     const prompt = extractPrompt(input);
     const additionalContext = profile === 'study-note'
-        ? await buildStudyNoteHookContext({ cwd })
+        ? await buildStudyNoteTurnContext(input, cwd)
         : await buildYamLiteContext({ cwd, prompt });
     const output = {
         continue: true,
@@ -2445,6 +2454,7 @@ function extractPrompt(input = {}) {
 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);
@@ -2464,37 +2474,10 @@ async function buildYamLiteContext({ cwd, prompt }) {
         lines.push(routeHint);
     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 = {}, 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,
@@ -2503,7 +2486,11 @@ async function buildStudyNoteStopOutput(input = {}, 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,
@@ -2513,12 +2500,17 @@ async function buildStudyNoteStopOutput(input = {}, 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, cwd) {
+    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)

package/dist/lib/study-note-scope.d.ts

@@ -0,0 +1,8 @@
+/** Hash-only, bounded scope evidence; not a security attestation. */
+export declare function studyNoteTurnScope(input: any, cwd: string, begin?: boolean): {
+    available: boolean;
+    files: string[];
+    source: string;
+    mode: string;
+    reason: string;
+};

package/dist/lib/study-note-scope.js

@@ -0,0 +1,165 @@
+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) => createHash('sha256').update(value).digest('hex');
+const MAX_FILES = 4000;
+const MAX_BYTES = 2 * 1024 * 1024;
+function git(dir, args) {
+    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) {
+    const root = fs.realpathSync(git(dir, ['rev-parse', '--show-toplevel']).trim());
+    const config = policy(root);
+    const files = 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) {
+                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) {
+            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) {
+    const target = path.join(root, '.yam', 'study-note.json');
+    let value = {};
+    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) => {
+        const result = value[key] || [];
+        if (!Array.isArray(result) || result.length > 100 || result.some((x) => 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, pattern) => pattern.endsWith('/**')
+    ? name.startsWith(pattern.slice(0, -2)) : name === pattern;
+function selected(name, config) {
+    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, session) {
+    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, cwd, 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) {
+                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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -69,6 +69,7 @@
     "forbidden-names:check": "node ./scripts/check-forbidden-names.mjs",
     "workflow-pins:check": "node ./scripts/check-workflow-pins.mjs",
     "study-note:check": "node ./dist/bin/yam.js study-note check --json",
+    "study-note-turn-smoke": "node ./scripts/study-note-turn-smoke.mjs",
     "package-boundary:check": "node ./scripts/check-package-boundary.mjs",
     "package-secrets:check": "node ./scripts/check-package-secrets.mjs",
     "package-secrets-smoke": "node ./scripts/package-secrets-smoke.mjs",
@@ -86,7 +87,7 @@
     "trust-adoptions-smoke": "npm run build && node ./scripts/trust-adoptions-smoke.mjs",
     "design-production-smoke": "npm run build && node ./scripts/design-production-smoke.mjs",
     "phase-adoptions-smoke": "npm run build && node ./scripts/phase-adoptions-smoke.mjs",
-    "hook-latency-smoke": "node ./scripts/hook-latency-smoke.mjs",
+    "hook-latency-smoke": "node ./scripts/hook-latency-smoke.mjs && node ./scripts/study-note-turn-smoke.mjs",
     "install-transaction-smoke": "npm run build && node ./scripts/install-transaction-smoke.mjs",
     "next-step-smoke": "node ./scripts/next-step-smoke.mjs",
     "scout-receipt-smoke": "node ./scripts/scout-receipt-smoke.mjs",

package/references/context-reuse.md

@@ -40,6 +40,7 @@ Use it only for known wrong decisions, repeated mistakes, direction changes, and
 
 Rules:
 
+- Work on the current branch by default. Creating/switching branches, creating worktrees and creating PRs each need an explicit user request or applicable project rule. Commit/push, release bumps and a `codex/` naming convention do not authorize these actions. Branch protection specifies acceptance conditions, not a mandate to create a branch; when blocked, report and ask instead of changing workflow or protections. Preserve existing work; if detached HEAD prevents a requested commit, clarify the target before changing it.
 - Do not regenerate a broad plan when `yam.project.md` already answers the direction question.
 - Do not reread architecture docs unless the task touches architecture.
 - Do not reread full design docs for tiny UI work when the pack has the relevant style direction.

package/references/final-report.md

@@ -21,7 +21,7 @@ Always keep final reports short. Include these when they apply:
 - Publish blocker evidence when npm/release work fails.
 - Structured diagnostic next action, when a check found a concrete next step.
 - Study Note whenever code, config, release metadata, documentation, or project artifacts changed, even if no yam skill was explicitly invoked. This item is required for changed artifacts, not optional.
-- Next step immediately after Study Note for changed-artifact reports. It must come from a quick whole-process scan and include ordered fix-first and planned actions, not only leftovers.
+- Next step immediately after Study Note for changed-artifact reports. Ordinary advisory work may use one concrete action or no remaining work; strict reports use the whole-process scan and ordered fix-first/planned contract.
 - Remaining tasks.
 - Fix-first items before planned tasks.
 - Recommended direction and why that next step matters when the handoff would otherwise be ambiguous.
@@ -90,6 +90,8 @@ Include:
 - One ordered sequence with all fix-first items before planned work.
 - Why each action matters, owner route and scope, blockers and safe retry, evidence level and stamp, expected side effects, and truth status.
 
+These detailed fields are for strict reports and structured receipts. Ordinary advisory work can summarize the next action (or none) without mandatory labels or numbered steps.
+
 This is broader than `Remaining Tasks`: it may recommend the next useful work after the current scope is complete. Do not invent filler when nothing meaningful remains. Use `references/next-step.md`; reusable JSON receipts use `yam.next-step.v1`.
 
 ## Handoff Direction

package/references/next-step.md

@@ -8,6 +8,8 @@ When code, config, documentation, release metadata, or another project artifact
 
 ## Whole-process scan
 
+For ordinary advisory hook work, keep Next step to a concrete remaining action or “no remaining work”; numbered ownership/safety/truth fields are not mandatory. The detailed contract below applies to strict report validation and structured receipts. Do not manufacture a task just to satisfy a report shape.
+
 Before writing the sequence, quickly re-check:
 
 - the original goal and acceptance criteria;

package/references/security-check.md

@@ -13,6 +13,8 @@ Assess security applicability during new development and changes. Before commit,
 
 Commit, push, and deployment are distinct actions. A remote CI failure generally blocks protected-branch merge or deployment; it does not mean the preceding Git push was rejected. Local hooks can be bypassed or absent. Do not claim that `--no-verify` is automatically observable; future CI must independently check incoming revisions. Direct deployments must use the same required gate or access restrictions, otherwise enforcement remains incomplete.
 
+Branch protection is an acceptance boundary, not authorization to create a branch, worktree or PR. Keep the current branch unless the user or an explicit applicable project rule requests a different workflow. If direct push or merge is blocked, preserve work, report the exact blocker and ask for direction. Do not silently create a PR, change protection settings or bypass the security gate.
+
 ## Fixed areas and concrete summaries
 
 Every run includes each ID exactly once with a concrete explanation, a status, and the applicable evidence or reason. An ID or short heading alone does not satisfy the explanation requirement. These summaries are the canonical minimum; add project-specific targets without removing their security meaning.

package/references/study-note.md

@@ -16,6 +16,10 @@ This is final-report writing guidance, not a new CLI JSON schema. The current CL
 
 Keep the default note short: 4-7 lines for ordinary work, longer only for `$deep`, `$mission`, release, DB, runtime, or learning-heavy work.
 
+Automatic hook scope is turn-based, not the existing dirty tree. Ordinary work is advisory: summarize the touched artifact/role and change, verification/limits, then a short Next step (or no remaining work). The hook checks only the compact minimum; the fuller guidance below remains useful when relevant. Deep/Mission names alone do not activate strict. Risk intent or explicit/project strict policy requires the detailed contract only if selected artifacts changed. Explicit `yam study-note check` retains strict whole-tree validation.
+
+Known generated mission/security receipts, logs and screenshots are not product changes by default; `.yam/study-note.json` includes override excludes. Security evidence is still required by the independent stage security gate. Unavailable or expired baseline means partial/manual inspection, not no changes. Plain, Markdown heading and standalone bold Study Note / Next step titles are accepted.
+
 Include:
 
 - Touched code/artifact: the file, function, component, config, or artifact that changed.

package/skills/deep/SKILL.md

@@ -18,6 +18,7 @@ Use for:
 
 ## Principles
 
+- Keep the current branch. Create/switch branches, create worktrees or create PRs only on explicit user request or an applicable project rule; commit/push, version bumps, route selection and protection alone do not authorize them. If blocked, report and ask instead of silently changing workflow, protections or bypassing checks.
 - Direction before execution.
 - Token economy still matters, even in deep mode.
 - Reuse `yam.project.md` before broad context reading when present.

package/skills/mission/SKILL.md

@@ -24,6 +24,7 @@ Do not use for:
 
 ## Principles
 
+- Keep the current branch. Create/switch branches, create worktrees or create PRs only on explicit user request or an applicable project rule; commit/push, version bumps, route selection and protection alone do not authorize them. If blocked, report and ask instead of silently changing workflow, protections or bypassing checks.
 - Direction before execution.
 - Mission is explicit-only; never auto-escalate small tasks into mission.
 - Start from the user's approved plan or ask for one if the plan is missing.

package/skills/question/SKILL.md

@@ -17,6 +17,7 @@ Do not use for:
 - Risky verification or broad debugging. Use `$deep`.
 
 Principles:
+- Keep the current branch. Create/switch branches, create worktrees or create PRs only on explicit user request or an applicable project rule; commit/push, version bumps, route selection and protection alone do not authorize them. If blocked, report and ask instead of silently changing workflow, protections or bypassing checks.
 - Direction before execution.
 - Answer the question first.
 - Keep context tiny.

package/skills/quick/SKILL.md

@@ -22,6 +22,7 @@ Do not use for:
 
 ## Principles
 
+- Keep the current branch. Create/switch branches, create worktrees or create PRs only on explicit user request or an applicable project rule; commit/push, version bumps, route selection and protection alone do not authorize them. If blocked, report and ask instead of silently changing workflow, protections or bypassing checks.
 - Direction before execution.
 - Context-reuse first.
 - Token economy is part of quality.
@@ -84,7 +85,7 @@ Keep it compact:
 
 - What changed or what the scan found.
 - Study Note when code, config, docs, or project artifacts changed: what changed, what role it has, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
-- Next step immediately after Study Note when artifacts changed; use `references/next-step.md` to record the whole-process scan, critical opinion, recommendations, and ordered fix-first then planned actions.
+- Next step immediately after Study Note when artifacts changed; ordinary advisory work uses one concrete action or no remaining work. Use the detailed `references/next-step.md` contract only for risky/strict reports or structured receipts.
 - Architecture hygiene when relevant: flag if the change risks dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - What was checked.
 - What was skipped, blocked, or still risky.

package/skills/scout/SKILL.md

@@ -22,6 +22,7 @@ Use for:
 
 ## Principles
 
+- Keep the current branch. Create/switch branches, create worktrees or create PRs only on explicit user request or an applicable project rule; commit/push, version bumps, route selection and protection alone do not authorize them. If blocked, report and ask instead of silently changing workflow, protections or bypassing checks.
 - Scout broadly enough to see the field, then compress the judgment.
 - Token economy is part of quality.
 - Reuse `yam.project.md` before broad context reading when present.

package/skills/ueye/SKILL.md

@@ -22,6 +22,7 @@ Do not use for:
 
 ## Principles
 
+- Keep the current branch. Create/switch branches, create worktrees or create PRs only on explicit user request or an applicable project rule; commit/push, version bumps, route selection and protection alone do not authorize them. If blocked, report and ask instead of silently changing workflow, protections or bypassing checks.
 - Direction before execution.
 - Visual evidence before visual claims.
 - Ueye is the tight UX/UI/design route, not Quick with screenshots.

package/src/bin/yam.ts

@@ -1,5 +1,6 @@
 #!/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';
@@ -988,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;
@@ -1024,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',
@@ -1110,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] || '';
@@ -1236,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;
@@ -2465,7 +2473,7 @@ async function hookRun(args = []) {
   }
   const prompt = extractPrompt(input);
   const additionalContext = profile === 'study-note'
-    ? await buildStudyNoteHookContext({ cwd })
+    ? await buildStudyNoteTurnContext(input, cwd)
     : await buildYamLiteContext({ cwd, prompt });
   const output = {
     continue: true,
@@ -2497,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);
@@ -2512,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,
@@ -2551,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,
@@ -2561,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 '';

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.2",
+  "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": [