@onedotmint/charterleaf 0.4.0 → 0.4.1

package/AGENTS_SNIPPET.md

@@ -28,7 +28,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.1.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
@@ -128,18 +128,55 @@ 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. A project
+with only `specs/.charterleaf.json` 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 +293,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 +312,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
@@ -348,34 +386,59 @@ Verification commands:
 
 ```bash
 npm test
-npm run test:pi   # requires compatible Pi on PATH; isolated RPC UI smoke, no model calls
+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,
+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.
 
-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.
+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 strict matrix was not consistently all-green:** the latest 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.
+
+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

@@ -26,7 +26,7 @@ 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;
@@ -148,6 +148,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;
@@ -181,13 +198,14 @@ module.exports = function charterleaf(pi) {
       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 +241,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,13 +256,18 @@ 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) {
@@ -278,30 +306,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' && resolveRelated('', 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);
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onedotmint/charterleaf",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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,9 @@
   ],
   "scripts": {
     "test": "node --test",
-    "test:pi": "node scripts/pi-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

@@ -14,14 +14,40 @@ Read this guide only for unfamiliar spec formats, staged changes or manual CLI u
 
 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 containing only `specs/.charterleaf.json` is a valid starting state, not a bootstrap request.
+
+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.