foundry-implementation-actor 0.2.1__tar.gz → 0.5.1__tar.gz

foundry_implementation_actor-0.5.1/.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.1/.github/workflows/release.yml

@@ -0,0 +1,210 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+  # A REGISTRY ADDED AFTER A TAG WAS ALREADY CUT. The image job below publishes to two registries,
+  # and the second one was not always there. Running this workflow by hand backfills the image for
+  # a version whose wheel is already on PyPI — without inventing a version number whose only
+  # content is "the last release missed a registry".
+  #
+  # THE TAG IS AN INPUT, NOT THE REF THIS RUNS FROM. GitHub takes the workflow FILE from the ref it
+  # is dispatched on, and the tag needing a backfill is by definition older than the workflow that
+  # can do it — dispatching on that tag would run the very file that lacks this trigger. So run it
+  # from the default branch and name the tag here; the checkout below takes the CONTENT from the
+  # tag, and the version gate still refuses a tag that disagrees with the `pyproject.toml` beside
+  # it.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to publish an image for, e.g. v0.5.0"
+        required: true
+
+# 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:
+    # ONLY ON A TAG PUSH. A manual run exists to backfill an IMAGE (see `on:` above), and PyPI
+    # refuses a version it already holds — so re-uploading is not merely redundant, it fails, and
+    # would take the image job down with it.
+    if: github.event_name == 'push'
+    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
+    # `needs` still orders this after the wheel on a tag push. On a manual backfill `publish` is
+    # skipped, and a skipped dependency skips its dependents too unless `always()` says otherwise —
+    # so the condition has to name both cases rather than relying on `needs` alone.
+    if: always() && (needs.publish.result == 'success' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Empty on a tag push, which is `checkout`'s own default — the ref that triggered the
+          # run. On a manual backfill it is the tag being republished, so every step below reads
+          # that tag's own tree rather than whatever the default branch has moved on to.
+          ref: ${{ inputs.tag }}
+
+      - 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. On a backfill
+        # this compares the named tag against the `pyproject.toml` checked out FROM that tag, so a
+        # typo in the input is refused rather than published under the wrong name.
+        id: version
+        env:
+          TAG: ${{ inputs.tag || github.ref_name }}
+        run: |
+          tag="${TAG#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 $TAG 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
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          # `latest` FOLLOWS THE RELEASE STREAM, NOT A BACKFILL. A manual run exists to give an
+          # already-released version an image in a registry it missed; run against an older tag it
+          # would otherwise drag `latest` backwards onto it, silently, in whichever registry a
+          # consumer happens to pull from. The version tag is the whole point of a backfill —
+          # `latest` already names something newer, and stays there.
+          MOVE_LATEST: ${{ github.event_name == 'push' }}
+        run: |
+          image="ghcr.io/${{ github.repository }}"
+          docker build -f docker/Dockerfile -t "$image:$VERSION" -t "$image:latest" .
+          docker push "$image:$VERSION"
+          if [ "$MOVE_LATEST" = "true" ]; then docker push "$image:latest"; fi
+
+      # ── the product's own registry ────────────────────────────────────────────────────────────
+      #
+      # TWO REGISTRIES, ONE IMAGE. GHCR is where this package publishes; a product that RUNS uses
+      # of it pulls from its own registry, which its cluster already authenticates to and which a
+      # `FROM` line inside that cluster's builder can reach without a second credential. The base
+      # image has to exist in both, because the two are reached by different things: an embedder
+      # writing a Dockerfile reads the README and pins GHCR, while a use built by an in-cluster
+      # builder resolves its `FROM` against the registry that builder has a push token for.
+      #
+      # THE SAME IMAGE, NOT ANOTHER BUILD. `docker tag` re-points the build the step above already
+      # pushed, so both registries hold one digest. Building a second time would let them diverge —
+      # a base-image refresh between two steps of one job is enough — and nothing downstream would
+      # ever notice that `:0.5.0` meant two different things depending on where you pulled it.
+      #
+      # ONE VARIABLE NAMES THE WHOLE TARGET. `vars.PRODUCT_IMAGE` is the full repository path, e.g.
+      # `<name>.azurecr.io/<product>/foundry-implementation-actor`; the login server is its first
+      # segment. This package is generic across capabilities and names no product of its own — the
+      # same rule `tests/test_portability.py` enforces over `src/` — so the product that hosts a
+      # registry names itself in a repository variable rather than in this file.
+      #
+      # UNSET IS A VALID STATE, AND IT SAYS SO. A fork, or this repo before its credentials were
+      # added, publishes to GHCR alone; that is a `::notice`, not a failure. Configured-but-broken
+      # IS a failure — the push below is not best-effort, because an image the product's cluster
+      # cannot pull is the whole reason this block exists.
+      - name: is a product registry configured?
+        id: product
+        env:
+          PRODUCT_IMAGE: ${{ vars.PRODUCT_IMAGE }}
+        run: |
+          if [ -z "$PRODUCT_IMAGE" ]; then
+            echo "::notice::PRODUCT_IMAGE is unset — publishing to GHCR only"
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          case "$PRODUCT_IMAGE" in
+            */*/*) : ;;
+            *) echo "::error::PRODUCT_IMAGE must be <registry>/<path>/<repository>, got $PRODUCT_IMAGE"; exit 1 ;;
+          esac
+          echo "server=${PRODUCT_IMAGE%%/*}" >> "$GITHUB_OUTPUT"
+          echo "configured=true" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/login-action@v3
+        if: steps.product.outputs.configured == 'true'
+        with:
+          registry: ${{ steps.product.outputs.server }}
+          username: ${{ secrets.ACR_PUSH_USERNAME }}
+          password: ${{ secrets.ACR_PUSH_PASSWORD }}
+
+      - name: the same image, in the product's registry
+        if: steps.product.outputs.configured == 'true'
+        env:
+          PRODUCT_IMAGE: ${{ vars.PRODUCT_IMAGE }}
+          VERSION: ${{ steps.version.outputs.version }}
+          MOVE_LATEST: ${{ github.event_name == 'push' }}
+        run: |
+          ghcr="ghcr.io/${{ github.repository }}"
+          docker tag "$ghcr:$VERSION" "$PRODUCT_IMAGE:$VERSION"
+          docker push "$PRODUCT_IMAGE:$VERSION"
+          if [ "$MOVE_LATEST" = "true" ]; then
+            docker tag "$ghcr:latest" "$PRODUCT_IMAGE:latest"
+            docker push "$PRODUCT_IMAGE:latest"
+          fi
+
+      - 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.1 → foundry_implementation_actor-0.5.1}/.gitignore

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

{foundry_implementation_actor-0.2.1 → foundry_implementation_actor-0.5.1}/CLAUDE.md

@@ -88,6 +88,11 @@ Beside them, two folders of committed contract, both shipped in the wheel:
 - **The clone is full, never `--depth 1`.** `papeete_version.compute()` runs `git describe --tags`
   against it and needs the matching tag's commit reachable.
 - **The generated `CLAUDE.md` appends** to one the repo already commits. Never overwrite.
+- **The image is one build in two registries.** GHCR is where this package publishes; a product's
+  own registry is where the in-cluster builder that resolves a use's `FROM` line can actually
+  authenticate (ADR-FIA-0006). `release.yml` `docker tag`s one build into both so they hold one
+  digest — never add a second `docker build`, and never hardcode a registry: the product names
+  itself in `vars.PRODUCT_IMAGE`, the same reason `src/` names no capability.
 - **Never set `ANTHROPIC_API_KEY` in a container running this.** In `claude -p` non-interactive
   mode an API key in the environment is always preferred over `CLAUDE_CODE_OAUTH_TOKEN`, silently
   routing every session through metered billing. There is no warning; the only symptom is the bill.
@@ -104,7 +109,12 @@ similar weight rather than only writing it into code comments.
 ## Releasing
 
 Tag-triggered (`v*`) via `.github/workflows/release.yml`, publishing to PyPI through Trusted
-Publishing (OIDC) — no stored token. The release job builds the wheel, installs it into a throwaway
-venv, and renders a `CLAUDE.md` from a fixture sidecar, asserting its `@`-imports resolve, before
-publishing. `ci.yml` runs the suite plus two gates — *the wheel must carry its contract* and *the
-gate must run* — and reaches nothing outside its own checkout.
+Publishing (OIDC) — no stored token. The image goes to GHCR and, when `vars.PRODUCT_IMAGE` names
+one, to a product's own registry as well (ADR-FIA-0006). The workflow also accepts a manual run
+that takes a tag as an INPUT — dispatched from the default branch, because the file comes from the
+dispatched ref and a tag needing a backfill predates the workflow that can do it — to give an
+already-released version an image in a registry it missed; that run skips PyPI and does not move
+`latest`. The release job builds the wheel, installs it into
+a throwaway venv, and renders a `CLAUDE.md` from a fixture sidecar, asserting its `@`-imports
+resolve, before publishing. `ci.yml` runs the suite plus two gates — *the wheel must carry its
+contract* and *the gate must run* — and reaches nothing outside its own checkout.

{foundry_implementation_actor-0.2.1 → foundry_implementation_actor-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: foundry-implementation-actor
-Version: 0.2.1
+Version: 0.5.1
 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.1
+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,12 +129,17 @@ papeete-actor-synchronous-messaging lint-card \
   "$(python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
 ```
 
-A use's copy is made by hand, so it can drift: 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.
+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.
@@ -111,7 +148,16 @@ Because the cards sit under `src/`, `tests/test_portability.py` greps them too
 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)
@@ -126,6 +172,44 @@ 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 `--tools Read,Glob,Grep`, so `Write`, `Edit` and `Bash` are absent from the session
+rather than merely unapproved (0.5.0 passed only `--allowedTools`, which removes nothing — see
+ADR-FIA-0004's amendment). 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
@@ -206,11 +290,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.
 
@@ -244,6 +331,32 @@ move, not a rewrite."*
 
 `adr/` records the decisions. Design rationale belongs there, not in commit messages.
 
+## Releasing, and which registry to pin
+
+A tag (`v*`) publishes two artifacts at one version — the wheel to PyPI, and the image to **two
+registries** holding the same digest (ADR-FIA-0006):
+
+| Registry | Pin it when |
+|---|---|
+| `ghcr.io/papeete-hub/foundry-implementation-actor` | you are writing a use's Dockerfile yourself, and build it with your own Docker |
+| a product's own registry, `vars.PRODUCT_IMAGE` | the use is built **in-cluster**, by a builder whose one registry credential is that product's |
+
+The second exists because `buildctl` resolves a `FROM` line client-side against the single registry
+credential it was handed — so a use built by the cluster's shared builder can only reach the
+product's own registry, whatever the README says. The push is skipped, with a notice, when
+`vars.PRODUCT_IMAGE` is unset.
+
+To give an already-released version an image in a registry it missed, run the workflow by hand from
+the default branch with the tag as its input — it checks that tag out, and refuses it if it
+disagrees with the `pyproject.toml` beside it:
+
+```bash
+gh workflow run release.yml --ref main -f tag=v0.5.0
+```
+
+That run skips PyPI (which refuses a version it already holds) and does not move `latest` in either
+registry.
+
 ## Development
 
 ```bash