[plan] [#798] Add Response Header to acw TTY stdout

[were]

Implementation Plan: Add Response Header to acw TTY stdout

Consensus Summary

Add a Response: separator in the existing TTY-only stdout echo path for acw --chat --editor --stdout, keeping non-TTY output unchanged to avoid pipeline breakage. Update user-facing docs and the relevant test to codify the new header ordering, while keeping the change small and aligned with current --stdout semantics in docs/cli/acw.md.

Goal

Ensure acw --chat --editor --stdout visibly separates the echoed prompt from assistant output on TTY stdout by adding a Response: header.

Success criteria:

• --chat --editor --stdout on TTY prints User Prompt: then Response: before assistant output.
• Non-TTY stdout remains assistant-only to preserve current piping behavior.

Out of scope:

• Non-TTY transcript formatting or new --stdout format flags.
• However, it it a good idea for future work?
  • ✅ Good to have in the future: Add an explicit --stdout-format flag if users request machine-parseable transcripts or non-TTY framing.

Bug Reproduction

Skip reason (if reproduction not attempted):

• Feature request (not a bug); implementation is straightforward and validated via targeted tests.

Codebase Analysis

Files verified (docs/code checked by agents):

• docs/cli/acw.md: Current --stdout/--chat/--editor semantics and TTY echo behavior.
• src/cli/acw/dispatch.md: Stdout capture flow and TTY echo location.
• src/cli/acw/README.md: Module boundaries and dispatch.sh responsibility.
• src/cli/acw/dispatch.sh: TTY echo and stdout emission point.
• tests/cli/test-acw-flags.sh: Existing TTY stdout echo test harness using script.
• tests/cli/test-acw-flags.md: Test case documentation for TTY echo behavior.

File changes:

File	Level	Purpose
src/cli/acw/dispatch.sh	medium	Insert Response: header in TTY stdout echo path
src/cli/acw/dispatch.md	minor	Document Response: header in stdout capture section
docs/cli/acw.md	minor	Update --stdout notes to include Response: header
tests/cli/test-acw-flags.sh	minor	Assert Response: header ordering in TTY stdout test
tests/cli/test-acw-flags.md	minor	Document new Response: header expectation

Modification level definitions:

• minor: Cosmetic or trivial changes (comments, formatting, <10 LOC changed)
• medium: Moderate changes to existing logic (10-50 LOC, no interface changes)
• major: Significant structural changes (>50 LOC, interface changes, or new files)
• remove: File deletion

Current architecture notes:

• dispatch.sh emits TTY prompt echo and stdout capture for --chat --stdout, making it the correct single point for adding a Response: header.

Interface Design

New interfaces:

• None.

Modified interfaces:

• TTY stdout echo behavior for --chat --editor --stdout (documented in docs/cli/acw.md).

- With `--chat --editor`: when stdout is a TTY, the editor prompt is echoed to stdout before assistant output.
+ With `--chat --editor`: when stdout is a TTY, the editor prompt is echoed to stdout, followed by a `Response:` header before assistant output.

Documentation changes:

• docs/cli/acw.md: --stdout behavior notes (cite for interface accuracy).
• src/cli/acw/dispatch.md: stdout capture section.
• tests/cli/test-acw-flags.md: TTY echo expectations.

Documentation Planning

High-level design docs (docs/)

• docs/cli/acw.md — update --stdout notes to include Response: header in TTY echo.

- - With `--chat --editor`: when stdout is a TTY, the editor prompt is echoed to stdout before assistant output.
+ - With `--chat --editor`: when stdout is a TTY, the editor prompt is echoed to stdout, followed by a `Response:` header before assistant output.

Folder READMEs

• None.

Interface docs

• src/cli/acw/dispatch.md — update stdout capture description.

- If `--editor` is used and stdout is a TTY, the editor prompt
- is echoed to stdout before the assistant output.
+ If `--editor` is used and stdout is a TTY, the editor prompt
+ is echoed to stdout, followed by a `Response:` header before the assistant output.

• tests/cli/test-acw-flags.md — update TTY echo case expectations.

- **Expected**: Output includes `User Prompt:` and editor content before assistant output.
+ **Expected**: Output includes `User Prompt:` and editor content, then `Response:` before assistant output.

Citation requirement: Command interface references align with docs/cli/acw.md.

Test Strategy

Test modifications:

• tests/cli/test-acw-flags.sh
  • Test case: chat_editor_stdout_tty_echo asserts Response: appears after User Prompt: and before assistant output.
  • Test case: Ensure non-TTY output still excludes Response: (same as prompt echo rule).

New test files:

• None.

Test data required:

• Existing stub provider and script-based TTY runner are reused.

Implementation Steps

Step 1: Documentation updates (Estimated: 14 LOC)

• File changes:
  • docs/cli/acw.md
  • src/cli/acw/dispatch.md
  • tests/cli/test-acw-flags.md
    Dependencies: None
    Correspondence:
• Docs: Defines Response: header behavior for TTY stdout.
• Tests: Establishes expected header ordering in TTY path.

Step 2: Test updates (Estimated: 10 LOC)

• File changes:
  • tests/cli/test-acw-flags.sh
    Dependencies: Step 1
    Correspondence:
• Docs: Implements the Response: header expectation described in docs.
• Tests: Adds assertion that Response: appears after User Prompt: and before assistant output.

Step 3: Implementation update (Estimated: 8 LOC)

• File changes:
  • src/cli/acw/dispatch.sh
    Dependencies: Step 2
    Correspondence:
• Docs: Matches docs/cli/acw.md and dispatch.md behavior.
• Tests: Satisfies new Response: header assertions.

Implementation sketch (single insertion in TTY echo path):

 if [ "$use_editor" -eq 1 ] && [ -t 1 ]; then
     echo "User Prompt:"
     cat "$original_input_file"
     echo ""
+    echo "Response:"
 fi
 # Emit captured output to stdout
 cat "$chat_output_capture"

Total estimated complexity: 32 LOC (Low)
Recommended approach: Single session

Success Criteria

• TTY stdout includes User Prompt: and Response: before assistant output.
• Non-TTY stdout remains assistant-only (no prompt or response headers).
• Documentation and tests reflect the new header behavior.

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Users expect Response: in non-TTY --stdout	M	M	Document TTY-only behavior and note future --stdout-format option.
Header ordering ambiguity in TTY output	L	M	Add explicit test assertions for User Prompt: then Response: ordering.

Dependencies

No external dependencies.

Dude, carefully read my response to determine what to do next.