sdtk-wiki-kit 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-wiki-kit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Project-local wiki and knowledge graph toolkit for SDTK workspaces.",
   "bin": {
     "sdtk-wiki": "bin/sdtk-wiki.js"

package/src/commands/ask.js

@@ -57,6 +57,8 @@ Inputs:
 Behavior:
   Executes a local premium wiki.ask runtime pack when entitlement and graph preconditions pass.
   Fails closed when the graph, entitlement, or runtime pack is missing.
+  --source grounds on the chosen doc plus its directly-related siblings (docs sharing
+  the same BK issue, knowledge id, skill, or family), bounded and labelled as related.
   Query history is off by default.
   --save-query writes one redacted JSON record under .sdtk/wiki/queries after a successful answer.
   Full question and full answer are not stored by default.`);

package/src/commands/help.js

@@ -53,6 +53,7 @@ R1 command model:
   wiki discover        Write a local-only discovery plan from WIKI gap evidence.
   wiki compile         Preview or explicitly apply local wiki compile plans.
   ask                  Ask grounded questions over the built SDTK-WIKI graph.
+  kaban                Open the Agent Kaban board (Dashboard panel) for the current project.
   search               Search generated local wiki pages without premium Ask.
   lint                 Write a report-first, non-destructive wiki lint report.
   update               Package-only updater; no wiki/.sdtk/wiki/.sdtk/atlas files are mutated in R1.

package/src/commands/init.js

@@ -32,7 +32,7 @@ BK-102 behavior:
 Options:
   --project-path <path>   Project root. Defaults to current working directory.
   --output-dir <path>     Graph output dir under .sdtk/wiki. Defaults to .sdtk/wiki/graph.
-  --scan-root <path>      Repeatable markdown scan root.
+  --scan-root <path>      Repeatable markdown scan root. Defaults to ./docs if it exists, otherwise the project root.
   --force                 Overwrite existing config.
   --no-build              Write config only.
   --no-open               Build graph but do not launch viewer.

package/src/commands/kaban.js

@@ -0,0 +1,85 @@
+"use strict";
+
+// BK-272: sdtk-wiki kaban — open the viewer on the Dashboard (Kaban board) panel.
+// Follows the same flow as cmdAtlasOpen; Dashboard is the default active panel.
+
+const fs = require("fs");
+const path = require("path");
+const { resolveWikiConfig } = require("../lib/wiki-config");
+const { openViewer, runBuild } = require("../lib/wiki-runner");
+const { parseFlags } = require("../lib/args");
+const { OPEN_FLAG_DEFS } = require("../lib/wiki-flags");
+
+const KABAN_FLAG_DEFS = {
+  ...OPEN_FLAG_DEFS,
+  "project-path": { type: "string", alias: "project" },
+};
+
+function hasHelp(args) {
+  return args.includes("-h") || args.includes("--help");
+}
+
+async function cmdKaban(args) {
+  if (hasHelp(args)) {
+    console.log(`Usage:
+  sdtk-wiki kaban [--project <dir>] [--port <n>] [--no-open]
+
+Purpose:
+  Open the SDTK-WIKI viewer showing the Agent Kaban board (Dashboard panel).
+  The board reads SHARED_PLANNING.md and QUALITY_CHECKLIST.md from the project
+  directory and polls /api/kaban every 3 s while the Dashboard panel is active.
+
+Options:
+  --project, --project-path <dir>  Project root containing SHARED_PLANNING.md
+                                   and QUALITY_CHECKLIST.md (default: cwd)
+  --port <n>                       Local server port (default: from config or 7654)
+  --no-open                        Print the viewer URL without opening a browser
+  -h, --help                       Show this help and exit
+
+Example:
+  sdtk-wiki kaban --project /path/to/project
+  sdtk-wiki kaban --no-open`);
+    return 0;
+  }
+
+  const { flags } = parseFlags(args, KABAN_FLAG_DEFS);
+  const config = resolveWikiConfig(flags);
+
+  const viewerPath = path.join(config.outputDir, "viewer.html");
+  const legacyViewerPath = path.join(config.legacyAtlasDir || "", "viewer.html");
+
+  const hasViewer =
+    fs.existsSync(viewerPath) || fs.existsSync(legacyViewerPath);
+
+  if (!hasViewer) {
+    console.log("[kaban] No SDTK-WIKI viewer found. Running initial build...");
+    try {
+      await runBuild(config);
+    } catch (err) {
+      console.error("[kaban] Build failed: " + err.message);
+      console.error("[kaban] Run: sdtk-wiki atlas build");
+      return 1;
+    }
+  }
+
+  // Use legacy atlas dir if the wiki output dir has no viewer yet
+  const activeConfig = fs.existsSync(viewerPath)
+    ? config
+    : { ...config, outputDir: config.legacyAtlasDir };
+
+  const noOpen = !!flags["no-open"];
+  const { server } = await openViewer(activeConfig, noOpen);
+
+  if (noOpen) {
+    if (server) server.close();
+    return 0;
+  }
+
+  console.log("[kaban] Dashboard (Kaban board) is the active panel.");
+  console.log("[kaban] Edit SHARED_PLANNING.md or QUALITY_CHECKLIST.md to see live updates.");
+  console.log("[kaban] Press Ctrl+C to stop the viewer server.");
+  await new Promise(() => {});
+  return 0;
+}
+
+module.exports = { cmdKaban };

package/src/index.js

@@ -2,6 +2,7 @@
 
 const { cmdAtlas } = require("./commands/atlas");
 const { cmdAsk } = require("./commands/ask");
+const { cmdKaban } = require("./commands/kaban");
 const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
 const { cmdLint } = require("./commands/lint");
@@ -47,6 +48,7 @@ const COMMANDS = new Set([
   "atlas",
   "wiki",
   "ask",
+  "kaban",
   "lint",
   "search",
   "ingest",
@@ -82,6 +84,8 @@ async function run(argv) {
       return cmdWiki(args);
     case "ask":
       return cmdAsk(args);
+    case "kaban":
+      return cmdKaban(args);
     case "lint":
       return cmdLint(args);
     case "search":

package/src/lib/wiki-ask.js

@@ -9,6 +9,11 @@ const { loadWikiAskHandler } = require("./wiki-premium-loader");
 const INDEX_FILE = "SDTK_DOC_INDEX.json";
 const GRAPH_FILE = "SDTK_DOC_GRAPH.json";
 const DEFAULT_MAX_SOURCES = 6;
+// BK-269 hyperedge-aware context expansion (--source filter only).
+// Mirrors run_doc_atlas_server.py so both grounding surfaces behave identically.
+const DEFAULT_MAX_HYPEREDGE_EXPANSION = 6;
+const DEFAULT_MIN_HYPEREDGE_CO_MEMBERSHIP = 1;
+const DEFAULT_MAX_FAMILY_HYPEREDGE_CONTRIB = 3;
 
 function readJsonFile(filePath, label) {
   try {
@@ -69,28 +74,251 @@ function extractDocumentText(document) {
   return "";
 }
 
-function buildSources(index, sourceFilters, maxSources) {
+function docId(document) {
+  return document.id || extractDocumentPath(document);
+}
+
+function docFacetKeys(document) {
+  const keys = [];
+  const groups = [
+    ["issue", document.issues],
+    ["knowledge", document.knowledge_ids],
+    ["skill", document.skill_refs],
+    ["lane", document.lane_refs],
+  ];
+  for (const [namespace, values] of groups) {
+    if (!Array.isArray(values)) {
+      continue;
+    }
+    for (const value of values) {
+      const text = String(value == null ? "" : value).trim();
+      if (text) {
+        keys.push(`${namespace}:${text}`);
+      }
+    }
+  }
+  const family = String(document.family == null ? "" : document.family).trim();
+  if (family) {
+    keys.push(`family:${family}`);
+  }
+  return keys;
+}
+
+// Invert shared reference facets into hyperedges (groups with >=2 docs). Pure and
+// deterministic; mirrors _derive_hyperedges in run_doc_atlas_server.py.
+function deriveHyperedges(documents) {
+  const facetToDocs = new Map();
+  for (const document of documents) {
+    if (!document || typeof document !== "object") {
+      continue;
+    }
+    const id = docId(document);
+    if (!id) {
+      continue;
+    }
+    for (const facetKey of docFacetKeys(document)) {
+      let members = facetToDocs.get(facetKey);
+      if (!members) {
+        members = [];
+        facetToDocs.set(facetKey, members);
+      }
+      if (!members.includes(id)) {
+        members.push(id);
+      }
+    }
+  }
+  const hyperedges = new Map();
+  for (const [facet, ids] of facetToDocs) {
+    if (ids.length >= 2) {
+      hyperedges.set(facet, ids.slice().sort());
+    }
+  }
+  const docHyperedges = new Map();
+  for (const [facet, ids] of hyperedges) {
+    for (const id of ids) {
+      let facets = docHyperedges.get(id);
+      if (!facets) {
+        facets = new Set();
+        docHyperedges.set(id, facets);
+      }
+      facets.add(facet);
+    }
+  }
+  return { hyperedges, docHyperedges };
+}
+
+function computeNodeDegree(graph, docIdSet) {
+  const degree = new Map();
+  const edges = graph && Array.isArray(graph.edges) ? graph.edges : [];
+  for (const edge of edges) {
+    const source = edge && edge.source;
+    const target = edge && edge.target;
+    if (docIdSet.has(source) && docIdSet.has(target)) {
+      degree.set(source, (degree.get(source) || 0) + 1);
+      degree.set(target, (degree.get(target) || 0) + 1);
+    }
+  }
+  return degree;
+}
+
+// Bounded hyperedge co-member expansion. Returns ranked expansion entries
+// ({ id, facets, relation }). Mirrors _expand_via_hyperedges in the Python server:
+// shared-facet-count desc -> node_degree desc -> title/id lexical, with a family cap.
+function expandSourcesViaHyperedges(seedIds, derived, nodeDegree, docsById, options) {
+  const opts = options || {};
+  const maxExpansion = Number.isInteger(opts.maxExpansion)
+    ? opts.maxExpansion
+    : DEFAULT_MAX_HYPEREDGE_EXPANSION;
+  const minCoMembership = Number.isInteger(opts.minCoMembership)
+    ? opts.minCoMembership
+    : DEFAULT_MIN_HYPEREDGE_CO_MEMBERSHIP;
+  const familyCap = Number.isInteger(opts.familyCap)
+    ? opts.familyCap
+    : DEFAULT_MAX_FAMILY_HYPEREDGE_CONTRIB;
+  if (maxExpansion <= 0) {
+    return [];
+  }
+  const seedSet = new Set(seedIds);
+  const seedFacets = new Set();
+  for (const seedId of seedIds) {
+    const facets = derived.docHyperedges.get(seedId);
+    if (facets) {
+      for (const facet of facets) {
+        seedFacets.add(facet);
+      }
+    }
+  }
+  if (seedFacets.size === 0) {
+    return [];
+  }
+  const candidateFacets = new Map();
+  for (const facet of seedFacets) {
+    const members = derived.hyperedges.get(facet) || [];
+    for (const id of members) {
+      if (seedSet.has(id)) {
+        continue;
+      }
+      let facets = candidateFacets.get(id);
+      if (!facets) {
+        facets = new Set();
+        candidateFacets.set(id, facets);
+      }
+      facets.add(facet);
+    }
+  }
+  const candidates = [];
+  for (const [id, facets] of candidateFacets) {
+    if (facets.size >= minCoMembership) {
+      candidates.push({ id, facets });
+    }
+  }
+  candidates.sort((a, b) => {
+    if (b.facets.size !== a.facets.size) {
+      return b.facets.size - a.facets.size;
+    }
+    const degreeDelta = (nodeDegree.get(b.id) || 0) - (nodeDegree.get(a.id) || 0);
+    if (degreeDelta !== 0) {
+      return degreeDelta;
+    }
+    const titleA = String((docsById.get(a.id) || {}).title || a.id).toLowerCase();
+    const titleB = String((docsById.get(b.id) || {}).title || b.id).toLowerCase();
+    if (titleA !== titleB) {
+      return titleA < titleB ? -1 : 1;
+    }
+    const idA = a.id.toLowerCase();
+    const idB = b.id.toLowerCase();
+    if (idA !== idB) {
+      return idA < idB ? -1 : 1;
+    }
+    return 0;
+  });
+  const selected = [];
+  let familyOnlyAdmitted = 0;
+  for (const candidate of candidates) {
+    if (selected.length >= maxExpansion) {
+      break;
+    }
+    let hasNonFamily = false;
+    for (const facet of candidate.facets) {
+      if (!facet.startsWith("family:")) {
+        hasNonFamily = true;
+        break;
+      }
+    }
+    if (!hasNonFamily) {
+      // OQ-C: cap how many docs can enter via a family facet alone.
+      if (familyOnlyAdmitted >= familyCap) {
+        continue;
+      }
+      familyOnlyAdmitted += 1;
+    }
+    const sortedFacets = Array.from(candidate.facets).sort();
+    selected.push({
+      id: candidate.id,
+      facets: sortedFacets,
+      relation: `shares ${sortedFacets.join(", ")}`,
+    });
+  }
+  return selected;
+}
+
+function buildSources(index, sourceFilters, maxSources, graph) {
   const documents = Array.isArray(index.documents) ? index.documents : [];
   const filters = (sourceFilters || []).map((item) => item.trim()).filter(Boolean);
   const limit = Number.isInteger(maxSources) && maxSources > 0 ? maxSources : DEFAULT_MAX_SOURCES;
 
-  return documents
-    .map((document) => {
-      const sourcePath = extractDocumentPath(document);
-      return {
-        id: document.id || sourcePath,
-        path: sourcePath,
-        title: document.title || sourcePath,
-        text: extractDocumentText(document),
-      };
-    })
-    .filter((source) => {
-      if (filters.length === 0) {
-        return true;
-      }
-      return filters.some((filter) => source.id === filter || source.path === filter);
-    })
-    .slice(0, limit);
+  const mapped = documents.map((document) => {
+    const sourcePath = extractDocumentPath(document);
+    return {
+      id: document.id || sourcePath,
+      path: sourcePath,
+      title: document.title || sourcePath,
+      text: extractDocumentText(document),
+      relation: "primary",
+    };
+  });
+
+  // No explicit --source filter: ground on all docs, unchanged (no expansion).
+  if (filters.length === 0) {
+    return mapped.slice(0, limit);
+  }
+
+  const primaries = mapped.filter((source) =>
+    filters.some((filter) => source.id === filter || source.path === filter)
+  );
+
+  // BK-269: append the filtered docs' hyperedge co-members (capped, labelled),
+  // so `--source <doc>` also grounds on its directly-related siblings.
+  const sourceById = new Map(mapped.map((source) => [source.id, source]));
+  const docsById = new Map();
+  for (const document of documents) {
+    if (!document || typeof document !== "object") {
+      continue;
+    }
+    const id = docId(document);
+    if (id && !docsById.has(id)) {
+      docsById.set(id, document);
+    }
+  }
+  const derived = deriveHyperedges(documents);
+  const nodeDegree = computeNodeDegree(graph, new Set(docsById.keys()));
+  const seedIds = primaries.map((source) => source.id);
+  const expansion = expandSourcesViaHyperedges(seedIds, derived, nodeDegree, docsById, {});
+
+  const result = primaries.slice();
+  const seen = new Set(seedIds);
+  for (const item of expansion) {
+    if (seen.has(item.id)) {
+      continue;
+    }
+    const base = sourceById.get(item.id);
+    if (!base) {
+      continue;
+    }
+    seen.add(item.id);
+    result.push({ ...base, relation: item.relation });
+  }
+  return result.slice(0, limit);
 }
 
 function normalizeCitations(citations) {
@@ -126,6 +354,7 @@ function normalizeAskResult(rawResult, context) {
     citations: normalizeCitations(result.citations),
     confidence: result.confidence,
     graphPath: context.graphPath,
+    expandedDocCount: Number.isInteger(context.expandedDocCount) ? context.expandedDocCount : 0,
   };
 }
 
@@ -139,7 +368,10 @@ async function runWikiAsk(options) {
   const graphInfo = assertWikiGraphReady(projectPath);
   const index = readJsonFile(graphInfo.indexPath, INDEX_FILE);
   const graph = readJsonFile(graphInfo.graphFilePath, GRAPH_FILE);
-  const sources = buildSources(index, options.sources, options.maxSources);
+  const sources = buildSources(index, options.sources, options.maxSources, graph);
+  const expandedDocCount = sources.filter(
+    (source) => source.relation && source.relation !== "primary"
+  ).length;
 
   const handlerState = await loadWikiAskHandler();
   if (!handlerState.ok) {
@@ -155,6 +387,7 @@ async function runWikiAsk(options) {
     graphFilePath: graphInfo.graphFilePath,
     graph,
     sources,
+    expandedDocCount,
     maxSources: options.maxSources,
   };
 
@@ -170,6 +403,8 @@ async function runWikiAsk(options) {
 
 module.exports = {
   buildSources,
+  deriveHyperedges,
+  expandSourcesViaHyperedges,
   normalizeAskResult,
   runWikiAsk,
 };

package/src/lib/wiki-config.js

@@ -71,7 +71,9 @@ function resolveWikiConfig(flags = {}) {
   ) {
     scanRoots = persisted.scanRoots.map((r) => path.resolve(r));
   } else {
-    scanRoots = [projectPath];
+    const docsDir = path.join(projectPath, "docs");
+    const hasDocsDir = fs.existsSync(docsDir) && fs.statSync(docsDir).isDirectory();
+    scanRoots = [hasDocsDir ? docsDir : projectPath];
   }
 
   const excludes =