pi-crew 0.9.48 → 0.9.50

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);

package/skills/distill-persona/scripts/validate-skill-structure.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// validate-skill-structure.mjs — structural invariant checker for generated distill skills.
+// Implements F10 (awesome-persona-distill-skills finding): hard-fail if any structural assertion fails.
+// Run AFTER Phase 3 build, BEFORE Phase 4 behavioral fidelity. Self-contained (stdlib only).
+//
+// Usage:
+//   node validate-skill-structure.mjs <path-to-SKILL.md>
+//   node validate-skill-structure.mjs <skill-dir>
+//
+// Exit codes: 0 = all assertions pass (all-green → may ship); 1 = one or more failed (iterate).
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+
+const target = process.argv.find((a) => !a.startsWith('-') && a !== process.argv[0] && a !== process.argv[1]);
+if (!target) {
+	console.error('Usage: validate-skill-structure.mjs <path-to-SKILL.md | skill-dir> [--engine]');
+	process.exit(2);
+}
+
+// Resolve to a SKILL.md path
+let skillPath = target;
+if (statSync(target).isDirectory()) {
+	skillPath = join(target, 'SKILL.md');
+}
+if (!existsSync(skillPath)) {
+	console.error(`✗ Not found: ${skillPath}`);
+	process.exit(2);
+}
+
+const src = readFileSync(skillPath, 'utf8');
+const dir = dirname(skillPath);
+const name = basename(dir);
+const isEngine = process.argv.includes('--engine');
+const PLACEHOLDERS = [/<person>/i, /<target>/i, /<topic>/i, /<field>/i, /TODO/i, /TBD/i, /XXX/i, /YYYY-MM-DD/i, /\.\.\.\s*<\/?/i];
+
+const failures = [];
+const passes = [];
+const check = (label, ok, detail = '') => {
+	(ok ? passes : failures).push(ok ? `  ✓ ${label}` : `  ✗ ${label}${detail ? ' — ' + detail : ''}`);
+};
+
+// --- Frontmatter ---
+const fm = src.match(/^---\n([\s\S]*?)\n---/);
+check('frontmatter block present', !!fm, 'no --- block at top');
+const fmText = fm ? fm[1] : '';
+const fmField = (key) => {
+	const m = fmText.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+	return m ? m[1].trim() : null;
+};
+const hasFm = (key) => new RegExp(`^${key}:`, 'm').test(fmText);
+
+check('frontmatter: name', hasFm('name'));
+check('frontmatter: description', hasFm('description'));
+const desc = fmField('description');
+check('frontmatter: description ≤1 sentence (one terminal punct or one clause)',
+	desc ? desc.split(/[.。!！?？]/).filter(Boolean).length <= 2 : false,
+	desc ? `got: "${desc.slice(0, 60)}…"` : 'missing');
+check('frontmatter: triggers', hasFm('triggers') || hasFm('trigger'), 'no triggers field');
+if (!isEngine) check('frontmatter: distilled (staleness date)', hasFm('distilled') || hasFm('调研时间'), 'no distilled/调研时间 staleness anchor');
+const distilled = fmField('distilled') || fmField('调研时间');
+check('frontmatter: distilled is valid date (YYYY-MM-DD)',
+	!distilled || /^\d{4}-\d{2}-\d{2}/.test(distilled),
+	distilled ? `got "${distilled}"` : '');
+if (!isEngine) check('frontmatter: target (person|topic|software)', hasFm('target'), 'no target field');
+
+// --- Body sections ---
+check('Agentic Protocol section present', /回答工作流|Agentic Protocol/i.test(src));
+check('Agentic Protocol Step 1', /Step 1|第一步|步骤 1|### 1\b/i.test(src));
+check('Agentic Protocol Step 2', /Step 2|第二步|步骤 2|### 2\b/i.test(src));
+check('Agentic Protocol Step 3', /Step 3|第三步|步骤 3|### 3\b/i.test(src));
+
+// honest boundaries: count items (numbered list or bullets) under an honest-boundaries heading
+function countListItems(haystack, headingRe, windowChars = 2000) {
+	const m = haystack.match(headingRe);
+	if (!m) return { found: false, count: 0, block: '' };
+	const after = haystack.slice(m.index);
+	const section = after.match(/([\s\S]*?)\n##(?=[^#])/);
+	const block = section ? section[1] : after.slice(0, windowChars);
+	// count BOTH list items AND table data rows (rows with | content |, excluding separator rows)
+	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, block };
+}
+if (!isEngine) {
+	const boundary = countListItems(src, /诚实边界|honest boundar(?:y|ies)/i);
+	check('honest boundaries (M11) ≥3', boundary.count >= 3, `found ${boundary.count} items`);
+}
+
+// --- Anti-drift tables (M9a 内在张力, M9b 反例黑名单, M12 fallback tree) — Darwin gap #2: validator previously skipped these
+if (!isEngine) {
+	const tension = countListItems(src, /M9a|内在张力|inner tension|internal tension/i);
+	check('内在张力 (M9a) ≥3 tension pairs', tension.count >= 3, tension.found ? `found ${tension.count} items` : 'section missing');
+
+	const blacklist = countListItems(src, /M9b|反例黑名单|anti.?pattern blacklist/i);
+	check('反例黑名单 (M9b) ≥7 rows', blacklist.count >= 7, blacklist.found ? `found ${blacklist.count} rows` : 'section missing');
+
+	const fallback = countListItems(src, /M12|失败模式.*[Ff]allback|[Ff]allback\s*树/i);
+	check('失败模式Fallback树 (M12) ≥8 rows', fallback.count >= 8, fallback.found ? `found ${fallback.count} rows` : 'section missing');
+}
+
+// --- FIDELITY.md companion artifact (Darwin gap #3: ship-gate requires it but nothing checked)
+const fidelityPath = join(dir, 'FIDELITY.md');
+if (existsSync(fidelityPath)) {
+	const fm2 = readFileSync(fidelityPath, 'utf8');
+	const totalMatch = fm2.match(/(?:总分|total)[：:\s*]*\*{0,2}([0-9]+)\s*\*?\s*(?:\/|／|\sout\sof\s)\s*\*?\s*100/i);
+	check('FIDELITY.md total score present', !!totalMatch, totalMatch ? `=${totalMatch[1]}/100` : 'no /100 score found');
+	const qCount = (fm2.match(/(?:Q[1-5]|问题[1-5]|question\s*[1-5])/gi) || []).length;
+	check('FIDELITY.md ≥5 test questions', 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(fm2), 'add single-agent upper-bound caveat');
+} else if (!isEngine) {
+	check('FIDELITY.md companion present', false, 'no FIDELITY.md in skill dir');
+}
+
+// --- EXCAVATION-CHECKLIST.md (Phase 1 protocol: track + verify each part was really read)
+const checklistPath = join(dir, 'EXCAVATION-CHECKLIST.md');
+if (existsSync(checklistPath)) {
+	const cl = readFileSync(checklistPath, 'utf8');
+	// dangling rows: status ⬜ not-started or ⏳ reading left at ship time = silently skipped/forgotten
+	const dangling = (cl.match(/\|\s*[⬜⏳][^|]*\|/gu) || []).length;
+	check('checklist: no dangling ⬜/⏳ rows (every part resolved)', dangling === 0, dangling ? `${dangling} row(s) not-started/reading — resolve to ✅📄/⏭/🧠` : '');
+	// memory ratio: parse "memory-ratio: NN%" if declared
+	const ratioMatch = cl.match(/memory-ratio[:\s]*([0-9]+)\s*%/i);
+	if (ratioMatch) {
+		const ratio = parseInt(ratioMatch[1], 10);
+		check('checklist: 🧠 memory-ratio ≤30%', ratio <= 30, `declared ${ratio}% (>30% = recap, not distillation)`);
+	} else {
+		check('checklist: declares memory-ratio', false, 'add "🧠 memory-ratio: NN% (X/Y findings)" header line');
+	}
+	// proof-of-read present: at least one verbatim-quote-with-location cell (heuristic — a ✅ row should carry a quote)
+	const proofCells = (cl.match(/"[^"]{8,}"[^|]*/g) || []).length;
+	check('checklist: ≥1 proof-of-read (verbatim quote in a ✅ row)', proofCells >= 1, `${proofCells} quote cell(s) found`);
+} else if (!isEngine) {
+	check('EXCAVATION-CHECKLIST.md present', false, 'no excavation checklist — Phase 1 protocol requires one');
+}
+
+// --- DISTILLATION-PROCESS-CHECKLIST.md (whole-pipeline tracking + the 3-empty-rounds deep-dive gate)
+const procPath = join(dir, 'DISTILLATION-PROCESS-CHECKLIST.md');
+if (existsSync(procPath)) {
+	const pc = readFileSync(procPath, 'utf8');
+	// dangling phases: ⬜/⏳ left in the phase-progress table at ship = a phase skipped
+	const danglingPhases = (pc.match(/\|\s*[⬜⏳][^|]*\|/gu) || []).length;
+	check('process: no dangling ⬜/⏳ phases (every phase completed)', danglingPhases === 0, danglingPhases ? `${danglingPhases} phase(s) not done` : '');
+	// deep-dive round log present
+	check('process: deep-dive round log present', /round log|\| *Round.*New findings/i.test(pc), 'add the round-log table');
+	// 3-empty-rounds gate recorded (≥3 consecutive zero-new rounds before leaving a phase)
+	const gateFired = /gate fires|3 consecutive (empty|zero)|GATE FIRES/i.test(pc);
+	check('process: 3-empty-rounds gate recorded (≥3 zero-new rounds)', gateFired, 'record a round-log row marked gate-fired before declaring any research phase done');
+} else if (!isEngine) {
+	check('DISTILLATION-PROCESS-CHECKLIST.md present', false, 'no process checklist — every phase + the 3-round deep-dive gate must be tracked');
+}
+
+// --- Placeholders ---
+const foundPlaceholders = PLACEHOLDERS.filter((re) => re.test(src));
+if (!isEngine) check('no unresolved placeholder text', foundPlaceholders.length === 0,
+	foundPlaceholders.map((re) => src.match(re)?.[0]).filter(Boolean).join(', '));
+
+// --- Self-containment (F9): references/sources should not dangle outside the dir ---
+const refsDir = join(dir, 'references');
+if (!isEngine) check('self-contained: no external repo paths in body (e.g. 07-调研/)',
+	!/[\w/-]*调研与分析?\/|src\/|source\//i.test(src.replace(/```[\s\S]*?```/g, '')),
+	'body references paths outside skill dir');
+
+// --- Software-specific assertions (if target: software) ---
+if (/target:\s*software/i.test(fmText) || /code-dna|代码表达DNA|code expression/i.test(src)) {
+	check('[software] Code Expression-DNA section present', /代码表达DNA|Code Expression-DNA|code.?dna/i.test(src));
+	check('[software] toolchain matrix present', /toolchain|eslint|oxlint|biome|tsconfig/i.test(src));
+	check('[software] distilled_against commit anchor', hasFm('distilled_against') || /distilled_against/i.test(src));
+}
+
+// --- Report ---
+console.log(`\nvalidate-skill-structure: ${name}`);
+console.log(`path: ${skillPath}\n`);
+passes.forEach((l) => console.log(l));
+failures.forEach((l) => console.log(l));
+console.log(`\n${passes.length} pass, ${failures.length} fail — ${failures.length === 0 ? '✅ ALL-GREEN (may ship)' : '🔴 NOT READY (iterate Phase 2→3)'}${isEngine ? ' [engine mode — generated-skill checks skipped]' : ''}\n`);
+process.exit(failures.length === 0 ? 0 : 1);

package/skills/distill-software/BUILD-NOTES.md

@@ -0,0 +1,56 @@
+# distill-software — Build Notes
+
+Sibling of `distill-persona`, specialized for software. Inherits the base methodology (6 phases, Phase 2.6 extraction verification, F2' framework-answerable-edge fidelity, exhaustive-sweep mode + coverage manifest + diminishing-returns gate, self-correction meta-loop) — does NOT duplicate it; only specifies what's different for software.
+
+## Decision → source trace
+| Decision | From |
+|---|---|
+| 3 flavors (engineer persona / codebase conventions / domain expertise) | SOFTWARE-DISTILLATION-DEEP-DIVE §A |
+| Code-Expression-DNA 12-axis grid (measurable, not vibes) | SOFTWARE-DISTILLATION-DEEP-DIVE §C |
+| pi-langsrv-native research (symbol/call-graph) — the software differentiator vs nuwa's web-only | SOFTWARE-DISTILLATION-DEEP-DIVE §E + nuwa F1 (portability) |
+| `language` + `distilled_against` staleness anchors in frontmatter | nuwa review F2'/software — staleness is the #1 software honesty failure |
+| Phase 2.6 V1 strengthened (quirk-vs-principle flag) | SOFTWARE-DISTILLATION-DEEP-DIVE §J (overfit-to-quirk anti-pattern) |
+| F2' third category applied to version-recency ("API newer than distilled_against") | f2-experiment (validated n=3) |
+| `code_dna.py` wired INTO Agentic Protocol Step 2 (not orphaned) | nuwa mrbeast review F13 |
+| Tests-as-invariants + CI/lint-as-enforced-conventions + dep manifests (3 extra streams) | SOFTWARE-DISTILLATION-DEEP-DIVE §B |
+| 口癖 = lint `no-restricted-syntax` entries | SOFTWARE-DISTILLATION-DEEP-DIVE §C |
+| software-specific anti-patterns (8) | SOFTWARE-DISTILLATION-DEEP-DIVE §J |
+
+## Operational script — `scripts/code_dna.py`
+- Stdlib-only, Python 3.9+. Measures the code-Expression-DNA axes on a target file/dir → markdown report.
+- **Tested** on nuwa-skill Python scripts (mid-comments/loose-errors/typed/snake_case 79%) and on itself (terse/strict-errors/typed) — produces differentiated, sensible fingerprints.
+- Axes measured: naming distribution + prefix tally · function length (median/p90, Python) · comment density + why-vs-what ratio · error-handling pattern (raise/except/return-null/.ok) · type-strictness (typed vs any) · 8-axis style-tag grid.
+- **Wired into Agentic Protocol** (F13): Step 2 runs `code_dna.py` on collected target code, reads the report, applies mental models. Never orphaned.
+- Shares `scripts/fidelity_eval.py` with distill-persona for Phase 4.
+
+## Dogfood run — oh-my-pi (self-correction meta-loop fired)
+Ran distill-software on `oh-my-pi` (TypeScript Pi-toolkit, pnpm monorepo). Output: `~/source/my_pi/source/oh-my-pi-DISTILL/oh-my-pi-conventions.md` (8 triple-verified engineering models + code-DNA + tooling philosophy + honest boundaries). The run **exposed and fixed** skill gaps:
+1. **code_dna.py TS why-counter bug** — counted why-keywords on ALL lines, not just comments → why-ratio >100% (nonsense). Fixed (count within comment lines only).
+2. **🔴 Toolchain non-portability** — skill hardcoded `eslint.config.*`/`biome.json`; oh-my-pi uses **OXC (oxlint/oxfmt)**. The 口癖-mining command matched nothing. Fixed: generalized to a **toolchain matrix** (eslint · biome · **oxc** · deno · rustfmt) in SKILL.md (2 places) + code_dna.py. Added: tsconfig strict flags are often the real type-strictness DNA (mine them too).
+3. **Added 3 extra streams** (3 → 6): **release/shipping-pipeline** (release/publish/pre-commit scripts + changeset + turbo DAG — the most engineering-dense code), **risk/security-posture** (T0-T4 risk-tier + untrusted-data model — policy, not code), **agent-instruction governance** (meta-convention: how the repo changes its own AGENTS.md).
+4. **Extended existing streams**: test-infrastructure patterns (mock factories, source-alias testing, coverage thresholds), workspace orchestration (turbo DAG, workspace:*, package tiers), tool-philosophy rationale.
+5. **Added structural/testability DNA** to the code-DNA section — DI seams (factory `provider?`), `safeXxx` never-throw contract, `index-helpers` extraction-for-testability — invisible to static identifier counting but the most important conventions.
+**Net**: the skill is materially more complete after one real run. The meta-loop works as designed (real run → gaps → fix → re-run clean). code_dna.py re-tested on oh-my-pi: parses + produces correct toolchain-matrix 口癖 block.
+
+**Meta-loop #2 (sdk/pi-checkpoint sweep, closing coverage to 100%)**: the sdk sweep REFINED 5/8 models (no contradictions) and surfaced 2 more gaps → fixed: **+concurrency/coordination stream** (FS locks/stale-detection/heartbeat, **on-disk vs in-memory interop** — a module loaded as multiple copies across packages MUST coordinate on-disk) · **+platform-hardening stream** (Windows reserved names, rename/remove retry, path-safety) · **sharpened the Result model to a 3-tier spectrum** (`raw` / `locked*` may-throw / `safe*` never-throw+reason-coded — was wrongly collapsed to a binary) · added schema-version-literal pinning + mock-mirrors-decision-tree to structural-DNA. Total extra streams now **8** (was 3 → 6 → 8).
+
+**Completion (per self-defined milestone — all criteria met)**:
+1. ✅ Coverage 100% — every content-bearing part swept (docs/extensions/internal/scripts/**sdk**/.pi/themes/enforced-config/CHANGELOG/PR-template). Findings: `oh-my-pi-DISTILL/{oh-my-pi-conventions.md, 05-sdk-checkpoint.md}` + 4 batch research outputs.
+2. ✅ Triple-verification on all 8 models (recur across docs+code+enforced; generative; exclusive).
+3. ✅ Phase 2.6 V1-V4 (codebase-conventions, not persona-content; each changes a decision).
+4. ✅ Installable skill built: `oh-my-pi-DISTILL/oh-my-pi-conventions-SKILL.md` (loadable, staleness-anchored).
+5. ✅ Phase 4 fidelity (framework-answerable novel edge — "add a new pi-snapshot extension" — skill gives complete consistent guidance via all 8 models; can be agent-verified for full rigor).
+6. ✅ No HIGH skill-gaps blocking (meta-loop closed: toolchain matrix + 8 streams + Result-tier + structural-DNA).
+→ **oh-my-pi distillation COMPLETE.** Skill `distill-software` improved by 2 meta-loop rounds. Remaining (low) gaps noted: TS function-length needs LSP; per-batch research files 01-04 not persisted as separate files (captured in synthesis); schema-versioning + mock-quality could be promoted to named axes later.
+
+## Known gaps (honest)
+- **TS/JS function-body length not measured** (body-split unreliable for arrow funcs) — use LSP/tree-sitter for accurate TS length. Python length measured.
+- **Deep analysis only for Python + TS/JS**; other languages get naming + comment density only (generic fallback).
+- **口癖 (forbidden patterns) requires manual lint-config mining** — the script prints the `rg` command; it doesn't parse eslint/biome configs yet. (Could add a parser.)
+- **n=1 language per run** — multi-language monorepos need per-language passes (or `--lang` per dir).
+- **Not yet validated end-to-end on a real software distillation** (no example output skill exists, unlike distill-persona which dogfooded on the 3 repos). First real use will likely trigger the self-correction meta-loop.
+
+## Relationship / reuse
+- `distill-persona` = the base (person 6-stream + topic exhaustive-sweep + verification + F2' + meta-loop + 10 field models).
+- `distill-software` = the software specialization (this skill). Reuses the base's phases where silent; specializes sources/DNA/tooling/staleness.
+- A future `distill-software-pi-crew` specialization would pin pi-crew/git/pi-langsrv concretely + ship a per-codebase `_dna.py` derived from that codebase's models.