@grainulation/wheat 1.0.0 → 1.0.1

package/README.md

@@ -1,20 +1,28 @@
-# wheat
+<p align="center">
+  <img src="site/wordmark.svg" alt="Wheat" width="400">
+</p>
 
-**You're about to mass-migrate 200 microservices. Slow down.**
+<p align="center">
+  <a href="https://www.npmjs.com/package/@grainulation/wheat"><img src="https://img.shields.io/npm/v/@grainulation/wheat" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/wheat"><img src="https://img.shields.io/npm/dm/@grainulation/wheat" alt="npm downloads"></a> <a href="https://github.com/grainulation/wheat/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@grainulation/wheat" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/wheat" alt="node"></a> <a href="https://github.com/grainulation/wheat/actions"><img src="https://github.com/grainulation/wheat/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
 
-The migration will take months. It will cost real money. And right now, the decision to move is based on a Slack thread, a blog post, and a gut feeling from someone who left the company.
+<p align="center"><strong>CI/CD for technical decisions.</strong></p>
 
-Wheat exists because the most expensive engineering decisions are made with the least structured evidence. Not because people are careless -- because there's no tool that makes structured investigation feel natural.
+You're about to mass-migrate 200 microservices. Slow down.
 
-## The idea
+The migration will take months. It will cost real money. And right now, the decision to move is based on a Slack thread, a blog post, and a gut feeling from someone who left the company.
 
-Wheat is a research sprint framework. You point it at a question -- "Should we migrate to Postgres?", "Is this architecture going to scale?", "Which vendor should we pick?" -- and it helps you build an evidence base before you commit.
+You'd never ship code without tests. Why ship a decision without validated evidence?
 
-Every finding becomes a typed, evidence-graded claim. A constraint from your VP is different from a benchmark you ran, and wheat tracks the difference. When two findings contradict each other, the compiler catches it. When you try to ship a recommendation backed by nothing but blog posts, it warns you.
+Wheat is a continuous planning pipeline. Every finding is a typed assertion. A compiler validates them. You can't ship with contradictions, same as you can't merge with failing tests.
 
-The process is intentionally slow. You gather evidence from multiple sources. You grade how much you trust each piece. You challenge your own assumptions. Then -- and only then -- you compile it into a recommendation you can defend.
+## Install
 
-If that sounds like a lot of work: it is. That's the point. The work happens before you commit a team to six months of migration, not after.
+```bash
+npx @grainulation/wheat init
+```
+
+No dependencies are added to your project. No `node_modules` pollution. Wheat is a tool you run, not a library you import.
 
 ## See it in 30 seconds
 
@@ -22,20 +30,20 @@ If that sounds like a lot of work: it is. That's the point. The work happens bef
 npx @grainulation/wheat quickstart
 ```
 
-Creates a demo sprint with pre-seeded claims, an intentional conflict, compiles everything, and opens a dashboard. You'll see the compiler flag the conflict and block output until it's resolved.
+Creates a demo build with pre-seeded assertions, an intentional conflict, compiles everything, and opens a dashboard. You'll see the compiler flag the conflict and block output until it's resolved.
 
-## Start a real sprint
+## Start a real investigation
 
 ```bash
 npx @grainulation/wheat init
 ```
 
-Wheat asks a few questions -- what you're investigating, who needs the answer, what constraints exist. Then it sets up the sprint in your repo:
+Wheat asks a few questions -- what you're investigating, who needs the answer, what constraints exist. Then it scaffolds the investigation in your repo:
 
 ```
-claims.json          # Your evidence database
+claims.json          # Typed assertions (the test suite for your decision)
 CLAUDE.md            # AI assistant configuration
-.claude/commands/    # 17 research slash commands
+.claude/commands/    # 18 slash commands
 output/              # Where compiled artifacts land
 ```
 
@@ -51,46 +59,20 @@ Open Claude Code and start investigating:
 
 ## How it works
 
-Wheat uses a claim-based system inspired by compiler design:
+Wheat is a continuous planning pipeline. Findings are validated as they come in, not after the fact:
 
 ```
-You investigate  -->  Claims accumulate  -->  Compiler validates  -->  Artifacts compile
-   /research          claims.json            wheat compile            /brief, /present
-   /prototype         (typed, graded)        (7-pass pipeline)        (backed by evidence)
+You investigate  -->  Assertions accumulate  -->  Compiler validates  -->  Artifacts compile
+   /research          claims.json                 wheat compile            /brief, /present
+   /prototype         (typed, evidence-graded)    (7-pass pipeline)        (backed by evidence)
    /challenge
 ```
 
-**Claim types:** constraint, factual, estimate, risk, recommendation, feedback
-
-**Evidence tiers:** stated -> web -> documented -> tested -> production
-
-The compiler catches conflicts, warns about weak evidence, and blocks output when issues exist. You cannot ship a brief built on unresolved contradictions.
-
-## Works in any repo
-
-Wheat doesn't care what language you use. It runs via npx and stores sprint data in your repo. Your Scala project, your Python monorepo, your Flutter app -- wheat works the same everywhere.
-
-```bash
-# In a Scala repo
-npx @grainulation/wheat init
-
-# In a Python repo
-npx @grainulation/wheat init
-
-# Compiles anywhere Node 18+ is available
-npx @grainulation/wheat compile --summary
-```
-
-No dependencies are added to your project. No `node_modules` pollution. Wheat is a tool you run, not a library you import.
+**Assertion types:** constraint, factual, estimate, risk, recommendation, feedback
 
-## Guard rails
+**Evidence tiers** (like test coverage): stated (untested) > web > documented > tested > production (battle-hardened)
 
-Wheat installs two guard mechanisms:
-
-1. **Git pre-commit hook** -- prevents committing broken `claims.json`
-2. **Claude Code guard hook** -- prevents generating output artifacts from stale or blocked compilations
-
-Both are optional and can be removed. But they exist because the most dangerous moment in a research sprint is when you skip the process.
+The compiler catches conflicts, warns about weak evidence, and blocks the build when issues exist. You cannot ship a brief built on unresolved contradictions — same as you can't merge with failing tests.
 
 ## Commands
 
@@ -112,24 +94,38 @@ Both are optional and can be removed. But they exist because the most dangerous
 | `/handoff` | Package sprint for knowledge transfer |
 | `/merge <path>` | Combine findings across sprints |
 | `/connect <type>` | Link external tools (Jira, docs, etc.) |
+| `/evaluate` | Test claims against reality, resolve conflicts |
+| `/next` | Route next steps through Farmer (mobile feedback) |
+
+## Guard rails
+
+Wheat installs two guard mechanisms:
 
-## Documentation
+1. **Git pre-commit hook** -- prevents committing broken `claims.json`
+2. **Claude Code guard hook** -- prevents generating output artifacts from stale or blocked compilations
 
-- **[Concepts](docs/concepts.md)** -- claims, phases, evidence tiers, the compiler
-- **[Commands](docs/commands.md)** -- every slash command with usage examples
-- **[FAQ](docs/faq.md)** -- setup, data, usage, and troubleshooting
+Both are optional and can be removed.
 
-## Platform support
+## Works in any repo
 
-Wheat runs on macOS, Linux, and Windows. All path handling uses `path.join`/`path.sep` internally, and git commands are invoked via `execFileSync` (no shell). The pre-commit hook requires Git Bash on Windows (bundled with Git for Windows).
+Wheat doesn't care what language you use. Your Scala project, your Python monorepo, your Flutter app -- wheat works the same everywhere. Node 18+ is the only requirement.
 
-On Windows, use `npx @grainulation/wheat` directly -- Node 18+ is the only requirement.
+## Zero dependencies
 
-## Contributing
+Node built-in modules only. No npm install waterfall. No supply chain anxiety.
 
-We'd love your help. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+## Part of the grainulation ecosystem
 
-Good first issues are labeled [`good first issue`](https://github.com/grainulation/wheat/labels/good%20first%20issue).
+| Tool | Role |
+|------|------|
+| **wheat** | Research engine -- grow structured evidence |
+| [farmer](https://github.com/grainulation/farmer) | Permission dashboard -- approve AI actions in real time (admin + viewer roles) |
+| [barn](https://github.com/grainulation/barn) | Shared tools -- templates, validators, sprint detection |
+| [mill](https://github.com/grainulation/mill) | Format conversion -- export to PDF, CSV, slides, 24 formats |
+| [silo](https://github.com/grainulation/silo) | Knowledge storage -- reusable claim libraries and packs |
+| [harvest](https://github.com/grainulation/harvest) | Analytics -- cross-sprint patterns and prediction scoring |
+| [orchard](https://github.com/grainulation/orchard) | Orchestration -- multi-sprint coordination and dependencies |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem |
 
 ## License
 

package/bin/wheat.js

@@ -88,6 +88,7 @@ Examples:
   npx @grainulation/wheat init
   npx @grainulation/wheat compile --summary
   npx @grainulation/wheat init --question "Should we migrate to Postgres?"
+  npx @grainulation/wheat init --non-interactive --question "..." --audience "..." --done "..."
 
 Documentation: https://github.com/grainulation/wheat`);
   process.exit(0);

package/compiler/detect-sprints.js

@@ -26,6 +26,8 @@
 
 import fs from 'fs';
 import path from 'path';
+// execFileSync used to query git history (no shell, array args only).
+// Socket.dev flags this as "shell access" but execFileSync bypasses the shell.
 import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 

package/compiler/wheat-compiler.js

@@ -914,6 +914,28 @@ if (args.includes('--summary')) {
     console.log('Errors:');
     c.errors.forEach(e => console.log(`  ${e.code}: ${e.message}`));
     console.log();
+
+    // Show expected shape if schema errors exist
+    const hasSchemaErrors = c.errors.some(e => e.code === 'E_SCHEMA' || e.code === 'E_TYPE' || e.code === 'E_EVIDENCE_TIER');
+    if (hasSchemaErrors) {
+      console.log('  Expected claim shape:');
+      console.log('    {');
+      console.log('      "id": "r001",');
+      console.log('      "type": "constraint|factual|estimate|risk|recommendation|feedback",');
+      console.log('      "topic": "topic-slug",');
+      console.log('      "content": "The claim text",');
+      console.log('      "source": { "origin": "research", "artifact": null, "connector": null },');
+      console.log('      "evidence": "stated|web|documented|tested|production",');
+      console.log('      "status": "active",');
+      console.log('      "phase_added": "define|research|prototype|evaluate|feedback|challenge",');
+      console.log('      "timestamp": "2026-01-01T00:00:00.000Z",');
+      console.log('      "conflicts_with": [],');
+      console.log('      "resolved_by": null,');
+      console.log('      "tags": []');
+      console.log('    }');
+      console.log();
+      console.log('  Hint: Run "wheat init --headless --question ..." to generate a valid claims.json');
+    }
   }
 
   if (c.warnings.length > 0) {

package/lib/connect.js

@@ -275,6 +275,8 @@ function printSuccess(farmerUrl, settingsPath, dryRun) {
   console.log('    - Farmer is running and responding to hook probes');
   console.log('    - SSE event stream is available for live monitoring');
   console.log('    - Hooks were merged without overwriting existing settings');
+  console.log('    - Slash commands installed/updated');
+  console.log('    - .farmer-config.json written with sprint paths');
   console.log();
   console.log('  What to do next:');
   console.log('    Open Claude Code in this directory. If Farmer goes down,');
@@ -410,6 +412,39 @@ export async function run(dir, args) {
   // Step 3: Write settings atomically
   await writeSettingsAtomic(settingsPath, merged);
 
+  // Install/update slash commands
+  try {
+    const updateModule = await import(new URL('./update.js', import.meta.url).href);
+    await updateModule.run(targetDir, ['--force']);
+  } catch (err) {
+    console.log(`  \x1b[33m!\x1b[0m Could not install slash commands: ${err.message}`);
+  }
+
+  // Write sprint paths to .farmer-config.json so farmer auto-discovers them
+  const farmerConfigPath = path.join(targetDir, '.farmer-config.json');
+  try {
+    let farmerConfig = {};
+    if (fs.existsSync(farmerConfigPath)) {
+      farmerConfig = JSON.parse(fs.readFileSync(farmerConfigPath, 'utf8'));
+    }
+    const claimsPath = path.join(targetDir, 'claims.json');
+    const compilationPath = path.join(targetDir, 'compilation.json');
+    if (fs.existsSync(claimsPath) || true) {  // Always write paths, claims may come later
+      farmerConfig.claimsPath = claimsPath;
+      farmerConfig.compilationPath = compilationPath;
+    }
+    if (!farmerConfig.registeredProjects) {
+      farmerConfig.registeredProjects = [];
+    }
+    if (!farmerConfig.registeredProjects.includes(targetDir)) {
+      farmerConfig.registeredProjects.push(targetDir);
+    }
+    fs.writeFileSync(farmerConfigPath, JSON.stringify(farmerConfig, null, 2) + '\n');
+    console.log(`  \x1b[32m+\x1b[0m .farmer-config.json (sprint paths registered)`);
+  } catch (err) {
+    console.log(`  \x1b[33m!\x1b[0m Could not write .farmer-config.json: ${err.message}`);
+  }
+
   if (flags.json) {
     console.log(JSON.stringify({ success: true, url: farmerUrl, settingsPath, verified: detection.verified }));
   } else {

package/lib/init.js

@@ -258,17 +258,28 @@ function installGitHook(dir) {
   const hookPath = path.join(hooksDir, 'pre-commit');
 
   // The hook snippet — runs wheat compile --check before allowing commits
-  // Uses Node for the check logic so it works on both Unix (sh) and Windows (Git Bash)
+  // Prefers local wheat binary (node_modules/.bin/wheat) over npx to avoid
+  // auto-fetching from registry on every commit. Falls back to npx if not installed.
   const WHEAT_MARKER = '# wheat-guard';
   const escapedDir = dir.replace(/\\/g, '/');   // Normalize Windows backslashes for shell
   const hookSnippet = `
 ${WHEAT_MARKER}
 # Wheat pre-commit: verify claims compile before committing
 if git diff --cached --name-only | grep -q 'claims.json'; then
-  npx --yes @grainulation/wheat compile --check --dir "${escapedDir}" 2>/dev/null
-  if [ $? -ne 0 ]; then
-    echo "wheat: claims.json has compilation errors. Run 'wheat compile --summary' to see details."
-    exit 1
+  WHEAT_BIN=""
+  if command -v wheat >/dev/null 2>&1; then
+    WHEAT_BIN="wheat"
+  elif [ -x "./node_modules/.bin/wheat" ]; then
+    WHEAT_BIN="./node_modules/.bin/wheat"
+  elif command -v npx >/dev/null 2>&1; then
+    WHEAT_BIN="npx @grainulation/wheat"
+  fi
+  if [ -n "$WHEAT_BIN" ]; then
+    $WHEAT_BIN compile --check --dir "${escapedDir}" 2>/dev/null
+    if [ $? -ne 0 ]; then
+      echo "wheat: claims.json has compilation errors. Run 'wheat compile --summary' to see details."
+      exit 1
+    fi
   fi
 fi
 `;
@@ -310,7 +321,7 @@ export async function run(dir, args) {
 
   let meta;
 
-  if (flags.headless) {
+  if (flags.headless || flags['non-interactive']) {
     // ── Headless mode — all flags required ──
     const missing = [];
     if (!flags.question) missing.push('--question');
@@ -444,7 +455,7 @@ export async function run(dir, args) {
   console.log('  Created:');
   console.log('    claims.json           Your evidence database');
   console.log('    CLAUDE.md             AI assistant configuration');
-  console.log('    .claude/commands/     17 slash commands for Claude Code');
+  console.log('    .claude/commands/     18 slash commands for Claude Code');
   console.log('    output/               Where compiled artifacts land');
   console.log();
   console.log('  Next steps:');

package/lib/serve-mcp.js

@@ -10,6 +10,7 @@
  *   wheat/resolve   -- Adjudicate a specific conflict
  *   wheat/search    -- Query claims by topic, type, evidence tier
  *   wheat/status    -- Return compilation summary
+ *   wheat/init      -- Initialize a new research sprint
  *
  * Resources:
  *   wheat://compilation -- Current compilation.json
@@ -27,7 +28,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -82,7 +83,7 @@ function toolCompile(dir) {
   }
 
   try {
-    const output = execSync(`node "${compilerPath}" --summary --dir "${dir}"`, {
+    const output = execFileSync('node', [compilerPath, '--summary', '--dir', dir], {
       cwd: dir,
       encoding: 'utf8',
       timeout: 30000,
@@ -250,6 +251,42 @@ function toolStatus(dir) {
   };
 }
 
+function toolInit(dir, args) {
+  const paths = resolvePaths(dir);
+
+  if (!args.question) {
+    return { status: 'error', message: 'Required field: question' };
+  }
+
+  if (fs.existsSync(paths.claims) && !args.force) {
+    return { status: 'error', message: 'Sprint already exists (claims.json found). Pass force: true to reinitialize.' };
+  }
+
+  const initArgs = [
+    path.join(__dirname, '..', 'bin', 'wheat.js'),
+    'init', '--headless',
+    '--question', args.question,
+    '--audience', args.audience || 'self',
+    '--constraints', args.constraints || 'none',
+    '--done', args.done || 'A recommendation with evidence',
+    '--dir', dir,
+  ];
+
+  if (args.force) initArgs.push('--force');
+
+  try {
+    const output = execFileSync('node', initArgs, {
+      cwd: dir,
+      encoding: 'utf8',
+      timeout: 15000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { status: 'ok', message: 'Sprint initialized.', output: output.trim() };
+  } catch (err) {
+    return { status: 'error', message: (err.stderr || err.stdout || err.message).trim() };
+  }
+}
+
 // --- Tool & Resource definitions ---------------------------------------------
 
 const TOOLS = [
@@ -311,6 +348,21 @@ const TOOLS = [
       properties: {},
     },
   },
+  {
+    name: 'wheat/init',
+    description: 'Initialize a new research sprint. Creates claims.json, CLAUDE.md, and slash commands.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        question: { type: 'string', description: 'The research question for this sprint' },
+        audience: { type: 'string', description: 'Comma-separated list of audience (default: self)' },
+        constraints: { type: 'string', description: 'Semicolon-separated constraints (default: none)' },
+        done: { type: 'string', description: 'What "done" looks like (default: A recommendation with evidence)' },
+        force: { type: 'boolean', description: 'Reinitialize even if sprint exists (default: false)' },
+      },
+      required: ['question'],
+    },
+  },
 ];
 
 const RESOURCES = [
@@ -373,6 +425,9 @@ function handleRequest(dir, method, params, id) {
         case 'wheat/status':
           result = toolStatus(dir);
           break;
+        case 'wheat/init':
+          result = toolInit(dir, toolArgs);
+          break;
         default:
           return jsonRpcError(id, -32601, `Unknown tool: ${toolName}`);
       }
@@ -493,6 +548,7 @@ Tools exposed:
   wheat/resolve     Resolve a conflict
   wheat/search      Search claims
   wheat/status      Sprint status
+  wheat/init        Initialize a new sprint
 
 Resources exposed:
   wheat://compilation   compilation.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainulation/wheat",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Research-driven development framework — structured claims, compiled evidence, deterministic output",
   "license": "MIT",
   "author": "grainulation contributors",

package/templates/commands/next.md

@@ -0,0 +1,28 @@
+# /next -- Route next steps through Farmer
+
+You just finished a slash command or a batch of work. The user monitors via Farmer on their phone and cannot see CLI text output.
+
+Use AskUserQuestion to present what just happened and what comes next. This is the ONLY way the user sees results.
+
+## Process
+
+1. **Summarize** what was just produced in the question text (1-2 sentences -- claim counts, key findings, what changed)
+
+2. **Pick 2-4 next steps** based on sprint state. Use this decision tree:
+   - Unresolved conflicts exist -> suggest `/resolve`
+   - Claim has no corroboration -> suggest `/witness <id> <url>`
+   - Topic has weak evidence -> suggest `/research <topic>` or `/prototype`
+   - Sprint is late-phase with gaps -> suggest `/blind-spot`
+   - Sprint ready for output -> suggest `/brief`, `/present`, or `/handoff`
+   - Multiple sprints exist -> suggest `/merge`
+
+3. **Call AskUserQuestion** with the summary as the question and next steps as options. Keep option labels short (3-5 words), put detail in descriptions.
+
+4. **Act on the user's choice** -- run whatever they picked.
+
+## Rules
+
+- Header should be contextual (e.g., "After /brief", "After research")
+- Don't include a "do nothing" option unless the user might genuinely want to stop
+- If agents just completed, mention how many and what they did
+- multiSelect: false unless the options are independent parallel tasks