Publish DevRunbook source

examples/playbooks/repository-cleanup/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Initial reviewed example package for **Repository Cleanup and Hygiene**.

examples/playbooks/repository-cleanup/README.md

@@ -0,0 +1,5 @@
+# Repository Cleanup and Hygiene
+
+Remove dead files, stale scripts, generated artifacts and unused dependencies while preserving behavior.
+
+This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.

examples/playbooks/repository-cleanup/evaluations/static-structure.yaml

@@ -0,0 +1,23 @@
+apiVersion: devrunbook.io/v1alpha1
+kind: EvaluationCase
+metadata:
+  id: repository-cleanup.static-structure
+  version: 1.0.0
+spec:
+  playbookVersion: 1.0.0
+  inputFile: ../examples/minimal.yaml
+  expectedHeadings:
+  - Mission
+  - Scope
+  - Constraints and guardrails
+  - Execution workflow
+  - Validation plan
+  - Completion contract
+  - Final reporting format
+  prohibitedPatterns:
+  - BEGIN PRIVATE KEY
+  - 'Authorization: Bearer'
+  deterministic: true
+  requiredPatterns:
+  - Repository Cleanup and Hygiene
+  expectedLintStatus: ready

examples/playbooks/repository-cleanup/examples/minimal.yaml

@@ -0,0 +1,12 @@
+playbook:
+  slug: repository-cleanup
+  version: 1.0.0
+workMode: plan
+autonomyLevel: verify
+inputs:
+  cleanupAreas:
+  - dead-files
+  - unused-dependencies
+  - stale-scripts
+  protectedPaths: []
+  aggressiveness: conservative

examples/playbooks/repository-cleanup/playbook.yaml

@@ -0,0 +1,253 @@
+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

examples/playbooks/repository-cleanup/prompt.md

@@ -0,0 +1,9 @@
+# Repository cleanup instructions
+
+Selected cleanup areas: {{ inputs.cleanupAreas }}.
+Aggressiveness: {{ inputs.aggressiveness }}.
+Additional protected paths: {{ inputs.protectedPaths }}.
+
+Use conservative evidence by default. Search references, build manifests, CI configuration, documentation, runtime loading patterns and external entry points before removal. Dynamic loading or deployment scripts should be treated as uncertainty, not proof of non-use.
+
+Apply cleanup in coherent batches. Do not hide behavior changes inside a hygiene task.