@codedrifters/configulator 0.0.260 → 0.0.261

package/lib/index.d.mts

@@ -1766,12 +1766,13 @@ declare const jestBundle: AgentRuleBundle;
  * `true` per this batch's directive that bundles assume peers are
  * present.
  *
- * Provides a 2-phase documentation-maintenance pipeline (scan → fix)
- * designed for any project with structured doc registries and
- * cross-references. Ships a sub-agent, a user-invocable skill, and
- * `maint:*` phase labels via the bundle `labels` mechanism so
- * consuming projects automatically pick up the label taxonomy
- * through the sync-labels workflow.
+ * Provides a 3-phase documentation-maintenance pipeline
+ * (scan → fix → verify) designed for any project with structured doc
+ * registries and cross-references. Ships a sub-agent, two user-
+ * invocable skills (`/audit-docs`, `/verify-audit`), and `maint:*`
+ * phase labels via the bundle `labels` mechanism so consuming projects
+ * automatically pick up the label taxonomy through the sync-labels
+ * workflow.
  */
 declare const maintenanceAuditBundle: AgentRuleBundle;
 

package/lib/index.d.ts

@@ -1815,12 +1815,13 @@ declare const jestBundle: AgentRuleBundle;
  * `true` per this batch's directive that bundles assume peers are
  * present.
  *
- * Provides a 2-phase documentation-maintenance pipeline (scan → fix)
- * designed for any project with structured doc registries and
- * cross-references. Ships a sub-agent, a user-invocable skill, and
- * `maint:*` phase labels via the bundle `labels` mechanism so
- * consuming projects automatically pick up the label taxonomy
- * through the sync-labels workflow.
+ * Provides a 3-phase documentation-maintenance pipeline
+ * (scan → fix → verify) designed for any project with structured doc
+ * registries and cross-references. Ships a sub-agent, two user-
+ * invocable skills (`/audit-docs`, `/verify-audit`), and `maint:*`
+ * phase labels via the bundle `labels` mechanism so consuming projects
+ * automatically pick up the label taxonomy through the sync-labels
+ * workflow.
  */
 declare const maintenanceAuditBundle: AgentRuleBundle;
 

package/lib/index.js

@@ -4543,7 +4543,7 @@ var jestBundle = {
 // src/agent/bundles/maintenance-audit.ts
 var maintenanceAuditSubAgent = {
   name: "maintenance-audit",
-  description: "Audits documentation registries and cross-references for integrity (broken links, registry drift, stale indexes) and applies idempotent fixes. One phase per session, tracked by maint:* GitHub issue labels with filesystem-based durability between phases.",
+  description: "Audits documentation registries and cross-references for integrity (broken links, registry drift, stale indexes), applies idempotent fixes, then re-runs the checks to confirm the fixes cleared the reported findings. One phase per session, tracked by maint:* GitHub issue labels with filesystem-based durability between phases.",
   model: AGENT_MODEL.POWERFUL,
   maxTurns: 80,
   platforms: { cursor: { exclude: true } },
@@ -4601,18 +4601,18 @@ var maintenanceAuditSubAgent = {
     "",
     "## State Machine Overview",
     "",
-    "Maintenance audits flow through **2 phases**:",
+    "Maintenance audits flow through **3 phases**:",
     "",
     "```",
-    "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
-    "\u2502  1. SCAN     \u2502\u2500\u2500\u2500\u2500\u25B6\u2502  2. FIX      \u2502",
-    "\u2502  Walk doc    \u2502     \u2502  Read audit  \u2502",
-    "\u2502  tree, check \u2502     \u2502  report,     \u2502",
-    "\u2502  xrefs and   \u2502     \u2502  apply safe  \u2502",
-    "\u2502  indexes,    \u2502     \u2502  idempotent  \u2502",
-    "\u2502  write audit \u2502     \u2502  fixes, then \u2502",
-    "\u2502  report      \u2502     \u2502  verify      \u2502",
-    "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
+    "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
+    "\u2502  1. SCAN     \u2502\u2500\u2500\u2500\u2500\u25B6\u2502  2. FIX      \u2502\u2500\u2500\u2500\u2500\u25B6\u2502  3. VERIFY   \u2502",
+    "\u2502  Walk doc    \u2502     \u2502  Read audit  \u2502     \u2502  Re-run the  \u2502",
+    "\u2502  tree, check \u2502     \u2502  report,     \u2502     \u2502  scan checks \u2502",
+    "\u2502  xrefs and   \u2502     \u2502  apply safe  \u2502     \u2502  scoped to   \u2502",
+    "\u2502  indexes,    \u2502     \u2502  idempotent  \u2502     \u2502  fixed paths,\u2502",
+    "\u2502  write audit \u2502     \u2502  fixes, write\u2502     \u2502  compare pre \u2502",
+    "\u2502  report      \u2502     \u2502  fix report  \u2502     \u2502  and post    \u2502",
+    "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
     "```",
     "",
     "**Issue labels encode the phase:**",
@@ -4620,18 +4620,22 @@ var maintenanceAuditSubAgent = {
     "| Label | Phase | Session work |",
     "|-------|-------|-------------|",
     "| `maint:scan` | 1. Scan | Walk the configured doc tree, check cross-references and registry indexes, write a durable audit report. |",
-    "| `maint:fix` | 2. Fix | Read the audit report, apply idempotent fixes, then verify the fixes cleared the reported findings. |",
+    "| `maint:fix` | 2. Fix | Read the audit report, apply idempotent fixes, write a durable fix report. |",
+    "| `maint:verify` | 3. Verify | Re-run the same checks from the parent `maint:scan` issue scoped to the paths and registries the fix phase touched, compare pre and post findings, close the parent scan issue when clean, and file a follow-up `maint:scan` for any residual findings. |",
     "",
     "All issues also carry `type:maintenance` and a `status:*` label.",
     "",
-    "**Issue count per audit cycle:** 1 scan + 1 fix = **2 sessions**.",
+    "**Issue count per audit cycle:** 1 scan + 1 fix + 1 verify = **3 sessions**.",
     "",
     "**Shortened paths:**",
     "- Scan finds no issues \u2192 close scan issue with a justification,",
-    "  do not create a fix issue \u2192 **1 session**.",
+    "  do not create a fix or verify issue \u2192 **1 session**.",
     "- Every reported finding requires a human judgment call \u2192 close",
     "  scan with the report, open a `status:needs-attention` flag,",
-    "  do not auto-create a fix issue \u2192 **1 session**.",
+    "  do not auto-create a fix or verify issue \u2192 **1 session**.",
+    "- Fix phase applied only `flag-for-human` decisions (no auto-",
+    "  fixable findings landed) \u2192 close the fix issue with the",
+    "  skipped list and do not create a verify issue \u2192 **2 sessions**.",
     "",
     "---",
     "",
@@ -4661,7 +4665,9 @@ var maintenanceAuditSubAgent = {
     "Run this loop exactly once per session. Never start a second issue.",
     "",
     "1. Claim one open `type:maintenance` issue using phase priority:",
-    "   `maint:scan` > `maint:fix`.",
+    "   `maint:verify` > `maint:fix` > `maint:scan`. Verify ahead of fix",
+    "   and scan so the oldest in-flight audit cycle finishes closing",
+    "   the loop before a new cycle starts.",
     "2. Transition `status:ready` \u2192 `status:in-progress` and create the",
     "   branch per your project's branch-naming convention.",
     "3. Execute the phase handler that matches the issue's `maint:*`",
@@ -4773,24 +4779,30 @@ var maintenanceAuditSubAgent = {
     "   - **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` issue.",
+    "     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 and",
-    "     enumerate the auto-fix categories to apply.",
+    "     fix issue body must reference the audit report path, enumerate",
+    "     the auto-fix categories to apply, and record the parent scan",
+    "     issue number so Phase 3 (Verify) can close the loop.",
     "",
-    "6. **Commit and push.**",
+    "6. **Commit and push.** Leave the scan issue open so the downstream",
+    "   `maint:verify` phase can close it (or file a follow-up scan)",
+    "   after Phase 2 runs.",
     "",
     "---",
     "",
     "## Phase 2: Fix (`maint:fix`)",
     "",
-    "**Goal:** Read the audit report, apply idempotent fixes, verify",
-    "they cleared the reported findings, and commit the doc-tree changes.",
+    "**Goal:** Read the audit report, apply idempotent fixes, write a",
+    "fix report, and enqueue the verify phase so the audit cycle",
+    "actually closes its loop.",
     "",
-    "**Budget:** Bounded edits to files under `<DOCS_ROOT>` plus a final",
-    "verification re-run of the checks from Phase 1. No new audit",
-    "categories. No fixes that require authoring new content.",
+    "**Budget:** Bounded edits to files under `<DOCS_ROOT>` and one fix",
+    "report file. No new audit categories. No fixes that require",
+    "authoring new content. The formal re-scan lives in Phase 3 \u2014",
+    "Phase 2 confirms only that it did not regress the files it touched",
+    "(a smoke check, not the full pre/post comparison).",
     "",
     "### Fix Categories",
     "",
@@ -4824,11 +4836,13 @@ var maintenanceAuditSubAgent = {
     "   mark it `flag-for-human` and skip. Authoring new docs belongs",
     "   to the writer agent for that doc type, not this agent.",
     "",
-    "5. **Verify.** Re-run the same checks the scan phase ran, scoped",
-    "   to the files the fix phase touched (plus any index files those",
-    "   edits affect). Every finding the fix phase claimed to resolve",
-    "   must now be gone. Any finding that remains is a regression \u2014",
-    "   revert the corresponding edit and mark it `flag-for-human`.",
+    "5. **Smoke check the touched files.** Before writing the fix",
+    "   report, spot-check that the specific findings the fix phase",
+    "   claimed to resolve are at least no longer present in the edited",
+    "   file(s). This is a narrow local check \u2014 not the full re-scan,",
+    "   which is Phase 3's job. If a finding the fix phase targeted",
+    "   still reproduces in the edited file, revert that edit and mark",
+    "   the finding `flag-for-human` in the fix report instead.",
     "",
     "6. **Write the fix report** to:",
     "   ```",
@@ -4859,18 +4873,141 @@ var maintenanceAuditSubAgent = {
     "",
     "   ## Skipped",
     "   <findings that were stale, flagged for human, or reverted",
-    "   during verification \u2014 one entry each, with the reason>",
+    "   during the smoke check \u2014 one entry each, with the reason>",
     "",
-    "   ## Verification",
-    "   - **Re-scan result:** clean / <N> residual findings",
-    "   - **Residual findings:** <list, with reasons \u2014 each becomes a",
-    "     follow-up `flag-for-human` note>",
+    "   ## Paths Touched",
+    "   <ordered list of files edited, plus any index files those edits",
+    "   affect. This is the Phase 3 re-scan scope \u2014 the verify phase",
+    "   reads this section to decide which paths to re-check.>",
     "   ```",
     "",
     "7. **Comment on the scan issue** with a summary of what was fixed,",
-    "   what was skipped, and any residual findings.",
+    "   what was skipped, and that Phase 3 (Verify) will close the loop.",
+    "",
+    "8. **Create the `maint:verify` issue.** Block it on this fix issue",
+    "   via `Depends on: #N` so it only runs after the fix PR lands.",
+    "   The verify issue body must reference:",
+    "   - The parent `maint:scan` issue number",
+    "   - The Phase 1 audit report path",
+    "   - The Phase 2 fix report path",
+    "   - The `Paths Touched` list (so Phase 3 scopes the re-scan",
+    "     correctly)",
+    "   - The same check catalog the scan phase used",
+    "",
+    "   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.",
+    "",
+    "9. **Commit and push.**",
     "",
-    "8. **Commit and push.**",
+    "---",
+    "",
+    "## Phase 3: Verify (`maint:verify`)",
+    "",
+    "**Goal:** Close the loop on the audit cycle. Re-run the same checks",
+    "the scan phase ran, scoped to the paths and registries the fix",
+    "phase actually touched, compare pre and post findings, and record",
+    "the result in a durable verify report.",
+    "",
+    "**Budget:** Filesystem reads + registry parsing, just like Phase 1,",
+    "but bounded to the paths enumerated in the fix report's",
+    "`Paths Touched` section (plus any index files those paths transit).",
+    "No edits to source docs in this phase \u2014 if the re-scan surfaces a",
+    "regression, record it and file a follow-up `maint:scan` issue,",
+    "but do not attempt to re-fix in-session.",
+    "",
+    "### Steps",
+    "",
+    "1. **Read the verify scope** from the issue body. Confirm the parent",
+    "   scan issue number, the audit report path, the fix report path,",
+    "   and the `Paths Touched` list. If any of these are missing or",
+    "   the files they reference do not exist, close the verify issue",
+    "   with `status:needs-attention` and stop.",
+    "",
+    "2. **Re-run the same checks the scan phase ran**, scoped to the",
+    "   paths the fix phase touched plus any index or registry files",
+    "   those paths transit. Use the identical check catalog that the",
+    "   parent scan issue declared \u2014 do not add or remove checks",
+    "   between scan and verify.",
+    "",
+    "3. **Compare pre and post findings.** For each finding in the Phase 1",
+    "   audit report that fell within the re-scan scope, classify it as:",
+    "   - **resolved** \u2014 absent from the re-scan; the fix worked.",
+    "   - **still-failing** \u2014 still present in the re-scan; the fix did",
+    "     not clear it.",
+    "   - **regressed** \u2014 was not in the Phase 1 audit report but appears",
+    "     now; the fix introduced it.",
+    "   - **out-of-scope** \u2014 was in the Phase 1 audit report but its",
+    "     path was not in the fix phase's `Paths Touched` list, so this",
+    "     verify pass cannot speak to it.",
+    "",
+    "4. **Write the verify report** to:",
+    "   ```",
+    "   <AUDIT_ROOT>/maint-verify-<AUDIT_SLUG>-<YYYY-MM-DD>.md",
+    "   ```",
+    "",
+    "   Format:",
+    "   ```markdown",
+    "   ---",
+    '   title: "Maintenance Verify: <AUDIT_SLUG>"',
+    "   date: YYYY-MM-DD",
+    "   parent_issue: <N>",
+    "   scan_issue: <N>",
+    "   fix_issue: <N>",
+    "   audit_report: <path to Phase 1 scan report>",
+    "   fix_report: <path to Phase 2 fix report>",
+    "   status: complete",
+    "   ---",
+    "",
+    "   # Maintenance Verify: <AUDIT_SLUG>",
+    "",
+    "   ## Source Reports",
+    "   - Scan report: <link>",
+    "   - Fix report: <link>",
+    "",
+    "   ## Re-scan Scope",
+    "   - **Paths re-checked:** <list \u2014 from the fix report's",
+    "     `Paths Touched` section>",
+    "   - **Checks re-run:** <same catalog the scan phase used>",
+    "",
+    "   ## Pre/Post Comparison",
+    "   | Status | Count | Findings |",
+    "   |--------|-------|----------|",
+    "   | resolved | N | <one line per finding: category + file:line> |",
+    "   | still-failing | N | <one line per finding> |",
+    "   | regressed | N | <one line per finding> |",
+    "   | out-of-scope | N | <one line per finding> |",
+    "",
+    "   ## Verdict",
+    "   - **clean** \u2014 every in-scope finding resolved and no regressions;",
+    "     the parent scan issue will be closed.",
+    "   - **residual** \u2014 one or more still-failing or regressed findings;",
+    "     a follow-up `maint:scan` issue is filed and the parent scan",
+    "     issue is closed with a reference to the follow-up.",
+    "   ```",
+    "",
+    "5. **Decide the next step:**",
+    "   - **Clean verdict** (every in-scope finding resolved, no",
+    "     regressions, no still-failing entries) \u2192 comment on the parent",
+    "     `maint:scan` issue summarizing the result and **close it**.",
+    "     Do not file a follow-up scan.",
+    "   - **Residual verdict** (one or more `still-failing` or",
+    "     `regressed` entries) \u2192 file a new `maint:scan` issue for the",
+    "     residual scope, blocked on nothing (it is ready to run on its",
+    "     own schedule), and link the verify report from its body. Then",
+    "     comment on the parent scan issue with the residual summary and",
+    "     **close it**.",
+    "   - **Out-of-scope-only verdict** (every finding fell outside the",
+    "     fix phase's `Paths Touched`) \u2192 comment on the parent scan",
+    "     issue explaining that the fix phase did not cover those paths",
+    "     and leave it open with `status:needs-attention` so a human can",
+    "     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.",
     "",
     "---",
     "",
@@ -4880,11 +5017,13 @@ var maintenanceAuditSubAgent = {
     "|-----------|-------|------|",
     "| Downstream (last resort) | Writer agent for the audited doc type | When the audit surfaces findings that require authoring new content (missing target, partial coverage that can only be resolved by writing a new doc), the fix phase flags them for human \u2014 the human may then dispatch the appropriate writer agent. This agent never opens writer-agent issues itself. |",
     "",
-    "**File boundaries:** Writes audit and fix reports to",
+    "**File boundaries:** Writes audit, fix, and verify reports to",
     "`<AUDIT_ROOT>/`. Applies bounded, idempotent edits under",
-    "`<DOCS_ROOT>/` per the fix-policy declared in the fix issue body.",
-    "Never writes to source code, never writes to doc trees outside",
-    "`<DOCS_ROOT>`, never authors new document files to close a gap.",
+    "`<DOCS_ROOT>/` only in Phase 2 (Fix), per the fix-policy declared",
+    "in the fix issue body. Phase 3 (Verify) never edits doc files \u2014",
+    "it only reads and re-scans. Never writes to source code, never",
+    "writes to doc trees outside `<DOCS_ROOT>`, never authors new",
+    "document files to close a gap.",
     "",
     "---",
     "",
@@ -4896,6 +5035,10 @@ var maintenanceAuditSubAgent = {
     "- All findings are `flag-for-human` and the fix issue has nothing",
     "  to auto-apply \u2014 resolve by closing the fix issue with a summary",
     "  instead",
+    "- A `maint:verify` issue references a fix report whose",
+    "  `Paths Touched` list is empty \u2014 there is nothing to re-scan, so",
+    "  close the verify issue with a summary and let a human decide",
+    "  whether to re-run the scan",
     "",
     "---",
     "",
@@ -4910,13 +5053,24 @@ var maintenanceAuditSubAgent = {
     "  Record out-of-scope observations in the report for human review.",
     "- **No authoring.** Do not invent new document content to close a",
     "  finding. That work belongs to the writer agent for the doc type.",
-    "- **Verify before closing.** Always re-run the checks after",
-    "  applying fixes and record the result in the fix report."
+    "- **Verify closes the loop.** Every fix-phase run that lands at",
+    "  least one auto-fix must enqueue a `maint:verify` issue. Phase 3",
+    "  is the only phase that closes the parent `maint:scan` issue.",
+    "  Phase 2 never closes the scan issue itself.",
+    "- **Pre/post comparison is required.** The verify report must",
+    "  classify every in-scope finding from the scan report as",
+    "  `resolved`, `still-failing`, `regressed`, or `out-of-scope`.",
+    "  An unclassified finding means the re-scan was incomplete \u2014 re-",
+    "  run the missing checks before writing the verdict.",
+    "- **Residual findings get their own cycle.** When the verify phase",
+    "  finds `still-failing` or `regressed` entries, file a follow-up",
+    "  `maint:scan` issue rather than attempting to re-fix in-session.",
+    "  The new scan starts its own audit cycle with a fresh report."
   ].join("\n")
 };
 var maintenanceAuditSkill = {
   name: "audit-docs",
-  description: "Kick off a documentation-maintenance audit cycle (scan \u2192 fix). Creates a maint:scan issue for the supplied scope and dispatches Phase 1.",
+  description: "Kick off a documentation-maintenance audit cycle (scan \u2192 fix \u2192 verify). Creates a maint:scan issue for the supplied scope and dispatches Phase 1.",
   disableModelInvocation: true,
   userInvocable: true,
   context: "fork",
@@ -4928,7 +5082,8 @@ var maintenanceAuditSkill = {
     "Kick off a maintenance-audit cycle against a configurable doc",
     "tree. Creates a `maint:scan` issue targeted at the requested",
     "scope and dispatches Phase 1 (Scan) in the maintenance-audit",
-    "agent.",
+    "agent. Subsequent phases (`maint:fix`, `maint:verify`) are",
+    "created automatically as the cycle progresses.",
     "",
     "## Usage",
     "",
@@ -4955,30 +5110,102 @@ var maintenanceAuditSkill = {
     "2. Execute Phase 1 (Scan) of the maintenance-audit agent.",
     "3. If auto-fixable findings exist, a `maint:fix` issue is created",
     "   automatically.",
+    "4. When the fix phase lands, a `maint:verify` issue is created",
+    "   automatically so Phase 3 can re-run the checks and close the",
+    "   parent scan issue.",
     "",
     "## Output",
     "",
     "- A `maint-audit-<slug>-<YYYY-MM-DD>.md` report under",
     "  `<AUDIT_ROOT>`.",
-    "- A `maint:fix` issue if auto-fixable findings were found."
+    "- A `maint:fix` issue if auto-fixable findings were found.",
+    "- A `maint:verify` issue after the fix phase lands (Phase 3",
+    "  produces a `maint-verify-<slug>-<YYYY-MM-DD>.md` report)."
+  ].join("\n")
+};
+var maintenanceVerifySkill = {
+  name: "verify-audit",
+  description: "Kick off the verify phase of a documentation-maintenance audit cycle. Creates a maint:verify issue that re-runs the scan checks scoped to the paths a fix phase touched, compares pre/post findings, and closes the parent maint:scan issue when clean or files a follow-up maint:scan for residual findings.",
+  disableModelInvocation: true,
+  userInvocable: true,
+  context: "fork",
+  agent: "maintenance-audit",
+  platforms: { cursor: { exclude: true } },
+  instructions: [
+    "# Verify Audit",
+    "",
+    "Close the loop on a maintenance-audit cycle. Creates a",
+    "`maint:verify` issue and dispatches Phase 3 (Verify) in the",
+    "maintenance-audit agent.",
+    "",
+    "Phase 3 re-runs the same checks the scan phase ran, scoped to the",
+    "paths the fix phase actually touched, compares pre and post",
+    "findings, and writes a verify report. Based on the verdict the",
+    "phase either closes the parent `maint:scan` issue or files a",
+    "follow-up `maint:scan` for residual findings.",
+    "",
+    "## Usage",
+    "",
+    "/verify-audit <scan-issue-number>",
+    "",
+    "Where `<scan-issue-number>` is the `maint:scan` issue that kicked",
+    "off the audit cycle. The skill resolves the scan report, the",
+    "Phase 2 fix report, and the `Paths Touched` list from that scan",
+    "issue's downstream `maint:fix` issue.",
+    "",
+    "Most cycles do not need this skill \u2014 Phase 2 (Fix) creates the",
+    "verify issue automatically. Use this skill when:",
+    "- Phase 2 ran on an older audit cycle that predates the verify",
+    "  phase and never enqueued a verify issue, or",
+    "- A human wants to re-run the verify phase after a manual fix",
+    "  applied on top of the Phase 2 PR.",
+    "",
+    "## Steps",
+    "",
+    "1. Create a `maint:verify` issue with `type:maintenance`,",
+    "   `priority:medium`, and `status:ready`. Body must list:",
+    "   - The parent `maint:scan` issue number",
+    "   - The Phase 1 audit report path",
+    "   - The Phase 2 fix report path (if one exists)",
+    "   - The `Paths Touched` list (copied from the fix report)",
+    "   - The audit check catalog (copied from the scan issue)",
+    "2. Execute Phase 3 (Verify) of the maintenance-audit agent.",
+    "",
+    "## Output",
+    "",
+    "- A `maint-verify-<slug>-<YYYY-MM-DD>.md` report under",
+    "  `<AUDIT_ROOT>` containing the pre/post comparison.",
+    "- The parent `maint:scan` issue is closed (clean verdict) or a",
+    "  follow-up `maint:scan` issue is filed (residual verdict)."
   ].join("\n")
 };
 var maintenanceAuditBundle = {
   name: "maintenance-audit",
-  description: "Documentation-maintenance agent bundle. 2-phase pipeline (scan, fix) with maint:* phase labels for auditing registries and cross-references and applying idempotent fixes. Enabled by default.",
+  description: "Documentation-maintenance agent bundle. 3-phase pipeline (scan, fix, verify) with maint:* phase labels for auditing registries and cross-references, applying idempotent fixes, and confirming the fixes cleared the originally-flagged findings. Enabled by default.",
   appliesWhen: () => true,
   rules: [
     {
       name: "maintenance-audit-workflow",
-      description: "Describes the 2-phase documentation-maintenance pipeline, the maint:* label taxonomy, and the audit-before-fix boundary.",
+      description: "Describes the 3-phase documentation-maintenance pipeline, the maint:* label taxonomy, the audit-before-fix boundary, and the verify-closes-the-loop rule.",
       scope: AGENT_RULE_SCOPE.ALWAYS,
       content: [
         "# Maintenance Audit Workflow",
         "",
         "Use `/audit-docs <scope>` to kick off a documentation-maintenance",
-        "audit cycle. The pipeline runs in 2 phases \u2014 scan and fix \u2014 each",
-        "tracked by its own GitHub issue labeled `maint:scan` or",
-        "`maint:fix`. All issues carry `type:maintenance`.",
+        "audit cycle. The pipeline runs in 3 phases \u2014 scan, fix, and",
+        "verify \u2014 each tracked by its own GitHub issue labeled",
+        "`maint:scan`, `maint:fix`, or `maint:verify`. All issues carry",
+        "`type:maintenance`.",
+        "",
+        "One additional user-invocable skill drives the verify phase",
+        "on demand:",
+        "",
+        "- `/verify-audit <scan-issue-number>` \u2014 re-run the scan checks",
+        "  scoped to the paths the fix phase touched, compare pre/post",
+        "  findings, and close the parent `maint:scan` issue (or file a",
+        "  follow-up for residual findings). Phase 2 (Fix) normally",
+        "  enqueues the verify issue automatically \u2014 this skill is the",
+        "  explicit entry point for re-running the phase on demand.",
         "",
         "The maintenance-audit agent *audits doc registries and applies",
         "idempotent fixes*; it does **not** author new document content.",
@@ -4994,7 +5221,7 @@ var maintenanceAuditBundle = {
       tags: ["workflow"]
     }
   ],
-  skills: [maintenanceAuditSkill],
+  skills: [maintenanceAuditSkill, maintenanceVerifySkill],
   subAgents: [maintenanceAuditSubAgent],
   labels: [
     {
@@ -5011,6 +5238,11 @@ var maintenanceAuditBundle = {
       name: "maint:fix",
       color: "BFDADC",
       description: "Phase 2: apply idempotent fixes from a maintenance audit report"
+    },
+    {
+      name: "maint:verify",
+      color: "D4C5F9",
+      description: "Phase 3: re-run the scan checks scoped to the paths the fix phase touched, compare pre/post findings, and close or re-queue the parent scan"
     }
   ]
 };