Dhpk Harness Revise

---
name: dhpk-harness-revise
description: "Trims and validates the project harness (.claude/ or .codex/) for a harness audit request, after major rule additions, or as periodic maintenance. Detects the active environment and ensures consistency, hygiene, and trigger preservation. Not for: business code review. Output: inventory snapshot, gap list with severity, proposed fixes, validation results."
metadata:
  dhpk-invocation-class: "explicit-only"
---

# Harness Revise Skill

Methodology to trim, deduplicate, and validate the project harness without regressing trigger semantics. Supports Claude and Codex project harnesses.

## When to Use

- 當使用者想要檢視當前環境的harness配置，並且希望優化或修正其中的問題時。
- 定期維護，確保harness的健康和效率。

## When NOT to Use

- 不涉及harness的業務邏輯或產品代碼修改。
- 單純的業務功能開發或bug修復。

## Workflow

### Phase 0 — Detection

Before proceeding, identify the active harness directory and its primary rule file.
The shared resolution contract is
`@skills/dhpk-harness-revise/references/harness-directory-contract.md`.

1. **Contextual Hint**: When invoked by Claude Code through
   `/dhpk:dhpk-harness-revise`, pass the `.claude` hint to the shared contract.
2. **Set Variables**: Set `[HARNESS_DIR]`, `[MAIN_RULE]`, and `[SKILL_DIR]` from
   the contract before invoking any deterministic script.
3. **Script Boundary**: Pass the selected directory explicitly; the scripts'
   error for an ambiguous or missing directory is a blocking result.

Use the skill directory as the source of truth for scripts. Resolution order: an explicit `CLAUDE_SKILL_DIR` (set when invoked via the Skill tool), then the dhpk plugin install path (`CLAUDE_PLUGIN_ROOT`, set for plugin commands/hooks), then the repo-relative location for Codex:

```bash
SKILL_DIR="${CLAUDE_SKILL_DIR:-${CLAUDE_PLUGIN_ROOT:+${CLAUDE_PLUGIN_ROOT}/skills/dhpk-harness-revise}}"
SKILL_DIR="${SKILL_DIR:-.agents/skills/dhpk-harness-revise}"
```

> If `SKILL_DIR` resolves to `.agents/skills/dhpk-harness-revise` but that directory does not exist, you are running outside both the Skill-tool context and the dhpk plugin (neither `CLAUDE_SKILL_DIR` nor `CLAUDE_PLUGIN_ROOT` is set). The scripts ship inside the dhpk plugin — install it, or pass the script paths explicitly. Do not silently proceed as if the harness has no scripts.

### Phase 1 — Baseline (deterministic, scripts only)

Run all three scripts from the skill folder. Pass the detected harness directory.

```bash
# Example for Claude
bash "$SKILL_DIR/scripts/harness-inventory.sh" --dir .claude
bash "$SKILL_DIR/scripts/harness-scenarios.sh" --dir .claude
bash "$SKILL_DIR/scripts/test-harness.sh" --dir .claude
```

Acceptance gate before proposing fixes:
- `harness-scenarios.sh` must report `FAIL=0` (target ceiling; a newly adopted environment may start with failures representing gaps).
- `test-harness.sh` must report `PASS: [Target Count]` (e.g., 71/71 for Claude with `--dir .claude`; SKIP entries for T5.4/T9.3 are acceptable).
- `harness-inventory.sh` reports inform the report; handles missing `memory.md` or platform-specific configs.

If either suite fails before any fix is proposed, **stop and report the existing regression** — do not stack new changes on a broken baseline.

### Phase 2 — Gap Identification (AI judgment using gap taxonomy)

Walk the inventory output against the gap taxonomy below.

#### Gap taxonomy (canonical, ID-stable)

| ID | Symptom | Fix pattern |
|----|---------|-------------|
| **G1** | `post-edit-remind.sh` re-triggers on agent artifacts | Skip `[HARNESS_DIR]/artifacts/*` early |
| **G2** | Hooks parse JSON via `jq` only | Add `python3` fallback for portability |
| **G3** | `stop-review-reminder.sh` output is too verbose | Add condensed mode; default condensed unless `VERBOSE=1` |
| **G4** | `settings.json` (or config.toml) contains loose command wildcards | Refine to explicit matchers or `<verb>:*` colon-prefix |
| **G5** | Sentinel gates bypassed by terminal `git commit` | Add `.git/hooks/pre-commit` wrapper (mirroring harness hooks) |
| **G6** | Rules reference deleted skills | `harness-inventory.sh` `dangling_skills` count > 0 — prune rules |
| **G7** | `pre-bash-guard.sh` lacks coverage for dangerous operations | Extend with `rm -rf /`, `curl \| sh` patterns |
| **G8** | `test-harness.sh` uses outdated hook payload formats | Update to JSON payload contract: `{tool_input:{file_path}}` |
| **G9** | Cosmetic `echo` or dead-code in settings/hooks | Prune redundant entries from `settings.json` / `config.toml` |
| **G10** | Status line lacks sentinel badge | Ensure `statusline.sh` surfaces pending sentinels (e.g. `⚠2pending`) |
| **G11** | Hooks fire on unrelated files (e.g. CRLF fix on binary/code) | Narrow matchers to relevant extensions (e.g. `*.sh`) |
| **G12** | Trigger/Guard map duplication | Centralize logic in hooks; rules point to hooks as SSOT |
| **G13** | Monolithic `memory.md` overlaps module rules | Prune `memory.md` to a lightweight index/stub |

### Phase 3 — Proposal & User Approval

Produce a ranked table:

```md
| ID | Severity | Effort | Location | Action |
|----|----------|--------|----------|--------|
| G1 | MED | 4 lines | [HARNESS_DIR]/hooks/post-edit-remind.sh | Add artifacts skip |
| G9 | LOW | 2 lines | [HARNESS_DIR]/settings.json | Prune cosmetic echo |
```

Wait for user approval before editing.

### Phase 4 — Apply Fixes (with per-fix verification)

For each approved fix:
1. Read the target file.
2. Apply minimal change.
3. Re-run the matching deterministic script (with `--dir [HARNESS_DIR]`).
4. Revert and re-plan on regression.

### Phase 5 — Final Validation

After all fixes:

```bash
bash "$SKILL_DIR/scripts/harness-inventory.sh" --dir [HARNESS_DIR]
bash "$SKILL_DIR/scripts/harness-scenarios.sh" --dir [HARNESS_DIR]
bash "$SKILL_DIR/scripts/test-harness.sh" --dir [HARNESS_DIR]
```

Then spawn the `code-reviewer` agent on the diff scope.

## Output

Include, in order:
1. **Active Harness**: Detected directory and main rule file.
2. **Baseline numbers**: metrics before optimization.
3. **Gap table**: using IDs G1-G13.
4. **Fixes applied**: file + line range.
5. **Post-fix numbers**: including deltas.
6. **Code-reviewer verdict**.
7. **Deferred items**.

## Anti-Patterns

- Hardcoding `.claude/` when running in `.codex/` or vice-versa.
- Modifying business code instead of harness assets.
- Inventing new IDs without updating the taxonomy.
- Translating zh-TW in project communication files (PRs/commits).

## Verification

- [ ] The active harness and main rule file were detected rather than assumed.
- [ ] All three deterministic baseline scripts passed before fixes, or the
      pre-existing failure was reported without stacking changes.
- [ ] Each applied fix was followed by its matching deterministic check.
- [ ] Final inventory, scenario, and harness tests cover the selected harness.
- [ ] The output lists deferred items and the code-reviewer verdict.