feature: enforce 250-character limit on skill descriptions

Extract description extraction, validation, and replacement logic from
instruction-builder bash pipelines into a standalone update-skill-description
Java CLI tool. Consolidate description parsing into SkillFrontmatter shared
utility. Enforce ???250-char limit in SkillFrontmatter, DescriptionOptimizer,
DescriptionTester, and SkillValidator.

Author: cowwoc

.cat/issues/v2/v2.1/enforce-description-length-limit/index.json

@@ -1,3 +1,5 @@
 {
-  "status" : "open"
-}
+  "status" : "closed",
+  "resolution" : "implemented",
+  "target_branch" : "v2.1"
+}

.cat/issues/v2/v2.1/enforce-description-length-limit/plan.md

@@ -21,3 +21,214 @@ character count, reject input, and prompt user to shorten before continuing.
 - [ ] No regressions to existing instruction-builder wizard flows
 - [ ] E2E verification: invoke instruction-builder with a description >250 chars and confirm hard reject
   occurs
+
+## Research Findings
+
+### Wizard (instruction-builder first-use.md)
+
+The skill description is embedded in the `INSTRUCTION_DRAFT` document as YAML frontmatter
+(`description: "..."`) generated by the design subagent in Step 2. The description is never collected
+interactively from the user — it is designed by the AI and written to `INSTRUCTION_DRAFT`.
+
+**Insertion point:** After current Step 3 (Compact-Output Pass, which normalizes the draft) and before
+current Step 4 (Write Draft to disk), a new step validates the description length. If it exceeds 250
+characters, the step displays the character count, rejects, and prompts the user to provide a shorter
+description (AskUserQuestion). Once accepted, the INSTRUCTION_DRAFT is updated before writing.
+
+**Renumbering scope:** Inserting the new step shifts Steps 4–12 to Steps 5–13. All cross-references in
+first-use.md must be updated. There are ~54 references to steps 4–12 that need renumbering.
+
+**Description extraction from INSTRUCTION_DRAFT:** Use grep/sed to extract the description from the in-
+memory `INSTRUCTION_DRAFT` string, since it hasn't been written to disk yet at the time of validation.
+
+### Java CLI Tools
+
+Three classes extract the skill description from YAML frontmatter via `extractDescription()`:
+
+| Class | Package | Visibility |
+|-------|---------|-----------|
+| `DescriptionTester` | `io.github.cowwoc.cat.hooks.skills` | `public` |
+| `DescriptionOptimizer` | `io.github.cowwoc.cat.hooks.skills` | `private` |
+| `SkillValidator` | `io.github.cowwoc.cat.hooks.skills` | `public` |
+
+All three use the same YAML extraction pattern and normalize whitespace before returning. The 250-char
+validation must be added after the `replaceAll("\\s+", " ").strip()` normalization call in each class.
+
+**Error message pattern:** "Description exceeds 250-character limit: {N} characters in '{skillPath}'.
+Shorten the description before using this tool."
+
+### Tests
+
+- `DescriptionTesterTest` and `SkillValidatorTest` can test `extractDescription()` directly (public).
+- `DescriptionOptimizerTest` must test via `getOutput()` with a temp skill file containing a long description.
+- Two boundary tests per class: exactly 250 chars (allowed) and 251 chars (rejected).
+
+**Minimal skill file for testing:** Must include valid YAML frontmatter with `---` delimiters and a
+`description:` field. Tests already use `Files.createTempDirectory("test-")` + `TestClaudeTool` pattern.
+
+## Jobs
+
+### Job 1: Java validation + tests
+
+**Source files to edit:**
+- `client/src/main/java/io/github/cowwoc/cat/hooks/skills/DescriptionTester.java`
+- `client/src/main/java/io/github/cowwoc/cat/hooks/skills/DescriptionOptimizer.java`
+- `client/src/main/java/io/github/cowwoc/cat/hooks/skills/SkillValidator.java`
+
+**Test files to edit:**
+- `client/src/test/java/io/github/cowwoc/cat/hooks/test/DescriptionTesterTest.java`
+- `client/src/test/java/io/github/cowwoc/cat/hooks/test/SkillValidatorTest.java`
+- `client/src/test/java/io/github/cowwoc/cat/hooks/test/DescriptionOptimizerTest.java`
+
+**Production changes:**
+
+In each of the three source files, locate `extractDescription()` and add the following validation
+block immediately after the `return rawDescription.replaceAll("\\s+", " ").strip();` line is
+computed (i.e., store in a variable first, then validate, then return):
+
+```java
+String description = rawDescription.replaceAll("\\s+", " ").strip();
+if (description.length() > 250)
+  throw new IllegalArgumentException(
+    "Description exceeds 250-character limit: " + description.length() + " characters in '" +
+    skillPath + "'. Shorten the description before using this tool.");
+return description;
+```
+
+Also update the `@throws IllegalArgumentException` Javadoc on `extractDescription()` in each class
+to cover both throw reasons:
+
+```java
+ * @throws IllegalArgumentException if no description field is found, or if the description
+ *                                  exceeds 250 characters after whitespace normalization
+```
+
+**Test changes:**
+
+In `DescriptionTesterTest`, add two new test methods:
+- `acceptsDescriptionOfExactly250Chars()` — writes a SKILL.md with a description that is exactly
+  250 characters (after normalization); asserts no exception is thrown (call
+  `handler.extractDescription(content, "SKILL.md")` directly; follow the existing test pattern using
+  `Files.createTempDirectory("test-desc-")` and `TestClaudeTool`)
+- `rejectsDescriptionExceeding250Chars()` — writes a SKILL.md with a 251-character description;
+  annotate with `@Test(expectedExceptions = IllegalArgumentException.class,
+  expectedExceptionsMessageRegExp = ".*exceeds 250-character limit.*")`; call
+  `handler.extractDescription(content, "SKILL.md")` directly
+
+In `SkillValidatorTest`, add the same two boundary tests (can call `extractDescription()` directly
+since it is public; follow the existing test pattern in that file).
+
+In `DescriptionOptimizerTest`, add the same two boundary tests via `getOutput()` (since
+`extractDescription()` is private). For the accept test, construct a 4-argument call to
+`handler.getOutput()` with: a temp SKILL.md file containing a 250-char description, a minimal valid
+eval-set JSON (`[{"query":"test","should_trigger":true},{"query":"other","should_trigger":false}]`),
+a model ID string (e.g., `"claude-sonnet-4-5"`), and `"1"` for max iterations. For the reject test,
+use the same 4-argument call with a 251-char description and annotate with
+`@Test(expectedExceptions = IllegalArgumentException.class,
+expectedExceptionsMessageRegExp = ".*exceeds 250-character limit.*")`.
+
+- Run `mvn -f client/pom.xml verify -e` — all tests must pass
+- Commit with type: `feature:` (new validation capability)
+
+### Job 2: Wizard validation step + renumbering
+
+All changes are to `plugin/skills/instruction-builder-agent/first-use.md`.
+
+**Step A — Insert new Step 4 after the current Step 3 section** (around line 283, before
+`### Step 4: Write Draft and Prepare Test Infrastructure`):
+
+```markdown
+### Step 4: Validate Description Length
+
+After compaction, extract the description from `INSTRUCTION_DRAFT` and enforce the 250-character limit.
+
+Extract the description from `INSTRUCTION_DRAFT` using a Bash heredoc and grep/sed:
+
+```bash
+DESCRIPTION=$(printf '%s' "${INSTRUCTION_DRAFT}" | \
+  sed -n '/^---/,/^---/p' | head -n -1 | tail -n +2 | \
+  grep -o 'description:.*' | head -1 | sed 's/description:[[:space:]]*//')
+DESC_LEN=${#DESCRIPTION}
+echo "Description length: ${DESC_LEN} characters"
+```
+
+If `DESC_LEN > 250`, display a hard-reject message and present AskUserQuestion:
+
+```
+REJECT: Description exceeds 250-character limit ({DESC_LEN} characters).
+
+Skill descriptions are used for intent routing and must remain concise.
+Current description:
+  {DESCRIPTION}
+
+Please provide a shorter version (≤250 characters).
+```
+
+```
+AskUserQuestion:
+  header: "Description Too Long"
+  question: |
+    The skill description is {DESC_LEN} characters, which exceeds the 250-character limit.
+    Skill descriptions are used for intent routing — keep them concise.
+
+    Current ({DESC_LEN} chars):
+      {DESCRIPTION}
+
+    Enter a shorter description (≤250 characters):
+  options:
+    - "Enter shorter description" (user types new description in a follow-up message)
+```
+
+After the user provides a shorter description, replace the description line in `INSTRUCTION_DRAFT`:
+
+```bash
+NEW_DESCRIPTION="<user-provided text>"
+INSTRUCTION_DRAFT=$(printf '%s' "${INSTRUCTION_DRAFT}" | \
+  sed "s|description:.*|description: ${NEW_DESCRIPTION}|")
+```
+
+Re-extract and re-check length. If still > 250, present the AskUserQuestion again (no limit on
+retries — require compliance before writing to disk).
+
+If `DESC_LEN ≤ 250`, continue to Step 5.
+```
+
+**Step B — Rename all step headers and update cross-references:**
+
+Rename step headers (`### Step N:`):
+- `### Step 4:` → `### Step 5:` (Write Draft)
+- `### Step 5:` → `### Step 6:` (Auto-Generate Test Cases)
+- `### Step 6:` → `### Step 7:` (SPRT Test Execution)
+- `### Step 7:` → `### Step 8:` (SPRT Failure Investigation)
+- `### Step 8:` → `### Step 9:` (Analyze via instruction-analyzer-agent)
+- `### Step 9:` → `### Step 10:` (Adversarial TDD Loop)
+- `### Step 10:` → `### Step 11:` (In-Place Hardening Mode)
+- `### Step 11:` → `### Step 12:` (Compression Phase)
+- `### Step 12:` → `### Step 13:` (Cross-File Reorganization)
+
+Update all inline cross-references (in-text mentions of step numbers). Apply renaming in reverse
+order (highest to lowest) to avoid double-substitution:
+- `Step 12` → `Step 13` (all occurrences)
+- `Step 11` → `Step 12` (all occurrences)
+- `Step 10` → `Step 11` (all occurrences)
+- `Step 9` → `Step 10` (all occurrences)
+- `Step 8` → `Step 9` (all occurrences)
+- `Step 7` → `Step 8` (all occurrences)
+- `Step 6` → `Step 7` (all occurrences)
+- `Step 5` → `Step 6` (all occurrences)
+- `Step 4` → `Step 5` (all occurrences)
+
+**Step C — Update Verification section** (near line 2100): Add a new verification item under the
+appropriate section (e.g., a new "Description validation" section or appended to the Compact-output
+section):
+
+```markdown
+### Description validation
+
+- [ ] New Step 4 rejects descriptions > 250 characters with hard reject (displays char count)
+- [ ] AskUserQuestion presented with current description and character count
+- [ ] INSTRUCTION_DRAFT updated with user-provided replacement before writing to disk
+- [ ] Descriptions of exactly 250 characters are accepted without prompting
+```
+
+- Commit with type: `feature:` (new wizard validation step)

.cat/issues/v2/v2.1/extract-instruction-builder-description-ops-to-java/index.json

@@ -0,0 +1,5 @@
+{
+  "status" : "closed",
+  "resolution" : "implemented",
+  "target_branch" : "v2.1"
+}

.cat/issues/v2/v2.1/extract-instruction-builder-description-ops-to-java/plan.md

@@ -0,0 +1,35 @@
+# Plan: extract-instruction-builder-description-ops-to-java
+
+## Type
+refactor
+
+## Goal
+Extract the description extraction, validation, and replacement bash operations in instruction-builder's
+Step 4 into a Java CLI tool, applying the llm-to-java policy to eliminate fragile grep/sed pipelines.
+
+## Parent Requirements
+None
+
+## Post-conditions
+- [ ] New Java CLI tool `update-skill-description` exists in `client/src/main/java/.../skills/`
+- [ ] Tool accepts the skill/instruction file content on stdin and a new description as a positional
+  argument; validates the description is ≤250 characters; replaces the `description:` frontmatter field;
+  outputs the updated content to stdout; exits non-zero with an error message if validation fails
+- [ ] `instruction-builder-agent/first-use.md` Step 4 bash block replaced with a single invocation of
+  the new CLI tool: `INSTRUCTION_DRAFT=$(printf '%s' "${INSTRUCTION_DRAFT}" | update-skill-description "${NEW_DESCRIPTION}")`
+- [ ] Unit tests cover: valid replacement, 250-char boundary accepted, 251-char rejected, missing
+  frontmatter error, missing description field error
+- [ ] All tests pass (`mvn -f client/pom.xml verify -e`)
+
+## Jobs
+
+### Job 1
+- Implement `UpdateSkillDescription` Java class with `getOutput(String[] args)` that reads stdin,
+  validates description length, replaces description in frontmatter, writes to stdout
+- Add `update-skill-description` launcher entry to the jlink build configuration
+- Add unit tests in `UpdateSkillDescriptionTest`
+
+### Job 2 (depends on Job 1)
+- Update `plugin/skills/instruction-builder-agent/first-use.md` Step 4 to replace the bash grep/sed
+  pipeline with a call to `update-skill-description`
+- Remove the `ESCAPED_DESCRIPTION` escaping block (now handled inside the Java tool)

client/build-jlink.sh

@@ -97,6 +97,7 @@ declare -a HANDLERS=(
   "write-and-commit:util.WriteAndCommit"
   "get-subagent-status:skills.GetSubagentStatusOutput"
   "extract-turns:skills.ExtractTurnsContent"
+  "update-skill-description:skills.UpdateSkillDescription"
 )
 
 # --- Logging ---

client/src/main/java/io/github/cowwoc/cat/hooks/skills/DescriptionOptimizer.java

@@ -15,8 +15,6 @@
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 
 import static io.github.cowwoc.requirements13.java.DefaultJavaValidators.requireThat;
 
@@ -54,13 +52,6 @@ public final class DescriptionOptimizer implements SkillOutput
    */
   private static final int MIN_EVAL_SET_SIZE = 2;
 
-  /**
-   * Pattern to extract the description field from YAML frontmatter.
-   * Handles both single-line and block scalar (>) formats.
-   */
-  private static final Pattern DESCRIPTION_PATTERN =
-    Pattern.compile("^description:\\s*>?\\s*(.+?)(?=^\\w|^---)", Pattern.MULTILINE | Pattern.DOTALL);
-
   private final ClaudeTool scope;
 
   /**
@@ -128,7 +119,7 @@ public String getOutput(String[] args) throws IOException
         ". Provide an absolute or relative path to a SKILL.md file.");
 
     String skillContent = Files.readString(skillFile);
-    String currentDescription = extractDescription(skillContent, skillPath);
+    String currentDescription = SkillFrontmatter.extractDescription(skillContent, skillPath);
 
     // Parse eval set
     JsonNode evalSetNode = scope.getJsonMapper().readTree(evalSetJson);
@@ -198,40 +189,6 @@ public String getOutput(String[] args) throws IOException
       trainSize, testSize, splitJson);
   }
 
-  /**
-   * Extracts the description value from YAML frontmatter.
-   *
-   * @param content   the full SKILL.md content
-   * @param skillPath the file path (for error messages)
-   * @return the extracted description text, with leading/trailing whitespace removed
-   * @throws IllegalArgumentException if no description field is found
-   */
-  private String extractDescription(String content, String skillPath)
-  {
-    int firstDash = content.indexOf("---");
-    if (firstDash < 0)
-      throw new IllegalArgumentException(
-        "No YAML frontmatter found in skill file: " + skillPath +
-        ". SKILL.md files must start with --- frontmatter.");
-
-    int secondDash = content.indexOf("---", firstDash + 3);
-    if (secondDash < 0)
-      throw new IllegalArgumentException(
-        "Unclosed YAML frontmatter in skill file: " + skillPath +
-        ". Frontmatter must be closed with ---.");
-
-    String frontmatter = content.substring(firstDash + 3, secondDash);
-
-    Matcher matcher = DESCRIPTION_PATTERN.matcher(frontmatter);
-    if (!matcher.find())
-      throw new IllegalArgumentException(
-        "No 'description:' field found in frontmatter of: " + skillPath +
-        ". Every SKILL.md must have a description field for intent routing.");
-
-    String rawDescription = matcher.group(1);
-    return rawDescription.replaceAll("\\s+", " ").strip();
-  }
-
   /**
    * Formats the optimization prompt from the parsed inputs and split data.
    *