atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/commands/demo.py

@@ -0,0 +1,142 @@
+"""``forge demo`` — one-shot launch-video verb.
+
+Run a preset evolve trajectory + post-run CLI invocation + DEMO.md artifact.
+Designed to produce a recordable 90-second showcase from a single command.
+
+    forge demo run                      # default preset (calc), auto provider
+    forge demo run --preset kv          # KV-store preset
+    forge demo run --preset slug --provider gemini
+    forge demo list                     # show all presets
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import click
+import typer
+
+from atomadic_forge.a1_at_functions.provider_resolver import (
+    PROVIDER_HELP,
+    resolve_provider,
+)
+from atomadic_forge.a3_og_features.demo_runner import (
+    DemoResult,
+    list_presets,
+    run_demo,
+)
+
+COMMAND_NAME = "demo"
+COMMAND_HELP = "One-shot launch-video verb: preset evolve + DEMO.md artifact."
+
+
+app = typer.Typer(no_args_is_help=True, help=COMMAND_HELP)
+
+
+def _cli_demo_failed(result: DemoResult) -> bool:
+    return bool(result.cli_demo_command) and result.cli_demo_returncode != 0
+
+
+def _resolve_provider(name: str) -> object:
+    try:
+        return resolve_provider(name)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+@app.command("list")
+def list_cmd(
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """List available demo presets."""
+    presets = list_presets()
+    if json_out:
+        typer.echo(json.dumps([
+            {"name": p.name, "headline": p.headline, "package": p.package,
+              "rounds": p.rounds, "iterations": p.iterations,
+              "target_score": p.target_score}
+            for p in presets
+        ], indent=2))
+        return
+    typer.echo("\nForge demo presets:")
+    for p in presets:
+        typer.echo(f"  {p.name:8s} — {p.headline}")
+
+
+@app.command("run")
+def run_cmd(
+    preset: Annotated[str, typer.Option("--preset", "-p",
+        help="Preset name (use `forge demo list` to see options).")] = "calc",
+    output: Annotated[Path | None, typer.Option("--output", "-o",
+        help="Output directory.  Defaults to ./forge-demo-<preset>.",
+        file_okay=False, dir_okay=True, resolve_path=True)] = None,
+    provider: Annotated[str, typer.Option("--provider",
+        help=PROVIDER_HELP)] = "auto",
+    rounds: Annotated[int | None, typer.Option("--rounds",
+        help="Override the preset's round count.")] = None,
+    iterations: Annotated[int | None, typer.Option("--iterations",
+        help="Override the preset's iterations-per-round.")] = None,
+    skip_cli_demo: Annotated[bool, typer.Option("--skip-cli-demo")] = False,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Run the preset and produce a DEMO.md artifact."""
+    llm = _resolve_provider(provider)
+    try:
+        result = run_demo(
+            preset_name=preset,
+            output=output,
+            llm=llm,                      # type: ignore[arg-type]
+            rounds=rounds,
+            iterations=iterations,
+            skip_cli_demo=skip_cli_demo,
+        )
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if json_out:
+        from dataclasses import asdict
+        typer.echo(json.dumps(asdict(result), indent=2, default=str))
+        if _cli_demo_failed(result):
+            raise typer.Exit(code=1)
+        return
+
+    arc = " → ".join(f"{s:.0f}" for s in result.score_trajectory)
+    # Showcase presets bypass the LLM entirely — print "static showcase"
+    # in the LLM slot so output stays consistent across both kinds.
+    from atomadic_forge.a3_og_features.demo_runner import get_preset
+    try:
+        preset_obj = get_preset(preset)
+    except KeyError:
+        preset_obj = None
+    is_showcase = preset_obj is not None and preset_obj.kind == "showcase"
+    llm_label = "static showcase (no LLM)" if is_showcase else llm.name
+
+    typer.echo("")
+    typer.echo("=" * 60)
+    typer.echo(f"  forge demo: {preset}")
+    typer.echo("=" * 60)
+    typer.echo("")
+    typer.echo(f"  {result.headline}")
+    typer.echo("")
+    typer.echo(f"  llm:          {llm_label}")
+    typer.echo(f"  package:      {result.package}")
+    typer.echo(f"  rounds:       {result.rounds_completed}")
+    typer.echo(f"  trajectory:   {arc}")
+    typer.echo(f"  final score:  {result.final_score:.0f}/100")
+    typer.echo(f"  converged:    {result.converged}")
+    typer.echo(f"  duration:     {result.duration_s:.1f}s")
+    typer.echo("")
+    if result.cli_demo_command:
+        typer.echo("  Generated CLI:")
+        typer.echo(f"    $ {' '.join(result.cli_demo_command)}")
+        for line in (result.cli_demo_stdout or "(no output)").splitlines()[:6]:
+            typer.echo(f"    {line}")
+        if _cli_demo_failed(result):
+            typer.echo("    generated CLI demo failed")
+        typer.echo("")
+    typer.echo(f"  Artifact:     {result.artifact_md_path}")
+    typer.echo(f"  Output:       {result.output_root}")
+    typer.echo("")
+    if _cli_demo_failed(result):
+        raise typer.Exit(code=1)

atomadic_forge/commands/emergent.py

@@ -0,0 +1,124 @@
+"""``atomadic-forge emergent`` — discover and synthesise emergent feature candidates.
+
+Once you've assimilated a sibling repo (or just grown the catalog), every
+function and class in the tier folders is a *building block*.  This command
+walks the catalog, finds typed compositions nobody wrote yet, scores them on
+cross-domain / cross-tier / purity / novelty, and (optionally) materialises
+the top candidate as a new ``a3_og_features/<name>_emergent.py`` for review.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a3_og_features.emergent_feature import EmergentScan
+
+COMMAND_NAME = "emergent"
+COMMAND_HELP = "Synthesise new feature candidates from existing components."
+
+
+app = typer.Typer(no_args_is_help=True, help=COMMAND_HELP)
+
+
+def _resolve_src_root() -> Path:
+    """Locate ``<repo>/src`` from this file's location."""
+    here = Path(__file__).resolve()
+    return here.parent.parent.parent  # commands/ -> atomadic_forge/ -> src/
+
+
+@app.command("scan")
+def scan_cmd(
+    package: Annotated[str, typer.Option("--package",
+        help="Importable package under src/ to scan.")] = "atomadic_forge",
+    src_root: Annotated[Path, typer.Option("--src-root",
+        help="Path to the src directory containing the package.",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)] = None,  # type: ignore[assignment]
+    max_depth: Annotated[int, typer.Option("--max-depth",
+        help="Max chain length.")] = 3,
+    top_n: Annotated[int, typer.Option("--top-n",
+        help="Return at most this many candidates.")] = 15,
+    require_pure: Annotated[bool, typer.Option("--require-pure",
+        help="Restrict to chains where every step is heuristically pure.")] = False,
+    no_domain_jump: Annotated[bool, typer.Option("--no-domain-jump",
+        help="Allow same-domain chains (default: require ≥2 distinct domains).")] = False,
+    json_out: Annotated[bool, typer.Option("--json",
+        help="Emit machine-readable JSON.")] = False,
+    save: Annotated[Path | None, typer.Option("--save",
+        help="Persist the report at this path.",
+        file_okay=True, dir_okay=False, resolve_path=True)] = None,
+) -> None:
+    """Walk the catalog and report top-scoring composition candidates."""
+    root = src_root or _resolve_src_root()
+    scanner = EmergentScan(src_root=root, package=package)
+    report = scanner.scan(
+        max_depth=max_depth,
+        top_n=top_n,
+        require_pure=require_pure,
+        domain_jump_required=not no_domain_jump,
+    )
+    if save:
+        EmergentScan.save_report(report, save)
+
+    if json_out:
+        typer.echo(json.dumps(report, indent=2, default=str))
+        return
+
+    typer.echo(f"\nEmergent scan — {package}")
+    typer.echo("-" * 60)
+    typer.echo(f"  catalog size:       {report['catalog_size']}")
+    typer.echo(f"  chains considered:  {report['chain_count_considered']}")
+    typer.echo(f"  domains:            {len(report['domain_inventory'])}")
+    typer.echo(f"  candidates:         {len(report['candidates'])}\n")
+
+    for i, c in enumerate(report["candidates"], 1):
+        typer.echo(f"  #{i:2d}  {c['candidate_id']}  score={c['score']:.0f}")
+        typer.echo(f"        name:  {c['name']}")
+        typer.echo(f"        tier:  {c['suggested_tier']}")
+        typer.echo(f"        chain: {' → '.join(c['chain']['domains'])}")
+        if c["novelty_signals"]:
+            typer.echo(f"        why:   {'; '.join(c['novelty_signals'])}")
+        typer.echo("")
+
+
+@app.command("synthesize")
+def synthesize_cmd(
+    candidate_id: Annotated[str, typer.Argument(
+        help="Candidate id from a prior `scan` (e.g. emrg-abc12345).")],
+    report_path: Annotated[Path, typer.Argument(
+        help="Saved report JSON from `scan --save …`.",
+        exists=True, file_okay=True, dir_okay=False, resolve_path=True)],
+    package: Annotated[str, typer.Option("--package")] = "atomadic_forge",
+    src_root: Annotated[Path | None, typer.Option("--src-root",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)] = None,
+    out_dir: Annotated[Path | None, typer.Option("--out-dir",
+        help="Where to write the new feature file (defaults to a3_og_features/).",
+        file_okay=False, dir_okay=True, resolve_path=True)] = None,
+) -> None:
+    """Materialize a candidate as a new a3 feature module."""
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    scanner = EmergentScan(src_root=src_root or _resolve_src_root(),
+                           package=package)
+    target = scanner.synthesize(candidate_id, report, out_dir=out_dir)
+    typer.echo(f"Wrote {target}")
+    typer.echo("Review carefully before committing — this is scaffolding,")
+    typer.echo("not a finished feature.  Methods need their receiver wired.")
+
+
+@app.command("show")
+def show_cmd(
+    candidate_id: Annotated[str, typer.Argument()],
+    report_path: Annotated[Path, typer.Argument(
+        exists=True, file_okay=True, dir_okay=False, resolve_path=True)],
+) -> None:
+    """Print one candidate's full chain + score breakdown."""
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    match = next((c for c in report["candidates"] if c["candidate_id"] == candidate_id),
+                 None)
+    if match is None:
+        typer.secho(f"candidate {candidate_id} not in report", fg="red", err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(match, indent=2))

atomadic_forge/commands/emergent_then_synergy.py

@@ -0,0 +1,70 @@
+"""
+Auto-synthesized synergy adapter (syn-e3622070).
+
+Producer:  emergent
+Consumer:  synergy
+Kind:      json_artifact
+Score:     42
+
+Why this synergy was detected:
+  - emergent emits json-out
+  - synergy accepts json_out
+
+Re-emit with ``atomadic-forge synergy implement <id>`` after surfaces change.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+COMMAND_NAME = 'emergent-then-synergy'
+COMMAND_HELP = 'Run emergent to emit a JSON artifact, then feed it to synergy for the next phase.'
+
+app = typer.Typer(no_args_is_help=False, help='Run emergent to emit a JSON artifact, then feed it to synergy for the next phase.')
+
+@app.callback(invoke_without_command=True)
+def run(
+    ctx: typer.Context,
+    producer_args: Annotated[list[str] | None, typer.Argument(
+        help='Args forwarded to the producer command.')] = None,
+) -> None:
+    """Run emergent → capture artifact → feed to synergy."""
+    if ctx.invoked_subcommand is not None:
+        return
+    producer_args = producer_args or []
+    with tempfile.TemporaryDirectory(prefix='synergy-') as tmp:
+        artifact = Path(tmp) / 'producer.json'
+        cmd_a = [sys.executable, '-m',
+                 'atomadic_forge.a4_sy_orchestration.cli',
+                 'emergent', *producer_args,
+                 '--json-out', str(artifact)]
+        rc = subprocess.run(cmd_a, capture_output=False).returncode
+        if rc != 0:
+            typer.secho(f'producer exited {rc}', fg='red', err=True)
+            raise typer.Exit(rc)
+        cmd_b = [sys.executable, '-m',
+                 'atomadic_forge.a4_sy_orchestration.cli',
+                 'synergy', str(artifact)]
+        rc = subprocess.run(cmd_b, capture_output=False).returncode
+        if rc != 0:
+            typer.secho(f'consumer exited {rc}', fg='red', err=True)
+            raise typer.Exit(rc)
+        try:
+            data = json.loads(artifact.read_text(encoding='utf-8'))
+        except (OSError, json.JSONDecodeError):
+            data = None
+        typer.echo(json.dumps({
+            'synergy': 'syn-e3622070',
+            'producer': 'emergent',
+            'consumer': 'synergy',
+            'artifact_size_bytes': artifact.stat().st_size,
+            'producer_payload_keys': sorted(data.keys()) if isinstance(data, dict) else None,
+        }, indent=2))
+

atomadic_forge/commands/evolve.py

@@ -0,0 +1,122 @@
+"""``forge evolve`` — recursive self-improvement: iterate that iterates.
+
+Each round, the package generated last time becomes the seed catalog for
+the next round.  The LLM sees its own prior output as building blocks via
+emergent + reuse feedback.  The catalog grows; compositions multiply; the
+LLM (in principle) gets richer context every round.
+
+This is **narrow self-improvement** — same shape as AlphaEvolve / Voyager.
+NOT a path to AGI.  Bounded by underlying LLM quality and the realism of
+the certify/wire signals.  Honest about what it is.
+
+Examples
+--------
+    forge evolve "discord bot that summarises PDFs" ./out --auto 5
+
+    # Sit-back mode: 8 rounds, 4 LLM turns per round, max score 90:
+    forge evolve "..." ./out --auto 8 --target-score 90
+
+    # Stop early if score regresses:
+    forge evolve "..." ./out --auto 5 --stop-on-regression
+
+    # Resume from an existing growing seed:
+    forge evolve "..." ./out --auto 3 --seed ./out/src/evolved
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import click
+import typer
+
+from atomadic_forge.a1_at_functions.provider_resolver import (
+    PROVIDER_HELP,
+    resolve_provider,
+)
+from atomadic_forge.a3_og_features.forge_evolve import run_evolve
+
+COMMAND_NAME = "evolve"
+COMMAND_HELP = ("Recursive self-improvement: run iterate N times, each "
+                "round seeded by the previous round's growing catalog.")
+
+
+app = typer.Typer(no_args_is_help=True, help=COMMAND_HELP)
+
+
+def _resolve_provider(name: str) -> object:
+    try:
+        return resolve_provider(name)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+@app.command("run")
+def run_cmd(
+    intent: Annotated[str, typer.Argument(help="One-paragraph description.")],
+    output: Annotated[Path, typer.Argument(
+        file_okay=False, dir_okay=True, resolve_path=True)],
+    auto: Annotated[int, typer.Option("--auto",
+        help="Number of evolve rounds — sit-back parameter.")] = 3,
+    iterations_per_round: Annotated[int, typer.Option("--iterations")] = 4,
+    target_score: Annotated[float, typer.Option("--target-score")] = 75.0,
+    package: Annotated[str, typer.Option("--package")] = "evolved",
+    seed_repo: Annotated[Path | None, typer.Option("--seed",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)] = None,
+    provider: Annotated[str, typer.Option("--provider",
+        help=PROVIDER_HELP)] = "auto",
+    language: Annotated[str, typer.Option("--language", "-l",
+        help="Output language: python | javascript | typescript")] = "python",
+    stop_on_regression: Annotated[bool, typer.Option("--stop-on-regression")] = False,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Run the recursive evolve loop and watch the show."""
+    output.mkdir(parents=True, exist_ok=True)
+    llm = _resolve_provider(provider)
+    try:
+        report = run_evolve(
+            intent,
+            output=output,
+            package=package,
+            seed_repo=seed_repo,
+            llm=llm,                       # type: ignore[arg-type]
+            rounds=auto,
+            iterations_per_round=iterations_per_round,
+            target_score=target_score,
+            stop_on_regression=stop_on_regression,
+            language=language,
+        )
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if json_out:
+        typer.echo(json.dumps(report, indent=2, default=str))
+        return
+
+    # Output path varies by language: python uses src/, JS/TS uses pkg root directly.
+    lang = report.get("language", "python")
+    pkg_path = (f"src/{report['package']}" if lang == "python"
+                else report["package"])
+    typer.echo(f"\nForge evolve — {auto} round(s) requested, "
+                f"{report['rounds_completed']} completed")
+    typer.echo("-" * 60)
+    typer.echo(f"  llm:      {report['llm']}")
+    typer.echo(f"  package:  {report['package']}")
+    typer.echo(f"  language: {lang}")
+    typer.echo(f"  output:   {report['output_root']}/{pkg_path}")
+    typer.echo("")
+    typer.echo("  Round │ Iters │ Files │ Symbols (Δ)    │ Score (Δ)      │ Wire │ Conv")
+    typer.echo("  ──────┼───────┼───────┼────────────────┼────────────────┼──────┼──────")
+    for r in report["rounds"]:
+        sym = f"{r['symbol_count']:3d} ({r['delta_symbols']:+d})"
+        sco = f"{r['score']:.0f} ({r['delta_score']:+.1f})"
+        wire = r["wire_verdict"][:4]
+        conv = "Y" if r["converged"] else "n"
+        typer.echo(f"   {r['round']:3d}  │  {r['iterations']:3d}  │ {r['files_written']:3d}   │ "
+                    f"{sym:<14s} │ {sco:<14s} │ {wire:<4s} │  {conv}")
+    typer.echo("")
+    typer.echo(f"  final score:    {report['final_score']:.0f}/100")
+    typer.echo(f"  final symbols:  {report['final_symbol_count']}")
+    typer.echo(f"  trajectory:     {report['score_trajectory']}")
+    typer.echo(f"  converged:      {report['converged']}")

atomadic_forge/commands/evolve_then_iterate.py

@@ -0,0 +1,70 @@
+"""
+Auto-synthesized synergy adapter (syn-f69aff67).
+
+Producer:  evolve
+Consumer:  iterate
+Kind:      json_artifact
+Score:     39
+
+Why this synergy was detected:
+  - evolve emits json-out
+  - iterate accepts json_out
+
+Re-emit with ``atomadic-forge synergy implement <id>`` after surfaces change.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+COMMAND_NAME = 'evolve-then-iterate'
+COMMAND_HELP = 'Run evolve to emit a JSON artifact, then feed it to iterate for the next phase.'
+
+app = typer.Typer(no_args_is_help=False, help='Run evolve to emit a JSON artifact, then feed it to iterate for the next phase.')
+
+@app.callback(invoke_without_command=True)
+def run(
+    ctx: typer.Context,
+    producer_args: Annotated[list[str] | None, typer.Argument(
+        help='Args forwarded to the producer command.')] = None,
+) -> None:
+    """Run evolve → capture artifact → feed to iterate."""
+    if ctx.invoked_subcommand is not None:
+        return
+    producer_args = producer_args or []
+    with tempfile.TemporaryDirectory(prefix='synergy-') as tmp:
+        artifact = Path(tmp) / 'producer.json'
+        cmd_a = [sys.executable, '-m',
+                 'atomadic_forge.a4_sy_orchestration.cli',
+                 'evolve', *producer_args,
+                 '--json-out', str(artifact)]
+        rc = subprocess.run(cmd_a, capture_output=False).returncode
+        if rc != 0:
+            typer.secho(f'producer exited {rc}', fg='red', err=True)
+            raise typer.Exit(rc)
+        cmd_b = [sys.executable, '-m',
+                 'atomadic_forge.a4_sy_orchestration.cli',
+                 'iterate', str(artifact)]
+        rc = subprocess.run(cmd_b, capture_output=False).returncode
+        if rc != 0:
+            typer.secho(f'consumer exited {rc}', fg='red', err=True)
+            raise typer.Exit(rc)
+        try:
+            data = json.loads(artifact.read_text(encoding='utf-8'))
+        except (OSError, json.JSONDecodeError):
+            data = None
+        typer.echo(json.dumps({
+            'synergy': 'syn-f69aff67',
+            'producer': 'evolve',
+            'consumer': 'iterate',
+            'artifact_size_bytes': artifact.stat().st_size,
+            'producer_payload_keys': sorted(data.keys()) if isinstance(data, dict) else None,
+        }, indent=2))
+

atomadic_forge/commands/feature_then_emergent.py

@@ -0,0 +1,111 @@
+"""``atomadic-forge feature-then-emergent`` — universal pipeline:
+run any feature's JSON-emitting verb, then fan its payload into emergent scan.
+
+This is the Item-1 synergy from the roadmap: every feature in the catalog
+becomes a producer; emergent scan becomes the universal consumer.  The
+adapter is generic (it doesn't bake in any single feature) so adding a new
+feature later automatically participates without code changes.
+
+Examples:
+    atomadic-forge feature-then-emergent scout C:/path/to/repo --no-llm
+    atomadic-forge feature-then-emergent commandsmith discover --json
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a3_og_features.emergent_pipeline_integration import (
+    emergent_overlay_for_path,
+)
+
+COMMAND_NAME = "feature-then-emergent"
+COMMAND_HELP = ("Run any feature, then fan its JSON output into emergent "
+                "scan to surface novel compositions.")
+
+
+app = typer.Typer(no_args_is_help=False, help=COMMAND_HELP)
+
+
+def _try_extract_repo_root(payload: dict) -> Path | None:
+    """Try to find a repo path in the producer's JSON payload.
+
+    We probe a few common keys (``repo``, ``src_root``, ``project_path``,
+    ``primary_root``).  This makes the adapter useful even when the producer
+    isn't scout-shaped.
+    """
+    for key in ("src_root", "primary_root", "repo", "project_path", "repo_root"):
+        if key in payload and isinstance(payload[key], str):
+            p = Path(payload[key])
+            if p.exists():
+                return p
+    return None
+
+
+@app.command("run",
+             context_settings={"allow_extra_args": True,
+                               "ignore_unknown_options": True})
+def run(
+    ctx: typer.Context,
+    feature: Annotated[str, typer.Argument(
+        help="ASS-ADE verb to run as the producer (e.g. scout, commandsmith).")],
+    explicit_repo: Annotated[Path | None, typer.Option("--repo",
+        help="Override repo root used for the emergent scan; otherwise inferred.",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)] = None,
+    package: Annotated[str, typer.Option("--package")] = "atomadic_forge",
+    top_n: Annotated[int, typer.Option("--top-n")] = 10,
+) -> None:
+    """Run ``atomadic-forge <feature> <args>``, then run emergent scan over its scope.
+
+    Forwarded args go after ``--``.  Example::
+
+        atomadic-forge feature-then-emergent run scout --top-n 3 -- C:/repo --no-llm
+        # → producer args = ["C:/repo", "--no-llm"], adapter top_n = 3
+    """
+    feature_args = list(ctx.args)  # everything after the recognised options
+    with tempfile.TemporaryDirectory(prefix="feature-emergent-") as tmp:
+        artifact = Path(tmp) / "producer.json"
+        cmd = [sys.executable, "-m",
+               "atomadic_forge.a4_sy_orchestration.unified_cli",
+               feature, *feature_args, "--json-out", str(artifact)]
+        rc = subprocess.run(cmd, capture_output=False).returncode
+        if rc != 0:
+            typer.secho(f"producer `{feature}` exited {rc}", fg="red", err=True)
+            raise typer.Exit(rc)
+
+        try:
+            payload = json.loads(artifact.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            typer.secho(f"producer JSON invalid: {exc}", fg="red", err=True)
+            raise typer.Exit(2) from exc
+
+        repo_root = explicit_repo or _try_extract_repo_root(payload)
+        if repo_root is None:
+            typer.secho(
+                "could not infer a repo root from producer payload; "
+                "pass --repo PATH to set it explicitly",
+                fg="yellow", err=True,
+            )
+            raise typer.Exit(2)
+
+        overlay = emergent_overlay_for_path(repo_root, phase="scout",
+                                             package=package)
+        # Only keep the top-N candidates the operator actually wants to see.
+        overlay["candidates"] = overlay["candidates"][:top_n]
+
+        typer.echo(json.dumps({
+            "synergy": "feature_then_emergent",
+            "feature": feature,
+            "feature_args": feature_args,
+            "producer_payload_keys": sorted(payload.keys()) if isinstance(payload, dict) else None,
+            "emergent_repo_root": str(repo_root),
+            "emergent_summary": overlay.get("summary_line"),
+            "candidates": overlay["candidates"],
+        }, indent=2, default=str))