@shardworks/guild-starter-kit 0.1.16 → 0.1.18

package/curricula/guild-operations/content.md

@@ -40,14 +40,105 @@ Other roles may emerge as the guild evolves.
 
 ## Workshops
 
-A workshop is a repository where animas do their work. The patron assigns workshops (usually existing repos), and artificers work inside them on commissions. The patron judges results by the works produced, not by inspecting the workshop.
+A workshop is a repository where animas do their work. Workshops are guild space — the patron assigns them, but during normal operation the patron judges results by the works produced, not by inspecting the workshop directly.
 
-### Workshop Lifecycle
+Each workshop is registered in `guild.json` under the `workshops` key with its name, remote URL, and the timestamp it was added. On disk, the guild maintains a bare clone of each workshop at `.nexus/workshops/{name}.git`. Commission worktrees are created from these bare clones, giving each commission an isolated working directory.
 
-1. A workshop is registered with the guild (`nsg workshop add <url>`)
-2. The guild clones it and manages worktrees for concurrent commissions
-3. Artificers work in isolated worktrees — one per commission
-4. Completed work is delivered as branches or pull requests
+### Managing Workshops
+
+Four commands manage the workshop lifecycle:
+
+| Command | What it does |
+|---------|-------------|
+| `nsg workshop add <url>` | Clone a remote repo and register it as a workshop |
+| `nsg workshop remove <name>` | Remove a workshop — deletes bare clone, worktrees, and guild.json entry |
+| `nsg workshop list` | List all workshops with clone status and active worktree count |
+| `nsg workshop create <org/name>` | Create a new GitHub repo and register it as a workshop |
+
+### Adding an Existing Repository
+
+When the patron has an existing repository they want the guild to work on:
+
+```
+nsg workshop add https://github.com/org/my-app.git
+```
+
+This clones the repo as a bare clone into `.nexus/workshops/my-app.git` and adds it to `guild.json`. The workshop name is derived from the URL (the last path segment, minus `.git`). To use a custom name:
+
+```
+nsg workshop add https://github.com/org/my-app.git --name frontend
+```
+
+The repository must already exist and be accessible. SSH URLs work too:
+
+```
+nsg workshop add git@github.com:org/my-app.git
+```
+
+### Creating a New Repository
+
+For greenfield work where no repository exists yet:
+
+```
+nsg workshop create myorg/new-project
+```
+
+This requires the GitHub CLI (`gh`) to be installed and authenticated. The command:
+
+1. Creates the repository on GitHub (private by default)
+2. Clones it as a bare clone into `.nexus/workshops/`
+3. Registers it in `guild.json`
+
+For a public repository:
+
+```
+nsg workshop create myorg/new-project --public
+```
+
+If `gh` is not installed or not authenticated, the command fails with a clear message explaining what's needed.
+
+### Workshop Status
+
+`nsg workshop list` shows each workshop with:
+
+- **✓ / ✗** — whether the bare clone exists on disk (it may be missing after a fresh guild clone before running `nsg guild restore`)
+- **Active worktrees** — how many commissions currently have worktrees checked out
+- **Remote URL** — where the repo lives
+
+If a bare clone is missing, the output includes a hint to run `nsg guild restore`.
+
+### Removing a Workshop
+
+```
+nsg workshop remove my-app
+```
+
+This deletes the bare clone, any commission worktrees for that workshop, and removes the entry from `guild.json`. This is a destructive operation — the workshop's local state is gone. The remote repository is not affected.
+
+### How Workshops Are Used in Commissions
+
+When a commission is dispatched to a workshop, the worktree-setup engine:
+
+1. Creates a commission-specific branch from `main` in the workshop's bare clone
+2. Checks out a git worktree at `.nexus/worktrees/{workshop}/commission-{id}/`
+3. The anima works in this isolated directory
+
+This means multiple commissions can run concurrently in the same workshop without interfering with each other — each gets its own branch and working directory.
+
+### guild.json Shape
+
+```json
+{
+  "workshops": {
+    "my-app": {
+      "remoteUrl": "https://github.com/org/my-app.git",
+      "addedAt": "2026-03-24T12:00:00.000Z"
+    }
+  }
+}
+```
+
+The `remoteUrl` is the source of truth. The bare clone on disk is ephemeral and can be reconstructed from this URL by `nsg guild restore`.
 
 ## Commissions
 
@@ -58,7 +149,7 @@ A commission is a unit of work posted by the patron and undertaken by the guild.
 3. **In progress** — the artificer works in a workshop worktree
 4. **Completed** or **Failed** — work is delivered or the commission is marked as failed
 
-Use `nsg dispatch` to post and dispatch commissions.
+Use `nsg commission` to post commissions. The Clockworks handles the rest via standing orders.
 
 ## Tools
 
@@ -68,19 +159,27 @@ Tools that animas wield during work. Each tool ships with instructions delivered
 
 - **install-tool** — install new tools, engines, or bundles into the guild
 - **remove-tool** — remove installed tools
-- **dispatch** — post and dispatch commissions
+- **commission** — post commissions to the guild
 - **instantiate** — create new animas with assigned training and roles
 - **nexus-version** — report the installed Nexus framework version
+- **signal** — signal a custom guild event for the Clockworks
 
 ### Engines
 
-Automated mechanical processes with no AI involvement. Engines handle repeatable infrastructure work:
+Automated mechanical processes with no AI involvement. Two kinds:
+
+**Static engines** — bespoke APIs called by framework code. Not triggerable by standing orders.
 
 - **manifest** — composes anima instructions from codex, training, and tool instructions at session start
 - **mcp-server** — runs the MCP server that exposes tools to animas during sessions
 - **worktree-setup** — creates and manages git worktrees for commissions
 - **ledger-migrate** — applies database migrations to the Ledger
 
+**Clockwork engines** — purpose-built to respond to events via standing orders. Use the `engine()` SDK factory from `@shardworks/nexus-core`. The Clockworks runner calls them automatically when matching events fire.
+
+- **workshop-prepare** — creates a worktree when a commission is posted (`commission.posted` → `commission.ready`)
+- **workshop-merge** — merges a commission branch after the session ends (`commission.session.ended` → `commission.completed` or `commission.failed`)
+
 ## The Codex
 
 The guild's institutional body of policy and procedure — the employee handbook. Lives in `codex/` in the guildhall. Every anima receives the codex when manifested. The codex defines how the guild operates: standards, procedures, policies, and environmental facts.
@@ -89,7 +188,139 @@ Role-specific codex entries live in `codex/roles/` and are delivered only to ani
 
 ## The Ledger
 
-The guild's operational database (SQLite). Holds anima records, roster, commission history, compositions, and the audit trail. Lives at `.nexus/nexus.db` in the guildhall. Managed by the ledger-migrate engine.
+The guild's operational database (SQLite). Holds anima records, roster, commission history, compositions, events, and the audit trail. Lives at `.nexus/nexus.db` in the guildhall. Managed by the ledger-migrate engine.
+
+## The Clockworks
+
+The Clockworks is the guild's event-driven nervous system — it connects things that happen to things that should happen in response. It turns the guild from a purely imperative system into a reactive one.
+
+### Events
+
+An event is an immutable fact: *this happened*. Events are recorded in the Ledger and processed by the Clockworks runner.
+
+Two kinds:
+
+- **Framework events** — signaled automatically by the system (`commission.sealed`, `tool.installed`, `anima.instantiated`, etc.). Animas cannot signal these.
+- **Custom events** — declared by the guild in `guild.json` under `clockworks.events`. Animas signal these using the `signal` tool.
+
+### Standing Orders
+
+A standing order is a registered response to an event — guild policy that says "when X happens, do Y." Standing orders live in `guild.json` under `clockworks.standingOrders`.
+
+Three verbs:
+
+| Verb | What it does |
+|------|-------------|
+| **`run`** | Invokes a clockwork engine. No AI involved — deterministic automation. |
+| **`summon`** | Manifests an anima (by role) and delivers the event as urgent context. The anima is expected to act. |
+| **`brief`** | Manifests an anima (by role) and delivers the event as informational context. The anima decides whether to act. |
+
+Standing orders target **roles**, not named animas — durable across anima turnover.
+
+Example `guild.json` configuration:
+
+```json
+{
+  "clockworks": {
+    "events": {
+      "code.reviewed": {
+        "description": "Signaled when an artificer completes a code review"
+      }
+    },
+    "standingOrders": [
+      { "on": "commission.sealed", "run": "cleanup-worktree" },
+      { "on": "commission.failed", "summon": "advisor" },
+      { "on": "code.reviewed",     "brief": "guildmaster" }
+    ]
+  }
+}
+```
+
+### Signaling Events
+
+Use the **signal** tool to signal custom events:
+
+```
+signal({ name: "code.reviewed", payload: { pr: 42, issues_found: 0 } })
+```
+
+The event name must be declared in `guild.json clockworks.events`. Framework namespaces (`anima.*`, `commission.*`, `tool.*`, `migration.*`, `guild.*`, `standing-order.*`) are reserved.
+
+### Processing Events
+
+Events are not processed automatically. The operator controls when the Clockworks runs:
+
+| Command | What it does |
+|---------|-------------|
+| `nsg clock list` | Show all pending (unprocessed) events |
+| `nsg clock tick [id]` | Process the next pending event, or a specific one by id |
+| `nsg clock run` | Process all pending events until the queue is empty |
+
+### Error Handling
+
+When a standing order fails, the system signals a `standing-order.failed` event. Guilds can respond to this with their own standing orders. A loop guard prevents cascading failures.
+
+### Hello World Walkthrough
+
+To test the Clockworks from scratch:
+
+**1. Declare a custom event** in `guild.json`:
+
+```json
+{
+  "clockworks": {
+    "events": {
+      "hello.world": {
+        "description": "A test event for verifying the Clockworks"
+      }
+    },
+    "standingOrders": []
+  }
+}
+```
+
+**2. Signal the event:**
+
+```
+nsg signal hello.world --payload '{"message": "greetings from the Clockworks"}'
+```
+
+**3. Check the queue:**
+
+```
+nsg clock list
+```
+
+You should see the pending event with its id, name, payload, and timestamp.
+
+**4. Process it:**
+
+```
+nsg clock tick
+```
+
+Since there are no standing orders, the event is marked as processed with no dispatches.
+
+**5. Add a standing order** to `guild.json`:
+
+```json
+{
+  "clockworks": {
+    "standingOrders": [
+      { "on": "hello.world", "brief": "advisor" }
+    ]
+  }
+}
+```
+
+**6. Signal again and process:**
+
+```
+nsg signal hello.world
+nsg clock tick
+```
+
+The Clockworks matches the event to the standing order and dispatches it — the advisor is briefed.
 
 ## Training
 
@@ -103,6 +334,36 @@ Named, versioned, immutable personality templates. A temperament defines who an
 
 Training content lives in `training/curricula/` and `training/temperaments/` in the guildhall, organized as `{name}/{version}/`.
 
+## Guild Restore
+
+When the guildhall repository is cloned fresh onto a new machine (or by a new developer), the `.nexus/` directory does not exist — it is gitignored. The guild's configuration and code are all tracked in git, but runtime state needs to be reconstructed.
+
+```
+nsg guild restore
+```
+
+This command reconstructs all ephemeral runtime state from the tracked guild configuration:
+
+1. **Workshops** — re-clones all workshop bare repos from their `remoteUrl` in `guild.json`. Skips any that are already present.
+2. **npm dependencies** — runs `npm install` to restore packages from `package.json`.
+3. **On-disk tools** — reinstalls tools that have full source tracked in the guildhall.
+4. **Reports linked tools** — lists any tools that were npm-linked and need manual re-linking (since symlinks don't survive a clone).
+
+The command is idempotent — safe to run at any time. If everything is already in place, it reports "Nothing to restore."
+
+### When to Run Restore
+
+- After cloning the guildhall repo for the first time
+- After pulling changes that added new workshops
+- If a bare clone is corrupted or accidentally deleted
+- When `nsg workshop list` shows ✗ (missing bare clone) for any workshop
+
+### What Restore Does NOT Do
+
+- It does not create the Ledger (that's done by `nsg init` and the ledger-migrate engine)
+- It does not re-create animas or commissions — those live in the Ledger
+- It does not push or pull workshop repos — it only clones them fresh if missing
+
 ## CLI Reference
 
 The primary interface is the `nsg` command:
@@ -110,10 +371,19 @@ The primary interface is the `nsg` command:
 | Command | Purpose |
 |---------|---------|
 | `nsg init` | Create a new guild |
-| `nsg dispatch <content>` | Post and dispatch a commission |
+| `nsg commission <spec> --workshop <name>` | Post a commission |
 | `nsg tool install <source>` | Install a tool or bundle |
 | `nsg tool remove <name>` | Remove an installed tool |
+| `nsg workshop add <url>` | Clone a remote repo and register it as a workshop |
+| `nsg workshop remove <name>` | Remove a workshop |
+| `nsg workshop list` | List workshops with status |
+| `nsg workshop create <org/name>` | Create a new GitHub repo and register as a workshop |
+| `nsg guild restore` | Restore runtime state after a fresh clone |
 | `nsg anima create` | Instantiate a new anima |
 | `nsg anima manifest <name>` | Generate an anima's full instructions |
 | `nsg status` | Show guild status |
 | `nsg consult <name>` | Consult a standing anima (e.g., the advisor) |
+| `nsg signal <name>` | Signal a custom guild event |
+| `nsg clock list` | Show pending events |
+| `nsg clock tick [id]` | Process next pending event (or specific id) |
+| `nsg clock run` | Process all pending events |

package/migrations/002-clockworks.sql

@@ -0,0 +1,24 @@
+-- Clockworks tables: event log and dispatch tracking.
+-- Part of Pillar 5 — the guild's event-driven nervous system.
+
+CREATE TABLE events (
+    id         INTEGER PRIMARY KEY,
+    name       TEXT NOT NULL,
+    payload    TEXT,
+    emitter    TEXT NOT NULL,
+    fired_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    processed  INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE event_dispatches (
+    id           INTEGER PRIMARY KEY,
+    event_id     INTEGER NOT NULL REFERENCES events(id),
+    handler_type TEXT NOT NULL,
+    handler_name TEXT NOT NULL,
+    target_role  TEXT,
+    notice_type  TEXT,
+    started_at   TEXT,
+    ended_at     TEXT,
+    status       TEXT,
+    error        TEXT
+);

package/migrations/003-commission-status-reason.sql

@@ -0,0 +1,5 @@
+-- Add status_reason to commissions for tracking why each state transition happened.
+-- Every status change should include a reason: "posted by patron", "merged to main",
+-- "merge conflict in src/foo.ts", etc.
+
+ALTER TABLE commissions ADD COLUMN status_reason TEXT;

package/nexus-bundle.json

@@ -3,7 +3,7 @@
   "tools": [
     { "package": "@shardworks/tool-install@0.x", "name": "install-tool" },
     { "package": "@shardworks/tool-remove@0.x", "name": "remove-tool" },
-    { "package": "@shardworks/tool-dispatch@0.x", "name": "dispatch" },
+    { "package": "@shardworks/tool-commission@0.x", "name": "commission" },
     { "package": "@shardworks/tool-instantiate@0.x", "name": "instantiate" },
     { "package": "@shardworks/tool-nexus-version@0.x", "name": "nexus-version" }
   ],
@@ -11,15 +11,20 @@
     { "package": "@shardworks/engine-manifest@0.x", "name": "manifest" },
     { "package": "@shardworks/engine-mcp-server@0.x", "name": "mcp-server" },
     { "package": "@shardworks/engine-worktree-setup@0.x", "name": "worktree-setup" },
+    { "package": "@shardworks/engine-workshop-prepare@0.x", "name": "workshop-prepare" },
+    { "package": "@shardworks/engine-workshop-merge@0.x", "name": "workshop-merge" },
     { "package": "@shardworks/engine-ledger-migrate@0.x", "name": "ledger-migrate" }
   ],
   "temperaments": [
-    { "path": "temperaments/guide" }
+    { "path": "temperaments/guide" },
+    { "path": "temperaments/artisan" }
   ],
   "curricula": [
     { "path": "curricula/guild-operations" }
   ],
   "migrations": [
-    { "path": "migrations/001-initial-schema.sql" }
+    { "path": "migrations/001-initial-schema.sql" },
+    { "path": "migrations/002-clockworks.sql" },
+    { "path": "migrations/003-commission-status-reason.sql" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/guild-starter-kit",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Default bundle for new Nexus guilds — tools, training, and migrations",
   "repository": {
     "type": "git",

package/temperaments/artisan/content.md

@@ -0,0 +1,23 @@
+# Artisan Temperament
+
+You are an artisan — methodical, resourceful, and focused on delivering solid work. You take pride in craft, not in flash.
+
+## Disposition
+
+- **Pragmatic.** Favor working solutions over elegant abstractions. Get something real running, then refine. Don't gold-plate.
+- **Self-directed.** Once you have a clear brief, work independently. Make decisions within scope without asking permission for every detail. Use your judgment — that's why you were commissioned.
+- **Thorough.** Test your work. Check edge cases. Read the error messages. Don't declare something done until you've verified it works, not just that it compiles.
+- **Honest about problems.** If something isn't working, say so early. If the brief is unclear or contradictory, surface it rather than guessing. A well-timed question saves more time than a wrong assumption.
+
+## Communication Style
+
+- Be concise. Commit messages and code comments are your primary output — make them clear and useful for the next anima who reads them.
+- When reporting status, lead with what's done and what's blocked. Skip the preamble.
+- If you encounter a design decision outside your brief, flag it and move on. Don't block on decisions that aren't yours to make.
+
+## Work Ethic
+
+- Commit early and often. Small, atomic commits that tell a clear story.
+- Leave the workshop cleaner than you found it. No dead code, no dangling TODOs, no mystery files.
+- Respect the scope of your commission. Do the work you were asked to do. If you see adjacent improvements, note them — don't chase them.
+- When sage advice is provided, follow it. The sage planned the work; you execute the plan. If you believe the plan has a flaw, record your concern, but do not contradict it unilaterally.

package/temperaments/artisan/nexus-temperament.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.1.0",
+  "content": "content.md"
+}