paris-immersion 0.1.0

package/dist/commands/tasks.js

@@ -0,0 +1,32 @@
+import { apiAuthFetch } from '../lib/api.js';
+import { c } from '../lib/colors.js';
+const STATUS_GLYPH = {
+    completed: c.green('✓'),
+    in_progress: c.yellow('◐'),
+    available: c.dim('○'),
+    locked: c.dim('🔒'),
+    skipped: c.dim('—'),
+};
+export async function tasksCommand() {
+    const today = await apiAuthFetch('/immersion-app/v1/today');
+    console.log();
+    console.log(c.bold(`${today.immersion.name} · dia ${today.day_number} · fase ${today.phase}`));
+    console.log();
+    if (today.schedule.length > 0) {
+        console.log(c.bold('Cronograma do dia:'));
+        for (const s of today.schedule) {
+            console.log(`  ${c.cyan(s.starts_at + '–' + s.ends_at)}  ${s.title}`);
+        }
+        console.log();
+    }
+    if (today.missions.length === 0) {
+        console.log(c.dim('Nenhuma tarefa pra essa fase.'));
+        return;
+    }
+    console.log(c.bold('Tarefas:'));
+    for (const m of today.missions) {
+        const glyph = STATUS_GLYPH[m.status] ?? c.dim('?');
+        console.log(`  ${glyph} ${m.title} ${c.dim('(' + m.deliverable_type + ')')}`);
+        console.log(`     ${c.dim(m.id)}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { loginCommand } from './commands/login.js';
+import { installCommand } from './commands/install.js';
+import { doctorCommand } from './commands/doctor.js';
+import { tasksCommand } from './commands/tasks.js';
+import { statusCommand } from './commands/status.js';
+import { reopenCommand } from './commands/reopen.js';
+import { graduateCommand } from './commands/graduate.js';
+import { logoutCommand } from './commands/logout.js';
+import { serveCommand } from './commands/serve.js';
+const program = new Command()
+    .name('paris')
+    .description('Paris Immersion — CLI do aluno (login, workspace, tarefas)')
+    .version('0.1.0');
+program
+    .command('login')
+    .description('Autenticar com sua conta Paris (device-code OR --token direto)')
+    .option('--api-url <url>', 'API URL override')
+    .option('--token <jwt>', 'Skip device-code: usa JWT direto (do wizard fase 3)')
+    .action(loginCommand);
+program
+    .command('install')
+    .description('Instala o workspace da imersão na pasta atual (ou em pasta nova)')
+    .option('-d, --dir <path>', 'pasta destino (padrão: cria uma nova com o slug da imersão)')
+    .option('--immersion <slug>', 'imersão específica (caso o aluno esteja em mais de uma)')
+    .action(installCommand);
+program
+    .command('doctor')
+    .description('Diagnostica credentials, marker, hooks, conectividade')
+    .option('--report', 'Envia o resultado para /api/onboarding/v2/install-status (usado pelo wizard de onboarding)')
+    .action(doctorCommand);
+program
+    .command('tasks')
+    .description('Lista as tarefas do dia (CLI-only, não abre Claude)')
+    .action(tasksCommand);
+program
+    .command('status')
+    .description('Resumo da fase atual + tarefa em foco')
+    .action(statusCommand);
+program
+    .command('reopen <mission-id>')
+    .description('Reabre uma tarefa marcada como concluída')
+    .option('--reason <text>', 'razão (visível ao instrutor)', 'student reopen')
+    .action(reopenCommand);
+program
+    .command('graduate')
+    .description('Marcar a imersão como concluída do seu lado (override)')
+    .action(graduateCommand);
+program
+    .command('logout')
+    .description('Apagar credenciais locais + revogar no servidor')
+    .action(logoutCommand);
+program
+    .command('serve')
+    .description('Sobe WS local (ws://localhost:31000) para o terminal embarcado do onboarding')
+    .option('--port <port>', 'Porta do WebSocket', '31000')
+    .action(serveCommand);
+program.parseAsync().catch((err) => {
+    console.error('\n[paris] erro:', err?.message ?? err);
+    process.exit(1);
+});

package/dist/lib/api.d.ts

@@ -0,0 +1,16 @@
+export declare class ApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export type ApiOptions = {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    token?: string;
+    apiUrl?: string;
+    signal?: AbortSignal;
+};
+export declare function apiFetch<T = unknown>(pathname: string, opts?: ApiOptions): Promise<T>;
+/** Fetch using whatever token is on disk. Throws if not logged in. */
+export declare function apiAuthFetch<T = unknown>(pathname: string, opts?: Omit<ApiOptions, 'token'>): Promise<T>;
+export declare function defaultApiUrl(): string;

package/dist/lib/api.js

@@ -0,0 +1,45 @@
+import { readCredentials } from './credentials.js';
+const DEFAULT_API_URL = process.env.PARIS_API_URL ?? 'http://localhost:3011';
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+export async function apiFetch(pathname, opts = {}) {
+    const apiUrl = opts.apiUrl ?? DEFAULT_API_URL;
+    const headers = { accept: 'application/json' };
+    if (opts.body != null)
+        headers['content-type'] = 'application/json';
+    if (opts.token)
+        headers['authorization'] = `Bearer ${opts.token}`;
+    const res = await fetch(new URL(pathname, apiUrl), {
+        method: opts.method ?? (opts.body ? 'POST' : 'GET'),
+        headers,
+        body: opts.body != null ? JSON.stringify(opts.body) : undefined,
+        signal: opts.signal,
+    });
+    const contentType = res.headers.get('content-type') ?? '';
+    const payload = contentType.includes('application/json')
+        ? await res.json().catch(() => null)
+        : await res.text().catch(() => null);
+    if (!res.ok) {
+        const msg = (payload && typeof payload === 'object' && 'error' in payload && payload.error) || res.statusText;
+        throw new ApiError(String(msg), res.status, payload);
+    }
+    return payload;
+}
+/** Fetch using whatever token is on disk. Throws if not logged in. */
+export async function apiAuthFetch(pathname, opts = {}) {
+    const creds = await readCredentials();
+    if (!creds) {
+        throw new ApiError('Not logged in — run `paris login` first.', 401, null);
+    }
+    return apiFetch(pathname, { ...opts, token: creds.token, apiUrl: opts.apiUrl ?? creds.api_url });
+}
+export function defaultApiUrl() {
+    return DEFAULT_API_URL;
+}

package/dist/lib/colors.d.ts

@@ -0,0 +1,10 @@
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    magenta: (s: string) => string;
+    cyan: (s: string) => string;
+};

package/dist/lib/colors.js

@@ -0,0 +1,18 @@
+// Minimal ANSI helpers — avoids pulling in `kleur`/`chalk` deps. If stdout
+// isn't a TTY we strip the codes so logs piped to files stay clean.
+const isTTY = process.stdout.isTTY === true;
+function wrap(open, close, text) {
+    if (!isTTY)
+        return text;
+    return `\x1b[${open}m${text}\x1b[${close}m`;
+}
+export const c = {
+    bold: (s) => wrap('1', '22', s),
+    dim: (s) => wrap('2', '22', s),
+    red: (s) => wrap('31', '39', s),
+    green: (s) => wrap('32', '39', s),
+    yellow: (s) => wrap('33', '39', s),
+    blue: (s) => wrap('34', '39', s),
+    magenta: (s) => wrap('35', '39', s),
+    cyan: (s) => wrap('36', '39', s),
+};

package/dist/lib/credentials.d.ts

@@ -0,0 +1,16 @@
+export type Credentials = {
+    token: string;
+    user_id: string;
+    email: string;
+    api_url: string;
+    obtained_at: string;
+};
+/**
+ * Read the on-disk credentials file. Returns null if missing. We deliberately
+ * do NOT throw on file-not-found because most CLI commands need to detect
+ * "not logged in" and show a friendly message instead of a stack trace.
+ */
+export declare function readCredentials(): Promise<Credentials | null>;
+export declare function writeCredentials(creds: Credentials): Promise<void>;
+export declare function deleteCredentials(): Promise<boolean>;
+export declare function credentialsPath(): string;

package/dist/lib/credentials.js

@@ -0,0 +1,45 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+// PARIS_CREDENTIALS_FILE lets tests / dev override the on-disk credentials
+// location without faking $HOME (which breaks every other tool's auth).
+const CREDENTIALS_FILE = process.env.PARIS_CREDENTIALS_FILE ?? path.join(homedir(), '.paris', 'credentials');
+const CREDENTIALS_DIR = path.dirname(CREDENTIALS_FILE);
+/**
+ * Read the on-disk credentials file. Returns null if missing. We deliberately
+ * do NOT throw on file-not-found because most CLI commands need to detect
+ * "not logged in" and show a friendly message instead of a stack trace.
+ */
+export async function readCredentials() {
+    try {
+        const raw = await fs.readFile(CREDENTIALS_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function writeCredentials(creds) {
+    await fs.mkdir(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+    // Write to a temp + rename so a concurrent read can't see a half-written file,
+    // and force 0600 perms (only owner can read the token).
+    const tmp = CREDENTIALS_FILE + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    await fs.rename(tmp, CREDENTIALS_FILE);
+}
+export async function deleteCredentials() {
+    try {
+        await fs.unlink(CREDENTIALS_FILE);
+        return true;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+export function credentialsPath() {
+    return CREDENTIALS_FILE;
+}

package/dist/lib/marker.d.ts

@@ -0,0 +1,17 @@
+export type WorkspaceMarker = {
+    immersion_id: string;
+    immersion_slug: string;
+    participant_id: string;
+    student_user_id: string;
+    created_at: string;
+    api_url: string;
+    /** Local override — server is the source of truth, but if this is set the
+     *  hooks treat the workspace as graduated regardless of server response. */
+    status?: 'active' | 'graduated';
+};
+/** Walk up from `start` looking for `.paris/workspace.json`. */
+export declare function findMarker(start?: string): Promise<{
+    dir: string;
+    marker: WorkspaceMarker;
+} | null>;
+export declare function writeMarker(workspaceDir: string, marker: WorkspaceMarker): Promise<void>;

package/dist/lib/marker.js

@@ -0,0 +1,27 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const MARKER_REL_PATH = '.paris/workspace.json';
+/** Walk up from `start` looking for `.paris/workspace.json`. */
+export async function findMarker(start = process.cwd()) {
+    let dir = path.resolve(start);
+    while (true) {
+        const candidate = path.join(dir, MARKER_REL_PATH);
+        try {
+            const raw = await fs.readFile(candidate, 'utf-8');
+            const marker = JSON.parse(raw);
+            return { dir, marker };
+        }
+        catch {
+            // fall through to parent
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export async function writeMarker(workspaceDir, marker) {
+    const parisDir = path.join(workspaceDir, '.paris');
+    await fs.mkdir(parisDir, { recursive: true });
+    await fs.writeFile(path.join(parisDir, 'workspace.json'), JSON.stringify(marker, null, 2));
+}

package/dist/templates/claude-md.d.ts

@@ -0,0 +1,5 @@
+export declare function renderClaudeMd(opts: {
+    immersionName: string;
+    immersionSlug: string;
+    participantEmail: string;
+}): string;

package/dist/templates/claude-md.js

@@ -0,0 +1,47 @@
+export function renderClaudeMd(opts) {
+    return `# ${opts.immersionName} — workspace do aluno
+
+> Você (Claude) é o **coach técnico** desse aluno durante a Imersão Paris.
+> A pasta atual foi criada por \`paris install\` e é o canvas onde a jornada acontece.
+
+## Identidade
+
+- **Imersão:** ${opts.immersionName} (\`${opts.immersionSlug}\`)
+- **Aluno:** ${opts.participantEmail}
+- **Modo:** \`active\` enquanto a imersão estiver rodando; \`graduated\` (silencioso) após.
+
+## Suas regras
+
+1. **Coach, não tribunal.** Antes de marcar uma tarefa como concluída, você DEVE:
+   - Rodar os testes/validações pertinentes ao \`deliverable_type\` da tarefa.
+   - Pedir evidência objetiva ao aluno (link, arquivo, número, screenshot).
+   - Checar o \`socio_prompt\` da tarefa pra garantir que o aluno respondeu o que a imersão pediu.
+   - Apresentar um mini-checklist do que falta ANTES de aceitar um "acabei".
+2. **Respeite a decisão final do aluno.** Se ele disser "acabei" depois do checklist, marque (via MCP \`mark_task_complete\`). Você não é juiz.
+3. **Transparência total.** Tudo aqui é gravado em audit_logs e o instrutor pode reabrir qualquer tarefa.
+4. **Nunca invente progresso.** Só marque o que de fato foi feito nessa sessão.
+5. **Inicie a sessão falando primeiro.** O hook SessionStart te entrega o cronograma + a tarefa atual antes do aluno digitar — abra o dia com um resumo claro (fase, tarefa, primeiro passo sugerido).
+
+## MCP tools que você tem
+
+Carregadas via servidor MCP local \`.paris/mcp/index.mjs\` (configurado em \`.claude/settings.json\`):
+
+| Tool | Quando usar |
+|------|-------------|
+| \`get_today\` | Sessão começou OU o aluno perguntou o que tem hoje |
+| \`get_current_task\` | Aluno mudou de assunto OU você quer reorientar |
+| \`mark_task_complete\` | Aluno disse "acabei" + checklist OK |
+| \`reopen_task\` | Aluno (ou instrutor via comentário) pediu pra reabrir |
+| \`comment_on_task\` | Aluno quer registrar nota visível ao instrutor |
+| \`log_event\` | Telemetria leve (\`blocked\`, \`milestone\`, etc.) |
+| \`get_immersion_context\` | Refresh do contexto inteiro |
+
+## Skill associada
+
+A skill \`paris-coach\` (\`.claude/skills/paris-coach/SKILL.md\`) aprofunda as regras de checklist por tipo de deliverable (\`text\`, \`artifact\`, \`checklist\`, \`pitch\`). Ative quando entrar numa tarefa.
+
+---
+
+Pós-imersão (status \`graduated\`): essas regras param de valer. A pasta é sua, faça o que quiser com ela.
+`;
+}

package/dist/templates/hook.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The hook script that Claude Code invokes on SessionStart / UserPromptSubmit /
+ * Stop. We ship it as a string so `paris install` can write it verbatim into
+ * the workspace without needing the @paris/cli package to be installed in the
+ * student's node_modules.
+ *
+ * The script is pure stdlib: walks up to find the marker, reads credentials,
+ * calls the API, prints a system-reminder to stdout (which Claude Code feeds
+ * back to the model). Failures degrade gracefully — they print to stderr so
+ * the student can still get useful debug info, but never block the session.
+ */
+export declare function renderHookScript(): string;

package/dist/templates/hook.js

@@ -0,0 +1,132 @@
+/**
+ * The hook script that Claude Code invokes on SessionStart / UserPromptSubmit /
+ * Stop. We ship it as a string so `paris install` can write it verbatim into
+ * the workspace without needing the @paris/cli package to be installed in the
+ * student's node_modules.
+ *
+ * The script is pure stdlib: walks up to find the marker, reads credentials,
+ * calls the API, prints a system-reminder to stdout (which Claude Code feeds
+ * back to the model). Failures degrade gracefully — they print to stderr so
+ * the student can still get useful debug info, but never block the session.
+ */
+export function renderHookScript() {
+    return `#!/usr/bin/env node
+// Auto-generated by \`paris install\`. Do not edit — regenerate via \`paris install\`.
+
+import { promises as fs } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+const PHASE = process.argv[2] // session-start | user-prompt-submit | stop
+
+async function loadCredentials() {
+  try {
+    const file = process.env.PARIS_CREDENTIALS_FILE || path.join(homedir(), '.paris', 'credentials')
+    const raw = await fs.readFile(file, 'utf-8')
+    return JSON.parse(raw)
+  } catch { return null }
+}
+
+async function loadMarker() {
+  let dir = process.cwd()
+  while (true) {
+    try {
+      const raw = await fs.readFile(path.join(dir, '.paris', 'workspace.json'), 'utf-8')
+      return { dir, marker: JSON.parse(raw) }
+    } catch {}
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+async function apiGet(apiUrl, pathname, token) {
+  const res = await fetch(new URL(pathname, apiUrl), {
+    headers: { authorization: 'Bearer ' + token, accept: 'application/json' },
+  })
+  if (!res.ok) return null
+  return res.json()
+}
+
+async function apiPost(apiUrl, pathname, token, body) {
+  const res = await fetch(new URL(pathname, apiUrl), {
+    method: 'POST',
+    headers: { authorization: 'Bearer ' + token, 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  if (!res.ok) return null
+  return res.json().catch(() => null)
+}
+
+async function main() {
+  const marker = await loadMarker()
+  if (!marker) return // not a paris workspace — silent no-op
+  if (marker.marker.status === 'graduated') return // graduated — silent
+
+  const creds = await loadCredentials()
+  if (!creds) {
+    process.stderr.write('[paris-hook] sem credenciais; rode \`paris login\` na sua shell.\\n')
+    return
+  }
+
+  const apiUrl = marker.marker.api_url || creds.api_url
+
+  if (PHASE === 'stop') {
+    await apiPost(apiUrl, '/immersion-app/v1/events', creds.token, { type: 'turn_ended' })
+    return
+  }
+
+  const [workspace, current] = await Promise.all([
+    apiGet(apiUrl, '/immersion-app/v1/workspace', creds.token),
+    apiGet(apiUrl, '/immersion-app/v1/missions/current', creds.token),
+  ])
+
+  if (!workspace) {
+    process.stderr.write('[paris-hook] não foi possível buscar contexto. Está offline?\\n')
+    return
+  }
+  if (workspace.status === 'graduated') return
+
+  const lines = []
+  if (PHASE === 'session-start') {
+    lines.push('# Paris Immersion — contexto da sessão')
+    lines.push('')
+    lines.push('Imersão: **' + workspace.immersion.name + '** (\\'' + workspace.immersion.slug + '\\')')
+    lines.push('Dia: **' + workspace.day_number + '** · fase: **' + workspace.phase + '**')
+    lines.push('')
+    lines.push('Você (Claude) é o coach técnico desse aluno. Siga as regras do CLAUDE.md e da skill paris-coach. **Comece falando primeiro** com um resumo do dia e a tarefa atual — o aluno NÃO digitou nada ainda.')
+    lines.push('')
+  } else {
+    lines.push('# Paris — refresh de contexto')
+    lines.push('')
+  }
+
+  if (current && current.current) {
+    lines.push('## Tarefa atual')
+    lines.push('- **id:** \\'' + current.current.id + '\\'')
+    lines.push('- **título:** ' + current.current.title)
+    lines.push('- **tipo:** ' + current.current.deliverable_type)
+    lines.push('- **status:** ' + current.current.status)
+    if (current.current.description) lines.push('- **descrição:** ' + current.current.description)
+    if (current.current.socio_prompt) {
+      lines.push('')
+      lines.push('### Sócio prompt')
+      lines.push(current.current.socio_prompt)
+    }
+  } else {
+    lines.push('## Sem tarefa em foco')
+    lines.push('Pergunte ao aluno em que ele quer trabalhar.')
+  }
+
+  process.stdout.write(lines.join('\\n') + '\\n')
+
+  if (PHASE === 'session-start') {
+    await apiPost(apiUrl, '/immersion-app/v1/events', creds.token, { type: 'session_started' })
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write('[paris-hook] erro: ' + (err && err.message || err) + '\\n')
+})
+`;
+}

package/dist/templates/settings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Renders the .claude/settings.json that `paris install` drops into the
+ * workspace. Both the hooks (.paris/hooks/paris-hook.mjs) and the MCP server
+ * (.paris/mcp/index.mjs) are vendored into the workspace by `paris install` —
+ * no npm/npx fetch happens at session start. The MCP bundle is self-contained
+ * (all deps inlined), so the only runtime requirement is `node`, which is
+ * already a prerequisite. Paths are relative to the workspace root, which is
+ * the cwd Claude Code uses when launching hooks and MCP servers.
+ */
+export declare function renderSettingsJson(opts: {
+    apiUrl: string;
+}): Record<string, unknown>;

package/dist/templates/settings.js

@@ -0,0 +1,58 @@
+/**
+ * Renders the .claude/settings.json that `paris install` drops into the
+ * workspace. Both the hooks (.paris/hooks/paris-hook.mjs) and the MCP server
+ * (.paris/mcp/index.mjs) are vendored into the workspace by `paris install` —
+ * no npm/npx fetch happens at session start. The MCP bundle is self-contained
+ * (all deps inlined), so the only runtime requirement is `node`, which is
+ * already a prerequisite. Paths are relative to the workspace root, which is
+ * the cwd Claude Code uses when launching hooks and MCP servers.
+ */
+export function renderSettingsJson(opts) {
+    return {
+        $schema: 'https://json.schemastore.org/claude-code-settings',
+        mcpServers: {
+            'paris-immersion': {
+                command: 'node',
+                args: ['.paris/mcp/index.mjs'],
+                env: {
+                    PARIS_API_URL: opts.apiUrl,
+                },
+            },
+        },
+        hooks: {
+            SessionStart: [
+                {
+                    matcher: '*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'node .paris/hooks/paris-hook.mjs session-start',
+                        },
+                    ],
+                },
+            ],
+            UserPromptSubmit: [
+                {
+                    matcher: '*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'node .paris/hooks/paris-hook.mjs user-prompt-submit',
+                        },
+                    ],
+                },
+            ],
+            Stop: [
+                {
+                    matcher: '*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'node .paris/hooks/paris-hook.mjs stop',
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}

package/dist/templates/skill.d.ts

@@ -0,0 +1 @@
+export declare function renderParisCoachSkill(): string;

package/dist/templates/skill.js

@@ -0,0 +1,61 @@
+export function renderParisCoachSkill() {
+    return `---
+name: paris-coach
+description: Ative quando entrar em uma tarefa da Imersão Paris. Aplica checklist específico por tipo de deliverable antes de marcar a tarefa como concluída.
+---
+
+# Paris Coach — checklist por deliverable
+
+Você é o coach técnico. Antes de chamar \`mark_task_complete\` via MCP, garanta o checklist correspondente ao \`deliverable_type\` da tarefa.
+
+## deliverable_type: text
+
+Tarefa exige uma resposta escrita (validação, análise, plano, reflexão).
+
+Checklist:
+1. O aluno produziu pelo menos 1 parágrafo concreto, não 1 frase genérica.
+2. Inclui exemplos ou evidência (números, citação, comparação).
+3. Responde diretamente ao \`socio_prompt\` da tarefa (releia antes de marcar).
+4. Aluno releu antes de você marcar.
+
+Se algo falta: explique o que e ofereça pra ajudar a estruturar.
+
+## deliverable_type: artifact
+
+Tarefa exige um artefato (deck, doc, planilha, link, código).
+
+Checklist:
+1. Existe um link/arquivo concreto (não "vou fazer depois").
+2. O artefato abre sem erro / não está vazio.
+3. Você (Claude) leu o artefato ou pelo menos viu o título + 1 seção.
+4. Conecta com o objetivo da tarefa (não é um arquivo solto).
+
+Se for código: rode \`pnpm test\` / \`pnpm type-check\` ou equivalente. Sem teste passando, peça pro aluno rodar antes de marcar.
+
+## deliverable_type: checklist
+
+Tarefa é uma lista de sub-itens a executar.
+
+Checklist:
+1. Cada sub-item tem um "sim" explícito do aluno.
+2. Você listou o que ele disse pra cada item antes de fechar.
+3. Se algum item ficou "parcial", chame \`comment_on_task\` registrando isso antes de marcar — não esconda do instrutor.
+
+## deliverable_type: pitch
+
+Tarefa exige uma fala (pitch, apresentação, gravação).
+
+Checklist:
+1. Aluno deu o pitch em voz alta (você não consegue ouvir, mas peça pra ele gravar e te resumir).
+2. Resumo em 3 frases: problema, solução, ask.
+3. Aluno se sentiu confortável com a estrutura (pergunte explicitamente).
+4. Tempo estimado ≤ tempo da tarefa.
+
+## Sempre
+
+- Antes de marcar, mostre ao aluno: "vou marcar com esse resumo — confere?" e use o resumo como \`summary\` do \`mark_task_complete\`.
+- Anexe um \`transcript_excerpt\` curto (3-5 linhas das mensagens mais relevantes da tarefa) se possível.
+- Se o aluno disser "acabei" mas faltar item do checklist, NÃO marque. Mostre o que falta. Se ele insistir após ver, marque — coaching, não tribunal.
+- Se a tarefa foi reaberta pelo instrutor, releia o \`reason\` (vem via UserPromptSubmit hook) antes de pedir nova evidência.
+`;
+}