codd-dev 2.48.0__tar.gz → 2.50.0__tar.gz

{codd_dev-2.48.0 → codd_dev-2.50.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.48.0
+Version: 2.50.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev

{codd_dev-2.48.0 → codd_dev-2.50.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.48.0"
+__version__ = "2.50.0"

{codd_dev-2.48.0 → codd_dev-2.50.0}/codd/contracts_registry/registry.py

@@ -231,11 +231,15 @@ _COVERED: tuple[Contract, ...] = (
         finding_ids=("PC-docref-resolution",),
     ),
     # ── authenticity.observable_in_supported_stack.v1 (GPT r2 §3.6) ──────────
-    # The NEW hard gate: a marker-bearing file the adapter RECOGNIZES but parses
-    # ZERO executable test blocks out of was silently degraded to a pass (only an
-    # UNSUPPORTED file should degrade). strict_observability=True (greenfield Gate 2)
-    # makes it an unobservable_test_structure violation — an unparseable test in a
-    # SUPPORTED stack is a false-green, not an unsupported one.
+    # The hard gate, NARROWED to HARNESS-OWNED files: a marker-bearing file the
+    # adapter RECOGNIZES but parses ZERO executable test blocks out of is a
+    # false-green CoDD owns ONLY when CoDD itself generated it (it carries a
+    # ``@generated-by: codd …`` provenance header). strict_observability=True
+    # (greenfield Gate 2) makes THAT an unobservable_test_structure violation. A
+    # USER/CUSTOM recognized-extension file with no provenance header DEGRADES —
+    # our block-parser's incompleteness (a Mocha variant, a decorated/wrapped test
+    # style) must not hard-RED a user's valid-but-unparsed-by-us test. An
+    # UNSUPPORTED file (no adapter) also degrades. Never a false-RED.
     Contract(
         id="authenticity.observable_in_supported_stack.v1",
         source_node="TestFile",
@@ -247,6 +251,8 @@ _COVERED: tuple[Contract, ...] = (
         status="covered",
         certification_fixtures=(
             "tests/test_vb_marker_authenticity.py::test_strict_observability_flags_recognized_file_with_no_parseable_test",
+            "tests/test_vb_marker_authenticity.py::test_strict_observability_user_file_degrades_not_red",
+            "tests/test_vb_marker_authenticity.py::test_strict_observability_harness_owned_spoof_is_red",
             "tests/test_vb_marker_authenticity.py::test_strict_observability_still_degrades_unsupported_stack",
             "tests/test_vb_marker_authenticity.py::test_strict_observability_does_not_affect_genuine_covering_test",
         ),

{codd_dev-2.48.0 → codd_dev-2.50.0}/codd/generator.py

@@ -607,33 +607,144 @@ def generate_wave(
         if output_path.exists() and not force:
             results.append(GenerationResult(node_id=artifact.node_id, path=output_path, status="skipped"))
             continue
-
-        dependency_documents = _load_dependency_documents(project_root, artifact.depends_on, document_node_paths)
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        combined_conventions = deepcopy(global_conventions) + deepcopy(artifact.conventions)
-        content = _render_document(
-            artifact=artifact,
-            global_conventions=global_conventions,
-            depended_by=depended_by_map.get(artifact.node_id, []),
-            body=_generate_document_body(
+        results.append(
+            _generate_one_artifact(
                 artifact=artifact,
-                dependency_documents=dependency_documents,
-                conventions=combined_conventions,
-                ai_command=resolved_ai_command,
                 project_root=project_root,
-                feedback=feedback,
-                max_retries=body_max_retries,
+                global_conventions=global_conventions,
+                depended_by_map=depended_by_map,
+                document_node_paths=document_node_paths,
+                resolved_ai_command=resolved_ai_command,
+                body_max_retries=body_max_retries,
                 capabilities=capabilities,
                 project_language=project_language,
-            ),
+                feedback=feedback,
+            )
         )
-        output_path.write_text(content, encoding="utf-8")
-        results.append(GenerationResult(node_id=artifact.node_id, path=output_path, status="generated"))
 
     _enforce_vb_declaration_coherence(project_root, config, results)
     return results
 
 
+def _generate_one_artifact(
+    *,
+    artifact: WaveArtifact,
+    project_root: Path,
+    global_conventions: list[dict[str, Any]],
+    depended_by_map: dict[str, list[dict[str, Any]]],
+    document_node_paths: dict[str, Path],
+    resolved_ai_command: str,
+    body_max_retries: int,
+    capabilities: "ProjectCapabilities | None",
+    project_language: str | None,
+    feedback: str | None,
+) -> GenerationResult:
+    """Render ONE artifact's document and write it (overwriting any prior file).
+
+    The shared per-artifact rendering step used by both :func:`generate_wave`
+    (the wave loop) and :func:`regenerate_artifact` (the single-doc repair seam).
+    Always (re)writes the output; skip-if-exists is the wave loop's decision, not
+    this helper's, so a scoped repair can overwrite exactly one doc.
+    """
+
+    output_path = project_root / artifact.output
+    dependency_documents = _load_dependency_documents(
+        project_root, artifact.depends_on, document_node_paths
+    )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    combined_conventions = deepcopy(global_conventions) + deepcopy(artifact.conventions)
+    content = _render_document(
+        artifact=artifact,
+        global_conventions=global_conventions,
+        depended_by=depended_by_map.get(artifact.node_id, []),
+        body=_generate_document_body(
+            artifact=artifact,
+            dependency_documents=dependency_documents,
+            conventions=combined_conventions,
+            ai_command=resolved_ai_command,
+            project_root=project_root,
+            feedback=feedback,
+            max_retries=body_max_retries,
+            capabilities=capabilities,
+            project_language=project_language,
+        ),
+    )
+    output_path.write_text(content, encoding="utf-8")
+    return GenerationResult(node_id=artifact.node_id, path=output_path, status="generated")
+
+
+def regenerate_artifact(
+    project_root: Path,
+    *,
+    node_id: str | None = None,
+    output_path: str | None = None,
+    feedback: str | None = None,
+    ai_command: str | None = None,
+) -> GenerationResult:
+    """Regenerate a SINGLE wave artifact in place, scoped to one document.
+
+    The thin seam the greenfield generate-time VB-registry repair uses: it
+    rewrites ONLY the canonical VB doc (``docs/test/test_strategy.md``) with
+    repair feedback, WITHOUT re-running the whole wave (which would clobber the
+    sibling governance/design docs already generated). Reuses the exact wave
+    plumbing (:func:`_generate_one_artifact` → ``_load_dependency_documents`` /
+    ``_render_document`` / ``_generate_document_body``); only the artifact
+    selection (by ``node_id`` or ``output``) and the forced overwrite differ.
+
+    Identify the target by ``node_id`` (preferred) or ``output_path`` (the
+    artifact's ``output``). Raises ``ValueError`` if no/!=1 wave artifact matches
+    — an ambiguous or absent target must fail loudly, never silently no-op.
+    """
+
+    from codd.scanner import build_document_node_path_map
+
+    if not node_id and not output_path:
+        raise ValueError("regenerate_artifact requires node_id or output_path")
+
+    config = _load_project_config(project_root)
+    artifacts = _load_wave_artifacts(config)
+
+    def _matches(candidate: WaveArtifact) -> bool:
+        if node_id is not None and candidate.node_id == node_id:
+            return True
+        if output_path is not None:
+            want = output_path.replace("\\", "/").strip("/")
+            have = str(candidate.output).replace("\\", "/").strip("/")
+            if want == have:
+                return True
+        return False
+
+    matched = [artifact for artifact in artifacts if _matches(artifact)]
+    if not matched:
+        target = node_id or output_path
+        raise ValueError(f"wave_config has no artifact matching {target!r}")
+    if len(matched) > 1:
+        target = node_id or output_path
+        raise ValueError(f"wave_config has {len(matched)} artifacts matching {target!r}; ambiguous")
+
+    artifact = matched[0]
+    resolved_ai_command = _resolve_ai_command(config, ai_command, command_name="generate")
+    global_conventions = _normalize_conventions(config.get("conventions", []))
+    depended_by_map = _build_depended_by_map(artifacts)
+    document_node_paths = build_document_node_path_map(project_root, config)
+    body_max_retries = _body_max_retries(config)
+    capabilities = _resolve_generation_capabilities(config, project_root)
+    project_language = _resolve_project_language(config)
+
+    return _generate_one_artifact(
+        artifact=artifact,
+        project_root=project_root,
+        global_conventions=global_conventions,
+        depended_by_map=depended_by_map,
+        document_node_paths=document_node_paths,
+        resolved_ai_command=resolved_ai_command,
+        body_max_retries=body_max_retries,
+        capabilities=capabilities,
+        project_language=project_language,
+        feedback=feedback,
+    )
+
+
 def _enforce_vb_declaration_coherence(
     project_root: Path,
     config: dict[str, Any],

{codd_dev-2.48.0 → codd_dev-2.50.0}/codd/greenfield/pipeline.py

@@ -657,8 +657,181 @@ class GreenfieldPipeline:
             record["units"][key] = STATUS_DONE
             self._checkpoint(project_root)
             self.echo(f"[greenfield] generate wave {wave}: {detail}")
+
+        # After ALL waves are generated, enforce the canonical VB-registry
+        # completeness contract (model-independence): a weak model can reference
+        # VB ids in acceptance-criteria tables yet declare none in the canonical
+        # registry, which honest-REDs only later at implement with a confusing
+        # orphan message. Catch it HERE and drive a bounded, canonical-doc-scoped
+        # repair so a coherent registry exists before implement — or fail
+        # honestly at generate. Runs BEFORE implement by construction.
+        self._enforce_generate_vb_registry_gate(project_root, options)
         record["detail"] = f"{len(waves)} wave(s) generated"
 
+    def _enforce_generate_vb_registry_gate(
+        self, project_root: Path, options: dict[str, Any]
+    ) -> None:
+        """Generate-time canonical VB-registry completeness gate + bounded repair.
+
+        Adopts the GPT design (B as contract + A as bounded generate repair). On
+        error-level :func:`validate_vb_registry_completeness` issues (empty
+        canonical registry / unresolved AC references / missing canonical doc),
+        re-invoke generation SCOPED TO the canonical VB doc only
+        (:func:`codd.generator.regenerate_artifact`) with repair feedback, then
+        re-validate. After the bounded attempts (1–2), a still-failing registry
+        raises :class:`StageError` (generate honest-RED).
+
+        The MODEL writes the declarations — this is NOT deterministic auto-derive.
+        Acceptance-criteria references are used ONLY as the candidate list in the
+        repair feedback, NEVER auto-inserted into the canonical table (rejecting
+        design option C). Skipped for a project with no verifiable-behavior
+        surface (:func:`project_expects_vb_registry`) and when the owner turned
+        the coverage gate off — the registry contract tracks the coverage gate.
+        """
+        from codd.config import load_project_config
+        from codd.verifiable_behavior_audit import (
+            _CANONICAL_VB_OUTPUT_PATH,
+            coverage_gate_enabled,
+            project_expects_vb_registry,
+            validate_vb_registry_completeness,
+        )
+
+        if not bool(options.get("coverage_gate", True)):
+            return
+        try:
+            config = load_project_config(project_root)
+        except (FileNotFoundError, ValueError):
+            config = {}
+        if not coverage_gate_enabled(config):
+            return
+        if not project_expects_vb_registry(project_root, config):
+            # No VB surface planned/declared — nothing to certify. Mirrors the
+            # brownfield "nothing to audit -> pass" rule; a minimal greenfield
+            # project with only design docs is not forced to invent behaviors.
+            return
+
+        max_attempts = max(1, int(self._option_overrides.get("max_repair_attempts") or 0) or 2)
+        max_attempts = min(max_attempts, 2)  # bounded: 1–2 attempts (design)
+
+        # Reference the seam through the module (not a bound name) so a test's
+        # monkeypatch on ``codd.generator.regenerate_artifact`` is honored.
+        from codd import generator as generator_module
+
+        issues = validate_vb_registry_completeness(project_root, config, strict=True)
+        errors = [issue for issue in issues if issue.severity == "error"]
+        attempt = 0
+        while errors and attempt < max_attempts:
+            attempt += 1
+            feedback = self._build_vb_registry_repair_feedback(project_root, config, errors)
+            self.echo(
+                f"[greenfield] generate VB-registry gate: {len(errors)} issue(s); "
+                f"re-generating {_CANONICAL_VB_OUTPUT_PATH} with repair feedback "
+                f"(attempt {attempt}/{max_attempts})"
+            )
+            try:
+                generator_module.regenerate_artifact(
+                    project_root,
+                    output_path=_CANONICAL_VB_OUTPUT_PATH,
+                    feedback=feedback,
+                    ai_command=self.ai_command,
+                )
+            except (FileNotFoundError, ValueError) as exc:
+                # The canonical doc is not a planned artifact, or regeneration
+                # failed — cannot repair. Fail honestly with the original gap.
+                raise StageError(
+                    f"generate VB-registry gate: canonical registry repair could not run "
+                    f"({exc}); the canonical VB document ({_CANONICAL_VB_OUTPUT_PATH}) must "
+                    "declare every verifiable behavior as a first-column VB-* row."
+                ) from exc
+            issues = validate_vb_registry_completeness(project_root, config, strict=True)
+            errors = [issue for issue in issues if issue.severity == "error"]
+
+        if errors:
+            detail = "\n".join(f"  - {issue.message}" for issue in errors)
+            raise StageError(
+                "generate VB-registry gate FAILED: the generated canonical verifiable-behavior "
+                f"registry ({_CANONICAL_VB_OUTPUT_PATH}) is still incomplete after "
+                f"{attempt} repair attempt(s):\n{detail}\n"
+                "Declare every real verifiable behavior exactly once as a first-column VB-* row "
+                "in the canonical doc so coverage/authenticity can certify the system."
+            )
+        if attempt:
+            self.echo(
+                f"[greenfield] generate VB-registry gate: canonical registry repaired "
+                f"after {attempt} attempt(s) — OK"
+            )
+
+    def _build_vb_registry_repair_feedback(
+        self, project_root: Path, config: dict[str, Any], errors: list[Any]
+    ) -> str:
+        """Repair feedback for the canonical-doc-scoped regeneration.
+
+        Lists the canonical-registry declaration count + the unresolved AC
+        references (the CANDIDATE id list, never auto-inserted) + the repair
+        rules in the shape the GPT design specified. The references are a hint
+        about which behaviors likely exist — the model decides which correspond
+        to real behaviors and declares them; nothing is derived deterministically.
+        """
+        from codd.verifiable_behavior_audit import (
+            _CANONICAL_VB_OUTPUT_PATH,
+            _config_without_doc_pin,
+            _iter_doc_texts,
+            _normalize_vb_id,
+            is_canonical_vb_doc,
+            parse_vb_references,
+            parse_vb_table,
+        )
+
+        # Scan the WHOLE test-doc tree (not just test_coverage.docs) so the
+        # candidate-reference list mirrors what validate_vb_registry_completeness
+        # saw (an AC doc that references VB ids is not in test_coverage.docs).
+        doc_texts = _iter_doc_texts(project_root, config=_config_without_doc_pin(config))
+        canonical_count = 0
+        declared: set[str] = set()
+        for doc, text in doc_texts:
+            if not is_canonical_vb_doc(output_path=doc):
+                continue
+            rows = parse_vb_table(text, source_doc=doc)
+            canonical_count += len(rows)
+            declared.update(_normalize_vb_id(row.vb_id) for row in rows)
+
+        # Collect unresolved references (id -> the docs that reference it) as the
+        # CANDIDATE list only — never auto-inserted into the canonical table.
+        candidates: dict[str, set[str]] = {}
+        for doc, text in doc_texts:
+            if is_canonical_vb_doc(output_path=doc):
+                continue
+            for ref in parse_vb_references(text, source_doc=doc):
+                if _normalize_vb_id(ref.vb_id) in declared:
+                    continue
+                candidates.setdefault(ref.vb_id, set()).add(doc)
+
+        lines = [
+            "The generated verifiable-behavior (VB) registry is incomplete.",
+            "",
+            "Canonical registry:",
+            f"- {_CANONICAL_VB_OUTPUT_PATH} declares {canonical_count} canonical VB-* row(s).",
+        ]
+        if candidates:
+            lines.append("")
+            lines.append("Unresolved VB references (candidate ids — NOT yet declared canonically):")
+            for vb_id in sorted(candidates):
+                docs = ", ".join(sorted(candidates[vb_id]))
+                lines.append(f"- {vb_id} (referenced in {docs})")
+        lines.extend(
+            [
+                "",
+                "Repair rules:",
+                f"- Rewrite ONLY {_CANONICAL_VB_OUTPUT_PATH}.",
+                "- Declare every real verifiable behavior exactly once as a first-column VB-* row.",
+                "- Use a referenced id only when it corresponds to a real behavior derived from "
+                "the requirements/design; fix a reference elsewhere only if its id is genuinely wrong.",
+                "- Do NOT add or modify `codd: covers` markers.",
+                "- Do NOT edit source or executable tests.",
+            ]
+        )
+        return "\n".join(lines)
+
     # ── stage: implement ────────────────────────────────────
 
     def _stage_implement(self, project_root: Path, record: dict[str, Any], options: dict[str, Any]) -> None:
@@ -2522,6 +2695,7 @@ def _enforce_stage_coverage_gate(
         coverage_gate_enabled,
         coverage_gate_max_retries,
         format_gap_feedback,
+        project_expects_vb_registry,
         run_implement_coverage_gate,
     )
 
@@ -2536,6 +2710,24 @@ def _enforce_stage_coverage_gate(
     if not coverage_gate_enabled(config):
         return
 
+    # GREENFIELD-ONLY empty-registry hard-fail (rear guard behind the generate
+    # gate). For a project that is EXPECTED to own a canonical VB registry (it
+    # plans/declares one — see project_expects_vb_registry), an empty audit means
+    # NO verifiable behaviors were declared, so orphan never fires and the
+    # marker-authenticity gate has nothing to judge — verify could pass over a
+    # build whose VB-coverage contract was never generated. Fail honestly here.
+    # This does NOT change the brownfield run_implement_coverage_gate
+    # "nothing to audit -> pass" rule (that path is untouched); it gates ONLY the
+    # greenfield autopilot, and ONLY when a VB surface was expected — a minimal
+    # greenfield project with no VB surface still passes.
+    if project_expects_vb_registry(project_root, config):
+        if not build_vb_coverage_audit(project_root, config=config).rows:
+            raise StageError(
+                "greenfield requires a non-empty canonical VB registry in "
+                "docs/test/test_strategy.md; no verifiable behaviors were declared, "
+                "so coverage/authenticity cannot certify the generated system."
+            )
+
     # Pass the configured test dirs as the audited output paths so the gate
     # treats this as a test-related run (it is — every test the build will ever
     # have now exists) and evaluates the FULL project VB universe in one pass.

{codd_dev-2.48.0 → codd_dev-2.50.0}/codd/vb_marker_authenticity.py

@@ -257,6 +257,32 @@ def _scan_cover_markers_with_lines(text: str, rel_path: str) -> list[_CoverMarke
     return markers
 
 
+#: Provenance header CoDD stamps onto every file it generates. The implementer
+#: writes ``@generated-by: codd implement``, the generator ``@generated-by: codd
+#: generate``, the propagator ``@generated-by: codd propagate`` — all sharing this
+#: language-agnostic substring under the file's own comment prefix (``//`` / ``#``;
+#: see ``codd.implementer.COMMENT_PREFIX_BY_SUFFIX`` and ``_build_traceability_
+#: comment``). The same substring is what ``implementer._root_artifact_overwrite_
+#: blocked`` uses to recognize a CoDD-owned file.
+_HARNESS_PROVENANCE_MARKER = "@generated-by: codd"
+
+
+def _is_harness_generated(text: str) -> bool:
+    """Whether ``text`` is a file CoDD ITSELF generated (deterministic; no LLM).
+
+    True iff the file carries CoDD's generation-provenance header
+    (``@generated-by: codd …``). This is the HARNESS-OWNED vs USER/CUSTOM
+    discriminator for the strict-observability gate: a harness-owned file with no
+    parseable test block is a genuine false-green CoDD produced (hard-RED), while
+    a user-authored file in a recognized extension that our block-parser merely
+    cannot extract must degrade rather than false-RED. Matching the bare
+    ``@generated-by: codd`` substring keeps this language-agnostic — the marker is
+    emitted under each language's own comment prefix but the substring is constant.
+    """
+
+    return _HARNESS_PROVENANCE_MARKER in text
+
+
 def _attached_block(marker_line: int, text: str, blocks: list[TestBlock]) -> TestBlock | None:
     """The executable test block a marker on ``marker_line`` attaches to.
 
@@ -399,11 +425,16 @@ def build_authenticity_report(
     ``strict_observability`` (contract authenticity.observable_in_supported_stack.v1):
     when True, a marker-bearing file the adapter RECOGNIZES (``handles_file``) but
     from which it parses ZERO executable test blocks is an
-    ``unobservable_test_structure`` VIOLATION rather than a silent degrade — a
-    SUPPORTED stack that yields no observable test is a false-green, not an
-    unparseable one. An UNSUPPORTED file (no adapter / not handled) still degrades
-    in either mode (never a false-RED). The greenfield autopilot passes True; the
-    default is False for back-compat with non-autopilot callers.
+    ``unobservable_test_structure`` VIOLATION rather than a silent degrade — BUT
+    ONLY when that file is HARNESS-OWNED (CoDD generated it; it carries a
+    ``@generated-by: codd …`` provenance header). A harness-owned file with no
+    parseable test is a genuine false-green CoDD produced. A USER/CUSTOM file in a
+    recognized extension WITHOUT a provenance header DEGRADES instead: our block-
+    parser's incompleteness (a Mocha variant, a decorated / framework-wrapped test
+    style) must not hard-RED a user's valid-but-unparsed-by-us test. An UNSUPPORTED
+    file (no adapter / not handled) also degrades in either mode (never a
+    false-RED). The greenfield autopilot passes True; the default is False for
+    back-compat with non-autopilot callers.
     """
 
     project_root = Path(project_root).resolve()
@@ -469,14 +500,20 @@ def build_authenticity_report(
             except Exception:  # noqa: BLE001 — a parser that throws degrades, never fails.
                 blocks = []
         if not blocks:
-            if adapter_handles and strict_observability:
-                # OBSERVABILITY (contract authenticity.observable_in_supported_stack.v1):
-                # the adapter RECOGNIZES this file type but extracted ZERO executable
-                # test blocks though live coverage markers are present. That is NOT an
-                # unsupported stack (which legitimately degrades) — it is an
-                # unobservable coverage claim in a SUPPORTED stack, so it honest-fails
-                # instead of silently degrading to a pass (the false-green this
-                # contract closes).
+            if adapter_handles and strict_observability and _is_harness_generated(text):
+                # OBSERVABILITY (contract authenticity.observable_in_supported_stack.v1),
+                # NARROWED to HARNESS-OWNED files. The adapter RECOGNIZES this file
+                # type but extracted ZERO executable test blocks though live coverage
+                # markers are present. We HARD-FAIL this ONLY when CoDD ITSELF
+                # generated the file (it carries a ``@generated-by: codd …``
+                # provenance header): CoDD produced a marker-bearing test with no
+                # parseable assertion, which is a genuine false-green CoDD owns and
+                # must not ship. A USER/CUSTOM file in a recognized extension (NO
+                # provenance header) falls through to the degrade path below: our
+                # block-parser's incompleteness — a Mocha variant, a decorated /
+                # framework-wrapped test style we cannot extract — must NOT hard-RED a
+                # user's valid-but-unparsed-by-us test (that would be a false-RED).
+                # Stage 1 (orphan) already ran for every file regardless.
                 for marker in live_markers:
                     violations.append(
                         AuthenticityViolation(
@@ -486,18 +523,21 @@ def build_authenticity_report(
                             line=marker.line,
                             message=(
                                 f"{rel}:{marker.line} `codd: covers vb={marker.vb_id}` sits in a "
-                                "recognized test file from which the structural parser extracted NO "
-                                "executable test block — the coverage claim is unobservable (a marker "
-                                "with no parseable test proves nothing). Write a real test case the "
-                                "runner executes, or use `codd: blocked vb=… reason=…` if it genuinely "
-                                "cannot run yet."
+                                "CoDD-generated test file (`@generated-by: codd …`) from which the "
+                                "structural parser extracted NO executable test block — the coverage "
+                                "claim is unobservable (a generated marker with no parseable test "
+                                "proves nothing). Generate a real test case the runner executes, or "
+                                "use `codd: blocked vb=… reason=…` if it genuinely cannot run yet."
                             ),
                         )
                     )
                 continue
             # Graceful degradation: an UNSUPPORTED stack/file (no adapter, or the
-            # adapter does not handle this file), or strict observability off.
-            # Stage 1 already ran; skip stages 2-3 with a warning (never false-RED).
+            # adapter does not handle this file), strict observability off, OR a
+            # USER/CUSTOM recognized-extension file (no CoDD provenance header) our
+            # parser could not extract a block from — our parser's incompleteness must
+            # not hard-fail a user's valid test. Stage 1 already ran; skip stages 2-3
+            # with a warning (never false-RED).
             degraded.append(rel)
             continue