yam-flow 0.1.6 → 0.1.7

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

@@ -113,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;
 }

package/dist/lib/trust-kernel.js

@@ -165,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,
@@ -172,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 = {}) {
@@ -604,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.6",
+  "version": "0.1.7",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

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/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/skills/scout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scout
-description: Lightweight investigation and judgment route. Use when the user invokes $scout or asks to find options, references, docs, tools, product direction, or third-party perspective before implementation.
+description: Broad investigation and judgment route. Use when the user invokes $scout or asks to find options, references, docs, tools, product direction, security implications, or third-party perspective before implementation.
 ---
 
 # yam Scout
@@ -15,21 +15,27 @@ Use for:
 - Third-party judgment before committing to a direction.
 - Objective and subjective evaluation together.
 - Macro, realistic, and future-facing judgment.
+- Broad reference scans when the user needs wider perspective.
+- Security-centered direction checks before implementation.
+- Finding patterns worth reworking into yam style.
 
 ## Principles
 
-- Scout, do not sprawl.
+- Scout broadly enough to see the field, then compress the judgment.
 - Token economy is part of quality.
 - Reuse `yam.project.md` before broad context reading when present.
 - Prefer official and primary sources.
+- Keep source boundaries clear: cite what was read, separate fact from inference, and do not blur reference material into yam claims.
 - Use current docs proof only when SDK/API/cloud-service freshness matters.
-- Keep the question narrow.
+- Keep the decision clear, but do not make the field of view artificially narrow when the user asks for a broad scan.
 - Do not change code unless the user asks.
 - Return a practical recommendation.
 - Separate fact, inference, opinion, and recommendation.
 - Treat "objective" as evidence plus constraints, not certainty theater.
 - Treat "subjective" as named taste, product instinct, and likely user perception.
-- Keep source count bounded by default; use `$deep` only when the user asks for heavy verification.
+- Security is the first lens: call out auth, payment, DB, secrets, permission, deployment, supply-chain, and public-release risks early.
+- Source count should match the decision: 3-7 high-signal sources for focused scouting, more when the user explicitly asks for wide research.
+- Use `$deep` when the user asks for heavy verification or when false confidence would be costly.
 
 ## Workflow
 
@@ -41,11 +47,12 @@ Use for:
    - product/technical direction memo
    - risk discovery
 3. Read `yam.project.md` first when project direction matters.
-4. Gather 3-7 high-signal sources by default.
+4. Gather enough high-signal sources to support the decision; keep source quality higher than source volume.
 5. Compare options by fit, risk, cost, implementation effort, and durability.
-6. Give both objective and subjective judgment when useful.
-7. Recommend a direction.
-8. State uncertainty and what would change the recommendation.
+6. Identify security and trust implications before convenience or aesthetics.
+7. Give both objective and subjective judgment when useful.
+8. Recommend a direction and which ideas are worth reworking into yam style.
+9. State uncertainty and what would change the recommendation.
 
 ## Output
 
@@ -57,9 +64,12 @@ Use concise sections:
 - Macro / realistic / future view when the decision benefits from it.
 - Alternatives.
 - Risks.
+- Security lens.
+- Ideas to rework into yam style.
 - Sources or local evidence.
+- Remaining tasks or useful next improvements.
 
-Use `references/token-economy.md`; default to 3-7 high-signal sources.
+Use `references/token-economy.md`; default to 3-7 high-signal sources unless the user asks for a broad research scan.
 Use `references/current-docs.md` for current SDK/API/cloud-service questions.
 Use `references/context-reuse.md`; do not rescout known decisions unless they may be stale.
 Use `references/markdown-management.md` before creating or updating project packs.