pi-crew 0.9.49 → 0.9.51

package/skills/distill-persona/references/field-models.md

@@ -0,0 +1,20 @@
+## Field models (from distilling the 3 source projects)
+
+> Self-distillation artifact: this skill was applied to its own sources (nuwa engine + 2 awesome-list indexes). Full triple-verification synthesis in `references/distillation-field-synthesis.md`. Five field models surfaced that the engine-only view missed — they shape Phase 0 below.
+
+**M-F1 — Dissemination flywheel.** A mature distillation practice is 3 layers: **engine (distill) → index (awesome-list) → auto-curation (issue→PR→merge)**. Both awesome-lists ship auto-curation pipelines wrapping nuwa. *Implication*: distilling a skill is step 1; getting it discovered + quality-gated + distributed is steps 2-3. Overkill at personal scale; earns its cost at registry scale.
+
+**M-F2 — Target taxonomy.** Targets form a spectrum with different source-availability, ethics, and method. *Gestalt (pass 1):* self → close-living → commemorative → public-figure → field. **Empirically corrected (R1 sweep of ~187 real entries):** the spectrum is **bimodal, not balanced** — public-figures ≈84% of practice. Corrections: (a) a **meta-distillation-engine tier sits ABOVE the spectrum** (nuwa/immortal/ditto/forge/anti-distill — tools that distill, not personas); (b) public-figure needs **sub-domains + a `living-content-creator` sub-tier** (UP主/内娱/峰哥 — recency-gated, platform-bound) distinct from historical figures; (c) **commemorative splits** into death (consent-of-estate) vs breakup (**ex/crush = the consent-gray-zone** → must trigger M-F3 gate; crush.skill simulates a living non-consenting person's chat); (d) self splits functional vs archaeological; (e) **adversarial** (anti-distill, vengeful-ghost) is a real counter-movement, not satire. See `references/research/r1-c-human-readme.md`. *Implication*: route by tier; the consent gate is mandatory for close-living + breakup-commemorative + living-creator-of-others.
+
+**M-F3 — Ethics spectrum: commemorative ↔ consent-violating ↔ deliberately-degraded.** Same technique, opposite moral weight — from a *memorial act* (preserving a lost person's thinking) to a *consent violation* (cloning a living non-consenting individual). Anti-distill satire is a *legitimate* pressure-test stance, not a defect. **R2 refine:** anti-distill is not just satire — it's a practical **IP-protection mechanism** ("sanitize your forced Skill file — looks complete, core knowledge stays yours"). This is a *third pole*: deliberately-degraded output. For forced/employer-mandated distillation, controlled degradation is the *ethical* choice; the engine should support a "redaction mode" where the subject marks models as public vs withheld. *Implication*: every distillation declares its ethics tier; the slip-line is "methodology lens" (ok) vs "persona impersonation" (flag).
+
+**M-F4 — The field systematically over-claims its own fidelity.** (pass-2 meta-model, validated at n=3) Every published distillation score is an *upper bound*: nuwa publishes 94-97/100; the indexes propagate them; independent re-scoring lands 67-76 (edge-honesty 20→7/13/7). The inflation is *question-design* (easy/known-adjacent edges, no framework-answerable novel edge) + author-side confirmation bias — NOT scorer contamination (F2 refuted). *Implication*: treat ANY published distillation score as an optimistic ceiling; re-score independently with a framework-answerable novel edge before trusting. A skill that "scores 97" but can't flag inference on a novel in-domain question is not ship-ready. See `references/distillation-field-synthesis-pass2.md`.
+
+**🔴 Structural-gate warning (R1 sweep of quality_check.py):** nuwa's automated `quality_check.py` validates only 6 STRUCTURAL criteria (model-count, limitations keyword, expression-DNA markers, honest-boundary section, tensions, primary-source ratio). It does NOT check the behavioral edge-honesty that F2' showed matters. **A skill can pass quality_check.py 6/6 and still fail the F2' edge-honesty gate.** Never trust a structural-only auto-pass; require the behavioral framework-answerable-edge test (`scripts/fidelity_eval.py`).
+
+**M-F7 — Structural invariants ARE the quality gate at index scale.** (R1 sweep of the 5 test files) At registry scale (200+ entries, bilingual), "quality" shifts from content-review to structure-enforcement — the invariants only CI can check ARE the gate: bilingual URL-parity per category, deterministic repo-slug sort (the only language-agnostic key), cross-section dedup, terminal-punctuation normalization, governance-keyword embedding in docs, and `doesNotMatch` regression guards for known-failed approaches. These are impossible to verify by hand at scale. *Implication*: when building a distillation registry, encode invariants as CI checks (not doc rules), use language-agnostic identity keys, make submissions atomic across languages. Necessary-not-sufficient (a coherent index can still hold bad distillations — complements M4/M-F4, doesn't replace them). See `references/research/r1-d-tests.md`.
+
+**R2 refine (two invariant classes):** at registry scale there are TWO distinct invariant classes: (a) **STATIC structural** — deterministic sort, dedup, terminal-punctuation parity, bilingual URL-parity (from nuwa tests); (b) **DYNAMIC quality** — star-based re-ranking, link-liveness checks, auto-issue on dead links (from awesome-human-distillation CI). Both CI-gated but serve different purposes: structural = consistency, dynamic = freshness/ranking. A registry needs *both*. (Original M-F7 described only class (a); awesome-human-distillation's `sort_by_stars.py` + `check_links.py` demonstrate class (b).)
+
+---
+

package/skills/distill-persona/references/optional-body-sections.md

@@ -0,0 +1,9 @@
+### Optional body sections (○)
+
+| Section | When to add | Must contain |
+|---------|------------|-------------|
+| ⚠️ 反机械化约束 | Always recommended | Don't reveal internal model names; vary narrative arcs; cap repeated markers (max 2× "我发现"/response); make tool-calling invisible (F9) |
+| 激活确认 (Dual-mode) | "Analyze how X thinks" vs "be X" | Path A roleplay (first-person) vs Path B analyst (third-person, probability dist, confidence ratings, key unknowns) (F10) |
+| 场景→模型路由表 | ≥4 mental models | `\| problem type \| priority model \| priority heuristic \| conflict rule \|` — prevents "use all models every time" (F12) |
+| 可运行工具脚本 | Software/topic flavor | `\| script \| function \| usage \|` — wired INTO Agentic Protocol Step 2 (F13/F17), never orphaned |
+

package/skills/distill-persona/references/registry-routing.md

@@ -0,0 +1,11 @@
+## Phase 6 — Registry routing + multi-persona debate (optional, post-distillation)
+
+When multiple persona skills exist in the registry, two meta-patterns emerge:
+
+- **Curator routing** ("curator.skill" pattern): a meta-skill that matches user intent → best-fit persona skill from the pool. Analyzes the question, recommends/activates the most relevant skill. Complements Phase 0B diagnostic (which is pre-distillation); this is post-distillation routing.
+- **Multi-persona debate** ("zhuzi-skill" pattern): select 2–4 relevant persona skills; each independently analyzes via its Agentic Protocol; structured round-based exchange; neutral synthesis. Produces higher-quality analysis than any single lens ("how would Musk AND Munger AND Taleb approach this?").
+
+These are registry-scale capabilities — only relevant when ≥3 persona skills exist. Building blocks (Agentic Protocol, mental models, expression DNA) are already produced by this skill.
+
+---
+

package/skills/distill-persona/references/self-upgrade-directive.md

@@ -0,0 +1,20 @@
+## ⚠️ CONCEPTUAL NOTE — SELF-UPGRADE DIRECTIVE (read before every run)
+
+**Chưng cất = chắt lọc tinh túy source → apply VÀO target** (target cải thiện). Skill chỉ là 1 tool apply, không phải output.
+
+**Skill trong source cũng chỉ là 1 PHẦN cần sweep** — xử lý bằng cùng 3-chiều filter như mọi phần khác (conventions, architecture, lint, decisions...). Nếu skill đó hữu dụng cho target → lấy; không → bỏ. Không ưu tiên, không đặc biệt.
+
+**ĐÀO TRIỆT ĐỂ — KHÔNG QUA LOA**: khi chưng cất 1 đối tượng, PHẢI đọc/re-read đầy đủ TOÀN BỘ nội dung của đối tượng đó. Không dựa vào trí nhớ. Không recap. Mỗi file, mỗi section, mỗi practice phải được:
+1. **Đọc thật** (read/re-read file gốc, không memory-grep)
+2. **Trích từng finding** (systematic, từng section)
+3. **So sánh với target** (3-chiều filter: relevant? → có? → cần/tốt hơn?)
+4. **Ghi lại** kết quả filter (ADOPT/IMPROVE/MERGE/SKIP + lý do)
+
+Qua loa = thất bại. Memory-recap = thất bại. Chưng cất thật = đọc từng dòng → trích → so → apply.
+
+**Khi sử dụng**: nếu output chỉ là standalone skill (không apply vào target) → **chưa hoàn thành**. Tự nâng cấp: thêm target parameter + 3-chiều filter (relevance → presence+need → quality compare) + **pre-apply effectiveness verification** (SELECTED phải chứng minh hiệu quả CHO TARGET NÀY — generative/problem-exists/delta-test — trước khi apply; "assume effective" = không được) + apply phase. See `distill-software` for the full directive + the EFFECTIVENESS VERIFICATION gate spec.
+
+**Pre-apply gate (tóm tắt, áp dụng cả khi persona distill INTO target)**: giữa "đã quyết định ADOPT/IMPROVE/MERGE" và "apply" phải có 1 verify bước — (1) concrete delta (cái gì đổi?), (2) effectiveness proof (≥1: đổi quyết định thật / target có vấn đề này / delta-test tốt hơn), (3) conflict check, (4) verdict ✅TO-APPLY / ❌REJECTED+log. Chỉ TO-APPLY mới edit target. Đây là analog apply-side của Phase 2.6 V3 (V3 verify model effective lúc extract; gate này verify apply effective lúc integrate). **APPLY consent + path-containment gate (HIGH-2)**: trước khi edit bất kỳ target file nào: (a) resolve target về canonical path, kiểm tra nằm trong approved root — reject symlink escape / out-of-target writes; (b) xuất exact file list + diff plan cho user; (c) yêu cầu **explicit user confirmation** trước lần ghi đầu tiên (no destructive action without `--confirm`); (d) rollback = inverse patch hoặc restore file cụ thể, không broad `git reset`/clean/force-push; (e) không tự delete/prune, install dependency, chạy script từ source repo, commit/publish, hay gửi network data.
+
+---
+

package/skills/distill-persona/references/taste-principles.md

@@ -0,0 +1,8 @@
+## Taste principles (quick reference for judgment calls)
+
+| Principle | One-liner |
+|---|---|
+| **Long-form > quotes** | A 3000-word essay reveals more thinking structure than 50 tweets |
+| **Controversy > consensus** | The most controversial opinions reveal the most uniqueness |
+| **Change > static** | Where they CHANGED stance is more informative than where they held firm |
+

package/skills/distill-persona/references/topic-variant.md

@@ -0,0 +1,13 @@
+## Topic-skill phase variant (when flavor = topic/field)
+
+| Phase | Person skill | Topic variant |
+|---|---|---|
+| 0A | confirm person + focus | confirm topic boundary + target audience |
+| 0.5 | `[person]-perspective/` | `[topic]-framework/`, same dir structure |
+| 1 | 6 agents around ONE person | search 3-5 core people/schools, assign agents per person (1-2 each) |
+| 2.1 | extract ONE person's mental models | extract **field consensus** (all schools agree) + **school divergences** (A says X, B says Y) |
+| 2.3 | simulate ONE person's expression | neutral but professional (no role-play) |
+| 2.4 | one person's inner contradictions | **fundamental disagreements between schools** |
+| 3 | use skill-template.md | adjust: remove role-play + identity card → add "framework overview" + "school comparison" |
+| 4 | compare against this person's known stances | compare against field's canonical classic cases |
+

package/skills/distill-persona/references/update-mode.md

@@ -0,0 +1,7 @@
+## Update mode
+"update <person>'s skill": read existing, find `distilled:` date; run only streams 2 + 5 + 6 (recent); merge (strengthen / flag contradiction / add new model); update date + latest-dynamics. Never rewrite wholesale.
+
+**No-op detection**: after merge, if no model was added/strengthened/contradicted → report "no new contribution since last distillation; existing skill is current." Do NOT re-ship an unchanged skill — it wastes cost and pollutes the registry with false "updated" timestamps. Also check for a pre-existing update in progress before starting (idempotency).
+
+**Deletion tracking (#12)**: updates must also log what was *removed* (`### Removed` section in the skill's changelog/BUILD-NOTES), not just added. A skill that only ever grows drifts — stale heuristics never get pruned. Enumerate each retired model/heuristic/source with a 1-line reason; if nothing was removed, state "no removals" explicitly (auditable).
+

package/skills/distill-persona/scripts/validate-run.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+// validate-run.mjs — machine-checked RUN-completion gate for distillation runs.
+//
+// Complements validate-skill-structure.mjs (which checks the OUTPUT skill's STRUCTURE —
+// frontmatter, sections, anti-drift tables). This checks the RUN: did the agent produce
+// every required process artifact + fire every gate? Both must pass before claiming done:
+//   validate-skill-structure.mjs <skill-dir>   →  output skill structure
+//   validate-run.mjs <run-dir>                 →  run completeness (this script)
+//
+// ALSO checks Phase 4 APPLY evidence (software + persona flavors): APPLY-LOG.md must
+// exist at run-dir root, documenting what was edited in the TARGET (SKILL.md is the
+// intermediate essence, not the deliverable — distillation = source → essence → APPLY).
+//
+// Run BEFORE claiming done. If you feel tempted to skip a phase to save effort,
+// THAT is exactly when you must run the gate. A skipped gate = a failed run.
+//
+// Usage:
+//   node validate-run.mjs <run-dir>                          →  distillation run completeness
+//   node validate-run.mjs <skill-dir> --build                →  engine-skill build completeness
+//                                                              (--build: skips APPLY-LOG, alias-tolerant evidence,
+//                                                               AND Phase 2.7/5.5 checks — engine builds have no target-apply)
+//
+// Exit codes: 0 = ALL-GREEN (run complete — may ship); 1 = NOT READY (produce missing artifacts, re-run).
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+const runDir = process.argv.find((a) => !a.startsWith('-') && a !== process.argv[0] && a !== process.argv[1]);
+if (!runDir || !existsSync(runDir) || !statSync(runDir).isDirectory()) {
+	console.error('Usage: validate-run.mjs <run-dir>');
+	console.error('  <run-dir> = directory holding the distillation artifacts (SKILL.md, FIDELITY.md, …)');
+	process.exit(2);
+}
+
+const isBuild = process.argv.includes('--build');
+// Mode auto-detection (default mode; --build stays Capture and skips these):
+//   APPLY mode   = APPLY-LOG.md present at run-dir root → SKILL.md optional (deliverable = target transformed)
+//   CAPTURE mode = no APPLY-LOG.md                    → SKILL.md + FIDELITY required (current behavior)
+const applyLogExists = existsSync(join(runDir, 'APPLY-LOG.md'));
+const isApplyMode = !isBuild && applyLogExists;
+const isCaptureMode = !isBuild && !applyLogExists;
+
+const failures = [];
+const passes = [];
+const check = (label, ok, detail = '') => {
+	(ok ? passes : failures).push(ok ? `  ✓ ${label}` : `  ✗ ${label}${detail ? ' — ' + detail : ''}`);
+};
+
+const readText = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : null);
+
+// count list/table items under a heading (mirrors validate-skill-structure.mjs)
+function countListItems(haystack, headingRe, windowChars = 2000) {
+	const m = haystack.match(headingRe);
+	if (!m) return { found: false, count: 0 };
+	const after = haystack.slice(m.index);
+	const section = after.match(/([\s\S]*?)\n##(?=[^#])/);
+	const block = section ? section[1] : after.slice(0, windowChars);
+	const listItems = (block.match(/^\s*(?:\d+[.)]|[-*])\s+\S/gm) || []).length;
+	const tableRows = (block.match(/^\s*\|(?![\s:|-]+\|?\s*$).+\|/gm) || []).length;
+	return { found: true, count: listItems + tableRows };
+}
+
+// hint: does a file exist at the flat research/ path? (artifact-scattering signal)
+const flatHint = (name) => existsSync(join(runDir, 'research', name)) ? ' (found at research/ — artifact scattering; canonical path is references/research/)' : '';
+
+// --- SKILL.md ---
+// Apply mode: optional (deliverable = target transformed + APPLY-LOG, NOT a skill file).
+// Capture/build mode: required at run-dir root (NOT scattered elsewhere).
+const skillPath = join(runDir, 'SKILL.md');
+const skillText = readText(skillPath);
+if (isApplyMode && !skillText) {
+	passes.push('  ℹ no SKILL.md — correct for Apply mode (deliverable = target transformed + APPLY-LOG)');
+} else {
+	check('SKILL.md exists at run-dir root (NOT scattered elsewhere)', !!skillText,
+		!skillText ? 'missing — did you install it to ~/.pi/agent/skills/ early? Keep it in run-dir until ALL-GREEN' : '');
+}
+
+let isSoftware = false;
+let isPersona = false;
+let isTopic = false; // research/topic flavor — its 'apply' is a validated report; no APPLY-LOG required
+
+if (skillText) {
+	const fm = skillText.match(/^---\n([\s\S]*?)\n---/);
+	check('SKILL.md: frontmatter --- block present', !!fm, 'no --- block at top');
+	const fmText = fm ? fm[1] : '';
+
+	const PLACEHOLDERS = [/<person>/i, /<target>/i, /<topic>/i, /<field>/i, /TODO/i, /TBD/i, /XXX/i, /YYYY-MM-DD/i, /\.\.\.\s*<\/?/i];
+	const found = PLACEHOLDERS.filter((re) => re.test(skillText));
+	check('SKILL.md: no unresolved placeholder text', found.length === 0,
+		found.map((re) => skillText.match(re)?.[0]).filter(Boolean).join(', '));
+
+	// flavor auto-detect
+	isSoftware = /target:\s*(software|codebase|engineer)/i.test(fmText) || /code-?dna|代码表达DNA|code expression/i.test(skillText);
+	isPersona = !isSoftware && (/target:\s*(person|topic)/i.test(fmText) || /mental.?model/i.test(skillText));
+	isTopic = /target:\s*topic/i.test(fmText); // exclude topic/research flavor from APPLY checks
+
+	if (isSoftware) {
+		check('[software] Code-DNA section present', /代码表达DNA|Code Expression-DNA|code.?dna/i.test(skillText), 'missing 代码表达DNA/code-DNA section');
+		check('[software] toolchain matrix present', /toolchain|eslint|oxlint|biome|tsconfig|deno|rustfmt/i.test(skillText), 'no toolchain detection');
+		check('[software] distilled_against anchor present', /distilled_against/i.test(fmText) || /distilled_against/i.test(skillText), 'no distilled_against staleness anchor');
+	}
+
+	if (isPersona) {
+		check('[persona] mental-models section present', /mental.?model|心智模型|核心心智模型/i.test(skillText), 'no mental-models section');
+		const boundary = countListItems(skillText, /诚实边界|honest boundar(?:y|ies)/i);
+		check('[persona] honest-boundaries ≥3 items', boundary.count >= 3, boundary.found ? `found ${boundary.count} items` : 'section missing');
+	}
+}
+
+// --- Fallback flavor detection (when SKILL.md is absent/scattered) ---
+// Needed because isSoftware/isPersona are only set inside if(skillText); a run that
+// skipped APPLY often also has no SKILL.md at the run-dir root (it was installed early
+// or never written there). Detect software flavor from research/CODE-DNA.md so the
+// APPLY-evidence checks still fire for the all-too-common 'wrote SKILL, skipped APPLY' case.
+if (!isSoftware && !isPersona && !isTopic) {
+	if (existsSync(join(runDir, 'references', 'research', 'CODE-DNA.md')) ||
+	    existsSync(join(runDir, 'research', 'CODE-DNA.md')) ||
+	    /code-?dna/i.test(basename(runDir))) {
+		isSoftware = true;
+	}
+}
+
+// --- APPLY-LOG.md (Phase 3 APPLY evidence — Apply mode only) ---
+// Apply mode (APPLY-LOG.md present): the deliverable is the target transformed — these
+// checks are REQUIRED. Capture mode (--build or no APPLY-LOG): skipped (no target-apply).
+// Gated on isApplyMode (not flavor) so it fires even when SKILL.md is absent in Apply mode.
+if (isApplyMode) {
+	const applyLogPath = join(runDir, 'APPLY-LOG.md');
+	const applyText = readText(applyLogPath);
+	check('APPLY-LOG.md exists at run-dir root', !!applyText,
+		!applyText ? 'Phase 4 APPLY missing — SKILL.md is intermediate, not the deliverable. Distillation = source → essence → APPLY to target. A standalone SKILL.md = NOT complete.' : '');
+	if (applyText) {
+		// count list items + table rows across the whole file (mirrors countListItems)
+		const applyItems = (applyText.match(/^\s*(?:\d+[.)]|[-*])\s+\S/gm) || []).length
+			+ (applyText.match(/^\s*\|(?![\s:|-]+\|?\s*$).+\|/gm) || []).length;
+		check('APPLY-LOG: ≥3 applied items', applyItems >= 3, `found ${applyItems} item(s) — need ≥3 concrete edits in the target`);
+		const pathRefs = /\/[\w.-]+\.\w{1,4}|src\/|AGENTS\.md|scripts\/|package\.json|tsconfig/i.test(applyText);
+		check('APPLY-LOG: references target file paths', pathRefs, 'no file-path-like tokens found — add paths proving real edits (not just claims)');
+		const verified = /test|typecheck|build|bundle|lint|pass|green|✅|97\/97|all-green/i.test(applyText);
+		check('APPLY-LOG: verification evidence (test/typecheck/bundle/lint pass)', verified, 'no verification keyword found — add test/build/lint pass evidence');
+	}
+}
+
+// --- FIDELITY.md ---
+// --build mode: accept references/fidelity.md as an alias (workflow produces it there)
+const fidText = isBuild
+	? (readText(join(runDir, 'FIDELITY.md')) || readText(join(runDir, 'references', 'fidelity.md')))
+	: readText(join(runDir, 'FIDELITY.md'));
+const fidLabel = isBuild ? 'FIDELITY.md exists (root or references/fidelity.md)' : 'FIDELITY.md exists at run-dir root';
+check(fidLabel, !!fidText, !fidText ? 'missing' : '');
+if (fidText) {
+	const totalMatch = fidText.match(/(?:总分|total)[：:\s*]*\*{0,2}([0-9]+)\s*\*?\s*(?:\/|／|\sout\sof\s)\s*\*?\s*100/i);
+	check('FIDELITY.md: /100 total score present', !!totalMatch, totalMatch ? `=${totalMatch[1]}/100` : 'no /100 score found');
+	const qCount = (fidText.match(/(?:Q[1-5]|问题[1-5]|question\s*[1-5])/gi) || []).length;
+	check('FIDELITY.md: ≥5 test-question references', qCount >= 5, `found ${qCount} question refs`);
+	check('FIDELITY.md: flags single-agent/self-score caveat',
+		/单\s*agent|single.?agent|self.?score|upper.?bound|independent/i.test(fidText),
+		'add single-agent upper-bound caveat');
+}
+
+// --- DISTILLATION-PROCESS-CHECKLIST.md ---
+const procText = readText(join(runDir, 'DISTILLATION-PROCESS-CHECKLIST.md'));
+check('DISTILLATION-PROCESS-CHECKLIST.md exists', !!procText, !procText ? 'missing — every phase + the 3-round deep-dive gate must be tracked' : '');
+if (procText) {
+	const dangling = (procText.match(/\|\s*[⬜⏳][^|]*\|/gu) || []).length;
+	check('process: no dangling ⬜/⏳ phase rows (every phase completed)', dangling === 0, dangling ? `${dangling} phase(s) not done` : '');
+	check('process: deep-dive round-log table present', /round log|\| *Round.*New findings/i.test(procText), 'add the round-log table');
+	check('process: 3-empty-rounds gate fired', /gate fires|3 consecutive (empty|zero)|GATE FIRES/i.test(procText),
+		'record ≥3 consecutive zero-new rounds before declaring a phase done');
+}
+
+// --- EXCAVATION-CHECKLIST.md ---
+const excText = readText(join(runDir, 'EXCAVATION-CHECKLIST.md'));
+check('EXCAVATION-CHECKLIST.md exists', !!excText, !excText ? 'missing — Phase 1 protocol requires one' : '');
+if (excText) {
+	const danglingExc = (excText.match(/\|\s*[⬜⏳][^|]*\|/gu) || []).length;
+	check('excavation: no dangling ⬜/⏳ rows (every part resolved)', danglingExc === 0, danglingExc ? `${danglingExc} row(s) not resolved` : '');
+	const ratioMatch = excText.match(/memory-ratio[:\s]*([0-9]+)\s*%/i);
+	if (ratioMatch) {
+		const ratio = parseInt(ratioMatch[1], 10);
+		check('excavation: 🧠 memory-ratio ≤30%', ratio <= 30, `declared ${ratio}% (>30% = recap, not distillation)`);
+	} else {
+		check('excavation: declares memory-ratio', false, 'add "🧠 memory-ratio: NN% (X/Y)" header');
+	}
+	const proofCells = (excText.match(/"[^"]{8,}"/g) || []).length;
+	check('excavation: ≥1 proof-of-read (verbatim quote cell)', proofCells >= 1, `${proofCells} quote cell(s)`);
+}
+
+// --- references/research/ artifacts (canonical path — solves scattering) ---
+const researchDir = join(runDir, 'references', 'research');
+
+if (isBuild) {
+	// --- BUILD MODE: alias-tolerant evidence checks ---
+	// Engine skills use different file names than distillation runs.
+	// Accept canonical names OR common aliases OR name/content regex matches.
+	const refsDir = join(runDir, 'references');
+
+	// Helper: find a file under references/ or references/research/ by name regex or content regex
+	function findRef(nameRe, contentRe) {
+		const dirs = [refsDir, researchDir].filter((d) => existsSync(d) && statSync(d).isDirectory());
+		for (const d of dirs) {
+			for (const f of readdirSync(d)) {
+				const fp = join(d, f);
+				if (!existsSync(fp) || !statSync(fp).isFile()) continue;
+				if (nameRe && nameRe.test(f)) return fp;
+				if (contentRe) {
+					const txt = readText(fp);
+					if (txt && contentRe.test(txt)) return fp;
+				}
+			}
+		}
+		return null;
+	}
+
+	// 1. Coverage evidence
+	const covPath =
+		existsSync(join(researchDir, 'COVERAGE-MANIFEST.md')) ? join(researchDir, 'COVERAGE-MANIFEST.md')
+		: existsSync(join(refsDir, 'source-inventory.md')) ? join(refsDir, 'source-inventory.md')
+		: existsSync(join(refsDir, 'coverage-manifest.md')) ? join(refsDir, 'coverage-manifest.md')
+		: findRef(null, /UNCOVERED.*COVERED|covered.*parts/i);
+	const covTextB = covPath ? readText(covPath) : null;
+	check('coverage evidence present (COVERAGE-MANIFEST | source-inventory | coverage-manifest | content-match)',
+		!!covTextB, !covTextB ? 'missing — no coverage evidence found under references/' : `found: ${covPath}`);
+	if (covTextB) {
+		const uncovered = (covTextB.match(/\|\s*UNCOVERED[^|]*\|/gi) || []).length;
+		check('coverage: no dangling UNCOVERED rows', uncovered === 0, uncovered ? `${uncovered} part(s) not covered` : '');
+	}
+
+	// 2. V5/citation-verify evidence
+	const v5Path =
+		existsSync(join(researchDir, 'V5-VERIFICATION.md')) ? join(researchDir, 'V5-VERIFICATION.md')
+		: existsSync(join(refsDir, 'verified-models.md')) ? join(refsDir, 'verified-models.md')
+		: findRef(/v5|verified|citation/i, null);
+	check('V5/citation-verify evidence present (V5-VERIFICATION | verified-models | name-match)',
+		!!v5Path, !v5Path ? 'missing — no V5/citation evidence found under references/' : `found: ${v5Path}`);
+
+	// 3. Effectiveness-gate evidence
+	const effPath =
+		existsSync(join(researchDir, 'EFFECTIVENESS-VERIFICATION.md')) ? join(researchDir, 'EFFECTIVENESS-VERIFICATION.md')
+		: existsSync(join(refsDir, 'effectiveness-gate.md')) ? join(refsDir, 'effectiveness-gate.md')
+		: existsSync(join(refsDir, 'three-filter.md')) ? join(refsDir, 'three-filter.md')
+		: findRef(/effectiveness|three-filter|gate/i, null);
+	// FIDELITY.md validates the built skill reproduces the target — for an engine-skill BUILD that IS effectiveness
+	// evidence. The pre-apply effectiveness-gate.md is a forward-looking workflow artifact, not retroactively required
+	// for hand-built engine skills (research/persona/software predate Phase 2.6).
+	const effViaFidelity = !effPath && !!fidText;
+	check('effectiveness-gate evidence present (EFFECTIVENESS-VERIFICATION | effectiveness-gate | three-filter | FIDELITY.md)',
+		!!effPath || effViaFidelity, (!effPath && !effViaFidelity) ? 'missing — no effectiveness evidence found under references/ or FIDELITY.md' : `found: ${effPath || 'FIDELITY.md'}`);
+} else {
+	// --- DEFAULT MODE: strict canonical paths (UNCHANGED — byte-for-byte equivalent) ---
+	const covText = readText(join(researchDir, 'COVERAGE-MANIFEST.md'));
+	check('references/research/COVERAGE-MANIFEST.md exists', !!covText, !covText ? 'missing' + flatHint('COVERAGE-MANIFEST.md') : '');
+	if (covText) {
+		const uncovered = (covText.match(/\|\s*UNCOVERED[^|]*\|/gi) || []).length;
+		check('coverage: no dangling UNCOVERED rows', uncovered === 0, uncovered ? `${uncovered} part(s) not covered` : '');
+	}
+
+	const v5Exists = existsSync(join(researchDir, 'V5-VERIFICATION.md'));
+	check('references/research/V5-VERIFICATION.md exists', v5Exists, !v5Exists ? 'missing' + flatHint('V5-VERIFICATION.md') : '');
+
+	const effExists = existsSync(join(researchDir, 'EFFECTIVENESS-VERIFICATION.md'));
+	check('references/research/EFFECTIVENESS-VERIFICATION.md exists', effExists, !effExists ? 'missing' + flatHint('EFFECTIVENESS-VERIFICATION.md') : '');
+}
+
+// --- Phase 2.7 + 5.5 anti-lazy gate checks (APPLY mode only) ---
+// apply-plan + scrutinize are APPLY-mode artifacts (they assume a target to apply to).
+// CAPTURE mode (skill-build: --build, or no APPLY-LOG = persona/workflow) has no target-apply → skip.
+if (isApplyMode) {
+	// Phase 2.7 output: references/apply-plan.md
+	const applyPlanPath = join(runDir, 'references', 'apply-plan.md');
+	const applyPlanText = readText(applyPlanPath);
+	check('references/apply-plan.md exists (Phase 2.7 plan-approval gate output)', !!applyPlanText,
+		!applyPlanText ? 'missing — Phase 2.7 requires a plan table output' : '');
+	if (applyPlanText) {
+		const hasApproval = /APPROVED|LOW-YIELD DEFENSE/i.test(applyPlanText);
+		check('apply-plan: approval or defense present (APPROVED | LOW-YIELD DEFENSE)', hasApproval,
+			!hasApproval ? 'Phase 2.7 plan-approval gate not respected — present the plan and get approval (interactive) or write a LOW-YIELD DEFENSE (autonomous).' : '');
+	}
+
+	// Phase 5.5 output: SCRUTINIZE-REPORT.md at run-dir root
+	check('SCRUTINIZE-REPORT.md exists at run-dir root (Phase 5.5 adversarial scrutinize)', existsSync(join(runDir, 'SCRUTINIZE-REPORT.md')),
+		!existsSync(join(runDir, 'SCRUTINIZE-REPORT.md')) ? 'Phase 5.5 adversarial scrutinize not run — laziness unaudited.' : '');
+}
+
+// --- Report ---
+console.log(`\nvalidate-run: ${basename(runDir)}`);
+console.log(`path: ${runDir}\n`);
+passes.forEach((l) => console.log(l));
+failures.forEach((l) => console.log(l));
+const flavorTag = isSoftware ? ' [software]' : isPersona ? (isTopic ? ' [topic]' : ' [persona]') : '';
+const modeTag = isBuild
+	? ' [build mode — APPLY-LOG + strict-run checks skipped]'
+	: isApplyMode
+		? ' [apply mode — SKILL.md optional]'
+		: ' [capture mode]';
+console.log(`\n${passes.length} pass, ${failures.length} fail — ${failures.length === 0 ? '✅ ALL-GREEN (may ship)' : '🔴 NOT READY (produce the missing artifacts, then re-run)'}${flavorTag}${modeTag}\n`);
+process.exit(failures.length === 0 ? 0 : 1);