argonath
Use when the user runs /argonath [project] [--quick]. Default mode weighs the about-to-be-pushed diff; the `project` verb weighs the standing project tree instead. Runs the project's lint/format/build
SKILL.mdskills/argonath/SKILL.md
GitHubArgonath — Pre-Push Analysis
The twin pillars at the river-gate. Before code crosses, render a verdict on whether it should pass. Report only — the skill never invokes git push itself.
Argument Parsing
Arguments: /argonath [project] [--quick]
- No verb → diff mode. Weighs the about-to-be-pushed diff (
@{upstream}..HEAD). Full run includes artefacts + secret scan + merge check + advisory rows. projectverb → project mode. Weighs the standing project tree, not a diff. Useful on master/main, on a fully pushed branch, or when no commits have been made yet.--quick→ skip the two sub-skill advisory rows (Rubric, Verdict) and the merged-tests escalation. Faster; only artefact commands, the secret scan, and (diff mode) the merge check and the drift probe. The drift probe survives--quickbecause it costs arev-listand two name-only diffs, not a sub-skill dispatch — it still reports the risk, it just does not act on it.
Workflow
1. Verify a git repo
git rev-parse --show-toplevel
If it errors, stop:
Not in a git repo — nothing to analyse.
Capture branch and upstream:
git rev-parse --abbrev-ref HEAD
git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'
git rev-list --count '@{upstream}..HEAD'
If no upstream is configured, mark the header · no upstream.
2. Resolve commands
~/.claude/hooks/argonath-detect.sh
Returns JSON: {stack, lint, format, build, test, install, test_scope, source}. If stack is unknown and every command is empty, render every artefact row as ⚪ skipped — no command, run the secret scan and advisory rows, and finish.
install is not an artefact row and is never run here — this tree is already installed. It belongs to step 7, which materialises a fresh checkout that carries none of the project's dependencies.
When source is override or merged, append (via .skadi/argonath.yaml) after the stack name in the header.
3. Run artefact steps
For each non-empty command (lint, format, build, test), call:
~/.claude/hooks/argonath-run.sh <label> <command...>
Labels: Lint, Format, Build, Tests. Capture each JSON result. The hook always exits 0; read ok from the JSON.
The format command is a check, not a fix — it carries --set-exit-if-changed, so it exits non-zero when files are unformatted and the row fails. Argonath never rewrites the tree it grades.
Empty command → render the row as ⚪ skipped — no command.
If test_scope is changed, the project's test command runs as configured — Argonath does not transform it. The override file is the place to express scope.
Test secrets. A suite that needs credentials names them as {{NAME}} placeholders in its override command — e.g. test: fvm flutter test --dart-define=testAccount={{TEST_ACCOUNT}} — and declares each one in the repo's test_env.md in Skadi state (~/.claude/hooks/skadi-state.sh path "${SKADI_PROFILE:-default}" "$PWD" test_env.md), one NAME=secret:<item>:<field> line apiece. argonath-run.sh resolves them through secret.sh; the row's command keeps the placeholder and the log masks the value. When the file or a name is missing, the row fails before the suite runs and its summary names the path to write — render that summary as it stands, never as failing tests. A mass failure confined to one directory whose test config calls fail(…) for missing credentials is the same missing secret: say so, rather than calling the suite broken.
4. Secret scan
Diff mode — resolve the target here, by step 5's order: run that rev-parse chain and pass the name that resolved (master, main, or origin/HEAD), not the SHA it prints. If none resolves, call the hook with no argument:
~/.claude/hooks/argonath-secrets.sh <target>
Project mode:
~/.claude/hooks/argonath-secrets.sh --project
Returns JSON {ok, count, hits, note}. In diff mode the scanned range is everything the branch brings to its target — <merge-base>..HEAD — whether pushed or not. Standing on the target itself, or with no target resolved, it falls back to @{upstream}..HEAD, and with no upstream either, to everything HEAD carries; the note names the range read. A branch with no commits beyond its target and no upstream thus scans the whole tree, so an old committed secret can raise a Hold there; in project mode every tracked file is scanned, untracked / .gitignored paths excluded.
ok: false with count: 0 means the scan could not run at all — a root it could not enter, or a git diff (diff mode) or git grep (project mode) that failed. Render the row 🚫 with the hook's note as its detail, never as a clean pass and never as "0 hits".
5. Merge check (diff mode only)
Project mode has no other branch to merge into — render the row ⚪ skipped — no project mode, the same shape as the Verdict row, and skip the rest of this section.
Diff mode resolves the target the same way /mithrandir already does — the first of master, main, origin/HEAD that exists locally:
git rev-parse --verify --quiet master \
|| git rev-parse --verify --quiet main \
|| git rev-parse --verify --quiet origin/HEAD
If none resolves, or the current branch is the resolved target, render the row ⚪ skipped — no target — there is nothing to probe.
Otherwise:
~/.claude/hooks/argonath-merge-check.sh <target>
Returns JSON {ok, conflicted_paths, note}. The probe runs git merge-tree --write-tree — a purely in-memory computation that never touches the working tree or the index, so it is safe to run regardless of what else this step has checked out. ok: false names a genuine textual conflict against the target's current tip; render the conflicting paths (comma-joined, capped at 3 with a +N more tail) in the detail column.
The hook can also return ok: true with a note ending in — skipped or unavailable or errored — its own internal degrade for a git too old to carry --write-tree, or any other merge-tree failure that never produced a CONFLICT line. Render that case as ⚪ skipped — <note>, not ✅ — only a note of "clean merge against <target>" is a genuine pass.
On that genuine pass, the detail column reads no textual conflict — not clean. The probe compared hunks and found none overlapping; it did not build the merged tree, run its tests, or otherwise establish that the merge is sound. clean invites the reader to conclude the second thing from the first. Step 6 exists for exactly the gap that phrasing used to hide.
6. Drift probe (diff mode only)
The merge check reads hunks: it answers whether the two sides collide textually. A merge can be textually clean and still break — the branch swaps the test framework while the target adds tests in the old one; the branch bumps a dependency while the target adds code against the old API; both sides add a migration bearing the same version. Neither side touched the other's lines, so merge-tree sees nothing. The drift probe names that risk without merging anything.
Project mode has no target to drift from — render the row ⚪ skipped — no project mode and skip the rest of this section. Reuse the target resolved in step 5; when none resolved, or the current branch is the target, render ⚪ skipped — no target.
Otherwise:
~/.claude/hooks/argonath-drift.sh <target>
Returns JSON {ok, moved, signals, note}. The probe is two-layered, cheapest first: it asks whether the target has moved at all since the branch point (a target standing still carries no risk — there is nothing new to collide with), and only then whether either side's changes land on one of three surfaces where a silent collision is known to hide — dependency (a manifest or lockfile, either side), test-config (a test-runner config, either side), migration (a migrations directory, both sides, since a version collision needs two). Each signal carries its kind, its path, and the side that moved it (branch, target, or both).
Render by outcome:
moved: 0→⚪ skippedwith the detailtarget unmoved since branch pointok: truewithmoved > 0→✅with the detailtarget moved <N> commits, no risk signalok: false→⚠with the signal paths and the tail— escalated. Each path carries its side in parentheses —pubspec.yaml (both sides),vitest.config.ts (target)— because which side moved a shared surface is half of what makes it worth reading. Comma-join them, capped at 3 with a+N moretail, the same cap the merge row's conflicting paths use
A fired signal is a risk, not a proven failure — the probe never ran a test. It is advisory: it never holds the verdict, whatever it found. What it does is decide whether step 7 runs at all. A quiet drift is the common case, and it is the reason the expensive probe stays unpaid for: nothing is merged, nothing is checked out, nothing is installed.
7. Merged tests (diff mode only, and only when drift fired)
Steps 5 and 6 both read and neither runs. This step is the escalation, and the only one that actually settles the question: it materialises the merge result and puts the project's own tests to it.
It runs only when step 6 returned ok: false. There is no flag to reach for and none to remember — a quiet drift means there is nothing to verify, and the merge is never performed. Render the row:
- project mode →
⚪ skipped — no project mode - no target resolved, or the current branch is the target →
⚪ skipped — no target - drift returned
moved: 0orok: true→⚪ skipped — no drift risk --quick→⚪ skipped — --quick
Otherwise:
~/.claude/hooks/argonath-merged-test.sh <target>
Returns JSON {ok, ran, stage, stack, command, summary, log, note}. The hook computes the merged tree in memory, wraps it in an unreferenced commit, and checks that out in a throwaway git worktree — the caller's working tree and index are never touched. Inside that worktree it re-detects the toolchain, installs, then tests. The re-detection is the point: when the merge is what changes the test framework, the old framework's command would prove nothing. Dependencies are installed there rather than copied from this tree, because a manifest that changed in the merge is exactly the case being tested.
Render by outcome:
ran: false→⚪ skipped — <note>(no test command on the merged tree, a textual conflict the merge row already owns, or a materialisation that failed)ok: true→✅with the detail<command> on the merged tree — all greenok: false→🚫with the detail<command> on the merged tree — <summary>, and name the failingstagewhen it isinstall
Unlike drift, this row is a gate. It ran the tests; a failure here is proven, not suspected, and it holds the verdict.
A run costs an install and a full test pass on a cold checkout — often slower than every other row combined. That cost is why step 6 stands in front of it.
8. Advisory rows (skip when --quick)
Invoke the two existing skills as sub-skills via the Skill tool, but fold each into a single row only.
- Rubric —
- Diff mode → invoke
/nazgul(default verb, scope=diff). Read its pass/fail tally; render<P> pass · <F> fail. - Project mode → invoke
/nazgul project. Same row shape.
- Diff mode → invoke
- Verdict —
- Diff mode → invoke
/mithrandir branch. Read the tier (sound/wavering/off) and the one-line reasoning paragraph; render<tier> — <≤60-char excerpt>. - Project mode →
/mithrandirhas no project verb, so render the row as⚪ skipped — no project mode.
- Diff mode → invoke
If either errors out, render its row as ⚠ unavailable — <short reason> and continue.
9. Aggregate
- Pass — every artefact step
okorskipped, secret scan returnedok: true, and the merge check and merged tests (where they ran) returnedok: trueor were skipped. - Hold — any artefact step
ok: false, secret scan returnedok: false, the merge check returnedok: false, or merged tests returnedok: false.
Advisory rows (drift, rubric, mithrandir) never push the verdict off Pass. A skipped merge check (project mode, or no target resolved) never holds the verdict either — it is a skip, not a finding. The drift probe never holds it under any outcome: it reports a risk it has not tested, and an untested risk is not a failing gate.
10. Render
Lead with a blockquote summary line, then the table. The blockquote echoes the verdict so the reader gets the conclusion in one breath.
Diff mode:
> Hold — tests must pass before crossing.
Argonath master · 3 commits ahead of origin/master · stack: flutter
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Lint fvm flutter analyze 0 issues
✅ Format fvm dart format --set-exit-if-changed . clean
✅ Build fvm flutter build apk --debug ok
🚫 Tests fvm flutter test 4 failing in test/dos_step3_test.dart
✅ Secret scan no tokens / .env values in diff
✅ Merge dry-run vs master no textual conflict
⚠ Drift pubspec.yaml (both sides) — escalated
🚫 Merged tests fvm flutter test on the merged tree 2 failing in test/api_client_test.dart
✅ Rubric /nazgul: 9 pass · 0 fail
⚠ Verdict /mithrandir: wavering — proportion drifts wide
───────────────────────────────────────
5 of 7 gates clear · 2 advisory notes
Project mode:
> Pass — project tree clear, no obstacles found.
Argonath master · up to date with origin/master · stack: flutter · mode: project
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Lint fvm flutter analyze 0 issues
✅ Format fvm dart format --set-exit-if-changed . clean
✅ Build fvm flutter build apk --debug ok
✅ Tests fvm flutter test all green
✅ Secret scan no tokens / .env values in tracked files
⚪ Merge skipped — no project mode
⚪ Drift skipped — no project mode
⚪ Merged tests skipped — no project mode
✅ Rubric /nazgul project: 9 pass · 0 fail
⚪ Verdict skipped — no project mode
───────────────────────────────────────
7 of 7 gates clear · 0 advisory notes
Symbols:
✅— passed (ok: true)🚫— failed (ok: false)⚪— skipped (no command, no project-mode counterpart, no resolvable merge target, or--quickmode for advisory rows)⚠— advisory tier belowsound/ unavailable, or a drift risk signal
Header line carries: <branch> · <ahead-state> · stack: <stack> and (via .skadi/argonath.yaml) when relevant. In project mode, append · mode: project after the stack name so the scope is plain.
<ahead-state>:
<N> commits ahead of <upstream>whenN > 0up to date with <upstream>whenN == 0no upstreamwhen not tracking
Footer line: <P> of <T> gates clear · <A> advisory note(s) — counts the artefact + secret + merge + merged-tests rows toward the gate count, a skipped row counting as clear; advisory rows (drift, rubric, verdict) are tallied separately, and only those that actually flagged count toward <A>.
Verdict-summary line in the blockquote follows /mithrandir's spirit:
- Diff mode:
> Pass — every gate clear, the road is open.> Hold — <plain reason: tests must pass / secrets removed / both>.
- Project mode:
> Pass — project tree clear, no obstacles found.> Hold — <plain reason>.
When stack: unknown and every artefact row was skipped, the verdict still resolves on the secret scan alone. If clean: > Pass — toolchain unknown, but no obstacles found.
Rules
- Read-only — never runs
git push,git commit,git tag,git push --tags, or any state-mutating tool beyond the artefact commands themselves - Artefact commands are taken at the user's word — if
.skadi/argonath.yamlconfigures something destructive as the test command, the skill runs it; the override file is the user's responsibility - The full step log lives in the tempfile path emitted by
argonath-run.sh. Do not read it unless the user asks for the failure detail - Sub-skills (
/nazgul,/mithrandir) are advisory — never block the Pass/Hold verdict on their findings - Sort the body rows in the order: Lint → Format → Build → Tests → Secret scan → Merge → Drift → Merged tests → Rubric → Verdict. Hide a row only if it is
--quick-suppressed - Project mode scans tracked files only — untracked /
.gitignored paths stay out of the secret scan, and the verdict row is always⚪ skipped(no/mithrandirproject verb exists) - Project mode has no target tree to probe either — the merge, drift, and merged-tests rows are always
⚪ skipped — no project mode - The merge check never mutates the tree —
git merge-tree --write-treecomputes entirely in memory. If it ever needs a fallback for a git older than 2.38, that fallback must preserve the same guarantee; a realgit merge --no-commitagainst the working tree is not an acceptable substitute inside a read-only skill - The merge row proves only that the two sides do not collide textually. Its detail column reads
no textual conflict, never a bareclean— a reader who takes it for "the merge is fine" has been misled by the skill, and the drift row exists because that reading was too easy to make - The drift probe merges nothing and checks nothing out — it reads refs and name-only diffs, the same read-only guarantee the merge check carries. A signal it raises is a risk it has not tested; never render it as a proven failure, and never let it hold the verdict
- The drift probe survives
--quickwhile the two sub-skill advisory rows do not. It costs onerev-listand two name-only diffs, so the reason--quickexists does not apply to it - Merged tests run only on a fired drift signal, and never under
--quick. There is no flag to force them: a flag would have to be remembered, and the run it guards is expensive enough that nobody would reach for it on the day it mattered. The drift signal is the trigger precisely so the decision is not the user's to make twice - Merged tests are a gate, not an advisory row — alone among the merge-adjacent rows they actually executed something, so alone among them they may hold the verdict. Drift's own signal never holds it, however loud
- The merged-tree probe never mutates the caller's tree either: it computes the tree in memory, wraps it in an unreferenced commit, and checks that out in a throwaway
git worktreeit tears down on every exit path. A realgit mergeorgit checkoutagainst the working tree is not an acceptable substitute, the same rule the merge check carries - The merged tree's toolchain is re-detected inside that worktree, never inherited from this one. A merge that swaps the test framework is the case the probe exists for, and the old framework's command would prove nothing about it