rootr-cli 0.9.0 → 0.13.0

package/lib/mcp-tools/signed.js

@@ -0,0 +1,495 @@
+import { z } from 'zod';
+
+import {
+  jsonResult,
+  textResult,
+  errorResult,
+  makeClient,
+  requireWorkspace,
+  resolveNodeId,
+  resolveOptionalNodeId,
+  NODE_TARGET_HINT,
+} from './shared.js';
+
+/**
+ * SIGN-001 — 서명문서 · 연구노트.
+ *
+ * 마크다운 문서인데 **올리는 순간 본문이 얼고**, 결재라인에 적힌 사람들이 차례로
+ * 서명하면 서명마다 시점확인(RFC 3161 TSA)과 워크스페이스 원장 해시 체이닝이
+ * 붙는다. 국가R&D 전자연구노트 지침이 요구하는 ①전자서명 ②시점확인 ③위변조확인이
+ * 그대로 이 셋이다.
+ *
+ * 에이전트가 대신 눌러 줄 수 없는 자리가 하나 있다: **서명**. 확인 코드가 사람
+ * 메일로만 가고, 그게 "본인이 눌렀다"의 유일한 증거라서 그렇다. 그래서 흐름은
+ * 항상 rootr_request_signing_code → (사람이 메일에서 코드를 읽어 알려 준다) →
+ * rootr_sign_document 다. 코드를 지어내지 말고 사람에게 물어야 한다.
+ */
+
+const APPROVAL_STEP = z.object({
+  label: z.string().optional().describe('단계 이름, 예: "기재자" / "점검자" / "부서장"'),
+  rule: z
+    .enum(['ALL', 'ANY', 'N_OF_M'])
+    .optional()
+    .describe('ALL=이 단계 전원 서명(기본), ANY=아무나 한 명, N_OF_M=requiredCount 명'),
+  requiredCount: z.number().int().min(1).optional().describe('rule이 N_OF_M일 때 필요한 인원 수'),
+  members: z
+    .array(
+      z.object({
+        userId: z
+          .string()
+          .optional()
+          .describe('워크스페이스 멤버의 userId. 밖의 사람이면 대신 email을 쓴다'),
+        email: z
+          .string()
+          .optional()
+          .describe(
+            '워크스페이스 밖 결재자의 메일 주소. 그 사람에게 서명 링크가 메일로 가고, ' +
+              '계정 없이 서명한다. userId와 둘 중 하나만 쓴다',
+          ),
+        displayName: z
+          .string()
+          .optional()
+          .describe('메일 결재자를 화면에 뭐라고 부를지. 생략하면 메일 주소를 그대로 쓴다'),
+        role: z
+          .enum(['AUTHOR', 'REVIEWER', 'APPROVER'])
+          .optional()
+          .describe('AUTHOR=기재자, REVIEWER=점검자, APPROVER=결재자. 생략하면 자리로 정해진다'),
+      }),
+    )
+    .min(1),
+});
+
+const CODE_HINT =
+  '메일로 받은 6자리 확인 코드. 먼저 rootr_request_signing_code 를 부르면 사용자 메일로 가고, ' +
+  '사용자가 알려 준 값을 그대로 넣는다. 절대 지어내지 말 것 — 틀리면 403이고 5회 틀리면 코드가 죽는다.';
+
+export function registerSignedDocTools(server) {
+  server.registerTool(
+    'rootr_create_signed_document',
+    {
+      title: 'Create a Rootr signed document',
+      description:
+        'Create a SIGNED document (서명문서 · 전자결재 · 국가R&D 전자연구노트) in a Rootr (루터) workspace. ' +
+        'A markdown document that FREEZES on submit: after that the body, attachments and approval line ' +
+        'cannot be edited, every signature carries an RFC 3161 timestamp, and the whole workspace keeps a ' +
+        'hash-chained ledger so tampering is detectable. Signed documents cannot be deleted (30-year ' +
+        'retention). Use this instead of a plain DOCUMENT whenever the content must be provable — 결재/승인 ' +
+        '문서, 연구노트, 점검 기록, 회의 확인서. ' +
+        'Flow: create (body + approval line) → edit the body freely with rootr_write/rootr_append → ' +
+        'rootr_request_signing_code → ask the human for the 6-digit code → rootr_submit_signed_document ' +
+        '(freezes + first signature) → each remaining signer does request-code + rootr_sign_document.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        name: z.string().optional().describe('문서 이름, 예: "2026-08-25 실험 기록"'),
+        path: z
+          .string()
+          .optional()
+          .describe('트리 경로로 만들 때, 예: "/연구노트/2026-08-25 실험기록" (parentId 대신)'),
+        parentId: z.string().optional().describe(`부모 폴더 id${NODE_TARGET_HINT}`),
+        createParents: z.boolean().optional().describe('path를 쓸 때 없는 상위 폴더까지 만든다'),
+        icon: z.string().optional().describe('이모지 아이콘'),
+        content: z.string().optional().describe('본문 마크다운. 올리기 전까지는 얼마든지 고칠 수 있다'),
+        mode: z
+          .enum(['APPROVAL', 'RESEARCH_NOTE'])
+          .optional()
+          .describe('APPROVAL=전자결재(기본), RESEARCH_NOTE=연구노트'),
+        reviewerUserId: z
+          .string()
+          .optional()
+          .describe(
+            '연구노트 프리셋용 점검자(연구책임자) userId. approvalLine 없이 이것만 주면 ' +
+              '"기재자(만든 사람) → 점검자" 두 단계가 자동으로 짜인다',
+          ),
+        noteMeta: z
+          .record(z.any())
+          .optional()
+          .describe('연구노트 표지 정보: 과제번호·과제명·연구책임자·기관 등'),
+        approvalLine: z
+          .array(APPROVAL_STEP)
+          .optional()
+          .describe('결재라인. 배열 순서가 곧 서명 순서다'),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ parentId, workspace, ...rest }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
+        return jsonResult(await client.createSignedDoc(ws, { ...rest, parentId }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_read_signed_document',
+    {
+      title: 'Read a Rootr signed document state',
+      description:
+        'Read a SIGNED document\'s signing state: mode, status (DRAFT/IN_PROGRESS/COMPLETED/REJECTED/' +
+        'SUPERSEDED), whether it is locked, the approval line with each step\'s progress, every signature so far ' +
+        '(signer, time, TSA timestamp), whether the body still matches the frozen hash, and whether YOU can ' +
+        'sign right now (canSign). Read the body itself with rootr_read.',
+      annotations: { readOnlyHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(await client.getSignedDoc(await resolveNodeId(client, nodeId)));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_set_approval_line',
+    {
+      title: 'Set a signed document approval line',
+      description:
+        'Replace the approval line (결재라인) of a SIGNED document. The array order IS the signing order; ' +
+        'each step can require everyone (ALL), anyone (ANY) or N of M. Only possible BEFORE submit — once ' +
+        'the document is submitted the line is frozen with the body (409 SIGNED_DOC_LOCKED); reject it first ' +
+        'to reopen. Each member is EITHER a workspace member (userId) OR an outside person (email) — ' +
+        'an email signer gets a signing link by mail and signs without an account. Never both on one member.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        steps: z.array(APPROVAL_STEP).min(1).describe('단계 배열. 순서가 곧 서명 순서다'),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, steps, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(await client.setApprovalLine(await resolveNodeId(client, nodeId), steps));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_apply_research_note_preset',
+    {
+      title: 'Turn a signed document into a research note',
+      description:
+        'Switch a SIGNED document to RESEARCH_NOTE mode and build the two-step line the Korean national R&D ' +
+        'guideline requires: 기재자(the caller) → 점검자(the reviewer/연구책임자). Optionally stores the cover ' +
+        'metadata (과제번호·과제명·기관). Use this instead of hand-building the approval line for 연구노트.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        reviewerUserId: z.string().describe('점검자(연구책임자)의 userId'),
+        noteMeta: z.record(z.any()).optional().describe('표지 정보: 과제번호·과제명·연구책임자·기관 등'),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, reviewerUserId, noteMeta, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(
+          await client.applyResearchNotePreset(await resolveNodeId(client, nodeId), {
+            reviewerUserId,
+            noteMeta,
+          }),
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_request_signing_code',
+    {
+      title: 'Email a signing confirmation code',
+      description:
+        'Send the 6-digit signing confirmation code to the signer\'s own email. REQUIRED before ' +
+        'rootr_submit_signed_document / rootr_sign_document / rootr_reject_signed_document / ' +
+        'rootr_bulk_sign_documents — the code is the only evidence that a HUMAN pressed sign, so you cannot ' +
+        'read it and must ask the user for it. Valid 10 minutes, 5 wrong tries kill it, and re-requesting ' +
+        'within 30 seconds is refused. Pass `bulk: true` (with no nodeId) for one code that covers a bulk sign.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        nodeId: z
+          .string()
+          .optional()
+          .describe(`서명문서 노드 id${NODE_TARGET_HINT}. bulk가 true면 생략한다`),
+        bulk: z.boolean().optional().describe('묶음 서명용 코드를 받을 때 true'),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, bulk, workspace }) => {
+      try {
+        if (bulk) {
+          const ws = requireWorkspace(workspace);
+          const client = makeClient(ws);
+          const out = await client.requestBulkSigningCode(ws);
+          return jsonResult({ ...out, next: '사용자에게 메일로 받은 6자리 코드를 물어보세요.' });
+        }
+        const client = makeClient(workspace);
+        if (!nodeId) throw new Error('nodeId 또는 bulk: true 중 하나가 필요합니다.');
+        const out = await client.requestSigningCode(await resolveNodeId(client, nodeId));
+        return jsonResult({ ...out, next: '사용자에게 메일로 받은 6자리 코드를 물어보세요.' });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_submit_signed_document',
+    {
+      title: 'Submit (freeze + first-sign) a signed document',
+      description:
+        'Submit a SIGNED document: the body and attachments FREEZE (their SHA-256 is recorded) and the ' +
+        'first step\'s signers are notified. IRREVERSIBLE except by rejection — after this the only way ' +
+        'to change the content is a revision (rootr_revise_signed_document). ' +
+        'Submitting and signing are DIFFERENT acts: submitting only needs write access. `code` is required ' +
+        'ONLY when the submitter is themselves a signer in step 1, because then their signature is stamped ' +
+        'at the same time — get it with rootr_request_signing_code and ask the human for it. If step 1 has ' +
+        'no account members (e.g. only email signers), omit `code` entirely. When in doubt omit it: the ' +
+        'server answers REAUTH_REQUIRED if a code was in fact needed.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        code: z
+          .string()
+          .optional()
+          .describe(`올리는 사람이 1단계 서명자일 때만 필요합니다. ${CODE_HINT}`),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, code, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        const id = await resolveNodeId(client, nodeId);
+        return jsonResult(await client.submitSignedDoc(id, code ? { code } : {}));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_sign_document',
+    {
+      title: 'Sign a Rootr signed document',
+      description:
+        'Sign a SIGNED document as the current step\'s signer. Records an Ed25519 signature over the frozen ' +
+        'content hash, requests an RFC 3161 timestamp, and links the signature into the workspace hash ledger. ' +
+        'Only works when it is your turn (check canSign with rootr_read_signed_document). Needs the emailed ' +
+        'code from rootr_request_signing_code — ask the human for it, never invent it.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        code: z.string().describe(CODE_HINT),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, code, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(await client.signSignedDoc(await resolveNodeId(client, nodeId), { code }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_reject_signed_document',
+    {
+      title: 'Reject a signed document',
+      description:
+        'Reject a SIGNED document with a reason. The document unlocks so the author can fix and resubmit; ' +
+        'signatures already collected are recorded as part of the history and the rejection itself is ' +
+        'notified to the author. The reason is required — "반려됨"만 남으면 고칠 수가 없다.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        comment: z.string().describe('반려 사유 (필수)'),
+        code: z.string().optional().describe(CODE_HINT),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, comment, code, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(
+          await client.rejectSignedDoc(await resolveNodeId(client, nodeId), { comment, code }),
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_reopen_signed_document',
+    {
+      title: 'Reopen an unsigned signed-document draft',
+      description:
+        'Unlock a SIGNED document so the body and the approval line can be edited again. Works when the ' +
+        'document was sent back (REJECTED), or when it is still in progress and **nobody has signed yet** — ' +
+        'the escape hatch for "I submitted it to the wrong address". Once any signature exists this refuses: ' +
+        'make a revision instead (rootr_revise_signed_document).',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(await client.reopenSignedDoc(await resolveNodeId(client, nodeId)));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_revise_signed_document',
+    {
+      title: 'Create a revision of a signed document',
+      description:
+        'Create a NEW revision of an already-signed document. Signed documents are never edited in place — ' +
+        'the guideline requires that both the original and the correction stay visible — so this copies the ' +
+        'body into a fresh SIGNED node (revisionNo + 1), marks the original SUPERSEDED, and returns the new ' +
+        'node id. The reason (note) is recorded on the revision.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        nodeId: z.string().describe(`원본 서명문서 노드 id${NODE_TARGET_HINT}`),
+        note: z.string().describe('무엇을 왜 고치는지 (필수, 개정본에 남는다)'),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, note, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(await client.reviseSignedDoc(await resolveNodeId(client, nodeId), note));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_verify_signed_document',
+    {
+      title: 'Verify a signed document (tamper check)',
+      description:
+        'Verify a SIGNED document end to end: every Ed25519 signature is re-checked against its payload, ' +
+        'every hash-chain link is recomputed, the current body is hashed and compared with the frozen hash, ' +
+        'and the workspace ledger is replayed. Returns contentIntact / allSignaturesValid / allTimestamped / ' +
+        'ledgerIntact plus per-signature detail. This is the answer to "이 문서가 위조되지 않았음을 증명해 봐".',
+      annotations: { readOnlyHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeId, workspace }) => {
+      try {
+        const client = makeClient(workspace);
+        return jsonResult(await client.verifySignedDoc(await resolveNodeId(client, nodeId)));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_list_signed_documents',
+    {
+      title: 'List Rootr signed documents',
+      description:
+        'List the SIGNED documents of a workspace with their status and who each one is waiting on. ' +
+        'Set pendingMine: true for "내 차례인 것만" — the list a 연구책임자 opens to see this week\'s ' +
+        'unchecked notes before bulk-signing them.',
+      annotations: { readOnlyHint: true },
+      inputSchema: {
+        status: z
+          .enum(['DRAFT', 'IN_PROGRESS', 'COMPLETED', 'REJECTED', 'SUPERSEDED', 'VOIDED'])
+          .optional(),
+        mode: z.enum(['APPROVAL', 'RESEARCH_NOTE']).optional(),
+        pendingMine: z.boolean().optional().describe('내 서명을 기다리는 것만'),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ status, mode, pendingMine, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        return jsonResult(await client.listSignedDocs(ws, { status, mode, pendingMine }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_bulk_sign_documents',
+    {
+      title: 'Submit and sign many Rootr documents at once',
+      description:
+        'Process up to 100 SIGNED documents in one call with ONE emailed code (get it with ' +
+        'rootr_request_signing_code + bulk: true). ' +
+        '**DRAFT documents are submitted too** — you do NOT need a separate per-document code to submit ' +
+        'them first. A draft is frozen and, if you are a step-1 signer, stamped at the same time; a document ' +
+        'already IN_PROGRESS is simply signed. Each result carries `did`: "submitted", "submitted+signed" ' +
+        'or "signed". Documents where it is not your turn are skipped and reported, not failed. ' +
+        'This is what makes 연구노트 usable in practice — a 연구책임자 clearing "이번 주 미점검 12건" ' +
+        'without opening each one. Submitting FREEZES the body irreversibly, so pass only the ids you mean.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeIds: z.array(z.string()).min(1).max(100).describe('서명할 노드 id 목록 (경로도 됩니다)'),
+        code: z.string().describe(CODE_HINT + ' (bulk: true 로 받은 코드)'),
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ nodeIds, code, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const ids = [];
+        for (const t of nodeIds) ids.push(await resolveNodeId(client, t));
+        return jsonResult(await client.bulkSignSignedDocs(ws, { nodeIds: ids, code }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_verify_ledger',
+    {
+      title: 'Verify the workspace signature ledger',
+      description:
+        'Replay the whole workspace signature ledger (every signature ever made, hash-chained in order) and ' +
+        'report whether it is intact, how many links it holds, its head hash, and the first broken sequence ' +
+        'if any. A broken ledger means someone edited or deleted signature rows in the database.',
+      annotations: { readOnlyHint: true },
+      inputSchema: {
+        workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
+      },
+    },
+    async ({ workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        return jsonResult(await makeClient(ws).verifyLedger(ws));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/workspaces.js

@@ -152,15 +152,27 @@ export function registerWorkspaceTools(server) {
   server.registerTool(
     'rootr_scaffold_plan',
     {
-      title: 'Plan a workspace scaffold from an intent — then ASK THE USER before building',
+      title: 'Step 1 of scaffolding — get the design method, then think and ask',
       description:
-        'Step 1 of scaffolding, ALWAYS call this first. Given a natural-language intent (e.g. "SRE 온콜 위키" or ' +
-        '"sales CRM for a 5-person team"), Rootr\'s consultant returns a questionPolicy (ask the user MIN 3, up ' +
-        'to 10 clarifying questions — this is not optional), the dimensions to cover, domain frameworks, and the ' +
-        'buildingBlocks menu (DATABASE/DOCUMENT/SPREADSHEET/WHITEBOARD/FORM/ISSUE_TRACKER/FOLDER). You must then ' +
-        'GENERATE your own questions from those frameworks, ask the user, and only design the tree AFTER their ' +
-        'answers — every answer must visibly shape the result. Never build straight from a one-line intent. ' +
-        'No workspace needed; create with rootr_create_workspace or rootr_scaffold_apply afterwards.',
+        'ALWAYS call this first. There are NO templates and NO domain skeletons behind it — deliberately. It ' +
+        'does not classify your intent and it will not hand you a structure; what comes back is the METHOD: ' +
+        '`analyzeFirst` (the questions to answer about how this job actually runs before you design anything — ' +
+        'the daily and weekly rhythm, what piles up, what moves through stages, what arrives from outside, where ' +
+        'money is added up, what causes trouble when it is late, and above all what is UNIQUE to this job), ' +
+        '`designRules` (how to turn those answers into structure — nouns that pile up become DATABASEs, "one A ' +
+        'has many B" becomes a relation, stages become select + board, dates become calendar, outside input ' +
+        'becomes FORM + collectInto, calculation becomes SPREADSHEET, counting becomes rollup), `buildingBlocks` ' +
+        '(what the product actually offers), `questionPolicy` (ask the user 3-10 questions — you WRITE them, ' +
+        'none are provided), and `loop` (the whole sequence). Design it from scratch every time: a bakery, a ' +
+        'dental clinic and an SRE team need different things, and no catalogue of skeletons could hold them. ' +
+        'Treat it exactly like a coding request. When someone says "build me this" you ask a few clarifying ' +
+        'questions, write the code, compile it, run the tests, leave a README, and report. Same sequence here: ' +
+        'analyzeFirst = understanding the requirement · questionPolicy = the questions you ask · designRules = ' +
+        'writing the code · rootr_scaffold_review = compiling (fix what it flags, compile again) · ' +
+        'rootr_scaffold_apply = building · the how-to-use manual = the README · rootr_test_workspace = running ' +
+        'the tests. The user should only ever have to type that one sentence — ask your questions, take their ' +
+        'answers, and finish the whole thing in this conversation. If they do not answer or say "just do it", ' +
+        'assume the most plausible answers, build it anyway, and record the assumptions in the manual.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         intent: z.string().describe('Natural-language description of what the workspace/tree should be for'),
@@ -184,8 +196,10 @@ export function registerWorkspaceTools(server) {
       description:
         'Create an entirely new Rootr (루터) workspace pre-populated with the given document tree. ' +
         'REQUIRES an account key (PAT) with the workspaces:create scope — a workspace-scoped key cannot do this. ' +
-        'PRECONDITION: call rootr_scaffold_plan first and ask the user its 3-10 clarifying questions; design the ' +
-        'tree from their answers. Build a real tool, not a pile of thin markdown files: mix DATABASE (board/' +
+        'PRECONDITION: rootr_scaffold_plan first, ask the user its 3-10 clarifying questions, design the tree from ' +
+        'their answers, then run rootr_scaffold_review and fix everything it flags at `error` level. The ' +
+        'response carries the same `review` back, so a low score here means you shipped something thin. ' +
+        'Build a real tool, not a pile of thin markdown files: mix DATABASE (board/' +
         'timeline views, seed rows), SPREADSHEET (formulas), FORM, ISSUE_TRACKER and rich multi-section DOCUMENTs ' +
         'where they fit, and set an emoji `icon` on folders/databases/key documents. The `tree` shape follows ' +
         'the scaffold schema in llms.txt (max 200 nodes). AFTER creating: if your runtime can receive HTTP ' +
@@ -209,15 +223,105 @@ export function registerWorkspaceTools(server) {
     },
   );
 
+  server.registerTool(
+    'rootr_scaffold_review',
+    {
+      title: 'Check a designed tree BEFORE building it — the compiler pass',
+      description:
+        'Step 3 of scaffolding (plan → ask → design → REVIEW → fix → apply). Give it the tree you designed and ' +
+        'it returns { score 0-100, counts, findings[], summary } — every finding is a concrete defect with the ' +
+        'node path, e.g. a table whose only column is the title (that is a list, not a table), a lifecycle ' +
+        'column with no board view, a date column with no calendar, a form with nowhere to collect answers, ' +
+        'tables that are never related to each other, an empty guide document. Fix what it flags and review ' +
+        'again — like re-running a compiler — until nothing at `error` level is left. The rules are ' +
+        'domain-agnostic, so this works for a bakery or a dental clinic exactly as well as for a SaaS team. ' +
+        'Creates nothing and needs no workspace, so run it as many times as you like before committing.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        tree: treeArg('The scaffold tree you designed — an ARRAY of node objects, same shape you would pass to rootr_scaffold_apply'),
+      },
+    },
+    async ({ tree }) => {
+      try {
+        const client = makeClient();
+        const result = await client.scaffoldReview(parseTree(tree));
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_review_workspace',
+    {
+      title: 'Check the workspace you ACTUALLY built — not the tree you sent',
+      description:
+        'Step 5, after building. `rootr_scaffold_review` grades the tree you DESIGNED; this grades what really ' +
+        'exists in the workspace right now — whatever tools made it. Run it after every build: a design can score ' +
+        '100 and still land broken (a form whose answers go nowhere, a view whose filter vanished, rows that never ' +
+        'got linked). Returns the same { score, counts, findings[], summary }. Pass `rootPath` to grade only the ' +
+        'subtree you just added, otherwise an older workspace drags the score down and the number stops meaning ' +
+        'anything. Fix what it flags with the normal tools (add rows, write the guide document, add the missing ' +
+        'columns/views) and run it again until it is clean.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        rootPath: z.string().optional().describe('Grade only this subtree, e.g. "/동네 빵집 운영"'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
+      },
+    },
+    async ({ rootPath, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        return jsonResult(await client.scaffoldReviewBuilt(ws, rootPath));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_test_workspace',
+    {
+      title: 'RUN the workspace you built — does it actually work?',
+      description:
+        'The last step, and the one that catches what the two review tools cannot. `rootr_scaffold_review` grades ' +
+        'the tree you designed; `rootr_review_workspace` grades the shape of what got built; this one **exercises ' +
+        'it**: does every relation point at a row that really exists, do rollups and formulas produce a value on ' +
+        'real rows, do board/calendar/filter views reference columns that exist, can the form actually deposit an ' +
+        'answer (target table alive AND every question name matching a column — a mismatch makes answers vanish ' +
+        'with no error), are sheet formulas computed and free of #REF!/#DIV/0!. Returns { ran, passed, failed, ' +
+        'warned, checks[] }. It writes nothing, so run it as often as you like. A workspace can score 100 on both ' +
+        'reviews and still fail here — that is exactly the case this exists for. Pass `rootPath` to test only the ' +
+        'subtree you just built. Fix every `fail` and run it again.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        rootPath: z.string().optional().describe('Test only this subtree, e.g. "/동네 빵집 운영"'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
+      },
+    },
+    async ({ rootPath, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        return jsonResult(await client.scaffoldSelfTest(ws, rootPath));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_scaffold_apply',
     {
       title: 'Apply a scaffold tree to an existing workspace',
       description:
         'Create the given document tree inside an existing Rootr (루터) workspace, optionally rooted under an ' +
-        'existing path. Works with a workspace key (docs:write scope). PRECONDITION: call rootr_scaffold_plan ' +
-        'first and ask the user its 3-10 clarifying questions; design the tree from their answers (same quality ' +
-        'bar as rootr_create_workspace — real building blocks with icons/views/seed content, not thin markdown). ' +
+        'existing path. Works with a workspace key (docs:write scope). PRECONDITION: rootr_scaffold_plan first, ask ' +
+        'its 3-10 clarifying questions, design from the answers, then rootr_scaffold_review and fix every ' +
+        '`error` finding (same quality bar as rootr_create_workspace — real building blocks with icons/views/' +
+        'seed rows, not thin markdown). The response carries the `review` back so you can see what stayed weak, and AFTER it lands run rootr_review_workspace (rootPath = your new subtree) — that one grades what really exists. ' +
         'AFTER creating: if your runtime can receive HTTP callbacks, offer a webhook on the new subtree ' +
         '(rootr_create_webhook with scopeNodeId) so changes flow back to you — skip your own actorId.',
       annotations: { readOnlyHint: false, destructiveHint: false },