sourcecode 0.28.0__tar.gz → 0.30.0__tar.gz

sourcecode-0.30.0/.agents/skills/source-command-gsd-join-discord/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: "source-command-gsd-join-discord"
+description: "Join the GSD Discord community"
+---
+
+# source-command-gsd-join-discord
+
+Use this skill when the user asks to run the migrated source command `gsd-join-discord`.
+
+## Command Template
+
+<objective>
+Display the Discord invite link for the GSD community server.
+</objective>
+
+<output>
+# Join the GSD Discord
+
+Connect with other GSD users, get help, share what you're building, and stay updated.
+
+**Invite link:** https://discord.gg/mYgfVNfA2r
+
+Click the link or paste it into your browser to join.
+</output>

sourcecode-0.30.0/.agents/skills/source-command-gsd-review-backlog/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: "source-command-gsd-review-backlog"
+description: "Review and promote backlog items to active milestone"
+---
+
+# source-command-gsd-review-backlog
+
+Use this skill when the user asks to run the migrated source command `gsd-review-backlog`.
+
+## Command Template
+
+<objective>
+Review all 999.x backlog items and optionally promote them into the active
+milestone sequence or remove stale entries.
+</objective>
+
+<process>
+
+1. **List backlog items:**
+   ```bash
+   ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found"
+   ```
+
+2. **Read ROADMAP.md** and extract all 999.x phase entries:
+   ```bash
+   cat .planning/ROADMAP.md
+   ```
+   Show each backlog item with its description, any accumulated context (CONTEXT.md, RESEARCH.md), and creation date.
+
+3. **Present the list to the user** via AskUserQuestion:
+   - For each backlog item, show: phase number, description, accumulated artifacts
+   - Options per item: **Promote** (move to active), **Keep** (leave in backlog), **Remove** (delete)
+
+4. **For items to PROMOTE:**
+   - Find the next sequential phase number in the active milestone
+   - Rename the directory from `999.x-slug` to `{new_num}-slug`:
+     ```bash
+     NEW_NUM=$(node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" phase add "${DESCRIPTION}" --raw)
+     ```
+   - Move accumulated artifacts to the new phase directory
+   - Update ROADMAP.md: move the entry from `## Backlog` section to the active phase list
+   - Remove `(BACKLOG)` marker
+   - Add appropriate `**Depends on:**` field
+
+5. **For items to REMOVE:**
+   - Delete the phase directory
+   - Remove the entry from ROADMAP.md `## Backlog` section
+
+6. **Commit changes:**
+   ```bash
+   node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" commit "docs: review backlog — promoted N, removed M" --files .planning/ROADMAP.md
+   ```
+
+7. **Report summary:**
+   ```
+   ## 📋 Backlog Review Complete
+
+   Promoted: {list of promoted items with new phase numbers}
+   Kept: {list of items remaining in backlog}
+   Removed: {list of deleted items}
+   ```
+
+</process>

sourcecode-0.30.0/.agents/skills/source-command-gsd-workstreams/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: "source-command-gsd-workstreams"
+description: "Manage parallel workstreams — list, create, switch, status, progress, complete, and resume"
+---
+
+# source-command-gsd-workstreams
+
+Use this skill when the user asks to run the migrated source command `gsd-workstreams`.
+
+## Command Template
+
+# /gsd-workstreams
+
+Manage parallel workstreams for concurrent milestone work.
+
+## Usage
+
+`/gsd-workstreams [subcommand] [args]`
+
+### Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `list` | List all workstreams with status |
+| `create <name>` | Create a new workstream |
+| `status <name>` | Detailed status for one workstream |
+| `switch <name>` | Set active workstream |
+| `progress` | Progress summary across all workstreams |
+| `complete <name>` | Archive a completed workstream |
+| `resume <name>` | Resume work in a workstream |
+
+## Step 1: Parse Subcommand
+
+Parse the user's input to determine which workstream operation to perform.
+If no subcommand given, default to `list`.
+
+## Step 2: Execute Operation
+
+### list
+Run: `node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" workstream list --raw --cwd "$CWD"`
+Display the workstreams in a table format showing name, status, current phase, and progress.
+
+### create
+Run: `node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" workstream create <name> --raw --cwd "$CWD"`
+After creation, display the new workstream path and suggest next steps:
+- `/gsd-new-milestone --ws <name>` to set up the milestone
+
+### status
+Run: `node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" workstream status <name> --raw --cwd "$CWD"`
+Display detailed phase breakdown and state information.
+
+### switch
+Run: `node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" workstream set <name> --raw --cwd "$CWD"`
+Also set `GSD_WORKSTREAM` for the current session when the runtime supports it.
+If the runtime exposes a session identifier, GSD also stores the active workstream
+session-locally so concurrent sessions do not overwrite each other.
+
+### progress
+Run: `node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" workstream progress --raw --cwd "$CWD"`
+Display a progress overview across all workstreams.
+
+### complete
+Run: `node "C:/Users/dominique.haroun_m3i/Documents/workspace/test-gsd/.Codex/get-shit-done/bin/gsd-tools.cjs" workstream complete <name> --raw --cwd "$CWD"`
+Archive the workstream to milestones/.
+
+### resume
+Set the workstream as active and suggest `/gsd-resume-work --ws <name>`.
+
+## Step 3: Display Results
+
+Format the JSON output from gsd-tools into a human-readable display.
+Include the `${GSD_WS}` flag in any routing suggestions.

{sourcecode-0.28.0 → sourcecode-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.28.0
+Version: 0.30.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004

{sourcecode-0.28.0 → sourcecode-0.30.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "0.28.0"
+version = "0.30.0"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-0.28.0 → sourcecode-0.30.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Genera mapas de contexto estructurado para agentes IA."""
 
-__version__ = "0.28.0"
+__version__ = "0.30.0"

{sourcecode-0.28.0 → sourcecode-0.30.0}/src/sourcecode/architecture_analyzer.py

@@ -12,6 +12,10 @@ from sourcecode.schema import (
     SourceMap,
 )
 
+_WORKSPACE_CONFIG_FILES: frozenset[str] = frozenset({
+    "turbo.json", "nx.json", "pnpm-workspace.yaml", "lerna.json", "rush.json",
+})
+
 _TOOLING_PREFIXES = (
     ".claude/",
     ".vscode/",
@@ -34,6 +38,18 @@ _CODE_EXTENSIONS = {
 _GENERIC_NAMES = {"utils", "helpers", "common", "shared", "misc", "core", "root", ""}
 
 _TEST_DIRS: frozenset[str] = frozenset({"tests", "test", "spec", "specs", "__tests__", "e2e"})
+_BENCHMARK_DIRS: frozenset[str] = frozenset({
+    "benchmark", "benchmarks", "bench",
+    "example", "examples",
+    "demo", "demos",
+    "playground", "playgrounds",
+    "fixture", "fixtures",
+    "sandbox",
+})
+_DOCS_DIRS: frozenset[str] = frozenset({"docs", "doc", "documentation", "wiki"})
+_TOOLING_DIRS: frozenset[str] = frozenset({"scripts", "script", "tools", "tool", "ci"})
+# All dirs that are not part of the runtime source architecture
+_NON_SOURCE_DIRS: frozenset[str] = _TEST_DIRS | _BENCHMARK_DIRS | _DOCS_DIRS | _TOOLING_DIRS
 
 # Exact file stems that signal a specific architectural layer
 _LAYER_STEM_EXACT: dict[str, str] = {
@@ -177,15 +193,35 @@ class ArchitectureAnalyzer:
             elif pattern == "unknown":
                 limitations.append("Patron de capas no reconocido: estructura de directorios sin senales claras")
 
+        # Step 3b: monorepo override — workspace config is hard evidence
+        if self._has_workspace_config(sm.file_paths) and pattern not in (
+            "monorepo", "cqrs", "clean", "onion", "hexagonal"
+        ):
+            mono_layers = self._detect_monorepo_packages(filtered)
+            if mono_layers or pattern in (None, "unknown", "flat", "modular", "layered"):
+                pattern = "monorepo"
+                layers = mono_layers
+                limitations.append(
+                    "Workspace config detectado — arquitectura refleja topologia de paquetes"
+                )
+
         # Step 4: bounded context inference
         bounded_contexts = self._infer_bounded_contexts(domains, graph)
 
-        # Overall confidence
+        # Overall confidence — based on domain quality, not raw count
         confidence: Literal["high", "medium", "low"]
+        strong_domains = [d for d in domains if d.confidence in ("high", "medium")]
+        all_layers_weak = layers and all(l.confidence == "low" for l in layers)
         if pattern not in (None, "unknown", "flat"):
-            # A recognised pattern was detected — at least medium confidence
-            confidence = "high" if len(domains) >= 3 else "medium"
-        elif len(domains) >= 1:
+            if all_layers_weak:
+                # Layers came from file-naming heuristic only, not directory structure
+                confidence = "medium"
+                limitations.append(
+                    "Patron inferido de nombres de archivo — sin estructura de directorios confirmatoria"
+                )
+            else:
+                confidence = "high" if len(strong_domains) >= 3 else "medium"
+        elif len(strong_domains) >= 1:
             confidence = "medium"
         else:
             confidence = "low"
@@ -217,6 +253,10 @@ class ArchitectureAnalyzer:
             norm = p.replace("\\", "/")
             if self._is_tooling(norm):
                 continue
+            # Exclude non-source dirs at every path segment (benchmarks, docs, tests, scripts…)
+            parts = norm.split("/")
+            if any(part.lower() in _NON_SOURCE_DIRS for part in parts[:-1]):
+                continue
             ext = Path(norm).suffix.lower()
             if ext not in _CODE_EXTENSIONS:
                 continue
@@ -250,6 +290,8 @@ class ArchitectureAnalyzer:
         for name, files in groups.items():
             if len(files) < 2:
                 continue
+            if name.lower() in _NON_SOURCE_DIRS:
+                continue
             role = DOMAIN_ROLES.get(name, "")
             domain_confidence: Literal["high", "medium", "low"]
             if name in DOMAIN_ROLES:
@@ -262,10 +304,10 @@ class ArchitectureAnalyzer:
         return domains
 
     def _detect_layers(self, paths: list[str]) -> tuple[str, list[ArchitectureLayer]]:
-        # Exclude test paths so test directories don't skew layer scoring
+        # Exclude non-source paths (tests, benchmarks, docs, tooling) from layer scoring
         source_paths = [
             p for p in paths
-            if not any(part.lower() in _TEST_DIRS for part in p.replace("\\", "/").split("/"))
+            if not any(part.lower() in _NON_SOURCE_DIRS for part in p.replace("\\", "/").split("/"))
         ]
         if not source_paths:
             return "unknown", []
@@ -360,7 +402,7 @@ class ArchitectureAnalyzer:
             parts = p.replace("\\", "/").split("/")
             if len(parts) >= 2 and parts[-1].lower() in _ENTRY_FILES:
                 top = parts[0]
-                if top.lower() not in _SRC_TRANSPARENT and top.lower() not in _TEST_DIRS:
+                if top.lower() not in _SRC_TRANSPARENT and top.lower() not in _NON_SOURCE_DIRS:
                     entry_dirs.setdefault(top, []).append(p)
         if len(entry_dirs) >= 4:
             return "microservices", [
@@ -394,7 +436,7 @@ class ArchitectureAnalyzer:
         non_empty = {k: v for k, v in layer_files.items() if v}
         if len(non_empty) >= 2:
             return "layered", [
-                ArchitectureLayer(name=k, pattern="layered", files=v, confidence="medium")
+                ArchitectureLayer(name=k, pattern="layered", files=v, confidence="low")
                 for k, v in non_empty.items()
             ]
         return None
@@ -412,19 +454,42 @@ class ArchitectureAnalyzer:
             parts = p.replace("\\", "/").split("/")
             for part in parts[:-1]:
                 if (part not in _SRC_TRANSPARENT
-                        and part.lower() not in _TEST_DIRS
+                        and part.lower() not in _NON_SOURCE_DIRS
                         and part.lower() not in _GENERIC_NAMES):
                     module_files.setdefault(part, []).append(p)
                     break
 
-        meaningful = {k: v for k, v in module_files.items() if len(v) >= 2}
+        meaningful = {k: v for k, v in module_files.items() if len(v) >= 3}
         if len(meaningful) >= 2:
             return "modular", [
-                ArchitectureLayer(name=k, pattern="modular", files=v, confidence="medium")
+                ArchitectureLayer(name=k, pattern="modular", files=v, confidence="low")
                 for k, v in meaningful.items()
             ]
         return None
 
+    def _has_workspace_config(self, file_paths: list[str]) -> bool:
+        for path in file_paths:
+            parts = path.replace("\\", "/").split("/")
+            if len(parts) == 1 and parts[0] in _WORKSPACE_CONFIG_FILES:
+                return True
+        return False
+
+    def _detect_monorepo_packages(self, paths: list[str]) -> list[ArchitectureLayer]:
+        """Find workspace packages (packages/*, apps/*, libs/*) in a monorepo."""
+        _WORKSPACE_ROOTS = {"packages", "apps", "libs", "applications"}
+        groups: dict[str, list[str]] = {}
+        for p in paths:
+            parts = p.replace("\\", "/").split("/")
+            if len(parts) >= 2 and parts[0].lower() in _WORKSPACE_ROOTS:
+                key = f"{parts[0]}/{parts[1]}"
+                groups.setdefault(key, []).append(p)
+        result = [
+            ArchitectureLayer(name=k, pattern="monorepo", files=v, confidence="medium")
+            for k, v in groups.items()
+            if len(v) >= 2
+        ]
+        return result[:16]
+
     def _infer_bounded_contexts(
         self,
         domains: list[ArchitectureDomain],

{sourcecode-0.28.0 → sourcecode-0.30.0}/src/sourcecode/architecture_summary.py

@@ -5,6 +5,7 @@ import re
 from pathlib import Path
 from typing import Any
 
+from sourcecode.entrypoint_classifier import is_production_entry_point
 from sourcecode.schema import EntryPoint, SourceMap, StackDetection
 from sourcecode.tree_utils import flatten_file_tree
 
@@ -63,11 +64,8 @@ class ArchitectureSummarizer:
             entry for entry in sm.entry_points
             if not self._is_tooling_path(entry.path)
             and not self._is_auxiliary_path(entry.path)
-            and entry.entrypoint_type not in ("benchmark", "example")
+            and is_production_entry_point(entry)
         ]
-        if not entry_points:
-            fallback = self._infer_fallback_entry_points(file_paths, sm.stacks)
-            entry_points = fallback[:1]
 
         lang_lines: list[str] = []
         if entry_points:
@@ -280,8 +278,7 @@ class ArchitectureSummarizer:
         if modules:
             formatted = self._format_module_list([self._module_label(module) for module in modules])
             if formatted:
-                lines.append(f"Orquesta modulos internos: {formatted}.")
-        lines.append("Produce la salida principal del entry point JavaScript/TypeScript detectado.")
+                lines.append(f"Imports internos del entry point: {formatted}.")
         return lines
 
     def _summarize_java_entry(self, path: str, content: str, stacks: list[StackDetection]) -> list[str]:
@@ -344,8 +341,7 @@ class ArchitectureSummarizer:
         if internal:
             formatted = self._format_module_list([self._module_label(module) for module in internal])
             if formatted:
-                lines.append(f"Orquesta paquetes internos: {formatted}.")
-        lines.append("Produce la salida principal del binario Go detectado.")
+                lines.append(f"Imports internos del binario Go: {formatted}.")
         return lines
 
     def _describe_entry_point(self, entry_point: EntryPoint, project_type: str | None) -> str:

{sourcecode-0.28.0 → sourcecode-0.30.0}/src/sourcecode/classifier.py

@@ -45,8 +45,12 @@ class TypeClassifier:
         primary_stack = self._select_primary_stack(enriched, project_type)
 
         final_stacks: list[StackDetection] = []
+        primary_assigned = False
         for stack in enriched:
-            final_stacks.append(replace(stack, primary=(stack.stack == primary_stack)))
+            is_primary = stack.stack == primary_stack and not primary_assigned
+            if is_primary:
+                primary_assigned = True
+            final_stacks.append(replace(stack, primary=is_primary))
         return final_stacks, project_type
 
     def _enrich_stack(

{sourcecode-0.28.0 → sourcecode-0.30.0}/src/sourcecode/cli.py

@@ -1,13 +1,141 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import time
 from pathlib import Path
 from typing import Any, Optional, cast
 
-import typer
+import typer
+
+from sourcecode import __version__
+from sourcecode.entrypoint_classifier import is_production_entry_point, normalize_entry_point
 
-from sourcecode import __version__
+
+# ---------------------------------------------------------------------------
+# Analyzer fingerprints — short hashes of each analyzer's key rule constants.
+# A change in heuristics, filter lists, or pattern maps changes the hash,
+# making it immediately visible that two runs used different rule versions
+# even if the semver string is the same.
+# ---------------------------------------------------------------------------
+
+def _fingerprint(*objects: object) -> str:
+    raw = json.dumps([repr(o) for o in objects], sort_keys=True)
+    return hashlib.sha256(raw.encode()).hexdigest()[:8]
+
+
+def _compute_analyzer_fingerprints() -> dict[str, str]:
+    from sourcecode.detectors.heuristic import (
+        _AUXILIARY_DIRS as _HEUR_AUX,
+        _ENTRYPOINT_NAMES,
+        _EXTENSION_MAP,
+    )
+    from sourcecode.detectors.nodejs import _FRAMEWORK_MAP, NodejsDetector
+    from sourcecode.confidence_analyzer import (
+        _AUXILIARY_DIR_PREFIXES,
+        _HARD_SOURCES,
+        _SOFT_SOURCES,
+    )
+    from sourcecode.architecture_analyzer import (
+        _BENCHMARK_DIRS,
+        _NON_SOURCE_DIRS,
+        LAYER_PATTERNS,
+    )
+
+    return {
+        "heuristic": _fingerprint(_EXTENSION_MAP, _ENTRYPOINT_NAMES, sorted(_HEUR_AUX)),
+        "nodejs": _fingerprint(_FRAMEWORK_MAP, sorted(NodejsDetector._AUXILIARY_DIRS)),
+        "confidence": _fingerprint(sorted(_AUXILIARY_DIR_PREFIXES), sorted(_HARD_SOURCES), sorted(_SOFT_SOURCES)),
+        "architecture": _fingerprint(sorted(_BENCHMARK_DIRS), sorted(_NON_SOURCE_DIRS), list(LAYER_PATTERNS.keys())),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Pipeline trace collector
+# ---------------------------------------------------------------------------
+
+class _TraceCollector:
+    """Lightweight collector for pipeline trace events."""
+
+    def __init__(self, enabled: bool = False) -> None:
+        self._enabled = enabled
+        self._events: list[dict[str, Any]] = []
+
+    def emit(
+        self,
+        stage: str,
+        component: str,
+        action: str,
+        target: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> None:
+        if not self._enabled:
+            return
+        self._events.append({
+            "stage": stage,
+            "component": component,
+            "action": action,
+            **({"target": target} if target else {}),
+            **({"reason": reason} if reason else {}),
+        })
+
+    def build_trace(self) -> "PipelineTrace":
+        from sourcecode.schema import PipelineEvent, PipelineTrace
+        events = [
+            PipelineEvent(
+                stage=e["stage"],
+                component=e["component"],
+                action=e["action"],
+                target=e.get("target"),
+                reason=e.get("reason"),
+            )
+            for e in self._events
+        ]
+        return PipelineTrace(requested=True, events=events)
+
+
+# ---------------------------------------------------------------------------
+# E2E pipeline coherence check
+# ---------------------------------------------------------------------------
+
+def _check_pipeline_coherence(sm: "SourceMap") -> list[str]:  # type: ignore[name-defined]
+    """Verify no contradictory states exist between analyzers.
+
+    Returns a list of human-readable violation strings (empty when clean).
+    These are emitted to stderr as [coherence] warnings — never abort a run.
+    """
+    issues: list[str] = []
+    cs = sm.confidence_summary
+
+    if cs is not None:
+        # overall:high requires at least one manifest-detected stack
+        if cs.overall == "high":
+            manifest_stacks = [s for s in sm.stacks if s.detection_method != "heuristic"]
+            if not manifest_stacks:
+                issues.append(
+                    "[coherence] overall=high but all stacks are heuristic — "
+                    "downgrade not applied; check confidence_analyzer"
+                )
+
+        # overall:high requires at least one production entry point
+        if cs.overall == "high":
+            prod_eps = [
+                ep for ep in sm.entry_points
+                if is_production_entry_point(ep)
+            ]
+            if not prod_eps and sm.entry_points:
+                issues.append(
+                    "[coherence] overall=high but no production entry points exist — "
+                    "all detected EPs are auxiliary (benchmark/example/dev)"
+                )
+
+        # entry_point_confidence must not be high when entry_points is empty
+        if cs.entry_point_confidence == "high" and not sm.entry_points:
+            issues.append(
+                "[coherence] entry_point_confidence=high but entry_points is empty"
+            )
+
+    return issues
 
 _HELP = """\
 Deterministic codebase context for AI coding agents.
@@ -327,6 +455,11 @@ def main(
         "--agent",
         help="Modo agente: output estructurado y sin ruido para consumo por IA. Incluye identidad, entrypoints, arquitectura, dependencias clave, señales operacionales y gaps. Sin arbol de ficheros ni secciones vacias.",
     ),
+    trace_pipeline: bool = typer.Option(
+        False,
+        "--trace-pipeline",
+        help="Modo trazabilidad: incluye pipeline_trace con candidatos, filtros, descartes y origen de cada dato. Para diagnóstico de contaminación de resultados.",
+    ),
 ) -> None:
     """Analyze a repository and produce structured context for AI coding agents.
 
@@ -672,7 +805,18 @@ def main(
     )
 
     # 3. Construir el schema
-    metadata = AnalysisMetadata(analyzed_path=str(target))
+    # Compute analyzer fingerprints: short hashes of each analyzer's key rule
+    # constants so that a rule change is always visible in the output, regardless
+    # of whether the semver was bumped.
+    try:
+        _fingerprints = _compute_analyzer_fingerprints()
+    except Exception:
+        _fingerprints = {}
+
+    metadata = AnalysisMetadata(
+        analyzed_path=str(target),
+        analyzer_fingerprints=_fingerprints,
+    )
     sm = SourceMap(
         metadata=metadata,
         file_tree=file_tree,
@@ -812,6 +956,52 @@ def main(
     _conf_summary, _analysis_gaps = ConfidenceAnalyzer().analyze(sm)
     sm = _replace(sm, confidence_summary=_conf_summary, analysis_gaps=_analysis_gaps)
 
+    # E2E pipeline coherence check — emits [coherence] warnings to stderr.
+    # Catches contradictory states that can survive individual-analyzer validation.
+    for _issue in _check_pipeline_coherence(sm):
+        typer.echo(_issue, err=True)
+
+    # Build pipeline trace when --trace-pipeline is set.
+    if trace_pipeline:
+        _trace = _TraceCollector(enabled=True)
+        _trace.emit("scan", "scanner", "complete",
+                    reason=f"{len(sm.file_paths)} files, {len(manifests)} manifests")
+        for _s in sm.stacks:
+            _trace.emit("detect", _s.produced_by or "unknown", "emit_stack",
+                        target=_s.stack,
+                        reason=f"method={_s.detection_method} confidence={_s.confidence}")
+        for _ep in sm.entry_points:
+            _trace.emit("detect", _ep.produced_by or "unknown", "emit_ep",
+                        target=_ep.path,
+                        reason=f"type={_ep.entrypoint_type} confidence={_ep.confidence} reason={_ep.reason}")
+        # Record EPs filtered from agent_view (benchmark/example with path-auxiliary parts)
+        _aux_parts = frozenset({
+            "benchmark", "benchmarks", "bench", "demo", "demos",
+            "example", "examples", "docs", "doc", "fixtures", "fixture",
+        })
+        for _ep in sm.entry_points:
+            _normalized_ep = normalize_entry_point(_ep)
+            _ep_type = _normalized_ep.entrypoint_type
+            _path_parts = _ep.path.replace("\\", "/").lower().split("/")
+            _filtered = (
+                _normalized_ep.classification != "production"
+                or any(p in _aux_parts for p in _path_parts)
+            )
+            if _filtered:
+                _trace.emit("output", "agent_view", "filter_ep",
+                            target=_ep.path,
+                            reason=f"entrypoint_type={_ep_type} (auxiliary)")
+        if sm.confidence_summary is not None:
+            _cs = sm.confidence_summary
+            _trace.emit("confidence", "confidence_analyzer", "computed",
+                        reason=(
+                            f"overall={_cs.overall} "
+                            f"stack={_cs.stack_confidence} "
+                            f"ep={_cs.entry_point_confidence} "
+                            f"anomalies={len(_cs.anomalies)}"
+                        ))
+        sm = _replace(sm, pipeline_trace=_trace.build_trace())
+
     # 4. Serializar
     if agent:
         data = agent_view(sm)