diff --git a/registry.json b/registry.json index 130b24086..496487655 100644 --- a/registry.json +++ b/registry.json @@ -1,6 +1,6 @@ { "schema_version": 2, - "generated_at": "2026-05-30T01:23:51Z", + "generated_at": "2026-05-30T02:15:34Z", "summary": { "skills": 80, "hooks": 0, @@ -178,7 +178,7 @@ "path": "skills/evolve/", "has_skill_md": true, "has_references": true, - "reference_count": 25 + "reference_count": 26 }, { "name": "grafana-platform-dashboard", @@ -1983,7 +1983,7 @@ "ao rpi loop" ], "path": "skills/evolve/", - "references": 25 + "references": 26 }, { "sku": "skill:flywheel", diff --git a/skills-codex/.agentops-manifest.json b/skills-codex/.agentops-manifest.json index 31ee25142..7b93736d7 100644 --- a/skills-codex/.agentops-manifest.json +++ b/skills-codex/.agentops-manifest.json @@ -793,7 +793,7 @@ { "name": "evolve", "source_skill": "skills/evolve", - "source_hash": "a82ec266a2f22a2d6a065695f365cbf778efc063baea7aa01541f0291b1cffcb", + "source_hash": "98497b8eb4aba4fc1e954f622200de5d8b5eb35a12920669875d9c044d7d2715", "generated_hash": "5c8274c6606089b1a2854015f0f0f5176ed49806e3a6e9fce10749eeabffd01f" }, { diff --git a/skills-codex/evolve/.agentops-generated.json b/skills-codex/evolve/.agentops-generated.json index 69861fb9d..857de77b6 100644 --- a/skills-codex/evolve/.agentops-generated.json +++ b/skills-codex/evolve/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/evolve", "layout": "modular", - "source_hash": "a82ec266a2f22a2d6a065695f365cbf778efc063baea7aa01541f0291b1cffcb", + "source_hash": "98497b8eb4aba4fc1e954f622200de5d8b5eb35a12920669875d9c044d7d2715", "generated_hash": "5c8274c6606089b1a2854015f0f0f5176ed49806e3a6e9fce10749eeabffd01f" } diff --git a/skills/evolve/SKILL.md b/skills/evolve/SKILL.md index a0aa989df..d58c4c238 100644 --- a/skills/evolve/SKILL.md +++ b/skills/evolve/SKILL.md @@ -299,6 +299,8 @@ Before invoking the regression gate, sync downstream artifacts when the staged d Without these, the gate fails on stale-binary or embedded-drift errors that look like real regressions. See `references/gate-hygiene.md` for the detection recipe. +**Adding or modifying a skill?** A skill touches **six derived surfaces** (registry.json SKU catalog, skill-domain-map, context-map, skill counts + the hand-added `SKILL-TIERS.md` row, codex twin, narrative counts) — regenerate them in one shot via `scripts/regen-all.sh` + the codex/count steps, never piecemeal. The most-missed is `registry.json` (stale → `contracts-sync` + `correctness(ubuntu)` fail together). See [references/new-skill-landing.md](references/new-skill-landing.md) for the full procedure, then [references/gate-hygiene.md](references/gate-hygiene.md) for the pre-push diff-scope check + pre-existing-vs-mine red triage. + ### Step 5: Regression Gate After execution, run the project build+test bundle. If the repo execution profile declared `validation_commands`, run them. If a repo-local program contract exists, run its `validation_commands` too, de-duplicated and in declared order after the repo bootstrap checks. Also check `if [ -f scripts/check-wiring-closure.sh ]; then bash scripts/check-wiring-closure.sh; fi`. @@ -447,7 +449,8 @@ See `references/cycle-history.md` for advanced troubleshooting. - [references/cycle-history.md](references/cycle-history.md) — JSONL format, recovery protocol, kill switch - [references/examples.md](references/examples.md) — Detailed usage examples - [references/fitness-scoring.md](references/fitness-scoring.md) — Baseline capture, regression detection, revert procedure -- [references/gate-hygiene.md](references/gate-hygiene.md) — Pre-gate source-surface detection and structural gate-output parsing +- [references/gate-hygiene.md](references/gate-hygiene.md) — Pre-gate source-surface detection, structural gate-output parsing, pre-push diff-scope check, pre-existing-vs-mine red triage +- [references/new-skill-landing.md](references/new-skill-landing.md) — The six derived surfaces a new/modified skill must regenerate in one shot to stay one-shot-green - [references/goals-schema.md](references/goals-schema.md) — GOALS.yaml format and continuous metrics - [references/knowledge-loop-integration.md](references/knowledge-loop-integration.md) — Claim/release semantics and harvest re-read - [references/mechanical-batches.md](references/mechanical-batches.md) — Script-first vs per-file Edit for > 20-file uniform batches diff --git a/skills/evolve/references/gate-hygiene.md b/skills/evolve/references/gate-hygiene.md index f0973b264..b63d6b7ce 100644 --- a/skills/evolve/references/gate-hygiene.md +++ b/skills/evolve/references/gate-hygiene.md @@ -52,3 +52,23 @@ Documented release valve for the eval canary lane only, when: - A recorded recent run has confirmed the canary is currently 50/50 Never use `--no-verify`. The pre-commit hook is a no-op for most diffs but the principle violation is durable in `git log` and surfaces in post-mortem. + +## Pre-push diff-scope check (mandatory before every commit) + +Two cheap pre-commit reads catch the failure modes that cost a full fix-and-repush round each (the 2026-05-29 `/burndown` + codex-budget reds): + +1. **`git status --short` must show ALL intended files staged.** A half-staged commit — the feature gate-script left out while only its test was committed — let CI run the *old* code so the new assertion could not pass (the #612 red). A feature and its test are one commit, not the test alone. +2. **`git diff origin/main --stat` must be SCOPE-ONLY.** Confirm: no collateral deletions (a `git checkout --theirs` conflict take silently dropped two *unrelated* skill rows in the #600 rebase), and no lossy whole-file reformats (a 252-line `catalog.json` round-trip — discard those and use the idempotent appender). For generated/narrative files, restore `origin/main`'s version and **re-run the generator** rather than hand-merging. + +## Triage red precisely — pre-existing-main vs your-change + +Not every red is yours. The `agentops` main branch carries known pre-existing failures a local gate or a broad generator will surface: + +- **Local `mkdocs --strict`** fails on tracked docs because the system `mkdocs` (≤1.1.2) can't parse the modern `mkdocs.yml` (needs material plugins). CI uses the venv and passes. Confirm a flagged file is `git ls-tree origin/main`-tracked AND absent from your diff → pre-existing, proceed. +- **~7 codex `.agentops-generated.json` drifts** (deps, provenance, red-team, release, scenario, trace, using-agentops): `regen-codex-hashes.sh` "updates" them because they're drifted on main. **REVERT them** (`git checkout origin/main -- `) and keep only your skill's hash; surgically rebuild the manifest from `origin/main` + your delta. The CI artifact gate is changed-files-scoped (`--scope head`) so it ignores the pre-existing drift; sweeping them in adds unrelated churn and risks a manifest↔marker mismatch. + +**Rule:** only fix red your own diff introduced. When a generator touches files outside your bead's scope, revert those files. "The generator changed it" never justifies shipping unrelated drift. + +## See also + +- [new-skill-landing.md](new-skill-landing.md) — the six derived surfaces a new/modified skill must regenerate in one shot (the companion to this diff-scope discipline). diff --git a/skills/evolve/references/new-skill-landing.md b/skills/evolve/references/new-skill-landing.md new file mode 100644 index 000000000..8ad8d6fe8 --- /dev/null +++ b/skills/evolve/references/new-skill-landing.md @@ -0,0 +1,24 @@ +# New-Skill Landing — the six derived surfaces + +Adding or modifying a skill regenerates **six derived surfaces**, each gated by CI. Regenerating them piecemeal is the dominant fix-and-repush cause (the 2026-05-29 `/burndown` re-land needed 3 rounds; the codex-desc-budget fix needed 1). Regenerate them in **one shot** before opening the PR. + +## The shortcut + +`scripts/regen-all.sh` covers surfaces 1–3 + the CLI reference in one pass — prefer it over running the generators individually. Then run the codex + count steps below. + +## The six surfaces + +1. **registry.json (SKU catalog)** — `scripts/generate-registry.sh` (verify with `--check`). **The most-missed surface**: a stale `registry.json` trips `contracts-sync` ("registry.json is stale") AND `correctness(ubuntu)` ("SKU_CATALOG: DRIFT") *together*. As of ag-ekyq, `skills/skill-builder/scripts/init.sh` regenerates it automatically during scaffold; regenerate by hand for any out-of-band skill edit. +2. **skill-domain-map** — `scripts/generate-skill-domain-map.sh` (narrative `N skills` count + per-skill row; verify `--check`). +3. **context-map** — `scripts/generate-context-map.sh` (hex roles from frontmatter; CI gate `validate-context-map-drift`). +4. **skill counts** — `scripts/sync-skill-counts.sh`. **The `SKILL-TIERS.md` row must be added by hand** — `sync-skill-counts` only syncs the *counts* across PRODUCT/ARCHITECTURE/SKILLS/using-agentops; it never adds the row. +5. **codex twin** — `scripts/register-new-codex-skill.sh --treatment parity_only|bespoke --reason "…"` (manifest entry + override-catalog + `.agentops-generated.json` marker, atomic + idempotent). Then **hand-author `skills-codex//prompt.md`** — codex twins are MANUAL; `regen-all.sh` does NOT generate them. Re-run `scripts/regen-codex-hashes.sh` afterward (adding `prompt.md` changes the tree hash). Parity_only minimal `prompt.md` = title + description + an `## Instructions` block ("Load and follow the sibling `SKILL.md`"). +6. **narrative skill counts** — `scripts/check-registry-drift.sh --fix-counts` (the `N skills` lines in `agentops-skill-domain-map.md` + `agentops-domain-evolution-bdd.md`). + +## Embedded sync + +If the edit touches `skills/**` content that is embedded (e.g. `using-agentops`), run `cd cli && make sync-hooks` so `cli/embedded/skills/...` stays in sync — else the `codex artifact metadata`/embedded-drift gate fails. + +## See also + +- [gate-hygiene.md](gate-hygiene.md) — pre-push diff-scope check + pre-existing-vs-mine red triage (the companion discipline that keeps a new-skill PR one-shot-green). diff --git a/tests/scripts/evolve-discipline-references.bats b/tests/scripts/evolve-discipline-references.bats new file mode 100644 index 000000000..0b5411576 --- /dev/null +++ b/tests/scripts/evolve-discipline-references.bats @@ -0,0 +1,36 @@ +#!/usr/bin/env bats +# ag-j4l1: the /evolve skill must bake in this session's fix-and-repush discipline +# as durable references — new-skill-landing.md (the six derived surfaces) and the +# gate-hygiene.md additions (pre-push diff-scope check + pre-existing-vs-mine red +# triage). Every references/*.md must be linked from SKILL.md (heal --strict rule); +# this locks the two specific links so they cannot silently drop. + +SKILL="$BATS_TEST_DIRNAME/../../skills/evolve/SKILL.md" +REF_DIR="$BATS_TEST_DIRNAME/../../skills/evolve/references" + +@test "new-skill-landing.md reference exists and enumerates the six surfaces" { + [ -f "$REF_DIR/new-skill-landing.md" ] + run grep -c "registry.json" "$REF_DIR/new-skill-landing.md" + [ "$status" -eq 0 ] + # The six numbered surfaces + the regen-all.sh shortcut must be present. + grep -q "regen-all.sh" "$REF_DIR/new-skill-landing.md" + grep -q "register-new-codex-skill.sh" "$REF_DIR/new-skill-landing.md" + grep -q "SKILL-TIERS.md" "$REF_DIR/new-skill-landing.md" +} + +@test "SKILL.md links new-skill-landing.md (heal --strict reference-linkage rule)" { + run grep -E 'references/new-skill-landing\.md' "$SKILL" + [ "$status" -eq 0 ] +} + +@test "gate-hygiene.md gained the pre-push diff-scope + red-triage subsections" { + run grep -E '## Pre-push diff-scope check' "$REF_DIR/gate-hygiene.md" + [ "$status" -eq 0 ] + run grep -E '## Triage red precisely' "$REF_DIR/gate-hygiene.md" + [ "$status" -eq 0 ] +} + +@test "gate-hygiene.md is linked from SKILL.md" { + run grep -E 'references/gate-hygiene\.md' "$SKILL" + [ "$status" -eq 0 ] +}