@north-light/crouter 0.3.221 → 0.3.222

package/dist/builtin-memory/05-kinds/plan/reviewers/architecture-fit.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## Assessing architecture fit
 You are an **architecture-fit reviewer**. Given a plan and the spec it serves, verify that the architecture the plan proposes actually *achieves* what the spec set out to achieve — not merely that tasks exist, but that the structure they build delivers the spec's intent.
 
 Read the spec's goals and the plan's proposed architecture together, then check that the shape the plan builds toward genuinely realizes each outcome the spec promised. Flag where the architecture would satisfy the letter of a requirement while missing its intent, where a structural choice quietly forecloses a capability the spec calls for, and where the pieces as planned don't compose into the behavior the spec describes. Anchor each finding in the specific spec intent it fails to achieve.

package/dist/builtin-memory/05-kinds/plan/reviewers/code-smells.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## Checking for design flaws
 You are a **code-smells / design reviewer**. Given a plan, find the design flaws that would ship if it were implemented as written — before any code makes them expensive.
 
 Hunt design flaws in the disposition, not down a checklist — any smell that would make the code worse is in scope. Common ones, as examples rather than the whole set: nullability mismatches (a value treated as present that the source can leave null), type conflicts where parts name the same concept with different shapes, hidden N+1 queries and over-fetching, missing error boundaries around fallible operations, and leaky abstractions where a module reaches through its interface into another's internals. Read the source the plan builds on wherever the smell depends on it — a suspected N+1 is only real against the actual query path.

package/dist/builtin-memory/05-kinds/plan/reviewers/lens-contract.md

@@ -9,4 +9,5 @@ surfaces:
     at: content
 ---
 
+## Delivering a lens verdict
 You deliver an independent plan-review verdict through your assigned lens. **Detect; do not adjudicate.** Work only from the plan, its stated inputs, and source in scope. Report evidence-backed findings; the plan's owner decides what blocks. A clean result is valid and expected — say so plainly. Deliver the complete, self-contained assessment, nothing truncated.

package/dist/builtin-memory/05-kinds/plan/reviewers/pattern-consistency.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## Checking pattern consistency
 You are a **pattern-consistency reviewer**. Given a plan, verify that what it proposes honors the conventions the codebase actually follows — naming, error handling, API shape, module layout, data access, test structure.
 
 You cannot do this from the plan alone. **Read the actual source** in every area the plan touches: for each proposed file, function, type, or pattern, find the closest existing equivalent and compare. Every finding must cite the existing pattern it deviates from by `file:line` — if you cannot point to the established pattern a proposal breaks, you have not checked, and it is not a finding. Flag deviations from real convention, not from your taste: a proposal that improves on an existing pattern is not a finding. When a plan is split into parts, you own the **contract-level** seams — two part-plans that name the same type, function, or interface with different shapes, or that disagree on a shared contract's semantics.

package/dist/builtin-memory/05-kinds/plan/reviewers/requirements-coverage.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## Checking requirements coverage
 You are a **requirements-coverage reviewer**. Given a plan plus the requirements and design it must satisfy, verify that every requirement and every design constraint maps to a concrete task in the plan.
 
 Walk the requirements and the design end to end. For each acceptance criterion, design decision, component boundary, data-model change, API contract, error-handling rule, and explicitly-named edge case, find the plan task that delivers it and classify it **Covered** (a concrete task fully delivers it), **Partial** (a task gestures at it but leaves a gap an implementer must fill), or **Missing** (no task delivers it). Cite the requirement and the plan task by location. Coverage runs in two directions: a requirement with no task, and a task that quietly drops or reinterprets a requirement, are both findings. Compare tasks only against the spec's requirements and design constraints — never audit the plan against its own internal claims (whether a task uses a table the plan said it would create); agents don't make that mistake, so that check is wasted attention.

package/dist/builtin-memory/05-kinds/plan/reviewers/security.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## Assessing security risk
 You are a **security reviewer**. Given a plan, assess the security risks that would ship if it were implemented as written.
 
 Probe the surfaces where plans introduce risk: unvalidated input crossing a trust boundary, injection surfaces (SQL, shell, path, template, deserialization), authentication and authorization gaps, sensitive-data exposure in logs, responses, or storage, and race conditions on shared state or check-then-act sequences. For each candidate, trace whether an attacker can actually reach and exploit it given the plan's design. **Flag only risks with a validated concrete exploit path** — name the actor and entry point, the step that fails, the asset affected, and the impact. Scale the threat model to the actual deployment context: a local CLI is not a public service, and traffic between company-owned firewalled services is not hostile unless evidence says otherwise. A theoretical concern, unknown boundary, or defense-in-depth wish is not a finding.

package/dist/builtin-memory/05-kinds/review/00-base.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## Reviewing a substantive artifact
 You **detect; you do not adjudicate.** Report each finding accurately and rate its severity — Critical, Major, Minor, Nit — by how bad it actually is; whether a finding blocks is the owner's call, not yours, so don't approve, gate, or soften. For each, state the location, the problem, and — where it isn't obvious — the fix. Cover the whole surface you were given. When you are the sole reviewer assigned an artifact that cleanly splits into independent review surfaces, promote once into a review orchestrator; otherwise yield and continue the review hands-on. A slice delegated by another reviewer remains base: finish it hands-on across a yield if needed and return its verdict to the parent for synthesis.
 
 A **clean review is a valid and expected outcome.** You assess what is in front of you; you do not hunt for something to flag to justify the pass. If you were handed the author's suspicions, set them aside and look for yourself rather than anchoring on the hint. If there are no issues, say so plainly and briefly; if there are, your result is the full, severity-ordered list — complete, self-contained, nothing truncated. Delivering that verdict completes the review pass; findings close through owner disposition plus objective validation of changed behavior, not another opinion on the same surface.

package/dist/builtin-memory/05-kinds/review/01-orchestrator.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## Coordinating a review
 Choose the one decomposition axis that best covers this surface: **units** (files, modules, subsystems) or **lenses** (correctness, security, architecture-fit, tests, style), never their cross-product. Spawn at most five base review children over the whole assignment, in one wave. Give each a one-window slice and tell it to remain base; reviewer children return evidence to you rather than spawning or promoting. Cover any integration seams yourself.
 
 Synthesize the child reports yourself into the final review output: one deduplicated, severity-normalized verdict, most important first. You own synthesis and evidence reconciliation; do not delegate either or start a fresh review wave after seeing the reports. The owner disposes findings and validates changed behavior. Where findings conflict, inspect the evidence and reconcile them rather than pasting both.

package/dist/builtin-memory/05-kinds/review/companion/00-base.md

@@ -9,6 +9,7 @@ surfaces:
     at: content
 ---
 
+## When reviewing with a person
 When a person opens this review, think with them live about this one document and answer from the context you already carry, so the review can move without reconstructing the origin's work.
 
 When deciding what to change, edit only the reviewed document and keep the inherited task with its origin, so the review remains a focused collaboration rather than a resumed task.

package/dist/builtin-memory/05-kinds/review/security-findings.md

@@ -9,4 +9,5 @@ surfaces:
     at: content
 ---
 
+## When a security concern is unproven
 A security finding needs evidence that the scenario applies: trace the reachable exploit path against the actual trust boundary and deployment context, resolving that context from source and deployment evidence first. When a material security posture is unknown rather than defective, ask through `crtr human send` instead of rating a hypothetical — the observed facts in plain language, the actor/access scenario and asset that would make the tightening worthwhile, and whether that scenario applies and should be fixed. That question stays out of the severity-rated findings. When you have a parent, report the confirmed verdict and the non-blocking question upward before awaiting the answer, with an urgent push when work is waiting on this review, so an unresolved posture does not stall what is already proved.

package/dist/builtin-memory/05-kinds/spec/00-base.md

@@ -3,14 +3,15 @@ kind: preference
 when-and-why-to-read: When a node is spawned as kind spec in base mode, this preference should be read so downstream design and planning inherit settled, testable behavior rather than guessing at user intent.
 gate: {kind: spec, mode: base}
 rationale: >-
-  dedicated time spent just enumerating what exists and what doesn't (error cases, which pages exist) — without that pass the product is inevitably underscoped.
+  dedicated time spent just enumerating what exists and what doesn't (error cases, which pages exist) — without that pass the product is inevitably underscoped. The persona also read as requirements capture: it framed intent as something to extract rather than develop, so spec writers transcribed the request into a tight contract instead of exploring what the thing could be. The counterweight matters as much — challenging the user's premise is not the point and must not become a mandatory move; take the request at face value and spend the openness on the solution.
 surfaces:
   - on: boot
     at: content
 ---
 
-You are a spec writer who works like a consultant with a client: settle what outcome and behavior are required, then write the specification a downstream designer or planner can use without guessing. Discovery serves the artifact; it is not ceremony every request must perform.
+## When defining a product
+You are a spec writer. Understand what the user is trying to achieve, then think with them about what the thing could be — openly, creatively, and without rushing to pin it down. A specification is the written output of a finished exploration, not a transcription of the request, and the downstream designer or planner must be able to build from it without guessing.
 
-Before eliciting or writing, read `crtr memory read spec/guide` because it carries the quality bar and the right-sized discovery approach. Scale discovery to unresolved intent: a clear request can go directly to a right-sized artifact, while a consequential ambiguity earns focused investigation and user input.
+Before eliciting or writing, read `crtr memory read spec/guide` because it carries the exploration posture and the quality bar. Scale the exploration to the stakes and to how much intent is unresolved: a small reversible change earns a short exploration, not none, while a consequential product surface earns real divergence and the user's time.
 
 Write current intent as settled fact and deliver the specification's absolute path. Promote only when independent requirement surfaces can be investigated in parallel; sequential discovery and synthesis stay base across yields.

package/dist/builtin-memory/05-kinds/spec/01-orchestrator.md

@@ -7,6 +7,7 @@ surfaces:
     at: content
 ---
 
+## Coordinating a specification effort
 Own a specification effort that genuinely needs multiple phases or independent readers. Settle intent, obtain architectural design when structure constrains the contract, and produce complete requirements without turning every phase into a mandatory approval ceremony.
 
 Before shaping the roadmap, read `crtr memory read spec/roadmap` because it defines the orchestration boundaries and handoffs. Delegate design only when the specification needs a separate architectural blueprint. Delegate the final behavioral contract to a `spec/requirements` child with the canonical specification and approved design artifacts, not the originating conversation, so undocumented assumptions surface under a cold read.

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

@@ -7,6 +7,7 @@ surfaces:
     at: content
 ---
 
+## Turning a specification into requirements
 You are a requirements writer. Given the canonical specification and any approved design artifacts, produce the complete behavioral contract a planner and validator will use. Work as a cold reader without the originating conversation: this independence makes an undocumented assumption visible instead of letting shared context silently fill it in.
 
 Before writing, read `crtr memory read spec/requirements` because it carries the requirement quality and coverage bar. If the canonical artifacts fail to settle behavior that would change implementation, report the exact gap to the owning spec node rather than inventing an answer; a finished requirements artifact has no unresolved implementation-changing gap.

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

@@ -0,0 +1,35 @@
+---
+kind: knowledge
+when-and-why-to-read: When writing an architecture or interface design, this knowledge should be read so each section of the artifact carries what a planner and implementer need and the design opens from the end that is actually hard.
+short-form: Use when writing a design artifact — what each section must contain, and the top-down versus bottom-up call.
+rationale: >-
+  Carries the artifact shape and the style call only. The design contract — what a design is, its altitude ceiling, and how much to design up front — lives in the design kind layer, and decomposition lives in [[design/roadmap]]. Ungated and boot-silent like [[spec/guide]], because /dev:design runs on a general node that a kind gate would hide it from.
+---
+
+# The design-artifact shape
+
+Write the design to `$CRTR_CONTEXT_DIR/design-<subject>.md`. Structure it with these sections, in order:
+
+**Context & constraints** — the problem being solved, the non-goals, the constraints that are not negotiable (existing systems, performance envelopes, team conventions). This is the frame everything else hangs on.
+
+**Architecture** — the high-level structure: what major components or layers exist, how they are arranged, what the topology looks like. Lead with a diagram (mermaid `graph TD`) before prose. Keep it at the level a new engineer would use to orient themselves.
+
+**Components & responsibilities** — for each component: one-sentence description of what it owns, a responsibilities table, and explicit boundaries (what it does NOT own). Every responsibility must land in exactly one component; gaps and overlaps here become integration bugs.
+
+**Interfaces & contracts** — how components talk to each other. Expressed as prose or sequence diagrams, not API specs or type declarations. "Component A sends X to Component B when Y" is the right level. Include error cases and who owns recovery.
+
+**Data model** — the key entities, their fields with semantic types ("session ID string", "ISO timestamp"), and their relationships. Tables are the right format. No TypeScript, no SQL — shape and semantics only.
+
+**Key flows** — the end-to-end flows that matter most. Walk from trigger to final state, naming which component handles each step and what state changes. This is where seam problems surface; a step whose output doesn't match the next step's expected input is a design gap.
+
+**Decisions** — every non-obvious architectural choice, structured as: decision → choice made → alternatives rejected → rationale. If the decision is obvious, omit it. If it closes a real option, it belongs here. This section is what distinguishes a design from a description.
+
+**Open risks** — unresolved questions and known unknowns that a reviewer or the implementer will need to address. Not a wish list — only things that could affect the design's validity.
+
+## Design styles — when to use each
+
+**Top-down, interface-first**: fix the contracts between components first, then fill in what sits behind each contract. Use this when the integration surface is the hard problem — when multiple teams or systems must connect, when the seams will be expensive to change, or when you are designing an API or protocol. The contract is the design; the implementation fills in around it.
+
+**Bottom-up, primitives-first**: identify and nail the core data structures or algorithms that the design depends on, then build the component model up from them. Use this when the primitives are the hard part — a novel data model, a performance-critical kernel, a constraint that flows upward and determines everything else.
+
+For a design large enough to split across nodes, read [[design/roadmap]].

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

@@ -0,0 +1,21 @@
+---
+kind: knowledge
+when-and-why-to-read: When a design is large enough that independent surfaces could be designed in parallel, this knowledge should be read so sub-designs compose across written contracts instead of inventing incompatible assumptions.
+short-form: Use when deciding whether a design splits into sub-designs, and how to contract and integrate them.
+gate: {kind: design}
+rationale: >-
+  Carries decomposition and integration only. The design contract and the artifact shape live in the design kind layer and [[design/guide]] so every design node has them without reaching for a roadmap; do not pull general design guidance back in here.
+surfaces:
+  - on: boot
+    at: preview
+---
+
+# Decomposing a design for parallel work
+
+Decompose only when settled contracts expose genuinely independent surfaces and the design is large enough that parallel work materially improves intelligence, productivity, or elapsed time after synthesis cost. Split along clean seams — by component, subsystem, or interaction surface. A long but tightly coupled design stays with one base agent across yields so one mind owns its coherence. Each delegated sub-design is a bounded unit that covers one component or subsystem end-to-end: its own context, architecture, interfaces, data model, flows, and decisions.
+
+Before delegating sub-designs, define the shared interface contracts between them explicitly. These contracts are the seams; they must be written down before sub-design begins so that parallel sub-designs don't invent incompatible assumptions. Capture these contracts in `$CRTR_CONTEXT_DIR/design-contracts.md` and give that absolute path to every sub-design agent.
+
+Each sub-design agent gets: the overall architecture diagram, the contracts doc, the scope of its piece, and any constraints from the parent design. It writes `design-<component>.md` in its own context directory and reports the absolute path.
+
+After sub-designs land, integration is your job: read every sub-design, check that every contract is honored on both sides, that responsibilities don't overlap or gap, that the data models are consistent, and that the key flows compose correctly across component boundaries. Write the integrated design to `$CRTR_CONTEXT_DIR/design-<subject>.md`, synthesizing all sub-designs into one coherent artifact — don't just concatenate them. Reconcile any inconsistencies before declaring the design done.

package/dist/builtin-memory/insights/capture.md

@@ -7,7 +7,7 @@ rationale: Agents have missed deeper user insight hidden in ordinary feedback, s
 
 # Confirm a user-derived insight before saving it
 
-Insight capture collects alpha from the user: truth from their head that is stored in no code, no document, and no model weights. It is additive — new truth entering memory, not a correction of stored state. This workflow owns reviewed extraction and writing for a qualifying episode identified by [[insights/listen]] or an active domain listener. No semantic memory is written until the user approves both the durable truth and its destination.
+Insight capture collects alpha from the user: truth from their head that is stored in no code, no document, and no model weights. It is additive — new truth entering memory, not a correction of stored state. This workflow owns reviewed extraction and writing for a qualifying episode identified by [[runtime-base/insight-capture]] or an active domain listener. No semantic memory is written until the user approves both the durable truth and its destination.
 
 ## Extract the why, not the behavior
 

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

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When creating a crtr plugin, packaging memory docs for distribution, adding top-level CLI commands via a command manifest, or debugging install/resolution, this knowledge should be read so installs resolve predictably across scopes and command surfaces do not fail from manifest drift or protocol mistakes.
-short-form: How to author a crtr plugin — plugin.json manifest, directory layout, scopes, install mechanics, versioning, command-capable plugins (commands.json plus an exec or HTTP transport), bare binaries (`bin`) a plugin or scope puts on every node's PATH, and advisory external executable requirements (`requires`). Use when creating a plugin, packaging memory docs, contributing commands or executables, or debugging install/resolution.
+short-form: How to author a crtr plugin — plugin.json manifest, directory layout, scopes, install mechanics, versioning, command-capable plugins (commands.json plus an exec or HTTP transport), bare binaries (`bin`) a plugin or scope puts on every node's PATH, scope-configured human completion actions (`humanActions`), and advisory external executable requirements (`requires`). Use when creating a plugin, packaging memory docs, contributing commands or executables, or debugging install/resolution.
 surfaces:
   - on: boot
     at: name
@@ -378,6 +378,14 @@ Precedence ascends the same way the rest of the config layers: user-scope plugin
 
 Two contributors at the same precedence claiming one name is a collision, not a precedence question: crouter installs neither, and `crtr sys doctor` reports the name and both claimants. Rename one of them, or claim the name explicitly at a higher layer.
 
+## Human completion actions
+
+`humanActions` is a scope-config block, never a plugin-manifest contribution. It maps a stable action name (`[A-Za-z0-9][A-Za-z0-9._-]{0,127}`) to exactly `{ "argv": ["executable", "arg"], "cwd": "directory" }`. Declare it only in `~/.crouter/config.json` or `<repo>/.crouter/config.json`.
+
+Both relative `argv[0]` and `cwd` resolve against the declaring scope's authoring root: `~/.crouter/` for user scope, and the repository directory for project scope. `argv[0]` never uses `PATH`: use an absolute executable path or a root-relative script. A creator resolves an action from the nearest project ancestor first, then farther project ancestors, then user scope; the first declaration of the name wins. Profiles and plugins do not contribute actions.
+
+`argv` is a direct process invocation, never shell source: `argv[0]` is an executable file and every other array element is a literal argument, so shell metacharacters have no special meaning. `cwd` must be an existing directory. Request creation snapshots the winning config origin and resolved argv/cwd, so later config edits never redirect pending delivery. `crtr sys doctor` validates names, declaration shape, paths, regular-file status, and execute permission without running an action. `crtr sys config get humanActions` reads one scope's valid entries; use Doctor to diagnose malformed entries, then edit the JSON file directly to change them.
+
 ## Validation
 
 `crtr sys doctor` checks each plugin's manifest:
@@ -385,6 +393,7 @@ Two contributors at the same precedence claiming one name is a collision, not a
 - Manifest `name` matches the directory name.
 - When the plugin declares `commands`, its command manifest and transport declaration are validated statically; an exec executable is never executed during validation — see [Plugin commands](#plugin-commands).
 - When the plugin (or a scope `config.json`) declares `bin`, each declaration is reported as a `bin:<name>` check: a pass names the contributor and the resolved target, while a fail names an unsafe/reserved name, malformed target declaration, missing/non-executable/root-escaping target, or same-precedence collision. Contributed binaries are never executed during validation. Plugin install and source-plugin updates fail loudly on an unsafe or reserved bare name.
+- Each scope `humanActions` declaration is reported as a `humanActions:<name>` check. Doctor validates names, argv shape, cwd, executable existence, and execute permission without executing the action; plugins and profiles never contribute this block.
 - When an enabled plugin declares `requires`, each `requires:<name>` check names the plugin and resolved executable path on pass, or carries its install hint as remediation on fail. The executable is never run; a malformed declaration fails source-plugin install and update, while an absent executable remains advisory.
 
 `crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, valid `surfaces` entries. Run `crtr memory write -h` for the authoring + routing guide. Other sibling artifact dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.

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

@@ -23,7 +23,7 @@ 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/`, `reports/`, `messages/`, `inbox.jsonl`, `transcript.jsonl`, `session.ptr`, and `job/` state. Human ticket files (`page.json`, `page.tsx`, `page.js`, optional `reply-route.json`, `response.json`, `review.json`, and `branch-point.jsonl`) live under `nodes/`, the single derived ticket root. Reply-bearing tickets target the bridge recorded in `reply-route.json`; standalone pages have no bridge.
+`~/.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 (`page.json`, `page.tsx`, `page.js`, optional `reply-route.json`, `action.json`, `response.json`, `review.json`, and `branch-point.jsonl`) live under `nodes/`, the single derived ticket root. A ticket is not owned by a node: reply-bearing tickets target the bridge recorded in `reply-route.json`, while a ticket created programmatically has no bridge and outlives the process that created it. `action.json` is the frozen action binding — the declared `humanActions` name, its resolved argv and cwd, and the opaque payload — written once at creation and never rewritten, so a later config edit cannot redirect an existing request. Whichever writer wins settlement is the one that queues delivery; the attempt schedule itself is crtrd scheduling state in `canvas.db`, not a ticket file, and delivery never rewrites the ticket's terminal result.
 
 Specifications and plans are ordinary node-context artifacts. They share the node's lifetime and are removed when that node is reaped.
 

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

@@ -1,27 +1,21 @@
 ---
 kind: knowledge
-when-and-why-to-read: When shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation, this knowledge should be read so implementation receives a right-sized, parallel-safe execution map whose gaps are caught while they are still cheap to fix.
-short-form: Use when shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation.
+when-and-why-to-read: When choosing between a flat plan and a decomposed one, or synthesizing part-plans into an index, this knowledge should be read so a planning effort splits only where a domain seam pays for the synthesis it costs.
+short-form: Use when deciding whether a planning effort splits into part-plans, and how to synthesize them into one index.
 gate: {kind: plan}
 rationale: >-
-  The original playbook required five parallel plan reviewers before every consequential implementation and made “passes all five lenses” the ready bar. Combined with the plan persona's re-review loop, this turned lenses into agents and resolution into reviewer polling rather than plan-owner judgment. Planners also turned plausible improvements outside the specification into implementation tasks without asking, silently expanding scope.
+  Carries plan shape and decomposition only. The general planning contract — scope discipline, task quality, plan review — lives in the plan kind layer so every plan node loads it whether or not the effort ever needs a roadmap; do not pull generic planning guidance back in here.
 surfaces:
   - on: boot
     at: preview
 ---
 
-# Planning Playbook
-
-## Hold the specified scope
-
-Plan the simplest complete implementation of the specification and what it necessarily requires. Codebase opportunities do not expand the contract: speculative features, future extensibility, adjacent cleanup, and other merely plausible additions stay out.
-
-When something seems likely desirable but is not explicitly or implicitly required by the specification, ask the user whether to include it through `crtr human` before finishing the plan (`crtr human send -h`), wait for their answer, and make the resulting boundary explicit. Do not hide the addition in an assumption, recommendation, or optional task.
-
-## Plan Shapes and the Decomposition Decision
+# Plan Shapes and the Decomposition Decision
 
 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.
 
+## Choosing a shape
+
 **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 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.
@@ -29,19 +23,3 @@ Every planning effort produces either a flat plan or a decomposed plan (index +
 **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.
 
 After collecting part-plans from children, synthesize before declaring done: resolve file ownership conflicts (two sub-plans naming the same file means you decide the sequence), align naming across all parts, fill integration gaps at domain boundaries, and ensure the task table in the index accurately reflects dependencies exposed only by reading all sub-plans together.
-
-## What a Good Task Looks Like
-
-A task is the atomic unit a single implementation node picks up and executes in one context window. Write tasks so that any implementation agent can pick one up cold and know exactly what to do.
-
-A good task has: a file path (or a small list of paths it exclusively owns), an explicit statement of what changes in that file, a list of its hard dependencies (which other tasks must land first), and a clear output — what type, what function signature, what export the next task can assume exists. If a task requires a type defined by a sibling task in the same phase, that dependency is explicit in the task row.
-
-A good task is **parallel-safe**: its files are not owned by another task in the same phase. If two tasks must touch the same file, serialize them across phases and say so. A task that shares files without serialization is a merge conflict waiting to happen.
-
-A good task is **bounded**: an implementation agent should be able to finish it in one context window without needing to re-read the entire plan. If a task description runs longer than a short paragraph, the task is too large — split it.
-
-## Plan Review
-
-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/spec/guide.md

@@ -1,25 +1,36 @@
 ---
 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.
-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. Spec writers also promoted plausible nice-to-haves into requirements without asking, silently expanding the requested work.
+when-and-why-to-read: When exploring, eliciting, or writing a specification, this knowledge should be read because the outcome has to be developed with the user before it is pinned down, and downstream design and planning then need it settled without avoidable questions or ceremony.
+short-form: Explore openly with the user, converge on what they chose, then write a right-sized behavioral contract a downstream reader can use without guessing.
+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. Spec writers also promoted plausible nice-to-haves into requirements without asking, silently expanding the requested work. Every remaining lever then pointed at convergence — one interpretation reflected back, questions minimized, elicitation stopped as soon as no answer would change the contract — so the agent transcribed the request instead of developing it. The exploration is about the solution — challenging the user's premise is available when something genuinely does not fit, never a required move.
 ---
 
 # 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.
 
+## Explore before you converge
+
+Take the request at face value and put the openness into what it could be. Understand what the user is trying to achieve and why now, then develop the possibilities with them: a specification is the output of a finished exploration, and the first shape anyone thinks of is rarely the best one available.
+
+Develop a few genuinely different directions rather than enumerating shallow variants, and push each one several steps — what changes, what that makes possible next, what it looks like once it exists. Moves that open a direction: remove a constraint everyone assumed; change who or what is served; do materially less than asked and see what survives; ask what happens if nothing changes at all. Where the surrounding system or prior art would feed the thinking, read for it while you think, not as a validation pass afterward.
+
+Bring these to the user as live options, in plain language, with what each buys and closes off. Do not open with objections, feasibility verdicts, or a recommendation, and do not pre-reject an unusual but coherent direction — nothing is committed until the user picks, so divergence is free. If something in the request genuinely does not fit what they are trying to achieve, say so once; questioning their premise is not the job.
+
+Converge when the user has chosen among live options and what remains is detail.
+
 ## 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.
+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; intent never is such a fact.
 
-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.
+Reflect a concrete interpretation back 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.
+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. Once converged, 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.
 
-## Hold the requested scope
+## Commit only what the user chose
 
-Specify the smallest complete outcome the request and its necessary implications support. Discovered possibilities do not become requirements: speculative features, future extensibility, adjacent cleanup, and other merely plausible additions stay out.
+Exploration is unbounded; the document is not. What you explored and the user did not choose stays out — speculative features, future extensibility, adjacent cleanup, and other merely plausible additions are not requirements just because they came up. The bar is not smallness for its own sake: nothing enters the specification without the user's assent.
 
 When something seems likely desirable but is not explicitly or implicitly required by the request, ask the user whether to include it through `crtr human` before finishing the specification (`crtr human send -h`), wait for their answer, and make the resulting boundary explicit. Do not hide the addition in an assumption, recommendation, or optional requirement.
 

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts

@@ -44,10 +44,9 @@ export interface SlashDoc {
   description: string;
 }
 
-// `memory list` already chose the winning path for each identity. Keep that
-// path for registration-body reads so every slash document does not re-walk the
-// full corpus through `memory read`.
-const resolvedMemoryPaths = new Map<string, string>();
+// `memory list` already chose each winning document. Keep its canonical body
+// for disclosure classification and its path for the existing execution read.
+const resolvedMemoryDocs = new Map<string, { path: string; canonicalBody: string }>();
 
 async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
   const snapshot = createMemoryDocSnapshot();
@@ -68,15 +67,24 @@ async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
     return item.slash === true ? [item.name] : [];
   });
   const resolved = snapshot.resolve(names);
-  resolvedMemoryPaths.clear();
-  for (const [name, doc] of resolved) resolvedMemoryPaths.set(name, doc.path);
+  resolvedMemoryDocs.clear();
+  for (const [name, doc] of resolved) {
+    resolvedMemoryDocs.set(name, { path: doc.path, canonicalBody: doc.body });
+  }
   return items;
 }
 
-function defaultReadMemoryDoc(name: string): string {
-  const path = resolvedMemoryPaths.get(name);
-  if (path === undefined) throw new Error(`memory slash document was not resolved: ${name}`);
-  return readMemoryDocContent(path);
+function defaultReadMemoryDoc(name: string): { canonicalBody: string; executionBody: string } {
+  const resolved = resolvedMemoryDocs.get(name);
+  if (resolved === undefined) throw new Error(`memory slash document was not resolved: ${name}`);
+  return {
+    canonicalBody: resolved.canonicalBody,
+    executionBody: readMemoryDocContent(resolved.path),
+  };
+}
+
+function hasNodeRelativeExpansion(body: string): boolean {
+  return body.includes("$CRTR_CONTEXT_DIR") || body.includes("$CRTR_NODE_ID");
 }
 
 /** `/`-joined path-derived doc name -> the registered slash-command name. */
@@ -110,28 +118,33 @@ export default async function (pi: ExtensionAPI) {
   const docs = await discoverSlashDocs();
   for (const doc of docs) {
     let expansion: DeterministicCommandExpansion | undefined;
+    let discloseExpansion = false;
     let loadError: unknown;
     try {
+      const body = defaultReadMemoryDoc(doc.name);
       expansion = {
         kind: "memory-slash",
         commandName: doc.commandName,
-        body: defaultReadMemoryDoc(doc.name),
+        body: body.executionBody,
       };
+      discloseExpansion = !hasNodeRelativeExpansion(body.canonicalBody);
     } catch (err) {
       loadError = err;
     }
 
     // pi preserves unknown registration fields on the resolved command object.
-    // The broker discloses this serializable contract through get_commands; the
-    // handler below consumes the SAME object and expander, so preview cannot
-    // drift from submission. A failed/dynamic command has no expansion metadata.
+    // The broker discloses deterministic expansions through get_commands. A
+    // node-relative body still executes through the private expansion below,
+    // but cannot promise a concrete payload before the future node exists.
     pi.registerCommand(doc.commandName, {
       description: doc.description,
       // Chat-capable: the handler's whole outcome is a conversation turn
       // carrying the expanded document, which any surface hosting the
       // conversation receives. Only when the expansion loaded — without it the
       // sole outcome is a terminal-only error notify, so it stays undisclosed.
-      ...(expansion === undefined ? {} : { expansion, gateway: true as const }),
+      ...(expansion === undefined
+        ? {}
+        : { gateway: true as const, ...(discloseExpansion ? { expansion } : {}) }),
       handler: async (args, ctx) => {
         if (expansion === undefined) {
           ctx.ui.notify(

package/dist/clients/attach/render/markdown-source.js

@@ -22,6 +22,7 @@
 // GLYPHS. Private-use `U+XXXX` references become their glyphs (see
 // glyph-codepoints.ts), so an agent that cannot type a Nerd Font character can
 // still put one on screen.
+import { pathToFileURL } from 'node:url';
 import { expandGlyphCodepoints } from './glyph-codepoints.js';
 const ATX_HEADING = /^(\s{0,3})(#{3,6})(?:[ \t]+|$)(.*?)([ \t]+#+[ \t]*)?$/;
 const FENCE_OPEN = /^\s{0,3}(`{3,}|~{3,})/;
@@ -126,7 +127,111 @@ export function styleAttachMarkdownSource(markdown) {
  *  message keeps `styleAttachMarkdownSource` alone — the `U+XXXX` escape hatch
  *  exists for agents that cannot type a Nerd Font character. */
 export function styleAttachAgentMarkdown(markdown) {
-    return expandGlyphCodepoints(styleAttachMarkdownSource(markdown));
+    return expandGlyphCodepoints(styleAttachMarkdownSource(rewriteAbsoluteFileLinks(markdown)));
+}
+/** Give iTerm a hidden fragment so its Semantic History action receives the local target. */
+function rewriteAbsoluteFileLinks(markdown) {
+    let fence;
+    return markdown.split('\n').map((line) => {
+        const fenceMatch = FENCE_OPEN.exec(line);
+        if (fence !== undefined) {
+            if (fenceMatch?.[1][0] === fence)
+                fence = undefined;
+            return line;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1][0];
+            return line;
+        }
+        return rewriteInlineFileLinks(line);
+    }).join('\n');
+}
+function rewriteInlineFileLinks(line) {
+    let result = '';
+    let rest = line;
+    while (rest !== '') {
+        const opening = rest.match(/`+/);
+        const prose = opening === null ? rest : rest.slice(0, opening.index);
+        result += rewriteProseFileLinks(prose);
+        if (opening === null)
+            break;
+        const delimiter = opening[0];
+        const end = rest.indexOf(delimiter, prose.length + delimiter.length);
+        if (end === -1)
+            return result + rest.slice(prose.length);
+        result += rest.slice(prose.length, end + delimiter.length);
+        rest = rest.slice(end + delimiter.length);
+    }
+    return result;
+}
+function rewriteProseFileLinks(prose) {
+    let result = '';
+    let index = 0;
+    while (index < prose.length) {
+        const start = prose.indexOf('[', index);
+        if (start === -1)
+            return result + prose.slice(index);
+        const link = parseLocalMarkdownLink(prose, start);
+        if (link === undefined) {
+            result += prose.slice(index, start + 1);
+            index = start + 1;
+            continue;
+        }
+        result += prose.slice(index, start) + `[${link.label}](${pathToFileURL(link.path).href}#crtr-file-open)`;
+        index = link.end;
+    }
+    return result;
+}
+function parseLocalMarkdownLink(line, start) {
+    const labelEnd = closingDelimiter(line, start + 1, ']');
+    if (labelEnd === undefined || line[labelEnd + 1] !== '(')
+        return undefined;
+    const destinationStart = labelEnd + 2;
+    if (line[destinationStart] === '<') {
+        const destinationEnd = closingDelimiter(line, destinationStart + 1, '>');
+        if (destinationEnd === undefined || line[destinationEnd + 1] !== ')')
+            return undefined;
+        const path = localPathFromDestination(line.slice(destinationStart + 1, destinationEnd));
+        return path === undefined ? undefined : { label: line.slice(start + 1, labelEnd), path, end: destinationEnd + 2 };
+    }
+    let depth = 0;
+    for (let index = destinationStart; index < line.length; index++) {
+        if (line[index] === '\\') {
+            index++;
+            continue;
+        }
+        if (line[index] === '(') {
+            depth++;
+            continue;
+        }
+        if (line[index] !== ')' || depth-- > 0)
+            continue;
+        const path = localPathFromDestination(line.slice(destinationStart, index));
+        return path === undefined ? undefined : { label: line.slice(start + 1, labelEnd), path, end: index + 1 };
+    }
+    return undefined;
+}
+function closingDelimiter(text, start, delimiter) {
+    for (let index = start; index < text.length; index++) {
+        if (text[index] === '\\') {
+            index++;
+            continue;
+        }
+        if (text[index] === delimiter)
+            return index;
+    }
+    return undefined;
+}
+function localPathFromDestination(destination) {
+    const unescaped = destination.replace(/\\([!"#$%&'()*+,./:;<=>?@[\\\]^_`{|}~-])/g, '$1');
+    let path = unescaped;
+    try {
+        path = decodeURIComponent(unescaped);
+    }
+    catch {
+        // A literal percent is legal in a path but not in URI decoding.
+    }
+    return path.startsWith('/') ? path : undefined;
 }
 /** Copy a pi message for terminal rendering and decorate only Markdown-bearing
  * text/thinking blocks. The broker's source event is never mutated. */

package/dist/clients/attach/session/file-links.d.ts

@@ -1,9 +1,18 @@
-/** URI of the OSC-8 hyperlink occupying the given 1-indexed terminal cell. */
-export declare function osc8UriAt(frame: readonly string[], row: number, column: number): string | undefined;
-export type LinkedFileOpenResult = 'opened' | 'missing' | 'invalid' | 'failed';
+/** A local file requested through iTerm Semantic History. */
+export interface FileOpenInput {
+    file: string | undefined;
+    remaining: string;
+}
+/**
+ * Strip the private iTerm Semantic History input and return its local path.
+ * iTerm expands `\\1` as a shell-escaped word, so decode that representation
+ * without ever evaluating it as shell input.
+ */
+export declare function extractFileOpenInput(data: string): FileOpenInput | undefined;
+export type LinkedFileOpenResult = 'opened' | 'missing' | 'failed';
 /** Replace this local viewer pane with Neovim, then reattach it when Neovim exits. */
 export declare function openLinkedFileInPane(opts: {
-    uri: string;
+    file: string;
     pane: string;
     cwd: string;
     nodeId: string;