yam-flow 2.8.1 → 2.8.3

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/dist/lib/verification-closure.d.ts

@@ -63,7 +63,7 @@ export declare function createVerificationClosureReceipt(input: {
     schema: "yam.verification-closure-write.v1";
     receipt_path: string;
     receipt: VerificationClosureReceipt;
-    truth_status: "blocked" | "partial";
+    truth_status: "partial" | "blocked";
     next_action: string;
 }>;
 export declare function verifyVerificationClosureReceipt(value: unknown): {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -60,7 +60,7 @@
     "doctor": "node ./dist/bin/yam.js doctor",
     "list": "node ./dist/bin/yam.js list",
     "examples": "node ./dist/bin/yam.js examples",
-    "verify:self": "npm run build && node --check ./dist/bin/yam.js && node --check ./dist/lib/trust-kernel.js && node --check ./dist/lib/skill-installation.js && node --check ./dist/lib/external-updates.js && node --check ./dist/lib/next-step.js && node --check ./dist/lib/scout-receipt.js && node --check ./dist/lib/release-registry-status.js && node --check ./dist/lib/release-auth-readiness.js && node --check ./dist/lib/gate-result.js && node --check ./dist/lib/benchmark-promotion.js && node --check ./dist/lib/design-production.js && node --check ./dist/lib/verification-closure.js && node --check ./dist/lib/media-provider-receipt.js && npm run security-smoke && npm run security-integration-smoke && npm run hook-latency-smoke && npm run next-step-smoke && npm run scout-receipt-smoke && npm run release:registry-parser:smoke && npm run release:auth-smoke && node ./scripts/external-updates-smoke.mjs && node ./scripts/install-transaction-smoke.mjs && node ./scripts/trust-adoptions-smoke.mjs && node ./scripts/design-production-smoke.mjs && node ./scripts/phase-adoptions-smoke.mjs && npm run package-secrets:check && npm run package-secrets-smoke && node ./dist/bin/yam.js verify && node ./dist/bin/yam.js doctor",
+    "verify:self": "npm run build && node --check ./dist/bin/yam.js && node --check ./dist/lib/trust-kernel.js && node --check ./dist/lib/skill-installation.js && node --check ./dist/lib/external-updates.js && node --check ./dist/lib/hook-readiness.js && node --check ./dist/lib/memory-records.js && node --check ./dist/lib/next-step.js && node --check ./dist/lib/scout-receipt.js && node --check ./dist/lib/release-registry-status.js && node --check ./dist/lib/release-auth-readiness.js && node --check ./dist/lib/gate-result.js && node --check ./dist/lib/benchmark-promotion.js && node --check ./dist/lib/design-production.js && node --check ./dist/lib/verification-closure.js && node --check ./dist/lib/media-provider-receipt.js && npm run security-smoke && npm run security-integration-smoke && npm run hook-latency-smoke && npm run hook-readiness-smoke && npm run next-step-smoke && npm run scout-receipt-smoke && npm run release:registry-parser:smoke && npm run release:auth-smoke && node ./scripts/external-updates-smoke.mjs && node ./scripts/install-transaction-smoke.mjs && node ./scripts/trust-adoptions-smoke.mjs && node ./scripts/design-production-smoke.mjs && node ./scripts/phase-adoptions-smoke.mjs && npm run skill-content:check && npm run skill-content-smoke && npm run memory-completeness-smoke && npm run package-secrets:check && npm run package-secrets-smoke && node ./dist/bin/yam.js verify && node ./dist/bin/yam.js doctor",
     "prepare": "npm run build",
     "prepack": "npm run verify:self",
     "prepublishOnly": "npm run verify:self",
@@ -69,9 +69,14 @@
     "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",
+    "skill-content:check": "node ./scripts/check-skill-content.mjs",
+    "skill-content-smoke": "node ./scripts/skill-content-smoke.mjs",
+    "memory-completeness-smoke": "node ./scripts/memory-completeness-smoke.mjs",
+    "hook-readiness-smoke": "node ./scripts/hook-readiness-smoke.mjs",
     "dist:freshness": "node ./scripts/check-dist-freshness.mjs",
     "registry:check": "node ./scripts/check-registry-version.mjs",
     "registry:check:smoke": "node ./scripts/check-registry-version.mjs --self-test",
@@ -82,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.