2026-05-09 13:36:02 +00:00 · 2026-05-09 16:00:55 +00:00 · 2026-05-09 16:00:55 +00:00 · 2026-05-09 13:36:03 +00:00 · 2026-05-09 13:36:03 +00:00 · 2026-05-09 16:00:55 +00:00
6 changed files with 537 additions and 22 deletions
@@ -3,8 +3,6 @@ name: CI
 on:
    push:
        branches: [master, develop]
-    pull_request:
-        branches: [master, develop]

 vars:
    docker_prefix: "http://harbor.cleverthis.com/docker/"
@@ -5,6 +5,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

 ## [Unreleased]

+### Test Infra
+
+- **Harden BDD scenario tagging rules with strict one-tag-per-domain enforcement** (#10992): Added ``validate_domain_tags()`` and ``check_domain_title_keywords()`` in ``features/environment.py`` to enforce that each Behave scenario belongs to a single architectural domain (``@a2a``, ``@session``, or ``@cli``). The only allowed cross-domain combination is ``@session`` + ``@cli`` (sessions are exercised via CLI by definition). Mixing ``@a2a`` with any other domain tag is now a hard error that fails the scenario before it runs. A complementary soft-warning system emits stderr+logger messages when a scenario title contains domain keywords (e.g. "A2A agent") but lacks the corresponding tag — this never breaks CI, it only surfaces potential mis-tagging. Full BDD coverage in ``features/testing/bdd_tag_enforcement.feature`` with dedicated step definitions.
+
 - Fixed `ReactiveEventBus.emit()` exception handler to log the full exception
  message (`str(exc)`) and enable traceback forwarding (`exc_info=True`).
  Previously the handler logged only the exception type name (e.g.
@@ -14,6 +18,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  from the TDD test so both scenarios run as normal regression guards. (#988)

 ### Fixed
+- **TUI Prompt Symbol Mode Awareness** (#6431): The prompt widget now displays a
+  mode-dependent symbol (`❯` normal, `/` command, `$` shell, `☰` multi-line),
+  implemented via `_PromptSymbolMixin` and `InputMode.MULTILINE`. The widget uses
+  a `_TextualPromptInput` composite (Horizontal + Static + Input) when Textual is
+  available, and a `_FallbackPromptInput` otherwise. Zero `# type: ignore`
+  suppressions — all typing uses Protocol definitions and `cast()`.
 - **Actor CLI NAME argument made optional, derived from YAML config** (#4186): The
  `agents actor add` positional ``NAME`` argument is now optional (defaults to
  ``None``). When omitted, the actor name is derived from the ``name`` field in
@@ -77,8 +87,21 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  This wires the previously-isolated `discover_devcontainers()` function into the production
  code path, enabling the spec's zero-configuration devcontainer experience.

+- **Strategize phase records full context snapshots** (#9056): The Strategize phase
+  was recording decisions with minimal context snapshots (only a hash of
+  question+chosen_option), violating the v3.2.0 acceptance criterion that decisions
+  must include full context snapshots sufficient to replay the decision. Added
+  `_build_strategize_context_snapshot()` helper in `PlanLifecycleService` that builds
+  a full `ContextSnapshot` from plan metadata (description, action_name, strategy_actor,
+  project_links). Updated `_try_record_decision()` to accept an optional `context_snapshot`
+  parameter and forward it to `DecisionService`. Added BDD scenarios verifying
+  `hot_context_hash`, `hot_context_ref`, `actor_state_ref`, and `relevant_resources`
+  are all populated for Strategize-phase decisions.
+
 ### Changed

+- Fixed stale `AUTO-BUG-POOL` tracking prefix references in automation-tracking.md documentation and agent-system-specification.md spec document, replaced with correct `AUTO-BUG-SUP` prefix used by the bug-hunt-pool-supervisor agent (#7875).
+
 - **`agents session list` now displays full 26-character session ULIDs** (#10970): The Rich table
  and Summary panel ("Most Recent" / "Oldest") previously showed only the first 8 characters of
  each session ULID. This made the output unusable for copy-paste into `session tell`,
@@ -86,6 +109,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  26-character identifier. The full ULID is now displayed in all output formats (Rich, plain,
  JSON, YAML, table).

+- **`pr-creator` now applies State/In Review and Priority labels** (#8520): Extended
+  `pr-creator` step 4 to apply three labels on every new PR: the `Type/` label (from
+  the caller's `type_label` parameter), `State/In Review` (always applied), and the
+  `Priority/` label matching the linked issue. Updated Rule 1 to enumerate all required
+  labels. Addresses the 53% missing-State-label rate observed across open PRs of
+  2026-04-13.
+
 - **Suppress passing BDD scenario output in `unit_tests` by default** (#10987): Implemented
  `PassSuppressFormatter`, a custom Behave formatter (in `scripts/behave_pass_suppress_formatter.py`)
  that buffers all per-scenario output and only flushes it to stdout when a scenario fails or
@@ -116,6 +146,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  and milestone assignment. This eliminates systemic PR merge blockers caused by workers
  omitting required items.

+- **Implementation Pool Supervisor PR Compliance Checklist** (#9824): Added a mandatory
+  8-item PR Compliance Checklist to the new `implementation-pool-supervisor.md` agent definition.
+  Supervisors must enforce that workers complete all 8 checklist items (CHANGELOG.md update,
+  CONTRIBUTORS.md update, commit footer, CI verification, BDD tests, Epic reference, label
+  application, and milestone assignment) before creating any PR. Includes concrete markdown
+  examples for each subsection and compliance verification pseudocode to ensure reproducible
+  adherence.
+
+- **ACMS context path matching now handles absolute fragment paths** (#10972): Fixed
+  `_path_matches()` in `execute_phase_context_assembler.py` and `_matches_pattern()` in
+  `context_phase_analysis.py` to correctly match absolute paths (e.g. `/app/.opencode/skills/SKILL.md`)
+  against relative glob patterns (e.g. `.opencode/**`, `docs/*`). Previously
+  `PurePath.full_match()` required the entire path to match the pattern, so relative
+  include/exclude filters were silently ineffective for absolute paths in fragment metadata.
+  Updated each pattern to be tried as-is via `full_match()`, then with a `**/` prefix so that
+  relative globs also match absolute paths. Added BDD regression tests in
+  `execute_phase_context_assembler_coverage.feature` and `project_context_phase_analysis.feature`.
+
 ### Changed

 - Restored `benchmark-regression` CI job to `master.yml` with `pull_request` trigger guard
@@ -178,6 +226,25 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  failure paths. Comprehensive BDD test coverage validates the fix under concurrent
  execution and confirms proper cleanup behavior.

+- **Database resource types (PostgreSQL, SQLite) with transaction-based sandbox strategy** (#8608):
+  Implemented comprehensive database resource support enabling users to interact with
+  PostgreSQL and SQLite backends through a unified resource interface. Introduces
+  `DatabaseResourceHandler` providing full CRUD operations (`read`, `write`, `delete`,
+  `list_children`), connection validation with automatic credential masking via
+  :mod:`cleveragents.shared.redaction`, and transaction-based sandbox strategy using
+  BEGIN/COMMIT/ROLLBACK wrappers for safe, isolated database operations. SQLite-specific
+  checkpoint and rollback support with SAVEPOINT semantics. Support for multiple backends (PostgreSQL, SQLite, MySQL, DuckDB) via unified "DatabaseResourceHandler" and type-specific routing. BDD test
+  coverage in ``features/database_resources.feature`` (connection validation, CRUD workflows,
+  transaction/rollback behavior, error handling, credential masking verification) and
+  Robot Framework integration tests in ``robot/database_resources.robot``.
+
+- **TransactionSandbox infrastructure for database resource isolation** (#8608):
+  Implemented ``TransactionSandbox`` class with BEGIN/COMMIT/ROLLBACK lifecycle
+  management for transaction-based sandbox strategy. Wired into ``SandboxFactory``
+  as the strategy resolver for database resource types. Added ``database`` resource type
+  registration in bootstrap builtin types and updated ``_resource_registry_data.py``
+  to recognize database resource categories.
+
 ### Fixed

 - **fix(repositories): derive PlanResult.success from result_success column instead of error_message** (#7501):
@@ -428,6 +495,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  forward-compatibility.  Added BDD coverage for the stored-JSON path,
  corrupt-JSON fallback, resource-passing, and stub extra-kwargs scenarios. (#828)

+- **Decision Recording Hook in Strategize Phase** (#8522): Implemented
+  `StrategizeDecisionHook` class that integrates decision recording into the
+  Strategize phase. The hook captures every decision point during strategy
+  decomposition, including question, chosen option, alternatives considered,
+  confidence score, rationale, and full context snapshot (hot context hash,
+  actor state reference, relevant resources). Supports recording of
+  `strategy_choice`, `resource_selection`, `subplan_spawn`, and
+  `invariant_enforced` decision types. Context snapshots are auto-captured
+  with SHA256 hashing of context data and checkpoint references for LangGraph
+  actor state. Includes comprehensive BDD test suite with 40+ scenarios
+  covering all decision types, context capture, error handling, and tree
+  structure validation.

 - **TDD Issue-Capture Test Activation** (#7025): Replaced 234 bare `@skip` tags
  across 82 Behave feature files with the correct `@tdd_expected_fail @tdd_issue
@@ -599,6 +678,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  delays from 15s to 2s, and reduced idle sleep from 60s to 10s for dramatically
  faster throughput.

+- **Specification — Validation Gate Empty-Run Guard** (#8146): Updated `docs/specification.md`
+  to document the security invariant introduced in PR #7786 (fixing issue #7508). The spec now
+  explicitly states that `ApplyValidationSummary.all_required_passed` returns `False` when no
+  validations have been run (empty summary), blocking apply. Added a prominent danger admonition
+  block, updated the validation process results section, the `final_validation_results` data
+  model description, and two milestone acceptance criteria to reflect the corrected blocking
+  behavior for empty validation summaries and no-attachment runs.

 ### Fixed

@@ -17,10 +17,13 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed automated implementation, bug fixes, and feature development as part of the CleverAgents automation pool.
 * HAL 9000 has contributed concurrency safety improvements, including thread-safe context tier management (issue #7547) for parallel plan execution.
 * HAL 9000 has contributed the plan concurrency race-condition fix (#7989): wired `LockService` into the plan lifecycle, guarding `execute_plan()` and `apply_plan()` with plan-level advisory locks and unique per-invocation owner identities to prevent silent concurrent state corruption.
-* HAL 9000 has contributed the bug-hunt-pool-supervisor non-blocking tracking fix: updated step 5 to be best-effort and added rule 9 to prevent the automation-tracking-manager call from blocking the main supervisor loop.
+* HAL 9000 has contributed the bug-hunt-pool-supervisor non-blocking tracking fix (#7875 / PR #7957): updated step 5 to be best-effort and added rule 9 to prevent the automation-tracking-manager call from blocking the main supervisor loop.
+* Jeffrey Phillips Freeman has contributed the complete AUTO-BUG-POOL to AUTO-BUG-SUP tracking prefix fix across agent-system-specification.md, automation-tracking.md documentation and agent-system-specification.md spec document, replaced with correct `AUTO-BUG-SUP` prefix used by the bug-hunt-pool-supervisor agent (#7875).
 * HAL 9000 has contributed the plugin entry point security hardening fix (#7476): enforced entry point allowlist validation before importing plugin modules to prevent malicious plugin loading.
 * HAL 9000 has contributed the benchmark workflow separation (#9040): moved the benchmark-regression job out of the default PR workflow into a dedicated scheduled workflow, reducing median PR CI turnaround time from 99-132 minutes to under 30 minutes.
 * HAL 9000 has contributed the agent-evolution-pool-supervisor PR metadata assignment (#7888): the supervisor now automatically looks up the Type/Automation label and earliest open milestone before dispatching improvement PR creation workers, ensuring all generated improvement PRs have correct Type labels and milestone assignments.
+* HAL 9000 has contributed the decision recording hook for the Strategize phase (issue #8522): captures every decision point with question, chosen option, alternatives, confidence, rationale, and full context snapshot for replay and correction.
+* HAL 9000 has contributed automated specification maintenance, documentation updates, and bot-driven PR authorship.
 * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
 * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.
 * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559).
@@ -29,8 +32,12 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the git_tools TOCTOU race condition fix (PR #8255 / issue #7619): eliminated the Time-Of-Check-To-Time-Of-Use race in `_get_base_env()` by adding double-checked locking with a module-level `threading.Lock`, preventing concurrent threads from writing conflicting environment snapshots.
 * HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-supervisor.md` (#9824): added an 8-item checklist to the worker prompt body with concrete items covering CHANGELOG.md, CONTRIBUTORS.md, commit footer, CI verification, BDD tests, Epic reference, labels, and milestone assignment to eliminate systemic PR merge blockers.
 * HAL 9000 has contributed the PlanResult.success derivation fix (PR #8214 / issue #7501): replaced the incorrect `error_message is None` heuristic with a dedicated `result_success` column in the plans table, ensuring plans with historical build errors are not incorrectly marked as failed after a successful apply.
+* HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-pool-supervisor.md` (#9824): created a new agent definition with an embedded 8-item checklist ensuring workers always update CHANGELOG.md, CONTRIBUTORS.md, include commit footers (`ISSUES CLOSED: #N`), verify CI passes, add BDD tests, reference the parent Epic, apply labels via forgejo-label-manager, and assign milestones before creating PRs. Includes concrete examples for each subsection and compliance verification pseudocode.
 * HAL 9000 has contributed comprehensive milestone documentation for v3.6.0 (Advanced Concepts & Deferred Features) and v3.7.0 (TUI Implementation) (PR #9903): split into sub-documents covering context strategies, LLM backends, resource types, A2A rename, container tool execution, scope chain resolution, cost/safety budgets, E2E workflow tests, code review examples, plugin architecture, TUI layout, persona system, reference/command input, session management, configuration, and TuiMaterializer integration.
 * HAL 9000 has contributed the LLMTraceRepository data-integrity fix (PR #8185 / issue #7505): replaced the unconditional `session.commit()` in `LLMTraceRepository.save()` with a dual-path implementation that respects the UnitOfWork pattern — flushing only when an external session is provided, and flushing + committing + closing when operating standalone. This eliminates premature transaction commits, loss of rollback capability, and a docstring/implementation mismatch.
 * HAL 9000 has contributed the ACMS Index Data Model and File Traversal Engine (PR #9664 / issue #9579): foundational data structures for indexed context entries with hot/warm/cold/archive storage tier classification, tag system, and a timeout-safe chunked file traversal engine for large projects with 10,000+ files.
-
-* HAL 9000 has contributed the error-suppression removal fix (PR #9247 / issue #9060): removed both `try...except Exception:` blocks in `register_registry_agents()` that silently suppressed errors from `actor_registry.list_actors()` and the route bridge refresh, enabling exceptions to propagate per CONTRIBUTING.md fail-fast policy. Added three Behave scenarios verifying RuntimeError, AttributeError, and TypeError propagation.
+* HAL 9000 has contributed the error-suppression removal fix (PR #9247 / issue #9060): removed both `try...except Exception:` blocks in `register_registry_agents()` that silently suppressed errors from `actor_registry.list_actors()` and the route bridge refresh, enabling exceptions to propagate per CONTRIBUTING.md fail-fast policy. Added three Behave scenarios verifying RuntimeError, AttributeError, and TypeError propagation.
+* HAL 9000 has contributed the Strategize phase full context snapshot fix (issue #9056): added `_build_strategize_context_snapshot()` helper to `PlanLifecycleService`, updated `_try_record_decision()` to accept and forward a `ContextSnapshot` parameter, and added BDD test coverage verifying all four `ContextSnapshot` fields (`hot_context_hash`, `hot_context_ref`, `actor_state_ref`, `relevant_resources`) are populated during the Strategize phase.
+* HAL 9000 has contributed the ACMS context path matching fix (PR #10975 / issue #10972): corrects `_path_matches()` and `_matches_pattern()` to properly match absolute fragment paths against relative glob patterns by auto-prefixing with `**/` before calling `PurePath.full_match()`, preventing silent inefficacy of include/exclude filters for absolute paths in fragment metadata.
+* HAL 9000 has contributed BDD scenario domain-tag enforcement (PR #10992): added ``validate_domain_tags()`` and ``check_domain_title_keywords()`` in ``features/environment.py`` to enforce strict one-tag-per-domain rules for ``@a2a``, ``@session``, and ``@cli`` tags across all Behave scenarios. Includes BDD test coverage in ``features/testing/bdd_tag_enforcement.feature`` with 18 scenarios covering empty sets, single tags, allowed cross-domain combinations, forbidden mixes, and keyword-to-tag soft warnings.
+* HAL 9000 has contributed database resource types (PostgreSQL, SQLite) with transaction-based sandbox strategy: implemented ``DatabaseResourceHandler`` providing full CRUD operations (`read`, `write`, `delete`, `list_children`) and connection validation with automatic credential masking for PostgreSQL and SQLite backends. Includes ``TransactionSandbox`` infrastructure wired into ``SandboxFactory``, BDD test coverage in ``features/database_resources.feature``, and Robot Framework integration tests in ``robot/database_resources.robot`` (PR #10591 / issue #8608, Epic #8568).
1
				
			
			
				
			
			
			
				@@ -33,29 +33,142 @@ LANGSMITH_ENV_VARS = [
 ]

 # ---------------------------------------------------------------------------
-# TDD Issue Test Tags — Three-Tag System
+# Domain Tags — @a2a, @session, @cli Enforcement
 # ---------------------------------------------------------------------------
-# TDD issue-capture tests use a three-tag system documented in
-# CONTRIBUTING.md > Bug Fix Workflow > TDD Issue Test Tags:
+# BDD/Behave scenarios are partitioned into three architectural domains:
 #
-#   @tdd_issue             — Generic filter tag. Present on ALL TDD issue tests.
-#   @tdd_issue_<N>         — Issue reference (e.g. @tdd_issue_123). Links the
-#                          test to the specific Type/Bug issue it captures.
-#   @tdd_expected_fail   — Behavioral switch. When present, the test result
-#                          is inverted: a failure means the bug still exists
-#                          (reported as passed), and a pass means the bug was
-#                          fixed without removing the tag (reported as failed).
+#   @a2a     — Agent-to-Agent protocol tests (A2A SDK, inter-agent messaging)
+#   @session — Session-management tests (CLI sessions, state, lifecycle)
+#   @cli     — CLI interaction tests (user-facing commands, input/output)
 #
-# The ``validate_tdd_tags`` and ``should_invert_result`` helpers below are
-# called from the ``before_scenario`` hook and the ``Scenario.run()``
-# wrapper (installed in ``before_all``) respectively.  They are extracted
-# as standalone functions so they can be unit-tested directly from Behave
-# step definitions.  ``apply_tdd_inversion`` encapsulates the full
-# inversion logic and is likewise directly testable.
+# Strict one-tag-per-domain enforcement is required: a scenario may not mix
+# domain tags from different domains.  The only allowed cross-domain
+# combination is ``@session`` + ``@cli`` because session scenarios are
+# exercised through the CLI by definition.
+#
+# Additionally, if a scenario title contains keywords belonging to a domain
+# (e.g. "a2a", "session", "cli") but the tag is missing, a soft warning is
+# emitted — this does NOT break CI, it only surfaces potential mis-tagging.
+#
+# The ``validate_domain_tags`` and ``check_domain_title_keywords`` helpers
+# below are called from the ``before_scenario`` hook.  They follow the same
+# architectural pattern as ``validate_tdd_tags``.
 # ---------------------------------------------------------------------------

 _TDD_ISSUE_N_RE = re.compile(r"tdd_issue_\d+")

+_DOMAIN_TAGS = ("a2a", "session", "cli")
+_DOMAIN_TAG_RE = re.compile(r"^(a2a|session(?:_[a-z0-9]+)?|cli)$")
+
+# Keywords that indicate the scenario belongs to a domain but is missing the tag.
+# Each keyword maps to the canonical domain tag it should have been tagged with.
+_DOMAIN_KEYWORDS: dict[str, str] = {
+    "a2a": "a2a",
+    "agent-to-agent": "a2a",
+    "inter-agent": "a2a",
+    "client agent": "a2a",
+    "session": "session",
+    "new session": "session",
+    "session lifecycle": "session",
+    "active session": "session",
+    "cli": "cli",
+    "command line interface": "cli",
+    "cli command": "cli",
+}
+_DOMAIN_KEYWORD_RE = re.compile(
+    "|".join(rf"(?:{k})" for k in _DOMAIN_KEYWORDS),
+    re.IGNORECASE,
+)
+
+
+def validate_domain_tags(tags: set[str]) -> None:
+    """Validate that a scenario does not mix incompatible domain tags.
+
+    Raises ``ValueError`` with a descriptive message when the tag set mixes
+    ``@a2a`` with other domain tags, which violates strict one-tag-per-domain
+    enforcement.  The ``@session`` + ``@cli`` combination is explicitly allowed
+    because session scenarios are exercised through the CLI by definition.
+
+    Args:
+        tags: The *effective* tags of a scenario (own tags + feature tags).
+
+    Raises:
+        ValueError: If the tag combination mixes incompatible domain domains.
+    """
+    # Normalise session_* tags to canonical "session" for set membership checks.
+    normalised: set[str] = {
+        t for t in tags if t in ("a2a",) or _DOMAIN_TAG_RE.fullmatch(t)
+    }
+
+    has_a2a = "a2a" in normalised
+    has_session = any(t.startswith("session") for t in normalised)
+    has_cli = "cli" in normalised
+
+    domain_count = sum(bool(v) for v in (has_a2a, has_session, has_cli))
+
+    if domain_count <= 1:
+        return  # Valid: single tag or none.
+
+    # At this point domain_count == 2 (can't be more -- only three domains).
+    # Allowed combination: session + cli
+    if has_session and has_cli and not has_a2a:
+        return
+
+    # Forbidden combinations: anything involving @a2a with another domain tag.
+    a2a_involved = has_a2a and (has_session or has_cli)
+    if a2a_involved:
+        offending: list[str] = []
+        if has_a2a:
+            offending.append("@a2a")
+        if has_session:
+            offending.append("@session")
+        if has_cli:
+            offending.append("@cli")
+        raise ValueError(
+            f"Scenario mixes incompatible domain tags: {', '.join(offending)}. "
+            "Strict one-tag-per-domain enforcement is required — a scenario may "
+            "only belong to a single architectural domain (a2a, session, or cli). "
+            "The only allowed cross-domain combination is @session + @cli. "
+            "See CONTRIBUTING.md > BDD Domain Tagging."
+        )
+
+
+def check_domain_title_keywords(tags: set[str], scenario_name: str) -> list[str]:
+    """Emit soft warnings when a scenario title suggests a domain but lacks the tag.
+
+    This helper scans the scenario title for domain-related keywords and warns
+    if the corresponding tag is missing.  Unlike ``validate_domain_tags``, this
+    does NOT raise exceptions — it only produces warnings so that potential
+    mis-tagging is surfaced without breaking CI.
+
+    Args:
+        tags: The *effective* tags of a scenario (own tags + feature tags).
+        scenario_name: The Gherkin scenario title / name.
+
+    Returns:
+        A list of warning messages for each keyword→tag mismatch found.
+    """
+    warnings: list[str] = []
+    normalised: set[str] = {
+        t for t in tags if t in ("a2a",) or _DOMAIN_TAG_RE.fullmatch(t)
+    }
+    has_a2a = "a2a" in normalised
+    has_session = any(t.startswith("session") for t in normalised)
+    has_cli = "cli" in normalised
+    tag_present = {"a2a": has_a2a, "session": has_session, "cli": has_cli}
+    for match in _DOMAIN_KEYWORD_RE.finditer(scenario_name):
+        matched_keyword = match.group(0).lower()
+        expected_tag = _DOMAIN_KEYWORDS.get(matched_keyword)
+        if expected_tag is None:
+            continue
+        if not tag_present.get(expected_tag, False):
+            warnings.append(
+                f"[W] Scenario '{scenario_name}' references keyword '{matched_keyword}' "
+                f"(domain={expected_tag}) but is missing the @{expected_tag} tag."
+            )
+    return warnings
+
+
 # ---------------------------------------------------------------------------
 # Process-global set of already-initialized DB paths
 # ---------------------------------------------------------------------------
@@ -63,7 +176,7 @@ _TDD_ISSUE_N_RE = re.compile(r"tdd_issue_\d+")
 # by copying the template or confirming the file is non-empty), the URL is
 # added to this set.  Subsequent calls with the same URL short-circuit at
 # the very top of the function, avoiding all URL parsing, path extraction,
-# prefix matching, and ``stat()`` syscalls.  The set is cleared in
+# and ``stat()`` syscalls.  The set is cleared in
 # ``before_scenario`` to prevent cross-scenario state leaks.
 #
 # See issue #735 — eliminates ~65,000 unnecessary function executions per
@@ -72,6 +185,21 @@ _TDD_ISSUE_N_RE = re.compile(r"tdd_issue_\d+")
 _INITIALIZED_DBS: set[str] = set()

 _tdd_logger = logging.getLogger("cleveragents.testing.tdd_tags")
+_domain_logger = logging.getLogger("cleveragents.testing.domain_tags")
+
+# ---------------------------------------------------------------------------
+# Domain-tag soft warnings — stderr visibility
+# ---------------------------------------------------------------------------
+# Soft warnings about missing domain tags are emitted to both the logger and
+# stderr so they appear in Behave output even when structured logging routes
+# logs elsewhere.
+# ---------------------------------------------------------------------------
+
+
+def _domain_warning(message: str) -> None:
+    """Emit a domain-tag soft warning to both logger and stderr."""
+    _domain_logger.warning(message)
+    print(message, file=sys.stderr)


 def _warning_with_stderr(message: str) -> None:
@@ -573,6 +701,27 @@ def before_scenario(context, scenario):
        _tdd_logger.error("TDD TAG ERROR in %r: %s", scenario.name, exc)
        return

+    # --- Domain Tag Validation (BDD @a2a/@session/@cli enforcement) ---
+    # Validate strict one-tag-per-domain enforcement.  This runs after TDD
+    # validation so that clearly misconfigured tests never execute.
+    try:
+        validate_domain_tags(set(scenario.effective_tags))
+    except ValueError as exc:
+        scenario.hook_failed = True
+        scenario.set_status(Status.failed)
+        _domain_logger.error("DOMAIN TAG ERROR in %r: %s", scenario.name, exc)
+        return
+
+    # --- Domain keyword → tag mismatch (soft warning) ---
+    # Emit soft warnings when the scenario title hints at a domain but lacks
+    # the corresponding tag.  These are NON-BLOCKING — they never set
+    # ``hook_failed`` and do NOT break CI.
+    kw_warnings = check_domain_title_keywords(
+        set(scenario.effective_tags), scenario.name
+    )
+    for msg in kw_warnings:
+        _domain_warning(msg)
+
    # Clear the process-global set of already-initialised DB paths so
    # that stale entries from the previous scenario cannot leak into this
    # one.  Each scenario receives fresh temp-DB paths, so old entries are
@@ -0,0 +1,149 @@
+"""Step definitions for BDD domain-tag enforcement scenarios.
+
+Tests the ``validate_domain_tags()`` and ``check_domain_title_keywords()``
+helper functions defined in ``features/environment.py``.
+
+All step names are prefixed with ``domain tags`` or ``domain warnings`` to
+avoid ``AmbiguousStep`` conflicts with existing step definitions.
+
+See CONTRIBUTING.md > BDD Domain Tagging for the one-tag-per-domain specification.
+"""
+
+from __future__ import annotations
+
+from behave import given, then, when
+from behave.runner import Context
+
+from features.environment import (
+    check_domain_title_keywords,
+    validate_domain_tags,
+)
+from features.mocks.tdd_test_helpers import make_mock_scenario
+
+# ---------------------------------------------------------------------------
+# Tag-set construction helpers
+# ---------------------------------------------------------------------------
+
+
+@given('domain tags a tag set with "{tags_csv}"')
+def step_given_tag_set(context: Context, tags_csv: str) -> None:
+    """Parse a comma-separated tag list into a set on the context."""
+    context.domain_tag_set = {t.strip() for t in tags_csv.split(",") if t.strip()}
+
+
+@given("domain tags an empty tag set")
+def step_given_empty_tag_set(context: Context) -> None:
+    context.domain_tag_set = set()
+
+
+# ---------------------------------------------------------------------------
+# Scenario name builder
+# ---------------------------------------------------------------------------
+
+
+@given('domain tags I have a scenario named "{scenario_name}"')
+def step_given_scenario_name(context: Context, scenario_name: str) -> None:
+    context.domain_scenario_name = scenario_name
+
+
+# ---------------------------------------------------------------------------
+# Validation execution — validate_domain_tags()
+# ---------------------------------------------------------------------------
+
+
+@when("domain tags I validate the domain tags")
+def step_when_validate_domain(context: Context) -> None:
+    """Run ``validate_domain_tags`` and capture any raised ``ValueError``."""
+    context.domain_validation_error = None
+    try:
+        validate_domain_tags(context.domain_tag_set)
+    except ValueError as exc:
+        context.domain_validation_error = str(exc)
+
+
+# ---------------------------------------------------------------------------
+# Validation outcome assertions
+# ---------------------------------------------------------------------------
+
+
+@then("domain tags domain validation should pass")
+def step_then_domain_validation_passes(context: Context) -> None:
+    assert context.domain_validation_error is None, (
+        f"Expected validation to pass but got error: {context.domain_validation_error}"
+    )
+
+
+@then('domain tags domain validation should fail with error containing "{fragment}"')
+def step_then_domain_validation_fails_with(context: Context, fragment: str) -> None:
+    assert context.domain_validation_error is not None, (
+        "Expected validation to fail but it passed"
+    )
+    assert fragment in context.domain_validation_error, (
+        f"Expected error to contain '{fragment}' but got: {context.domain_validation_error}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Soft-warning execution — check_domain_title_keywords()
+# ---------------------------------------------------------------------------
+
+
+@when("domain tags I check the scenario name for missing domain keywords")
+def step_when_check_keywords(context: Context) -> None:
+    """Run ``check_domain_title_keywords`` and capture warnings."""
+    context.domain_warnings = check_domain_title_keywords(
+        context.domain_tag_set, context.domain_scenario_name
+    )
+
+
+# ---------------------------------------------------------------------------
+# Soft-warning outcome assertions
+# ---------------------------------------------------------------------------
+
+
+@then("domain tags the keyword warning list should be empty")
+def step_then_keyword_warnings_empty(context: Context) -> None:
+    assert context.domain_warnings == [], (
+        f"Expected no warnings but got: {context.domain_warnings}"
+    )
+
+
+@then(
+    'domain tags a keyword warning should mention "{keyword}" but is missing the "@{tag}" tag'
+)
+def step_then_keyword_warning_includes(
+    context: Context, keyword: str, tag: str
+) -> None:
+    assert len(context.domain_warnings) >= 1, "Expected at least one warning"
+    found = any(keyword in w and f"@{tag}" in w for w in context.domain_warnings)
+    assert found is True, (
+        f"Expected a warning about '{keyword}' missing '@{tag}', got: {context.domain_warnings}"
+    )
+
+
+@then("domain tags the number of keyword warnings should be {count:d}")
+def step_then_keyword_warning_count(context: Context, count: int) -> None:
+    assert len(context.domain_warnings) == count, (
+        f"Expected {count} warning(s), got {len(context.domain_warnings)}: {context.domain_warnings}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Mock-domain scenario builders for edge cases
+# ---------------------------------------------------------------------------
+
+
+@given("domain inversion a mock domain scenario with empty tags")
+def step_given_domain_empty_tags_scenario(context: Context) -> None:
+    context.domain_mock_scenario = make_mock_scenario(
+        tags=[],
+        steps_passed=True,
+    )
+
+
+@given("domain inversion a mock domain scenario that passes with @a2a tag")
+def step_given_a2a_passing_scenario(context: Context) -> None:
+    context.domain_mock_scenario = make_mock_scenario(
+        tags=["a2a"],
+        steps_passed=True,
+    )
@@ -0,0 +1,126 @@
+@mock_only
+Feature: BDD domain-tag enforcement
+  As a CleverAgents developer writing BDD/Behave tests
+  I want strict one-tag-per-domain enforcement for @a2a, @session, and @cli tags
+  So that misconfigured test scenarios are caught before they run
+
+  # Tests for the validate_domain_tags() and check_domain_title_keywords()
+  # helper functions defined in features/environment.py.
+  # See CONTRIBUTING.md > BDD Domain Tagging for the specification.
+
+  # --- validate_domain_tags: empty tag set (valid) ---
+
+  Scenario: Empty tag set passes validation
+    Given domain tags an empty tag set
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should pass
+
+  # --- validate_domain_tags: single-domain tags (all valid) ---
+
+  Scenario: Single @a2a tag passes validation
+    Given domain tags a tag set with "a2a"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should pass
+
+  Scenario: Single @session_repo tag passes validation
+    Given domain tags a tag set with "session_repo"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should pass
+
+  Scenario: Single @cli tag passes validation
+    Given domain tags a tag set with "cli"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should pass
+
+  # --- validate_domain_tags: allowed cross-domain (@session + @cli) ---
+
+  Scenario: Allowed combination @session_repo + @cli passes validation
+    Given domain tags a tag set with "session_repo, cli"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should pass
+
+  # --- validate_domain_tags: forbidden combinations involving @a2a ---
+
+  Scenario: Forbidden @a2a + @session combination raises ValueError
+    Given domain tags a tag set with "a2a, session"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should fail with error containing "@a2a"
+
+  Scenario: Forbidden @a2a + @cli combination raises ValueError
+    Given domain tags a tag set with "a2a, cli"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should fail with error containing "@a2a"
+
+  Scenario: Forbidden @a2a + @session_repo combination raises ValueError
+    Given domain tags a tag set with "a2a, session_repo"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should fail with error containing "@a2a"
+
+  Scenario: Forbidden @a2a + @cli + other tags raises ValueError
+    Given domain tags a tag set with "a2a, cli, wip"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should fail with error containing "@a2a"
+
+  # --- check_domain_title_keywords: soft warnings ---
+
+  Scenario: Missing @a2a tag warning when title contains "A2A agent" but no a2a tag
+    Given domain tags an empty tag set
+    And domain tags I have a scenario named "A2A agent discovery should list all registered agents"
+    When domain tags I check the scenario name for missing domain keywords
+    Then domain tags a keyword warning should mention "A2A agent" but is missing the "@a2a" tag
+
+  Scenario: Missing @cli tag when title has CLI keyword and CLI tag IS present — no warning
+    Given domain tags a tag set with "cli"
+    And domain tags I have a scenario named "CLI invocation should persist output to disk"
+    When domain tags I check the scenario name for missing domain keywords
+    Then domain tags the keyword warning list should be empty
+
+  Scenario: Missing @session tag when title contains "active session" but no session tag
+    Given domain tags a tag set with "cli"
+    And domain tags I have a scenario named "Active session list should show all open sessions"
+    When domain tags I check the scenario name for missing domain keywords
+    Then domain tags a keyword warning should mention "active session" but is missing the "@session" tag
+
+  # --- check_domain_title_keywords: zero warnings when all tags present ---
+
+  Scenario: Named combined tags covering all matched keywords yields no warnings
+    Given domain tags a tag set with "session_repo, cli"
+    And domain tags I have a scenario named "Active session lifecycle through CLI commands"
+    When domain tags I check the scenario name for missing domain keywords
+    Then domain tags the keyword warning list should be empty
+
+  Scenario: Non-domain title produces no warnings regardless of tags
+    Given domain tags a tag set with "wip, slow"
+    And domain tags I have a scenario named "Refactor legacy config parser utilities"
+    When domain tags I check the scenario name for missing domain keywords
+    Then domain tags the keyword warning list should be empty
+
+  # --- check_domain_title_keywords: multiple keywords warning count ---
+
+  Scenario: Multiple missing keywords produce multiple warnings
+    Given domain tags an empty tag set
+    And domain tags I have a scenario named "A2A agent session CLI orchestration"
+    When domain tags I check the scenario name for missing domain keywords
+    Then domain tags the number of keyword warnings should be 3
+
+  # --- validate_domain_tags: additional edge case — multiple cli tags ---
+
+  Scenario: Two @session variants without @cli pass validation via session + cli rule
+    Given domain tags a tag set with "session_repo, session_feature"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should pass
+
+  # --- validate_domain_tags: forbidden — @a2a + two others ---
+
+  Scenario: Triple mix with @a2a raises ValueError mentioning all three domains
+    Given domain tags a tag set with "a2a, session, cli"
+    When domain tags I validate the domain tags
+    Then domain tags domain validation should fail with error containing "@a2a"
+
+  # --- check_domain_title_keywords: keyword without mapping edge case ---
+
+  Scenario: Non-mapped keyword in title does not produce a warning for unknown mapping
+    Given domain tags a tag set with "wip"
+    And domain tags I have a scenario named "agent-to-agent session recovery fallback"
+    When domain tags I check the scenario name for missing domain keywords
+    Then domain tags the number of keyword warnings should be 2