repo-health-review
Systematic repo health review — survey scripts, detect duplicates, check naming, find gaps, prune dead weight, and produce a structured report. Run before major refactors or when asked to audit the repo.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- repo-health-review
- pinned
- false
- version
- 1.1.0
- category
- devops
- description
- Systematic repo health review — survey scripts, detect duplicates, check naming, find gaps, prune dead weight, and produce a structured report. Run before major refactors or when asked to audit the repo.
- related_skills
- [ "fleet-preflight", "documentation-auditing", "change-checklist" ]
02 资源文件 6
- 参考文档references/agent-type-branching-audit-2026-07-23.md2.7 KB
- 参考文档references/agent-type-system.md2.3 KB
- 参考文档references/comprehensive-review-2026-07-23.md2.3 KB
- 参考文档references/full-review-checklist.md2.7 KB
- 参考文档references/stale-deploy-and-auto-doctor.md2.5 KB
- 参考文档references/stale-deploy-cleanup.md2.9 KB
03 SKILL.md 正文
Repo Health Review — Systematic Audit
When to Use
- User asks "review the repo", "audit for gaps", "look for consolidation opportunities"
- Before a major refactor
- When onboarding a new team member (to document current state)
Multi-Axis Audit (preferred for comprehensive reviews)
For thorough reviews, run 3+ parallel subagents via delegate_task — one per axis.
Each subagent scans a different dimension simultaneously, keeping your context
uncluttered while they work:
# Standard 3-axis dispatch
delegate_task(tasks=[{
"goal": "Audit docs for stale paths, broken cross-refs, missing sections",
"context": "Check docs/ for stale src/, deploy/, runtime/ references..."
}, {
"goal": "Audit install/update/doctor pipeline",
"context": "Check fleet-update.sh register() validity, doctor --quick..."
}, {
"goal": "Audit Linux vs macOS platform support and agent types",
"context": "Check platform-specific code, SOUL.md profiles..."
}])
After subagents return, consolidate findings, fix easy items immediately, then produce a structured report of what was fixed vs deferred.
The 7-Pass Review (use for smaller/script-focused audits)
Pass 1: Structure Survey
ls ops/scripts/*/ # All script directories
ls docs/ # All docs
ls skills/ # All skill categories
Pass 2: Duplicate Detection
Check for files with same name in multiple directories:
find ops/scripts/ -name '*.py' -o -name '*.sh' | sed 's|.*/||' | sort | uniq -d
Verify identical content via MD5 when found:
md5sum <path1> <path2>
Pass 3: Naming Check
Identify scripts breaking hyphen convention:
find ops/scripts/ -name '*_*' -not -path '*/__pycache__/*' -not -name '__*'
Pass 4: Registration Check (Bi-Directional)
Check BOTH directions:
- Scripts in
ops/scripts/that are NOT registered infleet-update.sh register()entries infleet-update.shthat point to NON-EXISTENT files
# Direction A: Which scripts are NOT registered?
grep -oP 'register\s+"[^"]+' ops/scripts/fleet-update.sh | sed 's/register "//'
# Direction B: Which registered files are MISSING on disk?
grep -oP 'register\s+"[^"]+' ops/scripts/fleet-update.sh | sed 's/register "//' | while read f; do [ -f "$f" ] || echo "MISSING: $f"; done
Stale register() entries silently fail during deploy — the file simply
doesn't get copied. Over time this causes the deployed state to diverge
from expectations. Fix by removing the stale line from fleet-update.sh.
Also check for duplicate registrations (same file registered twice)
and path drift (file was renamed but register wasn't updated, e.g.
offline_code_index_cron.sh → offline-code-index-cron.sh).
Pass 4b: Stale Deploy Check
Check for deployed files that are no longer registered in fleet-update.sh.
When a register() line is removed, the deployed copy stays on disk as
an orphan. The doctor detects these:
python3 ~/steadfaste-fleet/ops/scripts/manage/fleet-doctor.py 2>&1 | grep "Stale deploy"
Fix with:
bash ~/steadfaste-fleet/ops/scripts/fleet-update.sh --clean-stale
Or run fleet-update.sh (auto-cleans stales after deploy). For non-scripts
deploy targets (dashboard/, bus/, systemd units, launchd plists), manual
cleanup may be needed.
Pass 4c: Doctor Comprehensive Check
After any structural change, run the full doctor and check ALL sections:
python3 ~/steadfaste-fleet/ops/scripts/manage/fleet-doctor.py 2>&1 | grep -E "❌|⚠️|ℹ️" | head -20
New in this session (2026-07-23):
- check_stale_deploys() — detects orphaned deploy files and missing sources
- Orphan cron detection — flags crons in scheduler not in expected list
- Network safety — scans for services on 0.0.0.0 (Ollama, Bus, Langfuse)
- Systemd linger — verifies Linux user services survive reboot
- Skills disk presence — verifies every listed skill exists on disk
The doctor itself was modularized into fleet_doctor/ package (8 modules).
Monolith at fleet-doctor.py is now a 34-line shim. To add a new check:
create a new function in checks.py and add it to the all_checks list in cli.py.
Pass 5: Doc Cross-Reference
Check which docs are NOT referenced by any other doc, AGENTS.md, or README.md:
Search every .md for each doc filename. Unreferenced docs may be lost or stale.
Pass 6: Stale File Check
__pycache__directories.pytest_cachedirectories- Root-level test files (should be in
tests/) - Zero-byte files
runtimesymlinks
Pass 7: Gap Analysis
- PRDs with no named implementation
- Overlapping scripts doing similar things
- Features documented but not wired
Pass 8a: Platform & Agent-Type Consistency
Check that platform-aware code handles both Linux and macOS:
grep -rn "systemctl\|launchctl\|brew\|apt-get\|platform\|uname" ops/scripts/ --include="*.py" --include="*.sh"
Identify scripts that assume one platform without an OS guard. Key patterns:
systemctlused without falling back tolaunchctlon macOSapt-getused on macOS (should bebrew)- Hardcoded paths like
/home/(Linux-only) or/Users/(macOS-only)
Check SOUL.md profiles for platform consistency:
- Does each agent profile declare a
platforms:field in frontmatter? - Do orchestrator profiles specify Linux?
- Do dev-agent profiles specify macOS/Linux?
Check agent-type coverage in docs:
docs/agent-architecture.md— lists all 4 roles (orchestrator, backup-orch, server-agent, dev-agent)?docs/fleet-reference.md— maps real agent names (Moses, Esther, etc.) to roles?docs/cron-schedules.md— split byorch-*,agent-*,local-*prefixes?AGENTS.md— mentions agent type differences?
Pass 8b: Cross-Script Deploy/Install/Doctor Consistency Audit
Purpose: Verify that the three core lifecycle scripts — install.sh, fleet-update.sh, and fleet_doctor/ — agree on agent-type branching. If they diverge, agents get false-positive doctor failures, wrong cron expectations, or orphan deploy artifacts.
Run when: User asks to audit agent-type branching, fix doctor false positives on non-orch agents, or verify deploy/install/doctor pipeline consistency. Also run before adding a new agent type.
Methodology — check 5 dimensions:
8b-1: Capability Model vs Role Model
Identify whether the system uses a capability model (FLEET_PROFILE=core|laptop|server — how much hardware) or a role model (--agent-type orchestrator|server|dev — what services to run):
# Which model does install.sh use?
grep -n 'FLEET_PROFILE' ops/install/install.sh | head -5
grep -n 'agent.type\|agent_type\|--agent-type' ops/install/install.sh | head -5
# Which model does the doctor use?
grep -n 'is_orch\|IS_ORCH\|hostname\|agent.type' ops/scripts/manage/fleet_doctor/config.py
Gap to detect: A capability model (FLEET_PROFILE) cannot distinguish between an orchestrator (needs bus server + dashboard + nginx) and a server-agent (needs bus client + crons, NOT dashboard/nginx). When both map to server, orchestrator-only services get deployed to server-agents and produce doctor false positives.
8b-2: register() Guard Coverage in fleet-update.sh
Check whether orchestrator-only service files (dashboard, fleet-bus server, nginx configs) are conditionally registered or deployed to every agent:
# Are dashboard/bus/nginx files registered unconditionally?
grep -n 'register.*dashboard\|register.*bus\|register.*nginx' ops/scripts/fleet-update.sh
# Is deploy_nginx_configs() guarded?
grep -B3 -A3 'deploy_nginx_configs' ops/scripts/fleet-update.sh
# Is deploy_system_scripts() guarded?
grep -B3 -A3 'deploy_system_scripts' ops/scripts/fleet-update.sh
Check: Is there an IS_ORCHESTRATOR, IS_SERVER, or FLEET_PROFILE guard on these? If they run unconditionally, server-agents and dev-agents get files they don't need. The only guard is FLEET_SKIP_NGINX env var — optional, not default.
8b-3: Doctor EXTERNAL_SERVICES Hardcoding
The doctor's config.py defines EXTERNAL_SERVICES — endpoints it checks for health. If this list is hardcoded with Dashboard, Langfuse, and Agent Bus, it will FAIL on every non-orch agent:
grep -A10 'EXTERNAL_SERVICES' ops/scripts/manage/fleet_doctor/config.py
Check: Is there agent-type awareness? Does the doctor skip Dashboard/Langfuse checks on server-agents that don't host them? Also check check_nginx() — does it run unconditionally?
8b-4: Cron Separation and Doctor Cron Expectation
Three cron layers should be cleanly separated. Verify cross-referencing:
# Universal crons (all agents)
grep -n 'agent-' ops/scripts/install-crons.sh | head -5
# Orchestrator-only crons
grep -n 'orch-' ops/scripts/install/install-orch-crons.sh | head -5
# Dev-agent crons — local-* prefix (created manually, no installer exists)
grep -n 'local-' ops/scripts/install-crons.sh | head -5
Check path 1: Does the doctor's parse_expected_crons() correctly exclude orch crons from the universal expected list?
grep -A15 'parse_expected_crons' ops/scripts/manage/fleet_doctor/config.py
Check path 2: Does check_crons() correctly identify orchestrator hosts and only FAIL on missing orch crons for those hosts?
grep -A15 'orch_crons_list' ops/scripts/manage/fleet_doctor/checks.py
Check path 3: Does check_crons() check the IS_ORCHESTRATOR env var (like fleet-update.sh does), or only hostname? Hostname-only is brittle — won't match fresh installs or custom hostnames.
Gap to detect: If parse_expected_crons() doesn't match install-orch-crons.sh, or if check_crons() hostname detection differs from install-orch-crons.sh, the doctor will produce inconsistent results.
8b-5: Dev-Agent Minimal Path
Check whether dev agents (e.g. titus) have a valid automated setup path:
# Is there an install-local-crons.sh script?
find ops/ -name '*local*' 2>/dev/null
# Does install.sh --agent-type dev exist?
grep 'dev\|titus' ops/install/install.sh
# Does fleet-update.sh skip dashboard/bus/nginx for dev agents?
grep 'IS_DEV\|agent.dev\|dev.minimal\|skip.*dev' ops/scripts/fleet-update.sh
Gap to detect: Dev agents with no automated installer must create local-* crons manually. If the local-* prefix is documented in comments but no scaffolding exists (no installer, no doctor awareness, no update guard), the dev-agent path is incomplete.
8b-6: Verify Hostname Detection Uniformity
The same hostname/orch-detection logic should appear in:
fleet-update.sh(lines ~1412-1438) —IS_ORCHESTRATORenv var + hostname fallbackfleet_doctor/checks.py(lines ~407-421) — hostname onlyinstall-orch-crons.sh(lines ~29-39) —IS_ORCHESTRATORenv var + hostname fallback
Gap: If the doctor doesn't read IS_ORCHESTRATOR from .env, it will fail to detect orchestrator hosts not named moses/esther. Scripts 1 and 3 agree; script 2 may be out of sync.
8b-7: Produce Cross-Script Consistency Table (see also: references/agent-type-system.md)
After checking all 5 dimensions, produce a table showing which files branch on what:
| Dimension | install.sh | fleet-update.sh | fleet_doctor/ |
|-----------|-----------|-----------------|----------------|
| Service install guard | FLEET_PROFILE=server | none (unconditional deploy) | none (hardcoded EXTERNAL_SERVICES) |
| Nginx deploy guard | FLEET_PROFILE=server | FLEET_SKIP_NGINX (optional) | none (always checks) |
| Orch cron guard | N/A | IS_ORCHESTRATOR + hostname | hostname only |
| Dev-agent path | none | none | none |
This table makes gaps visible at a glance. Each row that differs by column is a consistency failure.
User Preference Signals
When the user corrects your approach or style, capture the lesson:
| Signal | Response |
|---|---|
| "No. Refactor. Do it right" | Don't take shortcuts — thin wrappers are tech debt. Do the full refactor, not a compromise. |
| "Finish. Don't wait for future" | Don't defer actionable items. Fix them in the same session — every issue found during audit must be fixed or explicitly acknowledged before reporting done. |
| "Thoroughly test" | Every change must be exercised with real tool output before reporting done. |
| "Make agent X aware of Y" | If the doctor or pipeline should check for Y, add a check — don't just document it. |
| User repeats a correction | Add a structural guardrail (skill update, pre-commit hook, doctor check, auto-cleanup) that makes the mistake impossible. |
Encode these in the relevant skill's SKILL.md body — not just in memory. Skills capture "how to do this class of task for this user"; memory captures "who the user is and what the current situation is."
Deliverable
Produce a structured report with:
- Summary — counts: scripts, docs, skills, issues found, issues fixed
- Fixed Items — what was changed (moved, renamed, pruned, archived)
- Documented Items — what was noted for future action
- Priority Recommendations — ordered by effort vs impact
Output Path
Persist the report as a durable markdown document in the repo, committed so the whole fleet benefits:
docs/reviews/repo-health-review-YYYY-MM-DD.md
Treat that as relative to the repo root (e.g. steadfaste-fleet/docs/reviews/).
Prior reports live alongside it in docs/reviews/ — keep new reports there,
never at the docs root.
Anti-Patterns
- ❌ Only searching disk, not git — file may exist in repo but not deployed
- ❌ Skipping MD5 verification — two files with same name may differ
- ❌ Not checking cross-references before renames — breaks other agents
- ❌ Leaving stales without documenting the decision
04 同仓库更多 Skills
macbook-linux-maintenance
Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.
governance-regression-triage
Triage a host's governance issues: what changed.
enforcement-immutability
Use when enforcement files lose their immutable flag.
steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
steadfaste-fleet-maintenance
Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.
fleet-preflight
DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its "Repo-Specific Pre-Flight" section covers git search, Hermes boundary, and deployment verification.