yam-flow 0.1.0

package/src/lib/trust-kernel.ts

@@ -0,0 +1,398 @@
+export const TRUTH_STATUSES = Object.freeze([
+  'verified',
+  'proven',
+  'partial',
+  'fixture_only',
+  'fixture_instrumented_real',
+  'integration_optional',
+  'real_required_missing',
+  'skipped',
+  'blocked',
+  'assumed'
+] as const);
+
+export type TruthStatus = (typeof TRUTH_STATUSES)[number];
+export type SafetyLevel = 'danger' | 'warning';
+export type EvidenceKind = 'command' | 'evidence' | 'visual' | 'runtime' | 'skipped' | 'blocked' | 'assumption' | 'cleanup' | 'none';
+export type RuntimeSubsystem = 'real_runtime' | 'tmux_physical' | 'process_cleanup' | 'browser_visual' | 'db_safety';
+
+export interface SafetyHit {
+  level: SafetyLevel;
+  reason: string;
+}
+
+export interface DbSafetyScanResult {
+  hits: SafetyHit[];
+  recommendation: '$deep' | '$quick or current route';
+  truth: TruthStatus;
+}
+
+export interface EvidenceRow {
+  kind: EvidenceKind;
+  value: string;
+  truth: TruthStatus;
+}
+
+export interface RuntimeTruthRow {
+  subsystem: RuntimeSubsystem;
+  proof_level: TruthStatus;
+  required: boolean;
+  next_action: string;
+}
+
+export interface RuntimeTruthMatrix {
+  schema: 'yam.runtime-truth-matrix.v1';
+  ok: boolean;
+  rows: RuntimeTruthRow[];
+  blockers: string[];
+}
+
+export interface FakeRealPolicyResult {
+  schema: 'yam.fake-real-policy.v1';
+  ok: boolean;
+  proof_level: TruthStatus;
+  fake_claims: string[];
+  real_claims: string[];
+  blockers: string[];
+}
+
+export interface ProofSummary {
+  route?: unknown;
+  goal?: unknown;
+  truth?: unknown;
+  source?: unknown;
+  commands?: unknown;
+  evidence?: unknown;
+  visual?: unknown;
+  runtime?: unknown;
+  cleanup?: unknown;
+  changed?: unknown;
+  skipped?: unknown;
+  blocked?: unknown;
+  assumptions?: unknown;
+  unverified?: unknown;
+}
+
+export interface ProofOptions {
+  requireRealRuntime?: boolean;
+  requireVisual?: boolean;
+  requireTmux?: boolean;
+}
+
+export interface ProofTruthCaps {
+  truth: TruthStatus;
+  requestedTruth: TruthStatus;
+  evidenceRows: EvidenceRow[];
+  caps: string[];
+  blockers: string[];
+  unverified: string[];
+  fakeReal: FakeRealPolicyResult;
+}
+
+export interface YamCompletionProof {
+  schema: 'yam.completion-proof.v1';
+  generatedAt: string;
+  route: unknown;
+  goal: unknown;
+  truth: TruthStatus;
+  requestedTruth: TruthStatus;
+  source: unknown;
+  commands: string[];
+  evidence: string[];
+  visual: string[];
+  runtime: string[];
+  cleanup: unknown;
+  changed: string[];
+  skipped: string[];
+  blocked: string[];
+  assumptions: string[];
+  unverified: string[];
+  truthCaps: string[];
+  evidenceRows: EvidenceRow[];
+  fakeReal: FakeRealPolicyResult;
+  runtimeTruth: RuntimeTruthMatrix;
+}
+
+const TRUTH_RANK: Readonly<Record<TruthStatus, number>> = Object.freeze({
+  blocked: 0,
+  real_required_missing: 0,
+  skipped: 1,
+  assumed: 1,
+  fixture_only: 2,
+  integration_optional: 2,
+  fixture_instrumented_real: 3,
+  partial: 3,
+  verified: 4,
+  proven: 5
+});
+
+export function isTruthStatus(value: unknown = ''): value is TruthStatus {
+  return (TRUTH_STATUSES as readonly string[]).includes(String(value || ''));
+}
+
+export function weakestTruth(...statuses: unknown[]): TruthStatus {
+  const valid = statuses.filter(isTruthStatus);
+  if (!valid.length) return 'assumed';
+  return valid.reduce((weakest, status) => {
+    return TRUTH_RANK[status] < TRUTH_RANK[weakest] ? status : weakest;
+  }, valid[0]);
+}
+
+export function detectDbSafetyText(text: unknown = ''): DbSafetyScanResult {
+  const value = String(text || '');
+  const hits: SafetyHit[] = [];
+  const checks: Array<[SafetyLevel, RegExp, string]> = [
+    ['danger', /\bdrop\s+(table|schema|database|view|index)\b/i, 'DROP statement can destroy database objects'],
+    ['danger', /\btruncate\s+(table\s+)?[a-z0-9_".]+/i, 'TRUNCATE statement can destroy table data'],
+    ['danger', /\bdelete\s+from\s+[a-z0-9_".]+/i, 'DELETE FROM can destroy row data'],
+    ['danger', /\bupdate\s+[a-z0-9_".]+\s+set\b/i, 'UPDATE can mutate row data'],
+    ['warning', /\balter\s+table\s+[a-z0-9_".]+/i, 'ALTER TABLE can change schema or lock production data'],
+    ['danger', /\bsupabase\s+db\s+(reset|push)\b/i, 'supabase db reset/push can mutate database state'],
+    ['warning', /\bsupabase\s+(migration|migrations|db\s+diff|db\s+pull)\b/i, 'Supabase migration/db command needs explicit environment awareness'],
+    ['danger', /\b(prisma\s+migrate\s+(deploy|reset|dev)|drizzle-kit\s+(push|drop|migrate)|knex\s+migrate|sequelize\s+db:migrate)\b/i, 'ORM migration command can mutate schema/data'],
+    ['danger', /\bpsql\b[\s\S]{0,160}\b(drop|truncate|delete\s+from|update\s+[a-z0-9_".]+\s+set|alter\s+table)\b/i, 'psql command contains destructive SQL'],
+    ['warning', /\b(create\s+policy|alter\s+policy|drop\s+policy|grant\s+|revoke\s+)/i, 'RLS/policy/permission change affects data access safety']
+  ];
+  for (const [level, pattern, reason] of checks) {
+    if (pattern.test(value)) hits.push({ level, reason });
+  }
+  const productionSignal = /\b(prod|production|live|remote|linked|service[_-]?role|database_url|--db-url|--linked|--remote|--project-ref)\b/i.test(value);
+  if (productionSignal) hits.push({ level: 'warning', reason: 'production/remote credential or environment signal detected' });
+  const unique: SafetyHit[] = [];
+  const seen = new Set<string>();
+  for (const hit of hits) {
+    const key = `${hit.level}:${hit.reason}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(hit);
+  }
+  return {
+    hits: unique,
+    recommendation: unique.length ? '$deep' : '$quick or current route',
+    truth: 'assumed'
+  };
+}
+
+export function classifyEvidenceTruth(summary: ProofSummary = {}, options: ProofOptions = {}): EvidenceRow[] {
+  const rows: EvidenceRow[] = [];
+  for (const command of asList(summary.commands)) {
+    rows.push(evidenceRow('command', command, commandPassed(command) ? 'verified' : 'partial'));
+  }
+  for (const evidence of asList(summary.evidence)) {
+    rows.push(evidenceRow('evidence', evidence, classifyTextEvidence(evidence)));
+  }
+  for (const visual of asList(summary.visual)) {
+    rows.push(evidenceRow('visual', visual, classifyVisualEvidence(visual)));
+  }
+  for (const runtime of asList(summary.runtime)) {
+    rows.push(evidenceRow('runtime', runtime, classifyRuntimeEvidence(runtime, options)));
+  }
+  for (const skipped of asList(summary.skipped)) rows.push(evidenceRow('skipped', skipped, 'skipped'));
+  for (const blocked of asList(summary.blocked)) rows.push(evidenceRow('blocked', blocked, 'blocked'));
+  for (const assumption of asList(summary.assumptions)) rows.push(evidenceRow('assumption', assumption, 'assumed'));
+  if (summary.cleanup) rows.push(evidenceRow('cleanup', summary.cleanup, classifyCleanupEvidence(summary.cleanup)));
+  if (!rows.length) rows.push(evidenceRow('none', 'no evidence supplied', 'assumed'));
+  return rows;
+}
+
+export function applyProofTruthCaps(summary: ProofSummary = {}, options: ProofOptions = {}): ProofTruthCaps {
+  const evidenceRows = classifyEvidenceTruth(summary, options);
+  const blockers: string[] = [];
+  const unverified: string[] = [];
+  const caps: string[] = [];
+  const requested = isTruthStatus(summary.truth) ? summary.truth : 'assumed';
+  const evidenceCap = strongestSupportedTruth(evidenceRows);
+  let cappedTruth = weakestTruth(requested, evidenceCap);
+
+  if (asList(summary.blocked).length) cappedTruth = 'blocked';
+  if (options.requireRealRuntime && !hasRuntimeProof(evidenceRows)) {
+    cappedTruth = 'real_required_missing';
+    blockers.push('real_runtime_required_missing');
+  }
+  if (options.requireVisual && !hasRealVisualProof(evidenceRows)) {
+    cappedTruth = weakestTruth(cappedTruth, 'partial');
+    unverified.push('real_visual_evidence_missing');
+  }
+  if (requested !== cappedTruth) {
+    caps.push(`requested ${requested} capped to ${cappedTruth} by evidence`);
+  }
+  const fakeReal = evaluateFakeRealPolicy({ summary, evidenceRows, options });
+  if (fakeReal.blockers.length) {
+    cappedTruth = weakestTruth(cappedTruth, fakeReal.proof_level);
+    blockers.push(...fakeReal.blockers);
+  }
+  return {
+    truth: cappedTruth,
+    requestedTruth: requested,
+    evidenceRows,
+    caps,
+    blockers: uniqueStrings(blockers),
+    unverified: uniqueStrings(unverified),
+    fakeReal
+  };
+}
+
+export function buildRuntimeTruthMatrix(summary: ProofSummary = {}, options: ProofOptions = {}): RuntimeTruthMatrix {
+  const evidenceRows = classifyEvidenceTruth(summary, options);
+  const rows = [
+    runtimeRow('real_runtime', hasRuntimeProof(evidenceRows) ? 'proven' : options.requireRealRuntime ? 'real_required_missing' : 'integration_optional', options.requireRealRuntime),
+    runtimeRow('tmux_physical', hasText(asList(summary.runtime), /tmux/i) ? runtimeLevelFor(evidenceRows, /tmux/i, options.requireTmux) : options.requireTmux ? 'real_required_missing' : 'integration_optional', options.requireTmux),
+    runtimeRow('process_cleanup', summary.cleanup ? classifyCleanupEvidence(summary.cleanup) : 'integration_optional', false),
+    runtimeRow('browser_visual', hasRealVisualProof(evidenceRows) ? 'verified' : options.requireVisual ? 'real_required_missing' : 'integration_optional', options.requireVisual),
+    runtimeRow('db_safety', asList(summary.evidence).some((item) => /db[_ -]?safety|supabase|database/i.test(String(item))) ? 'partial' : 'integration_optional', false)
+  ];
+  const blockers = rows
+    .filter((row) => row.required && ['blocked', 'real_required_missing', 'integration_optional'].includes(row.proof_level))
+    .map((row) => `${row.subsystem}_required_missing`);
+  return {
+    schema: 'yam.runtime-truth-matrix.v1',
+    ok: blockers.length === 0,
+    rows,
+    blockers
+  };
+}
+
+export function buildYamCompletionProof(summary: ProofSummary = {}, options: ProofOptions = {}): YamCompletionProof {
+  const capped = applyProofTruthCaps(summary, options);
+  const runtimeTruth = buildRuntimeTruthMatrix(summary, options);
+  return {
+    schema: 'yam.completion-proof.v1',
+    generatedAt: new Date().toISOString(),
+    route: summary.route || 'unspecified',
+    goal: summary.goal || '',
+    truth: capped.truth,
+    requestedTruth: capped.requestedTruth,
+    source: summary.source || '',
+    commands: asList(summary.commands),
+    evidence: asList(summary.evidence),
+    visual: asList(summary.visual),
+    runtime: asList(summary.runtime),
+    cleanup: summary.cleanup || '',
+    changed: asList(summary.changed),
+    skipped: asList(summary.skipped),
+    blocked: uniqueStrings([...asList(summary.blocked), ...capped.blockers]),
+    assumptions: asList(summary.assumptions),
+    unverified: uniqueStrings([...asList(summary.unverified), ...capped.unverified]),
+    truthCaps: capped.caps,
+    evidenceRows: capped.evidenceRows,
+    fakeReal: capped.fakeReal,
+    runtimeTruth
+  };
+}
+
+function classifyTextEvidence(value: unknown = ''): TruthStatus {
+  const text = String(value || '');
+  if (/mock|fixture|stub|fake/i.test(text)) return 'fixture_only';
+  if (/browser|screenshot|playwright|test.*pass|passed|build.*pass|typecheck.*pass|lint.*pass|verified/i.test(text)) return 'verified';
+  if (/blocked|failed|error/i.test(text)) return 'blocked';
+  if (/read|inspect|review|inferred|assumed|source/i.test(text)) return 'assumed';
+  return 'partial';
+}
+
+function classifyVisualEvidence(value: unknown = ''): TruthStatus {
+  const text = String(value || '');
+  if (/blocked|unavailable|could not|missing/i.test(text)) return 'blocked';
+  if (/reference[-_ ]?only|reference image|generated|annotation|mock|fixture|text[-_ ]?only|code[-_ ]?only/i.test(text)) return 'partial';
+  if (/browser|screenshot|screen capture|viewport|mobile|desktop|playwright|chrome/i.test(text)) return 'verified';
+  return 'partial';
+}
+
+function classifyRuntimeEvidence(value: unknown = '', options: ProofOptions = {}): TruthStatus {
+  const text = String(value || '');
+  if (/blocked|missing|unavailable|failed/i.test(text)) return options.requireRealRuntime ? 'real_required_missing' : 'blocked';
+  if (/fixture|mock|fake/i.test(text)) return 'fixture_only';
+  if (/tmux|pid|process|port|server|watcher|browser qa|exit verified|closed|cleanup verified/i.test(text)) return 'proven';
+  return 'partial';
+}
+
+function classifyCleanupEvidence(value: unknown = ''): TruthStatus {
+  const text = String(value || '');
+  if (/exit verified|closed|stopped|no runtime started|not started|intentionally left running/i.test(text)) return 'proven';
+  if (/not checked|unknown|assumed/i.test(text)) return 'assumed';
+  if (/blocked|failed|missing/i.test(text)) return 'blocked';
+  return 'partial';
+}
+
+function commandPassed(value: unknown = ''): boolean {
+  return /pass|passed|ok|success|exit\s*0|green/i.test(String(value || '')) && !/fail|failed|error|blocked/i.test(String(value || ''));
+}
+
+function strongestSupportedTruth(rows: EvidenceRow[] = []): TruthStatus {
+  if (rows.some((row) => row.truth === 'blocked')) return 'blocked';
+  if (rows.some((row) => row.truth === 'real_required_missing')) return 'real_required_missing';
+  if (rows.some((row) => row.truth === 'fixture_only')) return 'fixture_only';
+  if (rows.some((row) => row.truth === 'proven')) return 'proven';
+  if (rows.some((row) => row.truth === 'verified')) return 'verified';
+  if (rows.some((row) => row.truth === 'partial')) return 'partial';
+  if (rows.some((row) => row.truth === 'skipped')) return 'skipped';
+  return 'assumed';
+}
+
+interface FakeRealPolicyInput {
+  summary?: ProofSummary;
+  evidenceRows?: EvidenceRow[];
+  options?: ProofOptions;
+}
+
+function evaluateFakeRealPolicy({ summary = {}, evidenceRows = [], options = {} }: FakeRealPolicyInput): FakeRealPolicyResult {
+  const fakeClaims = evidenceRows.filter((row) => ['fixture_only'].includes(row.truth)).map((row) => `${row.kind}:${row.value}`);
+  const realClaims = evidenceRows.filter((row) => ['verified', 'proven'].includes(row.truth)).map((row) => `${row.kind}:${row.value}`);
+  const blockers: string[] = [];
+  if (options.requireRealRuntime && !hasRuntimeProof(evidenceRows)) blockers.push('real_runtime_required_missing');
+  if (summary.truth === 'verified' && fakeClaims.length && !realClaims.length) blockers.push('fixture_or_fake_evidence_cannot_verify_real_status');
+  const proofLevel: TruthStatus = blockers.length ? 'real_required_missing'
+    : fakeClaims.length && !realClaims.length ? 'fixture_only'
+      : realClaims.some((claim) => claim.startsWith('runtime:') || claim.startsWith('cleanup:')) ? 'proven'
+        : realClaims.length ? 'verified'
+          : 'assumed';
+  return {
+    schema: 'yam.fake-real-policy.v1',
+    ok: blockers.length === 0,
+    proof_level: proofLevel,
+    fake_claims: fakeClaims,
+    real_claims: realClaims,
+    blockers
+  };
+}
+
+function hasRuntimeProof(rows: EvidenceRow[] = []): boolean {
+  return rows.some((row) => (row.kind === 'runtime' || row.kind === 'cleanup') && ['proven', 'verified'].includes(row.truth));
+}
+
+function hasRealVisualProof(rows: EvidenceRow[] = []): boolean {
+  return rows.some((row) => row.kind === 'visual' && row.truth === 'verified');
+}
+
+function runtimeLevelFor(rows: EvidenceRow[] = [], pattern: RegExp, required = false): TruthStatus {
+  const matching = rows.filter((row) => row.kind === 'runtime' && pattern.test(row.value));
+  if (!matching.length) return required ? 'real_required_missing' : 'integration_optional';
+  return strongestSupportedTruth(matching);
+}
+
+function runtimeRow(subsystem: RuntimeSubsystem, proofLevel: TruthStatus, required?: boolean): RuntimeTruthRow {
+  return {
+    subsystem,
+    proof_level: proofLevel,
+    required: Boolean(required),
+    next_action: proofLevel === 'integration_optional' || proofLevel === 'real_required_missing'
+      ? `collect ${subsystem} evidence when the claim requires it`
+      : 'no action required'
+  };
+}
+
+function evidenceRow(kind: EvidenceKind, value: unknown, truth: TruthStatus): EvidenceRow {
+  return { kind, value: String(value || ''), truth };
+}
+
+function hasText(values: unknown[] = [], pattern: RegExp): boolean {
+  return values.some((value) => pattern.test(String(value || '')));
+}
+
+function asList(value?: unknown): string[] {
+  if (!value) return [];
+  return Array.isArray(value) ? value.filter(Boolean).map(String) : [String(value)].filter(Boolean);
+}
+
+function uniqueStrings(values: unknown[] = []): string[] {
+  return [...new Set(values.filter(Boolean).map(String))];
+}

package/templates/mission-plan.md

@@ -0,0 +1,46 @@
+# yam Mission Prompt
+
+```text
+$mission
+아래 구현 계획은 확정됐어.
+
+목표:
+-
+
+범위:
+-
+
+금지사항:
+-
+
+Acceptance criteria:
+-
+
+역할:
+- Implementer: 범위 안에서 구현
+- Reviewer: 코드/구조/리스크/방향성 검토
+- UX/browser verifier: 화면/상태/브라우저 흐름 확인
+- Doctor/scanner: stale context, 과검증/검증부족, false-completion risk, cleanup, 남은 fix-first 점검
+
+Subagent 판단:
+- 실제 subagent/team 사용 가능 여부:
+- meaningful split:
+- decision: used / downgraded_to_deep / unavailable_partial / blocked
+- 이유:
+- subagent가 불가능하거나 불필요하면 기본적으로 $deep으로 전환:
+
+검증:
+- 필요한 가장 작은 검증 명령을 우선 실행
+- 필요하면 tmux/dev server/browser QA/process cleanup proof 사용
+- 검증하지 못한 것은 skipped/blocked/assumed로 명확히 보고
+
+최종 보고:
+- 구현 요약
+- 역할별 교차 검증 결과
+- subagent decision
+- 실제 evidence
+- truth status
+- cleanup status
+- fix-first items
+- remaining tasks
+```

package/templates/runtime-proof.md

@@ -0,0 +1,54 @@
+# yam Deep/Mission Runtime Proof Summary
+
+## Goal
+
+-
+
+## Plan
+
+-
+
+## Processes
+
+- Command:
+- PID/session/pane:
+- Port:
+- Started:
+- Stopped:
+- Exit/closure verified:
+
+## tmux
+
+- Used: yes / no
+- Session:
+- Pane:
+- Before-drain observation:
+- After-drain observation:
+- Final observation:
+
+## Evidence
+
+- Before:
+- During:
+- After:
+
+## Verification
+
+- Command/check:
+- Result:
+- Truth status:
+
+## Cleanup
+
+- Cleanup performed:
+- Process exit verified:
+- tmux pane/session closed or intentionally left running:
+- Remaining process intentionally left running:
+
+## Blockers
+
+- None.
+
+## Final Truth Status
+
+- proven / verified / partial / fixture_only / fixture_instrumented_real / integration_optional / real_required_missing / skipped / blocked / assumed:

package/templates/tuning-log.md

@@ -0,0 +1,39 @@
+# yam Tuning Log
+
+Use this to tune route wording from real use.
+
+## Entry
+
+- Date:
+- Project:
+- Route:
+- Task:
+
+## What Happened
+
+- Over-read context:
+- Under-verified:
+- Report too long:
+- Direction mismatch:
+- Useful behavior:
+
+## Budget Measurement
+
+- Files read:
+- Commands run:
+- Report lines:
+- Seconds:
+- Budget result:
+
+## Fix To Harness
+
+- Skill to edit:
+- Proposed wording:
+- Keep/remove:
+
+## Compared Against
+
+- Strict proof:
+- Modular skills:
+- Minimal core:
+- yam decision:

package/templates/ueye-comparison.md

@@ -0,0 +1,78 @@
+# yam Ueye Reference Comparison
+
+## Input
+
+- Implementation screenshot/URL:
+- Reference screenshot/URL/path:
+- Product or screen:
+- Review bound:
+
+## Visual Evidence Inventory
+
+| Label | Type | Path/URL | Dimensions | sha256 | Viewport | State | Role |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| implementation |  |  | unknown | unknown |  |  | proof |
+| reference |  |  | unknown | unknown |  |  | reference direction |
+
+## Reference Read Proof
+
+- Layout:
+- Visual hierarchy:
+- Typography:
+- Color/contrast:
+- Component detail:
+- Interaction/motion:
+- Responsiveness:
+- Brand/mood fit:
+
+## Reference vs Implementation Matrix
+
+Use `matched`, `similar`, `different`, `not-verified`, or `not-applicable`.
+
+| Dimension | Status | Evidence | Suggested Fix |
+| --- | --- | --- | --- |
+| Layout and spacing | not-verified |  |  |
+| Visual hierarchy | not-verified |  |  |
+| Typography | not-verified |  |  |
+| Color and contrast | not-verified |  |  |
+| Component detail | not-verified |  |  |
+| Interaction and motion | not-verified |  |  |
+| Responsiveness | not-verified |  |  |
+| Accessibility visuals | not-verified |  |  |
+| Brand and mood fit | not-verified |  |  |
+
+## Design Quality Review
+
+Use `pass`, `needs-polish`, or `fails` for each relevant design dimension before listing actionable issues.
+
+| Dimension | Result | Evidence |
+| --- | --- | --- |
+| Visual hierarchy | needs-polish |  |
+| Layout/spacing | needs-polish |  |
+| Typography | needs-polish |  |
+| Color/contrast | needs-polish |  |
+| Component detail | needs-polish |  |
+| Interaction/motion | needs-polish |  |
+| Responsiveness | needs-polish |  |
+| Accessibility | needs-polish |  |
+| Brand/mood fit | needs-polish |  |
+
+### P0 Blockers
+
+- None.
+
+### P1 Major
+
+- None.
+
+### P2 Quality
+
+- None.
+
+### P3 Polish
+
+- None.
+
+## Truth Status
+
+- verified / partial / skipped / blocked / assumed: