foundry-implementation-actor 0.1.0__tar.gz

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

@@ -0,0 +1,48 @@
+name: ci
+on: [push, pull_request]
+
+# NO CREDENTIAL. This pipeline reaches nothing outside its own checkout — no registry, no lab
+# repo, no PyPI. Everything it asserts, it asserts from source and from a wheel it built itself.
+
+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 tests/fixtures/valid
+          /tmp/probe/bin/foundry-implementation-actor show tests/fixtures/valid \
+            --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 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 tests/fixtures/valid

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

@@ -0,0 +1,40 @@
+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
+  contents: read
+
+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 tests/fixtures/valid
+
+      - 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 tests/fixtures/valid
+
+      - name: publish to PyPI
+        run: uv publish --trusted-publishing always

foundry_implementation_actor-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+*.egg-info/
+__pycache__/
+.venv/
+.pytest_cache/

foundry_implementation_actor-0.1.0/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this
+repository.
+
+## What this is
+
+`foundry-implementation-actor` runs a headless Claude Code implementation session against one
+capability's own repo, then commits, pushes and publishes what it produced. It is the **machinery**
+— it carries no capability of its own. The capability arrives in a sidecar
+(`actor-agentic-context.yaml`, contract `foundry-implementation-actor/agentic-context/v1`) that the
+consuming repo writes.
+
+Extracted from one capability's implementation repo, where it sat beside that capability's own
+source. See `adr/ADR-FIA-0001-*.md` and README.md's "Where this came from".
+
+## Commands
+
+```bash
+uv run --extra dev pytest -q                                    # full suite (what CI runs)
+uv run --extra dev pytest -q tests/test_config.py               # one file
+uv run --extra dev pytest -q tests/test_config.py::test_name    # one test
+uv build                                                        # sdist/wheel (hatchling)
+uv run foundry-implementation-actor lint <folder>               # validate a sidecar
+uv run foundry-implementation-actor show <folder> --registry r  # every derived rendering
+```
+
+There is no separate lint/format command configured in this repo.
+
+## Architecture
+
+Six 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
+  carries `lint()` and the `Report` it returns.
+- **`grounding.py`** — runs each `ground_in` entry's `fetch:`, writes the envelope **inside the
+  clone** as Markdown, and renders the `CLAUDE.md` that makes the eager ones enter the session's
+  window before turn one.
+- **`engine.py`** — `ClaudeCodeEngine`. Satisfies the `Engine` port from
+  `papeete-actor-synchronous-messaging`. Clones, branches, grounds, runs `claude --print`, streams
+  and projects every turn to the log. Never commits.
+- **`handler.py`** — `make_implement_task(config)`. Containment, commit, push, publish. Never
+  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.
+- **`cli.py`** — argparse wiring only, no logic of its own.
+
+## Core invariants that any change must preserve
+
+- **No capability literal, ever.** `tests/test_portability.py` greps `src/` for the originating
+  instance's identifiers *and* for any knowledge tool name (`kpack`, `kontract`, …), and fails on
+  either. The tools a capability grounds itself in are the consumer's dependencies. A fourth
+  knowledge source is a `ground_in` entry, never a change here.
+- **The image ref is a three-way contract.** `<registry>/<capability_path>/<component>:<version>`
+  — peer actors recompute the identical string and parse it back apart. It is `config.image_ref`
+  output or nothing. **Never invent a tag scheme.**
+- **The write boundary is stated once**, as `components[].path`. It used to be declared in the
+  sidecar *and* hardcoded in the enforcing module. Do not reintroduce a second copy.
+- **Component resolution is longest-prefix**, not the path's first segment. The shortcut is correct
+  only while every component root is one segment deep.
+- **The observability record schema is the contract; step names are not.** `{event: "step", step,
+  phase, duration_ms}`, `{event: "event", step, **fields}`, `{event: "result", cost_usd,
+  input_tokens, output_tokens}`, plus `correlation_id`/`task_id` as structured metadata. Rename a
+  step freely; do not change a record's shape.
+- **Every emitted log line is budgeted to 64 KB.** Loki rejects an oversized line outright rather
+  than truncating it, so one large `Read` would silently delete exactly the turn worth reading.
+- **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.
+- **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.
+
+## Scope discipline
+
+Generic across **capabilities**, not across actor *kinds*. No hooks, no base classes, no strategy
+objects for a hypothetical second consumer. If a change would only make sense for an actor that
+does not exist yet, it does not belong here.
+
+Design rationale lives in `adr/`. Add a new ADR (copy `adr/template.md`) for any decision of
+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.

foundry_implementation_actor-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: foundry-implementation-actor
+Version: 0.1.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>
+License-Expression: MIT
+Keywords: actor-model,agentic,capability,claude-code,papeete
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: papeete-actor-synchronous-messaging>=0.2.1
+Requires-Dist: papeete-version>=0.1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# foundry-implementation-actor
+
+Runs a headless [Claude Code](https://claude.com/claude-code) implementation session against one
+capability's own repository, then commits, pushes and publishes what it produced — inside a write
+boundary the actor enforces rather than requests.
+
+An **actor, for one use**, with a [`papeete-actor`](https://github.com/papeete-hub/papeete-actor)
+underneath. The `-actor` suffix is that claim; `papeete-actor-*` names, by contrast, are transverse
+features *of* the framework (`ADR-ECO-0022`).
+
+```bash
+pip install foundry-implementation-actor
+```
+
+## What it is
+
+The machinery. It carries **no capability of its own** — the capability it serves arrives in a
+sidecar the consuming repo writes:
+
+```yaml
+# actor-agentic-context.yaml
+context: foundry-implementation-actor/agentic-context/v1
+engine: claude-code
+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}
+ground_in:
+  - name: business
+    answers: the WHAT/WHY — domain vision, business events, ubiquitous language
+    fetch: [kpack, pack, "{capability}", --deep, --compact, --registry-repo, "{registry_repo}"]
+    into: .foundry/business.md
+    load: eager
+  - name: process
+    answers: the HOW — aggregates, commands, policies, read-models, bus, api, JSON schemas
+    fetch: [kontract, fetch, "{capability}", --compact, --registry-repo, "{registry_repo}"]
+    into: .foundry/process.md
+    load: on-demand
+```
+
+and four lines in the consuming entrypoint:
+
+```python
+from foundry_implementation_actor import CapabilityConfig, ClaudeCodeEngine, make_implement_task
+
+config = CapabilityConfig.load(".")
+actor = Actor.from_card(".", mailbox=mailbox,
+                        engines={config.engine: ClaudeCodeEngine(config)},
+                        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.
+
+## What one request does
+
+```
+clone (full, not --depth 1)
+  → checkout impl/TASK-NNN
+  → run every ground_in fetch, write it into the clone, render CLAUDE.md
+  → claude --print --output-format stream-json --permission-mode acceptEdits
+  → git add <each component root>; refuse anything staged outside them
+  → commit as the actor, push the branch
+  → buildctl build + push one image per touched component
+```
+
+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.
+
+## Grounding is a precondition, not a request
+
+`CLAUDE.md` at the working directory's root is loaded by the `claude` CLI **before the first
+turn**, and its `@relative/path.md` imports resolve eagerly at the same moment. Verified live in
+this actor's exact invocation shape: a question only the fetched context could answer came back in
+`num_turns: 1` with zero tool calls.
+
+So the envelopes are written **inside the clone** and named from a generated `CLAUDE.md`. The
+earlier arrangement — fetch into a sibling tempdir, then ask the session in prose to "read it
+before you start" — was not broken, it was *advisory*: whether the context entered the window was
+the model's choice, re-made every session, and a session that skipped it looked exactly like one
+that had read it. An `@`-import resolves relative to the file containing it, so the sibling-tempdir
+arrangement could not have been fixed by writing a better prompt.
+
+If the repo commits its own `CLAUDE.md`, the generated block is **appended**, never substituted.
+
+### The two tiers
+
+| `load:` | cost | when |
+|---|---|---|
+| `eager` | its full token weight, every session, unconditionally | the session cannot do the work without it |
+| `on-demand` | one line — its `answers:` and its path | useful sometimes; the session opens it if the task needs it |
+
+Choose from a measurement of the envelope, not from taste. One such read has already been recorded
+as putting *"40 kB of JSON on screen"*.
+
+## One capability id, eight renderings, zero literals
+
+Every identifier is derived from `capability` and `source_repo`. `foundry-implementation-actor
+show` prints the table for a given sidecar:
+
+| rendering | from |
+|---|---|
+| `ACME.PARTS.CAP.SUP.007.WID` | `capability` |
+| `acme-lab/ACME.PARTS.CAP.SUP.007.WID-implementation` | `source_repo` |
+| `acme.parts/sup.007.wid` | the id, split at its `CAP` segment |
+| `acme.parts.cap.sup.007.wid-backend` | the image name `papeete-version` versions |
+| `acme-parts-cap-sup-007-wid-implementation-TASK-042-` | the clone's tempdir prefix |
+| `ACME.PARTS.CAP.SUP.007.WID-implementation` | git `user.name` |
+| `acme-parts-cap-sup-007-wid-implementation@users.noreply.github.com` | git `user.email` |
+| `<registry>/acme.parts/sup.007.wid/<component>:<version>` | the published image ref |
+
+**The image ref is a three-way contract.** Peer actors recompute the identical string and parse it
+back apart, so it is derivation output or nothing. Never invent a tag scheme.
+
+## The write boundary is stated once
+
+`components[].path` — and nothing else. It used to be declared in the sidecar *and* hardcoded in
+the module that actually enforces containment, which is how a boundary comes to be stated twice
+and eventually stated differently.
+
+Containment is `git add <each root>`, never `-A` and never a bare `.`, then an assertion that every
+staged path starts with one of them. A staged path outside is **refused**, the index reset, and the
+door answers a refusal. The session's own prompt only asks for the boundary; this is what holds it.
+
+Which component a staged path belongs to is resolved by **longest declared prefix**, not by taking
+the path's first segment — that shortcut is correct only while every root is one segment deep, and
+reports the wrong component the day one of them is `src/gateway/`.
+
+## Credentials
+
+Two, both passed at run time, never baked into an image:
+
+| variable | what for |
+|---|---|
+| `GITHUB_TOKEN` | fine-grained PAT: `contents:write` on `source_repo`, read-only `contents` on whatever the `ground_in` fetches resolve through |
+| `CLAUDE_CODE_OAUTH_TOKEN` | from `claude setup-token` on a machine with a browser, tied to a Pro/Max/Team/Enterprise subscription |
+
+> **Do not also set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`.** In `claude -p`
+> non-interactive mode an API key present in the environment is ALWAYS preferred over
+> `CLAUDE_CODE_OAUTH_TOKEN`, silently routing every session through metered billing. There is no
+> warning and no visible difference in the transcript; the only symptom is the bill.
+
+Publishing additionally needs `IMAGE_REGISTRY` and `BUILDKIT_HOST`. There is no Docker daemon and
+no docker socket anywhere in this design — `buildctl` is a client, which is why an actor running
+this can be an ordinary Pod.
+
+## CLI
+
+```bash
+foundry-implementation-actor lint .                        # validate the sidecar
+foundry-implementation-actor show . --registry reg.example.com   # every derived rendering
+```
+
+`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.
+
+## Observability
+
+One JSON object per step, so a dashboard reads them with the same `| json` it uses for the session
+transcript and tells them apart by `event`:
+
+```
+{level, event: "step",   step, phase: start|ok|failed, duration_ms, error}
+{level, event: "event",  step, **fields}
+{level, event: "result", cost_usd, input_tokens, output_tokens}
+correlation_id, task_id                                    # structured metadata
+```
+
+**That schema is the contract; the step names are not.** Step names may be renamed freely — a
+drill-down discovers them. `correlation_id` is the W3C trace id the caller propagated, not a second
+identifier invented here, so it pastes straight from Loki into Tempo.
+
+Every emitted line is budgeted to 64 KB. Loki's `max_line_size` is 256 KB with
+`max_line_size_truncate: false` — an oversized line is **rejected outright**, not trimmed, so one
+large `Read` would silently delete exactly the turn worth reading while leaving the rest intact.
+
+## Where this came from
+
+Extracted from one capability's own implementation actor, where 891 lines of this machinery sat
+beside the business capability's source. Both files that moved said so themselves: the engine's
+docstring called extraction *"a near-mechanical move"*, and the sidecar's header said it was kept
+structural *"specifically so extracting this into a real published package later (once proven) is a
+move, not a rewrite."*
+
+`adr/` records the decisions. Design rationale belongs there, not in commit messages.
+
+## Development
+
+```bash
+uv run --extra dev pytest -q     # what CI runs
+uv build
+```
+
+There is no separate lint/format command configured in this repo.

foundry_implementation_actor-0.1.0/README.md

@@ -0,0 +1,197 @@
+# foundry-implementation-actor
+
+Runs a headless [Claude Code](https://claude.com/claude-code) implementation session against one
+capability's own repository, then commits, pushes and publishes what it produced — inside a write
+boundary the actor enforces rather than requests.
+
+An **actor, for one use**, with a [`papeete-actor`](https://github.com/papeete-hub/papeete-actor)
+underneath. The `-actor` suffix is that claim; `papeete-actor-*` names, by contrast, are transverse
+features *of* the framework (`ADR-ECO-0022`).
+
+```bash
+pip install foundry-implementation-actor
+```
+
+## What it is
+
+The machinery. It carries **no capability of its own** — the capability it serves arrives in a
+sidecar the consuming repo writes:
+
+```yaml
+# actor-agentic-context.yaml
+context: foundry-implementation-actor/agentic-context/v1
+engine: claude-code
+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}
+ground_in:
+  - name: business
+    answers: the WHAT/WHY — domain vision, business events, ubiquitous language
+    fetch: [kpack, pack, "{capability}", --deep, --compact, --registry-repo, "{registry_repo}"]
+    into: .foundry/business.md
+    load: eager
+  - name: process
+    answers: the HOW — aggregates, commands, policies, read-models, bus, api, JSON schemas
+    fetch: [kontract, fetch, "{capability}", --compact, --registry-repo, "{registry_repo}"]
+    into: .foundry/process.md
+    load: on-demand
+```
+
+and four lines in the consuming entrypoint:
+
+```python
+from foundry_implementation_actor import CapabilityConfig, ClaudeCodeEngine, make_implement_task
+
+config = CapabilityConfig.load(".")
+actor = Actor.from_card(".", mailbox=mailbox,
+                        engines={config.engine: ClaudeCodeEngine(config)},
+                        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.
+
+## What one request does
+
+```
+clone (full, not --depth 1)
+  → checkout impl/TASK-NNN
+  → run every ground_in fetch, write it into the clone, render CLAUDE.md
+  → claude --print --output-format stream-json --permission-mode acceptEdits
+  → git add <each component root>; refuse anything staged outside them
+  → commit as the actor, push the branch
+  → buildctl build + push one image per touched component
+```
+
+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.
+
+## Grounding is a precondition, not a request
+
+`CLAUDE.md` at the working directory's root is loaded by the `claude` CLI **before the first
+turn**, and its `@relative/path.md` imports resolve eagerly at the same moment. Verified live in
+this actor's exact invocation shape: a question only the fetched context could answer came back in
+`num_turns: 1` with zero tool calls.
+
+So the envelopes are written **inside the clone** and named from a generated `CLAUDE.md`. The
+earlier arrangement — fetch into a sibling tempdir, then ask the session in prose to "read it
+before you start" — was not broken, it was *advisory*: whether the context entered the window was
+the model's choice, re-made every session, and a session that skipped it looked exactly like one
+that had read it. An `@`-import resolves relative to the file containing it, so the sibling-tempdir
+arrangement could not have been fixed by writing a better prompt.
+
+If the repo commits its own `CLAUDE.md`, the generated block is **appended**, never substituted.
+
+### The two tiers
+
+| `load:` | cost | when |
+|---|---|---|
+| `eager` | its full token weight, every session, unconditionally | the session cannot do the work without it |
+| `on-demand` | one line — its `answers:` and its path | useful sometimes; the session opens it if the task needs it |
+
+Choose from a measurement of the envelope, not from taste. One such read has already been recorded
+as putting *"40 kB of JSON on screen"*.
+
+## One capability id, eight renderings, zero literals
+
+Every identifier is derived from `capability` and `source_repo`. `foundry-implementation-actor
+show` prints the table for a given sidecar:
+
+| rendering | from |
+|---|---|
+| `ACME.PARTS.CAP.SUP.007.WID` | `capability` |
+| `acme-lab/ACME.PARTS.CAP.SUP.007.WID-implementation` | `source_repo` |
+| `acme.parts/sup.007.wid` | the id, split at its `CAP` segment |
+| `acme.parts.cap.sup.007.wid-backend` | the image name `papeete-version` versions |
+| `acme-parts-cap-sup-007-wid-implementation-TASK-042-` | the clone's tempdir prefix |
+| `ACME.PARTS.CAP.SUP.007.WID-implementation` | git `user.name` |
+| `acme-parts-cap-sup-007-wid-implementation@users.noreply.github.com` | git `user.email` |
+| `<registry>/acme.parts/sup.007.wid/<component>:<version>` | the published image ref |
+
+**The image ref is a three-way contract.** Peer actors recompute the identical string and parse it
+back apart, so it is derivation output or nothing. Never invent a tag scheme.
+
+## The write boundary is stated once
+
+`components[].path` — and nothing else. It used to be declared in the sidecar *and* hardcoded in
+the module that actually enforces containment, which is how a boundary comes to be stated twice
+and eventually stated differently.
+
+Containment is `git add <each root>`, never `-A` and never a bare `.`, then an assertion that every
+staged path starts with one of them. A staged path outside is **refused**, the index reset, and the
+door answers a refusal. The session's own prompt only asks for the boundary; this is what holds it.
+
+Which component a staged path belongs to is resolved by **longest declared prefix**, not by taking
+the path's first segment — that shortcut is correct only while every root is one segment deep, and
+reports the wrong component the day one of them is `src/gateway/`.
+
+## Credentials
+
+Two, both passed at run time, never baked into an image:
+
+| variable | what for |
+|---|---|
+| `GITHUB_TOKEN` | fine-grained PAT: `contents:write` on `source_repo`, read-only `contents` on whatever the `ground_in` fetches resolve through |
+| `CLAUDE_CODE_OAUTH_TOKEN` | from `claude setup-token` on a machine with a browser, tied to a Pro/Max/Team/Enterprise subscription |
+
+> **Do not also set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`.** In `claude -p`
+> non-interactive mode an API key present in the environment is ALWAYS preferred over
+> `CLAUDE_CODE_OAUTH_TOKEN`, silently routing every session through metered billing. There is no
+> warning and no visible difference in the transcript; the only symptom is the bill.
+
+Publishing additionally needs `IMAGE_REGISTRY` and `BUILDKIT_HOST`. There is no Docker daemon and
+no docker socket anywhere in this design — `buildctl` is a client, which is why an actor running
+this can be an ordinary Pod.
+
+## CLI
+
+```bash
+foundry-implementation-actor lint .                        # validate the sidecar
+foundry-implementation-actor show . --registry reg.example.com   # every derived rendering
+```
+
+`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.
+
+## Observability
+
+One JSON object per step, so a dashboard reads them with the same `| json` it uses for the session
+transcript and tells them apart by `event`:
+
+```
+{level, event: "step",   step, phase: start|ok|failed, duration_ms, error}
+{level, event: "event",  step, **fields}
+{level, event: "result", cost_usd, input_tokens, output_tokens}
+correlation_id, task_id                                    # structured metadata
+```
+
+**That schema is the contract; the step names are not.** Step names may be renamed freely — a
+drill-down discovers them. `correlation_id` is the W3C trace id the caller propagated, not a second
+identifier invented here, so it pastes straight from Loki into Tempo.
+
+Every emitted line is budgeted to 64 KB. Loki's `max_line_size` is 256 KB with
+`max_line_size_truncate: false` — an oversized line is **rejected outright**, not trimmed, so one
+large `Read` would silently delete exactly the turn worth reading while leaving the rest intact.
+
+## Where this came from
+
+Extracted from one capability's own implementation actor, where 891 lines of this machinery sat
+beside the business capability's source. Both files that moved said so themselves: the engine's
+docstring called extraction *"a near-mechanical move"*, and the sidecar's header said it was kept
+structural *"specifically so extracting this into a real published package later (once proven) is a
+move, not a rewrite."*
+
+`adr/` records the decisions. Design rationale belongs there, not in commit messages.
+
+## Development
+
+```bash
+uv run --extra dev pytest -q     # what CI runs
+uv build
+```
+
+There is no separate lint/format command configured in this repo.