@olierjs/fugue-cli 0.0.0-stage → 0.1.2

package/skills/plan-with-remote/scripts/protocol.mjs

@@ -0,0 +1,147 @@
+import { digest } from './storage.mjs';
+import { validateDocuments } from './service.mjs';
+
+const record = (value, name) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${name} is invalid`);
+  return value;
+};
+const positive = value => Number.isSafeInteger(value) && value > 0;
+const same = (left, right) => digest(left) === digest(right);
+
+export function buildAcceptSolutionReviewCommand(input) {
+  return { type: 'accept_solution_review', ...input };
+}
+export function buildFeedbackSolutionReviewCommand(input) {
+  return { type: 'feedback_solution_review', ...input };
+}
+export function parseSolutionReviewOperationAccepted(response, command) {
+  const data = record(response?.data, 'solution review acceptance');
+  if (data.type !== 'solution_review_operation_accepted' || data.requirementId !== command.requirementId || data.commandId !== command.commandId || typeof data.operationId !== 'string' || data.polling?.operationId !== data.operationId || data.review?.reviewRevision !== command.reviewRevision || !same(data.review?.sourceBinding, command.sourceBinding) || !positive(data.lifecycle?.snapshotRevision)) throw new Error('solution review operation does not match the submitted decision');
+}
+
+export async function waitForProjectPreparation(input, accepted, deps) {
+  const data = record(accepted?.data, 'preparation acceptance');
+  if (data.requirementId !== input.requirementId || !data.operationId || !positive(data.polling?.nextPollAfterMs)) throw new Error('preparation acceptance identity is invalid');
+  while (deps.now() - input.startedAt < input.timeoutMs) {
+    const response = record((await deps.read())?.data, 'project context');
+    const preparation = response.preparation;
+    if (response.project?.projectId !== input.projectId || preparation?.projectId !== input.projectId || preparation?.requirementId !== input.requirementId || preparation?.runId !== data.operationId) throw new Error('project preparation identity mismatch');
+    if (preparation.status === 'failed') throw new Error(`project preparation failed: ${preparation.error?.code ?? 'unknown'}: ${preparation.error?.message ?? 'no details'}`);
+    if (preparation.status === 'succeeded' && preparation.baselineId && response.baseline?.baselineId === preparation.baselineId) return;
+    await deps.wait(Math.min(data.polling.nextPollAfterMs, input.timeoutMs - (deps.now() - input.startedAt)));
+  }
+  throw new Error('project preparation timed out');
+}
+
+export async function continuePlanningAfterHumanInput(input, deps) {
+  const response = await deps.post(input.command);
+  const data = record(response?.data, 'human input response');
+  if (data.operationId) return runPlanningFromAcceptedOperation({ requirementId: input.requirementId, operationId: data.operationId, timeoutMs: input.timeoutMs }, deps);
+  if (data.type !== 'submit_stage_clarification' || data.requirementId !== input.requirementId) throw new Error('human input response identity mismatch');
+  const pending = record(data.pendingStageResolution, 'pending stage resolution');
+  return { status: 'needs_human_input', requirementId: input.requirementId, viewVersion: pending.expectedSnapshotRevision, snapshotRevision: pending.expectedSnapshotRevision, questions: (pending.actions ?? []).map(action => ({ kind: 'stage', questionKey: action.questionKey, questionRef: action.questionRef, blockerRef: action.blockerRef, prompt: action.question })), resolution: { kind: 'stage', expectedSnapshotRevision: pending.expectedSnapshotRevision } };
+}
+
+export async function runPlanningFromAcceptedOperation(input, deps) {
+  const started = deps.now();
+  while (deps.now() - started < input.timeoutMs) {
+    const response = await deps.post(flowCommand(input.requirementId, input.operationId, 'summary'));
+    const summary = record(response?.data, 'planning flow');
+    summary.polling = response.polling;
+    summary.limits = response.limits;
+    if (summary.requirementId !== input.requirementId || summary.operation?.operationId !== input.operationId) throw new Error('planning flow identity mismatch');
+    if (input.expectedPlanningMode && summary.planningMode !== input.expectedPlanningMode) throw new Error('planning mode differs from the submitted request');
+    const operation = summary.operation;
+    if (summary.pendingStageResolution || summary.pendingOwnerResolution) return humanInput(summary);
+    if (summary.displayStatus === 'awaiting_revision' && ['finished', 'failed'].includes(operation.status)) {
+      const outcome = await readRevisionDocuments(input, deps, summary);
+      if (outcome) return outcome;
+      const remaining = input.timeoutMs - (deps.now() - started);
+      const interval = summary.polling?.nextPollAfterMs;
+      if (!positive(interval)) throw new Error('planning polling interval is invalid');
+      if (remaining > 0) await deps.wait(Math.min(interval, remaining));
+      continue;
+    }
+    const recovering = summary.currentStage === 'failed' && ['queued', 'running'].includes(operation.status);
+    if (summary.currentStage === 'failed' && !recovering || operation.status === 'failed' || summary.currentStage === 'stopped') return { status: 'failed', requirementId: input.requirementId, viewVersion: summary.viewVersion, code: operation.error?.code ?? 'runtime_failed', message: operation.error?.message ?? 'planning failed', retryable: operation.error?.retryable === true };
+    if (summary.currentStage === 'awaiting_solution_review' && operation.status === 'finished') {
+      if (summary.planningMode !== 'standard') throw new Error('lightweight planning cannot require solution acknowledgement');
+      const data = record((await deps.post({ type: 'get_solution_review', requirementId: input.requirementId }))?.data, 'solution review');
+      if (data.requirementId !== input.requirementId || data.snapshotRevision !== summary.viewVersion || data.review?.reviewRevision !== operation.solutionReviewResult?.reviewRevision || !same(data.review?.sourceBinding, operation.solutionReviewResult?.sourceBinding)) throw new Error('solution review is not bound to the current flow');
+      return { status: 'awaiting_solution_review', requirementId: input.requirementId, planningMode: summary.planningMode, viewVersion: summary.viewVersion, snapshotRevision: data.snapshotRevision, solutionReview: data.review, flow: summary };
+    }
+    if (summary.currentStage === 'awaiting_execution_doc_approval' && operation.status === 'finished') {
+      const fullResponse = await deps.post(flowCommand(input.requirementId, input.operationId, 'full'));
+      const flow = record(fullResponse?.data, 'full planning flow');
+      flow.limits = fullResponse.limits;
+      if (flow.requirementId !== input.requirementId || flow.operation?.operationId !== input.operationId || flow.operation?.status !== 'finished' || flow.currentStage !== 'awaiting_execution_doc_approval' || flow.viewVersion !== summary.viewVersion || flow.pageInfo?.hasMore || flow.limits?.omittedCollections?.some(value => ['artifacts', 'gateResults'].includes(value)) || !Array.isArray(flow.gateResults) || !flow.gateResults.length) throw new Error('full planning flow is incomplete or mismatched');
+      if (flow.pendingStageResolution || flow.pendingOwnerResolution) return humanInput(flow);
+      const documents = (await deps.post({ type: 'get_planning_candidate_documents', requirementId: input.requirementId }))?.data?.documents;
+      validateDocuments(documents, input.requirementId);
+      if (documents.snapshotRevision !== flow.viewVersion) throw new Error('candidate document version differs from planning flow');
+      if (flow.displayStatus === 'awaiting_revision') {
+        const revision = flow.planningRevision;
+        if (revision?.available !== true || revision.reason !== 'quality_blocked' || revision.candidateRevision !== documents.candidateRevision) throw new Error('quality revision documents do not match the candidate');
+        for (const [kind, ref] of [['execution_doc', documents.executionDocumentRef], ['acceptance_doc', documents.acceptanceDocumentRef]]) {
+          const entry = flow.planningDocuments?.[kind];
+          if (entry?.candidateRevision !== documents.candidateRevision || !same(entry.documentRef, ref)) throw new Error('quality revision document reference differs from flow');
+        }
+        return { status: 'awaiting_revision', planningMode: flow.planningMode, flow, ...documents };
+      }
+      if (summary.planningMode === 'standard' && !flow.boundedReview) throw new Error('full planning flow is missing bounded review');
+      const gateIds = flow.gateResults.map(gate => gate?.gateId).filter(value => typeof value === 'string');
+      const gate = documents.gate;
+      if (gate.status !== 'decided' || (summary.currentStageStatus === 'gate_blocked' && gate.decision !== 'blocked') || (gateIds.length && !gateIds.includes(`gate-decision-${gate.gateRevision}`))) throw new Error('candidate Gate differs from planning flow');
+      const report = (await deps.post({ type: 'inspect_requirement', requirementId: input.requirementId }))?.data?.report;
+      if (report?.requirementId !== input.requirementId || report.snapshotRevision !== documents.snapshotRevision || report?.approvalReport?.requirement_id !== input.requirementId || report.approvalReport.candidate_revision !== documents.candidateRevision || report.approvalReport.gate_revision !== gate.gateRevision || report.approvalReport.decision !== gate.decision) throw new Error('candidate Gate differs from current approval report');
+      return { status: gate.decision === 'pass' ? 'ready_for_approval' : 'awaiting_revision', planningMode: flow.planningMode, flow, ...documents };
+    }
+    const remaining = input.timeoutMs - (deps.now() - started);
+    const interval = summary.polling?.nextPollAfterMs;
+    if (!positive(interval)) throw new Error('planning polling interval is invalid');
+    await deps.wait(Math.min(interval, remaining));
+  }
+  return { status: 'failed', requirementId: input.requirementId, viewVersion: 0, code: 'planning_wait_timeout', message: 'planning wait timed out', retryable: true };
+}
+
+function flowCommand(requirementId, operationId, mode) {
+  const full = mode === 'full';
+  return { type: 'get_requirement_flow_view', requirementId, operationId, responseMode: mode, include: { stages: true, artifacts: full, runtimeRuns: full, gateResults: true, projectionJobs: full, externalProjections: full, evidenceRefs: full }, limit: { maxArtifacts: 200, maxRuntimeRuns: 200, maxEvidenceRefs: 200 }, maxItemsPerSection: 200 };
+}
+function humanInput(flow) {
+  const resolution = flow.pendingOwnerResolution ?? flow.pendingStageResolution;
+  const owner = !!flow.pendingOwnerResolution;
+  const actions = owner ? [resolution] : resolution.actions ?? [];
+  const questions = actions.map(action => {
+    if (!owner) return { kind: 'stage', questionKey: action.questionKey, questionRef: action.questionRef, blockerRef: action.blockerRef, prompt: action.question };
+    if (!['replan_required', 'human_resolution_required'].includes(action.outcome)) throw new Error('owner resolution outcome is invalid');
+    return { kind: 'owner', pendingResolutionIdentity: action.pendingResolutionIdentity, action: action.outcome === 'replan_required' ? 'confirm_replan' : 'clarify', prompt: action.reason };
+  });
+  return { status: 'needs_human_input', requirementId: flow.requirementId, viewVersion: flow.viewVersion, snapshotRevision: resolution.expectedSnapshotRevision, questions, resolution: { kind: owner ? 'owner' : 'stage', expectedSnapshotRevision: resolution.expectedSnapshotRevision } };
+}
+
+async function readRevisionDocuments(input, deps, summary) {
+  const fullResponse = await deps.post(flowCommand(input.requirementId, input.operationId, 'full'));
+  const flow = record(fullResponse?.data, 'full planning flow');
+  flow.limits = fullResponse.limits;
+  if (flow.requirementId !== input.requirementId || flow.operation?.operationId !== input.operationId) throw new Error('quality revision flow identity mismatch');
+  if (flow.limits?.omittedCollections?.some(value => ['artifacts', 'gateResults'].includes(value)) || !Array.isArray(flow.gateResults)) throw new Error('quality revision flow is missing required collections');
+  if (flow.pageInfo?.hasMore) throw new Error('quality revision flow has more pages');
+  if (!['finished', 'failed'].includes(flow.operation?.status) || flow.displayStatus !== 'awaiting_revision' || flow.viewVersion !== summary.viewVersion) return undefined;
+  if (flow.pendingStageResolution || flow.pendingOwnerResolution) return humanInput(flow);
+  const documents = (await deps.post({ type: 'get_planning_candidate_documents', requirementId: input.requirementId }))?.data?.documents;
+  validateDocuments(documents, input.requirementId);
+  if (documents.snapshotRevision !== flow.viewVersion || flow.planningRevision?.available !== true || flow.planningRevision.reason !== 'quality_blocked' || flow.planningRevision.candidateRevision !== documents.candidateRevision) throw new Error('quality revision documents do not match the candidate');
+  for (const [kind, ref] of [['execution_doc', documents.executionDocumentRef], ['acceptance_doc', documents.acceptanceDocumentRef]]) {
+    const entry = flow.planningDocuments?.[kind];
+    if (entry?.candidateRevision !== documents.candidateRevision || !same(entry.documentRef, ref)) throw new Error('quality revision document reference differs from flow');
+  }
+  return { status: 'awaiting_revision', planningMode: flow.planningMode, flow, ...documents };
+}
+export function parseDeliveryPackage(pkg) {
+  if (!pkg || !['ready', 'not_approved', 'unavailable'].includes(pkg.status)) throw new Error('delivery package is invalid');
+  if (pkg.status === 'ready') {
+    if (!pkg.planningDelivery || typeof pkg.planningDelivery.requirementId !== 'string' || pkg.planningCandidateRevision !== pkg.planningDelivery.planningCandidateRevision || !same(pkg.executionDocumentRef, pkg.planningDelivery.executionDocumentRef) || !same(pkg.acceptanceDocumentRef, pkg.planningDelivery.acceptanceDocumentRef) || typeof pkg.executionDocument !== 'string' || typeof pkg.acceptanceDocument !== 'string') throw new Error('delivery package binding is invalid');
+  }
+  return pkg;
+}

package/skills/plan-with-remote/scripts/service.mjs

@@ -0,0 +1,146 @@
+import { execFileSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { digest } from './storage.mjs';
+
+export function transport(baseUrl, timeoutMs) {
+  async function request(path, command) {
+    const response = await fetch(baseUrl + path, {
+      ...(command ? { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(command) } : {}),
+      signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
+    });
+    const text = await response.text();
+    let body;
+    try { body = JSON.parse(text); }
+    catch {
+      const error = new Error('服务未返回有效响应，请检查服务地址或稍后重试原任务。');
+      error.detail = text;
+      error.status = response.status;
+      throw error;
+    }
+    if (!response.ok || body?.ok !== true || !body.data) {
+      const error = new Error('服务未完成请求。请检查服务配置和项目登记；已有任务请勿改用新任务重复提交。');
+      error.detail = body;
+      error.status = response.status;
+      throw error;
+    }
+    return body;
+  }
+  return { request, post: command => request('/v1/reconcile/command', command) };
+}
+
+export async function resolveProject(api, remote, cwd) {
+  const repository = execFileSync('git', ['-C', cwd, 'remote', 'get-url', remote], { encoding: 'utf8' }).trim();
+  const identity = normalizeRepositoryIdentity(repository);
+  if (!identity) throw new Error('目标仓库需要有效的 HTTPS 或 SSH Git remote。');
+  const response = await api.request(`/v1/reconcile/projects/resolve?repository=${encodeURIComponent(repository)}`);
+  const project = response.data;
+  if (!project || typeof project.projectId !== 'string' || typeof project.repositoryIdentity !== 'string') throw new Error('服务返回的项目登记信息无效。');
+  if (project.repositoryIdentity !== identity) throw new Error('服务返回的项目与当前仓库不一致。');
+  return project.projectId;
+}
+
+export async function readInput(path) {
+  const value = JSON.parse(await readFile(path, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('需求文件必须是 JSON 对象。');
+  for (const key of Object.keys(value)) {
+    if (!['title', 'description', 'sources'].includes(key)) throw new Error(`未知需求字段：${key}`);
+  }
+  if (typeof value.description !== 'string' || !value.description.trim()) throw new Error('description 必须包含需求正文。');
+  if (value.title !== undefined && (typeof value.title !== 'string' || !value.title.trim())) throw new Error('title 必须是非空文本。');
+  if (value.sources !== undefined && !Array.isArray(value.sources)) throw new Error('sources 必须是数组。');
+  for (const source of value.sources ?? []) {
+    if (!source || Object.keys(source).some(key => !['label', 'content'].includes(key)) || typeof source.label !== 'string' || !source.label.trim() || typeof source.content !== 'string' || !source.content.trim()) {
+      throw new Error('每项来源只需提供 label 和已读取的 content 正文。');
+    }
+  }
+  return value;
+}
+
+export function requestPackage(input, id, projectId, mode, agent) {
+  return { requestId: id, planningTargetKey: projectId, planningMode: mode,
+    requirement: { description: input.description, ...(input.title ? { title: input.title } : {}) },
+    materials: (input.sources ?? []).map(source => ({ kind: 'text', ...source })),
+    ...(agent ? { agent } : {}),
+  };
+}
+
+function positive(value) { return Number.isSafeInteger(value) && value > 0; }
+function validRef(ref, fields) {
+  return ref && typeof ref === 'object' && fields.every(([key, check]) => check(ref[key]));
+}
+const text = value => typeof value === 'string';
+const nonEmpty = value => text(value) && value.length > 0;
+const integer = value => Number.isSafeInteger(value) && value > 0;
+export function validateDocuments(documents, requirementId) {
+  if (!documents || documents.requirementId !== requirementId || !positive(documents.snapshotRevision) || !positive(documents.candidateRevision)) {
+    throw new Error('返回的规划文档身份或版本无效。');
+  }
+  for (const [key, stage] of [['requirementArtifactRef', 'prd_understanding'], ['technicalDesignArtifactRef', 'technical_design']]) {
+    const ref = documents[key];
+    if (!validRef(ref, [['stage', nonEmpty], ['artifact_revision', integer], ['content_digest', nonEmpty]])) throw new Error('规划来源绑定不匹配。');
+    if (ref.stage !== stage) throw new Error('规划来源绑定不匹配。');
+  }
+  const gate = documents.gate;
+  if (!gate || (gate.status !== 'not_decided' && (gate.status !== 'decided' || !positive(gate.gateRevision) || !['pass', 'blocked'].includes(gate.decision)))) {
+    throw new Error('规划文档的检查信息缺失或无效。');
+  }
+  const rendered = {};
+  for (const [key, type, filename] of [['executionDocumentMarkdown', 'execution_doc', 'execution.md'], ['acceptanceDocumentMarkdown', 'acceptance_doc', 'acceptance.md']]) {
+    const ref = documents[key === 'executionDocumentMarkdown' ? 'executionDocumentRef' : 'acceptanceDocumentRef'];
+    const markdown = documents[key];
+    if (!validRef(ref, [['document_type', nonEmpty], ['document_revision', integer], ['content_digest', nonEmpty]]) || ref.document_type !== type || !nonEmpty(markdown)) throw new Error('正式文档 Markdown 或其版本引用缺失，请更新规划服务后重试。');
+    rendered[filename] = markdown;
+  }
+  return rendered;
+}
+
+export function normalizeRepositoryIdentity(source) {
+  if (source.startsWith('/') || /^[A-Za-z]:[\\/]/u.test(source)) return undefined;
+  let protocol;
+  let host;
+  let port = '';
+  let path;
+  const scp = /^git@([A-Za-z0-9.-]+):([A-Za-z0-9._/-]+)$/u.exec(source);
+  if (scp) {
+    host = scp[1]; path = scp[2]; protocol = 'ssh';
+    if (path.includes('..')) return undefined;
+  } else {
+    if (!/^https:\/\//iu.test(source) && !/^ssh:\/\//iu.test(source)) return undefined;
+    const match = /^(https|ssh):\/\/([^/?#]+)(\/[^?#]*)$/iu.exec(source);
+    const rawPath = match?.[3];
+    if (!match || !rawPath || rawPath.includes('//') || rawPath.includes('\\') || /%2f/iu.test(rawPath) || rawPath.split('/').some(part => part === '.' || part === '..')) return undefined;
+    let url;
+    try { url = new URL(source); } catch { return undefined; }
+    if (!url.hostname || url.password || url.search || url.hash || (url.protocol === 'https:' && url.username) || (url.protocol === 'ssh:' && url.username && url.username !== 'git')) return undefined;
+    protocol = url.protocol === 'https:' ? 'https' : 'ssh'; host = url.hostname.toLowerCase(); port = url.port;
+    try { path = decodeURIComponent(rawPath.replace(/^\//u, '')); } catch { return undefined; }
+    if (!path || path.split('/').some(part => part === '.' || part === '..')) return undefined;
+  }
+  path = path.replace(/\/$/u, '').replace(/\.git$/u, '').replace(/\/$/u, '');
+  if (!path) return undefined;
+  const defaultPort = (protocol === 'https' && port === '443') || (protocol === 'ssh' && port === '22');
+  return !port || defaultPort ? `${host.toLowerCase()}/${path}` : `${protocol}://${host.toLowerCase()}:${port}/${path}`;
+}
+
+export async function assertFresh(api, state, outcome) {
+  if (outcome.status === 'awaiting_solution_review') {
+    const response = await api.post({ type: 'get_solution_review', requirementId: state.requirementId });
+    const current = response.data;
+    if (!current || current.type !== 'get_solution_review' || !current.review || !current.review.overview) throw new Error('服务返回的方案审阅信息无效。');
+    if (current.requirementId !== state.requirementId || current.snapshotRevision !== outcome.snapshotRevision || digest(current.review.sourceBinding) !== digest(outcome.solutionReview.sourceBinding) || current.review.reviewRevision !== outcome.solutionReview.reviewRevision || current.review.overview.markdown !== outcome.solutionReview.overview.markdown) {
+      throw new Error('方案已变化，请重新读取并请用户审阅；旧决定不能用于新方案。');
+    }
+  } else if (['ready_for_approval', 'awaiting_revision'].includes(outcome.status)) {
+    const current = (await api.post({ type: 'get_planning_candidate_documents', requirementId: state.requirementId })).data.documents;
+    validateDocuments(current, state.requirementId);
+    for (const key of ['snapshotRevision', 'candidateRevision', 'gate', 'requirementArtifactRef', 'technicalDesignArtifactRef', 'executionDocumentRef', 'acceptanceDocumentRef']) {
+      if (digest(current[key]) !== digest(outcome[key])) throw new Error('规划文档已变化，请重新读取并请用户审阅；旧决定不能用于新文档。');
+    }
+    for (const key of ['executionDocumentMarkdown', 'acceptanceDocumentMarkdown']) {
+      if (current[key] !== outcome[key]) throw new Error('规划文档正文已变化，请重新读取并请用户审阅；旧决定不能用于新文档。');
+    }
+  } else {
+    const report = (await api.post({ type: 'inspect_requirement', requirementId: state.requirementId })).data.report;
+    if (report?.requirementId !== state.requirementId || report.snapshotRevision !== outcome.snapshotRevision) throw new Error('待处理问题已变化，请重新读取后再回答。');
+  }
+}

package/skills/plan-with-remote/scripts/storage.mjs

@@ -0,0 +1,74 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, open, unlink } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+export const digest = value => `sha256:${createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex')}`;
+export const readJson = async path => JSON.parse(await readFile(path, 'utf8'));
+
+export async function saveSession(path, state) {
+  const temp = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  await rename(temp, path);
+}
+
+export async function createSession(output, state) {
+  const directory = resolve(output);
+  await mkdir(directory, { recursive: true });
+  const path = resolve(directory, 'session.json');
+  await writeFile(path, JSON.stringify(state, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  return path;
+}
+
+export async function loadSession(path) {
+  const state = await readJson(path);
+  if (state.version !== 1 || !state.requirementId || !state.baseUrl) throw new Error('任务文件无效。请使用脚本返回的 session 路径。');
+  return state;
+}
+
+export async function lockSession(path, work) {
+  const lock = `${path}.lock`;
+  try {
+    const handle = await open(lock, 'wx', 0o600);
+    await handle.writeFile(String(process.pid));
+    await handle.close();
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const pid = Number(await readFile(lock, 'utf8'));
+    if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('任务锁无法识别，请确认没有其他命令运行后清理锁文件。');
+    try { process.kill(pid, 0); }
+    catch (cause) {
+      if (cause.code === 'ESRCH') { await unlink(lock); return lockSession(path, work); }
+      throw cause;
+    }
+    throw new Error('此任务已有命令运行，请等待该命令结束。');
+  }
+  try { return await work(); }
+  finally { await unlink(lock); }
+}
+
+export async function writeReview(sessionPath, state, outcome, documents) {
+  const directory = resolve(dirname(sessionPath), `review-${randomUUID()}`);
+  await mkdir(directory);
+  const files = {};
+  const hashes = {};
+  for (const [name, text] of Object.entries(documents)) {
+    const path = resolve(directory, name);
+    await writeFile(path, text, { flag: 'wx' });
+    files[name] = path;
+    hashes[path] = digest(text);
+  }
+  const path = resolve(directory, 'review.json');
+  await writeFile(path, JSON.stringify({ version: 1, session: resolve(sessionPath), requirementId: state.requirementId, baseUrl: state.baseUrl, outcome, hashes }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  return { review: path, documents: files };
+}
+
+export async function loadReview(path) {
+  const review = await readJson(path);
+  if (review.version !== 1 || !review.session || !review.outcome || !review.hashes) throw new Error('审阅凭据无效，请重新读取文档。');
+  const state = await loadSession(review.session);
+  if (review.requirementId !== state.requirementId || review.baseUrl !== state.baseUrl) throw new Error('审阅凭据与任务不匹配。');
+  for (const [file, hash] of Object.entries(review.hashes)) {
+    if (digest(await readFile(file, 'utf8')) !== hash) throw new Error('审阅文档已被修改，请重新读取正式文档后再作决定。');
+  }
+  return review;
+}

package/skills/show-me/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: show-me
+description: Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
+disable-model-invocation: true
+---
+
+Help the user understand the current topic of conversation visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```
+
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, write one focused HTML file — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then open it for the user:
+
+```
+Bash(open path/to/show-me-{description}.html)
+```
+
+### guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/skills/show-me/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/statechart/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: statechart
+description: "Draw how any system moves between states, such as a product flow, a protocol, or a service, as a Mermaid statechart from a TLA+ model. Each bug is a numbered path with blue borders to a state that breaks a rule. Use for /statechart, to show a bug as a path through states, or to turn an agreed chart into a TLA+ skeleton."
+disable-model-invocation: true
+---
+
+# Statechart
+
+The chart shows how a system moves between states, in the words of the person who reads it. The scripts call that person the reader, as in `readerActions` and reader steps. The reader decides whether the behavior is right. The reader can be a PM who reads a product flow, an engineer who reads a protocol or a service, or a reviewer who reads a design. Label each state with what the reader can observe or cares about, such as "Paying" in an app or "Lease held, write pending" in a lock service. Label each step with the event that moves the system, such as "tap Pay" in an app, "the request reads the count" in a service, or "the lease expires" in a lock service. Keep variable and action names out of labels.
+
+Run `node <skill dir>/scripts/statechart.mjs --help` for the commands and for how to read a chart. Work in a scratch folder outside the repo. The command writes its files next to its input. The first run installs TLC and Java with mise, which downloads about 305 MB and needs the network. The help's TLC section tells how to use a TLC and Java that you have.
+
+## Pick the direction
+
+Use `from-spec` when a TLA+ model exists, or when the code or design is concrete enough to model. Use `from-chart` when there is no model, and the people who own the behavior should agree on it before anyone builds or changes it.
+
+If the code already has a TLA+ spec, start from a copy of that spec. Add the variables that the labels and rules need, and keep the spec's existing invariants. To audit the code against that spec, make the copy model what the code does, and pass the spec unchanged as `--against`. Check it with the config that its authors say it passes, and pass that config as `--against-config` unless it has the spec's file name. One mapping labels both models, so label states and steps from variables that both have. A label that reads a variable that only the copy has must test `"name" in v` first, and label the spec's states another way. When a model describes code, tie every variable and action to code that a reviewer can open, and take its name from that code. Make each action one indivisible step in the code. Put the file and line of the code that checks each condition of an action in a comment on that condition, as in `\* pay.ts:120`.
+
+## Spec to chart
+
+1. Choose the chart's states. When the reader cares about something that a label would hide, put it in the label, such as "Paying, charged twice" when the screen still says "Paying" after a second charge. Start with few states. Split a state when the split separates two bugs, or when the reader must see a step that leaves the label the same, such as a request that reads a count, because the chart does not draw such a step.
+2. Write each rule that the reader agrees to as one invariant, with the reader's sentence as its comment. A rule can be about any state in the model: what a screen shows, what a request returns, a stored value, or a message between parts. When the model describes code, the rule also names the code that can change that state. If the model has no variable for what a rule is about, add the variable. Do not drop the rule. For a rule that applies once everything settles, define `Settled == ~ENABLED System`, where `System` is the disjunction of the actions that happen without the reader. For a rule that applies at a narrower point, such as after each request finishes, write a predicate for that point and make the rule hold where it is true. For a goal that the system must be able to reach, write a rule that says the goal never happens, and pass that rule with `--expect-broken`. The path that breaks it is then a way to the goal. The chart still draws the goal as a state that breaks a rule, and `stories.md` tells it as a bug, so name each goal rule in the hand-off. Report each other broken rule as a bug. Never weaken a rule to make the chart pass.
+3. Run `from-spec`, then fill in the mapping file it writes. Put the labels in `state` and `step`. When the chart must separate what the reader does from what happens around the reader, list the reader's actions in `readerActions` by action name. Leave the list empty when every action counts the same. When the overview is too large to read, add `--cover`. The overview then keeps only the shortest path to each settled state, plus every bug path, and the command lists what it leaves out. When two bugs end in the same state for different reasons, add `cause` and make it name each reason. To color the states by what the reader cares about, such as "Order shipped", return that group from `group`. The legend names the groups, and in the PNG a state that breaks a rule is red in place of its group color.
+4. If there is a proposed fix, model it and pass that model as `--fixed`.
+5. Render each chart with `--png` and look at every PNG. Check that each numbered path reads in order. If a label reads like code, fix `state` or `step` and run the command again.
+6. When the model describes code, replay each bug's story against the real code, as a test or a live repro, one step per model action. Drive only entry points that a user, a client, or another part of the system reaches, and assert only what they can observe. A test that asserts a flag that it sets, or that searches the source text, proves nothing. When a run proves part of the story and reading the code proves the rest, say which part each proves. When the test copies code that it cannot import, give the commit and line range of the copy, and list what the copy leaves out. If a bug does not reproduce, assume the model is wrong until you show otherwise. Fix the model, not the rule. For a design with no code yet, the TLC trace is the evidence, and the hand-off must say so.
+
+## Chart to spec
+
+1. Draw the chart that the reader agrees to. Use one region for each part that changes independently, such as a device's connection and the job that the device runs. Add one `%% never` line per rule, with the reader's sentence. Draw an event that stops or restarts a part, such as "the app closes" or "the process restarts", as an edge to the state that comes next. Run `render CHART.mmd` to get a PNG of the chart for the reader.
+2. Run `from-chart`. If a rule breaks, the agreed chart has a design bug. Take the bug to the people who agreed to the chart.
+3. Add the real code's guards and variables to the spec that `from-chart` wrote, and run `from-chart` again. For each difference it prints, ask the reader whether the code is wrong or the chart needs a correction.
+
+## Hand off
+
+Give the PNG and the Mermaid source of each chart to the person who must decide. Add one line per bug with the rule it breaks, its steps as the chart numbers them, whether it reproduced, and whether the proposed fix fixes it. A broken PROPERTY has no path on the chart, so give the TLC counterexample that `stories.md` names for it. With `--against`, also say whether the spec already lists it: in the configs that `stories.md` names, in the spec's notes on what the model leaves out, or not at all. When the model describes code, do not report that a rule holds while the command lists conditions with no file and line. Take every count you quote from `summary.json`. Attach `stories.md` and the command that regenerates everything. Say what the model leaves out.

package/skills/statechart/scripts/bug-states.mjs

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import { BROKEN_MARK, parseValue, stateKey } from "./lib.mjs";
+import { SEP } from "./chart-parts.mjs";
+
+export function firstBad(raw) {
+  const badStates = new Map();
+  for (const t of raw) {
+    if (!badStates.has(t.invariant)) badStates.set(t.invariant, new Set());
+    badStates.get(t.invariant).add(stateKey(t.steps[t.steps.length - 1].vars));
+  }
+  const cuts = [];
+  const seen = new Set();
+  for (const t of raw) {
+    const first = t.steps.findIndex((s) => badStates.get(t.invariant).has(stateKey(s.vars)));
+    const cut = { invariant: t.invariant, steps: t.steps.slice(0, first + 1) };
+    const id = `${t.invariant}${SEP}${stateKey(cut.steps[cut.steps.length - 1].vars)}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    cuts.push(cut);
+  }
+  return cuts;
+}
+
+export const byOrder = (a, b) =>
+  a.steps - b.steps ||
+  a.trace.steps.length - b.trace.steps.length ||
+  (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+const lastKey = (t) => stateKey(t.steps[t.steps.length - 1].vars);
+export const badOf = (raw, rule) => new Set(raw.filter((t) => t.invariant === rule).map(lastKey));
+export function reachableAvoiding({ graph: g, stateKeys }, bad) {
+  const ok = (id) => !bad.has(stateKeys.get(id));
+  const next = new Map();
+  for (const e of g.edges) {
+    if (!next.has(e.from)) next.set(e.from, []);
+    next.get(e.from).push(e.to);
+  }
+  const clean = new Set([...g.nodes.values()].filter((n) => n.init && ok(n.id)).map((n) => n.id));
+  for (const id of clean) for (const to of next.get(id) ?? []) if (ok(to)) clean.add(to);
+  return clean;
+}
+
+export const diverges = (c) => c.second?.key !== undefined;
+export function readBroken(file) {
+  if (!file) return [];
+  const lines = fs.readFileSync(file, "utf8").split("\n");
+  const marked = new RegExp(`^<<\\s*"${BROKEN_MARK}",`);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!marked.test(lines[i])) continue;
+    let text = lines[i];
+    while (typeof parseValue(text) === "string" && i + 1 < lines.length) text += `\n${lines[++i]}`;
+    const [, vars, broken] = parseValue(text);
+    out.push({ key: stateKey(vars), rules: broken });
+  }
+  return out;
+}
+export const badStates = (raw, broken, counts = () => true) =>
+  new Set([
+    ...raw.filter((t) => counts(t.invariant)).map(lastKey),
+    ...broken.filter((b) => b.rules.some(counts)).map((b) => b.key),
+  ]);
+export function labelStatus(m, keys, bad) {
+  const good = reachableAvoiding(m, bad);
+  const kinds = new Map();
+  for (const n of m.graph.nodes.values()) {
+    const k = keys.get(n.id);
+    if (!kinds.has(k)) kinds.set(k, new Set());
+    kinds.get(k).add(bad.has(m.stateKeys.get(n.id)) ? "bad" : good.has(n.id) ? "good" : "after");
+  }
+  return (k) => {
+    const has = kinds.get(k);
+    if (!has) return undefined;
+    if (has.has("bad")) return has.has("good") ? "mixed" : "wrong";
+    return has.has("good") ? "works" : "after";
+  };
+}
+
+export const RANK = ["works", "fixed", "after", "mixed", "wrong", "worse"];
+export const worst = (...all) =>
+  all.filter(Boolean).reduce((a, b) => (RANK.indexOf(b) > RANK.indexOf(a) ? b : a), "works");