arkaos 2.41.0 → 2.43.0

package/VERSION

@@ -1 +1 @@
-2.41.0
+2.43.0

package/arka/SKILL.md

@@ -188,6 +188,7 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 | `/arka status` | System status (version, departments, agents, active projects). Includes **LLM costs (24h)** section: top-line cost + cache hit rate + call count from `core.runtime.llm_cost_telemetry.summarise(period="today")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period="today")` (PR19 v2.41.0). |
 | `/arka costs [period]` | LLM cost visibility — aggregates telemetry by day/week/month/all, with top expensive sessions. See `arka/skills/costs/SKILL.md`. Shells out to `python -m core.runtime.llm_cost_telemetry_cli <period>`. |
 | `/arka enforcement [period]` | Enforcement compliance — aggregates flow-marker enforcement telemetry by day/week/month/all. Shows block rate, top blocked tools, top reasons. Shells out to `python -m core.governance.enforcement_telemetry_cli <period>`. |
+| `/arka reorganize [--since-days N]` | Dreaming → Agent reorganizer. Aggregates recent KB pattern/anti-pattern/lesson artifacts (default last 7 days) into a markdown proposal at `~/.arkaos/reorganize-proposals/<date>.md`. **Propose-only** — never modifies agent YAMLs. Sanitizes client identifiers from titles and body excerpts; drops `tags:` field entirely to prevent project-name leaks. Shells out to `python -m core.cognition.reorganizer_cli [--since-days N] [--dry-run]`. |
 | `/arka standup` | Daily standup (projects, priorities, blockers, updates) |
 | `/arka monitor` | System health monitoring |
 | `/arka onboard <path>` | Onboard an existing project into ArkaOS |

package/core/cognition/reorganizer.py

@@ -0,0 +1,412 @@
+"""Dreaming → Agent reorganizer MVP (PR20 v2.42.0).
+
+Propose-only. Scans the KB for pattern/anti-pattern/lesson artifacts
+produced by Dreaming, sanitizes client identifiers, and renders a
+markdown proposal report. Never modifies agent YAMLs — that step is
+left for human review (and PR21 will wire optional auto-PR creation).
+
+Reads only. The only write is the proposal markdown file under
+``output_dir`` (default ``~/.arkaos/reorganize-proposals/``), and only
+when ``dry_run=False``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n(.*)", re.DOTALL)
+_BODY_EXCERPT_LIMIT = 500
+_PROPOSAL_FILENAME_FMT = "%Y-%m-%d.md"
+_DEFAULT_OUTPUT_DIR = Path.home() / ".arkaos" / "reorganize-proposals"
+_REDACT_TOKEN = "<redacted-client>"
+
+# Client-name redaction patterns are loaded from a user-local JSON file —
+# NEVER hard-coded in source. v2.18.0 shipped client names in source and
+# leaked them to the npm registry (see feedback_npm_publish_safety in
+# user memory); v2.42.0 fixes that class of mistake by design.
+#
+# File: ~/.arkaos/redaction-clients.json
+# Shape: {"clients": ["client-a", "client-b", ...]}
+# Missing file or malformed JSON → empty list (no redaction, tags-drop
+# safety net at `_render` is the architectural backstop).
+#
+# Word boundary uses negative lookaround that allows hyphens so
+# `client-a-billing-quirk` redacts the `client-a` segment correctly
+# without false-positives on `client-axfoo`.
+_REDACT_CONFIG_PATH = Path.home() / ".arkaos" / "redaction-clients.json"
+
+
+def _load_client_patterns() -> tuple[str, ...]:
+    """Read the user-local redaction list. Empty tuple on any error."""
+    try:
+        data = json.loads(_REDACT_CONFIG_PATH.read_text(encoding="utf-8"))
+        raw = data.get("clients", [])
+        return tuple(str(c).strip().lower() for c in raw if c and isinstance(c, str))
+    except (OSError, json.JSONDecodeError, AttributeError):
+        return ()
+
+
+def _build_redact_re(patterns: tuple[str, ...]) -> re.Pattern[str] | None:
+    if not patterns:
+        return None
+    escaped = [re.escape(p) for p in patterns]
+    return re.compile(
+        r"(?<![a-z0-9])(" + "|".join(escaped) + r")(?![a-z0-9])",
+        re.IGNORECASE,
+    )
+
+
+_CLIENT_PATTERNS: tuple[str, ...] = _load_client_patterns()
+_REDACT_RE: re.Pattern[str] | None = _build_redact_re(_CLIENT_PATTERNS)
+
+_KNOWN_CATEGORIES = ("pattern", "anti-pattern", "lesson")
+
+
+@dataclass(frozen=True)
+class KbArtifact:
+    """One pattern / anti-pattern / lesson surfaced from the KB."""
+    path: Path
+    category: str
+    title: str
+    confidence: str
+    tags: list[str] = field(default_factory=list)
+    first_seen: str = ""
+    last_seen: str = ""
+    times_used: int = 0
+    body_excerpt: str = ""
+
+
+@dataclass(frozen=True)
+class ProposalReport:
+    """Result of build_proposal — never contains client identifiers."""
+    generated_at: str
+    since_days: int
+    kb_dir: str
+    artifact_count: int
+    by_category: dict[str, int] = field(default_factory=dict)
+    report_markdown: str = ""
+    report_path: Path | None = None
+
+
+def build_proposal(
+    kb_dir: Path,
+    *,
+    since_days: int = 7,
+    output_dir: Path | None = None,
+    dry_run: bool = False,
+) -> ProposalReport:
+    """Aggregate recent KB artifacts into a propose-only markdown report."""
+    kb_dir = Path(kb_dir)
+    cutoff = datetime.now(timezone.utc).date() - timedelta(days=max(since_days - 1, 0))
+    artifacts = _scan_kb(kb_dir, cutoff)
+    by_category = _aggregate_by_category(artifacts)
+    generated_at = datetime.now(timezone.utc).isoformat()
+    markdown = _render(artifacts, by_category, since_days, kb_dir, generated_at)
+    report_path = None if dry_run else _write_report(markdown, output_dir)
+    return ProposalReport(
+        generated_at=generated_at,
+        since_days=since_days,
+        kb_dir=str(kb_dir),
+        artifact_count=len(artifacts),
+        by_category=by_category,
+        report_markdown=markdown,
+        report_path=report_path,
+    )
+
+
+def _aggregate_by_category(artifacts: list[KbArtifact]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for art in artifacts:
+        counts[art.category] = counts.get(art.category, 0) + 1
+    return counts
+
+
+def _write_report(markdown: str, output_dir: Path | None) -> Path:
+    """Atomic markdown write to a validated output directory."""
+    out = _validate_output_dir(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    report_path = out / datetime.now(timezone.utc).strftime(_PROPOSAL_FILENAME_FMT)
+    tmp_path = report_path.with_suffix(f".tmp-{os.getpid()}.md")
+    tmp_path.write_text(markdown, encoding="utf-8")
+    os.replace(tmp_path, report_path)
+    return report_path
+
+
+def _validate_output_dir(output_dir: Path | None) -> Path:
+    """Allowlist the output directory to a safe parent.
+
+    Without this guard, programmatic callers passing an attacker-controlled
+    ``output_dir`` could write the proposal report anywhere the process has
+    write access (e.g., ``~/.ssh/``). Even though the CLI does not expose
+    ``--output-dir``, the public API does — defence in depth.
+
+    Allowed roots:
+      - ``~/.arkaos`` — the canonical production location
+      - the system tempdir — for tests using pytest's ``tmp_path`` and any
+        deliberate scratch use; still bounded by OS process privilege
+    """
+    if output_dir is None:
+        return _DEFAULT_OUTPUT_DIR
+    resolved = Path(output_dir).expanduser().resolve()
+    allowed_roots = (
+        (Path.home() / ".arkaos").resolve(),
+        Path(tempfile.gettempdir()).resolve(),
+    )
+    for root in allowed_roots:
+        try:
+            resolved.relative_to(root)
+            return resolved
+        except ValueError:
+            continue
+    raise ValueError(
+        "output_dir must be under one of "
+        f"{[str(r) for r in allowed_roots]}; got {resolved}"
+    )
+
+
+def _scan_kb(kb_dir: Path, cutoff) -> list[KbArtifact]:
+    if not kb_dir.is_dir():
+        return []
+    out: list[KbArtifact] = []
+    for md in sorted(kb_dir.rglob("*.md")):
+        category = _category_from_filename(md.name)
+        if category is None:
+            continue
+        try:
+            text = md.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        artifact = _parse_artifact(md, text, category)
+        if artifact is None:
+            continue
+        if not _within_window(artifact, cutoff):
+            continue
+        out.append(artifact)
+    return out
+
+
+def _category_from_filename(name: str) -> str | None:
+    lower = name.lower()
+    if lower.startswith("anti-pattern-"):
+        return "anti-pattern"
+    if lower.startswith("pattern-"):
+        return "pattern"
+    if lower.startswith("lesson-"):
+        return "lesson"
+    return None
+
+
+def _parse_artifact(path: Path, text: str, default_category: str) -> KbArtifact | None:
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return None
+    fm = _parse_frontmatter(match.group(1))
+    if not fm:
+        return None
+    body = match.group(2)
+    category = str(fm.get("category", default_category))
+    if category not in _KNOWN_CATEGORIES:
+        category = default_category
+    raw_title = str(fm.get("title", path.stem))
+    excerpt = _redact(_body_excerpt(body))
+    times_used = _safe_int(fm.get("times_used"))
+    return KbArtifact(
+        path=path,
+        category=category,
+        title=_redact(raw_title),
+        confidence=str(fm.get("confidence", "")),
+        tags=_parse_list(fm.get("tags")),
+        first_seen=str(fm.get("first_seen", "")),
+        last_seen=str(fm.get("last_seen", "")),
+        times_used=times_used,
+        body_excerpt=excerpt,
+    )
+
+
+def _within_window(artifact: KbArtifact, cutoff) -> bool:
+    for raw in (artifact.last_seen, artifact.first_seen):
+        try:
+            seen = datetime.strptime(raw, "%Y-%m-%d").date()
+        except (ValueError, TypeError):
+            continue
+        if seen >= cutoff:
+            return True
+    return not artifact.first_seen and not artifact.last_seen
+
+
+def _parse_frontmatter(block: str) -> dict:
+    out: dict[str, object] = {}
+    current_key: str | None = None
+    current_list: list[str] = []
+    for raw_line in block.splitlines():
+        if not raw_line.strip():
+            continue
+        if raw_line.startswith("  - "):
+            current_list.append(raw_line[4:].strip())
+            continue
+        if current_key is not None and current_list:
+            out[current_key] = list(current_list)
+            current_list = []
+        current_key = None
+        if ":" not in raw_line:
+            continue
+        key, _, value = raw_line.partition(":")
+        key, value = key.strip(), value.strip()
+        if value == "":
+            current_key = key
+            continue
+        out[key] = _parse_inline_value(value)
+    if current_key is not None and current_list:
+        out[current_key] = list(current_list)
+    return out
+
+
+def _parse_inline_value(value: str) -> object:
+    if value.startswith("[") and value.endswith("]"):
+        inner = value[1:-1].strip()
+        if not inner:
+            return []
+        return [item.strip() for item in inner.split(",")]
+    return value
+
+
+def _parse_list(value: object) -> list[str]:
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    if isinstance(value, str) and value:
+        return [value]
+    return []
+
+
+def _safe_int(value: object) -> int:
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _redact(text: str) -> str:
+    if _REDACT_RE is None:
+        return text
+    return _REDACT_RE.sub(_REDACT_TOKEN, text)
+
+
+def _md_escape(text: str) -> str:
+    """Escape markdown control characters that would distort a table row.
+
+    Titles and excerpts come from frontmatter the operator controls, but
+    a `|` in a title silently shifts table columns and corrupts the raw-
+    artifact table. Escape pipes, newlines, and stray backticks.
+    """
+    return (
+        text.replace("\\", "\\\\")
+            .replace("|", "\\|")
+            .replace("\n", " ")
+            .replace("\r", " ")
+            .replace("`", "")
+    )
+
+
+def _body_excerpt(body: str) -> str:
+    stripped = body.strip()
+    if len(stripped) <= _BODY_EXCERPT_LIMIT:
+        return stripped
+    return stripped[:_BODY_EXCERPT_LIMIT].rstrip() + "..."
+
+
+def _render(
+    artifacts: list[KbArtifact],
+    by_category: dict[str, int],
+    since_days: int,
+    kb_dir: Path,
+    generated_at: str,
+) -> str:
+    today = generated_at.split("T", 1)[0]
+    parts = [
+        _render_header(today, len(artifacts), since_days),
+        _render_summary(by_category, since_days, len(artifacts)),
+    ]
+    if not artifacts:
+        parts.append("\n_(no artifacts in window — nothing to propose)_")
+        return "\n".join(parts)
+    parts.append(_render_suggested_actions(artifacts))
+    parts.append("## Raw artifact list\n\n" + _render_table(artifacts))
+    return "\n".join(parts)
+
+
+def _render_header(today: str, count: int, since_days: int) -> str:
+    return (
+        f"# ArkaOS Reorganization Proposal — {today}\n"
+        "\n"
+        f"> Generated by `/arka reorganize` from {count} artifact(s) "
+        f"learned in the last {since_days} days.\n"
+        "> **Propose-only** — no agent YAML changes have been applied."
+    )
+
+
+def _render_summary(by_category: dict[str, int], since_days: int, count: int) -> str:
+    lines = [
+        "\n## Summary\n",
+        f"- Window: last {since_days} days",
+        f"- Artifacts: **{count}**",
+    ]
+    for cat in _KNOWN_CATEGORIES:
+        if cat in by_category:
+            lines.append(f"- {cat.capitalize()}s: {by_category[cat]}")
+    return "\n".join(lines)
+
+
+def _render_suggested_actions(artifacts: list[KbArtifact]) -> str:
+    lines = ["\n## Suggested actions\n"]
+    for cat in _KNOWN_CATEGORIES:
+        cat_items = [a for a in artifacts if a.category == cat]
+        if not cat_items:
+            continue
+        lines.append(f"### {cat.capitalize()}s\n")
+        for art in cat_items:
+            lines.append(_render_artifact_bullet(art, cat))
+    return "\n".join(lines)
+
+
+def _render_artifact_bullet(art: KbArtifact, category: str) -> str:
+    # Tags intentionally NOT rendered — see _CLIENT_PATTERNS comment.
+    line = (
+        f"- **{art.title}** (confidence: {art.confidence or 'n/a'}, "
+        f"times_used: {art.times_used})\n"
+        f"  suggested: review for {_suggest_target(category)}"
+    )
+    if art.body_excerpt:
+        line += f"\n  > {art.body_excerpt}"
+    return line + "\n"
+
+
+def _suggest_target(category: str) -> str:
+    if category == "pattern":
+        return "surfacing in the relevant department squad's context"
+    if category == "anti-pattern":
+        return "candidate detector in `core/governance/learning_detector.py`"
+    if category == "lesson":
+        return "Tier 0 review — potential constitution amendment"
+    return "manual review"
+
+
+def _render_table(artifacts: list[KbArtifact]) -> str:
+    rows = [
+        "| Category | Title | Confidence | first_seen | last_seen | times_used |",
+        "|---|---|---|---|---|---|",
+    ]
+    for art in artifacts:
+        rows.append(
+            f"| {_md_escape(art.category)} | {_md_escape(art.title)} "
+            f"| {_md_escape(art.confidence) or 'n/a'} "
+            f"| {_md_escape(art.first_seen) or 'n/a'} "
+            f"| {_md_escape(art.last_seen) or 'n/a'} "
+            f"| {art.times_used} |"
+        )
+    return "\n".join(rows)

package/core/cognition/reorganizer_cli.py

@@ -0,0 +1,72 @@
+"""CLI for the propose-only Dreaming reorganizer (PR20 v2.42.0).
+
+Invoked as ``python -m core.cognition.reorganizer_cli [options]``.
+Reads recent KB artifacts (pattern / anti-pattern / lesson files),
+sanitizes client identifiers, and writes a proposal markdown report.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from core.cognition.reorganizer import build_proposal
+
+# Default KB location — the Obsidian vault subfolder where Dreaming v2
+# writes pattern/anti-pattern/lesson artifacts. Overridable via env var
+# or --kb-dir for tests and unusual installs.
+_DEFAULT_KB_DIR = (
+    Path.home()
+    / "Documents" / "Personal" / "Projects"
+    / "WizardingCode Internal" / "ArkaOS" / "Knowledge Base"
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="arkaos-reorganize",
+        description="Aggregate recent KB artifacts into a propose-only "
+                    "markdown report. Never modifies agent YAMLs.",
+    )
+    parser.add_argument(
+        "--since-days", type=int, default=7,
+        help="Window in days for first_seen/last_seen filter (default: 7).",
+    )
+    parser.add_argument(
+        "--kb-dir", type=Path, default=None,
+        help="Override the KB directory to scan (default: ArkaOS vault).",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Print the report to stdout, do not write to disk.",
+    )
+    return parser
+
+
+def main(argv: list[str]) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv[1:])
+    kb_dir = args.kb_dir or Path(os.environ.get("ARKAOS_KB_DIR", _DEFAULT_KB_DIR))
+
+    report = build_proposal(
+        kb_dir,
+        since_days=args.since_days,
+        dry_run=args.dry_run,
+    )
+
+    if args.dry_run:
+        print(report.report_markdown)
+        return 0
+
+    print(f"Artifacts: {report.artifact_count}")
+    for cat, count in sorted(report.by_category.items()):
+        print(f"  {cat}: {count}")
+    if report.report_path is not None:
+        print(f"Report: {report.report_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/core/release/__init__.py

@@ -0,0 +1 @@
+"""Release pipeline tooling — preflight gate, version helpers."""

package/core/release/preflight.py

@@ -0,0 +1,225 @@
+"""Release preflight gate (PR21 v2.43.0).
+
+Runs BEFORE the irreversible tag/push/publish steps of the release
+pipeline. Catches expired tokens, version misalignment, and dirty
+git state at minute 0 instead of minute 60.
+
+Closes a real-world debt: v2.40.0 release took ~1h because the npm
+token had expired silently and the failure was only discovered
+after merge, tag, GH release. A 2-second check up front would have
+turned that into an immediate STOP-and-rotate.
+
+All shell-outs use ``subprocess.run(check=False, capture_output=True,
+timeout=10)`` with argv as a list — no ``shell=True``, no string
+interpolation of user input.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_DEFAULT_REPO_ROOT = Path.cwd()
+_SUBPROCESS_TIMEOUT = 10
+_NPM_PACKAGE_VERSION_RE = re.compile(r'"version"\s*:\s*"([^"]+)"')
+_PYPROJECT_VERSION_RE = re.compile(r'^version\s*=\s*"([^"]+)"', re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Single preflight check outcome."""
+    name: str
+    passed: bool
+    reason: str
+    remediation: str | None = None
+    severity: str = "blocking"
+
+
+@dataclass(frozen=True)
+class PreflightReport:
+    """Aggregated preflight verdict."""
+    all_passed: bool
+    results: list[CheckResult] = field(default_factory=list)
+    blocking_failures: list[CheckResult] = field(default_factory=list)
+    warnings: list[CheckResult] = field(default_factory=list)
+
+
+def run_preflight(
+    *,
+    repo_root: Path | None = None,
+    expected_npm_user: str | None = None,
+) -> PreflightReport:
+    """Run every preflight check and return an aggregated report."""
+    root = repo_root or _DEFAULT_REPO_ROOT
+    results = [
+        check_version_alignment(repo_root=root),
+        check_npm_auth(expected_user=expected_npm_user),
+        check_npm_publish_capability(),
+        check_gh_auth(),
+        check_git_remote(),
+        check_git_clean(),
+    ]
+    return _aggregate(results)
+
+
+def _load_repo_versions(
+    root: Path,
+) -> tuple[str | None, str | None, str | None] | None:
+    """Read VERSION, package.json, pyproject.toml. None if any unreadable."""
+    try:
+        v = (root / "VERSION").read_text(encoding="utf-8").strip()
+        pkg_match = _NPM_PACKAGE_VERSION_RE.search(
+            (root / "package.json").read_text(encoding="utf-8"),
+        )
+        py_match = _PYPROJECT_VERSION_RE.search(
+            (root / "pyproject.toml").read_text(encoding="utf-8"),
+        )
+    except (OSError, AttributeError):
+        return None
+    pkg_v = pkg_match.group(1) if pkg_match else None
+    py_v = py_match.group(1) if py_match else None
+    return v, pkg_v, py_v
+
+
+def check_version_alignment(*, repo_root: Path | None = None) -> CheckResult:
+    """Verify VERSION, package.json, pyproject.toml all carry the same version."""
+    root = repo_root or _DEFAULT_REPO_ROOT
+    versions = _load_repo_versions(root)
+    if versions is None:
+        return CheckResult(
+            name="version-alignment", passed=False,
+            reason="could not read one of VERSION / package.json / pyproject.toml",
+            remediation="ensure all three files exist at repo root",
+        )
+    v, pkg_v, py_v = versions
+    if v and pkg_v == v and py_v == v:
+        return CheckResult(
+            name="version-alignment", passed=True,
+            reason=f"all three at {v}",
+        )
+    return CheckResult(
+        name="version-alignment", passed=False,
+        reason=f"mismatch: VERSION={v} package.json={pkg_v} pyproject={py_v}",
+        remediation="align all three files to the same version, then re-run",
+    )
+
+
+def check_npm_auth(*, expected_user: str | None = None) -> CheckResult:
+    """Verify `npm whoami` returns a valid user (and matches expected, if set)."""
+    out = _run(["npm", "whoami"])
+    if out is None:
+        return CheckResult(
+            name="npm-auth", passed=False,
+            reason="npm command not found or timed out",
+            remediation="install Node.js / npm and retry",
+        )
+    if out.returncode != 0:
+        return CheckResult(
+            name="npm-auth", passed=False,
+            reason=f"npm whoami failed: {out.stderr.strip() or 'unknown'}",
+            remediation="run `npm login` or rotate token in ~/.npmrc",
+        )
+    user = out.stdout.strip()
+    if expected_user and user != expected_user:
+        return CheckResult(
+            name="npm-auth", passed=False,
+            reason=f"npm authenticated as {user}, expected {expected_user}",
+            remediation=f"switch token to {expected_user} or update expected user",
+        )
+    return CheckResult(
+        name="npm-auth", passed=True,
+        reason=f"authenticated as {user}",
+    )
+
+
+def check_npm_publish_capability() -> CheckResult:
+    """Verify `npm pack --dry-run` succeeds — proves write scope on the package."""
+    out = _run(["npm", "pack", "--dry-run"])
+    if out is None or out.returncode != 0:
+        msg = (out.stderr.strip() if out else "command unavailable") or "unknown"
+        return CheckResult(
+            name="npm-publish-capability", passed=False,
+            reason=f"pack dry-run failed: {msg}",
+            remediation="check granular token has 'read and write' on this package",
+        )
+    return CheckResult(
+        name="npm-publish-capability", passed=True,
+        reason="pack dry-run OK",
+    )
+
+
+def check_gh_auth() -> CheckResult:
+    """Verify `gh auth status` reports a logged-in session."""
+    out = _run(["gh", "auth", "status"])
+    if out is None:
+        return CheckResult(
+            name="gh-auth", passed=False,
+            reason="gh command not found or timed out",
+            remediation="install the GitHub CLI and run `gh auth login`",
+        )
+    if out.returncode != 0:
+        return CheckResult(
+            name="gh-auth", passed=False,
+            reason="gh not authenticated",
+            remediation="run `gh auth login`",
+        )
+    return CheckResult(name="gh-auth", passed=True, reason="authenticated")
+
+
+def check_git_remote() -> CheckResult:
+    """Verify `git remote get-url origin` returns a real remote URL."""
+    out = _run(["git", "remote", "get-url", "origin"])
+    if out is None or out.returncode != 0:
+        return CheckResult(
+            name="git-remote", passed=False,
+            reason="no `origin` remote configured",
+            remediation="set up the remote with `git remote add origin <url>`",
+        )
+    return CheckResult(
+        name="git-remote", passed=True,
+        reason=out.stdout.strip(),
+    )
+
+
+def check_git_clean() -> CheckResult:
+    """Flag uncommitted changes as a WARNING (not blocking)."""
+    out = _run(["git", "status", "--porcelain"])
+    if out is None:
+        return CheckResult(
+            name="git-clean", passed=False, severity="warning",
+            reason="git not available",
+        )
+    dirty = out.stdout.strip()
+    if not dirty:
+        return CheckResult(name="git-clean", passed=True, reason="working tree clean")
+    file_count = len([line for line in dirty.splitlines() if line.strip()])
+    return CheckResult(
+        name="git-clean", passed=False, severity="warning",
+        reason=f"{file_count} uncommitted file(s)",
+        remediation="commit, stash, or proceed deliberately",
+    )
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess | None:
+    """subprocess.run with our defaults; returns None on missing exe / timeout."""
+    try:
+        return subprocess.run(
+            cmd, capture_output=True, text=True,
+            timeout=_SUBPROCESS_TIMEOUT, check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+
+
+def _aggregate(results: list[CheckResult]) -> PreflightReport:
+    blocking = [r for r in results if not r.passed and r.severity == "blocking"]
+    warnings = [r for r in results if not r.passed and r.severity == "warning"]
+    return PreflightReport(
+        all_passed=not blocking,
+        results=results,
+        blocking_failures=blocking,
+        warnings=warnings,
+    )

package/core/release/preflight_cli.py

@@ -0,0 +1,74 @@
+"""CLI entry for the release preflight gate (PR21 v2.43.0).
+
+Usage:
+    python -m core.release.preflight_cli [--expected-npm-user USER]
+
+Exit code: 0 if all blocking checks pass, 1 otherwise. Warnings never
+gate the exit code. Output is markdown so it renders cleanly in both
+terminal and PR comments.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timezone
+
+from core.release.preflight import (
+    CheckResult,
+    PreflightReport,
+    run_preflight,
+)
+
+
+def _glyph(result: CheckResult) -> str:
+    if result.passed:
+        return "PASS"
+    if result.severity == "warning":
+        return "WARN"
+    return "FAIL"
+
+
+def _render(report: PreflightReport) -> str:
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    lines = [
+        f"# Release Preflight — {today}",
+        "",
+        "| Check | Status | Notes |",
+        "|---|---|---|",
+    ]
+    for r in report.results:
+        notes = r.reason or ""
+        if r.remediation and not r.passed:
+            notes = f"{notes} | remediation: {r.remediation}"
+        lines.append(f"| {r.name} | {_glyph(r)} | {notes} |")
+    lines.append("")
+    if report.blocking_failures:
+        lines.append(f"**BLOCKED — {len(report.blocking_failures)} failure(s).** "
+                     "Fix each remediation and rerun before tagging/publishing.")
+    elif report.warnings:
+        lines.append(f"All blocking checks passed ({len(report.warnings)} "
+                     "warning(s) noted, non-blocking).")
+    else:
+        lines.append("All checks green. Safe to proceed to tag → release → publish.")
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="arkaos-preflight",
+        description="Run release preflight checks. Exit 1 on any blocking failure.",
+    )
+    parser.add_argument(
+        "--expected-npm-user", default=None,
+        help="Assert that `npm whoami` returns this user (e.g. wizardingcode).",
+    )
+    args = parser.parse_args(argv[1:])
+
+    report = run_preflight(expected_npm_user=args.expected_npm_user)
+    print(_render(report))
+    return 0 if report.all_passed else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.41.0",
+  "version": "2.43.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.41.0"
+version = "2.43.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}