fix(ce-compound): write Phase 1 subagent output to run artifacts to survive summary-collapse (#984)

Author: tmchow

skills/ce-compound/SKILL.md

@@ -98,11 +98,13 @@ If the user says yes, run the internal session-history step in Phase 1 (see step
 <critical_requirement>
 **The primary deliverable is ONE file - the final documentation.**
 
-Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator writes files. Beyond the Phase 2 solution doc, its other writes are maintenance side effects — not additional deliverables, and creating one when absent is expected, not a violation of this rule:
+Phase 1 subagents write their full structured output to a per-run scratch artifact under `/tmp/compound-engineering/ce-compound/<run-id>/` and return only a compact confirmation containing the artifact path. The orchestrator Reads those artifacts back in Phase 2 assembly. This is scratch space, identical in spirit to `ce-code-review`'s per-reviewer run artifacts; it does not make the scratch files additional deliverables. **Only the orchestrator writes product files** — the final solution doc and the maintenance side effects below. Subagents must not touch `docs/`, project instruction files, or any tracked path. Beyond the Phase 2 solution doc, the orchestrator's other writes are maintenance side effects — not additional deliverables, and creating one when absent is expected, not a violation of this rule:
 - **`CONCEPTS.md`** — create or update in Phase 2.4 (Vocabulary Capture) when a qualifying domain term surfaces.
 - **A project instruction file** (AGENTS.md or CLAUDE.md) — a small edit when the Discoverability Check finds a gap.
 
 Both ensure future agents can discover and ground in the knowledge store; neither makes the documentation any less the single deliverable.
+
+**Why the scratch artifact (issue #956):** a subagent asked to return a long prose body as its inline response intermittently returns an executive summary instead ("Doc body complete — six sections filled. Returning above."), and the original prose is then unrecoverable from the orchestrator side. Writing to disk first means the full output always survives; the inline confirmation is just a pointer, and the orchestrator falls back to whatever the subagent did return inline only when the artifact is missing.
 </critical_requirement>
 
 ### Phase 0.5: Auto Memory Scan
@@ -128,7 +130,23 @@ If no relevant entries are found, proceed to Phase 1 without passing memory cont
 
 ### Phase 1: Research
 
-Launch research subagents. Each returns text data to the orchestrator.
+Launch research subagents. Each writes its full output to a per-run scratch artifact and returns only the artifact path to the orchestrator.
+
+**Run ID and run dir (before dispatching any subagent):** generate a unique run identifier and create the run directory. This scopes every Phase 1 artifact file to the same directory so the orchestrator can Read them back in Phase 2.
+
+```bash
+RUN_ID=$(date +%Y%m%d-%H%M%S)-$(head -c4 /dev/urandom | od -An -tx1 | tr -d ' ')
+mkdir -p "/tmp/compound-engineering/ce-compound/$RUN_ID"
+```
+
+Pass `{run_id}` (the resolved `$RUN_ID` value) into every Phase 1 subagent prompt. Each subagent **writes its full structured output** to its own file under `/tmp/compound-engineering/ce-compound/{run_id}/`, **confirms the write succeeded** (the file exists and is non-empty), and then **returns only a one-line confirmation containing the artifact path** — not the prose body inline. Artifact filenames by subagent:
+
+- **Context Analyzer** → `/tmp/compound-engineering/ce-compound/{run_id}/context.json` (frontmatter skeleton, category path, filename, track)
+- **Solution Extractor** → `/tmp/compound-engineering/ce-compound/{run_id}/solution.md` (the full doc-body prose sections)
+- **Related Docs Finder** → `/tmp/compound-engineering/ce-compound/{run_id}/related.json` (links, refresh candidates, overlap assessment)
+- **Session History** synthesis subagent (when run) → `/tmp/compound-engineering/ce-compound/{run_id}/session-history.md` (prose findings)
+
+**Return the full output inline whenever the artifact write did not succeed.** This covers both cases where the orchestrator's Phase 2 inline fallback would otherwise have nothing to read: (a) `{run_id}` is empty or did not resolve (non-Claude-Code platforms where the pre-resolution failed), so there is no path to write to; and (b) `{run_id}` resolved but the write itself failed — tool permission denied, absolute-path writes unavailable, disk error, or the post-write existence check came back empty. In either case the subagent must return its complete structured output inline instead of a path, because the path would point at a file that does not exist. Return only the bare path when — and only when — the write is confirmed on disk. The artifact pattern is a reliability improvement, not a hard requirement; the orchestrator handles a missing artifact in Phase 2 by using the inline return.
 
 **Dispatch order:**
 - Launch `Context Analyzer`, `Solution Extractor`, and `Related Docs Finder` in parallel (background)
@@ -146,13 +164,14 @@ Launch research subagents. Each returns text data to the orchestrator.
    - Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence
    - Reads `references/yaml-schema.md` for category mapping into `docs/solutions/`
    - Suggests a filename using the pattern `[sanitized-problem-slug].md` — no date suffix, even if existing files in the target directory have one; the `date:` frontmatter field is the canonical creation date
-   - Returns: YAML frontmatter skeleton (must include `category:` field mapped from problem_type), category directory path, suggested filename, and which track applies
+   - Writes to `context.json`: YAML frontmatter skeleton (must include `category:` field mapped from problem_type), category directory path, suggested filename, and which track applies. Returns only the artifact path.
    - Does not invent enum values, categories, or frontmatter fields from memory; reads the schema and mapping files above
    - Does not force bug-track fields onto knowledge-track learnings or vice versa
 
 #### 2. **Solution Extractor**
    - Reads `references/schema.yaml` for track classification (bug vs knowledge)
    - Adapts output structure based on the problem_type track
+   - **Writes the full doc-body prose** (all track-appropriate sections below) to `solution.md` and returns only the artifact path. This is the subagent most prone to the issue #956 summary-collapse, so its prose must land on disk rather than only in the inline return.
    - Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence -- conversation history and the verified fix take priority; if memory notes contradict the conversation, note the contradiction as cautionary context
 
    **Bug track output sections:**
@@ -181,7 +200,7 @@ Launch research subagents. Each returns text data to the orchestrator.
      - **High**: 4-5 dimensions match — essentially the same problem solved again
      - **Moderate**: 2-3 dimensions match — same area but different angle or solution
      - **Low**: 0-1 dimensions match — related but distinct
-   - Returns: Links, relationships, refresh candidates, and overlap assessment (score + which dimensions matched)
+   - Writes to `related.json`: Links, relationships, refresh candidates, and overlap assessment (score + which dimensions matched). Returns only the artifact path.
 
    **Search strategy (grep-first filtering for efficiency):**
 
@@ -265,7 +284,7 @@ Launch research subagents. Each returns text data to the orchestrator.
    - the output schema above
    - the filter rule above
 
-   The subagent reads only the scratch paths and returns prose findings. If synthesis fails, note the failure and continue without session context.
+   The subagent reads only the scratch paths, **writes its prose findings to `/tmp/compound-engineering/ce-compound/{run_id}/session-history.md`, and returns only that artifact path once the write is confirmed** (same #956 reliability rationale — session-history findings are long-form prose prone to summary-collapse). If `{run_id}` did not resolve or the artifact write failed, it returns the prose inline instead (per the inline-fallback rule above). If synthesis fails, note the failure and continue without session context.
 
 ### Phase 2: Assembly & Write
 
@@ -275,7 +294,7 @@ Launch research subagents. Each returns text data to the orchestrator.
 
 The orchestrating agent (main conversation) performs these steps:
 
-1. Collect all text results from Phase 1 subagents
+1. **Collect Phase 1 results from the run artifacts.** For each Phase 1 subagent, `Read` its artifact file under `/tmp/compound-engineering/ce-compound/{run_id}/` (`context.json`, `solution.md`, `related.json`, and `session-history.md` when session history ran). The artifact holds the subagent's full output. **Fall back to the subagent's inline return only when its artifact file is absent or empty** (e.g., `{run_id}` did not resolve, or the subagent failed to write). The artifact is authoritative when present — this is what makes the workflow resilient to the issue #956 summary-collapse, where the inline return is only an executive summary.
 2. **Check the overlap assessment** from the Related Docs Finder before deciding what to write:
 
    | Overlap | Action |
@@ -553,7 +572,8 @@ Knowledge track:
 
 | ❌ Wrong | ✅ Correct |
 |----------|-----------|
-| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
+| Subagents write product files into `docs/` or edit tracked paths | Subagents write only scratch artifacts under `/tmp/compound-engineering/ce-compound/<run-id>/` and return the path; orchestrator writes the one final doc |
+| Subagent returns a long prose body only as its inline response | Subagent writes full output to its run artifact; orchestrator Reads it back (inline return is fallback only) |
 | Research and assembly run in parallel | Research completes → then assembly runs |
 | Multiple files created during workflow | One solution doc written or updated: `docs/solutions/[category]/[filename].md` (plus optional maintenance writes: a `CONCEPTS.md` create/update from Phase 2.4 and a small instruction-file edit for discoverability) |
 | Creating a new doc when an existing doc covers the same problem | Check overlap assessment; update the existing doc when overlap is high |

tests/pipeline-review-contract.test.ts

@@ -688,6 +688,68 @@ describe("ce-compound frontmatter schema expansion contract", () => {
   })
 })
 
+describe("ce-compound Phase 1 artifact contract", () => {
+  // Regression guard for issue #956: Phase 1 subagents that returned long-form
+  // prose only as their inline Agent response failed silently when the harness
+  // collapsed the return to an executive summary. The fix mirrors ce-code-review's
+  // proven /tmp run-artifact pattern: subagents write full output to disk and the
+  // orchestrator Reads it back with the inline return as a fallback.
+  test("generates a run id and run dir before dispatching Phase 1 subagents", async () => {
+    const content = await readRepoFile("skills/ce-compound/SKILL.md")
+
+    // A run identifier scopes the per-subagent artifact files
+    expect(content).toContain("RUN_ID")
+    // Run dir under the shared cross-invocation scratch namespace
+    expect(content).toContain("/tmp/compound-engineering/ce-compound/")
+    expect(content).toContain('mkdir -p "/tmp/compound-engineering/ce-compound/')
+  })
+
+  test("Phase 1 subagents write full output to the run-artifact path", async () => {
+    const content = await readRepoFile("skills/ce-compound/SKILL.md")
+
+    const phase1 = content.slice(
+      content.indexOf("### Phase 1: Research"),
+      content.indexOf("### Phase 2: Assembly & Write"),
+    )
+
+    // Subagents are instructed to write their full structured output to the run dir
+    expect(phase1).toContain("/tmp/compound-engineering/ce-compound/")
+    // ...and return a compact confirmation containing the artifact path
+    expect(phase1.toLowerCase()).toContain("artifact path")
+    // Inline return is required whenever the write did not succeed (not only when
+    // {run_id} is missing) so Phase 2's fallback always has content to read.
+    expect(phase1.toLowerCase()).toContain("write did not succeed")
+    expect(phase1.toLowerCase()).toContain("the write itself failed")
+  })
+
+  test("Phase 2 assembly reads artifacts with inline-return fallback", async () => {
+    const content = await readRepoFile("skills/ce-compound/SKILL.md")
+
+    const phase2 = content.slice(
+      content.indexOf("### Phase 2: Assembly & Write"),
+      content.indexOf("### Phase 2.4: Vocabulary Capture"),
+    )
+
+    // Orchestrator reads the per-subagent artifact files
+    expect(phase2).toContain("/tmp/compound-engineering/ce-compound/")
+    // Inline return is the documented fallback when the artifact is absent
+    expect(phase2.toLowerCase()).toContain("fall back")
+  })
+
+  test("no longer imposes an absolute no-write rule on Phase 1 subagents", async () => {
+    const content = await readRepoFile("skills/ce-compound/SKILL.md")
+
+    // The brittle absolute prohibition is gone — only product-file writes are reserved
+    // to the orchestrator; scratch artifacts under /tmp are now expected.
+    expect(content).not.toContain(
+      "They must NOT use Write, Edit, or create any files.",
+    )
+    expect(content).not.toContain(
+      "Subagents return text data; orchestrator writes one final file",
+    )
+  })
+})
+
 describe("learnings-researcher local prompt domain-agnostic contract", () => {
   test("local prompt frames as domain-agnostic not bug-focused", async () => {
     const agent = await readRepoFile(