@event4u/agent-config 5.10.1 → 6.1.0

package/src/scripts/condense_memory.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Input-side memory condensation — Phase 2 of step-16-telegraph-substance.
+
+Rewrites memory files (AGENTS.md, CLAUDE.md, .cursorrules, ...) to telegraph
+grammar (drop articles / auxiliaries) while preserving carve-outs byte-for-byte
+(code blocks, numbered-options, status markers, Iron-Law ALL-CAPS, backtick
+spans). Writes `.original.md` backup before mutating. Gated by Phase 0
+`validate_safe_paths.assert_safe`. Idempotency guard: `original_sha256:` +
+`condensed_at:` frontmatter refuse re-condensation on body-hash drift.
+
+CLI: `condense_memory.py <path> [--check|--decondense]`. Stdlib-only.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(REPO_ROOT / "src" / "scripts"))
+
+from validate_safe_paths import SensitivePathError, assert_safe  # noqa: E402
+
+__all__ = ["condense_text", "condense_file", "decondense_file", "CondensationRefused"]
+
+
+class CondensationRefused(RuntimeError):
+    """Raised when the target is already condensed and body hash diverged."""
+
+
+# Carve-out region patterns — mirrors telegraph-speak.md § Carve-outs (1–7).
+RE_FENCE = re.compile(r"^```")
+RE_NUMBERED = re.compile(r"^>?\s*\d+\.\s")
+RE_STATUS = re.compile(r"^\s*(?:❌|⚠️|✅)")
+RE_IRONLAW = re.compile(r"^[A-Z][A-Z0-9 ,.\-_/']{3,}$")
+RE_BACKTICK_SPAN = re.compile(r"`[^`\n]+`")
+# Spans frozen byte-for-byte inside prose lines. Backtick spans first so a
+# slash-bearing span inside backticks is captured whole; then any non-whitespace
+# run containing `/` or `\` — bare URLs, markdown link/image targets, and file
+# paths whose segments (`is`, `the`, `a`) would otherwise be eaten as drop-tokens.
+RE_PRESERVE_SPAN = re.compile(r"`[^`\n]+`|\S*[/\\]\S*")
+RE_FRONTMATTER = re.compile(r"^---\s*$")
+WORD_RE = re.compile(r"\b[A-Za-z]+\b")
+DROP_TOKENS = {"the", "a", "an", "is", "are", "was", "were", "be", "been",
+               "being", "that", "which"}
+
+
+def _condense_words(text: str) -> str:
+    out = WORD_RE.sub(lambda m: "" if m.group(0).lower() in DROP_TOKENS else m.group(0), text)
+    out = re.sub(r"[ \t]{2,}", " ", out)
+    return re.sub(r" +([,.;:!?])", r"\1", out)
+
+
+def _condense_prose_line(line: str) -> str:
+    """Condense a prose line; preserve backtick spans, URLs, link targets, and
+    slash-bearing paths byte-for-byte (see ``RE_PRESERVE_SPAN``)."""
+    parts: list[str] = []
+    last = 0
+    for span in RE_PRESERVE_SPAN.finditer(line):
+        parts.append(_condense_words(line[last:span.start()]))
+        parts.append(span.group(0))
+        last = span.end()
+    parts.append(_condense_words(line[last:]))
+    return "".join(parts)
+
+
+def condense_text(body: str) -> str:
+    """Condense a memory-file body. Idempotent on already-telegraph text."""
+    out: list[str] = []
+    in_fence = False
+    for raw in body.splitlines(keepends=True):
+        stripped = raw.rstrip("\r\n")
+        if RE_FENCE.match(stripped):
+            in_fence = not in_fence
+            out.append(raw)
+            continue
+        if in_fence or RE_NUMBERED.match(stripped) or RE_STATUS.match(stripped) \
+                or RE_IRONLAW.match(stripped.strip()):
+            out.append(raw)
+            continue
+        out.append(_condense_prose_line(raw))
+    return "".join(out)
+
+
+def _split_frontmatter(text: str) -> tuple[str, str]:
+    lines = text.splitlines(keepends=True)
+    if not lines or not RE_FRONTMATTER.match(lines[0].rstrip()):
+        return "", text
+    for idx in range(1, len(lines)):
+        if RE_FRONTMATTER.match(lines[idx].rstrip()):
+            return "".join(lines[: idx + 1]), "".join(lines[idx + 1:])
+    return "", text
+
+
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _has_sha_marker(fm: str) -> bool:
+    return bool(re.search(r"^original_sha256:\s*[0-9a-f]{64}\s*$", fm, re.MULTILINE))
+
+
+def _inject_frontmatter(fm: str, sha: str, ts: str) -> str:
+    drop = re.compile(r"^(original_sha256|condensed_at):.*$", re.MULTILINE)
+    inner = drop.sub("", fm.strip().strip("-").strip()).strip() if fm else ""
+    body = inner + ("\n" if inner else "")
+    return f"---\n{body}original_sha256: {sha}\ncondensed_at: {ts}\n---\n"
+
+
+def _backup_path(target: Path) -> Path:
+    return target.parent / (target.name + ".original.md")
+
+
+def condense_file(target: Path) -> Path:
+    assert_safe(target)
+    text = target.read_text(encoding="utf-8")
+    fm, body = _split_frontmatter(text)
+    if _has_sha_marker(fm):
+        if _sha256(condense_text(body)) != _sha256(body):
+            raise CondensationRefused(
+                f"{target}: body hash diverged; decondense first "
+                f"(`scripts/condense_memory.py {target} --decondense`)."
+            )
+        return target
+    backup = _backup_path(target)
+    backup.write_text(text, encoding="utf-8")
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    target.write_text(
+        _inject_frontmatter(fm, _sha256(body), ts) + condense_text(body),
+        encoding="utf-8",
+    )
+    return backup
+
+
+def decondense_file(target: Path) -> Path:
+    assert_safe(target)
+    backup = _backup_path(target)
+    if not backup.is_file():
+        raise FileNotFoundError(f"no backup at {backup}")
+    target.write_text(backup.read_text(encoding="utf-8"), encoding="utf-8")
+    backup.unlink()
+    return target
+
+
+def _main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description="Condense memory files to telegraph grammar.")
+    ap.add_argument("path", type=Path)
+    grp = ap.add_mutually_exclusive_group()
+    grp.add_argument("--check", action="store_true", help="exit 0 if safe; no writes")
+    grp.add_argument("--decondense", action="store_true", help="restore .original.md")
+    args = ap.parse_args(argv)
+    try:
+        if args.check:
+            assert_safe(args.path)
+            return 0
+        if args.decondense:
+            decondense_file(args.path)
+            print(f"decondenseed: {args.path}")
+            return 0
+        backup = condense_file(args.path)
+        print(f"condensed: {args.path}  (backup: {backup})")
+        return 0
+    except SensitivePathError as exc:
+        print(f"error: refused: {exc}", file=sys.stderr)
+        return 2
+    except CondensationRefused as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 3
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 4
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main(sys.argv[1:]))

package/src/scripts/config/packs.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Pack loader (6.0.0-B Phase 3) — deterministic build/install-time resolver.
+
+Given a selected pack set, resolves:
+
+  1. the full ACTIVE PACK set — seed the ``always_on`` packs + the selected
+     packs, then expand the ``requires`` closure (capability-packs.md;
+     ``suggests`` is advisory and is NOT expanded);
+  2. the ACTIVE ARTEFACT set — commands by their canonical ``pack`` OWNER,
+     skills by ``packs`` membership. Rules are excluded: they stay
+     router-driven (ADR-040). ``legacy_all=True`` returns the full set —
+     the 6.0.0 default, byte-for-byte the pre-6.0.0 projection.
+
+This is the resolver ADR-040 scopes as build/install-time — NOT a runtime
+daemon. The projector (``scripts/condense.py``) and ``agent-config use``
+(``scripts/profile_use.py``) consult it; it never runs per host-tool request.
+
+CLI (debugging):
+  python3 scripts/config/packs.py --packs laravel,finance-basic
+  python3 scripts/config/packs.py --legacy-all
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT / "src"))
+
+# Reuse the vocab / closure / manifest loaders — single source of truth.
+from scripts.config.session_profiles import (  # noqa: E402
+    expand_closure,
+    load_manifest,
+    load_packs_vocab,
+)
+
+_PROJECTED_CATEGORIES = ("command", "skill")  # rules stay router-driven
+
+
+@dataclass
+class ActiveSet:
+    """Resolved active pack + artefact set for one projection."""
+
+    packs: list[str]
+    commands: list[str]
+    skills: list[str]
+    legacy_all: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "legacy_all": self.legacy_all,
+            "packs": self.packs,
+            "commands": self.commands,
+            "skills": self.skills,
+            "counts": {
+                "packs": len(self.packs),
+                "commands": len(self.commands),
+                "skills": len(self.skills),
+            },
+        }
+
+
+def always_on_packs(vocab: dict[str, dict[str, Any]]) -> set[str]:
+    """Default packs the resolver seeds into every scoped projection."""
+    return {pid for pid, p in vocab.items() if (p or {}).get("always_on")}
+
+
+def resolve_active_packs(
+    vocab: dict[str, dict[str, Any]],
+    selected: Iterable[str] | None,
+    *,
+    legacy_all: bool = False,
+) -> list[str]:
+    """Full active pack set: always-on ∪ selected, expanded over ``requires``.
+
+    ``legacy_all`` short-circuits to the entire declared vocabulary.
+    ``suggests`` edges are advisory and intentionally not expanded.
+    """
+    if legacy_all:
+        return sorted(vocab.keys())
+    seeds = set(selected or ()) | always_on_packs(vocab)
+    # Drop unknown ids defensively — a typo'd pack must not crash projection.
+    seeds &= set(vocab.keys())
+    return expand_closure(seeds, vocab)
+
+
+def resolve_active_set(
+    repo_root: Path,
+    selected: Iterable[str] | None = None,
+    *,
+    legacy_all: bool = False,
+) -> ActiveSet:
+    """Resolve the active pack + artefact set for a projection.
+
+    Command membership is OWNER-based (``pack``); skill membership is
+    discovery-based (``packs`` ∩ active). Rules are never returned.
+    """
+    vocab = load_packs_vocab(repo_root)
+    active = set(resolve_active_packs(vocab, selected, legacy_all=legacy_all))
+    commands: list[str] = []
+    skills: list[str] = []
+    for art in load_manifest(repo_root):
+        cat = art.get("category")
+        if cat not in _PROJECTED_CATEGORIES:
+            continue
+        path = art.get("path")
+        if not path:
+            continue
+        if legacy_all:
+            (commands if cat == "command" else skills).append(path)
+            continue
+        if cat == "command":
+            if art.get("pack") in active:
+                commands.append(path)
+        else:  # skill
+            if set(art.get("packs") or ()) & active:
+                skills.append(path)
+    return ActiveSet(
+        packs=sorted(active),
+        commands=sorted(commands),
+        skills=sorted(skills),
+        legacy_all=legacy_all,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--packs", default="", help="Comma-separated selected pack ids."
+    )
+    parser.add_argument(
+        "--legacy-all", action="store_true",
+        help="Resolve the full set (6.0.0 default, non-breaking).",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit JSON.")
+    args = parser.parse_args(argv)
+
+    selected = [p.strip() for p in args.packs.split(",") if p.strip()]
+    result = resolve_active_set(REPO_ROOT, selected, legacy_all=args.legacy_all)
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        mode = "legacy-all" if result.legacy_all else f"scoped({','.join(selected) or 'always-on only'})"
+        print(f"Active set [{mode}]:")
+        print(f"  packs ({len(result.packs)}): {', '.join(result.packs)}")
+        print(f"  commands: {len(result.commands)}")
+        print(f"  skills:   {len(result.skills)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/scripts/config/profile_explain.py

@@ -0,0 +1,89 @@
+"""profile_explain — the `profile-overlay` explain envelope + renderer.
+
+Phase 2 of road-to-session-profile-observability: answer "why is the agent
+behaving differently / why is the surface different?" over the session-profile
+overlay, in plain language by default (`technical` for an engineering lead).
+
+Trust boundary (AI-council amendment): the renderer is a **pure template** over
+the envelope fields — it NEVER calls an LLM and NEVER reads beyond the overlay
+state it is handed. `build_profile_envelope` is the only place that reads state;
+`render_profile_overlay` is a pure function of the envelope (golden-testable).
+
+Reuses the explain-modes two-views-over-one-envelope convention
+(`docs/contracts/explain-modes.md`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+ENVELOPE_TYPE = "profile-overlay"
+
+
+def build_profile_envelope(
+    active_packs: list[str],
+    commands_shown: int,
+    skills_shown: int,
+    hidden_total: int,
+) -> dict[str, Any]:
+    """Build the `profile-overlay` envelope from the `show`/`surface` state.
+
+    Only the persisted overlay state is available, so seed-vs-closure split and
+    staleness-age-in-days are intentionally NOT fields (the overlay stores the
+    effective pack set, no request log, no timestamp — see the contract). The
+    overlay set is reported as the effective `active_packs`; staleness is
+    persistence, not an age.
+    """
+    return {
+        "envelope_type": ENVELOPE_TYPE,
+        "active": list(active_packs),
+        "commands_shown": commands_shown,
+        "skills_shown": skills_shown,
+        "hidden_total": hidden_total,
+        # deterministic "what changed vs the full surface"
+        "delta": {"hidden_behind_inactive_packs": hidden_total},
+        # staleness = persistence (no timestamp in the overlay)
+        "persists_across_sessions": bool(active_packs),
+    }
+
+
+def _g(env: dict[str, Any], key: str, default: Any) -> Any:
+    """Missing-field-tolerant getter — the renderer never throws on a partial
+    envelope (a missing field renders a placeholder, per the coverage spec)."""
+    v = env.get(key, default)
+    return default if v is None else v
+
+
+def render_profile_overlay(envelope: dict[str, Any], mode: str = "plain") -> str:
+    """Pure render of the `profile-overlay` envelope. `plain` (default) for a
+    non-technical employee; `technical` for an engineering lead. Never raises on
+    a partial envelope."""
+    active = _g(envelope, "active", [])
+    cmds = _g(envelope, "commands_shown", "?")
+    skills = _g(envelope, "skills_shown", "?")
+    hidden = _g(envelope, "hidden_total", "?")
+
+    if not active:
+        if mode == "technical":
+            return "profile-overlay: none active — full surface (no filtering)."
+        return (
+            "Nothing is filtered — no profile is active, so you see every command "
+            "and skill. The agent isn't hiding anything."
+        )
+
+    names = ", ".join(active) if isinstance(active, list) else str(active)
+    if mode == "technical":
+        return "\n".join([
+            f"profile-overlay: active=[{names}]",
+            f"  surfaced: commands={cmds} skills={skills}",
+            f"  hidden:   {hidden} (behind inactive packs)",
+            "  delta:    surface = full ∖ (artefacts whose packs ∉ active)",
+            "  staleness: persists across sessions (overlay has no timestamp)",
+        ])
+    return "\n".join([
+        f"Why the surface looks different: a profile is active ({names}).",
+        f"It shows you {cmds} commands and {skills} skills, and hides {hidden} "
+        "behind packs you haven't turned on — that's why some commands aren't visible.",
+        "Nothing is broken; the overlay just narrows the surface to this profile.",
+        "It stays this way across sessions until you run `/profile deactivate`.",
+    ])

package/src/scripts/config/profiles.py

@@ -0,0 +1,191 @@
+"""Profile loader — step-15 Phase 1 item 1.
+
+Resolves the active ``profile.id`` from the chain documented in
+:mod:`docs.contracts.profile-system` and returns a structured
+:class:`ResolvedProfile`. Pure, read-only, lazy-PyYAML.
+
+Resolution chain (last writer wins):
+
+1. Pack-supplied ``profile_id`` (Phase 2 item 7 — pack loader passes it
+   in via ``pack_profile_id``; ``None`` until packs land).
+2. ``.agent-settings.yml`` top-level ``profile.id`` (and any user
+   overrides for ``audience`` / ``defaults`` / ``surface``).
+3. Environment variable ``AGENT_CONFIG_PROFILE_ID``.
+4. Runtime CLI flag — caller passes ``runtime_id``.
+
+Falls back to ``developer`` **only** when no settings file exists yet
+(fresh install before ``/onboard``). With a settings file present but
+no ``profile`` block, the loader returns a structured warning state so
+``/onboard`` can surface "audience not yet picked".
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from scripts._lib import agent_settings
+
+logger = logging.getLogger(__name__)
+
+PROFILE_ID_ENV = "AGENT_CONFIG_PROFILE_ID"
+SEED_PROFILE_IDS: tuple[str, ...] = (
+    "founder",
+    "developer",
+    "content_creator",
+    "agency",
+    "finance",
+    "ops",
+)
+DEFAULT_PROFILE_ID = "developer"
+PROFILES_DIRNAME = ".agent-src.uncondensed/profiles"
+
+SOURCE_PACK = "pack"
+SOURCE_USER = "user-settings"
+SOURCE_ENV = "env"
+SOURCE_RUNTIME = "runtime"
+SOURCE_DEFAULT = "default"
+SOURCE_MISSING = "missing"
+
+
+@dataclass(frozen=True)
+class ResolvedProfile:
+    """Outcome of :func:`resolve_profile`. See profile-system contract."""
+
+    id: str
+    audience: dict[str, str] = field(default_factory=dict)
+    preset_id: str | None = None
+    packs: tuple[str, ...] = ()
+    personas: tuple[str, ...] = ()
+    skills_hint: tuple[str, ...] = ()
+    commands_hint: tuple[str, ...] = ()
+    docs_first_pointer: str | None = None
+    source: str = SOURCE_DEFAULT
+    warning: str | None = None
+
+
+class ProfileError(Exception):
+    """Raised when a profile id is referenced but its YAML cannot load."""
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ImportError:
+        logger.info("PyYAML unavailable; profile %s returned empty", path)
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("profile read failed for %s: %s", path, exc)
+        return {}
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        logger.warning("profile parse failed for %s: %s", path, exc)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _profile_file(project_root: Path, profile_id: str) -> Path:
+    legacy = project_root / PROFILES_DIRNAME / f"{profile_id}.yml"
+    if legacy.exists():
+        return legacy
+    try:
+        import sys as _sys
+        scripts_root = Path(__file__).resolve().parents[1]
+        if str(scripts_root) not in _sys.path:
+            _sys.path.insert(0, str(scripts_root))
+        from _lib.agent_src import artefact_roots  # type: ignore
+    except Exception:
+        return legacy
+    for root in artefact_roots():
+        candidate = root / "profiles" / f"{profile_id}.yml"
+        if candidate.exists():
+            return candidate
+    return legacy
+
+
+def _build_resolved(
+    profile_id: str,
+    raw: dict[str, Any],
+    *,
+    source: str,
+    warning: str | None = None,
+) -> ResolvedProfile:
+    block = raw.get("profile") or {}
+    audience_raw = block.get("audience") or {}
+    defaults = block.get("defaults") or {}
+    surface = block.get("surface") or {}
+    audience = {str(k): str(v) for k, v in audience_raw.items()}
+    packs = tuple(str(p) for p in (block.get("packs") or []))
+    personas = tuple(str(p) for p in (defaults.get("personas") or []))
+    skills_hint = tuple(str(s) for s in (defaults.get("skills_hint") or []))
+    commands_hint = tuple(str(c) for c in (surface.get("commands_hint") or []))
+    docs_pointer = surface.get("docs_first_pointer")
+    return ResolvedProfile(
+        id=profile_id,
+        audience=audience,
+        preset_id=defaults.get("preset_id"),
+        packs=packs,
+        personas=personas,
+        skills_hint=skills_hint,
+        commands_hint=commands_hint,
+        docs_first_pointer=str(docs_pointer) if docs_pointer else None,
+        source=source,
+        warning=warning,
+    )
+
+
+def _pick_id(
+    pack_profile_id: str | None,
+    user_settings: dict[str, Any],
+    runtime_id: str | None,
+) -> tuple[str | None, str]:
+    if runtime_id:
+        return runtime_id, SOURCE_RUNTIME
+    env_id = os.environ.get(PROFILE_ID_ENV)
+    if env_id:
+        return env_id, SOURCE_ENV
+    block = user_settings.get("profile") if isinstance(user_settings, dict) else None
+    if isinstance(block, dict) and block.get("id"):
+        return str(block["id"]), SOURCE_USER
+    if pack_profile_id:
+        return pack_profile_id, SOURCE_PACK
+    return None, SOURCE_MISSING
+
+
+def resolve_profile(
+    *,
+    project_root: Path,
+    user_settings: dict[str, Any] | None = None,
+    pack_profile_id: str | None = None,
+    runtime_id: str | None = None,
+) -> ResolvedProfile:
+    """Return the active :class:`ResolvedProfile` for the current session."""
+    settings = user_settings or {}
+    settings_file = project_root / agent_settings.DEFAULT_PROJECT_FILE
+    profile_id, source = _pick_id(pack_profile_id, settings, runtime_id)
+    if profile_id is None:
+        if settings_file.exists():
+            return ResolvedProfile(
+                id=DEFAULT_PROFILE_ID,
+                source=SOURCE_MISSING,
+                warning=(
+                    "no profile.id in .agent-settings.yml — run /onboard to "
+                    "pick an audience deliberately"
+                ),
+            )
+        return _build_resolved(
+            DEFAULT_PROFILE_ID,
+            _load_yaml(_profile_file(project_root, DEFAULT_PROFILE_ID)),
+            source=SOURCE_DEFAULT,
+        )
+    yaml_path = _profile_file(project_root, profile_id)
+    if not yaml_path.exists():
+        raise ProfileError(
+            f"profile.id={profile_id!r} ({source}) but {yaml_path} not found",
+        )
+    return _build_resolved(profile_id, _load_yaml(yaml_path), source=source)