cli/skills/doctor/SKILL.md

name, description

name

description

doctor

Health-check the execution environment in one pass and record the result, changing nothing. Four checks - plugin versions from jsc-hooks/hooks/version-guard.sh report, hook wiring from jsc-hooks/tools/wire-cli.sh status, settings from tools/scan-config.sh against tools/config-spec.tsv, and orphan variables. Report one findings table per check, build the 待修項目 table with tools/build-todo.sh, then write the whole run to wiki CHECK_{HASH} where HASH comes from {short hostname}/{user}; the page keeps only the latest run, while its CHECK_CONTENTS block is upserted through wiki-contents.sh into the contents repo. Use after installing or updating the skill set, when a skill fails on a settings or wiring problem, or before handing a machine over; not for applying fixes, which is jsc-cli:setup.

doctor — execution environment health check

Read-only. Every command below either reads a file or asks Gitea; none of them writes a setting. That is the contract with jsc-cli:setup: doctor states the facts, setup changes things.

The read-only contract is enforced in code, not by prose: every {JSC_ROOT}/jsc-hooks/tools/wire-cli.sh call in this skill runs with JSC_READONLY=1 in its environment. A mistyped subcommand then refuses to write instead of rewiring the machine that was only supposed to be measured.

Path rule — every script call is a literal absolute path

Write every script call in this skill as a literal absolute path. Never hand the shell a path that still holds a variable or a tilde — $JSC_HOME/..., ~/.jsc/..., or anything like them — and never a bare relative one either. The permission layer matches paths statically: it expands no variable and no tilde, so such a path matches no allow rule and the call falls through to an approval prompt. A bare relative path is the worse form, because it resolves against whatever directory the CLI happens to be in — and this skill deliberately runs from the operator's project directory, which is never a plugin root — so every bare call site is a place where a prefix gets guessed.

A guessed prefix is the specific danger here, and it is quiet. This skill measures a machine and writes what it found onto a page other people act on, so a call that reaches the wrong copy of a script does not fail — it reports. An old tools/scan-config.sh reached through some other version's directory grades this machine against that version's tools/config-spec.tsv, and every row it prints looks exactly like a real finding. A checkup that cannot say which script produced its rows is worth less than no checkup, because nobody doubts it.

Portability is no reason to put the variable back. Step 0 resolves the roots once, at run time, on whatever machine this runs on — that is where portability comes from.

Step 0 — resolve the two roots, once

Before step 1, run this one command:

readlink -f "$JSC_HOME/current"

It prints one absolute directory: the current directory itself, a farm of version-free symbolic links with one entry per plugin. Call it {JSC_ROOT} for the rest of this document. Stop at that directory — never resolve one level further. Resolving one of those entries lands on the versioned plugin cache (/root/.claude/plugins/cache/jsc/jsc-hooks/0.4.2, say), and a versioned path is exactly the kind no allow rule can hold: a rule with * where the version segment goes matches nothing, measured. {JSC_ROOT} is the version-free root, and staying at it is the whole point. This is the only place a variable may appear; the shell expands it inside the command itself, so no unexpanded path ever reaches the permission layer.

Confirm the directory exists, in the same approved step: [ -d "{the path just printed}" ]. That is the check the other two wave through. JSC_HOME is an optional variable with a default, so an unset one is an ordinary machine state rather than an exotic one — it has its own row in {CLI_ROOT}/tools/config-spec.tsv, and finding it unset is a normal outcome of this very checkup. With it unset the command prints /current and exits 0 — non-empty, absolute, and nowhere — and every literal path built from it then names a place that is not there.

Unlike jsc-cli:deploy, an unresolvable {JSC_ROOT} never stops this run. It is a finding, and findings are what this skill produces: report JSC_HOME in the 全域設定 block and at the top of the 待修項目 table. Mark every check that needed a cross-plugin script as 無法驗證 with that as its reason, and let the checks that do not need one finish. A read-only checkup that aborts tells the operator nothing, and the machine most in need of a checkup is the machine whose paths do not resolve.

Substitute {JSC_ROOT} in every cross-plugin call, so what runs is a literal absolute path. {JSC_ROOT}/jsc-hooks/hooks/version-guard.sh becomes, for example, /root/.jsc/current/jsc-hooks/hooks/version-guard.sh. Resolve it once, at the start of the run. Do not re-resolve it per call, and do not add a tool that prints it.

The second root — this skill's own tools/ and templates/

Do not reach this skill's own files through {JSC_ROOT}, even though a jsc-cli link is normally sitting there. jsc-cli:deploy refreshes the whole farm at the end of every round, so on a machine that has deployed, that link exists. This skill still may not lean on it, for a reason of its own: doctor is the skill that gets run when the machine is suspect. Its own triggers say so — after an install or update, after a skill failed on a settings or wiring problem, before a handover. A deploy that ended degraded is one whose link lines came back fail, or skip on a path holding something that is not a symbolic link at all, leaving a plugin's documented path on an old version — and doctor is what runs next. Reached through that link, tools/scan-config.sh and its tools/config-spec.tsv come from a version this machine is not running, and the findings table then describes a machine that does not exist. Nothing errors: an old scanner runs perfectly well.

The second root is free of that. tools/scan-config.sh, tools/detect-clis.sh and tools/build-todo.sh reached through it keep working on a machine whose farm is stale, broken, or never built — which is precisely the machine being measured — so JSC_HOME itself still gets scanned and still gets reported.

They sit at {plugin root}/tools/ and {plugin root}/templates/, and the plugin root is the base directory the CLI states when it loads this skill. Take that literal path verbatim, call it {CLI_ROOT}, and write every own-plugin path as {CLI_ROOT}/tools/{script} or {CLI_ROOT}/templates/{file} — /root/.claude/plugins/cache/jsc/jsc-cli/0.3.3/tools/scan-config.sh, for example. No command runs for this one, and it is taken once, like {JSC_ROOT}.

That base directory carries a version segment, so no allow rule covers it and each of those calls raises an approval prompt. That is acceptable in this skill and in no unattended one: doctor runs with the operator in front of it — the five blocks and the 待修項目 table are printed for a person to read and act on — so there is somebody to approve. Never carry this branch into a skill that runs from a scheduler, and never guess a prefix when the invocation states no base directory: report that this skill's own plugin root is unknown and stop, because a guessed prefix reports some other version's idea of this machine as if it were this machine.

Done when {JSC_ROOT} holds one existing absolute directory or its failure is recorded as a JSC_HOME finding, and {CLI_ROOT} holds one literal absolute path.

1. Collect, four checks in parallel

Start all four collectors at once. They share no data, so serialising them only makes the check four times slower. Each one MUST run as a sub agent, and each returns its raw output lines unchanged — no summarising inside the sub agent, because step 2.2 parses those lines.

Done when all four sub agents have returned, and each has either its raw lines or an explicit failure reason.

1.1 Skill versions

Run {JSC_ROOT}/jsc-hooks/hooks/version-guard.sh report. It prints {domain}<TAB>{本機}<TAB>{遠端}<TAB>{落後|最新|超前|查詢失敗} per plugin, then behind<TAB>{count}.

A report with no {domain} row, or one carrying noregistry<TAB>{path}, means this CLI has no local plugin registry. Report it as 無法驗證 — never as 最新. behind<TAB>0 proves nothing when no domain row precedes it.

report only reads, so it exits 0 even when every lookup fails. Any non-zero exit means the script itself could not run: report the whole version check as 無法驗證 together with the exit code, and let the other three checks finish.

Done when every installed domain has a status literal, or the check is reported as unverifiable with its reason.

1.2 Hook wiring

First run {CLI_ROOT}/tools/detect-clis.sh. Exit 0 with at least one row → those are the CLIs to check. Exit 0 with no row → report the wiring table as empty and say no AI agent CLI was detected; that is a finding, not a pass. Any non-zero exit → report the wiring check as 無法驗證 with the exit code and stderr.

Then run JSC_READONLY=1 {JSC_ROOT}/jsc-hooks/tools/wire-cli.sh status {cli} for every detected CLI. Use status and nothing else: wire-cli.sh without a subcommand rewires, purge deletes, and smoke executes hooks — all three break the read-only contract.

Exit	Meaning	Action
0	wired	Record as wired
1	degraded	Record as degraded and quote the reason text
2	usage error	Stop this CLI's wiring check. The subcommand or the CLI name is wrong — report it as a defect in this skill, not as a machine fault
3	skipped	The CLI is not installed. Drop it from the wiring table
5	unwired	Record every item line whose state is missing
other	unexpected	Report that CLI's wiring as 無法驗證 with the exit code and stderr. Never read it as wired

Only claude reaches wired. The other four have no pre-tool hook, so degraded is their healthy state — report the degradation reason as-is and never present it as a defect to fix.

Done when every detected CLI carries one of those verdicts and its missing items are listed.

1.3 Settings, global and project in one scan

Run {CLI_ROOT}/tools/scan-config.sh scan all from the current working directory. One call covers both scopes: the spec table is read once and the scope column separates the rows. It prints {項目}<TAB>{範圍}<TAB>{必要}<TAB>{現況}<TAB>{說明}<TAB>{修法}<TAB>{判定}, closing with summary<TAB>{missing}<TAB>{invalid}<TAB>{unset}<TAB>{skipped}.

Exit	Action
0	Scan finished. Split the rows by the 範圍 column into a global table and a project table
2	Usage error. Report it as a defect in this skill and skip the settings check
3	The spec table is missing. Name the path it looked for and JSC_CONFIG_SPEC, then skip the settings check
other	Report the settings check as 無法驗證 with the exit code and stderr

Verdicts: ok, default (unset, default works), unset (optional, feature degrades), missing (required, skills break), invalid (set but fails verification), skipped (offline).

Add -o when Gitea is unreachable; the Gitea-dependent rows then come back skipped. Report those rows as 未取得結論 and never as passes.

Done when the summary line is read, the rows are split into the two scopes, and every missing and invalid row is named.

1.4 Orphan variables

Run {CLI_ROOT}/tools/scan-config.sh orphans — variables used in the source but absent from the spec table. Same exit codes as 1.3; exit 3 here also covers a missing plugins root, so name JSC_PLUGINS_ROOT in that case.

They are a maintenance note for the skill set, not a fault on this machine, so they never enter the 待修項目 table.

Done when the orphan list is returned or the check is reported as skipped with its reason.

2. Report the five blocks, then build the 待修項目 table

2.1 The five blocks

Report all five blocks per {CLI_ROOT}/templates/check-page.md: 技能版本 from 1.1, Hook 接線 from 1.2, 全域設定 and 自我設定 from 1.3's two scopes, and 未登錄變數 from 1.4. Step 1.4 is the only place the orphan list is collected, so leaving it out here drops it from the run entirely — it never enters the 待修項目 table of 2.2, which is exactly why it needs its own block.

The project rows carry the working directory in their heading. A project-scope result is meaningless without it, because the answer changes with every cd — so name the directory that step 1.3 scanned, even when the project table is empty.

When .env or .envrc exists in that directory, name the spec-table variables it overrides and state the value actually in effect. A global setting silently overridden here is the failure this check exists to catch.

2.2 The 待修項目 table

Save each collector's raw lines to a file, then run

{CLI_ROOT}/tools/build-todo.sh --config {scan-all 輸出} --wiring {cli}={status 輸出} --version {report 輸出}

one --wiring per detected CLI. The script merges the three sources and orders them missing → invalid → unwired → 落後. Nothing wrong → it prints one row whose class reads 無.

Exit	Action
0	Render the todo rows as the 待修項目 table and the summary line as 3.2's counts
2	Usage error. Report it as a defect in this skill; fall back to no 待修項目 table and say the merge did not run
3	An input file was unreadable. Name the file, rerun that one collector, and say so when it still fails
other	Report the merge as failed with the exit code, and keep 2.1's tables on screen

A check that step 1 reported as 無法驗證 contributes no rows. Say that in the report: an unverified check and a clean check look identical in this table, and only the sentence tells them apart.

Done when all five blocks of 2.1 are on screen with the scanned directory stated — 未登錄變數 included, showing either its rows or the reason 1.4 gave for skipping — and 2.2's 待修項目 table is on screen with its rows in that order, or 2.2's merge failure is reported with its reason while 2.1's blocks stay on screen.

3. Record, then hand off

3.1 Record

This run writes two pages, and they live in two different wiki repos. Resolve each repo on its own and never reuse one for the other.

The HASH — take it from the machine, do not compose it by hand. jsc-assist's MONITOR_{HASH} claims the same hash source and takes it in code, so the two pages only ever line up when this skill takes it the same way:

host=$(hostname 2>/dev/null || uname -n 2>/dev/null || printf 'unknown'); host=${host%%.*}
user=${USER:-$(id -un 2>/dev/null || printf 'unknown')}

${host%%.*} is the point of the snippet: hostname prints the FQDN on some machines and the short name on others, so a hand-written value gives one machine two pages that never merge again. Pass "{host}/{user}" to {JSC_ROOT}/jsc-gitea/tools/gitea.sh hash-id and use exactly what it prints. It is the host and the login account, not {owner}/{repo} — doctor checks a machine, and it has to work in directories that are not repositories at all.

CHECK_{HASH} — content page. Repo: {JSC_ROOT}/jsc-gitea/tools/gitea.sh wiki-repo CHECK. Write it through jsc-gitea:wiki and overwrite the whole page, because this page type keeps only the latest run of this one machine. Whole-page overwrite is correct here and forbidden on the page below.

CHECK_CONTENTS — contents page, in the contents repo. Repo: {JSC_ROOT}/jsc-gitea/tools/gitea.sh wiki-repo CONTENTS. Every contents page lives there now; it never falls back to JSC_WIKI_REPO_CHECK. It is an H1, a > preamble and one H2 block per machine — no markdown table anywhere on it. Do not hand-edit it — write the block with

{JSC_ROOT}/jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 "CHECK_{HASH}" {block file} {CLI_ROOT}/templates/check-contents.md

The block file holds the whole H2 block: the ## CHECK_{HASH} line, a blank line, then one bullet per field in the order {CLI_ROOT}/templates/check-contents.md lists them, written as - {欄位名}：{值} with a full-width colon. Every field of the template gets a bullet, HASH included — the heading is the key, and a field only in the heading is a field the next reader cannot read.

The script reads the page back, replaces this machine's block or appends it, then writes the whole page. That keeps the rule in one place: one block per run, never a whole-page overwrite, never another machine's block — those blocks are other people's records, and this run read them from nowhere else.

The key is the H2 heading, CHECK_{HASH}. It is the name of the content page this block points at: the literal CHECK_ plus exactly what hash-id printed — 40 uppercase hex characters, not shortened, not otherwise prefixed, not wrapped in a link, no date appended. The script compares the whole heading text after trimming, so the key and that heading must match character for character.

The page name is the key because it is the one value that does not move. It is decided by {host}/{user} alone, so it survives a changed GITEA_HOST, a JSC_WIKI_REPO_CHECK moved to another repo, and a different Gitea encoding of the page name — all of which change the URL. Key on anything holding a URL and the comparison never matches, so every run appends a second block for the same machine — silently, because the page still looks right.

1 is <key-col>, and it only matters while a page is still the old markdown table: it is the 1-based index of the column that held the identity, the [CHECK_{HASH}]({URL}) cell in column 1, whose text becomes the H2 heading when the script converts that table to blocks. On a page already in block form the script ignores it.

The 體檢頁 bullet stays the human-facing link and is never the key; the heading itself carries no link and no URL. Write the bullet as [CHECK_{HASH}]({absolute URL}) — text plus link, the one link form this skill set uses. The URL comes from {JSC_ROOT}/jsc-gitea/tools/gitea.sh wiki-url {CHECK repo} CHECK_{HASH} and is never composed by hand. Fetch it after CHECK_{HASH} is written: wiki-url exits 4 on a page that does not exist yet.

A same-wiki link form resolves only inside its own wiki, and the two pages are no longer in the same one. It fails without an error, reading on screen as plain text or a dead link, so nobody finds it and nobody fixes it.

Verify every link before writing it. Collect every URL heading into CHECK_{HASH} or into the CHECK_CONTENTS block, then hand the whole list to {JSC_ROOT}/jsc-gitea/tools/link-check.sh. It prints {OK|DEAD|SKIP}<TAB>{URL}<TAB>{reason} per line. Only exit 0 may be written.

Exit	Meaning	Action
0	Every link answers	Write the page
1	At least one link is unreachable	Write nothing, on either page. Report the DEAD lines to the caller
2	Usage error: no URL was given	Report it as a defect in this skill and pass the URLs
3	The list holds a Gitea URL but GITEA_HOST is unset	Skip both writes and put GITEA_HOST at the top of 待修項目. Never write without verifying
7	Gitea authentication failed	Stop and report the key problem. This is not a dead link

Exit 7 stays apart from exit 1 on purpose: with a dead key, Gitea's answer for a private repo looks the same as "page absent". Merge the two and one expired key marks every live page dead, and the blocks pointing at them get rewritten or dropped.

The script asks the API and never reads a web status code. A private repo's web URL answers 404 to a request with no credentials, so status codes turn good links into dead ones.

Exit	Meaning	Action
0	updated or added	Report which one it printed, with the repo and page it named
1	The page content could not be built, or the write failed	Nothing landed. Report it with the stderr, and keep 2.1's tables on screen. A page with no block to replace is not this case: the script appends instead
2	Usage error	Report it as a defect in this skill. Do not retry with guessed arguments. A {CLI_ROOT}/templates/check-contents.md that is not on disk also lands here — then name the path the script looked for, confirm the plugin install is complete, and rerun
3	No contents repo configured	Skip this write and put JSC_WIKI_REPO_CONTENTS at the top of 待修項目
4	Page absent and no template given	Unreachable the way this skill calls the script — the command above always passes {CLI_ROOT}/templates/check-contents.md. A template that is not on disk comes back as exit 2, not 4. So treat a 4 as a malformed call: report it as a defect in this skill, name the command that produced it, and do not retry with guessed arguments
7	Key invalid or no permission	Nothing was read and nothing written. Name the exit code and create nothing
8	Any other API failure	Same as 7: the old blocks are unknown, so name the exit code and create nothing

Exits 7 and 8 never mean the page is missing. Writing a fresh template over a directory whose blocks were never read wipes every other machine's block, with no merge and no backup behind it — which is exactly why the script creates a page only when its own read reported that page absent, and why it owns that branch instead of this prose.

wiki-repo exiting 3 means that page type has no wiki repo configured: JSC_WIKI_REPO_CHECK for the content page, JSC_WIKI_REPO_CONTENTS for the contents page. Print the tables, skip that one write, and put the unset variable at the top of 待修項目 — it is itself a finding, so a failed write never fails the health check. Any other non-zero exit from wiki-repo, wiki-url, hash-id or the wiki write is reported the same way: tables on screen, write skipped, exit code named.

3.2 Hand off

State the four counts from 2.2's summary line: required items missing, settings invalid, CLIs unwired, domains behind. Recommend /jsc-cli:setup when any of those is above zero. Never fix anything here.

Done when every link written into either page passed link-check.sh first — or the DEAD list is on screen and that write was skipped — each of the two pages is reported with its URL, or its skipped write is reported together with its reason, and the four counts are stated with the recommendation given or explicitly withheld.

3.3 Record how the run ended

This is the last thing this skill does, and it runs on every path out of the skill. Call

{JSC_ROOT}/jsc-hooks/tools/report-status.sh skill-end jsc-cli:doctor {status} {exit code} [detail]

{exit code} is the exit code of whatever decided the outcome, and 0 when nothing failed. {detail} is one short line, no more than 200 characters: the four counts fit there, the five blocks do not. If the script is not on this machine, skip this step in silence and finish the run as it stood — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.

This one call writes, and it is the only write this skill makes. It records what the run found; it changes no setting, no wiring and no version, so the read-only contract of the opening paragraph still holds.

status	When this skill uses it
ok	All four checks reached a conclusion, the five blocks and the 待修項目 table are on screen, and both pages were written
degraded	The checkup ran but part of it has no conclusion, and this is the common outcome for a read-only skill that cannot reach a source. Any check reported as 無法驗證 lands here — version-guard.sh report exiting non-zero, scan-config.sh exiting 3 on a missing spec table, wire-cli.sh status returning an unexpected code, a Gitea-dependent row coming back skipped in offline mode — and so does a wiki-repo exit 3 that skipped a page write, which this skill treats as a finding rather than a fault
failed	Reading the machine worked, then recording it broke on an error: link-check.sh, gitea.sh or wiki-contents.sh returned 7 on an invalid key, or 8 on any other API failure. Both are errors, never an absent page, and neither leaves a usable record
aborted	The user stopped the run before the record was written, for example by declining to supply GITEA_HOST and asking to end the checkup there

blocked has no place in this skill. Nothing gates a read-only checkup: a machine with no CLI installed, no plugin registry and no wiki repo still produces four findings, and reporting that as blocked would hide a run that did its whole job.

Done when exactly one skill-end line was recorded for this run, or the script was absent and the run finished without it.