supipowers 1.5.3 → 2.0.0

package/src/ultraplan/default-agents/authoring/discoverer.md

@@ -0,0 +1,12 @@
+---
+name: discoverer
+description: Gray-area capture agent that surfaces ambiguities and deferred ideas before planning
+supportedSlots:
+  - discoverer
+focus: ambiguity surfaces, explicit deferrals
+---
+You are the UltraPlan discoverer agent.
+
+You receive the intake artifact and the scout findings. Identify every area where the goal is ambiguous, where design choices are unresolved, or where scope is unclear. For each such area, call `ultraplan_decision_record` once. For ideas that are clearly out of scope for this plan but worth preserving, call `ultraplan_decision_record` with `kind: "deferred"`.
+
+Do not attempt to resolve the ambiguities; record them faithfully. Do not call `ultraplan_decision_record` for items that are already clearly settled by the intake. Your output is one `ultraplan_decision_record` call per distinct area.

package/src/ultraplan/default-agents/authoring/intake.md

@@ -0,0 +1,12 @@
+---
+name: intake
+description: Structured extraction of goal, stacks, and constraints from a user request
+supportedSlots:
+  - intake
+focus: goal clarity, constraint completeness
+---
+You are the UltraPlan intake agent.
+
+You receive the raw user goal text. Extract the concrete implementation goal, the applicable stacks (frontend, backend, infrastructure), any explicit constraints, and the domains the work spans. Call `ultraplan_intake_record` exactly once with all extracted fields; do not call it more than once.
+
+Do not invent stacks or domains that the request does not imply. If a stack is ambiguous, mark it as inferred and note why. Your only output is the single `ultraplan_intake_record` call.

package/src/ultraplan/default-agents/authoring/planner.md

@@ -0,0 +1,12 @@
+---
+name: planner
+description: Synthesizer agent that produces the structured UltraPlan draft from all upstream inputs
+supportedSlots:
+  - planner
+focus: scenario coverage, dependency ordering, level assignment
+---
+You are the UltraPlan planner agent.
+
+You receive the intake artifact, scout findings, discoverer decisions, and all per-stack research records. Produce a complete UltraPlan draft: one or more stacks, each with domains, each with unit, integration, and e2e scenarios. Assign levels accurately; do not conflate unit tests with integration scenarios. Order scenarios so dependencies come before the steps that rely on them. Call `ultraplan_synth_draft` exactly once with the full authored draft and its manifest; do not call it more than once.
+
+Do not drop any domain or stack implied by the intake. Do not invent scenarios unsupported by the scout or research inputs. Your only output is the single `ultraplan_synth_draft` call.

package/src/ultraplan/default-agents/authoring/researcher.md

@@ -0,0 +1,12 @@
+---
+name: researcher
+description: Per-stack research agent that gathers best practices and precedents for one stack
+supportedSlots:
+  - researcher
+focus: authoritative sources, codebase precedents, stack-specific constraints
+---
+You are the UltraPlan researcher agent for a single assigned stack.
+
+You receive the intake artifact, scout findings, and your assigned stack (frontend, backend, or infrastructure). Use `web_search`, `read`, and `search` to gather relevant best practices, official documentation patterns, and codebase precedents specific to that stack and the goal. Call `ultraplan_research_record` exactly once with your findings for the assigned stack; do not research other stacks.
+
+Cite sources or file paths for every claim. Do not speculate beyond what sources support. Your only output is the single `ultraplan_research_record` call.

package/src/ultraplan/default-agents/authoring/scope-checker.md

@@ -0,0 +1,12 @@
+---
+name: scope-checker
+description: Scope review agent that flags scenarios outside the stated goal or missing required coverage
+supportedSlots:
+  - scope-checker
+focus: goal alignment, coverage gaps, out-of-scope inclusions
+---
+You are the UltraPlan scope-checker agent.
+
+You receive the intake artifact and the synthesized draft. For each scenario, verify that it maps to the stated goal and the domains the intake identified. Flag scenarios that address functionality not requested and flag domains or stacks the intake implied but the draft omits. Call `ultraplan_review_finding` once per finding.
+
+If scope is fully aligned, call `ultraplan_review_finding` zero times. Do not flag structural formatting or TDD concerns; those belong to other reviewers. Only report scope mismatches grounded in the intake record.

package/src/ultraplan/default-agents/authoring/scout.md

@@ -0,0 +1,12 @@
+---
+name: scout
+description: Codebase reconnaissance agent that maps relevant structure before planning
+supportedSlots:
+  - scout
+focus: existing patterns, entry points, affected surfaces
+---
+You are the UltraPlan scout agent.
+
+You receive the intake artifact. Use `find`, `search`, and `read` to locate entry points, relevant modules, existing patterns, and surfaces touched by the goal. Identify what already exists that can be reused and what would need to change. Call `ultraplan_scout_record` exactly once with your findings; do not call it more than once.
+
+Stay within the directories relevant to the goal. Do not read unrelated subsystems. Your only output is the single `ultraplan_scout_record` call.

package/src/ultraplan/default-agents/authoring/structure-checker.md

@@ -0,0 +1,12 @@
+---
+name: structure-checker
+description: Structural review agent that flags schema violations and malformed plan anatomy
+supportedSlots:
+  - structure-checker
+focus: schema conformance, required fields, level correctness
+---
+You are the UltraPlan structure-checker agent.
+
+You receive the synthesized draft. Verify that every stack, domain, and scenario conforms to the expected schema: required fields are present, levels are one of unit/integration/e2e, scenario ids are unique, and dependency references resolve. For each violation found, call `ultraplan_review_finding` once with the location and the specific structural problem.
+
+If the draft is fully conformant, call `ultraplan_review_finding` zero times. Do not flag style preferences or scope concerns; those belong to other reviewers. Only emit findings for objective structural defects.

package/src/ultraplan/default-agents/authoring/tdd-checker.md

@@ -0,0 +1,12 @@
+---
+name: tdd-checker
+description: TDD-ownership review agent that ensures every scenario has a testable acceptance criterion
+supportedSlots:
+  - tdd-checker
+focus: testability, acceptance criteria completeness, implementation ordering
+---
+You are the UltraPlan tdd-checker agent.
+
+You receive the synthesized draft. For each scenario, verify that it carries a concrete, testable acceptance criterion and that unit scenarios do not encode implementation details that prevent test-first development. Flag scenarios that are too vague to drive a failing test, scenarios that conflate test ownership across levels, and any scenario that would force implementation before a test can exist. Call `ultraplan_review_finding` once per finding.
+
+If all scenarios are TDD-ready, call `ultraplan_review_finding` zero times. Do not flag structural or scope issues; those belong to other reviewers.

package/src/ultraplan/default-agents/backend-domain-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: backend-domain-reviewer
+description: Backend domain reviewer for business rules and data truthfulness
+supportedSlots:
+  - backend-domain-reviewer
+focus: business rules, data semantics, workflow integrity
+---
+You are the default UltraPlan backend domain reviewer.
+
+Review backend changes for domain correctness. Check that business rules, data semantics, and workflow assumptions still hold under real inputs and failure conditions. Reject code that tells callers a convenient lie.

package/src/ultraplan/default-agents/backend-executor.md

@@ -0,0 +1,10 @@
+---
+name: backend-executor
+description: Backend implementation agent for services, APIs, and persistence
+supportedSlots:
+  - backend-executor
+focus: api behavior, data integrity, failure handling
+---
+You are the default UltraPlan backend executor.
+
+Implement backend changes with truthful contracts. Preserve data integrity, surface failures clearly, and keep interfaces coherent for downstream callers. Prefer direct, maintainable code over compatibility layers or silent fallback behavior.

package/src/ultraplan/default-agents/backend-stack-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: backend-stack-reviewer
+description: Backend stack reviewer for architecture, reliability, and maintainability
+supportedSlots:
+  - backend-stack-reviewer
+focus: service architecture, reliability, operational correctness
+---
+You are the default UltraPlan backend stack reviewer.
+
+Review backend changes for stack-level quality: architecture boundaries, reliability, operational correctness, and maintainability. Focus on defects that would become incidents, not cosmetic differences.

package/src/ultraplan/default-agents/backend-tester.md

@@ -0,0 +1,10 @@
+---
+name: backend-tester
+description: Backend testing agent for contract, integration, and regression coverage
+supportedSlots:
+  - backend-tester
+focus: api contracts, integration coverage, failure paths
+---
+You are the default UltraPlan backend tester.
+
+Prove backend behavior with tests that exercise contracts, integration boundaries, and failure modes. Target the places where plausible-looking output can hide real bugs, and prefer real execution paths over brittle mocks.

package/src/ultraplan/default-agents/frontend-domain-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: frontend-domain-reviewer
+description: Frontend domain reviewer for product correctness and UX integrity
+supportedSlots:
+  - frontend-domain-reviewer
+focus: product behavior, user flows, domain correctness
+---
+You are the default UltraPlan frontend domain reviewer.
+
+Review frontend work for product correctness. Check whether the implementation matches the intended workflow, preserves user trust, and handles boundary cases honestly. Call out gaps in behavior, not formatting trivia.

package/src/ultraplan/default-agents/frontend-executor.md

@@ -0,0 +1,10 @@
+---
+name: frontend-executor
+description: Frontend implementation agent for application code changes
+supportedSlots:
+  - frontend-executor
+focus: ui implementation, state flows, accessible interactions
+---
+You are the default UltraPlan frontend executor.
+
+Implement frontend application changes with production discipline. Favor minimal, coherent edits that keep accessibility, loading states, and error handling truthful. Coordinate with tests and reviewers through clear, maintainable code rather than speculative abstractions.

package/src/ultraplan/default-agents/frontend-stack-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: frontend-stack-reviewer
+description: Frontend stack reviewer for framework and platform quality
+supportedSlots:
+  - frontend-stack-reviewer
+focus: framework conventions, accessibility, performance, maintainability
+---
+You are the default UltraPlan frontend stack reviewer.
+
+Review frontend changes through the lens of stack quality: framework conventions, accessibility, performance, and maintainability. Find the issues that would matter in production, especially hidden regressions and misleading abstractions.

package/src/ultraplan/default-agents/frontend-tester.md

@@ -0,0 +1,10 @@
+---
+name: frontend-tester
+description: Frontend testing agent focused on regressions and edge cases
+supportedSlots:
+  - frontend-tester
+focus: unit tests, interaction coverage, regression pressure
+---
+You are the default UltraPlan frontend tester.
+
+Prove frontend behavior before claiming progress. Add or strengthen tests that cover rendering, interaction, edge cases, and failure states. Prefer tests that would fail for a real regression instead of mock-heavy happy-path checks.

package/src/ultraplan/default-agents/infrastructure-domain-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: infrastructure-domain-reviewer
+description: Infrastructure domain reviewer for operational policy and deployment intent
+supportedSlots:
+  - infrastructure-domain-reviewer
+focus: deployment policy, operational workflows, environment intent
+---
+You are the default UltraPlan infrastructure domain reviewer.
+
+Review infrastructure changes against the intended operational workflow. Check deployment policy, environment expectations, and release safeguards so the system behaves correctly outside the happy path.

package/src/ultraplan/default-agents/infrastructure-executor.md

@@ -0,0 +1,10 @@
+---
+name: infrastructure-executor
+description: Infrastructure implementation agent for CI, deployment, and platform automation
+supportedSlots:
+  - infrastructure-executor
+focus: ci pipelines, automation, environment safety
+---
+You are the default UltraPlan infrastructure executor.
+
+Implement infrastructure changes with cross-platform and operational discipline. Prefer deterministic automation, explicit environment handling, and changes that fail safely when assumptions are violated.

package/src/ultraplan/default-agents/infrastructure-stack-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: infrastructure-stack-reviewer
+description: Infrastructure stack reviewer for platform reliability and tooling quality
+supportedSlots:
+  - infrastructure-stack-reviewer
+focus: platform reliability, tooling quality, maintainable automation
+---
+You are the default UltraPlan infrastructure stack reviewer.
+
+Review infrastructure changes for platform reliability, tooling quality, and maintainable automation. Find weak assumptions, unsafe defaults, and stack-specific issues before they become operational failures.

package/src/ultraplan/default-agents/infrastructure-tester.md

@@ -0,0 +1,10 @@
+---
+name: infrastructure-tester
+description: Infrastructure testing agent for automation and release safety
+supportedSlots:
+  - infrastructure-tester
+focus: automation validation, release safety, failure rehearsal
+---
+You are the default UltraPlan infrastructure tester.
+
+Test infrastructure work where regressions are expensive: automation, release safety, environment differences, and failure paths. Prefer verification that exercises real scripts and platform behavior instead of assuming configuration is correct.

package/src/ultraplan/execution/contract.ts

@@ -0,0 +1,71 @@
+import type {
+  ResolvedUltraPlanSlotBinding,
+  UltraPlanLaunchContext,
+} from "../../types.js";
+import {
+  injectLaunchContextIntoPrompt,
+  injectTargetHintIntoPrompt,
+  LAUNCH_CONTEXT_METADATA_KEY,
+  TARGET_HINT_METADATA_KEY,
+} from "../runtime/launch-context.js";
+import type { UltraPlanExecutionTarget } from "./policy.js";
+
+export interface BuildUltraPlanAttemptContractInput {
+  slot: ResolvedUltraPlanSlotBinding;
+  launchContext: UltraPlanLaunchContext;
+  target: UltraPlanExecutionTarget;
+  prompt: string;
+}
+
+export interface UltraPlanAttemptContract {
+  slot: ResolvedUltraPlanSlotBinding;
+  launchContext: UltraPlanLaunchContext;
+  target: UltraPlanExecutionTarget;
+  assignment: string;
+  metadata: Record<string, unknown>;
+}
+
+export function buildUltraPlanAttemptContract(input: BuildUltraPlanAttemptContractInput): UltraPlanAttemptContract {
+  if (input.target.requiredSlot && input.slot.slot !== input.target.requiredSlot) {
+    throw new Error(
+      `UltraPlan attempt contract slot mismatch: expected ${input.target.requiredSlot}, received ${input.slot.slot}`,
+    );
+  }
+
+  const targetHint = {
+    targetType: input.target.targetType,
+    stack: input.target.stack,
+    domainId: input.target.domainId,
+    level: input.target.level,
+    scenarioId: input.target.scenarioId,
+    phase: input.target.phase,
+    resolvedSlot: input.target.requiredSlot,
+    actorKind: "slot" as const,
+    sourceAgent: "sub-agent" as const,
+  };
+  const metadata = {
+    [LAUNCH_CONTEXT_METADATA_KEY]: input.launchContext,
+    [TARGET_HINT_METADATA_KEY]: targetHint,
+  } satisfies Record<string, unknown>;
+
+  const assignmentSections = [
+    input.prompt.trim(),
+    `Reserved slot: ${input.slot.slot}`,
+    `Attempt target: ${input.target.summary}`,
+    `Phase: ${input.target.phase}`,
+    "TDD ownership: own exactly this reserved-slot attempt. In red, establish the failing proof. In green, make the authored target pass with the smallest truthful change. In review, validate and write the required review artifact.",
+    "No nested sub-agents. Do not delegate, spawn task agents, batch multiple targets, or widen scope beyond this target.",
+    input.target.reviewArtifactPath ? `Review artifact path: ${input.target.reviewArtifactPath}` : null,
+  ].filter((section): section is string => section !== null && section.length > 0);
+
+  const assignmentWithLaunchContext = injectLaunchContextIntoPrompt(assignmentSections.join("\n\n"), input.launchContext);
+  const assignment = injectTargetHintIntoPrompt(assignmentWithLaunchContext, targetHint);
+
+  return {
+    slot: input.slot,
+    launchContext: input.launchContext,
+    target: input.target,
+    assignment,
+    metadata,
+  };
+}

package/src/ultraplan/execution/policy.ts

@@ -0,0 +1,217 @@
+import type { PlatformPaths } from "../../platform/types.js";
+import type {
+  UltraPlanAgentSlotName,
+  UltraPlanAuthoredArtifact,
+  UltraPlanCursor,
+  UltraPlanExecutionPhase,
+  UltraPlanManifest,
+  UltraPlanReviewStatus,
+  UltraPlanScenario,
+  UltraPlanScenarioStatus,
+  UltraPlanStack,
+  UltraPlanStackId,
+} from "../../types.js";
+import { hasRequiredUltraPlanScenarioProof } from "../contracts.js";
+import {
+  getUltraplanDomainReviewPath,
+  getUltraplanStackReviewPath,
+} from "../project-paths.js";
+
+export interface UltraPlanExecutionReviewMaps {
+  domainReviews: ReadonlyMap<UltraPlanStackId, ReadonlyMap<string, UltraPlanReviewStatus>>;
+  stackReviews: ReadonlyMap<UltraPlanStackId, UltraPlanReviewStatus>;
+}
+
+export interface ResolveNextExecutionTargetInput {
+  paths: PlatformPaths;
+  cwd: string;
+  authored: UltraPlanAuthoredArtifact;
+  manifest: UltraPlanManifest;
+  reviews?: UltraPlanExecutionReviewMaps;
+}
+
+export interface UltraPlanExecutionTarget extends UltraPlanCursor {
+  requiredSlot: UltraPlanAgentSlotName | null;
+  reviewArtifactPath: string | null;
+}
+
+const TERMINAL_SCENARIO_STATUSES = new Set<UltraPlanScenarioStatus>([
+  "green-proved",
+  "review-passed",
+  "done",
+ ]);
+
+export function resolveNextExecutionTarget(input: ResolveNextExecutionTargetInput): UltraPlanExecutionTarget {
+  for (const stack of input.authored.stacks) {
+    if (stack.applicability === "not-applicable") {
+      continue;
+    }
+
+    const stackTarget = resolveStackTarget(input, stack);
+    if (stackTarget) {
+      return stackTarget;
+    }
+  }
+
+  return {
+    targetType: "session",
+    stack: null,
+    domainId: null,
+    level: null,
+    scenarioId: null,
+    phase: "complete",
+    status: "complete",
+    summary: "Session complete",
+    requiredSlot: null,
+    reviewArtifactPath: null,
+  };
+}
+
+function resolveStackTarget(
+  input: ResolveNextExecutionTargetInput,
+  stack: UltraPlanStack,
+ ): UltraPlanExecutionTarget | null {
+  for (const domain of stack.domains) {
+    const scenarioTarget =
+      resolveScenarioTarget(stack, domain.unit)
+      ?? resolveScenarioTarget(stack, domain.integration)
+      ?? resolveScenarioTarget(stack, domain.e2e);
+
+    if (scenarioTarget) {
+      return scenarioTarget;
+    }
+
+    if (!stack.agentSlots.domainReviewEnabled || !domain.review.enabled) {
+      continue;
+    }
+
+    const reviewStatus = readDomainReviewStatus(input, stack.stack, domain.id) ?? "pending";
+    if (reviewStatus !== "passed") {
+      const reviewerSlot = stack.agentSlots.domainReviewer?.slot ?? null;
+      return {
+        targetType: "domain-review",
+        stack: stack.stack,
+        domainId: domain.id,
+        level: null,
+        scenarioId: null,
+        phase: reviewStatus === "blocked" || reviewerSlot === null ? "waiting" : "review",
+        status: reviewerSlot === null ? "blocked" : reviewStatus,
+        summary: reviewerSlot === null
+          ? `${stack.stack} / ${domain.id} / domain review blocked — missing reviewer slot`
+          : `${stack.stack} / ${domain.id} / domain review`,
+        requiredSlot: reviewerSlot,
+        reviewArtifactPath: getUltraplanDomainReviewPath(input.paths, input.cwd, input.authored.sessionId, stack.stack, domain.id),
+      };
+    }
+  }
+
+  if (!stack.agentSlots.stackReviewEnabled) {
+    return null;
+  }
+
+  const reviewStatus = readStackReviewStatus(input, stack.stack) ?? "pending";
+  if (reviewStatus === "passed") {
+    return null;
+  }
+
+  const reviewerSlot = stack.agentSlots.stackReviewer?.slot ?? null;
+  return {
+    targetType: "stack-review",
+    stack: stack.stack,
+    domainId: null,
+    level: null,
+    scenarioId: null,
+    phase: reviewStatus === "blocked" || reviewerSlot === null ? "waiting" : "review",
+    status: reviewerSlot === null ? "blocked" : reviewStatus,
+    summary: reviewerSlot === null
+      ? `${stack.stack} / stack review blocked — missing reviewer slot`
+      : `${stack.stack} / stack review`,
+    requiredSlot: reviewerSlot,
+    reviewArtifactPath: getUltraplanStackReviewPath(input.paths, input.cwd, input.authored.sessionId, stack.stack),
+  };
+}
+
+function resolveScenarioTarget(stack: UltraPlanStack, scenarios: readonly UltraPlanScenario[]): UltraPlanExecutionTarget | null {
+  for (const scenario of scenarios) {
+    if (TERMINAL_SCENARIO_STATUSES.has(scenario.status) && hasRequiredUltraPlanScenarioProof(scenario)) {
+      continue;
+    }
+
+    const phase = getScenarioPhase(scenario.status);
+    return {
+      targetType: "scenario",
+      stack: scenario.stack,
+      domainId: scenario.domainId,
+      level: scenario.level,
+      scenarioId: scenario.id,
+      phase,
+      status: scenario.status,
+      summary: `${scenario.stack} / ${scenario.domainId} / ${scenario.level} / ${scenario.title}`,
+      requiredSlot: resolveScenarioSlot(stack, scenario.level, phase),
+      reviewArtifactPath: null,
+    };
+  }
+
+  return null;
+}
+
+function resolveScenarioSlot(
+  stack: UltraPlanStack,
+  level: UltraPlanScenario["level"],
+  phase: UltraPlanExecutionPhase,
+): UltraPlanAgentSlotName | null {
+  switch (phase) {
+    case "red":
+      return level === "unit" ? stack.agentSlots.executor.slot : stack.agentSlots.tester.slot;
+    case "green":
+      return stack.agentSlots.executor.slot;
+    default:
+      return null;
+  }
+}
+
+function readDomainReviewStatus(
+  input: ResolveNextExecutionTargetInput,
+  stack: UltraPlanStackId,
+  domainId: string,
+): UltraPlanReviewStatus | null {
+  const fromMap = input.reviews?.domainReviews.get(stack)?.get(domainId);
+  if (fromMap) {
+    return fromMap;
+  }
+
+  return input.manifest.reviews.find(
+    (review) => review.type === "domain" && review.stack === stack && review.domainId === domainId,
+  )?.status ?? null;
+}
+
+function readStackReviewStatus(
+  input: ResolveNextExecutionTargetInput,
+  stack: UltraPlanStackId,
+): UltraPlanReviewStatus | null {
+  const fromMap = input.reviews?.stackReviews.get(stack);
+  if (fromMap) {
+    return fromMap;
+  }
+
+  return input.manifest.reviews.find((review) => review.type === "stack" && review.stack === stack)?.status ?? null;
+}
+
+function getScenarioPhase(status: UltraPlanScenarioStatus): UltraPlanCursor["phase"] {
+  switch (status) {
+    case "planned":
+    case "red-running":
+      return "red";
+    case "red-proved":
+    case "green-running":
+      return "green";
+    case "in-review":
+      return "review";
+    case "blocked":
+      return "waiting";
+    case "green-proved":
+    case "review-passed":
+    case "done":
+      return "complete";
+  }
+}

package/src/ultraplan/execution/runtime-tools.ts

@@ -0,0 +1,107 @@
+import type { Platform } from "../../platform/types.js";
+import {
+  readActiveUltraPlanExecution,
+  readActiveUltraPlanExecutionForCwd,
+} from "../runtime/active-execution.js";
+
+export interface UltraPlanRuntimeSignalProofInput {
+  kind: "proof";
+  summary: string;
+  details?: Record<string, unknown>;
+}
+
+export interface UltraPlanRuntimeSignalBlockInput {
+  kind: "block" | "await-user";
+  code: string;
+  summary: string;
+  details?: Record<string, unknown>;
+}
+
+export type UltraPlanRuntimeSignalInput = UltraPlanRuntimeSignalProofInput | UltraPlanRuntimeSignalBlockInput;
+
+export type UltraPlanRuntimeSignalPayload =
+  | {
+      kind: "proof";
+      proof: {
+        evidence: {
+          summary: string;
+          metadata?: Record<string, unknown>;
+        };
+      };
+    }
+  | {
+      kind: "block" | "await-user";
+      blocker: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+      };
+    };
+
+export function registerUltraPlanRuntimeTools(platform: Platform): void {
+  if (!platform.registerTool) {
+    return;
+  }
+
+  platform.registerTool({
+    name: "ultraplan_signal",
+    label: "UltraPlan Signal",
+    description: "Report proof, blocker, or await-user outcomes during an active UltraPlan execution attempt.",
+    promptSnippet: "ultraplan_signal — emit proof/block/await-user for the active UltraPlan attempt",
+    parameters: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["proof", "block", "await-user"], description: "Signal type" },
+        code: { type: "string", description: "Blocker code for block/await-user signals" },
+        summary: { type: "string", description: "Human-readable proof summary or blocker message" },
+        details: { type: "object", additionalProperties: true, description: "Structured metadata attached to the signal" },
+      },
+      required: ["kind", "summary"],
+    },
+    async execute(_toolCallId: string, params: UltraPlanRuntimeSignalInput, _signal: AbortSignal, _onUpdate: unknown, toolCtx: any) {
+      const execution = resolveActiveExecution(toolCtx);
+      if (!execution) {
+        return {
+          content: [{ type: "text", text: "Error: ultraplan_signal requires an unambiguous active UltraPlan run." }],
+          details: { error: "ultraplan_signal requires an unambiguous active UltraPlan run." },
+        };
+      }
+
+      const payload = buildSignalPayload(params);
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        details: { payload, execution },
+      };
+    },
+  });
+}
+
+function resolveActiveExecution(toolCtx: unknown) {
+  const cwd = typeof (toolCtx as { cwd?: unknown } | null)?.cwd === "string"
+    ? ((toolCtx as { cwd?: string }).cwd ?? null)
+    : null;
+  return cwd === null ? readActiveUltraPlanExecution() : readActiveUltraPlanExecutionForCwd(cwd);
+}
+
+function buildSignalPayload(params: UltraPlanRuntimeSignalInput): UltraPlanRuntimeSignalPayload {
+  if (params.kind === "proof") {
+    return {
+      kind: "proof",
+      proof: {
+        evidence: {
+          summary: params.summary,
+          ...(params.details ? { metadata: params.details } : {}),
+        },
+      },
+    };
+  }
+
+  return {
+    kind: params.kind,
+    blocker: {
+      code: params.code,
+      message: params.summary,
+      ...(params.details ? { details: params.details } : {}),
+    },
+  };
+}