@gregiteen/ssss-cli 0.7.0 → 0.8.0

package/skills/ssss/SKILL.md

@@ -0,0 +1,225 @@
+---
+type: skill
+title: SSSS System Manager
+name: ssss
+description: "Inspect, validate, implement, or change SSSS primitives, extension registries, operation envelopes, workflow runtimes, semantic search, translation/localization overlays, bundles, projections, and host adapters. Use for SSSS schema changes, registry collisions, conformance failures, portability/privacy questions, or translatable semantic vault work. MANDATORY: Read this file before editing SSSS files or code."
+timestamp: 2026-07-10T00:00:00Z
+---
+
+# SSSS — Structured Semantic Syntax System Manager
+
+SSSS is a vendor-neutral, Markdown-first state and mutation contract. Canonical
+state is typed Markdown plus append-only events. Databases, indexes, queues,
+dashboards, and search stores are host projections unless explicitly documented
+as external resources.
+
+## Establish Ground Truth First
+
+Do not infer the contract from an installed skill snapshot.
+
+1. Find the repository root and inspect `package.json`, `VERSION`,
+   `registry/core.json`, and `docs/ssss-spec.md` when they exist.
+2. Treat `registry/core.json` as the machine-readable primitive contract and
+   `docs/ssss-spec.md` as the normative explanation.
+3. Treat `src/engine.mjs`, `src/runtime.mjs`, `src/semantic.mjs`,
+   `src/bundle.mjs`, `src/registry.mjs`, and `src/frontmatter.mjs` as the
+   reference behavior.
+4. Treat host schemas and services as adapters or extension registries. Never
+   promote host-only fields into the core standard without an explicit spec and
+   registry change.
+5. Read the current package name and version instead of hard-coding an alias.
+   In this checkout the published package is `@gregiteen/ssss-cli`; the CLI is
+   `ssss`.
+
+If those files are absent, inspect the installed
+`@gregiteen/ssss-cli/registry/core.json` export. Use the bundled reference only
+as a fallback and report that the result is snapshot-based.
+
+## Authority Order
+
+When sources disagree, resolve drift in this order:
+
+1. Conformance fixtures and tests for observed executable behavior.
+2. `registry/core.json` for required fields, enums, append behavior, and
+   portability.
+3. `docs/ssss-spec.md` for normative semantics.
+4. Reference engine/runtime/bundle code.
+5. Host extension registry and host adapter documentation.
+6. Skills, examples, README prose, and copied mirrors.
+
+Do not silently pick one side. Identify the mismatch, decide whether code or
+canon is wrong, update every affected source, and add a regression check.
+
+## Document Contract
+
+Every SSSS document has YAML frontmatter and a Markdown body. SSSS-managed
+documents require the universal fields:
+
+- `type`
+- `title`
+- `description`
+- `timestamp`
+
+Primitive-specific required fields are additive. An SSSS-managed skill also
+requires `name`; a schema-v2 memory has knowledge-graph fields; a workflow
+requires `name`.
+
+Unknown frontmatter fields must be preserved for forward compatibility. Never
+drop a nested map, array, or unknown field during parse/serialize or patch.
+
+Registry declarations are executable contract. Enforce `required_fields`,
+`required_when`, `enums`, `patterns`, `immutable_fields`, `references`,
+`append_only`, and `portability`. Reject malformed extension definitions,
+symlinked registry files, and core or sibling type collisions during load.
+
+## Mutation Contract
+
+Agent-generated mutations flow through the Operation Contract:
+
+```text
+validate envelope
+  -> verify safe workspace/idempotency/actor identifiers
+  -> resolve and contain the target path
+  -> replay or reject the idempotency key + request hash
+  -> authorize with verified actor identity (fail closed)
+  -> validate any active lease (fail closed)
+  -> validate universal + primitive-specific content
+  -> commit atomically
+  -> append the audit event
+```
+
+The mutation envelopes are:
+
+- `operation` — create or fully replace a replace-type document.
+- `patch` — merge an existing replace-type document without changing `type`.
+- `event` — append an immutable event record.
+- `delete` — remove a replace-type document and emit an audit event; reject
+  append-type targets.
+
+Use `dry_run: true` for model-generated preflight. Idempotency is scoped by the
+effective request, not the key alone: the same request replays, while the same
+workspace/key with a different request hash is a conflict.
+
+## Append, Lease, and Path Safety
+
+- `conversation` and `run` are append-only. Preserve prior bytes and append new
+  records; never rewrite or delete them.
+- Events are immutable.
+- Paths must be relative, contained vault paths. Reject absolute paths,
+  backslashes, null bytes, empty segments, `.`/`..`, directory targets, and
+  symlink escapes.
+- Leases are actor-owned, operation-linked, expiring locks. Missing, mismatched,
+  malformed, or unreadable lease state fails closed.
+- Hosts must overwrite caller-supplied actor data with verified session identity
+  before authorization.
+
+## Workflow Runtime
+
+Workflow frontmatter owns the schedule. Cron, daemon, webhook, file watcher, and
+event-loop processes are wake-up mechanisms, not a second scheduling database.
+
+Use `@gregiteen/ssss-cli/runtime` to deterministically derive the trigger event,
+task, and run envelopes. Duplicate ticks must replay idempotently. Queues and
+task dashboards are disposable projections over workflow state and events.
+
+## Bundles and Portability
+
+Every document primitive resolves to one portability class:
+
+- `structural` — reusable model shipped in templates and sale bundles.
+- `tenant_private` — operator/customer runtime data; excluded from template and
+  sale exports.
+- `resource_bound` — exported only as a requirement declaration; never leak the
+  seller's bound resource value.
+
+Bundle paths must be unique, safe, and symlink-free. Validate content hashes,
+required extensions, primitive inventory, core version, parameters, and link
+integrity before import. Preflight the complete plan before the first commit so a
+late invalid envelope cannot leave a partial install. Provisioning produces
+deterministic Operation Contract envelopes; re-import must be a no-op.
+
+## Semantic Search and Localization
+
+Treat semantic indexes and localized trees as disposable projections. Use
+`@gregiteen/ssss-cli/semantic`, `ssss semantic`, and `ssss localize` for the
+dependency-free reference behavior.
+
+- Index only `structural` documents by default. Include `tenant_private` and
+  `resource_bound` sources only after an explicit authorized opt-in.
+- Derive stable identity from `semantic_id`, then `resource`, then source path.
+- Build edges from explicit `relations`, wiki links, and Markdown links.
+- Keep projection output outside the source vault; reject symlinks and unsafe paths,
+  and stage the complete tree before publishing it.
+- Model localization as a `translation` document pointing to an existing
+  structural source and its exact SHA-256 content hash.
+- Translate only `title`, `description`, and body. Preserve types, ids, enums,
+  permissions, status, portability, relations, and paths from the source.
+- Apply approved overlays by default. Reject stale hashes, duplicate locale/source
+  overlays, recursive translations, private sources, and immutable identity edits.
+
+## Scope and Host Adapters
+
+The core standard does not collapse host ownership layers. A host may implement
+global/project or system/account/workspace overlays, but must document precedence
+and preserve isolation. Shared system skills should be inherited through an
+overlay rather than copied into every workspace.
+
+When working in Total Recall, use its validated-write and memory-validator
+adapter if those modules exist. In another host, locate its extension registry
+and conformance bridge. Do not quote Total Recall paths as universal SSSS
+architecture.
+
+## Procedure for Changes
+
+1. Classify the change: core primitive, contract behavior, runtime behavior,
+   semantic/localization behavior, bundle/provisioning behavior, projection, or
+   host extension.
+2. Inspect the registry, spec section, implementation, fixtures, and host bridge
+   for that surface.
+3. Make the smallest coherent change across code and canon.
+4. Add positive, negative, replay, and invalid-path cases where applicable.
+5. Run focused validation, then the full conformance gate.
+6. Update skill/reference mirrors only after the executable contract is green.
+
+## Validation
+
+Validate a Markdown document with the dependency-free skill helper:
+
+```bash
+node skills/ssss/scripts/validate-schema.mjs path/to/document.md
+```
+
+In the SSSS reference repository, the required gate is:
+
+```bash
+npm test
+```
+
+It covers registry/engine parity, shipped-skill conformance, Operation Contract
+fixtures, workflow runtime behavior, lease/frontmatter regressions,
+extension-registry hardening, semantic/localization behavior,
+bundle/provisioning round trips, and CLI smoke tests.
+
+For host adapters, run the host's named SSSS conformance command as well. Do not
+substitute a loose YAML parse or a generic typecheck for the SSSS gate.
+
+## Do Not
+
+- Do not treat an installed skill, copied spec, or README as newer than the live
+  registry and conformance suite.
+- Do not use raw file writes for agent-generated vault mutations.
+- Do not make a derived database/index/queue the canonical record.
+- Do not add a primitive in prose without registry and fixture coverage.
+- Do not translate symbolic control fields or index private content by default.
+- Do not materialize a projection inside its source vault.
+- Do not mix document primitives with contract envelopes.
+- Do not claim conformance from HTTP success or file creation alone.
+- Do not publish package names, versions, or exporter identities without reading
+  them from current package metadata.
+
+## References
+
+Read `references/contract-reference.md` for the compact topology, primitive
+families, package entry points, and drift checklist. For normative detail, read
+the exact linked section of `docs/ssss-spec.md` rather than loading a stale
+vendored copy.

package/skills/ssss/evals/evals.json

@@ -0,0 +1,37 @@
+[
+  {
+    "name": "ssss-skill-validates-as-primitive",
+    "assertion": "SKILL.md includes universal SSSS frontmatter plus type: skill, name: ssss, and a trigger-optimized description.",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-canon-is-evidence-first",
+    "assertion": "The skill tells agents to inspect package metadata, registry, spec, implementation, and conformance instead of trusting a copied snapshot.",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-validator-is-dependency-free",
+    "assertion": "scripts/validate-schema.mjs runs with Node built-ins and validates universal plus primitive-specific fields.",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-host-boundaries-are-explicit",
+    "assertion": "The skill distinguishes the vendor-neutral reference kernel from Total Recall and other host adapters.",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-full-gate-is-named",
+    "assertion": "The skill requires npm test in the reference repository and the host-specific SSSS conformance gate for adapters.",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-semantic-default-is-private",
+    "assertion": "The skill requires structural-only semantic and localization projections by default, with explicit authorization before private or resource-bound indexing.",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-translations-preserve-controls",
+    "assertion": "The skill limits translations to title, description, and body; requires an exact structural source hash; and preserves symbolic control fields.",
+    "severity": "error"
+  }
+]

package/skills/ssss/references/contract-reference.md

@@ -0,0 +1,96 @@
+# SSSS Contract Reference
+
+This is an operational map. The normative source is the current
+`docs/ssss-spec.md`; the machine-readable source is `registry/core.json`.
+
+## Reference-kernel topology
+
+| Surface | Responsibility |
+| --- | --- |
+| `registry/core.json` | Core document/contract primitives, universal fields, enums, portability, bundle/runtime vocabularies. |
+| `registry/extensions/*.json` | Host/application types that cannot redefine core primitives. |
+| `src/engine.mjs` | Operation Contract, validation, authorization, leases, idempotency, atomic commit, audit. |
+| `src/runtime.mjs` | Workflow trigger planning and deterministic event/task/run envelopes. |
+| `src/semantic.mjs` | Deterministic semantic records/edges, localized search, and safe materialization. |
+| `src/bundle.mjs` | Export, validate, provision, import, portability filtering, link/hash integrity. |
+| `src/registry.mjs` | Registry loading and type/portability resolution. |
+| `src/frontmatter.mjs` | Dependency-free parse/serialize with unknown-field preservation. |
+| `conformance/fixtures.json` | Canonical mutation examples and negative cases. |
+| `scripts/conformance.mjs` | Full executable contract gate. |
+
+## Package entry points
+
+Read the npm package name from `package.json`. The current reference checkout
+uses `@gregiteen/ssss-cli` and exposes `/engine`, `/runtime`, `/semantic`, `/bundle`,
+`/registry`, `/frontmatter`, `/registry/core.json`,
+`/conformance/fixtures.json`, and `/conformance/reference-bundle.ucw.json`.
+The executable command is `ssss`.
+
+## Document versus contract primitives
+
+Document primitives persist as Markdown and carry universal frontmatter.
+Contract primitives are mutation/concurrency envelopes and are not Markdown
+document types.
+
+Current core document families include knowledge (`memory`), capability
+(`skill`, `page`), governance (`rule`, `security_role`), work (`task`,
+`workflow`), actors/catalog (`assistant`, `model`), transcripts (`conversation`,
+`run`), localization (`translation`), and lifecycle/meta (`conflict`, `migration`,
+`release`).
+
+The contract primitives are `operation`, `patch`, `event`, `delete`, and
+`lease`.
+
+## Required validation dimensions
+
+For a document:
+
+1. Frontmatter exists and parses.
+2. Universal fields are present and non-empty.
+3. `type` exists in the core or a loaded extension registry.
+4. Primitive-specific required/conditional fields are present.
+5. Enum values are valid.
+6. Pattern constraints match and document references resolve safely.
+7. Immutable fields do not change during replacement or patch.
+8. Append-only behavior is preserved.
+9. Unknown fields survive parse/serialize and patch.
+10. Path and canonical filename rules hold where applicable.
+
+For an envelope:
+
+1. Envelope type and identifiers are valid.
+2. Target path is relative and contained.
+3. Idempotency replay is bound to the request hash.
+4. Actor identity is verified and authorization fails closed.
+5. Lease state is valid or the write is rejected.
+6. Content validates against universal plus primitive-specific rules.
+7. Commit is atomic and emits an audit event.
+
+For a bundle:
+
+1. Manifest shape and core version are supported.
+2. Required extensions are loaded.
+3. Paths are safe, unique, and sorted.
+4. Content hash and primitive inventory match.
+5. Portability prevents tenant-private and resource-value leakage.
+6. Parameters/provisioning use registry vocabularies.
+7. Internal links resolve after remapping.
+8. Re-import replays without new commits.
+
+For a semantic/localization projection:
+
+1. Records and index hashes are deterministic for identical inputs.
+2. Stable identity, tokens, content hashes, portability, and graph edges are retained.
+3. Private and resource-bound documents are excluded unless explicitly authorized.
+4. A translation targets one structural, non-translation source by safe relative path.
+5. The source hash is exact and only natural-language surface fields change.
+6. Duplicate, stale, traversing, symlinked, or recursive overlays fail closed.
+7. Materialization occurs outside the source vault and remains rebuildable.
+
+## Drift checklist
+
+Compare package/version metadata, spec and registry versions, registry fields
+against engine consumption, `spec_ref` headings, docs/skills against package
+exports, reference-bundle provenance, host extensions against core ownership,
+and generated/symlinked skill copies against tracked sources. Add a deterministic
+check for every drift class that has occurred once.

package/skills/ssss/scripts/validate-schema.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const FALLBACK_UNIVERSAL = ['type', 'title', 'description', 'timestamp'];
+const FALLBACK_REQUIRED = {
+  memory: ['slug', 'category', 'status', 'schema_version'],
+  skill: ['name'],
+  rule: ['name'],
+  security_role: ['name', 'permissions'],
+  task: ['priority', 'category', 'status'],
+  assistant: ['name'],
+  workflow: ['name'],
+  model: ['model_id', 'provider'],
+  conversation: ['thread_id'],
+  run: ['run_id', 'workflow_id'],
+  conflict: ['conflict_id', 'status', 'new_slug', 'existing_slug', 'detected_at'],
+  page: ['slug', 'name', 'sandbox_entry'],
+  migration: ['migration_id', 'from_version', 'to_version', 'status'],
+  release: ['release_id', 'version', 'schema_version', 'summary', 'released_at'],
+  translation: ['translation_id', 'source_path', 'source_hash', 'locale', 'status', 'translated_fields'],
+};
+const CONTRACT_TYPES = new Set(['operation', 'patch', 'event', 'delete', 'lease']);
+const APPEND_TYPES = new Set(['conversation', 'run']);
+
+function findUp(start, predicate) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (predicate(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function findKernelRoot(start) {
+  return findUp(start, (dir) =>
+    fs.existsSync(path.join(dir, 'registry', 'core.json')) &&
+    fs.existsSync(path.join(dir, 'src', 'frontmatter.mjs'))
+  );
+}
+
+function parseScalar(value) {
+  const text = value.trim();
+  if (!text) return '';
+  if ((text.startsWith('"') && text.endsWith('"')) ||
+      (text.startsWith("'") && text.endsWith("'"))) return text.slice(1, -1);
+  if (text === 'true') return true;
+  if (text === 'false') return false;
+  if (text === 'null' || text === '~') return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(text)) return Number(text);
+  if (text.startsWith('[') && text.endsWith(']')) {
+    return text.slice(1, -1).split(',').map((item) => parseScalar(item)).filter((item) => item !== '');
+  }
+  return text;
+}
+
+function parseFallback(raw) {
+  const lines = raw.replace(/\r\n/g, '\n').split('\n');
+  if (lines[0]?.trim() !== '---') throw new Error('Missing YAML frontmatter block.');
+  const close = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+  if (close < 0) throw new Error('Unclosed YAML frontmatter block.');
+  const data = {};
+  let collectionKey = null;
+  for (const line of lines.slice(1, close)) {
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const listMatch = line.match(/^\s+-\s+(.+)$/);
+    if (listMatch && collectionKey) {
+      if (!Array.isArray(data[collectionKey])) data[collectionKey] = [];
+      data[collectionKey].push(parseScalar(listMatch[1]));
+      continue;
+    }
+    if (/^\s/.test(line)) continue;
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!match) continue;
+    collectionKey = match[1];
+    data[collectionKey] = parseScalar(match[2]);
+  }
+  return { data, body: lines.slice(close + 1).join('\n') };
+}
+
+async function parseDocument(raw, kernelRoot) {
+  if (!kernelRoot) return parseFallback(raw);
+  try {
+    const module = await import(pathToFileURL(path.join(kernelRoot, 'src', 'frontmatter.mjs')).href);
+    return module.parseDocument(raw);
+  } catch {
+    return parseFallback(raw);
+  }
+}
+
+function loadRegistry(kernelRoot) {
+  if (!kernelRoot) return null;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(kernelRoot, 'registry', 'core.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isEmpty(value) {
+  return value === undefined || value === null || value === '' ||
+    (Array.isArray(value) && value.length === 0);
+}
+
+function requiredWhenFields(definition, data) {
+  const fields = [];
+  for (const [condition, required] of Object.entries(definition?.required_when || {})) {
+    const match = condition.match(/^([A-Za-z_][A-Za-z0-9_-]*)==(.+)$/);
+    if (match && String(data[match[1]]) === match[2]) fields.push(...required);
+  }
+  return fields;
+}
+
+function isSafeReferencePath(value) {
+  return typeof value === 'string' && value.length > 0 && value.endsWith('.md') &&
+    !path.isAbsolute(value) && !value.includes('\\') && !value.includes('\0') &&
+    value.split('/').every((segment) => segment && segment !== '.' && segment !== '..');
+}
+
+function inferVaultRoot(target) {
+  let cursor = path.dirname(target);
+  while (path.dirname(cursor) !== cursor) {
+    if (path.basename(cursor) === 'translations') return path.dirname(cursor);
+    cursor = path.dirname(cursor);
+  }
+  return null;
+}
+
+async function validateTranslationReference(target, data, registry, kernelRoot, errors, warnings) {
+  if (data.type !== 'translation' || isEmpty(data.source_path)) return;
+  if (!isSafeReferencePath(data.source_path)) {
+    errors.push(`Field 'source_path' must be a safe vault-relative Markdown path.`);
+    return;
+  }
+  const vaultRoot = inferVaultRoot(target);
+  if (!vaultRoot) {
+    warnings.push("Cannot resolve translation source outside the canonical translations/<locale>/ layout.");
+    return;
+  }
+  const source = path.resolve(vaultRoot, data.source_path);
+  const relative = path.relative(vaultRoot, source);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    errors.push("Translation source_path escapes the vault.");
+    return;
+  }
+  if (!fs.existsSync(source) || !fs.statSync(source).isFile() || fs.lstatSync(source).isSymbolicLink()) {
+    errors.push(`Translation source does not exist as a regular non-symlinked file: ${data.source_path}.`);
+    return;
+  }
+  const raw = fs.readFileSync(source, 'utf8');
+  const parsed = await parseDocument(raw, kernelRoot);
+  if (parsed.data.type === 'translation') errors.push('Translations may not target another translation.');
+  const sourceDefinition = registry?.document_primitives?.[parsed.data.type];
+  const portability = parsed.data.x_portability || sourceDefinition?.portability;
+  if (portability !== 'structural') errors.push('Translations may target structural documents only.');
+  const hash = `sha256:${crypto.createHash('sha256').update(raw).digest('hex')}`;
+  if (data.source_hash !== hash) errors.push(`Translation source_hash is stale; expected '${hash}'.`);
+}
+
+export async function validateNode(filePath) {
+  const target = path.resolve(filePath);
+  const kernelRoot = findKernelRoot(path.dirname(target)) || findKernelRoot(process.cwd());
+  const registry = loadRegistry(kernelRoot);
+  const raw = fs.readFileSync(target, 'utf8');
+  const { data, body } = await parseDocument(raw, kernelRoot);
+  const errors = [];
+  const warnings = [];
+
+  if (isEmpty(data.type)) {
+    errors.push("Missing required field 'type'.");
+    return { valid: false, errors, warnings, file: target, type: null, kernelRoot };
+  }
+  if (CONTRACT_TYPES.has(data.type)) {
+    errors.push(`Type '${data.type}' is a contract envelope, not a Markdown document primitive.`);
+  }
+
+  const definition = registry?.document_primitives?.[data.type] || null;
+  if (registry && !definition) errors.push(`Unknown document primitive '${data.type}'.`);
+  if (!registry && !FALLBACK_REQUIRED[data.type]) {
+    warnings.push(`No live core registry found and no fallback schema exists for '${data.type}'.`);
+  }
+
+  const required = new Set([
+    ...(registry?.universal_frontmatter?.required || FALLBACK_UNIVERSAL),
+    ...(definition?.required_fields || FALLBACK_REQUIRED[data.type] || []),
+    ...requiredWhenFields(definition, data),
+  ]);
+  for (const field of required) {
+    if (isEmpty(data[field])) errors.push(`Missing required field '${field}'.`);
+  }
+
+  for (const [field, allowed] of Object.entries(definition?.enums || {})) {
+    const values = Array.isArray(data[field]) ? data[field] : [data[field]];
+    if (!isEmpty(data[field]) && values.some((value) => !allowed.includes(value))) {
+      errors.push(`Field '${field}' must contain only: ${allowed.join(', ')}.`);
+    }
+  }
+
+  for (const [field, source] of Object.entries(definition?.patterns || {})) {
+    if (isEmpty(data[field])) continue;
+    try {
+      if (!(new RegExp(source, 'u')).test(String(data[field]))) {
+        errors.push(`Field '${field}' does not match required pattern ${source}.`);
+      }
+    } catch {
+      errors.push(`Registry pattern for '${field}' is invalid.`);
+    }
+  }
+
+  await validateTranslationReference(target, data, registry, kernelRoot, errors, warnings);
+
+  if (APPEND_TYPES.has(data.type) && body.trim() === '') {
+    warnings.push(`Append-only primitive '${data.type}' has an empty body.`);
+  }
+  if (data.type === 'memory' && target.split(path.sep).includes('memory-vault')) {
+    const parent = path.basename(path.dirname(target));
+    if (data.category && data.category !== parent) {
+      errors.push(`Memory category '${data.category}' does not match parent directory '${parent}'.`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    file: target,
+    type: data.type,
+    kernelRoot,
+  };
+}
+
+function realpath(value) {
+  try { return fs.realpathSync(value); } catch { return value; }
+}
+
+const invoked = process.argv[1] ? realpath(path.resolve(process.argv[1])) : null;
+if (invoked === realpath(fileURLToPath(import.meta.url))) {
+  const target = process.argv[2];
+  if (!target) {
+    console.error('Usage: node validate-schema.mjs <path-to-ssss-document.md>');
+    process.exit(2);
+  }
+  try {
+    const result = await validateNode(target);
+    for (const warning of result.warnings) console.warn(`WARN: ${warning}`);
+    if (!result.valid) {
+      for (const error of result.errors) console.error(`ERROR: ${error}`);
+      process.exit(1);
+    }
+    console.log(`OK: ${path.basename(result.file)} is a valid '${result.type}' document.`);
+  } catch (error) {
+    console.error(`ERROR: ${error.message}`);
+    process.exit(1);
+  }
+}

package/skills/ssss/subagents/audit-ssss-contract.md

@@ -0,0 +1,22 @@
+# Role: SSSS Contract Auditor
+
+Audit one bounded SSSS surface without editing it.
+
+## Inputs
+
+- Repository root
+- Surface: primitive, envelope, runtime, bundle, projection, or host adapter
+- Files or symbols in scope
+
+## Procedure
+
+1. Read the relevant registry entry and exact spec section.
+2. Trace the implementation and every related conformance fixture.
+3. Compare required fields, enums, append behavior, authorization, path safety,
+   idempotency, portability, and package identity where relevant.
+4. Report only evidence-backed mismatches with file paths and a proposed test.
+
+## Output
+
+Return a compact table with `severity`, `contract`, `implementation`, `evidence`,
+and `recommended regression`. Do not modify files.