planning: record tee hardening review artifacts

Preserve issue status updates, follow-up issue plans, and adversarial validation artifacts produced while hardening the tee-piped-output workflow.

Author: cowwoc

.cat/issues/v2/v2.1/clarify-skill-launch-execution-continuation/index.json

@@ -0,0 +1,4 @@
+{
+  "status": "open",
+  "dependencies": []
+}

.cat/issues/v2/v2.1/clarify-skill-launch-execution-continuation/plan.md

@@ -0,0 +1,26 @@
+<!--
+Copyright (c) 2026 Gili Tzabari. All rights reserved.
+Licensed under the CAT Commercial License.
+See LICENSE.md in the project root for license terms.
+-->
+# Issue: clarify-skill-launch-execution-continuation
+
+## Type
+bugfix
+
+## Goal
+Update execution-model guidance so that after skill launch acknowledgment without completion artifacts, execution continues through first-use instructions rather than returning control to the user.
+
+## Pre-conditions
+- [ ] Reproduce the launch-only behavior with a failing regression test
+- [ ] Verify the failing test demonstrates missing continuation behavior
+
+## Post-conditions
+- [ ] execution-model.md explicitly defines continuation requirements after launch acknowledgment
+- [ ] When a skill returns only `Launching skill: ...`, execution proceeds by reading and running that skill's `first-use.md` contract in the same turn
+- [ ] Continuation logic includes a deterministic stop condition and does not loop indefinitely on repeated launch-only acknowledgments
+- [ ] If launch acknowledgment is returned but `first-use.md` cannot be loaded or is invalid, execution fails explicitly instead of silently succeeding
+- [ ] Continuation behavior is consistent for explicit `/skill` invocation and automatic skill invocation
+- [ ] Regression coverage verifies both continuation action and absence of “please rerun” fallback on the happy path
+- [ ] Regression coverage ensures launch-only responses do not terminate skill execution prematurely
+- [ ] `mvn -f client/pom.xml verify -e` passes

.cat/issues/v2/v2.1/document-cli-string-array-params/plan.md

@@ -0,0 +1,86 @@
+# Plan: Document CLI String[] Entry-Point Parameters
+
+## Goal
+
+Update `@param` Javadoc on every legitimate CLI `String[] args` parameter at the boundary between
+the JVM and internal Java code, following the new convention in `.claude/rules/java.md`:
+
+> Every positional element must be listed in order with an individual description. Every recognized
+> flag must be described separately. No element may be left undescribed or deferred to another method.
+
+The `refactor-instruction-test-runner-string-args` issue converts internal dispatch methods away
+from `String[]`. This issue is complementary: it improves the Javadoc on the methods that legitimately
+keep `String[]` because they sit at a shell-to-Java CLI boundary.
+
+## Parent Requirements
+
+None — code quality and maintainability.
+
+## Affected Methods
+
+### Hook entry points (`client/src/main/java/io/github/cowwoc/cat/claude/hook/`)
+
+Each hook class follows the pattern `main(String[] args)` → `run(scope, args, in, out)`.
+The `run()` method is the real CLI boundary; `main()` just delegates. Javadoc is needed on
+both if they carry any `@param args` description.
+
+| Class | Method |
+|-------|--------|
+| `HookRunner` | `execute(HookHandlerFactory, String[])` |
+| `PreToolUseHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `PreAskHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `PreReadHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `PreWriteHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `PreIssueHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `PostToolUseHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `PostToolUseFailureHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `PostReadHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `SessionStartHook` | `main(String[])`, `run(ClaudeHook, Path, String[], InputStream, PrintStream)` |
+| `SessionEndHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `UserPromptSubmitHook` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `EnforceStatusOutput` | `main(String[])`, `run(ClaudeHook, String[], InputStream, PrintStream)` |
+| `TokenCounter` | `main(String[])`, `run(JvmScope, String[], PrintStream)` |
+| `SubagentStartHook` | `main(String[])` |
+
+### Skill CLI entry points (`client/src/main/java/io/github/cowwoc/cat/claude/hook/skills/`)
+
+| Class | Method |
+|-------|--------|
+| `ClaudeRunner` | `run(ClaudeTool, String[], PrintStream)` |
+| `GetConfigOutput` | `getOutput(String[])`, `run(ClaudeTool, String[], PrintStream)` |
+| `GetStatuslineOutput` | `getOutput(String[])`, `run(ClaudeTool, String[], PrintStream)` |
+| `GetIssueCompleteOutput` | `getOutput(String[])`, `run(ClaudeTool, String[], PrintStream)` |
+| `GetAddOutput` | `getOutput(String[])`, `run(ClaudeTool, String[], PrintStream)` |
+| `SkillComparison` | `getOutput(String[])` |
+| `ExtractTurnsContent` | `main(String[])` |
+| `InstructionTestRunner` | `main(String[])` (top-level CLI; subcommands are covered by `refactor-instruction-test-runner-string-args`) |
+
+## Approach
+
+For each `String[] args` parameter, read the method body to discover:
+1. How many positional arguments it consumes (and from which indices)
+2. What each positional argument represents (name, type, valid values, sentinels)
+3. Which optional flags it recognizes and what they do
+
+Then write a `@param args` block with:
+- An `<ol>` listing positional elements **in order** (item 1 = `args[0]`, item 2 = `args[1]`, ...)
+- A `<ul>` for optional flags (if any), each individually described
+- Sentinel values called out explicitly (e.g., `{@code "none"}` when no value is available)
+
+`main(String[] args)` methods that simply delegate to `run()` with no additional parsing may
+carry a brief `@param args` that refers to the `run()` signature, rather than duplicating it.
+
+## Exclusions
+
+- Methods already covered by `refactor-instruction-test-runner-string-args`: the internal
+  `String[]` dispatch methods in `InstructionTestRunner`, `SprtStateManager`, and
+  `SprtIsolationManager` — those will be converted to named parameters, eliminating the `String[]`.
+- `AotTraining.main(String[])`: training harness, not a production CLI boundary.
+- Test classes.
+
+## Verification
+
+- Every `String[] args` parameter at a CLI boundary has a `@param` block that individually describes
+  each positional element and each recognized flag.
+- No element description defers to another method ("see handler for details").
+- `mvn -f client/pom.xml verify -e` passes with no Checkstyle or Javadoc errors.

.cat/issues/v2/v2.1/fix-sprt-api-error-retry/index.json

@@ -0,0 +1,3 @@
+{
+  "status" : "open"
+}

.cat/issues/v2/v2.1/fix-sprt-api-error-retry/plan.md

@@ -0,0 +1,86 @@
+# Plan: Fix SPRT API Error Retry
+
+## Goal
+
+When a claude-runner JSON output contains only API error responses (e.g., "API Error: 503 Service
+temporarily unavailable") with an empty `bashCommands[]`, the SPRT runner should detect this as an
+infrastructure failure and retry the run rather than recording a FAIL verdict. Transient API outages
+must not abort SPRT suites via the early-failure-detection threshold.
+
+## Parent Requirements
+
+None — testing infrastructure reliability fix.
+
+## Current State
+
+`InstructionTestRunner.runSprtLoop` runs each trial via `SprtGrader.gradeTc`, which invokes a
+grader agent. The grader sees empty `bashCommands[]` and marks assertions FAIL because no behavior
+was demonstrated. The SPRT runner counts these as real failures, triggering early abort after 4
+failures.
+
+`SprtGrader.invokeGrader` already retries on grader API errors (the grader process itself failing
+with exit code != 0 containing "API Error"). But the subject-under-test run — the claude-runner
+process that actually executes the test scenario — has no retry logic for API errors.
+
+## Root Cause
+
+The claude-runner JSON produced for the subject run contains:
+- `texts[]`: one or more entries with "API Error: 503 Service temporarily unavailable."
+- `bashCommands[]`: empty array
+- `toolUses[]`: empty array
+
+This is detectable. The grader correctly marks it FAIL (no behavior observed), but the SPRT loop
+should treat this as a retryable infrastructure error, not a behavioral failure.
+
+## Implementation
+
+### 1. Add API-error detection to `ClaudeRunner.ParsedOutput`
+
+In `ParsedOutput`, add a helper method:
+
+```java
+public boolean isApiError() {
+    return bashCommands.isEmpty()
+        && toolUses.isEmpty()
+        && texts.stream().anyMatch(t -> t.contains("API Error:"));
+}
+```
+
+### 2. Retry subject runs in `InstructionTestRunner`
+
+In the trial execution loop inside `runSprtLoop` (and any shared helper), after calling
+`runner.executeProcess(...)`, check `result.parsed().isApiError()`. If true:
+- Log a warning with the TC ID, trial number, and attempt number
+- Sleep `attempt * 5` seconds (same backoff as grader retries)
+- Retry up to `MAX_API_ERROR_RETRIES = 3` times
+- If all retries are exhausted, throw `IOException` (fail the batch, not just the trial)
+
+### 3. Update `SprtGrader.buildGraderPrompt`
+
+Add a note to the grader prompt: if `texts[]` contains only API errors and `bashCommands[]` is
+empty, the run is an infrastructure failure — do not grade it, throw an error instead. (This is a
+belt-and-suspenders measure in case a retried run still slips through.)
+
+## Test
+
+Run `mvn -f client/pom.xml verify -e` — all existing tests must pass.
+
+Run the full SPRT suite for `plugin/tests/rules/tee-piped-output` after the fix. The 4 false
+failures from the 503 outage must not recur for infrastructure reasons.
+
+## Files to Change
+
+- `client/src/main/java/io/github/cowwoc/cat/claude/hook/skills/ClaudeRunner.java` — add
+  `isApiError()` to `ParsedOutput`
+- `client/src/main/java/io/github/cowwoc/cat/claude/hook/skills/InstructionTestRunner.java` —
+  add retry loop around subject run execution
+- `client/src/main/java/io/github/cowwoc/cat/claude/hook/skills/SprtGrader.java` — add
+  belt-and-suspenders note to grader prompt
+
+## Post-conditions
+
+- `ClaudeRunner.ParsedOutput.isApiError()` exists and returns true iff texts contain "API Error:"
+  and both `bashCommands` and `toolUses` are empty
+- Subject runs that return only API errors are retried up to 3 times before failing the batch
+- SPRT suites are not aborted by transient 503 outages
+- All existing tests pass

.cat/issues/v2/v2.1/improve-tee-piped-output-rule/index.json

@@ -1,5 +1,7 @@
 {
-  "status" : "open",
+  "status" : "closed",
+  "resolution" : "implemented",
+  "target_branch" : "v2.1",
   "dependencies" : [ ],
   "blocks" : [ ]
 }

.cat/issues/v2/v2.1/index.json

@@ -23,6 +23,12 @@
     "codex-latest-only-release-alignment",
     "update-codex-0133-plugin-alignment",
     "update-ai-output-license-headers",
-    "require-javadoc-for-private-methods"
+    "require-javadoc-for-private-methods",
+    "fix-sprt-api-error-retry",
+    "refactor-instruction-test-runner-string-args",
+    "document-cli-string-array-params",
+    "normalize-frontmatter-key-casing",
+    "replace-claude-session-id-with-claude-code-session-id",
+    "clarify-skill-launch-execution-continuation"
   ]
 }

.cat/issues/v2/v2.1/normalize-frontmatter-key-casing/index.json

@@ -0,0 +1,7 @@
+{
+  "status" : "open",
+  "resolution" : "",
+  "target_branch" : "v2.1",
+  "dependencies" : [ ],
+  "blocks" : [ ]
+}

.cat/issues/v2/v2.1/normalize-frontmatter-key-casing/plan.md

@@ -0,0 +1,36 @@
+# normalize-frontmatter-key-casing
+
+## Goal
+
+All YAML frontmatter keys must use hyphen-separated lowercase (e.g., `main-agent`, `sub-agents`,
+`argument-hint`). Currently many files use camelCase keys (e.g., `mainAgent`, `subAgents`,
+`argumentHint`). This issue audits all files with frontmatter and renames camelCase keys to
+hyphen-separated lowercase.
+
+## Background
+
+The naming convention was added to `.claude/rules/naming-conventions.md` as part of
+`improve-tee-piped-output-rule`. All frontmatter keys in skills, agents, rules, and test files
+must follow the new convention going forward.
+
+## Acceptance Criteria
+
+- [ ] All `.md` files with YAML frontmatter in `plugin/` and `.claude/` have hyphen-separated
+      lowercase keys
+- [ ] Any Java code that reads frontmatter keys is updated to match the new key names
+- [ ] A migration script is added to `plugin/migrations/` to rename keys in existing files
+
+## Implementation Steps
+
+1. Find all `.md` files with YAML frontmatter:
+   ```bash
+   grep -rl "^---" plugin/ .claude/ | xargs grep -l "^[a-z][a-zA-Z]*:" 2>/dev/null
+   ```
+2. Identify all camelCase keys in use (e.g., `mainAgent`, `subAgents`, `argumentHint`,
+   `userInvocable`)
+3. Rename each key to its hyphen-separated equivalent in all files
+4. Update Java code in `client/` that reads these keys (e.g., `SkillMetadataExtractor`,
+   `GetSkill`, frontmatter parsers)
+5. Add migration script to `plugin/migrations/` that renames camelCase frontmatter keys in
+   all `.md` files
+6. Run all tests to verify no breakage

.cat/issues/v2/v2.1/refactor-instruction-test-runner-string-args/index.json

@@ -0,0 +1,3 @@
+{
+  "status" : "open"
+}