total-recall-brain 3.9.0 → 3.11.0

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

@@ -1,5 +1,6 @@
 ---
-name: ssss
+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."
 ---
 
@@ -12,9 +13,18 @@ schema/reference files.
 
 ## Ground Truth
 
-The vendor-neutral contract is `references/ssss-spec.md`. If this skill conflicts
-with the spec, correct this skill unless the implementation has intentionally
-advanced beyond the vendored spec and the difference is documented here.
+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:
 
@@ -27,6 +37,33 @@ Current local implementation entry points:
 - `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:
@@ -34,7 +71,7 @@ All agent-generated mutations must flow through the SSSS operation pipeline:
 ```text
 processOperation(envelope, vaultRoot, options)
   -> envelope validation
-  -> idempotency check
+  -> idempotency replay/conflict check
   -> authorization
   -> lease validation
   -> deterministic schema validation
@@ -45,21 +82,66 @@ processOperation(envelope, vaultRoot, options)
 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 currently implements these envelope types in
+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.
-
-The UltraChat host also models a `delete` envelope. Do not claim or use `delete`
-inside the Total Recall kernel until `src/core/schema.mjs` and
-`src/core/operation-validator.mjs` implement and test it. For memory removal, use
-the CLI/API forget/archive flow.
+- `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,
@@ -125,9 +207,6 @@ SSSS schema v2. Required schema v2 knowledge-graph fields are:
 
 Invariants additionally use `priority: absolute` and `immutable: true`.
 
-### OKF Compatibility Note
-SSSS v0.2 is a strict superset of the Open Knowledge Format (OKF v0.1 Draft). SSSS memory nodes are fully OKF-compatible, as they are Markdown files containing a YAML frontmatter block with a `type` field (which maps to SSSS `category` via the OKF adapter). To bridge the format seamlessly, SSSS v0.2 extends `MemoryNodeSchema` with two optional OKF-standard fields: `description` and `resource` (supporting non-HTTP URIs such as `gs://` or `s3://`).
-
 Memory validation is owned by `TotalRecallMemoryValidator`, not by generic loose
 frontmatter checks. No memory path may be committed with zero validation.
 
@@ -141,6 +220,13 @@ frontmatter checks. No memory path may be committed with zero validation.
   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
 
@@ -157,7 +243,7 @@ spec and tests are updated together.
 Validate an individual SSSS Markdown file with:
 
 ```bash
-node .agent/skills/ssss/scripts/validate-schema.mjs <path-to-node.md>
+node .agent/skills/tr-ssss/scripts/validate-schema.mjs <path-to-node.md>
 ```
 
 Run focused kernel tests after changing the operation contract, schema registry,
@@ -168,9 +254,17 @@ 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/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.
@@ -179,16 +273,23 @@ npx vitest run \
 - Do not collapse `global`/`project` or `system`/`account`/`workspace` scope
   boundaries.
 - Do not represent copied seeded skills as canonical system primitives.
-- Do not claim Total Recall supports `delete` envelopes until the implementation
-  supports them.
+- 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 |
 | --- | --- |
-| SSSS standard | `references/ssss-spec.md` |
+| 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` |

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

@@ -0,0 +1,124 @@
+# 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.