@onedotmint/charterleaf 0.4.1 → 0.4.3

package/AGENTS_SNIPPET.md

@@ -11,10 +11,21 @@ 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.
+Reference or Not Enable through `/charterleaf`. In Git, the saved mode lives in
+`charterleaf.json` under `git rev-parse --path-format=absolute --git-common-dir`
+(usually `.git/charterleaf.json`), shared by all branches and linked worktrees,
+not independent clones. Outside Git, it remains `specs/.charterleaf.json`.
+The local config is authoritative, including saved `off`; a branch's legacy config
+cannot override it. Only when local config is absent may first load import a valid
+saved mode from current-branch legacy `specs/.charterleaf.json`, without overwriting local
+config or changing the legacy file/worktree. Invalid config means an error and
+disabled automation; never recover lost authorization from Git history or sessions.
+No saved choice means off, not a global Auto default: no automatic scan, adoption
+prompt or document creation. Enabling Git projects creates no `specs/` directory or
+documents; a branch without specs remains usable for normal reads/edits and later
+justified spec creation under the selected mode. Specs route from the current
+worktree, not the shared config directory. Do not change activation config on the
+user's behalf.
 
 For manual use on a concrete repository path, run from the project root:
 

package/README.md

@@ -39,7 +39,7 @@ pi install npm:@onedotmint/charterleaf
 For the standalone CLI, use `npm install -g @onedotmint/charterleaf`.
 For local development, use `pi install /absolute/path/to/charterleaf` (a package
 directory, not a `.tgz` file). To test the CLI from a local package, run `npm pack`
-then `npm install -g ./onedotmint-charterleaf-0.4.1.tgz`.
+then `npm install -g ./onedotmint-charterleaf-0.4.3.tgz`.
 
 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
@@ -51,14 +51,17 @@ 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`:
+`@earendil-works/pi-coding-agent` **1.1.0 and 1.4.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:
+Run `/charterleaf` in Pi for the native project mode menu. It distinguishes
+**not configured** from explicitly **disabled**, explains that existing specs do
+not enable automation, and describes the current mode. Saving confirms what the
+selected mode allows, not just where its config was written:
 
 | Choice | Behavior |
 | --- | --- |
@@ -67,20 +70,35 @@ Run `/charterleaf` in Pi for the native project mode menu:
 | **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`:
+The choice is saved immediately in `charterleaf.json` under the absolute directory
+returned by `git rev-parse --path-format=absolute --git-common-dir` (usually
+`.git/charterleaf.json`). All branches and linked worktrees of that repository
+share the mode; independent clones do not. Outside Git, the path remains
+`specs/.charterleaf.json`. The config format is unchanged:
 
 ```json
 { "version": 1, "mode": "off" }
 ```
 
-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.
+Valid modes are `auto`, `confirm`, `reference`, and `off`. The new repository-local
+config is authoritative whenever it exists, including saved `off`; a branch's
+legacy `specs/.charterleaf.json` cannot override it. If no local config exists,
+the first load imports the saved mode from a valid legacy config on the current branch,
+without overwriting a local config or changing/removing the legacy file or tracked
+worktree. Invalid config reports an error and disables automation, not a fallback
+to another source. Lost authorization is never recovered from Git history or sessions.
+
+With no saved choice, the mode stays **off**; existing `specs/` alone never enables
+automation. This is repository-local opt-in, **not a global Auto default**.
+Activation is an explicit user choice through `/charterleaf`, not an Agent decision.
+Enabling a Git project creates only the local config, never a `specs/` directory or
+spec documents. A branch without `specs/` is valid: normal code reads/edits and later
+evidence-based spec creation still work under the selected mode. Spec content and
+routing always belong to the current worktree, not the shared Git directory.
+Outside Git, saving may create the `specs/` directory for the config only.
+Disabling preserves documents; cancel changes nothing. Disabled/unconfigured
+projects get no automatic adoption prompt, task context, scan, or document bootstrap.
+The two manual CLI commands remain unchanged and 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
@@ -109,9 +127,11 @@ 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
+knowledge. Native Pi raw pages and AFT numbered pages (offset/limit or
+startLine/endLine) are credited only when their exact content covers the same
+spec version with no gaps; AFT line labels must be sequential and correct.
+Display newlines and CRLF line endings do not prevent complete-read credit;
+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.
@@ -130,8 +150,9 @@ again. This is task-local bookkeeping, not a watcher or persistent index.
 
 Knowledge capture happens **during normal work**, not just after code changes:
 development, debugging, substantive code/test/architecture investigation and
-accepted technical decisions can establish or uncover durable knowledge. A project
-with only `specs/.charterleaf.json` is a valid initial state. When evidence warrants
+accepted technical decisions can establish or uncover durable knowledge. An enabled
+project with no spec documents (or no `specs/` directory in Git) is a valid initial
+state. When evidence warrants
 it, the Agent creates a concise scoped spec using ordinary authorized `write`/`edit`;
 Core immediately routes its `id`/`applies_to` on later related code reads or edits.
 There is no initialization scan, document quota or adoption wizard.
@@ -185,8 +206,10 @@ workflow or another development cycle.
 
 ## CLI
 
-Charterleaf exposes exactly two deterministic commands. Run them from a
-repository root containing `specs/`:
+Charterleaf exposes exactly two deterministic commands. Run them from the project
+root or a subdirectory: the nearest ancestor containing `specs/` is used, without
+crossing a Git repository or worktree boundary. The target path remains
+repo-relative, not relative to the shell's current directory.
 
 ```bash
 charterleaf related <path>
@@ -363,7 +386,8 @@ Important limits:
    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.
+  rejected for project spec writes. Native Windows CLI, helper/Extension tests and
+  RPC mode persistence are covered by hosted CI; platform-specific permissions still apply.
 - `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
@@ -386,6 +410,7 @@ Verification commands:
 
 ```bash
 npm test
+npm run test:package  # real tarball install and tests against installed code
 npm run test:pi   # isolated real RPC/UI smoke; no model calls
 CHARTERLEAF_MODEL=deepseek/deepseek-flash npm run test:organic  # paid isolated A–G acceptance
 CHARTERLEAF_MODEL=deepseek/deepseek-flash CHARTERLEAF_BASELINE=5d470db npm run test:context  # paid comparison against v0.4.0
@@ -396,10 +421,20 @@ 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: 183 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.
+GitHub Actions runs the installed-package suite on Ubuntu and Windows with Node
+20.0.0, 22.19.0 and 24.x, plus Pi 1.1.0/1.4.0 smoke checks on host-compatible Node.
+CI makes no model calls and retains packaging/test logs. `PI_CLI` can select the
+Pi Node entry point for smoke checks without relying on platform-specific shims.
+
+For v0.4.2, the [passing eight-job release-candidate matrix](https://github.com/onedotmint/Charterleaf/actions/runs/40078816360)
+checks the actual npm tarball after isolated installation, including byte equality,
+CLI commands and Core/Extension/recovery tests. Each Ubuntu job passes all 227 tests;
+each Windows job passes 220 with zero failures and seven platform-specific skips
+(one Linux/WSL path check, two POSIX permission checks and four SIGKILL checks).
+Windows symlink tests run, rather than being skipped. Host-compatible jobs also
+pass real Pi RPC loading/native selection, cancellation, mode changes, legacy
+migration and cross-branch/process persistence. RPC checks use isolated temporary
+projects/settings and make no model calls.
 
 The 0.4.1 organic-capture acceptance used real `deepseek/deepseek-flash` sessions
 in isolated Git projects. Actual tool results, approval records, specs, routing,
@@ -407,11 +442,18 @@ file snapshots/diffs, original tests and an independent exact-money oracle were
 checked, not just assistant claims. Empty-spec development and investigation,
 ordinary-query non-triggers, authoritative-document references, bug-versus-contract
 handling, cross-session reuse and mode/read-only/no-UI permissions all have passing
-evidence. **The strict matrix was not consistently all-green:** the latest focused
+evidence. **The earlier strict matrix was not consistently all-green:** a focused
 A→F1→F2 run passed A and F1, while F2 omitted its knowledge-completion comment and
 received one redundant fallback review. Its actual routing, code behavior and
-unchanged-spec checks passed. These bounded examples do not prove model reliability
-on every task or provider, or guarantee zero redundant reviews.
+unchanged-spec checks passed. A later complete pre-0.4.2 run on the same model
+passed all 15 scenarios and 231 assertions, including F1/F2 without redundant reviews.
+The final Windows Git-root path fix was subsequently validated by cross-platform
+CI, not another paid model run. These bounded examples do not prove model reliability
+on every task or provider, or guarantee zero redundant reviews. A subsequent
+case-A rerun on `deepseek/deepseek-flash` failed knowledge-capture assertions on
+both the v0.4.2 baseline and the patch candidate: accounting tests passed, but
+the model concluded `covered` without writing a routed spec. Automatic knowledge
+capture remains model-dependent; passing structural tests does not prove it.
 
 The controlled organic-capture comparison (`scripts/context-smoke.js`) keeps cwd,
 package paths, prompt and native tools identical. On `deepseek/deepseek-flash`:

package/extensions/charterleaf.js

@@ -4,7 +4,7 @@ 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 { projectRoot, projectPath, toolPath, modeConfigPath, isModeConfig, readMode, saveMode, fingerprint, gitSnapshot, changedSince } = require('../lib/project.js');
 
 const OPTIONS = [
   'Auto (recommended) — read constraints and maintain only durable knowledge',
@@ -13,6 +13,12 @@ const OPTIONS = [
   'Not Enable — disable; keep existing documents',
 ];
 const MODES = ['auto', 'confirm', 'reference', 'off'];
+const MODE_EFFECTS = {
+  auto: 'Automatic constraint loading and code edit checks; maintain only justified durable specs.',
+  confirm: 'Automatic constraint loading and code edit checks; approve each spec modification.',
+  reference: 'Automatic constraint loading and code edit checks; never modify specs.',
+  off: 'Automation off: no automatic constraint loading or code edit checks; existing documents preserved.',
+};
 const isSpec = (file) => file === 'specs' || file.startsWith('specs/');
 const message = (content) => ({ type: 'custom_message', customType: 'charterleaf', content, display: false });
 
@@ -32,8 +38,14 @@ module.exports = function charterleaf(pi) {
     return state;
   }
 
+  function related(file, root) {
+    // Mode survives branch switches even when the new branch has no specs yet.
+    if (!fs.existsSync(path.join(root, 'specs'))) return { global: [], scoped: [], changes: [], available: [] };
+    return resolveRelated(file, root);
+  }
+
   function route(s, file) {
-    const result = resolveRelated(file, s.root);
+    const result = related(file, s.root);
     const notes = [];
     let required = false;
     for (const spec of [...result.global, ...result.scoped, ...result.changes]) {
@@ -53,7 +65,8 @@ module.exports = function charterleaf(pi) {
         s.budget -= size;
         s.staged.set(spec, hash);
       } else {
-        notes.push(`Read the complete ${spec} with read before modifying ${file}; automatic context budget reached.`);
+        const pages = Math.ceil(size / 8000);
+        notes.push(`Read the complete ${spec} (${size} bytes, ~${pages} page(s) via offset/limit) before modifying ${file}; it exceeds the ${size > 8000 ? '8 KB per-file limit' : 'per-task context budget'}.`);
       }
     }
     if (!result.scoped.length && !s.miss) {
@@ -68,12 +81,23 @@ module.exports = function charterleaf(pi) {
 
   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 footer = /\n\n(?:\[(?:Showing lines \d+-\d+ of \d+[^\n]*|\d+ more lines in file\.[^\n]*)Use offset=\d+ to continue\.\]|\(File is large; use startLine\/endLine or offset\/limit to read a section\.\))$/;
     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 end = start + body.split('\n').length;
+    if (start < 0) return false;
+    if (end > lines.length || lines.slice(start, end).join('\n') !== body) {
+      const numbered = body.split('\n');
+      // AFT adds sequential line labels and a final display newline, not file content.
+      if (numbered.at(-1) === '') numbered.pop();
+      if (!numbered.length || !numbered.every((line, i) => {
+        const match = line.match(/^ *(\d+): (.*)$/);
+        return match && Number(match[1]) === start + i + 1 && match[2] === lines[start + i]?.replace(/\r$/, '');
+      })) return false;
+      end = start + numbered.length;
+      if (end === lines.length - 1 && lines.at(-1) === '') end++;
+    }
     let pages = s.pages.get(file);
     if (!pages || pages.hash !== hash) pages = { hash, ranges: [] };
     pages.ranges.push([start, end]);
@@ -107,13 +131,19 @@ module.exports = function charterleaf(pi) {
         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 config = modeConfigPath(root);
+        const status = mode === 'off'
+          ? (fs.existsSync(config) ? 'off (disabled)' : 'off (not configured)') : mode;
+        const effect = MODE_EFFECTS[mode] || MODE_EFFECTS.off;
+        const adoption = !MODES.includes(mode) || mode === 'off'
+          ? '\nExisting specs do not enable automation; choose a mode to enable it.' : '';
+        const choice = await ctx.ui.select(`Charterleaf — ${status}\n${root}\n${effect}${adoption}`, 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');
+        ctx.ui.notify(`Charterleaf: ${MODES[index]} — ${MODE_EFFECTS[MODES[index]]} (saved to ${config})`, 'info');
       } catch (error) { report(ctx, `Charterleaf: ${error.message}`); }
     },
   });
@@ -180,6 +210,9 @@ module.exports = function charterleaf(pi) {
     if (!['read', 'write', 'edit'].includes(event.toolName)) return;
     const mutation = event.toolName !== 'read';
     try {
+      if (mutation && isModeConfig(s.root, ctx.cwd, event.input.path)) {
+        return { block: true, reason: 'Only the user may change Charterleaf mode via /charterleaf.' };
+      }
       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;
@@ -192,9 +225,6 @@ module.exports = function charterleaf(pi) {
       // 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') {
@@ -272,7 +302,8 @@ module.exports = function charterleaf(pi) {
           }
         } else if (!call.mutation) {
           if (isSpec(call.file)) {
-            const fullRead = event.input.offset === undefined && event.input.startLine === undefined &&
+            const fullRead = !/^ *\d+: /.test(visible) &&
+              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' &&
@@ -317,13 +348,13 @@ module.exports = function charterleaf(pi) {
       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));
-      const emptySpecs = s.knowledge === 'no-value' && resolveRelated('', s.root).available.length === 0;
+      const emptySpecs = s.knowledge === 'no-value' && related('', s.root).available.length === 0;
       if (s.knowledge === 'no-value' && !(emptySpecs && owned.length > 0)) return;
       const candidate = s.knowledge === 'review';
       if (!candidate && !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);
+        const result = related(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` +

package/lib/charterleaf.js

@@ -122,7 +122,8 @@ function globMatches(pattern, targetPath) {
   });
 
   source += '$';
-  return new RegExp(source).test(normalizedPath);
+  // Windows filesystems are case-insensitive, so a path's casing is not meaningful there.
+  return new RegExp(source, process.platform === 'win32' ? 'i' : '').test(normalizedPath);
 }
 
 function walkMarkdown(root) {
@@ -142,6 +143,15 @@ function walkMarkdown(root) {
   });
 }
 
+// CLI discovery must not inherit another repository's constraints.
+function resolveSpecRoot(cwd) {
+  for (let current = path.resolve(cwd); ; current = path.dirname(current)) {
+    const candidate = path.join(current, 'specs');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return current;
+    if (fs.existsSync(path.join(current, '.git')) || path.dirname(current) === current) return null;
+  }
+}
+
 function relativeDisplay(filePath, cwd) {
   const relative = path.relative(cwd, filePath);
   if (!relative.startsWith('..') && !path.isAbsolute(relative)) return relative.replaceAll('\\', '/');
@@ -153,7 +163,8 @@ function write(stream, line) {
 }
 
 function resolveRelated(repoPath, cwd = process.cwd()) {
-  const specRoot = path.join(cwd, 'specs');
+  const root = path.resolve(cwd);
+  const specRoot = path.join(root, 'specs');
   if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
     throw new Error('ERROR specs/: not found');
   }
@@ -163,7 +174,7 @@ function resolveRelated(repoPath, cwd = process.cwd()) {
   const errors = [];
 
   for (const filePath of walkMarkdown(specRoot)) {
-    const display = relativeDisplay(filePath, cwd);
+    const display = relativeDisplay(filePath, root);
     let parsed;
     try {
       parsed = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
@@ -317,7 +328,8 @@ function allRequirementIds(text) {
 function lint(cwd = process.cwd(), streams = {}) {
   const stdout = streams.stdout || process.stdout;
   const stderr = streams.stderr || process.stderr;
-  const specRoot = path.join(cwd, 'specs');
+  const root = path.resolve(cwd);
+  const specRoot = path.join(root, 'specs');
   if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
     write(stderr, 'ERROR specs/: not found');
     return 2;
@@ -332,15 +344,15 @@ function lint(cwd = process.cwd(), streams = {}) {
   const paths = walkMarkdown(specRoot);
 
   for (const filePath of paths) {
-    const display = relativeDisplay(filePath, cwd);
+    const display = relativeDisplay(filePath, root);
     let result;
     try {
       result = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
-      parsed.set(filePath, result);
     } catch (error) {
       errors.push([display, `invalid frontmatter: ${error.message}`]);
       continue;
     }
+    parsed.set(filePath, result);
 
     const frontmatter = result.frontmatter || {};
     const living = isLivingSpec(filePath, specRoot);
@@ -353,7 +365,7 @@ function lint(cwd = process.cwd(), streams = {}) {
       } else {
         const specId = rawSpecId.trim();
         if (ids.has(specId)) {
-          errors.push([display, `duplicate spec id ${specId} (also in ${relativeDisplay(ids.get(specId), cwd)})`]);
+          errors.push([display, `duplicate spec id ${specId} (also in ${relativeDisplay(ids.get(specId), root)})`]);
         } else {
           ids.set(specId, filePath);
         }
@@ -411,8 +423,8 @@ function lint(cwd = process.cwd(), streams = {}) {
       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)})`,
+          relativeDisplay(filePath, root),
+          `duplicate requirement id ${reqId} (also in ${relativeDisplay(first, root)})`,
         ]);
       }
     }
@@ -425,7 +437,7 @@ function lint(cwd = process.cwd(), streams = {}) {
   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 display = relativeDisplay(filePath, root);
     const { frontmatter: rawFrontmatter, body } = parsed.get(filePath);
     const frontmatter = rawFrontmatter || {};
     const sections = changeSections(stripHtmlComments(body));
@@ -534,7 +546,7 @@ function main(argv = process.argv.slice(2), cwd = process.cwd(), streams = {}) {
       return 0;
     }
     if (rest.length !== 1) return usageError('related requires exactly one path', streams);
-    return related(rest[0], path.resolve(cwd), streams);
+    return related(rest[0], resolveSpecRoot(cwd) || path.resolve(cwd), streams);
   }
   if (command === 'lint') {
     if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
@@ -542,7 +554,7 @@ function main(argv = process.argv.slice(2), cwd = process.cwd(), streams = {}) {
       return 0;
     }
     if (rest.length) return usageError('lint takes no arguments', streams);
-    return lint(path.resolve(cwd), streams);
+    return lint(resolveSpecRoot(cwd) || path.resolve(cwd), streams);
   }
   return usageError(`unknown command ${command}`, streams);
 }

package/lib/project.js

@@ -12,9 +12,11 @@ const CONFIG = 'specs/.charterleaf.json';
 
 function projectRoot(cwd) {
   const start = fs.realpathSync(cwd);
+  let legacyRoot;
   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;
+    if (fs.existsSync(path.join(current, '.git'))) return current;
+    if (!legacyRoot && fs.existsSync(path.join(current, CONFIG))) legacyRoot = current;
+    if (path.dirname(current) === current) return legacyRoot || start;
   }
 }
 
@@ -52,7 +54,7 @@ function toolPath(input) {
   return value;
 }
 
-function projectPath(root, cwd, input) {
+function absoluteToolPath(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)) {
@@ -61,35 +63,77 @@ function projectPath(root, cwd, input) {
     // A foreign UNC host cannot safely be interpreted as a local Linux path.
     return null;
   }
-  const lexical = path.resolve(cwd, value);
+  return path.resolve(cwd, value);
+}
+
+function projectPath(root, cwd, input) {
+  const lexical = absoluteToolPath(cwd, input);
+  if (!lexical) return null;
   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');
+function modeConfigPath(root) {
+  let directory = root;
+  let file = path.join(root, CONFIG);
+  if (fs.existsSync(path.join(root, '.git'))) {
+    const env = { ...process.env };
+    // Git hooks and wrappers may export another repository's location; it is not this project's authority.
+    for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE']) delete env[key];
+    directory = fs.realpathSync(execFileSync('git', ['-C', root, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'pipe'], env,
+    }).trim());
+    file = path.join(directory, 'charterleaf.json');
+  }
+  if (!inside(directory, canonical(file))) throw new Error('Charterleaf config escapes project storage');
+  return file;
+}
+
+function readConfig(file) {
   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)');
+  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');
+function readMode(root) {
+  const file = modeConfigPath(root);
+  if (fs.existsSync(file)) return readConfig(file);
+  const legacy = path.join(root, CONFIG);
+  if (file === legacy || !fs.existsSync(legacy)) return 'off';
+  if (!inside(root, canonical(legacy))) throw new Error('Charterleaf config escapes project');
+  // Preserve a prior explicit choice without changing tracked files or replacing a concurrent choice.
+  persistMode(file, readConfig(legacy), false);
+  return readConfig(file);
+}
+
+function persistMode(file, mode, replace) {
   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);
+    fs.writeFileSync(temporary, `${JSON.stringify({ version: 1, mode }, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    if (replace) fs.renameSync(temporary, file);
+    else {
+      try { fs.linkSync(temporary, file); }
+      catch (error) { if (error.code !== 'EEXIST') throw error; }
+    }
   } finally {
     if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
   }
 }
 
+function saveMode(root, mode) {
+  if (!MODES.includes(mode)) throw new Error('Invalid Charterleaf mode');
+  persistMode(modeConfigPath(root), mode, true);
+}
+
+function isModeConfig(root, cwd, input) {
+  const lexical = absoluteToolPath(cwd, input);
+  if (!lexical) return false;
+  const target = canonical(lexical);
+  return [path.join(root, CONFIG), modeConfigPath(root)].some((file) => target === canonical(file));
+}
+
 function fingerprint(root, relative) {
   const file = path.join(root, relative);
   if (!inside(root, canonical(file))) return 'outside';
@@ -110,7 +154,9 @@ function gitSnapshot(root) {
     encoding: 'utf8', timeout: 3000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
   });
   try {
-    if (fs.realpathSync(git(['rev-parse', '--show-toplevel']).trim()) !== root) return null;
+    // Windows Git may expand an 8.3 temp-directory alias to its long path.
+    root = fs.realpathSync.native(root);
+    if (fs.realpathSync.native(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);
@@ -139,4 +185,4 @@ function changedSince(before, after) {
     before.index?.get(name) !== after.index?.get(name)).sort();
 }
 
-module.exports = { CONFIG, MODES, projectRoot, projectPath, toolPath, readMode, saveMode, fingerprint, gitSnapshot, changedSince };
+module.exports = { CONFIG, MODES, projectRoot, projectPath, toolPath, modeConfigPath, isModeConfig, readMode, saveMode, fingerprint, gitSnapshot, changedSince };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onedotmint/charterleaf",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Lightweight Agent-Native Constraint Layer: opt-in spec discovery and maintenance for Pi, with a standalone zero-dependency CLI.",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,7 @@
   ],
   "scripts": {
     "test": "node --test",
+    "test:package": "node scripts/package-smoke.js",
     "test:pi": "node scripts/pi-smoke.js",
     "test:organic": "node scripts/organic-smoke.js",
     "test:context": "node scripts/context-smoke.js"

package/skills/charterleaf/SKILL.md

@@ -10,11 +10,17 @@ The essential rules live in [runtime.md](runtime.md); read it only if not alread
 
 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.
 
+## Mode scope
+
+The user chooses the mode only through `/charterleaf`. In Git, it is saved in `charterleaf.json` under `git rev-parse --path-format=absolute --git-common-dir` (usually `.git/charterleaf.json`), shared across the repository's branches and linked worktrees, not independent clones. Outside Git, keep using `specs/.charterleaf.json`. No saved choice means off, never a global Auto default.
+
+An existing local config is authoritative, including saved `off`; branch-local legacy config cannot override it. Only if local config is absent, first load imports the saved mode from a valid current-branch legacy `specs/.charterleaf.json` without overwriting local config or changing/removing the legacy file or tracked worktree. Invalid config must report an error and disable automation, not fall back. Never recover lost authorization from Git history or sessions. Enabling a Git project creates neither `specs/` nor spec documents; spec content and routing remain in the current worktree. The two CLI commands are unchanged and independent of mode storage.
+
 ## Ownership and durable writing
 
 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.
 
-Capture during ordinary development, debugging, code/test/architecture investigation or technical decisions; do not wait for settlement or require existing specs. An enabled project containing only `specs/.charterleaf.json` is a valid starting state, not a bootstrap request.
+Capture during ordinary development, debugging, code/test/architecture investigation or technical decisions; do not wait for settlement or require existing specs. An enabled project with no spec documents (or no `specs/` directory in Git) is a valid starting state, not a bootstrap request; normal code reads/edits and later justified spec creation remain allowed under the selected mode.
 
 Distinguish **newly established knowledge** (an accepted new contract/decision) from **newly discovered knowledge** (an existing but ineffectively documented constraint). Either can qualify without code changes; neither obliges every task to produce a document. Apply all three checks:
 
@@ -55,7 +61,9 @@ Use `specs/changes/<name>.md` only when an accepted future contract must coexist
 
 ## CLI details
 
-Run from the project root:
+Run from the project root or a subdirectory. CLI discovery stops at the nearest
+`specs/` directory or Git repository/worktree boundary; target paths stay
+repo-relative:
 
 - `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.