docs: propose further simplifications

packages/core/system-prompt/src/index.ts

@@ -99,6 +99,8 @@ export interface PromptSection {
 export interface AssembledSection {
   /** The contributing section's unique name. */
   name: string
+  // TODO(assembled-section-order): drop this output field; registry order has
+  // already sorted the array, and no production renderer/listener reads it.
   /** The contributing section's order (sections arrive sorted ascending). */
   order: number
   /** The resolved (but not yet interpolated) section text. */

packages/ui/acp-agent/src/index.ts

@@ -72,6 +72,8 @@ export const Config: z<Config> = z.object({
   // schemastery's native [] default would read as an invalid configured list.
   toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
   tools: ToolRegistry.Config,
+  // TODO(single-default-literal): share this schema default and the defensive
+  // apply() fallback through one named constant while retaining both boundaries.
   persistenceRoot: z.string().default('./.sessions'),
   skills: agentCore.SkillConfigSchema,
 })

packages/ui/acp/src/index.ts

@@ -362,6 +362,8 @@ export function apply(ctx: Context, config: AcpConfig): void {
   // this warn sink so a throwing tool presenter is logged, not propagated.
   const makePresenter = (agent?: Agent): ToolPresenter => new ToolPresenter(tools, (message) => { logger.warn(message) }, agent)
 
+  // TODO(derive-acp-session-id): derive an event's id from agent.session and
+  // verify sessions.get(id)?.agent === agent; then this reverse map disappears.
   // Live sessions keyed by id (RFC 011 multi-session), plus an agent→sessionId
   // reverse map so `agent/*` events (which carry only the Agent) demux in O(1).
   // The two stay in lockstep: a record is added to `sessions` and the agent to

packages/ui/stdio-agent/src/index.ts

@@ -93,6 +93,8 @@ export const Config: z<Config> = z.object({
   // schemastery's native [] default would read as an invalid configured list.
   toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
   tools: ToolRegistry.Config,
+  // TODO(single-default-literal): share these schema defaults and defensive
+  // apply() fallbacks through named constants while retaining both boundaries.
   persistenceRoot: z.string().default('./.sessions'),
   welcome: z.string().default('ready.'),
   skills: agentCore.SkillConfigSchema,

packages/ui/stdio-agent/src/stdio-chat.ts

@@ -36,6 +36,8 @@ export const inject = ['agents', 'userInteraction']
 export interface Config {
   /** Banner printed once on start, before the first `> ` prompt. */
   welcome?: string
+  // TODO(fixed-stdio-agent): this app-internal plugin is mounted only for the
+  // precreated `main` agent; remove configurability and its config-only test.
   /** Id of the agent stdin drives (`send`/`steer`) and whose status gates the EOF exit; rendering is global. Defaults to `'main'`. */
   agent?: string
 }