agentforge-framework 0.2.3__tar.gz → 0.2.5__tar.gz

{agentforge_framework-0.2.3 → agentforge_framework-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-framework
-Version: 0.2.3
+Version: 0.2.5
 Summary: A modular framework for coordinating specialized software agents.
 Author: Yash Mhatre
 License-Expression: Apache-2.0
@@ -26,9 +26,9 @@ A human states a Task. The Orchestrator grills them on it, writes a spec, cuts t
 
 ## Status
 
-The Workflow runtime now runs multiple Roles in order. The default `feature`
-Workflow invokes the Implementer, the Tester, Security, and then the Reviewer,
-posting each Agent Result to the Issue before starting the next Step.
+A Workflow runs its Roles in order. The default `feature` Workflow invokes the
+Implementer, the Tester, Security, and then the Reviewer, posting each Agent
+Result to the Issue before starting the next Step.
 
 ```console
 $ agentforge plan "add a retry to the loader"
@@ -99,15 +99,20 @@ 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
+run. Plugins carry the data-engineering conventions: a
 repository whose files import `pyspark` has its Roles told to write DataFrame
 expressions rather than RDDs, and a Databricks workspace gets Unity Catalog
 naming and the Delta MERGE idioms in the prompts that write code and the
 workspace's own posture in the one that audits it. A repository that matches
-neither hears neither. `agentforge init` is still to come. See
-[`docs/PLAN.md`](docs/PLAN.md).
+neither hears neither. `agentforge init` inspects a repository and writes its
+`.agentforge/config.yaml`; the file is optional, and
+[Project configuration](#project-configuration) below says what it holds. What
+is still to come is in [`docs/PLAN.md`](docs/PLAN.md).
 
 Before the first Role is invoked, AgentForge resolves a Context Pack from the
 frozen plan — the files it names, the symbols and imports inside them, the
@@ -145,7 +150,7 @@ without notice. See
 ```console
 $ pip install agentforge-framework
 $ agentforge --version
-agentforge 0.2.3
+agentforge 0.2.5
 ```
 
 That is the whole of it. The two routes below the naming note are for a machine
@@ -169,7 +174,7 @@ from the [latest release](https://github.com/yashmhatre/AgentForge/releases/late
 and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.3-py3-none-any.whl
+$ pip install agentforge_framework-0.2.5-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:
@@ -206,7 +211,7 @@ AgentForge is a terminal tool. It runs fine from an IDE's terminal, but the IDE
 
 **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.
+**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. A second `agentforge implement` is refused outright rather than merely disclosed — a Run holds its checkout for the duration ([ADR-0026](docs/adr/0026-a-run-holds-the-checkout-it-was-pointed-at.md)) — but nothing else consults that lock, so an IDE assistant is still yours to keep away.
 
 ## Commands
 
@@ -274,22 +279,53 @@ if the repository has no GitHub remote, because ADR-0002 makes that a
 precondition for every Run. Re-running never clobbers a config you have edited:
 it reports what differs and writes nothing, and `--force` replaces it.
 
+A Python suite is written pinned to the interpreter that will run it —
+`[".venv/bin/python", "-m", "pytest"]` rather than `pytest` — whenever the
+repository has a virtualenv to pin it to, and init checks that the interpreter
+can run pytest before writing the line. Bare `pytest` is whichever one PATH
+answers with, which in a project with a venv is the one the project does not
+use: the suite then fails on imports that are installed and reads as a broken
+repository rather than a misconfigured one. The interpreter is named relative to
+the repository root, so the file is still right on somebody else's clone, and
+init looks up to two directories down for the project — a suite that lives in
+`subproject/tests/` is found, and named.
+
 The file is not a precondition. Without one, the documented Provider capability
 defaults are Claude `native` and every other Provider `fragment`, and the
-`tests` Gate runs `pytest`.
+`tests` Gate runs `pytest` — the case the pinning above exists to avoid, so a
+repository with a venv is better off with a file.
 
 ```yaml
 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

{agentforge_framework-0.2.3 → agentforge_framework-0.2.5}/README.md

@@ -8,9 +8,9 @@ A human states a Task. The Orchestrator grills them on it, writes a spec, cuts t
 
 ## Status
 
-The Workflow runtime now runs multiple Roles in order. The default `feature`
-Workflow invokes the Implementer, the Tester, Security, and then the Reviewer,
-posting each Agent Result to the Issue before starting the next Step.
+A Workflow runs its Roles in order. The default `feature` Workflow invokes the
+Implementer, the Tester, Security, and then the Reviewer, posting each Agent
+Result to the Issue before starting the next Step.
 
 ```console
 $ agentforge plan "add a retry to the loader"
@@ -81,15 +81,20 @@ 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
+run. Plugins carry the data-engineering conventions: a
 repository whose files import `pyspark` has its Roles told to write DataFrame
 expressions rather than RDDs, and a Databricks workspace gets Unity Catalog
 naming and the Delta MERGE idioms in the prompts that write code and the
 workspace's own posture in the one that audits it. A repository that matches
-neither hears neither. `agentforge init` is still to come. See
-[`docs/PLAN.md`](docs/PLAN.md).
+neither hears neither. `agentforge init` inspects a repository and writes its
+`.agentforge/config.yaml`; the file is optional, and
+[Project configuration](#project-configuration) below says what it holds. What
+is still to come is in [`docs/PLAN.md`](docs/PLAN.md).
 
 Before the first Role is invoked, AgentForge resolves a Context Pack from the
 frozen plan — the files it names, the symbols and imports inside them, the
@@ -127,7 +132,7 @@ without notice. See
 ```console
 $ pip install agentforge-framework
 $ agentforge --version
-agentforge 0.2.3
+agentforge 0.2.5
 ```
 
 That is the whole of it. The two routes below the naming note are for a machine
@@ -151,7 +156,7 @@ from the [latest release](https://github.com/yashmhatre/AgentForge/releases/late
 and install the file:
 
 ```console
-$ pip install agentforge_framework-0.2.3-py3-none-any.whl
+$ pip install agentforge_framework-0.2.5-py3-none-any.whl
 ```
 
 Publishing a release is a wizard rather than a checklist:
@@ -188,7 +193,7 @@ AgentForge is a terminal tool. It runs fine from an IDE's terminal, but the IDE
 
 **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.
+**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. A second `agentforge implement` is refused outright rather than merely disclosed — a Run holds its checkout for the duration ([ADR-0026](docs/adr/0026-a-run-holds-the-checkout-it-was-pointed-at.md)) — but nothing else consults that lock, so an IDE assistant is still yours to keep away.
 
 ## Commands
 
@@ -256,22 +261,53 @@ if the repository has no GitHub remote, because ADR-0002 makes that a
 precondition for every Run. Re-running never clobbers a config you have edited:
 it reports what differs and writes nothing, and `--force` replaces it.
 
+A Python suite is written pinned to the interpreter that will run it —
+`[".venv/bin/python", "-m", "pytest"]` rather than `pytest` — whenever the
+repository has a virtualenv to pin it to, and init checks that the interpreter
+can run pytest before writing the line. Bare `pytest` is whichever one PATH
+answers with, which in a project with a venv is the one the project does not
+use: the suite then fails on imports that are installed and reads as a broken
+repository rather than a misconfigured one. The interpreter is named relative to
+the repository root, so the file is still right on somebody else's clone, and
+init looks up to two directories down for the project — a suite that lives in
+`subproject/tests/` is found, and named.
+
 The file is not a precondition. Without one, the documented Provider capability
 defaults are Claude `native` and every other Provider `fragment`, and the
-`tests` Gate runs `pytest`.
+`tests` Gate runs `pytest` — the case the pinning above exists to avoid, so a
+repository with a venv is better off with a file.
 
 ```yaml
 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

{agentforge_framework-0.2.3 → agentforge_framework-0.2.5}/pyproject.toml

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

{agentforge_framework-0.2.3 → agentforge_framework-0.2.5}/src/agentforge_framework/__init__.py

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

{agentforge_framework-0.2.3 → agentforge_framework-0.2.5}/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.3 → agentforge_framework-0.2.5}/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.3 → agentforge_framework-0.2.5}/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.3 → agentforge_framework-0.2.5}/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.3 → agentforge_framework-0.2.5}/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.3 → agentforge_framework-0.2.5}/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.3 → agentforge_framework-0.2.5}/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.3 → agentforge_framework-0.2.5}/src/agentforge_framework/cli.py

@@ -512,7 +512,7 @@ def _run_init(args: argparse.Namespace, runner=None) -> int:
     from .core.config import load_config
     from .core.contracts import Plan
     from .core.process import SubprocessRunner
-    from .core.project import config_path, detect, differences, render_config
+    from .core.project import config_path, detect, differences, render_config, verified
     from .core.registry import activate
     from .core.repo import PreconditionFailed, open_repository
     from .providers import DEFAULT_PROVIDER, PROVIDERS
@@ -531,11 +531,14 @@ def _run_init(args: argparse.Namespace, runner=None) -> int:
         return 2
 
     active = activate(Plan(summary=""), repo.root)
-    context = detect(
-        repo.root,
-        provider,
-        tracked=repo.tracked_files(),
-        plugins=tuple(plugin.name for plugin in active.plugins),
+    context = verified(
+        detect(
+            repo.root,
+            provider,
+            tracked=repo.tracked_files(),
+            plugins=tuple(plugin.name for plugin in active.plugins),
+        ),
+        runner,
     )
 
     print(f"Repository: {repo.root}")
@@ -544,6 +547,8 @@ def _run_init(args: argparse.Namespace, runner=None) -> int:
     suite = " ".join(context.test_suite)
     where = context.suite_detected or "not detected, so this is the documented default"
     print(f"  Suite:     `{suite}` — {where}")
+    if context.suite_note:
+        print(f"             {context.suite_note}")
     print(f"  Plugins:   {', '.join(context.plugins) or 'none by root marker'}")
     print(
         "             printed, not written: which Plugins answer is decided per Run\n"

{agentforge_framework-0.2.3 → agentforge_framework-0.2.5}/src/agentforge_framework/core/config.py

@@ -9,6 +9,8 @@ from pathlib import Path
 
 import yaml
 
+from .contracts import Effort, ModelTier
+
 
 class CapabilityTier(StrEnum):
     """How a Provider receives a Role's declared Vendored Skills."""
@@ -48,9 +50,27 @@ class Config:
     #: 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."""
@@ -60,17 +80,52 @@ def load_config(root: Path | str) -> 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():
-        capabilities[str(name)] = CapabilityTier(provider["capability_tier"])
+        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.
 

{agentforge_framework-0.2.3 → agentforge_framework-0.2.5}/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: