docs(ess): implementation code comes from the specification; release 0.19.1

.engineering/planning/task/ess-synthesized-implementation.md

@@ -0,0 +1,24 @@
+---
+format: aep.planning-md/3
+id: task:ess-synthesized-implementation
+kind: task
+status: implemented
+title: The ess skills route implementation through synthesized code, so a hand-transcribed model cannot drift
+owner: human:timo
+revision: 4
+transitions:
+- {from: "draft", to: "proposed", at: "2026-09-29T16:35:13Z", actor: "human:timo", revision: 2}
+- {from: "proposed", to: "active", at: "2026-09-29T16:35:13Z", actor: "human:timo", revision: 3}
+- {from: "active", to: "implemented", at: "2026-09-29T16:36:59Z", actor: "human:timo", revision: 4, decided_on: {"asserted":{"test_result":1}}}
+---
+## Outcome
+The ess skills tell an implementer to build behind `ess generate synthesize` output and never hand-transcribe the model, and say what to do while synthesis refuses a specification.
+
+## Scope
+`plugins/ess/skills/specifying/SKILL.md` (a section beside "Deterministic projections") and `plugins/ess/skills/testing-conformance/SKILL.md` (what a green suite does not prove). No CLI, agent or eval-runner change.
+
+## Acceptance
+Both sections are present in the released ess plugin; `task check` and `agentplugins-check tools` pass; the wording names no downstream product.
+
+## Authorization
+Interactive user approved the plan on 2026-09-29: skill notes, PR, merge and release.

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.19.1] — 2026-09-29
+
+The ess skills now say where implementation code comes from: the specification, through
+`ess generate synthesize`, and never a hand transcription. A hand-transcribed model passed a
+669-scenario conformance suite with every entity field unchecked.
+
+- `ess:specifying` gains "Implementation code comes from the specification": fill the generated
+  `…Behavior` and `…Query` obligations, commit the generated tree, and fail the gate when a
+  regeneration differs. When `synthesize` refuses a specification, file the refusal on
+  beyond10x/ess; until the fix ships, a hand-written model needs a test that compares it with the
+  compiled IR field by field.
+- `ess:testing-conformance`: a green suite proves only the fields its expectations read, and a
+  synthesized scenario witnesses one value per `any_of` guard.
+- `verified.json` does not move: `agentplugins-check tools` still reports aep 0.65.0 and ess 0.43.0
+  as newer than verified, and `aep plan artifact divergences` as not a command of aep 0.65.0. The
+  commands the new sections spell pass against ess 0.43.0.
+
 ## [0.19.0] — 2026-09-29
 
 A new skill investigates what cannot be re-run: a production incident, an outage, or a question

Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/agentplugins-check", "crates/b10x"]
 
 [workspace.package]
-version = "0.19.0"
+version = "0.19.1"
 edition = "2021"
 rust-version = "1.85"
 license = "Apache-2.0"

plugins/aep/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "aep",
   "displayName": "AEP",
   "description": "Plan governed work in the AEP artifact store and deliver it in reviewed waves: decomposition, plan critique, reverse engineering, story scoping, implementation and adversarial review.",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "author": {
     "name": "Beyond10x"
   },

plugins/aep/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aep",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Plan governed work in the AEP artifact store and deliver it in reviewed waves.",
   "author": {
     "name": "Beyond10x"

plugins/aep/skills/diagnosing/SKILL.md

@@ -3,7 +3,7 @@ name: diagnosing
 description: Diagnose a hard bug or a performance regression by building a red-capable feedback loop before any hypothesis, then ranked falsifiable hypotheses, one-variable probes, a regression test at the right seam, and evidence recorded in the AEP store. Use when the user says diagnose, debug, "why is this failing", "this is slow", or reports something broken, throwing, flaky or slower than before. Not for a production incident that cannot be re-run, which is `aep:investigating`; not for a failing CI job whose cause is already named in its log; and not for raising conformance coverage, which is `ess:testing-conformance`.
 ---
 
-**Skill version 0.19.0** — the version in `.claude-plugin/plugin.json`.
+**Skill version 0.19.1** — the version in `.claude-plugin/plugin.json`.
 
 # Diagnosing a failure
 

plugins/aep/skills/implementing/SKILL.md

@@ -3,7 +3,7 @@ name: implementing
 description: Implement accepted AEP work, in one of two modes. A wave picks the stories that can be implemented at once, proposes the wave for approval, dispatches one implementor per story into its own worktree, sends each result to the adversary and merges what goes green. A drive hands one story to a governed `metaharness aep drive` run and reports the run id. Use when the operator asks to implement, build or deliver planned stories, to pick or start the next wave, to implement several stories in parallel or fan out across sub-agents, to drive a story or start a governed run, or asks why a wave's rules are instructions and a drive's are enforced. A wave proposes first and stops; a drive starts one run and reports; neither moves an artifact itself.
 ---
 
-**Skill version 0.19.0** — the version in `.claude-plugin/plugin.json`; a wave's stage-1 proposal quotes it.
+**Skill version 0.19.1** — the version in `.claude-plugin/plugin.json`; a wave's stage-1 proposal quotes it.
 
 # Implementing accepted work
 

plugins/aep/skills/investigating/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Investigate a production incident, an outage or a question about a running system from evidence that can be cited — capture state before anyone remediates, build a sourced UTC timeline, date an onset from an instrument that can see a negative, compare against a healthy peer, and label every claim verified or inferred, with a catalogue of ten techniques. Use when the user says investigate, "what happened", "when did this start", "is it still happening", "has this shipped", "is this deployed", reports an alert, an outage, a hung or crashing process or a customer-visible failure, or asks for an incident report or a postmortem. Not for a defect that can be reproduced on demand, which is `aep:diagnosing`; not for checking a change before it merges, which is `aep:implementing`.
 ---
 
-**Skill version 0.19.0** — the version in `.claude-plugin/plugin.json`.
+**Skill version 0.19.1** — the version in `.claude-plugin/plugin.json`.
 
 # Investigating a live system
 

plugins/aep/skills/migrating/SKILL.md

@@ -3,7 +3,7 @@ name: migrating
 description: Migrate a repository's legacy work tracking — story trees, TODO.md, plan and issue documents — into the governed AEP planning store, without deleting or rewriting the sources. Use when the user asks to migrate, import, port or convert an existing backlog into AEP, when a repository is adopting AEP and already has work written down somewhere, or when a store has been adopted beside a legacy backlog nobody retired. Read it before creating the first artifact in a repository that already tracks work in markdown.
 ---
 
-**Skill version 0.19.0** — the version in `.claude-plugin/plugin.json`.
+**Skill version 0.19.1** — the version in `.claude-plugin/plugin.json`.
 
 # Migrating legacy tracking into the store
 

plugins/aep/skills/planning/SKILL.md

@@ -3,7 +3,7 @@ name: planning
 description: Plan engineering work in a governed markdown artifact store — create, relate, move and validate epics, stories, tasks and initiatives through the `aep` CLI. Use when the user mentions planning, a backlog, an epic, a story, a task, decomposing or breaking down work, an artifact's status ("move this to active", "what is still in draft?", "why can't this be implemented?"), or when the project contains a `.engineering/planning/` directory. Use it at adoption too — the user asks to adopt AEP, to migrate from or replace the track plugin, to start a first backlog, or works in a repository with no `.engineering/` directory at all — because § 5 says how a first store is populated and it is worth nothing after one has been hand-written. Also use before editing any file under `.engineering/planning/`.
 ---
 
-**Skill version 0.19.0** — the version in `.claude-plugin/plugin.json`.
+**Skill version 0.19.1** — the version in `.claude-plugin/plugin.json`.
 
 # Planning in a governed artifact store
 

plugins/b10x/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "b10x",
   "displayName": "Beyond10x",
   "description": "Set up, upgrade and check the Beyond10x plugins and binaries, route work to them, and create portable plugins.",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "author": {
     "name": "Beyond10x"
   },

plugins/b10x/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "b10x",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Set up, upgrade and check the Beyond10x plugins and binaries, route work to them, and create portable plugins.",
   "author": {
     "name": "Beyond10x"

plugins/connectors/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "connectors",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Set up, inspect, and invoke governed integrations through the connectors CLI.",
   "author": { "name": "Beyond10x" },
   "license": "Apache-2.0",

plugins/connectors/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "connectors",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Set up, inspect, and invoke governed integrations through the connectors CLI.",
   "author": { "name": "Beyond10x" },
   "license": "Apache-2.0",

plugins/ess/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "ess",
   "displayName": "ESS",
   "description": "Write, retrofit, validate and project Executable System Specifications, and hold implementations to them with conformance suites.",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "author": {
     "name": "Beyond10x"
   },

plugins/ess/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ess",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Write, retrofit, validate and project Executable System Specifications, and hold implementations to them with conformance suites.",
   "author": {
     "name": "Beyond10x"

plugins/ess/skills/specifying/SKILL.md

@@ -227,6 +227,34 @@ The same typed IR must produce the same ordered files and bytes. Compare a regen
 tree with the committed tree before replacing anything. A stale committed file is drift; a file no
 projection owns is not authority.
 
+## Implementation code comes from the specification
+
+**Never hand-transcribe the model into code.** Entities, their states and transitions, command
+inputs, outcomes, events, errors and views are generated; the implementation fills in only what the
+specification cannot say:
+
+```console
+ess generate synthesize --path <specification> --target rust --out <directory>
+```
+
+The generated workspace carries one `…Behavior` trait per command and one `…Query` trait per view,
+each stubbed with a typed refusal. Implement those traits and nothing beside them. Commit the
+generated tree and hold it in the gate: regenerate into a temporary directory and fail on any
+difference, exactly as for projections above. When the specification changes, regenerate; the
+compiler then names every handler the change touched.
+
+A hand transcription drifts, and nothing catches it. One passed a 669-scenario conformance suite
+with every entity field unchecked: a scenario only reads the fields its expectations name, so a
+wrong field type or a missing field that no expectation reads stays green.
+
+**When `synthesize` refuses the specification,** the refusal names each position the target cannot
+represent. That is a gap in ESS, not a licence to transcribe: file it on beyond10x/ess with the
+refusal lines. Until the fix is released, a hand-written model is allowed only with a test that
+compares it against `ess specify compile --path <specification> --format json`: every entity's
+fields and their types, every lifecycle's states and transitions, every command's input, every
+event's and error's fields, every view's fields, and every actor's `may` list. Names alone are not
+enough. Replace the hand-written model with the generated one as soon as the release is out.
+
 ## Conformance is a record, not a claim
 
 In the planning store an `executable-system-specification` is `conforming` because a suite ran and

plugins/ess/skills/testing-conformance/SKILL.md

@@ -40,6 +40,14 @@ The mechanism generalises, so learn to spot it by reading rather than by mutatin
 Do the mutation test once per mapping you rely on, and record in the commit that you did it and what
 failed. A scenario nobody has ever seen fail is a scenario that has never been tested.
 
+**A green suite does not prove the implementation's model.** It proves the fields its expectations
+read. If the implementation's entities, events or views were written by hand rather than generated
+(`ess:specifying`, "Implementation code comes from the specification"), a field no expectation
+names can have the wrong type, or be missing, and every scenario stays green. The same holds for
+guards: a synthesized scenario witnesses one value per `any_of`, so a guard over `[A, B]` is
+exercised with `A` and never with `B`. Cover the other values with the implementation's own tests,
+and prove each one can fail by breaking it once.
+
 **A cheaper check comes first: would the scenario pass against a target that does nothing?** Point
 the suite at a target whose every `ExecuteCommand` returns an accepted outcome with no state change
 and whose every `QueryView` returns an empty row. A scenario that passes there asserts only that a

plugins/worktree/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "worktree",
   "displayName": "Worktree",
   "description": "Create, lease, finish, audit and safely clean isolated Git worktrees through the worktree CLI.",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "author": {
     "name": "Beyond10x"
   },

plugins/worktree/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Create, lease, finish, audit and safely clean isolated Git worktrees through the worktree CLI.",
   "author": {
     "name": "Beyond10x"