hooks/skills/hooks-install/SKILL.md

name, description

name

description

hooks-install

Wire jsc hooks (STE100 guard, session timer, skill usage logger, SDLC model gate, plugin version guard, post-deploy restart gate, comment scope scanner, language guard, write and commit guard) into every installed AI CLI, purging all pre-existing hooks first — third-party ones included, backed up before removal. Drive it per CLI through tools/wire-cli.sh purge, tools/wire-cli.sh, tools/wire-cli.sh status, tools/wire-cli.sh smoke and tools/scan-hook-errors.sh. Hand any hook error, wiring or runtime, to jsc-hooks:repair, which must finish with a PR against develop; aborting the rest of the install to start that repair is allowed. Use after installing or updating the jsc plugin set; not for writing new hooks.

hooks-install — wire jsc hooks into every installed CLI

Goal: make the nine hooks (ste100-guard.sh, session-timer.sh, skill-usage.sh, sdlc-gate.sh, version-guard.sh, restart-gate.sh, comment-scope.sh, lang-guard.sh, write-guard.sh) effective in every CLI, with nothing else wired alongside them.

Install on a clean slate. Every CLI is purged of all hooks first, third-party ones included, so a later failure has exactly one owner. tools/wire-cli.sh purge backs up every file it touches before it removes anything, so the removal stays reversible.

The wiring commands stored in user config use $JSC_HOME/current/jsc-hooks, not the versioned plugin cache path and not the development checkout. tools/wire-cli.sh {cli} creates or refreshes that symlink before it writes notify, shell aliases or Kiro hook JSON, then verifies the linked scripts exist. If the filesystem cannot create the symlink, the script must say so and explicitly fall back to the current root; it must never write a silent broken path. The bundled hooks/hooks.json follows the same rule: use ${CLAUDE_PLUGIN_ROOT} only where the host provides it, and fall back to $JSC_HOME/current/jsc-hooks for any other CLI reading the same manifest, so an unset Claude-only variable never expands into /hooks/....

Only claude has PreToolUse, PostToolUse and UserPromptSubmit, so only claude reports wired. On codex, copilot, antigravity and kiro neither the version guard, the post-deploy restart gate nor any mode of the write and commit guard can be wired at all, and the SDLC gate degrades to the skill-step check, so all four report degraded — report that gap as the script words it instead of implying every CLI is covered. On those four the restart gate blocks no skill call whatsoever: the state file is still written and still cleared at the next session start, so the restart itself rests on the jsc-cli:deploy closing message.

comment-scope.sh and lang-guard.sh both reach all five, wired at the same set of places, but on a different event and at a different moment each. Report the timing per CLI; never state it as one uniform behaviour:

CLI	Scanning moment	Wired through
claude	Per file, the instant it is written	PostToolUse
codex	End of every turn, over the whole git worktree	notify in config.toml
kiro	On every prompt submit, over the whole git worktree — it sees what the previous turn wrote	userPromptSubmit in .kiro/hooks/jsc-hooks.json
copilot, antigravity	Once, when the session ends	tools/jsc-wrap.sh teardown

The table above holds for both scanners. The sweep mode reads git diff HEAD, so its coverage matches what claude sees; only the feedback delay differs. Outside a git worktree sweep exits 0 in silence and nothing is scanned at all — say so when the user works outside git. Both prompt rule reminders still go into every rule file alongside the STE100 block, because a warning that arrives a turn late is worth less than not writing the offending text in the first place. The lock file still works on those four because the SDLC skills call sdlc-gate.sh lock {stage} directly — that call is where the capability-tag comparison happens, so the gate keeps its force even where the prompt hook cannot be wired. The gate needs $JSC_HOME/model-tags.tsv; when it is missing, report that jsc-cli:models (or jsc-cli/tools/model-tags.sh sync) must run once, because sdlc-gate.sh lock refuses to lock without it.

Treat any hook error as repair work, whether it appeared while wiring or while running. Stopping the remaining installs to start that repair is the right call; leaving a broken hook wired is not.

The detailed flow MUST run as a sub agent; the main agent only reports the summary.

Steps

1. Take the CLI list from the caller when it hands one over — jsc-cli:deploy passes the list it already detected, and probing the same five executables a second time buys nothing. Run jsc-cli/tools/detect-clis.sh yourself only when no list came in; that fallback is what keeps this skill usable when it is called on its own. The script always exits 0 and prints one name<TAB>path<TAB>version line per installed CLI. Done when you hold that list and have said which of the two ways produced it; when it is empty, report that no CLI was detected and stop.

2. Run the five-stage pipeline purge → wire → status → smoke → scan once per detected CLI. Run the first CLI's pipeline on its own, because tools/wire-cli.sh {cli} is what refreshes the shared $JSC_HOME/current/jsc-hooks link and two CLIs must not rewrite it at the same time; once that first pipeline has finished, run every remaining CLI's pipeline in parallel, one sub agent per CLI — the five stages of one CLI stay in this order, but different CLIs touch different config files and share nothing else. Every stage prints its verdict on its first line, so read that line and never infer the outcome from the prose below it.

   1. tools/wire-cli.sh purge {cli} — backs up every file it touches, removes all hooks, re-reads each file to confirm the removal, and restores the backup by itself when a check fails. Marker matching trims leading and trailing whitespace, so an indented or padded marker block is still removed as the same jsc-owned block. Exit 0 is purged, exit 3 is skipped (that CLI's executable is not on this machine, so skip its remaining stages too), exit 4 is failed and goes to step 3. Exit 2 is a bad CLI name, not a purge outcome — fix the name and rerun the stage.
   2. tools/wire-cli.sh {cli} — owns both the wiring and its verification: it refreshes the link, writes the config, alias or hook file inside a <!-- jsc-hooks --> (or # jsc-hooks) marker block, re-reads every file it wrote, confirms the block is present and correctly placed, and confirms the stored runtime paths resolve to existing scripts before it prints a success status. Exit 0 is wired, exit 1 is degraded and is the expected result on the four non-claude CLIs, exit 3 is skipped, exit 4 is failed and goes to step 3. Exit 2 is a bad CLI name — fix the name and rerun.
   3. tools/wire-cli.sh status {cli} — the read-only inventory of what the previous stage wrote. It writes nothing and runs no hook, so it is safe to run right after wiring. Exit 0 is wired, exit 1 is degraded, exit 3 is skipped, exit 5 is unwired, which names every missing item and means the wiring stage has to run again before you continue. Exit 2 is a bad CLI name. For codex this stage is the only one that reads the installed jsc-hooks manifest in the Codex plugin cache and reports a stale UserPromptSubmit command there, the one that expands ${CLAUDE_PLUGIN_ROOT} into /hooks/...; carry that item into the report.
   4. tools/wire-cli.sh smoke {cli} — runs every wired mode of all nine hooks once, plus each decision path of the work-package check, of the restart gate and of the write and commit guard. It catches what the wiring check cannot see: a hook that is wired correctly and still fails when it executes. It prints its own result-line count as lines<TAB>{count} and asserts that count against what it expected to run, so read the number from that line and never restate a number of your own. Exit 0 is ok, exit 4 is failed — either a hook errored or the line count did not match, and both go to step 3. Exit 2 is a bad CLI name.
   5. tools/scan-hook-errors.sh --cli {cli} — only claude keeps hook results in its native records and can answer clean or errors; codex, copilot, antigravity and kiro answer unavailable, and their runtime evidence comes from the smoke stage alone. Exit 0 covers both clean and unavailable, exit 1 is errors and every entry with jsc=true goes to step 3, exit 2 is a bad CLI name.

   Done when every detected CLI has exactly one verdict line per stage, no stage exited 2, the smoke stage's lines count matches its own assertion, and the four non-claude CLIs are reported as unavailable rather than clean.

3. For each error — a failed purge, a failed wiring, an unwired status, a failed smoke, or a scanned error with jsc=true — run tools/report-error.sh --hook {script name} --exit {code} --summary "{reason}" --cli {cli} with the script's [jsc] output on stdin, then hand the failure to jsc-hooks:repair, which MUST run as a sub agent and must finish by opening a PR against develop. Aborting the remaining installs here is allowed as long as the repair starts. Exit 0 with an ERROR_{HASH} page name and URL on stdout means the page was written; exit 0 with empty output means JSC_WIKI_REPO_ERROR and JSC_WIKI_REPO are both unset, so carry that reason into step 4 instead; exit 2 means the call itself was malformed — --hook or --summary is missing — so fix the arguments and rerun the same call; exit 4 means the wiki record did not land, so report the failure text and still start the repair — a page that could not be written is no reason to leave a broken hook wired. Exit 4 covers two cases, and the report has to say which: a failed write, or the script refusing to write the error directory page because it could not read the old one back. That directory is appended to, never overwritten: every row on it is somebody else's error report, so the script reads the page, adds this run's row, and writes the whole page. Only a genuine 404 (wiki-get exit 4) means the page is not there yet and lets it build one from the template. An invalid key (exit 7) or any other API failure (exit 8) leaves the old rows unknown, so it skips the directory write and names the code instead — writing a fresh template over a directory it never read would erase every earlier report, with no merge and no backup behind it. A scanned error with jsc=false belongs to a third-party hook: report it and leave it alone. Skip this step when every CLI passed all five stages. Done when every error carries one ERROR_{HASH} result — a page name and URL, or the recorded reason no page was written — and one repair PR URL against develop.

4. Report five results per CLI — purge, wiring, status, smoke, scan — each with the reason its script printed, plus the smoke lines count, any ERROR_{HASH} page name and every repair PR URL. Done when every detected CLI appears with one verdict per stage and every repair has a PR against develop.

Notes

• Every hook script accepts both stdin JSON and environment variables (JSC_CLI, JSC_SESSION_ID, JSC_SKILL, JSC_TOOL_NAME, JSC_TOOL_COMMAND, JSC_MODEL); jsc-wrap.sh sets the first two itself.
• session-timer.sh takes start (keep an existing start time), restart (always overwrite it, for a CLI with no session id — kiro), mark and report. wire-cli.sh picks the right one per CLI; do not hand-edit the generated hook files. start and restart also clear the restart gate whenever they decide this SessionStart is a new session, so the wiring of those two events is what lowers the gate after a restart — a CLI wired without them keeps the gate up until the user sets JSC_RESTART_GATE=off.
• restart-gate.sh blocks jsc skill calls while $JSC_HOME/restart-required.d/{cli} exists — one file per CLI, named after the CLI code — so a freshly deployed skill set is not used by a process still running the old one. Each CLI reads only its own file: another CLI's file never blocks this one, and a restart clears only the file of the CLI that restarted. jsc-cli:deploy writes the current CLI's file through restart-gate.sh require {install|update} [{domain}...] at the end of an install or update; restart-gate.sh report prints one line per file, so it is visible which CLIs still owe a restart. A leftover old-format single file at $JSC_HOME/restart-required blocks every CLI and is deleted on the next clear — transitional only, and hooks/restart-gate.sh records when it can be dropped. The gate matches skill names, not call chains, so a nested call to anything off the exemption list is blocked all the same; hooks/restart-gate.sh owns that list with a reason per entry, and jsc-meta/references/guidelines.md「部署後重啟閘門」carries the same list. Escape hatch: JSC_RESTART_GATE=off.
• write-guard.sh takes three blocking modes, wired on two PreToolUse matchers, so claude is the only CLI where any of it takes effect, plus a fourth mode, release, that is wired nowhere and is called by a skill itself. stage reads the stage lock that sdlc-gate.sh already owns and blocks Write, Edit and MultiEdit while plan or analyze holds it, because those two stages produce wiki pages rather than files. review reads the current skill — the environment variable first, then the record skill-usage.sh keeps — and blocks writes while jsc-review:code-review or jsc-review:api-doc runs, since both only report findings. It deliberately does not block jsc-review:comment-cleanup: that skill has to write, limited to comment lines, and deciding that limit needs per-language comment parsing of the whole proposed content, which would block legitimate cleanups more often than it caught bad ones — that boundary stays with the skill text and the later review. commit is wired on Bash and blocks a single command that stages everything and commits in one go, plus any commit message carrying simplified characters or mojibake, which it decides by calling lang-guard.sh rather than keeping a second word list. A git add -A split across two separate tool calls is not caught, on purpose: catching it needs cross-call state that the blocked operator has no way to clear. release deletes that recorded skill and always exits 0; jsc-review:code-review and jsc-review:api-doc call it once each as they hand their findings back. It exists because the record says which skill was loaded last, not which one is still running: both audit skills end by leaving the fixing to their caller, and without release every write that caller makes stays blocked for the whole TTL, with the escape hatch or a wait as the only way out — a gate must never lock away its own release. Escape hatch: JSC_WRITE_GUARD=off, which release ignores because clearing a record blocks nobody, plus JSC_WRITE_GUARD_TTL for how long a recorded skill counts as still running.
• purge reaches the user-level config only. Hooks that another plugin ships in its own hooks.json stay active, and uninstalling that plugin is the only way to clear them — say so when reporting, and treat their errors as third-party.
• Backups land in $JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/, one directory per purge run, under the original file names. Hand that path to the user whenever a purge removed something.
• status claude reads Claude Code's installed_plugins.json and checks the installPath that the CLI actually loads. It must not check only the hooks.json next to the wire-cli.sh that happens to be running, because a development checkout can otherwise hide a broken installed plugin.
• Never set JSC_READONLY=1 for this skill. wire-cli.sh refuses purge and wiring with exit 6 under that variable, which is exactly what a health check wants and exactly what an install must not have.
• smoke treats sdlc-gate.sh check exit 2 as healthy: that exit is the stage lock blocking a turn on purpose, not a runtime error. comment-scope.sh, lang-guard.sh and write-guard.sh exit 2 count as healthy for the same reason — the check found something and said so. Their no-argument mode has no file name during smoke and exits 0 in silence; sweep depends on the worktree it runs in, so it answers 2 whenever that worktree happens to carry an offending comment, a simplified character or a mojibake sequence, and write-guard.sh answers 2 whenever the machine happens to hold a plan stage lock or a recent audit skill. None of these is a broken hook.
• comment-scope.sh takes three modes: prompt (inject the rule summary at UserPromptSubmit), no argument at all (scan the file just written at PostToolUse, reading file_path from stdin JSON or JSC_CHANGED_FILE), and sweep [dir] (scan every file the git worktree changed, for the four CLIs with no post-tool hook). All scanning modes read only the lines a diff added, skip markdown and binary files, and turn off entirely with JSC_COMMENT_SCOPE=off. The rule text itself lives in one place only, jsc-review's references/comment-scope.md; never restate the list anywhere in this repo.
• lang-guard.sh takes the same three modes as comment-scope.sh and is wired at the same places, but it scans differently on purpose: it reads the whole file rather than comment lines only, and it does scan .md and plain-text files, because those are exactly the non-code output the rule targets. It flags three things — simplified characters (word list in hooks/simplified.txt, the single source of truth for this repo; a missing list skips that check in silence), mojibake (U+FFFD and double-encoding remnants), and non-UTF-8 encoding (decided by iconv; no iconv skips that check). It skips binaries, generated files, and the three files whose subject is those very characters (simplified.txt, ste100-guard.sh, lang-guard.sh). Turn it off with JSC_LANG_GUARD=off. The rule text lives only in jsc-meta's references/ste100.md.
• jsc-wrap.sh runs both sweeps after the CLI exits and always returns the CLI's own exit code. A sweep hit warns on stderr and changes nothing else — never let a language or comment warning turn a successful CLI run into a failed one.
• tools/report-error.sh is operator- or skill-invoked only. Never wire it to fire from a failing hook: hooks stay silent and exit 0, and a failing hook that reports itself can loop.
• Data lands in $JSC_HOME (default ~/.jsc), consumed by jsc-log:worklog and jsc-log:stats.