@codedrifters/configulator 0.0.414 → 0.0.415

package/lib/index.js

@@ -6211,6 +6211,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 {
@@ -6406,7 +6458,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.",
       "",
@@ -6420,6 +6473,10 @@ function buildBcmWriterSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Outline (`bcm:outline`)",
       "",
       "**Goal:** Identify the capability (name-as-noun, business object, tier)",
@@ -6508,7 +6565,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}.`,
       "",
       "---",
       "",
@@ -6595,7 +6653,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}.`,
       "",
       "---",
       "",
@@ -6684,7 +6743,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}.`,
       "",
       "---",
       "",
@@ -6778,7 +6837,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}.`,
       "",
       "---",
       "",
@@ -7710,7 +7769,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.",
       "",
@@ -7724,6 +7784,10 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scan (`business-models:scan`)",
       "",
       "**Goal:** Read upstream industry and profile artifacts to identify",
@@ -7802,7 +7866,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}.`,
       "",
       "---",
       "",
@@ -7874,7 +7939,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}.`,
       "",
       "---",
       "",
@@ -8005,7 +8071,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}.`,
       "",
       "---",
       "",
@@ -8619,7 +8685,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.",
       "",
@@ -8633,6 +8700,10 @@ function buildCompanyProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Research (`company:research`)",
       "",
       "**Goal:** Gather public sources into a bounded research-notes file.",
@@ -8698,7 +8769,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}.`,
       "",
       "---",
       "",
@@ -8808,7 +8880,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}.`,
       "",
       "---",
       "",
@@ -8904,7 +8977,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}.`,
       "",
       "---",
       "",
@@ -8953,7 +9026,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,",
@@ -9024,8 +9097,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}.`,
       "",
       "---",
       "",
@@ -9117,8 +9191,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}.`,
       "",
       "---",
       "",
@@ -9232,8 +9307,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}.`,
       "",
       "---",
       "",
@@ -10070,7 +10146,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.",
       "",
@@ -10084,6 +10161,10 @@ function buildCustomerProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Discover (`customer:discover`)",
       "",
       "**Goal:** Identify and segment the customer archetypes relevant to",
@@ -10169,7 +10250,7 @@ function buildCustomerProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "   priority archetype.",
       "",
       "7. **Commit and push** the discovery report. Close the discover",
-      "   issue.",
+      `   issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -10248,7 +10329,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}.`,
       "",
       "---",
       "",
@@ -10381,7 +10463,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}.`,
       "",
       "---",
       "",
@@ -13028,7 +13110,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.",
       "",
@@ -13042,6 +13125,10 @@ function buildIndustryDiscoveryAnalystSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Discover (`industry:discover`)",
       "",
       "**Goal:** Enumerate candidate industry verticals into a bounded",
@@ -13106,7 +13193,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}.`,
       "",
       "---",
       "",
@@ -13167,7 +13255,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}.`,
       "",
       "---",
       "",
@@ -13230,7 +13319,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}.`,
       "",
       "---",
       "",
@@ -13593,7 +13683,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.",
       "",
@@ -13609,6 +13700,10 @@ function buildMaintenanceAuditSubAgent(paths, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scan (`maint:scan`)",
       "",
       "**Goal:** Walk the configured doc tree, check every cross-reference",
@@ -13705,11 +13800,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",
@@ -13824,9 +13921,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.**",
       "",
@@ -13932,8 +14029,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}.`,
       "",
       "---",
       "",
@@ -14211,7 +14308,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",
       "",
@@ -14505,6 +14604,10 @@ function buildMeetingAnalystSubAgent(tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Extract (`meeting:extract`)",
       "",
       "**Goal:** Read the available meeting inputs (notes, transcript, or both)",
@@ -14646,7 +14749,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}.`,
       "",
       "---",
       "",
@@ -14744,7 +14848,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}.`,
       "",
       "---",
       "",
@@ -14776,7 +14880,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}.`,
       "",
       "---",
       "",
@@ -14888,7 +14993,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}.`,
       "",
       "---",
       "",
@@ -20538,7 +20644,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.",
       "",
@@ -20552,6 +20659,10 @@ function buildPeopleProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Research (`people:research`)",
       "",
       "**Goal:** Gather public sources into a bounded research-notes file.",
@@ -20622,7 +20733,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}.`,
       "",
       "---",
       "",
@@ -20724,7 +20836,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}.`,
       "",
       "---",
       "",
@@ -20856,7 +20969,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}.`,
       "",
       "---",
       "",
@@ -20940,8 +21053,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}.`,
       "",
       "---",
       "",
@@ -25384,7 +25498,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.",
       "",
@@ -25398,6 +25513,10 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scan (`regulatory:scan`)",
       "",
       "**Goal:** Enumerate regulations applicable to a given scope \u2014",
@@ -25515,7 +25634,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}.`,
       "",
       "---",
       "",
@@ -25589,7 +25708,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}.`,
       "",
       "---",
       "",
@@ -25733,7 +25852,7 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       ...renderIssueTypeAssignmentStep(),
       "",
       "7. **Commit and push** the updated regulation page. Close the",
-      "   impact issue.",
+      `   impact issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",
@@ -31237,7 +31356,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.",
       "",
@@ -31251,6 +31371,10 @@ function buildResearchAnalystSubAgent(paths) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scope (`research:scope`)",
       "",
       "**Goal:** Turn a natural-language research question into a bounded",
@@ -31326,7 +31450,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}.`,
       "",
       "---",
       "",
@@ -31383,7 +31508,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}.`,
       "",
       "---",
       "",
@@ -31448,7 +31574,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}.`,
       "",
       "---",
       "",
@@ -31988,7 +32115,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.",
       "",
@@ -32002,6 +32130,10 @@ function buildSoftwareProfileAnalystSubAgent(paths, issueDefaults, tier) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Research (`software:research`)",
       "",
       "**Goal:** Gather public sources into a bounded research-notes file.",
@@ -32068,7 +32200,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}.`,
       "",
       "---",
       "",
@@ -32163,7 +32296,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}.`,
       "",
       "---",
       "",
@@ -32273,7 +32407,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}.`,
       "",
       "---",
       "",
@@ -32395,7 +32530,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}.`,
       "",
       "---",
       "",
@@ -32515,7 +32651,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}.`,
       "",
       "---",
       "",
@@ -33132,7 +33268,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.",
       "",
@@ -33146,6 +33283,10 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "",
       "---",
       "",
+      ...renderIssueClosePolicySection(),
+      "",
+      "---",
+      "",
       "## Phase 1: Scope (`standards:scope`)",
       "",
       "**Goal:** Plan the research campaign for a standard \u2014 identify which",
@@ -33230,7 +33371,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}.`,
       "",
       "---",
       "",
@@ -33379,7 +33521,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}.`,
       "",
       "---",
       "",
@@ -33445,7 +33588,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}.`,
       "",
       "---",
       "",
@@ -33583,7 +33727,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}.`,
       "",
       "---",
       "",
@@ -33684,7 +33828,7 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       ...renderIssueTypeAssignmentStep(),
       "",
       "7. **Commit and push** the organization page. Close the",
-      "   organizations issue.",
+      `   organizations issue ${ISSUE_CLOSE_RULE_REFERENCE}.`,
       "",
       "---",
       "",