codd-dev 2.28.0__tar.gz → 2.30.0__tar.gz

{codd_dev-2.28.0 → codd_dev-2.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.28.0
+Version: 2.30.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.28.0 → codd_dev-2.30.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.28.0"
+__version__ = "2.30.0"

{codd_dev-2.28.0 → codd_dev-2.30.0}/codd/defaults.yaml

@@ -171,13 +171,16 @@ implement:
   # implement task (or a declared harness/profile contract). An orphan (a file no
   # task owns) sits OUTSIDE the artifact-contract graph -- its repair scope and
   # write-fence are undecidable, so a non-deterministic SUT can keep mutating it
-  # invisibly. 'warn' (default) observes + reports orphans after implement but
-  # never blocks (the check is heuristic; a large behaviour change rolls out as
-  # warn). 'enforce' makes an orphan a hard stage failure. 'off' disables it. A
+  # invisibly. 'warn' observes + reports orphans after implement but never blocks
+  # (heuristic; the large behaviour change first rolled out as warn, validated on
+  # the dogfood zoo, then promoted). 'enforce' (default, owner-set 2026-06-15)
+  # makes an orphan a hard stage failure -- the orphan-artifact invariant. Scaffold
+  # /harness-owned files (vitest.config.ts, tsconfig.json, ...) are profile-owned
+  # and never flagged. 'off' disables it. A
   # legitimate helper a task wrote under its OWN output directory is adopted (it
   # is dir-owned), so the warn list should be small. Only active for stacks with
   # a declared implement-time oracle + a derivable owner index.
-  orphan_artifact_gate: warn
+  orphan_artifact_gate: enforce
   # Bounded wall-clock for ONE implement-oracle command run (seconds). tsc on a
   # fresh build is fast, but a cold first run can compile a large module graph.
   # Default 600.

{codd_dev-2.28.0 → codd_dev-2.30.0}/codd/e2e_generator.py

@@ -375,6 +375,17 @@ def _render_header_comments(scenario: UserScenario, context: GenerationContext,
     if scenario.kind == "operational":
         source_operation = _source_operation_label(scenario)
         coverage_axis = scenario.coverage_axis or "unspecified"
+        # Machine-injection guard (anti-false-coverage): injecting a coverage
+        # marker is ONLY safe here because the mapping is HARNESS-OWNED and
+        # machine-known — this is a skeleton the harness itself generates for
+        # ``operation=<X>`` and the marker names that same operation. NEVER
+        # inject ``codd: covers vb=<id>`` into a free-form unit/integration test
+        # by guessing the VB from a test name or nearby text: a guessed marker is
+        # a false coverage claim the authenticity gate exists to reject. A VB
+        # marker may only be authored by the SUT on a test that genuinely proves
+        # the behavior, or attached to a harness-generated VB-specific skeleton
+        # whose asserting body the SUT fills in (still subject to the
+        # assertion-presence gate).
         lines.extend(
             [
                 "// Operational E2E policy: run the whole generated suite, collect all failures, then repair after the full campaign finishes.",

{codd_dev-2.28.0 → codd_dev-2.30.0}/codd/generator.py

@@ -226,6 +226,7 @@ _TEST_DOC_CANONICAL_VB_HEAD = [
     "- Every verifiable behavior must map to at least one test scenario — if a design document specifies a transition chain (e.g. action → intermediate state → final state), each link in the chain requires a separate assertion.",
     "- Include a traceability section that lists each verifiable behavior and its corresponding test scenario(s). Flag any behavior that lacks coverage.",
     "- Write that traceability section as a Markdown table whose FIRST column is a stable verifiable-behavior id of the form `VB-<id>` (e.g. `VB-01`, `VB-AUTH-02`), one row per verifiable behavior. Header wording and language are free; CoDD machine-parses the `VB-` id in the first cell (`codd test audit`), so never merge multiple behaviors into one row and never omit the id column.",
+    "- Each VB id must be ATOMIC — name exactly one behavior. Never use range or list shorthand in an id (no `VB-EVAL-02..06`, no `VB-02,03`, no `VB-02〜06`); write one row with a distinct atomic id per behavior instead. A range id cannot be honestly covered by a single test marker, and its members would read as permanently uncovered.",
     "- Declare each behavior under exactly one stable id; do not split one behavior across two ids or reuse an id for two different behaviors.",
     "- Treat design-time `operation_flow` records as the authoritative source for operational test obligations. Do not invent E2E-only behavior that is absent from requirements or design; instead flag missing design obligations.",
 ]

{codd_dev-2.28.0 → codd_dev-2.30.0}/codd/greenfield/pipeline.py

@@ -733,16 +733,29 @@ class GreenfieldPipeline:
         # — code that does not even typecheck cannot have meaningful VB coverage.
         self._enforce_implement_oracle_gate(project_root, tasks, options)
 
-        # Project-wide VB coverage gate — ONCE, after every implement task has
-        # run and all covering tests therefore exist. Per-task enforcement was
-        # disabled in _default_implement_task_runner precisely because the gate
-        # is project-wide; this is where it belongs. Honors the greenfield
-        # coverage_gate option (--no-coverage-gate / greenfield.coverage_gate:
-        # false) — when the owner turned it off, the final gate is skipped too.
+        # Project-wide VB coverage + marker-authenticity gate — ONCE, after every
+        # implement task has run and all covering tests therefore exist. Per-task
+        # enforcement was disabled in _default_implement_task_runner precisely
+        # because the gate is project-wide; this is where it belongs. Honors the
+        # greenfield coverage_gate option (--no-coverage-gate /
+        # greenfield.coverage_gate: false) — when the owner turned it off, the
+        # final gate is skipped too. The rerun is wired (was dormant): an
+        # uncovered VB drives a bounded, TEST-SCOPED re-implementation (source is
+        # never edited by a VB rerun) with gap feedback, and the native oracle is
+        # re-asserted after each test edit.
+        coverage_on = bool(options.get("coverage_gate", True))
         _enforce_stage_coverage_gate(
             project_root,
-            coverage_gate=bool(options.get("coverage_gate", True)),
+            coverage_gate=coverage_on,
             echo=self.echo,
+            rerun=self._make_vb_rerun_callback(project_root, tasks, options) if coverage_on else None,
+            rerun_oracle=(
+                (lambda: self._enforce_implement_oracle_gate(project_root, tasks, options))
+                if coverage_on
+                else None
+            ),
+            scope_resolver=self._make_vb_scope_resolver(project_root, tasks) if coverage_on else None,
+            authenticity_profile=self._resolve_layout_profile(project_root) if coverage_on else None,
         )
         record["detail"] = f"{len(tasks)} task(s) implemented"
 
@@ -925,19 +938,52 @@ class GreenfieldPipeline:
             return None
 
     def _oracle_manifest_paths(self, project_root: Path) -> tuple[str, ...]:
-        """Manifest/config files the write-fence always permits (they are shared).
-
-        A scoped rerun may legitimately touch the build manifest/config even when
-        no task "owns" it (e.g. adding a dependency the fix needs). Only files
-        that actually exist are listed, project-relative.
+        """Harness-owned shared files the write-fence permits + the orphan gate exempts.
+
+        Two roles, one list (both legitimate for the same files):
+          * **write-fence permit** — a scoped rerun may touch shared build
+            manifest/config even when no task "owns" it (e.g. adding a dependency
+            the fix needs).
+          * **orphan-gate escape hatch** (``extra_owned``) — a scaffolded config
+            is a generated artifact owned by the HARNESS contract, not a task, so
+            it must not be mis-flagged as an unowned orphan.
+
+        Sources, unioned: (1) the active stack's :class:`LayoutProfile`
+        ``harness_owned_scaffold_paths`` (e.g. TS ``vitest.config.ts`` /
+        ``tsconfig.json`` / ``package.json`` — the files the scaffolder creates),
+        derived language-agnostically from the profile; (2) a small fallback set of
+        common lockfiles a manager may have produced that the profile does not
+        enumerate. Only files that actually EXIST are returned, project-relative.
         """
-        candidates = (
-            "package.json",
-            "tsconfig.json",
-            "package-lock.json",
-            "pnpm-lock.yaml",
-            "yarn.lock",
-        )
+        candidates: list[str] = []
+
+        def _add(rel: str) -> None:
+            if rel and rel not in candidates:
+                candidates.append(rel)
+
+        # (1) Profile-declared scaffold contract (language-agnostic, single source).
+        try:
+            from codd.project_types import resolve_layout_profile
+
+            config, language, source_dirs, test_dirs = self._layout_inputs(project_root)
+            profile = resolve_layout_profile(
+                language=language,
+                project_name=self._layout_project_name(project_root, config),
+                source_dirs=source_dirs,
+                test_dirs=test_dirs,
+                config=config,
+                project_root=project_root,
+            )
+            if profile is not None:
+                for rel in profile.harness_owned_scaffold_paths():
+                    _add(rel)
+        except Exception as exc:  # noqa: BLE001 — escape hatch is best-effort; fall back to the static set.
+            self.echo(f"[greenfield] implement-oracle: scaffold-path contract unavailable ({exc}).")
+
+        # (2) Lockfile fallbacks not necessarily enumerated by the profile.
+        for name in ("package.json", "tsconfig.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"):
+            _add(name)
+
         present: list[str] = []
         for name in candidates:
             if (project_root / name).is_file():
@@ -1018,6 +1064,91 @@ class GreenfieldPipeline:
                 feedback=feedback,
             )
 
+    def _make_vb_rerun_callback(
+        self,
+        project_root: Path,
+        tasks: list[ImplementTaskRef],
+        options: dict[str, Any],
+    ) -> Callable[[str, Any], None]:
+        """A ``rerun(feedback, scope)`` for the VB coverage gate's feedback loop.
+
+        Reuses the oracle's scoped, write-fenced rerun dispatch
+        (:meth:`_rerun_tasks_with_feedback`): a TEST-scoped
+        :class:`~codd.implement_oracle_scope.OracleRerunScope` re-implements ONLY
+        its test tasks, fenced to test files/helpers, so a VB coverage rerun can
+        never rewrite production source.
+        """
+
+        def _rerun(feedback: str, scope: Any = None) -> None:
+            self._rerun_tasks_with_feedback(project_root, tasks, feedback, options, scope=scope)
+
+        return _rerun
+
+    def _make_vb_scope_resolver(
+        self,
+        project_root: Path,
+        tasks: list[ImplementTaskRef],
+    ) -> Callable[[list[str]], Any]:
+        """A resolver mapping uncovered VB source docs → a TEST-scoped rerun scope.
+
+        Delegates to :func:`codd.vb_rerun_scope.derive_vb_rerun_scope` with the
+        pipeline's ``_output_paths_for_task`` so each task's outputs resolve the
+        same way the rerun itself resolves them. A derivation failure degrades to
+        a broad scope (never aborts the gate).
+        """
+        from codd.config import load_project_config
+
+        def _resolve(uncovered_source_docs: list[str]) -> Any:
+            try:
+                config = load_project_config(project_root)
+            except (FileNotFoundError, ValueError):
+                config = {}
+            try:
+                from codd.vb_rerun_scope import derive_vb_rerun_scope
+
+                return derive_vb_rerun_scope(
+                    uncovered_source_docs,
+                    tasks,
+                    config=config,
+                    path_resolver=_output_paths_for_task,
+                )
+            except Exception as exc:  # noqa: BLE001 — degrade to broad, never abort.
+                self.echo(f"[greenfield] VB rerun: scope derivation failed ({exc}); rerun stays broad.")
+                from codd.implement_oracle_scope import SCOPE_BROAD, OracleRerunScope
+
+                return OracleRerunScope(
+                    rung=SCOPE_BROAD,  # canonical broad ⇒ is_broad() True ⇒ unfenced
+                    task_ids=tuple(task.task_id for task in tasks),
+                    allowed_paths=(),
+                    detail="VB rerun: scope derivation error — broad fallback",
+                )
+
+        return _resolve
+
+    def _resolve_layout_profile(self, project_root: Path) -> Any:
+        """Resolve the active :class:`~codd.project_types.LayoutProfile` (or None).
+
+        Used by the marker-authenticity gate to obtain the per-language
+        test-block adapter (``profile.test_block_profile()``). Best-effort: any
+        resolution failure returns ``None`` so the gate degrades to its
+        language-agnostic stage-1 (orphan) check rather than aborting.
+        """
+        try:
+            from codd.project_types import resolve_layout_profile
+
+            config, language, source_dirs, test_dirs = self._layout_inputs(project_root)
+            return resolve_layout_profile(
+                language=language,
+                project_name=self._layout_project_name(project_root, config),
+                source_dirs=source_dirs,
+                test_dirs=test_dirs,
+                config=config,
+                project_root=project_root,
+            )
+        except Exception as exc:  # noqa: BLE001 — authenticity degrades without a profile.
+            self.echo(f"[greenfield] VB authenticity: layout profile unavailable ({exc}); stage-1 only.")
+            return None
+
     def _default_implement_task_runner(
         self,
         project_root: Path,
@@ -1964,8 +2095,12 @@ def _enforce_stage_coverage_gate(
     *,
     coverage_gate: bool,
     echo: Callable[[str], None],
+    rerun: Callable[[str, Any], None] | None = None,
+    rerun_oracle: Callable[[], None] | None = None,
+    scope_resolver: Callable[[list[str]], Any] | None = None,
+    authenticity_profile: Any = None,
 ) -> None:
-    """Project-wide verifiable-behavior coverage gate for the implement STAGE.
+    """Project-wide verifiable-behavior coverage + authenticity gate (implement STAGE).
 
     Runs ONCE after every implement task has completed, so all covering tests
     already exist. This is the correct granularity for the project-wide VB
@@ -1975,20 +2110,35 @@ def _enforce_stage_coverage_gate(
     — an early fixtures/helper task that writes no covering tests would
     otherwise hard-fail against the whole project's VBs.)
 
-    No ``rerun`` is wired: by stage end the build is complete, so any remaining
-    uncovered VB is a genuine failure of the whole implement stage, not a
-    transient gap to re-implement away. The failure is raised as a
-    :class:`StageError` carrying the gap list, which the pipeline records on the
-    implement stage record and surfaces through the existing checkpoint/resume
-    machinery.
-
-    Honors the greenfield ``coverage_gate`` option: when it is off
-    (``--no-coverage-gate`` / ``greenfield.coverage_gate: false``) the gate is
-    skipped entirely. The project-level ``test_coverage.gate`` config is also
-    respected (via :func:`run_implement_coverage_gate`).
+    Two gates, both HARD (raise :class:`StageError` on failure):
+
+    1. **Coverage** (:func:`run_implement_coverage_gate`): every declared VB has a
+       ``covers``/``blocked`` marker. When a ``rerun`` callback is wired, an
+       uncovered gap drives a bounded, TEST-SCOPED re-implementation with gap
+       feedback (the previously-dormant feedback loop, now live) before failing.
+    2. **Authenticity** (:func:`build_authenticity_report`): each ``covers``
+       marker is a *credible* claim — attached to an executable test block that
+       contains an assertion (anti-false-green; "add a marker" cannot be
+       satisfied by marking an empty/skipped test). Gracefully degrades for
+       stacks/files it cannot structurally parse.
+
+    ``rerun(feedback, scope)`` re-implements the scoped TEST tasks under a
+    write-fence (source is never edited by a VB rerun). ``scope_resolver`` maps
+    the uncovered VB source docs to that scope. ``rerun_oracle`` re-runs the
+    native implement-oracle AFTER a VB rerun (a test edit can break a helper
+    symbol; the pipeline order is oracle→VB, so the oracle must be re-asserted).
+
+    Honors the greenfield ``coverage_gate`` option and the project-level
+    ``test_coverage.gate`` config.
     """
     from codd.config import load_project_config
-    from codd.verifiable_behavior_audit import run_implement_coverage_gate
+    from codd.verifiable_behavior_audit import (
+        build_vb_coverage_audit,
+        coverage_gate_enabled,
+        coverage_gate_max_retries,
+        format_gap_feedback,
+        run_implement_coverage_gate,
+    )
 
     if not coverage_gate:
         return
@@ -1998,6 +2148,9 @@ def _enforce_stage_coverage_gate(
     except (FileNotFoundError, ValueError):
         config = {}
 
+    if not coverage_gate_enabled(config):
+        return
+
     # 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.
@@ -2007,13 +2160,52 @@ def _enforce_stage_coverage_gate(
     else:
         audited_paths = ["tests/"]
 
+    # --- Gate 1: coverage, with the (now-live) TEST-scoped feedback rerun. ---
+    if rerun is not None and scope_resolver is not None:
+        # Drive the bounded feedback loop HERE so each rerun is TEST-scoped (the
+        # scope is recomputed from the current gap) and the native oracle is
+        # re-asserted after each test edit. ``run_implement_coverage_gate`` is
+        # then called once more with rerun=None to produce the final verdict +
+        # gap reporting (no second loop).
+        max_retries = coverage_gate_max_retries(config)
+        report = build_vb_coverage_audit(project_root, config=config)
+        attempt = 0
+        while report.rows and report.uncovered_rows and attempt < max_retries:
+            attempt += 1
+            uncovered_docs = sorted({row.source_doc for row in report.uncovered_rows if row.source_doc})
+            scope = scope_resolver(uncovered_docs)
+            echo(
+                f"Test coverage gate: {len(report.uncovered_rows)} uncovered verifiable behavior(s); "
+                f"re-running TEST tasks with gap feedback (attempt {attempt}/{max_retries})"
+            )
+            try:
+                rerun(format_gap_feedback(report), scope)
+                if rerun_oracle is not None:
+                    # A VB test rerun can break test↔helper symbol coherence;
+                    # re-assert the native oracle so a type/import break never
+                    # rides into verify.
+                    rerun_oracle()
+            except Exception as exc:  # noqa: BLE001
+                # A rerun that cannot proceed (e.g. a codegen/environment error)
+                # must NOT mask the gate's verdict: log and stop the bounded loop,
+                # then fall through to the final coverage audit, which fails
+                # HONESTLY on whatever VBs are still uncovered. (The oracle gate
+                # treats its rerun failures as hard because they ARE the defect;
+                # here the authority is the coverage audit below, not the rerun.)
+                echo(
+                    f"Test coverage gate: re-run attempt {attempt} could not complete ({exc}); "
+                    "stopping the feedback loop and evaluating coverage as-is."
+                )
+                break
+            report = build_vb_coverage_audit(project_root, config=config)
+
     passed = run_implement_coverage_gate(
         project_root,
         config=config,
         design_node=None,
         output_paths=audited_paths,
         opt_out=not coverage_gate,
-        rerun=None,
+        rerun=None,  # the scoped loop (above) already ran; this is the final verdict
         echo=echo,
         echo_error=echo,
     )
@@ -2024,6 +2216,29 @@ def _enforce_stage_coverage_gate(
             "marker after all implement tasks completed (see the gap list above)"
         )
 
+    # --- Gate 2: marker authenticity (anti-false-green). HARD gate. ---
+    from codd.vb_marker_authenticity import build_authenticity_report
+
+    auth = build_authenticity_report(project_root, config=config, profile=authenticity_profile)
+    if auth.degraded_paths:
+        echo(
+            "Test coverage gate: marker-authenticity attachment/assertion checks skipped for "
+            f"{len(auth.degraded_paths)} un-parseable file(s) (stage-1 orphan check still applied): "
+            + ", ".join(auth.degraded_paths)
+        )
+    if not auth.passed:
+        for violation in auth.violations:
+            echo(violation.message)
+        raise StageError(
+            "verifiable-behavior marker-authenticity gate failed for the implement stage: "
+            f"{len(auth.violations)} `codd: covers vb=` marker(s) are not credible coverage claims "
+            "(attached to a skipped/empty test, an orphan id, or a test with no assertion). A "
+            "covers marker must sit on an executable test that asserts the behavior."
+        )
+    echo(
+        f"Test coverage gate: marker authenticity OK ({len(auth.degraded_paths)} file(s) stage-1-only)."
+    )
+
 
 def _default_verify_runner(
     project_root: Path,

{codd_dev-2.28.0 → codd_dev-2.30.0}/codd/implementer.py

@@ -1884,9 +1884,10 @@ def _build_implementation_prompt(
     if _spec_targets_tests(spec, config):
         lines.extend(
             [
-                "Verifiable-behavior traceability markers:",
-                "- If the design or dependency test documents declare verifiable-behavior ids (a traceability table whose first column is `VB-<id>`), annotate each generated test with a comment marker `codd: covers vb=<id>` for every behavior that test proves (`codd test audit` reconciles these markers).",
-                "- If a declared behavior cannot be tested yet, add an explicit `codd: blocked vb=<id> reason=<short_reason>` comment marker instead of leaving it silently uncovered.",
+                "Verifiable-behavior traceability markers (release-blocking — the implement stage gate fails the build on any gap):",
+                "- The design and its dependency test documents declare verifiable behaviors in a traceability table whose first column is `VB-<id>`. Reconcile EVERY declared VB id against the tests you write: for each VB, produce either a real test that PROVES it (carrying a `codd: covers vb=<id>` comment marker) or, if it genuinely cannot be tested yet, an explicit `codd: blocked vb=<id> reason=<short_reason>` marker. Never leave a declared VB silently uncovered.",
+                "- A `codd: covers vb=<id>` marker is a CLAIM that the test proves that behavior. Only attach it to a test that (a) is actually executed — not `it.skip`/`test.todo`/`describe.skip`/`@pytest.mark.skip`/disabled — and (b) contains at least one assertion that would FAIL if the behavior were broken. A marker on an empty test, a skipped test, or a smoke test with no assertion is a false coverage claim and the authenticity gate will reject it. If no proving test exists, create or extend a real one FIRST, then mark it — do not add the marker to make the gate pass.",
+                "- One marker per behavior, placed inside the test file (a comment immediately above the proving test). Example (pytest): `# codd: covers vb=VB-07` directly above `def test_rejects_missing_id(): ...` whose body asserts the rejection. Example (vitest): `// codd: covers vb=VB-07` directly above the `it('rejects missing id', () => { expect(...).toThrow(); })`.",
                 "",
                 "Scoped assertions (precision, not weakening):",
                 "- When a test asserts a CONTENT constraint over rendered or serialized output (e.g. \"displayed amounts contain no decimal point\", \"no personal data appears in the response\", \"every listed price shows a currency symbol\"), assert ONLY against the specific values or elements the constraint governs: parse and read the relevant nodes/fields under test (DOM elements, table cells, the parsed JSON values, the matched record), not the whole response body.",

{codd_dev-2.28.0 → codd_dev-2.30.0}/codd/project_types.py

@@ -540,6 +540,83 @@ class LayoutProfile:
             ),
         }
 
+    def harness_owned_scaffold_paths(self) -> tuple[str, ...]:
+        """Project-relative files the harness SCAFFOLD owns (the contract escape hatch).
+
+        These are the files :func:`scaffold_layout` creates for this stack —
+        topology + config the SUT never "owns" via a task, yet which are
+        legitimate generated artifacts (the orphan-artifact invariant's "owned by
+        a task OR an explicit harness/profile contract" branch). The orphan-gate
+        and the scoped-rerun write-fence consult this list so a scaffold file
+        (e.g. TS ``vitest.config.ts`` / ``tsconfig.json``) is never mis-flagged as
+        an unowned orphan and never reverted by the fence.
+
+        Language-agnostic: each path is DERIVED from this profile's own fields
+        (the same values the scaffolder uses) + the toolchain manifest/lock
+        filenames, so a new stack inherits the contract by populating its profile,
+        with no per-language logic in the gate. The list is a STATIC declaration of
+        what the scaffolder *can* create (not what is present on disk); callers
+        that need only existing files filter by ``is_file()``.
+        """
+        paths: list[str] = []
+
+        def _add(rel: str) -> None:
+            norm = _norm_rel(rel)
+            if norm and norm not in paths:
+                paths.append(norm)
+
+        # Dependency manifest + lockfile(s) the toolchain contract owns
+        # (package.json / package-lock.json; pyproject.toml / uv.lock; …).
+        toolchain = self.toolchain_dependencies
+        if toolchain is not None:
+            _add(toolchain.manifest_filename)
+            for lock in toolchain.lock_filenames:
+                _add(lock)
+
+        if self.language == "python":
+            # _scaffold_python: pyproject + package <__init__>/<__main__> + test <__init__>.
+            _add(_PYPROJECT_FILENAME)
+            if self.requires_package_init:
+                _add(f"{self.package_root}/__init__.py")
+                _add(f"{self.package_root}/__main__.py")
+            if self.requires_test_init:
+                _add(f"{self.test_root}/__init__.py")
+        elif self.language in ("typescript", "node"):
+            # _scaffold_typescript: tsconfig + vitest config + package.json.
+            _add(_TSCONFIG_FILENAME)
+            _add(_VITEST_CONFIG_FILENAME)
+            _add(_PACKAGE_JSON_FILENAME)
+
+        return tuple(paths)
+
+    def test_block_profile(self) -> Any:
+        """Resolve this stack's test-structure adapter for the VB authenticity gate.
+
+        Returns a ``codd.vb_marker_authenticity.TestBlockProfile`` (a per-language
+        parser that locates executable test blocks and resolves skip/assertion
+        facts) or ``None`` for a stack with no adapter — in which case the
+        authenticity gate gracefully degrades to its language-agnostic stage 1
+        (orphan-marker) check only. This is the SINGLE registration point for a
+        new stack's test parser, mirroring :meth:`harness_owned_scaffold_paths`
+        (dispatch on ``self.language``, no per-language logic in the gate). The
+        import is lazy so the authenticity module (which imports the VB audit) is
+        never pulled in at ``project_types`` import time.
+        """
+
+        try:
+            from codd.vb_marker_authenticity import (
+                PythonTestBlockProfile,
+                TypeScriptTestBlockProfile,
+            )
+        except Exception:  # noqa: BLE001 — adapter is optional; degrade if unavailable.
+            return None
+
+        if self.language == "python":
+            return PythonTestBlockProfile()
+        if self.language in ("typescript", "node", "javascript"):
+            return TypeScriptTestBlockProfile()
+        return None
+
 
 def normalize_package_name(project_name: str | None, *, fallback: str = "app") -> str:
     """Derive a valid Python package identifier from a project name.