@grainulation/orchard 1.0.0 → 1.0.2

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our standards
+
+We are committed to providing a welcoming and productive environment for everyone. We expect participants to:
+
+- Use welcoming and inclusive language
+- Respect differing viewpoints and experiences
+- Accept constructive criticism gracefully
+- Focus on what is best for the community and the project
+- Show empathy toward other participants
+
+Unacceptable behavior includes harassment, trolling, personal attacks, and publishing others' private information without permission.
+
+## Scope
+
+This code of conduct applies to all project spaces -- issues, pull requests, discussions, and any public channel where someone represents the project.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated, and will result in a response deemed necessary and appropriate.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to Orchard
+
+Thanks for considering contributing. Orchard is the multi-sprint planner for the grainulation ecosystem -- it tracks dependencies, assignments, and timelines across concurrent sprints.
+
+## Quick setup
+
+```bash
+git clone https://github.com/grainulation/orchard.git
+cd orchard
+node bin/orchard.js --help
+```
+
+No `npm install` needed -- orchard has zero dependencies.
+
+## How to contribute
+
+### Report a bug
+
+Open an issue with:
+
+- What you expected
+- What happened instead
+- Your Node version (`node --version`)
+- Steps to reproduce
+
+### Suggest a feature
+
+Open an issue describing the use case, not just the solution. "I need X because Y" is more useful than "add X."
+
+### Submit a PR
+
+1. Fork the repo
+2. Create a branch (`git checkout -b fix/description`)
+3. Make your changes
+4. Run the tests: `node test/basic.test.js`
+5. Commit with a clear message
+6. Open a PR
+
+## Architecture
+
+```
+bin/orchard.js            CLI entrypoint -- dispatches subcommands
+lib/scanner.js            Auto-detects active sprints in a workspace
+lib/planner.js            Sprint planning and scheduling logic
+lib/tracker.js            Progress tracking across sprints
+lib/dependencies.js       Cross-sprint dependency resolution
+lib/conflicts.js          Conflict detection between parallel sprints
+lib/assignments.js        Work assignment and load balancing
+lib/timeline.js           Timeline generation and critical path
+lib/sync.js               State synchronization across sprint repos
+lib/export.js             Export planner data to various formats
+lib/dashboard.js          Dashboard data aggregation
+lib/server.js             Local preview server (SSE, zero deps)
+templates/                HTML templates (orchard-dashboard, etc.)
+public/                   Web UI -- multi-sprint planning dashboard
+site/                     Public website (orchard.grainulation.com)
+test/                     Node built-in test runner tests
+```
+
+The key architectural principle: **orchard operates above individual sprints.** It scans for active wheat sprints, detects dependencies and conflicts between them, and provides a unified planning view. It reads sprint data but never modifies it directly.
+
+## Code style
+
+- Zero dependencies. If you need something, write it or use Node built-ins.
+- No transpilation. Ship what you write.
+- ESM imports (`import`/`export`). Node 18+ required.
+- Keep functions small. If a function needs a scroll, split it.
+- No emojis in code, CLI output, or dashboards.
+
+## Testing
+
+```bash
+node test/basic.test.js
+```
+
+Tests use Node's built-in test runner. No test framework dependencies.
+
+## Commit messages
+
+Follow the existing pattern:
+
+```
+orchard: <what changed>
+```
+
+Examples:
+
+```
+orchard: add cross-sprint dependency graph
+orchard: fix timeline calculation for overlapping sprints
+orchard: update scanner to detect archived sprints
+```
+
+## License
+
+MIT. See LICENSE for details.

package/README.md

@@ -1,28 +1,31 @@
-# @grainulation/orchard
+<p align="center">
+  <img src="site/wordmark.svg" alt="Orchard" width="400">
+</p>
 
-> 12 sprints running. One command to see them all.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@grainulation/orchard"><img src="https://img.shields.io/npm/v/@grainulation/orchard" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/orchard"><img src="https://img.shields.io/npm/dm/@grainulation/orchard" alt="npm downloads"></a> <a href="https://github.com/grainulation/orchard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/orchard" alt="node"></a> <a href="https://github.com/grainulation/orchard/actions"><img src="https://github.com/grainulation/orchard/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://deepwiki.com/grainulation/orchard"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
+</p>
 
-**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.
+<p align="center"><strong>Multi-sprint orchestration and dependency tracking.</strong></p>
+
+12 sprints running. One command to see them all. Orchard coordinates parallel research across teams with dependency graphs, conflict detection, and unified dashboards.
 
 ## Install
 
 ```bash
-npx @grainulation/orchard status
+npm install -g @grainulation/orchard
 ```
 
-## What it does
+Or use directly:
 
-- **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**
+```bash
+npx @grainulation/orchard status
+```
 
 ## Quick start
 
-Create a `orchard.json` in your project root:
+Create `orchard.json` in your project root:
 
 ```json
 {
@@ -50,68 +53,56 @@ Create a `orchard.json` in your project root:
 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
+orchard plan        # Show the dependency graph
+orchard status      # Check status of all sprints
+orchard sync        # Sync status from sprint directories
+orchard dashboard   # Generate unified HTML 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
+## What it does
 
-```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
-  }>
-}
-```
+- **Sprint dependency graphs** -- "sprint B needs sprint A's results first"
+- **Cross-sprint conflict detection** -- when two sprints reach opposing conclusions
+- **Team assignment** -- who's running which sprint
+- **Unified status dashboard** across all active sprints
+- **Sprint scheduling and deadline tracking**
+- **Topological sort** -- determines execution order, flags cycles
 
-## How it works
+## CLI
 
-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.
+| Command                          | Description                              |
+| -------------------------------- | ---------------------------------------- |
+| `orchard plan`                   | Show sprint dependency graph             |
+| `orchard status`                 | Show status of all tracked sprints       |
+| `orchard assign <path> <person>` | Assign a person to a sprint              |
+| `orchard sync`                   | Sync sprint states from directories      |
+| `orchard dashboard [outfile]`    | Generate unified HTML dashboard          |
+| `orchard init`                   | Initialize orchard.json                  |
+| `orchard serve`                  | Start the portfolio dashboard web server |
 
-### Conflict detection
+## Conflict detection
 
 Orchard flags two types of cross-sprint conflicts:
 
-1. **Opposing recommendations** -- two sprints make recommendations on the same topic that may contradict
+1. **Opposing recommendations** -- two sprints make recommendations on the same topic that contradict
 2. **Constraint-recommendation tension** -- one sprint's constraints conflict with another's recommendations
 
-### Dependency tracking
+## Zero dependencies
 
-Sprints can declare dependencies. Orchard uses topological sorting to determine execution order and flags cycles. The `plan` command renders this as ASCII art.
+Node built-in modules only.
 
-## Zero dependencies
+## Part of the grainulation ecosystem
 
-Orchard uses only Node.js built-in modules. No npm install required.
+| Tool                                                         | Role                                                        |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| [wheat](https://github.com/grainulation/wheat)               | Research engine -- grow structured evidence                 |
+| [farmer](https://github.com/grainulation/farmer)             | Permission dashboard -- approve AI actions in real time     |
+| [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**                                                  | Orchestration -- multi-sprint coordination and dependencies |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem          |
 
 ## License