From 4cbc993af49dcd0ea98a10826218291fba6de196 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 27 Jun 2026 19:04:20 +0000 Subject: [PATCH] docs: remove stale references to deleted setup scripts Update docs to reflect pre-commit migration and cleanup: - spec/overview.md: removed phantom test file references - ROADMAP.md: removed references to non-existent test files - LESSONS.md: removed reference to setup-hooks.sh bug Co-Authored-By: Claude Haiku 4.5 --- LESSONS.md | 8 ++++++-- docs/ROADMAP.md | 5 ++--- docs/spec/overview.md | 4 ++-- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/LESSONS.md b/LESSONS.md index 1e75083..1eef110 100644 --- a/LESSONS.md +++ b/LESSONS.md @@ -94,9 +94,13 @@ When running a full test audit, `claude plugin validate --strict` was not includ `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` +## 2026-06-21 — `shellcheck` without `-x` blocks pre-commit on any script using `source` (LEGACY SHELL HOOKS) -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 ` before committing. +**Status:** Historical. Shell-hook-based pre-commit was replaced by pre-commit framework (Chunk 5, .pre-commit-config.yaml). Modern repos no longer affected. Documented for reference when supporting legacy repos. + +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 in legacy shell hooks, 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. + +**Lesson for future work:** When writing a `source=` directive, use a path that resolves correctly from the CWD where shellcheck will be invoked — verify with `shellcheck -x ` before committing. Pre-commit framework hooks include `-x` by default in the ecosystem's shellcheck integration. ## 2026-06-22 — Plugin cache isolation rules out shared/ directories between skills diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 60de79d..dacd16e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -44,11 +44,10 @@ A parallel workstream (not a numbered chunk) that runs alongside the chunk seque **Pre-Chunk 6 test suite work** (no CI required — can be done now; see Gitea issue #2 for full context): - Fix U1 first: add gitleaks.toml allowlist entry for `docs/research/ai-coding-factory/ai-coding-factory-session.md:90` (`Token routing: Haiku/Sonnet/Opus` triggers `generic-api-key` false positive; pre-commit hook blocks commits on all machines with gitleaks installed) - `tests/test-plugin-validate.sh` — run `claude plugin validate --strict` on all plugins and marketplace manifests; add the same check to the pre-push hook alongside `check-manifests.sh` -- `tests/test-hook-integrity.sh` — verify `.git/hooks/pre-commit` is installed, executable, and contains the expected idempotency markers; distinct from `test-setup-hooks.sh` which tests the setup script, not the installed artifact -- `tests/test-gitleaks-scan.sh` — run `gitleaks detect` against the repo and assert exit 0; validates `gitleaks.toml` allowlist correctly suppresses known false positives (requires U1 fix first) +- `tests/test-pre-commit-installed.sh` — verify `.pre-commit-config.yaml` is present and hooks run successfully; validate pre-commit framework integration - `tests/test-inventory-crossrefs.sh` — run `inventory.sh` against the live repo; assert zero `../` cross-reference warnings in post-refactor skills; triage the 11 current warnings (U4: determine which are in Chunk 3 rebuild targets vs. post-refactor skills that should be self-contained) - `tests/run-all-tests.sh` — single entry point that runs every test in `tests/`; needed for both developer use and future CI integration -- Extend `test-governance-layer.sh` — add structural checks that CONTROLS.md-required controls are in place (gitleaks wired to pre-commit, hook executable, plugin validation passes strict mode); current checks verify governance files exist but not that controls are enforced +- Extend `test-governance-layer.sh` — add structural checks that CONTROLS.md-required controls are in place (.pre-commit-config.yaml present with gitleaks hook, pre-commit framework installed, plugin validation passes strict mode); current checks verify governance files exist but not that controls are enforced **Chunk 6 CI gaps** (require CI pipeline; implement during Chunk 6 grill): - Secret scanning in CI — CONTROLS.md: "Pre-commit hooks can be bypassed; CI cannot. Both layers are required." diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 00ea7e4..988056b 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -47,7 +47,7 @@ Current skills (direct): `caveman`, `diagnose`, `gitleaks`, `grill-me`, `grill-w - `init-project.sh` — bootstraps a new project (Chunk 6) - Copilot provider adapter (Chunk 7) - Formal CI/pre-commit enforcement of governance rules (Chunk 6) -- `setup-gitleaks.sh` not yet wired into `init-project.sh` (Chunk 6) — run manually against new repos +- `init-project.sh` scaffolding (Chunk 6) — will seed `.pre-commit-config.yaml` for new projects For chunk planning and open questions, see `docs/ROADMAP.md`. @@ -57,7 +57,7 @@ For chunk planning and open questions, see `docs/ROADMAP.md`. - 2026-06-20 — kyberforge plugin created and registered in `holocron` marketplace. Consolidates `create-plugin`, `marketplace-architect`, `write-skill`, and `write-eval` skills (previously in `.agents/skills/`) plus their evals, bundled scripts, references, and the plugin-marketplace-architecture research doc into a single installable plugin at `plugins/kyberforge/`. Plugin template (`templates/plugin/`) bundled into `plugins/kyberforge/skills/create-plugin/assets/plugin-template/` and removed from repo root. Evals moved from `.agents/evals/marketplace/` and `.agents/evals/factory/write-eval/` into `plugins/kyberforge/tests/evals/`. These four skills are no longer available as standalone slash commands — install the plugin to use them. -- 2026-06-20 — Gitleaks secret scanning added. `scripts/setup-gitleaks.sh` installs gitleaks v8.24.2, seeds `.gitleaks.toml` (first run only — project-owned after that), and writes a managed pre-commit hook block that is replaced on re-run. `scripts/gitleaks.toml` is the base config template extending gitleaks defaults. `tests/test-setup-gitleaks.sh` covers 6 behaviors (reject non-git dir, config deploy, hook create, append, stale-block replace, idempotency). `.gitleaks.toml` in repo root adds path allowlist for `docs/research/` (high-entropy terminal captures). `gitleaks` skill added (`cross-cutting`) covering full lifecycle: install, update, tune allowlist, scan modes, resolve real findings. Key lesson: v8.24.2 uses `[allowlist]` (singular); v8.25.0+ uses `[[allowlists]]` — wrong syntax silently does nothing. +- 2026-06-20 — Gitleaks secret scanning added via pre-commit framework. `.gitleaks.toml` in repo root is the base config extending gitleaks defaults and adds path allowlist for `docs/research/` (high-entropy terminal captures). `gitleaks` skill added (`cross-cutting`) covering full lifecycle: install, update, tune allowlist, scan modes, resolve real findings. Supports both modern repos (pre-commit-based) and legacy repos (shell hook-based setup). Key lesson: v8.24.2 uses `[allowlist]` (singular); v8.25.0+ uses `[[allowlists]]` — wrong syntax silently does nothing. - 2026-05-18 — Issue 0018 phase 1 refactor complete: `write-skill` redesigned from scratch. New files added to skill directory: `SKILL-TEMPLATE.md` (authoritative 6-section template with XML blocks, human-usable), `META-TEMPLATE.md` (provenance schema with inline-commented YAML), `CATEGORIES.md` (self-contained category table), `META.md` (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (`name`, `description`, `metadata.category`); provenance fields (`version`, `updated`, `when`, `source`, `references`) moved to META.md (progressive disclosure — not loaded at startup). `docs/notes/skill-implementation-workflow.md` updated to reference SKILL-TEMPLATE.md as the authoritative template.