@onedotmint/charterleaf 0.2.0 → 0.3.0

package/AGENTS_SNIPPET.md

@@ -1,21 +1,14 @@
-# Charterleaf instructions
+# Project References
 
-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.
+Use this file as the project navigation entry.
+Document where authoritative information lives — project state,
+validation, resources, history, and other project-specific sources.
 
-- `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.
+Durable constraints live under `specs/`. For work on a concrete
+repository path:
 
-When a concrete code path is known, use `charterleaf related <path>` to locate matching living specs plus active changes that affect them. When the relevant code path is not yet known, use `charterleaf map` only to discover available specification scopes; do not read every listed specification. Use normal code navigation to locate the smallest relevant area, then use `charterleaf related <path>`. For broad project-level questions, start with normal project entry documents; do not expand into every spec or project-state document merely because no path was provided. Use `charterleaf lint` for structural validation and mechanical active-change conflicts. These commands are helpers, not workflow gates.
+    charterleaf related <path>
 
-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.
+Read authoritative owners progressively. If the current source is
+sufficient, stop. Keep one owner per fact and point to it elsewhere
+instead of copying the same fact into multiple documents.

package/README.md

@@ -2,20 +2,28 @@
 
 A tiny specification layer for coding agents.
 
+Given a concrete repository path, Charterleaf answers one question:
+
+> Which durable constraints should I read before touching this code?
+
 Durable project intent, deterministic routing, and structural linting —
 without workflow orchestration.
 
-> **Keep project intent in the repo, without turning specs into a workflow.**
+## Two layers
 
-Charterleaf keeps durable project knowledge in Markdown and provides exactly three deterministic helpers:
+Charterleaf sits beside a project's own navigation, not on top of it.
 
-```bash
-charterleaf map
-charterleaf related <path>
-charterleaf lint
-```
+- **A project reference protocol** — a tracked `AGENTS.md` entry plus
+  the project's own documents — tells an agent *where* authoritative
+  information lives: current state, validation, resources, history,
+  source roots.
+- **Charterleaf** tells an agent *which durable constraints* matter when
+  work lands on a specific repository path.
 
-It is a knowledge layer, not a workflow framework.
+Charterleaf complements project navigation; it does not replace
+project-owned sources of state, evidence, or workflow. It stores and
+routes durable constraints; it never becomes the owner of a fact that
+belongs to a project file.
 
 ## Install
 
@@ -35,21 +43,87 @@ No Pi extension or Pi runtime dependency is used.
 
 ## CLI
 
-Run from a repository root containing `specs/`:
+Charterleaf exposes exactly two deterministic commands. Run them from a
+repository root containing `specs/`:
 
 ```bash
-charterleaf map
-charterleaf related src/auth/session.ts
+charterleaf related <path>
 charterleaf lint
 ```
 
-`map` shows a deterministic, lightweight index of the `specs/` layer when a relevant code path is not yet known. It lists specification scopes and metadata only; it does not summarize specs or recommend what to read. Use normal code navigation to find the smallest relevant area, then use `related <path>`.
+There is no `map` command. Discovery is handled by a scoped miss (below)
+and by the project's own reference protocol.
+
+### related \<path\>
+
+Routes the supplied repo-relative path (`/` or `\` separators) to durable
+constraints:
+
+- `specs/constitution.md` is **Global**: returned whenever it exists,
+  regardless of frontmatter. It needs no `id` and no `applies_to`.
+- `capabilities/` and `engineering/` specs are **Scoped**: returned when
+  any `applies_to` glob matches.
+- Active changes whose `affects` reference a matched spec id are appended
+  under `Active changes`.
+
+```text
+Global
+  specs/constitution.md
+
+Scoped
+  specs/capabilities/auth.md
+```
+
+`applies_to` is a deterministic routing hint, not a completeness proof.
+"No match" only ever means "no living spec's `applies_to` glob matched
+this path" — never "no constraints apply". When nothing matches, the
+command states that explicitly and lists available living specs by `id`,
+path, and `applies_to` only, so discovery stays possible without reading
+every spec:
 
-`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.
+```text
+Global
+  specs/constitution.md
 
-`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.
+Scoped
+  No applies_to glob matched this path.
 
-The frontmatter convention intentionally supports only top-level scalar values and simple string lists. Runtime dependencies remain zero.
+Available living specs
+  auth.session
+    specs/capabilities/auth.md
+    applies_to: src/auth/**
+
+  engineering.backend
+    specs/engineering/backend.md
+    applies_to: src/**/*.ts
+```
+
+`related` never inspects the filesystem for the supplied path; it accepts
+the caller's repo-relative string. A scoped miss is success (exit code
+0), not an error.
+
+### lint
+
+```bash
+charterleaf lint
+```
+
+`lint` performs mechanical structural checks only: frontmatter shape,
+living Spec IDs, required `applies_to` on living specs, duplicate spec
+and requirement IDs, change references, static `ADD` / `MODIFY` /
+`REMOVE` references, changes whose `ADD` / `MODIFY` / `REMOVE` sections
+are all empty (HTML comments do not count), and conflicting active
+changes that touch the same requirement ID. Success prints
+`0 structural errors`.
+
+`lint` does **not** verify:
+
+- semantic correctness;
+- code/spec agreement;
+- routing coverage;
+- project compliance;
+- whether a change is actually complete;
+- whether an Agent read the specs.
 
 ## Project knowledge
 
@@ -62,51 +136,75 @@ specs/
 └── 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.
+- `constitution.md` — rare project-wide durable boundaries. Global
+  constraint; not routed by `applies_to`.
+- `capabilities/` — durable observable behavior, contracts, invariants,
+  non-goals.
+- `engineering/` — durable implementation boundaries, long-lived
+  constraints, recurring pitfalls, verification practice.
+- `decisions/` — important architectural rationale and revisit
+  conditions.
+- `changes/` — optional staging for an accepted but not-yet-implemented
+  contract. See below.
 
-Authority is structural, not scored metadata:
+## Writing specs
 
-```text
-Constitution > Active Change > Living Spec > Current Code
-```
+A spec records a constraint whose absence would plausibly cause a future
+developer or agent to make a wrong decision. It should be non-obvious,
+durable, **already true**, and mistake-preventing. Good fits: contracts,
+invariants, architecture boundaries, non-goals, recurring pitfalls,
+accepted rationale, verification constraints.
+
+Do not write specs for current state, future design, aspirations, todos,
+implementation plans, session notes, progress, temporary debugging,
+navigation, or history. What you hope to become is a plan, not a living
+spec.
+
+## changes/ is optional staging
 
-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.
+Use `specs/changes/<name>.md` only when an accepted future contract must
+temporarily coexist with current living reality — for example when
+implementation happens in another session or by another agent, human
+review comes first, or a multi-step migration is underway. A change must
+contain at least one of `ADD`, `MODIFY`, `REMOVE`; `PRESERVE` alone is
+not a change.
 
-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.
+Otherwise, implement, verify, and update the living spec if durable truth
+changed. After an accepted change is implemented, merge the durable
+result into living specs and delete the change file. Git keeps history.
 
-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.
+## Agent conventions
 
-## Other agents
+The complete Agent convention lives in
+[`skills/charterleaf/SKILL.md`](skills/charterleaf/SKILL.md): adoption
+gate, progressive retrieval, `related` and `lint` semantics, spec
+writing discipline, and durable learning.
 
-Charterleaf core does not depend on Pi. Any coding agent capable of reading Markdown and executing shell commands can use it.
+For agents that read project instructions, the minimal reference
+bootstrap is [`AGENTS_SNIPPET.md`](AGENTS_SNIPPET.md).
 
-Use `AGENTS_SNIPPET.md` with agents that support project instructions. Agent Skills-compatible harnesses can use the bundled `skills/charterleaf/SKILL.md`.
+Charterleaf core does not depend on Pi. Any coding agent that can read
+Markdown and run shell commands can use it.
 
 ## 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
+- project state, tasks, planning, or workflow;
+- memory, session lifecycle, evidence, or history management;
+- scope registry, owner registry, or project bootstrap command;
+- semantic search, embeddings, or code/spec semantic verification;
+- repository coverage analysis or filesystem awareness in `related`;
+- database, index, cache, daemon, or watcher;
+- plugin/extension runtime;
+- Git abstraction.
 
-The three CLI commands are helpers, not workflow gates.
+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.
+Requires Node.js 20 or newer. There are no runtime or development
+dependencies and no build step.
 
 ```bash
 npm test

package/lib/charterleaf.js

@@ -163,8 +163,6 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
 
   const target = normalizeRepoPath(repoPath);
   const documents = [];
-  const matches = [];
-  const matchedIds = new Set();
   const errors = [];
 
   for (const filePath of walkMarkdown(specRoot)) {
@@ -176,23 +174,24 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
       errors.push(`ERROR ${display}: ${error.message}`);
       continue;
     }
-    documents.push({ filePath, display, frontmatter: parsed.frontmatter || {} });
+    documents.push({
+      filePath,
+      display,
+      relative: path.relative(specRoot, filePath).replaceAll('\\', '/'),
+      frontmatter: parsed.frontmatter || {},
+    });
   }
 
-  for (const document of documents) {
-    const { display, frontmatter } = document;
-    if (!Object.hasOwn(frontmatter, 'applies_to')) continue;
-    const patterns = frontmatter.applies_to;
+  const livingSpecs = documents.filter((document) => isLivingSpec(document.filePath, specRoot));
+  const scoped = [];
+  for (const document of livingSpecs) {
+    const patterns = document.frontmatter.applies_to;
+    if (patterns === undefined) continue;
     if (!Array.isArray(patterns) || !patterns.every((item) => typeof item === 'string')) {
-      errors.push(`ERROR ${display}: applies_to must be a list of paths`);
+      errors.push(`ERROR ${document.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 (patterns.some((pattern) => globMatches(pattern, target))) scoped.push(document);
   }
 
   if (errors.length) {
@@ -200,6 +199,12 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
     return 2;
   }
 
+  const matchedIds = new Set();
+  for (const document of scoped) {
+    const id = typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '';
+    if (id) matchedIds.add(id);
+  }
+
   const activeChanges = [];
   if (matchedIds.size) {
     const changeRoot = path.join(specRoot, 'changes');
@@ -213,93 +218,40 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
     }
   }
 
-  matches.sort();
+  scoped.sort((left, right) => (left.display < right.display ? -1 : left.display > right.display ? 1 : 0));
   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 writeLivingSpecs(stdout, documents) {
-  for (const document of documents) {
-    const id = typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '';
-    const appliesTo = Array.isArray(document.frontmatter.applies_to)
-      ? document.frontmatter.applies_to.join(', ')
-      : String(document.frontmatter.applies_to || '');
-    write(stdout, `  ${id || '(missing id)'}`);
-    write(stdout, `    ${document.display}`);
-    write(stdout, `    applies_to: ${appliesTo}`);
-  }
-}
-
-function map(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 documents = [];
-  const errors = [];
-  for (const filePath of walkMarkdown(specRoot)) {
-    const display = relativeDisplay(filePath, cwd);
-    try {
-      const { frontmatter } = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
-      documents.push({
-        filePath,
-        display,
-        frontmatter: frontmatter || {},
-        relative: path.relative(specRoot, filePath).replaceAll('\\', '/'),
-      });
-    } catch (error) {
-      errors.push(`ERROR ${display}: ${error.message}`);
-    }
+  const blocks = [];
+  const constitution = documents.find((document) => document.relative === 'constitution.md');
+  if (constitution) blocks.push(['Global', [`  ${constitution.display}`]]);
+  if (scoped.length) {
+    blocks.push(['Scoped', scoped.map((document) => `  ${document.display}`)]);
+  } else {
+    blocks.push(['Scoped', ['  No applies_to glob matched this path.']]);
   }
-  if (errors.length) {
-    for (const error of errors) write(stderr, error);
-    return 2;
+  if (activeChanges.length) {
+    blocks.push(['Active changes', activeChanges.map((change) => `  ${change}`)]);
   }
-
-  const constitution = [];
-  const capabilities = [];
-  const engineering = [];
-  const decisions = [];
-  const changes = [];
-  for (const document of documents) {
-    if (document.relative === 'constitution.md') constitution.push(document);
-    else if (document.relative.startsWith('capabilities/')) capabilities.push(document);
-    else if (document.relative.startsWith('engineering/')) engineering.push(document);
-    else if (document.relative.startsWith('decisions/')) decisions.push(document);
-    else if (document.relative.startsWith('changes/')) changes.push(document);
+  if (!scoped.length && livingSpecs.length) {
+    const lines = [];
+    livingSpecs.forEach((document, index) => {
+      if (index) lines.push('');
+      const id = typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '';
+      const appliesTo = Array.isArray(document.frontmatter.applies_to)
+        ? document.frontmatter.applies_to.join(', ')
+        : String(document.frontmatter.applies_to ?? '');
+      lines.push(`  ${id || '(missing id)'}`);
+      lines.push(`    ${document.display}`);
+      lines.push(`    applies_to: ${appliesTo}`);
+    });
+    blocks.push(['Available living specs', lines]);
   }
 
-  write(stdout, 'Constitution');
-  for (const document of constitution) write(stdout, `  ${document.display}`);
-  write(stdout, '');
-  write(stdout, 'Capabilities');
-  writeLivingSpecs(stdout, capabilities);
-  write(stdout, '');
-  write(stdout, 'Engineering');
-  writeLivingSpecs(stdout, engineering);
-  write(stdout, '');
-  write(stdout, 'Decisions');
-  for (const document of decisions) write(stdout, `  ${document.display}`);
-  write(stdout, '');
-  write(stdout, 'Active changes');
-  for (const document of changes) {
-    const affects = Array.isArray(document.frontmatter.affects)
-      ? document.frontmatter.affects.join(', ')
-      : String(document.frontmatter.affects || '');
-    write(stdout, `  ${document.display}`);
-    write(stdout, `    affects: ${affects}`);
-  }
+  blocks.forEach(([title, lines], index) => {
+    if (index) write(stdout, '');
+    write(stdout, title);
+    for (const line of lines) write(stdout, line);
+  });
   return 0;
 }
 
@@ -317,6 +269,10 @@ function requirementDefinitions(text) {
   return found;
 }
 
+function stripHtmlComments(text) {
+  return String(text).replace(/<!--[\s\S]*?(?:-->|$)/g, '');
+}
+
 function changeSections(body) {
   const sections = new Map();
   let current = null;
@@ -384,6 +340,12 @@ function lint(cwd = process.cwd(), streams = {}) {
           ids.set(specId, filePath);
         }
       }
+
+      if (!Object.hasOwn(frontmatter, 'applies_to')) {
+        errors.push([display, 'missing applies_to']);
+      } else if (Array.isArray(frontmatter.applies_to) && frontmatter.applies_to.length === 0) {
+        errors.push([display, 'applies_to must contain at least one path']);
+      }
     }
 
     for (const field of ['applies_to', 'tags']) {
@@ -448,6 +410,14 @@ function lint(cwd = process.cwd(), streams = {}) {
     const display = relativeDisplay(filePath, cwd);
     const { frontmatter: rawFrontmatter, body } = parsed.get(filePath);
     const frontmatter = rawFrontmatter || {};
+    const sections = changeSections(body);
+    const hasDelta = ['ADD', 'MODIFY', 'REMOVE'].some(
+      (section) => stripHtmlComments(sections[section] || '').trim().length > 0,
+    );
+    if (!hasDelta) {
+      errors.push([display, 'change must contain at least one ADD, MODIFY, or REMOVE section']);
+    }
+
     const affects = frontmatter.affects;
     if (!Array.isArray(affects) || !affects.every((item) => typeof item === 'string' && item.length > 0)) {
       continue;
@@ -464,7 +434,6 @@ function lint(cwd = process.cwd(), streams = {}) {
       }
     }
 
-    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());
@@ -509,10 +478,10 @@ function lint(cwd = process.cwd(), streams = {}) {
   });
   for (const [display, message] of errors) write(stdout, `ERROR ${display}: ${message}`);
   if (errors.length) {
-    write(stdout, `${errors.length} errors`);
+    write(stdout, `${errors.length} structural errors`);
     return 1;
   }
-  write(stdout, '0 errors');
+  write(stdout, '0 structural errors');
   return 0;
 }
 
@@ -521,9 +490,8 @@ function helpText() {
     'Usage: charterleaf <command> [args]',
     '',
     'Commands:',
-    '  map             show the specification map',
-    '  related <path>  find specs matching a repo-relative code path',
-    '  lint            check Charterleaf structural conventions',
+    '  related <path>  find durable constraints matching a repo-relative path',
+    '  lint            report structural errors in specs/',
   ].join('\n');
 }
 
@@ -542,14 +510,6 @@ function main(argv = process.argv.slice(2), cwd = process.cwd(), streams = {}) {
   if (!argv.length) return usageError('a command is required', streams);
 
   const [command, ...rest] = argv;
-  if (command === 'map') {
-    if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
-      write(streams.stdout || process.stdout, 'Usage: charterleaf map');
-      return 0;
-    }
-    if (rest.length) return usageError('map takes no arguments', streams);
-    return map(path.resolve(cwd), streams);
-  }
   if (command === 'related') {
     if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
       write(streams.stdout || process.stdout, 'Usage: charterleaf related <path>');
@@ -575,7 +535,6 @@ module.exports = {
   globMatches,
   lint,
   main,
-  map,
   normalizeRepoPath,
   parseFrontmatter,
   related,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onedotmint/charterleaf",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A tiny specification layer for coding agents.",
   "license": "MIT",
   "repository": {

package/skills/charterleaf/SKILL.md

@@ -5,46 +5,145 @@ description: A tiny specification layer for durable project intent and constrain
 
 # Charterleaf
 
-Treat Charterleaf as a small knowledge layer, not a workflow system.
+## Adoption gate
 
-When a concrete code path is known, run:
+Before using Charterleaf in a repository, check whether `specs/` exists.
 
-```bash
-charterleaf related <path>
-```
+If no `specs/` directory exists:
 
-Read only the returned living specs and active changes.
+- do not run Charterleaf;
+- do not create `specs/`;
+- do not recommend adoption automatically;
+- continue using the repository's normal instructions.
 
-When the relevant code path is not yet known, run:
+Charterleaf is opt-in.
 
-```bash
-charterleaf map
-```
+## Boundary
 
-Use the map only to discover available specification scopes. Do not read every listed specification by default. Use normal code navigation to locate the smallest relevant area. Once a concrete path is known, run `charterleaf related <path>`.
+Charterleaf answers one question:
 
-For broad project-level questions, start with normal project entry documents. Do not expand into every spec or project-state document merely because no path was provided. `map` is not semantic search.
+> For this repository path, which durable constraints should I read?
 
-Use authority in this order:
+A project's own reference protocol — its `AGENTS.md` entry and the
+project-owned documents it points to — answers a different question:
 
-```text
-Constitution > Active Change > Living Spec > Current Code
-```
+> Where do this project's authoritative facts live?
 
-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.
+Charterleaf owns only: spec taxonomy, durable constraint routing
+(`related`), and structural lint (`lint`).
 
-Do not touch specs for renames, lint cleanup, routine refactors, temporary debugging, Todo/status changes, or trivial fixes with no durable implication.
+Charterleaf does not own: current project state, tasks, workflow,
+planning, memory, evidence, history, session lifecycle, project-wide
+consistency, semantic code/spec verification, or repository state
+synchronization.
 
-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.
+## Progressive retrieval
 
-After editing specs, run:
+1. **Identify the need.** Orientation, current state, evidence,
+   validation, resources, implementation detail, or durable constraint?
+2. **Locate the owner.** If the owner is known, read it directly. If not,
+   read the project `AGENTS.md` / project instructions. Do not scan the
+   whole repository's Markdown first.
+3. **Enough?** If the authoritative information you have is sufficient,
+   stop reading. Do not keep reading for completeness.
+4. **Expand progressively.** Only when information is insufficient, the
+   owner is unclear, sources conflict, the work area is unknown, or
+   verification is needed — and only one layer at a time.
+5. **Concrete path.** Once work lands on a concrete repository path, run
+   `charterleaf related <path>` and read the returned constraints.
+6. **Work.** Normal implementation, learning, design, or debugging. The
+   reference protocol does not manage workflow.
+7. **Write back.** Changed current fact → its single owner. New evidence
+   → the evidence owner. New or changed durable constraint → `specs/`.
+   Historical event → project history or Git. Future plan → planning
+   docs. Never copy one fact into several files: one owner per fact,
+   other documents point to it.
 
-```bash
-charterleaf lint
-```
+## related semantics
 
-`lint` checks structural conventions and deterministic active-change conflicts only. It does not judge writing, architecture quality, or semantic code/spec drift.
+`charterleaf related <path>`:
 
-After an accepted change is implemented, merge the durable result into living specs and delete the change file. Git keeps history.
+- always returns `specs/constitution.md` as Global when it exists;
+- routes `capabilities/` and `engineering/` specs whose `applies_to`
+  glob matches the path;
+- appends active changes whose `affects` reference a returned spec id.
 
-Do not plan, manage tasks, invoke agents, run implementation/review workflows, manage memory, or replace the host agent's code-navigation tools.
+`applies_to` is a **routing hint**, not a completeness proof. The message
+`No applies_to glob matched this path.` means exactly that — it never
+means "no constraints apply". On a scoped miss the command lists
+available living specs by `id`, path, and `applies_to` only. Use that
+list to find the right area, then rerun with the concrete path. The
+command never prints spec bodies, ranks relevance, or guesses.
+
+## lint semantics
+
+`charterleaf lint` reports mechanical structural problems only:
+frontmatter shape, living-spec ids and `applies_to`, duplicate spec and
+requirement ids, change references, changes whose `ADD` / `MODIFY` /
+`REMOVE` sections are all empty (HTML comments do not count), and
+conflicting active changes.
+
+It does **not** verify semantic correctness, code/spec agreement,
+routing coverage, project compliance, whether a change is complete, or
+whether an Agent read the specs. Success prints `0 structural errors`.
+Run it after editing specs.
+
+## Spec writing discipline
+
+A spec records a constraint whose absence would plausibly cause a future
+developer or agent to make a wrong decision. It should be non-obvious,
+durable, **already true**, and mistake-preventing.
+
+Good fits: contracts, invariants, architecture boundaries, non-goals,
+recurring pitfalls, accepted architectural rationale, verification
+constraints.
+
+Not specs: current state, future design, aspirations, todos,
+implementation plans, session notes, progress, temporary debugging,
+navigation, history. "Already true" matters — what you hope to become is
+a plan, not a living spec.
+
+Place a constraint where it belongs:
+
+- rare project-wide durable boundary → `specs/constitution.md`;
+- observable behavior, contract, invariant, or non-goal →
+  `specs/capabilities/`;
+- implementation boundary, long-lived constraint, recurring pitfall, or
+  verification practice → `specs/engineering/`;
+- important architectural rationale and revisit condition →
+  `specs/decisions/`.
+
+Keep specs compressed. Prefer durable contracts and pitfalls over
+commentary, and never invent aspirational standards.
+
+## changes/ is optional staging
+
+Use `specs/changes/<name>.md` only when an accepted future contract must
+temporarily coexist with current living reality — for example when
+implementation happens in another session or by another agent, human
+review comes first, or a multi-step migration is underway. A change must
+contain at least one of `ADD`, `MODIFY`, `REMOVE`; `PRESERVE` alone is
+not a change.
+
+Otherwise: implement, verify, and update the living spec if durable truth
+changed. After an accepted change is implemented, merge the durable
+result into living specs and delete the change file. Git keeps history.
+
+## Durable learning
+
+After non-trivial implementation or debugging, ask once: did this work
+reveal durable knowledge whose absence could cause a future mistake?
+
+If not, change nothing. If yes, record only the durable constraint in
+the matching category above.
+
+Never record current progress, temporary debug notes, one-off commands,
+session history, todos, or transient observations. Specs accumulate
+durable constraints, not development activity.
+
+## Non-goals
+
+Do not use Charterleaf to manage tasks, planning, workflow, memory,
+evidence, history, repository state, or scope registries. Do not ask it
+to verify semantics, coverage, or project compliance. It finds
+constraints; it does not manage the project.

package/templates/change.md

@@ -5,6 +5,16 @@ affects:
 
 # <Change name>
 
+<!-- Optional staging. Use only when an accepted future contract must
+coexist with current living reality — implementation in another session or
+by another agent, human review first, or a multi-step migration.
+
+A change must contain at least one of ADD, MODIFY, or REMOVE.
+PRESERVE alone is not a change.
+
+After implementation, merge the durable result into living specs and
+delete this file. Git keeps history. -->
+
 ## Intent
 
 <What intentional behavior/contract change is being made, and why?>