devflow-cli 6.2.0__py3-none-any.whl → 6.3.0__py3-none-any.whl

devflow_cli/__init__.py

@@ -1,6 +1,6 @@
 """devflow CLI — workflow de développement adaptatif."""
 
-VERSION = "6.2.0"
+VERSION = "6.3.0"
 
 SUPPORTED_AGENTS = ["claude-code", "codex", "cursor"]
 

devflow_cli/cli.py

@@ -18,6 +18,7 @@ from devflow_cli.commands import extension
 from devflow_cli.commands import hooks_cmd
 from devflow_cli.commands import linear
 from devflow_cli.commands import adaptive
+from devflow_cli.commands import feedback
 from devflow_cli.commands.docs_sync import docs_sync
 from devflow_cli.commands.traceability import traceability
 from devflow_cli.commands.verify import verify
@@ -58,6 +59,7 @@ app.add_typer(extension.app, name="extension")
 app.add_typer(hooks_cmd.app, name="hooks")
 app.add_typer(linear.app, name="linear")
 app.add_typer(adaptive.app, name="adaptive")
+app.add_typer(feedback.app, name="feedback")
 app.command(name="docs-sync")(docs_sync)
 app.command()(traceability)
 app.command()(verify)

devflow_cli/commands/adaptive.py

@@ -13,6 +13,7 @@ from typing import Literal, Optional
 
 import typer
 
+from devflow_cli import VERSION
 from devflow_cli.core.adaptive_workflow import (
     AdaptiveWorkflowState,
     complete_activity,
@@ -862,6 +863,7 @@ def _record_telemetry(
         return
     record = {
         "schemaVersion": 1,
+        "cliVersion": VERSION,
         "runId": run_id,
         "recordedAt": _utc_now(),
         "startedAt": attempt.get("startedAt"),

devflow_cli/commands/feedback.py

@@ -0,0 +1,282 @@
+"""devflow feedback — Consigne et exploite les retours d'usage de Devflow."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from rich.markup import escape
+
+from devflow_cli.core.feedback import (
+    FEEDBACK_SCHEMA_VERSION,
+    FEEDBACK_TYPES,
+    MIN_PREFIX,
+    SEVERITIES,
+    STATUSES,
+    append_feedback,
+    build_entry,
+    build_resolution,
+    feedback_file,
+    find_entry,
+    group_entries,
+    read_feedback,
+    render_export,
+    resolutions,
+    sanitize_text,
+    select_entries,
+    strip_controls,
+)
+from devflow_cli.utils.console import console, fail, ok
+
+app = typer.Typer(
+    help="Consigne, trie et exporte les retours d'usage de Devflow.",
+    no_args_is_help=True,
+)
+
+
+def _plain(text: object) -> str:
+    """Texte issu du fichier : sans controle ni balisage rich."""
+    return escape(strip_controls(str(text)))
+
+
+def _refuse(message: str) -> typer.Exit:
+    fail(_plain(message))
+    return typer.Exit(2)
+
+
+def _values(values: tuple[str, ...]) -> str:
+    return ", ".join(values)
+
+
+def _check_choice(option: str, value: str | None, allowed: tuple[str, ...]) -> None:
+    if value is not None and value not in allowed:
+        raise _refuse(f"{option} invalide : {value!r} (valeurs admises : {_values(allowed)})")
+
+
+def _write(record: dict[str, Any]) -> Path:
+    try:
+        return append_feedback(record)
+    except OSError as exc:
+        fail(f"Ecriture impossible dans {_plain(feedback_file())} : {_plain(exc)}")
+        raise typer.Exit(1) from exc
+
+
+@app.command()
+def add(
+    type_: Optional[str] = typer.Option(
+        None, "--type", help=f"Type de retour : {_values(FEEDBACK_TYPES)}"
+    ),
+    severity: Optional[str] = typer.Option(
+        None, "--severity", help=f"Gravite (friction seulement) : {_values(SEVERITIES)}"
+    ),
+    issue: Optional[str] = typer.Option(
+        None, "--issue", help="Issue du parcours (obligatoire pour un bilan)"
+    ),
+    what: Optional[str] = typer.Option(
+        None, "--what", help="Ce qui s'est passe (deroule du parcours pour un bilan)"
+    ),
+    impact: Optional[str] = typer.Option(
+        None, "--impact", help="Pourquoi ca coute (obligatoire pour une friction)"
+    ),
+    suggestion: Optional[str] = typer.Option(
+        None, "--suggestion", help="Piste (obligatoire pour une friction)"
+    ),
+    weighed: Optional[str] = typer.Option(
+        None, "--weighed", help="Activites qui ont pese (bilan seulement)"
+    ),
+    went_well: Optional[str] = typer.Option(
+        None, "--went-well", help="Ce qui a bien marche (bilan seulement)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Sortie JSON"),
+) -> None:
+    """Consigne un retour d'usage dans ~/.devflow/feedback.jsonl.
+
+    Seuls les secrets libellés (token=, password: …) sont masqués : ne jamais coller de jeton nu, de contenu de fichier ni de sortie d'environnement.
+    """
+    if type_ is None:
+        raise _refuse(f"--type est requis (valeurs admises : {_values(FEEDBACK_TYPES)})")
+    _check_choice("--type", type_, FEEDBACK_TYPES)
+    _check_choice("--severity", severity, SEVERITIES)
+    is_friction = type_ == "friction"
+
+    if is_friction and severity is None:
+        raise _refuse(
+            f"--severity est requis pour une friction (valeurs admises : {_values(SEVERITIES)})"
+        )
+    if not is_friction:
+        if severity is not None:
+            raise _refuse("--severity est refuse pour un bilan")
+    else:
+        for option, value in (("--weighed", weighed), ("--went-well", went_well)):
+            if value is not None:
+                raise _refuse(f"{option} est refuse pour une friction")
+
+    clean = {
+        name: sanitize_text(value) if value is not None else None
+        for name, value in (
+            ("--issue", issue),
+            ("--what", what),
+            ("--impact", impact),
+            ("--suggestion", suggestion),
+            ("--weighed", weighed),
+            ("--went-well", went_well),
+        )
+    }
+    required = ["--what", "--impact", "--suggestion"] if is_friction else [
+        "--issue", "--what", "--weighed", "--went-well",
+    ]
+    for option in required:
+        if not clean[option]:
+            raise _refuse(f"{option} est requis pour un {type_} et ne peut pas etre vide")
+
+    entry = build_entry(
+        type_,
+        severity=severity,
+        issue=clean["--issue"],
+        what=clean["--what"] or "",
+        impact=clean["--impact"],
+        suggestion=clean["--suggestion"],
+        weighed=clean["--weighed"],
+        went_well=clean["--went-well"],
+        cwd=Path.cwd(),
+    )
+    path = _write(entry)
+    if json_output:
+        typer.echo(json.dumps(entry, ensure_ascii=False, sort_keys=True))
+        return
+    ok(f"Retour {entry['id'][:MIN_PREFIX]} consigné dans {_plain(path)}")
+
+
+def _validate_filters(severity: str | None, status: str | None) -> None:
+    _check_choice("--severity", severity, SEVERITIES)
+    _check_choice("--status", status, STATUSES)
+
+
+@app.command(name="list")
+def list_feedback(
+    cli_version: Optional[str] = typer.Option(
+        None, "--cli-version", help="Version de la CLI de l'entree (egalite exacte)"
+    ),
+    project: Optional[str] = typer.Option(
+        None, "--project", help="Ne garder que les projets dont le chemin contient ce texte"
+    ),
+    severity: Optional[str] = typer.Option(
+        None, "--severity", help=f"Gravite : {_values(SEVERITIES)} (exclut les bilans)"
+    ),
+    status: Optional[str] = typer.Option(
+        None, "--status", help=f"Statut : {_values(STATUSES)}"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Sortie JSON"),
+) -> None:
+    """Liste les retours consignes, regroupes par parcours (projet + issue)."""
+    _validate_filters(severity, status)
+    records = read_feedback()
+    treated = resolutions(records)
+    groups = group_entries(select_entries(records, cli_version, project, severity, status))
+    source = feedback_file()
+
+    if json_output:
+        payload_groups = []
+        for group in groups:
+            entries = []
+            for entry in group["entries"]:
+                event = treated.get(entry["id"])
+                resolution = (
+                    {k: v for k, v in event.items()
+                     if k not in ("schemaVersion", "kind", "id", "entryId")}
+                    if event else None
+                )
+                entries.append({
+                    **entry,
+                    "status": "traité" if event else "ouvert",
+                    "resolution": resolution,
+                })
+            payload_groups.append({**group, "entries": entries})
+        typer.echo(json.dumps(
+            {"schemaVersion": FEEDBACK_SCHEMA_VERSION, "source": str(source),
+             "groups": payload_groups},
+            ensure_ascii=False,
+        ))
+        return
+
+    if not groups:
+        console.print(f"Aucun retour consigné dans {_plain(source)}.", soft_wrap=True)
+        return
+    for group in groups:
+        label = group["issueId"] or "sans issue"
+        console.print(f"{_plain(group['project'])} · {_plain(label)}", style="bold", soft_wrap=True, highlight=False)
+        for entry in group["entries"]:
+            event = treated.get(entry["id"])
+            cells = [
+                entry["id"][:MIN_PREFIX],
+                entry["type"],
+                entry.get("severity") or "-",
+                "traité" if event else "ouvert",
+                entry.get("cliVersion") or "-",
+                entry.get("activity") or "-",
+            ]
+            console.print("  " + _plain(" ".join(str(c) for c in cells)), soft_wrap=True, highlight=False)
+            console.print("    " + _plain(entry.get("what", "")), soft_wrap=True, highlight=False)
+            if event:
+                trace = f"traité par {event.get('resolvedBy', 'inconnu')} le {event.get('resolvedAt', '?')}"
+                if event.get("ref"):
+                    trace += f" (réf. {event['ref']})"
+                console.print("    " + _plain(trace), soft_wrap=True, highlight=False)
+
+
+@app.command()
+def resolve(
+    entry_id: str = typer.Argument(
+        ..., help=f"Identifiant complet ou prefixe d'au moins {MIN_PREFIX} caracteres"
+    ),
+    ref: Optional[str] = typer.Option(
+        None, "--ref", help="Reference du traitement (issue, commit)"
+    ),
+    by: Optional[str] = typer.Option(
+        None, "--by", help="Auteur du traitement (defaut : utilisateur systeme)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Sortie JSON"),
+) -> None:
+    """Marque un retour comme traite en ajoutant un evenement (rien n'est reecrit)."""
+    records = read_feedback()
+    try:
+        entry = find_entry(records, entry_id)
+    except ValueError as exc:
+        raise _refuse(str(exc)) from exc
+    if entry["id"] in resolutions(records):
+        raise _refuse(f"Le retour {entry['id'][:MIN_PREFIX]} est deja traite")
+    clean_by = None
+    if by is not None:
+        clean_by = sanitize_text(by)
+        if not clean_by:
+            raise _refuse("--by ne peut pas etre vide")
+    event = build_resolution(entry["id"], clean_by, ref)
+    _write(event)
+    if json_output:
+        typer.echo(json.dumps(event, ensure_ascii=False, sort_keys=True))
+        return
+    ok(f"Retour {entry['id'][:MIN_PREFIX]} marqué traité")
+
+
+@app.command()
+def export(
+    cli_version: Optional[str] = typer.Option(
+        None, "--cli-version", help="Version de la CLI de l'entree (egalite exacte)"
+    ),
+    project: Optional[str] = typer.Option(
+        None, "--project", help="Ne garder que les projets dont le chemin contient ce texte"
+    ),
+    severity: Optional[str] = typer.Option(
+        None, "--severity", help=f"Gravite : {_values(SEVERITIES)} (exclut les bilans)"
+    ),
+    status: Optional[str] = typer.Option(
+        None, "--status", help=f"Statut : {_values(STATUSES)} (defaut : ouvert)"
+    ),
+) -> None:
+    """Exporte les retours en Markdown sur la sortie standard (jamais dans un fichier)."""
+    _validate_filters(severity, status)
+    records = read_feedback()
+    entries = select_entries(records, cli_version, project, severity, status or "ouvert")
+    typer.echo(render_export(entries, resolutions(records), Path.home().resolve()))

devflow_cli/core/feedback.py

@@ -0,0 +1,495 @@
+"""Retours d'usage de Devflow (`devflow feedback`).
+
+Les retours sont ajoutes a `feedback.jsonl`, a cote de `telemetry.jsonl`
+(`DEVFLOW_HOME`, a defaut `~/.devflow`), en append-only. Le fichier ne contient
+que du texte saisi et passe par `redact_text()` : seuls les secrets libelles
+sont masques. `DEVFLOW_TELEMETRY` n'a aucun effet sur l'ecriture d'un retour.
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+import math
+import os
+import re
+import subprocess
+import unicodedata
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from devflow_cli import VERSION
+from devflow_cli.core.redaction import redact_text
+from devflow_cli.core.telemetry import (
+    _quota_delta,
+    append_record,
+    read_records,
+    telemetry_enabled,
+    telemetry_file,
+)
+from devflow_cli.utils.paths import project_root_for_feature, resolve_feature_dir
+
+FEEDBACK_SCHEMA_VERSION = 1
+FEEDBACK_TYPES = ("friction", "bilan")
+SEVERITIES = ("bloquant", "majeur", "mineur")
+STATUSES = ("ouvert", "traité")
+MIN_PREFIX = 8
+
+_KEPT_CONTROLS = {"\n", "\t"}
+_DROPPED_CATEGORIES = {"Cc", "Zl", "Zp"}
+_PATH_END = r"""(?=$|/|\s|[,;:!?)\]}>"'`]|\.(?:$|\s))"""
+_FENCES = ("```", "~~~")
+_SEPARATOR_RE = re.compile(r"([-*_=])\1{2,}")
+_ID_RE = re.compile(r"[0-9a-f]{8,32}")
+
+
+def feedback_file() -> Path:
+    return telemetry_file().parent / "feedback.jsonl"
+
+
+def strip_controls(value: str) -> str:
+    """Supprime les controles (Cc) sauf saut de ligne et tabulation, et U+2028/U+2029."""
+    return "".join(
+        char for char in value
+        if char in _KEPT_CONTROLS or unicodedata.category(char) not in _DROPPED_CATEGORIES
+    )
+
+
+def sanitize_text(value: str) -> str:
+    """Controle supprimes puis secrets libelles masques, puis blancs de bord retires."""
+    return redact_text(strip_controls(value)).strip()
+
+
+def append_feedback(record: dict[str, Any], path: Path | None = None) -> Path:
+    """Ajoute une ligne en une seule ecriture O_APPEND ; leve OSError en cas d'echec.
+
+    Si le fichier ne finit pas par un saut de ligne (ecriture interrompue, edition
+    a la main), un saut de ligne est d'abord ajoute pour ne pas coller les lignes.
+    """
+    target = path or feedback_file()
+    if target.is_file() and target.stat().st_size > 0:
+        with target.open("rb") as handle:
+            handle.seek(-1, 2)
+            last = handle.read(1)
+        if last != b"\n":
+            descriptor = os.open(target, os.O_WRONLY | os.O_APPEND)
+            try:
+                os.write(descriptor, b"\n")
+            finally:
+                os.close(descriptor)
+    return append_record(record, target)
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _is_valid(record: Any) -> bool:
+    if not isinstance(record, dict):
+        return False
+    if record.get("schemaVersion") != FEEDBACK_SCHEMA_VERSION:
+        return False
+    if not isinstance(record.get("id"), str):
+        return False
+    kind = record.get("kind")
+    if kind == "entry":
+        return record.get("type") in FEEDBACK_TYPES and isinstance(record.get("project"), str)
+    if kind == "resolution":
+        return isinstance(record.get("entryId"), str)
+    return False
+
+
+def read_feedback(path: Path | None = None) -> list[dict[str, Any]]:
+    """Lit les entrees et evenements valides ; ignore toute ligne illisible."""
+    target = path or feedback_file()
+    if not target.is_file():
+        return []
+    records: list[dict[str, Any]] = []
+    for line in target.read_text(encoding="utf-8", errors="replace").split("\n"):
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if _is_valid(record):
+            records.append(record)
+    return records
+
+
+def _entries(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [record for record in records if record["kind"] == "entry"]
+
+
+def resolutions(records: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    """Premier evenement de traitement de chaque entree lisible."""
+    known = {entry["id"] for entry in _entries(records)}
+    found: dict[str, dict[str, Any]] = {}
+    for record in records:
+        if record["kind"] == "resolution" and record["entryId"] in known:
+            found.setdefault(record["entryId"], record)
+    return found
+
+
+# --- Contexte d'une entree ---------------------------------------------------
+
+
+def _read_state(feature_dir: Path) -> tuple[str | None, str | None]:
+    try:
+        state = json.loads((feature_dir / "workflow-state.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None, None
+    if not isinstance(state, dict):
+        return None, None
+    activity = state.get("currentActivity")
+    profile = state.get("profile")
+    return (
+        activity if isinstance(activity, str) else None,
+        profile if isinstance(profile, str) else None,
+    )
+
+
+def _git_root(cwd: Path) -> str:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return str(cwd.resolve())
+    top = result.stdout.strip()
+    if result.returncode != 0 or not top:
+        return str(cwd.resolve())
+    return str(Path(top).resolve())
+
+
+def resolve_context(issue: str | None, cwd: Path) -> tuple[str, str | None, str | None]:
+    """Projet, activite et profil d'une entree (C4.1)."""
+    if issue:
+        feature_dir = resolve_feature_dir(issue, cwd)
+        if feature_dir is not None:
+            try:
+                project = str(project_root_for_feature(feature_dir))
+            except ValueError:
+                project = None
+            if project is not None:
+                activity, profile = _read_state(feature_dir)
+                return project, activity, profile
+    return _git_root(cwd), None, None
+
+
+def matching_telemetry(project: str, issue: str | None) -> list[dict[str, Any]]:
+    """Tentatives de meme projet et meme issue ; vide si issue absente ou collecte coupee."""
+    if not issue or not telemetry_enabled():
+        return []
+    return [
+        record for record in read_records()
+        if record.get("project") == project and record.get("issueId") == issue
+    ]
+
+
+def latest_run_id(records: list[dict[str, Any]]) -> str | None:
+    best: dict[str, Any] | None = None
+    for record in records:
+        if best is None or str(record.get("recordedAt", "")) >= str(best.get("recordedAt", "")):
+            best = record
+    run_id = best.get("runId") if best else None
+    return run_id if isinstance(run_id, str) else None
+
+
+def path_cost(records: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Cout d'un parcours ; USD et points de quota ne sont jamais additionnes."""
+    if not records:
+        return None
+    usages = [record.get("usage") or {} for record in records]
+    measured = [usage for usage in usages if usage]
+    costs = [usage["costUsd"] for usage in measured if usage.get("costUsd") is not None]
+    five_hours = [d for d in (_quota_delta(r, 300) for r in records) if d is not None]
+    weekly = [d for d in (_quota_delta(r, 10080) for r in records) if d is not None]
+    cost: dict[str, Any] = {"attempts": len(records), "measured": len(measured)}
+    if costs:
+        cost["costUsd"] = round(sum(costs), 4)
+    if five_hours:
+        cost["quota5hPoints"] = sum(five_hours)
+    if weekly:
+        cost["quotaWeeklyPoints"] = sum(weekly)
+    cost["partial"] = len(measured) < len(records)
+    return cost
+
+
+def friction_ids(records: list[dict[str, Any]], project: str, issue: str | None) -> list[str]:
+    return [
+        entry["id"] for entry in _entries(records)
+        if entry["type"] == "friction"
+        and entry["project"] == project
+        and entry.get("issueId") == issue
+    ]
+
+
+def build_entry(
+    entry_type: str,
+    *,
+    severity: str | None,
+    issue: str | None,
+    what: str,
+    impact: str | None,
+    suggestion: str | None,
+    weighed: str | None,
+    went_well: str | None,
+    cwd: Path,
+) -> dict[str, Any]:
+    """Construit une entree ; les champs facultatifs vides sont omis (jamais null)."""
+    issue = sanitize_text(issue or "") or None
+    project, activity, profile = resolve_context(issue, cwd)
+    telemetry = matching_telemetry(project, issue)
+    entry: dict[str, Any] = {
+        "schemaVersion": FEEDBACK_SCHEMA_VERSION,
+        "kind": "entry",
+        "id": uuid.uuid4().hex,
+        "type": entry_type,
+        "cliVersion": VERSION,
+        "project": project,
+        "recordedAt": _utc_now(),
+        "what": sanitize_text(what),
+    }
+    optional = {
+        "severity": severity if entry_type == "friction" else None,
+        "issueId": issue,
+        "activity": activity,
+        "profile": profile,
+        "runId": latest_run_id(telemetry) if telemetry else None,
+        "impact": sanitize_text(impact or "") or None,
+        "suggestion": sanitize_text(suggestion or "") or None,
+        "weighed": sanitize_text(weighed or "") or None if entry_type == "bilan" else None,
+        "wentWell": sanitize_text(went_well or "") or None if entry_type == "bilan" else None,
+    }
+    entry.update({key: value for key, value in optional.items() if value is not None})
+    if entry_type == "bilan":
+        entry["frictionIds"] = friction_ids(read_feedback(), project, issue)
+        cost = path_cost(telemetry)
+        if cost is not None:
+            entry["cost"] = cost
+    return entry
+
+
+def build_resolution(entry_id: str, by: str | None, ref: str | None) -> dict[str, Any]:
+    """Evenement de traitement ; `by` deja assaini, a defaut l'utilisateur systeme."""
+    if by is None:
+        try:
+            by = sanitize_text(getpass.getuser()) or "inconnu"
+        except Exception:  # noqa: BLE001 - getuser peut lever plusieurs types
+            by = "inconnu"
+    event: dict[str, Any] = {
+        "schemaVersion": FEEDBACK_SCHEMA_VERSION,
+        "kind": "resolution",
+        "id": uuid.uuid4().hex,
+        "entryId": entry_id,
+        "resolvedBy": by,
+        "resolvedAt": _utc_now(),
+        "cliVersion": VERSION,
+    }
+    clean_ref = sanitize_text(ref or "")
+    if clean_ref:
+        event["ref"] = clean_ref
+    return event
+
+
+# --- Statut, selection, regroupement -----------------------------------------
+
+
+def find_entry(records: list[dict[str, Any]], entry_id: str) -> dict[str, Any]:
+    """Entree designee par un identifiant complet ou un prefixe unique de 8 caracteres."""
+    prefix = entry_id.strip().lower()
+    if not _ID_RE.fullmatch(prefix):
+        raise ValueError(
+            f"Identifiant invalide : {entry_id!r} "
+            f"(attendu {MIN_PREFIX} a 32 caracteres hexadecimaux)"
+        )
+    matches = [entry for entry in _entries(records) if entry["id"].startswith(prefix)]
+    if not matches:
+        raise ValueError(f"Aucun retour ne correspond a l'identifiant {prefix}")
+    if len(matches) > 1:
+        raise ValueError(f"Identifiant ambigu : {prefix} designe {len(matches)} retours")
+    return matches[0]
+
+
+def select_entries(
+    records: list[dict[str, Any]],
+    cli_version: str | None = None,
+    project: str | None = None,
+    severity: str | None = None,
+    status: str | None = None,
+) -> list[dict[str, Any]]:
+    """Entrees retenues par les filtres (ET logique), dans l'ordre du fichier."""
+    treated = resolutions(records)
+    selected = []
+    for entry in _entries(records):
+        if cli_version is not None and entry.get("cliVersion") != cli_version:
+            continue
+        if project and project not in entry["project"]:
+            continue
+        if severity is not None and entry.get("severity") != severity:
+            continue
+        if status is not None and ("traité" if entry["id"] in treated else "ouvert") != status:
+            continue
+        selected.append(entry)
+    return selected
+
+
+def group_entries(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Groupes (projet, issue) ; parcours sans issue en dernier dans chaque projet."""
+    groups: dict[tuple[str, str | None], list[dict[str, Any]]] = {}
+    for entry in entries:
+        issue = entry.get("issueId")
+        key = (entry["project"], issue if isinstance(issue, str) else None)
+        groups.setdefault(key, []).append(entry)
+    ordered = sorted(groups, key=lambda key: (key[0], key[1] is None, key[1] or ""))
+    return [
+        {"project": project, "issueId": issue, "entries": groups[(project, issue)]}
+        for project, issue in ordered
+    ]
+
+
+# --- Export ------------------------------------------------------------------
+
+
+def normalize_paths(text: str, project: str, home: Path) -> str:
+    """Racine du projet -> `<projet>`, puis home -> `~`, sans toucher aux prefixes partiels."""
+    if project and project != "/":
+        text = re.sub(re.escape(project) + _PATH_END, "<projet>", text)
+    forms = {str(home), str(home.resolve())}
+    forms.discard("/")
+    forms.discard("")
+    for form in sorted(forms, key=len, reverse=True):
+        text = re.sub(re.escape(form) + _PATH_END, "~", text)
+    return text
+
+
+def neutralize_markdown(text: str) -> str:
+    """Prefixe d'une barre oblique inverse les lignes qui casseraient la structure."""
+    lines = []
+    for line in text.split("\n"):
+        stripped = line.lstrip()
+        compact = "".join(stripped.split())
+        if (
+            stripped.startswith("#")
+            or stripped.startswith(_FENCES)
+            or _SEPARATOR_RE.fullmatch(compact)
+        ):
+            line = line[: len(line) - len(stripped)] + "\\" + stripped
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def _inline(value: Any) -> str:
+    return " ".join(str(value).split())
+
+
+def _number(value: Any) -> float | None:
+    """Nombre fini, sinon None (un champ de type inattendu est ignore au rendu)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value) if math.isfinite(value) else None
+
+
+def _cost_line(cost: dict[str, Any]) -> str:
+    attempts = _number(cost.get("attempts")) or 0
+    measured = _number(cost.get("measured")) or 0
+    head = f"{attempts:g} tentatives, {measured:g} mesurées"
+    if cost.get("partial") is True:
+        head += ", partiel"
+    amounts = []
+    usd = _number(cost.get("costUsd"))
+    five_hours = _number(cost.get("quota5hPoints"))
+    weekly = _number(cost.get("quotaWeeklyPoints"))
+    if usd is not None:
+        amounts.append(f"{usd:.2f} USD")
+    if five_hours is not None:
+        amounts.append(f"{five_hours:g} points de quota 5 h")
+    if weekly is not None:
+        amounts.append(f"{weekly:g} points de quota hebdomadaires")
+    return head + (" : " + " ; ".join(amounts) if amounts else "") + "."
+
+
+def render_export(
+    entries: list[dict[str, Any]],
+    treated: dict[str, dict[str, Any]],
+    home: Path,
+) -> str:
+    """Markdown au format de FEEDBACK.md ; chemins normalises, structure neutralisee."""
+    out = ["# Retours d'usage devflow — export", ""]
+    if not entries:
+        out += ["Aucun retour.", ""]
+        return "\n".join(out)
+
+    ordered = [entry for group in group_entries(entries) for entry in group["entries"]]
+    sections = [(severity.capitalize(), severity) for severity in SEVERITIES]
+    sections.append(("Bilans de parcours", None))
+    for title, severity in sections:
+        chosen = [
+            entry for entry in ordered
+            if (entry.get("severity") == severity if severity else entry["type"] == "bilan")
+        ]
+        if not chosen:
+            continue
+        out += [f"## {title}", ""]
+        for entry in chosen:
+            out += _render_entry(entry, treated.get(entry["id"]), home)
+    return "\n".join(out)
+
+
+def _render_entry(
+    entry: dict[str, Any], resolution: dict[str, Any] | None, home: Path
+) -> list[str]:
+    project = entry["project"]
+
+    def text(value: Any) -> str:
+        return neutralize_markdown(normalize_paths(str(value), project, home))
+
+    def inline(value: Any) -> str:
+        return text(_inline(value))
+
+    issue = entry.get("issueId")
+    title = [entry["type"], inline(issue) if issue else "sans issue"]
+    if entry.get("activity"):
+        title.append(inline(entry["activity"]))
+    title.append(entry["id"][:MIN_PREFIX])
+    context = [f"Projet {inline(Path(project).name)}"]
+    for label, key in (("issue", "issueId"), ("activité", "activity"), ("profil", "profile")):
+        if entry.get(key):
+            context.append(f"{label} {inline(entry[key])}")
+    if entry.get("cliVersion"):
+        context.append(f"CLI {inline(entry['cliVersion'])}")
+    if entry.get("recordedAt"):
+        context.append(inline(str(entry["recordedAt"])[:10]))
+
+    lines = [f"### {' · '.join(title)}", "", f"**Contexte.** {', '.join(context)}.", ""]
+
+    def block(label: str, key: str) -> None:
+        if entry.get(key):
+            lines.extend([f"**{label}.**", text(entry[key]), ""])
+
+    block("Ce qui s'est passé", "what")
+    block("Pourquoi ça coûte", "impact")
+    block("Piste", "suggestion")
+    if entry["type"] == "bilan":
+        if isinstance(entry.get("cost"), dict):
+            lines.extend([f"**Coût du parcours.** {_cost_line(entry['cost'])}", ""])
+        block("Activités qui ont pesé", "weighed")
+        block("Ce qui a bien marché", "wentWell")
+        ids = entry.get("frictionIds")
+        ids = [i for i in ids if isinstance(i, str)] if isinstance(ids, list) else []
+        shown = ", ".join(f"`{inline(str(i)[:MIN_PREFIX])}`" for i in ids) if ids else "aucune"
+        lines.extend([f"**Frictions référencées.** {shown}" + ".", ""])
+    if resolution is not None:
+        trace = f"Par {inline(resolution.get('resolvedBy', 'inconnu'))}"
+        if resolution.get("resolvedAt"):
+            trace += f" le {inline(str(resolution['resolvedAt'])[:10])}"
+        if resolution.get("ref"):
+            trace += f", réf. {inline(resolution['ref'])}"
+        lines.extend([f"**Traité.** {trace}.", ""])
+    return lines

devflow_cli/resources/commands/devflow.md

@@ -25,5 +25,25 @@ interpréter de `state.json`.
    tentative refusée et afficher sa commande de reprise.
 7. Afficher ensuite `devflow adaptive status ISSUE_ID`.
 
+## Retours d'usage
+
+Consigner les retours au fil du parcours avec `devflow feedback add`, sans
+interaction.
+
+- Une `friction` dès qu'un comportement de Devflow est en cause : refus à tort,
+  message trompeur, reprise inadaptée, prérequis d'environnement non documenté.
+  Ne jamais en consigner pour un refus justifié du travail de l'agent.
+- Un `bilan` en fin de parcours, terminé ou abandonné.
+- Ne jamais coller de secret, de contenu de fichier ni de sortie brute
+  d'environnement : seuls les secrets libellés (`token=`, `password:` …) sont
+  masqués.
+
+```bash
+devflow feedback add --type friction --severity majeur --issue <ISSUE> \
+  --what "…" --impact "…" --suggestion "…"
+devflow feedback add --type bilan --issue <ISSUE> --what "…" \
+  --weighed "…" --went-well "…"
+```
+
 Le contrat produit par Devflow est la seule autorité sur les actions,
 artefacts, validations et preuves de l'activité.

{devflow_cli-6.2.0.dist-info → devflow_cli-6.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: devflow-cli
-Version: 6.2.0
+Version: 6.3.0
 Summary: Spec-Driven Development workflow CLI
 Project-URL: Homepage, https://github.com/sopequenoteck/devflow
 Project-URL: Repository, https://github.com/sopequenoteck/devflow

{devflow_cli-6.2.0.dist-info → devflow_cli-6.3.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-devflow_cli/__init__.py,sha256=pRas3ja9tJb0F6YHAqQMncoMsOxuNSjH3HDXEbiSejc,1002
-devflow_cli/cli.py,sha256=nst8kP2QneJZJg6K5bBf9uO8Nj9lYmoHrEhcxA7nsIM,2129
+devflow_cli/__init__.py,sha256=EaJQ7YnyA-lEJmnyXiOSovWHa-5JC1C3VWMJ_7Wol4M,1002
+devflow_cli/cli.py,sha256=SY0nIY0R1XjoVxGzSPn7Qcojsh6bMHHmiSKigZBndWE,2216
 devflow_cli/adapters/__init__.py,sha256=RkjHPU2Lp4hSVIq2iOmyTrv2zYU9NuiIF9wEMWzLdMI,377
 devflow_cli/adapters/agents.py,sha256=8_y70AIhmtuR8kyPN3Wpj0-i76k9wd_uaycVKTqC96g,26503
 devflow_cli/adapters/linear.py,sha256=MyqI2tHx7NNHY1KRfeYZ_Zjc-6_xhZPWD4oS-j7wnNY,2659
 devflow_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-devflow_cli/commands/adaptive.py,sha256=_CICxGw27XOSnXteudn75IriY12zz5jhcZoH__zNfns,45797
+devflow_cli/commands/adaptive.py,sha256=mtc7CzQFQ4C1j-XmGgAAsuf386Y6FhWv36E_FpvSnPc,45860
 devflow_cli/commands/assess.py,sha256=GrWGGZjvBAgHWzSlUdtS-IfYocacA6VYxWduDvBunzg,4395
 devflow_cli/commands/check.py,sha256=M_sbcH1L3FEa4DF9gm46LEADlJndRKlaEDoysIBHv8k,6668
 devflow_cli/commands/context.py,sha256=hwTitOHxIpJMx1X8R1jHHy9CpE4HVZpJKkyeOujxAio,6246
@@ -12,6 +12,7 @@ devflow_cli/commands/docs_sync.py,sha256=Xc0mulpNTjDyeUDumKL7VNG0eumAf3016wEM_dq
 devflow_cli/commands/export_cmd.py,sha256=_DVgQru8z7UM9br-ntzMkNPcDL9OpY1G6S3cMPJ4Gqo,3259
 devflow_cli/commands/extension.py,sha256=W2bc1xntJmDUrvLt8GFgg3lgTcJSwmGGTDPUkrxonBo,4494
 devflow_cli/commands/feature.py,sha256=gomtMUUJl-0YfZZIx0PHNHBX-Rq5GhmMZE-XkP55SwE,4200
+devflow_cli/commands/feedback.py,sha256=pKG4jCsyVcfTA7Df_qe8tYF1VzveLJ-WfR9BcV9ZtMM,10268
 devflow_cli/commands/hooks_cmd.py,sha256=440K9AmXt6nF99JV2v6ActvG7-Pp1u6rYScEHRNoibI,5924
 devflow_cli/commands/init_cmd.py,sha256=VXR52ocqkO23J18pgij0Mhc_BTBl2PolxArjoCOuNow,5383
 devflow_cli/commands/linear.py,sha256=i066d5ryyBzZVfrSudbD0VWg9fSLivnB8yNe4vAMMW0,972
@@ -31,6 +32,7 @@ devflow_cli/core/automatic_evidence.py,sha256=DAd74AWeLF1L8ySlTgQ3tVJMgbVKfB1Zqx
 devflow_cli/core/catalog.py,sha256=nLPc78JkbISaSxJnHlWiMi_lvepaumbfwcjgLuVy7Zc,3102
 devflow_cli/core/contract_schemas.py,sha256=ugHrC4vcRpf3Dn_4JGHdBIkVr_TjnKu5dvvy3b0yKec,4480
 devflow_cli/core/docgen.py,sha256=EPDP0EKIToGYN1inQRj3CSYzADNtLTI_YCFYU4YWRuM,3075
+devflow_cli/core/feedback.py,sha256=ZdlEnM8mQuFpGHQ_fn1pG3L3XvLrNwkBNSw_MozJkbo,18110
 devflow_cli/core/git.py,sha256=o7Vk_n8b3-cAQa3CR1FblTZUvMDez7Ik4D9lrYI0njY,2561
 devflow_cli/core/hooks.py,sha256=p_NC0mR0Qa0a-LvfWhDQqqcAwxC5qRRk-lPHKUHGpiA,7942
 devflow_cli/core/installer.py,sha256=MfcGZKoOcQc2qviNnGShoD0P_MqOgRuVHX7YwCrG2vw,6259
@@ -61,7 +63,7 @@ devflow_cli/utils/strings.py,sha256=bfFXCwBDnFxshgZOYfy6mtysnjiaWO1wFnqBf7HLg4o,
 devflow_cli/resources/commands/devflow.context.md,sha256=SdvZ286cJKkgQIKYwnjd30v5zDeEXTFBhpEEsEOInoc,2048
 devflow_cli/resources/commands/devflow.extension.md,sha256=w7hoFfxRS0y-3rsvUmQDx1fvZhtE9KhANmRgFDwYVaA,2373
 devflow_cli/resources/commands/devflow.init.md,sha256=wplv3IiJrNkUoPXGZtOw9k6m3dzXBQDYAcPPN8d3EF8,2011
-devflow_cli/resources/commands/devflow.md,sha256=X_xRpkOIuCL19ExG1egh7pJpaesO_GCqbjW_8wHmejQ,1275
+devflow_cli/resources/commands/devflow.md,sha256=_8CQfwiT-e30FTGdok7m8xgQ3TPDpBi3tgtsf55fKLk,2079
 devflow_cli/resources/commands/devflow.regen.md,sha256=yjbMNAt6k0y6M9Y5HZDhCRgj_tb33Om6_-5OijmD5Bw,1169
 devflow_cli/resources/commands/devflow.status.md,sha256=tqjQ1IboU99ztG6C4nunBHGJCvMn3qDqx3AoF4SPjCk,338
 devflow_cli/resources/extensions/EXTENSION-API-REFERENCE.md,sha256=1wuAV-K8WI0BJ6SJ0HViieSHe3zazlfHemkKDT7bbKM,4478
@@ -85,8 +87,8 @@ devflow_cli/resources/templates/contracts/api-template.md,sha256=rC5v7JBz71PznCn
 devflow_cli/resources/templates/contracts/components-template.md,sha256=XIWfEXfC72sNmL5OA3V-7xIywkNDU2DBPLfyiagOWcs,484
 devflow_cli/resources/templates/contracts/interfaces-template.md,sha256=kf8B7b6HsmN7jyRlLNU7RnZl0rTMlI5s97yVRyI-6yc,336
 devflow_cli/resources/templates/contracts/services-template.md,sha256=cFafKCyLmq_a7aR7G0LXAaMO2z4Fuflq6iKdxfVg0vg,477
-devflow_cli-6.2.0.dist-info/METADATA,sha256=9k2DAloiyD6BLNT-24Ebalnivx2WhSasiefJeJon4nY,4275
-devflow_cli-6.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-devflow_cli-6.2.0.dist-info/entry_points.txt,sha256=GVJ6bMvFpqyO5589iC4nFKeGTpGIW8aKn_QPPpSZ6kU,48
-devflow_cli-6.2.0.dist-info/licenses/LICENSE,sha256=v79PvnmqOdKhQiOa_QcWxng4q8GuGscLOwi7ygUpwpo,1070
-devflow_cli-6.2.0.dist-info/RECORD,,
+devflow_cli-6.3.0.dist-info/METADATA,sha256=cdAoiz3DaCyQ8xqfA75HC_OGg8kfiPRWXeLnDGxjM2A,4275
+devflow_cli-6.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+devflow_cli-6.3.0.dist-info/entry_points.txt,sha256=GVJ6bMvFpqyO5589iC4nFKeGTpGIW8aKn_QPPpSZ6kU,48
+devflow_cli-6.3.0.dist-info/licenses/LICENSE,sha256=v79PvnmqOdKhQiOa_QcWxng4q8GuGscLOwi7ygUpwpo,1070
+devflow_cli-6.3.0.dist-info/RECORD,,