codec-cortex 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

{codec_cortex-0.3.2.dist-info → codec_cortex-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codec-cortex
-Version: 0.3.2
+Version: 0.3.4
 Summary: CODEC-CORTEX CLI — modular deterministic processor for .cortex files
 Author: Fidel Ernesto Lozada A.
 License: MIT

{codec_cortex-0.3.2.dist-info → codec_cortex-0.3.4.dist-info}/RECORD

@@ -1,17 +1,20 @@
-codec_cortex-0.3.2.dist-info/licenses/LICENSE,sha256=XH2MkxKGvJ_LcevUWgv7_OSxq37wpijTP-FogFipXCU,1080
+codec_cortex-0.3.4.dist-info/licenses/LICENSE,sha256=XH2MkxKGvJ_LcevUWgv7_OSxq37wpijTP-FogFipXCU,1080
 cortex/__init__.py,sha256=1Bs8--g5g1S2qeoIvX6uClpbBQWFAMaCQtdQw-dwPK4,899
 cortex/__main__.py,sha256=xUyHJQ7WGSMVwVG4SwzLyHz29cfLJNBzbPgY_x1QO8s,140
-cortex/_version.py,sha256=7Bzncojp21iM-dWXdN6Fqc8CpgZtvRE0o2j65xrTsR8,528
+cortex/_version.py,sha256=6VPYIvhLZJtMwihR7AOyYh2jhPuzbRCBdFS28bhCBjs,528
 cortex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/audit/__init__.py,sha256=wnng23HFOmMsxOGzx99gZgY2RVppKSybqwQucGFR8EE,859
+cortex/audit/logger.py,sha256=4BnBU_EVuQmlcmRnQNg_0m_amGv1rtbdkTYD64M4QJI,9167
 cortex/cli/__init__.py,sha256=tvd7DQfNaSTI3DZ3h6crL-R-KIZIEQ11bmzmMvI66nU,93
-cortex/cli/main.py,sha256=qBuSsVoNgNNYewM_09_T8q9AOJQ0Q7gr8uKhafjU-0Q,28799
+cortex/cli/main.py,sha256=ZPCPpB8dXGBKjueBhKJEc1hEO-SGFIQkbZnntBvF7l8,36713
 cortex/cli/commands/__init__.py,sha256=SEEf4ZLEoWUWWyfTHJAX5Xa4ioenYNDnqZpU5xaogxw,5689
 cortex/cli/commands/add.py,sha256=UC4Lg_GAupSOPNHNAhsRnCOjSl2B-B6iu95hWfP_Ng8,3118
+cortex/cli/commands/audit.py,sha256=L0HI8jI9BXdzE6p6QkOL0vtEp1lZ7PpTDyo4VUzUmRc,2485
 cortex/cli/commands/compile.py,sha256=PeiE3F0_kbA-ibC-f2evCAaaNB288eVKMeoM6tWrvs8,1076
 cortex/cli/commands/delete.py,sha256=0zeGt2Ny8ar_ggV3nbMNcJSpU_7iM8QorCDLnYCQd7M,1286
 cortex/cli/commands/diagram.py,sha256=B7gacxogQph9UTgiC3CY1PRJEAnFoQialeoFsNToj_w,4469
 cortex/cli/commands/diff.py,sha256=Wuc6ItkoMTlbfRbRD2n9pJq3uA5JlewDXK7WDS1Xruc,5795
-cortex/cli/commands/doctor.py,sha256=k6biTi5DNwROnulrxhGj3XRWflQLh4V_49xGPn8ZZ90,2833
+cortex/cli/commands/doctor.py,sha256=qtl2Z9z763fPkvqsWLMP_cBSXMVM8LBX_qoNz6Ls-AI,5131
 cortex/cli/commands/format.py,sha256=ioxiFCZn9O4oifwrzXckBODA-V2zafPfhKa1C8I0w5E,783
 cortex/cli/commands/get.py,sha256=hpHKZPo5y1Gk0NTwfoqzttFt7PNa0edQTJ9qMNY6z1E,1425
 cortex/cli/commands/glossary.py,sha256=cPRwl278gWbveceBcs0DziIFTZK2EwolYzwBB39hXWY,3088
@@ -30,13 +33,14 @@ cortex/cli/commands/v2_inspect.py,sha256=CI7W5RC8pv837NQhD4uMPoi0Exk6A2MlfUhiiVp
 cortex/cli/commands/v2_roundtrip.py,sha256=T6K_fZKylujuM2Lvb2KWCyA43y-LyrkOiwBqf5mCWcQ,4086
 cortex/cli/commands/v2_roundtrip_bidir.py,sha256=EFPQ9lh8xy_-3cSZ75IaDFJjn18juhCrka21jm0mPWg,5051
 cortex/cli/commands/v2_verify_view.py,sha256=PMaYt4iPumOkhCWyKceJ9I6mp07wQp-Ov43V-g5LFMI,2098
-cortex/cli/commands/verify.py,sha256=6szMscLYBgWlmDFl4IsV-RA1C-yK8x0HwJwpOL5QwaA,4250
+cortex/cli/commands/verify.py,sha256=fqSzAp5J35WKdUcdgsEyGWXdDLwwEXPh9RgQcTxlFIg,6325
 cortex/core/__init__.py,sha256=iy6qwId5H9UgPLg1UdaqxkxCR-WxKoUjplNqFHU2KWM,2760
 cortex/core/ast.py,sha256=1m_vXO3C-gx_uOmLinmZH_W6hSb5bFZiylzJGjJCOVs,9523
 cortex/core/compare.py,sha256=eYbO5CMP9Uz1QiTcktONO_TuggeDDv-NkBtAuFHzYn0,7221
 cortex/core/document_kind.py,sha256=pDe9k5zReudIZxOgg9odkSAvzcbfPkMjvXioXW20rE8,22618
-cortex/core/errors.py,sha256=UAdkxPPcyhbS5e5VkTsPNBMbJBLw_FwGF5mG1iyxIN8,13191
+cortex/core/errors.py,sha256=4puLs1sSbIx-5jrmQ1yYYNmeAxX7OpfMEoIlSu7DIy8,13538
 cortex/core/lexer.py,sha256=EfoQGzByljkxa7xYo9N7HM8KQuNQsCW8KIxL7Y9yFE0,8145
+cortex/core/modes.py,sha256=NjLENepLYECuWxf62IgO9lDI_7_4JkcZnGEG19Ygkds,10306
 cortex/core/parser.py,sha256=SbMAqua8dC-7s61TqlUFne_qvviL3Tgrhk7tNFgNpds,23866
 cortex/core/validator.py,sha256=6tusJCqKBR66cSc36WTFea2mkRBmgbAt-ynHsK3EtTY,10167
 cortex/core/writer.py,sha256=7DFQa0wauAl3B-5zCMWJ675io3Ke1kPyKqDTprJUsNY,9207
@@ -56,6 +60,9 @@ cortex/hcortex/markdown_model.py,sha256=JLHyN07a5ZOmLsxcSOZagsCJpWsURjRpW2JZdXXZ
 cortex/hcortex/profiles.py,sha256=e4ir9O99UThtPThffIP_h68EnE5F0V_iuOtTBfVn4uE,5777
 cortex/hcortex/read_renderer.py,sha256=6usu_ZTp4gS74g9vgNUSCprFo54Vqc1jCndGDiqzmT8,11317
 cortex/hcortex/recovery.py,sha256=huT_EOteDFi_3zOfRglufC3xN-gEHoO2uDDkui9kDPo,29832
+cortex/security/__init__.py,sha256=3pbqQGCNffN-MirAdQgNPl2WyFx-unhNnMChLabPbpE,941
+cortex/security/secret_scanner.py,sha256=wf0rJ0yfA7f3L-T7SHFP-v0v5JN0tdVsW6X8cUkiKk8,12906
+cortex/security/signature.py,sha256=gfbcr0j6CRlmJiRq2TKnuL4ZJuVolOzr10l2mNWEyYc,3843
 cortex/templates/__init__.py,sha256=D49Z4J-Nvl_o_tPM_z_KvW2m9fRIpHL4jYeSoCBmioo,292
 cortex/templates/brain.py,sha256=Ngs5Aj8Rf3c2LAckJxrN4K9oKGpmaZ-Ou_zZQhkA7jY,3531
 cortex/templates/minimal_glossary.py,sha256=ZeP4GH929_bqoKBVlluAF9Wgv9Ajtz-8HcIETkjsXcY,1564
@@ -72,10 +79,10 @@ cortex/v2/parser.py,sha256=wQkq7NnBQQDIzgkWxMpn-0GKxEppOPwidDnQOp4VMnY,20075
 cortex/v2/view.py,sha256=Rm9qcEcNDeidWy3Y5CAsSv4dvMrOqvb1Vl3k7WhTetA,15197
 cortex/v2/view_renderer.py,sha256=LQ5IP9b9giYofTL42F4cp6v3uAGvVZWYm0kYeGFw3nA,18553
 cortex/v2/writer.py,sha256=TiEbTfFPwtpFa-jNVbrShviyVvCNAu61baeCCAFnMDM,10913
-codec_cortex-0.3.2.dist-info/METADATA,sha256=rQLFkQ1SE1UxcOEPVbo-3GPx9w5DNdmqSDHwoK9zuI4,8137
-codec_cortex-0.3.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-codec_cortex-0.3.2.dist-info/entry_points.txt,sha256=_Fl_fZk_6jJeX4QXcG1dT4WakyDZVu_G320FkcyQUOI,48
-codec_cortex-0.3.2.dist-info/scm_file_list.json,sha256=Zm6OWQv8RtPgN8c5w4xfa8pzJSYNvNzH976T_BmOpRQ,4411
-codec_cortex-0.3.2.dist-info/scm_version.json,sha256=a54wpletfE6bmUiRUMXsGhr1UwZJYX1Wc2KqMusTe34,160
-codec_cortex-0.3.2.dist-info/top_level.txt,sha256=79LAeTJJ_pMIBy3mkF7uNaN0mdBRt5tGrnne5N_iAio,7
-codec_cortex-0.3.2.dist-info/RECORD,,
+codec_cortex-0.3.4.dist-info/METADATA,sha256=AjyYUSKLXVF9R_3ruWswCJVGjQ8f8bsjF59bNk0WzLk,8137
+codec_cortex-0.3.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codec_cortex-0.3.4.dist-info/entry_points.txt,sha256=_Fl_fZk_6jJeX4QXcG1dT4WakyDZVu_G320FkcyQUOI,48
+codec_cortex-0.3.4.dist-info/scm_file_list.json,sha256=6nPrUvtSqoE42QLS-MNk8RQqj54iqKuCUKMGjBfefjU,4826
+codec_cortex-0.3.4.dist-info/scm_version.json,sha256=tjJ3rcPApqh4nIht1WUSkNblALHnqBZPrw4caDtl8nE,160
+codec_cortex-0.3.4.dist-info/top_level.txt,sha256=79LAeTJJ_pMIBy3mkF7uNaN0mdBRt5tGrnne5N_iAio,7
+codec_cortex-0.3.4.dist-info/RECORD,,

{codec_cortex-0.3.2.dist-info → codec_cortex-0.3.4.dist-info}/scm_file_list.json

@@ -22,6 +22,7 @@
     "src/cortex/core/document_kind.py",
     "src/cortex/core/parser.py",
     "src/cortex/core/writer.py",
+    "src/cortex/core/modes.py",
     "src/cortex/core/ast.py",
     "src/cortex/core/lexer.py",
     "src/cortex/core/compare.py",
@@ -58,6 +59,11 @@
     "src/cortex/templates/skill.py",
     "src/cortex/templates/brain.py",
     "src/cortex/templates/minimal_glossary.py",
+    "src/cortex/security/__init__.py",
+    "src/cortex/security/secret_scanner.py",
+    "src/cortex/security/signature.py",
+    "src/cortex/audit/__init__.py",
+    "src/cortex/audit/logger.py",
     "src/cortex/cli/__init__.py",
     "src/cortex/cli/main.py",
     "src/cortex/cli/commands/verify.py",
@@ -78,6 +84,7 @@
     "src/cortex/cli/commands/render.py",
     "src/cortex/cli/commands/micro.py",
     "src/cortex/cli/commands/list.py",
+    "src/cortex/cli/commands/audit.py",
     "src/cortex/cli/commands/new.py",
     "src/cortex/cli/commands/glossary.py",
     "src/cortex/cli/commands/update.py",
@@ -87,11 +94,14 @@
     "src/cortex/cli/commands/diff.py",
     "src/cortex/cli/commands/v2_roundtrip.py",
     "src/tests/test_fixtures.py",
+    "src/tests/test_e2_modes.py",
     "src/tests/test_v1_1_6_fixes.py",
     "src/tests/test_v2_3_0_acceptance.py",
+    "src/tests/test_e2_secret_scanner.py",
     "src/tests/__init__.py",
     "src/tests/test_audit_gates.py",
     "src/tests/test_v1_1_2_fixes.py",
+    "src/tests/test_e2_signature.py",
     "src/tests/test_v1_1_7_fixes.py",
     "src/tests/test_acceptance.py",
     "src/tests/test_v2_2_3_fixes.py",
@@ -107,6 +117,7 @@
     "src/tests/test_errors.py",
     "src/tests/test_v2_2_1_fixes.py",
     "src/tests/test_v1_1_9_fixes.py",
+    "src/tests/test_e2_audit.py",
     "src/tests/test_v2_2_view.py",
     "src/tests/test_reaudit_gates.py",
     "src/tests/fixtures/SKILL_v2.cortex.md",

{codec_cortex-0.3.2.dist-info → codec_cortex-0.3.4.dist-info}/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.3.2",
+  "tag": "0.3.4",
   "distance": 0,
-  "node": "g5c75b370509905a226dc45a9d4ba8a5e4aa83e40",
+  "node": "gfda71bbd80142ab185405525e9ed3fb006f0d937",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-07-01"

cortex/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.2'
-__version_tuple__ = version_tuple = (0, 3, 2)
+__version__ = version = '0.3.4'
+__version_tuple__ = version_tuple = (0, 3, 4)
 
-__commit_id__ = commit_id = 'g5c75b3705'
+__commit_id__ = commit_id = 'gfda71bbd8'

cortex/audit/__init__.py

@@ -0,0 +1,43 @@
+"""Audit logging module (E2.4, v0.3.4+).
+
+Public surface:
+
+- :mod:`cortex.audit.logger` — append-only JSONL audit log with
+  on-demand session state, daily rotation, and snapshot export.
+"""
+
+from __future__ import annotations
+
+from .logger import (
+    AuditEntry,
+    SessionState,
+    append_entry,
+    audit_dir,
+    daily_log_path,
+    disable_logging,
+    enable_logging,
+    prune_old_logs,
+    read_session_state,
+    rotate_if_needed,
+    session_state_path,
+    snapshot_file,
+    snapshots_dir,
+    write_session_state,
+)
+
+__all__ = [
+    "AuditEntry",
+    "SessionState",
+    "append_entry",
+    "audit_dir",
+    "daily_log_path",
+    "disable_logging",
+    "enable_logging",
+    "prune_old_logs",
+    "read_session_state",
+    "rotate_if_needed",
+    "session_state_path",
+    "snapshot_file",
+    "snapshots_dir",
+    "write_session_state",
+]

cortex/audit/logger.py

@@ -0,0 +1,271 @@
+"""E2.4 (v0.3.4) — On-demand audit logging.
+
+This module implements the audit log described in the E2.4 plan:
+
+  - Logging is OFF by default. No automatic logging of any operation.
+  - ``cortex audit on``  → enable logging for the current session.
+  - ``cortex audit off`` → disable logging for the current session.
+  - ``cortex audit status`` → show whether logging is on or off.
+  - ``cortex audit snapshot`` → export a single snapshot of a .cortex
+    file to ``~/.codec-cortex/audit/snapshots/`` (one-shot, not a stream).
+
+The session state (on/off) is stored in
+``~/.codec-cortex/audit/session.state`` so it persists across CLI
+invocations within the same shell/session. The state file is removed
+by ``cortex audit off``.
+
+When logging is ON, mutation commands (add/update/delete/move/format)
+append a JSONL line to ``~/.codec-cortex/audit/YYYY-MM-DD.jsonl``::
+
+    {"t":"2026-07-01T12:00:00Z","op":"add","file":"brain.cortex",
+     "mode":"editor","result":"ok"}
+
+Design principles:
+  - **No silent logging.** Nothing is written unless the user opts in.
+  - **Append-only.** Existing entries are never modified.
+  - **Out-of-repo.** Logs live in the user's home, not in the project
+    repo, so they don't pollute git history.
+  - **Per-day rotation.** A new JSONL file is created each day.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+def audit_dir() -> Path:
+    """Return the audit directory under the user's home.
+
+    Defaults to ``~/.codec-cortex/audit/``. Can be overridden by the
+    ``CORTEX_AUDIT_DIR`` environment variable (useful for tests).
+    """
+    override = os.environ.get("CORTEX_AUDIT_DIR")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".codec-cortex" / "audit"
+
+
+def session_state_path() -> Path:
+    """Path to the session state file (created by `audit on`)."""
+    return audit_dir() / "session.state"
+
+
+def daily_log_path(date: Optional[datetime.date] = None) -> Path:
+    """Path to the daily JSONL log file (``YYYY-MM-DD.jsonl``)."""
+    if date is None:
+        date = datetime.date.today()
+    return audit_dir() / f"{date.isoformat()}.jsonl"
+
+
+def snapshots_dir() -> Path:
+    """Directory where `audit snapshot` exports one-shot snapshots."""
+    return audit_dir() / "snapshots"
+
+
+# ---------------------------------------------------------------------------
+# Session state
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SessionState:
+    """In-memory representation of the audit session state."""
+
+    enabled: bool
+    started_at: Optional[str] = None  # ISO 8601 timestamp
+    pid: Optional[int] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "enabled": self.enabled,
+            "started_at": self.started_at,
+            "pid": self.pid,
+        }
+
+
+def read_session_state() -> SessionState:
+    """Read the current session state from disk.
+
+    Returns a disabled SessionState if no state file exists.
+    """
+    path = session_state_path()
+    if not path.is_file():
+        return SessionState(enabled=False)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return SessionState(
+            enabled=bool(data.get("enabled", False)),
+            started_at=data.get("started_at"),
+            pid=data.get("pid"),
+        )
+    except (json.JSONDecodeError, OSError):
+        return SessionState(enabled=False)
+
+
+def write_session_state(state: SessionState) -> None:
+    """Persist the session state to disk. Creates the audit dir if needed."""
+    path = session_state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(state.to_dict(), indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def enable_logging() -> SessionState:
+    """Enable audit logging for the current session."""
+    state = SessionState(
+        enabled=True,
+        started_at=datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        pid=os.getpid(),
+    )
+    write_session_state(state)
+    # Also create the daily log file if it doesn't exist (touch).
+    log_path = daily_log_path()
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    if not log_path.exists():
+        log_path.touch()
+    return state
+
+
+def disable_logging() -> SessionState:
+    """Disable audit logging. The state file is removed; existing log
+    entries are preserved."""
+    path = session_state_path()
+    if path.is_file():
+        path.unlink()
+    return SessionState(enabled=False)
+
+
+# ---------------------------------------------------------------------------
+# Log entry
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AuditEntry:
+    """A single audit log entry."""
+
+    op: str          # "add" | "update" | "delete" | "move" | "format" | ...
+    file: str        # path to the .cortex file
+    mode: str        # "read-only" | "editor" | "admin"
+    result: str      # "ok" | "error" | "dry-run"
+    selector: Optional[str] = None  # entry selector (e.g. "FCS:primary")
+    error_code: Optional[str] = None
+    timestamp: Optional[str] = None  # ISO 8601; defaults to now()
+
+    def to_dict(self) -> dict:
+        ts = self.timestamp or datetime.datetime.now(datetime.timezone.utc).isoformat()
+        d: dict[str, Any] = {
+            "t": ts,
+            "op": self.op,
+            "file": self.file,
+            "mode": self.mode,
+            "result": self.result,
+        }
+        if self.selector:
+            d["selector"] = self.selector
+        if self.error_code:
+            d["error_code"] = self.error_code
+        return d
+
+    def to_jsonl(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, separators=(",", ":"))
+
+
+def append_entry(entry: AuditEntry) -> Optional[Path]:
+    """Append ``entry`` to today's JSONL log if logging is enabled.
+
+    Returns the path to the log file if written, or None if logging is
+    disabled.
+    """
+    state = read_session_state()
+    if not state.enabled:
+        return None
+
+    log_path = daily_log_path()
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    # Append-only: open in append mode, write one line, close.
+    with log_path.open("a", encoding="utf-8") as f:
+        f.write(entry.to_jsonl() + "\n")
+    return log_path
+
+
+# ---------------------------------------------------------------------------
+# Snapshot
+# ---------------------------------------------------------------------------
+
+def snapshot_file(cortex_path: Path, *, label: Optional[str] = None) -> Path:
+    """Export a one-shot snapshot of ``cortex_path`` to the snapshots dir.
+
+    The snapshot is a verbatim copy of the .cortex file, named with a
+    timestamp so multiple snapshots don't collide. An optional ``label``
+    can be appended to the filename for human readability.
+
+    Returns the path to the written snapshot.
+    """
+    if not cortex_path.is_file():
+        raise FileNotFoundError(f"cannot snapshot non-existent file: {cortex_path}")
+
+    snapshots_dir().mkdir(parents=True, exist_ok=True)
+    ts = datetime.datetime.now().strftime("%Y%m%dT%H%M%S")
+    stem = cortex_path.stem
+    suffix = cortex_path.suffix
+    label_part = f"_{label}" if label else ""
+    snap_name = f"{stem}_{ts}{label_part}{suffix}"
+    snap_path = snapshots_dir() / snap_name
+    snap_path.write_bytes(cortex_path.read_bytes())
+    return snap_path
+
+
+# ---------------------------------------------------------------------------
+# Rotation (E2 risk mitigation)
+# ---------------------------------------------------------------------------
+
+MAX_LOG_SIZE_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+def rotate_if_needed(log_path: Path) -> Optional[Path]:
+    """Rotate ``log_path`` if it exceeds :data:`MAX_LOG_SIZE_BYTES`.
+
+    Renames ``YYYY-MM-DD.jsonl`` to ``YYYY-MM-DD.jsonl.1`` (overwriting
+    any previous rotation). Returns the rotated path if rotation
+    happened, None otherwise.
+    """
+    if not log_path.is_file():
+        return None
+    if log_path.stat().st_size < MAX_LOG_SIZE_BYTES:
+        return None
+    rotated = log_path.with_suffix(log_path.suffix + ".1")
+    log_path.rename(rotated)
+    log_path.touch()
+    return rotated
+
+
+def prune_old_logs(*, keep_days: int = 30) -> int:
+    """Delete daily log files older than ``keep_days`` days.
+
+    Returns the number of files deleted.
+    """
+    cutoff = datetime.date.today() - datetime.timedelta(days=keep_days)
+    deleted = 0
+    for p in audit_dir().glob("*.jsonl"):
+        # Skip rotated files (.jsonl.1) — they're handled separately.
+        if p.name.endswith(".1"):
+            continue
+        try:
+            date_str = p.stem  # "YYYY-MM-DD"
+            file_date = datetime.date.fromisoformat(date_str)
+        except ValueError:
+            continue
+        if file_date < cutoff:
+            p.unlink()
+            deleted += 1
+    return deleted

cortex/cli/commands/audit.py

@@ -0,0 +1,95 @@
+"""``cortex audit`` — on-demand audit logging control (E2.4, v0.3.4).
+
+Subcommands::
+
+    cortex audit on          # enable logging for this session
+    cortex audit off         # disable logging
+    cortex audit status      # show whether logging is on/off
+    cortex audit snapshot <file>  # export a one-shot snapshot
+    cortex audit prune [--keep-days N]  # delete old logs
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from ...audit.logger import (
+    audit_dir,
+    daily_log_path,
+    disable_logging,
+    enable_logging,
+    prune_old_logs,
+    read_session_state,
+    snapshot_file,
+)
+
+
+def _emit_status() -> int:
+    state = read_session_state()
+    payload = {
+        "enabled": state.enabled,
+        "started_at": state.started_at,
+        "pid": state.pid,
+        "audit_dir": str(audit_dir()),
+        "daily_log": str(daily_log_path()),
+    }
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+    return 0
+
+
+def run_on(args) -> int:
+    state = enable_logging()
+    print("audit logging: ON")
+    print(f"  started_at: {state.started_at}")
+    print(f"  pid:        {state.pid}")
+    print(f"  log file:   {daily_log_path()}")
+    return 0
+
+
+def run_off(args) -> int:
+    disable_logging()
+    print("audit logging: OFF")
+    print(f"  (existing entries in {audit_dir()} are preserved)")
+    return 0
+
+
+def run_status(args) -> int:
+    return _emit_status()
+
+
+def run_snapshot(args) -> int:
+    target = Path(args.file).expanduser().resolve()
+    if not target.is_file():
+        print(f"error: file not found: {target}", file=sys.stderr)
+        return 1
+    label = getattr(args, "label", None)
+    snap = snapshot_file(target, label=label)
+    print(f"snapshot written: {snap}")
+    print(f"  size: {snap.stat().st_size} bytes")
+    return 0
+
+
+def run_prune(args) -> int:
+    keep_days = getattr(args, "keep_days", 30)
+    deleted = prune_old_logs(keep_days=keep_days)
+    print(f"pruned {deleted} log file(s) older than {keep_days} days")
+    return 0
+
+
+def run(args) -> int:
+    # Dispatch by subcommand.
+    sub = getattr(args, "audit_command", None)
+    if sub == "on":
+        return run_on(args)
+    if sub == "off":
+        return run_off(args)
+    if sub == "status":
+        return run_status(args)
+    if sub == "snapshot":
+        return run_snapshot(args)
+    if sub == "prune":
+        return run_prune(args)
+    print(f"error: unknown audit subcommand: {sub}", file=sys.stderr)
+    return 2

cortex/cli/commands/doctor.py

@@ -1,11 +1,20 @@
-"""``cortex doctor`` — deep diagnostic of a .cortex file."""
+"""``cortex doctor`` — deep diagnostic of a .cortex file.
+
+v0.3.4 (E2.2): adds secret scanning via :mod:`cortex.security.secret_scanner`.
+By default the scan is reported in the diagnostic summary; pass
+``--scan-secrets`` to exit 1 if any high-severity finding is present.
+Use ``--scan-secrets-paths <path>...`` to scan additional paths beyond
+the .cortex file itself (useful for scanning a whole repo).
+"""
 
 from __future__ import annotations
 
 import json
+from pathlib import Path
 
 from ...core.document_kind import infer_document_kind
 from ...core.validator import validate
+from ...security.secret_scanner import redact, scan_paths
 from ..commands import load_doc
 
 
@@ -13,7 +22,6 @@ def run(args) -> int:
     doc = load_doc(args.input)
     strict = getattr(args, "strict", False)
 
-    # Apply explicit kind if provided (audit gap H-01/H-02)
     kind = None
     if getattr(args, "kind", None):
         from ...core.document_kind import DocumentKind
@@ -30,9 +38,19 @@ def run(args) -> int:
     micro = list(doc.glossary.micro.values())
     entries = [(s.id, e) for s in sections if s.id != "$0" for e in s.entries]
 
+    # E2.2 (v0.3.4): secret scan.
+    # The .cortex file itself is always scanned. Additional paths can be
+    # provided via --scan-secrets-paths (typically used in CI to scan
+    # the whole repo, not just the .cortex artefact).
+    scan_paths_arg = getattr(args, "scan_secrets_paths", None) or []
+    scan_targets = [Path(args.input)] + [Path(p) for p in scan_paths_arg]
+    baseline = getattr(args, "secrets_baseline", None)
+    baseline_path = Path(baseline) if baseline else None
+    scan_result = scan_paths(scan_targets, baseline=baseline_path)
+
     json_mode = getattr(args, "_json_mode", False)
     if args.format == "json" or json_mode:
-        print(json.dumps({
+        payload = {
             "ok": len(errors) == 0,
             "input": args.input,
             "kind": kind.kind,
@@ -47,7 +65,13 @@ def run(args) -> int:
             "warnings": warnings,
             "section_ids": [s.id for s in sections],
             "sigil_names": [s.sigil for s in sigils],
-        }, indent=2, default=str))
+            "secret_scan": scan_result.to_dict(),
+        }
+        # Redact matches in the JSON output too, so the doctor output
+        # itself doesn't become a secret-leaking artefact.
+        for f in payload["secret_scan"]["findings"]:
+            f["match"] = redact(f["match"])
+        print(json.dumps(payload, indent=2, default=str))
     else:
         lines = []
         lines.append(f"doctor: {args.input}")
@@ -60,6 +84,22 @@ def run(args) -> int:
         lines.append(f"  micro:        {len(micro)}")
         lines.append(f"  errors:       {len(errors)}")
         lines.append(f"  warnings:     {len(warnings)}")
+        # Secret scan summary
+        lines.append("")
+        lines.append("secret scan:")
+        lines.append(f"  files scanned:  {scan_result.files_scanned}")
+        lines.append(f"  bytes scanned:  {scan_result.bytes_scanned}")
+        lines.append(f"  findings:       {len(scan_result.findings)} "
+                     f"(high={len(scan_result.by_severity('high'))}, "
+                     f"medium={len(scan_result.by_severity('medium'))})")
+        if scan_result.findings:
+            lines.append("")
+            lines.append("  findings (match redacted):")
+            for f in scan_result.findings:
+                lines.append(
+                    f"    [{f.severity.upper():6}] {f.path}:{f.line} "
+                    f"{f.rule} — {redact(f.match)}"
+                )
         if errors:
             lines.append("")
             lines.append("errors:")
@@ -71,4 +111,12 @@ def run(args) -> int:
             for w in warnings:
                 lines.append(f"  [{w.get('code')}] {w.get('message')}")
         print("\n".join(lines))
-    return 1 if errors else 0
+
+    # Exit codes:
+    #   1 if there are validation errors
+    #   2 if --scan-secrets was set and any high-severity finding exists
+    #   (both can be true; the higher code wins)
+    rc = 1 if errors else 0
+    if getattr(args, "scan_secrets", False) and scan_result.has_high:
+        rc = max(rc, 2)
+    return rc