@playcraft/cli 0.0.57 → 0.0.58

package/dist/workspace-runtime/workspaces/prepare.js

@@ -0,0 +1,364 @@
+import { spawn } from 'node:child_process';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { matchWorkspaceGitGatewayCloneUrl, workspaceGitAccessSchema, workspaceGitTransportSchema, workspacePreparationSchema, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { WorkspaceContextError } from './context-error.js';
+/** The caller holds the Workspace lock. Only an absent, never-published checkout may be cloned. */
+export async function prepareWorkspaceCheckout(state, binding, input, leaseFence) {
+    const preparation = workspacePreparationSchema.safeParse(input);
+    if (!preparation.success)
+        throw new WorkspaceContextError('invalid_workspace_preparation');
+    const source = parseCloneSource(binding.repositoryUrl);
+    const parent = await realpath(state.config.workspaceRoot);
+    const target = join(parent, binding.workspaceId);
+    const receiptDir = join(state.config.stateDir, 'workspace-preparations');
+    await mkdir(receiptDir, { recursive: true, mode: 0o700 });
+    const receiptPath = join(receiptDir, `${binding.workspaceId}.json`);
+    const previous = await readReceipt(receiptPath, binding);
+    if (previous?.status === 'published')
+        throw new WorkspaceContextError('workspace_recovery_required');
+    if (await exists(target))
+        throw new WorkspaceContextError('workspace_checkout_conflict');
+    const receipt = previous ?? {
+        binding,
+        stagingName: `.prepare-${binding.workspaceId}-${randomUUID()}`,
+        status: 'cloning',
+    };
+    const staging = join(parent, receipt.stagingName);
+    const assertCurrent = () => {
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+    };
+    assertCurrent();
+    if (receipt.status === 'cloning') {
+        // Persist ownership before creating/removing a staging directory, so a crash can be retried.
+        await writeReceipt(receiptPath, receipt);
+        await rm(staging, { recursive: true, force: true });
+        await mkdir(staging, { mode: 0o700 });
+        const access = preparation.data.gitAccess;
+        const now = Date.now();
+        if (access &&
+            (Date.parse(access.issuedAt) > now || Date.parse(access.expiresAt) <= now + 10_000))
+            throw new WorkspaceContextError('workspace_git_access_expired');
+        let gateway;
+        try {
+            gateway = access
+                ? await mountGateway(state, binding.repositoryUrl, access, preparation.data.transport)
+                : undefined;
+        }
+        catch (error) {
+            await rm(staging, { recursive: true, force: true });
+            throw error;
+        }
+        const deadline = Math.min(now + 90_000, access ? Date.parse(access.expiresAt) : Infinity);
+        const env = {
+            PATH: process.env.PATH,
+            HOME: state.config.stateDir,
+            GIT_CONFIG_NOSYSTEM: '1',
+            GIT_CONFIG_GLOBAL: '/dev/null',
+            GIT_TERMINAL_PROMPT: '0',
+            GIT_ALLOW_PROTOCOL: 'http:https',
+        };
+        const cloneConfig = [];
+        if (gateway) {
+            // Rewrite only inside this process. The password is read from the mounted directory for the proxy URL.
+            env.GIT_CONFIG_COUNT = '1';
+            env.GIT_CONFIG_KEY_0 = `url.${gateway.cloneUrl}.insteadOf`;
+            env.GIT_CONFIG_VALUE_0 = binding.repositoryUrl;
+            env.PLAYCRAFT_GIT_HELPER = Buffer.from(GIT_GATEWAY_CREDENTIAL_HELPER).toString('base64');
+            env.PLAYCRAFT_GIT_CREDENTIAL_DIRECTORY = gateway.directory;
+            env.PLAYCRAFT_GIT_GATEWAY_CLONE_URL = gateway.cloneUrl;
+            env.PLAYCRAFT_GIT_CANONICAL_URL = binding.repositoryUrl;
+            cloneConfig.push(`credential.helper=!${shellQuote(process.execPath)} -e ${shellQuote('eval(Buffer.from(process.env.PLAYCRAFT_GIT_HELPER,"base64").toString())')}`, 'credential.useHttpPath=true');
+        }
+        else if (access) {
+            // Authentication exists only in the clone process environment; never in arguments or .git/config.
+            env.GIT_CONFIG_COUNT = '1';
+            env.GIT_CONFIG_KEY_0 = `http.${source.href}.extraHeader`;
+            env.GIT_CONFIG_VALUE_0 = `Authorization: Basic ${Buffer.from(`${access.username}:${access.password}`).toString('base64')}`;
+        }
+        try {
+            await runGit(['check-ref-format', '--branch', binding.branchName], env, deadline);
+            await runGit([
+                'clone',
+                '--no-checkout',
+                '--single-branch',
+                '--branch',
+                binding.branchName,
+                '--',
+                binding.repositoryUrl,
+                staging,
+            ], env, deadline, cloneConfig);
+            // Checkout never receives the temporary credential and never invokes repository hooks or global filters.
+            clearCloneSecrets(env);
+            await runGit(['-C', staging, 'checkout', '--force', binding.branchName], env, deadline);
+            assertCurrent();
+            receipt.status = 'ready';
+            await writeReceipt(receiptPath, receipt);
+        }
+        catch (error) {
+            await rm(staging, { recursive: true, force: true });
+            if (error instanceof WorkspaceContextError)
+                throw error;
+            throw new WorkspaceContextError('workspace_clone_failed');
+        }
+    }
+    const stat = await lstat(staging).catch(() => undefined);
+    if (!stat?.isDirectory() || stat.isSymbolicLink())
+        throw new WorkspaceContextError('workspace_recovery_required');
+    assertCurrent();
+    if (await exists(target))
+        throw new WorkspaceContextError('workspace_checkout_conflict');
+    await rename(staging, target);
+    receipt.status = 'published';
+    await writeReceipt(receiptPath, receipt);
+}
+function clearCloneSecrets(env) {
+    for (const key of [
+        'GIT_CONFIG_COUNT',
+        'GIT_CONFIG_KEY_0',
+        'GIT_CONFIG_VALUE_0',
+        'GIT_CONFIG_KEY_1',
+        'GIT_CONFIG_VALUE_1',
+        'PLAYCRAFT_GIT_HELPER',
+        'PLAYCRAFT_GIT_CREDENTIAL_DIRECTORY',
+        'PLAYCRAFT_GIT_GATEWAY_CLONE_URL',
+        'PLAYCRAFT_GIT_CANONICAL_URL',
+    ]) {
+        delete env[key];
+    }
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** Read-only open of the publisher's control directory. Credentials are not copied into the checkout. */
+async function mountGateway(state, repositoryUrl, access, transport) {
+    if (!transport)
+        return undefined;
+    const directory = state.config.gitCredentialDirectory;
+    const matched = matchWorkspaceGitGatewayCloneUrl(transport.cloneUrl, state.config.gitGatewayOrigins, repositoryUrl);
+    if (!matched.ok || !directory)
+        throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+    const parsed = workspaceGitTransportSchema.parse(transport);
+    if (parsed.cloneUrl !== transport.cloneUrl) {
+        throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+    }
+    const entry = await readMountedEntry(directory, transport.cloneUrl, matched.requestId, repositoryUrl);
+    if (entry.username !== access.username ||
+        entry.issuedAt !== access.issuedAt ||
+        entry.expiresAt !== access.expiresAt ||
+        !sameSecret(entry.password, access.password)) {
+        throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+    }
+    return { directory, cloneUrl: transport.cloneUrl };
+}
+async function readMountedEntry(directory, cloneUrl, requestId, repositoryUrl) {
+    if (!isAbsolute(directory) || (await realpath(directory)) !== resolve(directory)) {
+        throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+    }
+    const directoryStat = await lstat(directory);
+    if (!directoryStat.isDirectory() ||
+        directoryStat.isSymbolicLink() ||
+        (directoryStat.mode & 0o077) !== 0 ||
+        (typeof process.getuid === 'function' && directoryStat.uid !== process.getuid())) {
+        throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+    }
+    const directoryHandle = await open(directory, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_DIRECTORY);
+    await directoryHandle.close();
+    const file = await open(join(directory, 'workspace-git-credentials.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.size > 1024 * 1024) {
+            throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+        }
+        const document = JSON.parse(await file.readFile('utf8'));
+        if (blocked(document).has(requestId)) {
+            throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+        }
+        const entries = (document.entries ?? []).filter((entry) => entry.transport &&
+            typeof entry.transport === 'object' &&
+            entry.transport.cloneUrl === cloneUrl);
+        if (entries.length !== 1)
+            throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+        const entry = entries[0];
+        if (entry.repositoryUrl !== repositoryUrl ||
+            requestIdOf(entry.command) !== requestId ||
+            requestIdOf(entry.receipt) !== requestId) {
+            throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+        }
+        return workspaceGitAccessSchema.parse(entry.gitAccess);
+    }
+    finally {
+        await file.close();
+    }
+}
+function requestIdOf(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const id = value.requestId;
+    return typeof id === 'string' ? id : undefined;
+}
+function blocked(document) {
+    const ids = new Set();
+    for (const list of [document.retired, document.revocations]) {
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list))
+            throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+        for (const item of list) {
+            const id = requestIdOf(item);
+            if (id)
+                ids.add(id);
+        }
+    }
+    return ids;
+}
+function sameSecret(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+const GIT_GATEWAY_CREDENTIAL_HELPER = `
+const fs = require('node:fs');
+const path = require('node:path');
+const action = process.argv[1];
+if (action !== 'get') process.exit(0);
+const chunks = [];
+process.stdin.on('data', (chunk) => chunks.push(chunk));
+process.stdin.on('end', () => {
+  try {
+    const fields = {};
+    for (const line of Buffer.concat(chunks).toString('utf8').split('\\n')) {
+      if (!line) continue;
+      const index = line.indexOf('=');
+      if (index > 0) fields[line.slice(0, index)] = line.slice(index + 1);
+    }
+    const cloneUrl = new URL(process.env.PLAYCRAFT_GIT_GATEWAY_CLONE_URL);
+    const canonical = new URL(process.env.PLAYCRAFT_GIT_CANONICAL_URL);
+    if (!fields.path || !fields.protocol || !fields.host) process.exit(1);
+    const requested = new URL(fields.protocol + '://' + fields.host + '/' + String(fields.path).replace(/^\\/+/, ''));
+    if (requested.origin !== cloneUrl.origin || requested.pathname !== cloneUrl.pathname || requested.origin === canonical.origin) process.exit(1);
+    const requestId = cloneUrl.pathname.split('/').pop();
+    const directory = process.env.PLAYCRAFT_GIT_CREDENTIAL_DIRECTORY;
+    const flags = fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW;
+    const dir = fs.openSync(directory, flags | (fs.constants.O_DIRECTORY || 0));
+    try {
+      if (!fs.fstatSync(dir).isDirectory()) process.exit(1);
+    } finally { fs.closeSync(dir); }
+    const file = fs.openSync(path.join(directory, 'workspace-git-credentials.json'), flags);
+    try {
+      const stat = fs.fstatSync(file);
+      if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.size > 1024 * 1024) process.exit(1);
+      const document = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const blocked = [...(document.retired || []), ...(document.revocations || [])];
+      if (blocked.some((item) => item && item.requestId === requestId)) process.exit(1);
+      const entries = (document.entries || []).filter((entry) => entry && entry.transport && entry.transport.cloneUrl === process.env.PLAYCRAFT_GIT_GATEWAY_CLONE_URL && entry.repositoryUrl === process.env.PLAYCRAFT_GIT_CANONICAL_URL);
+      if (entries.length !== 1) process.exit(1);
+      const access = entries[0].gitAccess || {};
+      if (Date.parse(access.issuedAt) > Date.now() || Date.parse(access.expiresAt) <= Date.now() + 10000) process.exit(1);
+      if (!access.username || !access.password || /[\\r\\n\\0]/.test(access.username) || /[\\r\\n\\0]/.test(access.password)) process.exit(1);
+      process.stdout.write('username=' + access.username + '\\npassword=' + access.password + '\\n');
+      process.exit(0);
+    } finally { fs.closeSync(file); }
+  } catch { process.exit(1); }
+});
+`;
+function parseCloneSource(value) {
+    try {
+        const source = new URL(value);
+        if ((source.protocol !== 'https:' &&
+            !(source.protocol === 'http:' &&
+                ['127.0.0.1', '[::1]', 'localhost'].includes(source.hostname))) ||
+            source.username ||
+            source.password ||
+            source.search ||
+            source.hash)
+            throw new Error();
+        return source;
+    }
+    catch {
+        throw new WorkspaceContextError('workspace_clone_transport_unavailable');
+    }
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function readReceipt(path, binding) {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        const parsed = workspaceRegistrationSchema.parse(value.binding);
+        if (JSON.stringify(parsed) !== JSON.stringify(binding) ||
+            !['cloning', 'ready', 'published'].includes(value.status) ||
+            !new RegExp(`^\\.prepare-${binding.workspaceId}-[0-9a-f-]{36}$`).test(value.stagingName))
+            throw new Error();
+        return { binding: parsed, stagingName: value.stagingName, status: value.status };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new WorkspaceContextError('workspace_preparation_receipt_invalid');
+    }
+}
+async function writeReceipt(path, value) {
+    const temp = `${path}.tmp`;
+    await writeFile(temp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+    await rename(temp, path);
+}
+function runGit(args, env, deadline, config = []) {
+    return new Promise((resolve, reject) => {
+        let timedOut = false;
+        const child = spawn('git', [
+            '-c',
+            'core.hooksPath=/dev/null',
+            '-c',
+            'credential.helper=',
+            ...config.flatMap((item) => ['-c', item]),
+            '-c',
+            'http.followRedirects=false',
+            '-c',
+            'init.templateDir=',
+            ...args,
+        ], {
+            env,
+            detached: process.platform !== 'win32',
+            stdio: 'ignore',
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                if (process.platform !== 'win32' && child.pid)
+                    process.kill(-child.pid, 'SIGKILL');
+                else
+                    child.kill('SIGKILL');
+            }
+            catch {
+                /* The process may have already exited. */
+            }
+        }, Math.max(1, deadline - Date.now()));
+        child.once('error', () => {
+            clearTimeout(timer);
+            reject(new WorkspaceContextError('workspace_clone_failed'));
+        });
+        child.once('exit', (code) => {
+            clearTimeout(timer);
+            if (timedOut)
+                reject(new WorkspaceContextError('workspace_clone_timeout'));
+            else if (code === 0)
+                resolve();
+            else
+                reject(new WorkspaceContextError('workspace_clone_failed'));
+        });
+    });
+}

package/dist/workspace-runtime/workspaces/registry.js

@@ -0,0 +1,107 @@
+import { execFile } from 'node:child_process';
+import { lstat, realpath } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { promisify } from 'node:util';
+import { workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { prepareWorkspaceCheckout } from './prepare.js';
+import { WorkspaceContextError } from './context-error.js';
+export { WorkspaceContextError } from './context-error.js';
+const exec = promisify(execFile);
+export function revisionScope(state, workspaceId) {
+    return state.config.workspaceMode === 'multi' ? workspaceId : undefined;
+}
+export function workspaceSessions(state, workspaceId) {
+    return state.journal
+        .listSessions()
+        .filter((item) => state.config.workspaceMode !== 'multi' || item.workspaceId === workspaceId);
+}
+export async function workspaceRoot(state, workspaceId) {
+    if (state.config.workspaceMode !== 'multi')
+        return state.config.workspaceRoot;
+    if (!workspaceId || !state.journal.getWorkspace(workspaceId))
+        throw new WorkspaceContextError('workspace_not_registered');
+    return checkedDirectory(state, workspaceId);
+}
+async function checkedDirectory(state, workspaceId) {
+    if (!/^[0-9a-f-]{36}$/i.test(workspaceId))
+        throw new WorkspaceContextError('invalid_workspace');
+    const parent = await realpath(state.config.workspaceRoot);
+    const target = join(parent, workspaceId);
+    try {
+        const stat = await lstat(target);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            relative(parent, await realpath(target)) !== workspaceId) {
+            throw new WorkspaceContextError('invalid_workspace_directory');
+        }
+        const stateDir = await realpath(state.config.stateDir);
+        if (stateDir === target || stateDir.startsWith(`${target}/`))
+            throw new WorkspaceContextError('invalid_workspace_directory');
+        return target;
+    }
+    catch (error) {
+        if (error instanceof WorkspaceContextError)
+            throw error;
+        throw new WorkspaceContextError('workspace_not_prepared');
+    }
+}
+/** Registers a fixed checkout; optional first creation is restricted to its trusted binding. */
+export async function registerWorkspace(state, input, leaseFence, preparation) {
+    if (state.config.workspaceMode !== 'multi')
+        throw new WorkspaceContextError('multi_workspace_unavailable');
+    const parsed = workspaceRegistrationSchema.safeParse(input);
+    if (!parsed.success)
+        throw new WorkspaceContextError('invalid_workspace_registration');
+    const binding = parsed.data;
+    return state.journal.exclusive(`workspace:${binding.workspaceId}`, async () => {
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+        state.acceptedLeaseFence = leaseFence;
+        await state.journal.setAcceptedLeaseFence(leaseFence);
+        const existing = state.journal.getWorkspace(binding.workspaceId);
+        if (existing && JSON.stringify(existing) !== JSON.stringify(binding))
+            throw new WorkspaceContextError('workspace_binding_conflict');
+        let root;
+        try {
+            root = await checkedDirectory(state, binding.workspaceId);
+        }
+        catch (error) {
+            if (existing && error instanceof WorkspaceContextError && error.message === 'workspace_not_prepared')
+                throw new WorkspaceContextError('workspace_recovery_required');
+            if (!preparation || !(error instanceof WorkspaceContextError) || error.message !== 'workspace_not_prepared')
+                throw error;
+            await prepareWorkspaceCheckout(state, binding, preparation, leaseFence);
+            root = await checkedDirectory(state, binding.workspaceId);
+        }
+        const git = async (...args) => (await exec('git', ['-C', root, ...args], {
+            timeout: 5000,
+            maxBuffer: 64 * 1024,
+            env: {
+                PATH: process.env.PATH,
+                HOME: process.env.HOME,
+                GIT_CONFIG_NOSYSTEM: '1',
+                GIT_CONFIG_GLOBAL: '/dev/null',
+            },
+        })).stdout.trim();
+        try {
+            if ((await realpath(await git('rev-parse', '--show-toplevel'))) !== root ||
+                (await git('remote', 'get-url', 'origin')) !== binding.repositoryUrl ||
+                (await git('symbolic-ref', '--short', 'HEAD')) !== binding.branchName) {
+                throw new WorkspaceContextError('workspace_checkout_mismatch');
+            }
+        }
+        catch (error) {
+            if (error instanceof WorkspaceContextError)
+                throw error;
+            throw new WorkspaceContextError('workspace_not_prepared');
+        }
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+        await state.journal.putWorkspace(binding);
+        return binding;
+    });
+}

package/dist/workspace-runtime/workspaces/revisions.js

@@ -0,0 +1,31 @@
+import { readWorkspaceFile } from './files.js';
+import { revisionScope, workspaceRoot } from './registry.js';
+/** Observe native/manual edits before checking an editor's conditional write. */
+export async function withObservedFile(state, workspaceId, path, action) {
+    const scope = revisionScope(state, workspaceId);
+    return state.journal.exclusive(`file:${scope ?? 'single'}:${path}`, async () => {
+        const records = state.journal.fileRevisions(scope);
+        const previous = records[path];
+        let file;
+        try {
+            file = await readWorkspaceFile(await workspaceRoot(state, workspaceId), path, records);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const hash = file?.contentHash ?? '';
+        const revision = previous ? previous.revision + (previous.contentHash === hash ? 0 : 1) : 0;
+        if ((!previous && file) || (previous && previous.contentHash !== hash)) {
+            await state.journal.putFileRevision(path, { revision, contentHash: hash }, scope);
+        }
+        return action({ file: file ? { ...file, revision } : undefined, revision });
+    });
+}
+export async function readObservedFile(state, workspaceId, path) {
+    return withObservedFile(state, workspaceId, path, async ({ file }) => {
+        if (!file)
+            throw Object.assign(new Error('file_not_found'), { code: 'ENOENT' });
+        return file;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "private": false,
   "type": "module",
   "engines": {
@@ -14,6 +14,7 @@
     "dist",
     "templates",
     "project-template",
+    "project-template-v2",
     "engine-packs",
     "project-templates",
     "REMIX.md",
@@ -35,6 +36,8 @@
     "test:agent:gate": "node scripts/run-agent-tests.mjs gate",
     "test:agent:vlm": "node scripts/run-agent-tests.mjs vlm",
     "test:agent:stop": "node scripts/run-agent-tests.mjs stop",
+    "generate:platform-skills": "node scripts/generate-platform-skills.mjs",
+    "verify:platform-skills": "node scripts/generate-platform-skills.mjs --check",
     "verify:agent-stop": "node scripts/verify-agent-stop.mjs",
     "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
     "link": "node scripts/bump-local.js && pnpm build && npm link",

package/project-template-v2/.claude/agents/artist.md

@@ -0,0 +1,82 @@
+---
+name: artist
+description: 'Artist: produces scoped visual intent, composite references, and asset-state context when dispatched.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'Skill'
+  - 'Bash'
+---
+
+# Artist — Role Contract
+
+## Role Essence
+
+You produce scoped visual direction and visual handoff context.
+
+Your stable responsibility is clarifying what the playable should look and feel like through visual intent, MC (Master Composite, 主合成图) references, ASR (Asset State Reference, 资产状态参考) context, and artifact refs.
+
+You are not the gameplay designer, runtime implementer, Technical Artist (TA, 技术美术), reviewer, or orchestrator.
+
+## Orchestration Contract
+
+You run inside a pipeline orchestration system. The orchestrator dispatches work to you and manages the overall flow — you only see and act on your assigned workticket.
+
+**On start** — read your workticket:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+Key fields:
+
+- `role` — must be `artist` for you to act; if it is empty or another role, stop and report no assigned workticket
+- `goal` / `guidance` — what you are here to do and how
+- `allowedFiles` — the only paths you may write (hard boundary)
+- `forbiddenTasks` — things explicitly out of scope for this run
+- `acceptance` — the conditions that define done; stop when these are met, no more
+- `activeTodoId` — the todo or stage task assigned to you this run
+
+**Before STOP** — record what you did:
+
+```bash
+npm run handoff:append -- role=artist summary="<what you did in one sentence>" artifactRefs="<produced files>"
+```
+
+If the work failed or is blocked, include the blocker in `summary` and pass `blockers="<reason>"`.
+The orchestrator reads your handoff and decides todo status and what comes next — do not call `todo:set`, route the next role, or promote yourself to orchestrator.
+
+Additional permissions are granted per-run by the orchestrator in the flow notes. Do not use them unless explicitly listed there.
+
+## Inputs
+
+- `docs/design-brief.md` or `docs/style-exploration.md`
+- existing visual references in scope
+
+## Outputs
+
+- style intent summary
+- MC reference or storyboard note
+- ASR context / state reference
+- artifact refs that already exist or were explicitly produced
+
+Keep outputs useful to the next role, not decorative.
+
+## Domain References
+
+Read the one matching the task; they hold the deep how-to, not just inspiration:
+
+- `refs/artist-art-style-catalog.md` — per-style visual definitions; pick and ground a style direction.
+- `refs/artist-master-composite-recipes.md` — MC prompt recipes and approved models per game type.
+- `refs/artist-color-audio-recipes.md` — color schemes and audio mood arcs by genre.
+- `refs/artist-dimension-axis.md` — what MC/ASR to deliver per dimension (flat 2D vs 3D).
+
+## Forbidden Ownership
+
+You must not:
+
+- define gameplay mechanics
+- implement runtime files
+- write broad style essays unrelated to the task