oh-my-llmwikimode 1.5.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_CHAT_HOME_IA.md

@@ -101,6 +101,9 @@ Do not use these labels in the Eos Chat MVP:
 - `GET /workspace` redirects to `/workspace/`.
 - `GET /side-review/` serves the review desk for local artifacts, evidence, and prepare-only decision notes.
 - `GET /api/home` remains a read-only home data snapshot.
+- `POST /api/agent/side-review/approval-requests` prepares a review-required approval request from an existing `prepare_approval` Side Review decision artifact only.
+- `GET /api/workspace/artifacts/inspect` returns whitelisted read-only artifact inspector data by `{type,id}` only.
+- `GET /api/workspace/timeline-status` returns a local lifecycle timeline/status panel derived from EOS local artifacts only.
 - `POST /api/chat/requests` creates a review-required local artifact only.
 
 ## 12. Browser-first Workspace Slice
@@ -166,3 +169,22 @@ Stable fields:
 - `review_queue.side_review_decision_recent`: latest prepared decision artifacts for the right inspector/Home summary
 
 The snapshot is a read model only. It must not become an execution queue, approval queue, hosted sync contract, or source wiki mutation path.
+
+## 14. Approval Inspector workspace slice - 2026-06-01
+
+`EOS Workspace` now includes an Approval Queue and Artifact Inspector for review-required approval request artifacts.
+
+Stable surfaces:
+
+- `review_queue.approval_request_recent`: latest local approval request artifacts visible in Home/Workspace.
+- `approval_surface`: local approval queue metadata and route hints for the browser workbench.
+- `/api/agent/side-review/approval-requests`: prepare-only route from `prepare_approval` Side Review decisions to approval request artifacts.
+- `/api/workspace/artifacts/inspect`: safe inspector route for whitelisted artifact types and ids.
+- `/api/workspace/timeline-status`: local lifecycle timeline and Timeline Gate status.
+- Workspace regions: `Approval Queue`, `Artifact Inspector`, `Lifecycle Timeline`, and `Timeline Gate`.
+
+Safety contract:
+
+- Approval Queue is a review queue, not an execution queue.
+- Artifact Inspector must reject raw local paths, traversal, unsupported types, symlinks, oversized artifacts, and malformed JSON without leaking secrets or user-home paths.
+- Timeline Gate may show `approved_not_executed`, but this is a review state only. It must not imply shell, git, provider, Discord, sync, publish, merge, push, or source wiki mutation work has happened.

package/docs/design/EOS_DESIGN.md

@@ -339,3 +339,69 @@ Verification anchors:
 - `test/eos/uiux-product-shape.test.js`
 - `npm run test:eos`
 - `npm run verify:eos-workspace-completion`
+
+## Implemented EOS Workspace Approval Inspector Slice - 2026-06-01
+
+The EOS Workspace Approval Inspector slice makes approval requests first-class local review artifacts inside the browser-first workbench.
+
+What changed:
+
+- Approval request artifacts now live under `.system/eos/approval/requests/` with review-required lifecycle statuses, deterministic duplicate handling, and append-only audit metadata.
+- `GET /api/home` includes a local approval queue summary with recent approval request artifacts.
+- `POST /api/agent/side-review/approval-requests` prepares an approval request only from an existing `prepare_approval` Side Review decision artifact.
+- `GET /api/workspace/artifacts/inspect` exposes a whitelisted, read-only artifact inspector for approval requests and adjacent EOS artifacts.
+- `GET /api/workspace/timeline-status` exposes a local-only lifecycle timeline/status panel derived from chat, Side Review, approval, visual QA, and local evidence artifacts.
+- `/workspace/` renders Approval Queue, Artifact Inspector, Lifecycle Timeline, and Timeline Gate surfaces with Local Only, Review Required, and Not Applied safety labels.
+- Browser product evidence is captured under `.omo/ulw-loop/evidence/eos-approval-inspector-20260601/`.
+
+Boundary:
+
+- The slice remains web-service first, not a VS Code extension or VSIX.
+- Approval statuses such as `approved_not_executed` mean explicit review state only; they do not execute shell, git, provider, Discord, or wiki mutation actions.
+- Side Review approval request creation is prepare-only; it creates a local review artifact and never applies the underlying decision.
+- The inspector reads only whitelisted local artifacts by type/id, rejects raw paths and traversal, redacts secrets and user-home paths, and degrades safely on malformed artifacts.
+- This slice does not add hosted sync, production Discord control, marketplace/account/payment features, package splitting, npm publish, auto-apply, auto-promotion, auto-merge/delete, auto-push, hidden execution, or source wiki mutation.
+
+Verification anchors:
+
+- `test/eos/approval-request-artifacts.test.js`
+- `test/eos/approval-queue-read-model.test.js`
+- `test/eos/side-review-approval-requests.test.js`
+- `test/eos/artifact-inspector-view-model.test.js`
+- `test/eos/workspace-approval-inspector-routes.test.js`
+- `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.5.0",
+  "version": "1.7.0",
   "description": "LLM Wiki plugin for OpenCode ??auto-memory, retrieval, and knowledge promotion",
   "type": "module",
   "main": "./src/server.js",
@@ -30,6 +30,8 @@
     "test:eos": "node --test test/eos/**/*.test.js",
     "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/artifacts.js

@@ -0,0 +1,164 @@
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  APPROVAL_REQUEST_STATUSES,
+  createApprovalAuditEntry,
+  createApprovalRequestArtifact,
+  validateApprovalRequest,
+} from "./contract.js";
+
+export { APPROVAL_REQUEST_STATUSES } from "./contract.js";
+
+const AUDIT_ACTIONS = Object.freeze([
+  "approval_requested",
+  "reject_approval_request",
+]);
+
+function resolveUnderWikiRoot(wikiRoot, relativePath) {
+  const root = path.resolve(wikiRoot);
+  const target = path.resolve(root, ...relativePath.split("/"));
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Eos approval artifact path escapes wiki root");
+  }
+  return target;
+}
+
+function resolveRequestArtifactPath(wikiRoot, relativePath) {
+  const target = resolveUnderWikiRoot(wikiRoot, relativePath);
+  const requestsRoot = path.resolve(getApprovalArtifactPaths(wikiRoot).requests);
+  const relative = path.relative(requestsRoot, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Eos approval artifact path escapes requests directory");
+  }
+  return target;
+}
+
+export function getApprovalArtifactPaths(wikiRoot) {
+  const root = path.join(wikiRoot, ".system", "eos", "approval");
+  return Object.freeze({
+    root,
+    requests: path.join(root, "requests"),
+    auditFile: path.join(root, "audit.jsonl"),
+  });
+}
+
+export async function ensureApprovalArtifactStructure(wikiRoot) {
+  const paths = getApprovalArtifactPaths(wikiRoot);
+  await mkdir(paths.requests, { recursive: true });
+  return paths;
+}
+
+export async function prepareApprovalRequestArtifact(wikiRoot, input = {}, options = {}) {
+  if (!wikiRoot || typeof wikiRoot !== "string") {
+    throw new Error("wikiRoot is required for Eos approval artifacts");
+  }
+
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  const validation = validateApprovalRequest(input);
+  if (!validation.valid) {
+    await appendApprovalAudit(wikiRoot, "reject_approval_request", {
+      source_decision_id: input.source_decision_id || "",
+      requested_action: input.requested_action || "",
+      reason: validation.errors.join("; "),
+    }, { ...options, now });
+    return rejected(validation.errors.join("; "));
+  }
+
+  const prepared = createApprovalRequestArtifact(validation.value, { ...options, now });
+  const resolvedArtifactPath = resolveRequestArtifactPath(wikiRoot, prepared.artifactPath);
+  const existing = await readExistingJson(resolvedArtifactPath);
+  if (existing.exists) {
+    return Object.freeze({
+      success: true,
+      duplicate: true,
+      request: existing.value,
+      artifactPath: prepared.artifactPath,
+      executed: false,
+      sourceEntryMutated: false,
+    });
+  }
+
+  await ensureApprovalArtifactStructure(wikiRoot);
+  await writeFile(resolvedArtifactPath, `${JSON.stringify(prepared.artifact, null, 2)}\n`, {
+    encoding: "utf-8",
+    flag: "wx",
+  });
+  await appendApprovalAuditEntry(wikiRoot, prepared.auditEntry);
+
+  return Object.freeze({
+    success: true,
+    duplicate: false,
+    request: prepared.artifact,
+    artifactPath: prepared.artifactPath,
+    audit: prepared.auditEntry,
+    auditPath: ".system/eos/approval/audit.jsonl",
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}
+
+export async function readApprovalRequestArtifacts(wikiRoot) {
+  const paths = getApprovalArtifactPaths(wikiRoot);
+  const requests = [];
+  const load_errors = [];
+  try {
+    const entries = await readdir(paths.requests, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const filePath = path.join(paths.requests, entry.name);
+      try {
+        const artifact = JSON.parse(await readFile(filePath, "utf-8"));
+        if (artifact?.type === "eos_approval_request" && APPROVAL_REQUEST_STATUSES.includes(artifact.status)) {
+          requests.push(artifact);
+        }
+      } catch (error) {
+        load_errors.push({ path: filePath, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return Object.freeze({
+    paths,
+    requests: Object.freeze(requests.sort((left, right) => String(left.id).localeCompare(String(right.id)))),
+    load_errors: Object.freeze(load_errors),
+    summary: Object.freeze({ requests: requests.length, load_errors: load_errors.length }),
+  });
+}
+
+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;
+  }
+}
+
+async function appendApprovalAudit(wikiRoot, action, entry = {}, options = {}) {
+  const payload = {
+    ...createApprovalAuditEntry(action, entry, options),
+    reason: entry.reason || "",
+  };
+  await appendApprovalAuditEntry(wikiRoot, payload);
+  return payload;
+}
+
+async function appendApprovalAuditEntry(wikiRoot, entry) {
+  if (!AUDIT_ACTIONS.includes(entry.action)) {
+    throw new Error(`Unsupported Eos approval audit action: ${entry.action}`);
+  }
+  const paths = await ensureApprovalArtifactStructure(wikiRoot);
+  await appendFile(paths.auditFile, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+
+function rejected(error) {
+  return Object.freeze({
+    success: false,
+    error,
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}

package/src/eos/approval/contract.js

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export const APPROVAL_REQUEST_STATUSES = Object.freeze([
+  "review_required",
+  "blocked",
+  "approved_not_executed",
+  "handoff_prepared",
+  "rejected",
+]);
+
+export const APPROVAL_ACTION = "prepare_handoff";
+
+const SUPPORTED_SOURCE_ROOTS = Object.freeze([
+  ".system/eos/chat/requests/",
+  ".system/eos/side-review/decisions/",
+  ".system/eos/approval/requests/",
+  ".system/eos/visual-qa/",
+  ".omo/ulw-loop/evidence/",
+]);
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function iso(value) {
+  return (value instanceof Date ? value : new Date(value || Date.now())).toISOString();
+}
+
+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);
+}
+
+function safeId(value, fallback = "approval") {
+  return String(value || fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || fallback;
+}
+
+export function relativeRequestPath(id) {
+  return path.posix.join(".system", "eos", "approval", "requests", `${id}.json`);
+}
+
+function normalizeRelativePath(value, field, options = {}) {
+  if (typeof value !== "string" || !value.trim()) return { error: `${field} is required` };
+  const normalized = value.trim().replaceAll("\\", "/");
+  if (path.isAbsolute(normalized) || normalized.includes("://")) return { error: `${field} must be a safe relative path` };
+  const collapsed = path.posix.normalize(normalized);
+  if (collapsed.startsWith("../") || collapsed === ".." || collapsed.startsWith("/")) {
+    return { error: `${field} must stay inside the wiki root` };
+  }
+  if (options.supportedRoot && !SUPPORTED_SOURCE_ROOTS.some((root) => collapsed.startsWith(root))) {
+    return { error: `${field} must use a supported approval source root` };
+  }
+  return { value: collapsed };
+}
+
+export function validateApprovalRequest(input = {}) {
+  const errors = [];
+  const sourceDecisionId = typeof input.source_decision_id === "string" ? input.source_decision_id.trim() : "";
+  const requestedAction = typeof input.requested_action === "string" ? input.requested_action.trim() : "";
+  const sourceArtifactPath = normalizeRelativePath(input.source_artifact_path, "source_artifact_path", { supportedRoot: true });
+  const sourcePath = input.source_path ? normalizeRelativePath(input.source_path, "source_path") : { value: null };
+  const evidence = Array.isArray(input.evidence) ? input.evidence : [];
+
+  if (!sourceDecisionId) errors.push("source_decision_id is required");
+  if (requestedAction !== APPROVAL_ACTION) errors.push(`requested_action must be ${APPROVAL_ACTION}`);
+  if (input.status && !APPROVAL_REQUEST_STATUSES.includes(input.status)) errors.push("status is not supported");
+  if (sourceArtifactPath.error) errors.push(sourceArtifactPath.error);
+  if (sourcePath.error) errors.push(sourcePath.error);
+  if (evidence.length === 0) errors.push("evidence is required");
+
+  if (errors.length > 0) return Object.freeze({ valid: false, errors: Object.freeze(errors) });
+
+  return Object.freeze({
+    valid: true,
+    value: Object.freeze({
+      source_decision_id: sourceDecisionId,
+      source_artifact_path: sourceArtifactPath.value,
+      requested_action: requestedAction,
+      reason: typeof input.reason === "string" ? input.reason.trim() : "",
+      source_path: sourcePath.value,
+      evidence: Object.freeze(evidence.map((item) => String(item).trim()).filter(Boolean)),
+      requested_by: typeof input.requested_by === "string" && input.requested_by.trim()
+        ? input.requested_by.trim()
+        : "eos-approval",
+    }),
+  });
+}
+
+export function createApprovalRequestArtifact(request, options = {}) {
+  const seed = {
+    source_decision_id: request.source_decision_id,
+    source_artifact_path: request.source_artifact_path,
+    requested_action: request.requested_action,
+    evidence: request.evidence,
+  };
+  const id = `approval-${safeId(request.source_decision_id)}-${safeId(request.requested_action)}-${shortHash(seed)}`;
+  const artifactPath = relativeRequestPath(id);
+  const auditEntry = createApprovalAuditEntry("approval_requested", request, options, { requestId: id, artifactPath });
+  return Object.freeze({
+    artifactPath,
+    artifact: Object.freeze({
+      schema_version: 1,
+      type: "eos_approval_request",
+      id,
+      source_decision_id: request.source_decision_id,
+      source_artifact_path: request.source_artifact_path,
+      requested_action: request.requested_action,
+      reason: request.reason,
+      source_path: request.source_path,
+      evidence: request.evidence,
+      status: "review_required",
+      requested_by: request.requested_by,
+      safety_flags: Object.freeze({
+        review_required: true,
+        approved_not_executed: false,
+        executed: false,
+        source_entry_mutated: false,
+      }),
+      boundaries: Object.freeze({
+        no_hidden_execution: true,
+        no_source_mutation: true,
+        auto_apply: false,
+        auto_promote: false,
+        auto_merge: false,
+        auto_delete: false,
+        auto_push: false,
+        auto_publish: false,
+        hosted_sync: false,
+      }),
+      audit: Object.freeze([auditEntry]),
+      created_at: iso(options.now),
+      updated_at: iso(options.now),
+      artifact_path: artifactPath,
+    }),
+    auditEntry,
+  });
+}
+
+export function createApprovalAuditEntry(action, request, options = {}, refs = {}) {
+  return Object.freeze({
+    schema_version: 1,
+    action,
+    recorded_at: iso(options.now),
+    actor: options.actor || "eos-approval",
+    request_id: refs.requestId || null,
+    artifact_path: refs.artifactPath || null,
+    source_decision_id: request.source_decision_id || "",
+    requested_action: request.requested_action || "",
+    executed: false,
+    live_execution: false,
+    source_entry_mutated: false,
+  });
+}