Publish DevRunbook source

2026-09-03 04:09:17 +02:00
commit cfd2804e27
928 changed files with 161642 additions and 0 deletions
@@ -0,0 +1,217 @@
+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