@north-light/crouter 0.3.170 → 0.3.172

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

@@ -64,12 +64,12 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | Field | Required | Notes |
 |---|---|---|
 | `name` | yes | Must match the directory name. Lowercase kebab. |
-| `version` | yes | Semver. Marketplace CI may bump automatically — see marketplaces knowledge. |
+| `version` | yes for authored plugins | Semver. Marketplace CI may bump automatically; archive installs synthesize a 12-character content identifier. |
 | `description` | yes | One sentence. |
-| `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin update --name <name>`. |
+| `source` | recommended | Human-facing URL where the plugin lives. Source-installed plugin updates derive provenance from their checkout or marketplace registration, not this descriptive field. |
 | `owner` | optional | Author info. |
 | `commands` | optional | Plugin-root-relative path to a `commands.json` command manifest. It must appear with `transport`; together they make the plugin contribute `crtr` commands — see [Plugin commands](#plugin-commands). |
-| `transport` | optional | Required exactly when `commands` is present. `{ "kind": "exec", "executable": "bin/cmd.js" }` runs executable leaves; a passthrough-only exec manifest may omit `executable`. `{ "kind": "http", "endpoint": "https://…", "authEnv": "TOKEN_NAME" }` calls a remote HTTP command surface. |
+| `transport` | optional | Required exactly when `commands` is present. `{ "kind": "exec", "executable": "bin/cmd.js" }` runs executable leaves; a passthrough-only exec manifest may omit `executable`. `{ "kind": "http", "endpoint": "https://…", "authEnv": "TOKEN_NAME" }` calls a remote HTTP command surface. Archive-installed plugins also carry crouter-synthesized `bundle` provenance; authors do not add it. |
 
 ## Scopes
 
@@ -96,9 +96,10 @@ Four ways a plugin lands in a scope:
    - `crtr pkg market update --name <mkt>` refreshes the marketplace and every installed plugin it sources; relative sources follow the checkout, while remote-source checkouts pull their own Git remote.
    - See [[internal/marketplaces]].
 
-3. **From an HTTP endpoint** (`crtr pkg plugin install --endpoint <url> --name <name> --scope user`):
-   - Fetches the served `commands.json`, then writes the plugin manifest and exact fetched bytes into the selected scope. The endpoint must use `https:`; `http:` is accepted only for `localhost`, `127.0.0.1`, `[::1]`, `::1`, or `host.docker.internal`, with no credentials or fragment.
-   - The install fails loudly and writes nothing when that fetch fails. Reinstalling the same HTTP plugin replaces its endpoint/auth-env declaration and stored manifest; it conflicts with an existing non-HTTP plugin of the same name.
+3. **From an HTTP directory archive** (`crtr pkg plugin install --endpoint <url> --name <name> --scope user`):
+   - Fetches one authenticated uncompressed `application/x-tar` archive containing `bundle.json`, `commands.json`, and `memory/**/*.md`. crouter validates every member before writing, then materializes the complete package with a synthesized `.crouter-plugin/plugin.json`. The endpoint must use `https:`; `http:` is accepted only for `localhost`, `127.0.0.1`, `[::1]`, `::1`, or `host.docker.internal`, with no credentials or fragment.
+   - The synthesized `bundle` field records the archive endpoint and optional credential variable name for installs and updates. Its distinct `transport` field records the archive endpoint's origin for command invocation. crouter stores the environment variable name, never its token.
+   - Reinstalling a bundle plugin replaces commands and memory together. Fetch or validation failure leaves the prior package intact. A commands-only HTTP plugin predating this archive contract must be removed and reinstalled.
 
 4. **Authored in place** (you're writing the plugin in a working repo):
    - Symlink for tight dev loop: `ln -s $(pwd) ~/.crouter/plugins/<name>`.
@@ -136,7 +137,7 @@ Standard semver:
 | New doc, new section, new example | minor (0.1.0 → 0.2.0) |
 | Removed doc, renamed doc, changed manifest schema | major (0.1.0 → 1.0.0) |
 
-`crtr pkg plugin update --name <name>` pulls source updates for ordinary and exec-transport plugins, while an HTTP-transport plugin unconditionally refetches and replaces its stored `commands.json`. A failed HTTP refresh preserves the prior bytes and exits nonzero. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[internal/marketplaces]].
+`crtr pkg plugin update --name <name>` pulls source updates for ordinary plugins, including source-installed plugins whose command transport is HTTP. An archive plugin instead re-fetches its recorded `bundle` endpoint and replaces its complete package atomically; its version is the first 12 hex characters of the fetched archive SHA-256. A failed named update preserves the prior package and exits nonzero; bulk update reports the failure and continues. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[internal/marketplaces]].
 
 ## Enable/disable
 
@@ -180,12 +181,12 @@ Beyond docs, a plugin may contribute **top-level `crtr` commands** — new noun
 An HTTP-transport plugin replaces that declaration with:
 
 ```json
-"transport": { "kind": "http", "endpoint": "https://example.com/v1/cli/manifest", "authEnv": "DEPLOY_TOKEN" }
+"transport": { "kind": "http", "endpoint": "https://example.com", "authEnv": "DEPLOY_TOKEN" }
 ```
 
-For `exec`, `executable` is required when the manifest has any executable leaf; a passthrough-only manifest omits it. When declared, it is plugin-root-relative, resolves inside the plugin root to a regular file, and carries the POSIX exec bit. For `http`, `endpoint` is an absolute endpoint and `authEnv` is optional. crtr stores only the environment variable **name**, never its credential; it reads the credential when fetching the manifest or invoking a leaf.
+For `exec`, `executable` is required when the manifest has any executable leaf; a passthrough-only manifest omits it. When declared, it is plugin-root-relative, resolves inside the plugin root to a regular file, and carries the POSIX exec bit. For `http`, `transport.endpoint` is the backend origin and `authEnv` is optional. crouter stores only the environment variable **name**, never its credential; it reads the credential when invoking a leaf. A crouter-materialized archive plugin additionally records its archive URL separately in `bundle` for installation and update.
 
-Only an installed, **enabled** plugin's command manifest contributes. Discovery is per-invocation: enable, disable, update, and remove take effect on the next `crtr` call — no daemon restart or cache clearing.
+Only an installed, **enabled** plugin's command manifest contributes. Discovery is per-invocation and reads the installed `commands.json` only: enable, disable, update, and remove take effect on the next `crtr` call with no daemon restart, cache clearing, or network fetch.
 
 ### commands.json shape
 
@@ -239,7 +240,7 @@ For an exec leaf, crtr writes exactly one JSON request to the executable's stdin
 
 - **Generate an exec plugin's `commands.json` from its command definitions — never hand-write it.** The manifest must stay in lockstep with the executable's command surface; drifted params or output fields surface as a validation issue or `plugin_protocol_error` at invocation.
 - **A required output field must be non-null.** The adapter treats an explicit `null` for a declared-required field as absent → `plugin_protocol_error`. If a value is optional, declare it `required: false`; if it is required, return a real value.
-- **HTTP plugin manifests are fetched bytes.** `crtr pkg plugin install --endpoint <url> --name <name>` fetches before writing the plugin, then stores the exact response at the plugin's declared `commands` path. `crtr pkg plugin update` unconditionally refetches HTTP plugins; failures preserve the prior bytes and exit nonzero. The stored manifest is authoritative with no TTL, ETag, or revalidation. If its file is missing or unparseable, an unknown-first-token miss fetches each affected HTTP plugin once; diagnostics name `crtr pkg plugin update <name>`.
+- **HTTP archive plugins are complete package bytes.** `crtr pkg plugin install --endpoint <url> --name <name>` fetches and validates the complete archive before replacing the plugin directory. `crtr pkg plugin update` uses the recorded `bundle` provenance to do the same replacement. The installed `commands.json` and memory tree are authoritative with no TTL, ETag, revalidation, or dispatch-time network path.
 
 ### Validation and command collisions
 

package/dist/builtin-memory/internal/storage-tiers.md

@@ -22,9 +22,9 @@ User-wide content with no cwd dimension also belongs here: `~/.crouter/profile-d
 
 ## 2. Canvas home — node-graph runtime state, node artifacts, and bounded diagnostics
 
-`~/.crouter/canvas/` (overridable with `CRTR_HOME`) is the cwd-agnostic node-graph home. `canvas.db` is the SQLite WAL topology store for nodes and edges, including durable tmux-pane focus. `nodes/<node_id>/` owns `meta.json`, `context/`, `mode/`, `reports/`, `messages/`, `inbox.jsonl`, `transcript.jsonl`, `session.ptr`, and `job/` state. Humanloop ticket files (`deck.json`, `run.json`, `response.json`, `review.json`, and `branch-point.jsonl`) live directly in a terminal human bridge node directory; the one registered inbox root is `nodes/`.
+`~/.crouter/canvas/` (overridable with `CRTR_HOME`) is the cwd-agnostic node-graph home. `canvas.db` is the SQLite WAL topology store for nodes and edges, including durable tmux-pane focus. `nodes/<node_id>/` owns `meta.json`, `context/`, `reports/`, `messages/`, `inbox.jsonl`, `transcript.jsonl`, `session.ptr`, and `job/` state. Human ticket files (`deck.json`, `run.json`, `response.json`, `review.json`, and `branch-point.jsonl`) live directly in a terminal human bridge node directory; `nodes/` is the single ticket root, derived rather than registered.
 
-Mode-switch specifications and plans are ordinary node-context artifacts. They share the node's lifetime and are removed when that node is reaped.
+Specifications and plans are ordinary node-context artifacts. They share the node's lifetime and are removed when that node is reaped.
 
 ### Canonical event streams
 

package/dist/builtin-memory/{planning.md → plan/roadmap.md}

@@ -13,11 +13,11 @@ rationale: >-
 
 ## Plan Shapes and the Decomposition Decision
 
-Every planning effort produces either a flat plan or a decomposed plan (index + part-plans). Choosing the wrong shape wastes a cycle — a flat plan that is too large forces an implementer to hold too much at once; a decomposed plan for something small adds overhead for no gain.
+Every planning effort produces either a flat plan or a decomposed plan (index + part-plans). Choose decomposition for worthwhile parallel planning, not raw size: a flat plan can span many yields, while part-plans add delegation and synthesis cost that independent slices must repay.
 
 **Use a flat plan** when the work is a single coherent domain and can be written at consistent task granularity in one plan. A flat plan has an overview, ordered phases, and a verification section. No sub-plans. One file.
 
-**Use a decomposed plan** when the change spans multiple domains (e.g., data layer, API surface, UI) or would require a master plan that cannot be written at consistent granularity without ballooning. In this case: produce an index plan (the navigable master) and delegate each domain slice to a `plan`-kind child node, giving each child its slice scope, the relevant portion of the spec, and its place in the dependency graph. A slice that itself decomposes further — multiple sub-domains, more than one window's worth of planning — goes to a `plan` sub-orchestrator created directly (`crtr node new --kind plan --mode orchestrator`), not a base child relied on to promote itself. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and their dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
+**Use a decomposed plan** when settled boundaries expose independent planning slices that can proceed concurrently and the effort is large enough that parallel work materially improves intelligence, productivity, or elapsed time after synthesis cost. Produce an index plan (the navigable master) and delegate each slice to a `plan`-kind child node, giving it the relevant spec, explicit scope, and place in the dependency graph. A slice goes to a `plan` sub-orchestrator (`crtr node new --kind plan --mode orchestrator`) only when its own work passes the same parallelism threshold; a long sequential slice goes to a base child that can yield. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
 
 **The decomposition trigger is domain boundary, not size alone.** Three backend files and three frontend files are two domains even if the total count is modest — plan them separately and synthesize, because the integration seam is where bugs live and one agent reading both halves won't catch them as cleanly as two agents each going deep.
 
@@ -35,6 +35,6 @@ A good task is **bounded**: an implementation agent should be able to finish it
 
 ## Plan Review
 
-Give a consequential synthesized plan one independent review pass. Use one base `review` node when the plan, requirements, design, and relevant source pointers fit a window; use one bounded `review` orchestrator when they do not. The assignment applies whichever lenses matter — requirements coverage, pattern consistency, code smells, security, and architecture fit — within one verdict. Lenses are questions, not separate reviewer assignments.
+Give a consequential synthesized plan one independent review pass. Use one base `review` node for a coherent review across yields; use one bounded `review` orchestrator only when the artifact splits into independent review surfaces large enough for parallel coverage to repay synthesis cost. The assignment applies whichever lenses matter — requirements coverage, pattern consistency, code smells, security, and architecture fit — within one verdict. Lenses are questions, not separate reviewer assignments.
 
 Fold that report into the plan once. Resolve every Critical, Major, or implementation-blocking finding in the plan; dismiss a false positive or out-of-scope finding with a reason. The revised plan is ready when you can trace each finding to its disposition and the plan still clears its exit criteria. Implementation and acceptance evidence validate the revision; reviewer silence is not the bar.

package/dist/builtin-memory/plan.md

@@ -0,0 +1,19 @@
+---
+kind: knowledge
+when-and-why-to-read: When an agent invokes /plan to pause work and map an implementation, this knowledge should be read because implementation can proceed from a grounded path instead of making consequential decisions while editing.
+short-form: "Pause to write one right-sized implementation plan in the node context, then stop."
+system-prompt-visibility: none
+file-read-visibility: none
+slash: true
+rationale: The prior /plan plugin prompt forced ordinary planning through a fixed question loop, reviewer node, and human approval, adding ceremony rather than letting the plan match the work.
+---
+
+# /plan — write an implementation plan
+
+Pause the current work and write one right-sized implementation plan for: $ARGUMENTS
+
+Ground it in the relevant code and requirements. Make the approach, affected areas, ordering or dependencies, and verification clear enough that an implementer can carry it out without guessing. Resolve only the decisions the plan needs; point to existing patterns rather than repeating source code.
+
+Write the artifact in `$CRTR_CONTEXT_DIR`. For work that genuinely needs a broader planning roadmap, read [[plan/roadmap]] instead.
+
+Report the artifact's absolute path, then stop. Do not implement as part of this invocation.

package/dist/builtin-memory/spec/guide.md

@@ -0,0 +1,38 @@
+---
+kind: knowledge
+when-and-why-to-read: When eliciting or writing a specification, this knowledge should be read because downstream design and planning need settled intent without making the user answer avoidable questions or forcing every request through the same ceremony.
+short-form: Elicit only consequential uncertainty, then write a right-sized behavioral contract a downstream reader can use without guessing.
+system-prompt-visibility: none
+file-read-visibility: none
+rationale: Specification quality and elicitation guidance lived inside an always-loaded spec persona while the lightweight /spec command had almost none, leaving agents to choose between a vague one-shot and a fixed discovery workflow.
+---
+
+# Writing a specification
+
+A specification settles **what outcome and behavior are required**. It is not an architecture document or an implementation plan. Its depth follows the stakes and unresolved intent: a small reversible change may need a few paragraphs; a consequential product surface may need collaborative discovery and separate design.
+
+## Elicit without interrogating
+
+Investigate before asking. Read the request, relevant code and documents, and already-settled decisions first. A fact available from the project is not a question for the user.
+
+Reflect a concrete interpretation of the request so the user can confirm or correct it. Resolve the uncertainty whose answer could most change behavior, scope, or acceptance. When a decision really belongs to the user, give them a focused question with a proposed default or concrete options; use one decision or one small coherent set rather than a questionnaire.
+
+Spend attention where judgment is load-bearing, not where detail is merely available. Keep settled points moving and fold each answer into the specification as current truth. Stop eliciting when another answer would not materially change the behavioral contract. Explicit approval is warranted when the user is co-authoring the document or the remaining decision is consequential; ordinary reversible work does not need a ritual approval loop.
+
+## The finished specification
+
+A downstream reader should be able to understand the required outcome and produce a design or plan without inventing intent. Include the dimensions that matter for this request rather than forcing a section template:
+
+- the user, caller, or system being served and the intended outcome;
+- observable behavior and experience;
+- scope and non-goals;
+- consequential constraints and settled decisions;
+- relevant interfaces, states, and transitions;
+- failure behavior, boundary conditions, and edge cases;
+- acceptance scenarios that make success observable.
+
+Implementation detail belongs only where it constrains the outcome. A finished specification has no unresolved question that would force downstream work to guess; intentionally deferred, non-blocking questions are named as such.
+
+Before handing it off, read it once as a stranger: remove placeholders and contradictions, resolve wording with two plausible interpretations, confirm the scope is coherent enough to plan, and ensure every acceptance signal can be observed. Split independent outcomes rather than hiding them in one oversized document. Fix the artifact in place rather than creating a review log.
+
+For a specification effort that genuinely needs separate discovery, design, and requirements work across nodes, read [[spec/roadmap]]. For the qualities of individual requirements and the complete requirements artifact, read [[spec/requirements]].

package/dist/builtin-memory/spec/requirements.md

@@ -0,0 +1,31 @@
+---
+kind: knowledge
+when-and-why-to-read: When writing or evaluating requirements, this knowledge should be read because implementation and validation need one complete behavioral contract rather than behavior scattered across design prose or silently filled in by the planner.
+short-form: Write complete, atomic, observable, testable requirements; use formal templates only when they make a conditional behavior clearer.
+system-prompt-visibility: none
+file-read-visibility: none
+rationale: The requirements persona made EARS mandatory and omitted behavior already stated by the design, which could produce a gap list instead of the complete behavioral contract downstream work needs.
+---
+
+# Writing requirements
+
+Requirements state the behavior and constraints the finished system must satisfy. The requirements artifact is the complete behavioral contract: a design may remain normative for structure, but required external behavior must not be recoverable only by inference from design prose. Requirements are not architecture choices, implementation tasks, or a list containing only what the design forgot to say.
+
+A good requirement is:
+
+- **necessary** — it protects the intended outcome or an explicit constraint;
+- **atomic** — one independently satisfiable behavior rather than several joined obligations;
+- **unambiguous** — its actors, conditions, and result have one reasonable interpretation;
+- **observable and verifiable** — a user, caller, operator, or test can determine pass or fail;
+- **bounded** — relevant triggers, states, limits, and failure conditions are explicit;
+- **traceable** — its reason or source in the specification or approved design is identifiable;
+- **feasible** — known technical or policy constraints do not make it impossible, and unresolved feasibility is explicit;
+- **implementation-neutral** — it specifies the result unless a particular mechanism is itself a constraint.
+
+Use direct declarative prose by default. EARS (`WHEN`, `WHILE`, `IF`, `WHERE` … `SHALL`) is useful when a trigger, state, or optional feature would otherwise be ambiguous; it is a clarity tool, not a required dialect. Acceptance scenarios can make representative cases concrete, but examples do not replace the general rule they illustrate. Use stable identifiers when another artifact needs to trace requirements individually.
+
+Cover the normal path and every relevant alternate state, failure, boundary, permission, and lifecycle transition. “Relevant” is a judgment about the specified outcome, not a checklist invitation to invent features.
+
+Never repair a missing product or design decision by guessing. Record the exact gap and return it to the owning specification or design artifact. A draft may expose such gaps; a finished requirements handoff has no unresolved gap that would change implementation behavior.
+
+Review the set in both directions before handoff: every required outcome has corresponding requirements, and every requirement serves a stated outcome or constraint. Split compound obligations, remove design and task detail, and rewrite anything a tester could not evaluate without asking what it means.

package/dist/builtin-memory/spec/roadmap.md

@@ -0,0 +1,35 @@
+---
+kind: knowledge
+when-and-why-to-read: When a specification effort contains independent discovery, design, or requirements surfaces large enough for worthwhile parallel work, this knowledge should be read because the handoffs must preserve one settled contract without turning sequential reasoning into coordination ceremony.
+short-form: Orchestrate a specification only for worthwhile parallel work, using canonical artifacts rather than conversation context for handoffs.
+system-prompt-visibility: preview
+file-read-visibility: none
+gate: {kind: spec}
+rationale: The prior roadmap required every large specification to follow exact stages, fresh-window yields, fixed delegation, and human gates; the resulting process treated ceremony as the quality bar instead of the clarity of the finished contract.
+---
+
+# Orchestrating a specification
+
+Use a roadmap when settled boundaries expose independent specification work that can proceed concurrently and the effort is large enough that parallel execution materially improves intelligence, productivity, or elapsed time after synthesis cost. Multiple sequential phases, consequential user collaboration, or work that needs several context windows stay with one base spec writer across yields. When one writer can settle the request coherently, read [[spec/guide]] and produce one right-sized specification.
+
+## Choose only the phases the work needs
+
+**Shape** establishes the canonical statement of intent: who or what is served, the intended outcome, scope and non-goals, and consequential decisions. The spec owner investigates and elicits according to [[spec/guide]]. Shape is ready for handoff when a designer or requirements writer can proceed without inventing product intent.
+
+**Design** is a separate phase only when structural choices constrain the behavioral contract or downstream plan. Delegate a bounded architecture to a base `design` node; use a design orchestrator only when its own independent surfaces make parallel design worthwhile. The design artifact records approved structure and interfaces; it does not replace the specification's outcome or behavioral contract.
+
+**Requirements** turns the canonical specification and any approved design into the complete behavioral contract. For a multi-phase effort, delegate this to a fresh `spec/requirements` node and have it read [[spec/requirements]]. The requirements writer receives the canonical artifacts, not the originating conversation, so it can detect what the documents fail to say without losing behavior that was already settled.
+
+The dependency is shape → optional design → requirements. A phase exists because its output is needed by the next one, not because every specification must pass through a fixed checklist.
+
+## Resolve gaps through the owning artifact
+
+An independent reader exposes omissions; it does not decide product intent on the spec owner's behalf. When design or requirements finds an implementation-changing gap, bring the owning specification or design artifact current, then rerun only the affected handoff. The final requirements artifact contains the complete resolved contract rather than a review log or a list of inherited assumptions.
+
+## Match human involvement to the decision
+
+Use focused questions for consequential uncertainty and explicit document approval when the user is co-authoring or the artifact settles a high-impact product or architectural decision. Otherwise, present the concrete interpretation or largest remaining risks and keep moving. Reviewer silence and repeated approval loops are not completion criteria; settled intent and a usable contract are.
+
+## Keep the handoff explicit
+
+The roadmap names the current phase, the absolute paths of canonical artifacts, and the one blocking gate or question, if any. Detail and resolved decisions live in those artifacts rather than the roadmap. The final handoff identifies which specification, requirements, and design files are normative so planning never has to reconstruct the contract from reports or conversation history.

package/dist/builtin-memory/spec.md

@@ -1,95 +1,19 @@
 ---
 kind: knowledge
-when-and-why-to-read: When running a specification effort, shaping a spec
-  roadmap, or deciding how to stage design and requirements work, this knowledge
-  should be read so gaps in design intent surface before planning and downstream
-  behavior is testable without inherited blind spots.
-short-form: Use when running a specification effort, shaping a spec roadmap, or
-  deciding how to stage design and requirements work. Covers the three-stage
-  shape→design→requirements methodology, when to delegate design to a child
-  node, the isolation principle behind the design/requirements split, and what a
-  finished spec contains.
-system-prompt-visibility: preview
+when-and-why-to-read: When an agent invokes /spec to pause work and capture a request, this knowledge should be read because the work can resume from settled intent instead of rediscovering what it is meant to achieve.
+short-form: "Pause to write one right-sized specification in the node context, then stop."
+system-prompt-visibility: none
 file-read-visibility: none
-gate: {kind: spec}
+slash: true
+rationale: The prior /spec plugin prompt forced ordinary artifact requests through discovery loops, reviewer nodes, and human approval, turning a small pause to clarify work into prescribed ceremony.
 ---
 
-## The Three Stages
+# /spec — write a specification
 
-A specification effort runs in exactly this order: **SHAPE** → **DESIGN** → **REQUIREMENTS**. Do not collapse them, skip ahead, or run them in parallel. Each stage has a gate; the next stage starts only when that gate is met.
+Pause the current work and write one right-sized specification for: $ARGUMENTS
 
-### Stage 1 — Shape
+Ground it in the relevant request and context. Make the intended outcome, behavior, and scope boundary clear enough that a downstream reader does not have to guess. Leave implementation choices to design and planning unless they constrain the outcome.
 
-Shape is the discovery stage — the one place this effort is genuinely interactive. You work the human like a **consultant with a client**: draw out intent, scope, and non-goals before any design work begins. The deliverable is not an artifact — it is a shared mental model sufficient to write a sharp design brief.
+Write the artifact in `$CRTR_CONTEXT_DIR`. Read [[spec/guide]] when the request needs elicitation or a fuller quality check; for work that genuinely needs separate discovery, design, and requirements work across nodes, read [[spec/roadmap]].
 
-Run a discovery loop with `crtr human ask`: name the most important open question, form a provisional take, offer concrete options, get a decision, repeat. Two rules keep it sharp. **Never ask a question you could answer yourself** — first try to settle it by reading the codebase or your references; only genuinely unresolved, judgment-bearing questions reach the human, because a dumb question a little reading would have answered erodes their trust. And **aim discovery where it matters for this task** — the uncertainty that would most damage the spec is itself a per-task judgment you infer (error semantics for one task, screen layout for another, an integration contract for a third). The **behavior of the finished system is the prize** — boundary behavior, error cases, UX — pin it down as precisely as the task allows. The user is technical, so pull them into high-level architectural calls (data and table shapes, major structural choices) but don't make them sign off low-level detail they'd rather you decide.
-
-Track these turns carefully. The shape stage is done when: (1) the named components or functional areas are identified, (2) the user's intent can be restated without correction, and (3) no unresolved contradictions remain between the user's goal and the existing codebase. If after several rounds an ambiguity remains genuinely unresolvable, surface it explicitly in the design brief as an open question — do not silently assume an answer.
-
-Gate: human confirms readiness to proceed to design.
-
-### Stage 2 — Design
-
-Design produces the blueprint: components and their topology, end-to-end flows, files and directories affected, locked decisions, and open questions resolved. The altitude is infra/services — no function signatures, no algorithm descriptions, no implementation ordering. Design answers "what shape does this take?" — planning answers "how is it built?"
-
-Small or simple design work (one surface, clear scope, few components) can be done by a single `design`-kind child node. Large or complex design work — multi-surface features, multiple interacting subsystems, significant architectural choices — must be delegated to a **design orchestrator** (a `design`-kind node created directly with `--mode orchestrator`), which decomposes the design internally and returns a finished artifact. The trigger for spawning a design orchestrator rather than a base design node: if the design effort has distinct phases or interacting components that need separate design treatment, use an orchestrator.
-
-Gate: human approves the rendered design artifact.
-
-### Stage 3 — Requirements
-
-Requirements are derived from the finished, approved design. They describe observable system behavior — what a user, caller, or tester sees the system do at its boundary — under what triggers, conditions, and failure modes. Each requirement is written in EARS format (WHEN/WHILE/IF/WHERE + SHALL). Requirements are not the design restated; if a behavior is clear from the design, it belongs as a safe assumption, not a load-bearing requirement.
-
-Delegate requirements writing to a terminal `spec/requirements` agent — the isolated requirements-writer sub-persona, distinct from the discovery-first base `spec` worker. Pass it the rendered design text only. Do not include the design conversation, user goals, or your own reasoning — the requirements writer must derive requirements from what is actually documented, not from what was intended.
-
-Gate: human reviews and approves all load-bearing requirements; no `rejected` or unresolved `draft` items remain.
-
----
-
-## The Design/Requirements Split — Why Isolation Matters
-
-Requirements written by the same context that argued out the design carry that context's blind spots. If the design left a behavior ambiguous and the design author filled it in mentally, requirements derived from that same mental state will encode the assumption without surfacing it for review. Written by a fresh context against the rendered design document alone, ambiguous points surface as gaps in `agentNotes` rather than silently-inherited assumptions.
-
-The isolation is structural, not stylistic. The requirements writer receives: the rendered design text and an output path. Nothing else. No user goal, no exploration findings, no conversation history. If something the user "intended" is not written in the design, it does not appear in the requirements — and that absence becomes visible, which is the desired outcome.
-
----
-
-## The Yield-Between-Runs Rule
-
-After the design is approved, the spec orchestrator runs `crtr node yield` before starting requirements work. This is mandatory, not optional.
-
-Why: the design conversation fills context with reasoning about tradeoffs, rejected alternatives, and design intent. That context biases delegation — it causes the orchestrator to frame the requirements task with assumptions from the design discussion. After yielding, the orchestrator revives fresh against `$CRTR_CONTEXT_DIR/roadmap.md`, which records the finished design artifact path. It reads the design artifact cold and delegates the requirements work from that clean window, anchored on the rendered design rather than on the design conversation.
-
-The roadmap must record the design artifact path and the current stage before yielding. On revive, the first action is to read `$CRTR_CONTEXT_DIR/roadmap.md`, confirm the design is landed, and delegate requirements work.
-
----
-
-## Roadmap Shape for a Spec Effort
-
-When shaping the roadmap at the start, structure it as follows. The goal section states what is being specified and for whom. Scope assumptions record what is in scope and what is not — a non-goal stated here propagates to every child without restating it. `## Strategy / phases` holds exactly three phases: Shape (gate: human sign-off), Design (gate: design artifact approved), Requirements (gate: all requirements approved). The current phase carries a one-line status of where it stands; completed phases are deleted, not summarized.
-
-After yield-and-revive, `## Strategy / phases` plus `## Active context` must let the fresh orchestrator orient in one pass without reading any child reports: the current phase's status line names what's in flight and which gate it's waiting on, and `## Active context` lists the design artifact and any other live context-file paths. Human-confirmed decisions and design detail fold into those context files, not the roadmap.
-
----
-
-## Delegating Design: Base Node vs. Orchestrator
-
-Spawn a base `design` node when the design surface is bounded: one component or subsystem with no multi-phase structure required. The child writes `design-<subject>.md` in its own context directory and reports that absolute path.
-
-Spawn a terminal `design` orchestrator when the feature spans multiple subsystems, has distinct implementation phases that need separate design treatment, or the design effort is itself likely to fill one context window before it is finished. Create it directly as an orchestrator — `crtr node new --kind design --mode orchestrator` — so it owns decomposition and integration from the start. Pass it the shape brief as its goal; it writes the integrated `design-<subject>.md` in its own context directory and reports that absolute path when done.
-
-In either case, the spec orchestrator waits for the design to land and the human to approve it before proceeding.
-
----
-
-## What a Finished Spec Contains
-
-A finished spec is precise enough that a planner can produce an implementation task breakdown without guessing intent. It contains:
-
-- **Behavior** — what the system does at its external boundary, organized by functional area, written in EARS format.
-- **Non-goals** — what is explicitly out of scope, so planners and implementers don't expand into it.
-- **Interfaces / inputs / outputs** — the data shapes and interaction contracts (at semantic-type level, not TypeScript declarations).
-- **Edge cases** — the failure modes, boundary conditions, and unusual states that must be handled, surfaced explicitly rather than left to the implementer to discover.
-- **Acceptance criteria** — per-requirement, testable conditions: "given input X, observe output Y" or "given state X, observe behavior Y."
-
-A spec that requires the reader to infer intent, assume behavior, or resolve design questions is not finished. If those gaps remain at the end of Stage 3, surface them explicitly as open questions before pushing final.
+Report the artifact's absolute path, then stop. Do not implement as part of this invocation.

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

@@ -4,8 +4,8 @@ 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.
+path into the `packages` array of `~/.pi/agent/settings.json` — there is nothing
+to clone or install separately.
 
 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
@@ -32,6 +32,7 @@ directory's `node_modules/`.
 | Extension | What it does |
 |-----------|--------------|
 | `claude-plugin-commands.ts` | Surfaces commands and skills from `~/.claude`, the cwd, every project in the selected crouter profile, and installed plugins as pi slash commands with arg/shell-block execution. Writes shims to `~/.pi/agent/.plugin-command-shims/`. Skips any name pi already serves natively from `~/.pi/agent/prompts/` (e.g. crtr exports a slash command to both `~/.claude/commands` and `~/.pi/agent/prompts`), so the shim never collides with the native prompt. |
+| `memory-slash-commands.ts` | Registers every builtin or scope-owned memory marked `slash: true`, including `/spec` and `/plan`. |
 | `provider-rotation.ts` | Subscription credential rotation across Anthropic / OpenAI-Codex: does its own OAuth login/refresh, rotates on rate-limits, falls back across the model ladder. Registers `/provider-sub <provider> <list\|add\|select\|rm>`. |
 | `crtr-commands/` | Auto-generates a slash command per `crtr` CLI node. The tree is derived in-process from crtr's own `buildRoot()` (no subprocesses, no cache on disk); `filters.json` controls which nodes are exposed. |
 | `sysprompt-window.ts` | Registers `/sysprompt`, which runs `crtr sys sysprompt --window` without injecting the prompt into context. |
@@ -39,8 +40,6 @@ directory's `node_modules/`.
 | `statusline.ts` | Custom status line. |
 | `strip-skills-docs.ts` | Trims skill docs from context. |
 
-(`/plan` and `/spec` mode commands live in the separate `pi-mode-switch` package, not here.)
-
 ## Notes
 
 - Reload after editing any extension: `/reload` in pi.

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/__tests__/provider-rotation.test.ts

@@ -1162,9 +1162,8 @@ test("treats a request timeout as transient: retries the SAME provider in place,
   }
 });
 
-// Once the in-place transient retry budget is exhausted, the failure is surfaced to the
-// user AND the credential is rotated away: the struggling credential cools down briefly and
-// the turn continues on the fallback provider, rather than hard-failing.
+// Once the in-place transient retry budget is exhausted, the credential is rotated away
+// for this turn without persisting a fake rate-limit cooldown.
 test("surfaces the transient error and rotates to the fallback once the in-place retry budget is exhausted", async () => {
   await resetRotationState();
   writeLadderConfig();
@@ -1211,8 +1210,53 @@ test("surfaces the transient error and rotates to the fallback once the in-place
     // The turn was served on the fallback, never failed with a terminal error.
     assert.ok(emitted.some((e) => e.type === "text_delta"));
     assert.ok(!emitted.some((e) => e.type === "error"));
-    // The struggling anthropic credential was cooled down so rotation moved on.
-    assert.ok(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil > Date.now());
+    // A network failure is not a rate limit and must not poison future turns.
+    assert.equal(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil, 0);
+  } finally {
+    rotationModule.__setStreamForProviderForTest(undefined);
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+test("surfaces the underlying transient error without reporting a rate limit when every route fails", async () => {
+  await resetRotationState();
+  writeLadderConfig();
+  await helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
+
+  const { ctx, providers, events, pi } = makeRotationCtx(undefined);
+  const sleepCalls: number[] = [];
+  let streamCalls = 0;
+  rotationModule.__setSleepForTest(async (ms) => {
+    sleepCalls.push(ms);
+  });
+  rotationModule.__setStreamForProviderForTest(() => {
+    streamCalls += 1;
+    return (async function* () {
+      yield {
+        type: "error",
+        error: Object.assign(new Error("WebSocket connection closed unexpectedly"), {
+          errorMessage: "WebSocket connection closed unexpectedly",
+        }),
+      };
+    })() as any;
+  });
+
+  try {
+    await providerRotationExtension(pi);
+    await events.session_start?.({}, ctx);
+    const stream = providers["openai-codex"].streamSimple(
+      { provider: "openai-codex", id: "gpt-5.6-sol", api: "openai-codex-responses" },
+      ctx,
+    );
+    const emitted = [] as any[];
+    for await (const event of stream) emitted.push(event);
+
+    assert.equal(streamCalls, 3);
+    assert.deepEqual(sleepCalls, [250, 750]);
+    assert.equal(emitted.length, 1);
+    assert.match(emitted[0].error.errorMessage, /WebSocket connection closed unexpectedly/);
+    assert.doesNotMatch(emitted[0].error.errorMessage, /rate limited/i);
+    assert.equal(helpers.readSubscriptionPool("openai-codex")[0].rateLimitedUntil, 0);
   } finally {
     rotationModule.__setStreamForProviderForTest(undefined);
     rotationModule.__setSleepForTest(undefined);

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.d.ts

@@ -0,0 +1,56 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AssistantMessageEventStream, type Context, type Model, type SimpleStreamOptions } from "@earendil-works/pi-ai";
+import { type ManagedProviderId, type SubscriptionCredential } from "../../../core/subscription-state.js";
+export interface ProviderRotationOptions {
+    modelIntent?: string;
+    nodeCwd?: string;
+    profileId?: string;
+}
+declare function defaultSleep(ms: number): Promise<void>;
+/** Test-only seam: override the sleep implementation used for in-place/wait-out retries. Pass undefined to restore the default. */
+export declare function __setSleepForTest(fn: typeof defaultSleep | undefined): void;
+/** Test-only seam for the bounded, non-fatal subscription bookkeeping path. */
+export declare function __recordSubscriptionMutationForTest(description: string, mutate: () => Promise<unknown>): Promise<boolean>;
+type RefreshedCredential = {
+    refresh: string;
+    access: string;
+    expires: number;
+};
+type LoginCredential = {
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+};
+type ResolvedCredential = SubscriptionCredential & {
+    access: string;
+};
+type RefreshForProvider = (providerId: ManagedProviderId, refreshToken: string) => Promise<RefreshedCredential>;
+/** Test-only seam: override the per-provider refresh function. Pass undefined to restore the default. */
+export declare function __setRefreshForProviderForTest(fn: RefreshForProvider | undefined): void;
+/** Test-only seam: exercises the real `refreshCredentialIfNeeded` (including its locked refresh
+ * transaction) without duplicating its logic. */
+export declare function __refreshCredentialIfNeededForTest(providerId: ManagedProviderId, credential: SubscriptionCredential): Promise<ResolvedCredential>;
+declare function defaultLoginForProvider(providerId: ManagedProviderId, ctx: ExtensionContext): Promise<LoginCredential>;
+/** Test-only seam: override the per-provider login function. Pass undefined to restore the default. */
+export declare function __setLoginForProviderForTest(fn: typeof defaultLoginForProvider | undefined): void;
+declare function defaultStreamForProvider(model: Model<any>, context: Context, options: SimpleStreamOptions | undefined): AssistantMessageEventStream;
+/** Test-only seam: override the per-provider stream factory. Pass undefined to restore the default. */
+export declare function __setStreamForProviderForTest(fn: typeof defaultStreamForProvider | undefined): void;
+/**
+ * pi-ai races the manual-code-paste dialog against its loopback callback server. When the
+ * callback supplies a code, the manual-input promise can remain pending, so `run` receives:
+ *  - `readCode`, a `ctx.ui.input` wrapper with an AbortSignal. Aborting it removes the pending
+ *    broker entry and emits an `extension_ui_dismiss` frame for exactly that dialog.
+ *  - `dismissManual`, which aborts the signal at the post-code `onProgress` boundary before
+ *    the token exchange completes. `onProgress` is emitted only after a code is available, so
+ *    dismissing then cannot close a dialog the user still needs; `finally` covers paths without
+ *    progress, and repeated AbortController calls are inert.
+ *
+ * `undefined` from `readCode` means cancellation or timeout. It throws so OAuth ends directly
+ * instead of opening a second paste-only dialog.
+ */
+export declare function loginWithManualInputCleanup<T>(ctx: ExtensionContext, run: (readCode: (title: string, placeholder: string) => Promise<string>, dismissManual: () => void) => Promise<T>): Promise<T>;
+export declare function createProviderRotationExtension(options?: ProviderRotationOptions): (pi: ExtensionAPI) => Promise<void>;
+declare const defaultProviderRotationExtension: (pi: ExtensionAPI) => Promise<void>;
+export default defaultProviderRotationExtension;