Restructure SKILL.md to an entry-only spine with recorded simulation evidence and a release gate

Andrew Dunnrequested to merge
skill-lifecycle-restructure into main

What this does

Lands a full skill-lifecycle pass in seven commits: SKILL.md becomes an entry-only spine, the seeding runbook moves to a branch sibling, the description is rewritten and validated by a recorded routing test, and releases gain a simulation-evidence gate that CI enforces at tag time.

Why

Two measurements drove this:

  • The SDLC-seeding runbook (~175 lines) was 59% of a 299-line SKILL.md, and only the seed-a-population branch ever reaches it. Every other consumer (Duo Agent Platform, airgap, devtier) paid its context cost on every load.
  • The frontmatter description spent characters on clauses that route nothing ("declarative just entrypoint, runtime-agnostic", "for LLM-mediated simulation") and stated no boundary for what the skill does not cover.

Evidence (in-repo, skills/gitlab-simulator/sims/)

  • Routing fire test: KEEP. Two blind arms (original description vs rewrite) against an identical 15-task battery that attacks every deleted clause and probes the added boundary. Both arms routed 15/15 identically, so the deleted clauses carried no routing weight; the rewrite is 90 characters shorter in every consumer's skill index. Run record and caveats in sims/fire-battery.md.
  • Fidelity test: SAFE. A blind planner working only from the split docs retained all three buried catches: Security reads zero without both an Ultimate license and a registered runner (and zero is the honest expected result), API-seeded activity timestamps stamp at call time, and the admin personal access token lives on the VM at /var/lib/simulation/root-pat.json. Run record in sims/fidelity-test.md.

Changes by commit

Commit What
Replace dated seeding validation note Present-tense capability prose, per the repo's own AGENTS.md voice rule
Split seeding block into gce/seeding.md SKILL.md 299 to 135 lines; the pointer flags the sharp edges so a consumer reads the sibling instead of improvising; manifold's worked example is marked as a reference implementation and an optional dependency
Rewrite description and scope execution to just 495-character description (was 585); allowed-tools: Bash(just *) Bash(just) Read makes the justfile the enforced front door, so raw gcloud detours become operator-gated
Re-baseline the 0.1.0 changelog entry The entry now matches the tree: three install bases, airgap single- and two-plane, AIGW slow-model scenario, seeding layer, drift-check CI
Add sims apparatus and a tag-only release gate Batteries live in sims/; just sims-check asserts a recorded KEEP verdict whose description-hash matches the current description; CI runs it on tags only as plain shell assertions
Add a Skill changes contributor gate Description edits re-run the fire test, body restructures re-run the fidelity test, just sims-check joins the MR checklist; a bootstrap-phase self-merge exception applies while CODEOWNERS lists a single owner
Record sims verdicts fire KEEP, fidelity SAFE, dated run records with caveats

After merge

Cut v0.1.0 as an annotated tag with a release. The changelog and the sims gate are aligned to that tag, and any future description edit that lands without a re-recorded verdict fails the tag pipeline.

Merge request reports