dna-cli 0.1.0__py3-none-any.whl

dna_cli/issue_bridge_cmd.py

@@ -0,0 +1,305 @@
+"""``dna sdlc issue publish|import|sync`` — the GitHub Issues bridge.
+
+The third side of the git↔SDLC symbiosis triangle (s-github-issues-
+bridge): commits carry the ``Work-Item:`` trailer, PRs carry the 🧬
+footer, and now GitHub issues do too. GitHub Issues are artifacts of
+the github.com domain — DNA **bridges** with provenance, it does not
+replace them:
+
+- ``issue publish <i-x>`` — creates the GitHub twin via ``gh issue
+  create`` (title from the doc + ``(i-x)`` suffix, body = description
+  + facts + doc link + 🧬 footer) and stamps ``github_number`` /
+  ``github_url`` / ``github_state`` / ``github_synced_at`` back onto
+  the doc through the kernel (the write path validates — the fields
+  live on the Issue Kind schema). Idempotent: an already-published doc
+  just prints its link.
+- ``issue import <#N | url>`` — creates an Issue doc FROM a GitHub
+  issue (``gh issue view --json``), board-convention name
+  (``i-NNN-<slug>`` via the next free number), labels mapped to
+  type/severity by the documented heuristic in ``_github_bridge``,
+  reporter = the GitHub author, provenance filled. Idempotent: a doc
+  already bridged to ``#N`` on that repo wins.
+- ``issue sync <i-x>`` — refreshes ``github_state`` from the remote;
+  a remotely-closed issue leaves a note on the local timeline.
+
+``--repo`` defaults to the ``origin`` remote of the enclosing repo
+(``owner/name``); pass it explicitly to bridge across repos. Honest
+degradation: no ``gh`` / auth / network → a didactic error, never a
+traceback (the fail-SOFT half — closing the twin on ``issue resolve``
+— lives in ``sdlc_cmd.cmd_issue_resolve``).
+
+Mechanics (pure builders + gh plumbing) live in ``_github_bridge.py``;
+this module is only the click surface. Registered onto the ``sdlc
+issue`` group at import time (same pattern as ``pr_cmd``) — see
+``dna_cli/__init__.py``.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import click
+
+from dna_cli import _github_bridge as gb
+from dna_cli._ctx import dna_session, fail
+from dna_cli.pr_cmd import _anchor_source_to_repo_root
+from dna_cli.sdlc_cmd import (
+    _append_timeline,
+    _build_raw,
+    _next_issue_number,
+    _now_iso,
+    _scope_option,
+    issue_group,
+)
+
+
+def _repo_option(f):
+    return click.option(
+        "--repo", default=None,
+        help="GitHub repo 'owner/name' (default: derivado do remote origin).",
+    )(f)
+
+
+def _resolve_repo(repo: str | None, *, context: str) -> str:
+    """Explicit ``--repo`` wins; else derive from origin; else didactic fail."""
+    if repo:
+        return repo
+    derived = gb.default_repo()
+    if derived:
+        return derived
+    raise fail(
+        f"não consegui derivar o repositório GitHub do remote origin — "
+        f"passe --repo owner/name pro {context}."
+    )
+
+
+def _issue_number_from_url(url: str) -> int | None:
+    m = re.search(r"/issues/(\d+)/?$", url.strip())
+    return int(m.group(1)) if m else None
+
+
+# ─── publish ──────────────────────────────────────────────────────────
+
+
+@issue_group.command("publish")
+@click.argument("name")
+@_repo_option
+@click.option("--dry-run", "dry_run", is_flag=True,
+              help="Só imprime title + body montados; não chama gh.")
+@_scope_option
+def cmd_issue_publish(
+    name: str, repo: str | None, dry_run: bool, scope: str,
+) -> None:
+    """Publish the Issue to GitHub — ``gh issue create`` born FROM the doc.
+
+    Title ``<título> (<i-x>)``; body = description + type/severity + link
+    pro doc no repo + footer 🧬 de atribuição. Grava github_number/url/
+    state/synced_at de volta no doc (proveniência). Idempotente: doc já
+    publicado só mostra o link.
+    """
+    _anchor_source_to_repo_root()
+    with dna_session(scope) as s:
+        doc = s.get_doc("Issue", name)
+        if doc is None:
+            raise fail(f"Issue '{name}' not found in scope {scope!r}")
+        spec = dict(doc.spec) if isinstance(doc.spec, dict) else {}
+
+        if spec.get("github_number"):
+            click.secho(
+                f"Issue/{name} já publicada — GitHub #{spec['github_number']}",
+                fg="yellow",
+            )
+            if spec.get("github_url"):
+                click.echo(spec["github_url"])
+            return
+
+        repo_full = _resolve_repo(repo, context="publish")
+        title = gb.build_issue_title(name, spec)
+        body = gb.build_issue_body(name, spec, scope=s.scope, repo=repo_full)
+
+        if dry_run:
+            click.secho("── title ──", fg="cyan")
+            click.echo(title)
+            click.secho("── body ──", fg="cyan")
+            click.echo(body, nl=False)
+            click.secho("(dry-run — gh issue create NÃO foi chamado)",
+                        fg="yellow", err=True)
+            return
+
+        try:
+            out = gb.run_gh(
+                ["gh", "issue", "create", "--repo", repo_full,
+                 "--title", title, "--body", body],
+                context="issue publish",
+            )
+        except gb.GhError as e:
+            raise fail(str(e))
+        url = out.strip().splitlines()[-1] if out.strip() else ""
+        number = _issue_number_from_url(url) if url else None
+        if not number:
+            raise fail(
+                f"gh issue create não devolveu uma URL de issue reconhecível "
+                f"(saída: {out.strip()[:200]!r}) — confira no GitHub antes de repetir."
+            )
+
+        spec["github_number"] = number
+        spec["github_url"] = url
+        spec["github_state"] = "open"
+        spec["github_synced_at"] = _now_iso()
+        spec["updated_at"] = _now_iso()
+        _append_timeline(
+            spec, "github_published",
+            summary=f"Publicada no GitHub: #{number}", github_url=url,
+        )
+        raw = _build_raw("Issue", name, spec)
+        s.run(s.kernel.write_document(scope, "Issue", name, raw))
+
+    click.secho(f"PUBLISHED Issue/{name} → {repo_full}#{number}", fg="green")
+    click.echo(url)
+
+
+# ─── import ───────────────────────────────────────────────────────────
+
+
+def _spec_from_github(gh_issue: dict[str, Any]) -> dict[str, Any]:
+    """Build the Issue spec from a ``gh issue view --json`` payload — pure.
+
+    Heuristics (documented in ``_github_bridge``): labels →
+    type/severity; GitHub state → status (OPEN→open, CLOSED→resolved
+    with ``closed_at`` from the GitHub close time); reporter = author.
+    """
+    labels = [
+        lbl.get("name", "") for lbl in gh_issue.get("labels") or []
+        if isinstance(lbl, dict)
+    ]
+    issue_type, severity = gb.map_labels(labels)
+    title = str(gh_issue.get("title") or "").strip()
+    body = str(gh_issue.get("body") or "").strip()
+    state = str(gh_issue.get("state") or "open").lower()
+    spec: dict[str, Any] = {
+        "title": title,
+        "description": body or title,
+        "type": issue_type,
+        "severity": severity,
+        "status": "open" if state == "open" else "resolved",
+        "reporter": str((gh_issue.get("author") or {}).get("login") or "github"),
+        "github_number": int(gh_issue["number"]),
+        "github_url": str(gh_issue.get("url") or ""),
+        "github_state": "open" if state == "open" else "closed",
+        "github_synced_at": _now_iso(),
+    }
+    if labels:
+        spec["labels"] = labels
+    if spec["status"] == "resolved":
+        spec["closed_at"] = str(gh_issue.get("closedAt") or _now_iso())
+    if gh_issue.get("createdAt"):
+        spec["created_at"] = str(gh_issue["createdAt"])
+    return spec
+
+
+@issue_group.command("import")
+@click.argument("ref")
+@_repo_option
+@_scope_option
+def cmd_issue_import(ref: str, repo: str | None, scope: str) -> None:
+    """Import a GitHub issue as an Issue doc (``#N``, ``N`` or the URL).
+
+    Nome segue a convenção do board (``i-NNN-<slug-do-título>`` no
+    próximo número livre). Labels→type/severity por heurística simples
+    (documentada em ``_github_bridge``); reporter = autor GitHub;
+    proveniência (github_number/url/state/synced_at) preenchida.
+    Idempotente: um doc já bridged pra essa issue vence.
+    """
+    _anchor_source_to_repo_root()
+    try:
+        number, repo_from_url = gb.parse_issue_ref(ref)
+    except ValueError as e:
+        raise fail(str(e))
+    repo_full = repo_from_url or _resolve_repo(repo, context="import")
+
+    try:
+        gh_issue = gb.fetch_issue(number, repo_full, context="issue import")
+    except gb.GhError as e:
+        raise fail(str(e))
+
+    spec = _spec_from_github(gh_issue)
+    _append_timeline(
+        spec, "github_imported",
+        summary=f"Importada do GitHub: {repo_full}#{number}",
+        github_url=spec.get("github_url"),
+    )
+
+    with dna_session(scope) as s:
+        for existing in s.query_list("Issue"):
+            espec = existing.spec if isinstance(existing.spec, dict) else {}
+            if espec.get("github_number") == number:
+                click.secho(
+                    f"GitHub #{number} já importada como Issue/{existing.name} "
+                    f"— nada a fazer.", fg="yellow",
+                )
+                return
+        name = f"i-{_next_issue_number(scope):03d}-gh{number}-{gb.slug_from_title(spec['title'])}"
+        raw = _build_raw("Issue", name, spec)
+        s.run(s.kernel.write_document(scope, "Issue", name, raw))
+
+    click.secho(
+        f"IMPORTED {repo_full}#{number} → Issue/{name} "
+        f"({spec['type']}/{spec['severity']}, status={spec['status']})",
+        fg="green",
+    )
+    if spec.get("github_url"):
+        click.echo(spec["github_url"])
+
+
+# ─── sync ─────────────────────────────────────────────────────────────
+
+
+@issue_group.command("sync")
+@click.argument("name")
+@_repo_option
+@_scope_option
+def cmd_issue_sync(name: str, repo: str | None, scope: str) -> None:
+    """Refresh ``github_state`` from the remote twin.
+
+    Fechada lá → além do refresh, deixa uma nota na timeline local (o
+    board fica sabendo sem ninguém vigiar o GitHub). Não mexe no status
+    local — decidir se "closed no GitHub" vira "resolved" é triage humana.
+    """
+    _anchor_source_to_repo_root()
+    with dna_session(scope) as s:
+        doc = s.get_doc("Issue", name)
+        if doc is None:
+            raise fail(f"Issue '{name}' not found in scope {scope!r}")
+        spec = dict(doc.spec) if isinstance(doc.spec, dict) else {}
+        number = spec.get("github_number")
+        if not number:
+            raise fail(
+                f"Issue/{name} não tem github_number — publique primeiro "
+                f"(dna sdlc issue publish {name}) ou importe do GitHub."
+            )
+        repo_full = _resolve_repo(repo, context="sync")
+
+        try:
+            gh_issue = gb.fetch_issue(int(number), repo_full, context="issue sync")
+        except gb.GhError as e:
+            raise fail(str(e))
+
+        prev_state = spec.get("github_state")
+        new_state = "open" if str(gh_issue.get("state") or "").lower() == "open" else "closed"
+        spec["github_state"] = new_state
+        spec["github_synced_at"] = _now_iso()
+        spec["updated_at"] = _now_iso()
+        if new_state == "closed" and prev_state != "closed":
+            _append_timeline(
+                spec, "comment",
+                summary=(
+                    f"GitHub #{number} foi fechada no remoto "
+                    f"({repo_full}) — avaliar resolve local."
+                ),
+            )
+        raw = _build_raw("Issue", name, spec)
+        s.run(s.kernel.write_document(scope, "Issue", name, raw))
+
+    flip = f" ({prev_state} → {new_state})" if prev_state != new_state else ""
+    click.secho(f"SYNCED Issue/{name} — GitHub #{number} is {new_state}{flip}",
+                fg="green")

dna_cli/kind_cmd.py

@@ -0,0 +1,84 @@
+"""``dna kind`` — list and inspect Kinds registered on the kernel.
+
+Migrated to dna-client (Phase F9 follow-up). Uses /kernel/kinds (global)
+and /scopes/{X}/kinds/{kind}/schema (per-scope) instead of touching
+the local kernel.
+"""
+from __future__ import annotations
+
+import click
+
+from dna_cli._ctx import dna_client, fail, print_json, print_table, run_async
+
+
+@click.group("kind", help="List + inspect registered Kinds.")
+def kind() -> None:
+    """Group root."""
+
+
+@kind.command("list")
+@click.option("--json", "as_json", is_flag=True, help="JSON output.")
+@click.option(
+    "--scope",
+    default="dna-development",
+    show_default=True,
+    help="Scope to enumerate kinds from.",
+)
+@click.option("--tenant", default=None, help="Route as this tenant.")
+def list_kinds(as_json: bool, scope: str, tenant: str | None) -> None:
+    """List all Kinds registered on the kernel (in the given scope)."""
+    with dna_client(tenant=tenant) as dna:
+        try:
+            body = run_async(dna.scopes.kinds(scope))
+        except Exception as e:  # noqa: BLE001
+            raise fail(f"scopes.kinds failed: {e}") from e
+    # /scopes/{X}/kinds returns {KindName: [doc names…], ...} — keys
+    # are the registered kinds. Tabular view emits one row per key;
+    # we don't have the per-kind metadata (alias/api_version/is_root)
+    # cheaply from this endpoint (would need /scopes/{X}/kinds/{kind}/schema
+    # per-kind, expensive on N=60+). For full descriptor of one kind,
+    # use `dna kind describe <KindName>`.
+    if isinstance(body, dict):
+        kinds_list = sorted(body.keys())
+    elif isinstance(body, list):
+        kinds_list = [it if isinstance(it, str) else (it.get("kind") if isinstance(it, dict) else "?") for it in body]
+    else:
+        kinds_list = []
+    rows = [
+        {
+            "kind": k,
+            "alias": "(use describe)",
+            "api_version": "(use describe)",
+            "is_root": "",
+            "is_prompt_target": "",
+        }
+        for k in kinds_list
+    ]
+    rows.sort(key=lambda r: r["kind"])
+    if as_json:
+        print_json(rows)
+    else:
+        print_table(rows, ["kind", "alias", "api_version", "is_root", "is_prompt_target"])
+
+
+@kind.command("describe")
+@click.argument("kind_name")
+@click.option(
+    "--scope",
+    default="dna-development",
+    show_default=True,
+)
+@click.option("--tenant", default=None, help="Route as this tenant.")
+def describe(kind_name: str, scope: str, tenant: str | None) -> None:
+    """Show the JSON Schema + storage descriptor for a Kind."""
+    with dna_client(tenant=tenant) as dna:
+        try:
+            descriptor = run_async(dna.scopes.kind_schema(scope, kind_name))
+        except Exception as e:  # noqa: BLE001
+            msg = str(e)
+            if "404" in msg or "not found" in msg.lower():
+                raise fail(f"Kind '{kind_name}' not registered in scope '{scope}'.") from e
+            raise fail(f"kind_schema failed: {e}") from e
+    # Descriptor: {kind, alias, api_version, display_label, schema,
+    #              dep_filters, is_runtime_artifact, is_root, ...}
+    print_json(descriptor)

dna_cli/memory_cmd.py

@@ -0,0 +1,298 @@
+"""``dna memory`` — remember / recall / forget / list / consolidate, offline.
+
+Kernel-bound, no server. Memory in DNA is the Kinds it already has
+(LessonLearned, Research, Evidence) written + recalled through the same kernel
++ ``RecordSearchProvider``. This command group drives ``dna.memory``'s verbs:
+
+    dna memory remember "always deep-copy the L2 cache before mutating" \
+        --area Feature/kernel --affect regret \
+        --reason "hit live during the JARVIS audit — same dict ref across calls"
+    dna memory recall "cache mutation" --json
+    dna memory forget rem-abc123 --superseded-by rem-def456
+    dna memory list --kind LessonLearned
+    dna memory consolidate --apply
+
+With the ``search-sqlite`` extra present recall is hybrid (dense sqlite-vec +
+lexical FTS5 + RRF, ``degraded=false``); without it, it degrades HONESTLY to the
+kernel's lexical scan. Recall re-ranks memory hits by Ebbinghaus retention ×
+affect, excludes bi-temporally-invalidated memories, and applies a light
+reconsolidation bump (cues_history + confidence) — all fail-soft.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+import click
+
+from dna_cli._ctx import dna_session, print_json, print_table
+from dna_cli.recall_cmd import _register_provider
+
+_MEMORY_KINDS = ("LessonLearned", "Research", "Evidence")
+
+
+def _slug(text: str) -> str:
+    """Derive a stable ``rem-<hash>`` name from the summary (upstream memory
+    naming convention)."""
+    h = hashlib.sha256(text.strip().lower().encode("utf-8")).hexdigest()[:10]
+    return f"rem-{h}"
+
+
+def _index_memory_kinds(s: Any, provider: Any, scope: str, kinds, tenant) -> None:
+    """Index the memory Kinds into the provider so recall finds pre-existing docs
+    (idempotent by text hash)."""
+    from dna.adapters.search.sqlite_vec import document_text
+
+    kernel = s.kernel
+    records: list[dict[str, Any]] = []
+
+    async def _collect() -> None:
+        for kind in kinds:
+            async for raw in kernel.query(scope, kind, tenant=tenant):
+                name = (raw.get("metadata") or {}).get("name") or raw.get("name")
+                if not name:
+                    continue
+                records.append({
+                    "scope": scope, "kind": kind, "name": name, "tenant": tenant or "",
+                    "text": document_text(raw),
+                    "title": (raw.get("spec") or {}).get("summary")
+                             or (raw.get("spec") or {}).get("title") or name,
+                })
+
+    s.run(_collect())
+    if records:
+        s.run(provider.index(records))
+
+
+@click.group(name="memory")
+def memory() -> None:
+    """Declarative memory over existing Kinds (remember/recall/forget/consolidate)."""
+
+
+@memory.command(name="remember")
+@click.argument("summary")
+@click.option("--kind", default="LessonLearned", type=click.Choice(_MEMORY_KINDS), show_default=True)
+@click.option("--name", default=None, help="Doc name (default: rem-<hash> of summary).")
+@click.option("--area", default="general", show_default=True, help="Scoped target area (Feature/X, Epic/Y, …).")
+@click.option("--affect", default="triumph",
+              type=click.Choice(["triumph", "regret", "surprise", "wistful", "ominous"]), show_default=True)
+@click.option("--reason", "affect_reason", default=None, help="Concrete justification for the affect (≥20 chars).")
+@click.option("--source-ref", "source_refs", multiple=True, help="Source artifact ref (repeatable).")
+@click.option("--tag", "tags", multiple=True, help="Tag (repeatable) — also seeds encoding_context co_topics.")
+@click.option("--owner", default=None, help="Authoring agent (claude-code, jarvis, …).")
+@click.option("--scope", default=None, help="Scope (default: first/only scope).")
+@click.option("--tenant", default=None, help="Tenant overlay.")
+@click.option("--json", "as_json", is_flag=True)
+def remember_cmd(
+    summary: str, kind: str, name: str | None, area: str, affect: str,
+    affect_reason: str | None, source_refs: tuple[str, ...], tags: tuple[str, ...],
+    owner: str | None, scope: str | None, tenant: str | None, as_json: bool,
+) -> None:
+    """Write a memory Kind + deterministic encoding-context + index it."""
+    from dna.memory import remember
+
+    name = name or _slug(summary)
+    spec: dict[str, Any] = {"summary": summary}
+    if kind == "LessonLearned":
+        spec.update({
+            "area": area,
+            "surface_when": ["feature_touched"],
+            "source_refs": list(source_refs) or [area],
+            "affect": affect,
+        })
+        if affect_reason:
+            spec["affect_reason"] = affect_reason
+        if tags:
+            spec["tags"] = list(tags)
+        if owner:
+            spec["owner"] = owner
+
+    with dna_session(scope) as s:
+        provider = _register_provider(s)  # registered → remember indexes on write
+        try:
+            out = s.run(remember(
+                s.kernel, s.scope, kind=kind, name=name, spec=spec, tenant=tenant,
+            ))
+        finally:
+            if provider is not None:
+                provider.close()
+
+    if as_json:
+        print_json({"kind": out["kind"], "name": out["name"], "indexed": out["indexed"]})
+        return
+    click.secho(f"🧠 remembered {out['kind']}/{out['name']}", fg="green", bold=True)
+    click.echo(f"   {summary}")
+    if not out["indexed"]:
+        click.secho("   (search-sqlite extra absent — recall will be lexical)", fg="yellow")
+
+
+@memory.command(name="recall")
+@click.argument("query")
+@click.option("--kind", "kinds", multiple=True, type=click.Choice(_MEMORY_KINDS),
+              help="Restrict to memory kind(s). Default: all.")
+@click.option("--scope", default=None)
+@click.option("--tenant", default=None)
+@click.option("-k", "--limit", "k", default=5, show_default=True)
+@click.option("--no-reconsolidate", is_flag=True, help="Skip the cue/confidence bump side-effect.")
+@click.option("--actor", default="cli", show_default=True, help="Who is recalling (stamped in cues_history).")
+@click.option("--json", "as_json", is_flag=True)
+def recall_cmd(
+    query: str, kinds: tuple[str, ...], scope: str | None, tenant: str | None,
+    k: int, no_reconsolidate: bool, actor: str, as_json: bool,
+) -> None:
+    """Hybrid, bi-temporal, retention-re-scored recall over the memory Kinds."""
+    from dna.memory import recall
+    from dna.memory.verbs import MEMORY_KINDS
+
+    kind_list = list(kinds) or list(MEMORY_KINDS)
+    with dna_session(scope) as s:
+        provider = _register_provider(s)
+        if provider is not None:
+            try:
+                _index_memory_kinds(s, provider, s.scope, kind_list, tenant)
+            except Exception as exc:  # noqa: BLE001 — indexing failure degrades to lexical
+                click.secho(f"⚠ index failed ({exc}); lexical fallback", fg="yellow", err=True)
+        else:
+            click.secho(
+                "⚠ search-sqlite extra not installed — degrading to lexical scan "
+                "(pip install 'dna-sdk[search-sqlite]' for semantic recall)",
+                fg="yellow", err=True,
+            )
+        try:
+            res = s.run(recall(
+                s.kernel, s.scope, query, kinds=tuple(kind_list), tenant=tenant, k=k,
+                reconsolidate=not no_reconsolidate, actor=actor,
+            ))
+        finally:
+            if provider is not None:
+                provider.close()
+
+    if as_json:
+        print_json(res)
+        return
+    mode = "lexical (degraded)" if res["degraded"] else "hybrid (dense+lexical+RRF)"
+    click.secho(f"\n🧠 recall · {mode} · scope={res['scope']} · '{query}'", bold=True)
+    hits = res["hits"]
+    if not hits:
+        click.echo("  (no memories)")
+        return
+    for i, h in enumerate(hits, 1):
+        score = h.get("score", 0.0)
+        ret = h.get("retention")
+        tail = f"  [retention {ret:.2f}]" if ret is not None else ""
+        click.echo(f"  {i:>2}. {h.get('kind','?')}/{h.get('name','?')}  ({score:.4f}){tail}")
+        if h.get("snippet"):
+            click.secho(f"      {h['snippet']}", fg="bright_black")
+
+
+@memory.command(name="forget")
+@click.argument("name")
+@click.option("--kind", default="LessonLearned", type=click.Choice(_MEMORY_KINDS), show_default=True)
+@click.option("--superseded-by", default=None, help="Name of the memory that supersedes this one.")
+@click.option("--scope", default=None)
+@click.option("--tenant", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def forget_cmd(
+    name: str, kind: str, superseded_by: str | None,
+    scope: str | None, tenant: str | None, as_json: bool,
+) -> None:
+    """Bi-temporal DEMOTION — set valid_to (never hard-delete)."""
+    from dna.memory import forget
+
+    with dna_session(scope) as s:
+        try:
+            out = s.run(forget(
+                s.kernel, s.scope, name, kind=kind, tenant=tenant, superseded_by=superseded_by,
+            ))
+        except KeyError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    if as_json:
+        print_json(out)
+        return
+    verb = "already forgotten" if out["already_forgotten"] else "forgotten"
+    click.secho(f"🕯  {verb}: {out['kind']}/{out['name']} (valid_to={out['valid_to']})", fg="yellow")
+    click.secho("   (retained + auditable — bi-temporal invalidation, not deleted)", fg="bright_black")
+
+
+@memory.command(name="list")
+@click.option("--kind", default="LessonLearned", type=click.Choice(_MEMORY_KINDS), show_default=True)
+@click.option("--all", "show_all", is_flag=True, help="Include bi-temporally-invalidated (forgotten) memories.")
+@click.option("--scope", default=None)
+@click.option("--tenant", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def list_cmd(kind: str, show_all: bool, scope: str | None, tenant: str | None, as_json: bool) -> None:
+    """List memories in the scope (current by default; ``--all`` includes forgotten)."""
+    from dna.memory.decay import currently_valid
+
+    now = datetime.now(timezone.utc)
+    with dna_session(scope) as s:
+        rows: list[dict[str, Any]] = []
+
+        async def _collect() -> None:
+            async for raw in s.kernel.query(s.scope, kind, tenant=tenant):
+                spec = raw.get("spec") or {}
+                nm = (raw.get("metadata") or {}).get("name") or raw.get("name")
+                valid = currently_valid(spec.get("valid_to"), now=now)
+                if not show_all and not valid:
+                    continue
+                rows.append({
+                    "name": nm,
+                    "area": spec.get("area", ""),
+                    "affect": spec.get("affect", ""),
+                    "state": "current" if valid else "forgotten",
+                    "summary": (spec.get("summary") or "")[:60],
+                })
+
+        s.run(_collect())
+
+    rows.sort(key=lambda r: r["name"])
+    if as_json:
+        print_json({"kind": kind, "count": len(rows), "memories": rows})
+        return
+    if not rows:
+        click.echo("(no memories)")
+        return
+    print_table(rows, ["name", "state", "affect", "area", "summary"])
+
+
+@memory.command(name="consolidate")
+@click.option("--kind", default="LessonLearned", type=click.Choice(_MEMORY_KINDS), show_default=True)
+@click.option("--floor", "stale_floor", default=0.15, show_default=True,
+              help="Retention floor below which a memory is stale.")
+@click.option("--apply", "do_apply", is_flag=True, help="Soft-forget stale memories (bi-temporal, never delete).")
+@click.option("--scope", default=None)
+@click.option("--tenant", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def consolidate_cmd(
+    kind: str, stale_floor: float, do_apply: bool,
+    scope: str | None, tenant: str | None, as_json: bool,
+) -> None:
+    """Deterministic consolidation pass — recompute decay, report/soft-forget
+    stale memories. NO LLM (that scribe is external + optional)."""
+    from dna.memory import consolidate
+
+    with dna_session(scope) as s:
+        report = s.run(consolidate(
+            s.kernel, s.scope, kind=kind, tenant=tenant,
+            stale_retention_floor=stale_floor, apply=do_apply,
+        ))
+
+    if as_json:
+        print_json(report)
+        return
+    click.secho(
+        f"\n🌙 consolidate · evaluated {report['evaluated']} · "
+        f"{len(report['stale'])} stale · archived {report['archived']}",
+        bold=True,
+    )
+    for stl in report["stale"]:
+        click.echo(f"  · {stl['name']}  retention={stl['retention']:.3f}  "
+                   f"({stl['days_since']:.0f}d since recall)")
+    if report["stale"] and not do_apply:
+        click.secho("  (report-only — pass --apply to soft-forget)", fg="bright_black")
+
+
+__all__ = ["memory"]