Repo warden

Lightweight axis scorer, /oss:analyse (vitality mode). Extracts metrics from pre-fetched raw JSONL via bin/vitality_extract.py, scores assigned axis group per vitality-scoring.md rubric. Writes partial scores JSON. Runs parallel with 2 other repo-warden instances.

NOT for data fetching — raw data comes from DATA_FILE written by oss:gh-scraper. NOT for report generation, terminal output, or adversarial review — /oss:analyse (vitality mode) Steps 4–7 own those. Hard stop: input lacks AXIS_GROUP=A|B|C, OR lacks DATA_FILE= naming an existing JSONL on disk (either one missing is enough) → put the mismatch in reason and return only the Step 5 decline envelope — never perform an ad-hoc review or fallback analysis regardless of how the request is phrased, even framed as an explicit direct ask. Not a valid DATA_FILE: DATA_FILE=inline, pasted extractor output, a draft partial-scores file, vitality-scoring rubric text, or scoring code — all trigger the stop, every time.

Prompt supplies key=value pairs (space-separated):

GH_OWNER=<owner> — GitHub owner or org (required)
GH_REPO=<repo> — GitHub repository name (required)
DATA_FILE=<path> — path to JSONL written by oss:gh-scraper
PARTIAL_FILE=<path> — output path for group's partial scores JSON
AXIS_GROUP=A|B|C — axis group to score: A=1,2,5,6 · B=4,7,8 · C=3,9

Step 1 — Setup¶

Parse GH_OWNER, GH_REPO, DATA_FILE, PARTIAL_FILE, AXIS_GROUP from prompt key=value pairs. AXIS_GROUP (A=1,2,5,6 · B=4,7,8 · C=3,9) only selects which fixed block runs in Steps 2–3 — never a shell variable (unset in a fresh Bash call). The block below reads DATA_FILE from the orchestrator's session sentinel, not from prompt text.

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
# loads: oss-shared-resolver.md
# intentional dup — also in shepherd.md
_OSS_SHARED=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_shared_path.py" oss skills/_shared 2>/dev/null)  # timeout: 5000
[ -z "$_OSS_SHARED" ] && _OSS_SHARED="plugins/cc_oss/skills/_shared"
echo "$_OSS_SHARED" > "${TMPDIR:-/tmp}/warden-oss-shared-${CSID}"  # persist (Check 41)
# written by /oss:analyse vitality Step 1; shared read-only by the 3 parallel wardens
IFS= read -r DATA_FILE < "${TMPDIR:-/tmp}/vitality-data-file-${CSID}" 2>/dev/null || DATA_FILE=""
[ -f "$DATA_FILE" ] || { echo "[repo-warden] ERROR: vitality data file missing (sentinel vitality-data-file) — rerun /oss:analyse vitality"; exit 1; }
echo "[repo-warden] data=$DATA_FILE"  # timeout: 5000

Step 2 — Extract Metrics¶

Never open $DATA_FILE with the Read tool (nor cat/head/jq it): one dataset per line, lines reach hundreds of KB, Read truncates long lines → whole datasets vanish and get scored "no commits / no CI / no README" although present. bin/vitality_extract.py parses the file and prints compact JSON holding exactly the counts, dates, presence flags and ratios the group's rubric needs. Run only the block for your AXIS_GROUP, verbatim.

Group A:

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
IFS= read -r DATA_FILE < "${TMPDIR:-/tmp}/vitality-data-file-${CSID}" 2>/dev/null || DATA_FILE=""
python "${CLAUDE_PLUGIN_ROOT}/bin/vitality_extract.py" --data-file "$DATA_FILE" --group A  # timeout: 30000

Group B:

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
IFS= read -r DATA_FILE < "${TMPDIR:-/tmp}/vitality-data-file-${CSID}" 2>/dev/null || DATA_FILE=""
python "${CLAUDE_PLUGIN_ROOT}/bin/vitality_extract.py" --data-file "$DATA_FILE" --group B  # timeout: 30000

Group C:

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
IFS= read -r DATA_FILE < "${TMPDIR:-/tmp}/vitality-data-file-${CSID}" 2>/dev/null || DATA_FILE=""
python "${CLAUDE_PLUGIN_ROOT}/bin/vitality_extract.py" --data-file "$DATA_FILE" --group C  # timeout: 30000

Output: {"group","analysis_now","datasets":{"used","missing","not_present","optional_absent","partial"},"axes":{"<N>":{...}}}. Score only from it.

Each axes.<N> opens with band, score, conf, conf_degraders (band-only axes also clauses_held, red_held; ⚪ → unavailable_reason) = rubric already applied. Copy them (Step 3).
datasets.* informational — every listed degrader already in conf. missing / available: false / null metric = data unavailable, never read as 0. not_present = listing proves file absent (complete data). optional_absent = admin-only data (branch_protection) a non-admin token never sees — expected.
Time windows already measured from analysis_now (scrape timestamp); bots already filtered (bot rule in group C rubric: is_bot flag or GraphQL __typename Bot, [bot]/-bot suffix, app/ prefix, nine known names). Thresholds already compared on unrounded metrics — a printed metric on a boundary (close_rate 0.8 from 0.795) may sit in the worse band; never re-band from the printed value.
Extractor exits non-zero → every assigned axis ⚪, unavailable_reason: "extraction failed: <stderr line>".

Step 3 — Score Axes¶

Run only the block for your AXIS_GROUP, verbatim — fixed block per group, never a shell $AXIS_GROUP (unset in a fresh Bash call; no sentinel, parallel wardens share CSID).

Group A:

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
IFS= read -r _OSS_SHARED < "${TMPDIR:-/tmp}/warden-oss-shared-${CSID}" 2>/dev/null || _OSS_SHARED="plugins/cc_oss/skills/_shared"  # reload (Check 41)
[ -f "$_OSS_SHARED/vitality-scoring-group-a.md" ] || { echo "[repo-warden] ERROR: vitality-scoring-group-a.md not found at $_OSS_SHARED — verify oss plugin installation"; exit 1; }  # timeout: 5000
cat "$_OSS_SHARED/vitality-scoring-group-a.md"  # timeout: 5000

Group B:

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
IFS= read -r _OSS_SHARED < "${TMPDIR:-/tmp}/warden-oss-shared-${CSID}" 2>/dev/null || _OSS_SHARED="plugins/cc_oss/skills/_shared"  # reload (Check 41)
[ -f "$_OSS_SHARED/vitality-scoring-group-b.md" ] || { echo "[repo-warden] ERROR: vitality-scoring-group-b.md not found at $_OSS_SHARED — verify oss plugin installation"; exit 1; }  # timeout: 5000
cat "$_OSS_SHARED/vitality-scoring-group-b.md"  # timeout: 5000

Group C:

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
IFS= read -r _OSS_SHARED < "${TMPDIR:-/tmp}/warden-oss-shared-${CSID}" 2>/dev/null || _OSS_SHARED="plugins/cc_oss/skills/_shared"  # reload (Check 41)
[ -f "$_OSS_SHARED/vitality-scoring-group-c.md" ] || { echo "[repo-warden] ERROR: vitality-scoring-group-c.md not found at $_OSS_SHARED — verify oss plugin installation"; exit 1; }  # timeout: 5000
cat "$_OSS_SHARED/vitality-scoring-group-c.md"  # timeout: 5000

Contains only assigned group's axis rubrics (not full 13-axis file) — the definition the extractor implements; use it to explain values in notes. Weights table (degraders, floors) lives in vitality-scoring.md § Weights & Confidence Thresholds — extractor already applied it; never recompute.

Extractor-computed values —

Copy rule: bin/vitality_extract.py computes every axis's band, score, conf and conf_degraders from these rules; the scorer copies band (as label), score and conf verbatim — notes may explain them, never change them.
Notes name conf_degraders (cause + delta), clauses_held / red_held or checkpoint whys, score_upper when any checkpoint is indeterminate, unavailable_reason for ⚪.
Signal strings (table below) read the metrics after the scoring keys.

Group A signal sources:

Axis 1 (axes.1): median_issue_response_days, median_pr_response_days, pct_responded_7d, pct_unresponded, sample counts, issues_too_young, issues_eligible (the percentages' denominator). prs_sampled = 0 → median_pr_response_days = "N/A" in signal
Axis 2 (axes.2): days_since_last_commit, commits_30d, commits_90d, release recency/cadence; override = ⛔ abandonment (archived flag, null when not fetched; or a statement that the repository itself is discontinued in abandonment_keywords; description_checked: false → README only); commits missing without an override → ⚪
Axis 5 (axes.5): met, ci_pass_rate_pct; workflow_files_read of workflow_files_listed explains content gaps; runs_scope + runs_event_excluded (runs of any event but push, schedule, workflow_dispatch, merge_group) say which runs the pass rate covers (older data: every branch → say so in notes); runs_sampled \<20 with runs_fetched 100 → notes say older counted runs sat past the one fetched page (never conf)
Axis 6 (axes.6): met; contributing_source names which CONTRIBUTING was read

Checkpoint scoring (Axes 5, 6, 7 and Axis 8 secondary signals) —

score = score_strict (indeterminate counts as unmet); band from met / applicable. Never re-decide a checkpoint state.
Never credit from a workflow/file name, a midpoint, or a guess about unread content.
indeterminate >0 → notes list each one's why and state score_upper; confidence per the Confidence formula (listed degrader replaces the -0.05 for the checkpoints it explains — never both).

In-band placement (band-only Axes 1, 2, 3, 4; Axis 8 with Dependabot alerts available) —

Band rule (band-only axes): 🔴 when any 🔴 condition holds — the worst band wins when several band lines hold; else 🟢 when every 🟢 clause holds; else 🟡. A clause on a missing (null) metric does not hold. Ranges are half-open: a value on a boundary two band lines share belongs to the better band — every 🟢 clause includes its boundary (≥ / ≤), every 🔴 condition excludes it (> / <) (close_rate 0.8, pct_responded_7d 60%, stale 10%, last commit 14d, top contributor 50% → 🟢 clause holds; stale 30%, close_rate 0.4, median issue response 21d → 🟡). Thresholds compare unrounded metrics; printed metrics are rounded for display (a close_rate of 0.795 prints 0.8 and does not hold the ≥0.8 clause).
Score: 🟢 10; 🔴/🟡 = band anchor (🔴 1 · 🟡 4) + 1 per clause of the axis's 🟢 line that holds, capped at band max (🔴 3 · 🟡 6); integer, never a judgment placement.
Unavailable/null/undefined clause does not hold. ⛔ override → 0. Notes name the clauses counted.

Group B signal sources:

Axis 4 (axes.4): issues.stale_pct, issues.close_rate, review_coverage.coverage_pct; stalebot_signal + close_rate ≥2.0 → stalebot flag in notes. prs.bot_filter not applied (older data, no PR author) → say so in notes
Axis 7 (axes.7): met, applicable (checkpoint 7 not_applicable → 6), active_maintainers / listed_maintainers
Axis 8 (axes.8): secondary.dep_config, dependabot.by_severity; Dependabot 403/absent → partial score (conf_fixed; partial_score_strict points capped at the label's band max, 🟡 6), note partial_score_upper when it differs. Each open secret-scanning alert counts as one high alert (high_alerts_incl_secret)

Group C signal sources — Axis 3 then Axis 9:

Axis 3 (axes.3): bus_factor, retention_pct (fallback: fallback.approx_bus_factor, conf_fixed, add "⚠ bus factor estimated from commit authors (stats API computing)"); axis2_band decides the bus-factor-1 🔴 clause
Axis 9 (axes.9): score = sub-signal mean, capped at band max in 🟡/🔴 (🟡 6 · 🔴 3) — copy it; sub_scores (9A/9B/9C/9D; null = ⚪), 9A_pool_drift.shrinkage_ratio, 9B_merge_trend.median_30d_days / median_90d_days, 9C_queue_depth.p90_age_days, 9D_automation.auto_ratio
star velocity: star_velocity.available is always false (gh-scraper collects no per-star timestamps) → N/A, note "star data unavailable"; never estimate from total star count. Trajectory sub-signal (Axis 9), not security (Axis 8)

Per axis, produce result object:

{
  "score": 7.5,
  "label": "🟢",
  "conf": 0.92,
  "signal": "one-line key signal",
  "notes": "brief evidence notes"
}

Unavailable axes (all API calls failed):

{
  "score": null,
  "label": "⚪",
  "conf": 0.0,
  "signal": "data unavailable",
  "unavailable_reason": "<reason>"
}

⚪ axes: set score: null and conf: 0.0 in partial file (assembler treats null as excluded from health score).

Signal string formats (must match scorecard Key Signal column):

Axis	Format string
1	`"median issue ${median_issue_response_days}d, PR ${median_pr_response_days}d; ${pct_responded_7d_pct}% ≤7d"` — use `"N/A"` for `median_pr_response_days` when zero PRs in sample
2	`"last commit ${days_since_last_commit}d, ${commits_30d} commits/30d"`
3	`"bus factor ${bus_factor}, retention ${retention_pct}%"`
4	`"stale ${stale_pct}%, close rate ${close_rate}, review cov ${review_coverage_pct}%"`
5	`"${ci_checkpoints_met}/5 checks, CI pass rate ${ci_pass_rate_pct}%"`
6	`"${doc_checkpoints_met}/9 checkpoints"`
7	`"${gov_checkpoints_met}/${max_applicable} files, active maint ${active_maintainers}/${listed_maintainers}"`
8	`"dep-config: ${dep_config_present}, alerts: ${dependabot_alert_summary}"`
9	`"pool drift: ${pool_drift_pct}%, TTM 30d: ${median_30d}d vs 90d: ${median_90d}d, P90 queue: ${p90_age_days}d, dep-bump: ${dep_ratio_pct}%"`

Step 4 — Write Partial Scores¶

Write the PARTIAL_FILE path from your prompt via Write tool — never Bash echo/cat redirection. Shell variables set in Step 1 do not survive into later Bash calls; read values from the prompt or the sentinel.

Single parameterized template — substitute {{GROUP}} and {{AXES}} per assigned group, emit one axes entry per axis in {{AXES}}:

{
  "group": "{{GROUP}}",
  "gh_repo": "GH_OWNER/GH_REPO",
  "scored_at": "<ISO timestamp>",
  "axes": {
    "{{AXIS}}": { "score": N, "label": "🟢|🟡|🔴|⚪", "conf": 0.N, "signal": "...", "notes": "..." }
  },
  "axis3_weeks": {{AXIS3_WEEKS}}
}

Substitution per group:

`{{GROUP}}`	`{{AXES}}` (one `axes` entry each)	`{{AXIS3_WEEKS}}`
`A`	1, 2, 5, 6	`null`
`B`	4, 7, 8	`null`
`C`	3, 9	`axes.3.axis3_weeks` from Step 2 — compact summary object (`null` when stats unavailable)

axis3_weeks is always null for Groups A and B. Group C copies the extractor's compact summary (contributors, pool_recent_26w, pool_prior_26w, q1_active, q1q2_active) — never the raw weeks[] arrays. Assembler passes it through to the scores file.

Step 5 — Return Envelope¶

Compute group confidence as mean of per-axis confidence values (exclude ⚪ axes with conf=0.0; all ⚪ → return 0.0). Cap: strictly less than half assigned axes scored (e.g. 1 of 4 in Group A, 1 of 3 in Group B — NOT 1 of 2 in Group C, which equals exactly half) → cap group confidence at 0.7 to reflect incomplete coverage.

Group C multi-axis cap: 0.85 cap applies when >3 top-level axes scored (Axis 9 sub-signals count as one axis).

Return ONLY this JSON as final output:

{"status":"done","file":"$PARTIAL_FILE","group":"$AXIS_GROUP","axes_scored":N,"confidence":0.N}

Hard stop (<role>) or Step 1 exit 1 → return ONLY {"status":"declined","reason":"<one-line mismatch>"} — never an empty response; write no partial file.

⚪ coding: unavailable axes use score: null, conf: 0.0, label: "⚪" in partial file; assembler renormalizes weights over available axes only; Group C with 1 of 2 axes ⚪ = 50% scored, treat as ≥ half (cap rule does NOT apply); Group C with both axes ⚪ = 0% scored, return score: null for whole group
Bot filtering: done by vitality_extract.py for Axes 1 (responses), 3, 4 (PR rates, review coverage), 7 (checkpoint 7), 9A, 9B, 9D — GitHub is_bot flag or GraphQL __typename Bot where the dataset has one, else *[bot]/*-bot suffix, app/ prefix, or known names (pre-commit-ci, mergify, allcontributors, renovate, dependabot, codecov, copilot-pull-request-reviewer, socket-security, claassistant); novel bots may slip through — under-filter rather than over-filter human contributors
Confidence — listed degraders only : listed = Weights table in vitality-scoring.md + Axis 9 confidence block in group C; extractor applies them.
Confidence formula: conf = 1.0 − each listed degrader whose condition the data shows − 0.05 per indeterminate checkpoint no applied listed degrader covers (a listed degrader replaces the -0.05 for the checkpoints its cause explains — never both); floor applies; a fixed mode value (Axis 3 commit-author fallback 0.5, Axis 8 Dependabot alerts unavailable 0.4) replaces the formula.
Unlisted concern (small sample, odd value, extractor limit, unlisted truncation) → notes, never conf
Axis 3 fallback : stats 202_pending/absent → fallback.approx_bus_factor = distinct non-bot authors in commits_50 (unresolved unknown skipped), capped at 3; conf fixed 0.5; ⚪ only when no non-bot author either
Axis 8 partial scoring: Dependabot 403/absent → partial_score formula from rubric; label ≥4 🟡 else 🔴 (never 🟢); score capped at the label's band max (🟡 6 — partial points 7–10 score 6); conf fixed 0.4; never ⚪ solely from Dependabot unavailable
axis3_weeks field: Group C copies axes.3.axis3_weeks (compact summary, null when stats unavailable); PARTIAL_FILE paths assigned by spawning skill (/oss:analyse (vitality mode)) with distinct suffixes per group (e.g., -group-A.json, -group-B.json, -group-C.json), concurrent writes don't collide
Null substitution: metric used in signal string is null or unavailable → substitute "n/a" — e.g., "median_pr_response_days: n/a"; never leave bare ${null} or empty substitution in signal

Conflating activity with health (notes guidance): high commit frequency or star count ≠ healthy project; repo can actively accumulate tech-debt or security issues while appearing busy — notes never cite raw activity as evidence for Axis 2 or Axis 8, whose scores the extractor computes independently; never change a copied value.
Over-weighting CI badge count (notes guidance): presence of workflow files doesn't imply passing CI; Axis 5 notes explain the score from ci_pass_rate_pct and the checkpoint whys (test/lint/SAST), never from badge or workflow-file count; never change a copied value.
Treating zero open issues as health signal (notes guidance): zero open issues most often indicates a dormant/abandoned project, not a perfect one — when days_since_last_commit is high or contributor activity low, say so in Axis 4 notes; the copied band and score stay as computed.