From e59599dc39a04a64f3a1e56500f5ea32f4f03c6d Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sat, 18 Jul 2026 16:38:11 +0200 Subject: [PATCH] fix(agent-improvement): fail closed on contract sections; route vendored fixes upstream MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two findings from the Codex review of the plugin that bundles this skill (devantler-tech/agent-plugins#73). Contract guard: the skill is installable and invocable on its own, without the agent-improver wrapper that checks the deployment's Agent definition locations and Authority model. The pre-flight only checked that some definition files exist, then step 4 happily routed edits at bootstrap entries and permission configuration. A skill that edits guardrails must establish its own bounds, so it now performs those checks itself and fails closed per dimension. Vendored copies: the routing table treated "skills" as a version-controlled surface to patch in place. Where a definition file was installed from another repository — a bundled SKILL.md, a vendored agent — the consuming repo generally forbids hand-editing it and the next sync reverts the change, so the defect returns and the fix appears to have failed. Now says to fix it at its upstream and check for an origin marker before editing any definition file you did not author. Both are stated generically rather than in marketplace terms, since the skill is deployment-neutral; the plugin case is one instance of the pattern. Co-Authored-By: Claude Opus 4.8 --- agent-improvement/SKILL.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/agent-improvement/SKILL.md b/agent-improvement/SKILL.md index 8062ebf..3a5af0e 100644 --- a/agent-improvement/SKILL.md +++ b/agent-improvement/SKILL.md @@ -97,6 +97,22 @@ point, stale by default. Verify anything actionable against live state before ac present — **stop and report**, change nothing. Never improve what you cannot see, and never improvise the procedure from the bootstrap entry alone. +**Contract guard — check this yourself; do not assume a wrapper did.** This skill can be invoked +directly, without any agent definition around it, so it must establish its own bounds before step 4 +routes a change at a bootstrap entry or a permission file. Confirm the consuming deployment's contract +defines both: + +- **Agent definition locations** — every surface you may change, and which are version-controlled + (ship as a pull request) versus not (bootstrap/loader entries, permission or approval configuration + — edited in place, backed up first). Anything not named there is out of scope. +- **Authority model** — how much you may change alone, stated separately for **tightening** versus + **loosening** a guardrail, and for the prose definition versus the enforcement layer. + +**If either is missing or malformed, fail closed on that dimension**: report the gap and change +nothing that depends on it. Do not infer which surfaces are yours, and do not assume an authority you +were not granted. This guard is load-bearing precisely because the skill edits guardrails — improvising +its own bounds would remove them before any other check runs. + --- ## 1. Gather @@ -169,6 +185,14 @@ ships as a **pull request**; a non-version-controlled surface (a bootstrap entry approval configuration) is edited in place **after backing it up** to a timestamped copy naming the reason. +**A VENDORED copy is not the surface — fix it at its upstream.** Where a definition file was installed +from somewhere else (a bundled skill in a plugin or marketplace, a vendored agent definition), the copy +usually records its origin in frontmatter or a lockfile, and the consuming repository generally forbids +hand-editing it — a local edit is silently reverted by the next sync, so the defect returns and the fix +looks like it failed. Change it in the repository it came from, let the normal sync carry it, and note +the upstream link in your report. Check for that origin marker before editing any definition file you +did not author. + **Every change carries its evidence** — the signature, the count, the window. **Every change is reversible**, and the before/after goes into memory and the run report: a pull request is auditable by version history, an in-place edit only if you made it so.