docs(evolve): bake fix-and-repush discipline into the /evolve skill (ag-j4l1 #evolve-discipline-references)

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",

skills-codex/.agentops-manifest.json

@@ -793,7 +793,7 @@
     {
       "name": "evolve",
       "source_skill": "skills/evolve",
-      "source_hash": "a82ec266a2f22a2d6a065695f365cbf778efc063baea7aa01541f0291b1cffcb",
+      "source_hash": "98497b8eb4aba4fc1e954f622200de5d8b5eb35a12920669875d9c044d7d2715",
       "generated_hash": "5c8274c6606089b1a2854015f0f0f5176ed49806e3a6e9fce10749eeabffd01f"
     },
     {

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"
 }

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

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 -- <those>`) 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).

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 <name> --treatment parity_only|bespoke --reason "…"` (manifest entry + override-catalog + `.agentops-generated.json` marker, atomic + idempotent). Then **hand-author `skills-codex/<name>/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).

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 ]
+}