@iflow-mcp/jkheadley-instar 0.26.2

package/playbook-scripts/playbook_paths.py

@@ -0,0 +1,232 @@
+"""
+Playbook Path Abstraction Layer (Phase 4.1)
+
+Centralizes all path resolution for the Playbook context engineering system.
+Replaces hardcoded .claude/ paths across 30 scripts with a single source of truth.
+
+Two modes:
+  1. Legacy (Dawn): Scripts in .claude/scripts/, data in .claude/
+  2. Instar: Config-driven paths, data in .instar/playbook/
+
+Resolution order:
+  - PLAYBOOK_CONFIG env var -> read config file -> config-driven paths
+  - PLAYBOOK_PROJECT_DIR env var -> legacy playbook root
+  - Script location -> auto-detect (scripts dir parent = playbook root)
+
+Path security: All resolved paths validated via os.path.realpath() to prevent
+directory traversal. Any path escaping the project root is rejected.
+"""
+
+import json
+import os
+import sys
+
+_singleton = None
+
+
+class PlaybookPaths:
+    """Resolves all Playbook file paths based on configuration or legacy layout."""
+
+    def __init__(self, project_dir=None, config_path=None):
+        self._config = None
+        self._script_dir = os.path.dirname(os.path.abspath(__file__))
+
+        # Try to load config first (Instar mode)
+        config_path = config_path or os.environ.get("PLAYBOOK_CONFIG")
+        if config_path and os.path.exists(config_path):
+            self._config = self._load_json(config_path)
+
+        # Resolve project root and playbook root
+        if self._config:
+            # Config-driven mode (Instar)
+            self.project_root = os.path.realpath(
+                project_dir
+                or os.environ.get("PLAYBOOK_PROJECT_DIR")
+                or os.getcwd()
+            )
+            playbook_rel = self._config.get("paths", {}).get("root", ".instar/playbook")
+            self.playbook_root = os.path.realpath(
+                os.path.join(self.project_root, playbook_rel)
+            )
+        else:
+            # Legacy mode: PLAYBOOK_PROJECT_DIR points to playbook root (e.g., .claude/)
+            # or auto-detect from script location
+            legacy_root = (
+                project_dir
+                or os.environ.get("PLAYBOOK_PROJECT_DIR")
+                or os.path.join(self._script_dir, "..")
+            )
+            self.playbook_root = os.path.realpath(legacy_root)
+            self.project_root = os.path.realpath(
+                os.path.join(self.playbook_root, "..")
+            )
+
+        # Where scripts live (bundled or ejected)
+        self.scripts_dir = os.path.realpath(
+            os.environ.get("PLAYBOOK_SCRIPTS_DIR", self._script_dir)
+        )
+
+    # --- Core data files ---
+
+    @property
+    def manifest(self):
+        """Path to context-manifest.json."""
+        name = self._config_path("manifest", "context-manifest.json")
+        return self._resolve(name)
+
+    @property
+    def governance(self):
+        """Path to context-governance.json."""
+        name = self._config_path("governance", "context-governance.json")
+        return self._resolve(name)
+
+    @property
+    def history(self):
+        """Path to context-history.jsonl."""
+        name = self._config_path("history", "context-history.jsonl")
+        return self._resolve(name)
+
+    @property
+    def assembly_log(self):
+        """Path to context-assembly-log.jsonl."""
+        return self._resolve("context-assembly-log.jsonl")
+
+    @property
+    def rejected_log(self):
+        """Path to context-rejected-deltas.jsonl."""
+        return self._resolve("context-rejected-deltas.jsonl")
+
+    @property
+    def feedback_file(self):
+        """Path to sub-agent-feedback.jsonl."""
+        return self._resolve("sub-agent-feedback.jsonl")
+
+    # --- Directories ---
+
+    @property
+    def pending_review_dir(self):
+        """Path to context-pending-review/ directory."""
+        return self._resolve("context-pending-review")
+
+    @property
+    def scratchpad_dir(self):
+        """Path to sessions/ directory for per-session scratchpads."""
+        name = self._config_path("scratchpad_dir", "sessions")
+        return self._resolve(name)
+
+    @property
+    def archive_dir(self):
+        """Path to archive/ directory for history rotations."""
+        name = self._config_path("archive_dir", "archive")
+        return self._resolve(name)
+
+    @property
+    def schema_dir(self):
+        """Path to schemas/ directory."""
+        name = self._config_path("schema_dir", "schemas")
+        return self._resolve(name)
+
+    # --- Schema files ---
+
+    @property
+    def manifest_schema(self):
+        """Path to context-manifest.schema.json."""
+        return os.path.join(self.schema_dir, "context-manifest.schema.json")
+
+    @property
+    def delta_schema(self):
+        """Path to context-delta.schema.json."""
+        return os.path.join(self.schema_dir, "context-delta.schema.json")
+
+    @property
+    def config_schema(self):
+        """Path to playbook-config.schema.json."""
+        return os.path.join(self.schema_dir, "playbook-config.schema.json")
+
+    # --- Repo-relative path resolution ---
+
+    def resolve_item_path(self, relative_path):
+        """Resolve a manifest item's file path relative to project root.
+
+        Raises ValueError if resolved path escapes project root (traversal attack).
+        """
+        if not relative_path:
+            return ""
+        if os.path.isabs(relative_path):
+            resolved = os.path.realpath(relative_path)
+        else:
+            resolved = os.path.realpath(
+                os.path.join(self.project_root, relative_path)
+            )
+        self._validate_containment(resolved, self.project_root)
+        return resolved
+
+    def script_path(self, script_name):
+        """Resolve path to a playbook script by name."""
+        return os.path.join(self.scripts_dir, script_name)
+
+    # --- Config access ---
+
+    @property
+    def config(self):
+        """The loaded playbook-config.json dict, or None in legacy mode."""
+        return self._config
+
+    @property
+    def is_instar_mode(self):
+        """True if running with a playbook-config.json (Instar mode)."""
+        return self._config is not None
+
+    # --- Internal helpers ---
+
+    def _config_path(self, key, default):
+        """Get a path name from config, or use default."""
+        if self._config:
+            return self._config.get("paths", {}).get(key, default)
+        return default
+
+    def _resolve(self, relative):
+        """Resolve a path relative to playbook root."""
+        return os.path.join(self.playbook_root, relative)
+
+    @staticmethod
+    def _validate_containment(path, container):
+        """Ensure path is within container directory."""
+        real_path = os.path.realpath(path)
+        real_container = os.path.realpath(container)
+        if not real_path.startswith(real_container + os.sep) and real_path != real_container:
+            raise ValueError(
+                f"Path traversal blocked: {path} resolves to {real_path} "
+                f"which is outside {real_container}"
+            )
+
+    @staticmethod
+    def _load_json(path):
+        """Load a JSON file, returning None on error."""
+        try:
+            with open(path, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def __repr__(self):
+        mode = "instar" if self.is_instar_mode else "legacy"
+        return (
+            f"PlaybookPaths(mode={mode}, "
+            f"project_root={self.project_root!r}, "
+            f"playbook_root={self.playbook_root!r})"
+        )
+
+
+def get_paths(project_dir=None, config_path=None):
+    """Get or create the singleton PlaybookPaths instance."""
+    global _singleton
+    if project_dir or config_path or _singleton is None:
+        _singleton = PlaybookPaths(project_dir=project_dir, config_path=config_path)
+    return _singleton
+
+
+def reset():
+    """Reset the singleton (for testing)."""
+    global _singleton
+    _singleton = None

package/playbook-scripts/schemas/context-delta.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://instar.dev/schemas/context-delta.schema.json",
+  "title": "Context Delta",
+  "description": "Schema for Playbook context deltas — proposed changes to the manifest, validated by the deterministic delta validator.",
+  "type": "object",
+  "required": ["delta_id", "timestamp", "source_session", "operation", "reflector_confidence"],
+  "properties": {
+    "delta_id": {
+      "type": "string",
+      "pattern": "^delta-[a-f0-9]{12}$",
+      "description": "Unique delta identifier (hex-encoded, 12 chars)."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when this delta was proposed."
+    },
+    "source_session": {
+      "type": "string",
+      "description": "Session ID that proposed this delta. Pattern is governance-configurable via source_session_pattern."
+    },
+    "operation": {
+      "type": "string",
+      "enum": ["create", "update_counter", "update_content", "retire", "merge", "promote", "resolve_quarantine"],
+      "description": "The type of manifest change being proposed."
+    },
+    "target_item_id": {
+      "type": "string",
+      "pattern": "^/context/[a-z]+/[a-z0-9/-]+$",
+      "description": "ID of the manifest item being modified (required for all operations except create)."
+    },
+    "reflector_confidence": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "description": "Reflector's confidence in this delta (0.0-1.0). Below governance threshold routes to pending_review."
+    },
+    "payload": {
+      "$ref": "#/$defs/DeltaPayload",
+      "description": "The actual change data — varies by operation type."
+    },
+    "evidence": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Evidence" },
+      "description": "Evidence supporting this delta. Required for create operations."
+    },
+    "rationale": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Brief explanation of why this delta is proposed."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "DeltaPayload": {
+      "type": "object",
+      "properties": {
+        "category": {
+          "type": "string",
+          "enum": ["identity", "safety", "infrastructure", "strategy", "lesson", "domain"],
+          "description": "Item category (required for create operations)."
+        },
+        "memory_type": {
+          "type": "string",
+          "enum": ["fact", "experiential", "episodic", "procedural", "historical"],
+          "description": "Memory type (required for create operations)."
+        },
+        "content_inline": {
+          "type": "string",
+          "maxLength": 2000,
+          "description": "Inline content (max ~500 tokens)."
+        },
+        "path": {
+          "type": "string",
+          "description": "File path relative to repo root."
+        },
+        "tags": {
+          "type": "object",
+          "properties": {
+            "domains": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 2
+            },
+            "qualifiers": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 3
+            }
+          },
+          "additionalProperties": false
+        },
+        "field": {
+          "type": "string",
+          "enum": ["helpful", "misleading"],
+          "description": "Counter field to update (for update_counter operations)."
+        },
+        "increment": {
+          "type": "number",
+          "enum": [1, -1, 0.5, -0.5],
+          "description": "Counter increment value (for update_counter operations)."
+        },
+        "access_scope": {
+          "type": "string",
+          "enum": ["global", "session", "user"],
+          "description": "Multi-tenant visibility scope."
+        },
+        "inheritance_eligible": {
+          "type": "boolean",
+          "description": "Whether sub-agents can inherit this item."
+        },
+        "retirement_policy": {
+          "type": "string",
+          "enum": ["auto", "manual_only"],
+          "description": "Whether this item can be auto-retired."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Evidence": {
+      "type": "object",
+      "required": ["type", "value"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["exit_code", "http_status", "test_result", "human_verification"],
+          "description": "Type of evidence supporting this delta."
+        },
+        "value": {
+          "description": "The evidence value (type varies by evidence type)."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/playbook-scripts/schemas/context-manifest.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://instar.dev/schemas/context-manifest.schema.json",
+  "title": "Context Manifest",
+  "description": "Schema for the Playbook context manifest — the single source of truth for an agent's accumulated knowledge items.",
+  "type": "object",
+  "required": ["version", "items"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Manifest format version."
+    },
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the manifest schema."
+    },
+    "last_lifecycle_run": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the last lifecycle job run."
+    },
+    "migration_stage": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Current migration stage (0=fresh, 1=seeded, 2=lessons migrated, etc.)."
+    },
+    "hmac_signature": {
+      "type": "string",
+      "description": "HMAC-SHA256 signature of the canonical JSON for integrity verification."
+    },
+    "items": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ManifestItem" },
+      "description": "All context items (active, retired, or pending_review)."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ManifestItem": {
+      "type": "object",
+      "required": ["id", "category", "memory_type", "status"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^/context/",
+          "description": "Unique hierarchical item ID (e.g., /context/infrastructure/session)."
+        },
+        "category": {
+          "$ref": "#/$defs/Category",
+          "description": "Item category determining governance policy."
+        },
+        "memory_type": {
+          "$ref": "#/$defs/MemoryType",
+          "description": "Memory type determining decay rate."
+        },
+        "path": {
+          "type": "string",
+          "description": "File path relative to repo root. Empty string for inline-only items."
+        },
+        "content_inline": {
+          "type": "string",
+          "maxLength": 2000,
+          "description": "Inline content (max ~500 tokens). Used for items without file paths."
+        },
+        "tags": {
+          "$ref": "#/$defs/Tags",
+          "description": "Domain and qualifier tags for trigger matching and assembly."
+        },
+        "freshness": {
+          "type": "string",
+          "description": "ISO 8601 timestamp of last meaningful update."
+        },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^(sha256:[a-f0-9]{16})?$",
+          "description": "Truncated SHA-256 hash of file content for drift detection."
+        },
+        "tokens_est": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Estimated token count (chars / 4 + 1)."
+        },
+        "usefulness": {
+          "$ref": "#/$defs/Usefulness",
+          "description": "Outcome-linked usefulness counters."
+        },
+        "load_triggers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Triggers that cause this item to be loaded during assembly."
+        },
+        "dependencies": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "IDs of items that should be co-loaded with this item."
+        },
+        "provenance": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Provenance" },
+          "description": "Provenance chain tracking who created/modified this item."
+        },
+        "retirement_policy": {
+          "type": "string",
+          "enum": ["auto", "manual_only"],
+          "description": "Whether this item can be automatically retired."
+        },
+        "access_scope": {
+          "type": "string",
+          "enum": ["global", "session", "user"],
+          "description": "Multi-tenant visibility scope. 'global' = all users/agents, 'session' = current session only, 'user' = specific user namespace."
+        },
+        "inheritance_eligible": {
+          "type": "boolean",
+          "description": "Whether sub-agents can inherit this item."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "retired", "pending_review"],
+          "description": "Current item status."
+        },
+        "retired_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp when the item was retired (only present for retired items)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Category": {
+      "type": "string",
+      "enum": ["identity", "safety", "infrastructure", "strategy", "lesson", "domain"]
+    },
+    "MemoryType": {
+      "type": "string",
+      "enum": ["fact", "experiential", "episodic", "procedural", "historical"]
+    },
+    "Tags": {
+      "type": "object",
+      "required": ["domains", "qualifiers"],
+      "properties": {
+        "domains": {
+          "type": "array",
+          "items": { "type": "string" },
+          "maxItems": 2,
+          "description": "Domain tags (max 2 per governance)."
+        },
+        "qualifiers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "maxItems": 3,
+          "description": "Qualifier tags (max 3 per governance)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Usefulness": {
+      "type": "object",
+      "required": ["helpful", "misleading"],
+      "properties": {
+        "helpful": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of times this item contributed to a successful outcome."
+        },
+        "misleading": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of times this item contributed to a negative outcome."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Provenance": {
+      "type": "object",
+      "required": ["source_session", "created_at", "provenance_type"],
+      "properties": {
+        "source_session": {
+          "type": "string",
+          "description": "Session ID that created or modified this provenance entry."
+        },
+        "created_at": {
+          "type": "string",
+          "description": "Date when this provenance entry was created."
+        },
+        "provenance_type": {
+          "type": "string",
+          "enum": ["human-verified", "system-computed", "llm-evaluated", "imported"],
+          "description": "How this provenance was established."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional note about this provenance entry."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}