feat(skills): retire safety-guard and apply the six context-engineering rules - #293
Open
naimkatiman wants to merge 9 commits into
Open
feat(skills): retire safety-guard and apply the six context-engineering rules#293naimkatiman wants to merge 9 commits into
naimkatiman wants to merge 9 commits into
Conversation
added 9 commits
August 7, 2026 23:25
…ety-guard, route CLAUDE.md, thin the tool surface Cites operator usage report 2026-08-07 (485 msgs/151 sessions) and skills/model-forward.md:28+31. Supersedes the safety-guard hold in docs/plans/2026-06-18-model-forward-retirement-candidates.md with explicit operator approval.
…y one enforcing surface safety-guard was a prose-only tier-2 skill claiming a runtime gate, a slash command, and a log file — none of which ever shipped. All three of its modes are already enforced by hooks/gateguard.mjs: Careful by the Destructive Bash Gate, Freeze by CI_GATEGUARD_TARGET_LOCK=block, Guard by both composed. gateguard.md also claimed the two were 'complementary, not overlapping', which was false in both directions. Bundle 28 -> 27 skills (16 tier-2). Adds a migration table to gateguard, drops the skill and its generated mirror, and updates every prose reference plus both CI-pinned derived counts. Plan: docs/plans/2026-08-07-six-rules-context-engineering.md
… ledgers Past Mistakes (7 rows) and Deferred (10 findings) moved to docs/past-mistakes.md and docs/deferred.md; CLAUDE.md keeps a two-line pointer to each. 101 -> 74 lines with no content lost. The Past Mistakes pointer names recall as the first lookup — the observation log finds matching failures without curation; the doc is the curated subset. Adds the 2026-08-07 safety-guard entry. Plan: docs/plans/2026-08-07-six-rules-context-engineering.md
…aller cannot infer ci_gateguard_clear 409 -> 219 chars and ci_distill_from_workflow 475 -> 250. Both restated material the model already has: the gate's fact list is printed verbatim in the hook's own block reason and again in skills/gateguard.md, and the workflow-recipe rationale was elaboration, not a decision input. Kept the two facts a caller cannot infer — path canonicalization, and draft-not-applied. 19 tool descriptions 2,979 -> 2,573 chars (avg 157 -> 135). Plan: docs/plans/2026-08-07-six-rules-context-engineering.md
…omes from shipped files, not prose Adds src/lib/skill-catalog.mts and wires it into the manifest generator, so docs/skill-catalog.html is derived from skills/*.md frontmatter plus the actual hooks/ and commands/ inventory. Every skill renders hook, command, or prose; the mapping fails closed, so a skill missing from HOOK_BY_SKILL under-claims rather than over-claims. Current bundle: 6 hook, 13 command, 8 prose. This is the structural fix for the safety-guard class of defect — a markdown row has nowhere to state what backs a skill, so prose-only scaffolding could advertise a runtime gate indefinitely. docs/skill-catalog.html joins verify:generated so it cannot drift. 22 new tests. Plan: docs/plans/2026-08-07-six-rules-context-engineering.md
…ed result Freeze Mode needed no porting — CI_GATEGUARD_TARGET_LOCK already implemented it, so a migration map shipped instead of a ported section. The HTML catalog shipped generated + verify:generated-guarded rather than hand-authored. Adds the before/after gate table, including the 4 environmental baseline test failures that were not caused by this branch.
… catalog in CI lib/skill-catalog.mjs was committed 100644 while the build chmods lib/*.mjs to 755, so Linux CI saw a mode-only drift and verify:generated failed. Windows core.filemode hides this locally. Audited every .mjs in the chmod'd directories — this was the only one. Both workflows hardcode their own path list rather than calling npm run verify:generated, so the package.json change in cffb3de never reached CI. Added docs/skill-catalog.html to ci.yml and release.yml so the catalog is actually guarded against drift.
… retirement main added the tier-1 ship skill (28 -> 29) and cut v3.23.0 while this branch sat open, so every count-bearing surface conflicted. Resolved by taking main's version of each conflicted file and re-applying the retirement on top: bundle is now 1 core + 1 featured + 7 tier-1 + 16 tier-2 + 3 always-bundled = 28 skills, on main's 3.23.0 base. verify:all 16/16 green; npm test 1159/1159 pass. Plan: docs/plans/2026-08-07-six-rules-context-engineering.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Applies the six context-engineering rules to this repo. The trigger was the operator's read of
~/.claude/usage-data/report-2026-08-07-231106.html(485 messages across 151 sessions, 2026-06-23 → 2026-08-07): "we use too much safety-guard skill."The report's "Primary Friction Types" are almost entirely guard friction, not model error — Permission Denied 19, Tool Permission Blocked 17, Tool Permission Blocks 15, Permission Blocked 10, Tool Limitation 8, Tool Blocked By Guard 7 — with "gateguard intercepted the initial Write in 10+ sessions."
The core finding
skills/safety-guard.mdwas 78 lines claiming a runtime gate, a/safety-guardslash command, and a~/.claude/safety-guard.logwriter. None of the three ever shipped. Line 71 of the same file admitted enforcement was prose-only, contradicting its own frontmatter.skills/gateguard.md:191compounded it by advertising the pair as "Runtime safety checks (complementary, not overlapping)" — false in both directions.All three of its modes were already enforced for real by
hooks/gateguard.mjs:CI_GATEGUARD_TARGET_LOCK=block— canonicalizes the target against the project root, before the fact gate and independent of clearanceRetirement was approved by the operator, superseding the "keep pending a separate decision" holds in
docs/plans/2026-06-18-model-forward-retirement-candidates.mdanddocs/audits/2026-06-10-model-forward-audit.md. It is the callskills/model-forward.md:28and:31already prescribe.Commits — one concern each
838449a28fb7a0safety-guard; migration map intogateguard; bundle 28 → 27653078eCLAUDE.md101 → 74 lines; ledgers todocs/past-mistakes.md+docs/deferred.md; Past Mistakes pointer namesrecallas the first lookup5931e89cffb3dedocs/skill-catalog.htmlwith an Enforcement column82b9721The structural fix
docs/skill-catalog.htmlis generated fromskills/*.mdfrontmatter plus the livehooks/andcommands/inventory. Every skill rendershook,command, orprose— derived from the shipped file set, never from the skill's own prose. The mapping fails closed: a skill absent fromHOOK_BY_SKILLdegrades tocommandorprose, never tohook. A markdown row had nowhere to state what backs a skill, which is why prose-only scaffolding could advertise a runtime gate for months.Current bundle: 6 hook, 13 command, 8 prose. Added to
verify:generatedso it cannot drift.Verification
188d1e4npm run verify:allnpm run verify:generateddocs/skill-catalog.html)npm testThe 4 baseline failures were
test/hook.test.mjs(observe.sh) at 3.3–5.0s wall clock under the full parallel run on a loaded Windows host — the suite passed 15/15 in isolation on the same commit, and all passed on the final run once the host quieted. Environmental, not caused by this branch; recorded indocs/past-mistakes.md.Both CI-pinned derived counts moved together: bundle 28 → 27 across the 5 manifest surfaces + the landing stat block, and the prose breakdown to
1 core + 1 featured + 6 tier-1 + 16 tier-2 + 3 always-bundledwith next-ordinal 29th → 28th.Scope notes
28fb7a0touches 36 files, above the 15-file guideline. Deliberate and not splittable: both count invariants and the mirror check fail on any partial application, so a split leaves CI red on the intermediate commit. ~18 are hand-edited source; the rest is generated output, which the guideline exempts.token-budget-advisor,strategic-compact,handoff,superpowersretirement decisions — separate operator calls, tracked indocs/deferred.md.gateguard's runtime behaviour. The measured friction is real, but loosening a hook with a +2.25 quality delta is a distinct evidence-gated decision, not a side effect of a docs pass.Plan:
docs/plans/2026-08-07-six-rules-context-engineering.md