GodModeAI2025/SkillSafeWerkstatt / maintain-llm-wiki
maintain-llm-wiki
UnverifiedCreate, 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.
scripts/verify_release.py
View on GitHub#!/usr/bin/env python3
"""Verify a released SkillSafeWerkstatt snapshot without modifying it."""
from __future__ import annotations
import argparse
import hashlib
import json
import sys
from pathlib import Path, PurePosixPath, PureWindowsPath
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 sync_artifacts
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",
)
def sha256_bytes(value: bytes) -> str:
return hashlib.sha256(value).hexdigest()
def result(state: str, **values: Any) -> dict[str, Any]:
return {"state": state, **values}
def transfer_pending(target: Path, drifted: list[str]) -> bool:
"""True when the manifest is newer than every file whose content disagrees.
A synchronization client transfers in its own order, so a second device can
receive the new manifest before the content it describes. That is a transient
state rather than a damaged release, and only waiting fixes it.
"""
try:
manifest_mtime = (target / "meta/manifest.json").stat().st_mtime
except OSError:
return False
for relative in set(drifted):
try:
if (target / relative).stat().st_mtime >= manifest_mtime:
return False
except OSError:
return False
return True
def controlled_paths(target: Path) -> set[str]:
paths: set[str] = set()
for name in ROOT_FILES:
if (target / name).is_file():
paths.add(name)
for directory in CONTROLLED_DIRS:
root = target / directory
if not root.is_dir():
continue
for path in root.rglob("*"):
if not path.is_file() or path.name.endswith(".tmp"):
continue
relative = path.relative_to(target).as_posix()
# A dot-prefixed name the classifier has no opinion about is skipped
# as before. Everything it does have an opinion about is kept, so it
# can be disclosed and then judged by kind. Asking for "ignorable"
# instead dropped `.lock` — the one reserved name that starts with a
# dot — out of the verifier's sight entirely.
if path.name.startswith(".") and sync_artifacts.classify(relative) is None:
continue
paths.add(relative)
for name in META_FILES:
if (target / name).is_file():
paths.add(name)
return paths
def verify_snapshot(
target: Path,
expected_manifest_sha256: str = "",
*,
allow_hydration: bool = False,
) -> dict[str, Any]:
lock_path = target / ".llmwiki.lock"
if lock_path.exists():
return result("wiki_busy", reason="A maintenance writer currently owns the wiki lock")
manifest_path = target / "meta/manifest.json"
try:
first_bytes = manifest_path.read_bytes()
except OSError as exc:
return result("invalid_wiki", reason=f"Release manifest is unavailable: {exc}")
first_hash = sha256_bytes(first_bytes)
if expected_manifest_sha256 and first_hash != expected_manifest_sha256:
return result(
"snapshot_changed",
expected_manifest_sha256=expected_manifest_sha256,
manifest_sha256=first_hash,
)
try:
manifest = json.loads(first_bytes)
except json.JSONDecodeError as exc:
return result("invalid_wiki", reason=f"Release manifest is invalid JSON: {exc}")
if not isinstance(manifest, dict) or manifest.get("format") != "lmwiki-release/1":
return result("invalid_wiki", reason="Unsupported or missing release manifest format")
files = manifest.get("files")
if not isinstance(files, list) or not files:
return result("invalid_wiki", reason="Release manifest contains no files")
# Reading every file to hash it is the safety property, but on a dehydrated
# cloud library it also downloads the whole wiki. Measure first, then decide.
manifest_paths = [
str(entry.get("path"))
for entry in files
if isinstance(entry, dict) and isinstance(entry.get("path"), str)
]
hydration = sync_artifacts.hydration_report(target, manifest_paths)
if hydration["dataless"] and not allow_hydration:
return result(
"hydration_required",
manifest_sha256=first_hash,
hydration=hydration,
reason=(
f"{hydration['dataless']} of {hydration['inspected']} released files hold no "
"local content. Verifying them would download roughly "
f"{hydration['dataless_bytes']} bytes from the storage provider and fails "
"offline. Re-run allowing hydration once that is acceptable."
),
)
errors: list[str] = []
content_drift: list[str] = []
seen: set[str] = set()
for entry in files:
if not isinstance(entry, dict):
errors.append("Manifest contains a non-object file entry")
continue
relative = entry.get("path")
if not isinstance(relative, str) or not relative:
errors.append("Manifest contains an empty file path")
continue
portable = PurePosixPath(relative)
windows = PureWindowsPath(relative)
if (
portable.is_absolute()
or windows.is_absolute()
or bool(windows.drive)
or ".." in portable.parts
or ".." in windows.parts
or "\\" in relative
or portable.as_posix() != relative
):
errors.append(f"Manifest contains a non-portable path: {relative}")
continue
if relative in seen:
errors.append(f"Manifest contains a duplicate path: {relative}")
continue
seen.add(relative)
path = target / relative
try:
content = path.read_bytes()
except OSError:
errors.append(f"Released file is missing or unreadable: {relative}")
continue
if sha256_bytes(content) != entry.get("sha256"):
errors.append(f"Released file hash differs: {relative}")
content_drift.append(relative)
if len(content) != entry.get("bytes"):
errors.append(f"Released file size differs: {relative}")
content_drift.append(relative)
unexpected = sorted(controlled_paths(target) - seen)
# A synchronization client writes into this directory too. Separate the
# files it created from genuine release damage before judging the wiki.
classified = sync_artifacts.classify_all(unexpected)
artifacts = [
artifact for artifact in classified if artifact.kind in sync_artifacts.NON_CONTENT_KINDS
]
artifact_paths = {artifact.path for artifact in artifacts}
# A name the storage layer refuses is neither noise nor a normal stray file:
# the file exists here but would silently never reach the storage, so this
# copy of the wiki cannot be the one another device sees. It blocks, and it
# is named with its reason rather than folded into the generic message.
refused = [
artifact for artifact in classified if artifact.kind not in sync_artifacts.NON_CONTENT_KINDS
]
refused_paths = {artifact.path for artifact in refused}
genuinely_unexpected = [
path for path in unexpected if path not in artifact_paths and path not in refused_paths
]
if refused:
errors.append(
"Controlled files carry names the storage layer refuses: "
+ "; ".join(f"{artifact.path} ({artifact.reason})" for artifact in refused)
)
if genuinely_unexpected:
errors.append(
f"Controlled files exist outside the release manifest: {genuinely_unexpected}"
)
version_path = target / "WIKI_VERSION"
version = version_path.read_text(encoding="utf-8").strip() if version_path.is_file() else ""
if version != manifest.get("version"):
errors.append("WIKI_VERSION differs from the release manifest")
if lock_path.exists():
return result("wiki_busy", reason="Maintenance started while the release was being verified")
try:
second_bytes = manifest_path.read_bytes()
except OSError as exc:
return result("snapshot_changed", reason=f"Release manifest became unavailable: {exc}")
if second_bytes != first_bytes:
return result(
"snapshot_changed",
expected_manifest_sha256=first_hash,
manifest_sha256=sha256_bytes(second_bytes),
)
if errors:
# Content that lags behind a freshly arrived manifest is a transfer still
# in flight, not damage. Waiting resolves it; repairing would not.
if (
content_drift
and not genuinely_unexpected
and not refused
and transfer_pending(target, content_drift)
):
return result(
"sync_in_progress",
manifest_sha256=first_hash,
version=version,
pending=sorted(set(content_drift)),
reason=(
"The manifest is newer than the files it describes. A synchronization "
"transfer is most likely still running; retry once it settles."
),
)
report = result("invalid_wiki", manifest_sha256=first_hash, version=version, errors=errors)
if refused:
report["storage_refused"] = [artifact.as_dict() for artifact in refused]
return report
# A conflict copy carries content that diverged across devices, so reading
# must stop until a human decides. Operating-system noise carries nothing and
# must never block a reader; it is reported and otherwise ignored.
blocking = [artifact for artifact in artifacts if artifact.kind == sync_artifacts.CONFLICT_COPY]
notices = [artifact.as_dict() for artifact in artifacts if artifact.ignorable]
if blocking:
return result(
"sync_artifacts_present",
manifest_sha256=first_hash,
version=version,
sync_artifacts=[artifact.as_dict() for artifact in blocking],
ignored_artifacts=notices,
reason=(
"A synchronization client kept a conflicting copy next to a released file. "
"Resolve it with the maintenance skill before reading; the release itself is intact."
),
)
return result(
"ready",
ignored_artifacts=notices,
manifest_sha256=first_hash,
release_id=manifest.get("release_id", ""),
version=version,
files=len(files),
released_at=manifest.get("released_at", ""),
)
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--target", required=True)
parser.add_argument("--expect-manifest-sha256", default="")
parser.add_argument(
"--allow-hydration",
action="store_true",
help="Verify even when released files must be downloaded from the storage provider",
)
args = parser.parse_args()
target = Path(args.target).expanduser().resolve()
report = verify_snapshot(
target, args.expect_manifest_sha256, allow_hydration=bool(args.allow_hydration)
)
print(json.dumps(report, ensure_ascii=False, indent=2))
return {
"ready": 0,
"wiki_busy": 2,
"snapshot_changed": 3,
"sync_artifacts_present": 5,
"sync_in_progress": 6,
"hydration_required": 7,
}.get(str(report.get("state")), 4)
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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |