yam-flow 2.8.1 → 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,31 @@
 
 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
+
+- Hook configuration now uses Codex's required top-level `hooks` wrapper. `yam hook migrate` backs up legacy files and preserves commands and unrelated handlers without automatically approving Codex trust.
+- Hook status can now separate configured health, Codex `hooks/list` discovery, and opt-in local entrypoint observations; Node launcher selection is bound to the running executable identity.
+- External yam update checks distinguish exact-version npm distribution propagation (`pending_distribution`) from network, authorization, or metadata failures.
+- Memory listing and summary preserve the difference between missing, empty, invalid, unreadable, and incomplete record storage; incomplete reads cannot overwrite an existing summary.
+- Added bounded Markdown skill-content checks for frontmatter identity, symlinks, personal absolute paths, download-to-shell patterns, and high-signal secrets.
+
 ## v2.8.1 - 2026-10-01
 
 ### Security

package/COMMANDS.md

@@ -153,6 +153,8 @@ yam memory add /path/to/project --kind repeat_mistake --summary "UI work was dec
 yam memory summary /path/to/project
 ```
 
+`yam memory list --json` keeps the normal complete result as an array and returns a bounded `yam.memory-read.v1` envelope for missing, invalid, unreadable, or incomplete storage. `yam memory summary --json` refuses to overwrite the existing summary unless the record directory was read completely.
+
 ## Token Budget
 
 ```bash
@@ -172,7 +174,7 @@ yam update apply --component yam --json
 yam update apply --all --json
 ```
 
-`yam update check` is read-only. Its component result preserves the registry artifact source receipt: npm integrity/`gitHead` for yam, PyPI release-file SHA-256 values for Scrapling, and the Git-pinned manifest commit for Insane Search. Every `apply` needs explicit authorization, pins the official npm registry or isolated PyPI index, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. A yam install verifies the effective executable identity before any yam-side install command and repeats that check during rollback. This identity contract currently supports POSIX symlink layouts; Windows npm `.cmd` shims fail closed as unverified. Insane Search requires a clean tracked local manifest whose bytes match Git and matching pre/post-add commits, is never remove-first, and never edits `.codex/plugins/cache` directly.
+`yam update check` is read-only. Its component result preserves the registry artifact source receipt: npm integrity/`gitHead` for yam, PyPI release-file SHA-256 values for Scrapling, and the Git-pinned manifest commit for Insane Search. Yam also compares `latest` with exact-version metadata and probes the official exact tarball URL; a 404 is `pending_distribution`, while network/auth/metadata mismatch is `check_failed`. The bounded HEAD probe confirms availability only and does not hash tarball bytes. Every `apply` needs explicit authorization, pins the official npm registry or isolated PyPI index, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. A yam install verifies the effective executable identity before any yam-side install command and repeats that check during rollback. This identity contract currently supports POSIX symlink layouts; Windows npm `.cmd` shims fail closed as unverified. Insane Search requires a clean tracked local manifest whose bytes match Git and matching pre/post-add commits, is never remove-first, and never edits `.codex/plugins/cache` directly.
 
 ## Release Supply Chain
 
@@ -327,15 +329,18 @@ Supported report shapes:
 
 `lite` is advisory-only. `study-note` runs the read-only Study Note Guard against the final assistant message and can request one correction pass; neither profile runs verification or forces routes.
 
+`yam hook migrate [--global|--project dir]` wraps legacy top-level events in Codex's `hooks` object without changing commands. It backs up the original, refuses unsafe files, and is a no-op for canonical configs. Review changed definitions in Codex `/hooks` before execution; yam does not approve trust.
+
 ```bash
 yam hook status --global
+yam hook migrate --global
 yam hook enable lite --global
 yam hook enable study-note --global
 yam hook disable lite --global
 yam hook disable study-note --global
 ```
 
-`yam hook status` exits nonzero for unreadable configs, stale paths, missing targets, duplicate handlers, or incomplete event coverage. Re-enable the affected profile to back up the file, preserve unrelated hooks, and migrate its command and events.
+`yam hook status` exits nonzero for unreadable configs, stale paths, missing targets, duplicate handlers, or incomplete event coverage. Add `--json` for `yam.hook-readiness.v1`, or `--probe` to query `hooks/list` in a separate bounded Codex app-server. The probe separates host discovery from local configuration and never claims that the active Desktop session loaded the hook. Add `--observe` to `yam hook enable` to record a bounded local entrypoint observation; it contains only hashes and event metadata and remains partial same-user evidence. Re-enable the affected profile to back up the file, preserve unrelated hooks, and migrate its command and events.
 
 ## Security check
 

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.
@@ -74,6 +75,8 @@ yam memory add . --kind lesson --summary "Keep UI checks visual before declaring
 yam memory summary .
 ```
 
+`yam memory list --json` distinguishes missing, empty, invalid, unreadable, and incomplete record directories. A blocked `yam memory summary --json` exits nonzero and preserves the previous summary instead of treating an access failure as an empty memory set.
+
 Memory writes to `.yam/memory/` only when you run the command. Routes should prefer `.yam/memory/summary.md` and should not read every record by default.
 
 ## Lite Hook
@@ -91,6 +94,8 @@ It only adds short advisory context. It does not run verification, tmux, browser
 
 ## Study Note Hook
 
+Codex hook files use a top-level `hooks` object containing event groups (`{"hooks":{"Stop":[...]}}`). For older yam files with events at the top level, run `yam hook migrate --global`: this creates a backup and changes only the layout, preserving existing commands and unrelated handlers. Review the changed definitions in Codex `/hooks`; discovery alone does not authorize execution, and yam never approves hook trust automatically.
+
 Enable this profile when you want Codex to check changed work at final-response time as well as remind the agent at prompt time.
 
 ```bash
@@ -98,11 +103,15 @@ 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.
 
-`yam hook status` reports stale or missing command targets as `broken` and exits nonzero. Run `yam hook enable <profile> --global` again to create a timestamped backup, preserve unrelated hooks, and migrate that profile to the current installed path and event coverage. Restart Codex or open a new task after changing hooks.
+`yam hook status` reports stale or missing command targets as `broken` and exits nonzero. Run `yam hook enable <profile> --global` again to create a timestamped backup, preserve unrelated hooks, and migrate that profile to the current installed path and event coverage. For runtime-oriented diagnosis, use `yam hook status --global --json --probe`; this separates configured hooks, discovery from a new bounded Codex app-server, and local entrypoint observations. The active Desktop session remains `not_measured` unless the host provides independent evidence. `yam hook enable <profile> --global --observe` records only a local hash-bound event observation; it is partial evidence and not host attestation. Restart Codex or open a new task after changing hooks.
 
 ## Install
 

package/dist/bin/yam.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import { studyNoteTurnScope } from '../lib/study-note-scope.js';
+import { selectHookNode, probeHookDiscovery, inspectHookObservation, recordHookObservation } from '../lib/hook-readiness.js';
+import { readMemoryDirectory } from '../lib/memory-records.js';
 import { runSecurityCommand } from '../lib/security-integration.js';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
@@ -71,8 +74,8 @@ const INSTRUCTION_DUPLICATION_LIMITS = {
     minDirectiveChars: 40
 };
 const YAM_HOOK_ENTRYPOINT = path.join(ROOT, 'dist', 'bin', 'yam.js');
-const YAM_LITE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite`;
-const YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note`;
+let YAM_LITE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite`;
+let YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note`;
 const REQUIRED_PACK_SECTIONS = [
     'Product Direction',
     'UI Direction',
@@ -932,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;
@@ -964,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',
@@ -1052,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] || '';
@@ -1176,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;
@@ -1944,6 +1955,8 @@ async function hook(args = []) {
         return hookUsage();
     if (subcommand === 'status')
         return hookStatus(args.slice(1));
+    if (subcommand === 'migrate')
+        return hookMigrate(args.slice(1));
     if (subcommand === 'enable')
         return hookEnable(args.slice(1));
     if (subcommand === 'disable')
@@ -1957,14 +1970,17 @@ function hookUsage() {
     console.log(`yam hook
 
 Usage:
-  yam hook status [--global|--project dir]
-  yam hook enable <lite|study-note> [--global|--project dir]
+  yam hook status [--global|--project dir] [--probe] [--json]
+  yam hook migrate [--global|--project dir]
+  yam hook enable <lite|study-note> [--global|--project dir] [--observe]
   yam hook disable [lite|study-note] [--global|--project dir]
   yam hook run <lite|study-note>
 
 Notes:
   hooks are opt-in. lite is advisory-only; study-note adds a prompt reminder and a one-pass Stop completion gate.
   Hooks do not generate reports, run tmux, start subagents, or execute verification automatically.
+  --probe queries hooks/list in a separate bounded Codex app-server; active session loading stays unknown.
+  --observe opts into private local entrypoint observations without storing prompt content; not host attestation.
 `);
 }
 function parseHookArgs(args = []) {
@@ -1991,7 +2007,7 @@ function parseHookArgs(args = []) {
 }
 function hookPathFor(parsed) {
     if (parsed.mode === 'global')
-        return path.join(os.homedir(), '.codex', 'hooks.json');
+        return path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'hooks.json');
     return path.join(path.resolve(parsed.projectDir || process.cwd()), '.codex', 'hooks.json');
 }
 function isYamLiteHook(handler = {}) {
@@ -2003,12 +2019,34 @@ function isYamStudyNoteHook(handler = {}) {
 function isYamHookProfile(handler = {}, profile = 'lite') {
     return profile === 'study-note' ? isYamStudyNoteHook(handler) : isYamLiteHook(handler);
 }
+const CODEX_HOOK_EVENTS = new Set(['SessionStart', 'SessionEnd', 'PreToolUse', 'PermissionRequest', 'PostToolUse', 'PreCompact', 'PostCompact', 'UserPromptSubmit', 'SubagentStart', 'SubagentStop', 'Stop', 'Interrupt']);
+function hookEventMap(config = {}) {
+    const nested = config.hooks && typeof config.hooks === 'object' && !Array.isArray(config.hooks) ? config.hooks : {};
+    const events = { ...nested };
+    for (const [event, entries] of Object.entries(config)) {
+        if (CODEX_HOOK_EVENTS.has(event) && Array.isArray(entries)) {
+            events[event] = [...(Array.isArray(events[event]) ? events[event] : []), ...entries];
+        }
+    }
+    return events;
+}
+function canonicalHookConfig(config = {}) {
+    if (config.hooks != null && (typeof config.hooks !== 'object' || Array.isArray(config.hooks)))
+        throw new Error('hooks must be an event object; existing file preserved');
+    const next = { ...config, hooks: hookEventMap(config) };
+    for (const event of CODEX_HOOK_EVENTS) {
+        if (event in config && !Array.isArray(config[event]))
+            throw new Error('legacy hook event must be an array; existing file preserved');
+        delete next[event];
+    }
+    return next;
+}
 function stripYamHooks(config = {}, profile = 'lite') {
-    const next = { ...config };
-    for (const event of Object.keys(next)) {
-        if (!Array.isArray(next[event]))
+    const next = canonicalHookConfig(config);
+    for (const event of Object.keys(next.hooks)) {
+        if (!Array.isArray(next.hooks[event]))
             continue;
-        const entries = next[event];
+        const entries = next.hooks[event];
         const keptEntries = [];
         for (const entry of entries) {
             const hooks = Array.isArray(entry?.hooks) ? entry.hooks.filter((handler) => !isYamHookProfile(handler, profile)) : [];
@@ -2017,9 +2055,9 @@ function stripYamHooks(config = {}, profile = 'lite') {
                 keptEntries.push(rest);
         }
         if (keptEntries.length > 0)
-            next[event] = keptEntries;
+            next.hooks[event] = keptEntries;
         else
-            delete next[event];
+            delete next.hooks[event];
     }
     return next;
 }
@@ -2036,7 +2074,7 @@ function withYamHook(config = {}, profile = 'lite') {
                 }
             ]
         };
-        next[event] = [...(Array.isArray(next[event]) ? next[event] : []), entry];
+        next.hooks[event] = [...(Array.isArray(next.hooks[event]) ? next.hooks[event] : []), entry];
     }
     return next;
 }
@@ -2045,6 +2083,11 @@ async function hookStatus(args = []) {
     const target = hookPathFor(parsed);
     const loaded = await readHookConfig(target);
     if (loaded.error) {
+        if (args.includes('--json')) {
+            console.log(JSON.stringify({ schema: 'yam.hook-readiness.v1', scope: parsed.mode, configuration: 'unreadable', loaded: 'unknown', execution_observed: false, truth_status: 'partial' }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
         console.log('yam-lite hook: broken');
         console.log('yam-study-note hook: broken');
         console.log(`  - hook config unreadable: ${loaded.error}`);
@@ -2055,10 +2098,30 @@ async function hookStatus(args = []) {
     }
     const lite = await inspectHookProfile(loaded.config, 'lite');
     const studyNote = await inspectHookProfile(loaded.config, 'study-note');
+    const cwd = path.resolve(parsed.projectDir || process.cwd());
+    const commands = { lite: lite.entries.map((entry) => String(entry.handler.command)), 'study-note': studyNote.entries.map((entry) => String(entry.handler.command)) };
+    const host = args.includes('--probe')
+        ? await probeHookDiscovery({ executable: await findExecutable('codex') || 'codex', cwd, commands, configPath: target })
+        : { state: 'not_measured', active_session_loaded: 'not_measured', execution_observed: false, truth_status: 'partial' };
+    const profiles = {};
+    for (const [profile, health] of [['lite', lite], ['study-note', studyNote]]) {
+        profiles[profile] = { configured: health.state, issues: health.issues, loaded: 'unknown',
+            execution: await inspectHookObservation(cwd, profile, YAM_HOOK_ENTRYPOINT) };
+    }
+    if (args.includes('--json')) {
+        console.log(JSON.stringify({ schema: 'yam.hook-readiness.v1', scope: parsed.mode, profiles, host, truth_status: 'partial' }, null, 2));
+        if (lite.state === 'broken' || studyNote.state === 'broken')
+            process.exitCode = 1;
+        return;
+    }
     printHookProfileStatus('lite', lite);
     printHookProfileStatus('study-note', studyNote);
     console.log(`scope: ${parsed.mode}`);
     console.log(`file: ${target}`);
+    console.log('active Codex session loaded: unknown (configuration is not runtime evidence)');
+    console.log(`host discovery: ${host.state}`);
+    for (const profile of ['lite', 'study-note'])
+        console.log(`yam-${profile} execution: ${profiles[profile].execution.state} (local entrypoint evidence, not host attestation)`);
     if (lite.state === 'broken' || studyNote.state === 'broken')
         process.exitCode = 1;
 }
@@ -2066,7 +2129,7 @@ function hookConfigHasYamLite(config = {}) {
     return hookConfigHasProfile(config, 'lite');
 }
 function hookConfigHasProfile(config = {}, profile = 'lite') {
-    return Object.values(config).some((entries) => Array.isArray(entries) && entries.some((entry) => {
+    return Object.values(hookEventMap(config)).some((entries) => Array.isArray(entries) && entries.some((entry) => {
         return Array.isArray(entry?.hooks) && entry.hooks.some((handler) => isYamHookProfile(handler, profile));
     }));
 }
@@ -2078,7 +2141,7 @@ function hookEventsForProfile(profile = 'lite') {
 }
 function hookProfileEntries(config = {}, profile = 'lite') {
     const matches = [];
-    for (const [event, entries] of Object.entries(config)) {
+    for (const [event, entries] of Object.entries(hookEventMap(config))) {
         if (!Array.isArray(entries))
             continue;
         for (const entry of entries) {
@@ -2142,6 +2205,8 @@ function splitHookCommand(command = '') {
 }
 function parseYamHookCommand(command = '', profile = 'lite') {
     const words = splitHookCommand(command);
+    if (words.at(-1) === '--observe')
+        words.pop();
     if (words.length === 5 && words[2] === 'hook' && words[3] === 'run' && words[4] === profile) {
         const nodeName = path.basename(words[0]).toLowerCase();
         if (/^node(?:\.exe)?$/.test(nodeName) && path.basename(words[1]).toLowerCase() === 'yam.js') {
@@ -2185,6 +2250,8 @@ async function inspectHookProfile(config = {}, profile = 'lite') {
     if (!entries.length)
         return { state: 'disabled', issues: [], entries };
     const issues = [];
+    if (Object.keys(config).some((event) => CODEX_HOOK_EVENTS.has(event)))
+        issues.push('legacy hook config requires the top-level hooks wrapper; rerun yam hook enable to migrate with backup');
     for (const event of hookEventsForProfile(profile)) {
         const count = entries.filter((entry) => entry.event === event).length;
         if (count === 0)
@@ -2213,6 +2280,9 @@ async function readHookConfig(target) {
         if (!value || Array.isArray(value) || typeof value !== 'object') {
             return { config: {}, exists: true, error: 'top-level value must be a JSON object' };
         }
+        if (value.hooks != null && (typeof value.hooks !== 'object' || Array.isArray(value.hooks))) {
+            return { config: {}, exists: true, error: 'hooks must be an event object' };
+        }
         return { config: value, exists: true, error: '' };
     }
     catch (error) {
@@ -2233,8 +2303,41 @@ async function writeHookConfig(target, config) {
         throw error;
     }
 }
+async function hookMigrate(args = []) {
+    const parsed = parseHookArgs(args);
+    const target = hookPathFor(parsed);
+    const loaded = await readHookConfig(target);
+    if (loaded.error) {
+        console.error('hook migration blocked: unreadable configuration');
+        process.exitCode = 1;
+        return;
+    }
+    if (!loaded.exists || !Object.keys(loaded.config).some((key) => CODEX_HOOK_EVENTS.has(key))) {
+        console.log('hook migration: no legacy event layout found');
+        return;
+    }
+    const before = await fsp.lstat(target);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)
+        throw new Error('hook migration blocked: unsafe config file');
+    const original = await fsp.readFile(target, 'utf8');
+    if (JSON.stringify(JSON.parse(original)) !== JSON.stringify(loaded.config))
+        throw new Error('hook configuration changed; retry migration');
+    const next = canonicalHookConfig(loaded.config);
+    const backup = `${target}.yam-backup-${timestampId()}`;
+    await fsp.copyFile(target, backup, fs.constants.COPYFILE_EXCL);
+    const after = await fsp.lstat(target);
+    if (after.dev !== before.dev || after.ino !== before.ino || after.mtimeMs !== before.mtimeMs
+        || await fsp.readFile(target, 'utf8') !== original)
+        throw new Error('hook configuration changed; backup preserved, retry migration');
+    await writeHookConfig(target, next);
+    console.log(`hook migration: wrapped event groups; handlers and metadata preserved\nbackup: ${backup}\nReview changed definitions in Codex /hooks before enabling execution.`);
+}
 async function hookEnable(args = []) {
     const parsed = parseHookArgs(args);
+    const node = await selectHookNode();
+    const observe = args.includes('--observe') ? ' --observe' : '';
+    YAM_LITE_HOOK_COMMAND = `${JSON.stringify(node.executable)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite${observe}`;
+    YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(node.executable)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note${observe}`;
     if (!['lite', 'study-note'].includes(parsed.profile)) {
         console.error('Only lite and study-note hooks are supported: yam hook enable <lite|study-note>');
         process.exitCode = 1;
@@ -2263,6 +2366,7 @@ async function hookEnable(args = []) {
     }
     await writeHookConfig(target, next);
     console.log(`yam-${parsed.profile} hook enabled (${parsed.mode}): ${target}`);
+    console.log(`node launcher: ${node.selection}; alias identity matched the current runtime (no PATH candidate executed)`);
     if (needsMigration)
         console.log(`migrated: ${existing.length} existing yam-${parsed.profile} handler(s) to the current command and event coverage`);
     console.log('Restart Codex or start a new thread if the app does not pick up hook changes immediately.');
@@ -2283,7 +2387,7 @@ async function hookDisable(args = []) {
         return;
     }
     const next = stripYamHooks(current, parsed.profile);
-    if (Object.keys(next).length === 0) {
+    if (Object.keys(next).length === 1 && Object.keys(next.hooks).length === 0) {
         await rmrf(target);
     }
     else {
@@ -2313,13 +2417,15 @@ async function hookRun(args = []) {
     }
     const event = input?.hook_event_name || input?.hookEventName || input?.event || 'UserPromptSubmit';
     const cwd = String(input?.cwd || process.cwd());
+    if (args.includes('--observe'))
+        await recordHookObservation(cwd, profile, String(event), YAM_HOOK_ENTRYPOINT).catch(() => { });
     if (profile === 'study-note' && event === 'Stop') {
         console.log(JSON.stringify(await buildStudyNoteStopOutput(input, cwd)));
         return;
     }
     const prompt = extractPrompt(input);
     const additionalContext = profile === 'study-note'
-        ? await buildStudyNoteHookContext({ cwd })
+        ? await buildStudyNoteTurnContext(input, cwd)
         : await buildYamLiteContext({ cwd, prompt });
     const output = {
         continue: true,
@@ -2348,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);
@@ -2367,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,
@@ -2406,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,
@@ -2416,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)
@@ -6079,7 +6168,7 @@ async function memory(args = []) {
     }
     if (subcommand === 'summary' || subcommand === 'summarize') {
         const parsed = parseMemoryArgs(args.slice(1));
-        return memorySummary(parsed.dir);
+        return memorySummary(parsed.dir, { json: args.includes('--json') });
     }
     if (subcommand === 'resolve')
         return memoryResolve(args.slice(1));
@@ -6093,7 +6182,7 @@ Usage:
   yam memory init [dir]
   yam memory add [dir] --kind <kind> --summary <text> [--evidence <text>] [--action <text>] [--source <text>]
   yam memory list [dir] [--json]
-  yam memory summary [dir]
+  yam memory summary [dir] [--json]
   yam memory resolve [dir] <id> [--note <text>]
 
 Kinds:
@@ -6163,7 +6252,17 @@ async function memoryAdd(args = []) {
     console.log(`memory added: ${id}`);
 }
 async function memoryList(targetDir = process.cwd(), { json = false } = {}) {
-    const records = await readMemoryRecords(targetDir);
+    const report = await readMemoryRecords(targetDir);
+    const records = report.records;
+    if (!report.complete) {
+        if (report.state !== 'missing')
+            process.exitCode = 1;
+        if (json)
+            console.log(JSON.stringify(report, null, 2));
+        else
+            console.error(`memory read ${report.state}: ${JSON.stringify(report.diagnostics)}${report.diagnostics_truncated ? ' (diagnostics truncated)' : ''}`);
+        return;
+    }
     if (json) {
         console.log(JSON.stringify(records, null, 2));
         return;
@@ -6178,9 +6277,18 @@ async function memoryList(targetDir = process.cwd(), { json = false } = {}) {
             console.log(`  action: ${record.action}`);
     }
 }
-async function memorySummary(targetDir = process.cwd()) {
+async function memorySummary(targetDir = process.cwd(), { json = false } = {}) {
     const dir = memoryDir(targetDir);
-    const records = await readMemoryRecords(targetDir);
+    const report = await readMemoryRecords(targetDir);
+    if (!report.complete) {
+        process.exitCode = 1;
+        if (json)
+            console.log(JSON.stringify({ ...report, summary_written: false }, null, 2));
+        else
+            console.error(`memory summary blocked (${report.state}); existing summary preserved: ${JSON.stringify(report.diagnostics)}${report.diagnostics_truncated ? ' (diagnostics truncated)' : ''}`);
+        return;
+    }
+    const records = report.records;
     await fsp.mkdir(dir, { recursive: true });
     const active = records.filter((record) => record.status !== 'resolved');
     const resolved = records.filter((record) => record.status === 'resolved');
@@ -6212,7 +6320,10 @@ async function memorySummary(targetDir = process.cwd()) {
     }
     const target = path.join(dir, 'summary.md');
     await fsp.writeFile(target, `${lines.join('\n').trim()}\n`);
-    console.log(`memory summary written: ${target}`);
+    if (json)
+        console.log(JSON.stringify({ ...report, summary_written: true, path: target }, null, 2));
+    else
+        console.log(`memory summary written: ${target}`);
 }
 async function memoryResolve(args = []) {
     const parsed = parseMemoryArgs(args);
@@ -6267,23 +6378,7 @@ function memoryDir(targetDir = process.cwd()) {
 }
 async function readMemoryRecords(targetDir = process.cwd()) {
     const recordsDir = path.join(memoryDir(targetDir), 'records');
-    if (!await exists(recordsDir))
-        return [];
-    const entries = await fsp.readdir(recordsDir, { withFileTypes: true });
-    const records = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.json'))
-            continue;
-        const file = path.join(recordsDir, entry.name);
-        try {
-            const record = await readJson(file);
-            records.push(record);
-        }
-        catch (error) {
-            records.push({ id: entry.name.replace(/\.json$/, ''), kind: 'invalid', status: 'invalid', summary: `invalid JSON: ${errorMessage(error)}` });
-        }
-    }
-    return records.sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+    return readMemoryDirectory(recordsDir);
 }
 function timestampId() {
     const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.(\d{3})Z$/, '$1z');