@grainulation/orchard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grainulation contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @grainulation/orchard
+
+> 12 sprints running. One command to see them all.
+
+**Orchard** is the multi-sprint orchestrator for [Wheat](https://github.com/grainulation/wheat) research sprints. It coordinates parallel research across teams with dependency tracking, conflict detection, and unified dashboards.
+
+## Install
+
+```bash
+npx @grainulation/orchard status
+```
+
+## What it does
+
+- **Run multiple wheat sprints in parallel** with dependency tracking
+- **Sprint dependency graphs** -- "sprint B needs sprint A's results first"
+- **Team assignment** -- who's running which sprint
+- **Resource allocation** -- distribute research bandwidth
+- **Cross-sprint conflict detection** -- when two sprints reach opposing conclusions
+- **Unified status dashboard** across all active sprints
+- **Sprint scheduling and deadline tracking**
+
+## Quick start
+
+Create a `orchard.json` in your project root:
+
+```json
+{
+  "sprints": [
+    {
+      "path": "./sprints/auth-scaling",
+      "question": "How should we scale auth for 10x traffic?",
+      "depends_on": [],
+      "assigned_to": "alice",
+      "deadline": "2026-03-20",
+      "status": "active"
+    },
+    {
+      "path": "./sprints/data-migration",
+      "question": "What's the safest migration path for the user table?",
+      "depends_on": ["./sprints/auth-scaling"],
+      "assigned_to": "bob",
+      "deadline": "2026-03-25",
+      "status": "active"
+    }
+  ]
+}
+```
+
+Then:
+
+```bash
+# See the dependency graph
+orchard plan
+
+# Check status of all sprints
+orchard status
+
+# Assign someone to a sprint
+orchard assign ./sprints/data-migration carol
+
+# Sync status from sprint directories
+orchard sync
+
+# Generate HTML dashboard
+orchard dashboard
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `orchard plan` | Show sprint dependency graph as ASCII |
+| `orchard status` | Show status of all tracked sprints |
+| `orchard assign <path> <person>` | Assign a person to a sprint |
+| `orchard sync` | Sync sprint states from their directories |
+| `orchard dashboard [outfile]` | Generate unified HTML dashboard |
+| `orchard init` | Initialize orchard.json in the current directory |
+| `orchard serve` | Start the portfolio dashboard web server |
+| `orchard help` | Show help |
+
+## orchard.json schema
+
+```typescript
+{
+  sprints: Array<{
+    path: string;           // Relative path to sprint directory
+    question: string;       // The research question
+    depends_on: string[];   // Paths of prerequisite sprints
+    assigned_to: string;    // Person responsible
+    deadline: string;       // ISO date string
+    status: string;         // active | done | blocked | not-started
+  }>
+}
+```
+
+## How it works
+
+Orchard reads `orchard.json` for the sprint graph, then scans each sprint directory for `claims.json` and `compilation.json` to determine actual state. It detects conflicts by comparing claims across sprints that share tags.
+
+### Conflict detection
+
+Orchard flags two types of cross-sprint conflicts:
+
+1. **Opposing recommendations** -- two sprints make recommendations on the same topic that may contradict
+2. **Constraint-recommendation tension** -- one sprint's constraints conflict with another's recommendations
+
+### Dependency tracking
+
+Sprints can declare dependencies. Orchard uses topological sorting to determine execution order and flags cycles. The `plan` command renders this as ASCII art.
+
+## Zero dependencies
+
+Orchard uses only Node.js built-in modules. No npm install required.
+
+## License
+
+MIT

package/bin/orchard.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+function vlog(...a) {
+  if (!verbose) return;
+  const ts = new Date().toISOString();
+  process.stderr.write(`[${ts}] orchard: ${a.join(' ')}\n`);
+}
+
+const COMMANDS = {
+  init: 'Initialize orchard.json in the current directory',
+  plan: 'Show sprint dependency graph as ASCII',
+  status: 'Show status of all tracked sprints',
+  assign: 'Assign a person to a sprint',
+  sync: 'Sync sprint states from their directories',
+  dashboard: 'Generate unified HTML dashboard',
+  serve: 'Start the portfolio dashboard web server',
+  connect: 'Connect to a farmer instance',
+  doctor: 'Check health of orchard setup',
+  help: 'Show this help message',
+};
+
+function loadConfig(dir) {
+  const configPath = path.join(dir, 'orchard.json');
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+}
+
+function findOrchardRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'orchard.json'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function printHelp() {
+  console.log('');
+  console.log('  orchard - Multi-sprint research orchestrator');
+  console.log('');
+  console.log('  Usage: orchard <command> [options]');
+  console.log('');
+  console.log('  Commands:');
+  for (const [cmd, desc] of Object.entries(COMMANDS)) {
+    console.log(`    ${cmd.padEnd(12)} ${desc}`);
+  }
+  console.log('');
+  console.log('  Serve options:');
+  console.log('    --port 9097    Port for the web server (default: 9097)');
+  console.log('    --root <dir>   Root directory to scan for sprints');
+  console.log('');
+  console.log('  Connect:');
+  console.log('    orchard connect farmer --url http://localhost:9090');
+  console.log('');
+  console.log('  Config: orchard.json in project root');
+  console.log('');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+  vlog('startup', `command=${command}`, `cwd=${process.cwd()}`);
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (!COMMANDS[command]) {
+    console.error(`orchard: unknown command: ${command}`);
+    console.error(`Run "orchard help" to see available commands.`);
+    process.exit(1);
+  }
+
+  // Serve command — start the HTTP server (ESM module)
+  if (command === 'serve') {
+    const serverPath = path.join(__dirname, '..', 'lib', 'server.js');
+    const { spawn } = require('node:child_process');
+
+    // Forward remaining args to the server
+    const serverArgs = args.slice(1);
+    const child = spawn(process.execPath, [serverPath, ...serverArgs], {
+      stdio: 'inherit',
+    });
+
+    child.on('close', (code) => process.exit(code ?? 0));
+    child.on('error', (err) => {
+      console.error(`orchard: failed to start server: ${err.message}`);
+      process.exit(1);
+    });
+    process.on('SIGTERM', () => child.kill('SIGTERM'));
+    process.on('SIGINT', () => child.kill('SIGINT'));
+    return;
+  }
+
+  if (command === 'connect') {
+    const { connect: farmerConnect } = require('../lib/farmer.js');
+    const connectArgs = process.argv.slice(process.argv.indexOf('connect') + 1);
+    const rootIdx = connectArgs.indexOf('--root');
+    let targetDir = process.cwd();
+    if (rootIdx !== -1 && connectArgs[rootIdx + 1]) {
+      targetDir = path.resolve(connectArgs[rootIdx + 1]);
+    }
+    await farmerConnect(targetDir, connectArgs);
+    return;
+  }
+
+  if (command === 'init') {
+    const { parseArgs } = require('node:util');
+    let rootDir = process.cwd();
+    try {
+      const { values } = parseArgs({ args: process.argv.slice(3), options: { root: { type: 'string' } }, allowPositionals: true });
+      if (values.root) rootDir = path.resolve(values.root);
+    } catch (_) { /* ignore parse errors for init */ }
+    const configPath = path.join(rootDir, 'orchard.json');
+    if (fs.existsSync(configPath)) {
+      console.error('orchard: orchard.json already exists');
+      process.exit(1);
+    }
+    const defaultConfig = { sprints: [], settings: { sync_interval: 'manual' } };
+    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf8');
+    console.log('Initialized orchard.json — add sprints with `orchard plan`');
+    process.exit(0);
+  }
+
+  const root = findOrchardRoot();
+  if (!root && command !== 'help' && command !== 'doctor') {
+    console.error('orchard: no orchard.json found. Run from a directory with orchard.json or a subdirectory.');
+    console.error('');
+    console.error('Create one:');
+    console.error('  { "sprints": [] }');
+    process.exit(1);
+  }
+
+  const config = root ? loadConfig(root) : { sprints: [] };
+  const jsonMode = args.includes('--json');
+
+  switch (command) {
+    case 'plan': {
+      if (jsonMode) {
+        const { buildGraph, topoSort, detectCycles } = require('../lib/planner.js');
+        const graph = buildGraph(config);
+        const order = topoSort(config);
+        const cycles = detectCycles(config);
+        console.log(JSON.stringify({ graph, order, cycles }, null, 2));
+        break;
+      }
+      const { printDependencyGraph } = require('../lib/planner.js');
+      printDependencyGraph(config, root);
+      break;
+    }
+    case 'status': {
+      if (jsonMode) {
+        const { getStatusData } = require('../lib/tracker.js');
+        const data = getStatusData(config, root);
+        console.log(JSON.stringify(data, null, 2));
+        break;
+      }
+      const { printStatus } = require('../lib/tracker.js');
+      printStatus(config, root);
+      break;
+    }
+    case 'assign': {
+      const sprintPath = args[1];
+      const person = args[2];
+      if (!sprintPath || !person) {
+        console.error('orchard: usage: orchard assign <sprint-path> <person>');
+        process.exit(1);
+      }
+      const { assignSprint } = require('../lib/assignments.js');
+      assignSprint(config, root, sprintPath, person);
+      break;
+    }
+    case 'sync': {
+      const { syncAll } = require('../lib/sync.js');
+      syncAll(config, root);
+      break;
+    }
+    case 'dashboard': {
+      const { generateDashboard } = require('../lib/dashboard.js');
+      const outPath = args[1] || path.join(root, 'orchard-dashboard.html');
+      generateDashboard(config, root, outPath);
+      break;
+    }
+    case 'doctor': {
+      const { runChecks, printReport } = require('../lib/doctor.js');
+      const result = runChecks(root || process.cwd());
+      if (jsonMode) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printReport(result);
+      }
+      if (!result.ok) process.exit(1);
+      break;
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(`orchard: ${err.message}`);
+  process.exit(1);
+});

package/lib/assignments.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Assign a person to a sprint. Updates orchard.json.
+ */
+function assignSprint(config, root, sprintPath, person) {
+  const sprint = (config.sprints || []).find((s) => s.path === sprintPath);
+
+  if (!sprint) {
+    console.error(`Sprint not found: ${sprintPath}`);
+    console.error('Available sprints:');
+    for (const s of config.sprints || []) {
+      console.error(`  ${s.path}`);
+    }
+    process.exit(1);
+  }
+
+  const prev = sprint.assigned_to;
+  sprint.assigned_to = person;
+
+  const configPath = path.join(root, 'orchard.json');
+  const tmp = configPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
+  fs.renameSync(tmp, configPath);
+
+  if (prev) {
+    console.log(`Reassigned ${path.basename(sprintPath)}: ${prev} -> ${person}`);
+  } else {
+    console.log(`Assigned ${path.basename(sprintPath)} to ${person}`);
+  }
+}
+
+/**
+ * Get workload summary: how many sprints per person.
+ */
+function getWorkload(config) {
+  const workload = new Map();
+
+  for (const sprint of config.sprints || []) {
+    const person = sprint.assigned_to || 'unassigned';
+    if (!workload.has(person)) {
+      workload.set(person, []);
+    }
+    workload.get(person).push(sprint);
+  }
+
+  return workload;
+}
+
+/**
+ * Print workload distribution.
+ */
+function printWorkload(config) {
+  const workload = getWorkload(config);
+
+  console.log('');
+  console.log('  Workload Distribution');
+  console.log('  ' + '-'.repeat(40));
+
+  for (const [person, sprints] of workload) {
+    const active = sprints.filter((s) => s.status !== 'done').length;
+    console.log(`  ${person}: ${sprints.length} sprints (${active} active)`);
+    for (const s of sprints) {
+      const status = s.status || 'unknown';
+      console.log(`    - ${path.basename(s.path)} [${status}]`);
+    }
+  }
+
+  console.log('');
+}
+
+/**
+ * Find overloaded team members (more than maxLoad active sprints).
+ */
+function findOverloaded(config, maxLoad = 3) {
+  const workload = getWorkload(config);
+  const overloaded = [];
+
+  for (const [person, sprints] of workload) {
+    if (person === 'unassigned') continue;
+    const active = sprints.filter((s) => s.status !== 'done').length;
+    if (active > maxLoad) {
+      overloaded.push({ person, active, sprints });
+    }
+  }
+
+  return overloaded;
+}
+
+module.exports = {
+  assignSprint,
+  getWorkload,
+  printWorkload,
+  findOverloaded,
+};

package/lib/conflicts.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Load claims from a sprint directory.
+ */
+function loadClaims(sprintPath, root) {
+  const absPath = path.isAbsolute(sprintPath) ? sprintPath : path.join(root, sprintPath);
+  const claimsPath = path.join(absPath, 'claims.json');
+
+  if (!fs.existsSync(claimsPath)) return [];
+
+  try {
+    const data = JSON.parse(fs.readFileSync(claimsPath, 'utf8'));
+    const claims = Array.isArray(data) ? data : (data.claims || []);
+    return claims.map((c) => ({ ...c, _source: sprintPath }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Detect potential conflicts between claims across sprints.
+ *
+ * Conflict heuristics:
+ * 1. Same-type claims with contradicting content (recommendations that oppose each other)
+ * 2. Constraints that conflict with recommendations from other sprints
+ * 3. Estimates with non-overlapping ranges on the same topic
+ *
+ * Returns array of { type, claimA, claimB, reason }
+ */
+function detectConflicts(config, root) {
+  const allClaims = [];
+
+  for (const sprint of config.sprints || []) {
+    const claims = loadClaims(sprint.path, root);
+    allClaims.push(...claims);
+  }
+
+  const conflicts = [];
+
+  // Group claims by tags for overlap detection
+  const byTag = new Map();
+  for (const claim of allClaims) {
+    for (const tag of claim.tags || []) {
+      if (!byTag.has(tag)) byTag.set(tag, []);
+      byTag.get(tag).push(claim);
+    }
+  }
+
+  // Check for cross-sprint conflicts within same tag
+  for (const [tag, claims] of byTag) {
+    for (let i = 0; i < claims.length; i++) {
+      for (let j = i + 1; j < claims.length; j++) {
+        const a = claims[i];
+        const b = claims[j];
+
+        // Only flag cross-sprint conflicts
+        if (a._source === b._source) continue;
+
+        // Opposing recommendations
+        if (a.type === 'recommendation' && b.type === 'recommendation') {
+          if (couldContradict(a.text, b.text)) {
+            conflicts.push({
+              type: 'opposing-recommendations',
+              claimA: a,
+              claimB: b,
+              tag,
+              reason: `Both sprints recommend on "${tag}" but may conflict`,
+            });
+          }
+        }
+
+        // Constraint vs recommendation
+        if (
+          (a.type === 'constraint' && b.type === 'recommendation') ||
+          (a.type === 'recommendation' && b.type === 'constraint')
+        ) {
+          conflicts.push({
+            type: 'constraint-recommendation-tension',
+            claimA: a,
+            claimB: b,
+            tag,
+            reason: `Constraint from ${a._source} may conflict with recommendation from ${b._source}`,
+          });
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Simple heuristic: two texts might contradict if they share keywords
+ * but use opposing qualifiers. This is intentionally conservative --
+ * false positives are better than missed conflicts.
+ */
+function couldContradict(textA, textB) {
+  if (!textA || !textB) return false;
+
+  const negators = ['not', 'no', 'never', 'avoid', 'instead', 'rather', 'without', 'dont', "don't"];
+  const aWords = new Set(textA.toLowerCase().split(/\s+/));
+  const bWords = new Set(textB.toLowerCase().split(/\s+/));
+
+  const aNeg = negators.some((n) => aWords.has(n));
+  const bNeg = negators.some((n) => bWords.has(n));
+
+  // One negated, one not -- possible contradiction
+  if (aNeg !== bNeg) return true;
+
+  return false;
+}
+
+/**
+ * Print conflict report.
+ */
+function printConflicts(config, root) {
+  const conflicts = detectConflicts(config, root);
+
+  if (conflicts.length === 0) {
+    console.log('');
+    console.log('  No cross-sprint conflicts detected.');
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  console.log(`  ${conflicts.length} potential conflict(s) detected`);
+  console.log('  ' + '='.repeat(50));
+
+  for (const c of conflicts) {
+    console.log('');
+    console.log(`  [${c.type}] tag: ${c.tag}`);
+    console.log(`    Sprint A: ${c.claimA._source} (${c.claimA.id})`);
+    console.log(`    Sprint B: ${c.claimB._source} (${c.claimB.id})`);
+    console.log(`    Reason: ${c.reason}`);
+  }
+
+  console.log('');
+}
+
+module.exports = {
+  loadClaims,
+  detectConflicts,
+  couldContradict,
+  printConflicts,
+};