DevRunbook-Public/content/playbooks/repository-health-audit/playbook.yaml

apiVersion: devrunbook.io/v1alpha1
kind: Playbook
metadata:
  id: audit.repository-health
  slug: repository-health-audit
  version: 1.0.0
  title: Repository Health Audit
  summary: Assess repository hygiene, documentation, testing, dependencies, release readiness and agent readiness without
    making changes.
  category: audits
  tags:
  - audit
  - repository
  - health
  lifecycle: reviewed
  riskTier: low
  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 often accumulate gaps across documentation, testing, dependencies, release practices and agent instructions
      without one evidence-based view.
    outcome: Produce a read-only, prioritized repository health report with evidence, confidence, impact and recommended follow-up
      playbooks.
    whenToUse:
    - Before major development or onboarding begins.
    - When repository quality has not been reviewed recently.
    - Before deciding where cleanup investment should go.
    whenNotToUse:
    - When a formal penetration test or legal compliance certification is required.
    - When the user expects automatic code changes rather than an audit report.
  modes:
  - inspect
  - plan
  defaultMode: inspect
  autonomy:
    min: observe
    max: plan
    default: diagnose
  inputs:
  - key: auditDepth
    label: Audit depth
    description: Select how broadly the repository should be inspected.
    type: enum
    required: true
    sensitive: false
    includeInOutput: true
    default: standard
    options:
    - focused
    - standard
    - deep
  - key: focusAreas
    label: Focus areas
    description: Optional dimensions that deserve extra attention.
    type: multiselect
    required: false
    sensitive: false
    includeInOutput: true
    default: []
    options:
    - documentation
    - testing
    - dependencies
    - architecture
    - security-hygiene
    - release
    - agent-readiness
  - key: excludedPaths
    label: Excluded paths
    description: Paths that must not be inspected beyond identifying their existence.
    type: string-list
    required: false
    sensitive: false
    includeInOutput: true
    default: []
  compatibility:
    repositoryRequired: true
    languages: []
    frameworks: []
    packageManagers: []
    databases: []
    deploymentTypes: []
    requiredProfileCapabilities: []
    incompatibleConditions: []
  guardrails:
  - id: read-only
    severity: blocking
    text: Do not modify files, Git state, repository settings or external systems.
  - id: evidence-first
    severity: blocking
    text: Link each finding to observable repository or forge evidence and distinguish absence of evidence from confirmed
      absence.
  - id: no-secret-reading
    severity: blocking
    text: Do not open secret files, private keys, runtime databases or credential stores.
  - id: no-certification-claim
    severity: warning
    text: Do not present this audit as a penetration test, legal review or certification.
  workflow:
  - id: recon
    title: Establish repository context
    instruction: Read repository-level instructions, manifests, documentation, build/test configuration and selected governance
      evidence before evaluating quality.
    required: true
  - id: dimension-review
    title: Assess quality dimensions
    instruction: Review repository hygiene, documentation accuracy, test strategy, dependency management, release readiness,
      container/operations readiness and Codex instruction readiness.
    required: true
  - id: validate-findings
    title: Validate findings
    instruction: Check potential findings against multiple evidence sources where practical and remove weak or duplicate observations.
    required: true
  - id: prioritize
    title: Prioritize recommendations
    instruction: Rank findings by user impact, operational risk, confidence and realistic remediation order.
    required: true
  - id: report
    title: Produce audit report
    instruction: Create a concise executive summary plus detailed evidence table and recommended follow-up playbooks.
    required: true
  validation:
    commandRoles: []
    checks:
    - id: read-only-proof
      type: assertion
      description: Confirm the worktree and repository settings were not changed.
      blocking: true
      evidence: Git/status or equivalent evidence shows no modifications.
    - id: evidence-links
      type: artifact
      description: Every medium/high finding includes an evidence path or forge evidence pointer.
      blocking: true
      evidence: Audit report finding table.
    - id: limitations
      type: artifact
      description: Permission limits, uninspected paths and uncertainty are documented.
      blocking: true
      evidence: Limitations section.
  completion:
    criteria:
    - No repository files or external settings were changed.
    - Every reported finding includes severity, confidence, evidence and impact.
    - Recommendations are ordered and mapped to actionable follow-up.
    - Limitations and unknowns are explicit.
  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: summary
      title: Executive summary
      required: true
      description: Overall health, strongest areas, highest risks and recommended first action.
    - id: findings
      title: Findings by dimension
      required: true
      description: Evidence-linked findings grouped by dimension and severity.
    - id: priorities
      title: Prioritized actions
      required: true
      description: Ordered remediation backlog with suggested playbooks.
    - id: limitations
      title: Limitations
      required: true
      description: Permissions, exclusions and uncertainty that affect the audit.
  template:
    main: prompt.md
    partials: []
  exports:
    prompt: true
    markdown: true
    runPack: true
    agentsSuggestion: true
quality:
  reviewStatus: technical-reviewed
  testedStacks: []
  knownLimitations:
  - Static evidence cannot prove runtime behavior that is not exercised.
  - Forge governance findings depend on available permissions and capabilities.
  evaluationCaseIds:
  - repository-health-audit.static-structure