docs(lessons): record three patterns from 2026-06-21 audit session

- claude plugin validate --strict absent from standard test sweep
- gitleaks source/deployed config silent divergence risk
- shellcheck without -x blocks pre-commit on scripts using source

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gv5iNACZxumtF2k6TsK18q

LESSONS.md

@@ -86,6 +86,18 @@ Claude Code supports `model:` as a provider extension in SKILL.md frontmatter
 
 When asked to research skill sub-file best practices, the research sub-agent reported "Process goes in SKILL.md. Context goes in reference files" as if it were verbatim from the Claude Code docs or the Agent Skills spec. Checking agentskills.io directly showed the spec says: "There are no format restrictions" on the body. The principle is a reasonable synthesis, not a quoted rule — but it nearly landed in write-skill's constraints as authoritative spec language. Fix: always verify research agent claims against the primary source before encoding them as rules, especially for spec or documentation claims. Plausible synthesis is the hardest fabrication to catch because it's often correct in spirit.
 
+## 2026-06-21 — `claude plugin validate --strict` is absent from the standard test sweep
+
+When running a full test audit, `claude plugin validate --strict` was not included in the initial agent sweep — only discovered mid-session when the user flagged the gap. The command catches warnings that normal mode tolerates (missing `version` fields, non-agent `.md` files in `agents/`) and will cause CI to fail when strict mode is enforced in Chunk 6. Fix: include `claude plugin validate --strict` on all plugin paths and marketplace manifests as a named step in any plugin audit. It belongs in the pre-push hook alongside `check-manifests.sh` — currently only `check-manifests.sh` runs there. See `tests/test-plugin-validate.sh` (pending, Gitea issue #2).
+
+## 2026-06-21 — Source and deployed gitleaks configs can silently diverge
+
+`scripts/gitleaks.toml` (source, in git, deployed to repo root by `setup-gitleaks.sh`) and `.gitleaks.toml` (deployed root copy, read by the hook, also tracked in git) were found with different allowlist states — someone had updated the deployed file directly without updating the source. Running `setup-gitleaks.sh` again would overwrite the deployed file with the stale source, silently deleting the existing allowlist and re-exposing a known false positive as a blocking pre-commit failure. Fix: treat `scripts/gitleaks.toml` as the single source of truth; never edit `.gitleaks.toml` directly. When making allowlist changes, always update source and deployed copy together in the same commit. Longer-term fix: `setup-gitleaks.sh` should merge rather than overwrite, or detect divergence and warn when `.gitleaks.toml` is tracked in git.
+
+## 2026-06-21 — `shellcheck` without `-x` blocks pre-commit on any script using `source`
+
+The pre-commit hook ran `shellcheck "$f"` without `-x`. Without `-x`, shellcheck fires SC1091 for every `source` statement and exits non-zero, blocking the commit. This was a latent bug since the hook was written, only triggered when `install.sh` (which sources `deploy-manifest.sh`) was staged for the first time. Compounding it: the `# shellcheck source=` directive in `install.sh` pointed to `deploy-manifest.sh` (bare filename, resolved from CWD = repo root) rather than `scripts/deploy-manifest.sh` (correct repo-root-relative path), so even with `-x` the file wasn't found on the first attempt. Fix: always pass `-x` to shellcheck in hooks. When writing a `source=` directive, use a path that resolves correctly from the CWD where shellcheck will be invoked — verify with `shellcheck -x <file>` before committing.
+
 ## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts
 
 During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction.