code2okf 0.1.0__py3-none-any.whl

code2okf/kit/files/home/.pi/agent/skills/compile-okf/scripts/frontmatter-guard.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""Check the wiki conventions that the OKF spec floor deliberately leaves open.
+
+`okfctl validate` enforces the floor: every concept node carries a non-empty
+`type` (OKF v0.2 §11). Everything beyond that is a producer's choice, so the
+conventions this wiki settled on -- a title, a description, tags, provenance,
+and a well-formed update log -- need their own check. This is that check.
+
+Usage: frontmatter-guard.py [bundle]
+  bundle  wiki root to check (default: ., the workspace, which IS the wiki root)
+
+Exit codes:
+  0  clean
+  1  findings (one per line on stdout)
+  2  usage or runtime error (bad path, or SPEC.md could not be found)
+
+SPEC.md is read to learn which okf_version the root index must declare, so the
+check moves with the spec instead of hard-coding a number. It is looked up as
+the sibling of the bundle directory, which is one rule that covers both layouts:
+on the host the bundle is `./okf` and the spec is `./SPEC.md`; in the sandbox the
+workspace IS the bundle and the spec is the read-only `../SPEC.md` mount. Set
+SPEC_MD to override.
+
+Deliberately dependency-free: the sandbox installs a bare python3, so PyYAML is
+not available and the frontmatter is parsed directly. The parser understands the
+small YAML subset this wiki uses and reports anything it cannot read, rather than
+passing it silently.
+"""
+
+from __future__ import annotations
+
+import itertools
+import os
+import re
+import sys
+from pathlib import Path
+
+RESERVED = {"index.md", "log.md"}
+
+# §5: "Every timestamp-valued key in OKF is an ISO 8601 datetime with an explicit
+# UTC offset". A bare date is what the okfctl migrate bug produces, so rejecting
+# it here is load-bearing, not pedantry.
+ISO_UTC = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$"
+)
+
+# §7 actor convention: <producer>/<version>, human:<id>, or process:<id>.
+ACTOR = re.compile(r"^([^\s:/]+/[^\s:/]+|human:[^\s]+|process:[^\s]+)$")
+
+# The spec states its own revision as, e.g., "**Version 0.2**".
+SPEC_VERSION = re.compile(r"^\*\*Version\s+(\d+\.\d+)\*\*\s*$", re.MULTILINE)
+
+DATE_HEADING = re.compile(r"^##\s+(\d{4}-\d{2}-\d{2})\s*$", re.MULTILINE)
+
+
+def strip_quotes(value: str) -> str:
+    """Unwrap a quoted scalar, honouring the \\" escape the wiki's titles use."""
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        inner = value[1:-1]
+        return inner.replace('\\"', '"') if value[0] == '"' else inner
+    return value
+
+
+def split_flow(body: str) -> list[str]:
+    """Split a flow collection's body on commas that are not inside quotes."""
+    items, current, quote = [], [], ""
+    for char in body:
+        if quote:
+            if char == quote:
+                quote = ""
+            current.append(char)
+        elif char in "\"'":
+            quote = char
+            current.append(char)
+        elif char == ",":
+            items.append("".join(current))
+            current = []
+        else:
+            current.append(char)
+    items.append("".join(current))
+    return [item for item in (i.strip() for i in items) if item]
+
+
+def parse_scalar(value: str) -> object:
+    """Parse one YAML value: a flow sequence, a flow mapping, or a scalar."""
+    value = value.strip()
+    if value.startswith("[") and value.endswith("]"):
+        return [strip_quotes(item) for item in split_flow(value[1:-1])]
+    if value.startswith("{") and value.endswith("}"):
+        mapping = {}
+        for item in split_flow(value[1:-1]):
+            key, sep, val = item.partition(":")
+            if sep:
+                mapping[key.strip()] = strip_quotes(val)
+        return mapping
+    return strip_quotes(value)
+
+
+def parse_frontmatter(text: str) -> dict | None:
+    """Return the frontmatter block as a dict, or None when there is no block.
+
+    Handles the shapes this wiki uses: `key: value`, flow sequences and mappings,
+    a one-level block mapping (`generated:` with indented `by:`/`at:`), and a
+    block sequence of plain strings. A value is always split on the FIRST colon,
+    so a URL or a timestamp keeps its colons.
+    """
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---", 3)
+    if end == -1:
+        return None
+    block = text[4 : end + 1]
+
+    data: dict[str, object] = {}
+    key: str | None = None
+    for raw in block.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if raw[0] not in " \t-":
+            name, sep, value = raw.partition(":")
+            if not sep:
+                continue
+            key = name.strip()
+            data[key] = parse_scalar(value) if value.strip() else {}
+        elif key is not None:
+            item = raw.strip()
+            if item.startswith("- "):
+                existing = data.get(key)
+                if not isinstance(existing, list):
+                    existing = []
+                    data[key] = existing
+                existing.append(strip_quotes(item[2:]))
+            else:
+                name, sep, value = item.partition(":")
+                if sep and isinstance(data.get(key), dict):
+                    data[key][name.strip()] = strip_quotes(value)  # type: ignore[index]
+    return data
+
+
+def spec_version(bundle: Path) -> str:
+    """The okf_version the root index must declare, read from SPEC.md."""
+    override = os.environ.get("SPEC_MD")
+    spec = Path(override) if override else bundle.resolve().parent / "SPEC.md"
+    if not spec.is_file():
+        sys.exit(
+            f"Error: SPEC.md not found at {spec}. It is looked up as the sibling "
+            "of the bundle; set SPEC_MD to override."
+        )
+    match = SPEC_VERSION.search(spec.read_text(encoding="utf-8"))
+    if not match:
+        sys.exit(f"Error: no '**Version X.Y**' line in {spec}.")
+    return match.group(1)
+
+
+def check_node(path: Path, rel: str, findings: list[str]) -> None:
+    """Check one concept node's frontmatter."""
+    data = parse_frontmatter(path.read_text(encoding="utf-8"))
+    if data is None:
+        findings.append(f"frontmatter: {rel} has no parseable YAML frontmatter block")
+        return
+
+    for field in ("title", "description"):
+        value = data.get(field)
+        if not isinstance(value, str) or not value.strip():
+            findings.append(f"{field}: {rel} has no non-empty {field}")
+
+    tags = data.get("tags")
+    if not isinstance(tags, list) or not tags:
+        findings.append(f"tags: {rel} has no tags list (a non-empty YAML list)")
+    elif not all(isinstance(tag, str) and tag.strip() for tag in tags):
+        findings.append(f"tags: {rel} has a tags list with a non-string entry")
+
+    check_provenance(rel, data, findings)
+
+
+def check_provenance(rel: str, data: dict, findings: list[str]) -> None:
+    """Check §5.2 `generated: { by, at }`.
+
+    The wiki was migrated to v0.2, so the legacy v0.1 `timestamp` key is a
+    finding rather than an accepted fallback: §13.1 lets a *consumer* fall back
+    to it, but a producer writing new v0.2 pages has no reason to emit one, and
+    silently accepting it would let the corpus drift back.
+    """
+    generated = data.get("generated")
+    if isinstance(generated, dict) and generated:
+        by = str(generated.get("by", "")).strip()
+        at = str(generated.get("at", "")).strip()
+        if not ACTOR.match(by):
+            findings.append(
+                f"generated.by: {rel} has {by!r}, not a §7 actor "
+                "(<producer>/<version>, human:<id>, or process:<id>)"
+            )
+        if not ISO_UTC.match(at):
+            findings.append(
+                f"generated.at: {rel} has {at!r}, not an ISO 8601 datetime with "
+                "an explicit UTC offset (§5)"
+            )
+        return
+
+    if data.get("timestamp"):
+        findings.append(
+            f"generated: {rel} carries a legacy v0.1 `timestamp`; v0.2 §13.1 "
+            "supersedes it with `generated: { by, at }` (§5.2)"
+        )
+        return
+
+    findings.append(
+        f"generated: {rel} records no provenance (§5.2 `generated: {{ by, at }}`)"
+    )
+
+
+def check_root_index(bundle: Path, findings: list[str]) -> None:
+    """§12: the bundle-root index declares okf_version, and nothing else."""
+    index = bundle / "index.md"
+    if not index.is_file():
+        findings.append("index: the bundle root has no index.md")
+        return
+    data = parse_frontmatter(index.read_text(encoding="utf-8"))
+    if data is None:
+        findings.append(
+            "okf_version: index.md carries no frontmatter block; the bundle-root "
+            "index declares the spec version (§12)"
+        )
+        return
+    want = spec_version(bundle)
+    got = str(data.get("okf_version", "")).strip()
+    if got != want:
+        findings.append(
+            f"okf_version: index.md declares {got!r} but SPEC.md is version {want!r}"
+        )
+    extra = sorted(key for key in data if key != "okf_version")
+    if extra:
+        findings.append(
+            "okf_version: index.md frontmatter may contain only okf_version (§12); "
+            f"found {', '.join(extra)}"
+        )
+
+
+def check_log(bundle: Path, findings: list[str]) -> None:
+    """§9: log.md exists, and its date headings are ISO 8601, newest first."""
+    log = bundle / "log.md"
+    if not log.is_file():
+        findings.append("log: the bundle root has no log.md (§9)")
+        return
+    dates = DATE_HEADING.findall(log.read_text(encoding="utf-8"))
+    if not dates:
+        findings.append("log: log.md has no '## YYYY-MM-DD' date headings (§9)")
+        return
+    for earlier, later in itertools.pairwise(dates):
+        if earlier < later:
+            findings.append(
+                f"log: log.md heading {later} follows {earlier}; dates run "
+                "newest first (§9)"
+            )
+
+
+def main(argv: list[str]) -> int:
+    bundle = Path(argv[1] if len(argv) > 1 else ".")
+    if not bundle.is_dir():
+        sys.exit(f"Error: wiki bundle not found: {bundle}")
+
+    findings: list[str] = []
+    for path in sorted(bundle.rglob("*.md")):
+        if path.name in RESERVED:
+            continue
+        check_node(path, str(path.relative_to(bundle)), findings)
+    check_root_index(bundle, findings)
+    check_log(bundle, findings)
+
+    if not findings:
+        print("OK: frontmatter, provenance and log conventions hold")
+        return 0
+    for finding in findings:
+        print(finding)
+    print(f"{len(findings)} guard finding(s)")
+    return 1
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except SystemExit as exc:
+        # sys.exit(str) prints the message and exits 1; this guard's contract
+        # reserves 1 for findings and 2 for "could not run", so remap.
+        if isinstance(exc.code, str):
+            print(exc.code, file=sys.stderr)
+            sys.exit(2)
+        raise

code2okf/kit/files/home/.pi/agent/skills/curate-okf/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: curate-okf
+description: Check the wiki against the OKF spec and its curation health, and maintain nodes and indexes without breaking links. Use before finishing a run, and whenever adding, moving or removing a page.
+---
+
+# Curate the wiki with `okfctl`
+
+Use the `okfctl` CLI (on `PATH`) to check the wiki and to maintain its nodes and
+reserved `index.md` files. The skill name is `curate-okf`; the binary is
+`okfctl` — never shell the skill id.
+
+## Invocation
+
+```bash
+okfctl index build "$PWD"           # after adding, moving or removing a page
+okfctl analyze "$PWD"               # where the wiki is weak — advice, never a gate
+okfctl node mv old.md new.md --bundle "$PWD"   # rename, rewriting inbound links
+```
+
+- **Always name the wiki as `"$PWD"`.** You are already in the wiki root, and
+  okfctl's own default is the current directory, but the explicit path keeps a
+  command copied into a skill or a log unambiguous.
+- `index build` **owns every `index.md`** — never hand-edit one. It regenerates
+  the link lists from what is on disk, so an index can never promise a page that
+  does not exist.
+- `node mv` rewrites every inbound link and preserves each link's existing form,
+  so bundle-absolute prose links stay absolute.
+- Allowed beyond the above: `validate`, `lint`, `bundle info`, `index check`,
+  `node list|show|new|rm`, `search`, `graph export`, `template list|show`,
+  `version`.
+- Exit codes: `0` ok, `1` findings, `2` usage or runtime error.
+
+## Workflow
+
+Write the pages first, then `okfctl index build`, then the gate —
+`~/.pi/agent/skills/compile-okf/scripts/check-okf.sh`, which runs `validate`,
+the frontmatter guard, `lint`, the dangling-link check and `index check` in one
+pass. Rebuild the index *before* the gate: `index check` fails closed, so a page
+added without a rebuild is reported as both a stale index and an orphan.
+
+`okfctl node new` writes `created`/`modified`, **not** the `generated: { by, at }`
+this wiki uses — fill the frontmatter in yourself afterwards, as `AGENTS.md`
+describes. The guard catches it if you forget.
+
+## Reading the output
+
+`lint` findings come in two classes, and the gate treats them differently:
+
+| Class | Checks | What to do |
+| --- | --- | --- |
+| Defect | `broken-link`, `orphan`, `type-hygiene`, `status-lifecycle`, `spec-version` | **Blocks the run.** Each has one correct fix — repair the path, link or rebuild the index. |
+| Judgment | `missing-xref`, `coverage-gap` | Printed, never blocking. Act on it when the wiki genuinely reads better for it. |
+
+`analyze` is a report, not a gate: thin pages, uncited pages and tag clusters are
+prompts for judgment. It exits `0` however much it finds.
+
+## Limits
+
+- **Never run `log append` or `log show`.** They write a second `# Change Log`
+  heading in a flat format that contradicts the spec's dated `##` headings. Write
+  `log.md` by hand, as `AGENTS.md` describes.
+- **Never run `migrate`, `eval`, `serve`, `registry`, `connect`, or anything
+  semantic** (`okfctl-search`, `lint --semantic`). `migrate` is a one-off the
+  maintainers have already run; the rest need a network or a model this sandbox
+  does not have.
+- A clean gate means the wiki is well-formed and well-linked. It says nothing
+  about whether the prose is faithful to the source — that is `compile-okf`'s
+  fidelity rule, and it outranks a clean report.

code2okf/kit/files/home/.pi/agent/skills/inspect-md/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: inspect-md
+description: Map headings in a long Markdown source under ../md/ before reading it in ranges. Use when a source is too large to pull into one call.
+---
+
+# Map a long Markdown source with `inspectmd`
+
+Use the `inspectmd` CLI (on `PATH`) to plan ranged reads of a file under
+`../md/`.
+The skill name is `inspect-md`; the binary is `inspectmd` — never shell the
+skill id.
+
+## Invocation
+
+```bash
+inspectmd ../md/<document>.md
+inspectmd -L 2 ../md/<document>.md
+inspectmd --section N ../md/<document>.md
+```
+
+- Requires a Markdown **file** path (not a directory).
+- `-L`/`--level N` caps the map at heading level `N` (`N` ≥ 1). Omit for every
+  heading.
+- `--section N` prints only `start:end  N words` for a ranged read.
+- Exit codes: `0` ok, `2` usage or runtime error.
+
+## Workflow
+
+Map → cut → read. Do **not** treat `-L` as a directory depth (that is the wiki
+tools).
+
+1. Run `inspectmd -L 2 ../md/<document>.md` (or without `-L` if you need deeper
+   headings).
+2. Pick a section `Index`, then `inspectmd --section N ../md/<document>.md`.
+3. Ranged-read that line span — never pull a whole book into one call.
+
+## Reading the output
+
+| Column | Meaning |
+| --- | --- |
+| `Index` | Section number in document order (`0` = preamble when present). Pass this to `--section`. |
+| `Level` | Heading depth: `0` preamble, `1` = `#`, …, `6` = `######`. |
+| `Lines` | 1-based inclusive line range (`start-end`) for that section. |
+| `Words` | Whitespace-split word count of that range. |
+| `Slug` | Kebab-case slug from the heading title (same style as OKF file names). |
+| `Title` | Heading text as written (or `(preamble)` / `(empty)`). |
+
+## Limits
+
+- Maps **ATX headings only** (`#` … `######`).
+- The map is a plan for cuts and reads — **not** permission to paraphrase source
+  prose. The fidelity rule in `compile-okf` still governs.

code2okf/kit/files/home/.pi/agent/skills/inspect-okf/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: inspect-okf
+description: Survey what the OKF wiki already contains before writing. Use when choosing where to place or update wiki pages.
+---
+
+# Survey the wiki with `inspectokf`
+
+Use the `inspectokf` CLI (on `PATH`) to see what the wiki already holds. The
+skill name is `inspect-okf`; the binary is `inspectokf` — never shell the
+skill id.
+
+## Invocation
+
+```bash
+inspectokf -L 1 "$PWD"          # top level only: the categories — start here
+inspectokf "$PWD/<topic>"       # then descend into the one category you need
+inspectokf "$PWD"               # every page: hundreds of lines — avoid opening with this
+```
+
+- **Always name the wiki as `"$PWD"`**. You are already in the wiki root; the
+  CLI's own default (`okf/`) is for host-side use and would select an invalid
+  nested `okf/` directory here. Any existing directory works, typically a wiki
+  subfolder.
+- `-L`/`--level N` descends at most `N` directory levels (`N` ≥ 1). Default:
+  unlimited.
+- Output is the `tree` listing of that path. An empty or dotfile-only directory
+  exits `0` with `0 directories, 0 files` and does not require `tree`.
+- Exit codes: `0` ok, `2` usage or runtime error.
+
+## Workflow
+
+Shallow first, then descend into the one path that matters. Do not open with the
+full unlimited tree.
+
+## Reading the output
+
+Each line is a path that exists on disk. Folders and files appear as `tree`
+renders them. Use this to find pages already covering a topic before writing.
+
+## Limits
+
+- Hides **dotfiles**, so anything starting with `.` is invisible here.
+- Slugs are lossy (`1981.md`, `exams.md` say nothing about content) — open the
+  page when you need substance.
+- A page listed here may still be **unreachable in the wiki** if no `index.md`
+  links it. The gate does catch that — `okfctl lint` reports it as an `orphan`,
+  which usually means the indexes need `okfctl index build`.

code2okf/kit/files/home/.pi/agent/skills/merkle-okf/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: merkle-okf
+description: Confirm which wiki pages a run actually changed via Merkle hashes. Use before and after writing to the wiki.
+---
+
+# Confirm what changed with `merkleokf`
+
+Use the `merkleokf` CLI (on `PATH`) to localise edits in the wiki. The skill
+name is `merkle-okf`; the binary is `merkleokf` — never shell the skill id.
+
+## Invocation
+
+```bash
+merkleokf -L 1 "$PWD"                     # categories — capture before and after
+merkleokf "$PWD/<topic>"                  # descend where a hash moved
+merkleokf "$PWD/<topic>/<page>.md"        # a single file
+```
+
+- **Always name the wiki as `"$PWD"`**. You are already in the wiki root; the
+  CLI's own default (`okf/`) is for host-side use and would select an invalid
+  nested `okf/` directory here. The absolute path also preserves the root name
+  that `--nolog` relies on.
+- Pass a directory or a single Markdown file.
+- `-L`/`--level N` lists entries at most `N` directory levels deep (`N` ≥ 0;
+  `0` = walk root only; ignored for a file). Default: unlimited. Digests always
+  cover the full subtree.
+- `--nolog` omits the wiki's root `log.md` from the listing and digests
+  (nested `log.md` still hashed; ignored for a single file).
+- Exit codes: `0` ok, `2` usage or runtime error.
+
+## Workflow
+
+Needs a **before** and an **after** listing — one post-write run alone cannot
+localise anything.
+
+1. Before writing: `merkleokf -L 1 "$PWD"` and keep the listing.
+2. After writing: run it again and diff against the baseline.
+3. Descend only into folders whose hash moved; folders whose hash is unchanged
+   are provably untouched.
+
+## Reading the output
+
+A table (no summary line). The walk root is always the first path listed when
+sorted alphabetically:
+
+| Column | Meaning |
+| --- | --- |
+| `Hash` | First 12 hex characters of the SHA-256 digest (Merkle digest for folders). |
+| `Files` | Markdown files covered. Always `1` for a file. |
+| `Path` | Rooted at the hashed directory's name (e.g. `okf/…`). Folders end in `/`. |
+
+Rows are sorted alphabetically so two runs diff line by line.
+
+## Limits
+
+- Hashes **raw bytes — frontmatter included**. A timestamp or tag edit counts as
+  a change (unlike `sizeokf`).
+- A moved hash proves *that* something changed, never that the change is
+  correct. Lint still gates conformance.

code2okf/kit/files/home/.pi/agent/skills/size-okf/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: size-okf
+description: Measure how much Markdown prose a page or category holds, excluding YAML frontmatter. Use when judging whether a page is thin or a category is unbalanced.
+---
+
+# Measure wiki content with `sizeokf`
+
+Use the `sizeokf` CLI (on `PATH`) to count content words in the wiki. The
+skill name is `size-okf`; the binary is `sizeokf` — never shell the skill id.
+
+## Invocation
+
+```bash
+sizeokf -L 1 "$PWD"          # words per category — start here
+sizeokf "$PWD/<topic>"       # then per page within one category
+sizeokf "$PWD"               # every file and folder (large)
+```
+
+- **Always name the wiki as `"$PWD"`**. You are already in the wiki root; the
+  CLI's own default (`okf/`) is for host-side use and would select an invalid
+  nested `okf/` directory here. The absolute path also preserves the root name
+  that `--nolog` relies on. Any existing directory works.
+- `-L`/`--level N` lists entries at most `N` directory levels deep (`N` ≥ 0;
+  `0` = walk root only). Default: unlimited. Folder **totals** are always
+  recursive.
+- `--nolog` omits the wiki's root `log.md` from the listing and totals (nested
+  `log.md` still counted).
+- Exit codes: `0` ok, `2` usage or runtime error.
+
+## Workflow
+
+Shallow first (`sizeokf -L 1`), then descend into the one category you care
+about. Same `-L` pattern as `inspectokf`, different question: how much is
+written, not what exists.
+
+## Reading the output
+
+A table (no summary line). The walk root is always listed:
+
+| Column | Meaning |
+| --- | --- |
+| `Words` | Whitespace-split words of Markdown **content**, frontmatter excluded. Recursive for folders. |
+| `Files` | Markdown files counted. Always `1` for a file. |
+| `Path` | Rooted at the measured directory's name (e.g. `okf/…`). Folders end in `/`. |
+
+Rows are sorted largest first.
+
+## Limits
+
+- Counts **content only** — says nothing about frontmatter bulk.
+- Never use it to reason about frontmatter itself; use `merkleokf` when asking
+  whether bytes changed.