oh-my-llmwikimode 1.6.0 → 1.7.0

package/docs/KNOWLEDGE_FOLDER_TAXONOMY.md

@@ -25,7 +25,7 @@ Example:
 | Current folder | Canonical label | Purpose |
 | --- | --- | --- |
 | `!대시보드` | `!대시보드_dashboard` | User-facing entry point and daily summary |
-| `0_omx 핸드오프` | `0_omx-핸드오프_omx-handoff` | OMX / Codex handoff plans and run instructions |
+| `0_omx 핸드오프` | `0_omw-handoff_omw-handoff` | OMW / Codex handoff plans and run instructions; old OMX folder names remain legacy readable inputs |
 | `개발-진행-기록` | `개발-진행-기록_dev-history` | Work logs, roadmap updates, implementation and release history |
 | `개발-진행-기록/로드맵` | `개발-진행-기록_dev-history/로드맵_roadmap` | Roadmaps and planning timeline |
 | `개발-진행-기록/구현-보고` | `개발-진행-기록_dev-history/구현-보고_implementation-reports` | Implementation reports |

package/docs/KNOWLEDGE_UX_DASHBOARD_CONTRACT.md

@@ -22,7 +22,7 @@ Snapshot source: local wiki root `C:\Users\USER\Documents\llm-wiki`.
 - Markdown entries under the project area: about 177
 - Current top-level project folders:
   - `!대시보드`
-  - `0_omx 핸드오프`
+  - `0_omx 핸드오프` (legacy readable input; new handoff output uses `0_omw-handoff_omw-handoff`)
   - `가이드-및-정책`
   - `개발-진행-기록`
   - `아카이브`

package/docs/design/EOS_DESIGN.md

@@ -372,3 +372,36 @@ Verification anchors:
 - `test/eos/timeline-status-panel.test.js`
 - `test/eos/approval-inspector-gate.test.js`
 - `npm run verify:eos-approval-inspector`
+
+## Implemented EOS Approval Handoff Workbench Slice - 2026-06-02
+
+The EOS Approval Handoff Workbench slice adds the first safe step after an
+approval request reaches `approved_not_executed`.
+
+What changed:
+
+- EOS can create a local review-required handoff package under
+  `.system/eos/approval/handoffs/`.
+- Handoff package audit records are appended to
+  `.system/eos/approval/handoff-audit.jsonl`.
+- The source approval request transitions to `handoff_prepared` only after the
+  package artifact exists.
+- `GET /api/home` includes a Handoff Queue summary.
+- `GET /api/workspace/artifacts/inspect?type=approval_handoff&id=<id>` exposes
+  a redacted, whitelisted package inspector view.
+- `/workspace/` renders Handoff Queue and package inspection controls using
+  package/review language.
+
+Boundary:
+
+- Handoff packages are human review packages, not external-worker dispatches.
+- This slice does not add shell, git, provider, Discord, worker, queue,
+  source-wiki mutation, hosted sync, auto-merge/delete/push/publish, or hidden
+  execution behavior.
+
+Verification anchors:
+
+- `test/eos/approval-handoff-artifacts.test.js`
+- `test/eos/approval-handoff-routes.test.js`
+- `test/eos/workspace-home-routes.test.js`
+- `npm run verify:eos-approval-handoff`

package/docs/eos-approval-handoff-workbench.md

@@ -0,0 +1,76 @@
+# EOS Approval Handoff Workbench
+
+Status: implemented local product slice.
+
+## What It Does
+
+EOS can prepare a local handoff package from an approval request that is already
+`approved_not_executed`.
+
+The package is written under:
+
+```text
+.system/eos/approval/handoffs/
+```
+
+Audit records are appended under:
+
+```text
+.system/eos/approval/handoff-audit.jsonl
+```
+
+The source approval request is updated to `handoff_prepared` only after the
+handoff package artifact exists.
+
+## Browser Surface
+
+Open the local daemon and visit:
+
+```text
+http://127.0.0.1:4825/workspace/
+```
+
+The Workspace shows:
+
+- Approval Queue
+- Handoff Queue
+- Artifact Inspector
+- Lifecycle Timeline
+- Local Only / Review Required / Not Applied safety labels
+
+## API Surface
+
+Create a package from a local approved request:
+
+```text
+POST /api/workspace/approval-handoffs
+```
+
+Inspect a package:
+
+```text
+GET /api/workspace/artifacts/inspect?type=approval_handoff&id=<id>
+```
+
+Read current queues through Home:
+
+```text
+GET /api/home
+```
+
+## Safety Boundary
+
+Handoff packages are review-required local artifacts only.
+
+This slice does not execute shell, git, providers, Discord, external workers,
+queues, wiki source mutation, merge, publish, push, hosted sync, or hidden
+agents. It also does not reuse external-worker dispatch as the primary model.
+
+## Verification
+
+```text
+npm run verify:eos-approval-handoff
+npm run test:eos
+npm run verify:eos-boundary-policy
+npm run verify:eos-boundary
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-llmwikimode",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "LLM Wiki plugin for OpenCode ??auto-memory, retrieval, and knowledge promotion",
   "type": "module",
   "main": "./src/server.js",
@@ -31,6 +31,7 @@
     "verify:eos-workspace-product": "npm run test:eos && npm run verify:eos-boundary-policy && npm run verify:eos-boundary && npm run eos:a11y-snapshot -- --json",
     "verify:eos-workspace-completion": "node scripts/verify-eos-workspace-completion.js",
     "verify:eos-approval-inspector": "node scripts/verify-eos-approval-inspector.js",
+    "verify:eos-approval-handoff": "node scripts/verify-eos-approval-handoff.js",
     "verify:package": "node test/verify-package.test.js",
     "verify:docs": "node test/verify-docs.test.js",
     "verify:side-effects": "node scripts/side-effect-audit.js",

package/src/eos/approval/handoff-contract.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export const HANDOFF_PACKAGE_TYPE = "eos_approval_handoff_package";
+export const HANDOFF_PACKAGE_STATUS = "review_required";
+export const HANDOFF_PACKAGE_INTENTS = Object.freeze(["human_handoff"]);
+export const HANDOFF_AUDIT_ACTIONS = Object.freeze([
+  "handoff_package_requested",
+  "handoff_package_prepared",
+  "reject_handoff_package",
+]);
+
+const SENSITIVE_RE = /\b(token|password|api[_-]?key|authorization)\s*[:=]\s*([^\s,;]+)/gi;
+const API_KEY_RE = /\bsk-(?:proj-)?[A-Za-z0-9_-]{8,}\b/g;
+const WINDOWS_USER_HOME_RE = /[a-z]:\\users\\[^\\/\s]+\\[^\s"'`)]*/gi;
+const UNIX_USER_HOME_RE = /(?:\/users|\/home)\/[^/\s"'`)]+(?:\/[^\s"'`)]+)*/gi;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function shortHash(value) {
+  return createHash("sha256").update(stableJson(value)).digest("hex").slice(0, 12);
+}
+
+export function iso(value) {
+  return (value instanceof Date ? value : new Date(value || Date.now())).toISOString();
+}
+
+export function safeHandoffId(value, fallback = "handoff") {
+  return String(value || fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || fallback;
+}
+
+export function isSafeHandoffId(value) {
+  return typeof value === "string" && /^[a-z0-9][a-z0-9_-]{0,159}$/.test(value);
+}
+
+export function sanitizeHandoffValue(value) {
+  if (typeof value === "string") return sanitizeString(value);
+  if (Array.isArray(value)) return value.map((item) => sanitizeHandoffValue(item));
+  if (isRecord(value)) {
+    const output = {};
+    for (const [key, item] of Object.entries(value)) output[key] = sanitizeHandoffValue(item);
+    return output;
+  }
+  return value;
+}
+
+export function relativeHandoffPath(id) {
+  return path.posix.join(".system", "eos", "approval", "handoffs", `${id}.json`);
+}
+
+export function validateHandoffRequest(input = {}) {
+  const errors = [];
+  const sourceApprovalRequestId = typeof input.source_approval_request_id === "string"
+    ? input.source_approval_request_id.trim()
+    : typeof input.sourceApprovalRequestId === "string"
+    ? input.sourceApprovalRequestId.trim()
+    : "";
+  const packageIntent = typeof input.package_intent === "string" && input.package_intent.trim()
+    ? input.package_intent.trim()
+    : typeof input.packageIntent === "string" && input.packageIntent.trim()
+    ? input.packageIntent.trim()
+    : "human_handoff";
+
+  if (!sourceApprovalRequestId) errors.push("source_approval_request_id is required");
+  if (!isSafeHandoffId(sourceApprovalRequestId)) errors.push("source_approval_request_id must be a safe artifact id");
+  if (!HANDOFF_PACKAGE_INTENTS.includes(packageIntent)) errors.push("package_intent is not supported");
+
+  if (errors.length > 0) return Object.freeze({ valid: false, errors: Object.freeze(errors) });
+  return Object.freeze({
+    valid: true,
+    value: Object.freeze({
+      source_approval_request_id: sourceApprovalRequestId,
+      package_intent: packageIntent,
+    }),
+  });
+}
+
+export function createHandoffPackageArtifact(approvalRequest, request, options = {}) {
+  const seed = {
+    source_approval_request_id: approvalRequest.id,
+    source_approval_artifact_path: approvalRequest.artifact_path,
+    package_intent: request.package_intent,
+  };
+  const id = `handoff-${safeHandoffId(approvalRequest.id)}-${safeHandoffId(request.package_intent)}-${shortHash(seed)}`;
+  const artifactPath = relativeHandoffPath(id);
+  const now = iso(options.now);
+  const evidenceManifest = Array.from(new Set([
+    approvalRequest.artifact_path,
+    approvalRequest.source_artifact_path,
+    approvalRequest.source_path,
+    ...(Array.isArray(approvalRequest.evidence) ? approvalRequest.evidence : []),
+  ].filter(Boolean))).map((item) => sanitizeString(String(item)));
+  const timelineSummary = Object.freeze([
+    `approval_request:${approvalRequest.status}`,
+    `handoff_package:${HANDOFF_PACKAGE_STATUS}`,
+  ]);
+  const handoffPrompt = [
+    "Review this local EOS handoff package.",
+    `Source approval request: ${approvalRequest.id}`,
+    `Requested action: ${approvalRequest.requested_action || "prepare_handoff"}`,
+    "This package is review-required and not applied.",
+    "Do not execute shell, git, providers, Discord, workers, wiki mutation, merge, publish, or push from this artifact.",
+  ].join("\n");
+
+  const artifact = Object.freeze({
+    schema_version: 1,
+    type: HANDOFF_PACKAGE_TYPE,
+    id,
+    status: HANDOFF_PACKAGE_STATUS,
+    package_intent: request.package_intent,
+    source_approval_request_id: approvalRequest.id,
+    source_approval_artifact_path: approvalRequest.artifact_path,
+    source_decision_id: approvalRequest.source_decision_id || "",
+    source_artifact_path: approvalRequest.source_artifact_path || "",
+    requested_action: approvalRequest.requested_action || "prepare_handoff",
+    reason: sanitizeString(approvalRequest.reason || ""),
+    evidence_manifest: Object.freeze(evidenceManifest),
+    timeline_summary: timelineSummary,
+    human_checklist: Object.freeze([
+      "Inspect the source approval request and evidence manifest.",
+      "Confirm the handoff prompt matches the approved intent.",
+      "Keep this package local and review-required until a separate execution contract exists.",
+    ]),
+    handoff_prompt: sanitizeString(handoffPrompt),
+    safety_flags: Object.freeze({
+      review_required: true,
+      local_only: true,
+      executed: false,
+      live_execution: false,
+      source_entry_mutated: false,
+    }),
+    boundaries: Object.freeze({
+      no_hidden_execution: true,
+      no_source_mutation: true,
+      external_worker_dispatch: false,
+      shell_execution: false,
+      git_mutation: false,
+      provider_call: false,
+      discord_runtime: false,
+      auto_apply: false,
+      auto_promote: false,
+      auto_merge: false,
+      auto_delete: false,
+      auto_push: false,
+      auto_publish: false,
+      hosted_sync: false,
+    }),
+    created_at: now,
+    updated_at: now,
+    artifact_path: artifactPath,
+  });
+
+  return Object.freeze({
+    artifactPath,
+    artifact,
+    auditEntry: createHandoffAuditEntry("handoff_package_prepared", request, options, {
+      packageId: id,
+      artifactPath,
+      sourceApprovalRequestId: approvalRequest.id,
+    }),
+  });
+}
+
+export function createHandoffAuditEntry(action, request = {}, options = {}, refs = {}) {
+  return Object.freeze({
+    schema_version: 1,
+    action,
+    recorded_at: iso(options.now),
+    actor: options.actor || "eos-approval-handoff",
+    package_id: refs.packageId || null,
+    artifact_path: refs.artifactPath || null,
+    source_approval_request_id: refs.sourceApprovalRequestId || request.source_approval_request_id || "",
+    package_intent: request.package_intent || "human_handoff",
+    executed: false,
+    live_execution: false,
+    source_entry_mutated: false,
+  });
+}
+
+function sanitizeString(value) {
+  return String(value || "")
+    .replace(SENSITIVE_RE, "$1=[REDACTED]")
+    .replace(API_KEY_RE, "[REDACTED]")
+    .replace(WINDOWS_USER_HOME_RE, "[REDACTED_PATH]")
+    .replace(UNIX_USER_HOME_RE, "[REDACTED_PATH]");
+}

package/src/eos/approval/handoff-read-model.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { HANDOFF_PACKAGE_TYPE } from "./handoff-contract.js";
+
+function zeroCounts() {
+  return { review_required: 0 };
+}
+
+function toHandoffSummary(artifact) {
+  return Object.freeze({
+    id: artifact.id,
+    status: artifact.status,
+    package_intent: artifact.package_intent,
+    source_approval_request_id: artifact.source_approval_request_id,
+    source_approval_artifact_path: artifact.source_approval_artifact_path,
+    requested_action: artifact.requested_action,
+    artifact_path: artifact.artifact_path,
+    created_at: artifact.created_at || null,
+    safety_flags: artifact.safety_flags || {},
+    review_required: artifact.status === "review_required",
+  });
+}
+
+export function summarizeApprovalHandoffQueue(wikiRoot, options = {}) {
+  const counts = zeroCounts();
+  const recent = [];
+  const loadErrors = [];
+  const handoffsDir = path.join(wikiRoot, ".system", "eos", "approval", "handoffs");
+  let entries;
+
+  try {
+    entries = fs.readdirSync(handoffsDir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return emptyHandoffQueue(counts);
+    throw error;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    try {
+      const artifact = JSON.parse(fs.readFileSync(path.join(handoffsDir, entry.name), "utf-8"));
+      if (artifact?.type !== HANDOFF_PACKAGE_TYPE || artifact.status !== "review_required") continue;
+      counts.review_required += 1;
+      recent.push(toHandoffSummary(artifact));
+    } catch (error) {
+      loadErrors.push({
+        path: path.posix.join(".system", "eos", "approval", "handoffs", entry.name),
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  recent.sort((left, right) => {
+    return String(right.created_at || "").localeCompare(String(left.created_at || "")) ||
+      String(left.id).localeCompare(String(right.id));
+  });
+
+  return Object.freeze({
+    counts: Object.freeze(counts),
+    total: recent.length,
+    recent: Object.freeze(recent.slice(0, options.limit || 5)),
+    load_errors: Object.freeze(loadErrors),
+    review_required: counts.review_required,
+    local_only: true,
+    prepare_only: true,
+  });
+}
+
+function emptyHandoffQueue(counts) {
+  return Object.freeze({
+    counts: Object.freeze(counts),
+    total: 0,
+    recent: Object.freeze([]),
+    load_errors: Object.freeze([]),
+    review_required: 0,
+    local_only: true,
+    prepare_only: true,
+  });
+}

package/src/eos/approval/handoffs.js

@@ -0,0 +1,245 @@
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { APPROVAL_REQUEST_STATUSES, getApprovalArtifactPaths } from "./artifacts.js";
+import {
+  HANDOFF_AUDIT_ACTIONS,
+  HANDOFF_PACKAGE_TYPE,
+  createHandoffAuditEntry,
+  createHandoffPackageArtifact,
+  isSafeHandoffId,
+  sanitizeHandoffValue,
+  validateHandoffRequest,
+} from "./handoff-contract.js";
+
+export { HANDOFF_PACKAGE_TYPE } from "./handoff-contract.js";
+
+export function getApprovalHandoffArtifactPaths(wikiRoot) {
+  const root = path.join(wikiRoot, ".system", "eos", "approval");
+  return Object.freeze({
+    root,
+    handoffs: path.join(root, "handoffs"),
+    auditFile: path.join(root, "handoff-audit.jsonl"),
+  });
+}
+
+export async function ensureApprovalHandoffArtifactStructure(wikiRoot) {
+  const paths = getApprovalHandoffArtifactPaths(wikiRoot);
+  await mkdir(paths.handoffs, { recursive: true });
+  return paths;
+}
+
+export async function prepareApprovalHandoffPackage(wikiRoot, input = {}, options = {}) {
+  if (!wikiRoot || typeof wikiRoot !== "string") {
+    throw new Error("wikiRoot is required for Eos approval handoff artifacts");
+  }
+
+  const validation = validateHandoffRequest(input);
+  if (!validation.valid) {
+    await appendHandoffAudit(wikiRoot, "reject_handoff_package", input, options);
+    return rejected(validation.errors.join("; "));
+  }
+
+  const request = validation.value;
+  const source = await readApprovalRequestById(wikiRoot, request.source_approval_request_id);
+  if (!source.success) {
+    await appendHandoffAudit(wikiRoot, "reject_handoff_package", request, options);
+    return rejected(source.error);
+  }
+  const prepared = createHandoffPackageArtifact(source.artifact, request, options);
+  const resolvedPackagePath = resolveHandoffArtifactPath(wikiRoot, prepared.artifactPath);
+  const existing = await readExistingJson(resolvedPackagePath);
+  if (existing.exists && source.artifact.status === "handoff_prepared") {
+    return Object.freeze({
+      success: true,
+      duplicate: true,
+      package: existing.value,
+      artifactPath: existing.value.artifact_path || prepared.artifactPath,
+      executed: false,
+      sourceEntryMutated: false,
+    });
+  }
+  if (source.artifact.status !== "approved_not_executed") {
+    await appendHandoffAudit(wikiRoot, "reject_handoff_package", request, options);
+    return rejected("handoff packages require approved_not_executed approval requests");
+  }
+
+  if (existing.exists) {
+    await markApprovalRequestHandoffPrepared(wikiRoot, source.artifact, existing.value.artifact_path || prepared.artifactPath, options);
+    return Object.freeze({
+      success: true,
+      duplicate: true,
+      package: existing.value,
+      artifactPath: existing.value.artifact_path || prepared.artifactPath,
+      executed: false,
+      sourceEntryMutated: false,
+    });
+  }
+
+  await ensureApprovalHandoffArtifactStructure(wikiRoot);
+  await appendHandoffAudit(wikiRoot, "handoff_package_requested", request, options);
+  await writeFile(resolvedPackagePath, `${JSON.stringify(prepared.artifact, null, 2)}\n`, {
+    encoding: "utf-8",
+    flag: "wx",
+  });
+  await appendHandoffAuditEntry(wikiRoot, prepared.auditEntry);
+  await markApprovalRequestHandoffPrepared(wikiRoot, source.artifact, prepared.artifactPath, options);
+
+  return Object.freeze({
+    success: true,
+    duplicate: false,
+    package: prepared.artifact,
+    artifactPath: prepared.artifactPath,
+    audit: prepared.auditEntry,
+    auditPath: ".system/eos/approval/handoff-audit.jsonl",
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}
+
+export async function readApprovalHandoffPackages(wikiRoot) {
+  const paths = getApprovalHandoffArtifactPaths(wikiRoot);
+  const packages = [];
+  const load_errors = [];
+  try {
+    const entries = await readdir(paths.handoffs, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const filePath = path.join(paths.handoffs, entry.name);
+      try {
+        const artifact = JSON.parse(await readFile(filePath, "utf-8"));
+        if (artifact?.type === HANDOFF_PACKAGE_TYPE && artifact.status === "review_required") {
+          packages.push(sanitizeHandoffValue(artifact));
+        }
+      } catch (error) {
+        load_errors.push({
+          path: path.posix.join(".system", "eos", "approval", "handoffs", entry.name),
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return Object.freeze({
+    paths,
+    packages: Object.freeze(packages.sort(sortRecent)),
+    load_errors: Object.freeze(load_errors),
+    summary: Object.freeze({ packages: packages.length, load_errors: load_errors.length }),
+  });
+}
+
+async function readApprovalRequestById(wikiRoot, id) {
+  if (!isSafeHandoffId(id)) return { success: false, error: "source_approval_request_id must be safe" };
+  const artifactPath = path.posix.join(".system", "eos", "approval", "requests", `${id}.json`);
+  const filePath = resolveApprovalRequestPath(wikiRoot, artifactPath);
+  let artifact;
+  try {
+    artifact = JSON.parse(await readFile(filePath, "utf-8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return { success: false, error: `Unknown approval request: ${id}` };
+    return { success: false, error: "Approval request could not be read" };
+  }
+  if (artifact?.type !== "eos_approval_request" || !APPROVAL_REQUEST_STATUSES.includes(artifact.status)) {
+    return { success: false, error: "Approval request is not valid" };
+  }
+  return { success: true, artifact: sanitizeHandoffValue(artifact), filePath };
+}
+
+async function markApprovalRequestHandoffPrepared(wikiRoot, approvalRequest, packagePath, options = {}) {
+  const artifactPath = approvalRequest.artifact_path || path.posix.join(".system", "eos", "approval", "requests", `${approvalRequest.id}.json`);
+  const filePath = resolveApprovalRequestPath(wikiRoot, artifactPath);
+  const current = JSON.parse(await readFile(filePath, "utf-8"));
+  if (current.status === "handoff_prepared") return;
+  const updated = {
+    ...current,
+    status: "handoff_prepared",
+    handoff_package_artifact_path: packagePath,
+    safety_flags: {
+      ...(current.safety_flags || {}),
+      review_required: true,
+      approved_not_executed: true,
+      executed: false,
+      source_entry_mutated: false,
+    },
+    updated_at: new Date(options.now || Date.now()).toISOString(),
+  };
+  await writeFile(filePath, `${JSON.stringify(updated, null, 2)}\n`, "utf-8");
+  await appendApprovalAudit(wikiRoot, {
+    schema_version: 1,
+    action: "handoff_prepared",
+    recorded_at: new Date(options.now || Date.now()).toISOString(),
+    actor: options.actor || "eos-approval-handoff",
+    request_id: current.id,
+    artifact_path: artifactPath,
+    handoff_package_artifact_path: packagePath,
+    source_decision_id: current.source_decision_id || "",
+    requested_action: current.requested_action || "",
+    executed: false,
+    live_execution: false,
+    source_entry_mutated: false,
+  });
+}
+
+async function appendApprovalAudit(wikiRoot, entry) {
+  const paths = getApprovalArtifactPaths(wikiRoot);
+  await mkdir(paths.requests, { recursive: true });
+  await appendFile(paths.auditFile, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+
+async function appendHandoffAudit(wikiRoot, action, request = {}, options = {}) {
+  return appendHandoffAuditEntry(wikiRoot, createHandoffAuditEntry(action, request, options));
+}
+
+async function appendHandoffAuditEntry(wikiRoot, entry) {
+  if (!HANDOFF_AUDIT_ACTIONS.includes(entry.action)) {
+    throw new Error(`Unsupported Eos approval handoff audit action: ${entry.action}`);
+  }
+  const paths = await ensureApprovalHandoffArtifactStructure(wikiRoot);
+  await appendFile(paths.auditFile, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+
+async function readExistingJson(filePath) {
+  try {
+    return Object.freeze({ exists: true, value: JSON.parse(await readFile(filePath, "utf-8")) });
+  } catch (error) {
+    if (error?.code === "ENOENT") return Object.freeze({ exists: false, value: null });
+    throw error;
+  }
+}
+
+function resolveApprovalRequestPath(wikiRoot, relativePath) {
+  return resolveUnderDirectory(wikiRoot, relativePath, path.join(wikiRoot, ".system", "eos", "approval", "requests"));
+}
+
+function resolveHandoffArtifactPath(wikiRoot, relativePath) {
+  return resolveUnderDirectory(wikiRoot, relativePath, path.join(wikiRoot, ".system", "eos", "approval", "handoffs"));
+}
+
+function resolveUnderDirectory(wikiRoot, relativePath, allowedDirectory) {
+  const root = path.resolve(wikiRoot);
+  const target = path.resolve(root, ...String(relativePath).split("/"));
+  const relativeRoot = path.relative(root, target);
+  if (!relativeRoot || relativeRoot.startsWith("..") || path.isAbsolute(relativeRoot)) {
+    throw new Error("Eos approval handoff path escapes wiki root");
+  }
+  const relativeAllowed = path.relative(path.resolve(allowedDirectory), target);
+  if (!relativeAllowed || relativeAllowed.startsWith("..") || path.isAbsolute(relativeAllowed)) {
+    throw new Error("Eos approval handoff path escapes allowed directory");
+  }
+  return target;
+}
+
+function sortRecent(left, right) {
+  return String(right.created_at || "").localeCompare(String(left.created_at || "")) ||
+    String(left.id).localeCompare(String(right.id));
+}
+
+function rejected(error) {
+  return Object.freeze({
+    success: false,
+    error,
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}

package/src/eos/artifact-inspector/view-model.js

@@ -25,6 +25,11 @@ const ARTIFACT_TYPES = Object.freeze({
     relativePath: (id) => `.system/eos/approval/requests/${id}.json`,
     format: "json",
   }),
+  approval_handoff: Object.freeze({
+    title: "Approval Handoff Package",
+    relativePath: (id) => `.system/eos/approval/handoffs/${id}.json`,
+    format: "json",
+  }),
   visual_qa: Object.freeze({
     title: "Visual QA Artifact",
     relativePath: (id) => `.system/eos/visual-qa/${id}.json`,

package/src/eos/home-review-queue.js

@@ -5,6 +5,7 @@ import {
   buildLlmWikiCuratorBrowserData,
   buildLlmWikiGraphReasoningBrowserData,
 } from "../llmwiki/eos-adapter.js";
+import { summarizeApprovalHandoffQueue } from "./approval/handoff-read-model.js";
 import { summarizeApprovalQueue } from "./approval/read-model.js";
 import { classifyChatIntent } from "./chat/intent-hints.js";
 
@@ -23,6 +24,7 @@ export function buildReviewQueue(wikiRoot) {
   const chatRequests = summarizeChatRequestsForHome(wikiRoot);
   const sideReviewDecisions = summarizeSideReviewDecisionsForHome(wikiRoot);
   const approvalQueue = summarizeApprovalQueue(wikiRoot);
+  const approvalHandoffQueue = summarizeApprovalHandoffQueue(wikiRoot);
 
   return {
     curator_queue_count: curatorQueueCount,
@@ -41,13 +43,19 @@ export function buildReviewQueue(wikiRoot) {
     approval_request_recent: approvalQueue.recent,
     approval_request_load_errors: approvalQueue.load_errors,
     approval_queue: approvalQueue,
+    approval_handoff_count: approvalHandoffQueue.total,
+    approval_handoff_counts: approvalHandoffQueue.counts,
+    approval_handoff_recent: approvalHandoffQueue.recent,
+    approval_handoff_load_errors: approvalHandoffQueue.load_errors,
+    approval_handoff_queue: approvalHandoffQueue,
     total_review_required: curatorQueueCount
       + curatorProposalCount
       + graphQueueCardCount
       + graphInsightCount
       + chatRequests.total
       + sideReviewDecisions.total
-      + approvalQueue.review_required,
+      + approvalQueue.review_required
+      + approvalHandoffQueue.review_required,
   };
 }
 

package/src/eos/home-workspace.js

@@ -36,16 +36,19 @@ export function buildWorkspaceHome() {
     primary_surface: "chat_capture",
     companion_surface: "side_review",
     approval_surface: "approval_queue",
+    handoff_surface: "handoff_queue",
     capture_endpoint: "/api/chat/requests",
     home_endpoint: "/api/home",
     side_review_endpoint: "/api/side-review",
     approval_queue_endpoint: "/api/home",
+    approval_handoff_endpoint: "/api/workspace/approval-handoffs",
     safe_copy: {
       primary: "Chat-first capture",
       safety: "Local Only / Review Required / Not Applied",
       capture: "Capture for Review",
       review: "Open Side Review",
       approval: "Open Approval Queue",
+      handoff: "Prepare Handoff Package",
     },
     nav: [
       {
@@ -66,6 +69,12 @@ export function buildWorkspaceHome() {
         href: "/workspace/",
         target: "approval_queue",
       },
+      {
+        id: "handoff-queue",
+        label: "Handoff Queue",
+        href: "/workspace/",
+        target: "handoff_queue",
+      },
     ],
     forbidden_capabilities: [
       "hidden_execution",

package/src/eos/home.js

@@ -35,7 +35,7 @@ function buildDraftPressure(stats) {
 }
 
 function buildCommandCenterHealth(reviewQueue, librarian) {
-  const loadErrorCount = safeCount(reviewQueue.chat_request_load_errors?.length) + safeCount(reviewQueue.side_review_decision_load_errors?.length) + safeCount(reviewQueue.approval_request_load_errors?.length);
+  const loadErrorCount = safeCount(reviewQueue.chat_request_load_errors?.length) + safeCount(reviewQueue.side_review_decision_load_errors?.length) + safeCount(reviewQueue.approval_request_load_errors?.length) + safeCount(reviewQueue.approval_handoff_load_errors?.length);
   const waitingCount = safeCount(reviewQueue.total_review_required);
   const status = loadErrorCount > 0 ? "needs_attention" : waitingCount > 0 ? "ready_for_review" : "clear";
   const label = loadErrorCount > 0 ? "Needs Attention" : waitingCount > 0 ? "Ready for Review" : "Clear";
@@ -58,7 +58,7 @@ function buildCommandCenterHealth(reviewQueue, librarian) {
 }
 
 function buildCommandCenterSections(reviewQueue, librarian) {
-  const loadErrorCount = safeCount(reviewQueue.chat_request_load_errors?.length) + safeCount(reviewQueue.side_review_decision_load_errors?.length) + safeCount(reviewQueue.approval_request_load_errors?.length);
+  const loadErrorCount = safeCount(reviewQueue.chat_request_load_errors?.length) + safeCount(reviewQueue.side_review_decision_load_errors?.length) + safeCount(reviewQueue.approval_request_load_errors?.length) + safeCount(reviewQueue.approval_handoff_load_errors?.length);
   return [
     {
       id: "waiting_review",

package/src/eos/http/app.js

@@ -80,7 +80,8 @@ function isLocalStaticUiRoute(url) {
 
 function isGuardedLocalMutationRoute(url) {
   const pathname = getPathname(url);
-  return pathname.startsWith("/api/agent/") || pathname.startsWith("/api/chat/");
+  return pathname.startsWith("/api/agent/") || pathname.startsWith("/api/chat/") ||
+    pathname === "/api/workspace/approval-handoffs";
 }
 
 // ---------------------------------------------------------------------------

package/src/eos/http/routes/home.js

@@ -1,4 +1,5 @@
 import { buildEosHomeData } from "../../home.js";
+import { prepareApprovalHandoffPackage } from "../../approval/handoffs.js";
 import { inspectArtifact } from "../../artifact-inspector/view-model.js";
 import { buildTimelineStatusPanel } from "../../timeline-status/read-model.js";
 import { errorResponse } from "../errors.js";
@@ -46,6 +47,23 @@ export async function registerHomeRoutes(fastify, config) {
     }
     return { artifact, safety };
   });
+
+  fastify.post("/api/workspace/approval-handoffs", async (request, reply) => {
+    const result = await prepareApprovalHandoffPackage(config.wikiRoot, request.body || {}, {
+      actor: request.headers["x-eos-user-id"] || "eos-http",
+    });
+    if (!result.success) {
+      return reply.status(400).send({
+        error: {
+          code: "APPROVAL_HANDOFF_REJECTED",
+          message: result.error,
+          statusCode: 400,
+        },
+        result,
+      });
+    }
+    return reply.status(201).send(result);
+  });
 }
 
 export default registerHomeRoutes;

package/src/eos/workspace/static/app.js

@@ -16,6 +16,8 @@ const elements = {
   decisionSummary: document.querySelector("#decision-summary"),
   approvalSummary: document.querySelector("#approval-summary"),
   approvalList: document.querySelector("#approval-list"),
+  handoffSummary: document.querySelector("#handoff-summary"),
+  handoffList: document.querySelector("#handoff-list"),
   timelineGate: document.querySelector("#timeline-gate"),
   timelineSummary: document.querySelector("#timeline-summary"),
   timelineList: document.querySelector("#timeline-list"),
@@ -23,6 +25,7 @@ const elements = {
   inspectorPath: document.querySelector("#inspector-path"),
   inspectorMeta: document.querySelector("#inspector-meta"),
   inspectorEvidence: document.querySelector("#inspector-evidence"),
+  handoffActionSummary: document.querySelector("#handoff-action-summary"),
 };
 
 function setText(node, value) {
@@ -133,10 +136,41 @@ function renderApprovalQueue(requests = []) {
     button.textContent = "Inspect Artifact";
     button.addEventListener("click", () => inspectApprovalRequest(request.id));
     item.append(title, status, artifact, button);
+    if (request.status === "approved_not_executed") {
+      const packageButton = document.createElement("button");
+      packageButton.type = "button";
+      packageButton.textContent = "Prepare Package";
+      packageButton.addEventListener("click", () => prepareHandoffPackage(request.id));
+      item.append(packageButton);
+    }
     elements.approvalList?.append(item);
   }
 }
 
+function renderHandoffQueue(packages = []) {
+  clearChildren(elements.handoffList);
+  setText(elements.handoffSummary, packages.length === 0
+    ? "No handoff packages yet. Approved requests can be prepared as local review packages."
+    : `${packages.length} handoff package${packages.length === 1 ? "" : "s"} ready for human review.`);
+  for (const itemData of packages) {
+    const item = document.createElement("li");
+    item.className = "result-item";
+    const title = document.createElement("strong");
+    title.textContent = itemData.source_approval_request_id || itemData.id || "Handoff package";
+    const status = document.createElement("p");
+    status.textContent = `Status: ${itemData.status || "review_required"}. Package: ${itemData.package_intent || "human_handoff"}.`;
+    const artifact = document.createElement("p");
+    artifact.className = "artifact-path";
+    artifact.textContent = itemData.artifact_path || "Artifact path unavailable";
+    const button = document.createElement("button");
+    button.type = "button";
+    button.textContent = "Inspect Package";
+    button.addEventListener("click", () => inspectHandoffPackage(itemData.id));
+    item.append(title, status, artifact, button);
+    elements.handoffList?.append(item);
+  }
+}
+
 function renderTimelineStatus(panel = {}) {
   const status = panel.status_panel || {};
   const timeline = Array.isArray(panel.timeline) ? panel.timeline : [];
@@ -185,6 +219,34 @@ async function inspectApprovalRequest(id) {
   renderInspector(payload.artifact || { status: "degraded", summary: "Artifact could not be inspected." });
 }
 
+async function inspectHandoffPackage(id) {
+  if (!id) return;
+  const query = new URLSearchParams({ type: "approval_handoff", id });
+  const response = await fetch(`/api/workspace/artifacts/inspect?${query.toString()}`, {
+    headers: { accept: "application/json" },
+  });
+  const payload = await response.json();
+  renderInspector(payload.artifact || { status: "degraded", summary: "Handoff package could not be inspected." });
+}
+
+async function prepareHandoffPackage(id) {
+  if (!id) return;
+  setText(elements.handoffActionSummary, "Preparing a local review-required handoff package...");
+  const response = await fetch("/api/workspace/approval-handoffs", {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({ source_approval_request_id: id, package_intent: "human_handoff" }),
+  });
+  const payload = await response.json();
+  if (!response.ok || payload.success === false) {
+    setText(elements.handoffActionSummary, payload.error?.message || payload.error || "Handoff package needs attention.");
+    return;
+  }
+  setText(elements.handoffActionSummary, `Handoff package prepared locally: ${payload.artifactPath}. Not applied.`);
+  await Promise.all([loadHome(), loadTimelineStatus()]);
+  if (payload.package?.id) await inspectHandoffPackage(payload.package.id);
+}
+
 function renderInspector(artifact) {
   clearChildren(elements.inspectorMeta);
   clearChildren(elements.inspectorEvidence);
@@ -197,6 +259,9 @@ function renderInspector(artifact) {
   appendListItem(elements.inspectorMeta, "Local Only", flags.local_only === false ? "No" : "Yes");
   appendListItem(elements.inspectorMeta, "Live Work", flags.executed === true ? "Yes" : "No");
   for (const evidence of artifact.evidence || []) appendListItem(elements.inspectorEvidence, "Evidence", evidence);
+  if (artifact.type === "approval_handoff") {
+    setText(elements.handoffActionSummary, "Selected handoff package is local, review-required, and not applied.");
+  }
 }
 
 async function loadHome() {
@@ -214,6 +279,7 @@ async function loadHome() {
     setText(elements.healthSummary, health);
     setText(elements.decisionSummary, formatDecisionSummary(queue.side_review_decision_recent));
     renderApprovalQueue(queue.approval_request_recent || queue.approval_queue?.recent || []);
+    renderHandoffQueue(queue.approval_handoff_recent || queue.approval_handoff_queue?.recent || []);
   } catch {
     setText(elements.wikiCount, "Unavailable");
     setText(elements.reviewCount, "Check local server");
@@ -221,6 +287,7 @@ async function loadHome() {
     setText(elements.healthSummary, "Home data is unavailable. Nothing was applied.");
     setText(elements.decisionSummary, "Prepared decisions are unavailable.");
     renderApprovalQueue([]);
+    renderHandoffQueue([]);
   } finally {
     setLoadingHome(false);
   }

package/src/eos/workspace/static/index.html

@@ -85,6 +85,13 @@
           <ol id="approval-list" class="result-list"></ol>
         </section>
 
+        <section class="result-panel" aria-live="polite" aria-label="Handoff Queue">
+          <p class="eyebrow">Review package area</p>
+          <h2>Handoff Queue</h2>
+          <p id="handoff-summary" class="muted">Loading handoff packages...</p>
+          <ol id="handoff-list" class="result-list"></ol>
+        </section>
+
         <section class="result-panel" aria-live="polite" aria-label="Lifecycle Timeline">
           <p class="eyebrow">Local status panel</p>
           <h2>Lifecycle Timeline</h2>
@@ -101,6 +108,7 @@
         <p id="inspector-path" class="artifact-path"></p>
         <ul id="inspector-meta" class="inspector-list"></ul>
         <ul id="inspector-evidence" class="inspector-list"></ul>
+        <p id="handoff-action-summary" class="muted">Handoff packages are review-required and not applied.</p>
         <p class="muted">Inspector is local-first, read-only, and review-required.</p>
       </aside>
 

package/src/wiki/save-routing.js

@@ -36,7 +36,8 @@ const RECORD_PATTERNS = [
 
 export const PROJECT_KNOWLEDGE_FOLDERS = {
   DASHBOARD: "!대시보드_dashboard",
-  OMX_HANDOFF: "0_omx-핸드오프_omx-handoff",
+  OMW_HANDOFF: "0_omw-handoff_omw-handoff",
+  OMX_HANDOFF: "0_omw-handoff_omw-handoff",
   DEV_HISTORY: "개발-진행-기록_dev-history",
   IMPLEMENTATION_REPORTS: "개발-진행-기록_dev-history/구현-보고_implementation-reports",
   VERIFICATION_LOGS: "개발-진행-기록_dev-history/검증-로그_verification-logs",
@@ -85,8 +86,8 @@ const PROJECT_PLACEMENT_RULES = [
   },
   {
     kind: "handoff",
-    folder: PROJECT_KNOWLEDGE_FOLDERS.OMX_HANDOFF,
-    patterns: [/\bhandoff\b/i, /\bultragoal\b/i, /\bomx\b/i, /핸드오프/u, /울트라골/u],
+    folder: PROJECT_KNOWLEDGE_FOLDERS.OMW_HANDOFF,
+    patterns: [/\bhandoff\b/i, /\bultragoal\b/i, /\bomw\b/i, /\bomx\b/i, /핸드오프/u, /울트라골/u],
   },
   {
     kind: "implementation-report",