Merge remote-tracking branch 'origin/master' into worktree-dynamic-workflows

Beyond the mechanical conflicts (provider capability lines vs master's new
inheritsParentContext field; generated catalogs regenerated rather than
hand-merged; knip/lockfile), three master-side reworks required semantic
adaptation of this branch:

- The persona rework removed AgentOptions.systemPrompt, which was the
  structured-output instruction's channel. The instruction now rides the
  SAME final-request enforcement listener that injects the schema'd tool:
  appended per request to final.system (per-request wire state, not agent
  prompt state). Tests assert the wire request (adapter.requests) instead
  of child.options; the bare-direct-dispatch test pins the no-system arm.
- Tool guidance moved out of deployment prompts into per-tool prompt
  sections; the examples' workflow paragraph became a tool:<toolName>
  section contributed by dsh-tool-workflow (explicit-ask-only policy),
  and both example personas resolve to master's minimal identity+behavior
  form. tool-workflow gains inject: systemPrompt (+ peer dep, tsconfig
  ref); the export-shape guard updated.
- The uniform-RFC-format gate: the dynamic-workflows RFC restructured to
  the implemented/ skeleton (bare Status line; Proposal -> Decision;
  What-was-rejected -> Alternatives considered; new Consequences), and
  the overall-run-timeout deferral is now recorded in the RFC's Deferred
  list. The doc-graphs atlas classification gains the workflows seam
  (workflow-vm implementation, tool-workflow consumer).

Master's harness-identity section made "empty assembled prompt" states
unreachable through the loop, so the instruction-append is a plain
undefined-ternary and the structured tests assert append-not-replace.
All snapshot goldens (including workflow-run) replay unchanged. Full
local CI-equivalent gate sequence green on the merged tree.

packages/workflow/tool-workflow/README.md

@@ -4,7 +4,7 @@ The model-facing **`workflow` tool**: run a JavaScript orchestration script that
 
 ## What the model sees
 
-Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, determinism bans, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest).
+Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, determinism bans, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest). The plugin also contributes a `tool:<toolName>` system-prompt section carrying the usage policy — use the tool only on an explicit user ask for a workflow / large orchestration; prefer plain subagent calls for one or two delegations — per the convention that tool guidance ships with the tool plugin, never in the deployment persona.
 
 ## Lifecycle
 

packages/workflow/tool-workflow/package.json

@@ -24,6 +24,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-workflow": "^0.0.1",
     "cordis": "^4.0.0-rc.6"

packages/workflow/tool-workflow/src/index.ts

@@ -17,6 +17,10 @@
  * the args — presentation must be a pure function of `args`, so it cannot ask
  * the engine to parse.
  *
+ * Usage policy ships with the tool as a `tool:<toolName>` system-prompt
+ * section (explicit-ask-only guidance) — tool guidance lives in tool plugins,
+ * never in the deployment persona.
+ *
  * @module @deepseek-ai/dsh-tool-workflow
  */
 
@@ -26,9 +30,11 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { WorkflowResult, WorkflowRun } from '@deepseek-ai/dsh-workflow'
+// Declaration merge only: makes ctx.systemPrompt visible for the section registration.
+import type {} from '@deepseek-ai/dsh-system-prompt'
 
 export const name = 'tool-workflow'
-export const inject = ['tools', 'workflows']
+export const inject = ['tools', 'workflows', 'systemPrompt']
 
 /** Config: the model-facing tool name plus result rendering caps. */
 export interface Config {
@@ -115,8 +121,16 @@ function renderResult(run: WorkflowRun, result: WorkflowResult, maxChars: number
 
 export function apply(ctx: Context, config: Config): void {
   const maxResultChars = config.maxResultChars ?? 50_000
+  const toolName = config.toolName ?? 'workflow'
+  // Usage policy ships with the tool (the master convention: tool guidance
+  // lives in tool plugins as prompt sections, not in the deployment persona).
+  ctx.systemPrompt.section({
+    name: `tool:${toolName}`,
+    order: 115,
+    text: `Use the ${toolName} tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.`,
+  })
   ctx.tools.register(defineTool({
-    name: config.toolName ?? 'workflow',
+    name: toolName,
     description: DESCRIPTION,
     parameters: {
       script: {

packages/workflow/tool-workflow/tests/tool-workflow.spec.ts

@@ -217,7 +217,7 @@ describe('dsh-tool-workflow', () => {
   it('has the namespace-plugin export shape (no stray default)', () => {
     expect('default' in toolWorkflow).toBe(false)
     expect(toolWorkflow.name).toBe('tool-workflow')
-    expect(toolWorkflow.inject).toEqual(['tools', 'workflows'])
+    expect(toolWorkflow.inject).toEqual(['tools', 'workflows', 'systemPrompt'])
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(toolWorkflow) as Record<string, unknown>
     expect(unwrapped).toBe(toolWorkflow)

packages/workflow/tool-workflow/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../core/tools"
     },
+    {
+      "path": "../../core/system-prompt"
+    },
     {
       "path": "../workflow"
     }

packages/workflow/workflow-vm/tests/workflow-vm.spec.ts

@@ -31,6 +31,8 @@ interface ControlledRun {
  */
 class StubProvider implements SubagentProvider {
   readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true }
+  // Context contract: stub children start fresh, mirroring the spawn backend.
+  readonly inheritsParentContext = false
   readonly runs: ControlledRun[] = []
 
   constructor(
@@ -460,6 +462,7 @@ describe('dsh-workflow-vm', () => {
       const provider: SubagentProvider = {
         name: 'rejecting',
         capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
         start: () => ({
           id: AgentId('reject-child'),
           result: Promise.reject(new Error('backend exploded')),