yam-flow 0.1.0

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

@@ -0,0 +1,99 @@
+export declare const TRUTH_STATUSES: readonly ["verified", "proven", "partial", "fixture_only", "fixture_instrumented_real", "integration_optional", "real_required_missing", "skipped", "blocked", "assumed"];
+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;
+}
+export declare function isTruthStatus(value?: unknown): value is TruthStatus;
+export declare function weakestTruth(...statuses: unknown[]): TruthStatus;
+export declare function detectDbSafetyText(text?: unknown): DbSafetyScanResult;
+export declare function classifyEvidenceTruth(summary?: ProofSummary, options?: ProofOptions): EvidenceRow[];
+export declare function applyProofTruthCaps(summary?: ProofSummary, options?: ProofOptions): ProofTruthCaps;
+export declare function buildRuntimeTruthMatrix(summary?: ProofSummary, options?: ProofOptions): RuntimeTruthMatrix;
+export declare function buildYamCompletionProof(summary?: ProofSummary, options?: ProofOptions): YamCompletionProof;

package/dist/lib/trust-kernel.js

@@ -0,0 +1,300 @@
+export const TRUTH_STATUSES = Object.freeze([
+    'verified',
+    'proven',
+    'partial',
+    'fixture_only',
+    'fixture_instrumented_real',
+    'integration_optional',
+    'real_required_missing',
+    'skipped',
+    'blocked',
+    'assumed'
+]);
+const TRUTH_RANK = 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 = '') {
+    return TRUTH_STATUSES.includes(String(value || ''));
+}
+export function weakestTruth(...statuses) {
+    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 = '') {
+    const value = String(text || '');
+    const hits = [];
+    const checks = [
+        ['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 = [];
+    const seen = new Set();
+    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 = {}, options = {}) {
+    const rows = [];
+    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 = {}, options = {}) {
+    const evidenceRows = classifyEvidenceTruth(summary, options);
+    const blockers = [];
+    const unverified = [];
+    const caps = [];
+    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 = {}, options = {}) {
+    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 = {}, options = {}) {
+    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 = '') {
+    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 = '') {
+    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 = '', options = {}) {
+    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 = '') {
+    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 = '') {
+    return /pass|passed|ok|success|exit\s*0|green/i.test(String(value || '')) && !/fail|failed|error|blocked/i.test(String(value || ''));
+}
+function strongestSupportedTruth(rows = []) {
+    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';
+}
+function evaluateFakeRealPolicy({ summary = {}, evidenceRows = [], options = {} }) {
+    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 = [];
+    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 = 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 = []) {
+    return rows.some((row) => (row.kind === 'runtime' || row.kind === 'cleanup') && ['proven', 'verified'].includes(row.truth));
+}
+function hasRealVisualProof(rows = []) {
+    return rows.some((row) => row.kind === 'visual' && row.truth === 'verified');
+}
+function runtimeLevelFor(rows = [], pattern, required = false) {
+    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, proofLevel, required) {
+    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, value, truth) {
+    return { kind, value: String(value || ''), truth };
+}
+function hasText(values = [], pattern) {
+    return values.some((value) => pattern.test(String(value || '')));
+}
+function asList(value) {
+    if (!value)
+        return [];
+    return Array.isArray(value) ? value.filter(Boolean).map(String) : [String(value)].filter(Boolean);
+}
+function uniqueStrings(values = []) {
+    return [...new Set(values.filter(Boolean).map(String))];
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "yam-flow",
+  "version": "0.1.0",
+  "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
+  "type": "module",
+  "author": "0kim0bos",
+  "homepage": "https://github.com/0kim0bos/yam#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0kim0bos/yam.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0kim0bos/yam/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "yam": "dist/bin/yam.js"
+  },
+  "types": "dist/lib/trust-kernel.d.ts",
+  "exports": {
+    "./trust-kernel": {
+      "types": "./dist/lib/trust-kernel.d.ts",
+      "import": "./dist/lib/trust-kernel.js"
+    }
+  },
+  "files": [
+    "AGENTS.md",
+    "COMMANDS.md",
+    "DECISIONS.md",
+    "LICENSE",
+    "README.md",
+    "ROADMAP.md",
+    "dist",
+    "src",
+    "tsconfig.json",
+    "references",
+    "skills",
+    "templates",
+    "yam.manifest.json"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "install:skills": "node ./dist/bin/yam.js install",
+    "uninstall:skills": "node ./dist/bin/yam.js uninstall",
+    "status": "node ./dist/bin/yam.js status",
+    "verify": "node ./dist/bin/yam.js verify",
+    "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 ./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",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:dry": "npm publish --dry-run --access public",
+    "forbidden-names:check": "node ./scripts/check-forbidden-names.mjs",
+    "package-boundary:check": "node ./scripts/check-package-boundary.mjs",
+    "dist:freshness": "node ./scripts/check-dist-freshness.mjs",
+    "registry:check": "node ./scripts/check-registry-version.mjs",
+    "cli-smoke": "node ./scripts/cli-smoke.mjs",
+    "release:check": "npm run typecheck && npm run forbidden-names:check && npm run verify:self && npm run dist:freshness && npm run package-boundary:check && npm run registry:check && npm run cli-smoke",
+    "budget": "node ./dist/bin/yam.js budget",
+    "measure": "node ./dist/bin/yam.js measure",
+    "tools": "node ./dist/bin/yam.js tools",
+    "proof": "node ./dist/bin/yam.js proof",
+    "safety": "node ./dist/bin/yam.js safety",
+    "detect": "node ./dist/bin/yam.js detect",
+    "pack": "node ./dist/bin/yam.js pack",
+    "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"
+  },
+  "keywords": [
+    "codex",
+    "harness",
+    "codex-skills",
+    "ai-agents",
+    "developer-tools",
+    "verification",
+    "ui-review",
+    "proof-first",
+    "skills",
+    "proof",
+    "ui"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
+}

package/references/context-reuse.md

@@ -0,0 +1,59 @@
+# Context Reuse
+
+One purpose of `yam` is to avoid re-reading the whole project and re-planning from scratch every run.
+
+Default order:
+
+```text
+1. Read project direction pack if present.
+2. Read `.yam/memory/summary.md` only when repeated mistakes or direction changes matter.
+3. Read the specific files needed for the request.
+4. Reuse known commands and constraints from the pack.
+5. Expand context only when evidence shows the pack is stale or incomplete.
+```
+
+Preferred project pack:
+
+```text
+yam.project.md
+```
+
+What it should contain:
+
+- Product direction.
+- Current UI/design direction.
+- Tech stack.
+- Important commands.
+- Test/build expectations.
+- Key directories.
+- Things not to do.
+- Current known risks.
+- Recent decisions.
+
+Optional memory summary:
+
+```text
+.yam/memory/summary.md
+```
+
+Use it only for known wrong decisions, repeated mistakes, direction changes, and lessons that would otherwise be rediscovered.
+
+Rules:
+
+- Do not regenerate a broad plan when `yam.project.md` already answers the direction question.
+- Do not reread architecture docs unless the task touches architecture.
+- Do not reread full design docs for tiny UI work when the pack has the relevant style direction.
+- If the pack is stale, update the pack narrowly instead of carrying stale assumptions in chat.
+- Keep the pack short; it is a context-saving artifact, not a second README.
+- Do not read every `.yam/memory/records/*.json` file by default; use `yam memory summary`.
+- Follow `references/markdown-management.md` when creating or updating markdown surfaces.
+
+Suggested size:
+
+```text
+500 to 1200 words.
+```
+
+Truth rule:
+
+If no project pack exists, say that direction was inferred from local files, not from a maintained project pack.

package/references/current-docs.md

@@ -0,0 +1,45 @@
+# Current Docs Rule
+
+Use current docs proof only when stale knowledge is a realistic risk.
+
+## Require Current Docs Proof
+
+Use Context7, official docs, or primary sources when the task depends on current behavior for:
+
+- modern SDK/API syntax
+- cloud services such as Supabase, Vercel, OpenAI, Stripe, or auth providers
+- framework version behavior, migration, deprecation, or breaking changes
+- CLI flags, deployment behavior, pricing/limits, security rules, or platform integrations
+- user wording such as latest, current, recently changed, new version, official docs, migration, or upgrade
+
+## Usually Skip
+
+Do not force current-docs proof for:
+
+- stable programming concepts
+- local codebase pattern matching
+- small copy/CSS/UI polish
+- questions answered by the project pack or local source
+- implementation that follows already-installed project conventions without external API uncertainty
+
+## Output Line
+
+Use one concise line:
+
+```text
+Current-docs proof: Context7/official docs checked for <SDK/service>; result applied to <decision>.
+```
+
+Or:
+
+```text
+Current-docs proof: skipped because this was stable/local/non-SDK work.
+```
+
+## Design Baseline
+
+Strict proof favors source-backed evidence for current tool behavior.
+
+Modular skill workflows keep research/context selective and low-context.
+
+Minimal-core design says the rule is useful only when it changes the answer.

package/references/db-supabase-safety-lite.md

@@ -0,0 +1,40 @@
+# DB/Supabase Safety Lite
+
+This is an advisory proof-first trust layer, not a database scanner.
+
+Use it when a prompt, command, migration, or code change touches database mutation, Supabase, RLS, production data, or schema changes.
+
+## Risk Signals
+
+Recommend `$deep` when you see:
+
+- `DROP`, `TRUNCATE`, `DELETE FROM`, broad `UPDATE`, or `ALTER TABLE`.
+- `supabase db reset`, `supabase db push`, migration generation, migration apply, or remote/linked project commands.
+- ORM migration commands such as Prisma, Drizzle, Knex, or Sequelize migrations.
+- RLS/policy/permission changes: `CREATE POLICY`, `ALTER POLICY`, `GRANT`, `REVOKE`.
+- Production/remote signals: `prod`, `production`, `live`, `DATABASE_URL`, `service_role`, `--db-url`, `--linked`, `--remote`, or `--project-ref`.
+
+## Guardrail
+
+Before claiming safe:
+
+- identify local/staging/production target
+- prefer read-only inspection first
+- require explicit user approval for destructive or production writes
+- know the rollback or backup path when data can be lost
+- run the smallest honest verification that matches the claim
+
+## Truth Language
+
+- Pattern detection is `assumed`, not proof.
+- Read-only inspection can be `partial` or `verified` for the inspected surface.
+- A successful migration command is not automatically safe; it only proves that command execution completed.
+- Do not claim production safety without environment evidence.
+
+## Design Baseline
+
+Strict proof would gate destructive DB work more aggressively.
+
+Modular skill workflows keep the check selective and evidence-bound.
+
+Minimal-core design keeps this as a short rule and a small detector, not a full DB policy engine.