Managed-Files-Guardrails in Consumer-Repos bringen (nicht SKILL.md): agent:check ≠ standards check

[fastner]

Problem / realer Vorfall

Ein Agent hat in einem standards-nutzenden node-Repo (sebastian-software/relanto) die managed Datei .oxfmtrc.json erweitert, um eine generierte OpenAPI-Spec (packages/backend/openapi.json) vom Formatter auszunehmen (**/openapi.json in ignorePatterns).

• Lokal war pnpm agent:check grün (lint, format:check, typecheck, build, test).
• Die CI schlug fehl im Schritt pnpm dlx @sebastian-software/standards check:

  [managed] .oxfmtrc.json: managed file differs from reference
  1 finding(s). Run `standards apply` for the mechanical part.
  

Ursache: .oxfmtrc.json ist managed (byte-exact); agent:check führt den standards check nicht aus. Der Agent bekam lokal kein Signal, dass er eine zentral verwaltete Datei verändert hat — der Konflikt tauchte erst in der CI auf.

Kernproblem: die Zielgruppe der Hinweise

Wichtige Abgrenzung: SKILL.md ist die Anweisung für den Standards-Apply-Agenten (OpenClaw) — also für den Lauf, der die Rules in ein Repo einspielt. Sie erreicht nicht einen Agenten, der in einem standards-nutzenden Repo ganz normal fachlich arbeitet (Feature/Fix/Refactor) und dabei versehentlich eine managed Root-Config anfasst.

Genau dieser Agent ist aber der, der stolpert: Er liest die AGENTS.md/Doku des Consumer-Repos, nicht die SKILL.md des Standards-Pakets, und optimiert gegen pnpm agent:check (grün) — ohne zu wissen, dass agent:check ≠ CI ist (der standards check fehlt dort) und welche Dateien managed sind.

Vorschlag: Hinweise in die Consumer-Repos bringen (nicht in SKILL.md)

Die Guidance muss dort ankommen, wo Consumer-Repo-Agents lesen. Optionen:

1. Standards-owned AGENTS.md-Section (bevorzugt). Die Standards besitzen bereits marker-delimited README-/AGENTS-Sections. Eine solche owned Section „Managed files & agent guardrails" in die AGENTS.md jedes managed Repos synchronisieren, mit:
   • Kurzliste bzw. Verweis, welche Dateien managed sind (aus manifest.json) und nicht projektlokal editiert werden dürfen (Beispiele: .oxfmtrc.json, eslint/oxlint-Config, tsconfig*, …).
   • der Warnung agent:check ≠ standards check: managed-Drift ist lokal grün, failt aber in der CI.
   • den sanktionierten Mustern (siehe unten).
2. Alternativ / ergänzend: eine seeded oder managed Hint-Datei (z. B. docs/agent-guardrails.md), die standards apply in jedes Repo bringt und die die AGENTS.md verlinkt.
3. Optional (früher lokaler Guard): empfehlen bzw. seedn, dass Consumer-Repos pnpm dlx @sebastian-software/standards check in ihren lokalen agent:check-Gate aufnehmen (oder ein standards check --only=managed-Fastpath), damit managed-Drift vor der CI auffällt.

Sanktionierte Muster (Beispiel: generiertes Artefakt vom Formatter ausnehmen)

Ohne .oxfmtrc.json anzufassen:

• Option A (bevorzugt bei Generatoren): das Artefakt im Generator-Schritt selbst mit oxfmt --write <file> formatieren, sodass es format:check besteht.
• Option B: eine nicht verwaltete Ignore-Datei — oxfmt respektiert per Default .gitignore und .prettierignore; --ignore-path=PATH (mehrfach) erlaubt eigene Dateien (Achtung: explizites --ignore-path ersetzt die Defaults → .gitignore mitangeben).

Nutzen

Consumer-Repo-Agents (und Menschen) hätten im Repo selbst eine kanonische Guardrail: keine managed Dateien projektlokal editieren, und für wiederkehrende Fälle (generierte Artefakte vs. Formatter) den vorgesehenen Weg — statt es je Repo per Trial-and-Error in der CI zu entdecken.

---

Kontext: sebastian-software/relanto PR #177 (OpenAPI-Spec-Generierung), final über Option A gelöst (oxfmt im openapi:generate-Script).

[fastner]

Gefixt in #59