total-recall-brain 3.13.0 → 3.13.2

package/scaffold/.agent/skills/total-recall/skills/tr-ssss/SKILL.md

@@ -1,298 +0,0 @@
----
-name: tr-ssss
-provenance: total-recall
-description: "Use this skill to inspect, validate, write, and manage SSSS primitives, memory nodes, operation envelopes, scope overlays, projections, and VFS specifications in the Total Recall reference kernel. MANDATORY: Read this file before editing SSSS files or code."
----
-
-# SSSS — Structured Semantic Syntax System Manager
-
-SSSS is the Markdown-first state contract for Total Recall and compatible VFS
-hosts. Use this skill when touching memory nodes, skills, assistants, workflows,
-models, conversations, runs, projection metadata, operation envelopes, or SSSS
-schema/reference files.
-
-## Ground Truth
-
-The vendor-neutral contract is now a published package, **`@ssss/cli`** (pinned to
-**`v0.7.0`**, spec v0.6 draft; source <https://github.com/gregiteen/ssss>), declared in
-`package.json`. `references/ssss-spec.md` is the local mirror. The canon owns the
-spec (§4.2 universal OKF-compatible frontmatter, §5.5 portability, §6 Operation
-Contract incl. `event` and `delete`, §11.8 workflow runtime daemon contract, §16
-the `.ucw` bundle format, §17 provisioning), the core
-registry (`@ssss/cli/registry/core.json`: 14 document + 5 contract primitives),
-the reference engine, runtime helpers, and the v1.4.0 conformance fixtures. Total
-Recall's kernel was the engine the canon's reference implementation was harvested
-from; keep them aligned. If this skill conflicts with the canon, correct this
-skill unless the implementation has intentionally advanced beyond it and the
-difference is documented here.
-
-Current local implementation entry points:
-
-- `src/core/schema.mjs` — implemented SSSS primitive registry (`SSSS_SCHEMAS`).
-- `src/core/operation-validator.mjs` — §6 operation pipeline.
-- `src/core/validated-write.mjs` — memory write adapter for the operation
-  pipeline.
-- `src/core/total-recall-memory-validator.mjs` — schema v2 memory validator.
-- `src/core/vault-cache.mjs` — cached vault reads and watcher invalidation.
-- `src/core/vector-store.mjs` and `src/core/semantic-index.mjs` — canonical
-  search/index path.
-
-## Using the `@ssss/cli` CLI
-
-`@ssss/cli` ships a `ssss` command (available via `npx`, since it's a dependency).
-It operates on a **vault directory** of Markdown files and `.ucw` bundles, using
-the canon's own reference engine — separate from this kernel's `processOperation`.
-Use it for bundle/tenant tooling and conformance; for in-kernel memory writes keep
-using `writeNodeValidated()` / `processOperation()`. Use `@ssss/cli/runtime` when
-building daemon, cron, webhook, event, file-change, or agent-host wake-up loops.
-
-```bash
-npx ssss help                  # list doc topics; e.g. `ssss help portability|bundle|provisioning`
-npx ssss <command> --help      # flags for any command
-
-# Vault → bundle → vault lifecycle (§16/§17)
-npx ssss export <vault-dir> --profile sale --out pack.ucw.json   # backup | template | sale
-npx ssss validate pack.ucw.json                                  # schema + portability + content hash
-npx ssss inspect  pack.ucw.json --files                          # manifest, inventory, params, steps
-npx ssss provision pack.ucw.json --param domain=acme.live --out plan.json   # pure: params + links → envelopes
-npx ssss import   pack.ucw.json --vault ./new-vault --param domain=acme.live  # idempotent replay
-
-npx ssss conformance --engine  # replay the canonical fixtures + round-trip the reference bundle
-```
-
-`export` is pure/deterministic and `template`/`sale` drop every `tenant_private`
-file (§5.5). Note: the canon's `.ucw` bundle (§16) is distinct from §7.4's OKF
-memory-vault `importBundle`/`exportBundle` in `repo-expert`.
-
-## Current Contract
-
-All agent-generated mutations must flow through the SSSS operation pipeline:
-
-```text
-processOperation(envelope, vaultRoot, options)
-  -> envelope validation
-  -> idempotency replay/conflict check
-  -> authorization
-  -> lease validation
-  -> deterministic schema validation
-  -> atomic commit
-  -> audit event
-```
-
-Use `writeNodeValidated()` for Total Recall memory writes. Do not call raw
-`writeNode()` or write files directly when an agent is mutating an SSSS vault.
-
-Total Recall implements all four canonical envelope types in
-`processOperation()`:
-
-- `operation` — full file create/replace.
-- `patch` — partial frontmatter/body merge.
-- `event` — append-only JSON event payload.
-- `delete` — remove a replace-type VFS file (SSSS spec §6.2). Refuses to delete
-  append-type documents (`conversation`, `run`), and emits an auditable deletion
-  event so history is never lost. Idempotent. For *memory* removal, still prefer
-  the CLI/API forget/archive flow over a raw `delete` envelope.
-
-Use `dry_run: true` for preflight validation when constructing writes from model
-output.
-
-## Universal Frontmatter / OKF
-
-SSSS v0.7.0 / spec v0.6 is an OKF-compatible Markdown contract. Every SSSS
-document primitive, including skills, memory, workflows, assistants, pages,
-models, migrations, and releases, MUST carry non-empty universal frontmatter:
-
-- `type`
-- `title`
-- `description`
-- `timestamp`
-
-Recommended OKF-compatible fields are:
-
-- `resource`
-- `tags`
-- `aliases`
-
-Primitive-specific required fields still apply on top of the universal fields.
-For example, a `workflow` still needs its workflow identity fields, and
-`schema_version: 2` memory nodes still need the knowledge-graph fields below.
-Do not "fix" OKF compatibility by weakening primitive validation; add the
-universal metadata and keep the primitive registry strict.
-
-## Security Contract
-
-The reference engine now treats path and replay safety as part of the standard:
-
-- `workspace_id`, `idempotency_key`, and `actor.role` must be safe identifiers:
-  ASCII alphanumeric start, then ASCII letters, digits, `.`, `_`, or `-`, max
-  128 characters.
-- Operation paths must be relative vault paths. Reject empty/root paths, `.`,
-  `..`, absolute paths, backslashes, null bytes, empty segments, and directory
-  targets.
-- `type` is immutable after creation. An operation or patch must not rewrite an
-  existing file from one primitive type to another.
-- Append-only primitives may only preserve existing content exactly or append
-  after the existing body plus a newline. Prefix tricks are not enough.
-- Idempotency is scoped by `workspace_id + idempotency_key + request_hash`.
-  Replaying the same effective request returns the original result; reusing the
-  same key/workspace with a different effective request is an idempotency
-  conflict and must fail.
-- Leases fail closed. Corrupt or unreadable lease state does not authorize a
-  write, and lease storage must not expose the VFS path directly.
-- Bundle import/export must reject unsafe or duplicate file paths, and exporters
-  must not follow symlinked vault entries into files outside the vault.
-
-## Canonical State
-
-The vault is source-of-truth. Derived files, embeddings, search indexes,
-instruction shims, UI caches, and projection manifests are disposable and must be
-rebuildable from Markdown vault state plus append-only events.
-
-Total Recall is database-free. Do not look for Postgres or SQLite as the record of
-truth. The internal vector store is a derived index, not canonical state.
-
-## Scope Layers
-
-Total Recall memory has layered vault scope:
-
-- `global` — machine/user-level brain shared across registered projects.
-- `project` — repository-local brain and session context.
-
-Host applications can add product runtime scopes such as `system`, `account`, and
-`workspace`. The UltraChat implementation proved the rule that shared system
-skills must be inherited through an overlay, not copied into every workspace.
-When authoring portable SSSS guidance, preserve this separation:
-
-- system/platform primitives are hidden shared defaults;
-- account-local primitives must not leak into workspace runtimes unless forked or
-  explicitly installed;
-- workspace primitives can shadow shared system defaults;
-- legacy copied system artifacts should be treated as derived cleanup targets only
-  when metadata proves they are seeded copies.
-
-Do not flatten these layers into one directory or one effective identity in docs,
-validators, or examples.
-
-## Primitive Registry
-
-`src/core/schema.mjs` is the implementation registry. `references/ssss-spec.md`
-is the vendor-neutral baseline. When adding or changing a primitive:
-
-1. Update `SSSS_SCHEMAS` and the relevant Zod schema.
-2. Update the spec or this skill if the primitive is standard or host-specific
-   respectively.
-3. Add/adjust fixtures or tests for the required fields and invalid cases.
-4. Confirm projection behavior is declared as source, projection, or external
-   state.
-
-The current implementation includes the core spec primitives plus host/product
-extensions such as `personalization_profile`, `account_assistant`,
-`account_memory`, `account_workflow`, `workspace_transfer`, CRM/CMS/commerce
-types, telephony types, and workspace/package types. Treat those as implemented
-host extensions unless the spec explicitly standardizes them.
-
-## Memory Nodes
-
-Memory files under `.agent/memory-vault/**` are `type: memory` and must satisfy
-SSSS schema v2. Required schema v2 knowledge-graph fields are:
-
-- `confidence`
-- `importance`
-- `modality`
-- `subject`
-- `predicate`
-- `object`
-- `sentiment_polarity`
-- `sentiment_target`
-
-Invariants additionally use `priority: absolute` and `immutable: true`.
-
-Memory validation is owned by `TotalRecallMemoryValidator`, not by generic loose
-frontmatter checks. No memory path may be committed with zero validation.
-
-## Reads And Writes
-
-- Use `vault-cache.mjs` `getNodes()` for vault reads. Do not call `loadNodes()`
-  directly in new code.
-- Use `writeNodeValidated()` or `processOperation()` for writes.
-- Invalidate the vault cache after successful writes.
-- Keep append-type documents append-only. `conversation` and `run` may append
-  body records but must not rewrite prior records.
-- Events are immutable. Do not update or delete event records.
-- Leases must be time-bound, actor-owned, operation-linked, and recoverable.
-- Workflow daemons, crons, webhook workers, and agent hosts must treat workflow
-  frontmatter triggers as canonical and use deterministic runtime planning
-  (`@ssss/cli/runtime`) to derive event/task/run envelopes.
-- Bundle exporters/importers must use the canon's path, content hash,
-  portability, and provisioning validation. `template` and `sale` profiles must
-  drop every `tenant_private` primitive and reduce `resource_bound` values to
-  requirement declarations.
-
-## Projections And Indexes
-
-Projection manifests must mark derived artifacts as disposable and record enough
-provenance to detect drift. A projection must have a rebuild path from vault state
-and events or be documented as external non-projection state.
-
-The canonical search/index stack is the Total Recall semantic index/vector store.
-Do not introduce a second embedding or indexing path for SSSS memory unless the
-spec and tests are updated together.
-
-## Validation
-
-Validate an individual SSSS Markdown file with:
-
-```bash
-node .agent/skills/tr-ssss/scripts/validate-schema.mjs <path-to-node.md>
-```
-
-Run focused kernel tests after changing the operation contract, schema registry,
-validator, or vault cache:
-
-```bash
-npx vitest run \
-  src/core/schema.spec.mjs \
-  src/core/operation-validator.spec.mjs \
-  src/core/total-recall-memory-validator.spec.mjs \
-  src/core/vault-cache.spec.mjs \
-  src/core/ssss-conformance.bridge.spec.mjs
-```
-
-The **conformance bridge** (`src/core/ssss-conformance.bridge.spec.mjs`) runs the
-canonical fixtures from `@ssss/cli` through this kernel's `processOperation` and
-asserts every canonical core primitive is present in `SSSS_SCHEMAS`. It proves the
-kernel implements the *same* standard as the SSSS reference engine and host apps.
-If you change the operation contract or the registry, keep this green; to adopt a
-newer standard, bump the `@ssss/cli` pin and re-run it.
-
-## Do Not
-
-- Do not write agent mutations directly to vault files.
-- Do not make derived indexes or projections canonical.
-- Do not bypass deterministic validation for model-generated changes.
-- Do not collapse `global`/`project` or `system`/`account`/`workspace` scope
-  boundaries.
-- Do not represent copied seeded skills as canonical system primitives.
-- Do not delete append-type documents (`conversation`, `run`); they are immutable.
-- Do not add host-specific required fields to the vendor-neutral spec unless they
-  are being standardized.
-- Do not claim OKF compliance unless `type`, `title`, `description`, and
-  `timestamp` are present and non-empty.
-- Do not replay idempotency keys without comparing `request_hash`.
-- Do not export symlinked vault entries or accept unsafe bundle paths.
-
-## References
-
-| For | Read |
-| --- | --- |
-| Upstream canon (package) | `@ssss/cli` (`v0.7.0`, spec v0.6 draft, github:gregiteen/ssss) |
-| Canonical core registry | `@ssss/cli/registry/core.json` |
-| Runtime helpers | `@ssss/cli/runtime` |
-| Conformance bridge | `src/core/ssss-conformance.bridge.spec.mjs` |
-| SSSS standard (local mirror) | `references/ssss-spec.md` |
-| Implemented schemas | `src/core/schema.mjs` |
-| Operation pipeline | `src/core/operation-validator.mjs` |
-| Validated memory writes | `src/core/validated-write.mjs` |
-| Memory validator | `src/core/total-recall-memory-validator.mjs` |
-| Vault cache | `src/core/vault-cache.mjs` |
-| Total Recall SSSS v2 reference | `.agent/skills/total-recall/references/ssss-reference.md` |

package/scaffold/.agent/skills/total-recall/skills/tr-ssss/evals/evals.json

@@ -1,17 +0,0 @@
-[
-  {
-    "name": "ssss-has-skill-file",
-    "assertion": "The skill directory contains a valid SKILL.md entrypoint",
-    "severity": "error"
-  },
-  {
-    "name": "ssss-has-spec-sheet",
-    "assertion": "The references directory contains ssss-spec.md",
-    "severity": "error"
-  },
-  {
-    "name": "ssss-validates-successfully",
-    "assertion": "The validate-schema script parses frontmatter correctly",
-    "severity": "warning"
-  }
-]

package/scaffold/.agent/skills/total-recall/skills/tr-ssss/references/CHANGELOG.md

@@ -1,124 +0,0 @@
-# Changelog
-
-All notable changes to the SSSS (Structured Semantic Syntax System) spec will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.7.0] - 2026-07-02
-### Changed
-- **BREAKING: universal frontmatter enforcement** — every SSSS document primitive
-  now requires `type`, `title`, `description`, and `timestamp`. Primitive-specific
-  required fields still apply after these universal fields.
-- Registry `spec_version` -> `0.6`; spec header -> v0.6 draft. Reference bundle
-  metadata now targets SSSS core `0.6`.
-- The reference engine, bundle validator, skill validator, runtime helpers,
-  scaffold output, conformance fixtures, shipped skills, and reference bundle now
-  share the universal metadata requirement.
-
-### Added
-- OKF compatibility guidance documenting `resource`, `tags`, and `aliases` as
-  recommended discovery enrichment fields while keeping the mandatory universal
-  metadata minimal and deterministic.
-- Security hardening for the reference engine and CLI:
-  - VFS paths now reject absolute, root, dot-segment, empty-segment, backslash,
-    and directory targets.
-  - `workspace_id`, `idempotency_key`, and role names are constrained to safe
-    filesystem identifiers.
-  - Idempotency replay is bound to a request hash; same-key/different-payload
-    requests now fail as conflicts.
-  - Leases fail closed when unreadable and no longer derive filenames directly
-    from raw VFS paths.
-  - Bundle validation rejects unsafe and duplicate file paths, and export refuses
-    symlinked vault entries.
-  - Autolink skips symlinked Markdown targets before `--write`.
-  - Repo-local skill utility scripts avoid shell-string execution and validate
-    write-target names.
-
-## [0.6.0] - 2026-07-02
-### Added
-- **Workflow Runtime & Daemon Contract (spec §11.8)** — standardizes workflow
-  trigger evaluation across daemon, cron, webhook, file-change, event, condition,
-  and manual runtimes. Workflows own `triggers[]`; external schedulers are only
-  wake-up mechanisms.
-- **`@ssss/cli/runtime` helpers** — deterministic `planWorkflowTrigger()` and
-  `createRunEnvelope()` helpers derive `workflow_triggered` events, task
-  documents, and run documents through the Operation Contract.
-- **Runtime conformance metadata/checks** — `conformance/fixtures.json` v1.3.0
-  declares trigger/misfire/concurrency vocabularies and proves duplicate daemon
-  ticks replay idempotently.
-
-### Changed
-- Registry `spec_version` -> `0.5`; spec header -> v0.5 draft. Reference bundle
-  metadata now targets SSSS core `0.5`.
-
-## [0.5.0] - 2026-06-25
-### Added
-- **`ssss new <dir>` scaffolder** — bootstrap a fresh SSSS-native repo in one command:
-  a starter `vault/` of core primitives (incl. a `tenant_private` task to demonstrate
-  the sale-drop), a dependency-free conformance test (`node --test`) that replays the
-  canonical fixtures through the engine and round-trips the vault as a `sale` bundle,
-  plus `package.json` (pinned to the matching `@ssss/cli` tag), `CLAUDE.md`, `README`,
-  and `.gitignore`. Flags: `--with-total-recall` (wire the Total Recall memory OS),
-  `--install` (npm install + Total Recall init + verify), `--ref`, `--name`, `--force`,
-  `--no-git`. All shelling-out uses `execFileSync` with fixed argv (no shell). Docs:
-  `ssss help scaffold`.
-
-## [0.4.0] - 2026-06-24
-### Added
-- **The `.ucw` bundle format (spec §16, registry `bundle`)** — the canonical transportable
-  package of a vault: a manifest plus path-sorted files, content-hashed for integrity. The
-  manifest declares `ssss_core_version`, `required_extensions`, `export_profile`,
-  `primitive_inventory` (registry-driven, replacing ultrachat's closed `categories` enum),
-  `provisioning[]`, `parameters[]`, and `provenance{content_hash, exporter, signature?}`.
-  Harvested from ultrachat's `WorkspaceVfsPackageService` and generalized to be portability-
-  and registry-driven.
-- **The provisioning contract (spec §17, registry `provisioning`)** — three deterministic,
-  idempotent verbs: `export` (pure, profile-filtered), `provision` (params + link-integrity
-  + id-remap → replayable envelope plan), `import` (engine replay, idempotent via
-  idempotency_key). Adopts ultrachat's `WorkspaceProvisioningStep.mode`/`system` and
-  `WorkspaceGraphEdge.relation` as the canonical binding/dependency vocabularies, plus
-  `installMode` composition and structural-only `migration`+`patch` upgrades.
-- **Reference engine for bundles (`src/bundle.mjs`)** — dependency-free `exportBundle`,
-  `validateBundle`, `provisionBundle`, `importBundle` over the registry bundle schema.
-- **Reference bundle (`conformance/reference-bundle.ucw.json`, "Festival in a Box")** — a
-  real `sale`-profile bundle, built deterministically by `scripts/build-reference-bundle.mjs`.
-  Proves the §5.5 keystone: structural + resource_bound files ship, the `tenant_private`
-  ticket record is dropped. Round-tripped (validate → provision → import → re-import) by
-  `ssss conformance --engine`; 6/6 bundle/provisioning checks pass alongside the 9 fixtures.
-- **`language_convention` documented (spec §11.7)** — the festech-shipped, `structural`
-  presentation-overlay primitive, formally placed in the semantic layer.
-- **CLI command surface for the full lifecycle** — `ssss export`, `validate`, `inspect`,
-  `provision`, and `import` wire the bundle/provisioning verbs to the command line, plus
-  `ssss help [topic]` serving offline docs from `docs/help/` and `ssss version`. Each
-  command has its own `--help`. Shared parsing/formatting in `scripts/lib/cli.mjs`.
-- **Open-source packaging** — `README.md`, `LICENSE` (ISC), `.gitignore`, and
-  `package.json` metadata (`engines`, `repository`, `files`) so `@ssss/cli` is
-  publishable and the runtime-read paths (`VERSION`, `docs/help`) ship in the tarball.
-
-### Changed
-- Registry `spec_version` → `0.4`; spec header + §14 → v0.4. Engine exports add `./bundle`.
-
-## [0.3.0] - 2026-06-24
-### Added
-- **Portability classification (spec §5.5, registry `portability`)** — every document
-  primitive now declares a portability class: `structural` (the sellable business model),
-  `tenant_private` (the operator's private data, never sold), or `resource_bound` (needs a
-  real resource bound at provision). Export profiles `backup | template | sale` are filters
-  over these classes; `template`/`sale` exports MUST drop all `tenant_private` primitives.
-  Files MAY override their type default with `x_portability`. Lifted and generalized from
-  ultrachat's ad-hoc export filter in `WorkspaceVfsPackageService`.
-- **`delete` envelope (spec §6.2)** — promoted from festech's `SsssOperationService` into
-  the canonical Operation Contract as the fourth envelope type. Removes a replace-type file,
-  rejects append-type targets, and emits a deletion event for audit. Idempotent.
-- **Reference engine (`src/engine.mjs`, `src/registry.mjs`, `src/frontmatter.mjs`)** — the
-  canonical, dependency-free `@ssss/cli` Operation Contract engine. Harvested from total-recall
-  (§6.3 pipeline, idempotency replay from the audit log, `buildRepair`/§9 repair blocks) and
-  festech (`delete` envelope, `resolveContainedPath` path-traversal guard, registry-driven
-  content validation). Validates content against `registry/core.json` + `registry/extensions/*`
-  with no per-type code and no Zod/YAML dependency. Runs all 9 conformance fixtures in-process
-  via `ssss conformance --engine` (now wired into `npm test`).
-
-### Changed
-- Registry now defines **5 contract primitives** (added `delete`); `spec_version` → `0.3`.
-- §5.1 Document Primitives table gains a **Portability** column.