fix(gh-aw): publish research only on explicit request (#2194)

Remove bootstrap research seeding and recovery requirements while preserving Cast provenance and proposal creation. Require research before triage in launch guidance and cover compiled retries, comment preservation, and no-seed mutation detection.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a0288984-b7ca-479f-991d-ab5aaa8ede61

Author: bradygaster

.changeset/fix-bootstrap-triage-continuity.md

@@ -3,6 +3,6 @@
 "@bradygaster/squad-sdk": patch
 ---
 
-Make automatic bootstrap proposals immediately available to `/squad triage`
-after the linked Cast PR merges, and recognize the deterministic bootstrap Cast
-branch during team-required command gating.
+Keep automatic bootstrap limited to the Cast PR and linked proposals issue;
+publish research only on explicit `/squad research` before triage. Recognize
+the deterministic bootstrap Cast branch during team-required command gating.

docs/src/content/docs/guide/gh-aw.md

@@ -290,7 +290,7 @@ missing, duplicate, open, foreign, or merged archived PRs fail closed. Closed
 fallback issues may be included in `archived_issues`; unrelated issues cannot.
 The operation never closes artifacts, deletes branches, or overwrites an
 installed team or registry. A merged current-generation Cast may still finish
-its linked research through ordinary recovery.
+its linked proposals issue through ordinary recovery.
 
 Keep the same record and ID for retries: they select the same branch and artifact
 identities. Existing branch contents must match the validated payload; divergent
@@ -308,12 +308,14 @@ closed. If the originating dispatch failed after publishing provenance, use
 **Re-run all jobs** on that same run with its original inputs; another run
 cannot promote a failed origin into successful provenance.
 
-Review and merge the Cast PR, then rerun `/squad triage` on the linked issue to
-classify its existing bootstrap proposals. If a proposal needs deeper or newer
-evidence, use one of the issue's focused `/squad research ...` commands first;
-that replaces the bootstrap research seed. Review the resulting plan and run
-`/squad activate`. The bootstrap journey ends when assignable implementation
-issues exist.
+Bootstrap creates the Cast PR and linked proposals issue only; it does not
+publish a research comment or artifact. Review and merge the Cast PR, then run
+`/squad research` on the linked issue, optionally using one of its focused
+proposal commands. Once research is published, run `/squad triage` to classify
+the findings, then `/squad plan`. Review the resulting plan and run
+`/squad activate`. Bootstrap retries do not require research and never modify
+existing research comments. The bootstrap journey ends when assignable
+implementation issues exist.
 
 ---
 

test/gh-aw-bootstrap-workflow.test.ts

@@ -216,6 +216,34 @@ describe('#1935: deterministic research artifact safe output', () => {
   ].join('\n');
   const boldSectionBody = body.replace(/^### (.+)$/gm, '**$1**');
 
+  it('publishes complete explicit research without a preexisting bootstrap artifact', async () => {
+    const completeBody = [
+      body,
+      '',
+      '### Online sources',
+      'Online sources: unavailable — repository evidence only.',
+      '',
+      '### Recommendations',
+      '- R1: address the verified finding before planning.',
+      '',
+      '### Next step',
+      'Run `/squad triage` or `/squad plan`.',
+    ].join('\n');
+    const result = await runResearchUpsert([
+      { type: 'upsert_research_artifact', body: completeBody },
+    ]);
+
+    expect(result.failures).toEqual([]);
+    expect(result.updated).toEqual([]);
+    expect(result.deleted).toEqual([]);
+    expect(result.created).toEqual([{
+      owner: 'octodemo',
+      repo: 'consumer',
+      issue_number: 5,
+      body: `${completeBody}\n\nStructured data:\n\n\`\`\`json\n{"squad_artifact":"research","schema_version":"1","origin_issue":5,"phases":[]}\n\`\`\``,
+    }]);
+  });
+
   it('accepts bold section labels and creates the fixed structured envelope', async () => {
     const result = await runResearchUpsert([
       { type: 'upsert_research_artifact', body: boldSectionBody },

test/gh-aw-lifecycle-upsert.test.ts

@@ -84,24 +84,10 @@ pre-agent-steps:
         })).filter((issue) => !issue.pull_request);
         let state;
         try {
-          const preliminary = stateModule.classifyBootstrapState({
-            ...resetState,
-            pullRequests,
-            issues,
-            defaultBranch: process.env.SQUAD_BOOTSTRAP_DEFAULT_BRANCH,
-          });
-          const comments = preliminary.issue
-            ? await github.paginate(github.rest.issues.listComments, {
-                ...context.repo,
-                issue_number: preliminary.issue.number,
-                per_page: 100,
-              })
-            : [];
           state = stateModule.classifyBootstrapState({
             ...resetState,
             pullRequests,
             issues,
-            comments,
             defaultBranch: process.env.SQUAD_BOOTSTRAP_DEFAULT_BRANCH,
           });
         } catch (error) {
@@ -116,9 +102,7 @@ pre-agent-steps:
           ? state.pull_request.merge_commit_sha
           : state.pull_request?.head_sha;
         core.setOutput('cast_ref', castRef || '');
-        core.info(
-          `Bootstrap recovery action: ${state.action}; research artifacts: ${state.research_artifact_count}`,
-        );
+        core.info(`Bootstrap recovery action: ${state.action}`);
   - name: Restore an existing Cast tree for partial recovery
     if: steps.bootstrap-state.outputs.cast_ref != ''
     uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
@@ -171,7 +155,7 @@ pre-agent-steps:
       # BEGIN GENERATED RESOURCE DIGESTS
       check_hash "$install_verifier" "a279cd5c4adeb613ceb90c1bfbb9818265aeb6bc8986e2e3799e96f7c2d787e5"
       check_hash "$cast_validator" "c6d0b92aac71dc6f6d5727cac418a323b0bc9c12047400faa12d96150d548ada"
-      check_hash "$bootstrap_validator" "ac969d1cc92353219ba312d0d9af8702b1a7a569b4e8d5c79ae71e4aa020aad6"
+      check_hash "$bootstrap_validator" "8462546aa0d2efa37a52ea1df9ffa1b1f0cb7df4e4b17a64e98a11f05cb9d449"
       # END GENERATED RESOURCE DIGESTS
       node "$bootstrap_validator" \
         --encode-payload "${GITHUB_WORKSPACE:?}/.github/workflows/squad-bootstrap-payload.json" \
@@ -385,28 +369,13 @@ safe-outputs:
                     state: 'all',
                     per_page: 100,
                   })).filter((issue) => !issue.pull_request);
-                  const preliminary = stateModule.classifyBootstrapState({
-                    ...resetState,
-                    pullRequests,
-                    issues,
-                    defaultBranch: process.env.SQUAD_BOOTSTRAP_DEFAULT_BRANCH,
-                  });
-                  const comments = preliminary.issue
-                    ? await github.paginate(github.rest.issues.listComments, {
-                        ...context.repo,
-                        issue_number: preliminary.issue.number,
-                        per_page: 100,
-                      })
-                    : [];
                   return {
                     pullRequests,
                     issues,
-                    comments,
                     state: stateModule.classifyBootstrapState({
                       ...resetState,
                       pullRequests,
                       issues,
-                      comments,
                       defaultBranch: process.env.SQUAD_BOOTSTRAP_DEFAULT_BRANCH,
                     }),
                   };
@@ -422,7 +391,7 @@ safe-outputs:
                   return;
                 }
                 if (snapshot.state.action === 'noop') {
-                  core.info('The deterministic Cast PR, research-proposals issue, and research artifact already exist.');
+                  core.info('The deterministic Cast PR and research-proposals issue already exist.');
                   return;
                 }
 
@@ -722,66 +691,23 @@ safe-outputs:
                 const markedIssueBody = `${finalPayload.issue_body.slice(0, issueBodyNewline)}\n${provenanceMarker}${finalPayload.issue_body.slice(issueBodyNewline)}`;
 
                 snapshot = await listState();
-                let issueNumber;
                 if (snapshot.state.issue) {
                   if (snapshot.state.issue.state !== 'open') {
                     core.info(`Bootstrap issue #${snapshot.state.issue.number} is closed; preserving human state.`);
                     return;
                   }
-                  issueNumber = snapshot.state.issue.number;
                   await github.rest.issues.update({
                     ...context.repo,
-                    issue_number: issueNumber,
+                    issue_number: snapshot.state.issue.number,
                     title: stateModule.BOOTSTRAP_ISSUE_TITLE,
                     body: markedIssueBody,
                   });
                 } else {
-                  const createdIssue = await github.rest.issues.create({
+                  await github.rest.issues.create({
                     ...context.repo,
                     title: stateModule.BOOTSTRAP_ISSUE_TITLE,
                     body: markedIssueBody,
                   });
-                  issueNumber = createdIssue.data.number;
-                }
-
-                const researchBody = validatorModule.createBootstrapResearchComment(
-                  finalPayload.issue_body,
-                  issueNumber,
-                );
-                const comments = await github.paginate(github.rest.issues.listComments, {
-                  ...context.repo,
-                  issue_number: issueNumber,
-                  per_page: 100,
-                });
-                const researchArtifacts = validatorModule.findBootstrapResearchArtifacts(
-                  comments,
-                  issueNumber,
-                );
-                const currentResearch = researchArtifacts.at(-1);
-                if (currentResearch) {
-                  if (validatorModule.isBootstrapResearchSeed(currentResearch)) {
-                    await github.rest.issues.updateComment({
-                      ...context.repo,
-                      comment_id: currentResearch.id,
-                      body: researchBody,
-                    });
-                  } else {
-                    core.info(
-                      `Preserving focused research artifact comment #${currentResearch.id}.`,
-                    );
-                  }
-                  for (const duplicate of researchArtifacts.slice(0, -1)) {
-                    await github.rest.issues.deleteComment({
-                      ...context.repo,
-                      comment_id: duplicate.id,
-                    });
-                  }
-                } else {
-                  await github.rest.issues.createComment({
-                    ...context.repo,
-                    issue_number: issueNumber,
-                    body: researchBody,
-                  });
                 }
               } finally {
                 rmSync(candidate, { recursive: true, force: true });
@@ -812,8 +738,6 @@ Read `.github/workflows/squad-bootstrap-state.json` before doing any analysis.
   issue from it, and request materialization.
 - `create_pr`: generate the Cast tree and request materialization; the writer
   updates the one marked issue with the real PR link.
-- `create_research`: preserve both linked artifacts and materialize or repair
-  their one canonical structured research comment.
 
 Never request more than one `materialize_bootstrap` output. The typed writer
 rechecks all pages of pull requests and issues, fails closed on duplicate or
@@ -948,15 +872,13 @@ The issue body must:
 11. End at assignable implementation issues in the actionable-backlog checklist.
 12. Include these exact numbered guidance lines:
     - `1. Review and merge the linked draft Cast PR.`
-    - `2. Rerun /squad triage to classify these existing proposals, or use focused /squad research ... first when deeper research is desired.` Wrap each command in Markdown code spans.
+    - `2. Run /squad research on the proposals you want to pursue, then /squad triage to classify the research findings.` Wrap each command in Markdown code spans.
     - `3. Run /squad plan, review the plan, then run /squad activate to create assignable implementation issues.` Wrap each command in Markdown code spans.
 
-The typed writer derives one concise canonical `squad_artifact=research`
-comment from these validated proposal sections. Do not repeat the full research
-artifact in the payload or issue body. A later focused `/squad research ...`
-run replaces this seed through the normal research upsert contract. Bootstrap
-recovery preserves a newer focused research artifact rather than replacing it
-with the shorter seed.
+Bootstrap creates only the Cast PR and linked proposals issue, not a research
+comment or artifact. Research is published only when a human invokes
+`/squad research` (optionally with a proposal focus), before triage or planning.
+Bootstrap recovery never creates, updates, or deletes research comments.
 
 Keep the issue concise and evidence-led. Do not copy the detailed research
 exemplar's long audit format.
@@ -981,7 +903,7 @@ Exit status zero with stdout exactly
 means the one output has already been submitted. Stop immediately.
 Never read, print, extract, or transcribe `squad-bootstrap-envelope.json` or its
 chunks. Never invoke `materialize_bootstrap` separately, retry the command, or
-split Cast and research into separate outputs.
+split Cast and proposals into separate outputs.
 
 Any validation, envelope, or submission error is terminal: report the exact
 stderr and stop without another materialization attempt.