config: align workflow conventions with deterministic enforcement

Broaden LLM-to-Java guidance, testing conventions, and update-client cache handling so future instruction work routes deterministic behavior through the runtime and harness.

Author: cowwoc

.cat/rules/common/naming-conventions.md

@@ -35,6 +35,28 @@ JSON field names in API output contracts (from Java CLI tools) use **snake_case*
 (e.g., `"issue_id"`, `"worktree_path"`, `"target_branch"`). This is consistent with the Configuration Reads
 table which already shows `target_branch` and `issue_id` in snake_case.
 
+## Frontmatter Keys
+
+YAML frontmatter keys in all file types (skill SKILL.md, agent `.md`, rule `.md`, test `.md`) use
+**hyphen-separated lowercase** (e.g., `main-agent`, `sub-agents`, `effort`, `model`, `argument-hint`).
+
+**Correct (hyphen-separated lowercase):**
+```yaml
+---
+main-agent: true
+argument-hint: "<cat_agent_id> <issue_id>"
+effort: medium
+---
+```
+
+**Incorrect (camelCase):**
+```yaml
+---
+mainAgent: true
+argumentHint: "<cat_agent_id> <issue_id>"
+---
+```
+
 ## All-Caps Shell Variables
 
 Shell environment variables use **SCREAMING_SNAKE_CASE** per POSIX convention (e.g., `WORKTREE_PATH`,

.cat/rules/include/failure-investigation.md

@@ -0,0 +1,53 @@
+---
+paths: ["plugin/**", "client/**"]
+---
+# Failure Investigation Convention
+
+## Never Assume — Always Investigate
+
+When a test run, build step, or tool invocation fails, **do not assume a cause**. Investigate
+the actual failure before taking action or changing code.
+
+Common assumptions that lead to incorrect fixes:
+- "The runner timed out" (might be a permission error, missing binary, or API failure)
+- "The test scenario is wrong" (might be an infrastructure issue or a real skill defect)
+- "It's a transient failure" (might be a consistent bug that needs fixing)
+- "The binary is missing" (might be a path resolution error)
+
+## Use `get-history-agent` for Session Failures
+
+When a runner or grader fails (`TC{N}: runner failed` or `TC{N}: grader failed`), use the
+`cat:get-history-agent` skill to inspect the session transcript before concluding anything.
+
+**CRITICAL timing**: Act immediately when you see a failure notification — do NOT wait for
+the batch to finish. Session files live inside the run worktree's isolated config directory
+(`${RUN_WORKTREE}/.cat/config/projects/...`). Once SPRT's cleanup step runs, the worktree
+is deleted and the session is unrecoverable.
+
+**Procedure when a runner/grader fails:**
+1. Kill SPRT immediately: `kill ${SPRT_PID}`
+2. Wait for monitor to stop
+3. Find the session:
+   ```bash
+   ENCODED=$(echo "${RUN_WORKTREE}" | sed 's|[/.]|-|g')
+   ls "${RUN_WORKTREE}/.cat/config/projects/${ENCODED}/"
+   ```
+4. Use `cat:get-history-agent` on the session ID to understand what actually happened
+5. Only after reading the session: form a hypothesis and fix
+
+## When Artifacts Are Already Gone
+
+If you missed the failure and the run worktree was cleaned up:
+- The session is unrecoverable — acknowledge this explicitly
+- Rerun SPRT and kill it immediately on the next failure occurrence
+- Do NOT hypothesize a fix based on the missing evidence
+
+## Scope
+
+This applies to all failure types encountered during work:
+- SPRT runner/grader failures
+- Build failures (`mvn verify` errors)
+- Hook failures
+- Test assertion failures
+
+The rule is: **read the evidence first, then conclude**.

.cat/rules/include/llm-to-java.md

@@ -1,14 +1,22 @@
 # LLM-to-Java Extraction Policy
 
-**MANDATORY goal:** When adding new features to the plugin or updating existing features, extract as much
-logic as possible from LLM skills into Java code. This applies to **all files in the skill's transitive
-reference graph**, rooted at `SKILL.md` — including `first-use.md` (loaded by the `SKILL.md` preprocessor
-directive), any `.md` file listed in `execution_context`, any referenced concept or rules file, and any
-Bash scripts invoked from skill steps.
-
-The aim is to make processes deterministic wherever possible. Only leave in the LLM layer:
+**MANDATORY goal:** When adding new features to the plugin or updating existing features, design the
+behavior as a whole Claude Code system, not as instruction text alone. Extract as much deterministic logic
+as possible from LLM skills, rules, and prompts into Java-backed components. This applies to **all files in
+the skill's transitive reference graph**, rooted at `SKILL.md` — including `first-use.md` (loaded by the
+`SKILL.md` preprocessor directive), any `.md` file listed in `execution_context`, any referenced concept or
+rules file, any Bash scripts invoked from skill steps, and any Claude Code component that can enforce the
+same goal more reliably.
+
+The aim is to achieve each instruction file's behavioral goal using the best mix of deterministic and LLM
+components. For instruction files and their transitive referenced content, convert deterministic portions to
+Java whenever possible to improve reliability and performance. Consider the whole enforcement surface:
+pre-tool hooks, post-tool hooks, session/subagent hooks, runtime guards, harness checks, deterministic
+graders, schema validators, parsers, command builders, migration utilities, and targeted tests. Only leave
+in the LLM layer:
 - Contextual decision-making that genuinely requires reasoning
-- Text output to the terminal
+- User-facing text generation or explanation
+- Policy guidance that cannot be enforced without semantic judgment
 
 ## What belongs in Java