@grainulation/orchard 1.0.0 → 1.0.2

package/lib/decompose.js

@@ -0,0 +1,268 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+/**
+ * Auto-decompose a research question into sub-sprints.
+ *
+ * Uses heuristic keyword analysis to break a broad question into
+ * focused sub-questions, each becoming its own sprint with appropriate
+ * dependency relationships.
+ *
+ * This is a deterministic, offline decomposition — no LLM required.
+ * For richer decomposition, pipe through wheat's claim system.
+ */
+
+/**
+ * Facets that broad research questions typically decompose into.
+ * Each facet has trigger keywords and a question template.
+ */
+const FACETS = [
+  {
+    name: "technical",
+    triggers: [
+      "how",
+      "implement",
+      "build",
+      "architecture",
+      "system",
+      "code",
+      "api",
+      "stack",
+      "platform",
+      "tool",
+    ],
+    template: (q) =>
+      `What are the technical requirements and architecture for: ${q}`,
+  },
+  {
+    name: "user-experience",
+    triggers: [
+      "user",
+      "ux",
+      "design",
+      "interface",
+      "experience",
+      "mobile",
+      "web",
+      "dashboard",
+      "visual",
+    ],
+    template: (q) => `What should the user experience look like for: ${q}`,
+  },
+  {
+    name: "market",
+    triggers: [
+      "market",
+      "competitor",
+      "existing",
+      "prior",
+      "landscape",
+      "alternative",
+      "compare",
+      "industry",
+    ],
+    template: (q) => `What does the competitive landscape look like for: ${q}`,
+  },
+  {
+    name: "feasibility",
+    triggers: [
+      "cost",
+      "time",
+      "effort",
+      "feasible",
+      "risk",
+      "constraint",
+      "limit",
+      "budget",
+      "resource",
+    ],
+    template: (q) => `What are the feasibility constraints and risks for: ${q}`,
+  },
+  {
+    name: "adoption",
+    triggers: [
+      "adopt",
+      "rollout",
+      "migration",
+      "team",
+      "org",
+      "enterprise",
+      "onboard",
+      "training",
+      "change",
+    ],
+    template: (q) => `What does adoption and rollout look like for: ${q}`,
+  },
+  {
+    name: "measurement",
+    triggers: [
+      "measure",
+      "metric",
+      "success",
+      "kpi",
+      "track",
+      "outcome",
+      "impact",
+      "evaluate",
+      "test",
+    ],
+    template: (q) => `How do we measure success for: ${q}`,
+  },
+];
+
+/**
+ * Score how relevant each facet is to the question.
+ */
+function scoreFacets(question) {
+  const words = new Set(question.toLowerCase().split(/\s+/));
+  return FACETS.map((f) => {
+    const hits = f.triggers.filter(
+      (t) => words.has(t) || question.toLowerCase().includes(t),
+    );
+    return { ...f, score: hits.length };
+  });
+}
+
+/**
+ * Decompose a question into sub-sprints.
+ * Returns an array of sprint configs ready to add to orchard.json.
+ *
+ * Options:
+ *   maxSprints: maximum number of sub-sprints (default 5)
+ *   prefix: path prefix for sprint directories (default 'sprints')
+ *   minFacets: minimum facets even if no keywords match (default 2)
+ */
+function decompose(question, opts = {}) {
+  const maxSprints = opts.maxSprints || 5;
+  const prefix = opts.prefix || "sprints";
+  const minFacets = opts.minFacets || 2;
+
+  const scored = scoreFacets(question);
+
+  // Pick facets: all with score > 0, or top minFacets if none match
+  let selected = scored.filter((f) => f.score > 0);
+  if (selected.length < minFacets) {
+    selected = scored
+      .sort(
+        (a, b) => b.score - a.score || FACETS.indexOf(a) - FACETS.indexOf(b),
+      )
+      .slice(0, minFacets);
+  }
+
+  // Cap at maxSprints
+  selected = selected.slice(0, maxSprints);
+
+  // Generate slug from question
+  const slug = question
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .substring(0, 40);
+
+  const sprints = selected.map((facet, i) => ({
+    path: path.join(prefix, `${slug}-${facet.name}`),
+    name: `${slug}-${facet.name}`,
+    question: facet.template(question),
+    depends_on:
+      i === 0 ? [] : [path.join(prefix, `${slug}-${selected[0].name}`)],
+  }));
+
+  // Add a synthesis sprint that depends on all others
+  if (sprints.length >= 2) {
+    sprints.push({
+      path: path.join(prefix, `${slug}-synthesis`),
+      name: `${slug}-synthesis`,
+      question: `Synthesize findings across all sub-sprints for: ${question}`,
+      depends_on: sprints.map((s) => s.path),
+    });
+  }
+
+  return sprints;
+}
+
+/**
+ * Apply decomposition: create directories and update orchard.json.
+ */
+function applyDecomposition(root, question, opts = {}) {
+  const sprints = decompose(question, opts);
+
+  // Create sprint directories with initial claims.json
+  for (const sprint of sprints) {
+    const absPath = path.join(root, sprint.path);
+    fs.mkdirSync(absPath, { recursive: true });
+
+    const claimsPath = path.join(absPath, "claims.json");
+    if (!fs.existsSync(claimsPath)) {
+      const initial = {
+        schema_version: "1.0",
+        meta: {
+          question: sprint.question,
+          initiated: new Date().toISOString().split("T")[0],
+          audience: [],
+          phase: "define",
+          connectors: [],
+        },
+        claims: [],
+      };
+      fs.writeFileSync(
+        claimsPath,
+        JSON.stringify(initial, null, 2) + "\n",
+        "utf8",
+      );
+    }
+  }
+
+  // Update orchard.json
+  const orchardPath = path.join(root, "orchard.json");
+  let config = { sprints: [] };
+  if (fs.existsSync(orchardPath)) {
+    config = JSON.parse(fs.readFileSync(orchardPath, "utf8"));
+  }
+  config.sprints = config.sprints || [];
+
+  const existingPaths = new Set(config.sprints.map((s) => s.path));
+  for (const sprint of sprints) {
+    if (!existingPaths.has(sprint.path)) {
+      config.sprints.push(sprint);
+    }
+  }
+
+  fs.writeFileSync(orchardPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+
+  return sprints;
+}
+
+/**
+ * Print decomposition plan without applying it.
+ */
+function printDecomposition(question, opts = {}) {
+  const sprints = decompose(question, opts);
+
+  console.log("");
+  console.log(`  Auto-decompose: "${question}"`);
+  console.log("  " + "=".repeat(50));
+  console.log(`  ${sprints.length} sub-sprints generated:`);
+  console.log("");
+
+  for (const s of sprints) {
+    const deps = s.depends_on.length
+      ? ` (depends on: ${s.depends_on.map((d) => path.basename(d)).join(", ")})`
+      : " (root)";
+    console.log(`    ${path.basename(s.path)}${deps}`);
+    console.log(`      Q: ${s.question}`);
+  }
+
+  console.log("");
+  console.log('  Apply with: orchard decompose --apply "<question>"');
+  console.log("");
+}
+
+module.exports = {
+  decompose,
+  applyDecomposition,
+  printDecomposition,
+  scoreFacets,
+  FACETS,
+};

package/lib/doctor.js

@@ -1,7 +1,7 @@
-'use strict';
+"use strict";
 
-const fs = require('node:fs');
-const path = require('node:path');
+const fs = require("node:fs");
+const path = require("node:path");
 
 /**
  * Run all doctor checks against the orchard root directory.
@@ -11,12 +11,14 @@ function runChecks(root) {
   const checks = [];
 
   // 1. orchard.json present and parseable
-  const configPath = path.join(root, 'orchard.json');
+  const configPath = path.join(root, "orchard.json");
   const configExists = fs.existsSync(configPath);
   checks.push({
-    name: 'orchard.json exists',
+    name: "orchard.json exists",
     ok: configExists,
-    detail: configExists ? configPath : 'Not found. Run "orchard init" to create one.',
+    detail: configExists
+      ? configPath
+      : 'Not found. Run "orchard init" to create one.',
   });
 
   if (!configExists) {
@@ -25,30 +27,36 @@ function runChecks(root) {
 
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    checks.push({ name: 'orchard.json is valid JSON', ok: true, detail: '' });
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    checks.push({ name: "orchard.json is valid JSON", ok: true, detail: "" });
   } catch (err) {
-    checks.push({ name: 'orchard.json is valid JSON', ok: false, detail: err.message });
+    checks.push({
+      name: "orchard.json is valid JSON",
+      ok: false,
+      detail: err.message,
+    });
     return { checks, ok: false };
   }
 
   const sprints = config.sprints || [];
   checks.push({
-    name: 'sprints defined',
+    name: "sprints defined",
     ok: sprints.length > 0,
-    detail: sprints.length > 0
-      ? `${sprints.length} sprint(s) configured`
-      : 'No sprints in orchard.json',
+    detail:
+      sprints.length > 0
+        ? `${sprints.length} sprint(s) configured`
+        : "No sprints in orchard.json",
   });
 
   // 2. Sprint directories reachable
   let allReachable = true;
   for (const sprint of sprints) {
-    const sprintDir = sprint.path === '.'
-      ? root
-      : path.isAbsolute(sprint.path)
-        ? sprint.path
-        : path.join(root, sprint.path);
+    const sprintDir =
+      sprint.path === "."
+        ? root
+        : path.isAbsolute(sprint.path)
+          ? sprint.path
+          : path.join(root, sprint.path);
     const exists = fs.existsSync(sprintDir);
     if (!exists) allReachable = false;
     checks.push({
@@ -78,9 +86,12 @@ function runChecks(root) {
     }
   }
   if (allDepsResolved && sprints.length > 0) {
-    const totalDeps = sprints.reduce((n, s) => n + (s.depends_on || []).length, 0);
+    const totalDeps = sprints.reduce(
+      (n, s) => n + (s.depends_on || []).length,
+      0,
+    );
     checks.push({
-      name: 'all dependencies resolve',
+      name: "all dependencies resolve",
       ok: true,
       detail: `${totalDeps} dependency link(s) verified`,
     });
@@ -89,17 +100,19 @@ function runChecks(root) {
   // 4. Cycle detection
   let hasCycles = false;
   try {
-    const { detectCycles } = require('./planner.js');
+    const { detectCycles } = require("./planner.js");
     const cycles = detectCycles(config);
     hasCycles = cycles.length > 0;
     checks.push({
-      name: 'no dependency cycles',
+      name: "no dependency cycles",
       ok: !hasCycles,
-      detail: hasCycles ? `Cycle involving: ${cycles.join(', ')}` : 'Dependency graph is acyclic',
+      detail: hasCycles
+        ? `Cycle involving: ${cycles.join(", ")}`
+        : "Dependency graph is acyclic",
     });
   } catch (err) {
     checks.push({
-      name: 'no dependency cycles',
+      name: "no dependency cycles",
       ok: false,
       detail: `Cycle check failed: ${err.message}`,
     });
@@ -113,13 +126,13 @@ function runChecks(root) {
  * Print doctor results to stdout.
  */
 function printReport(result) {
-  console.log('');
-  console.log('  orchard doctor');
-  console.log('  ' + '='.repeat(40));
-  console.log('');
+  console.log("");
+  console.log("  orchard doctor");
+  console.log("  " + "=".repeat(40));
+  console.log("");
 
   for (const check of result.checks) {
-    const icon = check.ok ? 'ok' : 'FAIL';
+    const icon = check.ok ? "ok" : "FAIL";
     const line = `  [${icon.padEnd(4)}] ${check.name}`;
     console.log(line);
     if (check.detail && !check.ok) {
@@ -127,11 +140,14 @@ function printReport(result) {
     }
   }
 
-  console.log('');
+  console.log("");
   const passed = result.checks.filter((c) => c.ok).length;
   const total = result.checks.length;
-  console.log(`  ${passed}/${total} checks passed` + (result.ok ? ' -- all healthy' : ' -- issues found'));
-  console.log('');
+  console.log(
+    `  ${passed}/${total} checks passed` +
+      (result.ok ? " -- all healthy" : " -- issues found"),
+  );
+  console.log("");
 }
 
 module.exports = { runChecks, printReport };

package/lib/export.js

@@ -1,4 +1,4 @@
-'use strict';
+"use strict";
 
 /**
  * orchard -> mill edge: export trigger for completed sprints.
@@ -8,14 +8,14 @@
  * or filesystem. Graceful fallback if mill is not available.
  */
 
-const fs = require('node:fs');
-const path = require('node:path');
-const http = require('node:http');
+const fs = require("node:fs");
+const path = require("node:path");
+const http = require("node:http");
 
 const MILL_PORT = 9094;
 const MILL_SIBLINGS = [
-  path.join(__dirname, '..', '..', 'mill'),
-  path.join(__dirname, '..', '..', '..', 'mill'),
+  path.join(__dirname, "..", "..", "mill"),
+  path.join(__dirname, "..", "..", "..", "mill"),
 ];
 
 /**
@@ -24,14 +24,16 @@ const MILL_SIBLINGS = [
  */
 function detectMill() {
   for (const dir of MILL_SIBLINGS) {
-    const pkg = path.join(dir, 'package.json');
+    const pkg = path.join(dir, "package.json");
     if (fs.existsSync(pkg)) {
       try {
-        const meta = JSON.parse(fs.readFileSync(pkg, 'utf8'));
-        if (meta.name === '@grainulation/mill') {
-          return { available: true, method: 'filesystem', path: dir };
+        const meta = JSON.parse(fs.readFileSync(pkg, "utf8"));
+        if (meta.name === "@grainulation/mill") {
+          return { available: true, method: "filesystem", path: dir };
         }
-      } catch { continue; }
+      } catch {
+        continue;
+      }
     }
   }
   return { available: false };
@@ -46,27 +48,44 @@ function detectMill() {
 function exportSprint(sprintPath, format) {
   return new Promise((resolve) => {
     const body = JSON.stringify({ format, options: { source: sprintPath } });
-    const req = http.request({
-      hostname: '127.0.0.1',
-      port: MILL_PORT,
-      path: '/api/export',
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
-      timeout: 5000,
-    }, (res) => {
-      let data = '';
-      res.on('data', (chunk) => { data += chunk; });
-      res.on('end', () => {
-        try {
-          const result = JSON.parse(data);
-          resolve(result.error ? { ok: false, error: result.error } : { ok: true, job: result.job });
-        } catch {
-          resolve({ ok: false, error: 'Invalid response from mill' });
-        }
-      });
+    const req = http.request(
+      {
+        hostname: "127.0.0.1",
+        port: MILL_PORT,
+        path: "/api/export",
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(body),
+        },
+        timeout: 5000,
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => {
+          data += chunk;
+        });
+        res.on("end", () => {
+          try {
+            const result = JSON.parse(data);
+            resolve(
+              result.error
+                ? { ok: false, error: result.error }
+                : { ok: true, job: result.job },
+            );
+          } catch {
+            resolve({ ok: false, error: "Invalid response from mill" });
+          }
+        });
+      },
+    );
+    req.on("error", () =>
+      resolve({ ok: false, error: "mill not reachable on port " + MILL_PORT }),
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({ ok: false, error: "mill request timed out" });
     });
-    req.on('error', () => resolve({ ok: false, error: 'mill not reachable on port ' + MILL_PORT }));
-    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'mill request timed out' }); });
     req.write(body);
     req.end();
   });
@@ -78,20 +97,29 @@ function exportSprint(sprintPath, format) {
  */
 function listFormats() {
   return new Promise((resolve) => {
-    const req = http.get(`http://127.0.0.1:${MILL_PORT}/api/formats`, { timeout: 2000 }, (res) => {
-      let body = '';
-      res.on('data', (chunk) => { body += chunk; });
-      res.on('end', () => {
-        try {
-          const data = JSON.parse(body);
-          resolve({ available: true, formats: data.formats || [] });
-        } catch {
-          resolve({ available: false });
-        }
-      });
+    const req = http.get(
+      `http://127.0.0.1:${MILL_PORT}/api/formats`,
+      { timeout: 2000 },
+      (res) => {
+        let body = "";
+        res.on("data", (chunk) => {
+          body += chunk;
+        });
+        res.on("end", () => {
+          try {
+            const data = JSON.parse(body);
+            resolve({ available: true, formats: data.formats || [] });
+          } catch {
+            resolve({ available: false });
+          }
+        });
+      },
+    );
+    req.on("error", () => resolve({ available: false }));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({ available: false });
     });
-    req.on('error', () => resolve({ available: false }));
-    req.on('timeout', () => { req.destroy(); resolve({ available: false }); });
   });
 }