refactor(harness): improve hooks and harness robustness and YAML parsing

[kyau]

This pull request introduces several improvements to the repository's developer tooling and harness validation scripts, with a focus on reliability, maintainability, and correctness. The main changes include a complete overhaul of the git hooks installation process, robust YAML frontmatter parsing for harness validation, and a suite of tests to ensure correct hook installation behavior. Additionally, ESLint and workflow configurations are updated to support these enhancements.

Git hooks installation and validation improvements:

• Replaces the previous per-file symlink mechanism in install-hooks.sh with git config core.hooksPath .github/hooks, eliminating issues with worktrees, symlink breakage, and file permission dirtiness. The script now only sets the hooks path and checks for the existence of the hooks directory.
• Updates documentation and checks in .opencode/commands/doctor.md to verify hooks installation via core.hooksPath rather than checking individual hook files.
• Adds a comprehensive shell test suite in tests/Shell/install-hooks_test.sh to verify correct installation, permissions, and handling of edge cases such as empty hooks directories.

Harness validation robustness and maintainability:

• Refactors .github/scripts/validate-harness.sh to require Bash 4+ and Node.js, replacing brittle awk/sed YAML parsing with a new Node.js script, frontmatter-parser.js, which uses js-yaml for robust YAML frontmatter extraction. This ensures correct handling of quoted values, scalars, comments, and CRLF line endings. [1] [2] [3]
• Converts all name registries and cross-reference lookups in validate-harness.sh to use Bash associative arrays for O(1) exact-match lookups, preventing regex injection and improving performance. [1] [2] [3] [4] [5]
• Adds a guard in validate-harness.sh to fail if no skills, agents, or commands are found, preventing vacuous passes.

Tooling and workflow updates:

• Adds js-yaml as a development dependency in package.json to support the new frontmatter parser.
• Updates eslint.config.mjs to correctly lint Node.js scripts in .github/scripts, allowing Node.js globals and disabling noisy console warnings.
• Adds a Shellcheck step to the CI workflow to lint shell scripts and hooks for best practices and errors.

Minor content and formatting fixes:

• Fixes YAML frontmatter quoting in skill files to ensure compatibility with strict YAML parsers. [1] [2]

---

Git hooks installation and testing:

• Overhauled install-hooks.sh to use git config core.hooksPath .github/hooks, removing all per-file symlink logic and related bugs.
• Added a shell test suite install-hooks_test.sh to verify correct installation, permissions, and handling of edge cases.
• Updated documentation and checks in doctor.md to reflect new installation method.

Harness validation robustness:

• Replaced fragile awk/sed YAML parsing in validate-harness.sh with a new Node.js-based frontmatter-parser.js using js-yaml for correct YAML frontmatter extraction. [1] [2]
• Switched all name registries and lookups in validate-harness.sh to Bash associative arrays for safe and fast cross-reference validation. [1] [2] [3] [4] [5]
• Added a guard to fail validation if no skills, agents, or commands are found.

Tooling and workflow:

• Added js-yaml to package.json for YAML parsing.
• Updated ESLint configuration for Node.js scripts.
• Added Shellcheck to CI workflow for shell script linting.

YAML formatting:

• Fixed YAML frontmatter quoting in skill files for parser compatibility. [1] [2]

Plan-by: glm-5.2
Acked-by: deepseek-v4-pro
Signed-off-by: kyau git@kyaulabs.com