foundry-implementation-actor 0.2.0__tar.gz → 0.5.0__tar.gz

foundry_implementation_actor-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,132 @@
+name: ci
+on: [push, pull_request]
+
+# NO CREDENTIAL. Nothing here authenticates to anything: no lab repo, no knowledge registry, no
+# PyPI upload, no image push. Everything this pipeline asserts about THIS package, it asserts from
+# source and from artifacts it built itself — the wheel it just built, and an image built from
+# that wheel rather than from a published one.
+#
+# It does reach the network for inputs: public base images and the npm package the engine drives.
+# That is fetching, not authenticating, and the distinction is the one that matters here — no
+# secret is available to this workflow, so nothing it runs can reach a real capability's repo.
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: the test suite
+        run: uv run --extra dev pytest -q
+
+      - name: build
+        run: uv build
+
+      # ── the two gates a contract-shipping package runs against its own artifact ────────────
+      #
+      # The suite above proves the code works in a source checkout. Neither of these does — they
+      # prove the WHEEL works, which is a different claim and the one a consumer actually depends
+      # on. A schema left out of the build passes every test in tests/ and fails here.
+
+      - name: the wheel must carry its contract
+        run: |
+          uv venv /tmp/probe
+          uv pip install --python /tmp/probe/bin/python -q dist/*.whl
+          /tmp/probe/bin/foundry-implementation-actor lint examples/ACME.PARTS.CAP.SUP.007.WID-implementation
+          /tmp/probe/bin/foundry-implementation-actor show examples/ACME.PARTS.CAP.SUP.007.WID-implementation \
+            --registry reg.example.com | tee /tmp/show.txt
+          grep -q 'reg.example.com/acme.parts/sup.007.wid/backend:<version>' /tmp/show.txt
+
+      - name: the wheel must carry the actor's own cards
+        # The `-actor` suffix asserts a papeete-actor underneath, which lint-card can check
+        # (ADR-ECO-0022). The suite proves the cards are conformant in a source checkout; this
+        # proves they SHIPPED. A card folder left out of the build passes every test in tests/ and
+        # makes the name a claim the artifact cannot honour. `papeete-actor-synchronous-messaging`
+        # is already a runtime dependency, so its gate is in the probe venv with nothing to add.
+        run: |
+          /tmp/probe/bin/papeete-actor-synchronous-messaging lint-card \
+            "$(/tmp/probe/bin/python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
+
+      - name: the gate must run
+        # A gate that cannot fail is not a gate. Lint a deliberately non-conformant sidecar with
+        # the INSTALLED wheel and require a non-zero exit.
+        run: |
+          if /tmp/probe/bin/foundry-implementation-actor lint tests/fixtures/broken; then
+            echo "::error::lint accepted a non-conformant sidecar — the gate is not running"
+            exit 1
+          fi
+          echo "the gate refused a non-conformant sidecar, as it should"
+
+      - name: grounding renders a CLAUDE.md whose imports resolve
+        # The property the whole design rests on: an @-import naming a file that is not there is a
+        # session grounded in nothing, and it looks identical to one grounded correctly.
+        run: /tmp/probe/bin/python scripts/probe_grounding.py examples/ACME.PARTS.CAP.SUP.007.WID-implementation
+
+  # ── the other half of what this package ships ─────────────────────────────────────────────────
+  #
+  # ADR-FIA-0005: a use is a sidecar, and the image is what turns one into a running actor. The
+  # job above proves the WHEEL works. This one proves the claim a consumer actually depends on —
+  # that a folder containing one YAML file builds into an actor that boots and answers its doors.
+  # Nothing here reaches a registry: the image is built, run and thrown away in the runner.
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: build the wheel this image will carry
+        # The image installs the wheel from dist/ rather than from PyPI, so that an image tagged
+        # <version> cannot contain some other build of <version> — see docker/Dockerfile.
+        run: uv build
+
+      - name: the base image
+        run: docker build -f docker/Dockerfile -t foundry-implementation-actor:ci .
+
+      - name: the image and the wheel are one release
+        # Two artifacts, one version. An image whose wheel says something else is the failure this
+        # arrangement creates, so it is the one CI asserts.
+        run: |
+          wheel="$(ls dist/*.whl | sed -E 's/.*-([0-9][^-]*)-py3.*/\1/')"
+          in_image="$(docker run --rm --entrypoint python foundry-implementation-actor:ci \
+            -c 'from foundry_implementation_actor import version; print(version())')"
+          echo "wheel=$wheel image=$in_image"
+          [ "$wheel" = "$in_image" ] || { echo "::error::image carries $in_image, wheel is $wheel"; exit 1; }
+
+      - name: a use is a sidecar
+        # The example folder holds exactly one file besides its Dockerfile. If this builds, the
+        # claim in the README is true of a real folder rather than of prose.
+        run: |
+          test "$(ls examples/ACME.PARTS.CAP.SUP.007.WID-implementation | grep -cv '^Dockerfile$')" = "1"
+          docker build --build-arg ACTOR_IMAGE=foundry-implementation-actor:ci \
+            -t use:ci examples/ACME.PARTS.CAP.SUP.007.WID-implementation
+
+      - name: the rendered cards are what a caller is validated against
+        # Rendering is the construction that replaces the hand copy conformance.check was built to
+        # police. Assert it inside the image, against the cards the image actually runs.
+        run: |
+          docker run --rm use:ci foundry-implementation-actor lint /actor
+
+      - name: it boots, and answers the doors its cards declare
+        # The credentials are deliberately junk. The engine refuses to construct without a
+        # GITHUB_TOKEN — which is itself worth having, and is why they are set rather than omitted
+        # — and no door is actually exercised here: a 400 means routed and refused the payload, a
+        # 404 would mean the route was never built.
+        run: |
+          docker run -d --name smoke -p 18080:8080 \
+            -e GITHUB_TOKEN=ci -e CLAUDE_CODE_OAUTH_TOKEN=ci use:ci
+          for _ in $(seq 1 30); do
+            curl -fsS -m 2 http://localhost:18080/health >/dev/null 2>&1 && break
+            sleep 1
+          done
+          curl -fsS -m 5 http://localhost:18080/health | grep -q ok
+          for door in implement-task assess-task; do
+            code="$(curl -sS -o /dev/null -w '%{http_code}' -m 5 -X POST \
+              -H 'content-type: application/json' -d '{}' "http://localhost:18080/$door")"
+            [ "$code" = "400" ] || { echo "::error::POST /$door answered $code, expected 400 (routed, bad payload)"; exit 1; }
+          done
+          code="$(curl -sS -o /dev/null -w '%{http_code}' -m 5 -X POST \
+            -H 'content-type: application/json' -d '{}' http://localhost:18080/no-such-door)"
+          [ "$code" = "404" ] || { echo "::error::an undeclared door answered $code, expected 404"; exit 1; }
+          docker logs smoke | grep -q actor-started
+          docker rm -f smoke

foundry_implementation_actor-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,106 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+# PyPI Trusted Publishing (OIDC) — no token is stored anywhere. The one-time setup is a pending
+# publisher on pypi.org naming this repo and this workflow; after the first release it becomes a
+# normal publisher. See README.
+permissions:
+  id-token: write   # PyPI Trusted Publishing
+  contents: read
+  packages: write   # the image, to this repo's own container registry
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: build
+        # No fetch step and no external token: the contract is committed here. A release depends
+        # on nothing but this checkout and PyPI.
+        run: uv build
+
+      - name: the wheel must carry its contract
+        run: |
+          uv venv /tmp/probe
+          uv pip install --python /tmp/probe/bin/python -q dist/*.whl
+          /tmp/probe/bin/foundry-implementation-actor lint examples/ACME.PARTS.CAP.SUP.007.WID-implementation
+
+      - name: the wheel must carry the actor's own cards
+        # Same reason as the line above, for the other half of what this package ships. The
+        # `-actor` suffix asserts a papeete-actor underneath (ADR-ECO-0022); a wheel published
+        # without its cards makes the name a claim the artifact cannot honour, and a published
+        # version is not something to discover that from.
+        run: |
+          /tmp/probe/bin/papeete-actor-synchronous-messaging lint-card \
+            "$(/tmp/probe/bin/python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
+
+      - name: grounding renders a CLAUDE.md whose imports resolve
+        # BEFORE the upload, not after. A wheel that ships without its schema, or whose grounding
+        # emits an @-import to a file it never wrote, produces sessions grounded in nothing that
+        # look identical to correct ones. That is not something to discover from a published
+        # version.
+        run: /tmp/probe/bin/python scripts/probe_grounding.py examples/ACME.PARTS.CAP.SUP.007.WID-implementation
+
+      - name: publish to PyPI
+        run: uv publish --trusted-publishing always
+
+  # ── the image, from the same tag and the same checkout ────────────────────────────────────────
+  #
+  # TWO ARTIFACTS, ONE RELEASE (ADR-FIA-0005). A use pins an image; an embedder pins a wheel; both
+  # are this package at this version. A tag that produced one and not the other leaves a consumer
+  # unable to take the release at all — so this job builds the wheel again from the same checkout
+  # rather than installing the one just uploaded: the image must not depend on PyPI having already
+  # indexed it, and must not be able to pick up a different build of the same version.
+  #
+  # It runs AFTER the wheel is published, not beside it. A failed upload should not leave an image
+  # published for a version that does not exist on PyPI; the reverse — a wheel with the image still
+  # to come — is recoverable by re-running this job alone.
+  image:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: the version is the tag
+        # The tag is what a consumer writes in a FROM line. A tag that disagrees with
+        # pyproject.toml would publish an image whose own `version()` contradicts its name, which
+        # is exactly the confusion the CI gate above exists to prevent for the wheel.
+        id: version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          declared="$(uv run --quiet python -c             'import tomllib,pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          [ "$tag" = "$declared" ] || { echo "::error::tag $GITHUB_REF_NAME does not match pyproject version $declared"; exit 1; }
+          echo "version=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: build
+        run: uv build
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: the image, tagged and latest
+        run: |
+          image="ghcr.io/${{ github.repository }}"
+          docker build -f docker/Dockerfile \
+            -t "$image:${{ steps.version.outputs.version }}" \
+            -t "$image:latest" .
+          docker push "$image:${{ steps.version.outputs.version }}"
+          docker push "$image:latest"
+
+      - name: a use built on it is still an actor
+        # BEFORE the image is something anyone can pin — the same reason the grounding probe runs
+        # before the upload above. An image that builds but produces a use that does not conform is
+        # not something to discover from a published tag.
+        run: |
+          docker build --build-arg ACTOR_IMAGE=ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }} \
+            -t use:release examples/ACME.PARTS.CAP.SUP.007.WID-implementation
+          docker run --rm use:release foundry-implementation-actor lint /actor

{foundry_implementation_actor-0.2.0 → foundry_implementation_actor-0.5.0}/.gitignore

@@ -3,3 +3,4 @@ dist/
 __pycache__/
 .venv/
 .pytest_cache/
+.serena/

{foundry_implementation_actor-0.2.0 → foundry_implementation_actor-0.5.0}/CLAUDE.md

@@ -29,7 +29,7 @@ There is no separate lint/format command configured in this repo.
 
 ## Architecture
 
-Six modules under `src/foundry_implementation_actor/`:
+Seven modules under `src/foundry_implementation_actor/`:
 
 - **`config.py`** — `CapabilityConfig`. The heart. Loads the sidecar and derives **every**
   rendering of the capability id from two declared fields (`capability`, `source_repo`). Also
@@ -44,6 +44,10 @@ Six modules under `src/foundry_implementation_actor/`:
   opens a pull request.
 - **`correlation.py`** — the two ids and the step vocabulary. Moved **verbatim** from the repo this
   was extracted from; its code below the docstring is byte-identical.
+- **`conformance.py`** — `check(folder)`. Compares a use's cards against the definition's, on
+  the derived wire contract only (door ids, each door's request/completion schema and engine).
+  Prose and `actor.yaml`'s `name:` are deliberately not compared — a use should name its own
+  capability. `lint` runs it beside the sidecar gate.
 - **`cli.py`** — argparse wiring only, no logic of its own.
 
 Beside them, two folders of committed contract, both shipped in the wheel:
@@ -56,6 +60,10 @@ Beside them, two folders of committed contract, both shipped in the wheel:
 
 ## Core invariants that any change must preserve
 
+- **A use's cards are a hand copy, and hand copies drift.** Both folders pass `lint-card`
+  independently, and neither gate looks at the other — so a definition that gains a field leaves
+  every un-updated use linting green and refusing callers at runtime. `conformance.check` is the
+  only thing that catches it. Compare the DERIVED contract, never the prose.
 - **The `-actor` suffix is a claim, and it is checked.** `ADR-ECO-0022`: a package ending in
   `-actor` asserts a `papeete-actor` underneath, and one that ships no conformant card is
   misnamed. `tests/test_cards.py` runs `lint-card` on `cards/` in the suite; CI and the release

{foundry_implementation_actor-0.2.0 → foundry_implementation_actor-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: foundry-implementation-actor
-Version: 0.2.0
+Version: 0.5.0
 Summary: Runs a headless Claude Code implementation session against one capability's own repo — a papeete-actor for one use, with the capability supplied by a sidecar.
 Project-URL: Homepage, https://github.com/papeete-hub/foundry-implementation-actor
 Author-email: Papeete Consulting <yoann.remy@outlook.com>
@@ -16,6 +16,9 @@ Requires-Dist: papeete-version>=0.1.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: papeete-actor-synchronous-messaging-http>=0.4.0; extra == 'serve'
+Requires-Dist: papeete-observability>=0.1.0; extra == 'serve'
 Description-Content-Type: text/markdown
 
 # foundry-implementation-actor
@@ -32,6 +35,10 @@ features *of* the framework (`ADR-ECO-0022`).
 pip install foundry-implementation-actor
 ```
 
+> **New here?** [`examples/`](examples/) walks through a complete, working use of this actor —
+> what the workflow is, what it is for, and how to instantiate one for your own capability. Every
+> command in it runs with no credentials and no network.
+
 ## What it is
 
 The actor's **definition** — its four cards, and the machinery behind them. It carries **no
@@ -45,8 +52,8 @@ capability: ACME.PARTS.CAP.SUP.007.WID
 source_repo: acme-lab/ACME.PARTS.CAP.SUP.007.WID-implementation
 registry_repo: acme-lab/acme-governance
 components:
-  - {name: backend, path: backend/, tests: backend/tests/, dockerfile: backend/deployment/local}
-  - {name: stub,    path: stub/,    tests: stub/tests/,    dockerfile: stub/deployment/local}
+  - {name: backend, path: backend/, dockerfile: backend/deployment/local}
+  - {name: stub,    path: stub/,    dockerfile: stub/deployment/local}
 ground_in:
   - name: business
     answers: the WHAT/WHY — domain vision, business events, ubiquitous language
@@ -60,7 +67,27 @@ ground_in:
     load: on-demand
 ```
 
-and four lines in the consuming entrypoint:
+and, beside it, a four-line Dockerfile:
+
+```dockerfile
+FROM ghcr.io/papeete-hub/foundry-implementation-actor:0.5.0
+RUN pip install --no-cache-dir kpack==2.0.1 kontract==0.1.0   # what this sidecar's ground_in names
+COPY actor-agentic-context.yaml /actor/
+RUN foundry-implementation-actor render-cards /actor && foundry-implementation-actor lint /actor
+```
+
+**That is the whole repository.** No cards, no entrypoint, no Python. The cards are rendered from
+the definition in the image, the entrypoint is `foundry-implementation-actor serve`, and the only
+hand-written line naming anything is the `pip install` of the knowledge tools this capability's own
+`ground_in:` argv happens to name — which is the consumer's fact by design (ADR-FIA-0005).
+
+A second capability instantiates the same actor by writing that sidecar. Nothing here is
+subclassed, hooked, or configured with a strategy object — there is one shape, and it is this one.
+
+### Embedding it instead
+
+A consumer that wants its own base image, or the actor inside a larger process, skips all of the
+above and wires it in four lines:
 
 ```python
 from foundry_implementation_actor import CapabilityConfig, ClaudeCodeEngine, make_implement_task
@@ -71,8 +98,10 @@ actor = Actor.from_card(".", mailbox=mailbox,
                         actions={"implement-task": make_implement_task(config)})
 ```
 
-A second capability instantiates the same actor by writing that file. Nothing here is subclassed,
-hooked, or configured with a strategy object — there is one shape, and it is this one.
+`assess-task` needs no entry here: it is a query with an engine and no handler, so the engine's own
+judgement is the reply. `pip install foundry-implementation-actor` is enough for this; the mailbox
+and the observability backend that `serve` needs live in the `[serve]` extra, so an embedder is not
+handed an HTTP server it did not ask for.
 
 ## The definition, and a use
 
@@ -81,11 +110,14 @@ four cards — who it is, the data it knows, the messages it exchanges, and the
 door it answers — and they ship in the wheel, reachable as `cards_path()`. They name no capability,
 because which capability an instance serves is not part of what the actor *is*.
 
-A **use** of this actor is one capability's own folder: its own copy of those four cards, named for
-the capability it serves, beside the `actor-agentic-context.yaml` that binds it to that capability's
-repository and knowledge base. Today that folder is a static repository, and the copy is made by
-hand. Once an instance can be spawned from a capability id alone, the cards here are what it would
-be rendered from — which is why they live in the wheel rather than in an `examples/` folder.
+A **use** of this actor is one capability's own folder: the `actor-agentic-context.yaml` that binds
+it to that capability's repository and knowledge base, and the four cards named for the capability
+it serves — **rendered from the definition, not copied.** `foundry-implementation-actor
+render-cards` writes them, the image runs it at `docker build` time, and a use's repository
+therefore holds one hand-written YAML file. That is why the cards live in the wheel rather than in
+an `examples/` folder: they are build input, not documentation (ADR-FIA-0005).
+
+They used to be copied by hand, which is why the gate below exists.
 
 The split is what the name asserts. `ADR-ECO-0022` makes the `-actor` suffix an obligation: a
 package ending in `-actor` claims a `papeete-actor` underneath, *"and a `<use>-<tier>-actor` that
@@ -97,11 +129,35 @@ papeete-actor-synchronous-messaging lint-card \
   "$(python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
 ```
 
+A hand copy drifts: both folders pass `lint-card` independently, and neither gate has an opinion
+about the other. `foundry-implementation-actor lint` therefore runs a second check —
+`conformance.check` — comparing the use's cards against the definition's on the **derived wire
+contract**: the set of doors, and each door's `request_schema`, `completion_schema` and `engine`.
+Those derivations already fold in the data dictionary and the message catalog, so a renamed item or
+a changed reference lands in the payload a caller is validated against.
+
+Rendering makes that gate cheap to pass rather than redundant, and both are worth having: a use
+still carrying a hand copy from before 0.5.0, or one pinned to an older image, is exactly the case
+that can be wrong — and a construction that cannot drift is still better than a check that catches
+drift, which is why the rendering exists at all.
+
+Prose is not compared, on purpose: a use *should* name its real capability and its real peers, and
+`actor.yaml`'s `name:` is its own identity and is required to differ.
+
 Because the cards sit under `src/`, `tests/test_portability.py` greps them too — a capability id or
 a knowledge tool name written into the actor's own definition fails the build exactly as it would
 in the code.
 
-## What one request does
+## Two doors
+
+| door | verb | what it does |
+|---|---|---|
+| `implement-task` | request | builds the increment, commits, pushes a branch, publishes one image per touched component |
+| `assess-task` | query | answers whether a proposed acceptance surface can be delivered. Writes nothing |
+
+Both name the same engine. `Actor.judge()` hands it the door id, and it dispatches on that.
+
+### `implement-task`
 
 ```
 clone (full, not --depth 1)
@@ -116,6 +172,42 @@ clone (full, not --depth 1)
 It never opens a pull request. Rendering a verdict and opening one belongs to whichever actor
 orchestrates the pipeline, once its other members have also confirmed.
 
+## The three amigos round
+
+Before any of that, the actor that will black-box test the increment says what it intends to
+assert, and this one answers whether that can be delivered:
+
+```
+orchestration ──▶ testing:        propose the acceptance surface for this task
+              ◀──                 expectations[] — each with a stable id, a statement, a handle
+orchestration ──▶ implementation: assess-task — can you deliver this?
+              ◀──                 feasible + objections[] + commitments[]
+
+  agreed     → the surface goes to implement-task AND test-task, on every attempt
+  disagreed  → orchestration stops and hands the objections back to a human
+```
+
+**Exactly one round, then a person.** No counter-proposal and no negotiation loop: a three-amigos
+meeting converges because a human is in the room, and here the human *is* the tie-breaker. *"The
+task does not determine this"* is a legitimate answer, and it is the most useful one.
+
+`assess-task` is a **query**, not an action — *"a promise to answer, from this actor's own state
+and nothing invented."* It clones read-only, grounds itself exactly as the implement door does, and
+is invoked with `Read,Glob,Grep` and no `Write`, `Edit` or `Bash`. A door that **cannot** write
+beats a door asked not to. It registers no handler either: with an engine and no handler,
+`Actor.receive()` returns the judged dict as the reply, and there is nothing to contain because
+nothing is produced.
+
+What it commits to is a **promise, not a report** — nothing has been built when it answers. That
+distinction is the whole point (`ADR-FIA-0004`): a tester deriving its assertions from what was
+already built can only ever confirm the build. The failure this prevents is real and already in the
+wild — an e2e suite carrying three fixture ids its own comment admits were *"discovered black-box
+against the running container"*, against a task card that never named them.
+
+`acceptance_surface` then rides along as an **optional** field on `implement-task`. Without it the
+door behaves exactly as before; with it, where it is more specific than the definition of done, it
+wins.
+
 ## Grounding is a precondition, not a request
 
 `CLAUDE.md` at the working directory's root is loaded by the `claude` CLI **before the first
@@ -196,11 +288,14 @@ this can be an ordinary Pod.
 ## CLI
 
 ```bash
-foundry-implementation-actor lint .                        # validate the sidecar
+foundry-implementation-actor lint .                        # validate the sidecar and the cards
 foundry-implementation-actor show . --registry reg.example.com   # every derived rendering
+foundry-implementation-actor render-cards .                # write the four cards from the wheel
+foundry-implementation-actor serve .                       # boot it (needs the `serve` extra)
 ```
 
-`lint` is the gate CI runs. A sidecar declaring some other `context:` is read, warned, and not
+`render-cards` and `serve` are what the image runs, and are usable anywhere the wheel is. `lint` is
+the gate CI runs. A sidecar declaring some other `context:` is read, warned, and not
 checked further — UNMIGRATED is not the same as non-conformant, and migrating is the owning pair's
 own act.
 

{foundry_implementation_actor-0.2.0 → foundry_implementation_actor-0.5.0}/README.md

@@ -12,6 +12,10 @@ features *of* the framework (`ADR-ECO-0022`).
 pip install foundry-implementation-actor
 ```
 
+> **New here?** [`examples/`](examples/) walks through a complete, working use of this actor —
+> what the workflow is, what it is for, and how to instantiate one for your own capability. Every
+> command in it runs with no credentials and no network.
+
 ## What it is
 
 The actor's **definition** — its four cards, and the machinery behind them. It carries **no
@@ -25,8 +29,8 @@ capability: ACME.PARTS.CAP.SUP.007.WID
 source_repo: acme-lab/ACME.PARTS.CAP.SUP.007.WID-implementation
 registry_repo: acme-lab/acme-governance
 components:
-  - {name: backend, path: backend/, tests: backend/tests/, dockerfile: backend/deployment/local}
-  - {name: stub,    path: stub/,    tests: stub/tests/,    dockerfile: stub/deployment/local}
+  - {name: backend, path: backend/, dockerfile: backend/deployment/local}
+  - {name: stub,    path: stub/,    dockerfile: stub/deployment/local}
 ground_in:
   - name: business
     answers: the WHAT/WHY — domain vision, business events, ubiquitous language
@@ -40,7 +44,27 @@ ground_in:
     load: on-demand
 ```
 
-and four lines in the consuming entrypoint:
+and, beside it, a four-line Dockerfile:
+
+```dockerfile
+FROM ghcr.io/papeete-hub/foundry-implementation-actor:0.5.0
+RUN pip install --no-cache-dir kpack==2.0.1 kontract==0.1.0   # what this sidecar's ground_in names
+COPY actor-agentic-context.yaml /actor/
+RUN foundry-implementation-actor render-cards /actor && foundry-implementation-actor lint /actor
+```
+
+**That is the whole repository.** No cards, no entrypoint, no Python. The cards are rendered from
+the definition in the image, the entrypoint is `foundry-implementation-actor serve`, and the only
+hand-written line naming anything is the `pip install` of the knowledge tools this capability's own
+`ground_in:` argv happens to name — which is the consumer's fact by design (ADR-FIA-0005).
+
+A second capability instantiates the same actor by writing that sidecar. Nothing here is
+subclassed, hooked, or configured with a strategy object — there is one shape, and it is this one.
+
+### Embedding it instead
+
+A consumer that wants its own base image, or the actor inside a larger process, skips all of the
+above and wires it in four lines:
 
 ```python
 from foundry_implementation_actor import CapabilityConfig, ClaudeCodeEngine, make_implement_task
@@ -51,8 +75,10 @@ actor = Actor.from_card(".", mailbox=mailbox,
                         actions={"implement-task": make_implement_task(config)})
 ```
 
-A second capability instantiates the same actor by writing that file. Nothing here is subclassed,
-hooked, or configured with a strategy object — there is one shape, and it is this one.
+`assess-task` needs no entry here: it is a query with an engine and no handler, so the engine's own
+judgement is the reply. `pip install foundry-implementation-actor` is enough for this; the mailbox
+and the observability backend that `serve` needs live in the `[serve]` extra, so an embedder is not
+handed an HTTP server it did not ask for.
 
 ## The definition, and a use
 
@@ -61,11 +87,14 @@ four cards — who it is, the data it knows, the messages it exchanges, and the
 door it answers — and they ship in the wheel, reachable as `cards_path()`. They name no capability,
 because which capability an instance serves is not part of what the actor *is*.
 
-A **use** of this actor is one capability's own folder: its own copy of those four cards, named for
-the capability it serves, beside the `actor-agentic-context.yaml` that binds it to that capability's
-repository and knowledge base. Today that folder is a static repository, and the copy is made by
-hand. Once an instance can be spawned from a capability id alone, the cards here are what it would
-be rendered from — which is why they live in the wheel rather than in an `examples/` folder.
+A **use** of this actor is one capability's own folder: the `actor-agentic-context.yaml` that binds
+it to that capability's repository and knowledge base, and the four cards named for the capability
+it serves — **rendered from the definition, not copied.** `foundry-implementation-actor
+render-cards` writes them, the image runs it at `docker build` time, and a use's repository
+therefore holds one hand-written YAML file. That is why the cards live in the wheel rather than in
+an `examples/` folder: they are build input, not documentation (ADR-FIA-0005).
+
+They used to be copied by hand, which is why the gate below exists.
 
 The split is what the name asserts. `ADR-ECO-0022` makes the `-actor` suffix an obligation: a
 package ending in `-actor` claims a `papeete-actor` underneath, *"and a `<use>-<tier>-actor` that
@@ -77,11 +106,35 @@ papeete-actor-synchronous-messaging lint-card \
   "$(python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
 ```
 
+A hand copy drifts: both folders pass `lint-card` independently, and neither gate has an opinion
+about the other. `foundry-implementation-actor lint` therefore runs a second check —
+`conformance.check` — comparing the use's cards against the definition's on the **derived wire
+contract**: the set of doors, and each door's `request_schema`, `completion_schema` and `engine`.
+Those derivations already fold in the data dictionary and the message catalog, so a renamed item or
+a changed reference lands in the payload a caller is validated against.
+
+Rendering makes that gate cheap to pass rather than redundant, and both are worth having: a use
+still carrying a hand copy from before 0.5.0, or one pinned to an older image, is exactly the case
+that can be wrong — and a construction that cannot drift is still better than a check that catches
+drift, which is why the rendering exists at all.
+
+Prose is not compared, on purpose: a use *should* name its real capability and its real peers, and
+`actor.yaml`'s `name:` is its own identity and is required to differ.
+
 Because the cards sit under `src/`, `tests/test_portability.py` greps them too — a capability id or
 a knowledge tool name written into the actor's own definition fails the build exactly as it would
 in the code.
 
-## What one request does
+## Two doors
+
+| door | verb | what it does |
+|---|---|---|
+| `implement-task` | request | builds the increment, commits, pushes a branch, publishes one image per touched component |
+| `assess-task` | query | answers whether a proposed acceptance surface can be delivered. Writes nothing |
+
+Both name the same engine. `Actor.judge()` hands it the door id, and it dispatches on that.
+
+### `implement-task`
 
 ```
 clone (full, not --depth 1)
@@ -96,6 +149,42 @@ clone (full, not --depth 1)
 It never opens a pull request. Rendering a verdict and opening one belongs to whichever actor
 orchestrates the pipeline, once its other members have also confirmed.
 
+## The three amigos round
+
+Before any of that, the actor that will black-box test the increment says what it intends to
+assert, and this one answers whether that can be delivered:
+
+```
+orchestration ──▶ testing:        propose the acceptance surface for this task
+              ◀──                 expectations[] — each with a stable id, a statement, a handle
+orchestration ──▶ implementation: assess-task — can you deliver this?
+              ◀──                 feasible + objections[] + commitments[]
+
+  agreed     → the surface goes to implement-task AND test-task, on every attempt
+  disagreed  → orchestration stops and hands the objections back to a human
+```
+
+**Exactly one round, then a person.** No counter-proposal and no negotiation loop: a three-amigos
+meeting converges because a human is in the room, and here the human *is* the tie-breaker. *"The
+task does not determine this"* is a legitimate answer, and it is the most useful one.
+
+`assess-task` is a **query**, not an action — *"a promise to answer, from this actor's own state
+and nothing invented."* It clones read-only, grounds itself exactly as the implement door does, and
+is invoked with `Read,Glob,Grep` and no `Write`, `Edit` or `Bash`. A door that **cannot** write
+beats a door asked not to. It registers no handler either: with an engine and no handler,
+`Actor.receive()` returns the judged dict as the reply, and there is nothing to contain because
+nothing is produced.
+
+What it commits to is a **promise, not a report** — nothing has been built when it answers. That
+distinction is the whole point (`ADR-FIA-0004`): a tester deriving its assertions from what was
+already built can only ever confirm the build. The failure this prevents is real and already in the
+wild — an e2e suite carrying three fixture ids its own comment admits were *"discovered black-box
+against the running container"*, against a task card that never named them.
+
+`acceptance_surface` then rides along as an **optional** field on `implement-task`. Without it the
+door behaves exactly as before; with it, where it is more specific than the definition of done, it
+wins.
+
 ## Grounding is a precondition, not a request
 
 `CLAUDE.md` at the working directory's root is loaded by the `claude` CLI **before the first
@@ -176,11 +265,14 @@ this can be an ordinary Pod.
 ## CLI
 
 ```bash
-foundry-implementation-actor lint .                        # validate the sidecar
+foundry-implementation-actor lint .                        # validate the sidecar and the cards
 foundry-implementation-actor show . --registry reg.example.com   # every derived rendering
+foundry-implementation-actor render-cards .                # write the four cards from the wheel
+foundry-implementation-actor serve .                       # boot it (needs the `serve` extra)
 ```
 
-`lint` is the gate CI runs. A sidecar declaring some other `context:` is read, warned, and not
+`render-cards` and `serve` are what the image runs, and are usable anywhere the wheel is. `lint` is
+the gate CI runs. A sidecar declaring some other `context:` is read, warned, and not
 checked further — UNMIGRATED is not the same as non-conformant, and migrating is the owning pair's
 own act.