@prismer/runtime 2.0.7 → 2.2.55

package/built-in-skills/role-builder/scripts/instantiate-and-run.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+import {
+  HarnessError,
+  invocationHash,
+  loadHarnessConfig,
+  readLedger,
+  requestJson,
+  sleep,
+  taskIdempotencyKey,
+  writeLedger,
+} from './operation-harness.mjs';
+
+const HELP = `Usage:
+  # with the required PRISMER_* environment already injected:
+  node scripts/instantiate-and-run.mjs [--json]
+
+Configuration stays in environment variables. Non-secret flags are available:
+  --role --workspace --task --title --handle --display-name --adapter
+  --target-daemon --request-id --ledger --timeout-ms --poll-ms
+  --preflight-only --no-wait --json
+
+Remote writes require PRISMER_ALLOW_REMOTE_WRITE=1 from the trusted environment.
+Set PRISMER_REQUEST_ID once when an interrupted operation must be resumed.
+
+Exit codes: 2 local harness rejection, 3 auth, 4 transient/network, 5 remote contract.`;
+
+function instanceBody(config) {
+  return {
+    workspaceId: config.workspaceId,
+    requestId: config.requestId,
+    ...(config.handle ? { handle: config.handle } : {}),
+    ...(config.displayName ? { displayName: config.displayName } : {}),
+    adapterName: config.adapterName,
+    ...(config.targetDaemonId ? { targetDaemonId: config.targetDaemonId } : {}),
+  };
+}
+
+function emit(config, ledger) {
+  if (config.json) process.stdout.write(`${JSON.stringify(ledger)}\n`);
+  else {
+    process.stdout.write(
+      `[role-builder] ${ledger.stage}: role=${config.role} workspace=${config.workspaceId}` +
+        `${ledger.agent?.id ? ` agent=${ledger.agent.id}` : ''}${ledger.task?.id ? ` task=${ledger.task.id}` : ''}\n`,
+    );
+  }
+}
+
+async function findExistingInstance(config) {
+  try {
+    const read = await requestJson(
+      config,
+      'GET',
+      `/api/im/role-templates/${encodeURIComponent(config.role)}/instances/${encodeURIComponent(config.requestId)}`,
+      undefined,
+      'operation_lookup',
+    );
+    return read.data;
+  } catch (error) {
+    if (error instanceof HarnessError && error.details?.status === 404) return null;
+    throw error;
+  }
+}
+
+async function waitForInstance(config, initial, ledger) {
+  let instance = initial;
+  const started = Date.now();
+  let lastResumeAt = started;
+  while (Date.now() - started < config.timeoutMs) {
+    if (instance.status === 'failed') {
+      throw new HarnessError(
+        'instance',
+        instance.error?.code || 'ROLE_INSTANCE_FAILED',
+        instance.error?.message || 'role instance provisioning failed',
+        instance.error?.retryable ? 4 : 5,
+      );
+    }
+    if (instance.execution?.state === 'wrong_daemon') {
+      throw new HarnessError(
+        'instance_wait',
+        'ROLE_INSTANCE_WRONG_DAEMON',
+        `agent is bound to ${instance.execution.boundDaemonId || 'an unknown daemon'} instead of ${instance.execution.targetDaemonId || 'the requested daemon'}`,
+        5,
+        {
+          targetDaemonId: instance.execution.targetDaemonId ?? null,
+          boundDaemonId: instance.execution.boundDaemonId ?? null,
+        },
+      );
+    }
+    // A task must never be created for an agent that the runtime has not yet
+    // adopted. `--no-wait` skips only the final task-result wait.
+    if (instance.status === 'ready' && instance.execution?.state === 'ready') return instance;
+    await sleep(config.pollMs);
+    const read = await requestJson(
+      config,
+      'GET',
+      `/api/im/role-templates/${encodeURIComponent(config.role)}/instances/${encodeURIComponent(config.requestId)}`,
+      undefined,
+      'instance_wait',
+    );
+    instance = read.data;
+    ledger.instance = instance;
+    ledger.stage = instance.status === 'ready' ? 'waiting_for_runtime' : 'provisioning_agent';
+    ledger.updatedAt = new Date().toISOString();
+    writeLedger(config.ledgerPath, ledger);
+
+    // A process may die after accepting the operation. Periodically re-POSTing
+    // is safe: the server lease decides whether this caller may resume it.
+    if (instance.status === 'provisioning' && Date.now() - lastResumeAt >= 35_000) {
+      const resumed = await requestJson(
+        config,
+        'POST',
+        `/api/im/role-templates/${encodeURIComponent(config.role)}/instances`,
+        instanceBody(config),
+        'instance_resume',
+      );
+      instance = resumed.data;
+      lastResumeAt = Date.now();
+    }
+  }
+  throw new HarnessError('instance_wait', 'WORKFLOW_TIMEOUT', 'timed out waiting for agent runtime binding', 4);
+}
+
+async function waitForTask(config, task, ledger) {
+  const started = Date.now();
+  while (Date.now() - started < config.timeoutMs) {
+    if (['completed', 'failed', 'cancelled'].includes(task.status)) return task;
+    await sleep(config.pollMs);
+    const read = await requestJson(
+      config,
+      'GET',
+      `/api/im/tasks/${encodeURIComponent(task.id)}`,
+      undefined,
+      'task_wait',
+    );
+    task = read.data;
+    ledger.task = task;
+    ledger.stage = 'waiting_for_task';
+    ledger.updatedAt = new Date().toISOString();
+    writeLedger(config.ledgerPath, ledger);
+  }
+  throw new HarnessError('task_wait', 'WORKFLOW_TIMEOUT', 'timed out waiting for task result', 4);
+}
+
+export async function runRoleWorkflow(config) {
+  const acceptedHash = invocationHash(config);
+  const previous = readLedger(config.ledgerPath);
+  if (
+    previous &&
+    (previous.requestId !== config.requestId ||
+      previous.role !== config.role ||
+      previous.workspaceId !== config.workspaceId ||
+      (previous.invocationHash && previous.invocationHash !== acceptedHash))
+  ) {
+    throw new HarnessError(
+      'local_validation',
+      'OPERATION_LEDGER_CONFLICT',
+      'the ledger path belongs to a different role workflow request',
+      2,
+    );
+  }
+  const ledger = {
+    schemaVersion: 2,
+    requestId: config.requestId,
+    invocationHash: acceptedHash,
+    role: config.role,
+    workspaceId: config.workspaceId,
+    stage: 'local_validation_complete',
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  // Persist the recovery key before the first request. Credentials are never
+  // written to the ledger or included in the result.
+  writeLedger(config.ledgerPath, ledger);
+
+  const existing = config.preflightOnly ? null : await findExistingInstance(config);
+  if (!existing || config.preflightOnly) {
+    const preflight = await requestJson(
+      config,
+      'POST',
+      `/api/im/role-templates/${encodeURIComponent(config.role)}/instances/preflight`,
+      instanceBody(config),
+      'remote_preflight',
+    );
+    ledger.preflight = preflight.data;
+    ledger.stage = 'remote_preflight_complete';
+    ledger.updatedAt = new Date().toISOString();
+    writeLedger(config.ledgerPath, ledger);
+    if (config.preflightOnly) return ledger;
+  } else {
+    ledger.instance = existing;
+    ledger.stage = 'operation_recovered';
+    ledger.updatedAt = new Date().toISOString();
+    writeLedger(config.ledgerPath, ledger);
+  }
+
+  // A ready/provisioning durable operation can be resumed from its read face.
+  // A failed operation needs an idempotent POST to re-enter server recovery.
+  const provisioned =
+    existing && existing.status !== 'failed'
+      ? { data: existing }
+      : await requestJson(
+          config,
+          'POST',
+          `/api/im/role-templates/${encodeURIComponent(config.role)}/instances`,
+          instanceBody(config),
+          'instance',
+        );
+  ledger.instance = provisioned.data;
+  ledger.stage = 'provisioning_agent';
+  ledger.updatedAt = new Date().toISOString();
+  writeLedger(config.ledgerPath, ledger);
+  const instance = await waitForInstance(config, provisioned.data, ledger);
+  ledger.instance = instance;
+  ledger.agent = instance.agent;
+  ledger.stage = config.wait ? 'agent_ready' : 'agent_created';
+  ledger.updatedAt = new Date().toISOString();
+  writeLedger(config.ledgerPath, ledger);
+
+  const taskRequestKey = taskIdempotencyKey(config.requestId);
+  const createdTask = await requestJson(
+    config,
+    'POST',
+    '/api/im/tasks',
+    {
+      title: config.title,
+      description: config.task,
+      workspaceId: config.workspaceId,
+      assigneeId: instance.agent.id,
+      runtimeRoute: 'agent',
+      dispatchPolicy: 'on-assign',
+      idempotencyKey: taskRequestKey,
+      metadata: {
+        kind: 'agent_run',
+        createdVia: 'role-builder-script',
+        roleInstanceRequestId: config.requestId,
+      },
+    },
+    'task_create',
+  );
+  ledger.task = createdTask.data;
+  ledger.stage = 'task_created';
+  ledger.updatedAt = new Date().toISOString();
+  writeLedger(config.ledgerPath, ledger);
+
+  if (config.wait) {
+    ledger.task = await waitForTask(config, createdTask.data, ledger);
+    if (ledger.task.status !== 'completed') {
+      throw new HarnessError(
+        'task_wait',
+        `TASK_${String(ledger.task.status).toUpperCase()}`,
+        ledger.task.error || `task ended as ${ledger.task.status}`,
+        5,
+      );
+    }
+  }
+  ledger.stage = config.wait ? 'completed' : 'dispatched';
+  ledger.completedAt = new Date().toISOString();
+  ledger.updatedAt = ledger.completedAt;
+  writeLedger(config.ledgerPath, ledger);
+  return ledger;
+}
+
+async function main() {
+  let config;
+  try {
+    config = loadHarnessConfig(process.argv.slice(2));
+    if (config.help) {
+      process.stdout.write(`${HELP}\n`);
+      return;
+    }
+    const result = await runRoleWorkflow(config);
+    emit(config, result);
+  } catch (error) {
+    const harnessError =
+      error instanceof HarnessError
+        ? error
+        : new HarnessError('internal', 'UNEXPECTED_ERROR', error?.message || String(error), 1);
+    const failure = {
+      ok: false,
+      stage: harnessError.stage,
+      error: { code: harnessError.code, message: harnessError.message, details: harnessError.details },
+      ...(config ? { requestId: config.requestId, ledger: config.ledgerPath } : {}),
+    };
+    process.stderr.write(`${JSON.stringify(failure)}\n`);
+    process.exitCode = harnessError.exitCode;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) await main();

package/built-in-skills/role-builder/scripts/operation-harness.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export class HarnessError extends Error {
+  constructor(stage, code, message, exitCode = 1, details = undefined) {
+    super(message);
+    this.name = 'HarnessError';
+    this.stage = stage;
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+const VALUE_OPTIONS = new Set([
+  '--role',
+  '--workspace',
+  '--task',
+  '--title',
+  '--handle',
+  '--display-name',
+  '--adapter',
+  '--target-daemon',
+  '--request-id',
+  '--timeout-ms',
+  '--poll-ms',
+  '--ledger',
+]);
+const BOOLEAN_OPTIONS = new Set(['--json', '--no-wait', '--preflight-only', '--help']);
+const SECRET_OPTIONS = new Set(['--api-key', '--token', '--jwt', '--secret', '--password']);
+
+function optionName(arg) {
+  if (typeof arg !== 'string') return '';
+  const equalsAt = arg.indexOf('=');
+  return equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+}
+
+export function parseHarnessArgs(argv) {
+  const values = {};
+  const flags = new Set();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const name = optionName(arg);
+    if (SECRET_OPTIONS.has(name)) {
+      throw new HarnessError(
+        'local_validation',
+        'SECRET_ARGUMENT_FORBIDDEN',
+        `${name} is forbidden; credentials must come from environment variables`,
+        2,
+      );
+    }
+    if (BOOLEAN_OPTIONS.has(arg)) {
+      flags.add(arg);
+      continue;
+    }
+    if (!VALUE_OPTIONS.has(arg)) {
+      // Never reflect an untrusted argv token. Besides ordinary typos, it may
+      // contain a credential in an unrecognised --name=value form.
+      throw new HarnessError('local_validation', 'UNKNOWN_ARGUMENT', `unknown argument at position ${index + 1}`, 2);
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new HarnessError('local_validation', 'MISSING_ARGUMENT_VALUE', `${arg} requires a value`, 2);
+    }
+    values[arg] = value;
+    index += 1;
+  }
+  return { values, flags };
+}
+
+function envOrArg(parsed, argName, envName, env) {
+  return parsed.values[argName] ?? env[envName];
+}
+
+function positiveInt(raw, fallback, name) {
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new HarnessError('local_validation', 'INVALID_NUMBER', `${name} must be a positive integer`, 2);
+  }
+  return value;
+}
+
+function isLocalWriteTarget(hostname) {
+  return ['localhost', '127.0.0.1', '::1', 'host.docker.internal'].includes(hostname);
+}
+
+export function loadHarnessConfig(argv, env = process.env) {
+  const parsed = parseHarnessArgs(argv);
+  if (parsed.flags.has('--help')) return { help: true };
+
+  const apiKey = envOrArg(parsed, '__never__', 'PRISMER_API_KEY', env);
+  const role = envOrArg(parsed, '--role', 'PRISMER_ROLE_SLUG', env)?.trim();
+  const workspaceId = envOrArg(parsed, '--workspace', 'PRISMER_WORKSPACE_ID', env)?.trim();
+  const task = envOrArg(parsed, '--task', 'PRISMER_TASK', env)?.trim();
+  const preflightOnly = parsed.flags.has('--preflight-only');
+  const missing = [
+    !apiKey && 'PRISMER_API_KEY',
+    !role && 'PRISMER_ROLE_SLUG/--role',
+    !workspaceId && 'PRISMER_WORKSPACE_ID/--workspace',
+    !task && !preflightOnly && 'PRISMER_TASK/--task',
+  ].filter(Boolean);
+  if (missing.length > 0) {
+    throw new HarnessError(
+      'local_validation',
+      'CONFIG_MISSING',
+      `missing required environment/config: ${missing.join(', ')}`,
+      2,
+    );
+  }
+
+  let baseUrl;
+  try {
+    baseUrl = new URL((env.PRISMER_CLOUD_BASE || 'http://127.0.0.1:3000').replace(/\/$/, ''));
+  } catch {
+    throw new HarnessError('local_validation', 'INVALID_BASE_URL', 'PRISMER_CLOUD_BASE must be a valid URL', 2);
+  }
+  if (
+    !['http:', 'https:'].includes(baseUrl.protocol) ||
+    baseUrl.username ||
+    baseUrl.password ||
+    baseUrl.search ||
+    baseUrl.hash
+  ) {
+    throw new HarnessError(
+      'local_validation',
+      'UNSAFE_BASE_URL',
+      'PRISMER_CLOUD_BASE must be a plain http(s) origin without credentials, query, or hash',
+      2,
+    );
+  }
+  // Remote mutation authority is deliberately environment-owned. A prompt or
+  // copied command must not be able to grant itself authority with a CLI flag.
+  const allowRemote = ['1', 'true', 'yes'].includes(String(env.PRISMER_ALLOW_REMOTE_WRITE).toLowerCase());
+  if (!preflightOnly && !isLocalWriteTarget(baseUrl.hostname) && !allowRemote) {
+    throw new HarnessError(
+      'local_validation',
+      'REMOTE_WRITE_NOT_CONFIRMED',
+      'remote mutation is blocked; set PRISMER_ALLOW_REMOTE_WRITE=1 after confirming the target environment',
+      2,
+    );
+  }
+
+  const adapterName = envOrArg(parsed, '--adapter', 'PRISMER_AGENT_ADAPTER', env)?.trim() || 'hermes';
+  if (!['hermes', 'pi-core', 'claude-code'].includes(adapterName)) {
+    throw new HarnessError('local_validation', 'INVALID_ADAPTER', 'adapter must be hermes, pi-core, or claude-code', 2);
+  }
+  const requestId =
+    envOrArg(parsed, '--request-id', 'PRISMER_REQUEST_ID', env)?.trim() ||
+    `role-run-${randomUUID()}`;
+  if (requestId.length > 191) {
+    throw new HarnessError('local_validation', 'INVALID_REQUEST_ID', 'request id exceeds 191 characters', 2);
+  }
+
+  const config = {
+    apiKey,
+    baseUrl: baseUrl.toString().replace(/\/$/, ''),
+    role,
+    workspaceId,
+    task: task || '',
+    title:
+      envOrArg(parsed, '--title', 'PRISMER_TASK_TITLE', env)?.trim() || (task || `Preflight ${role}`).slice(0, 100),
+    handle: envOrArg(parsed, '--handle', 'PRISMER_AGENT_HANDLE', env)?.trim(),
+    displayName: envOrArg(parsed, '--display-name', 'PRISMER_AGENT_DISPLAY_NAME', env)?.trim(),
+    adapterName,
+    targetDaemonId: envOrArg(parsed, '--target-daemon', 'PRISMER_TARGET_DAEMON_ID', env)?.trim(),
+    requestId,
+    timeoutMs: positiveInt(envOrArg(parsed, '--timeout-ms', 'PRISMER_WORKFLOW_TIMEOUT_MS', env), 600_000, 'timeout'),
+    pollMs: positiveInt(envOrArg(parsed, '--poll-ms', 'PRISMER_WORKFLOW_POLL_MS', env), 2_000, 'poll interval'),
+    ledgerPath: resolve(
+      envOrArg(parsed, '--ledger', 'PRISMER_OPERATION_LEDGER', env) || `.prismer/operations/${requestId}.json`,
+    ),
+    wait: !parsed.flags.has('--no-wait'),
+    preflightOnly,
+    json: parsed.flags.has('--json'),
+  };
+  if (config.handle && !/^[a-z0-9][a-z0-9_-]{1,63}$/.test(config.handle)) {
+    throw new HarnessError('local_validation', 'INVALID_HANDLE', 'agent handle has an invalid shape', 2);
+  }
+  return config;
+}
+
+export function writeLedger(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export function readLedger(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    throw new HarnessError(
+      'local_validation',
+      'INVALID_OPERATION_LEDGER',
+      'the operation ledger exists but is not valid JSON',
+      2,
+    );
+  }
+}
+
+export function invocationHash(config) {
+  return createHash('sha256')
+    .update(
+      JSON.stringify({
+        requestId: config.requestId,
+        role: config.role,
+        workspaceId: config.workspaceId,
+        task: config.task,
+        title: config.title,
+        handle: config.handle ?? null,
+        displayName: config.displayName ?? null,
+        adapterName: config.adapterName,
+        targetDaemonId: config.targetDaemonId ?? null,
+      }),
+    )
+    .digest('hex');
+}
+
+export function taskIdempotencyKey(requestId) {
+  return `role-task-${createHash('sha256').update(requestId).digest('hex')}`;
+}
+
+export async function requestJson(config, method, path, body, stage) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.min(config.timeoutMs, 120_000));
+  let response;
+  try {
+    response = await fetch(`${config.baseUrl}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${config.apiKey}`,
+        'content-type': 'application/json',
+        ...(body?.idempotencyKey ? { 'x-idempotency-key': body.idempotencyKey } : {}),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const message = error?.name === 'AbortError' ? 'request timed out' : error?.message || String(error);
+    throw new HarnessError(stage, 'NETWORK_ERROR', message, 4);
+  } finally {
+    clearTimeout(timer);
+  }
+  const payload = await response.json().catch(() => null);
+  if (!response.ok || payload?.ok === false) {
+    const serverError = payload?.error;
+    throw new HarnessError(
+      stage,
+      serverError?.code || `HTTP_${response.status}`,
+      serverError?.message || serverError || `request failed with HTTP ${response.status}`,
+      response.status === 401 || response.status === 403 ? 3 : response.status >= 500 ? 4 : 5,
+      { status: response.status, retryable: serverError?.retryable === true },
+    );
+  }
+  return { status: response.status, data: payload?.data ?? payload };
+}
+
+export function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}

package/built-in-skills/skill-authoring/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: skill-authoring
+scope: common
+description: Low-level helper for the DRAFT-GATED (review) tier of skill authoring — it is NOT the entry point for creating skills. To make/build/author a skill, use `skill-creator` (the single canonical skill author). This page only documents skill-creator's draft tier — generating a `status=draft` skill via `POST /api/im/skills/draft` (`cloud skill draft create`) for human review in Studio Authoring, plus the skill.json + sampleTasks/acceptanceCriteria test contract. Do NOT route here when the user wants to create a skill — route to skill-creator and add `--draft` only when human review is required.
+license: MIT
+compatibility:
+  - prismer-sdk
+  - hermes
+  - claude-code
+  - codex
+---
+
+# Skill Authoring — the draft-gated tier of `skill-creator`
+
+> **Not an authoring entry point.** Creating or editing a skill is the job of
+> **`skill-creator`** — the single canonical skill author. This page only
+> documents one of skill-creator's two publish trust tiers (**draft-gated**),
+> for the case where a skill must be reviewed by a human before it goes live.
+> If the user says "make this a skill" / "create a skill for X", **use
+> `skill-creator`**, not this.
+
+## Where this fits
+
+`skill-creator` drives the full lifecycle author→validate→test→package→publish.
+At the publish step there are two trust tiers ([[16-skill-role-authoring-as-agent-capability]] §5.3):
+
+- **Direct create (default)** — `cloud skill create ./<dir>` → `status=active`,
+  `publishScope=workspace` (**private**, installable — NOT the public marketplace).
+  Putting it in the marketplace is a separate `cloud skill publish`. Under `skill-builder`.
+- **Draft-gated (explicit, this page)** — `cloud skill draft create` →
+  `status=draft`, Studio Authoring reviews and promotes it. Opt into this **only
+  when human review is required** — the default is direct publish (decision 4,
+  locked 2026-06-24).
+
+Both tiers are reached from inside `skill-creator`; this is a publish-verb
+choice, not a separate skill to author in.
+
+## Draft submission (the review-gated path)
+
+When the workflow requires human review before a skill is live, submit a draft
+instead of publishing directly:
+
+```bash
+cloud skill draft create ./<bundle-dir>   # optional: --workspace-id <id> --json
+# → POST /api/im/skills/draft. Cloud reads the directory, runs the 7 validation
+#   gates, and returns { id, slug, status: draft }. Does NOT publish.
+```
+
+> ⚠️ **`<bundle-dir>` is a directory** holding `SKILL.md` + `skill.json` (+ an
+> optional `scripts/`). The CLI reads and packages the directory on every run, so
+> edits on disk take effect immediately — there is no separate manifest to
+> regenerate. There is **no** `--slug` / `--manifest` flag; the slug is taken from
+> the SKILL.md frontmatter `name`.
+
+The draft lands in `status=draft`; the workspace owner reviews and promotes it
+via Studio Authoring (`/evolution → Studio → Authoring`). Do **not** auto-publish
+or chain into install — promotion is the owner's call.
+
+> Do NOT call `POST /api/im/skills` (direct publish) when the intent is review-gated —
+> that bypasses the draft state. Use `--draft` deliberately.
+
+## `skill.json` — where security + the test contract live
+
+**Read this first — it is the #1 draft-tier gotcha.** The bundle must contain a
+`skill.json` alongside `SKILL.md` (cloud locates each file by name, so a
+`scripts/` dir sorted in between is fine). Cloud reads `security` and the test
+contract from **`skill.json`**, and **NEVER** from the `SKILL.md` YAML
+frontmatter. If you put `security:` / `dataAccess:` in the
+SKILL.md frontmatter, gate 5 still fails with "security.dataAccess must be
+non-empty" no matter how you format the YAML — it is reading a different file.
+
+### `security` (blocking — gate 5)
+
+```json
+{
+  "schemaVersion": 1,
+  "slug": "<slug>",
+  "security": {
+    "dataAccess": ["workspace-assets"],
+    "humanApprovalRequiredFor": []
+  }
+}
+```
+
+- **`security.dataAccess`** — non-empty array. Scopes: `workspace-assets` |
+  `memory` | `external-network` | `secrets` | `filesystem`.
+- **`security.humanApprovalRequiredFor`** — **required non-empty IF** `dataAccess`
+  contains a **sensitive** scope (`external-network`, `secrets`, `filesystem`).
+  List the actions needing human approval (e.g. `["filesystem-write"]`).
+- **Least privilege:** if the skill only reads env + prints (no arbitrary user
+  files), declare `["memory"]` — a non-sensitive scope — and
+  `humanApprovalRequiredFor` may stay empty. Only reach for `filesystem` when the
+  skill genuinely reads/writes user files, and then you must also declare
+  approval.
+
+### test contract (drives `cloud skill test`)
+
+The same `skill.json` also carries the VERIFICATION contract exercised by
+`cloud skill test --agent` in lifecycle step ③:
+
+- `runtime.kind` = `'inline-script'` (or `'http-endpoint'`), `runtime.requires`
+  declaring `bins`/`env` the script needs.
+- `inputs` / `outputs` describing the call contract.
+- **`sampleTasks[]`** — at least 2 concrete tasks. EACH MUST have
+  `acceptanceCriteria[]` written as substrings/regex the dispatch OUTPUT must
+  contain (e.g. `"\"status\":\\s*200"`, `"results"`). These are the auto-scored
+  tests: `cloud skill test` dispatches each sampleTask to a real agent and
+  matches its output against the criteria. A sampleTask with no
+  acceptanceCriteria scores `inconclusive` (NOT a pass), so always write them.
+
+> Derive acceptanceCriteria from the spec: required response fields, status
+> codes, schema keys. Tight enough to catch a broken call, not so tight they
+> depend on volatile data.
+
+## Draft validation gates (self-check before submit)
+
+The cloud server runs these at `createDraft` time and rejects with HTTP 400 on a
+blocking failure. Run the same checks locally first (or just `cloud skill validate ./<dir>`):
+
+| Gate           | Check                                                            | Blocking |
+|----------------|------------------------------------------------------------------|----------|
+| `manifest`     | files[] complete; merkle root reproducible                       | yes      |
+| `frontmatter`  | `name` matches `^[a-z][a-z0-9-]*$`; description ≥ 50 quality units (ASCII=1, non-ASCII=2); YAML `|`/`>` supported | yes      |
+| `package`      | bundle contains SKILL.md + skill.json (located by name)          | yes      |
+| `requires`     | runtime.requires declares env/bins/python/node explicitly        | warn     |
+| `security`     | **skill.json** security.dataAccess non-empty; sensitive scopes (external-network/secrets/filesystem) require security.humanApprovalRequiredFor. NOT read from SKILL.md frontmatter. | yes      |
+| `sample`       | at least 1 sampleTask + 1 acceptance criterion                   | warn     |
+| `runtime`      | sandbox executes sample task                                     | deferred |
+
+## Reference
+
+- The skill author (use this): `built-in-skills/skill-creator/SKILL.md`
+- Direct-publish tier: `built-in-skills/skill-builder/SKILL.md`
+- Bundle + catalog contract: `public/docs/Standardization/01-skill-standard.md` (SS-01)