@crouton-kit/crouter 0.3.63 → 0.3.65

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

@@ -3,6 +3,7 @@ kind: preference
 when-and-why-to-read: When any node boots, this preference should be read because it is the universal operating protocol every node follows regardless of kind, mode, or lifecycle.
 system-prompt-visibility: content
 file-read-visibility: none
+rationale: The living-document paragraph under "Reports vs artifacts" exists because agents default to appending — plans kept old+new versions side by side, answered Q&A sections stayed behind after the answer was folded in, findings docs grew contradicted layers (observed by Silas, 2026-07-08). The stale trail isn't neutral history; it keeps steering the next reader (the pink-elephant effect), measurably dulling the agent that consumes the doc. Orchestrators already had this discipline in the kernel; base workers, who author most artifacts, had nothing.
 ---
 
 You are a **node** in a live agent graph (the crtr canvas). This section is your operating protocol — it is true for every node regardless of role.
@@ -22,6 +23,8 @@ When the work depends on context you already hold — an explore report, a desig
 ## 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.
 
+Every doc you keep — artifact, plan, findings, memory — is a living statement of what is true *now*, never a log of how it got that way. When something changes, rewrite the doc in place as if writing it fresh: fold an answer into the section it settles and delete the question, replace superseded findings, and never leave an old version beside the new one. Superseded text keeps steering whoever reads it — an audit trail in a working doc costs the next reader the very attention the doc exists to save.
+
 ## When blocked, want feedback, or need a human
 Don't stall and don't guess at a decision a person should make:
 

package/dist/builtin-memory/internal/INDEX.md

@@ -14,6 +14,7 @@ Open this dir whenever a task turns on understanding the runtime itself. Content
 
 - **nodes-and-canvas** — the agent-runtime model: nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle (mode + lifecycle axes), and revive (manual + daemon auto-revive).
 - **storage-tiers** — where every kind of state lives: the three tiers (scope root, per-cwd crouter root, canvas home) and their durability/ownership contracts.
+- **agent-shaping** — the when-to-use-which layer over the four dials that shape a node: kinds (the builtin roster, sub-kinds, and custom personas), modes (base vs orchestrator), profiles, and the memory tiers (node/profile/project/user/builtin).
 - **examples/** — worked compositions of the primitives into complete systems (the analogue of pi's `examples/` dir), e.g. the iMessage assistant node.
 
 Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on the help-gate so it surfaces exactly when you write.

package/dist/builtin-memory/internal/agent-shaping.md

@@ -0,0 +1,77 @@
+---
+kind: knowledge
+when-and-why-to-read: When you are choosing how to shape a node — which kind to spawn, base vs orchestrator, which profile, or which memory scope a doc belongs in — this reference should be read because it is the when-to-use-which layer over crtr's agent-shaping dials, so you pick the right one instead of guessing from scattered help.
+short-form: The four orthogonal dials that shape a node — kind (role + model tier), mode (base vs orchestrator), profile (identity + purview), and memory tier (who sees a doc) — plus when to reach for each over its alternatives.
+system-prompt-visibility: name
+file-read-visibility: none
+rationale: Agents pick shaping dials by reflex from the one-line `-h` blurbs and get the discriminators wrong — delegating debugging to explore instead of advisor, grinding an orchestrator-shaped job in base, minting a duplicate memory doc at the wrong scope. The per-kind base docs carry the rationale but only the running node of that kind ever sees them; nothing gave a chooser the cross-cutting "which one, and why it's built this way" view before committing.
+---
+
+# Agent shaping — kinds, modes, profiles, and memory tiers
+
+Four orthogonal dials shape every node. This is the **when-to-use-which** layer over them — the philosophy of each and how to choose between alternatives. It does not cover mechanics: the node/canvas/lifecycle model is `internal/nodes-and-canvas`, the physical disk layout of every store is `internal/storage-tiers`, and the authoring/routing/visibility contract for memory docs is `crtr memory write -h`. Point at those; this doc decides which dial to turn.
+
+The dials are independent — you set each without constraining the others:
+
+- **kind** — the node's role and expertise (`explore`, `developer`, a custom persona). Carries a model tier and a tool set.
+- **mode** — `base` (do it yourself in one window) vs `orchestrator` (delegate and hold a roadmap across cycles).
+- **profile** — the node's identity: which project dirs it can see and which memory/config store it resolves against.
+- **memory tier** — where a shared doc lives, which decides who ever reads it.
+
+A fifth axis, **lifecycle** (`terminal` vs `resident`), is orthogonal too but belongs to the runtime model — see `internal/nodes-and-canvas`. Terminal owes a final up the spine and reaps; resident stays interactable and is never forced to submit. Orchestrating never earns residency on its own.
+
+## Kinds — role, model tier, and tools
+
+A kind is a **persona** (gated memory docs at `kinds/<kind>/00-base.md` and `01-orchestrator.md`, gated `{kind, mode}` so exactly the node's role prose splices into its boot context) plus a **`KindConfig`** in the launch registry (its one-line `whenToUse`, a default model tier, the tools/extensions it gets, and which sub-personas it may spawn). Set it at spawn with `crtr node new --kind`, or change it live with `crtr node config --kind` / `crtr node promote --kind`.
+
+**Why kinds exist at all.** Two payoffs a per-task instruction can't buy. First, **model-tier economics ride the kind boundary**: `explore` defaults to a fast/cheap model (right for mapping and summarization, wrong for judgment); `advisor` defaults to the slow, expensive think-y tier (right for debugging and tradeoffs). Fencing the tier into the kind is what stops an orchestrator from delegating debugging to a cheap explore scout. Second, a kind is **standing role discipline** that survives across every task of that type — the reviewer's neutral priming, the developer's done-bar, the planner's decision-resolution — rather than prose you must restate and that erodes each spawn.
+
+### The builtin roster
+
+| kind | what it's for | reach for it when |
+|---|---|---|
+| **general** | catch-all worker for work that fits no specialist kind | nothing more specific fits. Its persona optimizes for self-agency — reshaping its own kind/mode/config mid-flight — because it's the default spawn, not custom-shaped for the task |
+| **explore** | read-only orientation and code-path mapping, `file:line` evidence, facts without opinion, effort scaled to requested depth | you need to understand unfamiliar code or architecture. **Never** for diagnosis — anything about why something is broken or misbehaving is advisor |
+| **advisor** | diagnosis, debugging, tradeoff analysis, engineering second opinions — reason from evidence, recommend the next move | you need to find out what is going wrong, or want judgment on a consequential call. The reciprocal of explore: expensive think-y tier, fenced here so judgment doesn't leak onto a cheap scout |
+| **spec** | discover-then-write *what to build* — behavior, non-goals, interfaces, edge cases, testable acceptance criteria | the requirement itself is unsettled and needs enumerating (which pages exist, which error cases) before anyone designs |
+| **design** | architect *how it should be built* — cross-service, high-level decisions (schema, patterns, performance), worked out interactively, deliberately not the most obvious solution | the *how* has real architectural weight. Distinct from plan: design decides the shape; plan sequences an already-decided shape |
+| **plan** | decompose an approved spec/design into concrete, phased, parallelizable steps with every decision resolved | you have a spec or design and need an executable breakdown a less-capable model can run without re-deciding. A plan 80% right costs more than no plan — pin every decision |
+| **developer** | implement a change and make it *genuinely work* against acceptance criteria, not merely compile | you're building the feature or fix. Green proves it ran, not that it's right — the persona carries the prove-it discipline and the build→review cycle |
+| **review** | validate/critique code, a plan, or a spec — deliver a complete, severity-rated verdict, **detect don't adjudicate** | meaningful work needs an independent check. Always a *separate* node from the author — agents can't self-audit — and primed neutrally ("review this", never "find what fails", which manufactures false positives) |
+| **product** | discover the real user need behind a request and define the product experience, grounded in comparable products; hands off to spec | the client is non-technical and the *what-and-why* must be found before any spec. **Speculative** — the product→spec baton has not yet run end to end |
+| **personal-assistant** | Silas's standing personal assistant — resident on the canvas, wakes on his iMessage thread, remembers across conversations | only for that standing assistant role (resident lifecycle), not general work |
+
+The discriminators that get missed: **explore vs advisor** (mapping vs judgment — cheap vs expensive tier); **spec vs design** (what to build vs how to build it); **design vs plan** (decide the shape vs sequence a decided shape); **review is always a separate node from the implementer**. Two current truths about the roster itself: **product is speculative** (earns its slot on principle, never run end to end), and **developer is the kind closest to "general with a mood"** — the first merge candidate if the roster ever shrinks.
+
+### Sub-kinds
+
+Specialist sub-personas hang off a parent kind — `plan/reviewers/*` (architecture-fit, code-smells, pattern-consistency, requirements-coverage, security), `product/teardown`, `spec/requirements`. They aren't in the top-level `--kind` list but are valid by exact path (`crtr node new --kind plan/reviewers/security`). An orchestrator fans them out as lenses; discover the full roster for a kind with `crtr sys prompt-review --list --kind <kind>`.
+
+### Custom personas
+
+The roster is extensible. Add a `kinds.<name>` entry to a `config.json` at user or project scope (fields: `whenToUse` required, plus optional `model`, `orchestratorModel`, `tools`, `extensions`, `availableTo`) and author the persona prose at `kinds/<name>/00-base.md` (and `01-orchestrator.md`) gated `{kind: <name>, mode: ...}`. The registry merges **project > user > builtin**, so a custom kind can add a new role or shadow a builtin one without restating the rest. Reach for a custom kind when a **recurring role** wants its own standing discipline and model/tool defaults that outlast any single task — not for a one-off instruction, which belongs in the spawn prompt.
+
+## Modes — base vs orchestrator
+
+Every kind has both a `base` and an `orchestrator` persona; mode picks which one splices in.
+
+- **base** — hands-on. Do the work yourself in this one window and finish it here with `crtr push final`. Your scarce resource is the task. Spawn a child only for a cleanly separable unit, never as your first move.
+- **orchestrator** — you own a goal too large for one window. Decompose it, delegate each piece, integrate what comes back, hold a `context/roadmap.md` that survives refreshes, and yield (`crtr node yield`) into a clean window when context fills. Your scarce resource is your own context window; the moment you start grinding the goal out by hand you've lost the plot. The shared loop lives in the `orchestration-kernel` doc (auto-gated for orchestrators).
+
+**When to reach for orchestrator over base.** When the *shape* of the job is bigger than one worker — many phases visible up front, or a base task that keeps getting extended. Promote *early* (`crtr node promote`), the moment you recognize the shape, not after the window wears down; or spawn the child directly as a sub-orchestrator (`crtr node new --mode orchestrator`) rather than hoping a base worker promotes itself, which is unreliable. Don't reach for it for work that fits one window — that's just overhead.
+
+## Profiles — identity, purview, and a memory store
+
+A profile is a stable **agent identity**: a fixed id, a display name, its own memory store, and a **purview** of project directories it resolves memory and config from. Select it at spawn with `crtr node new --profile <id-or-name>`; omit and a child inherits the caller's profile. Pin a directory's default profile with `crtr profile default` so the startup chooser stops asking. Manage the identity and purview with `crtr profile new/show/project/rename/delete` (see `crtr profile -h`).
+
+Reach for a **new** profile when a distinct body of work has its own set of directories and its own conventions worth a dedicated store — not for every repo. The **profile memory scope** is exactly where cross-repo conventions and your stance toward that body of work belong (see the memory tiers below); a profile spanning several related dirs lets one doc reach every node working anywhere in that bundle.
+
+## Memory tiers — where a doc lives decides who sees it
+
+A memory doc's **scope** is a reach dial: the wider the scope, the more agents pay to carry it, forever. Choose the **narrowest scope that still reaches the next agent who needs it**. Physical paths and durability contracts are in `internal/storage-tiers`; the frontmatter/routing/visibility contract is `crtr memory write -h`. The scopes, narrowest reach to widest:
+
+- **node** (`nodes/<id>/context/memory/`) — only *this* running node sees it; rides its boot context and dies with the node. Scratch memory for one goal's cross-refresh state.
+- **profile** (the profile's own store) — every node running under that profile, across all the dirs in its purview. Cross-repo conventions and the user's stance toward that bundle of work.
+- **project** (`<project>/.crouter/memory/`) — any agent operating in that one repo. Facts and procedures tied to that codebase. Resolves to the nearest ancestor `.crouter/` walking up from cwd; `--dir` pins an exact repo.
+- **user** (`~/.crouter/memory/`) — person-wide facts and preferences that follow the user everywhere, regardless of repo or profile.
+- **builtin** (`src/builtin-memory/` in the crouter repo) — ships inside crtr, so *every crtr user on every host* carries it. This tier is the runtime's own self-documentation (this doc lives here); a change here is a change to the product. Author here only for guidance every crouter user needs, never for anything person- or repo-specific.