pi-crew 0.9.47 → 0.9.49

package/skills/distill-persona/scripts/fidelity_eval.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+fidelity_eval.py — Phase 4 automation + reproducibility test for distilled skills.
+
+Closes two gaps from the distill-persona build:
+  1. Automates Phase 4 fidelity validation (known-stance + FRAMEWORK-ANSWERABLE novel
+     edge + blind independent scorer). The novel edge MUST be framework-answerable
+     (validated at n=3: fact-demanding edges give false passes via refusal vocab).
+  2. Adds a reproducibility test (distill the same persona twice, diff the mental-model
+     sets; flag if overlap < 60%).
+
+Runtime-agnostic by design: the deterministic parts (test-spec validation, scorecard
+parsing, reproducibility diff, grading) live here; the LLM calls (answerer + scorer)
+are emitted as ready-to-dispatch prompts that THIS runtime's subagent mechanism runs
+(pi-crew `Agent`, Claude Code subagents, etc.). We never hardcode an LLM API — there is
+no key here, and runtimes vary.
+
+Stdlib only. Python 3.9+.
+
+Usage:
+  python3 fidelity_eval.py validate <test-spec.md>     # check spec structure
+  python3 fidelity_eval.py runbook <skill-dir> <spec>  # emit answerer+scorer prompts
+  python3 fidelity_eval.py parse <score.md>            # extract 5-dim numbers
+  python3 fidelity_eval.py repro <skillA.md> <skillB.md>  # diff mental models (Jaccard)
+
+Test-spec format (markdown):
+  ## known
+  1. <question>
+  2. <question>
+  3. <question>
+  ## edge            # exactly ONE, must be framework-answerable
+  <question>
+  ## ground-truth
+  <the persona's real documented public stances — for the blind scorer only>
+  ## edge-note
+  <one line: why this edge is framework-answerable + that the persona never addressed it>
+"""
+import argparse
+import re
+import sys
+from pathlib import Path
+
+# --- grading thresholds (from nuwa fidelity-scorecard, + the F2' edge-honesty gate) ---
+GRADE_A = 85          # ship
+GRADE_B = 70          # acceptable with flagged weak spots
+EDGE_HONESTY_SHIP = 14   # /20 — a skill that fails edge-honesty is NOT ship-ready even if total is high
+REPRO_FLOOR = 0.60    # mental-model Jaccard overlap below this flags non-reproducible distillation
+
+DIMS = [
+    ("stance_consistency", 30),
+    ("style_recognizability", 20),
+    ("edge_honesty", 20),
+    ("source_transparency", 15),
+    ("structural_completeness", 15),
+]
+
+
+# --------------------------------------------------------------------------- spec validation
+def parse_spec(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8")
+    sections = {}
+    cur = None
+    for line in text.splitlines():
+        m = re.match(r"^##\s+(\S.*)$", line)
+        if m:
+            cur = m.group(1).strip().lower().replace("-", "_").replace(" ", "_")
+            sections[cur] = []
+        elif cur:
+            sections[cur].append(line)
+    return {k: "\n".join(v).strip() for k, v in sections.items()}
+
+
+def validate_spec(path: Path) -> int:
+    s = parse_spec(path)
+    problems = []
+    if "known" not in s:
+        problems.append("missing '## known' section")
+    else:
+        known = [ln for ln in s["known"].splitlines() if re.match(r"^\s*\d+\.", ln.strip())]
+        if len(known) != 3:
+            problems.append(f"'## known' must have exactly 3 numbered questions, found {len(known)}")
+    if "edge" not in s or not s["edge"].strip():
+        problems.append("missing '## edge' section (exactly ONE novel edge question)")
+    if "ground_truth" not in s or len(s["ground_truth"]) < 50:
+        problems.append("missing or too-short '## ground-truth' (the blind scorer's reference)")
+    if "edge_note" not in s or "framework" not in s["edge_note"].lower():
+        problems.append("'## edge-note' must state why the edge is FRAMEWORK-answerable "
+                        "(fact-demanding edges give false passes — see f2-experiment/validation-conclusion.md)")
+    if problems:
+        print("❌ INVALID test spec:")
+        for p in problems:
+            print(f"  - {p}")
+        return 1
+    print("✅ test spec OK (3 known + 1 framework-answerable edge + ground-truth + edge-note)")
+    print(f"   edge question: {s['edge'].splitlines()[0][:90]}")
+    return 0
+
+
+# --------------------------------------------------------------------------- runbook emission
+RUNBOOK_HEADER = """# Fidelity runbook for {skill}
+
+Runtime-agnostic. Run the two steps below via THIS runtime's subagent mechanism, in order.
+Step 1 (answerer) MUST finish before Step 2 (scorer). The scorer is BLIND (ground-truth only,
+NO skill-file access) — F2 was refuted (skill-file access does not inflate scores) but the blind
+condition keeps the score independent of the author's design intent.
+
+## Step 1 — answerer (skill-only, NO web)
+Allowlist these files ONLY: <skill-dir>/SKILL.md + <skill-dir>/references/research/*
+Answer the 3 known + 1 edge question in character per the skill's Agentic Protocol.
+For the edge question, honor the skill's F2' third-category rule (flag framework-derived
+inference as inference, not established stance). Write answers to answers.md.
+
+## Step 2 — blind scorer (ground-truth ONLY, NO skill file)
+Allowlist: answers.md + rubric.md + ground-truth (from the test spec). Score 5 dims.
+Write scorecard to score-B.md.
+
+## Questions
+{questions}
+
+## Ground-truth (for blind scorer)
+{ground_truth}
+"""
+
+
+def emit_runbook(skill_dir: Path, spec_path: Path) -> int:
+    s = parse_spec(spec_path)
+    questions = "### known\n" + s.get("known", "") + "\n\n### edge (FRAMEWORK-answerable)\n" + s.get("edge", "")
+    out = RUNBOOK_HEADER.format(
+        skill=skill_dir.name,
+        questions=questions,
+        ground_truth=s.get("ground_truth", "(none)"),
+    )
+    dest = skill_dir / "fidelity-runbook.md"
+    dest.write_text(out, encoding="utf-8")
+    print(f"✅ wrote {dest}")
+    print("   next: dispatch Step 1 (answerer) then Step 2 (blind scorer) via your runtime.")
+    return 0
+
+
+# --------------------------------------------------------------------------- scorecard parsing
+def parse_score(path: Path) -> dict:
+    """Extract the 5 dimension scores from a scorer's markdown scorecard."""
+    text = path.read_text(encoding="utf-8")
+    found = {}
+    for name, _ in DIMS:
+        # match e.g. "| 1 Stance consistency | 26/30 |" or "| 3 Edge honesty | **6/20** |"
+        # [\s*]* tolerates bold (**..**) wrappers around the score.
+        pat = re.compile(rf"\|[^|]*{re.escape(name.split('_')[0])}[^|]*\|[\s*]*(\d+)\s*/\s*(\d+)", re.I)
+        m = pat.search(text)
+        if m:
+            found[name] = int(m.group(1))
+    total_m = re.search(r"\*\*TOTAL\*\*\s*\|\s*(\d+)\s*/\s*100", text, re.I)
+    if not total_m:
+        total_m = re.search(r"(\d+)\s*/\s*100", text)
+    total = int(total_m.group(1)) if total_m else sum(found.values())
+    return {"dims": found, "total": total}
+
+
+def report_score(path: Path) -> int:
+    r = parse_score(path)
+    if not r["dims"]:
+        print("❌ could not parse any dimension scores from", path)
+        return 1
+    print(f"Scores from {path}:")
+    for name, _max in DIMS:
+        v = r["dims"].get(name)
+        print(f"  {name:28} {v}/{_max}" if v is not None else f"  {name:28} (not found)")
+    print(f"  {'TOTAL':28} {r['total']}/100")
+    grade = grade_for(r["total"], r["dims"].get("edge_honesty", 0))
+    print(f"  grade: {grade}")
+    return 0
+
+
+def grade_for(total: int, edge: int) -> str:
+    if edge < EDGE_HONESTY_SHIP:
+        return f"NO-SHIP (edge-honesty {edge}/20 < {EDGE_HONESTY_SHIP} — fails the F2' gate regardless of total)"
+    if total >= GRADE_A:
+        return f"A (≥{GRADE_A}) — ship"
+    if total >= GRADE_B:
+        return f"B (≥{GRADE_B}) — acceptable with flagged weak spots"
+    return f"C (<{GRADE_B}) — re-distill"
+
+
+# --------------------------------------------------------------------------- reproducibility diff
+def extract_models(skill_md: Path) -> set:
+    """Extract mental-model names from a SKILL.md (### 模型N: / ### Model N: / ### N. Name)."""
+    text = skill_md.read_text(encoding="utf-8")
+    names = set()
+    # match model headings in either language; tolerate arabic OR Chinese numerals.
+    for m in re.finditer(r"^#{2,4}\s+(?:模型\s*[0-9一二三四五六七八九十]+\s*[:：]?\s*|Model\s*\d+\s*[:：]\s*|\d+\.\s*)(.+)$", text, re.M):
+        name = m.group(1).strip().split("(")[0].strip().split("（")[0].strip()
+        # drop parenthetical english + trailing junk
+        name = re.sub(r"\s+", " ", name)
+        if 2 <= len(name) <= 60:
+            names.add(name.lower())
+    return names
+
+
+def repro(a: Path, b: Path) -> int:
+    ma, mb = extract_models(a), extract_models(b)
+    if not ma or not mb:
+        print(f"❌ could not extract models (A={len(ma)}, B={len(mb)}). "
+              "Ensure SKILL.md uses '### 模型N: Name' / '### Model N: Name' headings.")
+        return 1
+    inter = ma & mb
+    union = ma | mb
+    jaccard = len(inter) / len(union) if union else 0.0
+    name_overlap = len(inter) / min(len(ma), len(mb)) if min(len(ma), len(mb)) else 0.0
+    print(f"Skill A models ({len(ma)}): {sorted(ma)}")
+    print(f"Skill B models ({len(mb)}): {sorted(mb)}")
+    print(f"intersection ({len(inter)}): {sorted(inter)}")
+    print(f"Jaccard overlap: {jaccard:.0%}   name-overlap/min: {name_overlap:.0%}")
+    if name_overlap < REPRO_FLOOR:
+        print(f"⚠️  NON-REPRODUCIBLE: overlap {name_overlap:.0%} < {REPRO_FLOOR:.0%} floor — "
+              "two distillations of the same persona diverge too much. Investigate Phase 2 subjectivity.")
+        return 2
+    print(f"✅ reproducible (overlap {name_overlap:.0%} ≥ {REPRO_FLOOR:.0%})")
+    return 0
+
+
+# --------------------------------------------------------------------------- CLI
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("validate", help="validate a test-spec.md structure").add_argument("spec")
+    sub.add_parser("runbook", help="emit answerer+scorer prompts for a skill").add_argument("skill_dir")
+    [a.add_argument("spec") for a in [sub.choices["runbook"]]]
+    sub.add_parser("parse", help="extract 5-dim scores from a scorer's markdown").add_argument("score")
+    r = sub.add_parser("repro", help="diff mental models of two SKILL.md (reproducibility test)")
+    r.add_argument("skillA"); r.add_argument("skillB")
+    args = ap.parse_args()
+    if args.cmd == "validate":
+        return validate_spec(Path(args.spec))
+    if args.cmd == "runbook":
+        return emit_runbook(Path(args.skill_dir), Path(args.spec))
+    if args.cmd == "parse":
+        return report_score(Path(args.score))
+    if args.cmd == "repro":
+        return repro(Path(args.skillA), Path(args.skillB))
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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.