@onedotmint/charterleaf 0.1.0

package/AGENTS_SNIPPET.md

@@ -0,0 +1,21 @@
+# Charterleaf instructions
+
+Project specifications live under `specs/`. For non-trivial architectural, behavioral, or cross-cutting changes, find the smallest relevant set; never read the whole tree by default.
+
+- `specs/capabilities/` — durable behavior, contracts, invariants, non-goals.
+- `specs/engineering/` — durable implementation constraints and concrete recurring pitfalls.
+- `specs/decisions/` — important architectural choices and revisit conditions.
+- `specs/changes/` — lightweight active deltas.
+- `specs/constitution.md` — project-wide guardrails only.
+
+When a concrete code path is known, use `charterleaf related <path>` to locate matching living specs plus active changes that affect them. Otherwise use normal code/text search. Use `charterleaf lint` for structural validation and mechanical active-change conflicts. These commands are helpers, not workflow gates.
+
+Authority is `Constitution > Active Change > Living Spec > Current Code`. Do not add authority scores or silently rewrite specs to match code.
+
+Keep specs compressed and evidence-based. Prefer durable contracts and pitfalls over commentary. Do not invent aspirational standards that are not demonstrated by the repo or explicitly accepted.
+
+Do not create specs for temporary implementation details, current tasks, debugging notes, routine refactors, or trivial fixes with no durable implication. For a durable bug fix, use `Current` / `Expected` when useful and explicitly state what must `PRESERVE`.
+
+For meaningful durable behavior/contract changes, use one change file with only the needed `ADD`, `MODIFY`, `REMOVE`, and/or `PRESERVE` sections. After acceptance and implementation, merge durable results into living specs and delete the change file. Git is the history.
+
+Charterleaf is a knowledge layer, not a workflow layer. It must not manage tasks, planning, agents, execution, review, memory, compression, semantic search, code/spec verification, release lifecycle, or Git history.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charterleaf contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# Charterleaf
+
+A tiny specification layer for coding agents.
+
+Durable project intent, deterministic routing, and structural linting —
+without workflow orchestration.
+
+> **Keep project intent in the repo, without turning specs into a workflow.**
+
+Charterleaf keeps durable project knowledge in Markdown and provides exactly two deterministic helpers:
+
+```bash
+charterleaf related <path>
+charterleaf lint
+```
+
+It is a knowledge layer, not a workflow framework.
+
+## Install
+
+Install the public scoped npm package:
+
+```bash
+npm install -g @onedotmint/charterleaf
+```
+
+Pi can install the same package and discover its bundled Agent Skill:
+
+```bash
+pi install npm:@onedotmint/charterleaf
+```
+
+No Pi extension or Pi runtime dependency is used.
+
+## CLI
+
+Run from a repository root containing `specs/`:
+
+```bash
+charterleaf related src/auth/session.ts
+charterleaf lint
+```
+
+`related <path>` performs deterministic path routing. It matches `applies_to` with `*` and `**`, normalizes repo-relative paths to POSIX form, then appends active changes whose `affects` reference a matched Spec ID. Output is stable; no match is success. It is not semantic search.
+
+`lint` performs mechanical checks only: frontmatter shape, living Spec IDs, duplicate requirement IDs, change references, static `ADD` / `MODIFY` / `REMOVE` references, and conflicting active changes that touch the same requirement ID. It does not judge wording, architecture quality, or semantic code/spec drift.
+
+The frontmatter convention intentionally supports only top-level scalar values and simple string lists. Runtime dependencies remain zero.
+
+## Project knowledge
+
+```text
+specs/
+├── constitution.md
+├── capabilities/
+├── engineering/
+├── decisions/
+└── changes/
+```
+
+- `constitution.md` — rare project-wide guardrails.
+- `capabilities/` — durable behavior, contracts, invariants, non-goals.
+- `engineering/` — durable implementation constraints and, when useful, concrete pitfalls.
+- `decisions/` — why an important architectural choice exists.
+- `changes/` — a lightweight active delta for an intentional durable change.
+
+Authority is structural, not scored metadata:
+
+```text
+Constitution > Active Change > Living Spec > Current Code
+```
+
+Keep specs compressed and evidence-based. Prefer contracts over commentary and record durable pitfalls that code alone does not reveal. Do not invent aspirational standards merely to make a spec look complete.
+
+For bug fixes with durable behavioral implications, clarify `Current`, `Expected`, and `PRESERVE` when that reduces accidental scope. Do not create a spec for trivial fixes with no durable implication.
+
+Load the smallest relevant set; do not read the whole tree by default. After an accepted change is implemented, merge the durable result into living specs and delete the change file. Git is the history.
+
+## Other agents
+
+Charterleaf core does not depend on Pi. Any coding agent capable of reading Markdown and executing shell commands can use it.
+
+Use `AGENTS_SNIPPET.md` with agents that support project instructions. Agent Skills-compatible harnesses can use the bundled `skills/charterleaf/SKILL.md`.
+
+## Boundaries
+
+Charterleaf has no:
+
+- planning
+- task management
+- agent orchestration
+- implementation or review workflow
+- session memory or context compression
+- semantic search or embeddings
+- code/spec semantic verification
+- database, index, or cache
+- daemon or background watcher
+- plugin/extension runtime
+- Git/history abstraction
+
+The two CLI commands are helpers, not workflow gates.
+
+## Development
+
+Requires Node.js 20 or newer. There are no runtime or development dependencies and no build step.
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+## License
+
+MIT

package/bin/charterleaf.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../lib/charterleaf.js');
+
+process.exitCode = main();

package/lib/charterleaf.js

@@ -0,0 +1,495 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REQUIREMENT_ID_SOURCE = String.raw`\b[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d{3,}\b`;
+const REQUIREMENT_HEADING = /^#{2,6}\s+([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d{3,})\b/;
+const SECTION_HEADING = /^##\s+(ADD|MODIFY|REMOVE|PRESERVE)\s*$/i;
+
+class FrontmatterError extends Error {}
+
+function normalizeRepoPath(value) {
+  let result = String(value).trim().replaceAll('\\', '/');
+  while (result.startsWith('./')) result = result.slice(2);
+  result = result.replace(/\/+/g, '/');
+  while (result.length > 1 && result.endsWith('/')) result = result.slice(0, -1);
+  return result || '.';
+}
+
+function unquote(value) {
+  if (
+    value.length >= 2 &&
+    value[0] === value[value.length - 1] &&
+    (value[0] === '"' || value[0] === "'")
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function inlineList(value) {
+  const trimmed = value.trim();
+  if (!(trimmed.startsWith('[') && trimmed.endsWith(']'))) return null;
+  const inner = trimmed.slice(1, -1).trim();
+  if (!inner) return [];
+  return inner.split(',').map((part) => {
+    const item = unquote(part.trim());
+    if (!item) throw new FrontmatterError('empty inline list item');
+    return item;
+  });
+}
+
+function parseFrontmatter(text) {
+  const lines = String(text).split(/\r?\n/);
+  if (!lines.length || lines[0].trim() !== '---') {
+    return { frontmatter: null, body: String(text) };
+  }
+
+  let end = -1;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index].trim() === '---') {
+      end = index;
+      break;
+    }
+  }
+  if (end === -1) throw new FrontmatterError('unclosed frontmatter');
+
+  const data = {};
+  let currentList = null;
+  for (let index = 1; index < end; index += 1) {
+    const raw = lines[index];
+    const number = index + 1;
+    if (!raw.trim() || raw.trimStart().startsWith('#')) continue;
+
+    const stripped = raw.trimStart();
+    const indent = raw.length - stripped.length;
+    if (indent) {
+      if (currentList === null || !stripped.startsWith('- ')) {
+        throw new FrontmatterError(`line ${number}: unsupported indentation`);
+      }
+      const item = unquote(stripped.slice(2).trim());
+      if (!item) throw new FrontmatterError(`line ${number}: empty list item`);
+      data[currentList].push(item);
+      continue;
+    }
+
+    currentList = null;
+    const colon = raw.indexOf(':');
+    if (colon === -1) throw new FrontmatterError(`line ${number}: expected 'key: value'`);
+    const key = raw.slice(0, colon).trim();
+    const value = raw.slice(colon + 1).trim();
+    if (!key || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) {
+      throw new FrontmatterError(`line ${number}: invalid key`);
+    }
+    if (Object.hasOwn(data, key)) {
+      throw new FrontmatterError(`line ${number}: duplicate key ${key}`);
+    }
+
+    if (!value) {
+      data[key] = [];
+      currentList = key;
+      continue;
+    }
+
+    const parsedList = inlineList(value);
+    data[key] = parsedList === null ? unquote(value) : parsedList;
+  }
+
+  return { frontmatter: data, body: lines.slice(end + 1).join('\n') };
+}
+
+function escapeRegexChar(char) {
+  return /[\\^$.*+?()[\]{}|]/.test(char) ? `\\${char}` : char;
+}
+
+function globMatches(pattern, targetPath) {
+  const normalizedPattern = normalizeRepoPath(pattern);
+  const normalizedPath = normalizeRepoPath(targetPath);
+  const parts = normalizedPattern.split('/');
+  let source = '^';
+
+  parts.forEach((part, index) => {
+    if (part === '**') {
+      source += index === parts.length - 1 ? '.*' : '(?:[^/]+/)*';
+      return;
+    }
+
+    for (const char of part) {
+      source += char === '*' ? '[^/]*' : escapeRegexChar(char);
+    }
+    if (index !== parts.length - 1) source += '/';
+  });
+
+  source += '$';
+  return new RegExp(source).test(normalizedPath);
+}
+
+function walkMarkdown(root) {
+  const files = [];
+  function walk(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith('.md')) files.push(full);
+    }
+  }
+  walk(root);
+  return files.sort((a, b) => {
+    const left = a.replaceAll('\\', '/');
+    const right = b.replaceAll('\\', '/');
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+
+function relativeDisplay(filePath, cwd) {
+  const relative = path.relative(cwd, filePath);
+  if (!relative.startsWith('..') && !path.isAbsolute(relative)) return relative.replaceAll('\\', '/');
+  return filePath.replaceAll('\\', '/');
+}
+
+function write(stream, line) {
+  stream.write(`${line}\n`);
+}
+
+function related(repoPath, cwd = process.cwd(), streams = {}) {
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const specRoot = path.join(cwd, 'specs');
+  if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
+    write(stderr, 'ERROR specs/: not found');
+    return 2;
+  }
+
+  const target = normalizeRepoPath(repoPath);
+  const documents = [];
+  const matches = [];
+  const matchedIds = new Set();
+  const errors = [];
+
+  for (const filePath of walkMarkdown(specRoot)) {
+    const display = relativeDisplay(filePath, cwd);
+    let parsed;
+    try {
+      parsed = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
+    } catch (error) {
+      errors.push(`ERROR ${display}: ${error.message}`);
+      continue;
+    }
+    documents.push({ filePath, display, frontmatter: parsed.frontmatter || {} });
+  }
+
+  for (const document of documents) {
+    const { display, frontmatter } = document;
+    if (!Object.hasOwn(frontmatter, 'applies_to')) continue;
+    const patterns = frontmatter.applies_to;
+    if (!Array.isArray(patterns) || !patterns.every((item) => typeof item === 'string')) {
+      errors.push(`ERROR ${display}: applies_to must be a list of paths`);
+      continue;
+    }
+    if (!patterns.some((pattern) => globMatches(pattern, target))) continue;
+
+    matches.push(display);
+    if (typeof frontmatter.id === 'string' && frontmatter.id.trim()) {
+      matchedIds.add(frontmatter.id.trim());
+    }
+  }
+
+  if (errors.length) {
+    for (const error of errors) write(stderr, error);
+    return 2;
+  }
+
+  const activeChanges = [];
+  if (matchedIds.size) {
+    const changeRoot = path.join(specRoot, 'changes');
+    for (const document of documents) {
+      if (path.dirname(document.filePath) !== changeRoot) continue;
+      const affects = document.frontmatter.affects;
+      if (!Array.isArray(affects)) continue;
+      if (affects.some((specId) => typeof specId === 'string' && matchedIds.has(specId.trim()))) {
+        activeChanges.push(document.display);
+      }
+    }
+  }
+
+  matches.sort();
+  activeChanges.sort();
+  const output = [...matches];
+  for (const change of activeChanges) {
+    if (!output.includes(change)) output.push(change);
+  }
+
+  for (const match of output) write(stdout, match);
+  if (!output.length) write(stdout, 'No related specs.');
+  return 0;
+}
+
+function isLivingSpec(filePath, specRoot) {
+  const relative = path.relative(specRoot, filePath).replaceAll('\\', '/').split('/');
+  return relative.length >= 2 && (relative[0] === 'capabilities' || relative[0] === 'engineering');
+}
+
+function requirementDefinitions(text) {
+  const found = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.trim().match(REQUIREMENT_HEADING);
+    if (match) found.push(match[1]);
+  }
+  return found;
+}
+
+function changeSections(body) {
+  const sections = new Map();
+  let current = null;
+  for (const line of body.split(/\r?\n/)) {
+    const heading = line.trim().match(SECTION_HEADING);
+    if (heading) {
+      current = heading[1].toUpperCase();
+      if (!sections.has(current)) sections.set(current, []);
+      continue;
+    }
+    if (line.startsWith('## ')) {
+      current = null;
+      continue;
+    }
+    if (current !== null) sections.get(current).push(line);
+  }
+  return Object.fromEntries([...sections].map(([name, lines]) => [name, lines.join('\n')]));
+}
+
+function allRequirementIds(text) {
+  return [...String(text).matchAll(new RegExp(REQUIREMENT_ID_SOURCE, 'g'))].map((match) => match[0]);
+}
+
+function lint(cwd = process.cwd(), streams = {}) {
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const specRoot = path.join(cwd, 'specs');
+  if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
+    write(stderr, 'ERROR specs/: not found');
+    return 2;
+  }
+
+  const errors = [];
+  const parsed = new Map();
+  const ids = new Map();
+  const livingRequirements = new Map();
+  const requirementsBySpecId = new Map();
+  const changeTouches = new Map();
+  const paths = walkMarkdown(specRoot);
+
+  for (const filePath of paths) {
+    const display = relativeDisplay(filePath, cwd);
+    let result;
+    try {
+      result = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
+      parsed.set(filePath, result);
+    } catch (error) {
+      errors.push([display, `invalid frontmatter: ${error.message}`]);
+      continue;
+    }
+
+    const frontmatter = result.frontmatter || {};
+    const living = isLivingSpec(filePath, specRoot);
+    const change = path.dirname(filePath) === path.join(specRoot, 'changes');
+
+    if (living) {
+      const rawSpecId = frontmatter.id;
+      if (typeof rawSpecId !== 'string' || !rawSpecId.trim()) {
+        errors.push([display, 'missing spec id']);
+      } else {
+        const specId = rawSpecId.trim();
+        if (ids.has(specId)) {
+          errors.push([display, `duplicate spec id ${specId} (also in ${relativeDisplay(ids.get(specId), cwd)})`]);
+        } else {
+          ids.set(specId, filePath);
+        }
+      }
+    }
+
+    for (const field of ['applies_to', 'tags']) {
+      if (Object.hasOwn(frontmatter, field)) {
+        const value = frontmatter[field];
+        if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.length > 0)) {
+          errors.push([display, `${field} must be a list of strings`]);
+        }
+      }
+    }
+
+    if (Object.hasOwn(frontmatter, 'affects')) {
+      const value = frontmatter.affects;
+      if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.length > 0)) {
+        errors.push([display, 'affects must be a list of spec ids']);
+      }
+    }
+
+    if (change && !Object.hasOwn(frontmatter, 'affects')) {
+      errors.push([display, 'missing affects']);
+    } else if (change && Array.isArray(frontmatter.affects) && frontmatter.affects.length === 0) {
+      errors.push([display, 'affects must contain at least one spec id']);
+    }
+
+    if (living) {
+      const requirementIds = requirementDefinitions(result.body);
+      livingRequirements.set(filePath, requirementIds);
+      const counts = new Map();
+      for (const reqId of requirementIds) counts.set(reqId, (counts.get(reqId) || 0) + 1);
+      for (const [reqId, count] of [...counts].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        if (count > 1) errors.push([display, `duplicate requirement id ${reqId}`]);
+      }
+    }
+  }
+
+  const globalRequirements = new Map();
+  for (const [filePath, reqIds] of livingRequirements) {
+    for (const reqId of [...new Set(reqIds)].sort()) {
+      if (!globalRequirements.has(reqId)) globalRequirements.set(reqId, []);
+      globalRequirements.get(reqId).push(filePath);
+    }
+  }
+  for (const [reqId, reqPaths] of [...globalRequirements].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    if (reqPaths.length > 1) {
+      const first = reqPaths[0];
+      for (const filePath of reqPaths.slice(1)) {
+        errors.push([
+          relativeDisplay(filePath, cwd),
+          `duplicate requirement id ${reqId} (also in ${relativeDisplay(first, cwd)})`,
+        ]);
+      }
+    }
+  }
+
+  for (const [specId, filePath] of ids) {
+    requirementsBySpecId.set(specId, new Set(livingRequirements.get(filePath) || []));
+  }
+
+  const allExistingRequirements = new Set(globalRequirements.keys());
+  for (const filePath of paths) {
+    if (path.dirname(filePath) !== path.join(specRoot, 'changes') || !parsed.has(filePath)) continue;
+    const display = relativeDisplay(filePath, cwd);
+    const { frontmatter: rawFrontmatter, body } = parsed.get(filePath);
+    const frontmatter = rawFrontmatter || {};
+    const affects = frontmatter.affects;
+    if (!Array.isArray(affects) || !affects.every((item) => typeof item === 'string' && item.length > 0)) {
+      continue;
+    }
+
+    const affectedRequirements = new Set();
+    let anyKnown = false;
+    for (const specId of affects) {
+      if (!ids.has(specId)) {
+        errors.push([display, `unknown spec id ${specId}`]);
+      } else {
+        anyKnown = true;
+        for (const reqId of requirementsBySpecId.get(specId) || []) affectedRequirements.add(reqId);
+      }
+    }
+
+    const sections = changeSections(body);
+    for (const section of ['ADD', 'MODIFY', 'REMOVE']) {
+      for (const reqId of new Set(allRequirementIds(sections[section] || ''))) {
+        if (!changeTouches.has(reqId)) changeTouches.set(reqId, new Map());
+        const byFile = changeTouches.get(reqId);
+        if (!byFile.has(display)) byFile.set(display, new Set());
+        byFile.get(display).add(section);
+      }
+    }
+
+    if (anyKnown) {
+      for (const section of ['MODIFY', 'REMOVE']) {
+        for (const reqId of [...new Set(allRequirementIds(sections[section] || ''))].sort()) {
+          if (!affectedRequirements.has(reqId)) {
+            errors.push([display, `${section} unknown requirement id ${reqId}`]);
+          }
+        }
+      }
+    }
+    for (const reqId of [...new Set(allRequirementIds(sections.ADD || ''))].sort()) {
+      if (allExistingRequirements.has(reqId)) {
+        errors.push([display, `ADD existing requirement id ${reqId}`]);
+      }
+    }
+  }
+
+  for (const [reqId, byFile] of [...changeTouches].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    if (byFile.size < 2) continue;
+    const entries = [...byFile].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const touches = entries.map(
+      ([display, sections]) => `${display}: ${[...sections].sort().join('/')}`,
+    );
+    errors.push([
+      entries[0][0],
+      `conflicting active changes for ${reqId}: ${touches.join('; ')}`,
+    ]);
+  }
+
+  errors.sort((a, b) => {
+    const left = a[0] === b[0] ? a[1] : a[0];
+    const right = a[0] === b[0] ? b[1] : b[0];
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  for (const [display, message] of errors) write(stdout, `ERROR ${display}: ${message}`);
+  if (errors.length) {
+    write(stdout, `${errors.length} errors`);
+    return 1;
+  }
+  write(stdout, '0 errors');
+  return 0;
+}
+
+function helpText() {
+  return [
+    'Usage: charterleaf <command> [args]',
+    '',
+    'Commands:',
+    '  related <path>  find specs matching a repo-relative code path',
+    '  lint            check Charterleaf structural conventions',
+  ].join('\n');
+}
+
+function usageError(message, streams = {}) {
+  const stderr = streams.stderr || process.stderr;
+  if (message) write(stderr, `ERROR: ${message}`);
+  write(stderr, helpText());
+  return 2;
+}
+
+function main(argv = process.argv.slice(2), cwd = process.cwd(), streams = {}) {
+  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) {
+    write(streams.stdout || process.stdout, helpText());
+    return 0;
+  }
+  if (!argv.length) return usageError('a command is required', streams);
+
+  const [command, ...rest] = argv;
+  if (command === 'related') {
+    if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
+      write(streams.stdout || process.stdout, 'Usage: charterleaf related <path>');
+      return 0;
+    }
+    if (rest.length !== 1) return usageError('related requires exactly one path', streams);
+    return related(rest[0], path.resolve(cwd), streams);
+  }
+  if (command === 'lint') {
+    if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
+      write(streams.stdout || process.stdout, 'Usage: charterleaf lint');
+      return 0;
+    }
+    if (rest.length) return usageError('lint takes no arguments', streams);
+    return lint(path.resolve(cwd), streams);
+  }
+  return usageError(`unknown command ${command}`, streams);
+}
+
+module.exports = {
+  FrontmatterError,
+  changeSections,
+  globMatches,
+  lint,
+  main,
+  normalizeRepoPath,
+  parseFrontmatter,
+  related,
+  requirementDefinitions,
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@onedotmint/charterleaf",
+  "version": "0.1.0",
+  "description": "A tiny specification layer for coding agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onedotmint/charterleaf.git"
+  },
+  "homepage": "https://github.com/onedotmint/charterleaf#readme",
+  "bugs": {
+    "url": "https://github.com/onedotmint/charterleaf/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "charterleaf": "./bin/charterleaf.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "templates/",
+    "AGENTS_SNIPPET.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "charterleaf",
+    "ai-agent",
+    "coding-agent",
+    "specification",
+    "agent-skills",
+    "pi"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/charterleaf/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: charterleaf
+description: A tiny specification layer for durable project intent and constraints.
+---
+
+# Charterleaf
+
+Treat Charterleaf as a small knowledge layer, not a workflow system.
+
+When a concrete code path is known, run:
+
+```bash
+charterleaf related <path>
+```
+
+Read only the returned living specs and active changes. If the location is unknown, use the host agent's normal search tools; Charterleaf does not provide semantic search.
+
+Use authority in this order:
+
+```text
+Constitution > Active Change > Living Spec > Current Code
+```
+
+Keep specs compressed and evidence-based. Prefer contracts over commentary and durable pitfalls over patterns obvious from code. Never invent aspirational standards; record only demonstrated or explicitly accepted intent.
+
+Do not touch specs for renames, lint cleanup, routine refactors, temporary debugging, Todo/status changes, or trivial fixes with no durable implication.
+
+For a durable bug fix, use `Current` and `Expected` when useful and state what must `PRESERVE`. For other durable behavior/contract changes, keep one `specs/changes/<name>.md` delta with only needed `ADD`, `MODIFY`, `REMOVE`, and/or `PRESERVE` sections.
+
+After editing specs, run:
+
+```bash
+charterleaf lint
+```
+
+`lint` checks structural conventions and deterministic active-change conflicts only. It does not judge writing, architecture quality, or semantic code/spec drift.
+
+After an accepted change is implemented, merge the durable result into living specs and delete the change file. Git keeps history.
+
+Do not plan, manage tasks, invoke agents, run implementation/review workflows, manage memory, or replace the host agent's code-navigation tools.

package/templates/capability.md

@@ -0,0 +1,31 @@
+---
+id: <domain.capability>
+applies_to:
+  - <path/**>
+---
+
+# <Capability name>
+
+## Purpose
+
+<One short paragraph describing the durable capability.>
+
+## Requirements
+
+### <REQ-001> — <Requirement name>
+
+The system MUST <observable or verifiable behavior>.
+
+#### Scenarios
+
+- GIVEN <precondition>
+  WHEN <event/action>
+  THEN <observable result>.
+
+## Invariants
+
+- <What must always remain true.>
+
+## Non-goals
+
+- <What this capability intentionally does not cover.>

package/templates/change.md

@@ -0,0 +1,49 @@
+---
+affects:
+  - <existing.spec.id>
+---
+
+# <Change name>
+
+## Intent
+
+<What intentional behavior/contract change is being made, and why?>
+
+<!-- For a durable bug fix, optionally make the gap explicit:
+## Current
+<Observed behavior.>
+
+## Expected
+<Intended behavior.>
+
+Always use PRESERVE for important unchanged behavior.
+-->
+
+<!-- Keep only the delta sections that are actually needed. -->
+
+## ADD
+
+### <REQ-ID> — <Requirement name>
+
+<New durable requirement.>
+
+## MODIFY
+
+### <REQ-ID> — <Requirement name>
+
+<New form of an existing requirement.>
+
+Previously: <old behavior, only when useful for clarity>.
+
+## REMOVE
+
+- <Durable requirement or behavior being removed.>
+
+## PRESERVE
+
+- <Behavior, API shape, invariant, or boundary that must remain unchanged.>
+
+## Verification
+
+- <Behavior that proves the intended change.>
+- <Existing behavior that proves PRESERVE constraints did not drift.>

package/templates/decision.md

@@ -0,0 +1,17 @@
+# ADR-<NNNN> — <Decision title>
+
+## Context
+
+<What durable problem or constraint made a decision necessary?>
+
+## Decision
+
+<What was deliberately chosen?>
+
+## Why
+
+<Why is this preferable under the current project constraints?>
+
+## Revisit when
+
+<Concrete condition that would justify reconsidering this decision.>

package/templates/engineering.md

@@ -0,0 +1,25 @@
+---
+id: <engineering.scope>
+applies_to:
+  - <path/**>
+---
+
+# <Engineering scope>
+
+## Boundaries
+
+- <Durable dependency or architecture boundary.>
+
+## Constraints
+
+- <Long-lived implementation constraint.>
+
+<!-- Optional; include only for concrete, durable traps not obvious from code:
+## Pitfalls
+
+- <What looks reasonable here but must not be done, and why.>
+-->
+
+## Verification
+
+- <How behavior changes in this scope should be verified.>