npm - @binarycheater/research-sidecar - Versions diffs - 0.1.2 → 0.1.3 - Mend

@binarycheater/research-sidecar 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +20 -1
package/README.zh.md +20 -1
package/dist/client/assets/{index-C3mAbt-i.css → index-BErjWgQz.css} +1 -1
package/dist/client/assets/index-kXy-k1Bp.js +321 -0
package/dist/client/index.html +2 -2
package/dist-server/lib/researchGraph.js +80 -23
package/dist-server/lib/researchGraphManifest.js +89 -3
package/dist-server/server/index.js +9 -1
package/package.json +1 -1
package/skills/research-graph-sop/SKILL.md +52 -1
package/skills/scholar-mode/SKILL.md +22 -1
package/dist/client/assets/index-DTKJmZxM.js +0 -321

package/dist/client/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Research Sidecar</title>
-    <script type="module" crossorigin src="/assets/index-DTKJmZxM.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-C3mAbt-i.css">
+    <script type="module" crossorigin src="/assets/index-kXy-k1Bp.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BErjWgQz.css">
   </head>
   <body>
     <div id="root"></div>

package/dist-server/lib/researchGraph.js CHANGED Viewed

@@ -15,6 +15,7 @@ export function buildGraphIndex(graph) {
 export function getVisibleResearchGraph(graph, options) {
     const byId = new Map(graph.nodes.map((node) => [node.id, node]));
     const hierarchyEdges = graph.edges.filter((edge) => hierarchyEdgeKinds.has(edge.kind));
+    const contextEdges = graph.edges.filter((edge) => !hierarchyEdgeKinds.has(edge.kind));
     const childrenByParent = groupEdges(hierarchyEdges, "from");
     const parentsByChild = groupEdges(hierarchyEdges, "to");
     const childCounts = Object.fromEntries(graph.nodes.map((node) => [node.id, childrenByParent.get(node.id)?.length || 0]));
@@ -31,7 +32,9 @@ export function getVisibleResearchGraph(graph, options) {
         }
     }
     else {
-        collectExpandedTree(graph.rootId, childrenByParent, options.expandedIds, visibleIds);
+        collectExpandedDag(graph.rootId, childrenByParent, options.expandedIds, visibleIds);
+        addSharedHierarchyChildren(visibleIds, hierarchyEdges);
+        addIncidentContextNodes(visibleIds, contextEdges);
     }
     const nodes = graph.nodes.filter((node) => visibleIds.has(node.id));
     const edges = graph.edges.filter((edge) => visibleIds.has(edge.from) && visibleIds.has(edge.to));
@@ -69,18 +72,11 @@ export function getExpandableDescendantIds(graph, rootId) {
 }
 export function getNextExpandedIdsForNodeClick(graph, currentIds, nodeId) {
     const next = new Set(currentIds);
-    const descendantIds = getHierarchyDescendantIds(graph, nodeId);
     if (next.has(nodeId)) {
         next.delete(nodeId);
-        for (const descendantId of descendantIds) {
-            next.delete(descendantId);
-        }
         return next;
     }
     next.add(nodeId);
-    for (const descendantId of descendantIds) {
-        next.delete(descendantId);
-    }
     return next;
 }
 export function getFocusedResearchGraph(graph, options) {
@@ -141,20 +137,13 @@ export function layoutResearchGraph(graph, options) {
             parentQueue.push(edge.from);
         }
     }
-    const rows = new Map();
-    for (const node of graph.nodes) {
-        const depth = depthById.get(node.id) ?? 0;
-        rows.set(depth, [...(rows.get(depth) || []), node]);
-    }
-    const rowOffsets = new Map();
-    for (const [depth, nodes] of rows) {
-        nodes.forEach((node, offset) => rowOffsets.set(node.id, offset - (nodes.length - 1) / 2));
-        rows.set(depth, nodes);
-    }
+    const ySlots = assignHierarchyYSlots(graph, childrenByParent, depthById);
+    const slots = [...ySlots.values()];
+    const centerSlot = slots.length ? (Math.min(...slots) + Math.max(...slots)) / 2 : 0;
+    const spacing = options.mode === "full" ? { depth: 700, cross: 300 } : { depth: 320, cross: 170 };
     const nodes = graph.nodes.map((node) => {
         const depth = depthById.get(node.id) ?? 0;
-        const offset = rowOffsets.get(node.id) || 0;
-        const spacing = options.mode === "full" ? { depth: 610, cross: 320 } : { depth: 300, cross: 160 };
+        const offset = (ySlots.get(node.id) ?? 0) - centerSlot;
         const position = options.direction === "LR" ? { x: depth * spacing.depth, y: offset * spacing.cross } : { x: offset * spacing.depth, y: depth * spacing.cross };
         return { ...node, position };
     });
@@ -165,12 +154,80 @@ export function layoutResearchGraph(graph, options) {
         childCounts: graph.childCounts
     };
 }
-function collectExpandedTree(id, childrenByParent, expandedIds, visibleIds) {
+function assignHierarchyYSlots(graph, childrenByParent, depthById) {
+    const graphNodeIds = new Set(graph.nodes.map((node) => node.id));
+    const ySlots = new Map();
+    const visiting = new Set();
+    let nextSlot = 0;
+    function assign(id) {
+        const existing = ySlots.get(id);
+        if (existing !== undefined)
+            return existing;
+        if (visiting.has(id)) {
+            const slot = nextSlot;
+            nextSlot += 1;
+            ySlots.set(id, slot);
+            return slot;
+        }
+        visiting.add(id);
+        const childSlots = [];
+        for (const edge of childrenByParent.get(id) || []) {
+            if (!graphNodeIds.has(edge.to))
+                continue;
+            childSlots.push(assign(edge.to));
+        }
+        visiting.delete(id);
+        const slot = childSlots.length ? (Math.min(...childSlots) + Math.max(...childSlots)) / 2 : nextSlot++;
+        ySlots.set(id, slot);
+        return slot;
+    }
+    if (graphNodeIds.has(graph.rootId)) {
+        assign(graph.rootId);
+    }
+    const remaining = graph.nodes
+        .filter((node) => !ySlots.has(node.id))
+        .sort((left, right) => (depthById.get(left.id) ?? 0) - (depthById.get(right.id) ?? 0));
+    for (const node of remaining) {
+        assign(node.id);
+    }
+    return ySlots;
+}
+function collectExpandedDag(id, childrenByParent, expandedIds, visibleIds) {
+    const alreadyVisible = visibleIds.has(id);
     visibleIds.add(id);
-    if (!expandedIds.has(id))
+    if (alreadyVisible || !expandedIds.has(id))
         return;
     for (const edge of childrenByParent.get(id) || []) {
-        collectExpandedTree(edge.to, childrenByParent, expandedIds, visibleIds);
+        collectExpandedDag(edge.to, childrenByParent, expandedIds, visibleIds);
+    }
+}
+function addIncidentContextNodes(visibleIds, contextEdges) {
+    const hierarchyVisibleIds = new Set(visibleIds);
+    for (const edge of contextEdges) {
+        if (hierarchyVisibleIds.has(edge.from)) {
+            visibleIds.add(edge.to);
+        }
+        if (hierarchyVisibleIds.has(edge.to)) {
+            visibleIds.add(edge.from);
+        }
+    }
+}
+function addSharedHierarchyChildren(visibleIds, hierarchyEdges) {
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const visibleParentCounts = new Map();
+        for (const edge of hierarchyEdges) {
+            if (!visibleIds.has(edge.from) || visibleIds.has(edge.to))
+                continue;
+            visibleParentCounts.set(edge.to, (visibleParentCounts.get(edge.to) || 0) + 1);
+        }
+        for (const [childId, parentCount] of visibleParentCounts) {
+            if (parentCount < 2)
+                continue;
+            visibleIds.add(childId);
+            changed = true;
+        }
     }
 }
 function getHierarchyDescendantIds(graph, rootId) {

package/dist-server/lib/researchGraphManifest.js CHANGED Viewed

@@ -1,11 +1,24 @@
 import { access, readFile } from "node:fs/promises";
-import { dirname, extname, isAbsolute, join } from "node:path";
+import { dirname, extname, isAbsolute, join, posix } from "node:path";
 import YAML from "yaml";
-import { resolveWorkspacePath, toWorkspaceRelativePath } from "./files.js";
+import { resolveWorkspacePath, toWorkspaceRelativePath, writeWorkspaceFile } from "./files.js";
 const DEFAULT_MANIFEST_PATH = "research/graph.yaml";
 const NODE_TYPES = new Set(["question", "claim", "evidence", "method", "concept", "source", "task", "output"]);
 const EDGE_KINDS = new Set(["decomposes", "answers", "supports", "contradicts", "depends_on", "operationalizes", "cites", "leads_to"]);
-const STATUSES = new Set(["active", "draft", "blocked", "done"]);
+const STATUSES = new Set([
+    "active",
+    "draft",
+    "blocked",
+    "done",
+    "needs_decomposition",
+    "testable",
+    "testing",
+    "supported",
+    "weakened",
+    "contradicted",
+    "revised",
+    "accepted_for_now"
+]);
 const LAYOUTS = new Set(["LR", "TB"]);
 export async function loadResearchGraphManifest(workspaceRoot, manifestPath = DEFAULT_MANIFEST_PATH) {
     const fullPath = resolveWorkspacePath(workspaceRoot, manifestPath);
@@ -34,6 +47,63 @@ export async function loadResearchGraphManifest(workspaceRoot, manifestPath = DE
         ...(ui ? { ui } : {})
     };
 }
+export async function saveResearchGraphManifest(workspaceRoot, manifestPath = DEFAULT_MANIFEST_PATH, graph) {
+    const manifestDir = dirname(manifestPath);
+    const nodeIds = new Set();
+    const nodes = graph.nodes.map((node) => {
+        const id = requiredString(node.id, "node.id");
+        if (nodeIds.has(id)) {
+            throw new Error(`Duplicate node id ${id}.`);
+        }
+        nodeIds.add(id);
+        const type = normalizeNodeType(node.type, id);
+        const files = serializeNodeFiles(manifestDir, node);
+        return {
+            id,
+            title: requiredString(node.title, `node ${id} title`),
+            type,
+            ...(files.length === 1 ? { file: files[0].path } : {}),
+            ...(files.length > 1
+                ? {
+                    files: files.map((file) => (file.title ? { path: file.path, title: file.title } : file.path))
+                }
+                : {}),
+            ...optionalField("summary", node.summary),
+            ...optionalStatus(node.status),
+            ...(node.tags?.length ? { tags: node.tags } : {})
+        };
+    });
+    const root = requiredString(graph.rootId, "root");
+    if (!nodeIds.has(root)) {
+        throw new Error(`Graph root ${root} does not match any node id.`);
+    }
+    const edges = graph.edges.map((edge) => {
+        const normalized = normalizeEdge(edge, nodeIds);
+        return {
+            ...(edge.id && edge.id !== `${normalized.from}->${normalized.to}:${normalized.kind}` ? { id: edge.id } : {}),
+            from: normalized.from,
+            to: normalized.to,
+            kind: normalized.kind,
+            ...optionalField("label", normalized.label)
+        };
+    });
+    const manifest = {
+        root,
+        ...(graph.ui?.layout || graph.ui?.expanded?.length
+            ? {
+                ui: {
+                    ...(graph.ui.layout ? { layout: graph.ui.layout } : {}),
+                    ...(graph.ui.expanded?.length ? { expanded: graph.ui.expanded } : {})
+                }
+            }
+            : {}),
+        nodes,
+        edges
+    };
+    const body = YAML.stringify(manifest, { lineWidth: 0 });
+    await writeWorkspaceFile(workspaceRoot, manifestPath, body, [".yaml", ".yml"]);
+    return loadResearchGraphManifest(workspaceRoot, manifestPath);
+}
 async function normalizeNode(workspaceRoot, manifestDir, input, warnings) {
     const id = requiredString(input.id, "node.id");
     const linkedFiles = normalizeManifestLinkedFiles(workspaceRoot, manifestDir, input.file, input.files);
@@ -147,6 +217,22 @@ function normalizeManifestLinkedFiles(workspaceRoot, manifestDir, fileValue, fil
     }
     return out;
 }
+function serializeNodeFiles(manifestDir, node) {
+    const files = node.files?.length ? node.files : node.file ? [{ path: node.file }] : [];
+    return files.map((file) => ({
+        path: toManifestRelativePath(manifestDir, file.path),
+        ...(file.title ? { title: file.title } : {})
+    }));
+}
+function toManifestRelativePath(manifestDir, workspacePath) {
+    const normalized = workspacePath.trim().replace(/^\/+/, "");
+    if (!normalized)
+        return normalized;
+    const relativePath = posix.relative(manifestDir === "." ? "" : manifestDir, normalized);
+    if (!relativePath || relativePath.startsWith("."))
+        return relativePath || ".";
+    return `./${relativePath}`;
+}
 function parseYamlRecord(source, label) {
     let parsed;
     try {

package/dist-server/server/index.js CHANGED Viewed

@@ -6,7 +6,7 @@ import { buildContextPacket } from "../lib/context.js";
 import { getWorkspaceOpenCommand, readWorkspaceFile, readWorkspaceRawFile, resolveWorkspaceFileForOpen } from "../lib/files.js";
 import { discoverGraphManifests } from "../lib/graphDiscovery.js";
 import { DEFAULT_REVIEW_PROMPT } from "../lib/prompt.js";
-import { loadResearchGraphManifest } from "../lib/researchGraphManifest.js";
+import { loadResearchGraphManifest, saveResearchGraphManifest } from "../lib/researchGraphManifest.js";
 import { streamOpenAIReview } from "../lib/openaiProvider.js";
 import { JsonSessionStore } from "../lib/store.js";
 import { installBundledSkills } from "../lib/workspaceInstall.js";
@@ -114,6 +114,14 @@ app.get("/api/research-graph", async (_req, res, next) => {
         next(error);
     }
 });
+app.put("/api/research-graph", async (req, res, next) => {
+    try {
+        res.json(await saveResearchGraphManifest(config.workspaceRoot, config.graphManifestPath, req.body));
+    }
+    catch (error) {
+        next(error);
+    }
+});
 app.get("/api/sessions", async (_req, res, next) => {
     try {
         res.json(await store.listSessions());

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@binarycheater/research-sidecar",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Local research graph sidecar and CLI for Codex-assisted research workflows.",
   "keywords": [
     "research",

package/skills/research-graph-sop/SKILL.md CHANGED Viewed

@@ -9,6 +9,37 @@ Use the graph as a small, inspectable map of the research state. Put structure a
 Core principle: **thin graph, thick notes, active agent**. The graph should reduce cognitive load, not become a database the researcher has to maintain.
+## Target Graph Shape
+The graph is a lightweight reasoning scaffold, not a collection of related notes. It should grow with the research path: questions decompose into testable claims, claims are made observable by methods, methods produce evidence, evidence changes claim status, and unresolved gaps become tasks.
+Prefer this reasoning backbone:
+`question -> claim -> method -> evidence -> revision/task/output`
+A useful graph should let a reader answer:
+1. What question is being decomposed?
+2. Which claim currently answers it?
+3. What would make the claim observable or testable?
+4. What evidence bears on the claim?
+5. What changed after the evidence appeared?
+6. What remains unresolved?
+## Reasoning Integrity Rules
+When editing the graph, preserve reasoning integrity:
+- An active `question` should have a decomposed subquestion, an answering `claim`, or a `task` explaining what is missing.
+- An active `claim` should have at least one of: a `method` that operationalizes it, `evidence` that supports or contradicts it, a rival `claim`, or a `depends_on` premise.
+- A `claim` should not be treated as settled merely because it has a `source`. Sources are materials; evidence is an extracted observation, result, finding, quotation, or counterexample.
+- A `method` should point toward the claim it makes observable. If the method has produced results, add or update an `evidence` node.
+- An `evidence` node should bear on a specific claim through `supports` or `contradicts`. Avoid evidence nodes that only summarize interesting material without changing the state of a claim.
+- Use `leads_to` when a result creates a revision, follow-up task, output, or new question. Do not use it as a generic related-to edge.
+- If a node is only context, background, or reading material, prefer `source` plus `cites`. Do not promote it into the reasoning backbone unless it changes a claim, method, question, or task.
+Keep updates conservative. If the user's graph is weak, inconsistent, over-connected, or logically underconstrained, point out the issue and propose a repair. Do not perform a major rewrite, reclassification, or graph-wide normalization unless the user explicitly asks for a major cleanup, rewrite, or restructuring.
 ## First Move
 If `graph.yaml` exists, read it before proposing structure changes. Then read only the linked Markdown/source files needed to understand the active question, claims, evidence, methods, and tasks.
@@ -80,6 +111,14 @@ Prefer the existing Sidecar vocabulary:
 | `cites` | a node uses a source |
 | `leads_to` | a result creates a task or next step |
+Use only the edge kinds in this table. Do not invent near-synonyms such as
+`motivates`, `uses`, `contextualizes`, or `informs`; map them to the closest
+allowed kind instead:
+- `motivates` -> `leads_to` when a result opens a next question/task; otherwise `supports`
+- `uses` or `contextualizes` -> `cites` when pointing to a source; otherwise `supports`
+- `informs` -> `supports` when it bears on a claim, or `leads_to` when it creates a next step
 ## YAML Contract
 When creating or editing `graph.yaml`, keep it valid, boring YAML. Use two-space indentation, arrays with `-`, no tabs, and quote strings only when they contain characters that could confuse YAML (`:`, `#`, `{}`, `[]`, leading `*`, or multiline text).
@@ -120,7 +159,7 @@ Optional node fields:
 - `summary`: use for short, one-sentence nodes that do not need a document yet.
 - `file`: one linked Markdown/HTML/text document.
 - `files`: multiple linked documents. Use either strings or `{ path, title }` objects.
-- `status`: `active`, `draft`, `blocked`, or `done`.
+- `status`: legacy statuses `active`, `draft`, `blocked`, or `done`; epistemic statuses `needs_decomposition`, `testable`, `testing`, `supported`, `weakened`, `contradicted`, `revised`, or `accepted_for_now`.
 - `tags`: array of short labels.
 Valid document-link patterns:
@@ -163,6 +202,8 @@ New agent-created nodes should usually be `status: draft`. Use `active` when the
 Add a graph node only when the item needs to be navigated, connected, reused, challenged, or tracked over time.
+For large graphs, reason from the active subgraph first: root or active question, nearby claims, methods, evidence, tasks, and directly cited files. Use the full graph as an index, not as a complete argument in context.
 Avoid:
 - duplicating long Markdown content in `summary`
@@ -170,6 +211,16 @@ Avoid:
 - adding schema fields the current repo does not already use
 - treating the graph as proof by itself
 - hiding uncertainty behind tidy structure
+- using `leads_to`, `supports`, or `cites` as vague association edges
+Bad graph smells:
+- Many nodes are connected only because they are topically related.
+- Claims have sources but no evidence, method, rival, or premise.
+- Evidence does not clearly support or contradict any claim.
+- Methods exist but do not say what claim they test.
+- Questions branch into themes instead of decomposed subquestions.
+- The graph has no visible next research action or unresolved gap.
 Good graph changes make the current research easier to inspect in under a minute.

package/skills/scholar-mode/SKILL.md CHANGED Viewed

@@ -27,7 +27,28 @@ Before answering, internally check: What is being judged? What evidence or mater
 ## Research Graph Use
-When a workspace includes `graph.yaml`, treat it as the structural map of the research project: nodes, relationships, and file pointers. Treat Markdown files as the content layer. If the user asks to update research structure, prefer editing the graph manifest and the affected Markdown notes together.
+When a workspace includes `graph.yaml`, treat it as the structural map of the research project: nodes, relationships, and file pointers. Treat Markdown files as the content layer.
+The graph is a lightweight reasoning scaffold, not a collection of related notes. It should grow with the research path: questions decompose into testable claims, claims are made observable by methods, methods produce evidence, evidence changes claim status, and unresolved gaps become tasks.
+Prefer this reasoning backbone: `question -> claim -> method -> evidence -> revision/task/output`.
+Use the graph to preserve rigor and continuity:
+- A `question` should decompose into smaller questions, be answered by claims, or expose a task/gap.
+- A `claim` should answer a question and show at least one of: a test method, bearing evidence, a rival claim, or a premise it depends on.
+- A `method` should make a claim observable or testable.
+- An `evidence` node should bear on a specific claim through support, contradiction, or pressure to revise.
+- A `source` is raw material; do not treat it as evidence until a relevant finding, observation, result, or quotation has been extracted into notes.
+- A `task` should represent an unresolved gap, verification step, or next research action, not a generic todo.
+Keep the graph minimal. Add nodes and edges only when they preserve the reasoning chain, make active uncertainty navigable, prevent overclaiming, or track a decision that will matter later. Avoid generic "related" connections.
+Use graph status as epistemic state when available: `needs_decomposition`, `testable`, `testing`, `supported`, `weakened`, `contradicted`, `revised`, and `accepted_for_now`. Legacy statuses such as `active`, `draft`, `blocked`, and `done` remain valid; interpret them conservatively.
+If the user's graph is weak, inconsistent, over-connected, or logically underconstrained, point out the issue and propose a repair. Do not perform a major rewrite, reclassification, or graph-wide normalization unless the user explicitly asks for a major cleanup, rewrite, or restructuring.
+For large graphs, reason from the active subgraph first: root or active question, nearby claims, methods, evidence, tasks, and directly cited files. Use the full graph as an index, not as a complete argument in context.
 ## Output