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

View on GitHub
#!/usr/bin/env python3
"""Generated directory indexes, so orientation stops growing with the wiki.

A single `wiki/index.md` must list every page, so the cost of orienting in a
wiki rises linearly with its size - paid before a single page has been read. A
directory index per branch lets a reader load the root, choose a branch, and
read only that branch.

These are the first generated files inside the curated `wiki/` namespace, which
is why the decision needed care. Two things settle it. First, `wiki/index.md`
already exists there and is already navigation rather than knowledge, with its
own `type: index` that the contract exempts from sources, clusters and claims -
so a branch index extends an existing category instead of introducing a new one.
Second, the alternative of generating them under `graph/` would not reduce what
the reading skill loads as Markdown, which was the entire point.

They are regenerated on every graph build. A hand edit does not survive, and the
linter reports a stale index the same way it reports a stale graph.
"""

from __future__ import annotations

from pathlib import Path
from typing import Any, Optional

import portable_io
import trust_contract
from frontmatter_contract import FrontmatterError, parse_document


#: Actor recorded on every generated index, so its origin is visible in the file.
GENERATOR = "process:skillsafewerkstatt-navigation"

#: Directory holding the maintained knowledge layer.
WIKI_DIR = "wiki"

#: Reserved name of an index within its directory.
INDEX_NAME = "index.md"

#: Prose of a generated index, keyed by primary language. An index is a wiki
#: page, so its prose follows the wiki language like every other maintained
#: page. A code without a table here gets English prose; the `language` field
#: still carries the exact profile code, because the linter compares it verbatim.
FALLBACK_LANGUAGE = "en"
INDEX_TEXTS: dict[str, dict[str, str]] = {
    "de": {
        "notice": (
            "Diese Übersicht wird bei jedem Graphlauf neu erzeugt. Änderungen hier gehen "
            "verloren; pflege stattdessen die verlinkten Seiten."
        ),
        "description": "Übersicht der Seiten unter {directory}.",
        "empty": "Diese Gruppe enthält derzeit keine Seiten.",
    },
    "en": {
        "notice": (
            "This overview is regenerated on every graph build. Edits made here are "
            "lost; maintain the linked pages instead."
        ),
        "description": "Overview of the pages under {directory}.",
        "empty": "This group currently holds no pages.",
    },
}

#: Profile file that records the maintained wiki language.
PROFILE = "schema/WIKI_PROFILE.md"

#: Fixed timestamp component, so regenerating an unchanged wiki changes nothing.
STABLE_CREATED = "1970-01-01"


#: Longest description carried into an index. A branch index exists to let a
#: reader choose a page without opening it; a full abstract defeats the saving.
DESCRIPTION_BUDGET = 100

#: Values so common they carry no information when repeated on every line.
QUIET_STATUS = "active"
QUIET_TIER = trust_contract.UNVERIFIED


def render_entry(entry: dict[str, str]) -> str:
    """Render one page line, naming only what differs from the norm.

    Status and trust tier appear only when they are not the ordinary case. On a
    healthy wiki most pages are active and unconfirmed, so repeating that on
    every line would cost tokens to say nothing, and would bury the one page
    that is superseded or the one that a person actually reviewed.
    """
    parts: list[str] = []
    description = " ".join(entry["description"].split())
    if description:
        if len(description) > DESCRIPTION_BUDGET:
            description = description[: DESCRIPTION_BUDGET - 1].rstrip() + "…"
        parts.append(description)
    if entry["status"] and entry["status"] != QUIET_STATUS:
        parts.append(entry["status"])
    if entry["trust_tier"] != QUIET_TIER:
        parts.append(entry["trust_tier"])
    detail = " — ".join(parts)
    return f"- [[{entry['link']}|{entry['title']}]]{f' — {detail}' if detail else ''}"


def _read(path: Path, relative: str) -> Optional[dict[str, Any]]:
    try:
        document = parse_document(
            path.read_text(encoding="utf-8"), relative, require_frontmatter=True
        )
    except (OSError, UnicodeError, FrontmatterError):
        return None
    return document.data


def _label(data: dict[str, Any], path: Path) -> str:
    title = data.get("title")
    return str(title) if isinstance(title, str) and title.strip() else path.stem


def _quote(value: str) -> str:
    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'


def wiki_language(target: Path) -> str:
    """The exact language code every generated index must declare.

    Writer and linter both derive the expected index from this, so it is read
    from the profile rather than passed in, and both sides cannot drift apart.
    A wiki without a readable profile is invalid anyway and the linter reports
    that itself; the fallback only keeps generation deterministic until then.
    """
    data = _read(target / PROFILE, PROFILE)
    value = (data or {}).get("wiki_language")
    return value.strip() if isinstance(value, str) and value.strip() else FALLBACK_LANGUAGE


def index_texts(language: str) -> dict[str, str]:
    primary = language.split("-", 1)[0].casefold()
    return INDEX_TEXTS.get(primary, INDEX_TEXTS[FALLBACK_LANGUAGE])


def page_entries(directory: Path, target: Path) -> list[dict[str, str]]:
    """Describe every non-index page directly inside one directory."""
    entries: list[dict[str, str]] = []
    for path in sorted(directory.glob("*.md")):
        if path.name == INDEX_NAME:
            continue
        relative = path.relative_to(target).as_posix()
        data = _read(path, relative)
        if data is None:
            continue
        entries.append(
            {
                "link": relative.removesuffix(".md"),
                "title": _label(data, path),
                "description": str(data.get("description") or "").strip(),
                "status": str(data.get("status") or ""),
                "trust_tier": trust_contract.trust_tier(data),
            }
        )
    return entries


def render_index(
    relative: str, label: str, entries: list[dict[str, str]], updated: str, language: str
) -> str:
    """Render one directory index as an ordinary wiki page of type `index`."""
    text = index_texts(language)
    directory = relative.rsplit("/", 1)[0]
    lines = [
        "---",
        f"id: {_quote('wiki-index-' + label)}",
        f"title: {_quote(label.replace('-', ' ').capitalize())}",
        'type: "index"',
        'status: "active"',
        f"created: {_quote(STABLE_CREATED)}",
        f"updated: {_quote(updated)}",
        f"description: {_quote(text['description'].format(directory=directory))}",
        f"language: {_quote(language)}",
        f"generated_by: {_quote(GENERATOR)}",
        "sources: []",
        "clusters: []",
        "concepts: []",
        "tags:",
        '  - "type/wiki-index"',
        "---",
        "",
        f"# {label.replace('-', ' ').capitalize()}",
        "",
        text["notice"],
        "",
    ]
    if entries:
        for entry in entries:
            lines.append(render_entry(entry))
    else:
        lines.append(text["empty"])
    return "\n".join(lines) + "\n"


def expected_indexes(target: Path, updated: str) -> dict[str, str]:
    """Return the index each populated wiki subdirectory should currently have.

    Only directories that actually hold pages get one. An empty group needs no
    navigation, and creating one would add a file nobody asked for.
    """
    root = target / WIKI_DIR
    expected: dict[str, str] = {}
    if not root.is_dir():
        return expected
    language = wiki_language(target)
    for directory in sorted(path for path in root.iterdir() if path.is_dir()):
        entries = page_entries(directory, target)
        if not entries:
            continue
        relative = (directory / INDEX_NAME).relative_to(target).as_posix()
        expected[relative] = render_index(relative, directory.name, entries, updated, language)
    return expected


def stale_indexes(target: Path, updated: str) -> list[str]:
    """Report generated indexes that are missing, outdated, or no longer wanted.

    The `updated` field is ignored when comparing, so merely rebuilding on a
    later day never counts as drift.
    """
    expected = expected_indexes(target, updated)
    problems: list[str] = []
    for relative, content in expected.items():
        path = target / relative
        if not path.is_file():
            problems.append(f"{relative}: generated directory index is missing")
        elif _without_updated(path.read_text(encoding="utf-8")) != _without_updated(content):
            problems.append(f"{relative}: generated directory index is stale")
    root = target / WIKI_DIR
    if root.is_dir():
        for directory in sorted(path for path in root.iterdir() if path.is_dir()):
            relative = (directory / INDEX_NAME).relative_to(target).as_posix()
            if (target / relative).is_file() and relative not in expected:
                problems.append(f"{relative}: directory index is stale; the group holds no pages")
    return problems


def _without_updated(text: str) -> str:
    return "\n".join(
        line for line in text.splitlines() if not line.startswith("updated:")
    )


def write_indexes(target: Path, updated: str) -> list[str]:
    """Create, refresh, or remove the generated indexes. Returns what changed."""
    expected = expected_indexes(target, updated)
    changed: list[str] = []
    for relative, content in expected.items():
        path = target / relative
        current = path.read_text(encoding="utf-8") if path.is_file() else ""
        if _without_updated(current) == _without_updated(content):
            continue
        portable_io.atomic_write_text(path, content)
        changed.append(relative)
    root = target / WIKI_DIR
    if root.is_dir():
        for directory in sorted(path for path in root.iterdir() if path.is_dir()):
            relative = (directory / INDEX_NAME).relative_to(target).as_posix()
            path = target / relative
            # A group emptied by a page move keeps no orphan navigation behind.
            if path.is_file() and relative not in expected:
                path.unlink()
                changed.append(relative)
    return changed


def listing_indexes(target: Path) -> dict[str, str]:
    """Map each wiki page to the index that is allowed to list it.

    A page in a subdirectory belongs to that directory's index; a page directly
    under `wiki/` belongs to the root index.
    """
    mapping: dict[str, str] = {}
    root = target / WIKI_DIR
    if not root.is_dir():
        return mapping
    for path in sorted(root.rglob("*.md")):
        if path.name == INDEX_NAME:
            continue
        relative = path.relative_to(target).as_posix()
        parent = path.parent
        candidate = (parent / INDEX_NAME).relative_to(target).as_posix()
        mapping[relative] = candidate if parent != root else f"{WIKI_DIR}/{INDEX_NAME}"
    return mapping
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