svharness 0.8.0

package/dist/wiki/repowikiStructureNormalize.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPOWIKI_MAX_TOP_SECTIONS = void 0;
+exports.comprehensiveOutlineNeedsStructureRetry = comprehensiveOutlineNeedsStructureRetry;
+exports.syncPageParentSectionsFromGroups = syncPageParentSectionsFromGroups;
+exports.patchWikiStructureSectionsAndParents = patchWikiStructureSectionsAndParents;
+exports.normalizeComprehensiveWikiStructure = normalizeComprehensiveWikiStructure;
+exports.structureRepairUserAppendix = structureRepairUserAppendix;
+const repowikiStructureNav_1 = require("./repowikiStructureNav");
+/** Top-level category folders under each `lang/` (inclusive cap). */
+exports.REPOWIKI_MAX_TOP_SECTIONS = 7;
+function escapeXmlText(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeXmlAttr(s) {
+    return escapeXmlText(s).replace(/"/g, "&quot;");
+}
+function comprehensiveOutlineNeedsStructureRetry(comprehensive, structureXml, pages) {
+    if (!comprehensive || pages.length <= 1)
+        return false;
+    return (0, repowikiStructureNav_1.parseSectionGroups)(structureXml).length < 2;
+}
+function capSectionCount(groups, max) {
+    if (groups.length <= max)
+        return groups.map((g) => ({ ...g, pageIds: [...g.pageIds] }));
+    const head = groups.slice(0, max - 1).map((g) => ({ ...g, pageIds: [...g.pageIds] }));
+    const tail = groups.slice(max - 1);
+    const merged = {
+        id: tail[0].id,
+        title: tail[0].title,
+        pageIds: tail.flatMap((t) => t.pageIds),
+    };
+    return [...head, merged];
+}
+function dedupeSectionPageRefsAcross(groups) {
+    const claimed = new Set();
+    for (const g of groups) {
+        const next = [];
+        const seenLocal = new Set();
+        for (const pid of g.pageIds) {
+            if (seenLocal.has(pid))
+                continue;
+            seenLocal.add(pid);
+            if (claimed.has(pid))
+                continue;
+            claimed.add(pid);
+            next.push(pid);
+        }
+        g.pageIds = next;
+    }
+}
+function assignOrphanPagesRoundRobin(groups, pageIds) {
+    if (groups.length === 0)
+        return;
+    const inSections = new Set(groups.flatMap((g) => g.pageIds));
+    const orphans = pageIds.filter((id) => !inSections.has(id));
+    if (!orphans.length)
+        return;
+    for (let i = 0; i < orphans.length; i++) {
+        groups[i % groups.length].pageIds.push(orphans[i]);
+    }
+}
+function syntheticSectionsForPages(pages, langFolder) {
+    const n = pages.length;
+    const numSections = Math.min(exports.REPOWIKI_MAX_TOP_SECTIONS, Math.max(2, Math.ceil(n / 4)));
+    const sections = [];
+    for (let s = 0; s < numSections; s++) {
+        const title = langFolder === "zh" ? `主题 ${s + 1}` : `Topic ${s + 1}`;
+        sections.push({ id: `auto-part-${s + 1}`, title, pageIds: [] });
+    }
+    for (let i = 0; i < pages.length; i++) {
+        sections[i % numSections].pageIds.push(pages[i].id);
+    }
+    return sections;
+}
+function syncPageParentSectionsFromGroups(pages, groups) {
+    const pageToSection = new Map();
+    for (const g of groups) {
+        for (const pid of g.pageIds) {
+            if (!pageToSection.has(pid))
+                pageToSection.set(pid, g.id);
+        }
+    }
+    for (const p of pages) {
+        const sid = pageToSection.get(p.id);
+        if (sid)
+            p.parentSection = sid;
+    }
+}
+function serializeSectionsElement(groups) {
+    const lines = ["  <sections>"];
+    for (const g of groups) {
+        lines.push(`    <section id="${escapeXmlAttr(g.id)}">`);
+        lines.push(`      <title>${escapeXmlText(g.title)}</title>`);
+        lines.push(`      <pages>`);
+        for (const pid of g.pageIds) {
+            lines.push(`        <page_ref>${escapeXmlText(pid)}</page_ref>`);
+        }
+        lines.push(`      </pages>`);
+        lines.push(`      <subsections/>`);
+        lines.push(`    </section>`);
+    }
+    lines.push(`  </sections>`);
+    return lines.join("\n");
+}
+function upsertPageParentSection(xml, pageId, sectionId) {
+    const escId = pageId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pageRe = new RegExp(`<page\\s+([^>]*\\bid\\s*=\\s*"${escId}"[^>]*)>([\\s\\S]*?)</page>`, "i");
+    return xml.replace(pageRe, (_full, attrs, inner) => {
+        const tagOpen = `<page ${attrs}>`;
+        let body = inner;
+        if (/<parent_section>/i.test(body)) {
+            body = body.replace(/<parent_section>\s*[\s\S]*?\s*<\/parent_section>/i, `<parent_section>${escapeXmlText(sectionId)}</parent_section>`);
+        }
+        else {
+            const rfClose = body.search(/<\/relevant_files>/i);
+            if (rfClose !== -1) {
+                const end = body.indexOf(">", rfClose) + 1;
+                body =
+                    body.slice(0, end) +
+                        `\n      <parent_section>${escapeXmlText(sectionId)}</parent_section>` +
+                        body.slice(end);
+            }
+            else {
+                body = `${body}\n      <parent_section>${escapeXmlText(sectionId)}</parent_section>`;
+            }
+        }
+        return `${tagOpen}${body}</page>`;
+    });
+}
+function patchWikiStructureSectionsAndParents(xml, groups, pages) {
+    let out = xml;
+    const serialized = serializeSectionsElement(groups);
+    if (/<sections>\s*[\s\S]*?<\/sections>/i.test(out)) {
+        out = out.replace(/<sections>\s*[\s\S]*?<\/sections>/i, serialized);
+    }
+    else {
+        const descClose = out.match(/<\/description>\s*/i);
+        if (descClose && descClose.index !== undefined) {
+            const insertAt = descClose.index + descClose[0].length;
+            out = `${out.slice(0, insertAt)}\n${serialized}\n${out.slice(insertAt)}`;
+        }
+        else {
+            const titleClose = out.match(/<\/title>\s*/i);
+            if (titleClose && titleClose.index !== undefined) {
+                const insertAt = titleClose.index + titleClose[0].length;
+                out = `${out.slice(0, insertAt)}\n${serialized}\n${out.slice(insertAt)}`;
+            }
+        }
+    }
+    for (const p of pages) {
+        if (p.parentSection) {
+            out = upsertPageParentSection(out, p.id, p.parentSection);
+        }
+    }
+    return out;
+}
+function normalizeComprehensiveWikiStructure(opts) {
+    const { comprehensive, langFolder, xml } = opts;
+    const pages = opts.pages;
+    if (!comprehensive) {
+        return { xml, pages, groups: (0, repowikiStructureNav_1.parseSectionGroups)(xml) };
+    }
+    if (pages.length === 0) {
+        return { xml, pages, groups: (0, repowikiStructureNav_1.parseSectionGroups)(xml) };
+    }
+    if (pages.length === 1) {
+        let groups = capSectionCount((0, repowikiStructureNav_1.parseSectionGroups)(xml), exports.REPOWIKI_MAX_TOP_SECTIONS);
+        dedupeSectionPageRefsAcross(groups);
+        assignOrphanPagesRoundRobin(groups, pages.map((p) => p.id));
+        const pid = pages[0].id;
+        const pick = groups[0] ?? { id: "section-overview", title: langFolder === "zh" ? "概述" : "Overview", pageIds: [] };
+        groups = [{ id: pick.id, title: pick.title, pageIds: [pid] }];
+        syncPageParentSectionsFromGroups(pages, groups);
+        return { xml: patchWikiStructureSectionsAndParents(xml, groups, pages), pages, groups };
+    }
+    let groups = capSectionCount((0, repowikiStructureNav_1.parseSectionGroups)(xml), exports.REPOWIKI_MAX_TOP_SECTIONS);
+    dedupeSectionPageRefsAcross(groups);
+    assignOrphanPagesRoundRobin(groups, pages.map((p) => p.id));
+    if (groups.length < 2) {
+        groups = syntheticSectionsForPages(pages, langFolder);
+    }
+    syncPageParentSectionsFromGroups(pages, groups);
+    return {
+        xml: patchWikiStructureSectionsAndParents(xml, groups, pages),
+        pages,
+        groups,
+    };
+}
+function structureRepairUserAppendix(previousRaw, langFolder) {
+    const preview = previousRaw.slice(0, 8_000);
+    if (langFolder === "zh") {
+        return `
+
+【修订要求 — 上一条纲要无效】上一次的 wiki_structure **小节数量不足**（少于 2 个顶层 <section>，或缺失 <sections>），但需要 **2 至 7 个** 顶层小节。请重新输出 **完整** 的 wiki_structure XML（不要用"见上文"省略）。
+
+硬性要求：
+- 在 <sections> 下提供 **至少 2 个、至多 7 个** 平级 <section>，每个有唯一 id。
+- **禁止** 把所有 <page> 放进同一个小节；将 ≤20 页分配到多个小节。
+- 每个 <page> 必须有 <parent_section>，其值必须等于拥有该页的 section 的 id（且该 section 的 <page_ref> 引用此页）。
+- 仍须符合此前的模板（先 <sections>，再完整 <pages> 块等）。
+
+上一次输出摘要（仅供参考，请修正而非照抄）：
+${preview}`;
+    }
+    return `
+
+【Revision required — previous outline invalid】The last wiki_structure had **too few** top-level <section> blocks under <sections> (or <sections> was missing). Return a **complete new** wiki_structure XML with **between 2 and 7** sibling <section> elements.
+
+Hard requirements:
+- Provide **at least 2 and at most 7** <section> elements under <sections>, each with a **unique** id.
+- **Do not** place every <page> in a single section; distribute up to 20 pages across multiple sections.
+- Every <page> MUST include <parent_section> equal to the owning section id (that section MUST list the page via <page_ref>).
+- Follow the same template as before (<sections> first, then a full <pages> block).
+
+Previous output (for reference only — fix it, do not copy):
+${preview}`;
+}

package/dist/wiki/wikiStructureXml.js

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPOWIKI_MAX_PAGES = void 0;
+exports.decodeXmlEntities = decodeXmlEntities;
+exports.extractWikiStructureXml = extractWikiStructureXml;
+exports.extractSectionsInnerXml = extractSectionsInnerXml;
+exports.parsePageRefsFromSections = parsePageRefsFromSections;
+exports.parseWikiPages = parseWikiPages;
+exports.sanitizeWikiOutlineId = sanitizeWikiOutlineId;
+exports.slugifyFileStem = slugifyFileStem;
+exports.slugifyWikiTitle = slugifyWikiTitle;
+exports.allocateWikiFileStems = allocateWikiFileStems;
+exports.allocateWikiFileStemsWithTargetPaths = allocateWikiFileStemsWithTargetPaths;
+/**
+ * Decode XML/HTML entities in text extracted from tags (parser does not use a real XML decoder).
+ * Runs until stable so double-escaped values (e.g. `&`) become a single `&`.
+ */
+function decodeXmlEntities(s) {
+    if (!s)
+        return s;
+    let prev = "";
+    let out = s;
+    for (let i = 0; i < 8 && out !== prev; i++) {
+        prev = out;
+        out = out
+            .replace(/&amp;/g, "&")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&apos;/g, "'")
+            .replace(/&#(\d+);/g, (_, n) => {
+            const cp = parseInt(n, 10);
+            return Number.isFinite(cp) ? String.fromCodePoint(cp) : _;
+        })
+            .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => {
+            const cp = parseInt(h, 16);
+            return Number.isFinite(cp) ? String.fromCodePoint(cp) : _;
+        });
+    }
+    return out;
+}
+/** Accept closed document or truncated model output (missing closing </wiki_structure>). */
+function extractWikiStructureXml(fullText) {
+    const closed = fullText.match(/<wiki_structure>[\s\S]*?<\/wiki_structure>/im);
+    if (closed)
+        return closed[0];
+    const open = fullText.match(/<wiki_structure>[\s\S]*/im);
+    return open?.[0] ?? "";
+}
+function textContent(inner, tag) {
+    const re = new RegExp(`<${tag}>[\\s\\S]*?<\\/${tag}>`, "i");
+    const m = inner.match(re);
+    if (!m)
+        return "";
+    const open = `<${tag}>`;
+    const close = `</${tag}>`;
+    const s = m[0];
+    const start = s.toLowerCase().indexOf(open.toLowerCase());
+    const end = s.toLowerCase().lastIndexOf(close.toLowerCase());
+    if (start === -1 || end === -1)
+        return "";
+    const body = s.slice(start + open.length, end).trim();
+    const stripped = body.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    return decodeXmlEntities(stripped);
+}
+function getAttr(inner, attr) {
+    const re = new RegExp(`${attr}="([^"]*)"`, "i");
+    const m = inner.match(re);
+    return decodeXmlEntities(m?.[1]?.trim() ?? "");
+}
+function collectFilePaths(block) {
+    const out = [];
+    const re = /<file_path>([\s\S]*?)<\/file_path>/gi;
+    let x;
+    while ((x = re.exec(block)) !== null) {
+        const raw = x[1]?.trim().replace(/\s+/g, "") ?? "";
+        const p = decodeXmlEntities(raw);
+        if (p)
+            out.push(p.replace(/\\/g, "/"));
+    }
+    return out;
+}
+/**
+ * `<sections>...</sections>` inner XML; supports truncation (missing `</sections>`).
+ * `page_ref` extraction is scoped here so stray tags elsewhere do not pollute.
+ */
+function extractSectionsInnerXml(wikiStructureXml) {
+    const closed = wikiStructureXml.match(/<sections>([\s\S]*?)<\/sections>/i);
+    if (closed)
+        return closed[1].trim();
+    const open = wikiStructureXml.match(/<sections>([\s\S]*)/i);
+    return open?.[1]?.trim() ?? "";
+}
+/**
+ * All `<page_ref>` ids under `<sections>`, deduped, first-seen order.
+ */
+function parsePageRefsFromSections(wikiStructureXml) {
+    const inner = extractSectionsInnerXml(wikiStructureXml);
+    if (!inner)
+        return [];
+    const re = /<page_ref>([\s\S]*?)<\/page_ref>/gi;
+    const seen = new Set();
+    const out = [];
+    let m;
+    while ((m = re.exec(inner)) !== null) {
+        const raw = decodeXmlEntities((m[1] ?? "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim());
+        const id = sanitizeId(raw);
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+function humanizeIdFallback(id) {
+    const s = id.replace(/[-_.]+/g, " ").trim();
+    if (!s)
+        return id;
+    return s.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function makeSyntheticPage(id) {
+    return {
+        id,
+        title: humanizeIdFallback(id) || id,
+        description: "",
+        relevantFiles: [],
+    };
+}
+/**
+ * Collect `<page id="...">` openings even when the tag was cut off before `>` (truncated model output).
+ * Skips ids already present in `alreadyHave` (full `<page>...</page>` parses).
+ */
+function salvagePartialPageOpeningIds(wikiStructureXml, alreadyHave) {
+    const re = /<page\b[^>]*?\bid\s*=\s*"([^"]+)"/gi;
+    const seen = new Set();
+    const out = [];
+    let m;
+    while ((m = re.exec(wikiStructureXml)) !== null) {
+        const id = sanitizeId((m[1] ?? "").trim());
+        if (!id || alreadyHave.has(id) || seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * Full `<page id="...">...</page>` entries only.
+ */
+function parseFullWikiPages(wikiStructureXml) {
+    const pageRe = /<page\s+([^>]*?)>([\s\S]*?)<\/page>/gi;
+    const list = [];
+    let pm;
+    while ((pm = pageRe.exec(wikiStructureXml)) !== null) {
+        const openAttrs = pm[1] ?? "";
+        const inner = pm[2] ?? "";
+        const id = getAttr(openAttrs, "id");
+        if (!id)
+            continue;
+        const title = textContent(inner, "title");
+        const description = textContent(inner, "description");
+        const parentSection = textContent(inner, "parent_section").trim();
+        const files = collectFilePaths(inner);
+        list.push({
+            id: sanitizeId(id),
+            title: title || id,
+            description,
+            relevantFiles: files.slice(0, 25),
+            ...(parentSection ? { parentSection } : {}),
+        });
+    }
+    return dedupeById(list);
+}
+/**
+ * Find all `<page id="...">...</page>` in the full structure, then merge in outline-only data when the
+ * outer `<pages>` block is missing or truncated: `<page_ref>` under `<sections>` and optional salvage
+ * of cut-off `<page id="...">` openings.
+ */
+function parseWikiPages(wikiStructureXml) {
+    if (!wikiStructureXml)
+        return [];
+    const fullList = parseFullWikiPages(wikiStructureXml);
+    const mergedIds = new Set(fullList.map((p) => p.id));
+    const refIds = parsePageRefsFromSections(wikiStructureXml);
+    const salvageIds = salvagePartialPageOpeningIds(wikiStructureXml, mergedIds);
+    const extra = [];
+    for (const id of refIds) {
+        if (mergedIds.has(id))
+            continue;
+        mergedIds.add(id);
+        extra.push(makeSyntheticPage(id));
+    }
+    for (const id of salvageIds) {
+        if (mergedIds.has(id))
+            continue;
+        mergedIds.add(id);
+        extra.push(makeSyntheticPage(id));
+    }
+    return [...fullList, ...extra];
+}
+function dedupeById(pages) {
+    const seen = new Set();
+    const out = [];
+    for (const p of pages) {
+        if (seen.has(p.id))
+            continue;
+        seen.add(p.id);
+        out.push(p);
+    }
+    return out;
+}
+function sanitizeWikiOutlineId(id) {
+    return id.replace(/[^a-zA-Z0-9_.-]/g, "-").slice(0, 80);
+}
+function sanitizeId(id) {
+    return sanitizeWikiOutlineId(id);
+}
+function slugifyFileStem(pageId) {
+    return pageId.replace(/[^a-zA-Z0-9_.-]/g, "-") || "page";
+}
+/**
+ * Stem from outline / page title: filesystem-safe, keeps letters (incl. CJK), digits,
+ * hyphen, underscore, dot; drops path/control chars and trims trailing dot/space (Windows).
+ */
+function slugifyWikiTitle(title) {
+    let s = title.trim();
+    if (!s)
+        return "";
+    s = s.replace(/[\x00-\x1f<>:"/\\|?*]/g, "");
+    s = s.replace(/\s+/g, "-");
+    s = s.replace(/-+/g, "-");
+    s = s.replace(/^[-.]+|[-.]+$/g, "");
+    if (!s)
+        return "";
+    if (s.length > 120)
+        s = s.slice(0, 120).replace(/[-.]+$/g, "");
+    s = s.replace(/[. ]+$/g, "").replace(/^[. ]+/g, "");
+    return s || "";
+}
+/**
+ * Unique `.md` file stem per page id for a language folder. Title-derived when possible.
+ */
+function allocateWikiFileStems(pages) {
+    const used = new Set();
+    const map = new Map();
+    for (const p of pages) {
+        const base = slugifyWikiTitle(p.title) || slugifyFileStem(p.id);
+        let stem = base;
+        if (used.has(stem)) {
+            const withId = `${base}-${slugifyFileStem(p.id)}`;
+            if (!used.has(withId))
+                stem = withId;
+            else {
+                let n = 2;
+                while (used.has(`${base}-${n}`))
+                    n++;
+                stem = `${base}-${n}`;
+            }
+        }
+        used.add(stem);
+        map.set(p.id, stem);
+    }
+    return map;
+}
+function shortPageIdSuffix(pageId) {
+    const s = slugifyFileStem(pageId).replace(/^page-?/i, "");
+    return (s || slugifyFileStem(pageId)).slice(-8) || "p";
+}
+/**
+ * Resolve final `.md` stems per page given section folder segments, so paths do not collide with
+ * unrelated files on disk (e.g. orphans from an old wiki-title folder layout) or other page ids.
+ */
+function allocateWikiFileStemsWithTargetPaths(pages, bucketByPageId, pathToOwnerPageId, physicalExists) {
+    const baseById = allocateWikiFileStems(pages);
+    const out = new Map();
+    /** rel posix path -> page id assigned in this pass */
+    const claimed = new Map();
+    const conflicts = (rel, pageId) => {
+        const metaOwner = pathToOwnerPageId.get(rel);
+        const stepOwner = claimed.get(rel);
+        const ex = physicalExists(rel);
+        if (stepOwner && stepOwner !== pageId)
+            return true;
+        if (metaOwner === pageId)
+            return false;
+        if (metaOwner && metaOwner !== pageId)
+            return true;
+        if (ex)
+            return true;
+        return false;
+    };
+    for (const p of pages) {
+        const bucket = bucketByPageId.get(p.id) ?? "wiki";
+        const baseStem = baseById.get(p.id);
+        let stem = baseStem;
+        let attempt = 0;
+        while (true) {
+            const rel = `${bucket}/${stem}.md`.replace(/\\/g, "/");
+            if (!conflicts(rel, p.id)) {
+                claimed.set(rel, p.id);
+                out.set(p.id, stem);
+                break;
+            }
+            attempt++;
+            if (attempt === 1) {
+                stem = `${baseStem}-${shortPageIdSuffix(p.id)}`;
+            }
+            else {
+                stem = `${baseStem}-${attempt + 1}`;
+            }
+        }
+    }
+    return out;
+}
+/** Max wiki pages per index run (structure prompt + truncation). */
+exports.REPOWIKI_MAX_PAGES = 20;

package/dist/wiki/wikiTasksWriter.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Writes a `TASKS.md` inside `<wikiBase>/` based on an outline computed by
+ * `runRepowikiOutlineOnly`. The file is consumed by the downstream
+ * harness-build-skill-knowledge-builder skill which fills page content iteratively.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeWikiTasks = writeWikiTasks;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+/**
+ * Group pages by their `sectionFolder` bucket, preserving first-seen order.
+ */
+function groupBySection(pages) {
+    const buckets = new Map();
+    for (const p of pages) {
+        const list = buckets.get(p.sectionFolder);
+        if (list)
+            list.push(p);
+        else
+            buckets.set(p.sectionFolder, [p]);
+    }
+    return [...buckets.entries()].map(([folder, list]) => ({ folder, pages: list }));
+}
+function renderTasksMarkdown(input) {
+    const { outline } = input;
+    const lines = [];
+    const groups = groupBySection(outline.pages);
+    lines.push(`# Baseline Wiki Tasks — ${input.projectName}`);
+    lines.push("");
+    lines.push(`Generated by svharness v${input.cliVersion} on ${input.generatedAtIso}`);
+    lines.push(`Source tree: \`${input.sourceRootRel}\``);
+    lines.push(`Outline model: \`${input.model}\``);
+    lines.push(`Outline XML: \`./structure.xml\``);
+    lines.push(`Primary language: \`${outline.primaryLang}\``);
+    lines.push("");
+    lines.push("> 下游 agent（harness-build-skill-wiki-writer）按本清单逐页生成 wiki：");
+    lines.push("> 逐条完成 Pages 列表中的任务，每完成一页把 `[ ]` 改为 `[x]`。");
+    lines.push("> 每页应产出 Markdown 文件到对应 `Output` 路径，内容严格基于基线源码。");
+    lines.push("");
+    lines.push("> **源码引用规范（强制，与 --generate-wiki 产出口径保持一致）**：");
+    lines.push("> 所有源码链接必须指向 `assets/baseline/code/` 下的路径，允许两种写法（可混用）：");
+    lines.push("> 1. 行内链接：`[Foo.java:10-30](../../../assets/baseline/code/<repo-relative>/Foo.java#L10-L30)`");
+    lines.push("> 2. Sources 行：`Sources: <repo-relative>/Foo.java:10-30, <repo-relative>/Bar.kt:5-8`");
+    lines.push("> `<repo-relative>` 指**相对 `assets/baseline/code/` 的路径**，既非仓库原始绝对路径，");
+    lines.push("> 也非 wiki md 文件的相对路径。行号使用 `start-end`（闭区间）。");
+    lines.push("");
+    lines.push("## Sections");
+    for (const g of groups) {
+        const ids = g.pages.map((p) => p.id).join(", ");
+        lines.push(`- \`${g.folder}\`: ${ids}`);
+    }
+    lines.push("");
+    lines.push(`## Pages (${outline.pages.length})`);
+    lines.push("");
+    for (const p of outline.pages) {
+        lines.push(`### [ ] ${p.id} — ${p.title}`);
+        lines.push(`- Output: \`${p.relativeOutputPath}\``);
+        lines.push(`- Section: \`${p.sectionFolder}\``);
+        if (p.parentSection) {
+            lines.push(`- Parent section id: \`${p.parentSection}\``);
+        }
+        if (p.description) {
+            lines.push(`- Description: ${p.description}`);
+        }
+        if (p.relevantFiles.length > 0) {
+            lines.push(`- Relevant files:`);
+            for (const f of p.relevantFiles) {
+                lines.push(`  - \`${f}\``);
+            }
+        }
+        else {
+            lines.push(`- Relevant files: _(none declared — agent should infer from tree)_`);
+        }
+        lines.push(`- Acceptance:`);
+        lines.push(`  - 文件存在且非空`);
+        lines.push(`  - 首段含页面标题（H1 与 title 一致）`);
+        lines.push(`  - 至少引用 1 个 Relevant files 中的源码片段或路径`);
+        lines.push(`  - Sources 行或行内链接的路径必须定位到 \`assets/baseline/code/\` 下的真实文件`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Write `TASKS.md` under the wiki base directory and return the absolute path.
+ */
+async function writeWikiTasks(input) {
+    const wikiBase = path.join(input.targetRoot, input.wikiRelPath.replace(/^[/\\]+/, ""));
+    await fs.mkdir(wikiBase, { recursive: true });
+    const out = path.join(wikiBase, "TASKS.md");
+    const md = renderTasksMarkdown(input);
+    await fs.writeFile(out, md, "utf8");
+    return out;
+}