docs: fold useful simplification RFCs from pr 74

packages/acp/src/index.ts

@@ -203,6 +203,10 @@ interface SessionRecord {
  * others are no-ops (settle-exactly-once).
  */
 export function apply(ctx: Context, config: AcpConfig): void {
+  // TODO(double-default): these literals duplicate the Config schema defaults
+  // (`agentName`/`agentVersion` `.default(...)` above). The Loader applies the
+  // schema before apply() runs, so the `??` only fires for direct-apply unit
+  // tests. Pick one home for the default to avoid drift.
   const agentName = config.agentName ?? 'deepseek-harness-acp'
   const agentVersion = config.agentVersion ?? '0.0.1'
 

packages/bash-local/src/run.ts

@@ -159,7 +159,11 @@ export class OutputCollector {
     writeSync(this.spillFd, chunk)
   }
 
-  /** Read the collected tail without finalizing (used by background polling). */
+  // TODO(snapshot-scope): `snapshot()` has one internal caller (`finalize()` at
+  // the bottom of this file) and `totalBytes` is read only by a test. The live
+  // background-poll path goes through `readFrom()`, so inline snapshot() into
+  // finalize() and drop or privatize the totalBytes getter.
+  /** Read the collected tail without finalizing (the final-result snapshot). */
   snapshot(): CollectedOutput {
     return {
       text: Buffer.concat(this.chunks).toString('utf8'),

packages/tools/src/schema.ts

@@ -39,7 +39,14 @@ export interface SchemaProp {
   description?: string
   /** Enum of allowed values (strings only). */
   enum?: string[]
-  /** Default value. */
+  /**
+   * Default value, emitted into the JSON Schema only (validation never applies
+   * it — see the validator note below).
+   *
+   * XXX(unused-default): no tool definition in the repo sets `default`; it rides
+   * into the wire schema for a model that no tool surfaces it to. Drop the field
+   * and its converter line unless a real tool needs a model-visible default.
+   */
   default?: unknown
   /** Nested properties for type: 'object'. */
   properties?: SchemaSpec