create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/egregore_runtime/onboarding_cli.py

@@ -0,0 +1,110 @@
+"""Runtime-neutral command adapter for the resumable onboarding ritual."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import subprocess
+from uuid import uuid4
+
+from .errors import AuthorizationDenied
+from .onboarding import OnboardingService
+from .runtime import local_runtime
+from .sync import LocalGitSyncTransport
+
+
+def _context():
+    root = Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
+    runtime = local_runtime(root, push_remote=False)
+    marker = root / ".egregore-session-id"
+    session_id = os.environ.get("EGREGORE_SESSION_ID", "").strip()
+    if not session_id and marker.is_file():
+        session_id = marker.read_text(encoding="utf-8").splitlines()[0].strip()
+    actor = runtime.resolve_actor(
+        session_id=session_id or f"onboarding_{uuid4().hex}",
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    return root, actor, OnboardingService(root, runtime)
+
+
+def _identity(root: Path, command: str, *arguments: str) -> bool:
+    result = subprocess.run(
+        ("bash", str(root / "bin" / "person.sh"), command, *arguments),
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=45,
+    )
+    return result.returncode == 0
+
+
+def _shell_alias(root: Path) -> str | None:
+    result = subprocess.run(
+        ("bash", str(root / "bin" / "ensure-shell-function.sh")),
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=15,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip().splitlines()[-1]
+    return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="egregore-onboarding")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("status")
+    name = commands.add_parser("set-name")
+    name.add_argument("value")
+    role = commands.add_parser("set-role")
+    role.add_argument("value")
+    invite = commands.add_parser("record-invite")
+    invite.add_argument("choice", choices=("invited", "skipped"))
+    commands.add_parser("complete")
+    args = parser.parse_args()
+    root, actor, service = _context()
+
+    if args.command == "status":
+        snapshot = service.snapshot(actor)
+        result = snapshot.to_dict()
+    elif args.command == "set-name":
+        snapshot = service.set_name(actor, args.value)
+        result = snapshot.to_dict() | {"identity_reconciled": _identity(root, "sync")}
+    elif args.command == "set-role":
+        snapshot = service.set_role(actor, args.value)
+        result = snapshot.to_dict() | {"identity_reconciled": _identity(root, "sync")}
+    elif args.command == "record-invite":
+        snapshot = service.record_invite(actor, skipped=args.choice == "skipped")
+        result = snapshot.to_dict()
+    else:
+        if not _identity(root, "onboard"):
+            raise OSError("canonical person profile could not be reconciled")
+        current = service.snapshot(actor)
+        state = json.loads((root / ".egregore-state.json").read_text(encoding="utf-8"))
+        username = str(state.get("github_username") or "").strip()
+        profile = root / "memory" / "people" / f"{username}.md"
+        if not current.profile_witness or not profile.is_file():
+            raise ValueError("canonical person profile witness is missing")
+        sync = LocalGitSyncTransport((root / "memory").resolve(), push_remote=True).push(
+            message=f"docs(people): onboard {username}", paths=(str(profile),)
+        )
+        snapshot = service.complete(actor, profile_witness=current.profile_witness)
+        result = snapshot.to_dict() | {
+            "sync_warnings": list(sync.warnings),
+            "launcher_alias": _shell_alias(root),
+        }
+    print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (AuthorizationDenied, OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"onboarding: {exc}", file=os.sys.stderr)
+        raise SystemExit(1) from exc

package/runtime/claude/egregore_runtime/policy.py

@@ -0,0 +1,144 @@
+"""Deterministic v1 policy and action-permission implementations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Sequence
+
+from .contracts import (
+    ActionAuthorizer,
+    ActorContext,
+    Permission,
+    PolicyDecision,
+    RetrievalRequest,
+)
+
+
+def _canonical_parts(path: str) -> tuple[str, ...] | None:
+    normalized = path.replace("\\", "/").strip().strip("/")
+    parts = tuple(normalized.split("/")) if normalized else ()
+    if not parts or any(part in {"", ".", ".."} for part in parts):
+        return None
+    return parts
+
+
+def scope_allows_path(path: str, scopes: Sequence[str]) -> bool:
+    """Return whether a normalized canonical path is inside an ACL scope."""
+
+    canonical = _canonical_parts(path)
+    if canonical is None:
+        return False
+    for raw_scope in scopes:
+        scope = _canonical_parts(raw_scope)
+        if scope is not None and canonical[: len(scope)] == scope:
+            return True
+    return False
+
+
+@dataclass(frozen=True, slots=True)
+class ActorGrant:
+    permissions: frozenset[Permission]
+    scopes: tuple[str, ...] = ()
+    resource_ids: tuple[str, ...] = ()
+
+
+@dataclass(slots=True)
+class StaticPolicy(ActionAuthorizer):
+    """Fail-closed policy driven by explicit actor grants.
+
+    This is deliberately small. It proves that dogfood uses a real policy
+    boundary while leaving room for a future ACL-backed policy adapter.
+    """
+
+    org_id: str
+    policy_epoch: str
+    grants: Mapping[str, ActorGrant] = field(default_factory=dict)
+
+    def _base_reasons(self, actor: ActorContext) -> list[str]:
+        reasons: list[str] = []
+        if actor.profile.org_id != self.org_id:
+            reasons.append("actor profile belongs to a different organization")
+        if actor.membership is None:
+            reasons.append("actor has no organization membership")
+        elif actor.membership.org_id != self.org_id:
+            reasons.append("membership belongs to a different organization")
+        elif actor.membership.actor_id != actor.actor.actor_id:
+            reasons.append("membership belongs to a different actor")
+        elif actor.membership.status != "active":
+            reasons.append("membership is not active")
+        if (
+            actor.actor.account_id is not None
+            and (actor.account is None or actor.account.account_id != actor.actor.account_id)
+        ):
+            reasons.append("actor account does not match the resolved account")
+        return reasons
+
+    def authorize_observe(
+        self, actor: ActorContext, request: RetrievalRequest
+    ) -> PolicyDecision:
+        reasons = self._base_reasons(actor)
+        if request.org_id != self.org_id:
+            reasons.append("retrieval request belongs to a different organization")
+        if request.actor_id != actor.actor.actor_id:
+            reasons.append("retrieval request actor does not match the active actor")
+        grant = self.grants.get(actor.actor.actor_id)
+        if grant is None:
+            reasons.append("actor has no policy grant")
+        elif not {Permission.DISCOVER, Permission.READ}.issubset(grant.permissions):
+            reasons.append("actor lacks discover/read permission")
+
+        return PolicyDecision(
+            allowed=not reasons,
+            actor_id=actor.actor.actor_id,
+            org_id=self.org_id,
+            permission=Permission.READ,
+            policy_epoch=self.policy_epoch,
+            resource_ids=grant.resource_ids if grant else (),
+            scopes=grant.scopes if grant else (),
+            reasons=tuple(reasons) if reasons else ("explicit actor grant",),
+        )
+
+    def authorize_action(
+        self,
+        actor: ActorContext,
+        permission: Permission,
+        resource_ids: Sequence[str] = (),
+    ) -> PolicyDecision:
+        reasons = self._base_reasons(actor)
+        grant = self.grants.get(actor.actor.actor_id)
+        if grant is None:
+            reasons.append("actor has no policy grant")
+        elif permission not in grant.permissions:
+            reasons.append(f"actor lacks {permission.value} permission")
+        elif grant.resource_ids and any(
+            resource_id not in grant.resource_ids for resource_id in resource_ids
+        ):
+            reasons.append("requested resource is outside the actor grant")
+
+        return PolicyDecision(
+            allowed=not reasons,
+            actor_id=actor.actor.actor_id,
+            org_id=self.org_id,
+            permission=permission,
+            policy_epoch=self.policy_epoch,
+            resource_ids=tuple(resource_ids),
+            scopes=grant.scopes if grant else (),
+            reasons=tuple(reasons) if reasons else ("explicit actor grant",),
+        )
+
+
+def all_access_dogfood_policy(
+    *, org_id: str, actor_id: str, policy_epoch: str = "all-access-v1"
+) -> StaticPolicy:
+    """Return the explicit dogfood policy; never bypass the policy interface."""
+
+    return StaticPolicy(
+        org_id=org_id,
+        policy_epoch=policy_epoch,
+        grants={
+            actor_id: ActorGrant(
+                permissions=frozenset(Permission),
+                scopes=("memory",),
+            )
+        },
+    )

package/runtime/claude/egregore_runtime/profile.py

@@ -0,0 +1,193 @@
+"""Versioned organizational profile loading for the Egregore runtime.
+
+``egregore.json`` remains a small, committed configuration document.  Rich
+organizational identity belongs in referenced Markdown documents; runtime
+caches, secrets, and telemetry never belong here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Mapping
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from .contracts import EgregoreProfile
+
+
+CONFIG_SCHEMA = "egregore-config/v1"
+PROFILE_SCHEMA = "egregore-profile/v1"
+DEFAULT_CONTEXT_BUDGET = 8_000
+
+
+class ProfileConfigError(ValueError):
+    """Raised when committed organization identity configuration is invalid."""
+
+
+def new_org_id() -> str:
+    """Return an opaque organization id with no provider or transport meaning."""
+
+    return f"org_{uuid4().hex}"
+
+
+def default_profile_config(*, revision: str = "profile/v1") -> dict[str, Any]:
+    """Return conservative profile defaults for a newly initialized org."""
+
+    return {
+        "schema_version": PROFILE_SCHEMA,
+        "revision": revision,
+        "identity_path": "memory/identity/EGREGORE.md",
+        "purpose_path": "memory/identity/EGREGORE.md",
+        "principles_path": "memory/identity/EGREGORE.md",
+        "conventions_path": "memory/identity/EGREGORE.md",
+        "declared_sections": [
+            "essence",
+            "values",
+            "domains",
+            "voice",
+            "decision-grammar",
+        ],
+        "default_policy": "all-access-v1",
+        "default_context_budget": DEFAULT_CONTEXT_BUDGET,
+    }
+
+
+def initialize_org_config(
+    config: Mapping[str, Any],
+    *,
+    org_id: str | None = None,
+) -> dict[str, Any]:
+    """Add runtime identity fields without disturbing existing configuration."""
+
+    result = dict(config)
+    result.setdefault("schema_version", CONFIG_SCHEMA)
+    result.setdefault("org_id", org_id or new_org_id())
+    profile = default_profile_config()
+    profile.update(dict(result.get("profile") or {}))
+    result["profile"] = profile
+    return result
+
+
+def render_identity_document(
+    name: str,
+    *,
+    org_type: str = "team",
+    intent: str = "collaborate and accumulate organizational knowledge",
+    founded: str | None = None,
+) -> str:
+    """Render declared organizational identity without derived graph claims."""
+
+    founded_on = founded or datetime.now(UTC).date().isoformat()
+    return "\n".join(
+        [
+            f"# {name}",
+            "",
+            "## Essence",
+            "",
+            f"{name} is a {org_type} using Egregore to {intent}.",
+            "This declaration is versioned organizational identity; refine it through normal review.",
+            "",
+            "## Values",
+            "",
+            "- Preserve provenance and make consequential reasoning inspectable.",
+            "- Leave canonical organizational state more useful than you found it.",
+            "- Keep human and agent authority explicit.",
+            "",
+            "## Domains",
+            "",
+            "- Add the fields this organization works in and the boundaries it respects.",
+            "",
+            "## Voice",
+            "",
+            "Direct, specific, and honest about uncertainty.",
+            "",
+            "## Decision Grammar",
+            "",
+            "- Record decisions that affect more than one session.",
+            "- Bias toward action for reversible choices.",
+            "- Seek another perspective before irreversible choices.",
+            "",
+            "## Lineage",
+            "",
+            f"Declaration created: {founded_on}",
+            "",
+        ]
+    )
+
+
+def _content_revision(raw: bytes) -> str:
+    return f"config-sha256:{hashlib.sha256(raw).hexdigest()}"
+
+
+def _profile_revision(root: Path, raw: bytes, profile: Mapping[str, Any]) -> str:
+    """Hash committed declarations so context freshness follows identity edits."""
+
+    digest = hashlib.sha256(raw)
+    for field in ("identity_path", "purpose_path", "principles_path", "conventions_path"):
+        value = profile.get(field)
+        if not isinstance(value, str) or not value.strip():
+            continue
+        relative = value.strip().replace("\\", "/")
+        parts = Path(relative).parts
+        if Path(relative).is_absolute() or ".." in parts:
+            raise ProfileConfigError(f"profile.{field} must stay inside the Egregore")
+        declaration = (root / relative).resolve()
+        digest.update(field.encode())
+        digest.update(relative.encode())
+        try:
+            digest.update(declaration.read_bytes())
+        except OSError:
+            digest.update(b"<missing>")
+    return f"profile-sha256:{digest.hexdigest()}"
+
+
+def load_profile(config_path: Path | str) -> EgregoreProfile:
+    """Load new or legacy ``egregore.json`` into the stable profile contract.
+
+    Legacy configs remain readable.  Their fallback org id is explicitly
+    marked as legacy and should be replaced by ``initialize_org_config`` at
+    the next controlled config write.
+    """
+
+    path = Path(config_path)
+    raw = path.read_bytes()
+    try:
+        config = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ProfileConfigError(f"invalid JSON in {path}: {exc}") from exc
+    if not isinstance(config, dict):
+        raise ProfileConfigError(f"{path} must contain a JSON object")
+
+    slug = str(config.get("slug") or "").strip()
+    name = str(config.get("org_name") or config.get("name") or "").strip()
+    if not slug or not name:
+        raise ProfileConfigError(f"{path} must define slug and org_name")
+
+    profile = config.get("profile") or {}
+    if not isinstance(profile, dict):
+        raise ProfileConfigError(f"{path} profile must be an object")
+    schema = str(profile.get("schema_version") or PROFILE_SCHEMA)
+    if schema != PROFILE_SCHEMA:
+        raise ProfileConfigError(f"unsupported profile schema: {schema}")
+
+    configured_org_id = str(config.get("org_id") or "").strip()
+    # Read compatibility only. New setup always writes an opaque org id.
+    resolved_org_id = configured_org_id or f"legacy-org:{slug}"
+    budget = profile.get("default_context_budget", DEFAULT_CONTEXT_BUDGET)
+    if not isinstance(budget, int) or budget <= 0:
+        raise ProfileConfigError("profile.default_context_budget must be positive")
+
+    return EgregoreProfile(
+        schema_version=schema,
+        org_id=resolved_org_id,
+        slug=slug,
+        name=name,
+        revision=_profile_revision(path.parent, raw, profile),
+        purpose_path=profile.get("purpose_path"),
+        principles_path=profile.get("principles_path"),
+        conventions_path=profile.get("conventions_path"),
+        default_policy=str(profile.get("default_policy") or "all-access-v1"),
+        default_context_budget=budget,
+    )

package/runtime/claude/egregore_runtime/quest_cli.py

@@ -0,0 +1,216 @@
+"""Runtime-neutral CLI for canonical collaborative quests."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+from uuid import uuid4
+
+from .contracts import Permission
+from .policy import scope_allows_path
+from .quests import CanonicalQuestService
+from .runtime import local_runtime
+
+
+PRIORITIES = {"none": 0, "low": 1, "medium": 2, "high": 3}
+
+
+def _context():
+    root = Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
+    runtime = local_runtime(root, push_remote=os.environ.get("EGREGORE_NO_PUSH") != "1")
+    actor = runtime.resolve_actor(
+        session_id=os.environ.get("EGREGORE_SESSION_ID", f"session_{uuid4().hex}"),
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    service = CanonicalQuestService(
+        memory_root=(root / "memory").resolve(),
+        write_document=runtime.write_document,
+    )
+    return runtime, actor, service
+
+
+def _require(
+    runtime,
+    actor,
+    permission: Permission,
+    resource: str,
+    *,
+    canonical_path: str | None = None,
+):
+    decision = runtime.authorize(actor, permission, (resource,))
+    if not decision.allowed:
+        raise PermissionError("; ".join(decision.reasons) or f"quest {permission.value} denied")
+    if canonical_path and not scope_allows_path(canonical_path, decision.scopes):
+        raise PermissionError("quest path is outside the actor's authorized scope")
+    return decision
+
+
+def _row(snapshot, *, detail: bool = False):
+    row = {
+        "id": snapshot.document.artifact.artifact_id,
+        "slug": snapshot.slug,
+        "title": snapshot.title,
+        "status": snapshot.status,
+        "projects": list(snapshot.projects),
+        "started": snapshot.started,
+        "started_by": snapshot.started_by,
+        "priority": snapshot.priority,
+        "completed": snapshot.completed,
+        "canonical_path": f"memory/quests/{snapshot.slug}.md",
+    }
+    if detail:
+        row["body"] = snapshot.body
+    return row
+
+
+def _list(args):
+    runtime, actor, service = _context()
+    decision = _require(runtime, actor, Permission.READ, "quests")
+    rows = [
+        _row(snapshot)
+        for snapshot in service.list(
+            actor,
+            include_completed=args.all,
+            authorized_scopes=decision.scopes,
+        )
+    ]
+    print(json.dumps({"quests": rows}, ensure_ascii=False))
+    return 0
+
+
+def _show(args):
+    runtime, actor, service = _context()
+    _require(
+        runtime,
+        actor,
+        Permission.READ,
+        f"quest:{args.slug}",
+        canonical_path=service.canonical_path(args.slug),
+    )
+    print(json.dumps({"quest": _row(service.read(actor, args.slug), detail=True)}, ensure_ascii=False))
+    return 0
+
+
+def _write_result(snapshot, receipt):
+    print(
+        json.dumps(
+            {"quest": _row(snapshot), "writeback": receipt.to_dict()},
+            ensure_ascii=False,
+        )
+    )
+    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+
+
+def _create(args):
+    runtime, actor, service = _context()
+    resource = f"quest:{args.slug or args.title}"
+    _require(
+        runtime,
+        actor,
+        Permission.WRITE,
+        resource,
+        canonical_path=service.canonical_path(args.slug or args.title),
+    )
+    snapshot, receipt = service.create(
+        actor,
+        title=args.title,
+        question=args.question,
+        slug=args.slug,
+        projects=args.project,
+        threads=args.thread,
+    )
+    return _write_result(snapshot, receipt)
+
+
+def _prioritize(args):
+    runtime, actor, service = _context()
+    _require(
+        runtime,
+        actor,
+        Permission.WRITE,
+        f"quest:{args.slug}",
+        canonical_path=service.canonical_path(args.slug),
+    )
+    value = PRIORITIES.get(args.priority, int(args.priority) if args.priority.isdigit() else -1)
+    snapshot, receipt = service.prioritize(actor, slug=args.slug, priority=value)
+    return _write_result(snapshot, receipt)
+
+
+def _transition(args):
+    runtime, actor, service = _context()
+    _require(
+        runtime,
+        actor,
+        Permission.WRITE,
+        f"quest:{args.slug}",
+        canonical_path=service.canonical_path(args.slug),
+    )
+    snapshot, receipt = service.transition(
+        actor,
+        slug=args.slug,
+        status=args.command,
+        outcome=getattr(args, "outcome", None),
+    )
+    return _write_result(snapshot, receipt)
+
+
+def _contribute(args):
+    runtime, actor, service = _context()
+    _require(
+        runtime,
+        actor,
+        Permission.WRITE,
+        f"quest:{args.slug}",
+        canonical_path=service.canonical_path(args.slug),
+    )
+    snapshot, receipt = service.contribute(actor, slug=args.slug, text=args.text)
+    return _write_result(snapshot, receipt)
+
+
+def _parser():
+    parser = argparse.ArgumentParser(prog="egregore-quest")
+    commands = parser.add_subparsers(dest="command", required=True)
+    listing = commands.add_parser("list")
+    listing.add_argument("--all", action="store_true")
+    listing.set_defaults(handler=_list)
+    show = commands.add_parser("show")
+    show.add_argument("slug")
+    show.set_defaults(handler=_show)
+    create = commands.add_parser("new")
+    create.add_argument("--title", required=True)
+    create.add_argument("--question", required=True)
+    create.add_argument("--slug")
+    create.add_argument("--project", action="append", default=[])
+    create.add_argument("--thread", action="append", default=[])
+    create.set_defaults(handler=_create)
+    prioritize = commands.add_parser("prioritize")
+    prioritize.add_argument("slug")
+    prioritize.add_argument("priority")
+    prioritize.set_defaults(handler=_prioritize)
+    contribute = commands.add_parser("contribute")
+    contribute.add_argument("slug")
+    contribute.add_argument("text")
+    contribute.set_defaults(handler=_contribute)
+    pause = commands.add_parser("pause")
+    pause.add_argument("slug")
+    pause.set_defaults(handler=_transition)
+    complete = commands.add_parser("complete")
+    complete.add_argument("slug")
+    complete.add_argument("--outcome", required=True)
+    complete.set_defaults(handler=_transition)
+    return parser
+
+
+def main():
+    args = _parser().parse_args()
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (OSError, PermissionError, ValueError) as exc:
+        print(f"quest: {exc}", file=os.sys.stderr)
+        raise SystemExit(1) from exc