@codedrifters/configulator 0.0.259 → 0.0.261

package/lib/index.mjs

@@ -4445,7 +4445,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 } },
@@ -4503,18 +4503,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:**",
@@ -4522,18 +4522,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**.",
     "",
     "---",
     "",
@@ -4563,7 +4567,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:*`",
@@ -4675,24 +4681,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",
     "",
@@ -4726,11 +4738,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:",
     "   ```",
@@ -4761,18 +4775,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.",
     "",
     "---",
     "",
@@ -4782,11 +4919,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.",
     "",
     "---",
     "",
@@ -4798,6 +4937,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",
     "",
     "---",
     "",
@@ -4812,13 +4955,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",
@@ -4830,7 +4984,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",
     "",
@@ -4857,30 +5012,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.",
@@ -4896,7 +5123,7 @@ var maintenanceAuditBundle = {
       tags: ["workflow"]
     }
   ],
-  skills: [maintenanceAuditSkill],
+  skills: [maintenanceAuditSkill, maintenanceVerifySkill],
   subAgents: [maintenanceAuditSubAgent],
   labels: [
     {
@@ -4913,6 +5140,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"
     }
   ]
 };
@@ -6173,7 +6405,7 @@ var orchestratorBundle = {
 // src/agent/bundles/people-profile.ts
 var peopleProfileAnalystSubAgent = {
   name: "people-profile-analyst",
-  description: "Researches an individual person (colleague, customer contact, vendor contact, partner contact, industry expert, or connector) from public sources and produces a structured markdown profile cross-linked to companies, software, and meeting notes, then enqueues downstream `company:research` and `software:research` issues for unprofiled companies and software products surfaced during profiling. One person per session, tracked by people:* GitHub issue labels.",
+  description: "Researches an individual person (colleague, customer contact, vendor contact, partner contact, industry expert, or connector) from public sources and produces a structured markdown profile cross-linked to companies, software, and meeting notes, then enqueues downstream `company:research` and `software:research` issues for unprofiled companies and software products surfaced during profiling. Also handles maintenance refreshes on a configurable staleness cadence (`people:refresh`). One person per session, tracked by people:* GitHub issue labels.",
   model: AGENT_MODEL.POWERFUL,
   maxTurns: 80,
   platforms: { cursor: { exclude: true } },
@@ -6233,6 +6465,12 @@ var peopleProfileAnalystSubAgent = {
     "   the `software-profile` bundle via `software:research` issues.",
     "   Meeting notes remain link-only \u2014 this agent never creates",
     "   meeting-research issues.",
+    "9. **Refresh is targeted re-verification, not re-research.**",
+    "   `people:refresh` runs a small number of targeted searches focused",
+    "   on the narrow set of facts that drift (role, employer, primary",
+    "   public channel) and updates the profile in place. It never",
+    "   re-runs the full research-phase sweep and never forks the profile",
+    "   under a new slug.",
     "",
     "---",
     "",
@@ -6267,6 +6505,15 @@ var peopleProfileAnalystSubAgent = {
     "\u2502 bounded notes     \u2502     \u2502 the configured path  \u2502     \u2502 company/software   \u2502",
     "\u2502 file              \u2502     \u2502                      \u2502     \u2502 research issues    \u2502",
     "\u2514\u2500\u2500\u2500\u2500\u2500\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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\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\u2500\u2500\u2500\u2500\u2500\u2510",
+    "\u2502 4. REFRESH        \u2502  (cadence-driven, or on-demand)",
+    "\u2502 Re-verify an      \u2502",
+    "\u2502 existing profile  \u2502",
+    "\u2502 with targeted web \u2502",
+    "\u2502 searches. Update  \u2502",
+    "\u2502 in place.         \u2502",
+    "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
     "```",
     "",
     "**Issue labels encode the phase:**",
@@ -6276,13 +6523,13 @@ var peopleProfileAnalystSubAgent = {
     "| `people:research` | 1. Research | Gather public sources. Write a bounded research-notes file. Create the draft issue. |",
     "| `people:draft` | 2. Draft | Read the research notes. Write the structured profile to `<PROFILES_DIR>`. Create the followup issue if warranted. |",
     "| `people:followup` | 3. Followup | Read the profile. Update cross-references to existing companies, software, and meeting notes. Enqueue `company:research` and `software:research` issues for unprofiled, genuinely-relevant entities surfaced in the profile. |",
+    "| `people:refresh` | 4. Refresh | Read an existing profile. Run 3\u20135 targeted web searches for role, employer, and primary public channel changes. Update the profile in place and add a revision-history entry. |",
     "",
     "All issues also carry `type:people-profile` and a `status:*` label.",
     "",
     "**Issue count per person cycle:** 1 research + 1 draft + 0\u20131 followup =",
-    "**2\u20133 sessions**. The followup phase is skipped when the profile did",
-    "not surface any cross-references worth linking and no companies or",
-    "software products warrant downstream research.",
+    "**2\u20133 sessions** on the initial cycle. `people:refresh` is an",
+    "independent downstream cycle that runs on its own cadence.",
     "",
     "**Shortened paths:**",
     "- Research phase determines the person is out of scope (not",
@@ -6290,14 +6537,17 @@ var peopleProfileAnalystSubAgent = {
     "  with a justification and no downstream issues are created \u2192 **1 session**.",
     "- Short profile with no cross-references and no downstream",
     "  candidates \u2192 **2 sessions**.",
+    "- Refresh that finds no material change \u2192 **1 session** (revision-",
+    "  history entry only, profile body unchanged).",
     "",
     "---",
     "",
     "## Configurable Paths",
     "",
     "The pipeline uses these placeholders. Consuming projects override the",
-    "defaults by passing paths in the `/profile-person` skill invocation",
-    "or by extending this rule in their own `agentConfig.rules`.",
+    "defaults by passing paths in the `/profile-person` or `/refresh-person`",
+    "skill invocations, or by extending this rule in their own",
+    "`agentConfig.rules`.",
     "",
     "| Placeholder | Meaning | Default |",
     "|-------------|---------|---------|",
@@ -6319,26 +6569,37 @@ var peopleProfileAnalystSubAgent = {
     "## Refresh Cadence",
     "",
     "Profiles go stale. A person changes jobs, publishes new work, or",
-    "shifts focus. The pipeline supports a configurable refresh cadence:",
+    "shifts focus. The pipeline supports a configurable refresh cadence",
+    "so `people:refresh` issues can be filed on a schedule without",
+    "hardcoding the interval:",
     "",
-    "- **Default cadence:** 180 days from the profile's `date` frontmatter.",
-    "- **Override:** the invoking issue body may specify a `refresh_days: N`",
-    "  field, or the consuming project may set a project-wide default in",
-    "  `docs/src/content/docs/project-context.md`.",
+    "- **Default staleness threshold:** 180 days from the profile's",
+    "  `date` frontmatter.",
+    "- **Override precedence** (first match wins):",
+    "  1. `refresh_days` in the issue body (per-run override)",
+    "  2. `refresh_days` frontmatter on the profile itself",
+    "  3. Project-wide default declared under a `## Refresh Cadence`",
+    "     section in `docs/src/content/docs/project-context.md`",
+    "  4. Built-in default: **180 days**",
     "",
-    "When the `/profile-person` skill is invoked for a slug that already",
-    "has a profile:",
+    "When the `/refresh-person` skill is invoked for an existing profile:",
     "",
-    "- If the profile is **younger** than the refresh cadence, the skill",
-    "  exits with a message pointing to the existing profile. Pass",
+    "- If the profile is **younger** than the staleness threshold, the",
+    "  skill exits with a message pointing to the existing profile. Pass",
     "  `force: true` in the issue body to refresh anyway.",
-    "- If the profile is **older** than the refresh cadence, the pipeline",
-    "  proceeds in update-in-place mode: Phase 2 edits the existing file,",
-    "  preserves its slug, and bumps the `date` frontmatter.",
+    "- If the profile is **older** than the staleness threshold, the",
+    "  pipeline files a `people:refresh` issue and Phase 4 updates the",
+    "  existing file in place, preserving its slug and bumping the",
+    "  `date` frontmatter.",
+    "",
+    "The same precedence and `force: true` semantics apply when",
+    "`/profile-person` is invoked for a slug that already has a profile:",
+    "a fresh profile short-circuits; a stale profile is updated in place",
+    "by Phase 2 rather than forked under a new slug.",
     "",
     "Refresh mode never changes the profile's role without an explicit",
-    "override in the refresh request \u2014 role changes are material and",
-    "warrant a human review step.",
+    "override in the refresh request (`retype: <role>`) \u2014 role changes",
+    "are material and warrant a human review step.",
     "",
     "---",
     "",
@@ -6347,7 +6608,8 @@ var peopleProfileAnalystSubAgent = {
     "Run this loop exactly once per session. Never start a second issue.",
     "",
     "1. Claim one open `type:people-profile` issue using phase priority:",
-    "   `people:research` > `people:draft` > `people:followup`.",
+    "   `people:research` > `people:draft` > `people:followup` >",
+    "   `people:refresh`.",
     "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 `people:*`",
@@ -6515,6 +6777,11 @@ var peopleProfileAnalystSubAgent = {
     "   <what the profile could not answer; flag anything the followup",
     "   phase should cross-reference>",
     "",
+    "   ## Revision History",
+    "   | Date | Changes |",
+    "   |------|---------|",
+    "   | YYYY-MM-DD | Initial profile |",
+    "",
     "   ## Sources",
     "   - <source URL> \u2014 <date accessed>",
     "   ```",
@@ -6660,12 +6927,87 @@ var peopleProfileAnalystSubAgent = {
     "",
     "---",
     "",
+    "## Phase 4: Refresh (`people:refresh`)",
+    "",
+    "**Goal:** Re-verify an existing profile against a narrow set of facts",
+    "that tend to drift \u2014 current role, current employer, primary public",
+    "channel (email, handle, personal site) \u2014 with a small number of",
+    "targeted web searches, then update the profile in place.",
+    "",
+    "**Budget:** 3\u20135 targeted web searches focused on the narrow delta",
+    "set. Do not redo the full research-phase sweep, do not re-gather the",
+    "full background, and do not rewrite the profile body for facts that",
+    "have not changed.",
+    "",
+    "### Steps",
+    "",
+    "1. **Read the existing profile** at the path referenced in the issue",
+    "   body. If the profile file is missing, close the issue with",
+    "   `status:needs-attention` and stop.",
+    "",
+    "2. **Confirm the staleness threshold.** Compare the profile's `date`",
+    "   frontmatter against today's date and the `refresh_days`",
+    "   frontmatter (or the project default from the Refresh Cadence",
+    "   section above). If the profile is younger than the threshold and",
+    "   the issue body does not set `force: true`, close the issue with",
+    "   a short comment and stop \u2014 do not burn the search budget.",
+    "",
+    "3. **Run 3\u20135 targeted searches.** Focus on the narrow delta set:",
+    "   - Current role / title at the current employer",
+    "   - Current employer (has the person changed jobs?)",
+    "   - Primary public channel (personal site URL, primary social",
+    "     handle, speaker inquiry form, public email if listed)",
+    "   - Optional: one search for notable recent public work (a new",
+    "     talk, post, or project) if the profile's Expertise Signals",
+    "     section has no entry from the last 12 months",
+    "",
+    "4. **Update the profile in place.** Edit only the affected sections",
+    "   (typically `## Current Position`, `## Contact Preferences`, and",
+    "   occasionally `## Expertise Signals`). Cite every new claim.",
+    "   Preserve the slug and the original `parent_issue` field. Bump the",
+    "   `date` frontmatter to today's date. Leave untouched sections",
+    "   untouched \u2014 refresh is a narrow delta, not a rewrite.",
+    "",
+    "5. **Do not silently re-type the person.** If the refresh surfaces",
+    "   evidence that the person's primary role has changed (e.g., a",
+    "   customer-contact who now works at your own organization and",
+    "   should become a colleague), flag it in `## Risks / Open Questions`",
+    "   and stop \u2014 do **not** rewrite the `role` frontmatter without an",
+    "   explicit override in the refresh issue body (`retype: <role>`).",
+    "",
+    "6. **Append a revision-history row.** Summarize the delta in one",
+    "   line:",
+    "",
+    "   ```markdown",
+    "   | YYYY-MM-DD | Refreshed: <one-line summary of what changed> |",
+    "   ```",
+    "",
+    "   When the search budget finds no material change, the row still",
+    "   appears so the next scheduled refresh knows this profile was",
+    "   reviewed:",
+    "",
+    "   ```markdown",
+    "   | YYYY-MM-DD | Refreshed: no material change |",
+    "   ```",
+    "",
+    "7. **Respect privacy.** The narrow delta set is bounded to public",
+    "   professional facts. Never expand the refresh into private contact",
+    "   details, family information, or other non-professional data \u2014",
+    "   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`).",
+    "",
+    "---",
+    "",
     "## Output Boundaries",
     "",
     "This agent writes **only** to:",
     "",
     "- `<NOTES_DIR>/` \u2014 research-notes files (Phase 1)",
-    "- `<PROFILES_DIR>/` \u2014 person profiles (Phase 2, updated in Phase 3)",
+    "- `<PROFILES_DIR>/` \u2014 person profiles (Phase 2, updated in Phases",
+    "  3 and 4)",
     "",
     "In Phase 3, this agent also **creates `company:research` and",
     "`software:research` issues** for companies and software products",
@@ -6676,6 +7018,13 @@ var peopleProfileAnalystSubAgent = {
     "which pick up the issues this pipeline creates. Meeting notes",
     "remain link-only across all phases.",
     "",
+    "In Phase 4, this agent only updates an existing profile in place \u2014",
+    "it never forks a new profile under a different slug and never",
+    "enqueues downstream `company:research` or `software:research`",
+    "issues. Cross-references surfaced during a refresh are flagged in",
+    "`## Risks / Open Questions` for a follow-up `people:followup` pass",
+    "to handle.",
+    "",
     "The pipeline produces **person profiles and notes only**. Deeper",
     "research on companies and software products is delegated to",
     "downstream research pipelines via `company:research` and",
@@ -6720,6 +7069,15 @@ var peopleProfileAnalystSubAgent = {
     "  not open `type:requirement` or formal evaluation issues from this",
     "  pipeline. Follow-up research is scoped through `company:research`",
     "  and `software:research` only.",
+    "- **Refresh respects the cadence.** Phase 4 exits early when the",
+    "  profile is younger than the staleness threshold and `force: true`",
+    "  is not set. It always appends a revision-history row so the next",
+    "  scheduled run knows the profile was reviewed.",
+    "- **Refresh is narrow, not a rewrite.** Phase 4 re-verifies role,",
+    "  employer, and primary public channel with 3\u20135 targeted searches",
+    "  and updates only the affected sections. It never re-runs the full",
+    "  research-phase sweep and never rewrites sections whose underlying",
+    "  facts have not changed.",
     "- **Refresh, don't fork.** When a profile exists and is past its",
     "  cadence, update in place rather than creating a new slug."
   ].join("\n")
@@ -6798,23 +7156,110 @@ var profilePersonSkill = {
     "  other downstream artifacts itself."
   ].join("\n")
 };
+var refreshPersonSkill = {
+  name: "refresh-person",
+  description: "Kick off a people-profile refresh cycle. Creates a people:refresh issue for an existing profile and dispatches Phase 4 (Refresh) in the people-profile-analyst agent. Refresh re-verifies the profile's narrow delta set (role, employer, primary public channel) with 3\u20135 targeted web searches and updates it in place. Respects a configurable staleness threshold so profiles younger than the threshold exit early.",
+  disableModelInvocation: true,
+  userInvocable: true,
+  context: "fork",
+  agent: "people-profile-analyst",
+  platforms: { cursor: { exclude: true } },
+  instructions: [
+    "# Refresh Person",
+    "",
+    "Re-verify an existing person profile with a small number of",
+    "targeted web searches and update the profile in place. Creates a",
+    "`people:refresh` issue for the target profile and dispatches",
+    "Phase 4 (Refresh) in the people-profile-analyst agent.",
+    "",
+    "Refresh respects a configurable **staleness threshold** so scheduled",
+    "refreshes do not burn search budget on profiles that are still",
+    "fresh.",
+    "",
+    "## Usage",
+    "",
+    "/refresh-person <path-to-profile>",
+    "",
+    "Optional extensions in the issue body:",
+    "- `refresh_days: <N>` \u2014 override the default 180-day staleness",
+    "  threshold for this run",
+    "- `force: true` \u2014 refresh even if the profile is younger than the",
+    "  threshold",
+    "- `retype: <colleague | customer-contact | vendor-contact |",
+    "   partner-contact | industry-expert | connector>` \u2014 explicitly",
+    "   allow Phase 4 to change the profile's `role` when the refresh",
+    "   finds material evidence of a role-type change",
+    "",
+    "## Staleness Threshold",
+    "",
+    "Order of precedence (first match wins):",
+    "",
+    "1. `refresh_days` in the issue body (per-run override)",
+    "2. `refresh_days` frontmatter on the profile itself",
+    "3. Project-wide default declared under a `## Refresh Cadence`",
+    "   section in `docs/src/content/docs/project-context.md`",
+    "4. Built-in default: **180 days**",
+    "",
+    "If the profile's `date` frontmatter plus the resolved threshold is",
+    "in the future (i.e. the profile is still fresh) and `force: true`",
+    "is not set, Phase 4 closes the refresh issue with a short comment",
+    "and stops without running any searches.",
+    "",
+    "## Budget",
+    "",
+    "- **3\u20135 targeted web searches** focused on the narrow delta set:",
+    "  current role / title, current employer, primary public channel",
+    "  (personal site, handle, speaker inquiry form, public email).",
+    "- Optional: one search for notable recent public work if the",
+    "  profile has no Expertise Signals entry from the last 12 months.",
+    "",
+    "## Privacy",
+    "",
+    "Privacy guardrails from Phase 1 apply to every refresh. Never",
+    "record private contact details, family information, or other",
+    "non-professional personal data \u2014 even if a search surfaces them.",
+    "",
+    "## Steps",
+    "",
+    "1. Create a `people:refresh` issue with `type:people-profile`,",
+    "   `priority:medium`, and `status:ready`. Body must include the",
+    "   profile path and any overrides.",
+    "2. Execute Phase 4 (Refresh) of the people-profile-analyst agent.",
+    "",
+    "## Output",
+    "",
+    "- The profile is updated in place (affected sections edited,",
+    "  `date` bumped, slug preserved)",
+    "- A revision-history row summarizing the delta \u2014 or",
+    "  `Refreshed: no material change` when the search budget found",
+    "  nothing material"
+  ].join("\n")
+};
 var peopleProfileBundle = {
   name: "people-profile",
-  description: "People research and profiling pipeline: research, draft profile, followup. Enabled by default; domain-neutral; filesystem-durable between phases. Cross-references existing companies, software, and meeting notes, and Phase 3 (Followup) hands unprofiled, genuinely-relevant companies and software products off to the `company-profile` and `software-profile` bundles via `company:research` and `software:research` issues.",
+  description: "People research and profiling pipeline: research, draft profile, followup, refresh. Enabled by default; domain-neutral; filesystem-durable between phases. Cross-references existing companies, software, and meeting notes, and Phase 3 (Followup) hands unprofiled, genuinely-relevant companies and software products off to the `company-profile` and `software-profile` bundles via `company:research` and `software:research` issues. Phase 4 (Refresh) re-verifies profiles on a configurable staleness cadence.",
   appliesWhen: () => true,
   rules: [
     {
       name: "people-profile-workflow",
-      description: "Describes the 3-phase people-profile pipeline, the people:* label taxonomy, the cross-reference model, and the boundary against downstream research agents.",
+      description: "Describes the 4-phase people-profile pipeline, the people:* label taxonomy, the cross-reference model, the refresh cadence rules, and the boundary against downstream research agents.",
       scope: AGENT_RULE_SCOPE.ALWAYS,
       content: [
         "# People Profile Workflow",
         "",
         "Use `/profile-person <person-name>` to kick off a person",
-        "research and profiling pipeline. The pipeline runs in up to 3",
-        "phases \u2014 research, draft, followup \u2014 each tracked by its own",
-        "GitHub issue labeled `people:research`, `people:draft`, or",
-        "`people:followup`. All issues carry `type:people-profile`.",
+        "research and profiling pipeline. The pipeline runs in up to 4",
+        "phases \u2014 research, draft, followup, refresh \u2014 each tracked by",
+        "its own GitHub issue labeled `people:research`, `people:draft`,",
+        "`people:followup`, or `people:refresh`. All issues carry",
+        "`type:people-profile`.",
+        "",
+        "One additional user-invocable skill drives the maintenance",
+        "phase independently:",
+        "",
+        "- `/refresh-person <path-to-profile>` \u2014 re-verify an existing",
+        "  profile with 3\u20135 targeted web searches and update it in",
+        "  place (Phase 4, respects a configurable staleness threshold).",
         "",
         "The pipeline produces **person profiles only**. Deeper research",
         "on companies and software products surfaced while profiling is",
@@ -6833,7 +7278,7 @@ var peopleProfileBundle = {
       tags: ["workflow"]
     }
   ],
-  skills: [profilePersonSkill],
+  skills: [profilePersonSkill, refreshPersonSkill],
   subAgents: [peopleProfileAnalystSubAgent],
   labels: [
     {
@@ -6855,6 +7300,11 @@ var peopleProfileBundle = {
       name: "people:followup",
       color: "D4C5F9",
       description: "Phase 3: cross-link the profile to existing companies, software, and meeting notes, and enqueue follow-up research issues for unprofiled companies and software products"
+    },
+    {
+      name: "people:refresh",
+      color: "F9D0C4",
+      description: "Phase 4: re-verify an existing person profile with targeted web searches and update it in place"
     }
   ]
 };