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