@rckflr/llms-skills 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ 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.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
+  core RFC v0.10 Open Question 6). Declares the project namespace for
+  multi-project origins: the manifest's `memory` block and every generated
+  `published` entry carry `scope`, and `publish` renders it as the **last**
+  key of both the skill lines and the `skills-memory` line
+  (`"scope":"kdd"`). Runtimes (mcpwasm ≥ 0.6.0) expose the tools as
+  `<scope>__<toolName>` and bind each scope's memory to its own snapshot.
+  Pattern `^[a-z][a-z0-9_-]*$`; invalid values fail fast. Re-running
+  `memory` with a different `--scope` (or none) refreshes the manifest
+  entries idempotently.
+- `validate` understands scopes: accepts multiple `skills-memory` lines when
+  each carries a distinct `scope` (at most one unscoped), and reports invalid
+  `scope` values and duplicated scopes as errors.
+- New test part: scoped fixture end-to-end (manifest wiring, key order,
+  validate, and **byte-identity with `scripts/generate.py`** on scoped
+  output — the mirror contract now covers scopes).
+
+### Changed
+- `scripts/generate.py` mirrored: manifest entries and the `memory` block
+  accept `scope` and render it identically (byte-identity enforced by
+  `cli/test.mjs` Part 6). No `scope` anywhere ⇒ output identical to 0.2.1.
+
+## [0.2.1] — 2026-07-10
+
+### Fixed
+- **Frontmatter values quoted with single quotes** (`type: 'Concept'`) are now
+  unquoted correctly: one *matching* pair of quotes (double or single) is
+  stripped. Found with a real OKF bundle (KDD) whose frontmatter uses single
+  quotes; before this fix the quotes leaked into concept `type`/`title`.
+  Mirrored in `scripts/generate.py` (`parse_yaml_frontmatter`) — byte-identity
+  between both generators re-verified.
+
 ## [0.2.0] — 2026-07-10
 
 ### Added

package/README.md

@@ -67,6 +67,21 @@ What it generates: a **byte-deterministic** BM25 snapshot (canonicalized, so
 content-addressed). It also pins the snapshot as `-text` in `.gitattributes`
 so git's CRLF conversion can never break the published hash.
 
+**Multi-project origins (scopes).** Publishing several projects on one origin
+(e.g. a GitHub Pages root)? Add `--scope <name>` (pattern
+`^[a-z][a-z0-9_-]*$`, Executable Skills v0.5 §2.5):
+
+```bash
+npx @rckflr/llms-skills memory ./knowledge --scope kdd
+```
+
+The manifest and the rendered lines carry `"scope":"kdd"`; runtimes
+(mcpwasm ≥ 0.6.0) expose the tools as `kdd__search_knowledge` etc. and bind
+each scope's memory to its own snapshot — no name collisions, one
+`skills-memory` line per scope. Published bytes and hashes are untouched
+(the rename is runtime-side), so `search_knowledge` stays the universal
+template.
+
 Consumers need nothing new: `npx -y @rckflr/mcpwasm <origin>` (>= 0.4.0)
 verifies the snapshot and injects `host.memorySearch` on both runtimes.
 `memory <bundle> --check` is the CI guard. The BM25 engine
@@ -74,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];
@@ -29,10 +30,17 @@ const USAGE = `llms-skills — publisher CLI for the llms.txt Skills standard
 
 Usage:
   llms-skills init <name> [--tool] [--root <dir>]   scaffold SKILL.md (+ tool.js) + manifest entry
-  llms-skills memory <bundle-dir> [--check] [--root <dir>] [--license <spdx>]
+  llms-skills memory <bundle-dir> [--check] [--root <dir>] [--license <spdx>] [--scope <name>]
                                                     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.
@@ -125,7 +133,7 @@ async function cmdMemory() {
     : { section_intro: "Remote Agent Skills published by this domain.", published: [] };
 
   const { targets, warnings, manifest: newManifest, snapshotSha, conceptCount } =
-    await buildMemoryTargets({ root, bundleDir, manifest, license: flag("--license") });
+    await buildMemoryTargets({ root, bundleDir, manifest, license: flag("--license"), scope: flag("--scope") });
   for (const w of warnings) console.error(`[warn] ${w}`);
 
   const rel = (p) => (relative(root, p) || p).replaceAll("\\", "/");
@@ -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/core.mjs

@@ -46,6 +46,9 @@ export function parseFrontmatter(text) {
 
 const REQUIRED_FRONTMATTER = ["name", "description", "version", "license"];
 
+// Executable Skills v0.5 SS2.5: namespace declarativo para origins multi-proyecto.
+const SCOPE_RE = /^[a-z][a-z0-9_-]*$/;
+
 // ---- load skills from a manifest (mirrors generate.py load_skills) ----
 export function loadSkills(manifest, repoRoot) {
   const skills = [];
@@ -64,10 +67,14 @@ export function loadSkills(manifest, repoRoot) {
       toolUrl = entry.tool_url;
       toolSha256 = sha256NormalizedFile(toolPath);
     }
+    if (entry.scope !== undefined && !SCOPE_RE.test(String(entry.scope))) {
+      throw new Error(`${entry.path}: invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)`);
+    }
     skills.push({
       name: fm.name, description: fm.description, version: fm.version, license: fm.license,
       homepage: fm.homepage || null, url: entry.url, summary: entry.summary,
       sha256: sha256NormalizedFile(path), path, toolUrl, toolSha256,
+      scope: entry.scope !== undefined ? String(entry.scope) : null,
     });
   }
   return skills;
@@ -81,7 +88,14 @@ export function loadMemory(manifest, repoRoot) {
   }
   const snapshotPath = join(repoRoot, memory.snapshot_path);
   if (!existsSync(snapshotPath)) throw new Error(`snapshot not found: ${memory.snapshot_path}`);
-  return { snapshot_url: memory.snapshot_url, format: memory.format, snapshot_sha256: sha256NormalizedFile(snapshotPath) };
+  if (memory.scope !== undefined && !SCOPE_RE.test(String(memory.scope))) {
+    throw new Error("manifest.memory: invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)");
+  }
+  return {
+    snapshot_url: memory.snapshot_url, format: memory.format,
+    snapshot_sha256: sha256NormalizedFile(snapshotPath),
+    scope: memory.scope !== undefined ? String(memory.scope) : null,
+  };
 }
 
 // ---- render: ## Skills section (compact JSON, exact key order of generate.py) ----
@@ -90,6 +104,7 @@ export function renderSkillsSection(manifest, skills) {
   for (const s of skills) {
     const meta = { version: s.version, license: s.license, sha256: s.sha256 };
     if (s.toolUrl && s.toolSha256) { meta.tool = s.toolUrl; meta.tool_sha256 = s.toolSha256; }
+    if (s.scope) meta.scope = s.scope;
     lines.push(`- [${s.name}](${s.url}): ${s.summary} <!-- skill: ${JSON.stringify(meta)} -->`);
   }
   return lines.join("\n") + "\n";
@@ -98,6 +113,7 @@ export function renderSkillsSection(manifest, skills) {
 export function renderSkillsMemoryLine(memory) {
   if (!memory) return "";
   const meta = { snapshot: memory.snapshot_url, snapshot_sha256: memory.snapshot_sha256, format: memory.format };
+  if (memory.scope) meta.scope = memory.scope;
   return `<!-- skills-memory: ${JSON.stringify(meta)} -->\n\n`;
 }
 
@@ -191,9 +207,20 @@ export function validateLlmsTxt(source, text) {
   const err = (message, line = "") => errors.push({ message, line });
   const warn = (message, line = "") => warnings.push({ message, line });
 
-  // origin memory line (optional)
-  const memMatch = text.split(/\r?\n/).map((l) => l.trim().match(MEMORY_CAPTURE_RE)).find(Boolean);
-  if (memMatch) validateMemory(memMatch[1], source, err, warn);
+  // origin memory lines (optional; Executable Skills v0.5 SS2.5: one per
+  // scope, at most one without scope)
+  const memScopes = [];
+  for (const l of text.split(/\r?\n/)) {
+    const memMatch = l.trim().match(MEMORY_CAPTURE_RE);
+    if (!memMatch) continue;
+    const scopeKey = validateMemory(memMatch[1], source, err, warn);
+    if (scopeKey === undefined) continue; // JSON invalido, ya reportado
+    if (memScopes.includes(scopeKey)) {
+      err(scopeKey === ""
+        ? "skills-memory: more than one line without 'scope' (at most one allowed)"
+        : `skills-memory: duplicate line for scope '${scopeKey}'`);
+    } else memScopes.push(scopeKey);
+  }
 
   // find ## Skills section
   const lines = text.split(/\r?\n/);
@@ -238,6 +265,8 @@ export function validateLlmsTxt(source, text) {
         if (hasToolSha && !hasTool) err("'tool_sha256' declared without 'tool' (both required together)", raw.slice(0, 80));
         if (hasToolSha && !/^[a-fA-F0-9]{64}$/.test(String(metaParsed.tool_sha256)))
           err("Invalid tool_sha256 (must be 64 hex chars)", raw.slice(0, 80));
+        if ("scope" in metaParsed && !SCOPE_RE.test(String(metaParsed.scope)))
+          err("Invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)", raw.slice(0, 80));
       } catch (e) { err(`Invalid metadata JSON: ${e.message}`, raw.slice(0, 80)); }
     }
     const resolved = resolveSkillPath(url, source);
@@ -272,12 +301,15 @@ const MEMORY_CAPTURE_RE = /^<!--\s*skills-memory:\s*(.*?)\s*-->\s*$/;
 function validateMemory(memJson, source, err, warn) {
   let meta;
   try { meta = JSON.parse(memJson); }
-  catch (e) { err(`skills-memory: invalid JSON: ${e.message}`); return; }
+  catch (e) { err(`skills-memory: invalid JSON: ${e.message}`); return undefined; }
+  const scopeKey = meta.scope === undefined ? "" : String(meta.scope);
+  if (meta.scope !== undefined && !SCOPE_RE.test(String(meta.scope)))
+    err(`skills-memory: invalid 'scope' (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)`);
   let ok = true;
   for (const key of ["snapshot", "snapshot_sha256", "format"]) {
     if (typeof meta[key] !== "string") { err(`skills-memory: missing or invalid '${key}' (must be string)`); ok = false; }
   }
-  if (!ok) return;
+  if (!ok) return scopeKey;
   if (!/^[a-fA-F0-9]{64}$/.test(meta.snapshot_sha256)) err("skills-memory: invalid snapshot_sha256 (must be 64 hex chars)");
   if (meta.format !== "minimemory-okf-v1") warn(`skills-memory: format '${meta.format}' is not the only one recognized today (minimemory-okf-v1)`);
   const resolved = resolveSkillPath(meta.snapshot, source);
@@ -288,4 +320,5 @@ function validateMemory(memJson, source, err, warn) {
       if (actual !== meta.snapshot_sha256) err(`skills-memory: snapshot_sha256 mismatch: declared ${meta.snapshot_sha256}, actual ${actual}`);
     }
   }
+  return scopeKey;
 }

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/lib/memory.mjs

@@ -192,7 +192,11 @@ runtime executes it verbatim in a sandbox.
 // ---- orchestrator --------------------------------------------------------------
 // Builds everything under `root`. Returns { targets, warnings, snapshotSha, manifest }
 // where targets is [path, content] pairs (the caller writes or checks them).
-export async function buildMemoryTargets({ root, bundleDir, manifest, license }) {
+export async function buildMemoryTargets({ root, bundleDir, manifest, license, scope }) {
+  // Executable Skills v0.5 SS2.5: namespace declarativo para origins multi-proyecto.
+  if (scope !== undefined && scope !== null && !/^[a-z][a-z0-9_-]*$/.test(String(scope))) {
+    throw new Error("memory: invalid --scope (pattern ^[a-z][a-z0-9_-]*$, Executable Skills v0.5 §2.5)");
+  }
   const bundleRel = relative(root, bundleDir).replaceAll("\\", "/");
   if (bundleRel.startsWith("..")) {
     throw new Error("memory: the bundle must live inside the publisher root (it is served as static content)");
@@ -236,17 +240,26 @@ export async function buildMemoryTargets({ root, bundleDir, manifest, license })
     snapshot_url: "/skills-index.snapshot",
     format: SNAPSHOT_FORMAT,
   };
+  if (scope) newManifest.memory.scope = String(scope);
+  else delete newManifest.memory.scope;
   if (!Array.isArray(newManifest.published)) newManifest.published = [];
   for (const [name, , summary] of SKILLS) {
     const path = `skills/${name}/SKILL.md`;
-    if (!newManifest.published.some((e) => e && e.path === path)) {
-      newManifest.published.push({
+    const existing = newManifest.published.find((e) => e && e.path === path);
+    if (!existing) {
+      const entry = {
         path,
         url: `/skills/${name}/SKILL.md`,
         summary,
         tool: `skills/${name}/tool.js`,
         tool_url: `/skills/${name}/tool.js`,
-      });
+      };
+      if (scope) entry.scope = String(scope);
+      newManifest.published.push(entry);
+    } else if (scope) {
+      existing.scope = String(scope); // re-run con --scope: refresca el namespace
+    } else {
+      delete existing.scope; // re-run sin --scope: vuelve al default global
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rckflr/llms-skills",
-  "version": "0.2.1",
+  "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"
   ],