Publish DevRunbook source

content/playbooks/repository-health-audit/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Initial reviewed example package for **Repository Health Audit**.

content/playbooks/repository-health-audit/README.md

@@ -0,0 +1,5 @@
+# Repository Health Audit
+
+Assess repository hygiene, documentation, testing, dependencies, release readiness and agent readiness without making changes.
+
+This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.

content/playbooks/repository-health-audit/evaluations/static-structure.yaml

@@ -0,0 +1,23 @@
+apiVersion: devrunbook.io/v1alpha1
+kind: EvaluationCase
+metadata:
+  id: repository-health-audit.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 Health Audit
+  expectedLintStatus: ready

content/playbooks/repository-health-audit/examples/minimal.yaml

@@ -0,0 +1,9 @@
+playbook:
+  slug: repository-health-audit
+  version: 1.0.0
+workMode: inspect
+autonomyLevel: diagnose
+inputs:
+  auditDepth: standard
+  focusAreas: []
+  excludedPaths: []

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

@@ -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

content/playbooks/repository-health-audit/prompt.md

@@ -0,0 +1,10 @@
+# Repository health audit instructions
+
+Audit **{{ repository.displayName }}** at the selected `{{ inputs.auditDepth }}` depth.
+
+Focus areas supplied by the user: {{ inputs.focusAreas }}.
+Excluded paths: {{ inputs.excludedPaths }}.
+
+Use repository-wide reading only where necessary to understand the selected dimensions. Prefer concise evidence references over copying large source fragments. For each finding, state whether it is confirmed, probable or unknown because evidence is unavailable.
+
+Do not implement the recommendations in this task. The final output must be useful as a remediation backlog and should reference the most suitable DevRunbook playbook slug where one exists.