feat(discuss-phase): auto-generate DISCUSSION-LOG.md for audit trail (#1209)

- Generate {phase_num}-DISCUSSION-LOG.md alongside CONTEXT.md during
  discuss-phase sessions
- Log captures all options presented per gray area (not just the
  selected one), user's choice, notes, Claude's discretion items,
  and deferred ideas
- File is explicitly marked as audit-only — not for agent consumption
- Add discussion-log.md template with format specification
- Track Q&A data accumulation instruction in discuss_areas step
- Commit discussion log alongside CONTEXT.md in same git commit
- Add regression tests for workflow reference and template existence

get-shit-done/templates/discussion-log.md

@@ -0,0 +1,63 @@
+# Discussion Log Template
+
+Template for `.planning/phases/XX-name/{phase_num}-DISCUSSION-LOG.md` — audit trail of discuss-phase Q&A sessions.
+
+**Purpose:** Software audit trail for decision-making. Captures all options considered, not just the selected one. Separate from CONTEXT.md which is the implementation artifact consumed by downstream agents.
+
+**NOT for LLM consumption.** This file should never be referenced in `<files_to_read>` blocks or agent prompts.
+
+## Format
+
+```markdown
+# Phase [X]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+## [Area 1 Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Brief description] | |
+| [Option 2] | [Brief description] | ✓ |
+| [Option 3] | [Brief description] | |
+
+**User's choice:** [Selected option or verbatim free-text response]
+**Notes:** [Any clarifications or rationale provided during discussion]
+
+---
+
+## [Area 2 Name]
+
+...
+
+---
+
+## Claude's Discretion
+
+[Areas delegated to Claude's judgment — list what was deferred and why]
+
+## Deferred Ideas
+
+[Ideas mentioned but not in scope for this phase]
+
+---
+
+*Phase: XX-name*
+*Discussion log generated: [date]*
+```
+
+## Rules
+
+- Generated automatically at end of every discuss-phase session
+- Includes ALL options considered, not just the selected one
+- Includes user's freeform notes and clarifications
+- Clearly marked as audit-only, not an implementation artifact
+- Does NOT interfere with CONTEXT.md generation or downstream agent behavior
+- Committed alongside CONTEXT.md in the same git commit

get-shit-done/workflows/discuss-phase.md

@@ -603,11 +603,23 @@ Back to [current area]: [return to current question]"
 ```
 
 Track deferred ideas internally.
+
+**Track discussion log data internally:**
+For each question asked, accumulate:
+- Area name
+- All options presented (label + description)
+- Which option the user selected (or their free-text response)
+- Any follow-up notes or clarifications the user provided
+This data is used to generate DISCUSSION-LOG.md in the `write_context` step.
 </step>
 
 <step name="write_context">
 Create CONTEXT.md capturing decisions made.
 
+**Also generate DISCUSSION-LOG.md** — a full audit trail of the discuss-phase Q&A.
+This file is for human reference only (software audits, compliance reviews). It is NOT
+consumed by downstream agents (researcher, planner, executor).
+
 **Find or create phase directory:**
 
 Use values from init: `phase_dir`, `phase_slug`, `padded_phase`.
@@ -762,10 +774,54 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 </step>
 
 <step name="git_commit">
-Commit phase context (uses `commit_docs` from init internally):
+**Write DISCUSSION-LOG.md before committing:**
+
+**File location:** `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md`
+
+```markdown
+# Phase [X]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+[For each gray area discussed:]
+
+## [Area Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Description from AskUserQuestion] | |
+| [Option 2] | [Description] | ✓ |
+| [Option 3] | [Description] | |
+
+**User's choice:** [Selected option or free-text response]
+**Notes:** [Any clarifications, follow-up context, or rationale the user provided]
+
+---
+
+[Repeat for each area]
+
+## Claude's Discretion
+
+[List areas where user said "you decide" or deferred to Claude]
+
+## Deferred Ideas
+
+[Ideas mentioned during discussion that were noted for future phases]
+```
+
+Write file.
+
+Commit phase context and discussion log:
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
 ```
 
 Confirm: "Committed: docs(${padded_phase}): capture phase context"

tests/agent-frontmatter.test.cjs

@@ -181,3 +181,34 @@ describe('AGENT: required frontmatter fields', () => {
     });
   }
 });
+
+// ─── Discussion Log ──────────────────────────────────────────────────────────
+
+describe('DISCUSS: discussion log generation', () => {
+  test('discuss-phase workflow references DISCUSSION-LOG.md generation', () => {
+    const content = fs.readFileSync(
+      path.join(WORKFLOWS_DIR, 'discuss-phase.md'), 'utf-8'
+    );
+    assert.ok(
+      content.includes('DISCUSSION-LOG.md'),
+      'discuss-phase must reference DISCUSSION-LOG.md generation'
+    );
+    assert.ok(
+      content.includes('Audit trail only'),
+      'discuss-phase must mark discussion log as audit-only'
+    );
+  });
+
+  test('discussion-log template exists', () => {
+    const templatePath = path.join(__dirname, '..', 'get-shit-done', 'templates', 'discussion-log.md');
+    assert.ok(
+      fs.existsSync(templatePath),
+      'discussion-log.md template must exist'
+    );
+    const content = fs.readFileSync(templatePath, 'utf-8');
+    assert.ok(
+      content.includes('Do not use as input to planning'),
+      'template must contain audit-only notice'
+    );
+  });
+});