@gregiteen/ssss-cli 0.9.6 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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
+  serializer wrote `"07003"` unquoted and the parser read any all-digit value
+  as an integer, so a zip code or license number with a leading zero lost it
+  (`07003` became `7003`) once any other field of the document was patched,
+  and YAML 1.1 readers such as PyYAML read the unquoted value as octal
+  (`07003` → 3587).
+
+### Behavior changes hosts should check
+- Strings that would read back as a number, boolean or null (`"07003"`,
+  `"00123"`, `"1.10"`, `"true"`, `"null"`) are now written double-quoted.
+- An unquoted scalar with a leading zero (`zip: 07003`) now parses as the
+  string `"07003"`, not an integer; plain integers (`0`, `42`, `-5`) are
+  unchanged. Documents already rewritten without the zero cannot be recovered
+  by the library.
+- New conformance check: number-like strings survive repeated patches.
+
 ## [0.9.6] - 2026-09-25
 ### Changed
 - The push skill describes this repo's real release path. `/push` is always a

package/VERSION

@@ -1 +1 @@
-0.9.6
+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.6"
+      "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.6",
+  "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);
@@ -121,7 +122,9 @@ export async function run(argv) {
     }
     if (withTR) {
       log('\nInitializing Total Recall memory vault…');
-      tryRun('npx', ['-p', 'total-recall-brain', 'total-recall', 'init'], root);
+      if (!tryRun('npx', ['-p', 'total-recall-brain', 'total-recall', 'init', '--project'], root)) {
+        die('scaffolded and installed, but project Total Recall init failed. Run `npx total-recall init --project` in the new directory.', 1);
+      }
     }
     log('\nVerifying the toolchain (npm test)…');
     if (!tryRun('npm', ['test'], root)) {
@@ -135,7 +138,7 @@ export async function run(argv) {
   console.log(`  cd ${path.relative(process.cwd(), root) || '.'}`);
   if (!flags.install) {
     console.log('  npm install');
-    if (withTR) console.log('  npx -p total-recall-brain total-recall init   # seed the memory vault');
+    if (withTR) console.log('  npx -p total-recall-brain total-recall init --project   # seed this project memory vault');
   }
   console.log('  npm test                       # replays the canonical fixtures + round-trips the vault');
   console.log('  npx ssss export vault --profile sale --out dist/bundle.ucw.json');
@@ -226,7 +229,7 @@ ${withTR ? `
 This project is also wired for [Total Recall](https://github.com/gregiteen/total-recall):
 
 \`\`\`bash
-npx -p total-recall-brain total-recall init      # seed .agent/skills/total-recall
+npx -p total-recall-brain total-recall init --project   # seed this project memory vault
 npx total-recall remember fact "..."             # persist a fact
 npx total-recall recall "..."                    # semantic recall
 \`\`\`
@@ -260,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.
+`;
+}

package/scripts/cmd-registry.mjs

@@ -6,7 +6,7 @@ import { parseArgs, die, wantsHelp } from './lib/cli.mjs';
 
 const HELP = 'Usage: ssss registry compose|lock|verify [--extension <file> ...] [--lock <file>] [--out <file>]';
 const read = (file) => JSON.parse(fs.readFileSync(path.resolve(file), 'utf8'));
-function serializable(set) { return { primitives: Object.fromEntries(set.primitives), aliases: Object.fromEntries(set.aliases), extension_versions: Object.fromEntries(set.extensionVersions) }; }
+function serializable(set) { return { primitives: Object.fromEntries(set.types), aliases: Object.fromEntries(set.aliases), extension_versions: Object.fromEntries(set.extensionVersions) }; }
 export async function run(argv) {
   if (wantsHelp(argv)) { console.log(HELP); return; }
   const verb = argv[0];

package/scripts/conformance.mjs

@@ -404,6 +404,29 @@ async function runOperationContractRegressionConformance() {
       patchRes.success === true && Array.isArray(patchedData.triggers) && patchedData.triggers[0]?.cron === '0 8 * * *',
       patched);
 
+    const codeRes = await engine.processOperation({
+      type: 'patch',
+      idempotency_key: 'leading-zero-patch',
+      workspace_id: 'ws-reg',
+      path: workflowPath,
+      actor: { role: 'system' },
+      patches: { zip: '07003', license: '00123', flag: 'true' },
+    }, vault);
+    await engine.processOperation({
+      type: 'patch',
+      idempotency_key: 'leading-zero-repatch',
+      workspace_id: 'ws-reg',
+      path: workflowPath,
+      actor: { role: 'system' },
+      patches: { description: 'A later, unrelated patch.' },
+    }, vault);
+    const codeText = fs.readFileSync(path.join(vault, workflowPath), 'utf8');
+    const codeData = parseDocument(codeText).data;
+    check('number-like strings (zip 07003, license 00123, "true") survive repeated patches',
+      codeRes.success === true && codeData.zip === '07003' && codeData.license === '00123'
+        && codeData.flag === 'true' && codeText.includes('zip: "07003"'),
+      codeText);
+
     const leaseTarget = 'rules/leased.md';
     const leasePathKey = crypto.createHash('sha256').update(leaseTarget).digest('hex');
     const leaseDir = path.join(leaseStore, 'ws-reg');
@@ -728,6 +751,42 @@ async function runCliSmokeConformance() {
       typeof lockOut.integrity === 'string' && lockOut.integrity.startsWith('sha256:'),
       JSON.stringify(lockOut));
 
+    const composed = JSON.parse(execFileSync('node', [
+      path.join(__dirname, 'ssss.mjs'),
+      'registry', 'compose',
+      '--extension', extensionPath,
+    ], { encoding: 'utf8' }));
+    check('ssss registry compose includes core and extension primitives',
+      !!composed.primitives.rule && composed.aliases['ssss:rule'] === 'rule' &&
+      composed.primitives[primitiveOut.primitive_id]?.registry === 'acme',
+      JSON.stringify(composed));
+
+    const fakeBin = path.join(tmp, 'bin');
+    const calls = path.join(tmp, 'install-calls.txt');
+    fs.mkdirSync(fakeBin);
+    for (const command of ['npm', 'npx']) {
+      const executable = path.join(fakeBin, command);
+      fs.writeFileSync(executable, '#!/bin/sh\nprintf "%s|%s|%s\\n" "$PWD" "$0" "$*" >> "$SSSS_TEST_CALLS"\n');
+      fs.chmodSync(executable, 0o755);
+    }
+    const trStarter = path.join(tmp, 'with-total-recall');
+    execFileSync('node', [path.join(__dirname, 'ssss.mjs'), 'new', trStarter,
+      '--with-total-recall', '--install', '--no-git'], {
+      stdio: 'ignore',
+      env: { ...process.env, PATH: `${fakeBin}${path.delimiter}${process.env.PATH}`, SSSS_TEST_CALLS: calls },
+    });
+    const installCalls = fs.readFileSync(calls, 'utf8').trim().split('\n');
+    const normalizedCalls = installCalls.map((line) => {
+      const [cwd, executable, args] = line.split('|');
+      return `${fs.realpathSync(cwd)}|${path.basename(executable)}|${args}`;
+    });
+    const realStarter = fs.realpathSync(trStarter);
+    check('ssss new initializes only the new project Total Recall brain',
+      normalizedCalls.some((line) => line === `${realStarter}|npx|-p total-recall-brain total-recall init --project`) &&
+      normalizedCalls.some((line) => line === `${realStarter}|npm|install --no-audit --no-fund`) &&
+      normalizedCalls.some((line) => line === `${realStarter}|npm|test`),
+      JSON.stringify(installCalls));
+
     const adapterOut = JSON.parse(execFileSync('node', [
       path.join(__dirname, 'ssss.mjs'),
       'adapter', 'conformance',

package/src/frontmatter.mjs

@@ -36,7 +36,8 @@ function coerce(raw) {
   if (v === 'true') return true;
   if (v === 'false') return false;
   if (v === 'null' || v === '~') return null;
-  if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+  // A leading zero (zip 07003, license 00123) marks a code, not a number.
+  if (/^-?(0|[1-9]\d*)$/.test(v)) return parseInt(v, 10);
   if (/^-?\d*\.\d+$/.test(v)) return parseFloat(v);
   if (v.startsWith('[') && v.endsWith(']')) {
     const inner = v.slice(1, -1).trim();
@@ -200,12 +201,18 @@ export function parseDocument(content) {
   return { data: parseFrontmatter(fm), body };
 }
 
+const LOOKS_TYPED =
+  /^(?:[-+]?\d+(?:\.\d*)?(?:[eE][-+]?\d+)?|[-+]?\.\d+|0[xXoObB][0-9a-fA-F_]+|true|false|yes|no|on|off|null|~|\.inf|\.nan)$/i;
+
 function serializeValue(v) {
   if (v === null) return 'null';
   if (typeof v === 'boolean' || typeof v === 'number') return String(v);
   if (Array.isArray(v)) return `[${v.map((x) => serializeValue(x)).join(', ')}]`;
   const s = String(v);
   if (s === '' || /[:#\[\]{}"'\\\n\r\t|>]/.test(s) || /^\s|\s$/.test(s)) return JSON.stringify(s);
+  // A string that would read back as a number, boolean or null stays quoted,
+  // so "07003" and "true" survive a round trip (here and in YAML 1.1 readers).
+  if (LOOKS_TYPED.test(s)) return JSON.stringify(s);
   return s;
 }