codd-dev 1.28.0__tar.gz → 1.30.0__tar.gz

{codd_dev-1.28.0 → codd_dev-1.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 1.28.0
+Version: 1.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-1.28.0 → codd_dev-1.30.0}/codd/cli.py

@@ -942,7 +942,7 @@ def propagate_from(project_path: str, files: tuple[str, ...], source: str, edito
         raise SystemExit(1)
 
 
-@main.command()
+@main.group(invoke_without_command=True)
 @click.option("--path", default=".", help="Project root directory")
 @click.option("--task", default=None, help="Generate only one task by task ID or title match")
 @click.option("--clean", is_flag=True, default=False, help="Remove existing generated output before re-generating")
@@ -964,16 +964,23 @@ def propagate_from(project_path: str, files: tuple[str, ...], source: str, edito
     default=None,
     help="Override AI CLI command (defaults to codd.yaml ai_command or merged CoDD defaults)",
 )
+@click.option("--use-derived-steps", default=None, help="Inject derived implementation steps: true or false")
+@click.pass_context
 def implement(
+    ctx,
     path: str,
     task: str | None,
     clean: bool,
     max_tasks: int,
     wave: int | None,
     ai_cmd: str | None,
+    use_derived_steps: str | None,
 ):
-    """Generate implementation code from the implementation plan."""
-    from codd.implementer import implement_tasks
+    """Generate implementation code from the implementation plan."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    from codd.implementer import implement_tasks
 
     project_root = Path(path).resolve()
     codd_dir = _require_codd_dir(project_root)
@@ -982,14 +989,17 @@ def implement(
         click.echo("Cleaning src/generated/ ...")
 
     try:
-        results = implement_tasks(
-            project_root,
-            task=task,
-            ai_command=ai_cmd,
-            clean=clean,
-            max_tasks=max_tasks,
-            wave=wave,
-        )
+        implement_kwargs = {
+            "task": task,
+            "ai_command": ai_cmd,
+            "clean": clean,
+            "max_tasks": max_tasks,
+            "wave": wave,
+        }
+        parsed_use_derived_steps = _optional_bool(use_derived_steps)
+        if parsed_use_derived_steps is not None:
+            implement_kwargs["use_derived_steps"] = parsed_use_derived_steps
+        results = implement_tasks(project_root, **implement_kwargs)
     except (FileNotFoundError, ValueError, CoddCLIError) as exc:
         click.echo(f"Error: {exc}")
         raise SystemExit(1)
@@ -1013,9 +1023,374 @@ def implement(
             f"\nFAILED: {len(failed_tasks)} task(s) produced no files:",
             fg="red", bold=True,
         ))
-        for ft in failed_tasks:
-            click.echo(click.style(f"  ✗ {ft.task_id} ({ft.task_title}): {ft.error}", fg="red"))
-        raise SystemExit(1)
+        for ft in failed_tasks:
+            click.echo(click.style(f"  ✗ {ft.task_id} ({ft.task_title}): {ft.error}", fg="red"))
+        raise SystemExit(1)
+
+
+@implement.command("plan")
+@click.option("--task", "task_id", required=True, help="Implementation task id or title match")
+@click.option("--design-doc", "design_docs", multiple=True, help="Design document path. May be repeated.")
+@click.option("--force", is_flag=True, help="Bypass cached implementation steps")
+@click.option("--dry-run", is_flag=True, help="Print derived steps without writing cache")
+@click.option("--path", "project_path", default=".", help="Project root directory")
+@click.option("--provider", default=None, help="Implementation step deriver provider name")
+@click.option("--ai-cmd", default=None, help="Override AI command")
+def implement_plan_cmd(
+    task_id: str,
+    design_docs: tuple[str, ...],
+    force: bool,
+    dry_run: bool,
+    project_path: str,
+    provider: str | None,
+    ai_cmd: str | None,
+):
+    """Derive implementation steps for one task."""
+    from codd.deployment.providers.ai_command import SubprocessAiCommand
+    from codd.llm.impl_step_deriver import IMPL_STEP_DERIVERS
+
+    project_root = Path(project_path).resolve()
+    _require_codd_dir(project_root)
+    config = _load_optional_project_config(project_root)
+    provider_name = provider or _impl_step_provider(config)
+    deriver_cls = IMPL_STEP_DERIVERS.get(provider_name)
+    if deriver_cls is None:
+        click.echo(f"Error: implementation step deriver provider not found: {provider_name}")
+        raise SystemExit(1)
+
+    try:
+        task_item = _implement_task_for_cli(project_root, config, task_id)
+        nodes = _plan_design_doc_nodes(project_root, design_docs)
+    except (FileNotFoundError, ValueError) as exc:
+        click.echo(f"Error: {exc}")
+        raise SystemExit(1)
+
+    command = ai_cmd or _impl_step_command(config)
+    deriver = deriver_cls(SubprocessAiCommand(command=command, project_root=project_root, config=config))
+    steps = deriver.derive_steps(
+        task_item,
+        nodes,
+        {
+            "project_root": project_root,
+            "force": force,
+            "dry_run": dry_run,
+            "write_cache": not dry_run,
+            "config": config,
+            "project_context": {"project": config.get("project", {})},
+        },
+    )
+    if dry_run:
+        click.echo(yaml.safe_dump([step.to_dict() for step in steps], sort_keys=False, allow_unicode=True), nl=False)
+        return
+    click.echo(f"Derived implementation steps: {len(steps)}")
+
+
+@implement.command("steps")
+@click.option("--task", "task_id", required=True, help="Implementation task id")
+@click.option("--approve", is_flag=True, help="Approve one or more derived steps")
+@click.option("--step", "step_id", default=None, help="Step id for --approve")
+@click.option("--all", "approve_all", is_flag=True, help="Approve all pending steps")
+@click.option("--show-only", is_flag=True, help="Only show cached steps")
+@click.option("--show-layer-breakdown", is_flag=True, help="Show explicit and inferred step groups")
+@click.option("--path", "project_path", default=".", help="Project root directory")
+def implement_steps_cmd(
+    task_id: str,
+    approve: bool,
+    step_id: str | None,
+    approve_all: bool,
+    show_only: bool,
+    show_layer_breakdown: bool,
+    project_path: str,
+):
+    """Show or approve derived implementation steps."""
+    from codd.llm.impl_step_deriver import approve_cached_impl_steps, impl_step_cache_path, read_impl_step_cache
+
+    project_root = Path(project_path).resolve()
+    cache_path = impl_step_cache_path(task_id, {"project_root": project_root})
+    if approve:
+        if not approve_all and not step_id:
+            click.echo("Error: --approve requires --step or --all")
+            raise SystemExit(2)
+        try:
+            changed = approve_cached_impl_steps(cache_path, step_id=step_id, approve_all=approve_all)
+        except (FileNotFoundError, ValueError) as exc:
+            click.echo(f"Error: {exc}")
+            raise SystemExit(1)
+        click.echo(f"Approved implementation steps: {changed}")
+        if not show_only:
+            return
+
+    record = read_impl_step_cache(cache_path)
+    if record is None:
+        click.echo("No derived implementation steps found")
+        return
+    if show_layer_breakdown:
+        _echo_impl_step_layer_breakdown(record)
+        return
+    for step in record.steps:
+        layer = "layer2" if step.inferred else "layer1"
+        status = "approved" if step.approved else "pending"
+        click.echo(f"{step.id}\t{status}\t{layer}\t{step.kind}\t{step.source_design_section}")
+
+
+def _echo_impl_step_layer_breakdown(record: Any) -> None:
+    layer_1 = [step for step in record.steps if not step.inferred]
+    layer_2 = [step for step in record.steps if step.inferred]
+    click.echo(f"[Layer 1 - Explicit, from design] (count={len(layer_1)})")
+    for step in layer_1:
+        click.echo(f"  - {step.kind}: {step.id} (rationale: {step.rationale})")
+
+    avg_confidence = sum(float(step.confidence) for step in layer_2) / len(layer_2) if layer_2 else 0.0
+    click.echo("")
+    click.echo(f"[Layer 2 - Best Practice Augment] (count={len(layer_2)}, avg_confidence={avg_confidence:.2f})")
+    for step in layer_2:
+        category = step.best_practice_category or "uncategorized"
+        click.echo(
+            f"  - {step.kind}: {step.id} "
+            f"(confidence={step.confidence:.2f}, category={category}, rationale: {step.rationale})"
+        )
+
+
+@implement.command("augment")
+@click.option("--task", "task_id", required=True, help="Implementation task id or title match")
+@click.option("--design-doc", "design_docs", multiple=True, help="Design document path. May be repeated.")
+@click.option("--path", "project_path", default=".", help="Project root directory")
+@click.option("--provider", default=None, help="Best practice augmenter provider name")
+@click.option("--ai-cmd", default=None, help="Override AI command")
+def implement_augment_cmd(
+    task_id: str,
+    design_docs: tuple[str, ...],
+    project_path: str,
+    provider: str | None,
+    ai_cmd: str | None,
+):
+    """Suggest inferred implementation steps and merge them into the task cache."""
+    from codd.deployment.providers.ai_command import SubprocessAiCommand
+    from codd.llm.best_practice_augmenter import BEST_PRACTICE_AUGMENTERS
+    from codd.llm.impl_step_deriver import (
+        ImplStepCacheRecord,
+        impl_step_cache_path,
+        merge_impl_steps,
+        read_impl_step_cache,
+        utc_timestamp,
+        write_impl_step_cache,
+    )
+
+    project_root = Path(project_path).resolve()
+    _require_codd_dir(project_root)
+    config = _load_optional_project_config(project_root)
+    cache_path = impl_step_cache_path(task_id, {"project_root": project_root})
+    record = read_impl_step_cache(cache_path)
+    if record is None:
+        click.echo("Error: derive Layer 1 steps before augmenting")
+        raise SystemExit(1)
+
+    provider_name = provider or _best_practice_provider(config)
+    augmenter_cls = BEST_PRACTICE_AUGMENTERS.get(provider_name)
+    if augmenter_cls is None:
+        click.echo(f"Error: best practice augmenter provider not found: {provider_name}")
+        raise SystemExit(1)
+
+    try:
+        task_item = _implement_task_for_cli(project_root, config, task_id)
+        docs = design_docs or tuple(record.design_docs)
+        nodes = _plan_design_doc_nodes(project_root, docs)
+    except (FileNotFoundError, ValueError) as exc:
+        click.echo(f"Error: {exc}")
+        raise SystemExit(1)
+
+    command = ai_cmd or _best_practice_command(config)
+    augmenter = augmenter_cls(SubprocessAiCommand(command=command, project_root=project_root, config=config))
+    explicit = [step for step in record.steps if not step.inferred]
+    implicit = augmenter.suggest_implicit_steps(
+        task_item,
+        nodes,
+        explicit,
+        {"project_root": project_root, "config": config, "project_context": {"project": config.get("project", {})}},
+    )
+    merged = merge_impl_steps(explicit, implicit)
+    write_impl_step_cache(
+        cache_path,
+        ImplStepCacheRecord(
+            provider_id=record.provider_id,
+            cache_key=f"{record.cache_key}:augmented",
+            task_id=record.task_id,
+            design_doc_sha=record.design_doc_sha,
+            prompt_template_sha=record.prompt_template_sha,
+            generated_at=utc_timestamp(),
+            design_docs=record.design_docs,
+            steps=merged,
+        ),
+    )
+    click.echo(f"Augmented implementation steps: {len(implicit)}")
+
+
+@implement.command("run")
+@click.option("--task", "task_id", default=None, help="Generate only one task by task ID or title match")
+@click.option("--path", "project_path", default=".", help="Project root directory")
+@click.option("--ai-cmd", default=None, help="Override AI CLI command")
+@click.option("--use-derived-steps", default="true", help="Inject derived implementation steps: true or false")
+@click.option("--chunk-size", default=None, type=click.IntRange(min=1), help="Run derived steps in chunks of this size")
+@click.option(
+    "--timeout-per-chunk",
+    default=600,
+    type=click.IntRange(min=1),
+    show_default=True,
+    help="Seconds before one chunk is interrupted",
+)
+def implement_run_cmd(
+    task_id: str | None,
+    project_path: str,
+    ai_cmd: str | None,
+    use_derived_steps: str,
+    chunk_size: int | None,
+    timeout_per_chunk: int,
+):
+    """Run implementation with optional derived step injection."""
+    from codd.implementer import implement_tasks
+
+    project_root = Path(project_path).resolve()
+    _require_codd_dir(project_root)
+    if chunk_size is not None:
+        try:
+            result = _run_chunked_implementation(
+                project_root=project_root,
+                task_id=task_id,
+                ai_cmd=ai_cmd,
+                chunk_size=chunk_size,
+                timeout_per_chunk=timeout_per_chunk,
+                history=None,
+            )
+        except (FileNotFoundError, ValueError, CoddCLIError) as exc:
+            click.echo(f"Error: {exc}")
+            raise SystemExit(1)
+        _echo_chunked_result(project_root, result)
+        if result.status != "SUCCESS":
+            raise SystemExit(1)
+        return
+
+    try:
+        results = implement_tasks(
+            project_root,
+            task=task_id,
+            ai_command=ai_cmd,
+            use_derived_steps=_optional_bool(use_derived_steps),
+        )
+    except (FileNotFoundError, ValueError, CoddCLIError) as exc:
+        click.echo(f"Error: {exc}")
+        raise SystemExit(1)
+    failed = [result for result in results if result.error]
+    for result in results:
+        for generated_file in result.generated_files:
+            click.echo(f"Generated: {generated_file.relative_to(project_root)} ({result.task_id})")
+    click.echo(f"{sum(len(result.generated_files) for result in results)} files generated across {len(results) - len(failed)} task(s)")
+    if failed:
+        raise SystemExit(1)
+
+
+@implement.command("resume")
+@click.option("--task", "task_id", required=True, help="Implementation task id or title match")
+@click.option("--history", required=True, help="History id or path from a previous chunked run")
+@click.option("--path", "project_path", default=".", help="Project root directory")
+@click.option("--ai-cmd", default=None, help="Override AI CLI command")
+@click.option("--chunk-size", default=5, type=click.IntRange(min=1), show_default=True, help="Chunk size")
+@click.option(
+    "--timeout-per-chunk",
+    default=600,
+    type=click.IntRange(min=1),
+    show_default=True,
+    help="Seconds before one chunk is interrupted",
+)
+def implement_resume_cmd(
+    task_id: str,
+    history: str,
+    project_path: str,
+    ai_cmd: str | None,
+    chunk_size: int,
+    timeout_per_chunk: int,
+):
+    """Resume a chunked implementation run."""
+    project_root = Path(project_path).resolve()
+    _require_codd_dir(project_root)
+    try:
+        result = _run_chunked_implementation(
+            project_root=project_root,
+            task_id=task_id,
+            ai_cmd=ai_cmd,
+            chunk_size=chunk_size,
+            timeout_per_chunk=timeout_per_chunk,
+            history=history,
+        )
+    except (FileNotFoundError, ValueError, CoddCLIError) as exc:
+        click.echo(f"Error: {exc}")
+        raise SystemExit(1)
+    _echo_chunked_result(project_root, result)
+    if result.status != "SUCCESS":
+        raise SystemExit(1)
+
+
+def _run_chunked_implementation(
+    *,
+    project_root: Path,
+    task_id: str | None,
+    ai_cmd: str | None,
+    chunk_size: int,
+    timeout_per_chunk: int,
+    history: str | None,
+):
+    if not task_id:
+        raise ValueError("--task is required when chunked execution is enabled")
+
+    import codd.generator as generator_module
+    from codd.implementer.chunked_runner import ChunkedRunner
+
+    config = _load_optional_project_config(project_root)
+    task_item, steps = _chunked_task_and_steps(project_root, config, task_id)
+    resolved_ai_command = generator_module._resolve_ai_command(config, ai_cmd, command_name="implement")
+
+    def progress(current: int, total: int) -> None:
+        click.echo(f"Chunk {current}/{total} complete")
+
+    runner = ChunkedRunner(
+        chunk_size=chunk_size,
+        timeout_per_chunk=timeout_per_chunk,
+        progress_callback=progress,
+    )
+    if history is None:
+        return runner.run_steps(task_item, steps, resolved_ai_command, project_root)
+    return runner.resume_steps(task_item, steps, resolved_ai_command, project_root, history)
+
+
+def _chunked_task_and_steps(project_root: Path, config: dict[str, Any], task_id: str):
+    from codd.implementer import _filter_layer1_impl_steps, _filter_layer2_impl_steps
+    from codd.llm.impl_step_deriver import impl_step_cache_path, read_impl_step_cache
+
+    task_item = _implement_task_for_cli(project_root, config, task_id)
+    context = {"project_root": project_root}
+    cache_path = impl_step_cache_path(task_item, context)
+    record = read_impl_step_cache(cache_path)
+    if record is None:
+        record = read_impl_step_cache(impl_step_cache_path(task_id, context))
+    if record is None or not record.steps:
+        raise ValueError("no derived implementation steps found; run 'codd implement plan' first")
+
+    explicit = _filter_layer1_impl_steps([step for step in record.steps if not step.inferred], config)
+    implicit = _filter_layer2_impl_steps([step for step in record.steps if step.inferred], config)
+    steps = [*explicit, *implicit]
+    if not steps:
+        raise ValueError("no approved implementation steps found for chunked execution")
+    return task_item, steps
+
+
+def _echo_chunked_result(project_root: Path, result) -> None:
+    try:
+        history = result.history_path.relative_to(project_root)
+    except ValueError:
+        history = result.history_path
+    click.echo(
+        f"Chunked implementation {result.status}: "
+        f"{len(result.completed_chunks)}/{result.total_chunks} chunks; history={history}"
+    )
 
 
 @main.command()
@@ -2425,6 +2800,63 @@ def _plan_derive_provider(config: dict[str, Any]) -> str:
     return value if isinstance(value, str) and value else "subprocess_ai_command"
 
 
+def _impl_step_command(config: dict[str, Any]) -> str | None:
+    value = _nested_config_value(config, ("ai_commands", "impl_step_derive"))
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        command = value.get("command")
+        return command if isinstance(command, str) else None
+    return None
+
+
+def _impl_step_provider(config: dict[str, Any]) -> str:
+    value = _nested_config_value(config, ("ai_commands", "impl_step_derive"))
+    if isinstance(value, dict) and isinstance(value.get("provider"), str):
+        return value["provider"]
+    value = _nested_config_value(config, ("ai_commands", "impl_step_deriver_provider"))
+    return value if isinstance(value, str) and value else "subprocess_ai_command"
+
+
+def _best_practice_command(config: dict[str, Any]) -> str | None:
+    value = _nested_config_value(config, ("ai_commands", "best_practice_augment"))
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        command = value.get("command")
+        return command if isinstance(command, str) else None
+    return None
+
+
+def _best_practice_provider(config: dict[str, Any]) -> str:
+    value = _nested_config_value(config, ("ai_commands", "best_practice_augment"))
+    if isinstance(value, dict) and isinstance(value.get("provider"), str):
+        return value["provider"]
+    value = _nested_config_value(config, ("ai_commands", "best_practice_augmenter_provider"))
+    return value if isinstance(value, str) and value else "subprocess_ai_command"
+
+
+def _optional_bool(value: str | bool | None) -> bool | None:
+    if value is None or isinstance(value, bool):
+        return value
+    text = str(value).strip().casefold()
+    if text in {"1", "true", "yes", "on"}:
+        return True
+    if text in {"0", "false", "no", "off"}:
+        return False
+    raise click.BadParameter("expected true or false")
+
+
+def _implement_task_for_cli(project_root: Path, config: dict[str, Any], task_id: str):
+    from codd.implementer import _extract_all_tasks, _filter_tasks, _load_implementation_plan
+
+    plan = _load_implementation_plan(project_root, config)
+    matches = _filter_tasks(_extract_all_tasks(plan), task_id)
+    if not matches:
+        raise ValueError(f"no implementation task matched {task_id!r}")
+    return matches[0]
+
+
 def _nested_config_value(config: dict[str, Any], path: tuple[str, ...]) -> Any:
     value: Any = config
     for key in path:
@@ -2805,6 +3237,12 @@ def _load_optional_project_config(project_root: Path) -> dict[str, Any]:
 
 
 def _run_verify_once(path: str, sprint: int | None = None) -> _CliVerificationResult:
+    if get_command_handler("verify") is None:
+        from codd.repair.verify_runner import run_standalone_verify
+
+        result = run_standalone_verify(Path(path).resolve())
+        return _cli_result_from_standalone_verify(result)
+
     try:
         _run_pro_command("verify", path=path, sprint=sprint)
     except SystemExit as exc:
@@ -2822,6 +3260,14 @@ def _run_verify_once(path: str, sprint: int | None = None) -> _CliVerificationRe
     return _CliVerificationResult(passed=True, exit_code=0, failure=None)
 
 
+def _cli_result_from_standalone_verify(result: Any) -> _CliVerificationResult:
+    return _CliVerificationResult(
+        passed=bool(result.passed),
+        exit_code=0 if result.passed else 1,
+        failure=getattr(result, "failure", None),
+    )
+
+
 def _system_exit_code(exc: SystemExit) -> int:
     code = exc.code
     if code is None:

{codd_dev-1.28.0 → codd_dev-1.30.0}/codd/config.py

@@ -57,16 +57,19 @@ def _read_yaml_mapping(path: Path) -> dict[str, Any]:
     return payload
 
 
-def _deep_merge(defaults: Any, project: Any) -> Any:
+def _deep_merge(defaults: Any, project: Any, path: tuple[str, ...] = ()) -> Any:
     if isinstance(defaults, dict) and isinstance(project, dict):
         merged = deepcopy(defaults)
         for key, value in project.items():
             if key in merged:
-                merged[key] = _deep_merge(merged[key], value)
+                merged[key] = _deep_merge(merged[key], value, (*path, str(key)))
             else:
                 merged[key] = deepcopy(value)
         return merged
 
+    if path == ("coherence", "path_prefix_tolerant"):
+        return deepcopy(project)
+
     if isinstance(defaults, list) and isinstance(project, list):
         return _merge_lists(defaults, project)
 

{codd_dev-1.28.0 → codd_dev-1.30.0}/codd/dag/builder.py

@@ -124,6 +124,7 @@ def load_dag_settings(project_root: Path, settings: dict[str, Any] | None = None
     _apply_scan_patterns(merged, project_config)
     _apply_scan_patterns(merged, requested_settings)
     merged["coherence"] = _coherence_settings(project_config, requested_settings)
+    merged["extraction"] = _extraction_settings(project_config, requested_settings)
     merged.setdefault("design_doc_patterns", [])
     merged.setdefault("impl_file_patterns", [])
     merged.setdefault("test_file_patterns", [])
@@ -210,11 +211,12 @@ def render_mermaid(dag: DAG) -> str:
 def _add_design_docs(dag: DAG, project_root: Path, settings: dict[str, Any]) -> dict[str, dict[str, Any]]:
     design_docs: dict[str, dict[str, Any]] = {}
     aliases: dict[str, str] = {}
+    frontmatter_alias = _frontmatter_alias_settings(settings)
     for md_path in _glob_project_paths(project_root, settings.get("design_doc_patterns", [])):
         if not md_path.is_file():
             continue
         node_id = _relative_id(md_path, project_root)
-        metadata = extract_design_doc_metadata(md_path)
+        metadata = extract_design_doc_metadata(md_path, frontmatter_alias=frontmatter_alias)
         attributes = metadata.get("attributes") or {}
         _validate_design_doc_journey_attributes(node_id, attributes)
         _add_node_once(
@@ -1180,6 +1182,31 @@ def _coherence_settings(*configs: dict[str, Any]) -> dict[str, Any]:
     return coherence
 
 
+def _extraction_settings(*configs: dict[str, Any]) -> dict[str, Any]:
+    extraction: dict[str, Any] = {"frontmatter_alias": {}}
+    for config in configs:
+        section = config.get("extraction", {})
+        if isinstance(section, dict):
+            extraction = _deep_merge(extraction, section)
+    if not isinstance(extraction.get("frontmatter_alias"), dict):
+        extraction["frontmatter_alias"] = {}
+    return extraction
+
+
+def _frontmatter_alias_settings(settings: dict[str, Any]) -> dict[str, str]:
+    extraction = settings.get("extraction", {})
+    if not isinstance(extraction, dict):
+        return {}
+    aliases = extraction.get("frontmatter_alias", {})
+    if not isinstance(aliases, dict):
+        return {}
+    return {
+        str(alias_key).strip(): str(canonical_key).strip()
+        for alias_key, canonical_key in aliases.items()
+        if str(alias_key).strip() and str(canonical_key).strip()
+    }
+
+
 def _capability_patterns(settings: dict[str, Any]) -> dict[str, Any]:
     coherence = settings.get("coherence", {})
     if not isinstance(coherence, dict):