yam-flow 0.1.5 → 0.1.7

package/dist/lib/trust-kernel.d.ts

@@ -68,6 +68,28 @@ export interface UeyeSurfaceContext {
     local_only: boolean;
     truth_status: TruthStatus;
 }
+export interface UeyeDesignGateCheck {
+    id: string;
+    label: string;
+    status: 'pass' | 'fail' | 'warning' | 'not_checked';
+    required: boolean;
+    next_action: string;
+}
+export interface UeyeDesignCompletionGate {
+    schema: 'yam.ueye-design-completion-gate.v1';
+    mode: 'fast' | 'strict';
+    completion_claim: 'draft' | 'needs-polish' | 'done';
+    ready_to_claim_done: boolean;
+    design_score: number | null;
+    min_design_score: number;
+    checks: UeyeDesignGateCheck[];
+    p0: string[];
+    p1: string[];
+    warnings: string[];
+    blockers: string[];
+    next_action: string;
+    truth_status: TruthStatus;
+}
 export interface RollbackHint {
     schema: 'yam.rollback-hint.v1';
     touched_files: string[];
@@ -91,6 +113,14 @@ export interface RuntimeBackendEvidence {
     evidence_id: string;
     command: string;
     cleanup_checked: boolean;
+    started_at: string;
+    stopped_at: string;
+    exit_code: number | null;
+    pid: number | null;
+    port: number | null;
+    cleanup_method: string;
+    cleanup_observed: boolean;
+    left_running_intentionally: boolean;
     note: string;
     truth_status: TruthStatus;
 }
@@ -99,12 +129,16 @@ export interface UeyeRunReport {
     reference_sources: UeyeVisualProvenance[];
     implementation_sources: UeyeVisualProvenance[];
     surface_context: UeyeSurfaceContext;
+    design_completion_gate: UeyeDesignCompletionGate;
     comparison_result: string;
     design_quality: string;
     blocked_reason: string;
     next_action: string;
     truth_status: TruthStatus;
 }
+export interface UeyeRunReportInput extends Partial<Omit<UeyeRunReport, 'design_completion_gate'>> {
+    design_completion_gate?: Partial<UeyeDesignCompletionGate> & Record<string, unknown>;
+}
 export interface MediaGenerationProof {
     schema: 'yam.media-generation-proof.v1';
     tool_name: string;
@@ -145,6 +179,7 @@ export interface ProofSummary {
     rollbackHint?: unknown;
     runtimeBackendEvidence?: unknown;
     mediaProof?: unknown;
+    designCompletion?: unknown;
 }
 export interface ProofOptions {
     requireRealRuntime?: boolean;
@@ -177,6 +212,7 @@ export interface YamCompletionProof {
     rollbackHint: string[];
     runtimeBackendEvidence: string[];
     mediaProof: string[];
+    designCompletion: string[];
     cleanup: unknown;
     changed: string[];
     skipped: string[];
@@ -190,10 +226,11 @@ export interface YamCompletionProof {
 }
 export declare function buildUeyeVisualProvenance(input?: Partial<UeyeVisualProvenance>): UeyeVisualProvenance;
 export declare function buildUeyeSurfaceContext(input?: Partial<UeyeSurfaceContext>): UeyeSurfaceContext;
+export declare function buildUeyeDesignCompletionGate(input?: Partial<UeyeDesignCompletionGate> & Record<string, unknown>): UeyeDesignCompletionGate;
 export declare function buildRollbackHint(input?: Partial<RollbackHint>): RollbackHint;
 export declare function buildMissionPatchEnvelope(input?: Partial<MissionPatchEnvelope>): MissionPatchEnvelope;
 export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBackendEvidence>): RuntimeBackendEvidence;
-export declare function buildUeyeRunReport(input?: Partial<UeyeRunReport>): UeyeRunReport;
+export declare function buildUeyeRunReport(input?: UeyeRunReportInput): UeyeRunReport;
 export declare function buildMediaGenerationProof(input?: Partial<MediaGenerationProof>): MediaGenerationProof;
 export declare function isTruthStatus(value?: unknown): value is TruthStatus;
 export declare function weakestTruth(...statuses: unknown[]): TruthStatus;

package/dist/lib/trust-kernel.js

@@ -52,6 +52,93 @@ export function buildUeyeSurfaceContext(input = {}) {
         truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
     };
 }
+export function buildUeyeDesignCompletionGate(input = {}) {
+    const completionClaim = normalizeUeyeCompletionClaim(input.completion_claim);
+    const mode = String(input.mode || '').toLowerCase() === 'strict' || completionClaim === 'done' ? 'strict' : 'fast';
+    const designScore = numberOrNull(input.design_score);
+    const minDesignScore = numberOrNull(input.min_design_score) ?? 8;
+    const p0 = asList(input.p0);
+    const p1 = asList(input.p1);
+    const hasReference = Boolean(input.has_reference);
+    const hasImplementation = Boolean(input.has_implementation_screenshot);
+    const comparisonResult = String(input.comparison_result || 'not-verified');
+    const designQuality = String(input.design_quality || 'not-checked');
+    const blockedReason = String(input.blocked_reason || '');
+    const strictOrDone = mode === 'strict' || completionClaim === 'done';
+    const checks = [
+        designGateCheck('direction_lock', 'Design direction and target screen were locked before judging completion', Boolean(input.direction_locked) ? 'pass' : 'not_checked', strictOrDone, 'record the target screen and design direction before claiming done'),
+        designGateCheck('reference_read', 'Reference read proof exists when reference is used', !hasReference ? 'not_checked' : Boolean(input.reference_read) ? 'pass' : 'fail', hasReference && strictOrDone, 'record concrete reference observations before claiming reference-led work is done'),
+        designGateCheck('implementation_screenshot', 'Real implementation screenshot or screen evidence exists', hasImplementation ? 'pass' : 'fail', strictOrDone, 'capture or provide implementation screenshot before claiming done'),
+        designGateCheck('reference_comparison', 'Reference comparison is recorded when reference is used', !hasReference ? 'not_checked' : ['matched', 'similar', 'not-applicable'].includes(comparisonResult) ? 'pass' : 'fail', hasReference, 'compare against the reference or mark the difference as intentional before claiming done'),
+        designGateCheck('design_quality', 'Design quality result is pass', designQuality === 'pass' ? 'pass' : designQuality === 'needs-polish' ? 'warning' : 'fail', strictOrDone, 'resolve design quality issues or keep the result as needs-polish/partial'),
+        designGateCheck('p0_clear', 'No P0 visual blockers remain', p0.length ? 'fail' : 'pass', true, 'fix P0 blockers before any done claim'),
+        designGateCheck('p1_clear', 'No P1 major visual issues remain', p1.length ? 'fail' : 'pass', strictOrDone, 'fix or explicitly defer P1 issues before claiming done'),
+        designGateCheck('cta_affordance', 'Primary CTA and interaction affordances were checked', Boolean(input.cta_checked) ? 'pass' : 'not_checked', strictOrDone, 'check primary CTA clarity and interaction affordances before claiming done'),
+        designGateCheck('state_coverage', 'Primary UI states were checked', Boolean(input.states_checked) ? 'pass' : 'not_checked', strictOrDone, 'check default/loading/error/empty/disabled states or keep completion partial'),
+        designGateCheck('mobile_coverage', 'Mobile/responsive behavior was checked', Boolean(input.mobile_checked || input.responsive_checked) ? 'pass' : 'not_checked', strictOrDone, 'check mobile/responsive behavior before claiming done'),
+        designGateCheck('accessibility_visuals', 'Contrast/accessibility-relevant visuals were checked', Boolean(input.contrast_checked || input.accessibility_checked) ? 'pass' : 'not_checked', strictOrDone, 'check contrast/accessibility-relevant visuals before claiming done')
+    ];
+    if (designScore !== null || strictOrDone) {
+        checks.push(designGateCheck('design_score', `Design score is at least ${minDesignScore}`, designScore !== null && designScore >= minDesignScore ? 'pass' : designScore === null ? 'not_checked' : 'fail', false, `record --design-score ${minDesignScore} or higher when using score-based completion`));
+    }
+    const blockers = [
+        ...p0.map((item) => `P0: ${item}`),
+        ...(blockedReason ? [blockedReason] : []),
+        ...checks
+            .filter((check) => check.required && check.status !== 'pass')
+            .map((check) => `${check.id}: ${check.next_action}`)
+    ];
+    const warnings = [
+        ...p1.map((item) => `P1: ${item}`),
+        ...checks
+            .filter((check) => !check.required && ['fail', 'warning', 'not_checked'].includes(check.status))
+            .map((check) => `${check.id}: ${check.next_action}`)
+    ];
+    const ready = completionClaim === 'done' && blockers.length === 0;
+    const truth = blockers.some((item) => item.startsWith('P0:')) || blockedReason ? 'blocked'
+        : ready ? 'verified'
+            : strictOrDone ? 'partial'
+                : hasImplementation ? 'partial'
+                    : 'assumed';
+    return {
+        schema: 'yam.ueye-design-completion-gate.v1',
+        mode,
+        completion_claim: completionClaim,
+        ready_to_claim_done: ready,
+        design_score: designScore,
+        min_design_score: minDesignScore,
+        checks,
+        p0,
+        p1,
+        warnings,
+        blockers,
+        next_action: blockers[0] || (ready ? 'done claim is supported by the recorded design gate' : warnings[0] || 'keep the Ueye result as draft or needs-polish until a done claim is needed'),
+        truth_status: truth
+    };
+}
+function normalizeUeyeCompletionClaim(value = '') {
+    const text = String(value || '').toLowerCase();
+    if (text === 'done' || text === 'complete' || text === 'completed')
+        return 'done';
+    if (text === 'needs-polish' || text === 'needs_polish' || text === 'polish')
+        return 'needs-polish';
+    return 'draft';
+}
+function designGateCheck(id, label, status, required, nextAction) {
+    return {
+        id,
+        label,
+        status,
+        required,
+        next_action: nextAction
+    };
+}
+function numberOrNull(value = null) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
 export function buildRollbackHint(input = {}) {
     return {
         schema: 'yam.rollback-hint.v1',
@@ -78,6 +165,13 @@ export function buildMissionPatchEnvelope(input = {}) {
 export function buildRuntimeBackendEvidence(input = {}) {
     const backend = normalizeRuntimeBackend(input.backend);
     const claim = normalizeRuntimeClaim(input.claim);
+    const cleanupObserved = Boolean(input.cleanup_observed);
+    const leftRunningIntentionally = Boolean(input.left_running_intentionally);
+    const exitCode = numberOrNull(input.exit_code);
+    const pid = numberOrNull(input.pid);
+    const port = numberOrNull(input.port);
+    const stoppedAt = String(input.stopped_at || '');
+    const cleanupMethod = String(input.cleanup_method || '');
     return {
         schema: 'yam.runtime-backend-evidence.v1',
         backend,
@@ -85,8 +179,24 @@ export function buildRuntimeBackendEvidence(input = {}) {
         evidence_id: String(input.evidence_id || ''),
         command: String(input.command || ''),
         cleanup_checked: Boolean(input.cleanup_checked),
+        started_at: String(input.started_at || ''),
+        stopped_at: stoppedAt,
+        exit_code: exitCode,
+        pid,
+        port,
+        cleanup_method: cleanupMethod,
+        cleanup_observed: cleanupObserved,
+        left_running_intentionally: leftRunningIntentionally,
         note: String(input.note || ''),
-        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : runtimeBackendTruth(backend, claim, Boolean(input.cleanup_checked))
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : runtimeBackendTruth(backend, claim, {
+            cleanupChecked: Boolean(input.cleanup_checked),
+            cleanupObserved,
+            leftRunningIntentionally,
+            stoppedAt,
+            exitCode,
+            pid,
+            cleanupMethod
+        })
     };
 }
 export function buildUeyeRunReport(input = {}) {
@@ -104,19 +214,30 @@ export function buildUeyeRunReport(input = {}) {
             : comparisonResult === 'matched' && hasImplementation ? 'verified'
                 : hasImplementation ? 'partial'
                     : 'partial';
+    const gate = buildUeyeDesignCompletionGate({
+        ...input.design_completion_gate,
+        has_reference: references.length > 0,
+        has_implementation_screenshot: hasImplementation,
+        comparison_result: comparisonResult,
+        design_quality: String(input.design_quality || 'not-checked'),
+        blocked_reason: blockedReason
+    });
+    const shouldApplyDesignGate = gate.mode === 'strict' || gate.completion_claim === 'done' || gate.blockers.length > 0;
+    const finalTruth = shouldApplyDesignGate ? weakestTruth(derivedTruth, gate.truth_status) : derivedTruth;
     return {
         schema: 'yam.ueye-run-report.v1',
         reference_sources: references,
         implementation_sources: implementations,
         surface_context: buildUeyeSurfaceContext({
             ...input.surface_context,
-            truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : derivedTruth
+            truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : finalTruth
         }),
+        design_completion_gate: gate,
         comparison_result: comparisonResult,
         design_quality: String(input.design_quality || 'not-checked'),
         blocked_reason: blockedReason,
-        next_action: String(input.next_action || (derivedTruth === 'verified' ? 'no action required' : 'capture or provide implementation screenshot before claiming verified visual status')),
-        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : derivedTruth
+        next_action: String(input.next_action || gate.blockers[0] || (finalTruth === 'verified' ? 'no action required' : 'capture or provide implementation screenshot before claiming verified visual status')),
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : finalTruth
     };
 }
 export function buildMediaGenerationProof(input = {}) {
@@ -229,6 +350,9 @@ export function classifyEvidenceTruth(summary = {}, options = {}) {
     for (const media of asList(summary.mediaProof)) {
         rows.push(evidenceRow('evidence', media, readStructuredTruth(media, 'partial')));
     }
+    for (const designCompletion of asList(summary.designCompletion)) {
+        rows.push(evidenceRow('visual', designCompletion, readStructuredTruth(designCompletion, 'partial')));
+    }
     for (const runtime of asList(summary.runtime)) {
         rows.push(evidenceRow('runtime', runtime, classifyRuntimeEvidence(runtime, options)));
     }
@@ -262,6 +386,15 @@ export function applyProofTruthCaps(summary = {}, options = {}) {
         cappedTruth = weakestTruth(cappedTruth, 'partial');
         unverified.push('real_visual_evidence_missing');
     }
+    const designCompletionTruth = designCompletionCap(summary.designCompletion);
+    if (designCompletionTruth) {
+        cappedTruth = weakestTruth(cappedTruth, designCompletionTruth);
+        if (designCompletionTruth === 'blocked')
+            blockers.push('ueye_design_completion_blocked');
+        if (!['verified', 'proven'].includes(designCompletionTruth)) {
+            unverified.push('ueye_design_completion_not_verified');
+        }
+    }
     if (requested !== cappedTruth) {
         caps.push(`requested ${requested} capped to ${cappedTruth} by evidence`);
     }
@@ -319,6 +452,7 @@ export function buildYamCompletionProof(summary = {}, options = {}) {
         rollbackHint: asList(summary.rollbackHint),
         runtimeBackendEvidence: asList(summary.runtimeBackendEvidence),
         mediaProof: asList(summary.mediaProof),
+        designCompletion: asList(summary.designCompletion),
         cleanup: summary.cleanup || '',
         changed: asList(summary.changed),
         skipped: asList(summary.skipped),
@@ -394,6 +528,12 @@ function readStructuredTruth(value = '', fallback = 'partial') {
         return fallback;
     }
 }
+function designCompletionCap(value = '') {
+    const items = asList(value);
+    if (!items.length)
+        return null;
+    return items.reduce((weakest, item) => weakestTruth(weakest, readStructuredTruth(item, 'partial')), 'proven');
+}
 function strongestSupportedTruth(rows = []) {
     if (rows.some((row) => row.truth === 'blocked'))
         return 'blocked';
@@ -487,15 +627,21 @@ function normalizeRuntimeClaim(value = '') {
         return 'blocked';
     return 'unknown';
 }
-function runtimeBackendTruth(backend, claim, cleanupChecked = false) {
+function runtimeBackendTruth(backend, claim, details = {}) {
     if (claim === 'blocked')
         return 'blocked';
     if (backend === 'none' || claim === 'not_started')
         return 'skipped';
     if (backend === 'unknown' || claim === 'unknown')
         return 'partial';
-    if (claim === 'cleanup_verified' || cleanupChecked)
-        return 'proven';
+    const hasClosureEvidence = Boolean(details.stoppedAt || details.exitCode !== null || details.cleanupMethod);
+    if (claim === 'cleanup_verified' || details.cleanupChecked) {
+        if (details.cleanupObserved && hasClosureEvidence)
+            return 'proven';
+        if (details.leftRunningIntentionally && (details.pid !== null || details.cleanupMethod))
+            return 'partial';
+        return 'real_required_missing';
+    }
     if (claim === 'observed' || claim === 'stopped' || claim === 'started')
         return 'verified';
     return 'partial';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -16,7 +16,7 @@
     "node": ">=18"
   },
   "bin": {
-    "yam": "./dist/bin/yam.js"
+    "yam": "dist/bin/yam.js"
   },
   "types": "dist/lib/trust-kernel.d.ts",
   "exports": {

package/references/cleanup-scan.md

@@ -0,0 +1,33 @@
+# Cleanup Scan
+
+`yam cleanup scan` is advisory only.
+
+It helps identify confusing local surfaces before a route starts drifting:
+
+- active hooks
+- project-local skill folders
+- competing instruction files
+- old skill/package traces
+- stale proof or runtime artifacts
+
+It must not delete, rename, disable, uninstall, or rewrite anything.
+
+Use it when:
+
+- routes feel unexpectedly heavy
+- old instructions keep influencing a project
+- install state is unclear
+- proof artifacts may be mistaken for current evidence
+
+Safe cleanup requires explicit user approval and a backup-minded next action.
+
+Every finding should include:
+
+- `risk_level`
+- `surface`
+- `why_it_matters`
+- `safe_next_action`
+- `destructive: false`
+- `truth_status`
+
+If cleanup is not needed, say so plainly and keep moving.

package/references/final-report.md

@@ -7,9 +7,14 @@ Every `yam` route should end with a compact handoff that helps the next run avoi
 Include these when they are useful and keep them short:
 
 - What changed or what was found.
+- Change insight for non-specialists: what the touched code does, how it changed, and why it matters.
 - What verification ran.
 - What was not checked.
 - Truth status, when verification or runtime claims matter.
+- Security notes when auth, payment, DB, secrets, permissions, deployment, dependency, or public-release surfaces are relevant.
+- Source boundaries when reference material shaped the decision.
+- Context pressure or cleanup findings when they could affect the next run.
+- Publish blocker evidence when npm/release work fails.
 - Structured diagnostic next action, when a check found a concrete next step.
 - Remaining tasks.
 - Fix-first items before planned tasks.
@@ -57,7 +62,7 @@ For `$ueye`, include source evidence, states/viewports checked, and P0-P3 issues
 
 For `$deep` and `$mission`, include evidence, remaining risks, remaining tasks, and fix-first items.
 
-Do not pad the final answer when there are no meaningful remaining tasks or fix-first items.
+Do not pad the final answer when there are no meaningful remaining tasks or fix-first items, but say so plainly when the user expects a handoff.
 
 When budget drift matters, include or run `yam measure <route>` with approximate files, commands, report lines, and seconds.
 

package/references/risk-escalation.md

@@ -2,12 +2,16 @@
 
 Escalate by recommendation, not silent mode switching.
 
+Security is the first lens. Before convenience, speed, or visual polish, look for sensitive surfaces a non-specialist may miss.
+
 Recommend `$deep` when work touches:
 
 - DB schema or data mutation.
 - Supabase destructive commands, migrations, production writes, RLS, or policy changes.
 - Auth, payment, billing, permissions.
 - Security-sensitive code.
+- Secret handling, environment variables, tokens, and credentials.
+- Dependency, package, install, release, or supply-chain changes.
 - Deployment or release configuration.
 - Broad refactor or many files.
 - Failing verification.

package/references/runtime-orchestration.md

@@ -44,6 +44,7 @@ Runtime proof should include:
 - PID, port, URL, session, pane, screenshot id, started_at, stopped_at, and exit_code when available.
 - Checks before and after.
 - Cleanup result.
+- `cleanup_method`, `cleanup_observed`, and `left_running_intentionally` when relevant.
 - Truth status: proven, verified, partial, fixture_only, fixture_instrumented_real, integration_optional, real_required_missing, skipped, blocked, assumed.
 
 ## Runtime Evidence Mini
@@ -58,6 +59,9 @@ Minimum fields:
 - `command` or check name
 - `target`: URL, port, process, or service
 - `pid`, `port`, `url`, `exit_code`, `screenshot_id`, `started_at`, `stopped_at`
+- `cleanup_method`
+- `cleanup_observed`
+- `left_running_intentionally`
 - `process`: session, pane, or `unknown` when process detail is unavailable
 - `observation`: before and after notes
 - `cleanup`: status and evidence
@@ -68,6 +72,9 @@ Truth caps:
 
 - Missing process/target evidence cannot support `proven`.
 - Missing cleanup evidence cannot support a cleanup-complete claim.
+- `cleanup_checked` alone is not enough for `proven`.
+- `cleanup_observed` plus exit, closure, or cleanup method evidence can support `proven`.
+- `left_running_intentionally` is acceptable only when explicitly recorded and reported.
 - Optional runtime checks may be `integration_optional`; required but unavailable runtime checks should be `real_required_missing`, `blocked`, or `partial`.
 
 ## Cleanup Rule

package/references/scout.md

@@ -1,6 +1,6 @@
 # Scout
 
-`scout` is practical investigation and judgment, not academic research.
+`scout` is broad practical investigation and judgment. It gives the user wider sight before implementation, then compresses the result into a decision.
 
 Use for:
 
@@ -12,15 +12,19 @@ Use for:
 - Third-party judgment before implementation.
 - Objective and subjective evaluation together.
 - Macro, realistic, and future-facing direction checks.
+- Security-centered direction checks.
+- Reference scans that find useful patterns to rework into yam style.
 
 Default behavior:
 
-- Define the question narrowly.
+- Define the decision clearly.
 - Prefer official or primary sources.
-- Gather 3-7 high-signal references by default.
+- Gather 3-7 high-signal references for focused scouting, or more when the user asks for a wide scan.
 - Use current docs proof only for modern SDK/API/cloud-service behavior where stale knowledge is plausible.
 - Summarize options and recommendation.
 - Separate fact, inference, opinion, and recommendation.
+- Keep source boundaries clear: cite what was read and do not present reference-derived judgment as direct verification.
+- Put security before convenience: auth, payment, DB, secrets, permissions, deployment, supply chain, and public release get called out early.
 - Do not change code unless the user asks.
 
 Judgment format:
@@ -30,6 +34,8 @@ Judgment format:
 - Macro view: category direction and broad movement.
 - Realistic view: what can be done soon with the current project and skill level.
 - Future view: second-order effects, durability, and what may age well or badly.
+- Security view: sensitive surfaces, safer defaults, failure modes, and what a non-specialist might miss.
+- Rework view: what ideas should be adapted into yam style and what should be rejected.
 
 Escalate:
 

package/references/tool-trust-layer.md

@@ -2,8 +2,8 @@
 
 `yam` should grow a proof-first trust layer, but not a proof-first cage.
 
-The goal is to help a beginner start small and then move toward professional implementation with evidence, without making every step feel like a release gate.
-This is not a lightweight-only direction. `yam-lite` is light; `yam` is progressive.
+The goal is to help a non-specialist start with momentum and then move toward professional implementation with evidence, wider judgment, security-first guidance, and useful change insight.
+This is not a lightweight-only direction. `yam-lite` is light; `yam` is progressive and is allowed to become deeper as the user's knowledge and project risk grow.
 
 ## Depth Ladder
 
@@ -13,6 +13,9 @@ Every route carries a basic contract:
 - use context packs or memory before broad re-reading
 - verify only what was actually checked
 - report remaining tasks and fix-first issues when useful
+- explain what changed in plain language when code or behavior changes
+- treat security as the first project lens
+- preserve source boundaries when outside references shaped the judgment
 
 Then depth increases by route:
 
@@ -70,6 +73,7 @@ On demand:
 - tmux/process cleanup truth.
 - Source-intelligence proof for current docs.
 - Destructive DB/Supabase command detection and production-write caution.
+- Security-first risk surfacing for non-specialists.
 - Fake-vs-real and runtime truth matrix checks, reduced to local route-scoped helpers.
 - Feature/release inventory as an optional doctor, not a default gate.
 
@@ -86,6 +90,14 @@ On demand:
 - Compact design direction.
 - P0 visual gates for design-heavy work.
 
+## Change Insight Inputs
+
+- What the touched code or artifact is responsible for.
+- What changed in behavior, contract, UI, or safety posture.
+- Why the change matters to the product or user.
+- What remains uncertain or unverified.
+- What should be fixed first before the next planned task.
+
 ## Reject
 
 - Always-on Team route.

package/references/trust-kernel.md

@@ -11,6 +11,7 @@ This is the small trust kernel that keeps `yam` honest without turning every tas
 - fake versus real evidence distinction
 - runtime truth matrix idea
 - visual evidence caps
+- Ueye design completion gate
 - DB/Supabase destructive-signal detection
 
 ## Rejected
@@ -38,6 +39,7 @@ The module provides:
 - fake/real policy
 - runtime truth matrix
 - completion proof object creation
+- Ueye design completion gate creation
 
 ## Policy
 
@@ -51,5 +53,6 @@ For example:
 - Mock/fixture evidence cannot become real runtime `proven`.
 - Required runtime evidence that is missing becomes `real_required_missing`.
 - Cleanup claims require cleanup evidence.
+- Ueye `done` claims require a passing design completion gate or stay capped at `partial` or `blocked`.
 
 This keeps the trust layer progressive and route-scoped.

package/references/truth-matrix.md

@@ -38,8 +38,12 @@ Never say `verified` when the correct status is `partial`, `skipped`, `blocked`,
 
 Never say `proven` for runtime work unless the runtime evidence exists.
 
+Never say cleanup is `proven` from a cleanup intention alone. Cleanup needs observed exit, closure, or an explicit intentional-left-running record.
+
 Never say full visual `verified` when the only evidence is a reference image, generated image, code reading, or text-only critique.
 
+Ueye preflight is `partial` by design. It can identify design risks before work starts, but it cannot prove visual quality without implementation screenshot/comparison evidence.
+
 For ordinary routes, prefer `verified`, `partial`, `skipped`, `blocked`, or `assumed`.
 For `$deep` runtime verification and `$mission`, use the more precise runtime statuses when they prevent overclaiming.
 

package/references/ueye-proof.md

@@ -26,7 +26,7 @@ Ueye is one route. It should not split into separate lite/deep skills. Use these
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 - `capture` uses a project-local capture backend when present, then reports `blocked` instead of installing dependencies or pretending a screenshot exists.
@@ -190,6 +190,55 @@ Dimensions:
 Report findings as P0-P3. Keep P2/P3 short unless the user requested a full polish pass.
 For each relevant design dimension, use `pass`, `needs-polish`, or `fails`.
 
+### Design Completion Gate
+
+Purpose: prevent Ueye from declaring visual work complete before the design evidence supports that claim.
+
+Use when the output says the UI is done, complete, polished, final, or verified.
+
+Minimum fields:
+
+- `completion_claim`: draft / needs-polish / done
+- `mode`: fast / strict
+- `ready_to_claim_done`
+- `design_score`, when used
+- `min_design_score`
+- `checks`
+- `p0`
+- `p1`
+- `warnings`
+- `blockers`
+- `next_action`
+- `truth_status`
+
+Required for a done claim when relevant:
+
+- direction locked
+- reference read proof for reference-led work
+- implementation screenshot or source-screen evidence
+- reference comparison for reference-led work
+- design quality pass
+- no P0 blockers
+- no unresolved P1 issues unless explicitly deferred
+- CTA affordance checked
+- primary states checked
+- mobile/responsive behavior checked
+- contrast/accessibility-relevant visuals checked
+
+Example:
+
+```bash
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --json
+```
+
+Attach to proof when needed:
+
+```bash
+yam proof --route ueye --truth verified --visual "implementation screenshot evidence recorded" --design-completion '{"completion_claim":"done","has_implementation_screenshot":true,"design_quality":"pass","states_checked":true,"mobile_checked":true,"contrast_checked":true,"cta_checked":true,"direction_locked":true,"truth_status":"verified"}'
+```
+
+The design completion gate is a completion judgment. Keep actual source-screen proof in visual evidence, visual provenance, or a Ueye run report. Do not use self-reported gate fields to pretend a missing screenshot was captured.
+
 ### Review Continuity And Comparison Report
 
 Use this when a Ueye task continues a previous visual review, rechecks a fix, or compares two review runs.
@@ -222,3 +271,4 @@ Do not claim continuity from memory alone. Link it to a previous report, screens
 - Reference-only evidence can support direction, not implementation proof.
 - Generated-only evidence can support ideation or annotation, not implemented-screen verification.
 - Missing screenshots, unavailable browser, or text-only review should cap the result at `partial`, `blocked`, or `assumed`.
+- A done claim with a missing or failing design completion gate should cap the result at `partial` or `blocked`.