@codedrifters/configulator 0.0.414 → 0.0.415

package/lib/index.mjs

@@ -5830,6 +5830,58 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS, conventions = DEFAULT_BASE
 }
 var baseBundle = buildBaseBundle();
 
+// src/agent/bundles/issue-close.ts
+var ISSUE_CLOSE_SECTION_TITLE = "Issue closing";
+var ISSUE_CLOSE_RULE_REFERENCE = `per the **${ISSUE_CLOSE_SECTION_TITLE}** rule`;
+function renderIssueClosePolicySection() {
+  return [
+    `## ${ISSUE_CLOSE_SECTION_TITLE}`,
+    "",
+    "**Never close a phase issue that your PR is going to close for**",
+    "**you.** Most projects put a closing keyword (`Closes #<n>`) in the",
+    "PR body, so the issue closes when the PR merges \u2014 and that merge is",
+    "what drives the documented `status:ready-for-review` \u2192",
+    "`status:done` transition.",
+    "",
+    "Closing the issue yourself at the end of a phase pre-empts all of",
+    "that:",
+    "",
+    "- the PR's `Closes #<n>` line becomes a no-op \u2014 nothing happens at",
+    "  merge time;",
+    "- the issue closes while still carrying `status:in-progress` or",
+    "  `status:ready-for-review`, so its labels describe a state it has",
+    "  already left;",
+    "- any caller that applies a status label afterwards is labelling a",
+    "  closed issue, and a caller that verifies workflow state has to",
+    "  reopen the issue to put it back in the pipeline.",
+    "",
+    "So whenever a phase step tells you to close its issue, resolve it",
+    "against your project's PR workflow first:",
+    "",
+    "1. **The PR closes it.** Your PR body carries `Closes #<n>` for this",
+    "   issue \u2014 commit, push, open the PR, and leave the issue **open**.",
+    "   Post the phase outcome the step asks for as an ordinary comment",
+    "   on the issue, not as a closing comment, and let the merge perform",
+    "   the close.",
+    "2. **The PR does not close it.** There is no closing keyword for",
+    "   this issue, or the phase lands no PR at all \u2014 close the issue",
+    "   yourself, with the outcome comment the step describes.",
+    "",
+    "### Always close directly",
+    "",
+    "Two cases never wait on a merge:",
+    "",
+    "- **Aborts.** A phase that stops without a deliverable \u2014 nothing",
+    "  relevant found, a duplicate, an ambiguity handed off with",
+    "  `status:needs-attention` \u2014 closes its issue directly. No PR will",
+    "  ever reference it.",
+    "- **Someone else's issue.** Closing an issue other than the one you",
+    "  are working (a parent issue your phase resolves, a superseded",
+    "  sibling) is bookkeeping, not the workflow close. A closing keyword",
+    "  only ever covers the issues your PR body names."
+  ];
+}
+
 // src/agent/bundles/bcm-writer.ts
 function buildBcmWriterSubAgent(paths, issueDefaults) {
   return {
@@ -6025,7 +6077,8 @@ function buildBcmWriterSubAgent(paths, issueDefaults) {
       "   branch per your project's branch-naming convention.",
       "3. Execute the phase handler that matches the issue's `bcm:*` label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -6039,6 +6092,10 @@ function buildBcmWriterSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Outline (`bcm:outline`)",
       "",
       "**Goal:** Identify the capability (name-as-noun, business object, tier)",
@@ -6127,7 +6184,8 @@ function buildBcmWriterSubAgent(paths, issueDefaults) {
       "   `Depends on: #<outline-issue>`. Its body references the outline",
       "   file path.",
       "",
-      "10. **Commit and push** the outline file. Close the outline issue.",
+      "10. **Commit and push** the outline file. Close the outline issue",
+      `    ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -6214,7 +6272,8 @@ function buildBcmWriterSubAgent(paths, issueDefaults) {
       "   `Depends on: #<scaffold-issue>`. Its body references the BCM",
       "   document path and the outline file path.",
       "",
-      "5. **Commit and push** the BCM document. Close the scaffold issue.",
+      "5. **Commit and push** the BCM document. Close the scaffold issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -6303,7 +6362,7 @@ function buildBcmWriterSubAgent(paths, issueDefaults) {
       "    those into downstream issues.",
       "",
       "11. **Commit and push** the updated BCM document. Close the context",
-      "    issue.",
+      `    issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -6397,7 +6456,7 @@ function buildBcmWriterSubAgent(paths, issueDefaults) {
       "",
       "8. **Commit and push** the registry update, capability-map update,",
       "   cross-link edits, and BCM-document revision-history row. Close the",
-      "   connect issue.",
+      `   connect issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -7335,7 +7394,8 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "3. Execute the phase handler that matches the issue's",
       "   `business-models:*` label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -7349,6 +7409,10 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scan (`business-models:scan`)",
       "",
       "**Goal:** Read upstream industry and profile artifacts to identify",
@@ -7427,7 +7491,8 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "   references the scan report, the industry, the segment name, and",
       "   the authorized source list.",
       "",
-      "8. **Commit and push** the scan report. Close the scan issue.",
+      "8. **Commit and push** the scan report. Close the scan issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -7499,7 +7564,8 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "   `Depends on: #<canvas-issue>`. Its body references the path to",
       "   the canvas document and names the industry and segment.",
       "",
-      "9. **Commit and push** the canvas document. Close the canvas issue.",
+      "9. **Commit and push** the canvas document. Close the canvas issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -7630,7 +7696,7 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "    summary: value-stream count, variation coverage, and the list of",
       "    `bcm:outline` issues created.",
       "",
-      "12. **Close the complete issue.**",
+      `12. **Close the complete issue** ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -8244,7 +8310,8 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "3. Execute the phase handler that matches the issue's `company:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -8258,6 +8325,10 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Research (`company:research`)",
       "",
       "**Goal:** Gather public sources into a bounded research-notes file.",
@@ -8323,7 +8394,8 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   Its body references the notes file path and the requested company",
       "   type.",
       "",
-      "6. **Commit and push** the notes file. Close the research issue.",
+      "6. **Commit and push** the notes file. Close the research issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -8433,7 +8505,8 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   no business-model canvases at all (Phase 4 will detect and exit",
       "   gracefully in that case).",
       "",
-      "7. **Commit and push** the profile file. Close the draft issue.",
+      "7. **Commit and push** the profile file. Close the draft issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -8529,7 +8602,7 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   because a profile already exists).",
       "",
       "8. **Commit and push** (if the profile was updated). Close the",
-      "   followup issue.",
+      `   followup issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -8578,7 +8651,7 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       `   the consuming project declares in \`${paths.docsRoot}/project-context.md\`).`,
       "   If the directory does not exist or contains no canvases, exit",
       "   gracefully: add a short note to the profile's `## Risks / Open",
-      "   Questions` section and close the issue.",
+      `   Questions\` section and close the issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "4. **For each candidate canvas, score the match.** For each canvas:",
       "   - Read the Customer Segments, Key Activities, Value Propositions,",
@@ -8649,8 +8722,9 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   | YYYY-MM-DD | Matched to business models: <comma-separated segment list> |",
       "   ```",
       "",
-      "9. **Commit and push.** Close the match issue with a short comment",
-      "   summarizing the matched segments.",
+      "9. **Commit and push.** Report the matched segments on the match",
+      "   issue with a short comment, and close it",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -8742,8 +8816,9 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   update the corresponding entry under `referencedIn` and the",
       "   research-area doc that links to this profile.",
       "",
-      "9. **Commit and push.** Close the refresh issue with a short comment",
-      "   summarizing the delta (or `no material change`).",
+      "9. **Commit and push.** Report the delta on the refresh issue with",
+      "   a short comment (or `no material change`), and close it",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -8857,8 +8932,9 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   from a profile to the analysis document should be added by a",
       "   follow-up `company:match` pass, not by this phase.",
       "",
-      "7. **Commit and push.** Close the analyze issue with a short",
-      "   comment naming the analysis document path.",
+      "7. **Commit and push.** Name the analysis document path on the",
+      "   analyze issue with a short comment, and close it",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -9695,7 +9771,8 @@ function buildCustomerProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "3. Execute the phase handler that matches the issue's `customer:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -9709,6 +9786,10 @@ function buildCustomerProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Discover (`customer:discover`)",
       "",
       "**Goal:** Identify and segment the customer archetypes relevant to",
@@ -9794,7 +9875,7 @@ function buildCustomerProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   priority archetype.",
       "",
       "7. **Commit and push** the discovery report. Close the discover",
-      "   issue.",
+      `   issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -9873,7 +9954,8 @@ function buildCustomerProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "10. **Verify all handoffs were created** before committing.",
       "",
-      "11. **Commit and push** the archetype page. Close the profile issue.",
+      "11. **Commit and push** the archetype page. Close the profile issue",
+      `    ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -10006,7 +10088,7 @@ function buildCustomerProfileAnalystSubAgent(paths, issueDefaults, tier) {
       ...renderIssueTypeAssignmentStep(),
       "",
       "10. **Commit and push** the competitor-analysis page and the",
-      "    updated archetype page. Close the competitors issue.",
+      `    updated archetype page. Close the competitors issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -12653,7 +12735,8 @@ function buildIndustryDiscoveryAnalystSubAgent(paths, issueDefaults) {
       "3. Execute the phase handler that matches the issue's `industry:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -12667,6 +12750,10 @@ function buildIndustryDiscoveryAnalystSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Discover (`industry:discover`)",
       "",
       "**Goal:** Enumerate candidate industry verticals into a bounded",
@@ -12731,7 +12818,8 @@ function buildIndustryDiscoveryAnalystSubAgent(paths, issueDefaults) {
       "   file path and the fit rubric source (invoking issue, project",
       "   context, or scaffold).",
       "",
-      "6. **Commit and push** the candidate file. Close the discover issue.",
+      "6. **Commit and push** the candidate file. Close the discover issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -12792,7 +12880,8 @@ function buildIndustryDiscoveryAnalystSubAgent(paths, issueDefaults) {
       "   `Depends on: #<evaluate-issue>`. Its body references the evaluation",
       "   file path and lists the verticals that clear the threshold (if any).",
       "",
-      "6. **Commit and push** the evaluation file. Close the evaluate issue.",
+      "6. **Commit and push** the evaluation file. Close the evaluate issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -12855,7 +12944,8 @@ function buildIndustryDiscoveryAnalystSubAgent(paths, issueDefaults) {
       "   table so each row references its newly-created `research:scope`",
       "   issue number.",
       "",
-      "6. **Commit and push** the plan file. Close the plan issue.",
+      "6. **Commit and push** the plan file. Close the plan issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -13218,7 +13308,8 @@ function buildMaintenanceAuditSubAgent(paths, tier) {
       "3. Execute the phase handler that matches the issue's `maint:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -13234,6 +13325,10 @@ function buildMaintenanceAuditSubAgent(paths, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scan (`maint:scan`)",
       "",
       "**Goal:** Walk the configured doc tree, check every cross-reference",
@@ -13330,11 +13425,13 @@ function buildMaintenanceAuditSubAgent(paths, tier) {
       "5. **Decide the next step:**",
       "   - **No findings** \u2192 comment on the scan issue noting a clean",
       "     audit, commit the (still valuable) empty report, close the",
-      "     issue. Do not create a `maint:fix` issue.",
+      `     issue ${ISSUE_CLOSE_RULE_REFERENCE}. Do not create a`,
+      "     `maint:fix` issue.",
       "   - **All findings need human judgment** \u2192 commit the report,",
       "     comment on the scan issue summarizing the findings, apply",
-      "     `status:needs-attention`, and close the issue. Do not create",
-      "     a `maint:fix` or `maint:verify` issue.",
+      "     `status:needs-attention`, and close the issue",
+      `     ${ISSUE_CLOSE_RULE_REFERENCE}. Do not create a \`maint:fix\` or`,
+      "     `maint:verify` issue.",
       "   - **At least one auto-fixable finding** \u2192 create a `maint:fix`",
       "     issue (blocked on this scan issue via `Depends on: #N`). The",
       "     fix issue body must reference the audit report path, enumerate",
@@ -13449,9 +13546,9 @@ function buildMaintenanceAuditSubAgent(paths, tier) {
       "",
       "   If the fix phase applied **zero** auto-fixes (every finding was",
       "   `stale-finding` or `flag-for-human`), skip the verify issue \u2014",
-      "   there is nothing to verify. Close the fix issue with a summary,",
-      "   comment on the scan issue, and let a human decide whether to",
-      "   re-scan.",
+      "   there is nothing to verify. Summarize on the fix issue and close",
+      `   it ${ISSUE_CLOSE_RULE_REFERENCE}, comment on the scan issue, and`,
+      "   let a human decide whether to re-scan.",
       "",
       "9. **Commit and push.**",
       "",
@@ -13557,8 +13654,8 @@ function buildMaintenanceAuditSubAgent(paths, tier) {
       "     re-scope the cycle. Do not auto-close the parent scan issue",
       "     in this case.",
       "",
-      "6. **Commit and push.** Close the verify issue with a one-line",
-      "   summary of the verdict.",
+      "6. **Commit and push.** Comment the verdict on the verify issue in",
+      `   one line, and close it ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -13836,7 +13933,9 @@ function buildMeetingAnalystSubAgent(tier) {
       "",
       "1. Each meeting produces up to 4 GitHub issues (one per phase)",
       "2. Each issue carries a `meeting:*` label identifying the phase",
-      "3. You pick up one issue, execute that phase, commit/push, then close the issue",
+      "3. You pick up one issue, execute that phase, commit/push, then close",
+      `   the issue \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}** section below`,
+      "   before you close anything yourself",
       "4. Phase 1 (Extract) creates the downstream phase issues for phases 2-4",
       "5. Each downstream issue includes `Depends on: #N` linking to its predecessor",
       "",
@@ -14130,6 +14229,10 @@ function buildMeetingAnalystSubAgent(tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Extract (`meeting:extract`)",
       "",
       "**Goal:** Read the available meeting inputs (notes, transcript, or both)",
@@ -14271,7 +14374,8 @@ function buildMeetingAnalystSubAgent(tier) {
       "   commit-path verification step (`git show HEAD:<index-path>`",
       "   + grep count) against that commit before pushing.",
       "",
-      "9. **Push and close.** Push the branch and close the extract issue.",
+      "9. **Push and close.** Push the branch, then close the extract issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -14369,7 +14473,7 @@ function buildMeetingAnalystSubAgent(tier) {
       "   commit** whose only file is the shared index. Run the",
       "   commit-path verification step against that commit before",
       "   pushing.",
-      "7. Push and close the notes issue.",
+      `7. Push, then close the notes issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -14401,7 +14505,8 @@ function buildMeetingAnalystSubAgent(tier) {
       "   - Stated preferences or decisions",
       "   - Status: Proposed or Decided",
       "5. Summarize product/strategy document updates needed.",
-      "6. Commit, push, and close the draft issue.",
+      "6. Commit, push, and close the draft issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -14513,7 +14618,8 @@ function buildMeetingAnalystSubAgent(tier) {
       "   meeting.",
       "9. Comment on the parent extract issue with a summary linking to all",
       "   created artifacts.",
-      "10. Commit and push (if any file changes were made), then close the link issue.",
+      "10. Commit and push (if any file changes were made), then close the",
+      `    link issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -20163,7 +20269,8 @@ function buildPeopleProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "3. Execute the phase handler that matches the issue's `people:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -20177,6 +20284,10 @@ function buildPeopleProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Research (`people:research`)",
       "",
       "**Goal:** Gather public sources into a bounded research-notes file.",
@@ -20247,7 +20358,8 @@ function buildPeopleProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   Its body references the notes file path, the requested role, and",
       "   any refresh-mode flags.",
       "",
-      "7. **Commit and push** the notes file. Close the research issue.",
+      "7. **Commit and push** the notes file. Close the research issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -20349,7 +20461,8 @@ function buildPeopleProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   followup when the profile surfaced no cross-reference candidates",
       "   at all; note this in the draft issue's closing comment.",
       "",
-      "5. **Commit and push** the profile file. Close the draft issue.",
+      "5. **Commit and push** the profile file. Close the draft issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -20481,7 +20594,7 @@ function buildPeopleProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "    enqueued for research).",
       "",
       "11. **Commit and push** the updated profile. Close the followup",
-      "    issue.",
+      `    issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -20565,8 +20678,9 @@ function buildPeopleProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   even if a search surfaces them. Privacy guardrails from Phase 1",
       "   apply to every refresh.",
       "",
-      "8. **Commit and push.** Close the refresh issue with a short comment",
-      "   summarizing the delta (or `no material change`).",
+      "8. **Commit and push.** Report the delta on the refresh issue with",
+      "   a short comment (or `no material change`), and close it",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -25009,7 +25123,8 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       "3. Execute the phase handler that matches the issue's `regulatory:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -25023,6 +25138,10 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scan (`regulatory:scan`)",
       "",
       "**Goal:** Enumerate regulations applicable to a given scope \u2014",
@@ -25140,7 +25259,7 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       "   page H1.",
       "",
       "8. **Commit and push** the scan report and the scope index page.",
-      "   Close the scan issue.",
+      `   Close the scan issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -25214,7 +25333,7 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       "9. **Verify all handoffs were created** before committing.",
       "",
       "10. **Commit and push** the regulation page. Close the research",
-      "    issue.",
+      `    issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -25358,7 +25477,7 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       ...renderIssueTypeAssignmentStep(),
       "",
       "7. **Commit and push** the updated regulation page. Close the",
-      "   impact issue.",
+      `   impact issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -30862,7 +30981,8 @@ function buildResearchAnalystSubAgent(paths) {
       "3. Execute the phase handler that matches the issue's `research:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -30876,6 +30996,10 @@ function buildResearchAnalystSubAgent(paths) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scope (`research:scope`)",
       "",
       "**Goal:** Turn a natural-language research question into a bounded",
@@ -30951,7 +31075,8 @@ function buildResearchAnalystSubAgent(paths) {
       "   issues. Its body references the scope file and lists every slice",
       "   output path that verify must read.",
       "",
-      "7. **Commit and push** the scope file. Close the scope issue.",
+      "7. **Commit and push** the scope file. Close the scope issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -31008,7 +31133,8 @@ function buildResearchAnalystSubAgent(paths) {
       "   cut and flag it for the verify phase \u2014 do not expand into other",
       "   slices' territory.",
       "",
-      "6. **Commit and push** the slice note. Close the slice issue.",
+      "6. **Commit and push** the slice note. Close the slice issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -31073,7 +31199,8 @@ function buildResearchAnalystSubAgent(paths) {
       "6. **Comment on the scope issue** with a summary linking to the",
       "   deliverable and verification report.",
       "",
-      "7. **Commit and push.** Close the verify issue.",
+      "7. **Commit and push.** Close the verify issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -31613,7 +31740,8 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "3. Execute the phase handler that matches the issue's `software:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -31627,6 +31755,10 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Research (`software:research`)",
       "",
       "**Goal:** Gather public sources into a bounded research-notes file.",
@@ -31693,7 +31825,8 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   `Depends on: #<research-issue>`. Its body references the notes",
       "   file path and the requested software type.",
       "",
-      "6. **Commit and push** the notes file. Close the research issue.",
+      "6. **Commit and push** the notes file. Close the research issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -31788,7 +31921,8 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   path, the matrix file path, and the segment-weights source",
       `   (\`${paths.docsRoot}/project-context.md\` or an explicit override).`,
       "",
-      "5. **Commit and push** the profile file. Close the profile issue.",
+      "5. **Commit and push** the profile file. Close the profile issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -31898,7 +32032,8 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   count on the product slug as the unique marker) against",
       "   that commit before pushing.",
       "",
-      "9. **Push and close.** Push the branch and close the matrix issue.",
+      "9. **Push and close.** Push the branch, then close the matrix issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -32020,7 +32155,8 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   could not be routed \u2014 never invent an alternative label",
       "   taxonomy.",
       "",
-      "10. **Commit and push** the updated profile. Close the map issue.",
+      "10. **Commit and push** the updated profile. Close the map issue",
+      `    ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -32140,7 +32276,7 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   were enqueued for research).",
       "",
       "9. **Commit and push** (if the profile was updated). Close the",
-      "   followup issue.",
+      `   followup issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -32757,7 +32893,8 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "3. Execute the phase handler that matches the issue's `standards:*`",
       "   label.",
       "4. Commit, push, open a PR (if applicable), and close the issue per",
-      "   your project's PR workflow.",
+      `   your project's PR workflow \u2014 see the **${ISSUE_CLOSE_SECTION_TITLE}**`,
+      "   section below before you close anything yourself.",
       "   Stamp every PR you open with the `origin:agent` label \u2014 see the",
       "   **Origin label** section below.",
       "",
@@ -32771,6 +32908,10 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scope (`standards:scope`)",
       "",
       "**Goal:** Plan the research campaign for a standard \u2014 identify which",
@@ -32855,7 +32996,8 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "   in parallel with research issues \u2014 they do not depend on",
       "   research completing.",
       "",
-      "8. **Commit and push** the query plan. Close the scope issue.",
+      "8. **Commit and push** the query plan. Close the scope issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -33004,7 +33146,8 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "   entity in both tables, confirm an existing profile or a fresh",
       "   handoff issue exists. Do not commit with missing handoffs.",
       "",
-      "8. **Commit and push** the version page. Close the research issue.",
+      "8. **Commit and push** the version page. Close the research issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -33070,7 +33213,8 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "   entity. This handoff is optional \u2014 if no domain entities show",
       "   gaps, skip it.",
       "",
-      "6. **Commit and push** the overview page. Close the compare issue.",
+      "6. **Commit and push** the overview page. Close the compare issue",
+      `   ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -33208,7 +33352,7 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "8. **Create `<EXTENSIONS_DIR>`** if it does not yet exist.",
       "",
       "9. **Commit and push** the extension analysis. Close the extension",
-      "   issue.",
+      `   issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -33309,7 +33453,7 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       ...renderIssueTypeAssignmentStep(),
       "",
       "7. **Commit and push** the organization page. Close the",
-      "   organizations issue.",
+      `   organizations issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",