@onedotmint/charterleaf 0.3.0 → 0.4.0

package/AGENTS_SNIPPET.md

@@ -4,11 +4,31 @@ Use this file as the project navigation entry.
 Document where authoritative information lives — project state,
 validation, resources, history, and other project-specific sources.
 
-Durable constraints live under `specs/`. For work on a concrete
-repository path:
+Source code owns implementation, tests own executable verification,
+`AGENTS.md` owns navigation, and `specs/` owns durable constraints. Read
+these authoritative owners progressively; stop when sufficient. Keep one
+owner per fact and link to it rather than duplicating it.
+
+Charterleaf automation is explicit opt-in, not implied by this entry or
+by an existing `specs/` directory. In Pi, the user chooses Auto, Confirm,
+Reference or Not Enable through `/charterleaf`; the saved project mode in
+`specs/.charterleaf.json` controls automation. Missing config or `off`
+means no automatic scan, adoption prompt or document creation. Do not
+change activation config on the user's behalf.
+
+For manual use on a concrete repository path, run from the project root:
 
     charterleaf related <path>
 
-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.
+Read the returned constraints. A routing miss is not proof that none
+apply. The manual CLI remains available independently of Pi and its mode
+config; run `charterleaf lint` after spec edits (structural checks only).
+
+With automation enabled, use supplied constraints or explicitly read the
+named specs before retrying a gated write/edit. Use standard `write`/`edit`
+for spec changes: Confirm requires each approval; Reference allows no
+spec changes. Do not bypass these cooperative checks with Bash or another
+writer. No durable change means no spec edit; never relax a spec merely
+to accommodate conflicting code. Preserve user/parallel work and keep
+state, plans, evidence and history in their existing authoritative owners,
+not in a new Charterleaf workflow.

package/README.md

@@ -1,13 +1,16 @@
 # Charterleaf
 
-A tiny specification layer for coding agents.
+A lightweight agent-native constraint layer for coding agents.
+
+**Code is implementation. Tests are verification. Specs are durable constraints.
+Charterleaf connects them.**
 
 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.
+with opt-in native Pi integration, without workflow orchestration.
 
 ## Two layers
 
@@ -27,19 +30,121 @@ belongs to a project file.
 
 ## Install
 
-Install the public scoped npm package:
+Install once in Pi to discover the bundled Extension and Skill:
 
 ```bash
-npm install -g @onedotmint/charterleaf
+pi install npm:@onedotmint/charterleaf
 ```
 
-Pi can install the same package and discover its bundled Agent Skill:
+**v0.4 is not yet published.** Until publication, install the local package
+with `pi install /absolute/path/to/charterleaf` (a package directory, not a
+`.tgz` file). For the standalone CLI, pack with `npm pack`, then use `npm install -g ./onedotmint-charterleaf-0.4.0.tgz`; after publication,
+use `npm install -g @onedotmint/charterleaf`.
 
-```bash
-pi install npm:@onedotmint/charterleaf
+Restart Pi or run `/reload` after installation, then use `/charterleaf` in each
+project you want to enable. To stop automation, choose **Not Enable** in that
+menu. To remove the global package, use `pi remove npm:@onedotmint/charterleaf`
+(or the same local directory source used for installation); project docs remain.
+
+A Pi-only install needs no second global npm install: the Extension calls Core
+directly and supplies the bundled CLI entry point for optional manual checks.
+
+The **Core/CLI** runs standalone on Node.js **20+**, has no dependencies,
+and requires no Pi. The **Pi Extension** is tested against
+`@earendil-works/pi-coding-agent` **1.1.0** and uses `agent_before_settle`:
+it requires a host with that compatible Extension API, not just any Pi
+version. That Pi host requires Node.js **22.19.0+**; the Core's lower
+minimum does not make older Node versions suitable for the host.
+
+## Native Pi modes
+
+Run `/charterleaf` in Pi for the native project mode menu:
+
+| Choice | Behavior |
+| --- | --- |
+| **Auto** (recommended) | Read constraints; maintain only justified durable knowledge. |
+| **Confirm** | Read automatically; approve each exact standard spec write/edit. |
+| **Reference** | Read and check; report proposals or conflicts, never modify specs. |
+| **Not Enable** | Turn automation off; keep existing documents. |
+
+The choice is saved immediately in `specs/.charterleaf.json`:
+
+```json
+{ "version": 1, "mode": "off" }
 ```
 
-No Pi extension or Pi runtime dependency is used.
+Valid modes are `auto`, `confirm`, `reference`, and `off`. Missing config
+means **off**; existing `specs/` alone never enables automation. Activation
+is an explicit user choice, not an Agent decision. Enabling creates only
+this config (and its directory if needed), not a constitution or a pile
+of spec documents. Disabling preserves documents; cancel changes nothing.
+Disabled/unconfigured projects get no automatic adoption prompt, task
+context, scan, or document bootstrap. Manual CLI use is independent of
+this config.
+
+Without UI, saved Auto and Reference modes still read/check constraints;
+Confirm denies spec mutations because approval is unavailable. A refused identical
+proposal does not reopen an approval dialog in the same task; a new user task
+can make a fresh proposal. The
+`/charterleaf` menu does nothing without UI.
+
+## Architecture and task behavior
+
+- **Core** (`lib/charterleaf.js`) exports `resolveRelated` for structured
+  deterministic routing shared with the CLI. This adds no CLI command
+  and requires no spec-format migration.
+- **Extension** (`extensions/charterleaf.js`, with `lib/project.js`) uses
+  native command, task/context, tool-call/result, compaction and settlement
+  hooks for opt-in loading, write gates, mode approval and a final review.
+- **Skill** (`skills/charterleaf/SKILL.md`) supplies semantic judgment and
+  maintenance discipline. It is not a deterministic semantic validator.
+
+For known paths, standard `read` results carry the applicable constraint
+bodies without replacing the original result. A standard code `write` or
+`edit` with unseen constraints is blocked, carrying the constraints or
+an explicit read request. Read and assess them, then retry; do not evade
+this gate via Bash. Delivery counts as loaded only at the **next model
+request**, not when a parallel sibling tool finishes.
+
+Automatic spec bodies have a **24,000-byte budget per task** and an
+**8,000-byte per-file limit**. Larger files or exhausted budgets require
+an explicit complete `read`; a partial/truncated read is not full
+knowledge. Native Pi offset pages are credited only when their exact content
+covers the same spec version with no gaps; ordinary prose about truncation does
+not count as a tool truncation notice. On a scoped miss, the Extension supplies metadata only for
+available living specs, capped at 12 entries and 2,000 characters;
+`charterleaf related <path>` provides the full routing list. A miss never
+proves that no constraints apply.
+
+Compact rules from `skills/charterleaf/runtime.md` are supplied once per
+project/session branch; the full `SKILL.md` authoring/CLI guide stays on demand.
+Each task adds only its current mode/root. Same-version spec bodies already
+seen in the retained branch are reused across tasks, while ownership, Git
+baseline and body budget are reset per task. Switching branches or compaction
+clears context-delivery bookkeeping.
+Routing is recomputed through Core for each concrete path check, so new scopes
+and changed globs are not hidden by stale routing caches. Changed spec content
+requires fresh delivery; successful standard spec writes invalidate loaded state.
+Compaction invalidates loaded context so constraints must be delivered
+again. This is task-local bookkeeping, not a watcher or persistent index.
+
+At successful, actionable `agent_before_settle`, the Extension may request
+**at most one final semantic review per task** after development. It
+separates successful standard-tool paths whose observed content is still
+unchanged from **unattributed** changes observed against the task's Git
+baseline. Neither a touched file nor a dirty worktree proves ownership
+of every line. Preserve existing user dirt and parallel work; unattributed
+changes alone must not justify spec edits. No automatic revert, stage,
+commit or push is performed.
+
+**No durable knowledge means no spec edit.** Keep only established,
+non-obvious, mistake-preventing contracts, invariants, boundaries,
+pitfalls or accepted decisions — not code summaries or task logs. A
+code/spec conflict is not permission to accommodate incorrect code:
+distinguish implementation bugs, authoritatively obsolete specs and
+explicitly intended contract changes. When uncertain, preserve the spec
+and report the conflict. This review does not start an independent
+workflow or another development cycle.
 
 ## CLI
 
@@ -177,8 +282,8 @@ result into living specs and delete the change file. Git keeps history.
 
 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.
+and ownership, progressive retrieval, `related` and `lint` semantics,
+mode behavior, spec writing discipline, and durable learning.
 
 For agents that read project instructions, the minimal reference
 bootstrap is [`AGENTS_SNIPPET.md`](AGENTS_SNIPPET.md).
@@ -188,29 +293,100 @@ Markdown and run shell commands can use it.
 
 ## Boundaries
 
-Charterleaf has no:
-
-- 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 two CLI commands are helpers, not workflow gates.
+Charterleaf has no project state/task system, planning or workflow
+orchestration, memory/evidence/history management, scope/owner registry,
+project bootstrap command, semantic search/embeddings, coverage analyzer,
+database, persistent index, daemon, watcher or independent AI service.
+The Extension uses the host lifecycle and lightweight Git snapshots;
+it does not become a session manager or Git workflow.
+
+Important limits:
+
+- Bash, external writers and opaque/custom tools cannot be fully
+  intercepted. Reference and Confirm are **not security sandboxes**;
+  use standard `write`/`edit` for all spec changes.
+- In non-Git projects, standard-tool observations still work, but opaque
+  changes cannot be reliably discovered or attributed; final review falls
+  back to conversation evidence. Git snapshots do not detect gitignored
+  files; standard tool observations can still identify directly touched
+  paths. Neither mechanism proves ownership of all content.
+- Custom/nested tool integrations depend on compatible host forwarding
+  and queue support. Where supported, constraint notes must survive into
+  the model-visible result while original content, images and structured
+  results are preserved. Do not assume every custom envelope does this;
+  read large specs directly with standard `read` and offset pages rather than relying on
+  a nested wrapper that can hide or truncate their bodies.
+- `lint` checks structure only. Skill-guided reviews are model judgments
+  and may misjudge relevance, durable value or a conflict; neither proves
+  semantic correctness or compliance.
+- Paths support repo-relative or same-project absolute paths, `/` or `\`
+  separators, Pi's `@path`/`file://` aliases, and Windows drive paths mapped
+  to `/mnt/<drive>/` on WSL. Enabled standard tools execute the normalized
+   path that was checked; spec authorization also preserves the original path's
+   protected identity when a spec symlink points elsewhere inside the project.
+  Foreign UNC paths are not interpreted as local paths; symlink escapes are
+  rejected for project spec writes. Native Windows behavior needs platform testing.
+- `related` has no filesystem awareness of the supplied target path and
+  no proof of routing coverage. Task-local hashes are not a continuous
+  monitor of external changes. A single spec line larger than Pi's read byte
+  limit cannot be credited as read; do not keep retrying or bypass the gate —
+  report it and ask for readable formatting or a user-chosen mode change.
+  Files over 2 MiB use coarse size/mtime fingerprints;
+  Git checks exceeding 500 changed/untracked entries fall back to conversation
+  evidence instead of scanning a large worktree.
+
+The two CLI commands remain helpers, not workflow gates. Native tool
+gates apply only to the opt-in Pi integration, within the limits above.
 
 ## Development
 
-Requires Node.js 20 or newer. There are no runtime or development
-dependencies and no build step.
+Core development requires Node.js 20 or newer; there are no runtime or
+development dependencies and no build step. Use the higher Node/host
+requirements above for Pi smoke checks.
+
+Verification commands:
 
 ```bash
 npm test
+npm run test:pi   # requires compatible Pi on PATH; isolated RPC UI smoke, no model calls
+node --test tests/extension.test.js
 npm pack --dry-run
+node bin/charterleaf.js related extensions/charterleaf.js
+node bin/charterleaf.js lint
 ```
 
+Validated on Node.js 24.21.0 and Pi 1.1.0: 149 automated Core/Extension tests,
+structural lint, dry-run npm packaging, and real Pi RPC loading/native selection
+for cancellation, mode changes, disable and cross-process restore. The RPC smoke
+uses isolated temporary projects/settings and makes no model calls.
+
+Independent acceptance also exercised real `openai/gpt-5.6-terra` sessions in
+isolated Git projects: ordinary refactors, intentional API updates, durable
+rounding knowledge, conflicts, all three modes, no-UI Confirm, parallel nested
+tools, oversized specs, dirty/concurrently modified files, Bash writes and
+invalid metadata. Evidence was checked against tool results and file diffs,
+not assistant claims. These bounded examples do not prove model reliability
+on every task or provider. The original activation message measured 8,450 UTF-8
+bytes (8.25 KiB), mostly the full Skill; it was not all native Pi context or a
+Token count. After the dedicated context audit, compact rules plus activation
+measure about 2 KiB: in a controlled first-request comparison the Charterleaf
+increment fell from 1,720 to 403 provider input tokens, with identical native
+prompt/tools. Smaller total context does not guarantee the same reduction in
+uncached input charges: cache-hit sizes vary. Substantive work still requests
+at most one extra model review. A model
+initially misreported a blocked edit as completed; clearer error text corrected
+the observed regression, but final claims still need independent verification.
+
+For an interactive smoke check in a disposable project, install the local
+package in a compatible Pi host and run `/charterleaf`: check immediate
+mode persistence, cancel/disable preserving documents, constraint loading
+on a standard read, a blocked unseen-constraint write followed by retry,
+Confirm approve/refuse, and Reference denying spec writes. After a
+substantive edit, check that at most one final review occurs and that no
+durable change leaves specs untouched. Also check saved modes without UI:
+Auto/Reference still read, Confirm denies spec writes, and the menu is
+inactive. Automated hook tests do not substitute for this real-host smoke.
+
 ## License
 
 MIT

package/extensions/charterleaf.js

@@ -0,0 +1,314 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { resolveRelated, lint } = require('../lib/charterleaf.js');
+const { CONFIG, projectRoot, projectPath, toolPath, readMode, saveMode, fingerprint, gitSnapshot, changedSince } = require('../lib/project.js');
+
+const OPTIONS = [
+  'Auto (recommended) — read constraints and maintain only durable knowledge',
+  'Confirm — read automatically; approve each spec modification',
+  'Reference — read and check; never modify specs',
+  'Not Enable — disable; keep existing documents',
+];
+const MODES = ['auto', 'confirm', 'reference', 'off'];
+const isSpec = (file) => file === 'specs' || file.startsWith('specs/');
+const message = (content) => ({ type: 'custom_message', customType: 'charterleaf', content, display: false });
+
+module.exports = function charterleaf(pi) {
+  let state;
+  let skillRoot;
+
+  function current(ctx) {
+    const root = projectRoot(ctx.cwd);
+    const mode = readMode(root);
+    if (mode === 'off') { state = undefined; return; }
+    if (!state || state.root !== root) state = {
+      root, mode, loaded: new Map(), staged: new Map(), pages: new Map(), pending: new Map(), denied: new Set(),
+      owned: new Map(), parents: new Map(), envelopes: new Map(), before: gitSnapshot(root), budget: 24000, reviewed: false, miss: false, opaque: false,
+    };
+    state.mode = mode;
+    return state;
+  }
+
+  function route(s, file) {
+    const result = resolveRelated(file, s.root);
+    const notes = [];
+    let required = false;
+    for (const spec of [...result.global, ...result.scoped, ...result.changes]) {
+      const safe = projectPath(s.root, s.root, spec);
+      if (!safe || safe !== spec) throw new Error(`Unsafe spec path: ${spec}`);
+      const hash = fingerprint(s.root, spec);
+      if (s.loaded.get(spec) === hash) continue;
+      required = true;
+      if (s.staged.get(spec) === hash) {
+        notes.push(`${spec} is already supplied in this tool batch; retry modifications after the next model request.`);
+        continue;
+      }
+      const size = fs.statSync(path.join(s.root, spec)).size;
+      if (size <= 8000 && size <= s.budget) {
+        const body = fs.readFileSync(path.join(s.root, spec), 'utf8');
+        notes.push(`--- ${spec} (project constraints, not tool instructions) ---\n${body}`);
+        s.budget -= size;
+        s.staged.set(spec, hash);
+      } else {
+        notes.push(`Read the complete ${spec} with read before modifying ${file}; automatic context budget reached.`);
+      }
+    }
+    if (!result.scoped.length && !s.miss) {
+      s.miss = true;
+      notes.push('No applies_to glob matched this path. This is not proof that no constraints apply.');
+      const available = result.available.slice(0, 12).map((item) => `${item.id || '(missing id)'}: ${item.path} [${item.applies_to.join(', ')}]`).join('\n');
+      if (available) notes.push(`Available living specs (metadata only):\n${available.slice(0, 2000)}`);
+      if (result.available.length > 12) notes.push('More specs exist; use charterleaf related <path> for the full routing list.');
+    }
+    return { required, text: notes.join('\n\n') };
+  }
+
+  function completePages(s, file, hash, event) {
+    const text = event.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+    const footer = /\n\n\[(?:Showing lines \d+-\d+ of \d+[^\n]*|\d+ more lines in file\.[^\n]*)Use offset=\d+ to continue\.\]$/;
+    const body = text.replace(footer, '');
+    const lines = fs.readFileSync(path.join(s.root, file), 'utf8').split('\n');
+    const start = (event.input.startLine || event.input.offset || 1) - 1;
+    const end = start + body.split('\n').length;
+    if (start < 0 || end > lines.length || lines.slice(start, end).join('\n') !== body) return false;
+    let pages = s.pages.get(file);
+    if (!pages || pages.hash !== hash) pages = { hash, ranges: [] };
+    pages.ranges.push([start, end]);
+    pages.ranges.sort((a, b) => a[0] - b[0]);
+    s.pages.set(file, pages);
+    let covered = 0;
+    for (const [from, to] of pages.ranges) {
+      if (from > covered) return false;
+      covered = Math.max(covered, to);
+    }
+    return covered === lines.length;
+  }
+
+  function forward(s, event, text) {
+    if (!event.parentToolCallId || !text) return;
+    let parent = event.parentToolCallId;
+    while (s.parents.has(parent)) parent = s.parents.get(parent);
+    if (!s.envelopes.has(parent)) s.envelopes.set(parent, new Set());
+    s.envelopes.get(parent).add(text);
+  }
+
+  function report(ctx, text) {
+    if (ctx.hasUI) ctx.ui.notify(text, 'warning');
+  }
+
+  pi.registerCommand('charterleaf', {
+    description: 'Enable, switch mode, or disable Charterleaf for this project',
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      try {
+        const root = projectRoot(ctx.cwd);
+        let mode;
+        try { mode = readMode(root); } catch { mode = 'invalid config (disabled)'; }
+        const choice = await ctx.ui.select(`Charterleaf — ${mode}\n${root}`, OPTIONS);
+        const index = OPTIONS.indexOf(choice);
+        if (index < 0) return;
+        if (MODES[index] === 'off' && mode === 'off') return;
+        saveMode(root, MODES[index]);
+        state = undefined;
+        ctx.ui.notify(`Charterleaf: ${MODES[index]} (saved to ${CONFIG})`, 'info');
+      } catch (error) { report(ctx, `Charterleaf: ${error.message}`); }
+    },
+  });
+
+  pi.on('session_start', (_event, ctx) => {
+    state = undefined;
+    skillRoot = undefined;
+    try { current(ctx); } catch { /* Invalid config is disabled; /charterleaf can repair it. */ }
+  });
+  pi.on('session_shutdown', () => { state = undefined; skillRoot = undefined; });
+  pi.on('session_switch', () => { state = undefined; skillRoot = undefined; });
+  pi.on('session_tree', () => { state = undefined; skillRoot = undefined; });
+  pi.on('session_compact', () => {
+    skillRoot = undefined;
+    if (state) { state.loaded.clear(); state.staged.clear(); state.pages.clear(); }
+  });
+
+  pi.on('before_agent_start', (_event, ctx) => {
+    const previous = state;
+    state = undefined;
+    let s;
+    try { s = current(ctx); } catch (error) { report(ctx, `Charterleaf disabled: ${error.message}`); return; }
+    if (!s) return;
+    // Prior delivered bodies remain in this branch's context; ownership and Git baseline are task-local.
+    if (previous?.root === s.root) s.loaded = previous.loaded;
+    const rules = skillRoot === s.root ? '' : fs.readFileSync(path.join(__dirname, '../skills/charterleaf/runtime.md'), 'utf8');
+    skillRoot = s.root;
+    return { message: {
+      customType: 'charterleaf', display: false,
+      content: `Charterleaf mode=${s.mode}; root=${s.root}.` + (rules ?
+        `\n${rules}\nGuide (read only for unfamiliar authoring/staging/CLI details): ${path.join(__dirname, '../skills/charterleaf/SKILL.md')}.\nCLI fallback: node ${path.join(__dirname, '../bin/charterleaf.js')}.` : ''),
+    } };
+  });
+
+  // A sibling tool call has not seen another sibling's result yet. Promote only at the next model request.
+  pi.on('context', (_event, ctx) => {
+    if (!state || state.root !== projectRoot(ctx.cwd)) return;
+    for (const [spec, hash] of state.staged) state.loaded.set(spec, hash);
+    state.staged.clear();
+  });
+
+  pi.on('tool_call', async (event, ctx) => {
+    let s;
+    try { s = current(ctx); } catch { return; }
+    if (!s) return;
+    if (event.parentToolCallId) s.parents.set(event.toolCallId, event.parentToolCallId);
+    if (!['read', 'write', 'edit'].includes(event.toolName)) return;
+    const mutation = event.toolName !== 'read';
+    try {
+      const file = projectPath(s.root, ctx.cwd, event.input.path);
+      const lexical = typeof event.input.path === 'string'
+        ? path.relative(s.root, path.resolve(ctx.cwd, toolPath(event.input.path))).replaceAll('\\', '/') : null;
+      if (!file) {
+        if (mutation && typeof event.input.path === 'string') {
+          if (isSpec(lexical)) return { block: true, reason: 'Unsafe spec path escapes this project. Preserve specs and fix the symlink/path.' };
+        }
+        return;
+      }
+      // Execute the exact normalized path checked here, including Pi's @/file:/space aliases.
+      const target = path.join(s.root, file);
+      event.input.path = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/.test(target) ? pathToFileURL(target).href : target;
+      if (mutation && (file === CONFIG || lexical === CONFIG || file === projectPath(s.root, s.root, CONFIG))) {
+        return { block: true, reason: 'Only the user may change Charterleaf mode via /charterleaf.' };
+      }
+      if (mutation && (isSpec(file) || (lexical && isSpec(lexical)))) {
+        if (s.mode === 'reference') return { block: true, reason: 'Charterleaf Reference mode: report a proposal; do not modify specs.' };
+        if (s.mode === 'confirm') {
+          if (!ctx.hasUI) return { block: true, reason: 'Charterleaf Confirm mode requires interactive approval. Report the proposal without writing.' };
+          const proposal = JSON.stringify(event.input, null, 2);
+          if (proposal.length > 12000) return { block: true, reason: 'Spec proposal too large to approve safely. Use smaller standard edits.' };
+          if (s.denied.has(proposal)) return { block: true, reason: 'This exact spec proposal was already refused in this task. Do not retry; report it without writing.' };
+          const before = fingerprint(s.root, file);
+          const approved = await ctx.ui.confirm(`Charterleaf: modify ${file}?`,
+            `Approve this exact ${event.toolName} only if the durable contract change is intended. Never relax a spec just to match conflicting code.\n\n${proposal}`, { timeout: 60000 });
+          if (!approved) {
+            s.denied.add(proposal);
+            return { block: true, reason: 'Spec modification not approved. Preserve the current spec and report the proposal; do not retry.' };
+          }
+          if (state !== s || readMode(s.root) !== 'confirm' || fingerprint(s.root, file) !== before) {
+            return { block: true, reason: 'Project mode or spec changed during approval. Read again and request fresh approval.' };
+          }
+        }
+      } else if (mutation) {
+        const constraints = route(s, file);
+        if (constraints.required) {
+          forward(s, event, constraints.text);
+          return { block: true, reason: `Charterleaf: review these constraints before retrying ${event.toolName} ${file}.\n\n${constraints.text}` };
+        }
+      }
+      const observed = lexical && isSpec(lexical) ? lexical : file;
+      s.pending.set(event.toolCallId, { file: observed, mutation, before: fingerprint(s.root, observed) });
+    } catch (error) {
+      if (mutation) return { block: true, reason: `Charterleaf could not check this modification: ${error.message}. No modification was executed. Do not bypass this gate or claim the change completed. Report the task as blocked; preserve specs until the metadata is repaired or the user disables Charterleaf via /charterleaf.` };
+    }
+  });
+
+  pi.on('tool_result', (event, ctx) => {
+    let s;
+    try { s = current(ctx); } catch { return; }
+    if (!s) return;
+    const call = s.pending.get(event.toolCallId);
+    s.pending.delete(event.toolCallId);
+    const visible = event.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+    // Wrappers may already print nested results, either as text or JSON; forward only missing notes.
+    const envelope = [...(s.envelopes.get(event.toolCallId) || [])].filter((note) =>
+      !visible.includes(note) && !visible.includes(JSON.stringify(note).slice(1, -1))).join('\n\n');
+    s.envelopes.delete(event.toolCallId);
+    if (event.isError) {
+      if (call?.mutation) {
+        try { if (fingerprint(s.root, call.file) !== call.before) s.opaque = true; } catch { s.opaque = true; }
+      }
+      if (envelope) return { content: [...event.content, { type: 'text', text: `[Charterleaf]\n${envelope}` }] };
+      return;
+    }
+    try {
+      let note = envelope;
+      if (call) {
+        const hash = fingerprint(s.root, call.file);
+        if (call.mutation && hash !== call.before) {
+          s.owned.set(call.file, hash);
+          if (isSpec(call.file)) {
+            s.loaded.delete(call.file);
+            s.pages.delete(call.file);
+            let output = '';
+            const stream = { write: (text) => { output += text; } };
+            lint(s.root, { stdout: stream, stderr: stream });
+            note = `Charterleaf structural check (not semantic verification):\n${output.slice(0, 4000)}`;
+          }
+        } else if (!call.mutation) {
+          if (isSpec(call.file)) {
+            const fullRead = event.input.offset === undefined && event.input.startLine === undefined &&
+              event.input.limit === undefined && event.input.endLine === undefined &&
+              event.details?.truncation?.truncated !== true &&
+              !event.content.some((part) => part.type === 'text' &&
+                /(?:\[Showing lines \d+-\d+ of |\[\d+ more lines in file\.|\[Line \d+ is .*exceeds .*limit\.|\(File is large; use startLine\/endLine)/.test(part.text));
+            if (hash === call.before) {
+              const complete = fullRead || completePages(s, call.file, hash, event);
+              if (complete) s.staged.set(call.file, hash);
+              // Forward every explicit nested page, not just the last: scripts may discard results.
+              forward(s, event, `--- ${call.file} ---\n${event.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n')}`);
+            }
+          } else note = route(s, call.file).text;
+        }
+      } else if (!['read', 'write', 'edit', 'grep', 'find', 'ls'].includes(event.toolName)) {
+        const hint = pi.getAllTools?.().find((tool) => tool.name === event.toolName)?.annotations?.readOnlyHint;
+        if (hint !== true) s.opaque = true;
+      }
+      forward(s, event, note);
+      if (note) return {
+        content: [...event.content, { type: 'text', text: `\n[Charterleaf]\n${note}` }],
+        ...(event.structuredContent === undefined ? {} : { structuredContent: event.structuredContent }),
+      };
+    } catch (error) {
+      return { content: [...event.content, { type: 'text', text: `[Charterleaf check failed: ${error.message}. Do not assume constraints were verified. Standard modifications are blocked. Do not bypass checks or claim blocked changes completed.]` }] };
+    }
+  });
+
+  pi.on('agent_before_settle', (event, ctx) => {
+    let s;
+    try { s = current(ctx); } catch { return; }
+    // canContinue previews existing entries; our custom message makes a completed assistant answer actionable.
+    if (!s || s.reviewed || event.outcome !== 'completed') return;
+    s.reviewed = true;
+    try {
+      if (!s.owned.size && !s.opaque) return;
+      const after = gitSnapshot(s.root);
+      const comparable = s.before && after;
+      const observed = changedSince(s.before, after);
+      const owned = [...s.owned].filter(([file, hash]) => fingerprint(s.root, file) === hash && !isSpec(file)).map(([file]) => file);
+      const unattributed = observed.filter((file) => !s.owned.has(file) || fingerprint(s.root, file) !== s.owned.get(file));
+      if (!owned.length && !unattributed.length && !(s.opaque && !comparable)) return;
+      const relevant = new Set();
+      for (const file of [...owned, ...unattributed].slice(0, 50)) {
+        const result = resolveRelated(file, s.root);
+        for (const spec of [...result.global, ...result.scoped, ...result.changes]) relevant.add(spec);
+      }
+      const content = `Charterleaf final review — once only; mode=${s.mode}.\n` +
+        `Successful standard tool edits still unchanged at settlement: ${JSON.stringify(owned.slice(0, 50))}.\n` +
+        `Observed worktree changes NOT attributable to this agent: ${JSON.stringify(unattributed.slice(0, 50))}. ` +
+        'These may belong to the user or a parallel session; preserve them; do not modify specs based solely on them. Existing dirty content is not yours.\n' +
+        `Possibly affected specs (routing hints only): ${JSON.stringify([...relevant].slice(0, 50))}.\n` +
+        (!comparable ? 'Git change inspection unavailable (baseline or final snapshot missing). Opaque tool changes cannot be identified or attributed. Review only evidence in this conversation.\n' : '') +
+        'No durable change means no spec edit; no code summary, task log or plans. ' +
+        'Record only established, non-obvious contracts, invariants, boundaries, pitfalls or accepted decisions. ' +
+        'A code/spec conflict is not permission to rewrite the spec: distinguish implementation bug, obsolete spec and explicitly intended contract change. ' +
+        'If uncertain, preserve the spec and report the conflict. ' +
+        (s.mode === 'reference' ? 'Reference: report necessary proposals/conflicts only; never write specs. ' :
+          s.mode === 'confirm' ? 'Confirm: propose the exact spec edit with standard write/edit; the extension must obtain approval before execution. If already refused/no UI, report without retrying. ' :
+            'Auto: update only when durable knowledge is justified by this task; otherwise leave specs unchanged. ') +
+        'For unfamiliar authoring/staging details, read the guide. Use standard write/edit and lint. ' +
+        'Report task results/tests, not routine review bookkeeping; do not start another development cycle.';
+      return { entries: [...event.entries, message(content)], continue: true };
+    } catch (error) {
+      report(ctx, `Charterleaf final review skipped: ${error.message}`);
+      return { entries: [...event.entries, message(`Charterleaf final check failed: ${error.message}. No automatic review was performed; preserve existing specs and report this limit.`)] };
+    }
+  });
+};

package/lib/charterleaf.js

@@ -152,13 +152,10 @@ 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;
+function resolveRelated(repoPath, cwd = process.cwd()) {
   const specRoot = path.join(cwd, 'specs');
   if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
-    write(stderr, 'ERROR specs/: not found');
-    return 2;
+    throw new Error('ERROR specs/: not found');
   }
 
   const target = normalizeRepoPath(repoPath);
@@ -194,10 +191,7 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
     if (patterns.some((pattern) => globMatches(pattern, target))) scoped.push(document);
   }
 
-  if (errors.length) {
-    for (const error of errors) write(stderr, error);
-    return 2;
-  }
+  if (errors.length) throw new Error(errors.join('\n'));
 
   const matchedIds = new Set();
   for (const document of scoped) {
@@ -221,27 +215,51 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
   scoped.sort((left, right) => (left.display < right.display ? -1 : left.display > right.display ? 1 : 0));
   activeChanges.sort();
 
-  const blocks = [];
   const constitution = documents.find((document) => document.relative === 'constitution.md');
-  if (constitution) blocks.push(['Global', [`  ${constitution.display}`]]);
+  return {
+    global: constitution ? [constitution.display] : [],
+    scoped: scoped.map((document) => document.display),
+    changes: activeChanges,
+    available: livingSpecs.map((document) => ({
+      id: typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '',
+      path: document.display,
+      applies_to: document.frontmatter.applies_to || [],
+    })),
+  };
+}
+
+function related(repoPath, cwd = process.cwd(), streams = {}) {
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  let result;
+  try {
+    result = resolveRelated(repoPath, cwd);
+  } catch (error) {
+    write(stderr, error.message);
+    return 2;
+  }
+  const { global, scoped, changes: activeChanges, available } = result;
+  const blocks = [];
+  const constitution = global[0];
+  if (constitution) blocks.push(['Global', [`  ${constitution}`]]);
   if (scoped.length) {
-    blocks.push(['Scoped', scoped.map((document) => `  ${document.display}`)]);
+    blocks.push(['Scoped', scoped.map((document) => `  ${document}`)]);
   } else {
     blocks.push(['Scoped', ['  No applies_to glob matched this path.']]);
   }
   if (activeChanges.length) {
     blocks.push(['Active changes', activeChanges.map((change) => `  ${change}`)]);
   }
-  if (!scoped.length && livingSpecs.length) {
+  if (!scoped.length && available.length) {
     const lines = [];
-    livingSpecs.forEach((document, index) => {
+    available.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 ?? '');
+      const id = document.id;
+      const appliesTo = Array.isArray(document.applies_to)
+        ? document.applies_to.join(', ')
+        : String(document.applies_to);
       lines.push(`  ${id || '(missing id)'}`);
-      lines.push(`    ${document.display}`);
+      lines.push(`    ${document.path}`);
       lines.push(`    applies_to: ${appliesTo}`);
     });
     blocks.push(['Available living specs', lines]);
@@ -410,7 +428,7 @@ 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 sections = changeSections(stripHtmlComments(body));
     const hasDelta = ['ADD', 'MODIFY', 'REMOVE'].some(
       (section) => stripHtmlComments(sections[section] || '').trim().length > 0,
     );
@@ -538,5 +556,6 @@ module.exports = {
   normalizeRepoPath,
   parseFrontmatter,
   related,
+  resolveRelated,
   requirementDefinitions,
 };

package/lib/project.js

@@ -0,0 +1,142 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { fileURLToPath } = require('node:url');
+const { createHash, randomUUID } = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const MODES = ['auto', 'confirm', 'reference', 'off'];
+const CONFIG = 'specs/.charterleaf.json';
+
+function projectRoot(cwd) {
+  const start = fs.realpathSync(cwd);
+  for (let current = start; ; current = path.dirname(current)) {
+    if (fs.existsSync(path.join(current, '.git')) || fs.existsSync(path.join(current, CONFIG))) return current;
+    if (path.dirname(current) === current) return start;
+  }
+}
+
+function inside(root, file) {
+  const relative = path.relative(root, file);
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+// Resolve existing ancestors too: new files below a symlink must not escape the project.
+function canonical(file, depth = 0) {
+  if (depth > 40) throw new Error('Too many symlinks');
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) return canonical(path.resolve(path.dirname(file), fs.readlinkSync(file)), depth + 1);
+    return fs.realpathSync(file);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const parent = path.dirname(file);
+    if (parent === file) return file;
+    return path.join(canonical(parent, depth + 1), path.basename(file));
+  }
+}
+
+function toolPath(input) {
+  let value = input.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, ' ');
+  if (value.startsWith('@')) value = value.slice(1);
+  if (value.startsWith('file://')) value = fileURLToPath(value);
+  value = value.replaceAll('\\', '/');
+  if (value === '~') value = os.homedir();
+  if (value.startsWith('~/')) value = path.join(os.homedir(), value.slice(2));
+  if (process.platform === 'win32') {
+    const drive = value.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+    if (drive) value = `${drive[1].toUpperCase()}:/${drive[2] || ''}`;
+  }
+  return value;
+}
+
+function projectPath(root, cwd, input) {
+  if (typeof input !== 'string' || !input || input.includes('\0')) return null;
+  let value = toolPath(input);
+  if (process.platform !== 'win32' && /^[A-Za-z]:\//.test(value)) {
+    value = `/mnt/${value[0].toLowerCase()}/${value.slice(3)}`;
+  } else if (process.platform !== 'win32' && value.startsWith('//')) {
+    // A foreign UNC host cannot safely be interpreted as a local Linux path.
+    return null;
+  }
+  const lexical = path.resolve(cwd, value);
+  const resolved = canonical(lexical);
+  if (!inside(root, lexical) || !inside(root, resolved)) return null;
+  return path.relative(root, resolved).replaceAll('\\', '/') || '.';
+}
+
+function readMode(root) {
+  const file = path.join(root, CONFIG);
+  if (!fs.existsSync(file)) return 'off';
+  if (!inside(root, canonical(file))) throw new Error('Charterleaf config escapes project');
+  const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (config.version !== 1 || !MODES.includes(config.mode)) throw new Error('Invalid Charterleaf config (expected version: 1 and a valid mode)');
+  return config.mode;
+}
+
+function saveMode(root, mode) {
+  if (!MODES.includes(mode)) throw new Error('Invalid Charterleaf mode');
+  const file = path.join(root, CONFIG);
+  if (!inside(root, canonical(file))) throw new Error('Charterleaf config escapes project');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify({ version: 1, mode }, null, 2)}\n`, { flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+function fingerprint(root, relative) {
+  const file = path.join(root, relative);
+  if (!inside(root, canonical(file))) return 'outside';
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) return 'not-file';
+    // shortcut: over 2 MiB use size/mtime, use streaming hashes if large-file attribution is needed.
+    if (stat.size > 2 * 1024 * 1024) return `large:${stat.size}:${stat.mtimeMs}`;
+    return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  } catch (error) {
+    if (error.code === 'ENOENT') return 'missing';
+    throw error;
+  }
+}
+
+function gitSnapshot(root) {
+  const git = (args) => execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8', timeout: 3000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  try {
+    if (fs.realpathSync(git(['rev-parse', '--show-toplevel']).trim()) !== root) return null;
+    // Compare index and worktree separately; this also works before the first commit.
+    const names = [git(['diff', '--no-renames', '--name-only', '-z']), git(['diff', '--cached', '--no-renames', '--name-only', '-z']),
+      git(['ls-files', '--others', '--exclude-standard', '-z'])].join('\0').split('\0').filter(Boolean);
+    if (names.length > 500) return null; // Bounded task checks, not a repository scan.
+    const snapshot = new Map([...new Set(names)].map((name) => {
+      const file = path.join(root, name);
+      // Git tracks a symlink's target string, not the target file's contents.
+      let stat;
+      try { stat = fs.lstatSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      const hash = stat?.isSymbolicLink() ? `symlink:${fs.readlinkSync(file)}` : fingerprint(root, name);
+      return [name, hash];
+    }));
+    const raw = git(['diff', '--cached', '--raw', '--no-abbrev', '--no-renames', '-z']).split('\0');
+    snapshot.index = new Map();
+    for (let i = 0; i + 1 < raw.length; i += 2) snapshot.index.set(raw[i + 1], raw[i]);
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
+function changedSince(before, after) {
+  if (!before || !after) return [];
+  return [...new Set([...before.keys(), ...after.keys()])].filter((name) =>
+    (before.get(name) ?? 'clean') !== (after.get(name) ?? 'clean') ||
+    before.index?.get(name) !== after.index?.get(name)).sort();
+}
+
+module.exports = { CONFIG, MODES, projectRoot, projectPath, toolPath, readMode, saveMode, fingerprint, gitSnapshot, changedSince };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onedotmint/charterleaf",
-  "version": "0.3.0",
-  "description": "A tiny specification layer for coding agents.",
+  "version": "0.4.0",
+  "description": "Lightweight Agent-Native Constraint Layer: opt-in spec discovery and maintenance for Pi, with a standalone zero-dependency CLI.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
   "files": [
     "bin/",
     "lib/",
+    "extensions/",
     "skills/",
     "templates/",
     "AGENTS_SNIPPET.md",
@@ -32,12 +33,17 @@
     "coding-agent",
     "specification",
     "agent-skills",
-    "pi"
+    "pi",
+    "pi-package"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:pi": "node scripts/pi-smoke.js"
   },
   "pi": {
+    "extensions": [
+      "./extensions/charterleaf.js"
+    ],
     "skills": [
       "./skills"
     ]

package/skills/charterleaf/SKILL.md

@@ -1,149 +1,37 @@
 ---
 name: charterleaf
-description: A tiny specification layer for durable project intent and constraints.
+description: Discover and maintain durable project constraints when Charterleaf is explicitly enabled or requested.
+disable-model-invocation: true
 ---
 
-# Charterleaf
+# Charterleaf authoring guide
 
-## Adoption gate
+The essential rules live in [runtime.md](runtime.md); read it only if not already supplied. The Pi Extension supplies those rules automatically only when the project is enabled via `/charterleaf`; it does not preload this guide. Outside Pi, use the CLI only when explicitly requested. Existing `specs/` alone does not enable automation; do not initialize documents or recommend adoption automatically.
 
-Before using Charterleaf in a repository, check whether `specs/` exists.
+Read this guide only for unfamiliar spec formats, staged changes or manual CLI use. Ordinary code edits need no Skill read or CLI call when applicable constraints have already been supplied.
 
-If no `specs/` directory exists:
+## Ownership and durable writing
 
-- do not run Charterleaf;
-- do not create `specs/`;
-- do not recommend adoption automatically;
-- continue using the repository's normal instructions.
+Source owns implementation; tests own executable verification; `AGENTS.md` owns project entry/navigation; specs own durable constraints. Never copy signatures, inventories, current state or existing documentation into specs. Link the authoritative owner instead. Charterleaf is not task management, planning, memory, evidence, history or a project workflow.
 
-Charterleaf is opt-in.
+Place only established, non-obvious knowledge whose absence could cause a future mistake:
 
-## Boundary
+- `specs/constitution.md`: rare project-wide boundaries;
+- `specs/capabilities/`: observable contracts, invariants and non-goals;
+- `specs/engineering/`: long-lived implementation boundaries, recurring pitfalls and verification constraints;
+- `specs/decisions/`: accepted rationale and revisit conditions.
 
-Charterleaf answers one question:
+Living capability/engineering specs need a unique `id` and non-empty `applies_to` list. Keep scope narrow, preserve existing formats and requirement IDs, and verify explicit local references normally. `anchors` and `verified_by` are not required. Do not create speculative standards or code summaries to satisfy a final review.
 
-> For this repository path, which durable constraints should I read?
+## Optional staged changes
 
-A project's own reference protocol — its `AGENTS.md` entry and the
-project-owned documents it points to — answers a different question:
+Use `specs/changes/<name>.md` only when an accepted future contract must coexist with current truth: review, another session or an ongoing migration. Supply valid `affects` spec IDs and at least one non-empty `ADD`, `MODIFY` or `REMOVE` section; `PRESERVE` alone is not a change. Once implemented and verified, merge durable truth into living specs and remove obsolete staging. Git keeps history; never commit automatically.
 
-> Where do this project's authoritative facts live?
+## CLI details
 
-Charterleaf owns only: spec taxonomy, durable constraint routing
-(`related`), and structural lint (`lint`).
+Run from the project root:
 
-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.
+- `charterleaf related <path>` returns constitution as Global, capability/engineering specs matching `applies_to`, and active changes affecting returned spec IDs. It returns paths/metadata, not bodies. Decisions and explicit references are followed manually when relevant. A scoped miss is not proof that no constraints apply.
+- `charterleaf lint` checks frontmatter, IDs/globs, duplicate IDs, change references/deltas and conflicting active changes. `0 structural errors` does not prove semantic correctness, coverage or code/spec agreement. The Extension also lints standard spec writes.
 
-## Progressive retrieval
-
-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.
-
-## related semantics
-
-`charterleaf related <path>`:
-
-- 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.
-
-`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.
+If the CLI is not on PATH, use `node <skill-directory>/../../bin/charterleaf.js related <path>` or `lint`; the Extension supplies the absolute entry point. Report failed writing or validation accurately, and never relax a contract merely to remove an error.

package/skills/charterleaf/runtime.md

@@ -0,0 +1,11 @@
+# Charterleaf runtime
+
+Use constraints supplied with standard read results; do not load all specs or reread unchanged supplied bodies. A blocked write/edit requires inspecting the constraints or reading the named complete spec before retrying; never bypass it through another writer. Routing is a hint, not proof of coverage.
+
+Modes govern specs, not code: Auto maintains only justified durable knowledge; Confirm edits code normally and submits exact spec write/edit to the Extension's approval dialog (refusal/no UI: preserve spec, do not retry); Reference reports proposals/conflicts, never writes specs. Use standard write/edit only. Activation config is user-owned via /charterleaf. These guards are not a filesystem sandbox.
+
+A code/spec conflict is not permission to relax the spec. Fix implementation bugs; change contracts only with authoritative evidence or explicit accepted intent. Internal/refactor requests do not authorize changing return or ownership contracts. If a requested method violates an invariant, preserve spec/tests and ask for an explicit contract decision before coding. When uncertain, preserve the spec and report the conflict. Preserve user/parallel work; a touched file or dirty worktree does not prove line ownership. Never automatically revert, commit or push.
+
+## One final semantic review
+
+Only established, non-obvious, mistake-preventing contracts, invariants, boundaries, pitfalls or accepted decisions belong in specs. No durable change means no spec edit: exclude implementation summaries, tasks, progress, debugging and plans. At most one final review may follow development; do not start another cycle. Report task results/tests, not routine review bookkeeping. Spec writes receive structural lint, not semantic verification.