@gregiteen/ssss-cli 0.9.7 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-28
+### Added
+- **`asset` primitive**: Text-encoded files (Base64 for small binaries, UTF-8 for code/SVGs) and pointer metadata for large files (`resource_ref`, `storage_uri`, `hash`).
+- **`resource` primitive**: First-class core support for external cloud infrastructure, databases, S3 buckets, domains, and mailboxes, completing the `resource_bound` portability class (§5.5) with automatic `resource.binds` stripping on bundle export.
+- **`trigger` primitive**: Standalone schedules and event sources (`cron`, `webhook`, `event`), decoupling procedural workflows from scheduling and enabling file-level distributed leasing without workflow lock contention.
+- **`role` and `thread` primitives**: Canonical, concise forms of `security_role` and `conversation` with 100% backward-compatible alias resolution.
+- **`docs/design.md` scaffolding**: `ssss new` now scaffolds a starter architecture and technical design specification alongside `README.md` and `CLAUDE.md`.
+- **Project Management Audit integration**: `scaffold-project.mjs` now includes `AUDIT` in canonical `DOC_TYPES` (the 5-document SWE sequence).
+
+### Behavior changes hosts should check
+- Core registry now recognizes `asset`, `resource`, `trigger`, `role`, and `thread`.
+- Existing documents using `security_role` and `conversation` continue to validate without modification via alias resolution.
+
 ## [0.9.7] - 2026-09-27
 ### Fixed
 - Frontmatter kept number-like strings as text only until the next patch. The

package/VERSION

@@ -1 +1 @@
-0.9.7
+0.10.0

package/conformance/reference-bundle.ucw.json

@@ -106,7 +106,7 @@
     "file_count": 14,
     "provenance": {
       "content_hash": "sha256:7febd673938a3dc04c068e0bf08097a9783c09e612606d2df9a4db8dcb8907f5",
-      "exporter": "@gregiteen/ssss-cli@0.9.7"
+      "exporter": "@gregiteen/ssss-cli@0.10.0"
     }
   },
   "files": [

package/docs/help/scaffold.md

@@ -22,6 +22,7 @@ my-app/
   test/ssss-conformance.test.mjs   Replays the canonical fixtures through the engine
                                     AND round-trips the vault as a sale bundle.
   CLAUDE.md           Agent guide (source-of-truth + portability rules).
+  docs/design.md      Architecture & technical design specification.
   README.md  .gitignore
 ```
 

package/docs/ssss-spec.md

@@ -229,13 +229,18 @@ primitive — it implements the subset its product requires — but any primitiv
 |--------|--------|-------------|---------|
 | `memory` | knowledge | structural | A single unit of agent knowledge (rule, pattern, fact, preference). |
 | `skill` | capability | structural | A skill package manifest. |
+| `asset` | capability | structural | A text-encoded code, vector, or binary asset payload or pointer. |
+| `resource` | capability | resource_bound | An external infrastructure, cloud asset, domain, database, or API dependency. |
 | `rule` | governance | structural | A workspace-scoped behavior rule applied to assistants/agents. |
-| `security_role` | governance | structural | A security role definition for role-based access control (RBAC). |
+| `role` | governance | structural | A security role definition for role-based access control (RBAC). |
+| `security_role` | governance | structural | A security role definition for role-based access control (RBAC). Legacy alias of `role`. |
 | `task` | work | tenant_private | A unit of submitted work — one step or many. The universal work primitive. |
 | `assistant` | actor | structural | The definition of an AI assistant/persona. |
-| `workflow` | work | structural | A reusable **task template**: a defined procedure plus triggers. Firing a workflow submits a `task`. |
+| `workflow` | work | structural | A reusable **task template**: a defined procedure. Firing a workflow submits a `task`. |
+| `trigger` | work | structural | A standalone schedule or event-driven trigger that fires a workflow. |
 | `model` | catalog | structural | The definition of an inference model. |
-| `conversation` | transcript | tenant_private | An append-only chat transcript. |
+| `thread` | transcript | tenant_private | An append-only chat transcript. |
+| `conversation` | transcript | tenant_private | An append-only chat transcript. Legacy alias of `thread`. |
 | `run` | transcript | tenant_private | An append-only workflow execution record. |
 | `conflict` | meta | tenant_private | A record of two contradicting primitives, blocking promotion. |
 | `page` | capability | structural | A VFS-native sandboxed custom workspace page. |
@@ -344,6 +349,50 @@ timestamp: 2026-05-16T14:00:00Z
 ...
 ```
 
+#### `asset`
+
+A text-encoded asset payload: source code, vector graphics, or base64-encoded binary content, or pointer metadata for large files.
+
+REQUIRED: `type`, `name`, `mime_type`, `encoding` (`base64|utf-8|none`).
+
+```markdown
+---
+type: asset
+name: "logo-icon"
+title: "Brand Logo Icon"
+description: "A 1x1 pixel PNG icon encoded in base64."
+timestamp: 2026-05-16T14:00:00Z
+mime_type: "image/png"
+encoding: "base64"
+---
+
+iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
+```
+
+#### `resource`
+
+An external infrastructure, cloud asset, domain, database, or API dependency bound to the workspace. Carries `portability: resource_bound`.
+
+REQUIRED: `type`, `name`, `kind`, `status` (`bound|unbound|pending|error`).
+
+```markdown
+---
+type: resource
+name: "Primary Database"
+title: "Primary Database"
+description: "Application production PostgreSQL database."
+timestamp: 2026-05-16T14:00:00Z
+kind: postgres
+status: bound
+binds:
+  host: "db.internal.net"
+  port: 5432
+  database: "app_prod"
+---
+
+Production PostgreSQL database connection.
+```
+
 #### `task`
 
 A unit of submitted work — the universal work primitive. A `task` MAY be ad-hoc or
@@ -445,6 +494,28 @@ isActive: true
 3. Send digest.
 ```
 
+#### `trigger`
+
+A standalone schedule or event-driven trigger that fires a task from a workflow template.
+
+REQUIRED: `type`, `name`, `source` (`cron|interval|webhook|event|file_change|condition|manual`), `status` (`active|paused|disabled`).
+
+```markdown
+---
+type: trigger
+name: "Daily Sync"
+title: "Daily Sync Trigger"
+description: "Fires the daily synchronization workflow at 08:00 UTC."
+timestamp: 2026-05-16T14:00:00Z
+source: cron
+status: active
+cron: "0 8 * * *"
+target_workflow: "workflows/sync.md"
+---
+
+Triggers daily synchronization.
+```
+
 #### `rule`
 
 A workspace-scoped behavior rule that constrains how assistants/agents act.
@@ -495,6 +566,27 @@ grants everything. A `security_role` is one way for a host to derive a
 principal's capabilities. The kernel only ever sees the resulting capability
 list, never the role name.
 
+#### `role`
+
+A named set of capabilities used for role-based access control (RBAC). Canonical form of `security_role`.
+
+REQUIRED: `type`, `name`, `permissions` (array). OPTIONAL: `description`.
+
+```markdown
+---
+type: role
+name: "support-agent"
+title: "Support agent"
+description: "Can write assistants and events, nothing else."
+timestamp: 2026-05-16T14:00:00Z
+permissions:
+  - "ssss:assistant:*"
+  - "write:event"
+---
+
+Maintains support assistants and records support events.
+```
+
 #### `model`
 
 The definition of an inference model.
@@ -543,6 +635,33 @@ Hello.
 Hi — how can I help?
 ```
 
+#### `thread`
+
+An append-only chat transcript. Append-type. Canonical form of `conversation`.
+
+REQUIRED: `type`, `thread_id`. Typical fields: `workspace_id`, `user_id`, `status`,
+`turn_count`, `created_at`.
+
+```markdown
+---
+type: thread
+title: "Support Thread"
+description: "A two-turn customer support thread."
+timestamp: 2026-05-16T14:00:05Z
+thread_id: "7f3a2b1c-5d6e-4f70-8a91-b2c3d4e5f607"
+workspace_id: "ws-acme"
+user_id: "user-42"
+status: active
+created_at: 2026-05-16T14:00:00Z
+---
+
+### turn 1 — user — 2026-05-16T14:00:00Z
+Hello.
+
+### turn 2 — assistant — 2026-05-16T14:00:05Z
+Hi — how can I help?
+```
+
 #### `run`
 
 An append-only workflow execution record. Append-type.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.9.7",
+  "version": "0.10.0",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {

package/registry/core.json

@@ -33,6 +33,36 @@
       "notes": "Compatible with the open Agent Skills standard (name + description). The `type: skill` discriminator is REQUIRED for SSSS-managed manifests.",
       "spec_ref": "§5.4 skill"
     },
+    "asset": {
+      "family": "capability",
+      "canonical_filename": null,
+      "filename_convention": "kebab-case slug matching the `slug` field",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name", "mime_type", "encoding"],
+      "optional_fields": ["slug", "hash", "size_bytes", "description"],
+      "enums": {
+        "encoding": ["base64", "utf-8", "none"]
+      },
+      "notes": "A text-encoded asset payload: source code, vector graphics, or base64-encoded binary content.",
+      "spec_ref": "§5.4 asset"
+    },
+    "resource": {
+      "family": "capability",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "resource_bound",
+      "required_fields": ["type", "name", "kind", "status"],
+      "optional_fields": ["slug", "description", "binds", "provisioning"],
+      "enums": {
+        "status": ["bound", "unbound", "pending", "error"]
+      },
+      "resource": {
+        "binds": ["binds"]
+      },
+      "notes": "An external infrastructure, cloud asset, domain, database, or API dependency bound to the workspace.",
+      "spec_ref": "§5.4 resource"
+    },
     "rule": {
       "family": "governance",
       "canonical_filename": null,
@@ -42,6 +72,16 @@
       "optional_fields": ["description", "scope"],
       "spec_ref": "§5.4 rule"
     },
+    "role": {
+      "family": "governance",
+      "canonical_filename": "ROLE.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name", "permissions"],
+      "optional_fields": ["description"],
+      "notes": "A named set of capabilities used for role-based access control (RBAC). Canonical form of security_role.",
+      "spec_ref": "§5.4 role"
+    },
     "security_role": {
       "family": "governance",
       "canonical_filename": "ROLE.md",
@@ -78,6 +118,22 @@
       "optional_fields": ["workflow_id", "slug", "description", "triggers", "isActive", "priority", "misfire_policy", "concurrency"],
       "spec_ref": "§5.4 workflow"
     },
+    "trigger": {
+      "family": "work",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name", "source", "status"],
+      "optional_fields": ["slug", "description", "cron", "interval", "timezone", "target_workflow", "target_params", "concurrency", "misfire_policy"],
+      "enums": {
+        "source": ["cron", "interval", "webhook", "event", "file_change", "condition", "manual"],
+        "status": ["active", "paused", "disabled"],
+        "concurrency": ["allow_parallel", "skip_if_running", "enqueue", "replace"],
+        "misfire_policy": ["skip", "run_once", "catch_up"]
+      },
+      "notes": "A standalone schedule or event-driven trigger that fires a task from a workflow template.",
+      "spec_ref": "§5.4 trigger"
+    },
     "model": {
       "family": "catalog",
       "canonical_filename": "MODEL.md",
@@ -86,6 +142,16 @@
       "required_fields": ["type", "model_id", "provider"],
       "spec_ref": "§5.4 model"
     },
+    "thread": {
+      "family": "transcript",
+      "canonical_filename": "CONVERSATION.md",
+      "append_only": true,
+      "portability": "tenant_private",
+      "required_fields": ["type", "thread_id"],
+      "optional_fields": ["workspace_id", "user_id", "status", "turn_count", "created_at"],
+      "notes": "An append-only multi-turn chat transcript. Canonical form of conversation.",
+      "spec_ref": "§5.4 thread"
+    },
     "conversation": {
       "family": "transcript",
       "canonical_filename": "CONVERSATION.md",

package/scripts/cmd-new.mjs

@@ -103,6 +103,7 @@ export async function run(argv) {
   W(root, '.gitignore', 'node_modules/\ndist/\n*.ucw.json\n.DS_Store\n');
   W(root, 'README.md', readme(name, withTR));
   W(root, 'CLAUDE.md', claudeMd(name, withTR));
+  W(root, 'docs/design.md', designMd(name));
 
   // ── git + install (best-effort, flag-gated, no shell) ───────────────────
   const log = (m) => console.error(m);
@@ -262,3 +263,29 @@ ${withTR ? `
   \`npx total-recall remember\` / \`recall\` CLI. Save corrections and decisions there.
 ` : ''}`;
 }
+
+function designMd(name) {
+  return `# ${name} — System Architecture & Design
+
+> Technical design and architecture specification for ${name}.
+
+## Overview
+
+<High-level summary of the system and its primary goals.>
+
+## Component Architecture
+
+- **Vault Structure**: Typed Markdown documents under \`vault/\` serving as the source of truth.
+- **Workflows & Execution**: Automated procedures defined in \`vault/workflows/\` triggered by operational events.
+- **Capabilities & Resources**: Tools and external service integrations required for execution.
+
+## Data & Schema Contracts
+
+<Core entities, external dependencies, and integration interfaces.>
+
+## Open Decisions & Invariants
+
+- SSSS VFS is the single source of truth for application state.
+- Structural business logic is strictly decoupled from private tenant operational data.
+`;
+}