specsmith 0.18.0.dev710__tar.gz → 0.19.0.dev726__tar.gz

{specsmith-0.18.0.dev710/src/specsmith.egg-info → specsmith-0.19.0.dev726}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.18.0.dev710
+Version: 0.19.0.dev726
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.18.0.dev710"
+version = "0.19.0.dev726"
 description = "AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider."
 readme = "README.md"
 license = "MIT"

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import version as _pkg_version
 try:
     __version__: str = _pkg_version("specsmith")
 except PackageNotFoundError:  # running from source without install
-    __version__ = "0.18.0"  # fallback: keep in sync with pyproject.toml
+    __version__ = "0.19.0"  # fallback: keep in sync with pyproject.toml

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/agent/broker.py

@@ -89,12 +89,19 @@ _DESTRUCTIVE_PATTERNS = (
 )
 
 _RELEASE_PATTERNS = (
-    re.compile(r"\brelease\b", re.IGNORECASE),
+    # Explicit release execution verbs — never matches tooling edits (REQ-430)
     re.compile(r"\bship\b", re.IGNORECASE),
     re.compile(r"\bpublish\s+(to\s+)?pypi\b", re.IGNORECASE),
     re.compile(r"\btag\s+v?\d", re.IGNORECASE),
     re.compile(r"\bbump\s+(the\s+)?version\b", re.IGNORECASE),
+    # "cut/do/make/create/publish a release" — execution intent only
+    re.compile(r"\b(cut|do|make|create|publish)\s+(a\s+|the\s+)?release\b", re.IGNORECASE),
+    # "release vX.Y" or "release 1.2.3" — version-tagged releases
+    re.compile(r"\brelease\s+v?\d+[\d\.]*\b", re.IGNORECASE),
 )
+# NOTE: bare "\brelease\b" was intentionally removed (REQ-430).  Edits to
+# release.yml, packaging scripts, release pipelines, and release docs must
+# fall through to _CHANGE_PATTERNS so scope-matching can accept them.
 
 _REFACTOR_PATTERNS = (
     re.compile(r"\b(refactor|rewrite|extract|reorganise|reorganize|restructure)\b", re.IGNORECASE),
@@ -109,7 +116,7 @@ _CHANGE_PATTERNS = (
     re.compile(r"\b(fix|repair|patch)\b", re.IGNORECASE),
     re.compile(r"\b(add|implement|create|introduce|build)\b", re.IGNORECASE),
     re.compile(r"\b(rename)\b", re.IGNORECASE),
-    re.compile(r"\b(update|migrate|upgrade)\b", re.IGNORECASE),
+    re.compile(r"\b(update|migrate|upgrade|edit)\b", re.IGNORECASE),
     re.compile(r"\b(remove|delete)\s+(the\s+)?(unused|stale|legacy)\b", re.IGNORECASE),
 )
 
@@ -324,6 +331,7 @@ def infer_scope(
     repo_index_path: Path | None = None,
     *,
     top_k: int = 3,
+    min_score: float = 0.15,
 ) -> ScopeProposal:
     """Infer the project scope affected by a natural-language utterance.
 
@@ -347,6 +355,7 @@ def infer_scope(
         denom = max(1, min(len(tokens), len(req_tokens)))
         scored.append((overlap / denom, req))
     scored.sort(key=lambda x: -x[0])
+    scored = [(s, r) for s, r in scored if s >= min_score]
     top_reqs = [r for _, r in scored[:top_k]]
 
     # File matches from .repo-index/files.json (best-effort, optional).

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/agent/runner.py

@@ -608,6 +608,7 @@ class AgentRunner:
 
         # Write token_metric to ESDB (REQ-410) — best-effort, never blocks.
         if tokens_in or tokens_out:
+            model_name = str(getattr(result, "provider", "") if result else "")
             try:
                 from specsmith.esdb_writer import write_token_metric
 
@@ -616,12 +617,27 @@ class AgentRunner:
                     input_tokens=tokens_in,
                     output_tokens=tokens_out,
                     cost_usd=cost_usd,
-                    model=str(getattr(result, "provider", "") if result else ""),
+                    model=model_name,
                     command_source=activity or "chat",
                     work_item_id=str(getattr(self._state, "active_work_item_id", "") or ""),
                 )
             except Exception:  # noqa: BLE001
                 pass
+            # Flush token usage to session_metrics.jsonl (REQ-436)
+            try:
+                from specsmith.project_metrics import flush_session_metrics  # noqa: PLC0415
+
+                flush_session_metrics(
+                    Path(self.project_dir),
+                    work_item_id=str(getattr(self._state, "active_work_item_id", "") or ""),
+                    model=model_name,
+                    input_tokens=tokens_in,
+                    output_tokens=tokens_out,
+                    cost_usd=cost_usd,
+                    command=activity or "chat",
+                )
+            except Exception:  # noqa: BLE001
+                pass
 
         if result is not None:
             self._history.append({"role": "user", "text": utterance})

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/auditor.py

@@ -316,6 +316,76 @@ def check_governance_files(root: Path) -> list[AuditResult]:
     return results
 
 
+def check_governance_yaml_content(root: Path) -> list[AuditResult]:
+    """Validate .specsmith/governance/*.yaml files are not empty/fallback-only."""
+    results: list[AuditResult] = []
+    gov_dir = root / ".specsmith" / "governance"
+    if not gov_dir.is_dir():
+        return results
+
+    import yaml
+
+    for yaml_path in sorted(gov_dir.glob("*.yaml")):
+        stem = yaml_path.stem
+        check_name = f"governance-yaml:{stem}"
+        try:
+            loaded = yaml.safe_load(yaml_path.read_text(encoding="utf-8")) or {}
+        except Exception as exc:  # noqa: BLE001
+            results.append(
+                AuditResult(
+                    name=check_name,
+                    passed=False,
+                    message=f"{yaml_path.name} failed to parse as YAML: {exc}",
+                )
+            )
+            continue
+
+        section = loaded.get(stem) if isinstance(loaded, dict) else None
+        if not isinstance(section, list):
+            results.append(
+                AuditResult(
+                    name=check_name,
+                    passed=False,
+                    message=(f"{yaml_path.name} missing expected top-level list key '{stem}'"),
+                )
+            )
+            continue
+
+        if not section:
+            results.append(
+                AuditResult(
+                    name=check_name,
+                    passed=False,
+                    message=f"{yaml_path.name} has an empty '{stem}' list",
+                )
+            )
+            continue
+
+        if (
+            len(section) == 1
+            and isinstance(section[0], dict)
+            and set(section[0].keys()) == {"note"}
+        ):
+            results.append(
+                AuditResult(
+                    name=check_name,
+                    passed=False,
+                    message=(f"{yaml_path.name} only contains migration fallback note (m001)"),
+                )
+            )
+            continue
+
+        results.append(
+            AuditResult(
+                name=check_name,
+                passed=True,
+                message=f"{yaml_path.name} contains structured '{stem}' entries",
+            )
+        )
+
+    return results
+
+
 # ---------------------------------------------------------------------------
 # Requirement ↔ Test consistency
 # ---------------------------------------------------------------------------
@@ -347,22 +417,13 @@ def check_req_test_consistency(root: Path) -> list[AuditResult]:
     test_candidates = _get_test_spec_paths(root)
     test_path = next((p for p in test_candidates if p.exists()), None)
 
-    if test_path is None:
-        results.append(
-            AuditResult(
-                name="req-test-consistency",
-                passed=True,
-                message="Skipped: test spec file not found",
-            )
-        )
-        return results
-
     # In YAML-first mode load REQ IDs from the JSON machine state so we don't
     # depend on docs/REQUIREMENTS.md being present or up to date (#174).
     import contextlib as _contextlib
     import json as _json_local
 
     _reqs_json = root / ".specsmith" / "requirements.json"
+    _tests_json = root / ".specsmith" / "testcases.json"
     _yaml_req_ids: set[str] | None = None
     if _reqs_json.is_file():
         with _contextlib.suppress(OSError, ValueError):
@@ -378,9 +439,18 @@ def check_req_test_consistency(root: Path) -> list[AuditResult]:
             )
         )
         return results
+    if test_path is None and not _tests_json.is_file():
+        results.append(
+            AuditResult(
+                name="req-test-consistency",
+                passed=True,
+                message="Skipped: test spec file and testcases.json not found",
+            )
+        )
+        return results
 
     req_text = req_path.read_text(encoding="utf-8") if req_path.exists() else ""
-    test_text = test_path.read_text(encoding="utf-8")
+    test_text = test_path.read_text(encoding="utf-8") if test_path else ""
 
     # Only check coverage for non-Draft requirements.
     # Draft requirements are stubs (e.g. auto-generated by import) and don't
@@ -405,7 +475,6 @@ def check_req_test_consistency(root: Path) -> list[AuditResult]:
 
     # In YAML-first mode, also collect coverage from testcases.json requirement_id fields
     # and from the test_ids list embedded in requirements.json records (#REQ-379 followup).
-    _tests_json = root / ".specsmith" / "testcases.json"
     if _tests_json.is_file():
         with _contextlib.suppress(OSError, ValueError):
             _test_records = _json_local.loads(_tests_json.read_text(encoding="utf-8"))
@@ -1458,6 +1527,7 @@ def run_audit(root: Path) -> AuditReport:
     """Run all audit checks and return a report."""
     report = AuditReport()
     report.results.extend(check_governance_files(root))
+    report.results.extend(check_governance_yaml_content(root))
     report.results.extend(check_req_test_consistency(root))
     report.results.extend(check_ledger_health(root))
     report.results.extend(check_context_size(root))

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/cli.py

@@ -760,6 +760,19 @@ def audit(fix: bool, project_dir: str) -> None:
         "Overrides .specsmith/config.yml epistemic.confidence_threshold for this call."
     ),
 )
+@click.option(
+    "--req",
+    "hint_req_ids",
+    multiple=True,
+    default=(),
+    metavar="REQ-NNN",
+    help=(
+        "Inject an explicit requirement ID into the utterance (repeatable). "
+        "Useful for release/destructive intents where the broker asks for clarification: "
+        "'specsmith preflight \"update release.yml\" --req REQ-051' "
+        "appends the ID so scope-matching can accept it (REQ-431)."
+    ),
+)
 def preflight_cmd(
     utterance: str,
     project_dir: str,
@@ -768,6 +781,7 @@ def preflight_cmd(
     stress: bool,
     predict_only: bool,
     escalate_threshold: float | None,
+    hint_req_ids: tuple[str, ...],
 ) -> None:
     """Classify a natural-language utterance under Specsmith governance (REQ-085).
 
@@ -784,6 +798,15 @@ def preflight_cmd(
     from specsmith.governance_logic import run_preflight
 
     root = Path(project_dir).resolve()
+
+    # REQ-431: --req flags inject explicit REQ IDs into the utterance so the
+    # governance_logic explicit-ID extractor (line ~149) picks them up.  This
+    # lets the user escape release/destructive needs_clarification dead-ends by
+    # naming a known requirement without having to reword the whole utterance.
+    if hint_req_ids:
+        req_suffix = " ".join(r.upper() for r in hint_req_ids if r.strip())
+        utterance = f"{utterance} [{req_suffix}]"
+
     # REQ-418: delegate the decision to the authoritative broker so explicit
     # REQ-NNN ids and .specsmith/requirements.json drive the result.  run_preflight
     # also applies the REQ-098 floor, allocates/persists the work item (unless
@@ -1129,6 +1152,20 @@ def verify_cmd(
         if equilibrium and confidence >= threshold
         else classify_retry_strategy(fake_report, fake_decision)
     )
+    # Wire equilibrium back to WI lifecycle (REQ-434)
+    if equilibrium and work_item_id:
+        try:
+            from specsmith.governance_logic import run_verify as _gov_verify
+
+            _gov_verify(
+                diff=payload_in.get("diff", ""),
+                files_changed=files_changed,
+                test_results=test_results,
+                project_dir=str(root),
+                work_item_id=work_item_id,
+            )
+        except Exception:  # noqa: BLE001
+            pass  # best-effort; never block verify output
 
     out = {
         "equilibrium": equilibrium,
@@ -4011,9 +4048,15 @@ def checkpoint_cmd(project_dir: str, as_json: bool) -> None:
         pass
 
     # ── ESDB ──────────────────────────────────────────────────────────────────
-    esdb_ok, esdb_records = True, 0
+    # Three possible states (REQ-429):
+    #   "chronomemory" — commercial ChronoStore backend, WAL present
+    #   "sqlite"       — free SQLite backend (chronomemory absent or WAL missing)
+    #   "n/a"          — no ESDB artefact found at all
+    esdb_ok: bool = True
+    esdb_records: int = 0
+    esdb_backend: str = "n/a"
     try:
-        from chronomemory import ChronoStore
+        from chronomemory import ChronoStore  # noqa: PLC0415
 
         wal = root / ".chronomemory" / "events.wal"
         if wal.exists():
@@ -4023,9 +4066,24 @@ def checkpoint_cmd(project_dir: str, as_json: bool) -> None:
                 # value that is not the literal False as valid.
                 esdb_ok = store.chain_valid() is not False
                 esdb_records = store.record_count()
+            esdb_backend = "chronomemory"
     except Exception:  # noqa: BLE001
         pass
 
+    if esdb_backend == "n/a":
+        # chronomemory not available or WAL absent — try SQLite (free default)
+        try:
+            from specsmith.esdb.sqlite_store import SqliteStore  # noqa: PLC0415
+
+            db = root / ".specsmith" / "esdb.sqlite3"
+            if db.exists():
+                with SqliteStore(root) as store:
+                    esdb_ok = store.chain_valid()
+                    esdb_records = store.record_count()
+                esdb_backend = "sqlite"
+        except Exception:  # noqa: BLE001
+            pass
+
     # ── Recent work items + last preflight from LEDGER.md ─────────────────────
     recent_wis: list[str] = []
     last_preflight = ""
@@ -4060,8 +4118,9 @@ def checkpoint_cmd(project_dir: str, as_json: bool) -> None:
         "audit_failed": audit_failed,
         "req_count": req_count,
         "test_count": test_count,
-        "esdb_records": esdb_records,
-        "esdb_chain_valid": esdb_ok,
+        "esdb_backend": esdb_backend,
+        "esdb_records": esdb_records if esdb_backend != "n/a" else None,
+        "esdb_chain_valid": esdb_ok if esdb_backend != "n/a" else None,
         "recent_wis": recent_wis,
         "last_preflight": last_preflight,
         "anchor": f"SPECSMITH-ANCHOR-{ts}",
@@ -4078,6 +4137,14 @@ def checkpoint_cmd(project_dir: str, as_json: bool) -> None:
     vbar = "\u2551"  # ║
     health_icon = "\u2713" if health_ok else "\u2717"
     esdb_icon = "\u2713" if esdb_ok else "\u2717"
+    if esdb_backend == "chronomemory":
+        esdb_field = f"ESDB: {esdb_records} records ({esdb_icon} chain)"
+    elif esdb_backend == "sqlite":
+        # Compact format keeps the row within the 57-char box interior.
+        # " REQs    : NNN   TESTs: NNN   " = 30 chars, leaving 27 for esdb_field.
+        esdb_field = f"ESDB: SQLite {esdb_records} recs {esdb_icon}"
+    else:
+        esdb_field = "ESDB: N/A"
     wi_str = ", ".join(recent_wis) if recent_wis else "none seen"
 
     def _arow(rich: str, plain: str, wide: int = 0) -> str:
@@ -4115,10 +4182,7 @@ def checkpoint_cmd(project_dir: str, as_json: bool) -> None:
     )
     console.print(_arow(r4_rich, r4_plain))
 
-    r5 = (
-        f" REQs    : {req_count}   TESTs: {test_count}"
-        f"   ESDB: {esdb_records} records ({esdb_icon} chain)"
-    )
+    r5 = f" REQs    : {req_count}   TESTs: {test_count}   {esdb_field}"
     console.print(_arow(r5, r5))
 
     r6 = f" WIs     : {wi_str}"
@@ -9225,6 +9289,30 @@ def wi_show_cmd(wi_id: str, project_dir: str, as_json: bool) -> None:
         console.print(f"  Reason    : {item.closed_reason}")
 
 
+@wi_group.command(name="link-test")
+@click.argument("wi_id")
+@click.option(
+    "--test",
+    "test_ids",
+    multiple=True,
+    required=True,
+    metavar="TEST-NNN",
+    help="Test case ID to link (repeatable).",
+)
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def wi_link_test_cmd(wi_id: str, test_ids: tuple[str, ...], project_dir: str) -> None:
+    """Link one or more test case IDs to a work item."""
+    from specsmith.wi_store import WorkItemStore
+
+    root = Path(project_dir).resolve()
+    store = WorkItemStore(root)
+    item = store.add_test_case_ids(wi_id.upper(), list(test_ids))
+    if item is None:
+        console.print(f"[red]Work item {wi_id!r} not found.[/red]")
+        raise SystemExit(1)
+    console.print(f"[green]\u2713[/green] {item.id} linked tests: {', '.join(test_ids)}")
+
+
 @wi_group.command(name="close")
 @click.argument("wi_id")
 @click.option("--project-dir", type=click.Path(exists=True), default=".")

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/commands/issues_policy.py

@@ -93,6 +93,8 @@ def register_issue_policy_commands(main: click.Group, console: Any) -> None:
         project_dir: str,
         as_json: bool,
     ) -> None:
+        from specsmith.wi_store import _now_iso
+
         record = record_approval(
             Path(project_dir).resolve(),
             approval_type=approval_type,
@@ -101,6 +103,16 @@ def register_issue_policy_commands(main: click.Group, console: Any) -> None:
             scope=scope,
             requirement_ids=list(requirements),
         )
+        # Update human_review_status to 'approved' (REQ-434)
+        try:
+            store = WorkItemStore(Path(project_dir).resolve())
+            item = store.get(work_item_id)
+            if item is not None:
+                item.human_review_status = "approved"
+                item.updated_at = _now_iso()
+                store.upsert(item)
+        except Exception:  # noqa: BLE001
+            pass
         if as_json:
             click.echo(json.dumps(record.to_dict(), indent=2))
         else:

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/governance_logic.py

@@ -119,6 +119,7 @@ def run_preflight(
         utterance,
         _req_md,
         repo_index_path=_repo_idx,
+        min_score=0.15,
     )
 
     requirement_ids = [r.req_id for r in scope.matched_requirements]
@@ -202,12 +203,25 @@ def run_preflight(
         )
         confidence_target = 0.9
     elif intent == Intent.RELEASE:
-        decision_str = "needs_clarification"
-        instruction = (
-            "Release operations require explicit confirmation. "
-            "Specify the target version and channel."
-        )
-        confidence_target = 0.9
+        # Accept if scope is known or explicit REQ IDs are present (REQ-431).
+        # This handles release-tooling edits that survived the narrowed classifier
+        # (e.g. the user cited REQ-050 or REQ-051 explicitly, or the utterance
+        # matched a release-management requirement via token overlap).
+        if requirement_ids or scope.is_known:
+            decision_str = "accepted"
+            instruction = (
+                "Release-adjacent change under known governance scope. "
+                "Proceed under Specsmith verification."
+            )
+            confidence_target = 0.85
+        else:
+            decision_str = "needs_clarification"
+            instruction = (
+                "Release operations require explicit confirmation. "
+                "Specify the target version and channel, or cite a release-management "
+                "requirement via --req REQ-050 / --req REQ-051."
+            )
+            confidence_target = 0.9
     elif intent == Intent.REFACTOR:
         # Refactoring accepted only if scope is matched; unmatched refactors
         # get needs_clarification because scope creep is the primary risk.
@@ -251,11 +265,13 @@ def run_preflight(
     if cfg_threshold is not None and cfg_threshold > confidence_target:
         confidence_target = cfg_threshold
 
-    work_item_id = (
-        f"WI-{uuid.uuid4().hex[:8].upper()}"
-        if (decision_str == "accepted" and not predict_only)
-        else ""
+    # Allocate a WI for accepted decisions AND for needs_clarification on
+    # RELEASE/DESTRUCTIVE intents (REQ-431) so `specsmith approve --work-item`
+    # can proceed after the user provides the requested context out-of-band.
+    _alloc_wi = decision_str == "accepted" or (
+        decision_str == "needs_clarification" and intent in (Intent.RELEASE, Intent.DESTRUCTIVE)
     )
+    work_item_id = f"WI-{uuid.uuid4().hex[:8].upper()}" if (_alloc_wi and not predict_only) else ""
 
     payload: dict[str, Any] = {
         "decision": decision_str,
@@ -402,7 +418,9 @@ def run_verify(
         try:
             from specsmith.wi_store import WorkItemStore
 
-            WorkItemStore(root).mark_implemented(work_item_id)
+            store = WorkItemStore(root)
+            store.mark_implemented(work_item_id)
+            store.set_files_touched(work_item_id, files_changed)
         except Exception:  # noqa: BLE001
             pass
 

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/migrations/__init__.py

@@ -40,6 +40,7 @@ class MigrationResult:
     message: str = ""
     files_created: list[str] = field(default_factory=list)
     files_modified: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
     error: str = ""
 
     def to_dict(self) -> dict[str, Any]:
@@ -51,6 +52,7 @@ class MigrationResult:
             "message": self.message,
             "files_created": self.files_created,
             "files_modified": self.files_modified,
+            "warnings": self.warnings,
             "error": self.error,
         }
 

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/migrations/m001_governance_yaml.py

@@ -49,7 +49,10 @@ class GovernanceYamlMigration(Migration):
             yaml_path = gov_dir / yaml_name
 
             if not md_path.exists():
-                continue  # Skip if source doesn't exist
+                result.warnings.append(
+                    f"Missing source_md for {yaml_name}: docs/governance/{md_name}"
+                )
+                continue
 
             if yaml_path.exists():
                 continue  # Already migrated — skip

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/project_metrics.py

@@ -364,3 +364,31 @@ class MetricsStore:
             "since": since,
             "until": until,
         }
+
+
+def flush_session_metrics(
+    root: Path,
+    *,
+    work_item_id: str = "",
+    model: str = "",
+    input_tokens: int = 0,
+    output_tokens: int = 0,
+    cost_usd: float = 0.0,
+    command: str = "chat",
+) -> None:
+    """Append a MetricsRecord from LLM usage data captured in runner.py (REQ-436).
+    Best-effort: never raises."""
+    try:
+        store = MetricsStore(root)
+        rec = MetricsRecord.new(
+            command=command,
+            passed=True,
+            work_item_id=work_item_id,
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_usd=cost_usd,
+        )
+        store.append(rec)
+    except Exception:  # noqa: BLE001
+        pass

{specsmith-0.18.0.dev710 → specsmith-0.19.0.dev726}/src/specsmith/sync.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 import contextlib
 import json
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Protocol, cast
 
@@ -182,6 +182,11 @@ def parse_tests_md(text: str) -> list[dict[str, Any]]:
 # ---------------------------------------------------------------------------
 
 
+@dataclass
+class SyncWarning:
+    message: str
+
+
 @dataclass
 class SyncResult:
     reqs_before: int
@@ -191,6 +196,7 @@ class SyncResult:
     reqs_changed: bool
     tests_changed: bool
     dry_run: bool
+    warnings: list[SyncWarning] = field(default_factory=list)
 
     @property
     def changed(self) -> bool:
@@ -436,6 +442,7 @@ def run_sync(root: Path, *, dry_run: bool = False) -> SyncResult:
     tests_md_path = root / "docs" / "TESTS.md"
     reqs_json_path = state_dir / "requirements.json"
     tests_json_path = state_dir / "testcases.json"
+    sync_warnings: list[SyncWarning] = []
     if not dry_run:
         normalize_esdb_gitignore_policy(root)
 
@@ -443,6 +450,8 @@ def run_sync(root: Path, *, dry_run: bool = False) -> SyncResult:
         # ── YAML-first mode ─────────────────────────────────────────────────
         new_reqs = load_yaml_requirements(root)
         new_tests = load_yaml_tests(root)
+        yaml_req_ids = {str(r["id"]) for r in new_reqs if str(r.get("id", "")).strip()}
+        yaml_test_ids = {str(t["id"]) for t in new_tests if str(t.get("id", "")).strip()}
 
         # REQ-358: If YAML mode has no YAML files but REQUIREMENTS.md has content,
         # fall back to Markdown parsing rather than silently producing an empty state.
@@ -499,6 +508,36 @@ def run_sync(root: Path, *, dry_run: bool = False) -> SyncResult:
             }
             for t in new_tests
         ]
+        if reqs_md_path.exists():
+            reqs_md_ids = {
+                r["id"]
+                for r in parse_requirements_md(reqs_md_path.read_text(encoding="utf-8"))
+                if str(r.get("id", "")).strip()
+            }
+            for req_id in sorted(reqs_md_ids - yaml_req_ids):
+                sync_warnings.append(
+                    SyncWarning(
+                        message=(
+                            f"{req_id} found in docs/REQUIREMENTS.md but missing from "
+                            "docs/requirements/*.yml — add it to a YAML file and re-run sync."
+                        )
+                    )
+                )
+        if tests_md_path.exists():
+            tests_md_ids = {
+                t["id"]
+                for t in parse_tests_md(tests_md_path.read_text(encoding="utf-8"))
+                if str(t.get("id", "")).strip()
+            }
+            for test_id in sorted(tests_md_ids - yaml_test_ids):
+                sync_warnings.append(
+                    SyncWarning(
+                        message=(
+                            f"{test_id} found in docs/TESTS.md but missing from "
+                            "docs/tests/*.yml — add it to a YAML file and re-run sync."
+                        )
+                    )
+                )
     else:
         # ── Legacy Markdown mode (DEPRECATED — REQ-373) ──────────────────────
         # Markdown mode will be removed in a future release.
@@ -614,6 +653,7 @@ def run_sync(root: Path, *, dry_run: bool = False) -> SyncResult:
         reqs_changed=reqs_changed,
         tests_changed=tests_changed,
         dry_run=dry_run,
+        warnings=sync_warnings,
     )