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/release_wiki.py

View on GitHub
#!/usr/bin/env python3
"""Validate and publish one immutable SkillSafeWerkstatt release boundary."""

from __future__ import annotations

import argparse
import hashlib
import json
import os
import re
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path, PurePosixPath
from typing import Optional
from uuid import uuid4

# 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 portable_io
import sync_artifacts

from wiki_lock import require_lock


VERSION_RE = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
ROOT_FILES = ("WIKI.md", "WIKI_VERSION", "SOUL.md", "STANDARDS.md")
CONTROLLED_DIRS = ("schema", "sources", "wiki", "graph")
META_FILES = (
    "meta/sources.jsonl",
    "meta/changes.md",
    "meta/questions.md",
    "meta/lint-report.json",
    "meta/releases.jsonl",
    "meta/quality-reviews.jsonl",
    "meta/quality-status.json",
)
QUALITY_FIELDS = (
    "quality_review_after_days",
    "cleaning_review_after_days",
    "snapshot_warning_after_days",
)


def utc_now() -> str:
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")


def sha256_bytes(value: bytes) -> str:
    return hashlib.sha256(value).hexdigest()


def atomic_write(path: Path, content: bytes) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
    descriptor = os.open(str(temporary), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    try:
        with os.fdopen(descriptor, "wb") as handle:
            handle.write(content)
            handle.flush()
            os.fsync(handle.fileno())
        portable_io.replace_with_retry(temporary, path)
    finally:
        if temporary.exists():
            temporary.unlink()


def read_version(path: Path) -> tuple[int, int, int]:
    value = path.read_text(encoding="utf-8").strip() if path.is_file() else "0.0.0"
    match = VERSION_RE.fullmatch(value)
    if not match:
        raise SystemExit(f"WIKI_VERSION is not semantic version x.y.z: {value!r}")
    return tuple(int(part) for part in match.groups())  # type: ignore[return-value]


def version_text(version: tuple[int, int, int]) -> str:
    return ".".join(str(part) for part in version)


def prior_operation(path: Path, operation_id: str) -> Optional[dict[str, object]]:
    if not path.is_file():
        return None
    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 record.get("operation_id") == operation_id:
            return record
    return None


def bump_version(version: tuple[int, int, int], bump: str) -> str:
    major, minor, patch = version
    if bump == "major":
        return f"{major + 1}.0.0"
    if bump == "minor":
        return f"{major}.{minor + 1}.0"
    return f"{major}.{minor}.{patch + 1}"


def controlled_files(target: Path) -> list[Path]:
    found: set[Path] = set()
    for name in ROOT_FILES:
        path = target / name
        if path.is_file():
            found.add(path)
    for directory in CONTROLLED_DIRS:
        root = target / directory
        if root.is_dir():
            for path in root.rglob("*"):
                if not path.is_file() or path.name.startswith(".") or path.name.endswith(".tmp"):
                    continue
                # Never hash operating-system noise into a release boundary; the
                # storage layer does not carry it, so its hash cannot be reproduced.
                if sync_artifacts.is_ignorable(path.relative_to(target).as_posix()):
                    continue
                found.add(path)
    for name in META_FILES:
        path = target / name
        if path.is_file():
            found.add(path)
    return sorted(found, key=lambda path: path.relative_to(target).as_posix())


def previous_manifest_hash(path: Path) -> str:
    return sha256_bytes(path.read_bytes()) if path.is_file() else ""


def read_quality_policy(path: Path) -> dict[str, int]:
    text = path.read_text(encoding="utf-8") if path.is_file() else ""
    policy: dict[str, int] = {}
    for field in QUALITY_FIELDS:
        match = re.search(rf"^{re.escape(field)}:\s*(\d+)\s*$", text, re.MULTILINE)
        if not match:
            raise SystemExit(f"schema/QUALITY_POLICY.md is missing {field}")
        value = int(match.group(1))
        if value < 1 or value > 3650:
            raise SystemExit(f"schema/QUALITY_POLICY.md has invalid {field}")
        policy[field] = value
    return policy


def latest_quality_reviews(path: Path) -> dict[str, object]:
    latest: dict[str, object] = {"quality": None, "cleaning": None}
    if not path.is_file():
        return latest
    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 not isinstance(record, dict) or record.get("format") != "lmwiki-quality-review/1":
            continue
        kind = record.get("kind")
        if kind not in latest:
            continue
        current = latest[kind]
        if not isinstance(current, dict) or str(record.get("reviewed_at") or "") >= str(current.get("reviewed_at") or ""):
            latest[str(kind)] = {
                "review_id": str(record.get("review_id") or ""),
                "reviewed_at": str(record.get("reviewed_at") or ""),
                "outcome": str(record.get("outcome") or ""),
                "summary": str(record.get("summary") or ""),
            }
    return latest


def count_open_question_items(path: Path) -> int:
    if not path.is_file():
        return 0
    return sum(
        1
        for line in path.read_text(encoding="utf-8").splitlines()
        if re.match(r"^\s*[-*+]\s+\S", line)
    )


def persistence_statement(target: Path) -> dict[str, object]:
    """State what a successful release actually guarantees on this storage.

    A durable local write is not an upload. On a synchronized library the release
    is published for this machine only until the client finishes transferring it,
    and no supported interface reports when that happened.
    """
    hint = sync_artifacts.storage_hint(target)
    if not hint["synchronized"]:
        return {
            "local": "durable",
            "remote": "not-applicable",
            "statement": "The release is written durably to local storage.",
        }
    return {
        "local": "durable",
        "remote": "unconfirmed",
        "storage_hint": hint,
        "statement": (
            "The release is written durably to local storage. This wiki appears to live in a "
            "synchronized folder, and no supported interface reports whether the client has "
            "uploaded it yet, so do not tell others the release is available to them until the "
            "client shows the folder as fully synchronized."
        ),
    }


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--target", required=True)
    parser.add_argument("--lock-token", required=True, help="Token returned by wiki_lock.py acquire")
    parser.add_argument("--bump", choices=("patch", "minor", "major"), default="patch")
    parser.add_argument("--summary", default="Validated wiki maintenance release")
    parser.add_argument("--operation-id", required=True, help="Stable idempotency key for this release intent")
    parser.add_argument("--expect-current-version", required=True)
    args = parser.parse_args()

    target = Path(args.target).expanduser().resolve()
    lock = require_lock(target, args.lock_token)
    if not (target / "WIKI.md").is_file():
        raise SystemExit("Target is not an initialized SkillSafeWerkstatt")
    operation_id = args.operation_id.strip()
    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", operation_id):
        raise SystemExit("operation-id must be a portable identifier of at most 128 characters")

    releases_path = target / "meta/releases.jsonl"
    existing_operation = prior_operation(releases_path, operation_id)
    if existing_operation is not None:
        current_version = version_text(read_version(target / "WIKI_VERSION"))
        manifest_path = target / "meta/manifest.json"
        try:
            current_manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
            manifest_hash = sha256_bytes(manifest_path.read_bytes())
        except (OSError, json.JSONDecodeError) as exc:
            raise SystemExit(f"Existing release operation cannot be verified: {exc}") from exc
        if (
            current_manifest.get("release_id") != existing_operation.get("release_id")
            or current_version != existing_operation.get("version")
        ):
            raise SystemExit("operation-id was already used by an older release; use a new operation-id")
        print(json.dumps({
            "state": "already_released",
            "released": True,
            "idempotent_replay": True,
            "operation_id": operation_id,
            "release_id": existing_operation.get("release_id", ""),
            "version": current_version,
            "manifest": "meta/manifest.json",
            "manifest_sha256": manifest_hash,
            "lint_valid": True,
            "manifest_written_last": True,
        }, ensure_ascii=False, indent=2))
        return 0

    old_version = read_version(target / "WIKI_VERSION")
    current_version = version_text(old_version)
    if args.expect_current_version != current_version:
        raise SystemExit(
            f"stale release precondition: expected {args.expect_current_version}, current {current_version}"
        )

    lint_script = Path(__file__).resolve().parent / "lint_wiki.py"
    lint = subprocess.run(
        [
            sys.executable,
            str(lint_script),
            "--target",
            str(target),
            "--lock-token",
            args.lock_token,
        ],
        capture_output=True,
        # The lint helper prints UTF-8 (see its __main__ block), whatever the host code page.
        encoding="utf-8",
        errors="replace",
        check=False,
    )
    if lint.returncode != 0:
        if lint.stdout:
            print(lint.stdout, end="", file=sys.stderr)
        if lint.stderr:
            print(lint.stderr, end="", file=sys.stderr)
        raise SystemExit("Release refused because the strict wiki lint failed")
    try:
        lint_result = json.loads(lint.stdout)
    except json.JSONDecodeError as exc:
        raise SystemExit("Release lint helper returned invalid JSON") from exc
    new_version = bump_version(old_version, args.bump)
    released_at = utc_now()
    release_id = str(uuid4())
    manifest_path = target / "meta/manifest.json"
    prior_hash = previous_manifest_hash(manifest_path)

    atomic_write(target / "WIKI_VERSION", (new_version + "\n").encode("utf-8"))
    existing_log = releases_path.read_bytes() if releases_path.is_file() else b""
    if existing_log and not existing_log.endswith(b"\n"):
        existing_log += b"\n"
    release_record = {
        "format": "lmwiki-release-log/1",
        "release_id": release_id,
        "version": new_version,
        "released_at": released_at,
        "summary": args.summary,
        "bump": args.bump,
        "previous_manifest_sha256": prior_hash,
        "lock_id": lock.get("lock_id", ""),
        "operation_id": operation_id,
    }
    log_line = json.dumps(release_record, ensure_ascii=False, sort_keys=True).encode("utf-8") + b"\n"
    atomic_write(releases_path, existing_log + log_line)

    try:
        lint_report = json.loads((target / "meta/lint-report.json").read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError):
        raise SystemExit("Release lint report is unavailable or invalid")
    policy = read_quality_policy(target / "schema/QUALITY_POLICY.md")
    quality_status = {
        "format": "lmwiki-quality/1",
        "generated_at": released_at,
        "release_id": release_id,
        "version": new_version,
        "policy": policy,
        "technical": {
            "last_lint_at": released_at,
            "valid": bool(lint_report.get("valid")),
            "errors": len(lint_report.get("errors") or []),
            "warnings": len(lint_report.get("warnings") or []),
        },
        "reviews": latest_quality_reviews(target / "meta/quality-reviews.jsonl"),
        # Wiki-wide reviews say when someone last looked; the trust distribution
        # says how much of the wiki that actually covered.
        "trust": (lint_report.get("stats") or {}).get("trust", {}),
        "freshness": (lint_report.get("stats") or {}).get("freshness", {}),
        "open_question_items": count_open_question_items(target / "meta/questions.md"),
    }
    atomic_write(
        target / "meta/quality-status.json",
        (json.dumps(quality_status, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode("utf-8"),
    )

    entries: list[dict[str, object]] = []
    total_bytes = 0
    for path in controlled_files(target):
        relative = path.relative_to(target).as_posix()
        if PurePosixPath(relative).is_absolute() or ".." in PurePosixPath(relative).parts:
            raise SystemExit(f"Refusing non-portable manifest path: {relative}")
        content = path.read_bytes()
        total_bytes += len(content)
        entries.append({"path": relative, "sha256": sha256_bytes(content), "bytes": len(content)})

    manifest = {
        "format": "lmwiki-release/1",
        "release_id": release_id,
        "version": new_version,
        "released_at": released_at,
        "previous_manifest_sha256": prior_hash,
        "files": entries,
        "totals": {"files": len(entries), "bytes": total_bytes},
    }
    manifest_bytes = (json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode("utf-8")
    atomic_write(manifest_path, manifest_bytes)
    manifest_hash = sha256_bytes(manifest_bytes)

    print(
        json.dumps(
            {
                "state": "released",
                "released": True,
                "idempotent_replay": False,
                "operation_id": operation_id,
                "release_id": release_id,
                "version": new_version,
                "manifest": "meta/manifest.json",
                "manifest_sha256": manifest_hash,
                "quality_status": "meta/quality-status.json",
                "quality_review_at": (
                    (quality_status.get("reviews") or {}).get("quality", {}).get("reviewed_at", "")
                    if isinstance((quality_status.get("reviews") or {}).get("quality"), dict)
                    else ""
                ),
                "cleaning_review_at": (
                    (quality_status.get("reviews") or {}).get("cleaning", {}).get("reviewed_at", "")
                    if isinstance((quality_status.get("reviews") or {}).get("cleaning"), dict)
                    else ""
                ),
                "files": len(entries),
                "bytes": total_bytes,
                "manifest_written_last": True,
                "lint_valid": bool(lint_result.get("valid")),
                "stats": lint_result.get("stats", {}),
                # fsync guarantees this disk, not the storage provider. Say which
                # one was actually achieved instead of implying both.
                "persistence": persistence_statement(target),
            },
            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