yam-flow 2.8.4 → 2.8.5

package/AGENTS.md

@@ -24,6 +24,10 @@
 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.
 
+## Test check completion gate
+
+After implementation and before claiming changed work complete, follow `references/test-check.md`: identify the exact starting revision, map changed targets to required scenarios, run the project Test check adapter and require a current PASS plus its explained note. Missing real DB/runtime evidence, skipped required scenarios, stale source/environment or note-write failures block completion approval. Report `Test check: BLOCKED` for an incomplete handoff; it does not grant commit/push/deployment approval. Recheck source identity before those operations. Do not treat report formatting, mock results, or operator-declared receipts as actual runtime verification. Projects need their own policy and adapters; an unavailable configuration is not a security or completion approval.
+
 ## Security check gate
 
 Before commit, push, CI approval, or deployment, run the configured `yam security check` gate for the exact stage and record its Security check block. Use `references/security-check.md`; preserve every SEC explanation, evidence reference, and unresolved status. Missing required evidence or a note-write failure blocks the stage. Local hooks are bypassable; enforce protected merge/deployment with a trusted CI policy and required checks. Never present a validated supplied report as an independent vulnerability scan.

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.8.5 - 2026-10-28
+
+### Added
+
+- Add the Test check completion gate with project-owned scenario policies, measured subprocess observations, source/environment bindings and private append-only notes.
+- Require current Test check evidence before configured commit, push, CI and deployment security approval; CI verifies an administrator-reviewed test policy pin before executing project code.
+- Add an optional isolated PostgreSQL simulation that reproduces SQLSTATE 42702 and checks normal writes, authorization, rollback, migration freshness and function drift using synthetic data.
+
+### Fixed
+
+- Keep private `.yam` research receipts and temporary tools outside the public-product terminology scan while retaining checks for public source and documentation.
+
+### Verification
+
+- 49 gate regression cases and full self-verification passed. Real PostgreSQL 17.10 simulations cover ten workflow scenarios and a 16-case role/brand/quantity matrix.
+- Exact-target security integration and package checks passed locally. Production application behavior and hosted rollout require their own project evidence.
+
 ## v2.8.4 - 2026-10-26
 
 ### Improved

package/COMMANDS.md

@@ -353,3 +353,7 @@ yam hook disable study-note --global
 - `yam template security` / `yam template security-ci`: explained note and CI setup templates.
 
 See `references/security-check.md` for stage arguments, trusted policy requirements and limitations. This validates supplied evidence; it does not automatically scan application vulnerabilities.
+
+## Test check
+
+Before changed-work completion: `yam test-check plan --base <exact starting commit> --json`, then `yam test-check run --base <exact starting commit> --json` and `yam test-check check --json`. Configure `testing/policy.json` or `.yam/testing/policy.json` and a reviewed JSON-report adapter first. `yam template test-check` prints a blocked-until-configured starter. See `references/test-check.md` for scenario floors, real DB manifests, Stop integration and stage-specific identity checks. `check --stage commit` verifies index equality; push/CI/deploy require `--source <exact commit>` and CI/deploy also require a trusted `--policy-digest`. No global hook, branch protection or deployment is silently installed.

package/dist/bin/yam.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { runTestCheckCommand, testCheckStop, testCheckConfigured } from '../lib/test-check.js';
 import { spawnSync } from 'node:child_process';
 import { studyNoteTurnScope } from '../lib/study-note-scope.js';
 import { selectHookNode, probeHookDiscovery, inspectHookObservation, recordHookObservation } from '../lib/hook-readiness.js';
@@ -149,6 +150,7 @@ Usage:
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
   yam study-note check [dir] [--report file|--text text] [--json]
+  yam test-check <plan|run|check|status> [--base commit] [--json]
   yam security <init|check|hooks|status> [--stage commit|push|ci|deploy] [--json]
   yam next-step <report|verify> [--spec file|--receipt file] [--json]
   yam loop report [--route route] [--intent text] [--stage id:status:note] [--evidence text] [--json]
@@ -175,7 +177,7 @@ Usage:
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
   yam hook <status|enable|disable|run> [lite|study-note] [--global|--project dir]
-  yam template <project|ueye|mission|proof|tuning|security|security-ci>
+  yam template <project|ueye|mission|proof|tuning|security|security-ci|test-check>
   yam tune-log [dir]
   yam install [--dry-run] [--json] [--replace-user-skill name]
   yam uninstall
@@ -495,6 +497,7 @@ async function verify({ quiet = false } = {}) {
         'markdown-management.md',
         'study-note.md',
         'security-check.md',
+        'test-check.md',
         'final-report.md',
         'token-budget-reporter.md',
         'memory.md'
@@ -513,7 +516,7 @@ async function verify({ quiet = false } = {}) {
                 issues.push(`project template missing section: ${section}`);
         }
     }
-    for (const template of ['ueye-review.md', 'ueye-comparison.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md', 'security-check-note.md', 'security-gate.yml']) {
+    for (const template of ['ueye-review.md', 'ueye-comparison.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md', 'security-check-note.md', 'security-gate.yml', 'test-check-policy.json']) {
         if (!await exists(path.join(ROOT, 'templates', template)))
             issues.push(`missing template: ${template}`);
     }
@@ -2477,6 +2480,9 @@ async function buildYamLiteContext({ cwd, prompt }) {
 async function buildStudyNoteStopOutput(input = {}, cwd = process.cwd()) {
     const lastAssistantMessage = String(input?.last_assistant_message || input?.lastAssistantMessage || '');
     const scope = studyNoteTurnScope(input, cwd);
+    const testGate = testCheckStop(cwd, !scope.available || scope.files.length > 0, lastAssistantMessage);
+    if (testGate)
+        return testGate;
     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 {
@@ -2507,9 +2513,10 @@ async function buildStudyNoteStopOutput(input = {}, cwd = process.cwd()) {
 }
 async function buildStudyNoteTurnContext(input, cwd) {
     const scope = studyNoteTurnScope(input, cwd, true);
+    const testReminder = testCheckConfigured(cwd) ? ' Test check active: before completion run yam test-check run --base <exact starting commit> --json and yam test-check check --json. Missing required tests/evidence block completion; report Test check: BLOCKED if unable to verify. This is separate from report formatting and Security check.' : '';
     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.'}`;
+    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.'}${testReminder}`;
 }
 function yamLiteRouteHint(prompt = '') {
     const text = String(prompt || '').toLowerCase();
@@ -6132,11 +6139,12 @@ async function printTemplate(name = '') {
         runtime: 'runtime-proof.md',
         tuning: 'tuning-log.md',
         security: 'security-check-note.md',
-        'security-ci': 'security-gate.yml'
+        'security-ci': 'security-gate.yml',
+        'test-check': 'test-check-policy.json'
     };
     const file = map[key];
     if (!file) {
-        console.error('usage: yam template <project|ueye|ueye-comparison|mission|proof|tuning|security|security-ci>');
+        console.error('usage: yam template <project|ueye|ueye-comparison|mission|proof|tuning|security|security-ci|test-check>');
         process.exitCode = 1;
         return;
     }
@@ -6433,6 +6441,17 @@ function showRequestedHelp(args) {
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0] || 'help';
+    if (command === 'test-check') {
+        if (!args[1] || ['help', '--help', '-h'].includes(args[1])) {
+            console.log('yam test-check run --base <exact commit> [--policy file --policy-digest sha256] [--json]\nyam test-check check [--stage complete|commit|push|ci|deploy --source <exact commit> --policy-digest sha256 --receipt file] [--json]\nyam test-check status\nyam test-check plan --base <exact commit> --json\nSee references/test-check.md for required scenarios, adapters and activation.');
+            return;
+        }
+        const result = runTestCheckCommand(args.slice(1));
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (showRequestedHelp(args))
         return;
     if (command === 'help')

package/dist/lib/security-integration.js

@@ -1,3 +1,4 @@
+import { checkTestCheck, testCheckConfigured } from './test-check.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs/promises';
@@ -30,7 +31,7 @@ function parseArgs(args) {
     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]))
+        if (!['--policy', '--policy-digest', '--evidence', '--note', '--stage', '--remote', '--destination', '--source', '--base', '--artifact', '--artifact-digest', '--configuration', '--configuration-digest', '--environment', '--cli', '--test-policy-digest'].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]);
     }
@@ -381,6 +382,14 @@ async function check(cwd, options, settings) {
         result = validateSecurityCheck(input, binding);
         gateErrors.push('security_input_or_binding_unavailable');
     }
+    if (testCheckConfigured(cwd) || config.test_policy_digest) {
+        const pin = options.get('--test-policy-digest') || config.test_policy_digest;
+        const sources = stage === 'push' ? (binding.push_refs || []).map(ref => ref.local_oid)
+            : [binding.source_revision];
+        const targets = sources.length ? sources : [undefined];
+        if (targets.some(source => !checkTestCheck(cwd, { stage, source, pin, base: stage === 'ci' ? binding.base_revision : undefined, artifact: options.get('--artifact'), configuration: options.get('--configuration') }).ok))
+            gateErrors.push('test_check_blocked');
+    }
     if (gateErrors.length) {
         result.result = 'BLOCKED';
         result.errors = [...new Set([...result.errors, ...gateErrors])];

package/dist/lib/test-check.d.ts

@@ -0,0 +1,156 @@
+export declare const TEST_REQUIREMENTS: {
+    readonly docs: readonly ["inspection"];
+    readonly logic: readonly ["success", "invalid", "boundary"];
+    readonly api: readonly ["success", "invalid", "contract"];
+    readonly db: readonly ["success", "denied", "invalid", "readback", "rollback", "migration_upgrade", "migration_fresh"];
+    readonly auth: readonly ["success", "denied", "cross_scope", "revoked"];
+    readonly ui: readonly ["success", "error"];
+    readonly release: readonly ["artifact", "integrity"];
+};
+type Risk = keyof typeof TEST_REQUIREMENTS;
+type Check = {
+    id: string;
+    target: string;
+    scenario: string;
+    explanation: string;
+    evidence: 'static' | 'unit' | 'integration' | 'e2e';
+    command: string[];
+    environment?: string;
+};
+type Surface = {
+    id: string;
+    paths: string[];
+    risks: Risk[];
+    targets: string[];
+    checks: Check[];
+};
+type Policy = {
+    schema: 'yam.test-policy.v1';
+    surfaces: Surface[];
+};
+export declare function planTestCheck(root: string, policy: Policy, base: string): {
+    changed: string[];
+    source_digest: string;
+    checks: Check[];
+    errors: string[];
+};
+export declare function runTestCheck(cwd: string, options?: {
+    policy?: string;
+    pin?: string;
+    base?: string;
+    stage?: string;
+    source?: string;
+    artifact?: string;
+    configuration?: string;
+}): {
+    ok: boolean;
+    result: string;
+    errors: any[];
+    run?: undefined;
+    note?: undefined;
+    receipt?: undefined;
+    changed_files?: undefined;
+    checks?: undefined;
+} | {
+    ok: boolean;
+    result: any;
+    errors: any;
+    run: any;
+    note: string;
+    receipt: string;
+    changed_files: any;
+    checks: number;
+};
+export declare function checkTestCheck(cwd: string, options?: {
+    policy?: string;
+    pin?: string;
+    stage?: string;
+    source?: string;
+    receipt?: string;
+    artifact?: string;
+    configuration?: string;
+    base?: string;
+}): {
+    ok: boolean;
+    result: string;
+    errors: string[];
+    run: any;
+    checks: number;
+} | {
+    ok: boolean;
+    result: string;
+    errors: string[];
+    run?: undefined;
+    checks?: undefined;
+};
+export declare function testCheckConfigured(cwd: string): boolean;
+export declare function testCheckStop(cwd: string, changed: boolean, message: string): {
+    continue: boolean;
+    systemMessage: string;
+    decision?: undefined;
+    reason?: undefined;
+} | {
+    decision: string;
+    reason: string;
+    continue?: undefined;
+    systemMessage?: undefined;
+};
+export declare function runTestCheckCommand(args: string[], cwd?: string): {
+    ok: boolean;
+    result: string;
+    errors: any[];
+    run?: undefined;
+    note?: undefined;
+    receipt?: undefined;
+    changed_files?: undefined;
+    checks?: undefined;
+} | {
+    ok: boolean;
+    result: any;
+    errors: any;
+    run: any;
+    note: string;
+    receipt: string;
+    changed_files: any;
+    checks: number;
+} | {
+    ok: boolean;
+    result: string;
+    errors: string[];
+    run: any;
+    checks: number;
+} | {
+    ok: boolean;
+    result: string;
+    errors: string[];
+    run?: undefined;
+    checks?: undefined;
+} | {
+    checks: {
+        id: string;
+        target: string;
+        scenario: string;
+        explanation: string;
+        evidence: "static" | "unit" | "integration" | "e2e";
+    }[];
+    policy_digest: string;
+    changed: string[];
+    source_digest: string;
+    errors: string[];
+    ok: boolean;
+} | {
+    ok: boolean;
+    result: string;
+    errors: string[];
+    run: any;
+    checks: number;
+    configured: boolean;
+} | {
+    ok: boolean;
+    result: string;
+    errors: string[];
+    run?: undefined;
+    checks?: undefined;
+    configured: boolean;
+};
+export {};