|
|
|
@@ -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
|
DevRunbook release export