check-vale-style-sync.sh used `declare -A` for a per-skill regex cache.
Associative arrays are bash 4.0+; this script runs as an always-run
pre-push hook with `language: system`, so it inherits whatever bash is
first on the invoking user's PATH. On macOS's stock bash 3.2, `declare -A`
at top level aborts immediately under `set -euo pipefail` — every push
would hard-fail before the sync check ran anything.
Replaced with two parallel indexed arrays (HOOK_REGEX_CACHE_KEYS/_VALS),
linear-scanned by index — same caching behavior (avoids re-parsing both
pre-commit manifests when agent-audit is probed twice), but only ever
uses ${#arr[@]} and index access, never a bare ${arr[@]} expansion.
Extended test-vale-wrap.sh's existing bash-3.2 hazard sweep to scan this
file too, and added a check for `declare -A` itself — it previously only
caught unguarded ${arr[@]} expansions and mapfile/readarray, so this
exact regression had no test that would have caught it.
Refs: #85
Two more efficiency findings from the same code-review pass:
- check-vale-style-sync.sh's hook_file_regexes() reparsed both
pre-commit manifests from scratch on every call. The final
validation loop calls it once per probe (3 probes: skill-audit once,
agent-audit twice for its two file shapes), so agent-audit's regex
set was being parsed twice for no reason. Now cached per skill in a
lazily-populated associative array, with a separate "seen" map so an
empty result isn't mistaken for "not yet computed."
- skill-size-check.sh read the target file twice (separate awk and
wc -w calls) to get line and word counts; now a single awk pass
returns both. Also documented, next to MAX_LINES/MAX_WORDS, why
those constants are duplicated against skill-audit/scripts/
validate.sh's Python implementation rather than unified — same
cross-language/cross-context tradeoff as vale-wrap.sh's duplication,
guarded by tests/test-skill-size-check.sh's drift check.
Verified: test-check-vale-style-sync.sh 20/20, test-skill-size-check.sh
9/9, full suite 12/12, pre-commit --all-files clean.
git describe --match is a shell glob, not a regex: the trailing `*`s
in 'v[0-9]*.[0-9]*.[0-9]*' match any suffix, so a tag like
v1.2.3-checkpoint or v1.2.3-rc1 satisfied the pattern and could be
picked as LAST_TAG instead of the true last release. That silently
shifts the diff baseline and can let a push skip a required release.
--exclude '*-*' rules out any tag carrying a hyphenated suffix.
Added a regression test that tags a release-relevant change with a
v1.0.1-checkpoint tag right after v1.0.0 and asserts the gate still
fires — confirmed it fails against the pre-fix script and passes
against the fix.
MAX_WORDS=2900 was calibrated to the corpus median density and carried no
margin: at the densest observed 7.22 chars/word (~1.81 tokens/word) it permits
~5,240 tokens against the 5,000 it proxies for. 2770 holds the worst observed
density under the ceiling. The largest SKILL.md is 2,489 words, so the change
costs nothing today — 281 words of margin — and the header comment now argues
the new calibration rather than swapping the digits.
Both enforcement points move together, and a new test asserts they agree, since
a SKILL.md passing its own audit while the commit hook blocks it is the
disagreement this pair exists to prevent.
CONTEXT.md is deliberately left ungated: it is 2,816 words, and gating it would
block the build. Recorded here so the omission reads as a decision rather than
an oversight.
skill-audit's manual-fallback path listed only the line ceiling, so an agent
taking that path passed an oversized SKILL.md the hook then rejected. The word
ceiling is now named alongside it. agent-audit is deliberately unchanged: the
size hook scopes to SKILL.md only and agent-audit's validate.sh has no word
gate, so claiming it there would be false.
The Vale research doc still showed the MDX {/* vale off */} form under a
Markdown heading, contradicting CONTEXT.md and vale-run's troubleshooting
reference — that form suppresses nothing in plain .md. Fixed in both places it
appeared.
tests/run-tests.sh used mapfile (bash 4.0+) with unguarded array expansion,
though AGENTS.md tells contributors to run it and macOS ships bash 3.2. It now
collects via a while-read loop over process substitution and guards every
expansion. The newline-delimited find|sort pipeline is kept rather than -print0
with sort -z, whose BSD portability is the weaker link, and which matches
mapfile -t's previous behaviour exactly.
Refs: #85
ADR: 0013
The gate hardcoded HEAD as its diff tip, but pre-commit exports
PRE_COMMIT_TO_REF for exactly this. Pushing "somebranch:main" from another
checkout diffed the wrong tip — a false negative when HEAD is older, a false
positive when newer. Fixing only the diff tip leaves a second bug: git describe
took the tag baseline from HEAD too, so a tag reachable only from HEAD becomes
a baseline the pushed ref never saw. Both now resolve from the pushed ref, and
an all-zeros ref (branch deletion) short-circuits before any rev resolution
rather than surfacing as "could not diff".
PRE_COMMIT_FROM_REF is deliberately not used: it is the remote's current tip,
so diffing from it would let an untagged release-relevant commit already on
main excuse the next push from cutting a tag — the drift this gate exists to
catch. The baseline must stay the last release tag.
collect_release_paths took tokens[0] as a path unconditionally. ADR-0014 makes
bare single-path entries a binding constraint, but nothing enforced it, and the
sibling .pre-commit-config.yaml already ships "entry: bash <script>". Under
that shape add_release_path takes "bash", git diff accepts the non-matching
pathspec silently, bundle_root becomes "." and is skipped — the hook's whole
surface leaves the gate with no error, the same shape as the --config
regression in LESSONS.md. Multi-token entries now fail loudly naming the hook
and the ADR, and tokens[0] must resolve at HEAD or at the tag (the union is
load-bearing: a per-scope check would reject the deletion cases).
Six mutations verified, each restored. One correction worth recording: the
first multi-token test passed with its guard removed, because the existence
guard caught "bash" and printed a similar message. It now requires the verbatim
entry text that only the multi-token diagnostic emits.
Refs: #85
ADR: 0014
The external-consumer test asserted a combined alert count (>=2) across both
shipped Vale hooks, but the SKILL.md fixture alone raises two alerts — so one
working hook satisfied the threshold. Retargeting agent-audit's glob to match
nothing left the suite reporting "3 passed" under the message "both hooks
flatten and flag". The Skipped guard does not catch this: the hook still
matches the file, Vale lints nothing, reports 0 errors in 1 file and exits 0,
which pre-commit renders as Passed. An assertion aggregating over N subjects
proves nothing about any individual subject.
Each hook now runs individually and its alerts are attributed to the nearest
preceding path header, so an alert is checked by path rather than by presence
in the combined blob. The two fixtures carry distinct VagueWording tokens, so
one hook's alert cannot be credited to another.
Nothing in the repo read either .vale.ini — the sync check diffed only
vale-wrap.sh and styles/Kyberforge, so a one-line glob typo silently disabled
the prefilter for a whole file type. That was the enabling half of the same
defect. The check now asserts the shared lines both copies must carry
(StylesPath, a section naming Kyberforge as a whole word) without flagging
their intentional divergence, and probes each glob section by asking Vale
itself to lint a representative path. Regex-to-glob comparison was rejected as
it means reimplementing doublestar semantics in bash; a file-count dry-run was
rejected because a section whose glob matches but whose BasedOnStyles lost
Kyberforge reports "1 file" with no alerts and would pass it.
Every new assertion is bound to a failing case in both directions: breaking the
artifact fails the suite, and neutering the assertion fails exactly one case.
That reverse sweep exposed two assertions bound to no failing case at all, one
masked by a stronger check running first.
Refs: #85
Three divergences between what the audit skills claim and what the hooks
enforce, each of which fails silently rather than loudly:
- `skill-size-check.sh` blocked at 2900 words while `validate.sh` checked only
the 500-line ceiling, so `/skill-audit` could report a skill ready to ship
that the commit hook then rejected. `validate.sh` now checks the same pair on
the same inclusive terms; the constants are duplicated with a comment naming
the other file, because a plugin skill's scripts cannot read outside the
plugin directory once installed to the cache.
- Both audit skills' Step 1 passed `--config assets/vale/.vale.ini`, which is
redundant (the wrapper self-locates its sibling config) and fragile: an agent
that resolves the script path against the skill directory but not the config
path gets E100, exit 2, which the surrounding fallback clause misreads as
"vale unavailable" and downgrades to full LLM judgment with no signal.
- The external-consumer test registered only the two Vale hooks, never the
third shipped hook, so a lost executable bit would have broken every consumer
while the local suite stayed green. Verified by mutation: `chmod 644` on the
copied script now turns three passes into two failures.
Also corrects the size hook's calibration comment, which claimed ~5.7-6.5
characters per word against a corpus whose measured median is 6.79 — the stated
upper bound sat below the median, so the "calibrated with margin" claim was
inverted for prose-dense files. MAX_WORDS is unchanged pending a decision; the
comment is now explicit that the gate holds under 5,000 tokens for typical
prose density, not for any file.
Refs: #85
Coverage was derived from the worktree alone, so the -d guard on a
hook's bundled assets/ tree meant deleting the whole tree removed it
from the pathspec instead of flagging it — the gate stayed silent
about a change that breaks every consumer at the next rev:.
The path set is now derived twice, from the worktree manifest and from
the manifest at $LAST_TAG, then unioned. A path the tag exposed but
HEAD no longer does is a removal pinned consumers must be told about;
a path only HEAD exposes is new contract surface. Both need flagging.
Fails closed on an unreadable tagged tree (shallow clone), and treats
a readable root tree with no manifest as "added since the tag".
tokens[0] needed no exit-code fix — it carries no existence guard, so
both deletion cases already exited non-zero. What was wrong was the
reporting: a fully retired hook could no longer be named in the
failure message. The tagged manifest fixes that.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
The gate derived release-relevant paths from the dirname of each
entry's --config target. Dropping --config from .pre-commit-hooks.yaml
left that loop dead, silently removing both assets/vale/ trees from
coverage — a Vale rule change could land on main without demanding a
release tag, leaving consumers pinned to an old rev: with stale rules.
Coverage now derives from tokens[0] instead: double-dirname for the ..
normalization, guarded on the tree existing and on the bundle root not
resolving to "." so skill-size-check.sh cannot invent a bogus path.
The --config branch is removed rather than kept as dead code. Since
pre-commit rewrites only entry[0], no argument in any entry can ever
name a file this repo ships, so that shape is broken by design.
Known gap: deleting a hook's entire assets/ tree is not flagged, as the
candidate path stops existing. Deletions within a surviving tree are.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
The guard used `||`, so exactly one of the two audit skill directories
missing also exited 0, where the intended silent no-op is both absent.
A renamed skill-audit reported green instead of flagging that a
canonical style copy had lost its counterpart.
One-present now exits 1 naming the missing side and the remedy.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
A review of PR #85's last two commits (1164f3a, 4d018af) found the new
release-gate script fails open in four separate ways, and the new drift
check for the duplicated Vale styles only ever detects drift after a
human already hand-edited both copies out of sync.
check-release-needed.sh:
- The `-e` existence filter dropped a RELEASE_PATHS entry from the diff
pathspec once it was deleted from the tree, so deleting a path exposed
via .pre-commit-hooks.yaml since the last tag passed the gate clean —
exactly the breakage the gate exists to catch. git diff reports
deletions fine without an existence check; the filter is gone.
- `git diff ... 2>/dev/null || true` turned any git failure (a shallow
clone missing the tag's objects, a corrupted ref) into an empty,
falsely-clean diff. The diff result is no longer swallowed: a failure
now hard-fails with the underlying git error visible.
- RELEASE_PATHS was a hand-maintained array duplicating
.pre-commit-hooks.yaml's entry: paths with only a comment holding them
in sync, and was already over-broad (it swept in validate.sh /
validate-provenance.sh, which no hook entry references). It's now
parsed straight from .pre-commit-hooks.yaml's entry: lines at
runtime, so it can't drift from the manifest and only tracks what a
hook actually exposes.
- `git describe --tags --abbrev=0` accepted any tag reachable from HEAD
as the diff baseline, not just release tags. Added
`--match 'v[0-9]*.[0-9]*.[0-9]*'` so an incidental checkpoint tag
can't shift the baseline and mask a real release-relevant change.
check-vale-style-sync.sh still only detects drift between skill-audit's
and agent-audit's duplicated vale-wrap.sh/styles/Kyberforge copies
(both copies must exist independently per the plugin's no-cross-skill-
path packaging rule — a symlink would break at install time). Added
scripts/sync-vale-styles.sh to regenerate skill-audit's copy from
agent-audit's canonical one on demand, and pointed the sync check's
failure message at it, so fixing drift is one command instead of a
hand diff across two files.
Also recorded, rather than silently left unfixed: check-release-needed.sh
only fires on a local `git push` through pre-commit's pre-push hook — a
PR merged via Gitea's merge button, or CI invoking
`pre-commit run --hook-stage pre-push` directly, never sets
PRE_COMMIT_REMOTE_BRANCH and skips the gate entirely. Closing that needs
a server-side CI job this repo doesn't have yet; documented as a known
limitation in ADR-0014 rather than papered over.
Separately, LESSONS.md's "a clean check can mean nothing ran" entry was
marked **Graduated** without ever being promoted per the repo's own
graduation rule (3+ instances → a standing doc, marked
`[graduated → target file]`). Actually promoted it into
core/instructions/testing.md and fixed the marker.
tests/test-check-release-needed.sh gained 4 regression tests, one per
check-release-needed.sh fix above, each verified to fail against the
pre-fix script and pass against the current one.
Verification: bash tests/run-tests.sh (11 scripts + 125 bats, all
passing), pre-commit run --all-files, and
pre-commit run --all-files --hook-stage pre-push all clean.
ADR: 0014
.pre-commit-hooks.yaml now exposes hooks to external consumers pinning
rev: <tag>, but nothing enforced that a tag actually gets cut when the
files it references change — relying on memory is exactly what this
repo's governance rules say to avoid for a repeatable, deterministic
check.
scripts/check-release-needed.sh hard-fails at pre-push, but only when
PRE_COMMIT_REMOTE_BRANCH (set by pre-commit's hook-impl) is
refs/heads/main: it diffs .pre-commit-hooks.yaml's referenced paths
against the last tag reachable from HEAD, and fails if either no tag
exists yet or something changed since. It's a silent no-op on every
other branch — hard-failing on feature-branch pushes mid-review would
force a premature tag on a commit that might not survive a
squash-merge, the exact risk the repo: local (vs. pinned self-
reference) decision in ADR-0014 already avoids for this repo's own
dev-time gate.
Verified against the real git pre-push hook path (not just the script
in isolation): simulated stdin matching git's pre-push protocol through
.git/hooks/pre-push, confirmed it correctly fires and fails when
targeting main with no tag, and is silent otherwise.
ADR: 0014
Refs: #87
skill-audit/agent-audit's Step 1 resolved vale-wrap.sh/.vale.ini via
`git rev-parse --show-toplevel`, which returns whichever repo the skill
happens to run in. Inside ai-development that works; in any external repo
that installs kyberforge@holocron as a plugin, it resolves to that repo's
own root, which has no .vale.ini — the prefilter silently fell back to
full LLM judgment. ADR-0013 named this as a deliberately deferred gap.
Vale's config/styles/wrapper now ship inside the plugin itself: a
canonical copy in agent-audit/assets/vale/ (Kyberforge + KyberforgeCopilot,
the superset agent-audit needs) and a smaller duplicate in
skill-audit/assets/vale/ (Kyberforge only) — per the no-cross-skill-path
rule already established for plugin cache-installs. Both skills resolve
these relative to their own directory, same as scripts/validate.sh
already does.
A new root .pre-commit-hooks.yaml exposes both copies plus
skill-size-check so any external repo can enforce the same rules via
`repo: <this-repo-url>, rev: <tag>` in its own pre-commit config,
independent of Claude Code entirely — the same mechanism covers CI. This
repo's own pre-commit hook now consumes the identical plugin-bundled
copies via repo: local (not a third root copy, and not a pinned
self-reference, which would lint working-tree edits against the last
tagged release instead of the change being made). Split into
vale-audit-prefilter-skill/-agent hooks after confirming, by diffing the
full corpus against both old and new config before deleting the old
files, that one combined hook pointed at only one copy silently 0-file-
skips the other file type.
scripts/check-vale-style-sync.sh guards the two copies against drift,
wired at pre-push alongside check-manifests.
ADR: 0014
Round-3 review of PR #85 found the "enforcing" pre-commit hook enforced
nothing. Vale's exit code keys on error-level alerts alone: five of the
six rules were level: warning, so they exited 0, and pre-commit hides
output from a passing hook — the alerts were invisible and blocked
nothing. ADR-0013 rejected a report-only trial tier and then shipped one
by accident.
Flatten every rule to level: error. Vale's own exit code is then correct,
so the hook entry drops to a bare vale-wrap.sh call and the graded
error->FAIL / warning->SUGGESTION mapping disappears from both audit
skills: every alert is a FAIL, in the gate and the audit alike. No
ignorable tier, matching shellcheck, the test suite and
conventional-pre-commit.
Delete Kyberforge.VagueQualifier. Measured against the 41 skill/agent
files as they stood before the rule ever ran: 2 hits. One marginal
("very different" -> "fundamentally different"), one an unfixable false
positive — caveman/SKILL.md quotes "of course" as an example of filler,
a mention not a use — which forced the only Vale suppression comments in
the repo. Those four lines go with it; two of them were dead anyway,
suppressing a frontmatter-scoped rule on a body line. Held-out prose (273
files) fired 15 times, 9 inside out-of-scope research examples and the
rest one word in two idioms in a single doc. SentenceOpenerThereIs
survives: 22 held-out hits, both in-corpus hits clean rewrites, zero
suppressions.
Widen .vale.ini's globs to [**/SKILL.md], [**/agents/*.md] and
[**/*.agent.md]. The plugins/*/-prefixed globs scoped nothing — Vale's *
crosses /, so they already matched docs/research/examples/**/agents/*.md
and assets/templates/SKILL.md, the two paths CONTEXT.md claimed they
excluded. Scoping is and was the hook's files: regex. The old globs also
hid a silent false negative: a skill outside plugins/ matched no section,
so Vale reported 0 files and exited 0, which both audits read as clean.
They now treat a 0-file run as NOT RUN and fall back to full judgment.
Also:
- vale-wrap.sh resolves relative --config values and file arguments
against the caller's cwd, as vale does, instead of the repo root, which
hard-errored from a subdirectory and silently skipped flattening for
file args that did not resolve from the root. Absolute paths inside the
cwd are relativized so reports cite resolvable paths, not scratch ones.
- vale-run's exit-code model was documented backwards ("exits non-zero
whenever it finds an alert at or above MinAlertLevel") and would have
led anyone following it to build a gate that passes everything. Its
Markdown suppression syntax was MDX-only and does not suppress in .md;
corrected in the skill and its troubleshooting reference, with
backtick/fence exemption documented as the first resort.
- skill-size-check.sh fails only above 500 lines, agreeing with
skill-audit's validate.sh <= 500 pass.
- ADR-0013 and CONTEXT.md amended to match, recording why graded
severities cannot gate.
Verified: 9 test scripts / 15 vale-wrap cases pass; vale-audit-prefilter,
skill-size-check and shellcheck pass --all-files; check-manifests and
claude plugin validate --strict clean. New tests fail against the old
script (3 of them) and pass against the new one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Addresses PR #85's outstanding review items after grilling the open
questions against ADR-0013/CONTEXT.md/ADR-0010:
Blocking fixes:
- vale-wrap.sh: replace json.dumps() escaping (which silently defeated
Vale's frontmatter scope on any description containing a quote,
backslash, or non-ASCII char — ~58% of the corpus) with a single-quoted
YAML scalar, substituting a Unicode right single quote for embedded
apostrophes rather than '' doubling (Vale's frontmatter scanner isn't a
full YAML parser and silently truncates on '' too).
- vale-wrap.sh: fix a blank-line-inside-a-folded-description truncation
bug via indentation-based, blank-line-tolerant body capture; narrow
flattening to `>`-style scalars only (`|` already works unflattened).
- skill-audit/agent-audit Step 1: make the vale-wrap.sh invocation
cwd-independent via git rev-parse --show-toplevel, fixing a bug where
no single cwd satisfied all three Step 1 commands.
- styles/Kyberforge/VagueQualifier.yml: prune 17 tokens verified
false-positive-dominated on this repo's own voice via a real corpus
sweep (obvious, clearly, usually, several, simple, easy, completely,
simply, tiny, etc.), keep 13 with real or unattested noise. Revert the
28 prose "fixes" those tokens drove across 14 skill files back to their
original, correct wording, including a functional regression to
caveman/SKILL.md's own filler-word list (a mention, not a use) — now
guarded with vale-off comments against recurrence.
Gaps:
- --minAlertLevel=warning on the pre-commit hook and Step 1 invocation
so warning-level rules actually surface, without collapsing the
FAIL/SUGGESTION severity mapping skill-audit/agent-audit rely on.
- vale-wrap.sh: fix --config=<path> equals-form, absolute-path silent
no-op, and a zero-file-argument stdin hang.
- Route vale-run and lint-runner through a documented wrapper script
when a target repo has one, instead of unconditionally recommending
bare `vale`.
- Wire Kyberforge.VagueQualifier/SentenceOpenerThereIs into skill-audit/
agent-audit's dimension-mapping prose (Body discipline).
- Add plugins/lint/sources.md provenance for lint-runner (ADR-0010).
- Sync both marketplace.json lint-entry descriptions with plugin.json.
- Retune skill-size-check.sh's MAX_WORDS 5000->2900 (measured ~1.6-1.7
tokens/word on this repo's corpus, the old value gated at ~8,500
tokens against a stated 5,000 ceiling); fix the >/>= line-count
boundary and wc -l undercount on files with no trailing newline.
- Document the vale binary as a Setup prerequisite in AGENTS.md.
- Fix SentenceOpenerThereIs's dead regex alternative and add a real
sentence-start anchor/scope.
- Fix a stale docs/research/docs/vale/ index pointer in kyberforge's
docs README (moved to plugins/lint/ in e1a5403).
- Rewrite ADR-0013's Consequences section past-tense to describe what
actually landed, and record the styles-portability limitation
(repo-root placement stays intentional; deferred to a separate
session per this PR's review).
Test coverage: 9 new vale-wrap.sh fixtures (quotes, backslash/unicode,
blank-line paragraphs, --config= form, zero-arg/absolute-path handling,
literal-block no-regression) and boundary-pair tests for
skill-size-check.sh's line/word ceilings.
bash tests/run-tests.sh: 9 scripts + 125 bats assertions, all passing.
scripts/check-manifests.sh and claude plugin validate --strict: clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Deferred item from PR #85 review. Per ADR-0013: cherry-picks two low-noise
rules from trialing write-good/alex against the real corpus (VagueQualifier,
SentenceOpenerThereIs) into styles/Kyberforge rather than adopting either
package wholesale (both are tuned for blog prose and were noisy on this
repo's terse, imperative instruction files - see the ADR's rejected-rule
list). Adds a new skill-size-check pre-commit hook enforcing agentskills.io's
500-line/5,000-token SKILL.md ceiling, currently unenforced. Fixes the 28
resulting violations across 20 existing SKILL.md/agent files so the
enforcing pre-commit hook lands clean.
governance.md/CONTROLS.md were evaluated and excluded as rule sources -
they're org/CI-infrastructure controls, not prose patterns Vale can express.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QUDczvw1H3eEeMD29Q9Lbi
Vale's text.frontmatter.description scope silently stops matching once
the description is a YAML block scalar spanning 2+ physical lines —
the style used by most skills/agents in this repo. scripts/vale-wrap.sh
flattens the description to one line in a scratch copy (preserving the
repo-relative path and total line count) before invoking real vale, and
both audit skills plus the pre-commit hook now call it instead of vale
directly. Also tightens the pre-commit hook's file glob to single path
segments so it can't cross into docs/research examples or asset
templates the way the audit skills' scoped invocations already avoid.
Addresses PR #85 review feedback.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
scripts/install.sh hardcoded $REPO_ROOT/.git/hooks, which breaks under any
git worktree checkout (.git is a file there, not a directory) — this is
what blocks every worktree-based agent from pushing cleanly. Resolve the
hooks directory via `git rev-parse --git-path hooks` instead, normalizing
to an absolute path since git returns it relative to the queried repo root
for plain checkouts but absolute for worktrees.
Also drops `agents`/`skills` fields from plugins/bin, plugins/core, and
plugins/gitea plugin.json where the referenced directories don't exist on
main yet (bin never had an agents/ dir; core and gitea's real skill/agent
content is still pending merge from an in-flight branch) — these were
failing scripts/check-manifests.sh and blocking pushes for unrelated work.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
## Why
The repo moved from a chunk-based delivery model with `.agents/skills/`
as the canonical skill source to a plugin model. Several files retained
references to the old model that were either dead code or misleading
framing.
## Impact
- `tests/test-install.sh`: dead `.agents/skills/` test blocks removed;
suite now tests only what `install.sh` actually deploys
- `scripts/deploy-manifest.sh`: `DEPLOY_SKILLS_SRC` variable and stale
`sync.sh (Chunk 6)` comment removed
- `tests/test-git-hooks-install.sh`: fixture stub no longer declares
the removed `DEPLOY_SKILLS_SRC` variable
- `docs/VISION.md`: chunk delivery framing replaced with plugin model
language throughout; manual test plan date updated
- `tests/test-instructions-and-docs.sh`: stale test plan date flagged
as pre-refactor so readers know a re-run is needed
Refs: #15
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
The hook was treating all source values as local directory paths. Remote
sources (github/git/npm objects) have no local directory — the jq -r of
a JSON object produced garbage, causing the hook to fail on push after
adding the mattpocock-skills remote plugin.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Installing kyberforge via the holocron marketplace caches the plugin at a
specific version. After every push, the marketplace clone and plugin cache
need to be refreshed manually — otherwise new skills added since the last
install are invisible until the user runs `claude plugin update` manually.
Adds a post-push git hook that pulls the holocron marketplace clone and
updates the kyberforge cache automatically after every push, eliminating
the manual refresh step.
## Implementation Notes
- `scripts/git-hooks/post-push` is the canonical source; `install.sh` now
copies all files in `scripts/git-hooks/` into `.git/hooks/` on fresh
checkouts, making the pattern extensible for future hooks.
- Hook exits 0 on all failures (warns to stderr) — a stale cache refresh
never blocks a completed push.
- 11 bats tests cover both the hook and the install.sh copy block, using
mocked binaries and a temp-tree fixture to avoid touching real state.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P87CiC58Ru2PPWYTeXtjHT
Removed .git/hooks/pre-commit.legacy and scripts/setup-hooks.sh — fully replaced by .pre-commit-config.yaml.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Add tests/run-tests.sh: discovers and runs all test-*.sh (including
plugin subdirs) and the bats suite; replaces per-script pre-push calls
- Add tests/run-tests.bats: TDD coverage for run-tests.sh behaviours
- Update setup-hooks.sh: pre-push block now calls run-tests.sh
- Fix test-install.sh: remove provider adapter symlink tests (adapter
removed in marketplace migration), guard skills loops on dir existence
- Fix test-instructions-and-docs.sh: content index checks now point to
core/AGENTS.md (where it lives), remove ard/bug dir assertions
- Fix test-setup-hooks.sh: assert pre-push hook calls run-tests.sh
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
With the marketplace architecture, provider-manifest.sh files and the
.agents/skills/ source directory may not exist. Guard both loops so
install.sh doesn't hard-fail when they're absent.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
gitleaks false positive (U1, Gitea issue #2):
- 'Token routing: Haiku/Sonnet/Opus' in ai-coding-factory-session.md:90
triggers generic-api-key on entropy match of "Token". Not a credential.
- ROADMAP.md now documents this pattern and triggers the same rule.
- Both .gitleaks.toml (deployed, read by hook) and scripts/gitleaks.toml
(source for setup-gitleaks.sh deploys) updated and aligned. Previously
out of sync — deployed file had docs/research/.* already; source did not.
ROADMAP.md: governance workstream Phase 2 expanded with 7 immediately-
actionable test suite gaps and 5 Chunk 6 CI gaps, all mapped to
CONTROLS.md requirements. Housekeeping updated with audit entry.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gv5iNACZxumtF2k6TsK18q
Two related fixes exposed when install.sh was first staged post-audit:
1. shellcheck invocation in setup-hooks.sh lacked -x, causing SC1091
(info) to fire for any .sh file that sources another, blocking the
pre-commit hook on legitimate scripts.
2. The shellcheck source= directive in install.sh pointed to
'deploy-manifest.sh' (bare filename). With -x, shellcheck resolves
this from CWD (repo root), where the file doesn't exist. Updated to
'scripts/deploy-manifest.sh' — the correct repo-root-relative path.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gv5iNACZxumtF2k6TsK18q
Adds a complete cross-cutting skill to install, configure, and manage
@neuledge/context — a local-first MCP server that delivers version-specific
library docs to AI agents via SQLite FTS5.
Includes:
- SKILL.md with 9-step process: install, global MCP registration, per-project
--libs scoping, package management, auth, custom registry, upgrade, uninstall
- setup-neuledge-context.sh: pinned version install, idempotent version check
- secure-context-config.sh: chmod 600 on ~/.context/config.json after auth
- 13-case test suite covering both scripts (all pass)
- eval.yaml with 6 trigger tests and 4 output tests
- references/: context-cli-reference.md, http-mode.md, install-notes.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ
trap '...' RETURN inside a function is NOT local to that function in bash
— it persists in the calling scope and fires on every subsequent function
return. After install_shellcheck set the trap, it fired again when
ensure_tool returned with $tmp_dir unbound, causing nounset abort.
Fix: change install functions from {} to () (subshell bodies) and use
trap EXIT instead of RETURN. The trap is now scoped to the subshell and
cannot leak to callers.
Also fixes double _os() call in install_jq and removes redundant local
declarations (subshells don't need them).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ
setup-hooks.sh now installs shellcheck, jq, and yq if absent rather
than warning and continuing. Follows the same install pattern as
setup-gitleaks.sh (curl + install to TOOL_INSTALL_DIR=/usr/local/bin,
OS/arch detection, pinned versions).
Pinned versions: shellcheck 0.10.0, jq 1.7.1, yq 4.44.3.
The deployed pre-commit hook retains its runtime fallbacks as a safety
net for environments where tools are removed after setup.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ
Two bugs in setup-hooks.sh:
1. awk+mv to replace a marker block created a 644 temp file, losing the
exec bit. chmod +x after every write_block call fixes this. Regression
test added to idempotency block.
2. set -euo pipefail in the deployed pre-commit hook caused grep to exit 1
when no files of a given type were staged, aborting the hook. Changed
all filter pipes to process substitution with || true so no-match is
handled gracefully.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ
Adds setup-hooks.sh and check-manifests.sh as the deterministic
enforcement layer described in docs/research/governance_principles/CONTROLS.md.
- commit-msg: conventional commits pattern check (hard block)
- pre-commit: shellcheck on .sh, jq on .json, yq on .yaml/.yml,
SKILL.md frontmatter validation; optional tools degrade gracefully
- pre-push: full test suite + manifest cross-reference check
- check-manifests.sh: validates marketplace.json plugin sources,
plugin.json skill/hooks/mcpServers path references
- Marker-based blocks (idempotent, composable with gitleaks)
- 33 integration tests across two test scripts
Run scripts/setup-hooks.sh to install into any repo's .git/hooks/.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ
Create AGENTS.md at repo root and core/AGENTS.md as provider-agnostic
sources of always-on rules. Slim both CLAUDE.md files to thin adapters.
Deploy core/AGENTS.md → ~/.agents/AGENTS.md via deploy-manifest.sh.
Update three test suites to check correct locations post-refactor.
All automated tests pass (57 instructions, 106 install, 25 governance).
HITL behavioral test plan in test-instructions-and-docs.sh scenarios 9–12.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Establishes the global AI development config repo from scratch:
- Chunk 1: repo skeleton, install.sh, statusline, deploy manifest
- Chunk 2: core instructions (coding/git/testing), CLAUDE.md rewrite
(always-on + content index two-tier model), docs restructure,
6 ADRs, ROADMAP.md, .gitkeep placeholders
- Bootstrap skills in .claude/skills/ (to be catalogued and migrated
to .agents/skills/ in Chunk 3)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
