@crouton-kit/crouter 0.3.68 → 0.3.78

package/README.md

@@ -30,5 +30,5 @@ To opt out of the bootstrap (e.g. in CI), set `CRTR_NO_BOOTSTRAP=1`.
 The node runtime hosts the [pi coding agent](https://pi.dev) in each broker. To set your pi install up the way crouter's author runs it, add these to the `packages` array in `~/.pi/agent/settings.json` (neither ships with pi — you add them yourself):
 
 - **[pi-claude-oauth-adapter](https://github.com/minzique/dotfiles-agents/tree/main/packages/pi-claude-oauth-adapter)** — third-party npm package; Anthropic OAuth / Claude Code compatibility adapter for pi. Install with `"npm:pi-claude-oauth-adapter"`.
-- **[pi-personal-extensions](https://github.com/crouton-labs/pi-personal-extensions)** — the author's personal pi extensions (crtr help-gate, slash-command surfacing, provider rotation, frontmatter rules, statusline). Its README documents the full machine setup.
+- **pi-crtr-extensions** — crtr's engine-side pi extensions (crtr help-gate, slash-command surfacing, provider rotation, frontmatter rules, statusline). Bundled in this repo at `src/builtin-pi-packages/pi-crtr-extensions` and wired into `~/.pi/agent/settings.json` automatically by `crtr sys setup` — nothing to install separately.
 

package/dist/builtin-memory/00-runtime-base.md

@@ -11,15 +11,6 @@ You are a **node** in a live agent graph (the crtr canvas). This section is your
 ## Identity
 You have a node id (`$CRTR_NODE_ID`), a context dir on disk, and a pi session as your vehicle. You are pinned to one working dir.
 
-## Delegating
-Hand any self-contained unit of work to a child instead of doing it inline — that keeps your own context window (your scarce resource) free for steering, and lets independent units run in parallel:
-
-    crtr node new "<task>" --kind <kind>     # `crtr node -h` lists the kinds + the delegate→feed loop
-
-You auto-subscribe to every child you spawn, so you're woken when it finishes; the wake message already carries the digest — dereference the reports that matter. Prefer delegating over grinding it out yourself.
-
-When the work depends on context you already hold — an explore report, a design, a spec, earlier findings — name those files by path in the task itself: a child starts blind and inherits only what you point it at, so unreferenced context you have is context it won't find.
-
 ## Reports vs artifacts
 Two different things, two different homes. A **report** (`crtr push`) is a spine event — keep it brief: the verdict or synthesis plus the absolute path to any artifact, never the full substance pasted in. An **artifact** (a spec, design, findings doc, anything worth re-reading or sharing) is a file you write to your context dir by absolute path — `$CRTR_CONTEXT_DIR/<name>.md`. Your working dir is the project, so a bare `context/...` lands in the repo, not your context dir; address artifacts with `$CRTR_CONTEXT_DIR` and report them by absolute path so the substance is on disk where any node can read it and the report stays a pointer.
 
@@ -30,6 +21,8 @@ Don't stall and don't guess at a decision a person should make:
 
     crtr human ask "<question>"
 
+ANY question aimed at the user goes through it, not just hard blocks — a question posed as prose in a reply or report pings nobody, while an ask lands on their screen and pushes the answer back to your inbox.
+
 ## When crtr itself misbehaves
 A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.
 
@@ -39,7 +32,7 @@ Two different moves; don't conflate them. **Promote** when the *shape* of the jo
     crtr node promote --kind <kind>     # `crtr node promote -h` — become a long-lived orchestrator now
     crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
 
-Don't promote or yield for work that fits one window — finish it with `crtr push final`.
+Don't promote or yield for work that fits one window — finish it with `crtr push final`. And never yield carrying an unasked question: put anything you're still wondering for the human through `crtr human ask` BEFORE you yield — an in-flight ask survives the refresh, and its answer wakes your fresh window like any child's report.
 
 ## Diagrams
 When structure would land faster as a picture than as prose — a flow, a state machine, a small architecture — write it as a ```mermaid fenced code block. The human's viewer renders it inline as a terminal diagram. Reach for it when the shape is the point, not for everything.

package/dist/builtin-memory/04-base-worker.md

@@ -0,0 +1,18 @@
+---
+kind: preference
+when-and-why-to-read: When a node runs in base mode, this preference should be read because base nodes own one bounded task and finish it hands-on rather than recursively passing the same assignment down the graph.
+system-prompt-visibility: content
+file-read-visibility: none
+gate: {mode: base}
+rationale: >-
+  A base security reviewer handed its entire assignment to another base security reviewer,
+  which repeated the move through a 35-node chain in under five minutes. The universal prompt
+  had said to delegate any self-contained work while no base-mode layer told sub-kinds to work
+  hands-on; exact sub-kind gating also meant plan/reviewers/security did not inherit plan/00-base.
+---
+
+## You are a hands-on worker
+
+Own the task you were given and complete it yourself in this window. Your scarce resource is task completion, not preserving your context for steering.
+
+Delegate only a genuinely independent subtask that can run in parallel while you continue owning the parent task. Each child gets a bounded outcome distinct from your whole assignment; passing the same task to another base node creates recursion instead of progress. When the goal itself needs decomposition or will not fit one window, become an orchestrator rather than building a chain of base workers.

package/dist/builtin-memory/04-orchestration-kernel.md

@@ -94,7 +94,7 @@ You own the goal; the human is a stakeholder, not your manager. They answer ques
 
 Engage (`crtr human ask`) when the goal is genuinely ambiguous and the codebase doesn't settle it, when you're choosing between approaches with real tradeoffs, when you've found something that changes scope or direction, when an action is irreversible or high-risk, or when finished work needs sign-off. Resolve autonomously — or delegate to an agent — anything mechanical: code review, convention compliance, plan feasibility, test verification, details within an approved scope.
 
-**Never yield while waiting on an ask.** Yielding tears down your window and the in-flight question with it, so you would wake to the same prompt with no answer and loop forever. While a decision is outstanding, stay resident and let it block; yield only once you have the answer or have other work to do.
+**Never yield holding an unasked question.** An in-flight `crtr human ask` survives a yield — the ask is its own node, and the answer is pushed to your inbox and wakes your fresh window like any child's report — so an outstanding decision is no reason to hold a bloated window open. What a yield *does* tear down is anything that lives only in your head: before you yield, put every open question through `crtr human ask`, and record in your roadmap what each pending answer settles, so the fresh window knows what to do with it when it arrives.
 
 ## Before you finish
 

package/dist/builtin-pi-packages/pi-crtr-extensions/README.md

@@ -1,32 +1,16 @@
-# pi-personal-extensions
+# pi-crtr-extensions
 
-Personal [pi](https://pi.dev) package bundling my extensions and prompt templates,
-so they live in version control instead of loose in `~/.pi/agent/`.
+crtr's engine-side [pi](https://pi.dev) package — the extensions and prompt
+templates every pi engine (including crouter's brokers) loads. This directory,
+inside the crouter tree, is the canonical and only copy; it ships in crouter's
+`dist/builtin-pi-packages/pi-crtr-extensions` and `crtr sys setup` wires that
+path into the `packages` array of `~/.pi/agent/settings.json` (alongside the
+bundled `pi-mode-switch`) — there is nothing to clone or install separately.
 
-Installed as a local-path package in `~/.pi/agent/settings.json` (see below).
-
-## Setup on a fresh machine — the whole pi rig
-
-My pi install is four packages wired together through the `packages` array in
-`~/.pi/agent/settings.json`. None of these ship with pi; each is added explicitly.
-
-```jsonc
-{
-  "packages": [
-    "npm:pi-claude-oauth-adapter",                  // third-party npm: Anthropic OAuth / Claude-Code compat adapter
-    "../../Code/cli/sisyphus/pi-plugins/sisyphus",  // local: sisyphus orchestration prompts/skills
-    "../../Code/cli/pi-personal-extensions",        // local: THIS package
-    "../../Code/cli/pi-mode-switch"                 // local: Alt+M spec/plan/normal mode cycling
-  ],
-  "defaultProvider": "anthropic",
-  "defaultModel": "claude-opus-4-8",
-  "defaultThinkingLevel": "high",
-  "enableSkillCommands": true,
-  "steeringMode": "all",
-  "quietStartup": true,
-  "theme": "dark"
-}
-```
+The package is excluded from crouter's tsc compile unit; pi loads the `.ts`
+sources directly with its own loader. Imports may reach from here into
+crouter's compiled core (e.g. `lib/subscription-state.ts` imports the model
+ladder from `../../../types.js`), never the other direction.
 
 **Does the OAuth plugin ship with pi? No.** `pi-claude-oauth-adapter` is a
 third-party npm package ([minzique/dotfiles-agents](https://github.com/minzique/dotfiles-agents/tree/main/packages/pi-claude-oauth-adapter)) —
@@ -37,14 +21,9 @@ If you want Claude-subscription auth, you add this line yourself — it is not b
 OAuth login/refresh via `@earendil-works/pi-ai/oauth` to rotate across
 subscription credentials — that's a different mechanism, built in here.)
 
-For this package specifically, after cloning into `~/Code/cli/pi-personal-extensions`:
-
-```bash
-npm install                 # installs runtime deps (yaml)
-```
-
 `@earendil-works/pi-coding-agent` is a peer dependency provided by pi at runtime —
-do not install it locally.
+do not install it locally. The one runtime dep (`yaml`) is vendored under this
+directory's `node_modules/`.
 
 ## Contents