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

View on GitHub
#!/usr/bin/env python3
"""Classify files a synchronization client or operating system created.

A OneDrive or SharePoint client is a writer on the wiki directory, not only a
transport. It resolves conflicts by keeping both copies and renaming one after
the device, and the operating system drops its own artifacts into synchronized
folders. Both are indistinguishable from wiki content to a plain directory walk.

This module is the single place that decides what such a file is, so the linter,
the release, and both verifiers can no longer disagree about the same path. It
only classifies; it never deletes, moves, or rewrites anything.

The storage-layer rules encoded here follow the documented OneDrive and
SharePoint restrictions: reserved names, forbidden characters, and the
400-character path budget.
"""

from __future__ import annotations

import re
from pathlib import Path, PurePosixPath
from typing import Any, Iterable, Optional


# Kinds, ordered from "ignore quietly" to "the storage will reject this".
IGNORABLE = "os_artifact"
CONFLICT_COPY = "conflict_copy"
RESERVED_NAME = "reserved_name"
INVALID_CHARACTER = "invalid_character"
TRAILING_CHARACTER = "trailing_character"

#: Kinds that must never be treated as wiki content.
NON_CONTENT_KINDS = frozenset({IGNORABLE, CONFLICT_COPY})

#: Names the operating system or an Office application writes on its own.
#: OneDrive deliberately does not upload these, so a local copy is expected and
#: is never evidence of smuggled binary originals.
OS_ARTIFACT_NAMES = frozenset(
    {
        ".ds_store",
        ".localized",
        "desktop.ini",
        "ehthumbs.db",
        "thumbs.db",
        "icon\r",
    }
)

#: Names OneDrive and SharePoint refuse outright, compared without extension.
RESERVED_STEMS = frozenset(
    {"con", "prn", "aux", "nul"}
    | {f"com{digit}" for digit in range(10)}
    | {f"lpt{digit}" for digit in range(10)}
)

#: Full names OneDrive and SharePoint refuse outright *and* that no other rule
#: already claims. The storage also refuses `desktop.ini` and every `~$` name,
#: but those carry nothing, so `_is_os_artifact` answers for them first and this
#: branch would never see them. Listing them here too would be dead weight that
#: silently turns into a lint error the moment someone reorders `classify()`.
RESERVED_NAMES = frozenset({".lock"})

#: Characters SharePoint rejects in a file or folder name.
INVALID_CHARACTERS = frozenset('"*:<>?/\\|')

#: Fragment SharePoint refuses anywhere inside a name.
FORBIDDEN_FRAGMENT = "_vti_"

#: Full decoded path budget for OneDrive and SharePoint, in characters.
PATH_BUDGET = 400

#: Default Windows path limit without long-path support, in characters.
WINDOWS_PATH_BUDGET = 260

# Conflict copies observed from OneDrive clients. The device suffix is the
# common Windows form; the parenthesized forms cover the localized variants.
_CONFLICT_PATTERNS = (
    re.compile(r"-(?:DESKTOP|LAPTOP|SURFACE)-[A-Z0-9]{5,8}$", re.IGNORECASE),
    re.compile(r"\((?:[^()]{1,64}\s)?conflicted copy(?:\s[^()]{1,64})?\)$", re.IGNORECASE),
    re.compile(r"\([^()]{1,64}\sconflict\)$", re.IGNORECASE),
    re.compile(r"-konfliktkopie(?:-[0-9]{1,4})?$", re.IGNORECASE),
)

# Deliberately absent: a rule that treats "<stem>-<UPPERCASE>" as a conflict copy
# whenever "<stem>" sits next to it. It looks helpful and is not: a wiki page
# named "energie-KRITIS" beside "energie" is ordinary curation, and misreading it
# as a conflict copy fails the lint and takes the whole wiki offline. A missed
# conflict copy is merely reported as an unexpected file, naming the path, which
# is recoverable. The asymmetry decides it - only documented patterns count.


class Artifact:
    """One classified path, relative to the wiki root."""

    __slots__ = ("path", "kind", "reason", "original")

    def __init__(self, path: str, kind: str, reason: str, original: str = "") -> None:
        self.path = path
        self.kind = kind
        self.reason = reason
        self.original = original

    @property
    def ignorable(self) -> bool:
        """True when the file is noise that no contract should ever hash."""
        return self.kind == IGNORABLE

    def as_dict(self) -> dict[str, Any]:
        record = {"path": self.path, "kind": self.kind, "reason": self.reason}
        if self.original:
            record["original"] = self.original
        return record

    def __repr__(self) -> str:  # pragma: no cover - diagnostic only
        return f"Artifact({self.path!r}, {self.kind!r})"


def _is_os_artifact(name: str) -> bool:
    lowered = name.casefold()
    return lowered in OS_ARTIFACT_NAMES or lowered.startswith("~$")


def _conflict_original(name: str) -> Optional[str]:
    """Return the original file name when `name` matches a known conflict pattern.

    Only the documented client-generated forms count. See the note above the
    patterns for why an ambiguous name is never guessed at.
    """
    stem = PurePosixPath(name).stem
    suffix = PurePosixPath(name).suffix
    for pattern in _CONFLICT_PATTERNS:
        match = pattern.search(stem)
        if match:
            return f"{stem[: match.start()]}{suffix}"
    return None


def classify(relative: str) -> Optional[Artifact]:
    """Classify one wiki-relative POSIX path, or return None for ordinary content.

    Classification depends only on the name, never on what sits beside it, so a
    page cannot be reclassified by an unrelated file appearing next to it.
    """
    name = PurePosixPath(relative).name
    if not name:
        return None

    # Deliberately first: `desktop.ini` and every `~$` name are also names the
    # storage refuses, but they carry nothing, so refusing them costs nothing
    # and a wiki must not go offline because Explorer wrote one. Reordering this
    # would turn ordinary desktop noise into a lint error everywhere at once.
    if _is_os_artifact(name):
        return Artifact(relative, IGNORABLE, f"operating-system or Office artifact {name!r}")

    original = _conflict_original(name)
    if original:
        return Artifact(
            relative,
            CONFLICT_COPY,
            "synchronization conflict copy; the client kept both versions instead of merging",
            original=(PurePosixPath(relative).parent / original).as_posix(),
        )

    lowered = name.casefold()
    stem = PurePosixPath(name).stem.casefold()
    if lowered in RESERVED_NAMES or stem in RESERVED_STEMS:
        return Artifact(
            relative,
            RESERVED_NAME,
            f"OneDrive and SharePoint refuse the name {name!r}",
        )
    if FORBIDDEN_FRAGMENT in lowered:
        return Artifact(
            relative,
            RESERVED_NAME,
            f"OneDrive and SharePoint refuse {FORBIDDEN_FRAGMENT!r} anywhere in a name",
        )
    offending = sorted(INVALID_CHARACTERS & set(name))
    if offending:
        return Artifact(
            relative,
            INVALID_CHARACTER,
            f"OneDrive and SharePoint refuse the character(s) {''.join(offending)!r} in a name",
        )
    # A trailing space before the extension is stripped by Windows and by the
    # storage layer, so the stored name stops matching the recorded one.
    if name != name.strip() or name.endswith(".") or PurePosixPath(name).stem != PurePosixPath(name).stem.strip():
        return Artifact(
            relative,
            TRAILING_CHARACTER,
            "OneDrive and SharePoint refuse a leading or trailing space and a trailing period",
        )
    return None


def classify_all(relatives: Iterable[str]) -> list[Artifact]:
    """Classify a whole set of wiki-relative paths."""
    found = [classify(relative) for relative in sorted(set(relatives))]
    return [artifact for artifact in found if artifact is not None]


def is_ignorable(relative: str) -> bool:
    """True for files every contract must skip without complaint."""
    artifact = classify(relative)
    return artifact is not None and artifact.ignorable


def path_budget_findings(
    relatives: Iterable[str],
    *,
    prefix: str = "",
    budget: int = PATH_BUDGET,
) -> list[dict[str, Any]]:
    """Report paths that would exceed the storage path budget.

    `prefix` is the decoded library path the wiki will live under, for example
    ``/sites/Team/Freigegebene Dokumente/Wiki``. Without it only the wiki-relative
    length is known, which is a lower bound rather than the real figure.
    """
    normalized = prefix.strip("/")
    lead = len(normalized) + 1 if normalized else 0
    findings = []
    for relative in sorted(set(relatives)):
        total = lead + len(relative)
        if total > budget:
            findings.append(
                {
                    "path": relative,
                    "characters": total,
                    "budget": budget,
                    "reason": "the decoded storage path exceeds the OneDrive and SharePoint limit",
                }
            )
    return findings


def case_collisions(relatives: Iterable[str]) -> list[dict[str, Any]]:
    """Report paths that differ only in case.

    SharePoint preserves case but does not distinguish it, so two such files
    cannot coexist there even though they can locally on Linux.
    """
    seen: dict[str, list[str]] = {}
    for relative in sorted(set(relatives)):
        seen.setdefault(relative.casefold(), []).append(relative)
    return [
        {"paths": paths, "reason": "SharePoint does not distinguish these names"}
        for paths in seen.values()
        if len(paths) > 1
    ]


#: Windows attribute set on a file whose content lives only in the cloud.
FILE_ATTRIBUTE_OFFLINE = 0x1000

#: Windows attribute meaning any read triggers a download. Absent from the
#: standard library's `stat` module, so the documented literal is used.
FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS = 0x400000


def is_dataless(path: Path) -> Optional[bool]:
    """True when reading `path` would pull its content down from the cloud.

    Files On-Demand hydrates transparently on read, and the reparse points it
    uses are hidden from ordinary applications, so this inspects only metadata
    and never opens the file. Returns None when the platform gives no usable
    signal, so callers can tell "not dataless" apart from "cannot tell".
    """
    try:
        status = path.stat()
    except OSError:
        return None
    attributes = getattr(status, "st_file_attributes", None)
    if attributes is not None:
        return bool(attributes & (FILE_ATTRIBUTE_OFFLINE | FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS))
    blocks = getattr(status, "st_blocks", None)
    if blocks is None:
        return None
    # A file that reports a size but occupies no blocks holds no local content.
    return bool(status.st_size > 0 and blocks == 0)


def hydration_report(root: Path, relatives: Iterable[str]) -> dict[str, Any]:
    """Estimate what verifying these files would download.

    Reading every released file to hash it is the safety property, but on a
    dehydrated library it also means downloading the whole wiki for one question.
    This measures the cost first so a caller can ask before paying it.
    """
    dataless: list[str] = []
    dataless_bytes = 0
    inspected = 0
    undetermined = 0
    for relative in sorted(set(relatives)):
        path = root / relative
        state = is_dataless(path)
        if state is None:
            undetermined += 1
            continue
        inspected += 1
        if state:
            dataless.append(relative)
            try:
                dataless_bytes += path.stat().st_size
            except OSError:
                pass
    return {
        "inspected": inspected,
        "undetermined": undetermined,
        "dataless": len(dataless),
        "dataless_bytes": dataless_bytes,
        "share": round(len(dataless) / inspected, 4) if inspected else 0.0,
        "paths": dataless[:50],
        "method": "file metadata only; no file was opened, so nothing was hydrated",
    }


#: Path components that indicate a locally synchronized cloud library.
_SYNC_MARKERS = ("onedrive", "sharepoint")

#: Environment variables the OneDrive client sets for its sync roots.
_SYNC_ENVIRONMENT = ("OneDrive", "OneDriveCommercial", "OneDriveConsumer")


def storage_hint(target: Path, environment: Optional[dict[str, str]] = None) -> dict[str, Any]:
    """Guess whether `target` lives inside a synchronized cloud folder.

    This is a heuristic on visible path names and the client's own environment
    variables. There is no supported way to query a sync client's state, so the
    answer is advisory: it may miss a renamed sync root and it may flag an
    ordinary directory that merely contains the word. Callers must present it as
    a hint, never as a fact about the storage.
    """
    import os as _os

    environment = _os.environ if environment is None else environment
    resolved = target.expanduser().resolve()
    parts = [part.casefold() for part in resolved.parts]
    reasons: list[str] = []
    for part in parts:
        for marker in _SYNC_MARKERS:
            if marker in part:
                reasons.append(f"path component {part!r} names a synchronized library")
                break
    for name in _SYNC_ENVIRONMENT:
        root = environment.get(name)
        if not root:
            continue
        try:
            resolved.relative_to(Path(root).expanduser().resolve())
        except (ValueError, OSError):
            continue
        reasons.append(f"the target lies inside {name}")
    return {
        "synchronized": bool(reasons),
        "confidence": "heuristic",
        "reasons": reasons,
        "advisory": (
            "This wiki appears to live in a synchronized folder. The maintenance lock is a "
            "cooperative file lock on one filesystem; it cannot exclude a second device whose "
            "changes are reconciled later. Do not maintain the same wiki from two machines at "
            "once, and treat a published release as local until the client confirms upload."
        )
        if reasons
        else "",
    }


def walk(root: Path, directories: Iterable[str]) -> frozenset[str]:
    """Collect every file under `directories` as wiki-relative POSIX paths."""
    found: set[str] = set()
    for directory in directories:
        base = root / directory
        if not base.is_dir():
            continue
        for path in base.rglob("*"):
            if path.is_file():
                found.add(path.relative_to(root).as_posix())
    return frozenset(found)
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