agentforge-framework 0.2.2__tar.gz → 0.2.4__tar.gz

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-framework
-Version: 0.2.2
+Version: 0.2.4
 Summary: A modular framework for coordinating specialized software agents.
 Author: Yash Mhatre
 License-Expression: Apache-2.0
@@ -99,7 +99,10 @@ ADR-0015.
 
 Without `--allow-commands`, the Implementer remains default-deny and the Tester
 reports that it could not run the suite; it never substitutes reading tests and
-claims completion. Security, the Reviewer, and the Architect need no such flag —
+claims completion. That gate is held by the `claude` adapter. The `codex` CLI
+cannot hold it — `codex exec` discards its approval flag — so a denied Run on
+`codex` is refused before it starts rather than run under a guarantee nothing
+enforces (ADR-0007, amended). Security, the Reviewer, and the Architect need no such flag —
 auditing, reviewing, and designing are reading. All six Roles `CONTEXT.md` names
 now run. Plugins have landed, and with them the data-engineering ones: a
 repository whose files import `pyspark` has its Roles told to write DataFrame
@@ -145,7 +148,7 @@ without notice. See
 ```console
 $ pip install agentforge-framework
 $ agentforge --version
-agentforge 0.2.2
+agentforge 0.2.4
 ```
 
 That is the whole of it. The two routes below the naming note are for a machine
@@ -169,7 +172,7 @@ from the [latest release](https://github.com/yashmhatre/AgentForge/releases/late
 and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.2-py3-none-any.whl
+$ pip install agentforge_framework-0.2.4-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:
@@ -200,6 +203,14 @@ What each release contains is in [CHANGELOG.md](CHANGELOG.md).
 
 AgentForge never touches a model API and handles no credentials of its own. Whatever your coding-agent CLI is already authenticated with is what a Run costs.
 
+### Editors and IDEs
+
+AgentForge is a terminal tool. It runs fine from an IDE's terminal, but the IDE is not a Provider and its assistant is not one either.
+
+**Antigravity IDE cannot be a Provider** ([#101](https://github.com/yashmhatre/AgentForge/issues/101)). Checked by running it, so nobody has to derive it again: `antigravity-ide chat` accepts a prompt and reads stdin, which is the right shape for the argument vector — but it is a window launcher. Piping a prompt to it returns exit 0 immediately with `Reading from stdin via: …\code-stdin-XXXX` on stdout and nothing else, ever; the answer goes to a GUI session. A Provider adapter has to read the Agent's result off stdout, so there is nothing for `parse_output` to parse. The same is true of any editor CLI of this shape.
+
+**Do not run another agent against a checkout while a Run is going.** A Run commits every change to a file git already tracks, however it got there ([ADR-0015](docs/adr/0015-a-run-commits-what-it-declared.md)) — so a second agent's half-finished edits are committed into the Run's branch and attributed to a Role. Files nothing in the Run claimed are listed in the pull request body ([ADR-0023](docs/adr/0023-a-commit-names-what-nothing-claimed.md)), which makes it visible at Sign-off but does not prevent it. Use a separate clone.
+
 ## Commands
 
 | Command | What it does |
@@ -274,14 +285,33 @@ defaults are Claude `native` and every other Provider `fragment`, and the
 providers:
   claude:
     capability_tier: native
+    # Optional. Overrides the adapter's own tier-to-model table; name only the
+    # tiers you disagree about, and the rest keep the shipped defaults.
+    models:
+      deep: claude-opus-5
   codex:
     capability_tier: fragment
 
+# Optional. A Role's two declared axes: which class of model runs it, and how
+# hard that model thinks. Both default to the table in ADR-0004.
+roles:
+  security:
+    tier: deep
+    effort: max
+
 gates:
   tests:
     suite: pytest
 ```
 
+There is no `roles.<name>.model` key, and naming one is an error rather than a
+line that gets ignored. A Role declares a tier; the Provider maps that tier onto
+a model. A model named per Role does not survive the next CLI release and does
+not port to another Provider, which is what
+[ADR-0004](docs/adr/0004-model-tiers-declared-not-named.md) exists to prevent --
+override `providers.<name>.models.<tier>` if the mapping is what you disagree
+with.
+
 There is no `plugins:` key. Which Plugins answer for a repository is decided per
 Run from the frozen plan's blast radius (ADR-0016), so a repository-level list
 would be inert and misleading -- init prints what it detected instead. The file
@@ -331,10 +361,21 @@ code rather than the verdict about the old code.
 
 Read [`CONTEXT.md`](CONTEXT.md) before writing anything, and [`docs/adr/`](docs/adr/) for the decisions that constrain it.
 
-## Tests
+## Changing AgentForge
+
+Clone it and install that clone editable. Never patch the installed copy.
 
 ```console
+$ git clone https://github.com/yashmhatre/AgentForge.git
+$ cd AgentForge
 $ pip install -e ".[dev]"
+```
+
+Editing `site-packages/agentforge_framework/` appears to work and is the one change nothing will catch: the local install diverges from what ships, so the thing that works is not the thing anybody else gets, and the fix is lost the next time the package is upgraded. If a Run is failing badly enough that patching the install looks like the way forward, that is a bug worth filing — [#101](https://github.com/yashmhatre/AgentForge/issues/101) is what happened the last time somebody reached for it.
+
+## Tests
+
+```console
 $ pytest
 ```
 

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/README.md

@@ -81,7 +81,10 @@ ADR-0015.
 
 Without `--allow-commands`, the Implementer remains default-deny and the Tester
 reports that it could not run the suite; it never substitutes reading tests and
-claims completion. Security, the Reviewer, and the Architect need no such flag —
+claims completion. That gate is held by the `claude` adapter. The `codex` CLI
+cannot hold it — `codex exec` discards its approval flag — so a denied Run on
+`codex` is refused before it starts rather than run under a guarantee nothing
+enforces (ADR-0007, amended). Security, the Reviewer, and the Architect need no such flag —
 auditing, reviewing, and designing are reading. All six Roles `CONTEXT.md` names
 now run. Plugins have landed, and with them the data-engineering ones: a
 repository whose files import `pyspark` has its Roles told to write DataFrame
@@ -127,7 +130,7 @@ without notice. See
 ```console
 $ pip install agentforge-framework
 $ agentforge --version
-agentforge 0.2.2
+agentforge 0.2.4
 ```
 
 That is the whole of it. The two routes below the naming note are for a machine
@@ -151,7 +154,7 @@ from the [latest release](https://github.com/yashmhatre/AgentForge/releases/late
 and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.2-py3-none-any.whl
+$ pip install agentforge_framework-0.2.4-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:
@@ -182,6 +185,14 @@ What each release contains is in [CHANGELOG.md](CHANGELOG.md).
 
 AgentForge never touches a model API and handles no credentials of its own. Whatever your coding-agent CLI is already authenticated with is what a Run costs.
 
+### Editors and IDEs
+
+AgentForge is a terminal tool. It runs fine from an IDE's terminal, but the IDE is not a Provider and its assistant is not one either.
+
+**Antigravity IDE cannot be a Provider** ([#101](https://github.com/yashmhatre/AgentForge/issues/101)). Checked by running it, so nobody has to derive it again: `antigravity-ide chat` accepts a prompt and reads stdin, which is the right shape for the argument vector — but it is a window launcher. Piping a prompt to it returns exit 0 immediately with `Reading from stdin via: …\code-stdin-XXXX` on stdout and nothing else, ever; the answer goes to a GUI session. A Provider adapter has to read the Agent's result off stdout, so there is nothing for `parse_output` to parse. The same is true of any editor CLI of this shape.
+
+**Do not run another agent against a checkout while a Run is going.** A Run commits every change to a file git already tracks, however it got there ([ADR-0015](docs/adr/0015-a-run-commits-what-it-declared.md)) — so a second agent's half-finished edits are committed into the Run's branch and attributed to a Role. Files nothing in the Run claimed are listed in the pull request body ([ADR-0023](docs/adr/0023-a-commit-names-what-nothing-claimed.md)), which makes it visible at Sign-off but does not prevent it. Use a separate clone.
+
 ## Commands
 
 | Command | What it does |
@@ -256,14 +267,33 @@ defaults are Claude `native` and every other Provider `fragment`, and the
 providers:
   claude:
     capability_tier: native
+    # Optional. Overrides the adapter's own tier-to-model table; name only the
+    # tiers you disagree about, and the rest keep the shipped defaults.
+    models:
+      deep: claude-opus-5
   codex:
     capability_tier: fragment
 
+# Optional. A Role's two declared axes: which class of model runs it, and how
+# hard that model thinks. Both default to the table in ADR-0004.
+roles:
+  security:
+    tier: deep
+    effort: max
+
 gates:
   tests:
     suite: pytest
 ```
 
+There is no `roles.<name>.model` key, and naming one is an error rather than a
+line that gets ignored. A Role declares a tier; the Provider maps that tier onto
+a model. A model named per Role does not survive the next CLI release and does
+not port to another Provider, which is what
+[ADR-0004](docs/adr/0004-model-tiers-declared-not-named.md) exists to prevent --
+override `providers.<name>.models.<tier>` if the mapping is what you disagree
+with.
+
 There is no `plugins:` key. Which Plugins answer for a repository is decided per
 Run from the frozen plan's blast radius (ADR-0016), so a repository-level list
 would be inert and misleading -- init prints what it detected instead. The file
@@ -313,10 +343,21 @@ code rather than the verdict about the old code.
 
 Read [`CONTEXT.md`](CONTEXT.md) before writing anything, and [`docs/adr/`](docs/adr/) for the decisions that constrain it.
 
-## Tests
+## Changing AgentForge
+
+Clone it and install that clone editable. Never patch the installed copy.
 
 ```console
+$ git clone https://github.com/yashmhatre/AgentForge.git
+$ cd AgentForge
 $ pip install -e ".[dev]"
+```
+
+Editing `site-packages/agentforge_framework/` appears to work and is the one change nothing will catch: the local install diverges from what ships, so the thing that works is not the thing anybody else gets, and the fix is lost the next time the package is upgraded. If a Run is failing badly enough that patching the install looks like the way forward, that is a bug worth filing — [#101](https://github.com/yashmhatre/AgentForge/issues/101) is what happened the last time somebody reached for it.
+
+## Tests
+
+```console
 $ pytest
 ```
 

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentforge-framework"
-version = "0.2.2"
+version = "0.2.4"
 description = "A modular framework for coordinating specialized software agents."
 readme = "README.md"
 requires-python = ">=3.11"

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/__init__.py

@@ -1,3 +1,3 @@
 """AgentForge — coordination of specialized software agents through reusable workflows."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/agents/__init__.py

@@ -12,7 +12,7 @@ would be the most expensive default in the project.
 
 from __future__ import annotations
 
-from ..core.contracts import ModelTier, Role
+from ..core.contracts import Effort, ModelTier, Role
 from .architect import ARCHITECT, Architect
 from .implementer import IMPLEMENTER, Implementer
 from .orchestrator import ORCHESTRATOR
@@ -53,12 +53,30 @@ RUNNERS: dict[str, type] = {
 KNOWN_TIERS: dict[str, ModelTier] = {
     "orchestrator": ModelTier.DEEP,
     "architect": ModelTier.DEEP,
-    "security": ModelTier.DEEP,
     "reviewer": ModelTier.DEEP,
     "implementer": ModelTier.STANDARD,
+    "security": ModelTier.STANDARD,
     "tester": ModelTier.CHEAP,
 }
 
+#: The second axis, keyed the same way. A tier says which model runs; this says
+#: how hard it thinks, and the two are set independently — see ADR-0004's
+#: 2026-09-03 amendment for why they were ever one thing.
+#:
+#: The Security row is the reason the axes split. It reads `standard` above and
+#: `high` here, which is not a demotion: ADR-0004 bought it `deep` because a
+#: missed finding is silent, and that argument was about reasoning depth. It
+#: keeps the depth — above the Implementer whose work it audits — and stops
+#: buying a frontier model to get it.
+KNOWN_EFFORTS: dict[str, Effort] = {
+    "orchestrator": Effort.HIGH,
+    "architect": Effort.HIGH,
+    "reviewer": Effort.HIGH,
+    "security": Effort.HIGH,
+    "implementer": Effort.MEDIUM,
+    "tester": Effort.MEDIUM,
+}
+
 
 class UnknownRole(LookupError):
     """A Roster names a Role this version of AgentForge cannot run."""
@@ -80,6 +98,7 @@ def resolve_role(name: str) -> Role:
 __all__ = [
     "ARCHITECT",
     "IMPLEMENTER",
+    "KNOWN_EFFORTS",
     "KNOWN_TIERS",
     "ORCHESTRATOR",
     "REVIEWER",

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/agents/architect.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from ..context.prompt import render_context_block
-from ..core.contracts import AgentResult, ContextPack, ModelTier, Plan, Role
+from ..core.contracts import AgentResult, ContextPack, Effort, ModelTier, Plan, Role
 from ..core.plan_format import RESULT_CLOSE, RESULT_OPEN
 from .implementer import render_steps
 
@@ -90,7 +90,12 @@ step and the mismatch in `summary`.\
 """
 
 #: The Architect runs `deep`: a boundary in the wrong place outlives the Run.
-ARCHITECT = Role(name="architect", tier=ModelTier.DEEP, instructions=INSTRUCTIONS)
+ARCHITECT = Role(
+    name="architect",
+    tier=ModelTier.DEEP,
+    effort=Effort.HIGH,
+    instructions=INSTRUCTIONS,
+)
 
 
 def build_prompt(

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/agents/implementer.py

@@ -19,7 +19,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from ..context.prompt import render_context_block
-from ..core.contracts import AgentResult, ContextPack, ModelTier, Plan, Role
+from ..core.contracts import AgentResult, ContextPack, Effort, ModelTier, Plan, Role
 from ..core.plan_format import RESULT_CLOSE, RESULT_OPEN
 
 INSTRUCTIONS = """\
@@ -77,7 +77,12 @@ actually contains. Change no files when you escalate.\
 """
 
 #: The Implementer runs at `standard`: it executes a plan it did not write.
-IMPLEMENTER = Role(name="implementer", tier=ModelTier.STANDARD, instructions=INSTRUCTIONS)
+IMPLEMENTER = Role(
+    name="implementer",
+    tier=ModelTier.STANDARD,
+    effort=Effort.MEDIUM,
+    instructions=INSTRUCTIONS,
+)
 
 
 def render_steps(plan: Plan) -> str:

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/agents/orchestrator.py

@@ -38,6 +38,7 @@ from ..core.contracts import (
     DEFAULT_WORKFLOW,
     AgentResult,
     ContextPack,
+    Effort,
     ModelTier,
     Outcome,
     Plan,
@@ -239,6 +240,7 @@ repository itself uses them, and do not start a glossary during an interview.\
 ORCHESTRATOR = Role(
     name="orchestrator",
     tier=ModelTier.DEEP,
+    effort=Effort.HIGH,
     instructions=INSTRUCTIONS,
     #: What a planning pass works with: the project's vocabulary, the synthesis
     #: of a conversation into a spec, and the breakdown of that spec into work.

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/agents/reviewer.py

@@ -33,6 +33,7 @@ from ..context.prompt import render_context_block
 from ..core.contracts import (
     AgentResult,
     ContextPack,
+    Effort,
     ModelTier,
     Outcome,
     Plan,
@@ -158,6 +159,7 @@ End your reply with this block and nothing after it:
 REVIEWER = Role(
     name="reviewer",
     tier=ModelTier.DEEP,
+    effort=Effort.HIGH,
     instructions=INSTRUCTIONS,
     skills=WRITING_SKILLS,
 )

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/agents/security.py

@@ -1,9 +1,15 @@
 """The Security Role: audits the change, and fixes nothing.
 
-It runs at `deep` per ADR-0004, which is the one tier decision in the project
-that is not about cost. A missed finding is silent — nobody reviews the audit
-that did not happen — so the Role that looks for what nobody asked about is the
-Role that cannot be run cheaply.
+It runs at `standard` and thinks at `high` (ADR-0004, amended 2026-09-03). The
+tier used to be `deep`, on the one argument in the table that was not about
+cost: a missed finding is silent — nobody reviews the audit that did not happen
+— so the Role that looks for what nobody asked about cannot be run cheaply.
+
+That argument survives; it was only ever about reasoning. When effort became a
+Role's own axis, the depth it was really buying became purchasable on its own,
+and Security kept it — `high`, above the Implementer whose work it reads —
+while the tier came down. If audits start missing what a human then finds at
+Sign-off, the tier is the half to move back.
 
 Its output is a list of Findings rather than prose, because the Gate downstream
 of it has to tell "audited, nothing found" from "did not audit", and a paragraph
@@ -16,7 +22,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from ..context.prompt import render_context_block
-from ..core.contracts import AgentResult, ContextPack, ModelTier, Plan, Role
+from ..core.contracts import AgentResult, ContextPack, Effort, ModelTier, Plan, Role
 from ..core.plan_format import RESULT_CLOSE, RESULT_OPEN
 from .implementer import render_steps
 
@@ -86,8 +92,14 @@ Use `"outcome": "escalated"` only when the Plan does not match the repository, \
 or when you could not audit the change at all. Say which in `summary`.\
 """
 
-#: Security runs `deep`: a finding nobody makes is a finding nobody reviews.
-SECURITY = Role(name="security", tier=ModelTier.DEEP, instructions=INSTRUCTIONS)
+#: A finding nobody makes is a finding nobody reviews — bought as depth rather
+#: than as model size. See the module docstring and ADR-0004.
+SECURITY = Role(
+    name="security",
+    tier=ModelTier.STANDARD,
+    effort=Effort.HIGH,
+    instructions=INSTRUCTIONS,
+)
 
 
 def build_prompt(

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/agents/tester.py

@@ -5,7 +5,15 @@ from __future__ import annotations
 from pathlib import Path
 
 from ..context.prompt import render_context_block
-from ..core.contracts import AgentResult, ContextPack, ModelTier, Outcome, Plan, Role
+from ..core.contracts import (
+    AgentResult,
+    ContextPack,
+    Effort,
+    ModelTier,
+    Outcome,
+    Plan,
+    Role,
+)
 from ..core.plan_format import RESULT_CLOSE, RESULT_OPEN
 from .implementer import render_steps
 
@@ -66,7 +74,12 @@ from verifying. Reading tests is not a substitute for running them.\
 #: recorded in ADR-0004 — reasoning about an edge case nobody wrote a test for is
 #: the part that gets worse here, and it is the part a human reads the findings
 #: for anyway.
-TESTER = Role(name="tester", tier=ModelTier.CHEAP, instructions=INSTRUCTIONS)
+TESTER = Role(
+    name="tester",
+    tier=ModelTier.CHEAP,
+    effort=Effort.MEDIUM,
+    instructions=INSTRUCTIONS,
+)
 
 
 def build_prompt(

agentforge_framework-0.2.4/src/agentforge_framework/core/config.py

@@ -0,0 +1,158 @@
+"""Read project configuration without creating or changing it."""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+import yaml
+
+from .contracts import Effort, ModelTier
+
+
+class CapabilityTier(StrEnum):
+    """How a Provider receives a Role's declared Vendored Skills."""
+
+    NATIVE = "native"
+    FRAGMENT = "fragment"
+
+
+DEFAULT_CAPABILITIES = {
+    "claude": CapabilityTier.NATIVE,
+    "codex": CapabilityTier.FRAGMENT,
+}
+
+#: What a `tests` Gate runs when the project declares nothing. `pytest` rather
+#: than `python -m pytest`, so that an environment without it is a binary the
+#: Command Runner cannot find — which is the difference between a suite that
+#: could not be run and one that ran and failed, and the Gate reports them
+#: differently.
+DEFAULT_TEST_SUITE = ("pytest",)
+
+
+@dataclass(frozen=True)
+class Config:
+    """The read-only project configuration the Workflow runtime reads."""
+
+    provider_capabilities: dict[str, CapabilityTier] = field(
+        default_factory=lambda: dict(DEFAULT_CAPABILITIES)
+    )
+    #: The argument vector the test-suite Gate runs. An argument vector, not a
+    #: Command in the glossary's sense: nothing infers anything from it.
+    test_suite: tuple[str, ...] = DEFAULT_TEST_SUITE
+
+    #: Whether the Context Pack comment publishes the symbols and import graph
+    #: it resolved, or only their counts. Off by default: the Issue already
+    #: carries the pack's file paths in the frozen Plan, and nothing else on it
+    #: carries private symbol names. A tracker whose audience matches the
+    #: code's turns this on. See ADR-0024.
+    publish_pack_inventory: bool = False
+
+    #: Per-Provider overrides of the adapter's tier-to-model table, keyed by
+    #: provider name and then by tier. ADR-0004 promised this in its first
+    #: paragraph and nothing read it until 2026-09-03. A tier absent here keeps
+    #: the adapter's default, so a project pins the one tier it disagrees about
+    #: rather than restating all three.
+    provider_models: dict[str, dict[ModelTier, str]] = field(default_factory=dict)
+
+    #: Per-Role overrides of the two declared axes. The Role still never names a
+    #: model — it names a tier, and the Provider maps that. `roles.x.model` is
+    #: deliberately not a key: a model named per Role does not survive a release
+    #: and does not port across Providers, which is the whole of ADR-0004.
+    role_tiers: dict[str, ModelTier] = field(default_factory=dict)
+    role_efforts: dict[str, Effort] = field(default_factory=dict)
+
+    def capability_for(self, provider: str) -> CapabilityTier:
+        return self.provider_capabilities.get(provider, CapabilityTier.FRAGMENT)
+
+    def model_for(self, provider: str, tier: ModelTier) -> str | None:
+        """The configured model for a tier, or None to keep the adapter's own."""
+        return self.provider_models.get(provider, {}).get(tier)
+
+
+def load_config(root: Path | str) -> Config:
+    """Read ``.agentforge/config.yaml``, or return documented defaults."""
+    path = Path(root) / ".agentforge" / "config.yaml"
+    if not path.is_file():
+        return Config()
+
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    capabilities = dict(DEFAULT_CAPABILITIES)
+    models: dict[str, dict[ModelTier, str]] = {}
+    for name, provider in (data.get("providers") or {}).items():
+        if "capability_tier" in provider:
+            capabilities[str(name)] = CapabilityTier(provider["capability_tier"])
+        if provider.get("models"):
+            models[str(name)] = {
+                ModelTier(tier): str(slug) for tier, slug in provider["models"].items()
+            }
+
+    tiers, efforts = _role_overrides(data)
+    return Config(
+        provider_capabilities=capabilities,
+        test_suite=_test_suite(data),
+        publish_pack_inventory=bool(
+            (data.get("context") or {}).get("publish_inventory", False)
+        ),
+        provider_models=models,
+        role_tiers=tiers,
+        role_efforts=efforts,
+    )
+
+
+def _role_overrides(data: dict) -> tuple[dict[str, ModelTier], dict[str, Effort]]:
+    """`roles.<name>.tier` and `roles.<name>.effort`, the two declared axes.
+
+    A `model` key here is refused rather than ignored. Silently dropping it
+    would leave a project believing it had pinned a model per Role, which reads
+    as working right up until a Provider changes — and the whole reason
+    ADR-0004 gives a Role a tier is that the failure is otherwise invisible.
+    """
+    tiers: dict[str, ModelTier] = {}
+    efforts: dict[str, Effort] = {}
+    for name, role in (data.get("roles") or {}).items():
+        if "model" in role:
+            raise ValueError(
+                f"`roles.{name}.model` names a model per Role, which ADR-0004 "
+                f"does not allow; set `roles.{name}.tier` and override "
+                f"`providers.<name>.models.<tier>` if the mapping is wrong"
+            )
+        if "tier" in role:
+            tiers[str(name)] = ModelTier(role["tier"])
+        if "effort" in role:
+            efforts[str(name)] = Effort(role["effort"])
+    return tiers, efforts
+
+
+def _test_suite(data: dict) -> tuple[str, ...]:
+    """`gates.tests.suite`: what the test-suite Gate runs in this repository.
+
+    A string is split the way a shell would; a list is taken as written, which
+    is how a path with a space in it gets named. Nothing here consults the tree
+    — a project that runs `npm test` says so, rather than being guessed at.
+
+    ADR-0007 defers a general execution allowlist to M5. This is the bounded
+    case that ADR names as the appropriate thing to persist: one suite, declared
+    by the project, run by AgentForge itself rather than by a Role.
+    """
+    value = ((data.get("gates") or {}).get("tests") or {}).get("suite")
+    if value is None:
+        return DEFAULT_TEST_SUITE
+
+    if isinstance(value, str):
+        parts = tuple(shlex.split(value))
+    elif isinstance(value, list):
+        parts = tuple(str(part) for part in value)
+    else:
+        raise TypeError(
+            f"`gates.tests.suite` must be a string or a list, not {type(value).__name__}"
+        )
+
+    if not parts:
+        raise ValueError("`gates.tests.suite` is empty; name the command that runs the suite")
+    return parts
+
+
+__all__ = ["DEFAULT_TEST_SUITE", "CapabilityTier", "Config", "load_config"]

{agentforge_framework-0.2.2 → agentforge_framework-0.2.4}/src/agentforge_framework/core/contracts.py

@@ -45,6 +45,28 @@ class ModelTier(StrEnum):
     CHEAP = "cheap"
 
 
+class Effort(StrEnum):
+    """How hard a Role thinks, named by intent and independent of its tier.
+
+    The second axis ADR-0004 originally folded into the first. A Model Tier
+    chooses which model runs; an Effort chooses how much reasoning it spends
+    getting there, and the two are not the same purchase -- the Security Role
+    is the case that proves it, auditing at `standard` and thinking at `high`.
+
+    The levels are the intersection of what the shipped adapters' CLIs accept:
+    `claude --effort` takes low through max, and every slug in a real codex
+    install takes the same five. `ultra` is offered by one codex model alone
+    and is deliberately absent -- a level a Role could declare and most
+    Providers could not honor is not an intent-named level.
+    """
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+    MAX = "max"
+
+
 class Outcome(StrEnum):
     """How an Agent finished.
 
@@ -278,11 +300,25 @@ class Role:
     tier: ModelTier
     instructions: str = ""
     skills: tuple[str, ...] = ()
+    #: How much reasoning the Role spends, independent of which model runs it.
+    #: `medium` rather than a tier-derived value: a Role that has not thought
+    #: about the question gets the level both CLIs already default most models
+    #: to, and the ones that have thought about it say so.
+    effort: Effort = Effort.MEDIUM
 
     def at_tier(self, tier: ModelTier) -> Role:
         """The same Role with its tier overridden, per user request or config."""
         return replace(self, tier=tier)
 
+    def at_effort(self, effort: Effort) -> Role:
+        """The same Role with its effort overridden, per config.
+
+        Separate from `at_tier` because the axes move separately -- overriding
+        one has never implied anything about the other, which is the whole
+        reason there are two.
+        """
+        return replace(self, effort=effort)
+
 
 @dataclass(frozen=True)
 class Roster: