@codedrifters/configulator 0.0.209 → 0.0.210

package/lib/index.mjs

@@ -2822,6 +2822,481 @@ 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.",
+  model: AGENT_MODEL.POWERFUL,
+  maxTurns: 80,
+  platforms: { cursor: { exclude: true } },
+  prompt: [
+    "# Maintenance Audit Agent",
+    "",
+    "Generic documentation-maintenance pipeline. Given a set of",
+    "configurable documentation directories (registries, cross-reference",
+    "trees, index files), you perform an **audit-then-fix** cycle: scan",
+    "for broken cross-references, registry drift, and stale indexes;",
+    "produce an audit report; apply idempotent fixes. Each phase runs",
+    "as its **own agent session**, triggered by a GitHub issue with a",
+    "`maint:*` phase label. You handle exactly **one phase per session**",
+    "\u2014 read the issue to determine which phase to execute.",
+    "",
+    "This agent is **domain-neutral**. It makes no assumptions about",
+    "what the documentation covers (requirements, ADRs, capability",
+    "models, research notes, profiles, product specs, etc.). All",
+    "domain-specific vocabulary, doc paths, registry formats, and fix",
+    "policies come from the invoking issue body or the consuming",
+    "project's configuration.",
+    "",
+    "Follow your project's shared agent conventions (`AGENTS.md`,",
+    "`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
+    "",
+    "---",
+    "",
+    ...PROJECT_CONTEXT_READER_SECTION,
+    "## Design Principles",
+    "",
+    "1. **Audit before fix.** Every cycle begins with a scan that writes",
+    "   a durable report. No fixes are applied until Phase 2 reads that",
+    "   report.",
+    "2. **Idempotent fixes only.** Every fix must be safe to re-run.",
+    "   Prefer removing stale entries, re-generating indexes from",
+    "   authoritative sources, and normalizing link targets. Never",
+    "   invent content to fill gaps \u2014 that is authoring work and",
+    "   belongs to the downstream writer agent for that doc type.",
+    "3. **Filesystem durability.** Phase 1 persists its report to disk",
+    "   before closing its issue. Phase 2 reads that file \u2014 never rely",
+    "   on session memory.",
+    "4. **Issue graph = state machine.** Phase ordering is encoded with",
+    "   `Depends on: #N` links between phase issues. The fix phase runs",
+    "   only after the scan phase is closed.",
+    "5. **Bounded scope.** The audit scope for each cycle is declared in",
+    "   the scan issue body. Do not expand scope mid-session \u2014 if you",
+    "   discover additional doc trees that need auditing, note them in",
+    "   the report and let a human decide whether to queue a follow-up",
+    "   cycle.",
+    "6. **Generic over specific.** No hardcoded domains, companies,",
+    "   source projects, or proprietary taxonomies. Use placeholders",
+    "   that the skill invocation or consuming project fills in.",
+    "",
+    "---",
+    "",
+    "## State Machine Overview",
+    "",
+    "Maintenance audits flow through **2 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",
+    "```",
+    "",
+    "**Issue labels encode the phase:**",
+    "",
+    "| 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. |",
+    "",
+    "All issues also carry `type:maintenance` and a `status:*` label.",
+    "",
+    "**Issue count per audit cycle:** 1 scan + 1 fix = **2 sessions**.",
+    "",
+    "**Shortened paths:**",
+    "- Scan finds no issues \u2192 close scan issue with a justification,",
+    "  do not create a fix 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**.",
+    "",
+    "---",
+    "",
+    "## Configurable Paths",
+    "",
+    "Projects adopting this bundle must define these paths in their",
+    "agent configuration (`agentConfig.rules` extension or project-level",
+    "docs) or in each scan issue body. The agent never hardcodes paths.",
+    "",
+    "| Placeholder | Meaning | Example |",
+    "|-------------|---------|---------|",
+    "| `<DOCS_ROOT>` | Root of the doc tree being audited | `docs/requirements/`, `docs/adrs/`, `docs/bcm/` |",
+    "| `<REGISTRY_INDEX>` | Registry or index file to check for drift | `<DOCS_ROOT>/_index.md`, `<DOCS_ROOT>/README.md` |",
+    "| `<AUDIT_ROOT>` | Where audit reports are written | `docs/maintenance/` |",
+    "| `<AUDIT_SLUG>` | Short identifier for this audit scope | e.g. `requirements-xrefs`, `adr-registry`, `bcm-traceability` |",
+    "| `<FIX_POLICY>` | Which fix categories to auto-apply vs. flag | e.g. `auto: prune-stale-index, normalize-links; flag: missing-target` |",
+    "",
+    "If your project stores these in different locations, substitute",
+    "accordingly wherever the phase instructions reference a path. The",
+    "agent reads the scan issue body to determine which scope is being",
+    "audited in this cycle.",
+    "",
+    "---",
+    "",
+    "## Agent Loop",
+    "",
+    "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`.",
+    "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:*`",
+    "   label.",
+    "4. Commit, push, open a PR (if applicable), and close the issue per",
+    "   your project's PR workflow.",
+    "",
+    "---",
+    "",
+    "## Phase 1: Scan (`maint:scan`)",
+    "",
+    "**Goal:** Walk the configured doc tree, check every cross-reference",
+    "and registry index, and produce a durable audit report listing",
+    "every finding.",
+    "",
+    "**Budget:** Filesystem reads + registry parsing. Write one audit",
+    "report file. No edits to source docs in this phase.",
+    "",
+    "### Audit Checks",
+    "",
+    "The scan issue body declares which checks to run. Default check",
+    "catalog:",
+    "",
+    "| Check | What it detects |",
+    "|-------|-----------------|",
+    "| **Broken xref** | A markdown link or relative path in a doc points to a file or anchor that does not exist under `<DOCS_ROOT>`. |",
+    "| **Orphaned doc** | A doc file exists under `<DOCS_ROOT>` but is not referenced by any registry, index, or parent doc. |",
+    "| **Registry drift** | A `<REGISTRY_INDEX>` lists a doc that no longer exists, or omits a doc that does exist. |",
+    "| **Stale index** | An index file is older than the most recently modified doc it indexes, or lists entries in an outdated order. |",
+    "| **Duplicate ID** | Two docs claim the same identifier (e.g. both `FOO-007`), violating the registry's ID uniqueness rule. |",
+    "| **Missing traceability** | A doc declares a `Traceability` or `Related` section but one or more listed targets do not exist. |",
+    "| **Dangling backlink** | A doc is referenced from elsewhere but its own Traceability section does not link back. |",
+    "",
+    "Additional project-specific checks can be supplied in the issue",
+    "body. Only run the checks the issue enumerates \u2014 do not invent new",
+    "categories mid-scan.",
+    "",
+    "### Steps",
+    "",
+    "1. **Read the scan scope** from the issue body. Confirm",
+    "   `<DOCS_ROOT>`, the checks to run, and the output path for the",
+    "   audit report.",
+    "",
+    "2. **Walk the doc tree.** Enumerate every file under `<DOCS_ROOT>`",
+    "   that matches the doc-extension convention (typically `*.md`).",
+    "",
+    "3. **Run each declared check.** For each finding, capture:",
+    "   - The check category (from the catalog above)",
+    "   - The source file path and line (if applicable)",
+    "   - The target that triggered the finding (broken link target,",
+    "     orphaned doc path, drifted registry entry, etc.)",
+    "   - A suggested fix category (`prune`, `normalize`, `regenerate`,",
+    "     `flag-for-human`)",
+    "",
+    "4. **Write the audit report** to:",
+    "   ```",
+    "   <AUDIT_ROOT>/maint-audit-<AUDIT_SLUG>-<YYYY-MM-DD>.md",
+    "   ```",
+    "",
+    "   Format:",
+    "   ```markdown",
+    "   ---",
+    '   title: "Maintenance Audit: <AUDIT_SLUG>"',
+    "   date: YYYY-MM-DD",
+    "   parent_issue: <N>",
+    "   status: complete",
+    "   ---",
+    "",
+    "   # Maintenance Audit: <AUDIT_SLUG>",
+    "",
+    "   ## Scope",
+    "   - **Docs root:** `<DOCS_ROOT>`",
+    "   - **Checks run:** <list of check categories>",
+    "   - **Files scanned:** <count>",
+    "",
+    "   ## Findings Summary",
+    "   | Category | Count | Auto-fixable | Needs human |",
+    "   |----------|-------|--------------|-------------|",
+    "   | Broken xref | N | N | N |",
+    "   | Orphaned doc | N | N | N |",
+    "   | Registry drift | N | N | N |",
+    "   | Stale index | N | N | N |",
+    "   | Duplicate ID | N | N | N |",
+    "   | Missing traceability | N | N | N |",
+    "   | Dangling backlink | N | N | N |",
+    "",
+    "   ## Findings",
+    "",
+    "   ### Finding 1: <category> \u2014 <short description>",
+    "   - **File:** <path>:<line>",
+    "   - **Target:** <broken target or drifted entry>",
+    "   - **Suggested fix:** prune / normalize / regenerate / flag-for-human",
+    "   - **Notes:** <any context that helps the fix phase>",
+    "",
+    "   ## Findings Requiring Human Judgment",
+    "   <list of findings where the fix phase must NOT auto-apply>",
+    "",
+    "   ## Out-of-Scope Observations",
+    "   <incidental issues noticed during the walk but outside the",
+    "   declared scope \u2014 e.g. a sibling doc tree that also looks stale.",
+    "   Recorded here so a human can decide whether to queue a follow-up",
+    "   cycle. Not acted on in this cycle.>",
+    "   ```",
+    "",
+    "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.",
+    "   - **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.",
+    "   - **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.",
+    "",
+    "6. **Commit and push.**",
+    "",
+    "---",
+    "",
+    "## 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.",
+    "",
+    "**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.",
+    "",
+    "### Fix Categories",
+    "",
+    "Apply only the categories the fix issue body enumerates. Defaults:",
+    "",
+    "| Category | What it does | Safety |",
+    "|----------|-------------|--------|",
+    "| **prune** | Remove stale entries from registries/indexes that point to non-existent docs. | Safe \u2014 only deletes references the scan confirmed are dead. |",
+    "| **normalize** | Rewrite relative link paths to a canonical form (e.g. always use paths relative to `<DOCS_ROOT>`, always include file extensions). | Safe \u2014 preserves target, changes only the link expression. |",
+    "| **regenerate** | Rebuild an index or registry file from the authoritative source (the filesystem or a declared source-of-truth file). | Safe IF the source-of-truth is unambiguous. Otherwise flag-for-human. |",
+    "| **flag-for-human** | Do not auto-apply. Leave the finding in place and note it in the fix report. | Used for ambiguous category assignments, duplicate IDs, or missing targets where the correct target is unclear. |",
+    "",
+    "### Steps",
+    "",
+    "1. **Read the audit report** referenced in the fix issue body.",
+    "",
+    "2. **Partition findings.** Group findings by fix category. Confirm",
+    "   each auto-fixable finding still matches what the report",
+    "   recorded (docs may have moved since the scan) \u2014 if a finding no",
+    "   longer applies, note it as `stale-finding` and skip.",
+    "",
+    "3. **Apply fixes in deterministic order:**",
+    "   1. **prune** \u2014 remove dead registry entries first. This reduces",
+    "      the surface area for downstream fixes.",
+    "   2. **normalize** \u2014 rewrite link expressions to canonical form.",
+    "   3. **regenerate** \u2014 rebuild indexes last, from the now-clean",
+    "      tree.",
+    "",
+    "4. **Never author new content.** If a finding requires inventing a",
+    "   target (e.g. a broken link where no candidate target exists),",
+    "   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`.",
+    "",
+    "6. **Write the fix report** to:",
+    "   ```",
+    "   <AUDIT_ROOT>/maint-fix-<AUDIT_SLUG>-<YYYY-MM-DD>.md",
+    "   ```",
+    "",
+    "   Format:",
+    "   ```markdown",
+    "   ---",
+    '   title: "Maintenance Fix: <AUDIT_SLUG>"',
+    "   date: YYYY-MM-DD",
+    "   parent_issue: <N>",
+    "   audit_report: <path to scan report>",
+    "   status: complete",
+    "   ---",
+    "",
+    "   # Maintenance Fix: <AUDIT_SLUG>",
+    "",
+    "   ## Source Audit Report",
+    "   <link to the Phase 1 audit report>",
+    "",
+    "   ## Fixes Applied",
+    "   | Category | Count | Files touched |",
+    "   |----------|-------|---------------|",
+    "   | prune | N | <list> |",
+    "   | normalize | N | <list> |",
+    "   | regenerate | N | <list> |",
+    "",
+    "   ## Skipped",
+    "   <findings that were stale, flagged for human, or reverted",
+    "   during verification \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>",
+    "   ```",
+    "",
+    "7. **Comment on the scan issue** with a summary of what was fixed,",
+    "   what was skipped, and any residual findings.",
+    "",
+    "8. **Commit and push.**",
+    "",
+    "---",
+    "",
+    "## Coordination with Other Agents",
+    "",
+    "| Direction | Agent | What |",
+    "|-----------|-------|------|",
+    "| 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",
+    "`<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.",
+    "",
+    "---",
+    "",
+    "## Blocked Issues",
+    "",
+    "Additional block reasons specific to maintenance audits:",
+    "- `<DOCS_ROOT>` is undefined or does not exist in the repo",
+    "- The registry file format is ambiguous (no declared schema)",
+    "- 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",
+    "",
+    "---",
+    "",
+    "## Rules",
+    "",
+    "- **Audit before fix.** Never apply a fix whose finding is not",
+    "  recorded in the audit report referenced by the fix issue.",
+    "- **Idempotent fixes only.** If re-running the same fix twice",
+    "  would produce a different result, it is not an idempotent fix.",
+    "  Mark it `flag-for-human` instead.",
+    "- **Bounded scope.** Do not expand the audit scope mid-session.",
+    "  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."
+  ].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.",
+  disableModelInvocation: true,
+  userInvocable: true,
+  context: "fork",
+  agent: "maintenance-audit",
+  platforms: { cursor: { exclude: true } },
+  instructions: [
+    "# Audit Docs",
+    "",
+    "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.",
+    "",
+    "## Usage",
+    "",
+    "/audit-docs <scope>",
+    "",
+    "Where `<scope>` is a short slug plus path for the doc tree to",
+    "audit. Examples:",
+    "- `requirements-xrefs:docs/requirements/` \u2014 audit requirement",
+    "  traceability links and the category registries",
+    "- `adr-registry:docs/adrs/` \u2014 audit the ADR registry index",
+    "- `bcm-traceability:docs/bcm/` \u2014 audit BCM capability-model",
+    "  cross-references",
+    "",
+    "The consuming project defines which scopes are valid.",
+    "",
+    "## Steps",
+    "",
+    "1. Create a `maint:scan` issue with `type:maintenance`,",
+    "   `priority:medium`, and `status:ready`. Body must list:",
+    "   - `<DOCS_ROOT>` \u2014 the doc tree to audit",
+    "   - `<AUDIT_ROOT>` \u2014 where to write the audit report",
+    "   - `<AUDIT_SLUG>` \u2014 short identifier for this audit",
+    "   - The audit checks to run (defaults to the full check catalog)",
+    "2. Execute Phase 1 (Scan) of the maintenance-audit agent.",
+    "3. If auto-fixable findings exist, a `maint:fix` issue is created",
+    "   automatically.",
+    "",
+    "## Output",
+    "",
+    "- A `maint-audit-<slug>-<YYYY-MM-DD>.md` report under",
+    "  `<AUDIT_ROOT>`.",
+    "- A `maint:fix` issue if auto-fixable findings were found."
+  ].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.",
+  appliesWhen: () => false,
+  rules: [
+    {
+      name: "maintenance-audit-workflow",
+      description: "Describes the 2-phase documentation-maintenance pipeline, the maint:* label taxonomy, and the audit-before-fix boundary.",
+      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`.",
+        "",
+        "The maintenance-audit agent *audits doc registries and applies",
+        "idempotent fixes*; it does **not** author new document content.",
+        "Findings that would require authoring new docs are flagged for",
+        "human review so the appropriate writer agent can be dispatched.",
+        "",
+        "See the `maintenance-audit` agent definition for full workflow",
+        "details and phase-by-phase instructions."
+      ].join("\n"),
+      platforms: {
+        cursor: { exclude: true }
+      },
+      tags: ["workflow"]
+    }
+  ],
+  skills: [maintenanceAuditSkill],
+  subAgents: [maintenanceAuditSubAgent],
+  labels: [
+    {
+      name: "type:maintenance",
+      color: "5319E7",
+      description: "Work that audits or fixes documentation registries, cross-references, or indexes"
+    },
+    {
+      name: "maint:scan",
+      color: "C5DEF5",
+      description: "Phase 1: scan doc tree for broken xrefs, registry drift, and stale indexes"
+    },
+    {
+      name: "maint:fix",
+      color: "BFDADC",
+      description: "Phase 2: apply idempotent fixes from a maintenance audit report"
+    }
+  ]
+};
+
 // src/agent/bundles/meeting-analysis.ts
 var meetingAnalystSubAgent = {
   name: "meeting-analyst",
@@ -7437,7 +7912,8 @@ var BUILT_IN_BUNDLES = [
   peopleProfileBundle,
   softwareProfileBundle,
   industryDiscoveryBundle,
-  bcmWriterBundle
+  bcmWriterBundle,
+  maintenanceAuditBundle
 ];
 
 // src/agent/bundles/scope.ts
@@ -10975,6 +11451,7 @@ export {
   githubWorkflowBundle,
   industryDiscoveryBundle,
   jestBundle,
+  maintenanceAuditBundle,
   meetingAnalysisBundle,
   orchestratorBundle,
   peopleProfileBundle,