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

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.0}/.github/workflows/ci.yml

@@ -32,6 +32,16 @@ jobs:
             --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.

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.0}/.github/workflows/release.yml

@@ -29,6 +29,15 @@ jobs:
           uv pip install --python /tmp/probe/bin/python -q dist/*.whl
           /tmp/probe/bin/foundry-implementation-actor lint tests/fixtures/valid
 
+      - 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

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

@@ -46,8 +46,20 @@ Six modules under `src/foundry_implementation_actor/`:
   was extracted from; its code below the docstring is byte-identical.
 - **`cli.py`** — argparse wiring only, no logic of its own.
 
+Beside them, two folders of committed contract, both shipped in the wheel:
+
+- **`schemas/agentic-context.schema.yaml`** — the sidecar contract this package owns, which
+  `lint` checks a use against.
+- **`cards/`** — the actor's own four cards: what this actor IS, as opposed to which capability a
+  use of it serves. `cards_path()` returns the folder. They name no capability, and they are what
+  a spawned instance would be rendered from once a use is not a static repository.
+
 ## Core invariants that any change must preserve
 
+- **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
+  workflow run it again against the built wheel, so the cards cannot silently stop shipping.
 - **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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: foundry-implementation-actor
-Version: 0.1.0
+Version: 0.2.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>
@@ -34,8 +34,8 @@ 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:
+The actor's **definition** — its four cards, and the machinery behind them. It carries **no
+capability of its own**: the capability it serves arrives in a sidecar the consuming repo writes:
 
 ```yaml
 # actor-agentic-context.yaml
@@ -74,6 +74,33 @@ actor = Actor.from_card(".", mailbox=mailbox,
 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.
 
+## The definition, and a use
+
+This package is where the actor is **defined**. `src/foundry_implementation_actor/cards/` holds its
+four cards — who it is, the data it knows, the messages it exchanges, and the one `implement-task`
+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.
+
+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
+ships no conformant card is misnamed, not merely unusual."* `tests/test_cards.py` runs that check
+in the suite, and CI runs it again against the built wheel:
+
+```bash
+papeete-actor-synchronous-messaging lint-card \
+  "$(python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
+```
+
+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
 
 ```

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

@@ -14,8 +14,8 @@ 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:
+The actor's **definition** — its four cards, and the machinery behind them. It carries **no
+capability of its own**: the capability it serves arrives in a sidecar the consuming repo writes:
 
 ```yaml
 # actor-agentic-context.yaml
@@ -54,6 +54,33 @@ actor = Actor.from_card(".", mailbox=mailbox,
 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.
 
+## The definition, and a use
+
+This package is where the actor is **defined**. `src/foundry_implementation_actor/cards/` holds its
+four cards — who it is, the data it knows, the messages it exchanges, and the one `implement-task`
+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.
+
+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
+ships no conformant card is misnamed, not merely unusual."* `tests/test_cards.py` runs that check
+in the suite, and CI runs it again against the built wheel:
+
+```bash
+papeete-actor-synchronous-messaging lint-card \
+  "$(python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
+```
+
+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
 
 ```

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "foundry-implementation-actor"
-version = "0.1.0"
+version = "0.2.0"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.11"

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.0}/src/foundry_implementation_actor/__init__.py

@@ -18,7 +18,8 @@ Wiring one up is four lines:
 `correlation` is exported too — an entrypoint installs its filter on the root logger's handlers
 after configuring observability, so every record the process emits carries this request's ids.
 """
-from .config import CapabilityConfig, Component, ConfigError, Grounding, Report, lint
+from .config import (CapabilityConfig, Component, ConfigError, Grounding, Report,
+                     cards_path, lint)
 from .engine import ClaudeCodeEngine
 from .handler import HandlerError, make_implement_task
 from . import correlation, grounding
@@ -31,6 +32,7 @@ __all__ = [
     "Grounding",
     "HandlerError",
     "Report",
+    "cards_path",
     "correlation",
     "grounding",
     "lint",

foundry_implementation_actor-0.2.0/src/foundry_implementation_actor/cards/actor-data.yaml

@@ -0,0 +1,38 @@
+# WHAT DATA EXISTS. `papeete-actor-data/v0`, owned by `papeete-actor-message` — a named, minimally
+# typed dictionary. Every field here belongs to the ACTOR, not to any capability: a task id, the
+# caller's statement of the task, and what came back. Nothing names a capability, a component or a
+# knowledge tool, because none of those are known until a sidecar supplies them.
+data: papeete-actor-data/v0
+items:
+  - name: task_id
+    type: string
+    description: the TASK-NNN card id this actor was asked about (e.g. "TASK-009")
+  - name: title
+    type: string
+    description: the task's short title/summary, supplied by the caller — no card lookup is performed here
+  - name: context
+    type: string
+    description: free-text elaboration beyond the title — background, constraints, links; optional
+  - name: definition_of_done
+    type: list
+    description: the acceptance criteria this task must satisfy, as the caller states them
+  - name: remediation_context
+    type: string
+    description: >-
+      on a retry, the prior attempt's failing test criteria — what the implementing session should
+      fix this time; optional, absent on a first attempt
+  - name: accepted
+    type: boolean
+    description: whether the implement-task request was accepted, pushed, and its images published
+  - name: because
+    type: string
+    description: why a request was refused (containment violation, nothing staged, ...)
+  - name: branch
+    type: string
+    description: the branch the implementation was pushed to (impl/TASK-NNN)
+  - name: images
+    type: list
+    description: >-
+      the full name:version ref of each touched component's published image (e.g.
+      "acme.parts.cap.sup.007.wid-backend:0.1.0-TASK-011-a1b2c3d"), by convention — no other actor
+      is ever told these tags explicitly

foundry_implementation_actor-0.2.0/src/foundry_implementation_actor/cards/actor-message.yaml

@@ -0,0 +1,17 @@
+# WHAT MESSAGES EXIST. `papeete-actor-message/v1`, owned by `papeete-actor-message` — named
+# messages, each a pure regrouping of references into the data dictionary, under an intent.
+# Wire-agnostic by that package's own design: WHAT a message is, never HOW it is carried.
+message: papeete-actor-message/v1
+messages:
+  - name: implement-task-cmd
+    intent: ask this actor to implement a TASK-NNN card for the capability it serves
+    references: [task_id, title, definition_of_done, context, remediation_context]
+    optional: [context, remediation_context]
+
+  - name: task-implemented-result
+    intent: report that the task was implemented, pushed, and its touched components' images published
+    references: [accepted, branch, images]
+
+  - name: task-refused-result
+    intent: report that the task was not implemented, and why
+    references: [accepted, because]

foundry_implementation_actor-0.2.0/src/foundry_implementation_actor/cards/actor-synchronous-messaging.yaml

@@ -0,0 +1,21 @@
+# THE DOORS. `synchronous-messaging-doors/v1` — one non-deterministic door, and no queries.
+#
+# `engine: claude-code` is this actor kind's declared engine. A use's sidecar repeats it in its own
+# `engine:` field, and the entrypoint registers the engine under exactly that key — so a use whose
+# sidecar names a different engine is caught by its own card rather than at the first request.
+manifest: synchronous-messaging-doors/v1
+actions:
+  - id: implement-task
+    means: >-
+      the door for "implement TASK-NNN for the capability I serve". Send it here with the task id,
+      title, definition of done, and (optionally) context and remediation_context — the caller
+      supplies everything, no task card is looked up here. I clone my capability's repository into
+      my own private copy, ground myself in that capability's own standing context, judge how to
+      implement the task (writing only under whichever of my declared components it touches), then
+      commit and push to impl/TASK-NNN, and build each touched component's image in the cluster's
+      shared buildkit and push it to the registry, named and versioned by convention. I never open
+      a pull request — an orchestrating actor does, once a testing actor also confirms.
+    completion: whether I accepted, pushed, and published images (with the branch and image refs), or refused, and why.
+    door_schema: implement-task-cmd
+    completion_schema: [task-implemented-result, task-refused-result]
+    engine: claude-code

foundry_implementation_actor-0.2.0/src/foundry_implementation_actor/cards/actor.yaml

@@ -0,0 +1,19 @@
+# WHO. The actor this package defines — `papeete-actor-manifest/v0`, owned by `papeete-actor`.
+#
+# THIS FOLDER IS THE DEFINITION, NOT A USE. The four cards here say what a foundry implementation
+# actor IS: the data it knows, the messages it exchanges, and the one door it answers. They name no
+# capability, because which capability an instance serves is not part of what the actor is — that
+# is `actor-agentic-context.yaml`, supplied per use.
+#
+# One use of this actor is a folder carrying its own copy of these four cards, named for the
+# capability it serves, beside the sidecar that binds it to that capability's knowledge base. Today
+# that folder is a static repository; the cards here are what a spawned instance would be rendered
+# from once it is not.
+manifest: papeete-actor-manifest/v0
+name: foundry-implementation-actor
+description: >-
+  Implements one TASK-NNN card for the business capability its sidecar names. Clones that
+  capability's own repository into a private copy, grounds the session in the capability's own
+  standing context, and writes only under the components the sidecar declares — then commits,
+  pushes a branch, and publishes one image per component the task actually touched. Never opens a
+  pull request: an orchestrating actor does that, once a testing actor also confirms.

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.0}/src/foundry_implementation_actor/config.py

@@ -45,6 +45,7 @@ CONTRACT = "foundry-implementation-actor/agentic-context/v1"
 SIDECAR = "actor-agentic-context.yaml"
 
 _SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "agentic-context.schema.yaml"
+_CARDS_PATH = Path(__file__).resolve().parent / "cards"
 
 # The segment a capability id carries to say "capability". It is dropped from the registry path
 # because the path position already says it — every other token of the id survives, across
@@ -56,6 +57,21 @@ _CAPABILITY_SEGMENT = "cap"
 _PLACEHOLDER = re.compile(r"\{([a-z_]+)\}")
 
 
+def cards_path() -> Path:
+    """The folder holding this actor's own four cards — its definition, shipped in the wheel.
+
+    The cards say what a foundry implementation actor IS: its data dictionary, its message
+    catalog, and the one door it answers. They name no capability, because which capability an
+    instance serves is not part of what the actor is — that is the sidecar, supplied per use.
+
+    A use is today a static folder carrying its own copy of these four, named for the capability
+    it serves. This path is what a spawned instance would be rendered from once it is not, and it
+    is what `papeete-actor-synchronous-messaging lint-card` is pointed at to check that the
+    `-actor` suffix in this package's name is a claim it actually honours (ADR-ECO-0022).
+    """
+    return _CARDS_PATH
+
+
 def load_schema() -> dict:
     """The contract, as committed source inside this package.
 

foundry_implementation_actor-0.2.0/tests/test_cards.py

@@ -0,0 +1,49 @@
+"""The `-actor` suffix, checked rather than asserted.
+
+`ADR-ECO-0022` makes the suffix an obligation: "A package ending in `-actor` asserts a
+`papeete-actor` underneath, which lint-card can check. A future `<use>-<tier>-actor` that ships no
+conformant card is misnamed, not merely unusual."
+
+This file is that check. It runs the same gate `papeete-actor-synchronous-messaging lint-card` runs,
+against the cards this package ships — so the claim in the name is a test, not a sentence in a
+record.
+
+The cards live under `src/`, which means `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.
+"""
+from __future__ import annotations
+
+from papeete_actor_synchronous_messaging import card
+
+from foundry_implementation_actor import cards_path
+
+
+def test_the_package_ships_the_four_cards():
+    """A card folder is four files; `Actor.from_card` opens exactly these and never globs."""
+    folder = cards_path()
+    missing = [name for name in ("actor.yaml", "actor-data.yaml", "actor-message.yaml",
+                                 "actor-synchronous-messaging.yaml")
+               if not (folder / name).exists()]
+    assert not missing, f"the actor's definition is incomplete — missing: {', '.join(missing)}"
+
+
+def test_the_shipped_cards_are_conformant():
+    """The whole of the `-actor` claim: this folder is a papeete-actor, or the name is wrong."""
+    report = card.lint(cards_path())
+    assert not report.errors, ("the cards this package ships are not conformant:\n  "
+                               + "\n  ".join(report.errors))
+
+
+def test_the_door_names_the_engine_a_sidecar_must_declare():
+    """The card's door and a use's sidecar name the same engine key.
+
+    The entrypoint registers the engine under the sidecar's `engine:`, and the door resolves
+    through the card's. They are two statements of one fact, in two repos; this pins the half that
+    lives here so a use's `lint` failure is the only way they can disagree.
+    """
+    loaded = card.load(cards_path())
+    assert set(loaded.actions) == {"implement-task"}, (
+        f"expected the one implement-task door, got {sorted(loaded.actions)}")
+    engines = {offer.engine for offer in loaded.actions.values()}
+    assert engines == {"claude-code"}, f"expected the one claude-code door, got {engines}"

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.0}/uv.lock

@@ -13,7 +13,7 @@ wheels = [
 
 [[package]]
 name = "foundry-implementation-actor"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "papeete-actor-synchronous-messaging" },