---
phase: 32-list-overhaul-skill-hint-audit
plan: 03
subsystem: testing
tags: [skill-frontmatter, argument-hint, yaml, regression-test, plugin-skills]

# Dependency graph
requires:
  - phase: 32-list-overhaul-skill-hint-audit
    provides: D-12/D-13/D-14/D-15 argument-hint decisions, HINT-01..HINT-05 requirements
provides:
  - "Canonical `argument-hint` YAML key on all 17 plugin/spt/skills/*/SKILL.md files"
  - "`tests/skill_hints.rs` regression guard — fails CI if any skill drops the key or unquotes YAML-special chars"
  - "Pinned-value enforcement for the 6 D-12/D-13/D-14/D-15 mandated hints"
affects: [future-skill-additions, plugin-deploy, skill-loader-compatibility]

# Tech tracking
tech-stack:
  added: []  # Zero-dep upheld — hand-rolled YAML frontmatter parser, no serde_yaml
  patterns:
    - "Hand-rolled YAML frontmatter parser in Rust integration tests (no external YAML crate)"
    - "Three-tier regression guard: presence, quoting, pinned-values"
    - "RESEARCH §Example 3 reference implementation pattern (verbatim adaptation)"

key-files:
  created:
    - "tests/skill_hints.rs"
    - ".planning/phases/32-list-overhaul-skill-hint-audit/deferred-items.md"
  modified:
    - "plugin/spt/skills/list-ready/SKILL.md"
    - "plugin/spt/skills/list-live/SKILL.md"
    - "plugin/spt/skills/list-psyche/SKILL.md"
    - "plugin/spt/skills/commune/SKILL.md"
    - "plugin/spt/skills/psyche-download/SKILL.md"
    - "plugin/spt/skills/whoami/SKILL.md"
    - "plugin/spt/skills/listen/SKILL.md"
    - "plugin/spt/skills/live/SKILL.md"
    - "plugin/spt/skills/revive/SKILL.md"
    - "plugin/spt/skills/send/SKILL.md"

key-decisions:
  - "Open Question #3 resolution APPLIED: conservative quoting rule (flag any unquoted [ ] { } | # or unquoted :) — implemented in both Task 2 edits and Task 3 regression test"
  - "Zero-dep policy upheld — hand-rolled YAML frontmatter parser in tests/skill_hints.rs; no serde_yaml dep added to Cargo.toml"
  - "Three test functions instead of two — added pinned-value guard (argument_hint_keys_known_set) to catch regressions like commune reverting to <msg>"
  - "Pre-existing cargo test --lib failures (13 tests) logged to deferred-items.md per SCOPE BOUNDARY — unrelated to argument-hint frontmatter edits"

patterns-established:
  - "Skill-frontmatter regression guard: integration test enumerates plugin/spt/skills/*/SKILL.md via env!(CARGO_MANIFEST_DIR) + std::fs::read_dir, parses hand-rolled YAML, asserts invariants. Future skill additions auto-validated by cargo test."
  - "Conservative YAML quoting policy: any argument-hint value containing |, #, [, ], {, } gets double-quoted, including values that lead with < (which would be safe unquoted) — chosen for consistency over strict-safety minimum"

requirements-completed: [HINT-01, HINT-02, HINT-03, HINT-04, HINT-05]

# Metrics
duration: ~18min
completed: 2026-05-16
---

# Phase 32 Plan 03: Skill Frontmatter Audit + HINT-05 Regression Guard Summary

**All 17 plugin/spt/skills/*/SKILL.md files now declare `argument-hint`; tests/skill_hints.rs ships a three-tier regression guard (presence + YAML-quoting + pinned-values) using a hand-rolled YAML parser with zero new dependencies.**

## Performance

- **Duration:** ~18 min
- **Tasks:** 3
- **Files modified:** 10 SKILL.md edits + 1 new test file + 1 deferred-items log
- **Commits:** 3 (feat / style / test)

## Accomplishments

- HINT-01 + HINT-02 satisfied: 100% of skills have `argument-hint` frontmatter key (was 14/17 before — list-ready, list-live, list-psyche all missing).
- HINT-03 satisfied: commune (`<msg>` → `""`), psyche-download (`""` → `"[<id>]"`), whoami (`(no arguments)` → `""`) per D-12/D-13/D-14.
- HINT-04 satisfied: listen, live, revive, send wrapped in double quotes for conservative YAML-flow-array safety.
- HINT-05 satisfied: 3-test regression guard ships under `cargo test --test skill_hints`, all green.
- Negative-test sanity check passed: stripping `argument-hint` from clear-psyche/SKILL.md produced exact failure message `HINT-01 / HINT-02: skills missing argument-hint frontmatter key: ["clear-psyche"]` — guard fires on real violations.
- Zero new dependencies — hand-rolled YAML frontmatter parser, no `serde_yaml` added.

## Task Commits

1. **Task 1: Six mandatory SKILL.md argument-hint edits (HINT-02 ADDs + HINT-03 VALUE CHANGEs)** — `18c42b5` (feat)
2. **Task 2: Four optional argument-hint quoting cleanups (HINT-04 conservative)** — `77fb62f` (style)
3. **Task 3: Add tests/skill_hints.rs regression-guard integration test (HINT-05 / D-18)** — `d5eefb8` (test)

## Pre-edit value snapshot (audit trail per `<output>` requirement)

### Six mandatory-change files — pre-edit verbatim values

| Skill                  | Pre-edit `argument-hint:`  | Post-edit                            | Decision |
| ---------------------- | -------------------------- | ------------------------------------ | -------- |
| list-ready/SKILL.md    | (key absent)               | `"[--all] [--offline] [--here]"`     | D-15     |
| list-live/SKILL.md     | (key absent)               | `"[--all] [--offline] [--here]"`     | D-15     |
| list-psyche/SKILL.md   | (key absent)               | `"[--all] [--offline] [--here]"`     | D-15     |
| commune/SKILL.md       | `<msg>`                    | `""`                                 | D-12     |
| psyche-download/SKILL.md | `""`                     | `"[<id>]"`                           | D-13     |
| whoami/SKILL.md        | `(no arguments)`           | `""`                                 | D-14     |

### Four quoting-fix files — value content preserved verbatim inside added quotes

| Skill              | Pre-edit `argument-hint:`              | Post-edit                                  | Verbatim preserved? |
| ------------------ | -------------------------------------- | ------------------------------------------ | ------------------- |
| listen/SKILL.md    | `<id> [--reboot] [--block] [--once]`   | `"<id> [--reboot] [--block] [--once]"`     | YES                 |
| live/SKILL.md      | `<id> [--period <seconds>]`            | `"<id> [--period <seconds>]"`              | YES                 |
| revive/SKILL.md    | `<id> [--period <seconds>]`            | `"<id> [--period <seconds>]"`              | YES                 |
| send/SKILL.md      | `<target> [--block]`                   | `"<target> [--block]"`                     | YES                 |

All 4 quoting fixes were strictly mechanical — only the surrounding `"..."` were added; the value content was preserved character-for-character.

## Negative-test sanity check (Task 3 acceptance)

Performed: deleted `argument-hint: ""` line from `plugin/spt/skills/clear-psyche/SKILL.md`, re-ran `cargo test --test skill_hints every_skill_has_argument_hint`, observed:

```
thread 'every_skill_has_argument_hint' panicked at tests\skill_hints.rs:94:5:
HINT-01 / HINT-02: skills missing argument-hint frontmatter key: ["clear-psyche"]
test result: FAILED. 0 passed; 1 failed
```

The guard fires with a clear violators list as designed. clear-psyche/SKILL.md was restored from backup; test re-ran 3/3 green. The backup file was a tempfile (`/tmp/clear-psyche-backup.md`) and is not committed.

## `argument-hint` keys discovered count

`tests/skill_hints.rs::every_skill_has_argument_hint` enumerates exactly **17** skills (matches the `ls plugin/spt/skills/` count) and finds an `argument-hint` key on all 17 — zero missing. This validates the readdir walk reaches every skill.

## RESEARCH Open Question #3 resolution

**APPLIED conservative rule** in both production edits and regression test:
- Task 2 edits added quotes to listen/live/revive/send even though they lead with `<` (which is safe unquoted) — chose consistency over strict-safety minimum.
- Task 3 test `argument_hint_values_quote_yaml_special_chars` flags any value containing `[`, `]`, `{`, `}`, `|`, `#`, or unquoted `:` regardless of leading character. This locks future skill additions into the same conservative rule.

## Decisions Made

- **Open Question #3:** APPLIED conservative quoting. Both the 4 quoting fixes (Task 2) and the Rust regression test (Task 3) enforce: "any value with bracket/brace/pipe/hash gets quoted, full stop."
- **Three test functions instead of two:** plan called for "third test as pinned-value guard." Implemented as `argument_hint_keys_known_set` covering the 6 D-12/D-13/D-14/D-15 hints. This is the strongest of the three guards — catches semantic regressions (someone re-edits commune back to `<msg>`).
- **Zero-dep upheld:** hand-rolled `parse_frontmatter_keys` (40 LOC) handles the trivial single-line-keys-with-indented-continuations shape used by every SKILL.md. Both `\n` and `\r\n` line endings tolerated.

## Deviations from Plan

None of Rule 1/2/3 type — plan executed cleanly. The only minor deviation worth noting:

**1. [Cleanup — meta-mention, not a Rule violation] Removed literal string `serde_yaml` from docstring**
- **Found during:** Task 3 acceptance-criteria verification
- **Issue:** Initial docstring read `No \`serde_yaml\` dependency added` — `grep -c serde_yaml tests/skill_hints.rs` returned 1, violating the literal `equals 0` acceptance criterion (even though the mention was a comment).
- **Fix:** Reworded to `No external YAML crate dependency added` — semantically identical, satisfies the literal grep gate.
- **Files modified:** tests/skill_hints.rs (docstring only, no logic change)
- **Verification:** `grep -c serde_yaml tests/skill_hints.rs Cargo.toml` returns 0 for both.
- **Committed in:** d5eefb8 (Task 3 commit — happened before the commit was finalized)

---

**Total deviations:** 0 Rule-1/2/3 deviations. 1 cosmetic docstring tweak for grep-gate compliance.
**Impact on plan:** None — plan ran exactly as written, all acceptance criteria satisfied.

## Issues Encountered

**Powershell verification command false-negative (Task 1):** The plan's `<verify><automated>` block used a complex `Select-String -SimpleMatch` expression piped through PowerShell-via-Bash. Triple-escaping the regex through bash → PowerShell → Select-String produced false negatives even though the file content was correct. Cross-verified via direct `grep -n 'argument-hint' plugin/spt/skills/*/SKILL.md` — all 6 edits confirmed. The plan-prescribed verifier had a Bash-quoting bug; the actual content is correct. Did NOT modify the SKILL.md files based on the false negative.

**Pre-existing cargo test --lib failures:** Running the full `cargo test` suite revealed 13 pre-existing library test failures in `live::*`, `owl::resume`, `owl::plugin_session_start`, `common::owlery`. Verified pre-existing by running `cargo test --lib` BEFORE adding `tests/skill_hints.rs` — same 13 failures present. Symptom: `Os { code: 3, kind: NotFound }` (Windows `%LOCALAPPDATA%\spt\owlery\` runtime state). Plan 03 modifies only Markdown + adds one integration test — cannot have caused Rust-library failures. Logged to `.planning/phases/32-list-overhaul-skill-hint-audit/deferred-items.md` per SCOPE BOUNDARY. `cargo test --test skill_hints` exits 0 with 3/3 green — the regression guard itself is healthy.

## User Setup Required

None — no external service configuration required. The regression test runs under standard `cargo test`.

## Next Phase Readiness

- All 5 HINT-* requirements (HINT-01..HINT-05) shipped as a coherent surface.
- Future skill additions cannot land without an `argument-hint` key — `cargo test --test skill_hints` will fail at PR time.
- Deploy path (`docs/DEPLOY.ps1`) syncs `plugin/spt/skills/` to marketplace; the 10 SKILL.md edits will propagate on next deploy.
- Pre-existing `cargo test --lib` Windows-state failures recommended for a follow-up `/gsd-debug` or quick-fix invocation focused on test-isolation hygiene.

## Self-Check

Performed inline:

- `tests/skill_hints.rs` exists — verified via `git log d5eefb8` showing `create mode 100644 tests/skill_hints.rs`.
- All 10 SKILL.md files modified and committed — verified via `grep -n '^argument-hint:' plugin/spt/skills/*/SKILL.md` showing 17/17 keys present with correct values.
- Commits exist: `18c42b5`, `77fb62f`, `d5eefb8` — created in this session, visible in `git log --oneline`.
- `cargo test --test skill_hints` exits 0 with 3/3 green — verified twice (after Task 3 initial pass, and again after negative-test restore).
- Zero `serde_yaml` references in either Cargo.toml or tests/skill_hints.rs — verified via grep returning 0 for both files.

## Self-Check: PASSED

---
*Phase: 32-list-overhaul-skill-hint-audit*
*Plan: 03*
*Completed: 2026-05-16*