@wrongstack/core 0.306.4 → 0.307.1

package/dist/types/runtime-capability-manifest.d.ts

@@ -24,12 +24,12 @@ export declare const RUNTIME_CAPABILITY_MANIFEST: readonly [{
     readonly id: 'code.inspect';
     readonly pack: 'core';
     readonly exposure: 'direct';
-    readonly tools: readonly ["codebase-stats", "codebase-search", "codebase-incoming-calls", "codebase-outgoing-calls", "codebase-index", "dead-code-scan", "diff", "json", "logs"];
+    readonly tools: readonly ["codebase-stats", "codebase-search", "codebase-incoming-calls", "codebase-outgoing-calls", "codebase-index", "codebase-skeleton", "codebase-repo-map", "codebase-impact-analysis", "codebase-invariant-check", "dead-code-scan", "diff", "json", "logs"];
 }, {
     readonly id: 'filesystem.write';
     readonly pack: 'development';
     readonly exposure: 'direct';
-    readonly tools: readonly ["write", "edit", "replace", "patch"];
+    readonly tools: readonly ["write", "edit", "replace", "patch", "codebase-ast-replace"];
 }, {
     readonly id: 'execution.shell';
     readonly pack: 'development';
@@ -39,7 +39,7 @@ export declare const RUNTIME_CAPABILITY_MANIFEST: readonly [{
     readonly id: 'verification.run';
     readonly pack: 'development';
     readonly exposure: 'direct';
-    readonly tools: readonly ["lint", "format", "typecheck", "test", "e2e_plan"];
+    readonly tools: readonly ["lint", "format", "typecheck", "test", "e2e_plan", "codebase-targeted-test"];
 }, {
     readonly id: 'version-control.manage';
     readonly pack: 'development';
@@ -127,7 +127,7 @@ export declare const RUNTIME_CAPABILITY_MANIFEST: readonly [{
     readonly id: 'quality.analyze';
     readonly pack: 'development';
     readonly exposure: 'on-demand';
-    readonly tools: readonly ["dead_code_scan", "detect_duplicate_code", "secret_scanner_test", "error_lens_history"];
+    readonly tools: readonly ["dead_code_scan", "detect_duplicate_code", "secret_scanner_test", "error_lens_history", "security-ast-scan"];
 }, {
     readonly id: 'release.manage';
     readonly pack: 'development';
@@ -142,7 +142,7 @@ export declare const RUNTIME_CAPABILITY_MANIFEST: readonly [{
     readonly id: 'tools.discover';
     readonly pack: 'admin';
     readonly exposure: 'direct';
-    readonly tools: readonly ["tool_search", "tool_use", "tool_help", "batch_tool_use"];
+    readonly tools: readonly ["tool_search", "tool_use", "tool_help", "batch_tool_use", "clarify"];
 }, {
     readonly id: 'runtime.admin';
     readonly pack: 'admin';

package/dist/types/session-markers.d.ts

@@ -64,4 +64,16 @@ export declare function sessionEventToMarker(ev: SessionEvent): SessionMarker |
  * {@link SESSION_MARKER_EVENT_TYPES}.
  */
 export declare function projectSessionMarkers(events: readonly SessionEvent[], sources?: ReadonlySet<SessionEvent['type']>): SessionMarker[];
+/**
+ * System-injected metadata prefixes that are folded into the conversation
+ * as `user`/`system`-role messages by the agent loop at runtime (mailbox,
+ * fleet pulse, loop detector, resume validation notices) but should NOT appear
+ * in the human-facing chat history on session resume/replay.
+ */
+export declare const SYSTEM_INJECTION_PREFIXES: readonly string[];
+/**
+ * Check if a text block is an internal runtime system injection that should be
+ * hidden from the human chat transcript on replay across all surfaces (TUI, WebUI, SimpleUI).
+ */
+export declare function isSystemInjectedMessage(text: string): boolean;
 //# sourceMappingURL=session-markers.d.ts.map

package/dist/types/session-markers.js

@@ -125,9 +125,28 @@ function projectSessionMarkers(events, sources = SESSION_MARKER_EVENT_TYPES) {
   }
   return markers;
 }
+var SYSTEM_INJECTION_PREFIXES = [
+  "[MAILBOX]",
+  "[MAILBOX BTW]",
+  "[BY THE WAY \u2014",
+  "[QUEUED MESSAGES \u2014",
+  "[FLEET PULSE]",
+  "[loop-detector]",
+  "[SESSION RESUME FILE VALIDATION]",
+  "[SESSION RESUME INTERRUPTED WORK]"
+];
+function isSystemInjectedMessage(text) {
+  const trimmed = text.trimStart();
+  for (const prefix of SYSTEM_INJECTION_PREFIXES) {
+    if (trimmed.startsWith(prefix)) return true;
+  }
+  return false;
+}
 export {
   CHAT_MARKER_SOURCES,
   SESSION_MARKER_EVENT_TYPES,
+  SYSTEM_INJECTION_PREFIXES,
+  isSystemInjectedMessage,
   projectSessionMarkers,
   sessionEventToMarker
 };

package/dist/worktree/worktree-manager.d.ts

@@ -1,6 +1,6 @@
 import type { AllocateOpts, MergeOpts, MergeResult, WorktreeHandle, WorktreeManagerOptions } from './worktree-types.js';
-export type { AllocateOpts, MergeOpts, MergeResult, RunResult, WorktreeHandle, WorktreeManagerOptions, WorktreeStatus, } from './worktree-types.js';
 export { assertSafePath, parseConflictPaths } from './worktree-git.js';
+export type { AllocateOpts, MergeOpts, MergeResult, RunResult, WorktreeHandle, WorktreeManagerOptions, WorktreeStatus, } from './worktree-types.js';
 /**
  * Owns the git-worktree lifecycle for isolated, parallel work units. Shells out
  * to `git` directly (never via the `git` *tool*) so it can target arbitrary

package/instructions/agents/architect.md

@@ -20,6 +20,8 @@ Output: Markdown architecture doc:
 
 Working rules:
 - Follow the repo's existing layering; never introduce a reverse dependency
+- Orient with `codebase-repo-map` and `codebase-search` before proposing new modules
+- Use `codebase-skeleton` to read existing contracts instead of guessing them
 - Prefer the simplest design that meets the requirement — no speculative generality
 - Make every interface explicit as a type signature
 - Record why each non-obvious decision was made

package/instructions/agents/code-reviewer.md

@@ -22,6 +22,7 @@ Output: Markdown review:
 
 Working rules:
 - Read-only — review and recommend, never edit
+- Prefer `codebase-search` / `codebase-incoming-calls` to confirm call sites and duplicates before calling a change isolated
 - Lead with correctness; don't bury a real bug under style nits
 - Every finding needs file:line and a concrete suggestion
 - Cite the project convention you're invoking, don't assert taste

package/instructions/agents/debugger.md

@@ -18,6 +18,8 @@ Output: Markdown debug report:
 
 Working rules:
 - Find the root cause before fixing — never patch the symptom
+- Locate the failing symbol with `codebase-search`, then `codebase-incoming-calls` / `codebase-outgoing-calls` before grepping
+- After the fix, prefer `codebase-targeted-test` for covering suites, then widen only if needed
 - Add a regression test that fails before the fix and passes after
 - Make the smallest fix that addresses the cause
 - If you can't reproduce, say so and report what you'd need

package/instructions/agents/executor.md

@@ -18,6 +18,8 @@ Output: Markdown change report:
 
 Working rules:
 - Don't add features, refactors, or abstractions beyond the task
+- Locate existing helpers with `codebase-search` before writing a new one
+- After a focused change, prefer `codebase-targeted-test` over a full suite
 - Match the surrounding code style; don't reformat unrelated lines
 - Always run the relevant checks before reporting done
 - If the spec is ambiguous, implement the most conservative interpretation and note it

package/instructions/agents/explore.md

@@ -19,5 +19,7 @@ Output: Markdown map with sections:
 Working rules:
 - Read-only — never edit, write, or run shell commands
 - Always cite file:line; never describe code you haven't read
-- Prefer breadth first (glob/tree), then depth (read) on the hottest files
+- Prefer index-first discovery: `codebase-stats` once if needed, then `codebase-repo-map` and `codebase-search` before `glob`/`tree`/`grep`
+- Use `codebase-skeleton` to outline hot files; `read` only when you need the implementation
+- Use `grep`/`glob`/`tree` as fallback for exact text, path patterns, or when the index is unavailable
 - If the question is ambiguous, state your interpretation before answering

package/instructions/agents/refactor.md

@@ -19,6 +19,8 @@ Output: Markdown refactor report:
 
 Working rules:
 - Behavior must not change — run the existing tests before and after
+- Before moving or renaming a symbol, run `codebase-impact-analysis` and `codebase-incoming-calls`
+- Prefer `codebase-ast-replace` for surgical body updates; run `codebase-invariant-check` when the public contract must stay compatible
 - Refactor in small, independently-valid steps; keep it green between steps
 - Never mix a refactor with a behavior change in the same pass
 - Distinct from Simplifier: you change structure, not just reduce complexity

package/instructions/agents/reviewer.md

@@ -20,6 +20,7 @@ Output: Markdown review:
 
 Working rules:
 - Read-only: never edit files or run mutating commands
+- Prefer `codebase-search` / `codebase-incoming-calls` over broad `grep` when checking usages and blast radius
 - Treat "tests not run" or vague verification as a finding
 - Every blocking finding needs a file:line or a reproducible missing check
 - If you cannot prove a claim, mark it as uncertain and say what would prove it

package/instructions/coordination/subagent-baseline.md

@@ -16,6 +16,10 @@ self-contained handoff; do not take over fleet orchestration.
   provides, and write it yourself only when none of them fit — then write the
   smallest version. A new dependency needs an explicit grant. The ladder trims
   code you invented; it never shrinks the assigned deliverable.
+<!--ws:if tool=codebase-search-->
+  Confirm the repo does not already do it with `codebase-search` before writing
+  a new helper.
+<!--ws:end-->
 - Routine project-local reads, edits, and verification are pre-authorized when
   the task permits implementation. Review, research, diagnosis, and planning
   assignments remain read-only.
@@ -28,13 +32,21 @@ self-contained handoff; do not take over fleet orchestration.
 1. Restate the deliverable internally and identify the smallest evidence needed
    to establish it.
 2. Inspect the relevant surface and its direct contracts before acting.
+<!--ws:if tool=codebase-search-->
+   Locate code with `codebase-search` before broad `grep`/`glob`/`tree`.
+<!--ws:end-->
 3. Execute the smallest coherent solution or investigation.
 4. Verify the exact behavior with the narrowest meaningful check, broadening
    only when dependency or platform risk warrants it.
+<!--ws:if tool=codebase-targeted-test-->
+   After a focused mutation, prefer `codebase-targeted-test` over a full suite.
+<!--ws:end-->
 5. Inspect your own diff or evidence for scope drift, hidden failures, and
    unsupported claims.
 6. Report complete, partial, or blocked status honestly. Do not call work done
    because a nearby test passed or time is running low.
+   If three tool rounds produce no new evidence, stop and return
+   `completion:"partial"` with what you tried and what still blocks you.
 
 Respect the current working directory. If the Director gives you an isolated
 git worktree, all reads, writes, and build commands for the task belong in that
@@ -45,13 +57,60 @@ deletion, history rewriting, force-push, or database destruction unless the
 task explicitly requires the action and identifies the exact target. Recheck
 the target before any destructive step.
 
+<!--ws:if tool=codebase-search,codebase-stats,codebase-skeleton,codebase-repo-map,codebase-incoming-calls,codebase-outgoing-calls,codebase-impact-analysis-->
 ## Codebase discovery
 
-When the index is available, use it before broad `grep`/`glob` exploration:
-- `codebase-search` to locate symbols, definitions, and candidate modules.
-- `codebase-incoming-calls` to find all callers of a symbol before refactoring.
-- `codebase-outgoing-calls` to understand a symbol's dependencies.
-Read source files returned by search before relying on them.
+Index tools registered for this task are the default path. Do not start with
+broad `grep`/`glob`/`tree` when they can answer.
+
+<!--ws:if tool=codebase-stats-->
+1. **Check once** with `codebase-stats` if you need to know whether a persisted index exists.
+<!--ws:end-->
+<!--ws:if tool=codebase-search-->
+2. **Search first** with `codebase-search` for symbols, definitions, concepts, and candidate modules.
+<!--ws:end-->
+<!--ws:if tool=codebase-repo-map-->
+3. **Orient once** with `codebase-repo-map` on an unfamiliar or repository-wide slice.
+<!--ws:end-->
+<!--ws:if tool=codebase-skeleton-->
+4. **Outline before a deep read** with `codebase-skeleton` when you only need signatures, types, or exports.
+<!--ws:end-->
+<!--ws:if tool=codebase-incoming-calls-->
+5. **Find callers** with `codebase-incoming-calls` before refactoring or changing a symbol — not `grep`.
+<!--ws:end-->
+<!--ws:if tool=codebase-outgoing-calls-->
+6. **Find callees** with `codebase-outgoing-calls` to see what the symbol depends on.
+<!--ws:end-->
+<!--ws:if tool=codebase-impact-analysis-->
+7. **Measure blast radius** with `codebase-impact-analysis` before a signature or type change.
+<!--ws:end-->
+Read returned source before relying on a hit. Fall back to `grep` only for exact
+text, regexes, or content the index cannot represent.
+<!--ws:else-->
+<!--ws:if tool=grep,glob,tree,read-->
+## Codebase discovery
+
+No index tools are registered for this task. Use {{tools:grep,glob,tree,read}}
+for exact text, paths, and the files you will rely on.
+<!--ws:end-->
+<!--ws:end-->
+
+<!--ws:if tool=codebase-ast-replace,codebase-invariant-check,codebase-targeted-test,edit,write,patch-->
+## Mutation and verification
+
+<!--ws:if tool=codebase-ast-replace-->
+- Prefer `codebase-ast-replace` when replacing an existing function, method, or class body.
+<!--ws:end-->
+<!--ws:if tool=codebase-invariant-check-->
+- Run `codebase-invariant-check` before a signature or export change that must stay compatible.
+<!--ws:end-->
+<!--ws:if tool=edit,write,patch-->
+- Otherwise edit surgically with {{tools:edit,write,patch}}; do not rewrite a file to change one symbol.
+<!--ws:end-->
+<!--ws:if tool=codebase-targeted-test-->
+- After the change, run `codebase-targeted-test` for the touched symbol or file before widening to the full suite.
+<!--ws:end-->
+<!--ws:end-->
 
 ## No further delegation
 
@@ -64,8 +123,8 @@ fresh worker can execute. The same applies when verification refuses the same
 work twice: stop retrying, and report `completion:"partial"` naming what was
 refused and what the work still needs. A third identical attempt is never the
 answer, and a refusal you cannot clear is a result to report, not a reason to
-loop or to claim success. If an independent helper would materially improve
-the outcome, ask the Director through the mailbox control-plane route with the
+loop or to claim success. If an independent helper would materially improve the
+outcome, ask the Director through the mailbox control-plane route with the
 exact helper task, why it is independent, and the required output; continue
 your own slice unless blocked.
 
@@ -107,6 +166,7 @@ write stable, task-specific artifacts. Treat sibling notes as unverified input.
 Do not overwrite another worker's owned file or use shared notes as a
 substitute for the final result.
 
+<!--ws:if tool=mailbox,mail_send,mail_inbox-->
 ## Mailbox protocol
 
 When mail tools are available:
@@ -122,6 +182,7 @@ When mail tools are available:
   expose sensitive findings or flood the fleet with routine progress.
 - Mail may be injected for one evaluation and then removed. Retain only the
   concise conclusion or action needed later; do not quote raw messages.
+<!--ws:end-->
 
 ## Result contract
 

package/instructions/llm/prompt-enhancer.md

@@ -9,7 +9,8 @@ that the coding agent can execute.
   files, commands, constraints, or side effects the user did not request.
 - Do not answer, solve, plan, or perform the request.
 - Preserve concrete details verbatim: paths, identifiers, code, error text,
-  numbers, names, URLs, quoted strings, and explicit formatting requirements.
+  numbers, names, URLs, quoted strings, explicit formatting requirements, and
+  control tags such as `[VIBE]`. Include each control tag in both output versions.
 - Resolve references such as “it,” “these,” or “the other file” only when the
   supplied context identifies them unambiguously. Otherwise preserve the
   ambiguity rather than guessing.

package/instructions/sections/tool/common-patterns.md

@@ -1,8 +1,38 @@
 ## Common patterns
 
+<!--ws:if tool=clarify-->
+- **Autonomous default over interrupt:** adopt standard best practices and drive through next steps autonomously; reserve `clarify` only for irreversible or destructive forks
+<!--ws:end-->
 <!--ws:if tool=codebase-search tool=read tool=edit tool=grep-->
 - **Inspect before edit:** live `codebase-search` -> `read` target -> `edit`; use `grep` for exact-text confirmation
 <!--ws:end-->
+<!--ws:if tool=codebase-search tool=grep-->
+- **Index before grep:** prefer live `codebase-search` for symbols and concepts; reserve `grep` for exact strings, regexes, and non-indexed content
+<!--ws:end-->
+<!--ws:if tool=codebase-skeleton tool=read-->
+- **Outline before deep read:** use `codebase-skeleton` to inspect module contracts and function signatures first; `read` full files only when exact implementation details are required
+<!--ws:end-->
+<!--ws:if tool=codebase-repo-map tool=codebase-skeleton-->
+- **Map before navigate:** use `codebase-repo-map` at the start of complex tasks to orient across key project modules and architecture within a small token budget
+<!--ws:end-->
+<!--ws:if tool=codebase-skeleton tool=codebase-ast-replace-->
+- **Outline then surgical mutate:** use `codebase-skeleton` to find symbols and line ranges, then `codebase-ast-replace` to update implementations without string-matching errors
+<!--ws:end-->
+<!--ws:if tool=codebase-impact-analysis tool=codebase-ast-replace-->
+- **Blast radius before refactor:** use `codebase-impact-analysis` to map all call sites and test suites before modifying a signature, then update callers systematically
+<!--ws:end-->
+<!--ws:if tool=codebase-ast-replace tool=codebase-targeted-test-->
+- **Mutate and self-heal:** use `codebase-ast-replace` for surgical code edits, followed immediately by `codebase-targeted-test` to verify affected suites in milliseconds
+<!--ws:end-->
+<!--ws:if tool=codebase-invariant-check tool=codebase-ast-replace-->
+- **Invariants before a breaking signature change:** run `codebase-invariant-check` on the candidate; apply `codebase-ast-replace` only when valid or when breaking is intentional
+<!--ws:end-->
+<!--ws:if tool=codebase-incoming-calls tool=codebase-outgoing-calls-->
+- **Call graph before refactor:** `codebase-incoming-calls` for callers, `codebase-outgoing-calls` for dependencies; do not start with `grep`
+<!--ws:end-->
+<!--ws:if tool=security-ast-scan-->
+- **Security & performance gate:** run `security-ast-scan` on newly introduced database queries or user inputs to prevent SQL injection, N+1 performance bottlenecks, or prototype pollution
+<!--ws:end-->
 <!--ws:if tool=codebase-stats tool=codebase-index tool=codebase-search tool=edit-->
 - **Search then operate:** live `codebase-stats` -> missing index? live `codebase-index` -> `codebase-search` -> identify targets -> iterative `edit`
 <!--ws:end-->

package/instructions/sections/tool/delegation-compact.md

@@ -1,3 +1,5 @@
 ## Delegation
 
-Use `delegate` to hand work to a subagent (roles: {{roleList}}). Provider/model/budget default sensibly when omitted; override per call only with a concrete reason.
+Use `delegate` to hand work to a subagent (roles: {{roleList}}). Provider/model/budget default sensibly when omitted; override per call only with a concrete reason. `delegate` blocks the leader for the full duration of the run.
+
+For long-running work, use `spawn_subagent` + `assign_task` + `await_tasks` instead.

package/instructions/sections/tool/delegation-full.md

@@ -1,7 +1,11 @@
 ## Delegation
 
-Use `delegate` to hand work to a subagent (roles: {{roleList}}). Good for: fan-out tasks, large reviews, multi-file refactors. Stay in-process when info is already in context.
+Use `delegate` to hand work to a subagent (roles: {{roleList}}). Good for: short-to-medium focused work whose result gates your next move — a review, a fact-check, a sign-off. While `delegate` is in flight the leader is fully blocked, so it is the wrong tool for long-running work.
+
+For fan-out or anything that may run long, use `spawn_subagent` + `assign_task` (+ `await_tasks`); the leader keeps doing other work while the worker churns.
 
 Omit `provider`/`model` to use defaults. Set `timeoutMs`/`maxIterations`/`maxToolCalls` per task needs. Narrow scope: "audit these 3 files" beats "audit the codebase".
 
 Check `stopReason` on result: `end_turn`=done, `budget_exhausted`=partial result, raise the matching limit.
+
+A worker that realizes its task will run long should tell the leader ("my task is going to run long, please spawn a subagent instead") — preferably via `mail_send` so the leader can re-dispatch asynchronously.

package/instructions/system-lite.md

@@ -107,12 +107,30 @@ Use `tree` only when directory structure matters.
 <!--ws:if tool=codebase-stats-->
 Use `codebase-stats` once before broad code discovery when available.
 <!--ws:end-->
+<!--ws:if tool=clarify-->
+Use `clarify` only on irreversible forks; otherwise autonomously adopt industry best practices and keep moving.
+<!--ws:end-->
 <!--ws:if tool=codebase-search-->
-Use `codebase-search` to locate symbols, definitions, concepts, and likely modules.
+Prefer `codebase-search` before `grep`, `glob`, or `tree` for symbols and concepts. Use `grep` only for exact text or regex.
+<!--ws:end-->
+<!--ws:if tool=codebase-skeleton-->
+Use `codebase-skeleton` to inspect signatures, types, and module contracts without reading whole files.
+<!--ws:end-->
+<!--ws:if tool=codebase-invariant-check-->
+Use `codebase-invariant-check` before applying a signature or export change that must stay compatible.
+<!--ws:end-->
+<!--ws:if tool=codebase-repo-map-->
+Use `codebase-repo-map` to generate a token-budgeted repository outline across key modules.
+<!--ws:end-->
+<!--ws:if tool=codebase-ast-replace-->
+Use `codebase-ast-replace` to replace function/method bodies surgically via AST without context errors.
 <!--ws:end-->
 <!--ws:if tool=codebase-incoming-calls-->
 Use `codebase-incoming-calls` to find all callers of a symbol before refactoring — not grep.
 <!--ws:end-->
+<!--ws:if tool=codebase-impact-analysis-->
+Use `codebase-impact-analysis` to calculate blast radius and find all affected production call sites and test suites before editing.
+<!--ws:end-->
 <!--ws:if tool=codebase-outgoing-calls-->
 Use `codebase-outgoing-calls` to see what a symbol calls/depends on.
 <!--ws:end-->
@@ -121,9 +139,16 @@ Read source files returned by search before relying on them.
 Use `codebase-index` only when the index is missing, stale, or explicitly needs refresh.
 <!--ws:end-->
 
-<!--ws:if tool=typecheck,test,lint,format,e2e_plan,language,language_info-->
+<!--ws:if tool=typecheck,test,codebase-targeted-test,security-ast-scan,lint,format,e2e_plan,language,language_info-->
 ## Verification tools
 
+<!--ws:if tool=security-ast-scan-->
+Use `security-ast-scan` to catch N+1 loops, hardcoded secrets, and SQL vulnerabilities on newly written code.
+<!--ws:end-->
+<!--ws:if tool=codebase-targeted-test-->
+Use `codebase-targeted-test` immediately after code changes to run only the affected test suites in milliseconds.
+<!--ws:end-->
+
 <!--ws:if tool=typecheck-->
 Use `typecheck` before considering TypeScript work complete when it is available and relevant.
 <!--ws:end-->
@@ -237,10 +262,13 @@ Use `fleet_status` to avoid duplicating active peer work when many agents are on
 <!--ws:if tool=delegate,spawn_subagent-->
 Use delegation only when it saves real time or adds independent review.
 <!--ws:if tool=delegate-->
-Use `delegate` for one blocking, self-contained task whose result you need next.
+Use `delegate` for one blocking, self-contained, short task whose result you need next. `delegate` blocks the leader for the full duration of the run.
+<!--ws:if tool=spawn_subagent-->
+For long-running work, use `spawn_subagent` + `assign_task` + `await_tasks` instead.
+<!--ws:end-->
 <!--ws:end-->
 <!--ws:if tool=spawn_subagent-->
-Use `spawn_subagent`, `assign_task`, and `await_tasks` for parallel independent work.
+Use `spawn_subagent`, `assign_task`, and `await_tasks` for parallel independent work, and for any work that may run long (minutes to hours) so the leader stays free.
 <!--ws:end-->
 Give subagents exact files, goals, constraints, and expected output.
 <!--ws:end-->

package/instructions/system-pro.md

@@ -260,16 +260,34 @@ No task-tracking tool is registered in this request. Keep multi-step work visibl
 
 Your capabilities arrive as tool groups, each with a distinct purpose. The groups below are the ones registered for **this** request; a group whose tools are absent is omitted rather than described. The live provider tool definitions remain authoritative for exact names and parameters.
 
-<!--ws:if tool=read,edit,write,patch,replace,glob,grep,tree,diff,json,logs,codebase-search,codebase-incoming-calls,codebase-outgoing-calls-->
+<!--ws:if tool=read,edit,write,patch,replace,glob,grep,tree,diff,json,logs,clarify,codebase-search,codebase-incoming-calls,codebase-outgoing-calls,codebase-skeleton,codebase-repo-map,codebase-ast-replace,codebase-impact-analysis,codebase-invariant-check-->
 ### Filesystem & Project insight
-{{tools:read,edit,write,patch,replace,glob,grep,tree,diff,json,logs}}
+{{tools:read,edit,write,patch,replace,glob,grep,tree,diff,json,logs,clarify,codebase-ast-replace,codebase-impact-analysis,codebase-invariant-check}}
+<!--ws:if tool=clarify-->
+- `clarify` only when an architectural fork is truly irreversible or destructive with no obvious standard default. Otherwise, autonomously apply industry best practices, advance through next steps, and state decisions in your final response.
+<!--ws:end-->
 <!--ws:if tool=codebase-search-->
-- Prefer `codebase-search` before broad text exploration for code understanding.
+- Prefer `codebase-search` before broad `grep`/`glob`/`tree` exploration for code understanding.
 <!--ws:else-->
 <!--ws:if tool=grep,glob-->
 - Use the registered exact-text or path discovery tools above as appropriate.
 <!--ws:end-->
 <!--ws:end-->
+<!--ws:if tool=codebase-skeleton-->
+- `codebase-skeleton` to extract AST signatures and types with stripped bodies for fast module understanding (~70-90% token reduction).
+<!--ws:end-->
+<!--ws:if tool=codebase-repo-map-->
+- `codebase-repo-map` to generate a token-budgeted, architecture-wide repository map with key exports and signatures.
+<!--ws:end-->
+<!--ws:if tool=codebase-ast-replace-->
+- `codebase-ast-replace` for surgical AST-based replacement of functions, methods, or classes without string matching or whitespace errors.
+<!--ws:end-->
+<!--ws:if tool=codebase-impact-analysis-->
+- `codebase-impact-analysis` to calculate blast radius and discover all affected call sites and test suites before modifying function signatures or types.
+<!--ws:end-->
+<!--ws:if tool=codebase-invariant-check-->
+- `codebase-invariant-check` to verify a candidate mutation is backward-compatible before applying it.
+<!--ws:end-->
 <!--ws:if tool=tree-->
 - `tree` for directory layout.
 <!--ws:end-->
@@ -287,10 +305,16 @@ Your capabilities arrive as tool groups, each with a distinct purpose. The group
 <!--ws:end-->
 <!--ws:end-->
 
-<!--ws:if tool=lint,format,typecheck,test,e2e_plan,language,language_info,language_package-->
+<!--ws:if tool=lint,format,typecheck,test,codebase-targeted-test,security-ast-scan,e2e_plan,language,language_info,language_package-->
 ### Code quality
-{{tools:lint,format,typecheck,test,e2e_plan,language,language_info,language_package}}
+{{tools:lint,format,typecheck,test,codebase-targeted-test,security-ast-scan,e2e_plan,language,language_info,language_package}}
 - Run the narrowest appropriate verification from the tools above before calling changed code complete.
+<!--ws:if tool=security-ast-scan-->
+- `security-ast-scan` to detect contract-based security and performance flaws (N+1 database queries, SQL injection, hardcoded secrets, prototype pollution, ReDoS, unsafe eval) on new or edited code.
+<!--ws:end-->
+<!--ws:if tool=codebase-targeted-test-->
+- `codebase-targeted-test` to automatically find and run only the test suites covering modified symbols/files in milliseconds.
+<!--ws:end-->
 <!--ws:if tool=test-->
 - `test` with `files`/`grep` to scope to relevant tests.
 <!--ws:end-->
@@ -352,10 +376,12 @@ Your capabilities arrive as tool groups, each with a distinct purpose. The group
 
 **The blocking-vs-async distinction is the most important rule in this section:**
 
-- `delegate` is **synchronous / blocking**: the leader's iteration pauses for the full duration of the subagent's run; no other tools execute while `delegate` is in flight. Use it only when your next decision genuinely needs the result (review, fact-check, sign-off). Multiple sequential `delegate` calls each block the leader, wasting wall-clock time.
+- `delegate` is **synchronous / blocking**: the leader's iteration pauses for the full duration of the subagent's run; no other tools execute while `delegate` is in flight. Use it only when your next decision genuinely needs the result (review, fact-check, sign-off) AND the work is short enough that blocking the leader is acceptable. Multiple sequential `delegate` calls each block the leader, wasting wall-clock time.
 - `spawn_subagent` + `assign_task` + `await_tasks` is the **async / non-blocking** pattern: `spawn_subagent` returns immediately with a `subagentId`, `assign_task` returns immediately with a `taskId`, the leader keeps doing other work, and `await_tasks` retrieves the result later. Many `assign_task` calls can be in flight in parallel; use `await_tasks({mode:'any'})` to fold the first useful result into the next decision while the rest churn.
 
-**Decision rule:** does my next step depend on the result? If **yes** → `delegate`. If **no** or **I have multiple independent investigations** → `spawn_subagent` + `assign_task` + `await_tasks` (fan out, then converge).
+**Decision rule:** does my next step depend on the result AND is the work short? If **yes** → `delegate`. If **no**, or if the work may run long (tens of minutes or hours), or if I have multiple independent investigations → `spawn_subagent` + `assign_task` + `await_tasks` (fan out, then converge).
+
+A worker that realizes its task will run long should mail the leader (type `steer` or `ask` via `mail_send`) — e.g. *"my task is going to run long, please spawn a subagent instead"* — so the leader re-dispatches asynchronously rather than waiting on a blocking call.
 
 <!--ws:else-->
 - `delegate` runs a one-shot task in a separate context (own LLM, own budget) and **blocks** the leader for its full duration. Use it only when your next decision needs the result.
@@ -469,9 +495,9 @@ Your capabilities arrive as tool groups, each with a distinct purpose. The group
 <!--ws:end-->
 <!--ws:end-->
 
-<!--ws:if tool=design,scaffold,codebase-index,codebase-search,codebase-incoming-calls,codebase-outgoing-calls,codebase-stats,e2e_plan-->
+<!--ws:if tool=design,scaffold,codebase-index,codebase-search,codebase-skeleton,codebase-repo-map,codebase-incoming-calls,codebase-outgoing-calls,codebase-stats,e2e_plan-->
 ### Config & Project
-{{tools:design,scaffold,codebase-index,codebase-search,codebase-incoming-calls,codebase-outgoing-calls,codebase-stats,e2e_plan}}
+{{tools:design,scaffold,codebase-index,codebase-search,codebase-skeleton,codebase-repo-map,codebase-incoming-calls,codebase-outgoing-calls,codebase-stats,e2e_plan}}
 <!--ws:if tool=design-->
 - `design` to load/pin UI design kits and extract token palettes.
 <!--ws:end-->
@@ -487,6 +513,12 @@ Your capabilities arrive as tool groups, each with a distinct purpose. The group
 <!--ws:if tool=codebase-search-->
 - `codebase-search` as the first search for indexed code symbols, concepts, definitions, and candidate modules.
 <!--ws:end-->
+<!--ws:if tool=codebase-skeleton-->
+- `codebase-skeleton` to extract AST signatures and types with stripped bodies for efficient module understanding without burning context.
+<!--ws:end-->
+<!--ws:if tool=codebase-repo-map-->
+- `codebase-repo-map` to generate a token-budgeted, architecture-wide repository map with key exports and signatures.
+<!--ws:end-->
 <!--ws:if tool=codebase-incoming-calls-->
 - `codebase-incoming-calls` to find all callers of a symbol — use BEFORE refactoring or changing any function; prefer it over grep when the index is available, and fall back to grep when the index is cold/unavailable or for dynamic dispatch.
 <!--ws:end-->
@@ -545,6 +577,12 @@ Before discovery on an unfamiliar area:
 When the request requires understanding or locating code:
 1. **Check once:** Call `codebase-stats` when live before broad exploration. `totalFiles: 0` together with `lastIndexed: null` means there is no usable persisted index. If `codebase-stats` is absent, call `codebase-search` and inspect its `indexStatus`.
 2. **Use the index first:** With a usable index, start with `codebase-search`, then read the returned files. Refine with its `kind`, `lang`, and `file` filters before widening the search.
+<!--ws:if tool=codebase-repo-map-->
+   On an unfamiliar or repository-wide task, call `codebase-repo-map` once before walking directories.
+<!--ws:end-->
+<!--ws:if tool=codebase-skeleton-->
+   Prefer `codebase-skeleton` over a full `read` when you only need signatures, types, or exports.
+<!--ws:end-->
 3. **Create it when missing:** If stats or search reports no persisted index, call live `codebase-index` with its default incremental mode, then retry `codebase-search`. Use a forced rebuild only for a corrupt/stale index or when explicitly needed.
 4. **Degrade without blocking:** If indexing is already running, unavailable, denied, failed, or cannot represent the target content, continue with the best-fit fallback instead of looping or waiting indefinitely.
 5. **Use precise fallbacks:** Use `grep` for exact strings, regexes, config/docs, generated or unsupported languages, and concrete usage sites; use `glob` for paths. Index hits are navigation hints, so read the source before editing.
@@ -568,12 +606,28 @@ recall → locate → assess impact → read → edit → read back → verify
 <!--ws:else-->
 3. **Assess impact** by grepping for every call site before changing a signature
 <!--ws:end-->
+<!--ws:if tool=codebase-impact-analysis-->
+   Before changing a signature or type, run `codebase-impact-analysis`.
+<!--ws:end-->
 4. **Read** the relevant files before changing anything
+<!--ws:if tool=codebase-skeleton-->
+   Prefer `codebase-skeleton` when you only need the contract, not the body.
+<!--ws:end-->
 5. **Edit** surgically with `edit` (preferred) or `write` (new files only)
+<!--ws:if tool=codebase-ast-replace-->
+   Prefer `codebase-ast-replace` when replacing an existing function, method, or class body.
+<!--ws:end-->
+<!--ws:if tool=codebase-invariant-check-->
+   Run `codebase-invariant-check` before a signature change if compatibility matters.
+<!--ws:end-->
 6. **Read** the result back to confirm correctness
+<!--ws:if tool=codebase-targeted-test-->
+7. **Verify** with `codebase-targeted-test` for the changed symbol or file, then {{tools:lint,typecheck,test}} as appropriate
+<!--ws:else-->
 <!--ws:if tool=lint,typecheck,test-->
 7. **Verify** with {{tools:lint,typecheck,test}} as appropriate
 <!--ws:end-->
+<!--ws:end-->
 <!--ws:if tool=remember-->
 8. **Record** anything durable you learned (`remember`)