docs(codegen): the template-spec is discovered, and the gap notes are retracted

Documents the fix in the two commits before this, and RETRACTS the three "known gap" notes
shipped earlier in this same session — they described the defect as permanent because at the
time it was, and leaving them would be worse than never having written them.

WHAT THE NOTES SAID AND WHY THEY GO. own-your-codegen.md, codegen-concepts.md and the
metaobjects-codegen skill each carried a warning that --template-spec was accepted by `gen`
only, that neither port auto-discovered a spec, and that adopters should therefore keep
template output OUTSIDE the directory verify --codegen diffs. All three are now false, and
the workaround they recommended is actively bad advice: output kept out of the diffed
directory is output the drift gate does not cover.

They are replaced by the convention rather than deleted silently, because the reason to
prefer the conventional path over the flag is the same fact that made the bug: `verify
--codegen` accepts no --template-spec, so discovery is the ONLY channel by which the drift
gate learns your template generators exist. That is worth stating positively at every site an
adopter reaches — a flag-only setup still works for `gen` and still leaves `verify`
resolving a different generator list.

ONE CORRECTION I OWE. The retracted notes claimed Python "convicts their committed output"
unconditionally. That was true only for a spec emitting .py — the one extension the old
*.py-scoped comparison could see. For every other extension it was the opposite failure,
silence, and the CHANGELOG entry now states both halves with the reproduction for each. I
had verified the .py case and generalised from it.

Per-port pages get the worked form: the conventional path, the anchor (the metadata dir's
parent, which is what .metaobjects/ already uses), the flag-overrides rule, and a two-line
gen/verify pair showing both verbs resolving the same file. python.md additionally documents
the declarative-config-mode refusal, and notes the flag-name asymmetry that trips people:
`gen` spells the templates dir --templates, while on `verify` that name is the SUBVERB, so
the directory flag there is --templates-root.

cli.md's C# and Python rows say the flag is auto-discovered and why the conventional path is
the one to use.

The roadmap entry moves from Planned to the SP-3 shipped block — carrying the C# jurisdiction
gap forward as explicitly still open, since that is the one thing here that was found and
NOT fixed, and it must not disappear with the entry that named it.

Fixture churn: all five agent-context-conformance corpora regenerated from tracked source.

Verified: doc-example gate 0 (91 examples), site-payload fresh, site-reference fresh (16
pages), sdk 300/0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HSCgs7z19w8aGXGiceCohC

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,76 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — `verify --codegen` convicted the output `gen` had just written (C#, Python)
+
+The declarative Mustache template-spec was wired into `gen` and nowhere else, so the drift
+gate regenerated a **different generator list** than the generator did — and then failed the
+project for the difference. Reproduced against the shipped code:
+
+```
+$ metaobjects gen ./meta --out ./out --template-spec spec.json --templates ./templates
+...wrote 9 file(s)
+$ metaobjects verify --codegen ./meta --out ./out
+error: generated code is out of sync with metadata.
+  extra:   OrderService.py
+  extra:   ProductService.py
+regenerate (metaobjects gen) and commit the result.        EXIT 1
+```
+
+The printed remedy is a **loop**: regenerating cannot produce files the regen does not know
+about, and `verify` accepts no `--template-spec` to be told. C# failed the same way
+(`committed but a fresh regen would not emit it`). It lands on exactly the two ports whose
+generator registries are closed — where the template-spec is the **only** consumer authoring
+path — so an adopter doing the one thing their port supports failed their own gate.
+
+**SP-1 §4 had specified the fix and it was never built:** *"`--template-spec <path>`, with a
+conventional default the port auto-discovers and the flag overriding"*, and that **both**
+`gen` and `verify` read it. Only the flag on `gen` shipped. Both ports now resolve the spec
+through **one shared helper**: explicit flag wins, else `<projectRoot>/template-spec.json`,
+where projectRoot is the metadata dir's **parent** — not a new rule, it is the anchor
+`.metaobjects/.gen-state/` already uses on both ports. A flag on `verify` was rejected
+deliberately: it would need repeating at every CI call site, and one forgotten reproduces the
+bug exactly.
+
+**Python was blind as well as wrong, and that half was worse.** For a spec emitting anything
+other than `.py`, there was no false conviction — there was silence. With one generated file
+**deleted** and another **overwritten with garbage**, the gate answered:
+
+```
+metaobjects verify: in sync (7 file(s)).                   EXIT 0
+```
+
+`_relative_set` globbed `*.py` under a docstring that had already called it — *"if a
+generator ever emits a non-`.py` artifact, broaden this glob so `verify` drift-checks it
+too."* One does: template-spec output is format-agnostic by design (text/markdown/csv/
+json/xml/html), which is the **common** case, so the usual configuration was ungated
+entirely. The comparison now covers every text artifact (skipping `__pycache__`/`*.pyc` and
+anything that will not decode).
+
+**Broadening it required the jurisdiction rule, or it would have re-created the bug it
+fixes.** Seeing every file in `outDir` means convicting every stranger in it — precisely what
+failed a zero-drift project in TypeScript and produced the `0.24.3` ruling: **`outDir` is a
+directory, not a namespace this tool owns.** The manifest already records what we *wrote*,
+keyed relative to `out_dir` — the same key space the diff uses — so `extra` is now scoped to
+files with a write record, failing closed when there is no manifest. C# needed neither half:
+its comparison already enumerated `*`.
+
+Also: Python's declarative-config mode **accepted `--template-spec` and silently did
+nothing** (`_cmd_gen_config` goes straight to `_run_gen_targets`, which has no spec pass). It
+now refuses with the working form, because it cannot simply be honoured — a spec entry names
+no `target` while config mode writes per target, so there is no non-arbitrary outDir. A
+*discovered* spec is ignored there rather than refused, so discovery can never hard-fail a
+command that did not ask for it.
+
+**Behaviour change:** a project that already has `<projectRoot>/template-spec.json` and
+passes no flag will now run it. Exposure is near zero — the filename is only meaningful if
+you knew of a flag that had no default — but it is real.
+
+**Known and NOT fixed:** C#'s `CodegenDrift` has no jurisdiction guard on its
+`inCommitted && !inFresh` branch, so it still convicts files it never wrote — the
+pre-`0.24.3` TypeScript behaviour. It is not introduced here and fixing it changes `verify`'s
+verdict for every existing C# adopter, so it is reported rather than folded in.
+
 ### Fixed — a reference fragment the stack no longer uses is deleted, not announced forever
 
 `meta init --refresh-docs --server typescript` on a project scaffolded as python left

agent-context/skills/metaobjects-codegen/SKILL.md

@@ -361,12 +361,11 @@ reach for it here.) Use `--template-spec <json>` — plus `--templates <dir>` on
 `--template-root <dir>` on C# — and your entries are appended to the default suite. Worked
 examples with the full JSON: `docs/ports/python.md` and `docs/ports/csharp.md`.
 
-**One caveat to plan around on those two ports:** `--template-spec` is accepted by `gen`
-only. `verify` does not take it and neither port auto-discovers a spec file, so
-`verify --codegen` regenerates WITHOUT your template generators and reports their
-committed output as stale — Python prints `extra: <path>` and exits 1, and the remedy it
-prints is a loop. Emit template-spec output somewhere other than the directory
-`verify --codegen` diffs, and do not "fix" the failure by deleting the files.
+**The spec is auto-discovered, and that is load-bearing.** With no `--template-spec`, both
+ports read `<projectRoot>/template-spec.json` — projectRoot being the metadata dir's parent.
+Keep it there: `verify --codegen` accepts no `--template-spec` flag, so the conventional path
+is how the drift gate learns your template generators exist. Put the spec somewhere else and
+reach it only by flag, and `verify` regenerates without it and reports its output as stale.
 
 So on C#/Python, "I need a shape the built-ins do not emit" is answered by a template, not
 by writing generator code. Do not conclude the port cannot be customized.

docs/features/cli.md

@@ -34,10 +34,10 @@ command surface splits in two:
 | **Vocabulary upgrade** (`upgrade`) | **Node `meta`** | `meta upgrade [--to <version>] [--apply]` | **any backend** — rewrites RETIRED metadata vocabulary (`@violation` → `@counterexample`, `@readOnly` → `@mutability`, dropping `@verifiedBy`) and resolves ATTRIBUTE CONTRADICTIONS (`@fields` beside `@expr` on an index key). Node-only because it edits the metadata documents themselves, which every port shares; a non-TS project runs `npx meta upgrade` against its own `metaobjects/`. **Canonical JSON and YAML alike.** Previews by default. Retirements needing a human decision are refused and the run exits non-zero, so CI cannot record a partial migration as finished |
 | **Vocabulary search** (`types`) | **Node `meta`** | `meta types [query]` | **any backend** — apropos/`kubectl explain` over the live metamodel registry (names + descriptions + when-to-use); the vocabulary is cross-port identical (registry-conformance) |
 | TS codegen | Node `meta` | `meta gen` | TS projects. **No `--template-spec` flag, deliberately** — `metaobjects.config.ts` already takes generator VALUES, so a declarative template generator is declared there (`templateGenerator()`, or `templateSpecToGenerators(parseTemplateSpec(spec))` to reuse a C#/Python spec file). Keeping it in the config is what lets `meta verify --codegen` regenerate WITH it, since that gate re-runs the config's generator list; see [declarative template scopes](codegen-concepts.md#declarative-template-scopes) |
-| C# codegen | `dotnet meta` | `dotnet meta gen` / `verify --templates` / `verify --codegen` | a .NET tool (`ToolCommandName=dotnet-meta`); invoked `dotnet meta` so it never shadows the Node `meta`; ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2; bare `verify` = `--templates`). `gen` also accepts `--template-spec <json>` (+ `--template-root <dir>`, default `templates`) — the declarative Mustache template-codegen surface (the cross-port JSON contract shared with Python); see [declarative template scopes](codegen-concepts.md#declarative-template-scopes) |
+| C# codegen | `dotnet meta` | `dotnet meta gen` / `verify --templates` / `verify --codegen` | a .NET tool (`ToolCommandName=dotnet-meta`); invoked `dotnet meta` so it never shadows the Node `meta`; ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2; bare `verify` = `--templates`). `gen` also accepts `--template-spec <json>` (+ `--template-root <dir>`, default `templates`) — the declarative Mustache template-codegen surface (the cross-port JSON contract shared with Python), **auto-discovered at `<projectRoot>/template-spec.json`** when the flag is absent. Prefer the conventional path: `verify --codegen` takes no `--template-spec`, so discovery is how the drift gate sees your template generators at all; see [declarative template scopes](codegen-concepts.md#declarative-template-scopes) |
 | Java/Kotlin codegen | Maven plugin | `mvn metaobjects:generate` (`metaobjects:generate`) | Kotlin generators run through the same goal — see below. **No `--template-spec` flag, deliberately** — `<generator>` already loads a consumer class from the project classpath, so the declarative surface is `com.metaobjects.generator.template.TemplateScopeGenerator` wired as an ordinary `<generator>` with `<template>` / `<scope>` / `<outputPattern>` / `<templatesDir>` / `<format>` args (covers BOTH Java and Kotlin); see [declarative template scopes](codegen-concepts.md#declarative-template-scopes). The `generate`/`verify`/`docs` goals are declared `threadSafe` and support parallel multi-module reactor builds (`mvn -T`) (#233) |
 | Java/Kotlin verify | Maven plugin | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`metaobjects:verify`) | parameter-driven ADR-0021 D2 modes (one goal covers BOTH Java + Kotlin): `codegen` (default, back-compat — regen + fail on drift vs committed output, generator-neutral) / `templates` (`{{field}}`↔payload drift via the render `Verify` engine). `db` rejected ("schema verify is the migrate engine, ADR-0015") |
-| Python codegen | console-script | `metaobjects gen` / `verify --codegen` / `verify --templates` | `[project.scripts] metaobjects` — **not** `meta` (that's the Node schema CLI); ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2). `gen` also accepts `--template-spec <json>` (+ `--templates <dir>`, default `templates`) — the declarative Mustache template-codegen surface (the cross-port JSON contract shared with C#); see [declarative template scopes](codegen-concepts.md#declarative-template-scopes) |
+| Python codegen | console-script | `metaobjects gen` / `verify --codegen` / `verify --templates` | `[project.scripts] metaobjects` — **not** `meta` (that's the Node schema CLI); ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2). `gen` also accepts `--template-spec <json>` (+ `--templates <dir>`, default `templates`) — the declarative Mustache template-codegen surface (the cross-port JSON contract shared with C#), **auto-discovered at `<projectRoot>/template-spec.json`** when the flag is absent (and REFUSED in declarative-config mode, where a spec has no target to write into). Prefer the conventional path: `verify --codegen` takes no `--template-spec`, so discovery is how the drift gate sees your template generators at all; see [declarative template scopes](codegen-concepts.md#declarative-template-scopes) |
 
 ## `verify` is one verb with explicit subverbs (ADR-0021 D2)
 

docs/features/codegen-concepts.md

@@ -242,10 +242,11 @@ overwrite a file lacking the `@generated` marker — a regenerable template must
 that header in its own body. The JVM's `TemplateScopeGenerator` writes directly and
 carries no such obligation.)
 
-**Known gap on the two flag ports.** `--template-spec` is accepted by `gen` only.
-Neither `metaobjects verify` nor `dotnet meta verify` takes it, and neither port
-auto-discovers a spec file, so `verify --codegen` regenerates without your template
-generators and convicts their committed output as stale. The ports that have a code
-seam (TypeScript, JVM) do not have this problem, because there the declaration lives
-in the build config that the drift gate re-runs. Details and the workaround:
-[`own-your-codegen.md`](own-your-codegen.md#per-port).
+**The spec is auto-discovered.** With no `--template-spec`, both CLI ports read
+`<projectRoot>/template-spec.json` (projectRoot = the metadata dir's parent, the anchor
+`.metaobjects/` already uses); the flag overrides it. This is what lets `verify --codegen`
+regenerate WITH your template generators — it accepts no `--template-spec` of its own, so a
+flag-only setup would leave the gate resolving a different generator list from `gen` and
+convicting gen's own output. The ports with a code seam (TypeScript, JVM) declare template
+generators in the build config the gate already re-runs, reaching the same guarantee a
+different way.

docs/features/own-your-codegen.md

@@ -152,18 +152,19 @@ output *shape* is what you are iterating on, or when you want the same output ac
 languages; reach for a generator when the logic is gnarly or the run is hot. Full
 tradeoff table: [`codegen-concepts.md` §3](codegen-concepts.md).
 
-> **Known gap on the two flag ports.** `--template-spec` is a flag on `gen` only —
-> neither `metaobjects verify` nor `dotnet meta verify` accepts it, and neither port
-> auto-discovers a spec file. So `verify --codegen` regenerates WITHOUT your template
-> generators and convicts their committed output — Python classifies each as
-> `extra: <path>` (*"stale committed file"*) and exits 1, and the remedy it prints
-> (*"regenerate and commit the result"*) is a **loop**: regenerating without the flag
-> cannot produce those files, and regenerating with it leaves the gate failing
-> identically. Until that is closed, keep template-spec output outside the directory
-> `verify --codegen` diffs, or run the gate only against the default suite.
-> (This is why the two ports that have a code seam —
-> TypeScript and the JVM — declare template generators in the build config instead: the
-> config is what the drift gate re-runs.)
+**The spec file is discovered, not just flagged.** With no `--template-spec`, both ports
+look for **`<projectRoot>/template-spec.json`** — projectRoot being the metadata dir's
+parent, the same anchor `.metaobjects/` already uses. The flag overrides it.
+
+That matters for more than typing: `verify --codegen` takes **no** `--template-spec` flag,
+so discovery is how the drift gate learns about your template generators. Before it existed,
+`gen` honoured the flag and `verify` never looked — so verify regenerated without them and
+convicted their committed output, with a remedy that loops. Keep the spec at the
+conventional path and both verbs resolve the same one.
+
+Passing `--template-spec` explicitly still works and still wins; just make sure any CI that
+runs `verify --codegen` can find the spec, which the conventional path guarantees and a
+flag-only setup does not.
 
 *(Full command/flag matrix and rationale: [`docs/features/cli.md`](cli.md), locked per
 ADR-0015. Schema migrations are TypeScript-owned across all ports.)*

docs/ports/csharp.md

@@ -260,6 +260,22 @@ dotnet meta gen ./metadata --out ./Generated \
 ]}
 ```
 
+**The spec is auto-discovered.** Omit `--template-spec` and the CLI reads
+`<projectRoot>/template-spec.json`, where projectRoot is the metadata dir's **parent** —
+the same anchor `.metaobjects/` uses (`GenCommand.ProjectRootFor`). The flag overrides it.
+
+Prefer the conventional path over the flag, because **`dotnet meta verify --codegen`
+accepts no `--template-spec`**: discovery is how the drift gate learns your template
+generators exist. A spec reachable only by flag leaves `verify` regenerating a different
+generator list from `gen` and convicting your committed template output as
+"committed but a fresh regen would not emit it".
+
+```bash
+dotnet meta gen ./metadata --out ./Generated --template-root ./templates
+dotnet meta verify --codegen ./metadata --out ./Generated --template-root ./templates
+#   ^ both resolve <projectRoot>/template-spec.json — the gate agrees with the generator
+```
+
 Each spec entry derives the neutral template data dict for its scope
 (`MetaObjects.Codegen.TemplateCodegen.TemplateData`) and names each file via the
 `outputPattern` placeholders (`{name}`, `{Name}`, `{package}`). The named generators

docs/ports/python.md

@@ -194,6 +194,29 @@ metaobjects gen ./metadata --out ./generated \
 ]}
 ```
 
+**The spec is auto-discovered.** Omit `--template-spec` and the CLI reads
+`<projectRoot>/template-spec.json`, where projectRoot is the metadata dir's **parent** —
+the same anchor `.metaobjects/` uses. The flag overrides it.
+
+Prefer the conventional path over the flag, because **`verify --codegen` accepts no
+`--template-spec`**: discovery is how the drift gate learns your template generators exist.
+A spec reachable only by flag leaves `verify` regenerating a different generator list from
+`gen` and reporting your committed template output as stale.
+
+```bash
+metaobjects gen ./metadata --out ./generated --templates ./templates
+metaobjects verify --codegen ./metadata --out ./generated --templates-root ./templates
+#   ^ both resolve <projectRoot>/template-spec.json — the gate agrees with the generator
+```
+
+(`gen` spells the templates dir `--templates`; on `verify` that name is the *subverb*, so
+the directory flag there is `--templates-root`.)
+
+`--template-spec` is **refused in declarative-config mode** (`metaobjects.config.yaml`,
+no positional metadata dir) rather than silently ignored: a spec entry names no `target`
+while config mode writes per target, so there is no outDir to render into. A *discovered*
+spec is ignored there rather than refused.
+
 Each spec entry derives the neutral template data dict for its scope and names
 each file via the `outputPattern` placeholders (`{name}`, `{Name}`, `{package}`).
 The named generators are **appended** to the default suite and gated byte-identical

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-codegen/SKILL.md

@@ -361,12 +361,11 @@ reach for it here.) Use `--template-spec <json>` — plus `--templates <dir>` on
 `--template-root <dir>` on C# — and your entries are appended to the default suite. Worked
 examples with the full JSON: `docs/ports/python.md` and `docs/ports/csharp.md`.
 
-**One caveat to plan around on those two ports:** `--template-spec` is accepted by `gen`
-only. `verify` does not take it and neither port auto-discovers a spec file, so
-`verify --codegen` regenerates WITHOUT your template generators and reports their
-committed output as stale — Python prints `extra: <path>` and exits 1, and the remedy it
-prints is a loop. Emit template-spec output somewhere other than the directory
-`verify --codegen` diffs, and do not "fix" the failure by deleting the files.
+**The spec is auto-discovered, and that is load-bearing.** With no `--template-spec`, both
+ports read `<projectRoot>/template-spec.json` — projectRoot being the metadata dir's parent.
+Keep it there: `verify --codegen` accepts no `--template-spec` flag, so the conventional path
+is how the drift gate learns your template generators exist. Put the spec somewhere else and
+reach it only by flag, and `verify` regenerates without it and reports its output as stale.
 
 So on C#/Python, "I need a shape the built-ins do not emit" is answered by a template, not
 by writing generator code. Do not conclude the port cannot be customized.