health-check

Skill: health-check

WHAT

Purpose and context

• Purpose: Quickly answer 3 questions about the "standard pattern" set (the set of files declared in .template-manifest.json) without manually diffing each file like sync-template:
  1. Complete yet? — whether every declared pattern is present on disk (MISSING).
  2. Local drift? — which patterns have been modified since the last sync (DRIFT).
  3. Need remote sync? — whether remote has a newer pattern version (BEHIND / older version).
• Trigger (when to use):
  • At session start the harness runs it automatically (SessionStart hook) — if there is drift it will remind automatically.
  • The user invokes /health-check to check manually at any time.
  • Before deciding whether to run /sync-template or not.
• Non-goals: does not pull/push files itself (that is /sync-template — health-check only diagnoses), does not inspect wiki content (broken link, orphan, stale — that is harness/scripts/wiki-health.py).

Mental model

Mechanism: a single config file harness/version.json stores template_version + hash of each pattern. Compare 3 points: disk ↔ version.json (drift), local ↔ remote version.json (behind), manifest ↔ disk (missing). Result per pattern → OK · DRIFT · NEEDS-SYNC → recommended action.

Input and output contract

	Field	Required?	Meaning
In	.template-manifest.json + harness/version.json	yes	pattern set + fingerprint; missing version.json → report the local part (fail-open)
In	--branch / --offline / --json / --fail-on	no	remote branch; skip fetch; machine-readable output; exit 2 for CI gate
Out	status report per group + OKF v0.1 line	yes	OK / DRIFT / NEEDS-SYNC + ✓ OKF v0.1: N/N …
Out	exit code	when --fail-on	2 if the specified group violates
Out	harness/version.json refreshed	only when --update after sync	hash matches disk

Rules and capabilities

• RULE-01 (MUST): Absolute fail-open: network error / missing version.json → report the local part, do NOT block the session.
• RULE-02 (MUST): harness/version.json is the single source of truth for version — do not hardcode version anywhere else.
• RULE-03 (MUST): Pattern set = includes in .template-manifest.json, EXCEPT harness/version.json and project-specific "live" files (index.md, log.md, active-context.md, decisions.md) — they are seeded but do not count as drift.
• RULE-04 (MUST): --bump only in the template repo; child projects only --update.
• RULE-05 (MUST): Adding a new pattern: add it to .template-manifest.json includes FIRST, then --update.
• Capabilities: read local disk + manifest + version.json; read remote version.json (optional, can be offline); write version.json only when --update.

Failure boundaries

• Network error / remote unreachable → report the local part, partial, do not block (RULE-01).
• Missing harness/version.json → report the checkable part, do not block.
• --fail-on encounters a violating group → failed (exit 2) for the CI gate.
• DRIFT unclear whether it is an improvement or a mistake → clarify with the user before upstream or revert.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	repo, branch	Run report harness/scripts/health-check.py (with/without remote)	status table + OKF line	offline → B01
W02	judgment	report	Read results by status table	recommended action	OK → done
W03	effect	recommendation	Action: /sync-template downstream/upstream or git checkout -- <file>	pattern synced/reverted	DRIFT ambiguous → clarify
W04	effect	after sync	Refresh fingerprint --update (bump only template repo, B02)	version.json matches disk	—

Details of each step (source of truth for W01–W04):

1. Run report (compare both remote)

python3 harness/scripts/health-check.py --root . --branch orca

• --offline : check local only (skip remote fetch) when there is no network.
• --json : machine-readable output (used for hook / CI).
• --fail-on behind,drift,missing : exit 2 if the specified group violates (used for CI gate).

2. Read results

status	meaning	action
OK	pattern sufficient + matches remote	nothing to do
DRIFT	pattern modified locally	consider upstream (/sync-template push) or revert
NEEDS-SYNC	missing file or remote newer	run downstream /sync-template

The report also includes 1 line OKF v0.1: ✓ OKF v0.1: N/N concept đạt chuẩn (every concept has YAML frontmatter + type) or ⟳ OKF v0.1: x/N … cần migrate. This is the quick answer to "has the project reached the OKF standard?". Not yet → python3 harness/scripts/okf-check.py --migrate.

3. Act on the recommendation

• BEHIND / MISSING → call /sync-template (downstream): pull the new/missing pattern.
• DRIFT → if it is an improvement you want to keep: /sync-template upstream; if accidentally modified: git checkout -- <file>.

4. After syncing completes — refresh version.json

Each time downstream sync changes pattern content, update the fingerprint:

python3 harness/scripts/health-check.py --update            # giữ nguyên version
python3 harness/scripts/health-check.py --update --bump patch   # khi PHÁT HÀNH bản mới (chỉ làm ở repo template)

--bump (major/minor/patch) ONLY runs in the template repo Rheinmir/setup when you want to publish a new pattern version to all projects. Child projects only --update (no bump) to sync the hash after pulling.

Branches

ID	Kind	Guard	Behavior	Skip / failure	Rejoin
B01	user_optional	no network / user wants to check local only	add --offline, skip remote fetch	network error when no flag → still reports the local part (fail-open)	W02
B02	conditional_required	currently in the template repo Rheinmir/setup and releasing a new pattern version	--update --bump patch (major/minor/patch)	child project → only --update	ends
B03	capability_optional	runs in a CI/hook gate	--json and/or --fail-on behind,drift,missing	—	W02 (or exit 2)

Validation and stopping

Status is computed by health-check.py deterministically (hash + version comparison), not guessed by the model. Stop when status OK, or after the recommended action is done and --update has synced the hash.

Examples

• Positive: start of session, remote orca has template_version newer → reports NEEDS-SYNC (BEHIND) → calls /sync-template downstream → python3 harness/scripts/health-check.py --update → rerun yields OK.
• Boundary/failure: machine offline, run without --offline → remote fetch fails, still prints the local part (DRIFT/MISSING) and does not block the session; the BEHIND group cannot be determined.

Reference — Relationship with other skills

• [[sync-template]] — health-check diagnosis (whether sync is needed); sync-template execution (pull/push files). Always run health-check first, sync-template after.
• harness/scripts/wiki-health.py — sibling at the same L4 layer but inspects wiki content (broken link, orphan, stale), not the pattern version.

Origin

• Draft: llmwiki/wiki/sources/draft/150626-health-check-pattern-sync.md