yam-flow 2.8.0 → 2.8.2

package/dist/lib/security-integration.js

@@ -0,0 +1,428 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import { constants, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createSecurityStarter, validateSecurityCheck, persistSecurityCheck, SECURITY_AREA_IDS } from './security-check.js';
+const OID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const ZERO = /^0+$/;
+const hash = (text) => `sha256:${createHash('sha256').update(text).digest('hex')}`;
+function git(cwd, args) {
+    try {
+        return execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 8 * 1024 * 1024 }).trim();
+    }
+    catch {
+        throw new Error('git binding inspection failed');
+    }
+}
+function revision(cwd, ref) {
+    if (!OID.test(ref))
+        throw new Error('revision must be an exact Git object ID');
+    const result = git(cwd, ['rev-parse', '--verify', `${ref}^{commit}`]);
+    if (!OID.test(result))
+        throw new Error('invalid source commit');
+    return result;
+}
+function parseArgs(args) {
+    const out = new Map();
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--json')
+            continue;
+        if (!['--policy', '--policy-digest', '--evidence', '--note', '--stage', '--remote', '--destination', '--source', '--base', '--artifact', '--artifact-digest', '--configuration', '--configuration-digest', '--environment', '--cli'].includes(args[i]) || !args[i + 1] || args[i + 1].startsWith('--') || out.has(args[i]))
+            throw new Error('invalid or duplicate security option');
+        out.set(args[i], args[++i]);
+    }
+    return out;
+}
+export function collectSecurityBinding(cwd, stage, options, stdin = '') {
+    if (stage === 'commit') {
+        let base;
+        try {
+            base = git(cwd, ['rev-parse', '--verify', 'HEAD']);
+        }
+        catch {
+            base = execFileSync('git', ['-C', cwd, 'hash-object', '-t', 'tree', '--stdin'], { input: '', encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        }
+        return { stage, staged_tree: git(cwd, ['write-tree']), base_revision: base };
+    }
+    if (stage === 'push') {
+        const remote = options.get('--remote');
+        if (!remote || /[\r\n\0]/.test(remote))
+            throw new Error('push requires remote identity');
+        const destination = options.get('--destination');
+        if (!destination || /[\r\n\0]/.test(destination))
+            throw new Error('push requires actual Git hook destination');
+        const lines = stdin.trim().split('\n').filter(Boolean);
+        if (!lines.length || lines.length > 256)
+            throw new Error('push requires exact outgoing refs from hook stdin');
+        const push_refs = lines.map(line => {
+            const fields = line.trim().split(/\s+/);
+            if (fields.length !== 4 || !OID.test(fields[1]) || !OID.test(fields[3]) || ZERO.test(fields[1]) || !(fields[0] === 'HEAD' || fields[0].startsWith('refs/')) || !fields[2].startsWith('refs/'))
+                throw new Error('invalid push ref or deletion; deletion requires separate reviewed handling');
+            revision(cwd, fields[1]);
+            return { local_ref: fields[0], local_oid: fields[1], remote_ref: fields[2], remote_oid: fields[3] };
+        });
+        if (new Set(push_refs.map(r => r.remote_ref)).size !== push_refs.length)
+            throw new Error('duplicate outgoing destination ref');
+        return { stage, destination_digest: hash(destination), push_refs };
+    }
+    if (stage === 'ci') {
+        const source = revision(cwd, options.get('--source') || '');
+        const base = revision(cwd, options.get('--base') || '');
+        return { stage: 'push', context: 'ci', source_revision: source, base_revision: base, tree: git(cwd, ['rev-parse', `${source}^{tree}`]) };
+    }
+    if (stage === 'deploy') {
+        const source = revision(cwd, options.get('--source') || '');
+        const artifact = options.get('--artifact-digest') || '';
+        const configuration = options.get('--configuration-digest') || '';
+        const environment = options.get('--environment') || '';
+        if (!DIGEST.test(artifact) || !DIGEST.test(configuration) || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$/.test(environment))
+            throw new Error('deploy requires exact artifact/configuration SHA256 and environment');
+        return { stage, source_revision: source, artifact_digest: artifact, configuration_digest: configuration, environment };
+    }
+    throw new Error('stage must be commit, push, ci or deploy');
+}
+async function readSafe(file) {
+    await safeParents(file);
+    const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > 1024 * 1024)
+            throw new Error('invalid security file');
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+function quote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
+async function exclusive(file, text, mode = 0o600) {
+    await safeParents(file);
+    const handle = await fs.open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);
+    try {
+        await handle.writeFile(text, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function gitMetadata(cwd) {
+    const root = git(cwd, ['rev-parse', '--show-toplevel']);
+    const directory = path.resolve(cwd, git(cwd, ['rev-parse', '--git-dir']));
+    const hookOverride = (() => { try {
+        return git(cwd, ['config', '--get', 'core.hooksPath']);
+    }
+    catch {
+        return '';
+    } })();
+    if (hookOverride)
+        throw new Error('custom hooksPath requires explicit manual integration');
+    return { root, directory, hooks: path.join(directory, 'hooks'), config: path.join(directory, 'yam-security.json') };
+}
+async function enableHooks(cwd, options, cliPath) {
+    if (process.platform === 'win32')
+        throw new Error('automatic hook setup requires a POSIX Git shell; integrate manually on Windows');
+    const metadata = await gitMetadata(cwd);
+    const settings = JSON.parse(await readSafe(metadata.config));
+    if (settings.schema !== 'yam.security-install.v1' || !DIGEST.test(settings.policy_digest))
+        throw new Error('security init required before hooks enable');
+    const cli = await fs.realpath(cliPath || options.get('--cli') || fileURLToPath(new URL('../bin/yam.js', import.meta.url)));
+    const node = await fs.realpath(process.execPath);
+    if (!(await fs.stat(cli)).isFile())
+        throw new Error('built CLI path required');
+    const files = ['pre-commit', 'pre-push'].map(name => path.join(metadata.hooks, name));
+    for (const file of files) {
+        try {
+            await fs.lstat(file);
+            throw new Error('existing Git hooks preserved; use manual integration');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    await fs.mkdir(metadata.hooks, { recursive: true });
+    const common = `${quote(node)} ${quote(cli)} security check --policy ${quote(settings.policy)} --policy-digest ${quote(settings.policy_digest)} --evidence ${quote(settings.evidence)} --note ${quote(settings.note)}`;
+    const created = [];
+    try {
+        for (const [index, file] of files.entries()) {
+            const stage = index === 0 ? 'commit' : 'push';
+            const remote = index === 1 ? ' --remote "$1" --destination "$2"' : '';
+            await exclusive(file, `#!/bin/sh\n# yam.security-hook.v1\nexec ${common} --stage ${stage}${remote}\n`, 0o700);
+            created.push(file);
+        }
+    }
+    catch (error) {
+        for (const file of created)
+            await fs.unlink(file);
+        throw error;
+    }
+    return { ok: true, result: 'ENABLED', hooks: ['pre-commit', 'pre-push'], enforcement: 'local_bypassable', ci_required: true };
+}
+async function safeParents(file) {
+    let current = path.dirname(path.resolve(file));
+    while (current !== path.dirname(current)) {
+        try {
+            const info = await fs.lstat(current);
+            if (info.isSymbolicLink() || !info.isDirectory())
+                throw new Error('unsafe security file parent');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        current = path.dirname(current);
+    }
+}
+async function initialize(cwd, options) {
+    const metadata = await gitMetadata(cwd);
+    const base = path.join(metadata.root, '.yam', 'security');
+    const policyPath = path.resolve(metadata.root, options.get('--policy') || '.yam/security/policy.json');
+    const evidencePath = path.resolve(metadata.root, options.get('--evidence') || '.yam/security/check.json');
+    const notePath = path.resolve(metadata.root, options.get('--note') || '.yam/security/notes.md');
+    for (const target of [policyPath, evidencePath, notePath]) {
+        if (!target.startsWith(metadata.root + path.sep))
+            throw new Error('init files must be inside repository');
+        await safeParents(target);
+    }
+    // All areas have explicit trusted requirements; live environment inspection is deferred to deploy.
+    const policy = { version: 'security-check-v1', required_at: Object.fromEntries(SECURITY_AREA_IDS.map(id => [id, id === 'SEC-05' ? ['deploy'] : ['commit', 'push', 'deploy']])) };
+    const policyText = JSON.stringify(policy, null, 2) + '\n';
+    const binding = collectSecurityBinding(metadata.root, 'commit', options);
+    const starter = createSecurityStarter({ stage: 'commit', policy, binding: binding, environment: 'local', scope: ['initial project security assessment'], checker: 'operator-review-required' });
+    starter.policy_digest = hash(policyText);
+    const files = [policyPath, evidencePath, metadata.config];
+    for (const file of files) {
+        try {
+            await fs.lstat(file);
+            throw new Error('security init preserves existing files');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    await safeParents(path.join(base, 'placeholder'));
+    await fs.mkdir(base, { recursive: true });
+    const created = [];
+    try {
+        for (const [file, content] of [
+            [policyPath, policyText], [evidencePath, JSON.stringify(starter, null, 2) + '\n'],
+            [metadata.config, JSON.stringify({ schema: 'yam.security-install.v1', policy: policyPath, policy_digest: hash(policyText), evidence: evidencePath, note: notePath }, null, 2) + '\n']
+        ]) {
+            await exclusive(file, content);
+            created.push(file);
+        }
+    }
+    catch (error) {
+        for (const file of created)
+            await fs.unlink(file);
+        throw error;
+    }
+    return { ok: true, result: 'INITIALIZED', policy_digest: hash(policyText), evidence: path.relative(metadata.root, evidencePath), hooks_installed: false, evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+}
+async function verifyReferencedEvidence(cwd, input) {
+    const errors = [];
+    for (const area of input.areas || []) {
+        if (!SECURITY_AREA_IDS.includes(area.id)) {
+            errors.push('invalid_evidence_area');
+            continue;
+        }
+        if (area.status === 'passed' && !area.evidence?.length)
+            errors.push(`evidence_missing:${area.id}`);
+        for (const evidence of area.evidence || []) {
+            if (typeof evidence.reference !== 'string' || !evidence.reference || path.isAbsolute(evidence.reference) || /^[a-z]+:/i.test(evidence.reference)) {
+                errors.push(`evidence_reference_invalid:${area.id}`);
+                continue;
+            }
+            const file = path.resolve(cwd, evidence.reference);
+            if (!file.startsWith(path.resolve(cwd) + path.sep)) {
+                errors.push(`evidence_outside_repository:${area.id}`);
+                continue;
+            }
+            try {
+                if (await digestFile(file, 16 * 1024 * 1024) !== evidence.sha256)
+                    errors.push(`evidence_digest_mismatch:${area.id}`);
+            }
+            catch {
+                errors.push(`evidence_unavailable:${area.id}`);
+            }
+        }
+    }
+    return errors;
+}
+export async function runSecurityCommand(args, settings = {}) {
+    const cwd = await fs.realpath(path.resolve(settings.cwd || process.cwd()));
+    const subcommand = args[0];
+    try {
+        if (subcommand === 'hooks') {
+            if (args[1] !== 'enable')
+                throw new Error('supported hook operation: enable');
+            return await enableHooks(cwd, parseArgs(args.slice(2)), settings.cliPath);
+        }
+        const options = parseArgs(args.slice(1));
+        if (subcommand === 'init')
+            return await initialize(cwd, options);
+        if (subcommand === 'status') {
+            const metadata = await gitMetadata(cwd);
+            let configured = false;
+            try {
+                const config = JSON.parse(await readSafe(metadata.config));
+                configured = config.schema === 'yam.security-install.v1';
+            }
+            catch { /* unavailable is reported */ }
+            const installed = [];
+            for (const name of ['pre-commit', 'pre-push']) {
+                try {
+                    if ((await readSafe(path.join(metadata.hooks, name))).includes('# yam.security-hook.v1'))
+                        installed.push(name);
+                }
+                catch { /* unavailable is reported */ }
+            }
+            return { ok: true, configured, local_hooks: installed, local_hooks_bypassable: true, remote_enforcement: 'not_measured', evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+        }
+        if (subcommand !== 'check')
+            throw new Error('supported commands: init, check, hooks enable, status');
+        return await check(cwd, options, settings);
+    }
+    catch {
+        if (subcommand === 'check') {
+            const input = createSecurityStarter({ stage: 'commit', binding: { stage: 'commit', invalid_binding: true }, environment: 'local', scope: ['rejected security command'], checker: 'yam-security-check' });
+            const result = validateSecurityCheck(input);
+            result.errors.push('security_command_failed');
+            result.blocking.push('integration:security_command_failed');
+            result.result = 'BLOCKED';
+            try {
+                const persisted = await persistSecurityCheck(cwd, input, result);
+                return { ok: false, ...persisted, evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+            }
+            catch {
+                return { ok: false, result: 'BLOCKED', errors: ['security_command_failed', 'security_note_persistence_failed'] };
+            }
+        }
+        return { ok: false, result: 'BLOCKED', errors: ['security_command_failed'], evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+    }
+}
+async function check(cwd, options, settings) {
+    const stage = options.get('--stage') || 'commit';
+    const normalizedStage = stage === 'ci' ? 'push' : stage;
+    let config = {};
+    try {
+        const metadata = await gitMetadata(cwd);
+        config = JSON.parse(await readSafe(metadata.config));
+    }
+    catch { /* an explicit trust pin can be provided instead */ }
+    const notePath = path.resolve(cwd, options.get('--note') || config.note || '.yam/security/notes.md');
+    let input;
+    let binding = { stage: normalizedStage, invalid_binding: true };
+    let policy = { version: 'security-check-v1', required_at: Object.fromEntries(SECURITY_AREA_IDS.map(id => [id, ['commit', 'push', 'deploy']])) };
+    let result;
+    const gateErrors = [];
+    try {
+        const policyFile = path.resolve(cwd, options.get('--policy') || config.policy || '.yam/security/policy.json');
+        const pin = options.get('--policy-digest') || ((stage !== 'ci' && stage !== 'deploy') ? config.policy_digest : undefined);
+        if (!pin || !DIGEST.test(pin))
+            throw new Error('policy_pin_missing');
+        const policyText = await readSafe(policyFile);
+        if (hash(policyText) !== pin)
+            throw new Error('policy_pin_mismatch');
+        policy = JSON.parse(policyText);
+        if (!policy || typeof policy.version !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(policy.version) || Object.keys(policy).some(key => !['version', 'required_at'].includes(key)) || !policy.required_at || Object.keys(policy.required_at).some(key => !SECURITY_AREA_IDS.includes(key)) || SECURITY_AREA_IDS.some(id => !Array.isArray(policy.required_at[id])))
+            throw new Error('policy_invalid');
+        for (const id of ['SEC-01', 'SEC-08'])
+            if (!['commit', 'push', 'deploy'].every(s => policy.required_at[id].includes(s)))
+                throw new Error('mandatory_policy_invalid');
+        for (const id of SECURITY_AREA_IDS)
+            if (!policy.required_at[id].length || policy.required_at[id].some(s => !['commit', 'push', 'deploy'].includes(s)))
+                throw new Error('policy_stage_invalid');
+        const stdin = stage === 'push' ? (settings.stdin ?? await readSafeStdin()) : '';
+        if (stage === 'deploy') {
+            for (const [fileOption, digestOption] of [['--artifact', '--artifact-digest'], ['--configuration', '--configuration-digest']]) {
+                const file = options.get(fileOption);
+                if (!file || await digestFile(path.resolve(cwd, file), 1024 * 1024 * 1024) !== options.get(digestOption))
+                    throw new Error('deployment_file_digest_mismatch');
+            }
+        }
+        binding = collectSecurityBinding(cwd, stage, options, stdin);
+        const evidenceText = await readSafe(path.resolve(cwd, options.get('--evidence') || config.evidence || '.yam/security/check.json'));
+        input = JSON.parse(evidenceText);
+        if (input.policy_digest !== pin)
+            gateErrors.push('policy_digest_mismatch');
+        if (input.stage !== normalizedStage)
+            gateErrors.push('stage_mismatch');
+        if (SECURITY_AREA_IDS.some(id => !input.areas?.some(area => area.id === id)))
+            gateErrors.push('area_coverage_missing');
+        if (input.areas?.some(area => ['SEC-01', 'SEC-08'].includes(area.id) && area.status === 'not_applicable'))
+            gateErrors.push('mandatory_area_not_applicable');
+        gateErrors.push(...await verifyReferencedEvidence(cwd, input));
+        input = { ...input, retry_of: input.run_id, run_id: `security-${randomUUID()}`, time: new Date().toISOString() };
+        result = validateSecurityCheck(input, binding, policy);
+        if (result.errors.includes('record_contains_secret')) {
+            input = createSecurityStarter({ stage: normalizedStage, binding: binding, environment: 'redacted', scope: ['unsafe supplied record rejected'], checker: 'yam-security-check' });
+            result = validateSecurityCheck(input, binding);
+            gateErrors.push('unsafe_security_record_rejected');
+        }
+        // Inspect the index/refs once more before persisting so mid-check changes cannot retain PASS.
+        const fresh = collectSecurityBinding(cwd, stage, options, stdin);
+        if (JSON.stringify(fresh) !== JSON.stringify(binding))
+            gateErrors.push('binding_changed_during_check');
+        if (stage === 'deploy') {
+            for (const [fileOption, digestOption] of [['--artifact', '--artifact-digest'], ['--configuration', '--configuration-digest']]) {
+                if (await digestFile(path.resolve(cwd, options.get(fileOption)), 1024 * 1024 * 1024) !== options.get(digestOption))
+                    gateErrors.push('deployment_file_changed_during_check');
+            }
+        }
+    }
+    catch {
+        input = createSecurityStarter({ stage: normalizedStage, binding: binding, environment: stage === 'deploy' ? options.get('--environment') || 'unavailable' : 'local', scope: ['security gate unavailable'], checker: 'yam-security-check' });
+        result = validateSecurityCheck(input, binding);
+        gateErrors.push('security_input_or_binding_unavailable');
+    }
+    if (gateErrors.length) {
+        result.result = 'BLOCKED';
+        result.errors = [...new Set([...result.errors, ...gateErrors])];
+        result.blocking = [...new Set([...result.blocking, ...gateErrors.map(e => `integration:${e}`)])];
+    }
+    try {
+        const persisted = await persistSecurityCheck(cwd, input, result, { notePath });
+        return { ok: persisted.result.result === 'PASS', ...persisted, evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+    }
+    catch {
+        return { ok: false, result: 'BLOCKED', errors: ['security_note_persistence_failed'], evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+    }
+}
+async function readSafeStdin() {
+    const text = readFileSync(0, 'utf8');
+    if (text.length > 128 * 1024)
+        throw new Error('push_ref_input_too_large');
+    return text;
+}
+async function digestFile(file, limit) {
+    await safeParents(file);
+    const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > limit)
+            throw new Error('invalid digest target');
+        const digest = createHash('sha256');
+        const buffer = Buffer.alloc(64 * 1024);
+        let position = 0;
+        while (position < info.size) {
+            const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, info.size - position), position);
+            if (!bytesRead)
+                throw new Error('digest target changed during read');
+            digest.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+        const after = await handle.stat();
+        if (after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs)
+            throw new Error('digest target changed during read');
+        return `sha256:${digest.digest('hex')}`;
+    }
+    finally {
+        await handle.close();
+    }
+}

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.0",
+  "version": "2.8.2",
   "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 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",
@@ -72,6 +72,10 @@
     "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",
@@ -102,7 +106,10 @@
     "memory": "node ./dist/bin/yam.js memory",
     "template": "node ./dist/bin/yam.js template",
     "tune-log": "node ./dist/bin/yam.js tune-log",
-    "init-project": "node ./dist/bin/yam.js init-project"
+    "init-project": "node ./dist/bin/yam.js init-project",
+    "security:check": "node ./dist/bin/yam.js security check --stage ci --json",
+    "security-smoke": "node ./scripts/security-check-smoke.mjs",
+    "security-integration-smoke": "node ./scripts/security-integration-smoke.mjs"
   },
   "keywords": [
     "codex",

package/references/final-report.md

@@ -4,6 +4,8 @@ Every `yam` route should end with a compact handoff that helps the next run avoi
 
 ## Required Closing Check
 
+For commit, push, or deployment security reports, use the separate Security check block defined in `references/security-check.md` and `templates/security-check-note.md`. An SEC ID alone is insufficient: include its concrete security explanation, evidence, limitations, and the stage decision. Keep this block before Study Note or after Next step. The CLI validates supplied evidence and writes notes; local hooks and remote CI/deployment enforcement require explicit project setup.
+
 Always keep final reports short. Include these when they apply:
 
 - What changed or what was found.

package/references/security-check.md

@@ -0,0 +1,131 @@
+# Security check contract v1
+
+This document defines the security-check contract and the human-readable `Security check` block in a Yam note. `yam security check` validates supplied reports, trusted stage policy, target bindings and evidence-file hashes, then writes a note. It is not an automatic vulnerability scanner and does not change `yam.study-note.v1`. A passing gate proves that the supplied evidence contract matches the checked target; it does not independently establish the truth or completeness of the evidence.
+
+## Scope and timing
+
+Assess security applicability during new development and changes. Before commit, push, or deployment, require a note and evidence for the checks required at that stage. A new project receives an initial assessment of all nine areas; later work reassesses changed boundaries and may reuse unchanged evidence with its source and validity reason.
+
+- Commit: bind the run to the actual staged tree and base revision, including newly staged files. Unstaged working files are not proof of the staged content. Changing the index invalidates the result.
+- Push: bind the run to the exact outgoing commit IDs and destination. Recheck the outgoing changes; a local note alone is insufficient proof for the future remote CI gate.
+- Deploy: bind the run to the exact artifact digest, source commit, target environment, and relevant configuration revision. Verify actual environment settings; build success does not establish deployment security.
+- Evidence reuse is valid only when the checked content, policy version, dependencies, and relevant environment/configuration remain unchanged. A code digest alone cannot validate live environment evidence.
+
+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.
+
+## 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.
+
+| ID | Required security explanation summary |
+| --- | --- |
+| SEC-01 | 사용자·관리자·외부 서비스·DB·파일 사이의 신뢰 경계와 보호할 데이터·작업을 식별한다. |
+| SEC-02 | 명시적으로 허용한 접근만 열고, 사용자·서비스 계정에 필요한 최소 권한만 부여한다. |
+| SEC-03 | 화면을 우회한 API·서버 함수·DB·파일·백그라운드 작업에서도 사용자·조직·대상별 권한을 확인한다. |
+| SEC-04 | 계정 정지·승인 철회·탈퇴·소속 변경 후 기존 세션·토큰·캐시에서도 권한 회수가 반영된다. |
+| SEC-05 | 코드의 보안 정책·migration·ACL·환경 설정이 대상 배포 환경의 실제 상태와 일치한다. |
+| SEC-06 | 로그인·관리자 인증·세션 만료·로그아웃·비밀번호 재설정·계정 복구가 계정 탈취를 막도록 동작한다. |
+| SEC-07 | 외부 입력·파일 업로드·출력의 형식·크기·경로를 검증하고 SQL 주입·XSS·SSRF·CSRF 등 해당 공격을 방어한다. |
+| SEC-08 | API 키·토큰·개인키·개인정보가 코드·브라우저 번들·로그·점검 기록에 불필요하게 노출되지 않는다. |
+| SEC-09 | 의존성·CI/CD 권한·배포 자격증명·릴리스 산출물의 출처와 무결성을 확인해 공급망 위험을 통제한다. |
+
+SEC-01 applicability assessment and SEC-08 note disclosure review are required for every run. Other areas can be inapplicable only with a concrete project and stage reason. A static site may still have deployment credentials, third-party scripts, or dependencies. Lack of access or a missing test is `미검증`, never `해당 없음`.
+
+Conditional subchecks belong under the relevant area: atomic multi-record writes and incomplete reads under SEC-01/03; retry/idempotency and concurrent resource changes under SEC-03; stable IDs and organization ownership under SEC-03/04; export permissions and CSV output under SEC-03/07; audit history access/retention under SEC-08. Record applicable subchecks separately so one passing subcheck cannot hide another unchecked subcheck. Static-analysis findings require reproduction or other adequate evidence before dismissal. N+1 and index tuning remain performance concerns unless there is a concrete availability, data-boundary, or integrity risk.
+
+## Five statuses and deterministic gate
+
+| Status | Meaning | Required-at-stage gate |
+| --- | --- | --- |
+| 점검 완료 - 이상 없음 | All applicable required subchecks passed with matching evidence. | Allow |
+| 점검 완료 - 보완 필요 | The check ran and identified an unresolved issue; include severity, owner, follow-up and mitigation. | Block |
+| 점검 실패 | A security requirement failed or a defect was reproduced. | Block |
+| 미검증 | Required evidence is absent, incomplete, stale, or unavailable. | Block |
+| 해당 없음 | No applicable requirement exists for this project and stage; include the reason. | Allow |
+
+Overall result is `PASS` only when every required area/subcheck is valid and is either evidenced `이상 없음` or justified `해당 없음`. Otherwise it is `BLOCKED`; show blocking IDs and reasons. Missing or duplicate IDs, missing explanations, invalid statuses, missing binding fields, unfilled template values, or a note-write failure also block the stage. Severity prioritizes remediation and does not silently turn an unresolved finding into a pass. This v1 contract has no automatic waiver path.
+
+Some evidence is only available at a later stage. Record `required_at` per area/subcheck and keep the unresolved state visible as `미검증`; for example, live SEC-05 environment inspection may be required at `deploy`. This does not block a commit if the commit-stage policy explicitly defers that live check, but it blocks deployment until verified. Version the stage policy and record it with the run. Do not downgrade a required-at-current-stage check to a later stage merely to obtain `PASS`.
+
+## Yam note format
+
+In the source repository or package root, use `templates/security-check-note.md`. Installed skills copy references but not templates; use the self-contained starter below when that file is unavailable. `Security check` is an independent block, not a replacement for Study Note or Next step. In changed-artifact reports keep Next step immediately after Study Note; place Security check before that pair. The existing Study Note JSON schema is unchanged.
+
+```text
+-- Security check --
+
+Contract: security-check-v1
+Run: <unique run ID>; Time: <ISO timestamp with timezone>
+Stage: <commit | push | deploy>; Policy: <stage-policy version>
+Environment: <target environment or explicit local/not-applicable reason>
+Binding: <commit: staged tree and base revision | push: outgoing commit IDs and destination | deploy: artifact digest, source commit, environment and configuration revision>
+Scope: <changed paths and connected security boundaries>
+Checker: <tool/version or named reviewer>; Evidence: <sanitized evidence references>
+
+1. SEC-01 : "사용자·관리자·외부 서비스·DB·파일 사이의 신뢰 경계와 보호할 데이터·작업을 식별한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+2. SEC-02 : "명시적으로 허용한 접근만 열고, 사용자·서비스 계정에 필요한 최소 권한만 부여한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+3. SEC-03 : "화면을 우회한 API·서버 함수·DB·파일·백그라운드 작업에서도 사용자·조직·대상별 권한을 확인한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+4. SEC-04 : "계정 정지·승인 철회·탈퇴·소속 변경 후 기존 세션·토큰·캐시에서도 권한 회수가 반영된다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+5. SEC-05 : "코드의 보안 정책·migration·ACL·환경 설정이 대상 배포 환경의 실제 상태와 일치한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+6. SEC-06 : "로그인·관리자 인증·세션 만료·로그아웃·비밀번호 재설정·계정 복구가 계정 탈취를 막도록 동작한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+7. SEC-07 : "외부 입력·파일 업로드·출력의 형식·크기·경로를 검증하고 SQL 주입·XSS·SSRF·CSRF 등 해당 공격을 방어한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+8. SEC-08 : "API 키·토큰·개인키·개인정보가 코드·브라우저 번들·로그·점검 기록에 불필요하게 노출되지 않는다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+9. SEC-09 : "의존성·CI/CD 권한·배포 자격증명·릴리스 산출물의 출처와 무결성을 확인해 공급망 위험을 통제한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+
+Result: BLOCKED
+Blocking: <required-at-current-stage unresolved IDs/subchecks or invalid record fields>
+Deferred: <later-stage missing evidence, required stage, owner and action; none if absent>
+Retry of: <prior run ID or none>
+-- End Security check --
+```
+
+This full starter contains all nine IDs and defaults to `미검증`/`BLOCKED`; copying it cannot create successful evidence. For `보완 필요` or `점검 실패`, record the finding, severity, owner, follow-up action/date and mitigation. For `해당 없음`, record the concrete project/stage reason.
+
+Each detail records required stages, actual checked target, command/test/review reference, result and time, plus any skipped subcheck. Human review is acceptable for design checks when the reviewer and inspected scope are explicit. A status supplied by an agent is not independent runtime evidence. Do not call the whole system secure from this checklist alone.
+
+## Persistence and enforcement boundaries
+
+- Append one complete block per run to the project's existing Yam note. If none exists, the default is `.yam/security/notes.md`; keep it out of published package contents. Do not overwrite user notes or silently initialize Git hooks.
+- Failed runs also leave a record. Preserve earlier records and connect retries by run ID; never rewrite a failure into a pass. Append-only behavior is a design requirement, not tamper-proof storage against the same OS user.
+- Store only redacted findings and references. Never include secret values, credential-bearing URLs, raw environment dumps, personal data, or malicious payload contents in the note. If safe persistence fails, block and report a sanitized error.
+- The validator rejects incomplete coverage and mismatched bindings; checks remeasure staged content, outgoing refs, or deployment files before persistence. Note writes are serialized with a bounded lock. Unsafe paths, links, duplicate run IDs and write failures block. A run JSON may remain if its note append fails: this is not a successful gate.
+- Focused hook/CI tests cover normal pass, improvement needed, failure, missing evidence, justified non-applicability, staged/unstaged mismatch, changed outgoing revisions, changed deployment artifact/configuration, missing note writes, bypassed local hooks, and note secret redaction.
+- `security init` and `security hooks enable` explicitly configure a project. No global hooks are installed by package installation. Remote branch protection and deployment authorization are outside the local CLI; until the required CI job and deployment dependency are configured, remote enforcement is incomplete.
+
+## Runtime commands
+
+```sh
+yam security init
+yam security status
+yam template security
+yam security check --stage commit --json
+yam security hooks enable
+```
+
+Init preserves existing files, creates a private draft at `.yam/security/check.json`, a policy at `.yam/security/policy.json`, and pins the exact policy file digest in Git-local `yam-security.json`. Every draft area is unverified. Replace draft values with real stage-bound review/test evidence before enabling workflows. Init does not grant PASS. Report fields follow `SecurityCheckInput` in `src/lib/security-check.ts`; `createSecurityStarter` and `collectSecurityBinding` provide exact report construction for each stage. Evidence uses repository-relative regular files, `sha256:<64 hex>` of their bytes, checker, checked_at, and `result: "passed"` for passing checks. IDs, canonical explanations and stage requirements are mandatory.
+
+Policy uses `version` and a `required_at` map for all nine IDs. SEC-01/08 must apply at every stage; other areas may defer only through the reviewed policy. CI maps to push requirements but has a distinct source/base/tree binding, so a local push report cannot stand in for a CI report. The exact policy file bytes are pinned, including whitespace. Reapprove a changed policy externally; do not take a policy pin from the same untrusted change that it is intended to verify.
+
+```sh
+# pre-push hook supplies refs on stdin and the actual remote destination.
+yam security check --stage push --remote origin --destination <actual-destination> --json
+# CI independently validates its report; policy pin comes from trusted runner settings.
+yam security check --stage ci --source <exact-commit> --base <exact-base> --policy security/policy.json --policy-digest <trusted-sha256> --evidence security/check.json --json
+# Deployment measures actual artifact/configuration file bytes as well as matching the report.
+yam security check --stage deploy --source <exact-commit> --artifact <file> --artifact-digest <sha256> --configuration <file> --configuration-digest <sha256> --environment production --policy <file> --policy-digest <trusted-sha256> --evidence <report> --json
+```
+
+`--note <repository-local-file>` can append to an existing Yam note. The default private note is `.yam/security/notes.md`; JSON runs go under `.yam/security/runs/`. Hooks refuse existing hooks and custom `core.hooksPath` rather than overwrite them. POSIX hook setup is supported; Windows and custom hooks need manual integration. Ref deletion pushes fail closed pending a separately reviewed workflow. CI initial pushes without a valid base also fail closed; use a reviewed exact base instead of fabricating a prior revision.
+
+`yam template security-ci` prints `templates/security-gate.yml`. It is a project setup template, not an active workflow in this repository: provision the trusted yam runner, approved policy pin, real test/review evidence, artifact retention and required branch check before enabling it. Put the same deployment gate immediately before the deployment operation, make later steps depend on success, and restrict bypass routes. Running a local command cannot change hosting-provider branch rules. Do not run untrusted project code with production credentials.
+
+Conditional subchecks must be represented in the referenced review/test evidence for their parent area. The validator does not discover omitted application requirements or execute project scanners. Supply independently generated evidence or an identified reviewer; operator-authored status and hash alone can be fabricated. Deploy configuration file hashes prove file identity, not cloud state: include actual environment inspection evidence for SEC-05. Secret-pattern rejection is best effort and not a comprehensive privacy classifier; record only sanitized references and short findings, never raw personal data or credential values. Same-user concurrent filesystem replacement cannot be fully prevented with Node path checks; this is not an adversarial same-user sandbox.