The-Artificer-of-Ciphers-LLC/skills-from-the-artificer / artifact-gates
artifact-gates
VerifiedMake workflow steps enforceable by giving each one a file it must produce. Use when an agent skips steps in a long directive, playbook, or slash command despite them being marked MANDATORY/ABSOLUTE/BLOCKING; when writing or reviewing a multi-step workflow that must not be short-circuited; when a review, design, or verification step is being self-reported rather than proven; or when a merge/label/publish action needs a machine-checked precondition instead of a promise. Triggers on "my agent keeps skipping", "it ignored the directive", "how do I enforce this step", "it said it ran the review but didn't", "self-attestation", "gate this action".
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.5 KB |
| SKILL.md | skill md | 10.5 KB |
| contracts/full-example.json | config | 13.0 KB |
| contracts/minimal.json | config | 2.6 KB |
| evals/evals.json | config | 5.7 KB |
| hooks/artifact-gate.cjsexecutable | script | 15.5 KB |
| test/gate-test.shexecutable | script | 12.1 KB |
contracts/full-example.json
View on GitHub{
"_comment": [
"Worked example: three directives, three failure modes, three contracts.",
"Copy to <repo-root>/.artifact-gate.json and adapt. The families are independent —",
"delete the ones you don't run. Every `message` is the text an agent sees at the",
"moment it is blocked, so it is worth writing them as instructions, not scoldings."
],
"exempt": ["^\\.claude/", "^\\.gsd/"],
"families": [
{
"_comment": "A feature/implementation directive. Failure mode: DESIGN steps get skipped, because thinking produces nothing observable.",
"name": "feature",
"scope": "branch",
"dir": ".gsd/phase/{slug}",
"arm": "00-run.json",
"gates": [
{
"on": "edit",
"paths": ["src/**"],
"requires": "40-design.md",
"message": "Step 4 (design) produced no artifact.\n\nRun the design step and write its output there:\n /rubber-duck — walk the logic, surface edge cases\n /grilling — attack the design BEFORE it is code\n /skills-from-the-artificer — which laws apply (Hyrum, Gall, Conway)\n\nRequired sections: Behavior table (one row per input class — the row SET is the deliverable) · Negative space (what legitimately looks like your trigger condition and must NOT fire) · Blast radius · Laws that apply · Rejected alternatives · Known limits.\n\nA design step that produces nothing is indistinguishable from a design step that was skipped."
},
{
"on": "edit",
"paths": ["test/**", "tests/**"],
"requires": "50-test-matrix.md",
"message": "Step 5 (QA matrix) produced no artifact.\n\nWrite the enumerated matrix first: one row per INPUT CLASS, categories happy / boundary (limit-1, limit, limit+1) / negative / hostile / independence.\n\nEnumerating the input space on paper is what catches the classes that reach CI otherwise — valid-JSON-that-is-not-an-object, a lone `---` that is a horizontal rule, the CRLF variant. Writing tests for the code you just wrote finds none of them."
},
{
"on": "bash",
"match": "(^|[\\s;|&])git(\\s+-[^\\s]+)*\\s+push(\\s|$)",
"requires": "60-review.json",
"message": "Step 6 (orthogonal review) produced no artifact.\n\nRun BOTH engines and record findings + dispositions:\n /code-review — correctness, logic, edge cases (the named skill, not an ad-hoc agent)\n /security-review — injection, secrets, traversal, unsafe argv\n at least one in an isolated reviewer context that did not author the change\n\nShape: {\"engines\":[{\"name\":\"code-review\",\"isolated\":false,\"findings\":[{\"severity\":\"\",\"summary\":\"\",\"disposition\":\"\"}]}]}\n\nThis replaces a self-attestation token with something checkable: such a token asserts the reviews happened, which is exactly the claim that cannot be verified."
}
]
},
{
"_comment": "An unattended bug-sweep directive. Failure modes: stopping at 'PR opened', and silently dropping the rest of the queue after one hard issue.",
"name": "bugfix",
"scope": "branch",
"dir": ".gsd/bug/{slug}",
"arm": "00-run.json",
"gates": [
{
"on": "edit",
"paths": ["src/**"],
"requires": "10-diagnosis.md",
"message": "Diagnosis produced no artifact.\n\nA fix written before the root cause is written down is a guess with a diff attached.\n\nRequired sections: Reproduction (exact command + observed output) · Root cause (`file:line`, located not suspected) · Introduced by · Blast radius · Must-Have Acceptance Checklist (verbatim from the issue) · Not-the-bug negative space (what legitimately looks like this symptom and must keep working) · Rejected fixes.\n\nThe last two pay for themselves: without negative space you ship an over-broad fix, and a fix with no rejected alternative was not chosen — it was the first thing that came to mind."
},
{
"on": "edit",
"paths": ["test/**", "tests/**"],
"requires": "50-test-matrix.md",
"message": "QA matrix produced no artifact.\n\nRow 1 is the failing-first regression test, and its `RED proven (sha)` cell carries the run where it actually failed. \"The test failed first\" is a claim; the sha is evidence."
},
{
"on": "bash",
"match": "(^|[\\s;|&])git(\\s+-[^\\s]+)*\\s+push(\\s|$)",
"requires": "60-review.json",
"message": "Two orthogonal reviews, at least one isolated, recorded with a disposition per finding. `not-a-defect` requires the proof, not the assertion."
},
{
"_comment": "Contents-checked, not presence-checked. This is where merge policy stops being prose.",
"on": "bash",
"match": "\\bgh\\s+pr\\s+merge\\b",
"requires": "80-ship.json",
"message": "This directive ends at MERGE, not at \"PR opened\" — so the merge is where the evidence is demanded.\n\nShape:\n {\"pr\":123,\"checks\":{\"green\":true,\"failing\":[]},\"mergeable\":\"MERGEABLE\",\n \"verdict_sha\":\"<sha the suite passed on>\",\n \"merge\":{\"method\":\"squash\",\"admin\":false,\"admin_reason\":null}}\n\nRecord the CI state you OBSERVED, not the state you expect.",
"assert": [
{
"path": "checks.green",
"equals": true,
"else": "A red check is a defect — yours, regardless of which file it points at. Diagnose the mechanism, fix the root cause, re-run the suite on the new sha, push, re-watch. A failure that does not reproduce is not a flake; it is a defect concealing itself.\n\nAdmin merge CANNOT bypass this. If it stays red after genuine remediation, park the issue with the evidence and take the next one."
},
{
"path": "checks.failing",
"empty": true,
"else": "`checks.green` says true but `checks.failing` is non-empty. Resolve the contradiction against `gh pr checks` before merging."
},
{
"path": "mergeable",
"notEquals": "CONFLICTING",
"else": "Resolve the conflict by rebasing onto the base and re-verifying — a rebase changes the sha and invalidates the prior pass. A genuinely unresolvable conflict parks the issue.\n\nAdmin merge CANNOT bypass a merge conflict: that and a red check are the two cases where it is forbidden outright."
},
{
"path": "findings_not_fixed",
"every": { "path": "issue", "integer": true, "min": 1 },
"else": "A finding you surfaced has no tracked issue.\n\nEvery entry in `findings_not_fixed` needs a real issue NUMBER. A description in the PR body is not a disposition — once this merges the PR is archive, nobody queries it, and the finding is gone. \"Happy to open a follow-up issue on request\" is the exact failure this blocks.\n\nTwo ways forward, and only two:\n 1. Fix it inline — the default, and it overrides one-concern-per-PR.\n 2. File it, THEN merge, and put the returned number in `issue` here.\n\n\"Too big to fold in\" is a reason to FILE, never a reason to merely mention: if it is large enough to justify its own PR, it is large enough to justify its own issue, and the issue is the cheaper half. An empty array is the normal case."
},
{
"when": "(^|\\s)--admin(\\s|$)",
"path": "merge.admin_reason",
"equals": "missing-secondary-reviewer",
"else": "Admin merge has exactly ONE sanctioned use: bypassing the missing-secondary-reviewer / self-review requirement. To use it, record that plainly:\n\n \"merge\": { \"admin\": true, \"admin_reason\": \"missing-secondary-reviewer\" }\n\nThat is the only accepted value. It may never stand in for a red check or a merge conflict — both are already denied above."
},
{
"when": "(^|\\s)--admin(\\s|$)",
"path": "merge.admin",
"equals": true,
"else": "The command passes --admin but the ship record says `admin: false`. Make the record match the action you are taking."
}
]
},
{
"_comment": "The next issue cannot start until this one is recorded. Catches queue abandonment.",
"on": "bash",
"match": "(^|[\\s;|&])git(\\s+-[^\\s]+)*\\s+checkout\\s+(-b|-B)(\\s|$)",
"requires": "/.gsd/bug/queue.json",
"message": "Shape: {\"issues\":[{\"issue\":123,\"branch\":\"fix/123-slug\",\"state\":\"merged|parked|skipped|closed\",\"reason\":\"<required when parked>\",\"pr\":456}]}\n\nThe parked log is the one deliverable of an unattended sweep that nobody is awake to read. As a promise in a final report it is unfalsifiable; as a file it is the thing the next branch depends on.",
"assert": [
{
"path": "issues[issue={arm.issue}].state",
"in": ["merged", "parked", "skipped", "closed"],
"else": "This issue has no terminal state in the queue, so the next issue cannot start.\n\nParking is a legitimate outcome and never halts the sweep — but an issue left with no recorded state is indistinguishable from one that was quietly abandoned. Record `merged`, `parked` (with a reason), `skipped`, or `closed`."
}
]
}
]
},
{
"_comment": "A triage directive. Edits no code, so its gates sit on OUTWARD writes. Repo-scoped, so it needs an explicit disarm.",
"name": "triage",
"scope": "repo",
"dir": ".gsd/triage",
"arm": "00-run.json",
"disarm": "90-summary.md",
"gates": [
{
"on": "bash",
"match": "\\bgh\\s+issue\\s+(comment|edit|close|reopen)\\b|\\bgh\\s+api\\b.*\\/issues\\/\\d+",
"requires": "10-worklist.md",
"message": "Persist the working set BEFORE disposing of anything: one row per issue with # · title · current labels · age · classification · disposition — including the ones you will skip.\n\nA sweep that starts writing before it has enumerated what it is sweeping cannot report at the end which issues it never reached."
},
{
"_comment": "The highest-consequence write: this label tells an unattended agent to start writing code, and it does not re-verify.",
"on": "bash",
"match": "\\bgh\\s+issue\\s+(comment|edit|close|reopen)\\b",
"when": "confirmed-bug",
"capture": {
"pattern": "gh\\s+issue\\s+(?:comment|edit|close|reopen)\\s+#?(\\d+)",
"as": "n",
"hint": "Pass the issue number positionally (`gh issue edit 1234 --add-label confirmed-bug`) so the gate can require the matching diagnosis."
},
"requires": "20-diagnosis/{n}.md",
"message": "`confirmed-bug` means \"reproduced, root-caused, ready for an agent to write the fix\" — and that agent acts on it without re-verifying.\n\nRequired sections: Reproduced (evidence — if you did not, this label is wrong) · Root cause (exact file:line) · **Tool calls made** (one line per call: tool -> what it returned) · Introduced by · Blast radius · Coupled symbols · Regression test to write first · Negative space.\n\nThe tool-calls section is the point: a grep-only guess shows up as an empty section instead of a confident label."
},
{
"on": "bash",
"match": "\\bgh\\s+api\\b.*\\/issues\\/\\d+",
"when": "confirmed-bug",
"capture": { "pattern": "\\/issues\\/(\\d+)", "as": "n" },
"requires": "20-diagnosis/{n}.md",
"message": "Same gate as the `gh issue edit` form — routing the label through the API does not change what it authorizes."
},
{
"on": "bash",
"match": "\\bgh\\s+issue\\s+close\\b",
"capture": { "pattern": "gh\\s+issue\\s+close\\s+#?(\\d+)", "as": "n" },
"requiresAnyOf": ["20-diagnosis/{n}.md", "30-decisions.json"],
"message": "Closing an issue is terminal and outward, so it needs a recorded basis: a diagnosis (defect lane — not-a-bug / already-fixed) or a decision record (enhancement / feature lane).\n\nShape: {\"decisions\":[{\"issue\":123,\"lane\":\"enhancement\",\"verdict\":\"deny\",\"source\":\"AskUserQuestion\",\"rationale\":\"...\"}]}\n\n`source` is the load-bearing field: this lane exists to give the maintainer a decision, not to make it for them. If you did not ask, there is no verdict to record and no close to perform."
},
{
"on": "bash",
"match": "\\bgh\\s+pr\\s+create\\b",
"requires": "40-oos-queue.json",
"message": "Shape: {\"entries\":[{\"issue\":123,\"slug\":\"thing.md\",\"written\":true}]} — an empty `entries` array is a valid answer and still gets recorded.\n\nA denied ask whose reasoning exists ONLY in a closed-issue comment is invisible to the next run's prior-denial check, so the same request returns and gets re-litigated from scratch. Recording `{\"entries\":[]}` is not skipping this step — it is completing it."
}
]
}
]
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |