@codedrifters/configulator 0.0.209 → 0.0.211

package/lib/index.d.mts

@@ -1058,6 +1058,19 @@ declare const industryDiscoveryBundle: AgentRuleBundle;
  */
 declare const jestBundle: AgentRuleBundle;
 
+/**
+ * Maintenance-audit bundle — opt-in via
+ * `includeBundles: ["maintenance-audit"]`.
+ *
+ * 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.
+ */
+declare const maintenanceAuditBundle: AgentRuleBundle;
+
 /**
  * Meeting analysis bundle — included by default.
  * Provides a 4-phase meeting transcript processing workflow.
@@ -1894,7 +1907,7 @@ declare const VERSION: {
      *
      * CLI and lib are versioned separately, so this is the lib version.
      */
-    readonly AWS_CDK_LIB_VERSION: "2.249.0";
+    readonly AWS_CDK_LIB_VERSION: "2.250.0";
     /**
      * Version of the AWS Constructs library to use.
      */
@@ -3508,4 +3521,4 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, type LabelDefinition, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, type McpServerConfig, type McpTransport, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightSidebarItem, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, type LabelDefinition, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, type McpServerConfig, type McpTransport, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightSidebarItem, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };

package/lib/index.d.ts

@@ -1107,6 +1107,19 @@ declare const industryDiscoveryBundle: AgentRuleBundle;
  */
 declare const jestBundle: AgentRuleBundle;
 
+/**
+ * Maintenance-audit bundle — opt-in via
+ * `includeBundles: ["maintenance-audit"]`.
+ *
+ * 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.
+ */
+declare const maintenanceAuditBundle: AgentRuleBundle;
+
 /**
  * Meeting analysis bundle — included by default.
  * Provides a 4-phase meeting transcript processing workflow.
@@ -1943,7 +1956,7 @@ declare const VERSION: {
      *
      * CLI and lib are versioned separately, so this is the lib version.
      */
-    readonly AWS_CDK_LIB_VERSION: "2.249.0";
+    readonly AWS_CDK_LIB_VERSION: "2.250.0";
     /**
      * Version of the AWS Constructs library to use.
      */
@@ -3557,5 +3570,5 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };
 export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, McpServerConfig, McpTransport, MergeMethod, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightSidebarItem, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };

package/lib/index.js

@@ -228,6 +228,7 @@ __export(index_exports, {
   githubWorkflowBundle: () => githubWorkflowBundle,
   industryDiscoveryBundle: () => industryDiscoveryBundle,
   jestBundle: () => jestBundle,
+  maintenanceAuditBundle: () => maintenanceAuditBundle,
   meetingAnalysisBundle: () => meetingAnalysisBundle,
   orchestratorBundle: () => orchestratorBundle,
   peopleProfileBundle: () => peopleProfileBundle,
@@ -2896,6 +2897,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",
@@ -7289,7 +7765,7 @@ var VERSION = {
    *
    * CLI and lib are versioned separately, so this is the lib version.
    */
-  AWS_CDK_LIB_VERSION: "2.249.0",
+  AWS_CDK_LIB_VERSION: "2.250.0",
   /**
    * Version of the AWS Constructs library to use.
    */
@@ -7511,7 +7987,8 @@ var BUILT_IN_BUNDLES = [
   peopleProfileBundle,
   softwareProfileBundle,
   industryDiscoveryBundle,
-  bcmWriterBundle
+  bcmWriterBundle,
+  maintenanceAuditBundle
 ];
 
 // src/agent/bundles/scope.ts
@@ -11037,6 +11514,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   githubWorkflowBundle,
   industryDiscoveryBundle,
   jestBundle,
+  maintenanceAuditBundle,
   meetingAnalysisBundle,
   orchestratorBundle,
   peopleProfileBundle,