@toolu/opencode 6.8.0

package/plugins/toolu-review/skills/review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: review
+description: Pre-push review mirroring CI code-review@v8 (+ Jev) so first push stays clean. Reviews correctness, security, performance, test coverage, doc accuracy, and tight assertions, then records push-review state. Use before pushing a feature branch, when asked to review before push, or when pr-babysit needs a reviewer. Explicit — does NOT auto-fire on edits.
+---
+
+# toolu-review:review
+
+A pre-push reviewer tuned to what this repo's CI Toolu Code Review action
+(`falconiere/toolu-ghactions/code-review@v8`, Jev-enabled; posts as
+`github-actions[bot]`) flags — run it locally so the verdict is clean on the
+first push instead of bouncing low/nit findings back as rework.
+
+## What it reviews
+
+Review `git diff <base>...HEAD` against these dimensions. Every finding blocks
+(the gate requires zero) — fix in code, do not suppress:
+
+1. **Correctness** — logic, edge cases, error handling (no swallowed errors, no
+   `@ts-ignore`/`eslint-disable`/`#[allow]` papering over a real problem).
+2. **Security** — input validation, injection, secrets, unsafe file/symlink ops.
+3. **Performance** — hot paths (e.g. per-render/per-hook work), needless spawns.
+4. **Test coverage for every NEW behavior** — a new code path without a colocated
+   real-data test is a finding. (The bot flagged a missing bats for an orphan
+   sweep on a prior PR — catch that class here.)
+5. **Doc/comment accuracy** — comments must match behavior; e.g. no "one-time" on
+   a block that runs every invocation; no stale paths after a move.
+6. **Tight test assertions** — assert the full identity, not a loose suffix
+   (`*/statusline/statusline.sh`, not `*/statusline.sh`).
+7. **In-session migration WARNs** — a breaking change (moved path, removed symlink)
+   must surface an actionable in-session hint, not a silent failure later.
+8. **Convention adherence** — follow `AGENTS.md` / related convention files the CI
+   action reads from the base ref (same bar as `code-review@v8`).
+
+## How to run
+
+**Commit the fix first, then review.** The gate binds `git diff <base>...HEAD` —
+the *committed* diff. State recorded while a fix is still uncommitted describes
+the pre-fix tree, so committing staleifies it and the push denies.
+
+1. Resolve the diff: `git diff --no-color <base>...HEAD` (base = the push-review
+   gate's base; the helper below resolves it the same way).
+2. Review every changed hunk against the checklist. Read surrounding code and
+   grep for usage before claiming a finding — no speculative nits.
+3. Fix accepted findings in code, commit them, re-review until none remain.
+4. Record the clean state for the push-review gate:
+
+   ```bash
+   # Codex
+   TOOLU_HOST_OVERRIDE=codex bash \
+     "${TOOLU_CONFIG_DIR:-${CODEX_HOME:-$HOME/.codex}}/toolu-review/write-state.sh" \
+     --findings-count 0 --reviewers '["toolu-review:review"]'
+
+   # Claude Code
+   TOOLU_HOST_OVERRIDE=claude bash \
+     "${TOOLU_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/toolu-review/write-state.sh" \
+     --findings-count 0 --reviewers '["toolu-review:review"]'
+   ```
+
+   Pass `--branch <name>` on a detached checkout — pr-babysit's
+   `git worktree add --detach` + `git push origin HEAD:<name>` contract — so
+   the state file is keyed to the branch the push targets; the push-review gate
+   resolves that same branch from the refspec. Omitting it there fails with
+   "not on a branch (detached HEAD?)".
+   Pass `--repo <path>` when the reviewed checkout is not the session's cwd —
+   a worktree, say. The gate reads the state file under the **pushed repo's own
+   root**, so a file written anywhere else is invisible to it. `--repo` defaults
+   to the cwd's repo root and the script fails with "not inside a git repo" when
+   the path given is not one. `$STATE_DIR`, when set, overrides the directory for
+   the writer and the gate alike.
+
+   `write-state.sh` is published below the active host's explicit config root,
+   as shown above, by the plugin's SessionStart hook. Always pass the matching
+   host override in the same command: plugin-root variables are lifecycle
+   context and are not reliable in ordinary shell calls.
+
+   It computes the gate's exact `diff_sha`/`base`/`slug`, sets `review_round`
+   (1 for a new `diff_sha`, +1 only when rewriting at the same one — the gate
+   caps at 5 rounds on an unchanged diff), and writes
+   the active host's `<repo root>/.claude/tmp/push-review/` or
+   `<repo root>/.codex/tmp/push-review/` path atomically as
+   schema `version: 2`, including `reviewed_files` — auto-computed from
+   `git diff --name-only <base>...HEAD` (sorted, unique); pass
+   `--reviewed-files a.ts,b.rs` only if the review genuinely covered a
+   different path set than the one auto-detected. The gate denies unless
+   `reviewed_files` matches the diff's changed paths exactly. Harmless no-op
+   when the toolu push-review gate is not installed (the file goes unread).
+
+If findings remain that you cannot fix (e.g. needs a human decision), record them
+with `--findings-count <n> --findings '<json>'` instead of 0 — the gate will then
+keep blocking the push, which is correct: open findings are not done.

package/plugins/toolu-review/skills/review/scripts/write-state.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+# write-state.sh — write the push-review state file the toolu push-review
+# gate validates (<host-dir>/tmp/push-review/<branch-slug>.json).
+#
+# The review JUDGMENT (which findings exist) belongs to the caller — the
+# `toolu-review:review` skill. This script does only the deterministic
+# bookkeeping: compute the gate's diff_sha/base/slug, bump review_round, and
+# write the JSON atomically.
+#
+# The base / diff_sha / slug / reviewed_files recipes are MIRRORS of the gate
+# in plugins/toolu/hooks/pre-tools/modules/push-review.sh — the cross-check in
+# scripts/__tests__/state-writer.bats asserts they produce identical SHAs (and,
+# for reviewed_files, an identical file list), so a drift in either recipe
+# fails CI. This mirror is deliberate (cross-plugin sourcing is barred here —
+# see spec Non-Goal 7): keep it local rather than sourcing toolu's diff-sha.sh.
+# Harmless no-op when the toolu gate is not installed (the file is simply
+# never read).
+#
+# Usage: write-state.sh --findings-count N [--reviewers JSON] [--findings JSON]
+#                       [--repo PATH] [--reviewed-files a.ts,b.rs]
+#   --findings-count  (required) integer; the gate allows push only when 0.
+#   --reviewers       (default ["toolu-review:review"]) JSON array.
+#   --findings        (default []) JSON array of {path,severity,text}.
+#   --repo            (default: the cwd's repo root) the checkout being reviewed.
+#                     Pass the worktree path when reviewing a worktree from a
+#                     session rooted elsewhere — the gate reads the state file
+#                     under the pushed repo's own root, so writing it anywhere
+#                     else is invisible to the gate.
+#   --branch          (default: the checked-out branch) the branch the push
+#                     targets. Required on a detached checkout — pr-babysit's
+#                     `git worktree add --detach` + `push origin HEAD:<branch>`
+#                     contract — and must name an existing refs/heads or
+#                     refs/remotes/origin ref. On an attached checkout it must
+#                     equal the checked-out branch: the gate keys the state
+#                     file by that branch and would never read a re-keyed one.
+#   --reviewed-files  (default: auto-computed) comma-separated list of paths,
+#                     overriding the auto-computed `git diff --name-only
+#                     <base>...HEAD` file list. The gate (schema v2) requires
+#                     `reviewed_files` (sorted, unique) to equal the diff's
+#                     changed paths exactly, so only override this when the
+#                     review genuinely covered a different path set than the
+#                     one auto-detected here.
+# Prints the state file path on success.
+set -o pipefail
+
+findings_count=""
+reviewers='["toolu-review:review"]'
+findings='[]'
+repo=""
+branch_arg=""
+reviewed_files_arg=""
+reviewed_files_set=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --findings-count) findings_count="$2"; shift 2 ;;
+    --reviewers)      reviewers="$2";      shift 2 ;;
+    --findings)       findings="$2";       shift 2 ;;
+    --repo)           repo="$2";           shift 2 ;;
+    --branch)         branch_arg="$2";     shift 2 ;;
+    --reviewed-files) reviewed_files_arg="$2"; reviewed_files_set=1; shift 2 ;;
+    *) echo "write-state.sh: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$findings_count" ] || { echo "write-state.sh: --findings-count required" >&2; exit 2; }
+[[ "$findings_count" =~ ^[0-9]+$ ]] || { echo "write-state.sh: --findings-count must be an integer" >&2; exit 2; }
+command -v jq  >/dev/null 2>&1 || { echo "write-state.sh: jq required"  >&2; exit 2; }
+command -v git >/dev/null 2>&1 || { echo "write-state.sh: git required" >&2; exit 2; }
+
+# Repo root — MIRROR of push_target_root's fallback chain. The gate resolves
+# the root from the push command (`git -C <path> push`), so the writer must be
+# able to name the same checkout or the two disagree in a worktree.
+repo_root=$(git -C "${repo:-.}" rev-parse --show-toplevel 2>/dev/null || echo "")
+[ -n "$repo_root" ] || { echo "write-state.sh: ${repo:-$(pwd)} is not inside a git repo" >&2; exit 1; }
+
+# Branch — MIRROR of push_target_branch (lib/detect.sh): the checked-out
+# branch when attached; on a detached checkout the branch the push targets,
+# which the caller names with --branch because the writer never sees the push
+# command. Validated against real refs so a typo cannot key a state file the
+# gate will never read.
+branch=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
+  [ -n "$branch_arg" ] || { echo "write-state.sh: not on a branch (detached HEAD?) — pass --branch <name> naming the branch the push targets (git push origin HEAD:<name>)" >&2; exit 1; }
+  git check-ref-format --branch "$branch_arg" >/dev/null 2>&1 \
+    || { echo "write-state.sh: --branch '$branch_arg' is not a valid branch name" >&2; exit 1; }
+  if ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/$branch_arg" \
+     && ! git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/$branch_arg"; then
+    echo "write-state.sh: unknown branch '$branch_arg' (no refs/heads/$branch_arg or refs/remotes/origin/$branch_arg)" >&2; exit 1
+  fi
+  branch="$branch_arg"
+elif [ -n "$branch_arg" ] && [ "$branch_arg" != "$branch" ]; then
+  echo "write-state.sh: --branch '$branch_arg' does not match the checked-out branch '$branch'; the gate keys the state file by the checked-out branch" >&2; exit 1
+fi
+
+# Base branch — mirror of detect_base_branch's core; $PUSH_REVIEW_BASE matches
+# the gate's own override.
+base="${PUSH_REVIEW_BASE:-}"
+if [ -z "$base" ]; then
+  base=$(git -C "$repo_root" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's#refs/remotes/origin/##')
+  [ -n "$base" ] || base="main"
+fi
+
+# diff_sha — MIRROR of push-review.sh's current_diff_sha (cross-checked by
+# state-writer.bats).
+diff_sha=$(git -C "$repo_root" diff --no-color "${base}...HEAD" 2>/dev/null | git -C "$repo_root" hash-object --stdin 2>/dev/null || echo "")
+[ -n "$diff_sha" ] || { echo "write-state.sh: git diff ${base}...HEAD failed" >&2; exit 1; }
+
+# Refuse the empty-blob SHA: an empty diff against base means nothing diverged
+# (or a force-reset). The push-review gate treats this sentinel as never-matching
+# and denies, so writing a state file with it just yields a confusing
+# "review recorded" → "diff is empty" deny. Fail early with an actionable message.
+EMPTY_BLOB_SHA="e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
+if [ "$diff_sha" = "$EMPTY_BLOB_SHA" ]; then
+  echo "write-state.sh: diff against ${base} is empty; nothing to review yet" >&2
+  exit 1
+fi
+
+# reviewed_files — MIRROR of the gate's `changed_sorted` (push-review.sh):
+# auto-computed from the real diff's changed paths (sorted, unique) unless
+# --reviewed-files overrides it. The gate denies unless this list equals its
+# own `git diff --name-only` computation exactly, so both branches emit a
+# sorted-unique JSON array of strings.
+if [ "$reviewed_files_set" -eq 1 ]; then
+  reviewed_files_json=$(printf '%s' "$reviewed_files_arg" \
+    | jq -R 'split(",") | map(select(length > 0)) | unique')
+else
+  reviewed_files_json=$(git -C "$repo_root" diff --no-color "${base}...HEAD" --name-only 2>/dev/null \
+    | sort -u | jq -R -s 'split("\n") | map(select(length > 0))')
+fi
+# jq always prints at least "[]" on success, so empty stdout here only
+# happens on a real git/jq failure — surface it rather than writing a state
+# file with a silently-wrong (and gate-denying) reviewed_files.
+[ -n "$reviewed_files_json" ] || { echo "write-state.sh: failed to compute reviewed_files" >&2; exit 1; }
+
+# slug — MIRROR of push-review.sh:_branch_slug.
+slug=$(echo "$branch" | tr '/' '_' | tr -cd 'a-zA-Z0-9_-')
+[ -n "$slug" ] || slug="_default"
+
+# state_dir — MIRROR of the gate's resolution, including its $STATE_DIR override.
+# The plugin is self-contained, so mirror the core adapter's project-dir choice.
+project_dir="${TOOLU_PROJECT_CONFIG_DIRNAME:-}"
+if [ -z "$project_dir" ]; then
+  if [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || { [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ]; }; then
+    project_dir=.codex
+  else
+    project_dir=.claude
+  fi
+fi
+state_dir="${STATE_DIR:-$repo_root/$project_dir/tmp/push-review}"
+state_file="$state_dir/${slug}.json"
+mkdir -p "$state_dir" || { echo "write-state.sh: cannot create $state_dir" >&2; exit 1; }
+
+# review_round counts rewrites AT THE SAME diff_sha, so the gate's MAX_ROUNDS
+# cap means "reviewers keep finding issues in code that never changed". A
+# changed diff restarts at 1: the previous rounds judged different code, and
+# nothing ever resets the counter after a push, so carrying it forward made the
+# cap terminal for any branch that lived long enough.
+prev_round=0
+if [ -f "$state_file" ]; then
+  prev_sha=$(jq -r '.diff_sha // ""' "$state_file" 2>/dev/null || echo "")
+  if [ "$prev_sha" = "$diff_sha" ]; then
+    prev_round=$(jq -r '.review_round // 0' "$state_file" 2>/dev/null || echo 0)
+    [[ "$prev_round" =~ ^[0-9]+$ ]] || prev_round=0
+  fi
+fi
+review_round=$((prev_round + 1))
+
+reviewed_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+tmp="$state_file.tmp.$$"
+if ! jq -n \
+  --arg branch "$branch" \
+  --arg diff_sha "$diff_sha" \
+  --arg base "$base" \
+  --arg reviewed_at "$reviewed_at" \
+  --argjson reviewers "$reviewers" \
+  --argjson findings_count "$findings_count" \
+  --argjson findings "$findings" \
+  --argjson review_round "$review_round" \
+  --argjson reviewed_files "$reviewed_files_json" \
+  '{version:2, branch:$branch, diff_sha:$diff_sha, base_branch:$base,
+    reviewed_at:$reviewed_at, reviewers:$reviewers,
+    findings_count:$findings_count, findings:$findings, review_round:$review_round,
+    reviewed_files:$reviewed_files}' \
+  > "$tmp"; then
+  rm -f "$tmp"; echo "write-state.sh: jq failed (bad --reviewers/--findings/--reviewed-files JSON?)" >&2; exit 1
+fi
+mv "$tmp" "$state_file" || { rm -f "$tmp"; echo "write-state.sh: atomic mv failed" >&2; exit 1; }
+echo "$state_file"

package/plugins/ts-quality/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "ts-quality",
+  "version": "6.8.0",
+  "description": "TypeScript PostToolUse quality checks registered into the toolu hook engine.",
+  "author": {
+    "name": "Falconiere Barbosa",
+    "email": "hello@falconiere.io"
+  },
+  "homepage": "https://github.com/falconiere/toolu",
+  "repository": "https://github.com/falconiere/toolu.git",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "typescript",
+    "quality",
+    "hooks"
+  ],
+  "dependencies": [
+    {
+      "name": "toolu",
+      "marketplace": "toolu"
+    }
+  ]
+}

package/plugins/ts-quality/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "ts-quality",
+  "version": "6.8.0",
+  "description": "TypeScript PostToolUse quality checks registered into the toolu hook engine.",
+  "hooks": "./hooks/hooks.json"
+}

package/plugins/ts-quality/README.md

@@ -0,0 +1,24 @@
+# ts-quality
+
+TypeScript `PostToolUse` quality checks registered into the toolu hook engine.
+
+## Install
+
+```
+/plugin install ts-quality@toolu
+```
+
+Requires the `toolu` plugin.
+
+## What it provides
+
+Every TypeScript file the agent edits is checked on the spot, contributing to toolu's quality gate. The checks (assembled from ordered `hooks/concerns/` fragments into one module at `SessionStart`):
+
+- File / function line limits (config-driven).
+- No `../` relative imports — use the `@/` alias (only enforced when the project defines a `@/*` path alias in its tsconfig).
+- No `as` type assertions and no hand-rolled type guards — use a type guard / Zod schema.
+- Tests colocated in a flat `__tests__/`.
+- Duplicate-type detection across the tree, plus "does too much" / too-many-factories heuristics.
+- No `console` left in, no lint suppression, no thrown literals; React hooks/props, toast, and error-handling AST checks.
+
+The fragments register into the core toolu dispatcher and run only while this plugin is installed — uninstall it and the TypeScript rules vanish, fail-closed.

package/plugins/ts-quality/hooks/check-toolu.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Codex lacks a plugin-dependency manifest field. Warn when this dependent
+# plugin is installed without the toolu core, using Codex's authoritative list.
+set -u
+
+[ "${TOOLU_HOST_OVERRIDE:-}" != claude ] || exit 0
+[ -n "${PLUGIN_ROOT:-}" ] || exit 0
+command -v codex >/dev/null 2>&1 || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+installed=$(codex plugin list --json 2>/dev/null) || exit 0
+jq -e 'any(.installed[]?; .pluginId == "toolu@toolu" and
+  ((has("installed") | not) or (.installed == true)) and
+  ((has("enabled") | not) or (.enabled == true)))' \
+  <<<"$installed" >/dev/null 2>&1 && exit 0
+
+jq -n '{hookSpecificOutput:{
+  hookEventName:"SessionStart",
+  additionalContext:"WARN: this plugin requires the toolu core. Install it first with: codex plugin add toolu@toolu"
+}}'

package/plugins/ts-quality/hooks/concerns/00-preamble.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Post-tool check: TypeScript / TSX quality rules
+# Lightweight file-level checks (fast, no external tool invocations).
+# Project-agnostic: no-op outside TS projects; package-manager driven.
+#
+# Inputs (from parent dispatcher post-tools/mod.sh, via `export`):
+#   $tool_name     - name of the tool being invoked
+#   $input         - raw JSON payload on stdin
+#   $PROJECT_ROOT  - repository root
+
+: "${tool_name:=}"
+: "${input:=}"
+: "${PROJECT_ROOT:=$(pwd)}"
+
+# Core lib comes from the toolu dispatcher via TOOLU_LIB_DIR (set by
+# plugins/toolu/hooks/post-tools/mod.sh before registry dispatch). Outside
+# that pipeline there is no relative path to it — fail SOFT: a quality check
+# must never break a tool call by erroring.
+[ -n "${TOOLU_LIB_DIR:-}" ] && [ -f "$TOOLU_LIB_DIR/detect.sh" ] || exit 0
+# shellcheck source=../../../toolu/hooks/lib/detect.sh
+. "$TOOLU_LIB_DIR/detect.sh"
+# Threshold resolver (defaults + project/native overrides). Soft if absent.
+# shellcheck source=../../../toolu/hooks/lib/quality-config.sh
+[ -f "$TOOLU_LIB_DIR/quality-config.sh" ] && . "$TOOLU_LIB_DIR/quality-config.sh"
+# Multi-slot gate writer (entries keyed by file — one hook's failure no longer
+# clobbers another's). Soft if absent: fallbacks below keep the legacy
+# single-slot behavior when the toolu lib predates gate-file.sh.
+# shellcheck source=../../../toolu/hooks/lib/gate-file.sh
+[ -f "$TOOLU_LIB_DIR/gate-file.sh" ] && . "$TOOLU_LIB_DIR/gate-file.sh"
+command -v gate_record_failure >/dev/null 2>&1 || gate_record_failure() {
+  jq -n --arg reason "$4" --arg source "$3" --arg file "$2" --arg violations "$5" \
+    --arg updatedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{status: "failing", reason: $reason, source: $source, file: $file,
+      violations: $violations, updatedAt: $updatedAt}' > "$1"
+}
+command -v gate_clear_file >/dev/null 2>&1 || gate_clear_file() {
+  [ -f "$1" ] || return 0
+  local _src _file
+  _src=$(jq -r '.source // ""' "$1" 2>/dev/null || echo "")
+  _file=$(jq -r '.file // ""' "$1" 2>/dev/null || echo "")
+  if [ "$_src" = "$3" ] && [ "$_file" = "$2" ]; then
+    jq -n --arg source "$3" --arg updatedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      '{status: "passing", source: $source, updatedAt: $updatedAt}' > "$1"
+  fi
+}
+command -v ts_max_file_lines        >/dev/null 2>&1 || ts_max_file_lines()        { echo "${DEFAULT_TS_MAX_FILE_LINES:-300}"; }
+command -v ts_max_fn_lines          >/dev/null 2>&1 || ts_max_fn_lines()          { echo "${DEFAULT_TS_MAX_FN_LINES:-60}"; }
+command -v ts_max_file_lines_source >/dev/null 2>&1 || ts_max_file_lines_source() { printf 'default'; }
+# Boolean flag reader (e.g. noMocks) — falls back to the caller's default when
+# quality-config.sh predates this reader.
+command -v quality_flag >/dev/null 2>&1 || quality_flag() { printf '%s' "$3"; }
+# count_code_lines comes from detect.sh (sourced above) — no fallback needed.
+
+# Load the merged config ONCE in this shell so TOOLU_CFG_LOADED sticks for
+# the threshold lookups below — each runs in a $(...) subshell that inherits it
+# and skips re-merging (otherwise every wrapper re-spawns the jq merge).
+command -v toolu_load_config >/dev/null 2>&1 && toolu_load_config 2>/dev/null || true
+
+# Exit early if this isn't a TypeScript project.
+[ "$(detect_ts)" = "ts" ] || exit 0
+
+# Exit if no package manager is detected — we cannot recommend a typecheck command.
+pm="$(detect_node_pm)"
+[ -n "$pm" ] || exit 0
+command -v "$pm" >/dev/null 2>&1 || exit 0
+
+# Resolve the project's typecheck command per package manager.
+typecheck_cmd() {
+  case "$1" in
+    bun)  echo "bun run typecheck" ;;
+    pnpm) echo "pnpm -w typecheck" ;;
+    yarn) echo "yarn typecheck" ;;
+    npm)  echo "npm run typecheck" ;;
+    *)    echo "$1 run typecheck" ;;
+  esac
+}
+TYPECHECK_CMD="$(typecheck_cmd "$pm")"
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+fp_from_input=""
+if [[ "$tool_name" == "Write" || "$tool_name" == "Edit" || "$tool_name" == "MultiEdit" ]]; then
+  fp_from_input=$(echo "$input" | jq -r '.tool_input.path // .tool_input.file_path // .tool_input.target_file // empty' 2>/dev/null || echo "")
+fi
+FILE_PATH="${CLAUDE_FILE_PATHS:-$fp_from_input}"
+
+# A deletion (or the source side of a move) no longer exists to lint, but any
+# gate entry previously owned by this path must be removed. The normalized
+# dispatcher exports these fields and also embeds them in tool_input so the
+# assembled module remains independently testable.
+EDIT_OPERATION="${TOOLU_EDIT_OPERATION:-$(echo "$input" | jq -r '.tool_input.toolu_edit_operation // ""' 2>/dev/null || echo "")}"
+EDIT_MOVED_TO="${TOOLU_EDIT_MOVED_TO:-$(echo "$input" | jq -r '.tool_input.toolu_edit_moved_to // ""' 2>/dev/null || echo "")}"
+if [[ "$EDIT_OPERATION" == delete || -n "$EDIT_MOVED_TO" ]]; then
+  if [[ -n "$FILE_PATH" && "$FILE_PATH" =~ \.(ts|tsx)$ ]]; then
+    GATE_FILE="$(toolu_project_state_root "$PROJECT_ROOT")/quality-gate-status.json"
+    gate_clear_file "$GATE_FILE" "$FILE_PATH" "ts-quality-hook"
+  fi
+  exit 0
+fi
+
+[[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]] && exit 0
+[[ ! "$FILE_PATH" =~ \.(ts|tsx)$ ]] && exit 0
+
+# Skip files inside git linked worktrees — quality state is for the main checkout only.
+# One git call, one dirname: --git-dir + --git-common-dir come back on two lines.
+_file_dir="$(dirname "$FILE_PATH")"
+_file_git_dir=""; _file_common_dir=""
+{ IFS= read -r _file_git_dir; IFS= read -r _file_common_dir; } < <(
+  git -C "$_file_dir" rev-parse --path-format=absolute --git-dir --git-common-dir 2>/dev/null
+)
+_file_git_dir="${_file_git_dir%/}"
+_file_common_dir="${_file_common_dir%/}"
+if [[ -n "$_file_git_dir" && -n "$_file_common_dir" && "$_file_git_dir" != "$_file_common_dir" ]]; then
+  exit 0
+fi
+
+MESSAGES=""
+# Separator is a REAL newline. It used to be a literal backslash-n inside double
+# quotes, which jq then encoded as "\\n" — so every multi-line violation reached
+# the agent as one run-on line with a visible \n in it.
+add_error() {
+  MESSAGES="${MESSAGES}${1}"$'\n'
+}

package/plugins/ts-quality/hooks/concerns/10-imports.sh

@@ -0,0 +1,33 @@
+# --- Existing checks ---
+
+# The "../ import → @/ alias" guidance is only actionable when the project
+# actually defines a `@/*` path alias. In a repo that uses plain NodeNext
+# relative imports with no alias configured, the recommendation cannot be
+# followed, so flagging `../` there is a false positive that blocks every edit
+# to such a file. Gate the check on the alias existing: walk up from the edited
+# file to PROJECT_ROOT for a tsconfig whose compilerOptions.paths declares a
+# `@/`-prefixed key. Tolerant of a missing / JSONC / oddly-shaped tsconfig (jq
+# failure → treat as "no alias", so we never emit advice the project can't act
+# on).
+_ts_has_at_alias() {
+  local dir root cfg
+  dir="$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && pwd)" || return 1
+  root="$(cd "${PROJECT_ROOT:-/}" 2>/dev/null && pwd)" || root=""
+  while [ -n "$dir" ]; do
+    for cfg in "$dir/tsconfig.json" "$dir/tsconfig.base.json"; do
+      [ -f "$cfg" ] || continue
+      if jq -e '[(.compilerOptions.paths // {}) | keys[] | select(startswith("@/"))] | length > 0' "$cfg" >/dev/null 2>&1; then
+        return 0
+      fi
+    done
+    [ "$dir" = "$root" ] && break
+    [ "$dir" = "/" ] && break
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+if grep -q 'from ["'"'"']\.\./' "$FILE_PATH" 2>/dev/null && _ts_has_at_alias; then
+  add_error "Forbidden ../ import in $FILE_PATH — use @/ alias"
+fi
+

package/plugins/ts-quality/hooks/concerns/15-type-as.sh

@@ -0,0 +1,9 @@
+AS_LINES=$(grep -nE '\)[[:space:]]+as[[:space:]]+[a-zA-Z]|\bas[[:space:]]+any\b|\bas[[:space:]]+unknown\b|[a-zA-Z>][[:space:]]+as[[:space:]]+[A-Z]|[a-zA-Z>][[:space:]]+as[[:space:]]+(string|number|boolean|object|symbol|bigint|never|undefined|null|void)\b' "$FILE_PATH" 2>/dev/null \
+  | grep -vE '^[0-9]+:[[:space:]]*//' \
+  | grep -vE '\bas[[:space:]]+const\b' \
+  | grep -vE '\bimport\b|^[0-9]+:[[:space:]]*export[[:space:]]*(type[[:space:]]+)?\{' \
+  | head -5)
+if [[ -n "$AS_LINES" ]]; then
+  add_error "Forbidden 'as' type assertion in $FILE_PATH — use type guards or Zod"$'\n'"${AS_LINES}"
+fi
+

package/plugins/ts-quality/hooks/concerns/20-tests.sh

@@ -0,0 +1,26 @@
+# E2E specs follow a framework layout (e2e/specs/<feature>/*.spec.ts), not the
+# unit-test __tests__/ co-location model — exempt them from these rules.
+if [[ "$FILE_PATH" =~ \.(test|spec)\.(ts|tsx)$ && "$FILE_PATH" != */e2e/* ]]; then
+  if [[ "$FILE_PATH" != */__tests__/* ]]; then
+    add_error "Test file outside __tests__/: $FILE_PATH — move to sibling __tests__/ directory"
+  else
+    _after_tests="${FILE_PATH##*__tests__/}"
+    if [[ "$_after_tests" == */* ]]; then
+      _subdir="${_after_tests%%/*}"
+      if [[ "$_subdir" != "fixtures" && "$_subdir" != "helpers" && "$_subdir" != "utils" ]]; then
+        add_error "Test nested in __tests__/ subdirectory: $FILE_PATH — keep __tests__/ flat (only fixtures/helpers/utils subdirs allowed; no mocks/ — tests must exercise real data)"
+      fi
+    fi
+    # `%` (shortest suffix) resolves to the NEAREST __tests__, matching the
+    # `##` (last __tests__) used for the nested-subdir check above; `%%` would
+    # pick the OUTERMOST __tests__ and mis-validate a doubly-nested path.
+    _tests_dir="${FILE_PATH%__tests__/*}__tests__"
+    _parent_dir=$(dirname "$_tests_dir")
+    if ! find "$_parent_dir" -maxdepth 1 -type f \( -name "*.ts" -o -name "*.tsx" \) \
+        ! -name "*.test.*" ! -name "*.spec.*" ! -name "*.d.ts" 2>/dev/null | grep -q . \
+       && ! find "$_parent_dir" -maxdepth 1 -type d ! -name "__tests__" ! -name "." 2>/dev/null | grep -q .; then
+      add_error "Test not co-located with source: $FILE_PATH — __tests__/ must be at the same level as the code it tests"
+    fi
+  fi
+fi
+

package/plugins/ts-quality/hooks/concerns/25-size-file.sh

@@ -0,0 +1,40 @@
+# Resolve the limit AND where it came from in one pass (avoids running the
+# override/native lookups twice). Contract: ts_max_file_lines_resolved prints
+# exactly "<int> <source>" where <source> is ONE token (override|native|default)
+# — the two-field `read` below relies on it; a multi-word source would spill
+# into TS_MAX_SRC and break the case arms.
+TS_MAX_FILE=""; TS_MAX_SRC="default"
+if command -v ts_max_file_lines_resolved >/dev/null 2>&1; then
+  read -r TS_MAX_FILE TS_MAX_SRC <<<"$(ts_max_file_lines_resolved)"
+else
+  TS_MAX_FILE=$(ts_max_file_lines)
+fi
+[ -n "$TS_MAX_FILE" ] || TS_MAX_FILE="${DEFAULT_TS_MAX_FILE_LINES:-300}"
+[ -n "$TS_MAX_SRC" ] || TS_MAX_SRC="default"   # empty read -> case must still pick a branch
+TS_LINE_COUNT=$(count_code_lines "$FILE_PATH")
+if [[ "$TS_LINE_COUNT" -gt "$TS_MAX_FILE" ]]; then
+  _split_hint="split into smaller modules"
+  _linter="$(detect_ts_linter)"
+  if [ -n "$_linter" ]; then
+    # Only claim the linter owns the limit when the limit truly came from its
+    # config; if a linter is present but its config isn't machine-readable
+    # (e.g. .eslintrc.cjs / eslint.config.js), say so instead of contradicting.
+    case "$TS_MAX_SRC" in
+      native)  _split_hint="$_split_hint ($_linter enforces this max-lines limit)" ;;
+      default)
+        # Biome has no max-lines rule at all, so "unparsed config form" would be
+        # misleading for it — say so plainly. ESLint/oxc do have max-lines, so
+        # there the limit genuinely could have come from an unreadable config.
+        if [ "$_linter" = "biome" ]; then
+          _split_hint="$_split_hint (biome has no max-lines equivalent — gate uses the ${TS_MAX_FILE}-line default)"
+        else
+          _split_hint="$_split_hint ($_linter is present but the gate's limit didn't come from its config (unparsed config form or a per-glob override) — gate uses the ${TS_MAX_FILE}-line default; align them)"
+        fi
+        ;;
+    esac
+  fi
+  _approx=""
+  has_unterminated_block "$FILE_PATH" && _approx=" (size approximated — an unterminated /* or a string containing /* may be affecting the count)"
+  add_error "TS file exceeds ${TS_MAX_FILE}-line limit: $FILE_PATH ($TS_LINE_COUNT code lines, blanks/comments excluded)${_approx} — $_split_hint"
+fi
+

package/plugins/ts-quality/hooks/concerns/30-size-fn.sh

@@ -0,0 +1,53 @@
+TS_MAX_FN=$(ts_max_fn_lines)
+# Brace-depth fn-length counter — mirrors rust-quality.sh so TS and Rust measure
+# the same way. The end of a function is found by counting brace depth from the
+# fn's own line (single-line "..."/'...'/`...` string and quote char-literal
+# contents stripped first), so a method inside a class/object is measured to ITS
+# own indented close, an inner if/for/switch close can't end the range early, and
+# a column-0 `}` inside a template literal no longer cuts the range short — the
+# bugs the old `^}` col-0 marker had. Three start forms: `function` declarations,
+# `const NAME = (…) =>` / `= function` expressions (params may span lines), and
+# class/object methods `name(…) {` (control-flow keywords excluded so their
+# blocks aren't mistaken for methods). Known limitation (same as Rust): a brace
+# inside a MULTI-LINE template/string still leaks into the count — an unbalanced
+# one leaves the fn unmeasured (fail-open), never falsely flagged short.
+LONG_FUNCS=$(awk -v max="$TS_MAX_FN" -v q="'" '
+  function strip(l) {
+    gsub(/\\"/, "", l)            # escaped double quotes
+    gsub(/"[^"]*"/, "", l)        # double-quoted string contents
+    gsub(q "[^" q "]*" q, "", l)  # single-quoted string / char-literal contents
+    gsub(/`[^`]*`/, "", l)        # single-line template-literal contents
+    return l
+  }
+  function fnstart() { infn=1; start=NR; name=$0; depth=0; opened=0 }
+  !infn {
+    s=strip($0)
+    if (s ~ /^[[:space:]]*(export[[:space:]]+)?(default[[:space:]]+)?(async[[:space:]]+)?function[ \t*]/) { fnstart() }
+    else if (s ~ /^[[:space:]]*(export[[:space:]]+)?(default[[:space:]]+)?const[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*[[:space:]]*=[[:space:]]*(async[[:space:]]+)?(\(|function[ \t(*])/) { fnstart() }
+    else if (s ~ /^[[:space:]]+(public[[:space:]]+|private[[:space:]]+|protected[[:space:]]+|static[[:space:]]+|async[[:space:]]+|override[[:space:]]+|readonly[[:space:]]+|get[[:space:]]+|set[[:space:]]+|\*[[:space:]]*)*[A-Za-z_$][A-Za-z0-9_$]*[[:space:]]*(<[^(){}]*>)?[[:space:]]*\(/ \
+         && s !~ /^[[:space:]]*(if|for|while|switch|catch|return|do|else|function|await|with|yield|throw|new|typeof|delete|void|in|of|case)[^A-Za-z0-9_$]/ \
+         && s !~ /=>/ \
+         && s !~ /;[[:space:]]*$/ \
+         && s ~ /\)([[:space:]]*:[^={]*)?[[:space:]]*\{[[:space:]]*$/) { fnstart() }
+  }
+  infn {
+    line=strip($0)
+    no=gsub(/\{/, "{", line); nc=gsub(/\}/, "}", line)
+    depth += no - nc
+    if (no > 0) opened=1
+    if (opened && depth <= 0) {
+      len=NR-start
+      if (len > max) printf "%s:%d (%d lines)\n", name, start, len
+      infn=0
+    }
+    # Release a brace-less single-line form (an expression-bodied arrow like
+    # `const sq = (x) => x * x;` or a parenthesized `const x = (a, b);`) on its
+    # terminating `;`. Mirrors rust-quality.sh: without this the start sticks and
+    # the NEXT real function is misattributed to this line — a bogus over-length.
+    if (!opened && $0 ~ /;[[:space:]]*$/) infn=0
+  }
+' "$FILE_PATH" 2>/dev/null)
+if [[ -n "$LONG_FUNCS" ]]; then
+  add_error "Function too long in $FILE_PATH (>${TS_MAX_FN} lines) — simplify or split"
+fi
+