apiVersion: devrunbook.io/v1alpha1
kind: Playbook
metadata:
  id: maintenance.repository-cleanup
  slug: repository-cleanup
  version: 1.0.0
  title: Repository Cleanup and Hygiene
  summary: Remove dead files, stale scripts, generated artifacts and unused dependencies while preserving behavior.
  category: code-quality
  tags:
  - cleanup
  - dead-code
  - dependencies
  lifecycle: reviewed
  riskTier: moderate
  authors:
  - name: DevRunbook Core Team
  license: MIT
package:
  files:
  - path: prompt.md
    role: template
    digest: true
    exportByDefault: false
  - path: README.md
    role: documentation
    digest: true
    exportByDefault: false
  - path: CHANGELOG.md
    role: changelog
    digest: true
    exportByDefault: false
  - path: examples/minimal.yaml
    role: example
    digest: true
    exportByDefault: false
  - path: evaluations/static-structure.yaml
    role: evaluation
    digest: true
    exportByDefault: false
spec:
  type: guided
  intent:
    problem: Repositories accumulate unused dependencies, dead code, stale scripts, generated files and obsolete documentation
      that increase maintenance cost and confuse agents.
    outcome: Perform an evidence-based cleanup that removes genuinely unused material while preserving observable behavior
      and reproducible setup.
    whenToUse:
    - Before a release or major refactor.
    - After multiple experiments or abandoned features.
    - When repository size and navigation have become noisy.
    whenNotToUse:
    - When behavior changes or architecture redesign are the primary goal.
    - When there is no reliable way to validate important behavior.
  modes:
  - plan
  - guided
  - execute
  defaultMode: execute
  autonomy:
    min: plan
    max: repair
    default: verify
  inputs:
  - key: cleanupAreas
    label: Cleanup areas
    description: Select the cleanup dimensions to include.
    type: multiselect
    required: true
    sensitive: false
    includeInOutput: true
    default:
    - dead-files
    - unused-dependencies
    - stale-scripts
    options:
    - dead-files
    - dead-code
    - unused-dependencies
    - stale-scripts
    - generated-artifacts
    - documentation
    - gitignore
  - key: protectedPaths
    label: Additional protected paths
    description: Paths that must not be modified or removed.
    type: string-list
    required: false
    sensitive: false
    includeInOutput: true
    default: []
  - key: aggressiveness
    label: Cleanup aggressiveness
    description: Choose how conservative removal evidence must be.
    type: enum
    required: true
    sensitive: false
    includeInOutput: true
    default: conservative
    options:
    - conservative
    - standard
    - aggressive-reviewed
  compatibility:
    repositoryRequired: true
    languages: []
    frameworks: []
    packageManagers: []
    databases: []
    deploymentTypes: []
    requiredProfileCapabilities: []
    incompatibleConditions: []
  guardrails:
  - id: evidence-before-removal
    severity: blocking
    text: Do not remove a file, dependency, export or script without evidence that it is unused in supported behavior.
  - id: preserve-runtime
    severity: blocking
    text: Do not alter product behavior, public contracts, migrations or persisted user data.
  - id: protect-paths
    severity: blocking
    text: Do not modify repository-profile protected paths or additional protected paths.
  - id: no-history-rewrite
    severity: blocking
    text: Do not rewrite Git history or delete remote branches/tags.
  - id: no-mass-format
    severity: blocking
    text: Do not combine cleanup with repository-wide formatting or unrelated refactoring.
  workflow:
  - id: baseline
    title: Capture baseline
    instruction: Record worktree state, repository commands and current validation result before cleanup.
    required: true
  - id: inventory
    title: Build cleanup inventory
    instruction: Identify candidates with references, import/use searches, package-manager evidence and generated/runtime
      ownership.
    required: true
  - id: classify
    title: Classify candidates
    instruction: Separate safe removals, uncertain items and intentionally retained compatibility assets.
    required: true
  - id: remove-batches
    title: Apply small cleanup batches
    instruction: Remove only supported candidates in reviewable groups and update direct references.
    required: true
  - id: validate-batches
    title: Validate after each batch
    instruction: Run the narrowest useful checks after risky batches to localize regressions.
    required: true
  - id: full-validation
    title: Run full validation
    instruction: Run install/lockfile checks and all available required repository validation.
    required: true
  - id: final-review
    title: Review repository state
    instruction: Confirm no runtime data, examples or required compatibility assets were removed.
    required: true
  validation:
    commandRoles:
    - lint
    - typecheck
    - unit-test
    - integration-test
    - build
    - dependency-audit
    checks:
    - id: baseline
      type: artifact
      description: A baseline validation and worktree state are recorded.
      blocking: true
      evidence: Baseline section.
    - id: removal-evidence
      type: artifact
      description: Every removal is traceable to evidence of non-use.
      blocking: true
      evidence: Cleanup inventory.
    - id: lockfile
      type: command
      description: Dependency manifest and lockfile remain consistent when dependencies change.
      blocking: true
      evidence: Install/frozen-lockfile result.
      when:
        fact:
          path: inputs.cleanupAreas
          operator: contains
          value: unused-dependencies
    - id: full-validation
      type: command
      description: Available lint, typecheck, tests and build pass.
      blocking: true
      evidence: Command results.
    - id: diff-review
      type: assertion
      description: No protected or unrelated files changed.
      blocking: true
      evidence: Final diff review.
  completion:
    criteria:
    - Selected cleanup areas are addressed with evidence.
    - Repository setup, tests and build remain reproducible.
    - No supported behavior or protected data path changed.
    - Uncertain candidates remain and are documented rather than guessed.
  failurePolicy:
    onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
      the affected validation and report any genuine blocker without claiming success.
    onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
      current behavior, document the decision needed and stop before an irreversible change.
    onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
      behavior or validation results. Report what remains unavailable.
    onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
      follow-up recommendation.
    onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
      the blocked validation and do not claim the external path succeeded.
    onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
      provide the narrowest next diagnostic action.
  reporting:
    sections:
    - id: removed
      title: Removed items
      required: true
      description: List removals by category with concise evidence.
    - id: retained
      title: Intentionally retained
      required: true
      description: Explain uncertain or compatibility-related items that were not removed.
    - id: validation
      title: Validation
      required: true
      description: Commands and results before and after cleanup.
    - id: impact
      title: Impact
      required: true
      description: Repository size, dependency or navigation improvements where measured.
    - id: unresolved
      title: Follow-up
      required: false
      description: Remaining cleanup candidates or structural debt outside scope.
  template:
    main: prompt.md
    partials: []
  exports:
    prompt: true
    markdown: true
    runPack: true
    agentsSuggestion: false
quality:
  reviewStatus: technical-reviewed
  testedStacks: []
  knownLimitations:
  - Dynamic imports, plugins and externally invoked scripts can make static non-use evidence incomplete.
  evaluationCaseIds:
  - repository-cleanup.static-structure