@vibecodetown/mcp-server 2.1.0

package/build/tools/vibe_pm/create_work_order.js

@@ -0,0 +1,271 @@
+// adapters/mcp-ts/src/tools/vibe_pm/create_work_order.ts
+// vibe_pm.create_work_order - Issue work order for implementation
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { runEngine, invalidateEngineCache } from "../../engine.js";
+import { safeJsonParse } from "../../cli.js";
+import { resolveRunId, resolveProjectId, getRunContext, readRunState, invalidateStateCache, getRunsDir } from "./context.js";
+import { generateWorkOrderText, transformAskQueueText } from "./pm_language.js";
+import { validateToolInput } from "../../security/input-validator.js";
+import { checkGate, formatViolations } from "../../control_plane/gate.js";
+import { ensureModulesForWorkOrder, readFileIfExists } from "./modules/ensure.js";
+import { ClinicBridgeFileSchema } from "../../generated/clinic_bridge_file.js";
+import { loadPromptDensity } from "./intent/prompt_density.js";
+import { runKceRetrieve, runKceStatus } from "./kce/preflight.js";
+import { updateKceDocUsage } from "./kce/doc_usage.js";
+/**
+ * vibe_pm.create_work_order - Issue work order for implementation
+ *
+ * Internal mapping:
+ *   → spec-high clinic-bridge <run_id> --write --format yaml
+ *   → paste_to_agent text generation
+ */
+export async function createWorkOrder(input) {
+    const basePath = process.cwd();
+    // Security: Validate input first
+    validateToolInput({
+        project_id: input.project_id,
+        additional_instructions: input.additional_instructions,
+    });
+    // Resolve run_id
+    const { run_id } = resolveRunId(input.project_id, basePath);
+    const project_id = resolveProjectId(run_id, basePath);
+    const context = getRunContext(run_id, basePath);
+    const runState = readRunState(run_id, basePath);
+    const promptDensityMode = loadPromptDensity(getRunsDir(basePath), run_id)?.mode ?? "mode_0";
+    // Generate clinic bridge
+    const bridgeResult = await runEngine("spec-high", ["--root", "engines/spec_high", "clinic-bridge", run_id, "--write", "--format", "yaml"], { timeoutMs: 120_000 });
+    if (bridgeResult.code !== 0) {
+        throw new Error(`작업 지시서 생성 실패: ${bridgeResult.stderr || "알 수 없는 오류"}`);
+    }
+    // Generate intent documents from resolved decision cards
+    try {
+        await runEngine("spec-high", ["--root", "engines/spec_high", "intent-generate", run_id, "--write", "--force"], { timeoutMs: 60_000 });
+    }
+    catch {
+        // Intent generation is optional - continue if it fails
+    }
+    // Invalidate caches after state mutation
+    invalidateEngineCache(new RegExp(run_id));
+    invalidateStateCache(run_id, basePath);
+    // Get bridge path from response or use default
+    let bridgePath = `engines/spec_high/runs/${run_id}/handoff/clinic_bridge.yaml`;
+    const bridgeParsed = safeJsonParse(bridgeResult.stdout);
+    if (bridgeParsed.ok && bridgeParsed.value.bridge_path) {
+        bridgePath = bridgeParsed.value.bridge_path;
+    }
+    // Read and parse bridge file
+    const fullBridgePath = path.isAbsolute(bridgePath)
+        ? bridgePath
+        : path.join(basePath, bridgePath);
+    let bridgeData = {};
+    try {
+        if (fs.existsSync(fullBridgePath)) {
+            const content = fs.readFileSync(fullBridgePath, "utf-8");
+            bridgeData = fullBridgePath.endsWith(".json") ? JSON.parse(content) : parseYaml(content);
+            const validated = ClinicBridgeFileSchema.safeParse(bridgeData);
+            if (!validated.success) {
+                throw new Error("작업 지시서 원본 파일 형식이 예상과 다릅니다. 업데이트 후 다시 시도해주세요.");
+            }
+            bridgeData = validated.data;
+        }
+    }
+    catch (e) {
+        // Fail closed (contract drift): do not issue a work order from an unknown/unsafe file shape.
+        throw e instanceof Error
+            ? e
+            : new Error("작업 지시서 원본 파일을 읽을 수 없습니다. 업데이트 후 다시 시도해주세요.");
+    }
+    // Extract data from bridge
+    const projectName = project_id;
+    const mode = runState?.mode ?? "balanced";
+    const headline = "프로젝트 구현";
+    const dg = bridgeData?.decision_guard;
+    const legacyScope = bridgeData?.scope;
+    const scopeInclude = Array.isArray(dg?.allow_paths)
+        ? dg.allow_paths
+        : Array.isArray(legacyScope?.include)
+            ? legacyScope.include
+            : [];
+    const scopeExclude = Array.isArray(dg?.deny_paths)
+        ? dg.deny_paths
+        : Array.isArray(legacyScope?.exclude)
+            ? legacyScope.exclude
+            : [];
+    const doNotTouch = Array.isArray(dg?.read_only_paths)
+        ? dg.read_only_paths
+        : Array.isArray(bridgeData?.do_not_touch)
+            ? bridgeData.do_not_touch
+            : [];
+    const verifyCriteria = Array.isArray(bridgeData?.verification?.required)
+        ? bridgeData.verification.required
+            .map((c) => (typeof c?.cmd === "string" ? c.cmd.trim() : ""))
+            .filter(Boolean)
+        : Array.isArray(bridgeData?.verify_criteria)
+            ? bridgeData.verify_criteria.filter((s) => typeof s === "string" && s.trim())
+            : [];
+    // Generate paste_to_agent text
+    let pasteToAgent = generateWorkOrderText({
+        projectName,
+        mode,
+        headline,
+        includes: scopeInclude,
+        excludes: scopeExclude,
+        doNotTouch,
+        verifyCriteria
+    });
+    if (input.additional_instructions && input.additional_instructions.trim()) {
+        pasteToAgent += `\n\n[추가 지시]\n- ${input.additional_instructions.trim()}\n`;
+    }
+    // Ensure versioned modules (Research/Skills/Planning) exist and link them to output
+    const modules = ensureModulesForWorkOrder({ basePath, runId: run_id });
+    // Append SKILLS_PACK / PLAN_STEPS into paste_to_agent (still user-friendly, no engine terms)
+    const skillsPack = readFileIfExists(modules.skill_bundle_prompt_path);
+    if (skillsPack) {
+        pasteToAgent += `\n\n[SKILLS_PACK]\n${skillsPack.trim()}\n`;
+    }
+    const planRaw = readFileIfExists(modules.planning.path);
+    if (planRaw) {
+        const planSummary = formatPlanSteps(planRaw);
+        if (planSummary) {
+            pasteToAgent += `\n\n[PLAN_STEPS]\n${planSummary.trim()}\n`;
+        }
+    }
+    // Attach KCE references (best-effort; unless prompt density explicitly disables it)
+    if (promptDensityMode !== "mode_2") {
+        const query = (input.additional_instructions ?? "").trim() ||
+            `${projectName}\n${headline}\n${verifyCriteria.slice(0, 3).join("\n")}`.trim();
+        try {
+            // Free policy: only inject when KCE is READY. Never auto-heal (no sync) from core tools.
+            const status = await runKceStatus();
+            if (status.readiness_state !== "READY") {
+                throw new Error("KCE_NOT_READY");
+            }
+            const out = await runKceRetrieve({ query, maxItems: 3, limit: 10, maxTotalChars: 2000, maxChunkChars: 800 });
+            const refsRaw = out.context_block.trim();
+            if (refsRaw) {
+                const sanitized = transformAskQueueText(refsRaw);
+                const clipped = sanitized.length > 2000 ? `${sanitized.slice(0, 2000).trimEnd()}…` : sanitized;
+                pasteToAgent += `\n\n[참고 문헌]\n${clipped}\n`;
+            }
+            // Evidence (best-effort): record what was injected
+            try {
+                const kceDir = path.join(context.runs_path, "kce");
+                fs.mkdirSync(kceDir, { recursive: true });
+                fs.writeFileSync(path.join(kceDir, "kb_query_evidence.json"), JSON.stringify({
+                    version: "kce_query_evidence.v1",
+                    created_at: new Date().toISOString(),
+                    query,
+                    hits: out.hits,
+                    kce_status: status
+                }, null, 2) + "\n", "utf-8");
+            }
+            catch {
+                // ignore
+            }
+            // Evidence (best-effort): record doc usage for deterministic recency signals.
+            try {
+                const injectedDocs = (out.hits ?? [])
+                    .map((h) => (typeof h.path === "string" ? h.path : ""))
+                    .map((p) => p.replace(/\\\\/g, "/"))
+                    .filter((p) => p.endsWith(".md") || p.endsWith(".mdx"));
+                const referencedEntities = injectedDocs
+                    .filter((p) => p.startsWith("entities/") && p.endsWith(".entity.json"))
+                    .map((p) => path.basename(p, ".entity.json"))
+                    .filter(Boolean);
+                updateKceDocUsage({ basePath, run_id, injected_docs: injectedDocs, referenced_entities: referencedEntities });
+            }
+            catch {
+                // ignore
+            }
+        }
+        catch {
+            // Best-effort: never block work order issuance when local memory is unavailable.
+        }
+    }
+    // Build work order
+    const workOrder = {
+        headline,
+        scope: {
+            include: scopeInclude,
+            exclude: scopeExclude
+        },
+        do_not_touch: doNotTouch,
+        verify_criteria: verifyCriteria,
+        paste_to_agent: pasteToAgent
+    };
+    // Run System Design Gate check
+    // Convert to WorkOrderV1 format for gate validation
+    const workOrderV1 = {
+        intent: `${headline}: ${pasteToAgent.slice(0, 100)}...`,
+        scope: {
+            include: scopeInclude.length > 0 ? scopeInclude : ["src/**/*"],
+            exclude: scopeExclude
+        },
+        tool_style: "EXEC",
+        idempotency_key: `${run_id}-${Date.now()}`
+    };
+    try {
+        const gateResult = await checkGate(workOrderV1, { repoRoot: basePath });
+        if (!gateResult.allowed && gateResult.result) {
+            const violations = formatViolations(gateResult.result);
+            throw new Error(`작업 지시서가 Gate 검사를 통과하지 못했습니다:\n${violations}`);
+        }
+        if (gateResult.error) {
+            // Log but don't block - gate check failure shouldn't prevent work order issuance
+            console.warn(`Gate check warning: ${gateResult.error}`);
+        }
+    }
+    catch (gateError) {
+        // If gate throws (not just returns blocked), log warning but continue
+        // This ensures backwards compatibility when Python CLI is not available
+        if (gateError instanceof Error && gateError.message.includes("Gate 검사")) {
+            throw gateError; // Re-throw actual gate violations
+        }
+        console.warn(`Gate check skipped: ${gateError instanceof Error ? gateError.message : String(gateError)}`);
+    }
+    return {
+        project_id,
+        run_id,
+        work_order: workOrder,
+        paths: {
+            bridge_path: bridgePath,
+            intent_dir: `engines/spec_high/runs/${run_id}/intent`
+        },
+        modules: {
+            research: modules.research,
+            skills: modules.skills,
+            planning: modules.planning
+        },
+        next_action: {
+            tool: "vibe_pm.inspect_code",
+            reason: "구현 후 검수를 요청하세요",
+            when: "after_implementation"
+        }
+    };
+}
+function formatPlanSteps(planJsonText) {
+    try {
+        const doc = JSON.parse(planJsonText);
+        const steps = doc.plan ?? [];
+        if (!Array.isArray(steps) || steps.length === 0)
+            return null;
+        const lines = [];
+        for (const s of steps) {
+            const n = s.step ?? 0;
+            const title = (s.title ?? "").trim();
+            const v = Array.isArray(s.verification) ? s.verification.filter(Boolean) : [];
+            if (title) {
+                lines.push(`${n}. ${title}`);
+            }
+            if (v.length > 0) {
+                lines.push(`   - 확인: ${v[0]}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    catch {
+        return null;
+    }
+}

package/build/tools/vibe_pm/doc_status_gate.js

@@ -0,0 +1,370 @@
+// adapters/mcp-ts/src/tools/vibe_pm/doc_status_gate.ts
+// Internal: policy-based doc status tagging + safe archiving (no delete).
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { minimatch } from "minimatch";
+function readJsonIfExists(p) {
+    try {
+        if (!fs.existsSync(p))
+            return null;
+        return JSON.parse(fs.readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function defaultPolicy() {
+    return {
+        version: "doc_status_policy.v1",
+        scope: { include_globs: ["docs/**/*.md", "docs/**/*.mdx"], exclude_globs: ["docs/archive/**"] },
+        signals: {
+            entity_link: { enabled: true, weight: 50, link_markers: ["<!-- ENTITY:", "entities/", "entity_id:"] },
+            evidence_link: { enabled: true, weight: 25, evidence_markers: ["runs/", "fixtures/", "schemas/"] },
+            recent_usage: { enabled: true, lookback_days: 30, weight: 25 }
+        },
+        classification: {
+            ACTIVE: { min_score: 70, required_any: ["entity_link", "evidence_link"] },
+            DORMANT: { min_score: 35, required_any: ["entity_link", "evidence_link"] },
+            ORPHAN: { max_score: 34, required_any: [], required_none: ["entity_link"] }
+        },
+        actions: {
+            tag_header: {
+                enabled: true,
+                format: "<!-- DOC_STATUS: {status} | score={score} | reason={reason} | last_seen={last_seen} -->"
+            },
+            archive: {
+                enabled: false,
+                only_status: ["DORMANT", "ORPHAN"],
+                grace_days: 14,
+                archive_root: "docs/archive",
+                archive_prefix: "{yyyy}-{mm}-{dd}__",
+                write_tombstone: true,
+                tombstone_mode: "overwrite_source",
+                tombstone_content: "# Moved\n\nThis document has been archived to: [{archive_path}]({archive_relative_path})\n\nReason: {reason}\nDate: {yyyy}-{mm}-{dd}\n"
+            }
+        }
+    };
+}
+function nowParts(now) {
+    const yyyy = String(now.getFullYear()).padStart(4, "0");
+    const mm = String(now.getMonth() + 1).padStart(2, "0");
+    const dd = String(now.getDate()).padStart(2, "0");
+    return { yyyy, mm, dd };
+}
+function renderTemplate(tpl, vars) {
+    let out = tpl;
+    for (const [k, v] of Object.entries(vars)) {
+        out = out.split(`{${k}}`).join(v);
+    }
+    return out;
+}
+function prependArchiveObsoleteMarker(body) {
+    const marker = "<!-- OBSOLETE: This document is archived and no longer authoritative -->\n" +
+        "<!-- Reference: docs/SSOT.md is the ultimate authority -->\n\n" +
+        "> **ARCHIVED** - 이 문서는 더 이상 기준이 아닙니다.\n" +
+        "> 기준: docs/SSOT.md\n\n" +
+        "---\n\n";
+    return marker + body;
+}
+function ensureArchiveMarker(absPath) {
+    const raw = fs.readFileSync(absPath, "utf-8");
+    const head = raw.split("\n").slice(0, 12).join("\n");
+    const hasObsolete = /OBSOLETE/i.test(head);
+    const hasRef = head.includes("docs/SSOT.md");
+    if (hasObsolete && hasRef)
+        return;
+    fs.writeFileSync(absPath, prependArchiveObsoleteMarker(raw), "utf-8");
+}
+function upsertStatusHeader(absPath, headerLine) {
+    const raw = fs.readFileSync(absPath, "utf-8");
+    const lines = raw.split("\n");
+    const first = lines[0] ?? "";
+    const isExisting = first.trim().startsWith("<!-- DOC_STATUS:");
+    const next = isExisting ? [headerLine, ...lines.slice(1)] : [headerLine, ...lines];
+    const out = next.join("\n");
+    if (out === raw)
+        return { changed: false, existed: isExisting };
+    fs.writeFileSync(absPath, out, "utf-8");
+    return { changed: true, existed: isExisting };
+}
+function collectDocsUnder(basePath) {
+    const docsRoot = path.join(basePath, "docs");
+    if (!fs.existsSync(docsRoot))
+        return [];
+    const out = [];
+    const stack = [docsRoot];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        let entries = [];
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const abs = path.join(cur, e.name);
+            if (e.isDirectory()) {
+                // Hard safety: skip common heavy dirs even if policy is wrong.
+                if (e.name === "node_modules" || e.name === ".git" || e.name === "target" || e.name === ".vibe")
+                    continue;
+                stack.push(abs);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            if (!abs.toLowerCase().endsWith(".md") && !abs.toLowerCase().endsWith(".mdx"))
+                continue;
+            out.push(abs);
+        }
+    }
+    return out;
+}
+function matchesAny(relPosix, globs) {
+    for (const g of globs) {
+        if (minimatch(relPosix, g, { dot: true }))
+            return true;
+    }
+    return false;
+}
+function readHeadBlock(absPath, maxLines) {
+    try {
+        const raw = fs.readFileSync(absPath, "utf-8");
+        return raw.split("\n").slice(0, maxLines).join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+function addRunDirsFromRoot(runsRoot, out) {
+    try {
+        if (!fs.existsSync(runsRoot))
+            return;
+        const entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+        for (const e of entries) {
+            if (!e.isDirectory())
+                continue;
+            const abs = path.join(runsRoot, e.name);
+            if (e.name === "examples" || e.name === "fixtures") {
+                addRunDirsFromRoot(abs, out);
+                continue;
+            }
+            out.push(abs);
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+function collectRecentUsedDocs(basePath, lookbackDays, now) {
+    const out = new Set();
+    const lookbackMs = Math.max(0, lookbackDays) * 24 * 60 * 60 * 1000;
+    const cutoff = now.getTime() - lookbackMs;
+    const runDirs = [];
+    addRunDirsFromRoot(path.join(basePath, "runs"), runDirs);
+    addRunDirsFromRoot(path.join(basePath, "engines", "spec_high", "runs"), runDirs);
+    for (const runDir of runDirs) {
+        const p = path.join(runDir, "kce", "kce_doc_usage.json");
+        try {
+            if (!fs.existsSync(p))
+                continue;
+            const st = fs.statSync(p);
+            if (st.mtime.getTime() < cutoff)
+                continue;
+            const doc = readJsonIfExists(p);
+            const touched = Array.isArray(doc?.touched_docs) ? doc.touched_docs : [];
+            const injected = Array.isArray(doc?.injected_docs) ? doc.injected_docs : [];
+            for (const v of [...touched, ...injected]) {
+                if (typeof v !== "string")
+                    continue;
+                const rel = v.replace(/\\\\/g, "/").trim();
+                if (rel)
+                    out.add(rel);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return out;
+}
+function classifyDoc(args) {
+    const { policy, absPath, relPosix, now, touchedNow, recentUsedDocs } = args;
+    const head = readHeadBlock(absPath, 80);
+    const signals = {
+        entity_link: false,
+        evidence_link: false,
+        recent_usage: false
+    };
+    if (policy.signals.entity_link.enabled) {
+        const markers = policy.signals.entity_link.link_markers ?? [];
+        signals.entity_link = markers.some((m) => m && head.includes(m));
+    }
+    if (policy.signals.evidence_link.enabled) {
+        const markers = policy.signals.evidence_link.evidence_markers ?? [];
+        signals.evidence_link = markers.some((m) => m && head.includes(m));
+    }
+    if (policy.signals.recent_usage.enabled) {
+        const lookbackMs = policy.signals.recent_usage.lookback_days * 24 * 60 * 60 * 1000;
+        let recent = false;
+        if (touchedNow.has(relPosix)) {
+            recent = true;
+        }
+        else if (recentUsedDocs.has(relPosix)) {
+            recent = true;
+        }
+        else {
+            try {
+                const mtime = fs.statSync(absPath).mtime.getTime();
+                recent = now.getTime() - mtime <= lookbackMs;
+            }
+            catch {
+                recent = false;
+            }
+        }
+        signals.recent_usage = recent;
+    }
+    const score = (signals.entity_link ? policy.signals.entity_link.weight : 0) +
+        (signals.evidence_link ? policy.signals.evidence_link.weight : 0) +
+        (signals.recent_usage ? policy.signals.recent_usage.weight : 0);
+    const active = policy.classification.ACTIVE;
+    const dormant = policy.classification.DORMANT;
+    const orphan = policy.classification.ORPHAN;
+    const any = (keys) => keys.length === 0 || keys.some((k) => signals[k] === true);
+    const none = (keys) => keys.length === 0 || keys.every((k) => signals[k] !== true);
+    let status = "ORPHAN";
+    if (score >= active.min_score && any(active.required_any))
+        status = "ACTIVE";
+    else if (score >= dormant.min_score && any(dormant.required_any))
+        status = "DORMANT";
+    else if (orphan.required_none && !none(orphan.required_none))
+        status = "DORMANT";
+    else
+        status = "ORPHAN";
+    const reason = Object.entries(signals)
+        .filter(([, v]) => v)
+        .map(([k]) => k)
+        .join(",");
+    const lastSeen = touchedNow.has(relPosix) || recentUsedDocs.has(relPosix) ? now.toISOString() : "";
+    return { status, score, reason: reason || "none", lastSeen };
+}
+export function runDocStatusTriage(args) {
+    const now = args.now ?? new Date();
+    const policyPath = path.join(args.basePath, "schemas", "doc_status_policy.v1.json");
+    const loaded = readJsonIfExists(policyPath);
+    const policy = loaded ?? defaultPolicy();
+    const include = policy.scope.include_globs ?? ["docs/**/*.md"];
+    const exclude = policy.scope.exclude_globs ?? [];
+    const touchedNow = new Set((args.touched_paths ?? []).map((p) => p.replace(/\\\\/g, "/")));
+    const recentUsedDocs = policy.signals.recent_usage.enabled
+        ? collectRecentUsedDocs(args.basePath, policy.signals.recent_usage.lookback_days, now)
+        : new Set();
+    const tagged = [];
+    const archived = [];
+    const tombstoned = [];
+    const hadStatusTagBefore = new Set();
+    let active = 0;
+    let dormant = 0;
+    let orphan = 0;
+    const candidates = collectDocsUnder(args.basePath);
+    for (const abs of candidates) {
+        const rel = path.relative(args.basePath, abs).replace(/\\\\/g, "/");
+        if (!matchesAny(rel, include))
+            continue;
+        if (matchesAny(rel, exclude))
+            continue;
+        const { status, score, reason, lastSeen } = classifyDoc({
+            relPosix: rel,
+            absPath: abs,
+            policy,
+            now,
+            touchedNow,
+            recentUsedDocs
+        });
+        if (status === "ACTIVE")
+            active += 1;
+        else if (status === "DORMANT")
+            dormant += 1;
+        else
+            orphan += 1;
+        if (policy.actions.tag_header.enabled) {
+            const header = renderTemplate(policy.actions.tag_header.format, {
+                status,
+                score: String(score),
+                reason,
+                last_seen: lastSeen || "-"
+            });
+            try {
+                const res = upsertStatusHeader(abs, header);
+                if (res.existed)
+                    hadStatusTagBefore.add(rel);
+                if (res.changed)
+                    tagged.push(rel);
+            }
+            catch {
+                // ignore
+            }
+        }
+        // Archive is intentionally conservative; v1 uses grace_days only with mtime heuristic.
+        if (policy.actions.archive.enabled && policy.actions.archive.only_status.includes(status)) {
+            // Safety: do not archive a doc the same run it gets tagged the first time.
+            // This prevents mass moves on first enable and keeps the pipeline idempotent.
+            if (!hadStatusTagBefore.has(rel))
+                continue;
+            const graceMs = policy.actions.archive.grace_days * 24 * 60 * 60 * 1000;
+            let eligible = false;
+            try {
+                const mtime = fs.statSync(abs).mtime.getTime();
+                eligible = now.getTime() - mtime >= graceMs;
+            }
+            catch {
+                eligible = false;
+            }
+            if (!eligible)
+                continue;
+            const { yyyy, mm, dd } = nowParts(now);
+            const archiveRootAbs = path.join(args.basePath, policy.actions.archive.archive_root);
+            const prefix = renderTemplate(policy.actions.archive.archive_prefix, { yyyy, mm, dd });
+            const fileName = path.basename(abs);
+            const archiveName = `${prefix}${fileName}`;
+            const archiveAbs = path.join(archiveRootAbs, archiveName);
+            try {
+                fs.mkdirSync(path.dirname(archiveAbs), { recursive: true });
+                fs.renameSync(abs, archiveAbs);
+                ensureArchiveMarker(archiveAbs);
+                archived.push(path.relative(args.basePath, archiveAbs).replace(/\\\\/g, "/"));
+                if (policy.actions.archive.write_tombstone) {
+                    const relArchiveFromRepo = path.relative(args.basePath, archiveAbs).replace(/\\\\/g, "/");
+                    const relFromSourceDir = path
+                        .relative(path.dirname(abs), archiveAbs)
+                        .replace(/\\\\/g, "/");
+                    const tombTpl = policy.actions.archive.tombstone_content ??
+                        policy.actions.archive.tombstone_format ??
+                        "# Moved\n\nThis document has been archived.\n";
+                    const tomb = renderTemplate(tombTpl, {
+                        yyyy,
+                        mm,
+                        dd,
+                        status,
+                        reason,
+                        path: rel,
+                        archive_path: relArchiveFromRepo,
+                        archive_relative_path: relFromSourceDir
+                    });
+                    fs.mkdirSync(path.dirname(abs), { recursive: true });
+                    fs.writeFileSync(abs, tomb + "\n", "utf-8");
+                    tombstoned.push(rel);
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return {
+        tagged,
+        archived,
+        tombstoned,
+        summary: { active, dormant, orphan }
+    };
+}