Skip to content

GodModeAI2025/SkillSafeWerkstatt / maintain-llm-wiki

maintain-llm-wiki

Unverified

Create, maintain, inventory, migrate, recover, quality-review, optionally clean, release, or export an evidence-linked SkillSafeWerkstatt Markdown wiki. Use whenever the user wants to initialize or extend this wiki, ingest documents as Markdown, curate claims, clusters or concepts, clean metadata, restore files, record who reviewed which pages, resolve a OneDrive or SharePoint conflict copy, publish a release, or export a frozen read-only knowledge skill or an Open Knowledge Format bundle in Claude Code, Claude Cowork, or Codex.

FileKindSize
SKILL.mdskill md57.2 KB
assets/graph-template.htmlother27.8 KB
assets/knowledge-skill/SKILL.template.mdmarkdown35.6 KB
assets/knowledge-skill/assess_quality.pyscript1.5 KB
assets/knowledge-skill/identity_status.pyscript5.9 KB
assets/knowledge-skill/search_knowledge.pyscript4.5 KB
assets/knowledge-skill/verify_knowledge.pyscript4.8 KB
assets/page-template.htmlother7.4 KB
evals/evals.jsonconfig32.6 KB
references/adapted-vault-standards.mdmarkdown3.3 KB
references/frontmatter-operations.mdmarkdown9.8 KB
references/wiki-contract.mdmarkdown73.0 KB
scripts/adopt_directory.pyscript13.2 KB
scripts/apply_identity.pyscript3.1 KB
scripts/bm25.pyscript8.2 KB
scripts/build_graph.pyscript27.0 KB
scripts/claim_id.pyscript1.9 KB
scripts/describe_actions.pyscript13.2 KB
scripts/design_contract.pyscript217 B
scripts/export_okf_bundle.pyscript17.9 KB
scripts/export_wiki_skill.pyscript23.7 KB
scripts/findability_questions.pyscript17.6 KB
scripts/freshness.pyscript3.6 KB
scripts/frontmatter_actions.pyscript26.1 KB
scripts/frontmatter_contract.pyscript10.0 KB
scripts/identity_contract.pyscript15.2 KB
scripts/init_wiki.pyscript18.2 KB
scripts/initialize_wiki.pyscript12.2 KB
scripts/inventory_wiki.pyscript6.7 KB
scripts/lint_wiki.pyscript56.0 KB
scripts/move_wiki_page.pyscript6.7 KB
scripts/navigation.pyscript11.0 KB
scripts/okf_contract.pyscript14.3 KB
scripts/page_batch.pyscript11.4 KB
scripts/plan_identity.pyscript2.2 KB
scripts/plan_language_migration.pyscript4.9 KB
scripts/portable_io.pyscript3.3 KB
scripts/quality_core.pyscript15.9 KB
scripts/record_quality_review.pyscript3.4 KB
scripts/register_source.pyscript12.2 KB
scripts/release_wiki.pyscript15.9 KB
scripts/report_okf.pyscript3.8 KB
scripts/resolve_conflict_copy.pyscript11.0 KB
scripts/restore_wiki.pyscript16.1 KB
scripts/run_locked.pyscript2.2 KB
scripts/search_core.pyscript221.1 KB
scripts/secret_screen.pyscript4.1 KB
scripts/snapshot_wiki.pyscript6.7 KB
scripts/source_coverage.pyscript22.8 KB
scripts/sync_artifacts.pyscript14.2 KB
scripts/trust_contract.pyscript5.2 KB
scripts/validate_extraction.pyscript5.0 KB
scripts/verify_pages.pyscript9.1 KB
scripts/verify_release.pyscript12.1 KB
scripts/wiki_filters.pyscript6.6 KB
scripts/wiki_lock.pyscript59.2 KB
scripts/wordforms.pyscript56.0 KB

scripts/export_okf_bundle.py

View on GitHub
#!/usr/bin/env python3
"""Export one verified release as an Open Knowledge Format v0.2 bundle.

The export is read-only with respect to the wiki and writes only into a
separately chosen destination. It is deliberately lossy: OKF has no equivalent
for claim-level evidence, the release manifest, snapshots, the confirmed
identity, or controlled concept worlds. Every bundle therefore carries a README
that names what did not come with it, so nobody mistakes the export for the
wiki.

Nothing is invented. A recommended field the wiki does not hold is left out and
reported, never filled with a guess.
"""

from __future__ import annotations

import argparse
import json
import re
import shutil
import sys
from pathlib import Path, PurePosixPath
from typing import Any

# Siblings are imported from this folder even where the interpreter leaves it
# off sys.path: python -I, python -P, PYTHONSAFEPATH=1.
_SCRIPT_DIR = str(Path(__file__).resolve().parent)
if _SCRIPT_DIR not in sys.path:
    sys.path.insert(0, _SCRIPT_DIR)

import okf_contract
import trust_contract
from frontmatter_contract import FrontmatterError, parse_document
from verify_release import verify_snapshot


BUNDLE_FORMAT = "lmwiki-okf-export/1"
WIKILINK = re.compile(r"\[\[([^\]]+)\]\]")


def yaml_scalar(value: Any) -> str:
    """Render one scalar for OKF frontmatter, quoting conservatively."""
    if isinstance(value, bool):
        return "true" if value else "false"
    if isinstance(value, (int, float)):
        return str(value)
    text = str(value)
    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
    return f'"{escaped}"'


def render_frontmatter(data: dict[str, Any]) -> str:
    """Render the OKF frontmatter, including the nested forms OKF expects."""
    lines = ["---"]
    for key, value in data.items():
        if value in (None, "", [], {}):
            continue
        if isinstance(value, dict):
            inline = ", ".join(f"{name}: {yaml_scalar(item)}" for name, item in value.items())
            lines.append(f"{key}: {{ {inline} }}")
        elif isinstance(value, list):
            lines.append(f"{key}:")
            for item in value:
                if isinstance(item, dict):
                    first = True
                    for name, inner in item.items():
                        prefix = "  - " if first else "    "
                        lines.append(f"{prefix}{name}: {yaml_scalar(inner)}")
                        first = False
                else:
                    lines.append(f"  - {yaml_scalar(item)}")
        else:
            lines.append(f"{key}: {yaml_scalar(value)}")
    lines.append("---")
    return "\n".join(lines) + "\n"


def bundle_relative_link(raw: str) -> str:
    """Rewrite one wikilink into an OKF bundle-relative link."""
    target, _, label = raw.partition("|")
    target = target.split("#", 1)[0].strip().removesuffix(".md").lstrip("./")
    text = label.strip() or PurePosixPath(target).name
    return f"[{text}](/{target}.md)"


def convert_body(body: str) -> str:
    """Convert wikilinks to Markdown links and strip claim markers.

    The visible claim text is kept because it is the maintained statement. The
    machine-readable evidence around it is dropped, which is the single largest
    thing an OKF bundle cannot carry.
    """
    without_claims = re.sub(
        r"<!--\s*claim\s*\n.*?-->\s*(.*?)\s*<!--\s*/claim\s*-->",
        lambda match: match.group(1),
        body,
        flags=re.DOTALL | re.IGNORECASE,
    )
    return WIKILINK.sub(lambda match: bundle_relative_link(match.group(1)), without_claims)


def load_registry(path: Path) -> dict[str, dict[str, Any]]:
    registry: dict[str, dict[str, Any]] = {}
    if not path.is_file():
        return registry
    for line in path.read_text(encoding="utf-8").splitlines():
        if not line.strip():
            continue
        try:
            record = json.loads(line)
        except json.JSONDecodeError:
            continue
        if isinstance(record, dict) and isinstance(record.get("source_id"), str):
            registry[record["source_id"]] = record
    return registry


def convert_page(
    data: dict[str, Any],
    registry: dict[str, dict[str, Any]],
) -> tuple[dict[str, Any], list[str]]:
    """Map one wiki page onto OKF frontmatter, reporting what was left out."""
    omitted: list[str] = []
    okf: dict[str, Any] = {"type": str(data.get("type") or "Concept")}

    for field in ("title", "description"):
        value = data.get(field)
        if isinstance(value, str) and value.strip():
            okf[field] = value
        else:
            omitted.append(field)

    tags = data.get("tags")
    if isinstance(tags, list) and tags:
        okf["tags"] = [str(tag) for tag in tags]
    else:
        omitted.append("tags")

    okf["status"] = okf_contract.okf_status(data.get("status"))
    note = okf_contract.status_note(data.get("status"))
    expiry = data.get("stale_after")
    if isinstance(expiry, str) and expiry.strip():
        okf["stale_after"] = expiry.strip()

    generated = okf_contract.actor_record(
        data.get(trust_contract.GENERATED_BY), data.get(trust_contract.GENERATED_AT)
    )
    if generated:
        okf["generated"] = generated
    verified = okf_contract.actor_record(
        data.get(trust_contract.VERIFIED_BY), data.get(trust_contract.VERIFIED_AT)
    )
    if verified:
        okf["verified"] = verified

    sources = okf_contract.source_records(data.get("sources"), registry)
    if sources:
        okf["sources"] = sources

    # `resource` identifies the underlying asset. The wiki holds no such URI for
    # a curated page, so it is reported as missing rather than fabricated.
    omitted.append("resource")
    return okf, ([note] if note else []) + [f"missing recommended field: {field}" for field in omitted]



def convert_source(record: dict[str, Any], body: str) -> tuple[dict[str, Any], list[str]]:
    """Map one registered source extraction onto an OKF concept.

    A bundle whose pages cite sources it does not contain has broken provenance
    the moment it leaves this machine. Exporting the faithful extractions makes
    the bundle answer its own citations.
    """
    notes: list[str] = []
    okf: dict[str, Any] = {"type": "Source"}
    title = record.get("title")
    if isinstance(title, str) and title.strip():
        okf["title"] = title
    else:
        notes.append("missing recommended field: title")
    original = record.get("original_ref")
    if isinstance(original, str) and original.strip():
        # The underlying asset, which stays outside the bundle by design.
        okf["resource"] = original
    else:
        notes.append("missing recommended field: resource")
    okf["description"] = (
        f"Faithful Markdown extraction of {title or 'a registered source'}, "
        "preserved in its original language."
    )
    status = str(record.get("status") or "")
    okf["status"] = "draft" if status == "partial" else okf_contract.okf_status(status)
    if status == "partial":
        notes.append(
            "The extraction is incomplete in the wiki. OKF has no partial status, so it "
            "is exported as draft."
        )
    extracted_at = record.get("extracted_at")
    extractor = record.get("extractor")
    generated = okf_contract.actor_record(f"agent/{extractor}" if extractor else None, extracted_at)
    if generated:
        okf["generated"] = generated
    language = record.get("content_language")
    if isinstance(language, str) and language.strip():
        okf["tags"] = [f"language/{language}"]
    else:
        notes.append("missing recommended field: tags")
    return okf, notes


def build_log(target: Path, version: str) -> str:
    """Render the wiki's change record as OKF's reserved chronological log."""
    changes = target / "meta/changes.md"
    body = changes.read_text(encoding="utf-8").strip() if changes.is_file() else ""
    lines = [
        "# Log",
        "",
        f"Chronological record carried over from the wiki at release {version}.",
        "",
    ]
    if body:
        # Keep the maintained record verbatim below the generated heading.
        lines.extend(convert_body(body).splitlines())
    else:
        lines.append("No change entries were recorded for this release.")
    return "\n".join(lines).rstrip() + "\n"


def build_index(
    pages: list[dict[str, Any]],
    sources: list[dict[str, Any]],
    title: str,
    topic: str,
) -> str:
    """Build the bundle root index. Per the spec it carries okf_version only."""
    lines = [
        "---",
        f'okf_version: "{okf_contract.OKF_VERSION}"',
        "---",
        "",
        f"# {title}",
        "",
        topic,
        "",
        "## Concepts",
        "",
    ]
    for page in sorted(pages, key=lambda item: str(item["path"])):
        label = str(page["title"] or PurePosixPath(str(page["path"])).stem)
        lines.append(f"- [{label}](/{page['path']}) — {page['status']}, {page['trust_tier']}")
    if sources:
        lines.extend(
            [
                "",
                "## Sources",
                "",
                "Faithful extractions the concepts above cite, in their original language.",
                "",
            ]
        )
        for source in sorted(sources, key=lambda item: str(item["path"])):
            label = str(source["title"] or PurePosixPath(str(source["path"])).stem)
            lines.append(f"- [{label}](/{source['path']})")
    lines.extend(["", "See [About this bundle](/README.md) for what this export leaves behind."])
    return "\n".join(lines) + "\n"


def build_readme(version: str, release_id: str, findings: list[dict[str, Any]]) -> str:
    # Everything that is not a reserved file is a concept document, so the README
    # carries frontmatter too rather than making its own bundle non-conformant.
    lines = [
        "---",
        'type: "Documentation"',
        'title: "About this bundle"',
        'description: "What this OKF export contains and what it deliberately leaves behind."',
        'status: "stable"',
        "---",
        "",
        "# What this bundle is, and what it is not",
        "",
        f"This is an Open Knowledge Format v{okf_contract.OKF_VERSION} export of "
        f"SkillSafeWerkstatt release {version} ({release_id}).",
        "",
        "It is an interoperability view of a wiki, not the wiki. The following does not "
        "exist in this bundle and cannot be reconstructed from it:",
        "",
    ]
    lines.extend(f"- {item}" for item in okf_contract.NOT_EXPORTED)
    lines.extend(
        [
            "",
            "## Fields that could not be filled",
            "",
            "The export never invents a value. Where a recommended field had no basis in the "
            "wiki, it was left out and listed here.",
            "",
        ]
    )
    if findings:
        for finding in findings:
            for note in finding["notes"]:
                lines.append(f"- `{finding['path']}`: {note}")
    else:
        lines.append("- None.")
    lines.extend(
        [
            "",
            "## Getting the current state",
            "",
            "Maintain and release the canonical wiki, then export again. Editing this bundle "
            "does not change the wiki and the change would be lost on the next export.",
            "",
        ]
    )
    return "\n".join(lines) + "\n"


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--target", required=True)
    parser.add_argument("--destination", required=True, help="Empty or non-existing output directory")
    parser.add_argument(
        "--no-sources",
        action="store_true",
        help="Omit the registered source extractions; the bundle can then not answer its own citations",
    )
    parser.add_argument("--allow-hydration", action="store_true")
    args = parser.parse_args()

    target = Path(args.target).expanduser().resolve()
    destination = Path(args.destination).expanduser().resolve()
    if destination == target or target in destination.parents or destination in target.parents:
        raise SystemExit("the export destination must stay outside the wiki")
    if destination.exists() and any(destination.iterdir()):
        raise SystemExit(f"export destination is not empty: {destination}")

    # An export must describe one published state, so it is bound to a verified
    # release rather than to whatever happens to be on disk. It deliberately runs
    # without a maintenance lock: an active lock means maintenance is in flight,
    # and a half-finished state must not be exported at all.
    verification = verify_snapshot(target, allow_hydration=bool(args.allow_hydration))
    if verification.get("state") != "ready":
        print(json.dumps({"state": "not_exported", "verification": verification}, indent=2))
        return 4

    registry = load_registry(target / "meta/sources.jsonl")
    wiki_root = target / "wiki"
    pages: list[dict[str, Any]] = []
    findings: list[dict[str, Any]] = []
    staged: list[tuple[str, str]] = []

    for path in sorted(wiki_root.rglob("*.md")):
        relative = path.relative_to(target).as_posix()
        try:
            document = parse_document(
                path.read_text(encoding="utf-8"), relative, require_frontmatter=True
            )
        except (OSError, UnicodeError, FrontmatterError) as exc:
            raise SystemExit(f"{relative}: {exc}") from exc
        if document.data.get("type") == "index":
            # The bundle root index is generated; a wiki index has no OKF role.
            continue
        okf, notes = convert_page(document.data, registry)
        bundle_path = relative.removeprefix("wiki/")
        staged.append((bundle_path, render_frontmatter(okf) + convert_body(document.body)))
        pages.append(
            {
                "path": bundle_path,
                "title": okf.get("title", ""),
                "status": okf["status"],
                "trust_tier": trust_contract.trust_tier(document.data),
            }
        )
        if notes:
            findings.append({"path": bundle_path, "notes": notes})

    sources: list[dict[str, Any]] = []
    if not args.no_sources:
        for path in sorted((target / "sources").glob("*.md")):
            relative = path.relative_to(target).as_posix()
            source_id = PurePosixPath(relative).stem.split("-")[0:2]
            record = registry.get("-".join(source_id)) or {}
            try:
                document = parse_document(
                    path.read_text(encoding="utf-8"), relative, require_frontmatter=True
                )
            except (OSError, UnicodeError, FrontmatterError) as exc:
                raise SystemExit(f"{relative}: {exc}") from exc
            merged = {**document.data, **record}
            okf, notes = convert_source(merged, document.body)
            staged.append((relative, render_frontmatter(okf) + convert_body(document.body)))
            sources.append({"path": relative, "title": okf.get("title", "")})
            if notes:
                findings.append({"path": relative, "notes": notes})

    destination.mkdir(parents=True, exist_ok=True)
    try:
        for bundle_path, content in staged:
            output = destination / bundle_path
            output.parent.mkdir(parents=True, exist_ok=True)
            output.write_text(content, encoding="utf-8")
        heading = next(
            (
                line.lstrip("# ").strip()
                for line in (target / "WIKI.md").read_text(encoding="utf-8").splitlines()
                if line.startswith("#")
            ),
            "",
        )
        (destination / "index.md").write_text(
            build_index(
                pages,
                sources,
                heading or "Wiki",
                f"Exported from SkillSafeWerkstatt release {verification['version']}.",
            ),
            encoding="utf-8",
        )
        (destination / "log.md").write_text(
            build_log(target, str(verification["version"])), encoding="utf-8"
        )
        (destination / "README.md").write_text(
            build_readme(str(verification["version"]), str(verification["release_id"]), findings),
            encoding="utf-8",
        )
    except OSError:
        # A partial bundle would misrepresent the release, so leave none behind.
        shutil.rmtree(destination, ignore_errors=True)
        raise

    # Claiming conformance is cheap; demonstrating it is the point. Validate what
    # was actually written, and leave no bundle behind that fails its own check.
    problems = okf_contract.validate_bundle(destination)
    if problems:
        shutil.rmtree(destination, ignore_errors=True)
        print(
            json.dumps(
                {
                    "state": "not_exported",
                    "reason": "the generated bundle does not satisfy the OKF conformance rules",
                    "conformance_errors": problems,
                },
                ensure_ascii=False,
                indent=2,
            )
        )
        return 5

    print(
        json.dumps(
            {
                "state": "exported",
                "format": BUNDLE_FORMAT,
                "okf_version": okf_contract.OKF_VERSION,
                "source_release": {
                    "version": verification["version"],
                    "release_id": verification["release_id"],
                    "manifest_sha256": verification["manifest_sha256"],
                },
                "documents": len(pages) + len(sources),
                "concepts": len(pages),
                "sources": len(sources),
                "conformance": "validated against OKF v0.2 after writing",
                "unfilled_fields": findings,
                "not_exported": list(okf_contract.NOT_EXPORTED),
                "wiki_unchanged": True,
            },
            ensure_ascii=False,
            indent=2,
        )
    )
    return 0


if __name__ == "__main__":
    # Windows pipes default to the ANSI code page; output is UTF-8 everywhere.
    for _stream in (sys.stdout, sys.stderr):
        if hasattr(_stream, "reconfigure"):
            _stream.reconfigure(encoding="utf-8", errors=_stream.errors)
    raise SystemExit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall