@leji-org/leji 1.0.0

package/schemas/context-changelog.schema.json

@@ -0,0 +1,150 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://leji.org/schemas/v1.0/context-changelog.schema.json",
+  "title": "Leji context changelog",
+  "description": "Append-only machine-readable record of context layer changes.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "entries"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "description": "Optional pointer to this schema, for editor validation and tooling.",
+      "type": "string"
+    },
+    "schemaVersion": {
+      "description": "The Leji spec line this artifact was written against, e.g. \"1.0\".",
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$"
+    },
+    "entries": {
+      "description": "Context layer changes. Canonical order is derived by sorting on (date, id) ascending; array position is not significant. New entries may appear anywhere; the oldest may be compacted with a compaction entry.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "date",
+          "type",
+          "summary",
+          "paths"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "description": "Stable identifier for this change entry, unique within the changelog.",
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "date": {
+            "description": "ISO 8601 in UTC: a calendar date YYYY-MM-DD (ordered as start of day) or a full timestamp ending in Z, e.g. 2026-06-13T15:04:05Z. Offsets and zoneless times are not allowed, so lexical order is chronological.",
+            "type": "string",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z)?$"
+          },
+          "type": {
+            "description": "The kind of change.",
+            "enum": [
+              "added",
+              "changed",
+              "deprecated",
+              "removed",
+              "fixed",
+              "decision",
+              "governance",
+              "compaction"
+            ]
+          },
+          "summary": {
+            "description": "One-line description of what changed.",
+            "type": "string",
+            "minLength": 1
+          },
+          "paths": {
+            "description": "Repository-root-relative paths the change affected.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
+            }
+          },
+          "categories": {
+            "description": "Content categories the change touched.",
+            "type": "array",
+            "items": {
+              "enum": [
+                "domain",
+                "system",
+                "practice",
+                "governance",
+                "decisions"
+              ]
+            }
+          },
+          "decisionRefs": {
+            "description": "Ids of decision records related to this change.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "proposedBy": {
+            "type": "string",
+            "description": "Human or agent that proposed the change."
+          },
+          "approvedBy": {
+            "type": "string",
+            "description": "Human who approved the change."
+          },
+          "breaking": {
+            "description": "Whether the change breaks consumers of the context layer.",
+            "type": "boolean"
+          },
+          "compacted": {
+            "type": "object",
+            "description": "Required on compaction entries: what the compaction removed from the oldest end.",
+            "required": [
+              "entries",
+              "firstId",
+              "lastId"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "entries": {
+                "description": "How many entries this compaction removed from the oldest end.",
+                "type": "integer",
+                "minimum": 1
+              },
+              "firstId": {
+                "description": "Id of the oldest entry removed by this compaction.",
+                "type": "string",
+                "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+              },
+              "lastId": {
+                "description": "Id of the newest entry removed by this compaction.",
+                "type": "string",
+                "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+              }
+            }
+          }
+        },
+        "if": {
+          "properties": {
+            "type": {
+              "const": "compaction"
+            }
+          },
+          "required": [
+            "type"
+          ]
+        },
+        "then": {
+          "required": [
+            "compacted"
+          ]
+        }
+      }
+    }
+  }
+}

package/schemas/context-index.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://leji.org/schemas/v1.0/context-index.schema.json",
+  "title": "Leji context index",
+  "description": "Generated map of the context layer. Never hand-maintained; regenerate on change.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "rootPath",
+    "entries"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "description": "Optional pointer to this schema, for editor validation and tooling.",
+      "type": "string"
+    },
+    "schemaVersion": {
+      "description": "The Leji spec line this artifact was written against, e.g. \"1.0\".",
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$"
+    },
+    "generatedAt": {
+      "description": "ISO 8601 timestamp when the index was generated.",
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}[T ].+$"
+    },
+    "generator": {
+      "description": "The tool that generated this index.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "description": "Name of the generating tool, e.g. \"leji\".",
+          "type": "string"
+        },
+        "version": {
+          "description": "Version of the generating tool.",
+          "type": "string"
+        }
+      }
+    },
+    "rootPath": {
+      "description": "Context root the entries are relative to; mirrors the manifest's rootPath.",
+      "type": "string",
+      "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).*$"
+    },
+    "entries": {
+      "description": "One entry per indexed document in the context layer.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "path",
+          "title",
+          "category"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "description": "Stable identifier; renames and moves update the path, never the id.",
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "path": {
+            "description": "Repository-root-relative path to the document.",
+            "type": "string",
+            "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
+          },
+          "title": {
+            "description": "Human-readable title, from the document's first heading or frontmatter.",
+            "type": "string",
+            "minLength": 1
+          },
+          "category": {
+            "description": "Which content category this document belongs to.",
+            "enum": [
+              "domain",
+              "system",
+              "practice",
+              "governance",
+              "decisions"
+            ]
+          },
+          "summary": {
+            "description": "One-line summary of the document, for routing and navigation.",
+            "type": "string"
+          },
+          "tags": {
+            "description": "Optional free-form tags.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "owners": {
+            "description": "Optional owners of this document.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "lastModified": {
+            "description": "ISO 8601 date the document last changed, from version control where available.",
+            "type": "string",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}([T ].*)?$"
+          },
+          "contentHash": {
+            "description": "Hash of the document's contents, used to detect drift and stable moves.",
+            "type": "string"
+          },
+          "freshness": {
+            "description": "Review horizon for this document.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "reviewAfter": {
+                "description": "ISO 8601 date after which the document should be reviewed for staleness.",
+                "type": "string",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+              }
+            }
+          },
+          "links": {
+            "description": "Optional outbound references from this document.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/context-manifest.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://leji.org/schemas/v1.0/context-manifest.schema.json",
+  "title": "Leji context manifest (leji.json)",
+  "description": "The machine entrypoint of a Leji context layer. Lives at the repository root as leji.json.",
+  "type": "object",
+  "required": [
+    "leji",
+    "name",
+    "rootPath",
+    "bootProfilePath",
+    "categories",
+    "owners"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "description": "Optional pointer to this schema, for editor validation and tooling.",
+      "type": "string"
+    },
+    "leji": {
+      "type": "string",
+      "description": "The Leji spec line this context layer targets, e.g. \"1.0\". The self-naming key follows the OpenAPI convention and identifies the file as a Leji manifest.",
+      "pattern": "^\\d+\\.\\d+$"
+    },
+    "name": {
+      "description": "A short, stable identifier for this context layer, e.g. \"acme-billing-context\".",
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "description": "One-line summary of what this context layer covers.",
+      "type": "string"
+    },
+    "rootPath": {
+      "type": "string",
+      "description": "Context root, POSIX path relative to the repository root. Declares where the context layer lives; it does not re-base other paths: all paths in all Leji artifacts resolve from the repository root.",
+      "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).*$"
+    },
+    "bootProfilePath": {
+      "description": "Path to the boot profile, the agent-agnostic entrypoint every host and person starts from.",
+      "type": "string",
+      "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+\\.md$"
+    },
+    "categories": {
+      "type": "object",
+      "description": "Logical category to path mapping. Keys are the five category identifiers.",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "domain": {
+          "description": "Where domain content lives: business language and product semantics.",
+          "$ref": "#/$defs/categoryMapping"
+        },
+        "system": {
+          "description": "Where system content lives: architecture and the invariants every change respects.",
+          "$ref": "#/$defs/categoryMapping"
+        },
+        "practice": {
+          "description": "Where practice content lives: conventions and proven patterns.",
+          "$ref": "#/$defs/categoryMapping"
+        },
+        "governance": {
+          "description": "Where governance content lives: agent guardrails and operating rules.",
+          "$ref": "#/$defs/categoryMapping"
+        },
+        "decisions": {
+          "description": "Where decision records live: dated records of why things are the way they are.",
+          "$ref": "#/$defs/categoryMapping"
+        }
+      }
+    },
+    "machine": {
+      "description": "Locations of the machine-readable artifacts: index, changelog, profiles, and decision records.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "indexPath": {
+          "description": "Path to the generated context index.",
+          "$ref": "#/$defs/relPath"
+        },
+        "changelogPath": {
+          "description": "Path to the machine-readable context changelog.",
+          "$ref": "#/$defs/relPath"
+        },
+        "agentProfilesPath": {
+          "description": "Directory holding agent profile documents.",
+          "$ref": "#/$defs/relPath"
+        },
+        "decisionRecordsPath": {
+          "description": "Directory holding decision records.",
+          "$ref": "#/$defs/relPath"
+        }
+      }
+    },
+    "agents": {
+      "type": "object",
+      "description": "Role to agent-profile binding. Keys are role identifiers (e.g. \"thought-partner\", \"reviewer\"); values are paths to agent profile documents. Protocols engage roles; this map decides who fills them.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z0-9]+(-[a-z0-9]+)*$": {
+          "$ref": "#/$defs/relPath"
+        }
+      }
+    },
+    "owners": {
+      "type": "object",
+      "description": "Who is accountable for the context layer's health. Owners answer for the context layer staying current and pruned; they do not author or curate it alone (governance.md).",
+      "required": [
+        "primary"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "$ref": "#/$defs/owner",
+          "description": "The person accountable for the context layer's currency. Ownerless context layers rot."
+        },
+        "continuity": {
+          "$ref": "#/$defs/owner",
+          "description": "Optional. A different person who carries the same accountability when the primary is unavailable or steps away; assisted adoptions should name one before outside help leaves. Naming the primary again provides no continuity, and an agent cannot fill it: owners are accountable people."
+        }
+      }
+    },
+    "conformance": {
+      "description": "The conformance level this context layer claims, checkable by tooling.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "claimedLevel": {
+          "description": "The conformance level claimed: core, indexed, governed, or federated.",
+          "enum": [
+            "core",
+            "indexed",
+            "governed",
+            "federated"
+          ]
+        },
+        "claimedAt": {
+          "description": "ISO 8601 date the claim was last asserted.",
+          "$ref": "#/$defs/isoDate"
+        }
+      }
+    },
+    "federation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mounts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "path",
+              "name",
+              "owner"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "path": {
+                "$ref": "#/$defs/relPath",
+                "description": "Where the sibling layer is mounted in this repository, e.g. \"context/product/\". The sibling's own leji.json lives at this path's root."
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The sibling layer's name; must match the `name` in the sibling's own manifest."
+              },
+              "owner": {
+                "$ref": "#/$defs/owner",
+                "description": "The owner of the sibling layer. Ownership stays with the sibling's team; the host never absorbs its content."
+              },
+              "role": {
+                "type": "string",
+                "description": "What this sibling layer carries, e.g. \"product-side context\"."
+              },
+              "source": {
+                "type": "string",
+                "description": "Upstream repository URL of the sibling layer. Optional; enables stale-pin reporting when git submodule metadata alone isn't available."
+              }
+            }
+          },
+          "description": "Each mount is a docs-only sibling layer at a pinned version, keeping its own repository, ownership, and review gate."
+        }
+      },
+      "description": "Sibling layers mounted into this repository (spec: distribution.md pattern 3). The circle composes ownership; it doesn't centralize it."
+    },
+    "vendorAdapters": {
+      "type": "array",
+      "description": "Vendor entrypoint files present in this repository; each must redirect to the boot profile.",
+      "items": {
+        "$ref": "#/$defs/relPath"
+      }
+    },
+    "docs": {
+      "type": "object",
+      "description": "Presentation preferences read by `leji docs`. Non-normative convenience configuration; presentation itself is out of normative scope.",
+      "additionalProperties": false,
+      "properties": {
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "description": "Preferred local-preview port for `leji docs --serve`. The --port flag overrides; the default is 5354 (LEJI on a phone keypad)."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "relPath": {
+      "type": "string",
+      "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
+    },
+    "isoDate": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}([T ].*)?$"
+    },
+    "owner": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "description": "The person's name.",
+          "type": "string",
+          "minLength": 1
+        },
+        "contact": {
+          "description": "How to reach them, e.g. an email address.",
+          "type": "string"
+        }
+      }
+    },
+    "categoryMapping": {
+      "type": "object",
+      "required": [
+        "paths"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "paths": {
+          "description": "One or more repository-root-relative paths where this category's content lives.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/relPath"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/decision-record.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://leji.org/schemas/v1.0/decision-record.schema.json",
+  "title": "Leji decision record frontmatter",
+  "description": "Validates the YAML frontmatter of a decision record. The markdown body carries context, decision, and consequences in prose.",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "status",
+    "date"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "description": "Stable identifier for this decision, e.g. \"adopt-leji\".",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "title": {
+      "description": "Short title of the decision.",
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "description": "Lifecycle status of the decision.",
+      "enum": [
+        "proposed",
+        "accepted",
+        "superseded",
+        "deprecated",
+        "rejected"
+      ]
+    },
+    "date": {
+      "description": "ISO 8601 date the decision was made or last changed status.",
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "deciders": {
+      "description": "People who made the decision.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "supersedes": {
+      "type": "string",
+      "description": "id of the record this decision replaces."
+    },
+    "supersededBy": {
+      "type": "string",
+      "description": "id of the record that replaced this one."
+    },
+    "affectedPaths": {
+      "description": "Repository-root-relative paths the decision affects.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
+      }
+    },
+    "affectedCategories": {
+      "description": "Content categories the decision affects.",
+      "type": "array",
+      "items": {
+        "enum": [
+          "domain",
+          "system",
+          "practice",
+          "governance",
+          "decisions"
+        ]
+      }
+    },
+    "links": {
+      "description": "Optional outbound references, e.g. to related decisions or issues.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/templates/README.md

@@ -0,0 +1,5 @@
+# Templates
+
+Copyable starters: manifest (leji.json), boot profile (boot-profile.md), core agent profile, role profile, decision record. Copy, fill in the placeholders, delete what you don't need. See adoption/README.md for the order.
+
+Naming: Leji-owned files use lowercase-kebab (`docs/boot-profile.md`, `agents/core.md`); ecosystem-fixed entrypoints (`README.md`, `CLAUDE.md`, `AGENTS.md`) keep their required names.

package/templates/agent-profile.md

@@ -0,0 +1,25 @@
+---
+id: <role-id>
+name: <Role name>
+role: <role>
+purpose: <one line>
+# host + invocation only for agents engaged as external CLIs; omit for the resident agent
+host: <agent host, e.g. codex>
+invocation:
+  command: <command template with <prompt> placeholder>
+  constraints:
+    - <operational constraint worth machine-knowing>
+inherits: core
+requiredRead:
+  - docs/boot-profile.md
+  - <paths this role loads before any task>
+defaultContext:
+  - system
+  - practice
+mustAskWhen:
+  - <condition>
+---
+
+# <Role name>
+
+<What this role does in this repository, and how its posture differs from core. Narrower than core, never looser.>

package/templates/agents/core.md

@@ -0,0 +1,27 @@
+---
+id: core
+name: Agent Core
+role: core
+purpose: Shared operating posture every role profile inherits.
+requiredRead:
+  - docs/boot-profile.md
+  - docs/governance/
+mustAskWhen:
+  - the change is destructive or hard to reverse
+  - the task touches data covered by a data-handling rule
+  - the right answer depends on a decision not yet recorded
+---
+
+# Agent Core
+
+The shared posture for all agents working in this repository. Role profiles inherit this file and narrow it; they never loosen it.
+
+## Defaults
+
+- Read the boot profile and the relevant category before acting, not after.
+- Derive actions from declared intent plus task context; don't re-encode intent into one-off instructions.
+- When context is missing or wrong, propose the fix in the same change set as the work that surfaced it.
+
+## Escalation
+
+<Who to ask, in what channel, for what kind of question.>