Fix log upload argument parsing bug (#1096)

[konard]

Summary

This PR fixes the log upload bug where `gh-upload-log` failed with the error:

```
Error: File does not exist: "/tmp/solution-draft-log-pr-1768003849690.txt" --public --verbose
```

The CLI flags were being incorrectly included as part of the filename argument.

Root Cause

When using `command-stream`'s `$` template tag, a single template interpolation (`${commandArgs.join(' ')}`) is treated as a single argument, regardless of internal spaces. This means the entire joined string becomes the first positional argument to `gh-upload-log`.

Upstream Issue Filed

📝 link-foundation/command-stream#153

We've reported this as a documentation improvement request to the `command-stream` library, including:

• Reproducible examples
• Workarounds
• Suggestions for detecting this pitfall

Changes

• Fix: Use separate `${}` interpolations for each argument instead of joining an array
• Fix: Include the `--description` flag in actual execution (was only displayed, never sent)
• Tests: Add comprehensive regression tests for issue Logs upload failed #1096
• Docs: Add case study documentation with timeline and root cause analysis

Before (Buggy)

```javascript
const commandArgs = ["${logFile}", publicFlag];
if (verbose) commandArgs.push('--verbose');
const uploadResult = await $`gh-upload-log ${commandArgs.join(' ')}`;
// Result: gh-upload-log receives entire string as ONE argument
```

After (Fixed)

```javascript
const uploadResult = await $`gh-upload-log ${logFile} ${publicFlag} --verbose`;
// Result: Each ${} is properly passed as a separate argument
```

Testing

All 28 tests pass, including the new integration test that verifies the fix:

```
📊 Test Summary: 28 passed, 0 failed
✅ All tests passed!
```

Fixes #1096

---

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $6.575455 USD
• Calculated by Anthropic: $4.794028 USD
• Difference: $-1.781427 (-27.09%)
  📎 Log file uploaded as GitHub Gist (692KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

Please make sure we report issue to https://github.com/link-foundation/command-stream

The issue must contain reproducible examples, workarounds and suggestions for fix the issue in code.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-01-10T21:38:58.833Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

Upstream Issue Created

As requested, I've created a documentation issue in the command-stream repository:

🔗 link-foundation/command-stream#153

Issue Contents

The issue includes:

1. Reproducible examples showing both the incorrect usage (${args.join(' ')}) and correct usage (${args})

2. Workarounds:

   • Pass arrays directly to template interpolation
   • Use separate interpolations for each argument
   • Use spread operator with array building

3. Suggestions for code improvements:

   • Documentation enhancement with "Common Pitfalls" section
   • Optional runtime warning when a string looks like it might be a pre-joined array
   • TypeScript/JSDoc hints to discourage .join() usage

Root Cause Analysis

The issue clarifies that this is not a bug in command-stream - the library already handles arrays correctly via:

if (Array.isArray(value)) {
  return value.map(quote).join(' ');  // Each element quoted separately
}

The problem is that calling .join(' ') converts the array to a string before passing it to the template, so command-stream sees a string (not an array) and quotes it as a single argument.

This is technically expected behavior, but the pitfall is subtle enough to warrant documentation.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $1.321052 USD
• Calculated by Anthropic: $0.911748 USD
• Difference: $-0.409303 (-30.98%)
  📎 Log file uploaded as GitHub Gist (191KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.