@rckflr/llms-skills 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,7 +4,41 @@ All notable changes to the [`@rckflr/llms-skills`](https://www.npmjs.com/package
 package. Format based on [Keep a Changelog](https://keepachangelog.com/); dates
 are the npm publish dates.
 
-## [Unreleased] — 0.3.0
+## [Unreleased] — 0.4.0
+
+### Added
+- **Signed knowledge freshness — the RAG-OKF v2 "vigencia" layer.** Two new
+  commands over a knowledge bundle, porting the proven
+  `ccdd/examples/okf-integration` sidecar and staying **wire-compatible**
+  with its Python tooling (same signed message
+  `vigencia:{concept}:{content_sha256}:{attested_at}:{valid_until}`, same
+  raw-hex ed25519 keys/signatures, same `freshness.yaml` /
+  `attestations.json` / `reviewers.json` files — attestations sign/verify
+  across both toolchains, covered by a verbatim fixture signed with the
+  Python reference):
+  - **`freshness <bundle> [--now ISO] [--json]`** — CI-friendly report of
+    three honestly-separated signals: content hashes say *not tampered*
+    (publish), age vs per-`type` TTLs says *recent* (a proxy — age ≠ truth),
+    and a signed human attestation says *still true*. Statuses: `fresh` /
+    `STALE` / `MISSING-TS` / `untracked` / `VIGENT` / `VOID-ATTEST` /
+    `EXPIRED-ATTEST` / `INVALID-ATTEST`. `on_stale: abort` turns stale
+    knowledge into a failing exit code.
+  - **`attest <bundle> --concept <rel.md> --by <reviewer> --until <ISO>
+    --key <hex-file>`** — a registered human signs "this content is still
+    true". The signature binds to the exact content sha (any edit voids it)
+    and expires at `--until` (re-affirmable without touching content); the
+    signing key must match the reviewer's registered pubkey. The machine
+    binds, verifies and expires; the human judges.
+- Note: `content_sha256` is over **raw** file bytes (Python-reference
+  compatibility, no CRLF normalization) — pin your bundle's markdown
+  (`*.md text eol=lf` or `-text`) so git line-ending conversion cannot void
+  attestations.
+- Hybrid embeddings (the other half of the v2 design) remain **not built**,
+  blocked upstream: `@rckflr/minimemory`'s OKF index is BM25-only by design,
+  there is no embedder in the stack, and float embeddings clash with
+  byte-exact content addressing.
+
+## [0.3.0] — 2026-07-10
 
 ### Added
 - **`--scope <name>` on `memory`** (Executable Skills v0.5 §2.5, resolves

package/README.md

@@ -89,6 +89,35 @@ verifies the snapshot and injects `host.memorySearch` on both runtimes.
 default; if omitted, `memory` fails with a clear message and every other
 command works as before.
 
+## Knowledge freshness (`freshness` / `attest`)
+
+Hashes prove *not tampered*; they say nothing about whether the content is
+still **true**. The freshness layer separates three signals honestly:
+
+```bash
+npx @rckflr/llms-skills freshness ./knowledge --now 2026-07-10   # CI report
+npx @rckflr/llms-skills attest ./knowledge --concept policies/refunds.md \
+    --by human:mauricio --until 2027-07-10 --key mauricio.key    # sign "still true"
+```
+
+- **Age vs TTL** (`knowledge/freshness.yaml`): per-`type` TTL in days +
+  per-path overrides. A concept past its TTL reports `STALE`; `on_stale:
+  abort` makes the command exit 1 (CI gate). Age is a *proxy* — old-but-true
+  passes as stale, new-but-false passes as fresh. Which is why:
+- **Signed attestations** (`knowledge/attestations.json`): a reviewer
+  registered in `knowledge/reviewers.json` (raw-hex ed25519 pubkey) signs
+  "this content is still true". The signature binds to the exact content
+  sha — **any edit voids it** — and expires at `valid_until`, re-affirmable
+  without touching the content. A valid attestation supersedes age
+  (`VIGENT`); tampering, expiry or an unregistered reviewer degrade it
+  loudly (`VOID-ATTEST` / `EXPIRED-ATTEST` / `INVALID-ATTEST`).
+
+Wire-compatible with the original Python sidecar
+(`ccdd/examples/okf-integration`): attestations sign/verify across both
+toolchains. Note: the content sha is over raw bytes — pin your bundle's
+markdown (`*.md text eol=lf`) so git CRLF conversion cannot void
+attestations.
+
 ## Signing / attestation (L3)
 
 ```bash

package/bin/llms-skills.mjs

@@ -11,12 +11,13 @@
 // Zero external dependencies.
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join, dirname, relative } from "node:path";
+import { join, dirname, relative, isAbsolute } from "node:path";
 import {
   loadSkills, loadMemory, renderSkillsSection, renderSkillsMemoryLine, renderLlmsTxt,
   renderIndex, loadSigningKey, signSkills, publicKeyRawB64, generateKeyPair, validateLlmsTxt,
 } from "../lib/core.mjs";
 import { buildMemoryTargets } from "../lib/memory.mjs";
+import { checkFreshness, attestVigencia } from "../lib/freshness.mjs";
 
 const args = process.argv.slice(2);
 const cmd = args[0];
@@ -33,6 +34,13 @@ Usage:
                                                     OKF bundle -> BM25 snapshot + knowledge skills (RAG)
   llms-skills publish [--check] [--manifest <p>] [--root <dir>]   generate llms.txt ## Skills + index.json
   llms-skills validate <src> [--strict]             validate an llms.txt (path or URL)
+  llms-skills freshness <bundle-dir> [--now <ISO>] [--json] [--root <dir>]
+                                                    check knowledge freshness: TTLs (freshness.yaml)
+                                                    + signed human attestations (attestations.json)
+  llms-skills attest <bundle-dir> --concept <rel.md> --by <reviewer> --until <ISO>
+                     --key <privkey-hex-file> [--on <ISO>] [--note <text>] [--root <dir>]
+                                                    sign "this content is still true" (ed25519,
+                                                    voided on edit, expires at --until)
   llms-skills keygen [--out <keyfile>]              generate an ed25519 signing keypair
 
 The minimal case (L0) needs no signing key and no tool.js — just init + publish.
@@ -237,6 +245,47 @@ function cmdKeygen() {
 }
 
 // ---- dispatch ----
+// ---- freshness (RAG-OKF v2: signed knowledge freshness) ----
+function resolveBundle(cmdName) {
+  const bundleArg = args[1];
+  if (!bundleArg || bundleArg.startsWith("--")) die(`${cmdName}: needs a bundle directory, e.g. \`llms-skills ${cmdName} ./knowledge\``);
+  const root = flag("--root") || process.cwd();
+  const bundleDir = isAbsolute(bundleArg) ? bundleArg : join(root, bundleArg);
+  if (!existsSync(bundleDir)) die(`${cmdName}: bundle directory not found: ${bundleDir}`);
+  return bundleDir;
+}
+
+function cmdFreshness() {
+  const bundleDir = resolveBundle("freshness");
+  const now = flag("--now") || new Date().toISOString().slice(0, 10);
+  const result = checkFreshness(bundleDir, now, (w) => console.error(`[warn] ${w}`));
+  if (has("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`FRESHNESS @ ${result.now}  (on_stale=${result.on_stale})`);
+    for (const r of result.concepts) {
+      const age = r.age_days === null || r.age_days === undefined ? "-" : `${r.age_days}d`;
+      const ttl = r.ttl_days === null || r.ttl_days === undefined ? "-" : `${r.ttl_days}d`;
+      const rem = r.remaining_days !== undefined && r.status === "fresh" ? `  (${r.remaining_days}d left)` : "";
+      const extra = r.detail ? `  [${r.by || "-"}] ${r.detail}` : "";
+      console.log(`  [${String(r.status).padStart(14)}] ${r.concept.padEnd(32)} age=${age.padEnd(5)} ttl=${ttl}${rem}${extra}`);
+    }
+    console.log(`  stale=${result.stale}  missing_required_ts=${result.missing_required_ts}`);
+  }
+  if (result.fail) process.exit(1);
+}
+
+// ---- attest (sign one freshness attestation) ----
+function cmdAttest() {
+  const bundleDir = resolveBundle("attest");
+  const concept = flag("--concept"); const by = flag("--by");
+  const until = flag("--until"); const keyPath = flag("--key");
+  if (!concept || !by || !until || !keyPath) die("attest: --concept, --by, --until and --key are required");
+  const on = flag("--on") || new Date().toISOString().slice(0, 10);
+  const entry = attestVigencia({ bundleDir, concept, by, on, until, keyPath, note: flag("--note") || "" });
+  console.log(`ATTESTED+SIGNED: ${concept} fresh per ${by} until ${until} (sha ${entry.content_sha256.slice(0, 8)}..., sig ${entry.signature.slice(0, 8)}...)`);
+}
+
 (async () => {
   try {
     switch (cmd) {
@@ -244,6 +293,8 @@ function cmdKeygen() {
       case "memory": await cmdMemory(); break;
       case "publish": cmdPublish(); break;
       case "validate": await cmdValidate(); break;
+      case "freshness": cmdFreshness(); break;
+      case "attest": cmdAttest(); break;
       case "keygen": cmdKeygen(); break;
       case "-h": case "--help": case "help": case undefined: console.log(USAGE); break;
       default: die(`Unknown command: ${cmd}\n\n${USAGE}`);

package/lib/freshness.mjs

@@ -0,0 +1,271 @@
+// freshness.mjs — signed knowledge freshness (RAG-OKF v2, "vigencia").
+//
+// Port of ccdd/examples/okf-integration (check_freshness.py + attest_vigencia.py),
+// kept WIRE-COMPATIBLE with that Python tooling: same signed message
+// `vigencia:{concept}:{content_sha256}:{attested_at}:{valid_until}`, same raw-hex
+// ed25519 keys/signatures, same bundle-root files (freshness.yaml,
+// attestations.json, reviewers.json). An attestation signed by either toolchain
+// verifies in the other.
+//
+// Three distinct signals, honestly separated:
+//   - content hashes (publish) say "not tampered";
+//   - age vs TTL (freshness.yaml) says "recent" — a PROXY, age != truth;
+//   - a SIGNED human attestation says "still true", bound to the exact
+//     content sha (voided by any edit) and expiring at valid_until
+//     (re-affirmable without touching content). The machine binds, verifies
+//     and expires; the human judges.
+//
+// NOTE on hashing: content_sha256 here is over the RAW file bytes (no CRLF
+// normalization) for compatibility with the Python reference. On Windows,
+// git autocrlf can rewrite *.md on checkout and spuriously void attestations —
+// pin your bundle's markdown as `*.md text eol=lf` (or -text) in .gitattributes.
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { createHash, createPublicKey, createPrivateKey, sign as cryptoSign, verify as cryptoVerify } from "node:crypto";
+import { privateKeyFromSeed } from "./core.mjs";
+
+const RESERVED = new Set(["index.md", "log.md"]);
+const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export function sha256RawFile(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+export function vigenciaMsg(concept, contentSha, on, until) {
+  return Buffer.from(`vigencia:${concept}:${contentSha}:${on}:${until}`, "utf8");
+}
+
+export function signVigenciaHex(privHex, msgBuf) {
+  const seed = Buffer.from(privHex.trim(), "hex");
+  if (seed.length !== 32) throw new Error("private key must be 32 raw ed25519 bytes in hex");
+  return cryptoSign(null, msgBuf, privateKeyFromSeed(seed)).toString("hex");
+}
+
+export function verifyVigenciaHex(pubHex, msgBuf, sigHex) {
+  try {
+    const raw = Buffer.from(String(pubHex), "hex");
+    if (raw.length !== 32) return false;
+    const pub = createPublicKey({ key: Buffer.concat([SPKI_ED25519_PREFIX, raw]), format: "der", type: "spki" });
+    return cryptoVerify(null, msgBuf, pub, Buffer.from(String(sigHex), "hex"));
+  } catch {
+    return false;
+  }
+}
+
+// ---- minimal YAML subset parser for freshness.yaml --------------------------
+// Supports exactly the reference file shape: top-level scalars, one-level
+// nested maps (defaults/overrides), and inline lists ([A, B]). Comments and
+// blank lines ignored. Anything deeper is out of scope (fail loud, not wrong).
+export function parseFreshnessYaml(text) {
+  const root = {};
+  let current = null; // name of the open nested map
+  for (const rawLine of text.split(/\r?\n/)) {
+    const noComment = rawLine.replace(/(^|\s)#.*$/, "");
+    if (!noComment.trim()) continue;
+    const indented = /^\s/.test(noComment);
+    const m = noComment.trim().match(/^("?)([^":]+)\1\s*:\s*(.*)$/);
+    if (!m) throw new Error(`freshness.yaml: unsupported line: ${rawLine.trim()}`);
+    const key = m[2].trim();
+    let val = m[3].trim();
+    if (indented) {
+      if (!current) throw new Error(`freshness.yaml: indented key '${key}' outside a map`);
+      root[current][key] = coerce(val);
+      continue;
+    }
+    if (val === "") {
+      root[key] = {};
+      current = key;
+      continue;
+    }
+    current = null;
+    root[key] = coerce(val);
+  }
+  return root;
+
+  function coerce(v) {
+    if (/^\[.*\]$/.test(v)) {
+      const inner = v.slice(1, -1).trim();
+      return inner === "" ? [] : inner.split(",").map((s) => s.trim().replace(/^["']|["']$/g, ""));
+    }
+    v = v.replace(/^["']|["']$/g, "");
+    if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+    return v;
+  }
+}
+
+// ---- frontmatter timestamp --------------------------------------------------
+function parseDateISO(s) {
+  const m = String(s).trim().match(/^(\d{4})-(\d{2})-(\d{2})/);
+  if (!m) return null;
+  const d = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]));
+  return isNaN(d.getTime()) ? null : d;
+}
+const dayDiff = (a, b) => Math.floor((a.getTime() - b.getTime()) / 86400000);
+
+function loadFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/);
+    if (!kv) continue;
+    let v = kv[2].trim();
+    if (v.length >= 2 && ((v[0] === '"' && v.at(-1) === '"') || (v[0] === "'" && v.at(-1) === "'"))) v = v.slice(1, -1);
+    fm[kv[1]] = v;
+  }
+  return fm;
+}
+
+function* walkMd(dir, rel = "") {
+  for (const name of readdirSync(dir).sort()) {
+    const full = join(dir, name);
+    const r = rel ? rel + "/" + name : name;
+    if (statSync(full).isDirectory()) yield* walkMd(full, r);
+    else if (name.endsWith(".md") && !RESERVED.has(name)) yield [full, r];
+  }
+}
+
+function loadJsonIf(path, label, warn) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    warn(`could not load ${label}: ${e.message}`);
+    return null;
+  }
+}
+
+// ---- check ------------------------------------------------------------------
+// Returns { now, stale, missingRequiredTs, onStale, concepts: rows, fail }.
+export function checkFreshness(bundleDir, nowISO, warn = () => {}) {
+  const polPath = join(bundleDir, "freshness.yaml");
+  if (!existsSync(polPath)) throw new Error(`freshness.yaml not found in ${bundleDir}`);
+  const pol = parseFreshnessYaml(readFileSync(polPath, "utf8"));
+  const now = parseDateISO(nowISO);
+  if (!now) throw new Error("--now must be ISO (YYYY-MM-DD)");
+
+  const defaults = pol.defaults || {};
+  const overrides = pol.overrides || {};
+  let onStale = pol.on_stale || "warn";
+  if (onStale !== "warn" && onStale !== "abort") {
+    warn(`unknown on_stale '${onStale}'; using 'warn'`);
+    onStale = "warn";
+  }
+  const requireTs = new Set(pol.require_timestamp_for_types || []);
+
+  const attData = loadJsonIf(join(bundleDir, "attestations.json"), "attestations.json", warn);
+  const attestations = {};
+  for (const a of (attData && Array.isArray(attData.attestations) ? attData.attestations : [])) {
+    if (a && typeof a === "object" && a.concept) attestations[a.concept] = a;
+  }
+  const reviewers = loadJsonIf(join(bundleDir, "reviewers.json"), "reviewers.json", warn) || {};
+
+  const rows = [];
+  let stale = 0, missing = 0;
+  for (const [full, rel] of walkMd(bundleDir)) {
+    const fm = loadFrontmatter(readFileSync(full, "utf8"));
+    if (fm === null) continue;
+    const ctype = fm.type;
+    const ttl = rel in overrides ? overrides[rel] : (ctype in defaults ? defaults[ctype] : null);
+
+    // Authoritative signal: a SIGNED human freshness attestation supersedes
+    // age — honored only if the ed25519 signature verifies against a reviewer
+    // registered in reviewers.json (the trust root).
+    const att = attestations[rel];
+    if (att !== undefined) {
+      const by = att.attested_by;
+      const pub = by ? reviewers[by] : undefined;
+      const signedSha = att.content_sha256 || "";
+      const msg = vigenciaMsg(rel, signedSha, att.attested_at || "", att.valid_until || "");
+      const sigOk = typeof pub === "string" && verifyVigenciaHex(pub, msg, att.signature || "");
+      if (!sigOk) {
+        stale++;
+        rows.push({ concept: rel, type: ctype, age_days: null, ttl_days: ttl, status: "INVALID-ATTEST", by, detail: "missing/invalid signature or unregistered reviewer" });
+        continue;
+      }
+      if (signedSha !== sha256RawFile(full)) {
+        stale++;
+        rows.push({ concept: rel, type: ctype, age_days: null, ttl_days: ttl, status: "VOID-ATTEST", by, detail: "content changed since attestation; re-attest" });
+        continue;
+      }
+      const until = att.valid_until ? parseDateISO(att.valid_until) : null;
+      if (!until || now.getTime() > until.getTime()) {
+        stale++;
+        rows.push({ concept: rel, type: ctype, age_days: null, ttl_days: ttl, status: "EXPIRED-ATTEST", by, detail: `attestation expired ${att.valid_until || "(no valid_until)"}; re-attest` });
+        continue;
+      }
+      rows.push({ concept: rel, type: ctype, age_days: null, ttl_days: ttl, status: "VIGENT", by, detail: `attested fresh until ${att.valid_until}` });
+      continue;
+    }
+
+    const ts = fm.timestamp !== undefined ? parseDateISO(fm.timestamp) : null;
+    if (!ts) {
+      const sev = requireTs.has(ctype) ? "MISSING-TS" : "no-ts";
+      if (sev === "MISSING-TS") missing++;
+      rows.push({ concept: rel, type: ctype, age_days: null, ttl_days: ttl, status: sev });
+      continue;
+    }
+    if (ttl === null || ttl === undefined) {
+      rows.push({ concept: rel, type: ctype, age_days: dayDiff(now, ts), ttl_days: null, status: "untracked" });
+      continue;
+    }
+    const age = dayDiff(now, ts);
+    const status = age > ttl ? "STALE" : "fresh";
+    if (status === "STALE") stale++;
+    rows.push({ concept: rel, type: ctype, age_days: age, ttl_days: ttl, status, remaining_days: ttl - age });
+  }
+
+  return {
+    now: nowISO, stale, missing_required_ts: missing, on_stale: onStale, concepts: rows,
+    fail: (stale + missing) > 0 && onStale === "abort",
+  };
+}
+
+// ---- attest -----------------------------------------------------------------
+// Signs and upserts one freshness attestation into <bundle>/attestations.json.
+export function attestVigencia({ bundleDir, concept, by, on, until, keyPath, note = "" }) {
+  const root = resolve(bundleDir);
+  const target = resolve(root, concept);
+  if (target !== root && !target.startsWith(root + sep)) {
+    throw new Error(`'${concept}' must live inside the bundle`);
+  }
+  if (!existsSync(target)) throw new Error(`no such concept: ${concept}`);
+  if (!parseDateISO(on) || !parseDateISO(until)) throw new Error("--on and --until must be ISO (YYYY-MM-DD)");
+
+  const regPath = join(root, "reviewers.json");
+  if (!existsSync(regPath)) {
+    throw new Error("no reviewers.json in the bundle. Register the reviewer's raw ed25519 pubkey (hex) there first.");
+  }
+  const registry = JSON.parse(readFileSync(regPath, "utf8"));
+  if (!(by in registry)) throw new Error(`'${by}' is not registered in reviewers.json`);
+  if (!existsSync(keyPath)) throw new Error(`no such private key file: ${keyPath}`);
+
+  const privHex = readFileSync(keyPath, "utf8").trim();
+  const contentSha = sha256RawFile(target);
+  const signature = signVigenciaHex(privHex, vigenciaMsg(concept, contentSha, on, until));
+
+  // Sanity: the key must actually belong to the registered reviewer.
+  if (!verifyVigenciaHex(registry[by], vigenciaMsg(concept, contentSha, on, until), signature)) {
+    throw new Error(`the private key does not match the registered pubkey for '${by}'`);
+  }
+
+  const storePath = join(root, "attestations.json");
+  let data = { vigencia_version: "0.2", attestations: [] };
+  if (existsSync(storePath)) {
+    data = JSON.parse(readFileSync(storePath, "utf8"));
+    if (!data || typeof data !== "object" || !Array.isArray(data.attestations)) {
+      throw new Error("attestations.json does not have the expected structure");
+    }
+  }
+  const entry = {
+    concept, content_sha256: contentSha, statement: "vigente",
+    attested_by: by, attested_at: on, valid_until: until, signature, note,
+  };
+  data.vigencia_version = "0.2";
+  data.attestations = data.attestations
+    .filter((a) => !(a && typeof a === "object" && a.concept === concept))
+    .concat([entry]);
+  writeFileSync(storePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+  return entry;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rckflr/llms-skills",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "One-command publisher CLI for the llms.txt Skills standard: scaffold, hash, sign, and sync the ## Skills section + .well-known/agent-skills/index.json. Byte-identical to the reference Python generator; zero hard dependencies (BM25 knowledge snapshots via an optional wasm engine).",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,7 @@
     "CHANGELOG.md",
     "bin/llms-skills.mjs",
     "lib/core.mjs",
+    "lib/freshness.mjs",
     "lib/memory.mjs",
     "README.md"
   ],