@onedotmint/charterleaf 0.4.0 → 0.4.2

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:
 
@@ -28,7 +39,12 @@ 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
+writer. During normal development or investigation, capture newly established
+or newly discovered knowledge only with reliable evidence, long-term value and a
+documentation/discoverability gap; no code change or prior spec is required.
+Prefer short scoped references to authoritative owners over copying documents.
+Explicit no-file-write/read-only instructions override Auto. No justified durable
+knowledge 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

@@ -36,10 +36,10 @@ Install once in Pi to discover the bundled Extension and Skill:
 pi install npm:@onedotmint/charterleaf
 ```
 
-**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`.
+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.2.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.
@@ -128,18 +148,56 @@ 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.
 
+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. 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.
+
 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
+**at most one final semantic review per task**. Actual development remains a
+fallback, but an unresolved evidenced knowledge candidate can also trigger it
+without file changes or Git. The existing Agent makes the semantic judgment; the
+Extension observes standalone assistant lifecycle comments outside fenced examples
+(`charterleaf: review` or an explicit `covered`/`no-value`/`proposed` knowledge
+conclusion; an exact terminal conclusion also works inline), never interprets read
+counts as knowledge. A generic `done` cannot suppress the development fallback.
+In an empty-spec project, a development fallback
+remains eligible when the Agent says `no-value`; this gives the existing single
+review a chance to catch a missed discovery gap. These are
+cooperative intent signals, not evidence or permissions. Already judged/captured,
+proposed or effectively documented knowledge needs no repeat review when a
+completion signal is observed. If the Agent
+omits its completion signal, the bounded fallback can repeat an already answered
+knowledge judgment; zero redundant reviews is not guaranteed. Successful
+structurally valid standard spec writes mark capture complete; later actual code
+edits or distinct candidates may rearm. Opaque activity after capture still uses
+bounded Git comparison when available. Ordinary views, queries and chat do not
+by themselves request another model call.
+
+For the development fallback, the Extension 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
+**No justified durable knowledge means no spec edit.** Distinguish **newly
+established** contracts/decisions from **newly discovered** existing constraints;
+both can qualify even in a code-read-only investigation. Require reliable evidence
+(accepted decisions, authoritative docs, tests or sufficiently verified behavior),
+future mistake-prevention value, and a documentation/discoverability gap. If an
+existing authoritative document covers it, prefer a short routed reference when
+needed; otherwise do nothing. Keep non-obvious contracts, invariants, boundaries,
+pitfalls or accepted decisions — not code summaries, progress, debugging logs,
+temporary plans/todos or speculation. Current code alone is not an accepted
+correct contract. Explicit **no-file-write/read-only** instructions override Auto:
+report a finding/proposal without writing. Confirm/Reference retain their existing
+permissions. 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
@@ -256,7 +314,8 @@ specs/
 
 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,
+durable, **already true or explicitly accepted**, evidenced, mistake-preventing,
+and not already effectively documented. Good fits: contracts,
 invariants, architecture boundaries, non-goals, recurring pitfalls,
 accepted rationale, verification constraints.
 
@@ -274,8 +333,8 @@ 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
+Otherwise, implement/verify as needed and maintain the living spec when durable
+truth changed **or an existing valuable constraint lacks effective documentation**. After an accepted change is implemented, merge the durable
 result into living specs and delete the change file. Git keeps history.
 
 ## Agent conventions
@@ -325,7 +384,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
@@ -348,34 +408,73 @@ Verification commands:
 
 ```bash
 npm test
-npm run test:pi   # requires compatible Pi on PATH; isolated RPC UI smoke, no model calls
+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
+node scripts/organic-smoke.js --self-test  # harness/oracle check, 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.
+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.
+
+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,
+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 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. 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.
+
+The controlled organic-capture comparison (`scripts/context-smoke.js`) keeps cwd,
+package paths, prompt and native tools identical. On `deepseek/deepseek-flash`:
+disabled 1,616 input tokens; v0.4.0 baseline 2,036 (increment 420); organic runtime
+2,142 (increment 526), or **106 additional fixed input tokens**. Input here includes
+cached input. Each chat made exactly one request and no tool calls; the full Skill
+remains on demand. Absolute path tokenization and provider tokenizers vary, and
+cache-hit sizes affect uncached charges, so these are measured examples, not fixed
+billing guarantees. The script defaults to `HEAD`; set `CHARTERLEAF_BASELINE` to the
+older revision being compared (the command above uses the v0.4.0 release commit).
+Substantive work requests **zero or at most one** extra model review: observed
+capture/coverage/proposal completion skips the fallback; empty-spec development can
+still get the one fallback after a `no-value` judgment.
+
+The real-model acceptance script retains raw RPC/JSONL, conversations, actual tool
+records, before/after files, tracked/untracked diffs, validation output and individual
+assertions in the printed private temporary directory, including failures. It copies
+credentials only to isolated settings and removes that copy on normal/error
+completion; a forced process kill may require deleting the private credential
+copy manually. It does not
+import personal extensions/instructions or modify other repositories, and it is not
+an OS security sandbox. Both paid scripts require explicit `CHARTERLEAF_MODEL=provider/id`; neither chooses
+another provider automatically. The requested model must be available;
+`--case A,B,...` selects bounded scenarios. F cases run A first, then B only if A failed to capture; they reuse only
+model-written knowledge in the same project across fresh sessions. A's failure
+remains a failed assertion; a successful B→F chain does not conceal it. Model usage counts visible assistant responses, not hidden
+provider HTTP retries. Cost fixtures also remove copied credentials on exit.
 
 For an interactive smoke check in a disposable project, install the local
 package in a compatible Pi host and run `/charterleaf`: check immediate

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 });
 
@@ -26,14 +32,20 @@ module.exports = function charterleaf(pi) {
     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,
+      owned: new Map(), parents: new Map(), envelopes: new Map(), before: gitSnapshot(root), budget: 24000, reviewed: false, miss: false, opaque: false, knowledge: undefined,
     };
     state.mode = mode;
     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]) {
@@ -68,12 +80,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 +130,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}`); }
     },
   });
@@ -148,6 +177,23 @@ module.exports = function charterleaf(pi) {
     } };
   });
 
+  // Semantic intent comes from the existing agent, never from file/read counts.
+  pi.on('message_end', (event, ctx) => {
+    if (event.message.role !== 'assistant' || ['error', 'aborted'].includes(event.message.stopReason)) return;
+    let s;
+    try { s = current(ctx); } catch { return; }
+    if (!s) return;
+    const text = event.message.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+    const prose = text.replace(/```[\s\S]*?(?:```|$)|~~~[\s\S]*?(?:~~~|$)/g, '');
+    const signal = prose.match(/<!-- charterleaf: (covered|no-value|proposed) -->\s*$/) ||
+      [...prose.matchAll(/^<!-- charterleaf: (review|covered|no-value|proposed) -->[ \t]*$/gm)].at(-1);
+    if (signal) {
+      if (signal[1] === 'proposed' && s.mode === 'confirm' && !s.proposed) return;
+      s.knowledge = signal[1];
+      if (s.knowledge !== 'review') { s.capture = gitSnapshot(s.root); s.opaque = false; }
+    }
+  });
+
   // 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;
@@ -163,6 +209,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;
@@ -175,19 +224,17 @@ 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') {
+          s.proposed = true;
           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 });
+            `Approve this exact ${event.toolName} only if the evidenced durable knowledge maintenance 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.' };
@@ -223,7 +270,12 @@ module.exports = function charterleaf(pi) {
     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; }
+        try {
+          if (fingerprint(s.root, call.file) !== call.before) {
+            s.opaque = true;
+            if (s.knowledge !== 'review') s.knowledge = undefined;
+          }
+        } catch { s.opaque = true; s.knowledge = undefined; }
       }
       if (envelope) return { content: [...event.content, { type: 'text', text: `[Charterleaf]\n${envelope}` }] };
       return;
@@ -233,18 +285,24 @@ module.exports = function charterleaf(pi) {
       if (call) {
         const hash = fingerprint(s.root, call.file);
         if (call.mutation && hash !== call.before) {
+          if (s.knowledge !== 'review') s.knowledge = undefined;
           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 });
+            if (lint(s.root, { stdout: stream, stderr: stream }) === 0) {
+              s.knowledge = 'captured';
+              s.capture = gitSnapshot(s.root);
+              s.opaque = false;
+            }
             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 &&
+            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' &&
@@ -278,30 +336,43 @@ module.exports = function charterleaf(pi) {
     if (!s || s.reviewed || event.outcome !== 'completed') return;
     s.reviewed = true;
     try {
-      if (!s.owned.size && !s.opaque) return;
+      if (['captured', 'covered', 'proposed'].includes(s.knowledge)) {
+        if (!s.opaque) return;
+        const afterCapture = gitSnapshot(s.root);
+        if (s.capture && afterCapture && !changedSince(s.capture, afterCapture).some((file) => !isSpec(file))) return;
+      }
+      if (!['review', 'no-value'].includes(s.knowledge) && !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 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` +
+        (candidate ? 'The agent identified unresolved durable knowledge in this task; file changes are not required. Judge the conversation evidence, not the signal itself.\n' : '') +
+        (emptySpecs ? 'Development in an empty-spec project: verify the no-value conclusion against evidence of existing undocumented constraints, not just newly changed contracts.\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. ' +
+        'Consider newly established AND newly discovered knowledge, including read-only investigation or accepted decisions; no code change is required. In an empty-spec project, tests or accepted behavior that reveal a non-obvious invariant without effective code-path guidance is a discovery gap; do not dismiss it merely because tests pass or the implementation already works. ' +
+        'No justified durable knowledge means no spec edit; no code summary, task log or plans. ' +
+        'Record only evidenced, non-obvious contracts, invariants, boundaries, pitfalls or accepted decisions whose absence risks future mistakes and which are not effectively documented. ' +
+        'Current code alone is not an accepted contract. Prefer a short routed reference to an authoritative document over copying it; do not duplicate knowledge already captured in this task. ' +
+        'Honor explicit no-file-write/read-only instructions even in Auto; report only. ' +
         '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. ' :
+          s.mode === 'confirm' ? 'Confirm: invoke the exact spec write/edit to open the Extension approval dialog; 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.';

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.0",
+  "version": "0.4.2",
   "description": "Lightweight Agent-Native Constraint Layer: opt-in spec discovery and maintenance for Pi, with a standalone zero-dependency CLI.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,10 @@
   ],
   "scripts": {
     "test": "node --test",
-    "test:pi": "node scripts/pi-smoke.js"
+    "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"
   },
   "pi": {
     "extensions": [

package/skills/charterleaf/SKILL.md

@@ -10,18 +10,50 @@ 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.
 
-Place only established, non-obvious knowledge whose absence could cause a future mistake:
+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:
+
+1. Reliable evidence: accepted user intent, authoritative documentation, tests or sufficiently verified implementation behavior. Current code alone does not establish an accepted correct contract.
+2. Long-term value: ignoring it could plausibly cause a future developer/Agent to make a wrong decision.
+3. A documentation or discoverability gap: inspect relevant existing owners/specs before writing. If an authoritative document already covers it, add only a short scoped reference when routing is genuinely missing; otherwise do nothing. Never duplicate a captured rule. Executable tests provide evidence, not automatically effective code-path discovery: accepted non-obvious invariants scattered among tests may warrant a short scoped constraint/reference even when no new contract was established. Do not copy test cases or document trivial assertions; judge whether a future code change could miss the boundary.
+
+Honor explicit no-file-write/read-only restrictions in every mode. Otherwise **code edits are allowed normally in all three modes**, including Reference and Confirm. Auto can create or update specs immediately when justified; Confirm uses the existing exact-spec-write approval; Reference only proposes spec changes, never restricts implementation edits. **In Confirm, invoke standard `write`/`edit` with the exact spec proposal to open the Extension's approval dialog; do not merely ask for prose permission and stop.** The call is an approval request, not an unauthorized mutation: the Extension pauses it before execution, denies it without UI, and only executes the exact operation if approved. If evidence conflicts, verify authority and distinguish a bug from an accepted change, never rewrite truth to match suspect code.
+
+Place qualifying non-obvious knowledge in:
 
 - `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.
 
-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.
+Living capability/engineering specs need a unique `id` and non-empty `applies_to` list, including the first organically created spec. For example:
+
+```markdown
+---
+id: engineering.amounts
+applies_to:
+  - src/amounts.js
+  - tests/amounts.test.js
+---
+# Amount boundary
+
+Preserve the accepted rounding contract; see [accounting policy](../../docs/accounting.md#rounding) and its executable cases in `tests/amounts.test.js`.
+```
+
+Use this shape, not this example's rule, for the actual project evidence. Route rationale in `decisions/` through a relevant capability/engineering reference when automatic code-path discovery is needed. 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. Task progress, implementation inventories, one-off debugging, temporary plans/todos and unverified behavior never belong in Specs.
+
+The runtime's standalone assistant comments (outside code fences; exact terminal completion comments also work inline) `<!-- charterleaf: review -->`, `<!-- charterleaf: covered -->`, `<!-- charterleaf: no-value -->` and `<!-- charterleaf: proposed -->` are task-local lifecycle signals, not spec contents, evidence or permissions. `review` means a concrete evidenced candidate still needs knowledge judgment; `covered` means relevant authority is already effectively discoverable; `no-value` means the evidence/value/gap checks found no qualifying knowledge; `proposed` means a Reference/read-only proposal was reported or a Confirm proposal passed through the gate and was refused/no UI. Use these exact comments; put explanation outside, never inside them. If an explicit no-write task surfaced a qualified constraint, report the finding/proposal in the normal answer and finish the knowledge judgment there rather than requesting a continuation just to repeat it. Ordinary code/test completion is not any of those conclusions: a generic `done` comment is deliberately ignored. Never use `covered` merely because tests exercise a boundary without effective code-path discovery. In an enabled empty-spec project, do not reject a non-obvious accepted invariant merely because the tests already exercise it. Waiting for human approval is not unresolved knowledge judgment: do not request a semantic continuation just to ask the same permission again. After submitting an exact proposal to the approval gate, handle approval/refusal/no UI and finish normally. New distinct findings may rearm, but the Extension continues at most once. Successful structurally valid standard spec writes also mark capture complete; later code edits rearm the development fallback. In an empty-spec project, owned development after `no-value` still permits the single fallback to check for missed discovery gaps. Omitting a recognized conclusion can cause a redundant fallback even when the normal answer already states that nothing needs documenting. Plain reads, file counts, search results and task wording are not semantic discovery signals.
 
 ## Optional staged changes
 

package/skills/charterleaf/runtime.md

@@ -1,11 +1,15 @@
 # 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.
+Use supplied specs; no bulk/unchanged rereads. Blocked write/edit: inspect constraints/read the complete spec, then retry; never bypass via another writer. Routing: a hint.
 
-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.
+Modes govern specs, not code: Auto maintains justified knowledge; Confirm calls spec write/edit to open Extension approval (refusal/no UI: preserve, no retry); Reference proposes, never writes specs. All modes allow normal code edits. Use standard write/edit only. User-owned config. read-only/no-file-write requests override Auto. 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.
+Internal/refactor requests do not authorize changing return or ownership contracts. Conflicts: verify authority, fix bugs; never relax specs to match code. Invariant-breaking method? Preserve spec/tests; get an explicit contract decision before coding. Uncertain: preserve and report. Preserve user/parallel work; Git dirt/touched files aren't line ownership. No automatic revert/commit/push.
+
+## Organic knowledge capture
+
+During development/debugging/investigation/decisions capture newly established OR newly discovered knowledge, even without code changes/prior specs. Need reliable evidence (accepted decisions, authoritative docs, tests or verified behavior), mistake-prevention value and a documentation/discoverability gap. Code alone is not an accepted contract. Check owners; tests aren't automatic code-path routing; prefer short routed references over copying docs. New capability/engineering specs: unique id, narrow applies_to; see guide. No justified knowledge: no spec. No code summaries/progress/logs/plans/todos/speculation.
 
 ## 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.
+Judge during work, not by read counts. Use one exact comment: <!-- charterleaf: review --> (evidenced pending), <!-- charterleaf: covered --> (effective authority), <!-- charterleaf: no-value --> (no value), <!-- charterleaf: proposed --> (Reference/refused Confirm/read-only report). Reasons outside, never inside comments. NOT merely finishing code/tests. Signals aren't evidence/permission. At most one extra review; no loop. Report results/tests, not review logs. Lint is structural only.